diff --git a/.github/workflows/benchmark_dispatch.yml b/.github/workflows/benchmark_dispatch.yml new file mode 100644 index 000000000..e6e223e17 --- /dev/null +++ b/.github/workflows/benchmark_dispatch.yml @@ -0,0 +1,122 @@ +# Tell openswmm.engine.benchmarks that this engine moved, so it can build THIS +# commit and sweep the model corpus against it. +# +# Why a dispatch rather than a job here: the benchmark platform owns the corpus, +# the engine registry, the scoring taxonomy and its own Pages site. Keeping the +# sweep there means this repository needs only permission to say "a new commit +# exists" -- it never needs a Pages credential, and the corpus never has to be +# vendored into this tree. +# +# Gated on Unit Testing succeeding. A sweep is a multi-hour, multi-runner job; +# dispatching a commit that does not build wastes it and buries the real signal +# under a matrix of ERROR cells. +name: Benchmark dispatch + +on: + workflow_run: + workflows: ["Unit Testing"] + types: [completed] + branches: [main, develop] + workflow_dispatch: + inputs: + sha: + description: Engine commit to benchmark (blank = this branch's HEAD) + required: false + +permissions: + contents: read + +env: + BENCHMARKS_REPO: HydroCouple/openswmm.engine.benchmarks + +jobs: + dispatch: + name: Notify the benchmark platform + # workflow_run fires on completion regardless of outcome, so filter to the + # successful PUSH runs. Pull-request runs are excluded deliberately: a fork + # PR cannot read secrets, and a sweep per PR would cost more than it tells + # us until the PR tier is curated. + if: >- + github.event_name == 'workflow_dispatch' || + (github.event.workflow_run.conclusion == 'success' && + github.event.workflow_run.event == 'push') + runs-on: ubuntu-latest + steps: + - name: Resolve the commit to benchmark + id: target + env: + RUN_SHA: ${{ github.event.workflow_run.head_sha }} + RUN_REF: ${{ github.event.workflow_run.head_branch }} + INPUT_SHA: ${{ inputs.sha }} + run: | + set -euo pipefail + sha="${INPUT_SHA:-${RUN_SHA:-${GITHUB_SHA}}}" + ref="${RUN_REF:-${GITHUB_REF_NAME}}" + # A blank sha would make the receiver silently check out its default + # branch and publish results keyed to the wrong commit. + if [ -z "$sha" ]; then + echo "::error::could not resolve an engine SHA to dispatch" + exit 1 + fi + echo "sha=$sha" >> "$GITHUB_OUTPUT" + echo "ref=$ref" >> "$GITHUB_OUTPUT" + echo "Dispatching $ref @ $sha to $BENCHMARKS_REPO" + + - name: Check the dispatch token is configured + env: + TOKEN: ${{ secrets.BENCHMARKS_DISPATCH_TOKEN }} + run: | + if [ -n "${TOKEN:-}" ]; then exit 0; fi + cat >&2 <<'MSG' + The secret BENCHMARKS_DISPATCH_TOKEN is not set on this repository. + + Cross-repository repository_dispatch cannot use the default + GITHUB_TOKEN -- it is scoped to this repository only -- so a separate + credential is required. + + To configure: + 1. Create a token that may POST to + HydroCouple/openswmm.engine.benchmarks: + * fine-grained PAT -> Repository access: that repo, + Permissions: Contents = Read and write + * classic PAT -> scope: repo + (A GitHub App installation token works too, and is preferable + for a shared org: it is not tied to one person's account.) + 2. Add it here as an Actions secret named + BENCHMARKS_DISPATCH_TOKEN. + + Until then the benchmark platform picks this engine up only via its + own nightly cron (07:00 UTC, building `develop`), not per push. + MSG + echo "::error::BENCHMARKS_DISPATCH_TOKEN is not configured -- see the log above" + exit 1 + + - name: Dispatch to openswmm.engine.benchmarks + env: + TOKEN: ${{ secrets.BENCHMARKS_DISPATCH_TOKEN }} + SHA: ${{ steps.target.outputs.sha }} + REF: ${{ steps.target.outputs.ref }} + run: | + set -euo pipefail + # Built with jq, not string interpolation: a branch name is + # attacker-influenced text and must not be able to break out of the + # JSON body. + payload=$(jq -n \ + --arg sha "$SHA" \ + --arg ref "$REF" \ + --arg repo "$GITHUB_REPOSITORY" \ + --arg run_url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/${{ github.event.workflow_run.id || github.run_id }}" \ + '{event_type: "engine-push", + client_payload: {sha: $sha, ref: $ref, repo: $repo, run_url: $run_url}}') + + curl --fail-with-body -sS -X POST \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer $TOKEN" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + "$GITHUB_API_URL/repos/$BENCHMARKS_REPO/dispatches" \ + -d "$payload" + + echo "Dispatched $REF @ $SHA" + echo "### Benchmark sweep dispatched" >> "$GITHUB_STEP_SUMMARY" + echo "" >> "$GITHUB_STEP_SUMMARY" + echo "\`$REF\` @ \`$SHA\` -> [$BENCHMARKS_REPO]($GITHUB_SERVER_URL/$BENCHMARKS_REPO/actions)" >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index f5d0b95da..61dd12534 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,5 +1,8 @@ name: CodeQL +permissions: + contents: read + on: push: branches: [main] # drop develop — covered by PR @@ -52,7 +55,7 @@ jobs: uses: actions/checkout@v5 with: repository: microsoft/vcpkg - ref: 2025.02.14 + ref: 2026.07.29 path: vcpkg - name: Install Ninja diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml index 05e01d1fa..9a8d4add1 100644 --- a/.github/workflows/deployment.yml +++ b/.github/workflows/deployment.yml @@ -1,5 +1,8 @@ name: Deployment +permissions: + contents: read + on: push: branches: [main] @@ -14,7 +17,7 @@ env: OMP_NUM_THREADS: 1 # Single source of truth for the vcpkg ref (used by every checkout + the # in-container clone in pyproject's linux before-all via environment-pass). - VCPKG_REF: "2025.02.14" + VCPKG_REF: "2026.07.29" # macOS minimum target. Set globally so the engine build job AND vcpkg's # dependency builds (SUNDIALS/HDF5/sqlite3) compile at this floor; ignored on # Linux/Windows. The Python wheels set the same value via cibuildwheel @@ -23,6 +26,9 @@ env: MACOSX_DEPLOYMENT_TARGET: "11.0" jobs: + python-contracts: + uses: ./.github/workflows/python_contracts.yml + # ────────────────────────────────────────────────────────────────────── # Build release binaries # ────────────────────────────────────────────────────────────────────── @@ -30,7 +36,6 @@ jobs: name: "Build (${{ matrix.alias }})" permissions: contents: read - actions: write # x-gha vcpkg binary cache + actions/cache strategy: fail-fast: false matrix: @@ -131,6 +136,15 @@ jobs: with: arch: amd64 + - name: Re-pin VCPKG_ROOT (Windows) + # vcvars64 (VS 2022 17.6+) exports VCPKG_ROOT pointing at Visual + # Studio's bundled vcpkg, and msvc-dev-cmd forwards it to every later + # step, overriding the job-level env — so configure would silently + # build against VS's port snapshot instead of the pinned checkout. + if: runner.os == 'Windows' + shell: pwsh + run: echo "VCPKG_ROOT=${{ github.workspace }}\vcpkg" >> $env:GITHUB_ENV + - name: Configure (Release) # Release packaging skips the test/benchmark targets so vcpkg pulls only # the runtime deps. Kokkos + hypre/AMG are vcpkg/CMake defaults, but @@ -215,7 +229,6 @@ jobs: # not block all wheels. (Previously `needs: build` coupled them.) permissions: contents: read - actions: write strategy: fail-fast: false matrix: @@ -299,7 +312,6 @@ jobs: name: "GPU-omp wheels (${{ matrix.os }})" permissions: contents: read - actions: write strategy: fail-fast: false matrix: @@ -426,7 +438,7 @@ jobs: # numpy (the base wheel's only runtime dep) is pulled from PyPI as a wheel. "$PY" -m pip install --only-binary :all: numpy # The project wheels MUST come from the local wheelhouse, never PyPI. - # openswmm / openswmm-gpu-omp are pre-releases (6.0.0a3), and a *stable* + # openswmm / openswmm-gpu-omp are pre-releases (for example, 6.0.0a4.dev1), and a *stable* # openswmm-gpu-omp 0.0.0 placeholder exists on PyPI; without --no-index pip # prefers that stable stub over our local pre-release and installs an empty # package (ModuleNotFoundError: openswmm_gpu_omp). --no-index also makes a @@ -434,9 +446,14 @@ jobs: # resolving to PyPI. "$PY" -m pip install --only-binary :all: --no-index --find-links wheelhouse openswmm openswmm-gpu-omp "$PY" -m pip show openswmm | tee wheel-smoke-${{ matrix.os }}.txt - # gpu-omp companion must import AND be auto-discovered by base openswmm - # (import openswmm runs _register_gpu_companion → OPENSWMM_GPU_PLUGIN_PATH). - "$PY" -c "import os,openswmm,openswmm_gpu_omp as g; p=os.environ.get('OPENSWMM_GPU_PLUGIN_PATH'); assert p, 'gpu-omp plugin not discovered'; print('OPENSWMM_GPU_PLUGIN_PATH='+p); print('companion at '+g.__file__)" | tee -a wheel-smoke-${{ matrix.os }}.txt + # A plugin must be auto-discovered on `import openswmm` + # (_register_gpu_plugin → OPENSWMM_GPU_PLUGIN_PATH), the companion must + # import, and the discovered directory must actually CONTAIN a built + # plugin binary — a non-empty env var alone would pass even if the + # OpenMP build had silently produced nothing. The base wheel now ships + # the plugin too, so the discovered dir is normally openswmm/engine; + # the shim prefers it and skips the companion (one OpenMP runtime). + "$PY" -c "import os,glob,openswmm,openswmm_gpu_omp as g; p=os.environ.get('OPENSWMM_GPU_PLUGIN_PATH'); assert p, 'no gpu plugin discovered'; d=p.split(os.pathsep)[0]; hits=[f for f in glob.glob(os.path.join(d,'*openswmm_gpu_*')) if f.endswith(('.so','.dylib','.dll'))]; assert hits, 'discovered dir has no plugin binary: '+d; print('OPENSWMM_GPU_PLUGIN_PATH='+p); print('plugin: '+hits[0]); print('companion at '+g.__file__)" | tee -a wheel-smoke-${{ matrix.os }}.txt # Run the example model end-to-end via the shared smoke script. "$PY" python/smoke_test.py 2>&1 | tee -a wheel-smoke-${{ matrix.os }}.txt @@ -463,7 +480,9 @@ jobs: python-version: "3.13" - name: Check version sync (CMake / vcpkg / pyproject) - run: python scripts/check_version_sync.py + run: | + python -m unittest discover -s scripts -p test_version_sync.py + python scripts/check_version_sync.py - name: Install build frontend run: | @@ -494,7 +513,6 @@ jobs: name: "C++ unit tests (release gate)" permissions: contents: read - actions: write runs-on: ubuntu-latest steps: - name: Checkout repository @@ -544,7 +562,7 @@ jobs: release: name: Create GitHub Release if: startsWith(github.ref, 'refs/tags/v') - needs: [build, test, wheels, gpu-omp-wheels, sdist, wheel-smoke] + needs: [build, test, wheels, gpu-omp-wheels, sdist, wheel-smoke, python-contracts] runs-on: ubuntu-latest permissions: contents: write diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 7bc9a7113..ce4aa3d52 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -1,15 +1,25 @@ name: Documentation +permissions: + contents: read + on: push: # branches: [main, develop] branches: [main, develop, swmm6_rel] tags: ["v*.*.*"] - paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md'] + # src/engine is in the filter because the manual lint checks the manuals + # against the parser (registered [SECTION]s, error codes): registering a + # section without documenting it must trip the gate. + paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md', + 'src/engine/**', 'scripts/lint_manual_docs*.py', + 'scripts/gen_manual_frontmatter.py', 'scripts/build_manual_figures.py'] pull_request: - branches: [main, develop] + branches: [main, develop, swmm6_rel] # branches: [main] - paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md'] + paths: ['docs/**', 'python/docs/**', 'python/openswmm/**', 'include/**', '**/*.md', + 'src/engine/**', 'scripts/lint_manual_docs*.py', + 'scripts/gen_manual_frontmatter.py', 'scripts/build_manual_figures.py'] workflow_dispatch: # Allow only one concurrent deployment. Do NOT cancel in-progress runs so @@ -19,9 +29,42 @@ concurrency: cancel-in-progress: false # ───────────────────────────────────────────────────────────────────────────── -# Job 1 – Build Python (Sphinx) documentation +# Job 0 – Lint the manual sources +# Referential integrity, tables, math delimiters, images, [SECTION] and +# error-code coverage, status badges, Mermaid blocks. Runs the negative +# suite too, so a check that silently stopped failing is caught here. +# Doxygen runs with WARN_AS_ERROR = NO (header warnings would drown it), so +# this job is what actually fails the build on a broken manual. # ───────────────────────────────────────────────────────────────────────────── jobs: + lint_manual_docs: + name: Lint Manual Sources + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + - name: Lint the manuals + run: python3 scripts/lint_manual_docs.py + + - name: Prove every lint check can fail + run: python3 scripts/lint_manual_docs_negative.py + + - name: Upload negative-test artifacts + if: always() + uses: actions/upload-artifact@v5 + with: + name: docs-lint-negative + path: tests/output/docs_lint_negative_*/*.log + if-no-files-found: ignore + retention-days: 7 + +# ───────────────────────────────────────────────────────────────────────────── +# Job 1 – Build Python (Sphinx) documentation +# ───────────────────────────────────────────────────────────────────────────── build_python_docs: name: Build Python Bindings Docs (Sphinx) runs-on: ubuntu-latest @@ -67,7 +110,7 @@ jobs: # ───────────────────────────────────────────────────────────────────────────── build_doxygen_docs: name: Build C/C++ Engine Docs (Doxygen) - needs: build_python_docs + needs: [lint_manual_docs, build_python_docs] runs-on: ubuntu-latest permissions: contents: read @@ -93,9 +136,61 @@ jobs: sudo mv doxygen-${DOXYGEN_VERSION}/bin/doxygen /usr/local/bin/doxygen doxygen --version + - name: Set up Python 3.12 (figure pipeline) + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install figure-pipeline dependencies + run: pip install "matplotlib>=3.8" numpy + + - name: Prove the synthetic figure generators run + # The committed PNGs are what gets published and were audited by the + # lint job (every embed has a manifest row, every row's file exists, + # bounds, no basename collisions). This renders the synthetic tier into + # a scratch directory to prove each generator still executes — never a + # pixel comparison. Generators that need the compiled openswmm package + # are skipped and listed. + run: python3 scripts/build_manual_figures.py build --tier synthetic --out /tmp/figcheck --skip-missing-deps + + - name: Check the GUI tagfile for drift (advisory) + # docs/tags/swmmvis-manual.tag is committed so the build never depends + # on the GUI Pages site being reachable. This only reports staleness — + # it must not fail the build, and it skips silently when offline. + continue-on-error: true + run: | + python3 scripts/refresh_gui_tagfile.py --check \ + || echo "::warning::docs/tags/swmmvis-manual.tag is stale; run scripts/refresh_gui_tagfile.py" + - name: Build Doxygen HTML docs + # docs/CNAME pins the Pages custom domain. It must sit at the ROOT of + # the published site, which is the Doxygen output — the Python docs + # land under /python and would put it one level too deep. working-directory: docs - run: doxygen Doxyfile + run: | + doxygen Doxyfile 2>&1 | tee doxygen.log + cp CNAME html/ + + - name: Fail on manual-scoped Doxygen problems + # WARN_AS_ERROR stays NO (the C++ headers carry ~1,200 warnings), so + # the gate is scoped: a missing image/input path, a page label declared + # twice (which silently re-points every @ref at the wrong page), a + # dangling @ref into any manual or the GUI tagfile, and a \snippet + # whose marker pair is broken. Each pattern has been seen to fire. + working-directory: docs + run: | + set -euo pipefail + fail=0 + for pat in 'does not exist or is not a file' \ + 'multiple use of page label' \ + "unable to resolve reference to '(application_manual|engine_manual|hydraulics_ref|hydrology_ref|quality_ref|manual_|tutorial_)" \ + 'should appear twice|included file .* is not found'; do + if grep -E "$pat" doxygen.log; then + echo "::error::doxygen.log matches '$pat'" + fail=1 + fi + done + exit $fail - name: Upload Doxygen docs artifact uses: actions/upload-artifact@v5 diff --git a/.github/workflows/python_contracts.yml b/.github/workflows/python_contracts.yml new file mode 100644 index 000000000..a542c8d66 --- /dev/null +++ b/.github/workflows/python_contracts.yml @@ -0,0 +1,55 @@ +name: Python API contracts + +permissions: + contents: read + +on: + workflow_call: + workflow_dispatch: + push: + branches: [main, develop, swmm6_rel] + pull_request: + branches: [main, develop, swmm6_rel] + +jobs: + contracts: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python -m pip install pytest + - name: Check native API reachability + run: python python/scripts/api_drift_audit.py --strict + - name: Check enums, stubs and Cython attributes + working-directory: python + run: python -m pytest tests/test_api_coverage.py tests/test_enum_drift.py tests/test_solver_pxd_attrs.py -q + + minimal-build: + name: Python without optional features + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python -m pip install 'cmake>=4.3' ninja 'Cython>=3.0.12' numpy pytest + - name: Configure minimal bindings + run: >- + cmake -S python -B build/python-minimal -G Ninja + -DCMAKE_BUILD_TYPE=Release + -DOPENSWMM_BUILD_2D=OFF + -DOPENSWMM_BUILD_GPU_PLUGIN=OFF + -DOPENSWMM_WITH_GEOPACKAGE=OFF + -DOPENSWMM_WITH_HDF5=OFF + -DPython_EXECUTABLE=$(which python) + - run: cmake --build build/python-minimal --parallel 2 + - run: cmake --install build/python-minimal --prefix "${{ runner.temp }}/openswmm-minimal" + - name: Stage Python sources + run: python python/scripts/stage_python_sources.py "${{ runner.temp }}/openswmm-minimal" + - name: Exercise omitted-feature imports and core solver + run: >- + python python/scripts/test_staged_package.py "${{ runner.temp }}/openswmm-minimal" + python/tests/minimal_features.py python/tests/engine/test_solver_pythonic.py + python/tests/engine/test_transport.py -q diff --git a/.github/workflows/regression_testing.yml b/.github/workflows/regression_testing.yml index 6a6323c8f..fbcf34834 100644 --- a/.github/workflows/regression_testing.yml +++ b/.github/workflows/regression_testing.yml @@ -1,5 +1,8 @@ name: Regression Testing +permissions: + contents: read + on: push: branches: [main] @@ -57,7 +60,7 @@ jobs: uses: actions/checkout@v5 with: repository: microsoft/vcpkg - ref: 2025.02.14 + ref: 2026.07.29 path: vcpkg - name: Install OpenMP (macOS) @@ -108,6 +111,25 @@ jobs: python -m pip install --upgrade pip python -m pip install pytest numpy + - name: Set up MSVC environment (Windows) + # The Windows preset uses the Ninja Multi-Config generator, which needs + # cl.exe (and ninja) on PATH — nothing else puts them there. vcpkg's + # own port builds locate VS by themselves, so the gap only surfaces at + # the outer configure ("CMAKE_C_COMPILER not set"). + if: runner.os == 'Windows' + uses: ilammy/msvc-dev-cmd@v1 + with: + arch: x64 + + - name: Re-pin VCPKG_ROOT (Windows) + # vcvars64 (VS 2022 17.6+) exports VCPKG_ROOT pointing at Visual + # Studio's bundled vcpkg, and msvc-dev-cmd forwards it to every later + # step, overriding the job-level env — so configure would silently + # build against VS's port snapshot instead of the pinned checkout. + if: runner.os == 'Windows' + shell: pwsh + run: echo "VCPKG_ROOT=${{ github.workspace }}\vcpkg" >> $env:GITHUB_ENV + - name: Configure (Release with tests) # The *-tests-release preset sets VCPKG_MANIFEST_FEATURES=tests;geopackage # and enables OPENSWMM_BUILD_UNIT_TESTS + OPENSWMM_BUILD_REGRESSION_TESTS @@ -163,6 +185,27 @@ jobs: OPENSWMM_BUILD_DIR: ${{ github.workspace }}/build-${{ matrix.vcpkg_triplet }} run: python -m pytest -v --tb=short + - name: Manual worked-example decks run to completion + # The manuals' simulated-tier figures and the Application Manual's + # worked examples cite decks under docs/figures/decks/. Every one must + # run clean (exit 0, no ERROR in the .rpt) under a per-deck budget, or + # the prose is describing a model that no longer works. Linux only: + # one platform proves the decks; the figures themselves are committed. + if: runner.os == 'Linux' + env: + OPENSWMM_BUILD_DIR: ${{ github.workspace }}/build-${{ matrix.vcpkg_triplet }} + run: > + python3 scripts/build_manual_figures.py run-decks + --out tests/output/manual_decks_ci --max-seconds 600 + + - name: Upload manual deck run summary + if: always() && runner.os == 'Linux' + uses: actions/upload-artifact@v5 + with: + name: manual-decks-${{ matrix.vcpkg_triplet }} + path: tests/output/manual_decks_ci/summary.tsv + if-no-files-found: ignore + - name: Install Release tree run: > cmake --install build-${{ matrix.vcpkg_triplet }} diff --git a/.github/workflows/typing.yml b/.github/workflows/typing.yml index 80ad77769..ce69a8224 100644 --- a/.github/workflows/typing.yml +++ b/.github/workflows/typing.yml @@ -1,19 +1,28 @@ name: Typing (mypy) +permissions: + contents: read + on: push: - branches: [main, develop] + branches: [main, develop, swmm6_rel] paths: - 'python/openswmm/**/*.py' - 'python/openswmm/**/*.pyi' + - 'python/openswmm/**/*.pyx' + - 'python/openswmm/**/*.pxd' + - 'include/openswmm/engine/**' - 'python/tests/typing/**' - 'python/pyproject.toml' - '.github/workflows/typing.yml' pull_request: - branches: [main, develop] + branches: [main, develop, swmm6_rel] paths: - 'python/openswmm/**/*.py' - 'python/openswmm/**/*.pyi' + - 'python/openswmm/**/*.pyx' + - 'python/openswmm/**/*.pxd' + - 'include/openswmm/engine/**' - 'python/tests/typing/**' - 'python/pyproject.toml' - '.github/workflows/typing.yml' diff --git a/.github/workflows/unit_testing.yml b/.github/workflows/unit_testing.yml index e1e1788e4..b66b39a0f 100644 --- a/.github/workflows/unit_testing.yml +++ b/.github/workflows/unit_testing.yml @@ -1,5 +1,8 @@ name: Unit Testing +permissions: + contents: read + on: push: branches: [main, develop] @@ -23,7 +26,6 @@ jobs: name: "C++ Engine (${{ matrix.alias }})" permissions: contents: read - actions: write strategy: fail-fast: false matrix: @@ -65,7 +67,7 @@ jobs: uses: actions/checkout@v5 with: repository: microsoft/vcpkg - ref: 2025.02.14 + ref: 2026.07.29 path: vcpkg - name: Install OpenMP (macOS) @@ -117,6 +119,15 @@ jobs: with: arch: x64 + - name: Re-pin VCPKG_ROOT (Windows) + # vcvars64 (VS 2022 17.6+) exports VCPKG_ROOT pointing at Visual + # Studio's bundled vcpkg, and msvc-dev-cmd forwards it to every later + # step, overriding the job-level env — so configure would silently + # build against VS's port snapshot instead of the pinned checkout. + if: runner.os == 'Windows' + shell: pwsh + run: echo "VCPKG_ROOT=${{ github.workspace }}\vcpkg" >> $env:GITHUB_ENV + # gpu;hypre are vcpkg default-features and the plugin/hypre CMake options # default ON, but request them EXPLICITLY so the Kokkos `tests/gpu` parity # tests and the BoomerAMG path are always built+exercised here even if an diff --git a/.github/workflows/unit_testing_python.yml b/.github/workflows/unit_testing_python.yml index af97e94bc..841d11d58 100644 --- a/.github/workflows/unit_testing_python.yml +++ b/.github/workflows/unit_testing_python.yml @@ -1,19 +1,31 @@ name: Unit Testing Python +permissions: + contents: read + on: push: - branches: [main, develop] + branches: [main, develop, swmm6_rel] pull_request: - branches: [main, develop] + branches: [main, develop, swmm6_rel] env: VCPKG_ROOT: ${{ github.workspace }}/vcpkg VCPKG_EXE: ${{ github.workspace }}/vcpkg/vcpkg VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite" - VCPKG_MANIFEST_FEATURES: "tests" + # `gpu` (Kokkos) is required, not optional: the base wheel builds the + # Kokkos-OpenMP surface plugin (python/CMakeLists.txt sets + # OPENSWMM_BUILD_GPU_PLUGIN=ON and VCPKG_MANIFEST_FEATURES=2d;gpu), and its + # find_package(Kokkos REQUIRED) fails configure outright if Kokkos is absent. + # Stated here as well so this workflow's feature set cannot drift out of step + # with the wheel's and fail late, in the middle of a matrix. + VCPKG_MANIFEST_FEATURES: "tests;2d;gpu" OMP_NUM_THREADS: 1 jobs: + python-contracts: + uses: ./.github/workflows/python_contracts.yml + # ────────────────────────────────────────────────────────────────────── # Python bindings — cibuildwheel matrix (one runner per OS/arch). # @@ -26,10 +38,10 @@ jobs: # See docs/CIBUILDWHEEL_REVERT_PLAN.md. # ────────────────────────────────────────────────────────────────────── python: + needs: python-contracts name: "Python (${{ matrix.os }})" permissions: contents: read - actions: write strategy: fail-fast: false matrix: @@ -59,7 +71,7 @@ jobs: uses: actions/checkout@v5 with: repository: microsoft/vcpkg - ref: 2025.02.14 + ref: 2026.07.29 path: vcpkg - name: Bootstrap vcpkg (macOS) diff --git a/.gitignore b/.gitignore index be43b5b91..691dc6574 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,17 @@ # Working notes not intended for version control doc/FlashX_SWMM_crosswalk.md doc/Verification_Implementation_Plan.md -/plans/ +# Plans, handoffs, verification notes and generated result write-ups are +# working records, never committed (user decision 2026-09-30; this reverses the +# 2026-09-01 decision to track plans/transport). The plans/parity tooling and +# its .tsv/.json data stay tracked. +/plans/* +*HANDOFF*.md +*_PLAN.md +*_PLAN_*.md +*VERIFICATION*.md +/tests/benchmarks/generated/LOAD_RESULTS_*.md +/tests/manual/*/RESULTS.md /tools/ docs/2D_MULTISCALE_FORMULATION_REVIEW.md # Ignore examples/ contents (not the dir itself, so the fixture below can be @@ -13,6 +23,12 @@ docs/2D_MULTISCALE_FORMULATION_REVIEW.md # Keep the canonical 2D fixture — tests/unit/engine/CMakeLists.txt and # python/tests/engine/{test_2d_evap,test_surface2d_view}.py load it from here. !/examples/2d_complete_example.inp +# Keep the street-inlet / inlet-junction example (deck + README only; the +# .rpt/.out a run writes next to them stay out). +!/examples/inlets/ +/examples/inlets/* +!/examples/inlets/street_inlet_junction.inp +!/examples/inlets/README.md # Eclipse Stuff .metadata/ @@ -66,7 +82,11 @@ python/tests/engine/output/ python/tests/legacy/output/* !python/tests/legacy/output/b8_aq_probe.inp python/tests/output_pet_parity/ -tests/verification/ +# Scratch verification runs (d2_retirement/ is ~88 .rpt/.out/.log artifacts). +# Trailing /* rather than /, so gw2d_gates below can be re-included: git +# cannot re-include anything under an excluded *directory*. +tests/verification/* +!tests/verification/gw2d_gates/ tests/regression_testing/p1c_parity/* !tests/regression_testing/p1c_parity/compare.py tests/regression_testing/p5_parity/ @@ -98,3 +118,18 @@ tests/unit/legacy/engine/data/hotstart/site_drainage_model_save_hotstart.rpt # SQLite side-car files left when a GeoPackage fixture is opened WAL-mode. *.gpkg-shm *.gpkg-wal + +# Model-load benchmark corpus. Generated on demand by +# tests/benchmarks/scripts/gen_load_bench.py (326 MB at the plan's sizes) — +# the generator is committed, its output is not. Results docs written here ARE +# committed, hence the negations. +tests/benchmarks/generated/*.inp +tests/benchmarks/generated/*.rpt +tests/benchmarks/generated/*.out +tests/benchmarks/generated/*.json + +# Working copies written by test_engine_output_reader_live (reviewable, not tracked) +tests/unit/engine/data/live_out/ + +# Figure-pipeline engine runs (regenerated by scripts/build_manual_figures.py build) +docs/figures/cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md index e69d1b6a2..d0ccbe792 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Version boundaries in this file: `6.0.0-alpha.2` covers work merged after the `v6.0.0-alpha.1` tag up to and including 2026-07-12; `6.0.0-alpha.3` covers -everything from the `6.0.0-alpha.3` version bump (2026-07-12) onward. No +everything from the `6.0.0-alpha.3` version bump (2026-07-12) up to the +`v6.0.0-alpha.3` tag (2026-08-11); `6.0.0-alpha.4` covers everything from that +tag to the `6.0.0-alpha.4` version bump (2026-09-08). No `v6.0.0-alpha.2` tag was ever cut — that version string lived only in `CMakeLists.txt` (`OPENSWMM_PRERELEASE`), `vcpkg.json` and `python/pyproject.toml` — so the `[6.0.0-alpha.2]` heading below is @@ -21,8 +23,1587 @@ retroactive. ## [Unreleased] +### Python bindings + +- **Add `openswmm.engine.catalog`**, a machine-readable description + (`catalog.json`, shipped in the wheel) of every service, element kind, + sub-view and standalone class the Python API exposes: each property's type, + access, units and lifecycle phases, each method's signature, the C symbols + behind it and the bulk array that reads a whole collection at once. + `python/scripts/gen_catalog.py` generates it from the type stubs, Cython + sources and header docs; `--check` in the Python contracts workflow fails on + a stale catalog, an uncatalogued public class or a float field without a + unit kind (`dimensionless` is explicit). `catalog.unit_label(kind, + unit_system, flow_units)` gives the label for a model's units, and a runtime + test fails when a public attribute is missing from the stubs. The OpenSWMM + MCP server and `openswmm.gymnasium` address engine fields through it. +- The type stubs now declare `Subcatchment.loadings` (`LoadingsView`), the + container methods of `Aquifers` and `Snowpacks`, and the groundwater and + groundwater-transport option records. +- Add groundwater hydrology and transport views, surface-quality tables, + transport configuration/capability records, 2D rainfall diagnostics, batch + deletion, live output refresh, compatibility/staged serialization and the + remaining metadata and forcing accessors. +- Report snapshots now read live routing diagnostics and convert fractional + continuity errors into their documented percentage fields. +- Retain owners in 2D/editor views, reject stale or concurrent access, propagate + callback failures safely, and synchronize public enums, type stubs and report + totals. Ship the `py.typed` marker and distinguish omitted optional extensions + from broken native dependencies. +- Add native API/enum drift gates to CI and release qualification. Wheel tests + include modern, legacy, top-level and integration tests. Expand Sphinx guides + with authoring/runtime units, lifecycle, persistence and callback contracts. + + +### Documentation + +- **Every implemented formulation is now documented, and every planned one is + marked as planned.** A review of the five manuals against the engine found the + `[OPTIONS]` table missing about 48 parsed keys, 27 input sections and 22 process + component sections with no grammar anywhere, no chapter for any process on the 2D + mesh, nothing on the two-layer mesh aquifer or on surface quality, an application + manual of seven empty stubs, no conceptual diagram as an image, and a roadmap + still calling five shipped features unimplemented. The programme that followed: + + - **New reference chapters.** Hydrology 8 (distributed surface processes on the + mesh) and 9 (spatially explicit groundwater); Water Quality 10 (surface quality + and transport on the mesh); planned-formulation chapters for all three reference + manuals. Hydraulics 9 absorbed the two September bolt-on sections: the three + momentum closures become §9.2.1–9.2.3, quadrilateral cells §9.3.1, the two-plane + VFR closure §9.4.2, the full shallow-water face flux §9.5.10 and the + diffusive-wave law §9.5.11. + - **The Application Manual is now a formulation-choice manual**: thirteen chapters, + six interactive decision workflows, and ten in-tree decks under + `docs/figures/decks/`. Each worked chapter runs one deck under the alternatives + and reports what changed, against laboratory measurements where they exist. + - **A scripted figure pipeline.** `docs/figures/` carries one manifest, the + generators, and the committed PNG and SVG outputs; `scripts/build_manual_figures.py` + builds, audits and runs the decks. 83 figures are generated from source — the + conceptual process-and-formulation map in five per-manual variants, the engine's + own cross-section geometry, and every simulated figure from a run the deck gate + also executes. + - **Interactive diagrams.** Mermaid workflows and the process maps pan, zoom, and + open the chapter behind whatever you click, through + `docs/custom/js/manual-interactive.js` and `@ref` targets that Doxygen and the + lint both validate. + - **Status badges.** `\status{Implemented|Experimental|Planned|Retired}` reads its + vocabulary and colours from `docs/figures/status.py`, so the text, the badges and + the diagrams cannot disagree. + - **Gates.** The manual lint runs in CI with a 38-case negative suite that proves + every check can fail; the figure check audits the manifest against the manuals; + `scripts/gen_manual_frontmatter.py` generates the figure and table lists from the + captions, which found the water-quality manual listing eleven figures against + thirty-eight and inventing their captions. +- **The three EPA reference-manual monoliths are deleted.** They were excluded from + the build and cited by nothing; their content lives in the per-chapter files. + Recover any of them with `git show ^:"docs/manuals/reference/hydrology/SWMM 5 Reference Manual I (20150917).md"`. +- **`ROADMAP.md` reconciled against the engine.** Inlet junctions, Lagrangian + transport, transport on the mesh, multi-species reactions, heat and the mesh + aquifer move to Completed; the full shallow-water equations leave the deferred + list; the TPA high-celerity filling divergence is recorded as closed on 2026-09-12 + rather than pending, and the finite-volume key count is corrected to twenty live + and five retired. + +- **The user manual is retired and replaced by an Engine Manual** at + `docs/manuals/engine/`, split from it by audience. The graphical application is + documented in its own repository, so the chapters that described the retired Delphi + interface — Quick Start Tutorial, Main Window, Working with Objects, Working with the + Map, Printing and Copying, Add-In Tools, and Appendix C's 26 property editors, about + 2,900 lines — are gone. The engine material was kept and renumbered: the conceptual + model (Ch. 1), the input file reference (Ch. 2, formerly Appendix D), files and + command-line operation (Ch. 3, formerly Ch. 11), the status report and summary tables + (Ch. 4, formerly Ch. 9), the C API, Python bindings and plugins (Ch. 5, formerly + Ch. 13), and the error and warning messages (Appendix A, formerly Appendix E). + `git mv` was used throughout, so file history follows. The parent page carries a + *Where the old chapters went* table for anyone holding a citation to the old numbering. +- **Appendix A (Useful Tables) and Appendix B (Visual Object Properties) moved to the + SWMMVis manual** — they are values typed into an editor and per-editor property + dictionaries, not engine behaviour. The engine now links to them. +- **The engine site links into the GUI site with real Doxygen cross-references.** + `docs/tags/swmmvis-manual.tag` is a committed, pages-only tagfile (42 pages, 8 KB, + filtered from the GUI's published 6 MB tag) wired through `TAGFILES`, so + `@ref manual_*` and `@ref tutorial_*` resolve to correct deep URLs under + `CREATE_SUBDIRS`. It is committed rather than fetched at build time so the docs build + never depends on the other site being reachable; `scripts/refresh_gui_tagfile.py` + refreshes it and CI reports drift without failing. Only the `manual_`/`tutorial_` + namespace is imported — both repos declare a page called `authors`, and importing it + would have silently redirected every engine `@ref authors` to the GUI site. + `EXTERNAL_PAGES` is now `NO`, so the GUI's pages do not appear in the engine's index. +- **307 orphaned images removed** from the retired manual's `images/` directory. They + were referenced by nothing and were in neither `INPUT` nor `IMAGE_PATH`, so they had + never rendered. The ~38 reusable diagrams among them (conduit cross-section shapes, + HEC-22 grate and curb types, conceptual hydrology and LID figures, pump-curve types) + are listed in `tests/output/docs_migration_2026-09-19/figure_salvage_list.md` with the + commit to recover them from, to be restored by the change that rewrites the conceptual + model chapter and actually cites them. +- **Stale references cleaned up while rewiring**: `docs/Doxyfile` listed `./Updates.md`, + which does not exist; the nav bar's GitHub tab pointed at the archived + `HydroCouple/OpenSWMMCore`. `scripts/split_user_manual.py`, the one-time generator for + the retired tree, is deleted along with its input and output. + +### Performance + +- **Explicit FV solver: five bit-identical fixed-cost removals** (Phase 1 of + `plans/FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11.md`). Measured on the new Phase 0 + counters against a frozen base binary: `.out` byte-identical on all 28 synthetic + baseline rows and the 25-deck parity manifest (11 FV decks); every FV unit gate and the + full unit suite green. + - `advance()` no longer begins with a full-mesh depth inversion when the state is the + solver's own (`state_clean_`): nothing outside the solver writes `cell_a` between two + routing steps, so the refresh recomputed what was already there — 27-32 % of a reach + deck's step at one substep per routing step. + - `settleAccumulators()` returns at once when no LTS macro cycle has booked flux + (`acc_dirty_`): on every baseline deck LTS never fired a cycle, yet each re-tier drained + all-zero accumulators and ran two full-mesh refreshes. The LTS block's own census is + reused as the global path's when it falls through without re-tiering — one face sweep + per substep instead of two. + - A per-cell closure cache (`cell_ah_`/`cell_t_`/`cell_i1_`, filled wherever `cell_h` is + written) serves `faceSide`, the step census and the LTS stability bounds, which + re-evaluated the same section at the same stored depth several times per substep and + once per node-solve trial. `faceSide` also stops computing a ghost side's first moment, + which `computeFaceFlux` discards, and `relaxOneNode` no longer evaluates each face's + geometry twice. + - Work removed (Phase 0 → Phase 1, same substeps): depth inversions −57 % on Example1 + and −75 % on a 500-conduit reach at the default mesh (LTS on/off rows now equal), area + calls −40…50 %, first-moment calls −50…60 %. Wall clock is recorded in + `plans/FV1D_PERF_BASELINE_2026-09-11.md` once measured on a quiet host. + +- **Explicit FV solver: the dt census bounds a pass-through junction's ghost by the cell + it actually fluxes; mass-only node residual; species-only face stores** (Phase 1e, 1c, + 1g of the same plan). `faceSide` presents the far cell's centred state as a pass-through + junction's ghost, but both the face census and the per-cell LTS bound rebuilt a ghost from + `node_head − z_face`, which after a drop offset stands above the downstream crown and + carries the slot celerity the flux never sees. Both bounds now use the far cell's cached + state: East Boston 77 goes from 28.0 to 4.55 substeps per routing step and 123.8 to 60.5 s + at one thread (continuity 0.797 % unchanged, node-head rms difference 0.0008 ft on a + 22 ft signal, overflow series identical; transitions and the lab columns identical) — + cumulative since the Phase 0 base 206 → 60.5 s, now faster than DYNWAVE's 64.4 s. The + algebraic node solve's trial fluxes are mass-only (`riemannMassFlux`, bit-identical to + `riemannFlux().mass`) with one full flux at the accepted head; the contact speed and the + full flux record are stored only when species are carried. Both bit-identical on the + 31-deck manifest. Dev switches: `OPENSWMM_FV_CENSUS_PASS=0` (old bound), `OPENSWMM_FV_CFL` + (overrides FV_CFL for the Phase 4a sweep), `OPENSWMM_FV_LTS_FIT=1` (Phase 4c: a macro + cycle cut to fit the remaining routing-step window instead of global stepping; off by + default, measured in the baseline document). Phase 4b (laterals credited into a clean + pass-through junction's end cells) was already in the tree. + +- **Explicit FV solver: section blocks shared across conduits, junction solves in + parallel** (Phase 1f and 3d of the same plan). The mesh carried one geometry block per + conduit (~4.4 kB with the closure table): TwinOaks v2 has 5086 conduits and eleven + distinct sections, East Boston 183 and forty. `mesh.geom` now holds one block per + distinct (section, barrels, open); friction, losses, slope and the culvert curve move to + `mesh.conduit_*` arrays; results are byte-identical (31-deck manifest). The algebraic + junction solves run in parallel on both the global path and the LTS tier firing — only + junctions that run the bracketed root solve are distributed, pass-through and storage + nodes stay serial, and the serial path is an explicit branch (a disabled pragma still + enters the runtime; on the 5-day East Boston deck the loop runs 13 M times and the + clause form cost 30 % at one thread). Bit-identical at any thread count. Measured on a + quiet host: TwinOaks 129.5 → 116.7 s at 1 thread and 103.0 s at 2 (183 → 125 s at 8); + East Boston 120.0 → 112.3 s at 1 thread and 104.7 s at 2. On this P+E-core host 8 + threads is slower than 1 on both decks (East Boston is authored `THREADS 8`); the + OpenMP loop gates take `OPENSWMM_FV_OMP_MIN_{CELLS,FACES,NODES}` overrides for sweeps. + Cumulative since the Phase 0 base: East Boston 206 → 105 s, TwinOaks 153 → 103 s. + +- **Explicit FV solver: cross sections from exact geometry, one POD closure kernel** + (Phase 2 of the same plan). FV no longer reads the legacy 51-row section tables + through the 25-way shape switch: `SectionGeometry.hpp` evaluates each section in + closed form at build time (circle segment, rectangle, trapezoid, triangle, parabola, + power; the arch/egg/horseshoe/… families and SWMM's elliptical pipes stay defined by + their tables), and `FvClosureKernels.hpp` samples it into a fixed-size, pointer-free + `FvClosure` — a monotone cubic-Hermite table (128 panels, Fritsch–Carlson limited) on + which the top width IS the derivative of the area and the first moment IS its + integral; RECT_OPEN / TRAPEZOIDAL / TRIANGULAR take an exact polynomial class with a + closed-form inverse. `depthOfArea` is a Newton iteration on the panel cubic instead + of Brent on tables that were never a derivative pair. Every hot-path function is an + `OPENSWMM_KERNEL_FN` over the POD struct (device-capturable, asserted by test). + Measured legacy → exact on one binary (`plans/FV1D_PERF_BASELINE_2026-09-11.md` + §Phase 2): circular inversion 3.3×, rect_open 7.9×, trapezoid 14.7×; same-moment wall + clocks base → Phase 1 → Phase 2 on reach_uniform_500 27.6 → 11.6 → 6.0 s, Example1 + 10.7 → 6.5 → 3.2 s. SWASHES `1d-fv` (33 cells) and the transitions suite are + IDENTICAL legacy vs exact; the explicit-slot lab column (e2_2006 C1) moves by 5e-4 + NSE. The legacy table/Brent path (the `XsectEval` pointer, the 129-row I₁/A table, + the area-uniform depth table, `depthOfAreaBracketed`, Brent) is deleted in the + follow-up commit once every `.out` of the exact path hashed identically without it; + `FvGeometry` is a pointer-free POD block apart from the build-time `XSectParams` it + keeps for the table-defined shapes. DYNWAVE is untouched (still bit-exact on the + legacy tables). + - **Implicit pressurized head update: secant storage correction.** With a closure + whose crown is consistent, the tangent linearization of the head row overshot + rising cells into the Preissmann slot (head spikes on the e2 rapid-fill implicit + column, divergence on e3 at c = 300 m/s). `PressurizedHeadSolver::solve` now + re-solves with the secant compliance of each cell's own closure (three Picard + passes, dev knob `OPENSWMM_FV_PRESS_SECANT_PASSES`). This changes results only under + `FV_PRESSURIZED_IMPLICIT YES`; default decks are byte-identical before/after. Known + residual (follow-up item): the map is not contracting on very stiff slots, so + `FvUnsteadyFriction.ValveClosureDampsOnImplicitPath` (c = 1000 ft/s) stays red + until a converged Newton on the nonlinear storage lands. + - **Integration gates re-based** (`test_fv_engine_integration.cpp`): the culvert + inlet-control and SURCHARGE_DEPTH fixtures run under the implicit head update — + measured on the explicit slot path the 3 ft culvert entrance locks pressurized at + 105/110/115/130/150 cfs and passed the fixture's 120 cfs only by luck of the table + closure (both closures pass every inflow with the implicit update, matching + DYNWAVE) — and the surcharge gate asserts the level the sealed node reaches; + mesh-refinement consistency is measured against FV's own dx = 10 answer (0.014 → + 0.012 → 0.004) with DYNWAVE agreement kept as a floor; the storage-loss continuity + gate is 0.2 % (the deck's own ledger error is 0.04 % under either closure). + +### Added + +- **Two-zone groundwater results in the 2D results file (G-O).** A model + with a resolved `[2D_AQUIFER]` now writes its aquifer to the `.h5` under + the new `REPORT_2D_VARIABLES` group `GROUNDWATER` (in DEFAULT): ten + per-cell `[time, face]` fields — `Mesh2_face_gw_table_elev`, `_hg` + (saturated thickness), `_hu` (closure A unsaturated storage), `_recharge`, + `_lateral`, `_node_exchange`, `_deep`, `_et`, `_dunne`, `_infil_in` (the + rates are each cell's last firing, held, as the C API reads them) — the + static `Mesh2_face_gw_bed_elev` and `Mesh2_face_gw_closure` (0 closed + form, 1 enslaved, 2 sigma — the mask for the σ block), the domain ledger + series `groundwater_ledger [time, 11]` (the `SWMM_GW2D_LED_*` order plus + the continuity residual), and `groundwater_node_exchange_cum [time, bed]` + with a `node_names` attribute (cumulative aquifer ↔ node exchange per + `[2D_AQUIFER_NODE]` bed, + out of the aquifer — the series behind the + GUI's GwExchange plot). `GW_DETAILED` (not in DEFAULT) adds the σ columns + `Mesh2_face_gw_theta_sigma [time, layer, face]`, the one m × nFace + variable. At finalize the file gains a `/groundwater_2d` group of ledger + scalars with a `continuity_error` attribute beside `/mass_balance_2d`, + and the `.rpt` gains a "2D Aquifer Continuity" block after the 2D surface + block. The storage views the C API used (`liveStorage`, `ledgeredStorage`, + the residual) moved onto `SubsurfaceState` so the file, the report and + `swmm_gw2d_get_continuity_error` share one definition. Gate: + `test_engine_2d_output_options` `DeckGroundwaterFieldsEndToEnd` — every + dataset present with the right shape on a two-triangle and a mixed + tri + quad deck, water table ≡ bed + hg per record, the ledger's last row + closes to 1e-6 of storage, a deck without an aquifer writes none of it. + Program plan row G-O; unblocks stream U (GG5) and the σ-column inspector. +- **2D cell coverages, buildup, washoff and street sweeping (S7).** The + subcatchment land-use convention on the mesh: `[2D_COVERAGES]` (`*` | `TAG + name` | `CELL n` → a land-use percent set; a row replaces its scope's set, + GLOBAL < TAG < CELL), `[2D_LOADINGS]` (initial buildup per acre | hectare, + a pollutant or a reactions-component species) and `[2D_CURB_LENGTH]` + (needed by PER_CURB land uses). Every cell then runs the subcatchment + surface-quality step's own arithmetic — POW / EXP / SAT / EXT buildup + through the inverse-days form, EXP / RC / EMC washoff with legacy's unit + pre-multiplies, the available-buildup cap, BMP removal, per-(cell, land + use) sweeping on the shared calendar — at the runoff-step cadence + (`2d/quality/SurfaceQuality2D`). The runoff rate a cell feeds the washoff + laws is its **net** outflow per unit area over the step (what left across + faces, boundaries and drains minus what arrived across faces, spills, + discharge and inflow boundaries; rain and groundwater return are + generation), accumulated by the marcher at the sites the species ledgers + already book — the cell analogue of the subcatchment's `outflow / area`, + and independent of how finely a plane is meshed. Washoff mass enters the + cell's species row (ledger `gained_washoff`) and reaches the 1D node + through the existing coupling tuple; no new coupling row. Outputs: + `REPORT_2D_VARIABLES` token `BUILDUP` (in DEFAULT) → `Mesh2_face_buildup + [time, species, face]` (lbs/acre | kg/ha, `species_names`), a `.rpt` + "2D Surface Washoff Summary" block, the `.inp` writer echoes the rows. + C API (`openswmm_sq2d.h`): `swmm_2d_coverage_*`, `swmm_2d_loading_*`, + `swmm_2d_curb_length_*` (row edits share the file's parsers; names are + validated at once; refused once initialized) and + `swmm_2d_get_buildup_bulk`. Ownership: rows are inert with one warning + under `RAINFALL_MODE NONE`; covered cells inside a subcatchment that has + `[COVERAGES]` raise one double-counting notice and the run proceeds. + Gates: `test_engine_2d_surface_quality` (buildup parity with a subcatchment + **bit-for-bit**, for a pollutant and an MSX species; EMC washoff = C × + runoff and Σ net cell outflow = drained volume to 1e-10 on a two-triangle + and a one-quad pan; ledger closure with sweeping and BMP; ownership + warnings; round trip and grammar refusals; inert rows bit-identical; C-API + grammar) and the `.h5` / C-API end-to-end gate in + `test_engine_2d_output_options`. Not in v1: co-pollutant fractions on + cells, `Mesh2_face_washoff`, hotstart carry of the store, Python / MCP + mirrors, GeoPackage rows. Design: `OVERLAND_TRANSPORT_HEAT_MSX_PLAN` §8 + (D-A22 revised 2026-09-19 to the net-outflow definition). +- **MSX species build up and wash off (BW-MSX).** `[BUILDUP]`, `[WASHOFF]` and + `[LOADINGS]` rows may name a reactions-component species (declared in the + component's `.rxn`), not only a `[POLLUTANTS]` entry. Such rows are parked by + name at parse and bound after the component is applied (the `[INITIAL_QUALITY]` + / `[INFLOWS]` deferral); they run the pollutant surface-quality step's own + arithmetic — POW / EXP / SAT / EXT buildup through the inverse-days form, + EXP / RC / EMC washoff with legacy's unit pre-multiplies, the available- + buildup cap, BMP removal and street sweeping on the shared (subcatchment, + land use) schedule — over a separate MSX-keyed store (`ReactionData::surface`, + `quality/MsxSurfaceQuality.cpp`), and deliver the washoff into + `msx_ext_mass_in`, the rate the ARD engine, the legacy MSX dispatch and LARD + already consume for species loads. Mass units per species follow the species' + declared units (`MG` → lbs/kg via UCF(MASS), `UG` → ÷1000, other → 1). The + `.inp` writer emits the rows; `swmm_buildup_get/set`, `swmm_washoff_get/set` + and `swmm_subcatch_get/set_initial_loading` address species at index + `n_pollutants + m` (Python: `set/get_buildup`, `set/get_washoff` and the + subcatchment `LoadingsView` accept a species name or that index); the `.rpt` + gains a "Subcatchment MSX Washoff Summary" + block with the surface ledger; deleting a land use re-packs the species + matrices. A row naming neither a pollutant nor a species warns (one line per + row) and is ignored. Not in v1: co-pollutant fractions for species and + kinetics inside the dry store (D-A28 / D-A29). Gate: + `test_engine_msx_buildup_washoff` — an MSX species with a pollutant's + parameters produces the pollutant's surface loads and final buildup + **bit-for-bit**, the ledger closes to 1e-10, pollutant trajectories are + bit-identical with the species rows present, round trip through writer and + C API, MSX-only decks. Design: `OVERLAND_TRANSPORT_HEAT_MSX_PLAN` §8.9. +- **`test_engine_fv_section_geometry`**: the exact section geometry against an + independent integration of the outline, the closure against the geometry (area, top + width, hydraulic radius), T ≡ dA/dh, I₁ ≡ ∫A, monotonicity, a 60 000-point + depth↔area round trip at 1e-12·y_full, the polynomial class in closed form, barrel + scaling, POD capture at a foreign address, and the recorded legacy-table error per + shape (circular: area 7.3e-4 of full, width 7.1 % of max, hydraulic radius 2.3 %). + `fv_perf_phase2_gates.sh` runs the Phase 2 gates as one job (bench, SWASHES, + transitions, lab cells, synthetic sweep; `FV_GATE_STEPS` selects steps) and + `fv_perf_compare_scores.py` diffs suite score files by verdict and metric. +- **FV solver instrumentation for the closure-kernel program.** `[PERF-FV]` gains + closure-call counters (`n.area n.width n.i1 n.hydrad`) and LTS macro-cycle counters + (`n.macro n.macrorej`); the report's "FV Solver Statistics" block gains + `LTS Macro Cycles Fired / Rejected`, which is what distinguishes "tiering never engaged" + from "tiering did not help" (the tier histogram alone cannot: it is filled whether or + not a cycle fits the routing step). `bench_fv_closure` times every closure kernel per + shape on the geometries the mesh builder builds (built in the tests tree too, no Google + Benchmark needed); `fv_perf_baseline.py` runs real decks as authored at THREADS 1/8 + (`--real-deck`), parses the new rows, and reports closure calls per substep; + `fv_perf_phase0.sh` runs the whole Phase 0 as one detached job and + `fv_perf_compare.py` is the mechanical Tier A hash gate between two runs. + ### Added +- **The 1D ⇄ aquifer quality seam carries mass (T7.4).** T7.1 left both 1D + seams moving water with no species: a recharging node and a leaking + conduit filled their cells with clean water, and a draining aquifer handed + its node nothing. All three now carry the tuple. A **leaking conduit** + delivers its own concentration into the cells it crosses, by the same + length weights the volume takes — the 1D quality solver already debited + that mass as its exfiltration loss, so this completes a transfer that used + to be a disappearance, and nothing is removed twice. A **recharging node** + sends its quality down the bed, sampled from the same published node row + the 2D surface spill reads, so the two 2D seams cannot disagree about what + a node is carrying; the 1D books the loss in `qual_routing_seep` — a row + it never had, which is why its quality continuity error previously grew by + exactly this. A **draining aquifer** hands its mass to the node's coupling + queues, the same channel the surface's drain uses, booked to + `qual_routing_gw_in`. MSX rows stay where they are: the 1D node has no MSX + inflow accumulator for any loader, the same recorded gap the surface seam + has. The gaining-conduit direction is still open — a conduit has no + per-link quality inlet to receive into. Gates: a leaking conduit's mass + arrives and the aquifer still conserves; a recharging node's mass arrives + and the 1D books the loss; **what the aquifer gives up is what the node + receives, to 1e-9, once the aquifer's conc·m³ is expressed in the 1D's + conc·ft³**. GW transport plan §3.5, T7.4. +- **The aquifer's transported tuple is visible and restartable (T7.5).** + T7.1 and T7.2 gave the two-zone kernel species, age and temperature; this + round gives them to the modeller. **Results file:** + `Mesh2_face_gw_sat_conc` and `Mesh2_face_gw_unsat_conc` + (`[time, species, face]` concentrations, one per zone, with a + `species_names` attribute) and `groundwater_species_ledger` + (`[time, species, 13]`, the per-species twin of `groundwater_ledger`, with + its `terms` attribute and a derived residual column), all riding the + existing `REPORT_2D_VARIABLES GROUNDWATER` mask and absent on a deck that + transports nothing. **Report:** a `2D Aquifer Quality Continuity` block + per species beside the water one — initial and final stored mass, every + inflow and outflow channel, and the continuity error — printed only when + the kernel carried a tuple, so a water-only deck's `.rpt` is unchanged + line-for-line. **Hot start:** a new **V6** block carries both stores and + the species ledgers, so a restart resumes a plume instead of re-seeding + it from `[GW_INITIAL_QUALITY]`; species are matched by NAME, because a row + layout depends on `[POLLUTANTS]`, the MSX list and the AGE / TEMPERATURE + switches, any of which can differ between the run that wrote the file and + the run that reads it — a species the reader lacks is dropped with a + warning, one the file lacks keeps its seed. **C API:** + `swmm_gw2d_species_count`, `swmm_gw2d_species_name`, + `swmm_gw2d_get_cell_conc` (per zone) and `swmm_gw2d_get_species_ledger`. + Gates: the C API agrees with the kernel cell for cell and term for term; + the `.h5`'s last record is the state the run ended in (at FLOAT64, so the + gate tests the plumbing rather than float32's last digit) and its residual + column closes; the `.rpt` block appears with the water block; a hotstart + round trip resumes both stores and continues the ledgers. GW transport + plan §3.4, gate 9, T7.5. +- **Dispersion, retardation and decay in the aquifer (T7.2).** The + transported tuple of T7.1 now spreads, sorbs and reacts. + **Dispersion** rides the lateral Darcy faces — `D = α_L·v_pore + D_m` from + `[GW_TRANSPORT_PARAMS]`, booked into the same side accumulators as + advection at the same cadence, so it inherits the marcher's cross-tier + consistency rather than needing its own argument. Its exchange is limited + exactly as the surface's is: at most the pairwise equalisation divided by + the receiver's face count (pairwise bounds do not compose — a cell fed by + three faces each closing its whole gap can end richer than every donor), + and at most a half-share of the giver's mass, with the signed temperature + row exempt from the mass share because it has no positivity to guard. + Binds are counted, not silenced. **Retardation** is linear-equilibrium + partitioning: a store holds the cell's TOTAL mass and every flux + multiplies by the dissolved fraction `1/R`, `R = 1 + ρ_b·K_d/θ` from + `[GW_SORPTION] Kd` and the grain density, so sorbed mass simply stays + where it is and no channel carries a retardation factor of its own. The + moving water table is the one exception — when it passes a grain, the + grain changes zone with it. **Decay** is first-order on the total mass of + both zones, per species, from `[GW_SORPTION] Decay` (1/day) falling back + to the `[POLLUTANTS]` Kdecay column, ledgered as `lost_reaction` so the + conservation statement still closes. `[GW_TRANSPORT_PARAMS]` and + `[GW_SORPTION]` resolve onto cells with the `* < TAG < CELL` precedence + the `[2D_AQUIFER]` rows use, and `[GW_TRANSPORT_OPTIONS] DISPERSION NO` + turns the first term off. Gates: dispersion narrows a seeded 25-against-5 + gradient and neither cell leaves the range its sources set; sorption cuts + what leaves the aquifer and keeps the rest; decay removes the analytic + `1 − e^{−kt}` fraction and the residual still closes to 1e-10. The + `SUBSURFACE` reactions-component adapter (`reactArdStage`, the hydvar + bindings and the EULERIAN_ARD element-state question) is **not** in this + round. GW transport plan §3.5, gates 1/2/5, T7.2. +- **The two-zone aquifer transports (T7.1).** With a `[2D_AQUIFER]` + resolved, the `[GW_*]` sections stop being authoring-only: the kernel now + carries a species / age / temperature tuple in two bulk stores + (`sat_mass`, `unsat_mass`), and every channel the water moves through + moves the tuple with it — lateral Darcy at the upwind donor's + concentration, recharge and capillary rise across the table, the moving + table's own handover between the zones, deep percolation, the node bed, + conduit seepage, saturation excess and column rejection back to the + surface, and ET, which carries water, age and temperature but no solute + (the column up-concentrates, program plan D-A20). Rows come from + `TransportPolicy` — the same authority the 1D and the 2D surface use, so a + species is the same row index in every domain — and the transport matrix's + groundwater row is real: `.rpt` and `swmm_get_transport_matrix` report + on(n) / off:KEY per class instead of a blanket "no transported quality". + `[GW_INITIAL_QUALITY]` seeds both zones (`ZONE SAT | UNSAT`; `LAYER` rows + are named as not applied while the unsaturated store is bulk). **The + surface seam is now a transfer, not a loss**: the mass infiltration takes + off a 2D cell arrives in the aquifer under it, and what saturation excess + pushes up arrives back on the surface (`gained_exfiltration`), each side + booking exactly what the other did. The "authored but INERT" warning now + fires only on a deck with no `[2D_AQUIFER]` for the rows to configure. + Gates: the GW plan's gate-6 conservation stub closes to 1e-10 on + all-triangle, all-quad and mixed meshes; the seam balances in both + directions net of what is in flight; ET leaves the solutes behind; the + matrix and the warning agree with each other. Heat still rides as a water + temperature-volume (the soil matrix's own capacity, conduction and the + thermal boundaries are T7.3), and dispersion, retardation and per-layer + resolution are T7.2. GW transport plan §3.4/§3.5, T7.1. +- **Conduits under the water table GAIN: the signed conduit ⇄ aquifer + conductance (G-X4).** `[2D_AQUIFER_OPTIONS] LINK_SEEPAGE TWO_WAY` replaces + a conduit's fixed `[LOSSES]` seepage loss with a MODFLOW-River exchange + about its own invert — `K·W·L·min((h_link − max(h_gw, z_inv))/d_c, 1)`, + `+` out of the pipe — so the loss is throttled as the table rises and + reverses once the table passes the water surface. This is the + groundwater-inflow term SWMM has never had for a conduit (only + subcatchment `[GROUNDWATER]` rows could feed a node). Three properties + hold by construction: a FULL pipe over a table at or below its invert + seeps exactly the legacy rate (`d_c` defaults to the conduit's full + depth), the exchange is continuous through the water table, and the gain + is bounded by the aquifer's own per-firing share of the cells the conduit + crosses — never by the pipe — so the 1D can never take water the 2D does + not have. `[2D_AQUIFER_LINKS] [KC k] [DC d] [EXCHANGE NO]` + overrides the conductivity and path length per conduit, gives a conduit + with no `[LOSSES]` rate an exchange, or keeps one out; rows round-trip + and a row naming an unknown link or a non-conduit is warned about, not + ignored silently. `LINK_SEEPAGE AUTO` (still the default) and `NONE` are + unchanged, and a deck without `TWO_WAY` takes the legacy branch at every + loss site. Ledger: the gaining half of the signed rate is booked to the + new `routing_link_gw_inflow` (`.rpt` "Conduit GW Inflow", printed only + when non-zero; `SWMM_ROUTING_LINK_GW_INFLOW`), never netted against + "Exfiltration Loss", and the aquifer is debited the same volume through + `led_link`. New `swmm_forcing_link_seepage` lets a host (HydroCouple's + `link_exchange_flow`) drive the exchange directly, OVERRIDE or ADD. + Gates: a drowned reach gains, the aquifer pays to 1e-9 and its table + draws down; a full pipe over a disconnected table reproduces the legacy + rate to 1e-12 while `AUTO` on the same deck still loses; `EXCHANGE NO` + keeps a conduit legacy; `KC` scales the gain linearly (damped by + drawdown); a forced rate is routed and booked on both sides. Program + plan §B.4b, D-A18 v2, G-X4. +- **Conduit seepage reaches the aquifer cells the conduit crosses (G-X3).** + A conduit with a `[LOSSES]` seepage rate used to lose that water to + nowhere; with a two-zone `[2D_AQUIFER]` under it, every routing step's + seepage volume — the same `rate × barrels × dt` the 1D books as + "Exfiltration Loss" — is now delivered into the saturated zone of the + cells its polyline (`[COORDINATES]` + `[VERTICES]`) crosses, split by the + exact length in each cell (a Cyrus–Beck clip against the convex cells; a + conduit half off the mesh delivers half). One-way and conservative: the + 1D still books the loss, the aquifer's new `led_link` term is where it + lands (continuity `in` gains it), and the table rises through the same + storage coefficient as the node and lateral volumes, Dunne excess if the + column is full. `[2D_AQUIFER_OPTIONS] LINK_SEEPAGE AUTO` (default) | + `NONE` (the legacy loss); the run reports how many conduits enrolled. + Surfaces: `.rpt` "Conduit Seepage Inflow" in the 2D Aquifer Continuity + block; `.h5` `Mesh2_face_gw_link_seepage` (m³/s per cell, held) and a + 12-column `groundwater_ledger` (`link` at index 10, the residual last — + read the `terms` attribute) plus `link_in` under `/groundwater_2d`; C API + `SWMM_GW2D_LED_LINK`, `SWMM_GW2D_VAR_QLINK`, option key `LINK_SEEPAGE`; + hotstart carries `led_link` as a 10th (length-prefixed) ledger term. + Gates: an evenly split conduit's seepage equals the aquifer's `led_link` + plus what is in flight to 1e-9 and raises the two columns identically to + 1e-12; `NONE` leaves the 1D bit-identical; a conduit half over the mesh + delivers half, all into the cell under it; one entirely off the mesh + enrols nothing. Program plan §B.4b, G-X3. +- **Every node inside the mesh exchanges with the two-zone aquifer (G-X2).** + `[2D_AQUIFER_OPTIONS] NODE_ENROLMENT AUTO` (the default) gives every node + whose `[COORDINATES]` fall in a mesh cell a direct-Darcy bed over the + cell's area — junctions, storage units and outfalls alike — so a + `[2D_AQUIFER_NODE]` row is only needed to override a bed's parameters or + to opt a node out: the row grammar gains `CELL AUTO` (locate the cell from + the coordinates; `swmm_gw2d_node_add` with cell −1) and `EXCHANGE NO` + (the node exchanges with nothing). `NODE_ENROLMENT ROWS` restores the + row-only behaviour. Auto-enrolled beds are not written back (the option + recreates them), authored rows round-trip with their new keywords, and + the run reports how many nodes enrolled. A node without authored + coordinates is never located (new `spatial.node_has_xy`). **One-owner + rule:** a storage unit with a bed exchanges through the conductance + channel and its own Green-Ampt exfiltration is switched off, named once + in the warnings; `EXCHANGE NO` keeps the legacy exfiltration. C API: + `swmm_gw2d_node_get_flags`, `swmm_gw2d_node_set_exchange`, option key + `NODE_ENROLMENT`. Gates: a junction with coordinates in a cell enrols, + exchanges and is not echoed; ROWS enrols nothing; `EXCHANGE NO` keeps a + node out and round-trips; an enrolled pond exfiltrates 0 on its own and + recharges through the bed, an opted-out pond exfiltrates as before. + Program plan §B.4b, G-X2. +- **Two-way node ⇄ aquifer exchange, the recharge direction capped (G-X1).** + `[2D_AQUIFER_NODE]` beds already drained the aquifer into a node at the + MODFLOW-River conductance rate with the drain capped at the cell's + drainable water; the reverse direction — a node standing above the water + table recharging the column — was uncapped. It is now limited by (i) a + saturation guard: a column whose table is at the ground takes nothing + (water it accepted would come back as saturation excess in the same + firing and ping-pong through the one-batch delivery lag); (ii) the + saturated zone's headroom, in the same per-step share as the drain side; + (iii) what the node can give — its stored volume as a per-batch budget + plus its through-flow (a junction stores nothing below its rim but can + lose water at the rate it is fed). Two things kept beds from exchanging + at all and are fixed with it: a bed under a node with no + `[2D_VERTEX_NODE_MAP]` entry never saw the 1D heads (the orifice coupling + alone published them), and the marcher's tail path — every routing step + that does not fit a full macro cycle, i.e. any variable 1D step — fired + the surface lists only, so the aquifer's lateral flow and node exchange + skipped those steps entirely. Gates: `FloodedManholeRechargesUntilThe + ColumnIsFullThenStops` (a surcharged junction recharges, the column + fills, the exchange goes to zero without ever reversing sign, no Dunne, + the recharge equals the storage gain to 1e-9, the 1D side books the same + water leaving) and `SpringOnDryGroundReachesTheNetworkThroughTheOrifice + Coupling` (exfiltration onto a dry cell drains into a junction; aquifer, + surface and 1D ledgers agree on the volume). Program plan §B.4b, gates + (b) and (c). + +### Fixed + +- **A CUMULATIVE rain gage rained for one step per table entry instead of for + its recording interval (issue #158).** A `CUMULATIVE` gage records a running + depth total: the intensity for a record is the rise since the previous + record spread over the gage's RECORDING INTERVAL, and legacy applies it for + the whole of that interval. Through `6.0.0-alpha.3` the gage was read as a + step-function lookup on its series rather than legacy's state machine, so + the intensity was applied for a single runoff step at each table entry. + Both reported symptoms follow from that one cause. Subcatchment runoff + showed a separate rise-and-recess at every entry instead of one continuous + hydrograph; and Total Precipitation came in short by the interval/step + ratio — 0.750 in against legacy's 9.000 in on the reporter's deck (an + hourly counter rising 1 in/hr against a `1:00` interval and a `00:05:00` + wet step), which is the reported "factor of 12", 3600 s / 300 s. The ratio + is the interval over the step, not a constant: a 15-minute cumulative + series on a `0:15` gage was short by 3. Fixed by the legacy state machine + (704ca917, 2026-09-13); ten cumulative decks — ramp, counter reset, zero + rise, interval shorter than the series spacing, non-zero first record, SI, + scale factor, co-gage, sub-hourly and late start — are now byte-identical + to legacy. Pinned by `test_engine_gage_cumulative`, which fails 8/8 against + an `alpha.3` build and passes 8/8 on this one. + +- **The aquifer's reported quality error was divided by the wrong total + (T7.4).** `.rpt`'s "2D Aquifer Quality Continuity" scaled its residual by + its own inline copy of "what came in" — `|init_mass| + |gained_infil| + + |net_lateral|` — written before T7.4 gave the aquifer two more inflow + routes, neither of which was added to it. On a network deck fed only + through its node beds that divides a machine-precision residual by a + machine-precision total: the block printed **6 198 889.840 %** beside a + balance exact to the last digit. The sum is now + `SubsurfaceTransportState::continuityDenominator`, which lives beside the + residual it scales, so a sixth channel cannot be added to one and + forgotten in the other. The balance rows themselves were always correct; + only the percentage was wrong. +- **ET's effect on water age in the 2D aquifer was implemented but ungated + (D-A20).** The kernel has always followed the program plan's D-A20 + convention — evaporation and ET take age-volume with the water at the + supplying layer's age, so the mean age of what remains is unchanged, while + solutes stay and the column up-concentrates. Nothing tested it: the only ET + gate asserted that the *solute* row lost nothing. Reverting the kernel to + the GW transport plan's superseded wording ("ET removes water not + age-volume") would therefore have left every gate green. Now gated, and the + plan's three stale statements — §2.4, the §3.5 ET row and gate 6's own + specification, which contradicted D-A20 — are amended to match the decision + and the code. +- **The node bed delivered 9.4× the water the aquifer released (G-W1).** The + cap on an aquifer→node drain measured the cell's drainable water with the + textbook specific yield θ_s − θ_r, while the column that then spent it used + the closure-consistent θ_s − θ_bot floored at 1e-3. For a table a few + centimetres under the ground those are 0.35 and 0.001, so the cap sat 350× + above anything reachable and never bound: the column went short on + essentially every firing, and the shortfall was refunded into the + **aquifer's** books alone — the router had already handed the unrefunded + volume to the node. Both continuity blocks closed and the seam still + created water: 0.625 m³ delivered against 0.067 m³ released on the gate + deck, 89 % of it refunded. Specific yield now has one owner, + `SubsurfaceSolver::specificYield`, which the cap and the column both call; + the refund no longer fires for the node at all, and the two sides agree to + the last digit. The defect needs a thin, near-saturated unsaturated zone + to bite — on a deck whose table sits 7.6 m up an 8 m column the cap never + binds and the numbers are unchanged — so the gate proves its own deck can + see it by counting the firings on which the cap actually clamped, and + asserts that the defect's signature (a column going short on the node's + account and being refunded) never occurs. The node→aquifer headroom cap has the same inconsistency + and is deliberately NOT changed here: making it consistent was attempted + twice and reverted twice — the floored yield leaves a saturated column + claiming 1e-3 of headroom it does not have (a surcharged node kept + trickling into a full column, which G-X1's gate caught), and the unfloored + yield takes the gate deck's 1D continuity from −0.66 % to −1.99 %. The + measured leak was on the drain side; the fill side needs its own round. +- **An aquifer species gate was passing on luck (G-W1).** T7.4's three seam + gates asserted `|residual| < 1e-10·|init|`, but `nacc_mass` — mass sampled + from a 1D node and not yet gathered by the cell — is counted in + `ledgeredStorage` while only being booked into `gained_node` at the + gather, so the balance is legitimately short by whatever is in transit. A + run that ends in that window carries the tail. Tightening the bed cap + above moved where the final sample landed and turned a tail that had been + ~0 into 0.0705 against an initial 614.9, which read exactly like an 11 % + mass leak; `residual` equalled `inFlight1D` to the last digit, which is + what identified it. The gates now assert `residual == inFlight1D` — the + identity completed, with the bound on it unchanged. +- **The aquifer quality block reported a perfect balance where it meant an + unmeasurable one (T7.4b).** When nothing had entered the aquifer on any + route the block had no scale to divide by, and printed `0.000` — which + reads as a balance closing exactly. It now prints `n/a`. This matters + beyond tidiness: with the denominator above naming every inflow route, a + zero scale beside a **non-zero** residual is precisely the signature of + mass leaving by a route nobody has booked the arrival of, which is the bug + class this stack has produced five times. `0 %` was the one answer that + would have hidden the sixth. +- **The aquifer→node transfer was counted in two inflow rows (T7.4b).** The + router queued the mass into `coupling_qual_queue` — which the quality + solver drains and books as `qual_routing_ex_in` — *and* booked + `qual_routing_gw_in` itself. One transfer, two inflow rows. On a deck whose + whole quality budget is aquifer → node → outfall it was a **49.7 % + continuity error**; the queue is now the only booking, which takes that + deck to ≈ −0.5 %. It was invisible until the fix below landed, because + while three quarters of the mass was being dropped the duplicated quantity + was ~0.001 lbs. The attribution cost is recorded rather than hidden: + **the `.rpt` quality continuity table's "Groundwater Inflow" row now reads + 0.000 on a deck whose only quality inflow is its aquifer, because that mass + moved to the 2D coupling inflow row — it did not vanish, and the table's + total is unchanged.** Restoring the dedicated row needs the queued mass + tagged by origin, since the queue is shared with the 2D surface's own + drain. +- **The aquifer delivered only a quarter of its drainage mass to the node + (T7.4, found by its own gate).** The per-bed weights that split a cell's + outgoing mass across the nodes it serves were accumulated over a routing + step and cleared at its flush — but a cell fires on the LTS ladder, not the + routing step, so any firing whose weights had already been cleared found no + weight to split by and dropped its mass. The aquifer still booked the + departure in `lost_node`, so the mass left one set of books without + arriving in the other: **75 % of it on the gate deck**. The weights are now + the volumes the gather itself takes, which makes them exact by + construction — they ARE what produced that firing's outgoing volume. The + seam delivers 100 %, and the two sides agree to machine precision. + +- **Infiltration from an inactive 2D cell never reached the aquifer.** The + marcher's cheap between-rebuild pass (`lazySourcesOnly`, taken on every + cycle that does not rebuild) sank infiltration off the surface and booked + it as a loss, but — unlike `syncAndRebuild`'s lazy pass, which G1-c item 1 + fixed — never handed the volume to the two-zone aquifer under it. Deck + continuity still closed, because a loss is a loss; the aquifer simply + never received that share of its recharge (1.4 % on T7.1's gate deck, and + more on a rain-on-grid deck where most cells stay inactive). Found by + T7.1's seam gate: the species could not balance while the water did not. + +- **A near-saturated closure-A column created water when anything withdrew + from it (found by G-X4's gate).** The two-zone kernel's closure A pairs the + saturated update's specific yield `Sy = θ_s − θ_bot` with a handover slab + of content `θ_bot`, so a moving table carries exactly `Sy·|Δh|`. When the + column is already at `θ_s` just under the table the difference collapses + and `Sy` hits its `1e-3` floor — but the handover kept using the raw + `θ_bot`, so the two no longer summed to `θ_s` and the cell gained + `(θ_bot − (θ_s − Sy_floor))·|Δh|·A` every firing. Invisible until a sink + pulled hard on a nearly-saturated column, which a conduit under a high + water table does: 0.08 m³ over half an hour on the G-X4 gate deck, an + 0.7 % continuity error. The slab content is now derived from the `Sy` + actually used, which makes the identity hold unconditionally and is a + no-op on every deck where the floor does not bind. + +- **ENSLAVED closure: the bracketed solve now converges on the volume.** The + G1-c bracket used a floored derivative, which across the capillary fringe + (θ(L) = θ_s, W flat in h) made Newton creep and leave the balance unmet by + up to 1e-5 m³ per firing — a −1.9e-4 m³ drift over a half-hour of two + full cells exchanging laterally. Newton now uses the true derivative and + drops to bisection where it vanishes, converging on the residual volume + (kernel gate 4 ENSLAVED: 2.3e-12 → 5e-14). +- **Two-zone aquifer: the ENSLAVED closure could zero the water table in one + firing (G1-c).** Its saturated-zone balance was solved by an unguarded + Newton from a linearised guess; with the table within centimetres of the + ground the surface water content is ≈ θ_s, the storage coefficient sits on + its floor, the guess lands above the ground and the clamped column makes + the derivative the floor too — one step of O(−1e5 m), the table zeroed, the + column re-evaluated at full length. Measured: the Dunne gate deck lost 10 + of the 10 m³ delivered (aquifer residual −32 %) and returned 0.001 m³ of + the ~8 m³ owed; a two-cell exfiltration deck created 23.5 m³. The balance + `W(h) = θ_s·h + hᵤ*(z_s − h)` is monotone, so it is now solved on + `[0, z_s]` by a safeguarded Newton with bisection fallback, and what the + interval cannot hold is booked exactly — above the ground as Dunne excess, + below the bottom as the sinks' refund. The kernel gates (`gw2d_gates`, all + closures) are unchanged to 1e-12; the Dunne deck now returns 9.95 m³ with a + zero residual. Every deck whose `[2D_AQUIFER]` resolves to ENSLAVED (AUTO + picks it for thin unsaturated zones) changes deliberately. +- **A dry surface froze the aquifer.** The marcher strode the whole window + when no surface cell was active, skipping the groundwater's lateral Darcy, + deep loss, ET and node exchange with it — a dry summer left the water + table exactly where the storm had put it. The macro cycle now runs while + an aquifer is live even when the surface is quiescent, and a dry cell the + aquifer exfiltrates into is pinned active by the rebuild's pending-cell + seed (the seed existed; nothing reached it). Gate: + `Aquifer2D.ExfiltrationReachesADryCellThroughThePendingSeed` — no rain, no + ponded water, lateral flow lifts a dry cell's table to the ground, the cell + receives exactly the Dunne volume, nothing stays parked, both continuity + errors zero. +- **The aquifer's own stability step now bounds the ladder's base step.** + `dt0` came from the active surface cells alone, so a groundwater cell with + a finer bound than every wet cell (or the whole domain with a dry surface, + where `dt0` fell back to `MAX_TIMESTEP`) fired beyond it on rung 0. The + rebuild folds `min(Δt_g, Δt_u)` over the aquifer into `dt0` (the fine side + of G1-c item 3; the coarse side — D-N1's runtime tier count — is still + open). +- **2D→aquifer recharge was booked one runoff step early (G1-c item 1).** + The 2D ledger's "to aquifer" transfer was booked when the marcher applied + the infiltration, the 1D groundwater ledger when the runoff step delivered + it, so the two disagreed by the routing steps between one drain and the + next — 3.6 % on the 30-minute U3 gate. The transfer is now booked at + delivery in the same loop as `gw_infil_2d_recharge`; the volume applied + but not yet delivered is `mass_balance_2d.infil_aquifer_pending`, and the + 2D continuity block prints both ("to Aquifer (delivered) / (in flight)"). + The U3 gate asserts the two ledgers equal to 1e-9 and delivered + pending + equals the applied loss. +- **A rain-on-grid deck with no subcatchment rained at its first record + forever.** The legacy rain-gage state machine (2026-09-13) keeps a gage no + subcatchment or unit hydrograph reads at its seeded first record — legacy's + "unused gage" rule — but the 2D mesh reads every gage under + `RAINFALL_MODE SYSTEM` / `NATURAL_NEIGHBOUR`, so a mesh-only deck saw its + first non-zero intensity for the whole run. `gageIsUsed` now counts the + mesh as a reader (S7 found it: the sweeping gate's dry tail never came). + Decks with a subcatchment on the gage are unaffected; the 25-deck parity + corpus is byte-identical; **47 rain-on-grid benchmark decks in the 2D + census change deliberately** (e.g. `2d_matrix/bench79202_t1.inp` rainfall + inflow 39601 → 6606 — it rained ~6× too long) — timing / bit-identity + baselines resting on them need regenerating. +- **2D transport rows on a mesh with no interior edge were silently inert.** + The marcher gated every species sink and source on its face accumulators + being non-empty, which is also true of a one-cell mesh with live rows + (`species_on_` now carries the intent; meshes with an interior edge are + bit-identical). +- **Street sweeping never fired on an `.inp` deck.** The per-(subcatchment, + land use) last-swept counters (`subcatches.sweep_last_swept`) were sized only + by the C API (`resize_coverage`) and the GeoPackage reader — never by the + `[COVERAGES]` handler — so the A7 sweeping loop skipped every index past the + empty array and "Sweeping Removal" read 0.000 on every deck read from a file. + `handle_coverages` now sizes the counters with the coverage matrix. Found by + the BW-MSX ledger gate; a deck with a nonzero `[LANDUSES]` sweep interval + now sweeps (legacy parity). The bit-identity corpus has no such deck and is + 25/25 byte-identical before and after. Two related parity gaps + remain and are recorded, not fixed: the `[LANDUSES]` LastSweep column is + parsed but never seeds the counter (legacy `lastSwept = start − sweepDays0`), + and a `[LOADINGS]` initial buildup is parked in `subcatches.conc` and never + applied to the pollutant buildup store (the new MSX store does apply its + loadings). +- **2D surface water age (S4b closeout).** (1) Evaporation now leaves at the + water's own mean age as well as its own temperature: the `__WATER_AGE__` row + is sunk proportionally with the evaporated volume (`sinkIntensiveRowsWithEvap`), + so a still pond no longer *ages* by evaporating — the 1D convention + ("evaporation leaves the mean age unchanged", `WaterAgeLegacy`) now holds on + the mesh. (2) `__WATER_AGE__` is authored in **hours** in `[2D_INITIAL_QUALITY]` + and `[2D_BOUNDARY_QUALITY]`, as in the 1D `[INITIAL_QUALITY]`, and the + `.h5` `Mesh2_face_species_conc` age row is reported in **hours** like every + 1D age column (it was seconds with `units = "1"`). (3) The dataset carries a + new `species_units` attribute parallel to `species_names` (`MG/L` | `UG/L` | + `#/L`, the MSX species' declared units, `hours`, `degC`); the engine + snapshot gains `surface_species_units`. (4) A deck with any transported row + (`TRANSPORT_*`, age, temperature) is always served by the CPU marcher and the + solver notice says why — the GPU/Kokkos plugin carries no transport rows and + used to be selectable with them silently absent. Gates: + `test_engine_2d_transport_s4` (evaporation keeps mean age; plugin refusal), + `test_engine_2d_output_options` (`species_units`; end-to-end hours). + Program plan D-A20 / D-A21. +- **Explicit FV: a lateral inflow into a dry pass-through junction is no longer lost.** A + clean degree-2 junction's lateral is credited straight into its two adjacent cells, and + the node marks it delivered — but under `FV_COMPACTION` (the default) dry cells are + inactive and the cell update, the only place the credit lands, skips them. The ledger + booked the inflow, no cell ever took it: on a 7 km tunnel filling from dry + (Klaver Example_02, 4.877 m circular in 5 m cells, seven lateral junctions) 100 % of the + first 70 minutes of lateral inflow at a junction vanished, 4.7 % of the run's total, until + the wetting front from upstream activated the cells; on East Boston the same mechanism + was the residual 0.8 % continuity error. A cell that receives a diverted lateral is now + active regardless of depth, and a credit into an inactive cell invalidates the active + lists. Klaver 4.691 % → −0.000 %, East Boston 0.797 % → −0.000 %, TwinOaks 4 h 0.000 %. + Gate `LateralIntoADryPassThroughJunctionIsNotLost` (a junction flanked by virtual + junctions, dry pipes: 100 % continuity error and zero outflow before the fix). +- **Explicit FV: a junction's own-head ghost no longer takes part in the slot/free bore + bound, and the vented-ghost crown-celerity cap is removed.** Marked free, the ghost of a + junction whose cell side stands in the slot too (a whole tunnel pressurized 50 m above + its junction crowns) made a "slot/free" pair of an acoustic face, the bound cut the + acoustic waves at every lateral junction, the algebraic solve found no head below its + ceiling, clamped at the rim and booked 63 100 m³ of "flooding" at junctions whose + published depth never exceeded half their rim (Klaver Example_02); marked by state, the + bound on a momentarily free cell beside it drove a 2× over-conveying limit cycle at a 20× + overloaded 0.5 ft entrance. The entrance lock the bound exists for lives at the INTERIOR + slot/free faces (measured: the bound alone releases it; the ghost celerity cap alone does + not, and with the ghost in the slot beside a momentarily free cell the cap fed the same + limit cycle), so the ghost is excluded (`FaceState::press == 2`) and the cap and + `FvGeometry::c_crown` are gone. Klaver: flooding 6.31 hectare-m → 0, the downstream weir + overflows 6.67 hectare-m as it should; the culvert fixture is unchanged; transitions + identical; lab e2_2006 C1/C2 within 0.003 NSE. `SurchargeDepthDelaysFlooding` asserts the + column on the AVERAGE depth: both runs open with a one-record startup overshoot (23–47 ft + on the first report line of a 10 cfs pour into a dry 0.5 ft pipe through a node with no + storage), a separate open item. +- **FV report: the per-node "Highest Continuity Errors" no longer reads a diverted lateral + as retained.** A lateral credited straight into the incident cells never crossed a node + face, so the face ledger held no outflow for it and the node's own continuity showed + 80–100 % at every lateral-fed pass-through junction (East Boston, TwinOaks, Klaver) while + the system balanced to 0.000 %. The solver books it as node outflow per substep on both + stepping paths (`bookDivertedLateral`), and a virtual junction's lateral likewise in the + publish. Report only: every `.out` is byte-identical. Nodes that see a few cubic metres + over a run still show large relative numbers, as in legacy. +- **Explicit FV: the wave entering a free surface at a Preissmann-slot interface is bounded + by the bore speed, not the slot's acoustic celerity.** The explicit slot path locked + pressurized at an entrance and flooded the junction however high its head stood (a 3 ft + culvert on a 5 % slope conveyed 96–136 cfs for every inflow from 100 cfs up; the + inlet-control fixture's 120 cfs passed only by luck of the legacy table closure). Face + traces showed Davis's symmetric estimate carrying the slot celerity into BOTH HLL waves + at a slot/free face, so the flux carried a diffusive mass term of order c_slot·ΔA (+52 cfs + at the node face) and a −245 ft⁴/s² momentum sink that pinned the entrance flux to the + cell's own momentum. Now: when exactly one side stands in the slot (`FaceState::press`), + the wave entering the free side is bounded by the Rankine–Hugoniot jump ΔQ/ΔA between + that side's own u ± c and the Davis bound (a junction's own-head ghost never takes part + in the bound — see the 2026-09-13 entry below); and the degree-1 prescribed-discharge + fallback skips an interior cell already in the slot (forcing the inflow into a full pipe + lifted its slot head by q·Δt/(t_slot·Δx) per substep — a 0.5 ft pipe fed 10 cfs chattered + its junction between dry and 40–80 ft; the fallback was also the culvert's + pressurized-reach deficit: 150 and 200 cfs now convey 150 / 200 at 2.85 / 10.90 ft against + DYNWAVE's 3.12 / 10.98). Measured (`plans/FV1D_PERF_BASELINE_2026-09-11.md`, Item 2): + the culvert passes 60–200 cfs like DYNWAVE at 53 instead of 173 substeps per step; + transitions `fv`/`fv-lts` identical; lab e2_2006 C1 within 0.0024 NSE, C2 st 0.56 → 0.84, + e4_aureli C1 p300 −9.7 → −2.3; the TPA high-celerity filling deck completes at + a = 150…3000 m/s where it diverged at every one (the P5b pin + `KnownIssueHighCelerityFillingDiverges` becomes the positive gate + `HighCelerityFillingCompletes`; `DivergenceGuardFailsLoudNotSilent` moves to a = 10 000, + which still diverges); `FvUnsteadyFriction.ValveClosureDampsOnImplicitPath`, the + implicit-path residual left red by the Phase 2 secant correction, passes again. Decks + that never pressurize are byte-identical. Dev switches `OPENSWMM_FV_MIXED_WAVE=0` and + `OPENSWMM_FV_DEG1=1` restore the previous estimates for one A/B cycle. +- **FILLED_CIRCULAR conduit offsets cross the C API as authored values.** Once + `resolve_cross_references` raised a partly filled circular conduit's stored offsets by the sediment + depth (legacy `link.c:1072-1077`), `swmm_link_get_offset_up/dn` reported the raised value, the setters + stored whatever they were handed, and `swmm_link_set_xsect` left `y_bot` stale on a live edit — while + the `.inp` and GeoPackage writers subtract the sediment depth unconditionally, so a GUI edit of such a + conduit saved offsets shifted by `yBot`. The getters and setters now remove / add the bump + (`link::filledCircularOffsetBump`; zero in the BUILDING state so `swmm_finalize_model` bumps exactly + once), `swmm_link_set_xsect` re-bases the stored offsets on every exit and derives a filled section + through `xsect::setParams` like the resolver does, and `swmm_conduit_split` stores an authored 0 at + the new junction. `test_engine_filled_circular_offset_api`. +- **The control-action log and the 2D marcher's telemetry no longer grow without bound.** With + `[REPORT] CONTROLS YES` every numeric control action pushed an entry carrying a heap string for the + whole run; entries are POD now (rule names interned by index), capped at 1 000 000 with the overflow + counted at the end of the report's *Control Actions Taken* block. `ExplicitInertialSolver` kept a + `(t, active cells)` sample per rebuild only to fold min / mean / max at `run_stats()`; it folds as it + samples and keeps the vector only when `OPENSWMM_2D_MARCHER_TELEMETRY` names a CSV. + +### Changed + +- **Host-reserved threads count toward oversubscription.** `OPENSWMM_HOST_RESERVED_THREADS` (the GUI + exports 3: its main, render and engine-IO threads) is added to the requested team before the + logical-CPU comparison, so a `THREADS 8` deck run inside the GUI on a 10-CPU machine takes the + passive-wait path instead of spinning eight workers against the render thread; the oversubscription + warning names the reserved count. `kmp_set_blocktime(INT_MAX)` is skipped when the host pre-set + `KMP_BLOCKTIME`, which the old comment promised but the runtime call ignored. `test_thread_info`. + +## [6.0.0-alpha.4] — 2026-09-08 + +### Fixed + +- **2D marcher performance regression after the tri-quad / FULL_SWE work** (`plans/2D_PERF_REGRESSION_DIAGNOSIS_2026-09-07.md`). + LOCAL_INERTIAL results are byte-identical before and after; measured on the Bellinge storm slice the + LI cell pass had grown ~17 % and start-up ~0.3 s. Fixes: `MeshData::n_quads()` (an O(n_cells) scan) was + re-run at the top of every face-tier fire — now resolved once in `initialize()`; the FULL_SWE momentum + code is compiled out of the LI/DW cell kernel (`fireCellsImpl`), and the quad VFR Newton is kept + out of line so `cellEtaDepth` inlines into the cell kernels again; species booking is skipped without + species; `buildCouplingPoints` uses a vertex→cell map instead of an O(n_couplings × n_cells) scan. + FULL_SWE / DIFFUSIVE_WAVE: the front-rebuild halo and frontier sweeps are cell-parallel instead of + serial edge passes (the tier pull-down stays serial — Gauss-Seidel propagates further per pass than a + Jacobi form, and the difference moves DIFFUSIVE_WAVE results); `FRONT_REBUILD AUTO` is on for FULL_SWE + only (a diffusive front never breaches the 1-ring halo within the 4-cycle cadence) — a DIFFUSIVE_WAVE + deck that wants the old cadence sets `FRONT_REBUILD YES` and is byte-identical again; dry-dry faces + leave the FULL_SWE face pass + early; WALL mirror fluxes come from a per-cell CSR built once instead of a neighbour scan on every wet + cell; the RK2 step allocates nothing and averages in parallel; the diffusive law reads a precomputed + `n_face`. `THREADS 0` now applies the Apple P-core clamp to the 2D marcher as it already did to dynamic + wave. Nothing changes for the Kokkos plugin (still all-triangle LOCAL_INERTIAL only). +- **2D `FULL_SWE`: a prescribed-discharge boundary now delivers exactly what it prescribes.** The + ghost-cell Riemann boundary returned the Riemann solver's own mass flux — a wave-speed-weighted + blend of the interior and prescribed states — so a `SPECIFIED_FLOW` / `RATING_CURVE` inlet + under-delivered (measured 9 %, 7 % and 21 % short on the SWASHES subcritical, transcritical and + shock bumps) and, at a supercritical inlet, ran backwards. The prescribed discharge is now the + mass flux verbatim, as the local-inertial law has always done; the ghost state supplies only the + momentum flux, and its depth follows the outgoing Riemann invariant on a subcritical inflow + (critical depth into a dry cell, interior depth otherwise). `NORMAL_FLOW` under `FULL_SWE` applies + the same Manning outlet law as the other closures instead of a zero-gradient ghost, which was + absorbing and drained a pond through an inert (zero-slope) outlet. Boundary momentum is rescaled + when the availability clamp shrinks the mass, and `settleAccumulators` now settles the momentum + accumulators with the mass, so a cell re-tiered between firings cannot strand or replay them. + SWASHES depth error: bump-shock 0.070 → 0.032 (gate 0.05), bump-transcritical 0.042 → 0.033. + All-triangle `LOCAL_INERTIAL` results are unchanged (byte-identical on four decks). + +### Added + +- **2D: `swmm_2d_get_run_stats` C API / `Surface2D.run_stats`** — the solver backend label, momentum + closure, configured `LTS_TIERS`, cumulative substeps and face-kernel evaluations, active-cell fractions + and per-tier LTS occupancy, readable while the run is in flight. The report and the warning callback + carry a `2D solver: …` advisory naming the backend and closure, and the Kokkos-plugin refusal for quad + meshes / non-`LOCAL_INERTIAL` closures is now printed under `BACKEND AUTO` too (a `DIFFUSIVE_WAVE` deck + used to fall back silently and read as a slowdown). `bookFaceSpecies` returns early on species-free models. +- **2D: momentum closures `MOMENTUM_EQUATION FULL_SWE | DIFFUSIVE_WAVE` and mixed + triangle/quadrilateral meshes `[2D_QUADS]`** (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md, + plans/2D_TRI_QUAD_MESH_PLAN_2026-09-06.md; handoff plans/HANDOFF_2D_TRIQUAD_FULLSWE_2026-09-06.md). + - `FULL_SWE`: conservative shallow-water equations with the convective term on the same explicit + marcher — cell (h, hu, hv), hydrostatic reconstruction, rotated HLLC Riemann flux with the + Audusse bed-slope correction (lake at rest exact, walls included), ghost-cell Riemann boundaries, + semi-implicit friction; `RECONSTRUCTION_ORDER 2` = MUSCL (Barth–Jespersen) + SSP-RK2 in global-dt + mode. SWASHES strips: Stoker 6.5 % → 0.7 % (0.3 % second order), Ritter 13 % → 1.7 %, subcritical + bump 6.8 % → 0.5 %, transcritical bump 27 % → 4.4 %, bump-with-shock 12 % → 7.3 %. + - `DIFFUSIVE_WAVE`: explicit Manning quasi-steady face law (Hunter et al. 2005) with the Δx² + step bound per cell absorbed by the LTS tiers. + - `FRONT_REBUILD AUTO|YES|NO`: breach-triggered active-set rebuild with a five-ring halo and + front-cadence tiers for dry halo cells (AUTO = on for the new closures, off for local-inertial). + - `[2D_QUADS]` convex quadrilateral cells (cells numbered triangles first, then quads; unified + edge rule `edge k = (v[(k+1)%nv], v[(k+2)%nv])`), padded stride-4 `MeshData` layout, quad + geometry (shoelace area, area centroid), Begnudelli & Sanders (2007) quad VFR closure + (`mesh/QuadVfr.hpp`, verified against a brute-force integration oracle), `β/nv` positivity + share, GeoPackage `mesh_2d_quads`, UGRID mixed-topology HDF5 output (`Mesh2_face_nodes [n,4]` + + `_FillValue` + `Mesh2_face_nv`), C API `swmm_2d_cell_count / quad_count / edge_stride / + cell_vertex_count / cell_get_vertices / cell_get_neighbours`, Python mirrors. + - All-triangle LOCAL_INERTIAL models are byte-identical (verified on four decks: `.h5` datasets, + `.out`, `.rpt`); the SWASHES harness gains the `2d-swe`, `2d-swe2`, `2d-dw` columns. + - `ADVECTION YES` is deprecated (warns on load; still honoured). The Kokkos plugin serves only + all-triangle LOCAL_INERTIAL models and hands everything else to the CPU marcher with a notice. + +- **Street inlets: legacy-parity HEC-22 capture kernel, `[INLET_JUNCTIONS]`, and an inlet + design/usage C API** — `[INLETS]` / `[INLET_USAGE]` were parsed, but the street geometry never + reached the capture calculation and capture ran after routing: + - `[INLET_JUNCTIONS]` and the inlet-junction node: a virtual junction (zero storage, exactly two + STREET conduits of the same section) that is *unsealed* — it floods above the street section + or its `MaxDepth` — and captures the arriving gutter flow to a capture node, with backflow when + that node surcharges. `Name Elev MaxDepth Inlet CaptureNode (#Inlets %Clog Qmax aLocal wLocal + Placement)`, written after `[VIRTUAL_JUNCTIONS]` and excluded from `[JUNCTIONS]` / + `[VIRTUAL_JUNCTIONS]`. Errors 623 (host conduits are not streets), 625 (unknown design), + 627 (capture node missing, the host itself, or virtual), 629 (`[INLET_USAGE]` row on an + inlet-junction conduit), 631 (extra tokens), 633 (inlet junction without a usage row); + warning 635 (design incompatible with the host section — legacy WARNING 12, row ignored). + - C API: `SWMM_InletDesign` with `swmm_inlet_get_design` / `set_design` / `get_comment` / + `set_comment`; `SWMM_InletUsage` with `swmm_inlet_usage_count` / `find_link` / `find_node` / + `get` / `set` / `remove`; `swmm_node_is_inlet` / `inlet_eligible` / `set_inlet`; + `swmm_conduit_split_inlet` (atomic split of a street conduit inserting an inlet junction) and + `swmm_inlet_junction_fuse`. Python: `Inlets.get_design` / `set_design`, `InletUsages`, + `Node.is_inlet`, `inlet_rule_violation`, `split_conduit_inlet`, `fuse_inlet_junction`, enums + `InletType` / `GrateType` / `ThroatType` / `InletCurveKind` / `InletPlacement` / + `InletHostKind` (`python/tests/engine/test_inlet_api.py`). + - HEC-22 kernel ported 1:1 from legacy `inlet.c` (on-grade grate / curb / slotted / combination + sweeper, on-sag weir-orifice, custom curves, drop inlets), run at the end of lateral-inflow + assembly — before routing, as legacy does — for conduit- and node-hosted inlets alike. + Report: legacy "Street Flow Summary" plus a "Street Inlet Flow Summary" with the legacy + performance columns (node hosts as `NAME (node)`). Example + `examples/inlets/street_inlet_junction.inp`; parity set `tests/parity/inlets/` (EPA 5.2 inlet + decks through both engines: capture efficiency at peak identical on every on-grade / on-sag + deck and physical captured volumes identical; the attributed divergences are listed in its + README). (`test_engine_inlet_capture`, `test_engine_inlet_junction_io`.) + - `swmm_model_write_compat(engine, path, SWMM_INP_PROFILE_SWMM5)` — the SWMM 5.x write + profile (MULTI_ENGINE plan V2 Phase 4): v6-only sections (`[VIRTUAL_JUNCTIONS]`, + `[INLET_JUNCTIONS]`, `[2D_*]`, `[PLUGINS]`, `[PROCESS_COMPONENTS]`, `[USER_FLAGS]`, + `[USER_FLAG_VALUES]`, `[RDII_DECAY]`) and option keys are omitted, `FLOW_ROUTING FV` is + written as `DYNWAVE`, `SURCHARGE_METHOD DYNAMIC_SLOT` / `TPA` as `SLOT`, a virtual junction + becomes an ordinary junction and an inlet junction an ordinary junction plus an + `[INLET_USAGE]` row on its approach conduit; every substitution is reported as a warning + and the file opens with a comment naming the profile. GeoPackage gains `streets`, + `inlets` and `inlet_usage` tables so street models and both inlet grammars round-trip + (files written before the tables existed read as before). Inlet junctions are refused + under `FLOW_ROUTING FV` (error 619): the FV mesh splices virtual junctions out and would + drop the inlet. + +- **GUI-editor round-trip API for `[GWF]` expressions** — a subcatchment's custom groundwater + flow expressions were reachable only through the stringly-typed `swmm_options_get/set_ext` + key `"GWF::LATERAL|DEEP"`, with no validator: + - `SWMM_GwfType` (`LATERAL`, `DEEP`) with `swmm_subcatch_get_gwf_expression` / + `_set_gwf_expression` (NULL/empty clears; stored as typed, pre-start-only). + - `swmm_gwf_validate_expression` — grammar-only, never mutates the engine (peer of + `swmm_treatment_validate_expression`): unknown characters and identifiers, unbalanced + parentheses, misplaced operators and wrong `min`/`max` arity are errors, with a 0-based + column; an empty expression is invalid. + - Vocabulary for completers: `swmm_gwf_variable_count/name/description` (the 11 `GW_VAR_NAMES`) + and `swmm_gwf_function_count/name` (the 21 `MathExpr` functions, enumerator order). + - Parser leniencies matched to the editor: `[GWF]` accepts the legacy `LAT` abbreviation and a + subcatchment name in any case (the stored key uses the `[SUBCATCHMENTS]` spelling), and a + malformed expression is now **ERROR 233** at open and at `initialize()` instead of being + silently dropped (unknown identifiers previously evaluated to 0.0). + - Python: `GwfType`, `Subcatchments.get/set_gwf_expression`, `validate_gwf_expression`, + `gwf_variables()`, `gwf_functions()` with `.pyi` stubs. (`test_engine_gwf_api`.) + +- **Live `.out` reading.** `swmm_output_open_live(path)` opens a binary + output file that is still being written (or that never got its closing + records): offsets come from a forward parse of the header and the period + count from the file size, whole records only. `swmm_output_refresh` + re-counts on demand and adopts the footer when it appears; + `swmm_output_is_live` reports the state. Both writers — the 6.x + `DefaultOutputPlugin` and the legacy 5.3.0 `output_saveResults` — now + `fflush` after every report period so a tailing reader sees each period + as it completes. File format unchanged; `swmm_output_open` untouched. + (`OutputReader::openLive/refresh`, `test_engine_output_reader_live`.) + +- **Per-cell cumulative rainfall volume in the 2D sidecar.** New + `/Mesh2_face_rain_cum` `[nTime, nFace]` dataset (m³) alongside the existing + `/Mesh2_face_rainfall` intensity. Booked in + `SurfaceRouter2D::accumulateMassBalance` from the same per-cell term that + feeds `mass_balance_2d/rainfall_in`, so the sum over cells equals the + ledger by construction (`SurfaceRouter2D::rainCumulative`, + `SimulationSnapshot::surface_rain_cum`). C API bulk getters + `swmm_2d_get_rainfall_bulk` / `swmm_2d_get_rain_volume_bulk` expose the + two fields to in-process consumers (GUI live plotting). + +- **`TEMP` in reaction expressions — temperature-dependent kinetics.** + Multispecies rate/equilibrium/formula expressions can reference the + local water temperature (°C) as the hydraulic variable `TEMP`, enabling + Arrhenius-style corrections such as `theta ^ (TEMP - 20)`. Under + `HEAT_TRANSPORT` each element evaluates at its own transported + temperature (per cell on the Eulerian ARD mesh, per segment under LARD, + per link/node under the legacy router); without heat transport the new + `[REACTION_OPTIONS] TEMPERATURE` constant applies (default 20 °C, any + finite value accepted, exposed through `swmm_reaction_option_get/set` + and `solver.reactions.get_option/set_option`). The GUI expression + completer picks the variable up automatically from the shared + vocabulary API. + +- **Components write their own config files — API and GUI edits survive a + save (IO3a).** `swmm_model_write` emitted the `[PROCESS_COMPONENTS]` + `config=` path and copied the file the model was read from; nothing + rewrote its content, so every edit made through a C API or the GUI — a + `[HEAT_SOURCES]` temperature, a reaction expression — was silently lost + on save while a hand-edit persisted. A new `ComponentConfigSave` hook + (the inverse of `ComponentConfigApply`; empty return = decline → the + carry-alongside copy still runs) lets components adopt saving one at a + time with no intermediate state losing data. Heat and reactions adopt + here; water age and ARD still decline (IO3c — their configs are + unit-bearing: age stores seconds against a file in hours, so their + serializers need a fixed-point round-trip gate heat never needed). `saveHeatConfig` writes + only what the model actually set. IO3b (same release) extended the heat + renderer to all five sections — `[RADIATIVE_FLUXES]` (all three SHORTWAVE + spellings, with the TIMESERIES index mapped back to its series name), + `[SOLAR_RADIATION]` and `[CLOUD_COVER]` — so heat edits survive a save on + EVERY model, and the IO3a decline guard is deleted in favour of + structural `sizeof` pins: growing any of the three config structs now + breaks the build beside the renderer instead of silently reopening the + loss. Found en route: the renderer's first spelling of the + longwave-reflection key (`LW_REFLECTION`) is one the parser refuses + (`ATM_LW_REFLECTION`) — caught by the new field-by-field round-trip gate + before it shipped. + +- **Python bindings for the five transport-process headers.** `solver.heat`, + `solver.reactions`, `solver.water_age`, `solver.initial_quality` and + `solver.process_components` bind `openswmm_heat.h`, + `openswmm_reactions.h`, `openswmm_water_age.h`, + `openswmm_initial_quality.h` and `openswmm_process_components.h` as + keyed, iterable Python views rather than index-and-out-pointer calls: + flux-module and `[RADIATIVE_FLUXES]`/`[SOLAR_RADIATION]`/`[CLOUD_COVER]` + mappings plus the `[HEAT_SOURCES]` table with node overrides; species, + coefficients, terms, per-scope expressions and the whole-file `.rxn` + text surface; the `[WATER_AGE_SOURCES]` globals and overrides; the + `[INITIAL_QUALITY]` rows; and the `[PROCESS_COMPONENTS]` registry. + + The bindings refuse exactly what the C API refuses, so the constraints + that matter survive the language boundary rather than being re-derived + on the Python side: heat values are refused rather than clamped and + `COMPUTED` shortwave still demands an explicit latitude and longitude; + reaction mutation stays eagerly validated and transactional, so a stored + system is never uncompilable and `serialize -> apply_text -> serialize` + is byte-identical; water-age hours stay **signed**, because a negative + source age extracts age-volume by design; and `Reactions`' + hydraulic-variable and function tables are exposed as engine-less + `staticmethod`s so a completer enumerates the compiler's own vocabulary + instead of carrying a copy of it. + + Nine enums land with them — `HeatFluxModule`, `HeatShortwaveMode`, + `HeatRadiativeParam`, `HeatSolarParam`, `HeatCloudParam`, + `HeatSourceKind`, `WaterAgeSource`, `ReactionScope` and + `ReactionExprForm` — each mirroring its C counterpart's numbering, and + each accepted anywhere the corresponding `int` or token string is. + +- **Preissmann slot readers and 2-D name/bulk accessors.** `Link.slot_volume` + reports the water standing above the pipe crown, and + `LinkStatsView.peak_slot_share` / `LinkStatsView.slot_share` report the + peak instantaneous and run-level slot fraction — the latter a ratio of + time integrals, never an average of instantaneous ratios. All three are + finite-volume-routing only and read `0.0` under dynamic wave. + `Surface2D` gains `set_vertex_z_bulk` (one mesh rescan instead of one + per vertex) and the three read-back companions the boundary-condition + setters had been missing: `get_edge_bc_tseries_name`, + `get_edge_bc_flow_tseries_name` and `get_edge_bc_rating_curve_name`, + each returning `""` for a clear slot so a round trip through an editor + no longer has to remember what it wrote. + +- **C/Python/MCP parity matrix at zero gaps in all three columns.** Of + 1016 C symbols, 992 are at parity and the remaining 24 are + documented-intentional exclusions — the first time the matrix has been + clean across the C, Python and MCP columns simultaneously. + +- **Heat transport H6a — incoming shortwave forcing.** `[RADIATIVE_FLUXES] + SHORTWAVE` now takes three mutually exclusive spellings instead of one + constant: a fixed W/m², `TIMESERIES ` for a measured record, or + `COMPUTED` for a Spencer/NOAA solar position driving a Bird & Hulstrom + (1981) clear-sky model. New `[SOLAR_RADIATION]` (site coordinates, + timezone, elevation, Bird atmosphere) and `[CLOUD_COVER]` (fraction, + constant or timeseries) sections in `model.heat`, plus the new public + header `openswmm_heat.h` — the surface GUI task G4g was blocked on. + The header also carries the `[HEAT_SOURCES]` inlet-temperature table + (step 3): per-source GLOBAL read/write with a configured-vs-default + distinction, NODE-override enumeration and CRUD, and an effective-value + resolver that delegates to the engine's own precedence. The API refuses + exactly what the parser refuses — including NaN/inf, a hole the + pre-existing `[RADIATIVE_FLUXES]` fraction guard had and which is now + closed. ⚠ API edits to a component config do not yet survive + `swmm_model_write` (no per-component serialization until IO3) — pinned + by a gate rather than left to be discovered. + + Cloud fraction modulates **both** directions: it attenuates shortwave + (Kasten–Czeplak `1 − k C^n`) and raises atmospheric emissivity in the + longwave (Bolz `1 + k_lw C²`). Clear sky is bit-identical to H3, not + merely close — the cloud factor is a literal `1.0` that + `atmosphericEmissivity` short-circuits, so the RHE-gated Brunt path is + the same object code it was validated as. + + Three refusals worth knowing about, each chosen over a silent fallback: + configuring two SHORTWAVE spellings is an error rather than a precedence + ladder; `COMPUTED` without `LATITUDE`/`LONGITUDE` is an error rather than + a fallback onto the `[TEMPERATURE]` SNOWMELT latitude (which defaults to + 0 and would model equatorial noon); and out-of-range values are refused + rather than clamped, identically in the parser and the C API. + + **Solar position is Spencer/NOAA (~0.1°), not NREL SPA (±0.0003°).** The + plan originally specified SPA; implementing it faithfully needs ~260 rows + of periodic-term constants that would have been transcribed from memory + alongside the test vector meant to check them. `solarPosition()` is the + swap point for landing SPA later, against its published source. See + `HEAT_TRANSPORT_PLAN.md` §2.5 and D-H6a-4. + +### Performance + +- **FV published node stages no longer stand above the conduits they connect.** + The face-consistent stage reconstruction covered only degree-2 pass-through + junctions -- the set the solver splices -- so on a branching network most + nodes published the solver's own head. Measured on `Example1.inp` under + `FLOW_ROUTING FV` at `FV_MIN_CELLS 1`, where a conduit is a single cell and + the comparison is exact, those nodes sat up to **0.91 ft above their own + adjacent cell**, falling ~first-order under refinement -- a datum term, not + physics. It survives on nodes with no lateral inflow at all, which rules out + "head needed to drive the inflow out". + + The reconstruction now covers storage-less clean junctions at any degree. + Two guards make that safe: a face perched ABOVE the node's own water surface + is a free overfall and does not vote (without this, a conduit entering 4 ft + above the invert read its offset as node depth and drove one junction's + reported average from 0.28 ft to 4.11 ft), and a pondable junction demoted to + the bucket path above its rim keeps its volume-ledger head. + + Culvert-inlet and flap-gate faces are excluded: those node heads are genuine + headwaters. Storage units, outfalls and structure-fed nodes are unchanged. + + After: max +0.0002 ft and -0.0001 ft on the two affected classes. **Routing is + untouched** -- continuity identical and the Link Flow Summary byte-identical. + Reporting only, on purpose: solver-internal heads double as ghost boundary + states under LTS tier holds. Probe and full measurements in + `tests/manual/fv_node_stage/`. + +- **`FV_CFL_CENSUS_INTERVAL` now does what it says; it was inert for every + value.** The explicit FV solver conflated two quantities in one member: the + step the last accepted substep took, and the Courant bound the last census + returned. The substep tail wrote the taken step — clamped to the time + remaining in the routing step, so possibly a tiny fragment — into that + member and then zeroed the census countdown to undo the damage, which forced + a full face census on every substep no matter what the option was set to. + + The two are now separate. The bound survives a skipped census, which is the + entire point of the option, and only a genuine invalidation resets the + countdown: a retry (the post-step census having proved the bound + inadmissible), a rebuild of the active face lists, a re-tier's accumulator + settle, and both macro-cycle exits. A clamp to the routing-step boundary + proves nothing about the Courant bound and is no longer written back. + + At the default of 1 this is bit-identical — verified, not asserted: + `Example1.inp` under `FLOW_ROUTING FV` produces a byte-identical `.out` at + `OMP_NUM_THREADS` 1 and 8 against the same build with the change reverted. + +- **Dropped the write-only `f_scale_` face array from the explicit FV solver.** + Written at four sites (`initialize`, `computeFaceFlux`, `limitPositivity`, + `fireFaces`) and read nowhere in the repository. + +- **Model load and initialization: up to 17× faster, and the wall-clock window + before the first routing step cut on every model size.** A user reported 25 + minutes between clicking Run and the analysis starting on a large model; that + window is `open()` + `initialize()` + `start()`, and none of it was + instrumented. See `plans/MODEL_LOAD_OPTIMIZATION_RESULTS_2026-08-13.md` for + the full measured breakdown, including the four plan predictions that + measurement disproved. + + Measured in Release, medians of 5, one process per model: + + | Model | before | after | + |---|---:|---:| + | 100k-conduit FV model, `open+initialize` | 8047 ms | 466 ms (**17.3×**) | + | 500 timeseries × 10k rows, `open` | 7213 ms | 2571 ms (**2.81×**) | + | 10k rain gages, `open` | 335 ms | 49 ms (**6.90×**) | + | 50k STREET conduits, `open` | 448 ms | 159 ms (**2.83×**) | + | 100k nodes + inflows with `REPORT INPUT YES`, full | 2550 ms | 897 ms (**2.84×**) | + | 500k nodes/links with geometry, `open` | 3553 ms | 2482 ms (**1.43×**) | + + Peak RSS also falls: −35% on the STREET model, −17% on the 500k model. + + The individual fixes: a case-insensitive hash index over the timeseries/curve + store (it was a linear scan called once per data row while parsing + `[TIMESERIES]`/`[CURVES]`); memoized STREET/CUSTOM transect tabulation (one + ~1.3 KB table per street instead of one per link); a one-pass node-inflow + prepass in the `REPORT INPUT YES` summary (was O(nodes × inflow rows)); + memoized finite-volume per-conduit geometry tabulation (~5,000 closure + evaluations per conduit, for a result that depends only on the cross-section); + reserved SoA capacity and token vectors during parsing; an allocation-free + `;; UNITS:` prescan; a 1 MB buffer on the binary `.out` stream; and + file-size-derived reserves for external FILE-backed timeseries in place of a + flat 100,000-row allocation each. + + All of it is bit-identical: every change was gated on a parity check + comparing the `.rpt` (timing lines masked), the `.out` byte for byte, and the + written-back `.inp`, across six models covering STREET, IRREGULAR, FV, + storage and quality. + +### Added + +- **MSX species ride LARD segments and react — L3, the last unstarted + quality step.** A reactions component under `QUALITY_SOLVER LAGRANGIAN` + used to warn "the LARD reaction binding is not implemented (deferred + L3)" while every species sat at its initial value — and the species did + not ride the segments at all (the row layout was pollutants + age + + temperature; the LEGACY engine does not transport them either — only + ARD did). The segment store now carries the compiled species table + after the reserved rows: they mix, pass through, release, seed and + publish like every other row, and a new stage after DECAY integrates + them through the shared reaction integrator — per segment at pipe + scope with the segment's own pollutant rows as expression context, per + node store at tank scope with the node's HRT. The deferral warning is + gone; treatment remains the one LARD bypass. Cross-engine: the same + RATE-production deck reads 85.46 under LARD segments where ARD cells + read 87.64 — ratio 0.9751, two independent discretisations within + 2.5 %. A model with no reactions component is byte-identical to before + (the corpus is the witness). + +- **Water age and ARD write their own config files — IO3 save is complete + (IO3c).** The last two decliners of the `ComponentConfigSave` hook adopt + it: every registered component now renders its own config on save. + `swmm_water_age_save`'s writer became the shared + `serializeWaterAgeConfig` (one spelling for `[WATER_AGE_SOURCES]`, + upgraded from `%g` to shortest-exact — the config stores seconds against + a file in hours, and a rounding formatter drifts the model every save; + the new gate pins exact round-trips and a byte-stable fixed point by + generation two). ARD renders `[TRANSPORT_OPTIONS]`, + `[CONDUIT_DISPERSION]` and the raw boundary/source rows; + `SCALAR_SCHEME`/`LIMITER` ride new provenance flags — they alias + `[OPTIONS]` FV keys the writer only emits under FLOW_ROUTING FV, so on + a DYNWAVE deck the component file is the only carrier of that state: + the renderer re-emits the alias (at the current live value) exactly + when the file originally spelled it, and never invents one. Found en + route: the IO3a **render** path silently replaced a different + pre-existing config at the save destination where the copy path + announces it — the render path now carries the same + announce-on-replace contract. + +### Fixed + +- **Street inlets** — `[INLETS]` two-line combination inlets were not merged, the curb throat + angle and custom capture curves were dropped, on-sag capture never ran, street geometry never + reached the capture calculation, and capture was applied after the routing step (so the router + never saw it); splitting a STREET conduit lost the lower half's street reference + (`vj_split_conduit` now copies the named cross-section). An `[INLET_USAGE]` row naming a capture + node declared later in the file (legacy parsing is order-independent) is deferred to the + post-parse pass instead of failing the open with ERROR 209, and the inlet summary's "Peak Flow" + column is the peak approach flow, as in legacy, not the peak captured flow. The Node Inflow + Summary's lateral-inflow statistics keep their sign as legacy `stats.c` does (an inlet's bypass + node shows the transfer as a negative lateral); they were accumulated as absolute values. + +- **DUMMY links are routed under `FLOW_ROUTING FV` instead of failing the + model.** A DUMMY conduit carries no cross-section, so the FV mesh builder + rejected it as unmeshable (`y_full <= 0`) and the run aborted — DUMMY links + are common in real models. They are now excluded from the mesh and routed as + pass-throughs, the way `isTrueConduit` (`dynwave.c:411-414`) excludes them + from the DW momentum solve and `findNonConduitFlow` passes the upstream + node's inflow straight through. + + The discharge could not simply reuse the existing DUMMY branch of + `computeNonConduitFlowOne`: that reads `ctx.nodes.inflow`, which under FV + holds only laterals and structure scatter until `publishFv` writes the real + boundary fluxes at end of step, so a dummy fed by a conduit would have + carried a fraction of its true flow. `ExplicitFvSolver::refreshDummyFlows` + derives it instead as a drain condition on the upstream node — the net face + volume plus that node's lateral and structure forcing, evaluated per substep + against the same fluxes the node update is about to integrate. This + reproduces DW's continuity exactly: `Q = inflow + overflow` booked as + outflow leaves `dV/dt = 0`, making the node a free-drainage boundary rather + than a storing junction. Both ends stay pinned to LTS tier 0, so the + source/sink pair integrates over one span and the transfer is conservative. + (`NetworkMeshBuilder` `struct_is_dummy` / `node_dummy_drain`, + `FvStepForcing::link_q_cap` for the control setting and FLOW_LIMIT, + `Router::publishFv` for the step-mean discharge and the node ledger.) + +- **ERROR 134 — illegal DUMMY / ideal-pump connections — is enforced again.** + Legacy `checkDummyLinks` (`toposort.c:480-528`) and the degree test in + `validateGeneralLayout` (`flowrout.c:301-313`) were never ported + (`plans/FULL_GAP_ANALYSIS.md:618`). Both are what make a pass-through well + posed: its discharge is defined as everything arriving at the upstream node, + so it must be that node's only outlet — a second outlet has both links + claiming the whole inflow — and a node cannot both receive and emit one + without the two definitions becoming circular. A storage node's outlet may + not be a dummy (`link.c:1006-1014`). Enforced for DYNWAVE and FV, the two + models that implement the pass-through. No model in the regression corpus + (1,637 `.inp` files) is rejected by it. + +- **`.inp` writer emits authored form — offsets and conduit orientation.** + `resolve_cross_references` rewrites `LINK_OFFSETS ELEVATION` offsets and + weir/outlet crests as depths and reverses adverse-slope conduits (node1/ + node2, offsets, losses, InitFlow sign) for DYNWAVE/FV; `InpWriter` then + emitted both verbatim, so Open → Save wrote depths under an `ELEVATION` + header (clamped to 0 with WARNING 03 on the next open) and swapped From/To + on every adverse conduit. New `input::convert_internal_to_authored` (with + `needs_authored_conversion` / `restore_authored_orientation`) undoes both + on the writer's local copy, and `swmm_links_restore_authored_orientation` + lets an editing host hold the authored orientation in its live context. + Pinned by four new `InpWriterRoundTrip` cases on `authored_form.inp`. + +- **`[POLLUTANTS]` Kdecay was applied 86,400× too fast — and the common case + destroyed the pollutant with a 100 % continuity error, booked nowhere + (KD1).** The Kdecay column is 1/day; legacy divides by `SECperDAY` at parse + (`landuse.c`), but this engine used the raw value against dt-in-seconds at + every application site. Any deck with a plausible decay coefficient + (0.05–1/day BOD or coliform values) silently reported ~zero for that + pollutant: the linearized node factor `1 − k·dt` went negative, clamped to + zero, and the annihilated mass never reached the ledger. The parser now + stores 1/sec exactly as legacy does, and every file-unit boundary converts + back — INP writer, GeoPackage both directions (pre-KD1 `.gpkg` files stored + the deck value unconverted, the same unit, so both eras read correctly), + and the C API, whose header documented 1/day all along. Three more defects + fell out of making the new gates close: the legacy-path solver never booked + decayed mass into `qual_routing_reacted` (nodes, all three link branches, + and the reactions-active twin now book it); every node decayed where legacy + decays only storage nodes or nodes actually holding volume, so pass-through + junction flux picked up decay factors legacy never applies; and + `mixAtNodes`' evaporation factor inferred evaporation from any volume + decrease — true for every draining node — creating ~`c·v_out` of mass per + step at a draining storage whenever concentrations weren't uniform (the + `c_max` cap masked it on every k = 0 deck). It now uses the storage unit's + actual evaporation volume, `fEvap = 1 + vEvap/v1`, per legacy + `findStorageQual`. After all four: the k = 1/day differential probe reads + Mass Reacted 0.158 lbs vs legacy's 0.159, and k = 200/day books 8.455 vs + legacy's 8.523 with continuity at baseline. Known residual (both engines, + P2.4): per-step transit mass takes the decay factor outside any + volume-basis booking — legacy leaks 6.5–7 % on the same storage deck. + Triage + evidence: `plans/transport/KDECAY_UNITS_TRIAGE_2026-08-31.md`. + +- **The 2D results file now says what its coordinates mean.** `Mesh2_node_x/y` + and `Mesh2_face_x/y` have always been written in the solver's SI metres and + tagged `units = "m"`, but nothing in the file recorded the model's own CRS or + the factor applied to get there. A consumer of a model in a foot-based + projected CRS (EPSG:2249 and friends) reasonably read those metres as the + CRS's own unit and placed the results ~0.3048x toward the CRS origin, while + the `.2dm`-backed mesh — which never leaves model units — rendered correctly. + The file gains a scalar `/crs` variable carrying `model_crs` (verbatim from + `[OPTIONS] CRS`) and `metres_per_model_unit` (the factor + `SurfaceRouter2D::initialize` actually applied), referenced by a + `openswmm_crs = "crs"` attribute on `/Mesh2` and the coordinate variables. + Deliberately not spelled as CF `spatial_ref`/`crs_wkt`: a reader honouring + those would place metres in a foot CRS and reproduce the very offset the + variable exists to describe. Existing files are unaffected and stay readable; + they simply declare nothing. (Issue #155.) + +- **A malformed option value handed to `swmm_options_set` returns + `SWMM_ERR_BADPARAM` instead of killing the process.** Thirty of the + dispatch's key branches parsed with raw `std::stod`/`std::stoi`, which + throw on junk — and an exception crossing the C boundary is + `std::terminate`. The guard alone was also not sufficient: two + non-throwing families slipped through it — the lenient time parse + fabricated `0.0` from junk (`"1e999999"` read back as 3600 s), and + `std::stoi` accepted a numeric prefix (`"1.5"` read as 1). All parse + sites in the dispatch now use strict wrappers that consume the entire + token or reject, covered by an exhaustive malformed-value suite over + every settable key. Reachable from any API client, including the MCP + server passing through arbitrary text. (`d80bba34`.) + +- **The `OPENSWMM_PERF` FV phase split double-counted, and its parts could + exceed the whole.** `perf::GatedTimer` accumulated wall time, so a timed + phase that called another timed phase booked the child twice — once in the + child's accumulator and once inside its own. Three nestings exist: + `settleAccumulators` and `restoreState` both call `refreshDepths`, and the + boundary-flow callback sits inside the settle window. Two of the three are + local-time-stepping only, which is why the symptom appeared only on LTS runs: + `total` came out **larger than the routing `step` it is a breakdown of**, for + an "unattributed" share of **−16.2 %** on Example1 and **−19.0 %** on a + 500-conduit graded chain. That is not a quantity that can be negative, and a + breakdown whose parts exceed the whole cannot rank optimization targets — + the only reason the timers exist. + + Timers now book **self** time: a thread-local tally collects the wall time of + timers opening and closing inside the running one, and each timer subtracts it + before accumulating. Unattributed time is now **+3.5 % to +6.2 %** across the + same four runs. No call site changed, and with `OPENSWMM_PERF` unset the + destructor still returns before touching anything. + + The correction changes what the table recommends. `settle` read 2.255 s on the + graded chain — 18 % of the reported total — while its own work is 0.007 s; + effectively all of it was the two `refreshDepths()` calls already counted under + `refreshdepths`. `restore` was the same. The real target is `refreshDepths`, at + 33 % of total on that deck, and it was not legible before. Evidence and + reproduction: `tests/manual/fv_phase_timers/RESULTS.md`. + +### Changed + +- **Inlet `MIN_RUNOFF_FLOW` / `FUDGE` aligned with legacy** (`0.001` cfs / `0.0001`; both were + `2.5e-5`) — results change for any model with conduit inlets. Error codes 623–635 are new. + +- **Hydraulics Reference Manual §8.6 and §8.7 rewritten to describe the solver + that ships.** §8.6.1 documented junctions as `MIN_SURFAREA` linear reservoirs + integrated in time — the BUCKET model, removed when junctions became + interfaces. A plain junction has **no storage**: a clean degree-2 junction + passes its cells' states straight through, and every other storage-less + junction solves its head from an instantaneous flux balance, now written out + as equation (8-31). §8.6.5's step 3 and the option table still documented + `FV_NODE_CELL_COUPLING` and `FV_JUNCTION_MODEL`, both retired and + accept-and-ignore since the interface treatment landed. The node time-step + bound (8-32) is now stated to apply to bucket nodes only, which is what + `nodeStableDt` implements. + + Two gaps are also closed. The chapter said junction momentum is not conserved + without saying what that costs — roughly a millimetre of head per junction + from splitting one Riemann problem into two, integrating to a 0.23 m backwater + over a 199-junction subcritical chain, which is why the pass-through splice + exists. And §8.7 now documents the published node stage (8-33), reconstructed + from the incident wet cells rather than read off the solver's head; that rule + changed in the previous release and was undocumented. + + A new subsection also answers a recurring question directly: the node is not + given half of each connected link's volume, as dynamic wave does, because + under finite volume the end cells already hold that water as explicit state. + Booking it at the node too was measured twice and rejected twice, at ~0.3 % of + routing continuity and −0.005 % per junction. + +- **Relicensed from MIT to the Apache License, Version 2.0** (#123, #122). The + `LICENSE` file now carries the full Apache 2.0 text, retaining the addendum + that acknowledges the USEPA SWMM material residing in the public domain under + 17 USC § 105 — the Apache grant covers only the OpenSWMM authors' original + contributions and places no restriction on that public domain material. A new + `NOTICE` file records the required attribution and SWMM provenance. All + first-party source headers now carry the Apache 2.0 boilerplate and an + `SPDX-License-Identifier: Apache-2.0` tag in place of the previous MIT tags. + `CLA.md` (v1.1), `CONTRIBUTING.md`, `CITATION.cff`, `README.md`, the Python + bindings' `pyproject.toml` and the Sphinx license page were updated to match. + Built-in plugin metadata (`IPluginComponentInfo::license_type`) now reports + `"Apache-2.0"`. + +### Added + +- **Two-component pressure approach (TPA) — sub-atmospheric pressurized flow + in both hydraulic solvers.** (#156) The closure of Vasconcelos, Wright & Roe + (2006): a sealed full pipe may carry pressure below atmospheric instead of + spuriously reverting to free-surface geometry, governed by a physical + air-pathway regime flag with submergence-checked venting and a + column-separation floor at −30 ft of head. In the finite-volume solver, + `FV_PRESSURE_CLOSURE TPA` extends the existing slot line to both signs of + ΔA (`FV_SLOT_CELERITY` doubles as the acoustic celerity) and composes with + `FV_PRESSURIZED_IMPLICIT`; in the dynamic wave solver, `SURCHARGE_METHOD + TPA` adds a constant-width slot `w = g·A_full/a²` above the crown (new + `TPA_CELERITY` key, project units, default 100) with a per-conduit + sub-atmospheric latch below it, updated once per routing step so the Picard + iteration sees a fixed operator. Both default off and bit-inert when off. + Measured on the paper's laboratory cases: the FV closure carries 0.0398 m of + true vacuum below the crest invert of the negative-pressure siphon into the + `.out` file — still deepening when the deck reaches the 40 s validity + boundary it documents — where the slot closures floor at the invert; and + DW TPA's rapid-fill bore arrival lands within 2 % of the + FV timing where the Sjöberg slot is ~20 % early. Documented as Hydraulics + Reference Manual §8.4.5 and §3.3.11. One pinned known issue: explicit FV + TPA filling at a = 150 m/s diverges at the reflected surge (the paper's own + high-celerity post-shock frontier; gate + `FvTpa.KnownIssueHighCelerityFillingDiverges`). + +- **Unsteady friction (`UNSTEADY_FRICTION VITKOVSKY`, `UF_K3`) in both + hydraulic solvers.** (#156) The Pinto, Vasconcelos & Soares (2025) modified + Vítkovský term with regime-dependent celerity, orthogonal to the + pressurization closure: the local-acceleration half folds in + semi-implicitly (no new prognostic state — hotstart- and rollback-safe), + the convective half enters explicitly with a velocity dead-band and a + half-momentum clamp. The DW gradient uses a cross-link stencil (the + within-link difference is structurally zero on a full conduit), so DW + damping requires discretized reaches — a single-link reach gets added + inertia only. Default `NONE` is bit-identical to earlier releases. + Documented as §3.3.12 and §8.5.4 of the Hydraulics Reference Manual. + +- **`REPORT_SIGNED_HEADS` — true signed piezometric heads in the `.out` + file.** (#156) The binary output's NODE_HEAD has always been rebuilt from a + depth floored at zero, so sub-atmospheric heads were invisible. With + `REPORT_SIGNED_HEADS YES` the HEAD field carries the true signed head for + both solvers; DEPTH stays floored, and the default `NO` keeps legacy + bit-parity (measured: a never-negative DW deck differs only in + float32-rewrite ULPs, confined to HEAD). + +- **Virtual-junction initial-state seeding under dynamic wave routing.** + (#156) `[VIRTUAL_JUNCTIONS]` carries no initial-depth column, so VJs + started dry regardless of their neighbors — a deck whose real nodes define + an initial pool began with a hole at every splice. Each VJ head is now + seeded by distance-weighted interpolation between the nearest non-virtual + nodes along its spliced chain, requiring at least one wet endpoint (so a + dry deck cannot manufacture water). DYNWAVE only, and that restriction is + measured, not cautionary: seeding the node alone under FV contradicts the + uniform-depth cell seed and was measured to drive a pressurized study deck + from 0.000 % to −19 % continuity. Decks without VJs are bitwise untouched. + +- **A Lagrangian transport engine (LARD) joins the quality solvers.** + `QUALITY_SOLVER LAGRANGIAN` routes pollutants with a Lagrangian + advection–reaction–dispersion scheme in place of the legacy complete-mix + chain: plug-parcel advection on per-link segment stores, first-order + `KDECAY`, quality substepping under a `QUALITY_STEP` key, and random-walk + particle tracking for longitudinal dispersion (validated against the Elder + profile). Water age rides the same engine as a reserved species: `WATER_AGE + ON`, a `[WATER_AGE_SOURCES]` table for initial state and boundary ages, + `__WATER_AGE__` rows in `[INFLOWS]`, hotstart round-tripping of the aged + state (including dry elements), and age columns in the report and binary + output. Negative source loads now extract mass deliberately at the node + seam in all three quality engines — warned at parse, clamped to the mass + actually held, booked to the ledger, and summarised in the report — instead + of being silently dropped. The option and API surface lands with it: + transport keys in `swmm_options_set`/`_get`, and a C age-source table API + (`openswmm_water_age.h`). Configurations the LARD engine does not cover yet + (heat, MSX-style reactions, `[TREATMENT]`) announce themselves with bypass + warnings at open rather than failing silently. (`24602eb2`, `8c141a5e`, + `647a3603`, `b9852cee`, `9f155227`, `d79c8bcf`, `d7b6c079`, `948b2840`, + `4639be37`.) + +- **FV solver statistics in the report file, and `OPENSWMM_PERF` phase timers + for the FV step.** FV runs now emit an "FV Solver Statistics" block — + explicit substeps, face-flux evaluations, mean/min/last substep, active-face + occupancy and the LTS tier histogram. Setting `OPENSWMM_PERF=1` additionally + prints a `[PERF-FV]` line whose bracketed phases sum to `total`, beside the + whole-router `step`; the difference between them is unattributed time and is + meant to be read as a finding rather than smoothed away. + +- **`SWMM_FilePathRole` covers the remaining external-file slots.** Three new + roles — `SWMM_FILE_MESH_2D`, `SWMM_FILE_OUTPUT_2D` and `SWMM_FILE_LID_REPORT` — + let a host read the resolved and authored form of the 2D mesh reference, the 2D + output file, and per-unit LID report files through the same + `swmm_file_path_get` / `swmm_file_path_set` pair as every other slot. The 2D + roles return `SWMM_ERR_BADPARAM` in builds without 2D support. + +- **Model-load benchmark harness and parity gate.** + `OPENSWMM_PERF=1` now emits a `[PERF-LOAD]` line attributing the whole + open/initialize/start window across 20 phases (including a `read.scan` vs + `read.dispatch` split of parsing). + `tests/benchmarks/scripts/gen_load_bench.py` generates a deterministic + scaling corpus up to 500k elements (not committed — 500 MB — but reproducible + from the committed generator); `bench_model_load` times three cuts per model + and reports peak RSS; `parity_probe` + `tests/benchmarks/scripts/load_parity.sh` + compare `.rpt`/`.out`/write-back `.inp` between two builds. Two new ctest + gates run under `ctest -L unit`: `load_parity_selfcheck` (engine output is + deterministic) and `bench_corpus_generator_smoke`. + - **Per-triangle 2D initial conditions in the Python bindings.** `Surface2D.get_triangle_init_depth` / `set_triangle_init_depth` and `get_triangle_init_velocity` / `set_triangle_init_velocity`, wrapping @@ -209,6 +1790,84 @@ retroactive. ### Fixed +- **Groundwater was silently lost on every save.** `[AQUIFERS]`, `[GROUNDWATER]` + and `[GWF]` were parsed but had no writer, so a model that used groundwater + came back from a round trip with none of it. All three now round-trip. + `[GWF]` expressions are stored in `options.ext_options` under + `"GWF::"` and were being re-emitted through the `[OPTIONS]` + passthrough, which uppercased the key (breaking the lookup that reads them + back) and kept only the first value token (truncating any real expression); + those keys are now excluded from the passthrough and written as a real + `[GWF]` section. + +- **A `[GROUNDWATER]` receiving node declared later in the file never + resolved.** `[GROUNDWATER]` normally precedes `[JUNCTIONS]`, and + `handle_groundwater()` resolved the node eagerly with no deferred pass, so + the index stayed `-1`. This was a live runtime bug as well as a write bug: + groundwater fell back to the subcatchment's outlet node instead of the one + the model specified. The name is now captured for `PostParseResolver`. + +- **Links declared before the node sections loaded silently orphaned.** Legacy + parsing is order-independent, but `[CONDUITS]`/`[PUMPS]`/`[ORIFICES]`/ + `[WEIRS]`/`[OUTLETS]` resolved their end nodes eagerly, kept no name, and + were never retried — so an `.inp` whose link sections came first loaded with + `node1`/`node2` at `-1` and **no error at all**, and then saved with `*` in + the FromNode/ToNode columns. End-node names are now re-resolved after every + section is parsed. An end node that still will not resolve is a fatal + `ERROR 209`, matching legacy `link_readParams()`; such a model previously + loaded quietly and ran wrong. + +- **`[INLET_USAGE]` was parsed but never written.** Every inlet-to-link + assignment was lost on save, leaving the surviving `[STREETS]` and + `[INLETS]` definitions inert. + +- **Five writers emitted `*` where the name was known, three of them fatally.** + A subcatchment that drains to another subcatchment (or to itself) has no + outlet *node*, and the writer only ever consulted the node index — so the + Outlet column saved as `*` and the model would not reload + (`ERROR 209: undefined object *`). The RainGage column had the same defect + against a retained gage name, and a rain gage with neither a resolved series + index nor a file path wrote **no row at all**, which made the subcatchments + naming it fail to reload. Non-fatally, the Snowpack column dropped a retained + pack name, and `[PUMPS]` ignored `pump_curve_name` and wrote `*` — silently + downgrading a curved pump to IDEAL. Each of these now falls back to the + retained name before giving up. + +- **Four external-file slots were written to the `.inp` verbatim.** The writer + rebases every external reference against the destination directory, but the + external `.2dm` mesh, the 2D `OUTPUT_FILE` and per-unit LID report files never + went through that path. `SolverOptions2D::mesh_file`, `::output_file` and + `LidUsageStore::rpt_file` are now `FilePathPair`s registered with + `resolve_external_file_slots`, and all three emit through `emit_path_token` + like every other slot. `[PLUGINS]` paths remain absolute by design — they name + installed shared libraries, not model data. + +- **A `[2D_MESH_FILE]` reference dangled after Save As when the mesh had not + loaded.** External mode normally writes the in-memory mesh to a `.2dm` beside + the destination `.inp`, so the reference stays local and the mesh travels with + the model. When there was no mesh in memory — a missing or unreadable `.2dm`, + or a lenient (editor) open — nothing was written, yet the token was still + copied through unchanged, so it re-resolved against the *new* directory and the + saved model opened 1D-only with no diagnostic. That case now re-anchors against + the resolved source path. The loaded case is unchanged, and a new test pins + both halves, including that Save As never writes back over the source `.2dm`. + +- **`[TEMPERATURE]` climate file was opened against the process working + directory.** `SWMMEngine::initialize` passed `temp_file.original` — the token + as authored — to `ClimateFileReader::open`, so a relative reference resolved + against the CWD rather than the `.inp` directory. `open()` returns `false` on + failure and the return value was discarded, so the run continued with no + climate data: a clean-looking result with silently missing temperature and + evaporation. It now opens the resolved `.absolute` path and pushes a warning + when the file cannot be read or its format is not recognised. + +- **`swmm_options_set_ext(engine, "WRITE_ABSOLUTE_PATHS", …)` did not set the + option.** The key fell through to `ext_options`, where the writer never looks, + so the save still emitted relative paths — while re-emitting + `WRITE_ABSOLUTE_PATHS YES` into `[OPTIONS]`, meaning the deck reopened with the + opt-out armed and behaved differently from the save that produced it. The key + now writes `SimulationOptions::write_absolute_paths` directly. + - **`MIN_SURFAREA` was a project option the junction storage convention never read.** Legacy keeps no junction storage at all (`node_getVolume` returns `fullVolume*(d/fd)`, and `fullVolume` is 0 for a plain junction); this engine diff --git a/CITATION.cff b/CITATION.cff index de32a1fa3..393dbff4a 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -5,7 +5,8 @@ authors: given-names: "Caleb" orcid: "https://orcid.org/0000-0002-9859-2264" title: "Open-Source SWMM (SWMM2D): Reimagining the Stormwater Management Model for the Digital Water Transformation" -version: 6.0.0-alpha.3 +version: 6.0.0-alpha.4 doi: https://doi.org/10.1016/j.envsoft.2018.07.015 date-released: 2025-01-06 -url: "https://github.com/hydrocouple/openswmm.engine" \ No newline at end of file +url: "https://github.com/hydrocouple/openswmm.engine" +license: Apache-2.0 \ No newline at end of file diff --git a/CLA.md b/CLA.md index 387f1ed97..8338e4949 100644 --- a/CLA.md +++ b/CLA.md @@ -1,11 +1,13 @@ # Contributor License Agreement — openswmm.engine -**Version 1.0 — May 2026** +**Version 1.1 — August 2026** Thank you for your interest in contributing to **openswmm.engine**, maintained by the Technical Manager of the project (currently [@cbuahin](https://github.com/cbuahin)). This Contributor License Agreement ("CLA") clarifies the intellectual property rights granted with contributions to the project. By signing this CLA you confirm that you have the legal authority to grant these rights, and that the Technical Manager may rely on them. This CLA does **not** transfer your copyright to the Technical Manager. You retain full ownership of your contributions. The CLA grants a license that enables the project to be distributed, maintained, and relicensed in the future without requiring additional consent from every contributor. +The Project is currently distributed to the public under the **Apache License, Version 2.0** (see [LICENSE](./LICENSE)). Contributions accepted into the Project are made available under those terms, together with the attribution notices recorded in [NOTICE](./NOTICE). The relicensing right granted in Section 2 below operates in addition to, and does not revoke, that outbound license: anything already released under the Apache License, Version 2.0 stays available under it. + The Technical Manager role may transfer over time per the succession process described in [CONTRIBUTING.md §3](./CONTRIBUTING.md#3-succession--delegation). Rights granted under this CLA persist through any such transition and vest in whoever holds the Technical Manager role at the time they are exercised. --- @@ -24,7 +26,9 @@ The Technical Manager role may transfer over time per the succession process des Subject to the terms of this CLA, You hereby grant to the Technical Manager a **perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license** to: - reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works; -- **relicense** Your Contributions under any license, including but not limited to the GPLv3, LGPL, AGPL, MIT, or a commercial license, at the Technical Manager's sole discretion and without further notice to You. +- **relicense** Your Contributions under any license, including but not limited to the Apache License 2.0, GPLv3, LGPL, AGPL, MIT, or a commercial license, at the Technical Manager's sole discretion and without further notice to You. + +This grant is at least as broad as the copyright license in Section 2 of the Apache License, Version 2.0, so the Technical Manager may distribute Your Contributions under the Project's current outbound license without further action by You. The relicensing right is granted specifically to preserve the Technical Manager's ability to adapt the project's licensing terms over time (for example, to offer a dual open-source/commercial licensing model) without being required to seek individual consent from each contributor. @@ -34,7 +38,7 @@ The relicensing right is granted specifically to preserve the Technical Manager' Subject to the terms of this CLA, You hereby grant to the Technical Manager and to recipients of software distributed by the Technical Manager a **perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license** to make, have made, use, offer to sell, sell, import, and otherwise transfer Your Contributions, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution alone or by combination of Your Contribution with the Project. -If any entity institutes patent litigation against You or any other party alleging that Your Contribution constitutes patent infringement, any patent licenses granted to that entity under this CLA for that Contribution shall terminate as of the date such litigation is filed. +If any entity institutes patent litigation against You or any other party alleging that Your Contribution constitutes patent infringement, any patent licenses granted to that entity under this CLA for that Contribution shall terminate as of the date such litigation is filed. This Section mirrors the patent grant and defensive termination provisions of Section 3 of the Apache License, Version 2.0. --- @@ -50,7 +54,7 @@ By submitting a Contribution, You represent and warrant that: 1. **You are the author.** You are the sole author of the Contribution, or you have the legal right to submit it on behalf of all co-authors. 2. **You have authority to grant this license.** The license grant in Sections 2 and 3 does not violate any agreement you have with a third party, and no third party has any claim over your Contribution that would restrict the grant. -3. **Third-party content is disclosed.** If Your Contribution includes any third-party code, data, or assets, you have identified them clearly in the pull request description, confirmed their licenses are compatible with the Project's current license, and included all required attribution. +3. **Third-party content is disclosed.** If Your Contribution includes any third-party code, data, or assets, you have identified them clearly in the pull request description, confirmed their licenses are compatible with the Apache License, Version 2.0, and added any attribution those licenses require to [NOTICE](./NOTICE). 4. **Employer authorization.** If you are employed and your Contribution relates to your employer's business or was created using employer resources, your employer has either (a) authorized you to make this Contribution and granted the necessary rights, or (b) signed a Corporate CLA (see Section 6) covering this Contribution. --- @@ -123,4 +127,10 @@ Questions about this CLA should be directed to the Technical Manager via GitHub: --- -*This CLA is maintained by the Technical Manager of openswmm.engine (currently [@cbuahin](https://github.com/cbuahin)). Last updated: May 2026.* +## 13. Public Domain Material + +Portions of the Project are derived from USEPA SWMM software that resides in the public domain and for which domestic copyright protection is not available under 17 USC § 105. Nothing in this CLA asserts, or asks You to assert, copyright over that material. If Your Contribution modifies or extends public domain material, the licenses granted above apply only to Your own original changes; the underlying public domain material remains free of any such restriction. See [NOTICE](./NOTICE) for the full provenance statement. + +--- + +*This CLA is maintained by the Technical Manager of openswmm.engine (currently [@cbuahin](https://github.com/cbuahin)). Last updated: August 2026.* diff --git a/CMakeLists.txt b/CMakeLists.txt index ceaa831e4..8a7cbf83f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,7 +3,7 @@ # # Project: openswmm.engine # Description: Open Storm Water Management Model Engine -# Version: 6.0.0-alpha.3 (refactored engine) / 5.3.0-beta.3 (legacy engine wrapper) +# Version: 6.0.0-alpha.4 (refactored engine) / 5.3.0-beta.3 (legacy engine wrapper) # # This is the root CMake file for the openswmm.engine project which contains: # - openswmm_legacy_engine : Original EPA SWMM 5.x C solver (preserved unmodified) @@ -34,7 +34,7 @@ project( ) # Pre-release label for the refactored engine (e.g. "alpha.1", "beta.1", "rc.1"). Leave empty for a final release. -set(OPENSWMM_PRERELEASE "alpha.3" CACHE STRING "Pre-release tag for the refactored engine (e.g. alpha.1, beta.1, rc.1). Empty for a final release.") +set(OPENSWMM_PRERELEASE "alpha.4" CACHE STRING "Pre-release tag for the refactored engine (e.g. alpha.1, beta.1, rc.1). Empty for a final release.") # Legacy SWMM engine version (EPA SWMM 5.x lineage, independent of the OpenSWMM # Engine version). Single source of truth: src/legacy/engine/CMakeLists.txt @@ -95,9 +95,18 @@ option(OPENSWMM_BUILD_BENCHMARKS "Build Google Benchmark performance tests" OFF option(OPENSWMM_INSTALL "Install openswmm libraries" ON) option(OPENSWMM_BUILD_PYTHON "Build Python bindings" OFF) option(OPENSWMM_WITH_GEOPACKAGE "Build GeoPackage I/O library (requires sqlite3)" ON) +option(OPENSWMM_WITH_HDF5 "Build HDF5 model I/O (requires hdf5)" ON) option(OPENSWMM_BUILD_2D "Build optional 2D surface routing module (explicit local-inertial marcher; HDF5 output)" ON) option(OPENSWMM_BUILD_GPU_PLUGIN "Build the GPU/Kokkos surface-solver plugin (standalone, dlopen()ed at runtime — never linked into the core). ON by default: a from-source build gets the Kokkos-OpenMP plugin and runtime `auto` uses it (the `gpu` vcpkg feature is in default-features, supplying Kokkos). The portable base build/wheel turns this OFF explicitly and excludes the `gpu` feature (VCPKG_MANIFEST_NO_DEFAULT_FEATURES) to stay Kokkos-free; pip users get OpenMP via the separate `openswmm-gpu-omp` companion wheel. Backend selected via OPENSWMM_GPU_BACKEND (default omp)." ON) +# HC-1 (2026-09-27): the HydroCouple component layer. OFF by default — the +# engine has shipped without it and a from-source build should not suddenly +# acquire a git fetch. Program plan D-C1 puts ONE `integrated2d` component +# behind this (surface + two-zone groundwater + all transport, GW as capability +# toggles), D-C2 puts the wrappers in `src/couplers/`, and D-C6 restricts the +# dependency to the header-only interfaces — never `HydroCoupleSDK`. +option(OPENSWMM_WITH_HYDROCOUPLE "Build the HydroCouple component wrappers (src/couplers) — header-only interfaces only, no HydroCoupleSDK (D-C6)" OFF) + # OPENSWMM_BUILD_TESTS is a convenience flag that enables both unit and regression if(OPENSWMM_BUILD_TESTS) set(OPENSWMM_BUILD_UNIT_TESTS ON CACHE BOOL "" FORCE) @@ -227,10 +236,27 @@ function(openswmm_bundle_runtime_deps TARGET_NAME SUBDIR) # unresolved-deps warnings on Windows and never get included in the # cpack zip. Linux/macOS usually resolve them via rpath, but the extra # dir is harmless on those platforms. + # + # vcpkg's DEBUG binaries live in /debug/bin, not /bin, so + # both trees are captured and the install script picks the order by config + # (issue #9). Searching only the release tree left Debug installs broken in + # two different ways: + # + # - HDF5's debug DLLs carry a _D suffix (hdf5_D.dll, hdf5_hl_D.dll). The + # name in the import table has no match under bin/, so it surfaced as + # "unresolved runtime dep: hdf5_D.dll" and the installed exe died at + # startup with STATUS_DLL_NOT_FOUND (0xC0000135). + # - sqlite3's debug DLL keeps the release NAME, so it resolved happily — + # against the RELEASE copy, quietly mixing a release sqlite3 into a + # Debug package. That one never warned, which is why it looked fine. + # set(OPENSWMM_BUNDLE_EXTRA_DIRS "") + set(OPENSWMM_BUNDLE_EXTRA_DIRS_DEBUG "") if(DEFINED VCPKG_INSTALLED_DIR AND DEFINED VCPKG_TARGET_TRIPLET) list(APPEND OPENSWMM_BUNDLE_EXTRA_DIRS "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/bin") + list(APPEND OPENSWMM_BUNDLE_EXTRA_DIRS_DEBUG + "${VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}/debug/bin") elseif(DEFINED ENV{VCPKG_ROOT}) # Fallback: use the env-var-rooted classic-mode layout. set(_triplet "${VCPKG_TARGET_TRIPLET}") @@ -240,6 +266,8 @@ function(openswmm_bundle_runtime_deps TARGET_NAME SUBDIR) if(_triplet) list(APPEND OPENSWMM_BUNDLE_EXTRA_DIRS "$ENV{VCPKG_ROOT}/installed/${_triplet}/bin") + list(APPEND OPENSWMM_BUNDLE_EXTRA_DIRS_DEBUG + "$ENV{VCPKG_ROOT}/installed/${_triplet}/debug/bin") endif() endif() @@ -382,6 +410,14 @@ if(OPENSWMM_INSTALL OR OPENSWMMCORE_INSTALL) ) endif() +# HC-1: resolve the HydroCouple interface headers before src/, so +# src/couplers/ can link HydroCouple::HydroCouple. Guarded, so a default build +# neither fetches nor requires anything. See cmake/FetchHydroCouple.cmake for +# why the pin is a SHA. +if(OPENSWMM_WITH_HYDROCOUPLE) + include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/FetchHydroCouple.cmake) +endif() + # Add subdirectories add_subdirectory(src) diff --git a/CMakePresets.json b/CMakePresets.json index b78448d5a..86f7b2ee0 100644 --- a/CMakePresets.json +++ b/CMakePresets.json @@ -3,25 +3,31 @@ "configurePresets": [ { "name": "default-debug", + "description": "Base Debug preset. Fast geometry/Manning kernels are OFF so the engine stays bit-identical to the legacy 5.x engine — see the `default` preset for why.", "generator": "Ninja", "binaryDir": "${sourceDir}/build/debug", "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake", "cacheVariables": { - "CMAKE_BUILD_TYPE": "Debug" + "CMAKE_BUILD_TYPE": "Debug", + "OPENSWMM_FAST_XSECT_LOOKUP": "OFF", + "OPENSWMM_FAST_MANNING_POW": "OFF" } }, { "name": "default", + "description": "Base Release preset — the shipping configuration. OPENSWMM_FAST_XSECT_LOOKUP and OPENSWMM_FAST_MANNING_POW are pinned OFF: they are ~10% faster on DW routing but NOT bit-exact vs legacy, and the engine the GUI ships must be bit-identical to the legacy 5.x engine so that a v6-vs-5.x run in the GUI is a real parity comparison. Use the `-fast` presets when you want the speed and do not need parity. Set BOTH or NEITHER — never mix.", "generator": "Ninja", "binaryDir": "${sourceDir}/build", "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake", "cacheVariables": { + "OPENSWMM_FAST_XSECT_LOOKUP": "OFF", + "OPENSWMM_FAST_MANNING_POW": "OFF" } }, { "name": "Windows", "inherits": "default", - "description": "Windows Release (Ninja Multi-Config, MSVC). FP policy: /fp:precise (IEEE-754, no FMA contraction). C extensions /we4013 promote implicit-decl to error.", + "description": "Windows Release (Ninja Multi-Config, MSVC). FP policy: /fp:precise (IEEE-754, no FMA contraction — VS2022 17.0+ generates no contractions under /fp:precise; /fp:contract would opt back IN, and there is no /fp:contract- spelling). C extensions /we4013 promote implicit-decl to error.", "generator": "Ninja Multi-Config", "binaryDir": "${sourceDir}/build/windows", "cacheVariables": { @@ -279,6 +285,36 @@ "OPENSWMM_BUILD_REGRESSION_TESTS": "ON", "OPENSWMM_WITH_GEOPACKAGE": "ON" } + }, + { + "name": "Windows-fast", + "inherits": "Windows", + "description": "Windows Release with the fast geometry/Manning kernels ON: ~10% faster DW routing, NOT bit-exact vs legacy. For benchmarking and perf work only — DO NOT SHIP this build, and do not grade legacy parity with it.", + "binaryDir": "${sourceDir}/build/windows-fast", + "cacheVariables": { + "OPENSWMM_FAST_XSECT_LOOKUP": "ON", + "OPENSWMM_FAST_MANNING_POW": "ON" + } + }, + { + "name": "Linux-fast", + "inherits": "Linux", + "description": "Linux Release with the fast geometry/Manning kernels ON: ~10% faster DW routing, NOT bit-exact vs legacy. For benchmarking and perf work only — DO NOT SHIP this build, and do not grade legacy parity with it.", + "binaryDir": "${sourceDir}/build/linux-fast", + "cacheVariables": { + "OPENSWMM_FAST_XSECT_LOOKUP": "ON", + "OPENSWMM_FAST_MANNING_POW": "ON" + } + }, + { + "name": "Darwin-fast", + "inherits": "Darwin", + "description": "macOS Release with the fast geometry/Manning kernels ON: ~10% faster DW routing, NOT bit-exact vs legacy. For benchmarking and perf work only — DO NOT SHIP this build, and do not grade legacy parity with it.", + "binaryDir": "${sourceDir}/build/darwin-fast", + "cacheVariables": { + "OPENSWMM_FAST_XSECT_LOOKUP": "ON", + "OPENSWMM_FAST_MANNING_POW": "ON" + } } ], "buildPresets": [ @@ -368,6 +404,21 @@ "name": "Darwin-tests-release", "description": "Build unit and regression tests in Release on macOS", "configurePreset": "Darwin-tests-release" + }, + { + "name": "Windows-fast", + "description": "Build the fast (non-bit-exact) engine on Windows — benchmarking only", + "configurePreset": "Windows-fast" + }, + { + "name": "Linux-fast", + "description": "Build the fast (non-bit-exact) engine on Linux — benchmarking only", + "configurePreset": "Linux-fast" + }, + { + "name": "Darwin-fast", + "description": "Build the fast (non-bit-exact) engine on macOS — benchmarking only", + "configurePreset": "Darwin-fast" } ] } \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf175ab8d..282b4bf85 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ openswmm.engine is a community-driven open source project. All contributors are The Technical Manager is responsible for: -- Maintaining the integrity and health of the `main`, `dev`, and `experimental` branches. +- Maintaining the integrity and health of the `main`, `develop`, and `experimental` branches. - Setting and enforcing coding standards, testing requirements, and documentation guidelines. - Triaging issues and pull requests in a timely manner. - Making final decisions on merges, releases, and branch management. @@ -65,7 +65,7 @@ The Technical Manager role is a single point of authority, which must be protect ## 4. Licensing, Intellectual Property & CLA -openswmm.engine is released under the **MIT License**. +openswmm.engine is released under the **Apache License, Version 2.0**. Attribution requirements are recorded in [NOTICE](./NOTICE), which also documents the USEPA SWMM material that resides in the public domain under 17 USC § 105. All contributors must sign the project **Contributor License Agreement (CLA)** before their pull request can be merged. The CLA is detailed in [CLA.md](./CLA.md). Key points: @@ -83,9 +83,9 @@ The project uses [CLA Assistant](https://cla-assistant.io). When you open your f Once signed, the CLA covers all future contributions. You do not need to sign again. -If your contribution includes third-party code or data, you are responsible for ensuring that the third-party license is compatible with MIT and that proper attribution is included in your submission. +If your contribution includes third-party code or data, you are responsible for ensuring that the third-party license is compatible with the Apache License, Version 2.0 and that proper attribution is added to [NOTICE](./NOTICE). -The full license text is available in [LICENSE](./LICENSE). +The full license text is available in [LICENSE](./LICENSE), and required attribution notices in [NOTICE](./NOTICE). --- @@ -179,11 +179,11 @@ Experimental APIs (clearly marked as such) carry no backward compatibility guara | Branch | Purpose | |---------------------------|--------------------------------------------------------------------------------------------| | `main` | Stable, production-ready code. Only receives merges from release candidates. | -| `dev` | Integration branch for ongoing development. All feature and bug-fix branches target here. | +| `develop` | Integration branch for ongoing development. All feature and bug-fix branches target here. | | `experimental/` | Sandboxed branches for exploratory or major formulation changes. See Section 15. | -| `bugfix/-desc` | Short-lived branches forked from `dev` to address specific bug reports. | -| `feature/` | Short-lived branches for minor feature additions, forked from `dev`. | -| `release/` | Release preparation branches (alpha → beta → rc) cut from `dev`. | +| `bugfix/-desc` | Short-lived branches forked from `develop` to address specific bug reports. | +| `feature/` | Short-lived branches for minor feature additions, forked from `develop`. | +| `release/` | Release preparation branches (alpha → beta → rc) cut from `develop`. | --- @@ -192,13 +192,13 @@ Experimental APIs (clearly marked as such) carry no backward compatibility guara For small, well-scoped bug fixes and minor improvements, follow this workflow: 1. **Open or reference an issue.** Verify the bug is reproducible and link the relevant issue number in all subsequent commits and pull requests. -2. **Fork the `dev` branch.** Name your branch `bugfix/-short-description` (e.g., `bugfix/42-overflow-in-routing`). +2. **Fork the `develop` branch.** Name your branch `bugfix/-short-description` (e.g., `bugfix/42-overflow-in-routing`). 3. **Write a failing unit test first.** The test must demonstrate the defect before the fix is applied. 4. **Implement the minimal fix.** Touch only the code necessary to resolve the issue. Do not refactor adjacent code. 5. **Ensure all regression tests pass.** If a regression test fails as a result of your change, you must either: - Fix the regression, **or** - Provide a written, technically justified explanation for why the regression failure is acceptable (included in the pull request description). -6. **Submit a pull request** against `dev` following the process described in Section 11. +6. **Submit a pull request** against `develop` following the process described in Section 11. --- @@ -222,7 +222,7 @@ Self-approvals are not permitted. The PR author may not count toward the communi Before requesting review, confirm that your PR: -- [ ] Targets the correct branch (`dev` for bug fixes and features; see Section 15 for experimental work) +- [ ] Targets the correct branch (`develop` for bug fixes and features; see Section 15 for experimental work) - [ ] CLA signed — first-time contributors must sign the [CLA](./CLA.md) before the PR can be merged - [ ] Includes a clear description of what was changed and why - [ ] References any related issues (e.g., `Closes #42`) @@ -235,8 +235,8 @@ Before requesting review, confirm that your PR: ### Merge Policy - Merges into `main` are performed exclusively by the Technical Manager at release time. -- Squash merging is preferred for `bugfix` and `feature` branches to keep the `dev` history clean. -- Merge commits are used when integrating `dev` into a `release` branch to preserve the full history. +- Squash merging is preferred for `bugfix` and `feature` branches to keep the `develop` history clean. +- Merge commits are used when integrating `develop` into a `release` branch to preserve the full history. --- @@ -325,7 +325,7 @@ Accepted proposals are implemented in a dedicated `experimental/` branch. - Rigorous **unit tests** covering the new formulation's behavior across the expected parameter space. - **Regression tests** as described in Section 17. -- Code must compile cleanly and not break the existing test suite on the `dev` branch. +- Code must compile cleanly and not break the existing test suite on the `develop` branch. - Implementation notes and algorithm descriptions must be maintained in Doxygen-compatible documentation. ### Step 4 — Peer Review (Strongly Encouraged) @@ -342,7 +342,7 @@ See Section 17 for full details. At minimum, the experimental implementation mus ### Step 6 — Documentation & References -Before a major formulation change can be merged into `dev`, the following documentation must be complete: +Before a major formulation change can be merged into `develop`, the following documentation must be complete: - **Doxygen comments** on all new and modified public APIs, structs, and functions. - **Inline citations** linking to peer-reviewed references where the formulation is derived from published work. @@ -417,7 +417,7 @@ Adding a third-party dependency increases the maintenance burden and risk surfac | Criterion | Requirement | |--------------------------|--------------------------------------------------------------------------------------------------| -| **License compatibility**| The dependency's license must be compatible with MIT (e.g., MIT, BSD, Apache 2.0). Copyleft licenses such as GPL are not permitted. | +| **License compatibility**| The dependency's license must be compatible with the Apache License, Version 2.0 (e.g., Apache-2.0, MIT, BSD). Copyleft licenses such as GPL, and licenses incompatible with Apache-2.0 such as GPLv2-only, are not permitted. | | **Maintenance status** | The dependency must be actively maintained with a responsive upstream community. | | **Stability** | The dependency must have a stable, versioned API. Unpinned or volatile dependencies are not acceptable. | | **Binary footprint** | Dependencies that substantially increase compiled binary size must be justified by proportional benefit. | diff --git a/LICENSE b/LICENSE index be942bae4..7810e5612 100644 --- a/LICENSE +++ b/LICENSE @@ -1,14 +1,219 @@ -MIT License +Copyright 2026 HydroCouple Developers -Copyright 2026 Caleb Buahin + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + 1. Definitions. -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. -This project contains original material has been released as part of various USEPA SWMM software over the years. These reside in the -public domain and cannot be claimed. This project also contains new material prepared by the United States -Government for which domestic copyright protection is not available under 17 -USC § 105. + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +-------------------------------------------------------------------------------- + +ADDENDUM: PUBLIC DOMAIN MATERIAL + +This project contains original material that has been released as part of +various USEPA SWMM software distributions over the years. That material +resides in the public domain and no copyright is claimed over it. This +project also contains new material prepared by the United States Government +for which domestic copyright protection is not available under 17 USC § 105. + +The Apache License, Version 2.0 above applies to the original contributions +of the OpenSWMM authors. It does not, and cannot, extend copyright to the +public domain material described in this addendum, nor does it restrict any +rights the public already holds in that material. See the NOTICE file for +further attribution details. diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..60997a89e --- /dev/null +++ b/NOTICE @@ -0,0 +1,40 @@ +OpenSWMM Engine +Copyright 2026 HydroCouple Developers + +This product includes software developed by the OpenSWMM authors +(https://github.com/HydroCouple/openswmm.engine). + +Licensed under the Apache License, Version 2.0. See the LICENSE file for the +full license text. + +-------------------------------------------------------------------------------- +PUBLIC DOMAIN MATERIAL +-------------------------------------------------------------------------------- + +Portions of this product are derived from the Storm Water Management Model +(SWMM) developed and released by the United States Environmental Protection +Agency (USEPA) over the course of several decades. That material was prepared +by or for the United States Government and resides in the public domain: +domestic copyright protection is not available for it under 17 USC § 105, and +no copyright is claimed over it by the OpenSWMM authors. + +The Apache License, Version 2.0 applies to the original contributions of the +OpenSWMM authors. It does not extend copyright to, and places no restriction +on, the public domain material described above. Recipients retain all rights +they already hold in that material independently of this License. + +Files derived in whole or in part from USEPA SWMM sources are, where +practical, marked as such in their file headers. The EPA SWMM 5.x sources are +available from https://www.epa.gov/water-research/storm-water-management-model-swmm. + +The USEPA does not endorse this product, and the names "EPA", "USEPA", and +"SWMM" are used solely to describe the origin of the public domain material. + +-------------------------------------------------------------------------------- +THIRD-PARTY COMPONENTS +-------------------------------------------------------------------------------- + +This product depends on and, in some distribution formats, bundles third-party +libraries that are licensed separately by their respective copyright holders. +Dependencies are declared in vcpkg.json. Each such component remains subject to +its own license terms, which accompany the component in its own distribution. diff --git a/README.md b/README.md index c4a49c546..76f79bf03 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![CodeQL](https://github.com/HydroCouple/openswmm.engine/actions/workflows/codeql.yml/badge.svg)](https://github.com/HydroCouple/openswmm.engine/actions/workflows/codeql.yml) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/HydroCouple/openswmm.engine/badge)](https://securityscorecards.dev/viewer/?uri=github.com/HydroCouple/openswmm.engine) [![Issues](https://img.shields.io/github/issues/HydroCouple/openswmm.engine)](https://github.com/HydroCouple/openswmm.engine/issues) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/HydroCouple/openswmm.engine/blob/HEAD/LICENSE) +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/HydroCouple/openswmm.engine/blob/HEAD/LICENSE) [![PyPI](https://img.shields.io/pypi/v/openswmm.svg)](https://pypi.org/project/openswmm) [![Downloads](https://pepy.tech/badge/openswmm)](https://pepy.tech/project/openswmm) [![Python](https://img.shields.io/pypi/pyversions/openswmm.svg)](https://pypi.org/project/openswmm) @@ -22,10 +22,11 @@ | | Site | Contents | |---|---|---| -| **C / C++ Engine** | **[hydrocouple.org/openswmm.engine](https://hydrocouple.org/openswmm.engine)** | Full C API reference, hydrology / hydraulics / water-quality reference manuals, user manual, architecture notes. | +| **C / C++ Engine** | **[hydrocouple.org/openswmm.engine](https://hydrocouple.org/openswmm.engine)** | Full C API reference, hydrology / hydraulics / water-quality reference manuals, engine manual (input format, files, reports, C API), architecture notes. | | **Python Bindings** | **[hydrocouple.org/openswmm.engine/python](https://hydrocouple.org/openswmm.engine/python)** | Quickstart, per-domain user guide, Cython API reference, SWMM 5 → v6 migration. | +| **SWMMVis (GUI)** | **[hydrocouple.org/openswmm.gui](https://www.hydrocouple.org/openswmm.gui/)** | The graphical application: map canvas, layers and CRS, every editor, running simulations, plots and animation, 2D meshing, tutorials, reference tables and error codes. | -Both sites cross-link from their top navigation. +The sites cross-link from their top navigation. --- @@ -273,7 +274,7 @@ Signing is automated through [CLA Assistant](https://cla-assistant.io) — when ## License -MIT — see [LICENSE](LICENSE). Original EPA SWMM material is in the public domain under 17 USC § 105. +Apache License, Version 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Original EPA SWMM material is in the public domain under 17 USC § 105 and is not subject to the Apache license grant. ## Acknowledgements diff --git a/ROADMAP.md b/ROADMAP.md index e613f145e..881312bca 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -37,7 +37,7 @@ test suites, but ship in pre-release builds until 6.0.0 is final. - Second-order MUSCL reconstruction (`FV_ORDER 2`) and SSP-RK2 time integration (`FV_TIME_INTEGRATION RK2`), both preserving the still-water property to machine precision. - Local time stepping (`FV_LTS`, on by default): each control volume takes a power-of-two tier from its own Courant limit, tiers are graded so no face spans more than one level, and conservation across a tier interface is exact by construction. Where tiering finds nothing to separate, the solver falls through to global stepping bit-for-bit. - Semi-implicit node coupling (`FV_NODE_COUPLING`, default `SEMI_IMPLICIT`), which linearizes each coupling face's flux in the node head and so removes the junction storage floor — not the pipe — from the explicit stability limit. -- Backward compatible: seventeen `FV_*` `[OPTIONS]` keys, readable and writable through `swmm_options_get`/`set`, the Python bindings (`RouteModel.FV`) and the MCP server, and inert rather than rejected under the other routing models, so switching `FLOW_ROUTING` never invalidates a file. Virtual junctions become ordinary interior faces and reproduce the unsplit conduit cell for cell. +- Backward compatible: twenty live `FV_*` `[OPTIONS]` keys and five retired ones (`FV_NODE_COUPLING`, `FV_NODE_DT`, `FV_NODE_PICARD`, `FV_NODE_CELL_COUPLING`, `FV_JUNCTION_MODEL`; the first three warn, the last two were already no-ops), readable and writable through `swmm_options_get`/`set`, the Python bindings (`RouteModel.FV`) and the MCP server, and inert rather than rejected under the other routing models, so switching `FLOW_ROUTING` never invalidates a file. Virtual junctions become ordinary interior faces and reproduce the unsplit conduit cell for cell. **Validation to date:** 29 analytic gates (closure, scheme, network) plus 7 local-time-stepping gates and 5 engine-level gates. Ritter and Stoker match the closed-form solutions including shock speed; lake at rest holds to 1e-9 ft across a slope break and while pressurized; mass is conserved to 1e-12 over 10⁵ substeps. On the EPA reference drainage model the routing continuity error is **0.000 % at every mesh resolution**, against 0.026 % for dynamic wave routing on the same file. Finite-volume routing is deliberately outside the legacy bit-parity contract — it is a different discretization, gated on analytic and engineering tolerances instead. @@ -45,9 +45,10 @@ test suites, but ship in pre-release builds until 6.0.0 is final. - **Performance.** The solver runs ~7× dynamic wave wall-clock at one cell per conduit and ~34× at Δx = 20 ft on the reference model. The original expectation of parity at equal element counts is recorded as refuted; the two largest costs found so far (the depth inversion, 3.2×, and the node stability constraint, 2.9×) are already addressed. Remaining levers are kernel fusion and CFL-census interval tuning. - **Parallel and GPU backends.** `FV_BACKEND` and the plugin loader are in place, but no plugin yet exports the 1D network-solver entry point, so execution is CPU-serial today. - **Peak attenuation at the default mesh.** One cell per conduit attenuates the reference model's peaks by 37 % on average (7 % at Δx = 20 ft). The cause is geometric rather than diffusive — a cell-centred scheme places a single cell's bed at the conduit mid-point, presenting an artificial bed step at every manhole — so higher-order reconstruction does not rescue it. Setting `FV_CELL_LENGTH` is the present workaround; a bed-step treatment at junction faces is the fix. -- **Desktop application exposure.** `FLOW_ROUTING FV` and the `FV_*` keys are not yet offered in the OpenSWMM GUI's routing options. - **Broader regression** against published benchmark cases beyond the analytic suite, and quantification of the short-steep-pipe cell-length floor. -- **Sub-atmospheric transients** are outside the slot closure; the two-component pressure approach is the documented extension path if rapid-downsurge fidelity is later required. +- **Sub-atmospheric transients.** The two-component pressure approach (TPA) is IMPLEMENTED in both solvers (#156): `FV_PRESSURE_CLOSURE TPA` in the finite-volume solver (Hydraulics Reference Manual §8.4.5) and `SURCHARGE_METHOD TPA` in the dynamic wave solver (§3.3.11), both default-off and bit-inert when off, validated on the Vasconcelos et al. (2006) laboratory cases with sub-atmospheric heads observable via `REPORT_SIGNED_HEADS`. The high-celerity filling divergence that was pinned here (explicit FV TPA at a = 150 m/s diverging at the reflected surge) **was closed on 2026-09-12** by the slot/free-surface wave-speed bound: Davis's symmetric estimate had carried the acoustic celerity into the wave entering the free-surface side of a pressurization front, and bounding that wave by the Rankine-Hugoniot bore speed removes the mode. The fixture completes at 0.000 % continuity from 150 to 3000 m/s and the gate is now the positive test `FvTpa.HighCelerityFillingCompletes`; the Vasconcelos & Wright (2009) hybrid flux is no longer required for this front. + +(`FLOW_ROUTING FV` and the FV keys, including the #156 additions, are exposed in the OpenSWMM GUI's Routing & Hydraulics options as of openswmm.gui #10; the former desktop-exposure gap is closed.) ### 1.2 2D Overland Flow — Local Inertial Finite Volume Model 🔧 @@ -65,16 +66,17 @@ test suites, but ship in pre-release builds until 6.0.0 is final. - Performance and robustness hardening on large regional meshes based on beta testing feedback. - 2D water quality transport (Section 2.2) on the same mesh. -### 1.3 Spatially Explicit Inlets — Mode-Switching Junction Nodes 🔬 +### 1.3 Spatially Explicit Inlets — Mode-Switching Junction Nodes ✅ **Motivation:** Since SWMM 5.2, inlets are attributes of street and channel conduits (`[INLET_USAGE]`): capture flow is computed from approach hydraulics and applied as a flow modification inside the link, with ponding tracked at a separate reference node. The inlet has no independent hydraulic presence, so inlet-controlled surface/sewer exchange cannot respond to the hydraulic state of the node it drains to. -**Status:** Design recorded. No implementation yet. +**Status:** Implemented as `[INLET_JUNCTIONS]` in the 6.0.0 development line, alongside the conduit-attribute form, which remains supported. An inlet junction is a virtual junction that also carries an inlet: it has its own head, floods above the curb, passes bypass on to the next street conduit, and takes a surcharging sewer's backflow onto the street. Documented in Hydraulics Reference Manual §7 and worked in Application Manual Chapter 5. -**Planned scope:** -- Promote inlets to first-class junction nodes that switch mode based on approach hydraulics: capturing street flow when gutter spread exceeds a threshold, and reverting to passive junctions otherwise. +**Delivered:** +- Inlets promoted to first-class junction nodes that switch mode based on approach hydraulics: capturing street flow when gutter spread exceeds a threshold, and reverting to passive junctions otherwise. - HEC-22 grate and curb-opening capture retained as the capture closure, evaluated at the node rather than as a link post-processing step. -- Ponding, bypass, and re-entry resolved at the inlet node itself, enabling two-way street ↔ sewer exchange under surcharge. +- Ponding, bypass, and re-entry resolved at the inlet node itself, with two-way street ↔ sewer exchange under surcharge. +- A conduit attached to an inlet junction may not also carry an `[INLET_USAGE]` row; the engine refuses the double capture rather than applying it twice. --- @@ -90,9 +92,9 @@ Two routes are being developed, and they are complementary rather than competing *Remaining for Route A:* the transport layer is not yet connected to the project's `[POLLUTANTS]`, land-use buildup/washoff, inflows or treatment — it is exercised through the solver's own gates. Wiring it up, deciding how `QUALITY_SOLVER` selects between the legacy Eulerian solver, Route B and finite-volume transport, and reporting cell-resolved concentrations are the open items. Note that local time stepping is disabled while species are transported, because the flux-corrected transport limiter needs one synchronous sweep. -**Route B — Lagrangian parcel tracking (design study recorded, not implemented).** Parcels of water and their constituent loads are advected along the flow field, with dispersion applied as a superimposed Fickian random-walk step. The approach is free of numerical diffusion, carries no Courant constraint on advection, conserves mass at the parcel level, and — unlike Route A — is independent of the hydraulic discretization, so it works under dynamic wave and kinematic wave routing as well. It is the natural host for the multispecies reaction system of Section 2.4, since reactions are evaluated along parcel trajectories. +**Route B — Lagrangian parcel tracking (implemented, `QUALITY_SOLVER LAGRANGIAN`).** Parcels of water and their constituent loads are advected along the flow field, with dispersion applied as a superimposed Fickian random-walk step. The approach is free of numerical diffusion, carries no Courant constraint on advection, conserves mass at the parcel level, and — unlike Route A — is independent of the hydraulic discretization, so it works under dynamic wave and kinematic wave routing as well. It is the natural host for the multispecies reaction system of Section 2.4, since reactions are evaluated along parcel trajectories. -*Planned scope for Route B:* +*Delivered for Route B:* - Lagrangian parcel-tracking advection for 1D pipe and conduit flow across all SWMM link and node types, driven by velocity fields from the flow routing solver. - Random-walk dispersion on parcel trajectories using user-specified or empirically estimated longitudinal dispersion coefficients. - Parcel injection, merging, and splitting logic to maintain solution resolution while controlling computational cost. @@ -100,11 +102,11 @@ Two routes are being developed, and they are complementary rather than competing - Water age as a built-in reserved species. - Numerical alignment with the legacy Eulerian solver in the degenerate case (single bulk species, first-order decay, no dispersion, complete-mixing storage) as a parity gate, plus comparison to analytical solutions for simple pipe transport problems. -### 2.2 Advection-Dispersion Model — Overland Flow 📋 +### 2.2 Advection-Dispersion Model — Overland Flow ✅ **Motivation:** Surface runoff carries dissolved and particulate constituents across the land surface. A 2D or quasi-2D ADE formulation for overland flow will extend water quality modeling to the catchment scale. -**Status:** No implementation yet. The 2D marcher solves water only; this work is sequenced behind Route A of Section 2.1, whose contact-upwinded, flux-corrected species update is the same construction applied to an unstructured 2D mesh. +**Status:** Implemented. The 2D marcher carries species mass per cell, species-major, with the same construction as Route A of Section 2.1 applied to the unstructured mesh, plus coverages, buildup, washoff and sweeping on the cells and an isotropic `DISPERSION` coefficient. Which classes are carried is resolved by the transport policy matrix printed in the report. Documented as Chapter 10 of the Water Quality Reference Manual. **Planned scope:** - 2D depth-averaged ADE for overland flow domains. @@ -120,11 +122,11 @@ Two routes are being developed, and they are complementary rather than competing - Dispersion tensor formulation accounting for mechanical dispersion and molecular diffusion. - Coupling to the surface and pipe water quality modules at shared boundaries. -### 2.4 Multispecies Reaction Support — All Flow Domains 🔬 +### 2.4 Multispecies Reaction Support — All Flow Domains ✅ **Motivation:** Real-world water quality problems involve interacting chemical and biological species (e.g., nitrogen cycling, dissolved oxygen–BOD interactions, pathogen decay). A general multispecies reaction framework will allow users to define arbitrary reaction networks without modifying source code. -**Status:** Design recorded — an EPANET-MSX-equivalent reaction system (user-defined rate ODEs and equilibrium DAEs, bulk and wall species, selectable integrators with adaptive error control) specified as part of the Route B strategy in Section 2.1. No implementation yet. Whichever transport route ships first, the reaction system is intended to be written once and shared, not duplicated per transport scheme. +**Status:** Implemented as the reactions process component: user-defined rate and equilibrium expressions, bulk and wall species, named coefficients and terms, selectable integrators, and pipe, tank and initial-quality scopes, configured from a `.rxn` file named in `[PROCESS_COMPONENTS]`. Five sections of the configuration (`[REACTION_SOURCES]`, `[REACTION_PARAMETERS]`, `[REACTION_PATTERNS]`, `[REACTION_REPORT]`, `[REACTION_SUBCATCHMENTS]`) are recognised and refused rather than ignored, and species concentrations are not yet written to the output file — `[REACTION_REPORT]` is what would select them. Documented as Chapter 8 of the Water Quality Reference Manual. Whichever transport route ships first, the reaction system is intended to be written once and shared, not duplicated per transport scheme. **Planned scope:** - A general reaction network specification (user-defined stoichiometry, rate laws, and kinetic parameters) applicable to pipe, overland, and groundwater transport. @@ -149,12 +151,14 @@ Two routes are being developed, and they are complementary rather than competing --- -## 4. Heat Transport 📋 +## 4. Heat Transport ✅ **Motivation:** Thermal loading from urban surfaces, impervious cover, and stormwater infrastructure is a significant stressor on receiving water bodies. A heat transport module will enable simulation of stormwater temperature dynamics from catchment to receiving water. -**Planned scope:** -- Surface energy balance model for catchment-scale water temperature estimation, accounting for solar radiation, long-wave exchange, evaporation, and conduction. +**Status:** Implemented as the heat process component, `HEAT_TRANSPORT ON` with a `.heat` configuration file: temperature is a reserved transported species carried by the selected transport engine, with surface exchange (latent and sensible), radiative exchange (net shortwave, back longwave, atmospheric and land-cover longwave), LID layer conduction and a bed zone with conduction and hyporheic exchange. Documented as Chapter 9 of the Water Quality Reference Manual. Per-element heat attributes remain outstanding. + +**Delivered:** +- Surface energy balance for water temperature, accounting for solar radiation, long-wave exchange, evaporation, and conduction. - 1D longitudinal heat transport in pipes and channels, coupled to the ADE solver (Section 2.1). - Coupling to the groundwater module for subsurface heat exchange and baseflow temperature. - Thermal stratification in detention basins (simplified layer model). @@ -174,11 +178,11 @@ Two routes are being developed, and they are complementary rather than competing - The coupling interface for the groundwater ADE transport module (Section 2.3). - Continued legacy-parity verification alongside the rest of the hydrology suite. -### 5.2 Spatially Explicit Groundwater — FV Mesh Integration 🔬 +### 5.2 Spatially Explicit Groundwater — FV Mesh Integration ✅ **Motivation:** The two-zone aquifer of Section 5.1 is integrated per subcatchment: lateral exchange is the empirical SWMM cubic polynomial, there is no inter-subcatchment communication, and the aquifer's only feedback to the rest of the engine is an end-of-step infiltration cap. Four physically real processes are therefore not representable: saturation-excess (Dunne) overland flow when the water table reaches the surface, return flow re-emerging downslope after lateral subsurface transport, head-driven pipe and node ↔ aquifer exchange (the physical mechanism behind RDII, groundwater inflow, and sewer exfiltration), and true capillary rise feeding evaporation. -**Status:** Design recorded, following the semidiscrete finite volume multiprocess watershed formulation of Qu & Duffy (2007). No implementation yet. +**Status:** Implemented, following the semidiscrete finite volume multiprocess watershed formulation of Qu & Duffy (2007): a two-layer aquifer per mesh cell with four selectable soil-characteristic laws, three unsaturated-zone closures resolved from `AUTO`, lateral Darcy exchange, deep loss, MODFLOW-River node exchange, Dunne saturation excess and Feddes-stressed evapotranspiration. Opt-in through `[2D_AQUIFER]` rows. The Russo, Brooks-Corey and van Genuchten recharge closures are **experimental**: their equilibrium is right and their relaxation rate is this engine's generalisation rather than a published result, pending the closure-ladder and HYDRUS-1D benchmarks. Documented as Chapter 9 of the Hydrology Reference Manual. **Planned scope:** - A vertically integrated, complementary two-layer subsurface kernel on the 2D FV mesh — unsaturated moisture depth and saturated thickness per cell, joined at a moving water table. @@ -209,12 +213,11 @@ The following items have been raised in community discussions, or explored and s | Item | Reason for Deferral | |------------------------------------------------|----------------------------------------------------------------------------| -| 2D overland flow (full shallow water equations) | Local inertial finite volume model implemented (Section 1.2); full dynamic-wave SWE not currently scheduled | | Implicit 2D time integration (CVODE/ARKODE) | Explored and retired — the explicit marcher outperformed it on the benchmark models and removed two heavy dependencies | | Real-time data assimilation & sensor fusion | Requires external telemetry infrastructure not yet in scope | | Machine learning surrogate models | Research area; may be introduced as an optional experimental module | -**No longer deferred.** *GPU-accelerated solvers* have moved into development: the +**No longer deferred.** *2D overland flow with the full shallow-water equations* shipped: `MOMENTUM_EQUATION FULL_SWE` selects an Audusse-reconstructed, rotated-HLLC face flux on the same marcher, alongside `LOCAL_INERTIAL` (the default) and `DIFFUSIVE_WAVE` (Hydraulics Reference Manual §9.2). *GPU-accelerated solvers* have moved into development: the 2D marcher's kernels run through Kokkos-based plugin backends (OpenMP, CUDA, HIP, SYCL) selected at runtime above a cell-count gate, shipped as optional plugin binaries so the base build carries no GPU dependency. The 1D finite volume solver @@ -241,7 +244,15 @@ means merged and gated but not yet carried by a tag. | Per-cell 2D parameter surfaces and 2D initial conditions | unreleased | | Explicit finite volume 1D routing, `FLOW_ROUTING FV` (Section 1.1) | unreleased | | Cell-resolved Eulerian scalar transport on the finite volume mesh (Section 2.1, Route A) | unreleased | +| Lagrangian parcel transport, `QUALITY_SOLVER LAGRANGIAN` (Section 2.1, Route B) | unreleased | +| Species transport, coverages, buildup and washoff on the 2D mesh (Section 2.2) | unreleased | +| Multispecies reactions as a process component (Section 2.4) | unreleased | +| Heat transport as a process component, with water age (Section 4) | unreleased | +| Spatially explicit two-layer groundwater on the mesh (Section 5.2) | unreleased | +| Inlet junctions, `[INLET_JUNCTIONS]` (Section 1.3) | unreleased | +| Full shallow-water and diffusive-wave momentum closures for the 2D marcher (Section 1.2) | unreleased | +| Virtual junctions, and the two-component pressure approach in both solvers (Section 1.1) | unreleased | --- -*Last updated: August 2026 — Caleb Buahin, Technical Manager* +*Last updated: September 2026 — Caleb Buahin, Technical Manager* diff --git a/cmake/BundleRuntimeDeps.cmake.in b/cmake/BundleRuntimeDeps.cmake.in index 3d174ca6b..1f35e8a70 100644 --- a/cmake/BundleRuntimeDeps.cmake.in +++ b/cmake/BundleRuntimeDeps.cmake.in @@ -42,6 +42,17 @@ set(_post_excludes @OPENSWMM_BUNDLE_POST_EXCLUDES@) # installed//bin where SUNDIALS, HDF5, etc. live. The list is # `;`-separated; ${_extra_dirs} dereference splits it into separate args. set(_extra_dirs "@OPENSWMM_BUNDLE_EXTRA_DIRS@") +# vcpkg keeps debug binaries in /debug/bin (issue #9). Under a +# multi-config generator the config is only known HERE, at install time, so the +# ordering is decided here rather than at configure time: for a debug install +# the debug tree is searched FIRST, so a DLL that keeps its release name +# (sqlite3.dll) resolves to the debug copy instead of silently pulling the +# release one into a Debug package. The release tree stays on the list as a +# fallback for anything vcpkg ships release-only. +set(_extra_dirs_debug "@OPENSWMM_BUNDLE_EXTRA_DIRS_DEBUG@") +if(_extra_dirs_debug AND "${CMAKE_INSTALL_CONFIG_NAME}" MATCHES "^([Dd]ebug|DEBUG)$") + set(_extra_dirs "${_extra_dirs_debug};${_extra_dirs}") +endif() file(GET_RUNTIME_DEPENDENCIES RESOLVED_DEPENDENCIES_VAR _resolved diff --git a/cmake/CheckNoHydroCoupleSDK.cmake b/cmake/CheckNoHydroCoupleSDK.cmake new file mode 100644 index 000000000..eb95d7474 --- /dev/null +++ b/cmake/CheckNoHydroCoupleSDK.cmake @@ -0,0 +1,167 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2026 Caleb Buahin +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# D1 (program plan §C.1) --- the D-C6 guard. +# +# cmake -DROOTS= [-DFILES=] [-DEXCLUDE=] +# -P cmake/CheckNoHydroCoupleSDK.cmake +# +# ROOTS are scanned recursively; FILES are scanned individually (the top-level +# CMakeLists.txt, which must not drag the whole repository into a recursive +# walk: tests/output alone is ~118k files, none of them target source). +# +# D-C6: the engine, `src/couplers/*` and SWMMVis link ONLY the header-only +# `HydroCouple` interfaces. No `HydroCoupleSDK`, anywhere — recorded as not +# re-openable by a later mounting of the SDK. A rule nobody checks is a rule +# that holds only until someone is in a hurry, so this makes it a test. +# +# What counts as a violation — the two ways a dependency actually arrives: +# 1. an `#include` of anything under `hydrocouplesdk/` (any case, either +# quote style) in a C/C++ source or header; +# 2. `find_package(HydroCoupleSDK …)`, or `HydroCoupleSDK::` / `hydrocouplesdk` +# named inside `target_link_libraries(…)`, in a CMake file. +# +# Known limitation, accepted: a CMake STRING literal that happens to contain +# `find_package(HydroCoupleSDK` or a `target_link_libraries(` span naming it +# is reported, because only comments are stripped. Stripping quoted strings +# would also hide a real, quoted link argument. Outside this script no such +# string exists; if one ever needs to, exclude that file explicitly. +# +# What does NOT count, deliberately: the WORD. The files that state this rule +# (this one, FetchHydroCouple.cmake, the option's docstring) necessarily name +# the SDK in prose, and a guard that fails on its own documentation would be +# switched off within a week. Matching the include and the link, not the +# name, is what lets the guard stay on. +# +# Written as a CMake script rather than Python so it runs on every CI leg +# with nothing installed beyond the build tool itself. + +cmake_minimum_required(VERSION 3.21) + +if(NOT DEFINED ROOTS AND NOT DEFINED FILES) + message(FATAL_ERROR "CheckNoHydroCoupleSDK: give -DROOTS= and/or -DFILES=") +endif() +set(_roots "") +foreach(_r IN LISTS ROOTS) + if(NOT IS_DIRECTORY "${_r}") + # A missing root is a configuration error, not a pass: a guard that + # silently scans nothing is worse than no guard. + message(FATAL_ERROR "CheckNoHydroCoupleSDK: root '${_r}' does not exist") + endif() + get_filename_component(_ra "${_r}" ABSOLUTE) + list(APPEND _roots "${_ra}") +endforeach() + +set(_excl "") +foreach(_e IN LISTS EXCLUDE) + get_filename_component(_ea "${_e}" ABSOLUTE) + list(APPEND _excl "${_ea}") +endforeach() + +set(_sources "") +set(_cmake "") +foreach(_r IN LISTS _roots) + file(GLOB_RECURSE _s LIST_DIRECTORIES FALSE + "${_r}/*.h" "${_r}/*.hh" "${_r}/*.hpp" "${_r}/*.hxx" + "${_r}/*.c" "${_r}/*.cc" "${_r}/*.cpp" "${_r}/*.cxx" + "${_r}/*.inl" "${_r}/*.ipp") + file(GLOB_RECURSE _c LIST_DIRECTORIES FALSE + "${_r}/CMakeLists.txt" "${_r}/*.cmake" "${_r}/*.cmake.in") + list(APPEND _sources ${_s}) + list(APPEND _cmake ${_c}) +endforeach() +foreach(_f IN LISTS FILES) + if(NOT EXISTS "${_f}") + message(FATAL_ERROR "CheckNoHydroCoupleSDK: file '${_f}' does not exist") + endif() + get_filename_component(_fa "${_f}" ABSOLUTE) + if(_fa MATCHES "(CMakeLists\\.txt|\\.cmake|\\.cmake\\.in)$") + list(APPEND _cmake "${_fa}") + else() + list(APPEND _sources "${_fa}") + endif() +endforeach() + +function(_is_excluded _path _out) + set(${_out} FALSE PARENT_SCOPE) + foreach(_x IN LISTS _excl) + string(FIND "${_path}" "${_x}/" _pos) + if(_pos EQUAL 0) + set(${_out} TRUE PARENT_SCOPE) + return() + endif() + endforeach() + # Build trees and fetched dependencies are not ours to police. + if(_path MATCHES "/(build|_deps|\\.git)/") + set(${_out} TRUE PARENT_SCOPE) + endif() + # …nor is this script. It is the one file that must SPELL the patterns it + # forbids — its violation messages are CMake string literals naming + # `find_package(HydroCoupleSDK …)` — and comment-stripping does not strip + # strings. The first run over the real tree failed on exactly that: the + # guard reported itself, twice. Found only because the real-tree case is + # a gate of its own, not an afterthought to the fixtures. + if(_path STREQUAL "${CMAKE_CURRENT_LIST_FILE}") + set(${_out} TRUE PARENT_SCOPE) + endif() +endfunction() + +set(_violations "") +set(_scanned 0) + +foreach(_f IN LISTS _sources) + _is_excluded("${_f}" _skip) + if(_skip) + continue() + endif() + math(EXPR _scanned "${_scanned} + 1") + file(STRINGS "${_f}" _hits + REGEX "^[ \t]*#[ \t]*include[ \t]*[<\"][^>\"]*[Hh][Yy][Dd][Rr][Oo][Cc][Oo][Uu][Pp][Ll][Ee][Ss][Dd][Kk]/") + foreach(_h IN LISTS _hits) + string(STRIP "${_h}" _h) + list(APPEND _violations "${_f}: ${_h}") + endforeach() +endforeach() + +foreach(_f IN LISTS _cmake) + _is_excluded("${_f}" _skip) + if(_skip) + continue() + endif() + math(EXPR _scanned "${_scanned} + 1") + file(READ "${_f}" _text) + # Strip CMake line comments first: prose that names the SDK is allowed, + # a call that uses it is not. + string(REGEX REPLACE "#[^\n]*" "" _code "${_text}") + string(TOLOWER "${_code}" _lc) + if(_lc MATCHES "find_package[ \t\n]*\\([ \t\n]*hydrocouplesdk") + list(APPEND _violations "${_f}: find_package(HydroCoupleSDK …)") + endif() + if(_lc MATCHES "target_link_libraries[ \t\n]*\\([^)]*hydrocouplesdk") + list(APPEND _violations "${_f}: target_link_libraries(… HydroCoupleSDK …)") + endif() +endforeach() + +if(_violations) + list(LENGTH _violations _n) + list(JOIN _violations "\n " _pretty) + message(FATAL_ERROR + "D-C6 violated: ${_n} HydroCoupleSDK dependenc(ies)\n ${_pretty}\n" + "The engine may use only the header-only HydroCouple interfaces " + "(program plan decision D-C6). This is not re-openable.") +endif() + +message(STATUS "D-C6 guard: ${_scanned} files scanned, no HydroCoupleSDK include or link") diff --git a/cmake/FetchHydroCouple.cmake b/cmake/FetchHydroCouple.cmake new file mode 100644 index 000000000..c3493629c --- /dev/null +++ b/cmake/FetchHydroCouple.cmake @@ -0,0 +1,152 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# Copyright 2026 Caleb Buahin +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# HC-1 --- the HydroCouple interface headers, and nothing else. +# +# Program plan D-C6: the engine, `src/couplers/*` and SWMMVis link ONLY the +# header-only `HydroCouple` interfaces. No `HydroCoupleSDK`, anywhere, and +# that decision is recorded as not re-openable by a later mounting of the SDK. +# `HydroCouple` is an INTERFACE library exporting `HydroCouple::HydroCouple`, +# so "link" here costs an include directory and `cxx_std_20` — no objects, no +# runtime dependency, nothing to ship. +# +# THE PIN IS THE POINT. HydroCouple 2.0.0 renumbered `WorkflowStatus` after +# tagging, without a release: a build against a moving ref compiles fine today +# and silently changes the meaning of a status enum tomorrow. The program plan's +# instruction is to pin a commit, so `OPENSWMM_HYDROCOUPLE_GIT_TAG` defaults to +# a full SHA rather than a branch or a tag, and a tag is accepted only because +# a caller may deliberately want one. +# +# Resolution order: +# 1. An already-defined `HydroCouple::HydroCouple` target (superbuild). +# 2. `find_package(HydroCouple CONFIG)` --- a system/vcpkg install, or the +# sibling checkout via `CMAKE_PREFIX_PATH` / `HydroCouple_ROOT`. Preferred +# in development, because it uses the tree the developer already has. +# 3. `FetchContent` at the pinned commit. +# +# Step 3 is deliberately last: silently downloading a second copy of interfaces +# the developer already has checked out is how two versions of an ABI end up in +# one build. + +include_guard(GLOBAL) + +set(OPENSWMM_HYDROCOUPLE_GIT_REPOSITORY + "https://github.com/hydrocouple/HydroCouple.git" + CACHE STRING "Git remote for the HydroCouple interface headers") + +# bef95cb --- "fix(abi): factory-component instances carry their ownership in +# the type" (2026-09-04). ABI 2. On origin/dev since 2026-09-29. +# +# The FULL 40-character SHA, not the abbreviation: an abbreviated SHA is only +# resolvable after the clone has fetched enough history to disambiguate it, +# and the full one cannot become ambiguous as the repository grows. +set(OPENSWMM_HYDROCOUPLE_GIT_TAG + "bef95cb19310c6560e7f35158515bf27ec57ac29" + CACHE STRING + "Pinned HydroCouple commit. A SHA, not a branch: WorkflowStatus was \ +renumbered without a release, so a moving ref is a silent ABI change.") + +# D1 (2026-09-29): the ABI the pin stands for, enforced on EVERY resolution +# path, not only the fetch. Resolution tries a local install before the pinned +# fetch, so without this the pin governs only machines that have no +# HydroCouple installed — anyone with a sibling checkout silently compiles +# against whatever ABI that checkout holds. Measured on the day this was +# written: pin bef95cb = ABI 2, origin/dev = ABI 3 (7e6d142, releaseState), +# the developer's uncommitted working tree = ABI 4. HC-1's own "ON via +# CONFIG" check installed that working tree and compiled against ABI 4 +# believing it was on the pin. `tests/compile_check/hydrocouple_headers.cpp` +# turns this number into a static_assert, so a mismatch is a build error +# naming both ABIs rather than a runtime surprise. Bump it together with +# OPENSWMM_HYDROCOUPLE_GIT_TAG, never separately. +set(OPENSWMM_HYDROCOUPLE_EXPECTED_ABI "2" CACHE STRING + "HYDROCOUPLE_ABI_VERSION the pinned commit declares; asserted at compile time") + +function(_openswmm_hydrocouple_report _how) + if(NOT OPENSWMM_HYDROCOUPLE_QUIET) + message(STATUS "HydroCouple interfaces: ${_how}") + endif() +endfunction() + +# --- 1. already satisfied ----------------------------------------------------- +if(TARGET HydroCouple::HydroCouple) + _openswmm_hydrocouple_report("using the target already defined in this build") + return() +endif() + +# --- 2. an installed or sibling copy ---------------------------------------- +find_package(HydroCouple CONFIG QUIET) +if(HydroCouple_FOUND AND TARGET HydroCouple::HydroCouple) + _openswmm_hydrocouple_report( + "found ${HydroCouple_VERSION} via CONFIG at ${HydroCouple_DIR}") + return() +endif() + +# --- 3. the pinned fetch ----------------------------------------------------- +# +# History worth keeping: on 2026-09-27 this path was verified BROKEN, because +# the pin was 6 commits ahead of origin/dev and unpushed — the ABI-2 work the +# engine targets existed only in the developer's checkout. FetchContent's own +# message for that is the unhelpful "Failed to checkout tag", which sends the +# reader looking for a typo. HydroCouple was pushed on 2026-09-29 and this +# path now resolves; see the verification in the HC-1 commit. +# +# What the pre-flight below can and cannot do. `git ls-remote` asks the remote +# about REFS, so it can prove a branch or tag name is wrong. It cannot ask +# about an arbitrary commit, so for the SHA pin actually in use an unpushed or +# mistyped commit still surfaces as FetchContent's opaque checkout error. If +# you see "Failed to checkout tag" with a SHA pin: check that the commit has +# been pushed to OPENSWMM_HYDROCOUPLE_GIT_REPOSITORY before anything else. +include(FetchContent) + +# Ask the remote whether the pin is even reachable before cloning, so the +# failure is one message instead of a clone plus a checkout error. +find_package(Git QUIET) +if(GIT_EXECUTABLE) + execute_process( + COMMAND ${GIT_EXECUTABLE} ls-remote --exit-code + ${OPENSWMM_HYDROCOUPLE_GIT_REPOSITORY} ${OPENSWMM_HYDROCOUPLE_GIT_TAG} + RESULT_VARIABLE _hc_lsremote_rc + OUTPUT_QUIET ERROR_QUIET) + # A SHA is not a ref, so ls-remote failing is expected for one and + # meaningful for the other. Only a ref-shaped pin is checked here. + if(NOT OPENSWMM_HYDROCOUPLE_GIT_TAG MATCHES "^[0-9a-fA-F]+$" + AND NOT _hc_lsremote_rc EQUAL 0) + message(FATAL_ERROR + "OPENSWMM_HYDROCOUPLE_GIT_TAG '${OPENSWMM_HYDROCOUPLE_GIT_TAG}' is " + "not a ref on ${OPENSWMM_HYDROCOUPLE_GIT_REPOSITORY}.") + endif() +endif() + +# HydroCouple's own CMakeLists offers tests; we want the interface target only. +set(HYDROCOUPLE_BUILD_TESTS OFF CACHE BOOL "" FORCE) + +FetchContent_Declare( + HydroCouple + GIT_REPOSITORY ${OPENSWMM_HYDROCOUPLE_GIT_REPOSITORY} + GIT_TAG ${OPENSWMM_HYDROCOUPLE_GIT_TAG} + GIT_SHALLOW FALSE # a SHA cannot be fetched shallowly from all remotes + EXCLUDE_FROM_ALL +) +FetchContent_MakeAvailable(HydroCouple) + +if(NOT TARGET HydroCouple::HydroCouple) + message(FATAL_ERROR + "HydroCouple was fetched at ${OPENSWMM_HYDROCOUPLE_GIT_TAG} but did " + "not define HydroCouple::HydroCouple. The interface target's name " + "changed, or the pin points at a commit that predates it.") +endif() + +_openswmm_hydrocouple_report("fetched at pinned ${OPENSWMM_HYDROCOUPLE_GIT_TAG}") diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 000000000..fb07d61fc --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +www.hydrocouple.org diff --git a/docs/Doxyfile b/docs/Doxyfile index f3f754413..86f8f7da8 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -48,13 +48,13 @@ PROJECT_NAME = "OpenSWMM Engine" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 6.0.0-alpha.3 +PROJECT_NUMBER = 6.0.0-alpha.4 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewers a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.3)" +PROJECT_BRIEF = "Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -293,7 +293,8 @@ TAB_SIZE = 4 ALIASES = "license=\par License\n" \ "description=\par Discription\n" \ "mod=\par Modified\n" \ - "moditem{3}=\b \date\1 \author\2 \3\n" + "moditem{3}=\b \date\1 \author\2 \3\n" \ + "status{1}=\htmlonly\1\endhtmlonly" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -1002,11 +1003,10 @@ INPUT = ../README.md \ ../src/output \ ../include \ ./images/*.png \ - ./manuals/user/figures/*.png \ - ./Updates.md \ + ./manuals/engine/figures/*.png \ ./authors.md \ ./manuals/manuals.md \ - ./manuals/user \ + ./manuals/engine \ ./manuals/reference \ ./manuals/application @@ -1122,7 +1122,7 @@ EXCLUDE_SYMLINKS = NO # exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = */SWMM* \ - manuals/user/figures/* \ + manuals/engine/figures/* \ manuals/reference/*/media/* \ manuals/reference/*/figures/* \ manuals/application/figures/* \ @@ -1140,28 +1140,36 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = +# The manuals quote worked-example decks verbatim with \snippet between +# ;//! [marker] pairs, so prose and deck cannot drift apart. +EXAMPLE_PATH = ./figures/decks # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = *.inp \ + *.rxn \ + *.ard \ + *.age \ + *.heat \ + *.py # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands # irrespective of the value of the RECURSIVE tag. # The default value is: NO. -EXAMPLE_RECURSIVE = NO +EXAMPLE_RECURSIVE = YES # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the # \image command). IMAGE_PATH = ./images \ - ./manuals/user/figures \ + ./figures/png \ + ./manuals/engine/figures \ ./manuals/reference/hydrology/media/media \ ./manuals/reference/hydraulics/media/media \ ./manuals/reference/quality/media/media @@ -1474,7 +1482,8 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = ./custom/css/doxygen-awesome.css +HTML_EXTRA_STYLESHEET = ./custom/css/doxygen-awesome.css \ + ./custom/css/manual.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1489,6 +1498,7 @@ HTML_EXTRA_FILES = custom/js/doxygen-awesome-darkmode-toggle.js \ custom/js/doxygen-awesome-interactive-toc.js \ custom/js/doxygen-awesome-paragraph-link.js \ custom/js/doxygen-awesome-tabs.js \ + custom/js/manual-interactive.js \ custom/mathjax-config.js # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output @@ -2584,7 +2594,7 @@ SKIP_FUNCTION_MACROS = YES # the path). If a tag file is not located in the directory in which Doxygen is # run, you must also specify the path to the tagfile here. -TAGFILES = +TAGFILES = tags/swmmvis-manual.tag=https://www.hydrocouple.org/openswmm.gui/ # When a file name is specified after GENERATE_TAGFILE, Doxygen will create a # tag file that is based on the input files it reads. See section "Linking to @@ -2611,7 +2621,7 @@ EXTERNAL_GROUPS = YES # be listed. # The default value is: YES. -EXTERNAL_PAGES = YES +EXTERNAL_PAGES = NO #--------------------------------------------------------------------------- # Configuration options related to diagram generator tools diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index e039e7e0c..fbb53652f 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -5,7 +5,10 @@ - + + + @@ -62,7 +65,7 @@ - + diff --git a/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26.md b/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26.md new file mode 100644 index 000000000..2efe37263 --- /dev/null +++ b/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26.md @@ -0,0 +1,132 @@ +# Python bindings implementation and validation + +Date: 2026-09-26. Repository: `openswmm.engine`. + +The approved review's binding gaps are implemented and locally validated using +the **Conda `openswmm` environment, Python 3.12.13**. The original review and its +118-function inventory remain the historical baseline. This report records the +resulting code and separates local evidence from release checks still pending. + +## Outcome + +| Measure | Result | +|---|---:| +| Current modern native exports | 1,173 | +| Recognized executable binding uses | 1,170 | +| Documented compatibility exclusions | 3 | +| Unexplained binding gaps | **0** | +| Original missing exports implemented | 118 | +| Additional staged-writer export implemented during this work | 1 | +| Installed-wheel tests | **1,221 passed** | +| Minimal-build tests, optional native features disabled | **37 passed** | +| Standalone source-contract tests | **34 passed** | +| Engine type-checking | **40 source files passed** | +| Strict consumer typing, source and installed-wheel runs | **passed** | +| Sphinx HTML with warnings treated as errors | **passed** | + +The exclusions are `swmm_get_current_time`, `swmm_get_last_error` and +`swmm_get_last_error_msg`: Python provides current time and typed exceptions. +`swmm_error_message` is recognized through its executable `.pxd` helper. +Reachability verifies that a wrapper calls an export; it is not numerical +validation of every native process. + +## Delivered domains and regression coverage + +| Area | Python surface | Principal evidence | +|---|---|---| +| Aquifer hydrology | `surface2d.groundwater`: rows, options, nodes, scalar/bulk state, sigma columns, ledgers and species | `test_groundwater.py`: mixed cells, authoring units, save/reopen, inactive/stale states, array ownership, water residual | +| Groundwater transport | `.groundwater.transport`: parameters, sorption, initial quality, boundaries, sources and source-species terms | `test_new_domain_tables.py`: all table round trips/removals, quad edge 3, sidecar reference, species snapshots/ledgers | +| Surface quality | `surface2d.quality`: coverage, initial loading, curb length, runtime buildup | `test_new_domain_tables.py`: scope precedence with nonzero buildup, bad coverage, round trip, independent arrays | +| ARD transport and capability | `solver.transport`, `transport_matrix`, thread diagnostics and typed records | `test_transport.py`: invalid coefficients, matrix axes, thread limits, US/SI persistence with registered component file | +| Existing metadata | Initial-quality file/is-file, heat series names, component registry, relative time metadata, authored link orientation, compatibility writer | `test_metadata_bindings.py`: round trips and all compatibility profiles | +| Editing, output and forcing | Batch deletions, live output refresh, local climate/temperature/age/seepage forcing, staged serialization | `test_binding_completion.py`: atomic invalid batches, duplicates, partial output records/footer adoption, callback failures and reentry rejection | +| 2D diagnostics | Rainfall, accumulated rain/coupling volumes, weights and output selections | Nonzero mixed triangle/quad rainfall fixtures in both US and SI units; scalar/bulk parity and volume increments | +| Safety | Owner retention, invalidation, callback error capture, per-owner access guards, file-reader guards | `test_native_safety.py`: destroy/GC/transfer, callbacks, independent and conflicting access, subprocess use-after-destroy regression | +| Packaging and typing | `py.typed`, public exports, new stubs and optional import behavior | Installed marker/source checks, stub/runtime signature checks, strict consumer typing outside the repository | +| Reports | Current routing diagnostics, percentage conversion, snow/forcing/coupling/groundwater totals | Snapshot values compared with the native-backed mass-balance view after a completed run | + +The GeoPackage bulk writer now validates matching lengths, copies strided +arrays, handles empty writes and refuses reads after close. Native series reads +pin their file handles against concurrent close or refresh. The 2D/editor views +retain the Python engine owner rather than retaining an unowned native address. +Callbacks cannot unwind through the C ABI; the first exception is re-raised +when native execution returns. + +## Documentation and CI + +Sphinx now includes guides for native-call safety, transport capabilities, +groundwater/transport, surface quality, batch edits, live output and staged +serialization. They state lifecycle, indices, units, snapshot ownership and +persistence rules. Existing metadata and mass-balance guides, type stubs, +README, changelog and the application manual's Python chapter were updated. + +Two details established by tests are explicit in the documentation: + +- ARD persistence requires a registered process component and configuration-file + path. Setting a dispersion value alone does not add that registration. +- Native continuity-error accessors return fractions; report fields named + `continuity_error_pct` now convert to percentages. Report diagnostics use the + current typed accessor instead of silently probing retired method names. + +CI has a reusable source-contract gate and an actual optional-feature-disabled +build. The gate is a release dependency. Wheel testing includes modern, legacy, +top-level and integration tests; only typing fixtures are excluded from runtime +collection. Typing triggers include Cython and native headers, and the Python +workflows include `swmm6_rel`. The old fuzzy parity report is marked historical; +the regenerated provenance report shares the strict tokenizer and counts +1,173 exports. MCP-only exclusions do not exempt Python bindings. + +The minimal build exposed native 2D references in core routing and reports that +prevented compilation/linking with 2D disabled. Feature guards fixed those +build failures without changing the enabled-feature behavior. + +## Reproducible local validation + +Interpreter: `/Users/calebbuahin/miniforge3/envs/openswmm/bin/python`. +NumPy 2.4.4, Cython 3.2.4 and pytest 9.0.2. Additional mypy/Sphinx dependencies +were loaded from a temporary directory; the Conda installation was not replaced. + +The final local wheel was built with 2D, GeoPackage, HDF5 and the OpenMP GPU +plugin enabled, and **both experimental fast-kernel switches disabled** to use +the release-default numerical behavior. It was installed with `pip --no-deps` +into `/tmp/openswmm-conda-wheel-installed`, then tested with the Conda interpreter. +All 62 Python source, stub and typing-marker files matched the built wheel. + +```sh +conda run -n openswmm python python/scripts/test_staged_package.py \ + /tmp/openswmm-conda-wheel-installed python/tests --ignore=python/tests/typing -q +``` + +`test_staged_package.py` removes only the OpenSWMM editable redirector for that +process and asserts that imported package modules come from the requested +prefix. This matters because the environment's editable install otherwise +selects older extensions despite `PYTHONPATH`. No installed environment files +are changed by this test runner. + +For a plain CMake install, `python/scripts/stage_python_sources.py PREFIX` +copies the Python modules/stubs that scikit-build adds to wheels. The minimal +build disables 2D, GPU, GeoPackage and HDF5 and exercises omitted-feature imports, +core solver lifecycle and transport configuration. + +The companion JSON preserves input hashes, audit output, wheel hash, feature +settings and complete final runtime test summaries. + +## Remaining release qualification + +Local implementation and macOS arm64 validation are complete. The following +remain external release checks, not claimed successes: + +- Run the updated GitHub Linux/Windows/macOS and Python-version wheel matrix. +- Validate portable dependency repair and minimum-OS tags. The locally built + `cp312-macosx_26_0_arm64` wheel is a local test artifact, not a published wheel. +- Run sanitizer builds where supported. The local safety regressions include a + subprocess test, but no ASan/TSan run was performed. +- Validate external documentation links/intersphinx inventories. The successful + Sphinx run disabled external inventories and retained the repository's + existing warning suppression categories. + +The earlier CI fix remains commit `4895765e`. The implementation commit includes the +bindings, documentation, contract gates and their native writer/build dependencies. +The validation above ran in the working tree alongside pre-existing work in +progress; the companion hashes identify the tested inputs. Unrelated changes +remain outside this commit. diff --git a/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26_evidence.json b/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26_evidence.json new file mode 100644 index 000000000..1c05101e7 --- /dev/null +++ b/docs/analysis/PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26_evidence.json @@ -0,0 +1,394 @@ +{ + "date": "2026-09-26", + "scope": "Python binding implementation and local qualification; original review remains historical", + "python": "/Users/calebbuahin/miniforge3/envs/openswmm/bin/python", + "python_version": "3.12.13", + "conda_environment": "openswmm", + "versions": { + "numpy": "2.4.4", + "Cython": "3.2.4", + "pytest": "9.0.2", + "scikit-build-core": "0.12.2" + }, + "features": { + "2d": true, + "geopackage": true, + "hdf5": true, + "gpu_plugin": "OpenMP", + "fast_xsect_lookup": false, + "fast_manning_pow": false + }, + "wheel": { + "path": "/tmp/openswmm-conda-release-wheels/openswmm-6.0.0a4-cp312-cp312-macosx_26_0_arm64.whl", + "sha256": "f9f6eb334e3dac6e5c23bf6b7f91a757c4ae4494d176151873be9ec4d6d3bd9d", + "installed_prefix": "/tmp/openswmm-conda-wheel-installed", + "portable_repair_validated": false + }, + "audit": { + "totals": { + "c_functions": 1173, + "pxd_declared": 1173, + "c_enums": 42, + "py_enums": 78 + }, + "unbound_without_exemption": [], + "intentional_exclusions": [ + "swmm_get_current_time", + "swmm_get_last_error", + "swmm_get_last_error_msg" + ], + "functions_missing_from_pxd": {}, + "declared_but_unsurfaced_in_pyx": [ + "swmm_get_current_time", + "swmm_get_last_error", + "swmm_get_last_error_msg" + ], + "enums_missing_from_python": {} + }, + "validation": { + "installed_wheel_tests": { + "passed": 1221, + "seconds": 90.36 + }, + "minimal_build_tests": { + "passed": 37, + "seconds": 1.36 + }, + "source_contract_tests": 34, + "mypy_sources": 40, + "strict_consumer_sources": 1, + "installed_consumer_sources": 1, + "sphinx_warnings_as_errors": "pass; external intersphinx inventories disabled", + "python_sources_stubs_marker_identical_to_wheel": 62 + }, + "remaining_release_checks": [ + "GitHub cross-platform wheel matrix", + "portable wheel dependency repair verification", + "sanitizer builds", + "external documentation links/intersphinx inventories" + ], + "source_sha256": { + ".github/workflows/deployment.yml": "cb934f45ffdaee4e244508c4c29669b712aa7f3440abd5769bd22430f2b558bf", + ".github/workflows/python_contracts.yml": "a38515c4372653d89d85a3f6f9ac27fd5205ca51a45d52b5c3d12704ce9d8ed3", + ".github/workflows/typing.yml": "41780d692c6e70a723fcfefb5d1d1f77d0f9be5a5b938ff715d96d7d1a6822cc", + ".github/workflows/unit_testing_python.yml": "13cf0b7a0406853d868ab12f4364d5e419e2948f6e4981931c1a1540488ae225", + "include/openswmm/engine/openswmm_2d.h": "268d399af5e5d0854ee6d9d7007374ca5dbbc46d648f199d98b9c82a3b9a21d9", + "include/openswmm/engine/openswmm_callbacks.h": "b9478a3215576729f8ec9dfbaedc5dfa71fa9a314dbc909bd31f1e13507c23bf", + "include/openswmm/engine/openswmm_climate.h": "abe39b945d12c733b9c5e80e3e0e01283215b0f41b0edda311e988d5f7a0fd79", + "include/openswmm/engine/openswmm_controls.h": "d9044dffb854deb66032db6b64843edf6ace9a807984d9a2e6adbd2ee77c45e8", + "include/openswmm/engine/openswmm_datetime.h": "585fd3307bff50e0118730d511f7e4ebb93ef0441a4636184fdf4f318270861d", + "include/openswmm/engine/openswmm_edit.h": "8aa855f546f523050ac40661167f32c0bd15b47746000d6be1301d3283aa9955", + "include/openswmm/engine/openswmm_engine.h": "60572711a25256d79fe5d4d4792ac5465b63e62c600c8815c14e35e91aec2c44", + "include/openswmm/engine/openswmm_engine_export.h": "2bdfbd8f07f33540dd2225a0f19415000afabe7f5e6c026daeaaae0d62434ff7", + "include/openswmm/engine/openswmm_forcing.h": "0488d4e4f1b0526f14589ca1a531426f99c986df1927e3326613bc36ad212cb1", + "include/openswmm/engine/openswmm_gages.h": "ba2a26d0f4dfcc64d43146ccda1eb253b72ede3c9c9cb281793e2e9f445561ac", + "include/openswmm/engine/openswmm_geopackage.h": "de86f4e904bfcefb65320e7be3e964077fde8b8db06e54e0d9d89f1243650f45", + "include/openswmm/engine/openswmm_gw2d.h": "4c0b3da7ddde9bdcfd4a084c0ab4965e6ea95276b203ded9d102eca2881e5d6f", + "include/openswmm/engine/openswmm_gw_transport.h": "4623357082c47c9d0b5f4e06069d4d167fafbfb331be6c1a186cc2e781f8dbf3", + "include/openswmm/engine/openswmm_heat.h": "8495210d3006a20a823fc3139066257af4f657e5643b094c580ce272b1304208", + "include/openswmm/engine/openswmm_hotstart.h": "1f6ae581f9cecbc5ab05feba89cc79ae66b968031b7c69fd64a0e308c7c9c49e", + "include/openswmm/engine/openswmm_infil2d.h": "9210857c289caa28d2a25161584669439692e60d9b4989e0805ebfe5d89060e0", + "include/openswmm/engine/openswmm_inflows.h": "ef8e7e5c047a750f00d6b4d04ea71d3fe78812b6f951a8d0b6237e60f22b73ff", + "include/openswmm/engine/openswmm_infrastructure.h": "9798057095169c49d7f77f306d6e3e6a686c72f7055a0f03729675aa1f7641b2", + "include/openswmm/engine/openswmm_initial_quality.h": "48ccfc67100b9f70078190a5ac83c9e747e2f2c46042c6adf6dfaf3913ba5917", + "include/openswmm/engine/openswmm_links.h": "23035dd45330ecf1935e1376dd1e25aaa5cb2f56e4d7ccb5d587ce06de079193", + "include/openswmm/engine/openswmm_massbalance.h": "d6f904cc1e7fa45f73adcce1b07beacc95f6ac5210c158c4408fd8737e098a4b", + "include/openswmm/engine/openswmm_model.h": "b59cca6d8e62e28f88b306678a88423a7e489d75faab941e5fd6628cdc3f4d72", + "include/openswmm/engine/openswmm_nodes.h": "7d35699f13ce94002673d87333d2d8acc68e203834b429ca03c65444b65ec070", + "include/openswmm/engine/openswmm_output.h": "0df7cc589e065c7e6611b94b3c997de0c27fe4384d2f593bb8ee97044182b48b", + "include/openswmm/engine/openswmm_pollutants.h": "5a3e13ed50c066ec20ffebc5524a8d6ae7eea74ba41a52894a6c1c09bf166045", + "include/openswmm/engine/openswmm_process_components.h": "9c9d0010018be37aa3bb62a088d5a1a902967fc76832872736a66782fdd57526", + "include/openswmm/engine/openswmm_quality.h": "f1d650bca9a5b03f9d18d3eda98823814acd473e54fc613b3e4a61965de8eeb9", + "include/openswmm/engine/openswmm_reactions.h": "deea68c6852a3a7e780eccc0edf957714662de49592849e21e7c66d3ac4e9e49", + "include/openswmm/engine/openswmm_spatial.h": "45ffcd0fe1421b1c35500a49d2b6b4a6bcfcd191cdf053ecdaa0ddebe0caad4c", + "include/openswmm/engine/openswmm_sq2d.h": "c60ac1ffc13c125687e3916055f09f2e9fb0a83d57ddcf6467af37f4ac240de5", + "include/openswmm/engine/openswmm_statistics.h": "131e483be0a6a2661a36a809077e541149896ef64d1340a8736dd04c4db51c22", + "include/openswmm/engine/openswmm_subcatchments.h": "20592588c70de0ab6abda4ddb0d30e60b417c6c3fef717a9a8429074dccbb71e", + "include/openswmm/engine/openswmm_tables.h": "c37c668e16ef16f5ba0df132955dc86bbf7fbab60936671a42c4aefb3bcc14ce", + "include/openswmm/engine/openswmm_transport.h": "e07bdfea9b24d8707950986dd7e37e2969e2705bc504408ca91235f3791670f2", + "include/openswmm/engine/openswmm_water_age.h": "5e02a102c515600156a1e519ee06b3bfbaed7786238032b9c3843025f1b0bb89", + "include/openswmm/engine/openswmm_xsect.h": "0c601562cddb7a15d124e4efc38ec70a1da3081fcc96b066dabb9cae401cf549", + "python/CMakeLists.txt": "ec1d3ab3fda23627d171def0850dd491f6065bec88c3cf31b28891ae49f4b228", + "python/cmake/CythonHelpers.cmake": "b5d57d299d333dd813299672754a01f577b9f4390349273bc0d32058fdab765f", + "python/docs/api.rst": "0eaf0125e24d9ca49d9923e7bf574617eb4a3bcfa536573ef42c624b0cd37b3b", + "python/docs/conf.py": "ee445eaf0cb92a13db003bb697cf8062c6950a55b603dc529d30b24b47d2a18e", + "python/docs/guide/2d.rst": "574eb3c3ea3a1c8ac0a6144bc5e3412b9fca6dac07ffa80589e2391f354154b9", + "python/docs/guide/binding_updates.rst": "f05f8dea739f04e599c300dcad53b19cc468ac7c7108cd9dd87993f35eabccb3", + "python/docs/guide/climate.rst": "3255d74cf6cf5e392ab8a8ca2598430c5023199a5e8da82c70bed686cf619767", + "python/docs/guide/concepts.rst": "ff7e77d7788c577317e11a499d8217c8e14da848d14d3f4e557cfaf4b533079d", + "python/docs/guide/controls.rst": "babb416a7c727dd2c6f928da69c4486be2046a30dc867f2c99f41817d0485327", + "python/docs/guide/datetime.rst": "0f8bc61a5919e1ed337c19f254f066db326c74b1d14e055cf4609bb60f138c7d", + "python/docs/guide/editing.rst": "3b716d94397ef09d4ad5fa8bd3ad0ac3cff51105db7c4a6780bd2f5b72c4ffef", + "python/docs/guide/error_handling.rst": "038b7c48432bee9d86e553ed09492ad00c6668dbec4d145c3cb2540a0d466ff7", + "python/docs/guide/forcing.rst": "1e3fdafcb6aa7a7a1a81b803b33c05514e41098d8360fa22d328a75df00aa2a7", + "python/docs/guide/gages.rst": "7cc0be27d677ad612ca58a37c175fa6d5990f8532298eecec48e0ea330da9768", + "python/docs/guide/geopackage.rst": "daea25d08f4d7475a3a26d12983de653fbb452faaee8ca528fd7e0ac74a91b4d", + "python/docs/guide/groundwater.rst": "fb5a160a28c35d4a8d1622dc40acb45669d34bce17d3e550de80ea4d0d4c410a", + "python/docs/guide/heat.rst": "1f4391d06ec3deef9ac435816167ffb4b7f16680e81c7314983ac36ec7f66915", + "python/docs/guide/hotstart.rst": "a9bf60bc027f1cea556a68aeb99fce5c0dc13a2047f5d60eef83af685050d485", + "python/docs/guide/index.rst": "d40be4729dfb7e0e6e136c0e70a5f741b79507dc06f2d108c3c1f8345c5ab846", + "python/docs/guide/inflows.rst": "9925e74d465658c085f83d8961621f44bf73a17b9e4419147602f97c3f496f3e", + "python/docs/guide/infrastructure.rst": "657a493bdba7b8d10fa9577edd0ecb94462699c48136022c5a4657b3fbe2cce3", + "python/docs/guide/initial_quality.rst": "6779b35f3e574b6ca764ee696c67b29e8045ce7da2c5debe1326fc741b5e6931", + "python/docs/guide/install.rst": "38a64479c78b92ad104035d64a6d4af9115a11c8a7c69bc78a6339bbe9527100", + "python/docs/guide/links.rst": "2a5faa82a670a35a1954497b7b3f586f1de5bd9e53fa59d5b817f61de83b1d88", + "python/docs/guide/massbalance.rst": "0f5df4e96f6d0cea4867ff55b6164005ec4d8cfb5e8e459e6d86fb5c4ed4d734", + "python/docs/guide/model_builder.rst": "993b9ac47157a630701397636d61dcb6643fec3bfad0ab4ae09a3c7bfd6e0705", + "python/docs/guide/native_safety.rst": "f40d4f6a54edf43df4d5df65f6aa9ed34391dcfa69043dbc52fc71a7623bd9f0", + "python/docs/guide/nodes.rst": "7ebac5e2080d0175f72600826f822d2210559db1e6ded5c7c678da2534c1984d", + "python/docs/guide/output_reader.rst": "64fc6f8d56f9fbfedbfdd7cbd47eea6d485784e9d59c75eeea755f43983fd1d7", + "python/docs/guide/plotting.rst": "f9173d62e83d2d79dc9bea9702c2c39924ea8c2554129cf8395ba455889e6a5e", + "python/docs/guide/pollutants.rst": "3c7856e9f973545402c701ad2dcecceb149faa6d98a943e258f8c7a1731269ab", + "python/docs/guide/process_components.rst": "c4f72dc7802e4ef6f0021316b20b557430b91f1d1c64febaed2322d6521fe846", + "python/docs/guide/quality.rst": "5a284ea6d2f059e259ea8dc276e1a357dc3227baa88b213583ce127aae89d924", + "python/docs/guide/quickstart.rst": "f63631d93aa5d337a8cc8f41ea75e73bd01238363955ce8d4e29ecf34e462308", + "python/docs/guide/reactions.rst": "1dc363c09c3eb6890cbfd6d596d5b4f564c5f404ef36ff11b046820159dbe0bf", + "python/docs/guide/solver.rst": "66db755252d8e56ddea02191e24e99687112c86df880e4bdc362a5fc8a244d1c", + "python/docs/guide/spatial.rst": "d62b8f309e74a6d1d32b00831913659da434aac4dacd337de2e6c9ff59842ba4", + "python/docs/guide/statistics.rst": "692221411cd6dba10beec9982c8c9e59cffa737462607208d60cb1974366f163", + "python/docs/guide/subcatchments.rst": "e3c00128d109bbce40e528baca3408600b5a20978eb4ca86c69a4176445a0f49", + "python/docs/guide/surface_quality.rst": "ca3e7726229470fbaeea757bd71b030e7a816570bb95e8f0c2569311b4d34270", + "python/docs/guide/tables.rst": "e1085046b1cdaab9e1ff763796d7ea5a22b5d6c422861d26aae0f2a6e9836bbe", + "python/docs/guide/transport.rst": "71732b4cbe861130a4cff66e0cc5cafd97e358c65f6e94582afd12ebd5803131", + "python/docs/guide/water_age.rst": "b24a7852e8c567d8711cabb793768e80a4a639757caf8532684d98862660282d", + "python/docs/guide/xsect_geometry.rst": "18f9421de50772a8e8b639d2a68143c010637165d5fb2d0a284803ab7bbf99aa", + "python/docs/index.rst": "2ac546b5c12c0dbdf7f4db1155b5cff53b80c11c98e8b60a5f58554063610ea7", + "python/docs/legacy/index.rst": "2ebcbf032a47a6b6079a15ffdf792a78e928d9fd578a118eccc6179f783e9428", + "python/docs/legacy/output.rst": "8ae087871b39a173259ca19f6cec23d6eef2cfdc7180199331f0765b4a948071", + "python/docs/legacy/solver.rst": "958949e9b0a4e8337d9ed8503ae483254af34bdeb301ab6b2f75ca5209e20ebb", + "python/docs/license.rst": "e45c68e560c9ec410008321fa0470d163c2ec8ffe4bfc3154a7b87eea339f835", + "python/docs/migration/swmm5_to_swmm6.rst": "3f963d36e02eea26cde22c82eb7b2c2984566e5e628cc501e92dc15f5e71d1fc", + "python/openswmm/CMakeLists.txt": "9c74c2b1cd674e38192e79d5adbb8855f89645843380318384a601954f26e9f5", + "python/openswmm/__init__.py": "a1457d58b2aa3ca34faacef4c87cc3c5cd6c85cfddf73d98ca22934b913e35bb", + "python/openswmm/data/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "python/openswmm/engine/CMakeLists.txt": "5b7cca3cc0fccfd59aa1ebde96930d4be286a30355f8cf5d90ddb3e5eedcf714", + "python/openswmm/engine/_2d.pxd": "828bf46e8a9b72dcfc1c32cdd7eddc81f3bff2a917d186ad61fba7dba118b76e", + "python/openswmm/engine/_2d.pyi": "262ccf72b65348ff2af4a2d2d441a3a0e82469acd93659230979fc7b5668ac80", + "python/openswmm/engine/_2d.pyx": "a57529fafc4d83404112a6f185a02d377a8e3af189969a18e5a3e72280a7896a", + "python/openswmm/engine/__init__.pxd": "15e77b6f88304122823ffcdaaa59cda9e78ccf21ddd744a96f6ddc0b44044b76", + "python/openswmm/engine/__init__.py": "69373d9856e082350fb896a6a9713d9a41996d9bf85b95973ee136553d4d51d2", + "python/openswmm/engine/__init__.pyi": "59e41d9a84e2b63114fb90a9e0b2a4ad1041fc720637e9180fcfe1bf1306f908", + "python/openswmm/engine/_access.py": "f236d12f627cfccf5c4fcacf260affd6d51570a702ded62a4495d3aa4857e741", + "python/openswmm/engine/_climate.pyi": "36218586d6d88695c08db76b748449cf1eafc955b02c37c6a7dbb103afbde966", + "python/openswmm/engine/_climate.pyx": "93dde91cd1ae8ec54a2eeca8c044f3ee7c5342d50a3b6463ef54fa31f8177304", + "python/openswmm/engine/_common.pxd": "b5f5363dd9f665f75c879a486a6a6d5771500f944aa857857ff08eb5eaa44c02", + "python/openswmm/engine/_controls.pyi": "72f315dab3f59d4fc623d06471b7aa8d376bcf21e56fde8ab14507e04cf12843", + "python/openswmm/engine/_controls.pyx": "0c4bff6e72680a62a0990e7cbb0b546e4be4f1b2350725ee11f14c7bae9c0600", + "python/openswmm/engine/_dates.py": "fff1d2eafa776616c2773d67caab6d63f41cccafbce9bd983d3331fe3f85d655", + "python/openswmm/engine/_dates.pyi": "da0aa2d7be8bc29223ba4a94ce2a5df9740a1cdf10ab47430615d370f3c28d31", + "python/openswmm/engine/_datetime.pyi": "cb252791b765467e8cfd01e7d502321f5b3481c8de1b3fb5f5d776d669c6ad5d", + "python/openswmm/engine/_datetime.pyx": "ae2bce8e1ead01d4a539d703f837cbf979ea71060ad0eb40414a4111248cb588", + "python/openswmm/engine/_edit.pyi": "8f6f05235b0a85fbb7797f5ba8da31f6de35f4530eb178f42b3397771b206cd8", + "python/openswmm/engine/_edit.pyx": "557de4283f7c9cdc06f73f7d734f3279de088104132fb199913de531dd44ec0f", + "python/openswmm/engine/_enums.py": "2769ebeede9aecef37b67687beb6a56c716dede0f5745fbdec4a5f9d4d259407", + "python/openswmm/engine/_enums.pyi": "750aa30dd2e46dd9fc66fb2584e63b294fabc959c6f6fb4060dd2ad18fea0b32", + "python/openswmm/engine/_exceptions.py": "3be9371c3a77101a248d5ea7fec064bc5894ba3d6582d77c7095159c8e2ca37e", + "python/openswmm/engine/_exceptions.pyi": "cf365bd80fc95cfe51b4b881cb7e47e47e5e2a20298693cc64a22d993e897d27", + "python/openswmm/engine/_forcing.pyi": "d3b2ecc8433181259211b4fa1b92cbf46d55e9147394b86487f5e9afae5c056b", + "python/openswmm/engine/_forcing.pyx": "d28049451d99e69bd4091bf3da96f066bb9fb18afe1389e746711996c41597eb", + "python/openswmm/engine/_gages.pyi": "c5166e72835b280b65abbb3b84e437ea3e50651e2609738a2bf281b08a1d8ad0", + "python/openswmm/engine/_gages.pyx": "8f3ac58547b72800aaaa65905909b7b54a0edc92fd38e815de9323a0a6af723e", + "python/openswmm/engine/_geometry.py": "380ed55ffc17fa84276a7415518e97ba88e5e463cae41ccc1f0131d629022549", + "python/openswmm/engine/_geopackage.pyi": "7d3e452b7c181e76c62223363f0663f53076352c51625a3a9cdd453d4e70efe8", + "python/openswmm/engine/_geopackage.pyx": "4f1b5b24cd3fabd6d6fc8f287359658752e88ac6eb4e5c0bd8d447164dfcd057", + "python/openswmm/engine/_groundwater.pyi": "426bfa4556728d76ee2b2061aa3c49ee5c1852f8135962f5bc2b4ece16d0fcda", + "python/openswmm/engine/_groundwater.pyx": "c1b69b9d47344577386edd924487bc6c3626b730ab61e5c3cd37d2e8d773dc5d", + "python/openswmm/engine/_gw_transport.pyi": "6fc2c018fe351b6578379d2d48c237a98281348dce7b15d02606b9cdae0725c8", + "python/openswmm/engine/_gw_transport.pyx": "0131e523e6ab98c45d3ed099e37795c41cfd86c37c8aec5edd76d6913cad187d", + "python/openswmm/engine/_heat.pyi": "9994202dff8f4e0a532bdedcdbd8fd1bda59dedcd4a818c9d25eec15caddb698", + "python/openswmm/engine/_heat.pyx": "d38d2aa9aaf91e1d65bd02a0e26eaa851e6792c38f53e2c78c6e9df5c804f5e3", + "python/openswmm/engine/_hotstart.pyi": "366c0d948bdf70f27e920cbb1f642fc9434b0c6d804c323f4db914f7baac262e", + "python/openswmm/engine/_hotstart.pyx": "81152602030c9410a33bb659a1631ac4e000b19ed0eb651e0362cd8f0764d9d8", + "python/openswmm/engine/_inflows.pyi": "48a7e6020ba067bd75f5a16c35f494a32f39b9455a04d6f1e1cb2e5a5aa8c1bd", + "python/openswmm/engine/_inflows.pyx": "73cab4cacb2ba3991db46f09f11ad4dfdb88054a13a688ba90fe2f4000841017", + "python/openswmm/engine/_infrastructure.pyi": "824ca5a5f17d826389ba79bbf89c13531eda7b88e8df3ccde8c00d871234929e", + "python/openswmm/engine/_infrastructure.pyx": "cff580fc4df7ffd0ba4ee9041f0ca1111c856044c1f45028c8e7ddb16f39aac6", + "python/openswmm/engine/_initial_quality.pyi": "0260be4ed72f25cadfe1847fed8327b185caa1dfac1954f1d6b0c6d82dae34ea", + "python/openswmm/engine/_initial_quality.pyx": "bd0e79798c5cee786e44d7632e8a39efde4b45ee7da2182e42d6beafafa29440", + "python/openswmm/engine/_links.pyi": "0b1a90750566c5928ce4bc1a6d931d3be5fe3e5fdff616ca4cdcb647d28c6b44", + "python/openswmm/engine/_links.pyx": "020b315f33f062556000dd231fe2ba483905058a41e236fc51e03e861a5e643d", + "python/openswmm/engine/_massbalance.pyi": "3cf3c3a056ef77bfdfcd736e57273b9489aa8fd9381c3167d873147bd8853406", + "python/openswmm/engine/_massbalance.pyx": "79d370f31cb9c671ced97e4e632b30dade40e8b418b634f7d96828a1f5594035", + "python/openswmm/engine/_model.pyi": "b4d8a1d0d4852252f204b0f43758ef801ad1ab543ab9162b8c39e6d12e2a9a2b", + "python/openswmm/engine/_model.pyx": "009e5dbaa19f33f029c2883afc23093de5eeef5e2db5c56b9f777ebb94344625", + "python/openswmm/engine/_nodes.pyi": "86f32c19b887376b0b63c2d3e1fe20541e9530a9a7824d1022b1f9f356ba6694", + "python/openswmm/engine/_nodes.pyx": "fa409cd3d24713876135bf95ff86b587f3d23f82b302e68c719d3bde6e6c6e0a", + "python/openswmm/engine/_output_reader.pyi": "881a7d9bee717105768d4540c3e985b73d8d031d6f66069677596d000c73311b", + "python/openswmm/engine/_output_reader.pyx": "aaf4c2ad900154fc258777b055849f99b4003aabc75644a908e133dac1515c37", + "python/openswmm/engine/_pollutants.pyi": "3709a7b81bfafbddd77c36c86510c82b05b987d47e74d34592f83c374dfed9d0", + "python/openswmm/engine/_pollutants.pyx": "123eeba3e36cfe3d5afd6b8f2e07aae7368426f5e66087286e8a6d9809e720a2", + "python/openswmm/engine/_process_components.pyi": "e2690929c68113ca9c6c408bf06157e0b6148e11cf78e1b6f8a2f180b18ca033", + "python/openswmm/engine/_process_components.pyx": "ecf32250113dd5cd3c2881d01445514f80de54bdcddbeaab391e36de05c4b159", + "python/openswmm/engine/_quality.pyi": "ee1a785b33f2c7797fff2d0bf7b04b929b26e53e0eeac269d63af886e3465f12", + "python/openswmm/engine/_quality.pyx": "a499fada754e6726dc608e40f1cb43f0e6e596902d1eb356f23811dec4e4f218", + "python/openswmm/engine/_reactions.pyi": "34399884a50f2fc387909557906f5e5e4560c12cdb40779b7cb2f54c389e4f37", + "python/openswmm/engine/_reactions.pyx": "8b3394209e7db162f728f5404f56d911f0ab1e1ff95e22679b9d0466c128d80a", + "python/openswmm/engine/_report.py": "3f324cebe4f80661d621b98962dc4bee9d04b90251d5e1cf72edd780b504d52b", + "python/openswmm/engine/_solver.pxd": "fea0a6d6fb28b25fa733296a01a58e2e085213e98573b98d6a40051c9d1f83ef", + "python/openswmm/engine/_solver.pyi": "91a266838c6440563f58b023c7d2ad150808a5091155df9ce314821c1454ee74", + "python/openswmm/engine/_solver.pyx": "e86778c7dbbb98ed769e77336f8a82d2e0c65fb241c270efa33276e8995d5da5", + "python/openswmm/engine/_spatial.pyi": "1bef90a1db14836d68effbacf36811a3f2e4a04eabfa004f82dd19641053d9f8", + "python/openswmm/engine/_spatial.pyx": "b9063c1321a5b69510198e1a80179b10a30cffd6ab543b06ce68c84ab9059271", + "python/openswmm/engine/_statistics.pyi": "3e36d9625dbcb445b51ac9897b3aa840672a1c66cd4a79ddc173ca0b05a2d8bb", + "python/openswmm/engine/_statistics.pyx": "e6596e77d584692b707ce08e5b262c454de27f0185c316facbd01ced0aa48cdd", + "python/openswmm/engine/_subcatchments.pyi": "a892f6472bf9e76e2d026c46e9675ff5cdf0816870a69fae3a9ab14bb45325ab", + "python/openswmm/engine/_subcatchments.pyx": "d848f7afa65fb1dc3d11b852a494f4978a94ca6682b9b0b41d77b48ab1c3ad39", + "python/openswmm/engine/_surface_quality.pyi": "addb38fae9a31d4611a04821d14dad5c874d4ad011fbce637e1d57214c863c83", + "python/openswmm/engine/_surface_quality.pyx": "95c4e0ee1d5677fbf184def777d04ae6ef6351496f1d12fa7ee5b7ef21b8a069", + "python/openswmm/engine/_tables.pyi": "adf38dcc669e4c5dd11bbe6996e32e0a95112eb6b9d9d130e877957de270c657", + "python/openswmm/engine/_tables.pyx": "227172992226816f875fa4e75f6a8e482be301cb7e70066cc3cd7af71224e379", + "python/openswmm/engine/_transport.pyi": "28dc438f04899f2476f29c32e95c4e62613bfea0ab9c3e28b2633fcd0171d61f", + "python/openswmm/engine/_transport.pyx": "b7d3882d8744532482b65ce54d0218e6905c82e8c27351a622ae2fceb528293d", + "python/openswmm/engine/_water_age.pyi": "3849b79d63db0dc4ad43b3af0c38ffc4d448860d6d7ab8642bbad28d72f87c14", + "python/openswmm/engine/_water_age.pyx": "11dcea5943bc3be1cecf02928e67c8066ed45b6e76153d9db30c4b36c5c733c2", + "python/openswmm/engine/_xsect.pyi": "2193922ca40d318f8d58ae7d274fe4a8b130bb341818b52beb241d9438a76507", + "python/openswmm/engine/_xsect.pyx": "82d626833df95cb7d3561190721f67a25085a918682055a17f306567ddb32bb2", + "python/openswmm/legacy/CMakeLists.txt": "5e907830f0a2281fbec3e9de86cf992fb1d4c51982a93cfa00271e541ed41441", + "python/openswmm/legacy/__init__.py": "774096ffcb03cd1931738e08d948798f1a4135212dd816d1c35bd167522243a8", + "python/openswmm/legacy/engine/CMakeLists.txt": "52064338884176e1864647f31cd2e63b552ce63438caf8def4723341f2d30fd9", + "python/openswmm/legacy/engine/__init__.pxd": "73aeafe1f91337e94fe80d5fbbc9e9aba34c6d56346054841b6ca091c9317346", + "python/openswmm/legacy/engine/__init__.py": "8e1b72ae62ad97d4c0fe41041503ff531ed0a9d3f116c3a59fcb1cab99883b27", + "python/openswmm/legacy/engine/_forcing_log.py": "d514ac58547b155b369cbd4b1f3a1c498c3879c8480dee987891801f1825452e", + "python/openswmm/legacy/engine/_links.py": "59287f6354b0302f94864ec8c8e5b5f3b39942190afffbad6de26b68779c61d0", + "python/openswmm/legacy/engine/_nodes.py": "cd8f2745076badae83193f304184e61fafbb36ddcdae6c41dd0165b69f9a0241", + "python/openswmm/legacy/engine/_raingages.py": "5df0581a5324ec19b015e31fd6e5f8bc7fd4e5abdf1bf7ae38d1dc1a93b846f6", + "python/openswmm/legacy/engine/_solver.pyi": "a4d1ffc15fa0b98b6934639387ff19627215967c0c422d7a22b7554c6772087d", + "python/openswmm/legacy/engine/_solver.pyx": "5d090cae9bea9a0d6f48b43d2c0dd1f2b89194335cbeb21b9d6eb76722cbefba", + "python/openswmm/legacy/engine/_subcatchments.py": "7e1d4869b89146fa2c2d7cde6a5f8a464066a6d632a1879b4f27ef2ab4cae82c", + "python/openswmm/legacy/engine/_system.py": "c4c12edbd3f9b5106f4d146c15d73fd6e7d5fae45b5b4a9b0887ae0c50a924d1", + "python/openswmm/legacy/engine/solver.pxd": "8b5507162c632dfd27e18170f60e84b4ba1d05d2fbe789e583c20177a88a4630", + "python/openswmm/legacy/output/CMakeLists.txt": "1f67cb167ffd5b23492be9ce9ebc1e8ed1b294913f110761e07974613f9472a0", + "python/openswmm/legacy/output/__init__.pxd": "3fa69206162dab8fcb723c813b98cb833c5ebfbba1195583b3f5f78e9ff448ff", + "python/openswmm/legacy/output/__init__.py": "21916cc3ef500ce4e6f85a17adf30ef3bee9c5c4b75655e9198f43014beed3f9", + "python/openswmm/legacy/output/_output.pyi": "2d37273d1a019bd5a1be686a6f66c25f5019e983f1f81236c3af4fac834691b7", + "python/openswmm/legacy/output/_output.pyx": "1f3b5ac42553aa7e8b69c53f255bcc21f0d3e4f25b478128906edab8e091562b", + "python/openswmm/legacy/output/output.pxd": "656538d69f0324cb44da0e6d4d7d0d1b6323538b3f08ef5647b0ae578feadf25", + "python/openswmm/output/CMakeLists.txt": "77a7ec1714557e8bfc5a6a6dde358826b30aa655c9b75b12a2ac080446194b94", + "python/openswmm/output/__init__.pxd": "3fa69206162dab8fcb723c813b98cb833c5ebfbba1195583b3f5f78e9ff448ff", + "python/openswmm/output/__init__.py": "65f5589276ef8e920a6ef5db80f3c00693f18575cf2c3c67c76046f7aca7f9b3", + "python/openswmm/output/_output.pyi": "c2dd394b5fa230e1b37beb71a20c02c204eb18dc4b97ffa0e1103aab1e91cfd7", + "python/openswmm/output/_output.pyx": "dab595b344eda4dbf25045c15cb9ac3883baaec7dadd7ccbaf0b9ec13f5262b0", + "python/openswmm/output/output.pxd": "656538d69f0324cb44da0e6d4d7d0d1b6323538b3f08ef5647b0ae578feadf25", + "python/openswmm/py.typed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "python/openswmm/solver/CMakeLists.txt": "6e41f36d62705c846288dd9b0e94e640366521d540c88a455df388266eb38270", + "python/openswmm/solver/__init__.pxd": "73aeafe1f91337e94fe80d5fbbc9e9aba34c6d56346054841b6ca091c9317346", + "python/openswmm/solver/__init__.py": "441e966d5cd5d2e9be6b760f289afa3372b6fbb8b11153a7e7828b5d005df4b4", + "python/openswmm/solver/_solver.pyi": "af426d21df5267dcad01537fb14910373ac1571e13f0342635998ea014bfd074", + "python/openswmm/solver/_solver.pyx": "9c15079e96645b3aa8f28dc5c502cfea0df4533a0eb6a67d72108ef37889cd88", + "python/openswmm/solver/solver.pxd": "bb641331ca9c9e56f6f52a5df37fba62bd3e236d4521e71f726f8adf76dc7ea8", + "python/pyproject.toml": "d7beac51e580933095ad7aca27be8977a3a9fe93811a4922a24500e2d2c440f4", + "python/scripts/api_drift_audit.py": "8be09dc46e57aa06c6181cbce45ffe8dbfd74f057b2b4394a1b17a374f772037", + "python/scripts/cibw_repair_windows.py": "5edc8787d374a3ffacf7e4c03a3e377f986ab11ec847551fbb82700c73e0e091", + "python/scripts/stage_python_sources.py": "68b79b5fe367c225ca6f36585717daf28b326ee98ef6741136ae02f8ce8eb059", + "python/scripts/test_staged_package.py": "204378ad3b1e8b089fa9ec4564f57da5c8e033e272a8db6f72c818e894e0891f", + "python/tests/__init__.py": "835bc84fd621a7633a38980b473afaa01da9b23b7f577649c31f4cbcb03c91e6", + "python/tests/_paths.py": "1bc96c79fc2cdb8f15ffba1b69bc7cf846a4c33b123490ecbee5d32baffb36e6", + "python/tests/data/__init__.py": "b226b242b47656004b8c0e8e9825273d1fdc7ba1034e67c89147afb235918014", + "python/tests/data/output/__init__.py": "57ca69e1cc4ea9b4cec8546bd84462b56ac2bea4d5f30eeb7f4970ff1a2407b7", + "python/tests/data/solver/__init__.py": "9d9ceddc89d0a3f4b48a0ddd8cbc6cd40cf022114c1de0d825bfab72a050f411", + "python/tests/engine/__init__.py": "79198af1bcffec8d8a6c67254cd11f48ce5efff34232ff3dbece39cc4e60a3d9", + "python/tests/engine/_groundwater_cases.py": "7f9bd03065f2d0fa9770fc55425dea3dc0d91d5aff6849bf2708c49f022b9e23", + "python/tests/engine/_solver_cases.py": "9b6cb63b1ae7e79f4f531a5ec93bef86b6f956f74140a9f77c1ba510b5d9e823", + "python/tests/engine/output/probe_case_sensitivity.py": "06a31ce047b9b12c02b668a1c5fbf30291ff8f08cf4ed56ef17a3eeb9cfa1d83", + "python/tests/engine/output/probe_lowercase_ingest.py": "4dc42841be34aa968afc927b5ed964ecc7628f53544cb469863296a7cbadd5b0", + "python/tests/engine/test_2d_evap.py": "0c273f49efc481c2ff8f94318afb9f3771d1e78e203c3781a45901390dd352f6", + "python/tests/engine/test_2d_ts_stage.py": "c5281c0ce21785d5351d1bbbaf3b5229a9a89f68064e3a201f1bc24d352051c6", + "python/tests/engine/test_aquifers_pythonic.py": "3461da6360582148ded8189fb9508aaa1246c8ad8530b91fde6364d5275e3007", + "python/tests/engine/test_binding_completion.py": "96ffdeacc2f142636370de23768fb026b2eb9f571d957b8092ff1c6e7e71f206", + "python/tests/engine/test_callbacks_and_xsect.py": "37aeb458ec96332c2057a8f3ac8a91cc7adf75d5695ef0c9684ee8b348096998", + "python/tests/engine/test_climate_pythonic.py": "aef93880b63a68b8c5f91cb30720a423d1cf2f57e03bfdf57884e5d295392a31", + "python/tests/engine/test_common.py": "2d004e2c30e43ae262a06cdb606744f7a1ff157024a0b5764819c6841895e559", + "python/tests/engine/test_concurrent_simulation.py": "54f1a70cc5fd476697bcc0ee5595f6caf0d008cb142b53290f081a76d31b2e9d", + "python/tests/engine/test_controls_advancement.py": "fa7136dbb7d89261fdc4cd61b43bb13afa384c4167b37426cb80fc3a709047ed", + "python/tests/engine/test_controls_inflows.py": "99bc5ebec635b3945e74c122ff2423d1b66bbcef255c88951ccb9394eefc3364", + "python/tests/engine/test_controls_references.py": "1ae5a6cbf74d51f95048231f8eb643061e631a1f055d7ba29e60f9fbbc2f75f7", + "python/tests/engine/test_edit.py": "1bc23f2b655421217876dea11447a561ce70acfbe5fa0e7aeecd4c6b4f10ecb1", + "python/tests/engine/test_edit_extended.py": "00cda7ac735d667cabdf11e79891c0c338377aee793af2fe4e68c76eac07deb9", + "python/tests/engine/test_editor_roundtrip.py": "a0af5887f9a5c7c722025c97f3ac0949ab8b776621c92de10afb543cbe57cd27", + "python/tests/engine/test_enums.py": "ba2f6ca089d56e3f089773b0a6e270f271645ca38413c2b02d63f75613984d36", + "python/tests/engine/test_files_iface_gaps.py": "9b97c0a5c6b56004b44379a4777a89cdab41b3088cd16ae52145619a8c844c73", + "python/tests/engine/test_forcing_climate.py": "284cb3eb20545086d725c033238400d5906b686fc9b092da9328237f8246a8c0", + "python/tests/engine/test_forcing_climate_evap.py": "ba518882f0233a871ed24382b9c8ccf3dbd4a557a897f41d955bdb9a4f3f959d", + "python/tests/engine/test_forcing_pet.py": "9c9e908d90460f078c66f1b9d2c885e8376116b679937216e5621c9b53e17500", + "python/tests/engine/test_forcing_quality.py": "4edc3b4cfbb9c63ddedb7b9f0cb3defcc1bf326891ff736d519b053dcf17a675", + "python/tests/engine/test_forcing_snow.py": "ec39fa3cf98816f56b15666e77e3922e61145e31b68c2280d000a700ef7816d1", + "python/tests/engine/test_gages_pythonic.py": "fb8cc4c925672d1659a1a119d006d373d0630c97e68e42553dcf84a5bc7f3f6e", + "python/tests/engine/test_geopackage.py": "57395e48df79ba9fef9e059c37474b49e794c93281519b59a9c68dcf2cae51fa", + "python/tests/engine/test_geopackage_export.py": "9f8ad0ebc92efed784f0d0006cd552d7d6b3a817b532e2a2ff168f3aa18effec", + "python/tests/engine/test_groundwater.py": "33706c2273f153643f79b9e7bda02436d4d757e5bf0d4f5f1fd5a655a82c1c3b", + "python/tests/engine/test_heat.py": "56ae02c10a394750ab54e545487277a71173080f1064f9c4e4387b5d57a57434", + "python/tests/engine/test_hotstart_pythonic.py": "68db3049b4f0dc7b4b885943dc9e1c3fbf788ae40c108343432f332164633792", + "python/tests/engine/test_iface_routing.py": "bfa0b122ada9ebd80a5d8b3b5196897b6845b7ad4fe560233a2e4cb147394bcb", + "python/tests/engine/test_initial_quality.py": "2442807916349c1815b865b08818f52719f3b58cc43193d1415cca95b4021608", + "python/tests/engine/test_inlet_api.py": "2e8a1df79418ab170df641afce65c57cea42aa6e7fab7571376e2c95d6e2fa80", + "python/tests/engine/test_integration.py": "2cf54a3d049f00a10a0c453e949a50f50abfe2a0d1c6f6d08900114d6c8e6c1a", + "python/tests/engine/test_lenient_open.py": "402d4e694ac95781efc570b8f509e55dc9d817b208da8618ab95c0d618d95a5f", + "python/tests/engine/test_links_pythonic.py": "3b1b3115ed549ba6d95c966a08bf9147889a0f25282b73fcd67bf3b8ba99ae10", + "python/tests/engine/test_mass_balance_pythonic.py": "4430c6372a87d96d3c90b1c0c1cb38ed5ba727399c4b88a683322e5c14aafbad", + "python/tests/engine/test_metadata_bindings.py": "9db13d4c09816bed4e4a3e8ecbf8340d12bd91393c94e65d74e39a9170bc7fdd", + "python/tests/engine/test_model_builder.py": "69191f5ee9e869571acf4bbc901a2426021c56796a22f890eb4d02a714d7216f", + "python/tests/engine/test_model_file_paths.py": "3ff1458bccf2562ee06dd9bf7e45d45980ef2b353738775c366747a0e733799e", + "python/tests/engine/test_native_safety.py": "4d7672d9dbc0200dcf957a3ebe65fd8aba364bbb6cdaf0546bcfa87f5b716f0d", + "python/tests/engine/test_new_binding_stubs.py": "e1006be0814ad0762011ffc933f09f91a23afa1bcff8334c50a0fa97af477ed2", + "python/tests/engine/test_new_domain_tables.py": "ccc2802b02851b25a2db33968fbae03875515c10be57bbd85fe1300918e71c1a", + "python/tests/engine/test_nodes_pythonic.py": "858d673c928f95c7dc8c7a064ada74c21490955912e80ea5640dfbb75ab17bbb", + "python/tests/engine/test_opened_state_editing.py": "bb502442736b1672cdc266e6ef8bfe5b887e4d717217069f7c8976dbf0a1e6ad", + "python/tests/engine/test_optional_imports.py": "2388d5f24ef754ac43d7138829a2e81d33b94c929a8093fc9f81a966782d8069", + "python/tests/engine/test_output_reader_pythonic.py": "712eb8afee71e80d5bdbd9fbdd9ad4a63fb36ddd2a30a06af03f774994fe2c5b", + "python/tests/engine/test_output_species_ids.py": "08e2d352738f155cd602709206bd725226ff6cd1ded69823fd25ee622e4f690e", + "python/tests/engine/test_p7_pythonic.py": "f193c89e1eb10149d722bc24a4892244273bec098d70819a8aa56d2299214cd7", + "python/tests/engine/test_p8_pythonic.py": "74de8252290823caf44bb80c694b3e16f04c8235b2a588c50015b6a74855ddce", + "python/tests/engine/test_param_runtime.py": "a9c46b2b9961d25521f8729c83cbeb28ba5bbd575e3fe74645fc43fd51d4f731", + "python/tests/engine/test_process_components.py": "6b74257a9ee9179e51d1759ee6dccdf697e18e57c82636028739c8bbc0270ddc", + "python/tests/engine/test_quality_editing.py": "8664f40275cc62fb620c323d12b1c96793db74d5a5dc98def3656b58b5590677", + "python/tests/engine/test_rdii_advancement.py": "480571987fdeb1f56261e2872aa4c5161b0dafda1d029dc650b00adca53fc793", + "python/tests/engine/test_reactions.py": "9f0ba8d2e59e00a3732b4a561e4fc69f6cab44bd9ac4bdfb54e097713f1f7ccb", + "python/tests/engine/test_runoff_interface.py": "b12485337069adaa958107daf96d170b8501f0cf753e484fa35ceccb33a7a663", + "python/tests/engine/test_snowpacks_pythonic.py": "0238914e676884220c9dcaa58c32678cbaaee701e0d827a94b79c66b7f8afaf9", + "python/tests/engine/test_solver.py": "6e9a9b6557c27b256294fa22db3797b5e586fb34e458f297e7325072ea14a48b", + "python/tests/engine/test_solver_introspection.py": "9593b46c5665c110dc758e717999f1b52915b50ffc83cec1f9b42349b3bedeac", + "python/tests/engine/test_solver_pythonic.py": "b4b791632ee72c32351dcae75218616b699aabce65cb950f076bb459c650df14", + "python/tests/engine/test_solver_units.py": "02fbc544d946be904efcf941737a319c9e768e9164485664631891dab4e629fe", + "python/tests/engine/test_state_injection.py": "7bf52e381e70ff2d57f2cc0321685a2fa343b1063297ebc03e47b3526a67a6d7", + "python/tests/engine/test_statistics_pythonic.py": "12772f691a687b3a111b7cfb59f501d77d866c461dde901eac5e47575dae86df", + "python/tests/engine/test_storage_shapes_pythonic.py": "e49001b264e97c6df3eb3ac6f0ac2f90a473f42f82b5d72a95dbe7571b647d43", + "python/tests/engine/test_streets_params.py": "9412ca0057c31ccecc1f7d64ad9c53ac856ccd63be90a9a5268dea9cfffb86a8", + "python/tests/engine/test_subcatchments_pythonic.py": "ae1c07d9292b6a84cb2dca52585403a00599ec915166cbc1ac0051d43f0c52f2", + "python/tests/engine/test_surface2d_run_stats.py": "70c78e33dd51c5de5d11f4d22c89cff775d4f40a073bf57f01ab60fab4f34735", + "python/tests/engine/test_surface2d_view.py": "0531d00450cd47113c3a6a69b827c26d2a82201fe75caaab580b765bcbc25b25", + "python/tests/engine/test_transects_pythonic.py": "fbbc240ef33568abad244901d2ed52367e5678674bf4908d49c523120009c5d4", + "python/tests/engine/test_transport.py": "1a68cb80dc058e69af760fe5702a4a0bbcb52cd6eb8e928a29cde0cdee48a36c", + "python/tests/engine/test_userflags_schema.py": "fb5e178f8762b1868db3344a1f8402ec30df0c30420f6f03bdf7b162652bc64a", + "python/tests/engine/test_water_age.py": "59e6c2fda88387fb8b67751ef466a3c9a35a0647b14db6d67208f4129c38d4d8", + "python/tests/engine/test_workflow.py": "cc734534456af9818416b0db0e6ade8234c87d78e32225fb3ac2f5d92ae5a853", + "python/tests/engine/test_xsect_geometry.py": "112e5b5f8a410cdc654c5c5b5282e99205d94765af9f4a77c5db807c8aa1683b", + "python/tests/legacy/__init__.py": "7958978068e4eb11b871d9b7062ddc0f1d9993ae50eccf8f968ef252d8fdc5e5", + "python/tests/legacy/test_output.py": "03b239c05ccd8a52ffdf16b48d73df09be62c9b6861ae02026e9f5ac2fa3bd34", + "python/tests/legacy/test_param_runtime.py": "6ac859d67dc20286a5864562d44593e3432df636ee64a48becd0a5cf89637e19", + "python/tests/legacy/test_phase1_enum_coverage.py": "ee4efe8f3e4d11da4509e3914f1f30810d0ca57ee751b5ebaa7f31532895c503", + "python/tests/legacy/test_phase2_statistics.py": "41415bd453b1f99d6c30b345cbac1551f45573473cbe11dd5f230e27fbd79d14", + "python/tests/legacy/test_phase3_oop_wrappers.py": "ae169cb9abbc7a786f68d8cebdb9404074e3d4768d1a7489f0eb2ff7d12bcbe7", + "python/tests/legacy/test_quality_sources.py": "dcd780f0e78995a97d180f43e7d0ec8bf48a50cff39cab30ce39925d43da1f6c", + "python/tests/legacy/test_snow_api.py": "2df824c149d99ecdf34284ed44deee36025f8dc43ced2972d5db0bfeb146e27c", + "python/tests/legacy/test_solver.py": "fb534492e02e1ae1865ec5ea21cae1fb9ac54fa5bf4c72a5fc9030657015fa20", + "python/tests/legacy/test_subcatch_api_pet.py": "aea501aaa1010656d7134ef6a20b1d4bbb6d2af4583642c517d68716249192c0", + "python/tests/legacy/test_system_api_climate.py": "85a973332af65f58ee16dac6eec06e824b3dacbf930336cafcebbd1855b79212", + "python/tests/minimal_features.py": "18442a47a0f581fa1d6f4ba5d846bf0e9cec19679b3c7b6d4c37b5d49d097573", + "python/tests/test_2d_marcher_options.py": "226bdb69a28ddd190aaf09a08d8706867b0ef804418c88c0e724b8259b264741", + "python/tests/test_2d_triangle_coupling.py": "63858ee2f2c080d67163eb74980807a8df634d2329258448d218adde363b35f2", + "python/tests/test_2d_triangle_initial_state.py": "1a7275edc6762b355100c2f41b586eba5ab23dd2c543da1d75ec5bc22be95b2f", + "python/tests/test_api_coverage.py": "5fa2e8ec1fd2a8242efdcf6cea2ec8d06c5923b5f8e833cd4040197a177c9618", + "python/tests/test_enum_drift.py": "444b6659001e23e2c89bf8765d97344aea6037258fe5abd52112a143f824c5f7", + "python/tests/test_fv_routing_options.py": "537a688d7f34dc71ce5a416f381bbf012ffdeeffdceb5a9d5fc28d2925efa5c7", + "python/tests/test_pet_parity.py": "a0ef99c30b415c373f1229899e383eb7af18f489b91ab344e474d2095d3de1a4", + "python/tests/test_solver_pxd_attrs.py": "c83f6fd1fa4e75531c0de8e5a559d7fc522b6ff3b40352d5ccaaa44d2f087c11", + "python/tests/typing/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "python/tests/typing/test_surface.py": "4b0f0b70836ab3be094baaf8ab3a647324349dbcf6636b47385d328fa1e51300", + "src/engine/core/SWMMEngine.cpp": "ee41044b5860a503495d83e315cfd3520ecaac04db062b591293fd53a71efcbc", + "src/engine/plugins/DefaultReportPlugin.cpp": "b42820eacb23f3ed0364930cfa287e2169c09ec60bb153f3c48dd9987d7b6745" + }, + "logs": { + "wheel_tests": "Python: /Users/calebbuahin/miniforge3/envs/openswmm/bin/python\nBindings: /private/tmp/openswmm-conda-wheel-installed/openswmm/engine/_solver.cpython-312-darwin.so\n============================= test session starts ==============================\nplatform darwin -- Python 3.12.13, pytest-9.0.2, pluggy-1.6.0\nrootdir: /Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/python\nconfigfile: pyproject.toml\nplugins: asyncio-1.3.0, anyio-4.13.0\nasyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function\ncollected 1221 items\n\npython/tests/engine/test_2d_evap.py .... [ 0%]\npython/tests/engine/test_2d_ts_stage.py .... [ 0%]\npython/tests/engine/test_aquifers_pythonic.py ......... [ 1%]\npython/tests/engine/test_binding_completion.py ......... [ 2%]\npython/tests/engine/test_callbacks_and_xsect.py ....... [ 2%]\npython/tests/engine/test_climate_pythonic.py .... [ 3%]\npython/tests/engine/test_common.py ................ [ 4%]\npython/tests/engine/test_concurrent_simulation.py ... [ 4%]\npython/tests/engine/test_controls_advancement.py ...... [ 5%]\npython/tests/engine/test_controls_inflows.py .... [ 5%]\npython/tests/engine/test_controls_references.py ........ [ 6%]\npython/tests/engine/test_edit.py ....................................... [ 9%]\n........ [ 9%]\npython/tests/engine/test_edit_extended.py ......... [ 10%]\npython/tests/engine/test_editor_roundtrip.py ...... [ 11%]\npython/tests/engine/test_enums.py ...................................... [ 14%]\n...... [ 14%]\npython/tests/engine/test_files_iface_gaps.py ... [ 14%]\npython/tests/engine/test_forcing_climate.py ........... [ 15%]\npython/tests/engine/test_forcing_climate_evap.py .... [ 16%]\npython/tests/engine/test_forcing_pet.py ............. [ 17%]\npython/tests/engine/test_forcing_quality.py ..... [ 17%]\npython/tests/engine/test_forcing_snow.py ....... [ 18%]\npython/tests/engine/test_gages_pythonic.py ........................ [ 20%]\npython/tests/engine/test_geopackage.py .......................... [ 22%]\npython/tests/engine/test_geopackage_export.py .... [ 22%]\npython/tests/engine/test_groundwater.py ... [ 22%]\npython/tests/engine/test_heat.py ....................................... [ 26%]\n... [ 26%]\npython/tests/engine/test_hotstart_pythonic.py .......... [ 27%]\npython/tests/engine/test_iface_routing.py ... [ 27%]\npython/tests/engine/test_initial_quality.py .................. [ 28%]\npython/tests/engine/test_inlet_api.py .... [ 29%]\npython/tests/engine/test_integration.py ... [ 29%]\npython/tests/engine/test_lenient_open.py ..... [ 29%]\npython/tests/engine/test_links_pythonic.py ............................. [ 32%]\n. [ 32%]\npython/tests/engine/test_mass_balance_pythonic.py ...... [ 32%]\npython/tests/engine/test_metadata_bindings.py ...... [ 33%]\npython/tests/engine/test_model_builder.py .............................. [ 35%]\n... [ 36%]\npython/tests/engine/test_model_file_paths.py ... [ 36%]\npython/tests/engine/test_native_safety.py ......... [ 37%]\npython/tests/engine/test_new_binding_stubs.py .... [ 37%]\npython/tests/engine/test_new_domain_tables.py ... [ 37%]\npython/tests/engine/test_nodes_pythonic.py .......................... [ 39%]\npython/tests/engine/test_opened_state_editing.py ........... [ 40%]\npython/tests/engine/test_optional_imports.py ..... [ 41%]\npython/tests/engine/test_output_reader_pythonic.py ..................... [ 42%]\n... [ 42%]\npython/tests/engine/test_output_species_ids.py ... [ 43%]\npython/tests/engine/test_p7_pythonic.py ....................... [ 45%]\npython/tests/engine/test_p8_pythonic.py ............. [ 46%]\npython/tests/engine/test_param_runtime.py ...................... [ 47%]\npython/tests/engine/test_process_components.py ................... [ 49%]\npython/tests/engine/test_quality_editing.py ..... [ 49%]\npython/tests/engine/test_rdii_advancement.py ........................... [ 52%]\n.. [ 52%]\npython/tests/engine/test_reactions.py .................................. [ 55%]\n.................. [ 56%]\npython/tests/engine/test_runoff_interface.py ..... [ 57%]\npython/tests/engine/test_snowpacks_pythonic.py ...... [ 57%]\npython/tests/engine/test_solver.py .......................... [ 59%]\npython/tests/engine/test_solver_introspection.py .... [ 59%]\npython/tests/engine/test_solver_pythonic.py ............................ [ 62%]\n... [ 62%]\npython/tests/engine/test_solver_units.py ..... [ 62%]\npython/tests/engine/test_state_injection.py ...... [ 63%]\npython/tests/engine/test_statistics_pythonic.py .... [ 63%]\npython/tests/engine/test_storage_shapes_pythonic.py ......... [ 64%]\npython/tests/engine/test_streets_params.py . [ 64%]\npython/tests/engine/test_subcatchments_pythonic.py ..................... [ 66%]\n. [ 66%]\npython/tests/engine/test_surface2d_run_stats.py . [ 66%]\npython/tests/engine/test_surface2d_view.py .......... [ 67%]\npython/tests/engine/test_transects_pythonic.py ........ [ 67%]\npython/tests/engine/test_transport.py ..... [ 68%]\npython/tests/engine/test_userflags_schema.py .................... [ 69%]\npython/tests/engine/test_water_age.py .................. [ 71%]\npython/tests/engine/test_workflow.py .... [ 71%]\npython/tests/engine/test_xsect_geometry.py ............................. [ 74%]\n.............................. [ 76%]\npython/tests/legacy/test_output.py ..................................... [ 79%]\n............ [ 80%]\npython/tests/legacy/test_param_runtime.py ................ [ 81%]\npython/tests/legacy/test_phase1_enum_coverage.py ....................... [ 83%]\n......... [ 84%]\npython/tests/legacy/test_phase2_statistics.py .......................... [ 86%]\n........... [ 87%]\npython/tests/legacy/test_phase3_oop_wrappers.py ........................ [ 89%]\n................ [ 90%]\npython/tests/legacy/test_quality_sources.py ......... [ 91%]\npython/tests/legacy/test_snow_api.py .... [ 91%]\npython/tests/legacy/test_solver.py ........................ [ 93%]\npython/tests/legacy/test_subcatch_api_pet.py ........... [ 94%]\npython/tests/legacy/test_system_api_climate.py .... [ 95%]\npython/tests/test_2d_marcher_options.py ..... [ 95%]\npython/tests/test_2d_triangle_coupling.py .... [ 95%]\npython/tests/test_2d_triangle_initial_state.py ....... [ 96%]\npython/tests/test_api_coverage.py ...... [ 96%]\npython/tests/test_enum_drift.py .......................... [ 99%]\npython/tests/test_fv_routing_options.py ........ [ 99%]\npython/tests/test_pet_parity.py .. [ 99%]\npython/tests/test_solver_pxd_attrs.py .. [100%]\n\n======================= 1221 passed in 90.36s (0:01:30) ========================\n", + "minimal_tests": "Python: /Users/calebbuahin/miniforge3/envs/openswmm/bin/python\nBindings: /private/tmp/openswmm-conda-minimal-stage/openswmm/engine/_solver.cpython-312-darwin.so\n============================= test session starts ==============================\nplatform darwin -- Python 3.12.13, pytest-9.0.2, pluggy-1.6.0\nrootdir: /Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/python\nconfigfile: pyproject.toml\nplugins: asyncio-1.3.0, anyio-4.13.0\nasyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function\ncollected 37 items\n\npython/tests/minimal_features.py . [ 2%]\npython/tests/engine/test_solver_pythonic.py ............................ [ 78%]\n... [ 86%]\npython/tests/engine/test_transport.py ..... [100%]\n\n============================== 37 passed in 1.36s ==============================\n" + } +} diff --git a/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26.md b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26.md new file mode 100644 index 000000000..b19d00a8b --- /dev/null +++ b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26.md @@ -0,0 +1,384 @@ +# Python bindings review and implementation strategy + +Date: 2026-09-26. Repository: `openswmm.engine`. + +> Historical review baseline. Implementation and current validation are recorded in [the implementation report](PYTHON_BINDINGS_IMPLEMENTATION_2026-09-26.md). + +## Scope and evidence + +This is a review and implementation plan, not an implementation of the missing bindings. It examines the current working-tree public C headers, modern Cython bindings, Python enums and stubs, tests, packaging, Sphinx sources, and relevant CI workflows. Existing local edits are included in the review. HEAD at evidence capture is `2daef06bec8ac48172010e31e709bc15827853b8`; the companion JSON records hashes of reviewed inputs because a commit alone does not describe this working tree. + +The modern API is the primary scope. The legacy solver/output bindings and compatibility import paths receive a separate maintenance assessment; the plugin SDK is not assumed to require a one-to-one Python wrapper. + +Evidence files: + +- `PYTHON_BINDINGS_REVIEW_2026-09-26_inventory.tsv`: every modern C export and its source-level binding status. +- `PYTHON_BINDINGS_REVIEW_2026-09-26_evidence.json`: counts, missing functions, stub findings, input hashes, and validation results. +- Appendix A below: the complete missing-function inventory grouped by header. + +### Current state + +| Measure | Result | Interpretation | +|---|---:|---| +| Modern public C functions extracted | 1,172 | Exported declarations in the engine headers | +| Functions referenced outside extern blocks in `.pyx` | 1,050 | Source-level reachability signal, not behavioral coverage | +| Entries in existing intentional-exclusion list | 4 | Requires review; one is actually used by a `.pxd` helper | +| Functions with no binding use and no exclusion | **118** | Current failing API-coverage assertion | +| Modern Cython extension modules checked | 29 | All translate and pass generated-C++ syntax checking | +| Engine Python test files / test definitions | 63 / 891 | Inventory only; not a claim that these tests ran or passed | + +The older parity report, `plans/parity/parity_matrix.md`, reports 552 functions and zero Python gaps. It is stale relative to this inventory and should not be used as a release-readiness claim. + +### Validation performed + +| Check | Result | +|---|---| +| `python3 -m unittest discover -s python/tests -p test_api_coverage.py -v` | 5 tests: 4 pass, headline coverage test fails with 118 functions | +| `python3 -m unittest discover -s python/tests -p test_solver_pxd_attrs.py -v` | 2 pass | +| Cython translation of all 29 modern `.pyx` modules | Pass | +| Apple Clang C++20 syntax check of all 29 generated translation units against current public headers, Python 3.13 and NumPy headers | Pass; no linking or runtime execution implied | +| Existing mypy engine check | Pass: 35 source files | +| Existing strict typing smoke file | Pass: 1 source file | +| Sphinx HTML, warnings treated as errors | Pass with external intersphinx inventories disabled | + +Sphinx used the existing Python virtual environment plus `sphinxcontrib-mermaid` installed into a temporary directory. No project dependency configuration was changed. External links/inventories were not validated. A clean native rebuild, full functional suite, installed-wheel checks, Linux/Windows verification, and runtime memory-safety tests remain acceptance work for implementation. + +## Findings, ordered by risk + +### R1 — The 2D view can outlive the engine handle (P0) + +`python/openswmm/engine/_2d.pyx` stores only `void* _engine`, populated from an integer. `Solver.surface2d` constructs it from `self.handle`; `Solver.destroy()` destroys and nulls the solver's own handle without invalidating the retained pointer. In `src/engine/2d/api/Api2D.cpp`, the entry guard checks for null, then dereferences the engine. A retained surface/infiltration view can therefore reach a freed pointer. + +This is a concrete ownership defect identified in source; a crash was not intentionally triggered. Retaining the solver alone is insufficient because explicit `destroy()` must also invalidate access. + +**Action:** use an owner-backed handle accessor with destruction/generation checks, including nested infiltration views. Define the behavior of views across close, reopen, mesh edits, builder-to-solver ownership transfer, and explicit destruction. Deprecate or clearly isolate the raw-pointer constructor. + +**Tests:** retained view after destroy; solver garbage collection; nested view lifetime; repeated close/destroy; reopen with a different mesh; access concurrent with destruction. Run unsafe-path regressions in subprocesses and use sanitizer builds where supported. + +### R2 — CI omits the existing drift guards (P0) + +`python/pyproject.toml` sets the wheel test command to `pytest {package}/tests/engine ... --ignore=.../test_integration.py`. It does not run top-level `test_api_coverage.py`, `test_solver_pxd_attrs.py`, the other top-level tests, or `tests/legacy`. This is why a substantial binding gap can coexist with passing wheel tests. + +The typing workflow watches `.py`, `.pyi`, and selected configuration files, but not `.pyx`, `.pxd`, or public headers. Python/typing workflows target main/develop, whereas documentation also targets the active `swmm6_rel` branch. Align the actual branch/release policy instead of relying on comments about manual triggers. + +**Action:** add an inexpensive source-contract job before wheel builds, and include it as a release dependency. Run legacy/top-level functional tests in explicit jobs. Review and either migrate or document the exclusion of `test_integration.py`. + +**Tests:** prove the guard fails when a declaration is added without a wrapper, a wrapper is removed, an enum member changes, or a stub signature diverges. Comments and extern declarations must not satisfy reachability. + +### R3 — Four entire API domains are absent (P1) + +Groundwater authoring/results, groundwater transport, surface water quality, and ARD transport configuration account for **82 of the 118 gaps**. All exported functions in their four headers are absent from the modern binding call surface. Generic string options and INP editing do not replace these structured APIs. + +Expose these as coherent domain views. Proposed names in this document are design suggestions, not existing Python features. Preserve the distinction between authoring data, runtime state, diagnostics, and supported engine capabilities. + +### R4 — Enum and report drift persists inside already-bound domains (P1) + +Confirmed missing named members include: + +- `RefType`: 15 reference kinds with codes 7–21. `_edit.pyx` already has their string names, so the exported enum disagrees with the editor rather than the whole editor being absent. +- `FilePathRole`: `MESH_2D`, `OUTPUT_2D`, `LID_REPORT` (11–13). +- `RunoffTotal`: initial/final snow storage (7–8). +- `RoutingTotal`: 1D-to-2D coupling outflow (12), link groundwater inflow (13). +- `ForcingType`: four per-element climate channels and link seepage (13–17). + +The name-based audit also finds nine C enum types without a same-named Python enum: `EvapType`, `TempSource`, `WindType`, `HumidityType`, `HumidityVar`, `HeatElemKind`, `InpProfile`, `TransportDispersionMode`, and `UnitSystem`. Some underlying operations already accept integers; classify these as typed-surface decisions, not nine entirely missing behaviors. Review the absent `ForcingMode.NONE` sentinel separately rather than automatically advertising it as a valid setter mode. + +The enum audit ignores public `#define` selectors, including groundwater scope/zone/soil/closure/ledger constants and transport matrix state/domain/class constants. Those need explicit mappings too. + +`_report.py` omits the new snow and coupling/groundwater totals. The `RoutingTotal.FORCING_INFLOW` Python docstring says it is distinct from EXTERNAL, while the C header now describes it as a subset. That distinction matters to consumers assembling water balances. + +**Action:** compare names, numeric values, aliases, sentinels and macro constants against C; synchronize `.py`, `.pyi`, exports, report records, examples and accounting descriptions. Generic integer getters already make some numeric selectors callable; that does not provide named discovery or report completeness. + +### R5 — Runtime members, stubs, and generated reference docs differ (P1) + +Confirmed examples of members present in `.pyx` but absent from their `.pyi` surface: + +| Runtime class | Missing stub members | +|---|---| +| `Pollutants` | `rename` | +| `Landuse` | `rename` | +| `Quality` | `validate_treatment_expression` | +| `Subcatchment` | `coverages`, `loadings`, `rain_scale_factor`, `snow_scale_factor` | + +Some are in current uncommitted implementation changes. They should ship with their companion stubs and documentation. This member-name comparison is a lower-bound finding, not an exhaustive proof of signature/default/type parity. + +There is no `py.typed` marker under `python/openswmm`, and the inspected packaging files do not create one. Source-tree mypy success does not establish that downstream installed-package consumers receive typing support. + +`python/docs/conf.py` imports `.pyi` files in preference to the compiled implementation. Consequently, the claim in `api.rst` that stubs are always synchronized with compiled extensions is not enforced. A successful Sphinx build can publish an incomplete API reference. + +**Action:** add installed-wheel typing checks, marker/package-content checks, and runtime-versus-stub comparisons for public names, signatures, keyword-only parameters, defaults, return types and read-only properties. Treat `.pyx` runtime docstrings as the implementation contract and `.pyi` as its checked typing projection. Publish reference docs from the tested wheel; retain a stub-based fast preview only with parity guards. + +### R6 — Exception, callback, and concurrency contracts need a common design (P1) + +Most modules use `_common.pxd`'s typed exception dispatch; `_2d.pyx` instead raises bare `RuntimeError` with a numeric code. The shared helper uses the generic `swmm_error_message(code)`, losing handle-specific details where those are available. Some older `ModelBuilder` mutations return raw status codes while newer facades raise exceptions. + +Callback trampolines in `_solver.pyx` call user Python code inside `noexcept with gil` functions without capturing exceptions for the initiating Python call. Decide and test propagation at a safe `step`/`stride`/`run` boundary; do not allow a controller failure to be silently lost. Abort timing and whether the current native step can finish must be explicit. + +`step`, `stride`, and bulk operations release the GIL. That supports independent solvers, but does not by itself serialize mutation/destruction of the same solver. Existing concurrency tests concentrate on speedup and concurrent reads, not the whole ownership contract. + +**Action:** define one per-handle operation/reentrancy policy, including callback-safe operations. Add deterministic correctness/progress tests; keep wall-clock speedup thresholds in a performance lane. Preserve older raw-status API behavior until a documented deprecation/migration can be made. + +### R7 — Documentation examples contain lifecycle and mesh drift (P1) + +`guide/initial_quality.rst` mutates initial-quality rows inside `with Solver(...)`. `Solver.__enter__` opens, initializes and starts the run, while the same guide and C API require BUILDING/OPENED for those mutations. That example cannot exercise the advertised editable state. + +The `_model.pyx` module example uses the old numeric step-return convention and tests RUNNING immediately after start. The current binding returns `timedelta`, with STARTED preceding RUNNING. These examples need executable fixtures. + +`guide/index.rst` still introduces the 2D router as a triangular CVODE solver. Current bindings expose the explicit marcher and mixed triangle/quad mesh helpers. `get_edge_geometry_bulk` allocates using `edge_stride` but its docstring still describes a fixed stride of three. The C header explicitly aliases triangle count to cell count; this review does **not** identify that count alias as a buffer-size defect. + +**Action:** fix concepts and executable examples together. Specify lifecycle, physical units, array layout, padding, indexing, ownership, optional capability behavior, and save/reload semantics at each public entry point. + +### R8 — Optional-module and compatibility testing can hide broken installations (P2) + +The package catches any `ImportError` from optional modules and reports `HAS_2D=False` or `HAS_GEOPACKAGE=False`. Several tests skip on import failure. Distinguish an intentionally disabled feature from a wheel that was meant to contain it but has a loader/dependency failure. + +A separate legacy symbol scan finds two solver exports not referenced in the legacy `.pyx`: `swmm_getRunningMassBalErr` and `swmm_setWarningCallback`; all 34 legacy output exports have references. This is not a signature or behavioral parity proof. Decide whether the two omissions are intentional, expose them if required, and keep legacy compatibility tests active. Documentation that calls the legacy engine “verbatim” or says no development happens there should reflect the actual maintained extensions. + +## Work packages for all 118 missing functions + +Names below are proposed Python entry points. Every package includes declarations, wrappers, public imports, type stubs, tests, code documentation, Sphinx reference entries, a guide example and a changelog entry. + +| Package / C header | Missing | Proposed surface | Required behavioral tests and docs | +|---|---:|---|---| +| Groundwater: `openswmm_gw2d.h` | 26 | `solver.groundwater2d`: options, authored rows/node beds, state, species, ledgers | Global/tag/cell precedence; BUILDING/OPENED mutation; automatic node enrollment and exchange flags; state/column shapes; species order; continuity; project-unit authoring versus SI runtime results. New `groundwater2d.rst`. | +| Groundwater transport: `openswmm_gw_transport.h` | 29 | `solver.groundwater_transport`: options, parameters, sorption, sources/species, boundary/initial quality | CRUD/upsert/removal semantics; selectors; sidecars; INP round trips and supported container round trips; runtime rejection of authoring edits; pollutant/age/temperature semantics. New `groundwater_transport.rst`. | +| Surface quality: `openswmm_sq2d.h` | 14 | `solver.surface2d.quality`: coverage, curb lengths, loading, buildup | Row width versus land-use count, precedence, dry/wet cases, mixed-cell meshes, species/cell array order, nonzero buildup response. New `surface_quality.rst`. | +| Transport configuration: `openswmm_transport.h` | 13 | `solver.transport`: dispersion, target dx, conduit overrides, source/boundary rows | OFF/FISCHER/VALUE; zero/default handling; finite/nonnegative parameters; ft²/s versus m²/s; read-only row access; negative extraction rates. New `transport.rst`. | +| 2D diagnostics: `openswmm_2d.h` | 8 | Rainfall/volume arrays, interpolation weights, output-variable metadata | Scalar/bulk agreement, configured rainfall modes, empty arrays, cell order, weights, cumulative versus instantaneous units, output masks/names. Update `2d.rst`. | +| Engine diagnostics: `openswmm_engine.h` | 5 | `thread_info()`, `solver.effective_threads()`, `solver.transport_matrix` | OpenMP absent/present; auto/explicit requests; full 4×4 matrix, reasons and refresh after edits. Update solver guide and new capabilities section. | +| Forcing: `openswmm_forcing.h` | 5 | Per-element climate, node age/temperature, link seepage on `solver.forcing` | RESET/PERSIST; ADD/OVERRIDE; clear/fallback; signed values; project temperature units; isolation from global climate; effect after an actual step. Update forcing/heat/age guides. | +| Batch editing: `openswmm_edit.h` | 4 | Batch-delete methods on `solver.editor` | Duplicate/invalid selections, preflight/atomicity per C contract, cascade/restrict, order independence, stale views and identity remapping. Update editing guide. | +| Initial quality: `openswmm_initial_quality.h` | 3 | Sidecar path and per-row provenance on `initial_quality` | Original/resolved paths, set versus load-on-next-open behavior, file/inline rows, clear/save/reopen, missing file diagnostics. Update initial-quality guide. | +| Live output: `openswmm_output.h` | 3 | `OutputReader.open_live`, `is_live`, `refresh` | Zero complete periods, incremental flush, incomplete tail, finalization, repeated refresh, array snapshots and close semantics. Update output-reader guide. | +| Heat: `openswmm_heat.h` | 2 | Shortwave/cloud timeseries names | Missing/assigned series and save/reopen consistency. Update heat guide. | +| Process registry: `openswmm_process_components.h` | 2 | Known component vocabulary, separate from configured instances | Enumerate metadata; unknown IDs; registry versus model membership. Update process-components guide. | +| Timeseries: `openswmm_tables.h` | 2 | Relative-time metadata on a timeseries | Relative/absolute distinction, start-date changes, authored round trip. Update tables/datetime guides. | +| Link orientation: `openswmm_links.h` | 1 | Explicit authored-orientation restoration | Adverse-slope reversal, endpoints/offsets/vertices, idempotency and save/reopen. Update links/editing guides. | +| Compatibility writing: `openswmm_model.h` | 1 | `solver.write_compat(path, profile)` with `InpProfile` | FULL, legacy and stock profiles; warnings for dropped content; original model unchanged; stock-load compatibility; file failures. Update model-builder/migration guides. | +| **Total** | **118** | | | + +Transport boundary/source rows are explicitly **read-only in the C API revision reviewed**. Their missing setters are an upstream API-design item, not something the Python wrapper should fake. Similarly, do not imply that adding wrappers implements a physical process absent from a selected transport backend. Expose the transport capability matrix and test meaningful supported configurations. + +## Test design and code-documentation requirements + +### Shared contract tests + +Build reusable fixtures that cover: + +1. **Lifecycle:** new/building/opened/initialized/started/running/ended/closed/destroyed, including reads versus authoring mutations and invalid handles. +2. **Ownership and identity:** retained views, deleted/renamed objects, structural generation changes, builder ownership transfer, garbage collection and callbacks holding references. +3. **Units and value semantics:** US/SI equivalents; seconds versus days/hours; project versus SI output quantities; concentration versus mass; signed age/temperature/extraction values; NaN/Inf and range validation. +4. **Array and ABI contracts:** exact dtype/shape/order; owned snapshots versus borrowed views; empty inputs, noncontiguous inputs, invalid sizes, undersized output buffers; platform C `long` width and integer overflow; triangle/quad padding. Compile C-derived enum/struct probes on each platform. +5. **Persistence:** author → write → reopen → compare both values and provenance. Cover relative paths, Unicode paths/identifiers, external sidecars, profiles and write failures. Apply GeoPackage/HDF5 expectations only where that serializer supports the feature; report unsupported behavior explicitly. +6. **Physical observables:** nonzero forcing changes the intended recipient, dry cells remain well-defined, conservative transfers balance within justified tolerances, and supported backend combinations agree on the wrapper contract. Use small analytical/reference fixtures; do not duplicate the entire numerical solver verification suite in Python. +7. **Failures:** correct exception class/code/context; unknown IDs; forbidden states; dangling references; callback exceptions; failed import of an expected native dependency. + +Reuse relevant C++ fixture/test intent from `test_gwf_api.cpp`, `test_gw_transport_authoring.cpp`, `test_gw_transport_kernel.cpp`, `test_2d_surface_quality.cpp`, `test_transport_options_api.cpp`, `test_transport_policy.cpp`, `test_output_reader_live.cpp`, `test_2d_quad_mesh.cpp`, and `test_thread_info.cpp`. Give Python tests independent expected results rather than simply asserting that a call returns success. Every new binding must be exercised by at least one reachable public Python test; every mutable subsystem needs a round-trip test and every numerical subsystem an observable-effect test. + +### Documentation contract for each public member + +Record purpose and underlying C function; parameters and accepted enums; return type and shape; physical units and signs; zero-based API versus one-based file indexing; allowed lifecycle; ownership/copy behavior; mutation invalidation; threading/GIL restrictions; errors and warnings; optional build/runtime capability; persistence and path semantics; and a minimal usable example. + +Use one consistent Sphinx-compatible docstring style for new work and normalize touched older epytext blocks. Do not invent documentation for units that the C implementation does not actually honor: resolve contradictory header/implementation contracts first. + +### Sphinx and related deliverables + +- Add the four new domain guides listed above and connect them through `guide/index.rst`, `api.rst`, and package/module maps. +- Add a units/lifecycle/capability reference shared by all guides; explain SI groundwater results alongside project-unit authoring and 2D conventions. +- Correct initial-quality and model-builder examples; execute guide examples against small checked-in fixture models in CI. +- Update quickstart, model editing, forcing, mass balance, live output, mixed meshes, compatibility migration and optional-installation troubleshooting. +- Update `.pyi`, `__init__.py`, `__init__.pyi`, `__all__`, any Cython re-export declarations and build module registration together. +- Add and verify the typing marker in built wheels; run downstream mypy from outside the source tree. +- Rebuild the parity inventory and retire stale claims/links; update README, CHANGELOG, package support tables and the application manual's Python chapter. +- Keep Sphinx `-W --keep-going`; inspect suppressed duplicate/reference warning categories and replace broad suppression with narrow documented exceptions where feasible. Add executable-example and periodic external-link checks. An HTML build alone is not a behavioral docs test. + +## Ordered implementation strategy + +| Phase | Work and dependencies | Completion gate | +|---|---|---| +| 0 — Reproducible baseline | Capture source hashes and feature configuration; reconcile the two audit tools and old parity matrix; map functions → Python entry points → tests → docs. Add a source-only contract job. | No newly introduced unexplained drift. The current 118 are explicit tracked implementation debt, not silently added to an intentional-exclusion list. | +| 1 — Safety and shared contracts | Fix 2D ownership/invalidation, callback exception capture, same-handle concurrency policy and diagnostic propagation. Synchronize enum members, known stub gaps and report semantics. Depends on baseline. | Regression tests fail on old behavior and pass on fixes; strict typing and public imports agree; retained views cannot dereference a destroyed engine. | +| 2 — Complete existing domain views | Compatibility writer, batch edits, initial-quality sidecars, relative timeseries, heat names, component registry, link orientation, live output and new forcing. | All corresponding gap rows closed with behavior/round-trip/error tests; guides and stubs ship in the same changes. | +| 3 — Transport and capability views | Bind the 13 transport-config functions and 5 engine diagnostics; introduce typed records and constants. | Matrix matches configured engine behavior; read-only limits documented; US/SI and configuration round-trip tests pass. | +| 4 — Groundwater | Bind 26 groundwater and 29 groundwater-transport functions. Split authoring and runtime/results into reviewable changes. Reuse Phase 1 ownership and Phase 3 capability contracts. | Explicit 55-function closure; state and species array tests; authoring round trips; meaningful water/species ledger checks; no false capability claims. | +| 5 — Surface quality and remaining 2D | Bind 14 surface-quality functions and 8 2D diagnostics; finalize mixed-mesh examples and naming. | Explicit 22-function closure; nonzero quality/rainfall fixtures, weights/masks, shape/stride and scalar/bulk parity tests. | +| 6 — Release qualification | Clean wheel builds; installed-package typing and examples; full modern, legacy and top-level test lanes; optional-feature build matrix; Sphinx from tested artifacts. Documentation is developed throughout, not postponed to this phase. | Zero unexplained binding gaps; correct intentionally unsupported inventory; supported wheel matrix green; reproducible docs and no unreviewed missing-feature skips. | + +Use one focused PR per domain or safety contract, with code, tests, stubs and documentation together. Avoid a single large wrapper-generation change that obscures ownership, units, or physical meaning. Preserve established Python names and calling conventions; add aliases/deprecations where API consistency requires a migration. Assign owners and estimates after the shared safety contract and upstream-only requirements are agreed. + +## Definition of done + +- Every modern public C function is classified as supported, intentionally replaced by a Python idiom, intentionally native-only, or explicitly deferred with an owner and issue. Release qualification has no unexplained or silently allowlisted backlog. +- Supported functions have consistent declarations, callable public wrappers, verified enum/struct/array contracts, stubs, exports, meaningful tests and current reference documentation. +- New domains include runnable examples, unit/lifecycle tables, persistence behavior and capability limitations. +- Source-contract, runtime, installed-wheel typing, documentation-example and supported-platform gates run on the branches and tags that actually release the package. +- Legacy compatibility remains tested, and proposed breaking changes carry a migration path. +- Validation results distinguish static checks, syntax compilation, linking, runtime tests and cross-platform results; none stands in for another. + + +## Appendix A — Complete missing-function inventory + +Generated from the existing source-level API coverage guard. These functions occur in public engine headers but have no recognized `.pyx` use and are not in its intentional-exclusion list. + +### `openswmm_2d.h` (8) + +- `swmm_2d_get_coupling_volume_bulk` +- `swmm_2d_get_rain_volume_bulk` +- `swmm_2d_get_rainfall_bulk` +- `swmm_2d_get_rainfall_weights` +- `swmm_2d_output_variable_count` +- `swmm_2d_output_variable_mask` +- `swmm_2d_output_variable_name` +- `swmm_2d_output_variable_text` + +### `openswmm_edit.h` (4) + +- `swmm_gage_delete_many` +- `swmm_link_delete_many` +- `swmm_node_delete_many` +- `swmm_subcatch_delete_many` + +### `openswmm_engine.h` (5) + +- `swmm_get_effective_threads` +- `swmm_get_thread_info` +- `swmm_get_transport_matrix` +- `swmm_transport_class_name` +- `swmm_transport_domain_name` + +### `openswmm_forcing.h` (5) + +- `swmm_forcing_element_climate` +- `swmm_forcing_element_climate_get` +- `swmm_forcing_link_seepage` +- `swmm_forcing_node_age` +- `swmm_forcing_node_temperature` + +### `openswmm_gw2d.h` (26) + +- `swmm_gw2d_get_cell` +- `swmm_gw2d_get_cell_bulk` +- `swmm_gw2d_get_cell_conc` +- `swmm_gw2d_get_column` +- `swmm_gw2d_get_continuity_error` +- `swmm_gw2d_get_dimensions` +- `swmm_gw2d_get_ledger` +- `swmm_gw2d_get_species_ledger` +- `swmm_gw2d_get_tier_histogram` +- `swmm_gw2d_is_active` +- `swmm_gw2d_node_add` +- `swmm_gw2d_node_count` +- `swmm_gw2d_node_get` +- `swmm_gw2d_node_get_flags` +- `swmm_gw2d_node_remove` +- `swmm_gw2d_node_set_exchange` +- `swmm_gw2d_option_get` +- `swmm_gw2d_option_set` +- `swmm_gw2d_row_add` +- `swmm_gw2d_row_count` +- `swmm_gw2d_row_get` +- `swmm_gw2d_row_get_property` +- `swmm_gw2d_row_remove` +- `swmm_gw2d_row_set_property` +- `swmm_gw2d_species_count` +- `swmm_gw2d_species_name` + +### `openswmm_gw_transport.h` (29) + +- `swmm_gw_boundary_quality_count` +- `swmm_gw_boundary_quality_get` +- `swmm_gw_boundary_quality_remove` +- `swmm_gw_boundary_quality_set` +- `swmm_gw_init_quality_count` +- `swmm_gw_init_quality_file_get` +- `swmm_gw_init_quality_file_set` +- `swmm_gw_init_quality_get` +- `swmm_gw_init_quality_remove` +- `swmm_gw_init_quality_set` +- `swmm_gw_params_count` +- `swmm_gw_params_get` +- `swmm_gw_params_remove` +- `swmm_gw_params_set` +- `swmm_gw_sorption_count` +- `swmm_gw_sorption_get` +- `swmm_gw_sorption_remove` +- `swmm_gw_sorption_set` +- `swmm_gw_source_count` +- `swmm_gw_source_get` +- `swmm_gw_source_remove` +- `swmm_gw_source_set` +- `swmm_gw_source_species_count` +- `swmm_gw_source_species_get` +- `swmm_gw_source_species_remove` +- `swmm_gw_source_species_set` +- `swmm_gw_transport_authored` +- `swmm_gw_transport_option_get` +- `swmm_gw_transport_option_set` + +### `openswmm_heat.h` (2) + +- `swmm_heat_get_cloud_timeseries` +- `swmm_heat_get_shortwave_timeseries` + +### `openswmm_initial_quality.h` (3) + +- `swmm_init_quality_file_get` +- `swmm_init_quality_file_set` +- `swmm_init_quality_is_file` + +### `openswmm_links.h` (1) + +- `swmm_links_restore_authored_orientation` + +### `openswmm_model.h` (1) + +- `swmm_model_write_compat` + +### `openswmm_output.h` (3) + +- `swmm_output_is_live` +- `swmm_output_open_live` +- `swmm_output_refresh` + +### `openswmm_process_components.h` (2) + +- `swmm_process_component_known_count` +- `swmm_process_component_known_get` + +### `openswmm_sq2d.h` (14) + +- `swmm_2d_coverage_count` +- `swmm_2d_coverage_get` +- `swmm_2d_coverage_remove` +- `swmm_2d_coverage_row_size` +- `swmm_2d_coverage_set` +- `swmm_2d_curb_length_count` +- `swmm_2d_curb_length_get` +- `swmm_2d_curb_length_remove` +- `swmm_2d_curb_length_set` +- `swmm_2d_get_buildup_bulk` +- `swmm_2d_loading_count` +- `swmm_2d_loading_get` +- `swmm_2d_loading_remove` +- `swmm_2d_loading_set` + +### `openswmm_tables.h` (2) + +- `swmm_timeseries_get_relative_info` +- `swmm_timeseries_set_relative_info` + +### `openswmm_transport.h` (13) + +- `swmm_transport_boundary_count` +- `swmm_transport_conduit_disp_count` +- `swmm_transport_get_boundary` +- `swmm_transport_get_conduit_disp` +- `swmm_transport_get_configured` +- `swmm_transport_get_dispersion_mode` +- `swmm_transport_get_dispersion_value` +- `swmm_transport_get_source` +- `swmm_transport_get_target_dx` +- `swmm_transport_set_dispersion_mode` +- `swmm_transport_set_dispersion_value` +- `swmm_transport_set_target_dx` +- `swmm_transport_source_count` diff --git a/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_evidence.json b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_evidence.json new file mode 100644 index 000000000..fd106a6ed --- /dev/null +++ b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_evidence.json @@ -0,0 +1,764 @@ +{ + "date": "2026-09-26", + "head": "2daef06bec8ac48172010e31e709bc15827853b8", + "scope": "working tree, including existing local edits; hashes define reviewed inputs", + "source_counts": { + "c_exports": 1172, + "exports_with_pyx_use": 1050, + "existing_allowlist": 4, + "unexplained_gaps": 118 + }, + "existing_allowlist": [ + "swmm_error_message", + "swmm_get_current_time", + "swmm_get_last_error", + "swmm_get_last_error_msg" + ], + "allowlist_caveat": "swmm_error_message is called by the shared .pxd helper; the current .pyx-only guard misses that use. Counts are the existing guard metrics, not a runtime coverage percentage.", + "missing_functions": { + "swmm_2d_coverage_count": "openswmm_sq2d.h", + "swmm_2d_coverage_get": "openswmm_sq2d.h", + "swmm_2d_coverage_remove": "openswmm_sq2d.h", + "swmm_2d_coverage_row_size": "openswmm_sq2d.h", + "swmm_2d_coverage_set": "openswmm_sq2d.h", + "swmm_2d_curb_length_count": "openswmm_sq2d.h", + "swmm_2d_curb_length_get": "openswmm_sq2d.h", + "swmm_2d_curb_length_remove": "openswmm_sq2d.h", + "swmm_2d_curb_length_set": "openswmm_sq2d.h", + "swmm_2d_get_buildup_bulk": "openswmm_sq2d.h", + "swmm_2d_get_coupling_volume_bulk": "openswmm_2d.h", + "swmm_2d_get_rain_volume_bulk": "openswmm_2d.h", + "swmm_2d_get_rainfall_bulk": "openswmm_2d.h", + "swmm_2d_get_rainfall_weights": "openswmm_2d.h", + "swmm_2d_loading_count": "openswmm_sq2d.h", + "swmm_2d_loading_get": "openswmm_sq2d.h", + "swmm_2d_loading_remove": "openswmm_sq2d.h", + "swmm_2d_loading_set": "openswmm_sq2d.h", + "swmm_2d_output_variable_count": "openswmm_2d.h", + "swmm_2d_output_variable_mask": "openswmm_2d.h", + "swmm_2d_output_variable_name": "openswmm_2d.h", + "swmm_2d_output_variable_text": "openswmm_2d.h", + "swmm_forcing_element_climate": "openswmm_forcing.h", + "swmm_forcing_element_climate_get": "openswmm_forcing.h", + "swmm_forcing_link_seepage": "openswmm_forcing.h", + "swmm_forcing_node_age": "openswmm_forcing.h", + "swmm_forcing_node_temperature": "openswmm_forcing.h", + "swmm_gage_delete_many": "openswmm_edit.h", + "swmm_get_effective_threads": "openswmm_engine.h", + "swmm_get_thread_info": "openswmm_engine.h", + "swmm_get_transport_matrix": "openswmm_engine.h", + "swmm_gw2d_get_cell": "openswmm_gw2d.h", + "swmm_gw2d_get_cell_bulk": "openswmm_gw2d.h", + "swmm_gw2d_get_cell_conc": "openswmm_gw2d.h", + "swmm_gw2d_get_column": "openswmm_gw2d.h", + "swmm_gw2d_get_continuity_error": "openswmm_gw2d.h", + "swmm_gw2d_get_dimensions": "openswmm_gw2d.h", + "swmm_gw2d_get_ledger": "openswmm_gw2d.h", + "swmm_gw2d_get_species_ledger": "openswmm_gw2d.h", + "swmm_gw2d_get_tier_histogram": "openswmm_gw2d.h", + "swmm_gw2d_is_active": "openswmm_gw2d.h", + "swmm_gw2d_node_add": "openswmm_gw2d.h", + "swmm_gw2d_node_count": "openswmm_gw2d.h", + "swmm_gw2d_node_get": "openswmm_gw2d.h", + "swmm_gw2d_node_get_flags": "openswmm_gw2d.h", + "swmm_gw2d_node_remove": "openswmm_gw2d.h", + "swmm_gw2d_node_set_exchange": "openswmm_gw2d.h", + "swmm_gw2d_option_get": "openswmm_gw2d.h", + "swmm_gw2d_option_set": "openswmm_gw2d.h", + "swmm_gw2d_row_add": "openswmm_gw2d.h", + "swmm_gw2d_row_count": "openswmm_gw2d.h", + "swmm_gw2d_row_get": "openswmm_gw2d.h", + "swmm_gw2d_row_get_property": "openswmm_gw2d.h", + "swmm_gw2d_row_remove": "openswmm_gw2d.h", + "swmm_gw2d_row_set_property": "openswmm_gw2d.h", + "swmm_gw2d_species_count": "openswmm_gw2d.h", + "swmm_gw2d_species_name": "openswmm_gw2d.h", + "swmm_gw_boundary_quality_count": "openswmm_gw_transport.h", + "swmm_gw_boundary_quality_get": "openswmm_gw_transport.h", + "swmm_gw_boundary_quality_remove": "openswmm_gw_transport.h", + "swmm_gw_boundary_quality_set": "openswmm_gw_transport.h", + "swmm_gw_init_quality_count": "openswmm_gw_transport.h", + "swmm_gw_init_quality_file_get": "openswmm_gw_transport.h", + "swmm_gw_init_quality_file_set": "openswmm_gw_transport.h", + "swmm_gw_init_quality_get": "openswmm_gw_transport.h", + "swmm_gw_init_quality_remove": "openswmm_gw_transport.h", + "swmm_gw_init_quality_set": "openswmm_gw_transport.h", + "swmm_gw_params_count": "openswmm_gw_transport.h", + "swmm_gw_params_get": "openswmm_gw_transport.h", + "swmm_gw_params_remove": "openswmm_gw_transport.h", + "swmm_gw_params_set": "openswmm_gw_transport.h", + "swmm_gw_sorption_count": "openswmm_gw_transport.h", + "swmm_gw_sorption_get": "openswmm_gw_transport.h", + "swmm_gw_sorption_remove": "openswmm_gw_transport.h", + "swmm_gw_sorption_set": "openswmm_gw_transport.h", + "swmm_gw_source_count": "openswmm_gw_transport.h", + "swmm_gw_source_get": "openswmm_gw_transport.h", + "swmm_gw_source_remove": "openswmm_gw_transport.h", + "swmm_gw_source_set": "openswmm_gw_transport.h", + "swmm_gw_source_species_count": "openswmm_gw_transport.h", + "swmm_gw_source_species_get": "openswmm_gw_transport.h", + "swmm_gw_source_species_remove": "openswmm_gw_transport.h", + "swmm_gw_source_species_set": "openswmm_gw_transport.h", + "swmm_gw_transport_authored": "openswmm_gw_transport.h", + "swmm_gw_transport_option_get": "openswmm_gw_transport.h", + "swmm_gw_transport_option_set": "openswmm_gw_transport.h", + "swmm_heat_get_cloud_timeseries": "openswmm_heat.h", + "swmm_heat_get_shortwave_timeseries": "openswmm_heat.h", + "swmm_init_quality_file_get": "openswmm_initial_quality.h", + "swmm_init_quality_file_set": "openswmm_initial_quality.h", + "swmm_init_quality_is_file": "openswmm_initial_quality.h", + "swmm_link_delete_many": "openswmm_edit.h", + "swmm_links_restore_authored_orientation": "openswmm_links.h", + "swmm_model_write_compat": "openswmm_model.h", + "swmm_node_delete_many": "openswmm_edit.h", + "swmm_output_is_live": "openswmm_output.h", + "swmm_output_open_live": "openswmm_output.h", + "swmm_output_refresh": "openswmm_output.h", + "swmm_process_component_known_count": "openswmm_process_components.h", + "swmm_process_component_known_get": "openswmm_process_components.h", + "swmm_subcatch_delete_many": "openswmm_edit.h", + "swmm_timeseries_get_relative_info": "openswmm_tables.h", + "swmm_timeseries_set_relative_info": "openswmm_tables.h", + "swmm_transport_boundary_count": "openswmm_transport.h", + "swmm_transport_class_name": "openswmm_engine.h", + "swmm_transport_conduit_disp_count": "openswmm_transport.h", + "swmm_transport_domain_name": "openswmm_engine.h", + "swmm_transport_get_boundary": "openswmm_transport.h", + "swmm_transport_get_conduit_disp": "openswmm_transport.h", + "swmm_transport_get_configured": "openswmm_transport.h", + "swmm_transport_get_dispersion_mode": "openswmm_transport.h", + "swmm_transport_get_dispersion_value": "openswmm_transport.h", + "swmm_transport_get_source": "openswmm_transport.h", + "swmm_transport_get_target_dx": "openswmm_transport.h", + "swmm_transport_set_dispersion_mode": "openswmm_transport.h", + "swmm_transport_set_dispersion_value": "openswmm_transport.h", + "swmm_transport_set_target_dx": "openswmm_transport.h", + "swmm_transport_source_count": "openswmm_transport.h" + }, + "stub_member_findings": { + "_pollutants.pyx": { + "Pollutants": [ + "rename" + ] + }, + "_quality.pyx": { + "Landuse": [ + "rename" + ], + "Quality": [ + "validate_treatment_expression" + ] + }, + "_subcatchments.pyx": { + "Subcatchment": [ + "coverages", + "loadings", + "rain_scale_factor", + "snow_scale_factor" + ] + } + }, + "cython_translation": [ + { + "module": "_2d.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_climate.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_controls.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_datetime.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_edit.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_forcing.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_gages.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_geopackage.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_heat.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_hotstart.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_inflows.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_infrastructure.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_initial_quality.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_links.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_massbalance.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_model.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_nodes.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_output_reader.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_pollutants.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_process_components.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_quality.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_reactions.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_solver.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_spatial.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_statistics.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_subcatchments.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_tables.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_water_age.pyx", + "returncode": 0, + "output": "" + }, + { + "module": "_xsect.pyx", + "returncode": 0, + "output": "" + } + ], + "native_syntax_checks": [ + { + "module": "_2d", + "returncode": 0, + "output": "" + }, + { + "module": "_climate", + "returncode": 0, + "output": "" + }, + { + "module": "_controls", + "returncode": 0, + "output": "" + }, + { + "module": "_datetime", + "returncode": 0, + "output": "" + }, + { + "module": "_edit", + "returncode": 0, + "output": "" + }, + { + "module": "_forcing", + "returncode": 0, + "output": "" + }, + { + "module": "_gages", + "returncode": 0, + "output": "" + }, + { + "module": "_geopackage", + "returncode": 0, + "output": "" + }, + { + "module": "_heat", + "returncode": 0, + "output": "" + }, + { + "module": "_hotstart", + "returncode": 0, + "output": "" + }, + { + "module": "_inflows", + "returncode": 0, + "output": "" + }, + { + "module": "_infrastructure", + "returncode": 0, + "output": "" + }, + { + "module": "_initial_quality", + "returncode": 0, + "output": "" + }, + { + "module": "_links", + "returncode": 0, + "output": "" + }, + { + "module": "_massbalance", + "returncode": 0, + "output": "" + }, + { + "module": "_model", + "returncode": 0, + "output": "" + }, + { + "module": "_nodes", + "returncode": 0, + "output": "" + }, + { + "module": "_output_reader", + "returncode": 0, + "output": "" + }, + { + "module": "_pollutants", + "returncode": 0, + "output": "" + }, + { + "module": "_process_components", + "returncode": 0, + "output": "" + }, + { + "module": "_quality", + "returncode": 0, + "output": "" + }, + { + "module": "_reactions", + "returncode": 0, + "output": "" + }, + { + "module": "_solver", + "returncode": 0, + "output": "" + }, + { + "module": "_spatial", + "returncode": 0, + "output": "" + }, + { + "module": "_statistics", + "returncode": 0, + "output": "" + }, + { + "module": "_subcatchments", + "returncode": 0, + "output": "" + }, + { + "module": "_tables", + "returncode": 0, + "output": "" + }, + { + "module": "_water_age", + "returncode": 0, + "output": "" + }, + { + "module": "_xsect", + "returncode": 0, + "output": "" + } + ], + "validation": { + "api_coverage": "4 pass; 1 fail (118 gaps)", + "solver_pxd_attributes": "2 pass", + "mypy_engine": "Success: no issues found in 35 source files", + "mypy_strict_typing_smoke": "Success: no issues found in 1 source file", + "sphinx": "HTML build passed with warningiserror=True, keep_going=True, intersphinx_mapping={}; published configuration and existing warning suppressions otherwise unchanged", + "not_run": [ + "full runtime suite", + "clean native link/wheel build", + "installed-wheel type checks", + "Linux/Windows verification", + "memory-safety reproductions", + "external intersphinx/link validation" + ] + }, + "sha256": { + ".github/workflows/benchmark_dispatch.yml": "72e25bbe98571ca79303ccab5c1bd70262af2416d7b41d86176bdb433d8914e7", + ".github/workflows/codeql.yml": "41135f087d8f83495353f1c96d24cdfc64f6f9478b0e8ba885f2d2f9c63d2b50", + ".github/workflows/deployment.yml": "c42663b444b652eab546ea0e3ce75669cf020128e3998ff1e09fa74765baa307", + ".github/workflows/documentation.yml": "55531bf780e7952a63b2538c3034d01762886d2205a3326ff6eff374b097b65b", + ".github/workflows/regression_testing.yml": "34b0f843e07d5a8218b427ab255fae7062e14153b5f55f3312f260dc2905999f", + ".github/workflows/scorecard.yml": "64c2a000bec81892165c2d49a6e5cfa13dba479a01d69711ea4d85794a078830", + ".github/workflows/typing.yml": "849feeaf6138a1f8ce777622256ecf594158577482f994644b4015fbb68cf3c8", + ".github/workflows/unit_testing.yml": "cb22e7360cadc017bbdfc12125c1eff002f84b6822aa9543ee8f5aac75340d2b", + ".github/workflows/unit_testing_python.yml": "a7218866e1fde1abd2cda5edf6f36c1c26a3b387b50affe13b933a25b1dd47e2", + "include/openswmm/engine/openswmm_2d.h": "268d399af5e5d0854ee6d9d7007374ca5dbbc46d648f199d98b9c82a3b9a21d9", + "include/openswmm/engine/openswmm_callbacks.h": "b9478a3215576729f8ec9dfbaedc5dfa71fa9a314dbc909bd31f1e13507c23bf", + "include/openswmm/engine/openswmm_climate.h": "abe39b945d12c733b9c5e80e3e0e01283215b0f41b0edda311e988d5f7a0fd79", + "include/openswmm/engine/openswmm_controls.h": "d9044dffb854deb66032db6b64843edf6ace9a807984d9a2e6adbd2ee77c45e8", + "include/openswmm/engine/openswmm_datetime.h": "585fd3307bff50e0118730d511f7e4ebb93ef0441a4636184fdf4f318270861d", + "include/openswmm/engine/openswmm_edit.h": "8aa855f546f523050ac40661167f32c0bd15b47746000d6be1301d3283aa9955", + "include/openswmm/engine/openswmm_engine.h": "60572711a25256d79fe5d4d4792ac5465b63e62c600c8815c14e35e91aec2c44", + "include/openswmm/engine/openswmm_engine_export.h": "2bdfbd8f07f33540dd2225a0f19415000afabe7f5e6c026daeaaae0d62434ff7", + "include/openswmm/engine/openswmm_forcing.h": "0488d4e4f1b0526f14589ca1a531426f99c986df1927e3326613bc36ad212cb1", + "include/openswmm/engine/openswmm_gages.h": "ba2a26d0f4dfcc64d43146ccda1eb253b72ede3c9c9cb281793e2e9f445561ac", + "include/openswmm/engine/openswmm_geopackage.h": "de86f4e904bfcefb65320e7be3e964077fde8b8db06e54e0d9d89f1243650f45", + "include/openswmm/engine/openswmm_gw2d.h": "4c0b3da7ddde9bdcfd4a084c0ab4965e6ea95276b203ded9d102eca2881e5d6f", + "include/openswmm/engine/openswmm_gw_transport.h": "a1f8d30f709d1eb7baa29ed6dab8c25c1d4cfed8855d79adfad06279b2b2a168", + "include/openswmm/engine/openswmm_heat.h": "8495210d3006a20a823fc3139066257af4f657e5643b094c580ce272b1304208", + "include/openswmm/engine/openswmm_hotstart.h": "1f6ae581f9cecbc5ab05feba89cc79ae66b968031b7c69fd64a0e308c7c9c49e", + "include/openswmm/engine/openswmm_infil2d.h": "9210857c289caa28d2a25161584669439692e60d9b4989e0805ebfe5d89060e0", + "include/openswmm/engine/openswmm_inflows.h": "ef8e7e5c047a750f00d6b4d04ea71d3fe78812b6f951a8d0b6237e60f22b73ff", + "include/openswmm/engine/openswmm_infrastructure.h": "9798057095169c49d7f77f306d6e3e6a686c72f7055a0f03729675aa1f7641b2", + "include/openswmm/engine/openswmm_initial_quality.h": "48ccfc67100b9f70078190a5ac83c9e747e2f2c46042c6adf6dfaf3913ba5917", + "include/openswmm/engine/openswmm_links.h": "23035dd45330ecf1935e1376dd1e25aaa5cb2f56e4d7ccb5d587ce06de079193", + "include/openswmm/engine/openswmm_massbalance.h": "d6f904cc1e7fa45f73adcce1b07beacc95f6ac5210c158c4408fd8737e098a4b", + "include/openswmm/engine/openswmm_model.h": "92f0171f8298f30b732451fbf6255636b6fe26e280b4f858bab77fb4424e436f", + "include/openswmm/engine/openswmm_nodes.h": "7d35699f13ce94002673d87333d2d8acc68e203834b429ca03c65444b65ec070", + "include/openswmm/engine/openswmm_output.h": "0df7cc589e065c7e6611b94b3c997de0c27fe4384d2f593bb8ee97044182b48b", + "include/openswmm/engine/openswmm_pollutants.h": "5a3e13ed50c066ec20ffebc5524a8d6ae7eea74ba41a52894a6c1c09bf166045", + "include/openswmm/engine/openswmm_process_components.h": "9c9d0010018be37aa3bb62a088d5a1a902967fc76832872736a66782fdd57526", + "include/openswmm/engine/openswmm_quality.h": "f1d650bca9a5b03f9d18d3eda98823814acd473e54fc613b3e4a61965de8eeb9", + "include/openswmm/engine/openswmm_reactions.h": "deea68c6852a3a7e780eccc0edf957714662de49592849e21e7c66d3ac4e9e49", + "include/openswmm/engine/openswmm_spatial.h": "45ffcd0fe1421b1c35500a49d2b6b4a6bcfcd191cdf053ecdaa0ddebe0caad4c", + "include/openswmm/engine/openswmm_sq2d.h": "c60ac1ffc13c125687e3916055f09f2e9fb0a83d57ddcf6467af37f4ac240de5", + "include/openswmm/engine/openswmm_statistics.h": "131e483be0a6a2661a36a809077e541149896ef64d1340a8736dd04c4db51c22", + "include/openswmm/engine/openswmm_subcatchments.h": "20592588c70de0ab6abda4ddb0d30e60b417c6c3fef717a9a8429074dccbb71e", + "include/openswmm/engine/openswmm_tables.h": "c37c668e16ef16f5ba0df132955dc86bbf7fbab60936671a42c4aefb3bcc14ce", + "include/openswmm/engine/openswmm_transport.h": "e07bdfea9b24d8707950986dd7e37e2969e2705bc504408ca91235f3791670f2", + "include/openswmm/engine/openswmm_water_age.h": "5e02a102c515600156a1e519ee06b3bfbaed7786238032b9c3843025f1b0bb89", + "include/openswmm/engine/openswmm_xsect.h": "0c601562cddb7a15d124e4efc38ec70a1da3081fcc96b066dabb9cae401cf549", + "python/docs/LEGACY_API_EXPANSION_PLAN.md": "7be1a40d638354c952559ab34f65e91464138fb881cb696d09beb7fdfa8ba581", + "python/docs/api.rst": "0eaf0125e24d9ca49d9923e7bf574617eb4a3bcfa536573ef42c624b0cd37b3b", + "python/docs/conf.py": "ee445eaf0cb92a13db003bb697cf8062c6950a55b603dc529d30b24b47d2a18e", + "python/docs/guide/2d.rst": "574eb3c3ea3a1c8ac0a6144bc5e3412b9fca6dac07ffa80589e2391f354154b9", + "python/docs/guide/climate.rst": "3255d74cf6cf5e392ab8a8ca2598430c5023199a5e8da82c70bed686cf619767", + "python/docs/guide/concepts.rst": "ff7e77d7788c577317e11a499d8217c8e14da848d14d3f4e557cfaf4b533079d", + "python/docs/guide/controls.rst": "babb416a7c727dd2c6f928da69c4486be2046a30dc867f2c99f41817d0485327", + "python/docs/guide/datetime.rst": "0f8bc61a5919e1ed337c19f254f066db326c74b1d14e055cf4609bb60f138c7d", + "python/docs/guide/editing.rst": "3b716d94397ef09d4ad5fa8bd3ad0ac3cff51105db7c4a6780bd2f5b72c4ffef", + "python/docs/guide/error_handling.rst": "038b7c48432bee9d86e553ed09492ad00c6668dbec4d145c3cb2540a0d466ff7", + "python/docs/guide/forcing.rst": "1e3fdafcb6aa7a7a1a81b803b33c05514e41098d8360fa22d328a75df00aa2a7", + "python/docs/guide/gages.rst": "7cc0be27d677ad612ca58a37c175fa6d5990f8532298eecec48e0ea330da9768", + "python/docs/guide/geopackage.rst": "daea25d08f4d7475a3a26d12983de653fbb452faaee8ca528fd7e0ac74a91b4d", + "python/docs/guide/heat.rst": "b5d92d90d16eaa9158391adae5407ae0ac991de78c1c9f91ad7888e578b0e825", + "python/docs/guide/hotstart.rst": "a9bf60bc027f1cea556a68aeb99fce5c0dc13a2047f5d60eef83af685050d485", + "python/docs/guide/index.rst": "9ac969066fbe0c575e7f64be6c680bee1b2ee471030a7071f2acc8faa256b0d2", + "python/docs/guide/inflows.rst": "9925e74d465658c085f83d8961621f44bf73a17b9e4419147602f97c3f496f3e", + "python/docs/guide/infrastructure.rst": "657a493bdba7b8d10fa9577edd0ecb94462699c48136022c5a4657b3fbe2cce3", + "python/docs/guide/initial_quality.rst": "af1e22f237d5c69766273fb7834eab8c2935e986e23c91130102bd5b24536fe1", + "python/docs/guide/install.rst": "38a64479c78b92ad104035d64a6d4af9115a11c8a7c69bc78a6339bbe9527100", + "python/docs/guide/links.rst": "a4fd3ed6947c2a126b98afbfcf3f2f46001cfab6e08e329a76241328d4c09e43", + "python/docs/guide/massbalance.rst": "cf5d1a73af86c54a782707641c4907e9ca8acb5e4b5d29b5a4adec5fe104fc7a", + "python/docs/guide/model_builder.rst": "993b9ac47157a630701397636d61dcb6643fec3bfad0ab4ae09a3c7bfd6e0705", + "python/docs/guide/nodes.rst": "7ebac5e2080d0175f72600826f822d2210559db1e6ded5c7c678da2534c1984d", + "python/docs/guide/output_reader.rst": "64fc6f8d56f9fbfedbfdd7cbd47eea6d485784e9d59c75eeea755f43983fd1d7", + "python/docs/guide/plotting.rst": "f9173d62e83d2d79dc9bea9702c2c39924ea8c2554129cf8395ba455889e6a5e", + "python/docs/guide/pollutants.rst": "3c7856e9f973545402c701ad2dcecceb149faa6d98a943e258f8c7a1731269ab", + "python/docs/guide/process_components.rst": "7e2edd56134c25f35ee41ad48c4f6454e99cbb167f89041cbf15a5bb2bc9e566", + "python/docs/guide/quality.rst": "5a284ea6d2f059e259ea8dc276e1a357dc3227baa88b213583ce127aae89d924", + "python/docs/guide/quickstart.rst": "f63631d93aa5d337a8cc8f41ea75e73bd01238363955ce8d4e29ecf34e462308", + "python/docs/guide/reactions.rst": "1dc363c09c3eb6890cbfd6d596d5b4f564c5f404ef36ff11b046820159dbe0bf", + "python/docs/guide/solver.rst": "a0cdc5933cba4b61e658d3b927dd6768dfe9117b7622a25eb9f88e5c4bae8f3f", + "python/docs/guide/spatial.rst": "d62b8f309e74a6d1d32b00831913659da434aac4dacd337de2e6c9ff59842ba4", + "python/docs/guide/statistics.rst": "692221411cd6dba10beec9982c8c9e59cffa737462607208d60cb1974366f163", + "python/docs/guide/subcatchments.rst": "e3c00128d109bbce40e528baca3408600b5a20978eb4ca86c69a4176445a0f49", + "python/docs/guide/tables.rst": "ea6edbf66fcd33d6a5d1864ef305facc5f40a6c50f88931667ca68bdb1c22811", + "python/docs/guide/water_age.rst": "b24a7852e8c567d8711cabb793768e80a4a639757caf8532684d98862660282d", + "python/docs/guide/xsect_geometry.rst": "18f9421de50772a8e8b639d2a68143c010637165d5fb2d0a284803ab7bbf99aa", + "python/docs/index.rst": "2ac546b5c12c0dbdf7f4db1155b5cff53b80c11c98e8b60a5f58554063610ea7", + "python/docs/legacy/index.rst": "2ebcbf032a47a6b6079a15ffdf792a78e928d9fd578a118eccc6179f783e9428", + "python/docs/legacy/output.rst": "8ae087871b39a173259ca19f6cec23d6eef2cfdc7180199331f0765b4a948071", + "python/docs/legacy/solver.rst": "958949e9b0a4e8337d9ed8503ae483254af34bdeb301ab6b2f75ca5209e20ebb", + "python/docs/license.rst": "e45c68e560c9ec410008321fa0470d163c2ec8ffe4bfc3154a7b87eea339f835", + "python/docs/migration/swmm5_to_swmm6.rst": "3f963d36e02eea26cde22c82eb7b2c2984566e5e628cc501e92dc15f5e71d1fc", + "python/docs/requirements.txt": "9f73ad40f09b6a25eceb194ec292e1b9292ed8c23c9ec3c90d21a5aba6c3944e", + "python/openswmm/CMakeLists.txt": "9c74c2b1cd674e38192e79d5adbb8855f89645843380318384a601954f26e9f5", + "python/openswmm/__init__.py": "a1457d58b2aa3ca34faacef4c87cc3c5cd6c85cfddf73d98ca22934b913e35bb", + "python/openswmm/data/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "python/openswmm/engine/CMakeLists.txt": "c5df95898ae1228805ff5486aca76ac57daf8cbc62d5a245d9be31179d9e8d0a", + "python/openswmm/engine/_2d.pxd": "828bf46e8a9b72dcfc1c32cdd7eddc81f3bff2a917d186ad61fba7dba118b76e", + "python/openswmm/engine/_2d.pyi": "24cbcdd8910b2169f880f58e8eafc0dd603c683018f66e83458e2d3932259ba5", + "python/openswmm/engine/_2d.pyx": "5766b64800d00be347cc7275afb335af86658499d3b29c1c8176b8b866cdbc89", + "python/openswmm/engine/__init__.pxd": "15e77b6f88304122823ffcdaaa59cda9e78ccf21ddd744a96f6ddc0b44044b76", + "python/openswmm/engine/__init__.py": "c75b42a51972fe5ef7867a9c6fbbcad3bcf451d0ffa72e8d02a7737123a4322a", + "python/openswmm/engine/__init__.pyi": "c03b131111edee881ca2f92433d84ffc80d5729f55f2435a4c31e8a277700a5f", + "python/openswmm/engine/_climate.pyi": "36218586d6d88695c08db76b748449cf1eafc955b02c37c6a7dbb103afbde966", + "python/openswmm/engine/_climate.pyx": "93dde91cd1ae8ec54a2eeca8c044f3ee7c5342d50a3b6463ef54fa31f8177304", + "python/openswmm/engine/_common.pxd": "b5f5363dd9f665f75c879a486a6a6d5771500f944aa857857ff08eb5eaa44c02", + "python/openswmm/engine/_controls.pyi": "72f315dab3f59d4fc623d06471b7aa8d376bcf21e56fde8ab14507e04cf12843", + "python/openswmm/engine/_controls.pyx": "0c4bff6e72680a62a0990e7cbb0b546e4be4f1b2350725ee11f14c7bae9c0600", + "python/openswmm/engine/_dates.py": "fff1d2eafa776616c2773d67caab6d63f41cccafbce9bd983d3331fe3f85d655", + "python/openswmm/engine/_dates.pyi": "da0aa2d7be8bc29223ba4a94ce2a5df9740a1cdf10ab47430615d370f3c28d31", + "python/openswmm/engine/_datetime.pyi": "cb252791b765467e8cfd01e7d502321f5b3481c8de1b3fb5f5d776d669c6ad5d", + "python/openswmm/engine/_datetime.pyx": "ae2bce8e1ead01d4a539d703f837cbf979ea71060ad0eb40414a4111248cb588", + "python/openswmm/engine/_edit.pyi": "a915107248f4747a4cff9eafe4980a43de9ed95eda99f44e54b6f139d1a3eb43", + "python/openswmm/engine/_edit.pyx": "ae1bec1b0c8ec51226b9caf72e85c876abd4e09f219bb524429db6bdcb0419fc", + "python/openswmm/engine/_enums.py": "556993819fa76531d26259a639d36df9352289354dc8248f593b460e8a06e35a", + "python/openswmm/engine/_enums.pyi": "46396721e392789ab5d354843eb0de62a33482cbeea5a5c4181faf18ce0c5f8d", + "python/openswmm/engine/_exceptions.py": "3be9371c3a77101a248d5ea7fec064bc5894ba3d6582d77c7095159c8e2ca37e", + "python/openswmm/engine/_exceptions.pyi": "cf365bd80fc95cfe51b4b881cb7e47e47e5e2a20298693cc64a22d993e897d27", + "python/openswmm/engine/_forcing.pyi": "1f02bd3f44b36431356fac6acdc16745ed06313fd9d6ea7af8accb7289678305", + "python/openswmm/engine/_forcing.pyx": "4af21b58a4a34aeb015a93a70f4f3573237fad767bff56b4d1b9afcaa5448deb", + "python/openswmm/engine/_gages.pyi": "c5166e72835b280b65abbb3b84e437ea3e50651e2609738a2bf281b08a1d8ad0", + "python/openswmm/engine/_gages.pyx": "a62202e6b8c3591f04b46ee3fcec8c82c81b3795edc830157d460109017e197f", + "python/openswmm/engine/_geometry.py": "380ed55ffc17fa84276a7415518e97ba88e5e463cae41ccc1f0131d629022549", + "python/openswmm/engine/_geopackage.pyi": "7d3e452b7c181e76c62223363f0663f53076352c51625a3a9cdd453d4e70efe8", + "python/openswmm/engine/_geopackage.pyx": "58be68241c1ab4769c3e9d52542058fc253a7afd20ab271fc1b690828d72961f", + "python/openswmm/engine/_heat.pyi": "c71b866882e688341689b1e023115627b7b77197ff55b5cf20dc468ebb67b01a", + "python/openswmm/engine/_heat.pyx": "01bcd08dbb448b86065e6f988592f6a139df734b608ac8f5077765a72fad2566", + "python/openswmm/engine/_hotstart.pyi": "366c0d948bdf70f27e920cbb1f642fc9434b0c6d804c323f4db914f7baac262e", + "python/openswmm/engine/_hotstart.pyx": "5d72761a8c7b1bda61c98e0c37bcd0d47b569deda809c3164f688ecbd4c4e6ef", + "python/openswmm/engine/_inflows.pyi": "48a7e6020ba067bd75f5a16c35f494a32f39b9455a04d6f1e1cb2e5a5aa8c1bd", + "python/openswmm/engine/_inflows.pyx": "73cab4cacb2ba3991db46f09f11ad4dfdb88054a13a688ba90fe2f4000841017", + "python/openswmm/engine/_infrastructure.pyi": "824ca5a5f17d826389ba79bbf89c13531eda7b88e8df3ccde8c00d871234929e", + "python/openswmm/engine/_infrastructure.pyx": "cff580fc4df7ffd0ba4ee9041f0ca1111c856044c1f45028c8e7ddb16f39aac6", + "python/openswmm/engine/_initial_quality.pyi": "1c5324ebb833e81dfb33dcf4bcf7cb8883d6791816372c1cd5f6ba8faefc2990", + "python/openswmm/engine/_initial_quality.pyx": "926356755dddde7e49e5be9117306e5c465b8d3c0dc21a66052acaa6036ed73f", + "python/openswmm/engine/_links.pyi": "5dbd3236161b36e2710f9275589f08a0e445897652d384859f97889aaf68b004", + "python/openswmm/engine/_links.pyx": "2ad5195174ad8b6ffe9dcc21a41b99c17e523ad4a5f71c2e82eaa95e05b8849a", + "python/openswmm/engine/_massbalance.pyi": "3cf3c3a056ef77bfdfcd736e57273b9489aa8fd9381c3167d873147bd8853406", + "python/openswmm/engine/_massbalance.pyx": "727a31668947ad71d4188a76a4ecbe82a1e0624babe369b50cbccd93651f1cab", + "python/openswmm/engine/_model.pyi": "ecf0281e5e9db22ecd330b756dad45c6133f3ac18b108c9646c03a9dc06e4800", + "python/openswmm/engine/_model.pyx": "656c75ddda8c44312e5f13c5d9cdbc85c59ee20592d4ef477c47fb5a9855b0f9", + "python/openswmm/engine/_nodes.pyi": "86f32c19b887376b0b63c2d3e1fe20541e9530a9a7824d1022b1f9f356ba6694", + "python/openswmm/engine/_nodes.pyx": "8393e4328aff50df352100065063407e0080519ff402af267a5fb1f4bf3ee825", + "python/openswmm/engine/_output_reader.pyi": "aca8e762379f7d4c994fd16625f5d19d9b41c2d56b65b201b23ffb7f33086b1e", + "python/openswmm/engine/_output_reader.pyx": "9953e8d2c420bfafa0b69414ce1e0875348f380878493e44dddc9c09f6b63ebb", + "python/openswmm/engine/_pollutants.pyi": "d642cb352e9dff581d2acb77004f728e79f8186243790e7f0b15e0aa4a81f7dc", + "python/openswmm/engine/_pollutants.pyx": "123eeba3e36cfe3d5afd6b8f2e07aae7368426f5e66087286e8a6d9809e720a2", + "python/openswmm/engine/_process_components.pyi": "5dae437eaf0786af511e4a9c29153dce150fef09d8a65c569edfcbdfeae54395", + "python/openswmm/engine/_process_components.pyx": "181452877477d16fd636b48186783ff9d52615ed6b113ecb3570eb15cd20069f", + "python/openswmm/engine/_quality.pyi": "044c714264287d9ef1ed2d5ccb6d3a11281e3baaf5bb16fbf2737f27af2d4386", + "python/openswmm/engine/_quality.pyx": "a499fada754e6726dc608e40f1cb43f0e6e596902d1eb356f23811dec4e4f218", + "python/openswmm/engine/_reactions.pyi": "34399884a50f2fc387909557906f5e5e4560c12cdb40779b7cb2f54c389e4f37", + "python/openswmm/engine/_reactions.pyx": "8b3394209e7db162f728f5404f56d911f0ab1e1ff95e22679b9d0466c128d80a", + "python/openswmm/engine/_report.py": "a848f9a0db349f4ffb7ed2d060c6d06d557c1ddbc38c0b899403630561720550", + "python/openswmm/engine/_solver.pxd": "2fc3d361bd3ed9855dc3b09bd1707c70173d6e03cb458fbdf483aca9a24643a8", + "python/openswmm/engine/_solver.pyi": "b0829d7671125a201094322f71d43a06f14e5786eaa2db1315e8b8e45d8745fa", + "python/openswmm/engine/_solver.pyx": "9d8642d702a5c283e5f87115676a9317d7349439f583b76d15588700362a0a50", + "python/openswmm/engine/_spatial.pyi": "1bef90a1db14836d68effbacf36811a3f2e4a04eabfa004f82dd19641053d9f8", + "python/openswmm/engine/_spatial.pyx": "b9063c1321a5b69510198e1a80179b10a30cffd6ab543b06ce68c84ab9059271", + "python/openswmm/engine/_statistics.pyi": "3e36d9625dbcb445b51ac9897b3aa840672a1c66cd4a79ddc173ca0b05a2d8bb", + "python/openswmm/engine/_statistics.pyx": "d622355b49abbfd49c22c2a6cb438c909ce802b1a8be4641ee11e2ee3538f6ae", + "python/openswmm/engine/_subcatchments.pyi": "31b98c70c7fa0e08082279ad41c8c18363bb22d2e5e0c6fa1fe44e5308da8af1", + "python/openswmm/engine/_subcatchments.pyx": "44e006f4f1790ae29d0f556d7d625f13b17117139cb11f3ae9a161a08823b5fc", + "python/openswmm/engine/_tables.pyi": "6362a82f986a93ea6daa4c9cdc297cdf1e82de51d7fc6bd62865e376a56ad814", + "python/openswmm/engine/_tables.pyx": "495e420bed811ba83f9eb308adc72227986b8856e7cc43229a574473e24e173a", + "python/openswmm/engine/_water_age.pyi": "44b2fa4e5ab47f91ea61875122c1909da0a43d4f9a3a08a2dd5bef63d3814a57", + "python/openswmm/engine/_water_age.pyx": "11dcea5943bc3be1cecf02928e67c8066ed45b6e76153d9db30c4b36c5c733c2", + "python/openswmm/engine/_xsect.pyi": "2193922ca40d318f8d58ae7d274fe4a8b130bb341818b52beb241d9438a76507", + "python/openswmm/engine/_xsect.pyx": "82d626833df95cb7d3561190721f67a25085a918682055a17f306567ddb32bb2", + "python/openswmm/legacy/CMakeLists.txt": "5e907830f0a2281fbec3e9de86cf992fb1d4c51982a93cfa00271e541ed41441", + "python/openswmm/legacy/__init__.py": "774096ffcb03cd1931738e08d948798f1a4135212dd816d1c35bd167522243a8", + "python/openswmm/legacy/engine/CMakeLists.txt": "52064338884176e1864647f31cd2e63b552ce63438caf8def4723341f2d30fd9", + "python/openswmm/legacy/engine/__init__.pxd": "73aeafe1f91337e94fe80d5fbbc9e9aba34c6d56346054841b6ca091c9317346", + "python/openswmm/legacy/engine/__init__.py": "8e1b72ae62ad97d4c0fe41041503ff531ed0a9d3f116c3a59fcb1cab99883b27", + "python/openswmm/legacy/engine/_forcing_log.py": "d514ac58547b155b369cbd4b1f3a1c498c3879c8480dee987891801f1825452e", + "python/openswmm/legacy/engine/_links.py": "59287f6354b0302f94864ec8c8e5b5f3b39942190afffbad6de26b68779c61d0", + "python/openswmm/legacy/engine/_nodes.py": "cd8f2745076badae83193f304184e61fafbb36ddcdae6c41dd0165b69f9a0241", + "python/openswmm/legacy/engine/_raingages.py": "5df0581a5324ec19b015e31fd6e5f8bc7fd4e5abdf1bf7ae38d1dc1a93b846f6", + "python/openswmm/legacy/engine/_solver.pyi": "a4d1ffc15fa0b98b6934639387ff19627215967c0c422d7a22b7554c6772087d", + "python/openswmm/legacy/engine/_solver.pyx": "5d090cae9bea9a0d6f48b43d2c0dd1f2b89194335cbeb21b9d6eb76722cbefba", + "python/openswmm/legacy/engine/_subcatchments.py": "7e1d4869b89146fa2c2d7cde6a5f8a464066a6d632a1879b4f27ef2ab4cae82c", + "python/openswmm/legacy/engine/_system.py": "c4c12edbd3f9b5106f4d146c15d73fd6e7d5fae45b5b4a9b0887ae0c50a924d1", + "python/openswmm/legacy/engine/solver.pxd": "8b5507162c632dfd27e18170f60e84b4ba1d05d2fbe789e583c20177a88a4630", + "python/openswmm/legacy/output/CMakeLists.txt": "1f67cb167ffd5b23492be9ce9ebc1e8ed1b294913f110761e07974613f9472a0", + "python/openswmm/legacy/output/__init__.pxd": "3fa69206162dab8fcb723c813b98cb833c5ebfbba1195583b3f5f78e9ff448ff", + "python/openswmm/legacy/output/__init__.py": "21916cc3ef500ce4e6f85a17adf30ef3bee9c5c4b75655e9198f43014beed3f9", + "python/openswmm/legacy/output/_output.pyi": "2d37273d1a019bd5a1be686a6f66c25f5019e983f1f81236c3af4fac834691b7", + "python/openswmm/legacy/output/_output.pyx": "1f3b5ac42553aa7e8b69c53f255bcc21f0d3e4f25b478128906edab8e091562b", + "python/openswmm/legacy/output/output.pxd": "656538d69f0324cb44da0e6d4d7d0d1b6323538b3f08ef5647b0ae578feadf25", + "python/openswmm/output/CMakeLists.txt": "77a7ec1714557e8bfc5a6a6dde358826b30aa655c9b75b12a2ac080446194b94", + "python/openswmm/output/__init__.pxd": "3fa69206162dab8fcb723c813b98cb833c5ebfbba1195583b3f5f78e9ff448ff", + "python/openswmm/output/__init__.py": "65f5589276ef8e920a6ef5db80f3c00693f18575cf2c3c67c76046f7aca7f9b3", + "python/openswmm/output/_output.pyi": "c2dd394b5fa230e1b37beb71a20c02c204eb18dc4b97ffa0e1103aab1e91cfd7", + "python/openswmm/output/_output.pyx": "dab595b344eda4dbf25045c15cb9ac3883baaec7dadd7ccbaf0b9ec13f5262b0", + "python/openswmm/output/output.pxd": "656538d69f0324cb44da0e6d4d7d0d1b6323538b3f08ef5647b0ae578feadf25", + "python/openswmm/solver/CMakeLists.txt": "6e41f36d62705c846288dd9b0e94e640366521d540c88a455df388266eb38270", + "python/openswmm/solver/__init__.pxd": "73aeafe1f91337e94fe80d5fbbc9e9aba34c6d56346054841b6ca091c9317346", + "python/openswmm/solver/__init__.py": "441e966d5cd5d2e9be6b760f289afa3372b6fbb8b11153a7e7828b5d005df4b4", + "python/openswmm/solver/_solver.pyi": "af426d21df5267dcad01537fb14910373ac1571e13f0342635998ea014bfd074", + "python/openswmm/solver/_solver.pyx": "9c15079e96645b3aa8f28dc5c502cfea0df4533a0eb6a67d72108ef37889cd88", + "python/openswmm/solver/solver.pxd": "bb641331ca9c9e56f6f52a5df37fba62bd3e236d4521e71f726f8adf76dc7ea8", + "python/pyproject.toml": "a83c832eacba6ba5bd56eeb125016a79edf1da274d25269540ac5c4ac46fec81", + "python/scripts/api_drift_audit.py": "ed83e50a761f760138f91316b79a5c3b86ba9f8bc25fec3b02f6a7f5f07a10bd", + "python/tests/__init__.py": "835bc84fd621a7633a38980b473afaa01da9b23b7f577649c31f4cbcb03c91e6", + "python/tests/_paths.py": "1bc96c79fc2cdb8f15ffba1b69bc7cf846a4c33b123490ecbee5d32baffb36e6", + "python/tests/data/__init__.py": "b226b242b47656004b8c0e8e9825273d1fdc7ba1034e67c89147afb235918014", + "python/tests/data/output/__init__.py": "57ca69e1cc4ea9b4cec8546bd84462b56ac2bea4d5f30eeb7f4970ff1a2407b7", + "python/tests/data/solver/__init__.py": "9d9ceddc89d0a3f4b48a0ddd8cbc6cd40cf022114c1de0d825bfab72a050f411", + "python/tests/engine/__init__.py": "79198af1bcffec8d8a6c67254cd11f48ce5efff34232ff3dbece39cc4e60a3d9", + "python/tests/engine/_solver_cases.py": "9b6cb63b1ae7e79f4f531a5ec93bef86b6f956f74140a9f77c1ba510b5d9e823", + "python/tests/engine/output/probe_case_sensitivity.py": "06a31ce047b9b12c02b668a1c5fbf30291ff8f08cf4ed56ef17a3eeb9cfa1d83", + "python/tests/engine/output/probe_lowercase_ingest.py": "4dc42841be34aa968afc927b5ed964ecc7628f53544cb469863296a7cbadd5b0", + "python/tests/engine/test_2d_evap.py": "0c273f49efc481c2ff8f94318afb9f3771d1e78e203c3781a45901390dd352f6", + "python/tests/engine/test_2d_ts_stage.py": "c5281c0ce21785d5351d1bbbaf3b5229a9a89f68064e3a201f1bc24d352051c6", + "python/tests/engine/test_aquifers_pythonic.py": "3461da6360582148ded8189fb9508aaa1246c8ad8530b91fde6364d5275e3007", + "python/tests/engine/test_callbacks_and_xsect.py": "37aeb458ec96332c2057a8f3ac8a91cc7adf75d5695ef0c9684ee8b348096998", + "python/tests/engine/test_climate_pythonic.py": "aef93880b63a68b8c5f91cb30720a423d1cf2f57e03bfdf57884e5d295392a31", + "python/tests/engine/test_common.py": "2d004e2c30e43ae262a06cdb606744f7a1ff157024a0b5764819c6841895e559", + "python/tests/engine/test_concurrent_simulation.py": "54f1a70cc5fd476697bcc0ee5595f6caf0d008cb142b53290f081a76d31b2e9d", + "python/tests/engine/test_controls_advancement.py": "fa7136dbb7d89261fdc4cd61b43bb13afa384c4167b37426cb80fc3a709047ed", + "python/tests/engine/test_controls_inflows.py": "99bc5ebec635b3945e74c122ff2423d1b66bbcef255c88951ccb9394eefc3364", + "python/tests/engine/test_controls_references.py": "1ae5a6cbf74d51f95048231f8eb643061e631a1f055d7ba29e60f9fbbc2f75f7", + "python/tests/engine/test_edit.py": "1bc23f2b655421217876dea11447a561ce70acfbe5fa0e7aeecd4c6b4f10ecb1", + "python/tests/engine/test_edit_extended.py": "00cda7ac735d667cabdf11e79891c0c338377aee793af2fe4e68c76eac07deb9", + "python/tests/engine/test_editor_roundtrip.py": "a0af5887f9a5c7c722025c97f3ac0949ab8b776621c92de10afb543cbe57cd27", + "python/tests/engine/test_enums.py": "ba2f6ca089d56e3f089773b0a6e270f271645ca38413c2b02d63f75613984d36", + "python/tests/engine/test_files_iface_gaps.py": "9b97c0a5c6b56004b44379a4777a89cdab41b3088cd16ae52145619a8c844c73", + "python/tests/engine/test_forcing_climate.py": "284cb3eb20545086d725c033238400d5906b686fc9b092da9328237f8246a8c0", + "python/tests/engine/test_forcing_climate_evap.py": "ba518882f0233a871ed24382b9c8ccf3dbd4a557a897f41d955bdb9a4f3f959d", + "python/tests/engine/test_forcing_pet.py": "9c9e908d90460f078c66f1b9d2c885e8376116b679937216e5621c9b53e17500", + "python/tests/engine/test_forcing_quality.py": "4edc3b4cfbb9c63ddedb7b9f0cb3defcc1bf326891ff736d519b053dcf17a675", + "python/tests/engine/test_forcing_snow.py": "ec39fa3cf98816f56b15666e77e3922e61145e31b68c2280d000a700ef7816d1", + "python/tests/engine/test_gages_pythonic.py": "fb8cc4c925672d1659a1a119d006d373d0630c97e68e42553dcf84a5bc7f3f6e", + "python/tests/engine/test_geopackage.py": "57395e48df79ba9fef9e059c37474b49e794c93281519b59a9c68dcf2cae51fa", + "python/tests/engine/test_geopackage_export.py": "66f33f873b14382b8cdda784107a3051abf0e95f0153d919601e8d71f217df05", + "python/tests/engine/test_heat.py": "56ae02c10a394750ab54e545487277a71173080f1064f9c4e4387b5d57a57434", + "python/tests/engine/test_hotstart_pythonic.py": "68db3049b4f0dc7b4b885943dc9e1c3fbf788ae40c108343432f332164633792", + "python/tests/engine/test_iface_routing.py": "bfa0b122ada9ebd80a5d8b3b5196897b6845b7ad4fe560233a2e4cb147394bcb", + "python/tests/engine/test_initial_quality.py": "2442807916349c1815b865b08818f52719f3b58cc43193d1415cca95b4021608", + "python/tests/engine/test_inlet_api.py": "2e8a1df79418ab170df641afce65c57cea42aa6e7fab7571376e2c95d6e2fa80", + "python/tests/engine/test_integration.py": "2cf54a3d049f00a10a0c453e949a50f50abfe2a0d1c6f6d08900114d6c8e6c1a", + "python/tests/engine/test_lenient_open.py": "402d4e694ac95781efc570b8f509e55dc9d817b208da8618ab95c0d618d95a5f", + "python/tests/engine/test_links_pythonic.py": "3b1b3115ed549ba6d95c966a08bf9147889a0f25282b73fcd67bf3b8ba99ae10", + "python/tests/engine/test_mass_balance_pythonic.py": "4430c6372a87d96d3c90b1c0c1cb38ed5ba727399c4b88a683322e5c14aafbad", + "python/tests/engine/test_model_builder.py": "69191f5ee9e869571acf4bbc901a2426021c56796a22f890eb4d02a714d7216f", + "python/tests/engine/test_model_file_paths.py": "3ff1458bccf2562ee06dd9bf7e45d45980ef2b353738775c366747a0e733799e", + "python/tests/engine/test_nodes_pythonic.py": "858d673c928f95c7dc8c7a064ada74c21490955912e80ea5640dfbb75ab17bbb", + "python/tests/engine/test_opened_state_editing.py": "bb502442736b1672cdc266e6ef8bfe5b887e4d717217069f7c8976dbf0a1e6ad", + "python/tests/engine/test_output_reader_pythonic.py": "712eb8afee71e80d5bdbd9fbdd9ad4a63fb36ddd2a30a06af03f774994fe2c5b", + "python/tests/engine/test_output_species_ids.py": "08e2d352738f155cd602709206bd725226ff6cd1ded69823fd25ee622e4f690e", + "python/tests/engine/test_p7_pythonic.py": "f193c89e1eb10149d722bc24a4892244273bec098d70819a8aa56d2299214cd7", + "python/tests/engine/test_p8_pythonic.py": "74de8252290823caf44bb80c694b3e16f04c8235b2a588c50015b6a74855ddce", + "python/tests/engine/test_param_runtime.py": "a9c46b2b9961d25521f8729c83cbeb28ba5bbd575e3fe74645fc43fd51d4f731", + "python/tests/engine/test_process_components.py": "6b74257a9ee9179e51d1759ee6dccdf697e18e57c82636028739c8bbc0270ddc", + "python/tests/engine/test_quality_editing.py": "4a87921b5b9020e2ec5e753aad6dc0a74d554909f2c33dfb532a5f5c2c8dca7c", + "python/tests/engine/test_rdii_advancement.py": "480571987fdeb1f56261e2872aa4c5161b0dafda1d029dc650b00adca53fc793", + "python/tests/engine/test_reactions.py": "9f0ba8d2e59e00a3732b4a561e4fc69f6cab44bd9ac4bdfb54e097713f1f7ccb", + "python/tests/engine/test_runoff_interface.py": "b12485337069adaa958107daf96d170b8501f0cf753e484fa35ceccb33a7a663", + "python/tests/engine/test_snowpacks_pythonic.py": "0238914e676884220c9dcaa58c32678cbaaee701e0d827a94b79c66b7f8afaf9", + "python/tests/engine/test_solver.py": "6e9a9b6557c27b256294fa22db3797b5e586fb34e458f297e7325072ea14a48b", + "python/tests/engine/test_solver_introspection.py": "9593b46c5665c110dc758e717999f1b52915b50ffc83cec1f9b42349b3bedeac", + "python/tests/engine/test_solver_pythonic.py": "b4b791632ee72c32351dcae75218616b699aabce65cb950f076bb459c650df14", + "python/tests/engine/test_solver_units.py": "02fbc544d946be904efcf941737a319c9e768e9164485664631891dab4e629fe", + "python/tests/engine/test_state_injection.py": "7bf52e381e70ff2d57f2cc0321685a2fa343b1063297ebc03e47b3526a67a6d7", + "python/tests/engine/test_statistics_pythonic.py": "12772f691a687b3a111b7cfb59f501d77d866c461dde901eac5e47575dae86df", + "python/tests/engine/test_storage_shapes_pythonic.py": "e49001b264e97c6df3eb3ac6f0ac2f90a473f42f82b5d72a95dbe7571b647d43", + "python/tests/engine/test_streets_params.py": "9412ca0057c31ccecc1f7d64ad9c53ac856ccd63be90a9a5268dea9cfffb86a8", + "python/tests/engine/test_subcatchments_pythonic.py": "ae1c07d9292b6a84cb2dca52585403a00599ec915166cbc1ac0051d43f0c52f2", + "python/tests/engine/test_surface2d_run_stats.py": "70c78e33dd51c5de5d11f4d22c89cff775d4f40a073bf57f01ab60fab4f34735", + "python/tests/engine/test_surface2d_view.py": "e401afed50a4818397eb80319e976f15cd4366667db760cb1aa8093796195333", + "python/tests/engine/test_transects_pythonic.py": "fbbc240ef33568abad244901d2ed52367e5678674bf4908d49c523120009c5d4", + "python/tests/engine/test_userflags_schema.py": "fb5e178f8762b1868db3344a1f8402ec30df0c30420f6f03bdf7b162652bc64a", + "python/tests/engine/test_water_age.py": "59e6c2fda88387fb8b67751ef466a3c9a35a0647b14db6d67208f4129c38d4d8", + "python/tests/engine/test_workflow.py": "cc734534456af9818416b0db0e6ade8234c87d78e32225fb3ac2f5d92ae5a853", + "python/tests/engine/test_xsect_geometry.py": "112e5b5f8a410cdc654c5c5b5282e99205d94765af9f4a77c5db807c8aa1683b", + "python/tests/legacy/__init__.py": "7958978068e4eb11b871d9b7062ddc0f1d9993ae50eccf8f968ef252d8fdc5e5", + "python/tests/legacy/test_output.py": "03b239c05ccd8a52ffdf16b48d73df09be62c9b6861ae02026e9f5ac2fa3bd34", + "python/tests/legacy/test_param_runtime.py": "6ac859d67dc20286a5864562d44593e3432df636ee64a48becd0a5cf89637e19", + "python/tests/legacy/test_phase1_enum_coverage.py": "ee4efe8f3e4d11da4509e3914f1f30810d0ca57ee751b5ebaa7f31532895c503", + "python/tests/legacy/test_phase2_statistics.py": "41415bd453b1f99d6c30b345cbac1551f45573473cbe11dd5f230e27fbd79d14", + "python/tests/legacy/test_phase3_oop_wrappers.py": "ae169cb9abbc7a786f68d8cebdb9404074e3d4768d1a7489f0eb2ff7d12bcbe7", + "python/tests/legacy/test_quality_sources.py": "2380a63ef8eca783b90d82dbaab87c20823fea9becd9589878c30036d227f560", + "python/tests/legacy/test_snow_api.py": "2df824c149d99ecdf34284ed44deee36025f8dc43ced2972d5db0bfeb146e27c", + "python/tests/legacy/test_solver.py": "fb534492e02e1ae1865ec5ea21cae1fb9ac54fa5bf4c72a5fc9030657015fa20", + "python/tests/legacy/test_subcatch_api_pet.py": "aea501aaa1010656d7134ef6a20b1d4bbb6d2af4583642c517d68716249192c0", + "python/tests/legacy/test_system_api_climate.py": "85a973332af65f58ee16dac6eec06e824b3dacbf930336cafcebbd1855b79212", + "python/tests/test_2d_marcher_options.py": "226bdb69a28ddd190aaf09a08d8706867b0ef804418c88c0e724b8259b264741", + "python/tests/test_2d_triangle_coupling.py": "b86501fa82476ec5ae071c0166fc064c9e93b000a12fb76cb738517ee36fa9e9", + "python/tests/test_2d_triangle_initial_state.py": "058d8ad31d48603f97f4b5b5339a4e779dfc3ea1e3470c49d55de62db16663ec", + "python/tests/test_api_coverage.py": "e5370b5e120445bfacdb1f35c21012c326c90302332726d5e3aae5b930f5fee5", + "python/tests/test_fv_routing_options.py": "feba88943d380b23ff511bdaeef7818e1d791801849a3647805858485e449a7e", + "python/tests/test_pet_parity.py": "a0ef99c30b415c373f1229899e383eb7af18f489b91ab344e474d2095d3de1a4", + "python/tests/test_solver_pxd_attrs.py": "c83f6fd1fa4e75531c0de8e5a559d7fc522b6ff3b40352d5ccaaa44d2f087c11", + "python/tests/typing/__init__.py": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "python/tests/typing/test_surface.py": "1eec75eab37c6bc68f4dbd8e569dd777d9793a62655f6f330bbb59e9ab3bc1a2" + } +} diff --git a/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_inventory.tsv b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_inventory.tsv new file mode 100644 index 000000000..0c0fbca40 --- /dev/null +++ b/docs/analysis/PYTHON_BINDINGS_REVIEW_2026-09-26_inventory.tsv @@ -0,0 +1,1173 @@ +function header line status reference_files +swmm_2d_add_triangle_coupling include/openswmm/engine/openswmm_2d.h 380 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_boundary_edge_count include/openswmm/engine/openswmm_2d.h 839 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_cell_count include/openswmm/engine/openswmm_2d.h 178 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_cell_get_neighbours include/openswmm/engine/openswmm_2d.h 208 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_cell_get_vertices include/openswmm/engine/openswmm_2d.h 201 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_cell_vertex_count include/openswmm/engine/openswmm_2d.h 195 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_clear_triangle_couplings include/openswmm/engine/openswmm_2d.h 392 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_coverage_count include/openswmm/engine/openswmm_sq2d.h 57 gap +swmm_2d_coverage_get include/openswmm/engine/openswmm_sq2d.h 82 gap +swmm_2d_coverage_remove include/openswmm/engine/openswmm_sq2d.h 88 gap +swmm_2d_coverage_row_size include/openswmm/engine/openswmm_sq2d.h 75 gap +swmm_2d_coverage_set include/openswmm/engine/openswmm_sq2d.h 69 gap +swmm_2d_curb_length_count include/openswmm/engine/openswmm_sq2d.h 114 gap +swmm_2d_curb_length_get include/openswmm/engine/openswmm_sq2d.h 122 gap +swmm_2d_curb_length_remove include/openswmm/engine/openswmm_sq2d.h 126 gap +swmm_2d_curb_length_set include/openswmm/engine/openswmm_sq2d.h 118 gap +swmm_2d_edge_get_geometry_bulk include/openswmm/engine/openswmm_2d.h 312 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_edge_stride include/openswmm/engine/openswmm_2d.h 191 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_clear_all include/openswmm/engine/openswmm_2d.h 799 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_coupling_flux include/openswmm/engine/openswmm_2d.h 793 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_evap include/openswmm/engine/openswmm_2d.h 780 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_evap_uniform include/openswmm/engine/openswmm_2d.h 786 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_rainfall include/openswmm/engine/openswmm_2d.h 759 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_force_rainfall_uniform include/openswmm/engine/openswmm_2d.h 765 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_buildup_bulk include/openswmm/engine/openswmm_sq2d.h 140 gap +swmm_2d_get_continuity_error include/openswmm/engine/openswmm_2d.h 731 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_coupling_flux include/openswmm/engine/openswmm_2d.h 476 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_coupling_fluxes_bulk include/openswmm/engine/openswmm_2d.h 519 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_coupling_volume_bulk include/openswmm/engine/openswmm_2d.h 555 gap +swmm_2d_get_depth include/openswmm/engine/openswmm_2d.h 468 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_depths_bulk include/openswmm/engine/openswmm_2d.h 511 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_dry_depth include/openswmm/engine/openswmm_2d.h 807 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_cum_flux include/openswmm/engine/openswmm_2d.h 961 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_flow include/openswmm/engine/openswmm_2d.h 915 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_flow_tseries_name include/openswmm/engine/openswmm_2d.h 935 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_head include/openswmm/engine/openswmm_2d.h 862 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_rating_curve_name include/openswmm/engine/openswmm_2d.h 953 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_slope include/openswmm/engine/openswmm_2d.h 875 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_tseries_name include/openswmm/engine/openswmm_2d.h 903 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_bc_type include/openswmm/engine/openswmm_2d.h 846 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_conveyance include/openswmm/engine/openswmm_2d.h 595 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_conveyance_bulk include/openswmm/engine/openswmm_2d.h 620 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_edge_flux_bulk include/openswmm/engine/openswmm_2d.h 573 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_head include/openswmm/engine/openswmm_2d.h 472 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_heads_bulk include/openswmm/engine/openswmm_2d.h 515 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_mass_balance include/openswmm/engine/openswmm_2d.h 737 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_max_depth include/openswmm/engine/openswmm_2d.h 659 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_net_source include/openswmm/engine/openswmm_2d.h 505 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_rain_volume_bulk include/openswmm/engine/openswmm_2d.h 534 gap +swmm_2d_get_rainfall include/openswmm/engine/openswmm_2d.h 481 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_rainfall_bulk include/openswmm/engine/openswmm_2d.h 526 gap +swmm_2d_get_rainfall_weights include/openswmm/engine/openswmm_2d.h 498 gap +swmm_2d_get_run_stats include/openswmm/engine/openswmm_2d.h 707 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_solver_last_step include/openswmm/engine/openswmm_2d.h 681 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_solver_steps include/openswmm/engine/openswmm_2d.h 675 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_stat_max_continuity_err include/openswmm/engine/openswmm_2d.h 725 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_stat_max_depths include/openswmm/engine/openswmm_2d.h 713 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_stat_max_velocities include/openswmm/engine/openswmm_2d.h 719 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_total_exchange_flow include/openswmm/engine/openswmm_2d.h 668 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_total_volume include/openswmm/engine/openswmm_2d.h 663 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_triangle_coupling_row include/openswmm/engine/openswmm_2d.h 407 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_triangle_tag include/openswmm/engine/openswmm_2d.h 292 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_vertex_coupling_area include/openswmm/engine/openswmm_2d.h 444 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_vertex_coupling_cd include/openswmm/engine/openswmm_2d.h 419 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_get_vertex_tag include/openswmm/engine/openswmm_2d.h 285 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_is_active include/openswmm/engine/openswmm_2d.h 71 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_loading_count include/openswmm/engine/openswmm_sq2d.h 94 gap +swmm_2d_loading_get include/openswmm/engine/openswmm_sq2d.h 103 gap +swmm_2d_loading_remove include/openswmm/engine/openswmm_sq2d.h 108 gap +swmm_2d_loading_set include/openswmm/engine/openswmm_sq2d.h 99 gap +swmm_2d_output_variable_count include/openswmm/engine/openswmm_2d.h 976 gap +swmm_2d_output_variable_mask include/openswmm/engine/openswmm_2d.h 981 gap +swmm_2d_output_variable_name include/openswmm/engine/openswmm_2d.h 978 gap +swmm_2d_output_variable_text include/openswmm/engine/openswmm_2d.h 983 gap +swmm_2d_prepare_for_edit include/openswmm/engine/openswmm_2d.h 83 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_quad_count include/openswmm/engine/openswmm_2d.h 182 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_reset_edge_conveyance include/openswmm/engine/openswmm_2d.h 625 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_dry_depth include/openswmm/engine/openswmm_2d.h 811 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_flow include/openswmm/engine/openswmm_2d.h 922 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_flow_tseries_name include/openswmm/engine/openswmm_2d.h 928 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_head include/openswmm/engine/openswmm_2d.h 869 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_rating_curve_name include/openswmm/engine/openswmm_2d.h 946 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_slope include/openswmm/engine/openswmm_2d.h 881 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_tseries_name include/openswmm/engine/openswmm_2d.h 892 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_bc_type include/openswmm/engine/openswmm_2d.h 852 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_edge_conveyance include/openswmm/engine/openswmm_2d.h 611 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_triangle_init_depth include/openswmm/engine/openswmm_2d.h 250 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_triangle_init_velocity include/openswmm/engine/openswmm_2d.h 265 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_triangle_mannings include/openswmm/engine/openswmm_2d.h 234 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_triangle_tag include/openswmm/engine/openswmm_2d.h 278 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_coupled_node include/openswmm/engine/openswmm_2d.h 360 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_coupling_area include/openswmm/engine/openswmm_2d.h 456 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_coupling_cd include/openswmm/engine/openswmm_2d.h 429 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_tag include/openswmm/engine/openswmm_2d.h 272 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_z include/openswmm/engine/openswmm_2d.h 128 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_set_vertex_z_bulk include/openswmm/engine/openswmm_2d.h 153 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_count include/openswmm/engine/openswmm_2d.h 95 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_coupling_count include/openswmm/engine/openswmm_2d.h 327 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_coupling_rows include/openswmm/engine/openswmm_2d.h 397 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_area include/openswmm/engine/openswmm_2d.h 215 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_centroid include/openswmm/engine/openswmm_2d.h 220 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_coupled_node include/openswmm/engine/openswmm_2d.h 341 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_init_depth include/openswmm/engine/openswmm_2d.h 242 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_init_velocity include/openswmm/engine/openswmm_2d.h 255 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_mannings include/openswmm/engine/openswmm_2d.h 226 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_neighbours include/openswmm/engine/openswmm_2d.h 298 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_triangle_get_vertices include/openswmm/engine/openswmm_2d.h 161 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_count include/openswmm/engine/openswmm_2d.h 91 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_coupling_count include/openswmm/engine/openswmm_2d.h 323 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_coupled_node include/openswmm/engine/openswmm_2d.h 333 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_head include/openswmm/engine/openswmm_2d.h 633 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_heads_bulk include/openswmm/engine/openswmm_2d.h 638 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_render_depths_bulk include/openswmm/engine/openswmm_2d.h 650 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_xyz include/openswmm/engine/openswmm_2d.h 101 pyx_use python/openswmm/engine/_2d.pyx +swmm_2d_vertex_get_xyz_bulk include/openswmm/engine/openswmm_2d.h 107 pyx_use python/openswmm/engine/_2d.pyx +swmm_aquifer_add include/openswmm/engine/openswmm_subcatchments.h 856 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_analyze_impact include/openswmm/engine/openswmm_edit.h 166 pyx_use python/openswmm/engine/_edit.pyx +swmm_aquifer_count include/openswmm/engine/openswmm_subcatchments.h 827 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_delete include/openswmm/engine/openswmm_edit.h 347 pyx_use python/openswmm/engine/_edit.pyx +swmm_aquifer_get_evap_pattern include/openswmm/engine/openswmm_subcatchments.h 945 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_get_param include/openswmm/engine/openswmm_subcatchments.h 910 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_id include/openswmm/engine/openswmm_subcatchments.h 843 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_index include/openswmm/engine/openswmm_subcatchments.h 835 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_rename include/openswmm/engine/openswmm_subcatchments.h 873 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_set_evap_pattern include/openswmm/engine/openswmm_subcatchments.h 961 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_aquifer_set_param include/openswmm/engine/openswmm_subcatchments.h 926 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_buildup_get include/openswmm/engine/openswmm_quality.h 120 pyx_use python/openswmm/engine/_quality.pyx +swmm_buildup_set include/openswmm/engine/openswmm_quality.h 100 pyx_use python/openswmm/engine/_quality.pyx +swmm_climate_get_adc_impervious include/openswmm/engine/openswmm_climate.h 266 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_adc_pervious include/openswmm/engine/openswmm_climate.h 273 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_adjust_conductivity include/openswmm/engine/openswmm_climate.h 302 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_adjust_evaporation include/openswmm/engine/openswmm_climate.h 290 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_adjust_rainfall include/openswmm/engine/openswmm_climate.h 296 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_adjust_temperature include/openswmm/engine/openswmm_climate.h 284 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_ati_weight include/openswmm/engine/openswmm_climate.h 249 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_dry_only include/openswmm/engine/openswmm_forcing.h 469 pyx_use python/openswmm/engine/_forcing.pyx +swmm_climate_get_elevation include/openswmm/engine/openswmm_climate.h 146 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_evap_monthly include/openswmm/engine/openswmm_climate.h 174 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_evap_rate include/openswmm/engine/openswmm_forcing.h 368 pyx_use python/openswmm/engine/_forcing.pyx +swmm_climate_get_evap_recovery include/openswmm/engine/openswmm_climate.h 191 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_evap_timeseries include/openswmm/engine/openswmm_climate.h 180 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_evap_type include/openswmm/engine/openswmm_climate.h 167 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_humidity_monthly include/openswmm/engine/openswmm_climate.h 230 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_humidity_timeseries include/openswmm/engine/openswmm_climate.h 235 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_humidity_type include/openswmm/engine/openswmm_climate.h 216 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_humidity_variable include/openswmm/engine/openswmm_climate.h 222 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_latitude include/openswmm/engine/openswmm_climate.h 151 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_longitude_correction include/openswmm/engine/openswmm_climate.h 158 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_neg_melt_ratio include/openswmm/engine/openswmm_climate.h 255 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_pan_coeff include/openswmm/engine/openswmm_climate.h 186 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_snow_temp include/openswmm/engine/openswmm_climate.h 244 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_temp_file_start include/openswmm/engine/openswmm_climate.h 134 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_temp_source include/openswmm/engine/openswmm_climate.h 123 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_temp_timeseries include/openswmm/engine/openswmm_climate.h 129 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_temp_units include/openswmm/engine/openswmm_climate.h 140 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_temperature include/openswmm/engine/openswmm_forcing.h 402 pyx_use python/openswmm/engine/_forcing.pyx +swmm_climate_get_wind_monthly include/openswmm/engine/openswmm_climate.h 207 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_get_wind_speed include/openswmm/engine/openswmm_forcing.h 429 pyx_use python/openswmm/engine/_forcing.pyx +swmm_climate_get_wind_type include/openswmm/engine/openswmm_climate.h 200 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adc_impervious include/openswmm/engine/openswmm_climate.h 269 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adc_pervious include/openswmm/engine/openswmm_climate.h 276 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adjust_conductivity include/openswmm/engine/openswmm_climate.h 305 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adjust_evaporation include/openswmm/engine/openswmm_climate.h 292 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adjust_rainfall include/openswmm/engine/openswmm_climate.h 298 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_adjust_temperature include/openswmm/engine/openswmm_climate.h 286 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_ati_weight include/openswmm/engine/openswmm_climate.h 252 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_dry_only include/openswmm/engine/openswmm_forcing.h 459 pyx_use python/openswmm/engine/_forcing.pyx +swmm_climate_set_elevation include/openswmm/engine/openswmm_climate.h 148 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_evap_monthly include/openswmm/engine/openswmm_climate.h 177 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_evap_recovery include/openswmm/engine/openswmm_climate.h 193 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_evap_timeseries include/openswmm/engine/openswmm_climate.h 182 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_evap_type include/openswmm/engine/openswmm_climate.h 170 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_humidity_monthly include/openswmm/engine/openswmm_climate.h 232 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_humidity_timeseries include/openswmm/engine/openswmm_climate.h 237 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_humidity_type include/openswmm/engine/openswmm_climate.h 219 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_humidity_variable include/openswmm/engine/openswmm_climate.h 225 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_latitude include/openswmm/engine/openswmm_climate.h 154 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_longitude_correction include/openswmm/engine/openswmm_climate.h 160 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_neg_melt_ratio include/openswmm/engine/openswmm_climate.h 258 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_pan_coeff include/openswmm/engine/openswmm_climate.h 188 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_snow_temp include/openswmm/engine/openswmm_climate.h 246 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_temp_file_start include/openswmm/engine/openswmm_climate.h 136 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_temp_source include/openswmm/engine/openswmm_climate.h 126 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_temp_timeseries include/openswmm/engine/openswmm_climate.h 131 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_temp_units include/openswmm/engine/openswmm_climate.h 143 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_wind_monthly include/openswmm/engine/openswmm_climate.h 209 pyx_use python/openswmm/engine/_climate.pyx +swmm_climate_set_wind_type include/openswmm/engine/openswmm_climate.h 203 pyx_use python/openswmm/engine/_climate.pyx +swmm_conduit_split include/openswmm/engine/openswmm_edit.h 501 pyx_use python/openswmm/engine/_edit.pyx +swmm_conduit_split_inlet include/openswmm/engine/openswmm_edit.h 544 pyx_use python/openswmm/engine/_edit.pyx +swmm_control_add_rule include/openswmm/engine/openswmm_controls.h 70 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_clear_rules include/openswmm/engine/openswmm_controls.h 112 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_count include/openswmm/engine/openswmm_controls.h 77 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_find_references include/openswmm/engine/openswmm_controls.h 144 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_get_id include/openswmm/engine/openswmm_controls.h 105 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_get_rule include/openswmm/engine/openswmm_controls.h 87 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_remove_rule include/openswmm/engine/openswmm_controls.h 124 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_set_link_setting include/openswmm/engine/openswmm_controls.h 205 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_set_link_status include/openswmm/engine/openswmm_controls.h 217 pyx_use python/openswmm/engine/_controls.pyx +swmm_control_validate_rule include/openswmm/engine/openswmm_controls.h 185 pyx_use python/openswmm/engine/_controls.pyx +swmm_conversion_result_free include/openswmm/engine/openswmm_edit.h 423 pyx_use python/openswmm/engine/_edit.pyx +swmm_curve_add include/openswmm/engine/openswmm_tables.h 114 pyx_use python/openswmm/engine/_tables.pyx +swmm_datetime_add_seconds include/openswmm/engine/openswmm_datetime.h 175 pyx_use python/openswmm/engine/_datetime.pyx +swmm_datetime_decode_date include/openswmm/engine/openswmm_datetime.h 138 pyx_use python/openswmm/engine/_datetime.pyx +swmm_datetime_decode_time include/openswmm/engine/openswmm_datetime.h 155 pyx_use python/openswmm/engine/_datetime.pyx +swmm_datetime_encode_date include/openswmm/engine/openswmm_datetime.h 106 pyx_use python/openswmm/engine/_datetime.pyx +swmm_datetime_encode_time include/openswmm/engine/openswmm_datetime.h 121 pyx_use python/openswmm/engine/_datetime.pyx +swmm_datetime_time_diff include/openswmm/engine/openswmm_datetime.h 187 pyx_use python/openswmm/engine/_datetime.pyx +swmm_dwf_add include/openswmm/engine/openswmm_inflows.h 152 pyx_use python/openswmm/engine/_inflows.pyx +swmm_dwf_count include/openswmm/engine/openswmm_inflows.h 603 pyx_use python/openswmm/engine/_inflows.pyx +swmm_dwf_get include/openswmm/engine/openswmm_inflows.h 175 pyx_use python/openswmm/engine/_inflows.pyx +swmm_dwf_remove include/openswmm/engine/openswmm_inflows.h 190 pyx_use python/openswmm/engine/_inflows.pyx +swmm_dwf_set_baseline include/openswmm/engine/openswmm_inflows.h 198 pyx_use python/openswmm/engine/_inflows.pyx +swmm_engine_close include/openswmm/engine/openswmm_engine.h 236 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_create include/openswmm/engine/openswmm_engine.h 188 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_destroy include/openswmm/engine/openswmm_engine.h 239 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_end include/openswmm/engine/openswmm_engine.h 230 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_get_state include/openswmm/engine/openswmm_engine.h 242 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_initialize include/openswmm/engine/openswmm_engine.h 206 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_new include/openswmm/engine/openswmm_model.h 62 pyx_use python/openswmm/engine/_model.pyx +swmm_engine_open include/openswmm/engine/openswmm_engine.h 201 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_report include/openswmm/engine/openswmm_engine.h 233 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_run include/openswmm/engine/openswmm_engine.h 261 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_run_with_callback include/openswmm/engine/openswmm_engine.h 278 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_set_lenient_open include/openswmm/engine/openswmm_engine.h 314 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_start include/openswmm/engine/openswmm_engine.h 209 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_step include/openswmm/engine/openswmm_engine.h 212 pyx_use python/openswmm/engine/_solver.pyx +swmm_engine_stride include/openswmm/engine/openswmm_engine.h 227 pyx_use python/openswmm/engine/_solver.pyx +swmm_error_message include/openswmm/engine/openswmm_engine.h 302 existing_allowlist +swmm_events_add include/openswmm/engine/openswmm_engine.h 469 pyx_use python/openswmm/engine/_solver.pyx +swmm_events_clear include/openswmm/engine/openswmm_engine.h 477 pyx_use python/openswmm/engine/_solver.pyx +swmm_events_count include/openswmm/engine/openswmm_engine.h 453 pyx_use python/openswmm/engine/_solver.pyx +swmm_events_get include/openswmm/engine/openswmm_engine.h 457 pyx_use python/openswmm/engine/_solver.pyx +swmm_events_remove include/openswmm/engine/openswmm_engine.h 474 pyx_use python/openswmm/engine/_solver.pyx +swmm_events_set include/openswmm/engine/openswmm_engine.h 463 pyx_use python/openswmm/engine/_solver.pyx +swmm_ext_inflow_add include/openswmm/engine/openswmm_inflows.h 68 pyx_use python/openswmm/engine/_inflows.pyx +swmm_ext_inflow_count include/openswmm/engine/openswmm_inflows.h 596 pyx_use python/openswmm/engine/_inflows.pyx +swmm_ext_inflow_get include/openswmm/engine/openswmm_inflows.h 96 pyx_use python/openswmm/engine/_inflows.pyx +swmm_ext_inflow_remove include/openswmm/engine/openswmm_inflows.h 115 pyx_use python/openswmm/engine/_inflows.pyx +swmm_ext_inflow_set_baseline include/openswmm/engine/openswmm_inflows.h 130 pyx_use python/openswmm/engine/_inflows.pyx +swmm_ext_inflow_set_scale include/openswmm/engine/openswmm_inflows.h 123 pyx_use python/openswmm/engine/_inflows.pyx +swmm_file_path_get include/openswmm/engine/openswmm_model.h 398 pyx_use python/openswmm/engine/_model.pyx +swmm_file_path_set include/openswmm/engine/openswmm_model.h 419 pyx_use python/openswmm/engine/_model.pyx +swmm_files_get include/openswmm/engine/openswmm_model.h 307 pyx_use python/openswmm/engine/_model.pyx +swmm_files_set include/openswmm/engine/openswmm_model.h 322 pyx_use python/openswmm/engine/_model.pyx +swmm_finalize_model include/openswmm/engine/openswmm_model.h 91 pyx_use python/openswmm/engine/_model.pyx +swmm_forcing_clear include/openswmm/engine/openswmm_forcing.h 560 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_clear_all include/openswmm/engine/openswmm_forcing.h 569 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_climate_evap include/openswmm/engine/openswmm_forcing.h 448 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_climate_temperature include/openswmm/engine/openswmm_forcing.h 391 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_climate_wind include/openswmm/engine/openswmm_forcing.h 418 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_element_climate include/openswmm/engine/openswmm_forcing.h 547 gap +swmm_forcing_element_climate_get include/openswmm/engine/openswmm_forcing.h 556 gap +swmm_forcing_gage_rainfall include/openswmm/engine/openswmm_forcing.h 486 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_link_flow include/openswmm/engine/openswmm_forcing.h 224 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_link_quality include/openswmm/engine/openswmm_forcing.h 291 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_link_seepage include/openswmm/engine/openswmm_forcing.h 272 gap +swmm_forcing_link_setting include/openswmm/engine/openswmm_forcing.h 238 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_node_age include/openswmm/engine/openswmm_forcing.h 206 gap +swmm_forcing_node_head_boundary include/openswmm/engine/openswmm_forcing.h 161 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_node_lat_inflow include/openswmm/engine/openswmm_forcing.h 147 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_node_quality include/openswmm/engine/openswmm_forcing.h 176 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_node_temperature include/openswmm/engine/openswmm_forcing.h 193 gap +swmm_forcing_subcatch_evap include/openswmm/engine/openswmm_forcing.h 331 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_subcatch_rainfall include/openswmm/engine/openswmm_forcing.h 310 pyx_use python/openswmm/engine/_forcing.pyx +swmm_forcing_subcatch_snowfall include/openswmm/engine/openswmm_forcing.h 351 pyx_use python/openswmm/engine/_forcing.pyx +swmm_gage_add include/openswmm/engine/openswmm_gages.h 95 pyx_use python/openswmm/engine/_gages.pyx;python/openswmm/engine/_model.pyx +swmm_gage_analyze_impact include/openswmm/engine/openswmm_edit.h 146 pyx_use python/openswmm/engine/_edit.pyx +swmm_gage_count include/openswmm/engine/openswmm_gages.h 66 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_gages.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_gage_delete include/openswmm/engine/openswmm_edit.h 251 pyx_use python/openswmm/engine/_edit.pyx +swmm_gage_delete_many include/openswmm/engine/openswmm_edit.h 297 gap +swmm_gage_get_data_source include/openswmm/engine/openswmm_gages.h 258 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_file_column include/openswmm/engine/openswmm_gages.h 318 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_file_format include/openswmm/engine/openswmm_gages.h 330 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rain_interval include/openswmm/engine/openswmm_gages.h 276 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rain_type include/openswmm/engine/openswmm_gages.h 249 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rain_units include/openswmm/engine/openswmm_gages.h 339 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rainfall include/openswmm/engine/openswmm_gages.h 346 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rainfall_bulk include/openswmm/engine/openswmm_gages.h 367 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rainfall_series include/openswmm/engine/openswmm_gages.h 426 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_rainfall_series_count include/openswmm/engine/openswmm_gages.h 392 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_scale_factor include/openswmm/engine/openswmm_gages.h 267 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_snow_factor include/openswmm/engine/openswmm_gages.h 285 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_station_id include/openswmm/engine/openswmm_gages.h 307 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_get_timeseries include/openswmm/engine/openswmm_gages.h 296 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_id include/openswmm/engine/openswmm_gages.h 82 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_index include/openswmm/engine/openswmm_gages.h 74 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_gages.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_gage_reload_rain_files include/openswmm/engine/openswmm_gages.h 446 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_rename include/openswmm/engine/openswmm_gages.h 372 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_data_source include/openswmm/engine/openswmm_gages.h 126 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_file_column include/openswmm/engine/openswmm_gages.h 180 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_file_format include/openswmm/engine/openswmm_gages.h 203 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_filename include/openswmm/engine/openswmm_gages.h 154 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_rain_interval include/openswmm/engine/openswmm_gages.h 117 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_rain_type include/openswmm/engine/openswmm_gages.h 108 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_rain_units include/openswmm/engine/openswmm_gages.h 221 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_rainfall include/openswmm/engine/openswmm_gages.h 354 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_scale_factor include/openswmm/engine/openswmm_gages.h 236 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_snow_factor include/openswmm/engine/openswmm_gages.h 212 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_station_id include/openswmm/engine/openswmm_gages.h 164 pyx_use python/openswmm/engine/_gages.pyx +swmm_gage_set_timeseries include/openswmm/engine/openswmm_gages.h 135 pyx_use python/openswmm/engine/_gages.pyx +swmm_get_crs include/openswmm/engine/openswmm_model.h 560 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_get_current_time include/openswmm/engine/openswmm_engine.h 413 existing_allowlist python/openswmm/engine/_solver.pyx +swmm_get_effective_threads include/openswmm/engine/openswmm_engine.h 360 gap +swmm_get_end_time include/openswmm/engine/openswmm_engine.h 412 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_error_at include/openswmm/engine/openswmm_engine.h 319 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_error_count include/openswmm/engine/openswmm_engine.h 318 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_event_count include/openswmm/engine/openswmm_engine.h 441 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_flow_units include/openswmm/engine/openswmm_engine.h 426 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_last_error include/openswmm/engine/openswmm_engine.h 300 existing_allowlist +swmm_get_last_error_msg include/openswmm/engine/openswmm_engine.h 301 existing_allowlist +swmm_get_max_courant include/openswmm/engine/openswmm_massbalance.h 151 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_quality_continuity_error include/openswmm/engine/openswmm_massbalance.h 52 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_quality_evap_loss include/openswmm/engine/openswmm_massbalance.h 161 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_quality_seep_loss include/openswmm/engine/openswmm_massbalance.h 158 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_routing_continuity_error include/openswmm/engine/openswmm_massbalance.h 49 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_routing_stats include/openswmm/engine/openswmm_massbalance.h 145 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_routing_step include/openswmm/engine/openswmm_engine.h 414 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_routing_total include/openswmm/engine/openswmm_massbalance.h 138 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_runoff_continuity_error include/openswmm/engine/openswmm_massbalance.h 46 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_runoff_total include/openswmm/engine/openswmm_massbalance.h 129 pyx_use python/openswmm/engine/_massbalance.pyx +swmm_get_start_time include/openswmm/engine/openswmm_engine.h 411 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_steady_state_skip include/openswmm/engine/openswmm_engine.h 480 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_thread_info include/openswmm/engine/openswmm_engine.h 345 gap +swmm_get_transport_matrix include/openswmm/engine/openswmm_engine.h 401 gap +swmm_get_unit_system include/openswmm/engine/openswmm_engine.h 430 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_warning_at include/openswmm/engine/openswmm_engine.h 321 pyx_use python/openswmm/engine/_solver.pyx +swmm_get_warning_count include/openswmm/engine/openswmm_engine.h 320 pyx_use python/openswmm/engine/_solver.pyx +swmm_gpkg_begin include/openswmm/engine/openswmm_geopackage.h 146 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_close include/openswmm/engine/openswmm_geopackage.h 123 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_commit include/openswmm/engine/openswmm_geopackage.h 153 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_create_observed_series include/openswmm/engine/openswmm_geopackage.h 310 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_gage_count include/openswmm/engine/openswmm_geopackage.h 216 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_is_registered include/openswmm/engine/openswmm_geopackage.h 184 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_last_error include/openswmm/engine/openswmm_geopackage.h 130 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_link_count include/openswmm/engine/openswmm_geopackage.h 214 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_node_count include/openswmm/engine/openswmm_geopackage.h 213 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_observed_series_count include/openswmm/engine/openswmm_geopackage.h 370 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_observed_value_count include/openswmm/engine/openswmm_geopackage.h 378 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_open include/openswmm/engine/openswmm_geopackage.h 114 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_query_double include/openswmm/engine/openswmm_geopackage.h 418 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_query_int include/openswmm/engine/openswmm_geopackage.h 409 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_read_observed_values include/openswmm/engine/openswmm_geopackage.h 392 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_read_result_ts include/openswmm/engine/openswmm_geopackage.h 241 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_read_summary include/openswmm/engine/openswmm_geopackage.h 283 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_register include/openswmm/engine/openswmm_geopackage.h 175 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_result_ts_count include/openswmm/engine/openswmm_geopackage.h 262 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_rollback include/openswmm/engine/openswmm_geopackage.h 160 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_simulation_count include/openswmm/engine/openswmm_geopackage.h 195 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_simulation_id include/openswmm/engine/openswmm_geopackage.h 206 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_subcatch_count include/openswmm/engine/openswmm_geopackage.h 215 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_topology_edge_count include/openswmm/engine/openswmm_geopackage.h 217 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_variable_count include/openswmm/engine/openswmm_geopackage.h 218 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_write_observed_value include/openswmm/engine/openswmm_geopackage.h 328 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gpkg_write_observed_values include/openswmm/engine/openswmm_geopackage.h 354 pyx_use python/openswmm/engine/_geopackage.pyx +swmm_gw2d_get_cell include/openswmm/engine/openswmm_gw2d.h 261 gap +swmm_gw2d_get_cell_bulk include/openswmm/engine/openswmm_gw2d.h 266 gap +swmm_gw2d_get_cell_conc include/openswmm/engine/openswmm_gw2d.h 144 gap +swmm_gw2d_get_column include/openswmm/engine/openswmm_gw2d.h 273 gap +swmm_gw2d_get_continuity_error include/openswmm/engine/openswmm_gw2d.h 290 gap +swmm_gw2d_get_dimensions include/openswmm/engine/openswmm_gw2d.h 257 gap +swmm_gw2d_get_ledger include/openswmm/engine/openswmm_gw2d.h 278 gap +swmm_gw2d_get_species_ledger include/openswmm/engine/openswmm_gw2d.h 149 gap +swmm_gw2d_get_tier_histogram include/openswmm/engine/openswmm_gw2d.h 295 gap +swmm_gw2d_is_active include/openswmm/engine/openswmm_gw2d.h 253 gap +swmm_gw2d_node_add include/openswmm/engine/openswmm_gw2d.h 224 gap +swmm_gw2d_node_count include/openswmm/engine/openswmm_gw2d.h 220 gap +swmm_gw2d_node_get include/openswmm/engine/openswmm_gw2d.h 228 gap +swmm_gw2d_node_get_flags include/openswmm/engine/openswmm_gw2d.h 240 gap +swmm_gw2d_node_remove include/openswmm/engine/openswmm_gw2d.h 232 gap +swmm_gw2d_node_set_exchange include/openswmm/engine/openswmm_gw2d.h 245 gap +swmm_gw2d_option_get include/openswmm/engine/openswmm_gw2d.h 160 gap +swmm_gw2d_option_set include/openswmm/engine/openswmm_gw2d.h 165 gap +swmm_gw2d_row_add include/openswmm/engine/openswmm_gw2d.h 187 gap +swmm_gw2d_row_count include/openswmm/engine/openswmm_gw2d.h 173 gap +swmm_gw2d_row_get include/openswmm/engine/openswmm_gw2d.h 195 gap +swmm_gw2d_row_get_property include/openswmm/engine/openswmm_gw2d.h 210 gap +swmm_gw2d_row_remove include/openswmm/engine/openswmm_gw2d.h 214 gap +swmm_gw2d_row_set_property include/openswmm/engine/openswmm_gw2d.h 206 gap +swmm_gw2d_species_count include/openswmm/engine/openswmm_gw2d.h 134 gap +swmm_gw2d_species_name include/openswmm/engine/openswmm_gw2d.h 138 gap +swmm_gw_boundary_quality_count include/openswmm/engine/openswmm_gw_transport.h 152 gap +swmm_gw_boundary_quality_get include/openswmm/engine/openswmm_gw_transport.h 153 gap +swmm_gw_boundary_quality_remove include/openswmm/engine/openswmm_gw_transport.h 161 gap +swmm_gw_boundary_quality_set include/openswmm/engine/openswmm_gw_transport.h 158 gap +swmm_gw_init_quality_count include/openswmm/engine/openswmm_gw_transport.h 130 gap +swmm_gw_init_quality_file_get include/openswmm/engine/openswmm_gw_transport.h 140 gap +swmm_gw_init_quality_file_set include/openswmm/engine/openswmm_gw_transport.h 142 gap +swmm_gw_init_quality_get include/openswmm/engine/openswmm_gw_transport.h 132 gap +swmm_gw_init_quality_remove include/openswmm/engine/openswmm_gw_transport.h 138 gap +swmm_gw_init_quality_set include/openswmm/engine/openswmm_gw_transport.h 135 gap +swmm_gw_params_count include/openswmm/engine/openswmm_gw_transport.h 104 gap +swmm_gw_params_get include/openswmm/engine/openswmm_gw_transport.h 106 gap +swmm_gw_params_remove include/openswmm/engine/openswmm_gw_transport.h 111 gap +swmm_gw_params_set include/openswmm/engine/openswmm_gw_transport.h 109 gap +swmm_gw_sorption_count include/openswmm/engine/openswmm_gw_transport.h 117 gap +swmm_gw_sorption_get include/openswmm/engine/openswmm_gw_transport.h 119 gap +swmm_gw_sorption_remove include/openswmm/engine/openswmm_gw_transport.h 124 gap +swmm_gw_sorption_set include/openswmm/engine/openswmm_gw_transport.h 122 gap +swmm_gw_source_count include/openswmm/engine/openswmm_gw_transport.h 167 gap +swmm_gw_source_get include/openswmm/engine/openswmm_gw_transport.h 168 gap +swmm_gw_source_remove include/openswmm/engine/openswmm_gw_transport.h 174 gap +swmm_gw_source_set include/openswmm/engine/openswmm_gw_transport.h 172 gap +swmm_gw_source_species_count include/openswmm/engine/openswmm_gw_transport.h 177 gap +swmm_gw_source_species_get include/openswmm/engine/openswmm_gw_transport.h 178 gap +swmm_gw_source_species_remove include/openswmm/engine/openswmm_gw_transport.h 184 gap +swmm_gw_source_species_set include/openswmm/engine/openswmm_gw_transport.h 182 gap +swmm_gw_transport_authored include/openswmm/engine/openswmm_gw_transport.h 84 gap +swmm_gw_transport_option_get include/openswmm/engine/openswmm_gw_transport.h 76 gap +swmm_gw_transport_option_set include/openswmm/engine/openswmm_gw_transport.h 80 gap +swmm_gwf_function_count include/openswmm/engine/openswmm_subcatchments.h 1269 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_gwf_function_name include/openswmm/engine/openswmm_subcatchments.h 1281 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_gwf_validate_expression include/openswmm/engine/openswmm_subcatchments.h 1233 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_gwf_variable_count include/openswmm/engine/openswmm_subcatchments.h 1241 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_gwf_variable_description include/openswmm/engine/openswmm_subcatchments.h 1262 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_gwf_variable_name include/openswmm/engine/openswmm_subcatchments.h 1251 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_heat_clear_cloud include/openswmm/engine/openswmm_heat.h 233 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_clear_source_temp include/openswmm/engine/openswmm_heat.h 292 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_cloud include/openswmm/engine/openswmm_heat.h 208 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_cloud_configured include/openswmm/engine/openswmm_heat.h 204 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_cloud_timeseries include/openswmm/engine/openswmm_heat.h 226 gap +swmm_heat_get_current_cloud include/openswmm/engine/openswmm_heat.h 236 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_current_shortwave include/openswmm/engine/openswmm_heat.h 180 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_effective_source_temp include/openswmm/engine/openswmm_heat.h 329 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_enabled include/openswmm/engine/openswmm_heat.h 124 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_module include/openswmm/engine/openswmm_heat.h 127 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_node_override include/openswmm/engine/openswmm_heat.h 300 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_radiative include/openswmm/engine/openswmm_heat.h 136 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_shortwave_mode include/openswmm/engine/openswmm_heat.h 151 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_shortwave_timeseries include/openswmm/engine/openswmm_heat.h 174 gap +swmm_heat_get_solar include/openswmm/engine/openswmm_heat.h 186 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_solar_sited include/openswmm/engine/openswmm_heat.h 199 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_source_configured include/openswmm/engine/openswmm_heat.h 284 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_get_source_temp include/openswmm/engine/openswmm_heat.h 270 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_node_override_count include/openswmm/engine/openswmm_heat.h 296 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_remove_node_override include/openswmm/engine/openswmm_heat.h 321 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_cloud include/openswmm/engine/openswmm_heat.h 214 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_cloud_timeseries include/openswmm/engine/openswmm_heat.h 219 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_module include/openswmm/engine/openswmm_heat.h 130 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_node_override include/openswmm/engine/openswmm_heat.h 315 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_radiative include/openswmm/engine/openswmm_heat.h 147 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_shortwave_mode include/openswmm/engine/openswmm_heat.h 158 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_shortwave_timeseries include/openswmm/engine/openswmm_heat.h 164 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_solar include/openswmm/engine/openswmm_heat.h 192 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_set_source_temp include/openswmm/engine/openswmm_heat.h 278 pyx_use python/openswmm/engine/_heat.pyx +swmm_heat_source_count include/openswmm/engine/openswmm_heat.h 264 pyx_use python/openswmm/engine/_heat.pyx +swmm_hotstart_apply include/openswmm/engine/openswmm_hotstart.h 250 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_close include/openswmm/engine/openswmm_hotstart.h 397 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_get_crs include/openswmm/engine/openswmm_hotstart.h 344 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_get_sim_time include/openswmm/engine/openswmm_hotstart.h 335 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_link_count include/openswmm/engine/openswmm_hotstart.h 358 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_node_count include/openswmm/engine/openswmm_hotstart.h 351 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_open include/openswmm/engine/openswmm_hotstart.h 227 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_save include/openswmm/engine/openswmm_hotstart.h 211 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_add include/openswmm/engine/openswmm_hotstart.h 175 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_clear include/openswmm/engine/openswmm_hotstart.h 191 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_count include/openswmm/engine/openswmm_hotstart.h 114 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_get_datetime include/openswmm/engine/openswmm_hotstart.h 135 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_get_path include/openswmm/engine/openswmm_hotstart.h 124 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_remove include/openswmm/engine/openswmm_hotstart.h 184 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_set_datetime include/openswmm/engine/openswmm_hotstart.h 163 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_saves_set_path include/openswmm/engine/openswmm_hotstart.h 152 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_set_link_depth include/openswmm/engine/openswmm_hotstart.h 306 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_set_link_flow include/openswmm/engine/openswmm_hotstart.h 293 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_set_node_depth include/openswmm/engine/openswmm_hotstart.h 267 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_set_node_head include/openswmm/engine/openswmm_hotstart.h 280 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_set_subcatch_runoff include/openswmm/engine/openswmm_hotstart.h 319 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_warning include/openswmm/engine/openswmm_hotstart.h 382 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hotstart_warning_count include/openswmm/engine/openswmm_hotstart.h 373 pyx_use python/openswmm/engine/_hotstart.pyx +swmm_hydrograph_add include/openswmm/engine/openswmm_inflows.h 274 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_add_gage include/openswmm/engine/openswmm_inflows.h 316 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_analyze_impact include/openswmm/engine/openswmm_edit.h 202 pyx_use python/openswmm/engine/_edit.pyx +swmm_hydrograph_clear_group_months include/openswmm/engine/openswmm_inflows.h 462 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_count include/openswmm/engine/openswmm_inflows.h 306 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_delete include/openswmm/engine/openswmm_edit.h 395 pyx_use python/openswmm/engine/_edit.pyx +swmm_hydrograph_gage_count include/openswmm/engine/openswmm_inflows.h 339 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_get include/openswmm/engine/openswmm_inflows.h 296 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_get_gage include/openswmm/engine/openswmm_inflows.h 331 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_group_count include/openswmm/engine/openswmm_inflows.h 353 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_group_id include/openswmm/engine/openswmm_inflows.h 368 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_group_rename include/openswmm/engine/openswmm_inflows.h 486 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_remove_entry include/openswmm/engine/openswmm_inflows.h 441 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_remove_group include/openswmm/engine/openswmm_inflows.h 450 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_set_gage include/openswmm/engine/openswmm_inflows.h 473 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_set_ia include/openswmm/engine/openswmm_inflows.h 428 pyx_use python/openswmm/engine/_inflows.pyx +swmm_hydrograph_set_rtk include/openswmm/engine/openswmm_inflows.h 412 pyx_use python/openswmm/engine/_inflows.pyx +swmm_impact_report_free include/openswmm/engine/openswmm_edit.h 120 pyx_use python/openswmm/engine/_edit.pyx +swmm_infil2d_defaults_count include/openswmm/engine/openswmm_infil2d.h 220 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_cell include/openswmm/engine/openswmm_infil2d.h 320 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_cum_bulk include/openswmm/engine/openswmm_infil2d.h 412 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_default include/openswmm/engine/openswmm_infil2d.h 234 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_default_tag include/openswmm/engine/openswmm_infil2d.h 249 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_options include/openswmm/engine/openswmm_infil2d.h 178 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_rate_bulk include/openswmm/engine/openswmm_infil2d.h 392 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_get_total_volume include/openswmm/engine/openswmm_infil2d.h 428 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_remove_default include/openswmm/engine/openswmm_infil2d.h 290 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_set_cell include/openswmm/engine/openswmm_infil2d.h 343 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_set_cells include/openswmm/engine/openswmm_infil2d.h 368 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_set_default include/openswmm/engine/openswmm_infil2d.h 273 pyx_use python/openswmm/engine/_2d.pyx +swmm_infil2d_set_options include/openswmm/engine/openswmm_infil2d.h 203 pyx_use python/openswmm/engine/_2d.pyx +swmm_init_quality_count include/openswmm/engine/openswmm_initial_quality.h 59 pyx_use python/openswmm/engine/_initial_quality.pyx +swmm_init_quality_file_get include/openswmm/engine/openswmm_initial_quality.h 114 gap +swmm_init_quality_file_set include/openswmm/engine/openswmm_initial_quality.h 117 gap +swmm_init_quality_get include/openswmm/engine/openswmm_initial_quality.h 72 pyx_use python/openswmm/engine/_initial_quality.pyx +swmm_init_quality_is_file include/openswmm/engine/openswmm_initial_quality.h 120 gap +swmm_init_quality_remove include/openswmm/engine/openswmm_initial_quality.h 102 pyx_use python/openswmm/engine/_initial_quality.pyx +swmm_init_quality_set include/openswmm/engine/openswmm_initial_quality.h 91 pyx_use python/openswmm/engine/_initial_quality.pyx +swmm_inlet_add include/openswmm/engine/openswmm_infrastructure.h 407 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_analyze_impact include/openswmm/engine/openswmm_edit.h 182 pyx_use python/openswmm/engine/_edit.pyx +swmm_inlet_count include/openswmm/engine/openswmm_infrastructure.h 443 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_delete include/openswmm/engine/openswmm_edit.h 375 pyx_use python/openswmm/engine/_edit.pyx +swmm_inlet_get_comment include/openswmm/engine/openswmm_infrastructure.h 599 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_get_design include/openswmm/engine/openswmm_infrastructure.h 578 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_get_params include/openswmm/engine/openswmm_infrastructure.h 481 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_get_type include/openswmm/engine/openswmm_infrastructure.h 494 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_id include/openswmm/engine/openswmm_infrastructure.h 459 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_index include/openswmm/engine/openswmm_infrastructure.h 451 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_infrastructure.pyx +swmm_inlet_junction_fuse include/openswmm/engine/openswmm_edit.h 555 pyx_use python/openswmm/engine/_edit.pyx +swmm_inlet_rename include/openswmm/engine/openswmm_infrastructure.h 422 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_set_comment include/openswmm/engine/openswmm_infrastructure.h 600 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_set_design include/openswmm/engine/openswmm_infrastructure.h 594 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_set_params include/openswmm/engine/openswmm_infrastructure.h 435 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_count include/openswmm/engine/openswmm_infrastructure.h 627 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_find_link include/openswmm/engine/openswmm_infrastructure.h 630 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_find_node include/openswmm/engine/openswmm_infrastructure.h 633 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_get include/openswmm/engine/openswmm_infrastructure.h 639 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_remove include/openswmm/engine/openswmm_infrastructure.h 662 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_inlet_usage_set include/openswmm/engine/openswmm_infrastructure.h 655 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_is_between_events include/openswmm/engine/openswmm_engine.h 437 pyx_use python/openswmm/engine/_solver.pyx +swmm_landuse_add include/openswmm/engine/openswmm_quality.h 56 pyx_use python/openswmm/engine/_quality.pyx +swmm_landuse_analyze_impact include/openswmm/engine/openswmm_edit.h 186 pyx_use python/openswmm/engine/_edit.pyx +swmm_landuse_count include/openswmm/engine/openswmm_quality.h 47 pyx_use python/openswmm/engine/_quality.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_landuse_delete include/openswmm/engine/openswmm_edit.h 382 pyx_use python/openswmm/engine/_edit.pyx +swmm_landuse_get_sweep_interval include/openswmm/engine/openswmm_quality.h 76 pyx_use python/openswmm/engine/_quality.pyx +swmm_landuse_get_sweep_removal include/openswmm/engine/openswmm_quality.h 82 pyx_use python/openswmm/engine/_quality.pyx +swmm_landuse_id include/openswmm/engine/openswmm_quality.h 53 pyx_use python/openswmm/engine/_quality.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_landuse_index include/openswmm/engine/openswmm_quality.h 50 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_quality.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_landuse_rename include/openswmm/engine/openswmm_quality.h 70 pyx_use python/openswmm/engine/_quality.pyx +swmm_landuse_set_sweep_interval include/openswmm/engine/openswmm_quality.h 73 pyx_use python/openswmm/engine/_quality.pyx +swmm_landuse_set_sweep_removal include/openswmm/engine/openswmm_quality.h 79 pyx_use python/openswmm/engine/_quality.pyx +swmm_lid_add include/openswmm/engine/openswmm_infrastructure.h 680 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_analyze_impact include/openswmm/engine/openswmm_edit.h 174 pyx_use python/openswmm/engine/_edit.pyx +swmm_lid_count include/openswmm/engine/openswmm_infrastructure.h 789 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_delete include/openswmm/engine/openswmm_edit.h 361 pyx_use python/openswmm/engine/_edit.pyx +swmm_lid_get_drain include/openswmm/engine/openswmm_infrastructure.h 831 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_drainmat include/openswmm/engine/openswmm_infrastructure.h 838 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_pavement include/openswmm/engine/openswmm_infrastructure.h 834 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_soil include/openswmm/engine/openswmm_infrastructure.h 825 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_storage include/openswmm/engine/openswmm_infrastructure.h 828 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_surface include/openswmm/engine/openswmm_infrastructure.h 822 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_get_type include/openswmm/engine/openswmm_infrastructure.h 815 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_id include/openswmm/engine/openswmm_infrastructure.h 805 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_index include/openswmm/engine/openswmm_infrastructure.h 797 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_infrastructure.pyx +swmm_lid_rename include/openswmm/engine/openswmm_infrastructure.h 698 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_drain include/openswmm/engine/openswmm_infrastructure.h 745 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_drainmat include/openswmm/engine/openswmm_infrastructure.h 782 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_pavement include/openswmm/engine/openswmm_infrastructure.h 765 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_soil include/openswmm/engine/openswmm_infrastructure.h 723 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_storage include/openswmm/engine/openswmm_infrastructure.h 734 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_set_surface include/openswmm/engine/openswmm_infrastructure.h 709 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_usage_add include/openswmm/engine/openswmm_infrastructure.h 860 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_usage_count include/openswmm/engine/openswmm_infrastructure.h 869 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_usage_get include/openswmm/engine/openswmm_infrastructure.h 886 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_lid_usage_remove include/openswmm/engine/openswmm_infrastructure.h 896 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_link_add include/openswmm/engine/openswmm_links.h 152 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_link_analyze_impact include/openswmm/engine/openswmm_edit.h 138 pyx_use python/openswmm/engine/_edit.pyx +swmm_link_convert include/openswmm/engine/openswmm_edit.h 465 pyx_use python/openswmm/engine/_edit.pyx +swmm_link_count include/openswmm/engine/openswmm_links.h 114 pyx_use python/openswmm/engine/_controls.pyx;python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_initial_quality.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_statistics.pyx +swmm_link_create_xsect include/openswmm/engine/openswmm_xsect.h 231 pyx_use python/openswmm/engine/_xsect.pyx +swmm_link_delete include/openswmm/engine/openswmm_edit.h 235 pyx_use python/openswmm/engine/_edit.pyx +swmm_link_delete_many include/openswmm/engine/openswmm_edit.h 287 gap +swmm_link_get_barrels include/openswmm/engine/openswmm_links.h 892 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_capacities_bulk include/openswmm/engine/openswmm_links.h 1074 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_capacity include/openswmm/engine/openswmm_links.h 620 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_closed include/openswmm/engine/openswmm_links.h 681 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_control_setting include/openswmm/engine/openswmm_links.h 655 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_control_settings_bulk include/openswmm/engine/openswmm_links.h 1088 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_crest_height include/openswmm/engine/openswmm_links.h 747 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_culvert_code include/openswmm/engine/openswmm_links.h 874 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_depth include/openswmm/engine/openswmm_links.h 602 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_depths_bulk include/openswmm/engine/openswmm_links.h 1020 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_discharge_coeff include/openswmm/engine/openswmm_links.h 765 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_end_contractions include/openswmm/engine/openswmm_links.h 787 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_flap_gate include/openswmm/engine/openswmm_links.h 834 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_flow include/openswmm/engine/openswmm_links.h 584 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_flows_bulk include/openswmm/engine/openswmm_links.h 1011 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_from_node include/openswmm/engine/openswmm_links.h 195 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_hyd_power include/openswmm/engine/openswmm_links.h 1213 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_hyd_powers_bulk include/openswmm/engine/openswmm_links.h 1106 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_ids_bulk include/openswmm/engine/openswmm_links.h 1128 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_initial_flow include/openswmm/engine/openswmm_links.h 293 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_length include/openswmm/engine/openswmm_links.h 562 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_loss_coeff include/openswmm/engine/openswmm_links.h 813 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_max_flow include/openswmm/engine/openswmm_links.h 307 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_offset_dn include/openswmm/engine/openswmm_links.h 919 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_offset_up include/openswmm/engine/openswmm_links.h 910 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_orifice_open_close_rate include/openswmm/engine/openswmm_links.h 502 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_orifice_type include/openswmm/engine/openswmm_links.h 347 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_outlet_expon include/openswmm/engine/openswmm_links.h 461 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_outlet_rating_type include/openswmm/engine/openswmm_links.h 439 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_pump_curve include/openswmm/engine/openswmm_links.h 707 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_pump_init_state include/openswmm/engine/openswmm_links.h 725 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_pump_shutoff_depth include/openswmm/engine/openswmm_links.h 485 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_pump_startup_depth include/openswmm/engine/openswmm_links.h 473 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_pump_stats_bulk include/openswmm/engine/openswmm_links.h 1202 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_quality include/openswmm/engine/openswmm_links.h 997 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_quality_bulk include/openswmm/engine/openswmm_links.h 1039 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_roughness include/openswmm/engine/openswmm_links.h 571 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_seep_rate include/openswmm/engine/openswmm_links.h 852 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_slope include/openswmm/engine/openswmm_links.h 901 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_slot_volume include/openswmm/engine/openswmm_links.h 642 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_max_filling include/openswmm/engine/openswmm_links.h 950 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_max_flow include/openswmm/engine/openswmm_links.h 932 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_max_velocity include/openswmm/engine/openswmm_links.h 941 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_peak_slot_share include/openswmm/engine/openswmm_links.h 957 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_pump_cycles include/openswmm/engine/openswmm_links.h 1138 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_pump_on_time include/openswmm/engine/openswmm_links.h 1141 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_pump_volume include/openswmm/engine/openswmm_links.h 1144 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_slot_share include/openswmm/engine/openswmm_links.h 965 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_surcharge_time include/openswmm/engine/openswmm_links.h 983 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_stat_vol_flow include/openswmm/engine/openswmm_links.h 974 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_tag include/openswmm/engine/openswmm_links.h 1225 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_target_setting include/openswmm/engine/openswmm_links.h 669 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_target_settings_bulk include/openswmm/engine/openswmm_links.h 1095 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_to_node include/openswmm/engine/openswmm_links.h 204 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_type include/openswmm/engine/openswmm_links.h 553 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_velocities_bulk include/openswmm/engine/openswmm_links.h 1066 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_velocity include/openswmm/engine/openswmm_links.h 611 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_volume include/openswmm/engine/openswmm_links.h 629 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_volumes_bulk include/openswmm/engine/openswmm_links.h 1081 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_weir_type include/openswmm/engine/openswmm_links.h 397 pyx_use python/openswmm/engine/_links.pyx +swmm_link_get_xsect include/openswmm/engine/openswmm_links.h 538 pyx_use python/openswmm/engine/_links.pyx +swmm_link_id include/openswmm/engine/openswmm_links.h 130 pyx_use python/openswmm/engine/_links.pyx +swmm_link_index include/openswmm/engine/openswmm_links.h 122 pyx_use python/openswmm/engine/_controls.pyx;python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_initial_quality.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_spatial.pyx +swmm_link_pop_last include/openswmm/engine/openswmm_links.h 171 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_link_rename include/openswmm/engine/openswmm_links.h 1218 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_barrels include/openswmm/engine/openswmm_links.h 883 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_closed include/openswmm/engine/openswmm_links.h 678 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_control_setting include/openswmm/engine/openswmm_links.h 652 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_crest_height include/openswmm/engine/openswmm_links.h 738 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_culvert_code include/openswmm/engine/openswmm_links.h 865 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_discharge_coeff include/openswmm/engine/openswmm_links.h 756 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_end_contractions include/openswmm/engine/openswmm_links.h 778 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_flap_gate include/openswmm/engine/openswmm_links.h 825 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_flow include/openswmm/engine/openswmm_links.h 593 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_flows_bulk include/openswmm/engine/openswmm_links.h 1029 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_initial_flow include/openswmm/engine/openswmm_links.h 269 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_length include/openswmm/engine/openswmm_links.h 233 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_link_set_loss_coeff include/openswmm/engine/openswmm_links.h 802 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_max_flow include/openswmm/engine/openswmm_links.h 278 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_nodes include/openswmm/engine/openswmm_links.h 185 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_link_set_offset_dn include/openswmm/engine/openswmm_links.h 260 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_offset_up include/openswmm/engine/openswmm_links.h 251 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_orifice_open_close_rate include/openswmm/engine/openswmm_links.h 499 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_orifice_type include/openswmm/engine/openswmm_links.h 335 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_outlet_expon include/openswmm/engine/openswmm_links.h 453 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_outlet_rating_type include/openswmm/engine/openswmm_links.h 431 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_pump_curve include/openswmm/engine/openswmm_links.h 698 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_pump_init_state include/openswmm/engine/openswmm_links.h 716 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_pump_shutoff_depth include/openswmm/engine/openswmm_links.h 482 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_pump_startup_depth include/openswmm/engine/openswmm_links.h 470 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_quality include/openswmm/engine/openswmm_pollutants.h 319 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_link_set_roughness include/openswmm/engine/openswmm_links.h 242 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_link_set_seep_rate include/openswmm/engine/openswmm_links.h 843 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_tag include/openswmm/engine/openswmm_links.h 1229 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_target_setting include/openswmm/engine/openswmm_links.h 666 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_weir_type include/openswmm/engine/openswmm_links.h 385 pyx_use python/openswmm/engine/_links.pyx +swmm_link_set_xsect include/openswmm/engine/openswmm_links.h 523 pyx_use python/openswmm/engine/_links.pyx;python/openswmm/engine/_model.pyx +swmm_links_restore_authored_orientation include/openswmm/engine/openswmm_links.h 220 gap +swmm_model_write include/openswmm/engine/openswmm_model.h 109 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_model_write_compat include/openswmm/engine/openswmm_model.h 111 gap +swmm_model_write_with_plugin include/openswmm/engine/openswmm_model.h 190 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_node_add include/openswmm/engine/openswmm_nodes.h 105 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_analyze_impact include/openswmm/engine/openswmm_edit.h 134 pyx_use python/openswmm/engine/_edit.pyx +swmm_node_convert include/openswmm/engine/openswmm_edit.h 447 pyx_use python/openswmm/engine/_edit.pyx +swmm_node_count include/openswmm/engine/openswmm_nodes.h 64 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_heat.pyx;python/openswmm/engine/_inflows.pyx;python/openswmm/engine/_initial_quality.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_nodes.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_quality.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_statistics.pyx;python/openswmm/engine/_subcatchments.pyx;python/openswmm/engine/_water_age.pyx +swmm_node_delete include/openswmm/engine/openswmm_edit.h 225 pyx_use python/openswmm/engine/_edit.pyx +swmm_node_delete_many include/openswmm/engine/openswmm_edit.h 282 gap +swmm_node_get_crown_elev include/openswmm/engine/openswmm_nodes.h 831 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_degree include/openswmm/engine/openswmm_nodes.h 867 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_depth include/openswmm/engine/openswmm_nodes.h 348 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_depth_from_volume include/openswmm/engine/openswmm_nodes.h 1095 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_depths_bulk include/openswmm/engine/openswmm_nodes.h 920 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_divider_type include/openswmm/engine/openswmm_nodes.h 791 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_exfil_params include/openswmm/engine/openswmm_nodes.h 642 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_full_volume include/openswmm/engine/openswmm_nodes.h 840 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_head include/openswmm/engine/openswmm_nodes.h 366 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_heads_bulk include/openswmm/engine/openswmm_nodes.h 929 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_ids_bulk include/openswmm/engine/openswmm_nodes.h 1075 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_inflow include/openswmm/engine/openswmm_nodes.h 411 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_inflows_bulk include/openswmm/engine/openswmm_nodes.h 938 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_initial_depth include/openswmm/engine/openswmm_nodes.h 822 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_invert_elev include/openswmm/engine/openswmm_nodes.h 312 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_lateral_inflow include/openswmm/engine/openswmm_nodes.h 389 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_lateral_inflows_bulk include/openswmm/engine/openswmm_nodes.h 1034 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_losses include/openswmm/engine/openswmm_nodes.h 849 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_losses_bulk include/openswmm/engine/openswmm_nodes.h 1020 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_max_depth include/openswmm/engine/openswmm_nodes.h 321 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_flap_gate include/openswmm/engine/openswmm_nodes.h 754 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_param include/openswmm/engine/openswmm_nodes.h 703 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_route_to include/openswmm/engine/openswmm_nodes.h 1088 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_tidal include/openswmm/engine/openswmm_nodes.h 719 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_timeseries include/openswmm/engine/openswmm_nodes.h 733 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outfall_type include/openswmm/engine/openswmm_nodes.h 667 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outflow include/openswmm/engine/openswmm_nodes.h 858 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_outflows_bulk include/openswmm/engine/openswmm_nodes.h 1007 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_overflow include/openswmm/engine/openswmm_nodes.h 402 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_overflows_bulk include/openswmm/engine/openswmm_nodes.h 947 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_ponded_area include/openswmm/engine/openswmm_nodes.h 813 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_quality include/openswmm/engine/openswmm_nodes.h 473 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_quality_bulk include/openswmm/engine/openswmm_nodes.h 975 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_rim_depth include/openswmm/engine/openswmm_nodes.h 335 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_stat_max_depth include/openswmm/engine/openswmm_nodes.h 880 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_stat_max_overflow include/openswmm/engine/openswmm_nodes.h 889 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_stat_time_flooded include/openswmm/engine/openswmm_nodes.h 907 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_stat_vol_flooded include/openswmm/engine/openswmm_nodes.h 898 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_storage_curve include/openswmm/engine/openswmm_nodes.h 496 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_storage_functional include/openswmm/engine/openswmm_nodes.h 522 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_storage_geometry include/openswmm/engine/openswmm_nodes.h 597 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_storage_seep_rate include/openswmm/engine/openswmm_nodes.h 616 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_storage_shape include/openswmm/engine/openswmm_nodes.h 564 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_surcharge_depth include/openswmm/engine/openswmm_nodes.h 804 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_tag include/openswmm/engine/openswmm_nodes.h 1110 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_type include/openswmm/engine/openswmm_nodes.h 215 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_volume include/openswmm/engine/openswmm_nodes.h 375 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_get_volumes_bulk include/openswmm/engine/openswmm_nodes.h 994 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_id include/openswmm/engine/openswmm_nodes.h 80 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_index include/openswmm/engine/openswmm_nodes.h 72 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_heat.pyx;python/openswmm/engine/_inflows.pyx;python/openswmm/engine/_initial_quality.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_nodes.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_quality.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_subcatchments.pyx;python/openswmm/engine/_water_age.pyx +swmm_node_inlet_eligible include/openswmm/engine/openswmm_nodes.h 293 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_is_inlet include/openswmm/engine/openswmm_nodes.h 285 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_is_virtual include/openswmm/engine/openswmm_nodes.h 230 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_pop_last include/openswmm/engine/openswmm_nodes.h 128 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_rename include/openswmm/engine/openswmm_nodes.h 1101 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_depth include/openswmm/engine/openswmm_nodes.h 357 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_depths_bulk include/openswmm/engine/openswmm_nodes.h 956 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_divider_type include/openswmm/engine/openswmm_nodes.h 782 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_exfil_params include/openswmm/engine/openswmm_nodes.h 631 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_head_boundary include/openswmm/engine/openswmm_nodes.h 459 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_initial_depth include/openswmm/engine/openswmm_nodes.h 181 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_inlet include/openswmm/engine/openswmm_nodes.h 303 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_set_invert_elev include/openswmm/engine/openswmm_nodes.h 141 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_set_lat_inflows_bulk include/openswmm/engine/openswmm_nodes.h 965 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_lateral_inflow include/openswmm/engine/openswmm_nodes.h 429 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_max_depth include/openswmm/engine/openswmm_nodes.h 150 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_flap_gate include/openswmm/engine/openswmm_nodes.h 745 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_route_to include/openswmm/engine/openswmm_nodes.h 1085 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_stage include/openswmm/engine/openswmm_nodes.h 676 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_tidal include/openswmm/engine/openswmm_nodes.h 685 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_timeseries include/openswmm/engine/openswmm_nodes.h 694 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_outfall_type include/openswmm/engine/openswmm_nodes.h 658 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_pond_area include/openswmm/engine/openswmm_nodes.h 172 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_quality include/openswmm/engine/openswmm_pollutants.h 309 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_node_set_quality_mass_flux include/openswmm/engine/openswmm_nodes.h 445 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_rim_depth include/openswmm/engine/openswmm_nodes.h 202 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_storage_curve include/openswmm/engine/openswmm_nodes.h 487 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_storage_functional include/openswmm/engine/openswmm_nodes.h 511 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_storage_geometry include/openswmm/engine/openswmm_nodes.h 585 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_storage_seep_rate include/openswmm/engine/openswmm_nodes.h 607 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_storage_shape include/openswmm/engine/openswmm_nodes.h 555 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_surcharge_depth include/openswmm/engine/openswmm_nodes.h 159 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_tag include/openswmm/engine/openswmm_nodes.h 1116 pyx_use python/openswmm/engine/_nodes.pyx +swmm_node_set_virtual include/openswmm/engine/openswmm_nodes.h 252 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_nodes.pyx +swmm_node_virtual_eligible include/openswmm/engine/openswmm_nodes.h 271 pyx_use python/openswmm/engine/_nodes.pyx +swmm_options_get include/openswmm/engine/openswmm_model.h 501 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_get_end_date include/openswmm/engine/openswmm_model.h 591 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_get_ext include/openswmm/engine/openswmm_model.h 531 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_get_report_start include/openswmm/engine/openswmm_model.h 607 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_get_start_date include/openswmm/engine/openswmm_model.h 575 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_set include/openswmm/engine/openswmm_model.h 516 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_set_end_date include/openswmm/engine/openswmm_model.h 599 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_set_ext include/openswmm/engine/openswmm_model.h 546 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_set_report_start include/openswmm/engine/openswmm_model.h 615 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_options_set_start_date include/openswmm/engine/openswmm_model.h 583 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_output_close include/openswmm/engine/openswmm_output.h 203 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_error_code include/openswmm/engine/openswmm_output.h 618 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_flow_units include/openswmm/engine/openswmm_output.h 222 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_link_attribute include/openswmm/engine/openswmm_output.h 510 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_link_count include/openswmm/engine/openswmm_output.h 243 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_link_id include/openswmm/engine/openswmm_output.h 310 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_link_result include/openswmm/engine/openswmm_output.h 371 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_link_series include/openswmm/engine/openswmm_output.h 441 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_attribute include/openswmm/engine/openswmm_output.h 494 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_count include/openswmm/engine/openswmm_output.h 236 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_id include/openswmm/engine/openswmm_output.h 301 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_result include/openswmm/engine/openswmm_output.h 357 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_series include/openswmm/engine/openswmm_output.h 423 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_stat_max_depth include/openswmm/engine/openswmm_output.h 569 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_stat_max_overflow include/openswmm/engine/openswmm_output.h 580 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_stat_time_flooded include/openswmm/engine/openswmm_output.h 605 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_node_stat_vol_flooded include/openswmm/engine/openswmm_output.h 592 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_period_count include/openswmm/engine/openswmm_output.h 257 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_period_time include/openswmm/engine/openswmm_output.h 533 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_pollut_count include/openswmm/engine/openswmm_output.h 250 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_pollut_id include/openswmm/engine/openswmm_output.h 327 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_report_step include/openswmm/engine/openswmm_output.h 280 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_start_date include/openswmm/engine/openswmm_output.h 272 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_subcatch_attribute include/openswmm/engine/openswmm_output.h 478 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_subcatch_count include/openswmm/engine/openswmm_output.h 229 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_subcatch_id include/openswmm/engine/openswmm_output.h 292 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_subcatch_result include/openswmm/engine/openswmm_output.h 343 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_subcatch_series include/openswmm/engine/openswmm_output.h 405 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_system_result include/openswmm/engine/openswmm_output.h 385 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_system_series include/openswmm/engine/openswmm_output.h 458 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_get_version include/openswmm/engine/openswmm_output.h 214 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_is_live include/openswmm/engine/openswmm_output.h 196 gap +swmm_output_open include/openswmm/engine/openswmm_output.h 160 pyx_use python/openswmm/engine/_output_reader.pyx +swmm_output_open_live include/openswmm/engine/openswmm_output.h 176 gap +swmm_output_refresh include/openswmm/engine/openswmm_output.h 190 gap +swmm_pattern_add include/openswmm/engine/openswmm_tables.h 235 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_analyze_impact include/openswmm/engine/openswmm_edit.h 162 pyx_use python/openswmm/engine/_edit.pyx +swmm_pattern_count include/openswmm/engine/openswmm_tables.h 252 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_delete include/openswmm/engine/openswmm_edit.h 340 pyx_use python/openswmm/engine/_edit.pyx +swmm_pattern_get_factor include/openswmm/engine/openswmm_tables.h 301 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_get_factor_count include/openswmm/engine/openswmm_tables.h 291 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_get_type include/openswmm/engine/openswmm_tables.h 282 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_id include/openswmm/engine/openswmm_tables.h 268 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_index include/openswmm/engine/openswmm_tables.h 260 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_tables.pyx +swmm_pattern_remove include/openswmm/engine/openswmm_tables.h 322 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_rename include/openswmm/engine/openswmm_tables.h 335 pyx_use python/openswmm/engine/_tables.pyx +swmm_pattern_set_factors include/openswmm/engine/openswmm_tables.h 245 pyx_use python/openswmm/engine/_tables.pyx +swmm_plugin_get include/openswmm/engine/openswmm_model.h 233 pyx_use python/openswmm/engine/_model.pyx +swmm_plugin_remove include/openswmm/engine/openswmm_model.h 270 pyx_use python/openswmm/engine/_model.pyx +swmm_plugin_set include/openswmm/engine/openswmm_model.h 256 pyx_use python/openswmm/engine/_model.pyx +swmm_plugins_count include/openswmm/engine/openswmm_model.h 213 pyx_use python/openswmm/engine/_model.pyx +swmm_pollutant_add include/openswmm/engine/openswmm_pollutants.h 79 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_analyze_impact include/openswmm/engine/openswmm_edit.h 158 pyx_use python/openswmm/engine/_edit.pyx +swmm_pollutant_count include/openswmm/engine/openswmm_pollutants.h 50 pyx_use python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_massbalance.pyx;python/openswmm/engine/_nodes.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_quality.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_pollutant_delete include/openswmm/engine/openswmm_edit.h 329 pyx_use python/openswmm/engine/_edit.pyx +swmm_pollutant_get_co_pollutant include/openswmm/engine/openswmm_pollutants.h 277 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_dwf_conc include/openswmm/engine/openswmm_pollutants.h 239 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_gw_conc include/openswmm/engine/openswmm_pollutants.h 192 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_init_conc include/openswmm/engine/openswmm_pollutants.h 201 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_kdecay include/openswmm/engine/openswmm_pollutants.h 174 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_mwt include/openswmm/engine/openswmm_pollutants.h 257 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_rain_conc include/openswmm/engine/openswmm_pollutants.h 183 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_rdii_conc include/openswmm/engine/openswmm_pollutants.h 219 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_snow_only include/openswmm/engine/openswmm_pollutants.h 295 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_get_units include/openswmm/engine/openswmm_pollutants.h 161 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_id include/openswmm/engine/openswmm_pollutants.h 66 pyx_use python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_pollutant_index include/openswmm/engine/openswmm_pollutants.h 58 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_links.pyx;python/openswmm/engine/_massbalance.pyx;python/openswmm/engine/_nodes.pyx;python/openswmm/engine/_pollutants.pyx;python/openswmm/engine/_quality.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_pollutant_rename include/openswmm/engine/openswmm_pollutants.h 94 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_co_pollutant include/openswmm/engine/openswmm_pollutants.h 267 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_dwf_conc include/openswmm/engine/openswmm_pollutants.h 230 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_gw_conc include/openswmm/engine/openswmm_pollutants.h 143 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_init_conc include/openswmm/engine/openswmm_pollutants.h 152 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_kdecay include/openswmm/engine/openswmm_pollutants.h 125 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_mwt include/openswmm/engine/openswmm_pollutants.h 248 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_rain_conc include/openswmm/engine/openswmm_pollutants.h 134 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_rdii_conc include/openswmm/engine/openswmm_pollutants.h 210 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_snow_only include/openswmm/engine/openswmm_pollutants.h 286 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_pollutant_set_units include/openswmm/engine/openswmm_pollutants.h 116 pyx_use python/openswmm/engine/_pollutants.pyx +swmm_process_component_count include/openswmm/engine/openswmm_process_components.h 46 pyx_use python/openswmm/engine/_process_components.pyx +swmm_process_component_find include/openswmm/engine/openswmm_process_components.h 60 pyx_use python/openswmm/engine/_process_components.pyx +swmm_process_component_get include/openswmm/engine/openswmm_process_components.h 55 pyx_use python/openswmm/engine/_process_components.pyx +swmm_process_component_known_count include/openswmm/engine/openswmm_process_components.h 83 gap +swmm_process_component_known_get include/openswmm/engine/openswmm_process_components.h 93 gap +swmm_process_component_register include/openswmm/engine/openswmm_process_components.h 67 pyx_use python/openswmm/engine/_process_components.pyx +swmm_process_component_remove include/openswmm/engine/openswmm_process_components.h 71 pyx_use python/openswmm/engine/_process_components.pyx +swmm_rdii_add include/openswmm/engine/openswmm_inflows.h 216 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_count include/openswmm/engine/openswmm_inflows.h 610 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_decay_add include/openswmm/engine/openswmm_inflows.h 549 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_decay_count include/openswmm/engine/openswmm_inflows.h 585 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_decay_get include/openswmm/engine/openswmm_inflows.h 574 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_decay_remove include/openswmm/engine/openswmm_inflows.h 514 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_decay_set include/openswmm/engine/openswmm_inflows.h 501 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_get include/openswmm/engine/openswmm_inflows.h 229 pyx_use python/openswmm/engine/_inflows.pyx +swmm_rdii_remove include/openswmm/engine/openswmm_inflows.h 239 pyx_use python/openswmm/engine/_inflows.pyx +swmm_reaction_coeff_add include/openswmm/engine/openswmm_reactions.h 137 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_coeff_count include/openswmm/engine/openswmm_reactions.h 92 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_coeff_get include/openswmm/engine/openswmm_reactions.h 95 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_coeff_remove include/openswmm/engine/openswmm_reactions.h 145 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_coeff_set_value include/openswmm/engine/openswmm_reactions.h 141 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_expr_get include/openswmm/engine/openswmm_reactions.h 109 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_expr_set include/openswmm/engine/openswmm_reactions.h 162 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_function_count include/openswmm/engine/openswmm_reactions.h 236 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_function_get include/openswmm/engine/openswmm_reactions.h 239 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_hydvar_count include/openswmm/engine/openswmm_reactions.h 229 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_hydvar_get include/openswmm/engine/openswmm_reactions.h 232 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_elem_count include/openswmm/engine/openswmm_reactions.h 175 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_elem_get include/openswmm/engine/openswmm_reactions.h 176 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_elem_remove include/openswmm/engine/openswmm_reactions.h 182 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_elem_set include/openswmm/engine/openswmm_reactions.h 180 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_global_get include/openswmm/engine/openswmm_reactions.h 171 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_init_global_set include/openswmm/engine/openswmm_reactions.h 173 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_option_get include/openswmm/engine/openswmm_reactions.h 117 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_option_set include/openswmm/engine/openswmm_reactions.h 166 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_species_add include/openswmm/engine/openswmm_reactions.h 129 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_species_count include/openswmm/engine/openswmm_reactions.h 84 pyx_use python/openswmm/engine/_quality.pyx;python/openswmm/engine/_reactions.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_reaction_species_get include/openswmm/engine/openswmm_reactions.h 87 pyx_use python/openswmm/engine/_quality.pyx;python/openswmm/engine/_reactions.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_reaction_species_remove include/openswmm/engine/openswmm_reactions.h 134 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_term_add include/openswmm/engine/openswmm_reactions.h 148 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_term_count include/openswmm/engine/openswmm_reactions.h 99 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_term_get include/openswmm/engine/openswmm_reactions.h 102 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_term_remove include/openswmm/engine/openswmm_reactions.h 156 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_term_set_expr include/openswmm/engine/openswmm_reactions.h 152 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reaction_validate_expression include/openswmm/engine/openswmm_reactions.h 78 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reactions_apply_text include/openswmm/engine/openswmm_reactions.h 215 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reactions_check_text include/openswmm/engine/openswmm_reactions.h 205 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reactions_save include/openswmm/engine/openswmm_reactions.h 222 pyx_use python/openswmm/engine/_reactions.pyx +swmm_reactions_serialize include/openswmm/engine/openswmm_reactions.h 196 pyx_use python/openswmm/engine/_reactions.pyx +swmm_runoff_iface_close include/openswmm/engine/openswmm_engine.h 562 pyx_use python/openswmm/engine/_solver.pyx +swmm_runoff_iface_open_read include/openswmm/engine/openswmm_engine.h 525 pyx_use python/openswmm/engine/_solver.pyx +swmm_runoff_iface_open_write include/openswmm/engine/openswmm_engine.h 514 pyx_use python/openswmm/engine/_solver.pyx +swmm_runoff_iface_read_step include/openswmm/engine/openswmm_engine.h 554 pyx_use python/openswmm/engine/_solver.pyx +swmm_runoff_iface_save_step include/openswmm/engine/openswmm_engine.h 540 pyx_use python/openswmm/engine/_solver.pyx +swmm_set_progress_callback include/openswmm/engine/openswmm_engine.h 287 pyx_use python/openswmm/engine/_solver.pyx +swmm_set_steady_state_skip include/openswmm/engine/openswmm_engine.h 481 pyx_use python/openswmm/engine/_solver.pyx +swmm_set_step_begin_callback include/openswmm/engine/openswmm_engine.h 291 pyx_use python/openswmm/engine/_solver.pyx +swmm_set_step_end_callback include/openswmm/engine/openswmm_engine.h 293 pyx_use python/openswmm/engine/_solver.pyx +swmm_set_warning_callback include/openswmm/engine/openswmm_engine.h 289 pyx_use python/openswmm/engine/_solver.pyx +swmm_snowpack_add include/openswmm/engine/openswmm_subcatchments.h 1003 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_analyze_impact include/openswmm/engine/openswmm_edit.h 170 pyx_use python/openswmm/engine/_edit.pyx +swmm_snowpack_count include/openswmm/engine/openswmm_subcatchments.h 972 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_delete include/openswmm/engine/openswmm_edit.h 354 pyx_use python/openswmm/engine/_edit.pyx +swmm_snowpack_get_impervious include/openswmm/engine/openswmm_subcatchments.h 1062 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_get_pervious include/openswmm/engine/openswmm_subcatchments.h 1071 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_get_plowable include/openswmm/engine/openswmm_subcatchments.h 1053 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_get_removal include/openswmm/engine/openswmm_subcatchments.h 1090 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_get_removal_subcatch include/openswmm/engine/openswmm_subcatchments.h 1097 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_id include/openswmm/engine/openswmm_subcatchments.h 988 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_index include/openswmm/engine/openswmm_subcatchments.h 980 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_rename include/openswmm/engine/openswmm_subcatchments.h 1022 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_set_impervious include/openswmm/engine/openswmm_subcatchments.h 1058 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_set_pervious include/openswmm/engine/openswmm_subcatchments.h 1067 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_set_plowable include/openswmm/engine/openswmm_subcatchments.h 1049 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_set_removal include/openswmm/engine/openswmm_subcatchments.h 1086 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_snowpack_set_removal_subcatch include/openswmm/engine/openswmm_subcatchments.h 1095 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_spatial_get_crs include/openswmm/engine/openswmm_spatial.h 65 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_gage_coord include/openswmm/engine/openswmm_spatial.h 266 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_link_coord include/openswmm/engine/openswmm_spatial.h 133 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_link_vertex_count include/openswmm/engine/openswmm_spatial.h 166 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_link_vertices include/openswmm/engine/openswmm_spatial.h 183 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_node_coord include/openswmm/engine/openswmm_spatial.h 89 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_node_coords_bulk include/openswmm/engine/openswmm_spatial.h 99 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_subcatch_coord include/openswmm/engine/openswmm_spatial.h 207 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_subcatch_polygon include/openswmm/engine/openswmm_spatial.h 242 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_get_subcatch_polygon_count include/openswmm/engine/openswmm_spatial.h 231 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_crs include/openswmm/engine/openswmm_spatial.h 56 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_gage_coord include/openswmm/engine/openswmm_spatial.h 256 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_link_coord include/openswmm/engine/openswmm_spatial.h 123 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_link_vertices include/openswmm/engine/openswmm_spatial.h 152 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_node_coord include/openswmm/engine/openswmm_spatial.h 79 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_node_coords_bulk include/openswmm/engine/openswmm_spatial.h 109 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_subcatch_coord include/openswmm/engine/openswmm_spatial.h 197 pyx_use python/openswmm/engine/_spatial.pyx +swmm_spatial_set_subcatch_polygon include/openswmm/engine/openswmm_spatial.h 222 pyx_use python/openswmm/engine/_spatial.pyx +swmm_stat_link_max_filling include/openswmm/engine/openswmm_statistics.h 68 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_max_filling_bulk include/openswmm/engine/openswmm_statistics.h 159 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_max_flow include/openswmm/engine/openswmm_statistics.h 62 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_max_flow_bulk include/openswmm/engine/openswmm_statistics.h 97 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_max_velocity include/openswmm/engine/openswmm_statistics.h 65 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_max_velocity_bulk include/openswmm/engine/openswmm_statistics.h 151 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_surcharge_time include/openswmm/engine/openswmm_statistics.h 74 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_surcharge_time_bulk include/openswmm/engine/openswmm_statistics.h 175 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_vol_flow include/openswmm/engine/openswmm_statistics.h 71 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_link_vol_flow_bulk include/openswmm/engine/openswmm_statistics.h 167 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_max_depth include/openswmm/engine/openswmm_statistics.h 46 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_max_depth_bulk include/openswmm/engine/openswmm_statistics.h 94 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_max_overflow include/openswmm/engine/openswmm_statistics.h 49 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_max_overflow_bulk include/openswmm/engine/openswmm_statistics.h 115 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_time_flooded include/openswmm/engine/openswmm_statistics.h 55 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_time_flooded_bulk include/openswmm/engine/openswmm_statistics.h 129 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_vol_flooded include/openswmm/engine/openswmm_statistics.h 52 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_node_vol_flooded_bulk include/openswmm/engine/openswmm_statistics.h 122 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_subcatch_max_runoff include/openswmm/engine/openswmm_statistics.h 87 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_subcatch_max_runoff_bulk include/openswmm/engine/openswmm_statistics.h 136 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_subcatch_precip include/openswmm/engine/openswmm_statistics.h 81 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_subcatch_runoff_vol include/openswmm/engine/openswmm_statistics.h 84 pyx_use python/openswmm/engine/_statistics.pyx +swmm_stat_subcatch_runoff_vol_bulk include/openswmm/engine/openswmm_statistics.h 100 pyx_use python/openswmm/engine/_statistics.pyx +swmm_street_add include/openswmm/engine/openswmm_infrastructure.h 304 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_street_analyze_impact include/openswmm/engine/openswmm_edit.h 178 pyx_use python/openswmm/engine/_edit.pyx +swmm_street_count include/openswmm/engine/openswmm_infrastructure.h 352 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_street_delete include/openswmm/engine/openswmm_edit.h 368 pyx_use python/openswmm/engine/_edit.pyx +swmm_street_get_params include/openswmm/engine/openswmm_infrastructure.h 391 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_street_id include/openswmm/engine/openswmm_infrastructure.h 368 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_street_index include/openswmm/engine/openswmm_infrastructure.h 360 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_infrastructure.pyx +swmm_street_rename include/openswmm/engine/openswmm_infrastructure.h 323 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_street_set_params include/openswmm/engine/openswmm_infrastructure.h 342 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_subcatch_add include/openswmm/engine/openswmm_subcatchments.h 85 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_analyze_impact include/openswmm/engine/openswmm_edit.h 142 pyx_use python/openswmm/engine/_edit.pyx +swmm_subcatch_count include/openswmm/engine/openswmm_subcatchments.h 50 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_infrastructure.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_statistics.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_delete include/openswmm/engine/openswmm_edit.h 245 pyx_use python/openswmm/engine/_edit.pyx +swmm_subcatch_delete_many include/openswmm/engine/openswmm_edit.h 292 gap +swmm_subcatch_get_aquifer include/openswmm/engine/openswmm_subcatchments.h 583 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_area include/openswmm/engine/openswmm_subcatchments.h 244 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_coverage include/openswmm/engine/openswmm_subcatchments.h 475 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_coverages include/openswmm/engine/openswmm_subcatchments.h 490 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_ds_imperv include/openswmm/engine/openswmm_subcatchments.h 317 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_ds_perv include/openswmm/engine/openswmm_subcatchments.h 326 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_evap include/openswmm/engine/openswmm_subcatchments.h 568 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_evap_bulk include/openswmm/engine/openswmm_subcatchments.h 762 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_gage include/openswmm/engine/openswmm_subcatchments.h 335 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_groundwater include/openswmm/engine/openswmm_subcatchments.h 541 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_gw_node include/openswmm/engine/openswmm_subcatchments.h 589 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_gw_params include/openswmm/engine/openswmm_subcatchments.h 607 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_gw_state include/openswmm/engine/openswmm_subcatchments.h 643 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_gwf_expression include/openswmm/engine/openswmm_subcatchments.h 1187 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_ids_bulk include/openswmm/engine/openswmm_subcatchments.h 796 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_imperv_pct include/openswmm/engine/openswmm_subcatchments.h 253 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil include/openswmm/engine/openswmm_subcatchments.h 689 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil_bulk include/openswmm/engine/openswmm_subcatchments.h 770 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil_curve_number include/openswmm/engine/openswmm_subcatchments.h 413 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil_green_ampt include/openswmm/engine/openswmm_subcatchments.h 400 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil_horton include/openswmm/engine/openswmm_subcatchments.h 387 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_infil_model include/openswmm/engine/openswmm_subcatchments.h 375 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_initial_loading include/openswmm/engine/openswmm_subcatchments.h 519 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_n_imperv include/openswmm/engine/openswmm_subcatchments.h 299 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_n_perv include/openswmm/engine/openswmm_subcatchments.h 308 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_outlet include/openswmm/engine/openswmm_subcatchments.h 272 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_outlet_subcatch include/openswmm/engine/openswmm_subcatchments.h 358 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_ponded_quality include/openswmm/engine/openswmm_subcatchments.h 806 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_quality include/openswmm/engine/openswmm_subcatchments.h 714 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_quality_bulk include/openswmm/engine/openswmm_subcatchments.h 738 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_rain_scale_factor include/openswmm/engine/openswmm_subcatchments.h 1130 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_rainfall include/openswmm/engine/openswmm_subcatchments.h 550 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_rainfall_bulk include/openswmm/engine/openswmm_subcatchments.h 754 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_runoff include/openswmm/engine/openswmm_subcatchments.h 532 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_runoff_bulk include/openswmm/engine/openswmm_subcatchments.h 728 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_slope include/openswmm/engine/openswmm_subcatchments.h 290 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_snow_depth include/openswmm/engine/openswmm_subcatchments.h 559 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_snow_depth_bulk include/openswmm/engine/openswmm_subcatchments.h 780 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_snow_scale_factor include/openswmm/engine/openswmm_subcatchments.h 1153 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_snow_state include/openswmm/engine/openswmm_subcatchments.h 678 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_stat_max_runoff include/openswmm/engine/openswmm_subcatchments.h 445 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_stat_precip include/openswmm/engine/openswmm_subcatchments.h 427 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_stat_runoff_vol include/openswmm/engine/openswmm_subcatchments.h 436 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_tag include/openswmm/engine/openswmm_subcatchments.h 1104 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_width include/openswmm/engine/openswmm_subcatchments.h 281 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_get_zero_imperv_pct include/openswmm/engine/openswmm_subcatchments.h 263 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_id include/openswmm/engine/openswmm_subcatchments.h 66 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_index include/openswmm/engine/openswmm_subcatchments.h 58 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_forcing.pyx;python/openswmm/engine/_infrastructure.pyx;python/openswmm/engine/_spatial.pyx;python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_rename include/openswmm/engine/openswmm_subcatchments.h 816 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_aquifer include/openswmm/engine/openswmm_subcatchments.h 580 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_area include/openswmm/engine/openswmm_subcatchments.h 107 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_coverage include/openswmm/engine/openswmm_subcatchments.h 465 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_ds_imperv include/openswmm/engine/openswmm_subcatchments.h 172 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_ds_perv include/openswmm/engine/openswmm_subcatchments.h 181 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_gage include/openswmm/engine/openswmm_subcatchments.h 190 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_gw_node include/openswmm/engine/openswmm_subcatchments.h 586 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_gw_params include/openswmm/engine/openswmm_subcatchments.h 601 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_gw_state include/openswmm/engine/openswmm_subcatchments.h 631 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_gwf_expression include/openswmm/engine/openswmm_subcatchments.h 1207 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_imperv_pct include/openswmm/engine/openswmm_subcatchments.h 134 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_infil_curve_number include/openswmm/engine/openswmm_subcatchments.h 215 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_infil_green_ampt include/openswmm/engine/openswmm_subcatchments.h 200 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_infil_horton include/openswmm/engine/openswmm_subcatchments.h 195 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_infil_model include/openswmm/engine/openswmm_subcatchments.h 231 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_initial_loading include/openswmm/engine/openswmm_subcatchments.h 509 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_n_imperv include/openswmm/engine/openswmm_subcatchments.h 154 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_n_perv include/openswmm/engine/openswmm_subcatchments.h 163 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_outlet include/openswmm/engine/openswmm_subcatchments.h 98 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_outlet_subcatch include/openswmm/engine/openswmm_subcatchments.h 349 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_ponded_quality include/openswmm/engine/openswmm_subcatchments.h 810 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_rain_scale_factor include/openswmm/engine/openswmm_subcatchments.h 1126 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_rainfall include/openswmm/engine/openswmm_subcatchments.h 700 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_slope include/openswmm/engine/openswmm_subcatchments.h 125 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_snow_scale_factor include/openswmm/engine/openswmm_subcatchments.h 1149 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_snow_state include/openswmm/engine/openswmm_subcatchments.h 662 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_tag include/openswmm/engine/openswmm_subcatchments.h 1108 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_width include/openswmm/engine/openswmm_subcatchments.h 116 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_subcatch_set_zero_imperv_pct include/openswmm/engine/openswmm_subcatchments.h 145 pyx_use python/openswmm/engine/_subcatchments.pyx +swmm_table_add_point include/openswmm/engine/openswmm_tables.h 132 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_analyze_impact include/openswmm/engine/openswmm_edit.h 150 pyx_use python/openswmm/engine/_edit.pyx +swmm_table_clear include/openswmm/engine/openswmm_tables.h 160 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_count include/openswmm/engine/openswmm_tables.h 50 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_tables.pyx +swmm_table_delete include/openswmm/engine/openswmm_edit.h 308 pyx_use python/openswmm/engine/_edit.pyx +swmm_table_get_point include/openswmm/engine/openswmm_tables.h 152 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_get_point_count include/openswmm/engine/openswmm_tables.h 141 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_get_type include/openswmm/engine/openswmm_tables.h 89 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_id include/openswmm/engine/openswmm_tables.h 66 pyx_use python/openswmm/engine/_tables.pyx +swmm_table_index include/openswmm/engine/openswmm_tables.h 58 pyx_use python/openswmm/engine/_edit.pyx;python/openswmm/engine/_tables.pyx +swmm_table_lookup include/openswmm/engine/openswmm_tables.h 219 pyx_use python/openswmm/engine/_tables.pyx +swmm_timeseries_add include/openswmm/engine/openswmm_tables.h 101 pyx_use python/openswmm/engine/_tables.pyx +swmm_timeseries_get_relative_info include/openswmm/engine/openswmm_tables.h 180 gap +swmm_timeseries_set_relative_info include/openswmm/engine/openswmm_tables.h 200 gap +swmm_title_add_line include/openswmm/engine/openswmm_model.h 460 pyx_use python/openswmm/engine/_model.pyx +swmm_title_clear include/openswmm/engine/openswmm_model.h 480 pyx_use python/openswmm/engine/_model.pyx +swmm_title_get_count include/openswmm/engine/openswmm_model.h 435 pyx_use python/openswmm/engine/_model.pyx +swmm_title_get_line include/openswmm/engine/openswmm_model.h 446 pyx_use python/openswmm/engine/_model.pyx +swmm_title_set include/openswmm/engine/openswmm_model.h 472 pyx_use python/openswmm/engine/_model.pyx +swmm_transect_add include/openswmm/engine/openswmm_infrastructure.h 51 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_add_station include/openswmm/engine/openswmm_infrastructure.h 76 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_analyze_impact include/openswmm/engine/openswmm_edit.h 154 pyx_use python/openswmm/engine/_edit.pyx +swmm_transect_clear_stations include/openswmm/engine/openswmm_infrastructure.h 265 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_count include/openswmm/engine/openswmm_infrastructure.h 83 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_delete include/openswmm/engine/openswmm_edit.h 317 pyx_use python/openswmm/engine/_edit.pyx +swmm_transect_get_bank_stations include/openswmm/engine/openswmm_infrastructure.h 144 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_comments include/openswmm/engine/openswmm_infrastructure.h 233 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_encroachment_stations include/openswmm/engine/openswmm_infrastructure.h 174 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_modifiers include/openswmm/engine/openswmm_infrastructure.h 208 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_roughness include/openswmm/engine/openswmm_infrastructure.h 118 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_station include/openswmm/engine/openswmm_infrastructure.h 252 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_get_station_count include/openswmm/engine/openswmm_infrastructure.h 241 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_id include/openswmm/engine/openswmm_infrastructure.h 99 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_index include/openswmm/engine/openswmm_infrastructure.h 91 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_remove include/openswmm/engine/openswmm_infrastructure.h 292 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_rename include/openswmm/engine/openswmm_infrastructure.h 278 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_set_bank_stations include/openswmm/engine/openswmm_infrastructure.h 133 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_set_comments include/openswmm/engine/openswmm_infrastructure.h 218 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_set_encroachment_stations include/openswmm/engine/openswmm_infrastructure.h 163 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_set_modifiers include/openswmm/engine/openswmm_infrastructure.h 196 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transect_set_roughness include/openswmm/engine/openswmm_infrastructure.h 62 pyx_use python/openswmm/engine/_infrastructure.pyx +swmm_transport_boundary_count include/openswmm/engine/openswmm_transport.h 101 gap +swmm_transport_class_name include/openswmm/engine/openswmm_engine.h 405 gap +swmm_transport_conduit_disp_count include/openswmm/engine/openswmm_transport.h 91 gap +swmm_transport_domain_name include/openswmm/engine/openswmm_engine.h 404 gap +swmm_transport_get_boundary include/openswmm/engine/openswmm_transport.h 114 gap +swmm_transport_get_conduit_disp include/openswmm/engine/openswmm_transport.h 95 gap +swmm_transport_get_configured include/openswmm/engine/openswmm_transport.h 59 gap +swmm_transport_get_dispersion_mode include/openswmm/engine/openswmm_transport.h 63 gap +swmm_transport_get_dispersion_value include/openswmm/engine/openswmm_transport.h 75 gap +swmm_transport_get_source include/openswmm/engine/openswmm_transport.h 129 gap +swmm_transport_get_target_dx include/openswmm/engine/openswmm_transport.h 83 gap +swmm_transport_set_dispersion_mode include/openswmm/engine/openswmm_transport.h 71 gap +swmm_transport_set_dispersion_value include/openswmm/engine/openswmm_transport.h 79 gap +swmm_transport_set_target_dx include/openswmm/engine/openswmm_transport.h 87 gap +swmm_transport_source_count include/openswmm/engine/openswmm_transport.h 121 gap +swmm_treatment_clear include/openswmm/engine/openswmm_quality.h 197 pyx_use python/openswmm/engine/_quality.pyx +swmm_treatment_get include/openswmm/engine/openswmm_quality.h 186 pyx_use python/openswmm/engine/_quality.pyx +swmm_treatment_set include/openswmm/engine/openswmm_quality.h 174 pyx_use python/openswmm/engine/_quality.pyx +swmm_treatment_validate_expression include/openswmm/engine/openswmm_quality.h 223 pyx_use python/openswmm/engine/_quality.pyx +swmm_userflag_def_count include/openswmm/engine/openswmm_model.h 679 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_def_get include/openswmm/engine/openswmm_model.h 692 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_define include/openswmm/engine/openswmm_model.h 712 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_get_bool include/openswmm/engine/openswmm_model.h 631 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_get_int include/openswmm/engine/openswmm_model.h 640 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_get_real include/openswmm/engine/openswmm_model.h 649 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_set_bool include/openswmm/engine/openswmm_model.h 652 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_set_int include/openswmm/engine/openswmm_model.h 655 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_set_real include/openswmm/engine/openswmm_model.h 658 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_undefine include/openswmm/engine/openswmm_model.h 725 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_value_clear include/openswmm/engine/openswmm_model.h 778 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_value_get include/openswmm/engine/openswmm_model.h 738 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_userflag_value_set include/openswmm/engine/openswmm_model.h 761 pyx_use python/openswmm/engine/_model.pyx;python/openswmm/engine/_solver.pyx +swmm_validate_model include/openswmm/engine/openswmm_model.h 78 pyx_use python/openswmm/engine/_model.pyx +swmm_virtual_junction_fuse include/openswmm/engine/openswmm_edit.h 525 pyx_use python/openswmm/engine/_edit.pyx +swmm_washoff_get include/openswmm/engine/openswmm_quality.h 158 pyx_use python/openswmm/engine/_quality.pyx +swmm_washoff_set include/openswmm/engine/openswmm_quality.h 141 pyx_use python/openswmm/engine/_quality.pyx +swmm_water_age_get_enabled include/openswmm/engine/openswmm_water_age.h 68 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_get_global_source include/openswmm/engine/openswmm_water_age.h 72 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_get_override include/openswmm/engine/openswmm_water_age.h 93 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_override_count include/openswmm/engine/openswmm_water_age.h 86 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_remove_override include/openswmm/engine/openswmm_water_age.h 108 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_save include/openswmm/engine/openswmm_water_age.h 117 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_set_global_source include/openswmm/engine/openswmm_water_age.h 81 pyx_use python/openswmm/engine/_water_age.pyx +swmm_water_age_set_override include/openswmm/engine/openswmm_water_age.h 103 pyx_use python/openswmm/engine/_water_age.pyx +swmm_xsect_area_of_depth include/openswmm/engine/openswmm_xsect.h 301 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_area_of_depth_array include/openswmm/engine/openswmm_xsect.h 440 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_area_of_sectfactor include/openswmm/engine/openswmm_xsect.h 374 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_area_of_sectfactor_array include/openswmm/engine/openswmm_xsect.h 464 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_create include/openswmm/engine/openswmm_xsect.h 121 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_create_custom include/openswmm/engine/openswmm_xsect.h 175 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_create_irregular include/openswmm/engine/openswmm_xsect.h 152 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_create_street include/openswmm/engine/openswmm_xsect.h 203 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_critical_depth include/openswmm/engine/openswmm_xsect.h 397 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_critical_depth_array include/openswmm/engine/openswmm_xsect.h 471 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_depth_of_area include/openswmm/engine/openswmm_xsect.h 337 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_depth_of_area_array include/openswmm/engine/openswmm_xsect.h 452 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_dsda include/openswmm/engine/openswmm_xsect.h 386 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_dsda_array include/openswmm/engine/openswmm_xsect.h 468 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_free include/openswmm/engine/openswmm_xsect.h 70 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_full_properties include/openswmm/engine/openswmm_xsect.h 415 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_get_shape include/openswmm/engine/openswmm_xsect.h 254 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_get_units include/openswmm/engine/openswmm_xsect.h 271 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_hydrad_of_area include/openswmm/engine/openswmm_xsect.h 349 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_hydrad_of_area_array include/openswmm/engine/openswmm_xsect.h 456 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_hydrad_of_depth include/openswmm/engine/openswmm_xsect.h 325 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_hydrad_of_depth_array include/openswmm/engine/openswmm_xsect.h 448 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_is_open include/openswmm/engine/openswmm_xsect.h 427 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_sectfactor_of_area include/openswmm/engine/openswmm_xsect.h 361 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_sectfactor_of_area_array include/openswmm/engine/openswmm_xsect.h 460 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_shape_name include/openswmm/engine/openswmm_xsect.h 285 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_width_of_depth include/openswmm/engine/openswmm_xsect.h 313 pyx_use python/openswmm/engine/_xsect.pyx +swmm_xsect_width_of_depth_array include/openswmm/engine/openswmm_xsect.h 444 pyx_use python/openswmm/engine/_xsect.pyx diff --git a/docs/analysis/RAINFALL_2D_TEMPORAL_OUTPUT_AUDIT_2026-09-30.md b/docs/analysis/RAINFALL_2D_TEMPORAL_OUTPUT_AUDIT_2026-09-30.md new file mode 100644 index 000000000..7cfa98c3b --- /dev/null +++ b/docs/analysis/RAINFALL_2D_TEMPORAL_OUTPUT_AUDIT_2026-09-30.md @@ -0,0 +1,74 @@ +# 2D rainfall: input formats, integration and saved output + +## Scope + +Audit the current engine's gage-to-cell rainfall conversion and its actual HDF5 output, independently of the GUI plot renderer. The affected project was not supplied; this is controlled model verification, not a diagnosis of that project's individual dry cells. + +## Input and output contracts + +- `INTENSITY` records are rates in the project's rain units: in/hr for US flow units, mm/hr for SI flow units. +- `VOLUME` records are **rainfall depths per gage recording interval** (inches or millimetres), not cubic metres. Conversion is `depth / interval_seconds * 3600`. +- `CUMULATIVE` records are cumulative depths. Consecutive differences give interval depths; a decreasing counter starts a new accumulation and the new reading is that interval's depth. Differencing happens before spatial interpolation. +- Each gage uses its own recording interval. Its converted rate is constant over that interval; gaps are dry. The runoff clock books changes, and each 2D synchronization window receives the integral of those rates divided by the window duration. The solver's smaller internal steps use that window mean. +- Spatial weights map gage values to each cell. Natural neighbour uses its existing inverse-distance fallback outside the gage hull. Nearest neighbour selects the closest located gage, including when its rainfall is zero. +- `Mesh2_face_rainfall` stores a sampled rate in **m/s**, not a report-period average. Multiply by 3,600,000 for mm/hr. +- `Mesh2_face_rain_cum` stores cumulative **volume in m³ per cell**. Divide by `Mesh2_face_area` for depth in metres; multiply by 1,000 for millimetres. Differences between cumulative records give the volume over a reporting interval. + +For cell c, area A and static spatial weights w, the expected accumulated volume is: + +`V_c(t) = A_c * sum_g(w_cg * integral(start, t, rain_g(t) dt))`. + +A storm entirely between report instants can leave every sampled rate zero while cumulative volume increases correctly. Also, the last scheduled frame can precede simulation end: the final `mass_balance_2d/rainfall_in` includes the trailing interval, while that last frame stops at its own reporting time. `swmm_engine_end()` flushes a final partial 2D batch before writing final mass balance. + +## Confirmed defects and correction + +The old saved cumulative volume came directly from the completed 2D window, even when that window ended after the frame timestamp. A controlled 7-second routing case reported the accumulated volume through 21 seconds at the 17-second frame, 23.53% too high at that early frame. Across 36 cases / 1,080 cell records, maximum absolute saved-volume error was 0.0012072649572649578 m³. Final domain rainfall totals were already correct: maximum error against the independent input integral was 9.03e-17 m³. + +The correction preserves the gage integral at a report boundary before the runoff clock passes it, then maps only the portion up to that boundary onto the cells. Added and overridden cell rainfall is included over the corresponding portion of the window. Runtime source rates, integration, and mass-balance totals are unchanged. Storage is bounded to one additional gage row and one cell row; the extra spatial mapping occurs at report cadence. This reconstructs source accumulation at the requested time: the hydraulic solver still applies a window-mean source, and reported depth/head still use linear state interpolation. Inside a window crossing a rain change, those interpolated hydraulic states need not imply exactly the same partial volume as the piecewise gage integral. Completed-window and final rainfall conservation are unchanged. + +The saved rate also used the runoff cursor's current rain record. If a routing step crossed a report instant and then a rain-record change, the cursor could already point beyond the requested report time. The 2D report path now looks up the source interval directly, reusing the existing format conversion, scaling, co-gage and monthly-adjustment handling. The 1D legacy report path is preserved. Both paths retain SWMM's +1 second report-gage lookup convention, so a rate within one second of a boundary can show the next interval; cumulative volume integrates to the nominal report boundary without this look-ahead. + +The HDF5 `time` coordinate contained absolute SWMM dates but was labelled `days since simulation start`. The label is corrected to `days since 1899-12-30 00:00:00`. Numeric timestamps are unchanged and retain SWMM's 1 ms report-date offset. The GUI already interprets these numbers as absolute SWMM dates. + +## Regression matrix + +`Output2DWriter.RainFormatsAndMismatchedClocks` writes and reopens real output files. Its expected values come from independently integrated depth records, not the production conversion or integration functions. + +The matrix combines both interpolation modes, both unit systems and all three rain formats with these clock configurations: + +| Routing maximum (s) | 2D maximum substep (s) | Base report interval (s) | Requested runoff interval (s) | Start offset (s) | Additional coverage | +|---:|---:|---:|---:|---:|---| +| 7 | 2 | 17 | 37 | 0 | Unaligned report and rain boundaries | +| 31 | 7 | 60 | 120 | 17 | Partial first rain interval and final simulation interval | +| 2.5 | 0.7 | 19 | 13 | 0 | Fractional routing and solver timesteps | +| 7 | 2 | 17 | 37 | 0 | 29 s synchronization, report start at 68 s, 34 s 2D reports, FLOAT32, persistent added rainfall | +| 31 | 7 | 53 | 120 | 17 | Routing step crosses a rain change after the report instant | + +Three simultaneously active gages have 60-, 120- and 180-second recording intervals, distinct wet/dry patterns and cumulative counter resets. The engine correctly reduces a requested runoff step longer than the shortest recording interval. Other cases use FLOAT64. All authored report intervals exceed the routing maximum; sub-routing-step reporting is outside this matrix. + +The assertions cover each saved rate, each saved cumulative cell volume, frame count, timestamps, unit attributes, final rainfall mass balance and consistency of the live cell-volume sum with the live ledger. Existing pulse, dry-cell, spatial interpolation and gage-file tests provide complementary coverage. + +## Validation artifacts + +Reviewable generated models, reports and HDF5 files: `tests/output/2d_output_options/rain_clocks_*`. + +Audit logs and the independent Python/HDF5 checker: `tests/output/rainfall_temporal_audit_2026-09-30/`. + +## Results + +- All **60 model runs / 1,440 saved cell records** passed the analytic comparisons. +- All **45 tests** passed across `test_engine_gage_rain_series` (10), `test_engine_2d_rainfall_interp` (19) and `test_engine_2d_output_options` (16). The between-report pulse test now requires zero cumulative rain at the pulse's start instead of allowing an entire routing step's premature rainfall. +- The independent Python/HDF5 audit found a maximum FLOAT64 cumulative-volume error of **3.13e-17 m³** and maximum rate error of **1.70e-21 m/s**. For FLOAT32 these were **8.91e-10 m³** and **1.08e-13 m/s**, consistent with storage rounding. +- Maximum final domain rainfall error was **9.03e-17 m³**. Final rainfall totals on the original 36 baseline cases changed by **exactly zero** after the output corrections. +- All 60 files have the corrected time-axis units. Both US and SI models retain SI rainfall output units. + +Validation used the rebuilt Release engine and the CPU explicit 2D marcher with one local-timestep tier. These changes are in the engine working tree; no GUI package was rebuilt or installed during this audit. Existing results need a simulation rerun with the updated engine to obtain corrected saved values. The input matrix uses model time series; external rain-file loading is covered separately by the passing gage-series suite, rather than every external file format being crossed with every clock configuration. + +Reproduce the automated matrix and regression checks: + +```sh +cmake --build build/darwin --target test_engine_2d_output_options test_engine_2d_rainfall_interp test_engine_gage_rain_series -j6 +ctest --test-dir build/darwin -R '^test_engine_(2d_output_options|2d_rainfall_interp|gage_rain_series)$' --output-on-failure +``` + +The independent file-audit summaries are `before.json` and `after.json`; the test logs are `before.log`, `after.log`, and `regression.log` in the audit artifact directory above. diff --git a/docs/custom/css/manual.css b/docs/custom/css/manual.css new file mode 100644 index 000000000..e3da02ccc --- /dev/null +++ b/docs/custom/css/manual.css @@ -0,0 +1,103 @@ +/* Manual-specific styling on top of doxygen-awesome. + * + * Status badges: emitted by the Doxyfile alias + * \status{Implemented} -> Implemented + * The four hex values are copied from docs/figures/status.py; the lint + * (check_status_badges) fails if they drift apart, so change them there first. + */ +.status-badge { + display: inline-block; + padding: 0 0.55em; + border-radius: 1em; + font-size: 0.78em; + font-weight: 600; + line-height: 1.7; + letter-spacing: 0.01em; + color: #ffffff; + white-space: nowrap; + vertical-align: baseline; +} +.status-badge[data-status="Implemented"] { background: #1baf7a; } +.status-badge[data-status="Experimental"] { background: #eda100; } +.status-badge[data-status="Planned"] { background: #898781; } +.status-badge[data-status="Retired"] { background: #e87ba4; text-decoration: line-through; } + +html.dark-mode .status-badge[data-status="Implemented"] { background: #148a5f; } +html.dark-mode .status-badge[data-status="Experimental"] { background: #b97e00; } +html.dark-mode .status-badge[data-status="Planned"] { background: #6a6863; } +html.dark-mode .status-badge[data-status="Retired"] { background: #b85c7f; } + +/* A table whose header names a Status column reads better with the badge + * centred and the column kept narrow. */ +table.markdownTable td .status-badge { margin: 0 auto; } + +/* Interactive diagrams (docs/custom/js/manual-interactive.js). + * + * The link blocks that carry the click targets are data for the script, not + * content: hidden here so a page without JavaScript shows the plain figure. */ +div.fig-hotspots, div.workflow-links { display: none; } + +.mi-wrap { position: relative; margin: 0.6em 0 0.3em; } +.mi-viewport { + position: relative; + overflow: hidden; + border: 1px solid var(--separator-color, #dedede); + border-radius: 6px; + background: var(--page-background-color, #ffffff); + cursor: grab; + touch-action: pan-y; + user-select: none; + -webkit-user-select: none; +} +.mi-viewport.is-active { + border-color: var(--primary-color, #1982d2); + box-shadow: 0 0 0 2px rgba(25, 130, 210, 0.22); + touch-action: none; +} +.mi-viewport.is-dragging { cursor: grabbing; } +.mi-canvas { position: relative; display: inline-block; max-width: 100%; transform-origin: 0 0; will-change: transform; } +.mi-canvas > img { display: block; max-width: 100%; height: auto; } +.mi-canvas > pre.mermaid { margin: 0; padding: 0.4em; background: transparent; border: 0; text-align: center; } +.mi-canvas > pre.mermaid > svg { max-width: 100%; height: auto; } +.mi-overlay { position: absolute; left: 0; top: 0; right: 0; bottom: 0; } +.mi-hs { + position: absolute; + display: block; + border: 1px solid transparent; + border-radius: 4px; + box-sizing: border-box; + cursor: pointer; +} +.mi-hs:hover, .mi-hs:focus-visible { + border-color: var(--primary-color, #1982d2); + background: rgba(25, 130, 210, 0.13); + outline: none; +} +.mi-toolbar { + position: absolute; + top: 6px; + right: 6px; + display: flex; + gap: 4px; + z-index: 5; + opacity: 0.45; + transition: opacity 0.15s; +} +.mi-wrap:hover .mi-toolbar, .mi-viewport.is-active ~ .mi-toolbar { opacity: 1; } +.mi-btn { + min-width: 26px; + height: 26px; + padding: 0 6px; + border: 1px solid var(--separator-color, #cfcfcf); + border-radius: 5px; + background: var(--page-background-color, #ffffff); + color: var(--page-foreground-color, #222222); + font: 600 14px/24px sans-serif; + text-align: center; + text-decoration: none; + cursor: pointer; +} +.mi-btn:hover { border-color: var(--primary-color, #1982d2); color: var(--primary-color, #1982d2); } +.mi-hint { font-size: 0.78em; color: var(--page-secondary-foreground-color, #6a6a6a); margin-top: 0.3em; } +html.dark-mode .mi-viewport.is-active { box-shadow: 0 0 0 2px rgba(120, 180, 240, 0.28); } +html.dark-mode .mi-hs:hover, html.dark-mode .mi-hs:focus-visible { background: rgba(120, 180, 240, 0.18); } diff --git a/docs/custom/html/header.html b/docs/custom/html/header.html index 13a72f9e2..d59d3e9ca 100644 --- a/docs/custom/html/header.html +++ b/docs/custom/html/header.html @@ -43,14 +43,19 @@ + in the manual markdown. Theme follows the doxygen-awesome dark-mode class. + Rendering is started by manual-interactive.js, which first injects the click + targets a block's
carries, then wraps every + diagram and every hotspot figure in a pan/zoom viewport. --> + $extrastylesheet diff --git a/docs/custom/js/manual-interactive.js b/docs/custom/js/manual-interactive.js new file mode 100644 index 000000000..a27fa5f18 --- /dev/null +++ b/docs/custom/js/manual-interactive.js @@ -0,0 +1,263 @@ +/* manual-interactive.js — pan, zoom and click for the manuals' workflow and + * process diagrams. + * + * Two kinds of diagram are made interactive: + * + * 1. Mermaid workflows: `
` blocks. When a block is
+ *      followed by `
` whose
+ *      `` children hold links (written as @ref in the
+ *      markdown and resolved by Doxygen), a Mermaid `click` directive is
+ *      injected per node before rendering, so the node opens that page.
+ *
+ *   2. Generated figures with hotspots: an `` whose page carries
+ *      `
` with
+ *      `` children (fractions of the
+ *      image, top-left origin) holding a resolved link each. The spans are
+ *      written by scripts/build_manual_figures.py from the generator's
+ *      sink.hotspot() calls, so the boxes match the drawing exactly.
+ *
+ * Both get the same viewport: drag to pan, wheel to zoom once the diagram is
+ * activated by a click (or with Ctrl/⌘ held, so a page scroll is never
+ * hijacked), pinch on touch, double-click to reset, and a small toolbar.
+ * Everything degrades to the static image or diagram without JavaScript.
+ *
+ * Rendering is driven from docs/custom/html/header.html, which imports
+ * Mermaid and calls ManualInteractive.init(mermaid).
+ */
+(function () {
+  "use strict";
+  var MIN_SCALE = 0.4, MAX_SCALE = 10;
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text) e.textContent = text;
+    return e;
+  }
+
+  function panZoom(wrap, viewport, canvas) {
+    var s = 1, tx = 0, ty = 0, active = false, suppressClick = false, drag = null;
+    var pointers = new Map(), pinch = null;
+
+    function apply() { canvas.style.transform = "translate(" + tx + "px," + ty + "px) scale(" + s + ")"; }
+    function zoomAt(factor, cx, cy) {
+      var ns = Math.min(MAX_SCALE, Math.max(MIN_SCALE, s * factor));
+      factor = ns / s;
+      tx = cx - factor * (cx - tx);
+      ty = cy - factor * (cy - ty);
+      s = ns;
+      apply();
+    }
+    function reset() { s = 1; tx = 0; ty = 0; apply(); }
+    function centre() { return [viewport.clientWidth / 2, viewport.clientHeight / 2]; }
+    function setActive(on) {
+      active = on;
+      viewport.classList.toggle("is-active", on);
+    }
+
+    viewport.addEventListener("wheel", function (e) {
+      if (!active && !(e.ctrlKey || e.metaKey)) return;
+      e.preventDefault();
+      var r = viewport.getBoundingClientRect();
+      zoomAt(Math.exp(-e.deltaY * 0.0015), e.clientX - r.left, e.clientY - r.top);
+    }, { passive: false });
+
+    viewport.addEventListener("pointerdown", function (e) {
+      if (e.button !== 0) return;
+      pointers.set(e.pointerId, [e.clientX, e.clientY]);
+      viewport.setPointerCapture(e.pointerId);
+      if (pointers.size === 1) {
+        drag = { x: e.clientX, y: e.clientY, tx: tx, ty: ty, moved: false };
+      } else if (pointers.size === 2) {
+        var p = Array.from(pointers.values());
+        pinch = { d: Math.hypot(p[0][0] - p[1][0], p[0][1] - p[1][1]), s: s };
+        drag = null;
+      }
+    });
+    viewport.addEventListener("pointermove", function (e) {
+      if (!pointers.has(e.pointerId)) return;
+      pointers.set(e.pointerId, [e.clientX, e.clientY]);
+      if (pinch && pointers.size === 2) {
+        var p = Array.from(pointers.values());
+        var d = Math.hypot(p[0][0] - p[1][0], p[0][1] - p[1][1]);
+        var r = viewport.getBoundingClientRect();
+        var cx = (p[0][0] + p[1][0]) / 2 - r.left, cy = (p[0][1] + p[1][1]) / 2 - r.top;
+        zoomAt((pinch.s * d / pinch.d) / s, cx, cy);
+        e.preventDefault();
+      } else if (drag) {
+        var dx = e.clientX - drag.x, dy = e.clientY - drag.y;
+        if (Math.abs(dx) + Math.abs(dy) > 3) {
+          drag.moved = true;
+          viewport.classList.add("is-dragging");
+        }
+        if (drag.moved) {
+          tx = drag.tx + dx; ty = drag.ty + dy;
+          apply();
+          e.preventDefault();
+        }
+      }
+    });
+    function endPointer(e) {
+      pointers.delete(e.pointerId);
+      if (pointers.size < 2) pinch = null;
+      if (drag && drag.moved) suppressClick = true;
+      drag = null;
+      viewport.classList.remove("is-dragging");
+    }
+    viewport.addEventListener("pointerup", endPointer);
+    viewport.addEventListener("pointercancel", endPointer);
+
+    // a click that ends a drag must not follow a hotspot link; a plain click activates zooming
+    viewport.addEventListener("click", function (e) {
+      if (suppressClick) { suppressClick = false; e.preventDefault(); e.stopPropagation(); return; }
+      setActive(true);
+    }, true);
+    viewport.addEventListener("dblclick", function (e) { e.preventDefault(); reset(); });
+    document.addEventListener("click", function (e) { if (!wrap.contains(e.target)) setActive(false); });
+    document.addEventListener("keydown", function (e) { if (e.key === "Escape") setActive(false); });
+
+    // the viewport keeps the diagram's layout height whatever the transform
+    function fit() { viewport.style.height = canvas.offsetHeight + "px"; }
+    if (window.ResizeObserver) new ResizeObserver(fit).observe(canvas); else window.addEventListener("resize", fit);
+    fit();
+
+    return {
+      zoomIn: function () { var c = centre(); zoomAt(1.25, c[0], c[1]); },
+      zoomOut: function () { var c = centre(); zoomAt(0.8, c[0], c[1]); },
+      reset: reset,
+      fit: fit
+    };
+  }
+
+  function toolbar(wrap, pz, extra) {
+    var bar = el("div", "mi-toolbar");
+    function button(label, title, fn) {
+      var b = el("button", "mi-btn", label);
+      b.type = "button";
+      b.title = title;
+      b.addEventListener("click", function (e) { e.stopPropagation(); fn(); });
+      bar.appendChild(b);
+    }
+    button("+", "Zoom in", pz.zoomIn);
+    button("−", "Zoom out", pz.zoomOut);
+    button("⟲", "Reset the view (or double-click the diagram)", pz.reset);
+    if (extra) bar.appendChild(extra);
+    wrap.appendChild(bar);
+  }
+
+  function wrapElement(target, hint) {
+    var wrap = el("div", "mi-wrap");
+    var viewport = el("div", "mi-viewport");
+    var canvas = el("div", "mi-canvas");
+    target.parentNode.insertBefore(wrap, target);
+    canvas.appendChild(target);
+    viewport.appendChild(canvas);
+    wrap.appendChild(viewport);
+    var pz = panZoom(wrap, viewport, canvas);
+    var hintEl = el("div", "mi-hint", hint || "drag to pan · click the diagram, then scroll to zoom (or hold Ctrl/⌘) · double-click resets");
+    wrap.appendChild(hintEl);
+    return { wrap: wrap, viewport: viewport, canvas: canvas, pz: pz };
+  }
+
+  // ── figures with hotspots ────────────────────────────────────────────────
+  function findImage(figId) {
+    var imgs = document.querySelectorAll("img");
+    for (var i = 0; i < imgs.length; i++) {
+      var src = imgs[i].getAttribute("src") || "";
+      if (src.split("/").pop() === figId + ".png") return imgs[i];
+    }
+    return null;
+  }
+
+  function initFigures() {
+    var blocks = document.querySelectorAll("div.fig-hotspots[data-fig]");
+    for (var b = 0; b < blocks.length; b++) {
+      var block = blocks[b], figId = block.getAttribute("data-fig");
+      var img = findImage(figId);
+      if (!img || img.closest(".mi-wrap")) continue;
+      var open = el("a", "mi-btn", "⤢");
+      open.href = img.getAttribute("src");
+      open.target = "_blank";
+      open.rel = "noopener";
+      open.title = "Open the image in a new tab";
+      var w = wrapElement(img, "drag to pan · click the figure, then scroll to zoom (or hold Ctrl/⌘) · double-click resets · click a box to open its chapter");
+      var overlay = el("div", "mi-overlay");
+      var spans = block.querySelectorAll("span.hs[data-box]");
+      for (var i = 0; i < spans.length; i++) {
+        var a = spans[i].querySelector("a[href]");
+        if (!a) continue;
+        var box = spans[i].getAttribute("data-box").split(",").map(Number);
+        if (box.length !== 4 || box.some(isNaN)) continue;
+        var hs = el("a", "mi-hs");
+        hs.href = a.getAttribute("href");
+        hs.title = a.textContent + (a.title && a.title !== a.textContent ? " — " + a.title : "");
+        hs.setAttribute("aria-label", hs.title);
+        hs.style.left = (box[0] * 100) + "%";
+        hs.style.top = (box[1] * 100) + "%";
+        hs.style.width = ((box[2] - box[0]) * 100) + "%";
+        hs.style.height = ((box[3] - box[1]) * 100) + "%";
+        overlay.appendChild(hs);
+      }
+      w.canvas.appendChild(overlay);
+      toolbar(w.wrap, w.pz, open);
+      if (!img.complete) img.addEventListener("load", w.pz.fit);
+    }
+  }
+
+  // ── Mermaid workflows ────────────────────────────────────────────────────
+  function previousMermaid(node) {
+    var p = node.previousSibling;
+    while (p) {
+      if (p.nodeType === 1) {
+        if (p.matches("pre.mermaid")) return p;
+        var inner = p.querySelector && p.querySelector("pre.mermaid");
+        if (inner) return inner;
+        return null;
+      }
+      if (p.nodeType === 3 && p.textContent.trim() !== "") return null;
+      p = p.previousSibling;
+    }
+    return null;
+  }
+
+  function injectClicks() {
+    var links = document.querySelectorAll("div.workflow-links[data-workflow]");
+    for (var i = 0; i < links.length; i++) {
+      var pre = previousMermaid(links[i]);
+      if (!pre || pre.getAttribute("data-processed")) continue;
+      var spans = links[i].querySelectorAll("span[data-node]");
+      var extra = "";
+      for (var j = 0; j < spans.length; j++) {
+        var a = spans[j].querySelector("a[href]");
+        if (!a) continue;
+        var node = spans[j].getAttribute("data-node");
+        if (!/^[A-Za-z0-9_]+$/.test(node)) continue;
+        var tip = (a.textContent || node).replace(/"/g, "'");
+        extra += "\nclick " + node + " \"" + a.getAttribute("href").replace(/"/g, "") + "\" \"" + tip + "\"";
+      }
+      if (extra) pre.textContent = pre.textContent.replace(/\s+$/, "") + extra + "\n";
+    }
+  }
+
+  function wrapMermaids() {
+    var pres = document.querySelectorAll("pre.mermaid");
+    for (var i = 0; i < pres.length; i++) {
+      if (pres[i].closest(".mi-wrap")) continue;
+      var w = wrapElement(pres[i]);
+      toolbar(w.wrap, w.pz, null);
+    }
+  }
+
+  window.ManualInteractive = {
+    init: function (mermaid) {
+      try { initFigures(); } catch (e) { if (window.console) console.warn("manual-interactive: figures", e); }
+      if (!mermaid) return;
+      try { injectClicks(); } catch (e) { if (window.console) console.warn("manual-interactive: click injection", e); }
+      var run = mermaid.run ? mermaid.run({ querySelector: "pre.mermaid" }) : Promise.resolve(mermaid.init(undefined, "pre.mermaid"));
+      Promise.resolve(run).then(wrapMermaids, function (e) {
+        if (window.console) console.warn("manual-interactive: mermaid", e);
+        wrapMermaids();
+      });
+    }
+  };
+})();
diff --git a/docs/figures/MANIFEST.tsv b/docs/figures/MANIFEST.tsv
new file mode 100644
index 000000000..e8ec8e0a6
--- /dev/null
+++ b/docs/figures/MANIFEST.tsv
@@ -0,0 +1,227 @@
+# fig_id	tier	generator	inputs	file	page_id	figure_no	caption	provenance
+# One row per image any manual embeds. Audited by scripts/build_manual_figures.py check;
+# the column contract is in that script's docstring. Keep rows sorted by fig_id.
+eng_conceptual_map	synthetic	src/engine/conceptual_map.py	-	figures/png/eng_conceptual_map.png	engine_manual_ch1_conceptual_model	1-1	Compartments, processes and the formulations that represent them	-
+eng_fig3_02_box_culvert	legacy	-	-	manuals/engine/figures/fig3-02-box-culvert.jpg	engine_manual_ch1_conceptual_model	1-4	Concrete box culvert	Concrete Box Culvert.png (retired user manual; converted PNG->JPEG q88 2026-09-19, photograph over 400 KB as PNG)
+eng_fig3_03_storm_drain_inlet	legacy	-	-	manuals/engine/figures/fig3-03-storm-drain-inlet.png	engine_manual_ch1_conceptual_model	1-5	Storm drain inlet	Storm Drain Inlet Grate.png
+eng_fig3_06_natural_transect	legacy	-	-	manuals/engine/figures/fig3-06-natural-transect.jpg	engine_manual_ch1_conceptual_model	1-8	Example of a natural channel transect	Natural Channel Transect.png (retired user manual; converted PNG->JPEG q88 2026-09-19, photograph over 400 KB as PNG)
+eng_fig3_08_dual_drainage	legacy	-	-	manuals/engine/figures/fig3-08-dual-drainage.png	engine_manual_ch1_conceptual_model	1-10	Representation of a dual drainage system	Dual Drainage System.png
+eng_fig3_09_hec22_inlets	legacy	-	-	manuals/engine/figures/fig3-09-hec22-inlets.png	engine_manual_ch1_conceptual_model	1-11	HEC-22 inlets supported by SWMM	HEC22 Inlets.png
+eng_fig3_10_lid_adjustment	legacy	-	-	manuals/engine/figures/fig3-10-lid-adjustment.png	engine_manual_ch1_conceptual_model	1-12	Adjustment of subcatchment parameters after LID placement	LID Parameter Adjustment.png
+eng_figure1_1_urban_sewershed	legacy	-	-	manuals/engine/figures/figure1_1_urban_sewershed.jpg	engine_manual	-	Urban wet weather flows	Urban Wet Weather Flows Diagram.png (retired user manual; converted PNG->JPEG q88 2026-09-19, photograph over 400 KB as PNG)
+eng_hydrocouple_logo	legacy	-	-	images/hydrocouple_logo.png	-	-	-	Doxyfile PROJECT_LOGO; README.md; python/docs/index.rst
+eng_lid_bioretention_layers	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/eng_lid_bioretention_layers.png	engine_manual_ch1_conceptual_model	1-15	Conceptual diagram of a bio-retention cell LID	-
+eng_object_sketch	synthetic	src/engine/object_sketch.py	-	figures/png/eng_object_sketch.png	engine_manual_ch1_conceptual_model;hydraulics_ref_ch1_overview;hydrology_ref_ch1_overview;quality_ref_ch1_overview	1-2	Objects of an OpenSWMM model	-
+eng_process_flow	synthetic	src/engine/process_flow.py	-	figures/png/eng_process_flow.png	engine_manual_ch1_conceptual_model;hydraulics_ref_ch1_overview;hydrology_ref_ch1_overview;quality_ref_ch1_overview	1-3	Processes modelled by OpenSWMM	-
+eng_rdii_unit_hydrograph	synthetic	src/hydrology/ch7_rtk_unit_hydrograph.py	-	figures/png/eng_rdii_unit_hydrograph.png	engine_manual_ch1_conceptual_model	1-7	An RDII unit hydrograph	-
+hydraulics_ch3_virtual_junction	synthetic	src/hydraulics/ch3_virtual_junction.py	-	figures/png/hydraulics_ch3_virtual_junction.png	hydraulics_ref_ch3_dynamic_wave	3-10	A regular junction and a virtual junction at a grade break	-
+hydraulics_ch5_circular_theta	synthetic	src/hydraulics/ch5_xsect_gallery.py	-	figures/png/hydraulics_ch5_circular_theta.png	hydraulics_ref_ch5_cross_section	-	Definition sketch of the circular section: central angle θ	-
+hydraulics_ch5_power_law	synthetic	src/hydraulics/ch5_xsect_gallery.py	-	figures/png/hydraulics_ch5_power_law.png	hydraulics_ref_ch5_cross_section	5-1	Power law cross section shape	-
+hydraulics_ch5_shapes_composite	synthetic	src/hydraulics/ch5_xsect_gallery.py	-	figures/png/hydraulics_ch5_shapes_composite.png	hydraulics_ref_ch5_cross_section	5-6	Composite cross section shapes	-
+hydraulics_ch5_shapes_elliptical_arch	synthetic	src/hydraulics/ch5_xsect_gallery.py	-	figures/png/hydraulics_ch5_shapes_elliptical_arch.png	hydraulics_ref_ch5_cross_section	5-4	Elliptical and arch pipe cross sectional shapes	-
+hydraulics_ch5_shapes_masonry	synthetic	src/hydraulics/ch5_xsect_gallery.py	-	figures/png/hydraulics_ch5_shapes_masonry.png	hydraulics_ref_ch5_cross_section	5-5	Masonry sewer shapes	-
+hydraulics_ch5_storage_cone	synthetic	src/hydraulics/ch5_storage_shapes.py	-	figures/png/hydraulics_ch5_storage_cone.png	hydraulics_ref_ch5_cross_section	-	Elliptical cone storage shape	-
+hydraulics_ch5_storage_cylinder	synthetic	src/hydraulics/ch5_storage_shapes.py	-	figures/png/hydraulics_ch5_storage_cylinder.png	hydraulics_ref_ch5_cross_section	-	Elliptical cylinder storage shape	-
+hydraulics_ch5_storage_paraboloid	synthetic	src/hydraulics/ch5_storage_shapes.py	-	figures/png/hydraulics_ch5_storage_paraboloid.png	hydraulics_ref_ch5_cross_section	-	Elliptical paraboloid storage shape	-
+hydraulics_ch5_storage_pyramid	synthetic	src/hydraulics/ch5_storage_shapes.py	-	figures/png/hydraulics_ch5_storage_pyramid.png	hydraulics_ref_ch5_cross_section	-	Rectangular pyramid storage shape	-
+hydraulics_ch5_street_section	synthetic	src/hydraulics/ch5_street_section.py	-	figures/png/hydraulics_ch5_street_section.png	engine_manual_ch1_conceptual_model;hydraulics_ref_ch5_cross_section	5-10	A one-sided street cross-section	-
+hydraulics_ch6_pump_type1	synthetic	src/hydraulics/ch6_pump_types.py	-	figures/png/hydraulics_ch6_pump_type1.png	hydraulics_ref_ch6_pumps_regulators	-	Type 1 pump curve	-
+hydraulics_ch6_pump_type2	synthetic	src/hydraulics/ch6_pump_types.py	-	figures/png/hydraulics_ch6_pump_type2.png	hydraulics_ref_ch6_pumps_regulators	-	Type 2 pump curve	-
+hydraulics_ch6_pump_type3	synthetic	src/hydraulics/ch6_pump_types.py	-	figures/png/hydraulics_ch6_pump_type3.png	hydraulics_ref_ch6_pumps_regulators	-	Type 3 pump curve	-
+hydraulics_ch6_pump_type4	synthetic	src/hydraulics/ch6_pump_types.py	-	figures/png/hydraulics_ch6_pump_type4.png	hydraulics_ref_ch6_pumps_regulators	-	Type 4 pump curve	-
+hydraulics_ch6_pump_type5	synthetic	src/hydraulics/ch6_pump_types.py	-	figures/png/hydraulics_ch6_pump_type5.png	hydraulics_ref_ch6_pumps_regulators	-	Type 5 pump curve	-
+hydraulics_ch7_street_spread	synthetic	src/hydraulics/ch5_street_section.py	-	figures/png/hydraulics_ch7_street_spread.png	hydraulics_ref_ch7_advanced_features	7-11	Street cross-section divided into gutter and roadway flow	-
+hydraulics_ch8_cell_layout	synthetic	src/hydraulics/ch8_cell_layout.py	-	figures/png/hydraulics_ch8_cell_layout.png	hydraulics_ref_ch8_finite_volume	8-1	Node–link routing against the finite-volume view: one momentum balance per conduit versus a conduit cut into cells with the water surface resolved inside it	-
+hydraulics_ch8_hll_fan	synthetic	src/hydraulics/ch8_hll_fan.py	-	figures/png/hydraulics_ch8_hll_fan.png	hydraulics_ref_ch8_finite_volume	8-3	The Riemann fan at a face: HLL signal speeds for a wet–wet face and the rarefaction-tail estimate at a dry bed	-
+hydraulics_ch8_hydrostatic_reconstruction	synthetic	src/hydraulics/ch8_hydrostatic_reconstruction.py	-	figures/png/hydraulics_ch8_hydrostatic_reconstruction.png	hydraulics_ref_ch8_finite_volume	8-7	Hydrostatic reconstruction at a wet and dry face	-
+hydraulics_ch8_lts_ladder	synthetic	src/hydraulics/ch8_lts_ladder.py	-	figures/png/hydraulics_ch8_lts_ladder.png	hydraulics_ref_ch8_finite_volume	8-4	Local time stepping: power-of-two tiers, the macro cycle and flux accumulation across a tier interface	-
+hydraulics_ch8_node_ghost_state	synthetic	src/hydraulics/ch8_node_ghost_state.py	-	figures/png/hydraulics_ch8_node_ghost_state.png	hydraulics_ref_ch8_finite_volume	8-8	Ghost state built from the node head at a coupling face	-
+hydraulics_ch8_slot_closure	synthetic	src/hydraulics/ch8_slot_closure.py	-	figures/png/hydraulics_ch8_slot_closure.png	hydraulics_ref_ch8_finite_volume	8-2	The tapered static slot for a 3 ft circular pipe: top width and celerity across the crown at four slot celerities	-
+hydraulics_ch9_active_set	synthetic	src/hydraulics/ch9_active_set.py	-	figures/png/hydraulics_ch9_active_set.png	hydraulics_ref_ch9_two_dimensional	9-5	The flux-active set at a wetting front: the default one-ring halo, the front-rebuild halo and the breach that forces an early rebuild	-
+hydraulics_ch9_coupling_modes	synthetic	src/hydraulics/ch9_coupling_modes.py	-	figures/png/hydraulics_ch9_coupling_modes.png	hydraulics_ref_ch9_two_dimensional	9-6	Where a node spill is booked under COUPLING_IN_FLOODING: the same totals and the same continuity error, in two different rows	-
+hydraulics_ch9_mesh_stencil	synthetic	src/hydraulics/ch9_mesh_stencil.py	-	figures/png/hydraulics_ch9_mesh_stencil.png	hydraulics_ref_ch9_two_dimensional	9-4	A quadrilateral and a triangle sharing a face: local edge numbering, the padded slot layout and the centroid-to-edge distance	-
+hydraulics_ch9_vfr_wetting_cases	synthetic	src/hydraulics/ch9_vfr_wetting_cases.py	-	figures/png/hydraulics_ch9_vfr_wetting_cases.png	hydraulics_ref_ch9_two_dimensional	9-3	Wetting cases of a planar-bed triangular cell and the wetted-edge face gate	-
+hydraulics_conceptual_1d2d	synthetic	src/engine/conceptual_map.py	-	figures/png/hydraulics_conceptual_1d2d.png	hydraulics_ref_ch9_two_dimensional	9-1	The one-dimensional network and the two-dimensional surface: exchange pathways	-
+hydraulics_conceptual_map	synthetic	src/engine/conceptual_map.py	-	figures/png/hydraulics_conceptual_map.png	hydraulics_ref_ch1_overview	1-7	The hydraulics of this manual: the 1D network, the 2D surface and their coupling	-
+hydraulics_figure3_8_placeholder	legacy	-	-	manuals/reference/hydraulics/media/media/figure3-8-placeholder.png	hydraulics_ref_ch3_dynamic_wave	3-8	Conceptual representation of the dynamic Preissmann slot	scripts/generate_placeholder_figures.py (watermarked placeholder, 2026-08-11)
+hydraulics_figure4_1	legacy	-	-	manuals/reference/hydraulics/media/media/figure4-1.png	hydraulics_ref_ch4_kinematic_wave	4-1	Section factor versus area for a circular shape	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_figure1_6	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-figure1-6.png	hydraulics_ref_ch1_overview	1-6	Interpolation of reported values from computed values	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image1	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image1.jpeg	hydraulics_ref_ch1_overview	1-1	Elements of a typical urban drainage system	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image10	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image10.png	hydraulics_ref_ch2_hydraulic_model	2-2	Comparison of dynamic wave and kinematic wave solutions (from Miller, 1984)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image11	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image11.png	hydraulics_ref_ch3_dynamic_wave	3-1	Node-link representation of a conveyance network in SWMM (from Roesner et al, 1992)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image12	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image12.png	hydraulics_ref_ch3_dynamic_wave	3-2	Special flow conditions for dynamic wave analysis	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image13	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image13.png	hydraulics_ref_ch3_dynamic_wave	3-2	Special flow conditions for dynamic wave analysis	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image14	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image14.png	hydraulics_ref_ch3_dynamic_wave	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image15	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image15.png	hydraulics_ref_ch3_dynamic_wave	3-4	Ponding of excess water above a junction	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image16	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image16.png	hydraulics_ref_ch3_dynamic_wave	3-5	Profile view of example rectangular conduit (not to scale)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image17	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image17.png	hydraulics_ref_ch3_dynamic_wave	3-6	Outflow hydrographs for example conduit -I	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image18	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image18.png	hydraulics_ref_ch3_dynamic_wave	3-7	Outflow hydrographs for example conduit - II	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image20	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image20.png	hydraulics_ref_ch4_kinematic_wave	4-2	Space-time grid for kinematic wave analysis	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image21	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image21.png	hydraulics_ref_ch4_kinematic_wave	4-3	Outflow hydrograph for example conduit	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image23	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image23.png	hydraulics_ref_ch5_cross_section	5-2	Geometric properties of a partly filled circular shape based on depth	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image24	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image24.png	hydraulics_ref_ch5_cross_section	5-3	Geometric properties of a partly filled circular shape based on area	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image29	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image29.png	hydraulics_ref_ch5_cross_section	5-7	A Shape Curve with a depth segment shown	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image30	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image30.png	hydraulics_ref_ch5_cross_section	5-8	A natural channel transect	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image31	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image31.png	hydraulics_ref_ch5_cross_section	5-9	A transect depth increment with three compound segments	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image37	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image37.png	hydraulics_ref_ch5_cross_section	5-11	Example of a storage curve and its section view	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image38	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image38.png	hydraulics_ref_ch5_cross_section	5-11	Example of a storage curve and its section view	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image39	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image39.png	hydraulics_ref_ch5_cross_section	5-12	Finding the volume at a given depth for a storage curve	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image4	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image4.png	hydraulics_ref_ch1_overview	1-4	Block diagram of SWMM's state transition process	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image49	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image49.png	hydraulics_ref_ch6_pumps_regulators	6-4	Transverse weir shapes	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image5	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image5.png	hydraulics_ref_ch1_overview	1-5	Flow chart of SWMM's simulation procedure	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image50	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image50.png	hydraulics_ref_ch6_pumps_regulators	6-5	Coefficient for triangular weirs (from Brater and King, 1976)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image51	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image51.png	hydraulics_ref_ch6_pumps_regulators	6-6	Definitions of submerged and surcharged weir flow	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image52	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image52.png	hydraulics_ref_ch6_pumps_regulators	6-7	Rating curve for a vortex device compared to an orifice	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image8	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image8.png	hydraulics_ref_ch2_hydraulic_model	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_hydraulics_image9	legacy	-	-	manuals/reference/hydraulics/media/media/hydraulics-image9.png	hydraulics_ref_ch2_hydraulic_model	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image45	legacy	-	-	manuals/reference/hydraulics/media/media/image45.png	hydraulics_ref_ch6_pumps_regulators	6-1	Orifice orientations	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image46	legacy	-	-	manuals/reference/hydraulics/media/media/image46.png	hydraulics_ref_ch6_pumps_regulators	6-2	Determination of effective head for an orifice	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image47	legacy	-	-	manuals/reference/hydraulics/media/media/image47.png	hydraulics_ref_ch6_pumps_regulators	6-2	Determination of effective head for an orifice	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image48	legacy	-	-	manuals/reference/hydraulics/media/media/image48.png	hydraulics_ref_ch6_pumps_regulators	6-3	Orifice with unsubmerged inlet	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image53	legacy	-	-	manuals/reference/hydraulics/media/media/image53.png	hydraulics_ref_ch7_advanced_features	7-1	Depths used for computing seepage in storage units	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image54	legacy	-	-	manuals/reference/hydraulics/media/media/image54.png	hydraulics_ref_ch7_advanced_features	7-2	Concrete box culvert (from FHWA, 2012)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image55	legacy	-	-	manuals/reference/hydraulics/media/media/image55.png	hydraulics_ref_ch7_advanced_features	7-3	Example of a culvert rating curve (from FHWA, 2012)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image56	legacy	-	-	manuals/reference/hydraulics/media/media/image56.png	hydraulics_ref_ch7_advanced_features	7-4	Roadway overtopping (from FHWA, 2012)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image57	legacy	-	-	manuals/reference/hydraulics/media/media/image57.png	hydraulics_ref_ch7_advanced_features	7-5	SWMM node-link representation of a culvert with a roadway weir	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image58	legacy	-	-	manuals/reference/hydraulics/media/media/image58.png	hydraulics_ref_ch7_advanced_features	7-6	Discharge coefficients for roadway weirs (from FHWA, 2012)	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image59	legacy	-	-	manuals/reference/hydraulics/media/media/image59.png	hydraulics_ref_ch7_advanced_features	7-7	Examples of storm drain inlets	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image60	legacy	-	-	manuals/reference/hydraulics/media/media/image60.png	hydraulics_ref_ch7_advanced_features	7-7	Examples of storm drain inlets	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image61	legacy	-	-	manuals/reference/hydraulics/media/media/image61.png	hydraulics_ref_ch7_advanced_features	7-8	Standard types of curb and gutter inlets	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image62	legacy	-	-	manuals/reference/hydraulics/media/media/image62.png	hydraulics_ref_ch7_advanced_features	7-9	Performance curve for a custom inlet	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image63	legacy	-	-	manuals/reference/hydraulics/media/media/image63.png	hydraulics_ref_ch7_advanced_features	7-10	Representation of a dual drainage system	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image64	legacy	-	-	manuals/reference/hydraulics/media/media/image64.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image67	legacy	-	-	manuals/reference/hydraulics/media/media/image67.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image68	legacy	-	-	manuals/reference/hydraulics/media/media/image68.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image69	legacy	-	-	manuals/reference/hydraulics/media/media/image69.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image7	legacy	-	-	manuals/reference/hydraulics/media/media/image7.jpg	hydraulics_ref_ch2_hydraulic_model	2-1	Node-link representation of a sewer system	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image70	legacy	-	-	manuals/reference/hydraulics/media/media/image70.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image72	legacy	-	-	manuals/reference/hydraulics/media/media/image72.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image73	legacy	-	-	manuals/reference/hydraulics/media/media/image73.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image74	legacy	-	-	manuals/reference/hydraulics/media/media/image74.png	hydraulics_ref_ch7_advanced_features	-	-	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydraulics_image75	legacy	-	-	manuals/reference/hydraulics/media/media/image75.png	hydraulics_ref_ch7_advanced_features	7-12	Types of channel drop inlets	EPA SWMM 5 Reference Manual Vol. II Hydraulics (2021), pandoc export
+hydrology_ch3_nonlinear_reservoir	synthetic	src/hydrology/ch3_nonlinear_reservoir.py	-	figures/png/hydrology_ch3_nonlinear_reservoir.png	engine_manual_ch1_conceptual_model;hydrology_ref_ch3_surface_runoff	3-2	Nonlinear reservoir model of a subcatchment	-
+hydrology_ch4_green_ampt_curve	synthetic	src/hydrology/ch4_infiltration_curves.py	-	figures/png/hydrology_ch4_green_ampt_curve.png	hydrology_ref_ch4_infiltration	4-6	Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method	-
+hydrology_ch4_green_ampt_recovery_params	synthetic	src/hydrology/ch4_infiltration_curves.py	-	figures/png/hydrology_ch4_green_ampt_recovery_params.png	hydrology_ref_ch4_infiltration	4-7	Green-Ampt recovery parameters as functions of hydraulic conductivity	-
+hydrology_ch4_horton_cumulative	synthetic	src/hydrology/ch4_infiltration_curves.py	-	figures/png/hydrology_ch4_horton_cumulative.png	hydrology_ref_ch4_infiltration	4-3	Cumulative infiltration F as the area under the Horton curve	-
+hydrology_ch4_horton_curve	synthetic	src/hydrology/ch4_infiltration_curves.py	-	figures/png/hydrology_ch4_horton_curve.png	hydrology_ref_ch4_infiltration	4-2	The Horton infiltration curve	-
+hydrology_ch4_horton_recovery	synthetic	src/hydrology/ch4_infiltration_curves.py	-	figures/png/hydrology_ch4_horton_recovery.png	hydrology_ref_ch4_infiltration	4-4	Regeneration (recovery) of infiltration capacity during dry time steps	-
+hydrology_ch5_lateral_flow_heights	synthetic	src/hydrology/ch5_two_zone_column.py	-	figures/png/hydrology_ch5_lateral_flow_heights.png	hydrology_ref_ch5_groundwater	5-2	Heights used to compute lateral groundwater flow rate	-
+hydrology_ch5_two_zone	synthetic	src/hydrology/ch5_two_zone_column.py	-	figures/png/hydrology_ch5_two_zone.png	engine_manual_ch1_conceptual_model;hydrology_ref_ch5_groundwater	5-1	Definitional sketch of the two-zone groundwater model	-
+hydrology_ch6_areal_depletion_curve	synthetic	src/hydrology/ch6_adc_curves.py	-	figures/png/hydrology_ch6_areal_depletion_curve.png	engine_manual_ch1_conceptual_model;hydrology_ref_ch6_snowmelt	6-4	Typical areal depletion curve for natural area and temporary curve for new snow	-
+hydrology_ch7_ia_seasonal	synthetic	src/hydrology/ch7_ia_seasonal.py	-	figures/png/hydrology_ch7_ia_seasonal.png	hydrology_ref_ch7_rdii	7-11	Seasonal behaviour of the exponential-decay initial abstraction model	-
+hydrology_ch7_rtk_unit_hydrographs	synthetic	src/hydrology/ch7_rtk_unit_hydrograph.py	-	figures/png/hydrology_ch7_rtk_unit_hydrographs.png	hydrology_ref_ch7_rdii	7-4	Use of three unit hydrographs to represent RDII	-
+hydrology_ch8_cell_budget	synthetic	src/hydrology/ch8_cell_budget.py	-	figures/png/hydrology_ch8_cell_budget.png	hydrology_ref_ch8_mesh_surface	8-1	The water balance of one mesh cell: rainfall, evaporation, infiltration, network exchange and the lateral face fluxes	-
+hydrology_ch8_infiltration_strip	synthetic	src/hydrology/ch8_infiltration_strip.py	-	figures/png/hydrology_ch8_infiltration_strip.png	hydrology_ref_ch8_mesh_surface	8-3	Per-cell infiltration: how a cell resolves its method and parameters, and the rate held across an infiltration step	-
+hydrology_ch8_nn_weights	synthetic	src/hydrology/ch8_nn_weights.py	-	figures/png/hydrology_ch8_nn_weights.png	hydrology_ref_ch8_mesh_surface	8-2	Natural-neighbour rainfall weights inside the gage hull, and inverse-distance weighting outside it	-
+hydrology_ch9_node_bed_exchange	synthetic	src/hydrology/ch9_node_bed_exchange.py	-	figures/png/hydrology_ch9_node_bed_exchange.png	hydrology_ref_ch9_mesh_groundwater	9-3	Node-aquifer exchange through a semi-confining bed, in both directions, with the caps that bound it	-
+hydrology_ch9_soil_characteristics	synthetic	src/hydrology/ch9_soil_characteristics.py	-	figures/png/hydrology_ch9_soil_characteristics.png	hydrology_ref_ch9_mesh_groundwater	9-2	Retention and relative conductivity of the four soil-characteristic laws at their default parameters	-
+hydrology_ch9_two_layer_column	synthetic	src/hydrology/ch9_two_layer_column.py	-	figures/png/hydrology_ch9_two_layer_column.png	hydrology_ref_ch9_mesh_groundwater	9-1	One aquifer column and its fluxes, with the unsaturated zone held as a bulk store (closure A) and as sigma layers (closure B)	-
+hydrology_conceptual_map	synthetic	src/engine/conceptual_map.py	-	figures/png/hydrology_conceptual_map.png	hydrology_ref_ch1_overview	1-7	The hydrology of this manual: atmosphere, land surface and subsurface representations	-
+hydrology_figure1_4	legacy	-	-	manuals/reference/hydrology/media/media/figure1-4.png	hydrology_ref_ch1_overview	1-4	Block diagram of SWMM's state transition process	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure1_5	legacy	-	-	manuals/reference/hydrology/media/media/figure1-5.png	hydrology_ref_ch1_overview	1-5	Flow chart of SWMM's simulation procedure	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure3_1	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-1.png	hydrology_ref_ch3_surface_runoff	3-1	Idealized representation of a subcatchment	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export; the same image is embedded again as Figure 3-8 (Chapter3-SurfaceRunoff.md), the former duplicate Figure3-8.png
+hydrology_figure3_12	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-12.png	hydrology_ref_ch3_surface_runoff	3-12	Runoff results for illustrative example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure3_13	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-13.png	hydrology_ref_ch3_surface_runoff	3-13	SCS (NRCS) triangular unit hydrograph (NRCS, 2007)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure3_4	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-4.png	hydrology_ref_ch3_surface_runoff	3-4	Idealized subcatchment partitioning for overland flow	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure3_5	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-5.png	hydrology_ref_ch3_surface_runoff	3-5	Re-routing of overland flow (Huber, 2001)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure3_9	legacy	-	-	manuals/reference/hydrology/media/media/Figure3-9.png	hydrology_ref_ch3_surface_runoff	3-9	Rectangular subcatchments for illustration of shape and width effects	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure4_5	legacy	-	-	manuals/reference/hydrology/media/media/figure4-5.png	hydrology_ref_ch4_infiltration	4-5	Two-zone representation of the Green-Ampt infiltration model (after Nicklow et al., 2006)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure5_9	legacy	-	-	manuals/reference/hydrology/media/media/figure5-9.png	hydrology_ref_ch5_groundwater	5-9	Surface runoff and groundwater flow for the illustrative groundwater example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure6_10	legacy	-	-	manuals/reference/hydrology/media/media/Figure6-10.png	hydrology_ref_ch6_snowmelt	6-10	Runoff time series for illustrative snowmelt example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure6_2	legacy	-	-	manuals/reference/hydrology/media/media/Figure6-2.png	hydrology_ref_ch6_snowmelt	6-2	Subcatchment partitionings used for snowmelt and runoff	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure6_7	legacy	-	-	manuals/reference/hydrology/media/media/Figure6-7.png	hydrology_ref_ch6_snowmelt	6-7	Continuous air temperature for illustrative snowmelt example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure6_8	legacy	-	-	manuals/reference/hydrology/media/media/Figure6-8.png	hydrology_ref_ch6_snowmelt	6-8	Precipitation amounts for illustrative snowmelt example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure6_9	legacy	-	-	manuals/reference/hydrology/media/media/Figure6-9.png	hydrology_ref_ch6_snowmelt	6-9	Snow pack depth for illustrative snowmelt example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure7_1	legacy	-	-	manuals/reference/hydrology/media/media/Figure7-1.png	hydrology_ref_ch7_rdii	7-1	Components of wet-weather wastewater flow	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure7_2	legacy	-	-	manuals/reference/hydrology/media/media/Figure7-2.png	hydrology_ref_ch7_rdii	7-2	Example of an RDII triangular unit hydrograph	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure7_3	legacy	-	-	manuals/reference/hydrology/media/media/Figure7-3.png	hydrology_ref_ch7_rdii	7-3	Application of a unit hydrograph to a storm event	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure7_8	legacy	-	-	manuals/reference/hydrology/media/media/Figure7-8.png	hydrology_ref_ch7_rdii	7-8	Unit hydrographs used for the illustrative RDII example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_figure7_9	legacy	-	-	manuals/reference/hydrology/media/media/Figure7-9.png	hydrology_ref_ch7_rdii	7-9	Time series of RDII flows for the illustrative RDII example	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_figure1_6	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-figure1-6.png	hydrology_ref_ch1_overview	1-6	Interpolation of reported values from computed values	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image1	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image1.jpeg	hydrology_ref_ch1_overview	1-1	Elements of a typical urban drainage system	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image10	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image10.jpg	hydrology_ref_ch3_surface_runoff	3-6	Fisk B catchment, Portland, Oregon (Portland BES, 1996)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export; converted PNG->JPEG q82 at 1400 px 2026-09-19 (aerial photograph)
+hydrology_hydrology_image11	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image11.png	hydrology_ref_ch3_surface_runoff	3-7	Detailed view of two Fisk B subcatchments (Portland BES, 1996)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image12	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image12.png	hydrology_ref_ch3_surface_runoff	3-10	Subcatchment hydrographs for different shapes of Figure 3-9	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image13	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image13.png	hydrology_ref_ch3_surface_runoff	3-11	Irregular subcatchment shape for width calculations (DiGiano et al., 1977, p. 165)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image15	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image15.png	hydrology_ref_ch4_infiltration	4-1	Physical properties for Woodburn silt loam, Benton County, Oregon	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image24	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image24.png	hydrology_ref_ch4_infiltration	4-8	Infiltration rates produced by different methods for a 2-inch rainfall event	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image29	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image29.png	hydrology_ref_ch5_groundwater	5-3	Relation between soil moisture limits and soil texture class (Schroeder et al., 1994)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image30	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image30.png	hydrology_ref_ch5_groundwater	5-4	SPAW's soil water characteristics calculator	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image31	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image31.png	hydrology_ref_ch5_groundwater	-	-	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image32	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image32.png	hydrology_ref_ch5_groundwater	5-5	Measured hydraulic conductivity for three soils	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image33	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image33.png	hydrology_ref_ch5_groundwater	5-5	Measured hydraulic conductivity for three soils	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image34	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image34.png	hydrology_ref_ch5_groundwater	5-6	Fitting SWMM's hydraulic conductivity equation to a power law equation	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image35	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image35.png	hydrology_ref_ch5_groundwater	5-7	Definition sketch for Dupuit-Forcheimer seepage to an adjacent channel	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image36	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image36.png	hydrology_ref_ch5_groundwater	5-8	Definition sketch for Hooghoudt's method for flow to circular drains	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image37	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image37.png	hydrology_ref_ch6_snowmelt	6-1	Typical gage catch deficiency correction (Anderson, 2006, p. 8)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image38	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image38.png	hydrology_ref_ch6_snowmelt	6-3	Seasonal variation of melt coefficients	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image4	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image4.png	hydrology_ref_ch2_meteorology	2-1	Sinusoidal interpolation of hourly temperatures	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image41	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image41.png	hydrology_ref_ch6_snowmelt	6-5	Effect of snow cover on areal depletion curves	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image43	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image43.png	hydrology_ref_ch6_snowmelt	6-6	Schematic of liquid water routing through snow pack	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image50	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image50.png	hydrology_ref_ch7_rdii	7-5	Sewershed delineation (Vallabhaneni et al., 2007)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image51	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image51.png	hydrology_ref_ch7_rdii	7-6	Extracting RDII flow from a continuous flow monitor (Vallabhaneni et al., 2007)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image52	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image52.png	hydrology_ref_ch7_rdii	7-7	Fitting unit hydrographs to an RDII flow record (Vallabhaneni et al., 2007)	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+hydrology_hydrology_image8	legacy	-	-	manuals/reference/hydrology/media/media/hydrology-image8.png	hydrology_ref_ch3_surface_runoff	3-3	Types of subareas within a subcatchment	EPA SWMM 5 Reference Manual Vol. I Hydrology (2015), pandoc export
+quality_ch10_cell_buildup_washoff	synthetic	src/quality/ch10_cell_buildup_washoff.py	-	figures/png/quality_ch10_cell_buildup_washoff.png	quality_ref_ch10_mesh_quality	10-2	Buildup and washoff on one mesh cell: land-use slices, accrual, sweeping and the mass handed to the network	-
+quality_ch10_transport_policy	synthetic	src/quality/ch10_transport_policy.py	-	figures/png/quality_ch10_transport_policy.png	quality_ref_ch10_mesh_quality	10-1	The transport policy matrix: which species class moves in which domain, and the gate ladder the 2D surface passes	-
+quality_ch6_lid_bio_cell	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_bio_cell.png	quality_ref_ch6_lid_controls	-	Bio-retention cell layer stack	-
+quality_ch6_lid_block_paver	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_block_paver.png	quality_ref_ch6_lid_controls	-	Block paver layer stack	-
+quality_ch6_lid_green_roof	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_green_roof.png	quality_ref_ch6_lid_controls	-	Green roof layer stack	-
+quality_ch6_lid_infiltration_trench	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_infiltration_trench.png	quality_ref_ch6_lid_controls	-	Infiltration trench layer stack	-
+quality_ch6_lid_permeable_pavement	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_permeable_pavement.png	quality_ref_ch6_lid_controls	-	Continuous permeable pavement layer stack	-
+quality_ch6_lid_rain_barrel	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_rain_barrel.png	quality_ref_ch6_lid_controls	-	Rain barrel layer stack	-
+quality_ch6_lid_rain_garden	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_rain_garden.png	quality_ref_ch6_lid_controls	-	Rain garden layer stack	-
+quality_ch6_lid_rooftop_disconnection	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_rooftop_disconnection.png	quality_ref_ch6_lid_controls	-	Rooftop disconnection layer stack	-
+quality_ch6_lid_vegetative_swale	synthetic	src/quality/ch6_lid_stacks.py	-	figures/png/quality_ch6_lid_vegetative_swale.png	quality_ref_ch6_lid_controls	-	Vegetative swale layer stack	-
+quality_ch7_ard_stencil	synthetic	src/quality/ch7_ard_stencil.py	-	figures/png/quality_ch7_ard_stencil.png	quality_ref_ch7_ard_transport	7-1	Flux-limited advection in the Eulerian engine: the face stencil and a step front under UPWIND and the three MUSCL limiters	-
+quality_ch7_lard_parcels	synthetic	src/quality/ch7_lard_parcels.py	-	figures/png/quality_ch7_lard_parcels.png	quality_ref_ch7_ard_transport	7-2	The five phases of a Lagrangian transport step: drain, mix, release, decay and publish on one conduit's parcel slab	-
+quality_ch9_heat_budget	synthetic	src/quality/ch9_heat_budget.py	-	figures/png/quality_ch9_heat_budget.png	quality_ref_ch9_age_heat	9-1	The heat budget of a water body: the six surface terms of the net flux by module, and the bed zone's conduction and hyporheic exchange	-
+quality_conceptual_map	synthetic	src/engine/conceptual_map.py	-	figures/png/quality_conceptual_map.png	quality_ref_ch1_overview	1-7	The water quality of this manual: buildup, washoff, transport and reactions across the compartments	-
+quality_figure2_1	legacy	-	-	manuals/reference/quality/media/media/figure2-1.png	quality_ref_ch2_urban_runoff_quality	2-1	Hourly domestic sewage time patterns	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_image19	legacy	-	-	manuals/reference/quality/media/media/image19.png	quality_ref_ch5_transport_treatment	5-2	Comparison of completely mixed reactor equations for time varying inflow	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_figure1_6	legacy	-	-	manuals/reference/quality/media/media/quality-figure1-6.png	quality_ref_ch1_overview	1-6	Interpolation of reported values from computed values	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image1	legacy	-	-	manuals/reference/quality/media/media/quality-image1.jpeg	quality_ref_ch1_overview	1-1	Elements of a typical urban drainage system	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image10	legacy	-	-	manuals/reference/quality/media/media/quality-image10.png	quality_ref_ch3_pollutant_buildup	3-3	Comparison of buildup equations for a hypothetical pollutant	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image11	legacy	-	-	manuals/reference/quality/media/media/quality-image11.png	quality_ref_ch3_pollutant_buildup	3-4	Evolution of buildup after a storm event	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image12	legacy	-	-	manuals/reference/quality/media/media/quality-image12.png	quality_ref_ch4_surface_washoff	4-1	Washoff of street solids by flushing with a sprinkler system (from Sartor and Boyd, 1972)	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image13	legacy	-	-	manuals/reference/quality/media/media/quality-image13.png	quality_ref_ch4_surface_washoff	4-2	Comparison of washoff functions	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image14	legacy	-	-	manuals/reference/quality/media/media/quality-image14.png	quality_ref_ch4_surface_washoff	4-3	Two-stream approach to modeling pollutant washoff	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image15	legacy	-	-	manuals/reference/quality/media/media/quality-image15.png	quality_ref_ch4_surface_washoff	4-4	Simulated load variations within a storm as a function of runoff rate	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image16	legacy	-	-	manuals/reference/quality/media/media/quality-image16.png	quality_ref_ch4_surface_washoff	4-4	Simulated load variations within a storm as a function of runoff rate	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image17	legacy	-	-	manuals/reference/quality/media/media/quality-image17.png	quality_ref_ch4_surface_washoff	4-4	Simulated load variations within a storm as a function of runoff rate	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image18	legacy	-	-	manuals/reference/quality/media/media/quality-image18.png	quality_ref_ch4_surface_washoff	4-4	Simulated load variations within a storm as a function of runoff rate	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image2	legacy	-	-	manuals/reference/quality/media/media/quality-image2.png	quality_ref_ch5_transport_treatment	5-1	Representation of the conveyance network in SWMM	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image20	legacy	-	-	manuals/reference/quality/media/media/quality-image20.png	quality_ref_ch5_transport_treatment	5-3	Comparison of completely mixed reactor equations for a step inflow	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image21	legacy	-	-	manuals/reference/quality/media/media/quality-image21.png	quality_ref_ch5_transport_treatment	5-4	Gravity settling treatment of TSS within a detention pond	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image31	legacy	-	-	manuals/reference/quality/media/media/quality-image31.png	quality_ref_ch6_lid_controls	6-1	A typical bio-retention cell	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image32	legacy	-	-	manuals/reference/quality/media/media/quality-image32.png	quality_ref_ch6_lid_controls	6-1	A typical bio-retention cell	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image33	legacy	-	-	manuals/reference/quality/media/media/quality-image33.png	quality_ref_ch6_lid_controls	6-2	Flow path across the surface of a green roof	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image34	legacy	-	-	manuals/reference/quality/media/media/quality-image34.png	quality_ref_ch6_lid_controls	6-3	Representation of a permeable pavement system	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image35	legacy	-	-	manuals/reference/quality/media/media/quality-image35.png	quality_ref_ch6_lid_controls	6-4	Representation of rooftop disconnection	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image36	legacy	-	-	manuals/reference/quality/media/media/quality-image36.png	quality_ref_ch6_lid_controls	6-5	Representation of a vegetative swale	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image37	legacy	-	-	manuals/reference/quality/media/media/quality-image37.png	quality_ref_ch6_lid_controls	6-6	Different options for placing LID controls	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image38	legacy	-	-	manuals/reference/quality/media/media/quality-image38.png	quality_ref_ch6_lid_controls	6-7	Storm event used for the LID example	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image39	legacy	-	-	manuals/reference/quality/media/media/quality-image39.png	quality_ref_ch6_lid_controls	6-8	Flux rates through the bio-retention cell with no underdrain	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image4	legacy	-	-	manuals/reference/quality/media/media/quality-image4.png	quality_ref_ch1_overview	1-4	Block diagram of SWMM's state transition process	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image40	legacy	-	-	manuals/reference/quality/media/media/quality-image40.png	quality_ref_ch6_lid_controls	6-9	Moisture levels in the bio-retention cell with no underdrain	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image41	legacy	-	-	manuals/reference/quality/media/media/quality-image41.png	quality_ref_ch6_lid_controls	6-10	Moisture levels in the bio-retention cell with underdrain	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image42	legacy	-	-	manuals/reference/quality/media/media/quality-image42.png	quality_ref_ch6_lid_controls	6-11	Flux rates through the bio-retention cell with underdrain	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image5	legacy	-	-	manuals/reference/quality/media/media/quality-image5.png	quality_ref_ch1_overview	1-5	Flow chart of SWMM's simulation procedure	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image8	legacy	-	-	manuals/reference/quality/media/media/quality-image8.png	quality_ref_ch3_pollutant_buildup	3-1	Accumulation of solids on urban streets versus time (Sartor and Boyd, 1972)	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+quality_quality_image9	legacy	-	-	manuals/reference/quality/media/media/quality-image9.png	quality_ref_ch3_pollutant_buildup	3-2	Buildup of street solids in San Jose (from Pitt, 1979)	EPA SWMM 5 Reference Manual Vol. III Water Quality (2016), pandoc export
+workflow_ch10_heat_diurnal	simulated	src/workflows/ch9_msx_and_age_heat.py	decks/transport_demo/transport_demo.inp	figures/png/workflow_ch10_heat_diurnal.png	application_manual_ch10_age_heat	10-2	Water temperature along the line against the air temperature driving it	-
+workflow_ch10_water_age_along_line	simulated	src/workflows/ch9_msx_and_age_heat.py	decks/transport_demo/transport_demo.inp	figures/png/workflow_ch10_water_age_along_line.png	application_manual_ch10_age_heat	10-1	Water age along the line as the initial water is flushed out, and the travel-time profile it leaves	-
+workflow_ch11_rdii_decay_vs_linear	simulated	src/workflows/ch11_rdii_decay.py	decks/hydrology_additions/rdii_decay.inp	figures/png/workflow_ch11_rdii_decay_vs_linear.png	application_manual_ch11_hydrology	11-1	Two identical storms through one RTK group, with and without a physics-based recovery	-
+workflow_ch2_rapid_fill_front	simulated	src/workflows/ch2_rapid_fill.py	decks/rapid_fill/rapid_fill.inp	figures/png/workflow_ch2_rapid_fill_front.png	application_manual_ch2_filling_pipe	2-2	Velocity at the transducer and surge-tank level, measured and under the same three choices	-
+workflow_ch2_rapid_fill_pressure_9p9	simulated	src/workflows/ch2_rapid_fill.py	decks/rapid_fill/rapid_fill.inp	figures/png/workflow_ch2_rapid_fill_pressure_9p9.png	application_manual_ch2_filling_pipe	2-1	Pressure head at x = 9.9 m in the rapid-filling experiment, measured and under three routing choices	-
+workflow_ch3_negative_pressure_head_14p1	simulated	src/workflows/ch3_negative_pressure.py	decks/negative_pressure/negative_pressure.inp	figures/png/workflow_ch3_negative_pressure_head_14p1.png	application_manual_ch3_subatmospheric	3-1	Piezometric head at x = 14.1 m and velocity at x = 9.9 m in the siphon experiment, under both closures on both routers	-
+workflow_ch3_velocity_9p9	simulated	src/workflows/ch3_negative_pressure.py	decks/negative_pressure/negative_pressure.inp	figures/png/workflow_ch3_velocity_9p9.png	application_manual_ch3_subatmospheric	3-2	The same four runs at the velocity transducer, where the closures diverge after the drawdown	-
+workflow_ch4_cedar_glen_profile_hgl	simulated	src/workflows/ch4_virtual_junctions.py	decks/cedar_glen/cedar_glen_fv.inp;decks/cedar_glen/cedar_glen_dw.inp;decks/cedar_glen/cedar_glen_dw_extran.inp	figures/png/workflow_ch4_cedar_glen_profile_hgl.png	application_manual_ch4_virtual_junctions	4-1	The hydraulic grade line along a trunk chained by virtual junctions, under three routings	-
+workflow_ch4_cedar_glen_worst_node_head	simulated	src/workflows/ch4_virtual_junctions.py	decks/cedar_glen/cedar_glen_fv.inp;decks/cedar_glen/cedar_glen_dw.inp;decks/cedar_glen/cedar_glen_dw_extran.inp	figures/png/workflow_ch4_cedar_glen_worst_node_head.png	application_manual_ch4_virtual_junctions	4-2	Head at the node where the three routings disagree most, with each run's cost	-
+workflow_ch5_inlet_capture_vs_bypass	simulated	src/workflows/ch5_street_inlets.py	decks/street_inlets/street_inlet_junction.inp	figures/png/workflow_ch5_inlet_capture_vs_bypass.png	application_manual_ch5_street_inlets	5-1	Capture and bypass along a street reach with a conduit-attribute inlet and an inlet junction	-
+workflow_ch6_mesh_and_coupling	simulated	src/workflows/ch6_coupled_1d2d.py	decks/coupled_1d2d/2d_complete_example.inp	figures/png/workflow_ch6_mesh_and_coupling.png	application_manual_ch6_coupled_1d2d	6-1	The example mesh: bed elevation, the five boundary-condition types and both kinds of coupling point	-
+workflow_ch6_momentum_closures_depth	simulated	src/workflows/ch6_coupled_1d2d.py	decks/coupled_1d2d/2d_complete_example.inp	figures/png/workflow_ch6_momentum_closures_depth.png	application_manual_ch6_coupled_1d2d	6-2	One cell's depth history under the three momentum closures	-
+workflow_ch7_rain_and_infiltration	simulated	src/workflows/ch7_mesh_hydrology.py	decks/mesh_hydrology/mesh_hydrology.inp	figures/png/workflow_ch7_rain_and_infiltration.png	application_manual_ch7_mesh_hydrology	7-1	Interpolated rainfall and infiltrated depth on each cell of a meshed patch of ground	-
+workflow_ch8_ard_dx_sensitivity	simulated	src/workflows/ch8_transport_engines.py	decks/transport_demo/transport_demo.inp	figures/png/workflow_ch8_ard_dx_sensitivity.png	application_manual_ch8_transport_engines	8-2	The same front under the Eulerian engine at three cell sizes, and what each costs	-
+workflow_ch8_tracer_breakthrough_three_engines	simulated	src/workflows/ch8_transport_engines.py	decks/transport_demo/transport_demo.inp	figures/png/workflow_ch8_tracer_breakthrough_three_engines.png	application_manual_ch8_transport_engines	8-1	A step of conservative tracer at the downstream junction under the three transport engines	-
+workflow_ch9_arrhenius_rate_from_temperature	simulated	src/workflows/ch9_msx_and_age_heat.py	decks/transport_demo/transport_demo.inp	figures/png/workflow_ch9_arrhenius_rate_from_temperature.png	application_manual_ch9_msx	9-1	What the computed water temperature does to a reaction system's rate, through the Arrhenius correction in its expression	-
diff --git a/docs/figures/README.md b/docs/figures/README.md
new file mode 100644
index 000000000..ad86d185e
--- /dev/null
+++ b/docs/figures/README.md
@@ -0,0 +1,134 @@
+# Manual figures
+
+Every image any manual embeds has one row in `MANIFEST.tsv`, and every
+generated figure has a generator module here that can rebuild it. The audit
+(`scripts/build_manual_figures.py check`) is part of the manual lint and runs
+in CI; the generators run locally and their outputs are committed.
+
+```
+docs/figures/
+  MANIFEST.tsv        one row per embedded image (column contract: scripts/build_manual_figures.py)
+  status.py           feature -> Implemented | Experimental | Planned | Retired, with colours
+  style.py            vendored house style (palette, chrome, DPI)
+  src//*.py   generators: REQUIRES = (...); def build(sink)
+  decks//       small in-tree models for the simulated tier (+ provenance.md)
+  png/  svg/          committed outputs (PNG is embedded; SVG is for the paper)
+  cache/              git-ignored engine runs
+```
+
+## Tiers
+
+| tier | means | generator | committed output |
+|---|---|---|---|
+| `synthetic` | numpy/matplotlib only; may `REQUIRES = ("openswmm",)` for geometry | required | `png/.png` + `svg/.svg` |
+| `simulated` | runs an in-tree deck under `decks/` through the engine first | required | same |
+| `external` | image whose generator or data cannot live in-tree (e.g. the Bellinge hero) | `-` | the image, with `provenance` filled |
+| `legacy` | EPA or hand-drawn figure kept as-is | `-` | the image, in its manual's media directory |
+
+## Writing a generator
+
+```python
+REQUIRES = ()                        # ("openswmm",) when the engine's Python package is needed
+
+def build(sink):
+    import style, status             # docs/figures is on sys.path during build
+    fig = style.figure(8, 4.5)
+    ...
+    sink.save(fig, "hydraulics_ch8_hll_fan")          # one call per manifest row this module owns
+```
+
+`sink.run("negative_pressure/negative_pressure.inp", options={"FV_PRESSURE_CLOSURE": "TPA"})`
+runs a deck through the engine CLI (cached under `cache/`) and returns the
+`.inp/.rpt/.out/.h5` paths. A module may own several rows (the conceptual map
+owns five); the build fails if it produces more or fewer than the manifest lists.
+
+Naming: `fig_id` is `__` (`hydraulics_ch8_hll_fan`,
+`eng_conceptual_map`, `workflow_ch3_negative_pressure_head_14p1`). Embed it
+as `![Figure n-m caption](figures/png/.png)` followed by an italic
+`*Figure n-m caption*` line — the audit expects the figure number within five
+lines of the embed.
+
+## Commands
+
+```bash
+python3 scripts/build_manual_figures.py check                      # stdlib only; CI runs this
+python3 scripts/build_manual_figures.py list --manual hydraulics
+python  scripts/build_manual_figures.py build --tier synthetic     # needs matplotlib
+python  scripts/build_manual_figures.py build --tier simulated --cli install/Darwin/bin/openswmm
+python3 scripts/build_manual_figures.py run-decks --cli  # every simulated deck runs clean
+```
+
+Requirements for `build`: matplotlib ≥ 3.8 (which brings Pillow) and numpy;
+h5py for figures that read 2D output; the `openswmm` package for
+geometry-backed figures. The engine-run tier finds the CLI through `--cli`,
+`$OPENSWMM_BIN`, `$OPENSWMM_BUILD_DIR`, or a `build*/` / `install/*/` tree.
+
+## Determinism and bounds
+
+Outputs are committed. Re-running a generator on one machine is diff-free
+(metadata stripped, `svg.hashsalt` fixed, DejaVu Sans bundled with
+matplotlib); byte identity across matplotlib versions is **not** required and
+CI never compares pixels — it audits the manifest and proves the synthetic
+generators execute. PNGs are exported at DPI 160 and must stay within
+1600 px width and 400 KB; keep figure widths ≤ 10 in.
+
+## Interactive diagrams: hotspots and workflow links
+
+`docs/custom/js/manual-interactive.js` (shipped by the Doxyfile, loaded by
+`custom/html/header.html`) wraps two kinds of diagram in a pan/zoom
+viewport at page load — drag to pan, click the diagram then scroll (or hold
+Ctrl/⌘) to zoom, pinch on touch, double-click to reset, toolbar buttons —
+and makes their parts clickable. Both degrade to the static image or
+diagram without JavaScript.
+
+**Figure hotspots.** A generator registers clickable regions in data
+coordinates:
+
+```python
+sink.hotspot("eng_process_flow", ax, x0, y0, x1, y1, "hydraulics_ref_ch8_finite_volume", "finite volume")
+```
+
+`save()` converts each box to fractions of the saved PNG (top-left
+origin) and `build` writes, after the figure's caption on every page the
+manifest row lists, a block the script reads:
+
+```
+

+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+

+```
+
+The `@ref` is resolved by Doxygen (and validated by the lint), so a target
+that disappears fails the build rather than the click. Targets for the
+conceptual map, the process-flow chart and the object sketch come from
+`refs.py` (feature id or box title → page id or anchor); `primitives.pill_row`
+returns each pill's box through its `out=` list. `check` C13 asserts every
+block names a figure the page embeds and holds only well-formed spans;
+the blocks are hidden by `manual.css`. Never hand-edit a block — rebuild
+the figure.
+
+**Workflow links.** A Mermaid flowchart's nodes open a section when the
+block is followed *directly* by
+
+```
+
+
+@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping" +
+``` + +The script injects a Mermaid `click` directive per node before rendering +(the `` comment does not survive Doxygen, so adjacency +is the pairing). The lint's `check_mermaid_workflows` requires the id to +match, every node to exist in the diagram, and a flowchart (Mermaid has no +`click` on state diagrams). Point nodes at explicit heading anchors +(`### 8.5.6 Local time stepping {#hydraulics_ref_ch8_lts}`), never at the +auto-generated `autotoc_md` ids. + +## Why legacy files are prefixed with their manual + +Doxygen copies every image into one output directory by basename. The three +EPA reference manuals shipped with the same `imageNN.png` names for different +figures, so each page could be served another manual's figure. The migration +of 2026-09-19 renamed every colliding file `-` and the audit +(C12) now refuses duplicate basenames across `IMAGE_PATH` directories. diff --git a/docs/figures/decks/README.md b/docs/figures/decks/README.md new file mode 100644 index 000000000..0ae9da5ba --- /dev/null +++ b/docs/figures/decks/README.md @@ -0,0 +1,11 @@ +# Worked-example decks + +Small models the simulated-tier figures and the Application Manual run. +This directory is the Doxyfile's `EXAMPLE_PATH`, so chapters quote a deck's +lines verbatim with `\snippet ` between `;//! [marker]` pairs +instead of copying them into prose. + +Each deck lives in its own subdirectory with a `provenance.md` naming where it +came from (a study, an example, a benchmark case, or authored for the manual), +the commit or date, and what was changed. Keep decks runnable in minutes on +CPU; anything longer belongs to the `external` figure tier. diff --git a/docs/figures/decks/cedar_glen/cedar_glen_dw.inp b/docs/figures/decks/cedar_glen/cedar_glen_dw.inp new file mode 100644 index 000000000..f086f1618 --- /dev/null +++ b/docs/figures/decks/cedar_glen/cedar_glen_dw.inp @@ -0,0 +1,1667 @@ +[TITLE] +;;Cedar Glen to FRS -- synthetic conveyance demonstration +;;Generated by generate_model.py (seed 20260816); all data invented. + +[OPTIONS] +;;Option Value +FLOW_UNITS MGD +INFILTRATION HORTON +FLOW_ROUTING DYNWAVE +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING YES +SKIP_STEADY_STATE NO + +START_DATE 01/01/2026 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2026 +REPORT_START_TIME 00:00:00 +END_DATE 01/02/2026 +END_TIME 00:00:00 +REPORT_STEP 0:01:00 +WET_STEP 0:05:00 +DRY_STEP 1:00:00 +ROUTING_STEP 0:00:30 + +INERTIAL_DAMPING PARTIAL +NORMAL_FLOW_LIMITED BOTH +FORCE_MAIN_EQUATION H-W +SURCHARGE_METHOD SLOT +VARIABLE_STEP 0.75 +LENGTHENING_STEP 0 +MIN_SURFAREA 0 +MAX_TRIALS 8 +HEAD_TOLERANCE 0.005 +SYS_FLOW_TOL 5 +LAT_FLOW_TOL 5 +MINIMUM_STEP 0.5 + +FV_LTS YES +FV_LTS_MAX_TIERS 4 + + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +TU0000000 468.0000 0.0000 0.0000 40.0000 0.0000 +TU0002672 459.9837 0.0000 0.0000 40.0000 0.0000 +TU0005213 452.3601 0.0000 0.0000 40.0000 0.0000 +TU0007917 447.0146 0.0000 0.0000 40.0000 0.0000 +TU0009817 443.5949 0.0000 0.0000 40.0000 0.0000 +TM0002713 452.3498 0.0000 0.0000 40.0000 0.0000 +TM0005252 442.7143 0.0000 0.0000 40.0000 0.0000 +TM0007238 442.6854 0.0000 0.0000 40.0000 0.0000 +TL0002658 436.8368 0.0000 0.0000 40.0000 0.0000 +TL0005207 430.5798 0.0000 0.0000 40.0000 0.0000 +TL0007853 423.1725 0.0000 0.0000 40.0000 0.0000 +BA0000000 479.1635 0.0000 0.0000 40.0000 0.0000 +BA0002678 463.0955 0.0000 0.0000 40.0000 0.0000 +BA0005279 451.0498 0.0000 0.0000 40.0000 0.0000 +BB0000000 469.8142 0.0000 0.0000 40.0000 0.0000 +BB0002622 455.3955 0.0000 0.0000 40.0000 0.0000 +BB0005220 444.0169 0.0000 0.0000 40.0000 0.0000 + +[VIRTUAL_JUNCTIONS] +;;Name Elev Rim +TU0000124 467.6278 11.0000 +TU0000243 467.2712 11.0000 +TU0000340 466.9790 11.0000 +TU0000435 466.6961 11.0000 +TU0000560 466.3192 11.0000 +TU0000624 466.1265 11.0000 +TU0000722 465.8332 11.0000 +TU0000835 465.4957 11.0000 +TU0000940 465.1792 11.0000 +TU0001043 464.8695 11.0000 +TU0001128 464.6167 11.0000 +TU0001211 464.3666 11.0000 +TU0001310 464.0714 11.0000 +TU0001388 463.8351 11.0000 +TU0001514 463.4592 11.0000 +TU0001586 463.2412 11.0000 +TU0001670 462.9900 11.0000 +TU0001788 462.6370 11.0000 +TU0001904 462.2882 11.0000 +TU0001982 462.0545 11.0000 +TU0002056 461.8319 11.0000 +TU0002136 461.5911 11.0000 +TU0002196 461.4109 11.0000 +TU0002329 461.0126 11.0000 +TU0002403 460.7906 11.0000 +TU0002542 460.3733 11.0000 +TU0002811 459.5681 11.0000 +TU0002907 459.2792 11.0000 +TU0003035 458.8960 11.0000 +TU0003158 458.5271 11.0000 +TU0003232 458.3033 11.0000 +TU0003306 458.0835 11.0000 +TU0003428 457.7166 11.0000 +TU0003502 457.4948 11.0000 +TU0003572 457.2839 11.0000 +TU0003633 457.1010 11.0000 +TU0003725 456.8251 11.0000 +TU0003860 456.4194 11.0000 +TU0003925 456.2246 11.0000 +TU0004028 455.9175 11.0000 +TU0004125 455.6251 11.0000 +TU0004230 455.3086 11.0000 +TU0004296 455.1128 11.0000 +TU0004396 454.8127 11.0000 +TU0004532 454.4055 11.0000 +TU0004635 454.0938 11.0000 +TU0004699 453.9045 11.0000 +TU0004824 453.5286 11.0000 +TU0004892 453.3232 11.0000 +TU0004960 453.1190 11.0000 +TU0005034 452.8970 11.0000 +TU0005118 452.6474 11.0000 +TU0005350 451.9509 11.0000 +TU0005415 451.7559 11.0000 +TU0005538 451.3853 11.0000 +TU0005612 451.1634 11.0000 +TU0005720 450.9701 11.0000 +TU0005803 450.8193 11.0000 +TU0005888 450.6667 11.0000 +TU0005996 450.4717 11.0000 +TU0006069 450.3419 11.0000 +TU0006204 450.0976 11.0000 +TU0006329 449.8732 11.0000 +TU0006445 449.6652 11.0000 +TU0006547 449.4800 11.0000 +TU0006649 449.2963 11.0000 +TU0006784 449.0547 11.0000 +TU0006922 448.8052 11.0000 +TU0007041 448.5917 11.0000 +TU0007110 448.4672 11.0000 +TU0007249 448.2172 11.0000 +TU0007340 448.0528 11.0000 +TU0007462 447.8340 11.0000 +TU0007577 447.6268 11.0000 +TU0007686 447.4310 11.0000 +TU0007798 447.2290 11.0000 +TU0008033 446.8067 11.0000 +TU0008128 446.6346 11.0000 +TU0008196 446.5129 11.0000 +TU0008327 446.2772 11.0000 +TU0008434 446.0837 11.0000 +TU0008546 445.8831 11.0000 +TU0008608 445.7701 11.0000 +TU0008742 445.5298 11.0000 +TU0008847 445.3415 11.0000 +TU0008976 445.1079 11.0000 +TU0009092 444.9001 11.0000 +TU0009193 444.7172 11.0000 +TU0009260 444.5967 11.0000 +TU0009338 444.4564 11.0000 +TU0009406 444.3347 11.0000 +TU0009470 444.2187 11.0000 +TU0009608 443.9717 11.0000 +TU0009718 443.7729 11.0000 +TM0000096 443.4218 11.5000 +TM0000199 443.2371 11.5000 +TM0000310 443.0369 11.5000 +TM0000381 442.9088 11.5000 +TM0000450 442.7842 11.5000 +TM0000516 442.6667 11.5000 +TM0000580 442.6153 11.5000 +TM0000672 442.5417 11.5000 +TM0000767 442.4660 11.5000 +TM0000872 442.3815 11.5000 +TM0000987 442.2898 11.5000 +TM0001060 442.2316 11.5000 +TM0001158 442.1532 11.5000 +TM0001259 442.0721 11.5000 +TM0001339 442.0077 11.5000 +TM0001460 441.9109 11.5000 +TM0001579 443.7457 11.5000 +TM0001675 445.2339 11.5000 +TM0001742 446.2792 11.5000 +TM0001838 447.7644 11.5000 +TM0001947 449.4592 11.5000 +TM0002081 451.5303 11.5000 +TM0002189 453.2071 11.5000 +TM0002305 455.0013 11.5000 +TM0002412 454.3052 11.5000 +TM0002474 453.9026 11.5000 +TM0002582 453.1989 11.5000 +TM0002773 451.9566 11.5000 +TM0002894 451.1712 11.5000 +TM0003030 450.2895 11.5000 +TM0003126 449.6640 11.5000 +TM0003262 448.7792 11.5000 +TM0003352 448.1980 11.5000 +TM0003416 447.7769 11.5000 +TM0003519 447.1112 11.5000 +TM0003585 446.6787 11.5000 +TM0003683 446.0447 11.5000 +TM0003808 445.2290 11.5000 +TM0003923 444.4868 11.5000 +TM0004047 443.6783 11.5000 +TM0004167 443.5821 11.5000 +TM0004263 443.5053 11.5000 +TM0004352 443.4346 11.5000 +TM0004432 443.3702 11.5000 +TM0004544 443.2807 11.5000 +TM0004675 443.1757 11.5000 +TM0004789 443.0845 11.5000 +TM0004865 443.0240 11.5000 +TM0004992 442.9227 11.5000 +TM0005127 442.8144 11.5000 +TM0005377 442.6143 11.5000 +TM0005490 443.1788 11.5000 +TM0005578 443.6185 11.5000 +TM0005684 444.1481 11.5000 +TM0005760 444.5283 11.5000 +TM0005872 445.0880 11.5000 +TM0005955 445.5065 11.5000 +TM0006059 445.2794 11.5000 +TM0006123 445.1373 11.5000 +TM0006205 444.9581 11.5000 +TM0006319 444.7076 11.5000 +TM0006413 444.5003 11.5000 +TM0006552 444.1947 11.5000 +TM0006652 443.9730 11.5000 +TM0006717 443.8300 11.5000 +TM0006792 443.6664 11.5000 +TM0006897 443.4357 11.5000 +TM0006959 443.2981 11.5000 +TM0007031 443.1411 11.5000 +TM0007142 442.8959 11.5000 +TL0000111 442.4420 12.5000 +TL0000172 442.3071 12.5000 +TL0000258 442.1188 12.5000 +TL0000356 441.9019 12.5000 +TL0000488 441.6116 12.5000 +TL0000569 441.4325 12.5000 +TL0000647 441.2628 12.5000 +TL0000749 441.0369 12.5000 +TL0000830 440.8583 12.5000 +TL0000936 440.6265 12.5000 +TL0001055 440.3643 12.5000 +TL0001128 440.2028 12.5000 +TL0001230 439.9800 12.5000 +TL0001347 439.7221 12.5000 +TL0001419 439.5627 12.5000 +TL0001507 439.3701 12.5000 +TL0001571 439.2291 12.5000 +TL0001682 438.9855 12.5000 +TL0001776 438.7782 12.5000 +TL0001874 438.5634 12.5000 +TL0001991 438.3060 12.5000 +TL0002075 438.1206 12.5000 +TL0002155 437.9448 12.5000 +TL0002282 437.6654 12.5000 +TL0002374 437.4618 12.5000 +TL0002444 437.3083 12.5000 +TL0002551 437.0738 12.5000 +TL0002767 436.5972 12.5000 +TL0002880 436.3491 12.5000 +TL0002962 436.1699 12.5000 +TL0003039 435.9998 12.5000 +TL0003126 435.8078 12.5000 +TL0003263 435.5059 12.5000 +TL0003397 435.2114 12.5000 +TL0003471 435.0493 12.5000 +TL0003550 434.8762 12.5000 +TL0003627 434.7054 12.5000 +TL0003696 434.5552 12.5000 +TL0003812 434.2980 12.5000 +TL0003912 434.0792 12.5000 +TL0004035 433.8086 12.5000 +TL0004124 433.6125 12.5000 +TL0004231 433.3127 12.5000 +TL0004323 433.0559 12.5000 +TL0004460 432.6710 12.5000 +TL0004588 432.3137 12.5000 +TL0004707 431.9815 12.5000 +TL0004797 431.7294 12.5000 +TL0004894 431.4573 12.5000 +TL0005003 431.1503 12.5000 +TL0005119 430.8273 12.5000 +TL0005323 430.2545 12.5000 +TL0005447 429.9075 12.5000 +TL0005564 429.5814 12.5000 +TL0005637 429.3760 12.5000 +TL0005767 429.0117 12.5000 +TL0005840 428.8075 12.5000 +TL0005912 428.6070 12.5000 +TL0006049 428.2227 12.5000 +TL0006125 428.0101 12.5000 +TL0006238 427.6925 12.5000 +TL0006375 427.3104 12.5000 +TL0006486 426.9995 12.5000 +TL0006608 426.6581 12.5000 +TL0006736 426.2996 12.5000 +TL0006842 426.0009 12.5000 +TL0006906 425.8223 12.5000 +TL0006972 425.6378 12.5000 +TL0007106 425.2620 12.5000 +TL0007246 424.8703 12.5000 +TL0007331 424.6338 12.5000 +TL0007391 424.4655 12.5000 +TL0007482 424.2114 12.5000 +TL0007592 423.9021 12.5000 +TL0007711 423.5703 12.5000 +TL0007780 423.3753 12.5000 +TL0007940 422.9291 12.5000 +TL0008058 422.5963 12.5000 +TL0008156 422.3231 12.5000 +TL0008291 421.9439 12.5000 +TL0008415 421.5970 12.5000 +TL0008539 421.2498 12.5000 +TL0008657 420.9194 12.5000 +TL0008764 420.6194 12.5000 +BA0000066 478.7702 9.0000 +BA0000147 478.2787 9.0000 +BA0000248 477.6760 9.0000 +BA0000357 477.0241 9.0000 +BA0000491 476.2179 9.0000 +BA0000615 475.4735 9.0000 +BA0000735 474.7552 9.0000 +BA0000822 474.2333 9.0000 +BA0000926 473.6095 9.0000 +BA0000993 473.2036 9.0000 +BA0001132 472.3740 9.0000 +BA0001208 471.9136 9.0000 +BA0001310 471.3054 9.0000 +BA0001448 470.4780 9.0000 +BA0001560 469.8036 9.0000 +BA0001622 469.4311 9.0000 +BA0001740 468.7255 9.0000 +BA0001867 467.9623 9.0000 +BA0001947 467.4830 9.0000 +BA0002065 466.7742 9.0000 +BA0002151 466.2595 9.0000 +BA0002213 465.8852 9.0000 +BA0002283 465.4644 9.0000 +BA0002376 464.9051 9.0000 +BA0002479 464.2884 9.0000 +BA0002576 463.7048 9.0000 +BA0002746 462.6897 9.0000 +BA0002849 462.0696 9.0000 +BA0002945 461.4910 9.0000 +BA0003033 460.9636 9.0000 +BA0003095 460.5956 9.0000 +BA0003235 459.7564 9.0000 +BA0003311 459.2952 9.0000 +BA0003404 458.7402 9.0000 +BA0003499 458.1668 9.0000 +BA0003631 457.6424 9.0000 +BA0003743 457.1937 9.0000 +BA0003851 456.7589 9.0000 +BA0003922 456.4756 9.0000 +BA0004020 456.0862 9.0000 +BA0004157 455.5382 9.0000 +BA0004271 455.0791 9.0000 +BA0004410 454.5235 9.0000 +BA0004543 453.9913 9.0000 +BA0004613 453.7114 9.0000 +BA0004710 453.3242 9.0000 +BA0004823 452.8718 9.0000 +BA0004893 452.5910 9.0000 +BA0004985 452.2234 9.0000 +BA0005061 451.9206 9.0000 +BA0005180 451.4428 9.0000 +BA0005359 450.7276 9.0000 +BA0005423 450.4724 9.0000 +BA0005511 450.1187 9.0000 +BA0005580 449.8436 9.0000 +BA0005650 449.5635 9.0000 +BA0005767 449.0960 9.0000 +BA0005860 448.7251 9.0000 +BA0005945 448.3835 9.0000 +BA0006053 447.9525 9.0000 +BA0006170 447.4843 9.0000 +BA0006275 447.0632 9.0000 +BA0006413 446.5138 9.0000 +BA0006510 446.1238 9.0000 +BA0006572 445.8766 9.0000 +BA0006702 445.3569 9.0000 +BA0006807 444.9371 9.0000 +BA0006902 444.5564 9.0000 +BA0006971 444.2818 9.0000 +BA0007053 443.9515 9.0000 +BB0000130 469.0989 8.5000 +BB0000201 468.7073 8.5000 +BB0000273 468.3122 8.5000 +BB0000335 467.9700 8.5000 +BB0000469 467.2365 8.5000 +BB0000568 466.6900 8.5000 +BB0000668 466.1395 8.5000 +BB0000778 465.5333 8.5000 +BB0000915 464.7805 8.5000 +BB0000981 464.4178 8.5000 +BB0001065 463.9552 8.5000 +BB0001168 463.3875 8.5000 +BB0001229 463.0555 8.5000 +BB0001359 462.3374 8.5000 +BB0001422 461.9906 8.5000 +BB0001540 461.3445 8.5000 +BB0001605 460.9877 8.5000 +BB0001679 460.5789 8.5000 +BB0001817 459.8179 8.5000 +BB0001934 459.1769 8.5000 +BB0002032 458.6402 8.5000 +BB0002116 458.1760 8.5000 +BB0002243 457.4800 8.5000 +BB0002336 456.9665 8.5000 +BB0002415 456.5316 8.5000 +BB0002507 456.0251 8.5000 +BB0002721 454.8495 8.5000 +BB0002839 454.2022 8.5000 +BB0002977 453.4420 8.5000 +BB0003079 452.8804 8.5000 +BB0003149 452.4933 8.5000 +BB0003278 451.7855 8.5000 +BB0003350 451.4992 8.5000 +BB0003489 450.9414 8.5000 +BB0003628 450.3835 8.5000 +BB0003736 449.9541 8.5000 +BB0003841 449.5330 8.5000 +BB0003920 449.2185 8.5000 +BB0004045 448.7177 8.5000 +BB0004134 448.3604 8.5000 +BB0004265 447.8384 8.5000 +BB0004326 447.5950 8.5000 +BB0004414 447.2422 8.5000 +BB0004499 446.9018 8.5000 +BB0004614 446.4410 8.5000 +BB0004734 445.9621 8.5000 +BB0004858 445.4644 8.5000 +BB0004953 445.0850 8.5000 +BB0005056 444.6714 8.5000 +BB0005158 444.2642 8.5000 +BB0005347 443.5087 8.5000 +BB0005425 443.1955 8.5000 + +[OUTFALLS] +;;Name Elev Type Gated +OUT_RIVER 415.4379 FREE NO +OUT_OVERFLOW 424.4379 FREE NO + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape Coeff Expon Const SurDepth Fevap +FRS_Basin 418.4379 22.0000 2.0000 FUNCTIONAL 0 0 120000 0 0 + +[CONDUITS] +;;Name FromNode ToNode Length Roughness InOffset OutOffset InitFlow MaxFlow +TUC000 TU0000000 TU0000124 124.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC001 TU0000124 TU0000243 118.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC002 TU0000243 TU0000340 97.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC003 TU0000340 TU0000435 94.30 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC004 TU0000435 TU0000560 125.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC005 TU0000560 TU0000624 64.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC006 TU0000624 TU0000722 97.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC007 TU0000722 TU0000835 112.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC008 TU0000835 TU0000940 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC009 TU0000940 TU0001043 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC010 TU0001043 TU0001128 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC011 TU0001128 TU0001211 83.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC012 TU0001211 TU0001310 98.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC013 TU0001310 TU0001388 78.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC014 TU0001388 TU0001514 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC015 TU0001514 TU0001586 72.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC016 TU0001586 TU0001670 83.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC017 TU0001670 TU0001788 117.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC018 TU0001788 TU0001904 116.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC019 TU0001904 TU0001982 77.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC020 TU0001982 TU0002056 74.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC021 TU0002056 TU0002136 80.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC022 TU0002136 TU0002196 60.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC023 TU0002196 TU0002329 132.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC024 TU0002329 TU0002403 74.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC025 TU0002403 TU0002542 139.13 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC026 TU0002542 TU0002672 129.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC027 TU0002672 TU0002811 138.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC028 TU0002811 TU0002907 96.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC029 TU0002907 TU0003035 127.74 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC030 TU0003035 TU0003158 122.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC031 TU0003158 TU0003232 74.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC032 TU0003232 TU0003306 73.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC033 TU0003306 TU0003428 122.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC034 TU0003428 TU0003502 73.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC035 TU0003502 TU0003572 70.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC036 TU0003572 TU0003633 60.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC037 TU0003633 TU0003725 91.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC038 TU0003725 TU0003860 135.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC039 TU0003860 TU0003925 64.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC040 TU0003925 TU0004028 102.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC041 TU0004028 TU0004125 97.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC042 TU0004125 TU0004230 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC043 TU0004230 TU0004296 65.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC044 TU0004296 TU0004396 100.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC045 TU0004396 TU0004532 135.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC046 TU0004532 TU0004635 103.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC047 TU0004635 TU0004699 63.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC048 TU0004699 TU0004824 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC049 TU0004824 TU0004892 68.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC050 TU0004892 TU0004960 68.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC051 TU0004960 TU0005034 74.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC052 TU0005034 TU0005118 83.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC053 TU0005118 TU0005213 95.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC054 TU0005213 TU0005350 136.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC055 TU0005350 TU0005415 65.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC056 TU0005415 TU0005538 123.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC057 TU0005538 TU0005612 73.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC058 TU0005612 TU0005720 107.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC059 TU0005720 TU0005803 83.81 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC060 TU0005803 TU0005888 84.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC061 TU0005888 TU0005996 108.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC062 TU0005996 TU0006069 72.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC063 TU0006069 TU0006204 135.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC064 TU0006204 TU0006329 124.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC065 TU0006329 TU0006445 115.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC066 TU0006445 TU0006547 102.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC067 TU0006547 TU0006649 102.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC068 TU0006649 TU0006784 134.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC069 TU0006784 TU0006922 138.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC070 TU0006922 TU0007041 118.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC071 TU0007041 TU0007110 69.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC072 TU0007110 TU0007249 138.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC073 TU0007249 TU0007340 91.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC074 TU0007340 TU0007462 121.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC075 TU0007462 TU0007577 115.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC076 TU0007577 TU0007686 108.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC077 TU0007686 TU0007798 112.23 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC078 TU0007798 TU0007917 119.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC079 TU0007917 TU0008033 115.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC080 TU0008033 TU0008128 95.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC081 TU0008128 TU0008196 67.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC082 TU0008196 TU0008327 130.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC083 TU0008327 TU0008434 107.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC084 TU0008434 TU0008546 111.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC085 TU0008546 TU0008608 62.80 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC086 TU0008608 TU0008742 133.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC087 TU0008742 TU0008847 104.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC088 TU0008847 TU0008976 129.79 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC089 TU0008976 TU0009092 115.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC090 TU0009092 TU0009193 101.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC091 TU0009193 TU0009260 66.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC092 TU0009260 TU0009338 77.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC093 TU0009338 TU0009406 67.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC094 TU0009406 TU0009470 64.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC095 TU0009470 TU0009608 137.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC096 TU0009608 TU0009718 110.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC097 TU0009718 TU0009817 98.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC000 TU0009817 TM0000096 96.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC001 TM0000096 TM0000199 102.59 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC002 TM0000199 TM0000310 111.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC003 TM0000310 TM0000381 71.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC004 TM0000381 TM0000450 69.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC005 TM0000450 TM0000516 65.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC006 TM0000516 TM0000580 64.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC007 TM0000580 TM0000672 92.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC008 TM0000672 TM0000767 94.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC009 TM0000767 TM0000872 105.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC010 TM0000872 TM0000987 114.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC011 TM0000987 TM0001060 72.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC012 TM0001060 TM0001158 98.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC013 TM0001158 TM0001259 101.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC014 TM0001259 TM0001339 80.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC015 TM0001339 TM0001460 121.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC016 TM0001460 TM0001579 118.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC017 TM0001579 TM0001675 96.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC018 TM0001675 TM0001742 67.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC019 TM0001742 TM0001838 95.82 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC020 TM0001838 TM0001947 109.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC021 TM0001947 TM0002081 133.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC022 TM0002081 TM0002189 108.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC023 TM0002189 TM0002305 115.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC024 TM0002305 TM0002412 107.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC025 TM0002412 TM0002474 61.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC026 TM0002474 TM0002582 108.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC027 TM0002582 TM0002713 130.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC028 TM0002713 TM0002773 60.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC029 TM0002773 TM0002894 120.83 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC030 TM0002894 TM0003030 135.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC031 TM0003030 TM0003126 96.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC032 TM0003126 TM0003262 136.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC033 TM0003262 TM0003352 89.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC034 TM0003352 TM0003416 64.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC035 TM0003416 TM0003519 102.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC036 TM0003519 TM0003585 66.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC037 TM0003585 TM0003683 97.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC038 TM0003683 TM0003808 125.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC039 TM0003808 TM0003923 114.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC040 TM0003923 TM0004047 124.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC041 TM0004047 TM0004167 120.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC042 TM0004167 TM0004263 95.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC043 TM0004263 TM0004352 88.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC044 TM0004352 TM0004432 80.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC045 TM0004432 TM0004544 111.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC046 TM0004544 TM0004675 131.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC047 TM0004675 TM0004789 113.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC048 TM0004789 TM0004865 75.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC049 TM0004865 TM0004992 126.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC050 TM0004992 TM0005127 135.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC051 TM0005127 TM0005252 125.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC052 TM0005252 TM0005377 124.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC053 TM0005377 TM0005490 112.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC054 TM0005490 TM0005578 87.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC055 TM0005578 TM0005684 105.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC056 TM0005684 TM0005760 76.03 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC057 TM0005760 TM0005872 111.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC058 TM0005872 TM0005955 83.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC059 TM0005955 TM0006059 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC060 TM0006059 TM0006123 64.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC061 TM0006123 TM0006205 81.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC062 TM0006205 TM0006319 113.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC063 TM0006319 TM0006413 94.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC064 TM0006413 TM0006552 138.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC065 TM0006552 TM0006652 100.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC066 TM0006652 TM0006717 65.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC067 TM0006717 TM0006792 74.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC068 TM0006792 TM0006897 104.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC069 TM0006897 TM0006959 62.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC070 TM0006959 TM0007031 71.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC071 TM0007031 TM0007142 111.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC072 TM0007142 TM0007238 95.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC000 TM0007238 TL0000111 110.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC001 TL0000111 TL0000172 61.35 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC002 TL0000172 TL0000258 85.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC003 TL0000258 TL0000356 98.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC004 TL0000356 TL0000488 131.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC005 TL0000488 TL0000569 81.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC006 TL0000569 TL0000647 77.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC007 TL0000647 TL0000749 102.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC008 TL0000749 TL0000830 81.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC009 TL0000830 TL0000936 105.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC010 TL0000936 TL0001055 119.14 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC011 TL0001055 TL0001128 73.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC012 TL0001128 TL0001230 101.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC013 TL0001230 TL0001347 117.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC014 TL0001347 TL0001419 72.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC015 TL0001419 TL0001507 87.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC016 TL0001507 TL0001571 64.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC017 TL0001571 TL0001682 110.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC018 TL0001682 TL0001776 94.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC019 TL0001776 TL0001874 97.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC020 TL0001874 TL0001991 117.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC021 TL0001991 TL0002075 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC022 TL0002075 TL0002155 79.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC023 TL0002155 TL0002282 127.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC024 TL0002282 TL0002374 92.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC025 TL0002374 TL0002444 69.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC026 TL0002444 TL0002551 106.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC027 TL0002551 TL0002658 107.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC028 TL0002658 TL0002767 108.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC029 TL0002767 TL0002880 112.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC030 TL0002880 TL0002962 81.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC031 TL0002962 TL0003039 77.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC032 TL0003039 TL0003126 87.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC033 TL0003126 TL0003263 137.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC034 TL0003263 TL0003397 133.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC035 TL0003397 TL0003471 73.66 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC036 TL0003471 TL0003550 78.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC037 TL0003550 TL0003627 77.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC038 TL0003627 TL0003696 68.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC039 TL0003696 TL0003812 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC040 TL0003812 TL0003912 99.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC041 TL0003912 TL0004035 123.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC042 TL0004035 TL0004124 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC043 TL0004124 TL0004231 107.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC044 TL0004231 TL0004323 91.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC045 TL0004323 TL0004460 137.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC046 TL0004460 TL0004588 127.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC047 TL0004588 TL0004707 118.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC048 TL0004707 TL0004797 90.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC049 TL0004797 TL0004894 97.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC050 TL0004894 TL0005003 109.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC051 TL0005003 TL0005119 115.36 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC052 TL0005119 TL0005207 88.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC053 TL0005207 TL0005323 116.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC054 TL0005323 TL0005447 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC055 TL0005447 TL0005564 116.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC056 TL0005564 TL0005637 73.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC057 TL0005637 TL0005767 130.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC058 TL0005767 TL0005840 72.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC059 TL0005840 TL0005912 71.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC060 TL0005912 TL0006049 137.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC061 TL0006049 TL0006125 75.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC062 TL0006125 TL0006238 113.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC063 TL0006238 TL0006375 136.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC064 TL0006375 TL0006486 111.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC065 TL0006486 TL0006608 121.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC066 TL0006608 TL0006736 128.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC067 TL0006736 TL0006842 106.68 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC068 TL0006842 TL0006906 63.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC069 TL0006906 TL0006972 65.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC070 TL0006972 TL0007106 134.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC071 TL0007106 TL0007246 139.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC072 TL0007246 TL0007331 84.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC073 TL0007331 TL0007391 60.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC074 TL0007391 TL0007482 90.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC075 TL0007482 TL0007592 110.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC076 TL0007592 TL0007711 118.51 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC077 TL0007711 TL0007780 69.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC078 TL0007780 TL0007853 72.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC079 TL0007853 TL0007940 86.96 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC080 TL0007940 TL0008058 118.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC081 TL0008058 TL0008156 97.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC082 TL0008156 TL0008291 135.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC083 TL0008291 TL0008415 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC084 TL0008415 TL0008539 123.99 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC085 TL0008539 TL0008657 118.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC086 TL0008657 TL0008764 107.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC087 TL0008764 FRS_Basin 64.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC000 BA0000000 BA0000066 65.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC001 BA0000066 BA0000147 81.92 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC002 BA0000147 BA0000248 100.45 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC003 BA0000248 BA0000357 108.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC004 BA0000357 BA0000491 134.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC005 BA0000491 BA0000615 124.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC006 BA0000615 BA0000735 119.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC007 BA0000735 BA0000822 86.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC008 BA0000822 BA0000926 103.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC009 BA0000926 BA0000993 67.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC010 BA0000993 BA0001132 138.26 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC011 BA0001132 BA0001208 76.74 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC012 BA0001208 BA0001310 101.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC013 BA0001310 BA0001448 137.91 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC014 BA0001448 BA0001560 112.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC015 BA0001560 BA0001622 62.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC016 BA0001622 BA0001740 117.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC017 BA0001740 BA0001867 127.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC018 BA0001867 BA0001947 79.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC019 BA0001947 BA0002065 118.14 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC020 BA0002065 BA0002151 85.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC021 BA0002151 BA0002213 62.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC022 BA0002213 BA0002283 70.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC023 BA0002283 BA0002376 93.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC024 BA0002376 BA0002479 102.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC025 BA0002479 BA0002576 97.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC026 BA0002576 BA0002678 101.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC027 BA0002678 BA0002746 67.63 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC028 BA0002746 BA0002849 103.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC029 BA0002849 BA0002945 96.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC030 BA0002945 BA0003033 87.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC031 BA0003033 BA0003095 61.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC032 BA0003095 BA0003235 139.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC033 BA0003235 BA0003311 76.86 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC034 BA0003311 BA0003404 92.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC035 BA0003404 BA0003499 95.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC036 BA0003499 BA0003631 131.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC037 BA0003631 BA0003743 112.16 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC038 BA0003743 BA0003851 108.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC039 BA0003851 BA0003922 70.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC040 BA0003922 BA0004020 97.34 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC041 BA0004020 BA0004157 137.00 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC042 BA0004157 BA0004271 114.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC043 BA0004271 BA0004410 138.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC044 BA0004410 BA0004543 133.07 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC045 BA0004543 BA0004613 69.97 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC046 BA0004613 BA0004710 96.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC047 BA0004710 BA0004823 113.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC048 BA0004823 BA0004893 70.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC049 BA0004893 BA0004985 91.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC050 BA0004985 BA0005061 75.72 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC051 BA0005061 BA0005180 119.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC052 BA0005180 BA0005279 98.24 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC053 BA0005279 BA0005359 80.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC054 BA0005359 BA0005423 63.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC055 BA0005423 BA0005511 88.43 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC056 BA0005511 BA0005580 68.77 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC057 BA0005580 BA0005650 70.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC058 BA0005650 BA0005767 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC059 BA0005767 BA0005860 92.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC060 BA0005860 BA0005945 85.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC061 BA0005945 BA0006053 107.76 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC062 BA0006053 BA0006170 117.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC063 BA0006170 BA0006275 105.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC064 BA0006275 BA0006413 137.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC065 BA0006413 BA0006510 97.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC066 BA0006510 BA0006572 61.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC067 BA0006572 BA0006702 129.93 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC068 BA0006702 BA0006807 104.96 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC069 BA0006807 BA0006902 95.17 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC070 BA0006902 BA0006971 68.66 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC071 BA0006971 BA0007053 82.58 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC072 BA0007053 TU0009817 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC000 BB0000000 BB0000130 130.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC001 BB0000130 BB0000201 71.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC002 BB0000201 BB0000273 71.85 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC003 BB0000273 BB0000335 62.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC004 BB0000335 BB0000469 133.37 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC005 BB0000469 BB0000568 99.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC006 BB0000568 BB0000668 100.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC007 BB0000668 BB0000778 110.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC008 BB0000778 BB0000915 136.88 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC009 BB0000915 BB0000981 65.94 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC010 BB0000981 BB0001065 84.10 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC011 BB0001065 BB0001168 103.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC012 BB0001168 BB0001229 60.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC013 BB0001229 BB0001359 130.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC014 BB0001359 BB0001422 63.06 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC015 BB0001422 BB0001540 117.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC016 BB0001540 BB0001605 64.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC017 BB0001605 BB0001679 74.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC018 BB0001679 BB0001817 138.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC019 BB0001817 BB0001934 116.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC020 BB0001934 BB0002032 97.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC021 BB0002032 BB0002116 84.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC022 BB0002116 BB0002243 126.54 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC023 BB0002243 BB0002336 93.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC024 BB0002336 BB0002415 79.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC025 BB0002415 BB0002507 92.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC026 BB0002507 BB0002622 114.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC027 BB0002622 BB0002721 99.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC028 BB0002721 BB0002839 117.68 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC029 BB0002839 BB0002977 138.22 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC030 BB0002977 BB0003079 102.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC031 BB0003079 BB0003149 70.38 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC032 BB0003149 BB0003278 128.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC033 BB0003278 BB0003350 71.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC034 BB0003350 BB0003489 139.46 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC035 BB0003489 BB0003628 139.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC036 BB0003628 BB0003736 107.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC037 BB0003736 BB0003841 105.27 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC038 BB0003841 BB0003920 78.61 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC039 BB0003920 BB0004045 125.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC040 BB0004045 BB0004134 89.32 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC041 BB0004134 BB0004265 130.51 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC042 BB0004265 BB0004326 60.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC043 BB0004326 BB0004414 88.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC044 BB0004414 BB0004499 85.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC045 BB0004499 BB0004614 115.18 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC046 BB0004614 BB0004734 119.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC047 BB0004734 BB0004858 124.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC048 BB0004858 BB0004953 94.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC049 BB0004953 BB0005056 103.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC050 BB0005056 BB0005158 101.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC051 BB0005158 BB0005220 61.82 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC052 BB0005220 BB0005347 127.05 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC053 BB0005347 BB0005425 78.30 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC054 BB0005425 TM0007238 127.53 0.0130 0.0000 0.0000 0.0000 0.0000 + +[ORIFICES] +;;Name FromNode ToNode Type Offset Cd Gated +FRS_Outlet FRS_Basin OUT_RIVER SIDE 0.0000 0.6500 NO +FRS_Overflow FRS_Basin OUT_OVERFLOW SIDE 8.0000 1.0000 NO + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +TUC000 CIRCULAR 6.0000 0 0 0 1 +TUC001 CIRCULAR 6.0000 0 0 0 1 +TUC002 CIRCULAR 6.0000 0 0 0 1 +TUC003 CIRCULAR 6.0000 0 0 0 1 +TUC004 CIRCULAR 6.0000 0 0 0 1 +TUC005 CIRCULAR 6.0000 0 0 0 1 +TUC006 CIRCULAR 6.0000 0 0 0 1 +TUC007 CIRCULAR 6.0000 0 0 0 1 +TUC008 CIRCULAR 6.0000 0 0 0 1 +TUC009 CIRCULAR 6.0000 0 0 0 1 +TUC010 CIRCULAR 6.0000 0 0 0 1 +TUC011 CIRCULAR 6.0000 0 0 0 1 +TUC012 CIRCULAR 6.0000 0 0 0 1 +TUC013 CIRCULAR 6.0000 0 0 0 1 +TUC014 CIRCULAR 6.0000 0 0 0 1 +TUC015 CIRCULAR 6.0000 0 0 0 1 +TUC016 CIRCULAR 6.0000 0 0 0 1 +TUC017 CIRCULAR 6.0000 0 0 0 1 +TUC018 CIRCULAR 6.0000 0 0 0 1 +TUC019 CIRCULAR 6.0000 0 0 0 1 +TUC020 CIRCULAR 6.0000 0 0 0 1 +TUC021 CIRCULAR 6.0000 0 0 0 1 +TUC022 CIRCULAR 6.0000 0 0 0 1 +TUC023 CIRCULAR 6.0000 0 0 0 1 +TUC024 CIRCULAR 6.0000 0 0 0 1 +TUC025 CIRCULAR 6.0000 0 0 0 1 +TUC026 CIRCULAR 6.0000 0 0 0 1 +TUC027 CIRCULAR 6.0000 0 0 0 1 +TUC028 CIRCULAR 6.0000 0 0 0 1 +TUC029 CIRCULAR 6.0000 0 0 0 1 +TUC030 CIRCULAR 6.0000 0 0 0 1 +TUC031 CIRCULAR 6.0000 0 0 0 1 +TUC032 CIRCULAR 6.0000 0 0 0 1 +TUC033 CIRCULAR 6.0000 0 0 0 1 +TUC034 CIRCULAR 6.0000 0 0 0 1 +TUC035 CIRCULAR 6.0000 0 0 0 1 +TUC036 CIRCULAR 6.0000 0 0 0 1 +TUC037 CIRCULAR 6.0000 0 0 0 1 +TUC038 CIRCULAR 6.0000 0 0 0 1 +TUC039 CIRCULAR 6.0000 0 0 0 1 +TUC040 CIRCULAR 6.0000 0 0 0 1 +TUC041 CIRCULAR 6.0000 0 0 0 1 +TUC042 CIRCULAR 6.0000 0 0 0 1 +TUC043 CIRCULAR 6.0000 0 0 0 1 +TUC044 CIRCULAR 6.0000 0 0 0 1 +TUC045 CIRCULAR 6.0000 0 0 0 1 +TUC046 CIRCULAR 6.0000 0 0 0 1 +TUC047 CIRCULAR 6.0000 0 0 0 1 +TUC048 CIRCULAR 6.0000 0 0 0 1 +TUC049 CIRCULAR 6.0000 0 0 0 1 +TUC050 CIRCULAR 6.0000 0 0 0 1 +TUC051 CIRCULAR 6.0000 0 0 0 1 +TUC052 CIRCULAR 6.0000 0 0 0 1 +TUC053 CIRCULAR 6.0000 0 0 0 1 +TUC054 CIRCULAR 6.0000 0 0 0 1 +TUC055 CIRCULAR 6.0000 0 0 0 1 +TUC056 CIRCULAR 6.0000 0 0 0 1 +TUC057 CIRCULAR 6.0000 0 0 0 1 +TUC058 CIRCULAR 6.0000 0 0 0 1 +TUC059 CIRCULAR 6.0000 0 0 0 1 +TUC060 CIRCULAR 6.0000 0 0 0 1 +TUC061 CIRCULAR 6.0000 0 0 0 1 +TUC062 CIRCULAR 6.0000 0 0 0 1 +TUC063 CIRCULAR 6.0000 0 0 0 1 +TUC064 CIRCULAR 6.0000 0 0 0 1 +TUC065 CIRCULAR 6.0000 0 0 0 1 +TUC066 CIRCULAR 6.0000 0 0 0 1 +TUC067 CIRCULAR 6.0000 0 0 0 1 +TUC068 CIRCULAR 6.0000 0 0 0 1 +TUC069 CIRCULAR 6.0000 0 0 0 1 +TUC070 CIRCULAR 6.0000 0 0 0 1 +TUC071 CIRCULAR 6.0000 0 0 0 1 +TUC072 CIRCULAR 6.0000 0 0 0 1 +TUC073 CIRCULAR 6.0000 0 0 0 1 +TUC074 CIRCULAR 6.0000 0 0 0 1 +TUC075 CIRCULAR 6.0000 0 0 0 1 +TUC076 CIRCULAR 6.0000 0 0 0 1 +TUC077 CIRCULAR 6.0000 0 0 0 1 +TUC078 CIRCULAR 6.0000 0 0 0 1 +TUC079 CIRCULAR 6.0000 0 0 0 1 +TUC080 CIRCULAR 6.0000 0 0 0 1 +TUC081 CIRCULAR 6.0000 0 0 0 1 +TUC082 CIRCULAR 6.0000 0 0 0 1 +TUC083 CIRCULAR 6.0000 0 0 0 1 +TUC084 CIRCULAR 6.0000 0 0 0 1 +TUC085 CIRCULAR 6.0000 0 0 0 1 +TUC086 CIRCULAR 6.0000 0 0 0 1 +TUC087 CIRCULAR 6.0000 0 0 0 1 +TUC088 CIRCULAR 6.0000 0 0 0 1 +TUC089 CIRCULAR 6.0000 0 0 0 1 +TUC090 CIRCULAR 6.0000 0 0 0 1 +TUC091 CIRCULAR 6.0000 0 0 0 1 +TUC092 CIRCULAR 6.0000 0 0 0 1 +TUC093 CIRCULAR 6.0000 0 0 0 1 +TUC094 CIRCULAR 6.0000 0 0 0 1 +TUC095 CIRCULAR 6.0000 0 0 0 1 +TUC096 CIRCULAR 6.0000 0 0 0 1 +TUC097 CIRCULAR 6.0000 0 0 0 1 +TMC000 CIRCULAR 6.5000 0 0 0 1 +TMC001 CIRCULAR 6.5000 0 0 0 1 +TMC002 CIRCULAR 6.5000 0 0 0 1 +TMC003 CIRCULAR 6.5000 0 0 0 1 +TMC004 CIRCULAR 6.5000 0 0 0 1 +TMC005 CIRCULAR 6.5000 0 0 0 1 +TMC006 CIRCULAR 6.5000 0 0 0 1 +TMC007 CIRCULAR 6.5000 0 0 0 1 +TMC008 CIRCULAR 6.5000 0 0 0 1 +TMC009 CIRCULAR 6.5000 0 0 0 1 +TMC010 CIRCULAR 6.5000 0 0 0 1 +TMC011 CIRCULAR 6.5000 0 0 0 1 +TMC012 CIRCULAR 6.5000 0 0 0 1 +TMC013 CIRCULAR 6.5000 0 0 0 1 +TMC014 CIRCULAR 6.5000 0 0 0 1 +TMC015 CIRCULAR 6.5000 0 0 0 1 +TMC016 CIRCULAR 6.5000 0 0 0 1 +TMC017 CIRCULAR 6.5000 0 0 0 1 +TMC018 CIRCULAR 6.5000 0 0 0 1 +TMC019 CIRCULAR 6.5000 0 0 0 1 +TMC020 CIRCULAR 6.5000 0 0 0 1 +TMC021 CIRCULAR 6.5000 0 0 0 1 +TMC022 CIRCULAR 6.5000 0 0 0 1 +TMC023 CIRCULAR 6.5000 0 0 0 1 +TMC024 CIRCULAR 6.5000 0 0 0 1 +TMC025 CIRCULAR 6.5000 0 0 0 1 +TMC026 CIRCULAR 6.5000 0 0 0 1 +TMC027 CIRCULAR 6.5000 0 0 0 1 +TMC028 CIRCULAR 6.5000 0 0 0 1 +TMC029 CIRCULAR 6.5000 0 0 0 1 +TMC030 CIRCULAR 6.5000 0 0 0 1 +TMC031 CIRCULAR 6.5000 0 0 0 1 +TMC032 CIRCULAR 6.5000 0 0 0 1 +TMC033 CIRCULAR 6.5000 0 0 0 1 +TMC034 CIRCULAR 6.5000 0 0 0 1 +TMC035 CIRCULAR 6.5000 0 0 0 1 +TMC036 CIRCULAR 6.5000 0 0 0 1 +TMC037 CIRCULAR 6.5000 0 0 0 1 +TMC038 CIRCULAR 6.5000 0 0 0 1 +TMC039 CIRCULAR 6.5000 0 0 0 1 +TMC040 CIRCULAR 6.5000 0 0 0 1 +TMC041 CIRCULAR 6.5000 0 0 0 1 +TMC042 CIRCULAR 6.5000 0 0 0 1 +TMC043 CIRCULAR 6.5000 0 0 0 1 +TMC044 CIRCULAR 6.5000 0 0 0 1 +TMC045 CIRCULAR 6.5000 0 0 0 1 +TMC046 CIRCULAR 6.5000 0 0 0 1 +TMC047 CIRCULAR 6.5000 0 0 0 1 +TMC048 CIRCULAR 6.5000 0 0 0 1 +TMC049 CIRCULAR 6.5000 0 0 0 1 +TMC050 CIRCULAR 6.5000 0 0 0 1 +TMC051 CIRCULAR 6.5000 0 0 0 1 +TMC052 CIRCULAR 6.5000 0 0 0 1 +TMC053 CIRCULAR 6.5000 0 0 0 1 +TMC054 CIRCULAR 6.5000 0 0 0 1 +TMC055 CIRCULAR 6.5000 0 0 0 1 +TMC056 CIRCULAR 6.5000 0 0 0 1 +TMC057 CIRCULAR 6.5000 0 0 0 1 +TMC058 CIRCULAR 6.5000 0 0 0 1 +TMC059 CIRCULAR 6.5000 0 0 0 1 +TMC060 CIRCULAR 6.5000 0 0 0 1 +TMC061 CIRCULAR 6.5000 0 0 0 1 +TMC062 CIRCULAR 6.5000 0 0 0 1 +TMC063 CIRCULAR 6.5000 0 0 0 1 +TMC064 CIRCULAR 6.5000 0 0 0 1 +TMC065 CIRCULAR 6.5000 0 0 0 1 +TMC066 CIRCULAR 6.5000 0 0 0 1 +TMC067 CIRCULAR 6.5000 0 0 0 1 +TMC068 CIRCULAR 6.5000 0 0 0 1 +TMC069 CIRCULAR 6.5000 0 0 0 1 +TMC070 CIRCULAR 6.5000 0 0 0 1 +TMC071 CIRCULAR 6.5000 0 0 0 1 +TMC072 CIRCULAR 6.5000 0 0 0 1 +TLC000 CIRCULAR 7.5000 0 0 0 1 +TLC001 CIRCULAR 7.5000 0 0 0 1 +TLC002 CIRCULAR 7.5000 0 0 0 1 +TLC003 CIRCULAR 7.5000 0 0 0 1 +TLC004 CIRCULAR 7.5000 0 0 0 1 +TLC005 CIRCULAR 7.5000 0 0 0 1 +TLC006 CIRCULAR 7.5000 0 0 0 1 +TLC007 CIRCULAR 7.5000 0 0 0 1 +TLC008 CIRCULAR 7.5000 0 0 0 1 +TLC009 CIRCULAR 7.5000 0 0 0 1 +TLC010 CIRCULAR 7.5000 0 0 0 1 +TLC011 CIRCULAR 7.5000 0 0 0 1 +TLC012 CIRCULAR 7.5000 0 0 0 1 +TLC013 CIRCULAR 7.5000 0 0 0 1 +TLC014 CIRCULAR 7.5000 0 0 0 1 +TLC015 CIRCULAR 7.5000 0 0 0 1 +TLC016 CIRCULAR 7.5000 0 0 0 1 +TLC017 CIRCULAR 7.5000 0 0 0 1 +TLC018 CIRCULAR 7.5000 0 0 0 1 +TLC019 CIRCULAR 7.5000 0 0 0 1 +TLC020 CIRCULAR 7.5000 0 0 0 1 +TLC021 CIRCULAR 7.5000 0 0 0 1 +TLC022 CIRCULAR 7.5000 0 0 0 1 +TLC023 CIRCULAR 7.5000 0 0 0 1 +TLC024 CIRCULAR 7.5000 0 0 0 1 +TLC025 CIRCULAR 7.5000 0 0 0 1 +TLC026 CIRCULAR 7.5000 0 0 0 1 +TLC027 CIRCULAR 7.5000 0 0 0 1 +TLC028 CIRCULAR 7.5000 0 0 0 1 +TLC029 CIRCULAR 7.5000 0 0 0 1 +TLC030 CIRCULAR 7.5000 0 0 0 1 +TLC031 CIRCULAR 7.5000 0 0 0 1 +TLC032 CIRCULAR 7.5000 0 0 0 1 +TLC033 CIRCULAR 7.5000 0 0 0 1 +TLC034 CIRCULAR 7.5000 0 0 0 1 +TLC035 CIRCULAR 7.5000 0 0 0 1 +TLC036 CIRCULAR 7.5000 0 0 0 1 +TLC037 CIRCULAR 7.5000 0 0 0 1 +TLC038 CIRCULAR 7.5000 0 0 0 1 +TLC039 CIRCULAR 7.5000 0 0 0 1 +TLC040 CIRCULAR 7.5000 0 0 0 1 +TLC041 CIRCULAR 7.5000 0 0 0 1 +TLC042 CIRCULAR 7.5000 0 0 0 1 +TLC043 CIRCULAR 7.5000 0 0 0 1 +TLC044 CIRCULAR 7.5000 0 0 0 1 +TLC045 CIRCULAR 7.5000 0 0 0 1 +TLC046 CIRCULAR 7.5000 0 0 0 1 +TLC047 CIRCULAR 7.5000 0 0 0 1 +TLC048 CIRCULAR 7.5000 0 0 0 1 +TLC049 CIRCULAR 7.5000 0 0 0 1 +TLC050 CIRCULAR 7.5000 0 0 0 1 +TLC051 CIRCULAR 7.5000 0 0 0 1 +TLC052 CIRCULAR 7.5000 0 0 0 1 +TLC053 CIRCULAR 7.5000 0 0 0 1 +TLC054 CIRCULAR 7.5000 0 0 0 1 +TLC055 CIRCULAR 7.5000 0 0 0 1 +TLC056 CIRCULAR 7.5000 0 0 0 1 +TLC057 CIRCULAR 7.5000 0 0 0 1 +TLC058 CIRCULAR 7.5000 0 0 0 1 +TLC059 CIRCULAR 7.5000 0 0 0 1 +TLC060 CIRCULAR 7.5000 0 0 0 1 +TLC061 CIRCULAR 7.5000 0 0 0 1 +TLC062 CIRCULAR 7.5000 0 0 0 1 +TLC063 CIRCULAR 7.5000 0 0 0 1 +TLC064 CIRCULAR 7.5000 0 0 0 1 +TLC065 CIRCULAR 7.5000 0 0 0 1 +TLC066 CIRCULAR 7.5000 0 0 0 1 +TLC067 CIRCULAR 7.5000 0 0 0 1 +TLC068 CIRCULAR 7.5000 0 0 0 1 +TLC069 CIRCULAR 7.5000 0 0 0 1 +TLC070 CIRCULAR 7.5000 0 0 0 1 +TLC071 CIRCULAR 7.5000 0 0 0 1 +TLC072 CIRCULAR 7.5000 0 0 0 1 +TLC073 CIRCULAR 7.5000 0 0 0 1 +TLC074 CIRCULAR 7.5000 0 0 0 1 +TLC075 CIRCULAR 7.5000 0 0 0 1 +TLC076 CIRCULAR 7.5000 0 0 0 1 +TLC077 CIRCULAR 7.5000 0 0 0 1 +TLC078 CIRCULAR 7.5000 0 0 0 1 +TLC079 CIRCULAR 7.5000 0 0 0 1 +TLC080 CIRCULAR 7.5000 0 0 0 1 +TLC081 CIRCULAR 7.5000 0 0 0 1 +TLC082 CIRCULAR 7.5000 0 0 0 1 +TLC083 CIRCULAR 7.5000 0 0 0 1 +TLC084 CIRCULAR 7.5000 0 0 0 1 +TLC085 CIRCULAR 7.5000 0 0 0 1 +TLC086 CIRCULAR 7.5000 0 0 0 1 +TLC087 CIRCULAR 7.5000 0 0 0 1 +BAC000 CIRCULAR 4.0000 0 0 0 1 +BAC001 CIRCULAR 4.0000 0 0 0 1 +BAC002 CIRCULAR 4.0000 0 0 0 1 +BAC003 CIRCULAR 4.0000 0 0 0 1 +BAC004 CIRCULAR 4.0000 0 0 0 1 +BAC005 CIRCULAR 4.0000 0 0 0 1 +BAC006 CIRCULAR 4.0000 0 0 0 1 +BAC007 CIRCULAR 4.0000 0 0 0 1 +BAC008 CIRCULAR 4.0000 0 0 0 1 +BAC009 CIRCULAR 4.0000 0 0 0 1 +BAC010 CIRCULAR 4.0000 0 0 0 1 +BAC011 CIRCULAR 4.0000 0 0 0 1 +BAC012 CIRCULAR 4.0000 0 0 0 1 +BAC013 CIRCULAR 4.0000 0 0 0 1 +BAC014 CIRCULAR 4.0000 0 0 0 1 +BAC015 CIRCULAR 4.0000 0 0 0 1 +BAC016 CIRCULAR 4.0000 0 0 0 1 +BAC017 CIRCULAR 4.0000 0 0 0 1 +BAC018 CIRCULAR 4.0000 0 0 0 1 +BAC019 CIRCULAR 4.0000 0 0 0 1 +BAC020 CIRCULAR 4.0000 0 0 0 1 +BAC021 CIRCULAR 4.0000 0 0 0 1 +BAC022 CIRCULAR 4.0000 0 0 0 1 +BAC023 CIRCULAR 4.0000 0 0 0 1 +BAC024 CIRCULAR 4.0000 0 0 0 1 +BAC025 CIRCULAR 4.0000 0 0 0 1 +BAC026 CIRCULAR 4.0000 0 0 0 1 +BAC027 CIRCULAR 4.0000 0 0 0 1 +BAC028 CIRCULAR 4.0000 0 0 0 1 +BAC029 CIRCULAR 4.0000 0 0 0 1 +BAC030 CIRCULAR 4.0000 0 0 0 1 +BAC031 CIRCULAR 4.0000 0 0 0 1 +BAC032 CIRCULAR 4.0000 0 0 0 1 +BAC033 CIRCULAR 4.0000 0 0 0 1 +BAC034 CIRCULAR 4.0000 0 0 0 1 +BAC035 CIRCULAR 4.0000 0 0 0 1 +BAC036 CIRCULAR 4.0000 0 0 0 1 +BAC037 CIRCULAR 4.0000 0 0 0 1 +BAC038 CIRCULAR 4.0000 0 0 0 1 +BAC039 CIRCULAR 4.0000 0 0 0 1 +BAC040 CIRCULAR 4.0000 0 0 0 1 +BAC041 CIRCULAR 4.0000 0 0 0 1 +BAC042 CIRCULAR 4.0000 0 0 0 1 +BAC043 CIRCULAR 4.0000 0 0 0 1 +BAC044 CIRCULAR 4.0000 0 0 0 1 +BAC045 CIRCULAR 4.0000 0 0 0 1 +BAC046 CIRCULAR 4.0000 0 0 0 1 +BAC047 CIRCULAR 4.0000 0 0 0 1 +BAC048 CIRCULAR 4.0000 0 0 0 1 +BAC049 CIRCULAR 4.0000 0 0 0 1 +BAC050 CIRCULAR 4.0000 0 0 0 1 +BAC051 CIRCULAR 4.0000 0 0 0 1 +BAC052 CIRCULAR 4.0000 0 0 0 1 +BAC053 CIRCULAR 4.0000 0 0 0 1 +BAC054 CIRCULAR 4.0000 0 0 0 1 +BAC055 CIRCULAR 4.0000 0 0 0 1 +BAC056 CIRCULAR 4.0000 0 0 0 1 +BAC057 CIRCULAR 4.0000 0 0 0 1 +BAC058 CIRCULAR 4.0000 0 0 0 1 +BAC059 CIRCULAR 4.0000 0 0 0 1 +BAC060 CIRCULAR 4.0000 0 0 0 1 +BAC061 CIRCULAR 4.0000 0 0 0 1 +BAC062 CIRCULAR 4.0000 0 0 0 1 +BAC063 CIRCULAR 4.0000 0 0 0 1 +BAC064 CIRCULAR 4.0000 0 0 0 1 +BAC065 CIRCULAR 4.0000 0 0 0 1 +BAC066 CIRCULAR 4.0000 0 0 0 1 +BAC067 CIRCULAR 4.0000 0 0 0 1 +BAC068 CIRCULAR 4.0000 0 0 0 1 +BAC069 CIRCULAR 4.0000 0 0 0 1 +BAC070 CIRCULAR 4.0000 0 0 0 1 +BAC071 CIRCULAR 4.0000 0 0 0 1 +BAC072 CIRCULAR 4.0000 0 0 0 1 +BBC000 CIRCULAR 3.5000 0 0 0 1 +BBC001 CIRCULAR 3.5000 0 0 0 1 +BBC002 CIRCULAR 3.5000 0 0 0 1 +BBC003 CIRCULAR 3.5000 0 0 0 1 +BBC004 CIRCULAR 3.5000 0 0 0 1 +BBC005 CIRCULAR 3.5000 0 0 0 1 +BBC006 CIRCULAR 3.5000 0 0 0 1 +BBC007 CIRCULAR 3.5000 0 0 0 1 +BBC008 CIRCULAR 3.5000 0 0 0 1 +BBC009 CIRCULAR 3.5000 0 0 0 1 +BBC010 CIRCULAR 3.5000 0 0 0 1 +BBC011 CIRCULAR 3.5000 0 0 0 1 +BBC012 CIRCULAR 3.5000 0 0 0 1 +BBC013 CIRCULAR 3.5000 0 0 0 1 +BBC014 CIRCULAR 3.5000 0 0 0 1 +BBC015 CIRCULAR 3.5000 0 0 0 1 +BBC016 CIRCULAR 3.5000 0 0 0 1 +BBC017 CIRCULAR 3.5000 0 0 0 1 +BBC018 CIRCULAR 3.5000 0 0 0 1 +BBC019 CIRCULAR 3.5000 0 0 0 1 +BBC020 CIRCULAR 3.5000 0 0 0 1 +BBC021 CIRCULAR 3.5000 0 0 0 1 +BBC022 CIRCULAR 3.5000 0 0 0 1 +BBC023 CIRCULAR 3.5000 0 0 0 1 +BBC024 CIRCULAR 3.5000 0 0 0 1 +BBC025 CIRCULAR 3.5000 0 0 0 1 +BBC026 CIRCULAR 3.5000 0 0 0 1 +BBC027 CIRCULAR 3.5000 0 0 0 1 +BBC028 CIRCULAR 3.5000 0 0 0 1 +BBC029 CIRCULAR 3.5000 0 0 0 1 +BBC030 CIRCULAR 3.5000 0 0 0 1 +BBC031 CIRCULAR 3.5000 0 0 0 1 +BBC032 CIRCULAR 3.5000 0 0 0 1 +BBC033 CIRCULAR 3.5000 0 0 0 1 +BBC034 CIRCULAR 3.5000 0 0 0 1 +BBC035 CIRCULAR 3.5000 0 0 0 1 +BBC036 CIRCULAR 3.5000 0 0 0 1 +BBC037 CIRCULAR 3.5000 0 0 0 1 +BBC038 CIRCULAR 3.5000 0 0 0 1 +BBC039 CIRCULAR 3.5000 0 0 0 1 +BBC040 CIRCULAR 3.5000 0 0 0 1 +BBC041 CIRCULAR 3.5000 0 0 0 1 +BBC042 CIRCULAR 3.5000 0 0 0 1 +BBC043 CIRCULAR 3.5000 0 0 0 1 +BBC044 CIRCULAR 3.5000 0 0 0 1 +BBC045 CIRCULAR 3.5000 0 0 0 1 +BBC046 CIRCULAR 3.5000 0 0 0 1 +BBC047 CIRCULAR 3.5000 0 0 0 1 +BBC048 CIRCULAR 3.5000 0 0 0 1 +BBC049 CIRCULAR 3.5000 0 0 0 1 +BBC050 CIRCULAR 3.5000 0 0 0 1 +BBC051 CIRCULAR 3.5000 0 0 0 1 +BBC052 CIRCULAR 3.5000 0 0 0 1 +BBC053 CIRCULAR 3.5000 0 0 0 1 +BBC054 CIRCULAR 3.5000 0 0 0 1 +FRS_Outlet CIRCULAR 3.0000 0 0 0 +FRS_Overflow RECT_CLOSED 4.0000 8 0 0 + +[INFLOWS] +;;Node Constituent TimeSeries Type Mfactor Sfactor +TU0000000 FLOW Trunk_Surge FLOW 1.0 1.0 +BA0000000 FLOW BranchA_Surge FLOW 1.0 1.0 +BB0000000 FLOW BranchB_Surge FLOW 1.0 1.0 + +[TIMESERIES] +;;Name Time Value +Trunk_Surge 0:00 12.00 +Trunk_Surge 1:00 12.00 +Trunk_Surge 2:30 140.00 +Trunk_Surge 4:00 140.00 +Trunk_Surge 7:00 12.00 +Trunk_Surge 13:00 12.00 +Trunk_Surge 14:30 119.00 +Trunk_Surge 16:00 119.00 +Trunk_Surge 19:00 12.00 +Trunk_Surge 24:00 12.00 +BranchA_Surge 0:00 4.00 +BranchA_Surge 1:30 4.00 +BranchA_Surge 3:00 45.00 +BranchA_Surge 4:30 45.00 +BranchA_Surge 7:30 4.00 +BranchA_Surge 13:30 4.00 +BranchA_Surge 15:00 38.25 +BranchA_Surge 16:30 38.25 +BranchA_Surge 19:30 4.00 +BranchA_Surge 24:00 4.00 +BranchB_Surge 0:00 3.00 +BranchB_Surge 2:00 3.00 +BranchB_Surge 3:30 30.00 +BranchB_Surge 5:00 30.00 +BranchB_Surge 8:00 3.00 +BranchB_Surge 14:00 3.00 +BranchB_Surge 15:30 25.50 +BranchB_Surge 17:00 25.50 +BranchB_Surge 20:00 3.00 +BranchB_Surge 24:00 3.00 + +[REPORT] +INPUT NO +CONTINUITY YES +FLOWSTATS YES + +[COORDINATES] +;;Node X-Coord Y-Coord +TU0000000 10000.0000 42000.0000 +TU0000124 10073.8205 41900.2800 +TU0000243 10156.9185 41815.2852 +TU0000340 10220.6007 41741.5788 +TU0000435 10283.3950 41671.2223 +TU0000560 10356.6083 41569.1333 +TU0000624 10395.4792 41518.0155 +TU0000722 10464.9438 41449.2218 +TU0000835 10547.6212 41372.9278 +TU0000940 10632.3207 41310.0415 +TU0001043 10708.0571 41239.8732 +TU0001128 10764.8596 41177.6158 +TU0001211 10813.9521 41110.2328 +TU0001310 10870.3222 41029.5914 +TU0001388 10908.4316 40960.6478 +TU0001514 10953.5453 40843.7631 +TU0001586 10982.6549 40777.1957 +TU0001670 11016.9119 40700.7594 +TU0001788 11040.1448 40585.4265 +TU0001904 11069.0347 40472.8096 +TU0001982 11093.6649 40398.8990 +TU0002056 11111.2101 40326.8082 +TU0002136 11122.3169 40247.3126 +TU0002196 11132.3492 40188.0762 +TU0002329 11134.6719 40055.3500 +TU0002403 11149.6388 39982.8838 +TU0002542 11188.6880 39849.3484 +TU0002672 11222.7931 39724.0615 +TU0002811 11262.0352 39591.1814 +TU0002907 11305.5729 39505.3098 +TU0003035 11374.1657 39397.5446 +TU0003158 11437.9782 39292.4475 +TU0003232 11484.7579 39234.3086 +TU0003306 11522.4218 39171.4614 +TU0003428 11585.9682 39066.9776 +TU0003502 11622.4897 39002.6788 +TU0003572 11663.0890 38945.3031 +TU0003633 11703.5059 38899.6435 +TU0003725 11766.0728 38832.2794 +TU0003860 11845.7531 38723.0070 +TU0003925 11887.7320 38673.4674 +TU0004028 11941.9311 38586.6052 +TU0004125 11983.9184 38498.6468 +TU0004230 12017.2934 38398.5791 +TU0004296 12033.8437 38335.4551 +TU0004396 12065.7122 38240.6312 +TU0004532 12102.1910 38109.8762 +TU0004635 12124.4202 38008.3731 +TU0004699 12147.0298 37949.4705 +TU0004824 12173.9653 37827.1135 +TU0004892 12184.1714 37759.4122 +TU0004960 12203.1781 37694.0546 +TU0005034 12211.7267 37620.5296 +TU0005118 12223.1744 37538.1350 +TU0005213 12256.1258 37448.2257 +TU0005350 12310.1425 37322.9620 +TU0005415 12334.8138 37262.8246 +TU0005538 12388.4412 37151.5546 +TU0005612 12405.6674 37079.6093 +TU0005720 12425.7016 36974.1152 +TU0005803 12438.9858 36891.3607 +TU0005888 12445.0220 36806.8182 +TU0005996 12450.7921 36698.6409 +TU0006069 12454.8068 36626.6584 +TU0006204 12475.2055 36492.4747 +TU0006329 12498.7547 36370.0212 +TU0006445 12517.7736 36256.0822 +TU0006547 12542.2851 36156.1498 +TU0006649 12569.5367 36057.7950 +TU0006784 12609.5162 35929.6379 +TU0006922 12653.8701 35798.3267 +TU0007041 12695.3692 35687.2093 +TU0007110 12717.2043 35621.5754 +TU0007249 12785.7861 35500.8049 +TU0007340 12835.8210 35424.4032 +TU0007462 12900.7756 35321.6450 +TU0007577 12967.0260 35227.5143 +TU0007686 13018.6167 35131.7492 +TU0007798 13064.5440 35029.3455 +TU0007917 13094.6194 34914.0893 +TU0008033 13121.3902 34801.7334 +TU0008128 13135.6952 34707.2099 +TU0008196 13150.7840 34641.3075 +TU0008327 13190.2512 34516.4440 +TU0008434 13235.3649 34418.8684 +TU0008546 13290.8947 34322.2902 +TU0008608 13321.9511 34267.7012 +TU0008742 13406.0169 34163.9701 +TU0008847 13455.4112 34071.7857 +TU0008976 13509.9905 33954.0314 +TU0009092 13569.4805 33855.1154 +TU0009193 13613.2480 33763.3855 +TU0009260 13639.4886 33701.8293 +TU0009338 13663.6922 33627.7394 +TU0009406 13674.2366 33560.9255 +TU0009470 13680.0282 33496.7560 +TU0009608 13665.1476 33360.3441 +TU0009718 13650.3647 33250.9177 +TU0009817 13638.5527 33152.7003 +TM0000096 13645.5548 33056.7994 +TM0000199 13641.5993 32954.2838 +TM0000310 13642.7366 32843.0189 +TM0000381 13626.5307 32773.7223 +TM0000450 13611.3305 32706.1955 +TM0000516 13606.6684 32641.1166 +TM0000580 13605.4309 32576.8524 +TM0000672 13593.8382 32485.5662 +TM0000767 13584.7875 32391.3691 +TM0000872 13593.7783 32286.1148 +TM0000987 13587.5775 32171.7185 +TM0001060 13594.4485 32099.2905 +TM0001158 13610.9349 32002.6433 +TM0001259 13619.7346 31901.6408 +TM0001339 13619.1089 31821.2415 +TM0001460 13617.7382 31700.1378 +TM0001579 13630.2698 31582.4263 +TM0001675 13640.9316 31487.0068 +TM0001742 13658.1546 31421.8055 +TM0001838 13681.7843 31328.9455 +TM0001947 13706.6752 31222.4722 +TM0002081 13728.3974 31090.6315 +TM0002189 13734.3283 30982.6148 +TM0002305 13763.4146 30870.5731 +TM0002412 13779.4292 30764.6901 +TM0002474 13798.7126 30705.8231 +TM0002582 13826.4380 30601.1747 +TM0002713 13846.4527 30472.0861 +TM0002773 13857.1413 30412.5395 +TM0002894 13894.9667 30297.7816 +TM0003030 13916.7741 30163.9116 +TM0003126 13950.7695 30073.8796 +TM0003262 14007.7662 29950.2712 +TM0003352 14047.1579 29869.9861 +TM0003416 14072.0554 29810.1905 +TM0003519 14111.1675 29715.5256 +TM0003585 14135.8268 29653.7234 +TM0003683 14164.8671 29560.6100 +TM0003808 14192.1765 29438.1321 +TM0003923 14211.4125 29325.5749 +TM0004047 14251.0060 29207.6624 +TM0004167 14293.5355 29095.1860 +TM0004263 14326.8201 29005.1909 +TM0004352 14332.5356 28916.9740 +TM0004432 14331.0291 28836.4068 +TM0004544 14327.1721 28724.7135 +TM0004675 14317.3429 28593.7151 +TM0004789 14309.6105 28480.0294 +TM0004865 14321.0657 28405.2898 +TM0004992 14323.8323 28278.6681 +TM0005127 14338.7977 28144.1545 +TM0005252 14361.2371 28020.9935 +TM0005377 14388.3330 27899.0487 +TM0005490 14413.2425 27788.9279 +TM0005578 14421.1598 27701.3552 +TM0005684 14405.2550 27596.6290 +TM0005760 14394.1998 27521.4026 +TM0005872 14370.8945 27411.9139 +TM0005955 14357.3698 27329.3134 +TM0006059 14335.0420 27228.5095 +TM0006123 14319.4570 27165.8439 +TM0006205 14286.3536 27091.4471 +TM0006319 14250.7770 26983.2408 +TM0006413 14214.3433 26896.3674 +TM0006552 14146.1476 26775.3420 +TM0006652 14096.5864 26687.6238 +TM0006717 14066.7469 26629.8654 +TM0006792 14027.1319 26566.9043 +TM0006897 13970.8908 26478.4257 +TM0006959 13940.6125 26423.6962 +TM0007031 13918.6011 26355.8020 +TM0007142 13894.1631 26247.0808 +TM0007238 13870.5491 26154.3177 +TL0000111 13850.3045 26045.5822 +TL0000172 13836.3903 25985.8346 +TL0000258 13813.2679 25903.4352 +TL0000356 13797.8343 25806.0825 +TL0000488 13781.8295 25675.0807 +TL0000569 13766.1169 25595.2053 +TL0000647 13751.2050 25519.5122 +TL0000749 13731.7293 25418.7099 +TL0000830 13709.7110 25340.5764 +TL0000936 13677.3162 25240.2918 +TL0001055 13620.0443 25135.8151 +TL0001128 13589.3226 25069.1216 +TL0001230 13540.2535 24980.5172 +TL0001347 13508.3149 24867.7399 +TL0001419 13474.2495 24803.8151 +TL0001507 13445.3620 24721.1552 +TL0001571 13422.6217 24661.2315 +TL0001682 13373.9768 24561.7600 +TL0001776 13332.7835 24477.0317 +TL0001874 13288.4221 24390.0213 +TL0001991 13231.5598 24287.7694 +TL0002075 13191.2851 24213.7382 +TL0002155 13160.3358 24140.0950 +TL0002282 13085.2308 24037.6859 +TL0002374 13021.4803 23970.5768 +TL0002444 12969.5457 23923.9934 +TL0002551 12896.9917 23845.8925 +TL0002658 12832.6921 23759.4508 +TL0002767 12769.4790 23670.7913 +TL0002880 12713.3740 23572.9518 +TL0002962 12681.4867 23498.0115 +TL0003039 12637.2895 23434.5479 +TL0003126 12582.4887 23366.6435 +TL0003263 12485.2027 23269.8300 +TL0003397 12394.7625 23171.1575 +TL0003471 12347.2036 23114.9137 +TL0003550 12307.7464 23046.8007 +TL0003627 12265.1645 22981.8783 +TL0003696 12226.2354 22925.7944 +TL0003812 12167.7179 22824.6277 +TL0003912 12103.9148 22748.3193 +TL0004035 12005.2815 22674.8349 +TL0004124 11935.2753 22619.6373 +TL0004231 11859.2085 22544.3030 +TL0004323 11787.0285 22487.7093 +TL0004460 11686.7564 22393.6650 +TL0004588 11609.5009 22292.1295 +TL0004707 11540.8185 22195.3802 +TL0004797 11484.6147 22125.0351 +TL0004894 11417.6295 22054.6317 +TL0005003 11343.3521 21973.9674 +TL0005119 11270.7991 21884.2779 +TL0005207 11206.4638 21823.6651 +TL0005323 11122.7327 21743.1439 +TL0005447 11031.6566 21659.1083 +TL0005564 10949.5036 21576.5550 +TL0005637 10896.8053 21525.4862 +TL0005767 10796.6215 21442.5212 +TL0005840 10745.5077 21390.5063 +TL0005912 10703.8348 21332.2574 +TL0006049 10609.4958 21232.5595 +TL0006125 10546.6944 21189.9085 +TL0006238 10446.9323 21135.9350 +TL0006375 10333.6357 21059.8357 +TL0006486 10244.3790 20993.7874 +TL0006608 10137.0248 20936.0278 +TL0006736 10024.4602 20874.9561 +TL0006842 9924.5938 20837.4365 +TL0006906 9863.4111 20819.4269 +TL0006972 9803.5600 20791.9303 +TL0007106 9680.6987 20737.8891 +TL0007246 9557.3667 20671.8415 +TL0007331 9488.0063 20623.6310 +TL0007391 9440.9566 20586.2138 +TL0007482 9372.3739 20526.8296 +TL0007592 9294.9498 20448.0211 +TL0007711 9201.1736 20375.5545 +TL0007780 9148.7451 20329.7367 +TL0007853 9087.9587 20290.3734 +TL0007940 9010.8176 20250.2319 +TL0008058 8910.8609 20185.9549 +TL0008156 8832.8488 20127.3331 +TL0008291 8732.4959 20036.4281 +TL0008415 8642.7230 19951.0062 +TL0008539 8555.2948 19863.0935 +TL0008657 8476.1802 19775.5470 +TL0008764 8398.5225 19701.7018 +FRS_Basin 8357.5557 19651.4865 +BA0000000 16368.2325 39642.9747 +BA0000066 16330.7922 39589.1661 +BA0000147 16275.9306 39528.3299 +BA0000248 16204.4620 39457.7467 +BA0000357 16129.4764 39379.1235 +BA0000491 16052.8690 39268.7393 +BA0000615 15995.3823 39158.7803 +BA0000735 15939.2079 39053.0700 +BA0000822 15911.8750 38970.4977 +BA0000926 15875.1933 38873.2054 +BA0000993 15857.3555 38807.9506 +BA0001132 15823.7464 38673.8404 +BA0001208 15797.5507 38601.7046 +BA0001310 15781.4811 38501.6311 +BA0001448 15758.3687 38365.6675 +BA0001560 15736.1899 38255.4855 +BA0001622 15725.6241 38194.3002 +BA0001740 15686.5143 38083.4053 +BA0001867 15637.1472 37966.1811 +BA0001947 15600.0991 37895.4040 +BA0002065 15544.4121 37791.2149 +BA0002151 15497.6564 37719.3006 +BA0002213 15472.7249 37662.1008 +BA0002283 15441.5314 37599.2975 +BA0002376 15390.1197 37521.5431 +BA0002479 15336.6532 37433.7618 +BA0002576 15297.1815 37344.8522 +BA0002678 15253.6585 37253.1064 +BA0002746 15220.9338 37193.9260 +BA0002849 15174.4823 37101.5919 +BA0002945 15121.4616 37021.0544 +BA0003033 15061.8930 36956.4108 +BA0003095 15037.6950 36900.0516 +BA0003235 15007.3645 36763.5131 +BA0003311 14988.6052 36688.9726 +BA0003404 14973.3060 36597.7494 +BA0003499 14962.5074 36502.7971 +BA0003631 14950.0034 36372.2785 +BA0003743 14945.6667 36260.2048 +BA0003851 14932.5044 36152.2969 +BA0003922 14922.6430 36082.1601 +BA0004020 14903.9339 35986.6308 +BA0004157 14854.1887 35858.9793 +BA0004271 14824.0059 35748.2388 +BA0004410 14768.7240 35620.8218 +BA0004543 14705.7649 35503.5899 +BA0004613 14667.9550 35444.7186 +BA0004710 14620.1651 35360.5272 +BA0004823 14560.3847 35264.5335 +BA0004893 14529.3667 35201.5618 +BA0004985 14484.8960 35121.1432 +BA0005061 14467.1152 35047.5399 +BA0005180 14448.8367 34929.5029 +BA0005279 14423.5891 34834.5628 +BA0005359 14399.4238 34757.7196 +BA0005423 14378.8891 34697.3154 +BA0005511 14341.5846 34617.1342 +BA0005580 14315.7014 34553.4263 +BA0005650 14285.4579 34490.2528 +BA0005767 14231.8902 34386.3861 +BA0005860 14195.2955 34301.1777 +BA0005945 14164.5844 34221.5067 +BA0006053 14139.2074 34116.7737 +BA0006170 14098.2019 34007.1509 +BA0006275 14056.8636 33910.3281 +BA0006413 13996.9578 33786.7228 +BA0006510 13940.0494 33707.5584 +BA0006572 13909.1713 33654.0455 +BA0006702 13850.6709 33538.0304 +BA0006807 13802.1657 33444.9552 +BA0006902 13756.8229 33361.2799 +BA0006971 13728.6723 33298.6604 +BA0007053 13681.9397 33230.5747 +BB0000000 9596.9996 29587.8684 +BB0000130 9717.4147 29538.7729 +BB0000201 9783.8417 29513.1425 +BB0000273 9845.9414 29476.9982 +BB0000335 9904.9863 29457.4295 +BB0000469 10029.5150 29409.6859 +BB0000568 10124.1039 29379.2657 +BB0000668 10210.3674 29328.5056 +BB0000778 10301.9927 29267.2267 +BB0000915 10400.9769 29172.6913 +BB0000981 10449.0279 29127.5316 +BB0001065 10507.2835 29066.8752 +BB0001168 10576.2863 28990.0981 +BB0001229 10616.6046 28945.1841 +BB0001359 10711.8065 28855.8388 +BB0001422 10759.1305 28814.1685 +BB0001540 10849.5662 28739.1888 +BB0001605 10895.3573 28693.2333 +BB0001679 10955.9172 28650.1307 +BB0001817 11069.2676 28570.8005 +BB0001934 11157.7259 28494.9049 +BB0002032 11228.4552 28427.6698 +BB0002116 11289.2663 28369.1428 +BB0002243 11375.2525 28276.3009 +BB0002336 11436.4814 28205.8365 +BB0002415 11488.1147 28145.9400 +BB0002507 11552.5725 28080.1737 +BB0002622 11642.9386 28009.8877 +BB0002721 11721.1291 27948.7146 +BB0002839 11812.2529 27874.2515 +BB0002977 11918.7193 27786.1133 +BB0003079 12003.7943 27729.6473 +BB0003149 12062.3700 27690.6303 +BB0003278 12168.8255 27618.2923 +BB0003350 12228.1783 27578.3154 +BB0003489 12343.8528 27500.4092 +BB0003628 12429.4350 27390.2745 +BB0003736 12490.2868 27301.8378 +BB0003841 12550.4012 27215.4160 +BB0003920 12600.6255 27154.9441 +BB0004045 12699.6156 27078.2673 +BB0004134 12776.8119 27033.3322 +BB0004265 12889.3517 26967.2486 +BB0004326 12944.8398 26942.3177 +BB0004414 13022.8703 26901.1844 +BB0004499 13093.0458 26853.0347 +BB0004614 13197.1957 26803.8375 +BB0004734 13294.8904 26734.6246 +BB0004858 13386.1033 26649.9726 +BB0004953 13458.8814 26589.1820 +BB0005056 13535.9036 26520.1622 +BB0005158 13608.5227 26448.8177 +BB0005220 13647.4612 26400.8083 +BB0005347 13728.1833 26302.6923 +BB0005425 13785.5005 26249.3532 +OUT_RIVER 9257.5557 18951.4865 +OUT_OVERFLOW 9457.5557 19951.4865 diff --git a/docs/figures/decks/cedar_glen/cedar_glen_dw_extran.inp b/docs/figures/decks/cedar_glen/cedar_glen_dw_extran.inp new file mode 100644 index 000000000..ac5c7deb1 --- /dev/null +++ b/docs/figures/decks/cedar_glen/cedar_glen_dw_extran.inp @@ -0,0 +1,1667 @@ +[TITLE] +;;Cedar Glen to FRS -- synthetic conveyance demonstration +;;Generated by generate_model.py (seed 20260816); all data invented. + +[OPTIONS] +;;Option Value +FLOW_UNITS MGD +INFILTRATION HORTON +FLOW_ROUTING DYNWAVE +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING YES +SKIP_STEADY_STATE NO + +START_DATE 01/01/2026 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2026 +REPORT_START_TIME 00:00:00 +END_DATE 01/02/2026 +END_TIME 00:00:00 +REPORT_STEP 0:01:00 +WET_STEP 0:05:00 +DRY_STEP 1:00:00 +ROUTING_STEP 0:00:30 + +INERTIAL_DAMPING PARTIAL +NORMAL_FLOW_LIMITED BOTH +FORCE_MAIN_EQUATION H-W +SURCHARGE_METHOD EXTRAN +VARIABLE_STEP 0.75 +LENGTHENING_STEP 0 +MIN_SURFAREA 0 +MAX_TRIALS 8 +HEAD_TOLERANCE 0.005 +SYS_FLOW_TOL 5 +LAT_FLOW_TOL 5 +MINIMUM_STEP 0.5 + +FV_LTS YES +FV_LTS_MAX_TIERS 4 + + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +TU0000000 468.0000 0.0000 0.0000 40.0000 0.0000 +TU0002672 459.9837 0.0000 0.0000 40.0000 0.0000 +TU0005213 452.3601 0.0000 0.0000 40.0000 0.0000 +TU0007917 447.0146 0.0000 0.0000 40.0000 0.0000 +TU0009817 443.5949 0.0000 0.0000 40.0000 0.0000 +TM0002713 452.3498 0.0000 0.0000 40.0000 0.0000 +TM0005252 442.7143 0.0000 0.0000 40.0000 0.0000 +TM0007238 442.6854 0.0000 0.0000 40.0000 0.0000 +TL0002658 436.8368 0.0000 0.0000 40.0000 0.0000 +TL0005207 430.5798 0.0000 0.0000 40.0000 0.0000 +TL0007853 423.1725 0.0000 0.0000 40.0000 0.0000 +BA0000000 479.1635 0.0000 0.0000 40.0000 0.0000 +BA0002678 463.0955 0.0000 0.0000 40.0000 0.0000 +BA0005279 451.0498 0.0000 0.0000 40.0000 0.0000 +BB0000000 469.8142 0.0000 0.0000 40.0000 0.0000 +BB0002622 455.3955 0.0000 0.0000 40.0000 0.0000 +BB0005220 444.0169 0.0000 0.0000 40.0000 0.0000 + +[VIRTUAL_JUNCTIONS] +;;Name Elev Rim +TU0000124 467.6278 11.0000 +TU0000243 467.2712 11.0000 +TU0000340 466.9790 11.0000 +TU0000435 466.6961 11.0000 +TU0000560 466.3192 11.0000 +TU0000624 466.1265 11.0000 +TU0000722 465.8332 11.0000 +TU0000835 465.4957 11.0000 +TU0000940 465.1792 11.0000 +TU0001043 464.8695 11.0000 +TU0001128 464.6167 11.0000 +TU0001211 464.3666 11.0000 +TU0001310 464.0714 11.0000 +TU0001388 463.8351 11.0000 +TU0001514 463.4592 11.0000 +TU0001586 463.2412 11.0000 +TU0001670 462.9900 11.0000 +TU0001788 462.6370 11.0000 +TU0001904 462.2882 11.0000 +TU0001982 462.0545 11.0000 +TU0002056 461.8319 11.0000 +TU0002136 461.5911 11.0000 +TU0002196 461.4109 11.0000 +TU0002329 461.0126 11.0000 +TU0002403 460.7906 11.0000 +TU0002542 460.3733 11.0000 +TU0002811 459.5681 11.0000 +TU0002907 459.2792 11.0000 +TU0003035 458.8960 11.0000 +TU0003158 458.5271 11.0000 +TU0003232 458.3033 11.0000 +TU0003306 458.0835 11.0000 +TU0003428 457.7166 11.0000 +TU0003502 457.4948 11.0000 +TU0003572 457.2839 11.0000 +TU0003633 457.1010 11.0000 +TU0003725 456.8251 11.0000 +TU0003860 456.4194 11.0000 +TU0003925 456.2246 11.0000 +TU0004028 455.9175 11.0000 +TU0004125 455.6251 11.0000 +TU0004230 455.3086 11.0000 +TU0004296 455.1128 11.0000 +TU0004396 454.8127 11.0000 +TU0004532 454.4055 11.0000 +TU0004635 454.0938 11.0000 +TU0004699 453.9045 11.0000 +TU0004824 453.5286 11.0000 +TU0004892 453.3232 11.0000 +TU0004960 453.1190 11.0000 +TU0005034 452.8970 11.0000 +TU0005118 452.6474 11.0000 +TU0005350 451.9509 11.0000 +TU0005415 451.7559 11.0000 +TU0005538 451.3853 11.0000 +TU0005612 451.1634 11.0000 +TU0005720 450.9701 11.0000 +TU0005803 450.8193 11.0000 +TU0005888 450.6667 11.0000 +TU0005996 450.4717 11.0000 +TU0006069 450.3419 11.0000 +TU0006204 450.0976 11.0000 +TU0006329 449.8732 11.0000 +TU0006445 449.6652 11.0000 +TU0006547 449.4800 11.0000 +TU0006649 449.2963 11.0000 +TU0006784 449.0547 11.0000 +TU0006922 448.8052 11.0000 +TU0007041 448.5917 11.0000 +TU0007110 448.4672 11.0000 +TU0007249 448.2172 11.0000 +TU0007340 448.0528 11.0000 +TU0007462 447.8340 11.0000 +TU0007577 447.6268 11.0000 +TU0007686 447.4310 11.0000 +TU0007798 447.2290 11.0000 +TU0008033 446.8067 11.0000 +TU0008128 446.6346 11.0000 +TU0008196 446.5129 11.0000 +TU0008327 446.2772 11.0000 +TU0008434 446.0837 11.0000 +TU0008546 445.8831 11.0000 +TU0008608 445.7701 11.0000 +TU0008742 445.5298 11.0000 +TU0008847 445.3415 11.0000 +TU0008976 445.1079 11.0000 +TU0009092 444.9001 11.0000 +TU0009193 444.7172 11.0000 +TU0009260 444.5967 11.0000 +TU0009338 444.4564 11.0000 +TU0009406 444.3347 11.0000 +TU0009470 444.2187 11.0000 +TU0009608 443.9717 11.0000 +TU0009718 443.7729 11.0000 +TM0000096 443.4218 11.5000 +TM0000199 443.2371 11.5000 +TM0000310 443.0369 11.5000 +TM0000381 442.9088 11.5000 +TM0000450 442.7842 11.5000 +TM0000516 442.6667 11.5000 +TM0000580 442.6153 11.5000 +TM0000672 442.5417 11.5000 +TM0000767 442.4660 11.5000 +TM0000872 442.3815 11.5000 +TM0000987 442.2898 11.5000 +TM0001060 442.2316 11.5000 +TM0001158 442.1532 11.5000 +TM0001259 442.0721 11.5000 +TM0001339 442.0077 11.5000 +TM0001460 441.9109 11.5000 +TM0001579 443.7457 11.5000 +TM0001675 445.2339 11.5000 +TM0001742 446.2792 11.5000 +TM0001838 447.7644 11.5000 +TM0001947 449.4592 11.5000 +TM0002081 451.5303 11.5000 +TM0002189 453.2071 11.5000 +TM0002305 455.0013 11.5000 +TM0002412 454.3052 11.5000 +TM0002474 453.9026 11.5000 +TM0002582 453.1989 11.5000 +TM0002773 451.9566 11.5000 +TM0002894 451.1712 11.5000 +TM0003030 450.2895 11.5000 +TM0003126 449.6640 11.5000 +TM0003262 448.7792 11.5000 +TM0003352 448.1980 11.5000 +TM0003416 447.7769 11.5000 +TM0003519 447.1112 11.5000 +TM0003585 446.6787 11.5000 +TM0003683 446.0447 11.5000 +TM0003808 445.2290 11.5000 +TM0003923 444.4868 11.5000 +TM0004047 443.6783 11.5000 +TM0004167 443.5821 11.5000 +TM0004263 443.5053 11.5000 +TM0004352 443.4346 11.5000 +TM0004432 443.3702 11.5000 +TM0004544 443.2807 11.5000 +TM0004675 443.1757 11.5000 +TM0004789 443.0845 11.5000 +TM0004865 443.0240 11.5000 +TM0004992 442.9227 11.5000 +TM0005127 442.8144 11.5000 +TM0005377 442.6143 11.5000 +TM0005490 443.1788 11.5000 +TM0005578 443.6185 11.5000 +TM0005684 444.1481 11.5000 +TM0005760 444.5283 11.5000 +TM0005872 445.0880 11.5000 +TM0005955 445.5065 11.5000 +TM0006059 445.2794 11.5000 +TM0006123 445.1373 11.5000 +TM0006205 444.9581 11.5000 +TM0006319 444.7076 11.5000 +TM0006413 444.5003 11.5000 +TM0006552 444.1947 11.5000 +TM0006652 443.9730 11.5000 +TM0006717 443.8300 11.5000 +TM0006792 443.6664 11.5000 +TM0006897 443.4357 11.5000 +TM0006959 443.2981 11.5000 +TM0007031 443.1411 11.5000 +TM0007142 442.8959 11.5000 +TL0000111 442.4420 12.5000 +TL0000172 442.3071 12.5000 +TL0000258 442.1188 12.5000 +TL0000356 441.9019 12.5000 +TL0000488 441.6116 12.5000 +TL0000569 441.4325 12.5000 +TL0000647 441.2628 12.5000 +TL0000749 441.0369 12.5000 +TL0000830 440.8583 12.5000 +TL0000936 440.6265 12.5000 +TL0001055 440.3643 12.5000 +TL0001128 440.2028 12.5000 +TL0001230 439.9800 12.5000 +TL0001347 439.7221 12.5000 +TL0001419 439.5627 12.5000 +TL0001507 439.3701 12.5000 +TL0001571 439.2291 12.5000 +TL0001682 438.9855 12.5000 +TL0001776 438.7782 12.5000 +TL0001874 438.5634 12.5000 +TL0001991 438.3060 12.5000 +TL0002075 438.1206 12.5000 +TL0002155 437.9448 12.5000 +TL0002282 437.6654 12.5000 +TL0002374 437.4618 12.5000 +TL0002444 437.3083 12.5000 +TL0002551 437.0738 12.5000 +TL0002767 436.5972 12.5000 +TL0002880 436.3491 12.5000 +TL0002962 436.1699 12.5000 +TL0003039 435.9998 12.5000 +TL0003126 435.8078 12.5000 +TL0003263 435.5059 12.5000 +TL0003397 435.2114 12.5000 +TL0003471 435.0493 12.5000 +TL0003550 434.8762 12.5000 +TL0003627 434.7054 12.5000 +TL0003696 434.5552 12.5000 +TL0003812 434.2980 12.5000 +TL0003912 434.0792 12.5000 +TL0004035 433.8086 12.5000 +TL0004124 433.6125 12.5000 +TL0004231 433.3127 12.5000 +TL0004323 433.0559 12.5000 +TL0004460 432.6710 12.5000 +TL0004588 432.3137 12.5000 +TL0004707 431.9815 12.5000 +TL0004797 431.7294 12.5000 +TL0004894 431.4573 12.5000 +TL0005003 431.1503 12.5000 +TL0005119 430.8273 12.5000 +TL0005323 430.2545 12.5000 +TL0005447 429.9075 12.5000 +TL0005564 429.5814 12.5000 +TL0005637 429.3760 12.5000 +TL0005767 429.0117 12.5000 +TL0005840 428.8075 12.5000 +TL0005912 428.6070 12.5000 +TL0006049 428.2227 12.5000 +TL0006125 428.0101 12.5000 +TL0006238 427.6925 12.5000 +TL0006375 427.3104 12.5000 +TL0006486 426.9995 12.5000 +TL0006608 426.6581 12.5000 +TL0006736 426.2996 12.5000 +TL0006842 426.0009 12.5000 +TL0006906 425.8223 12.5000 +TL0006972 425.6378 12.5000 +TL0007106 425.2620 12.5000 +TL0007246 424.8703 12.5000 +TL0007331 424.6338 12.5000 +TL0007391 424.4655 12.5000 +TL0007482 424.2114 12.5000 +TL0007592 423.9021 12.5000 +TL0007711 423.5703 12.5000 +TL0007780 423.3753 12.5000 +TL0007940 422.9291 12.5000 +TL0008058 422.5963 12.5000 +TL0008156 422.3231 12.5000 +TL0008291 421.9439 12.5000 +TL0008415 421.5970 12.5000 +TL0008539 421.2498 12.5000 +TL0008657 420.9194 12.5000 +TL0008764 420.6194 12.5000 +BA0000066 478.7702 9.0000 +BA0000147 478.2787 9.0000 +BA0000248 477.6760 9.0000 +BA0000357 477.0241 9.0000 +BA0000491 476.2179 9.0000 +BA0000615 475.4735 9.0000 +BA0000735 474.7552 9.0000 +BA0000822 474.2333 9.0000 +BA0000926 473.6095 9.0000 +BA0000993 473.2036 9.0000 +BA0001132 472.3740 9.0000 +BA0001208 471.9136 9.0000 +BA0001310 471.3054 9.0000 +BA0001448 470.4780 9.0000 +BA0001560 469.8036 9.0000 +BA0001622 469.4311 9.0000 +BA0001740 468.7255 9.0000 +BA0001867 467.9623 9.0000 +BA0001947 467.4830 9.0000 +BA0002065 466.7742 9.0000 +BA0002151 466.2595 9.0000 +BA0002213 465.8852 9.0000 +BA0002283 465.4644 9.0000 +BA0002376 464.9051 9.0000 +BA0002479 464.2884 9.0000 +BA0002576 463.7048 9.0000 +BA0002746 462.6897 9.0000 +BA0002849 462.0696 9.0000 +BA0002945 461.4910 9.0000 +BA0003033 460.9636 9.0000 +BA0003095 460.5956 9.0000 +BA0003235 459.7564 9.0000 +BA0003311 459.2952 9.0000 +BA0003404 458.7402 9.0000 +BA0003499 458.1668 9.0000 +BA0003631 457.6424 9.0000 +BA0003743 457.1937 9.0000 +BA0003851 456.7589 9.0000 +BA0003922 456.4756 9.0000 +BA0004020 456.0862 9.0000 +BA0004157 455.5382 9.0000 +BA0004271 455.0791 9.0000 +BA0004410 454.5235 9.0000 +BA0004543 453.9913 9.0000 +BA0004613 453.7114 9.0000 +BA0004710 453.3242 9.0000 +BA0004823 452.8718 9.0000 +BA0004893 452.5910 9.0000 +BA0004985 452.2234 9.0000 +BA0005061 451.9206 9.0000 +BA0005180 451.4428 9.0000 +BA0005359 450.7276 9.0000 +BA0005423 450.4724 9.0000 +BA0005511 450.1187 9.0000 +BA0005580 449.8436 9.0000 +BA0005650 449.5635 9.0000 +BA0005767 449.0960 9.0000 +BA0005860 448.7251 9.0000 +BA0005945 448.3835 9.0000 +BA0006053 447.9525 9.0000 +BA0006170 447.4843 9.0000 +BA0006275 447.0632 9.0000 +BA0006413 446.5138 9.0000 +BA0006510 446.1238 9.0000 +BA0006572 445.8766 9.0000 +BA0006702 445.3569 9.0000 +BA0006807 444.9371 9.0000 +BA0006902 444.5564 9.0000 +BA0006971 444.2818 9.0000 +BA0007053 443.9515 9.0000 +BB0000130 469.0989 8.5000 +BB0000201 468.7073 8.5000 +BB0000273 468.3122 8.5000 +BB0000335 467.9700 8.5000 +BB0000469 467.2365 8.5000 +BB0000568 466.6900 8.5000 +BB0000668 466.1395 8.5000 +BB0000778 465.5333 8.5000 +BB0000915 464.7805 8.5000 +BB0000981 464.4178 8.5000 +BB0001065 463.9552 8.5000 +BB0001168 463.3875 8.5000 +BB0001229 463.0555 8.5000 +BB0001359 462.3374 8.5000 +BB0001422 461.9906 8.5000 +BB0001540 461.3445 8.5000 +BB0001605 460.9877 8.5000 +BB0001679 460.5789 8.5000 +BB0001817 459.8179 8.5000 +BB0001934 459.1769 8.5000 +BB0002032 458.6402 8.5000 +BB0002116 458.1760 8.5000 +BB0002243 457.4800 8.5000 +BB0002336 456.9665 8.5000 +BB0002415 456.5316 8.5000 +BB0002507 456.0251 8.5000 +BB0002721 454.8495 8.5000 +BB0002839 454.2022 8.5000 +BB0002977 453.4420 8.5000 +BB0003079 452.8804 8.5000 +BB0003149 452.4933 8.5000 +BB0003278 451.7855 8.5000 +BB0003350 451.4992 8.5000 +BB0003489 450.9414 8.5000 +BB0003628 450.3835 8.5000 +BB0003736 449.9541 8.5000 +BB0003841 449.5330 8.5000 +BB0003920 449.2185 8.5000 +BB0004045 448.7177 8.5000 +BB0004134 448.3604 8.5000 +BB0004265 447.8384 8.5000 +BB0004326 447.5950 8.5000 +BB0004414 447.2422 8.5000 +BB0004499 446.9018 8.5000 +BB0004614 446.4410 8.5000 +BB0004734 445.9621 8.5000 +BB0004858 445.4644 8.5000 +BB0004953 445.0850 8.5000 +BB0005056 444.6714 8.5000 +BB0005158 444.2642 8.5000 +BB0005347 443.5087 8.5000 +BB0005425 443.1955 8.5000 + +[OUTFALLS] +;;Name Elev Type Gated +OUT_RIVER 415.4379 FREE NO +OUT_OVERFLOW 424.4379 FREE NO + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape Coeff Expon Const SurDepth Fevap +FRS_Basin 418.4379 22.0000 2.0000 FUNCTIONAL 0 0 120000 0 0 + +[CONDUITS] +;;Name FromNode ToNode Length Roughness InOffset OutOffset InitFlow MaxFlow +TUC000 TU0000000 TU0000124 124.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC001 TU0000124 TU0000243 118.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC002 TU0000243 TU0000340 97.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC003 TU0000340 TU0000435 94.30 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC004 TU0000435 TU0000560 125.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC005 TU0000560 TU0000624 64.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC006 TU0000624 TU0000722 97.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC007 TU0000722 TU0000835 112.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC008 TU0000835 TU0000940 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC009 TU0000940 TU0001043 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC010 TU0001043 TU0001128 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC011 TU0001128 TU0001211 83.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC012 TU0001211 TU0001310 98.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC013 TU0001310 TU0001388 78.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC014 TU0001388 TU0001514 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC015 TU0001514 TU0001586 72.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC016 TU0001586 TU0001670 83.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC017 TU0001670 TU0001788 117.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC018 TU0001788 TU0001904 116.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC019 TU0001904 TU0001982 77.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC020 TU0001982 TU0002056 74.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC021 TU0002056 TU0002136 80.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC022 TU0002136 TU0002196 60.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC023 TU0002196 TU0002329 132.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC024 TU0002329 TU0002403 74.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC025 TU0002403 TU0002542 139.13 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC026 TU0002542 TU0002672 129.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC027 TU0002672 TU0002811 138.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC028 TU0002811 TU0002907 96.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC029 TU0002907 TU0003035 127.74 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC030 TU0003035 TU0003158 122.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC031 TU0003158 TU0003232 74.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC032 TU0003232 TU0003306 73.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC033 TU0003306 TU0003428 122.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC034 TU0003428 TU0003502 73.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC035 TU0003502 TU0003572 70.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC036 TU0003572 TU0003633 60.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC037 TU0003633 TU0003725 91.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC038 TU0003725 TU0003860 135.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC039 TU0003860 TU0003925 64.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC040 TU0003925 TU0004028 102.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC041 TU0004028 TU0004125 97.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC042 TU0004125 TU0004230 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC043 TU0004230 TU0004296 65.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC044 TU0004296 TU0004396 100.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC045 TU0004396 TU0004532 135.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC046 TU0004532 TU0004635 103.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC047 TU0004635 TU0004699 63.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC048 TU0004699 TU0004824 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC049 TU0004824 TU0004892 68.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC050 TU0004892 TU0004960 68.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC051 TU0004960 TU0005034 74.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC052 TU0005034 TU0005118 83.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC053 TU0005118 TU0005213 95.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC054 TU0005213 TU0005350 136.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC055 TU0005350 TU0005415 65.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC056 TU0005415 TU0005538 123.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC057 TU0005538 TU0005612 73.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC058 TU0005612 TU0005720 107.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC059 TU0005720 TU0005803 83.81 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC060 TU0005803 TU0005888 84.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC061 TU0005888 TU0005996 108.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC062 TU0005996 TU0006069 72.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC063 TU0006069 TU0006204 135.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC064 TU0006204 TU0006329 124.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC065 TU0006329 TU0006445 115.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC066 TU0006445 TU0006547 102.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC067 TU0006547 TU0006649 102.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC068 TU0006649 TU0006784 134.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC069 TU0006784 TU0006922 138.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC070 TU0006922 TU0007041 118.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC071 TU0007041 TU0007110 69.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC072 TU0007110 TU0007249 138.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC073 TU0007249 TU0007340 91.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC074 TU0007340 TU0007462 121.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC075 TU0007462 TU0007577 115.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC076 TU0007577 TU0007686 108.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC077 TU0007686 TU0007798 112.23 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC078 TU0007798 TU0007917 119.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC079 TU0007917 TU0008033 115.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC080 TU0008033 TU0008128 95.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC081 TU0008128 TU0008196 67.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC082 TU0008196 TU0008327 130.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC083 TU0008327 TU0008434 107.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC084 TU0008434 TU0008546 111.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC085 TU0008546 TU0008608 62.80 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC086 TU0008608 TU0008742 133.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC087 TU0008742 TU0008847 104.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC088 TU0008847 TU0008976 129.79 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC089 TU0008976 TU0009092 115.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC090 TU0009092 TU0009193 101.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC091 TU0009193 TU0009260 66.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC092 TU0009260 TU0009338 77.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC093 TU0009338 TU0009406 67.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC094 TU0009406 TU0009470 64.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC095 TU0009470 TU0009608 137.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC096 TU0009608 TU0009718 110.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC097 TU0009718 TU0009817 98.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC000 TU0009817 TM0000096 96.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC001 TM0000096 TM0000199 102.59 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC002 TM0000199 TM0000310 111.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC003 TM0000310 TM0000381 71.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC004 TM0000381 TM0000450 69.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC005 TM0000450 TM0000516 65.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC006 TM0000516 TM0000580 64.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC007 TM0000580 TM0000672 92.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC008 TM0000672 TM0000767 94.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC009 TM0000767 TM0000872 105.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC010 TM0000872 TM0000987 114.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC011 TM0000987 TM0001060 72.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC012 TM0001060 TM0001158 98.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC013 TM0001158 TM0001259 101.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC014 TM0001259 TM0001339 80.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC015 TM0001339 TM0001460 121.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC016 TM0001460 TM0001579 118.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC017 TM0001579 TM0001675 96.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC018 TM0001675 TM0001742 67.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC019 TM0001742 TM0001838 95.82 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC020 TM0001838 TM0001947 109.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC021 TM0001947 TM0002081 133.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC022 TM0002081 TM0002189 108.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC023 TM0002189 TM0002305 115.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC024 TM0002305 TM0002412 107.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC025 TM0002412 TM0002474 61.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC026 TM0002474 TM0002582 108.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC027 TM0002582 TM0002713 130.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC028 TM0002713 TM0002773 60.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC029 TM0002773 TM0002894 120.83 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC030 TM0002894 TM0003030 135.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC031 TM0003030 TM0003126 96.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC032 TM0003126 TM0003262 136.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC033 TM0003262 TM0003352 89.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC034 TM0003352 TM0003416 64.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC035 TM0003416 TM0003519 102.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC036 TM0003519 TM0003585 66.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC037 TM0003585 TM0003683 97.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC038 TM0003683 TM0003808 125.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC039 TM0003808 TM0003923 114.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC040 TM0003923 TM0004047 124.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC041 TM0004047 TM0004167 120.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC042 TM0004167 TM0004263 95.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC043 TM0004263 TM0004352 88.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC044 TM0004352 TM0004432 80.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC045 TM0004432 TM0004544 111.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC046 TM0004544 TM0004675 131.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC047 TM0004675 TM0004789 113.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC048 TM0004789 TM0004865 75.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC049 TM0004865 TM0004992 126.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC050 TM0004992 TM0005127 135.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC051 TM0005127 TM0005252 125.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC052 TM0005252 TM0005377 124.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC053 TM0005377 TM0005490 112.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC054 TM0005490 TM0005578 87.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC055 TM0005578 TM0005684 105.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC056 TM0005684 TM0005760 76.03 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC057 TM0005760 TM0005872 111.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC058 TM0005872 TM0005955 83.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC059 TM0005955 TM0006059 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC060 TM0006059 TM0006123 64.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC061 TM0006123 TM0006205 81.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC062 TM0006205 TM0006319 113.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC063 TM0006319 TM0006413 94.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC064 TM0006413 TM0006552 138.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC065 TM0006552 TM0006652 100.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC066 TM0006652 TM0006717 65.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC067 TM0006717 TM0006792 74.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC068 TM0006792 TM0006897 104.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC069 TM0006897 TM0006959 62.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC070 TM0006959 TM0007031 71.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC071 TM0007031 TM0007142 111.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC072 TM0007142 TM0007238 95.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC000 TM0007238 TL0000111 110.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC001 TL0000111 TL0000172 61.35 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC002 TL0000172 TL0000258 85.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC003 TL0000258 TL0000356 98.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC004 TL0000356 TL0000488 131.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC005 TL0000488 TL0000569 81.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC006 TL0000569 TL0000647 77.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC007 TL0000647 TL0000749 102.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC008 TL0000749 TL0000830 81.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC009 TL0000830 TL0000936 105.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC010 TL0000936 TL0001055 119.14 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC011 TL0001055 TL0001128 73.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC012 TL0001128 TL0001230 101.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC013 TL0001230 TL0001347 117.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC014 TL0001347 TL0001419 72.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC015 TL0001419 TL0001507 87.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC016 TL0001507 TL0001571 64.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC017 TL0001571 TL0001682 110.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC018 TL0001682 TL0001776 94.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC019 TL0001776 TL0001874 97.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC020 TL0001874 TL0001991 117.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC021 TL0001991 TL0002075 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC022 TL0002075 TL0002155 79.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC023 TL0002155 TL0002282 127.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC024 TL0002282 TL0002374 92.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC025 TL0002374 TL0002444 69.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC026 TL0002444 TL0002551 106.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC027 TL0002551 TL0002658 107.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC028 TL0002658 TL0002767 108.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC029 TL0002767 TL0002880 112.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC030 TL0002880 TL0002962 81.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC031 TL0002962 TL0003039 77.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC032 TL0003039 TL0003126 87.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC033 TL0003126 TL0003263 137.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC034 TL0003263 TL0003397 133.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC035 TL0003397 TL0003471 73.66 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC036 TL0003471 TL0003550 78.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC037 TL0003550 TL0003627 77.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC038 TL0003627 TL0003696 68.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC039 TL0003696 TL0003812 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC040 TL0003812 TL0003912 99.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC041 TL0003912 TL0004035 123.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC042 TL0004035 TL0004124 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC043 TL0004124 TL0004231 107.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC044 TL0004231 TL0004323 91.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC045 TL0004323 TL0004460 137.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC046 TL0004460 TL0004588 127.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC047 TL0004588 TL0004707 118.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC048 TL0004707 TL0004797 90.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC049 TL0004797 TL0004894 97.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC050 TL0004894 TL0005003 109.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC051 TL0005003 TL0005119 115.36 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC052 TL0005119 TL0005207 88.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC053 TL0005207 TL0005323 116.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC054 TL0005323 TL0005447 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC055 TL0005447 TL0005564 116.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC056 TL0005564 TL0005637 73.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC057 TL0005637 TL0005767 130.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC058 TL0005767 TL0005840 72.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC059 TL0005840 TL0005912 71.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC060 TL0005912 TL0006049 137.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC061 TL0006049 TL0006125 75.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC062 TL0006125 TL0006238 113.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC063 TL0006238 TL0006375 136.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC064 TL0006375 TL0006486 111.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC065 TL0006486 TL0006608 121.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC066 TL0006608 TL0006736 128.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC067 TL0006736 TL0006842 106.68 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC068 TL0006842 TL0006906 63.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC069 TL0006906 TL0006972 65.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC070 TL0006972 TL0007106 134.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC071 TL0007106 TL0007246 139.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC072 TL0007246 TL0007331 84.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC073 TL0007331 TL0007391 60.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC074 TL0007391 TL0007482 90.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC075 TL0007482 TL0007592 110.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC076 TL0007592 TL0007711 118.51 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC077 TL0007711 TL0007780 69.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC078 TL0007780 TL0007853 72.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC079 TL0007853 TL0007940 86.96 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC080 TL0007940 TL0008058 118.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC081 TL0008058 TL0008156 97.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC082 TL0008156 TL0008291 135.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC083 TL0008291 TL0008415 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC084 TL0008415 TL0008539 123.99 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC085 TL0008539 TL0008657 118.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC086 TL0008657 TL0008764 107.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC087 TL0008764 FRS_Basin 64.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC000 BA0000000 BA0000066 65.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC001 BA0000066 BA0000147 81.92 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC002 BA0000147 BA0000248 100.45 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC003 BA0000248 BA0000357 108.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC004 BA0000357 BA0000491 134.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC005 BA0000491 BA0000615 124.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC006 BA0000615 BA0000735 119.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC007 BA0000735 BA0000822 86.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC008 BA0000822 BA0000926 103.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC009 BA0000926 BA0000993 67.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC010 BA0000993 BA0001132 138.26 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC011 BA0001132 BA0001208 76.74 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC012 BA0001208 BA0001310 101.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC013 BA0001310 BA0001448 137.91 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC014 BA0001448 BA0001560 112.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC015 BA0001560 BA0001622 62.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC016 BA0001622 BA0001740 117.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC017 BA0001740 BA0001867 127.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC018 BA0001867 BA0001947 79.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC019 BA0001947 BA0002065 118.14 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC020 BA0002065 BA0002151 85.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC021 BA0002151 BA0002213 62.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC022 BA0002213 BA0002283 70.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC023 BA0002283 BA0002376 93.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC024 BA0002376 BA0002479 102.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC025 BA0002479 BA0002576 97.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC026 BA0002576 BA0002678 101.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC027 BA0002678 BA0002746 67.63 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC028 BA0002746 BA0002849 103.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC029 BA0002849 BA0002945 96.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC030 BA0002945 BA0003033 87.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC031 BA0003033 BA0003095 61.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC032 BA0003095 BA0003235 139.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC033 BA0003235 BA0003311 76.86 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC034 BA0003311 BA0003404 92.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC035 BA0003404 BA0003499 95.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC036 BA0003499 BA0003631 131.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC037 BA0003631 BA0003743 112.16 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC038 BA0003743 BA0003851 108.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC039 BA0003851 BA0003922 70.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC040 BA0003922 BA0004020 97.34 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC041 BA0004020 BA0004157 137.00 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC042 BA0004157 BA0004271 114.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC043 BA0004271 BA0004410 138.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC044 BA0004410 BA0004543 133.07 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC045 BA0004543 BA0004613 69.97 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC046 BA0004613 BA0004710 96.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC047 BA0004710 BA0004823 113.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC048 BA0004823 BA0004893 70.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC049 BA0004893 BA0004985 91.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC050 BA0004985 BA0005061 75.72 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC051 BA0005061 BA0005180 119.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC052 BA0005180 BA0005279 98.24 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC053 BA0005279 BA0005359 80.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC054 BA0005359 BA0005423 63.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC055 BA0005423 BA0005511 88.43 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC056 BA0005511 BA0005580 68.77 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC057 BA0005580 BA0005650 70.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC058 BA0005650 BA0005767 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC059 BA0005767 BA0005860 92.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC060 BA0005860 BA0005945 85.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC061 BA0005945 BA0006053 107.76 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC062 BA0006053 BA0006170 117.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC063 BA0006170 BA0006275 105.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC064 BA0006275 BA0006413 137.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC065 BA0006413 BA0006510 97.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC066 BA0006510 BA0006572 61.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC067 BA0006572 BA0006702 129.93 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC068 BA0006702 BA0006807 104.96 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC069 BA0006807 BA0006902 95.17 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC070 BA0006902 BA0006971 68.66 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC071 BA0006971 BA0007053 82.58 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC072 BA0007053 TU0009817 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC000 BB0000000 BB0000130 130.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC001 BB0000130 BB0000201 71.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC002 BB0000201 BB0000273 71.85 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC003 BB0000273 BB0000335 62.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC004 BB0000335 BB0000469 133.37 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC005 BB0000469 BB0000568 99.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC006 BB0000568 BB0000668 100.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC007 BB0000668 BB0000778 110.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC008 BB0000778 BB0000915 136.88 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC009 BB0000915 BB0000981 65.94 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC010 BB0000981 BB0001065 84.10 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC011 BB0001065 BB0001168 103.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC012 BB0001168 BB0001229 60.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC013 BB0001229 BB0001359 130.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC014 BB0001359 BB0001422 63.06 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC015 BB0001422 BB0001540 117.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC016 BB0001540 BB0001605 64.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC017 BB0001605 BB0001679 74.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC018 BB0001679 BB0001817 138.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC019 BB0001817 BB0001934 116.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC020 BB0001934 BB0002032 97.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC021 BB0002032 BB0002116 84.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC022 BB0002116 BB0002243 126.54 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC023 BB0002243 BB0002336 93.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC024 BB0002336 BB0002415 79.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC025 BB0002415 BB0002507 92.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC026 BB0002507 BB0002622 114.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC027 BB0002622 BB0002721 99.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC028 BB0002721 BB0002839 117.68 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC029 BB0002839 BB0002977 138.22 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC030 BB0002977 BB0003079 102.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC031 BB0003079 BB0003149 70.38 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC032 BB0003149 BB0003278 128.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC033 BB0003278 BB0003350 71.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC034 BB0003350 BB0003489 139.46 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC035 BB0003489 BB0003628 139.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC036 BB0003628 BB0003736 107.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC037 BB0003736 BB0003841 105.27 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC038 BB0003841 BB0003920 78.61 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC039 BB0003920 BB0004045 125.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC040 BB0004045 BB0004134 89.32 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC041 BB0004134 BB0004265 130.51 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC042 BB0004265 BB0004326 60.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC043 BB0004326 BB0004414 88.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC044 BB0004414 BB0004499 85.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC045 BB0004499 BB0004614 115.18 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC046 BB0004614 BB0004734 119.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC047 BB0004734 BB0004858 124.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC048 BB0004858 BB0004953 94.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC049 BB0004953 BB0005056 103.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC050 BB0005056 BB0005158 101.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC051 BB0005158 BB0005220 61.82 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC052 BB0005220 BB0005347 127.05 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC053 BB0005347 BB0005425 78.30 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC054 BB0005425 TM0007238 127.53 0.0130 0.0000 0.0000 0.0000 0.0000 + +[ORIFICES] +;;Name FromNode ToNode Type Offset Cd Gated +FRS_Outlet FRS_Basin OUT_RIVER SIDE 0.0000 0.6500 NO +FRS_Overflow FRS_Basin OUT_OVERFLOW SIDE 8.0000 1.0000 NO + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +TUC000 CIRCULAR 6.0000 0 0 0 1 +TUC001 CIRCULAR 6.0000 0 0 0 1 +TUC002 CIRCULAR 6.0000 0 0 0 1 +TUC003 CIRCULAR 6.0000 0 0 0 1 +TUC004 CIRCULAR 6.0000 0 0 0 1 +TUC005 CIRCULAR 6.0000 0 0 0 1 +TUC006 CIRCULAR 6.0000 0 0 0 1 +TUC007 CIRCULAR 6.0000 0 0 0 1 +TUC008 CIRCULAR 6.0000 0 0 0 1 +TUC009 CIRCULAR 6.0000 0 0 0 1 +TUC010 CIRCULAR 6.0000 0 0 0 1 +TUC011 CIRCULAR 6.0000 0 0 0 1 +TUC012 CIRCULAR 6.0000 0 0 0 1 +TUC013 CIRCULAR 6.0000 0 0 0 1 +TUC014 CIRCULAR 6.0000 0 0 0 1 +TUC015 CIRCULAR 6.0000 0 0 0 1 +TUC016 CIRCULAR 6.0000 0 0 0 1 +TUC017 CIRCULAR 6.0000 0 0 0 1 +TUC018 CIRCULAR 6.0000 0 0 0 1 +TUC019 CIRCULAR 6.0000 0 0 0 1 +TUC020 CIRCULAR 6.0000 0 0 0 1 +TUC021 CIRCULAR 6.0000 0 0 0 1 +TUC022 CIRCULAR 6.0000 0 0 0 1 +TUC023 CIRCULAR 6.0000 0 0 0 1 +TUC024 CIRCULAR 6.0000 0 0 0 1 +TUC025 CIRCULAR 6.0000 0 0 0 1 +TUC026 CIRCULAR 6.0000 0 0 0 1 +TUC027 CIRCULAR 6.0000 0 0 0 1 +TUC028 CIRCULAR 6.0000 0 0 0 1 +TUC029 CIRCULAR 6.0000 0 0 0 1 +TUC030 CIRCULAR 6.0000 0 0 0 1 +TUC031 CIRCULAR 6.0000 0 0 0 1 +TUC032 CIRCULAR 6.0000 0 0 0 1 +TUC033 CIRCULAR 6.0000 0 0 0 1 +TUC034 CIRCULAR 6.0000 0 0 0 1 +TUC035 CIRCULAR 6.0000 0 0 0 1 +TUC036 CIRCULAR 6.0000 0 0 0 1 +TUC037 CIRCULAR 6.0000 0 0 0 1 +TUC038 CIRCULAR 6.0000 0 0 0 1 +TUC039 CIRCULAR 6.0000 0 0 0 1 +TUC040 CIRCULAR 6.0000 0 0 0 1 +TUC041 CIRCULAR 6.0000 0 0 0 1 +TUC042 CIRCULAR 6.0000 0 0 0 1 +TUC043 CIRCULAR 6.0000 0 0 0 1 +TUC044 CIRCULAR 6.0000 0 0 0 1 +TUC045 CIRCULAR 6.0000 0 0 0 1 +TUC046 CIRCULAR 6.0000 0 0 0 1 +TUC047 CIRCULAR 6.0000 0 0 0 1 +TUC048 CIRCULAR 6.0000 0 0 0 1 +TUC049 CIRCULAR 6.0000 0 0 0 1 +TUC050 CIRCULAR 6.0000 0 0 0 1 +TUC051 CIRCULAR 6.0000 0 0 0 1 +TUC052 CIRCULAR 6.0000 0 0 0 1 +TUC053 CIRCULAR 6.0000 0 0 0 1 +TUC054 CIRCULAR 6.0000 0 0 0 1 +TUC055 CIRCULAR 6.0000 0 0 0 1 +TUC056 CIRCULAR 6.0000 0 0 0 1 +TUC057 CIRCULAR 6.0000 0 0 0 1 +TUC058 CIRCULAR 6.0000 0 0 0 1 +TUC059 CIRCULAR 6.0000 0 0 0 1 +TUC060 CIRCULAR 6.0000 0 0 0 1 +TUC061 CIRCULAR 6.0000 0 0 0 1 +TUC062 CIRCULAR 6.0000 0 0 0 1 +TUC063 CIRCULAR 6.0000 0 0 0 1 +TUC064 CIRCULAR 6.0000 0 0 0 1 +TUC065 CIRCULAR 6.0000 0 0 0 1 +TUC066 CIRCULAR 6.0000 0 0 0 1 +TUC067 CIRCULAR 6.0000 0 0 0 1 +TUC068 CIRCULAR 6.0000 0 0 0 1 +TUC069 CIRCULAR 6.0000 0 0 0 1 +TUC070 CIRCULAR 6.0000 0 0 0 1 +TUC071 CIRCULAR 6.0000 0 0 0 1 +TUC072 CIRCULAR 6.0000 0 0 0 1 +TUC073 CIRCULAR 6.0000 0 0 0 1 +TUC074 CIRCULAR 6.0000 0 0 0 1 +TUC075 CIRCULAR 6.0000 0 0 0 1 +TUC076 CIRCULAR 6.0000 0 0 0 1 +TUC077 CIRCULAR 6.0000 0 0 0 1 +TUC078 CIRCULAR 6.0000 0 0 0 1 +TUC079 CIRCULAR 6.0000 0 0 0 1 +TUC080 CIRCULAR 6.0000 0 0 0 1 +TUC081 CIRCULAR 6.0000 0 0 0 1 +TUC082 CIRCULAR 6.0000 0 0 0 1 +TUC083 CIRCULAR 6.0000 0 0 0 1 +TUC084 CIRCULAR 6.0000 0 0 0 1 +TUC085 CIRCULAR 6.0000 0 0 0 1 +TUC086 CIRCULAR 6.0000 0 0 0 1 +TUC087 CIRCULAR 6.0000 0 0 0 1 +TUC088 CIRCULAR 6.0000 0 0 0 1 +TUC089 CIRCULAR 6.0000 0 0 0 1 +TUC090 CIRCULAR 6.0000 0 0 0 1 +TUC091 CIRCULAR 6.0000 0 0 0 1 +TUC092 CIRCULAR 6.0000 0 0 0 1 +TUC093 CIRCULAR 6.0000 0 0 0 1 +TUC094 CIRCULAR 6.0000 0 0 0 1 +TUC095 CIRCULAR 6.0000 0 0 0 1 +TUC096 CIRCULAR 6.0000 0 0 0 1 +TUC097 CIRCULAR 6.0000 0 0 0 1 +TMC000 CIRCULAR 6.5000 0 0 0 1 +TMC001 CIRCULAR 6.5000 0 0 0 1 +TMC002 CIRCULAR 6.5000 0 0 0 1 +TMC003 CIRCULAR 6.5000 0 0 0 1 +TMC004 CIRCULAR 6.5000 0 0 0 1 +TMC005 CIRCULAR 6.5000 0 0 0 1 +TMC006 CIRCULAR 6.5000 0 0 0 1 +TMC007 CIRCULAR 6.5000 0 0 0 1 +TMC008 CIRCULAR 6.5000 0 0 0 1 +TMC009 CIRCULAR 6.5000 0 0 0 1 +TMC010 CIRCULAR 6.5000 0 0 0 1 +TMC011 CIRCULAR 6.5000 0 0 0 1 +TMC012 CIRCULAR 6.5000 0 0 0 1 +TMC013 CIRCULAR 6.5000 0 0 0 1 +TMC014 CIRCULAR 6.5000 0 0 0 1 +TMC015 CIRCULAR 6.5000 0 0 0 1 +TMC016 CIRCULAR 6.5000 0 0 0 1 +TMC017 CIRCULAR 6.5000 0 0 0 1 +TMC018 CIRCULAR 6.5000 0 0 0 1 +TMC019 CIRCULAR 6.5000 0 0 0 1 +TMC020 CIRCULAR 6.5000 0 0 0 1 +TMC021 CIRCULAR 6.5000 0 0 0 1 +TMC022 CIRCULAR 6.5000 0 0 0 1 +TMC023 CIRCULAR 6.5000 0 0 0 1 +TMC024 CIRCULAR 6.5000 0 0 0 1 +TMC025 CIRCULAR 6.5000 0 0 0 1 +TMC026 CIRCULAR 6.5000 0 0 0 1 +TMC027 CIRCULAR 6.5000 0 0 0 1 +TMC028 CIRCULAR 6.5000 0 0 0 1 +TMC029 CIRCULAR 6.5000 0 0 0 1 +TMC030 CIRCULAR 6.5000 0 0 0 1 +TMC031 CIRCULAR 6.5000 0 0 0 1 +TMC032 CIRCULAR 6.5000 0 0 0 1 +TMC033 CIRCULAR 6.5000 0 0 0 1 +TMC034 CIRCULAR 6.5000 0 0 0 1 +TMC035 CIRCULAR 6.5000 0 0 0 1 +TMC036 CIRCULAR 6.5000 0 0 0 1 +TMC037 CIRCULAR 6.5000 0 0 0 1 +TMC038 CIRCULAR 6.5000 0 0 0 1 +TMC039 CIRCULAR 6.5000 0 0 0 1 +TMC040 CIRCULAR 6.5000 0 0 0 1 +TMC041 CIRCULAR 6.5000 0 0 0 1 +TMC042 CIRCULAR 6.5000 0 0 0 1 +TMC043 CIRCULAR 6.5000 0 0 0 1 +TMC044 CIRCULAR 6.5000 0 0 0 1 +TMC045 CIRCULAR 6.5000 0 0 0 1 +TMC046 CIRCULAR 6.5000 0 0 0 1 +TMC047 CIRCULAR 6.5000 0 0 0 1 +TMC048 CIRCULAR 6.5000 0 0 0 1 +TMC049 CIRCULAR 6.5000 0 0 0 1 +TMC050 CIRCULAR 6.5000 0 0 0 1 +TMC051 CIRCULAR 6.5000 0 0 0 1 +TMC052 CIRCULAR 6.5000 0 0 0 1 +TMC053 CIRCULAR 6.5000 0 0 0 1 +TMC054 CIRCULAR 6.5000 0 0 0 1 +TMC055 CIRCULAR 6.5000 0 0 0 1 +TMC056 CIRCULAR 6.5000 0 0 0 1 +TMC057 CIRCULAR 6.5000 0 0 0 1 +TMC058 CIRCULAR 6.5000 0 0 0 1 +TMC059 CIRCULAR 6.5000 0 0 0 1 +TMC060 CIRCULAR 6.5000 0 0 0 1 +TMC061 CIRCULAR 6.5000 0 0 0 1 +TMC062 CIRCULAR 6.5000 0 0 0 1 +TMC063 CIRCULAR 6.5000 0 0 0 1 +TMC064 CIRCULAR 6.5000 0 0 0 1 +TMC065 CIRCULAR 6.5000 0 0 0 1 +TMC066 CIRCULAR 6.5000 0 0 0 1 +TMC067 CIRCULAR 6.5000 0 0 0 1 +TMC068 CIRCULAR 6.5000 0 0 0 1 +TMC069 CIRCULAR 6.5000 0 0 0 1 +TMC070 CIRCULAR 6.5000 0 0 0 1 +TMC071 CIRCULAR 6.5000 0 0 0 1 +TMC072 CIRCULAR 6.5000 0 0 0 1 +TLC000 CIRCULAR 7.5000 0 0 0 1 +TLC001 CIRCULAR 7.5000 0 0 0 1 +TLC002 CIRCULAR 7.5000 0 0 0 1 +TLC003 CIRCULAR 7.5000 0 0 0 1 +TLC004 CIRCULAR 7.5000 0 0 0 1 +TLC005 CIRCULAR 7.5000 0 0 0 1 +TLC006 CIRCULAR 7.5000 0 0 0 1 +TLC007 CIRCULAR 7.5000 0 0 0 1 +TLC008 CIRCULAR 7.5000 0 0 0 1 +TLC009 CIRCULAR 7.5000 0 0 0 1 +TLC010 CIRCULAR 7.5000 0 0 0 1 +TLC011 CIRCULAR 7.5000 0 0 0 1 +TLC012 CIRCULAR 7.5000 0 0 0 1 +TLC013 CIRCULAR 7.5000 0 0 0 1 +TLC014 CIRCULAR 7.5000 0 0 0 1 +TLC015 CIRCULAR 7.5000 0 0 0 1 +TLC016 CIRCULAR 7.5000 0 0 0 1 +TLC017 CIRCULAR 7.5000 0 0 0 1 +TLC018 CIRCULAR 7.5000 0 0 0 1 +TLC019 CIRCULAR 7.5000 0 0 0 1 +TLC020 CIRCULAR 7.5000 0 0 0 1 +TLC021 CIRCULAR 7.5000 0 0 0 1 +TLC022 CIRCULAR 7.5000 0 0 0 1 +TLC023 CIRCULAR 7.5000 0 0 0 1 +TLC024 CIRCULAR 7.5000 0 0 0 1 +TLC025 CIRCULAR 7.5000 0 0 0 1 +TLC026 CIRCULAR 7.5000 0 0 0 1 +TLC027 CIRCULAR 7.5000 0 0 0 1 +TLC028 CIRCULAR 7.5000 0 0 0 1 +TLC029 CIRCULAR 7.5000 0 0 0 1 +TLC030 CIRCULAR 7.5000 0 0 0 1 +TLC031 CIRCULAR 7.5000 0 0 0 1 +TLC032 CIRCULAR 7.5000 0 0 0 1 +TLC033 CIRCULAR 7.5000 0 0 0 1 +TLC034 CIRCULAR 7.5000 0 0 0 1 +TLC035 CIRCULAR 7.5000 0 0 0 1 +TLC036 CIRCULAR 7.5000 0 0 0 1 +TLC037 CIRCULAR 7.5000 0 0 0 1 +TLC038 CIRCULAR 7.5000 0 0 0 1 +TLC039 CIRCULAR 7.5000 0 0 0 1 +TLC040 CIRCULAR 7.5000 0 0 0 1 +TLC041 CIRCULAR 7.5000 0 0 0 1 +TLC042 CIRCULAR 7.5000 0 0 0 1 +TLC043 CIRCULAR 7.5000 0 0 0 1 +TLC044 CIRCULAR 7.5000 0 0 0 1 +TLC045 CIRCULAR 7.5000 0 0 0 1 +TLC046 CIRCULAR 7.5000 0 0 0 1 +TLC047 CIRCULAR 7.5000 0 0 0 1 +TLC048 CIRCULAR 7.5000 0 0 0 1 +TLC049 CIRCULAR 7.5000 0 0 0 1 +TLC050 CIRCULAR 7.5000 0 0 0 1 +TLC051 CIRCULAR 7.5000 0 0 0 1 +TLC052 CIRCULAR 7.5000 0 0 0 1 +TLC053 CIRCULAR 7.5000 0 0 0 1 +TLC054 CIRCULAR 7.5000 0 0 0 1 +TLC055 CIRCULAR 7.5000 0 0 0 1 +TLC056 CIRCULAR 7.5000 0 0 0 1 +TLC057 CIRCULAR 7.5000 0 0 0 1 +TLC058 CIRCULAR 7.5000 0 0 0 1 +TLC059 CIRCULAR 7.5000 0 0 0 1 +TLC060 CIRCULAR 7.5000 0 0 0 1 +TLC061 CIRCULAR 7.5000 0 0 0 1 +TLC062 CIRCULAR 7.5000 0 0 0 1 +TLC063 CIRCULAR 7.5000 0 0 0 1 +TLC064 CIRCULAR 7.5000 0 0 0 1 +TLC065 CIRCULAR 7.5000 0 0 0 1 +TLC066 CIRCULAR 7.5000 0 0 0 1 +TLC067 CIRCULAR 7.5000 0 0 0 1 +TLC068 CIRCULAR 7.5000 0 0 0 1 +TLC069 CIRCULAR 7.5000 0 0 0 1 +TLC070 CIRCULAR 7.5000 0 0 0 1 +TLC071 CIRCULAR 7.5000 0 0 0 1 +TLC072 CIRCULAR 7.5000 0 0 0 1 +TLC073 CIRCULAR 7.5000 0 0 0 1 +TLC074 CIRCULAR 7.5000 0 0 0 1 +TLC075 CIRCULAR 7.5000 0 0 0 1 +TLC076 CIRCULAR 7.5000 0 0 0 1 +TLC077 CIRCULAR 7.5000 0 0 0 1 +TLC078 CIRCULAR 7.5000 0 0 0 1 +TLC079 CIRCULAR 7.5000 0 0 0 1 +TLC080 CIRCULAR 7.5000 0 0 0 1 +TLC081 CIRCULAR 7.5000 0 0 0 1 +TLC082 CIRCULAR 7.5000 0 0 0 1 +TLC083 CIRCULAR 7.5000 0 0 0 1 +TLC084 CIRCULAR 7.5000 0 0 0 1 +TLC085 CIRCULAR 7.5000 0 0 0 1 +TLC086 CIRCULAR 7.5000 0 0 0 1 +TLC087 CIRCULAR 7.5000 0 0 0 1 +BAC000 CIRCULAR 4.0000 0 0 0 1 +BAC001 CIRCULAR 4.0000 0 0 0 1 +BAC002 CIRCULAR 4.0000 0 0 0 1 +BAC003 CIRCULAR 4.0000 0 0 0 1 +BAC004 CIRCULAR 4.0000 0 0 0 1 +BAC005 CIRCULAR 4.0000 0 0 0 1 +BAC006 CIRCULAR 4.0000 0 0 0 1 +BAC007 CIRCULAR 4.0000 0 0 0 1 +BAC008 CIRCULAR 4.0000 0 0 0 1 +BAC009 CIRCULAR 4.0000 0 0 0 1 +BAC010 CIRCULAR 4.0000 0 0 0 1 +BAC011 CIRCULAR 4.0000 0 0 0 1 +BAC012 CIRCULAR 4.0000 0 0 0 1 +BAC013 CIRCULAR 4.0000 0 0 0 1 +BAC014 CIRCULAR 4.0000 0 0 0 1 +BAC015 CIRCULAR 4.0000 0 0 0 1 +BAC016 CIRCULAR 4.0000 0 0 0 1 +BAC017 CIRCULAR 4.0000 0 0 0 1 +BAC018 CIRCULAR 4.0000 0 0 0 1 +BAC019 CIRCULAR 4.0000 0 0 0 1 +BAC020 CIRCULAR 4.0000 0 0 0 1 +BAC021 CIRCULAR 4.0000 0 0 0 1 +BAC022 CIRCULAR 4.0000 0 0 0 1 +BAC023 CIRCULAR 4.0000 0 0 0 1 +BAC024 CIRCULAR 4.0000 0 0 0 1 +BAC025 CIRCULAR 4.0000 0 0 0 1 +BAC026 CIRCULAR 4.0000 0 0 0 1 +BAC027 CIRCULAR 4.0000 0 0 0 1 +BAC028 CIRCULAR 4.0000 0 0 0 1 +BAC029 CIRCULAR 4.0000 0 0 0 1 +BAC030 CIRCULAR 4.0000 0 0 0 1 +BAC031 CIRCULAR 4.0000 0 0 0 1 +BAC032 CIRCULAR 4.0000 0 0 0 1 +BAC033 CIRCULAR 4.0000 0 0 0 1 +BAC034 CIRCULAR 4.0000 0 0 0 1 +BAC035 CIRCULAR 4.0000 0 0 0 1 +BAC036 CIRCULAR 4.0000 0 0 0 1 +BAC037 CIRCULAR 4.0000 0 0 0 1 +BAC038 CIRCULAR 4.0000 0 0 0 1 +BAC039 CIRCULAR 4.0000 0 0 0 1 +BAC040 CIRCULAR 4.0000 0 0 0 1 +BAC041 CIRCULAR 4.0000 0 0 0 1 +BAC042 CIRCULAR 4.0000 0 0 0 1 +BAC043 CIRCULAR 4.0000 0 0 0 1 +BAC044 CIRCULAR 4.0000 0 0 0 1 +BAC045 CIRCULAR 4.0000 0 0 0 1 +BAC046 CIRCULAR 4.0000 0 0 0 1 +BAC047 CIRCULAR 4.0000 0 0 0 1 +BAC048 CIRCULAR 4.0000 0 0 0 1 +BAC049 CIRCULAR 4.0000 0 0 0 1 +BAC050 CIRCULAR 4.0000 0 0 0 1 +BAC051 CIRCULAR 4.0000 0 0 0 1 +BAC052 CIRCULAR 4.0000 0 0 0 1 +BAC053 CIRCULAR 4.0000 0 0 0 1 +BAC054 CIRCULAR 4.0000 0 0 0 1 +BAC055 CIRCULAR 4.0000 0 0 0 1 +BAC056 CIRCULAR 4.0000 0 0 0 1 +BAC057 CIRCULAR 4.0000 0 0 0 1 +BAC058 CIRCULAR 4.0000 0 0 0 1 +BAC059 CIRCULAR 4.0000 0 0 0 1 +BAC060 CIRCULAR 4.0000 0 0 0 1 +BAC061 CIRCULAR 4.0000 0 0 0 1 +BAC062 CIRCULAR 4.0000 0 0 0 1 +BAC063 CIRCULAR 4.0000 0 0 0 1 +BAC064 CIRCULAR 4.0000 0 0 0 1 +BAC065 CIRCULAR 4.0000 0 0 0 1 +BAC066 CIRCULAR 4.0000 0 0 0 1 +BAC067 CIRCULAR 4.0000 0 0 0 1 +BAC068 CIRCULAR 4.0000 0 0 0 1 +BAC069 CIRCULAR 4.0000 0 0 0 1 +BAC070 CIRCULAR 4.0000 0 0 0 1 +BAC071 CIRCULAR 4.0000 0 0 0 1 +BAC072 CIRCULAR 4.0000 0 0 0 1 +BBC000 CIRCULAR 3.5000 0 0 0 1 +BBC001 CIRCULAR 3.5000 0 0 0 1 +BBC002 CIRCULAR 3.5000 0 0 0 1 +BBC003 CIRCULAR 3.5000 0 0 0 1 +BBC004 CIRCULAR 3.5000 0 0 0 1 +BBC005 CIRCULAR 3.5000 0 0 0 1 +BBC006 CIRCULAR 3.5000 0 0 0 1 +BBC007 CIRCULAR 3.5000 0 0 0 1 +BBC008 CIRCULAR 3.5000 0 0 0 1 +BBC009 CIRCULAR 3.5000 0 0 0 1 +BBC010 CIRCULAR 3.5000 0 0 0 1 +BBC011 CIRCULAR 3.5000 0 0 0 1 +BBC012 CIRCULAR 3.5000 0 0 0 1 +BBC013 CIRCULAR 3.5000 0 0 0 1 +BBC014 CIRCULAR 3.5000 0 0 0 1 +BBC015 CIRCULAR 3.5000 0 0 0 1 +BBC016 CIRCULAR 3.5000 0 0 0 1 +BBC017 CIRCULAR 3.5000 0 0 0 1 +BBC018 CIRCULAR 3.5000 0 0 0 1 +BBC019 CIRCULAR 3.5000 0 0 0 1 +BBC020 CIRCULAR 3.5000 0 0 0 1 +BBC021 CIRCULAR 3.5000 0 0 0 1 +BBC022 CIRCULAR 3.5000 0 0 0 1 +BBC023 CIRCULAR 3.5000 0 0 0 1 +BBC024 CIRCULAR 3.5000 0 0 0 1 +BBC025 CIRCULAR 3.5000 0 0 0 1 +BBC026 CIRCULAR 3.5000 0 0 0 1 +BBC027 CIRCULAR 3.5000 0 0 0 1 +BBC028 CIRCULAR 3.5000 0 0 0 1 +BBC029 CIRCULAR 3.5000 0 0 0 1 +BBC030 CIRCULAR 3.5000 0 0 0 1 +BBC031 CIRCULAR 3.5000 0 0 0 1 +BBC032 CIRCULAR 3.5000 0 0 0 1 +BBC033 CIRCULAR 3.5000 0 0 0 1 +BBC034 CIRCULAR 3.5000 0 0 0 1 +BBC035 CIRCULAR 3.5000 0 0 0 1 +BBC036 CIRCULAR 3.5000 0 0 0 1 +BBC037 CIRCULAR 3.5000 0 0 0 1 +BBC038 CIRCULAR 3.5000 0 0 0 1 +BBC039 CIRCULAR 3.5000 0 0 0 1 +BBC040 CIRCULAR 3.5000 0 0 0 1 +BBC041 CIRCULAR 3.5000 0 0 0 1 +BBC042 CIRCULAR 3.5000 0 0 0 1 +BBC043 CIRCULAR 3.5000 0 0 0 1 +BBC044 CIRCULAR 3.5000 0 0 0 1 +BBC045 CIRCULAR 3.5000 0 0 0 1 +BBC046 CIRCULAR 3.5000 0 0 0 1 +BBC047 CIRCULAR 3.5000 0 0 0 1 +BBC048 CIRCULAR 3.5000 0 0 0 1 +BBC049 CIRCULAR 3.5000 0 0 0 1 +BBC050 CIRCULAR 3.5000 0 0 0 1 +BBC051 CIRCULAR 3.5000 0 0 0 1 +BBC052 CIRCULAR 3.5000 0 0 0 1 +BBC053 CIRCULAR 3.5000 0 0 0 1 +BBC054 CIRCULAR 3.5000 0 0 0 1 +FRS_Outlet CIRCULAR 3.0000 0 0 0 +FRS_Overflow RECT_CLOSED 4.0000 8 0 0 + +[INFLOWS] +;;Node Constituent TimeSeries Type Mfactor Sfactor +TU0000000 FLOW Trunk_Surge FLOW 1.0 1.0 +BA0000000 FLOW BranchA_Surge FLOW 1.0 1.0 +BB0000000 FLOW BranchB_Surge FLOW 1.0 1.0 + +[TIMESERIES] +;;Name Time Value +Trunk_Surge 0:00 12.00 +Trunk_Surge 1:00 12.00 +Trunk_Surge 2:30 140.00 +Trunk_Surge 4:00 140.00 +Trunk_Surge 7:00 12.00 +Trunk_Surge 13:00 12.00 +Trunk_Surge 14:30 119.00 +Trunk_Surge 16:00 119.00 +Trunk_Surge 19:00 12.00 +Trunk_Surge 24:00 12.00 +BranchA_Surge 0:00 4.00 +BranchA_Surge 1:30 4.00 +BranchA_Surge 3:00 45.00 +BranchA_Surge 4:30 45.00 +BranchA_Surge 7:30 4.00 +BranchA_Surge 13:30 4.00 +BranchA_Surge 15:00 38.25 +BranchA_Surge 16:30 38.25 +BranchA_Surge 19:30 4.00 +BranchA_Surge 24:00 4.00 +BranchB_Surge 0:00 3.00 +BranchB_Surge 2:00 3.00 +BranchB_Surge 3:30 30.00 +BranchB_Surge 5:00 30.00 +BranchB_Surge 8:00 3.00 +BranchB_Surge 14:00 3.00 +BranchB_Surge 15:30 25.50 +BranchB_Surge 17:00 25.50 +BranchB_Surge 20:00 3.00 +BranchB_Surge 24:00 3.00 + +[REPORT] +INPUT NO +CONTINUITY YES +FLOWSTATS YES + +[COORDINATES] +;;Node X-Coord Y-Coord +TU0000000 10000.0000 42000.0000 +TU0000124 10073.8205 41900.2800 +TU0000243 10156.9185 41815.2852 +TU0000340 10220.6007 41741.5788 +TU0000435 10283.3950 41671.2223 +TU0000560 10356.6083 41569.1333 +TU0000624 10395.4792 41518.0155 +TU0000722 10464.9438 41449.2218 +TU0000835 10547.6212 41372.9278 +TU0000940 10632.3207 41310.0415 +TU0001043 10708.0571 41239.8732 +TU0001128 10764.8596 41177.6158 +TU0001211 10813.9521 41110.2328 +TU0001310 10870.3222 41029.5914 +TU0001388 10908.4316 40960.6478 +TU0001514 10953.5453 40843.7631 +TU0001586 10982.6549 40777.1957 +TU0001670 11016.9119 40700.7594 +TU0001788 11040.1448 40585.4265 +TU0001904 11069.0347 40472.8096 +TU0001982 11093.6649 40398.8990 +TU0002056 11111.2101 40326.8082 +TU0002136 11122.3169 40247.3126 +TU0002196 11132.3492 40188.0762 +TU0002329 11134.6719 40055.3500 +TU0002403 11149.6388 39982.8838 +TU0002542 11188.6880 39849.3484 +TU0002672 11222.7931 39724.0615 +TU0002811 11262.0352 39591.1814 +TU0002907 11305.5729 39505.3098 +TU0003035 11374.1657 39397.5446 +TU0003158 11437.9782 39292.4475 +TU0003232 11484.7579 39234.3086 +TU0003306 11522.4218 39171.4614 +TU0003428 11585.9682 39066.9776 +TU0003502 11622.4897 39002.6788 +TU0003572 11663.0890 38945.3031 +TU0003633 11703.5059 38899.6435 +TU0003725 11766.0728 38832.2794 +TU0003860 11845.7531 38723.0070 +TU0003925 11887.7320 38673.4674 +TU0004028 11941.9311 38586.6052 +TU0004125 11983.9184 38498.6468 +TU0004230 12017.2934 38398.5791 +TU0004296 12033.8437 38335.4551 +TU0004396 12065.7122 38240.6312 +TU0004532 12102.1910 38109.8762 +TU0004635 12124.4202 38008.3731 +TU0004699 12147.0298 37949.4705 +TU0004824 12173.9653 37827.1135 +TU0004892 12184.1714 37759.4122 +TU0004960 12203.1781 37694.0546 +TU0005034 12211.7267 37620.5296 +TU0005118 12223.1744 37538.1350 +TU0005213 12256.1258 37448.2257 +TU0005350 12310.1425 37322.9620 +TU0005415 12334.8138 37262.8246 +TU0005538 12388.4412 37151.5546 +TU0005612 12405.6674 37079.6093 +TU0005720 12425.7016 36974.1152 +TU0005803 12438.9858 36891.3607 +TU0005888 12445.0220 36806.8182 +TU0005996 12450.7921 36698.6409 +TU0006069 12454.8068 36626.6584 +TU0006204 12475.2055 36492.4747 +TU0006329 12498.7547 36370.0212 +TU0006445 12517.7736 36256.0822 +TU0006547 12542.2851 36156.1498 +TU0006649 12569.5367 36057.7950 +TU0006784 12609.5162 35929.6379 +TU0006922 12653.8701 35798.3267 +TU0007041 12695.3692 35687.2093 +TU0007110 12717.2043 35621.5754 +TU0007249 12785.7861 35500.8049 +TU0007340 12835.8210 35424.4032 +TU0007462 12900.7756 35321.6450 +TU0007577 12967.0260 35227.5143 +TU0007686 13018.6167 35131.7492 +TU0007798 13064.5440 35029.3455 +TU0007917 13094.6194 34914.0893 +TU0008033 13121.3902 34801.7334 +TU0008128 13135.6952 34707.2099 +TU0008196 13150.7840 34641.3075 +TU0008327 13190.2512 34516.4440 +TU0008434 13235.3649 34418.8684 +TU0008546 13290.8947 34322.2902 +TU0008608 13321.9511 34267.7012 +TU0008742 13406.0169 34163.9701 +TU0008847 13455.4112 34071.7857 +TU0008976 13509.9905 33954.0314 +TU0009092 13569.4805 33855.1154 +TU0009193 13613.2480 33763.3855 +TU0009260 13639.4886 33701.8293 +TU0009338 13663.6922 33627.7394 +TU0009406 13674.2366 33560.9255 +TU0009470 13680.0282 33496.7560 +TU0009608 13665.1476 33360.3441 +TU0009718 13650.3647 33250.9177 +TU0009817 13638.5527 33152.7003 +TM0000096 13645.5548 33056.7994 +TM0000199 13641.5993 32954.2838 +TM0000310 13642.7366 32843.0189 +TM0000381 13626.5307 32773.7223 +TM0000450 13611.3305 32706.1955 +TM0000516 13606.6684 32641.1166 +TM0000580 13605.4309 32576.8524 +TM0000672 13593.8382 32485.5662 +TM0000767 13584.7875 32391.3691 +TM0000872 13593.7783 32286.1148 +TM0000987 13587.5775 32171.7185 +TM0001060 13594.4485 32099.2905 +TM0001158 13610.9349 32002.6433 +TM0001259 13619.7346 31901.6408 +TM0001339 13619.1089 31821.2415 +TM0001460 13617.7382 31700.1378 +TM0001579 13630.2698 31582.4263 +TM0001675 13640.9316 31487.0068 +TM0001742 13658.1546 31421.8055 +TM0001838 13681.7843 31328.9455 +TM0001947 13706.6752 31222.4722 +TM0002081 13728.3974 31090.6315 +TM0002189 13734.3283 30982.6148 +TM0002305 13763.4146 30870.5731 +TM0002412 13779.4292 30764.6901 +TM0002474 13798.7126 30705.8231 +TM0002582 13826.4380 30601.1747 +TM0002713 13846.4527 30472.0861 +TM0002773 13857.1413 30412.5395 +TM0002894 13894.9667 30297.7816 +TM0003030 13916.7741 30163.9116 +TM0003126 13950.7695 30073.8796 +TM0003262 14007.7662 29950.2712 +TM0003352 14047.1579 29869.9861 +TM0003416 14072.0554 29810.1905 +TM0003519 14111.1675 29715.5256 +TM0003585 14135.8268 29653.7234 +TM0003683 14164.8671 29560.6100 +TM0003808 14192.1765 29438.1321 +TM0003923 14211.4125 29325.5749 +TM0004047 14251.0060 29207.6624 +TM0004167 14293.5355 29095.1860 +TM0004263 14326.8201 29005.1909 +TM0004352 14332.5356 28916.9740 +TM0004432 14331.0291 28836.4068 +TM0004544 14327.1721 28724.7135 +TM0004675 14317.3429 28593.7151 +TM0004789 14309.6105 28480.0294 +TM0004865 14321.0657 28405.2898 +TM0004992 14323.8323 28278.6681 +TM0005127 14338.7977 28144.1545 +TM0005252 14361.2371 28020.9935 +TM0005377 14388.3330 27899.0487 +TM0005490 14413.2425 27788.9279 +TM0005578 14421.1598 27701.3552 +TM0005684 14405.2550 27596.6290 +TM0005760 14394.1998 27521.4026 +TM0005872 14370.8945 27411.9139 +TM0005955 14357.3698 27329.3134 +TM0006059 14335.0420 27228.5095 +TM0006123 14319.4570 27165.8439 +TM0006205 14286.3536 27091.4471 +TM0006319 14250.7770 26983.2408 +TM0006413 14214.3433 26896.3674 +TM0006552 14146.1476 26775.3420 +TM0006652 14096.5864 26687.6238 +TM0006717 14066.7469 26629.8654 +TM0006792 14027.1319 26566.9043 +TM0006897 13970.8908 26478.4257 +TM0006959 13940.6125 26423.6962 +TM0007031 13918.6011 26355.8020 +TM0007142 13894.1631 26247.0808 +TM0007238 13870.5491 26154.3177 +TL0000111 13850.3045 26045.5822 +TL0000172 13836.3903 25985.8346 +TL0000258 13813.2679 25903.4352 +TL0000356 13797.8343 25806.0825 +TL0000488 13781.8295 25675.0807 +TL0000569 13766.1169 25595.2053 +TL0000647 13751.2050 25519.5122 +TL0000749 13731.7293 25418.7099 +TL0000830 13709.7110 25340.5764 +TL0000936 13677.3162 25240.2918 +TL0001055 13620.0443 25135.8151 +TL0001128 13589.3226 25069.1216 +TL0001230 13540.2535 24980.5172 +TL0001347 13508.3149 24867.7399 +TL0001419 13474.2495 24803.8151 +TL0001507 13445.3620 24721.1552 +TL0001571 13422.6217 24661.2315 +TL0001682 13373.9768 24561.7600 +TL0001776 13332.7835 24477.0317 +TL0001874 13288.4221 24390.0213 +TL0001991 13231.5598 24287.7694 +TL0002075 13191.2851 24213.7382 +TL0002155 13160.3358 24140.0950 +TL0002282 13085.2308 24037.6859 +TL0002374 13021.4803 23970.5768 +TL0002444 12969.5457 23923.9934 +TL0002551 12896.9917 23845.8925 +TL0002658 12832.6921 23759.4508 +TL0002767 12769.4790 23670.7913 +TL0002880 12713.3740 23572.9518 +TL0002962 12681.4867 23498.0115 +TL0003039 12637.2895 23434.5479 +TL0003126 12582.4887 23366.6435 +TL0003263 12485.2027 23269.8300 +TL0003397 12394.7625 23171.1575 +TL0003471 12347.2036 23114.9137 +TL0003550 12307.7464 23046.8007 +TL0003627 12265.1645 22981.8783 +TL0003696 12226.2354 22925.7944 +TL0003812 12167.7179 22824.6277 +TL0003912 12103.9148 22748.3193 +TL0004035 12005.2815 22674.8349 +TL0004124 11935.2753 22619.6373 +TL0004231 11859.2085 22544.3030 +TL0004323 11787.0285 22487.7093 +TL0004460 11686.7564 22393.6650 +TL0004588 11609.5009 22292.1295 +TL0004707 11540.8185 22195.3802 +TL0004797 11484.6147 22125.0351 +TL0004894 11417.6295 22054.6317 +TL0005003 11343.3521 21973.9674 +TL0005119 11270.7991 21884.2779 +TL0005207 11206.4638 21823.6651 +TL0005323 11122.7327 21743.1439 +TL0005447 11031.6566 21659.1083 +TL0005564 10949.5036 21576.5550 +TL0005637 10896.8053 21525.4862 +TL0005767 10796.6215 21442.5212 +TL0005840 10745.5077 21390.5063 +TL0005912 10703.8348 21332.2574 +TL0006049 10609.4958 21232.5595 +TL0006125 10546.6944 21189.9085 +TL0006238 10446.9323 21135.9350 +TL0006375 10333.6357 21059.8357 +TL0006486 10244.3790 20993.7874 +TL0006608 10137.0248 20936.0278 +TL0006736 10024.4602 20874.9561 +TL0006842 9924.5938 20837.4365 +TL0006906 9863.4111 20819.4269 +TL0006972 9803.5600 20791.9303 +TL0007106 9680.6987 20737.8891 +TL0007246 9557.3667 20671.8415 +TL0007331 9488.0063 20623.6310 +TL0007391 9440.9566 20586.2138 +TL0007482 9372.3739 20526.8296 +TL0007592 9294.9498 20448.0211 +TL0007711 9201.1736 20375.5545 +TL0007780 9148.7451 20329.7367 +TL0007853 9087.9587 20290.3734 +TL0007940 9010.8176 20250.2319 +TL0008058 8910.8609 20185.9549 +TL0008156 8832.8488 20127.3331 +TL0008291 8732.4959 20036.4281 +TL0008415 8642.7230 19951.0062 +TL0008539 8555.2948 19863.0935 +TL0008657 8476.1802 19775.5470 +TL0008764 8398.5225 19701.7018 +FRS_Basin 8357.5557 19651.4865 +BA0000000 16368.2325 39642.9747 +BA0000066 16330.7922 39589.1661 +BA0000147 16275.9306 39528.3299 +BA0000248 16204.4620 39457.7467 +BA0000357 16129.4764 39379.1235 +BA0000491 16052.8690 39268.7393 +BA0000615 15995.3823 39158.7803 +BA0000735 15939.2079 39053.0700 +BA0000822 15911.8750 38970.4977 +BA0000926 15875.1933 38873.2054 +BA0000993 15857.3555 38807.9506 +BA0001132 15823.7464 38673.8404 +BA0001208 15797.5507 38601.7046 +BA0001310 15781.4811 38501.6311 +BA0001448 15758.3687 38365.6675 +BA0001560 15736.1899 38255.4855 +BA0001622 15725.6241 38194.3002 +BA0001740 15686.5143 38083.4053 +BA0001867 15637.1472 37966.1811 +BA0001947 15600.0991 37895.4040 +BA0002065 15544.4121 37791.2149 +BA0002151 15497.6564 37719.3006 +BA0002213 15472.7249 37662.1008 +BA0002283 15441.5314 37599.2975 +BA0002376 15390.1197 37521.5431 +BA0002479 15336.6532 37433.7618 +BA0002576 15297.1815 37344.8522 +BA0002678 15253.6585 37253.1064 +BA0002746 15220.9338 37193.9260 +BA0002849 15174.4823 37101.5919 +BA0002945 15121.4616 37021.0544 +BA0003033 15061.8930 36956.4108 +BA0003095 15037.6950 36900.0516 +BA0003235 15007.3645 36763.5131 +BA0003311 14988.6052 36688.9726 +BA0003404 14973.3060 36597.7494 +BA0003499 14962.5074 36502.7971 +BA0003631 14950.0034 36372.2785 +BA0003743 14945.6667 36260.2048 +BA0003851 14932.5044 36152.2969 +BA0003922 14922.6430 36082.1601 +BA0004020 14903.9339 35986.6308 +BA0004157 14854.1887 35858.9793 +BA0004271 14824.0059 35748.2388 +BA0004410 14768.7240 35620.8218 +BA0004543 14705.7649 35503.5899 +BA0004613 14667.9550 35444.7186 +BA0004710 14620.1651 35360.5272 +BA0004823 14560.3847 35264.5335 +BA0004893 14529.3667 35201.5618 +BA0004985 14484.8960 35121.1432 +BA0005061 14467.1152 35047.5399 +BA0005180 14448.8367 34929.5029 +BA0005279 14423.5891 34834.5628 +BA0005359 14399.4238 34757.7196 +BA0005423 14378.8891 34697.3154 +BA0005511 14341.5846 34617.1342 +BA0005580 14315.7014 34553.4263 +BA0005650 14285.4579 34490.2528 +BA0005767 14231.8902 34386.3861 +BA0005860 14195.2955 34301.1777 +BA0005945 14164.5844 34221.5067 +BA0006053 14139.2074 34116.7737 +BA0006170 14098.2019 34007.1509 +BA0006275 14056.8636 33910.3281 +BA0006413 13996.9578 33786.7228 +BA0006510 13940.0494 33707.5584 +BA0006572 13909.1713 33654.0455 +BA0006702 13850.6709 33538.0304 +BA0006807 13802.1657 33444.9552 +BA0006902 13756.8229 33361.2799 +BA0006971 13728.6723 33298.6604 +BA0007053 13681.9397 33230.5747 +BB0000000 9596.9996 29587.8684 +BB0000130 9717.4147 29538.7729 +BB0000201 9783.8417 29513.1425 +BB0000273 9845.9414 29476.9982 +BB0000335 9904.9863 29457.4295 +BB0000469 10029.5150 29409.6859 +BB0000568 10124.1039 29379.2657 +BB0000668 10210.3674 29328.5056 +BB0000778 10301.9927 29267.2267 +BB0000915 10400.9769 29172.6913 +BB0000981 10449.0279 29127.5316 +BB0001065 10507.2835 29066.8752 +BB0001168 10576.2863 28990.0981 +BB0001229 10616.6046 28945.1841 +BB0001359 10711.8065 28855.8388 +BB0001422 10759.1305 28814.1685 +BB0001540 10849.5662 28739.1888 +BB0001605 10895.3573 28693.2333 +BB0001679 10955.9172 28650.1307 +BB0001817 11069.2676 28570.8005 +BB0001934 11157.7259 28494.9049 +BB0002032 11228.4552 28427.6698 +BB0002116 11289.2663 28369.1428 +BB0002243 11375.2525 28276.3009 +BB0002336 11436.4814 28205.8365 +BB0002415 11488.1147 28145.9400 +BB0002507 11552.5725 28080.1737 +BB0002622 11642.9386 28009.8877 +BB0002721 11721.1291 27948.7146 +BB0002839 11812.2529 27874.2515 +BB0002977 11918.7193 27786.1133 +BB0003079 12003.7943 27729.6473 +BB0003149 12062.3700 27690.6303 +BB0003278 12168.8255 27618.2923 +BB0003350 12228.1783 27578.3154 +BB0003489 12343.8528 27500.4092 +BB0003628 12429.4350 27390.2745 +BB0003736 12490.2868 27301.8378 +BB0003841 12550.4012 27215.4160 +BB0003920 12600.6255 27154.9441 +BB0004045 12699.6156 27078.2673 +BB0004134 12776.8119 27033.3322 +BB0004265 12889.3517 26967.2486 +BB0004326 12944.8398 26942.3177 +BB0004414 13022.8703 26901.1844 +BB0004499 13093.0458 26853.0347 +BB0004614 13197.1957 26803.8375 +BB0004734 13294.8904 26734.6246 +BB0004858 13386.1033 26649.9726 +BB0004953 13458.8814 26589.1820 +BB0005056 13535.9036 26520.1622 +BB0005158 13608.5227 26448.8177 +BB0005220 13647.4612 26400.8083 +BB0005347 13728.1833 26302.6923 +BB0005425 13785.5005 26249.3532 +OUT_RIVER 9257.5557 18951.4865 +OUT_OVERFLOW 9457.5557 19951.4865 diff --git a/docs/figures/decks/cedar_glen/cedar_glen_fv.inp b/docs/figures/decks/cedar_glen/cedar_glen_fv.inp new file mode 100644 index 000000000..b8c4811c6 --- /dev/null +++ b/docs/figures/decks/cedar_glen/cedar_glen_fv.inp @@ -0,0 +1,1667 @@ +[TITLE] +;;Cedar Glen to FRS -- synthetic conveyance demonstration +;;Generated by generate_model.py (seed 20260816); all data invented. + +[OPTIONS] +;;Option Value +FLOW_UNITS MGD +INFILTRATION HORTON +FLOW_ROUTING FV +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING YES +SKIP_STEADY_STATE NO + +START_DATE 01/01/2026 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2026 +REPORT_START_TIME 00:00:00 +END_DATE 01/02/2026 +END_TIME 00:00:00 +REPORT_STEP 0:01:00 +WET_STEP 0:05:00 +DRY_STEP 1:00:00 +ROUTING_STEP 0:00:30 + +INERTIAL_DAMPING PARTIAL +NORMAL_FLOW_LIMITED BOTH +FORCE_MAIN_EQUATION H-W +SURCHARGE_METHOD SLOT +VARIABLE_STEP 0.75 +LENGTHENING_STEP 0 +MIN_SURFAREA 0 +MAX_TRIALS 8 +HEAD_TOLERANCE 0.005 +SYS_FLOW_TOL 5 +LAT_FLOW_TOL 5 +MINIMUM_STEP 0.5 + +FV_LTS YES +FV_LTS_MAX_TIERS 4 + + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +TU0000000 468.0000 0.0000 0.0000 40.0000 0.0000 +TU0002672 459.9837 0.0000 0.0000 40.0000 0.0000 +TU0005213 452.3601 0.0000 0.0000 40.0000 0.0000 +TU0007917 447.0146 0.0000 0.0000 40.0000 0.0000 +TU0009817 443.5949 0.0000 0.0000 40.0000 0.0000 +TM0002713 452.3498 0.0000 0.0000 40.0000 0.0000 +TM0005252 442.7143 0.0000 0.0000 40.0000 0.0000 +TM0007238 442.6854 0.0000 0.0000 40.0000 0.0000 +TL0002658 436.8368 0.0000 0.0000 40.0000 0.0000 +TL0005207 430.5798 0.0000 0.0000 40.0000 0.0000 +TL0007853 423.1725 0.0000 0.0000 40.0000 0.0000 +BA0000000 479.1635 0.0000 0.0000 40.0000 0.0000 +BA0002678 463.0955 0.0000 0.0000 40.0000 0.0000 +BA0005279 451.0498 0.0000 0.0000 40.0000 0.0000 +BB0000000 469.8142 0.0000 0.0000 40.0000 0.0000 +BB0002622 455.3955 0.0000 0.0000 40.0000 0.0000 +BB0005220 444.0169 0.0000 0.0000 40.0000 0.0000 + +[VIRTUAL_JUNCTIONS] +;;Name Elev Rim +TU0000124 467.6278 11.0000 +TU0000243 467.2712 11.0000 +TU0000340 466.9790 11.0000 +TU0000435 466.6961 11.0000 +TU0000560 466.3192 11.0000 +TU0000624 466.1265 11.0000 +TU0000722 465.8332 11.0000 +TU0000835 465.4957 11.0000 +TU0000940 465.1792 11.0000 +TU0001043 464.8695 11.0000 +TU0001128 464.6167 11.0000 +TU0001211 464.3666 11.0000 +TU0001310 464.0714 11.0000 +TU0001388 463.8351 11.0000 +TU0001514 463.4592 11.0000 +TU0001586 463.2412 11.0000 +TU0001670 462.9900 11.0000 +TU0001788 462.6370 11.0000 +TU0001904 462.2882 11.0000 +TU0001982 462.0545 11.0000 +TU0002056 461.8319 11.0000 +TU0002136 461.5911 11.0000 +TU0002196 461.4109 11.0000 +TU0002329 461.0126 11.0000 +TU0002403 460.7906 11.0000 +TU0002542 460.3733 11.0000 +TU0002811 459.5681 11.0000 +TU0002907 459.2792 11.0000 +TU0003035 458.8960 11.0000 +TU0003158 458.5271 11.0000 +TU0003232 458.3033 11.0000 +TU0003306 458.0835 11.0000 +TU0003428 457.7166 11.0000 +TU0003502 457.4948 11.0000 +TU0003572 457.2839 11.0000 +TU0003633 457.1010 11.0000 +TU0003725 456.8251 11.0000 +TU0003860 456.4194 11.0000 +TU0003925 456.2246 11.0000 +TU0004028 455.9175 11.0000 +TU0004125 455.6251 11.0000 +TU0004230 455.3086 11.0000 +TU0004296 455.1128 11.0000 +TU0004396 454.8127 11.0000 +TU0004532 454.4055 11.0000 +TU0004635 454.0938 11.0000 +TU0004699 453.9045 11.0000 +TU0004824 453.5286 11.0000 +TU0004892 453.3232 11.0000 +TU0004960 453.1190 11.0000 +TU0005034 452.8970 11.0000 +TU0005118 452.6474 11.0000 +TU0005350 451.9509 11.0000 +TU0005415 451.7559 11.0000 +TU0005538 451.3853 11.0000 +TU0005612 451.1634 11.0000 +TU0005720 450.9701 11.0000 +TU0005803 450.8193 11.0000 +TU0005888 450.6667 11.0000 +TU0005996 450.4717 11.0000 +TU0006069 450.3419 11.0000 +TU0006204 450.0976 11.0000 +TU0006329 449.8732 11.0000 +TU0006445 449.6652 11.0000 +TU0006547 449.4800 11.0000 +TU0006649 449.2963 11.0000 +TU0006784 449.0547 11.0000 +TU0006922 448.8052 11.0000 +TU0007041 448.5917 11.0000 +TU0007110 448.4672 11.0000 +TU0007249 448.2172 11.0000 +TU0007340 448.0528 11.0000 +TU0007462 447.8340 11.0000 +TU0007577 447.6268 11.0000 +TU0007686 447.4310 11.0000 +TU0007798 447.2290 11.0000 +TU0008033 446.8067 11.0000 +TU0008128 446.6346 11.0000 +TU0008196 446.5129 11.0000 +TU0008327 446.2772 11.0000 +TU0008434 446.0837 11.0000 +TU0008546 445.8831 11.0000 +TU0008608 445.7701 11.0000 +TU0008742 445.5298 11.0000 +TU0008847 445.3415 11.0000 +TU0008976 445.1079 11.0000 +TU0009092 444.9001 11.0000 +TU0009193 444.7172 11.0000 +TU0009260 444.5967 11.0000 +TU0009338 444.4564 11.0000 +TU0009406 444.3347 11.0000 +TU0009470 444.2187 11.0000 +TU0009608 443.9717 11.0000 +TU0009718 443.7729 11.0000 +TM0000096 443.4218 11.5000 +TM0000199 443.2371 11.5000 +TM0000310 443.0369 11.5000 +TM0000381 442.9088 11.5000 +TM0000450 442.7842 11.5000 +TM0000516 442.6667 11.5000 +TM0000580 442.6153 11.5000 +TM0000672 442.5417 11.5000 +TM0000767 442.4660 11.5000 +TM0000872 442.3815 11.5000 +TM0000987 442.2898 11.5000 +TM0001060 442.2316 11.5000 +TM0001158 442.1532 11.5000 +TM0001259 442.0721 11.5000 +TM0001339 442.0077 11.5000 +TM0001460 441.9109 11.5000 +TM0001579 443.7457 11.5000 +TM0001675 445.2339 11.5000 +TM0001742 446.2792 11.5000 +TM0001838 447.7644 11.5000 +TM0001947 449.4592 11.5000 +TM0002081 451.5303 11.5000 +TM0002189 453.2071 11.5000 +TM0002305 455.0013 11.5000 +TM0002412 454.3052 11.5000 +TM0002474 453.9026 11.5000 +TM0002582 453.1989 11.5000 +TM0002773 451.9566 11.5000 +TM0002894 451.1712 11.5000 +TM0003030 450.2895 11.5000 +TM0003126 449.6640 11.5000 +TM0003262 448.7792 11.5000 +TM0003352 448.1980 11.5000 +TM0003416 447.7769 11.5000 +TM0003519 447.1112 11.5000 +TM0003585 446.6787 11.5000 +TM0003683 446.0447 11.5000 +TM0003808 445.2290 11.5000 +TM0003923 444.4868 11.5000 +TM0004047 443.6783 11.5000 +TM0004167 443.5821 11.5000 +TM0004263 443.5053 11.5000 +TM0004352 443.4346 11.5000 +TM0004432 443.3702 11.5000 +TM0004544 443.2807 11.5000 +TM0004675 443.1757 11.5000 +TM0004789 443.0845 11.5000 +TM0004865 443.0240 11.5000 +TM0004992 442.9227 11.5000 +TM0005127 442.8144 11.5000 +TM0005377 442.6143 11.5000 +TM0005490 443.1788 11.5000 +TM0005578 443.6185 11.5000 +TM0005684 444.1481 11.5000 +TM0005760 444.5283 11.5000 +TM0005872 445.0880 11.5000 +TM0005955 445.5065 11.5000 +TM0006059 445.2794 11.5000 +TM0006123 445.1373 11.5000 +TM0006205 444.9581 11.5000 +TM0006319 444.7076 11.5000 +TM0006413 444.5003 11.5000 +TM0006552 444.1947 11.5000 +TM0006652 443.9730 11.5000 +TM0006717 443.8300 11.5000 +TM0006792 443.6664 11.5000 +TM0006897 443.4357 11.5000 +TM0006959 443.2981 11.5000 +TM0007031 443.1411 11.5000 +TM0007142 442.8959 11.5000 +TL0000111 442.4420 12.5000 +TL0000172 442.3071 12.5000 +TL0000258 442.1188 12.5000 +TL0000356 441.9019 12.5000 +TL0000488 441.6116 12.5000 +TL0000569 441.4325 12.5000 +TL0000647 441.2628 12.5000 +TL0000749 441.0369 12.5000 +TL0000830 440.8583 12.5000 +TL0000936 440.6265 12.5000 +TL0001055 440.3643 12.5000 +TL0001128 440.2028 12.5000 +TL0001230 439.9800 12.5000 +TL0001347 439.7221 12.5000 +TL0001419 439.5627 12.5000 +TL0001507 439.3701 12.5000 +TL0001571 439.2291 12.5000 +TL0001682 438.9855 12.5000 +TL0001776 438.7782 12.5000 +TL0001874 438.5634 12.5000 +TL0001991 438.3060 12.5000 +TL0002075 438.1206 12.5000 +TL0002155 437.9448 12.5000 +TL0002282 437.6654 12.5000 +TL0002374 437.4618 12.5000 +TL0002444 437.3083 12.5000 +TL0002551 437.0738 12.5000 +TL0002767 436.5972 12.5000 +TL0002880 436.3491 12.5000 +TL0002962 436.1699 12.5000 +TL0003039 435.9998 12.5000 +TL0003126 435.8078 12.5000 +TL0003263 435.5059 12.5000 +TL0003397 435.2114 12.5000 +TL0003471 435.0493 12.5000 +TL0003550 434.8762 12.5000 +TL0003627 434.7054 12.5000 +TL0003696 434.5552 12.5000 +TL0003812 434.2980 12.5000 +TL0003912 434.0792 12.5000 +TL0004035 433.8086 12.5000 +TL0004124 433.6125 12.5000 +TL0004231 433.3127 12.5000 +TL0004323 433.0559 12.5000 +TL0004460 432.6710 12.5000 +TL0004588 432.3137 12.5000 +TL0004707 431.9815 12.5000 +TL0004797 431.7294 12.5000 +TL0004894 431.4573 12.5000 +TL0005003 431.1503 12.5000 +TL0005119 430.8273 12.5000 +TL0005323 430.2545 12.5000 +TL0005447 429.9075 12.5000 +TL0005564 429.5814 12.5000 +TL0005637 429.3760 12.5000 +TL0005767 429.0117 12.5000 +TL0005840 428.8075 12.5000 +TL0005912 428.6070 12.5000 +TL0006049 428.2227 12.5000 +TL0006125 428.0101 12.5000 +TL0006238 427.6925 12.5000 +TL0006375 427.3104 12.5000 +TL0006486 426.9995 12.5000 +TL0006608 426.6581 12.5000 +TL0006736 426.2996 12.5000 +TL0006842 426.0009 12.5000 +TL0006906 425.8223 12.5000 +TL0006972 425.6378 12.5000 +TL0007106 425.2620 12.5000 +TL0007246 424.8703 12.5000 +TL0007331 424.6338 12.5000 +TL0007391 424.4655 12.5000 +TL0007482 424.2114 12.5000 +TL0007592 423.9021 12.5000 +TL0007711 423.5703 12.5000 +TL0007780 423.3753 12.5000 +TL0007940 422.9291 12.5000 +TL0008058 422.5963 12.5000 +TL0008156 422.3231 12.5000 +TL0008291 421.9439 12.5000 +TL0008415 421.5970 12.5000 +TL0008539 421.2498 12.5000 +TL0008657 420.9194 12.5000 +TL0008764 420.6194 12.5000 +BA0000066 478.7702 9.0000 +BA0000147 478.2787 9.0000 +BA0000248 477.6760 9.0000 +BA0000357 477.0241 9.0000 +BA0000491 476.2179 9.0000 +BA0000615 475.4735 9.0000 +BA0000735 474.7552 9.0000 +BA0000822 474.2333 9.0000 +BA0000926 473.6095 9.0000 +BA0000993 473.2036 9.0000 +BA0001132 472.3740 9.0000 +BA0001208 471.9136 9.0000 +BA0001310 471.3054 9.0000 +BA0001448 470.4780 9.0000 +BA0001560 469.8036 9.0000 +BA0001622 469.4311 9.0000 +BA0001740 468.7255 9.0000 +BA0001867 467.9623 9.0000 +BA0001947 467.4830 9.0000 +BA0002065 466.7742 9.0000 +BA0002151 466.2595 9.0000 +BA0002213 465.8852 9.0000 +BA0002283 465.4644 9.0000 +BA0002376 464.9051 9.0000 +BA0002479 464.2884 9.0000 +BA0002576 463.7048 9.0000 +BA0002746 462.6897 9.0000 +BA0002849 462.0696 9.0000 +BA0002945 461.4910 9.0000 +BA0003033 460.9636 9.0000 +BA0003095 460.5956 9.0000 +BA0003235 459.7564 9.0000 +BA0003311 459.2952 9.0000 +BA0003404 458.7402 9.0000 +BA0003499 458.1668 9.0000 +BA0003631 457.6424 9.0000 +BA0003743 457.1937 9.0000 +BA0003851 456.7589 9.0000 +BA0003922 456.4756 9.0000 +BA0004020 456.0862 9.0000 +BA0004157 455.5382 9.0000 +BA0004271 455.0791 9.0000 +BA0004410 454.5235 9.0000 +BA0004543 453.9913 9.0000 +BA0004613 453.7114 9.0000 +BA0004710 453.3242 9.0000 +BA0004823 452.8718 9.0000 +BA0004893 452.5910 9.0000 +BA0004985 452.2234 9.0000 +BA0005061 451.9206 9.0000 +BA0005180 451.4428 9.0000 +BA0005359 450.7276 9.0000 +BA0005423 450.4724 9.0000 +BA0005511 450.1187 9.0000 +BA0005580 449.8436 9.0000 +BA0005650 449.5635 9.0000 +BA0005767 449.0960 9.0000 +BA0005860 448.7251 9.0000 +BA0005945 448.3835 9.0000 +BA0006053 447.9525 9.0000 +BA0006170 447.4843 9.0000 +BA0006275 447.0632 9.0000 +BA0006413 446.5138 9.0000 +BA0006510 446.1238 9.0000 +BA0006572 445.8766 9.0000 +BA0006702 445.3569 9.0000 +BA0006807 444.9371 9.0000 +BA0006902 444.5564 9.0000 +BA0006971 444.2818 9.0000 +BA0007053 443.9515 9.0000 +BB0000130 469.0989 8.5000 +BB0000201 468.7073 8.5000 +BB0000273 468.3122 8.5000 +BB0000335 467.9700 8.5000 +BB0000469 467.2365 8.5000 +BB0000568 466.6900 8.5000 +BB0000668 466.1395 8.5000 +BB0000778 465.5333 8.5000 +BB0000915 464.7805 8.5000 +BB0000981 464.4178 8.5000 +BB0001065 463.9552 8.5000 +BB0001168 463.3875 8.5000 +BB0001229 463.0555 8.5000 +BB0001359 462.3374 8.5000 +BB0001422 461.9906 8.5000 +BB0001540 461.3445 8.5000 +BB0001605 460.9877 8.5000 +BB0001679 460.5789 8.5000 +BB0001817 459.8179 8.5000 +BB0001934 459.1769 8.5000 +BB0002032 458.6402 8.5000 +BB0002116 458.1760 8.5000 +BB0002243 457.4800 8.5000 +BB0002336 456.9665 8.5000 +BB0002415 456.5316 8.5000 +BB0002507 456.0251 8.5000 +BB0002721 454.8495 8.5000 +BB0002839 454.2022 8.5000 +BB0002977 453.4420 8.5000 +BB0003079 452.8804 8.5000 +BB0003149 452.4933 8.5000 +BB0003278 451.7855 8.5000 +BB0003350 451.4992 8.5000 +BB0003489 450.9414 8.5000 +BB0003628 450.3835 8.5000 +BB0003736 449.9541 8.5000 +BB0003841 449.5330 8.5000 +BB0003920 449.2185 8.5000 +BB0004045 448.7177 8.5000 +BB0004134 448.3604 8.5000 +BB0004265 447.8384 8.5000 +BB0004326 447.5950 8.5000 +BB0004414 447.2422 8.5000 +BB0004499 446.9018 8.5000 +BB0004614 446.4410 8.5000 +BB0004734 445.9621 8.5000 +BB0004858 445.4644 8.5000 +BB0004953 445.0850 8.5000 +BB0005056 444.6714 8.5000 +BB0005158 444.2642 8.5000 +BB0005347 443.5087 8.5000 +BB0005425 443.1955 8.5000 + +[OUTFALLS] +;;Name Elev Type Gated +OUT_RIVER 415.4379 FREE NO +OUT_OVERFLOW 424.4379 FREE NO + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape Coeff Expon Const SurDepth Fevap +FRS_Basin 418.4379 22.0000 2.0000 FUNCTIONAL 0 0 120000 0 0 + +[CONDUITS] +;;Name FromNode ToNode Length Roughness InOffset OutOffset InitFlow MaxFlow +TUC000 TU0000000 TU0000124 124.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC001 TU0000124 TU0000243 118.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC002 TU0000243 TU0000340 97.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC003 TU0000340 TU0000435 94.30 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC004 TU0000435 TU0000560 125.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC005 TU0000560 TU0000624 64.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC006 TU0000624 TU0000722 97.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC007 TU0000722 TU0000835 112.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC008 TU0000835 TU0000940 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC009 TU0000940 TU0001043 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC010 TU0001043 TU0001128 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC011 TU0001128 TU0001211 83.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC012 TU0001211 TU0001310 98.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC013 TU0001310 TU0001388 78.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC014 TU0001388 TU0001514 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC015 TU0001514 TU0001586 72.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC016 TU0001586 TU0001670 83.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC017 TU0001670 TU0001788 117.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC018 TU0001788 TU0001904 116.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC019 TU0001904 TU0001982 77.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC020 TU0001982 TU0002056 74.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC021 TU0002056 TU0002136 80.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC022 TU0002136 TU0002196 60.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC023 TU0002196 TU0002329 132.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC024 TU0002329 TU0002403 74.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC025 TU0002403 TU0002542 139.13 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC026 TU0002542 TU0002672 129.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC027 TU0002672 TU0002811 138.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC028 TU0002811 TU0002907 96.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC029 TU0002907 TU0003035 127.74 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC030 TU0003035 TU0003158 122.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC031 TU0003158 TU0003232 74.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC032 TU0003232 TU0003306 73.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC033 TU0003306 TU0003428 122.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC034 TU0003428 TU0003502 73.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC035 TU0003502 TU0003572 70.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC036 TU0003572 TU0003633 60.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC037 TU0003633 TU0003725 91.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC038 TU0003725 TU0003860 135.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC039 TU0003860 TU0003925 64.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC040 TU0003925 TU0004028 102.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC041 TU0004028 TU0004125 97.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC042 TU0004125 TU0004230 105.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC043 TU0004230 TU0004296 65.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC044 TU0004296 TU0004396 100.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC045 TU0004396 TU0004532 135.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC046 TU0004532 TU0004635 103.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC047 TU0004635 TU0004699 63.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC048 TU0004699 TU0004824 125.29 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC049 TU0004824 TU0004892 68.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC050 TU0004892 TU0004960 68.07 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC051 TU0004960 TU0005034 74.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC052 TU0005034 TU0005118 83.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC053 TU0005118 TU0005213 95.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC054 TU0005213 TU0005350 136.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC055 TU0005350 TU0005415 65.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC056 TU0005415 TU0005538 123.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC057 TU0005538 TU0005612 73.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC058 TU0005612 TU0005720 107.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC059 TU0005720 TU0005803 83.81 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC060 TU0005803 TU0005888 84.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC061 TU0005888 TU0005996 108.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC062 TU0005996 TU0006069 72.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC063 TU0006069 TU0006204 135.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC064 TU0006204 TU0006329 124.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC065 TU0006329 TU0006445 115.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC066 TU0006445 TU0006547 102.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC067 TU0006547 TU0006649 102.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC068 TU0006649 TU0006784 134.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC069 TU0006784 TU0006922 138.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC070 TU0006922 TU0007041 118.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC071 TU0007041 TU0007110 69.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC072 TU0007110 TU0007249 138.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC073 TU0007249 TU0007340 91.33 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC074 TU0007340 TU0007462 121.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC075 TU0007462 TU0007577 115.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC076 TU0007577 TU0007686 108.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC077 TU0007686 TU0007798 112.23 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC078 TU0007798 TU0007917 119.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC079 TU0007917 TU0008033 115.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC080 TU0008033 TU0008128 95.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC081 TU0008128 TU0008196 67.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC082 TU0008196 TU0008327 130.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC083 TU0008327 TU0008434 107.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC084 TU0008434 TU0008546 111.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC085 TU0008546 TU0008608 62.80 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC086 TU0008608 TU0008742 133.52 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC087 TU0008742 TU0008847 104.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC088 TU0008847 TU0008976 129.79 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC089 TU0008976 TU0009092 115.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC090 TU0009092 TU0009193 101.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC091 TU0009193 TU0009260 66.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC092 TU0009260 TU0009338 77.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC093 TU0009338 TU0009406 67.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC094 TU0009406 TU0009470 64.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC095 TU0009470 TU0009608 137.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC096 TU0009608 TU0009718 110.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TUC097 TU0009718 TU0009817 98.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC000 TU0009817 TM0000096 96.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC001 TM0000096 TM0000199 102.59 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC002 TM0000199 TM0000310 111.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC003 TM0000310 TM0000381 71.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC004 TM0000381 TM0000450 69.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC005 TM0000450 TM0000516 65.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC006 TM0000516 TM0000580 64.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC007 TM0000580 TM0000672 92.02 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC008 TM0000672 TM0000767 94.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC009 TM0000767 TM0000872 105.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC010 TM0000872 TM0000987 114.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC011 TM0000987 TM0001060 72.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC012 TM0001060 TM0001158 98.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC013 TM0001158 TM0001259 101.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC014 TM0001259 TM0001339 80.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC015 TM0001339 TM0001460 121.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC016 TM0001460 TM0001579 118.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC017 TM0001579 TM0001675 96.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC018 TM0001675 TM0001742 67.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC019 TM0001742 TM0001838 95.82 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC020 TM0001838 TM0001947 109.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC021 TM0001947 TM0002081 133.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC022 TM0002081 TM0002189 108.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC023 TM0002189 TM0002305 115.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC024 TM0002305 TM0002412 107.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC025 TM0002412 TM0002474 61.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC026 TM0002474 TM0002582 108.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC027 TM0002582 TM0002713 130.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC028 TM0002713 TM0002773 60.50 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC029 TM0002773 TM0002894 120.83 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC030 TM0002894 TM0003030 135.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC031 TM0003030 TM0003126 96.24 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC032 TM0003126 TM0003262 136.12 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC033 TM0003262 TM0003352 89.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC034 TM0003352 TM0003416 64.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC035 TM0003416 TM0003519 102.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC036 TM0003519 TM0003585 66.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC037 TM0003585 TM0003683 97.54 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC038 TM0003683 TM0003808 125.49 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC039 TM0003808 TM0003923 114.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC040 TM0003923 TM0004047 124.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC041 TM0004047 TM0004167 120.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC042 TM0004167 TM0004263 95.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC043 TM0004263 TM0004352 88.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC044 TM0004352 TM0004432 80.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC045 TM0004432 TM0004544 111.76 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC046 TM0004544 TM0004675 131.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC047 TM0004675 TM0004789 113.95 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC048 TM0004789 TM0004865 75.61 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC049 TM0004865 TM0004992 126.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC050 TM0004992 TM0005127 135.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC051 TM0005127 TM0005252 125.19 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC052 TM0005252 TM0005377 124.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC053 TM0005377 TM0005490 112.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC054 TM0005490 TM0005578 87.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC055 TM0005578 TM0005684 105.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC056 TM0005684 TM0005760 76.03 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC057 TM0005760 TM0005872 111.94 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC058 TM0005872 TM0005955 83.70 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC059 TM0005955 TM0006059 103.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC060 TM0006059 TM0006123 64.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC061 TM0006123 TM0006205 81.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC062 TM0006205 TM0006319 113.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC063 TM0006319 TM0006413 94.20 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC064 TM0006413 TM0006552 138.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC065 TM0006552 TM0006652 100.75 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC066 TM0006652 TM0006717 65.01 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC067 TM0006717 TM0006792 74.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC068 TM0006792 TM0006897 104.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC069 TM0006897 TM0006959 62.55 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC070 TM0006959 TM0007031 71.37 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC071 TM0007031 TM0007142 111.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TMC072 TM0007142 TM0007238 95.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC000 TM0007238 TL0000111 110.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC001 TL0000111 TL0000172 61.35 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC002 TL0000172 TL0000258 85.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC003 TL0000258 TL0000356 98.57 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC004 TL0000356 TL0000488 131.98 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC005 TL0000488 TL0000569 81.41 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC006 TL0000569 TL0000647 77.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC007 TL0000647 TL0000749 102.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC008 TL0000749 TL0000830 81.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC009 TL0000830 TL0000936 105.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC010 TL0000936 TL0001055 119.14 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC011 TL0001055 TL0001128 73.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC012 TL0001128 TL0001230 101.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC013 TL0001230 TL0001347 117.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC014 TL0001347 TL0001419 72.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC015 TL0001419 TL0001507 87.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC016 TL0001507 TL0001571 64.09 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC017 TL0001571 TL0001682 110.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC018 TL0001682 TL0001776 94.21 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC019 TL0001776 TL0001874 97.67 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC020 TL0001874 TL0001991 117.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC021 TL0001991 TL0002075 84.28 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC022 TL0002075 TL0002155 79.88 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC023 TL0002155 TL0002282 127.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC024 TL0002282 TL0002374 92.56 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC025 TL0002374 TL0002444 69.77 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC026 TL0002444 TL0002551 106.60 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC027 TL0002551 TL0002658 107.73 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC028 TL0002658 TL0002767 108.89 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC029 TL0002767 TL0002880 112.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC030 TL0002880 TL0002962 81.44 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC031 TL0002962 TL0003039 77.34 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC032 TL0003039 TL0003126 87.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC033 TL0003126 TL0003263 137.25 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC034 TL0003263 TL0003397 133.85 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC035 TL0003397 TL0003471 73.66 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC036 TL0003471 TL0003550 78.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC037 TL0003550 TL0003627 77.64 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC038 TL0003627 TL0003696 68.27 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC039 TL0003696 TL0003812 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC040 TL0003812 TL0003912 99.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC041 TL0003912 TL0004035 123.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC042 TL0004035 TL0004124 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC043 TL0004124 TL0004231 107.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC044 TL0004231 TL0004323 91.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC045 TL0004323 TL0004460 137.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC046 TL0004460 TL0004588 127.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC047 TL0004588 TL0004707 118.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC048 TL0004707 TL0004797 90.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC049 TL0004797 TL0004894 97.18 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC050 TL0004894 TL0005003 109.65 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC051 TL0005003 TL0005119 115.36 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC052 TL0005119 TL0005207 88.39 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC053 TL0005207 TL0005323 116.17 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC054 TL0005323 TL0005447 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC055 TL0005447 TL0005564 116.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC056 TL0005564 TL0005637 73.38 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC057 TL0005637 TL0005767 130.08 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC058 TL0005767 TL0005840 72.93 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC059 TL0005840 TL0005912 71.62 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC060 TL0005912 TL0006049 137.26 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC061 TL0006049 TL0006125 75.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC062 TL0006125 TL0006238 113.43 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC063 TL0006238 TL0006375 136.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC064 TL0006375 TL0006486 111.04 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC065 TL0006486 TL0006608 121.91 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC066 TL0006608 TL0006736 128.06 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC067 TL0006736 TL0006842 106.68 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC068 TL0006842 TL0006906 63.78 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC069 TL0006906 TL0006972 65.87 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC070 TL0006972 TL0007106 134.22 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC071 TL0007106 TL0007246 139.90 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC072 TL0007246 TL0007331 84.47 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC073 TL0007331 TL0007391 60.11 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC074 TL0007391 TL0007482 90.72 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC075 TL0007482 TL0007592 110.48 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC076 TL0007592 TL0007711 118.51 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC077 TL0007711 TL0007780 69.63 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC078 TL0007780 TL0007853 72.42 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC079 TL0007853 TL0007940 86.96 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC080 TL0007940 TL0008058 118.84 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC081 TL0008058 TL0008156 97.58 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC082 TL0008156 TL0008291 135.40 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC083 TL0008291 TL0008415 123.92 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC084 TL0008415 TL0008539 123.99 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC085 TL0008539 TL0008657 118.00 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC086 TL0008657 TL0008764 107.16 0.0130 0.0000 0.0000 0.0000 0.0000 +TLC087 TL0008764 FRS_Basin 64.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC000 BA0000000 BA0000066 65.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC001 BA0000066 BA0000147 81.92 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC002 BA0000147 BA0000248 100.45 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC003 BA0000248 BA0000357 108.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC004 BA0000357 BA0000491 134.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC005 BA0000491 BA0000615 124.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC006 BA0000615 BA0000735 119.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC007 BA0000735 BA0000822 86.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC008 BA0000822 BA0000926 103.98 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC009 BA0000926 BA0000993 67.65 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC010 BA0000993 BA0001132 138.26 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC011 BA0001132 BA0001208 76.74 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC012 BA0001208 BA0001310 101.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC013 BA0001310 BA0001448 137.91 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC014 BA0001448 BA0001560 112.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC015 BA0001560 BA0001622 62.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC016 BA0001622 BA0001740 117.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC017 BA0001740 BA0001867 127.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC018 BA0001867 BA0001947 79.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC019 BA0001947 BA0002065 118.14 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC020 BA0002065 BA0002151 85.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC021 BA0002151 BA0002213 62.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC022 BA0002213 BA0002283 70.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC023 BA0002283 BA0002376 93.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC024 BA0002376 BA0002479 102.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC025 BA0002479 BA0002576 97.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC026 BA0002576 BA0002678 101.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC027 BA0002678 BA0002746 67.63 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC028 BA0002746 BA0002849 103.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC029 BA0002849 BA0002945 96.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC030 BA0002945 BA0003033 87.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC031 BA0003033 BA0003095 61.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC032 BA0003095 BA0003235 139.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC033 BA0003235 BA0003311 76.86 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC034 BA0003311 BA0003404 92.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC035 BA0003404 BA0003499 95.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC036 BA0003499 BA0003631 131.12 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC037 BA0003631 BA0003743 112.16 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC038 BA0003743 BA0003851 108.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC039 BA0003851 BA0003922 70.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC040 BA0003922 BA0004020 97.34 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC041 BA0004020 BA0004157 137.00 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC042 BA0004157 BA0004271 114.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC043 BA0004271 BA0004410 138.89 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC044 BA0004410 BA0004543 133.07 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC045 BA0004543 BA0004613 69.97 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC046 BA0004613 BA0004710 96.81 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC047 BA0004710 BA0004823 113.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC048 BA0004823 BA0004893 70.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC049 BA0004893 BA0004985 91.90 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC050 BA0004985 BA0005061 75.72 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC051 BA0005061 BA0005180 119.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC052 BA0005180 BA0005279 98.24 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC053 BA0005279 BA0005359 80.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC054 BA0005359 BA0005423 63.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC055 BA0005423 BA0005511 88.43 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC056 BA0005511 BA0005580 68.77 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC057 BA0005580 BA0005650 70.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC058 BA0005650 BA0005767 116.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC059 BA0005767 BA0005860 92.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC060 BA0005860 BA0005945 85.39 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC061 BA0005945 BA0006053 107.76 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC062 BA0006053 BA0006170 117.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC063 BA0006170 BA0006275 105.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC064 BA0006275 BA0006413 137.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC065 BA0006413 BA0006510 97.50 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC066 BA0006510 BA0006572 61.78 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC067 BA0006572 BA0006702 129.93 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC068 BA0006702 BA0006807 104.96 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC069 BA0006807 BA0006902 95.17 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC070 BA0006902 BA0006971 68.66 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC071 BA0006971 BA0007053 82.58 0.0130 0.0000 0.0000 0.0000 0.0000 +BAC072 BA0007053 TU0009817 89.15 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC000 BB0000000 BB0000130 130.04 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC001 BB0000130 BB0000201 71.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC002 BB0000201 BB0000273 71.85 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC003 BB0000273 BB0000335 62.20 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC004 BB0000335 BB0000469 133.37 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC005 BB0000469 BB0000568 99.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC006 BB0000568 BB0000668 100.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC007 BB0000668 BB0000778 110.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC008 BB0000778 BB0000915 136.88 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC009 BB0000915 BB0000981 65.94 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC010 BB0000981 BB0001065 84.10 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC011 BB0001065 BB0001168 103.23 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC012 BB0001168 BB0001229 60.36 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC013 BB0001229 BB0001359 130.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC014 BB0001359 BB0001422 63.06 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC015 BB0001422 BB0001540 117.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC016 BB0001540 BB0001605 64.87 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC017 BB0001605 BB0001679 74.33 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC018 BB0001679 BB0001817 138.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC019 BB0001817 BB0001934 116.55 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC020 BB0001934 BB0002032 97.59 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC021 BB0002032 BB0002116 84.40 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC022 BB0002116 BB0002243 126.54 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC023 BB0002243 BB0002336 93.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC024 BB0002336 BB0002415 79.08 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC025 BB0002415 BB0002507 92.09 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC026 BB0002507 BB0002622 114.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC027 BB0002622 BB0002721 99.28 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC028 BB0002721 BB0002839 117.68 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC029 BB0002839 BB0002977 138.22 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC030 BB0002977 BB0003079 102.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC031 BB0003079 BB0003149 70.38 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC032 BB0003149 BB0003278 128.71 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC033 BB0003278 BB0003350 71.56 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC034 BB0003350 BB0003489 139.46 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC035 BB0003489 BB0003628 139.48 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC036 BB0003628 BB0003736 107.35 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC037 BB0003736 BB0003841 105.27 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC038 BB0003841 BB0003920 78.61 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC039 BB0003920 BB0004045 125.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC040 BB0004045 BB0004134 89.32 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC041 BB0004134 BB0004265 130.51 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC042 BB0004265 BB0004326 60.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC043 BB0004326 BB0004414 88.21 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC044 BB0004414 BB0004499 85.11 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC045 BB0004499 BB0004614 115.18 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC046 BB0004614 BB0004734 119.73 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC047 BB0004734 BB0004858 124.44 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC048 BB0004858 BB0004953 94.83 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC049 BB0004953 BB0005056 103.42 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC050 BB0005056 BB0005158 101.80 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC051 BB0005158 BB0005220 61.82 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC052 BB0005220 BB0005347 127.05 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC053 BB0005347 BB0005425 78.30 0.0130 0.0000 0.0000 0.0000 0.0000 +BBC054 BB0005425 TM0007238 127.53 0.0130 0.0000 0.0000 0.0000 0.0000 + +[ORIFICES] +;;Name FromNode ToNode Type Offset Cd Gated +FRS_Outlet FRS_Basin OUT_RIVER SIDE 0.0000 0.6500 NO +FRS_Overflow FRS_Basin OUT_OVERFLOW SIDE 8.0000 1.0000 NO + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +TUC000 CIRCULAR 6.0000 0 0 0 1 +TUC001 CIRCULAR 6.0000 0 0 0 1 +TUC002 CIRCULAR 6.0000 0 0 0 1 +TUC003 CIRCULAR 6.0000 0 0 0 1 +TUC004 CIRCULAR 6.0000 0 0 0 1 +TUC005 CIRCULAR 6.0000 0 0 0 1 +TUC006 CIRCULAR 6.0000 0 0 0 1 +TUC007 CIRCULAR 6.0000 0 0 0 1 +TUC008 CIRCULAR 6.0000 0 0 0 1 +TUC009 CIRCULAR 6.0000 0 0 0 1 +TUC010 CIRCULAR 6.0000 0 0 0 1 +TUC011 CIRCULAR 6.0000 0 0 0 1 +TUC012 CIRCULAR 6.0000 0 0 0 1 +TUC013 CIRCULAR 6.0000 0 0 0 1 +TUC014 CIRCULAR 6.0000 0 0 0 1 +TUC015 CIRCULAR 6.0000 0 0 0 1 +TUC016 CIRCULAR 6.0000 0 0 0 1 +TUC017 CIRCULAR 6.0000 0 0 0 1 +TUC018 CIRCULAR 6.0000 0 0 0 1 +TUC019 CIRCULAR 6.0000 0 0 0 1 +TUC020 CIRCULAR 6.0000 0 0 0 1 +TUC021 CIRCULAR 6.0000 0 0 0 1 +TUC022 CIRCULAR 6.0000 0 0 0 1 +TUC023 CIRCULAR 6.0000 0 0 0 1 +TUC024 CIRCULAR 6.0000 0 0 0 1 +TUC025 CIRCULAR 6.0000 0 0 0 1 +TUC026 CIRCULAR 6.0000 0 0 0 1 +TUC027 CIRCULAR 6.0000 0 0 0 1 +TUC028 CIRCULAR 6.0000 0 0 0 1 +TUC029 CIRCULAR 6.0000 0 0 0 1 +TUC030 CIRCULAR 6.0000 0 0 0 1 +TUC031 CIRCULAR 6.0000 0 0 0 1 +TUC032 CIRCULAR 6.0000 0 0 0 1 +TUC033 CIRCULAR 6.0000 0 0 0 1 +TUC034 CIRCULAR 6.0000 0 0 0 1 +TUC035 CIRCULAR 6.0000 0 0 0 1 +TUC036 CIRCULAR 6.0000 0 0 0 1 +TUC037 CIRCULAR 6.0000 0 0 0 1 +TUC038 CIRCULAR 6.0000 0 0 0 1 +TUC039 CIRCULAR 6.0000 0 0 0 1 +TUC040 CIRCULAR 6.0000 0 0 0 1 +TUC041 CIRCULAR 6.0000 0 0 0 1 +TUC042 CIRCULAR 6.0000 0 0 0 1 +TUC043 CIRCULAR 6.0000 0 0 0 1 +TUC044 CIRCULAR 6.0000 0 0 0 1 +TUC045 CIRCULAR 6.0000 0 0 0 1 +TUC046 CIRCULAR 6.0000 0 0 0 1 +TUC047 CIRCULAR 6.0000 0 0 0 1 +TUC048 CIRCULAR 6.0000 0 0 0 1 +TUC049 CIRCULAR 6.0000 0 0 0 1 +TUC050 CIRCULAR 6.0000 0 0 0 1 +TUC051 CIRCULAR 6.0000 0 0 0 1 +TUC052 CIRCULAR 6.0000 0 0 0 1 +TUC053 CIRCULAR 6.0000 0 0 0 1 +TUC054 CIRCULAR 6.0000 0 0 0 1 +TUC055 CIRCULAR 6.0000 0 0 0 1 +TUC056 CIRCULAR 6.0000 0 0 0 1 +TUC057 CIRCULAR 6.0000 0 0 0 1 +TUC058 CIRCULAR 6.0000 0 0 0 1 +TUC059 CIRCULAR 6.0000 0 0 0 1 +TUC060 CIRCULAR 6.0000 0 0 0 1 +TUC061 CIRCULAR 6.0000 0 0 0 1 +TUC062 CIRCULAR 6.0000 0 0 0 1 +TUC063 CIRCULAR 6.0000 0 0 0 1 +TUC064 CIRCULAR 6.0000 0 0 0 1 +TUC065 CIRCULAR 6.0000 0 0 0 1 +TUC066 CIRCULAR 6.0000 0 0 0 1 +TUC067 CIRCULAR 6.0000 0 0 0 1 +TUC068 CIRCULAR 6.0000 0 0 0 1 +TUC069 CIRCULAR 6.0000 0 0 0 1 +TUC070 CIRCULAR 6.0000 0 0 0 1 +TUC071 CIRCULAR 6.0000 0 0 0 1 +TUC072 CIRCULAR 6.0000 0 0 0 1 +TUC073 CIRCULAR 6.0000 0 0 0 1 +TUC074 CIRCULAR 6.0000 0 0 0 1 +TUC075 CIRCULAR 6.0000 0 0 0 1 +TUC076 CIRCULAR 6.0000 0 0 0 1 +TUC077 CIRCULAR 6.0000 0 0 0 1 +TUC078 CIRCULAR 6.0000 0 0 0 1 +TUC079 CIRCULAR 6.0000 0 0 0 1 +TUC080 CIRCULAR 6.0000 0 0 0 1 +TUC081 CIRCULAR 6.0000 0 0 0 1 +TUC082 CIRCULAR 6.0000 0 0 0 1 +TUC083 CIRCULAR 6.0000 0 0 0 1 +TUC084 CIRCULAR 6.0000 0 0 0 1 +TUC085 CIRCULAR 6.0000 0 0 0 1 +TUC086 CIRCULAR 6.0000 0 0 0 1 +TUC087 CIRCULAR 6.0000 0 0 0 1 +TUC088 CIRCULAR 6.0000 0 0 0 1 +TUC089 CIRCULAR 6.0000 0 0 0 1 +TUC090 CIRCULAR 6.0000 0 0 0 1 +TUC091 CIRCULAR 6.0000 0 0 0 1 +TUC092 CIRCULAR 6.0000 0 0 0 1 +TUC093 CIRCULAR 6.0000 0 0 0 1 +TUC094 CIRCULAR 6.0000 0 0 0 1 +TUC095 CIRCULAR 6.0000 0 0 0 1 +TUC096 CIRCULAR 6.0000 0 0 0 1 +TUC097 CIRCULAR 6.0000 0 0 0 1 +TMC000 CIRCULAR 6.5000 0 0 0 1 +TMC001 CIRCULAR 6.5000 0 0 0 1 +TMC002 CIRCULAR 6.5000 0 0 0 1 +TMC003 CIRCULAR 6.5000 0 0 0 1 +TMC004 CIRCULAR 6.5000 0 0 0 1 +TMC005 CIRCULAR 6.5000 0 0 0 1 +TMC006 CIRCULAR 6.5000 0 0 0 1 +TMC007 CIRCULAR 6.5000 0 0 0 1 +TMC008 CIRCULAR 6.5000 0 0 0 1 +TMC009 CIRCULAR 6.5000 0 0 0 1 +TMC010 CIRCULAR 6.5000 0 0 0 1 +TMC011 CIRCULAR 6.5000 0 0 0 1 +TMC012 CIRCULAR 6.5000 0 0 0 1 +TMC013 CIRCULAR 6.5000 0 0 0 1 +TMC014 CIRCULAR 6.5000 0 0 0 1 +TMC015 CIRCULAR 6.5000 0 0 0 1 +TMC016 CIRCULAR 6.5000 0 0 0 1 +TMC017 CIRCULAR 6.5000 0 0 0 1 +TMC018 CIRCULAR 6.5000 0 0 0 1 +TMC019 CIRCULAR 6.5000 0 0 0 1 +TMC020 CIRCULAR 6.5000 0 0 0 1 +TMC021 CIRCULAR 6.5000 0 0 0 1 +TMC022 CIRCULAR 6.5000 0 0 0 1 +TMC023 CIRCULAR 6.5000 0 0 0 1 +TMC024 CIRCULAR 6.5000 0 0 0 1 +TMC025 CIRCULAR 6.5000 0 0 0 1 +TMC026 CIRCULAR 6.5000 0 0 0 1 +TMC027 CIRCULAR 6.5000 0 0 0 1 +TMC028 CIRCULAR 6.5000 0 0 0 1 +TMC029 CIRCULAR 6.5000 0 0 0 1 +TMC030 CIRCULAR 6.5000 0 0 0 1 +TMC031 CIRCULAR 6.5000 0 0 0 1 +TMC032 CIRCULAR 6.5000 0 0 0 1 +TMC033 CIRCULAR 6.5000 0 0 0 1 +TMC034 CIRCULAR 6.5000 0 0 0 1 +TMC035 CIRCULAR 6.5000 0 0 0 1 +TMC036 CIRCULAR 6.5000 0 0 0 1 +TMC037 CIRCULAR 6.5000 0 0 0 1 +TMC038 CIRCULAR 6.5000 0 0 0 1 +TMC039 CIRCULAR 6.5000 0 0 0 1 +TMC040 CIRCULAR 6.5000 0 0 0 1 +TMC041 CIRCULAR 6.5000 0 0 0 1 +TMC042 CIRCULAR 6.5000 0 0 0 1 +TMC043 CIRCULAR 6.5000 0 0 0 1 +TMC044 CIRCULAR 6.5000 0 0 0 1 +TMC045 CIRCULAR 6.5000 0 0 0 1 +TMC046 CIRCULAR 6.5000 0 0 0 1 +TMC047 CIRCULAR 6.5000 0 0 0 1 +TMC048 CIRCULAR 6.5000 0 0 0 1 +TMC049 CIRCULAR 6.5000 0 0 0 1 +TMC050 CIRCULAR 6.5000 0 0 0 1 +TMC051 CIRCULAR 6.5000 0 0 0 1 +TMC052 CIRCULAR 6.5000 0 0 0 1 +TMC053 CIRCULAR 6.5000 0 0 0 1 +TMC054 CIRCULAR 6.5000 0 0 0 1 +TMC055 CIRCULAR 6.5000 0 0 0 1 +TMC056 CIRCULAR 6.5000 0 0 0 1 +TMC057 CIRCULAR 6.5000 0 0 0 1 +TMC058 CIRCULAR 6.5000 0 0 0 1 +TMC059 CIRCULAR 6.5000 0 0 0 1 +TMC060 CIRCULAR 6.5000 0 0 0 1 +TMC061 CIRCULAR 6.5000 0 0 0 1 +TMC062 CIRCULAR 6.5000 0 0 0 1 +TMC063 CIRCULAR 6.5000 0 0 0 1 +TMC064 CIRCULAR 6.5000 0 0 0 1 +TMC065 CIRCULAR 6.5000 0 0 0 1 +TMC066 CIRCULAR 6.5000 0 0 0 1 +TMC067 CIRCULAR 6.5000 0 0 0 1 +TMC068 CIRCULAR 6.5000 0 0 0 1 +TMC069 CIRCULAR 6.5000 0 0 0 1 +TMC070 CIRCULAR 6.5000 0 0 0 1 +TMC071 CIRCULAR 6.5000 0 0 0 1 +TMC072 CIRCULAR 6.5000 0 0 0 1 +TLC000 CIRCULAR 7.5000 0 0 0 1 +TLC001 CIRCULAR 7.5000 0 0 0 1 +TLC002 CIRCULAR 7.5000 0 0 0 1 +TLC003 CIRCULAR 7.5000 0 0 0 1 +TLC004 CIRCULAR 7.5000 0 0 0 1 +TLC005 CIRCULAR 7.5000 0 0 0 1 +TLC006 CIRCULAR 7.5000 0 0 0 1 +TLC007 CIRCULAR 7.5000 0 0 0 1 +TLC008 CIRCULAR 7.5000 0 0 0 1 +TLC009 CIRCULAR 7.5000 0 0 0 1 +TLC010 CIRCULAR 7.5000 0 0 0 1 +TLC011 CIRCULAR 7.5000 0 0 0 1 +TLC012 CIRCULAR 7.5000 0 0 0 1 +TLC013 CIRCULAR 7.5000 0 0 0 1 +TLC014 CIRCULAR 7.5000 0 0 0 1 +TLC015 CIRCULAR 7.5000 0 0 0 1 +TLC016 CIRCULAR 7.5000 0 0 0 1 +TLC017 CIRCULAR 7.5000 0 0 0 1 +TLC018 CIRCULAR 7.5000 0 0 0 1 +TLC019 CIRCULAR 7.5000 0 0 0 1 +TLC020 CIRCULAR 7.5000 0 0 0 1 +TLC021 CIRCULAR 7.5000 0 0 0 1 +TLC022 CIRCULAR 7.5000 0 0 0 1 +TLC023 CIRCULAR 7.5000 0 0 0 1 +TLC024 CIRCULAR 7.5000 0 0 0 1 +TLC025 CIRCULAR 7.5000 0 0 0 1 +TLC026 CIRCULAR 7.5000 0 0 0 1 +TLC027 CIRCULAR 7.5000 0 0 0 1 +TLC028 CIRCULAR 7.5000 0 0 0 1 +TLC029 CIRCULAR 7.5000 0 0 0 1 +TLC030 CIRCULAR 7.5000 0 0 0 1 +TLC031 CIRCULAR 7.5000 0 0 0 1 +TLC032 CIRCULAR 7.5000 0 0 0 1 +TLC033 CIRCULAR 7.5000 0 0 0 1 +TLC034 CIRCULAR 7.5000 0 0 0 1 +TLC035 CIRCULAR 7.5000 0 0 0 1 +TLC036 CIRCULAR 7.5000 0 0 0 1 +TLC037 CIRCULAR 7.5000 0 0 0 1 +TLC038 CIRCULAR 7.5000 0 0 0 1 +TLC039 CIRCULAR 7.5000 0 0 0 1 +TLC040 CIRCULAR 7.5000 0 0 0 1 +TLC041 CIRCULAR 7.5000 0 0 0 1 +TLC042 CIRCULAR 7.5000 0 0 0 1 +TLC043 CIRCULAR 7.5000 0 0 0 1 +TLC044 CIRCULAR 7.5000 0 0 0 1 +TLC045 CIRCULAR 7.5000 0 0 0 1 +TLC046 CIRCULAR 7.5000 0 0 0 1 +TLC047 CIRCULAR 7.5000 0 0 0 1 +TLC048 CIRCULAR 7.5000 0 0 0 1 +TLC049 CIRCULAR 7.5000 0 0 0 1 +TLC050 CIRCULAR 7.5000 0 0 0 1 +TLC051 CIRCULAR 7.5000 0 0 0 1 +TLC052 CIRCULAR 7.5000 0 0 0 1 +TLC053 CIRCULAR 7.5000 0 0 0 1 +TLC054 CIRCULAR 7.5000 0 0 0 1 +TLC055 CIRCULAR 7.5000 0 0 0 1 +TLC056 CIRCULAR 7.5000 0 0 0 1 +TLC057 CIRCULAR 7.5000 0 0 0 1 +TLC058 CIRCULAR 7.5000 0 0 0 1 +TLC059 CIRCULAR 7.5000 0 0 0 1 +TLC060 CIRCULAR 7.5000 0 0 0 1 +TLC061 CIRCULAR 7.5000 0 0 0 1 +TLC062 CIRCULAR 7.5000 0 0 0 1 +TLC063 CIRCULAR 7.5000 0 0 0 1 +TLC064 CIRCULAR 7.5000 0 0 0 1 +TLC065 CIRCULAR 7.5000 0 0 0 1 +TLC066 CIRCULAR 7.5000 0 0 0 1 +TLC067 CIRCULAR 7.5000 0 0 0 1 +TLC068 CIRCULAR 7.5000 0 0 0 1 +TLC069 CIRCULAR 7.5000 0 0 0 1 +TLC070 CIRCULAR 7.5000 0 0 0 1 +TLC071 CIRCULAR 7.5000 0 0 0 1 +TLC072 CIRCULAR 7.5000 0 0 0 1 +TLC073 CIRCULAR 7.5000 0 0 0 1 +TLC074 CIRCULAR 7.5000 0 0 0 1 +TLC075 CIRCULAR 7.5000 0 0 0 1 +TLC076 CIRCULAR 7.5000 0 0 0 1 +TLC077 CIRCULAR 7.5000 0 0 0 1 +TLC078 CIRCULAR 7.5000 0 0 0 1 +TLC079 CIRCULAR 7.5000 0 0 0 1 +TLC080 CIRCULAR 7.5000 0 0 0 1 +TLC081 CIRCULAR 7.5000 0 0 0 1 +TLC082 CIRCULAR 7.5000 0 0 0 1 +TLC083 CIRCULAR 7.5000 0 0 0 1 +TLC084 CIRCULAR 7.5000 0 0 0 1 +TLC085 CIRCULAR 7.5000 0 0 0 1 +TLC086 CIRCULAR 7.5000 0 0 0 1 +TLC087 CIRCULAR 7.5000 0 0 0 1 +BAC000 CIRCULAR 4.0000 0 0 0 1 +BAC001 CIRCULAR 4.0000 0 0 0 1 +BAC002 CIRCULAR 4.0000 0 0 0 1 +BAC003 CIRCULAR 4.0000 0 0 0 1 +BAC004 CIRCULAR 4.0000 0 0 0 1 +BAC005 CIRCULAR 4.0000 0 0 0 1 +BAC006 CIRCULAR 4.0000 0 0 0 1 +BAC007 CIRCULAR 4.0000 0 0 0 1 +BAC008 CIRCULAR 4.0000 0 0 0 1 +BAC009 CIRCULAR 4.0000 0 0 0 1 +BAC010 CIRCULAR 4.0000 0 0 0 1 +BAC011 CIRCULAR 4.0000 0 0 0 1 +BAC012 CIRCULAR 4.0000 0 0 0 1 +BAC013 CIRCULAR 4.0000 0 0 0 1 +BAC014 CIRCULAR 4.0000 0 0 0 1 +BAC015 CIRCULAR 4.0000 0 0 0 1 +BAC016 CIRCULAR 4.0000 0 0 0 1 +BAC017 CIRCULAR 4.0000 0 0 0 1 +BAC018 CIRCULAR 4.0000 0 0 0 1 +BAC019 CIRCULAR 4.0000 0 0 0 1 +BAC020 CIRCULAR 4.0000 0 0 0 1 +BAC021 CIRCULAR 4.0000 0 0 0 1 +BAC022 CIRCULAR 4.0000 0 0 0 1 +BAC023 CIRCULAR 4.0000 0 0 0 1 +BAC024 CIRCULAR 4.0000 0 0 0 1 +BAC025 CIRCULAR 4.0000 0 0 0 1 +BAC026 CIRCULAR 4.0000 0 0 0 1 +BAC027 CIRCULAR 4.0000 0 0 0 1 +BAC028 CIRCULAR 4.0000 0 0 0 1 +BAC029 CIRCULAR 4.0000 0 0 0 1 +BAC030 CIRCULAR 4.0000 0 0 0 1 +BAC031 CIRCULAR 4.0000 0 0 0 1 +BAC032 CIRCULAR 4.0000 0 0 0 1 +BAC033 CIRCULAR 4.0000 0 0 0 1 +BAC034 CIRCULAR 4.0000 0 0 0 1 +BAC035 CIRCULAR 4.0000 0 0 0 1 +BAC036 CIRCULAR 4.0000 0 0 0 1 +BAC037 CIRCULAR 4.0000 0 0 0 1 +BAC038 CIRCULAR 4.0000 0 0 0 1 +BAC039 CIRCULAR 4.0000 0 0 0 1 +BAC040 CIRCULAR 4.0000 0 0 0 1 +BAC041 CIRCULAR 4.0000 0 0 0 1 +BAC042 CIRCULAR 4.0000 0 0 0 1 +BAC043 CIRCULAR 4.0000 0 0 0 1 +BAC044 CIRCULAR 4.0000 0 0 0 1 +BAC045 CIRCULAR 4.0000 0 0 0 1 +BAC046 CIRCULAR 4.0000 0 0 0 1 +BAC047 CIRCULAR 4.0000 0 0 0 1 +BAC048 CIRCULAR 4.0000 0 0 0 1 +BAC049 CIRCULAR 4.0000 0 0 0 1 +BAC050 CIRCULAR 4.0000 0 0 0 1 +BAC051 CIRCULAR 4.0000 0 0 0 1 +BAC052 CIRCULAR 4.0000 0 0 0 1 +BAC053 CIRCULAR 4.0000 0 0 0 1 +BAC054 CIRCULAR 4.0000 0 0 0 1 +BAC055 CIRCULAR 4.0000 0 0 0 1 +BAC056 CIRCULAR 4.0000 0 0 0 1 +BAC057 CIRCULAR 4.0000 0 0 0 1 +BAC058 CIRCULAR 4.0000 0 0 0 1 +BAC059 CIRCULAR 4.0000 0 0 0 1 +BAC060 CIRCULAR 4.0000 0 0 0 1 +BAC061 CIRCULAR 4.0000 0 0 0 1 +BAC062 CIRCULAR 4.0000 0 0 0 1 +BAC063 CIRCULAR 4.0000 0 0 0 1 +BAC064 CIRCULAR 4.0000 0 0 0 1 +BAC065 CIRCULAR 4.0000 0 0 0 1 +BAC066 CIRCULAR 4.0000 0 0 0 1 +BAC067 CIRCULAR 4.0000 0 0 0 1 +BAC068 CIRCULAR 4.0000 0 0 0 1 +BAC069 CIRCULAR 4.0000 0 0 0 1 +BAC070 CIRCULAR 4.0000 0 0 0 1 +BAC071 CIRCULAR 4.0000 0 0 0 1 +BAC072 CIRCULAR 4.0000 0 0 0 1 +BBC000 CIRCULAR 3.5000 0 0 0 1 +BBC001 CIRCULAR 3.5000 0 0 0 1 +BBC002 CIRCULAR 3.5000 0 0 0 1 +BBC003 CIRCULAR 3.5000 0 0 0 1 +BBC004 CIRCULAR 3.5000 0 0 0 1 +BBC005 CIRCULAR 3.5000 0 0 0 1 +BBC006 CIRCULAR 3.5000 0 0 0 1 +BBC007 CIRCULAR 3.5000 0 0 0 1 +BBC008 CIRCULAR 3.5000 0 0 0 1 +BBC009 CIRCULAR 3.5000 0 0 0 1 +BBC010 CIRCULAR 3.5000 0 0 0 1 +BBC011 CIRCULAR 3.5000 0 0 0 1 +BBC012 CIRCULAR 3.5000 0 0 0 1 +BBC013 CIRCULAR 3.5000 0 0 0 1 +BBC014 CIRCULAR 3.5000 0 0 0 1 +BBC015 CIRCULAR 3.5000 0 0 0 1 +BBC016 CIRCULAR 3.5000 0 0 0 1 +BBC017 CIRCULAR 3.5000 0 0 0 1 +BBC018 CIRCULAR 3.5000 0 0 0 1 +BBC019 CIRCULAR 3.5000 0 0 0 1 +BBC020 CIRCULAR 3.5000 0 0 0 1 +BBC021 CIRCULAR 3.5000 0 0 0 1 +BBC022 CIRCULAR 3.5000 0 0 0 1 +BBC023 CIRCULAR 3.5000 0 0 0 1 +BBC024 CIRCULAR 3.5000 0 0 0 1 +BBC025 CIRCULAR 3.5000 0 0 0 1 +BBC026 CIRCULAR 3.5000 0 0 0 1 +BBC027 CIRCULAR 3.5000 0 0 0 1 +BBC028 CIRCULAR 3.5000 0 0 0 1 +BBC029 CIRCULAR 3.5000 0 0 0 1 +BBC030 CIRCULAR 3.5000 0 0 0 1 +BBC031 CIRCULAR 3.5000 0 0 0 1 +BBC032 CIRCULAR 3.5000 0 0 0 1 +BBC033 CIRCULAR 3.5000 0 0 0 1 +BBC034 CIRCULAR 3.5000 0 0 0 1 +BBC035 CIRCULAR 3.5000 0 0 0 1 +BBC036 CIRCULAR 3.5000 0 0 0 1 +BBC037 CIRCULAR 3.5000 0 0 0 1 +BBC038 CIRCULAR 3.5000 0 0 0 1 +BBC039 CIRCULAR 3.5000 0 0 0 1 +BBC040 CIRCULAR 3.5000 0 0 0 1 +BBC041 CIRCULAR 3.5000 0 0 0 1 +BBC042 CIRCULAR 3.5000 0 0 0 1 +BBC043 CIRCULAR 3.5000 0 0 0 1 +BBC044 CIRCULAR 3.5000 0 0 0 1 +BBC045 CIRCULAR 3.5000 0 0 0 1 +BBC046 CIRCULAR 3.5000 0 0 0 1 +BBC047 CIRCULAR 3.5000 0 0 0 1 +BBC048 CIRCULAR 3.5000 0 0 0 1 +BBC049 CIRCULAR 3.5000 0 0 0 1 +BBC050 CIRCULAR 3.5000 0 0 0 1 +BBC051 CIRCULAR 3.5000 0 0 0 1 +BBC052 CIRCULAR 3.5000 0 0 0 1 +BBC053 CIRCULAR 3.5000 0 0 0 1 +BBC054 CIRCULAR 3.5000 0 0 0 1 +FRS_Outlet CIRCULAR 3.0000 0 0 0 +FRS_Overflow RECT_CLOSED 4.0000 8 0 0 + +[INFLOWS] +;;Node Constituent TimeSeries Type Mfactor Sfactor +TU0000000 FLOW Trunk_Surge FLOW 1.0 1.0 +BA0000000 FLOW BranchA_Surge FLOW 1.0 1.0 +BB0000000 FLOW BranchB_Surge FLOW 1.0 1.0 + +[TIMESERIES] +;;Name Time Value +Trunk_Surge 0:00 12.00 +Trunk_Surge 1:00 12.00 +Trunk_Surge 2:30 140.00 +Trunk_Surge 4:00 140.00 +Trunk_Surge 7:00 12.00 +Trunk_Surge 13:00 12.00 +Trunk_Surge 14:30 119.00 +Trunk_Surge 16:00 119.00 +Trunk_Surge 19:00 12.00 +Trunk_Surge 24:00 12.00 +BranchA_Surge 0:00 4.00 +BranchA_Surge 1:30 4.00 +BranchA_Surge 3:00 45.00 +BranchA_Surge 4:30 45.00 +BranchA_Surge 7:30 4.00 +BranchA_Surge 13:30 4.00 +BranchA_Surge 15:00 38.25 +BranchA_Surge 16:30 38.25 +BranchA_Surge 19:30 4.00 +BranchA_Surge 24:00 4.00 +BranchB_Surge 0:00 3.00 +BranchB_Surge 2:00 3.00 +BranchB_Surge 3:30 30.00 +BranchB_Surge 5:00 30.00 +BranchB_Surge 8:00 3.00 +BranchB_Surge 14:00 3.00 +BranchB_Surge 15:30 25.50 +BranchB_Surge 17:00 25.50 +BranchB_Surge 20:00 3.00 +BranchB_Surge 24:00 3.00 + +[REPORT] +INPUT NO +CONTINUITY YES +FLOWSTATS YES + +[COORDINATES] +;;Node X-Coord Y-Coord +TU0000000 10000.0000 42000.0000 +TU0000124 10073.8205 41900.2800 +TU0000243 10156.9185 41815.2852 +TU0000340 10220.6007 41741.5788 +TU0000435 10283.3950 41671.2223 +TU0000560 10356.6083 41569.1333 +TU0000624 10395.4792 41518.0155 +TU0000722 10464.9438 41449.2218 +TU0000835 10547.6212 41372.9278 +TU0000940 10632.3207 41310.0415 +TU0001043 10708.0571 41239.8732 +TU0001128 10764.8596 41177.6158 +TU0001211 10813.9521 41110.2328 +TU0001310 10870.3222 41029.5914 +TU0001388 10908.4316 40960.6478 +TU0001514 10953.5453 40843.7631 +TU0001586 10982.6549 40777.1957 +TU0001670 11016.9119 40700.7594 +TU0001788 11040.1448 40585.4265 +TU0001904 11069.0347 40472.8096 +TU0001982 11093.6649 40398.8990 +TU0002056 11111.2101 40326.8082 +TU0002136 11122.3169 40247.3126 +TU0002196 11132.3492 40188.0762 +TU0002329 11134.6719 40055.3500 +TU0002403 11149.6388 39982.8838 +TU0002542 11188.6880 39849.3484 +TU0002672 11222.7931 39724.0615 +TU0002811 11262.0352 39591.1814 +TU0002907 11305.5729 39505.3098 +TU0003035 11374.1657 39397.5446 +TU0003158 11437.9782 39292.4475 +TU0003232 11484.7579 39234.3086 +TU0003306 11522.4218 39171.4614 +TU0003428 11585.9682 39066.9776 +TU0003502 11622.4897 39002.6788 +TU0003572 11663.0890 38945.3031 +TU0003633 11703.5059 38899.6435 +TU0003725 11766.0728 38832.2794 +TU0003860 11845.7531 38723.0070 +TU0003925 11887.7320 38673.4674 +TU0004028 11941.9311 38586.6052 +TU0004125 11983.9184 38498.6468 +TU0004230 12017.2934 38398.5791 +TU0004296 12033.8437 38335.4551 +TU0004396 12065.7122 38240.6312 +TU0004532 12102.1910 38109.8762 +TU0004635 12124.4202 38008.3731 +TU0004699 12147.0298 37949.4705 +TU0004824 12173.9653 37827.1135 +TU0004892 12184.1714 37759.4122 +TU0004960 12203.1781 37694.0546 +TU0005034 12211.7267 37620.5296 +TU0005118 12223.1744 37538.1350 +TU0005213 12256.1258 37448.2257 +TU0005350 12310.1425 37322.9620 +TU0005415 12334.8138 37262.8246 +TU0005538 12388.4412 37151.5546 +TU0005612 12405.6674 37079.6093 +TU0005720 12425.7016 36974.1152 +TU0005803 12438.9858 36891.3607 +TU0005888 12445.0220 36806.8182 +TU0005996 12450.7921 36698.6409 +TU0006069 12454.8068 36626.6584 +TU0006204 12475.2055 36492.4747 +TU0006329 12498.7547 36370.0212 +TU0006445 12517.7736 36256.0822 +TU0006547 12542.2851 36156.1498 +TU0006649 12569.5367 36057.7950 +TU0006784 12609.5162 35929.6379 +TU0006922 12653.8701 35798.3267 +TU0007041 12695.3692 35687.2093 +TU0007110 12717.2043 35621.5754 +TU0007249 12785.7861 35500.8049 +TU0007340 12835.8210 35424.4032 +TU0007462 12900.7756 35321.6450 +TU0007577 12967.0260 35227.5143 +TU0007686 13018.6167 35131.7492 +TU0007798 13064.5440 35029.3455 +TU0007917 13094.6194 34914.0893 +TU0008033 13121.3902 34801.7334 +TU0008128 13135.6952 34707.2099 +TU0008196 13150.7840 34641.3075 +TU0008327 13190.2512 34516.4440 +TU0008434 13235.3649 34418.8684 +TU0008546 13290.8947 34322.2902 +TU0008608 13321.9511 34267.7012 +TU0008742 13406.0169 34163.9701 +TU0008847 13455.4112 34071.7857 +TU0008976 13509.9905 33954.0314 +TU0009092 13569.4805 33855.1154 +TU0009193 13613.2480 33763.3855 +TU0009260 13639.4886 33701.8293 +TU0009338 13663.6922 33627.7394 +TU0009406 13674.2366 33560.9255 +TU0009470 13680.0282 33496.7560 +TU0009608 13665.1476 33360.3441 +TU0009718 13650.3647 33250.9177 +TU0009817 13638.5527 33152.7003 +TM0000096 13645.5548 33056.7994 +TM0000199 13641.5993 32954.2838 +TM0000310 13642.7366 32843.0189 +TM0000381 13626.5307 32773.7223 +TM0000450 13611.3305 32706.1955 +TM0000516 13606.6684 32641.1166 +TM0000580 13605.4309 32576.8524 +TM0000672 13593.8382 32485.5662 +TM0000767 13584.7875 32391.3691 +TM0000872 13593.7783 32286.1148 +TM0000987 13587.5775 32171.7185 +TM0001060 13594.4485 32099.2905 +TM0001158 13610.9349 32002.6433 +TM0001259 13619.7346 31901.6408 +TM0001339 13619.1089 31821.2415 +TM0001460 13617.7382 31700.1378 +TM0001579 13630.2698 31582.4263 +TM0001675 13640.9316 31487.0068 +TM0001742 13658.1546 31421.8055 +TM0001838 13681.7843 31328.9455 +TM0001947 13706.6752 31222.4722 +TM0002081 13728.3974 31090.6315 +TM0002189 13734.3283 30982.6148 +TM0002305 13763.4146 30870.5731 +TM0002412 13779.4292 30764.6901 +TM0002474 13798.7126 30705.8231 +TM0002582 13826.4380 30601.1747 +TM0002713 13846.4527 30472.0861 +TM0002773 13857.1413 30412.5395 +TM0002894 13894.9667 30297.7816 +TM0003030 13916.7741 30163.9116 +TM0003126 13950.7695 30073.8796 +TM0003262 14007.7662 29950.2712 +TM0003352 14047.1579 29869.9861 +TM0003416 14072.0554 29810.1905 +TM0003519 14111.1675 29715.5256 +TM0003585 14135.8268 29653.7234 +TM0003683 14164.8671 29560.6100 +TM0003808 14192.1765 29438.1321 +TM0003923 14211.4125 29325.5749 +TM0004047 14251.0060 29207.6624 +TM0004167 14293.5355 29095.1860 +TM0004263 14326.8201 29005.1909 +TM0004352 14332.5356 28916.9740 +TM0004432 14331.0291 28836.4068 +TM0004544 14327.1721 28724.7135 +TM0004675 14317.3429 28593.7151 +TM0004789 14309.6105 28480.0294 +TM0004865 14321.0657 28405.2898 +TM0004992 14323.8323 28278.6681 +TM0005127 14338.7977 28144.1545 +TM0005252 14361.2371 28020.9935 +TM0005377 14388.3330 27899.0487 +TM0005490 14413.2425 27788.9279 +TM0005578 14421.1598 27701.3552 +TM0005684 14405.2550 27596.6290 +TM0005760 14394.1998 27521.4026 +TM0005872 14370.8945 27411.9139 +TM0005955 14357.3698 27329.3134 +TM0006059 14335.0420 27228.5095 +TM0006123 14319.4570 27165.8439 +TM0006205 14286.3536 27091.4471 +TM0006319 14250.7770 26983.2408 +TM0006413 14214.3433 26896.3674 +TM0006552 14146.1476 26775.3420 +TM0006652 14096.5864 26687.6238 +TM0006717 14066.7469 26629.8654 +TM0006792 14027.1319 26566.9043 +TM0006897 13970.8908 26478.4257 +TM0006959 13940.6125 26423.6962 +TM0007031 13918.6011 26355.8020 +TM0007142 13894.1631 26247.0808 +TM0007238 13870.5491 26154.3177 +TL0000111 13850.3045 26045.5822 +TL0000172 13836.3903 25985.8346 +TL0000258 13813.2679 25903.4352 +TL0000356 13797.8343 25806.0825 +TL0000488 13781.8295 25675.0807 +TL0000569 13766.1169 25595.2053 +TL0000647 13751.2050 25519.5122 +TL0000749 13731.7293 25418.7099 +TL0000830 13709.7110 25340.5764 +TL0000936 13677.3162 25240.2918 +TL0001055 13620.0443 25135.8151 +TL0001128 13589.3226 25069.1216 +TL0001230 13540.2535 24980.5172 +TL0001347 13508.3149 24867.7399 +TL0001419 13474.2495 24803.8151 +TL0001507 13445.3620 24721.1552 +TL0001571 13422.6217 24661.2315 +TL0001682 13373.9768 24561.7600 +TL0001776 13332.7835 24477.0317 +TL0001874 13288.4221 24390.0213 +TL0001991 13231.5598 24287.7694 +TL0002075 13191.2851 24213.7382 +TL0002155 13160.3358 24140.0950 +TL0002282 13085.2308 24037.6859 +TL0002374 13021.4803 23970.5768 +TL0002444 12969.5457 23923.9934 +TL0002551 12896.9917 23845.8925 +TL0002658 12832.6921 23759.4508 +TL0002767 12769.4790 23670.7913 +TL0002880 12713.3740 23572.9518 +TL0002962 12681.4867 23498.0115 +TL0003039 12637.2895 23434.5479 +TL0003126 12582.4887 23366.6435 +TL0003263 12485.2027 23269.8300 +TL0003397 12394.7625 23171.1575 +TL0003471 12347.2036 23114.9137 +TL0003550 12307.7464 23046.8007 +TL0003627 12265.1645 22981.8783 +TL0003696 12226.2354 22925.7944 +TL0003812 12167.7179 22824.6277 +TL0003912 12103.9148 22748.3193 +TL0004035 12005.2815 22674.8349 +TL0004124 11935.2753 22619.6373 +TL0004231 11859.2085 22544.3030 +TL0004323 11787.0285 22487.7093 +TL0004460 11686.7564 22393.6650 +TL0004588 11609.5009 22292.1295 +TL0004707 11540.8185 22195.3802 +TL0004797 11484.6147 22125.0351 +TL0004894 11417.6295 22054.6317 +TL0005003 11343.3521 21973.9674 +TL0005119 11270.7991 21884.2779 +TL0005207 11206.4638 21823.6651 +TL0005323 11122.7327 21743.1439 +TL0005447 11031.6566 21659.1083 +TL0005564 10949.5036 21576.5550 +TL0005637 10896.8053 21525.4862 +TL0005767 10796.6215 21442.5212 +TL0005840 10745.5077 21390.5063 +TL0005912 10703.8348 21332.2574 +TL0006049 10609.4958 21232.5595 +TL0006125 10546.6944 21189.9085 +TL0006238 10446.9323 21135.9350 +TL0006375 10333.6357 21059.8357 +TL0006486 10244.3790 20993.7874 +TL0006608 10137.0248 20936.0278 +TL0006736 10024.4602 20874.9561 +TL0006842 9924.5938 20837.4365 +TL0006906 9863.4111 20819.4269 +TL0006972 9803.5600 20791.9303 +TL0007106 9680.6987 20737.8891 +TL0007246 9557.3667 20671.8415 +TL0007331 9488.0063 20623.6310 +TL0007391 9440.9566 20586.2138 +TL0007482 9372.3739 20526.8296 +TL0007592 9294.9498 20448.0211 +TL0007711 9201.1736 20375.5545 +TL0007780 9148.7451 20329.7367 +TL0007853 9087.9587 20290.3734 +TL0007940 9010.8176 20250.2319 +TL0008058 8910.8609 20185.9549 +TL0008156 8832.8488 20127.3331 +TL0008291 8732.4959 20036.4281 +TL0008415 8642.7230 19951.0062 +TL0008539 8555.2948 19863.0935 +TL0008657 8476.1802 19775.5470 +TL0008764 8398.5225 19701.7018 +FRS_Basin 8357.5557 19651.4865 +BA0000000 16368.2325 39642.9747 +BA0000066 16330.7922 39589.1661 +BA0000147 16275.9306 39528.3299 +BA0000248 16204.4620 39457.7467 +BA0000357 16129.4764 39379.1235 +BA0000491 16052.8690 39268.7393 +BA0000615 15995.3823 39158.7803 +BA0000735 15939.2079 39053.0700 +BA0000822 15911.8750 38970.4977 +BA0000926 15875.1933 38873.2054 +BA0000993 15857.3555 38807.9506 +BA0001132 15823.7464 38673.8404 +BA0001208 15797.5507 38601.7046 +BA0001310 15781.4811 38501.6311 +BA0001448 15758.3687 38365.6675 +BA0001560 15736.1899 38255.4855 +BA0001622 15725.6241 38194.3002 +BA0001740 15686.5143 38083.4053 +BA0001867 15637.1472 37966.1811 +BA0001947 15600.0991 37895.4040 +BA0002065 15544.4121 37791.2149 +BA0002151 15497.6564 37719.3006 +BA0002213 15472.7249 37662.1008 +BA0002283 15441.5314 37599.2975 +BA0002376 15390.1197 37521.5431 +BA0002479 15336.6532 37433.7618 +BA0002576 15297.1815 37344.8522 +BA0002678 15253.6585 37253.1064 +BA0002746 15220.9338 37193.9260 +BA0002849 15174.4823 37101.5919 +BA0002945 15121.4616 37021.0544 +BA0003033 15061.8930 36956.4108 +BA0003095 15037.6950 36900.0516 +BA0003235 15007.3645 36763.5131 +BA0003311 14988.6052 36688.9726 +BA0003404 14973.3060 36597.7494 +BA0003499 14962.5074 36502.7971 +BA0003631 14950.0034 36372.2785 +BA0003743 14945.6667 36260.2048 +BA0003851 14932.5044 36152.2969 +BA0003922 14922.6430 36082.1601 +BA0004020 14903.9339 35986.6308 +BA0004157 14854.1887 35858.9793 +BA0004271 14824.0059 35748.2388 +BA0004410 14768.7240 35620.8218 +BA0004543 14705.7649 35503.5899 +BA0004613 14667.9550 35444.7186 +BA0004710 14620.1651 35360.5272 +BA0004823 14560.3847 35264.5335 +BA0004893 14529.3667 35201.5618 +BA0004985 14484.8960 35121.1432 +BA0005061 14467.1152 35047.5399 +BA0005180 14448.8367 34929.5029 +BA0005279 14423.5891 34834.5628 +BA0005359 14399.4238 34757.7196 +BA0005423 14378.8891 34697.3154 +BA0005511 14341.5846 34617.1342 +BA0005580 14315.7014 34553.4263 +BA0005650 14285.4579 34490.2528 +BA0005767 14231.8902 34386.3861 +BA0005860 14195.2955 34301.1777 +BA0005945 14164.5844 34221.5067 +BA0006053 14139.2074 34116.7737 +BA0006170 14098.2019 34007.1509 +BA0006275 14056.8636 33910.3281 +BA0006413 13996.9578 33786.7228 +BA0006510 13940.0494 33707.5584 +BA0006572 13909.1713 33654.0455 +BA0006702 13850.6709 33538.0304 +BA0006807 13802.1657 33444.9552 +BA0006902 13756.8229 33361.2799 +BA0006971 13728.6723 33298.6604 +BA0007053 13681.9397 33230.5747 +BB0000000 9596.9996 29587.8684 +BB0000130 9717.4147 29538.7729 +BB0000201 9783.8417 29513.1425 +BB0000273 9845.9414 29476.9982 +BB0000335 9904.9863 29457.4295 +BB0000469 10029.5150 29409.6859 +BB0000568 10124.1039 29379.2657 +BB0000668 10210.3674 29328.5056 +BB0000778 10301.9927 29267.2267 +BB0000915 10400.9769 29172.6913 +BB0000981 10449.0279 29127.5316 +BB0001065 10507.2835 29066.8752 +BB0001168 10576.2863 28990.0981 +BB0001229 10616.6046 28945.1841 +BB0001359 10711.8065 28855.8388 +BB0001422 10759.1305 28814.1685 +BB0001540 10849.5662 28739.1888 +BB0001605 10895.3573 28693.2333 +BB0001679 10955.9172 28650.1307 +BB0001817 11069.2676 28570.8005 +BB0001934 11157.7259 28494.9049 +BB0002032 11228.4552 28427.6698 +BB0002116 11289.2663 28369.1428 +BB0002243 11375.2525 28276.3009 +BB0002336 11436.4814 28205.8365 +BB0002415 11488.1147 28145.9400 +BB0002507 11552.5725 28080.1737 +BB0002622 11642.9386 28009.8877 +BB0002721 11721.1291 27948.7146 +BB0002839 11812.2529 27874.2515 +BB0002977 11918.7193 27786.1133 +BB0003079 12003.7943 27729.6473 +BB0003149 12062.3700 27690.6303 +BB0003278 12168.8255 27618.2923 +BB0003350 12228.1783 27578.3154 +BB0003489 12343.8528 27500.4092 +BB0003628 12429.4350 27390.2745 +BB0003736 12490.2868 27301.8378 +BB0003841 12550.4012 27215.4160 +BB0003920 12600.6255 27154.9441 +BB0004045 12699.6156 27078.2673 +BB0004134 12776.8119 27033.3322 +BB0004265 12889.3517 26967.2486 +BB0004326 12944.8398 26942.3177 +BB0004414 13022.8703 26901.1844 +BB0004499 13093.0458 26853.0347 +BB0004614 13197.1957 26803.8375 +BB0004734 13294.8904 26734.6246 +BB0004858 13386.1033 26649.9726 +BB0004953 13458.8814 26589.1820 +BB0005056 13535.9036 26520.1622 +BB0005158 13608.5227 26448.8177 +BB0005220 13647.4612 26400.8083 +BB0005347 13728.1833 26302.6923 +BB0005425 13785.5005 26249.3532 +OUT_RIVER 9257.5557 18951.4865 +OUT_OVERFLOW 9457.5557 19951.4865 diff --git a/docs/figures/decks/cedar_glen/generate_model.py b/docs/figures/decks/cedar_glen/generate_model.py new file mode 100644 index 000000000..b4e6f16fc --- /dev/null +++ b/docs/figures/decks/cedar_glen/generate_model.py @@ -0,0 +1,321 @@ +#!/usr/bin/env python3 +"""Generate the Cedar Glen to FRS demonstration model. + +A synthetic raw-water conveyance in the same style as a GIS-derived +client network: a long trunk built from short survey segments chained by +virtual junctions, two lateral branches, and a terminal flow-regulating +storage (FRS) basin with orifice outlets. All geometry, elevations, and +names are invented; nothing here comes from any client dataset. + +Writes cedar_glen_fv.inp and cedar_glen_dw.inp (identical decks except +FLOW_ROUTING; the FV_* options are inert under dynamic wave). + +Run: python generate_model.py +""" + +from __future__ import annotations + +import math +from pathlib import Path + +import numpy as np + +HERE = Path(__file__).resolve().parent +RNG = np.random.default_rng(20260816) + +FT_PER_SEG = (60.0, 140.0) # survey segment length range, ft + + +def alignment(n_pts: int, start_xy, heading_deg, drift_deg=0.0, wobble=7.0, + seg_range=FT_PER_SEG): + """Meandering polyline from a smooth random walk. Returns (xy, s).""" + xy = [np.asarray(start_xy, dtype=float)] + s = [0.0] + theta = math.radians(heading_deg) + drift = math.radians(drift_deg) + for _ in range(n_pts - 1): + theta += drift + math.radians(RNG.normal(0.0, wobble)) + # relax back toward the drift direction so the line keeps going + theta = 0.92 * theta + 0.08 * (math.radians(heading_deg) + drift * len(s)) + L = RNG.uniform(*seg_range) + step = np.array([math.cos(theta), math.sin(theta)]) * L + xy.append(xy[-1] + step) + s.append(s[-1] + L) + return np.array(xy), np.array(s) + + +def profile(s, elev_top, reaches): + """Piecewise-slope invert profile along chainage s. + + reaches: list of (fraction_of_length, slope). Fractions sum to 1. + """ + total = s[-1] + z = np.empty_like(s) + z[0] = elev_top + bounds = np.cumsum([f for f, _ in reaches]) * total + slopes = [sl for _, sl in reaches] + for i in range(1, len(s)): + ds = s[i] - s[i - 1] + k = np.searchsorted(bounds, s[i], side="left") + k = min(k, len(slopes) - 1) + z[i] = z[i - 1] - slopes[k] * ds + return z + + +class Net: + def __init__(self): + self.junctions = [] # (name, invert, maxdepth, surdepth) + self.virtual = [] # (name, invert, rim) + self.conduits = [] # (name, n1, n2, length, diam_ft) + self.coords = {} # name -> (x, y) + + def add_run(self, prefix, xy, s, z, diam, first_node=None, last_node=None, + real_every_ft=2600.0): + """Add a chain of short conduits; interior nodes are virtual + junctions except a real access junction every ~real_every_ft.""" + n = len(s) + names = [] + next_real = real_every_ft + for i in range(n): + if i == 0 and first_node: + names.append(first_node) + continue + if i == n - 1 and last_node: + names.append(last_node) + self.coords[last_node] = tuple(xy[i]) + continue + name = f"{prefix}{s[i]:07.0f}" + names.append(name) + self.coords[name] = tuple(xy[i]) + if i == 0 or i == n - 1: + # run endpoints are real junctions (heads and tie-ins can + # carry inflows or a third conduit; VJs take exactly two) + self.junctions.append((name, z[i], 0.0, 40.0)) + elif s[i] >= next_real and i < n - 1: + self.junctions.append((name, z[i], 0.0, 40.0)) + next_real += real_every_ft + else: + self.virtual.append((name, z[i], diam + 5.0)) + for i in range(n - 1): + self.conduits.append((f"{prefix}C{i:03d}", names[i], names[i + 1], + s[i + 1] - s[i], diam)) + return names + + +def main(): + net = Net() + + # Trunk: ~26,000 ft, 72 in upper, 78 in middle, 90 in lower. + n_tr = 260 + xy, s = alignment(n_tr, (10000.0, 42000.0), heading_deg=-55.0, + drift_deg=-0.28) + # between the tie-ins the invert dips into pocket A, climbs a STEEP + # adverse riser to a crest at ~455 ft, drops into pocket B, and lips up + # again: the double-pocket grade a valved raw-water conveyance carries + z = profile(s, 468.0, [(0.22, 0.0030), (0.18, 0.0018), + (0.04, 0.0008), # pocket A floor + (0.03, -0.0155), # riser to ~455 + (0.07, 0.0065), # steep fall + (0.05, 0.0008), # pocket B floor + (0.02, -0.0050), # second lip + (0.21, 0.0022), (0.18, 0.0028)]) + thirds = [int(n_tr * 0.38), int(n_tr * 0.66)] + tie_a, tie_b = thirds + + trunk_names = [] + seg_specs = [(0, tie_a, 6.0, "TU"), (tie_a, tie_b, 6.5, "TM"), + (tie_b, n_tr - 1, 7.5, "TL")] + for k, (i0, i1, diam, pref) in enumerate(seg_specs): + first = trunk_names[-1] if trunk_names else None + names = net.add_run(pref, xy[i0:i1 + 1], s[i0:i1 + 1] - s[i0], + z[i0:i1 + 1], diam, first_node=first, + last_node="FRS_Basin" if k == 2 else None) + trunk_names.extend(names if not first else names[1:]) + + tie_a_node, tie_b_node = trunk_names[tie_a], trunk_names[tie_b] + + # Branch A: 7,400 ft of 48 in joining the trunk at tie_a. + n_a = 74 + xy_a, s_a = alignment(n_a, tuple(xy[tie_a] + (5200.0, 5600.0)), + heading_deg=-125.0, drift_deg=0.10) + xy_a = xy_a - xy_a[-1] + xy[tie_a] # land exactly on the tie-in + z_a = profile(s_a, z[tie_a] + 118.0, [(0.5, 0.0060), (0.5, 0.0040)]) + z_a += z[tie_a] - z_a[-1] + net.add_run("BA", xy_a, s_a, z_a, 4.0, last_node=tie_a_node) + + # Branch B: 5,600 ft of 42 in joining the trunk at tie_b. + n_b = 56 + xy_b, s_b = alignment(n_b, tuple(xy[tie_b] + (-6100.0, 4200.0)), + heading_deg=-35.0, drift_deg=-0.12) + xy_b = xy_b - xy_b[-1] + xy[tie_b] + z_b = profile(s_b, z[tie_b] + 86.0, [(0.6, 0.0055), (0.4, 0.0040)]) + z_b += z[tie_b] - z_b[-1] + net.add_run("BB", xy_b, s_b, z_b, 3.5, last_node=tie_b_node) + + frs_invert = z[-1] - 2.0 + net.coords["FRS_Basin"] = tuple(xy[-1]) + net.coords["OUT_RIVER"] = tuple(xy[-1] + (900.0, -700.0)) + net.coords["OUT_OVERFLOW"] = tuple(xy[-1] + (1100.0, 300.0)) + + head_trunk = trunk_names[0] + head_a = f"BA{0:07.0f}" + head_b = f"BB{0:07.0f}" + + n_vj = len(net.virtual) + n_j = len(net.junctions) + n_c = len(net.conduits) + + def fmt_ts(pairs): + return "\n".join(f"{name:<18} {h:>7} {q:>10.2f}" + for name, h, q in pairs) + + def hydrograph(name, base, peak, t_rise, t_peak0, t_peak1, t_end): + # two surge-and-drain cycles across the 24 h run; the second peaks + # at 85 % of the first + knots = [(0.0, base), (t_rise, base), (t_peak0, peak), (t_peak1, peak), + (t_end, base)] + off, peak2 = 12.0, 0.85 * peak + knots += [(t_rise + off, base), (t_peak0 + off, peak2), + (t_peak1 + off, peak2), (t_end + off, base), (24.0, base)] + pts = [] + for hh, q in knots: + hstr = f"{int(hh)}:{int(round((hh % 1) * 60)):02d}" + pts.append((name, hstr, q)) + return pts + + ts = (hydrograph("Trunk_Surge", 12.0, 140.0, 1.0, 2.5, 4.0, 7.0) + + hydrograph("BranchA_Surge", 4.0, 45.0, 1.5, 3.0, 4.5, 7.5) + + hydrograph("BranchB_Surge", 3.0, 30.0, 2.0, 3.5, 5.0, 8.0)) + + options = """[OPTIONS] +;;Option Value +FLOW_UNITS MGD +INFILTRATION HORTON +FLOW_ROUTING {routing} +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING YES +SKIP_STEADY_STATE NO + +START_DATE 01/01/2026 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2026 +REPORT_START_TIME 00:00:00 +END_DATE 01/02/2026 +END_TIME 00:00:00 +REPORT_STEP 0:01:00 +WET_STEP 0:05:00 +DRY_STEP 1:00:00 +ROUTING_STEP 0:00:30 + +INERTIAL_DAMPING PARTIAL +NORMAL_FLOW_LIMITED BOTH +FORCE_MAIN_EQUATION H-W +SURCHARGE_METHOD {surcharge} +VARIABLE_STEP 0.75 +LENGTHENING_STEP 0 +MIN_SURFAREA 0 +MAX_TRIALS 8 +HEAD_TOLERANCE 0.005 +SYS_FLOW_TOL 5 +LAT_FLOW_TOL 5 +MINIMUM_STEP 0.5 + +FV_LTS YES +FV_LTS_MAX_TIERS 4 +""" + + body = ["[TITLE]", + ";;Cedar Glen to FRS -- synthetic conveyance demonstration", + ";;Generated by generate_model.py (seed 20260816); all data invented.", + "", "@OPTIONS@", "", + "[JUNCTIONS]", + ";;Name Elev MaxDepth InitDepth SurDepth Aponded"] + for name, inv, mx, sur in net.junctions: + body.append(f"{name:<18} {inv:>10.4f} {mx:>10.4f} {0.0:>10.4f} " + f"{sur:>10.4f} {0.0:>10.4f}") + + body += ["", "[VIRTUAL_JUNCTIONS]", + ";;Name Elev Rim"] + for name, inv, rim in net.virtual: + body.append(f"{name:<18} {inv:>10.4f} {rim:>10.4f}") + + body += ["", "[OUTFALLS]", + ";;Name Elev Type Gated", + f"{'OUT_RIVER':<18} {frs_invert - 3.0:>10.4f} FREE NO", + f"{'OUT_OVERFLOW':<18} {frs_invert + 6.0:>10.4f} FREE NO", + "", "[STORAGE]", + ";;Name Elev MaxDepth InitDepth Shape " + "Coeff Expon Const SurDepth Fevap", + f"{'FRS_Basin':<18} {frs_invert:>10.4f} {22.0:>10.4f} {2.0:>10.4f} " + f"FUNCTIONAL 0 0 120000 0 0", + "", "[CONDUITS]", + ";;Name FromNode ToNode " + "Length Roughness InOffset OutOffset InitFlow MaxFlow"] + for name, n1, n2, length, _ in net.conduits: + body.append(f"{name:<18} {n1:<18} {n2:<18} {length:>10.2f} " + f"{0.013:>10.4f} {0.0:>10.4f} {0.0:>10.4f} " + f"{0.0:>10.4f} {0.0:>10.4f}") + + body += ["", "[ORIFICES]", + ";;Name FromNode ToNode " + "Type Offset Cd Gated", + f"{'FRS_Outlet':<18} {'FRS_Basin':<18} {'OUT_RIVER':<18} " + f"SIDE {0.0:>10.4f} {0.65:>10.4f} NO", + f"{'FRS_Overflow':<18} {'FRS_Basin':<18} {'OUT_OVERFLOW':<18} " + f"SIDE {8.0:>10.4f} {1.0:>10.4f} NO", + "", "[XSECTIONS]", + ";;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels"] + for name, _, _, _, diam in net.conduits: + body.append(f"{name:<18} CIRCULAR {diam:>10.4f} 0 0 0 1") + body.append(f"{'FRS_Outlet':<18} CIRCULAR {3.0:>10.4f} 0 0 0") + body.append(f"{'FRS_Overflow':<18} RECT_CLOSED {4.0:>10.4f} 8 0 0") + + body += ["", "[INFLOWS]", + ";;Node Constituent TimeSeries Type Mfactor Sfactor", + f"{head_trunk:<18} FLOW Trunk_Surge FLOW 1.0 1.0", + f"{head_a:<18} FLOW BranchA_Surge FLOW 1.0 1.0", + f"{head_b:<18} FLOW BranchB_Surge FLOW 1.0 1.0", + "", "[TIMESERIES]", + ";;Name Time Value", + fmt_ts(ts), + "", "[REPORT]", + "INPUT NO", "CONTINUITY YES", "FLOWSTATS YES", + "", "[COORDINATES]", + ";;Node X-Coord Y-Coord"] + for name, (x, y) in net.coords.items(): + body.append(f"{name:<18} {x:>14.4f} {y:>14.4f}") + + # metadata for the animation / figure scripts + import json + diam_at = np.empty(n_tr) + for i0, i1, diam, _ in seg_specs: + diam_at[i0:i1 + 1] = diam + meta = { + "trunk": [{"name": trunk_names[i], "s": float(s[i]), + "z": float(z[i]), "diam": float(diam_at[i])} + for i in range(n_tr)], + "conduits": [{"name": c[0], "n1": c[1], "n2": c[2], + "diam": c[4]} for c in net.conduits], + "coords": {k: [float(v[0]), float(v[1])] for k, v in net.coords.items()}, + "frs_invert": float(frs_invert), + "tie_nodes": [tie_a_node, tie_b_node], + "heads": [head_trunk, head_a, head_b], + } + (HERE / "model_meta.json").write_text(json.dumps(meta, indent=1)) + + template = "\n".join(body) + "\n" + decks = (("FV", "SLOT", "cedar_glen_fv.inp"), + ("DYNWAVE", "SLOT", "cedar_glen_dw.inp"), + ("DYNWAVE", "EXTRAN", "cedar_glen_dw_extran.inp")) + for routing, surcharge, fname in decks: + text = template.replace("@OPTIONS@", options.format( + routing=routing, surcharge=surcharge)) + (HERE / fname).write_text(text) + + print(f"junctions={n_j} virtual={n_vj} conduits={n_c} " + f"trunk_len={s[-1]:.0f}ft heads: {head_trunk} {head_a} {head_b}") + + +if __name__ == "__main__": + main() diff --git a/docs/figures/decks/cedar_glen/model_meta.json b/docs/figures/decks/cedar_glen/model_meta.json new file mode 100644 index 000000000..0a8811ec0 --- /dev/null +++ b/docs/figures/decks/cedar_glen/model_meta.json @@ -0,0 +1,5460 @@ +{ + "trunk": [ + { + "name": "TU0000000", + "s": 0.0, + "z": 468.0, + "diam": 6.0 + }, + { + "name": "TU0000124", + "s": 124.07073473839861, + "z": 467.6277877957848, + "diam": 6.0 + }, + { + "name": "TU0000243", + "s": 242.93784562603028, + "z": 467.2711864631219, + "diam": 6.0 + }, + { + "name": "TU0000340", + "s": 340.34448826202726, + "z": 466.97896653521394, + "diam": 6.0 + }, + { + "name": "TU0000435", + "s": 434.6480589535614, + "z": 466.6960558231393, + "diam": 6.0 + }, + { + "name": "TU0000560", + "s": 560.2759470279722, + "z": 466.3191721589161, + "diam": 6.0 + }, + { + "name": "TU0000624", + "s": 624.4940869973174, + "z": 466.1265177390081, + "diam": 6.0 + }, + { + "name": "TU0000722", + "s": 722.2586022407165, + "z": 465.8332241932779, + "diam": 6.0 + }, + { + "name": "TU0000835", + "s": 834.758972638195, + "z": 465.4957230820855, + "diam": 6.0 + }, + { + "name": "TU0000940", + "s": 940.2515449700661, + "z": 465.17924536508986, + "diam": 6.0 + }, + { + "name": "TU0001043", + "s": 1043.4969083894114, + "z": 464.86950927483184, + "diam": 6.0 + }, + { + "name": "TU0001128", + "s": 1127.773258947052, + "z": 464.61668022315894, + "diam": 6.0 + }, + { + "name": "TU0001211", + "s": 1211.1431940988086, + "z": 464.36657041770366, + "diam": 6.0 + }, + { + "name": "TU0001310", + "s": 1309.5332991089422, + "z": 464.07140010267324, + "diam": 6.0 + }, + { + "name": "TU0001388", + "s": 1388.3086318047351, + "z": 463.8350741045859, + "diam": 6.0 + }, + { + "name": "TU0001514", + "s": 1513.5973744596633, + "z": 463.4592078766211, + "diam": 6.0 + }, + { + "name": "TU0001586", + "s": 1586.251252194455, + "z": 463.24124624341675, + "diam": 6.0 + }, + { + "name": "TU0001670", + "s": 1670.013151413243, + "z": 462.98996054576037, + "diam": 6.0 + }, + { + "name": "TU0001788", + "s": 1787.6628558389868, + "z": 462.6370114324831, + "diam": 6.0 + }, + { + "name": "TU0001904", + "s": 1903.9262944389734, + "z": 462.2882211166832, + "diam": 6.0 + }, + { + "name": "TU0001982", + "s": 1981.8328423389341, + "z": 462.0545014729833, + "diam": 6.0 + }, + { + "name": "TU0002056", + "s": 2056.0279162852885, + "z": 461.83191625114426, + "diam": 6.0 + }, + { + "name": "TU0002136", + "s": 2136.295710975254, + "z": 461.59111286707434, + "diam": 6.0 + }, + { + "name": "TU0002196", + "s": 2196.375682894828, + "z": 461.41087295131564, + "diam": 6.0 + }, + { + "name": "TU0002329", + "s": 2329.122165869433, + "z": 461.01263350239185, + "diam": 6.0 + }, + { + "name": "TU0002403", + "s": 2403.117836570661, + "z": 460.79064649028817, + "diam": 6.0 + }, + { + "name": "TU0002542", + "s": 2542.245569509044, + "z": 460.373263291473, + "diam": 6.0 + }, + { + "name": "TU0002672", + "s": 2672.0915268683584, + "z": 459.98372541939506, + "diam": 6.0 + }, + { + "name": "TU0002811", + "s": 2810.6449767766726, + "z": 459.5680650696701, + "diam": 6.0 + }, + { + "name": "TU0002907", + "s": 2906.9230887477424, + "z": 459.2792307337569, + "diam": 6.0 + }, + { + "name": "TU0003035", + "s": 3034.6662558513262, + "z": 458.8960012324461, + "diam": 6.0 + }, + { + "name": "TU0003158", + "s": 3157.6192166012006, + "z": 458.52714235019647, + "diam": 6.0 + }, + { + "name": "TU0003232", + "s": 3232.241354130316, + "z": 458.3032759376091, + "diam": 6.0 + }, + { + "name": "TU0003306", + "s": 3305.5103552139612, + "z": 458.08346893435817, + "diam": 6.0 + }, + { + "name": "TU0003428", + "s": 3427.8010044910784, + "z": 457.71659698652684, + "diam": 6.0 + }, + { + "name": "TU0003502", + "s": 3501.7480368803404, + "z": 457.49475588935906, + "diam": 6.0 + }, + { + "name": "TU0003572", + "s": 3572.0350932580845, + "z": 457.2838947202258, + "diam": 6.0 + }, + { + "name": "TU0003633", + "s": 3633.0131937534925, + "z": 457.1009604187396, + "diam": 6.0 + }, + { + "name": "TU0003725", + "s": 3724.9508750544564, + "z": 456.8251473748367, + "diam": 6.0 + }, + { + "name": "TU0003860", + "s": 3860.1891728920527, + "z": 456.41943248132395, + "diam": 6.0 + }, + { + "name": "TU0003925", + "s": 3925.122959202049, + "z": 456.224631122394, + "diam": 6.0 + }, + { + "name": "TU0004028", + "s": 4027.5074754170478, + "z": 455.917477573749, + "diam": 6.0 + }, + { + "name": "TU0004125", + "s": 4124.9734766860665, + "z": 455.62507956994193, + "diam": 6.0 + }, + { + "name": "TU0004230", + "s": 4230.460120621004, + "z": 455.30861963813715, + "diam": 6.0 + }, + { + "name": "TU0004296", + "s": 4295.717729442961, + "z": 455.11284681167126, + "diam": 6.0 + }, + { + "name": "TU0004396", + "s": 4395.753537462686, + "z": 454.8127393876121, + "diam": 6.0 + }, + { + "name": "TU0004532", + "s": 4531.501772601995, + "z": 454.40549468219416, + "diam": 6.0 + }, + { + "name": "TU0004635", + "s": 4635.41041458018, + "z": 454.0937687562596, + "diam": 6.0 + }, + { + "name": "TU0004699", + "s": 4698.503336160511, + "z": 453.9044899915186, + "diam": 6.0 + }, + { + "name": "TU0004824", + "s": 4823.789977173636, + "z": 453.5286300684792, + "diam": 6.0 + }, + { + "name": "TU0004892", + "s": 4892.256289401501, + "z": 453.3232311317956, + "diam": 6.0 + }, + { + "name": "TU0004960", + "s": 4960.321489710892, + "z": 453.1190355308674, + "diam": 6.0 + }, + { + "name": "TU0005034", + "s": 5034.341805401736, + "z": 452.8969745837949, + "diam": 6.0 + }, + { + "name": "TU0005118", + "s": 5117.5278083260155, + "z": 452.647416575022, + "diam": 6.0 + }, + { + "name": "TU0005213", + "s": 5213.28529275596, + "z": 452.36014412173216, + "diam": 6.0 + }, + { + "name": "TU0005350", + "s": 5349.699281682859, + "z": 451.95090215495145, + "diam": 6.0 + }, + { + "name": "TU0005415", + "s": 5414.700704660407, + "z": 451.75589788601883, + "diam": 6.0 + }, + { + "name": "TU0005538", + "s": 5538.219505615493, + "z": 451.3853414831536, + "diam": 6.0 + }, + { + "name": "TU0005612", + "s": 5612.198413501115, + "z": 451.1634047594967, + "diam": 6.0 + }, + { + "name": "TU0005720", + "s": 5719.577957303545, + "z": 450.97012158065235, + "diam": 6.0 + }, + { + "name": "TU0005803", + "s": 5803.391921686134, + "z": 450.8192564447637, + "diam": 6.0 + }, + { + "name": "TU0005888", + "s": 5888.1496202249045, + "z": 450.6666925873939, + "diam": 6.0 + }, + { + "name": "TU0005996", + "s": 5996.480668766112, + "z": 450.4716967000198, + "diam": 6.0 + }, + { + "name": "TU0006069", + "s": 6068.575032723795, + "z": 450.34192684489597, + "diam": 6.0 + }, + { + "name": "TU0006204", + "s": 6204.300421292431, + "z": 450.09762114547243, + "diam": 6.0 + }, + { + "name": "TU0006329", + "s": 6328.997770363276, + "z": 449.8731659171449, + "diam": 6.0 + }, + { + "name": "TU0006445", + "s": 6444.51320630324, + "z": 449.66523813245294, + "diam": 6.0 + }, + { + "name": "TU0006547", + "s": 6547.407784882089, + "z": 449.480027891011, + "diam": 6.0 + }, + { + "name": "TU0006649", + "s": 6649.468160093541, + "z": 449.2963192156304, + "diam": 6.0 + }, + { + "name": "TU0006784", + "s": 6783.716401653355, + "z": 449.0546723808227, + "diam": 6.0 + }, + { + "name": "TU0006922", + "s": 6922.316200013881, + "z": 448.8051927437738, + "diam": 6.0 + }, + { + "name": "TU0007041", + "s": 7040.930119772791, + "z": 448.59168768820774, + "diam": 6.0 + }, + { + "name": "TU0007110", + "s": 7110.100739694608, + "z": 448.46718057234847, + "diam": 6.0 + }, + { + "name": "TU0007249", + "s": 7248.985474917161, + "z": 448.2171880489479, + "diam": 6.0 + }, + { + "name": "TU0007340", + "s": 7340.312995076676, + "z": 448.0527985126608, + "diam": 6.0 + }, + { + "name": "TU0007462", + "s": 7461.879262799863, + "z": 447.83397923075904, + "diam": 6.0 + }, + { + "name": "TU0007577", + "s": 7576.98659908611, + "z": 447.6267860254438, + "diam": 6.0 + }, + { + "name": "TU0007686", + "s": 7685.764130746094, + "z": 447.4309864684558, + "diam": 6.0 + }, + { + "name": "TU0007798", + "s": 7797.995263253128, + "z": 447.2289704299431, + "diam": 6.0 + }, + { + "name": "TU0007917", + "s": 7917.110902085554, + "z": 447.01456228004474, + "diam": 6.0 + }, + { + "name": "TU0008033", + "s": 8032.6121119107265, + "z": 446.80666010235944, + "diam": 6.0 + }, + { + "name": "TU0008128", + "s": 8128.211841075756, + "z": 446.63458058986237, + "diam": 6.0 + }, + { + "name": "TU0008196", + "s": 8195.819600432114, + "z": 446.5128866230209, + "diam": 6.0 + }, + { + "name": "TU0008327", + "s": 8326.772073583681, + "z": 446.27717217134807, + "diam": 6.0 + }, + { + "name": "TU0008434", + "s": 8434.271985166093, + "z": 446.0836723304997, + "diam": 6.0 + }, + { + "name": "TU0008546", + "s": 8545.676287874692, + "z": 445.8831445856242, + "diam": 6.0 + }, + { + "name": "TU0008608", + "s": 8608.481167335063, + "z": 445.77009580259556, + "diam": 6.0 + }, + { + "name": "TU0008742", + "s": 8741.999724238094, + "z": 445.5297624001701, + "diam": 6.0 + }, + { + "name": "TU0008847", + "s": 8846.583502686255, + "z": 445.34151159896345, + "diam": 6.0 + }, + { + "name": "TU0008976", + "s": 8976.371682867975, + "z": 445.1078928746364, + "diam": 6.0 + }, + { + "name": "TU0009092", + "s": 9091.79884951424, + "z": 444.9001239746731, + "diam": 6.0 + }, + { + "name": "TU0009193", + "s": 9193.435320953935, + "z": 444.71717832608164, + "diam": 6.0 + }, + { + "name": "TU0009260", + "s": 9260.351196101692, + "z": 444.59672975081565, + "diam": 6.0 + }, + { + "name": "TU0009338", + "s": 9338.294326647643, + "z": 444.45643211583297, + "diam": 6.0 + }, + { + "name": "TU0009406", + "s": 9405.935108594274, + "z": 444.334678708329, + "diam": 6.0 + }, + { + "name": "TU0009470", + "s": 9470.365468174588, + "z": 444.21870406108445, + "diam": 6.0 + }, + { + "name": "TU0009608", + "s": 9607.586619588074, + "z": 443.9717059885402, + "diam": 6.0 + }, + { + "name": "TU0009718", + "s": 9718.007042035928, + "z": 443.77294922813405, + "diam": 6.0 + }, + { + "name": "TU0009817", + "s": 9816.932162375246, + "z": 443.5948840115233, + "diam": 6.5 + }, + { + "name": "TM0000096", + "s": 9913.088353738827, + "z": 443.42180286706883, + "diam": 6.5 + }, + { + "name": "TM0000199", + "s": 10015.680218911937, + "z": 443.23713750975725, + "diam": 6.5 + }, + { + "name": "TM0000310", + "s": 10126.95094849237, + "z": 443.0368501965125, + "diam": 6.5 + }, + { + "name": "TM0000381", + "s": 10198.117286357296, + "z": 442.90875078835563, + "diam": 6.5 + }, + { + "name": "TM0000450", + "s": 10267.333710807365, + "z": 442.7841612243455, + "diam": 6.5 + }, + { + "name": "TM0000516", + "s": 10332.579392792739, + "z": 442.6667189967718, + "diam": 6.5 + }, + { + "name": "TM0000580", + "s": 10396.855480388944, + "z": 442.6152981266948, + "diam": 6.5 + }, + { + "name": "TM0000672", + "s": 10488.874838456908, + "z": 442.5416826402405, + "diam": 6.5 + }, + { + "name": "TM0000767", + "s": 10583.505815534778, + "z": 442.4659778585782, + "diam": 6.5 + }, + { + "name": "TM0000872", + "s": 10689.143342116235, + "z": 442.38146783731304, + "diam": 6.5 + }, + { + "name": "TM0000987", + "s": 10803.70755705742, + "z": 442.2898164653601, + "diam": 6.5 + }, + { + "name": "TM0001060", + "s": 10876.460815557903, + "z": 442.23161385855974, + "diam": 6.5 + }, + { + "name": "TM0001158", + "s": 10974.504014199685, + "z": 442.1531792996463, + "diam": 6.5 + }, + { + "name": "TM0001259", + "s": 11075.889127583743, + "z": 442.07207120893906, + "diam": 6.5 + }, + { + "name": "TM0001339", + "s": 11156.29086967971, + "z": 442.0077498152623, + "diam": 6.5 + }, + { + "name": "TM0001460", + "s": 11277.402316451633, + "z": 441.91086065784475, + "diam": 6.5 + }, + { + "name": "TM0001579", + "s": 11395.77907476241, + "z": 443.7457004116618, + "diam": 6.5 + }, + { + "name": "TM0001675", + "s": 11491.792364370633, + "z": 445.23390640058926, + "diam": 6.5 + }, + { + "name": "TM0001742", + "s": 11559.229994090996, + "z": 446.2791896612549, + "diam": 6.5 + }, + { + "name": "TM0001838", + "s": 11655.049348212893, + "z": 447.7643896501443, + "diam": 6.5 + }, + { + "name": "TM0001947", + "s": 11764.393427648572, + "z": 449.45922288139735, + "diam": 6.5 + }, + { + "name": "TM0002081", + "s": 11898.011609440066, + "z": 451.53030469916547, + "diam": 6.5 + }, + { + "name": "TM0002189", + "s": 12006.190973723336, + "z": 453.20708484555615, + "diam": 6.5 + }, + { + "name": "TM0002305", + "s": 12121.946590685484, + "z": 455.00129690846944, + "diam": 6.5 + }, + { + "name": "TM0002412", + "s": 12229.033857447837, + "z": 454.3052296745141, + "diam": 6.5 + }, + { + "name": "TM0002474", + "s": 12290.978750203229, + "z": 453.90258787160406, + "diam": 6.5 + }, + { + "name": "TM0002582", + "s": 12399.237573172695, + "z": 453.19890552230254, + "diam": 6.5 + }, + { + "name": "TM0002713", + "s": 12529.868583403586, + "z": 452.34980395580175, + "diam": 6.5 + }, + { + "name": "TM0002773", + "s": 12590.366913123009, + "z": 451.9565648126255, + "diam": 6.5 + }, + { + "name": "TM0002894", + "s": 12711.197857235997, + "z": 451.1711636758911, + "diam": 6.5 + }, + { + "name": "TM0003030", + "s": 12846.832521081964, + "z": 450.28953836089227, + "diam": 6.5 + }, + { + "name": "TM0003126", + "s": 12943.068869338878, + "z": 449.6640020972223, + "diam": 6.5 + }, + { + "name": "TM0003262", + "s": 13079.18525507118, + "z": 448.77924558996233, + "diam": 6.5 + }, + { + "name": "TM0003352", + "s": 13168.61342755384, + "z": 448.19796246882504, + "diam": 6.5 + }, + { + "name": "TM0003416", + "s": 13233.385379116293, + "z": 447.7769447836691, + "diam": 6.5 + }, + { + "name": "TM0003519", + "s": 13335.811931404092, + "z": 447.1111721937984, + "diam": 6.5 + }, + { + "name": "TM0003585", + "s": 13402.352018439124, + "z": 446.6786616280707, + "diam": 6.5 + }, + { + "name": "TM0003683", + "s": 13499.88901193267, + "z": 446.0446711703627, + "diam": 6.5 + }, + { + "name": "TM0003808", + "s": 13625.3746299936, + "z": 445.2290146529666, + "diam": 6.5 + }, + { + "name": "TM0003923", + "s": 13739.56363462031, + "z": 444.48678612289297, + "diam": 6.5 + }, + { + "name": "TM0004047", + "s": 13863.946129844462, + "z": 443.67829990393597, + "diam": 6.5 + }, + { + "name": "TM0004167", + "s": 13984.194605806082, + "z": 443.5821011231667, + "diam": 6.5 + }, + { + "name": "TM0004263", + "s": 14080.147654457138, + "z": 443.5053386842458, + "diam": 6.5 + }, + { + "name": "TM0004352", + "s": 14168.549519349435, + "z": 443.434617192332, + "diam": 6.5 + }, + { + "name": "TM0004432", + "s": 14249.130832782672, + "z": 443.3701521415854, + "diam": 6.5 + }, + { + "name": "TM0004544", + "s": 14360.89065152089, + "z": 443.2807442865948, + "diam": 6.5 + }, + { + "name": "TM0004675", + "s": 14492.257320208802, + "z": 443.1756509516445, + "diam": 6.5 + }, + { + "name": "TM0004789", + "s": 14606.205670917492, + "z": 443.0844922710776, + "diam": 6.5 + }, + { + "name": "TM0004865", + "s": 14681.8180369471, + "z": 443.0240023782539, + "diam": 6.5 + }, + { + "name": "TM0004992", + "s": 14808.469992690943, + "z": 442.9226808136588, + "diam": 6.5 + }, + { + "name": "TM0005127", + "s": 14943.813480845965, + "z": 442.8144060231348, + "diam": 6.5 + }, + { + "name": "TM0005252", + "s": 15069.001966724736, + "z": 442.7142552344318, + "diam": 6.5 + }, + { + "name": "TM0005377", + "s": 15193.920825312405, + "z": 442.61432014756167, + "diam": 6.5 + }, + { + "name": "TM0005490", + "s": 15306.823754939296, + "z": 443.1788347956961, + "diam": 6.5 + }, + { + "name": "TM0005578", + "s": 15394.753618422024, + "z": 443.61848411310973, + "diam": 6.5 + }, + { + "name": "TM0005684", + "s": 15500.680658837446, + "z": 444.1481193151868, + "diam": 6.5 + }, + { + "name": "TM0005760", + "s": 15576.715103778854, + "z": 444.52829153989387, + "diam": 6.5 + }, + { + "name": "TM0005872", + "s": 15688.656654451283, + "z": 445.087999293256, + "diam": 6.5 + }, + { + "name": "TM0005955", + "s": 15772.357067617944, + "z": 445.5065013590893, + "diam": 6.5 + }, + { + "name": "TM0006059", + "s": 15875.604147709728, + "z": 445.2793577828874, + "diam": 6.5 + }, + { + "name": "TM0006123", + "s": 15940.17865828659, + "z": 445.1372938596183, + "diam": 6.5 + }, + { + "name": "TM0006205", + "s": 16021.60788721793, + "z": 444.9581495559693, + "diam": 6.5 + }, + { + "name": "TM0006319", + "s": 16135.512687840313, + "z": 444.7075589946001, + "diam": 6.5 + }, + { + "name": "TM0006413", + "s": 16229.716718503225, + "z": 444.5003101271417, + "diam": 6.5 + }, + { + "name": "TM0006552", + "s": 16368.63327233702, + "z": 444.19469370870735, + "diam": 6.5 + }, + { + "name": "TM0006652", + "s": 16469.38442746106, + "z": 443.9730411674345, + "diam": 6.5 + }, + { + "name": "TM0006717", + "s": 16534.395368070655, + "z": 443.8300170980934, + "diam": 6.5 + }, + { + "name": "TM0006792", + "s": 16608.78251482561, + "z": 443.6663653752325, + "diam": 6.5 + }, + { + "name": "TM0006897", + "s": 16713.62298092387, + "z": 443.4357163498163, + "diam": 6.5 + }, + { + "name": "TM0006959", + "s": 16776.169755832318, + "z": 443.2981134450177, + "diam": 6.5 + }, + { + "name": "TM0007031", + "s": 16847.54290248389, + "z": 443.1410925223842, + "diam": 6.5 + }, + { + "name": "TM0007142", + "s": 16958.97680533055, + "z": 442.8959379361216, + "diam": 6.5 + }, + { + "name": "TM0007238", + "s": 17054.698324070985, + "z": 442.6853505948926, + "diam": 7.5 + }, + { + "name": "TL0000111", + "s": 17165.30233651777, + "z": 442.4420217675097, + "diam": 7.5 + }, + { + "name": "TL0000172", + "s": 17226.648711833102, + "z": 442.307059741816, + "diam": 7.5 + }, + { + "name": "TL0000258", + "s": 17312.23084800132, + "z": 442.1187790422459, + "diam": 7.5 + }, + { + "name": "TL0000356", + "s": 17410.799348682627, + "z": 441.901928340747, + "diam": 7.5 + }, + { + "name": "TL0000488", + "s": 17542.775240113355, + "z": 441.61158137959944, + "diam": 7.5 + }, + { + "name": "TL0000569", + "s": 17624.181381891885, + "z": 441.4324878676867, + "diam": 7.5 + }, + { + "name": "TL0000647", + "s": 17701.329351415076, + "z": 441.26276233473567, + "diam": 7.5 + }, + { + "name": "TL0000749", + "s": 17803.99586291389, + "z": 441.0368960094383, + "diam": 7.5 + }, + { + "name": "TL0000830", + "s": 17885.172538351857, + "z": 440.8583073234748, + "diam": 7.5 + }, + { + "name": "TL0000936", + "s": 17990.559551815844, + "z": 440.62645589385403, + "diam": 7.5 + }, + { + "name": "TL0001055", + "s": 18109.704175708826, + "z": 440.3643377212895, + "diam": 7.5 + }, + { + "name": "TL0001128", + "s": 18183.133360470514, + "z": 440.2027935148138, + "diam": 7.5 + }, + { + "name": "TL0001230", + "s": 18284.417676265766, + "z": 439.97996802006423, + "diam": 7.5 + }, + { + "name": "TL0001347", + "s": 18401.630293796552, + "z": 439.7221002614965, + "diam": 7.5 + }, + { + "name": "TL0001419", + "s": 18474.065314308915, + "z": 439.5627432163693, + "diam": 7.5 + }, + { + "name": "TL0001507", + "s": 18561.62751958206, + "z": 439.3701063647684, + "diam": 7.5 + }, + { + "name": "TL0001571", + "s": 18625.721040626686, + "z": 439.2291006184702, + "diam": 7.5 + }, + { + "name": "TL0001682", + "s": 18736.449998671338, + "z": 438.985496910772, + "diam": 7.5 + }, + { + "name": "TL0001776", + "s": 18830.66127319604, + "z": 438.77823210681765, + "diam": 7.5 + }, + { + "name": "TL0001874", + "s": 18928.32775843629, + "z": 438.5633658392891, + "diam": 7.5 + }, + { + "name": "TL0001991", + "s": 19045.32685894236, + "z": 438.3059678181757, + "diam": 7.5 + }, + { + "name": "TL0002075", + "s": 19129.604125120102, + "z": 438.12055783258467, + "diam": 7.5 + }, + { + "name": "TL0002155", + "s": 19209.48641715847, + "z": 437.9448167901003, + "diam": 7.5 + }, + { + "name": "TL0002282", + "s": 19336.484071872677, + "z": 437.665421949729, + "diam": 7.5 + }, + { + "name": "TL0002374", + "s": 19429.046212617966, + "z": 437.4617852400894, + "diam": 7.5 + }, + { + "name": "TL0002444", + "s": 19498.811684214605, + "z": 437.3083012025768, + "diam": 7.5 + }, + { + "name": "TL0002551", + "s": 19605.412982237794, + "z": 437.0737783469258, + "diam": 7.5 + }, + { + "name": "TL0002658", + "s": 19713.146944012205, + "z": 436.8367636310221, + "diam": 7.5 + }, + { + "name": "TL0002767", + "s": 19822.03400473878, + "z": 436.59721209742366, + "diam": 7.5 + }, + { + "name": "TL0002880", + "s": 19934.818452196072, + "z": 436.3490863130176, + "diam": 7.5 + }, + { + "name": "TL0002962", + "s": 20016.2607983063, + "z": 436.1699131515751, + "diam": 7.5 + }, + { + "name": "TL0003039", + "s": 20093.597819980067, + "z": 435.9997717038928, + "diam": 7.5 + }, + { + "name": "TL0003126", + "s": 20180.856832370442, + "z": 435.80780187663396, + "diam": 7.5 + }, + { + "name": "TL0003263", + "s": 20318.10640766243, + "z": 435.5058528109916, + "diam": 7.5 + }, + { + "name": "TL0003397", + "s": 20451.955883469414, + "z": 435.2113839642162, + "diam": 7.5 + }, + { + "name": "TL0003471", + "s": 20525.611874759667, + "z": 435.04934078337766, + "diam": 7.5 + }, + { + "name": "TL0003550", + "s": 20604.328149712477, + "z": 434.8761649784815, + "diam": 7.5 + }, + { + "name": "TL0003627", + "s": 20681.96923745191, + "z": 434.70535458545476, + "diam": 7.5 + }, + { + "name": "TL0003696", + "s": 20750.23983565062, + "z": 434.5551592694176, + "diam": 7.5 + }, + { + "name": "TL0003812", + "s": 20867.11157508284, + "z": 434.2980414426667, + "diam": 7.5 + }, + { + "name": "TL0003912", + "s": 20966.579222614237, + "z": 434.07921261809764, + "diam": 7.5 + }, + { + "name": "TL0004035", + "s": 21089.57709451797, + "z": 433.80861729990943, + "diam": 7.5 + }, + { + "name": "TL0004124", + "s": 21178.726688322473, + "z": 433.6124881935395, + "diam": 7.5 + }, + { + "name": "TL0004231", + "s": 21285.784672280017, + "z": 433.3127258384584, + "diam": 7.5 + }, + { + "name": "TL0004323", + "s": 21377.505996119362, + "z": 433.05590613170824, + "diam": 7.5 + }, + { + "name": "TL0004460", + "s": 21514.97897933281, + "z": 432.6709817787106, + "diam": 7.5 + }, + { + "name": "TL0004588", + "s": 21642.56372658523, + "z": 432.31374448640383, + "diam": 7.5 + }, + { + "name": "TL0004707", + "s": 21761.213169844985, + "z": 431.9815260452765, + "diam": 7.5 + }, + { + "name": "TL0004797", + "s": 21851.253810370272, + "z": 431.7294122518057, + "diam": 7.5 + }, + { + "name": "TL0004894", + "s": 21948.432247117922, + "z": 431.4573126289123, + "diam": 7.5 + }, + { + "name": "TL0005003", + "s": 22058.08563535067, + "z": 431.1502831418606, + "diam": 7.5 + }, + { + "name": "TL0005119", + "s": 22173.446580572272, + "z": 430.8272724952401, + "diam": 7.5 + }, + { + "name": "TL0005207", + "s": 22261.83741218789, + "z": 430.5797781667164, + "diam": 7.5 + }, + { + "name": "TL0005323", + "s": 22378.0035414414, + "z": 430.25451300480654, + "diam": 7.5 + }, + { + "name": "TL0005447", + "s": 22501.92620806855, + "z": 429.9075295382505, + "diam": 7.5 + }, + { + "name": "TL0005564", + "s": 22618.391463356063, + "z": 429.5814268234455, + "diam": 7.5 + }, + { + "name": "TL0005637", + "s": 22691.774941045038, + "z": 429.37595308591636, + "diam": 7.5 + }, + { + "name": "TL0005767", + "s": 22821.851781719415, + "z": 429.0117379320281, + "diam": 7.5 + }, + { + "name": "TL0005840", + "s": 22894.77755949337, + "z": 428.807545754261, + "diam": 7.5 + }, + { + "name": "TL0005912", + "s": 22966.39860760174, + "z": 428.60700681955757, + "diam": 7.5 + }, + { + "name": "TL0006049", + "s": 23103.65568570181, + "z": 428.2226870008774, + "diam": 7.5 + }, + { + "name": "TL0006125", + "s": 23179.570948689605, + "z": 428.01012426451155, + "diam": 7.5 + }, + { + "name": "TL0006238", + "s": 23292.99763267988, + "z": 427.69252954933876, + "diam": 7.5 + }, + { + "name": "TL0006375", + "s": 23429.479188187623, + "z": 427.31038119391707, + "diam": 7.5 + }, + { + "name": "TL0006486", + "s": 23540.515803177128, + "z": 426.99947867194646, + "diam": 7.5 + }, + { + "name": "TL0006608", + "s": 23662.42200082079, + "z": 426.6581413185442, + "diam": 7.5 + }, + { + "name": "TL0006736", + "s": 23790.486527233712, + "z": 426.29956064458804, + "diam": 7.5 + }, + { + "name": "TL0006842", + "s": 23897.168439820332, + "z": 426.0008512893455, + "diam": 7.5 + }, + { + "name": "TL0006906", + "s": 23960.946630339895, + "z": 425.82227235589073, + "diam": 7.5 + }, + { + "name": "TL0006972", + "s": 24026.81185993539, + "z": 425.63784971302334, + "diam": 7.5 + }, + { + "name": "TL0007106", + "s": 24161.0331213387, + "z": 425.2620301810941, + "diam": 7.5 + }, + { + "name": "TL0007246", + "s": 24300.936820701747, + "z": 424.87029982287754, + "diam": 7.5 + }, + { + "name": "TL0007331", + "s": 24385.40648760975, + "z": 424.63378475553515, + "diam": 7.5 + }, + { + "name": "TL0007391", + "s": 24445.520765991707, + "z": 424.4654647760657, + "diam": 7.5 + }, + { + "name": "TL0007482", + "s": 24536.240436765896, + "z": 424.21144969789793, + "diam": 7.5 + }, + { + "name": "TL0007592", + "s": 24646.717965385607, + "z": 423.9021126177627, + "diam": 7.5 + }, + { + "name": "TL0007711", + "s": 24765.231116143736, + "z": 423.57027579564, + "diam": 7.5 + }, + { + "name": "TL0007780", + "s": 24834.85890464907, + "z": 423.37531798782504, + "diam": 7.5 + }, + { + "name": "TL0007853", + "s": 24907.277513793193, + "z": 423.1725458822215, + "diam": 7.5 + }, + { + "name": "TL0007940", + "s": 24994.237795834193, + "z": 422.92905709250675, + "diam": 7.5 + }, + { + "name": "TL0008058", + "s": 25113.077444080125, + "z": 422.59630607741815, + "diam": 7.5 + }, + { + "name": "TL0008156", + "s": 25210.66020605043, + "z": 422.3230743439013, + "diam": 7.5 + }, + { + "name": "TL0008291", + "s": 25346.064935497063, + "z": 421.9439411014507, + "diam": 7.5 + }, + { + "name": "TL0008415", + "s": 25469.984557723245, + "z": 421.5969661592174, + "diam": 7.5 + }, + { + "name": "TL0008539", + "s": 25593.96980875725, + "z": 421.2498074563222, + "diam": 7.5 + }, + { + "name": "TL0008657", + "s": 25711.96769553742, + "z": 420.9194133733377, + "diam": 7.5 + }, + { + "name": "TL0008764", + "s": 25819.13035501988, + "z": 420.6193579267868, + "diam": 7.5 + }, + { + "name": "FRS_Basin", + "s": 25883.936614595455, + "z": 420.43790039997515, + "diam": 7.5 + } + ], + "conduits": [ + { + "name": "TUC000", + "n1": "TU0000000", + "n2": "TU0000124", + "diam": 6.0 + }, + { + "name": "TUC001", + "n1": "TU0000124", + "n2": "TU0000243", + "diam": 6.0 + }, + { + "name": "TUC002", + "n1": "TU0000243", + "n2": "TU0000340", + "diam": 6.0 + }, + { + "name": "TUC003", + "n1": "TU0000340", + "n2": "TU0000435", + "diam": 6.0 + }, + { + "name": "TUC004", + "n1": "TU0000435", + "n2": "TU0000560", + "diam": 6.0 + }, + { + "name": "TUC005", + "n1": "TU0000560", + "n2": "TU0000624", + "diam": 6.0 + }, + { + "name": "TUC006", + "n1": "TU0000624", + "n2": "TU0000722", + "diam": 6.0 + }, + { + "name": "TUC007", + "n1": "TU0000722", + "n2": "TU0000835", + "diam": 6.0 + }, + { + "name": "TUC008", + "n1": "TU0000835", + "n2": "TU0000940", + "diam": 6.0 + }, + { + "name": "TUC009", + "n1": "TU0000940", + "n2": "TU0001043", + "diam": 6.0 + }, + { + "name": "TUC010", + "n1": "TU0001043", + "n2": "TU0001128", + "diam": 6.0 + }, + { + "name": "TUC011", + "n1": "TU0001128", + "n2": "TU0001211", + "diam": 6.0 + }, + { + "name": "TUC012", + "n1": "TU0001211", + "n2": "TU0001310", + "diam": 6.0 + }, + { + "name": "TUC013", + "n1": "TU0001310", + "n2": "TU0001388", + "diam": 6.0 + }, + { + "name": "TUC014", + "n1": "TU0001388", + "n2": "TU0001514", + "diam": 6.0 + }, + { + "name": "TUC015", + "n1": "TU0001514", + "n2": "TU0001586", + "diam": 6.0 + }, + { + "name": "TUC016", + "n1": "TU0001586", + "n2": "TU0001670", + "diam": 6.0 + }, + { + "name": "TUC017", + "n1": "TU0001670", + "n2": "TU0001788", + "diam": 6.0 + }, + { + "name": "TUC018", + "n1": "TU0001788", + "n2": "TU0001904", + "diam": 6.0 + }, + { + "name": "TUC019", + "n1": "TU0001904", + "n2": "TU0001982", + "diam": 6.0 + }, + { + "name": "TUC020", + "n1": "TU0001982", + "n2": "TU0002056", + "diam": 6.0 + }, + { + "name": "TUC021", + "n1": "TU0002056", + "n2": "TU0002136", + "diam": 6.0 + }, + { + "name": "TUC022", + "n1": "TU0002136", + "n2": "TU0002196", + "diam": 6.0 + }, + { + "name": "TUC023", + "n1": "TU0002196", + "n2": "TU0002329", + "diam": 6.0 + }, + { + "name": "TUC024", + "n1": "TU0002329", + "n2": "TU0002403", + "diam": 6.0 + }, + { + "name": "TUC025", + "n1": "TU0002403", + "n2": "TU0002542", + "diam": 6.0 + }, + { + "name": "TUC026", + "n1": "TU0002542", + "n2": "TU0002672", + "diam": 6.0 + }, + { + "name": "TUC027", + "n1": "TU0002672", + "n2": "TU0002811", + "diam": 6.0 + }, + { + "name": "TUC028", + "n1": "TU0002811", + "n2": "TU0002907", + "diam": 6.0 + }, + { + "name": "TUC029", + "n1": "TU0002907", + "n2": "TU0003035", + "diam": 6.0 + }, + { + "name": "TUC030", + "n1": "TU0003035", + "n2": "TU0003158", + "diam": 6.0 + }, + { + "name": "TUC031", + "n1": "TU0003158", + "n2": "TU0003232", + "diam": 6.0 + }, + { + "name": "TUC032", + "n1": "TU0003232", + "n2": "TU0003306", + "diam": 6.0 + }, + { + "name": "TUC033", + "n1": "TU0003306", + "n2": "TU0003428", + "diam": 6.0 + }, + { + "name": "TUC034", + "n1": "TU0003428", + "n2": "TU0003502", + "diam": 6.0 + }, + { + "name": "TUC035", + "n1": "TU0003502", + "n2": "TU0003572", + "diam": 6.0 + }, + { + "name": "TUC036", + "n1": "TU0003572", + "n2": "TU0003633", + "diam": 6.0 + }, + { + "name": "TUC037", + "n1": "TU0003633", + "n2": "TU0003725", + "diam": 6.0 + }, + { + "name": "TUC038", + "n1": "TU0003725", + "n2": "TU0003860", + "diam": 6.0 + }, + { + "name": "TUC039", + "n1": "TU0003860", + "n2": "TU0003925", + "diam": 6.0 + }, + { + "name": "TUC040", + "n1": "TU0003925", + "n2": "TU0004028", + "diam": 6.0 + }, + { + "name": "TUC041", + "n1": "TU0004028", + "n2": "TU0004125", + "diam": 6.0 + }, + { + "name": "TUC042", + "n1": "TU0004125", + "n2": "TU0004230", + "diam": 6.0 + }, + { + "name": "TUC043", + "n1": "TU0004230", + "n2": "TU0004296", + "diam": 6.0 + }, + { + "name": "TUC044", + "n1": "TU0004296", + "n2": "TU0004396", + "diam": 6.0 + }, + { + "name": "TUC045", + "n1": "TU0004396", + "n2": "TU0004532", + "diam": 6.0 + }, + { + "name": "TUC046", + "n1": "TU0004532", + "n2": "TU0004635", + "diam": 6.0 + }, + { + "name": "TUC047", + "n1": "TU0004635", + "n2": "TU0004699", + "diam": 6.0 + }, + { + "name": "TUC048", + "n1": "TU0004699", + "n2": "TU0004824", + "diam": 6.0 + }, + { + "name": "TUC049", + "n1": "TU0004824", + "n2": "TU0004892", + "diam": 6.0 + }, + { + "name": "TUC050", + "n1": "TU0004892", + "n2": "TU0004960", + "diam": 6.0 + }, + { + "name": "TUC051", + "n1": "TU0004960", + "n2": "TU0005034", + "diam": 6.0 + }, + { + "name": "TUC052", + "n1": "TU0005034", + "n2": "TU0005118", + "diam": 6.0 + }, + { + "name": "TUC053", + "n1": "TU0005118", + "n2": "TU0005213", + "diam": 6.0 + }, + { + "name": "TUC054", + "n1": "TU0005213", + "n2": "TU0005350", + "diam": 6.0 + }, + { + "name": "TUC055", + "n1": "TU0005350", + "n2": "TU0005415", + "diam": 6.0 + }, + { + "name": "TUC056", + "n1": "TU0005415", + "n2": "TU0005538", + "diam": 6.0 + }, + { + "name": "TUC057", + "n1": "TU0005538", + "n2": "TU0005612", + "diam": 6.0 + }, + { + "name": "TUC058", + "n1": "TU0005612", + "n2": "TU0005720", + "diam": 6.0 + }, + { + "name": "TUC059", + "n1": "TU0005720", + "n2": "TU0005803", + "diam": 6.0 + }, + { + "name": "TUC060", + "n1": "TU0005803", + "n2": "TU0005888", + "diam": 6.0 + }, + { + "name": "TUC061", + "n1": "TU0005888", + "n2": "TU0005996", + "diam": 6.0 + }, + { + "name": "TUC062", + "n1": "TU0005996", + "n2": "TU0006069", + "diam": 6.0 + }, + { + "name": "TUC063", + "n1": "TU0006069", + "n2": "TU0006204", + "diam": 6.0 + }, + { + "name": "TUC064", + "n1": "TU0006204", + "n2": "TU0006329", + "diam": 6.0 + }, + { + "name": "TUC065", + "n1": "TU0006329", + "n2": "TU0006445", + "diam": 6.0 + }, + { + "name": "TUC066", + "n1": "TU0006445", + "n2": "TU0006547", + "diam": 6.0 + }, + { + "name": "TUC067", + "n1": "TU0006547", + "n2": "TU0006649", + "diam": 6.0 + }, + { + "name": "TUC068", + "n1": "TU0006649", + "n2": "TU0006784", + "diam": 6.0 + }, + { + "name": "TUC069", + "n1": "TU0006784", + "n2": "TU0006922", + "diam": 6.0 + }, + { + "name": "TUC070", + "n1": "TU0006922", + "n2": "TU0007041", + "diam": 6.0 + }, + { + "name": "TUC071", + "n1": "TU0007041", + "n2": "TU0007110", + "diam": 6.0 + }, + { + "name": "TUC072", + "n1": "TU0007110", + "n2": "TU0007249", + "diam": 6.0 + }, + { + "name": "TUC073", + "n1": "TU0007249", + "n2": "TU0007340", + "diam": 6.0 + }, + { + "name": "TUC074", + "n1": "TU0007340", + "n2": "TU0007462", + "diam": 6.0 + }, + { + "name": "TUC075", + "n1": "TU0007462", + "n2": "TU0007577", + "diam": 6.0 + }, + { + "name": "TUC076", + "n1": "TU0007577", + "n2": "TU0007686", + "diam": 6.0 + }, + { + "name": "TUC077", + "n1": "TU0007686", + "n2": "TU0007798", + "diam": 6.0 + }, + { + "name": "TUC078", + "n1": "TU0007798", + "n2": "TU0007917", + "diam": 6.0 + }, + { + "name": "TUC079", + "n1": "TU0007917", + "n2": "TU0008033", + "diam": 6.0 + }, + { + "name": "TUC080", + "n1": "TU0008033", + "n2": "TU0008128", + "diam": 6.0 + }, + { + "name": "TUC081", + "n1": "TU0008128", + "n2": "TU0008196", + "diam": 6.0 + }, + { + "name": "TUC082", + "n1": "TU0008196", + "n2": "TU0008327", + "diam": 6.0 + }, + { + "name": "TUC083", + "n1": "TU0008327", + "n2": "TU0008434", + "diam": 6.0 + }, + { + "name": "TUC084", + "n1": "TU0008434", + "n2": "TU0008546", + "diam": 6.0 + }, + { + "name": "TUC085", + "n1": "TU0008546", + "n2": "TU0008608", + "diam": 6.0 + }, + { + "name": "TUC086", + "n1": "TU0008608", + "n2": "TU0008742", + "diam": 6.0 + }, + { + "name": "TUC087", + "n1": "TU0008742", + "n2": "TU0008847", + "diam": 6.0 + }, + { + "name": "TUC088", + "n1": "TU0008847", + "n2": "TU0008976", + "diam": 6.0 + }, + { + "name": "TUC089", + "n1": "TU0008976", + "n2": "TU0009092", + "diam": 6.0 + }, + { + "name": "TUC090", + "n1": "TU0009092", + "n2": "TU0009193", + "diam": 6.0 + }, + { + "name": "TUC091", + "n1": "TU0009193", + "n2": "TU0009260", + "diam": 6.0 + }, + { + "name": "TUC092", + "n1": "TU0009260", + "n2": "TU0009338", + "diam": 6.0 + }, + { + "name": "TUC093", + "n1": "TU0009338", + "n2": "TU0009406", + "diam": 6.0 + }, + { + "name": "TUC094", + "n1": "TU0009406", + "n2": "TU0009470", + "diam": 6.0 + }, + { + "name": "TUC095", + "n1": "TU0009470", + "n2": "TU0009608", + "diam": 6.0 + }, + { + "name": "TUC096", + "n1": "TU0009608", + "n2": "TU0009718", + "diam": 6.0 + }, + { + "name": "TUC097", + "n1": "TU0009718", + "n2": "TU0009817", + "diam": 6.0 + }, + { + "name": "TMC000", + "n1": "TU0009817", + "n2": "TM0000096", + "diam": 6.5 + }, + { + "name": "TMC001", + "n1": "TM0000096", + "n2": "TM0000199", + "diam": 6.5 + }, + { + "name": "TMC002", + "n1": "TM0000199", + "n2": "TM0000310", + "diam": 6.5 + }, + { + "name": "TMC003", + "n1": "TM0000310", + "n2": "TM0000381", + "diam": 6.5 + }, + { + "name": "TMC004", + "n1": "TM0000381", + "n2": "TM0000450", + "diam": 6.5 + }, + { + "name": "TMC005", + "n1": "TM0000450", + "n2": "TM0000516", + "diam": 6.5 + }, + { + "name": "TMC006", + "n1": "TM0000516", + "n2": "TM0000580", + "diam": 6.5 + }, + { + "name": "TMC007", + "n1": "TM0000580", + "n2": "TM0000672", + "diam": 6.5 + }, + { + "name": "TMC008", + "n1": "TM0000672", + "n2": "TM0000767", + "diam": 6.5 + }, + { + "name": "TMC009", + "n1": "TM0000767", + "n2": "TM0000872", + "diam": 6.5 + }, + { + "name": "TMC010", + "n1": "TM0000872", + "n2": "TM0000987", + "diam": 6.5 + }, + { + "name": "TMC011", + "n1": "TM0000987", + "n2": "TM0001060", + "diam": 6.5 + }, + { + "name": "TMC012", + "n1": "TM0001060", + "n2": "TM0001158", + "diam": 6.5 + }, + { + "name": "TMC013", + "n1": "TM0001158", + "n2": "TM0001259", + "diam": 6.5 + }, + { + "name": "TMC014", + "n1": "TM0001259", + "n2": "TM0001339", + "diam": 6.5 + }, + { + "name": "TMC015", + "n1": "TM0001339", + "n2": "TM0001460", + "diam": 6.5 + }, + { + "name": "TMC016", + "n1": "TM0001460", + "n2": "TM0001579", + "diam": 6.5 + }, + { + "name": "TMC017", + "n1": "TM0001579", + "n2": "TM0001675", + "diam": 6.5 + }, + { + "name": "TMC018", + "n1": "TM0001675", + "n2": "TM0001742", + "diam": 6.5 + }, + { + "name": "TMC019", + "n1": "TM0001742", + "n2": "TM0001838", + "diam": 6.5 + }, + { + "name": "TMC020", + "n1": "TM0001838", + "n2": "TM0001947", + "diam": 6.5 + }, + { + "name": "TMC021", + "n1": "TM0001947", + "n2": "TM0002081", + "diam": 6.5 + }, + { + "name": "TMC022", + "n1": "TM0002081", + "n2": "TM0002189", + "diam": 6.5 + }, + { + "name": "TMC023", + "n1": "TM0002189", + "n2": "TM0002305", + "diam": 6.5 + }, + { + "name": "TMC024", + "n1": "TM0002305", + "n2": "TM0002412", + "diam": 6.5 + }, + { + "name": "TMC025", + "n1": "TM0002412", + "n2": "TM0002474", + "diam": 6.5 + }, + { + "name": "TMC026", + "n1": "TM0002474", + "n2": "TM0002582", + "diam": 6.5 + }, + { + "name": "TMC027", + "n1": "TM0002582", + "n2": "TM0002713", + "diam": 6.5 + }, + { + "name": "TMC028", + "n1": "TM0002713", + "n2": "TM0002773", + "diam": 6.5 + }, + { + "name": "TMC029", + "n1": "TM0002773", + "n2": "TM0002894", + "diam": 6.5 + }, + { + "name": "TMC030", + "n1": "TM0002894", + "n2": "TM0003030", + "diam": 6.5 + }, + { + "name": "TMC031", + "n1": "TM0003030", + "n2": "TM0003126", + "diam": 6.5 + }, + { + "name": "TMC032", + "n1": "TM0003126", + "n2": "TM0003262", + "diam": 6.5 + }, + { + "name": "TMC033", + "n1": "TM0003262", + "n2": "TM0003352", + "diam": 6.5 + }, + { + "name": "TMC034", + "n1": "TM0003352", + "n2": "TM0003416", + "diam": 6.5 + }, + { + "name": "TMC035", + "n1": "TM0003416", + "n2": "TM0003519", + "diam": 6.5 + }, + { + "name": "TMC036", + "n1": "TM0003519", + "n2": "TM0003585", + "diam": 6.5 + }, + { + "name": "TMC037", + "n1": "TM0003585", + "n2": "TM0003683", + "diam": 6.5 + }, + { + "name": "TMC038", + "n1": "TM0003683", + "n2": "TM0003808", + "diam": 6.5 + }, + { + "name": "TMC039", + "n1": "TM0003808", + "n2": "TM0003923", + "diam": 6.5 + }, + { + "name": "TMC040", + "n1": "TM0003923", + "n2": "TM0004047", + "diam": 6.5 + }, + { + "name": "TMC041", + "n1": "TM0004047", + "n2": "TM0004167", + "diam": 6.5 + }, + { + "name": "TMC042", + "n1": "TM0004167", + "n2": "TM0004263", + "diam": 6.5 + }, + { + "name": "TMC043", + "n1": "TM0004263", + "n2": "TM0004352", + "diam": 6.5 + }, + { + "name": "TMC044", + "n1": "TM0004352", + "n2": "TM0004432", + "diam": 6.5 + }, + { + "name": "TMC045", + "n1": "TM0004432", + "n2": "TM0004544", + "diam": 6.5 + }, + { + "name": "TMC046", + "n1": "TM0004544", + "n2": "TM0004675", + "diam": 6.5 + }, + { + "name": "TMC047", + "n1": "TM0004675", + "n2": "TM0004789", + "diam": 6.5 + }, + { + "name": "TMC048", + "n1": "TM0004789", + "n2": "TM0004865", + "diam": 6.5 + }, + { + "name": "TMC049", + "n1": "TM0004865", + "n2": "TM0004992", + "diam": 6.5 + }, + { + "name": "TMC050", + "n1": "TM0004992", + "n2": "TM0005127", + "diam": 6.5 + }, + { + "name": "TMC051", + "n1": "TM0005127", + "n2": "TM0005252", + "diam": 6.5 + }, + { + "name": "TMC052", + "n1": "TM0005252", + "n2": "TM0005377", + "diam": 6.5 + }, + { + "name": "TMC053", + "n1": "TM0005377", + "n2": "TM0005490", + "diam": 6.5 + }, + { + "name": "TMC054", + "n1": "TM0005490", + "n2": "TM0005578", + "diam": 6.5 + }, + { + "name": "TMC055", + "n1": "TM0005578", + "n2": "TM0005684", + "diam": 6.5 + }, + { + "name": "TMC056", + "n1": "TM0005684", + "n2": "TM0005760", + "diam": 6.5 + }, + { + "name": "TMC057", + "n1": "TM0005760", + "n2": "TM0005872", + "diam": 6.5 + }, + { + "name": "TMC058", + "n1": "TM0005872", + "n2": "TM0005955", + "diam": 6.5 + }, + { + "name": "TMC059", + "n1": "TM0005955", + "n2": "TM0006059", + "diam": 6.5 + }, + { + "name": "TMC060", + "n1": "TM0006059", + "n2": "TM0006123", + "diam": 6.5 + }, + { + "name": "TMC061", + "n1": "TM0006123", + "n2": "TM0006205", + "diam": 6.5 + }, + { + "name": "TMC062", + "n1": "TM0006205", + "n2": "TM0006319", + "diam": 6.5 + }, + { + "name": "TMC063", + "n1": "TM0006319", + "n2": "TM0006413", + "diam": 6.5 + }, + { + "name": "TMC064", + "n1": "TM0006413", + "n2": "TM0006552", + "diam": 6.5 + }, + { + "name": "TMC065", + "n1": "TM0006552", + "n2": "TM0006652", + "diam": 6.5 + }, + { + "name": "TMC066", + "n1": "TM0006652", + "n2": "TM0006717", + "diam": 6.5 + }, + { + "name": "TMC067", + "n1": "TM0006717", + "n2": "TM0006792", + "diam": 6.5 + }, + { + "name": "TMC068", + "n1": "TM0006792", + "n2": "TM0006897", + "diam": 6.5 + }, + { + "name": "TMC069", + "n1": "TM0006897", + "n2": "TM0006959", + "diam": 6.5 + }, + { + "name": "TMC070", + "n1": "TM0006959", + "n2": "TM0007031", + "diam": 6.5 + }, + { + "name": "TMC071", + "n1": "TM0007031", + "n2": "TM0007142", + "diam": 6.5 + }, + { + "name": "TMC072", + "n1": "TM0007142", + "n2": "TM0007238", + "diam": 6.5 + }, + { + "name": "TLC000", + "n1": "TM0007238", + "n2": "TL0000111", + "diam": 7.5 + }, + { + "name": "TLC001", + "n1": "TL0000111", + "n2": "TL0000172", + "diam": 7.5 + }, + { + "name": "TLC002", + "n1": "TL0000172", + "n2": "TL0000258", + "diam": 7.5 + }, + { + "name": "TLC003", + "n1": "TL0000258", + "n2": "TL0000356", + "diam": 7.5 + }, + { + "name": "TLC004", + "n1": "TL0000356", + "n2": "TL0000488", + "diam": 7.5 + }, + { + "name": "TLC005", + "n1": "TL0000488", + "n2": "TL0000569", + "diam": 7.5 + }, + { + "name": "TLC006", + "n1": "TL0000569", + "n2": "TL0000647", + "diam": 7.5 + }, + { + "name": "TLC007", + "n1": "TL0000647", + "n2": "TL0000749", + "diam": 7.5 + }, + { + "name": "TLC008", + "n1": "TL0000749", + "n2": "TL0000830", + "diam": 7.5 + }, + { + "name": "TLC009", + "n1": "TL0000830", + "n2": "TL0000936", + "diam": 7.5 + }, + { + "name": "TLC010", + "n1": "TL0000936", + "n2": "TL0001055", + "diam": 7.5 + }, + { + "name": "TLC011", + "n1": "TL0001055", + "n2": "TL0001128", + "diam": 7.5 + }, + { + "name": "TLC012", + "n1": "TL0001128", + "n2": "TL0001230", + "diam": 7.5 + }, + { + "name": "TLC013", + "n1": "TL0001230", + "n2": "TL0001347", + "diam": 7.5 + }, + { + "name": "TLC014", + "n1": "TL0001347", + "n2": "TL0001419", + "diam": 7.5 + }, + { + "name": "TLC015", + "n1": "TL0001419", + "n2": "TL0001507", + "diam": 7.5 + }, + { + "name": "TLC016", + "n1": "TL0001507", + "n2": "TL0001571", + "diam": 7.5 + }, + { + "name": "TLC017", + "n1": "TL0001571", + "n2": "TL0001682", + "diam": 7.5 + }, + { + "name": "TLC018", + "n1": "TL0001682", + "n2": "TL0001776", + "diam": 7.5 + }, + { + "name": "TLC019", + "n1": "TL0001776", + "n2": "TL0001874", + "diam": 7.5 + }, + { + "name": "TLC020", + "n1": "TL0001874", + "n2": "TL0001991", + "diam": 7.5 + }, + { + "name": "TLC021", + "n1": "TL0001991", + "n2": "TL0002075", + "diam": 7.5 + }, + { + "name": "TLC022", + "n1": "TL0002075", + "n2": "TL0002155", + "diam": 7.5 + }, + { + "name": "TLC023", + "n1": "TL0002155", + "n2": "TL0002282", + "diam": 7.5 + }, + { + "name": "TLC024", + "n1": "TL0002282", + "n2": "TL0002374", + "diam": 7.5 + }, + { + "name": "TLC025", + "n1": "TL0002374", + "n2": "TL0002444", + "diam": 7.5 + }, + { + "name": "TLC026", + "n1": "TL0002444", + "n2": "TL0002551", + "diam": 7.5 + }, + { + "name": "TLC027", + "n1": "TL0002551", + "n2": "TL0002658", + "diam": 7.5 + }, + { + "name": "TLC028", + "n1": "TL0002658", + "n2": "TL0002767", + "diam": 7.5 + }, + { + "name": "TLC029", + "n1": "TL0002767", + "n2": "TL0002880", + "diam": 7.5 + }, + { + "name": "TLC030", + "n1": "TL0002880", + "n2": "TL0002962", + "diam": 7.5 + }, + { + "name": "TLC031", + "n1": "TL0002962", + "n2": "TL0003039", + "diam": 7.5 + }, + { + "name": "TLC032", + "n1": "TL0003039", + "n2": "TL0003126", + "diam": 7.5 + }, + { + "name": "TLC033", + "n1": "TL0003126", + "n2": "TL0003263", + "diam": 7.5 + }, + { + "name": "TLC034", + "n1": "TL0003263", + "n2": "TL0003397", + "diam": 7.5 + }, + { + "name": "TLC035", + "n1": "TL0003397", + "n2": "TL0003471", + "diam": 7.5 + }, + { + "name": "TLC036", + "n1": "TL0003471", + "n2": "TL0003550", + "diam": 7.5 + }, + { + "name": "TLC037", + "n1": "TL0003550", + "n2": "TL0003627", + "diam": 7.5 + }, + { + "name": "TLC038", + "n1": "TL0003627", + "n2": "TL0003696", + "diam": 7.5 + }, + { + "name": "TLC039", + "n1": "TL0003696", + "n2": "TL0003812", + "diam": 7.5 + }, + { + "name": "TLC040", + "n1": "TL0003812", + "n2": "TL0003912", + "diam": 7.5 + }, + { + "name": "TLC041", + "n1": "TL0003912", + "n2": "TL0004035", + "diam": 7.5 + }, + { + "name": "TLC042", + "n1": "TL0004035", + "n2": "TL0004124", + "diam": 7.5 + }, + { + "name": "TLC043", + "n1": "TL0004124", + "n2": "TL0004231", + "diam": 7.5 + }, + { + "name": "TLC044", + "n1": "TL0004231", + "n2": "TL0004323", + "diam": 7.5 + }, + { + "name": "TLC045", + "n1": "TL0004323", + "n2": "TL0004460", + "diam": 7.5 + }, + { + "name": "TLC046", + "n1": "TL0004460", + "n2": "TL0004588", + "diam": 7.5 + }, + { + "name": "TLC047", + "n1": "TL0004588", + "n2": "TL0004707", + "diam": 7.5 + }, + { + "name": "TLC048", + "n1": "TL0004707", + "n2": "TL0004797", + "diam": 7.5 + }, + { + "name": "TLC049", + "n1": "TL0004797", + "n2": "TL0004894", + "diam": 7.5 + }, + { + "name": "TLC050", + "n1": "TL0004894", + "n2": "TL0005003", + "diam": 7.5 + }, + { + "name": "TLC051", + "n1": "TL0005003", + "n2": "TL0005119", + "diam": 7.5 + }, + { + "name": "TLC052", + "n1": "TL0005119", + "n2": "TL0005207", + "diam": 7.5 + }, + { + "name": "TLC053", + "n1": "TL0005207", + "n2": "TL0005323", + "diam": 7.5 + }, + { + "name": "TLC054", + "n1": "TL0005323", + "n2": "TL0005447", + "diam": 7.5 + }, + { + "name": "TLC055", + "n1": "TL0005447", + "n2": "TL0005564", + "diam": 7.5 + }, + { + "name": "TLC056", + "n1": "TL0005564", + "n2": "TL0005637", + "diam": 7.5 + }, + { + "name": "TLC057", + "n1": "TL0005637", + "n2": "TL0005767", + "diam": 7.5 + }, + { + "name": "TLC058", + "n1": "TL0005767", + "n2": "TL0005840", + "diam": 7.5 + }, + { + "name": "TLC059", + "n1": "TL0005840", + "n2": "TL0005912", + "diam": 7.5 + }, + { + "name": "TLC060", + "n1": "TL0005912", + "n2": "TL0006049", + "diam": 7.5 + }, + { + "name": "TLC061", + "n1": "TL0006049", + "n2": "TL0006125", + "diam": 7.5 + }, + { + "name": "TLC062", + "n1": "TL0006125", + "n2": "TL0006238", + "diam": 7.5 + }, + { + "name": "TLC063", + "n1": "TL0006238", + "n2": "TL0006375", + "diam": 7.5 + }, + { + "name": "TLC064", + "n1": "TL0006375", + "n2": "TL0006486", + "diam": 7.5 + }, + { + "name": "TLC065", + "n1": "TL0006486", + "n2": "TL0006608", + "diam": 7.5 + }, + { + "name": "TLC066", + "n1": "TL0006608", + "n2": "TL0006736", + "diam": 7.5 + }, + { + "name": "TLC067", + "n1": "TL0006736", + "n2": "TL0006842", + "diam": 7.5 + }, + { + "name": "TLC068", + "n1": "TL0006842", + "n2": "TL0006906", + "diam": 7.5 + }, + { + "name": "TLC069", + "n1": "TL0006906", + "n2": "TL0006972", + "diam": 7.5 + }, + { + "name": "TLC070", + "n1": "TL0006972", + "n2": "TL0007106", + "diam": 7.5 + }, + { + "name": "TLC071", + "n1": "TL0007106", + "n2": "TL0007246", + "diam": 7.5 + }, + { + "name": "TLC072", + "n1": "TL0007246", + "n2": "TL0007331", + "diam": 7.5 + }, + { + "name": "TLC073", + "n1": "TL0007331", + "n2": "TL0007391", + "diam": 7.5 + }, + { + "name": "TLC074", + "n1": "TL0007391", + "n2": "TL0007482", + "diam": 7.5 + }, + { + "name": "TLC075", + "n1": "TL0007482", + "n2": "TL0007592", + "diam": 7.5 + }, + { + "name": "TLC076", + "n1": "TL0007592", + "n2": "TL0007711", + "diam": 7.5 + }, + { + "name": "TLC077", + "n1": "TL0007711", + "n2": "TL0007780", + "diam": 7.5 + }, + { + "name": "TLC078", + "n1": "TL0007780", + "n2": "TL0007853", + "diam": 7.5 + }, + { + "name": "TLC079", + "n1": "TL0007853", + "n2": "TL0007940", + "diam": 7.5 + }, + { + "name": "TLC080", + "n1": "TL0007940", + "n2": "TL0008058", + "diam": 7.5 + }, + { + "name": "TLC081", + "n1": "TL0008058", + "n2": "TL0008156", + "diam": 7.5 + }, + { + "name": "TLC082", + "n1": "TL0008156", + "n2": "TL0008291", + "diam": 7.5 + }, + { + "name": "TLC083", + "n1": "TL0008291", + "n2": "TL0008415", + "diam": 7.5 + }, + { + "name": "TLC084", + "n1": "TL0008415", + "n2": "TL0008539", + "diam": 7.5 + }, + { + "name": "TLC085", + "n1": "TL0008539", + "n2": "TL0008657", + "diam": 7.5 + }, + { + "name": "TLC086", + "n1": "TL0008657", + "n2": "TL0008764", + "diam": 7.5 + }, + { + "name": "TLC087", + "n1": "TL0008764", + "n2": "FRS_Basin", + "diam": 7.5 + }, + { + "name": "BAC000", + "n1": "BA0000000", + "n2": "BA0000066", + "diam": 4.0 + }, + { + "name": "BAC001", + "n1": "BA0000066", + "n2": "BA0000147", + "diam": 4.0 + }, + { + "name": "BAC002", + "n1": "BA0000147", + "n2": "BA0000248", + "diam": 4.0 + }, + { + "name": "BAC003", + "n1": "BA0000248", + "n2": "BA0000357", + "diam": 4.0 + }, + { + "name": "BAC004", + "n1": "BA0000357", + "n2": "BA0000491", + "diam": 4.0 + }, + { + "name": "BAC005", + "n1": "BA0000491", + "n2": "BA0000615", + "diam": 4.0 + }, + { + "name": "BAC006", + "n1": "BA0000615", + "n2": "BA0000735", + "diam": 4.0 + }, + { + "name": "BAC007", + "n1": "BA0000735", + "n2": "BA0000822", + "diam": 4.0 + }, + { + "name": "BAC008", + "n1": "BA0000822", + "n2": "BA0000926", + "diam": 4.0 + }, + { + "name": "BAC009", + "n1": "BA0000926", + "n2": "BA0000993", + "diam": 4.0 + }, + { + "name": "BAC010", + "n1": "BA0000993", + "n2": "BA0001132", + "diam": 4.0 + }, + { + "name": "BAC011", + "n1": "BA0001132", + "n2": "BA0001208", + "diam": 4.0 + }, + { + "name": "BAC012", + "n1": "BA0001208", + "n2": "BA0001310", + "diam": 4.0 + }, + { + "name": "BAC013", + "n1": "BA0001310", + "n2": "BA0001448", + "diam": 4.0 + }, + { + "name": "BAC014", + "n1": "BA0001448", + "n2": "BA0001560", + "diam": 4.0 + }, + { + "name": "BAC015", + "n1": "BA0001560", + "n2": "BA0001622", + "diam": 4.0 + }, + { + "name": "BAC016", + "n1": "BA0001622", + "n2": "BA0001740", + "diam": 4.0 + }, + { + "name": "BAC017", + "n1": "BA0001740", + "n2": "BA0001867", + "diam": 4.0 + }, + { + "name": "BAC018", + "n1": "BA0001867", + "n2": "BA0001947", + "diam": 4.0 + }, + { + "name": "BAC019", + "n1": "BA0001947", + "n2": "BA0002065", + "diam": 4.0 + }, + { + "name": "BAC020", + "n1": "BA0002065", + "n2": "BA0002151", + "diam": 4.0 + }, + { + "name": "BAC021", + "n1": "BA0002151", + "n2": "BA0002213", + "diam": 4.0 + }, + { + "name": "BAC022", + "n1": "BA0002213", + "n2": "BA0002283", + "diam": 4.0 + }, + { + "name": "BAC023", + "n1": "BA0002283", + "n2": "BA0002376", + "diam": 4.0 + }, + { + "name": "BAC024", + "n1": "BA0002376", + "n2": "BA0002479", + "diam": 4.0 + }, + { + "name": "BAC025", + "n1": "BA0002479", + "n2": "BA0002576", + "diam": 4.0 + }, + { + "name": "BAC026", + "n1": "BA0002576", + "n2": "BA0002678", + "diam": 4.0 + }, + { + "name": "BAC027", + "n1": "BA0002678", + "n2": "BA0002746", + "diam": 4.0 + }, + { + "name": "BAC028", + "n1": "BA0002746", + "n2": "BA0002849", + "diam": 4.0 + }, + { + "name": "BAC029", + "n1": "BA0002849", + "n2": "BA0002945", + "diam": 4.0 + }, + { + "name": "BAC030", + "n1": "BA0002945", + "n2": "BA0003033", + "diam": 4.0 + }, + { + "name": "BAC031", + "n1": "BA0003033", + "n2": "BA0003095", + "diam": 4.0 + }, + { + "name": "BAC032", + "n1": "BA0003095", + "n2": "BA0003235", + "diam": 4.0 + }, + { + "name": "BAC033", + "n1": "BA0003235", + "n2": "BA0003311", + "diam": 4.0 + }, + { + "name": "BAC034", + "n1": "BA0003311", + "n2": "BA0003404", + "diam": 4.0 + }, + { + "name": "BAC035", + "n1": "BA0003404", + "n2": "BA0003499", + "diam": 4.0 + }, + { + "name": "BAC036", + "n1": "BA0003499", + "n2": "BA0003631", + "diam": 4.0 + }, + { + "name": "BAC037", + "n1": "BA0003631", + "n2": "BA0003743", + "diam": 4.0 + }, + { + "name": "BAC038", + "n1": "BA0003743", + "n2": "BA0003851", + "diam": 4.0 + }, + { + "name": "BAC039", + "n1": "BA0003851", + "n2": "BA0003922", + "diam": 4.0 + }, + { + "name": "BAC040", + "n1": "BA0003922", + "n2": "BA0004020", + "diam": 4.0 + }, + { + "name": "BAC041", + "n1": "BA0004020", + "n2": "BA0004157", + "diam": 4.0 + }, + { + "name": "BAC042", + "n1": "BA0004157", + "n2": "BA0004271", + "diam": 4.0 + }, + { + "name": "BAC043", + "n1": "BA0004271", + "n2": "BA0004410", + "diam": 4.0 + }, + { + "name": "BAC044", + "n1": "BA0004410", + "n2": "BA0004543", + "diam": 4.0 + }, + { + "name": "BAC045", + "n1": "BA0004543", + "n2": "BA0004613", + "diam": 4.0 + }, + { + "name": "BAC046", + "n1": "BA0004613", + "n2": "BA0004710", + "diam": 4.0 + }, + { + "name": "BAC047", + "n1": "BA0004710", + "n2": "BA0004823", + "diam": 4.0 + }, + { + "name": "BAC048", + "n1": "BA0004823", + "n2": "BA0004893", + "diam": 4.0 + }, + { + "name": "BAC049", + "n1": "BA0004893", + "n2": "BA0004985", + "diam": 4.0 + }, + { + "name": "BAC050", + "n1": "BA0004985", + "n2": "BA0005061", + "diam": 4.0 + }, + { + "name": "BAC051", + "n1": "BA0005061", + "n2": "BA0005180", + "diam": 4.0 + }, + { + "name": "BAC052", + "n1": "BA0005180", + "n2": "BA0005279", + "diam": 4.0 + }, + { + "name": "BAC053", + "n1": "BA0005279", + "n2": "BA0005359", + "diam": 4.0 + }, + { + "name": "BAC054", + "n1": "BA0005359", + "n2": "BA0005423", + "diam": 4.0 + }, + { + "name": "BAC055", + "n1": "BA0005423", + "n2": "BA0005511", + "diam": 4.0 + }, + { + "name": "BAC056", + "n1": "BA0005511", + "n2": "BA0005580", + "diam": 4.0 + }, + { + "name": "BAC057", + "n1": "BA0005580", + "n2": "BA0005650", + "diam": 4.0 + }, + { + "name": "BAC058", + "n1": "BA0005650", + "n2": "BA0005767", + "diam": 4.0 + }, + { + "name": "BAC059", + "n1": "BA0005767", + "n2": "BA0005860", + "diam": 4.0 + }, + { + "name": "BAC060", + "n1": "BA0005860", + "n2": "BA0005945", + "diam": 4.0 + }, + { + "name": "BAC061", + "n1": "BA0005945", + "n2": "BA0006053", + "diam": 4.0 + }, + { + "name": "BAC062", + "n1": "BA0006053", + "n2": "BA0006170", + "diam": 4.0 + }, + { + "name": "BAC063", + "n1": "BA0006170", + "n2": "BA0006275", + "diam": 4.0 + }, + { + "name": "BAC064", + "n1": "BA0006275", + "n2": "BA0006413", + "diam": 4.0 + }, + { + "name": "BAC065", + "n1": "BA0006413", + "n2": "BA0006510", + "diam": 4.0 + }, + { + "name": "BAC066", + "n1": "BA0006510", + "n2": "BA0006572", + "diam": 4.0 + }, + { + "name": "BAC067", + "n1": "BA0006572", + "n2": "BA0006702", + "diam": 4.0 + }, + { + "name": "BAC068", + "n1": "BA0006702", + "n2": "BA0006807", + "diam": 4.0 + }, + { + "name": "BAC069", + "n1": "BA0006807", + "n2": "BA0006902", + "diam": 4.0 + }, + { + "name": "BAC070", + "n1": "BA0006902", + "n2": "BA0006971", + "diam": 4.0 + }, + { + "name": "BAC071", + "n1": "BA0006971", + "n2": "BA0007053", + "diam": 4.0 + }, + { + "name": "BAC072", + "n1": "BA0007053", + "n2": "TU0009817", + "diam": 4.0 + }, + { + "name": "BBC000", + "n1": "BB0000000", + "n2": "BB0000130", + "diam": 3.5 + }, + { + "name": "BBC001", + "n1": "BB0000130", + "n2": "BB0000201", + "diam": 3.5 + }, + { + "name": "BBC002", + "n1": "BB0000201", + "n2": "BB0000273", + "diam": 3.5 + }, + { + "name": "BBC003", + "n1": "BB0000273", + "n2": "BB0000335", + "diam": 3.5 + }, + { + "name": "BBC004", + "n1": "BB0000335", + "n2": "BB0000469", + "diam": 3.5 + }, + { + "name": "BBC005", + "n1": "BB0000469", + "n2": "BB0000568", + "diam": 3.5 + }, + { + "name": "BBC006", + "n1": "BB0000568", + "n2": "BB0000668", + "diam": 3.5 + }, + { + "name": "BBC007", + "n1": "BB0000668", + "n2": "BB0000778", + "diam": 3.5 + }, + { + "name": "BBC008", + "n1": "BB0000778", + "n2": "BB0000915", + "diam": 3.5 + }, + { + "name": "BBC009", + "n1": "BB0000915", + "n2": "BB0000981", + "diam": 3.5 + }, + { + "name": "BBC010", + "n1": "BB0000981", + "n2": "BB0001065", + "diam": 3.5 + }, + { + "name": "BBC011", + "n1": "BB0001065", + "n2": "BB0001168", + "diam": 3.5 + }, + { + "name": "BBC012", + "n1": "BB0001168", + "n2": "BB0001229", + "diam": 3.5 + }, + { + "name": "BBC013", + "n1": "BB0001229", + "n2": "BB0001359", + "diam": 3.5 + }, + { + "name": "BBC014", + "n1": "BB0001359", + "n2": "BB0001422", + "diam": 3.5 + }, + { + "name": "BBC015", + "n1": "BB0001422", + "n2": "BB0001540", + "diam": 3.5 + }, + { + "name": "BBC016", + "n1": "BB0001540", + "n2": "BB0001605", + "diam": 3.5 + }, + { + "name": "BBC017", + "n1": "BB0001605", + "n2": "BB0001679", + "diam": 3.5 + }, + { + "name": "BBC018", + "n1": "BB0001679", + "n2": "BB0001817", + "diam": 3.5 + }, + { + "name": "BBC019", + "n1": "BB0001817", + "n2": "BB0001934", + "diam": 3.5 + }, + { + "name": "BBC020", + "n1": "BB0001934", + "n2": "BB0002032", + "diam": 3.5 + }, + { + "name": "BBC021", + "n1": "BB0002032", + "n2": "BB0002116", + "diam": 3.5 + }, + { + "name": "BBC022", + "n1": "BB0002116", + "n2": "BB0002243", + "diam": 3.5 + }, + { + "name": "BBC023", + "n1": "BB0002243", + "n2": "BB0002336", + "diam": 3.5 + }, + { + "name": "BBC024", + "n1": "BB0002336", + "n2": "BB0002415", + "diam": 3.5 + }, + { + "name": "BBC025", + "n1": "BB0002415", + "n2": "BB0002507", + "diam": 3.5 + }, + { + "name": "BBC026", + "n1": "BB0002507", + "n2": "BB0002622", + "diam": 3.5 + }, + { + "name": "BBC027", + "n1": "BB0002622", + "n2": "BB0002721", + "diam": 3.5 + }, + { + "name": "BBC028", + "n1": "BB0002721", + "n2": "BB0002839", + "diam": 3.5 + }, + { + "name": "BBC029", + "n1": "BB0002839", + "n2": "BB0002977", + "diam": 3.5 + }, + { + "name": "BBC030", + "n1": "BB0002977", + "n2": "BB0003079", + "diam": 3.5 + }, + { + "name": "BBC031", + "n1": "BB0003079", + "n2": "BB0003149", + "diam": 3.5 + }, + { + "name": "BBC032", + "n1": "BB0003149", + "n2": "BB0003278", + "diam": 3.5 + }, + { + "name": "BBC033", + "n1": "BB0003278", + "n2": "BB0003350", + "diam": 3.5 + }, + { + "name": "BBC034", + "n1": "BB0003350", + "n2": "BB0003489", + "diam": 3.5 + }, + { + "name": "BBC035", + "n1": "BB0003489", + "n2": "BB0003628", + "diam": 3.5 + }, + { + "name": "BBC036", + "n1": "BB0003628", + "n2": "BB0003736", + "diam": 3.5 + }, + { + "name": "BBC037", + "n1": "BB0003736", + "n2": "BB0003841", + "diam": 3.5 + }, + { + "name": "BBC038", + "n1": "BB0003841", + "n2": "BB0003920", + "diam": 3.5 + }, + { + "name": "BBC039", + "n1": "BB0003920", + "n2": "BB0004045", + "diam": 3.5 + }, + { + "name": "BBC040", + "n1": "BB0004045", + "n2": "BB0004134", + "diam": 3.5 + }, + { + "name": "BBC041", + "n1": "BB0004134", + "n2": "BB0004265", + "diam": 3.5 + }, + { + "name": "BBC042", + "n1": "BB0004265", + "n2": "BB0004326", + "diam": 3.5 + }, + { + "name": "BBC043", + "n1": "BB0004326", + "n2": "BB0004414", + "diam": 3.5 + }, + { + "name": "BBC044", + "n1": "BB0004414", + "n2": "BB0004499", + "diam": 3.5 + }, + { + "name": "BBC045", + "n1": "BB0004499", + "n2": "BB0004614", + "diam": 3.5 + }, + { + "name": "BBC046", + "n1": "BB0004614", + "n2": "BB0004734", + "diam": 3.5 + }, + { + "name": "BBC047", + "n1": "BB0004734", + "n2": "BB0004858", + "diam": 3.5 + }, + { + "name": "BBC048", + "n1": "BB0004858", + "n2": "BB0004953", + "diam": 3.5 + }, + { + "name": "BBC049", + "n1": "BB0004953", + "n2": "BB0005056", + "diam": 3.5 + }, + { + "name": "BBC050", + "n1": "BB0005056", + "n2": "BB0005158", + "diam": 3.5 + }, + { + "name": "BBC051", + "n1": "BB0005158", + "n2": "BB0005220", + "diam": 3.5 + }, + { + "name": "BBC052", + "n1": "BB0005220", + "n2": "BB0005347", + "diam": 3.5 + }, + { + "name": "BBC053", + "n1": "BB0005347", + "n2": "BB0005425", + "diam": 3.5 + }, + { + "name": "BBC054", + "n1": "BB0005425", + "n2": "TM0007238", + "diam": 3.5 + } + ], + "coords": { + "TU0000000": [ + 10000.0, + 42000.0 + ], + "TU0000124": [ + 10073.820517602007, + 41900.280000002516 + ], + "TU0000243": [ + 10156.91850939342, + 41815.285213038806 + ], + "TU0000340": [ + 10220.600731974664, + 41741.578845900476 + ], + "TU0000435": [ + 10283.394985299003, + 41671.22228831974 + ], + "TU0000560": [ + 10356.608335383351, + 41569.13325055631 + ], + "TU0000624": [ + 10395.479154407709, + 41518.01545591004 + ], + "TU0000722": [ + 10464.94380410635, + 41449.22183060201 + ], + "TU0000835": [ + 10547.621187380677, + 41372.927770318915 + ], + "TU0000940": [ + 10632.320678559248, + 41310.04153167097 + ], + "TU0001043": [ + 10708.057125676043, + 41239.873193756226 + ], + "TU0001128": [ + 10764.859625613555, + 41177.61583062412 + ], + "TU0001211": [ + 10813.952136728172, + 41110.23281021342 + ], + "TU0001310": [ + 10870.322167369932, + 41029.59142871886 + ], + "TU0001388": [ + 10908.431630000605, + 40960.64781480622 + ], + "TU0001514": [ + 10953.54530850234, + 40843.76314922474 + ], + "TU0001586": [ + 10982.654873787806, + 40777.19574609984 + ], + "TU0001670": [ + 11016.911926520306, + 40700.75943209386 + ], + "TU0001788": [ + 11040.144827595996, + 40585.42649985388 + ], + "TU0001904": [ + 11069.034711167842, + 40472.80961931504 + ], + "TU0001982": [ + 11093.664925650475, + 40398.89897907814 + ], + "TU0002056": [ + 11111.21012861244, + 40326.80823868155 + ], + "TU0002136": [ + 11122.316864324368, + 40247.3125829121 + ], + "TU0002196": [ + 11132.349221911878, + 40188.07615132567 + ], + "TU0002329": [ + 11134.671873593581, + 40055.349989506336 + ], + "TU0002403": [ + 11149.638800288001, + 39982.88378781307 + ], + "TU0002542": [ + 11188.687961513622, + 39849.348440132584 + ], + "TU0002672": [ + 11222.79309509399, + 39724.061519402516 + ], + "TU0002811": [ + 11262.035162080543, + 39591.18142811673 + ], + "TU0002907": [ + 11305.572862777432, + 39505.30975954821 + ], + "TU0003035": [ + 11374.165694975829, + 39397.544551282015 + ], + "TU0003158": [ + 11437.97816713342, + 39292.447458295115 + ], + "TU0003232": [ + 11484.7578811846, + 39234.30864369846 + ], + "TU0003306": [ + 11522.421834646395, + 39171.4614231599 + ], + "TU0003428": [ + 11585.968188187568, + 39066.97762607997 + ], + "TU0003502": [ + 11622.489679967648, + 39002.678759547685 + ], + "TU0003572": [ + 11663.08899797101, + 38945.303105547835 + ], + "TU0003633": [ + 11703.505931498259, + 38899.64349293141 + ], + "TU0003725": [ + 11766.07282119302, + 38832.2793959886 + ], + "TU0003860": [ + 11845.753102147177, + 38723.00702972394 + ], + "TU0003925": [ + 11887.731979119151, + 38673.467444615424 + ], + "TU0004028": [ + 11941.931102074233, + 38586.605230555 + ], + "TU0004125": [ + 11983.918438902609, + 38498.64680316209 + ], + "TU0004230": [ + 12017.293363302806, + 38398.579093735236 + ], + "TU0004296": [ + 12033.843744458289, + 38335.455085681504 + ], + "TU0004396": [ + 12065.712234641449, + 38240.63123731199 + ], + "TU0004532": [ + 12102.191002619382, + 38109.87618834542 + ], + "TU0004635": [ + 12124.420178877821, + 38008.373136171496 + ], + "TU0004699": [ + 12147.029756227932, + 37949.4704726868 + ], + "TU0004824": [ + 12173.965301906701, + 37827.11354074039 + ], + "TU0004892": [ + 12184.171372883455, + 37759.41219640144 + ], + "TU0004960": [ + 12203.178118704871, + 37694.054602302225 + ], + "TU0005034": [ + 12211.726687057644, + 37620.52957857499 + ], + "TU0005118": [ + 12223.174358403205, + 37538.135028371216 + ], + "TU0005213": [ + 12256.125835314378, + 37448.22565180946 + ], + "TU0005350": [ + 12310.142467352103, + 37322.962010483454 + ], + "TU0005415": [ + 12334.813767201495, + 37262.82456829602 + ], + "TU0005538": [ + 12388.441159463477, + 37151.55463979527 + ], + "TU0005612": [ + 12405.667398505246, + 37079.60927510494 + ], + "TU0005720": [ + 12425.701577779224, + 36974.11520850384 + ], + "TU0005803": [ + 12438.985829990796, + 36891.36069642924 + ], + "TU0005888": [ + 12445.021959050555, + 36806.81820647559 + ], + "TU0005996": [ + 12450.792072230286, + 36698.640935887306 + ], + "TU0006069": [ + 12454.806834951249, + 36626.65844499711 + ], + "TU0006204": [ + 12475.205535499388, + 36492.474712309224 + ], + "TU0006329": [ + 12498.754666780944, + 36370.02118119974 + ], + "TU0006445": [ + 12517.773627815533, + 36256.08218409355 + ], + "TU0006547": [ + 12542.285119543712, + 36156.149801583284 + ], + "TU0006649": [ + 12569.536702777623, + 36057.79497760628 + ], + "TU0006784": [ + 12609.516165288816, + 35929.63791405059 + ], + "TU0006922": [ + 12653.870119471332, + 35798.32671554127 + ], + "TU0007041": [ + 12695.369196973315, + 35687.20926179498 + ], + "TU0007110": [ + 12717.204333535059, + 35621.57541784464 + ], + "TU0007249": [ + 12785.786074927168, + 35500.804914717985 + ], + "TU0007340": [ + 12835.820962781785, + 35424.40317431986 + ], + "TU0007462": [ + 12900.775610345507, + 35321.64495709117 + ], + "TU0007577": [ + 12967.026021809941, + 35227.51429339592 + ], + "TU0007686": [ + 13018.616737323504, + 35131.74921903769 + ], + "TU0007798": [ + 13064.543991847562, + 35029.34553553122 + ], + "TU0007917": [ + 13094.619449414204, + 34914.08928942449 + ], + "TU0008033": [ + 13121.390235502233, + 34801.73336175128 + ], + "TU0008128": [ + 13135.695180396875, + 34707.20994260032 + ], + "TU0008196": [ + 13150.784046666253, + 34641.307474969035 + ], + "TU0008327": [ + 13190.251200256756, + 34516.44397344847 + ], + "TU0008434": [ + 13235.3648924034, + 34418.86843465352 + ], + "TU0008546": [ + 13290.894747582306, + 34322.29020809184 + ], + "TU0008608": [ + 13321.951087716734, + 34267.70122915391 + ], + "TU0008742": [ + 13406.016880832989, + 34163.9700985074 + ], + "TU0008847": [ + 13455.411234574502, + 34071.785693465376 + ], + "TU0008976": [ + 13509.990494425887, + 33954.03138947203 + ], + "TU0009092": [ + 13569.480512233078, + 33855.11542220039 + ], + "TU0009193": [ + 13613.247958414942, + 33763.385476264346 + ], + "TU0009260": [ + 13639.488591860645, + 33701.82929458323 + ], + "TU0009338": [ + 13663.692154521044, + 33627.7393549568 + ], + "TU0009406": [ + 13674.236601993842, + 33560.925509012675 + ], + "TU0009470": [ + 13680.028228805077, + 33496.75598124031 + ], + "TU0009608": [ + 13665.147584436214, + 33360.344065271034 + ], + "TU0009718": [ + 13650.364708309327, + 33250.917668697904 + ], + "TU0009817": [ + 13638.552680416587, + 33152.70028005817 + ], + "TM0000096": [ + 13645.554790160977, + 33056.79937497027 + ], + "TM0000199": [ + 13641.599309025638, + 32954.28379094187 + ], + "TM0000310": [ + 13642.73660041183, + 32843.018873606416 + ], + "TM0000381": [ + 13626.53067203261, + 32773.72229699203 + ], + "TM0000450": [ + 13611.330453663004, + 32706.195511379447 + ], + "TM0000516": [ + 13606.668366658418, + 32641.116605714873 + ], + "TM0000580": [ + 13605.430918071293, + 32576.852430954208 + ], + "TM0000672": [ + 13593.838189307053, + 32485.566227730287 + ], + "TM0000767": [ + 13584.787504441696, + 32391.369057251657 + ], + "TM0000872": [ + 13593.778272313326, + 32286.114826385023 + ], + "TM0000987": [ + 13587.577493559545, + 32171.718542844268 + ], + "TM0001060": [ + 13594.448450752896, + 32099.290464244285 + ], + "TM0001158": [ + 13610.934902904724, + 32002.643344807864 + ], + "TM0001259": [ + 13619.734614717005, + 31901.640838463125 + ], + "TM0001339": [ + 13619.108880314197, + 31821.241531323554 + ], + "TM0001460": [ + 13617.738176000965, + 31700.13784141745 + ], + "TM0001579": [ + 13630.269754216835, + 31582.426259763022 + ], + "TM0001675": [ + 13640.9316017665, + 31487.006781729342 + ], + "TM0001742": [ + 13658.15463144538, + 31421.805545920644 + ], + "TM0001838": [ + 13681.78433613308, + 31328.945513179377 + ], + "TM0001947": [ + 13706.675153440856, + 31222.47216007454 + ], + "TM0002081": [ + 13728.39740293506, + 31090.631489634132 + ], + "TM0002189": [ + 13734.328339651956, + 30982.614829593225 + ], + "TM0002305": [ + 13763.414556830438, + 30870.573074749176 + ], + "TM0002412": [ + 13779.429227859662, + 30764.690059045726 + ], + "TM0002474": [ + 13798.71255868892, + 30705.823065827062 + ], + "TM0002582": [ + 13826.437957625683, + 30601.17472611481 + ], + "TM0002713": [ + 13846.452720498122, + 30472.086112747467 + ], + "TM0002773": [ + 13857.141333109643, + 30412.53948010312 + ], + "TM0002894": [ + 13894.966659168847, + 30297.781640441724 + ], + "TM0003030": [ + 13916.77410812155, + 30163.911564596583 + ], + "TM0003126": [ + 13950.769503369313, + 30073.87963788292 + ], + "TM0003262": [ + 14007.766198923502, + 29950.271194964458 + ], + "TM0003352": [ + 14047.157934689234, + 29869.986145378927 + ], + "TM0003416": [ + 14072.05540504186, + 29810.19047932152 + ], + "TM0003519": [ + 14111.167507094102, + 29715.525585688134 + ], + "TM0003585": [ + 14135.826762455112, + 29653.72344731356 + ], + "TM0003683": [ + 14164.8671343934, + 29560.609957971545 + ], + "TM0003808": [ + 14192.17651842638, + 29438.132050233566 + ], + "TM0003923": [ + 14211.412452185561, + 29325.574919717317 + ], + "TM0004047": [ + 14251.00602374068, + 29207.6624343322 + ], + "TM0004167": [ + 14293.535462330216, + 29095.18602425279 + ], + "TM0004263": [ + 14326.820134944572, + 29005.19092375067 + ], + "TM0004352": [ + 14332.535636910123, + 28916.974016336513 + ], + "TM0004432": [ + 14331.029108527038, + 28836.406786975833 + ], + "TM0004544": [ + 14327.172106004538, + 28724.713543599428 + ], + "TM0004675": [ + 14317.342919523053, + 28593.715113321534 + ], + "TM0004789": [ + 14309.610519939717, + 28480.029421055908 + ], + "TM0004865": [ + 14321.065712985923, + 28405.28981676963 + ], + "TM0004992": [ + 14323.832279104245, + 28278.668080856503 + ], + "TM0005127": [ + 14338.797650141662, + 28144.15452222511 + ], + "TM0005252": [ + 14361.237149578707, + 28020.993546824484 + ], + "TM0005377": [ + 14388.332980936097, + 27899.04873490574 + ], + "TM0005490": [ + 14413.242451270718, + 27788.92793847753 + ], + "TM0005578": [ + 14421.159766938938, + 27701.355242934336 + ], + "TM0005684": [ + 14405.255047203236, + 27596.62903904391 + ], + "TM0005760": [ + 14394.199789947465, + 27521.402593530667 + ], + "TM0005872": [ + 14370.894489010967, + 27411.913901351032 + ], + "TM0005955": [ + 14357.369799211105, + 27329.31340540768 + ], + "TM0006059": [ + 14335.04204685938, + 27228.509481761826 + ], + "TM0006123": [ + 14319.4570468477, + 27165.843899574495 + ], + "TM0006205": [ + 14286.353646342377, + 27091.447097228312 + ], + "TM0006319": [ + 14250.776974393057, + 26983.240794187153 + ], + "TM0006413": [ + 14214.343276661362, + 26896.367408949012 + ], + "TM0006552": [ + 14146.147611898172, + 26775.341956103075 + ], + "TM0006652": [ + 14096.586421584721, + 26687.62375004788 + ], + "TM0006717": [ + 14066.746865823594, + 26629.865431937647 + ], + "TM0006792": [ + 14027.131872158116, + 26566.9043337958 + ], + "TM0006897": [ + 13970.890756096913, + 26478.425747709163 + ], + "TM0006959": [ + 13940.612532045216, + 26423.69615608157 + ], + "TM0007031": [ + 13918.601090615752, + 26355.80195523095 + ], + "TM0007142": [ + 13894.163070142056, + 26247.08076199354 + ], + "TM0007238": [ + 13870.549137543268, + 26154.31766945564 + ], + "TL0000111": [ + 13850.304534333018, + 26045.582194056908 + ], + "TL0000172": [ + 13836.390287413653, + 25985.834629278106 + ], + "TL0000258": [ + 13813.267936079998, + 25903.43524275176 + ], + "TL0000356": [ + 13797.834311785258, + 25806.082520305543 + ], + "TL0000488": [ + 13781.829452221988, + 25675.080686771445 + ], + "TL0000569": [ + 13766.116912505671, + 25595.205308744615 + ], + "TL0000647": [ + 13751.204977934673, + 25519.512221815217 + ], + "TL0000749": [ + 13731.72933261497, + 25418.709881451927 + ], + "TL0000830": [ + 13709.71098427964, + 25340.57637409596 + ], + "TL0000936": [ + 13677.316193524173, + 25240.291778375737 + ], + "TL0001055": [ + 13620.04434861703, + 25135.815095888534 + ], + "TL0001128": [ + 13589.322583382602, + 25069.121630574104 + ], + "TL0001230": [ + 13540.25352598897, + 24980.517227564924 + ], + "TL0001347": [ + 13508.31486701443, + 24867.73992589776 + ], + "TL0001419": [ + 13474.249487458497, + 24803.815109806226 + ], + "TL0001507": [ + 13445.362046450527, + 24721.15523112069 + ], + "TL0001571": [ + 13422.621707920609, + 24661.231475869183 + ], + "TL0001682": [ + 13373.97678664944, + 24561.76000365641 + ], + "TL0001776": [ + 13332.78350765667, + 24477.031743828935 + ], + "TL0001874": [ + 13288.422121010695, + 24390.021343795204 + ], + "TL0001991": [ + 13231.55982758421, + 24287.769355523535 + ], + "TL0002075": [ + 13191.285136365763, + 24213.738234759003 + ], + "TL0002155": [ + 13160.335839893085, + 24140.095029850814 + ], + "TL0002282": [ + 13085.230760469443, + 24037.685892818627 + ], + "TL0002374": [ + 13021.48031572263, + 23970.576797355086 + ], + "TL0002444": [ + 12969.5456987033, + 23923.99336057594 + ], + "TL0002551": [ + 12896.991656983313, + 23845.892478568603 + ], + "TL0002658": [ + 12832.69205602809, + 23759.450776615155 + ], + "TL0002767": [ + 12769.479046368026, + 23670.791274003255 + ], + "TL0002880": [ + 12713.373988616964, + 23572.951843899657 + ], + "TL0002962": [ + 12681.48668729527, + 23498.011495926366 + ], + "TL0003039": [ + 12637.28951949873, + 23434.54792149084 + ], + "TL0003126": [ + 12582.48873647646, + 23366.643507617442 + ], + "TL0003263": [ + 12485.202657791133, + 23269.829950654257 + ], + "TL0003397": [ + 12394.762500006258, + 23171.157461916762 + ], + "TL0003471": [ + 12347.203640297259, + 23114.91370745345 + ], + "TL0003550": [ + 12307.746442357646, + 23046.800702284094 + ], + "TL0003627": [ + 12265.164467859042, + 22981.878333618413 + ], + "TL0003696": [ + 12226.23541298443, + 22925.79443873781 + ], + "TL0003812": [ + 12167.717875044606, + 22824.62773852784 + ], + "TL0003912": [ + 12103.914821892517, + 22748.319263809095 + ], + "TL0004035": [ + 12005.28152318455, + 22674.834919361914 + ], + "TL0004124": [ + 11935.275271270355, + 22619.63732187403 + ], + "TL0004231": [ + 11859.20846685756, + 22544.303045508757 + ], + "TL0004323": [ + 11787.028480970537, + 22487.70931012938 + ], + "TL0004460": [ + 11686.756371224745, + 22393.665037997936 + ], + "TL0004588": [ + 11609.50093216136, + 22292.12950300359 + ], + "TL0004707": [ + 11540.818543109131, + 22195.380240371112 + ], + "TL0004797": [ + 11484.6146526105, + 22125.035093850394 + ], + "TL0004894": [ + 11417.629549820434, + 22054.631652365468 + ], + "TL0005003": [ + 11343.352062057496, + 21973.967407730386 + ], + "TL0005119": [ + 11270.799105169694, + 21884.27785354899 + ], + "TL0005207": [ + 11206.46376277697, + 21823.665125241216 + ], + "TL0005323": [ + 11122.732650163216, + 21743.14388353317 + ], + "TL0005447": [ + 11031.656606223933, + 21659.10828676398 + ], + "TL0005564": [ + 10949.50362294982, + 21576.555012883724 + ], + "TL0005637": [ + 10896.805344323753, + 21525.486174757352 + ], + "TL0005767": [ + 10796.62154706134, + 21442.521174631325 + ], + "TL0005840": [ + 10745.507691775723, + 21390.50634153751 + ], + "TL0005912": [ + 10703.834797886608, + 21332.257354876387 + ], + "TL0006049": [ + 10609.495785167606, + 21232.559530588325 + ], + "TL0006125": [ + 10546.694379581062, + 21189.90849764819 + ], + "TL0006238": [ + 10446.932283386383, + 21135.935015234387 + ], + "TL0006375": [ + 10333.635702824786, + 21059.835739108636 + ], + "TL0006486": [ + 10244.379031589988, + 20993.787449892254 + ], + "TL0006608": [ + 10137.024756666024, + 20936.027769495933 + ], + "TL0006736": [ + 10024.460201237876, + 20874.95614116796 + ], + "TL0006842": [ + 9924.593750033884, + 20837.436514343317 + ], + "TL0006906": [ + 9863.411134450304, + 20819.42692977562 + ], + "TL0006972": [ + 9803.559967277666, + 20791.93027074692 + ], + "TL0007106": [ + 9680.69865441032, + 20737.88913074037 + ], + "TL0007246": [ + 9557.366743451483, + 20671.84153551763 + ], + "TL0007331": [ + 9488.006337150886, + 20623.6309696076 + ], + "TL0007391": [ + 9440.956562143658, + 20586.21379257415 + ], + "TL0007482": [ + 9372.373934163228, + 20526.829604403603 + ], + "TL0007592": [ + 9294.94977429366, + 20448.021078225207 + ], + "TL0007711": [ + 9201.173642765141, + 20375.554506220145 + ], + "TL0007780": [ + 9148.74506741453, + 20329.736677606725 + ], + "TL0007853": [ + 9087.958690611194, + 20290.3733527282 + ], + "TL0007940": [ + 9010.817574878989, + 20250.23186650458 + ], + "TL0008058": [ + 8910.860899265708, + 20185.954926661754 + ], + "TL0008156": [ + 8832.848837459145, + 20127.333141918858 + ], + "TL0008291": [ + 8732.495850977908, + 20036.42814282193 + ], + "TL0008415": [ + 8642.723006630815, + 19951.006194878137 + ], + "TL0008539": [ + 8555.294767621017, + 19863.09347965667 + ], + "TL0008657": [ + 8476.180194588725, + 19775.54700275152 + ], + "TL0008764": [ + 8398.522464089641, + 19701.70181007735 + ], + "FRS_Basin": [ + 8357.555665100728, + 19651.486546852124 + ], + "BA0000000": [ + 16368.232485132872, + 39642.97465455902 + ], + "BA0000066": [ + 16330.792209998499, + 39589.1660775527 + ], + "BA0000147": [ + 16275.930560471892, + 39528.3299079898 + ], + "BA0000248": [ + 16204.461988752393, + 39457.74668186657 + ], + "BA0000357": [ + 16129.476447851453, + 39379.123522027105 + ], + "BA0000491": [ + 16052.86896733914, + 39268.739337973035 + ], + "BA0000615": [ + 15995.382277798331, + 39158.780252949335 + ], + "BA0000735": [ + 15939.207905292727, + 39053.06999218432 + ], + "BA0000822": [ + 15911.875021287799, + 38970.49774431359 + ], + "BA0000926": [ + 15875.193295572733, + 38873.20536709536 + ], + "BA0000993": [ + 15857.355498910942, + 38807.95064771497 + ], + "BA0001132": [ + 15823.746411321315, + 38673.84039264823 + ], + "BA0001208": [ + 15797.550662393258, + 38601.70464033639 + ], + "BA0001310": [ + 15781.48108759098, + 38501.63105953338 + ], + "BA0001448": [ + 15758.368700079414, + 38365.667504276396 + ], + "BA0001560": [ + 15736.189936309418, + 38255.48553823761 + ], + "BA0001622": [ + 15725.624135713775, + 38194.3002347647 + ], + "BA0001740": [ + 15686.514346961574, + 38083.405331223694 + ], + "BA0001867": [ + 15637.14723961861, + 37966.181123434915 + ], + "BA0001947": [ + 15600.099095473053, + 37895.40396538927 + ], + "BA0002065": [ + 15544.412122269869, + 37791.21488140087 + ], + "BA0002151": [ + 15497.656433768107, + 37719.30056885116 + ], + "BA0002213": [ + 15472.7248580807, + 37662.10083587197 + ], + "BA0002283": [ + 15441.531419394285, + 37599.297478564564 + ], + "BA0002376": [ + 15390.11973138407, + 37521.5431031864 + ], + "BA0002479": [ + 15336.653216816552, + 37433.76181461515 + ], + "BA0002576": [ + 15297.181481155016, + 37344.85223818265 + ], + "BA0002678": [ + 15253.658497540024, + 37253.10636175625 + ], + "BA0002746": [ + 15220.933752271007, + 37193.92596995781 + ], + "BA0002849": [ + 15174.482285416825, + 37101.591856039566 + ], + "BA0002945": [ + 15121.461634753547, + 37021.05440203422 + ], + "BA0003033": [ + 15061.89298317324, + 36956.410754381475 + ], + "BA0003095": [ + 15037.694970469061, + 36900.05163609232 + ], + "BA0003235": [ + 15007.36449805564, + 36763.51312858077 + ], + "BA0003311": [ + 14988.605165550629, + 36688.972641880915 + ], + "BA0003404": [ + 14973.305987476453, + 36597.74938827983 + ], + "BA0003499": [ + 14962.507353025636, + 36502.797143074305 + ], + "BA0003631": [ + 14950.003437796362, + 36372.27848492579 + ], + "BA0003743": [ + 14945.666686721006, + 36260.20475007601 + ], + "BA0003851": [ + 14932.504391069708, + 36152.296937775754 + ], + "BA0003922": [ + 14922.64297178975, + 36082.16005220551 + ], + "BA0004020": [ + 14903.933883317599, + 35986.630803069944 + ], + "BA0004157": [ + 14854.188687881955, + 35858.97933972253 + ], + "BA0004271": [ + 14824.00592417256, + 35748.23882291607 + ], + "BA0004410": [ + 14768.724028810413, + 35620.82175991 + ], + "BA0004543": [ + 14705.764878944241, + 35503.589905528 + ], + "BA0004613": [ + 14667.954987567655, + 35444.71860570433 + ], + "BA0004710": [ + 14620.165135922789, + 35360.527211435605 + ], + "BA0004823": [ + 14560.384689184679, + 35264.5334999155 + ], + "BA0004893": [ + 14529.366748551774, + 35201.56180553355 + ], + "BA0004985": [ + 14484.895982945736, + 35121.14320617166 + ], + "BA0005061": [ + 14467.115172936856, + 35047.53990469067 + ], + "BA0005180": [ + 14448.836669663864, + 34929.50290754743 + ], + "BA0005279": [ + 14423.589057340238, + 34834.56278698816 + ], + "BA0005359": [ + 14399.423777422699, + 34757.719589749206 + ], + "BA0005423": [ + 14378.889134429262, + 34697.31542384504 + ], + "BA0005511": [ + 14341.584560308444, + 34617.13423854404 + ], + "BA0005580": [ + 14315.70135102514, + 34553.426261137574 + ], + "BA0005650": [ + 14285.457904985307, + 34490.25284042732 + ], + "BA0005767": [ + 14231.890206658487, + 34386.38612561747 + ], + "BA0005860": [ + 14195.295450590309, + 34301.177662786315 + ], + "BA0005945": [ + 14164.584382831343, + 34221.506708839384 + ], + "BA0006053": [ + 14139.207417872442, + 34116.77365939027 + ], + "BA0006170": [ + 14098.201905206612, + 34007.15087111261 + ], + "BA0006275": [ + 14056.863561590219, + 33910.32805229747 + ], + "BA0006413": [ + 13996.95778357837, + 33786.722846711564 + ], + "BA0006510": [ + 13940.049440477678, + 33707.55843595225 + ], + "BA0006572": [ + 13909.171291795623, + 33654.04549595683 + ], + "BA0006702": [ + 13850.670866309376, + 33538.03036131557 + ], + "BA0006807": [ + 13802.16568264165, + 33444.9552197047 + ], + "BA0006902": [ + 13756.822912485672, + 33361.27986651909 + ], + "BA0006971": [ + 13728.672283232165, + 33298.66036248056 + ], + "BA0007053": [ + 13681.939671949778, + 33230.574690882786 + ], + "BB0000000": [ + 9596.999616343335, + 29587.86844558454 + ], + "BB0000130": [ + 9717.41468207308, + 29538.772892829063 + ], + "BB0000201": [ + 9783.841655008879, + 29513.14247178434 + ], + "BB0000273": [ + 9845.941352619477, + 29476.99816508411 + ], + "BB0000335": [ + 9904.98630083392, + 29457.42948403666 + ], + "BB0000469": [ + 10029.515031058243, + 29409.68593091555 + ], + "BB0000568": [ + 10124.10390859734, + 29379.265677208376 + ], + "BB0000668": [ + 10210.367381396927, + 29328.505581423276 + ], + "BB0000778": [ + 10301.992719452473, + 29267.226718756767 + ], + "BB0000915": [ + 10400.976907667358, + 29172.691306696917 + ], + "BB0000981": [ + 10449.027944676698, + 29127.531562604792 + ], + "BB0001065": [ + 10507.28353457489, + 29066.875153163655 + ], + "BB0001168": [ + 10576.2862562531, + 28990.098091609852 + ], + "BB0001229": [ + 10616.604597425126, + 28945.18405822512 + ], + "BB0001359": [ + 10711.806483206929, + 28855.83878156531 + ], + "BB0001422": [ + 10759.130483320032, + 28814.168499234096 + ], + "BB0001540": [ + 10849.56617389457, + 28739.18880017662 + ], + "BB0001605": [ + 10895.35731934891, + 28693.233326689424 + ], + "BB0001679": [ + 10955.917188821946, + 28650.13067109138 + ], + "BB0001817": [ + 11069.267603642797, + 28570.800532458725 + ], + "BB0001934": [ + 11157.725872598194, + 28494.904858709593 + ], + "BB0002032": [ + 11228.455165396976, + 28427.669774914753 + ], + "BB0002116": [ + 11289.266349219683, + 28369.14283010866 + ], + "BB0002243": [ + 11375.252506016497, + 28276.30091683887 + ], + "BB0002336": [ + 11436.481388028851, + 28205.836543914174 + ], + "BB0002415": [ + 11488.114688679489, + 28145.940001421528 + ], + "BB0002507": [ + 11552.572497777184, + 28080.173656047617 + ], + "BB0002622": [ + 11642.938571616014, + 28009.887714971872 + ], + "BB0002721": [ + 11721.129139150114, + 27948.71464800272 + ], + "BB0002839": [ + 11812.252899721143, + 27874.25145435776 + ], + "BB0002977": [ + 11918.719270411833, + 27786.113294240942 + ], + "BB0003079": [ + 12003.794339327993, + 27729.647323709025 + ], + "BB0003149": [ + 12062.369950039552, + 27690.630280148525 + ], + "BB0003278": [ + 12168.825452086177, + 27618.292327197327 + ], + "BB0003350": [ + 12228.17828215751, + 27578.3154033285 + ], + "BB0003489": [ + 12343.852849844805, + 27500.409190369483 + ], + "BB0003628": [ + 12429.435045206192, + 27390.27445564866 + ], + "BB0003736": [ + 12490.286752368278, + 27301.837753145515 + ], + "BB0003841": [ + 12550.401219373236, + 27215.416009031756 + ], + "BB0003920": [ + 12600.625461667629, + 27154.944138194573 + ], + "BB0004045": [ + 12699.615637568086, + 27078.267335312816 + ], + "BB0004134": [ + 12776.811873412735, + 27033.33216591378 + ], + "BB0004265": [ + 12889.351656476696, + 26967.248626172048 + ], + "BB0004326": [ + 12944.839812005148, + 26942.317650502493 + ], + "BB0004414": [ + 13022.870282337757, + 26901.18443186419 + ], + "BB0004499": [ + 13093.045832168591, + 26853.034657954144 + ], + "BB0004614": [ + 13197.19573290731, + 26803.837519395463 + ], + "BB0004734": [ + 13294.890398991007, + 26734.62457148378 + ], + "BB0004858": [ + 13386.10331106229, + 26649.972596956035 + ], + "BB0004953": [ + 13458.881391644858, + 26589.182038981602 + ], + "BB0005056": [ + 13535.90358357368, + 26520.16215741525 + ], + "BB0005158": [ + 13608.522726842039, + 26448.81770687384 + ], + "BB0005220": [ + 13647.461225933599, + 26400.808296626787 + ], + "BB0005347": [ + 13728.183298812286, + 26302.692258403342 + ], + "BB0005425": [ + 13785.50045772619, + 26249.35323478025 + ], + "OUT_RIVER": [ + 9257.555665100728, + 18951.486546852124 + ], + "OUT_OVERFLOW": [ + 9457.555665100728, + 19951.486546852124 + ] + }, + "frs_invert": 418.43790039997515, + "tie_nodes": [ + "TU0009817", + "TM0007238" + ], + "heads": [ + "TU0000000", + "BA0000000", + "BB0000000" + ] +} \ No newline at end of file diff --git a/docs/figures/decks/cedar_glen/provenance.md b/docs/figures/decks/cedar_glen/provenance.md new file mode 100644 index 000000000..cea1a4831 --- /dev/null +++ b/docs/figures/decks/cedar_glen/provenance.md @@ -0,0 +1,40 @@ +# cedar_glen — a synthetic surveyed trunk chained by virtual junctions + +| | | +|---|---| +| Decks | `cedar_glen_fv.inp`, `cedar_glen_dw.inp`, `cedar_glen_dw_extran.inp` | +| Generator | `generate_model.py` (seeded 20260816; regeneration is byte-stable) | +| Metadata | `model_meta.json` — the trunk's chainage, invert and diameter, used by the figure | +| Copied from | `~/Downloads/epaswmm5_qa/article/cedar_glen/` (the SWMM paper's demonstration folder), 2026-09-20 | +| Used by | the Application Manual's virtual-junctions chapter; figures `workflow_ch4_cedar_glen_profile_hgl`, `workflow_ch4_cedar_glen_worst_node_head` | +| Changed on copy | nothing | + +## Provenance of the model itself + +**Every coordinate, elevation and name is invented by the generator.** +Nothing in this folder comes from any client dataset. The model is built +in the *style* of a GIS-derived raw-water conveyance — a long trunk of +short survey segments chained by virtual junctions, two lateral branches, +a terminal flow-regulating basin with orifice outlets — because that shape +is what makes virtual junctions matter, not because it reproduces a +particular system. + +## What it contains + +387 conduits, 370 of them joined by virtual junctions and 17 by real +junctions; a 25 884 ft trunk of 72, 78 and 90 in pipe with 48 and 42 in +branches; slopes of 0.10 to 0.30 %; a double-pocket reach between the two +tie-ins with a 1.55 % adverse riser to a crest at 455 ft; and a 24-hour +double surge-and-drain hydrograph whose second peak is 85 % of the first. +Junction `SurDepth` of 40 ft keeps the conveyance sealed. + +The three decks are identical but for their routing options: finite +volume, dynamic wave with the Preissmann slot, and dynamic wave with +EXTRAN surcharge. + +## Run times on this machine + +About 102 s for the finite-volume deck and 29 s and 9 s for the two +dynamic wave decks, on an Apple M-series laptop. The figure caches its +runs; `scripts/build_manual_figures.py run-decks` runs all three against +a 600 s budget. diff --git a/docs/figures/decks/coupled_1d2d/2d_complete_example.inp b/docs/figures/decks/coupled_1d2d/2d_complete_example.inp new file mode 100644 index 000000000..d39169afa --- /dev/null +++ b/docs/figures/decks/coupled_1d2d/2d_complete_example.inp @@ -0,0 +1,257 @@ +;;============================================================================ +;; OpenSWMM — Complete 2D Surface Routing Example +;; +;; A 20 m × 20 m parking lot meshed as 8 triangles on a 3×3 vertex grid, +;; sloping gently from north (z = 101.0) to south (z = 100.0). The mesh +;; exercises every 2D input section the engine currently parses: +;; +;; [2D_OPTIONS] — every documented key +;; [2D_VERTICES] — 9 vertices +;; [2D_TRIANGLES] — 8 triangles, Manning's n = 0.018 (asphalt) +;; [2D_VERTEX_NODE_MAP] — center vertex couples to drain inlet J1 +;; [2D_TRIANGLE_NODE_MAP] — NE-corner triangle couples to street vault ST1 +;; [2D_BOUNDARY_CONDITIONS] — one row each for NORMAL_FLOW, SPECIFIED_STAGE, +;; TS_STAGE, SPECIFIED_FLOW, RATING_CURVE +;; [2D_EDGE_CONVEYANCE] — east-west "leaky berm" at y = 10 m (c = 0.30) +;; +;; The optional `;; UNITS:` and `;; SOURCE_CRS:` comment headers at the top of +;; the file are read by the engine's prescan (see docs/2dModelStrategy.md §2A +;; and §11A). With `;; UNITS: SI (m)`, the engine treats the mesh values as +;; already-SI metres and skips its FLOW_UNITS-based ft→m scaling. For US-units +;; projects (FLOW_UNITS = CFS/GPM/MGD) you would either remove the header (and +;; let the engine multiply by 0.3048) or write mesh values in metres and keep +;; the header (recommended for new projects). +;; +;; To use an external `.2dm` mesh file instead of inline sections, comment out +;; the five [2D_*] mesh sections below and uncomment the [2D_MESH_FILE] block +;; at the very bottom of this file. +;;============================================================================ + +;; UNITS: SI (m) +;; SOURCE_CRS: EPSG:32616 + + +[TITLE] +2D Surface Routing — Complete Example +Demonstrates every implemented [2D_*] input section. + + +[OPTIONS] +FLOW_UNITS CMS +INFILTRATION GREEN_AMPT +FLOW_ROUTING DYNWAVE +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING NO +SKIP_STEADY_STATE NO + +START_DATE 01/01/2024 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2024 +REPORT_START_TIME 00:00:00 +END_DATE 01/01/2024 +END_TIME 06:00:00 +SWEEP_START 01/01 +SWEEP_END 12/31 +DRY_DAYS 0 +REPORT_STEP 00:05:00 +WET_STEP 00:05:00 +DRY_STEP 01:00:00 +ROUTING_STEP 00:00:15 + + +[EVAPORATION] +CONSTANT 0.0 +DRY_ONLY NO + + +[RAINGAGES] +;;Name Format Interval SCF Source +RG1 INTENSITY 0:05 1.0 TIMESERIES RAIN_TS + + +[JUNCTIONS] +;;Name Elevation MaxDepth InitDepth SurDepth Aponded +;; Rim elevation (= Elevation + MaxDepth) is 100.5 m — matches the surface +;; bed at v4 so the orifice gate opens as soon as water reaches the inlet. +J1 99.0 1.5 0.0 0.0 0.0 + + +[OUTFALLS] +;;Name Elevation Type Stage Gated Route To +OUT1 98.0 FREE * NO + + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape Coeff Exp Const SurDepth Fevap +;; Rim elevation (= Elev + MaxDepth) is 101.0 m, ~0.33 m above the T6 cell +;; centroid bed (≈ 100.67 m). Constant 5 m² area via FUNCTIONAL form. +ST1 99.5 1.5 0.0 FUNCTIONAL 0 0 5.0 0 0 + + +[CONDUITS] +;;Name FromNode ToNode Length Roughness InOffset OutOffset InitFlow MaxFlow +C1 J1 OUT1 100 0.013 0 0 0 0 +C2 ST1 OUT1 50 0.013 0 0 0 0 + + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +C1 CIRCULAR 0.30 0 0 0 1 +C2 CIRCULAR 0.20 0 0 0 1 + + +[TIMESERIES] +;;Name Date Time Value +;; Rainfall — 5 mm/hr for the first 2 hours, then dry. +RAIN_TS 01/01/2024 00:00 5.0 +RAIN_TS 02:00 5.0 +RAIN_TS 02:05 0.0 +RAIN_TS 06:00 0.0 + +;; Tidal stage on the east boundary (m): smooth diurnal swing 100.2 → 100.8. +TIDAL_TS 01/01/2024 00:00 100.20 +TIDAL_TS 01:30 100.55 +TIDAL_TS 03:00 100.80 +TIDAL_TS 04:30 100.55 +TIDAL_TS 06:00 100.20 + + +[CURVES] +;;Name Type X-Value Y-Value +;; Rating curve for the east-corner outflow edge: stage (m above bed) → flow (m³/s per m of edge). +DOWN_RC RATING 0.00 0.00 +DOWN_RC 0.25 0.05 +DOWN_RC 0.50 0.18 +DOWN_RC 1.00 0.55 +DOWN_RC 2.00 1.80 + + +[REPORT] +INPUT NO +CONTROLS NO +SUBCATCHMENTS ALL +NODES ALL +LINKS ALL + + +;;============================================================================ +;; 2D Surface Routing Sections +;;============================================================================ + + +[2D_OPTIONS] +;;Parameter Value ;; Notes +MAX_TIMESTEP 10.0 ;; Max marcher step (s) — caps CFL steps + sync batch +DRY_DEPTH 0.001 ;; Wet/dry threshold (m) +LIMITER_EPSILON 1.0e-6 ;; Jawahar-Kamath slope-limiter ε (output gradients) +COUPLING_CD 0.65 ;; Default discharge coefficient (overridden per-row below) +INTEGRATOR EXPLICIT ;; Explicit local-inertial LTS marcher (the default) +THETA 0.8 ;; Momentum θ-weighting (1 = Bates 2010) +CFL_NUMBER 0.7 ;; Courant safety factor α +H_MOVE 0.003 ;; Movement threshold (m) — lazy source-only below +LTS_TIERS 4 ;; Local-timestepping tiers (1 = global dt) +FROUDE_MAX 1.5 ;; Supercritical face |u| clamp +COUPLING_AREA DEFAULT ;; AUTO derives exchange areas from conduit areas +REPORT_2D YES ;; Toggle 2D reporting +OUTPUT_FILE 2d_complete_example.h5 ;; HDF5 output (relative to this .inp) + + +[2D_VERTICES] +;; X Y Z TAG +;; --------- -------- -------- ---------- + 0.0 0.0 100.00 ;; v0 — SW corner + 10.0 0.0 100.00 ;; v1 — south mid + 20.0 0.0 100.00 ;; v2 — SE corner + 0.0 10.0 100.50 ;; v3 — west mid + 10.0 10.0 100.50 ;; v4 — centre (couples to J1) + 20.0 10.0 100.50 ;; v5 — east mid + 0.0 20.0 101.00 ;; v6 — NW corner + 10.0 20.0 101.00 ;; v7 — north mid + 20.0 20.0 101.00 ;; v8 — NE corner + + +[2D_TRIANGLES] +;; V1 V2 V3 MANNINGS_N TAG +;; --- --- --- ---------- -------- + 0 1 4 0.018 ;; T0 — SW lower + 0 4 3 0.018 ;; T1 — SW upper + 1 2 5 0.018 ;; T2 — SE lower + 1 5 4 0.018 ;; T3 — SE upper + 3 4 7 0.018 ;; T4 — NW lower + 3 7 6 0.018 ;; T5 — NW upper + 4 5 8 0.018 vault ;; T6 — NE lower (couples to ST1) + 4 8 7 0.018 ;; T7 — NE upper + + +[2D_VERTEX_NODE_MAP] +;; VERTEX SWMM_NODE CD AREA (m²) +;; ------ --------- ---- ---- + 4 J1 0.65 2.0 ;; centre vertex → drain inlet + + +[2D_TRIANGLE_NODE_MAP] +;; TRIANGLE_OR_TAG SWMM_NODE CD AREA (m²) +;; ---------------- --------- ---- ---- + vault ST1 0.60 10.0 ;; NE-lower cell → street vault + + +[2D_BOUNDARY_CONDITIONS] +;; Per-edge boundary conditions. Format: TRI EDGE TYPE PARAM_1 PARAM_2 GROUP +;; PARAM_2 is reserved (always *); GROUP is optional (* = none). +;; Boundary edges not listed here default to WALL (zero flux). +;; +;; Local edge convention: edge e is opposite vertex e of the triangle. +;; For T0=(v0,v1,v4): e0=(v1,v4), e1=(v4,v0), e2=(v0,v1). +;; +;; TRI EDGE TYPE PARAM_1 PARAM_2 GROUP +;; --- ---- --------------- ------------- ------- -------- +;; South perimeter — let water leave under Manning's normal-flow: + 0 2 NORMAL_FLOW 0.0050 * * ;; T0 south edge (v0,v1) + 2 2 NORMAL_FLOW 0.0050 * * ;; T2 south edge (v1,v2) +;; +;; East perimeter — mixed tidal stage (timeseries) and rating-curve outflow: + 2 0 TS_STAGE TIDAL_TS * east_tide ;; T2 east edge (v2,v5) + 6 0 RATING_CURVE DOWN_RC * east_rc ;; T6 east edge (v5,v8) +;; +;; North perimeter — upstream inflow as specified per-metre flow + a constant stage: + 7 0 SPECIFIED_FLOW 0.0500 * upstream ;; T7 north edge (v8,v7) — inflow (outward-negative) + 5 0 SPECIFIED_STAGE 101.50 * * ;; T5 north edge (v7,v6) — fixed stage +;; +;; West perimeter — left default WALL (T5 e1 and T1 e1). + + +[2D_EDGE_CONVEYANCE] +;; "Leaky berm" running east–west at y = 10 m. Both interior edges along the +;; berm carry 30% of the diffusion-wave flux that the geometry would otherwise +;; allow. The engine mirrors each row to the partner slot on the neighbouring +;; triangle so antisymmetry (and mass conservation) is preserved. +;; +;; FROM_VERTEX TO_VERTEX CONVEYANCE +;; ----------- --------- ---------- + 3 4 0.30 ;; berm segment from v3 to v4 (T1↔T4) + 4 5 0.30 ;; berm segment from v4 to v5 (T3↔T6) + + +[COORDINATES] +;;Node X-Coord Y-Coord +J1 10.0 10.0 +ST1 15.0 15.0 +OUT1 22.0 0.0 + + +[MAP] +DIMENSIONS -2.0 -2.0 24.0 24.0 +UNITS Meters + + +;;============================================================================ +;; OPTIONAL — External mesh file +;; +;; To split the mesh into a sibling .2dm file (useful when the same mesh is +;; shared across multiple .inp configurations), delete the five [2D_*] mesh +;; sections above and uncomment the block below: +;; +;; [2D_MESH_FILE] +;; FILE 2d_complete_example.2dm +;;============================================================================ diff --git a/docs/figures/decks/hydrology_additions/provenance.md b/docs/figures/decks/hydrology_additions/provenance.md new file mode 100644 index 000000000..ba85f4c1f --- /dev/null +++ b/docs/figures/decks/hydrology_additions/provenance.md @@ -0,0 +1,39 @@ +# hydrology_additions — RDII with a physics-based recovery + +| | | +|---|---| +| Deck | `rdii_decay.inp` | +| Written for | the Application Manual's long-term-hydrology chapter; figure `workflow_ch11_rdii_decay_vs_linear` | +| RTK and decay coefficients from | `python/tests/engine/test_rdii_advancement.py:250-266`, the values that test pins | + +## What it is + +One sanitary sewer node fed by an RTK unit hydrograph group with three +response terms, each carrying a `[RDII_DECAY]` row, over a 30-day January. +Two identical six-hour storms fall nineteen days apart, and the air +temperature series warms through the month. + +The deck exists to show one thing: an RTK group alone answers both storms +identically, and the decay section makes the answer depend on what came +before and on how cold it has been. + +## Two parameter notes + +`T_ref` and `T_freeze` in `[RDII_DECAY]` are **degrees Celsius** whatever +the project's units are; this is a US deck, so its `[TEMPERATURE]` series +is Fahrenheit and the engine converts before evaluating the recovery rate. +The committed series runs 34 to 52 °F (1 to 11 °C) and the chapter's cold +variant runs 24 to 34 °F (−4 to +1 °C), which is mostly below the +`T_freeze` of 0 °C. + +`[HYDROGRAPHS]` keeps `Dmax` and `D0` when a decay row is present — they +describe the abstraction reservoir — but its linear recovery rate `Drec` +is ignored for that response. This deck leaves `Drec` at zero, so running +it with the decay section removed gives a linear model that never recovers +and abstracts both storms entirely. That is the contrast the figure draws, +and it is a real trap rather than a contrived one. + +## Snippet markers + +`;//! [options]`, `[temperature]`, `[rtk]` and `[decay]` bracket the blocks +the chapter quotes. diff --git a/docs/figures/decks/hydrology_additions/rdii_decay.inp b/docs/figures/decks/hydrology_additions/rdii_decay.inp new file mode 100644 index 000000000..e60cb2b2b --- /dev/null +++ b/docs/figures/decks/hydrology_additions/rdii_decay.inp @@ -0,0 +1,106 @@ +;;============================================================================ +;; OpenSWMM — RDII with a physics-based recovery, over two storms +;; +;; One sanitary sewer node fed by an RTK unit hydrograph group. The group's +;; three response terms each carry a [RDII_DECAY] row, so the second storm +;; produces less inflow than the first: the antecedent store has not fully +;; recovered, and how fast it recovers depends on temperature. +;; +;; Run it twice — as committed, and with the [TEMPERATURE] series lowered — +;; and the recovery between the storms changes. That is the whole point of +;; the section: an RTK group alone gives the same answer to both storms. +;; +;; Used by the Application Manual's long-term-hydrology chapter. +;;============================================================================ + +[TITLE] +RDII with seasonal decay, two storms thirty days apart + +;//! [options] +[OPTIONS] +FLOW_UNITS CFS +FLOW_ROUTING KINWAVE +INFILTRATION MODIFIED_GREEN_AMPT +START_DATE 01/01/2026 +START_TIME 00:00:00 +END_DATE 01/31/2026 +END_TIME 00:00:00 +REPORT_STEP 01:00:00 +WET_STEP 00:15:00 +DRY_STEP 01:00:00 +ROUTING_STEP 60 +;//! [options] + +[EVAPORATION] +CONSTANT 0.05 +DRY_ONLY NO + +;//! [temperature] +[TEMPERATURE] +TIMESERIES AIR_TEMP +;//! [temperature] + +[RAINGAGES] +;;Name Format Interval SCF Source +RG1 INTENSITY 1:00 1.0 TIMESERIES STORMS + +[TIMESERIES] +;;Name Date Time Value +;; two 6-hour storms, thirty days apart +STORMS 01/01/2026 06:00 0.00 +STORMS 01/01/2026 07:00 0.35 +STORMS 01/01/2026 09:00 0.55 +STORMS 01/01/2026 11:00 0.20 +STORMS 01/01/2026 13:00 0.00 +STORMS 01/20/2026 07:00 0.35 +STORMS 01/20/2026 09:00 0.55 +STORMS 01/20/2026 11:00 0.20 +STORMS 01/20/2026 13:00 0.00 +;; a cold month warming through it +AIR_TEMP 01/01/2026 00:00 34.0 +AIR_TEMP 01/10/2026 00:00 38.0 +AIR_TEMP 01/20/2026 00:00 45.0 +AIR_TEMP 01/31/2026 00:00 52.0 + +;//! [rtk] +[HYDROGRAPHS] +;;Group Gage/Month Response R T K Dmax Drec D0 +SanSewer RG1 +SanSewer All SHORT 0.055 1.0 2.0 8.0 0.0 2.0 +SanSewer All MEDIUM 0.032 3.5 2.0 8.0 0.0 2.0 +SanSewer All LONG 0.018 14.0 2.0 8.0 0.0 2.0 + +[RDII] +;;Node UHgroup SewerArea (ac) +J_RDII SanSewer 1000.0 +;//! [rtk] + +;//! [decay] +[RDII_DECAY] +;;UHgroup Response Kdep K0 KT Tref ThetaRec Tfreeze +SanSewer SHORT 0.15 0.010 0.070 10.0 0.055 0.0 +SanSewer MEDIUM 0.10 0.008 0.037 10.0 0.055 0.0 +SanSewer LONG 0.05 0.005 0.013 10.0 0.040 0.0 +;//! [decay] + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +J_RDII 10.0 6.0 0 0 0 + +[OUTFALLS] +;;Name Elev Type Gated +OUT1 8.0 FREE NO + +[CONDUITS] +;;Name From To Length Roughness InOffset OutOffset InitFlow +C1 J_RDII OUT1 400.0 0.013 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +C1 CIRCULAR 3.0 0 0 0 1 + +[REPORT] +INPUT NO +CONTINUITY YES +NODES ALL +LINKS ALL diff --git a/docs/figures/decks/mesh_hydrology/mesh_hydrology.inp b/docs/figures/decks/mesh_hydrology/mesh_hydrology.inp new file mode 100644 index 000000000..18e5bff2d --- /dev/null +++ b/docs/figures/decks/mesh_hydrology/mesh_hydrology.inp @@ -0,0 +1,147 @@ +;;============================================================================ +;; OpenSWMM — Rain, infiltration and groundwater on the mesh +;; +;; A 20 x 20 m patch of ground, meshed as eight triangles over nine vertices, +;; with three soil tags and a drain in the middle. Two rain gages stand at +;; opposite corners with different intensities, so the natural-neighbour +;; interpolation has something to interpolate: every cell takes a different +;; rainfall. Each tag infiltrates by its own method, and where the infiltrated +;; water goes is one key. +;; +;; RG_W (20 mm/hr) RG_E (5 mm/hr) +;; *----------------- mesh -----------------* +;; drain at the centre -> J1 -> O1 +;; +;; Used by the Application Manual's mesh-hydrology chapter. Variants in the +;; figures change [2D_OPTIONS] INFIL_DESTINATION and nothing else. +;;============================================================================ + +[TITLE] +Rain, infiltration and groundwater on the 2D mesh + +;//! [options] +[OPTIONS] +FLOW_UNITS CMS +FLOW_ROUTING DYNWAVE +START_DATE 01/01/2026 +START_TIME 00:00:00 +END_DATE 01/01/2026 +END_TIME 03:00:00 +REPORT_STEP 00:01:00 +WET_STEP 00:01:00 +DRY_STEP 00:01:00 +ROUTING_STEP 5 +ALLOW_PONDING NO +;//! [options] + +[EVAPORATION] +CONSTANT 0.0 +DRY_ONLY NO + +;//! [gages] +[RAINGAGES] +;;Name Format Interval SCF Source +RG_W INTENSITY 1:00 1.0 TIMESERIES TS_WEST +RG_E INTENSITY 1:00 1.0 TIMESERIES TS_EAST + +[SYMBOLS] +;;Gage X Y +RG_W -6.0 10.0 +RG_E 26.0 10.0 +;//! [gages] + +[TIMESERIES] +;;Name Date Time Value +;; one hour of rain, then two hours of recession +TS_WEST 01/01/2026 00:00 20.0 +TS_WEST 01/01/2026 01:00 0.0 +TS_WEST 01/01/2026 02:00 0.0 +TS_EAST 01/01/2026 00:00 5.0 +TS_EAST 01/01/2026 01:00 0.0 +TS_EAST 01/01/2026 02:00 0.0 + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +J1 6.0 2.0 0 0 0 + +[OUTFALLS] +;;Name Elev Type Gated +O1 5.0 FREE NO + +[CONDUITS] +;;Name From To Length Roughness InOffset OutOffset InitFlow +C1 J1 O1 30.0 0.013 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +C1 CIRCULAR 0.3 0 0 0 1 + +;//! [twod] +[2D_OPTIONS] +INTEGRATOR EXPLICIT +LTS_TIERS 1 +MAX_TIMESTEP 5 +DRY_DEPTH 0.001 +COUPLING_CD 0.7 +REPORT_2D YES +RAINFALL_MODE NATURAL_NEIGHBOUR +INFILTRATION YES +INFIL_DESTINATION AQUIFER_2D +GROUNDWATER YES +OUTPUT_FILE mesh_hydrology.h5 +;//! [twod] + +[2D_VERTICES] +;;X Y Z + 0.0 0.0 10.00 +10.0 0.0 10.00 +20.0 0.0 10.00 + 0.0 10.0 10.05 +10.0 10.0 9.90 +20.0 10.0 10.05 + 0.0 20.0 10.10 +10.0 20.0 10.10 +20.0 20.0 10.10 + +[2D_TRIANGLES] +;;V1 V2 V3 MANNINGS_N INIT_DEPTH TAG +0 1 4 0.030 0.0 LAWN +0 4 3 0.030 0.0 LAWN +1 2 5 0.018 0.0 PAVED +1 5 4 0.018 0.0 PAVED +3 4 7 0.045 0.0 WOODS +3 7 6 0.045 0.0 WOODS +4 5 8 0.030 0.0 LAWN +4 8 7 0.030 0.0 LAWN + +;//! [infiltration] +[2D_INFILTRATION_DEFAULTS] +;;TAG METHOD P1 P2 P3 P4 P5 DEST +* HORTON 25.0 2.5 4.0 - - +PAVED CONSTANT 1.0 - - - - +WOODS GREEN_AMPT 3.5 0.4 0.30 - - + +[2D_INFILTRATION_OPTIONS] +INFIL_STEP 0:05:00 +;//! [infiltration] + +;//! [aquifer] +[2D_AQUIFER_OPTIONS] +SOIL_CHAR GARDNER +CLOSURE AUTO +M_LAYERS 8 + +[2D_AQUIFER] +;;Scope KS ZS THETA_S THETA_R ALPHA [keywords] +* 36.0 4.0 0.45 0.10 2.0 HG0 1.0 +;//! [aquifer] + +[2D_VERTEX_NODE_MAP] +;;VERTEX SWMM_NODE CD AREA ;; AREA ~ the 0.3 m pipe's own area, per the engine's warning + 4 J1 0.70 0.07 + +[REPORT] +INPUT NO +CONTINUITY YES +NODES ALL +LINKS ALL diff --git a/docs/figures/decks/mesh_hydrology/provenance.md b/docs/figures/decks/mesh_hydrology/provenance.md new file mode 100644 index 000000000..2126ee696 --- /dev/null +++ b/docs/figures/decks/mesh_hydrology/provenance.md @@ -0,0 +1,43 @@ +# mesh_hydrology — rain, infiltration and an aquifer on a small mesh + +| | | +|---|---| +| Deck | `mesh_hydrology.inp` | +| Written for | the Application Manual's mesh-hydrology chapter; figure `workflow_ch7_rain_and_infiltration` | +| Composed from | the shapes of `tests/output/aquifer_2d/dest_ok.inp` and `tests/unit/engine/data/infil2d_out/g11_dest.inp`, 2026-09-20 | + +## What it is + +A 20 × 20 m patch of ground meshed as eight triangles over nine vertices, +falling gently toward a drain at the centre which is coupled to a junction +and a short pipe. Two rain gages stand west and east reading 20 and +5 mm/hr, so the natural-neighbour interpolation produces a different +rainfall in every cell. Three soil tags — `LAWN`, `PAVED`, `WOODS` — give +the cells Horton, constant-rate and Green-Ampt infiltration respectively, +and a mesh-wide two-layer aquifer sits beneath them. + +One hour of rain, two hours of recession, three-hour run. + +## Why it was written rather than copied + +No fixture exercised all three of the chapter's questions at once — +several gages, several infiltration methods, and a destination for the +infiltrated water. The two fixtures named above supply the shapes: the +aquifer deck's `[2D_AQUIFER]` row and the infiltration deck's tagged +triangles. + +## Two things the deck deliberately carries + +`AREA 0.07` on the coupling row is the drain pipe's own area. An earlier +version used 1.0 m² and the engine warned that the orifice could inject +fourteen times what the pipe can convey; the chapter quotes that warning. + +The gage interval is `1:00`, matching the rainfall series. With a 5-minute +interval against hourly series values the engine reads only the given +instants and the storm loses most of its volume — which is a real trap, +not an engine defect. + +## Snippet markers + +`;//! [options]`, `[gages]`, `[twod]`, `[infiltration]` and `[aquifer]` +bracket the blocks the chapter quotes with `\snippet`. diff --git a/docs/figures/decks/negative_pressure/e3_pressure_14p1.csv b/docs/figures/decks/negative_pressure/e3_pressure_14p1.csv new file mode 100644 index 000000000..fc43e5eee --- /dev/null +++ b/docs/figures/decks/negative_pressure/e3_pressure_14p1.csv @@ -0,0 +1,631 @@ +# source: Vasconcelos, Wright and Roe (2006) Fig. 6 -- raster image vasconcelos2006_p07_Im6.tiff extracted from the +# publisher PDF at native resolution (see results/_p6/figures_native/). +# quantity: pressure head (m) at x = 14.1 m, SI. time zero = the event. +# note: model markers and the experimental line are inseparable before ~41 s (the paper reports agreement over the first 40 s); the band centreline is digitized and the trace is cut at 41 s, past which the band is model-only (air-cavity intrusion, out of scope) +# x calibration (px -> s): 111.5 -> 0.0 873.0 -> 50.0 (axis box = axis limits) +# y calibration (px -> val): 131.5 -> 0.4 719.0 -> 0.0 (axis box = axis limits) +# open model markers removed by hole-filling; per-column longest ink run. +# digitized 2026-08-31 by scripts/digitize/vasconcelos_bilevel.py fig6_e3_p141 +time_s,head_m +0.1641,0.30162 +0.2298,0.30094 +0.2955,0.30094 +0.3611,0.30060 +0.4268,0.30026 +0.4924,0.29957 +0.5581,0.29889 +0.6238,0.29923 +0.6894,0.29889 +0.7551,0.29889 +0.8207,0.29889 +0.8864,0.29889 +0.9521,0.29889 +1.0177,0.29889 +1.0834,0.29889 +1.1490,0.29889 +1.2147,0.29923 +1.2804,0.29889 +1.3460,0.29889 +1.4117,0.29855 +1.4773,0.29855 +1.5430,0.29889 +1.6087,0.29889 +1.6743,0.29889 +1.7400,0.29889 +1.8056,0.29889 +1.8713,0.29889 +1.9370,0.29889 +2.0026,0.29889 +2.0683,0.29889 +2.1339,0.29889 +2.1996,0.29855 +2.2653,0.29787 +2.3309,0.29719 +2.3966,0.29685 +2.4622,0.29685 +2.5279,0.29685 +2.5936,0.29651 +2.6592,0.29617 +2.7249,0.29583 +2.7905,0.29583 +2.8562,0.29583 +2.9219,0.29549 +2.9875,0.29515 +3.0532,0.29481 +3.1188,0.29447 +3.1845,0.29413 +3.2502,0.29379 +3.3158,0.29345 +3.3815,0.29277 +3.4471,0.29277 +3.5128,0.29209 +3.5785,0.29174 +3.6441,0.29106 +3.7098,0.29072 +3.7754,0.29038 +3.8411,0.29004 +3.9068,0.28970 +3.9724,0.28936 +4.0381,0.28868 +4.1037,0.28766 +4.1694,0.28698 +4.2351,0.28698 +4.3007,0.28664 +4.3664,0.28596 +4.4320,0.28528 +4.4977,0.28460 +4.5634,0.28426 +4.6290,0.28391 +4.6947,0.28357 +4.7603,0.28255 +4.8260,0.28221 +4.8917,0.28119 +4.9573,0.28051 +5.0230,0.27949 +5.0886,0.27915 +5.1543,0.27847 +5.2200,0.27847 +5.2856,0.27779 +5.3513,0.27745 +5.4169,0.27677 +5.4826,0.27643 +5.5483,0.27540 +5.6139,0.27472 +5.6796,0.27336 +5.7452,0.27302 +5.8109,0.27200 +5.8766,0.27166 +5.9422,0.27098 +6.0079,0.27064 +6.0735,0.26928 +6.1392,0.26894 +6.2049,0.26860 +6.2705,0.26791 +6.3362,0.26757 +6.4018,0.26689 +6.4675,0.26621 +6.5332,0.26553 +6.5988,0.26451 +6.6645,0.26383 +6.7301,0.26383 +6.7958,0.26281 +6.8615,0.26213 +6.9271,0.26145 +6.9928,0.26043 +7.0584,0.25974 +7.1241,0.25872 +7.1898,0.25872 +7.2554,0.25804 +7.3211,0.25770 +7.3867,0.25702 +7.4524,0.25634 +7.5181,0.25566 +7.5837,0.25430 +7.6494,0.25362 +7.7150,0.25362 +7.7807,0.25362 +7.8464,0.25260 +7.9120,0.25191 +7.9777,0.25123 +8.0433,0.25021 +8.1090,0.24953 +8.1747,0.24953 +8.2403,0.24851 +8.3060,0.24851 +8.3716,0.24783 +8.4373,0.24749 +8.5030,0.24681 +8.5686,0.24613 +8.6343,0.24511 +8.6999,0.24511 +8.7656,0.24477 +8.8313,0.24443 +8.8969,0.24409 +8.9626,0.24340 +9.0282,0.24272 +9.0939,0.24272 +9.1596,0.24306 +9.2252,0.24136 +9.2909,0.24102 +9.3565,0.24068 +9.4222,0.24068 +9.4879,0.24068 +9.5535,0.24034 +9.6192,0.23932 +9.6848,0.23898 +9.7505,0.23864 +9.8162,0.23864 +9.8818,0.23864 +9.9475,0.23864 +10.0131,0.23796 +10.0788,0.23762 +10.1445,0.23728 +10.2101,0.23762 +10.2758,0.23762 +10.3414,0.23626 +10.4071,0.23591 +10.4728,0.23557 +10.5384,0.23557 +10.6041,0.23523 +10.6697,0.23523 +10.7354,0.23557 +10.8011,0.23523 +10.8667,0.23557 +10.9324,0.23591 +10.9980,0.23523 +11.0637,0.23523 +11.1293,0.23489 +11.1950,0.23455 +11.2607,0.23421 +11.3263,0.23421 +11.3920,0.23387 +11.4576,0.23353 +11.5233,0.23353 +11.5890,0.23319 +11.6546,0.23319 +11.7203,0.23353 +11.7859,0.23319 +11.8516,0.23319 +11.9173,0.23319 +11.9829,0.23319 +12.0486,0.23319 +12.1142,0.23319 +12.1799,0.23319 +12.2456,0.23319 +12.3112,0.23319 +12.3769,0.23319 +12.4425,0.23319 +12.5082,0.23319 +12.5739,0.23319 +12.6395,0.23319 +12.7052,0.23285 +12.7708,0.23319 +12.8365,0.23319 +12.9022,0.23319 +12.9678,0.23319 +13.0335,0.23319 +13.0991,0.23319 +13.1648,0.23285 +13.2305,0.23285 +13.2961,0.23319 +13.3618,0.23319 +13.4274,0.23319 +13.4931,0.23319 +13.5588,0.23319 +13.6244,0.23319 +13.6901,0.23319 +13.7557,0.23319 +13.8214,0.23319 +13.8871,0.23319 +13.9527,0.23251 +14.0184,0.23251 +14.0840,0.23217 +14.1497,0.23217 +14.2154,0.23217 +14.2810,0.23183 +14.3467,0.23149 +14.4123,0.23115 +14.4780,0.23115 +14.5437,0.23081 +14.6093,0.23115 +14.6750,0.23115 +14.7406,0.23115 +14.8063,0.23081 +14.8720,0.23115 +14.9376,0.23081 +15.0033,0.23047 +15.0689,0.22979 +15.1346,0.22945 +15.2003,0.22911 +15.2659,0.22911 +15.3316,0.22911 +15.3972,0.22911 +15.4629,0.22911 +15.5286,0.22843 +15.5942,0.22809 +15.6599,0.22774 +15.7255,0.22774 +15.7912,0.22740 +15.8569,0.22604 +15.9225,0.22570 +15.9882,0.22570 +16.0538,0.22536 +16.1195,0.22536 +16.1852,0.22468 +16.2508,0.22400 +16.3165,0.22332 +16.3821,0.22332 +16.4478,0.22332 +16.5135,0.22264 +16.5791,0.22196 +16.6448,0.22162 +16.7104,0.22128 +16.7761,0.22128 +16.8418,0.22060 +16.9074,0.21991 +16.9731,0.21889 +17.0387,0.21821 +17.1044,0.21753 +17.1701,0.21719 +17.2357,0.21719 +17.3014,0.21685 +17.3670,0.21583 +17.4327,0.21515 +17.4984,0.21481 +17.5640,0.21447 +17.6297,0.21379 +17.6953,0.21345 +17.7610,0.21277 +17.8267,0.21174 +17.8923,0.21140 +17.9580,0.21038 +18.0236,0.20970 +18.0893,0.20868 +18.1550,0.20834 +18.2206,0.20766 +18.2863,0.20732 +18.3519,0.20732 +18.4176,0.20664 +18.4833,0.20630 +18.5489,0.20528 +18.6146,0.20426 +18.6802,0.20357 +18.7459,0.20289 +18.8116,0.20153 +18.8772,0.20119 +18.9429,0.20017 +19.0085,0.19949 +19.0742,0.19949 +19.1399,0.19949 +19.2055,0.19915 +19.2712,0.19847 +19.3368,0.19779 +19.4025,0.19643 +19.4682,0.19574 +19.5338,0.19506 +19.5995,0.19370 +19.6651,0.19336 +19.7308,0.19268 +19.7965,0.19098 +19.8621,0.19064 +19.9278,0.18996 +19.9934,0.18962 +20.0591,0.18962 +20.1248,0.18996 +20.1904,0.18860 +20.2561,0.18826 +20.3217,0.18723 +20.3874,0.18655 +20.4531,0.18553 +20.5187,0.18485 +20.5844,0.18451 +20.6500,0.18383 +20.7157,0.18315 +20.7814,0.18281 +20.8470,0.18213 +20.9127,0.18179 +20.9783,0.18111 +21.0440,0.18111 +21.1097,0.18111 +21.1753,0.17974 +21.2410,0.17940 +21.3066,0.17872 +21.3723,0.17872 +21.4380,0.17804 +21.5036,0.17736 +21.5693,0.17702 +21.6349,0.17702 +21.7006,0.17668 +21.7663,0.17600 +21.8319,0.17532 +21.8976,0.17498 +21.9632,0.17498 +22.0289,0.17498 +22.0946,0.17464 +22.1602,0.17362 +22.2259,0.17362 +22.2915,0.17294 +22.3572,0.17260 +22.4228,0.17260 +22.4885,0.17260 +22.5542,0.17157 +22.6198,0.17123 +22.6855,0.17055 +22.7511,0.17055 +22.8168,0.17055 +22.8825,0.17055 +22.9481,0.17055 +23.0138,0.16987 +23.0794,0.16953 +23.1451,0.16953 +23.2108,0.16953 +23.2764,0.16885 +23.3421,0.16851 +23.4077,0.16851 +23.4734,0.16885 +23.5391,0.16851 +23.6047,0.16851 +23.6704,0.16817 +23.7360,0.16783 +23.8017,0.16783 +23.8674,0.16749 +23.9330,0.16783 +23.9987,0.16783 +24.0643,0.16749 +24.1300,0.16749 +24.1957,0.16783 +24.2613,0.16749 +24.3270,0.16749 +24.3926,0.16749 +24.4583,0.16749 +24.5240,0.16749 +24.5896,0.16715 +24.6553,0.16749 +24.7209,0.16783 +24.7866,0.16749 +24.8523,0.16749 +24.9179,0.16715 +24.9836,0.16681 +25.0492,0.16579 +25.1149,0.16647 +25.1806,0.16613 +25.2462,0.16579 +25.3119,0.16545 +25.3775,0.16545 +25.4432,0.16545 +25.5089,0.16545 +25.5745,0.16545 +25.6402,0.16545 +25.7058,0.16545 +25.7715,0.16545 +25.8372,0.16545 +25.9028,0.16545 +25.9685,0.16545 +26.0341,0.16545 +26.0998,0.16545 +26.1655,0.16545 +26.2311,0.16545 +26.2968,0.16545 +26.3624,0.16545 +26.4281,0.16545 +26.4938,0.16545 +26.5594,0.16545 +26.6251,0.16545 +26.6907,0.16545 +26.7564,0.16545 +26.8221,0.16545 +26.8877,0.16545 +26.9534,0.16545 +27.0190,0.16511 +27.0847,0.16511 +27.1504,0.16443 +27.2160,0.16374 +27.2817,0.16340 +27.3473,0.16340 +27.4130,0.16306 +27.4787,0.16272 +27.5443,0.16272 +27.6100,0.16306 +27.6756,0.16306 +27.7413,0.16272 +27.8070,0.16204 +27.8726,0.16170 +27.9383,0.16136 +28.0039,0.16102 +28.0696,0.16068 +28.1353,0.16034 +28.2009,0.16000 +28.2666,0.16000 +28.3322,0.15966 +28.3979,0.15932 +28.4636,0.15898 +28.5292,0.15898 +28.5949,0.15864 +28.6605,0.15830 +28.7262,0.15762 +28.7919,0.15796 +28.8575,0.15796 +28.9232,0.15728 +28.9888,0.15660 +29.0545,0.15591 +29.1202,0.15557 +29.1858,0.15489 +29.2515,0.15455 +29.3171,0.15421 +29.3828,0.15353 +29.4485,0.15387 +29.5141,0.15353 +29.5798,0.15319 +29.6454,0.15251 +29.7111,0.15149 +29.7768,0.15047 +29.8424,0.14945 +29.9081,0.14911 +29.9737,0.14774 +30.0394,0.14774 +30.1051,0.14740 +30.1707,0.14740 +30.2364,0.14706 +30.3020,0.14672 +30.3677,0.14536 +30.4334,0.14502 +30.4990,0.14468 +30.5647,0.14400 +30.6303,0.14332 +30.6960,0.14264 +30.7617,0.14162 +30.8273,0.14128 +30.8930,0.14094 +30.9586,0.13991 +31.0243,0.13923 +31.0900,0.13855 +31.1556,0.13753 +31.2213,0.13719 +31.2869,0.13651 +31.3526,0.13617 +31.4183,0.13549 +31.4839,0.13549 +31.5496,0.13447 +31.6152,0.13379 +31.6809,0.13277 +31.7466,0.13209 +31.8122,0.13140 +31.8779,0.13072 +31.9435,0.12970 +32.0092,0.12902 +32.0749,0.12868 +32.1405,0.12834 +32.2062,0.12834 +32.2718,0.12800 +32.3375,0.12732 +32.4032,0.12596 +32.4688,0.12562 +32.5345,0.12460 +32.6001,0.12426 +32.6658,0.12357 +32.7315,0.12323 +32.7971,0.12221 +32.8628,0.12221 +32.9284,0.12221 +32.9941,0.12153 +33.0598,0.12119 +33.1254,0.11983 +33.1911,0.11983 +33.2567,0.11813 +33.3224,0.11711 +33.3880,0.11711 +33.4537,0.11711 +33.5194,0.11677 +33.5850,0.11643 +33.6507,0.11574 +33.7163,0.11540 +33.7820,0.11540 +33.8477,0.11472 +33.9133,0.11404 +33.9790,0.11370 +34.0446,0.11302 +34.1103,0.11268 +34.1760,0.11268 +34.2416,0.11268 +34.3073,0.11132 +34.3729,0.11132 +34.4386,0.11064 +34.5043,0.11030 +34.5699,0.11030 +34.6356,0.11064 +34.7012,0.11030 +34.7669,0.10962 +34.8326,0.10894 +34.8982,0.10826 +34.9639,0.10826 +35.0295,0.10791 +35.0952,0.10655 +35.1609,0.10621 +35.2265,0.10655 +35.2922,0.10689 +35.3578,0.10655 +35.4235,0.10621 +35.4892,0.10621 +35.5548,0.10655 +35.6205,0.10519 +35.6861,0.10485 +35.7518,0.10451 +35.8175,0.10451 +35.8831,0.10451 +35.9488,0.10451 +36.0144,0.10417 +36.0801,0.10383 +36.1458,0.10349 +36.2114,0.10315 +36.2771,0.10315 +36.3427,0.10315 +36.4084,0.10349 +36.4741,0.10281 +36.5397,0.10281 +36.6054,0.10213 +36.6710,0.10213 +36.7367,0.10247 +36.8024,0.10111 +36.8680,0.10111 +36.9337,0.10145 +36.9993,0.10145 +37.0650,0.10145 +37.1307,0.10111 +37.1963,0.10111 +37.2620,0.10111 +37.3276,0.10111 +37.3933,0.10111 +37.4590,0.10009 +37.5246,0.10009 +37.5903,0.10009 +37.6559,0.10009 +37.7216,0.10043 +37.7873,0.10077 +37.8529,0.10009 +37.9186,0.10009 +37.9842,0.10009 +38.0499,0.10009 +38.1156,0.10009 +38.1812,0.10009 +38.2469,0.09974 +38.3125,0.10009 +38.3782,0.10009 +38.4439,0.10009 +38.5095,0.10009 +38.5752,0.10009 +38.6408,0.10009 +38.7065,0.10009 +38.7722,0.10009 +38.8378,0.09940 +38.9035,0.09906 +38.9691,0.09838 +39.0348,0.09804 +39.1005,0.09804 +39.1661,0.09804 +39.2318,0.09770 +39.2974,0.09770 +39.3631,0.09804 +39.4288,0.09770 +39.4944,0.09770 +39.5601,0.09804 +39.6257,0.09804 +39.6914,0.09804 +39.7571,0.09872 +39.8227,0.09906 +39.8884,0.09906 +39.9540,0.09906 +40.0197,0.09906 +40.0854,0.09940 +40.1510,0.09974 +40.2167,0.10043 +40.2823,0.10077 +40.3480,0.10111 +40.4137,0.10213 +40.4793,0.10349 +40.5450,0.10383 +40.6106,0.10587 +40.6763,0.10655 +40.7420,0.10757 +40.8076,0.10519 +40.8733,0.10519 +40.9389,0.10519 diff --git a/docs/figures/decks/negative_pressure/e3_velocity_9p9.csv b/docs/figures/decks/negative_pressure/e3_velocity_9p9.csv new file mode 100644 index 000000000..5a6eee609 --- /dev/null +++ b/docs/figures/decks/negative_pressure/e3_velocity_9p9.csv @@ -0,0 +1,767 @@ +# source: Vasconcelos, Wright and Roe (2006) Fig. 5 -- raster image vasconcelos2006_p07_Im5.tiff extracted from the +# publisher PDF at native resolution (see results/_p6/figures_native/). +# quantity: water velocity (m/s) at x = 9.9 m, SI. time zero = the event. +# note: figure ordinate is cm/s; converted to m/s (x 0.01) +# x calibration (px -> s): 103.0 -> 0.0 876.5 -> 50.0 (axis box = axis limits) +# y calibration (px -> val): 131.0 -> 0.0 737.5 -> -6.0 (axis box = axis limits) +# open model markers removed by hole-filling; per-column longest ink run. +# digitized 2026-08-31 by scripts/digitize/vasconcelos_bilevel.py fig5_e3_v99 +time_s,velocity_mps +0.1293,-0.00109 +0.1939,-0.00104 +0.2586,-0.00099 +0.3232,-0.00089 +0.3878,-0.00089 +0.4525,-0.00094 +0.5171,-0.00163 +0.5818,-0.00168 +0.6464,-0.00267 +0.7111,-0.00267 +0.7757,-0.00064 +0.8403,-0.00064 +0.9050,-0.00376 +0.9696,-0.00064 +1.0343,-0.00064 +1.0989,-0.00064 +1.1635,-0.00064 +1.2282,-0.00064 +1.2928,-0.00064 +1.3575,-0.00059 +1.4221,-0.00089 +1.4867,-0.00143 +1.5514,-0.00143 +1.6160,-0.00153 +1.6807,-0.00228 +1.7453,-0.00267 +1.8100,-0.00302 +1.8746,-0.00326 +1.9392,-0.00341 +2.0039,-0.00406 +2.0685,-0.00425 +2.1332,-0.00579 +2.1978,-0.00579 +2.2624,-0.00722 +2.3271,-0.01736 +2.3917,-0.00979 +2.4564,-0.01825 +2.5210,-0.00935 +2.5856,-0.00935 +2.6503,-0.02013 +2.7149,-0.01024 +2.7796,-0.01009 +2.8442,-0.01004 +2.9089,-0.01148 +2.9735,-0.02320 +3.1028,-0.01331 +3.1674,-0.01336 +3.2321,-0.01509 +3.2967,-0.01434 +3.3613,-0.01434 +3.4260,-0.01726 +3.4906,-0.01617 +3.5553,-0.01904 +3.6846,-0.01998 +3.7492,-0.03146 +3.8138,-0.02201 +3.8785,-0.02211 +3.9431,-0.02107 +4.0078,-0.02389 +4.0724,-0.02394 +4.1370,-0.02320 +4.2017,-0.02572 +4.2663,-0.02498 +4.3956,-0.03744 +4.4602,-0.03744 +4.5249,-0.02879 +4.5895,-0.02889 +4.6542,-0.02810 +4.7188,-0.03932 +4.8481,-0.03141 +4.9127,-0.03141 +4.9774,-0.04026 +5.0420,-0.03462 +5.1067,-0.03467 +5.1713,-0.03556 +5.2359,-0.03586 +5.3006,-0.03591 +5.3652,-0.03660 +5.4299,-0.03705 +5.4945,-0.03705 +5.5591,-0.04190 +5.6238,-0.03868 +5.6884,-0.03858 +5.7531,-0.03853 +5.8177,-0.03853 +5.8824,-0.03858 +5.9470,-0.04239 +6.0116,-0.04239 +6.0763,-0.04244 +6.1409,-0.04249 +6.2056,-0.04254 +6.2702,-0.04254 +6.3348,-0.04254 +6.3995,-0.04254 +6.4641,-0.03705 +6.5288,-0.03705 +6.5934,-0.03710 +6.6580,-0.03710 +6.7227,-0.03715 +6.7873,-0.03715 +6.8520,-0.03715 +6.9166,-0.03715 +6.9813,-0.03754 +7.0459,-0.03739 +7.1105,-0.03739 +7.1752,-0.03739 +7.2398,-0.03364 +7.3045,-0.03359 +7.3691,-0.03324 +7.4337,-0.03319 +7.4984,-0.04106 +7.5630,-0.04101 +7.6277,-0.04096 +7.6923,-0.03062 +7.7569,-0.03057 +7.8216,-0.03052 +7.8862,-0.03052 +7.9509,-0.03052 +8.0155,-0.03052 +8.0802,-0.02943 +8.1448,-0.02938 +8.2094,-0.02928 +8.2741,-0.02755 +8.3387,-0.02750 +8.4034,-0.02602 +8.4680,-0.02582 +8.5326,-0.02562 +8.5973,-0.02384 +8.6619,-0.02384 +8.7266,-0.02379 +8.7912,-0.02320 +8.8559,-0.02320 +8.9205,-0.02236 +8.9851,-0.02018 +9.0498,-0.01984 +9.1144,-0.01979 +9.1791,-0.01944 +9.2437,-0.01880 +9.3083,-0.02918 +9.3730,-0.02735 +9.4376,-0.02735 +9.5023,-0.02730 +9.5669,-0.01568 +9.6315,-0.01494 +9.6962,-0.01479 +9.7608,-0.02463 +9.8255,-0.01519 +9.8901,-0.01232 +10.0194,-0.02270 +10.0840,-0.02073 +10.1487,-0.02068 +10.2133,-0.01894 +10.2780,-0.01890 +10.3426,-0.01885 +10.4072,-0.00900 +10.4719,-0.00900 +10.5365,-0.01702 +10.6012,-0.00712 +10.6658,-0.01608 +10.7304,-0.00569 +10.7951,-0.01430 +10.8597,-0.01425 +10.9244,-0.00500 +10.9890,-0.01078 +11.0537,-0.01237 +11.1183,-0.00376 +11.2476,-0.00287 +11.3122,-0.00979 +11.3769,-0.00297 +11.4415,-0.00856 +11.5061,-0.00791 +11.5708,-0.00247 +11.6354,-0.00232 +11.7001,-0.00228 +11.7647,-0.00213 +11.8293,-0.00213 +11.8940,-0.00208 +11.9586,-0.00198 +12.0233,-0.00297 +12.0879,-0.00287 +12.1526,-0.00228 +12.2172,-0.00228 +12.2818,-0.00228 +12.3465,-0.00247 +12.4111,-0.00247 +12.4758,-0.00242 +12.5404,-0.00228 +12.6050,-0.00163 +12.6697,-0.00148 +12.7343,-0.00168 +12.7990,-0.00168 +12.8636,-0.00173 +12.9282,-0.00213 +12.9929,-0.00218 +13.0575,-0.00218 +13.1222,-0.00213 +13.1868,-0.00099 +13.2515,-0.00099 +13.3161,-0.00099 +13.3807,-0.00099 +13.4454,-0.00539 +13.5100,-0.00564 +13.5747,-0.00564 +13.6393,-0.00099 +13.7039,-0.00104 +13.7686,-0.00109 +13.8332,-0.00114 +13.8979,-0.00124 +13.9625,-0.00138 +14.0271,-0.00193 +14.0918,-0.00203 +14.1564,-0.00257 +14.2211,-0.00262 +14.2857,-0.00302 +14.3504,-0.00371 +14.4150,-0.00371 +14.4796,-0.00406 +14.5443,-0.00475 +14.6089,-0.00490 +14.6736,-0.00559 +14.7382,-0.00594 +14.8028,-0.00613 +14.8675,-0.00623 +14.9321,-0.00737 +14.9968,-0.00791 +15.0614,-0.00707 +15.1261,-0.00876 +15.1907,-0.00910 +15.2553,-0.01998 +15.4493,-0.02068 +15.5139,-0.01083 +15.5785,-0.01078 +15.6432,-0.01336 +15.7078,-0.01261 +15.7725,-0.01514 +15.8371,-0.02567 +15.9017,-0.01647 +15.9664,-0.01627 +16.0310,-0.02849 +16.0957,-0.01786 +16.1603,-0.01791 +16.2250,-0.01800 +16.2896,-0.01974 +16.3542,-0.03181 +16.4189,-0.01899 +16.4835,-0.03265 +16.5482,-0.03265 +16.6128,-0.03275 +16.6774,-0.03279 +16.7421,-0.02335 +16.8067,-0.02335 +16.8714,-0.02523 +16.9360,-0.02528 +17.0006,-0.02533 +17.0653,-0.02854 +17.1299,-0.02854 +17.1946,-0.02869 +17.2592,-0.02869 +17.3239,-0.02869 +17.3885,-0.03190 +17.4531,-0.02943 +17.5178,-0.02884 +17.5824,-0.02928 +17.6471,-0.02904 +17.7117,-0.02904 +17.7763,-0.02978 +17.8410,-0.03561 +17.9056,-0.03566 +17.9703,-0.03092 +18.0349,-0.03087 +18.0995,-0.04066 +18.1642,-0.03141 +18.2288,-0.03181 +18.2935,-0.03190 +18.3581,-0.04091 +18.4228,-0.04026 +18.4874,-0.04036 +18.5520,-0.04066 +18.6167,-0.04071 +18.6813,-0.04110 +18.7460,-0.04125 +18.8106,-0.04135 +18.8752,-0.03299 +18.9399,-0.03289 +19.0045,-0.04170 +19.0692,-0.04170 +19.1338,-0.04165 +19.1984,-0.03151 +19.2631,-0.03151 +19.3277,-0.03116 +19.3924,-0.03106 +19.4570,-0.03072 +19.5217,-0.02933 +19.5863,-0.02918 +19.6509,-0.02918 +19.7156,-0.02973 +19.7802,-0.02983 +19.8449,-0.03017 +19.9095,-0.03007 +19.9741,-0.02889 +20.0388,-0.02859 +20.1034,-0.04041 +20.1681,-0.04036 +20.2327,-0.04031 +20.2973,-0.02696 +20.3620,-0.02696 +20.4266,-0.02676 +20.4913,-0.02602 +20.5559,-0.02498 +20.6206,-0.02488 +20.6852,-0.03779 +20.7498,-0.03725 +20.8145,-0.03705 +20.8791,-0.03665 +20.9438,-0.03660 +21.0084,-0.02354 +21.0730,-0.02364 +21.1377,-0.02295 +21.2023,-0.02285 +21.2670,-0.02275 +21.3316,-0.02077 +21.3963,-0.02073 +21.4609,-0.02068 +21.5255,-0.02073 +21.5902,-0.02073 +21.6548,-0.01998 +21.7195,-0.01924 +21.7841,-0.01904 +21.8487,-0.01810 +21.9134,-0.01756 +21.9780,-0.01741 +22.0427,-0.01563 +22.1073,-0.01563 +22.1719,-0.01479 +22.2366,-0.01469 +22.3012,-0.01469 +22.3659,-0.01380 +22.4305,-0.01350 +22.4952,-0.01331 +22.5598,-0.01207 +22.6244,-0.01192 +22.6891,-0.01128 +22.7537,-0.01083 +22.8184,-0.01073 +22.8830,-0.01924 +22.9476,-0.00979 +23.0123,-0.00969 +23.0769,-0.01830 +23.1416,-0.00752 +23.2062,-0.00752 +23.2708,-0.00752 +23.3355,-0.00697 +23.4001,-0.01494 +23.4648,-0.01573 +23.5294,-0.00564 +23.5941,-0.01256 +23.6587,-0.01395 +23.7233,-0.00485 +23.8526,-0.01044 +23.9173,-0.01014 +23.9819,-0.00979 +24.0465,-0.00307 +24.1112,-0.00302 +24.1758,-0.00282 +24.2405,-0.00277 +24.3051,-0.00272 +24.3697,-0.00262 +24.4344,-0.00257 +24.4990,-0.00252 +24.5637,-0.00247 +24.6283,-0.00242 +24.6930,-0.00232 +24.7576,-0.00228 +24.8222,-0.00322 +24.8869,-0.00312 +24.9515,-0.00307 +25.0162,-0.00287 +25.0808,-0.00138 +25.1454,-0.00134 +25.2101,-0.00134 +25.2747,-0.00134 +25.3394,-0.00465 +25.4040,-0.00465 +25.4686,-0.00129 +25.5333,-0.00465 +25.5979,-0.00465 +25.6626,-0.00129 +25.7272,-0.00129 +25.7919,-0.00134 +25.8565,-0.00134 +25.9211,-0.00158 +25.9858,-0.00163 +26.0504,-0.00168 +26.1151,-0.00737 +26.1797,-0.00737 +26.2443,-0.00727 +26.3090,-0.00722 +26.3736,-0.00717 +26.4383,-0.00203 +26.5029,-0.00208 +26.5676,-0.00237 +26.6322,-0.00242 +26.6968,-0.00257 +26.7615,-0.00317 +26.8261,-0.00322 +26.8908,-0.00341 +26.9554,-0.00406 +27.0200,-0.00415 +27.0847,-0.00435 +27.1493,-0.00519 +27.2140,-0.00534 +27.2786,-0.00633 +27.3432,-0.00658 +27.4079,-0.00692 +27.4725,-0.00732 +27.5372,-0.00752 +27.6018,-0.00757 +27.6665,-0.01776 +27.7311,-0.00890 +27.7957,-0.00876 +27.8604,-0.00876 +27.9250,-0.01004 +27.9897,-0.01029 +28.1189,-0.01118 +28.1836,-0.01128 +28.2482,-0.01345 +28.3129,-0.01459 +28.3775,-0.01464 +28.4421,-0.01454 +28.5068,-0.01558 +28.5714,-0.01563 +28.6361,-0.01568 +28.7007,-0.01726 +28.7654,-0.01736 +28.8300,-0.01751 +28.8946,-0.01949 +28.9593,-0.01949 +29.0239,-0.01919 +29.0886,-0.01919 +29.1532,-0.02028 +29.2178,-0.02132 +29.2825,-0.02127 +29.3471,-0.02117 +29.4118,-0.02117 +29.4764,-0.02122 +29.5410,-0.02147 +29.6057,-0.02147 +29.6703,-0.02374 +29.7350,-0.02280 +29.7996,-0.02280 +29.8643,-0.02290 +29.9289,-0.02325 +29.9935,-0.02468 +30.0582,-0.02483 +30.1228,-0.02528 +30.1875,-0.02587 +30.2521,-0.02582 +30.3167,-0.02538 +30.3814,-0.02528 +30.4460,-0.02538 +30.5107,-0.02582 +30.5753,-0.02627 +30.6399,-0.02671 +30.7046,-0.02681 +30.7692,-0.03997 +30.8339,-0.04002 +30.8985,-0.04007 +30.9632,-0.02547 +31.0278,-0.02547 +31.0924,-0.02552 +31.1571,-0.02478 +31.2217,-0.02473 +31.2864,-0.04031 +31.3510,-0.04046 +31.4156,-0.04071 +31.4803,-0.02686 +31.5449,-0.04081 +31.6096,-0.04091 +31.6742,-0.04086 +31.7388,-0.04096 +31.8035,-0.04091 +31.8681,-0.04086 +31.9328,-0.02904 +31.9974,-0.02904 +32.0621,-0.02904 +32.1267,-0.02899 +32.1913,-0.02735 +32.2560,-0.02661 +32.3206,-0.02320 +32.3853,-0.02300 +32.4499,-0.02305 +32.5145,-0.02335 +32.5792,-0.02330 +32.6438,-0.02310 +32.7085,-0.02275 +32.7731,-0.03937 +32.8378,-0.03937 +32.9024,-0.02261 +32.9670,-0.02290 +33.0317,-0.02295 +33.0963,-0.02280 +33.1610,-0.02275 +33.2256,-0.02236 +33.2902,-0.02112 +33.3549,-0.02107 +33.4195,-0.02102 +33.4842,-0.02063 +33.5488,-0.02008 +33.6134,-0.01949 +33.6781,-0.01929 +33.7427,-0.01919 +33.8074,-0.01835 +33.8720,-0.01805 +33.9367,-0.01746 +34.0013,-0.01647 +34.0659,-0.03279 +34.1306,-0.01697 +34.1952,-0.01697 +34.2599,-0.01697 +34.3245,-0.01682 +34.3891,-0.01667 +34.4538,-0.01637 +34.5184,-0.01420 +34.5831,-0.01395 +34.6477,-0.01266 +34.7123,-0.01266 +34.7770,-0.01242 +34.8416,-0.01227 +34.9063,-0.01232 +34.9709,-0.01222 +35.0356,-0.01207 +35.1002,-0.01197 +35.1648,-0.01063 +35.2295,-0.01039 +35.2941,-0.01039 +35.3588,-0.00930 +35.4234,-0.00935 +35.4880,-0.00940 +35.5527,-0.00861 +35.6173,-0.00816 +35.6820,-0.00811 +35.7466,-0.00801 +35.8112,-0.00722 +35.8759,-0.00722 +35.9405,-0.00594 +36.0052,-0.00589 +36.0698,-0.00589 +36.1345,-0.00529 +36.1991,-0.00534 +36.2637,-0.00539 +36.3284,-0.00559 +36.3930,-0.00559 +36.4577,-0.00554 +36.5223,-0.00524 +36.5869,-0.00514 +36.6516,-0.00509 +36.7162,-0.00500 +36.7809,-0.00480 +36.8455,-0.00475 +36.9101,-0.00470 +36.9748,-0.00450 +37.0394,-0.00544 +37.1041,-0.00500 +37.1687,-0.00485 +37.2334,-0.00440 +37.2980,-0.00420 +37.3626,-0.00376 +37.4273,-0.00371 +37.4919,-0.00356 +37.5566,-0.00346 +37.6212,-0.00326 +37.6858,-0.00317 +37.7505,-0.00307 +37.8151,-0.00297 +37.8798,-0.00307 +37.9444,-0.00307 +38.0090,-0.00307 +38.0737,-0.00302 +38.1383,-0.00307 +38.2030,-0.00312 +38.2676,-0.00336 +38.3323,-0.00346 +38.3969,-0.00351 +38.4615,-0.00346 +38.5262,-0.00326 +38.5908,-0.00336 +38.6555,-0.00341 +38.7201,-0.00361 +38.7847,-0.00346 +38.8494,-0.00351 +38.9140,-0.00361 +38.9787,-0.00366 +39.0433,-0.00371 +39.1080,-0.00391 +39.1726,-0.00401 +39.2372,-0.00406 +39.3019,-0.00831 +39.3665,-0.00836 +39.4312,-0.00846 +39.4958,-0.00851 +39.5604,-0.00856 +39.6251,-0.00861 +39.6897,-0.00880 +39.7544,-0.00885 +39.8190,-0.00841 +39.8836,-0.00861 +39.9483,-0.00866 +40.0129,-0.00871 +40.0776,-0.00871 +40.1422,-0.00880 +40.2069,-0.00890 +40.2715,-0.00900 +40.3361,-0.00900 +40.4008,-0.00895 +40.4654,-0.00737 +40.5301,-0.00732 +40.5947,-0.00707 +40.6593,-0.01034 +40.7240,-0.01316 +40.7886,-0.01237 +40.8533,-0.01336 +40.9179,-0.01350 +40.9825,-0.01350 +41.0472,-0.01340 +41.1118,-0.01340 +41.1765,-0.01355 +41.2411,-0.01449 +41.3058,-0.01449 +41.3704,-0.01464 +41.4350,-0.01469 +41.4997,-0.01474 +41.5643,-0.01538 +41.6290,-0.01622 +41.6936,-0.01627 +41.7582,-0.01746 +41.8229,-0.01716 +41.8875,-0.01736 +41.9522,-0.01914 +42.0168,-0.01969 +42.0814,-0.01969 +42.1461,-0.01969 +42.2107,-0.01707 +42.2754,-0.01702 +42.3400,-0.01702 +42.4047,-0.01984 +42.4693,-0.01924 +42.5339,-0.01929 +42.5986,-0.01914 +42.6632,-0.01894 +42.7279,-0.01771 +42.7925,-0.01771 +42.8571,-0.01687 +42.9218,-0.02132 +42.9864,-0.02127 +43.0511,-0.01909 +43.1157,-0.01988 +43.1803,-0.01998 +43.2450,-0.02008 +43.3096,-0.02018 +43.3743,-0.02077 +43.4389,-0.02082 +43.5036,-0.02082 +43.5682,-0.02073 +43.6328,-0.02073 +43.6975,-0.02107 +43.7621,-0.02117 +43.8268,-0.02117 +43.8914,-0.02127 +43.9560,-0.02092 +44.0207,-0.02092 +44.0853,-0.02077 +44.1500,-0.02048 +44.2146,-0.02048 +44.2793,-0.02048 +44.3439,-0.02092 +44.4085,-0.02097 +44.4732,-0.02429 +44.5378,-0.02434 +44.6025,-0.02419 +44.6671,-0.02419 +44.7317,-0.02181 +44.7964,-0.02181 +44.8610,-0.02216 +44.9257,-0.02226 +44.9903,-0.02226 +45.0549,-0.02221 +45.1196,-0.02216 +45.1842,-0.02231 +45.2489,-0.02280 +45.3135,-0.02305 +45.3782,-0.02389 +45.4428,-0.02389 +45.5074,-0.02369 +45.5721,-0.02379 +45.6367,-0.02384 +45.7014,-0.02350 +45.7660,-0.02330 +45.8306,-0.02320 +45.8953,-0.02315 +45.9599,-0.02325 +46.0246,-0.02359 +46.0892,-0.02364 +46.1538,-0.02458 +46.2185,-0.02483 +46.2831,-0.02513 +46.3478,-0.02567 +46.4124,-0.02582 +46.4771,-0.02597 +46.5417,-0.02597 +46.6063,-0.02592 +46.6710,-0.02592 +46.7356,-0.02597 +46.8003,-0.02547 +46.8649,-0.02552 +46.9295,-0.02552 +46.9942,-0.02656 +47.0588,-0.02849 +47.1235,-0.02839 +47.1881,-0.02735 +47.2527,-0.02740 +47.3174,-0.02745 +47.3820,-0.02607 +47.4467,-0.02597 +47.5113,-0.02542 +47.5760,-0.02542 +47.6406,-0.02641 +47.7052,-0.02770 +47.7699,-0.02775 +47.8345,-0.02671 +47.8992,-0.02651 +47.9638,-0.02636 +48.0284,-0.02631 +48.0931,-0.02636 +48.1577,-0.02646 +48.2224,-0.02676 +48.2870,-0.02676 +48.3516,-0.02701 +48.4163,-0.02686 +48.4809,-0.02533 +48.5456,-0.02587 +48.6102,-0.02587 +48.6749,-0.02953 +48.7395,-0.03022 +48.8041,-0.03047 +48.8688,-0.03062 +48.9334,-0.03062 +48.9981,-0.03067 +49.0627,-0.03067 +49.1273,-0.03067 +49.1920,-0.03096 +49.2566,-0.03096 +49.3213,-0.03087 +49.3859,-0.03052 +49.4505,-0.03032 +49.5152,-0.03002 +49.5798,-0.03002 +49.6445,-0.03181 +49.7091,-0.03185 diff --git a/docs/figures/decks/negative_pressure/negative_pressure.inp b/docs/figures/decks/negative_pressure/negative_pressure.inp new file mode 100644 index 000000000..02e7016ae --- /dev/null +++ b/docs/figures/decks/negative_pressure/negative_pressure.inp @@ -0,0 +1,89 @@ +[TITLE] +E3 - Vasconcelos et al. (2006) negative piezometric pressure (siphon) experiment. Issue #156. +Same pipeline as E2 with the center raised 0.15 m: first half +2.0% (upstream to center), +second half -2.0%. Both ends at elev 0. System filled to 0.30 m at the fill box, at rest +(fully pressurized: center crown 0.244 < 0.30). Sudden siphon withdrawal 0.45 L/s at the +fill box from t=0. Negative gauge pressure develops at the center as the fill-box level +drops. Comparison valid to t~40 s (air-cavity intrusion afterwards - two-phase, out of scope); +END_TIME is set AT that boundary: past it the TPA column separates and the regime chatter +of a physics the model does not contain (two-phase air transport) ends the run (P5). +Measured: velocity + pressure at x=9.9 m, pressure at x=14.1 m. Paper: a=300 m/s (measured). +STATIONS ARE SEALED JUNCTIONS (SUR_DEPTH 30, P5 revision): a plain junction would be an +atmosphere contact and would (correctly, but wrongly for this deck) vent a TPA latch, but a +SEALED junction (SUR_DEPTH > 0) holds it -- same classification as a virtual junction in +both routers. Virtual junctions cannot carry an initial depth, and under FV that left the +two VJ-to-VJ conduits (C2, C3) seeded EMPTY on a deck whose whole premise is a primed +column: the slot columns spent the first seconds refilling garbage and the TPA columns +diverged outright (P5 measurement). InitDepth on each sealed junction seeds every conduit +full, which is the state the paper starts from. +EXPECTED PHYSICAL CONTRAST: slot-closure columns (C1/C2/C7) revert to free surface when head +drops below crown; TPA columns hold full-pipe sub-atmospheric flow (plan gate A-G4 analog). + +[OPTIONS] +FLOW_UNITS LPS +FLOW_ROUTING FV +LINK_OFFSETS DEPTH +START_DATE 01/01/2026 +START_TIME 00:00:00 +END_DATE 01/01/2026 +END_TIME 00:00:40 +REPORT_STEP 0.02 +ROUTING_STEP 0.01 +MIN_SURFAREA 0.05 +SURCHARGE_METHOD EXTRAN +INERTIAL_DAMPING NONE +NORMAL_FLOW_LIMITED NEITHER +FV_CELL_LENGTH 0.036 +FV_MIN_CELLS 4 +FV_SLOT_CELERITY 300 +FV_PRESSURE_CLOSURE TPA ;; docs copy: the static slot cannot represent this deck's + ;; sub-atmospheric full-pipe flow and diverges (ERROR 14) +REPORT_SIGNED_HEADS YES + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape A1/Curve A2 A0 SurDepth Fevap +FB 0.0 0.31 0.30 FUNCTIONAL 0 0 0.0625 0 0 +ST 0.0 1.50 0.30 FUNCTIONAL 0 0 0.02835 0 0 + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth +VJC 0.1433 1.0 0.1567 30 +VJ99 0.0886 1.0 0.2114 30 +VJ141 0.0046 1.0 0.2954 30 + +; Rim-overflow path: the surge tank is open-topped (rim at 1.50 m). The weir crest +; sits AT the rim (= ST MaxDepth), so it is transparent to the solution (levels only +; drop in this withdrawal experiment); it exists because the engine (legacy ERROR 145 +; parity) requires >= 1 outfall node. +[OUTFALLS] +;;Name Elev Type StageData Gated +DN 0.0 FREE NO + +[WEIRS] +;;Name From To Type CrestHt Cd Gated EC +OVF ST DN TRANSVERSE 1.50 1.84 NO 0 + +[CONDUITS] +;;Name From To Length N Zin Zout Q0 +C1 FB VJC 7.165 0.012 0 0 0 +C2 VJC VJ99 2.735 0.012 0 0 0 +C3 VJ99 VJ141 4.20 0.012 0 0 0 +C4 VJ141 ST 0.23 0.012 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +C1 CIRCULAR 0.094 0 0 0 1 +C2 CIRCULAR 0.094 0 0 0 1 +C3 CIRCULAR 0.094 0 0 0 1 +C4 CIRCULAR 0.094 0 0 0 1 +OVF RECT_OPEN 0.10 0.19 0 0 + +[INFLOWS] +;;Node Constituent Tseries Type Mfactor Sfactor Baseline +FB FLOW "" FLOW 1.0 1.0 -0.45 + +[REPORT] +CONTINUITY YES +FLOWSTATS YES +NODES ALL +LINKS ALL diff --git a/docs/figures/decks/negative_pressure/provenance.md b/docs/figures/decks/negative_pressure/provenance.md new file mode 100644 index 000000000..d4ea319b7 --- /dev/null +++ b/docs/figures/decks/negative_pressure/provenance.md @@ -0,0 +1,59 @@ +# negative_pressure — Vasconcelos, Wright and Roe (2006) siphon experiment + +| | | +|---|---| +| Deck | `negative_pressure.inp` | +| Copied from | `studies/mixed_flow_closures/decks/e3_negative_pressure.inp` (untracked study folder), 2026-09-20 | +| Study plan | `plans/MIXED_FLOW_CLOSURES_TPA_UF_PLAN_2026-08-29.md`, experiment e3; engine issue #156 | +| Used by | the Application Manual's sub-atmospheric chapter; figures `workflow_ch3_negative_pressure_head_14p1`, `workflow_ch3_velocity_9p9` | +| Changed on copy | one line added: `FV_PRESSURE_CLOSURE TPA` (see below) | + +## The one change from the study deck + +The study deck leaves `FV_PRESSURE_CLOSURE` at its default, the static +slot, because the study's runner sets the closure per matrix column. Run +as committed that deck diverges with ERROR 14 in the first substeps — +which is the very result the chapter reports — and the manual's deck gate +requires every committed deck to run clean. The docs copy therefore names +the closure this physics needs, `TPA`, and the chapter's figures set the +closure explicitly for each of their four runs, including the slot run +that fails. + +## The experiment + +The pipeline of `rapid_fill` with its centre raised 0.15 m — 2 % up to the +centre, 2 % down from it — both ends at elevation zero. The system starts +full and at rest, filled to 0.30 m at the fill box, which puts the crown at +the centre (0.244 m) under water. At t = 0 a siphon withdrawal of 0.45 L/s +starts at the fill box, the fill-box level falls, and the piezometric +pressure at the centre goes **negative**. + +That is the discriminator this deck exists for. A Preissmann slot cannot +represent sub-atmospheric pressure in a full pipe: the slot is open to the +atmosphere, so the water surface it invents simply drops into the pipe. The +two-component pressure approach carries a pressurized cell's pressure as a +second component and can take it below zero. + +The comparison is valid to about t = 40 s. After that an air cavity intrudes +— two-phase flow the model does not contain — so `END_TIME` is set at that +boundary rather than past it. + +The gauge stations are **sealed junctions** (`SUR_DEPTH 30`) rather than +virtual junctions: a plain junction is an atmosphere contact and would vent +the pressurized latch, correctly for a manhole and wrongly for a transducer +tapping on a sealed pipeline. + +## Observed data + +| File | Quantity | Station | +|---|---|---| +| `e3_pressure_14p1.csv` | pressure head, m gauge | x = 14.1 m | +| `e3_velocity_9p9.csv` | velocity, m/s | x = 9.9 m | + +Digitised from the published figures; each file's header records the source +figure and any datum shift. The paper's measured acoustic celerity for this +pipeline is a = 300 m/s. + +Vasconcelos, J. G., Wright, S. J. and Roe, P. L. (2006). Improved simulation +of flow regime transition in sewers: the two-component pressure approach. +*Journal of Hydraulic Engineering* 132(6), 553–562. diff --git a/docs/figures/decks/rapid_fill/e2_pressure_9p9.csv b/docs/figures/decks/rapid_fill/e2_pressure_9p9.csv new file mode 100644 index 000000000..2ae84cdb5 --- /dev/null +++ b/docs/figures/decks/rapid_fill/e2_pressure_9p9.csv @@ -0,0 +1,752 @@ +# source: Vasconcelos, Wright and Roe (2006) Fig. 3 -- raster image vasconcelos2006_p06_Im3.tiff extracted from the +# publisher PDF at native resolution (see results/_p6/figures_native/). +# quantity: pressure head (m) at x = 9.9 m, SI. time zero = the event. +# note: figure ordinate is pressure head VARIATION; +0.073 m (the initial water level, paper p. 557) is added here so the CSV is gauge head at the transducer, which is what matrix.yaml datum 0.0 compares to +# x calibration (px -> s): 117.5 -> 0.0 885.0 -> 15.0 (axis box = axis limits) +# y calibration (px -> val): 18.0 -> 0.4 634.5 -> 0.0 (axis box = axis limits) +# open model markers removed by hole-filling; per-column longest ink run. +# digitized 2026-08-31 by scripts/digitize/vasconcelos_bilevel.py fig3_e2_p99 +time_s,head_m +0.0489,0.07722 +0.0684,0.07689 +0.0879,0.07657 +0.1075,0.07592 +0.1270,0.07560 +0.1466,0.07560 +0.1661,0.07560 +0.1857,0.07560 +0.2052,0.07560 +0.2443,0.07527 +0.2638,0.07592 +0.2834,0.07560 +0.3029,0.07527 +0.3225,0.07527 +0.3420,0.07560 +0.3616,0.07560 +0.4007,0.07560 +0.4202,0.07560 +0.4397,0.07560 +0.4788,0.07527 +0.4984,0.07592 +0.5179,0.07560 +0.5375,0.07560 +0.5570,0.07560 +0.5765,0.07560 +0.5961,0.07560 +0.6156,0.07527 +0.6352,0.07560 +0.6547,0.07560 +0.6743,0.07592 +0.6938,0.07527 +0.7134,0.07527 +0.7329,0.07592 +0.7524,0.07592 +0.7720,0.07624 +0.7915,0.08079 +0.8111,0.08079 +0.8306,0.08079 +0.8502,0.07884 +0.8697,0.07916 +0.8893,0.07949 +0.9088,0.07852 +0.9283,0.07852 +0.9479,0.07884 +0.9674,0.07884 +0.9870,0.07916 +1.0065,0.07949 +1.0261,0.07819 +1.0456,0.07722 +1.0651,0.07689 +1.0847,0.07657 +1.1042,0.07624 +1.1238,0.07657 +1.1433,0.07657 +1.1629,0.07657 +1.1824,0.07689 +1.2020,0.07852 +1.2215,0.07884 +1.2410,0.07884 +1.2606,0.07884 +1.2801,0.07819 +1.2997,0.07722 +1.3192,0.07689 +1.3388,0.07689 +1.3583,0.07689 +1.3779,0.07722 +1.3974,0.07754 +1.4169,0.07819 +1.4365,0.07884 +1.4560,0.07852 +1.4756,0.07819 +1.4951,0.07722 +1.5147,0.07722 +1.5342,0.07689 +1.5537,0.07657 +1.5733,0.07657 +1.5928,0.07722 +1.6124,0.07852 +1.6319,0.07884 +1.6515,0.07884 +1.6710,0.07852 +1.6906,0.07787 +1.7101,0.07722 +1.7296,0.07657 +1.7492,0.07657 +1.7687,0.07657 +1.7883,0.07657 +1.8078,0.07689 +1.8274,0.07689 +1.8469,0.07754 +1.8664,0.07852 +1.8860,0.07884 +1.9055,0.07884 +1.9251,0.07819 +1.9446,0.07754 +1.9642,0.07722 +1.9837,0.07657 +2.0033,0.07657 +2.0228,0.07689 +2.0423,0.07722 +2.0619,0.07787 +2.0814,0.07852 +2.1010,0.07884 +2.1205,0.07852 +2.1401,0.07819 +2.1596,0.07722 +2.1792,0.07689 +2.1987,0.07657 +2.2182,0.07689 +2.2378,0.07689 +2.2573,0.07722 +2.2769,0.07819 +2.2964,0.07884 +2.3160,0.07884 +2.3355,0.07819 +2.3550,0.07722 +2.3746,0.07722 +2.3941,0.07689 +2.4137,0.07624 +2.4332,0.07624 +2.4528,0.07657 +2.4723,0.07689 +2.4919,0.07722 +2.5114,0.07787 +2.5309,0.07852 +2.5505,0.07852 +2.5700,0.07852 +2.5896,0.07787 +2.6091,0.07754 +2.6287,0.07689 +2.6482,0.07657 +2.6678,0.07657 +2.6873,0.07689 +2.7068,0.07689 +2.7264,0.07787 +2.7459,0.07819 +2.7655,0.07884 +2.7850,0.07852 +2.8046,0.07787 +2.8241,0.07722 +2.8436,0.07689 +2.8632,0.07657 +2.8827,0.07657 +2.9023,0.07624 +2.9218,0.07689 +2.9414,0.07689 +2.9609,0.07722 +2.9805,0.07787 +3.0000,0.07852 +3.0195,0.07884 +3.0391,0.07819 +3.0586,0.07754 +3.0782,0.07689 +3.0977,0.07657 +3.1173,0.07657 +3.1368,0.07689 +3.1564,0.07722 +3.1759,0.07754 +3.1954,0.07852 +3.2150,0.07884 +3.2345,0.07852 +3.2541,0.07787 +3.2736,0.07689 +3.2932,0.07689 +3.3127,0.07624 +3.3322,0.07689 +3.3518,0.07689 +3.3713,0.07722 +3.3909,0.07787 +3.4104,0.07852 +3.4300,0.07852 +3.4495,0.07787 +3.4691,0.07754 +3.4886,0.07689 +3.5081,0.07689 +3.5277,0.07689 +3.5472,0.07624 +3.5668,0.07624 +3.5863,0.07657 +3.6059,0.07722 +3.6254,0.07754 +3.6450,0.07787 +3.6645,0.07852 +3.6840,0.07852 +3.7036,0.07787 +3.7231,0.07722 +3.7427,0.07689 +3.7622,0.07657 +3.7818,0.07722 +3.8013,0.07722 +3.8208,0.07689 +3.8404,0.07819 +3.8599,0.07819 +3.8795,0.07884 +3.8990,0.07852 +3.9186,0.07754 +3.9381,0.07754 +3.9577,0.07722 +3.9772,0.07689 +3.9967,0.07657 +4.0163,0.07689 +4.0358,0.07754 +4.0554,0.07819 +4.0749,0.07884 +4.0945,0.07852 +4.1140,0.07787 +4.1336,0.07722 +4.1531,0.07689 +4.1726,0.07722 +4.1922,0.07722 +4.2117,0.07689 +4.2313,0.07689 +4.2508,0.07722 +4.2704,0.07722 +4.2899,0.07722 +4.3094,0.07852 +4.3290,0.07852 +4.3485,0.07819 +4.3681,0.07754 +4.3876,0.07722 +4.4072,0.07722 +4.4267,0.07722 +4.4463,0.07722 +4.4658,0.07689 +4.4853,0.07722 +4.5049,0.07722 +4.5244,0.07852 +4.5440,0.07852 +4.5635,0.07852 +4.5831,0.07754 +4.6026,0.07722 +4.6221,0.07689 +4.6417,0.07722 +4.6612,0.07722 +4.6808,0.07722 +4.7003,0.07787 +4.7199,0.07787 +4.7394,0.07819 +4.7590,0.07819 +4.7785,0.07787 +4.7980,0.07722 +4.8176,0.07722 +4.8371,0.07722 +4.8567,0.07689 +4.8762,0.07689 +4.8958,0.07722 +4.9153,0.07722 +4.9349,0.07689 +4.9544,0.07722 +4.9739,0.07787 +4.9935,0.07884 +5.0130,0.07852 +5.0326,0.07754 +5.0521,0.07754 +5.0717,0.07722 +5.0912,0.07689 +5.1107,0.07722 +5.1303,0.07722 +5.1498,0.07722 +5.1694,0.07819 +5.1889,0.07819 +5.2085,0.07884 +5.2280,0.07722 +5.2476,0.07722 +5.2671,0.07689 +5.2866,0.07689 +5.3062,0.07689 +5.3257,0.07689 +5.3453,0.07722 +5.3648,0.07722 +5.3844,0.07819 +5.4039,0.07884 +5.4235,0.07852 +5.4430,0.07754 +5.4625,0.07722 +5.4821,0.07722 +5.5016,0.07689 +5.5212,0.07722 +5.5407,0.07722 +5.5603,0.07689 +5.5798,0.07689 +5.5993,0.07722 +5.6189,0.07787 +5.6384,0.07819 +5.6580,0.07852 +5.6775,0.07787 +5.6971,0.07754 +5.7166,0.07722 +5.7362,0.07689 +5.7557,0.07689 +5.7752,0.07689 +5.7948,0.07689 +5.8143,0.07722 +5.8339,0.07819 +5.8534,0.07852 +5.8730,0.07819 +5.8925,0.07722 +5.9121,0.07722 +5.9316,0.07722 +5.9511,0.07689 +5.9707,0.07722 +5.9902,0.07722 +6.0098,0.07722 +6.0293,0.07852 +6.0489,0.07852 +6.0684,0.07852 +6.0879,0.07754 +6.1075,0.07722 +6.1270,0.07787 +6.1466,0.07852 +6.1661,0.07852 +6.1857,0.08046 +6.2052,0.08598 +6.2248,0.08630 +6.2443,0.08727 +6.2638,0.10025 +6.2834,0.10058 +6.3029,0.11647 +6.3225,0.11744 +6.3420,0.12555 +6.3616,0.12750 +6.3811,0.13010 +6.4007,0.12977 +6.4202,0.13139 +6.4397,0.13107 +6.4593,0.13172 +6.4788,0.13204 +6.4984,0.13204 +6.5179,0.13204 +6.5375,0.13204 +6.5570,0.13237 +6.5765,0.13399 +6.5961,0.13204 +6.6156,0.13950 +6.6352,0.13950 +6.6547,0.13950 +6.6743,0.14924 +6.6938,0.15021 +6.7134,0.13950 +6.7329,0.12685 +6.7524,0.12653 +6.7720,0.14048 +6.7915,0.14048 +6.8111,0.14048 +6.8306,0.14015 +6.8502,0.14048 +6.8697,0.13983 +6.8893,0.13950 +6.9088,0.13821 +6.9283,0.13756 +6.9479,0.13821 +6.9674,0.13821 +6.9870,0.13756 +7.0065,0.13756 +7.0456,0.21282 +7.0651,0.21282 +7.1238,0.14145 +7.1433,0.14242 +7.1629,0.14275 +7.1824,0.14275 +7.2020,0.14275 +7.2215,0.14242 +7.2410,0.14242 +7.3192,0.14534 +7.3388,0.14567 +7.3583,0.14567 +7.3779,0.14567 +7.3974,0.14502 +7.4169,0.14502 +7.4365,0.14437 +7.4560,0.14470 +7.4756,0.13107 +7.5537,0.07527 +7.5928,0.13496 +7.6124,0.14826 +7.6319,0.14826 +7.6515,0.14826 +7.6710,0.13496 +7.7101,0.07527 +7.7296,0.15573 +7.7492,0.15573 +7.7687,0.15573 +7.7883,0.15605 +7.8078,0.15410 +7.8274,0.15410 +7.8469,0.15410 +7.8664,0.15378 +7.9055,0.15410 +7.9251,0.15443 +7.9837,0.16027 +8.0033,0.14632 +8.0228,0.16124 +8.0423,0.16189 +8.0619,0.17259 +8.0814,0.16286 +8.1010,0.16513 +8.1205,0.16513 +8.1401,0.16546 +8.1596,0.16513 +8.1792,0.16448 +8.1987,0.16416 +8.2182,0.16416 +8.2378,0.16448 +8.2573,0.16384 +8.2769,0.17519 +8.2964,0.17519 +8.3160,0.17487 +8.3355,0.17487 +8.3550,0.19206 +8.3746,0.24234 +8.3941,0.26959 +8.4137,0.26927 +8.4332,0.26278 +8.4528,0.19141 +8.4723,0.19141 +8.4919,0.13302 +8.5114,0.18719 +8.5309,0.18168 +8.5505,0.18168 +8.5700,0.12977 +8.5896,0.17097 +8.6091,0.17097 +8.6287,0.17097 +8.6482,0.17097 +8.6678,0.16773 +8.6873,0.17032 +8.7068,0.17227 +8.7264,0.19757 +8.7459,0.18460 +8.7655,0.19595 +8.7850,0.20147 +8.8046,0.19757 +8.8241,0.20082 +8.8436,0.19887 +8.8632,0.19920 +8.8827,0.20374 +8.9023,0.20439 +8.9218,0.20568 +8.9414,0.20439 +8.9609,0.20471 +8.9805,0.20471 +9.0000,0.20828 +9.0195,0.20828 +9.0391,0.20860 +9.0586,0.20925 +9.0782,0.20925 +9.0977,0.20374 +9.1173,0.20828 +9.1368,0.20990 +9.1564,0.20990 +9.1759,0.21055 +9.1954,0.21217 +9.2150,0.21477 +9.2345,0.21542 +9.2541,0.21639 +9.2736,0.21736 +9.2932,0.21704 +9.3127,0.21834 +9.3322,0.21834 +9.3518,0.22126 +9.3713,0.22191 +9.3909,0.22288 +9.4104,0.22385 +9.4300,0.22385 +9.4495,0.22385 +9.4691,0.22515 +9.4886,0.22515 +9.5081,0.22515 +9.5277,0.22580 +9.5472,0.22710 +9.5668,0.23066 +9.5863,0.23099 +9.6059,0.23099 +9.6254,0.23261 +9.6450,0.23391 +9.6645,0.23391 +9.6840,0.23423 +9.7036,0.23715 +9.7231,0.23780 +9.7427,0.23813 +9.7622,0.23813 +9.7818,0.23877 +9.8013,0.24397 +9.8208,0.24494 +9.8404,0.24526 +9.8599,0.24688 +9.8795,0.24656 +9.8990,0.24656 +9.9186,0.24656 +9.9381,0.24753 +9.9577,0.24753 +9.9772,0.25143 +9.9967,0.25175 +10.0163,0.25208 +10.0358,0.25208 +10.0554,0.25143 +10.0749,0.25143 +10.0945,0.25402 +10.1140,0.25629 +10.1336,0.25662 +10.1531,0.25824 +10.1726,0.25791 +10.1922,0.25727 +10.2117,0.25662 +10.2313,0.25824 +10.2508,0.25856 +10.2704,0.25921 +10.2899,0.26051 +10.3094,0.26181 +10.3290,0.26343 +10.3485,0.26570 +10.3681,0.26603 +10.3876,0.26700 +10.4072,0.26570 +10.4267,0.26667 +10.4463,0.26992 +10.4658,0.27024 +10.4853,0.27349 +10.5049,0.27316 +10.5244,0.27349 +10.5440,0.27511 +10.5635,0.27511 +10.5831,0.27641 +10.6026,0.28095 +10.6221,0.26959 +10.6417,0.26959 +10.6612,0.27933 +10.6808,0.28095 +10.7003,0.28095 +10.7199,0.28160 +10.7394,0.28225 +10.7590,0.28289 +10.7785,0.28452 +10.7980,0.28549 +10.8176,0.28581 +10.8371,0.28646 +10.8567,0.28809 +10.8762,0.28841 +10.8958,0.29003 +10.9153,0.29068 +10.9349,0.29100 +10.9544,0.29133 +10.9739,0.29165 +10.9935,0.29133 +11.0130,0.29133 +11.0326,0.29198 +11.0521,0.29490 +11.0717,0.29620 +11.0912,0.29684 +11.1107,0.29814 +11.1303,0.29782 +11.1498,0.29976 +11.1694,0.30009 +11.1889,0.30041 +11.2085,0.30074 +11.2280,0.30203 +11.2476,0.30301 +11.2671,0.30268 +11.2866,0.30366 +11.3062,0.30398 +11.3257,0.30690 +11.3453,0.30723 +11.3648,0.30723 +11.3844,0.30560 +11.4039,0.30625 +11.4235,0.30560 +11.4430,0.30625 +11.4625,0.30950 +11.4821,0.30950 +11.5016,0.31079 +11.5212,0.31177 +11.5407,0.31177 +11.5603,0.31209 +11.5798,0.31209 +11.5993,0.31469 +11.6189,0.31501 +11.6384,0.31631 +11.6580,0.31598 +11.6775,0.31598 +11.6971,0.31631 +11.7166,0.31728 +11.7362,0.31890 +11.7557,0.31890 +11.7752,0.31923 +11.7948,0.31955 +11.8143,0.31988 +11.8339,0.32182 +11.8534,0.32215 +11.8730,0.32312 +11.8925,0.32345 +11.9121,0.32312 +11.9316,0.32312 +11.9511,0.32637 +11.9707,0.32669 +11.9902,0.32604 +12.0098,0.32766 +12.0293,0.32766 +12.0489,0.32831 +12.0684,0.32864 +12.0879,0.32182 +12.1075,0.32182 +12.1270,0.32150 +12.1466,0.32215 +12.1857,0.33610 +12.2052,0.33642 +12.2248,0.33675 +12.2443,0.33675 +12.2638,0.33707 +12.2834,0.33707 +12.3029,0.33707 +12.3225,0.33740 +12.3420,0.33740 +12.3616,0.33740 +12.3811,0.33707 +12.4007,0.33675 +12.4202,0.33512 +12.4593,0.33156 +12.4788,0.33156 +12.4984,0.34291 +12.5179,0.34194 +12.5375,0.34161 +12.5570,0.34194 +12.5765,0.34194 +12.5961,0.33058 +12.6156,0.34291 +12.6352,0.33091 +12.6547,0.33123 +12.7329,0.33285 +12.7524,0.33383 +12.7720,0.33383 +12.7915,0.33350 +12.8111,0.33383 +12.8306,0.33285 +12.8502,0.34875 +12.8697,0.34875 +12.8893,0.34875 +12.9088,0.34875 +12.9283,0.34875 +12.9479,0.34875 +12.9674,0.35070 +12.9870,0.34713 +13.0065,0.34907 +13.0261,0.34972 +13.0456,0.34680 +13.0651,0.34810 +13.0847,0.34648 +13.1042,0.34648 +13.1238,0.35070 +13.1433,0.35037 +13.1629,0.35037 +13.1824,0.35070 +13.2020,0.35102 +13.2215,0.35362 +13.2410,0.35329 +13.2606,0.35199 +13.2801,0.35199 +13.2997,0.35362 +13.3192,0.35167 +13.3388,0.35199 +13.3583,0.35394 +13.3779,0.35427 +13.3974,0.35427 +13.4169,0.35394 +13.4365,0.35329 +13.4560,0.35297 +13.4756,0.35297 +13.4951,0.35329 +13.5147,0.36627 +13.5342,0.36594 +13.5537,0.35718 +13.5733,0.35718 +13.5928,0.35718 +13.6124,0.35686 +13.6319,0.35718 +13.6515,0.36043 +13.6710,0.36043 +13.6906,0.36010 +13.7101,0.35783 +13.7296,0.35816 +13.7492,0.35848 +13.7687,0.36043 +13.7883,0.36108 +13.8078,0.36173 +13.8274,0.36075 +13.8469,0.36043 +13.8664,0.36010 +13.8860,0.36010 +13.9055,0.36043 +13.9251,0.36108 +13.9446,0.36108 +13.9642,0.36173 +13.9837,0.36270 +14.0033,0.36238 +14.0228,0.36205 +14.0423,0.36205 +14.0619,0.36140 +14.0814,0.36140 +14.1010,0.36432 +14.1205,0.36432 +14.1401,0.36400 +14.1596,0.36367 +14.1792,0.36400 +14.1987,0.36400 +14.2182,0.36335 +14.2378,0.36367 +14.2573,0.36400 +14.2769,0.37016 +14.2964,0.36562 +14.3160,0.36562 +14.3355,0.36530 +14.3550,0.36562 +14.3746,0.36302 +14.3941,0.36562 +14.4137,0.36627 +14.4332,0.36627 +14.4528,0.36659 +14.4723,0.36659 +14.4919,0.36659 +14.5114,0.36627 +14.5309,0.36594 +14.5505,0.36627 +14.5700,0.36627 +14.5896,0.36627 +14.6091,0.36789 +14.6287,0.36919 +14.6482,0.36789 +14.6678,0.36724 +14.6873,0.36659 +14.7068,0.36659 +14.7264,0.36659 +14.7459,0.36789 +14.7655,0.36789 +14.7850,0.37016 +14.8046,0.36821 +14.8241,0.36789 +14.8436,0.36789 +14.8632,0.36821 +14.8827,0.36821 +14.9023,0.36919 +14.9218,0.38379 +14.9414,0.38379 +14.9609,0.37146 +14.9805,0.37081 diff --git a/docs/figures/decks/rapid_fill/e2_surgetank_level.csv b/docs/figures/decks/rapid_fill/e2_surgetank_level.csv new file mode 100644 index 000000000..0a89e9a60 --- /dev/null +++ b/docs/figures/decks/rapid_fill/e2_surgetank_level.csv @@ -0,0 +1,677 @@ +# source: Pinto et al. (2025) Fig. 7 -- raster image pinto2025_p06_Im7.png extracted from the +# publisher PDF at native resolution (see results/_p6/figures_native/). +# quantity: water level (m) in the surge tank, SI. time zero = the event (runner applies t_offset). +# series identified by grey level: experiment 150-195/255, model curves < 110/255. +# x calibration (px -> s): 97.5 -> 0.0 1012.5 -> 40.0 (tick marks) +# y calibration (px -> val): 606.5 -> 0.1 41.0 -> 0.4 (tick marks) +# per-column median of the experiment mask; inset, legend and zoom-box removed. +# digitized 2026-08-31 by scripts/digitize/pinto_grey.py fig7_e2_st +time_s,level_m +2.2077,0.07480 +2.2514,0.07480 +2.2951,0.07480 +2.3388,0.07480 +2.3825,0.07480 +2.4262,0.07480 +2.4699,0.07480 +2.5137,0.07480 +2.5574,0.07480 +2.6011,0.07480 +2.6448,0.07480 +2.6885,0.07507 +2.7322,0.07507 +2.7760,0.07507 +2.8197,0.07507 +2.8634,0.07507 +2.9071,0.07507 +2.9508,0.07507 +2.9945,0.07507 +3.0383,0.07507 +3.0820,0.07507 +3.1257,0.07507 +3.1694,0.07533 +3.2131,0.07533 +3.2568,0.07533 +3.3005,0.07533 +3.3443,0.07533 +3.3880,0.07533 +3.4317,0.07533 +3.4754,0.07533 +3.5191,0.07533 +3.5628,0.07533 +3.6066,0.07560 +3.6503,0.07560 +3.6940,0.07560 +3.7377,0.07586 +3.7814,0.07586 +3.8251,0.07586 +3.8689,0.07586 +3.9126,0.07586 +3.9563,0.07586 +4.0000,0.07586 +4.0437,0.07586 +4.0874,0.07586 +4.1311,0.07586 +4.1749,0.07586 +4.2186,0.07586 +4.2623,0.07560 +4.3060,0.07560 +4.3497,0.07560 +4.3934,0.07533 +4.4372,0.07533 +4.4809,0.07533 +4.5246,0.07533 +4.5683,0.07533 +4.6120,0.07533 +4.6557,0.07533 +4.6995,0.07533 +4.7432,0.07533 +4.7869,0.07533 +4.8306,0.07533 +4.8743,0.07507 +4.9180,0.07507 +4.9617,0.07507 +5.0055,0.07507 +5.0492,0.07507 +5.0929,0.07507 +5.1366,0.07507 +5.1803,0.07507 +5.2240,0.07507 +5.2678,0.07507 +5.3115,0.07507 +5.3552,0.07507 +5.3989,0.07507 +5.4426,0.07507 +5.4863,0.07507 +5.5301,0.07507 +5.5738,0.07480 +5.6175,0.07480 +5.6612,0.07480 +5.7049,0.07480 +5.7486,0.07480 +5.7923,0.07480 +5.8361,0.07480 +5.8798,0.07480 +5.9235,0.07480 +5.9672,0.07480 +6.0109,0.07480 +6.0546,0.07480 +6.0984,0.07480 +6.2732,0.07480 +6.3169,0.07480 +6.3607,0.07480 +6.4044,0.07480 +6.4481,0.07480 +6.4918,0.07480 +6.5355,0.07480 +6.5792,0.07480 +6.6230,0.07480 +6.7541,0.06605 +6.8852,0.07480 +6.9290,0.07480 +6.9727,0.07480 +7.0164,0.07480 +7.0601,0.07480 +7.1038,0.07480 +7.1475,0.07507 +7.1913,0.07507 +7.2350,0.07507 +7.2787,0.07507 +7.3224,0.07507 +7.3661,0.07507 +7.4098,0.07507 +7.4536,0.07507 +7.4973,0.07507 +7.5410,0.07507 +7.5847,0.07533 +7.6284,0.07533 +7.6721,0.07533 +7.7158,0.07507 +7.7596,0.07507 +7.8033,0.07507 +7.8470,0.07507 +7.8907,0.07507 +7.9344,0.07560 +7.9781,0.07851 +8.0219,0.08117 +8.0656,0.08408 +8.1093,0.08674 +8.1530,0.09072 +8.1967,0.09469 +8.2404,0.09867 +8.2842,0.10292 +8.3279,0.10690 +8.3716,0.11114 +8.4153,0.11485 +8.4590,0.11883 +8.5027,0.12308 +8.5464,0.12706 +8.5902,0.13130 +8.6339,0.13528 +8.6776,0.13952 +8.7213,0.14324 +8.7650,0.14721 +8.8087,0.15066 +8.8525,0.15411 +8.8962,0.15729 +8.9399,0.16074 +8.9836,0.16419 +9.0273,0.16764 +9.0710,0.17135 +9.1148,0.17480 +9.1585,0.17825 +9.2022,0.18170 +9.2459,0.18488 +9.2896,0.18833 +9.3333,0.19151 +9.3770,0.19496 +9.4208,0.19788 +9.4645,0.20133 +9.5082,0.20477 +9.5519,0.20769 +9.5956,0.21114 +9.6393,0.21432 +9.6831,0.21751 +9.7268,0.22069 +9.7705,0.22387 +9.8142,0.22706 +9.8579,0.22997 +9.9016,0.23316 +9.9454,0.23634 +9.9891,0.23926 +10.0328,0.24164 +10.0765,0.24430 +10.1202,0.24668 +10.1639,0.24960 +10.2077,0.25199 +10.2514,0.25438 +10.2951,0.25729 +10.3388,0.25968 +10.3825,0.26207 +10.4262,0.26472 +10.4699,0.26711 +10.5137,0.26950 +10.5574,0.27188 +10.6011,0.27427 +10.6448,0.27666 +10.6885,0.27931 +10.7322,0.28143 +10.7760,0.28382 +10.8197,0.28621 +10.8634,0.28329 +10.9071,0.28541 +10.9508,0.28329 +10.9945,0.29019 +11.0383,0.29231 +11.0820,0.29469 +11.1257,0.29708 +11.1694,0.30345 +11.2131,0.30557 +11.2568,0.30796 +11.3005,0.31008 +11.3443,0.31220 +11.3880,0.31538 +11.4317,0.31724 +11.4754,0.31910 +11.5191,0.32122 +11.5628,0.32281 +11.6066,0.32493 +11.6503,0.32679 +11.6940,0.32865 +11.7377,0.33050 +11.7814,0.33210 +11.8251,0.33395 +11.8689,0.33581 +11.9126,0.33767 +11.9563,0.33926 +12.0000,0.34005 +12.0437,0.34960 +12.0874,0.34430 +12.1311,0.34509 +12.1749,0.34562 +12.2186,0.35119 +12.2623,0.34881 +12.3060,0.35332 +12.3497,0.35729 +12.3934,0.35809 +12.4372,0.35915 +12.4809,0.36048 +12.5246,0.36313 +12.5683,0.36446 +12.6120,0.36525 +12.6557,0.36658 +12.6995,0.36790 +12.7432,0.36923 +12.7869,0.37056 +12.8306,0.37188 +12.8743,0.37294 +12.9180,0.37374 +12.9617,0.37480 +13.0055,0.37560 +13.0492,0.37666 +13.0929,0.37745 +13.1366,0.37851 +13.1803,0.37931 +13.2240,0.38037 +13.2678,0.38117 +13.3115,0.38223 +13.3552,0.38302 +13.3989,0.38408 +13.4426,0.38488 +13.4863,0.38594 +13.5301,0.38674 +13.5738,0.38780 +13.6175,0.38859 +13.6612,0.38939 +13.7049,0.39045 +13.7486,0.39151 +13.7923,0.39231 +13.8361,0.39310 +13.8798,0.39416 +13.9235,0.39496 +13.9672,0.39549 +14.0109,0.39602 +14.0546,0.39682 +14.0984,0.39735 +14.1421,0.39761 +14.1858,0.39814 +14.2295,0.39841 +14.2732,0.39894 +14.3169,0.39920 +14.3607,0.39947 +14.4044,0.40000 +14.4481,0.40027 +14.4918,0.40080 +14.5355,0.40106 +14.5792,0.40159 +14.6230,0.40186 +14.6667,0.40239 +14.7104,0.40265 +14.7541,0.40318 +14.7978,0.40345 +14.8415,0.40318 +14.8852,0.40292 +14.9290,0.40265 +14.9727,0.40212 +15.0164,0.40159 +15.0601,0.40106 +15.1038,0.40053 +15.1475,0.40000 +15.1913,0.39947 +15.2350,0.39947 +15.2787,0.39894 +15.3224,0.39841 +15.3661,0.39788 +15.4098,0.39735 +15.4536,0.39682 +15.4973,0.39629 +15.5410,0.39629 +15.5847,0.39576 +15.6284,0.39523 +15.6721,0.39469 +15.7158,0.39416 +15.7596,0.39363 +15.8033,0.39310 +15.8470,0.39284 +15.8907,0.39257 +15.9344,0.39204 +15.9781,0.39151 +16.0219,0.39098 +16.0656,0.39045 +16.1093,0.38992 +16.1530,0.38939 +16.1967,0.38939 +16.2404,0.38886 +16.2842,0.38833 +16.3279,0.38780 +16.3716,0.38727 +16.4153,0.38647 +16.4590,0.38568 +16.5027,0.38541 +16.5464,0.38435 +16.5902,0.38355 +16.6339,0.38276 +16.6776,0.38170 +16.7213,0.38117 +16.7650,0.38011 +16.8087,0.37931 +16.8525,0.37851 +16.8962,0.37772 +16.9399,0.37666 +16.9836,0.37613 +17.0273,0.37533 +17.0710,0.37427 +17.1148,0.37374 +17.1585,0.37268 +17.2022,0.37162 +17.2459,0.37082 +17.2896,0.37003 +17.3333,0.36897 +17.3770,0.36817 +17.4208,0.36737 +17.4645,0.36631 +17.5082,0.36525 +17.5519,0.36472 +17.5956,0.36366 +17.6393,0.36260 +17.6831,0.36180 +17.7268,0.36074 +17.7705,0.35968 +17.8142,0.35889 +17.8579,0.35809 +17.9016,0.35703 +17.9454,0.35623 +17.9891,0.35517 +18.0328,0.35411 +18.0765,0.35332 +18.1202,0.35225 +18.1639,0.35119 +18.2077,0.35013 +18.2514,0.34907 +18.2951,0.34801 +18.3388,0.34721 +18.3825,0.34615 +18.4262,0.34509 +18.4699,0.34403 +18.5137,0.34297 +18.5574,0.34191 +18.6011,0.34111 +18.6448,0.34005 +18.6885,0.33899 +18.7322,0.33793 +18.7760,0.33687 +18.8197,0.33581 +18.8634,0.33475 +18.9071,0.33369 +18.9508,0.33263 +18.9945,0.33156 +19.0383,0.33050 +19.0820,0.32944 +19.1257,0.32838 +19.1694,0.32759 +19.2131,0.32653 +19.2568,0.32546 +19.3005,0.32440 +19.3443,0.32334 +19.3880,0.32228 +19.4317,0.32149 +19.4754,0.32042 +19.5191,0.31936 +19.5628,0.31830 +19.6066,0.31751 +19.6503,0.31645 +19.6940,0.31565 +19.7377,0.31485 +19.7814,0.31379 +19.8251,0.31300 +19.8689,0.31194 +19.9126,0.31114 +19.9563,0.31008 +20.0000,0.30928 +20.0437,0.30849 +20.0874,0.30743 +20.1311,0.30663 +20.1749,0.30557 +20.2186,0.30477 +20.2623,0.30371 +20.3060,0.30292 +20.3497,0.30212 +20.3934,0.30106 +20.4372,0.30027 +20.4809,0.29947 +20.5246,0.29841 +20.5683,0.29761 +20.6120,0.29682 +20.6557,0.29602 +20.6995,0.29496 +20.7432,0.29443 +20.7869,0.29363 +20.8306,0.29284 +20.8743,0.29178 +20.9180,0.29125 +20.9617,0.29045 +21.0055,0.28966 +21.0492,0.28886 +21.0929,0.28806 +21.1366,0.28727 +21.1803,0.28647 +21.2240,0.28594 +21.4426,0.28329 +21.4863,0.28276 +21.5301,0.28249 +21.5738,0.28223 +21.6175,0.28170 +21.6612,0.28143 +21.7049,0.28117 +21.7486,0.28090 +21.7923,0.28090 +21.8361,0.28064 +21.8798,0.28037 +21.9235,0.28011 +21.9672,0.27984 +22.0109,0.27984 +22.0546,0.27958 +22.0984,0.27931 +22.1421,0.27905 +22.1858,0.27878 +22.2295,0.27878 +22.2732,0.27851 +22.3169,0.27825 +22.3607,0.27798 +22.4044,0.27772 +22.4481,0.27772 +22.4918,0.27745 +22.5355,0.27719 +22.5792,0.27692 +22.6230,0.27666 +22.6667,0.27666 +22.7104,0.27639 +22.7541,0.27613 +22.7978,0.27586 +22.8415,0.27586 +22.8852,0.27586 +22.9290,0.27560 +22.9727,0.27560 +23.0164,0.27586 +23.0601,0.27586 +23.1038,0.27613 +23.1475,0.27639 +23.1913,0.27666 +23.2350,0.27666 +23.2787,0.27692 +23.3224,0.27692 +23.3661,0.27719 +23.4098,0.27745 +23.4536,0.27851 +23.7158,0.28011 +23.7596,0.27931 +23.8033,0.27905 +24.1093,0.28196 +24.1530,0.28196 +24.1967,0.28249 +24.2404,0.28276 +24.2842,0.28329 +24.3279,0.28329 +24.3716,0.28382 +24.9399,0.28541 +24.9836,0.28594 +25.0273,0.28621 +25.0710,0.28674 +25.1148,0.28700 +25.1585,0.28753 +25.2022,0.28833 +25.2459,0.28886 +25.2896,0.28939 +25.3333,0.29045 +25.3770,0.29098 +25.4208,0.29151 +25.4645,0.29204 +25.5082,0.29284 +25.5519,0.29337 +25.5956,0.29390 +25.6393,0.29443 +25.6831,0.29549 +25.7268,0.29602 +25.7705,0.29655 +25.8142,0.29708 +25.9454,0.29920 +25.9891,0.29973 +27.4317,0.32520 +27.4754,0.32573 +27.5191,0.32626 +27.6503,0.32838 +27.6940,0.32891 +27.7377,0.32944 +27.7814,0.33024 +27.8251,0.33077 +27.8689,0.33130 +27.9126,0.33183 +27.9563,0.33263 +28.0000,0.33316 +28.0437,0.33369 +28.0874,0.33422 +28.1311,0.33475 +28.1749,0.33528 +28.2186,0.33581 +28.2623,0.33634 +28.3060,0.33687 +28.3497,0.33767 +28.3934,0.33820 +28.4372,0.33873 +28.4809,0.33926 +28.5246,0.34005 +28.5683,0.34085 +28.6120,0.34138 +28.6557,0.34191 +28.6995,0.34271 +28.7432,0.34350 +28.7869,0.34403 +28.8306,0.34430 +28.8743,0.34483 +28.9180,0.34509 +28.9617,0.34562 +29.0055,0.34562 +29.0492,0.34615 +29.0929,0.34668 +29.1366,0.34668 +29.1803,0.34721 +29.2240,0.34721 +29.2678,0.34775 +29.3115,0.34828 +29.3552,0.34828 +29.3989,0.34881 +29.4426,0.34881 +29.4863,0.34934 +29.5301,0.34987 +29.5738,0.34987 +29.6175,0.35040 +29.6612,0.35040 +29.7049,0.35093 +29.7486,0.35146 +29.7923,0.35146 +29.8361,0.35199 +29.8798,0.35199 +29.9235,0.35252 +29.9672,0.35279 +30.0109,0.35305 +30.0546,0.35358 +30.0984,0.35358 +30.1421,0.35411 +30.1858,0.35385 +30.2295,0.35411 +30.2732,0.35438 +30.4918,0.35676 +30.5355,0.35676 +30.5792,0.35729 +30.6230,0.35756 +30.6667,0.35782 +30.7104,0.35836 +30.7541,0.35836 +30.7978,0.35782 +30.8415,0.35782 +30.8852,0.35729 +30.9290,0.35729 +30.9727,0.35676 +31.0164,0.35676 +31.0601,0.35623 +31.1038,0.35570 +31.1475,0.35570 +31.1913,0.35517 +31.2350,0.35517 +31.2787,0.35464 +31.3224,0.35464 +31.3661,0.35411 +31.4098,0.35385 +31.4536,0.35358 +31.4973,0.35305 +31.5410,0.35305 +31.5847,0.35252 +31.6284,0.35252 +31.6721,0.35199 +31.7158,0.35199 +31.7596,0.35146 +31.8033,0.35119 +31.8470,0.35093 +31.8907,0.35040 +31.9344,0.35040 +31.9781,0.34987 +32.0219,0.34987 +32.0656,0.34934 +32.1093,0.34934 +32.1530,0.34881 +32.1967,0.34828 +32.2404,0.34828 +32.2842,0.34775 +32.3279,0.34775 +32.3716,0.34721 +32.4153,0.34721 +32.4590,0.34668 +32.5027,0.34668 +32.5464,0.34615 +32.5902,0.34562 +32.6339,0.34562 +32.6776,0.34509 +32.7213,0.34509 +32.7650,0.34456 +32.8087,0.34456 +32.8525,0.34403 +32.8962,0.34377 +32.9399,0.34350 +32.9836,0.34297 +33.0273,0.34297 +33.0710,0.34244 +33.1148,0.34218 +33.1585,0.34191 +33.2022,0.34138 +33.2459,0.34111 +33.2896,0.34058 +33.3333,0.34032 +33.3770,0.33979 +33.4208,0.33952 +33.4645,0.33899 +33.5082,0.33873 +33.5519,0.33846 +33.5956,0.33793 +33.6393,0.33767 +33.6831,0.33714 +33.7268,0.33687 +33.7705,0.33634 +33.8142,0.33607 +33.8579,0.33554 +33.9016,0.33528 +33.9454,0.33475 +33.9891,0.33448 +34.0328,0.33422 +34.0765,0.33369 +34.1202,0.33342 +34.1639,0.33289 +34.2077,0.33263 +34.2514,0.33210 +34.2951,0.33183 +34.3388,0.33130 +34.3825,0.33103 +34.4262,0.33050 +34.4699,0.33024 +34.5137,0.32997 +34.5574,0.32971 +34.6011,0.32971 diff --git a/docs/figures/decks/rapid_fill/e2_velocity_9p9.csv b/docs/figures/decks/rapid_fill/e2_velocity_9p9.csv new file mode 100644 index 000000000..6a9b5b389 --- /dev/null +++ b/docs/figures/decks/rapid_fill/e2_velocity_9p9.csv @@ -0,0 +1,907 @@ +# source: Pinto et al. (2025) Fig. 6 -- raster image pinto2025_p06_Im6.png extracted from the +# publisher PDF at native resolution (see results/_p6/figures_native/). +# quantity: water velocity (m/s) at x = 9.9 m, SI. time zero = the event (runner applies t_offset). +# series identified by grey level: experiment 150-195/255, model curves < 110/255. +# x calibration (px -> s): 99.0 -> 0.0 1012.5 -> 40.0 (tick marks) +# y calibration (px -> val): 488.5 -> 0.0 43.0 -> 0.4 (tick marks) +# per-column median of the experiment mask; inset, legend and zoom-box removed. +# digitized 2026-08-31 by scripts/digitize/pinto_grey.py fig6_e2_v99 +time_s,velocity_mps +0.0876,0.00000 +0.1314,0.00224 +0.1752,0.00269 +0.2189,0.00449 +0.2627,0.00494 +0.3065,0.00494 +0.3503,0.00494 +0.3941,0.00449 +0.4379,0.00404 +0.4817,0.00314 +0.6130,0.00000 +0.6568,0.00314 +0.7006,0.00314 +0.7444,0.00314 +0.7882,0.00000 +0.8320,0.00000 +0.8758,-0.00314 +0.9195,-0.00314 +0.9633,-0.00314 +1.0071,-0.00314 +1.0509,-0.00314 +1.0947,-0.00314 +1.1385,-0.00314 +1.1823,-0.00314 +1.2261,0.00000 +1.2698,0.00000 +1.3136,0.00359 +1.3574,0.00404 +1.4012,0.00404 +1.4450,0.00404 +1.4888,0.00404 +1.5326,0.00449 +1.5764,0.00449 +1.6201,0.00494 +1.6639,0.00494 +1.7077,0.00449 +1.7515,0.00449 +1.7953,0.00449 +1.8391,0.00404 +1.8829,0.00404 +1.9267,0.00449 +1.9704,0.00494 +2.0142,0.00494 +2.0580,0.00539 +2.1018,0.00539 +2.1456,0.00494 +2.1894,0.00449 +2.2332,0.00404 +2.2770,0.00224 +2.3207,-0.00314 +2.3645,-0.00404 +2.4083,-0.00404 +2.4521,-0.00449 +2.4959,-0.00449 +2.5397,-0.00404 +2.5835,-0.00404 +2.6273,-0.00404 +2.6710,-0.00359 +2.7148,-0.00314 +2.7586,-0.00359 +2.8024,-0.00404 +2.8462,-0.00494 +2.8900,-0.00494 +2.9338,-0.00494 +2.9776,-0.00494 +3.0213,-0.00494 +3.0651,-0.00449 +3.1089,-0.00449 +3.1527,-0.00404 +3.1965,-0.00404 +3.2403,-0.00404 +3.2841,-0.00404 +3.3279,-0.00269 +3.3716,0.00000 +3.4154,0.00224 +3.4592,0.00314 +3.5030,0.00449 +3.5468,0.00449 +3.5906,0.00449 +3.6344,0.00494 +3.6782,0.00539 +3.7219,0.00584 +3.7657,0.00584 +3.8095,0.00584 +3.8533,0.00584 +3.8971,0.00539 +3.9409,0.00539 +3.9847,0.00539 +4.0285,0.00539 +4.0722,0.00539 +4.1160,0.00539 +4.1598,0.00584 +4.2036,0.00629 +4.2474,0.00584 +4.2912,0.00584 +4.3350,0.00584 +4.3788,0.00629 +4.4226,0.00673 +4.4663,0.00718 +4.5101,0.00808 +4.5539,0.00853 +4.5977,0.00943 +4.6415,0.00898 +4.6853,0.00898 +4.7291,0.00898 +4.7729,0.00898 +4.8166,0.00718 +4.8604,0.00718 +4.9042,-0.00898 +4.9480,0.00718 +4.9918,0.00718 +5.0356,0.00943 +5.0794,0.01033 +5.1232,0.01077 +5.1669,0.01167 +5.2107,0.01212 +5.2545,0.01212 +5.2983,0.01167 +5.3421,0.01122 +5.3859,0.01033 +5.4297,0.00943 +5.4735,0.00898 +5.5172,0.00898 +5.6924,0.01167 +5.7362,0.01212 +5.7800,0.01661 +5.9113,0.04848 +5.9551,0.01481 +5.9989,0.01751 +6.0427,0.01886 +6.0865,0.02110 +6.1303,0.09877 +6.1741,0.15488 +6.2178,0.21549 +6.2616,0.29675 +6.3054,0.30393 +6.3492,0.30617 +6.3930,0.30932 +6.4368,0.31111 +6.4806,0.31336 +6.5244,0.31695 +6.5681,0.32144 +6.6119,0.33939 +6.6557,0.34209 +6.6995,0.39461 +6.7433,0.39820 +6.7871,0.39865 +6.8309,0.39012 +6.8747,0.38070 +6.9184,0.33221 +6.9622,0.33042 +7.0060,0.33446 +7.0498,0.39192 +7.0936,0.34119 +7.1374,0.34478 +7.1812,0.34792 +7.2250,0.36139 +7.2687,0.37127 +7.3125,0.37262 +7.3563,0.36094 +7.4001,0.34658 +7.4439,0.34433 +7.4877,0.34029 +7.5315,0.33939 +7.5753,0.33760 +7.6190,0.33805 +7.6628,0.33805 +7.7066,0.33850 +7.7504,0.34029 +7.7942,0.34074 +7.8380,0.34164 +7.8818,0.34343 +7.9256,0.34613 +7.9693,0.34792 +8.0131,0.35017 +8.0569,0.35421 +8.1007,0.35690 +8.1445,0.36139 +8.1883,0.38070 +8.2321,0.37845 +8.2759,0.37800 +8.3196,0.36319 +8.3634,0.35780 +8.4072,0.34972 +8.4510,0.34568 +8.4948,0.33670 +8.5386,0.32772 +8.5824,0.32368 +8.6262,0.32054 +8.6700,0.31829 +8.7137,0.31919 +8.7575,0.32009 +8.8013,0.32144 +8.8451,0.32278 +8.8889,0.32233 +8.9327,0.32054 +8.9765,0.31695 +9.0203,0.31515 +9.0640,0.31515 +9.1078,0.31201 +9.1516,0.31066 +9.1954,0.30842 +9.2392,0.30572 +9.2830,0.31201 +9.3268,0.31201 +9.3706,0.31201 +9.4143,0.30932 +9.4581,0.30797 +9.5019,0.30617 +9.5457,0.30258 +9.5895,0.30168 +9.6333,0.29764 +9.6771,0.29181 +9.7209,0.28777 +9.7646,0.28283 +9.8084,0.27699 +9.8522,0.27834 +9.8960,0.27071 +9.9398,0.25230 +9.9836,0.23569 +10.0274,0.23300 +10.0712,0.22357 +10.1149,0.22222 +10.1587,0.21998 +10.2025,0.21279 +10.2463,0.20561 +10.2901,0.19933 +10.3339,0.19798 +10.3777,0.19394 +10.4215,0.19035 +10.4652,0.18721 +10.5090,0.18541 +10.5528,0.18631 +10.5966,0.18676 +10.6404,0.18721 +10.6842,0.18541 +10.7280,0.18406 +10.7718,0.18316 +10.8155,0.18182 +10.8593,0.18810 +10.9031,0.19259 +10.9469,0.19394 +10.9907,0.19304 +11.0345,0.19214 +11.0783,0.19169 +11.1221,0.19125 +11.1658,0.18496 +11.2096,0.18316 +11.2534,0.17104 +11.2972,0.16566 +11.3410,0.16386 +11.3848,0.16162 +11.4286,0.15713 +11.4724,0.15623 +11.5161,0.15488 +11.5599,0.15039 +11.6037,0.14994 +11.6475,0.14949 +11.6913,0.15129 +11.7351,0.15129 +11.7789,0.15039 +11.8227,0.15264 +11.8664,0.15309 +11.9102,0.14635 +11.9540,0.14635 +11.9978,0.14590 +12.0416,0.13962 +12.0854,0.13737 +12.1292,0.13468 +12.1730,0.13154 +12.2167,0.12974 +12.2605,0.12660 +12.3043,0.12525 +12.3481,0.12391 +12.3919,0.12301 +12.4357,0.12211 +12.4795,0.12076 +12.5233,0.13154 +12.5670,0.13244 +12.6108,0.13109 +12.6546,0.12840 +12.6984,0.12570 +12.7422,0.12525 +12.7860,0.12301 +12.8298,0.12076 +12.8736,0.11897 +12.9174,0.11762 +12.9611,0.11582 +13.0049,0.11448 +13.0487,0.11403 +13.0925,0.11313 +13.1363,0.10909 +13.1801,0.10460 +13.2239,0.10101 +13.2677,0.09787 +13.3114,0.09517 +13.3552,0.09158 +13.3990,0.08215 +13.4428,0.07138 +13.4866,0.06869 +13.5304,0.06016 +13.5742,0.05567 +13.6180,0.05342 +13.6617,0.05253 +13.7055,0.05118 +13.7493,0.04938 +13.7931,0.04848 +13.8369,0.04624 +13.8807,0.04444 +13.9245,0.04220 +13.9683,0.03816 +14.0120,0.03861 +14.0558,0.03681 +14.0996,0.03457 +14.1434,0.03232 +14.1872,0.02963 +14.2310,0.02828 +14.2748,0.02873 +14.3186,0.02828 +14.3623,0.02694 +14.4061,0.02290 +14.4499,0.02065 +14.4937,0.01930 +14.5375,0.01661 +14.5813,0.01392 +14.6251,0.01212 +14.6689,0.00808 +14.7126,0.00494 +14.7564,0.00135 +14.8002,0.00000 +14.8440,-0.00135 +14.8878,-0.00314 +14.9316,-0.00673 +14.9754,-0.01033 +15.0192,-0.01257 +15.0629,-0.02110 +15.1067,-0.02155 +15.1505,-0.02200 +15.1943,-0.02155 +15.2381,-0.02245 +15.2819,-0.03143 +15.3257,-0.03322 +15.3695,-0.03681 +15.4132,-0.03681 +15.4570,-0.03906 +15.5008,-0.04040 +15.5446,-0.04265 +15.5884,-0.04489 +15.6322,-0.04579 +15.6760,-0.04983 +15.7198,-0.05073 +15.7635,-0.05118 +15.8073,-0.05118 +15.8511,-0.05118 +15.8949,-0.04759 +15.9387,-0.04714 +16.0263,-0.05746 +16.0701,-0.05881 +16.1138,-0.05836 +16.1576,-0.05657 +16.2014,-0.06465 +16.2452,-0.06554 +16.2890,-0.06599 +16.3328,-0.06779 +16.3766,-0.06779 +16.4204,-0.07183 +16.4641,-0.07318 +16.5079,-0.07407 +16.5517,-0.07407 +16.5955,-0.07407 +16.6393,-0.07497 +16.6831,-0.07542 +16.7269,-0.08036 +16.7707,-0.08305 +16.8144,-0.08620 +16.8582,-0.08889 +16.9020,-0.09024 +16.9458,-0.09203 +16.9896,-0.09517 +17.0334,-0.09787 +17.0772,-0.10011 +17.1210,-0.10056 +17.1648,-0.09966 +17.2085,-0.09966 +17.2523,-0.09877 +17.2961,-0.10011 +17.3399,-0.10191 +17.3837,-0.10281 +17.4275,-0.10325 +17.4713,-0.10415 +17.5151,-0.10640 +17.5588,-0.10864 +17.6026,-0.11089 +17.6464,-0.11358 +17.6902,-0.11582 +17.7340,-0.11627 +17.7778,-0.11762 +17.8216,-0.12121 +17.8654,-0.12391 +17.9091,-0.12660 +17.9529,-0.12974 +17.9967,-0.13109 +18.0405,-0.13288 +18.0843,-0.13558 +18.1281,-0.13782 +18.1719,-0.14186 +18.2157,-0.14276 +18.2594,-0.14456 +18.3032,-0.14590 +18.3470,-0.14545 +18.3908,-0.14411 +18.4346,-0.14141 +18.4784,-0.14007 +18.5222,-0.13782 +18.5660,-0.13692 +18.6097,-0.13558 +18.6535,-0.13378 +18.6973,-0.13378 +18.7411,-0.13603 +18.7849,-0.13692 +18.8287,-0.13782 +18.8725,-0.14007 +18.9163,-0.14231 +18.9600,-0.14501 +19.0038,-0.14635 +19.0476,-0.14725 +19.0914,-0.14815 +19.1352,-0.14905 +19.1790,-0.14949 +19.2228,-0.14815 +19.2666,-0.14545 +19.3103,-0.14231 +19.3541,-0.14052 +19.3979,-0.13872 +19.4417,-0.13558 +19.4855,-0.13244 +19.5293,-0.13019 +19.5731,-0.13019 +19.6169,-0.13064 +19.6606,-0.12929 +19.7044,-0.12660 +19.7482,-0.12391 +19.7920,-0.12166 +19.8358,-0.12031 +19.8796,-0.11897 +19.9234,-0.11627 +19.9672,-0.11358 +20.0109,-0.11223 +20.0547,-0.11178 +20.0985,-0.10819 +20.1423,-0.10640 +20.1861,-0.10415 +20.2299,-0.10191 +20.2737,-0.10101 +20.3175,-0.09697 +20.3612,-0.09517 +20.4050,-0.09697 +20.4488,-0.09742 +20.4926,-0.09966 +20.5364,-0.10056 +20.5802,-0.10325 +20.6240,-0.10370 +20.6678,-0.10101 +20.7115,-0.10056 +20.7553,-0.09787 +20.7991,-0.09562 +20.8429,-0.09293 +20.8867,-0.09203 +20.9305,-0.09024 +20.9743,-0.08934 +21.0181,-0.08754 +21.0619,-0.08620 +21.1056,-0.08485 +21.1494,-0.08485 +21.1932,-0.08395 +21.2370,-0.08260 +21.2808,-0.08126 +21.3246,-0.08126 +21.3684,-0.08081 +21.4122,-0.07946 +21.4559,-0.07767 +21.4997,-0.07542 +21.5435,-0.07273 +21.5873,-0.07183 +21.6311,-0.07003 +21.6749,-0.06734 +21.7187,-0.06420 +21.7625,-0.06150 +21.8062,-0.05746 +21.8500,-0.05612 +21.8938,-0.05432 +21.9376,-0.05208 +21.9814,-0.05028 +22.0252,-0.04848 +22.0690,-0.04759 +22.1128,-0.04669 +22.1565,-0.04534 +22.2003,-0.04400 +22.2441,-0.04355 +22.2879,-0.04400 +22.3317,-0.04355 +22.3755,-0.04040 +22.4193,-0.03906 +22.4631,-0.03771 +22.5068,-0.03636 +22.5506,-0.03457 +22.5944,-0.03187 +22.6382,-0.03143 +22.6820,-0.03187 +22.7258,-0.03277 +22.7696,-0.03367 +22.8134,-0.03502 +22.8571,-0.03412 +22.9009,-0.03187 +22.9447,-0.03053 +22.9885,-0.02873 +23.0323,-0.02649 +23.0761,-0.02424 +23.1199,-0.02020 +23.1637,-0.01751 +23.2074,-0.01437 +23.2512,-0.01212 +23.2950,-0.00898 +23.3388,-0.00539 +23.3826,-0.00180 +23.4264,0.00045 +23.4702,0.00224 +23.5140,0.00449 +23.5577,0.00629 +23.6015,0.00898 +23.6453,0.01033 +23.6891,0.01212 +23.7329,0.01347 +23.7767,0.01437 +23.8205,0.01571 +23.8643,0.01616 +23.9080,0.01706 +23.9518,0.01796 +23.9956,0.01796 +24.0394,0.01526 +24.0832,0.01257 +24.1270,0.01122 +24.1708,0.01033 +24.2146,0.00943 +24.2583,0.00808 +24.3021,0.00943 +24.3459,0.01302 +24.3897,0.01661 +24.4335,0.01975 +24.4773,0.02334 +24.5211,0.02738 +24.5649,0.03098 +24.6086,0.03322 +24.6524,0.03591 +24.6962,0.03861 +24.7400,0.03951 +24.7838,0.03861 +24.8276,0.03861 +24.8714,0.03861 +24.9152,0.03906 +24.9589,0.03951 +25.0027,0.03996 +25.0465,0.04355 +25.0903,0.04444 +25.1341,0.04759 +25.1779,0.05297 +25.2217,0.05746 +25.2655,0.06105 +25.3093,0.06105 +25.3530,0.06150 +25.3968,0.05926 +25.4406,0.05926 +25.4844,0.05432 +25.5282,0.05926 +25.5720,0.06150 +25.6158,0.06240 +25.6596,0.06375 +25.7033,0.06465 +25.7471,0.06465 +25.7909,0.06510 +25.8347,0.06510 +25.8785,0.06375 +25.9223,0.05926 +25.9661,0.05567 +26.0099,0.05612 +26.0536,0.05612 +26.0974,0.05791 +26.1412,0.06195 +26.1850,0.06375 +26.2288,0.06554 +26.2726,0.06554 +26.3164,0.06554 +26.3602,0.06599 +26.4039,0.06824 +26.4477,0.07138 +26.4915,0.07318 +26.5353,0.07318 +26.5791,0.07363 +26.6229,0.07363 +26.6667,0.07363 +26.7105,0.07318 +26.7542,0.07273 +26.7980,0.07228 +26.8418,0.07138 +26.8856,0.06958 +26.9294,0.06734 +26.9732,0.06644 +27.0170,0.06734 +27.0608,0.06824 +27.1045,0.06824 +27.1483,0.06824 +27.1921,0.06824 +27.2359,0.06779 +27.2797,0.06779 +27.3235,0.06779 +27.3673,0.06824 +27.4111,0.06914 +27.4548,0.06958 +27.4986,0.07003 +27.5424,0.07003 +27.5862,0.06958 +27.6300,0.06914 +27.6738,0.06824 +27.7176,0.06689 +27.7614,0.06465 +27.8051,0.06420 +27.8489,0.06330 +27.8927,0.06285 +27.9365,0.06240 +27.9803,0.06105 +28.0241,0.06061 +28.0679,0.06016 +28.1117,0.06105 +28.1554,0.06105 +28.1992,0.06150 +28.2430,0.06105 +28.2868,0.06061 +28.3306,0.06016 +28.3744,0.05881 +28.4182,0.05836 +28.4620,0.05612 +28.5057,0.05567 +28.5495,0.05432 +28.5933,0.05297 +28.6371,0.05253 +28.6809,0.05163 +28.7247,0.04983 +28.7685,0.04938 +28.8123,0.04848 +28.8560,0.04848 +28.8998,0.04804 +28.9436,0.04804 +28.9874,0.04714 +29.0312,0.04714 +29.0750,0.04669 +29.1188,0.04579 +29.1626,0.04579 +29.2063,0.04534 +29.2501,0.04489 +29.2939,0.04400 +29.3377,0.04310 +29.3815,0.04175 +29.4253,0.04085 +29.4691,0.03996 +29.5129,0.03951 +29.5567,0.03906 +29.6004,0.03771 +29.6442,0.03726 +29.6880,0.03681 +29.7318,0.03502 +29.7756,0.03412 +29.8194,0.03322 +29.8632,0.03143 +29.9070,0.03008 +29.9507,0.02873 +29.9945,0.02738 +30.0383,0.02604 +30.0821,0.02469 +30.1259,0.02290 +30.1697,0.02155 +30.2135,0.02020 +30.2573,0.01886 +30.3010,0.01796 +30.3448,0.01706 +30.3886,0.01616 +30.4324,0.01437 +30.4762,0.01302 +30.5200,0.01212 +30.5638,0.01122 +30.6076,0.01033 +30.6513,0.00943 +30.6951,0.00808 +30.7389,0.00763 +30.7827,0.00673 +30.8265,0.00584 +30.8703,0.00494 +30.9141,0.00404 +30.9579,0.00269 +31.0016,0.00090 +31.0454,-0.00045 +31.0892,-0.00135 +31.1330,-0.00224 +31.1768,-0.00269 +31.2206,-0.00404 +31.2644,-0.00584 +31.3082,-0.00629 +31.3519,-0.00763 +31.3957,-0.00853 +31.4395,-0.00943 +31.4833,-0.00943 +31.5271,-0.01033 +31.5709,-0.01077 +31.6147,-0.01167 +31.6585,-0.01212 +31.7022,-0.01481 +31.7460,-0.01526 +31.7898,-0.01886 +31.8336,-0.02200 +31.8774,-0.02424 +31.9212,-0.02514 +31.9650,-0.02514 +32.0088,-0.02604 +32.0525,-0.02604 +32.0963,-0.02694 +32.1401,-0.02738 +32.1839,-0.02828 +32.2277,-0.02918 +32.2715,-0.02963 +32.3153,-0.03008 +32.3591,-0.03053 +32.4028,-0.03053 +32.4466,-0.03098 +32.4904,-0.03232 +32.5342,-0.03277 +32.5780,-0.03322 +32.6218,-0.03412 +32.6656,-0.03457 +32.7094,-0.03547 +32.7531,-0.03636 +32.7969,-0.03681 +32.8407,-0.03681 +32.8845,-0.03771 +32.9283,-0.03861 +32.9721,-0.03951 +33.0159,-0.04085 +33.0597,-0.04265 +33.1034,-0.04400 +33.1472,-0.04534 +33.1910,-0.04804 +33.2348,-0.04848 +33.2786,-0.04938 +33.3224,-0.05118 +33.3662,-0.05253 +33.4100,-0.05342 +33.4537,-0.05342 +33.4975,-0.05342 +33.5413,-0.05297 +33.5851,-0.05387 +33.6289,-0.05432 +33.6727,-0.05522 +33.7165,-0.05342 +33.7603,-0.05387 +33.8041,-0.05432 +34.0230,-0.06061 +34.0668,-0.05836 +34.1106,-0.05836 +34.1544,-0.05791 +34.1981,-0.05926 +34.2419,-0.05926 +34.2857,-0.05926 +34.3295,-0.05971 +34.3733,-0.06016 +34.4171,-0.06061 +34.4609,-0.06016 +34.5047,-0.06061 +34.5484,-0.06105 +34.5922,-0.06105 +34.6360,-0.06105 +34.6798,-0.06195 +34.7236,-0.06150 +34.7674,-0.06150 +34.8112,-0.06105 +34.8550,-0.06105 +34.8987,-0.06105 +34.9425,-0.06150 +34.9863,-0.06240 +35.0301,-0.06285 +35.0739,-0.06285 +35.1177,-0.06285 +35.1615,-0.06240 +35.2053,-0.06195 +35.2490,-0.06150 +35.2928,-0.06061 +35.3366,-0.06016 +35.3804,-0.05971 +35.4242,-0.05836 +35.4680,-0.05836 +35.5118,-0.05746 +35.5556,-0.05657 +35.5993,-0.05612 +35.6431,-0.05567 +35.6869,-0.05567 +35.7307,-0.05567 +35.7745,-0.05477 +35.8183,-0.05477 +35.8621,-0.05432 +35.9059,-0.05342 +35.9496,-0.05342 +35.9934,-0.05342 +36.0372,-0.05342 +36.0810,-0.05297 +36.1248,-0.05208 +36.1686,-0.05118 +36.2124,-0.05028 +36.2562,-0.04938 +36.2999,-0.04848 +36.3437,-0.04714 +36.3875,-0.04624 +36.4313,-0.04579 +36.4751,-0.04489 +36.5189,-0.04400 +36.5627,-0.04265 +36.6065,-0.04265 +36.6502,-0.04175 +36.6940,-0.04130 +36.7378,-0.03996 +36.7816,-0.03951 +36.8254,-0.03951 +36.8692,-0.03906 +36.9130,-0.03906 +36.9568,-0.03951 +37.0005,-0.03996 +37.0443,-0.04040 +37.0881,-0.04040 +37.1319,-0.03996 +37.1757,-0.03906 +37.2195,-0.03861 +37.2633,-0.03816 +37.3071,-0.03726 +37.3508,-0.03636 +37.3946,-0.03591 +37.4384,-0.03457 +37.4822,-0.03367 +37.5260,-0.03277 +37.5698,-0.03232 +37.6136,-0.03098 +37.6574,-0.03008 +37.7011,-0.03053 +37.7449,-0.03053 +37.7887,-0.03008 +37.8325,-0.02918 +37.8763,-0.02828 +37.9201,-0.02828 +37.9639,-0.02783 +38.0077,-0.02694 +38.0515,-0.02604 +38.0952,-0.02604 +38.1390,-0.02514 +38.1828,-0.02469 +38.2266,-0.02424 +38.2704,-0.02379 +38.3142,-0.02290 +38.3580,-0.02200 +38.4018,-0.02155 +38.4455,-0.02065 +38.4893,-0.01975 +38.5331,-0.01886 +38.5769,-0.01796 +38.6207,-0.01751 +38.6645,-0.01616 +38.7083,-0.01526 +38.7521,-0.01392 +38.7958,-0.01302 +38.8396,-0.01212 +38.8834,-0.01077 +38.9272,-0.00943 +38.9710,-0.00808 +39.0148,-0.00673 +39.0586,-0.00539 +39.1024,-0.00404 +39.1461,-0.00314 +39.1899,-0.00269 +39.2337,-0.00135 +39.2775,-0.00135 +39.3213,-0.00090 +39.3651,-0.00045 +39.4089,0.00000 +39.4527,0.00045 +39.4964,0.00135 +39.5402,0.00180 +39.5840,0.00269 +39.6278,0.00359 +39.6716,0.00449 +39.7154,0.00449 +39.7592,0.00494 +39.8030,0.00494 +39.8467,0.00763 +39.8905,0.00853 diff --git a/docs/figures/decks/rapid_fill/provenance.md b/docs/figures/decks/rapid_fill/provenance.md new file mode 100644 index 000000000..2f04db4e1 --- /dev/null +++ b/docs/figures/decks/rapid_fill/provenance.md @@ -0,0 +1,41 @@ +# rapid_fill — Vasconcelos, Wright and Roe (2006) rapid pipe-filling experiment + +| | | +|---|---| +| Deck | `rapid_fill.inp` | +| Copied from | `studies/mixed_flow_closures/decks/e2_rapid_fill_2006.inp` (untracked study folder), 2026-09-20 | +| Study plan | `plans/MIXED_FLOW_CLOSURES_TPA_UF_PLAN_2026-08-29.md`, experiment e2 (2006 parameterization) | +| Used by | the Application Manual's filling-pipe chapter; figures `workflow_ch2_rapid_fill_pressure_9p9`, `workflow_ch2_rapid_fill_front` | +| Changed on copy | nothing: byte-identical to the study deck | + +## The experiment + +An acrylic pipe 14.33 m long and 94 mm in diameter, horizontal, initially at +rest and 78 % full (0.073 m). A fill box 0.25 × 0.25 m feeds the upstream end +and a 0.19 m surge tank closes the downstream end. At t = 0 an inflow of +3.1 L/s is admitted at the fill box; a bore runs down the pipe, fills it, and +the surge tank oscillates. + +The paper's own numerics are in the deck: 400 cells (Δx ≈ 0.036 m), +Courant 0.95, Manning n = 0.012, acoustic celerity a = 25 m/s. + +Both gauge stations are **virtual junctions** — sealed splices, transparent to +the solution — so the deck doubles as a virtual-junction composition check. + +## Observed data + +| File | Quantity | Station | +|---|---|---| +| `e2_pressure_9p9.csv` | pressure head, m gauge | x = 9.9 m (node `VJ99`) | +| `e2_velocity_9p9.csv` | velocity, m/s | x = 9.9 m (link `C2`) | +| `e2_surgetank_level.csv` | water level, m | surge tank (node `ST`) | + +All three were digitised from the figures of the published paper at native +raster resolution; each file's header records the figure, the extraction and +any datum shift applied. The pressure series is gauge head at the transducer: +the paper plots head *variation*, and the initial water level of 0.073 m has +been added back. + +Vasconcelos, J. G., Wright, S. J. and Roe, P. L. (2006). Improved simulation +of flow regime transition in sewers: the two-component pressure approach. +*Journal of Hydraulic Engineering* 132(6), 553–562. diff --git a/docs/figures/decks/rapid_fill/rapid_fill.inp b/docs/figures/decks/rapid_fill/rapid_fill.inp new file mode 100644 index 000000000..9b7fd51ab --- /dev/null +++ b/docs/figures/decks/rapid_fill/rapid_fill.inp @@ -0,0 +1,71 @@ +[TITLE] +E2 (2006 parameterization) - Vasconcelos et al. (2006) rapid pipe-filling experiment. +Acrylic pipe L=14.33 m, D=0.094 m, horizontal. Upstream fill box 0.25x0.25 m (h=0.31 m), +downstream surge tank D=0.19 m (h=1.50 m). Initial uniform depth 0.073 m (78%D), at rest. +Inflow 3.1 L/s admitted at fill box at t=0. Free air venting (vent tower not modeled - 1D water). +Measured: pressure head at x=9.9 m (VJ99) and x=14.1 m (VJ141); velocity at 9.9 m (link C2); +surge-tank level (node ST depth). Paper numerics: 400 cells (dx~0.036 m), Cr=0.95, n=0.012, +a=25 m/s. Stations are VIRTUAL junctions: sealed splices, transparent to the solution - +they double as the VJ-composition check (plan MIXED_FLOW_CLOSURES §2.2(6)). + +[OPTIONS] +FLOW_UNITS LPS +FLOW_ROUTING FV +LINK_OFFSETS DEPTH +START_DATE 01/01/2026 +START_TIME 00:00:00 +END_DATE 01/01/2026 +END_TIME 00:05:00 +REPORT_STEP 0.05 +ROUTING_STEP 0.01 +MIN_SURFAREA 0.05 +SURCHARGE_METHOD EXTRAN +INERTIAL_DAMPING NONE +NORMAL_FLOW_LIMITED NEITHER +FV_CELL_LENGTH 0.036 +FV_MIN_CELLS 4 +FV_SLOT_CELERITY 25 + +[STORAGE] +;;Name Elev MaxDepth InitDepth Shape A1/Curve A2 A0 SurDepth Fevap +FB 0.0 0.31 0.073 FUNCTIONAL 0 0 0.0625 0 0 +ST 0.0 1.50 0.073 FUNCTIONAL 0 0 0.02835 0 0 + +[VIRTUAL_JUNCTIONS] +;;Name Elev +VJ99 0.0 +VJ141 0.0 + +; Rim-overflow path: the surge tank is open-topped (rim at 1.50 m). The weir crest +; sits AT the rim (= ST MaxDepth), so it is transparent to the solution; it exists +; because the engine (legacy ERROR 145 parity) requires >= 1 outfall node. +[OUTFALLS] +;;Name Elev Type StageData Gated +DN 0.0 FREE NO + +[WEIRS] +;;Name From To Type CrestHt Cd Gated EC +OVF ST DN TRANSVERSE 1.50 1.84 NO 0 + +[CONDUITS] +;;Name From To Length N Zin Zout Q0 +C1 FB VJ99 9.90 0.012 0 0 0 +C2 VJ99 VJ141 4.20 0.012 0 0 0 +C3 VJ141 ST 0.23 0.012 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +C1 CIRCULAR 0.094 0 0 0 1 +C2 CIRCULAR 0.094 0 0 0 1 +C3 CIRCULAR 0.094 0 0 0 1 +OVF RECT_OPEN 0.10 0.19 0 0 + +[INFLOWS] +;;Node Constituent Tseries Type Mfactor Sfactor Baseline +FB FLOW "" FLOW 1.0 1.0 3.1 + +[REPORT] +CONTINUITY YES +FLOWSTATS YES +NODES ALL +LINKS ALL diff --git a/docs/figures/decks/street_inlets/provenance.md b/docs/figures/decks/street_inlets/provenance.md new file mode 100644 index 000000000..6c70dac54 --- /dev/null +++ b/docs/figures/decks/street_inlets/provenance.md @@ -0,0 +1,22 @@ +# street_inlets — one street reach, two ways of attaching an inlet + +| | | +|---|---| +| Deck | `street_inlet_junction.inp` | +| Copied from | `examples/inlets/street_inlet_junction.inp` in this repository, 2026-09-20 | +| Used by | the Application Manual's street-inlets chapter; figure `workflow_ch5_inlet_capture_vs_bypass` | +| Changed on copy | nothing: byte-identical to the example | + +The example is maintained in `examples/inlets/` with its own README and is +exercised by the engine's tests; this copy exists so the manual's figure has +an input under `docs/figures/decks/` like every other simulated-tier figure. +Keep the two in step: if the example changes, re-copy it and rebuild the +figure. + +## What the deck contains + +One street reach draining to a parallel sewer through two inlets attached +differently — a conduit-attribute inlet on the first reach and an inlet +junction between the second and third — and all four `[INLETS]` design +grammars, including the two-line combination encoding and a custom design +pointing at a diversion curve. diff --git a/docs/figures/decks/street_inlets/street_inlet_junction.inp b/docs/figures/decks/street_inlets/street_inlet_junction.inp new file mode 100644 index 000000000..b08e2197c --- /dev/null +++ b/docs/figures/decks/street_inlets/street_inlet_junction.inp @@ -0,0 +1,234 @@ +;;============================================================================ +;; OpenSWMM — Street Inlets and the Inlet Junction +;; +;; One street reach draining to a parallel sewer through two street inlets, +;; each attached a different way: +;; +;; 1. A conduit-attribute inlet — the legacy form. [INLET_USAGE] puts design +;; Combo1 on street conduit ST_A; captured flow is booked at ST_A's +;; downstream node (J_MID) and delivered to manhole MH1. The uncaptured +;; (bypass) flow stays on the street and continues down ST_B. +;; +;; 2. An inlet junction — the spatially explicit form. IJ1 is a node of its +;; own between street conduits ST_B and ST_C: it captures the gutter flow +;; arriving on ST_B, delivers it to MH2, passes the bypass on through +;; ST_C, can flood above the curb, and takes MH2's surcharge back onto +;; the street as backflow. An inlet junction is a virtual junction +;; (zero storage, momentum transmitting) that also carries an inlet, so +;; it obeys every [VIRTUAL_JUNCTIONS] rule: exactly two conduits, the +;; same cross-section on both, zero offsets, DYNWAVE routing. +;; +;; [INLETS] shows all four design grammars: a GRATE line, a CURB line with a +;; throat angle, the two-line COMBO encoding (one GRATE line and one CURB line +;; sharing a name, merged into a single combination design), and a CUSTOM +;; design pointing at a DIVERSION curve. Grate1 and Custom1 are library +;; designs here — nothing places them; see README.md for how to swap one in. +;; +;; J_TOP --ST_A--> J_MID --ST_B--> [IJ1] --ST_C--> OUT_ST (street, at grade) +;; | capture | capture +;; +--> MH1 --SW_1--> MH2 --+--SW_2--> OUT_SEW (sewer, buried) +;; +;; A conduit attached to an inlet junction may not also carry an [INLET_USAGE] +;; row (that would capture the same water twice, engine rule 629), which is +;; why the conduit-attribute inlet sits on ST_A rather than on ST_B or ST_C. +;; +;; Run: openswmm-cli street_inlet_junction.inp street_inlet_junction.rpt +;; Then read the Street Flow Summary and the Street Inlet Flow Summary in the +;; .rpt — README.md says what to look for. +;;============================================================================ + +[TITLE] +Street Inlets and the Inlet Junction +A conduit-attribute inlet and an inlet junction on one street reach. + + +[OPTIONS] +FLOW_UNITS CFS +INFILTRATION HORTON +FLOW_ROUTING DYNWAVE +LINK_OFFSETS DEPTH +MIN_SLOPE 0 +ALLOW_PONDING NO +SKIP_STEADY_STATE NO + +START_DATE 01/01/2026 +START_TIME 00:00:00 +REPORT_START_DATE 01/01/2026 +REPORT_START_TIME 00:00:00 +END_DATE 01/01/2026 +END_TIME 03:00:00 +SWEEP_START 01/01 +SWEEP_END 12/31 +DRY_DAYS 0 +REPORT_STEP 00:01:00 +WET_STEP 00:05:00 +DRY_STEP 01:00:00 +ROUTING_STEP 00:00:05 + + +;;---------------------------------------------------------------------------- +;; Nodes +;;---------------------------------------------------------------------------- +;; Street nodes carry a shallow MaxDepth: the street surface, not a manhole. +;; IJ1 is NOT listed here — an inlet junction lives in [INLET_JUNCTIONS]. + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +;;---------------- ------------ ------------ ------------ ------------ ------------ +J_TOP 100.0000 1.5000 0.0000 0.0000 0.0000 +J_MID 99.0000 1.5000 0.0000 0.0000 0.0000 +MH1 90.0000 8.0000 0.0000 0.0000 0.0000 +MH2 89.0000 9.0000 0.0000 0.0000 0.0000 + +;; Tokens 1-3 are exactly [VIRTUAL_JUNCTIONS] (name, invert, MaxDepth); here +;; MaxDepth is the flood threshold above the invert, not just a drawing hint. +;; Tokens 4-11 are exactly the [INLET_USAGE] tail (design, capture node, +;; #Inlets, %Clog, Qmax, aLocal, wLocal, Placement). + +[INLET_JUNCTIONS] +;;Name Elev MaxDepth Inlet CaptureNode #Inlets %Clog Qmax aLocal wLocal Placement +;;---------------- ------------ ------------ ---------------- ---------------- -------- -------- ---------- ---------- ---------- ---------- +IJ1 98.0000 0.5000 Curb1 MH2 1 10 0 0 0 ON_GRADE + +[OUTFALLS] +;;Name Elev Type Stage Data Gated Route To +;;---------------- ------------ ------------ ---------------- -------- ---------------- +OUT_ST 97.0000 FREE NO +OUT_SEW 88.0000 FREE NO + + +;;---------------------------------------------------------------------------- +;; Links +;;---------------------------------------------------------------------------- +;; ST_B and ST_C must share one cross-section and have zero offsets: they are +;; the pair IJ1 sits between. + +[CONDUITS] +;;Name From To Length N Z1 Z2 Q0 +;;---------------- ---------------- ---------------- ---------- ---------- ---------- ---------- ---------- +ST_A J_TOP J_MID 200.00 0.0160 0 0 0 +ST_B J_MID IJ1 200.00 0.0160 0 0 0 +ST_C IJ1 OUT_ST 200.00 0.0160 0 0 0 +SW_1 MH1 MH2 200.00 0.0130 0 0 0 +SW_2 MH2 OUT_SEW 200.00 0.0130 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 Barrels +;;---------------- ------------ ------------ ---------- ---------- ---------- ---------- +ST_A STREET ST_MAIN +ST_B STREET ST_MAIN +ST_C STREET ST_MAIN +SW_1 CIRCULAR 2.0000 0 0 0 1 +SW_2 CIRCULAR 2.0000 0 0 0 1 + + +;;---------------------------------------------------------------------------- +;; Street cross-section +;;---------------------------------------------------------------------------- +;; Tcrown half-width of the crowned roadway (ft) +;; Hcurb curb height (ft) Sx cross slope (%) +;; nRoad pavement Manning's n a gutter depression (in) +;; W depressed gutter width (ft) Sides 1 = curb on one side only +;; Tback / Sback / nBack the backing (parkway) strip behind the curb + +[STREETS] +;;Name Tcrown Hcurb Sx nRoad a W Sides Tback Sback nBack +;;---------------- ---------- ---------- ---------- ---------- ---------- ---------- -------- ---------- ---------- ---------- +ST_MAIN 20.0000 0.5000 4.0000 0.0160 2.0000 2.0000 1 10.0000 4.0000 0.0160 + + +;;---------------------------------------------------------------------------- +;; Inlet designs +;;---------------------------------------------------------------------------- +;; GRATE Name GRATE Length Width GrateType [OpenArea SplashVeloc] +;; CURB Name CURB Length Height [ThroatType] +;; COMBO (no keyword) a GRATE line and a CURB line under ONE name +;; SLOTTED Name SLOTTED Length Width +;; DROP_GRATE Name DROP_GRATE Length Width GrateType (drainage channels) +;; DROP_CURB Name DROP_CURB Length Height (drainage channels) +;; CUSTOM Name CUSTOM CurveID (a DIVERSION or RATING curve) + +[INLETS] +;;Name Type Param1 Param2 Param3 +;;---------------- ------------ ---------- ---------- ---------- +Grate1 GRATE 2.0000 2.0000 P_BAR-50 +Curb1 CURB 3.0000 0.5000 HORIZONTAL +;; Combo1: the legacy two-line combination inlet — a grate in the gutter plus +;; a curb opening beside it. The reader merges the pair into one COMBO design +;; and the writer emits it back as these same two lines. +Combo1 GRATE 2.0000 2.0000 CURVED_VANE +Combo1 CURB 3.0000 0.5000 VERTICAL +Custom1 CUSTOM DIV_CAP + + +;;---------------------------------------------------------------------------- +;; Inlet placement — the conduit-attribute form +;;---------------------------------------------------------------------------- +;; Captured flow leaves ST_A at its downstream node and arrives at MH1; the +;; bypass stays on the street. Qmax = 0 means the inlet is not flow-limited; +;; aLocal / wLocal = 0 means no local depression beyond the street's own +;; gutter. %Clog 10 keeps 90 % of the theoretical capacity. + +[INLET_USAGE] +;;Link Inlet Node #Inlets %Clog Qmax aLocal wLocal Placement +;;---------------- ---------------- ---------------- -------- -------- ---------- ---------- ---------- ---------- +ST_A Combo1 MH1 2 10 0 0 0 ON_GRADE + + +;;---------------------------------------------------------------------------- +;; Capture curve for the CUSTOM design (captured flow vs. approach flow) +;;---------------------------------------------------------------------------- +;; The [INLETS] CUSTOM line carries no curve-kind token: the curve's own type +;; is the kind. DIVERSION = captured flow as a function of approach flow; +;; RATING = captured flow as a function of ponded depth (sag inlets). + +[CURVES] +;;Name Type X-Value Y-Value +;;---------------- ------------ ---------- ---------- +DIV_CAP DIVERSION 0.0 0.0 +DIV_CAP 1.0 0.9 +DIV_CAP 3.0 2.1 +DIV_CAP 6.0 3.0 +DIV_CAP 12.0 3.6 + + +;;---------------------------------------------------------------------------- +;; Forcing — a two-hour gutter hydrograph entering the top of the street +;;---------------------------------------------------------------------------- + +[INFLOWS] +;;Node Constituent Time Series Type Mfactor Sfactor Baseline Pattern +;;---------------- ---------------- ---------------- -------- -------- -------- -------- -------- +J_TOP FLOW GUTTER_TS FLOW 1.0 1.0 + +[TIMESERIES] +;;Name Date Time Value +;;---------------- ------------ ------------ ---------- +GUTTER_TS 0:00 0.0 +GUTTER_TS 0:15 2.0 +GUTTER_TS 0:30 8.0 +GUTTER_TS 0:45 12.0 +GUTTER_TS 1:00 8.0 +GUTTER_TS 1:30 3.0 +GUTTER_TS 2:00 0.0 +GUTTER_TS 3:00 0.0 + + +[REPORT] +INPUT NO +CONTROLS NO +SUBCATCHMENTS ALL +NODES ALL +LINKS ALL + + +[COORDINATES] +;;Node X-Coord Y-Coord +;;---------------- ------------------ ------------------ +J_TOP 0.000 0.000 +J_MID 200.000 0.000 +IJ1 400.000 0.000 +OUT_ST 600.000 0.000 +MH1 200.000 -100.000 +MH2 400.000 -100.000 +OUT_SEW 600.000 -100.000 diff --git a/docs/figures/decks/transport_demo/provenance.md b/docs/figures/decks/transport_demo/provenance.md new file mode 100644 index 000000000..e678e42e2 --- /dev/null +++ b/docs/figures/decks/transport_demo/provenance.md @@ -0,0 +1,41 @@ +# transport_demo — five conduits, one tracer step, four process components + +| | | +|---|---| +| Deck | `transport_demo.inp` with the sidecars `transport_demo.rxn`, `.ard`, `.age`, `.heat` | +| Copied from | `openswmm.gui/docs/manual/tutorials/models/` (SWMMVis manual tutorial T7), 2026-09-20 | +| Used by | the Application Manual's transport-engines, multi-species-reactions and age-and-heat chapters | +| Changed on copy | nothing; the GUI copy is the same five files | + +## What the deck contains + +Five junctions in a line, `J1` to `J5`, discharging to the free outfall +`OUT1` through five 100 m circular conduits. A constant 0.2 m³/s inflow +enters at `J1` from t = 0 carrying + +- `TRACER`, a conservative pollutant at 10 mg/L, +- `DECAY`, a first-order pollutant at 20 mg/L with k = 2 /day, +- an inlet temperature of 18 °C, against air warming from 12 to 22 °C. + +Because the inflow starts at t = 0 into a clean system, the tracer arrives +at each junction as a **step front**, which is what makes this deck a +comparison of how each transport engine carries a front. + +Four process components are configured from the sidecars: a reaction +system with an Arrhenius temperature dependence, the Eulerian transport +options, the water-age source ages, and the heat sources with their flux +modules and radiative forcing. + +## Snippet markers + +The deck carries `;//! [name]` marker pairs around the blocks the manual +quotes — `options`, `temperature`, `pollutants`, `inflows`, `components` — +so the chapters can `\snippet` them rather than copy them. Keep the markers +in step with the GUI copy if either changes. + +## A note on the reporting step + +The deck reports every 5 minutes, which is right for reading the tutorial's +tables and too coarse for the front: it crosses the line in about five +minutes. The manual's figures upsert `REPORT_STEP 0:00:10` for that reason, +and the committed deck is left as the tutorial has it. diff --git a/docs/figures/decks/transport_demo/transport_demo.age b/docs/figures/decks/transport_demo/transport_demo.age new file mode 100644 index 000000000..ce2baf032 --- /dev/null +++ b/docs/figures/decks/transport_demo/transport_demo.age @@ -0,0 +1,6 @@ +;; Water-age source ages for the SWMMVis manual tutorial T7. +;; Values are in HOURS. Requires [OPTIONS] WATER_AGE ON in transport_demo.inp. + +[WATER_AGE_SOURCES] +EXTERNAL_INFLOW GLOBAL 0.5 +INITIAL_STATE GLOBAL 6.0 diff --git a/docs/figures/decks/transport_demo/transport_demo.ard b/docs/figures/decks/transport_demo/transport_demo.ard new file mode 100644 index 000000000..7f667ff7d --- /dev/null +++ b/docs/figures/decks/transport_demo/transport_demo.ard @@ -0,0 +1,8 @@ +;; Eulerian ARD transport options for the SWMMVis manual tutorial T7. +;; Only meaningful when [OPTIONS] QUALITY_SOLVER is EULERIAN_ARD. + +[TRANSPORT_OPTIONS] +DISPERSION FISCHER +SCALAR_SCHEME MUSCL +LIMITER VANLEER +TARGET_DX 25 diff --git a/docs/figures/decks/transport_demo/transport_demo.heat b/docs/figures/decks/transport_demo/transport_demo.heat new file mode 100644 index 000000000..1e7f9e558 --- /dev/null +++ b/docs/figures/decks/transport_demo/transport_demo.heat @@ -0,0 +1,23 @@ +;; Heat transport configuration for the SWMMVis manual tutorial T7. +;; Requires [OPTIONS] HEAT_TRANSPORT ON in transport_demo.inp, and the +;; [TEMPERATURE] block there supplies air temperature and humidity. + +[HEAT_SOURCES] +;;Source Scope Value (degC) +EXTERNAL_INFLOW GLOBAL 18.0 +INITIAL_STATE GLOBAL 12.0 + +[HEAT_FLUXES] +SURFACE_EXCHANGE ON +RADIATIVE_EXCHANGE ON + +[RADIATIVE_FLUXES] +SHORTWAVE GLOBAL COMPUTED +ALBEDO GLOBAL 0.08 +SKY_VIEW GLOBAL 0.90 + +[SOLAR_RADIATION] +LATITUDE GLOBAL 41.7 +LONGITUDE GLOBAL -111.8 +TIMEZONE GLOBAL -7.0 +ELEVATION GLOBAL 1380.0 diff --git a/docs/figures/decks/transport_demo/transport_demo.inp b/docs/figures/decks/transport_demo/transport_demo.inp new file mode 100644 index 000000000..95643a96d --- /dev/null +++ b/docs/figures/decks/transport_demo/transport_demo.inp @@ -0,0 +1,116 @@ +[TITLE] +Transport demo for the SWMMVis user manual (tutorial T7). +Five junctions in a line (J1 -> J5) discharging to the free outfall OUT1 +through five 100 m circular conduits. A constant 0.2 m3/s inflow enters at +J1 carrying a conservative tracer, a first-order decaying constituent and +an 18 C inlet temperature. +Sidecar component configs (same folder): + transport_demo.rxn reaction system (chlorine-like species with an + Arrhenius temperature dependence) + transport_demo.ard Eulerian ARD transport options + transport_demo.age water-age source ages + transport_demo.heat heat sources, flux modules, radiative + solar forcing + +;//! [options] +[OPTIONS] +FLOW_UNITS CMS +INFILTRATION HORTON +FLOW_ROUTING DYNWAVE +START_DATE 01/01/2026 +START_TIME 00:00:00 +END_DATE 01/01/2026 +END_TIME 06:00:00 +REPORT_STEP 0:05:00 +ROUTING_STEP 5 +QUALITY_SOLVER EULERIAN_ARD +WATER_AGE ON +HEAT_TRANSPORT ON +;//! [options] + +[EVAPORATION] +CONSTANT 0.0 +DRY_ONLY NO + +;//! [temperature] +[TEMPERATURE] +TIMESERIES AIR_TEMP +HUMIDITY 50.0 +;//! [temperature] + +[JUNCTIONS] +;;Name Elev MaxDepth InitDepth SurDepth Aponded +J1 10.0 3.0 0 0 0 +J2 9.5 3.0 0 0 0 +J3 9.0 3.0 0 0 0 +J4 8.5 3.0 0 0 0 +J5 8.0 3.0 0 0 0 + +[OUTFALLS] +;;Name Elev Type Gated +OUT1 7.5 FREE NO + +[CONDUITS] +;;Name From To Length Roughness InOffset OutOffset InitFlow +C1 J1 J2 100 0.013 0 0 0 +C2 J2 J3 100 0.013 0 0 0 +C3 J3 J4 100 0.013 0 0 0 +C4 J4 J5 100 0.013 0 0 0 +C5 J5 OUT1 100 0.013 0 0 0 + +[XSECTIONS] +;;Link Shape Geom1 Geom2 Geom3 Geom4 +C1 CIRCULAR 1.0 0 0 0 +C2 CIRCULAR 1.0 0 0 0 +C3 CIRCULAR 1.0 0 0 0 +C4 CIRCULAR 1.0 0 0 0 +C5 CIRCULAR 1.0 0 0 0 + +;//! [pollutants] +[POLLUTANTS] +;;Name Units Crain Cgw Crdii Kdecay SnowOnly CoPollut CoFrac Cdwf Cinit +TRACER MG/L 0 0 0 0 NO * 0 0 0 +DECAY MG/L 0 0 0 2.0 NO * 0 0 0 +;//! [pollutants] + +;//! [inflows] +[INFLOWS] +;;Node Constituent TimeSeries Type Mfactor Sfactor Baseline +J1 FLOW "" FLOW 1.0 1.0 0.2 +J1 TRACER "" CONCEN 1.0 1.0 10.0 +J1 DECAY "" CONCEN 1.0 1.0 20.0 +J1 __TEMPERATURE__ "" CONCEN 1.0 1.0 18.0 +;//! [inflows] + +[TIMESERIES] +;;Name Date Time Value +AIR_TEMP 01/01/2026 00:00 12.0 +AIR_TEMP 01/01/2026 03:00 20.0 +AIR_TEMP 01/01/2026 06:00 22.0 + +;//! [components] +[PROCESS_COMPONENTS] +org.hydrocouple.openswmm.reactions config="transport_demo.rxn" +org.hydrocouple.openswmm.transport.ard config="transport_demo.ard" +org.hydrocouple.openswmm.waterage config="transport_demo.age" +org.hydrocouple.openswmm.heat config="transport_demo.heat" +;//! [components] + +[REPORT] +INPUT NO +CONTINUITY YES +FLOWSTATS YES +NODES ALL +LINKS ALL + +[MAP] +DIMENSIONS 0.000 0.000 600.000 200.000 +Units Meters + +[COORDINATES] +;;Node X Y +J1 50.0 100.0 +J2 150.0 100.0 +J3 250.0 100.0 +J4 350.0 100.0 +J5 450.0 100.0 +OUT1 550.0 100.0 diff --git a/docs/figures/decks/transport_demo/transport_demo.rxn b/docs/figures/decks/transport_demo/transport_demo.rxn new file mode 100644 index 000000000..7ad93623d --- /dev/null +++ b/docs/figures/decks/transport_demo/transport_demo.rxn @@ -0,0 +1,31 @@ +;; Reaction system for the SWMMVis manual tutorial T7. +;; One bulk species that decays first order, with an Arrhenius (theta^(T-20)) +;; temperature correction taken from the heat module's computed water +;; temperature. TEMP is a hydraulic variable available to every expression. + +[REACTION_OPTIONS] +SOLVER RK5 +COUPLING NONE +RATE_UNITS HR +TEMPERATURE 20 + +[REACTION_SPECIES] +;;Kind Name Units +BULK CL2 MG + +[REACTION_COEFFICIENTS] +;;Kind Name Value +CONSTANT kb 0.30 +CONSTANT theta 1.07 + +[REACTION_PIPES] +;;Form Species Expression +RATE CL2 -kb * theta ^ (TEMP - 20) * CL2 + +[REACTION_TANKS] +;;Form Species Expression +RATE CL2 -kb * theta ^ (TEMP - 20) * CL2 + +[REACTION_QUALITY] +;;Scope Species Value +GLOBAL CL2 2.0 diff --git a/docs/figures/png/.gitkeep b/docs/figures/png/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/figures/png/eng_conceptual_map.png b/docs/figures/png/eng_conceptual_map.png new file mode 100644 index 000000000..aae8b5d60 Binary files /dev/null and b/docs/figures/png/eng_conceptual_map.png differ diff --git a/docs/figures/png/eng_lid_bioretention_layers.png b/docs/figures/png/eng_lid_bioretention_layers.png new file mode 100644 index 000000000..54ea5c23e Binary files /dev/null and b/docs/figures/png/eng_lid_bioretention_layers.png differ diff --git a/docs/figures/png/eng_object_sketch.png b/docs/figures/png/eng_object_sketch.png new file mode 100644 index 000000000..3a0376d68 Binary files /dev/null and b/docs/figures/png/eng_object_sketch.png differ diff --git a/docs/figures/png/eng_process_flow.png b/docs/figures/png/eng_process_flow.png new file mode 100644 index 000000000..2c2d1aee6 Binary files /dev/null and b/docs/figures/png/eng_process_flow.png differ diff --git a/docs/figures/png/eng_rdii_unit_hydrograph.png b/docs/figures/png/eng_rdii_unit_hydrograph.png new file mode 100644 index 000000000..7db26db63 Binary files /dev/null and b/docs/figures/png/eng_rdii_unit_hydrograph.png differ diff --git a/docs/figures/png/hydraulics_ch3_virtual_junction.png b/docs/figures/png/hydraulics_ch3_virtual_junction.png new file mode 100644 index 000000000..702c1d619 Binary files /dev/null and b/docs/figures/png/hydraulics_ch3_virtual_junction.png differ diff --git a/docs/figures/png/hydraulics_ch5_circular_theta.png b/docs/figures/png/hydraulics_ch5_circular_theta.png new file mode 100644 index 000000000..58ff26827 Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_circular_theta.png differ diff --git a/docs/figures/png/hydraulics_ch5_power_law.png b/docs/figures/png/hydraulics_ch5_power_law.png new file mode 100644 index 000000000..480a1a2ac Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_power_law.png differ diff --git a/docs/figures/png/hydraulics_ch5_shapes_composite.png b/docs/figures/png/hydraulics_ch5_shapes_composite.png new file mode 100644 index 000000000..7c9aec586 Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_shapes_composite.png differ diff --git a/docs/figures/png/hydraulics_ch5_shapes_elliptical_arch.png b/docs/figures/png/hydraulics_ch5_shapes_elliptical_arch.png new file mode 100644 index 000000000..e4d4f11df Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_shapes_elliptical_arch.png differ diff --git a/docs/figures/png/hydraulics_ch5_shapes_masonry.png b/docs/figures/png/hydraulics_ch5_shapes_masonry.png new file mode 100644 index 000000000..b35fb2d17 Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_shapes_masonry.png differ diff --git a/docs/figures/png/hydraulics_ch5_storage_cone.png b/docs/figures/png/hydraulics_ch5_storage_cone.png new file mode 100644 index 000000000..f3356a4a1 Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_storage_cone.png differ diff --git a/docs/figures/png/hydraulics_ch5_storage_cylinder.png b/docs/figures/png/hydraulics_ch5_storage_cylinder.png new file mode 100644 index 000000000..6cce34d0a Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_storage_cylinder.png differ diff --git a/docs/figures/png/hydraulics_ch5_storage_paraboloid.png b/docs/figures/png/hydraulics_ch5_storage_paraboloid.png new file mode 100644 index 000000000..e07ec5a3e Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_storage_paraboloid.png differ diff --git a/docs/figures/png/hydraulics_ch5_storage_pyramid.png b/docs/figures/png/hydraulics_ch5_storage_pyramid.png new file mode 100644 index 000000000..725fb84bd Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_storage_pyramid.png differ diff --git a/docs/figures/png/hydraulics_ch5_street_section.png b/docs/figures/png/hydraulics_ch5_street_section.png new file mode 100644 index 000000000..fe2e22d1b Binary files /dev/null and b/docs/figures/png/hydraulics_ch5_street_section.png differ diff --git a/docs/figures/png/hydraulics_ch6_pump_type1.png b/docs/figures/png/hydraulics_ch6_pump_type1.png new file mode 100644 index 000000000..6094cede6 Binary files /dev/null and b/docs/figures/png/hydraulics_ch6_pump_type1.png differ diff --git a/docs/figures/png/hydraulics_ch6_pump_type2.png b/docs/figures/png/hydraulics_ch6_pump_type2.png new file mode 100644 index 000000000..9fb88a763 Binary files /dev/null and b/docs/figures/png/hydraulics_ch6_pump_type2.png differ diff --git a/docs/figures/png/hydraulics_ch6_pump_type3.png b/docs/figures/png/hydraulics_ch6_pump_type3.png new file mode 100644 index 000000000..db7f3ed9d Binary files /dev/null and b/docs/figures/png/hydraulics_ch6_pump_type3.png differ diff --git a/docs/figures/png/hydraulics_ch6_pump_type4.png b/docs/figures/png/hydraulics_ch6_pump_type4.png new file mode 100644 index 000000000..8870929f2 Binary files /dev/null and b/docs/figures/png/hydraulics_ch6_pump_type4.png differ diff --git a/docs/figures/png/hydraulics_ch6_pump_type5.png b/docs/figures/png/hydraulics_ch6_pump_type5.png new file mode 100644 index 000000000..6da85741a Binary files /dev/null and b/docs/figures/png/hydraulics_ch6_pump_type5.png differ diff --git a/docs/figures/png/hydraulics_ch7_street_spread.png b/docs/figures/png/hydraulics_ch7_street_spread.png new file mode 100644 index 000000000..7df2761b3 Binary files /dev/null and b/docs/figures/png/hydraulics_ch7_street_spread.png differ diff --git a/docs/figures/png/hydraulics_ch8_cell_layout.png b/docs/figures/png/hydraulics_ch8_cell_layout.png new file mode 100644 index 000000000..af6a25c37 Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_cell_layout.png differ diff --git a/docs/figures/png/hydraulics_ch8_hll_fan.png b/docs/figures/png/hydraulics_ch8_hll_fan.png new file mode 100644 index 000000000..5d2fe85e8 Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_hll_fan.png differ diff --git a/docs/figures/png/hydraulics_ch8_hydrostatic_reconstruction.png b/docs/figures/png/hydraulics_ch8_hydrostatic_reconstruction.png new file mode 100644 index 000000000..9569b81aa Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_hydrostatic_reconstruction.png differ diff --git a/docs/figures/png/hydraulics_ch8_lts_ladder.png b/docs/figures/png/hydraulics_ch8_lts_ladder.png new file mode 100644 index 000000000..fab41f2ef Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_lts_ladder.png differ diff --git a/docs/figures/png/hydraulics_ch8_node_ghost_state.png b/docs/figures/png/hydraulics_ch8_node_ghost_state.png new file mode 100644 index 000000000..09ed38f0c Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_node_ghost_state.png differ diff --git a/docs/figures/png/hydraulics_ch8_slot_closure.png b/docs/figures/png/hydraulics_ch8_slot_closure.png new file mode 100644 index 000000000..93630894d Binary files /dev/null and b/docs/figures/png/hydraulics_ch8_slot_closure.png differ diff --git a/docs/figures/png/hydraulics_ch9_active_set.png b/docs/figures/png/hydraulics_ch9_active_set.png new file mode 100644 index 000000000..7f16e9180 Binary files /dev/null and b/docs/figures/png/hydraulics_ch9_active_set.png differ diff --git a/docs/figures/png/hydraulics_ch9_coupling_modes.png b/docs/figures/png/hydraulics_ch9_coupling_modes.png new file mode 100644 index 000000000..2342c74fc Binary files /dev/null and b/docs/figures/png/hydraulics_ch9_coupling_modes.png differ diff --git a/docs/figures/png/hydraulics_ch9_mesh_stencil.png b/docs/figures/png/hydraulics_ch9_mesh_stencil.png new file mode 100644 index 000000000..e28d41a78 Binary files /dev/null and b/docs/figures/png/hydraulics_ch9_mesh_stencil.png differ diff --git a/docs/figures/png/hydraulics_ch9_vfr_wetting_cases.png b/docs/figures/png/hydraulics_ch9_vfr_wetting_cases.png new file mode 100644 index 000000000..4e64ddc44 Binary files /dev/null and b/docs/figures/png/hydraulics_ch9_vfr_wetting_cases.png differ diff --git a/docs/figures/png/hydraulics_conceptual_1d2d.png b/docs/figures/png/hydraulics_conceptual_1d2d.png new file mode 100644 index 000000000..49a74608e Binary files /dev/null and b/docs/figures/png/hydraulics_conceptual_1d2d.png differ diff --git a/docs/figures/png/hydraulics_conceptual_map.png b/docs/figures/png/hydraulics_conceptual_map.png new file mode 100644 index 000000000..54b27c71e Binary files /dev/null and b/docs/figures/png/hydraulics_conceptual_map.png differ diff --git a/docs/figures/png/hydrology_ch3_nonlinear_reservoir.png b/docs/figures/png/hydrology_ch3_nonlinear_reservoir.png new file mode 100644 index 000000000..9dae75d3f Binary files /dev/null and b/docs/figures/png/hydrology_ch3_nonlinear_reservoir.png differ diff --git a/docs/figures/png/hydrology_ch4_green_ampt_curve.png b/docs/figures/png/hydrology_ch4_green_ampt_curve.png new file mode 100644 index 000000000..af498344c Binary files /dev/null and b/docs/figures/png/hydrology_ch4_green_ampt_curve.png differ diff --git a/docs/figures/png/hydrology_ch4_green_ampt_recovery_params.png b/docs/figures/png/hydrology_ch4_green_ampt_recovery_params.png new file mode 100644 index 000000000..b63538464 Binary files /dev/null and b/docs/figures/png/hydrology_ch4_green_ampt_recovery_params.png differ diff --git a/docs/figures/png/hydrology_ch4_horton_cumulative.png b/docs/figures/png/hydrology_ch4_horton_cumulative.png new file mode 100644 index 000000000..18f0c4b65 Binary files /dev/null and b/docs/figures/png/hydrology_ch4_horton_cumulative.png differ diff --git a/docs/figures/png/hydrology_ch4_horton_curve.png b/docs/figures/png/hydrology_ch4_horton_curve.png new file mode 100644 index 000000000..823bbc187 Binary files /dev/null and b/docs/figures/png/hydrology_ch4_horton_curve.png differ diff --git a/docs/figures/png/hydrology_ch4_horton_recovery.png b/docs/figures/png/hydrology_ch4_horton_recovery.png new file mode 100644 index 000000000..9d4cfb5e7 Binary files /dev/null and b/docs/figures/png/hydrology_ch4_horton_recovery.png differ diff --git a/docs/figures/png/hydrology_ch5_lateral_flow_heights.png b/docs/figures/png/hydrology_ch5_lateral_flow_heights.png new file mode 100644 index 000000000..6d7cc93c3 Binary files /dev/null and b/docs/figures/png/hydrology_ch5_lateral_flow_heights.png differ diff --git a/docs/figures/png/hydrology_ch5_two_zone.png b/docs/figures/png/hydrology_ch5_two_zone.png new file mode 100644 index 000000000..6bf9e1f4b Binary files /dev/null and b/docs/figures/png/hydrology_ch5_two_zone.png differ diff --git a/docs/figures/png/hydrology_ch6_areal_depletion_curve.png b/docs/figures/png/hydrology_ch6_areal_depletion_curve.png new file mode 100644 index 000000000..02a3fc9f0 Binary files /dev/null and b/docs/figures/png/hydrology_ch6_areal_depletion_curve.png differ diff --git a/docs/figures/png/hydrology_ch7_ia_seasonal.png b/docs/figures/png/hydrology_ch7_ia_seasonal.png new file mode 100644 index 000000000..a31a8ee30 Binary files /dev/null and b/docs/figures/png/hydrology_ch7_ia_seasonal.png differ diff --git a/docs/figures/png/hydrology_ch7_rtk_unit_hydrographs.png b/docs/figures/png/hydrology_ch7_rtk_unit_hydrographs.png new file mode 100644 index 000000000..a48b7040b Binary files /dev/null and b/docs/figures/png/hydrology_ch7_rtk_unit_hydrographs.png differ diff --git a/docs/figures/png/hydrology_ch8_cell_budget.png b/docs/figures/png/hydrology_ch8_cell_budget.png new file mode 100644 index 000000000..81a1e1e4f Binary files /dev/null and b/docs/figures/png/hydrology_ch8_cell_budget.png differ diff --git a/docs/figures/png/hydrology_ch8_infiltration_strip.png b/docs/figures/png/hydrology_ch8_infiltration_strip.png new file mode 100644 index 000000000..66206e8b3 Binary files /dev/null and b/docs/figures/png/hydrology_ch8_infiltration_strip.png differ diff --git a/docs/figures/png/hydrology_ch8_nn_weights.png b/docs/figures/png/hydrology_ch8_nn_weights.png new file mode 100644 index 000000000..83d02e838 Binary files /dev/null and b/docs/figures/png/hydrology_ch8_nn_weights.png differ diff --git a/docs/figures/png/hydrology_ch9_node_bed_exchange.png b/docs/figures/png/hydrology_ch9_node_bed_exchange.png new file mode 100644 index 000000000..58e29fc99 Binary files /dev/null and b/docs/figures/png/hydrology_ch9_node_bed_exchange.png differ diff --git a/docs/figures/png/hydrology_ch9_soil_characteristics.png b/docs/figures/png/hydrology_ch9_soil_characteristics.png new file mode 100644 index 000000000..f491a15f5 Binary files /dev/null and b/docs/figures/png/hydrology_ch9_soil_characteristics.png differ diff --git a/docs/figures/png/hydrology_ch9_two_layer_column.png b/docs/figures/png/hydrology_ch9_two_layer_column.png new file mode 100644 index 000000000..d7b81c55f Binary files /dev/null and b/docs/figures/png/hydrology_ch9_two_layer_column.png differ diff --git a/docs/figures/png/hydrology_conceptual_map.png b/docs/figures/png/hydrology_conceptual_map.png new file mode 100644 index 000000000..0ecdd6024 Binary files /dev/null and b/docs/figures/png/hydrology_conceptual_map.png differ diff --git a/docs/figures/png/quality_ch10_cell_buildup_washoff.png b/docs/figures/png/quality_ch10_cell_buildup_washoff.png new file mode 100644 index 000000000..8c1b22b33 Binary files /dev/null and b/docs/figures/png/quality_ch10_cell_buildup_washoff.png differ diff --git a/docs/figures/png/quality_ch10_transport_policy.png b/docs/figures/png/quality_ch10_transport_policy.png new file mode 100644 index 000000000..ce3766c8a Binary files /dev/null and b/docs/figures/png/quality_ch10_transport_policy.png differ diff --git a/docs/figures/png/quality_ch6_lid_bio_cell.png b/docs/figures/png/quality_ch6_lid_bio_cell.png new file mode 100644 index 000000000..d2b77dce8 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_bio_cell.png differ diff --git a/docs/figures/png/quality_ch6_lid_block_paver.png b/docs/figures/png/quality_ch6_lid_block_paver.png new file mode 100644 index 000000000..d9bc0ba2e Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_block_paver.png differ diff --git a/docs/figures/png/quality_ch6_lid_green_roof.png b/docs/figures/png/quality_ch6_lid_green_roof.png new file mode 100644 index 000000000..2063a5f00 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_green_roof.png differ diff --git a/docs/figures/png/quality_ch6_lid_infiltration_trench.png b/docs/figures/png/quality_ch6_lid_infiltration_trench.png new file mode 100644 index 000000000..47941afda Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_infiltration_trench.png differ diff --git a/docs/figures/png/quality_ch6_lid_permeable_pavement.png b/docs/figures/png/quality_ch6_lid_permeable_pavement.png new file mode 100644 index 000000000..be2af9116 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_permeable_pavement.png differ diff --git a/docs/figures/png/quality_ch6_lid_rain_barrel.png b/docs/figures/png/quality_ch6_lid_rain_barrel.png new file mode 100644 index 000000000..de7703f48 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_rain_barrel.png differ diff --git a/docs/figures/png/quality_ch6_lid_rain_garden.png b/docs/figures/png/quality_ch6_lid_rain_garden.png new file mode 100644 index 000000000..0794fbee1 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_rain_garden.png differ diff --git a/docs/figures/png/quality_ch6_lid_rooftop_disconnection.png b/docs/figures/png/quality_ch6_lid_rooftop_disconnection.png new file mode 100644 index 000000000..47b6561c5 Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_rooftop_disconnection.png differ diff --git a/docs/figures/png/quality_ch6_lid_vegetative_swale.png b/docs/figures/png/quality_ch6_lid_vegetative_swale.png new file mode 100644 index 000000000..5cfc4f7cd Binary files /dev/null and b/docs/figures/png/quality_ch6_lid_vegetative_swale.png differ diff --git a/docs/figures/png/quality_ch7_ard_stencil.png b/docs/figures/png/quality_ch7_ard_stencil.png new file mode 100644 index 000000000..d1e449b11 Binary files /dev/null and b/docs/figures/png/quality_ch7_ard_stencil.png differ diff --git a/docs/figures/png/quality_ch7_lard_parcels.png b/docs/figures/png/quality_ch7_lard_parcels.png new file mode 100644 index 000000000..23046eb2a Binary files /dev/null and b/docs/figures/png/quality_ch7_lard_parcels.png differ diff --git a/docs/figures/png/quality_ch9_heat_budget.png b/docs/figures/png/quality_ch9_heat_budget.png new file mode 100644 index 000000000..d9f913292 Binary files /dev/null and b/docs/figures/png/quality_ch9_heat_budget.png differ diff --git a/docs/figures/png/quality_conceptual_map.png b/docs/figures/png/quality_conceptual_map.png new file mode 100644 index 000000000..4aabf7d8d Binary files /dev/null and b/docs/figures/png/quality_conceptual_map.png differ diff --git a/docs/figures/png/workflow_ch10_heat_diurnal.png b/docs/figures/png/workflow_ch10_heat_diurnal.png new file mode 100644 index 000000000..2bd118518 Binary files /dev/null and b/docs/figures/png/workflow_ch10_heat_diurnal.png differ diff --git a/docs/figures/png/workflow_ch10_water_age_along_line.png b/docs/figures/png/workflow_ch10_water_age_along_line.png new file mode 100644 index 000000000..b0aac90fa Binary files /dev/null and b/docs/figures/png/workflow_ch10_water_age_along_line.png differ diff --git a/docs/figures/png/workflow_ch11_rdii_decay_vs_linear.png b/docs/figures/png/workflow_ch11_rdii_decay_vs_linear.png new file mode 100644 index 000000000..cd0d5dabd Binary files /dev/null and b/docs/figures/png/workflow_ch11_rdii_decay_vs_linear.png differ diff --git a/docs/figures/png/workflow_ch2_rapid_fill_front.png b/docs/figures/png/workflow_ch2_rapid_fill_front.png new file mode 100644 index 000000000..2431af37d Binary files /dev/null and b/docs/figures/png/workflow_ch2_rapid_fill_front.png differ diff --git a/docs/figures/png/workflow_ch2_rapid_fill_pressure_9p9.png b/docs/figures/png/workflow_ch2_rapid_fill_pressure_9p9.png new file mode 100644 index 000000000..0aea61210 Binary files /dev/null and b/docs/figures/png/workflow_ch2_rapid_fill_pressure_9p9.png differ diff --git a/docs/figures/png/workflow_ch3_negative_pressure_head_14p1.png b/docs/figures/png/workflow_ch3_negative_pressure_head_14p1.png new file mode 100644 index 000000000..1e05afcf0 Binary files /dev/null and b/docs/figures/png/workflow_ch3_negative_pressure_head_14p1.png differ diff --git a/docs/figures/png/workflow_ch3_velocity_9p9.png b/docs/figures/png/workflow_ch3_velocity_9p9.png new file mode 100644 index 000000000..7d884f57b Binary files /dev/null and b/docs/figures/png/workflow_ch3_velocity_9p9.png differ diff --git a/docs/figures/png/workflow_ch4_cedar_glen_profile_hgl.png b/docs/figures/png/workflow_ch4_cedar_glen_profile_hgl.png new file mode 100644 index 000000000..2c5caa66f Binary files /dev/null and b/docs/figures/png/workflow_ch4_cedar_glen_profile_hgl.png differ diff --git a/docs/figures/png/workflow_ch4_cedar_glen_worst_node_head.png b/docs/figures/png/workflow_ch4_cedar_glen_worst_node_head.png new file mode 100644 index 000000000..5b1cec74b Binary files /dev/null and b/docs/figures/png/workflow_ch4_cedar_glen_worst_node_head.png differ diff --git a/docs/figures/png/workflow_ch5_inlet_capture_vs_bypass.png b/docs/figures/png/workflow_ch5_inlet_capture_vs_bypass.png new file mode 100644 index 000000000..5b4e42481 Binary files /dev/null and b/docs/figures/png/workflow_ch5_inlet_capture_vs_bypass.png differ diff --git a/docs/figures/png/workflow_ch6_mesh_and_coupling.png b/docs/figures/png/workflow_ch6_mesh_and_coupling.png new file mode 100644 index 000000000..e49fac6ca Binary files /dev/null and b/docs/figures/png/workflow_ch6_mesh_and_coupling.png differ diff --git a/docs/figures/png/workflow_ch6_momentum_closures_depth.png b/docs/figures/png/workflow_ch6_momentum_closures_depth.png new file mode 100644 index 000000000..31662f8cd Binary files /dev/null and b/docs/figures/png/workflow_ch6_momentum_closures_depth.png differ diff --git a/docs/figures/png/workflow_ch7_rain_and_infiltration.png b/docs/figures/png/workflow_ch7_rain_and_infiltration.png new file mode 100644 index 000000000..cf644d34a Binary files /dev/null and b/docs/figures/png/workflow_ch7_rain_and_infiltration.png differ diff --git a/docs/figures/png/workflow_ch8_ard_dx_sensitivity.png b/docs/figures/png/workflow_ch8_ard_dx_sensitivity.png new file mode 100644 index 000000000..acd40f4b7 Binary files /dev/null and b/docs/figures/png/workflow_ch8_ard_dx_sensitivity.png differ diff --git a/docs/figures/png/workflow_ch8_tracer_breakthrough_three_engines.png b/docs/figures/png/workflow_ch8_tracer_breakthrough_three_engines.png new file mode 100644 index 000000000..5e17456d0 Binary files /dev/null and b/docs/figures/png/workflow_ch8_tracer_breakthrough_three_engines.png differ diff --git a/docs/figures/png/workflow_ch9_arrhenius_rate_from_temperature.png b/docs/figures/png/workflow_ch9_arrhenius_rate_from_temperature.png new file mode 100644 index 000000000..cda678589 Binary files /dev/null and b/docs/figures/png/workflow_ch9_arrhenius_rate_from_temperature.png differ diff --git a/docs/figures/primitives.py b/docs/figures/primitives.py new file mode 100644 index 000000000..15f54a3bb --- /dev/null +++ b/docs/figures/primitives.py @@ -0,0 +1,138 @@ +"""Drawing primitives shared by the diagram generators. + +Only what two or more generators use: rounded boxes, status pills, labelled +arrows, a legend of the four statuses, and a text-width estimate for laying +pills out without a renderer. Axes are in "tenths of an inch" data units +(see ``canvas``), so estimates stay honest at any figure size. +""" +from __future__ import annotations + +import matplotlib.pyplot as plt +from matplotlib.patches import FancyArrowPatch, FancyBboxPatch + +import status as st +import style + +U = 10.0 # data units per inch +EM = 0.56 # average glyph width, DejaVu Sans, in em + +COMP_FILL = {"atm": "#eef4fb", "land": "#f2f6ec", "sub": "#f7f1e6", "conv": "#eeeeee", "out": "#e6eff7"} +COMP_EDGE = "#b9b6ad" +BOX_FILL, BOX_EDGE = "#ffffff", "#d5d2c8" +ARROW = {"water": style.WATER, "mass": "#8a3ffc", "coupling": "#eb6834", "energy": "#d6336c"} + + +def canvas(width_in: float, height_in: float): + """A figure + axis whose data units are tenths of an inch.""" + fig = style.figure(width_in, height_in) + ax = fig.add_axes([0, 0, 1, 1]) + ax.set_xlim(0, width_in * U) + ax.set_ylim(0, height_in * U) + style.schematic_ax(ax) + return fig, ax + + +def est_width(text: str, size_pt: float) -> float: + """Approximate rendered width in data units.""" + return len(text) * size_pt * EM / 72.0 * U + + +def rounded(ax, x, y, w, h, *, fc=BOX_FILL, ec=BOX_EDGE, lw=0.9, ls="-", alpha=1.0, r=0.5, z=1): + p = FancyBboxPatch((x, y), w, h, boxstyle=f"round,pad=0,rounding_size={r}", + fc=fc, ec=ec, lw=lw, ls=ls, alpha=alpha, zorder=z) + ax.add_patch(p) + return p + + +def label(ax, x, y, s, *, size=9, weight="normal", color=style.INK, ha="left", va="top", + alpha=1.0, z=3, style_=None, rotation=0): + return ax.text(x, y, s, fontsize=size, fontweight=weight, color=color, ha=ha, va=va, + alpha=alpha, zorder=z, fontstyle=style_ or "normal", rotation=rotation) + + +def pill(ax, x, y, text, status_key, *, size=7.0, alpha=1.0, z=4): + """One alternative as a pill; returns (width, height) in data units. + + Style is the single status vocabulary: Implemented = thin green outline, + Experimental = amber outline and tint, Planned = grey dashed outline and + grey text, Retired = pink outline and struck-through text. + """ + lab, colour = st.STATUS[status_key] + w = est_width(text, size) + 0.9 + h = size / 72.0 * U * 1.75 + ls, fc, tc, lw = "-", "#ffffff", style.INK, 0.8 + if status_key == "experimental": + fc, lw = colour + "26", 1.1 + elif status_key == "planned": + ls, tc = (0, (2.2, 1.6)), colour + elif status_key == "retired": + tc = colour + rounded(ax, x, y, w, h, fc=fc, ec=colour, lw=lw, ls=ls, alpha=alpha, r=h / 2, z=z) + t = ax.text(x + w / 2, y + h / 2, text, fontsize=size, color=tc, ha="center", va="center", + alpha=alpha, zorder=z + 1) + if status_key == "retired": + t.set_path_effects([]) + ax.plot([x + 0.45, x + w - 0.45], [y + h / 2, y + h / 2], color=colour, lw=0.9, + alpha=alpha, zorder=z + 2) + return w, h + + +def pill_row(ax, x, y, width, alts, *, size=7.0, gap=0.45, alpha=1.0, z=4, out=None): + """Lay pills out left-to-right, wrapping within `width`; y is the TOP. + + `alts` is a list of (text, feature_id); a feature_id of None draws a + neutral pill (a value, not an alternative). Returns the height consumed. + When `out` is a list, every pill's (text, feature_id, x, y, w, h) box in + data units is appended to it, so a generator can register hotspots. + """ + cx, cy = x, y + row_h = size / 72.0 * U * 1.75 + used = row_h + for text, fid in alts: + key = st.FEATURES[fid] if fid else "implemented" + w = est_width(text, size) + 0.9 + if cx > x and cx + w > x + width: + cx, cy = x, cy - row_h - gap + used += row_h + gap + if out is not None: + out.append((text, fid, cx, cy - row_h, w, row_h)) + if fid is None: + rounded(ax, cx, cy - row_h, w, row_h, fc="#f4f3ef", ec="#e1e0d9", lw=0.7, + alpha=alpha, r=row_h / 2, z=z) + ax.text(cx + w / 2, cy - row_h / 2, text, fontsize=size, color=style.MUTED, + ha="center", va="center", alpha=alpha, zorder=z + 1) + else: + pill(ax, cx, cy - row_h, text, key, size=size, alpha=alpha, z=z) + cx += w + gap + return used + + +def arrow(ax, p0, p1, *, kind="water", text=None, size=6.8, both=False, alpha=1.0, z=2, + rad=0.0, text_offset=(0.0, 0.0), rotation=0, lw=1.2): + colour = ARROW[kind] + a = FancyArrowPatch(p0, p1, arrowstyle="<|-|>" if both else "-|>", mutation_scale=9, + color=colour, lw=lw, alpha=alpha, zorder=z, + connectionstyle=f"arc3,rad={rad}", shrinkA=0, shrinkB=0) + ax.add_patch(a) + if text: + mx, my = (p0[0] + p1[0]) / 2 + text_offset[0], (p0[1] + p1[1]) / 2 + text_offset[1] + ax.text(mx, my, text, fontsize=size, color=colour, ha="center", va="center", alpha=alpha, + zorder=z + 1, fontstyle="italic", rotation=rotation, + bbox=dict(boxstyle="round,pad=0.15", fc=style.SURFACE, ec="none", alpha=0.9 * alpha)) + return a + + +def legend(ax, x, y, *, size=7.0, title="Status of each alternative"): + """The four statuses as pills, left-to-right, starting at (x, y-top).""" + label(ax, x, y, title, size=size, color=style.MUTED) + cx = x + row_h = size / 72.0 * U * 1.75 + top = y - size / 72.0 * U * 1.6 + for key, (lab, _) in st.STATUS.items(): + w, h = pill(ax, cx, top - row_h, lab, key, size=size) + cx += w + 0.5 + return cx - x + + +def close_all(): + plt.close("all") diff --git a/docs/figures/refs.py b/docs/figures/refs.py new file mode 100644 index 000000000..d4e17331c --- /dev/null +++ b/docs/figures/refs.py @@ -0,0 +1,195 @@ +"""Where each formulation is documented — the click targets of the +conceptual map, the process-flow chart and the object sketch. + +`FEATURE_REFS` maps a feature id of status.py to the Doxygen page (or +anchor) that documents it; `TITLE_REFS` maps a process-box title or a +neutral pill's text to a page. The generators register one hotspot per +pill and per title through `sink.hotspot()`, and the build writes them +into the citing pages as `@ref` links, so Doxygen and the lint validate +every target. A feature that has no entry here is drawn but not linked. + +Targets are page ids (`@page …`) or explicit anchors (`{#…}`); the +`engine_manual_sect_
` anchors are the [SECTION] grammar entries +of the Engine Manual's Chapter 2. +""" +from __future__ import annotations + +H = "hydraulics_ref_" +Y = "hydrology_ref_" +Q = "quality_ref_" +S = "engine_manual_sect_" + +# feature id -> page id or anchor +FEATURE_REFS = { + "runoff.subcatchment": Y + "ch3_surface_runoff", + "runoff.mesh_2d": H + "ch9_two_dimensional", + "infiltration.horton": Y + "ch4_infiltration", + "infiltration.mod_horton": Y + "ch4_infiltration", + "infiltration.green_ampt": Y + "ch4_infiltration", + "infiltration.mod_green_ampt": Y + "ch4_infiltration", + "infiltration.curve_number": Y + "ch4_infiltration", + "infiltration.mesh_per_cell": Y + "ch8_mesh_surface", + "infiltration.mesh_constant": Y + "ch8_mesh_surface", + "snowmelt.degree_day": Y + "ch6_snowmelt", + "rain.mesh_natural_neighbour": Y + "ch8_mesh_surface", + "evaporation.mesh": Y + "ch8_mesh_surface", + "lid.layered": Q + "ch6_lid_controls", + "lid.storage_node": Q + "ch6_lid_controls", # -> hydrology_ref_ch10_planned when it lands + "lid.detailed_output": Q + "ch6_lid_controls", # -> hydrology_ref_ch10_planned when it lands + "quality.buildup_washoff": Q + "ch3_pollutant_buildup", + "quality.mesh_surface": Q + "ch10_mesh_quality", + "climate.humidity_dewpoint": Y + "ch2_meteorology", + "climate.precip_scaling": Y + "ch2_meteorology", + "climate.pet_forcing": Y + "ch2_meteorology", + "rdii.rtk": Y + "ch7_rdii", + "rdii.ia_decay": Y + "ch7_rdii", + "groundwater.two_zone": Y + "ch5_groundwater", + "groundwater.mesh_two_layer": Y + "ch9_mesh_groundwater", + "groundwater.mesh_per_subcatch": Y + "ch9_mesh_groundwater", + "groundwater.soil.gardner": Y + "ch9_mesh_groundwater", + "groundwater.soil.russo": Y + "ch9_mesh_groundwater", + "groundwater.soil.brooks_corey": Y + "ch9_mesh_groundwater", + "groundwater.soil.van_genuchten": Y + "ch9_mesh_groundwater", + "groundwater.transport": Y + "ch9_mesh_groundwater", # -> hydrology_ref_ch10_planned when it lands + "routing.steady": H + "ch2_hydraulic_model", + "routing.kinwave": H + "ch4_kinematic_wave", + "routing.dynwave": H + "ch3_dynamic_wave", + "routing.fv": H + "ch8_finite_volume", + "routing.node_continuity.explicit": H + "ch3_dynamic_wave", + "routing.node_continuity.semi_implicit": H + "ch3_dynamic_wave", + "routing.anderson": H + "ch3_anderson", + "pressurisation.extran": H + "ch3_dynamic_wave", + "pressurisation.slot": H + "ch3_dynamic_wave", + "pressurisation.dynamic_slot": H + "ch3_dynamic_wave", + "pressurisation.tpa": H + "ch3_dynamic_wave", + "fv.closure.slot": H + "ch8_finite_volume", + "fv.closure.tpa": H + "ch8_finite_volume", + "fv.pressurized_implicit": H + "ch8_finite_volume", + "fv.lts": H + "ch8_lts", + "fv.node_coupling_keys": H + "ch10_planned", + "fv.implicit_hypre": H + "ch10_planned", + "fv.bed_step_junction_faces": H + "ch10_planned", + "fv.tpa_high_celerity_fix": H + "ch10_planned", + "friction.unsteady_vitkovsky": H + "ch3_dynamic_wave", + "backend.1d.cpu": H + "ch8_finite_volume", + "backend.1d.gpu": H + "ch10_planned", + "junctions.virtual": H + "ch3_dynamic_wave", + "junctions.virtual_momentum_full": H + "ch10_planned", + "junctions.inlet": H + "ch7_advanced_features", + "inlets.link_attribute": H + "ch7_advanced_features", + "xsect.tabulated": H + "ch5_cross_section", + "xsect.street": H + "ch5_cross_section", + "xsect.dummy": H + "ch5_cross_section", + "xsect.chebyshev_irregular": H + "ch10_planned", + "storage.shapes": H + "ch5_cross_section", + "overland2d.local_inertial": H + "ch9_two_dimensional", + "overland2d.full_swe": H + "ch9_two_dimensional", + "overland2d.diffusive_wave": H + "ch9_two_dimensional", + "overland2d.integrator.explicit": H + "ch9_two_dimensional", + "overland2d.integrator.cvode": H + "ch10_planned", + "overland2d.imex": H + "ch10_planned", + "overland2d.advection_key": H + "ch10_planned", + "overland2d.cell_closure.flat": H + "ch9_two_dimensional", + "overland2d.cell_closure.vfr": H + "ch9_two_dimensional", + "overland2d.mesh.triangles": H + "ch9_two_dimensional", + "overland2d.mesh.quads": H + "ch9_two_dimensional", + "coupling.1d2d.vertex": H + "ch9_two_dimensional", + "coupling.1d2d.cell": H + "ch9_two_dimensional", + "backend.2d.cpu": H + "ch9_two_dimensional", + "backend.2d.omp": H + "ch9_two_dimensional", + "backend.2d.cuda": H + "ch9_two_dimensional", + "backend.2d.hip": H + "ch9_two_dimensional", + "backend.2d.sycl": H + "ch9_two_dimensional", + "backend.2d.metal": H + "ch10_planned", + "transport.cstr": Q + "ch5_transport_treatment", + "transport.ard": Q + "ch7_ard_transport", + "transport.lard": Q + "ch7_ard_transport", + "transport.rwpt": Q + "ch7_ard_transport", + "transport.mesh_2d": Q + "ch10_mesh_quality", + "transport.fv_mesh_pollutants": Q + "ch11_planned", + "reactions.first_order": Q + "ch5_transport_treatment", + "reactions.msx": Q + "ch8_msx_reactions", + "reactions.bw_msx": Q + "ch10_mesh_quality", + "water_age": Q + "ch9_age_heat", + "heat": Q + "ch9_age_heat", + "heat.per_element_attributes": Q + "ch11_planned", + "sediment": Q + "ch11_planned", + "outfall.backflow_quality": Q + "ch7_ard_transport", +} + +# process-box title or neutral-pill text -> page id or anchor +TITLE_REFS = { + # conceptual map processes + "Precipitation": Y + "ch2_meteorology", + "Climate": Y + "ch2_meteorology", + "Snowmelt": Y + "ch6_snowmelt", + "Runoff": Y + "ch3_surface_runoff", + "Infiltration": Y + "ch4_infiltration", + "LID controls": Q + "ch6_lid_controls", + "Surface quality": Q + "ch3_pollutant_buildup", + "Rain on the mesh": Y + "ch8_mesh_surface", + "Per-cell infiltration": Y + "ch8_mesh_surface", + "Overland flow": H + "ch9_two_dimensional", + "Mesh and closure": H + "ch9_two_dimensional", + "Surface quality · transport": Q + "ch10_mesh_quality", + "Backends": H + "ch9_two_dimensional", + "Two-zone aquifer": Y + "ch5_groundwater", + "Groundwater transport": Y + "ch9_mesh_groundwater", # -> hydrology_ref_ch10_planned when it lands + "Two-layer aquifer": Y + "ch9_mesh_groundwater", + "Nodes": S + "JUNCTIONS", + "Links": S + "CONDUITS", + "Flow routing": H + "ch2_hydraulic_model", + "Pressurisation": H + "ch3_dynamic_wave", + "Node solution": H + "ch3_dynamic_wave", + "Transport": Q + "ch5_transport_treatment", + "Inflows": S + "INFLOWS", + # process-flow boxes + "Initial abstraction · evaporation": Y + "ch3_surface_runoff", + "Surface runoff": Y + "ch3_surface_runoff", + "Washoff": Q + "ch4_surface_washoff", + "Groundwater": Y + "ch5_groundwater", + "Pollutant buildup": Q + "ch3_pollutant_buildup", + "2D overland flow": H + "ch9_two_dimensional", + "Per-cell infiltration · evaporation": Y + "ch8_mesh_surface", + "2D surface quality": Q + "ch10_mesh_quality", + "External inflows": S + "INFLOWS", + "Street inlets": H + "ch7_advanced_features", + "Channel, pipe and storage routing": H + "ch2_hydraulic_model", + "Transport and reactions": Q + "ch5_transport_treatment", + "OUTFALLS · receiving water": S + "OUTFALLS", + # neutral pills (values, not alternatives) + "rain gages": S + "RAINGAGES", + "rain · snow": S + "RAINGAGES", + "temperature": S + "TEMPERATURE", + "wind": S + "TEMPERATURE", + "evaporation: constant · monthly · series · Hargreaves · file": S + "EVAPORATION", + "depression storage": S + "SUBAREAS", + "routing to another subcatchment": S + "SUBAREAS", + "street sweeping": S + "LANDUSES", + "system": S + "2D_OPTIONS", + "→ lost · subcatchment aquifer · mesh aquifer": S + "2D_INFILTRATION_OPTIONS", + "→ lost · subcatchment · mesh aquifer": S + "2D_INFILTRATION_OPTIONS", + "percolation · deep percolation · ET": S + "AQUIFERS", + "lateral interflow, user [GWF]": S + "GWF", + "Dunne return flow": Y + "ch9_mesh_groundwater", + "node–bed exchange": Y + "ch9_mesh_groundwater", + "capillary rise · boundary ET": Y + "ch9_mesh_groundwater", + "junction · storage · divider · outfall": S + "JUNCTIONS", + "pumps · orifices · weirs · outlets · culverts": S + "PUMPS", + "treatment functions": S + "TREATMENT", + "treatment · diversion": S + "TREATMENT", + "dry weather flow": S + "DWF", + "user · interface files": S + "INFLOWS", + "control rules": S + "CONTROLS", +} + + +def ref_for(feature_id, text, title=None): + """The @ref target for a pill: by feature id, else by its text, else by its box title.""" + if feature_id and feature_id in FEATURE_REFS: + return FEATURE_REFS[feature_id] + if text in TITLE_REFS: + return TITLE_REFS[text] + if title in TITLE_REFS: + return TITLE_REFS[title] + return None diff --git a/docs/figures/src/engine/conceptual_map.py b/docs/figures/src/engine/conceptual_map.py new file mode 100644 index 000000000..abb0d214a --- /dev/null +++ b/docs/figures/src/engine/conceptual_map.py @@ -0,0 +1,250 @@ +"""The OpenSWMM process-and-formulation map — the conceptual diagram. + +One data model, five outputs. Compartments follow Rossman's four (atmosphere, +land surface, subsurface, conveyance) with the representations the modeller +now chooses between drawn side by side: lumped subcatchments next to the 2D +mesh, the per-subcatchment two-zone aquifer next to the two-layer aquifer on +the mesh. Every process box lists its alternatives as status pills coloured +from docs/figures/status.py, so the diagram cannot disagree with the badges +in the text. Fluxes are labelled arrows. + +Variants hide nothing — a compartment outside the variant's scope is drawn +ghosted so the reader sees where the zoom sits. +""" +from __future__ import annotations + +REQUIRES = () + +# ── data model ────────────────────────────────────────────────────────────── + +# id: (title, x, y_top, w, h, fill-key) in tenths of an inch on a 100 x 94 canvas +CANVAS = (10.0, 9.4) +COMPARTMENTS = { + "atm": ("ATMOSPHERE", 2, 89.5, 87, 9.8, "atm"), + "land_sub": ("LAND SURFACE · subcatchments (lumped)", 2, 76.7, 46, 24, "land"), + "land_mesh": ("LAND SURFACE · 2D mesh (distributed)", 52, 76.7, 37, 24, "land"), + "sub_2z": ("SUBSURFACE · two-zone aquifer per subcatchment", 2, 49.7, 46, 13.5, "sub"), + "sub_mesh": ("SUBSURFACE · two-layer aquifer on the mesh", 52, 49.7, 37, 13.5, "sub"), + "conv": ("CONVEYANCE · 1D node–link network", 2, 33.2, 87, 25, "conv"), + "out": ("OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage", + 2, 5.2, 87, 3.0, "out"), +} + +# (compartment, title, [(pill text, feature id | None), ...]) +PROCESSES = [ + ("atm", "Precipitation", [("rain gages", None), ("rain · snow split (SCF)", "snowmelt.degree_day"), + ("scale factors", "climate.precip_scaling")]), + ("atm", "Climate", [("temperature", None), ("evaporation: constant · monthly · series · Hargreaves · file", None), + ("wind", None), ("humidity · dew point", "climate.humidity_dewpoint"), + ("prescribed PET (API)", "climate.pet_forcing")]), + + ("land_sub", "Snowmelt", [("degree-day · heat budget · areal depletion", "snowmelt.degree_day")]), + ("land_sub", "Runoff", [("nonlinear reservoir", "runoff.subcatchment"), ("depression storage", None), + ("routing to another subcatchment", None)]), + ("land_sub", "Infiltration", [("Horton", "infiltration.horton"), ("modified Horton", "infiltration.mod_horton"), + ("Green-Ampt", "infiltration.green_ampt"), + ("modified Green-Ampt", "infiltration.mod_green_ampt"), + ("curve number", "infiltration.curve_number")]), + ("land_sub", "LID controls", [("layered units (8 types)", "lid.layered"), + ("LID as storage nodes", "lid.storage_node"), + ("detailed output", "lid.detailed_output")]), + ("land_sub", "Surface quality", [("buildup · washoff by land use", "quality.buildup_washoff"), + ("street sweeping", None), ("MSX species", "reactions.bw_msx")]), + + ("land_mesh", "Rain on the mesh", [("natural neighbour", "rain.mesh_natural_neighbour"), ("system", None)]), + ("land_mesh", "Per-cell infiltration", [("Horton · Green-Ampt · CN · constant", "infiltration.mesh_per_cell"), + ("→ lost · subcatchment aquifer · mesh aquifer", None)]), + ("land_mesh", "Overland flow", [("local inertial", "overland2d.local_inertial"), + ("full shallow water", "overland2d.full_swe"), + ("diffusive wave", "overland2d.diffusive_wave"), + ("IMEX / CVODE", "overland2d.imex")]), + ("land_mesh", "Mesh and closure", [("triangles", "overland2d.mesh.triangles"), ("quads", "overland2d.mesh.quads"), + ("flat cells", "overland2d.cell_closure.flat"), + ("VFR closure", "overland2d.cell_closure.vfr")]), + ("land_mesh", "Surface quality · transport", [("coverages · buildup · washoff", "quality.mesh_surface"), + ("species on the mesh", "transport.mesh_2d")]), + ("land_mesh", "Backends", [("CPU", "backend.2d.cpu"), ("OpenMP", "backend.2d.omp"), + ("CUDA · HIP · SYCL", "backend.2d.cuda"), ("Metal", "backend.2d.metal")]), + + ("sub_2z", "Two-zone aquifer", [("unsaturated + saturated zone", "groundwater.two_zone"), + ("percolation · deep percolation · ET", None), + ("lateral interflow, user [GWF]", None)]), + ("sub_2z", "Groundwater transport", [("advection–dispersion · heat", "groundwater.transport")]), + + ("sub_mesh", "Two-layer aquifer", [("Gardner", "groundwater.soil.gardner"), ("Russo", "groundwater.soil.russo"), + ("Brooks–Corey", "groundwater.soil.brooks_corey"), + ("van Genuchten", "groundwater.soil.van_genuchten"), + ("closed form · enslaved · σ column", "groundwater.mesh_two_layer"), + ("Dunne return flow", None), ("node–bed exchange", None), + ("capillary rise · boundary ET", None), + ("per-subcatchment mode", "groundwater.mesh_per_subcatch")]), + + ("conv", "Nodes", [("junction · storage · divider · outfall", None), ("virtual junction", "junctions.virtual"), + ("inlet junction", "junctions.inlet")]), + ("conv", "Links", [("conduits, 26 sections", "xsect.tabulated"), ("street · dummy", "xsect.street"), + ("Chebyshev irregular", "xsect.chebyshev_irregular"), + ("pumps · orifices · weirs · outlets · culverts", None), + ("storage shapes", "storage.shapes"), ("HEC-22 inlets", "inlets.link_attribute")]), + ("conv", "Flow routing", [("steady", "routing.steady"), ("kinematic wave", "routing.kinwave"), + ("dynamic wave", "routing.dynwave"), ("finite volume", "routing.fv"), + ("local time stepping", "fv.lts"), ("1D GPU backend", "backend.1d.gpu")]), + ("conv", "Pressurisation", [("EXTRAN", "pressurisation.extran"), ("slot", "pressurisation.slot"), + ("dynamic slot", "pressurisation.dynamic_slot"), ("TPA", "pressurisation.tpa"), + ("FV: slot", "fv.closure.slot"), ("FV: TPA", "fv.closure.tpa"), + ("FV: implicit head", "fv.pressurized_implicit"), + ("unsteady friction", "friction.unsteady_vitkovsky")]), + ("conv", "Node solution", [("explicit continuity", "routing.node_continuity.explicit"), + ("semi-implicit continuity", "routing.node_continuity.semi_implicit"), + ("Anderson acceleration", "routing.anderson"), + ("FV_NODE_* keys", "fv.node_coupling_keys")]), + ("conv", "Transport", [("CSTR", "transport.cstr"), ("Eulerian ARD", "transport.ard"), + ("Lagrangian LARD", "transport.lard"), ("random-walk dispersion", "transport.rwpt"), + ("first-order decay", "reactions.first_order"), ("MSX reactions", "reactions.msx"), + ("water age", "water_age"), ("heat", "heat"), ("sediment", "sediment"), + ("treatment functions", None)]), + ("conv", "Inflows", [("dry weather flow", None), ("RDII: RTK", "rdii.rtk"), ("RDII: IA decay", "rdii.ia_decay"), + ("user · interface files", None), ("control rules", None)]), +] + +# (src compartment, x, dst compartment, x, text, kind, both) — vertical arrows between +# the facing edges of two compartments, at absolute x positions +VERTICAL_FLUXES = [ + ("atm", 14, "land_sub", 14, "precipitation · snowmelt", "water", False), + ("land_sub", 34, "atm", 34, "evaporation · ET", "water", False), + ("atm", 62, "land_mesh", 62, "rain on cells", "water", False), + ("land_mesh", 80, "atm", 80, "evaporation on cells", "water", False), + ("land_sub", 16, "sub_2z", 16, "infiltration", "water", False), + ("land_mesh", 62, "sub_mesh", 62, "per-cell infiltration", "water", False), + ("sub_mesh", 80, "land_mesh", 80, "Dunne return flow · capillary rise", "water", False), + ("sub_2z", 16, "conv", 16, "GW interflow (user [GWF])", "water", False), + ("sub_mesh", 72, "conv", 72, "node–bed exchange", "water", True), + ("conv", 45.5, "out", 45.5, None, "water", False), +] +# corridors: runoff to nodes (centre gap) and the two 1D↔2D pathways (right margin) +CORRIDOR_FLUXES = [ + ("centre", 50.0, "land_sub", "conv", "runoff → outlet node", "water", False), + ("right", 92.6, "land_mesh", "conv", "1D ↔ 2D exchange at vertices / cells", "coupling", True), + ("right", 96.8, "land_mesh", "conv", "street inlet capture", "coupling", False), +] +HORIZONTAL_FLUXES = [ + ("land_sub", "land_mesh", 0.86, "runoff → cell", "water"), +] + +VARIANTS = { + "eng_conceptual_map": {"keep": set(COMPARTMENTS), "title": "OpenSWMM: compartments, processes and the formulations that represent them"}, + "hydrology_conceptual_map": {"keep": {"atm", "land_sub", "land_mesh", "sub_2z", "sub_mesh"}, + "title": "Hydrology: atmosphere, land surface and subsurface representations"}, + "hydraulics_conceptual_map": {"keep": {"land_mesh", "conv", "out"}, + "title": "Hydraulics: the 1D network, the 2D surface and their coupling"}, + "quality_conceptual_map": {"keep": {"land_sub", "land_mesh", "conv", "out"}, + "title": "Water quality: buildup, washoff, transport and reactions across the compartments"}, + "hydraulics_conceptual_1d2d": {"keep": {"land_mesh", "conv"}, + "title": "One-dimensional network and two-dimensional surface: the exchange pathways"}, +} +GHOST = 0.22 + + +def _comp_box(cid): + _, x, ytop, w, h, _ = COMPARTMENTS[cid] + return x, ytop - h, w, h + + +def _edge_point(cid, rel_x, side): + x, y, w, h = _comp_box(cid) + return (x + rel_x * w, y + h if side == "top" else y) + + +def _draw(variant: str): + """Returns (fig, ax, hotspots); hotspots are (x0, y0, x1, y1, ref, label) in data units.""" + import primitives as P + import refs + import style + keep = VARIANTS[variant]["keep"] + fig, ax = P.canvas(*CANVAS) + alpha_of = lambda cid: 1.0 if cid in keep else GHOST # noqa: E731 + hotspots = [] + + # compartments + for cid, (title, x, ytop, w, h, fill) in COMPARTMENTS.items(): + a = alpha_of(cid) + P.rounded(ax, x, ytop - h, w, h, fc=P.COMP_FILL[fill], ec=P.COMP_EDGE, lw=1.0, r=0.8, alpha=a, z=0) + P.label(ax, x + 1.0, ytop - (0.55 if cid != "out" else 0.75), title, size=8.2, weight="bold", + color=style.INK, alpha=a, z=3) + + # processes: stacked inside each compartment, two columns for the wide ones + by_comp = {} + for cid, title, alts in PROCESSES: + by_comp.setdefault(cid, []).append((title, alts)) + for cid, procs in by_comp.items(): + a = alpha_of(cid) + x, y, w, h = _comp_box(cid) + ncol = 3 if cid == "conv" else (2 if cid in ("atm", "land_sub", "land_mesh", "sub_mesh") else 2) + if cid in ("sub_2z",): + ncol = 2 + gap = 0.9 + col_w = (w - 2.0 - gap * (ncol - 1)) / ncol + cols_y = [y + h - 3.0] * ncol + for i, (title, alts) in enumerate(procs): + c = i % ncol if cid != "sub_mesh" else 0 + if cid == "sub_mesh": + col_w = w - 2.0 + cx = x + 1.0 + c * (col_w + gap) + top = cols_y[c] + title_h = 2.0 + P.label(ax, cx + 0.6, top - 0.35, title, size=7.6, weight="bold", alpha=a, z=4) + pills = [] + used = P.pill_row(ax, cx + 0.6, top - title_h, col_w - 1.2, alts, size=6.6, alpha=a, z=4, out=pills) + box_h = title_h + used + 0.7 + P.rounded(ax, cx, top - box_h, col_w, box_h, fc=P.BOX_FILL, ec=P.BOX_EDGE, lw=0.8, r=0.5, + alpha=a, z=1) + if title in refs.TITLE_REFS: + hotspots.append((cx, top - title_h, cx + col_w, top, refs.TITLE_REFS[title], title)) + for text, fid, px, py, pw, ph in pills: + ref = refs.ref_for(fid, text, title) + if ref: + hotspots.append((px, py, px + pw, py + ph, ref, text)) + cols_y[c] = top - box_h - 0.8 + + # fluxes + for src, x0, dst, x1, text, kind, both in VERTICAL_FLUXES: + a = min(alpha_of(src), alpha_of(dst)) + sx, sy, sw, sh = _comp_box(src) + dx, dy, dw, dh = _comp_box(dst) + downward = sy > dy + p0 = (x0, sy if downward else sy + sh) + p1 = (x1, dy + dh if downward else dy) + P.arrow(ax, p0, p1, kind=kind, text=text, both=both, alpha=a, z=2) + for corridor, xc, src, dst, text, kind, both in CORRIDOR_FLUXES: + a = min(alpha_of(src), alpha_of(dst)) + sx, sy, sw, sh = _comp_box(src) + dx, dy, dw, dh = _comp_box(dst) + if corridor == "centre": + ax.plot([sx + sw, xc], [sy + 3.0, sy + 3.0], color=P.ARROW[kind], lw=1.2, alpha=a, zorder=2) + P.arrow(ax, (xc, sy + 3.0), (xc, dy + dh), kind=kind, text=text, alpha=a, z=2, rotation=90) + else: + P.arrow(ax, (xc, sy), (xc, dy + dh), kind=kind, text=text, both=both, alpha=a, z=2, + rotation=90, size=6.4) + ax.plot([sx + sw, xc], [sy, sy], color=P.ARROW[kind], lw=1.2, alpha=a, zorder=2) + ax.plot([dx + dw, xc], [dy + dh, dy + dh], color=P.ARROW[kind], lw=1.2, alpha=a, zorder=2) + for src, dst, ry, text, kind in HORIZONTAL_FLUXES: + a = min(alpha_of(src), alpha_of(dst)) + sx, sy, sw, sh = _comp_box(src) + dx, dy, dw, dh = _comp_box(dst) + P.arrow(ax, (sx + sw, sy + ry * sh), (dx, dy + ry * dh), kind=kind, text=text or None, alpha=a, z=2, + text_offset=(0, 1.1), size=6.4) + + # title band: title left, status legend and arrow key right + P.label(ax, 2, 93.6, VARIANTS[variant]["title"], size=9.6, weight="bold") + P.legend(ax, 64, 93.9, size=6.6, title="Status of each alternative:") + P.label(ax, 89, 0.6, "arrows: water (blue) · 1D–2D exchange (orange)", size=6.4, color=style.MUTED, + ha="right", va="bottom") + return fig, ax, hotspots + + +def build(sink): + for variant in VARIANTS: + if variant in sink.expected: + fig, ax, hotspots = _draw(variant) + for x0, y0, x1, y1, ref, label in hotspots: + sink.hotspot(variant, ax, x0, y0, x1, y1, ref, label) + sink.save(fig, variant) diff --git a/docs/figures/src/engine/object_sketch.py b/docs/figures/src/engine/object_sketch.py new file mode 100644 index 000000000..040ab2bd2 --- /dev/null +++ b/docs/figures/src/engine/object_sketch.py @@ -0,0 +1,179 @@ +"""OpenSWMM's object model of a drainage system — the plan-view sketch. + +Replaces the 338 × 257 px legacy "conceptual model of a stormwater drainage +system" bitmap that all four Chapter 1 pages embedded. Same idea (every +object type placed once in a small network) with the objects the legacy +sketch predates: a virtual junction splicing a surveyed reach, an inlet +junction on a street conduit, and a 2D mesh patch coupled to the network. +Synthetic geometry; no model is run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +CANVAS = (10.0, 5.6) + +# clickable regions (x0, y0, x1, y1) in canvas units -> the Engine Manual's grammar section +S = "engine_manual_sect_" +HOTSPOTS = [ + (9, 48.3, 24, 51.7, S + "RAINGAGES", "Rain gage"), + (4, 28.5, 24, 46.5, S + "SUBCATCHMENTS", "Subcatchment S1"), + (24, 34.5, 44, 50.5, S + "SUBCATCHMENTS", "Subcatchment S2"), + (15, 27.5, 30, 33.5, S + "JUNCTIONS", "Junction"), + (30, 22.0, 40, 25.5, S + "CONDUITS", "Conduit"), + (39, 23.0, 50, 29.0, S + "VIRTUAL_JUNCTIONS", "Virtual junction"), + (55, 31.5, 82, 36.5, S + "INLET_JUNCTIONS", "Inlet junction"), + (59, 36.5, 67, 43.5, S + "STREETS", "Street conduit"), + (72, 21.5, 80, 27.5, S + "DIVIDERS", "Divider"), + (81, 20.0, 90, 27.5, S + "WEIRS", "Weir"), + (69, 15.5, 80, 20.5, S + "ORIFICES", "Orifice"), + (76, 8.5, 84, 14.5, S + "STORAGE", "Storage unit"), + (84, 8.5, 92, 14.5, S + "PUMPS", "Pump"), + (92, 17.5, 100, 22.5, S + "OUTFALLS", "Outfall"), + (45, 3.5, 67, 18.5, S + "2D_TRIANGLES", "2D mesh"), + (47, 18.5, 56, 23.5, S + "2D_VERTEX_NODE_MAP", "1D–2D exchange"), +] + + +def _subcatchment(ax, pts, label, P, style): + poly = np.array(pts) + ax.fill(poly[:, 0], poly[:, 1], fc="#e9efe0", ec="#6f8a4f", lw=1.0, hatch="//", zorder=1, alpha=0.9) + cx, cy = poly[:, 0].mean(), poly[:, 1].mean() + ax.plot([cx], [cy], marker="s", ms=4, color="#6f8a4f", zorder=3) + P.label(ax, cx, cy - 1.2, label, size=7, color="#4f6338", ha="center", va="top", z=4) + return cx, cy + + +def _node(ax, x, y, kind, P, style): + ink = style.INK + if kind == "junction": + ax.plot([x], [y], marker="o", ms=6, mfc=style.WATER, mec=ink, mew=0.8, zorder=5) + elif kind == "virtual": + ax.plot([x], [y], marker="o", ms=5, mfc="white", mec=style.WATER, mew=1.2, zorder=5) + elif kind == "inlet": + ax.plot([x], [y], marker="s", ms=7, mfc="#ffd8a8", mec=ink, mew=0.8, zorder=5) + ax.plot([x - 0.5, x + 0.5], [y, y], color=ink, lw=0.7, zorder=6) + ax.plot([x, x], [y - 0.5, y + 0.5], color=ink, lw=0.7, zorder=6) + elif kind == "divider": + ax.plot([x], [y], marker="D", ms=6, mfc="#cbd7f2", mec=ink, mew=0.8, zorder=5) + elif kind == "storage": + P.rounded(ax, x - 1.6, y - 1.0, 3.2, 2.0, fc="#cfe3f7", ec=ink, lw=0.9, r=0.4, z=5) + elif kind == "outfall": + ax.plot([x], [y], marker="v", ms=8, mfc="#9fb9d8", mec=ink, mew=0.8, zorder=5) + + +def _link(ax, p0, p1, kind, style, lw=2.0): + x = [p0[0], p1[0]] + y = [p0[1], p1[1]] + if kind == "conduit": + ax.plot(x, y, color="#5aa552", lw=lw, zorder=2, solid_capstyle="round") + elif kind == "street": + ax.plot(x, y, color="#8f8f8f", lw=lw + 1.6, zorder=2, solid_capstyle="round") + ax.plot(x, y, color="#e8e8e8", lw=lw - 1.0, zorder=2.1, ls=(0, (3, 2))) + elif kind == "pump": + ax.plot(x, y, color="#5aa552", lw=lw, zorder=2) + mx, my = (x[0] + x[1]) / 2, (y[0] + y[1]) / 2 + ax.plot([mx], [my], marker="^", ms=8, mfc="#ffffff", mec=style.INK, mew=0.9, zorder=4) + elif kind == "weir": + ax.plot(x, y, color="#5aa552", lw=lw, zorder=2) + mx, my = (x[0] + x[1]) / 2, (y[0] + y[1]) / 2 + ax.plot([mx - 0.6, mx + 0.6], [my + 0.45, my + 0.45], color=style.INK, lw=1.6, zorder=4) + ax.plot([mx - 0.6, mx + 0.6], [my - 0.45, my - 0.45], color=style.INK, lw=1.6, zorder=4) + elif kind == "orifice": + ax.plot(x, y, color="#5aa552", lw=lw, zorder=2) + mx, my = (x[0] + x[1]) / 2, (y[0] + y[1]) / 2 + ax.plot([mx], [my], marker="o", ms=8, mfc="#ffffff", mec=style.INK, mew=0.9, zorder=4) + ax.plot([mx], [my], marker="o", ms=3, mfc=style.INK, mec=style.INK, zorder=4.1) + + +def _mesh(ax, x0, y0, w, h, nx, ny, P, style): + xs = np.linspace(x0, x0 + w, nx + 1) + ys = np.linspace(y0, y0 + h, ny + 1) + for j in range(ny): + for i in range(nx): + a, b = (xs[i], ys[j]), (xs[i + 1], ys[j]) + c, d = (xs[i + 1], ys[j + 1]), (xs[i], ys[j + 1]) + if (i + j) % 2: + tris = [(a, b, c), (a, c, d)] + else: + tris = [(a, b, d), (b, c, d)] + for t in tris: + pts = np.array(t) + depth = 0.18 + 0.5 * np.exp(-((pts[:, 0].mean() - (x0 + w * 0.35)) ** 2 + (pts[:, 1].mean() - (y0 + h * 0.5)) ** 2) / 14) + ax.fill(pts[:, 0], pts[:, 1], fc=(0.16, 0.47, 0.84, depth), ec="#7a9bc4", lw=0.5, zorder=1.5) + + +def _draw(): + import primitives as P + import style + + fig, ax = P.canvas(*CANVAS) + + # subcatchments with a rain gage + s1 = _subcatchment(ax, [(4, 42), (18, 46), (24, 38), (16, 30), (6, 33)], "Subcatchment S1", P, style) + s2 = _subcatchment(ax, [(24, 48), (40, 50), (44, 42), (34, 36), (26, 39)], "Subcatchment S2", P, style) + ax.plot([12], [50], marker="*", ms=12, mfc="#ffd23f", mec=style.INK, mew=0.7, zorder=5) + P.label(ax, 14, 50, "Rain gage", size=7, va="center", z=4) + + # network + J1, J2, J3, J4 = (24, 30), (36, 26), (52, 24), (64, 22) + VJ = (44, 25) + D = (76, 24) + ST = (80, 12) + OUT = (94, 20) + IJ = (58, 34) + _link(ax, s1[0:2] if False else (16, 30), J1, "conduit", style, lw=1.2) # subcatchment outlet + _link(ax, J1, J2, "conduit", style) + _link(ax, J2, VJ, "conduit", style) + _link(ax, VJ, J3, "conduit", style) + _link(ax, J3, J4, "conduit", style) + _link(ax, J4, D, "conduit", style) + _link(ax, D, OUT, "weir", style) + _link(ax, D, ST, "orifice", style) + _link(ax, ST, (94, 12), "pump", style) + _link(ax, (94, 12), OUT, "conduit", style) + _link(ax, (62, 40), IJ, "street", style) + _link(ax, IJ, J4, "conduit", style, lw=1.2) + ax.plot([34, 36], [36, 26], color="#6f8a4f", lw=1.0, ls=(0, (2, 2)), zorder=2) # S2 outlet + ax.plot([16, 24], [30, 30], color="#6f8a4f", lw=1.0, ls=(0, (2, 2)), zorder=2) # S1 outlet + + for pt, kind in ((J1, "junction"), (J2, "junction"), (J3, "junction"), (J4, "junction"), + (VJ, "virtual"), (D, "divider"), (ST, "storage"), (OUT, "outfall"), (IJ, "inlet")): + _node(ax, *pt, kind, P, style) + + # 2D mesh patch coupled at J3 (vertex coupling) + _mesh(ax, 46, 6, 20, 12, 5, 3, P, style) + ax.plot([J3[0], 54], [J3[1], 18], color="#eb6834", lw=1.4, ls=(0, (3, 1.5)), zorder=3) + ax.plot([54], [18], marker="o", ms=4, mfc="#eb6834", mec="#eb6834", zorder=4) + + # labels + lab = dict(size=7, z=6) + P.label(ax, J1[0] - 1.2, J1[1] + 1.0, "Junction", ha="right", va="bottom", **lab) + P.label(ax, J2[0], J2[1] - 1.4, "Conduit", ha="center", va="top", **lab) + P.label(ax, VJ[0], VJ[1] + 1.3, "Virtual junction", ha="center", va="bottom", **lab) + P.label(ax, IJ[0] + 1.4, IJ[1], "Inlet junction on a street", va="center", **lab) + P.label(ax, 62, 41.2, "Street conduit", ha="center", va="bottom", **lab) + P.label(ax, D[0], D[1] + 1.4, "Divider", ha="center", va="bottom", **lab) + P.label(ax, 85, 25.2, "Weir", ha="center", va="bottom", **lab) + P.label(ax, 76.6, 18.0, "Orifice", ha="right", va="center", **lab) + P.label(ax, ST[0], ST[1] - 1.6, "Storage unit", ha="center", va="top", **lab) + P.label(ax, 87, 10.6, "Pump", ha="center", va="top", **lab) + P.label(ax, OUT[0] + 1.4, OUT[1], "Outfall", va="center", **lab) + P.label(ax, 56, 4.6, "2D mesh (triangles · quads) coupled to junction J3", ha="center", va="top", **lab) + P.label(ax, 50.5, 20.2, "1D ↔ 2D exchange", size=6.5, color="#eb6834", ha="right", va="bottom", z=6, + style_="italic") + + P.label(ax, 2, 55.0, "Objects of an OpenSWMM model", size=9.6, weight="bold") + P.label(ax, 2, 52.6, "hydrology: rain gages and subcatchments, with aquifers and snow packs beneath them · " + "hydraulics: nodes, links and a 2D mesh · quality: pollutants and land uses on the subcatchments", + size=6.4, color=style.MUTED, va="top") + return fig, ax + + +def build(sink): + fig, ax = _draw() + for x0, y0, x1, y1, ref, label in HOTSPOTS: + sink.hotspot("eng_object_sketch", ax, x0, y0, x1, y1, ref, label) + sink.save(fig, "eng_object_sketch") diff --git a/docs/figures/src/engine/process_flow.py b/docs/figures/src/engine/process_flow.py new file mode 100644 index 000000000..90296b2b3 --- /dev/null +++ b/docs/figures/src/engine/process_flow.py @@ -0,0 +1,144 @@ +"""Processes modelled by OpenSWMM — the replacement for the EPA "Figure 1-3". + +The legacy chart (precipitation → snowmelt → initial abstraction → surface +runoff → LID → washoff → routing → treatment) extended with the distributed +branch (rain on the mesh → 2D overland flow → 1D↔2D exchange), the two +subsurface representations, inlet capture, and the transport chain +(transport engine → reactions → age / heat). Alternatives are status pills +from docs/figures/status.py. Cited by all four Chapter 1 pages. + +Layout: four columns feed one full-width routing band, so every arrow into +routing is a vertical drop and nothing crosses a box. +""" +from __future__ import annotations + +REQUIRES = () + +CANVAS = (10.0, 7.2) + +# id: (title, x, y_top, w, [(pill, feature id | None), ...]) +BOXES = { + # column 1 — lumped hydrology chain + "precip": ("Precipitation", 2, 64, 22, [("rain · snow", None), ("scale factors", "climate.precip_scaling")]), + "snow": ("Snowmelt", 2, 56.5, 22, [("degree-day · areal depletion", "snowmelt.degree_day")]), + "abstract": ("Initial abstraction · evaporation", 2, 49, 22, [("depression storage", None)]), + "runoff": ("Surface runoff", 2, 41.5, 22, [("nonlinear reservoir", "runoff.subcatchment"), + ("Horton · Green-Ampt · CN", "infiltration.horton")]), + "lid": ("LID controls", 2, 32.5, 22, [("layered units", "lid.layered"), ("storage nodes", "lid.storage_node")]), + "washoff": ("Washoff", 2, 25, 22, [("EMC · exponential · rating", "quality.buildup_washoff")]), + # column 2 — subsurface, and buildup beside washoff + "gw": ("Groundwater", 28, 53, 24, [("two-zone aquifer per subcatchment", "groundwater.two_zone"), + ("two-layer aquifer on the mesh", "groundwater.mesh_two_layer"), + ("groundwater transport", "groundwater.transport")]), + "buildup": ("Pollutant buildup", 28, 25, 20, [("land uses · sweeping", "quality.buildup_washoff")]), + # column 3 — distributed hydrology on the 2D mesh + "rainmesh": ("Rain on the mesh", 56, 64, 22, [("natural neighbour", "rain.mesh_natural_neighbour")]), + "overland": ("2D overland flow", 56, 56.5, 22, [("local inertial", "overland2d.local_inertial"), + ("full shallow water", "overland2d.full_swe"), + ("diffusive wave", "overland2d.diffusive_wave")]), + "infilcell": ("Per-cell infiltration · evaporation", 56, 47, 22, [("→ lost · subcatchment · mesh aquifer", None)]), + "surfq2d": ("2D surface quality", 56, 39, 22, [("coverages · buildup · washoff", "quality.mesh_surface")]), + # column 4 — external inflows and inlets + "inflows": ("External inflows", 81, 64, 17, [("dry weather flow", None), ("RDII: RTK", "rdii.rtk"), + ("RDII: IA decay", "rdii.ia_decay"), ("user · interface files", None)]), + "inlets": ("Street inlets", 86, 52, 12, [("HEC-22 link attribute", "inlets.link_attribute"), + ("inlet junction", "junctions.inlet")]), + # bands + "routing": ("Channel, pipe and storage routing", 2, 17, 96, [("steady", "routing.steady"), + ("kinematic wave", "routing.kinwave"), + ("dynamic wave", "routing.dynwave"), + ("finite volume", "routing.fv"), + ("EXTRAN · slot · dynamic slot", "pressurisation.slot"), + ("TPA", "pressurisation.tpa"), + ("virtual · inlet junctions", "junctions.virtual")]), + "transport": ("Transport and reactions", 2, 10, 96, [("CSTR", "transport.cstr"), ("ARD", "transport.ard"), + ("LARD", "transport.lard"), + ("first-order decay", "reactions.first_order"), + ("MSX", "reactions.msx"), ("water age", "water_age"), + ("heat", "heat"), ("sediment", "sediment"), + ("treatment · diversion", None)]), +} + +# vertical chains (src above dst, same column) +DROPS = [("precip", "snow"), ("snow", "abstract"), ("abstract", "runoff"), ("runoff", "lid"), ("lid", "washoff"), + ("rainmesh", "overland"), ("overland", "infilcell"), ("infilcell", "surfq2d")] +# (src, x, text, kind): vertical drops onto the routing band +TO_ROUTING = [("washoff", 13, None, "mass"), ("gw", 48, "interflow · node–bed exchange", "water"), + ("surfq2d", 67, "species on the mesh", "mass"), ("inflows", 83, "inflows", "water"), + ("inlets", 92, "inlet capture", "coupling")] +# (src, dst, text, kind): horizontals between columns (the short ones stay unlabelled) +ACROSS = [("abstract", "gw", None, "water"), + ("infilcell", "gw", None, "water"), + ("buildup", "washoff", None, "mass")] + + +def _draw(): + """Returns (fig, ax, hotspots); hotspots are (x0, y0, x1, y1, ref, label) in data units.""" + import primitives as P + import refs + import style + + fig, ax = P.canvas(*CANVAS) + geom = {} + hotspots = [] + for bid, (title, x, ytop, w, alts) in BOXES.items(): + P.label(ax, x + 0.6, ytop - 0.35, title, size=7.8, weight="bold", z=4) + pills = [] + used = P.pill_row(ax, x + 0.6, ytop - 2.0, w - 1.2, alts, size=6.6, z=4, out=pills) + h = 2.0 + used + 0.7 + P.rounded(ax, x, ytop - h, w, h, fc=P.BOX_FILL, ec=P.BOX_EDGE, lw=0.9, r=0.6, z=1) + geom[bid] = (x, ytop - h, w, h) + if title in refs.TITLE_REFS: + hotspots.append((x, ytop - 2.0, x + w, ytop, refs.TITLE_REFS[title], title)) + for text, fid, px, py, pw, ph in pills: + ref = refs.ref_for(fid, text, title) + if ref: + hotspots.append((px, py, px + pw, py + ph, ref, text)) + + def box(bid): + return geom[bid] + + for x, text in ((2, "lumped: subcatchments"), (28, "subsurface"), (56, "distributed: 2D mesh"), + (81, "inflows · inlets")): + P.label(ax, x, 66.6, text.upper(), size=6.8, color=style.MUTED, weight="bold") + + for src, dst in DROPS: + sx, sy, sw, sh = box(src) + dx, dy, dw, dh = box(dst) + P.arrow(ax, (sx + sw / 2, sy), (dx + dw / 2, dy + dh), kind="water", lw=1.1) + rx, ry, rw, rh = box("routing") + for src, x, text, kind in TO_ROUTING: + sx, sy, sw, sh = box(src) + P.arrow(ax, (x, sy), (x, ry + rh), kind=kind, text=text, size=6.3, lw=1.1, rotation=90) + # 1D <-> 2D exchange: a corridor between the subsurface and mesh columns + ox, oy, ow, oh = box("overland") + xc = 54.0 + ax.plot([ox, xc], [oy + oh / 2, oy + oh / 2], color=P.ARROW["coupling"], lw=1.1, zorder=2) + P.arrow(ax, (xc, oy + oh / 2), (xc, ry + rh), kind="coupling", text="1D ↔ 2D exchange", both=True, + size=6.3, lw=1.1, rotation=90) + for src, dst, text, kind in ACROSS: + sx, sy, sw, sh = box(src) + dx, dy, dw, dh = box(dst) + ymid = sy + sh / 2 + if sx < dx: + P.arrow(ax, (sx + sw, ymid), (dx, ymid), kind=kind, text=text, size=6.3, lw=1.1, text_offset=(0, 1.0)) + else: + P.arrow(ax, (sx, ymid), (dx + dw, ymid), kind=kind, text=text, size=6.3, lw=1.1, text_offset=(0, 1.0)) + + tx, ty, tw, th = box("transport") + P.arrow(ax, (50, ry), (50, ty + th), kind="water", lw=1.1) + P.rounded(ax, 2, 1.0, 96, 2.8, fc=P.COMP_FILL["out"], ec=P.COMP_EDGE, lw=0.9, r=0.8, z=1) + P.arrow(ax, (50, ty), (50, 3.8), kind="water", lw=1.1) + P.label(ax, 50, 2.4, "OUTFALLS · receiving water", size=7.8, weight="bold", ha="center", va="center", z=4) + hotspots.append((2, 1.0, 98, 3.8, refs.TITLE_REFS["OUTFALLS · receiving water"], "Outfalls")) + P.legend(ax, 2, 71.4, size=6.4, title="Status of each alternative:") + P.label(ax, 98, 69.0, "arrows: water (blue) · constituent mass (violet) · 1D–2D exchange (orange)", + size=6.4, color=style.MUTED, ha="right", va="bottom") + return fig, ax, hotspots + + +def build(sink): + fig, ax, hotspots = _draw() + for x0, y0, x1, y1, ref, label in hotspots: + sink.hotspot("eng_process_flow", ax, x0, y0, x1, y1, ref, label) + sink.save(fig, "eng_process_flow") diff --git a/docs/figures/src/hydraulics/ch3_virtual_junction.py b/docs/figures/src/hydraulics/ch3_virtual_junction.py new file mode 100644 index 000000000..d0157921d --- /dev/null +++ b/docs/figures/src/hydraulics/ch3_virtual_junction.py @@ -0,0 +1,66 @@ +"""A regular junction and a virtual junction at a grade break (hydraulics +Figure 3-10). + +Left: the node-link scheme places a manhole with MIN_SURFAREA storage at +every conduit end, so a surveyed reach chained from short segments carries +a stagnation volume and a head update at each splice. Right: a virtual +junction is an interior point — zero storage, continuous invert — and +momentum is carried through it. Profile view, synthetic geometry; replaces +the watermarked placeholder. +""" +from __future__ import annotations + +REQUIRES = () + + +def _panel(ax, style, virtual): + from matplotlib.patches import Rectangle, FancyArrowPatch + xs, zin = [0, 4, 8], [2.0, 1.0, 0.7] # invert with a grade break at x = 4 + crown = [z + 1.0 for z in zin] + ax.fill_between(xs, [z - 0.9 for z in zin], zin, color=style.SOIL, zorder=0) + ax.fill_between(xs, zin, crown, color=style.PIPE_FILL, zorder=1) + ax.plot(xs, zin, color=style.INK, lw=1.8, zorder=2) + ax.plot(xs, crown, color=style.MUTED, lw=1.2, ls=(0, (4, 2)), zorder=2) + # water + wl = [2.45, 1.55, 1.25] + ax.fill_between(xs, zin, wl, color=style.WATER, alpha=0.25, zorder=1.5) + ax.plot(xs, wl, color=style.WATER, lw=1.2, zorder=2) + if not virtual: + ax.add_patch(Rectangle((3.7, 1.0), 0.6, 2.3, fc="#e9e9e9", ec=style.INK, lw=1.3, zorder=3)) + ax.fill_between([3.7, 4.3], 1.0, 1.55, color=style.WATER, alpha=0.35, zorder=3.5) + ax.text(4.0, 3.42, "manhole: MIN_SURFAREA storage,\nits own head update every trial", ha="center", + va="bottom", fontsize=8, color=style.INK) + ax.annotate("", xy=(4.0, 1.0), xytext=(4.0, 0.25), arrowprops=dict(arrowstyle="-|>", color=style.MUTED, lw=1.0)) + ax.text(4.0, 0.12, "stagnation volume\nbelow the outlet invert", ha="center", va="top", fontsize=7.6, + color=style.MUTED) + ax.text(1.0, 3.2, "conduit 1", fontsize=8, color=style.MUTED) + ax.text(6.2, 2.0, "conduit 2", fontsize=8, color=style.MUTED) + else: + ax.plot([4.0], [1.0], marker="o", ms=7, mfc="white", mec=style.WATER, mew=1.6, zorder=4) + ax.text(4.0, 3.42, "virtual junction: zero storage,\ncontinuous invert, no head unknown", ha="center", + va="bottom", fontsize=8, color=style.INK) + ax.add_patch(FancyArrowPatch((1.8, 1.95), (6.2, 1.05), arrowstyle="-|>", mutation_scale=16, + color=style.WATER, lw=2.2, zorder=5)) + ax.text(4.0, 2.05, "momentum flux carried through", ha="center", fontsize=8.5, color=style.WATER, zorder=6, + bbox=dict(boxstyle="round,pad=0.15", fc=style.SURFACE, ec="none", alpha=0.9)) + ax.text(1.0, 3.2, "one surveyed reach", fontsize=8, color=style.MUTED) + ax.text(4.9, 0.45, "the solver sees one conduit;\nthe file keeps two", fontsize=7.6, color=style.MUTED) + ax.set_xlim(-0.2, 8.4) + ax.set_ylim(-0.6, 4.4) + ax.axis("off") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, 2, figsize=(9.0, 3.9), sharey=True) + fig.patch.set_facecolor(style.SURFACE) + for ax, virtual, title in zip(axes, (False, True), ("Regular junction at the grade break", "Virtual junction at the grade break")): + _panel(ax, style, virtual) + ax.set_title(title, fontsize=9.5, color=style.INK, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch3_virtual_junction") diff --git a/docs/figures/src/hydraulics/ch5_storage_shapes.py b/docs/figures/src/hydraulics/ch5_storage_shapes.py new file mode 100644 index 000000000..a2589028b --- /dev/null +++ b/docs/figures/src/hydraulics/ch5_storage_shapes.py @@ -0,0 +1,70 @@ +"""The four standard storage-unit solids of hydraulics Table 5-14, whose +depth–area relation the engine evaluates as A(Y) = a0 + a1 Y + a2 Y²: +elliptical cylinder, elliptical paraboloid, elliptical cone and rectangular +pyramid. Drawn as shaded surfaces with the dimensions the table names +(major and minor axis or length and width at the top, depth). One tile per +manifest row so each sits in its table cell; replaces 67–93 px icons. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +SHAPES = ["hydraulics_ch5_storage_cylinder", "hydraulics_ch5_storage_paraboloid", + "hydraulics_ch5_storage_cone", "hydraulics_ch5_storage_pyramid"] + + +def _surface(kind, n=40): + """(X, Y, Z) of the solid's side wall, depth Z from 0 (bottom) to 1 (top).""" + z = np.linspace(0.0, 1.0, n) + if kind == "pyramid": + # rectangular pyramid: half-widths grow linearly from a small base to the top + u = np.linspace(0, 4, 4 * n + 1) # perimeter parameter, 4 sides + side = np.floor(u).astype(int) % 4 + f = u - np.floor(u) + px = np.select([side == 0, side == 1, side == 2, side == 3], [f * 2 - 1, 1.0, 1 - f * 2, -1.0]) + py = np.select([side == 0, side == 1, side == 2, side == 3], [-1.0, f * 2 - 1, 1.0, 1 - f * 2]) + Z, U = np.meshgrid(z, u, indexing="ij") + r = 0.15 + 0.85 * Z + X = r * px[np.newaxis, :] * 1.3 + Y = r * py[np.newaxis, :] * 0.9 + return X, Y, Z + t = np.linspace(0, 2 * np.pi, 2 * n) + Z, T = np.meshgrid(z, t, indexing="ij") + if kind == "cylinder": + r = np.ones_like(Z) + elif kind == "paraboloid": + r = np.sqrt(Z) # A ∝ Y + else: # cone: half-widths grow linearly + r = 0.1 + 0.9 * Z + return r * np.cos(T) * 1.3, r * np.sin(T) * 0.9, Z + + +def _tile(kind, title, style): + import matplotlib.pyplot as plt + from matplotlib.colors import LightSource + fig = plt.figure(figsize=(2.9, 2.2)) + fig.patch.set_facecolor(style.SURFACE) + ax = fig.add_subplot(111, projection="3d") + X, Y, Z = _surface(kind) + ls = LightSource(azdeg=225, altdeg=40) + rgb = ls.shade(Z, cmap=plt.cm.Blues, vert_exag=0.3, blend_mode="soft") + ax.plot_surface(X, Y, Z, facecolors=rgb, rstride=1, cstride=1, linewidth=0, antialiased=True, alpha=0.95) + # the water-surface outline at the top + ax.plot(X[-1], Y[-1], Z[-1], color=style.INK, lw=0.9) + ax.set_box_aspect((1.3, 0.9, 0.85)) + ax.view_init(elev=22, azim=-58) + ax.set_axis_off() + ax.set_facecolor(style.SURFACE) + fig.text(0.02, 0.96, title, fontsize=7.8, weight="bold", va="top", color=style.INK) + fig.subplots_adjust(left=0, right=1, bottom=0, top=0.92) + return fig + + +def build(sink): + import style + for fig_id, kind, title in zip(SHAPES, ("cylinder", "paraboloid", "cone", "pyramid"), + ("Elliptical cylinder", "Elliptical paraboloid", "Elliptical cone", "Rectangular pyramid")): + if fig_id in sink.expected: + sink.save(_tile(kind, title, style), fig_id) diff --git a/docs/figures/src/hydraulics/ch5_street_section.py b/docs/figures/src/hydraulics/ch5_street_section.py new file mode 100644 index 000000000..8232e8af3 --- /dev/null +++ b/docs/figures/src/hydraulics/ch5_street_section.py @@ -0,0 +1,119 @@ +"""Street cross-sections (hydraulics Figures 5-10 and 7-11, and the Engine +Manual's Figure 1-9). + +Figure 5-10 a one-sided street: curb, depressed gutter, road with a cross + slope up to the crown, and an optional backing (sidewalk or + shoulder) — the dimensions of the [STREETS] section +Figure 7-11 the same street divided into gutter flow and roadway flow, + with the spread T and the flow depth at the curb that the + HEC-22 inlet equations use + +Drawn from the [STREETS] parameters; replaces two 500 px sketches. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +# [STREETS] dimensions (ft): curb height, road width (curb to crown), cross slope, +# gutter width, gutter depression, backing width, backing slope +HC, WR, SX, WG, AG, WB, SB = 0.5, 20.0, 0.02, 2.0, 0.25, 4.0, 0.04 # depression exaggerated: not to scale + + +def _profile(): + """(x, z) of the one-sided street from the curb face to the crown, curb top at z = 0.""" + x = [0.0, 0.0, WG, WR] + z_curb_bottom = -HC + z_gutter_edge = z_curb_bottom + AG + WG * SX # depressed gutter meets the road cross slope + z = [0.0, z_curb_bottom, z_gutter_edge, z_gutter_edge + (WR - WG) * SX] + return np.array(x), np.array(z) + + +def _base(ax, style, water_depth=None): + from matplotlib.patches import Polygon + x, z = _profile() + # backing behind the curb + ax.plot([-WB, 0.0], [WB * SB, 0.0], color=style.INK, lw=1.4) + ax.fill_between([-WB, 0.0], [WB * SB, 0.0], -1.4, color="#e6e6e6", zorder=0) + # road surface and its fill + ax.plot(x, z, color=style.INK, lw=1.6) + ax.fill_between(x[1:], z[1:], -1.4, color="#d5d5d5", zorder=0) + ax.plot([x[-1], x[-1] + 1.5], [z[-1], z[-1]], color=style.INK, lw=1.6) + ax.plot([x[-1], x[-1]], [z[-1] - 0.3, z[-1]], color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.text(x[-1], z[-1] - 0.34, "crown", fontsize=7.5, color=style.MUTED, ha="center", va="top") + if water_depth is not None: + zw = -HC + water_depth + xs = np.linspace(0, WR, 400) + zs = np.interp(xs, x[1:], z[1:]) + m = zs <= zw + ax.fill_between(xs[m], zs[m], zw, color=style.WATER, alpha=0.3, zorder=1) + ax.plot([0, xs[m].max()], [zw, zw], color=style.WATER, lw=1.2) + return xs[m].max() + return None + + +def _fig_5_10(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.4, 3.0)) + fig.patch.set_facecolor(style.SURFACE) + _base(ax, style) + x, z = _profile() + D = dict(arrowstyle="<->", color=style.COLORS["fv"], lw=0.9) + L = dict(fontsize=7.6, color=style.COLORS["fv"]) + ax.annotate("", xy=(-0.5, 0), xytext=(-0.5, -HC), arrowprops=D) + ax.text(-0.6, -HC / 2, "curb height", ha="right", va="center", **L) + ax.annotate("", xy=(0, -HC - 0.22), xytext=(WG, -HC - 0.22), arrowprops=D) + ax.text(WG / 2, -HC - 0.30, "gutter width", ha="center", va="top", **L) + ax.annotate("", xy=(WG + 0.3, z[2]), xytext=(WG + 0.3, z[2] - AG), arrowprops=D) + ax.text(WG + 0.5, z[2] - AG / 2, "gutter depression (exaggerated)", va="center", **L) + ax.annotate("", xy=(0, 0.42), xytext=(WR, 0.42), arrowprops=D) + ax.text(WR / 2, 0.47, "road width (curb to crown)", ha="center", **L) + xm = WG + (WR - WG) * 0.55 + zm = np.interp(xm, x[1:], z[1:]) + ax.plot([xm, xm + 4], [zm, zm], color=style.COLORS["fv"], lw=0.8, ls=(0, (3, 2))) + ax.text(xm + 1.0, zm + 0.10, "cross slope S_x", va="bottom", **L) + ax.annotate("", xy=(-WB, WB * SB + 0.3), xytext=(0, WB * SB + 0.3), arrowprops=D) + ax.text(-WB / 2, WB * SB + 0.35, "backing width, slope", ha="center", **L) + ax.text(-WB, -1.32, "one-sided street, not to scale: a two-sided street repeats the section mirror-wise about the crown", + fontsize=7.4, color=style.MUTED) + ax.set_xlim(-WB - 3.5, WR + 2) + ax.set_ylim(-1.5, 1.0) + ax.set_aspect(4.0) + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def _fig_7_11(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.4, 3.0)) + fig.patch.set_facecolor(style.SURFACE) + depth = 0.46 + spread = _base(ax, style, water_depth=depth) + zw = -HC + depth + D = dict(arrowstyle="<->", color=style.COLORS["fv"], lw=0.9) + L = dict(fontsize=7.6, color=style.COLORS["fv"]) + ax.annotate("", xy=(0, zw + 0.3), xytext=(spread, zw + 0.3), arrowprops=D) + ax.text(spread / 2, zw + 0.35, "spread T", ha="center", **L) + ax.annotate("", xy=(-0.5, zw), xytext=(-0.5, -HC), arrowprops=D) + ax.text(-0.6, (zw - HC) / 2, "depth at curb d", ha="right", va="center", **L) + ax.plot([WG, WG], [zw - 0.55, zw + 0.05], color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.text(WG / 2 - 0.2, -HC - 0.30, "gutter flow Q_w", ha="right", va="top", fontsize=7.6, color=style.WATER) + ax.text(WG + 0.4, -HC - 0.30, "roadway (side) flow Q_s", ha="left", va="top", fontsize=7.6, color=style.WATER) + ax.text(-WB, -1.32, "HEC-22: E_0 = Q_w / Q is the fraction of the flow in the gutter; capture depends on d, T and E_0", + fontsize=7.4, color=style.MUTED) + ax.set_xlim(-WB - 3.5, WR + 2) + ax.set_ylim(-1.5, 1.0) + ax.set_aspect(4.0) + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + if "hydraulics_ch5_street_section" in sink.expected: + sink.save(_fig_5_10(style), "hydraulics_ch5_street_section") + if "hydraulics_ch7_street_spread" in sink.expected: + sink.save(_fig_7_11(style), "hydraulics_ch7_street_spread") diff --git a/docs/figures/src/hydraulics/ch5_xsect_gallery.py b/docs/figures/src/hydraulics/ch5_xsect_gallery.py new file mode 100644 index 000000000..8a27e2e19 --- /dev/null +++ b/docs/figures/src/hydraulics/ch5_xsect_gallery.py @@ -0,0 +1,176 @@ +"""Cross-section shape galleries for hydraulics Chapter 5, drawn from the +engine's own geometry. + +Every outline is the engine's width-at-depth function — `XSectionGeometry` +from the openswmm package, the same kernel the solvers call — sampled from +the invert to the crown and mirrored about the centreline, so the drawing +cannot disagree with the tables. Each tile carries an inset of the +area-versus-depth relation A(y)/A_full. Replaces the low-resolution EPA +bitmaps for Figures 5-1, 5-4, 5-5 and 5-6 and the θ definition sketch. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = ("openswmm",) + +# (label, shape name, geom1..geom4) — Geom1 is the full height; the rest +# follow the [XSECTIONS] conventions of the Engine Manual, Chapter 2. +ELLIPTICAL_ARCH = [ + ("Horizontal ellipse", "HORIZ_ELLIPSE", (2.0, 3.0)), + ("Vertical ellipse", "VERT_ELLIPSE", (3.0, 2.0)), + ("Arch", "ARCH", (2.0, 3.2)), +] +MASONRY = [ + ("Egg-shaped", "EGGSHAPED", (3.0,)), + ("Horseshoe", "HORSESHOE", (3.0,)), + ("Gothic", "GOTHIC", (3.0,)), + ("Catenary", "CATENARY", (3.0,)), + ("Semi-elliptical", "SEMIELLIPTICAL", (3.0,)), + ("Basket-handle", "BASKETHANDLE", (3.0,)), + ("Semi-circular", "SEMICIRCULAR", (3.0,)), +] +COMPOSITE = [ + ("Rectangular-triangular", "RECT_TRIANG", (3.0, 3.0, 1.0)), + ("Rectangular-round", "RECT_ROUND", (3.0, 3.0, 1.5)), + ("Modified basket-handle", "MODBASKETHANDLE", (3.0, 3.0, 1.5)), + ("Filled circular", "FILLED_CIRCULAR", (3.0, 0.6)), +] +POWER_EXPONENTS = [0.5, 1.0, 2.0, 4.0] + + +def _outline(G, S, shape, geom, n=161): + """(x_left, x_right, y) of the engine's section, plus whether it is open.""" + g = G(getattr(S, shape), *geom, units="US") + yfull = g.full_depth + y = np.linspace(0.0, yfull, n) + w = g.width(y) + return -w / 2.0, w / 2.0, y, g.is_open, g.area(y) / g.full_area + + +def _tile(ax, G, S, label, shape, geom, P, style, inset=True): + xl, xr, y, is_open, a_rel = _outline(G, S, shape, geom) + ax.fill_betweenx(y, xl, xr, color=style.PIPE_FILL, zorder=1) + ax.plot(xl, y, color=style.INK, lw=1.3, zorder=2) + ax.plot(xr, y, color=style.INK, lw=1.3, zorder=2) + if not is_open and (xr[-1] - xl[-1]) > 1e-9: + ax.plot([xl[-1], xr[-1]], [y[-1], y[-1]], color=style.INK, lw=1.3, zorder=2) + if is_open: + ax.plot([xl[-1] - 0.25, xl[-1]], [y[-1], y[-1]], color=style.MUTED, lw=0.8, ls=(0, (2, 2))) + ax.plot([xr[-1], xr[-1] + 0.25], [y[-1], y[-1]], color=style.MUTED, lw=0.8, ls=(0, (2, 2))) + # a water level at 40 % depth + k = int(0.4 * (len(y) - 1)) + ax.fill_betweenx(y[: k + 1], xl[: k + 1], xr[: k + 1], color=style.WATER, alpha=0.22, zorder=1.5) + ax.plot([xl[k], xr[k]], [y[k], y[k]], color=style.WATER, lw=1.0, zorder=2) + span = max(xr.max() - xl.min(), y.max()) + # the shape occupies the left 60 % of the tile; the inset gets the right column + ax.set_xlim(xl.min() - 0.12 * span, xl.min() + (1.9 if inset else 1.24) * span) + ax.set_ylim(-0.08 * span, y.max() + 0.16 * span) + ax.set_aspect("equal") + ax.axis("off") + ax.set_title(label, fontsize=8.5, color=style.INK, pad=8, loc="left") + if inset: + ia = ax.inset_axes([0.66, 0.16, 0.32, 0.46]) + ia.plot(a_rel, y / y.max(), color=style.COLORS["fv"], lw=1.1) + ia.set_xlim(0, 1) + ia.set_ylim(0, 1) + ia.set_xticks([0, 1]) + ia.set_yticks([0, 1]) + ia.tick_params(labelsize=5, colors=style.MUTED, length=2, pad=1) + ia.set_xlabel("A/A_full", fontsize=5.5, color=style.MUTED, labelpad=1) + ia.set_ylabel("y/Y_full", fontsize=5.5, color=style.MUTED, labelpad=1) + ia.set_facecolor(style.SURFACE) + for s in ("top", "right"): + ia.spines[s].set_visible(False) + for s in ("left", "bottom"): + ia.spines[s].set_color(style.GRIDC) + + +def _gallery(specs, ncol, title, G, S, P, style, width_in=9.0): + import matplotlib.pyplot as plt + nrow = -(-len(specs) // ncol) + fig, axes = plt.subplots(nrow, ncol, figsize=(width_in, 1.85 * nrow + 0.6)) + fig.patch.set_facecolor(style.SURFACE) + axes = np.atleast_1d(axes).ravel() + for ax, (label, shape, geom) in zip(axes, specs): + _tile(ax, G, S, label, shape, geom, P, style) + for ax in axes[len(specs):]: + ax.axis("off") + fig.suptitle(title, fontsize=9.5, color=style.INK, x=0.01, ha="left", y=0.995) + fig.text(0.99, 0.005, "outlines from the engine's width(depth); inset: area fraction versus depth fraction; " + "shaded: water at 40 % of full depth", + fontsize=6.3, color=style.MUTED, ha="right", va="bottom") + fig.tight_layout(rect=(0, 0.02, 1, 0.965)) + return fig + + +def _power_law(G, S, P, style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, len(POWER_EXPONENTS), figsize=(9.0, 2.9)) + fig.patch.set_facecolor(style.SURFACE) + for ax, ex in zip(axes, POWER_EXPONENTS): + _tile(ax, G, S, f"1/γ = {ex:g}" + (" (parabola)" if ex == 2.0 else ""), "POWER", (3.0, 4.0, ex), + P, style, inset=False) + xl, xr, y, _, _ = _outline(G, S, "POWER", (3.0, 4.0, ex)) + ax.annotate("", xy=(xr[-1], y[-1] + 0.22), xytext=(xl[-1], y[-1] + 0.22), + arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(xl[-1] + 0.3, y[-1] + 0.3, "b", fontsize=7.5, color=style.MUTED, ha="left", va="bottom") + ax.annotate("", xy=(xr.max() + 0.35, y[-1]), xytext=(xr.max() + 0.35, 0), + arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(xr.max() + 0.45, y[-1] / 2, "Y_full", fontsize=7.5, color=style.MUTED, va="center") + ax.set_xlim(xl.min() - 0.5, xr.max() + 1.3) + ax.set_ylim(-0.3, y[-1] + 1.1) + ax.set_title(ax.get_title(), fontsize=8.5, color=style.INK, pad=2, loc="center") + fig.suptitle("Power-law cross section y = α x^(1/γ): the same full depth and top width, four exponents", + fontsize=9.5, color=style.INK, x=0.01, ha="left") + fig.tight_layout(rect=(0, 0, 1, 0.94)) + return fig + + +def _theta(G, S, P, style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(4.2, 3.6)) + fig.patch.set_facecolor(style.SURFACE) + t = np.linspace(0, 2 * np.pi, 361) + ax.plot(np.cos(t), np.sin(t), color=style.INK, lw=1.4) + y = -0.35 # water surface at 0.325 D of a unit-radius pipe + xw = np.sqrt(1 - y * y) + theta_half = np.arccos(-y) # half central angle to the free surface + arc = np.linspace(-np.pi / 2 - theta_half, -np.pi / 2 + theta_half, 200) + ax.fill(np.concatenate([[0], np.cos(arc), [0]]), np.concatenate([[0], np.sin(arc), [0]]), + color=style.WATER, alpha=0.18, zorder=0) + ax.fill_between(np.cos(arc), np.sin(arc), y, color=style.WATER, alpha=0.22, zorder=0) + ax.plot([-xw, xw], [y, y], color=style.WATER, lw=1.2) + ax.plot([0, np.cos(arc[0])], [0, np.sin(arc[0])], color=style.INK, lw=0.9) + ax.plot([0, np.cos(arc[-1])], [0, np.sin(arc[-1])], color=style.INK, lw=0.9) + ax.plot([0], [0], marker="o", ms=3, color=style.INK) + small = np.linspace(arc[0], arc[-1], 60) + ax.plot(0.28 * np.cos(small), 0.28 * np.sin(small), color=style.INK, lw=0.8) + ax.text(0, -0.42, "θ", fontsize=11, ha="center", va="top", color=style.INK) + ax.annotate("", xy=(1.18, y), xytext=(1.18, -1.0), arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(1.24, (y - 1.0) / 2, "y", fontsize=8, color=style.MUTED, va="center") + ax.annotate("", xy=(-1.18, 1.0), xytext=(-1.18, -1.0), arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(-1.24, 0, "D", fontsize=8, color=style.MUTED, va="center", ha="right") + ax.text(0, 1.12, "A = (θ − sin θ) D² / 8, P = θ D / 2, T = D sin(θ/2)", fontsize=7.2, + ha="center", va="bottom", color=style.INK) + ax.set_xlim(-1.7, 1.7) + ax.set_ylim(-1.2, 1.35) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout() + return fig + + +def build(sink): + import primitives as P + import style + from openswmm import engine as e + G, S = e.XSectionGeometry, e.XSectShape + sink.save(_gallery(ELLIPTICAL_ARCH, 3, "Elliptical and arch pipe sections", G, S, P, style), + "hydraulics_ch5_shapes_elliptical_arch") + sink.save(_gallery(MASONRY, 4, "Older masonry sewer sections", G, S, P, style), + "hydraulics_ch5_shapes_masonry") + sink.save(_gallery(COMPOSITE, 4, "Composite sections: rectangular, triangular and circular parts", G, S, P, style), + "hydraulics_ch5_shapes_composite") + sink.save(_power_law(G, S, P, style), "hydraulics_ch5_power_law") + sink.save(_theta(G, S, P, style), "hydraulics_ch5_circular_theta") diff --git a/docs/figures/src/hydraulics/ch6_pump_types.py b/docs/figures/src/hydraulics/ch6_pump_types.py new file mode 100644 index 000000000..54e49f1e1 --- /dev/null +++ b/docs/figures/src/hydraulics/ch6_pump_types.py @@ -0,0 +1,61 @@ +"""The five pump curve types of hydraulics Table 6-1, one tile each. + +Type 1 flow in steps of inlet-node volume Type 2 flow in steps of inlet depth +Type 3 head–flow characteristic (centrifugal) Type 4 flow varying continuously with depth +Type 5 a Type 3 curve shifted by speed setting +Synthetic curves in the engine's conventions; replace 190 px icons. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +TILES = [("hydraulics_ch6_pump_type1", "Type 1: flow versus inlet volume", "inlet node volume", "pump flow", "step_v"), + ("hydraulics_ch6_pump_type2", "Type 2: flow versus inlet depth", "inlet node depth", "pump flow", "step_d"), + ("hydraulics_ch6_pump_type3", "Type 3: head versus flow", "pump flow", "head difference", "hq"), + ("hydraulics_ch6_pump_type4", "Type 4: flow versus inlet depth", "inlet node depth", "pump flow", "cont"), + ("hydraulics_ch6_pump_type5", "Type 5: head versus flow, by speed", "pump flow", "head difference", "hq_speed")] + + +def _tile(fig_id, title, xl, yl, kind, style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(3.0, 2.2)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + c = style.COLORS["fv"] + if kind in ("step_v", "step_d"): + x = [0, 1, 1, 2, 2, 3, 3, 4] + y = [0, 0, 1.5, 1.5, 2.6, 2.6, 3.4, 3.4] + ax.plot(x, y, color=c, lw=2.0) + for xi, yi in zip([1, 2, 3], [1.5, 2.6, 3.4]): + ax.plot([xi], [yi], marker="o", ms=3.5, color=c) + elif kind == "hq": + q = np.linspace(0, 4, 100) + ax.plot(q, 4 - 0.18 * q ** 2, color=c, lw=2.0) + ax.plot([0, 1.4, 2.6, 3.6], [4, 3.65, 2.8, 1.65], marker="o", ms=3.5, color=c, lw=0) + elif kind == "cont": + d = np.linspace(0, 4, 100) + ax.plot(d, 3.6 * (1 - np.exp(-1.1 * d)), color=c, lw=2.0) + ax.plot([0.5, 1.2, 2.2, 3.5], 3.6 * (1 - np.exp(-1.1 * np.array([0.5, 1.2, 2.2, 3.5]))), marker="o", ms=3.5, color=c, lw=0) + else: + q = np.linspace(0, 4, 100) + for s, cc in ((1.0, c), (0.8, style.COLORS["dw"]), (0.6, style.COLORS["dw-slot"])): + ax.plot(q * s, s * s * (4 - 0.18 * (q) ** 2), color=cc, lw=1.8, label=f"speed {s:g}") + ax.legend(fontsize=6, loc="upper right") + ax.set_xlabel(xl, fontsize=7) + ax.set_ylabel(yl, fontsize=7) + ax.set_xticks([]) + ax.set_yticks([]) + ax.set_xlim(0, 4.2) + ax.set_ylim(0, 4.4) + ax.set_title(title, fontsize=7.6, loc="left", color=style.INK) + fig.tight_layout(pad=0.3) + return fig + + +def build(sink): + import style + for fig_id, title, xl, yl, kind in TILES: + if fig_id in sink.expected: + sink.save(_tile(fig_id, title, xl, yl, kind, style), fig_id) diff --git a/docs/figures/src/hydraulics/ch8_cell_layout.py b/docs/figures/src/hydraulics/ch8_cell_layout.py new file mode 100644 index 000000000..c304cf9bb --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_cell_layout.py @@ -0,0 +1,62 @@ +"""What 'spatially explicit' means (hydraulics Chapter 8, §8.3): the legacy +node–link view — one momentum balance per pipe, one depth per manhole — set +against the finite-volume view, in which each conduit is cut into cells, the +water surface is resolved inside the pipe, and the flux leaving one cell is +exactly the flux entering the next. Promoted from the SWMM paper's schematic +(epaswmm5_qa/article/scripts/fig_schematic.py, 2026-09); synthetic geometry. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(2, 1, figsize=(8.0, 5.2), sharex=True) + fig.patch.set_facecolor(style.SURFACE) + x = np.linspace(0, 100, 200) + z = 3.0 - 0.02 * x + crown = z + 1.0 + h = np.where(x < 55, 0.35 + 0.001 * x, 0.85 - 0.001 * (x - 55)) # a jump mid-reach + eta = z + h + FV, DW = style.COLORS["fv"], style.COLORS["dw"] + for ax, title in zip(axes, ("Node–link dynamic wave: one flow per pipe, one depth per manhole", + "Finite volume: the pipe itself is discretised — profiles, bores and jumps live inside it")): + style.style_ax(ax) + ax.grid(False) + ax.fill_between(x, 0.4, z, color=style.SOIL, zorder=0) + ax.fill_between(x, z, crown, color=style.PIPE_FILL, zorder=1) + ax.plot(x, z, color=style.MUTED, lw=1.2) + ax.plot(x, crown, color=style.MUTED, lw=1.2, ls=(0, (4, 2))) + for xm in (0, 100): + ax.plot([xm, xm], [3.0 - 0.02 * xm, 4.6], color=style.MUTED, lw=6, solid_capstyle="butt", alpha=0.45) + ax.set_ylim(0.4, 4.9) + ax.set_yticks([]) + ax.set_title(title, fontsize=9.5, loc="left", color=style.INK) + A = dict(arrowstyle="->", color=style.MUTED, lw=1.0) + ax = axes[0] + ax.plot([0, 100], [z[0] + 0.42, z[-1] + 0.75], color=DW, lw=2.2, ls=(0, (5, 3))) + for xm, hh in ((0, 0.42), (100, 0.75)): + ax.plot(xm, 3.0 - 0.02 * xm + hh, "o", color=DW, ms=9, mec=style.SURFACE, mew=1.5) + ax.annotate("depth is known only here", xy=(0, z[0] + 0.42), xytext=(12, 4.15), fontsize=9, color=style.INK, arrowprops=A) + ax.annotate("one momentum balance\nfor the whole pipe", xy=(50, 2.6), xytext=(40, 4.0), fontsize=9, color=style.INK, arrowprops=A) + ax = axes[1] + edges = np.linspace(0, 100, 11) + for xe in edges[1:-1]: + ze = 3.0 - 0.02 * xe + ax.plot([xe, xe], [ze, ze + 1.0], color=style.MUTED, lw=0.8, alpha=0.6) + ax.plot(x, eta, color=FV, lw=2.4) + ax.annotate("hydraulic jump captured\nwhere it happens", xy=(55, z[110] + 0.78), xytext=(60, 4.1), fontsize=9, + color=style.INK, arrowprops=A) + ax.annotate("flux out of one cell =\nflux into the next (exactly)", xy=(edges[3], 3.0 - 0.02 * edges[3] + 0.25), + xytext=(4, 4.1), fontsize=9, color=style.INK, arrowprops=A) + ax.set_xlabel("distance along the conduit", color=style.MUTED, fontsize=9) + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch8_cell_layout") diff --git a/docs/figures/src/hydraulics/ch8_hll_fan.py b/docs/figures/src/hydraulics/ch8_hll_fan.py new file mode 100644 index 000000000..5a1210f79 --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_hll_fan.py @@ -0,0 +1,71 @@ +"""The Riemann fan at a finite-volume face (hydraulics Chapter 8, §8.5.3). + +Left: a wet–wet face. The left and right states U_L, U_R are separated by +the fastest left- and right-going signals S_L and S_R; the hydrodynamic +flux is HLL, one averaged state across the whole fan. The contact wave +S* = v is resolved only for the species flux (FV_RIEMANN HLLC). Right: a +dry-bed face, where the right signal is the tail of the rarefaction +fanning into the dry cell, S_R = v_L + 2 c_L. The Davis signal-speed +estimates are written under each panel. Synthetic; no run. +""" +from __future__ import annotations + +REQUIRES = () + + +def _panel(ax, style, dry): + FV, DW, OR = style.COLORS["fv"], style.COLORS["dw"], style.COLORS["fv-lts"] + sl, sr = (-0.75, 1.15) if not dry else (-0.55, 1.45) + T = 1.0 + ax.fill_between([sl * T, 0], 0, T, color=FV, alpha=0.10) + ax.fill_between([0, sr * T], 0, T, color=DW if not dry else style.GRIDC, alpha=0.10 if not dry else 0.35) + ax.fill_between([-1.6, sl * T], 0, T, color=style.WATER, alpha=0.06) + ax.plot([0, sl * T], [0, T], color=FV, lw=2.0) + ax.plot([0, sr * T], [0, T], color=DW if not dry else OR, lw=2.0) + if not dry: + ax.plot([0, 0.35 * T], [0, T], color=OR, lw=1.6, ls=(0, (4, 2))) + ax.text(0.35 * T + 0.03, T - 0.02, "S* = v\n(species only)", fontsize=8, color=OR, va="top") + ax.text(-1.55, 0.5 * T, "U_L", fontsize=10, color=style.INK) + ax.text((sl + sr) * T / 2 - 0.05, 0.62 * T, "U_HLL", fontsize=9.5, color=style.INK, ha="center") + ax.text(1.45, 0.5 * T, "U_R", fontsize=10, color=style.INK) + else: + for k in range(1, 6): + s = sl + (sr - sl) * k / 6 + ax.plot([0, s * T], [0, T], color=OR, lw=0.7, alpha=0.7) + ax.text(-1.55, 0.5 * T, "U_L", fontsize=10, color=style.INK) + ax.text(0.45 * T, 0.68 * T, "rarefaction\nfan", fontsize=9, color=style.INK, ha="center") + ax.text(1.55, 0.5 * T, "dry", fontsize=10, color=style.MUTED) + ax.text(sl * T - 0.04, T + 0.03, "S_L", fontsize=9, color=FV, ha="right") + ax.text(sr * T + 0.04, T + 0.03, "S_R", fontsize=9, color=DW if not dry else OR) + ax.axhline(0, color=style.INK, lw=1.0) + ax.plot([0, 0], [-0.06, 0.04], color=style.INK, lw=1.0) + ax.text(0, -0.1, "face", fontsize=8.5, ha="center", va="top", color=style.MUTED) + ax.annotate("", xy=(0, T + 0.22), xytext=(0, 0.02), arrowprops=dict(arrowstyle="-|>", color=style.MUTED, lw=0.8)) + ax.text(0.04, T + 0.18, "t", fontsize=9, color=style.MUTED) + ax.annotate("", xy=(1.85, 0), xytext=(-1.65, 0), arrowprops=dict(arrowstyle="-|>", color=style.MUTED, lw=0.8)) + ax.text(1.85, -0.1, "x", fontsize=9, color=style.MUTED, ha="right", va="top") + ax.set_xlim(-1.7, 1.9) + ax.set_ylim(-0.42, T + 0.3) + ax.axis("off") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, 2, figsize=(9.0, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + _panel(axes[0], style, dry=False) + _panel(axes[1], style, dry=True) + axes[0].set_title("(a) Wet–wet face: HLL averages the fan;\nS* serves only the species flux", + fontsize=8.6, loc="left", color=style.INK) + axes[1].set_title("(b) Dry-bed face: the rarefaction tail\nbounds the front", fontsize=8.6, loc="left", color=style.INK) + fig.text(0.02, 0.105, "Davis estimates: S_L = min(v_L − c_L, v_R − c_R), S_R = max(v_L + c_L, v_R + c_R), c = √(g A / T)", + fontsize=8, color=style.MUTED) + fig.text(0.02, 0.06, "Dry right cell: S_L = v_L − c_L, S_R = v_L + 2 c_L (mirror-wise for a dry left cell: v_R − 2 c_R, v_R + c_R)", + fontsize=8, color=style.MUTED) + fig.tight_layout(rect=[0, 0.13, 1, 1]) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch8_hll_fan") diff --git a/docs/figures/src/hydraulics/ch8_hydrostatic_reconstruction.py b/docs/figures/src/hydraulics/ch8_hydrostatic_reconstruction.py new file mode 100644 index 000000000..53bdd47b6 --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_hydrostatic_reconstruction.py @@ -0,0 +1,65 @@ +"""Hydrostatic (Audusse) reconstruction at a wet/dry face (hydraulics +Figure 8-3, §8.5.1–8.5.2). + +At a face between cells with beds z_L < z_R the reconstruction uses the +higher bed z* = max(z_L, z_R) and the face depths h*_L = max(0, η_L − z*), +h*_R = max(0, η_R − z*). Left: the left water surface stands above z*, so +the face is wet on the left and the front advances onto the dry cell. +Right: the left surface is below z*, both face depths are zero, and the +bank acts as a wall with exactly zero flux — the still-water property. +Replaces the watermarked placeholder. +""" +from __future__ import annotations + +REQUIRES = () + + +def _panel(ax, style, eta_l, title): + from matplotlib.patches import FancyArrowPatch + z_l, z_r = 0.5, 1.4 + ax.fill_between([0, 4], -0.2, z_l, color=style.SOIL, zorder=0) + ax.fill_between([4, 8], -0.2, z_r, color=style.SOIL, zorder=0) + ax.plot([0, 4], [z_l, z_l], color=style.INK, lw=1.8) + ax.plot([4, 8], [z_r, z_r], color=style.INK, lw=1.8) + ax.plot([4, 4], [z_l, z_r], color=style.INK, lw=1.8) + ax.plot([2.6, 5.4], [z_r, z_r], color=style.MUTED, lw=1.0, ls=(0, (4, 2))) + ax.text(5.5, z_r - 0.06, "z* = max(z_L, z_R)", fontsize=8.5, va="top", color=style.MUTED) + ax.fill_between([0, 4], z_l, eta_l, color=style.WATER, alpha=0.28) + ax.plot([0, 4], [eta_l, eta_l], color=style.WATER, lw=2.0) + ax.text(0.25, eta_l + 0.07, "η_L", fontsize=10, color=style.WATER) + ax.text(0.25, z_l - 0.2, "z_L", fontsize=9, color=style.INK, va="top") + ax.text(7.4, z_r - 0.2, "z_R", fontsize=9, color=style.INK, va="top") + h_star = max(0.0, eta_l - z_r) + if h_star > 0: + ax.annotate("", xy=(4.35, z_r + h_star), xytext=(4.35, z_r), + arrowprops=dict(arrowstyle="<->", color=style.WATER, lw=1.0)) + ax.text(4.5, z_r + h_star / 2, "h*_L = η_L − z*", fontsize=9, color=style.WATER, va="center") + ax.add_patch(FancyArrowPatch((3.2, eta_l + 0.18), (5.2, eta_l + 0.18), arrowstyle="-|>", + mutation_scale=14, color=style.WATER, lw=1.6)) + ax.text(4.2, eta_l + 0.32, "front advances onto the dry cell", ha="center", fontsize=8.5, color=style.WATER) + ax.text(6.4, z_r + 0.12, "h*_R = 0 (dry)", fontsize=9, color=style.INK) + else: + ax.text(4.0, z_r + 0.45, "h*_L = h*_R = 0\nzero flux: the bank is a wall", ha="center", fontsize=9, + color=style.INK) + ax.text(6.4, z_r + 0.12, "dry", fontsize=9, color=style.INK) + ax.text(2.0, -0.05, "cell L", ha="center", fontsize=8.5, color=style.MUTED, va="top") + ax.text(6.0, -0.05, "cell R", ha="center", fontsize=8.5, color=style.MUTED, va="top") + ax.set_xlim(0, 8) + ax.set_ylim(-0.45, 2.7) + ax.set_title(title, fontsize=9.5, color=style.INK, loc="left") + ax.axis("off") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, 2, figsize=(9.0, 3.8), sharey=True) + fig.patch.set_facecolor(style.SURFACE) + _panel(axes[0], style, 1.9, "Wetting front: η_L above z*") + _panel(axes[1], style, 1.15, "Emerged bank: η_L below z*") + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch8_hydrostatic_reconstruction") diff --git a/docs/figures/src/hydraulics/ch8_lts_ladder.py b/docs/figures/src/hydraulics/ch8_lts_ladder.py new file mode 100644 index 000000000..181fc3cdd --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_lts_ladder.py @@ -0,0 +1,59 @@ +"""The local-time-stepping tier ladder (hydraulics Chapter 8, §8.5.6). + +Every control volume takes a power-of-two multiple of the base step +Δt_0 from its own Courant limit; tiers are graded so that no face joins +volumes more than one tier apart, and a face fires at the finer side's +cadence, booking its flux into both accumulators. A macro cycle is one step +of the coarsest tier, at whose close every volume drains its accumulator. +Synthetic; no run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle + fig, ax = plt.subplots(figsize=(8.6, 3.9)) + fig.patch.set_facecolor(style.SURFACE) + K = 3 + macro = 2 ** K + colours = [style.COLORS["fv"], style.COLORS["dw"], style.COLORS["dw-slot"], style.COLORS["fv-lts"]] + for k in range(K + 1): + y = K - k + step = 2 ** k + ax.text(-0.4, y, f"tier {k}\nΔt = {step} Δt_0" if k else "tier 0\nΔt = Δt_0", fontsize=8.2, ha="right", va="center", + color=style.INK) + for j in range(0, macro, step): + ax.add_patch(Rectangle((j, y - 0.3), step, 0.6, fc=colours[k], ec=style.SURFACE, lw=1.2, alpha=0.75)) + ax.plot([j + step], [y], marker="|", ms=12, color=style.INK, mew=1.4) + for j in range(macro + 1): + ax.plot([j, j], [-0.65, K + 0.45], color=style.GRIDC, lw=0.6, zorder=0) + ax.text(macro / 2, K + 0.62, f"one macro cycle = one step of the coarsest tier = 2^{K} Δt_0 for {K + 1} tiers", + fontsize=8.6, ha="center", color=style.INK) + ax.annotate("", xy=(macro, K + 0.5), xytext=(0, K + 0.5), arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.9)) + # a face between tier 1 and tier 2 fires at tier 1's cadence + for j in range(0, macro, 2): + ax.plot([j + 2], [K - 1.5], marker="v", ms=6, color=style.INK, zorder=5) + ax.text(macro + 0.15, K - 1.5, "a face between tier 1 and tier 2\nfires at the finer cadence and\nbooks ±F Δt into both accumulators", fontsize=7.8, + va="center", color=style.INK) + ax.text(macro + 0.15, K - 3.0, "a volume drains its accumulator\nwhen its own window closes:\nexact conservation across tiers", fontsize=7.8, + va="center", color=style.INK) + ax.plot([macro], [-0.55], marker="^", ms=7, color=style.INK) + ax.text(macro, -0.85, "macro-cycle close: re-tiering allowed", fontsize=8, ha="center", va="top", color=style.INK) + ax.text(0, -0.85, "t", fontsize=8, ha="center", va="top", color=style.MUTED) + ax.text(0, K + 1.0, "Tiers are graded: no face joins volumes more than one tier apart; FV_LTS_MAX_TIERS caps the spread", + fontsize=8, color=style.MUTED) + ax.set_xlim(-2.2, macro + 3.6) + ax.set_ylim(-1.2, K + 1.3) + ax.axis("off") + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch8_lts_ladder") diff --git a/docs/figures/src/hydraulics/ch8_node_ghost_state.py b/docs/figures/src/hydraulics/ch8_node_ghost_state.py new file mode 100644 index 000000000..9f08fef0f --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_node_ghost_state.py @@ -0,0 +1,69 @@ +"""The ghost state a coupling face builds from the node head (hydraulics +Figure 8-4, §8.6.1). + +The end cell of a conduit meets the node at a coupling face. The face's +outside state is a ghost cell whose depth is the node head above the +conduit invert plus offset, h_g = H − z_f, whose area follows the section +closure A(h_g), and whose velocity is the interior end-cell velocity — so +the Riemann problem at the face sees the node as a reservoir at head H. +Profile view; replaces the watermarked placeholder. +""" +from __future__ import annotations + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle, FancyArrowPatch + fig, ax = plt.subplots(figsize=(7.6, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + # ground and manhole shaft + ax.fill_between([0, 8], -0.2, 0.4, color=style.SOIL, zorder=0) + ax.add_patch(Rectangle((0.6, 0.4), 1.4, 3.2, fc="#f4f3ef", ec=style.INK, lw=1.8, zorder=1)) + H = 2.6 + ax.fill_between([0.6, 2.0], 0.4, H, color=style.WATER, alpha=0.3, zorder=1.5) + ax.plot([0.6, 2.0], [H, H], color=style.WATER, lw=2.0, zorder=2) + ax.text(1.3, H + 0.12, "node head H", ha="center", fontsize=9.5, color=style.WATER) + ax.text(1.3, 3.72, "manhole", ha="center", fontsize=8.5, color=style.MUTED) + # conduit: invert from z_f at the face, crown one diameter above + z_f = 1.0 + ax.fill_between([2.0, 7.6], [z_f - 0.6, 0.2], [z_f, 0.8], color=style.SOIL, zorder=0) + ax.fill_between([2.0, 7.6], [z_f, 0.8], [z_f + 1.0, 1.8], color=style.PIPE_FILL, zorder=1) + ax.plot([2.0, 7.6], [z_f, 0.8], color=style.INK, lw=1.8, zorder=2) + ax.plot([2.0, 7.6], [z_f + 1.0, 1.8], color=style.MUTED, lw=1.2, ls=(0, (4, 2)), zorder=2) + ax.fill_between([2.0, 7.6], [z_f, 0.8], [z_f + 0.55, 1.15], color=style.WATER, alpha=0.25, zorder=1.5) + # cells + for x in (3.4, 4.8, 6.2): + ax.plot([x, x], [0.8 + (z_f - 0.8) * (7.6 - x) / 5.6, 1.8 + (z_f + 1.0 - 1.8) * (7.6 - x) / 5.6], + color=style.MUTED, lw=0.7, ls=(0, (2, 2))) + ax.text(2.7, 0.22, "end cell", fontsize=8.5, color=style.MUTED, ha="center") + ax.text(4.1, 0.22, "interior cells →", fontsize=8.5, color=style.MUTED) + # coupling face + ax.plot([2.0, 2.0], [0.4, 3.6], color=style.INK, lw=1.3, ls=(0, (5, 2, 1, 2)), zorder=3) + ax.text(2.06, 3.42, "coupling face", fontsize=9, color=style.INK) + ax.text(2.1, z_f - 0.34, "z_f: invert + offset", fontsize=8.5, color=style.INK, va="top") + # ghost depth + ax.annotate("", xy=(1.75, H), xytext=(1.75, z_f), arrowprops=dict(arrowstyle="<->", color=style.INK, lw=1.0)) + ax.text(0.32, (H + z_f) / 2, "h_g = H − z_f", fontsize=9.5, rotation=90, va="center", ha="center", color=style.INK) + # interior velocity carried onto the ghost + ax.add_patch(FancyArrowPatch((3.2, 1.28), (4.6, 1.18), arrowstyle="-|>", mutation_scale=16, + color=style.COLORS["fv-lts"], lw=2.0, zorder=4)) + ax.text(3.9, 1.5, "v_int (end cell)", ha="center", fontsize=9, color=style.COLORS["fv-lts"]) + ax.add_patch(FancyArrowPatch((2.9, 2.55), (2.15, 2.15), arrowstyle="-|>", mutation_scale=12, + color=style.COLORS["fv-lts"], lw=1.2, zorder=4)) + ax.text(2.95, 2.62, "ghost: A(h_g), v_g = v_int", fontsize=9.5, color=style.INK) + ax.text(0.2, -0.05, "the node is a reservoir at head H: the face flux is the Riemann solution between the ghost and the end cell", + fontsize=7.8, color=style.MUTED, va="top") + ax.set_xlim(0, 8) + ax.set_ylim(-0.45, 4.0) + ax.set_aspect("equal") + ax.axis("off") + ax.set_title("Ghost state at a node coupling face", fontsize=9.5, color=style.INK, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch8_node_ghost_state") diff --git a/docs/figures/src/hydraulics/ch8_slot_closure.py b/docs/figures/src/hydraulics/ch8_slot_closure.py new file mode 100644 index 000000000..4adf00784 --- /dev/null +++ b/docs/figures/src/hydraulics/ch8_slot_closure.py @@ -0,0 +1,115 @@ +"""The static slot closure of the finite-volume solver (hydraulics Chapter +8, §8.4.1–8.4.2), drawn from the engine's own circular-pipe geometry. + +Left: the top width T(h) of a 3 ft circular pipe. Below the crown cutoff +y_c it is the section's own width; across [y_c, y_full] the slot opens +through the C1 ramp φ(s) = s²(3 − 2s); above y_full it is the slot width +T_slot = g A_full / c_slot², capped at 5 % of the section's maximum width. +Right: the resulting celerity c = √(g A / T). Without the taper the +celerity would blow up at the crown of a closed section; with it the +celerity rises smoothly to the requested slot celerity. Requests below the +cap-implied celerity are inert: the 30 ft/s curve is byte-identical to the +cap. REQUIRES openswmm (XSectionGeometry); no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = ("openswmm",) + +G_FT = 32.174 +D = 3.0 # ft, circular +CROWN_CUTOFF = 0.985257 # y_c / y_full, Chapter 3 +CELERITIES = (30.0, 50.0, 100.0, 200.0) # ft/s; 30 falls under the 5 % cap + + +def _closure(width_fn, yfull, afull, wmax, c_slot, h): + """(T, A) along h for the tapered static slot at celerity c_slot.""" + t_slot = min(G_FT * afull / c_slot ** 2, 0.05 * wmax) + yc = CROWN_CUTOFF * yfull + T = np.empty_like(h) + below = h <= yfull + T[below] = width_fn(h[below]) + s = np.clip((h - yc) / (yfull - yc), 0.0, 1.0) + T += t_slot * s ** 2 * (3.0 - 2.0 * s) + T[~below] = t_slot + A = np.concatenate([[0.0], np.cumsum(0.5 * (T[1:] + T[:-1]) * np.diff(h))]) + return T, A, t_slot + + +def _draw(style, geom): + import matplotlib.pyplot as plt + yfull, afull = geom.full_depth, geom.full_area + wmax = float(np.max(geom.width(np.linspace(0.0, yfull, 801)))) + h = np.linspace(1e-4, 1.35 * yfull, 4000) + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 3.8)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + shades = [style.COLORS["dw-legacy"], style.COLORS["fv-lts"], style.COLORS["fv"], style.COLORS["dw"]] + cap_c = np.sqrt(G_FT * afull / (0.05 * wmax)) + curves = [] + for c, col in zip(CELERITIES, shades): + T, A, t_slot = _closure(geom.width, yfull, afull, wmax, c, h) + lab = f"c_slot = {c:.0f} ft/s" + if c < cap_c: + lab += f" (below the cap {cap_c:.0f} ft/s: inert)" + curves.append((T, np.sqrt(G_FT * A / T), col, lab)) + a0.plot(T, h / yfull, color=col, lw=1.6, label=lab) + a1.plot(curves[-1][1], h / yfull, color=col, lw=1.6) + # the section without a slot: the width collapses at the crown and the celerity diverges as + # 1/sqrt(y_full - h), so sample the last decades densely and use the engine's own area + hb = np.concatenate([np.linspace(1e-4, 0.97 * yfull, 800), yfull * (1.0 - np.logspace(-1.5, -7, 300))]) + T0 = geom.width(hb) + c0 = np.sqrt(G_FT * geom.area(hb) / np.maximum(T0, 1e-12)) + a0.plot(T0, hb / yfull, color=style.MUTED, lw=1.0, ls=(0, (3, 2)), label="section alone (no slot)") + a1.plot(c0, hb / yfull, color=style.MUTED, lw=1.2, ls=(0, (3, 2)), zorder=5) + for ax in (a0, a1): + ax.axhline(1.0, color=style.INK, lw=0.7, ls=(0, (2, 2))) + ax.axhline(CROWN_CUTOFF, color=style.INK, lw=0.5, ls=(0, (1, 2))) + ax.set_ylim(0, 1.35) + a0.text(wmax * 0.98, 1.012, "y_full (crown)", fontsize=7.5, ha="right", color=style.INK) + a0.text(wmax * 0.98, CROWN_CUTOFF - 0.05, "y_c = 0.985 y_full", fontsize=7.5, ha="right", color=style.INK) + a0.set_xlabel("top width T (ft)") + a0.set_ylabel("depth h / y_full") + a0.set_title("(a) Tapered slot mouth: T(h) for a 3 ft circular pipe", fontsize=9, loc="left") + a0.legend(fontsize=7, loc="center left", bbox_to_anchor=(0.02, 0.57), frameon=False) + # inset (a): the mouth + ins = a0.inset_axes([0.12, 0.06, 0.30, 0.26]) + m = (h / yfull > 0.975) & (h / yfull < 1.06) + for T, _, col, _ in curves: + ins.plot(T[m], h[m] / yfull, color=col, lw=1.4) + ins.set_xlim(0, 0.18) + ins.set_ylim(0.975, 1.06) + ins.set_title("the mouth, zoomed", fontsize=7, color=style.MUTED) + # inset (b): the crown, where the untapered celerity diverges + ins2 = a1.inset_axes([0.52, 0.10, 0.44, 0.40]) + m2 = (h / yfull > 0.96) & (h / yfull < 1.04) + for _, cel, col, _ in curves: + ins2.plot(cel[m2], h[m2] / yfull, color=col, lw=1.4) + mb = (hb / yfull > 0.96) + ins2.plot(c0[mb], hb[mb] / yfull, color=style.MUTED, lw=1.2, ls=(0, (3, 2)), zorder=5) + ins2.set_xscale("log") + ins2.set_xlim(10, 600) + ins2.set_ylim(0.96, 1.04) + ins2.set_title("the crown, zoomed", fontsize=7, color=style.MUTED) + for i in (ins, ins2): + i.axhline(1.0, color=style.INK, lw=0.6, ls=(0, (2, 2))) + i.axhline(CROWN_CUTOFF, color=style.INK, lw=0.5, ls=(0, (1, 2))) + i.tick_params(labelsize=6.5) + i.set_facecolor(style.SURFACE) + a1.set_xscale("log") + a1.set_xlim(3, 600) + a1.set_xlabel("celerity c = √(g A / T) (ft/s)") + a1.set_title("(b) Celerity rises smoothly to c_slot instead of diverging at the crown", fontsize=9, loc="left") + a1.text(3.4, 1.31, "T_slot = g A_full / c_slot²\ncapped at 0.05 W_max\ndashed: the section alone,\nno slot", fontsize=7.4, + color=style.MUTED, va="top", linespacing=1.25) + fig.tight_layout() + return fig + + +def build(sink): + import style + from openswmm import engine as e + geom = e.XSectionGeometry(e.XSectShape.CIRCULAR, D, units="US") + sink.save(_draw(style, geom), "hydraulics_ch8_slot_closure") diff --git a/docs/figures/src/hydraulics/ch9_active_set.py b/docs/figures/src/hydraulics/ch9_active_set.py new file mode 100644 index 000000000..beccf3684 --- /dev/null +++ b/docs/figures/src/hydraulics/ch9_active_set.py @@ -0,0 +1,111 @@ +"""The flux-active set at a wetting front (hydraulics Chapter 9, §9.5.7). + +A cell is flux-active only above `H_MOVE`, with a hysteresis band, and a +face flows only when both of its cells are active. A halo of inactive +cells is therefore kept around the active set so an advancing front always +has an active cell to flow into: one ring at the default cadence, and +`FRONT_REBUILD` widens it to five rings and marks the frontier ring, so +the rebuild can be deferred while the front crosses the halo. A cell of +the frontier whose depth crosses the activation threshold is a breach, and +forces the rebuild early. Inactive cells are not skipped but integrated +lazily: rainfall and held coupling accumulate as pure storage over the +whole interval, in one pass. Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +NX, NY = 22, 11 +FRONT_X = 7.4 # the wet front's position, in cell widths +BREACH = (13, 4) # a frontier cell that crosses h_on + + +def _classify(): + """state per cell: wet, halo1, halo5, frontier, dry — plus the breach.""" + st = np.full((NY, NX), "dry", dtype=object) + for j in range(NY): + # a curved front: wetter in the middle + edge = FRONT_X + 2.6 * np.exp(-((j - (NY - 1) / 2) ** 2) / 9.0) + for i in range(NX): + if i < edge - 0.5: + st[j, i] = "wet" + elif i < edge + 0.5: + st[j, i] = "halo1" + elif i < edge + 4.5: + st[j, i] = "halo5" + elif i < edge + 5.5: + st[j, i] = "frontier" + st[BREACH[1], BREACH[0]] = "breach" + return st + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 4.0), gridspec_kw=dict(width_ratios=[1.62, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + st = _classify() + COL = {"wet": ("#2a78d6", 0.55, "flux-active (h > H_MOVE)"), + "halo1": ("#7fb0e8", 0.55, "one-ring halo — the default cadence"), + "halo5": ("#cfe0f5", 0.85, "rings 2–5 — kept under FRONT_REBUILD"), + "frontier": ("#eda100", 0.35, "the marked frontier ring"), + "dry": ("#efeee9", 1.0, "dry, integrated lazily"), + "breach": ("#e87ba4", 0.95, "a breach: this cell crossed h_on")} + for j in range(NY): + for i in range(NX): + c, a, _ = COL[st[j, i]] + a0.add_patch(Rectangle((i, j), 1, 1, fc=c, alpha=a, ec=style.SURFACE, lw=0.8)) + a0.annotate("", xy=(FRONT_X + 3.4, NY + 0.75), xytext=(FRONT_X - 0.6, NY + 0.75), + arrowprops=dict(arrowstyle="-|>", color=style.INK, lw=1.4, mutation_scale=12)) + a0.text(FRONT_X + 1.4, NY + 0.95, "the front advances", fontsize=7.8, ha="center", color=style.INK) + a0.plot([BREACH[0] + 0.5], [BREACH[1] + 0.5], marker="*", ms=12, mfc="white", mec=style.INK, mew=1.0, zorder=5) + a0.annotate("breach — rebuild now", xy=(BREACH[0] + 0.5, BREACH[1] + 0.5), xytext=(BREACH[0] + 2.6, BREACH[1] - 2.6), + fontsize=7.6, color=style.INK, arrowprops=dict(arrowstyle="->", color=style.INK, lw=0.9)) + a0.set_xlim(-0.4, NX + 0.4) + a0.set_ylim(-0.6, NY + 1.5) + a0.set_aspect("equal", adjustable="datalim") + a0.axis("off") + a0.set_title("(a) The active set and its halo, in plan", fontsize=9, loc="left") + + # legend and the hysteresis band + y = 9.0 + for key in ("wet", "halo1", "halo5", "frontier", "breach", "dry"): + c, a, lab = COL[key] + a1.add_patch(Rectangle((0.1, y), 0.62, 0.42, fc=c, alpha=a, ec=style.SURFACE, lw=0.8)) + a1.text(0.88, y + 0.21, lab, fontsize=7.4, va="center", color=style.INK) + y -= 0.72 + a1.text(0.1, 4.25, "A face flows only when both of its cells are active.", fontsize=7.6, color=style.INK) + a1.text(0.1, 3.9, "A one-sided face exports volume into a cell whose update\n" + "never runs — measured as an 18 % basin loss when it was allowed.", + fontsize=7.2, color=style.MUTED, va="top", linespacing=1.45) + # the hysteresis band + h = np.linspace(0, 2.2, 400) + hm, d = 1.0, 0.18 + a1.plot(h, np.where(h > hm + d, 1.0, 0.0), color=style.COLORS["fv"], lw=1.6) + a1.plot(h, np.where(h > hm - d, 1.0, 0.0) * 0.0 + np.where(h > hm - d, 1.0, 0.0), color="none") + a1.set_xlim(0, 9.4) + a1.set_ylim(-0.6, 9.9) + a1.axis("off") + a1.set_title("(b) What the colours mean", fontsize=9, loc="left") + # hysteresis inset + ins = a1.inset_axes([0.08, 0.06, 0.86, 0.26]) + ins.plot([0, hm + d, hm + d, 2.2], [0, 0, 1, 1], color=style.COLORS["fv"], lw=1.6, label="entering: h_move + δ") + ins.plot([2.2, hm - d, hm - d, 0], [1, 1, 0, 0], color=style.COLORS["fv-lts"], lw=1.6, ls=(0, (4, 2)), + label="leaving: h_move − δ") + ins.axvline(hm, color=style.MUTED, lw=0.8, ls=(0, (1, 2))) + ins.set_xticks([hm]) + ins.set_xticklabels(["H_MOVE"], fontsize=6.6) + ins.set_yticks([]) + ins.set_ylim(-0.15, 1.35) + ins.legend(fontsize=6.2, frameon=False, loc="upper left") + ins.set_title("δ = min(1 mm, H_MOVE / 2): the band scales with the threshold", fontsize=6.8, color=style.MUTED) + ins.set_facecolor(style.SURFACE) + fig.tight_layout(pad=0.35) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch9_active_set") diff --git a/docs/figures/src/hydraulics/ch9_coupling_modes.py b/docs/figures/src/hydraulics/ch9_coupling_modes.py new file mode 100644 index 000000000..903363dd9 --- /dev/null +++ b/docs/figures/src/hydraulics/ch9_coupling_modes.py @@ -0,0 +1,77 @@ +"""Where a node spill is booked (hydraulics Chapter 9, §9.7.6). + +`COUPLING_IN_FLOODING` moves one number between two rows of the 1D routing +continuity table and changes nothing else. With `NO`, the default, water +leaving a node into the mesh is reported as coupling outflow, and the +flooding row holds only water genuinely lost from the model. With `YES`, +the spill is folded into the flooding loss, which is what a reader +comparing against a 1D-only run of the same model expects to see. The +totals, the ledger and the continuity error are identical either way; the +2D block below is untouched. Synthetic; the numbers are illustrative and +sum exactly. +""" +from __future__ import annotations + +REQUIRES = () + +ROWS = [ + ("Dry Weather Inflow", 0.000, 0.000), + ("Wet Weather Inflow", 12.480, 12.480), + ("Groundwater Inflow", 0.000, 0.000), + ("RDII Inflow", 0.000, 0.000), + ("External Inflow", 0.000, 0.000), + ("External Outflow", 9.120, 9.120), + ("Flooding Loss", 0.000, 3.210), + ("2D Coupling Outflow", 3.210, 0.000), + ("Evaporation Loss", 0.040, 0.040), + ("Initial Stored Volume", 0.310, 0.310), + ("Final Stored Volume", 0.418, 0.418), +] +MOVED = {"Flooding Loss", "2D Coupling Outflow"} +ERROR = -0.002 + + +def _table(ax, style, col, title, subtitle): + from matplotlib.patches import Rectangle + OR = style.COLORS["fv-lts"] + ax.text(0.0, len(ROWS) + 1.55, title, fontsize=9, weight="bold", color=style.INK) + ax.text(0.0, len(ROWS) + 1.05, subtitle, fontsize=7.4, color=style.MUTED) + ax.text(0.0, len(ROWS) + 0.35, "Flow Routing Continuity", fontsize=8, weight="bold", color=style.INK) + ax.text(5.4, len(ROWS) + 0.35, "Volume (10⁶ gal)", fontsize=7.6, ha="right", color=style.MUTED) + for k, (name, a, b) in enumerate(ROWS): + y = len(ROWS) - 1 - k + v = a if col == 0 else b + hot = name in MOVED + if hot: + ax.add_patch(Rectangle((-0.12, y - 0.02), 5.6, 0.62, fc=OR, alpha=0.16 if v else 0.06, ec="none")) + ax.text(0.0, y + 0.28, name, fontsize=7.6, va="center", + color=OR if hot and v else (style.MUTED if hot else style.INK)) + ax.text(5.35, y + 0.28, f"{v:.3f}", fontsize=7.6, ha="right", va="center", + color=OR if hot and v else (style.MUTED if hot else style.INK)) + ax.plot([-0.12, 5.4], [-0.35, -0.35], color=style.MUTED, lw=0.9) + ax.text(0.0, -0.85, "Continuity Error (%)", fontsize=7.8, weight="bold", color=style.INK) + ax.text(5.35, -0.85, f"{ERROR:.3f}", fontsize=7.8, ha="right", weight="bold", color=style.INK) + ax.set_xlim(-0.4, 5.8) + ax.set_ylim(-1.9, len(ROWS) + 2.1) + ax.axis("off") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.0, 4.6)) + fig.patch.set_facecolor(style.SURFACE) + _table(a0, style, 0, "COUPLING_IN_FLOODING NO (default)", + "the spill is its own row; Flooding Loss holds only water lost from the model") + _table(a1, style, 1, "COUPLING_IN_FLOODING YES", + "the spill is folded into Flooding Loss, as a 1D-only run reports it") + fig.text(0.5, 0.055, "One number moves between two rows. The totals, the ledger and the continuity error are " + "identical, and the 2D block of §9.9 is unchanged.", fontsize=7.6, color=style.MUTED, ha="center") + fig.text(0.5, 0.018, "The key changes reporting only: it never changes what the solvers exchange.", + fontsize=7.6, color=style.INK, ha="center") + fig.tight_layout(rect=[0, 0.085, 1, 1], w_pad=2.5) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch9_coupling_modes") diff --git a/docs/figures/src/hydraulics/ch9_mesh_stencil.py b/docs/figures/src/hydraulics/ch9_mesh_stencil.py new file mode 100644 index 000000000..eee89ba9c --- /dev/null +++ b/docs/figures/src/hydraulics/ch9_mesh_stencil.py @@ -0,0 +1,126 @@ +"""The mixed triangle-quadrilateral stencil (hydraulics Chapter 9, §9.3 +and §9.3.1). + +Left: a quadrilateral and a triangle sharing one face. Local edge k of a +cell runs between vertices (k+1) mod nv and (k+2) mod nv, so the same rule +numbers both shapes and local edge k is opposite vertex k on a triangle. +The centroid-to-edge normal distance d_e of (9-33) is drawn on both sides +of the shared face; the face's own separation is the sum. Right: the +padded slot layout. Every cell owns four slots whatever its vertex count, +so slot 4t + k addresses cell t's edge k with no indirection, and a +triangle's fourth slot is simply never visited. Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +QUAD = np.array([[0.0, 0.0], [2.9, -0.35], [3.25, 2.5], [0.3, 2.85]]) +TRI = np.array([[2.9, -0.35], [5.9, 1.05], [3.25, 2.5]]) + + +def _centroid(p): + return p.mean(axis=0) + + +def _edges(p): + nv = len(p) + return [(p[(k + 1) % nv], p[(k + 2) % nv]) for k in range(nv)] + + +def _cell(ax, style, poly, name, tag, fc, label_colour): + from matplotlib.patches import Polygon + ax.add_patch(Polygon(poly, closed=True, fc=fc, ec=style.INK, lw=1.4, zorder=2, alpha=0.5)) + c = _centroid(poly) + ax.plot(*c, marker="o", ms=5, color=style.INK, zorder=5) + ax.text(c[0], c[1] + 0.3, name, fontsize=8.6, ha="center", weight="bold", color=style.INK, zorder=6) + for k, (a, b) in enumerate(_edges(poly)): + m = (a + b) / 2 + out = m - c + out /= max(np.linalg.norm(out), 1e-9) + d = 0.75 if np.allclose(m, (QUAD[1] + QUAD[2]) / 2) else 0.32 + ax.text(m[0] + out[0] * d, m[1] + out[1] * d, f"k={k}", fontsize=7.4, ha="center", va="center", + color=label_colour, zorder=6) + for i, v in enumerate(poly): + ax.plot(*v, marker="o", ms=4.2, mfc="white", mec=style.INK, mew=1.0, zorder=6) + vout = v - c + vout /= max(np.linalg.norm(vout), 1e-9) + ax.text(v[0] + vout[0] * 0.38, v[1] + vout[1] * 0.38, f"{tag}:v{i}", fontsize=6.8, ha="center", + va="center", color=label_colour, zorder=6) + return c + + +def _geometry(ax, style): + FV, OR = style.COLORS["fv"], style.COLORS["fv-lts"] + cq = _cell(ax, style, QUAD, "quad L", "L", "#cfe0f5", FV) + ct = _cell(ax, style, TRI, "triangle R", "R", "#d8e9d4", "#4a7a42") + # the shared face: quad edge k=1 (v2,v3)? compute the common pair + a, b = QUAD[1], QUAD[2] + ax.plot([a[0], b[0]], [a[1], b[1]], color=OR, lw=3.4, zorder=4, solid_capstyle="round") + m = (a + b) / 2 + e = b - a + n = np.array([e[1], -e[0]]) + n /= np.linalg.norm(n) + for c, col, dy in ((cq, FV, -0.3), (ct, "#4a7a42", 0.3)): + ax.annotate("", xy=(m[0], m[1]), xytext=(c[0], c[1]), + arrowprops=dict(arrowstyle="-|>", color=col, lw=1.2, mutation_scale=10, ls=(0, (3, 2)))) + mid = (c + m) / 2 + ax.text(mid[0], mid[1] + dy, "d_e", fontsize=8, color=col, ha="center", va="center", zorder=7) + ax.annotate("", xy=(m[0] + n[0] * 0.95, m[1] + n[1] * 0.95 - 0.55), xytext=(m[0], m[1] - 0.55), + arrowprops=dict(arrowstyle="-|>", color=OR, lw=1.6, mutation_scale=12)) + ax.text(m[0] + n[0] * 1.12, m[1] + n[1] * 1.12 - 0.55, "n̂", fontsize=9, color=OR, ha="center", va="center") + ax.text(-1.5, -0.25, "shared face: length ξ, outward normal n̂ of L,\nseparation d_n = d_e(L) + d_e(R)", + fontsize=7.4, ha="left", va="top", color=OR, linespacing=1.5) + ax.text(-1.5, 3.95, "local edge k runs between vertices (k+1) mod nv and (k+2) mod nv — one rule for both\n" + "shapes, so on a triangle edge k is opposite vertex k. Each cell numbers its own vertices.", + fontsize=7.6, color=style.INK, linespacing=1.45, va="top") + ax.set_xlim(-1.6, 6.9) + ax.set_ylim(-1.3, 4.1) + ax.set_aspect("equal", adjustable="datalim") + ax.axis("off") + ax.set_title("(a) A quadrilateral and a triangle sharing a face", fontsize=9, loc="left") + + +def _slots(ax, style): + from matplotlib.patches import Rectangle + FV = style.COLORS["fv"] + cells = [("cell 0\nquad", 4), ("cell 1\ntriangle", 3), ("cell 2\ntriangle", 3), ("cell 3\nquad", 4)] + w, h = 1.15, 0.62 + for t, (name, nv) in enumerate(cells): + x = t * 4 * w + ax.text(x + 2 * w, 1.35, name, fontsize=7.4, ha="center", va="center", color=style.INK, linespacing=1.3) + for k in range(4): + used = k < nv + ax.add_patch(Rectangle((x + k * w, 0), w - 0.08, h, fc=FV if used else "#e4e3de", + ec=style.SURFACE, lw=1.4, alpha=0.85 if used else 1.0)) + ax.text(x + k * w + (w - 0.08) / 2, h / 2, f"{4 * t + k}", fontsize=7.6, ha="center", va="center", + color="#ffffff" if used else style.MUTED) + ax.text(x + k * w + (w - 0.08) / 2, -0.22, f"k={k}", fontsize=6.4, ha="center", va="top", + color=style.MUTED if used else "#d5d4cf") + ax.plot([x - 0.04, x + 4 * w - 0.08], [-0.52, -0.52], color=style.MUTED, lw=0.8) + ax.text(0, 2.35, "slot 4t + k addresses cell t's edge k directly: one stride, no per-cell offset table", + fontsize=7.6, color=style.INK) + ax.text(0, 2.0, "a triangle's fourth slot is allocated and never visited — the padding a fixed stride costs", + fontsize=7.2, color=style.MUTED) + ax.text(0, -0.95, "edge arrays (neighbour, length, normal, conveyance, momentum) all share this layout, " + "so one index reaches every one of them", fontsize=7.2, color=style.MUTED) + ax.set_xlim(-0.3, 4 * 4 * w + 0.3) + ax.set_ylim(-1.35, 2.6) + ax.axis("off") + ax.set_title("(b) The padded slot layout", fontsize=9, loc="left") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(2, 1, figsize=(8.4, 5.4), gridspec_kw=dict(height_ratios=[1.2, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + _geometry(a0, style) + _slots(a1, style) + fig.tight_layout(pad=0.35) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch9_mesh_stencil") diff --git a/docs/figures/src/hydraulics/ch9_vfr_wetting_cases.py b/docs/figures/src/hydraulics/ch9_vfr_wetting_cases.py new file mode 100644 index 000000000..b4335264e --- /dev/null +++ b/docs/figures/src/hydraulics/ch9_vfr_wetting_cases.py @@ -0,0 +1,62 @@ +"""Wetting cases of a planar-bed triangular cell and the wetted-edge face +gate (hydraulics Figure 9-3, §9.4 and §9.5.9). + +The VFR closure treats each cell as a planar bed through its three vertex +elevations z_1 ≤ z_2 ≤ z_3. A free surface η wets a triangle (η below +z_2), a quadrilateral (z_2 < η < z_3) or the whole cell. The fourth panel +shows the face gate: a shared edge sloping from z_lo to z_hi is blocked, +partially wet or submerged depending on η. Replaces the watermarked +placeholder (which was also over the 1600 px width bound). +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, 4, figsize=(9.6, 3.0), width_ratios=[1, 1, 1, 1.25]) + fig.patch.set_facecolor(style.SURFACE) + tri = np.array([[0.5, 0.5], [3.5, 1.0], [1.8, 3.4], [0.5, 0.5]]) + verts = [(0.5, 0.5, "z_1"), (3.5, 1.0, "z_2"), (1.8, 3.4, "z_3")] + cases = [ + ("η below z_2: a wet triangle", np.array([[0.5, 0.5], [1.9, 0.75], [1.05, 1.75], [0.5, 0.5]])), + ("z_2 < η < z_3: a wet quadrilateral", np.array([[0.5, 0.5], [3.5, 1.0], [2.6, 2.3], [1.15, 2.1], [0.5, 0.5]])), + ("η above z_3: fully wet", tri), + ] + for ax, (title, poly) in zip(axes[:3], cases): + ax.fill(tri[:, 0], tri[:, 1], color=style.SOIL, alpha=0.6, zorder=0) + ax.plot(tri[:, 0], tri[:, 1], color=style.INK, lw=1.6) + ax.fill(poly[:, 0], poly[:, 1], color=style.WATER, alpha=0.4) + for x, y, lab in verts: + ax.plot(x, y, marker="o", ms=4, color=style.INK) + ax.text(x + 0.1, y + 0.08, lab, fontsize=9, color=style.INK) + ax.set_xlim(0, 4.1) + ax.set_ylim(0, 3.9) + ax.set_title(title, fontsize=8.4, color=style.INK) + ax.set_aspect("equal") + ax.axis("off") + ax = axes[3] + z_lo, z_hi = 0.8, 2.2 + ax.fill_between([0, 4], -0.2, [z_lo, z_hi], color=style.SOIL, zorder=0) + ax.plot([0, 4], [z_lo, z_hi], color=style.INK, lw=1.6) + ax.text(0.05, z_lo + 0.1, "z_lo", fontsize=9, color=style.INK, va="bottom") + ax.text(3.55, z_hi + 0.1, "z_hi", fontsize=9, color=style.INK) + for eta, lab in ((0.55, "blocked"), (1.5, "partially wet"), (2.6, "submerged")): + ax.plot([0, 4], [eta, eta], color=style.WATER, lw=1.2, ls=(0, (4, 2))) + ax.text(4.08, eta, lab, fontsize=8, va="center", color=style.WATER) + xw = np.linspace(0, 2.0, 50) + ax.fill_between(xw, z_lo + (z_hi - z_lo) * xw / 4, 1.5, color=style.WATER, alpha=0.3) + ax.set_xlim(0, 5.6) + ax.set_ylim(-0.2, 3.2) + ax.set_title("the wetted-edge face gate", fontsize=8.4, color=style.INK) + ax.axis("off") + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydraulics_ch9_vfr_wetting_cases") diff --git a/docs/figures/src/hydrology/ch3_nonlinear_reservoir.py b/docs/figures/src/hydrology/ch3_nonlinear_reservoir.py new file mode 100644 index 000000000..6ca94999b --- /dev/null +++ b/docs/figures/src/hydrology/ch3_nonlinear_reservoir.py @@ -0,0 +1,74 @@ +"""The subcatchment as a nonlinear reservoir (hydrology Figure 3-2 and the +Engine Manual's Figure 1-13). + +A subcatchment surface holds a depth d of water; rainfall (and snowmelt +and run-on) enter, evaporation and infiltration leave, and once d exceeds +the depression storage d_s the excess discharges as overland flow q by +Manning's equation. Synthetic geometry; replaces a 470 × 224 px sketch. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon, Rectangle + fig, ax = plt.subplots(figsize=(7.4, 3.6)) + fig.patch.set_facecolor(style.SURFACE) + # a sloping subcatchment slab + x0, x1 = 0.8, 6.4 + slope = 0.09 + zs0, zs1 = 1.8, 1.8 - slope * (x1 - x0) + slab = Polygon([(x0, zs0), (x1, zs1), (x1, zs1 - 0.55), (x0, zs0 - 0.55)], closed=True, + fc="#e7d9bf", ec=style.INK, lw=1.0, zorder=1) + ax.add_patch(slab) + rng = np.random.default_rng(2) + xs = x0 + rng.random(60) * (x1 - x0) + ax.scatter(xs, zs0 - slope * (xs - x0) - 0.1 - rng.random(60) * 0.4, s=2, color="#a08a5e", alpha=0.5, zorder=2) + # ponded water: depth d above the surface, depression storage d_s marked + d, ds = 0.42, 0.22 + water = Polygon([(x0, zs0), (x1, zs1), (x1, zs1 + d), (x0, zs0 + d)], closed=True, + fc=style.WATER, alpha=0.25, ec=style.WATER, lw=1.0, zorder=1.5) + ax.add_patch(water) + ax.plot([x0, x1], [zs0 + ds, zs1 + ds], color=style.WATER, lw=0.9, ls=(0, (4, 2)), zorder=2) + ax.text(x1 + 0.12, zs1 - 0.02, "depression storage d_s (dashed)", fontsize=7.6, color=style.WATER, va="top") + ax.annotate("", xy=(x0 - 0.15, zs0 + d), xytext=(x0 - 0.15, zs0), arrowprops=dict(arrowstyle="<->", color=style.INK, lw=0.9)) + ax.text(x0 - 0.22, zs0 + d / 2, "d", fontsize=9, color=style.INK, ha="right", va="center") + W = dict(arrowstyle="-|>", color=style.WATER, lw=1.5, mutation_scale=12) + for x in (1.6, 2.4, 3.2, 4.0, 4.8): + z = zs0 - slope * (x - x0) + d + ax.annotate("", xy=(x, z + 0.03), xytext=(x, z + 0.75), arrowprops=W) + ax.text(3.2, zs0 + d + 0.85, "rainfall i (+ snowmelt, run-on from upstream subcatchments)", fontsize=8, + color=style.WATER, ha="center", fontstyle="italic") + ax.annotate("", xy=(5.7, zs1 + 0.12 + d + 0.75), xytext=(5.7, zs1 + 0.12 + d + 0.03), arrowprops=W) + ax.text(5.7, zs1 + 0.12 + d + 0.85, "evaporation e", fontsize=8, color=style.WATER, ha="center", fontstyle="italic") + for x in (2.0, 3.6): + z = zs0 - slope * (x - x0) + ax.annotate("", xy=(x, z - 0.5), xytext=(x, z - 0.02), arrowprops=W) + ax.text(4.5, zs0 - 0.62, "infiltration f", fontsize=8, color=style.WATER, ha="left", va="center", fontstyle="italic") + # outflow over the "weir" at the downstream end + ax.annotate("", xy=(x1 + 0.9, zs1 + d * 0.55), xytext=(x1 + 0.02, zs1 + d * 0.55), + arrowprops=dict(arrowstyle="-|>", color=style.WATER, lw=2.0, mutation_scale=13)) + ax.text(x1 + 0.12, zs1 + d + 0.1, "runoff q = (W/n) (d − d_s)^(5/3) S^(1/2)", fontsize=8, color=style.WATER, + fontstyle="italic") + ax.text(x1 + 0.12, zs1 - 0.5, "outlet: a node or\nanother subcatchment", fontsize=7.4, color=style.MUTED, va="top") + ax.annotate("", xy=(x1 + 0.2, zs1 - 0.75), xytext=(x0 - 0.2, zs0 - 0.75), + arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text((x0 + x1) / 2, zs0 - 0.75 - 0.32, "flow length = area / width W; slope S", fontsize=7.6, color=style.MUTED, + ha="center", va="top") + ax.text(x0 - 0.3, zs0 + d + 1.35, "The subcatchment as a nonlinear reservoir: dd/dt = i − e − f − q", + fontsize=9.2, weight="bold", color=style.INK) + ax.set_xlim(0.2, 9.0) + ax.set_ylim(zs1 - 1.3, zs0 + d + 1.55) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch3_nonlinear_reservoir") diff --git a/docs/figures/src/hydrology/ch4_infiltration_curves.py b/docs/figures/src/hydrology/ch4_infiltration_curves.py new file mode 100644 index 000000000..7fbcc9712 --- /dev/null +++ b/docs/figures/src/hydrology/ch4_infiltration_curves.py @@ -0,0 +1,176 @@ +"""Infiltration curves for hydrology Chapter 4, plotted from the chapter's +own equations. + +Figure 4-2 Horton infiltration capacity under an intermittent hyetograph +Figure 4-3 cumulative infiltration as the area under the Horton curve +Figure 4-4 regeneration of capacity during dry weather (the recovery curve) +Figure 4-6 Green-Ampt capacity versus cumulative infiltration +Figure 4-7 Green-Ampt recovery parameters versus saturated conductivity + +No engine run: the curves are Equations 4-1, 4-3, 4-6, 4-27, 4-29 and +4-35 to 4-37 evaluated in numpy with the parameter values the text quotes, +so a change to a formula in the chapter is a change here. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +F0, FINF, KD = 3.0, 0.5, 4.0 # in/hr, in/hr, 1/hr — a Horton sandy loam +KR = KD / 6.0 # recovery constant (the engine's default kd/6 ratio) + + +def _horton(t): + return FINF + (F0 - FINF) * np.exp(-KD * t) + + +def _fig_4_2(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(7.2, 3.6)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + t = np.linspace(0, 2.0, 400) + fp = _horton(t) + # a stepped hyetograph that exceeds capacity twice + steps = [(0.0, 0.25, 1.2), (0.25, 0.5, 3.5), (0.5, 0.8, 0.8), (0.8, 1.1, 2.2), (1.1, 1.4, 0.4), (1.4, 2.0, 1.4)] + i = np.zeros_like(t) + for a, b, v in steps: + i[(t >= a) & (t < b)] = v + ax.step(t, i, where="post", color=style.MUTED, lw=1.2, label="rainfall intensity i(t)") + ax.plot(t, fp, color=style.COLORS["fv"], lw=2.0, label="infiltration capacity f_p(t) = f_∞ + (f_0 − f_∞) e^(−k_d t)") + f = np.minimum(fp, i) + ax.fill_between(t, 0, f, color=style.COLORS["fv"], alpha=0.15, label="actual infiltration f = min(f_p, i)") + ax.fill_between(t, f, i, where=i > fp, color=style.COLORS["dw-slot"], alpha=0.35, label="runoff (i exceeds f_p)") + ax.axhline(FINF, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.text(1.98, FINF + 0.06, "f_∞", fontsize=8, color=style.MUTED, ha="right") + ax.text(0.02, F0 - 0.15, "f_0", fontsize=8, color=style.COLORS["fv"]) + ax.set_xlabel("time from the start of the storm t (h)") + ax.set_ylabel("rate (in/h)") + ax.set_xlim(0, 2) + ax.set_ylim(0, 3.8) + ax.legend(loc="upper right", fontsize=7) + fig.tight_layout() + return fig + + +def _fig_4_3(style): + import matplotlib.pyplot as plt + fig, (a1, a2) = plt.subplots(1, 2, figsize=(7.6, 3.2)) + fig.patch.set_facecolor(style.SURFACE) + for ax in (a1, a2): + style.style_ax(ax) + t = np.linspace(0, 2.0, 400) + tp = 0.6 + a1.plot(t, _horton(t), color=style.COLORS["fv"], lw=2.0) + m = t <= tp + a1.fill_between(t[m], 0, _horton(t[m]), color=style.COLORS["fv"], alpha=0.2) + a1.axvline(tp, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + a1.text(tp + 0.03, 3.3, "t_p", fontsize=8, color=style.MUTED) + a1.text(tp / 2, 0.9, "F(t_p)", fontsize=9, color=style.COLORS["fv"], ha="center") + a1.set_xlabel("t (h)") + a1.set_ylabel("f_p (in/h)") + a1.set_title("F is the area under the capacity curve", fontsize=9) + a1.set_ylim(0, 3.6) + F = FINF * t + (F0 - FINF) / KD * (1 - np.exp(-KD * t)) + a2.plot(t, F, color=style.COLORS["fv"], lw=2.0) + a2.plot(t, FINF * t + (F0 - FINF) / KD, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + a2.text(1.4, FINF * 1.4 + (F0 - FINF) / KD + 0.08, "asymptote f_∞ t + (f_0 − f_∞)/k_d", fontsize=7, color=style.MUTED) + a2.set_xlabel("t_p (h)") + a2.set_ylabel("F (in)") + a2.set_title("F(t_p) = f_∞ t_p + (f_0 − f_∞)(1 − e^(−k_d t_p))/k_d", fontsize=9) + fig.tight_layout() + return fig + + +def _fig_4_4(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(7.2, 3.6)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + t1 = 0.4 # rain stops; recovery begins at f_r + kr = KD / 8.0 # a slow recovery makes the projection visible + fr = _horton(t1) + tw = t1 - np.log((F0 - FINF) / (F0 - fr)) / kr # Equation 4-8 + t_wet = np.linspace(0, t1, 200) + t_dry = np.linspace(t1, 6.0, 400) + rec = F0 - (F0 - FINF) * np.exp(-kr * (t_dry - tw)) # Equation 4-6 + t_proj = np.linspace(tw, t1, 100) + ax.plot(t_wet, _horton(t_wet), color=style.COLORS["fv"], lw=2.0, label="capacity decays while wet (Eq. 4-1)") + ax.plot(t_dry, rec, color=style.COLORS["dw"], lw=2.0, label="capacity recovers while dry (Eq. 4-6)") + ax.plot(t_proj, F0 - (F0 - FINF) * np.exp(-kr * (t_proj - tw)), color=style.COLORS["dw"], lw=1.0, + ls=(0, (3, 2)), label="recovery curve projected back to t_w, where f_p = f_∞ (Eq. 4-8)") + ax.axhline(F0, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.axhline(FINF, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.plot([t1], [fr], marker="o", ms=5, color=style.INK) + ax.text(t1 + 0.1, fr + 0.12, "f_r at t_pr, when rain stops", fontsize=8, color=style.INK) + ax.plot([tw], [FINF], marker="o", ms=5, mfc="white", mec=style.COLORS["dw"]) + ax.text(tw, FINF - 0.22, "t_w", fontsize=8, color=style.COLORS["dw"], ha="center") + ax.axvspan(0, t1, color=style.WATER, alpha=0.07) + ax.text(t1 / 2, 3.45, "wet", fontsize=8, color=style.MUTED, ha="center") + ax.text(1.4, 3.45, "dry", fontsize=8, color=style.MUTED, ha="center") + ax.text(5.95, F0 - 0.2, "f_0", fontsize=8, color=style.MUTED, ha="right") + ax.text(5.95, FINF + 0.06, "f_∞", fontsize=8, color=style.MUTED, ha="right") + ax.set_xlabel("time (h)") + ax.set_ylabel("f_p (in/h)") + ax.set_xlim(min(tw, 0) - 0.15, 6) + ax.set_ylim(0, 3.8) + ax.legend(loc="center right", fontsize=7) + fig.tight_layout() + return fig + + +def _fig_4_6(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(7.2, 3.6)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + Ks, psi, thd, i = 0.25, 6.5, 0.20, 1.0 # in/h, in, —, in/h (the chapter's example) + Fs = Ks * psi * thd / (i - Ks) # Equation 4-29 + F = np.linspace(0.01, 4.0, 600) + fp = Ks * (1 + psi * thd / F) # Equation 4-27 + ax.plot(F[F <= Fs], np.full((F <= Fs).sum(), i), color=style.COLORS["fv"], lw=2.2, label="before saturation: f = i") + ax.plot(F[F >= Fs], fp[F >= Fs], color=style.COLORS["dw"], lw=2.2, label="after saturation: f_p = K_s (1 + ψ_s θ_d / F)") + ax.plot(F, fp, color=style.COLORS["dw"], lw=0.8, ls=(0, (2, 3)), alpha=0.7) + ax.axhline(Ks, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.axvline(Fs, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.text(Fs + 0.05, 1.9, f"F_s = K_s ψ_s θ_d / (i − K_s) = {Fs:.2f} in", fontsize=8, color=style.MUTED) + ax.text(3.95, Ks - 0.09, "K_s = 0.25 in/h", fontsize=8, color=style.MUTED, ha="right", va="top") + ax.set_xlabel("cumulative infiltration F (in)") + ax.set_ylabel("infiltration rate (in/h)") + ax.set_xlim(0, 4) + ax.set_ylim(0, 2.1) + ax.set_title("K_s = 0.25 in/h, ψ_s = 6.5 in, θ_d = 0.20, rainfall i = 1.0 in/h", fontsize=9) + ax.legend(loc="upper right", fontsize=7.5) + fig.tight_layout() + return fig + + +def _fig_4_7(style): + import matplotlib.pyplot as plt + fig, axes = plt.subplots(1, 3, figsize=(8.4, 2.9)) + fig.patch.set_facecolor(style.SURFACE) + Ks = np.linspace(0.02, 2.0, 300) + series = [("L_u = 4 √K_s (in)", 4 * np.sqrt(Ks), style.COLORS["fv"]), + ("k_r = √K_s / 75 (1/h)", np.sqrt(Ks) / 75, style.COLORS["dw"]), + ("T_r = 4.5 / √K_s (h)", 4.5 / np.sqrt(Ks), style.COLORS["fv-lts"])] + for ax, (label, y, c) in zip(axes, series): + style.style_ax(ax) + ax.plot(Ks, y, color=c, lw=2.0) + ax.set_title(label, fontsize=9) + ax.set_xlabel("K_s (in/h)") + ax.set_xlim(0, 2) + axes[0].set_ylabel("upper-zone depth L_u") + axes[1].set_ylabel("recovery rate k_r") + axes[2].set_ylabel("minimum dry time T_r") + fig.tight_layout() + return fig + + +def build(sink): + import style + for fid, fn in (("hydrology_ch4_horton_curve", _fig_4_2), ("hydrology_ch4_horton_cumulative", _fig_4_3), + ("hydrology_ch4_horton_recovery", _fig_4_4), ("hydrology_ch4_green_ampt_curve", _fig_4_6), + ("hydrology_ch4_green_ampt_recovery_params", _fig_4_7)): + if fid in sink.expected: + sink.save(fn(style), fid) diff --git a/docs/figures/src/hydrology/ch5_two_zone_column.py b/docs/figures/src/hydrology/ch5_two_zone_column.py new file mode 100644 index 000000000..f2bbf3d2a --- /dev/null +++ b/docs/figures/src/hydrology/ch5_two_zone_column.py @@ -0,0 +1,132 @@ +"""The per-subcatchment two-zone groundwater model (hydrology Chapter 5). + +Figure 5-1 definitional sketch: upper unsaturated zone, lower saturated + zone, and the six fluxes of the moisture balance (also the + Engine Manual's Figure 1-14) +Figure 5-2 the heights that enter the lateral groundwater flow equation: + the water table H_GW, the receiving node's water surface H_SW, + the threshold H* (default: the node invert) and the aquifer bottom + +Synthetic geometry; replaces two 470–740 px EPA drawings. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +SOIL_UNSAT = "#e7d9bf" +SOIL_SAT = "#b9cfe6" +BEDROCK = "#cfc9bd" + + +def _flux(ax, x, y0, y1, text, style, dx=0.02, ha="left", both=False): + ax.annotate("", xy=(x, y1), xytext=(x, y0), + arrowprops=dict(arrowstyle="<|-|>" if both else "-|>", color=style.WATER, lw=1.4, mutation_scale=11)) + ax.text(x + dx, (y0 + y1) / 2, text, fontsize=7.6, color=style.WATER, va="center", ha=ha, fontstyle="italic", + bbox=dict(boxstyle="round,pad=0.15", fc=style.SURFACE, ec="none", alpha=0.9)) + + +def _fig_5_1(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle + fig, ax = plt.subplots(figsize=(7.4, 3.9)) + fig.patch.set_facecolor(style.SURFACE) + x0, x1 = 0.6, 5.4 + zb, zwt, zs = 0.0, 1.5, 3.3 # bottom, water table, ground surface + ax.add_patch(Rectangle((x0, zwt), x1 - x0, zs - zwt, fc=SOIL_UNSAT, ec=style.INK, lw=1.0, zorder=1)) + ax.add_patch(Rectangle((x0, zb), x1 - x0, zwt - zb, fc=SOIL_SAT, ec=style.INK, lw=1.0, zorder=1)) + ax.add_patch(Rectangle((x0, zb - 0.35), x1 - x0, 0.35, fc=BEDROCK, ec=style.INK, lw=1.0, hatch="//", zorder=1)) + rng = np.random.default_rng(5) + ax.scatter(x0 + rng.random(70) * (x1 - x0), zwt + rng.random(70) * (zs - zwt), s=2, color="#a08a5e", alpha=0.5, zorder=2) + ax.plot([x0, x1], [zwt, zwt], color=style.WATER, lw=1.2, ls=(0, (5, 2)), zorder=3) + ax.text(x0 + 0.08, zwt + 0.06, "water table", fontsize=7.5, color=style.WATER, ha="left") + # grass and the ground line + for x in np.linspace(x0 + 0.1, x1 - 0.1, 22): + ax.plot([x, x - 0.03, x, x + 0.03], [zs, zs + 0.14, zs, zs + 0.12], color="#6f8a4f", lw=0.9) + ax.text(x0 - 0.08, (zwt + zs) / 2, "upper zone\nunsaturated\nmoisture content θ", fontsize=8, ha="right", + va="center", color=style.INK) + ax.text(x0 - 0.08, (zb + zwt) / 2, "lower zone\nsaturated\nθ = porosity φ", fontsize=8, ha="right", + va="center", color=style.INK) + ax.text(x0 - 0.08, zb - 0.17, "impermeable bottom", fontsize=7.5, ha="right", va="center", color=style.MUTED) + # depths + ax.annotate("", xy=(x1 + 0.25, zs), xytext=(x1 + 0.25, zwt), arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(x1 + 0.32, (zs + zwt) / 2, "d_U", fontsize=8, color=style.MUTED, va="center") + ax.annotate("", xy=(x1 + 0.25, zwt), xytext=(x1 + 0.25, zb), arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(x1 + 0.32, (zwt + zb) / 2, "d_L", fontsize=8, color=style.MUTED, va="center") + # fluxes + W = dict(arrowstyle="-|>", color=style.WATER, lw=1.4, mutation_scale=11) + T = dict(fontsize=7.6, color=style.WATER, fontstyle="italic", va="center", ha="left", + bbox=dict(boxstyle="round,pad=0.15", fc=style.SURFACE, ec="none", alpha=0.9)) + ax.annotate("", xy=(1.0, zs + 0.02), xytext=(1.0, zs + 0.95), arrowprops=W) + ax.text(1.08, zs + 0.92, "f_I infiltration from the surface", **T) + ax.annotate("", xy=(2.9, zs + 0.95), xytext=(2.9, zs + 0.02), arrowprops=W) + ax.text(2.98, zs + 0.62, "f_EU upper-zone ET", **T) + ax.annotate("", xy=(4.4, zs + 0.95), xytext=(4.4, zs + 0.02), arrowprops=W) + ax.text(4.48, zs + 0.30, "f_EL lower-zone ET", **T) + _flux(ax, 1.9, zwt + 0.55, zwt + 0.03, "f_U percolation, upper to lower zone", style) + _flux(ax, 3.9, zb + 0.4, zb - 0.02, "f_L deep percolation (seepage) loss", style) + ax.annotate("", xy=(x1 + 0.9, zwt / 2 + 0.2), xytext=(x1 - 0.02, zwt / 2 + 0.2), + arrowprops=dict(arrowstyle="-|>", color=style.WATER, lw=1.4, mutation_scale=11)) + ax.text(x1 + 0.95, zwt / 2 + 0.2, "f_G lateral groundwater\ninterflow to the\ndrainage system", fontsize=7.6, + color=style.WATER, va="center", fontstyle="italic") + ax.text(x0, zs + 1.05, "Two-zone groundwater model of a subcatchment (fluxes per unit area)", fontsize=9.2, + weight="bold", color=style.INK) + ax.set_xlim(-1.35, 7.4) + ax.set_ylim(zb - 0.5, zs + 1.2) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def _fig_5_2(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle, Polygon + fig, ax = plt.subplots(figsize=(7.4, 3.7)) + fig.patch.set_facecolor(style.SURFACE) + xa0, xa1 = 0.5, 4.2 # aquifer column + zb, hgw, zs = 0.0, 1.9, 3.2 # bottom, water table, surface + ax.add_patch(Rectangle((xa0, hgw), xa1 - xa0, zs - hgw, fc=SOIL_UNSAT, ec=style.INK, lw=1.0)) + ax.add_patch(Rectangle((xa0, zb), xa1 - xa0, hgw - zb, fc=SOIL_SAT, ec=style.INK, lw=1.0)) + ax.add_patch(Rectangle((xa0, zb - 0.3), 6.2, 0.3, fc=BEDROCK, ec=style.INK, lw=1.0, hatch="//")) + # receiving channel / node to the right + ch = Polygon([(4.2, zs), (4.9, 0.9), (6.1, 0.9), (6.7, zs)], closed=True, fc="#f4f3ef", ec=style.INK, lw=1.0) + ax.add_patch(ch) + hsw = 1.55 + ax.add_patch(Polygon([(4.9 - (hsw - 0.9) * 0.3, hsw), (4.9, 0.9), (6.1, 0.9), (6.1 + (hsw - 0.9) * 0.26, hsw)], + closed=True, fc=style.WATER, alpha=0.25, ec="none")) + ax.plot([4.9 - (hsw - 0.9) * 0.3, 6.1 + (hsw - 0.9) * 0.26], [hsw, hsw], color=style.WATER, lw=1.2) + ax.plot([xa0, xa1], [hgw, hgw], color=style.WATER, lw=1.2, ls=(0, (5, 2))) + ax.text(xa1 - 0.05, hgw + 0.06, "water table", fontsize=7.5, color=style.WATER, ha="right") + ax.text(5.45, zs + 0.12, "receiving node or channel", fontsize=7.8, ha="center", va="bottom", color=style.INK) + # flow arrow + ax.annotate("", xy=(5.05, 1.25), xytext=(xa1 - 0.3, 1.25), + arrowprops=dict(arrowstyle="-|>", color=style.WATER, lw=1.6, mutation_scale=12)) + ax.text(4.35, 1.36, "Q_GW", fontsize=8.5, color=style.WATER, fontstyle="italic") + # heights measured from the aquifer bottom + def height(x, z, text, color): + ax.annotate("", xy=(x, z), xytext=(x, zb), arrowprops=dict(arrowstyle="<->", color=color, lw=0.9)) + ax.text(x + 0.06, z / 2, text, fontsize=8, color=color, va="center") + height(2.0, hgw, "H_GW groundwater head", style.INK) + height(7.05, hsw, "H_SW surface water height", style.INK) + ax.plot([4.5, 7.3], [0.9, 0.9], color=style.MUTED, lw=0.9, ls=(0, (3, 2))) + ax.text(7.35, 1.22, "H* threshold (dashed; default: the node invert)", fontsize=7.4, color=style.MUTED, va="bottom") + ax.plot([0.2, 7.3], [zb, zb], color=style.MUTED, lw=0.6) + ax.text(7.35, zb + 0.02, "aquifer bottom: the datum of every height", fontsize=7.4, color=style.MUTED, va="bottom") + ax.text(xa0, zs + 0.95, "Heights in the lateral groundwater flow equation", fontsize=9.2, weight="bold", color=style.INK) + ax.text(xa0, zs + 0.55, "Q_GW = A1 (H_GW − H*)^B1 − A2 (H_SW − H*)^B2 + A3 · H_GW · H_SW", fontsize=8.4, color=style.INK) + ax.set_xlim(0.1, 10.4) + ax.set_ylim(zb - 0.45, zs + 1.15) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + if "hydrology_ch5_two_zone" in sink.expected: + sink.save(_fig_5_1(style), "hydrology_ch5_two_zone") + if "hydrology_ch5_lateral_flow_heights" in sink.expected: + sink.save(_fig_5_2(style), "hydrology_ch5_lateral_flow_heights") diff --git a/docs/figures/src/hydrology/ch6_adc_curves.py b/docs/figures/src/hydrology/ch6_adc_curves.py new file mode 100644 index 000000000..32efb86be --- /dev/null +++ b/docs/figures/src/hydrology/ch6_adc_curves.py @@ -0,0 +1,49 @@ +"""Areal depletion curves (hydrology Figure 6-4 and the Engine Manual's +Figure 1-6). + +The ADC maps the dimensionless snow depth AWESI = WSNOW / SI to the areal +snow cover fraction ASC. The natural-area curve is Anderson's (1973) +typical shape; the temporary curve is the straight line the engine uses +for new snow falling on a partly bare pack, from the origin to the point +of the natural curve where the new-snow event began. Plotted from the +tabulated points; replaces a 371 × 274 px bitmap. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +# Anderson (1973) typical natural-area ADC, as tabulated in the chapter's example +AWESI = np.array([0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]) +ASC = np.array([0.0, 0.35, 0.53, 0.66, 0.76, 0.84, 0.90, 0.94, 0.97, 0.99, 1.0]) + + +def _draw(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(6.4, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + x = np.linspace(0, 1, 200) + ax.plot(x, np.interp(x, AWESI, ASC), color=style.COLORS["fv"], lw=2.2, label="natural-area curve (Anderson, 1973)") + ax.plot(AWESI, ASC, marker="o", ms=3.5, color=style.COLORS["fv"], lw=0) + a0 = 0.35 + ax.plot([0, a0], [0, np.interp(a0, AWESI, ASC)], color=style.COLORS["dw-slot"], lw=1.8, ls=(0, (4, 2)), + label="temporary curve for new snow on a partly bare pack") + ax.plot([a0], [np.interp(a0, AWESI, ASC)], marker="o", ms=6, mfc="white", mec=style.COLORS["dw-slot"]) + ax.text(a0 + 0.02, np.interp(a0, AWESI, ASC) - 0.07, "pack state when\nthe new snow fell", fontsize=7.4, + color=style.COLORS["dw-slot"]) + ax.plot([1, 1.15], [1, 1], color=style.COLORS["fv"], lw=2.2) + ax.text(1.14, 0.955, "ASC = 1 for AWESI ≥ 1", fontsize=7.4, color=style.MUTED, ha="right", va="top") + ax.set_xlabel("AWESI = WSNOW / SI (snow depth as a fraction of the depth at 100 % cover)") + ax.set_ylabel("ASC (areal snow cover fraction)") + ax.set_xlim(0, 1.15) + ax.set_ylim(0, 1.05) + ax.legend(loc="lower right", fontsize=7.5) + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch6_areal_depletion_curve") diff --git a/docs/figures/src/hydrology/ch7_ia_seasonal.py b/docs/figures/src/hydrology/ch7_ia_seasonal.py new file mode 100644 index 000000000..f0a240963 --- /dev/null +++ b/docs/figures/src/hydrology/ch7_ia_seasonal.py @@ -0,0 +1,71 @@ +"""Seasonal behaviour of the exponential-decay initial-abstraction model +(hydrology Figure 7-11, §7.6). + +A one-year synthetic forcing — random storms and a sinusoidal temperature — +drives the available initial abstraction IA_avail: each storm depletes it +in proportion to rainfall, dry weather restores it at a temperature- +dependent rate, and recovery is suspended while the ground is frozen. The +RDII response is the rainfall in excess of the abstraction. Schematic: +deterministic seed, engine-free, so the seasonal pattern the section +describes is visible without a project. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + rng = np.random.default_rng(7) + days = np.arange(365) + temp = 10 + 15 * np.sin(2 * np.pi * (days - 100) / 365) + rain = np.where(rng.random(365) < 0.25, rng.gamma(2.0, 6.0, 365), 0.0) + ia_max, ia = 25.0, 12.0 + k_dep, r_rec, ddf, t_freeze = 0.08, 0.6, 0.12, 0.0 + ia_series, rdii = [], [] + for d in days: + ia = max(ia - k_dep * rain[d] * ia / ia_max * 3, 0.0) + rec = 0.0 if temp[d] < t_freeze else r_rec * (1 + ddf * max(temp[d], 0)) * 0.15 + ia = min(ia + rec, ia_max) + ia_series.append(ia) + rdii.append(max(rain[d] - (ia / ia_max) * rain[d], 0.0) * 0.12) + fig, axes = plt.subplots(3, 1, figsize=(8.6, 6.0), sharex=True) + fig.patch.set_facecolor(style.SURFACE) + for ax in axes: + style.style_ax(ax) + axes[0].bar(days, rain, color=style.WATER, width=1.0, label="rainfall") + ax0b = axes[0].twinx() + ax0b.plot(days, temp, color=style.COLORS["fv-lts"], lw=1.3, label="air temperature") + ax0b.axhline(t_freeze, color=style.COLORS["fv-lts"], ls=(0, (2, 2)), lw=0.8) + ax0b.set_ylabel("temperature (°C)", color=style.COLORS["fv-lts"]) + ax0b.tick_params(colors=style.MUTED, labelsize=9) + for s in ("top",): + ax0b.spines[s].set_visible(False) + axes[0].set_ylabel("rainfall (mm/d)") + frozen = temp < t_freeze + axes[1].fill_between(days, 0, ia_max * 1.1, where=frozen, color=style.GRIDC, alpha=0.7, + label="frozen ground: recovery suspended") + axes[1].plot(days, ia_series, color=style.COLORS["dw"], lw=1.6, label="available initial abstraction IA_avail") + axes[1].axhline(ia_max, color=style.MUTED, ls=(0, (3, 2)), lw=0.8) + axes[1].text(3, ia_max + 0.6, "IA_max", fontsize=8, color=style.MUTED) + axes[1].set_ylabel("IA_avail (mm)") + axes[1].set_ylim(0, ia_max * 1.15) + axes[1].legend(loc="upper center", fontsize=7.5, ncol=2) + axes[2].plot(days, rdii, color=style.COLORS["fv"], lw=1.3) + axes[2].fill_between(days, 0, rdii, color=style.COLORS["fv"], alpha=0.15) + axes[2].set_ylabel("RDII response\n(schematic)") + axes[2].set_xlabel("day of year") + axes[2].set_xlim(0, 364) + for ax, t in zip(axes, ("forcing: storms deplete the abstraction, warmth restores it", + "the abstraction store: depletion by rain, temperature-dependent recovery, frozen-ground hold", + "RDII: the same storm yields more inflow when the store is depleted or frozen")): + ax.set_title(t, fontsize=8.6, loc="left", color=style.INK) + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch7_ia_seasonal") diff --git a/docs/figures/src/hydrology/ch7_rtk_unit_hydrograph.py b/docs/figures/src/hydrology/ch7_rtk_unit_hydrograph.py new file mode 100644 index 000000000..86831eafd --- /dev/null +++ b/docs/figures/src/hydrology/ch7_rtk_unit_hydrograph.py @@ -0,0 +1,84 @@ +"""RDII unit hydrographs (hydrology Figure 7-4 and the Engine Manual's +Figure 1-7). + +A single RTK unit hydrograph is a triangle with peak at time T, base +T(1 + K) and area R (the fraction of rainfall that becomes RDII). The +engine sums three of them — short, medium and long response — for each +unit of rainfall. Both figures are the triangles drawn from (R, T, K); +they replace two low-resolution EPA bitmaps. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +# (R, T hours, K) — a typical short / medium / long set +UH = [(0.030, 1.0, 2.0), (0.040, 4.0, 3.0), (0.030, 12.0, 4.0)] + + +def _triangle(t, R, T, K): + """Ordinates of the unit hydrograph (per unit rainfall depth, per hour) with area R.""" + base = T * (1 + K) + peak = 2 * R / base + return np.where(t <= T, peak * t / T, np.where(t <= base, peak * (base - t) / (base - T), 0.0)) + + +def _single(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(6.2, 3.4)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + R, T, K = 0.05, 3.0, 2.0 + t = np.linspace(0, T * (1 + K) + 1, 400) + q = _triangle(t, R, T, K) + ax.fill_between(t, 0, q, color=style.COLORS["fv"], alpha=0.18) + ax.plot(t, q, color=style.COLORS["fv"], lw=2.2) + ax.axvline(T, color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ax.axvline(T * (1 + K), color=style.MUTED, lw=0.8, ls=(0, (3, 2))) + ymax = q.max() + ax.annotate("", xy=(T, -0.06 * ymax), xytext=(0, -0.06 * ymax), arrowprops=dict(arrowstyle="<->", color=style.INK, lw=0.9)) + ax.text(T / 2, -0.09 * ymax, "T (time to peak)", fontsize=8, ha="center", va="top", color=style.INK) + ax.annotate("", xy=(T * (1 + K), -0.06 * ymax), xytext=(T, -0.06 * ymax), arrowprops=dict(arrowstyle="<->", color=style.INK, lw=0.9)) + ax.text(T + T * K / 2, -0.09 * ymax, "K · T (recession)", fontsize=8, ha="center", va="top", color=style.INK) + ax.text(T * 0.55, ymax * 0.45, "area = R\n(fraction of rainfall\nbecoming RDII)", fontsize=8, ha="center", + color=style.COLORS["fv"]) + ax.set_xlabel("time since the unit of rainfall (h)") + ax.set_ylabel("RDII flow per unit rainfall") + ax.set_xlim(0, T * (1 + K) + 1) + ax.set_ylim(-0.22 * ymax, 1.15 * ymax) + ax.set_yticks([]) + fig.tight_layout() + return fig + + +def _three(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(7.2, 3.8)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + t = np.linspace(0, 65, 800) + total = np.zeros_like(t) + colours = [style.COLORS["fv"], style.COLORS["dw"], style.COLORS["fv-lts"]] + names = ["short-term response (R1, T1, K1)", "intermediate response (R2, T2, K2)", "long-term response (R3, T3, K3)"] + for (R, T, K), c, name in zip(UH, colours, names): + q = _triangle(t, R, T, K) + total += q + ax.plot(t, q, color=c, lw=1.6, label=name) + ax.fill_between(t, 0, q, color=c, alpha=0.10) + ax.plot(t, total, color=style.INK, lw=2.2, label="total RDII unit hydrograph (sum)") + ax.set_xlabel("time since the unit of rainfall (h)") + ax.set_ylabel("RDII flow per unit rainfall per unit area") + ax.set_xlim(0, 65) + ax.set_yticks([]) + ax.legend(loc="upper right", fontsize=7.5) + fig.tight_layout() + return fig + + +def build(sink): + import style + if "eng_rdii_unit_hydrograph" in sink.expected: + sink.save(_single(style), "eng_rdii_unit_hydrograph") + if "hydrology_ch7_rtk_unit_hydrographs" in sink.expected: + sink.save(_three(style), "hydrology_ch7_rtk_unit_hydrographs") diff --git a/docs/figures/src/hydrology/ch8_cell_budget.py b/docs/figures/src/hydrology/ch8_cell_budget.py new file mode 100644 index 000000000..4f1976cff --- /dev/null +++ b/docs/figures/src/hydrology/ch8_cell_budget.py @@ -0,0 +1,98 @@ +"""The water balance of one mesh cell (hydrology Chapter 8, §8.1 and +§8.3.4). + +Every term of the cell volume update (8-6) drawn on one cell in section: +interpolated rainfall in, evaporation and infiltration out through their +shared dry-depth ramp, the held coupling flux with the 1D network, the +aquifer's return from Chapter 9, and the face fluxes exchanged with the +neighbouring cells. Inset: the cubic Hermite ramp both sinks pass through +below DRY_DEPTH, which is what lets a drying cell shut them off together. +Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon, Rectangle, Circle + fig, ax = plt.subplots(figsize=(8.8, 4.6)) + fig.patch.set_facecolor(style.SURFACE) + INK, WA, OR, DW, FV = style.INK, style.WATER, style.COLORS["fv-lts"], style.COLORS["dw"], style.COLORS["fv"] + # terrain: the cell in the middle, neighbours either side + xs = [0.0, 3.0, 7.0, 10.0] + zb = [2.25, 1.85, 1.55, 1.2] + ax.add_patch(Polygon([(xs[0], zb[0]), (xs[3], zb[3]), (xs[3], -0.9), (xs[0], -0.9)], closed=True, + fc=style.SOIL, ec="none", zorder=0)) + ax.plot(xs, zb, color=INK, lw=1.4, zorder=3) + # water in the three cells + h = [0.55, 0.85, 0.5] + for k in range(3): + x0, x1 = xs[k], xs[k + 1] + z0, z1 = zb[k], zb[k + 1] + top = max(z0, z1) + h[k] + ax.add_patch(Polygon([(x0, z0), (x1, z1), (x1, top), (x0, top)], closed=True, + fc=WA, alpha=0.32 if k == 1 else 0.20, ec=WA, lw=1.1, zorder=2)) + ax.plot([x0, x0], [z0 - 0.5, top + 0.15], color=style.MUTED, lw=0.9, ls=(0, (3, 2)), zorder=1) + ax.plot([xs[3], xs[3]], [zb[3] - 0.5, zb[3] + h[2] + 0.15], color=style.MUTED, lw=0.9, ls=(0, (3, 2)), zorder=1) + ax.text(5.0, 2.05, "cell i", fontsize=9.5, ha="center", weight="bold", color=INK, zorder=5) + ax.text(5.0, 1.82, "depth h_i, area A_i, volume V_i", fontsize=7.4, ha="center", color=INK, zorder=5) + ax.text(1.5, 1.6, "neighbour", fontsize=7.6, ha="center", color=style.MUTED) + ax.text(8.9, 1.05, "neighbour", fontsize=7.6, ha="center", color=style.MUTED) + A = lambda col, lw=1.7: dict(arrowstyle="-|>", color=col, lw=lw, mutation_scale=13) # noqa: E731 + # rainfall in + for x in (4.2, 5.0, 5.8): + ax.annotate("", xy=(x, 2.62), xytext=(x, 3.55), arrowprops=A(WA, 1.4)) + ax.text(3.95, 3.66, "r_i interpolated rainfall (§8.2)", fontsize=7.8, color=WA) + # evaporation out + ax.annotate("", xy=(6.6, 3.55), xytext=(6.6, 2.55), arrowprops=A(OR)) + ax.text(6.72, 3.2, "e*_i evaporation,\nramped (§8.5)", fontsize=7.8, color=OR) + # infiltration out + ax.annotate("", xy=(4.6, 0.55), xytext=(4.6, 1.62), arrowprops=A(OR)) + ax.text(4.45, 0.42, "f*_i infiltration, ramped (§8.3)\n→ lost · subcatchment aquifer\n · mesh aquifer (§8.4)", + fontsize=7.8, ha="left", va="top", color=OR) + # aquifer return up + ax.annotate("", xy=(3.55, 1.72), xytext=(3.55, 0.75), arrowprops=A(DW, 1.5)) + ax.text(3.45, 0.62, "g_i aquifer return\n(Chapter 9)", fontsize=7.6, ha="right", va="top", color=DW) + # coupling with a node + ax.add_patch(Rectangle((6.35, -0.62), 0.9, 0.62, fc="#d9e6f5", ec=INK, lw=1.0, zorder=2)) + ax.add_patch(Rectangle((6.65, 0.0), 0.3, 1.45, fc="#d9e6f5", ec=INK, lw=0.9, zorder=2)) + ax.add_patch(Circle((6.8, 1.45), 0.13, fc="#bfbfbf", ec=INK, lw=0.9, zorder=4)) + ax.annotate("", xy=(6.8, 1.62), xytext=(6.8, 0.95), + arrowprops=dict(arrowstyle="<|-|>", color=DW, lw=1.6, mutation_scale=11)) + ax.text(7.35, 0.75, "s_i held coupling flux\nwith the 1D network", fontsize=7.6, color=DW) + # face fluxes + ax.annotate("", xy=(3.3, 2.05), xytext=(2.6, 2.05), arrowprops=A(FV, 1.6)) + ax.annotate("", xy=(7.4, 1.75), xytext=(6.7, 1.75), arrowprops=A(FV, 1.6)) + ax.text(2.55, 2.22, "ΣΔV face fluxes to and from the neighbours (Hydraulics Ch. 9)", fontsize=7.6, color=FV) + # the update equation + ax.text(-0.15, -1.35, "V_i ← max( 0, V_i + Δt A_i ( r_i + s_i + g_i − e*_i − f*_i ) + Σ_faces ΔV )", + fontsize=9, color=INK) + ax.text(-0.15, -1.75, "the same terms the 2D Surface Routing Continuity block of the report prints", + fontsize=7.4, color=style.MUTED) + # inset: the shared ramp + ins = ax.inset_axes([0.775, 0.07, 0.205, 0.26]) + t = np.linspace(0, 1.6, 300) + ramp = np.where(t >= 1.0, 1.0, t ** 2 * (3 - 2 * t)) + ins.plot(t, ramp, color=OR, lw=1.6) + ins.axvline(1.0, color=style.MUTED, lw=0.8, ls=(0, (2, 2))) + ins.set_xticks([0, 1.0]) + ins.set_xticklabels(["0", "DRY_DEPTH"], fontsize=6.4) + ins.set_yticks([0, 1]) + ins.tick_params(labelsize=6.4) + ins.set_xlabel("cell depth h_i", fontsize=6.6, labelpad=1) + ins.set_title("both sinks share this ramp", fontsize=6.8, color=style.MUTED) + ins.set_facecolor(style.SURFACE) + ax.set_xlim(-0.4, 10.6) + ax.set_ylim(-2.0, 4.1) + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch8_cell_budget") diff --git a/docs/figures/src/hydrology/ch8_infiltration_strip.py b/docs/figures/src/hydrology/ch8_infiltration_strip.py new file mode 100644 index 000000000..c85f25c58 --- /dev/null +++ b/docs/figures/src/hydrology/ch8_infiltration_strip.py @@ -0,0 +1,108 @@ +"""Per-cell infiltration: parameter resolution and the held rate +(hydrology Chapter 8, §8.3.3 and §8.3.4). + +(a) A strip of cells carrying three soil tags. Each cell takes its method +and parameters by the resolution order — a cell override beats a TAG row, +which beats the mesh-wide `*` row — and a row whose method is NONE clears +the default for its cells rather than inheriting it. (b) The kernel is +called on the INFIL_STEP cadence and the rate it returns is held between +calls, so the sink the marcher consumes is a step function whatever the +substep. Synthetic; the Horton curve is its own analytic decay, no model +run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +# (tag, cells, method, note) in strip order +TAGS = [("SILT", 3, "GREEN_AMPT", "TAG row"), + ("SAND", 3, "HORTON", "TAG row"), + ("CLAY", 3, "NONE", "TAG row clears the default")] +OVERRIDE_CELL = 5 # 1-based, inside the SAND run +OVERRIDE_METHOD = "CURVE_NUMBER" + +F0, FC, K = 3.0, 0.5, 4.5 # in/hr, in/hr, 1/hr — a Horton decay for panel (b) +INFIL_STEP = 0.25 # hr + + +def _strip(ax, style): + from matplotlib.patches import Rectangle + fills = {"SILT": "#e2d6bd", "SAND": "#efe3c3", "CLAY": "#cfc4ae"} + x = 0.0 + idx = 0 + for tag, n, method, note in TAGS: + for _ in range(n): + idx += 1 + over = idx == OVERRIDE_CELL + m = OVERRIDE_METHOD if over else method + ax.add_patch(Rectangle((x, 0), 1.0, 1.0, fc=fills[tag], ec=style.INK, lw=1.0)) + if over: + ax.add_patch(Rectangle((x, 0), 1.0, 1.0, fc="none", ec=style.COLORS["fv-lts"], lw=2.2)) + ax.text(x + 0.5, 0.62, f"cell {idx}", fontsize=6.8, ha="center", color=style.MUTED) + ax.text(x + 0.5, 0.34, m.replace("_", "\n"), fontsize=6.6, ha="center", va="center", + color=style.COLORS["fv-lts"] if over else style.INK) + x += 1.0 + x0 = x - n + ax.plot([x0, x], [-0.18, -0.18], color=style.INK, lw=1.0) + ax.text((x0 + x) / 2, -0.28, f"TAG {tag}", fontsize=7.4, ha="center", va="top", color=style.INK) + ax.text((x0 + x) / 2, -0.58, note, fontsize=6.8, ha="center", va="top", color=style.MUTED) + ax.annotate("", xy=(OVERRIDE_CELL - 0.5, 1.08), xytext=(OVERRIDE_CELL - 0.5, 1.62), + arrowprops=dict(arrowstyle="-|>", color=style.COLORS["fv-lts"], lw=1.3, mutation_scale=11)) + ax.text(OVERRIDE_CELL - 0.5, 1.70, "[2D_INFILTRATION] CELL row — a per-cell override", + fontsize=7.4, ha="center", color=style.COLORS["fv-lts"]) + ax.text(0.0, 2.35, "resolution order: cell override > TAG row > `*` row > none", + fontsize=8.2, color=style.INK) + ax.text(0.0, 2.02, "the `*` row of [2D_INFILTRATION_DEFAULTS] is the mesh-wide fallback; " + "a NONE row deliberately clears it", fontsize=7.2, color=style.MUTED) + ax.set_xlim(-0.3, 9.3) + ax.set_ylim(-1.15, 2.6) + ax.set_aspect("equal") + ax.axis("off") + + +def _held(ax, style): + t = np.linspace(0, 2.0, 800) + cont = FC + (F0 - FC) * np.exp(-K * t) + ax.plot(t, cont, color=style.MUTED, lw=1.1, ls=(0, (4, 2)), label="the kernel's continuous capacity") + edges = np.arange(0, 2.0 + 1e-9, INFIL_STEP) + for k in range(len(edges) - 1): + f = FC + (F0 - FC) * np.exp(-K * edges[k]) + ax.plot([edges[k], edges[k + 1]], [f, f], color=style.COLORS["fv"], lw=2.0, + label="the held rate f_i the marcher consumes" if k == 0 else None) + if k: + fp = FC + (F0 - FC) * np.exp(-K * edges[k - 1]) + ax.plot([edges[k], edges[k]], [fp, f], color=style.COLORS["fv"], lw=2.0) + ax.plot([edges[k]], [f], marker="o", ms=3.4, color=style.COLORS["fv"]) + for e in edges: + ax.axvline(e, color=style.GRIDC, lw=0.6, zorder=0) + ax.annotate("", xy=(edges[1], 0.15), xytext=(edges[2], 0.15), + arrowprops=dict(arrowstyle="<->", color=style.INK, lw=0.9)) + ax.text(edges[1] + INFIL_STEP / 2, 0.24, "INFIL_STEP", fontsize=7.4, ha="center", color=style.INK) + ax.set_xlabel("time (hr)") + ax.set_ylabel("infiltration rate (in/hr)") + ax.set_ylim(0, F0 * 1.12) + ax.set_xlim(0, 2.0) + ax.legend(fontsize=7.2, frameon=False, loc="upper right") + ax.set_title("(b) The rate is refreshed on INFIL_STEP and held between calls", fontsize=9, loc="left") + ax.text(0.78, 2.35, "the marcher's substeps are far shorter than INFIL_STEP;\n" + "each consumes the held rate through the dry-depth ramp of (8-5)", fontsize=7.2, color=style.MUTED, + linespacing=1.4) + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(2, 1, figsize=(8.6, 5.4), gridspec_kw=dict(height_ratios=[1.0, 1.15])) + fig.patch.set_facecolor(style.SURFACE) + a0.set_title("(a) How each cell resolves its method and parameters", fontsize=9, loc="left") + _strip(a0, style) + style.style_ax(a1) + _held(a1, style) + fig.tight_layout(pad=0.4) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch8_infiltration_strip") diff --git a/docs/figures/src/hydrology/ch8_nn_weights.py b/docs/figures/src/hydrology/ch8_nn_weights.py new file mode 100644 index 000000000..3bbc66136 --- /dev/null +++ b/docs/figures/src/hydrology/ch8_nn_weights.py @@ -0,0 +1,186 @@ +"""Rainfall weights on the mesh: Laplace natural-neighbour inside the gage +hull, inverse distance outside it (hydrology Chapter 8, §8.2.2). + +Left: six gages and their Delaunay triangulation. Inserting a cell +centroid as a new site carves the cavity of triangles whose circumcircles +contain it and fans that cavity; the fan circumcentres are the vertices of +the centroid's new Voronoi cell, and the facet it shares with each natural +neighbour, over the distance to that gage, is the Laplace weight. Gages +outside the cavity get no weight at all. Right: a centroid beyond the hull +falls back to power-2 inverse distance over every located gage. + +The triangulation, the insertion and the weights are computed here by the +same construction the engine uses, so the numbers on the drawing are the +numbers the interpolator produces. Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +# (name, x, y, mm/hr) +GAGES = [("A", 0.6, 1.2, 10.0), ("B", 4.3, 0.5, 22.0), ("C", 8.0, 1.9, 30.0), + ("D", 7.1, 6.2, 26.0), ("E", 3.2, 7.0, 16.0), ("F", 0.9, 4.6, 12.0)] +P_IN = np.array([5.5, 2.5]) +P_OUT = np.array([10.2, 5.4]) +XY = np.array([[g[1], g[2]] for g in GAGES]) +NAMES = [g[0] for g in GAGES] +RATES = np.array([g[3] for g in GAGES]) + + +def circumcentre(a, b, c): + d = 2.0 * (a[0] * (b[1] - c[1]) + b[0] * (c[1] - a[1]) + c[0] * (a[1] - b[1])) + if abs(d) < 1e-12: + return None + sa, sb, sc = a @ a, b @ b, c @ c + return np.array([(sa * (b[1] - c[1]) + sb * (c[1] - a[1]) + sc * (a[1] - b[1])) / d, + (sa * (c[0] - b[0]) + sb * (a[0] - c[0]) + sc * (b[0] - a[0])) / d]) + + +def in_circumcircle(p, a, b, c): + o = circumcentre(a, b, c) + return o is not None and np.linalg.norm(p - o) < np.linalg.norm(a - o) - 1e-12 + + +def delaunay(pts): + """Bowyer-Watson over a super-triangle; returns index triples into pts.""" + lo, hi = pts.min(axis=0), pts.max(axis=0) + c, r = (lo + hi) / 2, np.linalg.norm(hi - lo) + 1.0 + sup = np.array([c + [0, 3 * r], c + [-3 * r, -2 * r], c + [3 * r, -2 * r]]) + work = np.vstack([pts, sup]) + n = len(pts) + tris = [(n, n + 1, n + 2)] + for i in range(n): + p = work[i] + bad = [t for t in tris if in_circumcircle(p, work[t[0]], work[t[1]], work[t[2]])] + edges = {} + for t in bad: + for e in ((t[0], t[1]), (t[1], t[2]), (t[2], t[0])): + k = tuple(sorted(e)) + edges[k] = edges.get(k, 0) + 1 + tris = [t for t in tris if t not in bad] + tris += [(i, a, b) for (a, b), cnt in edges.items() if cnt == 1] + return [t for t in tris if max(t) < n] + + +def insert_point(p, pts, tris): + """(ordered Voronoi polygon of p, {site index: (facet endpoints, length)}).""" + bad = [t for t in tris if in_circumcircle(p, pts[t[0]], pts[t[1]], pts[t[2]])] + if not bad: + return None, {} + edges = {} + for t in bad: + for e in ((t[0], t[1]), (t[1], t[2]), (t[2], t[0])): + k = tuple(sorted(e)) + edges[k] = edges.get(k, 0) + 1 + hull = [e for e, cnt in edges.items() if cnt == 1] + fan = [(a, b) for a, b in hull] + cc = {} + for a, b in fan: + o = circumcentre(p, pts[a], pts[b]) + if o is None: + return None, {} + cc[tuple(sorted((a, b)))] = o + by_site = {} + for a, b in fan: + for s in (a, b): + by_site.setdefault(s, []).append(tuple(sorted((a, b)))) + facets = {} + for s, keys in by_site.items(): + if len(keys) != 2: + continue + e0, e1 = cc[keys[0]], cc[keys[1]] + facets[s] = ((e0, e1), float(np.linalg.norm(e0 - e1))) + poly = np.array(list(cc.values())) + ang = np.arctan2(poly[:, 1] - p[1], poly[:, 0] - p[0]) + return poly[np.argsort(ang)], facets + + +def _sites(ax, style, weights=None): + for i, (name, x, y, r) in enumerate(GAGES): + on = weights is None or weights.get(i, 0) > 0 + ax.plot(x, y, marker="*", ms=15, mfc="#ffd23f" if on else "#e4e4e4", mec=style.INK, mew=0.9, zorder=6) + ax.text(x, y + 0.36, f"{name} · {r:.0f}", fontsize=7.4, ha="center", + color=style.INK if on else style.MUTED, zorder=6) + + +def _panel_inside(ax, style): + from matplotlib.patches import Polygon + tris = delaunay(XY) + poly, facets = insert_point(P_IN, XY, tris) + raw = {s: L / np.linalg.norm(P_IN - XY[s]) for s, (_, L) in facets.items()} + tot = sum(raw.values()) + w = {s: v / tot for s, v in raw.items()} + for t in tris: + ax.add_patch(Polygon(XY[list(t)], closed=True, fc="none", ec=style.MUTED, lw=0.8, alpha=0.7, zorder=1)) + ax.add_patch(Polygon(poly, closed=True, fc=style.COLORS["fv"], alpha=0.10, ec="none", zorder=2)) + for s, ((e0, e1), L) in facets.items(): + ax.plot([e0[0], e1[0]], [e0[1], e1[1]], color=style.COLORS["fv-lts"], lw=2.6, zorder=4, solid_capstyle="round") + ax.plot([P_IN[0], XY[s][0]], [P_IN[1], XY[s][1]], color=style.COLORS["fv"], lw=0.9, ls=(0, (3, 2)), + alpha=0.8, zorder=3) + mid = (e0 + e1) / 2 + out = mid - P_IN + out = out / max(np.linalg.norm(out), 1e-9) * 0.42 + ax.text(mid[0] + out[0], mid[1] + out[1], f"ℓ={L:.2f}", fontsize=6.8, color=style.COLORS["fv-lts"], + zorder=5, ha="center", va="center") + ax.plot(*P_IN, marker="o", ms=7, mfc=style.COLORS["fv"], mec="white", mew=1.2, zorder=7) + ax.text(P_IN[0] + 0.15, P_IN[1] - 0.45, "cell centroid p", fontsize=7.6, color=style.COLORS["fv"], zorder=7) + _sites(ax, style, w) + rate = sum(w[s] * RATES[s] for s in w) + txt = " ".join(f"w_{NAMES[s]} = {w[s]:.3f}" for s in sorted(w)) + ax.text(-0.9, 9.35, "Laplace weights w = ℓ / distance, normalised", fontsize=7.8, color=style.INK, va="top") + ax.text(-0.9, 8.85, txt, fontsize=7.6, color=style.INK, va="top") + away = [NAMES[s] for s in range(len(GAGES)) if s not in w] + tail = (f" {' and '.join(away)} {'is' if len(away) == 1 else 'are'} not a natural neighbour: weight 0" + if away else "") + ax.text(-0.9, 8.35, f"intensity at p = {rate:.1f} mm/hr{tail}", fontsize=7.6, color=style.INK, va="top") + ax.text(-0.9, -1.35, "grey: the Delaunay triangulation of the gages blue fill: the centroid's new Voronoi cell\n" + "orange: the facet it shares with each natural neighbour", fontsize=7.2, color=style.MUTED, va="top", + linespacing=1.5) + ax.set_title("(a) Inside the hull — Laplace natural-neighbour weights", fontsize=9, loc="left") + + +def _panel_outside(ax, style): + from matplotlib.patches import Polygon + tris = delaunay(XY) + d = np.linalg.norm(XY - P_OUT, axis=1) + w = (1.0 / d ** 2) / np.sum(1.0 / d ** 2) + for t in tris: + ax.add_patch(Polygon(XY[list(t)], closed=True, fc="none", ec=style.MUTED, lw=0.8, alpha=0.45, zorder=1)) + for i, (name, x, y, _) in enumerate(GAGES): + ax.plot([P_OUT[0], x], [P_OUT[1], y], color=style.COLORS["dw"], lw=0.8 + 2.2 * w[i], ls=(0, (3, 2)), zorder=2) + ax.plot(*P_OUT, marker="o", ms=7, mfc=style.COLORS["dw"], mec="white", mew=1.2, zorder=7) + ax.text(P_OUT[0], P_OUT[1] + 0.4, "cell centroid q,\noutside every Delaunay triangle", fontsize=7.6, + ha="right", color=style.COLORS["dw"], zorder=7) + _sites(ax, style) + rate = float(w @ RATES) + txt = " ".join(f"w_{NAMES[i]} = {w[i]:.3f}" for i in range(len(GAGES))) + ax.text(-0.9, 9.35, "Inverse-distance weights w = d⁻² normalised, over every located gage", fontsize=7.8, + color=style.INK, va="top") + ax.text(-0.9, 8.85, txt, fontsize=7.2, color=style.INK, va="top") + ax.text(-0.9, 8.35, f"intensity at q = {rate:.1f} mm/hr", fontsize=7.6, color=style.INK, va="top") + ax.text(-0.9, -1.35, "line weight is the gage's share. IDW never leaves the range of the readings: it tends to the\n" + "nearest gage close in, and to the plain mean far out.", fontsize=7.2, color=style.MUTED, va="top", + linespacing=1.5) + ax.set_title("(b) Outside the hull — inverse-distance weights", fontsize=9, loc="left") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 4.9)) + fig.patch.set_facecolor(style.SURFACE) + for ax in (a0, a1): + ax.set_xlim(-1.0, 12.0) + ax.set_ylim(-1.8, 9.6) + ax.set_aspect("equal", adjustable="datalim") + ax.axis("off") + _panel_inside(a0, style) + _panel_outside(a1, style) + fig.subplots_adjust(left=0.01, right=0.99, top=0.94, bottom=0.02, wspace=0.05) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch8_nn_weights") diff --git a/docs/figures/src/hydrology/ch9_node_bed_exchange.py b/docs/figures/src/hydrology/ch9_node_bed_exchange.py new file mode 100644 index 000000000..95dd0ca70 --- /dev/null +++ b/docs/figures/src/hydrology/ch9_node_bed_exchange.py @@ -0,0 +1,88 @@ +"""Node-aquifer exchange through a semi-confining bed (hydrology Chapter 9, +§9.6). + +A 1D node standing in a mesh cell exchanges with that cell's aquifer by a +MODFLOW-River conductance. The direction follows the heads alone: a water +table above the pipe head drives groundwater infiltration into the +network, a pipe head above the table drives exfiltration into the +aquifer. Two conductances are available — through a declared +semi-confining bed of thickness d_C and conductivity K_c, or, with no bed +declared, directly through half the soil column. Both directions are +capped; the caps are annotated where they bite. Synthetic; no model run. +""" +from __future__ import annotations + +REQUIRES = () + +ZS = 4.4 # soil column thickness +HG = 3.0 # saturated thickness (table above the pipe head here) +D_C = 0.42 # semi-confining bed thickness +PIPE_Y = 1.15 # pipe invert +PIPE_H = 0.95 # pipe diameter + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Rectangle, Circle + fig, ax = plt.subplots(figsize=(9.2, 4.6)) + fig.patch.set_facecolor(style.SURFACE) + x0, W = 1.0, 8.0 + INK, WA, DW, OR = style.INK, style.WATER, style.COLORS["dw"], style.COLORS["fv-lts"] + # cell: unsaturated above, saturated below + ax.add_patch(Rectangle((x0, HG), W, ZS - HG, fc="#e7d9bf", ec=INK, lw=1.2)) + ax.add_patch(Rectangle((x0, 0), W, HG, fc=WA, alpha=0.34, ec=INK, lw=1.2)) + ax.plot([x0, x0 + W], [HG, HG], color=style.COLORS["fv"], lw=1.8) + ax.text(x0 + 0.15, ZS + 0.12, "mesh cell — ground surface z_c", fontsize=7.8, color=INK) + ax.text(x0 + W - 0.15, HG + 0.12, "water table H_gw = z_bed + h_g", fontsize=7.8, ha="right", + color=style.COLORS["fv"]) + ax.text(x0 + 0.15, 0.12, "aquifer bottom z_bed", fontsize=7.6, color=INK) + # manhole and pipe + mx = x0 + 3.9 + ax.add_patch(Rectangle((mx - 0.34, PIPE_Y + PIPE_H), 0.68, ZS - PIPE_Y - PIPE_H + 0.35, fc="#d9e6f5", + ec=INK, lw=1.1)) + ax.add_patch(Rectangle((mx - 0.9, PIPE_Y), 1.8, PIPE_H, fc="#d9e6f5", ec=INK, lw=1.2)) + ax.add_patch(Circle((mx, ZS + 0.35), 0.2, fc="#bfbfbf", ec=INK, lw=1.0)) + ax.add_patch(Rectangle((mx - 0.9, PIPE_Y), 1.8, 0.52, fc=WA, alpha=0.45, ec="none")) + ax.add_patch(Rectangle((mx - 0.34, PIPE_Y + PIPE_H), 0.68, 0.0, fc="none", ec="none")) + ax.text(mx, PIPE_Y + 0.26, "d", fontsize=8, ha="center", va="center", color=INK) + ax.plot([mx - 2.4, mx + 2.4], [PIPE_Y + 0.52, PIPE_Y + 0.52], color=DW, lw=1.5, ls=(0, (4, 2))) + ax.text(mx + 2.5, PIPE_Y + 0.62, "pipe head\nH_pipe = z_inv + d", fontsize=7.8, va="bottom", color=DW) + ax.plot([mx - 1.35, mx - 0.95], [PIPE_Y, PIPE_Y], color=INK, lw=0.9) + ax.text(mx - 1.0, PIPE_Y - 0.16, "z_inv", fontsize=7.6, ha="right", va="top", color=INK) + # semi-confining bed around the pipe + bw = 2.6 + ax.add_patch(Rectangle((mx - bw / 2, PIPE_Y - D_C), bw, D_C, fc="#cbbfa6", ec=INK, lw=1.0, hatch="xx")) + ax.annotate("", xy=(mx - bw / 2 - 0.12, PIPE_Y - D_C), xytext=(mx - bw / 2 - 0.12, PIPE_Y), + arrowprops=dict(arrowstyle="<->", color=INK, lw=0.9)) + ax.text(mx - bw / 2 - 0.25, PIPE_Y - D_C / 2, "d_C", fontsize=8, ha="right", va="center", color=INK) + ax.text(mx + bw / 2 + 0.15, PIPE_Y - D_C / 2, "semi-confining bed: K_c, contact area A_b", + fontsize=7.4, va="center", color=INK) + # the head difference + ax.annotate("", xy=(mx - 1.95, HG), xytext=(mx - 1.95, PIPE_Y + 0.52), + arrowprops=dict(arrowstyle="<->", color=style.COLORS["fv"], lw=1.0)) + ax.text(mx - 2.05, (HG + PIPE_Y + 0.52) / 2, "H_gw − H_pipe\ndrives the exchange", fontsize=7.6, ha="right", + va="center", color=style.COLORS["fv"]) + # the two directions + A = lambda col: dict(arrowstyle="-|>", color=col, lw=1.8, mutation_scale=13) # noqa: E731 + ax.annotate("", xy=(mx - 0.95, PIPE_Y + 0.25), xytext=(mx - 1.85, PIPE_Y + 0.25), arrowprops=A(WA)) + ax.text(mx - 1.95, PIPE_Y + 0.25, "Q > 0 infiltration\ninto the pipe", fontsize=7.4, ha="right", + va="center", color=WA) + ax.annotate("", xy=(mx + 1.85, PIPE_Y + 0.25), xytext=(mx + 0.95, PIPE_Y + 0.25), arrowprops=A(OR)) + ax.text(mx + 1.95, PIPE_Y + 0.25, "Q < 0 exfiltration\ninto the aquifer", fontsize=7.4, va="center", color=OR) + # the conductance and the caps + ax.text(x0, -0.55, "Q_node = C (H_gw − H_pipe), C = K_c A_b / d_C with a bed, C = K_s A_b / (½ z_s) without one", + fontsize=8.4, color=INK) + ax.text(x0, -1.05, "Caps — a drain takes at most half the cell's drainable water per step, ½ h_g S_y A / Δt. A recharge is refused " + "when the table is within 10⁻⁴ z_s of the ground,\ntakes at most half the headroom (z_s − h_g) S_y A, and cannot exceed what " + "the node holds for the batch plus what flows through it.", fontsize=7.4, color=style.MUTED, linespacing=1.5) + ax.set_xlim(0, 12.2) + ax.set_ylim(-1.7, ZS + 1.0) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch9_node_bed_exchange") diff --git a/docs/figures/src/hydrology/ch9_soil_characteristics.py b/docs/figures/src/hydrology/ch9_soil_characteristics.py new file mode 100644 index 000000000..4c0698dce --- /dev/null +++ b/docs/figures/src/hydrology/ch9_soil_characteristics.py @@ -0,0 +1,89 @@ +"""The four soil-characteristic laws of the mesh aquifer (hydrology +Chapter 9, §9.3): effective saturation and relative conductivity against +suction, at the engine's defaults. + +Suction is measured upward from the water table, so the abscissa is also +the height above it: psi = 0 at the table, psi = L at the ground. The +curves are the table of §9.3 evaluated directly. Brooks-Corey is the one +law with a kink — everything is saturated below its air-entry head. Note +the log conductivity axis: at one metre above the table the four laws +disagree by two orders of magnitude, which is why the recharge closure +they feed carries the Experimental caveat for all but Gardner. +Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +ALPHA = 2.0 # 1/m, Gardner and Russo sorptive number (and van Genuchten) +PSI_B = 0.20 # m, Brooks-Corey air entry +LAMBDA = 0.40 # Brooks-Corey pore-size index +N_VG = 1.6 # van Genuchten n +L_M = 0.5 # Mualem tortuosity exponent + + +def _gardner(p): + s = np.exp(-ALPHA * p) + return s, s + + +def _russo(p): + base = (1.0 + 0.5 * ALPHA * p) * np.exp(-0.5 * ALPHA * p) + return base ** (2.0 / (2.0 + L_M)), base ** 2 + + +def _brooks_corey(p): + se = np.where(p <= PSI_B, 1.0, (PSI_B / np.maximum(p, 1e-12)) ** LAMBDA) + kr = np.where(p <= PSI_B, 1.0, (PSI_B / np.maximum(p, 1e-12)) ** (2.0 + 3.0 * LAMBDA)) + return se, kr + + +def _van_genuchten(p): + m = 1.0 - 1.0 / N_VG + se = (1.0 + (ALPHA * p) ** N_VG) ** (-m) + kr = se ** L_M * (1.0 - (1.0 - se ** (1.0 / m)) ** m) ** 2 + return se, kr + + +def _draw(style): + import matplotlib.pyplot as plt + psi = np.linspace(0.0, 3.0, 900) + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.0, 3.8)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + laws = [("GARDNER", _gardner, style.COLORS["fv"], "-"), + ("RUSSO (default)", _russo, style.COLORS["dw"], "-"), + ("BROOKS_COREY", _brooks_corey, style.COLORS["fv-lts"], (0, (5, 2))), + ("VAN_GENUCHTEN", _van_genuchten, style.COLORS["dw-slot"], (0, (2, 1.6)))] + for name, fn, col, ls in laws: + se, kr = fn(psi) + a0.plot(psi, se, color=col, lw=1.7, ls=ls, label=name) + a1.plot(psi, np.maximum(kr, 1e-8), color=col, lw=1.7, ls=ls) + a0.axvline(PSI_B, color=style.MUTED, lw=0.8, ls=(0, (1, 2))) + a0.text(PSI_B + 0.05, 0.06, "air entry ψ_b = 0.2 m", fontsize=7.4, color=style.MUTED) + a1.axvline(PSI_B, color=style.MUTED, lw=0.8, ls=(0, (1, 2))) + a0.set_xlabel("suction ψ above the water table (m)") + a1.set_xlabel("suction ψ above the water table (m)") + a0.set_ylabel("effective saturation S_e") + a1.set_ylabel("relative conductivity K_r = K / K_s") + a0.set_ylim(0, 1.05) + a0.set_xlim(0, 3) + a1.set_xlim(0, 3) + a1.set_yscale("log") + a1.set_ylim(1e-6, 1.6) + a0.set_title("(a) Retention: what the column holds", fontsize=9, loc="left") + a1.set_title("(b) Conductivity: how fast it moves", fontsize=9, loc="left") + a0.legend(fontsize=7.4, frameon=False, loc="upper right") + a1.text(0.08, 2.2e-6, "α = 2 /m ψ_b = 0.2 m λ = 0.4 n = 1.6 L_M = 0.5\n" + "θ(ψ) = θ_r + S_e (θ_s − θ_r); K(ψ) = K_s K_r(ψ)", + fontsize=7.2, color=style.MUTED, linespacing=1.4) + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch9_soil_characteristics") diff --git a/docs/figures/src/hydrology/ch9_two_layer_column.py b/docs/figures/src/hydrology/ch9_two_layer_column.py new file mode 100644 index 000000000..081e9695c --- /dev/null +++ b/docs/figures/src/hydrology/ch9_two_layer_column.py @@ -0,0 +1,120 @@ +"""One column of the mesh aquifer and the two ways its unsaturated zone is +represented (hydrology Chapter 9, §9.2 and §9.4). + +Left: closure A (CLOSED_FORM and ENSLAVED) — the unsaturated column of +thickness L = z_s − h_g is one bulk store h_u, exchanging with the +saturated zone through the quasi-steady recharge q_0. Right: closure B +(SIGMA) — the same column as m layers on sigma = z/L that stretch and +compress with the table, integrating the real Richards flux. Every flux +the ledger of §9.10 books is drawn: infiltration in from the surface, +evapotranspiration out, recharge across the table, lateral Darcy through +the sides, deep loss at the bottom, node exchange with a pipe and Dunne +return flow back to the surface. Synthetic; no model run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + +W = 3.6 # cell width, drawing units +ZS = 5.0 # soil column thickness +HG = 1.7 # saturated thickness +M_LAYERS = 8 + + +def _column(ax, style, x0, sigma, title): + from matplotlib.patches import Rectangle + P = dict(lw=1.2, ec=style.INK) + ground, bed, table = ZS, 0.0, HG + # saturated zone + ax.add_patch(Rectangle((x0, bed), W, table, fc=style.WATER, alpha=0.38, **P)) + # unsaturated zone + if not sigma: + ax.add_patch(Rectangle((x0, table), W, ground - table, fc="#e7d9bf", **P)) + ax.add_patch(Rectangle((x0 + 0.25, table + 0.2), W - 0.5, 1.15, fc=style.WATER, alpha=0.42, + ec=style.WATER, lw=1.0)) + ax.text(x0 + W / 2, table + 0.78, "bulk store h_u", fontsize=8, ha="center", va="center", color=style.INK) + ax.text(x0 + W / 2, table + 2.35, "one state for the\nwhole column", fontsize=7.4, ha="center", + va="center", color=style.MUTED, style="italic") + else: + L = ground - table + dz = L / M_LAYERS + for j in range(M_LAYERS): + y = table + j * dz + theta = 0.40 - 0.30 * (j / (M_LAYERS - 1)) ** 0.7 # wetter near the table + ax.add_patch(Rectangle((x0, y), W, dz, fc="#e7d9bf", ec=style.MUTED, lw=0.5)) + ax.add_patch(Rectangle((x0, y), W * theta / 0.42, dz, fc=style.WATER, alpha=0.40, ec="none")) + ax.add_patch(Rectangle((x0, table), W, L, fc="none", **P)) + ax.annotate("", xy=(x0 + W + 0.28, ground), xytext=(x0 + W + 0.28, table), + arrowprops=dict(arrowstyle="<->", color=style.MUTED, lw=0.8)) + ax.text(x0 + W + 0.38, (ground + table) / 2, f"m = {M_LAYERS} layers\nΔσ = 1/m, σ = z/L\nθ_j per layer", + fontsize=7.2, va="center", color=style.MUTED) + ax.plot([x0, x0 + W], [table, table], color=style.COLORS["fv"], lw=1.8) + ax.plot([x0 - 0.35, x0], [ground, ground], color=style.INK, lw=1.4) + ax.text(x0 + W / 2, ground + 1.62, title, fontsize=8.8, ha="center", weight="bold", color=style.INK) + + +def _draw(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.8, 4.9)) + fig.patch.set_facecolor(style.SURFACE) + xa, xb = 1.9, 7.6 + _column(ax, style, xa, False, "closure A — CLOSED_FORM / ENSLAVED") + _column(ax, style, xb, True, "closure B — SIGMA") + A = lambda col, lw=1.5: dict(arrowstyle="-|>", color=col, lw=lw, mutation_scale=12) # noqa: E731 + WA, OR, DW = style.WATER, style.COLORS["fv-lts"], style.COLORS["dw"] + for x0 in (xa, xb): + # infiltration in (left), ET out (middle), Dunne return up (right) + ax.annotate("", xy=(x0 + 0.55, ZS - 0.05), xytext=(x0 + 0.55, ZS + 0.95), arrowprops=A(WA)) + ax.annotate("", xy=(x0 + 1.8, ZS + 0.95), xytext=(x0 + 1.8, ZS - 0.05), arrowprops=A(OR)) + ax.annotate("", xy=(x0 + 3.05, ZS + 0.95), xytext=(x0 + 3.05, ZS - 0.05), arrowprops=A(DW)) + # recharge across the table + ax.annotate("", xy=(x0 + W / 2, HG - 0.45), xytext=(x0 + W / 2, HG + 0.45), arrowprops=A(style.COLORS["fv"])) + ax.text(x0 + W / 2 + 0.12, HG + 0.12, "q_0", fontsize=8, color=style.COLORS["fv"]) + # deep loss + ax.annotate("", xy=(x0 + W / 2, -0.75), xytext=(x0 + W / 2, -0.05), arrowprops=A(WA, 1.3)) + # lateral Darcy + ax.annotate("", xy=(x0 - 0.8, HG / 2), xytext=(x0 - 0.05, HG / 2), arrowprops=A(WA, 1.3)) + ax.annotate("", xy=(x0 + W + 0.8, HG / 2), xytext=(x0 + W + 0.05, HG / 2), arrowprops=A(WA, 1.3)) + for x, col, lab in ((0.55, WA, "q⁺"), (1.8, OR, "q_ET"), (3.05, DW, "Dunne")): + ax.text(x0 + x, ZS + 1.05, lab, fontsize=7.6, ha="center", color=col) + ax.text(xa + W / 2, -0.95, "deep loss c_loss h_g / z_s", fontsize=7.4, ha="center", va="top", color=WA) + ax.text(xb + W / 2, -0.95, "deep loss", fontsize=7.4, ha="center", va="top", color=WA) + ax.text(xa - 0.9, HG / 2, "lateral Darcy\n(harmonic K)", fontsize=7.2, ha="right", va="center", color=WA) + ax.text(-1.6, ZS + 2.45, "q⁺ infiltration delivered by the surface (Chapter 8) q_ET root uptake and boundary ET\n" + "Dunne return flow when the table reaches the ground q_0 recharge across the table, H = z_bed + h_g", + fontsize=7.4, color=style.MUTED, va="top", linespacing=1.5) + # geometry labels on the left column + D = dict(arrowstyle="<->", color=style.INK, lw=0.9) + ax.annotate("", xy=(xa - 2.75, 0), xytext=(xa - 2.75, ZS), arrowprops=D) + ax.text(xa - 2.85, ZS / 2, "z_s", fontsize=9, ha="right", va="center", color=style.INK) + ax.annotate("", xy=(xa + W + 0.3, 0), xytext=(xa + W + 0.3, HG), arrowprops=D) + ax.text(xa + W + 0.4, HG / 2, "h_g", fontsize=9, va="center", color=style.INK) + ax.text(xa + W + 0.4, HG + 0.7, "L = z_s − h_g", fontsize=8, va="center", color=style.INK) + ax.text(xa - 0.45, ZS, "ground z_c", fontsize=7.6, ha="right", va="center", color=style.INK) + ax.text(xa - 0.45, 0.0, "bottom z_bed", fontsize=7.6, ha="right", va="center", color=style.INK) + ax.text(xa - 0.45, HG + 0.42, "water table H", fontsize=7.6, ha="right", va="center", + color=style.COLORS["fv"]) + # a pipe standing in the right column's saturated zone: the exchange of Figure 9-3 + from matplotlib.patches import Rectangle, Circle + px = xb + W - 1.15 + ax.add_patch(Rectangle((px, 0.5), 0.8, 0.75, fc="#d9e6f5", ec=style.INK, lw=1.0)) + ax.add_patch(Rectangle((px + 0.25, 1.25), 0.3, ZS - 1.25, fc="#d9e6f5", ec=style.INK, lw=0.9)) + ax.add_patch(Circle((px + 0.4, ZS), 0.16, fc="#bfbfbf", ec=style.INK, lw=0.9)) + ax.annotate("", xy=(px - 0.05, 0.88), xytext=(px - 0.75, 0.88), arrowprops=A(DW, 1.4)) + ax.text(px + 1.0, 0.88, "node exchange\n(Figure 9-3)", fontsize=7.2, ha="left", va="center", color=DW) + ax.text(-1.6, -1.65, "Both closures carry the same saturated state h_g and the same ledger;\nthey differ only in how the " + "unsaturated column above it is held. AUTO picks\nbetween them from αL, the column thickness in capillary " + "lengths (§9.4.1).", fontsize=7.6, color=style.MUTED, va="top", linespacing=1.5) + ax.set_xlim(-1.9, 13.4) + ax.set_ylim(-2.6, ZS + 2.6) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "hydrology_ch9_two_layer_column") diff --git a/docs/figures/src/quality/ch10_cell_buildup_washoff.py b/docs/figures/src/quality/ch10_cell_buildup_washoff.py new file mode 100644 index 000000000..f40bd72e9 --- /dev/null +++ b/docs/figures/src/quality/ch10_cell_buildup_washoff.py @@ -0,0 +1,89 @@ +"""Buildup and washoff on one mesh cell (quality Chapter 10, §10.5-§10.8). + +A cell declares which of the model's land uses cover it and by what +percent; the buildup store is held per (cell, land use, species) in user +mass per normalizer unit, where the normalizer is the covered area or, for +a per-curb land use, the covered curb length. Accrual runs on the runoff +step, sweeping removes a fraction on its own schedule, and washoff — driven +by the cell's net outflow expressed as a runoff rate — moves mass out of +the store and into the cell's species row, which then advects across the +mesh and hands mass to the network at a coupling point. Synthetic; no +model run. +""" +from __future__ import annotations + +REQUIRES = () + +SLICES = [("Residential", 0.60, "#cfe0c3"), ("Commercial", 0.25, "#e6d9bd"), ("bare", 0.15, "#dcdcd6")] +STORE = {"Residential": 0.78, "Commercial": 0.52, "bare": 0.0} # relative store height + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon, Rectangle, Circle + fig, ax = plt.subplots(figsize=(9.4, 4.7)) + fig.patch.set_facecolor(style.SURFACE) + INK, WA, OR, DW, FV = style.INK, style.WATER, style.COLORS["fv-lts"], style.COLORS["dw"], style.COLORS["fv"] + # the cell, in plan, cut into coverage slices + x0, y0, w, h = 0.4, 1.2, 4.6, 2.6 + x = x0 + for name, frac, fc in SLICES: + ww = frac * w + ax.add_patch(Rectangle((x, y0), ww, h, fc=fc, ec=INK, lw=1.0)) + ax.text(x + ww / 2, y0 + h - 0.22, f"{int(frac * 100)} %", fontsize=7.6, ha="center", va="top", color=INK) + ax.text(x + ww / 2, y0 + h - 0.62, name, fontsize=7.0, ha="center", va="top", color=INK, + rotation=0 if frac > 0.2 else 90) + # the buildup store as a bar standing on the slice + s = STORE[name] + if s > 0: + ax.add_patch(Rectangle((x + ww * 0.25, y0 + 0.3), ww * 0.5, s * 1.1, fc=OR, alpha=0.75, ec=OR, lw=1.0)) + ax.text(x + ww / 2, y0 + 0.3 + s * 1.1 + 0.08, f"B = {s:.2f}", fontsize=6.8, ha="center", color=OR) + else: + ax.text(x + ww / 2, y0 + 1.15, "no land use\nno store", fontsize=6.6, ha="center", va="center", + color=style.MUTED) + x += ww + ax.text(x0, y0 + h + 1.52, "one mesh cell — [2D_COVERAGES] replaces the whole set for its scope, " + "ladder * > TAG > CELL", fontsize=7.8, color=INK) + ax.text(x0, y0 + h + 1.22, "buildup per (cell, land use, species), in user mass per normalizer: " + "N = f·A (per area) or f·L (per curb)", fontsize=7.2, color=style.MUTED) + A = lambda col, lw=1.6: dict(arrowstyle="-|>", color=col, lw=lw, mutation_scale=12) # noqa: E731 + # accrual on the runoff step, and sweeping, both from above the cell + ax.annotate("", xy=(1.2, y0 + h + 0.05), xytext=(1.2, y0 + h + 0.62), arrowprops=A(OR)) + ax.text(1.32, y0 + h + 0.62, "accrual on the runoff step\n(Chapter 3's functions, unchanged)", fontsize=7.2, + va="top", color=OR) + ax.annotate("", xy=(3.6, y0 + h + 0.62), xytext=(3.6, y0 + h + 0.05), arrowprops=A(DW)) + ax.text(3.72, y0 + h + 0.62, "sweeping removes a fraction\non its own schedule", fontsize=7.2, va="top", color=DW) + # washoff out of the store into the species row + ax.annotate("", xy=(6.0, y0 + 0.9), xytext=(5.05, y0 + 0.9), arrowprops=A(WA, 2.0)) + ax.text(5.5, y0 + 1.08, "washoff", fontsize=7.8, ha="center", color=WA) + ax.text(5.5, y0 + 0.72, "driven by the cell's net\noutflow as a runoff rate", fontsize=6.9, ha="center", + va="top", color=WA) + # the species row + rows = ["Pollutant TSS", "Pollutant Lead", "MSX species"] + for k, r in enumerate(rows): + yy = y0 + 1.55 - k * 0.5 + ax.add_patch(Rectangle((6.05, yy), 2.3, 0.42, fc=WA, alpha=0.18 + 0.12 * k, ec=WA, lw=1.0)) + ax.text(7.2, yy + 0.21, r, fontsize=7.0, ha="center", va="center", color=INK) + ax.text(7.2, y0 + 2.25, "the cell's species mass rows m_{s,i}", fontsize=7.6, ha="center", color=INK) + ax.text(7.2, y0 + 0.28, "species-major; concentration is derived", fontsize=6.9, ha="center", color=style.MUTED) + # advection across the mesh, then to a node + ax.annotate("", xy=(9.5, y0 + 1.0), xytext=(8.45, y0 + 1.0), arrowprops=A(FV, 2.0)) + ax.text(8.98, y0 + 1.15, "advection across\nthe mesh (§10.2)", fontsize=7.0, ha="center", color=FV) + ax.add_patch(Circle((9.95, y0 + 1.0), 0.28, fc="#d9e6f5", ec=INK, lw=1.1)) + ax.text(9.95, y0 + 1.42, "coupled node", fontsize=7.0, ha="center", va="bottom", color=INK) + ax.annotate("", xy=(9.95, y0 + 0.18), xytext=(9.95, y0 + 0.68), arrowprops=A(DW, 1.4)) + ax.text(9.95, y0 + 0.08, "into the 1D\ntransport", fontsize=6.8, ha="center", va="top", color=DW) + ax.text(0.4, 0.55, "Per-curb land uses need a curb length on every cell they cover ([2D_CURB_LENGTH]); a covered cell " + "without one is refused at open, not given zero.", fontsize=7.2, color=style.MUTED) + ax.text(0.4, 0.2, "A cell whose centroid lies in a subcatchment that carries its own coverages is reported in one " + "ownership warning: the same storm would load twice.", fontsize=7.2, color=style.MUTED) + ax.set_xlim(0.1, 10.6) + ax.set_ylim(0.0, y0 + h + 1.95) + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "quality_ch10_cell_buildup_washoff") diff --git a/docs/figures/src/quality/ch10_transport_policy.py b/docs/figures/src/quality/ch10_transport_policy.py new file mode 100644 index 000000000..d70e84d71 --- /dev/null +++ b/docs/figures/src/quality/ch10_transport_policy.py @@ -0,0 +1,104 @@ +"""The transport policy matrix and the gates behind one of its cells +(quality Chapter 10, §10.1). + +Left: the four domains against the four species classes, each cell +enabled, disabled by a named key, or unavailable with a reason. This is +the matrix the report header prints and the C API and GUI read; the +example shown is a project with pollutants, a reaction system holding one +wall species, water age on and heat off. Right: the ladder the 2D-surface +row walks for one class, in the order the resolver applies it — the first +gate that fires names itself as the reason. Synthetic; no model run. +""" +from __future__ import annotations + +REQUIRES = () + +DOMAINS = ["Runoff / LID", "Groundwater", "1D network", "2D surface"] +CLASSES = ["Pollutants", "MSX", "Age", "Temperature"] + +# state: on / off: / n/a: +MATRIX = [ + ["on(3)", "on(2)", "n/a:age is not\ncarried on\nsubcatchments", "n/a:HEAT_TRANSPORT\nOFF"], + ["n/a:groundwater\ntransport is\nplanned", "n/a:planned", "n/a:planned", "n/a:planned"], + ["on(3)", "on(2)", "on(1)", "n/a:HEAT_TRANSPORT\nOFF"], + ["on(3)", "off:a WALL species\nis declared", "on(1)", "n/a:HEAT_TRANSPORT\nOFF"], +] + +LADDER = [ + ("Is there a mesh?", "no mesh → n/a"), + ("Is the class declared at project level?", "nothing to carry → n/a"), + ("[OPTIONS] IGNORE_2D", "YES → off, naming the key"), + ("[OPTIONS] IGNORE_QUALITY", "YES → off; pollutants and MSX only"), + ("A WALL species in the reaction system?", "yes → MSX n/a, with a warning"), + ("[2D_OPTIONS] TRANSPORT_", "NO → off, naming the key"), + ("otherwise", "on"), +] + + +def _matrix(ax, style): + from matplotlib.patches import Rectangle + ON, OFF, NA = "#1baf7a", "#eda100", "#c9c7c1" + cw, ch = 2.35, 1.35 + for j, c in enumerate(CLASSES): + ax.text(1.2 + j * cw + cw / 2, len(DOMAINS) * ch + 0.28, c, fontsize=7.6, ha="center", va="bottom", + color=style.INK, weight="bold", linespacing=1.3) + for i, d in enumerate(DOMAINS): + y = (len(DOMAINS) - 1 - i) * ch + ax.text(1.1, y + ch / 2, d, fontsize=8, ha="right", va="center", color=style.INK, weight="bold") + for j in range(len(CLASSES)): + x = 1.2 + j * cw + cell = MATRIX[i][j] + if cell.startswith("on"): + fc, txt, tc = ON, cell, "#ffffff" + elif cell.startswith("off:"): + fc, txt, tc = OFF, "off\n" + cell[4:], "#ffffff" + else: + fc, txt, tc = NA, "n/a\n" + cell.split(":", 1)[1], style.INK + ax.add_patch(Rectangle((x, y), cw - 0.1, ch - 0.1, fc=fc, ec=style.SURFACE, lw=1.6, alpha=0.92)) + ax.text(x + (cw - 0.1) / 2, y + (ch - 0.1) / 2, txt, fontsize=6.4, ha="center", va="center", + color=tc, linespacing=1.25) + ax.text(1.2, -0.55, "on(n) carries n rows · off names the key that disabled it · n/a says what is missing", + fontsize=7.2, color=style.MUTED) + ax.text(1.2, -0.95, "canonical row order: pollutants, MSX in declaration order, __WATER_AGE__, " + "__TEMPERATURE__ last", fontsize=7.2, color=style.MUTED) + ax.set_xlim(-2.6, 1.3 + len(CLASSES) * cw) + ax.set_ylim(-1.35, len(DOMAINS) * ch + 1.15) + ax.axis("off") + ax.set_title("(a) The matrix the report header prints", fontsize=9, loc="left") + + +def _ladder(ax, style): + from matplotlib.patches import FancyBboxPatch + for k, (q, outcome) in enumerate(LADDER): + yy = (len(LADDER) - 1 - k) * 1.0 + last = k == len(LADDER) - 1 + fc = "#1baf7a" if last else style.SURFACE + ax.add_patch(FancyBboxPatch((0.1, yy - 0.34), 8.9, 0.7, boxstyle="round,pad=0.06", + fc=fc, ec="#1baf7a" if last else style.MUTED, lw=1.0)) + ax.text(0.3, yy + 0.09, q, fontsize=7.4, va="center", color="#ffffff" if last else style.INK) + ax.text(0.3, yy - 0.18, outcome, fontsize=6.9, va="center", + color="#ffffff" if last else style.COLORS["fv-lts"]) + if not last: + ax.annotate("", xy=(0.5, yy - 0.48), xytext=(0.5, yy - 0.34), + arrowprops=dict(arrowstyle="-|>", color=style.MUTED, lw=1.0, mutation_scale=9)) + ax.text(0.1, len(LADDER) - 0.28, "the first gate that fires is the reason the cell reports", + fontsize=7.2, color=style.MUTED) + ax.set_xlim(0, 9.4) + ax.set_ylim(-0.9, len(LADDER) + 0.15) + ax.axis("off") + ax.set_title("(b) The gate ladder behind one 2D-surface cell", fontsize=9, loc="left") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.6, 3.9), gridspec_kw=dict(width_ratios=[1.28, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + _matrix(a0, style) + _ladder(a1, style) + fig.tight_layout(pad=0.3) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "quality_ch10_transport_policy") diff --git a/docs/figures/src/quality/ch6_lid_stacks.py b/docs/figures/src/quality/ch6_lid_stacks.py new file mode 100644 index 000000000..1a67b0ab6 --- /dev/null +++ b/docs/figures/src/quality/ch6_lid_stacks.py @@ -0,0 +1,154 @@ +"""LID unit layer stacks: nine table tiles for quality Chapter 6 and the +annotated bio-retention cell for the Engine Manual's Chapter 1. + +Each LID type is a vertical stack of the layers the engine models for it +(surface, pavement, soil, storage, drainage mat, underdrain), drawn to the +same conventions so the reader can compare types at a glance. The annotated +figure adds every flux the moisture balance tracks. Replaces the 90–300 px +legacy icons and the 129 × 90 px bio-retention sketch. +""" +from __future__ import annotations + +REQUIRES = () + +LAYER_STYLE = { + "surface": ("Surface", "#dbe7c6", "#6f8a4f", "grass"), + "roof": ("Roof", "#e4e4e4", "#7a7a7a", "roof"), + "pavement": ("Pavement", "#cfcfcf", "#7a7a7a", "pavement"), + "pavers": ("Paver blocks", "#cfcfcf", "#7a7a7a", "pavers"), + "soil": ("Soil", "#d9c4a3", "#8a6d45", "soil"), + "sand": ("Sand bedding", "#eadfc6", "#a08a5e", "soil"), + "storage": ("Storage (gravel)", "#d5d0c4", "#6e6a60", "gravel"), + "barrel": ("Barrel", "#cfe3f7", "#3b6fa0", "water"), + "mat": ("Drainage mat", "#e8e0f2", "#7a5da0", "mat"), + "native": ("Native soil", "#c9b592", "#8a6d45", "soil"), +} + +# (fig_id, title, [(layer key, relative thickness), ...], underdrain?) +TILES = [ + ("quality_ch6_lid_bio_cell", "Bio-retention cell", [("surface", 0.7), ("soil", 1.6), ("storage", 1.2)], True), + ("quality_ch6_lid_rain_garden", "Rain garden", [("surface", 0.7), ("soil", 1.6)], False), + ("quality_ch6_lid_green_roof", "Green roof", [("surface", 0.6), ("soil", 1.1), ("mat", 0.35), ("roof", 0.35)], False), + ("quality_ch6_lid_infiltration_trench", "Infiltration trench", [("surface", 0.5), ("storage", 2.2)], True), + ("quality_ch6_lid_permeable_pavement", "Continuous permeable pavement", + [("surface", 0.35), ("pavement", 0.8), ("soil", 0.7), ("storage", 1.4)], True), + ("quality_ch6_lid_block_paver", "Block paver", [("surface", 0.35), ("pavers", 0.7), ("sand", 0.5), ("storage", 1.4)], True), + ("quality_ch6_lid_rain_barrel", "Rain barrel", [("barrel", 2.4)], True), + ("quality_ch6_lid_rooftop_disconnection", "Rooftop disconnection", [("roof", 0.5), ("surface", 1.0)], False), + ("quality_ch6_lid_vegetative_swale", "Vegetative swale", [("surface", 1.3)], False), +] + + +def _hatch(ax, kind, x0, x1, y0, y1, ec): + import numpy as np + w, h = x1 - x0, y1 - y0 + if kind == "grass": + for x in np.linspace(x0 + 0.06 * w, x1 - 0.06 * w, 9): + ax.plot([x, x - 0.015 * w, x, x + 0.015 * w], [y1, y1 + 0.35 * h, y1, y1 + 0.32 * h], + color=ec, lw=0.9, solid_capstyle="round") + elif kind == "gravel": + rng = np.random.default_rng(7) + for _ in range(int(60 * w)): + ax.plot([x0 + rng.random() * w], [y0 + rng.random() * h], marker="o", ms=1.6, color=ec, alpha=0.55) + elif kind == "soil": + rng = np.random.default_rng(3) + for _ in range(int(25 * w)): + ax.plot([x0 + rng.random() * w], [y0 + rng.random() * h], marker=".", ms=1.2, color=ec, alpha=0.4) + elif kind == "pavement": + for y in np.linspace(y0, y1, 4)[1:-1]: + ax.plot([x0, x1], [y, y], color=ec, lw=0.4, alpha=0.6) + elif kind == "pavers": + for x in np.linspace(x0, x1, 7)[1:-1]: + ax.plot([x, x], [y0, y1], color=ec, lw=0.6) + elif kind == "mat": + for x in np.linspace(x0, x1, 12)[1:-1]: + ax.plot([x, x], [y0, y1], color=ec, lw=0.5, alpha=0.7) + elif kind == "water": + for y in np.linspace(y0 + 0.1 * h, y1 - 0.4 * h, 3): + ax.plot([x0 + 0.1 * w, x1 - 0.1 * w], [y, y], color=ec, lw=0.6, alpha=0.5) + elif kind == "roof": + for x in np.linspace(x0, x1, 5)[1:-1]: + ax.plot([x, x + 0.08 * w], [y0, y1], color=ec, lw=0.4, alpha=0.6) + + +def _stack(ax, layers, underdrain, x0=0.0, x1=1.0, top=1.0, label_size=7.0, style=None, label_side="right"): + total = sum(t for _, t in layers) + y = top + geom = {} + lx, ha = (x1 + 0.03, "left") if label_side == "right" else (x0 - 0.03, "right") + for key, thick in layers: + name, fc, ec, kind = LAYER_STYLE[key] + h = thick / total * top + ax.add_patch(__import__("matplotlib.patches", fromlist=["Rectangle"]).Rectangle( + (x0, y - h), x1 - x0, h, fc=fc, ec=ec, lw=0.9, zorder=1)) + _hatch(ax, kind, x0, x1, y - h, y, ec) + ax.text(lx, y - h / 2, name, fontsize=label_size, va="center", ha=ha, color=style.INK) + geom[key] = (y - h, y) + y -= h + if underdrain: + key = layers[-1][0] + yb, yt = geom[key] + cy = yb + 0.22 * (yt - yb) + ax.plot([x0 + 0.5 * (x1 - x0)], [cy], marker="o", ms=7, mfc="white", mec=style.INK, mew=1.0, zorder=3) + ax.text(lx, cy - 0.09 * top, "Underdrain", fontsize=label_size, va="center", ha=ha, color=style.MUTED) + return geom + + +def _tile(fig_id, title, layers, underdrain, style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(2.55, 1.75)) + fig.patch.set_facecolor(style.SURFACE) + _stack(ax, layers, underdrain, x0=0.05, x1=0.55, top=1.0, label_size=6.6, style=style) + ax.set_xlim(0, 1.3) + ax.set_ylim(-0.05, 1.42) + ax.axis("off") + ax.text(0.05, 1.36, title, fontsize=7.6, weight="bold", va="top", color=style.INK) + fig.tight_layout(pad=0.2) + return fig + + +def _bioretention(style): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(7.2, 4.2)) + fig.patch.set_facecolor(style.SURFACE) + layers = [("surface", 0.7), ("soil", 1.6), ("storage", 1.2)] + geom = _stack(ax, layers, True, x0=0.30, x1=0.85, top=1.0, label_size=8.0, style=style, label_side="left") + ax.add_patch(__import__("matplotlib.patches", fromlist=["Rectangle"]).Rectangle( + (0.30, -0.28), 0.55, 0.28, fc=LAYER_STYLE["native"][1], ec=LAYER_STYLE["native"][2], lw=0.9, zorder=1)) + _hatch(ax, "soil", 0.30, 0.85, -0.28, 0.0, LAYER_STYLE["native"][2]) + ax.text(0.27, -0.14, "Native soil", fontsize=8, va="center", ha="right", color=style.INK) + w = style.WATER + kw = dict(arrowstyle="-|>", color=w, lw=1.3, mutation_scale=11) + A = lambda xy, xytext, text, dx=0.0, dy=0.0, ha="center": ( # noqa: E731 + ax.annotate("", xy=xy, xytext=xytext, arrowprops=kw), + ax.text((xy[0] + xytext[0]) / 2 + dx, (xy[1] + xytext[1]) / 2 + dy, text, fontsize=7.4, color=w, + ha=ha, va="center", fontstyle="italic", + bbox=dict(boxstyle="round,pad=0.15", fc=style.SURFACE, ec="none", alpha=0.9))) + s0, s1 = geom["surface"] + so0, so1 = geom["soil"] + st0, st1 = geom["storage"] + A((0.45, s1 + 0.02), (0.45, s1 + 0.28), "rainfall", dx=-0.02, dy=0.03, ha="right") + A((0.32, s1 + 0.02), (0.10, s1 + 0.12), "run-on from the drainage area", dx=-0.03, dy=0.06, ha="right") + A((0.70, s1 + 0.28), (0.70, s1 + 0.02), "evaporation", dx=0.02, dy=0.03, ha="left") + A((1.10, s1 - 0.5 * (s1 - s0)), (0.86, s1 - 0.5 * (s1 - s0)), "surface outflow", dx=0.0, dy=0.05) + A((0.58, so1 - 0.08), (0.58, s0 + 0.02), "infiltration into the soil", dx=0.30, dy=0.0) + A((0.58, st1 - 0.06), (0.58, so0 + 0.02), "percolation", dx=0.22, dy=0.0) + A((0.58, -0.24), (0.58, st0 + 0.02), "infiltration into native soil (unless lined)", dx=0.03, dy=0.0, ha="left") + cy = st0 + 0.22 * (st1 - st0) + A((1.15, cy), (0.60, cy), "underdrain outflow", dx=0.12, dy=0.05) + ax.text(-0.02, 1.50, "Bio-retention cell: the layers of the moisture balance and its fluxes", + fontsize=9.2, weight="bold", va="top", color=style.INK) + ax.set_xlim(-0.02, 1.45) + ax.set_ylim(-0.34, 1.52) + ax.axis("off") + fig.tight_layout(pad=0.3) + return fig + + +def build(sink): + import style + for fig_id, title, layers, underdrain in TILES: + if fig_id in sink.expected: + sink.save(_tile(fig_id, title, layers, underdrain, style), fig_id) + if "eng_lid_bioretention_layers" in sink.expected: + sink.save(_bioretention(style), "eng_lid_bioretention_layers") diff --git a/docs/figures/src/quality/ch7_ard_stencil.py b/docs/figures/src/quality/ch7_ard_stencil.py new file mode 100644 index 000000000..57055326e --- /dev/null +++ b/docs/figures/src/quality/ch7_ard_stencil.py @@ -0,0 +1,113 @@ +"""Flux-limited advection in the Eulerian (ARD) engine (quality Chapter 7, +§7.3.2). + +Left: the face stencil. First-order upwind carries the cell value C_i to +the face; MUSCL reconstructs a slope inside the cell and the limiter +clips it so the face value never leaves the range of its neighbours. +Right: a step front advected 60 cells at Courant 0.5 by each scheme the +`SCALAR_SCHEME`/`LIMITER` keys select — UPWIND smears it, MINMOD less so, +VANLEER keeps it sharp, SUPERBEE sharpest but stair-steps a smooth ramp. +The demonstration is a 40-line numpy transcription of the flux-limited +form, not an engine run; it reproduces the qualitative ordering the text +describes. Synthetic. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _limiter(name, r): + if name == "UPWIND": + return np.zeros_like(r) + if name == "MINMOD": + return np.maximum(0.0, np.minimum(1.0, r)) + if name == "VANLEER": + return (r + np.abs(r)) / (1.0 + np.abs(r)) + if name == "SUPERBEE": + return np.maximum.reduce([np.zeros_like(r), np.minimum(2.0 * r, 1.0), np.minimum(r, 2.0)]) + raise KeyError(name) + + +def _advect(c0, nu, steps, name): + c = c0.copy() + for _ in range(steps): + dc = np.diff(c) # C_{i+1} - C_i, length n-1 + num = np.concatenate([[0.0], dc[:-1]]) # C_i - C_{i-1} at the same faces + with np.errstate(divide="ignore", invalid="ignore"): + r = np.where(np.abs(dc) > 1e-12, num / dc, 0.0) + phi = _limiter(name, r) + face = c[:-1] + 0.5 * phi * (1.0 - nu) * dc # C_{i+1/2} for u > 0, i = 0 .. n-2 + face = np.concatenate([[c[0]], face, [c[-1]]]) # inflow face holds the boundary value; outflow is upwind + c -= nu * (face[1:] - face[:-1]) + return c + + +def _stencil(ax, style): + vals = [1.0, 1.0, 0.85, 0.35, 0.1, 0.1] + FV, OR, DW = style.COLORS["fv"], style.COLORS["fv-lts"], style.COLORS["dw"] + for i, v in enumerate(vals): + ax.add_patch(__import__("matplotlib").patches.Rectangle((i, 0), 1, v, fc=style.WATER, alpha=0.18, ec=style.MUTED, lw=0.8)) + ax.plot([i, i + 1], [v, v], color=style.INK, lw=1.6) + i = 2 + ax.axvline(i + 1, color=style.INK, lw=1.0, ls=(0, (3, 2))) + ax.text(i + 1, 1.16, "face i+½", fontsize=8, ha="center", color=style.INK) + ax.text(i + 0.5, -0.09, "cell i", fontsize=8, ha="center", color=style.MUTED) + ax.text(i + 1.5, -0.09, "cell i+1", fontsize=8, ha="center", color=style.MUTED) + ax.text(i - 0.5, -0.09, "cell i−1", fontsize=8, ha="center", color=style.MUTED) + ax.annotate("", xy=(i + 0.95, vals[i]), xytext=(i + 0.55, vals[i]), + arrowprops=dict(arrowstyle="-|>", color=OR, lw=1.4, mutation_scale=11)) + ax.text(i + 0.5, vals[i] - 0.14, "upwind: C_i", fontsize=7.8, color=OR, ha="center", va="top") + slope_free = (vals[i + 1] - vals[i - 1]) / 2.0 + slope_lim = 0.55 * slope_free + xs = np.array([i, i + 1]) + ax.plot(xs, vals[i] + slope_free * (xs - i - 0.5), color=style.MUTED, lw=1.0, ls=(0, (2, 2))) + ax.plot(xs, vals[i] + slope_lim * (xs - i - 0.5), color=FV, lw=1.8) + ax.plot([i + 1], [vals[i] + 0.5 * slope_lim], "o", color=FV, ms=6) + ax.text(i + 1.08, vals[i] + 0.5 * slope_lim - 0.02, "MUSCL: C_i + ½ φ(r) ΔC", fontsize=7.8, color=FV, va="top") + ax.text(i + 0.45, 1.09, "unlimited slope (dashed)\nwould overshoot the\nupstream value", fontsize=7, color=style.MUTED, va="bottom", ha="right") + ax.text(0.1, 0.30, "r = (C_i − C_{i−1}) / (C_{i+1} − C_i)\nφ(r): MINMOD · VANLEER · SUPERBEE", fontsize=7.6, color=style.INK) + ax.text(3.9, 0.58, "limited slope never leaves\n[C_{i+1}, C_{i−1}]: no new extrema", fontsize=7.4, color=DW, va="top") + ax.annotate("", xy=(5.6, 0.25), xytext=(4.4, 0.25), arrowprops=dict(arrowstyle="-|>", color=style.WATER, lw=1.6, mutation_scale=12)) + ax.text(5.0, 0.30, "u > 0", fontsize=8, ha="center", color=style.WATER) + ax.set_xlim(-0.2, 6.3) + ax.set_ylim(-0.18, 1.28) + ax.axis("off") + ax.set_title("(a) One face of the ARD stencil", fontsize=9, loc="left") + + +def _demo(ax, style): + n = 160 + x = np.arange(n) + 0.5 + c0 = np.where(x < 20, 1.0, 0.0) + nu, steps = 0.5, 120 + exact = np.where(x < 20 + nu * steps, 1.0, 0.0) + ax.plot(x, exact, color=style.INK, lw=1.0, ls=(0, (2, 2)), label="exact (shifted step)") + for name, col in (("UPWIND", style.COLORS["dw-legacy"]), ("MINMOD", style.COLORS["dw-slot"]), + ("VANLEER", style.COLORS["fv"]), ("SUPERBEE", style.COLORS["dw"])): + c = _advect(c0, nu, steps, name) + lab = "UPWIND" if name == "UPWIND" else f"MUSCL + {name}" + ax.plot(x, c, color=col, lw=1.5, label=lab) + ax.set_xlim(40, 130) + ax.set_ylim(-0.05, 1.12) + ax.set_xlabel("cell index") + ax.set_ylabel("concentration C / C_0") + ax.legend(fontsize=7.2, frameon=False, loc="center right") + ax.set_title("(b) A step front after 60 cells of travel, Courant 0.5", fontsize=9, loc="left") + + +def _draw(style): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 3.7), gridspec_kw=dict(width_ratios=[1.05, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a1) + _stencil(a0, style) + _demo(a1, style) + fig.tight_layout() + return fig + + +def build(sink): + import style + sink.save(_draw(style), "quality_ch7_ard_stencil") diff --git a/docs/figures/src/quality/ch7_lard_parcels.py b/docs/figures/src/quality/ch7_lard_parcels.py new file mode 100644 index 000000000..34101bc29 --- /dev/null +++ b/docs/figures/src/quality/ch7_lard_parcels.py @@ -0,0 +1,98 @@ +"""The five phases of a Lagrangian (LARD) transport step (quality Chapter +7, §7.4): a conduit is an ordered slab of parcels, each with a volume and +a concentration, between an upstream and a downstream node. Drain sends +the volume that left the conduit into the downstream node's ledger; Mix +runs the nodes as CSTRs in topological order; Release adds a parcel at +the upstream node's new concentration and merges look-alike neighbours; +Decay applies exact exponential decay; Publish reports the volume- +weighted mean. Synthetic; no run. +""" +from __future__ import annotations + +REQUIRES = () + +# (volume fraction, concentration) parcels, upstream first +SLAB = [(0.18, 0.15), (0.22, 0.55), (0.20, 0.60), (0.25, 0.95), (0.15, 0.95)] +X0, LEN, H = 1.6, 6.0, 0.42 + + +def _shade(cm, c): + return cm(0.15 + 0.75 * c) + + +def _row(ax, y, parcels, style, cm, up_c, dn_c, title, note, drain=None, new=None, merged=None, uniform=False): + from matplotlib.patches import Circle, Rectangle + ax.text(0.05, y + H / 2, title, fontsize=8.6, weight="bold", va="center", color=style.INK) + ax.add_patch(Circle((X0 - 0.35, y + H / 2), 0.22, fc=_shade(cm, up_c), ec=style.INK, lw=0.9)) + ax.add_patch(Circle((X0 + LEN + 0.35, y + H / 2), 0.22, fc=_shade(cm, dn_c), ec=style.INK, lw=0.9)) + x = X0 + if uniform: + vmean = sum(v * c for v, c in parcels) / sum(v for v, _ in parcels) + ax.add_patch(Rectangle((X0, y), LEN, H, fc=_shade(cm, vmean), ec=style.INK, lw=0.9)) + ax.text(X0 + LEN / 2, y + H / 2, f"volume-weighted mean C = {vmean:.2f}", fontsize=7.6, ha="center", va="center", + color=style.SURFACE if vmean > 0.5 else style.INK) + else: + for k, (v, c) in enumerate(parcels): + w = v * LEN + ec = style.COLORS["fv-lts"] if new == k else style.INK + ax.add_patch(Rectangle((x, y), w, H, fc=_shade(cm, c), ec=ec, lw=1.6 if new == k else 0.9, zorder=2 if new == k else 1)) + ax.text(x + w / 2, y + H / 2, f"{c:.2f}", fontsize=6.8, ha="center", va="center", + color=style.SURFACE if c > 0.5 else style.INK) + x += w + if drain: + w = drain * LEN + ax.add_patch(Rectangle((X0 + LEN - w, y), w, H, fc="none", ec=style.COLORS["fv-lts"], lw=1.6, hatch="///", zorder=3)) + ax.annotate("", xy=(X0 + LEN + 0.15, y + H / 2), xytext=(X0 + LEN - 0.02, y + H / 2), + arrowprops=dict(arrowstyle="-|>", color=style.COLORS["fv-lts"], lw=1.4, mutation_scale=11)) + if merged: + xa = X0 + sum(v for v, _ in parcels[:merged[0]]) * LEN + xb = X0 + sum(v for v, _ in parcels[:merged[1] + 1]) * LEN + ax.plot([xa, xa, xb, xb], [y - 0.06, y - 0.12, y - 0.12, y - 0.06], color=style.COLORS["dw"], lw=1.0) + ax.text((xa + xb) / 2, y - 0.14, "merged: concentrations agree within tolerance", fontsize=6.8, ha="center", + va="top", color=style.COLORS["dw"]) + ax.text(X0 + LEN + 0.75, y + H / 2, note, fontsize=7.4, va="center", color=style.MUTED) + + +def _draw(style): + import matplotlib.pyplot as plt + cm = plt.get_cmap("Blues") + fig, ax = plt.subplots(figsize=(9.2, 5.0)) + fig.patch.set_facecolor(style.SURFACE) + rows = 5 + step = 0.92 + ys = [0.3 + (rows - 1 - k) * step for k in range(rows)] + # 1 drain: the downstream 0.20 of the slab leaves + _row(ax, ys[0], SLAB, style, cm, 0.20, 0.40, "1 Drain", "volume that left over the step goes to the\ndownstream node's inflow ledger, with its mass", + drain=0.20) + # 2 mix: nodes as CSTRs; downstream node now carries the mixed value + slab2 = [(0.18, 0.15), (0.22, 0.55), (0.20, 0.60), (0.20, 0.95)] + _row(ax, ys[1], slab2, style, cm, 0.20, 0.78, "2 Mix", "each node mixes held volume + arrivals as a CSTR,\nin flow-aware topological order; loads join here") + # 3 release: a new parcel at the upstream node's concentration; merge look-alikes + slab3 = [(0.20, 0.20), (0.18, 0.15), (0.42, 0.57), (0.20, 0.95)] + _row(ax, ys[2], slab3, style, cm, 0.20, 0.78, "3 Release", "a new parcel at the upstream node's new value,\nsized so parcels again sum to the link volume", + new=0, merged=(2, 2)) + # 4 decay + k = 0.75 + slab4 = [(v, c * k) for v, c in slab3] + _row(ax, ys[3], slab4, style, cm, 0.20 * k, 0.78 * k, "4 Decay", "exact exponential C ← C e^(−k Δt) on parcels and\nnode stores; removed mass booked as reacted") + # 5 publish + _row(ax, ys[4], slab4, style, cm, 0.20 * k, 0.78 * k, "5 Publish", "link concentration = volume-weighted mean of the\nparcels; the parcels themselves are kept", uniform=True) + ax.annotate("", xy=(X0 + LEN, ys[0] + H + 0.22), xytext=(X0, ys[0] + H + 0.22), + arrowprops=dict(arrowstyle="-|>", color=style.WATER, lw=1.6, mutation_scale=12)) + ax.text(X0 + LEN / 2, ys[0] + H + 0.27, "flow", fontsize=8, ha="center", color=style.WATER) + ax.text(X0 - 0.35, ys[0] + H + 0.27, "upstream\nnode", fontsize=7.2, ha="center", color=style.MUTED) + ax.text(X0 + LEN + 0.35, ys[0] + H + 0.27, "downstream\nnode", fontsize=7.2, ha="center", color=style.MUTED) + ax.text(0.05, -0.22, "Parcel budget: adjacent look-alikes merge at Release; MAX_SEGMENTS_PER_LINK (default 100) caps the slab,\n" + "merging the oldest first. QUALITY_STEP substeps the whole sequence; there is no Courant limit.", + fontsize=7.2, color=style.MUTED, va="top", linespacing=1.3) + ax.set_xlim(0, 12.6) + ax.set_ylim(-0.7, ys[0] + H + 0.75) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "quality_ch7_lard_parcels") diff --git a/docs/figures/src/quality/ch9_heat_budget.py b/docs/figures/src/quality/ch9_heat_budget.py new file mode 100644 index 000000000..e4f8258cd --- /dev/null +++ b/docs/figures/src/quality/ch9_heat_budget.py @@ -0,0 +1,80 @@ +"""The heat budget of a water body in the heat-transport component +(quality Chapter 9, §9.3.3–9.3.6 and §9.3.11): the six surface terms of +J_net grouped by the [HEAT_FLUXES] module that enables them, plus the bed +zone's conduction and hyporheic exchange. Sign convention of the text: +positive flux is heat leaving the water. Synthetic; no run. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = () + + +def _draw(style): + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon, Rectangle, Circle + fig, ax = plt.subplots(figsize=(9.2, 4.9)) + fig.patch.set_facecolor(style.SURFACE) + WARM, COOL = style.COLORS["fv-lts"], style.COLORS["fv"] + SUN = "#e6b422" + # ground, channel and water + ax.add_patch(Polygon([(0, 0), (12, 0), (12, 2.0), (9.2, 2.0), (8.2, 0.7), (3.8, 0.7), (2.8, 2.0), (0, 2.0)], closed=True, + fc=style.SOIL, ec="none", zorder=0)) + ax.add_patch(Polygon([(3.1, 1.6), (8.9, 1.6), (8.2, 0.7), (3.8, 0.7)], closed=True, fc=style.WATER, alpha=0.35, ec=style.WATER, lw=1.2, zorder=1)) + ax.add_patch(Rectangle((3.8, 0.0), 4.4, 0.7, fc="#bda98a", alpha=0.55, ec="none", zorder=0.5)) + ax.text(6.0, 1.15, "water T_w", fontsize=9, ha="center", color=style.INK) + ax.text(1.9, 4.55, "air T_a, RH, wind w, pressure p", fontsize=8, color=style.MUTED) + # land cover on the right bank + ax.add_patch(Rectangle((10.9, 2.0), 0.18, 1.0, fc="#7a5a3a", ec="none")) + ax.add_patch(Circle((10.99, 3.35), 0.55, fc="#6aa15c", ec="none")) + ax.text(11.0, 1.78, "land cover\n(1 − f_sky)", fontsize=7, ha="center", va="top", color=style.INK) + # sun + ax.add_patch(Circle((1.3, 4.6), 0.32, fc=SUN, ec="none")) + A = lambda col, lw=1.8: dict(arrowstyle="-|>", color=col, lw=lw, mutation_scale=13) + # incoming (warming): J_sn, J_an, J_lc + ax.annotate("", xy=(4.1, 1.62), xytext=(1.6, 4.35), arrowprops=A(SUN, 2.2)) + ax.text(0.2, 2.75, "J_sn net shortwave\n(1 − R_s) J_in max(0, 1 − f_s)", fontsize=7.4, color="#a07a10", ha="left", va="top") + ax.annotate("", xy=(5.2, 1.62), xytext=(5.2, 4.4), arrowprops=A(WARM)) + ax.text(5.1, 3.95, "J_an atmospheric longwave\nσ T_a⁴ ε_a (1 − R_L) f_sky", fontsize=7.4, color=WARM, ha="right", va="top") + ax.annotate("", xy=(8.6, 1.62), xytext=(10.55, 3.0), arrowprops=A(WARM)) + ax.text(9.25, 2.1, "J_lc ε_lc σ (1 − f_sky) T_a⁴", fontsize=7.0, color=WARM, ha="left", va="top") + # outgoing (cooling): J_br, J_e, J_h + ax.annotate("", xy=(6.35, 4.4), xytext=(6.35, 1.62), arrowprops=A(COOL)) + ax.text(6.45, 4.35, "J_br back radiation\nε_w σ T_w⁴", fontsize=7.4, color=COOL, ha="left", va="top") + ax.annotate("", xy=(7.3, 3.6), xytext=(7.3, 1.62), arrowprops=A(COOL)) + ax.text(7.4, 3.6, "J_e latent = ρ_w L_v E\nE = (a + b w)(e_w − e_a)\nsigned: condensation warms", fontsize=7.4, color=COOL, ha="left", va="top") + ax.annotate("", xy=(8.0, 2.55), xytext=(8.0, 1.62), arrowprops=A(COOL)) + ax.text(8.1, 2.62, "J_h = B_r J_e (Bowen)", fontsize=7.4, color=COOL, ha="left", va="top") + # bed zone: conduction and hyporheic exchange + ax.annotate("", xy=(4.6, 0.1), xytext=(4.6, 0.65), arrowprops=A(style.INK, 1.4)) + ax.annotate("", xy=(4.95, 0.65), xytext=(4.95, 0.1), arrowprops=A(style.INK, 1.4)) + ax.text(3.9, -0.08, "conduction G_cond (T_w − T_b)", fontsize=7.2, color=style.INK, va="top") + ax.annotate("", xy=(7.4, 0.62), xytext=(7.4, 0.12), arrowprops=A(style.WATER, 1.4)) + ax.annotate("", xy=(7.75, 0.12), xytext=(7.75, 0.62), arrowprops=A(style.WATER, 1.4)) + ax.text(8.2, -0.30, "hyporheic advection G_adv (T_w − T_b)", fontsize=7.2, color=style.WATER, va="top", ha="right") + ax.text(6.15, 0.44, "bed zone T_b", fontsize=7.4, ha="center", color=style.INK) + ax.text(6.15, 0.12, "to deep ground: G_bg (T_b − T_gr)", fontsize=6.8, ha="center", color=style.INK) + # sign convention and module grouping + ax.text(0.2, -0.80, + "Positive flux is heat leaving the water: J_net = (J_e + J_h) + (J_br − J_sn − J_an − J_lc)", + fontsize=8.2, color=style.INK) + ax.text(0.2, -1.10, "[HEAT_FLUXES] SURFACE_EXCHANGE → J_e, J_h RADIATIVE_EXCHANGE → J_sn, J_an, J_lc, J_br", + fontsize=7.2, color=style.MUTED) + ax.text(0.2, -1.36, "SEDIMENT_EXCHANGE → bed conduction, hyporheic exchange LAYER_CONDUCTION → LID layer conduction", + fontsize=7.2, color=style.MUTED) + ax.plot([0.2, 0.7], [-1.64, -1.64], color=WARM, lw=2.2) + ax.text(0.8, -1.64, "warms the water", fontsize=7.4, va="center", color=style.INK) + ax.plot([2.6, 3.1], [-1.64, -1.64], color=COOL, lw=2.2) + ax.text(3.2, -1.64, "cools the water (when positive)", fontsize=7.4, va="center", color=style.INK) + ax.set_xlim(0, 12) + ax.set_ylim(-1.82, 5.1) + ax.set_aspect("equal") + ax.axis("off") + fig.tight_layout(pad=0.2) + return fig + + +def build(sink): + import style + sink.save(_draw(style), "quality_ch9_heat_budget") diff --git a/docs/figures/src/workflows/ch11_rdii_decay.py b/docs/figures/src/workflows/ch11_rdii_decay.py new file mode 100644 index 000000000..ef96e1c1f --- /dev/null +++ b/docs/figures/src/workflows/ch11_rdii_decay.py @@ -0,0 +1,120 @@ +"""RDII with and without a physics-based recovery (Application Manual, +the long-term-hydrology chapter). + +The same two storms, thirty days apart, through one RTK unit hydrograph +group. Without `[RDII_DECAY]` the group answers both storms identically, +because an RTK hydrograph has no memory of what came before. With it, +the antecedent store depletes during the first storm and recovers at a +temperature-dependent rate, so the second storm produces less — and a +colder month produces less still. + +Simulated tier: three runs of docs/figures/decks/hydrology_additions, +cached under docs/figures/cache. +""" +from __future__ import annotations + +import re + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "hydrology_additions/rdii_decay.inp" +COLD = {"01/01/2026 00:00 34.0": "01/01/2026 00:00 24.0", + "01/10/2026 00:00 38.0": "01/10/2026 00:00 26.0", + "01/20/2026 00:00 45.0": "01/20/2026 00:00 30.0", + "01/31/2026 00:00 52.0": "01/31/2026 00:00 34.0"} + + +def _strip_decay(text): + """Drop the [RDII_DECAY] section, keeping the marker lines out with it.""" + lines = text.split("\n") + marks = [i for i, ln in enumerate(lines) if ln.strip() == ";//! [decay]"] + assert len(marks) == 2, f"expected two decay markers, found {len(marks)}" + out = "\n".join(lines[:marks[0]] + lines[marks[1] + 1:]) + # the deck's own header mentions the section by name, so test for the header line + assert not any(ln.strip().startswith("[RDII_DECAY]") for ln in out.split("\n")), \ + "the decay section was not removed" + return out + + +def _cold(text): + for a, b in COLD.items(): + assert a in text, a + text = text.replace(a, b) + return text + + +def _series(sink, key, text=None): + from openswmm.engine import OutputReader, OutNodeVar + r = sink.run(DECK, None, key, text=text) + with OutputReader(r.out) as o: + q = np.asarray(o.node_series("J_RDII", OutNodeVar.LATERAL_INFLOW), float) + return np.arange(len(q)) / 24.0, q # the deck reports hourly + + +def _storms(t, q): + a = q[t < 10.0] + b = q[(t >= 18.0) & (t < 28.0)] + return float(a.max()), float(b.max()), float(np.trapezoid(a) * 3600), float(np.trapezoid(b) * 3600) + + +def _draw(style, runs): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 4.0), gridspec_kw=dict(width_ratios=[1.5, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + for (label, colour), (t, q) in runs: + a0.plot(t, q, color=style.COLORS[colour], lw=1.6, label=label) + a0.set_xlim(0, 31) + a0.set_xlabel("day of the month") + a0.set_ylabel("RDII inflow at the node (cfs)") + a0.legend(fontsize=7.4, frameon=False, loc="upper right") + a0.set_title("(a) Two identical storms, nineteen days apart", fontsize=9, loc="left") + a0.text(0.16, 0.97, "Above freezing the store recovers between the storms and the second\n" + "produces about half the first. Below freezing recovery is suppressed\n" + "entirely, so the ground stays wet and the second storm produces more\n" + "than the first. The linear model with a zero recovery rate abstracts\n" + "both storms and reports no RDII at all.", + transform=a0.transAxes, fontsize=7.2, color=style.MUTED, va="top", linespacing=1.5) + a0.set_ylim(0, 8.2) + labels, first, second = [], [], [] + for (label, _), (t, q) in runs: + p1, p2, v1, v2 = _storms(t, q) + labels.append(label.split(":")[0].replace("exponential decay, ", "").replace("linear recovery", "linear\nrecovery")) + first.append(p1) + second.append(p2) + x = np.arange(len(labels)) + a1.bar(x - 0.19, first, 0.36, color=style.MUTED, label="first storm") + a1.bar(x + 0.19, second, 0.36, color=style.COLORS["fv"], label="second storm") + for i, (p1, p2) in enumerate(zip(first, second)): + if p1 > 0: + a1.text(i + 0.19, p2 + 0.12, f"{100 * p2 / p1:.0f} %", ha="center", fontsize=7.6, color=style.INK) + else: + a1.text(i, 0.25, "no RDII", ha="center", fontsize=7.4, color=style.MUTED) + a1.set_xticks(x) + a1.set_xticklabels(labels, fontsize=7.4) + a1.set_ylabel("peak RDII inflow (cfs)") + a1.set_ylim(0, max(max(first), max(second)) * 1.28) + a1.legend(fontsize=7.2, frameon=False, loc="upper right") + a1.set_title("(b) What the second storm produces", fontsize=9, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + base_text = (sink.fig_dir / "decks" / DECK).read_text() + runs = [ + (("linear recovery, IA_r = 0: no RDII at all", "dw-legacy"), + _series(sink, "no_decay", _strip_decay(base_text))), + (("exponential decay, month above freezing", "fv"), _series(sink, "decay")), + (("exponential decay, month below freezing", "dw"), _series(sink, "decay_cold", _cold(base_text))), + ] + for (label, _), (t, q) in runs: + p1, p2, v1, v2 = _storms(t, q) + share = f"{100 * p2 / p1:.0f} %" if p1 > 0 else "no RDII" + print(f" {label}: peaks {p1:.3f} then {p2:.3f} cfs ({share}), " + f"volumes {v1:,.0f} then {v2:,.0f} cf") + sink.save(_draw(style, runs), "workflow_ch11_rdii_decay_vs_linear") diff --git a/docs/figures/src/workflows/ch2_rapid_fill.py b/docs/figures/src/workflows/ch2_rapid_fill.py new file mode 100644 index 000000000..9da668bdc --- /dev/null +++ b/docs/figures/src/workflows/ch2_rapid_fill.py @@ -0,0 +1,128 @@ +"""A filling pipe under the dynamic wave and finite-volume routers +(Application Manual, the filling-pipe chapter). + +The deck is Vasconcelos, Wright and Roe's 2006 rapid-filling experiment, +run three ways with nothing changed but the routing and surcharge keys: +the finite-volume router with its static slot, the dynamic wave router +with EXTRAN surcharge, and the dynamic wave router with the Preissmann +slot. The measured pressure head, velocity and surge-tank level of the +laboratory pipe are plotted under all three. + +Simulated tier: each variant is one run of docs/figures/decks/rapid_fill, +cached under docs/figures/cache. +""" +from __future__ import annotations + +import csv +import re + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "rapid_fill/rapid_fill.inp" +VARIANTS = [ + ("FV, static slot", {"FLOW_ROUTING": "FV"}, "fv_slot", "fv"), + ("Dynamic wave, EXTRAN", {"FLOW_ROUTING": "DYNWAVE", "SURCHARGE_METHOD": "EXTRAN"}, "dw_extran", "dw-legacy"), + ("Dynamic wave, slot", {"FLOW_ROUTING": "DYNWAVE", "SURCHARGE_METHOD": "SLOT"}, "dw_slot", "dw-slot"), +] + + +def _observed(path): + t, y = [], [] + with open(path, newline="") as fh: + for row in csv.reader(r for r in fh if not r.startswith("#")): + if not row or not row[0].replace(".", "", 1).replace("-", "", 1).isdigit(): + continue + t.append(float(row[0])) + y.append(float(row[1])) + return np.array(t), np.array(y) + + +def _report_step(inp_text): + m = re.search(r"^REPORT_STEP\s+(\S+)", inp_text, re.M) + v = m.group(1) + if ":" in v: # hh:mm:ss + h, mi, s = (float(x) for x in v.split(":")) + return h * 3600 + mi * 60 + s + return float(v) + + +def _series(sink, options, key): + """(t, head at 9.9 m, velocity at 9.9 m, surge-tank depth) for one variant.""" + from openswmm.engine import OutputReader, OutNodeVar, OutLinkVar + run = sink.run(DECK, options, key) + dt = _report_step(run.inp.read_text()) + with OutputReader(run.out) as r: + n = r.period_count + t = np.arange(n) * dt + return (t, + np.asarray(r.node_series("VJ99", OutNodeVar.HEAD), dtype=float), + np.asarray(r.link_series("C2", OutLinkVar.VELOCITY), dtype=float), + np.asarray(r.node_series("ST", OutNodeVar.DEPTH), dtype=float), + run.seconds) + + +def _draw_pressure(style, runs, obs_t, obs_h): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.4, 4.2)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + ax.plot(obs_t, obs_h, marker="o", ms=2.2, lw=0, color=style.INK, alpha=0.55, + label="measured, Vasconcelos et al. 2006") + for (label, _, _, colour), (t, h, _, _, _) in zip(VARIANTS, runs): + ax.plot(t, h, color=style.COLORS[colour], lw=1.6, label=label) + ax.set_xlim(0, 15) + ax.set_ylim(0.0, 0.50) # the measured range; see the note on the EXTRAN excursion + ax.set_xlabel("time since the inflow starts (s)") + ax.set_ylabel("pressure head at x = 9.9 m (m)") + ax.legend(fontsize=7.6, frameon=False, loc="upper left") + ax.set_title("The bore arrives and the pipe fills: pressure head at the transducer", + fontsize=9.5, loc="left") + peak = max(float(h.max()) for _, h, _, _, _ in runs) + ax.text(0.15, 0.004, + "The arrival time is the bore speed and the rise is the closure's stiffness. Outside this window\n" + f"the EXTRAN run reaches {peak:.1f} m at t = 30.7 s — a spurious surcharge excursion forty times the\n" + "physical head, absent from both slot closures.", + fontsize=7.4, color=style.MUTED, va="bottom", ha="left", linespacing=1.45) + fig.tight_layout() + return fig + + +def _draw_front(style, runs, obs_v, obs_st): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 3.8)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + a0.plot(obs_v[0], obs_v[1], marker="o", ms=2.0, lw=0, color=style.INK, alpha=0.5, label="measured") + a1.plot(obs_st[0], obs_st[1], marker="o", ms=2.0, lw=0, color=style.INK, alpha=0.5, label="measured") + for (label, _, _, colour), (t, _, v, st, _) in zip(VARIANTS, runs): + a0.plot(t, v, color=style.COLORS[colour], lw=1.5, label=label) + a1.plot(t, st, color=style.COLORS[colour], lw=1.5, label=label) + a0.set_xlim(0, 40) + a1.set_xlim(0, 40) + a0.set_xlabel("time (s)") + a1.set_xlabel("time (s)") + a0.set_ylabel("velocity at x = 9.9 m (m/s)") + a1.set_ylabel("surge-tank level (m)") + a0.set_title("(a) Velocity: the front passing the transducer", fontsize=9, loc="left") + a1.set_title("(b) Surge tank: where the filled pipe puts the water", fontsize=9, loc="left") + a0.legend(fontsize=7.2, frameon=False) + fig.tight_layout() + return fig + + +def build(sink): + import style + runs = [_series(sink, opts, key) for _, opts, key, _ in VARIANTS] + decks = sink.fig_dir / "decks" / "rapid_fill" + obs_h = _observed(decks / "e2_pressure_9p9.csv") + obs_v = _observed(decks / "e2_velocity_9p9.csv") + obs_st = _observed(decks / "e2_surgetank_level.csv") + for label, (_, _, _, _, secs) in zip((v[0] for v in VARIANTS), runs): + print(f" {label}: {secs:.1f} s") + if "workflow_ch2_rapid_fill_pressure_9p9" in sink.expected: + sink.save(_draw_pressure(style, runs, *obs_h), "workflow_ch2_rapid_fill_pressure_9p9") + if "workflow_ch2_rapid_fill_front" in sink.expected: + sink.save(_draw_front(style, runs, obs_v, obs_st), "workflow_ch2_rapid_fill_front") diff --git a/docs/figures/src/workflows/ch3_negative_pressure.py b/docs/figures/src/workflows/ch3_negative_pressure.py new file mode 100644 index 000000000..3504811a7 --- /dev/null +++ b/docs/figures/src/workflows/ch3_negative_pressure.py @@ -0,0 +1,151 @@ +"""A sub-atmospheric transient under the slot and TPA closures +(Application Manual, the sub-atmospheric chapter). + +Vasconcelos, Wright and Roe's siphon experiment: the rapid-filling +pipeline with its centre raised, started full and drawn down by a siphon +at the upstream end. The pressure at the summit falls toward and through +the crown, which is the regime a Preissmann slot cannot represent — the +slot is open to the atmosphere — and which the two-component pressure +approach carries as a second component. The deck is run under both +closures on both routers, against the measured gauge pressure head at +x = 14.1 m and the measured velocity at x = 9.9 m. + +Simulated tier: four runs of docs/figures/decks/negative_pressure, +cached under docs/figures/cache. +""" +from __future__ import annotations + +import csv +import re + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "negative_pressure/negative_pressure.inp" +VARIANTS = [ + ("FV, TPA", {"FLOW_ROUTING": "FV", "FV_PRESSURE_CLOSURE": "TPA"}, "fv_tpa", "fv"), + ("FV, static slot", {"FLOW_ROUTING": "FV", "FV_PRESSURE_CLOSURE": "SLOT"}, "fv_slot", "dw-slot"), + ("Dynamic wave, TPA", {"FLOW_ROUTING": "DYNWAVE", "SURCHARGE_METHOD": "TPA", "TPA_CELERITY": "300"}, + "dw_tpa", "dw"), + ("Dynamic wave, slot", {"FLOW_ROUTING": "DYNWAVE", "SURCHARGE_METHOD": "SLOT"}, "dw_slot", "dw-legacy"), +] + + +def _observed(path): + t, y = [], [] + for row in csv.reader(r for r in open(path) if not r.startswith("#")): + if row and row[0][:1].isdigit(): + t.append(float(row[0])) + y.append(float(row[1])) + return np.array(t), np.array(y) + + +def _report_step(text): + v = re.search(r"^REPORT_STEP\s+(\S+)", text, re.M).group(1) + if ":" in v: + h, m, s = (float(x) for x in v.split(":")) + return h * 3600 + m * 60 + s + return float(v) + + +def _run(sink, options, key): + """(t, head, velocity, seconds, failure) — failure is the ERROR line when the run diverged. + + A run that cannot complete is a result here, not an exception: the static + slot cannot represent this deck's sub-atmospheric full-pipe flow and says + so by diverging. The figure reports that instead of hiding it. + """ + from openswmm.engine import OutputReader, OutNodeVar, OutLinkVar + r = sink.run(DECK, options, key) + dt = _report_step(r.inp.read_text()) + rpt = r.rpt.read_text(errors="replace") + fail = next((ln.strip() for ln in rpt.splitlines() if ln.strip().startswith("ERROR")), None) + with OutputReader(r.out) as o: + n = o.period_count + if n == 0: + return None, None, None, r.seconds, fail or "the run produced no reported periods", None + t = np.arange(n) * dt + # The stations are sealed junctions. A node's DEPTH is its gauge pressure + # head above the invert, which is what the transducers measured; the study's + # comparison subtracts the same datum from the absolute head. + return (t, + np.asarray(o.node_series("VJ141", OutNodeVar.DEPTH), float), + np.asarray(o.link_series("C3", OutLinkVar.VELOCITY), float), + r.seconds, fail, + np.asarray(o.node_series("VJC", OutNodeVar.DEPTH), float)) + + +def _draw(style, runs, obs_h, obs_v): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 4.1)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + a0.plot(*obs_h, marker="o", ms=2.0, lw=0, color=style.INK, alpha=0.55, label="measured") + failed = [] + for (label, _, _, colour), (t, h, v, _, fail, hc) in zip(VARIANTS, runs): + if t is None: + failed.append(label) + a0.plot([], [], color=style.COLORS[colour], lw=1.5, ls=(0, (2, 2)), + label=f"{label} — diverged, no solution") + a1.plot([], [], color=style.COLORS[colour], lw=1.5, ls=(0, (2, 2))) + continue + a0.plot(t, h, color=style.COLORS[colour], lw=1.5, label=label) + a1.plot(t, hc, color=style.COLORS[colour], lw=1.5, label=label) + a1.axhline(0.0, color=style.INK, lw=1.0) + a1.axhline(0.1007, color=style.MUTED, lw=0.9, ls=(0, (4, 2))) + a1.text(0.6, 0.104, "crown of the pipe at the summit", fontsize=7.0, color=style.MUTED) + for ax in (a0, a1): + ax.set_xlim(0, 40) + ax.set_xlabel("time since the withdrawal starts (s)") + a0.set_ylabel("gauge pressure head at x = 14.1 m (m)") + a1.set_ylabel("gauge pressure head at the summit (m)") + a0.set_title("(a) The drawdown, against the measurement", fontsize=9, loc="left") + a1.set_title("(b) At the summit, where the column is most at risk", fontsize=9, loc="left") + a0.legend(fontsize=7.2, frameon=False, loc="lower left") + note = ("the summit empties to zero gauge under FV with TPA\n" + "at t = 31.6 s: the column separates") + if failed: + note += "\n" + ", ".join(failed) + " diverged rather than reporting a wrong answer" + a1.text(17.5, a1.get_ylim()[1] - 0.012, note, fontsize=7.2, color=style.MUTED, va="top", ha="left", + linespacing=1.4) + fig.tight_layout() + return fig + + +def _draw_velocity(style, runs, obs_v): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.4, 3.9)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + ax.plot(*obs_v, marker="o", ms=2.2, lw=0, color=style.INK, alpha=0.55, label="measured") + for (label, _, _, colour), (t, _, v, _, _, _) in zip(VARIANTS, runs): + if t is None: + ax.plot([], [], color=style.COLORS[colour], lw=1.5, ls=(0, (2, 2)), label=f"{label} — diverged") + continue + ax.plot(t, v, color=style.COLORS[colour], lw=1.5, label=label) + ax.set_xlim(0, 40) + ax.set_xlabel("time since the withdrawal starts (s)") + ax.set_ylabel("velocity at x = 9.9 m (m/s)") + ax.legend(fontsize=7.4, frameon=False) + ax.set_title("The same four runs, at the velocity transducer", fontsize=9.5, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + runs = [_run(sink, o, k) for _, o, k, _ in VARIANTS] + decks = sink.fig_dir / "decks" / "negative_pressure" + obs_h = _observed(decks / "e3_pressure_14p1.csv") + obs_v = _observed(decks / "e3_velocity_9p9.csv") + for (label, _, _, _), (_, h, _, secs, fail, _) in zip(VARIANTS, runs): + if h is None: + print(f" {label}: {secs:.1f} s, DIVERGED — {fail}") + else: + print(f" {label}: {secs:.1f} s, min head {h.min():+.3f} m") + if "workflow_ch3_negative_pressure_head_14p1" in sink.expected: + sink.save(_draw(style, runs, obs_h, obs_v), "workflow_ch3_negative_pressure_head_14p1") + if "workflow_ch3_velocity_9p9" in sink.expected: + sink.save(_draw_velocity(style, runs, obs_v), "workflow_ch3_velocity_9p9") diff --git a/docs/figures/src/workflows/ch4_virtual_junctions.py b/docs/figures/src/workflows/ch4_virtual_junctions.py new file mode 100644 index 000000000..1865e4850 --- /dev/null +++ b/docs/figures/src/workflows/ch4_virtual_junctions.py @@ -0,0 +1,123 @@ +"""A surveyed trunk chained by virtual junctions (Application Manual, the +virtual-junctions chapter). + +Cedar Glen to FRS: a synthetic raw-water conveyance built the way a +GIS-derived network is — a long trunk of short survey segments joined by +virtual junctions rather than manholes, with a double-pocket reach that +pressurises at each surge peak. Three decks differ only in their routing +options. The figures are the trunk's hydraulic grade line at the worst +instant and the head history of the node where the solvers disagree +most. + +Simulated tier: three runs of docs/figures/decks/cedar_glen, cached +under docs/figures/cache. The finite-volume run takes about two minutes. +""" +from __future__ import annotations + +import json + +import numpy as np + +REQUIRES = ("openswmm",) + +DECKS = [("cedar_glen_fv.inp", "FV", "finite volume", "fv"), + ("cedar_glen_dw.inp", "DW slot", "dynamic wave, Preissmann slot", "dw-slot"), + ("cedar_glen_dw_extran.inp", "DW EXTRAN", "dynamic wave, EXTRAN surcharge", "dw-legacy")] + + +def _meta(sink): + return json.loads((sink.fig_dir / "decks" / "cedar_glen" / "model_meta.json").read_text()) + + +def _heads(run, names): + from openswmm.engine import OutputReader, OutNodeVar + with OutputReader(run.out) as o: + have = set(o.node_ids) + idx = [n for n in names if n in have] + H = np.column_stack([np.asarray(o.node_series(n, OutNodeVar.HEAD), float) for n in idx]) + t = np.arange(o.period_count) / 60.0 # the decks report every minute + return t, idx, H + + +def _continuity(run): + """The Flow Routing Continuity block's error, not the last line that mentions one.""" + lines = run.rpt.read_text(errors="replace").splitlines() + start = next(i for i, ln in enumerate(lines) if "Flow Routing Continuity" in ln) + for ln in lines[start:start + 20]: + if "Continuity Error" in ln: + return float(ln.split()[-1]) + raise RuntimeError("no continuity error in the Flow Routing Continuity block") + + +def _draw_profile(style, meta, runs, worst_k): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(9.2, 4.2)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + s = np.array([p["s"] for p in meta["trunk"]]) / 1000.0 + z = np.array([p["z"] for p in meta["trunk"]]) + crown = z + np.array([p["diam"] for p in meta["trunk"]]) / 12.0 + ax.fill_between(s, z - 6.0, z, color=style.SOIL, zorder=0) + ax.plot(s, z, color=style.INK, lw=1.2, label="invert") + ax.plot(s, crown, color=style.MUTED, lw=1.0, ls=(0, (4, 2)), label="crown") + for (_, short, label, colour), (t, idx, H, _) in zip(DECKS, runs): + pos = {n: i for i, n in enumerate(idx)} + sel = [(p["s"] / 1000.0, H[worst_k, pos[p["name"]]]) for p in meta["trunk"] if p["name"] in pos] + xs = np.array([a for a, _ in sel]) + ys = np.array([b for _, b in sel]) + ax.plot(xs, ys, color=style.COLORS[colour], lw=1.6, label=f"{short}: {label}") + ax.set_xlabel("chainage along the trunk (1000 ft)") + ax.set_ylabel("head (ft)") + ax.legend(fontsize=7.4, frameon=False, loc="upper right", ncol=2) + ax.set_title("The hydraulic grade line along the trunk, at the instant the solvers disagree most", + fontsize=9.5, loc="left") + ax.text(0.02, 0.06, "370 virtual junctions chain 387 conduits into one continuous trunk: no manhole,\n" + "no storage, no head loss at a splice — the grade line runs through them.", + transform=ax.transAxes, fontsize=7.4, color=style.MUTED, va="bottom", linespacing=1.45) + fig.tight_layout() + return fig + + +def _draw_worst(style, runs, worst_node): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.8, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + for (_, short, label, colour), (t, idx, H, secs) in zip(DECKS, runs): + pos = {n: i for i, n in enumerate(idx)} + ax.plot(t, H[:, pos[worst_node]], color=style.COLORS[colour], lw=1.6, + label=f"{short} — {label}") + ax.set_xlabel("time (hours)") + ax.set_ylabel(f"head at {worst_node} (ft)") + ax.legend(fontsize=7.4, frameon=False, loc="lower right") + ax.text(0.02, 0.94, "The slot run oscillates between the pocket floor and the crest for hours; the other two\n" + "hold a smooth recession. Its flow-routing continuity error is -8.3 %.", + transform=ax.transAxes, fontsize=7.4, color=style.MUTED, va="top", linespacing=1.45) + ax.set_title("Head at the node where the three routings disagree most", fontsize=9.5, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + meta = _meta(sink) + names = [p["name"] for p in meta["trunk"]] + runs, conts = [], [] + for deck, short, _, _ in DECKS: + run = sink.run(f"cedar_glen/{deck}", None, deck.replace(".inp", "")) + t, idx, H = _heads(run, names) + runs.append((t, idx, H, run.seconds)) + conts.append(_continuity(run)) + print(f" {short}: {run.seconds:.0f} s, continuity {conts[-1]:+.3f} %, " + f"{H.shape[1]} trunk nodes reported") + # the instant and the node of greatest disagreement between FV and DW-slot + a, b = runs[0][2], runs[1][2] + n = min(a.shape[0], b.shape[0]) + diff = np.abs(a[:n] - b[:n]) + worst_k, worst_i = np.unravel_index(int(np.argmax(diff)), diff.shape) + worst_node = runs[0][1][worst_i] + print(f" worst disagreement {diff.max():.2f} ft at {worst_node}, t = {runs[0][0][worst_k]:.2f} h") + if "workflow_ch4_cedar_glen_profile_hgl" in sink.expected: + sink.save(_draw_profile(style, meta, runs, worst_k), "workflow_ch4_cedar_glen_profile_hgl") + if "workflow_ch4_cedar_glen_worst_node_head" in sink.expected: + sink.save(_draw_worst(style, runs, worst_node), "workflow_ch4_cedar_glen_worst_node_head") diff --git a/docs/figures/src/workflows/ch5_street_inlets.py b/docs/figures/src/workflows/ch5_street_inlets.py new file mode 100644 index 000000000..6d46ff251 --- /dev/null +++ b/docs/figures/src/workflows/ch5_street_inlets.py @@ -0,0 +1,112 @@ +"""Capture and bypass along a street reach with two inlets +(Application Manual, the street-inlets chapter). + +One street draining to a parallel sewer through two inlets attached two +different ways: a conduit-attribute inlet on the first reach, whose +capture is booked at the reach's downstream node, and an inlet junction +between the second and third reaches, which is a node of its own. The +figure follows the water: what stays on the street, what each inlet takes, +and what the sewer receives. + +Simulated tier: one run of docs/figures/decks/street_inlets, cached under +docs/figures/cache. +""" +from __future__ import annotations + +import re + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "street_inlets/street_inlet_junction.inp" +STREET = [("ST_A", "street above the first inlet"), ("ST_B", "street between the inlets"), + ("ST_C", "street below the inlet junction")] +CAPTURE = [("MH1", "captured by the conduit-attribute inlet on ST_A"), + ("MH2", "captured by the inlet junction IJ1")] + + +def _summary_rows(rpt_text): + """The Street Inlet Flow Summary, as + {location: (peak approach flow, peak capture %, average capture %, bypass frequency %, + captured 1000 gal, bypassed 1000 gal)}. + + Note the fourth column of the report: "Bypass Flow Pcnt" is the *frequency* of + bypass over the capture periods, not a share of the volume. The volume split is + the last two columns. + """ + out = {} + block = rpt_text.split("Street Inlet Flow Summary", 1) + if len(block) < 2: + return out + for ln in block[1].splitlines(): + m = re.match(r"^\s{2}(\S+(?: \(node\))?)\s+(\S+)\s+\S+\s+(\d+)\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s+" + r"([\d.]+)\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*$", ln) + if m: + out[m.group(1)] = tuple(float(m.group(i)) for i in (4, 5, 6, 7, 11, 12)) + return out + + +def _draw(style, t, street, capture, rows): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 3.9), gridspec_kw=dict(width_ratios=[1.35, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + cols = [style.COLORS["fv"], style.COLORS["fv-lts"], style.COLORS["dw"]] + for (name, label), q, c in zip(STREET, street, cols): + a0.plot(t, q, color=c, lw=1.7, label=f"{name} — {label}") + for (name, label), q, ls in zip(CAPTURE, capture, ("-", (0, (4, 2)))): + a0.plot(t, q, color=style.MUTED, lw=1.3, ls=ls, label=label) + a0.set_yscale("symlog", linthresh=0.05) + a0.set_xlabel("time (hours)") + a0.set_ylabel("flow (cfs)") + a0.legend(fontsize=6.9, frameon=False, loc="upper right") + a0.set_title("(a) What stays on the street, and what each inlet takes", fontsize=9, loc="left") + a0.text(2.95, 0.35, "symmetric log scale below 0.05 cfs.\nThe street flow falls by three orders\n" + "of magnitude across the two inlets.", fontsize=7.0, color=style.MUTED, va="center", ha="right", + linespacing=1.45) + # capture / bypass split per inlet, from the report's own summary + labels, cap, byp = [], [], [] + for key, nice in (("ST_A", "ST_A\nconduit attribute"), ("IJ1 (node)", "IJ1\ninlet junction")): + if key not in rows: + continue + labels.append(nice) + cap.append(rows[key][4]) + byp.append(rows[key][5]) + # a share, not a volume: the two inlets differ by two orders of magnitude in + # the water they see, and the question here is what each did with it + x = np.arange(len(labels)) + tot = [c + b for c, b in zip(cap, byp)] + cap_pct = [100 * c / s for c, s in zip(cap, tot)] + byp_pct = [100 * b / s for b, s in zip(byp, tot)] + a1.bar(x, cap_pct, 0.5, color=style.COLORS["fv"], label="captured") + a1.bar(x, byp_pct, 0.5, bottom=cap_pct, color=style.COLORS["dw-legacy"], label="bypassed") + for i, (c, b, s) in enumerate(zip(cap, byp, tot)): + a1.text(i, cap_pct[i] / 2, f"{cap_pct[i]:.1f} %\n{c:,.1f} kgal", ha="center", va="center", + fontsize=7.6, color="white", linespacing=1.4) + a1.text(i, 101.5, f"bypass {byp_pct[i]:.1f} % ({b:,.2f} kgal)", ha="center", fontsize=7.2, + color=style.INK) + a1.set_xticks(x) + a1.set_xticklabels([f"{lab}\n{s:,.1f} kgal reached it" for lab, s in zip(labels, tot)], fontsize=7.6) + a1.set_ylabel("share of the water reaching the inlet (%)") + a1.set_ylim(0, 118) + a1.set_title("(b) What each inlet did with what reached it", fontsize=9, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + from openswmm.engine import OutputReader, OutNodeVar, OutLinkVar + run = sink.run(DECK, None, "base") + with OutputReader(run.out) as o: + n = o.period_count + t = np.arange(n) / 60.0 # the deck reports every minute + street = [np.asarray(o.link_series(k, OutLinkVar.FLOW), float) for k, _ in STREET] + capture = [np.asarray(o.node_series(k, OutNodeVar.LATERAL_INFLOW), float) for k, _ in CAPTURE] + rows = _summary_rows(run.rpt.read_text(errors="replace")) + for k, v in rows.items(): + print(f" {k}: peak approach {v[0]:.3f} cfs, peak capture {v[1]:.2f} %, avg capture {v[2]:.2f} %, " + f"bypass frequency {v[3]:.2f} %, {v[4]:,.3f} kgal captured / {v[5]:,.3f} kgal bypassed") + sink.save(_draw(style, t, street, capture, rows), "workflow_ch5_inlet_capture_vs_bypass") diff --git a/docs/figures/src/workflows/ch6_coupled_1d2d.py b/docs/figures/src/workflows/ch6_coupled_1d2d.py new file mode 100644 index 000000000..1f57490f6 --- /dev/null +++ b/docs/figures/src/workflows/ch6_coupled_1d2d.py @@ -0,0 +1,151 @@ +"""A coupled one- and two-dimensional model (Application Manual, the +coupled chapter). + +Two figures from the engine's complete 2D example: the mesh itself, with +every boundary condition and both kinds of coupling point marked, drawn +from the results file and the deck; and the depth history of one cell +under the three momentum closures, which is the choice the chapter is +about. + +Simulated tier: four runs of docs/figures/decks/coupled_1d2d, cached +under docs/figures/cache. The results file is HDF5, so this generator +needs h5py as well as the openswmm package. +""" +from __future__ import annotations + +import re + +import numpy as np + +REQUIRES = ("openswmm", "h5py") + +DECK = "coupled_1d2d/2d_complete_example.inp" +CLOSURES = [("LOCAL_INERTIAL", "local inertial (the default)", "fv"), + ("FULL_SWE", "full shallow water", "dw"), + ("DIFFUSIVE_WAVE", "diffusive wave", "fv-lts")] +WATCH = 4 # the cell whose depth history the second figure follows +BC_COLOUR = {"NORMAL_FLOW": "#1baf7a", "TS_STAGE": "#2a78d6", "RATING_CURVE": "#6f42c1", + "SPECIFIED_FLOW": "#eb6834", "SPECIFIED_STAGE": "#eda100"} + + +def _section(text, name): + m = re.search(rf"^\[{name}\]\s*$(.*?)(?=^\[|\Z)", text, re.M | re.S) + if not m: + return [] + out = [] + for ln in m.group(1).splitlines(): + s = ln.split(";")[0].strip() + if s: + out.append(s.split()) + return out + + +def _mesh(h5): + import h5py # noqa: F401 + x = np.asarray(h5["Mesh2_node_x"]) + y = np.asarray(h5["Mesh2_node_y"]) + tri = np.asarray(h5["Mesh2_face_nodes"]) + z = np.asarray(h5["Mesh2_face_z"]) + depth = np.asarray(h5["Mesh2_face_max_depth"]) # the engine's own per-cell maximum + cx = np.asarray(h5["Mesh2_face_x"]) + cy = np.asarray(h5["Mesh2_face_y"]) + return x, y, tri, z, depth, cx, cy + + +def _draw_mesh(style, run, deck_text): + import h5py + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon + with h5py.File(run.h5, "r") as h5: + x, y, tri, z, depth, cx, cy = _mesh(h5) + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 4.3)) + fig.patch.set_facecolor(style.SURFACE) + for ax, vals, title, cmap, unit in ( + (a0, z, "(a) The mesh: bed elevation, boundaries and coupling points", "terrain", "m"), + (a1, depth, "(b) The maximum depth each cell reached", "Blues", "m")): + cm = plt.get_cmap(cmap) + lo, hi = float(np.min(vals)), float(np.max(vals)) + rng = (hi - lo) or 1.0 + for t, v in zip(tri, vals): + ax.add_patch(Polygon(np.column_stack([x[t], y[t]]), closed=True, + fc=cm(0.25 + 0.6 * (v - lo) / rng), ec=style.MUTED, lw=0.8)) + for i, (px, py) in enumerate(zip(cx, cy)): + ax.text(px, py, f"{i}", fontsize=6.6, ha="center", va="center", color=style.INK, alpha=0.6) + mx, my = 0.10 * (x.max() - x.min()), 0.10 * (y.max() - y.min()) + ax.set_xlim(x.min() - mx, x.max() + mx) + ax.set_ylim(y.min() - 3.2 * my, y.max() + my) + ax.set_aspect("equal", adjustable="box") + ax.axis("off") + ax.set_title(title, fontsize=9, loc="left") + ax.text(x.min(), y.min() - 0.8 * my, f"{lo:.2f} to {hi:.2f} {unit}", fontsize=7.2, color=style.MUTED) + # boundary conditions, on panel (a) + seen = set() + for row in _section(deck_text, "2D_BOUNDARY_CONDITIONS"): + t, e, kind = int(row[0]), int(row[1]), row[2] + v = tri[t] + a, b = v[(e + 1) % 3], v[(e + 2) % 3] + a0.plot([x[a], x[b]], [y[a], y[b]], color=BC_COLOUR.get(kind, style.INK), lw=3.2, + solid_capstyle="round", zorder=4, + label=kind.replace("_", " ").lower() if kind not in seen else None) + seen.add(kind) + # coupling points + for row in _section(deck_text, "2D_VERTEX_NODE_MAP"): + v = int(row[0]) + a0.plot(x[v], y[v], marker="o", ms=10, mfc="none", mec="#e8484c", mew=2.0, zorder=6, + label="vertex coupled to a node") + a0.text(x[v], y[v] - 2.2, f"vertex {v} → {row[1]}", fontsize=7.0, ha="center", color="#e8484c", zorder=6) + for row in _section(deck_text, "2D_TRIANGLE_NODE_MAP"): + a0.plot([], [], marker="s", ms=8, mfc="none", mec="#e8484c", mew=2.0, lw=0, + label=f"cells tagged {row[0]} coupled to {row[1]}") + a0.legend(fontsize=6.6, frameon=False, loc="lower left", ncol=2, handlelength=1.4, + columnspacing=1.0) + a1.text(x.min(), y.min() - 2.4, "cell numbers are the triangle indices the deck uses", + fontsize=7.0, color=style.MUTED) + fig.tight_layout() + return fig + + +def _draw_closures(style, series): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.6, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + for (name, label, colour), (t, d, secs) in zip(CLOSURES, series): + ax.plot(t, d, color=style.COLORS[colour], lw=1.8, label=f"MOMENTUM_EQUATION {name} — {label}") + ax.set_xlabel("time (hours)") + ax.set_ylabel(f"depth in cell {WATCH} (m)") + ax.legend(fontsize=7.4, frameon=False, loc="center right") + ax.set_title("The same coupled model under the three momentum closures", fontsize=9.5, loc="left") + spread = max(float(np.max(np.abs(series[0][1] - s[1]))) for s in series[1:]) + ax.text(0.03, 0.06, "The three closures share every other part of the marcher: the same mesh, the same time\n" + f"stepping, the same coupling. On this cell they disagree by up to {spread:.2f} m and hold that\n" + "disagreement — the closure is not a cosmetic choice. Eight cells under strong boundary\n" + "forcing is a feature demonstration, not a validation: see the analytic cases of Hydraulics 9.", + transform=ax.transAxes, fontsize=7.4, color=style.MUTED, va="bottom", linespacing=1.45) + fig.tight_layout() + return fig + + +def build(sink): + import h5py + import style + deck_text = (sink.fig_dir / "decks" / DECK).read_text() + base = sink.run(DECK, None, "base") + # MOMENTUM_EQUATION lives in [2D_OPTIONS], so the variant is made by adding + # the line to the committed deck rather than by upserting into [OPTIONS] + series = [] + for name, _, _ in CLOSURES: + text = re.sub(r"^(INTEGRATOR\s+EXPLICIT.*)$", r"\1\nMOMENTUM_EQUATION " + name, + deck_text, count=1, flags=re.M) + assert "MOMENTUM_EQUATION" in text, "the deck's [2D_OPTIONS] INTEGRATOR line was not found" + run = sink.run(DECK, None, f"closure_{name.lower()}", text=text) + with h5py.File(run.h5, "r") as h5: + d = np.asarray(h5["Mesh2_face_depth"])[:, WATCH] + tt = np.asarray(h5["time"]) + t_h = (tt - tt[0]) * 24.0 + series.append((t_h, d, run.seconds)) + print(f" {name}: {run.seconds:.2f} s, peak depth {d.max():.3f} m in cell {WATCH}") + if "workflow_ch6_mesh_and_coupling" in sink.expected: + sink.save(_draw_mesh(style, base, deck_text), "workflow_ch6_mesh_and_coupling") + if "workflow_ch6_momentum_closures_depth" in sink.expected: + sink.save(_draw_closures(style, series), "workflow_ch6_momentum_closures_depth") diff --git a/docs/figures/src/workflows/ch7_mesh_hydrology.py b/docs/figures/src/workflows/ch7_mesh_hydrology.py new file mode 100644 index 000000000..b848cec8a --- /dev/null +++ b/docs/figures/src/workflows/ch7_mesh_hydrology.py @@ -0,0 +1,108 @@ +"""Rain and infiltration on a mesh (Application Manual, the +mesh-hydrology chapter). + +Two gages of different intensity stand west and east of a 20 x 20 m +patch, so every cell takes its own interpolated rainfall; three soil tags +give the cells three infiltration methods. The figure is the two fields +the run produces, read from the 2D results file: what fell on each cell, +and what went into the ground. + +Simulated tier: one run of docs/figures/decks/mesh_hydrology, cached +under docs/figures/cache. Needs h5py as well as the openswmm package. +""" +from __future__ import annotations + +import re + +import numpy as np + +REQUIRES = ("openswmm", "h5py") + +DECK = "mesh_hydrology/mesh_hydrology.inp" +METHOD_OF_TAG = {"LAWN": "HORTON", "PAVED": "CONSTANT", "WOODS": "GREEN_AMPT"} + + +def _tags(deck_text): + m = re.search(r"^\[2D_TRIANGLES\]\s*$(.*?)(?=^\[|\Z)", deck_text, re.M | re.S) + out = [] + for ln in m.group(1).splitlines(): + s = ln.split(";")[0].split() + if len(s) >= 6: + out.append(s[5]) + return out + + +def _gages(deck_text): + m = re.search(r"^\[SYMBOLS\]\s*$(.*?)(?=^\[|\Z)", deck_text, re.M | re.S) + out = [] + for ln in m.group(1).splitlines(): + s = ln.split(";")[0].split() + if len(s) >= 3: + out.append((s[0], float(s[1]), float(s[2]))) + return out + + +def _draw(style, h5, deck_text): + import matplotlib.pyplot as plt + from matplotlib.patches import Polygon + x = np.asarray(h5["Mesh2_node_x"]) + y = np.asarray(h5["Mesh2_node_y"]) + tri = np.asarray(h5["Mesh2_face_nodes"]) + cx = np.asarray(h5["Mesh2_face_x"]) + cy = np.asarray(h5["Mesh2_face_y"]) + rain = np.asarray(h5["Mesh2_face_rainfall"])[10] * 1000.0 * 3600.0 # mm/hr while it rains + infil = np.asarray(h5["Mesh2_face_infil_cum"])[-1] * 1000.0 # mm over the storm + depth = np.asarray(h5["Mesh2_face_max_depth"]) * 1000.0 # mm + tags = _tags(deck_text) + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.4, 4.5)) + fig.patch.set_facecolor(style.SURFACE) + for ax, vals, cmap, title, fmt in ( + (a0, rain, "Blues", "(a) Rainfall on each cell, interpolated from two gages", "{:.1f}"), + (a1, infil, "YlOrBr", "(b) Water infiltrated over the storm", "{:.2f}")): + cm = plt.get_cmap(cmap) + lo, hi = float(vals.min()), float(vals.max()) + rng = (hi - lo) or 1.0 + for t, v in zip(tri, vals): + ax.add_patch(Polygon(np.column_stack([x[t], y[t]]), closed=True, + fc=cm(0.18 + 0.68 * (v - lo) / rng), ec=style.MUTED, lw=0.9)) + for i, (px, py, v) in enumerate(zip(cx, cy, vals)): + ax.text(px, py + 0.7, fmt.format(v), fontsize=7.4, ha="center", va="center", color=style.INK) + ax.set_xlim(-9.0, 29.0) + ax.set_ylim(-4.0, 24.0) + ax.set_aspect("equal", adjustable="box") + ax.axis("off") + ax.set_title(title, fontsize=9, loc="left") + # the gages, on panel (a) + for name, gx, gy in _gages(deck_text): + a0.plot(gx, gy, marker="*", ms=15, mfc="#ffd23f", mec=style.INK, mew=0.9, zorder=5) + a0.text(gx, gy - 1.8, name, fontsize=7.4, ha="center", color=style.INK) + a0.text(0.0, -2.6, "mm/hr in each cell while it rains; the gages read 20 and 5 mm/hr", + fontsize=7.2, color=style.MUTED) + a0.text(0.0, 22.3, "Laplace natural-neighbour weights: every cell takes its own value,\n" + "and no cell leaves the range of the gage readings.", fontsize=7.2, color=style.MUTED, + linespacing=1.45) + # the tags and their methods, on panel (b) + for i, (px, py) in enumerate(zip(cx, cy)): + a1.text(px, py - 1.0, f"{tags[i]}\n{METHOD_OF_TAG[tags[i]]}", fontsize=6.2, ha="center", va="center", + color=style.MUTED, linespacing=1.3) + a1.text(0.0, -2.6, "mm infiltrated over the storm, per cell", fontsize=7.2, color=style.MUTED) + dry = int(np.argmin(depth)) + a1.text(0.0, 22.3, f"Three tags, three methods. Cell {dry} infiltrated {infil[dry]:.2f} mm: it never\n" + f"held more than {depth[dry]:.2f} mm of water, and the sink is ramped off below DRY_DEPTH.", + fontsize=7.2, color=style.MUTED, linespacing=1.45) + fig.tight_layout() + return fig + + +def build(sink): + import h5py + import style + deck_text = (sink.fig_dir / "decks" / DECK).read_text() + run = sink.run(DECK, None, "base") + with h5py.File(run.h5, "r") as h5: + fig = _draw(style, h5, deck_text) + rain = np.asarray(h5["Mesh2_face_rainfall"])[10] * 1000.0 * 3600.0 + infil = np.asarray(h5["Mesh2_face_infil_cum"])[-1] * 1000.0 + print(f" rainfall per cell {rain.min():.1f} to {rain.max():.1f} mm/hr; " + f"infiltration {infil.min():.2f} to {infil.max():.2f} mm") + sink.save(fig, "workflow_ch7_rain_and_infiltration") diff --git a/docs/figures/src/workflows/ch8_transport_engines.py b/docs/figures/src/workflows/ch8_transport_engines.py new file mode 100644 index 000000000..0f26f278e --- /dev/null +++ b/docs/figures/src/workflows/ch8_transport_engines.py @@ -0,0 +1,135 @@ +"""The three transport engines on one tracer front (Application Manual, +the transport-engines chapter). + +A step of conservative tracer enters a five-conduit line at t = 0 and +travels 500 m to the outfall. The three engines selected by +`[OPTIONS] QUALITY_SOLVER` are run on the same deck, with the reporting +step shortened so the front is resolved rather than stepped over, and the +Eulerian engine is then run again at three cell sizes to show what +`TARGET_DX` buys and costs. + +Simulated tier: six runs of docs/figures/decks/transport_demo, cached +under docs/figures/cache. +""" +from __future__ import annotations + +import re + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "transport_demo/transport_demo.inp" +# 10 s reporting: the front crosses the line in about five minutes, so the +# deck's own 5-minute reporting steps straight over it +FINE = {"REPORT_STEP": "0:00:10"} +ENGINES = [ + ("EULERIAN_ARD", "Eulerian, MUSCL with the van Leer limiter", "fv"), + ("LAGRANGIAN", "Lagrangian parcels", "dw"), + ("LEGACY", "legacy CSTR routing", "dw-legacy"), +] +DXS = [(50, "dw-slot"), (25, "fv"), (10, "fv-lts")] +ARD_TEMPLATE = """;; Eulerian ARD transport options — generated for the Application Manual's +;; TARGET_DX comparison; the committed sidecar carries TARGET_DX 25. + +[TRANSPORT_OPTIONS] +DISPERSION FISCHER +SCALAR_SCHEME MUSCL +LIMITER VANLEER +TARGET_DX {dx} +""" + + +def _series(sink, options, key, sidecars=None): + from openswmm.engine import OutputReader, OutNodeVar + r = sink.run(DECK, options, key, sidecars=sidecars) + dt = 10.0 + with OutputReader(r.out) as o: + base = int(OutNodeVar.POLLUT_BASE) + i = o.pollutant_ids.index("TRACER") + c = np.asarray([o.node_attributes("J5", period=k)[base + i] for k in range(o.period_count)], float) + return np.arange(len(c)) * dt / 60.0, c, r.seconds + + +def _travel(t, c, level=5.0): + """Time at which the front reaches half its plateau, by linear interpolation.""" + k = int(np.argmax(c >= level)) + if c[k] < level or k == 0: + return float("nan") + t0, t1, c0, c1 = t[k - 1], t[k], c[k - 1], c[k] + return float(t0 + (level - c0) * (t1 - t0) / (c1 - c0)) + + +def _draw_engines(style, runs): + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.6, 4.0)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + for (name, label, colour), (t, c, secs) in zip(ENGINES, runs): + ax.plot(t, c, color=style.COLORS[colour], lw=1.8, label=f"QUALITY_SOLVER {name} — {label}") + t50 = _travel(t, c) + if np.isfinite(t50): + ax.plot([t50], [5.0], marker="o", ms=5, color=style.COLORS[colour], mec="white", mew=1.0, zorder=5) + ax.axhline(10.0, color=style.MUTED, lw=0.9, ls=(0, (4, 2))) + ax.text(0.15, 10.15, "inflow concentration, 10 mg/L", fontsize=7.2, color=style.MUTED) + ax.axhline(5.0, color=style.GRIDC, lw=0.8) + ax.text(19.85, 5.25, "half of it: the marker on each curve is the half-rise", fontsize=7.2, + color=style.MUTED, ha="right") + ax.set_xlim(0, 20) + ax.set_ylim(0, 11.4) + ax.set_xlabel("time (minutes)") + ax.set_ylabel("tracer at J5, 400 m downstream (mg/L)") + ax.legend(fontsize=7.4, frameon=False, loc="lower right") + ax.set_title("A step of conservative tracer, reported every 10 s", fontsize=9.5, loc="left") + return fig + + +def _draw_dx(style, runs): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 3.8), gridspec_kw=dict(width_ratios=[1.45, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + times, secs = [], [] + for (dx, colour), (t, c, s) in zip(DXS, runs): + per = -(-100 // dx) # the deck is five 100 m conduits + a0.plot(t, c, color=style.COLORS[colour], lw=1.8, + label=f"TARGET_DX {dx} m ({per} cells per conduit, {5 * per} in all)") + times.append(_travel(t, c)) + secs.append(s) + a0.axhline(10.0, color=style.MUTED, lw=0.9, ls=(0, (4, 2))) + a0.set_xlim(2, 12) + a0.set_ylim(0, 11.4) + a0.set_xlabel("time (minutes)") + a0.set_ylabel("tracer at J5 (mg/L)") + a0.legend(fontsize=7.4, frameon=False, loc="lower right") + a0.set_title("(a) The same front at three cell sizes", fontsize=9, loc="left") + x = np.arange(len(DXS)) + a1.bar(x, secs, 0.5, color=[style.COLORS[c] for _, c in DXS]) + for i, s in enumerate(secs): + a1.text(i, s + max(secs) * 0.03, f"{s:.2f} s", ha="center", fontsize=7.6, color=style.INK) + a1.set_xticks(x) + a1.set_xticklabels([f"{dx} m" for dx, _ in DXS], fontsize=8) + a1.set_ylim(0, max(secs) * 1.25) + a1.set_xlabel("TARGET_DX") + a1.set_ylabel("run time (s)") + a1.set_title("(b) What the refinement costs", fontsize=9, loc="left") + fig.tight_layout() + return fig + + +def build(sink): + import style + engines = [_series(sink, dict(FINE, QUALITY_SOLVER=name), f"engine_{name.lower()}") + for name, _, _ in ENGINES] + for (name, _, _), (t, c, secs) in zip(ENGINES, engines): + print(f" {name}: {secs:.2f} s, half-rise at {_travel(t, c):.2f} min, plateau {c[-1]:.3f} mg/L") + dx_runs = [_series(sink, dict(FINE, QUALITY_SOLVER="EULERIAN_ARD"), f"dx_{dx}", + sidecars={"transport_demo.ard": ARD_TEMPLATE.format(dx=dx)}) + for dx, _ in DXS] + for (dx, _), (t, c, secs) in zip(DXS, dx_runs): + print(f" TARGET_DX {dx}: {secs:.2f} s, half-rise at {_travel(t, c):.2f} min") + if "workflow_ch8_tracer_breakthrough_three_engines" in sink.expected: + sink.save(_draw_engines(style, engines), "workflow_ch8_tracer_breakthrough_three_engines") + if "workflow_ch8_ard_dx_sensitivity" in sink.expected: + sink.save(_draw_dx(style, dx_runs), "workflow_ch8_ard_dx_sensitivity") diff --git a/docs/figures/src/workflows/ch9_msx_and_age_heat.py b/docs/figures/src/workflows/ch9_msx_and_age_heat.py new file mode 100644 index 000000000..870f711c5 --- /dev/null +++ b/docs/figures/src/workflows/ch9_msx_and_age_heat.py @@ -0,0 +1,174 @@ +"""Reactions, water age and heat on the transport demonstration deck +(Application Manual, the multi-species-reactions and age-and-heat +chapters). + +Three figures from the same five-conduit line: + +* what the computed water temperature does to the reaction system's rate, + through the Arrhenius correction its expression carries — the species + concentrations themselves are not written to the output file in this + release, because [REACTION_REPORT] is a planned section; +* water age along the line, against the source ages the component + declares; +* the water temperature against the air temperature driving it. + +Simulated tier: runs of docs/figures/decks/transport_demo, cached under +docs/figures/cache. +""" +from __future__ import annotations + +import numpy as np + +REQUIRES = ("openswmm",) + +DECK = "transport_demo/transport_demo.inp" +FINE = {"REPORT_STEP": "0:01:00"} +LINE = ["J1", "J2", "J3", "J4", "J5"] + + +def _read(sink, options, key, species, nodes=("J5",), sidecars=None): + from openswmm.engine import OutputReader, OutNodeVar + r = sink.run(DECK, options, key, sidecars=sidecars) + with OutputReader(r.out) as o: + base = int(OutNodeVar.POLLUT_BASE) + if species not in o.pollutant_ids: + raise RuntimeError(f"{species} is not reported by this run: {o.pollutant_ids}") + i = o.pollutant_ids.index(species) + n = o.period_count + out = {nd: np.asarray([o.node_attributes(nd, period=k)[base + i] for k in range(n)], float) + for nd in nodes} + return np.arange(n) / 60.0, out, r.seconds + + +def _draw_arrhenius(style, t_run, temp, kb=0.30, theta=1.07): + """The Arrhenius correction the .rxn expression carries, and where this run sits on it.""" + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 3.9)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + T = np.linspace(0.0, 30.0, 400) + mult = theta ** (T - 20.0) + a0.plot(T, mult, color=style.COLORS["fv"], lw=2.0) + a0b = a0.twinx() + a0b.plot(T, np.log(2.0) / (kb * mult) * 60.0, color=style.COLORS["fv-lts"], lw=1.6, ls=(0, (4, 2))) + a0b.set_ylabel("half-life of CL2 (minutes)", color=style.COLORS["fv-lts"], fontsize=8.5) + a0b.tick_params(labelsize=7.5, colors=style.COLORS["fv-lts"]) + for x, lab, col in ((12.0, "initial state, 12 °C", style.INK), + (18.0, "inflow, 18 °C", style.COLORS["dw"]), + (20.0, "the fallback, 20 °C", style.MUTED)): + a0.axvline(x, color=col, lw=0.9, ls=(0, (2, 2))) + a0.text(x, 1.62, lab, rotation=90, fontsize=7.0, color=col, ha="right", va="top") + a0.set_xlabel("water temperature TEMP (°C)") + a0.set_ylabel("rate multiplier θ^(TEMP − 20)", color=style.COLORS["fv"], fontsize=8.5) + a0.set_ylim(0, 1.75) + a0.set_title("(a) The correction the expression carries", fontsize=9, loc="left") + a0.text(0.4, 0.06, f"kb = 0.30 /hr and θ = 1.07, both from the .rxn file:\n" + f"the rate changes by {100 * (theta - 1):.0f} % per degree", + fontsize=7.4, color=style.MUTED, linespacing=1.45) + # where this run actually sits, over its first half hour + m = t_run <= 0.5 + cols = [style.COLORS["fv"], style.COLORS["dw"], style.COLORS["dw-slot"], style.COLORS["fv-lts"], + style.COLORS["dw-legacy"]] + for nd, c in zip(LINE, cols): + a1.plot(t_run[m] * 60, temp[nd][m], color=c, lw=1.6, label=nd) + a1.axhline(18.0, color=style.INK, lw=0.9, ls=(0, (1, 2))) + a1.set_xlabel("time (minutes)") + a1.set_ylabel("water temperature (°C)") + a1.set_title("(b) Where this run sits, over its first half hour", fontsize=9, loc="left") + a1.legend(fontsize=7.2, frameon=False, ncol=5, loc="lower right") + a1.text(0.97, 0.42, "The line fills from empty, so the first minutes are\n" + "a cold start: a nearly dry node carries a temperature\n" + "that is not a result. By ten minutes every node is at\n" + "the inflow temperature and the multiplier is 0.874.", + transform=a1.transAxes, fontsize=7.2, color=style.MUTED, va="center", ha="right", + linespacing=1.5) + fig.tight_layout() + return fig + + +def _draw_age(style, t, age): + import matplotlib.pyplot as plt + fig, (a0, a1) = plt.subplots(1, 2, figsize=(9.2, 3.8), gridspec_kw=dict(width_ratios=[1.3, 1.0])) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(a0) + style.style_ax(a1) + cols = [style.COLORS["fv"], style.COLORS["dw"], style.COLORS["dw-slot"], style.COLORS["fv-lts"], + style.COLORS["dw-legacy"]] + for nd, c in zip(LINE, cols): + a0.plot(t * 60.0, age[nd], color=c, lw=1.6, label=nd) + a0.axhline(0.5, color=style.MUTED, lw=0.9, ls=(0, (2, 2))) + a0.text(1.0, 0.508, "EXTERNAL_INFLOW 0.5 h — the age the arriving water is given", + fontsize=7.2, color=style.MUTED, va="bottom") + a0.set_xlim(0, 20) + a0.set_ylim(0, 0.68) + a0.set_xlabel("time (minutes)") + a0.set_ylabel("water age (hours)") + a0.legend(fontsize=7.4, frameon=False, ncol=5, loc="center right") + a0.set_title("(a) The line fills, and each node settles at its own age", fontsize=9, loc="left") + a0.text(1.0, 0.015, "INITIAL_STATE 6.0 h never appears: the pipes start empty, so there is\n" + "no standing water to carry it. A hot-started model would show it.", + fontsize=7.2, color=style.MUTED, linespacing=1.45) + # the steady profile at the end of the run + final = [age[nd][-1] for nd in LINE] + a1.plot(np.arange(len(LINE)) * 100.0, [f * 60 for f in final], marker="o", ms=5, + color=style.COLORS["fv"], lw=1.8) + a1.set_xlabel("distance from the inflow (m)") + a1.set_ylabel("water age at the end of the run (minutes)") + a1.set_title("(b) What is left is the travel time", fontsize=9, loc="left") + a1.text(0.04, 0.93, f"{final[0] * 60:.1f} min at J1, the declared source age,\n" + f"rising to {final[-1] * 60:.1f} min at J5", transform=a1.transAxes, fontsize=7.4, + color=style.MUTED, va="top", linespacing=1.45) + fig.tight_layout() + return fig + + +def _draw_heat(style, t, temp, air_t, air_c): + """The first hour, where everything happens, with the six-hour behaviour stated.""" + import matplotlib.pyplot as plt + fig, ax = plt.subplots(figsize=(8.8, 4.1)) + fig.patch.set_facecolor(style.SURFACE) + style.style_ax(ax) + tm = t * 60.0 + m = tm <= 60.0 + air_min = np.linspace(0, 60, 61) + ax.plot(air_min, np.interp(air_min / 60.0, air_t, air_c), color=style.MUTED, lw=1.5, ls=(0, (5, 2)), + label="air temperature, from the [TEMPERATURE] series") + cols = [style.COLORS["fv"], style.COLORS["dw"], style.COLORS["dw-slot"], style.COLORS["fv-lts"], + style.COLORS["dw-legacy"]] + for nd, c in zip(LINE, cols): + ax.plot(tm[m], temp[nd][m], color=c, lw=1.6, label=f"water at {nd}") + ax.axhline(18.0, color=style.INK, lw=0.9, ls=(0, (1, 2))) + ax.text(59.5, 18.25, "inflow temperature, 18 °C", fontsize=7.2, color=style.INK, ha="right") + ax.axhline(12.0, color=style.INK, lw=0.7, ls=(0, (1, 3))) + ax.text(59.5, 11.3, "initial state, 12 °C", fontsize=7.2, color=style.INK, ha="right") + ax.set_xlim(0, 60) + ax.set_xlabel("time (minutes)") + ax.set_ylabel("temperature (°C)") + ax.legend(fontsize=7.2, frameon=False, ncol=2, loc="lower right") + ax.set_title("Water temperature along the line, with surface and radiative exchange on", + fontsize=9.5, loc="left") + last = max(float(temp[nd][-1]) for nd in LINE) + ax.text(30.0, 6.2, "Everything happens in the first ten minutes: the line fills and each node\n" + f"reaches the inflow temperature. For the remaining five hours the water stays at\n" + f"{last:.2f} °C while the air rises to {air_c[-1]:.0f} °C — a 35-minute residence in 500 m of\n" + "pipe is far too short for the surface to move it. Heat here is transport, not exchange.", + fontsize=7.4, color=style.MUTED, linespacing=1.5, ha="center") + fig.tight_layout() + return fig + + +def build(sink): + import style + t_tmp, temp, _ = _read(sink, dict(FINE), "heat_on", "__TEMPERATURE__", tuple(LINE)) + print(" water temperature at the end (degC): " + ", ".join(f"{nd} {temp[nd][-1]:.2f}" for nd in LINE)) + t_age, age, _ = _read(sink, dict(FINE), "heat_on", "__WATER_AGE__", tuple(LINE)) + print(" water age at the end (min): " + ", ".join(f"{nd} {age[nd][-1] * 60:.1f}" for nd in LINE)) + air_t = np.array([0.0, 3.0, 6.0]) + air_c = np.array([12.0, 20.0, 22.0]) + if "workflow_ch9_arrhenius_rate_from_temperature" in sink.expected: + sink.save(_draw_arrhenius(style, t_tmp, temp), "workflow_ch9_arrhenius_rate_from_temperature") + if "workflow_ch10_water_age_along_line" in sink.expected: + sink.save(_draw_age(style, t_age, age), "workflow_ch10_water_age_along_line") + if "workflow_ch10_heat_diurnal" in sink.expected: + sink.save(_draw_heat(style, t_tmp, temp, air_t, air_c), "workflow_ch10_heat_diurnal") diff --git a/docs/figures/status.py b/docs/figures/status.py new file mode 100644 index 000000000..33ad496d2 --- /dev/null +++ b/docs/figures/status.py @@ -0,0 +1,173 @@ +"""Single source of truth for the status of every formulation the manuals name. + +Consumed by three things that must never disagree: + +* the figure generators under docs/figures/src/ — every alternative drawn on + the conceptual map or a process diagram carries a chip coloured from STATUS; +* scripts/lint_manual_docs.py check_status_badges() — the only words a + \\status{...} alias may carry are the labels below, and the CSS that styles + them must carry the same hex values; +* the "Planned formulations" chapters and the ROADMAP refresh, which are + written against FEATURES rather than from memory. + +Vocabulary (defined once in the Engine Manual, Chapter 1): + + Implemented shipped, selectable, exercised by gates or parity suites + Experimental shipped and selectable, default-off, with a validation caveat + recorded in source or in plans/ + Planned design recorded in plans/ or ROADMAP.md, no kernel — includes + sections that parse but are inert at run time + Retired parsed for compatibility, warned or ignored, no effect + +Stdlib only: the lint imports this file from a checkout that has no matplotlib. +""" + +STATUS = { + # key (label, hex) — hex values are the benchmarks + # translib categorical palette + "implemented": ("Implemented", "#1baf7a"), + "experimental": ("Experimental", "#eda100"), + "planned": ("Planned", "#898781"), + "retired": ("Retired", "#e87ba4"), +} + +# feature id -> status key. Ids are dotted, lower case, grouped by process. +# Sources for each ruling are cited in plans/DOCUMENTATION_FORMULATIONS_PLAN_2026-09-19.md. +FEATURES = { + # land surface + "runoff.subcatchment": "implemented", + "runoff.mesh_2d": "implemented", + "infiltration.horton": "implemented", + "infiltration.mod_horton": "implemented", + "infiltration.green_ampt": "implemented", + "infiltration.mod_green_ampt": "implemented", + "infiltration.curve_number": "implemented", + "infiltration.mesh_per_cell": "implemented", + "infiltration.mesh_constant": "implemented", + "snowmelt.degree_day": "implemented", + "rain.mesh_natural_neighbour": "implemented", + "evaporation.mesh": "implemented", + "lid.layered": "implemented", + "lid.storage_node": "planned", + "lid.detailed_output": "planned", + "quality.buildup_washoff": "implemented", + "quality.mesh_surface": "implemented", + "climate.humidity_dewpoint": "implemented", + "climate.precip_scaling": "implemented", + "climate.pet_forcing": "implemented", + "rdii.rtk": "implemented", + "rdii.ia_decay": "implemented", + # subsurface + "groundwater.two_zone": "implemented", + "groundwater.mesh_two_layer": "implemented", + "groundwater.mesh_per_subcatch": "implemented", + "groundwater.soil.gardner": "implemented", + "groundwater.soil.russo": "experimental", + "groundwater.soil.brooks_corey": "experimental", + "groundwater.soil.van_genuchten": "experimental", + "groundwater.transport": "planned", # [GW_*] sections authored but inert + # conveyance, 1D + "routing.steady": "implemented", + "routing.kinwave": "implemented", + "routing.dynwave": "implemented", + "routing.fv": "implemented", + "routing.node_continuity.explicit": "implemented", + "routing.node_continuity.semi_implicit": "implemented", + "routing.anderson": "implemented", + "pressurisation.extran": "implemented", + "pressurisation.slot": "implemented", + "pressurisation.dynamic_slot": "implemented", + "pressurisation.tpa": "experimental", + "fv.closure.slot": "implemented", + "fv.closure.tpa": "experimental", + "fv.pressurized_implicit": "experimental", + "fv.lts": "implemented", + "fv.node_coupling_keys": "retired", # FV_NODE_COUPLING, FV_NODE_DT, ... + "fv.implicit_hypre": "planned", + "friction.unsteady_vitkovsky": "implemented", + "backend.1d.cpu": "implemented", + "backend.1d.gpu": "planned", # loader hooks only, no plugin + "junctions.virtual": "implemented", + "junctions.virtual_momentum_full": "retired", + "junctions.inlet": "implemented", + "inlets.link_attribute": "implemented", + "xsect.tabulated": "implemented", + "xsect.street": "implemented", + "xsect.dummy": "implemented", + "xsect.chebyshev_irregular": "planned", + "storage.shapes": "implemented", + "fv.bed_step_junction_faces": "planned", + # the divergence this fix was recorded against was removed on 2026-09-12 by the + # slot/free-surface wave-speed bound; the hybrid flux is no longer required for it + "fv.tpa_high_celerity_fix": "retired", + # conveyance, 2D + "overland2d.local_inertial": "implemented", + "overland2d.full_swe": "implemented", + "overland2d.diffusive_wave": "implemented", + "overland2d.integrator.explicit": "implemented", + "overland2d.integrator.cvode": "retired", + "overland2d.imex": "retired", + "overland2d.advection_key": "retired", + "overland2d.cell_closure.flat": "implemented", + "overland2d.cell_closure.vfr": "implemented", + "overland2d.mesh.triangles": "implemented", + "overland2d.mesh.quads": "implemented", + "coupling.1d2d.vertex": "implemented", + "coupling.1d2d.cell": "implemented", + "backend.2d.cpu": "implemented", + "backend.2d.omp": "implemented", + "backend.2d.cuda": "implemented", + "backend.2d.hip": "implemented", + "backend.2d.sycl": "implemented", + "backend.2d.metal": "planned", + # transport and quality + "transport.cstr": "implemented", + "transport.ard": "implemented", + "transport.lard": "implemented", + "transport.rwpt": "implemented", + "transport.mesh_2d": "implemented", + "transport.fv_mesh_pollutants": "planned", # FV_DISPERSION path not wired to [POLLUTANTS] + "reactions.first_order": "implemented", + "reactions.msx": "implemented", + "reactions.bw_msx": "implemented", + "water_age": "implemented", + "heat": "implemented", + "heat.per_element_attributes": "planned", + "sediment": "planned", + "outfall.backflow_quality": "implemented", +} + + +def label(feature_id): + return STATUS[FEATURES[feature_id]][0] + + +def colour(feature_id): + return STATUS[FEATURES[feature_id]][1] + + +def labels(): + """The four words a \\status{} badge may carry.""" + return {lab for lab, _ in STATUS.values()} + + +def self_check(): + """Every feature maps to a known status; every status has a distinct label and hex.""" + errors = [] + for fid, key in FEATURES.items(): + if key not in STATUS: + errors.append(f"status.py: feature {fid!r} has unknown status {key!r}") + labs = [lab for lab, _ in STATUS.values()] + hexes = [h for _, h in STATUS.values()] + if len(set(labs)) != len(labs) or len(set(hexes)) != len(hexes): + errors.append("status.py: STATUS labels/colours are not distinct") + return errors + + +if __name__ == "__main__": + import sys + errs = self_check() + for e in errs: + print("ERROR", e) + print(f"{len(FEATURES)} features, {len(STATUS)} statuses, {len(errs)} errors") + sys.exit(1 if errs else 0) diff --git a/docs/figures/style.py b/docs/figures/style.py new file mode 100644 index 000000000..4fa4b0ed5 --- /dev/null +++ b/docs/figures/style.py @@ -0,0 +1,93 @@ +"""House style for every generated manual figure. + +Vendored 2026-09-19 from two validated sources so the manuals, the benchmark +reports and the SWMM paper share one visual language: + +* openswmm.engine.benchmarks/suites/analytical/transitions/translib/report.py + (COLORS, INK/MUTED/GRIDC/SURFACE/SOIL/PIPE_FILL, _style) +* epaswmm5_qa/article/scripts/_style.py (DPI 160, save()) + +The categorical solver palette is a fixed identity: a solver keeps its colour +in every figure and is never re-ranked. Status chips take their colours from +docs/figures/status.py, not from here. + +Only generators import this module; the manifest audit (check) stays stdlib. +""" +from __future__ import annotations + +import matplotlib + +matplotlib.use("Agg") + +import matplotlib.pyplot as plt # noqa: E402 + +# categorical solver identity (never re-ranked) +COLORS = { + "fv": "#2a78d6", + "fv-lts": "#eb6834", + "dw": "#1baf7a", + "dw-slot": "#eda100", + "dw-legacy": "#e87ba4", +} +LABELS = { + "fv": "Finite volume", + "fv-lts": "Finite volume + LTS", + "dw": "Dynamic wave", + "dw-slot": "Dynamic wave, slot", + "dw-legacy": "Legacy SWMM 5", +} +ORDER = ["fv", "fv-lts", "dw", "dw-slot", "dw-legacy"] # legend order +ZBOT = list(reversed(ORDER)) # draw fv last (top) + +# chrome +INK, MUTED, GRIDC = "#0b0b0b", "#898781", "#e1e0d9" +SURFACE, SOIL, PIPE_FILL = "#fcfcfb", "#e2d7bd", "#efede6" +WATER = "#2a78d6" + +DPI = 160 # article export; width <= 10 in keeps PNGs under 1600 px +MAX_WIDTH_IN = 10.0 + + +def style_ax(ax): + """Spines, grid and tick colours of the house style.""" + ax.set_facecolor(SURFACE) + for side in ("top", "right"): + ax.spines[side].set_visible(False) + for side in ("left", "bottom"): + ax.spines[side].set_color(GRIDC) + ax.tick_params(colors=MUTED, labelsize=9) + ax.xaxis.label.set_color(MUTED) + ax.yaxis.label.set_color(MUTED) + ax.title.set_color(INK) + ax.grid(True, color=GRIDC, linewidth=0.6, alpha=0.7) + ax.set_axisbelow(True) + + +def schematic_ax(ax): + """A diagram axis: no ticks, no spines, equal aspect.""" + ax.set_facecolor(SURFACE) + ax.set_aspect("equal") + ax.axis("off") + + +def figure(width_in=8.0, height_in=4.5, **kw): + """A figure whose width respects the 1600 px embed bound at DPI.""" + width_in = min(width_in, MAX_WIDTH_IN) + fig = plt.figure(figsize=(width_in, height_in), **kw) + fig.patch.set_facecolor(SURFACE) + return fig + + +def apply_rc(): + """Deterministic text and export settings; called once by the build script.""" + plt.rcParams.update({ + "font.family": "DejaVu Sans", # bundled with matplotlib + "font.size": 9, + "axes.titlesize": 10, + "axes.labelsize": 9, + "legend.fontsize": 8, + "legend.frameon": False, + "savefig.facecolor": SURFACE, + "svg.fonttype": "none", # text stays text in the SVG twin + "path.simplify": True, + }) diff --git a/docs/figures/svg/.gitkeep b/docs/figures/svg/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/figures/svg/eng_conceptual_map.svg b/docs/figures/svg/eng_conceptual_map.svg new file mode 100644 index 000000000..831f9bfd8 --- /dev/null +++ b/docs/figures/svg/eng_conceptual_map.svg @@ -0,0 +1,2520 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ATMOSPHERE + + + LAND SURFACE · subcatchments (lumped) + + + LAND SURFACE · 2D mesh (distributed) + + + SUBSURFACE · two-zone aquifer per subcatchment + + + SUBSURFACE · two-layer aquifer on the mesh + + + CONVEYANCE · 1D node–link network + + + OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage + + + + + + precipitation · snowmelt + + + + + + evaporation · ET + + + + + + rain on cells + + + + + + evaporation on cells + + + + + + infiltration + + + + + + per-cell infiltration + + + + + + Dunne return flow · capillary rise + + + + + + GW interflow (user [GWF]) + + + + + + node–bed exchange + + + + + + runoff → outlet node + + + + + + 1D ↔ 2D exchange at vertices / cells + + + + + + street inlet capture + + + + + + runoff → cell + + + OpenSWMM: compartments, processes and the formulations that represent them + + + Status of each alternative: + + + arrows: water (blue) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + + + + Climate + + + + + + + + + + + + + + + + + + Snowmelt + + + + + + Runoff + + + + + + + + + + + + Infiltration + + + + + + + + + + + + + + + + + + LID controls + + + + + + + + + + + + Surface quality + + + + + + + + + + + + Rain on the mesh + + + + + + + + + Per-cell infiltration + + + + + + + + + Overland flow + + + + + + + + + + + + + + + Mesh and closure + + + + + + + + + + + + + + + Surface quality · transport + + + + + + + + + Backends + + + + + + + + + + + + + + + Two-zone aquifer + + + + + + + + + + + + Groundwater transport + + + + + + Two-layer aquifer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nodes + + + + + + + + + + + + Links + + + + + + + + + + + + + + + + + + + + + Flow routing + + + + + + + + + + + + + + + + + + + + + Pressurisation + + + + + + + + + + + + + + + + + + + + + + + + + + + Node solution + + + + + + + + + + + + + + + Transport + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inflows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + rain gages + + + rain · snow split (SCF) + + + scale factors + + + temperature + + + evaporation: constant · monthly · series · Hargreaves · file + + + wind + + + humidity · dew point + + + prescribed PET (API) + + + degree-day · heat budget · areal depletion + + + nonlinear reservoir + + + depression storage + + + routing to another subcatchment + + + Horton + + + modified Horton + + + Green-Ampt + + + modified Green-Ampt + + + curve number + + + layered units (8 types) + + + LID as storage nodes + + + detailed output + + + buildup · washoff by land use + + + street sweeping + + + MSX species + + + natural neighbour + + + system + + + Horton · Green-Ampt · CN · constant + + + → lost · subcatchment aquifer · mesh aquifer + + + local inertial + + + full shallow water + + + diffusive wave + + + IMEX / CVODE + + + triangles + + + quads + + + flat cells + + + VFR closure + + + coverages · buildup · washoff + + + species on the mesh + + + CPU + + + OpenMP + + + CUDA · HIP · SYCL + + + Metal + + + unsaturated + saturated zone + + + percolation · deep percolation · ET + + + lateral interflow, user [GWF] + + + advection–dispersion · heat + + + Gardner + + + Russo + + + Brooks–Corey + + + van Genuchten + + + closed form · enslaved · σ column + + + Dunne return flow + + + node–bed exchange + + + capillary rise · boundary ET + + + per-subcatchment mode + + + junction · storage · divider · outfall + + + virtual junction + + + inlet junction + + + conduits, 26 sections + + + street · dummy + + + Chebyshev irregular + + + pumps · orifices · weirs · outlets · culverts + + + storage shapes + + + HEC-22 inlets + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + local time stepping + + + 1D GPU backend + + + EXTRAN + + + slot + + + dynamic slot + + + TPA + + + FV: slot + + + FV: TPA + + + FV: implicit head + + + unsteady friction + + + explicit continuity + + + semi-implicit continuity + + + Anderson acceleration + + + FV_NODE_* keys + + + CSTR + + + Eulerian ARD + + + Lagrangian LARD + + + random-walk dispersion + + + first-order decay + + + MSX reactions + + + water age + + + heat + + + sediment + + + treatment functions + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + control rules + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/eng_lid_bioretention_layers.svg b/docs/figures/svg/eng_lid_bioretention_layers.svg new file mode 100644 index 000000000..4bc3c594c --- /dev/null +++ b/docs/figures/svg/eng_lid_bioretention_layers.svg @@ -0,0 +1,813 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Soil + + + Storage (gravel) + + + + + + + + + + + + Underdrain + + + Native soil + + + + + + + + + + rainfall + + + + + + + + + + run-on from the drainage area + + + + + + + + + + evaporation + + + + + + + + + + surface outflow + + + + + + + + + + infiltration into the soil + + + + + + + + + + percolation + + + + + + + + + + infiltration into native soil (unless lined) + + + + + + + + + + underdrain outflow + + + Bio-retention cell: the layers of the moisture balance and its fluxes + + + + + + + + + diff --git a/docs/figures/svg/eng_object_sketch.svg b/docs/figures/svg/eng_object_sketch.svg new file mode 100644 index 000000000..85d2e74f8 --- /dev/null +++ b/docs/figures/svg/eng_object_sketch.svg @@ -0,0 +1,682 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Objects of an OpenSWMM model + + + hydrology: rain gages and subcatchments, with aquifers and snow packs beneath them · hydraulics: nodes, links and a 2D mesh · quality: pollutants and land uses on the subcatchments + + + Subcatchment S1 + + + Subcatchment S2 + + + Rain gage + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Junction + + + Conduit + + + Virtual junction + + + Inlet junction on a street + + + Street conduit + + + Divider + + + Weir + + + Orifice + + + Storage unit + + + Pump + + + Outfall + + + 2D mesh (triangles · quads) coupled to junction J3 + + + 1D ↔ 2D exchange + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/eng_process_flow.svg b/docs/figures/svg/eng_process_flow.svg new file mode 100644 index 000000000..d890ab2fd --- /dev/null +++ b/docs/figures/svg/eng_process_flow.svg @@ -0,0 +1,1328 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LUMPED: SUBCATCHMENTS + + + SUBSURFACE + + + DISTRIBUTED: 2D MESH + + + INFLOWS · INLETS + + + + + + interflow · node–bed exchange + + + + + + species on the mesh + + + + + + inflows + + + + + + inlet capture + + + + + + 1D ↔ 2D exchange + + + Status of each alternative: + + + arrows: water (blue) · constituent mass (violet) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + Snowmelt + + + + + + Initial abstraction · evaporation + + + + + + Surface runoff + + + + + + + + + LID controls + + + + + + + + + Washoff + + + + + + Groundwater + + + + + + + + + + + + Pollutant buildup + + + + + + Rain on the mesh + + + + + + 2D overland flow + + + + + + + + + + + + Per-cell infiltration · evaporation + + + + + + 2D surface quality + + + + + + External inflows + + + + + + + + + + + + + + + Street inlets + + + + + + + + + Channel, pipe and storage routing + + + + + + + + + + + + + + + + + + + + + + + + Transport and reactions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + OUTFALLS · receiving water + + + + + + + + + + + + + + + rain · snow + + + scale factors + + + degree-day · areal depletion + + + depression storage + + + nonlinear reservoir + + + Horton · Green-Ampt · CN + + + layered units + + + storage nodes + + + EMC · exponential · rating + + + two-zone aquifer per subcatchment + + + two-layer aquifer on the mesh + + + groundwater transport + + + land uses · sweeping + + + natural neighbour + + + local inertial + + + full shallow water + + + diffusive wave + + + → lost · subcatchment · mesh aquifer + + + coverages · buildup · washoff + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + HEC-22 link attribute + + + inlet junction + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + EXTRAN · slot · dynamic slot + + + TPA + + + virtual · inlet junctions + + + CSTR + + + ARD + + + LARD + + + first-order decay + + + MSX + + + water age + + + heat + + + sediment + + + treatment · diversion + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + diff --git a/docs/figures/svg/eng_rdii_unit_hydrograph.svg b/docs/figures/svg/eng_rdii_unit_hydrograph.svg new file mode 100644 index 000000000..f5561419d --- /dev/null +++ b/docs/figures/svg/eng_rdii_unit_hydrograph.svg @@ -0,0 +1,1024 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + time since the unit of rainfall (h) + + + + + RDII flow per unit rainfall + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + T (time to peak) + + + + + + + + K · T (recession) + + + area = R + (fraction of rainfall + becoming RDII) + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch3_virtual_junction.svg b/docs/figures/svg/hydraulics_ch3_virtual_junction.svg new file mode 100644 index 000000000..8722fe05c --- /dev/null +++ b/docs/figures/svg/hydraulics_ch3_virtual_junction.svg @@ -0,0 +1,286 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + manhole: MIN_SURFAREA storage, + its own head update every trial + + + + + + + stagnation volume + below the outlet invert + + + conduit 1 + + + conduit 2 + + + Regular junction at the grade break + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + virtual junction: zero storage, + continuous invert, no head unknown + + + one surveyed reach + + + the solver sees one conduit; + the file keeps two + + + Virtual junction at the grade break + + + + + + + + + + + + + + + + + + + momentum flux carried through + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_circular_theta.svg b/docs/figures/svg/hydraulics_ch5_circular_theta.svg new file mode 100644 index 000000000..14b2506f5 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_circular_theta.svg @@ -0,0 +1,910 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + θ + + + + + + + + y + + + + + + + + D + + + A = (θ − sin θ) D² / 8, P = θ D / 2, T = D sin(θ/2) + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_power_law.svg b/docs/figures/svg/hydraulics_ch5_power_law.svg new file mode 100644 index 000000000..f6011fb10 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_power_law.svg @@ -0,0 +1,2307 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + b + + + + + + + + Y_full + + + 1/γ = 0.5 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + b + + + + + + + + Y_full + + + 1/γ = 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + b + + + + + + + + Y_full + + + 1/γ = 2 (parabola) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + b + + + + + + + + Y_full + + + 1/γ = 4 + + + + Power-law cross section y = α x^(1/γ): the same full depth and top width, four exponents + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_shapes_composite.svg b/docs/figures/svg/hydraulics_ch5_shapes_composite.svg new file mode 100644 index 000000000..f9df61a37 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_shapes_composite.svg @@ -0,0 +1,2527 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Rectangular-triangular + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Rectangular-round + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Modified basket-handle + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Filled circular + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + Composite sections: rectangular, triangular and circular parts + + + outlines from the engine's width(depth); inset: area fraction versus depth fraction; shaded: water at 40 % of full depth + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_shapes_elliptical_arch.svg b/docs/figures/svg/hydraulics_ch5_shapes_elliptical_arch.svg new file mode 100644 index 000000000..f39ffeead --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_shapes_elliptical_arch.svg @@ -0,0 +1,1998 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Horizontal ellipse + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Vertical ellipse + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Arch + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + Elliptical and arch pipe sections + + + outlines from the engine's width(depth); inset: area fraction versus depth fraction; shaded: water at 40 % of full depth + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_shapes_masonry.svg b/docs/figures/svg/hydraulics_ch5_shapes_masonry.svg new file mode 100644 index 000000000..addd4ec69 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_shapes_masonry.svg @@ -0,0 +1,4494 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Egg-shaped + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Horseshoe + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Gothic + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Catenary + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Semi-elliptical + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Basket-handle + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Semi-circular + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + A/A_full + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + y/Y_full + + + + + + + + + + + + + + + + Older masonry sewer sections + + + outlines from the engine's width(depth); inset: area fraction versus depth fraction; shaded: water at 40 % of full depth + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_storage_cone.svg b/docs/figures/svg/hydraulics_ch5_storage_cone.svg new file mode 100644 index 000000000..62319850a --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_storage_cone.svg @@ -0,0 +1,18615 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Elliptical cone + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_storage_cylinder.svg b/docs/figures/svg/hydraulics_ch5_storage_cylinder.svg new file mode 100644 index 000000000..fb27fe3db --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_storage_cylinder.svg @@ -0,0 +1,18615 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Elliptical cylinder + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_storage_paraboloid.svg b/docs/figures/svg/hydraulics_ch5_storage_paraboloid.svg new file mode 100644 index 000000000..f1db0834f --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_storage_paraboloid.svg @@ -0,0 +1,18615 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Elliptical paraboloid + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_storage_pyramid.svg b/docs/figures/svg/hydraulics_ch5_storage_pyramid.svg new file mode 100644 index 000000000..4f3b247a9 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_storage_pyramid.svg @@ -0,0 +1,37495 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Rectangular pyramid + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch5_street_section.svg b/docs/figures/svg/hydraulics_ch5_street_section.svg new file mode 100644 index 000000000..063f88fd1 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch5_street_section.svg @@ -0,0 +1,181 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + crown + + + + + + + + curb height + + + + + + + + gutter width + + + + + + + + gutter depression (exaggerated) + + + + + + + + road width (curb to crown) + + + cross slope S_x + + + + + + + + backing width, slope + + + one-sided street, not to scale: a two-sided street repeats the section mirror-wise about the crown + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch6_pump_type1.svg b/docs/figures/svg/hydraulics_ch6_pump_type1.svg new file mode 100644 index 000000000..c3b68a38e --- /dev/null +++ b/docs/figures/svg/hydraulics_ch6_pump_type1.svg @@ -0,0 +1,109 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + inlet node volume + + + + + pump flow + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Type 1: flow versus inlet volume + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch6_pump_type2.svg b/docs/figures/svg/hydraulics_ch6_pump_type2.svg new file mode 100644 index 000000000..1f8d56a76 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch6_pump_type2.svg @@ -0,0 +1,109 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + inlet node depth + + + + + pump flow + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Type 2: flow versus inlet depth + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch6_pump_type3.svg b/docs/figures/svg/hydraulics_ch6_pump_type3.svg new file mode 100644 index 000000000..67606f6e7 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch6_pump_type3.svg @@ -0,0 +1,193 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + pump flow + + + + + head difference + + + + + + + + + + + + + + + + + + + + + + + + + Type 3: head versus flow + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch6_pump_type4.svg b/docs/figures/svg/hydraulics_ch6_pump_type4.svg new file mode 100644 index 000000000..4761882b2 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch6_pump_type4.svg @@ -0,0 +1,193 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + inlet node depth + + + + + pump flow + + + + + + + + + + + + + + + + + + + + + + + + + Type 4: flow versus inlet depth + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch6_pump_type5.svg b/docs/figures/svg/hydraulics_ch6_pump_type5.svg new file mode 100644 index 000000000..bed7633b9 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch6_pump_type5.svg @@ -0,0 +1,402 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + pump flow + + + + + head difference + + + + + + + + + + + + + + + + + + + Type 5: head versus flow, by speed + + + + + + + speed 1 + + + + + + speed 0.8 + + + + + + speed 0.6 + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch7_street_spread.svg b/docs/figures/svg/hydraulics_ch7_street_spread.svg new file mode 100644 index 000000000..111409b98 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch7_street_spread.svg @@ -0,0 +1,572 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + crown + + + + + + + + spread T + + + + + + + + depth at curb d + + + gutter flow Q_w + + + roadway (side) flow Q_s + + + HEC-22: E_0 = Q_w / Q is the fraction of the flow in the gutter; capture depends on d, T and E_0 + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_cell_layout.svg b/docs/figures/svg/hydraulics_ch8_cell_layout.svg new file mode 100644 index 000000000..e4017f4b8 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_cell_layout.svg @@ -0,0 +1,2016 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + depth is known only here + + + + + + + one momentum balance + for the whole pipe + + + Node–link dynamic wave: one flow per pipe, one depth per manhole + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + 20 + + + + + + + + + + 40 + + + + + + + + + + 60 + + + + + + + + + + 80 + + + + + + + + + + 100 + + + + distance along the conduit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + hydraulic jump captured + where it happens + + + + + + + flux out of one cell = + flux into the next (exactly) + + + Finite volume: the pipe itself is discretised — profiles, bores and jumps live inside it + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_hll_fan.svg b/docs/figures/svg/hydraulics_ch8_hll_fan.svg new file mode 100644 index 000000000..5fd1a9b63 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_hll_fan.svg @@ -0,0 +1,305 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + S* = v + (species only) + + + U_L + + + U_HLL + + + U_R + + + S_L + + + S_R + + + face + + + + + + + t + + + + + + + x + + + (a) Wet–wet face: HLL averages the fan; + S* serves only the species flux + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + U_L + + + rarefaction + fan + + + dry + + + S_L + + + S_R + + + face + + + + + + + t + + + + + + + x + + + (b) Dry-bed face: the rarefaction tail + bounds the front + + + + Davis estimates: S_L = min(v_L − c_L, v_R − c_R), S_R = max(v_L + c_L, v_R + c_R), c = √(g A / T) + + + Dry right cell: S_L = v_L − c_L, S_R = v_L + 2 c_L (mirror-wise for a dry left cell: v_R − 2 c_R, v_R + c_R) + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_hydrostatic_reconstruction.svg b/docs/figures/svg/hydraulics_ch8_hydrostatic_reconstruction.svg new file mode 100644 index 000000000..d12ba419f --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_hydrostatic_reconstruction.svg @@ -0,0 +1,259 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z* = max(z_L, z_R) + + + η_L + + + z_L + + + z_R + + + + + + + + h*_L = η_L − z* + + + front advances onto the dry cell + + + h*_R = 0 (dry) + + + cell L + + + cell R + + + Wetting front: η_L above z* + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z* = max(z_L, z_R) + + + η_L + + + z_L + + + z_R + + + h*_L = h*_R = 0 + zero flux: the bank is a wall + + + dry + + + cell L + + + cell R + + + Emerged bank: η_L below z* + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_lts_ladder.svg b/docs/figures/svg/hydraulics_ch8_lts_ladder.svg new file mode 100644 index 000000000..cea70386d --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_lts_ladder.svg @@ -0,0 +1,408 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + tier 0 + Δt = Δt_0 + + + tier 1 + Δt = 2 Δt_0 + + + tier 2 + Δt = 4 Δt_0 + + + tier 3 + Δt = 8 Δt_0 + + + one macro cycle = one step of the coarsest tier = 2^3 Δt_0 for 4 tiers + + + + + + + + a face between tier 1 and tier 2 + fires at the finer cadence and + books ±F Δt into both accumulators + + + a volume drains its accumulator + when its own window closes: + exact conservation across tiers + + + macro-cycle close: re-tiering allowed + + + t + + + Tiers are graded: no face joins volumes more than one tier apart; FV_LTS_MAX_TIERS caps the spread + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_node_ghost_state.svg b/docs/figures/svg/hydraulics_ch8_node_ghost_state.svg new file mode 100644 index 000000000..f61194017 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_node_ghost_state.svg @@ -0,0 +1,212 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + node head H + + + manhole + + + end cell + + + interior cells → + + + + + + coupling face + + + z_f: invert + offset + + + + + + + + h_g = H − z_f + + + v_int (end cell) + + + ghost: A(h_g), v_g = v_int + + + the node is a reservoir at head H: the face flux is the Riemann solution between the ghost and the end cell + + + Ghost state at a node coupling face + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch8_slot_closure.svg b/docs/figures/svg/hydraulics_ch8_slot_closure.svg new file mode 100644 index 000000000..c437ef683 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch8_slot_closure.svg @@ -0,0 +1,1719 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + top width T (ft) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.2 + + + + depth h / y_full + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + y_full (crown) + + + y_c = 0.985 y_full + + + (a) Tapered slot mouth: T(h) for a 3 ft circular pipe + + + + + + + + + + + + + + + + + 0.00 + + + + + + + + + + 0.05 + + + + + + + + + + 0.10 + + + + + + + + + + 0.15 + + + + + + + + + + + + + + + 0.975 + + + + + + + + + + 1.000 + + + + + + + + + + 1.025 + + + + + + + + + + 1.050 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the mouth, zoomed + + + + + + + + c_slot = 30 ft/s (below the cap 39 ft/s: inert) + + + + + + c_slot = 50 ft/s + + + + + + c_slot = 100 ft/s + + + + + + c_slot = 200 ft/s + + + + + + section alone (no slot) + + + + + + + + + + + + + + + + + + + + + + 1 + 0 + 1 + + + + + + + + + + + + + + + + + + 1 + 0 + 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + celerity c = √(g A / T) (ft/s) + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + T_slot = g A_full / c_slot² + capped at 0.05 W_max + dashed: the section alone, + no slot + + + (b) Celerity rises smoothly to c_slot instead of diverging at the crown + + + + + + + + + + + + + + + + + + + + 1 + 0 + 1 + + + + + + + + + + + + + + + 1 + 0 + 2 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.96 + + + + + + + + + + 0.98 + + + + + + + + + + 1.00 + + + + + + + + + + 1.02 + + + + + + + + + + 1.04 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the crown, zoomed + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch9_active_set.svg b/docs/figures/svg/hydraulics_ch9_active_set.svg new file mode 100644 index 000000000..5517ca35b --- /dev/null +++ b/docs/figures/svg/hydraulics_ch9_active_set.svg @@ -0,0 +1,2208 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the front advances + + + + + + + breach — rebuild now + + + (a) The active set and its halo, in plan + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + flux-active (h > H_MOVE) + + + one-ring halo — the default cadence + + + rings 2–5 — kept under FRONT_REBUILD + + + the marked frontier ring + + + a breach: this cell crossed h_on + + + dry, integrated lazily + + + A face flows only when both of its cells are active. + + + A one-sided face exports volume into a cell whose update + never runs — measured as an 18 % basin loss when it was allowed. + + + (b) What the colours mean + + + + + + + + + + + + + + + + + H_MOVE + + + + + + + + + + + + + + + + + + + + + + + + + + + δ = min(1 mm, H_MOVE / 2): the band scales with the threshold + + + + + + + entering: h_move + δ + + + + + + leaving: h_move − δ + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch9_coupling_modes.svg b/docs/figures/svg/hydraulics_ch9_coupling_modes.svg new file mode 100644 index 000000000..bb05151f4 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch9_coupling_modes.svg @@ -0,0 +1,254 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + COUPLING_IN_FLOODING NO (default) + + + the spill is its own row; Flooding Loss holds only water lost from the model + + + Flow Routing Continuity + + + Volume (10⁶ gal) + + + Dry Weather Inflow + + + 0.000 + + + Wet Weather Inflow + + + 12.480 + + + Groundwater Inflow + + + 0.000 + + + RDII Inflow + + + 0.000 + + + External Inflow + + + 0.000 + + + External Outflow + + + 9.120 + + + Flooding Loss + + + 0.000 + + + 2D Coupling Outflow + + + 3.210 + + + Evaporation Loss + + + 0.040 + + + Initial Stored Volume + + + 0.310 + + + Final Stored Volume + + + 0.418 + + + Continuity Error (%) + + + -0.002 + + + + + + + + + + + + + + COUPLING_IN_FLOODING YES + + + the spill is folded into Flooding Loss, as a 1D-only run reports it + + + Flow Routing Continuity + + + Volume (10⁶ gal) + + + Dry Weather Inflow + + + 0.000 + + + Wet Weather Inflow + + + 12.480 + + + Groundwater Inflow + + + 0.000 + + + RDII Inflow + + + 0.000 + + + External Inflow + + + 0.000 + + + External Outflow + + + 9.120 + + + Flooding Loss + + + 3.210 + + + 2D Coupling Outflow + + + 0.000 + + + Evaporation Loss + + + 0.040 + + + Initial Stored Volume + + + 0.310 + + + Final Stored Volume + + + 0.418 + + + Continuity Error (%) + + + -0.002 + + + + One number moves between two rows. The totals, the ledger and the continuity error are identical, and the 2D block of §9.9 is unchanged. + + + The key changes reporting only: it never changes what the solvers exchange. + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch9_mesh_stencil.svg b/docs/figures/svg/hydraulics_ch9_mesh_stencil.svg new file mode 100644 index 000000000..a4f6961e3 --- /dev/null +++ b/docs/figures/svg/hydraulics_ch9_mesh_stencil.svg @@ -0,0 +1,517 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + n̂ + + + shared face: length ξ, outward normal n̂ of L, + separation d_n = d_e(L) + d_e(R) + + + local edge k runs between vertices (k+1) mod nv and (k+2) mod nv — one rule for both + shapes, so on a triangle edge k is opposite vertex k. Each cell numbers its own vertices. + + + (a) A quadrilateral and a triangle sharing a face + + + + + + + + + + + + + + + + + + + + + quad L + + + k=0 + + + k=1 + + + k=2 + + + k=3 + + + + + + + + + + + + L:v0 + + + + + + + + + L:v1 + + + + + + + + + L:v2 + + + + + + + + + L:v3 + + + triangle R + + + k=0 + + + k=1 + + + k=2 + + + + + + + + + R:v0 + + + + + + + + + R:v1 + + + + + + + + + R:v2 + + + d_e + + + d_e + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + cell 0 + quad + + + 0 + + + k=0 + + + 1 + + + k=1 + + + 2 + + + k=2 + + + 3 + + + k=3 + + + cell 1 + triangle + + + 4 + + + k=0 + + + 5 + + + k=1 + + + 6 + + + k=2 + + + 7 + + + k=3 + + + cell 2 + triangle + + + 8 + + + k=0 + + + 9 + + + k=1 + + + 10 + + + k=2 + + + 11 + + + k=3 + + + cell 3 + quad + + + 12 + + + k=0 + + + 13 + + + k=1 + + + 14 + + + k=2 + + + 15 + + + k=3 + + + slot 4t + k addresses cell t's edge k directly: one stride, no per-cell offset table + + + a triangle's fourth slot is allocated and never visited — the padding a fixed stride costs + + + edge arrays (neighbour, length, normal, conveyance, momentum) all share this layout, so one index reaches every one of them + + + (b) The padded slot layout + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_ch9_vfr_wetting_cases.svg b/docs/figures/svg/hydraulics_ch9_vfr_wetting_cases.svg new file mode 100644 index 000000000..4e0aba17b --- /dev/null +++ b/docs/figures/svg/hydraulics_ch9_vfr_wetting_cases.svg @@ -0,0 +1,388 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z_1 + + + z_2 + + + z_3 + + + η below z_2: a wet triangle + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z_1 + + + z_2 + + + z_3 + + + z_2 < η < z_3: a wet quadrilateral + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z_1 + + + z_2 + + + z_3 + + + η above z_3: fully wet + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + z_lo + + + z_hi + + + blocked + + + partially wet + + + submerged + + + the wetted-edge face gate + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_conceptual_1d2d.svg b/docs/figures/svg/hydraulics_conceptual_1d2d.svg new file mode 100644 index 000000000..3190ec492 --- /dev/null +++ b/docs/figures/svg/hydraulics_conceptual_1d2d.svg @@ -0,0 +1,2520 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ATMOSPHERE + + + LAND SURFACE · subcatchments (lumped) + + + LAND SURFACE · 2D mesh (distributed) + + + SUBSURFACE · two-zone aquifer per subcatchment + + + SUBSURFACE · two-layer aquifer on the mesh + + + CONVEYANCE · 1D node–link network + + + OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage + + + + + + precipitation · snowmelt + + + + + + evaporation · ET + + + + + + rain on cells + + + + + + evaporation on cells + + + + + + infiltration + + + + + + per-cell infiltration + + + + + + Dunne return flow · capillary rise + + + + + + GW interflow (user [GWF]) + + + + + + node–bed exchange + + + + + + runoff → outlet node + + + + + + 1D ↔ 2D exchange at vertices / cells + + + + + + street inlet capture + + + + + + runoff → cell + + + One-dimensional network and two-dimensional surface: the exchange pathways + + + Status of each alternative: + + + arrows: water (blue) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + + + + Climate + + + + + + + + + + + + + + + + + + Snowmelt + + + + + + Runoff + + + + + + + + + + + + Infiltration + + + + + + + + + + + + + + + + + + LID controls + + + + + + + + + + + + Surface quality + + + + + + + + + + + + Rain on the mesh + + + + + + + + + Per-cell infiltration + + + + + + + + + Overland flow + + + + + + + + + + + + + + + Mesh and closure + + + + + + + + + + + + + + + Surface quality · transport + + + + + + + + + Backends + + + + + + + + + + + + + + + Two-zone aquifer + + + + + + + + + + + + Groundwater transport + + + + + + Two-layer aquifer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nodes + + + + + + + + + + + + Links + + + + + + + + + + + + + + + + + + + + + Flow routing + + + + + + + + + + + + + + + + + + + + + Pressurisation + + + + + + + + + + + + + + + + + + + + + + + + + + + Node solution + + + + + + + + + + + + + + + Transport + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inflows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + rain gages + + + rain · snow split (SCF) + + + scale factors + + + temperature + + + evaporation: constant · monthly · series · Hargreaves · file + + + wind + + + humidity · dew point + + + prescribed PET (API) + + + degree-day · heat budget · areal depletion + + + nonlinear reservoir + + + depression storage + + + routing to another subcatchment + + + Horton + + + modified Horton + + + Green-Ampt + + + modified Green-Ampt + + + curve number + + + layered units (8 types) + + + LID as storage nodes + + + detailed output + + + buildup · washoff by land use + + + street sweeping + + + MSX species + + + natural neighbour + + + system + + + Horton · Green-Ampt · CN · constant + + + → lost · subcatchment aquifer · mesh aquifer + + + local inertial + + + full shallow water + + + diffusive wave + + + IMEX / CVODE + + + triangles + + + quads + + + flat cells + + + VFR closure + + + coverages · buildup · washoff + + + species on the mesh + + + CPU + + + OpenMP + + + CUDA · HIP · SYCL + + + Metal + + + unsaturated + saturated zone + + + percolation · deep percolation · ET + + + lateral interflow, user [GWF] + + + advection–dispersion · heat + + + Gardner + + + Russo + + + Brooks–Corey + + + van Genuchten + + + closed form · enslaved · σ column + + + Dunne return flow + + + node–bed exchange + + + capillary rise · boundary ET + + + per-subcatchment mode + + + junction · storage · divider · outfall + + + virtual junction + + + inlet junction + + + conduits, 26 sections + + + street · dummy + + + Chebyshev irregular + + + pumps · orifices · weirs · outlets · culverts + + + storage shapes + + + HEC-22 inlets + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + local time stepping + + + 1D GPU backend + + + EXTRAN + + + slot + + + dynamic slot + + + TPA + + + FV: slot + + + FV: TPA + + + FV: implicit head + + + unsteady friction + + + explicit continuity + + + semi-implicit continuity + + + Anderson acceleration + + + FV_NODE_* keys + + + CSTR + + + Eulerian ARD + + + Lagrangian LARD + + + random-walk dispersion + + + first-order decay + + + MSX reactions + + + water age + + + heat + + + sediment + + + treatment functions + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + control rules + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydraulics_conceptual_map.svg b/docs/figures/svg/hydraulics_conceptual_map.svg new file mode 100644 index 000000000..0e5a824db --- /dev/null +++ b/docs/figures/svg/hydraulics_conceptual_map.svg @@ -0,0 +1,2520 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ATMOSPHERE + + + LAND SURFACE · subcatchments (lumped) + + + LAND SURFACE · 2D mesh (distributed) + + + SUBSURFACE · two-zone aquifer per subcatchment + + + SUBSURFACE · two-layer aquifer on the mesh + + + CONVEYANCE · 1D node–link network + + + OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage + + + + + + precipitation · snowmelt + + + + + + evaporation · ET + + + + + + rain on cells + + + + + + evaporation on cells + + + + + + infiltration + + + + + + per-cell infiltration + + + + + + Dunne return flow · capillary rise + + + + + + GW interflow (user [GWF]) + + + + + + node–bed exchange + + + + + + runoff → outlet node + + + + + + 1D ↔ 2D exchange at vertices / cells + + + + + + street inlet capture + + + + + + runoff → cell + + + Hydraulics: the 1D network, the 2D surface and their coupling + + + Status of each alternative: + + + arrows: water (blue) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + + + + Climate + + + + + + + + + + + + + + + + + + Snowmelt + + + + + + Runoff + + + + + + + + + + + + Infiltration + + + + + + + + + + + + + + + + + + LID controls + + + + + + + + + + + + Surface quality + + + + + + + + + + + + Rain on the mesh + + + + + + + + + Per-cell infiltration + + + + + + + + + Overland flow + + + + + + + + + + + + + + + Mesh and closure + + + + + + + + + + + + + + + Surface quality · transport + + + + + + + + + Backends + + + + + + + + + + + + + + + Two-zone aquifer + + + + + + + + + + + + Groundwater transport + + + + + + Two-layer aquifer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nodes + + + + + + + + + + + + Links + + + + + + + + + + + + + + + + + + + + + Flow routing + + + + + + + + + + + + + + + + + + + + + Pressurisation + + + + + + + + + + + + + + + + + + + + + + + + + + + Node solution + + + + + + + + + + + + + + + Transport + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inflows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + rain gages + + + rain · snow split (SCF) + + + scale factors + + + temperature + + + evaporation: constant · monthly · series · Hargreaves · file + + + wind + + + humidity · dew point + + + prescribed PET (API) + + + degree-day · heat budget · areal depletion + + + nonlinear reservoir + + + depression storage + + + routing to another subcatchment + + + Horton + + + modified Horton + + + Green-Ampt + + + modified Green-Ampt + + + curve number + + + layered units (8 types) + + + LID as storage nodes + + + detailed output + + + buildup · washoff by land use + + + street sweeping + + + MSX species + + + natural neighbour + + + system + + + Horton · Green-Ampt · CN · constant + + + → lost · subcatchment aquifer · mesh aquifer + + + local inertial + + + full shallow water + + + diffusive wave + + + IMEX / CVODE + + + triangles + + + quads + + + flat cells + + + VFR closure + + + coverages · buildup · washoff + + + species on the mesh + + + CPU + + + OpenMP + + + CUDA · HIP · SYCL + + + Metal + + + unsaturated + saturated zone + + + percolation · deep percolation · ET + + + lateral interflow, user [GWF] + + + advection–dispersion · heat + + + Gardner + + + Russo + + + Brooks–Corey + + + van Genuchten + + + closed form · enslaved · σ column + + + Dunne return flow + + + node–bed exchange + + + capillary rise · boundary ET + + + per-subcatchment mode + + + junction · storage · divider · outfall + + + virtual junction + + + inlet junction + + + conduits, 26 sections + + + street · dummy + + + Chebyshev irregular + + + pumps · orifices · weirs · outlets · culverts + + + storage shapes + + + HEC-22 inlets + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + local time stepping + + + 1D GPU backend + + + EXTRAN + + + slot + + + dynamic slot + + + TPA + + + FV: slot + + + FV: TPA + + + FV: implicit head + + + unsteady friction + + + explicit continuity + + + semi-implicit continuity + + + Anderson acceleration + + + FV_NODE_* keys + + + CSTR + + + Eulerian ARD + + + Lagrangian LARD + + + random-walk dispersion + + + first-order decay + + + MSX reactions + + + water age + + + heat + + + sediment + + + treatment functions + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + control rules + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch3_nonlinear_reservoir.svg b/docs/figures/svg/hydrology_ch3_nonlinear_reservoir.svg new file mode 100644 index 000000000..c1aeea8e2 --- /dev/null +++ b/docs/figures/svg/hydrology_ch3_nonlinear_reservoir.svg @@ -0,0 +1,275 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + depression storage d_s (dashed) + + + + + + + + d + + + + + + + + + + + + + + + + + + + + + + + rainfall i (+ snowmelt, run-on from upstream subcatchments) + + + + + + + evaporation e + + + + + + + + + + + infiltration f + + + + + + + runoff q = (W/n) (d − d_s)^(5/3) S^(1/2) + + + outlet: a node or + another subcatchment + + + + + + + + flow length = area / width W; slope S + + + The subcatchment as a nonlinear reservoir: dd/dt = i − e − f − q + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch4_green_ampt_curve.svg b/docs/figures/svg/hydrology_ch4_green_ampt_curve.svg new file mode 100644 index 000000000..a39fc628d --- /dev/null +++ b/docs/figures/svg/hydrology_ch4_green_ampt_curve.svg @@ -0,0 +1,537 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + + + + + + + + + + 3.5 + + + + + + + + + + + + + 4.0 + + + + cumulative infiltration F (in) + + + + + + + + + + + + + + + + + 0.00 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.50 + + + + + + + + + + + + + 0.75 + + + + + + + + + + + + + 1.00 + + + + + + + + + + + + + 1.25 + + + + + + + + + + + + + 1.50 + + + + + + + + + + + + + 1.75 + + + + + + + + + + + + + 2.00 + + + + infiltration rate (in/h) + + + + + + + + + + + + + + + + + + + + + + + + + F_s = K_s ψ_s θ_d / (i − K_s) = 0.43 in + + + K_s = 0.25 in/h + + + K_s = 0.25 in/h, ψ_s = 6.5 in, θ_d = 0.20, rainfall i = 1.0 in/h + + + + + + + before saturation: f = i + + + + + + after saturation: f_p = K_s (1 + ψ_s θ_d / F) + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch4_green_ampt_recovery_params.svg b/docs/figures/svg/hydrology_ch4_green_ampt_recovery_params.svg new file mode 100644 index 000000000..e9c89f9d0 --- /dev/null +++ b/docs/figures/svg/hydrology_ch4_green_ampt_recovery_params.svg @@ -0,0 +1,743 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + K_s (in/h) + + + + + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 5 + + + + upper-zone depth L_u + + + + + + + + + + + + + L_u = 4 √K_s (in) + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + K_s (in/h) + + + + + + + + + + + + + + 0.0025 + + + + + + + + + + + + + 0.0050 + + + + + + + + + + + + + 0.0075 + + + + + + + + + + + + + 0.0100 + + + + + + + + + + + + + 0.0125 + + + + + + + + + + + + + 0.0150 + + + + + + + + + + + + + 0.0175 + + + + recovery rate k_r + + + + + + + + + + + + + k_r = √K_s / 75 (1/h) + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + K_s (in/h) + + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + minimum dry time T_r + + + + + + + + + + + + + T_r = 4.5 / √K_s (h) + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch4_horton_cumulative.svg b/docs/figures/svg/hydrology_ch4_horton_cumulative.svg new file mode 100644 index 000000000..33f069cea --- /dev/null +++ b/docs/figures/svg/hydrology_ch4_horton_cumulative.svg @@ -0,0 +1,856 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + t (h) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + + + + + + + + + + 3.5 + + + + f_p (in/h) + + + + + + + + + + + + + + + + + + + + + + + + t_p + + + F(t_p) + + + F is the area under the capacity curve + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + t_p (h) + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.2 + + + + + + + + + + + + + 1.4 + + + + + + + + + + + + + 1.6 + + + + F (in) + + + + + + + + + + + + + + + + asymptote f_∞ t + (f_0 − f_∞)/k_d + + + F(t_p) = f_∞ t_p + (f_0 − f_∞)(1 − e^(−k_d t_p))/k_d + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch4_horton_curve.svg b/docs/figures/svg/hydrology_ch4_horton_curve.svg new file mode 100644 index 000000000..02abaf4b6 --- /dev/null +++ b/docs/figures/svg/hydrology_ch4_horton_curve.svg @@ -0,0 +1,1838 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.00 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.50 + + + + + + + + + + + + + 0.75 + + + + + + + + + + + + + 1.00 + + + + + + + + + + + + + 1.25 + + + + + + + + + + + + + 1.50 + + + + + + + + + + + + + 1.75 + + + + + + + + + + + + + 2.00 + + + + time from the start of the storm t (h) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + + + + + + + + + + 3.5 + + + + rate (in/h) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + f_∞ + + + f_0 + + + + + + + rainfall intensity i(t) + + + + + + infiltration capacity f_p(t) = f_∞ + (f_0 − f_∞) e^(−k_d t) + + + + + + actual infiltration f = min(f_p, i) + + + + + + runoff (i exceeds f_p) + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch4_horton_recovery.svg b/docs/figures/svg/hydrology_ch4_horton_recovery.svg new file mode 100644 index 000000000..3db944609 --- /dev/null +++ b/docs/figures/svg/hydrology_ch4_horton_recovery.svg @@ -0,0 +1,561 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 6 + + + + time (h) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + + + + + + + + + + 3.5 + + + + f_p (in/h) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + f_r at t_pr, when rain stops + + + t_w + + + wet + + + dry + + + f_0 + + + f_∞ + + + + + + + capacity decays while wet (Eq. 4-1) + + + + + + capacity recovers while dry (Eq. 4-6) + + + + + + recovery curve projected back to t_w, where f_p = f_∞ (Eq. 4-8) + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch5_lateral_flow_heights.svg b/docs/figures/svg/hydrology_ch5_lateral_flow_heights.svg new file mode 100644 index 000000000..717f2e744 --- /dev/null +++ b/docs/figures/svg/hydrology_ch5_lateral_flow_heights.svg @@ -0,0 +1,188 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + water table + + + receiving node or channel + + + + + + + Q_GW + + + + + + + + H_GW groundwater head + + + + + + + + H_SW surface water height + + + H* threshold (dashed; default: the node invert) + + + aquifer bottom: the datum of every height + + + Heights in the lateral groundwater flow equation + + + Q_GW = A1 (H_GW − H*)^B1 − A2 (H_SW − H*)^B2 + A3 · H_GW · H_SW + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch5_two_zone.svg b/docs/figures/svg/hydrology_ch5_two_zone.svg new file mode 100644 index 000000000..76c3d9414 --- /dev/null +++ b/docs/figures/svg/hydrology_ch5_two_zone.svg @@ -0,0 +1,531 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + water table + + + upper zone + unsaturated + moisture content θ + + + lower zone + saturated + θ = porosity φ + + + impermeable bottom + + + + + + + + d_U + + + + + + + + d_L + + + + + + + + + + f_I infiltration from the surface + + + + + + + + + + f_EU upper-zone ET + + + + + + + + + + f_EL lower-zone ET + + + + + + + + + + f_U percolation, upper to lower zone + + + + + + + + + + f_L deep percolation (seepage) loss + + + + + + + f_G lateral groundwater + interflow to the + drainage system + + + Two-zone groundwater model of a subcatchment (fluxes per unit area) + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch6_areal_depletion_curve.svg b/docs/figures/svg/hydrology_ch6_areal_depletion_curve.svg new file mode 100644 index 000000000..61ef1bfd3 --- /dev/null +++ b/docs/figures/svg/hydrology_ch6_areal_depletion_curve.svg @@ -0,0 +1,364 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + AWESI = WSNOW / SI (snow depth as a fraction of the depth at 100 % cover) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + ASC (areal snow cover fraction) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + pack state when + the new snow fell + + + ASC = 1 for AWESI ≥ 1 + + + + + + + natural-area curve (Anderson, 1973) + + + + + + temporary curve for new snow on a partly bare pack + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch7_ia_seasonal.svg b/docs/figures/svg/hydrology_ch7_ia_seasonal.svg new file mode 100644 index 000000000..2a3823d6f --- /dev/null +++ b/docs/figures/svg/hydrology_ch7_ia_seasonal.svg @@ -0,0 +1,5051 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 30 + + + + rainfall (mm/d) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + forcing: storms deplete the abstraction, warmth restores it + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 20 + + + + IA_avail (mm) + + + + + + + + + + + + + + + + + + + + IA_max + + + the abstraction store: depletion by rain, temperature-dependent recovery, frozen-ground hold + + + + + + + frozen ground: recovery suspended + + + + + + available initial abstraction IA_avail + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 50 + + + + + + + + + + + + + 100 + + + + + + + + + + + + + 150 + + + + + + + + + + + + + 200 + + + + + + + + + + + + + 250 + + + + + + + + + + + + + 300 + + + + + + + + + + + + + 350 + + + + day of year + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + RDII response + (schematic) + + + + + + + + + + + + + + + + + + + + + RDII: the same storm yields more inflow when the store is depleted or frozen + + + + + + + + + + + + + + + 0 + + + + + + + + + + 10 + + + + + + + + + + 20 + + + + temperature (°C) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch7_rtk_unit_hydrographs.svg b/docs/figures/svg/hydrology_ch7_rtk_unit_hydrographs.svg new file mode 100644 index 000000000..5a588eb77 --- /dev/null +++ b/docs/figures/svg/hydrology_ch7_rtk_unit_hydrographs.svg @@ -0,0 +1,5082 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 40 + + + + + + + + + + + + + 50 + + + + + + + + + + + + + 60 + + + + time since the unit of rainfall (h) + + + + + RDII flow per unit rainfall per unit area + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + short-term response (R1, T1, K1) + + + + + + intermediate response (R2, T2, K2) + + + + + + long-term response (R3, T3, K3) + + + + + + total RDII unit hydrograph (sum) + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch8_cell_budget.svg b/docs/figures/svg/hydrology_ch8_cell_budget.svg new file mode 100644 index 000000000..09efc2eea --- /dev/null +++ b/docs/figures/svg/hydrology_ch8_cell_budget.svg @@ -0,0 +1,387 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + neighbour + + + neighbour + + + + + + + + + + + + + + + r_i interpolated rainfall (§8.2) + + + + + + + e*_i evaporation, + ramped (§8.5) + + + + + + + f*_i infiltration, ramped (§8.3) + → lost · subcatchment aquifer + · mesh aquifer (§8.4) + + + + + + + g_i aquifer return + (Chapter 9) + + + + + + + + s_i held coupling flux + with the 1D network + + + + + + + + + + + ΣΔV face fluxes to and from the neighbours (Hydraulics Ch. 9) + + + V_i ← max( 0, V_i + Δt A_i ( r_i + s_i + g_i − e*_i − f*_i ) + Σ_faces ΔV ) + + + the same terms the 2D Surface Routing Continuity block of the report prints + + + + + + cell i + + + depth h_i, area A_i, volume V_i + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + DRY_DEPTH + + + + cell depth h_i + + + + + + + + + + + + + + 0 + + + + + + + + + + 1 + + + + + + + + + + + + + + + + + + + + + + + both sinks share this ramp + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch8_infiltration_strip.svg b/docs/figures/svg/hydrology_ch8_infiltration_strip.svg new file mode 100644 index 000000000..ae90444ef --- /dev/null +++ b/docs/figures/svg/hydrology_ch8_infiltration_strip.svg @@ -0,0 +1,790 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + cell 1 + + + GREEN + AMPT + + + cell 2 + + + GREEN + AMPT + + + cell 3 + + + GREEN + AMPT + + + TAG SILT + + + TAG row + + + cell 4 + + + HORTON + + + cell 5 + + + CURVE + NUMBER + + + cell 6 + + + HORTON + + + TAG SAND + + + TAG row + + + cell 7 + + + NONE + + + cell 8 + + + NONE + + + cell 9 + + + NONE + + + TAG CLAY + + + TAG row clears the default + + + + + + + [2D_INFILTRATION] CELL row — a per-cell override + + + resolution order: cell override > TAG row > `*` row > none + + + the `*` row of [2D_INFILTRATION_DEFAULTS] is the mesh-wide fallback; a NONE row deliberately clears it + + + (a) How each cell resolves its method and parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.00 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.50 + + + + + + + + + + + + + 0.75 + + + + + + + + + + + + + 1.00 + + + + + + + + + + + + + 1.25 + + + + + + + + + + + + + 1.50 + + + + + + + + + + + + + 1.75 + + + + + + + + + + + + + 2.00 + + + + time (hr) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + infiltration rate (in/hr) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + INFIL_STEP + + + the marcher's substeps are far shorter than INFIL_STEP; + each consumes the held rate through the dry-depth ramp of (8-5) + + + (b) The rate is refreshed on INFIL_STEP and held between calls + + + + + + + the kernel's continuous capacity + + + + + + the held rate f_i the marcher consumes + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch8_nn_weights.svg b/docs/figures/svg/hydrology_ch8_nn_weights.svg new file mode 100644 index 000000000..7f4fe0524 --- /dev/null +++ b/docs/figures/svg/hydrology_ch8_nn_weights.svg @@ -0,0 +1,433 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Laplace weights w = ℓ / distance, normalised + + + w_B = 0.404 w_C = 0.307 w_D = 0.145 w_E = 0.064 w_F = 0.080 + + + intensity at p = 23.9 mm/hr A is not a natural neighbour: weight 0 + + + grey: the Delaunay triangulation of the gages blue fill: the centroid's new Voronoi cell + orange: the facet it shares with each natural neighbour + + + (a) Inside the hull — Laplace natural-neighbour weights + + + + + + + + + + + + + + + + + + ℓ=4.13 + + + ℓ=3.45 + + + ℓ=2.57 + + + ℓ=1.41 + + + ℓ=1.77 + + + + + + + + + + + + A · 10 + + + + + + + + + + + + B · 22 + + + + + + + + + C · 30 + + + + + + + + + D · 26 + + + + + + + + + E · 16 + + + + + + + + + F · 12 + + + + + + + + + + + + cell centroid p + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inverse-distance weights w = d⁻² normalised, over every located gage + + + w_A = 0.043 w_B = 0.080 w_C = 0.275 w_D = 0.458 w_E = 0.091 w_F = 0.054 + + + intensity at q = 24.4 mm/hr + + + line weight is the gage's share. IDW never leaves the range of the readings: it tends to the + nearest gage close in, and to the plain mean far out. + + + (b) Outside the hull — inverse-distance weights + + + + + + + + + A · 10 + + + + + + + + + B · 22 + + + + + + + + + C · 30 + + + + + + + + + D · 26 + + + + + + + + + E · 16 + + + + + + + + + F · 12 + + + + + + + + + + + + cell centroid q, + outside every Delaunay triangle + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch9_node_bed_exchange.svg b/docs/figures/svg/hydrology_ch9_node_bed_exchange.svg new file mode 100644 index 000000000..6c6297ec1 --- /dev/null +++ b/docs/figures/svg/hydrology_ch9_node_bed_exchange.svg @@ -0,0 +1,266 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + mesh cell — ground surface z_c + + + water table H_gw = z_bed + h_g + + + aquifer bottom z_bed + + + d + + + pipe head + H_pipe = z_inv + d + + + z_inv + + + + + + + + d_C + + + semi-confining bed: K_c, contact area A_b + + + + + + + + H_gw − H_pipe + drives the exchange + + + + + + + Q > 0 infiltration + into the pipe + + + + + + + Q < 0 exfiltration + into the aquifer + + + Q_node = C (H_gw − H_pipe), C = K_c A_b / d_C with a bed, C = K_s A_b / (½ z_s) without one + + + Caps — a drain takes at most half the cell's drainable water per step, ½ h_g S_y A / Δt. A recharge is refused when the table is within 10⁻⁴ z_s of the ground, + takes at most half the headroom (z_s − h_g) S_y A, and cannot exceed what the node holds for the batch plus what flows through it. + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch9_soil_characteristics.svg b/docs/figures/svg/hydrology_ch9_soil_characteristics.svg new file mode 100644 index 000000000..4e9723850 --- /dev/null +++ b/docs/figures/svg/hydrology_ch9_soil_characteristics.svg @@ -0,0 +1,1248 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + suction ψ above the water table (m) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + effective saturation S_e + + + + + + + + + + + + + + + + + + + + + + + + + air entry ψ_b = 0.2 m + + + (a) Retention: what the column holds + + + + + + + GARDNER + + + + + + RUSSO (default) + + + + + + BROOKS_COREY + + + + + + VAN_GENUCHTEN + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + suction ψ above the water table (m) + + + + + + + + + + + + + + + + + 1 + 0 + − + 6 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 5 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 4 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 3 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 2 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 1 + + + + + + + + + + + + + + + + + + 1 + 0 + 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + relative conductivity K_r = K / K_s + + + + + + + + + + + + + + + + + + + + + + + + + α = 2 /m ψ_b = 0.2 m λ = 0.4 n = 1.6 L_M = 0.5 + θ(ψ) = θ_r + S_e (θ_s − θ_r); K(ψ) = K_s K_r(ψ) + + + (b) Conductivity: how fast it moves + + + + + + + + + + + + diff --git a/docs/figures/svg/hydrology_ch9_two_layer_column.svg b/docs/figures/svg/hydrology_ch9_two_layer_column.svg new file mode 100644 index 000000000..4c9d608b4 --- /dev/null +++ b/docs/figures/svg/hydrology_ch9_two_layer_column.svg @@ -0,0 +1,523 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bulk store h_u + + + one state for the + whole column + + + closure A — CLOSED_FORM / ENSLAVED + + + + + + + + m = 8 layers + Δσ = 1/m, σ = z/L + θ_j per layer + + + closure B — SIGMA + + + + + + + + + + + + + + + + + + + q_0 + + + + + + + + + + + + + + + q⁺ + + + q_ET + + + Dunne + + + + + + + + + + + + + + + + + + + q_0 + + + + + + + + + + + + + + + q⁺ + + + q_ET + + + Dunne + + + deep loss c_loss h_g / z_s + + + deep loss + + + lateral Darcy + (harmonic K) + + + q⁺ infiltration delivered by the surface (Chapter 8) q_ET root uptake and boundary ET + Dunne return flow when the table reaches the ground q_0 recharge across the table, H = z_bed + h_g + + + + + + + + z_s + + + + + + + + h_g + + + L = z_s − h_g + + + ground z_c + + + bottom z_bed + + + water table H + + + + + + + node exchange + (Figure 9-3) + + + Both closures carry the same saturated state h_g and the same ledger; + they differ only in how the unsaturated column above it is held. AUTO picks + between them from αL, the column thickness in capillary lengths (§9.4.1). + + + + + + + + + diff --git a/docs/figures/svg/hydrology_conceptual_map.svg b/docs/figures/svg/hydrology_conceptual_map.svg new file mode 100644 index 000000000..b133845f5 --- /dev/null +++ b/docs/figures/svg/hydrology_conceptual_map.svg @@ -0,0 +1,2520 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ATMOSPHERE + + + LAND SURFACE · subcatchments (lumped) + + + LAND SURFACE · 2D mesh (distributed) + + + SUBSURFACE · two-zone aquifer per subcatchment + + + SUBSURFACE · two-layer aquifer on the mesh + + + CONVEYANCE · 1D node–link network + + + OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage + + + + + + precipitation · snowmelt + + + + + + evaporation · ET + + + + + + rain on cells + + + + + + evaporation on cells + + + + + + infiltration + + + + + + per-cell infiltration + + + + + + Dunne return flow · capillary rise + + + + + + GW interflow (user [GWF]) + + + + + + node–bed exchange + + + + + + runoff → outlet node + + + + + + 1D ↔ 2D exchange at vertices / cells + + + + + + street inlet capture + + + + + + runoff → cell + + + Hydrology: atmosphere, land surface and subsurface representations + + + Status of each alternative: + + + arrows: water (blue) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + + + + Climate + + + + + + + + + + + + + + + + + + Snowmelt + + + + + + Runoff + + + + + + + + + + + + Infiltration + + + + + + + + + + + + + + + + + + LID controls + + + + + + + + + + + + Surface quality + + + + + + + + + + + + Rain on the mesh + + + + + + + + + Per-cell infiltration + + + + + + + + + Overland flow + + + + + + + + + + + + + + + Mesh and closure + + + + + + + + + + + + + + + Surface quality · transport + + + + + + + + + Backends + + + + + + + + + + + + + + + Two-zone aquifer + + + + + + + + + + + + Groundwater transport + + + + + + Two-layer aquifer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nodes + + + + + + + + + + + + Links + + + + + + + + + + + + + + + + + + + + + Flow routing + + + + + + + + + + + + + + + + + + + + + Pressurisation + + + + + + + + + + + + + + + + + + + + + + + + + + + Node solution + + + + + + + + + + + + + + + Transport + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inflows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + rain gages + + + rain · snow split (SCF) + + + scale factors + + + temperature + + + evaporation: constant · monthly · series · Hargreaves · file + + + wind + + + humidity · dew point + + + prescribed PET (API) + + + degree-day · heat budget · areal depletion + + + nonlinear reservoir + + + depression storage + + + routing to another subcatchment + + + Horton + + + modified Horton + + + Green-Ampt + + + modified Green-Ampt + + + curve number + + + layered units (8 types) + + + LID as storage nodes + + + detailed output + + + buildup · washoff by land use + + + street sweeping + + + MSX species + + + natural neighbour + + + system + + + Horton · Green-Ampt · CN · constant + + + → lost · subcatchment aquifer · mesh aquifer + + + local inertial + + + full shallow water + + + diffusive wave + + + IMEX / CVODE + + + triangles + + + quads + + + flat cells + + + VFR closure + + + coverages · buildup · washoff + + + species on the mesh + + + CPU + + + OpenMP + + + CUDA · HIP · SYCL + + + Metal + + + unsaturated + saturated zone + + + percolation · deep percolation · ET + + + lateral interflow, user [GWF] + + + advection–dispersion · heat + + + Gardner + + + Russo + + + Brooks–Corey + + + van Genuchten + + + closed form · enslaved · σ column + + + Dunne return flow + + + node–bed exchange + + + capillary rise · boundary ET + + + per-subcatchment mode + + + junction · storage · divider · outfall + + + virtual junction + + + inlet junction + + + conduits, 26 sections + + + street · dummy + + + Chebyshev irregular + + + pumps · orifices · weirs · outlets · culverts + + + storage shapes + + + HEC-22 inlets + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + local time stepping + + + 1D GPU backend + + + EXTRAN + + + slot + + + dynamic slot + + + TPA + + + FV: slot + + + FV: TPA + + + FV: implicit head + + + unsteady friction + + + explicit continuity + + + semi-implicit continuity + + + Anderson acceleration + + + FV_NODE_* keys + + + CSTR + + + Eulerian ARD + + + Lagrangian LARD + + + random-walk dispersion + + + first-order decay + + + MSX reactions + + + water age + + + heat + + + sediment + + + treatment functions + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + control rules + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/quality_ch10_cell_buildup_washoff.svg b/docs/figures/svg/quality_ch10_cell_buildup_washoff.svg new file mode 100644 index 000000000..2d21bfed1 --- /dev/null +++ b/docs/figures/svg/quality_ch10_cell_buildup_washoff.svg @@ -0,0 +1,241 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 60 % + + + Residential + + + B = 0.78 + + + 25 % + + + Commercial + + + B = 0.52 + + + 15 % + + + bare + + + no land use + no store + + + one mesh cell — [2D_COVERAGES] replaces the whole set for its scope, ladder * > TAG > CELL + + + buildup per (cell, land use, species), in user mass per normalizer: N = f·A (per area) or f·L (per curb) + + + + + + + accrual on the runoff step + (Chapter 3's functions, unchanged) + + + + + + + sweeping removes a fraction + on its own schedule + + + + + + + washoff + + + driven by the cell's net + outflow as a runoff rate + + + Pollutant TSS + + + Pollutant Lead + + + MSX species + + + the cell's species mass rows m_{s,i} + + + species-major; concentration is derived + + + + + + + advection across + the mesh (§10.2) + + + coupled node + + + + + + + into the 1D + transport + + + Per-curb land uses need a curb length on every cell they cover ([2D_CURB_LENGTH]); a covered cell without one is refused at open, not given zero. + + + A cell whose centroid lies in a subcatchment that carries its own coverages is reported in one ownership warning: the same storm would load twice. + + + + + + + + + diff --git a/docs/figures/svg/quality_ch10_transport_policy.svg b/docs/figures/svg/quality_ch10_transport_policy.svg new file mode 100644 index 000000000..fd2721b35 --- /dev/null +++ b/docs/figures/svg/quality_ch10_transport_policy.svg @@ -0,0 +1,463 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pollutants + + + MSX + + + Age + + + Temperature + + + Runoff / LID + + + on(3) + + + on(2) + + + n/a + age is not + carried on + subcatchments + + + n/a + HEAT_TRANSPORT + OFF + + + Groundwater + + + n/a + groundwater + transport is + planned + + + n/a + planned + + + n/a + planned + + + n/a + planned + + + 1D network + + + on(3) + + + on(2) + + + on(1) + + + n/a + HEAT_TRANSPORT + OFF + + + 2D surface + + + on(3) + + + off + a WALL species + is declared + + + on(1) + + + n/a + HEAT_TRANSPORT + OFF + + + on(n) carries n rows · off names the key that disabled it · n/a says what is missing + + + canonical row order: pollutants, MSX in declaration order, __WATER_AGE__, __TEMPERATURE__ last + + + (a) The matrix the report header prints + + + + + + + + + + + + + + + + + + + + + + + + + + Is there a mesh? + + + no mesh → n/a + + + + + + + Is the class declared at project level? + + + nothing to carry → n/a + + + + + + + [OPTIONS] IGNORE_2D + + + YES → off, naming the key + + + + + + + [OPTIONS] IGNORE_QUALITY + + + YES → off; pollutants and MSX only + + + + + + + A WALL species in the reaction system? + + + yes → MSX n/a, with a warning + + + + + + + [2D_OPTIONS] TRANSPORT_<CLASS> + + + NO → off, naming the key + + + + + + + otherwise + + + on + + + the first gate that fires is the reason the cell reports + + + (b) The gate ladder behind one 2D-surface cell + + + + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_bio_cell.svg b/docs/figures/svg/quality_ch6_lid_bio_cell.svg new file mode 100644 index 000000000..8b4adb99c --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_bio_cell.svg @@ -0,0 +1,475 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Soil + + + Storage (gravel) + + + + + + + + + + + + Underdrain + + + Bio-retention cell + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_block_paver.svg b/docs/figures/svg/quality_ch6_lid_block_paver.svg new file mode 100644 index 000000000..19e9b0b3c --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_block_paver.svg @@ -0,0 +1,511 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Paver blocks + + + Sand bedding + + + Storage (gravel) + + + + + + + + + + + + Underdrain + + + Block paver + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_green_roof.svg b/docs/figures/svg/quality_ch6_lid_green_roof.svg new file mode 100644 index 000000000..9d83f0224 --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_green_roof.svg @@ -0,0 +1,305 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Soil + + + Drainage mat + + + Roof + + + Green roof + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_infiltration_trench.svg b/docs/figures/svg/quality_ch6_lid_infiltration_trench.svg new file mode 100644 index 000000000..37aae9211 --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_infiltration_trench.svg @@ -0,0 +1,367 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Storage (gravel) + + + + + + + + + + + + Underdrain + + + Infiltration trench + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_permeable_pavement.svg b/docs/figures/svg/quality_ch6_lid_permeable_pavement.svg new file mode 100644 index 000000000..7298ba3bb --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_permeable_pavement.svg @@ -0,0 +1,496 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Pavement + + + Soil + + + Storage (gravel) + + + + + + + + + + + + Underdrain + + + Continuous permeable pavement + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_rain_barrel.svg b/docs/figures/svg/quality_ch6_lid_rain_barrel.svg new file mode 100644 index 000000000..64b52550e --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_rain_barrel.svg @@ -0,0 +1,85 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + Barrel + + + + + + + + + + + + Underdrain + + + Rain barrel + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_rain_garden.svg b/docs/figures/svg/quality_ch6_lid_rain_garden.svg new file mode 100644 index 000000000..39dcf983e --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_rain_garden.svg @@ -0,0 +1,218 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Soil + + + Rain garden + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_rooftop_disconnection.svg b/docs/figures/svg/quality_ch6_lid_rooftop_disconnection.svg new file mode 100644 index 000000000..837b8ee8f --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_rooftop_disconnection.svg @@ -0,0 +1,136 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Roof + + + Surface + + + Rooftop disconnection + + + + + + + + + diff --git a/docs/figures/svg/quality_ch6_lid_vegetative_swale.svg b/docs/figures/svg/quality_ch6_lid_vegetative_swale.svg new file mode 100644 index 000000000..13e76e4c2 --- /dev/null +++ b/docs/figures/svg/quality_ch6_lid_vegetative_swale.svg @@ -0,0 +1,110 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Surface + + + Vegetative swale + + + + + + + + + diff --git a/docs/figures/svg/quality_ch7_ard_stencil.svg b/docs/figures/svg/quality_ch7_ard_stencil.svg new file mode 100644 index 000000000..2960d426c --- /dev/null +++ b/docs/figures/svg/quality_ch7_ard_stencil.svg @@ -0,0 +1,651 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + face i+½ + + + cell i + + + cell i+1 + + + cell i−1 + + + + + + + upwind: C_i + + + MUSCL: C_i + ½ φ(r) ΔC + + + unlimited slope (dashed) + would overshoot the + upstream value + + + r = (C_i − C_{i−1}) / (C_{i+1} − C_i) + φ(r): MINMOD · VANLEER · SUPERBEE + + + limited slope never leaves + [C_{i+1}, C_{i−1}]: no new extrema + + + + + + + u > 0 + + + (a) One face of the ARD stencil + + + + + + + + + + + + + + + + + + + + + 40 + + + + + + + + + + + + + 50 + + + + + + + + + + + + + 60 + + + + + + + + + + + + + 70 + + + + + + + + + + + + + 80 + + + + + + + + + + + + + 90 + + + + + + + + + + + + + 100 + + + + + + + + + + + + + 110 + + + + + + + + + + + + + 120 + + + + + + + + + + + + + 130 + + + + cell index + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + concentration C / C_0 + + + + + + + + + + + + + + + + + + + + + + + + + (b) A step front after 60 cells of travel, Courant 0.5 + + + + + + + exact (shifted step) + + + + + + UPWIND + + + + + + MUSCL + MINMOD + + + + + + MUSCL + VANLEER + + + + + + MUSCL + SUPERBEE + + + + + + + + + + + + + diff --git a/docs/figures/svg/quality_ch7_lard_parcels.svg b/docs/figures/svg/quality_ch7_lard_parcels.svg new file mode 100644 index 000000000..6739e513a --- /dev/null +++ b/docs/figures/svg/quality_ch7_lard_parcels.svg @@ -0,0 +1,493 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 1 Drain + + + 0.15 + + + 0.55 + + + 0.60 + + + 0.95 + + + 0.95 + + + + + + + + + + volume that left over the step goes to the + downstream node's inflow ledger, with its mass + + + 2 Mix + + + 0.15 + + + 0.55 + + + 0.60 + + + 0.95 + + + each node mixes held volume + arrivals as a CSTR, + in flow-aware topological order; loads join here + + + 3 Release + + + 0.20 + + + 0.15 + + + 0.57 + + + 0.95 + + + merged: concentrations agree within tolerance + + + a new parcel at the upstream node's new value, + sized so parcels again sum to the link volume + + + 4 Decay + + + 0.15 + + + 0.11 + + + 0.43 + + + 0.71 + + + exact exponential C ← C e^(−k Δt) on parcels and + node stores; removed mass booked as reacted + + + 5 Publish + + + volume-weighted mean C = 0.37 + + + link concentration = volume-weighted mean of the + parcels; the parcels themselves are kept + + + + + + + flow + + + upstream + node + + + downstream + node + + + Parcel budget: adjacent look-alikes merge at Release; MAX_SEGMENTS_PER_LINK (default 100) caps the slab, + merging the oldest first. QUALITY_STEP substeps the whole sequence; there is no Courant limit. + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/quality_ch9_heat_budget.svg b/docs/figures/svg/quality_ch9_heat_budget.svg new file mode 100644 index 000000000..0edfcba87 --- /dev/null +++ b/docs/figures/svg/quality_ch9_heat_budget.svg @@ -0,0 +1,265 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + water T_w + + + air T_a, RH, wind w, pressure p + + + land cover + (1 − f_sky) + + + + + + + J_sn net shortwave + (1 − R_s) J_in max(0, 1 − f_s) + + + + + + + J_an atmospheric longwave + σ T_a⁴ ε_a (1 − R_L) f_sky + + + + + + + J_lc ε_lc σ (1 − f_sky) T_a⁴ + + + + + + + J_br back radiation + ε_w σ T_w⁴ + + + + + + + J_e latent = ρ_w L_v E + E = (a + b w)(e_w − e_a) + signed: condensation warms + + + + + + + J_h = B_r J_e (Bowen) + + + + + + + + + + + conduction G_cond (T_w − T_b) + + + + + + + + + + + hyporheic advection G_adv (T_w − T_b) + + + bed zone T_b + + + to deep ground: G_bg (T_b − T_gr) + + + Positive flux is heat leaving the water: J_net = (J_e + J_h) + (J_br − J_sn − J_an − J_lc) + + + [HEAT_FLUXES] SURFACE_EXCHANGE → J_e, J_h RADIATIVE_EXCHANGE → J_sn, J_an, J_lc, J_br + + + SEDIMENT_EXCHANGE → bed conduction, hyporheic exchange LAYER_CONDUCTION → LID layer conduction + + + warms the water + + + cools the water (when positive) + + + + + + + + + diff --git a/docs/figures/svg/quality_conceptual_map.svg b/docs/figures/svg/quality_conceptual_map.svg new file mode 100644 index 000000000..61b731096 --- /dev/null +++ b/docs/figures/svg/quality_conceptual_map.svg @@ -0,0 +1,2520 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ATMOSPHERE + + + LAND SURFACE · subcatchments (lumped) + + + LAND SURFACE · 2D mesh (distributed) + + + SUBSURFACE · two-zone aquifer per subcatchment + + + SUBSURFACE · two-layer aquifer on the mesh + + + CONVEYANCE · 1D node–link network + + + OUTFALLS · receiving water — free · normal · fixed · tidal · time-series stage + + + + + + precipitation · snowmelt + + + + + + evaporation · ET + + + + + + rain on cells + + + + + + evaporation on cells + + + + + + infiltration + + + + + + per-cell infiltration + + + + + + Dunne return flow · capillary rise + + + + + + GW interflow (user [GWF]) + + + + + + node–bed exchange + + + + + + runoff → outlet node + + + + + + 1D ↔ 2D exchange at vertices / cells + + + + + + street inlet capture + + + + + + runoff → cell + + + Water quality: buildup, washoff, transport and reactions across the compartments + + + Status of each alternative: + + + arrows: water (blue) · 1D–2D exchange (orange) + + + Precipitation + + + + + + + + + + + + Climate + + + + + + + + + + + + + + + + + + Snowmelt + + + + + + Runoff + + + + + + + + + + + + Infiltration + + + + + + + + + + + + + + + + + + LID controls + + + + + + + + + + + + Surface quality + + + + + + + + + + + + Rain on the mesh + + + + + + + + + Per-cell infiltration + + + + + + + + + Overland flow + + + + + + + + + + + + + + + Mesh and closure + + + + + + + + + + + + + + + Surface quality · transport + + + + + + + + + Backends + + + + + + + + + + + + + + + Two-zone aquifer + + + + + + + + + + + + Groundwater transport + + + + + + Two-layer aquifer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Nodes + + + + + + + + + + + + Links + + + + + + + + + + + + + + + + + + + + + Flow routing + + + + + + + + + + + + + + + + + + + + + Pressurisation + + + + + + + + + + + + + + + + + + + + + + + + + + + Node solution + + + + + + + + + + + + + + + Transport + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Inflows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + rain gages + + + rain · snow split (SCF) + + + scale factors + + + temperature + + + evaporation: constant · monthly · series · Hargreaves · file + + + wind + + + humidity · dew point + + + prescribed PET (API) + + + degree-day · heat budget · areal depletion + + + nonlinear reservoir + + + depression storage + + + routing to another subcatchment + + + Horton + + + modified Horton + + + Green-Ampt + + + modified Green-Ampt + + + curve number + + + layered units (8 types) + + + LID as storage nodes + + + detailed output + + + buildup · washoff by land use + + + street sweeping + + + MSX species + + + natural neighbour + + + system + + + Horton · Green-Ampt · CN · constant + + + → lost · subcatchment aquifer · mesh aquifer + + + local inertial + + + full shallow water + + + diffusive wave + + + IMEX / CVODE + + + triangles + + + quads + + + flat cells + + + VFR closure + + + coverages · buildup · washoff + + + species on the mesh + + + CPU + + + OpenMP + + + CUDA · HIP · SYCL + + + Metal + + + unsaturated + saturated zone + + + percolation · deep percolation · ET + + + lateral interflow, user [GWF] + + + advection–dispersion · heat + + + Gardner + + + Russo + + + Brooks–Corey + + + van Genuchten + + + closed form · enslaved · σ column + + + Dunne return flow + + + node–bed exchange + + + capillary rise · boundary ET + + + per-subcatchment mode + + + junction · storage · divider · outfall + + + virtual junction + + + inlet junction + + + conduits, 26 sections + + + street · dummy + + + Chebyshev irregular + + + pumps · orifices · weirs · outlets · culverts + + + storage shapes + + + HEC-22 inlets + + + steady + + + kinematic wave + + + dynamic wave + + + finite volume + + + local time stepping + + + 1D GPU backend + + + EXTRAN + + + slot + + + dynamic slot + + + TPA + + + FV: slot + + + FV: TPA + + + FV: implicit head + + + unsteady friction + + + explicit continuity + + + semi-implicit continuity + + + Anderson acceleration + + + FV_NODE_* keys + + + CSTR + + + Eulerian ARD + + + Lagrangian LARD + + + random-walk dispersion + + + first-order decay + + + MSX reactions + + + water age + + + heat + + + sediment + + + treatment functions + + + dry weather flow + + + RDII: RTK + + + RDII: IA decay + + + user · interface files + + + control rules + + + Implemented + + + Experimental + + + Planned + + + Retired + + + + + + + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch10_heat_diurnal.svg b/docs/figures/svg/workflow_ch10_heat_diurnal.svg new file mode 100644 index 000000000..82da2392a --- /dev/null +++ b/docs/figures/svg/workflow_ch10_heat_diurnal.svg @@ -0,0 +1,776 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 40 + + + + + + + + + + + + + 50 + + + + + + + + + + + + + 60 + + + + time (minutes) + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 12 + + + + + + + + + + + + + 14 + + + + + + + + + + + + + 16 + + + + + + + + + + + + + 18 + + + + temperature (°C) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + inflow temperature, 18 °C + + + initial state, 12 °C + + + Everything happens in the first ten minutes: the line fills and each node + reaches the inflow temperature. For the remaining five hours the water stays at + 18.00 °C while the air rises to 22 °C — a 35-minute residence in 500 m of + pipe is far too short for the surface to move it. Heat here is transport, not exchange. + + + Water temperature along the line, with surface and radiative exchange on + + + + + + + air temperature, from the [TEMPERATURE] series + + + + + + water at J1 + + + + + + water at J2 + + + + + + water at J3 + + + + + + water at J4 + + + + + + water at J5 + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch10_water_age_along_line.svg b/docs/figures/svg/workflow_ch10_water_age_along_line.svg new file mode 100644 index 000000000..3a986d1cb --- /dev/null +++ b/docs/figures/svg/workflow_ch10_water_age_along_line.svg @@ -0,0 +1,668 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 5.0 + + + + + + + + + + + + + 7.5 + + + + + + + + + + + + + 10.0 + + + + + + + + + + + + + 12.5 + + + + + + + + + + + + + 15.0 + + + + + + + + + + + + + 17.5 + + + + + + + + + + + + + 20.0 + + + + time (minutes) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.1 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.3 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 0.6 + + + + water age (hours) + + + + + + + + + + + + + + + + + + + + + + + + + + + + EXTERNAL_INFLOW 0.5 h — the age the arriving water is given + + + INITIAL_STATE 6.0 h never appears: the pipes start empty, so there is + no standing water to carry it. A hot-started model would show it. + + + (a) The line fills, and each node settles at its own age + + + + + + + J1 + + + + + + J2 + + + + + + J3 + + + + + + J4 + + + + + + J5 + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 100 + + + + + + + + + + + + + 200 + + + + + + + + + + + + + 300 + + + + + + + + + + + + + 400 + + + + distance from the inflow (m) + + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 31 + + + + + + + + + + + + + 32 + + + + + + + + + + + + + 33 + + + + + + + + + + + + + 34 + + + + + + + + + + + + + 35 + + + + water age at the end of the run (minutes) + + + + + + + + + + + + + + + + + + + + + + + 30.1 min at J1, the declared source age, + rising to 34.8 min at J5 + + + (b) What is left is the travel time + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch11_rdii_decay_vs_linear.svg b/docs/figures/svg/workflow_ch11_rdii_decay_vs_linear.svg new file mode 100644 index 000000000..f31fd47c7 --- /dev/null +++ b/docs/figures/svg/workflow_ch11_rdii_decay_vs_linear.svg @@ -0,0 +1,744 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + day of the month + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 7 + + + + + + + + + + + + + 8 + + + + RDII inflow at the node (cfs) + + + + + + + + + + + + + + + + + + + Above freezing the store recovers between the storms and the second + produces about half the first. Below freezing recovery is suppressed + entirely, so the ground stays wet and the second storm produces more + than the first. The linear model with a zero recovery rate abstracts + both storms and reports no RDII at all. + + + (a) Two identical storms, nineteen days apart + + + + + + + linear recovery, IA_r = 0: no RDII at all + + + + + + exponential decay, month above freezing + + + + + + exponential decay, month below freezing + + + + + + + + + + + + + + + + + + + linear + recovery, IA_r = 0 + + + + + + + + + + + + + month above freezing + + + + + + + + + + + + + month below freezing + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 7 + + + + + + + + + + + + + 8 + + + + peak RDII inflow (cfs) + + + + + + + + + + + + + + + + + + + + + + + + + + + + no RDII + + + 49 % + + + 151 % + + + (b) What the second storm produces + + + + + + + first storm + + + + + + second storm + + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch2_rapid_fill_front.svg b/docs/figures/svg/workflow_ch2_rapid_fill_front.svg new file mode 100644 index 000000000..3453ebd44 --- /dev/null +++ b/docs/figures/svg/workflow_ch2_rapid_fill_front.svg @@ -0,0 +1,4258 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 35 + + + + + + + + + + + + + 40 + + + + time (s) + + + + + + + + + + + + + + + + + −0.2 + + + + + + + + + + + + + −0.1 + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.1 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.3 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.5 + + + + velocity at x = 9.9 m (m/s) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (a) Velocity: the front passing the transducer + + + + + + + + + + measured + + + + + + FV, static slot + + + + + + Dynamic wave, EXTRAN + + + + + + Dynamic wave, slot + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 35 + + + + + + + + + + + + + 40 + + + + time (s) + + + + + + + + + + + + + + 0.05 + + + + + + + + + + + + + 0.10 + + + + + + + + + + + + + 0.15 + + + + + + + + + + + + + 0.20 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.30 + + + + + + + + + + + + + 0.35 + + + + + + + + + + + + + 0.40 + + + + surge-tank level (m) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (b) Surge tank: where the filled pipe puts the water + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch2_rapid_fill_pressure_9p9.svg b/docs/figures/svg/workflow_ch2_rapid_fill_pressure_9p9.svg new file mode 100644 index 000000000..ccd6bc0b4 --- /dev/null +++ b/docs/figures/svg/workflow_ch2_rapid_fill_pressure_9p9.svg @@ -0,0 +1,2027 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 12 + + + + + + + + + + + + + 14 + + + + time since the inflow starts (s) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.1 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.3 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.5 + + + + pressure head at x = 9.9 m (m) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The arrival time is the bore speed and the rise is the closure's stiffness. Outside this window + the EXTRAN run reaches 15.1 m at t = 30.7 s — a spurious surcharge excursion forty times the + physical head, absent from both slot closures. + + + The bore arrives and the pipe fills: pressure head at the transducer + + + + + + + + + + measured, Vasconcelos et al. 2006 + + + + + + FV, static slot + + + + + + Dynamic wave, EXTRAN + + + + + + Dynamic wave, slot + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch3_negative_pressure_head_14p1.svg b/docs/figures/svg/workflow_ch3_negative_pressure_head_14p1.svg new file mode 100644 index 000000000..846202d7b --- /dev/null +++ b/docs/figures/svg/workflow_ch3_negative_pressure_head_14p1.svg @@ -0,0 +1,3811 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 35 + + + + + + + + + + + + + 40 + + + + time since the withdrawal starts (s) + + + + + + + + + + + + + + + + + 0.10 + + + + + + + + + + + + + 0.15 + + + + + + + + + + + + + 0.20 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.30 + + + + gauge pressure head at x = 14.1 m (m) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (a) The drawdown, against the measurement + + + + + + + + + + measured + + + + + + FV, TPA + + + + + + FV, static slot — diverged, no solution + + + + + + Dynamic wave, TPA + + + + + + Dynamic wave, slot + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 35 + + + + + + + + + + + + + 40 + + + + time since the withdrawal starts (s) + + + + + + + + + + + + + + 0.00 + + + + + + + + + + + + + 0.05 + + + + + + + + + + + + + 0.10 + + + + + + + + + + + + + 0.15 + + + + + + + + + + + + + 0.20 + + + + + + + + + + + + + 0.25 + + + + + + + + + + + + + 0.30 + + + + gauge pressure head at the summit (m) + + + + + + + + + + + + + + + + + + + + + + + + + + crown of the pipe at the summit + + + the summit empties to zero gauge under FV with TPA + at t = 31.6 s: the column separates + FV, static slot diverged rather than reporting a wrong answer + + + (b) At the summit, where the column is most at risk + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch3_velocity_9p9.svg b/docs/figures/svg/workflow_ch3_velocity_9p9.svg new file mode 100644 index 000000000..9236ee1e4 --- /dev/null +++ b/docs/figures/svg/workflow_ch3_velocity_9p9.svg @@ -0,0 +1,3254 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + + + + + + + + + + 35 + + + + + + + + + + + + + 40 + + + + time since the withdrawal starts (s) + + + + + + + + + + + + + + + + + −0.06 + + + + + + + + + + + + + −0.04 + + + + + + + + + + + + + −0.02 + + + + + + + + + + + + + 0.00 + + + + velocity at x = 9.9 m (m/s) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The same four runs, at the velocity transducer + + + + + + + + + + measured + + + + + + FV, TPA + + + + + + FV, static slot — diverged + + + + + + Dynamic wave, TPA + + + + + + Dynamic wave, slot + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch4_cedar_glen_profile_hgl.svg b/docs/figures/svg/workflow_ch4_cedar_glen_profile_hgl.svg new file mode 100644 index 000000000..7289bd841 --- /dev/null +++ b/docs/figures/svg/workflow_ch4_cedar_glen_profile_hgl.svg @@ -0,0 +1,1024 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + chainage along the trunk (1000 ft) + + + + + + + + + + + + + + + + + 420 + + + + + + + + + + + + + 430 + + + + + + + + + + + + + 440 + + + + + + + + + + + + + 450 + + + + + + + + + + + + + 460 + + + + + + + + + + + + + 470 + + + + head (ft) + + + + + + + + + + + + + + + + + + + + + + + + + 370 virtual junctions chain 387 conduits into one continuous trunk: no manhole, + no storage, no head loss at a splice — the grade line runs through them. + + + The hydraulic grade line along the trunk, at the instant the solvers disagree most + + + + + + + invert + + + + + + crown + + + + + + FV: finite volume + + + + + + DW slot: dynamic wave, Preissmann slot + + + + + + DW EXTRAN: dynamic wave, EXTRAN surcharge + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch4_cedar_glen_worst_node_head.svg b/docs/figures/svg/workflow_ch4_cedar_glen_worst_node_head.svg new file mode 100644 index 000000000..d0c87306c --- /dev/null +++ b/docs/figures/svg/workflow_ch4_cedar_glen_worst_node_head.svg @@ -0,0 +1,1959 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + time (hours) + + + + + + + + + + + + + + + + + 420 + + + + + + + + + + + + + 425 + + + + + + + + + + + + + 430 + + + + + + + + + + + + + 435 + + + + + + + + + + + + + 440 + + + + + + + + + + + + + 445 + + + + + + + + + + + + + 450 + + + + + + + + + + + + + 455 + + + + head at TL0008764 (ft) + + + + + + + + + + + + + + + + + + + The slot run oscillates between the pocket floor and the crest for hours; the other two + hold a smooth recession. Its flow-routing continuity error is -8.3 %. + + + Head at the node where the three routings disagree most + + + + + + + FV — finite volume + + + + + + DW slot — dynamic wave, Preissmann slot + + + + + + DW EXTRAN — dynamic wave, EXTRAN surcharge + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch5_inlet_capture_vs_bypass.svg b/docs/figures/svg/workflow_ch5_inlet_capture_vs_bypass.svg new file mode 100644 index 000000000..08688de46 --- /dev/null +++ b/docs/figures/svg/workflow_ch5_inlet_capture_vs_bypass.svg @@ -0,0 +1,890 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.5 + + + + + + + + + + + + + 2.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 3.0 + + + + time (hours) + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 2 + + + + + + + + + + + + + + + + + + 1 + 0 + − + 1 + + + + + + + + + + + + + + + + + + 1 + 0 + 0 + + + + + + + + + + + + + + + + + + 1 + 0 + 1 + + + + + + flow (cfs) + + + + + + + + + + + + + + + + + + + + + + + + + symmetric log scale below 0.05 cfs. + The street flow falls by three orders + of magnitude across the two inlets. + + + (a) What stays on the street, and what each inlet takes + + + + + + + ST_A — street above the first inlet + + + + + + ST_B — street between the inlets + + + + + + ST_C — street below the inlet junction + + + + + + captured by the conduit-attribute inlet on ST_A + + + + + + captured by the inlet junction IJ1 + + + + + + + + + + + + + + + + + + + ST_A + conduit attribute + 269.3 kgal reached it + + + + + + + + + + + + + IJ1 + inlet junction + 2.7 kgal reached it + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 40 + + + + + + + + + + + + + 60 + + + + + + + + + + + + + 80 + + + + + + + + + + + + + 100 + + + + share of the water reaching the inlet (%) + + + + + + + + + + + + + + + + + + + + + + 99.0 % + 266.6 kgal + + + bypass 1.0 % (2.70 kgal) + + + 89.6 % + 2.4 kgal + + + bypass 10.4 % (0.28 kgal) + + + (b) What each inlet did with what reached it + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch6_mesh_and_coupling.svg b/docs/figures/svg/workflow_ch6_mesh_and_coupling.svg new file mode 100644 index 000000000..8fca00ec3 --- /dev/null +++ b/docs/figures/svg/workflow_ch6_mesh_and_coupling.svg @@ -0,0 +1,346 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + 1 + + + 2 + + + 3 + + + 4 + + + 5 + + + 6 + + + 7 + + + 100.17 to 100.83 m + + + (a) The mesh: bed elevation, boundaries and coupling points + + + + + + + + + + + + + + + + + + + + + + + + + normal flow + + + + + + ts stage + + + + + + rating curve + + + + + + specified flow + + + + + + specified stage + + + + + + + + + + + + vertex coupled to a node + + + + + + + + + + + + cells tagged vault coupled to ST1 + + + + + + + + + + vertex 4 → J1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + 1 + + + 2 + + + 3 + + + 4 + + + 5 + + + 6 + + + 7 + + + 0.00 to 0.67 m + + + cell numbers are the triangle indices the deck uses + + + (b) The maximum depth each cell reached + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch6_momentum_closures_depth.svg b/docs/figures/svg/workflow_ch6_momentum_closures_depth.svg new file mode 100644 index 000000000..0356026ed --- /dev/null +++ b/docs/figures/svg/workflow_ch6_momentum_closures_depth.svg @@ -0,0 +1,514 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 1 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 6 + + + + time (hours) + + + + + + + + + + + + + + + + + 0.5 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.7 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 0.9 + + + + depth in cell 4 (m) + + + + + + + + + + + + + + + + + + + The three closures share every other part of the marcher: the same mesh, the same time + stepping, the same coupling. On this cell they disagree by up to 0.46 m and hold that + disagreement — the closure is not a cosmetic choice. Eight cells under strong boundary + forcing is a feature demonstration, not a validation: see the analytic cases of Hydraulics 9. + + + The same coupled model under the three momentum closures + + + + + + + MOMENTUM_EQUATION LOCAL_INERTIAL — local inertial (the default) + + + + + + MOMENTUM_EQUATION FULL_SWE — full shallow water + + + + + + MOMENTUM_EQUATION DIFFUSIVE_WAVE — diffusive wave + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch7_rain_and_infiltration.svg b/docs/figures/svg/workflow_ch7_rain_and_infiltration.svg new file mode 100644 index 000000000..71d341fb5 --- /dev/null +++ b/docs/figures/svg/workflow_ch7_rain_and_infiltration.svg @@ -0,0 +1,284 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 15.1 + + + 17.6 + + + 7.9 + + + 9.6 + + + 15.4 + + + 17.1 + + + 7.4 + + + 9.9 + + + RG_W + + + RG_E + + + mm/hr in each cell while it rains; the gages read 20 and 5 mm/hr + + + Laplace natural-neighbour weights: every cell takes its own value, + and no cell leaves the range of the gage readings. + + + (a) Rainfall on each cell, interpolated from two gages + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.01 + + + 8.40 + + + 2.91 + + + 1.74 + + + 2.75 + + + 2.07 + + + 7.09 + + + 7.30 + + + LAWN + HORTON + + + LAWN + HORTON + + + PAVED + CONSTANT + + + PAVED + CONSTANT + + + WOODS + GREEN_AMPT + + + WOODS + GREEN_AMPT + + + LAWN + HORTON + + + LAWN + HORTON + + + mm infiltrated over the storm, per cell + + + Three tags, three methods. Cell 0 infiltrated 0.01 mm: it never + held more than 0.06 mm of water, and the sink is ramped off below DRY_DEPTH. + + + (b) Water infiltrated over the storm + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch8_ard_dx_sensitivity.svg b/docs/figures/svg/workflow_ch8_ard_dx_sensitivity.svg new file mode 100644 index 000000000..64daca455 --- /dev/null +++ b/docs/figures/svg/workflow_ch8_ard_dx_sensitivity.svg @@ -0,0 +1,675 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 12 + + + + time (minutes) + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + tracer at J5 (mg/L) + + + + + + + + + + + + + + + + + + + + + + (a) The same front at three cell sizes + + + + + + + TARGET_DX 50 m (2 cells per conduit, 10 in all) + + + + + + TARGET_DX 25 m (4 cells per conduit, 20 in all) + + + + + + TARGET_DX 10 m (10 cells per conduit, 50 in all) + + + + + + + + + + + + + + + + + + + 50 m + + + + + + + + + + + + + 25 m + + + + + + + + + + + + + 10 m + + + + TARGET_DX + + + + + + + + + + + + + + −0.04 + + + + + + + + + + + + + −0.02 + + + + + + + + + + + + + 0.00 + + + + + + + + + + + + + 0.02 + + + + + + + + + + + + + 0.04 + + + + run time (s) + + + + + + + + + + + + + + + + + + + 0.00 s + + + 0.00 s + + + 0.00 s + + + (b) What the refinement costs + + + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch8_tracer_breakthrough_three_engines.svg b/docs/figures/svg/workflow_ch8_tracer_breakthrough_three_engines.svg new file mode 100644 index 000000000..eeab15149 --- /dev/null +++ b/docs/figures/svg/workflow_ch8_tracer_breakthrough_three_engines.svg @@ -0,0 +1,779 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 2.5 + + + + + + + + + + + + + 5.0 + + + + + + + + + + + + + 7.5 + + + + + + + + + + + + + 10.0 + + + + + + + + + + + + + 12.5 + + + + + + + + + + + + + 15.0 + + + + + + + + + + + + + 17.5 + + + + + + + + + + + + + 20.0 + + + + time (minutes) + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + tracer at J5, 400 m downstream (mg/L) + + + + + + + + + + + + + + + + + + + + + + + + + inflow concentration, 10 mg/L + + + half of it: the marker on each curve is the half-rise + + + A step of conservative tracer, reported every 10 s + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + QUALITY_SOLVER EULERIAN_ARD — Eulerian, MUSCL with the van Leer limiter + + + + + + QUALITY_SOLVER LAGRANGIAN — Lagrangian parcels + + + + + + QUALITY_SOLVER LEGACY — legacy CSTR routing + + + + + + + + + + diff --git a/docs/figures/svg/workflow_ch9_arrhenius_rate_from_temperature.svg b/docs/figures/svg/workflow_ch9_arrhenius_rate_from_temperature.svg new file mode 100644 index 000000000..f9492c7d3 --- /dev/null +++ b/docs/figures/svg/workflow_ch9_arrhenius_rate_from_temperature.svg @@ -0,0 +1,1008 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + water temperature TEMP (°C) + + + + + + + + + + + + + + + + + 0.0 + + + + + + + + + + + + + 0.2 + + + + + + + + + + + + + 0.4 + + + + + + + + + + + + + 0.6 + + + + + + + + + + + + + 0.8 + + + + + + + + + + + + + 1.0 + + + + + + + + + + + + + 1.2 + + + + + + + + + + + + + 1.4 + + + + + + + + + + + + + 1.6 + + + + rate multiplier θ^(TEMP − 20) + + + + + + + + + + + + + + + + + + + + + + initial state, 12 °C + + + inflow, 18 °C + + + the fallback, 20 °C + + + kb = 0.30 /hr and θ = 1.07, both from the .rxn file: + the rate changes by 7 % per degree + + + (a) The correction the expression carries + + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + + + + 5 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 15 + + + + + + + + + + + + + 20 + + + + + + + + + + + + + 25 + + + + + + + + + + + + + 30 + + + + time (minutes) + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + 4 + + + + + + + + + + + + + 6 + + + + + + + + + + + + + 8 + + + + + + + + + + + + + 10 + + + + + + + + + + + + + 12 + + + + + + + + + + + + + 14 + + + + + + + + + + + + + 16 + + + + + + + + + + + + + 18 + + + + water temperature (°C) + + + + + + + + + + + + + + + + + + + + + + + + + + + + The line fills from empty, so the first minutes are + a cold start: a nearly dry node carries a temperature + that is not a result. By ten minutes every node is at + the inflow temperature and the multiplier is 0.874. + + + (b) Where this run sits, over its first half hour + + + + + + + J1 + + + + + + J2 + + + + + + J3 + + + + + + J4 + + + + + + J5 + + + + + + + + + + + + + + + + 100 + + + + + + + + + + 200 + + + + + + + + + + 300 + + + + + + + + + + 400 + + + + + + + + + + 500 + + + + half-life of CL2 (minutes) + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/Fig2a.png b/docs/images/Fig2a.png deleted file mode 100644 index 62a7c68f2..000000000 Binary files a/docs/images/Fig2a.png and /dev/null differ diff --git a/docs/images/Fig2b.png b/docs/images/Fig2b.png deleted file mode 100644 index 959242f5f..000000000 Binary files a/docs/images/Fig2b.png and /dev/null differ diff --git a/docs/images/Fig3.png b/docs/images/Fig3.png deleted file mode 100644 index 07833a9ab..000000000 Binary files a/docs/images/Fig3.png and /dev/null differ diff --git a/docs/images/Fig4.png b/docs/images/Fig4.png deleted file mode 100644 index 234bbf189..000000000 Binary files a/docs/images/Fig4.png and /dev/null differ diff --git a/docs/images/Fig5.png b/docs/images/Fig5.png deleted file mode 100644 index 2d7536ff6..000000000 Binary files a/docs/images/Fig5.png and /dev/null differ diff --git a/docs/images/Fig6.png b/docs/images/Fig6.png deleted file mode 100644 index b61664694..000000000 Binary files a/docs/images/Fig6.png and /dev/null differ diff --git a/docs/images/dps_hero_three_pipes.png b/docs/images/dps_hero_three_pipes.png deleted file mode 100644 index c5891518f..000000000 Binary files a/docs/images/dps_hero_three_pipes.png and /dev/null differ diff --git a/docs/images/dps_phat_decay.png b/docs/images/dps_phat_decay.png deleted file mode 100644 index a3a1695b8..000000000 Binary files a/docs/images/dps_phat_decay.png and /dev/null differ diff --git a/docs/manuals/application/application.md b/docs/manuals/application/application.md index bb6b68e82..15cbc0728 100644 --- a/docs/manuals/application/application.md +++ b/docs/manuals/application/application.md @@ -25,41 +25,72 @@ See @ref authors for the complete list of authors and contributors. ## Introduction -The OpenSWMM Application Manual provides a series of worked-out examples that illustrate how to apply OpenSWMM to model common stormwater and drainage system scenarios. This manual complements the @ref user_manual, which explains how to use the program, and the reference manuals (@ref hydrology_reference_manual, @ref hydraulics_reference_manual, @ref quality_reference_manual), which describe the underlying theory and numerical methods. - -The examples progress from simple to more complex applications: - -- Basic drainage system modeling -- Continuous simulation with climate data -- Water quality analysis -- Low impact development (LID) controls -- Combined sewer overflow analysis -- Real-time control strategies - -## Chapter 1 – Site Drainage Design {#app_manual_ch1} - -*Content is under development. This chapter will cover the design of a basic site drainage system using OpenSWMM.* - -## Chapter 2 – Detention Pond Design {#app_manual_ch2} - -*Content is under development. This chapter will cover the design and sizing of a detention pond for flood control.* - -## Chapter 3 – Water Quality Analysis {#app_manual_ch3} - -*Content is under development. This chapter will cover pollutant buildup and washoff modeling for water quality analysis.* - -## Chapter 4 – LID Controls {#app_manual_ch4} - -*Content is under development. This chapter will cover the modeling of low impact development controls such as bio-retention cells, permeable pavement, and rain gardens.* - -## Chapter 5 – Continuous Simulation {#app_manual_ch5} - -*Content is under development. This chapter will cover long-term continuous simulation using historical climate data.* - -## Chapter 6 – Combined Sewer Overflow Analysis {#app_manual_ch6} - -*Content is under development. This chapter will cover the analysis of combined sewer overflows and the evaluation of control strategies.* - -## Chapter 7 – Real-Time Control {#app_manual_ch7} - -*Content is under development. This chapter will cover the implementation of real-time control rules for dynamic operation of drainage system elements.* +This manual answers one question: **which formulation should this model +use, and what changes if you pick another one?** + +OpenSWMM offers more than one representation of nearly every process it +models — four flow routers, four pressurisation closures, three transport +engines, three two-dimensional momentum closures, two groundwater models. +The reference manuals derive them and the Engine Manual gives their +grammar. Neither tells a modeller facing a surcharging trunk sewer which +one to reach for, or what the answer would have been under the other. + +So this manual is built from decision workflows and worked examples rather +than from a tour of the software: + +- @ref application_manual_ch1_choosing "Chapter 1" is six decision + workflows — routing, pressurisation, the 2D surface, transport, age and + heat, groundwater — each ending at the literal `[OPTIONS]` lines that + select a formulation, and a table naming every formulation's keys, + status, theory and worked example. +- Chapters 2 to 11 are worked examples. Each names an in-tree deck under + `docs/figures/decks/`, shows the options that select the formulation, + runs the same model under the alternatives, and reports what changed. + Every figure in them is generated from those runs. +- @ref application_manual_ch12_python_plugins "Chapter 12" runs the same + models from Python and from plugins. +- @ref application_manual_ch13_planned "Chapter 13" is what is coming, and + is careful to present nothing planned as if it worked today. + +Each worked chapter keeps the same five headings — **Problem**, **Deck**, +**Options that select the formulation**, **Results**, **Where to go next** — +so a reader looking for one of them can find it without reading the rest. + +**How to read a result here.** Every comparison in this manual is between +runs of *the same deck* with one group of keys changed. Where two +formulations disagree, the chapter says which one is believed and why — +against a measurement, an analytic solution, or a conservation argument — +rather than presenting the difference as a matter of preference. + +## Where the SWMM 5 Applications Manual topics went + +The EPA SWMM 5 Applications Manual was a tour of the interface built around +one site. That ground is now covered by the GUI tutorials, and this manual +covers the formulations instead. + +| Former chapter | Now | +|---|---| +| Ex. 1 – Site Drainage | @ref tutorial_site_drainage | +| Ex. 2 – Surface Water Quality | @ref application_manual_ch8_transport_engines "Chapter 8: the three transport engines", and @ref quality_ref_ch3_pollutant_buildup for the theory | +| Ex. 3 – Runoff Water Quality | @ref quality_ref_ch4_surface_washoff | +| Ex. 4 – Low Impact Development | @ref engine_manual_sect_LID_USAGE for the grammar and @ref quality_ref_ch6_lid_controls for the theory | +| Ex. 5 – Continuous Simulation | @ref application_manual_ch11_hydrology "Chapter 11: long-term hydrology" | +| Ex. 6 – Detention Pond Design | not yet rewritten; the EPA SWMM 5 Applications Manual remains the reference | +| Ex. 7 – Combined Sewer Overflow | not yet rewritten; the EPA SWMM 5 Applications Manual remains the reference | +| Ex. 8 – Real-Time Control | not yet rewritten; the EPA SWMM 5 Applications Manual remains the reference | + +## Manual Contents + +- @subpage application_manual_ch1_choosing — Chapter 1: Choosing a Formulation +- @subpage application_manual_ch2_filling_pipe — Chapter 2: A Filling Pipe under the Dynamic Wave and Finite-Volume Routers +- @subpage application_manual_ch3_subatmospheric — Chapter 3: A Sub-Atmospheric Transient +- @subpage application_manual_ch4_virtual_junctions — Chapter 4: Virtual Junctions on a Surveyed Trunk +- @subpage application_manual_ch5_street_inlets — Chapter 5: Street Inlets and the Inlet Junction +- @subpage application_manual_ch6_coupled_1d2d — Chapter 6: Building a Coupled One- and Two-Dimensional Model +- @subpage application_manual_ch7_mesh_hydrology — Chapter 7: Rain, Infiltration and Groundwater on the Mesh +- @subpage application_manual_ch8_transport_engines — Chapter 8: The Three Transport Engines +- @subpage application_manual_ch9_msx — Chapter 9: Multi-Species Reactions +- @subpage application_manual_ch10_age_heat — Chapter 10: Water Age and Heat +- @subpage application_manual_ch11_hydrology — Chapter 11: Long-Term Hydrology +- @subpage application_manual_ch12_python_plugins — Chapter 12: Running Models from Python and Plugins +- @subpage application_manual_ch13_planned — Chapter 13: What Is Coming diff --git a/docs/manuals/application/sections/Chapter1-ChoosingAFormulation.md b/docs/manuals/application/sections/Chapter1-ChoosingAFormulation.md new file mode 100644 index 000000000..025d1d363 --- /dev/null +++ b/docs/manuals/application/sections/Chapter1-ChoosingAFormulation.md @@ -0,0 +1,292 @@ +@page application_manual_ch1_choosing Chapter 1: Choosing a Formulation + +OpenSWMM offers more than one representation of nearly every process it +models. This chapter is the map: six decision workflows that take a +modelling question and end at the literal `[OPTIONS]` lines that answer it, +and a closing table that names, for every formulation, the keys that select +it, its status, the theory that describes it and the worked example that +uses it. + +The workflows are drawn as flowcharts you can pan, zoom and click: a +terminal node opens the chapter that documents the formulation it names. +Nothing here decides for you — each branch states the question a modeller +has to answer about their own system, and the cost of the answer. + +**One principle runs through all six.** A default is not a recommendation; +it is the choice that reproduces earlier behaviour. `FLOW_ROUTING DYNWAVE`, +`SURCHARGE_METHOD EXTRAN`, `QUALITY_SOLVER LEGACY` and +`MOMENTUM_EQUATION LOCAL_INERTIAL` are all defaults because changing them +would change existing models' answers, not because they are the best +available representation of every system. A model that never sets a key is +choosing the legacy formulation. + +## 1.1 Which flow router + +The router decides what the momentum equation keeps. Steady flow keeps +nothing and translates hydrographs; kinematic wave keeps the friction +balance and cannot propagate a backwater; dynamic wave keeps the full +one-dimensional momentum equation between nodes; the finite-volume router +discretises the conduit itself and resolves the profile inside it. + + +
+graph TD
+    A[How is the conveyance system driven] --> B{Backwater, surcharge or pressurisation anywhere in the network}
+    B -- no --> C{Is in-pipe attenuation part of the answer}
+    C -- no --> D[FLOW_ROUTING STEADY]
+    C -- yes --> E[FLOW_ROUTING KINWAVE]
+    B -- yes --> F{Do you need the profile inside the conduit: bores, hydraulic jumps, mixed flow}
+    F -- no --> G[FLOW_ROUTING DYNWAVE]
+    F -- yes --> H[FLOW_ROUTING FV with FV_CELL_LENGTH and FV_MIN_CELLS]
+    G --> I{Does the network surcharge against its crowns}
+    I -- yes --> J[Choose a pressurisation closure: section 1.2]
+    H --> J
+
+
+@ref hydraulics_ref_ch2_hydraulic_model "Hydraulics 2: steady flow routing" +@ref hydraulics_ref_ch4_kinematic_wave "Hydraulics 4: kinematic wave" +@ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3: dynamic wave" +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8: explicit finite volume" +@ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" +
+ +*Figure 1-1 Choosing a flow router* + +The cost ladder is real. Steady flow is free, kinematic wave is cheap, +dynamic wave costs an iteration per node per step, and the finite-volume +router costs a substep bounded by the Courant condition on the shortest +cell. @ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" runs the same +filling pipe through the last two and shows what the extra cost buys. + +## 1.2 Which pressurisation closure + +A pipe that fills has no free surface, and the shallow-water equations need +one. Every closure invents a narrow slot above the crown so the equations +keep their form; they differ in what the slot remembers and whether the +pressure may go negative. + + +
+graph TD
+    A[Pipes pressurise] --> B{Which router}
+    B -- dynamic wave --> C{Is sub-atmospheric pressure part of the question}
+    C -- no --> D[SURCHARGE_METHOD EXTRAN or SLOT]
+    C -- yes --> E[SURCHARGE_METHOD TPA with TPA_CELERITY]
+    B -- finite volume --> F{Is sub-atmospheric pressure part of the question}
+    F -- no --> G[FV_PRESSURE_CLOSURE SLOT with FV_SLOT_CELERITY]
+    F -- yes --> H[FV_PRESSURE_CLOSURE TPA]
+    D --> I{Is the surge history itself the answer}
+    I -- yes --> K[SURCHARGE_METHOD DYNAMIC_SLOT with the DPS keys]
+    G --> L[Check the slot's share of stored volume in the report]
+    H --> M[Experimental: read section 8.4.5 before trusting a number]
+
+
+@ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3: EXTRAN and the static slot" +@ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3: the two-component pressure approach" +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8: the tapered static slot" +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8: the TPA closure" +@ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3: the dynamic Preissmann slot" +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8: slot storage accounting" +@ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" +
+ +*Figure 1-2 Choosing a pressurisation closure* + +A slot celerity is an accuracy-cost trade, not a physical constant: the +explicit step is bounded by the celerity, so asking for the acoustic speed +of water collapses the step size. The default of 100 ft/s is the order the +dynamic wave solver's own slot produces. +@ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" runs a siphon where +the two closures disagree about the sign of the pressure. + +## 1.3 Do you need the two-dimensional surface + +A one-dimensional model reports water leaving a node as flooding and loses +sight of it. A mesh keeps it: where it goes, how deep it gets and when it +comes back. That is a different question from how much left, and it costs a +mesh, a solver and a coupling. + + +
+graph TD
+    A[Does water leave the network and spread over the surface] --> B{Is where it goes part of the answer}
+    B -- no --> C[Stay one-dimensional: flooding is reported per node]
+    B -- yes --> D{What drives the mesh}
+    D -- rain on the grid --> E[RAINFALL_MODE NATURAL_NEIGHBOUR with 2D_INFILTRATION rows]
+    D -- spill from the network --> F[2D_VERTEX_NODE_MAP or 2D_TRIANGLE_NODE_MAP]
+    D -- both --> G[Both, with subcatchment coverage ownership checked]
+    E --> H{Which momentum closure}
+    F --> H
+    G --> H
+    H -- shallow and friction dominated --> I[MOMENTUM_EQUATION LOCAL_INERTIAL]
+    H -- transcritical flow or shocks --> J[MOMENTUM_EQUATION FULL_SWE]
+    H -- very flat and slow --> K[MOMENTUM_EQUATION DIFFUSIVE_WAVE]
+
+
+@ref engine_manual_ch4_reports "Engine 4: the flooding report" +@ref hydrology_ref_ch8_mesh_surface "Hydrology 8: rain and infiltration on the mesh" +@ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9: coupling to the network" +@ref quality_ref_ch10_mesh_quality "Quality 10: coverage ownership" +@ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9: the local inertial closure" +@ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9: the full shallow-water closure" +@ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9: the diffusive-wave closure" +
+ +*Figure 1-3 Deciding whether to add the two-dimensional surface, and how to drive it* + +@ref application_manual_ch6_coupled_1d2d "Chapter 6: building a coupled 1D-2D model" builds a coupled model +from an existing network; @ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" drives one with rain rather than spill. The GUI tutorials +@ref tutorial_2d_inundation and @ref tutorial_1d2d_coupling walk the same +ground with a mouse. + +## 1.4 Which transport engine + +All three engines solve the same advection-reaction-dispersion problem and +share the same loads, the same reactions and the same mass-balance ledger. +They differ in how they represent a front. + + +
+graph TD
+    A[Are constituents carried] --> B{What has to be right}
+    B -- totals at the outfall only --> C[QUALITY_SOLVER LEGACY]
+    B -- the shape of a front --> D{Sharp front or long chain of storages}
+    D -- a sharp front, plug flow --> E[QUALITY_SOLVER LAGRANGIAN with MAX_SEGMENTS_PER_LINK]
+    D -- dispersion is the mechanism --> F[QUALITY_SOLVER EULERIAN_ARD with TARGET_DX]
+    F --> G[DISPERSION FISCHER, or a measured VALUE]
+    E --> H[DISPERSION RWPT with RWPT_SEED for a reproducible draw]
+    C --> I[Every engine shares the same loads, reactions and ledger]
+
+
+@ref quality_ref_ch5_transport_treatment "Quality 5: the legacy CSTR routing" +@ref quality_ref_ch7_ard_transport "Quality 7: the Lagrangian engine" +@ref quality_ref_ch7_ard_transport "Quality 7: the Eulerian engine" +@ref quality_ref_ch7_ard_transport "Quality 7: dispersion" +@ref quality_ref_ch7_ard_transport "Quality 7: dispersion under the Lagrangian engine" +
+ +*Figure 1-4 Choosing a transport engine* + +Refining the Eulerian mesh is quadratic: halving `TARGET_DX` doubles both +the cell count and the substep count. +@ref application_manual_ch8_transport_engines "Chapter 8: the three transport engines" puts a tracer +pulse through all three. + +## 1.5 Age, heat and multi-species reactions + +These three ride on the transport engine rather than replacing it. Each is +a separate process component with its own configuration file, and each adds +its own reserved species row. + + +
+graph TD
+    A[Beyond pollutant concentrations] --> B{Which question}
+    B -- how long has this water been in the system --> C[WATER_AGE ON with a WATER_AGE_SOURCES section]
+    B -- what temperature is it --> D[HEAT_TRANSPORT ON with a heat configuration file]
+    B -- species that react with each other --> E[PROCESS_COMPONENTS reactions with a reaction file]
+    D --> F[TEMPERATURE with HUMIDITY, WIND and the radiative sections]
+    E --> G{Do the reactions depend on temperature}
+    G -- yes --> D
+    C --> H[The age row is carried by whichever transport engine is selected]
+
+
+@ref quality_ref_ch9_age_heat "Quality 9: water age" +@ref quality_ref_ch9_age_heat "Quality 9: heat transport" +@ref quality_ref_ch8_msx_reactions "Quality 8: multi-species reactions" +@ref hydrology_ref_ch2_meteorology "Hydrology 2: meteorological forcing" +@ref quality_ref_ch7_ard_transport "Quality 7: the transport engines" +
+ +*Figure 1-5 Water age, heat and reacting species* + +@ref application_manual_ch9_msx "Chapter 9: multi-species reactions" and +@ref application_manual_ch10_age_heat "Chapter 10: water age and heat" configure all three on +one deck. + +## 1.6 Which groundwater representation + +The lumped two-zone aquifer belongs to a subcatchment and exchanges with +one node. The mesh aquifer belongs to the cells and exchanges with every +node standing in them. They are different models of the same water, and +only one of them can own a given parcel of ground. + + +
+graph TD
+    A[Is subsurface exchange part of the question] --> B{Lumped or spatially explicit}
+    B -- one store per subcatchment --> C[AQUIFERS with GROUNDWATER rows]
+    B -- a store per mesh cell --> D[2D_AQUIFER_OPTIONS with 2D_AQUIFER rows]
+    C --> E{Do you need your own flow equation}
+    E -- yes --> F[A GWF section on the subcatchment]
+    D --> G{How thick is the unsaturated column in capillary lengths}
+    G -- thin or unknown --> H[CLOSURE AUTO chooses at initialisation]
+    G -- deep, with profile memory --> I[CLOSURE SIGMA integrates the column]
+    D --> J{Where does mesh infiltration go}
+    J -- to this aquifer --> K[INFIL_DESTINATION AQUIFER_2D]
+
+
+@ref hydrology_ref_ch5_groundwater "Hydrology 5: the two-zone aquifer" +@ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9: the mesh aquifer" +@ref engine_manual_sect_GWF "The GWF section" +@ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9: the AUTO closure rule" +@ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9: the sigma column" +@ref hydrology_ref_ch8_mesh_surface "Hydrology 8: infiltration destinations" +
+ +*Figure 1-6 Choosing a groundwater representation* + +The mesh aquifer's non-Gardner soil laws are \status{Experimental}: their +equilibrium is right and their relaxation rate is the engine's own +generalisation rather than a published result. +@ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" runs one. + +## 1.7 The formulations, their keys and where they are documented + +| Formulation | Selected by | Status | Theory | Worked example | +|---|---|---|---|---| +| Steady flow routing | `FLOW_ROUTING STEADY` | \status{Implemented} | @ref hydraulics_ref_ch2_hydraulic_model | — | +| Kinematic wave | `FLOW_ROUTING KINWAVE` | \status{Implemented} | @ref hydraulics_ref_ch4_kinematic_wave | — | +| Dynamic wave | `FLOW_ROUTING DYNWAVE` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" | +| Explicit finite volume | `FLOW_ROUTING FV` | \status{Implemented} | @ref hydraulics_ref_ch8_finite_volume | @ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" | +| Local time stepping | `FV_LTS` | \status{Implemented} | @ref hydraulics_ref_ch8_finite_volume | @ref application_manual_ch4_virtual_junctions "Chapter 4: virtual junctions on a surveyed trunk" | +| Semi-implicit node continuity | `NODE_CONTINUITY SEMI_IMPLICIT` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | — | +| Anderson acceleration | `ANDERSON_ACCEL` | \status{Implemented} | @ref hydraulics_ref_ch3_anderson | — | +| EXTRAN surcharge | `SURCHARGE_METHOD EXTRAN` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" | +| Static Preissmann slot | `SURCHARGE_METHOD SLOT` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch2_filling_pipe "Chapter 2: a filling pipe under both routers" | +| Dynamic Preissmann slot | `SURCHARGE_METHOD DYNAMIC_SLOT` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | — | +| Two-component pressure, dynamic wave | `SURCHARGE_METHOD TPA` | \status{Experimental} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" | +| Two-component pressure, finite volume | `FV_PRESSURE_CLOSURE TPA` | \status{Experimental} | @ref hydraulics_ref_ch8_finite_volume | @ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" | +| Unsteady friction | `UNSTEADY_FRICTION VITKOVSKY` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" | +| Virtual junctions | `[VIRTUAL_JUNCTIONS]` | \status{Implemented} | @ref hydraulics_ref_ch3_dynamic_wave | @ref application_manual_ch4_virtual_junctions "Chapter 4: virtual junctions on a surveyed trunk" | +| Inlet junctions | `[INLET_JUNCTIONS]` | \status{Implemented} | @ref hydraulics_ref_ch7_advanced_features | @ref application_manual_ch5_street_inlets "Chapter 5: street inlets and inlet junctions" | +| HEC-22 street inlets | `[STREETS]`, `[INLETS]`, `[INLET_USAGE]` | \status{Implemented} | @ref hydraulics_ref_ch7_advanced_features | @ref application_manual_ch5_street_inlets "Chapter 5: street inlets and inlet junctions" | +| 2D local inertial | `MOMENTUM_EQUATION LOCAL_INERTIAL` | \status{Implemented} | @ref hydraulics_ref_ch9_two_dimensional | @ref application_manual_ch6_coupled_1d2d "Chapter 6: building a coupled 1D-2D model" | +| 2D full shallow water | `MOMENTUM_EQUATION FULL_SWE` | \status{Implemented} | @ref hydraulics_ref_ch9_two_dimensional | @ref application_manual_ch6_coupled_1d2d "Chapter 6: building a coupled 1D-2D model" | +| 2D diffusive wave | `MOMENTUM_EQUATION DIFFUSIVE_WAVE` | \status{Implemented} | @ref hydraulics_ref_ch9_two_dimensional | @ref application_manual_ch6_coupled_1d2d "Chapter 6: building a coupled 1D-2D model" | +| Rain on the mesh | `RAINFALL_MODE` | \status{Implemented} | @ref hydrology_ref_ch8_mesh_surface | @ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" | +| Per-cell infiltration | `[2D_INFILTRATION]` | \status{Implemented} | @ref hydrology_ref_ch8_mesh_surface | @ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" | +| Two-zone aquifer | `[AQUIFERS]`, `[GROUNDWATER]` | \status{Implemented} | @ref hydrology_ref_ch5_groundwater | @ref application_manual_ch11_hydrology "Chapter 11: long-term hydrology" | +| Mesh two-layer aquifer | `[2D_AQUIFER]` | \status{Implemented} | @ref hydrology_ref_ch9_mesh_groundwater | @ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" | +| Non-Gardner soil laws | `SOIL_CHAR` | \status{Experimental} | @ref hydrology_ref_ch9_mesh_groundwater | @ref application_manual_ch7_mesh_hydrology "Chapter 7: rain, infiltration and groundwater on the mesh" | +| Modified Green-Ampt | `INFILTRATION MODIFIED_GREEN_AMPT` | \status{Implemented} | @ref hydrology_ref_ch4_infiltration | @ref application_manual_ch11_hydrology "Chapter 11: long-term hydrology" | +| RDII with decay | `[RDII_DECAY]` | \status{Implemented} | @ref hydrology_ref_ch7_rdii | @ref application_manual_ch11_hydrology "Chapter 11: long-term hydrology" | +| Legacy quality routing | `QUALITY_SOLVER LEGACY` | \status{Implemented} | @ref quality_ref_ch5_transport_treatment | @ref application_manual_ch8_transport_engines "Chapter 8: the three transport engines" | +| Eulerian transport | `QUALITY_SOLVER EULERIAN_ARD` | \status{Implemented} | @ref quality_ref_ch7_ard_transport | @ref application_manual_ch8_transport_engines "Chapter 8: the three transport engines" | +| Lagrangian transport | `QUALITY_SOLVER LAGRANGIAN` | \status{Implemented} | @ref quality_ref_ch7_ard_transport | @ref application_manual_ch8_transport_engines "Chapter 8: the three transport engines" | +| Multi-species reactions | `[PROCESS_COMPONENTS]` reactions | \status{Implemented} | @ref quality_ref_ch8_msx_reactions | @ref application_manual_ch9_msx "Chapter 9: multi-species reactions" | +| Water age | `WATER_AGE ON` | \status{Implemented} | @ref quality_ref_ch9_age_heat | @ref application_manual_ch10_age_heat "Chapter 10: water age and heat" | +| Heat transport | `HEAT_TRANSPORT ON` | \status{Implemented} | @ref quality_ref_ch9_age_heat | @ref application_manual_ch10_age_heat "Chapter 10: water age and heat" | +| 2D surface quality | `[2D_COVERAGES]`, `[2D_LOADINGS]` | \status{Implemented} | @ref quality_ref_ch10_mesh_quality | — | +| Groundwater transport | `[GW_*]` sections | \status{Planned} | @ref hydrology_ref_ch10_planned | — | +| Sediment transport | — | \status{Planned} | @ref quality_ref_ch11_planned | — | +| LID as storage nodes | — | \status{Planned} | @ref hydrology_ref_ch10_planned | — | +| Chebyshev cross-sections | — | \status{Planned} | @ref hydraulics_ref_ch10_planned | — | +| 1D GPU backend | `FV_BACKEND` | \status{Planned} | @ref hydraulics_ref_ch10_planned | — | +| 2D Metal backend | `BACKEND` | \status{Planned} | @ref hydraulics_ref_ch10_planned | — | + +*Table 1-1 Every formulation, the keys that select it, and where it is documented* + +Grammar for every key named here is in +@ref engine_manual_ch2_input_file "Chapter 2 of the Engine Manual"; the +GUI's own controls are in @ref manual_simulation_options. diff --git a/docs/manuals/application/sections/Chapter10-WaterAgeAndHeat.md b/docs/manuals/application/sections/Chapter10-WaterAgeAndHeat.md new file mode 100644 index 000000000..8a63022ea --- /dev/null +++ b/docs/manuals/application/sections/Chapter10-WaterAgeAndHeat.md @@ -0,0 +1,130 @@ +@page application_manual_ch10_age_heat Chapter 10: Water Age and Heat + +## Problem + +Two questions a concentration cannot answer. *How long has this water been +in the system?* — which governs disinfectant decay, septicity and the +credibility of a first-flush argument. And *what temperature is it?* — +which governs reaction rates, dissolved oxygen and what the receiving +water gets. + +OpenSWMM answers both with reserved species carried by the same transport +engine that carries the pollutants: `__WATER_AGE__` and +`__TEMPERATURE__`. Each is switched on by one `[OPTIONS]` key and +configured by its own component file. + +## Deck + +Deck: `docs/figures/decks/transport_demo/transport_demo.inp` with +`transport_demo.age` and `transport_demo.heat` + +The five-conduit line of +@ref application_manual_ch8_transport_engines "Chapter 8", starting empty, +filled from t = 0 by a constant 0.2 m³/s inflow at 18 °C while the air +warms from 12 °C to 22 °C over six hours. + +## Options that select the formulation + +\snippet transport_demo/transport_demo.inp options + +Water age needs its source ages: + +``` +[WATER_AGE_SOURCES] +EXTERNAL_INFLOW GLOBAL 0.5 +INITIAL_STATE GLOBAL 6.0 +``` + +Heat needs its sources and the flux modules to run: + +``` +[HEAT_SOURCES] +EXTERNAL_INFLOW GLOBAL 18.0 +INITIAL_STATE GLOBAL 12.0 + +[HEAT_FLUXES] +SURFACE_EXCHANGE ON +RADIATIVE_EXCHANGE ON + +[RADIATIVE_FLUXES] +SHORTWAVE GLOBAL COMPUTED +ALBEDO GLOBAL 0.08 +SKY_VIEW GLOBAL 0.90 +``` + +together with the deck's own meteorology: + +\snippet transport_demo/transport_demo.inp temperature + +The `[SOLAR_RADIATION]` block gives the site's latitude, longitude, time +zone and elevation, which is what `SHORTWAVE COMPUTED` needs to place the +sun. + +## Results: water age + +![Figure 10-1](figures/png/workflow_ch10_water_age_along_line.png) + +*Figure 10-1 Water age along the line as the initial water is flushed out, and the travel-time profile it leaves* + +| Node | Water age at the end of the run | +|---|---| +| J1 | 30.1 min | +| J2 | 31.3 min | +| J3 | 32.5 min | +| J4 | 33.6 min | +| J5 | 34.8 min | + +*Table 10-1 The steady age profile — the declared source age plus travel time* + +**Age is a clock the water carries, not a property of the pipe.** Every +node settles at the age its arriving water was given plus the time it took +to get there: 30 minutes at `J1`, which is the declared +`EXTERNAL_INFLOW 0.5 h`, rising by about 1.2 minutes per 100 m of pipe. +The gradient is the travel time, and it is the number a residence-time +argument actually needs. + +**`INITIAL_STATE 6.0 h` never appears.** The pipes in this deck start +empty, so there is no standing water to carry the initial age. In a model +started from a hot-start file, or one with storage that begins full, that +source dominates the first hours and the flushing of it is the interesting +part of the answer. Declaring an initial age is cheap insurance; the value +only matters if there is water to carry it. + +## Results: heat + +![Figure 10-2](figures/png/workflow_ch10_heat_diurnal.png) + +*Figure 10-2 Water temperature along the line against the air temperature driving it* + +**Here, heat transport is transport.** The water arrives at 18 °C and +stays at 18.00 °C for the whole run while the air climbs to 22 °C. With +surface exchange and radiative exchange both on, a 35-minute residence in +500 m of pipe is far too short for the atmosphere to move the water +temperature measurably. The component is doing its job — it carried the +inlet temperature down the line and mixed it correctly at every node — and +the exchange terms have almost nothing to work with. + +That is the general shape of the result for a conveyance system. Surface +exchange matters where water is slow and exposed: a detention pond, an +open channel, a long shallow reach, an LID surface. It does not matter +much in a 500 m sewer. + +**Read the cold start with suspicion.** The excursions in the first +minutes of Figure 10-2 — down to 2 °C at `J5` — are nodes that are nearly +dry and filling fast. A temperature is the property of a volume of water, +and when that volume is a few litres arriving into an empty pipe, the +number is arithmetic rather than physics. Start the reporting after the +system has filled, or hot-start it. + +## Where to go next + +- @ref quality_ref_ch9_age_heat "Quality 9" — water age and the heat + budget, including every flux module and its parameters +- @ref application_manual_ch9_msx "Chapter 9" — the reaction system that + reads this chapter's temperature +- @ref application_manual_ch8_transport_engines "Chapter 8" — the engine + that carries both reserved rows +- @ref engine_manual_sect_WATER_AGE_SOURCES, + @ref engine_manual_sect_HEAT_SOURCES, + @ref engine_manual_sect_HEAT_FLUXES — the grammar of each section +- @ref manual_climate — the meteorology in the GUI diff --git a/docs/manuals/application/sections/Chapter11-LongTermHydrology.md b/docs/manuals/application/sections/Chapter11-LongTermHydrology.md new file mode 100644 index 000000000..f1ef68980 --- /dev/null +++ b/docs/manuals/application/sections/Chapter11-LongTermHydrology.md @@ -0,0 +1,134 @@ +@page application_manual_ch11_hydrology Chapter 11: Long-Term Hydrology + +## Problem + +A design storm arrives at a model with no history. A continuous +simulation does not: what a storm produces depends on how wet the ground +already is, how cold it has been, and what the last storm left behind. + +Three additions to the hydrology serve that, and this chapter runs the +one whose effect is largest and least obvious — a physics-based recovery +for rainfall-derived inflow and infiltration, where the same storm +produces a different answer in January than in June, in the same model, +with no seasonal parameter table. + +## Deck + +Deck: `docs/figures/decks/hydrology_additions/rdii_decay.inp` + +One sanitary sewer node fed by an RTK unit hydrograph group over a 30-day +January. Two identical six-hour storms fall nineteen days apart. The air +temperature series warms through the month, and the chapter's second run +lowers it below freezing. + +## Options that select the formulation + +The RTK group is the classic one — three response terms, one line each: + +\snippet hydrology_additions/rdii_decay.inp rtk + +What is new is a decay row per response: + +\snippet hydrology_additions/rdii_decay.inp decay + +`k_dep` depletes the abstraction store per inch of rainfall; `k_0` and +`k_T` are the base and thermal recovery rates; `θ_rec` is the temperature +sensitivity; and below `T_freeze` recovery stops entirely. The recovery +needs a temperature source: + +\snippet hydrology_additions/rdii_decay.inp temperature + +**Two unit traps, both real.** `T_ref` and `T_freeze` are in **degrees +Celsius** whatever the project's units are. This is a US deck, so its +temperature series is Fahrenheit and the engine converts before +evaluating the recovery — a `T_freeze` of 0 means freezing, not −18 °C. +And when a decay row is present the `[HYDROGRAPHS]` linear recovery rate +is ignored for that response, while `Dmax` and `D0` still apply, because +they describe the reservoir rather than its dynamics. + +The deck also selects the modified Green-Ampt variant: + +\snippet hydrology_additions/rdii_decay.inp options + +which is the infiltration choice this chapter's kind of model wants. The +original resets the cumulative infiltration whenever the inter-event +timer expires; the modified variant does not, so a long drizzle below the +saturated conductivity counts toward saturating the soil instead of being +forgotten +(@ref hydrology_ref_ch4_infiltration "Hydrology 4, §4.4.5"). + +## Results + +![Figure 11-1](figures/png/workflow_ch11_rdii_decay_vs_linear.png) + +*Figure 11-1 Two identical storms through one RTK group, with and without a physics-based recovery* + +| Run | First storm peak | Second storm peak | Second as a share | +|---|---|---|---| +| Linear recovery, `Drec` = 0 | — | — | no RDII at all | +| Exponential decay, month above freezing | 2.921 cfs | 1.430 cfs | 49 % | +| Exponential decay, month below freezing | 4.505 cfs | 6.821 cfs | 151 % | + +*Table 11-1 The same two storms under three configurations* + +**The second storm is not the first storm.** Above freezing, the +abstraction store recovers over the nineteen dry days but not completely, +and the second storm produces 49 % of the first peak and 64 % of its +volume. An RTK group with a fully recovered linear abstraction would have +produced the same answer twice. + +**Below freezing, the ground stops recovering and the order reverses.** +With the month held under 0 °C, recovery is suppressed outright, so the +store stays depleted, the first storm produces more than it did in the +warm month, and the second produces *more than the first* — 151 %. That +is the seasonal behaviour the section exists for, and it is the sign a +lumped seasonal multiplier usually gets wrong. + +**The third run is a trap worth knowing.** With the decay section removed +this deck reports no RDII at all. Its `[HYDROGRAPHS]` rows carry an 8 in +maximum abstraction with a recovery rate of zero, so the linear model +abstracts both storms entirely and the run is silent about it: the +continuity block simply shows 0.000 for RDII inflow. A model that reports +no RDII is not necessarily a model with none. + +## The other two additions + +**Scale factors, at two levels.** A gage carries a snow catch factor and +a scale factor, and a subcatchment carries its own; the gage factor is +applied inside the gage's reading, and the subcatchment factor after the +conversion to internal units +(@ref hydrology_ref_ch2_meteorology "Hydrology 2, §2.1.6"). The rain-snow +split sits between them, and the catch factor applies on the snow branch +only. For a long run driven by one regional gage, that pair is how a +subcatchment gets its own exposure without a second series. + +**Forcing from outside the deck.** A continuous simulation often needs +inputs a deck cannot hold — a downscaled climate series, an evaporation +estimate computed from other variables, a live feed. Those are prescribed +at runtime: + +```python +from openswmm.engine import Solver + +with Solver("rdii_decay.inp", "rdii_decay.rpt", "rdii_decay.out") as s: + for _ in s.steps(): + s.forcing.climate_evap(daily_pet(s.current_datetime)) +``` + +Prescribed values enter *after* the rain-snow split and are not scaled by +either factor, which is what lets them drive a deck whose gages stay in +place. @ref application_manual_ch12_python_plugins "Chapter 12" and the +[forcing guide](python/guide/forcing.html) carry the full set. + +## Where to go next + +- @ref hydrology_ref_ch7_rdii "Hydrology 7, §7.6" — the exponential + decay model, its equations and every parameter +- @ref hydrology_ref_ch4_infiltration "Hydrology 4, §4.4.5" — the + modified Green-Ampt variant and when it matters +- @ref hydrology_ref_ch2_meteorology "Hydrology 2" — temperature, + humidity, the rain-snow split and the scale factors +- @ref application_manual_ch12_python_plugins "Chapter 12" — running and + forcing a model from Python +- @ref engine_manual_sect_RDII_DECAY, @ref engine_manual_sect_HYDROGRAPHS, + @ref engine_manual_sect_TEMPERATURE — the grammar of each section diff --git a/docs/manuals/application/sections/Chapter12-PythonAndPlugins.md b/docs/manuals/application/sections/Chapter12-PythonAndPlugins.md new file mode 100644 index 000000000..1820848cc --- /dev/null +++ b/docs/manuals/application/sections/Chapter12-PythonAndPlugins.md @@ -0,0 +1,157 @@ +@page application_manual_ch12_python_plugins Chapter 12: Running Models from Python and Plugins + +Everything the other chapters do from a deck and a command line can be done +from Python, and several things can only be done from Python: forcing a +model from a live data source, stepping it under a controller, reading a +result set without writing a file. This chapter is the map from a modelling +task to the interface that performs it. + +Three interfaces exist, and they are layers of one engine rather than +alternatives: + +| Interface | What it is | Reach for it when | +|---|---|---| +| The command line | `openswmm model.inp model.rpt model.out` | the deck is the whole experiment | +| The Python package | `openswmm.engine`, a Cython binding over the C API | the run is one step in a script: sweeps, forcing, post-processing | +| A plugin | a shared library the engine loads and calls back | the behaviour belongs *inside* every run, including runs someone else starts | + +## When the command line is enough + +A deck plus a report is a complete experiment, and the runner that produced +every simulated figure in this manual is exactly that: +`scripts/build_manual_figures.py` upserts a few `[OPTIONS]` lines into a +copy of a deck, runs the binary, and reads the report and the binary output. +Nothing in this manual's comparisons needs more. + +Two things the command line cannot do: change a model while it is running, +and see a result before the run ends. + +## Driving a run from Python + +The package exposes the engine as a solver you open, step and close. The +canonical shape is the context manager, which guarantees the close: + +```python +from openswmm.engine import Solver + +with Solver("model.inp", "model.rpt", "model.out") as solver: + for elapsed in solver.steps(): # a timedelta since the start + pass + print(solver.routing_error()) +``` + +`steps()` advances one routing step per iteration and yields the elapsed +time as a `timedelta`, so a controller reads state, decides, writes back +and continues. `step()` is the same thing one step at a time. The routing +error is a **fraction**, not a percentage — a gate that asserts it is below +0.5 is asserting 50 %, not half a percent. + +The guide pages carry the worked forms, and each is a short page: + +| Task | Guide page | +|---|---| +| Install the package | [install](python/guide/install.html) | +| The first run, end to end | [quickstart](python/guide/quickstart.html) | +| Open, step, close, and the state machine | [solver](python/guide/solver.html) | +| Build a model with no input file | [model_builder](python/guide/model_builder.html) | +| Prescribe rainfall, evaporation and temperature at runtime | [forcing](python/guide/forcing.html) | +| Read nodes, links and subcatchments while stepping | [nodes](python/guide/nodes.html), [links](python/guide/links.html), [subcatchments](python/guide/subcatchments.html) | +| Cross-section geometry without a model | [xsect_geometry](python/guide/xsect_geometry.html) | +| The 2D surface: mesh, depths, velocities | [2d](python/guide/2d.html) | +| Water quality, reactions, age and heat | [quality](python/guide/quality.html), [reactions](python/guide/reactions.html), [water_age](python/guide/water_age.html), [heat](python/guide/heat.html) | +| Process components from Python | [process_components](python/guide/process_components.html) | +| Read a binary output file after the run | [output_reader](python/guide/output_reader.html) | +| Hot start files | [hotstart](python/guide/hotstart.html) | +| Mass balance and statistics | [massbalance](python/guide/massbalance.html), [statistics](python/guide/statistics.html) | +| Plot results | [plotting](python/guide/plotting.html) | +| Read and write GeoPackage | [geopackage](python/guide/geopackage.html) | + +The full class and method reference is the +[Python Bindings API Reference](python/index.html). + +**A caution about the state machine.** A solver is past OPENED as soon as +the context manager enters; several setters are refused after that point +because the engine has already resolved the model. The +[solver](python/guide/solver.html) page lists which, and +@ref engine_manual_ch5_api "Chapter 5 of the Engine Manual" gives the same +sequence for the C API, where the states are explicit. + +## Three things worth doing from Python + +**A parameter sweep that never writes a deck.** The model builder makes the +network in memory, so a sweep over a design variable is a loop rather than a +directory of near-identical files. The comparisons in this manual are the +same idea run from the deck side: upsert the keys, run, read. + +**Forcing from outside the model.** Prescribed rainfall, evaporation and +temperature enter *after* the rain-snow split of +@ref hydrology_ref_ch2_meteorology "Hydrology 2, §2.1.6" — override replaces +the gage's value and addition augments it, and neither is scaled by the +gage or subcatchment factors. That is what lets a live feed or a downscaled +climate series drive an existing deck with its gages left in place. + +**Reading the 2D surface without the file.** A coupled run's mesh state is +addressable while it steps: depth, velocity and species per cell. The +result file is written for later analysis, not required for it, and it is +not readable while the run is in progress — there is no flush and no +single-writer-multiple-reader mode. + +## When the behaviour belongs in a plugin + +A plugin is loaded by the engine and called back during the run, so it acts +on every run of a model rather than on the runs a particular script starts. +The engine ships built-in plugins for input, output, reporting and state IO, +and a project names extra ones in `[PLUGINS]` +(@ref engine_manual_sect_PLUGINS). Discovery, version resolution and the +callback sequence are in +@ref engine_manual_ch5_plugins "Chapter 5 of the Engine Manual, §5.8". + +The rule of thumb: + +- A **process component** adds physics — reactions, heat, water age, + transport — and is configured from a file the deck names in + `[PROCESS_COMPONENTS]` (@ref engine_manual_sect_PROCESS_COMPONENTS). + @ref application_manual_ch9_msx "Chapter 9: multi-species reactions" configures one. +- An **output or report plugin** changes what a run writes without changing + what it computes. +- A **solver plugin** replaces a kernel. The 2D backends are selected this + way; a backend that a build does not carry is refused at open rather than + silently ignored. + +## Where to go next + +- @ref engine_manual_ch5_api "Engine Manual, Chapter 5" — the C API, the + state machine, user flags, extension options and the plugin interface +- @ref manual_running — running from the GUI +- @ref manual_plugins — managing plugins from the GUI +- @ref application_manual_ch13_planned "Chapter 13" — what is coming + + +## Authoring and observing the extended Python API + +Open a solver explicitly before authoring: the solver context manager starts +simulation, so editing-only tables must be changed before entering the runtime +state. `solver.transport` exposes dispersion configuration and authored rows; +`solver.transport_matrix` reports which process classes are available in each +domain, with reasons when unavailable. + +`solver.surface2d.groundwater` supplies aquifer rows, node exchange, SI state +arrays and water/species ledgers. Its `.transport` view edits groundwater +parameters, sorption, initial quality, boundary quality and source terms. +`solver.surface2d.quality` edits land-use coverage, initial buildup and curb +length. Table snapshots are immutable; arrays are owned copies. Aquifer +hydrology authoring uses project units while runtime hydrology uses SI. See the +[groundwater guide](python/guide/groundwater.html) and +[surface-quality guide](python/guide/surface_quality.html) for each field's units. + +`ModelEditor.delete_nodes`, `.delete_links`, `.delete_subcatchments` and +`.delete_gages` validate all pre-edit indices before a batch deletion and return +cascade impacts. Reacquire element views after structural edits. Views retain +their solver and raise Python exceptions after it closes or is destroyed. + +`OutputReader(path, live=True)` can read complete periods during a run; +`refresh()` updates the period count and timestamp cache. Staged serialization +uses `solver.write_staged(final_path, mapper)`; publication and rollback remain +the caller's responsibility. See the +[editing and live-output guide](python/guide/binding_updates.html) and +[native-call safety guide](python/guide/native_safety.html) for the contracts. diff --git a/docs/manuals/application/sections/Chapter13-WhatIsComing.md b/docs/manuals/application/sections/Chapter13-WhatIsComing.md new file mode 100644 index 000000000..406e367b7 --- /dev/null +++ b/docs/manuals/application/sections/Chapter13-WhatIsComing.md @@ -0,0 +1,96 @@ +@page application_manual_ch13_planned Chapter 13: What Is Coming + +Everything in this chapter is \status{Planned}: designed, recorded, and not +in this release. No key named here does anything useful today, and where a +section is parsed but inert this chapter says so and quotes the warning the +engine prints. The reference manuals' planned-formulation chapters carry the +detail; this is the modeller's-eye summary of what would change. + +| Formulation | What it would let a model do | Where the design is recorded | +|---|---|---| +| Groundwater transport | Carry species and heat in the saturated zone, and exchange them with the surface and the network | @ref hydrology_ref_ch10_planned, @ref quality_ref_ch11_planned | +| Sediment transport | Erode, carry and deposit solids rather than treating them as a dissolved pollutant | @ref quality_ref_ch11_planned | +| LID controls as storage nodes | Give an LID unit its own node, so it can be routed to, controlled, and reported like any other storage | @ref hydrology_ref_ch10_planned | +| Chebyshev cross-sections | Fit an arbitrary measured section with a spectral expansion instead of a lookup table | @ref hydraulics_ref_ch10_planned | +| Implicit finite volume | Remove the Courant bound on the 1D finite-volume step for slow, long runs | @ref hydraulics_ref_ch10_planned | +| 1D GPU backends | Run the 1D finite-volume solver on the same accelerators the 2D marcher already uses | @ref hydraulics_ref_ch10_planned | +| 2D Metal backend | Run the 2D marcher on Apple GPUs | @ref hydraulics_ref_ch10_planned | +| Per-element heat attributes | Vary the heat exchange parameters element by element rather than globally | @ref quality_ref_ch11_planned | + +*Table 13-1 Planned formulations, and what each would change for a model* + +## 13.1 Groundwater transport + +The six `[GW_*]` sections parse, validate, round-trip through the writer and +are editable through the C API. They compute nothing. A deck that carries +them runs, and the engine says why: + +> Groundwater transport sections are parsed but inert in this release. + +What the design would add: advection and dispersion of species in the +saturated zone of the mesh aquifer of +@ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9", with sorption and +retardation, heat carried on the same sweep, and exchange with both the +surface and the nodes standing in the cells. Until then, a model that needs +subsurface water quality has no representation of it, and a model that +carries the sections gets the warning and nothing else. + +## 13.2 Sediment transport + +Solids are transported today as a pollutant: a concentration that advects, +disperses and decays. Sediment would add what a concentration cannot carry — +a bed, a critical shear stress, deposition and re-entrainment, and the +feedback from a changing bed to the hydraulics. There is no design record +beyond the roadmap entry, which means this one is further out than the +others in this table. + +## 13.3 LID controls as storage nodes + +An LID unit is a layered column inside its subcatchment. It cannot be routed +to, controlled by a rule, or reported like a node, and two subcatchments +cannot share one. The redesign gives a unit its own node, so an underdrain +becomes a link and a control rule can throttle it. Layered units would stay: +the two representations answer different questions, and the existing one is +right for a rain garden on one subcatchment. + +## 13.4 Cross-sections, solvers and backends + +**Chebyshev sections** would fit a measured irregular section with a +spectral expansion, replacing the transect lookup with a smooth function +whose derivatives are continuous — which matters for the Riemann solver of +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8", where a kink in +\f$dA/dh\f$ becomes a spurious reflection. + +**An implicit finite-volume solver** would remove the Courant bound and let +a long continuous simulation take hydrological steps through quiescent +periods. The explicit solver's cost is bounded by the shortest cell in the +model whatever the flow is doing. + +**GPU backends** exist for the 2D marcher on CUDA, HIP and SYCL. The 1D +finite-volume solver has the option surface and no kernel; Metal is +designed and not built. A backend a build does not carry is refused at open, +so a deck naming one fails loudly rather than running on the CPU and +reporting a speed-up that never happened. + +## 13.5 Reading this chapter against the engine + +Three rules govern how planned work appears in OpenSWMM's documentation, and +they are worth knowing when reading any of the manuals: + +1. A section that is parsed but inert says so in the Engine Manual's + grammar entry, prints a warning at runtime, and carries + \status{Planned} wherever it is listed. +2. A formulation that ships but is not yet validated carries + \status{Experimental}, names what would license it, and says which + alternative to prefer meanwhile. +3. A key that is parsed and ignored carries \status{Retired} and is listed + with the retired keys, not quietly dropped: an old deck keeps running, + and the report says the key had no effect. + +## Where to go next + +- @ref hydraulics_ref_ch10_planned — planned and retired hydraulics +- @ref hydrology_ref_ch10_planned — planned hydrology +- @ref quality_ref_ch11_planned — planned water quality +- `ROADMAP.md` in the source tree — the engineering roadmap these entries + summarise diff --git a/docs/manuals/application/sections/Chapter2-FillingPipeDwVsFv.md b/docs/manuals/application/sections/Chapter2-FillingPipeDwVsFv.md new file mode 100644 index 000000000..1ca21200e --- /dev/null +++ b/docs/manuals/application/sections/Chapter2-FillingPipeDwVsFv.md @@ -0,0 +1,130 @@ +@page application_manual_ch2_filling_pipe Chapter 2: A Filling Pipe under the Dynamic Wave and Finite-Volume Routers + +## Problem + +A pipe that is running part full begins to fill. A bore travels down it, +the pipe pressurises behind the front, and whatever is at the downstream +end — a manhole, a shaft, a surge tank — takes the water and oscillates. + +A modeller has to decide how much of that to represent. The dynamic wave +router carries one flow per conduit, so the bore is not a front it can +place: the conduit fills as a whole. The finite-volume router discretises +the conduit and the front is a cell boundary that moves. The question this +chapter answers is what the difference is worth, measured against a +laboratory pipe where the answer is known. + +## Deck + +Deck: `docs/figures/decks/rapid_fill/rapid_fill.inp` + +The rapid-filling experiment of Vasconcelos, Wright and Roe (2006): an +acrylic pipe 14.33 m long and 94 mm in diameter, horizontal, initially at +rest and 78 % full. A fill box feeds the upstream end and a 0.19 m surge +tank closes the downstream one. At t = 0 an inflow of 3.1 L/s is admitted, +and pressure at x = 9.9 m, velocity at the same station and the surge-tank +level were all measured. The deck carries the paper's own numerics: 400 +cells, Courant 0.95, Manning n = 0.012, acoustic celerity 25 m/s. + +The two gauge stations are **virtual junctions** — sealed splices with no +storage, transparent to the solution — so the deck also exercises the +virtual-junction composition. `docs/figures/decks/rapid_fill/provenance.md` +records where the deck and the three digitised measurement series came +from. + +## Options that select the formulation + +The deck as committed is the finite-volume router with its static slot: + +``` +[OPTIONS] +FLOW_ROUTING FV +FV_CELL_LENGTH 0.036 +FV_MIN_CELLS 4 +FV_SLOT_CELERITY 25 +``` + +The comparison runs change nothing else. The dynamic wave variants are + +``` +FLOW_ROUTING DYNWAVE +SURCHARGE_METHOD EXTRAN ; and, in the third run, SLOT +``` + +`FV_CELL_LENGTH` is the target cell length and `FV_MIN_CELLS` the floor; +0.036 m over 14.33 m is the paper's 400 cells. `FV_SLOT_CELERITY` is the +pressurised wave speed the slot is sized for — the accuracy-cost trade of +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8, §8.4.1", since the +explicit step is bounded by \f$\Delta x / (|v| + c)\f$. + +Two warnings are expected and correct: `INERTIAL_DAMPING` and +`NORMAL_FLOW_LIMITED` are dynamic wave keys, and the engine says so rather +than ignoring them silently when the deck runs under `FV`. + +## Results + +![Figure 2-1](figures/png/workflow_ch2_rapid_fill_pressure_9p9.png) + +*Figure 2-1 Pressure head at x = 9.9 m in the rapid-filling experiment, measured and under three routing choices* + +![Figure 2-2](figures/png/workflow_ch2_rapid_fill_front.png) + +*Figure 2-2 Velocity at the transducer and surge-tank level, measured and under the same three choices* + +| | Front arrival at 9.9 m | Surge-tank first peak | Routing continuity error | Run time | +|---|---|---|---|---| +| Measured | 6.26 s | 0.403 m at 14.8 s | — | — | +| `FV`, static slot | 5.80 s | 0.427 m at 13.8 s | −0.000 % | 17.3 s | +| `DYNWAVE`, slot | 8.75 s | 0.389 m at 19.6 s | 1.147 % | 0.1 s | +| `DYNWAVE`, EXTRAN | 10.90 s | 0.267 m at 19.5 s | 5.655 % | 0.2 s | + +*Table 2-1 What each formulation reproduces, against the laboratory measurement* + +Arrival is the first time the head at the transducer passes 0.10 m; the +surge-tank peak is the first maximum within 25 s. Every number comes from +the runs this page's figures were drawn from. + +**The front.** The finite-volume run puts the bore at the transducer half a +second early and reproduces the whole rise; both dynamic wave runs are late +by 2.5 s and 4.6 s. That is not a calibration difference. The dynamic wave +router has no representation of a front inside a conduit, so the filling of +the pipe is spread over the conduit's own storage rather than propagated; +the arrival it reports is the arrival of a flow, not of a bore. + +**The oscillation.** The surge tank is the honest test of what happens +after filling, because its level integrates everything the pipe did. The +finite-volume run peaks 0.024 m high and one second early; the dynamic wave +runs peak five seconds late, and the EXTRAN run loses a third of the +amplitude. + +**The velocity trace is where EXTRAN fails visibly.** Panel (a) of +Figure 2-2 shows it oscillating between ±0.2 m/s from about 13 s onward, +at the reporting interval — numerical chatter, not a physical signal. The +same run's flow-routing continuity error is 5.655 %, against −0.000 % for +the finite-volume run. Outside the plotted window it reaches 15.1 m of head +at the transducer, forty times the physical value. + +**What it costs.** Seventeen seconds against a fifth of a second, on a deck +of three conduits. The finite-volume router's step is bounded by the +Courant condition on the shortest cell, and this deck is 400 cells of +36 mm; the ratio is the price of resolving the front. For a network model +the ratio is smaller — cells are metres, not centimetres, and local time +stepping (@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8, §8.5.6") +keeps the quiet parts of the network off the fine clock. + +**Which one to believe.** Here, the finite-volume run, because a laboratory +measurement says so. Away from a measurement, the discriminator is +continuity: a routing error of 5.655 % on a three-pipe deck with no +outfall losses is the solver reporting that it could not close its own +books. + +## Where to go next + +- @ref application_manual_ch3_subatmospheric "Chapter 3: a sub-atmospheric transient" — the same pipeline + with the centre raised and drained, where the static slot does not + produce a wrong answer but no answer at all +- @ref hydraulics_ref_ch8_finite_volume "Hydraulics 8" — the finite-volume + scheme, its slot closure and its time stepping +- @ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3" — the dynamic wave + solver and its four surcharge methods +- @ref engine_manual_sect_OPTIONS — the grammar of every key named here +- @ref manual_simulation_options — the same choices in the GUI diff --git a/docs/manuals/application/sections/Chapter3-SubAtmosphericSlotVsTpa.md b/docs/manuals/application/sections/Chapter3-SubAtmosphericSlotVsTpa.md new file mode 100644 index 000000000..58ae84732 --- /dev/null +++ b/docs/manuals/application/sections/Chapter3-SubAtmosphericSlotVsTpa.md @@ -0,0 +1,130 @@ +@page application_manual_ch3_subatmospheric Chapter 3: A Sub-Atmospheric Transient — the Slot against the Two-Component Pressure Approach + +## Problem + +A full pipe over a summit, drawn down from one end, develops pressure +*below* atmospheric at the high point. Inverted siphons do it, pumped +mains do it when a pump trips, and a sewer does it whenever a downstream +control drains a surcharged reach faster than the upstream end can follow. + +A Preissmann slot cannot represent that. The slot is a narrow shaft added +above the crown so the free-surface equations keep their form when the +pipe fills; it is open to the atmosphere by construction, so the water +surface inside it cannot describe a pressure lower than the air above it. +The two-component pressure approach carries the pressurised part of the +state as a second component instead, and that component is free to go +negative. + +This chapter runs the experiment that separates them. + +## Deck + +Deck: `docs/figures/decks/negative_pressure/negative_pressure.inp` + +The pipeline of *Chapter 2* with its centre raised 0.15 m — 2 % up to the +summit, 2 % down from it — both ends at elevation zero. The system starts +full and at rest, filled to 0.30 m at the upstream box, which puts the +summit's crown under water. At t = 0 a siphon withdrawal of 0.45 L/s +starts, the upstream level falls, and the pressure at the summit follows +it down. + +The gauge stations are **sealed junctions** (`SUR_DEPTH 30`), not plain +junctions: a plain junction is an atmosphere contact and would vent the +pressurised state — right for a manhole, wrong for a transducer tapping on +a sealed pipeline. The comparison window ends at 40 s, where an air cavity +intrudes in the laboratory and the single-phase model stops being a model +of the experiment. + +## Options that select the formulation + +``` +[OPTIONS] +FLOW_ROUTING FV +FV_PRESSURE_CLOSURE TPA ; SLOT in the second run +FV_SLOT_CELERITY 300 ; the pipeline's measured acoustic celerity +REPORT_SIGNED_HEADS YES +``` + +and, for the dynamic wave runs, + +``` +FLOW_ROUTING DYNWAVE +SURCHARGE_METHOD TPA ; SLOT in the fourth run +TPA_CELERITY 300 +``` + +`REPORT_SIGNED_HEADS` is what lets the report carry a head below the pipe +invert rather than clamping it. Without it the interesting part of the +answer is silently truncated at zero. + +## Results + +![Figure 3-1](figures/png/workflow_ch3_negative_pressure_head_14p1.png) + +*Figure 3-1 Piezometric head at x = 14.1 m and velocity at x = 9.9 m in the siphon experiment, under both closures on both routers* + +![Figure 3-2](figures/png/workflow_ch3_velocity_9p9.png) + +*Figure 3-2 The same four runs at the velocity transducer, where the closures diverge after the drawdown* + +| | Gauge head at x = 14.1 m, t = 40 s | Routing continuity error | +|---|---|---| +| Measured | 0.099 m | — | +| `FV`, TPA | 0.103 m | −0.000 % | +| `FV`, static slot | **diverged** — ERROR 14 in the first substeps | — | +| `DYNWAVE`, TPA | 0.232 m | −10.434 % | +| `DYNWAVE`, slot | 0.233 m | −11.118 % | + +*Table 3-1 The drawdown each formulation reports, against the measurement* + +**The static slot does not produce a wrong answer here; it produces no +answer.** Under the finite-volume router with `FV_PRESSURE_CLOSURE SLOT` +the run stops in the first substeps with ERROR 14, a depth magnitude of +13 000 ft in the conduit downstream of the summit. That is the right +behaviour for a closure asked to represent a state it has no +representation of: the slot must keep a free surface, the state has none, +and the solution runs away. A closure that quietly returned zero would be +worse. + +**With the right closure, the finite-volume run is the experiment.** It +tracks the measured drawdown through all four of its stages and ends +within 4 mm of the measurement after 40 s, with continuity at −0.000 %. +Panel (b) of Figure 3-1 shows why the summit is the interesting station: +the acoustic oscillation at 300 m/s is visible and decaying, and the +summit reaches zero gauge pressure at t = 31.6 s — the column separating, +which is the physical event the experiment was built to produce. + +**The dynamic wave runs fail differently, and quietly.** Both closures +give the same answer to within a millimetre, and both drain the system +less than half as fast as the measurement: 0.232 m against 0.099 m at +40 s. TPA does not rescue the dynamic wave router here, because the +problem is not the pressurisation closure — it is that a single flow per +conduit cannot carry the acoustic wave that governs how fast a full pipe +responds. The continuity errors, −10.4 % and −11.1 %, say so plainly: +these runs are not conserving the water they were given. + +**The velocity trace is the same story in a different variable.** +Figure 3-2: the finite-volume run follows the measured oscillation in +phase and in amplitude; the dynamic wave runs overshoot by roughly a +factor of two and drift out of phase by five seconds over the window. + +**One caution.** `FV_PRESSURE_CLOSURE TPA` is \status{Experimental}, and +this chapter is exactly the case it exists for. Its caveats — the +integrator choice, the pinned cases, the measured behaviour under +different acoustic celerities — are in +@ref hydraulics_ref_ch8_finite_volume "Hydraulics 8, §8.4.5", and they +should be read before a TPA result is trusted on a system that is not +this one. + +## Where to go next + +- @ref application_manual_ch2_filling_pipe "Chapter 2" — the same pipeline + filling rather than draining, where the static slot is the right choice +- @ref hydraulics_ref_ch8_finite_volume "Hydraulics 8, §8.4.5" — the TPA + closure, its flag transitions and its recorded caveats +- @ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3, §3.3.11" — TPA under + the dynamic wave router +- @ref hydraulics_ref_ch10_planned "Hydraulics 10, §10.7" — the + high-celerity filling divergence, which this closure carried until + 2026-09-12 and no longer does +- @ref engine_manual_sect_OPTIONS — the grammar of every key named here diff --git a/docs/manuals/application/sections/Chapter4-VirtualJunctions.md b/docs/manuals/application/sections/Chapter4-VirtualJunctions.md new file mode 100644 index 000000000..78232882d --- /dev/null +++ b/docs/manuals/application/sections/Chapter4-VirtualJunctions.md @@ -0,0 +1,127 @@ +@page application_manual_ch4_virtual_junctions Chapter 4: Virtual Junctions on a Surveyed Trunk + +## Problem + +A network built from survey or GIS data arrives as hundreds of short +segments. The segments are not separate pipes — they are one pipe, +described piecewise, with a point every time the survey recorded one. +Modelling each break as a junction invents a manhole that is not there: +a node with storage, a place for water to pond, an entrance and exit +loss, and one more equation to solve. + +A **virtual junction** is the alternative: a splice with no storage that +transmits momentum, so the solver sees one continuous conduit through it. +This chapter builds a trunk out of 370 of them and asks what the routing +choice does to the answer. + +## Deck + +Decks: `docs/figures/decks/cedar_glen/cedar_glen_fv.inp`, +`cedar_glen_dw.inp`, `cedar_glen_dw_extran.inp` + +Cedar Glen to FRS, a synthetic raw-water conveyance generated by +`generate_model.py` in the same folder: 387 conduits, of which 370 are +joined by virtual junctions and 17 by real ones, a 25 900 ft trunk of +72, 78 and 90 in pipe with two lateral branches, gentle slopes of +0.10 to 0.30 %, and a flow-regulating basin with a service orifice and an +elevated overflow. + +The interesting geometry is in the middle: a **double-pocket reach** +between the two tie-ins, where the invert falls into a pocket at 442 ft, +rises over a 1.55 % adverse riser to a crest at 455 ft, falls into a +second pocket, and lifts again. That reach pressurises at each surge +peak, which is the point of the model — a valved-conveyance grade is +where routing choices stop agreeing. + +The forcing is a 24-hour double surge-and-drain hydrograph, the second +peak at 85 % of the first. Every coordinate, elevation and name is +generated from a seeded script; nothing comes from any client data. + +## Options that select the formulation + +The three decks differ only in their routing options. The splices are +the same in all three: + +``` +[VIRTUAL_JUNCTIONS] +;;Name Elev Rim +TU0000124 467.6278 11.0000 +TU0000243 467.2712 11.0000 +... +``` + +and the routing is + +``` +FLOW_ROUTING FV ; cedar_glen_fv.inp +FLOW_ROUTING DYNWAVE ; cedar_glen_dw.inp, with SURCHARGE_METHOD SLOT +FLOW_ROUTING DYNWAVE ; cedar_glen_dw_extran.inp, with EXTRAN +``` + +A virtual junction is subject to the rules of its kind: exactly two +conduits, the same cross-section on both, zero offsets. Under the +finite-volume router the splice is transparent by construction — the +cells either side are neighbours across a face. Under dynamic wave it is +a node the solver is told not to give storage to. + +## Results + +![Figure 4-1](figures/png/workflow_ch4_cedar_glen_profile_hgl.png) + +*Figure 4-1 The hydraulic grade line along a trunk chained by virtual junctions, under three routings* + +![Figure 4-2](figures/png/workflow_ch4_cedar_glen_worst_node_head.png) + +*Figure 4-2 Head at the node where the three routings disagree most, with each run's cost* + +| Deck | Flow-routing continuity error | Run time | +|---|---|---| +| `cedar_glen_fv.inp` | 0.000 % | 102 s | +| `cedar_glen_dw.inp` (slot) | **−8.285 %** | 29 s | +| `cedar_glen_dw_extran.inp` | −0.026 % | 9 s | + +*Table 4-1 What each routing cost, and what it conserved* + +**The grade line runs through the splices.** Figure 4-1 is 260 trunk +nodes plotted at one instant, and there is no step at any of them. That +is the whole claim of a virtual junction, and it is worth checking on a +real model by eye: a sawtooth in a profile like this one is the signature +of accidental junctions with storage. + +**Two of the three routings agree; one does not.** The finite-volume and +EXTRAN runs sit on top of each other over most of the trunk, both +pressurising the flat reach to about 457 ft. The Preissmann-slot run +disagrees, and Figure 4-2 shows how: at the node 25 800 ft along, near +the basin, it oscillates between 420 and 455 ft for hours at a time while +the other two hold a smooth recession. + +**Continuity says which to believe.** The slot run's flow-routing +continuity error is −8.285 %: it lost more than one part in twelve of the +water it was given. The finite-volume run's is 0.000 % and EXTRAN's is +−0.026 %. On this network the slot's surcharge accounting is the problem, +not the virtual junctions — and the error is large enough that no +calibration of the deck would rescue it. + +**The cost.** 102 seconds against 29 and 9, for a 387-conduit model over +24 hours. The finite-volume router pays for resolving the pressurisation +front in the pocket reach; local time stepping is what keeps that from +being far worse, since the trunk's short survey segments would otherwise +put the whole model on the shortest cell's clock +(@ref hydraulics_ref_ch8_lts "Hydraulics 8, §8.5.6"). + +**What to take from this.** On a conveyance like this one — long, gently +sloped, pressurising in pockets — the choice that matters most is not +whether to use virtual junctions, which is settled by how the network was +surveyed, but the surcharge accounting. Read the continuity error first, +then the profile, then the cost. + +## Where to go next + +- @ref hydraulics_ref_ch3_dynamic_wave "Hydraulics 3, §3.3.10" — virtual + junctions under the dynamic wave router, and their rules +- @ref hydraulics_ref_ch8_finite_volume "Hydraulics 8, §8.6.2" — how the + finite-volume router splices cells across one +- @ref application_manual_ch2_filling_pipe "Chapter 2" — the same + surcharge question on a laboratory pipe, against a measurement +- @ref engine_manual_sect_VIRTUAL_JUNCTIONS — the grammar +- @ref manual_hydraulics — creating one in the GUI diff --git a/docs/manuals/application/sections/Chapter5-StreetInlets.md b/docs/manuals/application/sections/Chapter5-StreetInlets.md new file mode 100644 index 000000000..15ba2ba3f --- /dev/null +++ b/docs/manuals/application/sections/Chapter5-StreetInlets.md @@ -0,0 +1,119 @@ +@page application_manual_ch5_street_inlets Chapter 5: Street Inlets and the Inlet Junction + +## Problem + +Water running down a street reaches a grate or a curb opening, some of it +goes into the sewer, and the rest carries on to the next inlet. A model +has to say how much goes in — which is a HEC-22 calculation from the +spread, the depth at the curb and the inlet's design — and where the rest +goes. + +OpenSWMM offers two ways to attach an inlet, and they are not +interchangeable. A **conduit-attribute inlet** is a property of a street +conduit: `[INLET_USAGE]` names the conduit, the design and the node the +captured water is delivered to, and the capture is booked at the conduit's +downstream node. An **inlet junction** is a node of its own, sitting +between two street conduits. This chapter runs both on one street and +shows what each makes possible. + +## Deck + +Deck: `docs/figures/decks/street_inlets/street_inlet_junction.inp` + +One street reach draining to a parallel sewer: + +``` +J_TOP --ST_A--> J_MID --ST_B--> [IJ1] --ST_C--> OUT_ST street, at grade + | capture | capture + +--> MH1 --SW_1--> MH2 --+--SW_2--> OUT_SEW sewer, buried +``` + +`ST_A` carries a conduit-attribute inlet — a combination grate and curb +opening, two of them — whose capture is delivered to `MH1`. `IJ1` is an +inlet junction between `ST_B` and `ST_C` carrying a single curb opening, +delivering to `MH2`. The storm is a 2-hour event on a small catchment +above the street. + +The deck is a copy of `examples/inlets/street_inlet_junction.inp`; its +header shows all four `[INLETS]` design grammars, including the two-line +combination encoding and a custom design pointing at a diversion curve. + +## Options that select the formulation + +An inlet junction is a virtual junction that also carries an inlet, so it +inherits every virtual-junction rule: exactly two conduits, the same +cross-section on both, zero offsets, and dynamic wave routing. + +``` +[INLET_JUNCTIONS] +;;Name Elev MaxDepth InitDepth Inlet Node Count ... +IJ1 ... Curb1 MH2 1 + +[INLET_USAGE] +;;Conduit Inlet Node Number %Clogged Qmax aLocal wLocal Placement +ST_A Combo1 MH1 2 0 0 0 0 AUTOMATIC +``` + +with `[STREETS]` giving the cross-section both conduits use and `[INLETS]` +the designs. A conduit attached to an inlet junction may **not** also +carry an `[INLET_USAGE]` row — that would capture the same water twice, +and the engine refuses it (rule 629). That is why the conduit-attribute +inlet sits on `ST_A` rather than on `ST_B`. + +## Results + +![Figure 5-1](figures/png/workflow_ch5_inlet_capture_vs_bypass.png) + +*Figure 5-1 Capture and bypass along a street reach with a conduit-attribute inlet and an inlet junction* + +| | Peak approach flow | Peak capture | Average capture | Volume captured | Volume bypassed | +|---|---|---|---|---|---| +| `ST_A`, conduit attribute | 11.937 cfs | 99.00 % | 98.22 % | 266.6 kgal | 2.70 kgal | +| `IJ1`, inlet junction | 0.133 cfs | 90.00 % | 90.00 % | 2.41 kgal | 0.28 kgal | + +*Table 5-1 The Street Inlet Flow Summary for the two inlets, as the report prints it* + +**Read the summary's columns carefully.** "Peak Flow" is the peak +*approach* flow the inlet saw, not the flow it captured. "Bypass Flow +Pcnt" — 88.90 % for `ST_A` — is the *frequency* of bypass over the periods +with capture, not a share of the volume; the volume share is the last two +columns, and by volume `ST_A` captured 99 % of what reached it. A reader +who takes the bypass column as a volume fraction will conclude the +opposite of what the run says. + +**The first inlet does nearly all the work.** It sees 269 kgal over the +storm and passes 2.7 kgal on. The inlet junction then sees only what got +past the first one, captures 90 % of that, and leaves 0.28 kgal to reach +the downstream outfall. Panel (a) shows the same thing as flows: the +street flow falls from 11.9 cfs to 0.13 cfs to 0.012 cfs across the two +inlets, three orders of magnitude on a symmetric log scale. + +**What the inlet junction adds.** The capture itself is the same HEC-22 +calculation either way. The difference is that `IJ1` is a node, so it + +- has a head of its own, which the two street conduits see, instead of + the capture being booked at a neighbouring node's head; +- can flood above the curb and report it as a node would; +- takes `MH2`'s surcharge back onto the street as backflow, which a + conduit attribute cannot represent at all; +- transmits momentum between `ST_B` and `ST_C` rather than terminating + them. + +**When the conduit attribute is the right answer.** When the inlet is one +of a run of many on a long reach, when the sewer below it will not +surcharge, and when the street's own hydraulics are not the question. It +is cheaper — no extra node, no virtual-junction constraints on the +cross-sections — and this run shows it doing the same capture job. + +## Where to go next + +- @ref hydraulics_ref_ch7_advanced_features "Hydraulics 7" — the HEC-22 + capture relations and the inlet-junction formulation +- @ref hydraulics_ref_ch5_cross_section "Hydraulics 5" — the street + cross-section, its spread and its depth at the curb +- @ref engine_manual_sect_STREETS, @ref engine_manual_sect_INLETS, + @ref engine_manual_sect_INLET_USAGE and + @ref engine_manual_sect_INLET_JUNCTIONS — the grammar of each section +- @ref tutorial_street_inlets — the same model built in the GUI +- @ref application_manual_ch2_filling_pipe "Chapter 2" — what happens in + the sewer below, once the captured water surcharges it diff --git a/docs/manuals/application/sections/Chapter6-Coupled1D2D.md b/docs/manuals/application/sections/Chapter6-Coupled1D2D.md new file mode 100644 index 000000000..16e218845 --- /dev/null +++ b/docs/manuals/application/sections/Chapter6-Coupled1D2D.md @@ -0,0 +1,160 @@ +@page application_manual_ch6_coupled_1d2d Chapter 6: Building a Coupled One- and Two-Dimensional Model + +## Problem + +A one-dimensional model reports water leaving a node as flooding, and +then loses it. For a capacity assessment that is enough. For a flood map, +an evacuation route or a depth at a doorway, it is not: the question is +where the water goes, how deep it gets, and when it comes back. + +Adding a mesh answers that, and adds three things to get right — the +mesh, the boundaries, and the coupling between the two solvers. This +chapter builds all three on the engine's own complete example. + +## Deck + +Deck: `docs/figures/decks/coupled_1d2d/2d_complete_example.inp` + +A deliberately small model: a 1D network of junctions, a storage unit and +an outfall, beside a mesh of eight triangles over nine vertices. It is +small so that every feature is visible at once — five boundary-condition +types, both kinds of coupling point, per-edge conveyance factors — rather +than realistic. + +The 2D results go to an HDF5 file named by the deck, and both figures on +this page are read from it. + +## Options that select the formulation + +The mesh itself is `[2D_VERTICES]` and `[2D_TRIANGLES]`; the solver is +configured in `[2D_OPTIONS]`: + +``` +[2D_OPTIONS] +MAX_TIMESTEP 10.0 ;; caps the marcher step and the sync batch +DRY_DEPTH 0.001 ;; wet/dry threshold +COUPLING_CD 0.65 ;; default discharge coefficient +INTEGRATOR EXPLICIT ;; the explicit local-inertial marcher +CFL_NUMBER 0.7 +H_MOVE 0.003 ;; below this a cell is integrated lazily +LTS_TIERS 4 ;; local time stepping tiers +COUPLING_AREA DEFAULT +REPORT_2D YES +OUTPUT_FILE 2d_complete_example.h5 +``` + +The momentum closure is the one key this chapter varies: + +``` +MOMENTUM_EQUATION LOCAL_INERTIAL ;; or FULL_SWE, or DIFFUSIVE_WAVE +``` + +**Coupling is declared in two ways, and they mean different things.** + +``` +[2D_VERTEX_NODE_MAP] +;; VERTEX SWMM_NODE CD AREA + 4 J1 0.65 2.0 + +[2D_TRIANGLE_NODE_MAP] +;; TRIANGLE_OR_TAG SWMM_NODE CD AREA + vault ST1 0.60 10.0 +``` + +A **vertex** map attaches a node to a point of the mesh — a drain inlet in +the middle of a street, where the surrounding cells' surfaces are averaged +to give the 2D head. A **triangle** map attaches a node to whole cells, +named directly or by tag — a vault or a pond that occupies them. Both use +the same orifice law on the head difference, with the discharge +coefficient and exchange area the row gives. + +**Boundaries are per edge**, and unlisted boundary edges default to a +wall: + +``` +[2D_BOUNDARY_CONDITIONS] +;; TRI EDGE TYPE PARAM_1 PARAM_2 GROUP + 0 2 NORMAL_FLOW 0.0050 * * + 2 0 TS_STAGE TIDAL_TS * east_tide + 6 0 RATING_CURVE DOWN_RC * east_rc + 7 0 SPECIFIED_FLOW 0.0500 * upstream + 5 0 SPECIFIED_STAGE 101.50 * * +``` + +Edge *e* of a triangle is the edge opposite vertex *e*, which is the one +convention to keep in mind when reading or writing these rows. + +## Results + +![Figure 6-1](figures/png/workflow_ch6_mesh_and_coupling.png) + +*Figure 6-1 The example mesh: bed elevation, the five boundary-condition types and both kinds of coupling point* + +Panel (a) is the deck drawn from its own results file: the bed rises about +0.7 m from the south-west corner, the coloured perimeter segments are the +five boundary types, and the circled vertex is the drain inlet mapped to +node `J1`. Panel (b) is the maximum depth each cell reached. + +The run's 2D continuity block is the first thing to read after a coupled +run: + +| Term | Volume (m³) | +|---|---| +| Rainfall inflow | 0.334 | +| 1D → 2D spill inflow | 2 746.7 | +| Boundary inflow | 4 735.4 | +| 2D → 1D drain outflow | 4 630.3 | +| Boundary outflow | 2 739.8 | +| Final stored volume | 112.3 | +| **Continuity error** | **−0.000 %** | + +*Table 6-1 The 2D Surface Routing Continuity block for this run* + +Both coupling directions are active: the network spills 2 747 m³ onto the +surface and drains 4 630 m³ back off it. A coupled model whose spill and +drain rows are both zero is not coupled, whatever its maps say — that is +the first check. + +## Which momentum closure + +![Figure 6-2](figures/png/workflow_ch6_momentum_closures_depth.png) + +*Figure 6-2 One cell's depth history under the three momentum closures* + +| `MOMENTUM_EQUATION` | Peak depth in cell 4 | +|---|---| +| `LOCAL_INERTIAL` | 0.499 m | +| `FULL_SWE` | 0.912 m | +| `DIFFUSIVE_WAVE` | 0.642 m | + +*Table 6-2 What each closure gives on this mesh* + +The three closures share everything else — the same mesh, the same time +stepping, the same coupling, the same boundaries — and they disagree here +by nearly half a metre, holding that disagreement through the run. The +closure is not a cosmetic choice. + +**What this comparison is not.** Eight cells under strong boundary forcing +is a feature demonstration, and a spread this large on it says more about +the mesh than about the closures. The place to judge them is against +analytic solutions — the SWASHES cases in +@ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9, §9.10" — and the +guidance from those is the guidance in +@ref application_manual_ch1_choosing "Chapter 1": local inertial for +shallow friction-dominated spreading, full shallow water where the flow +is transcritical or shocked, diffusive wave for very flat and slow water. +What this figure establishes is that the choice must be made deliberately. + +## Where to go next + +- @ref hydraulics_ref_ch9_two_dimensional "Hydraulics 9" — the mesh, the + closures, the boundary laws and the coupling formulation +- @ref application_manual_ch7_mesh_hydrology "Chapter 7" — driving the + same kind of mesh with rain rather than spill +- @ref quality_ref_ch10_mesh_quality "Quality 10" — carrying constituents + on the mesh +- @ref tutorial_1d2d_coupling, @ref tutorial_2d_inundation, + @ref tutorial_2d_boundaries, @ref tutorial_pure_2d — the same ground in + the GUI +- @ref engine_manual_sect_2D_OPTIONS and the other `[2D_*]` entries — the + grammar of every section named here diff --git a/docs/manuals/application/sections/Chapter7-MeshHydrology.md b/docs/manuals/application/sections/Chapter7-MeshHydrology.md new file mode 100644 index 000000000..69b1d30d3 --- /dev/null +++ b/docs/manuals/application/sections/Chapter7-MeshHydrology.md @@ -0,0 +1,133 @@ +@page application_manual_ch7_mesh_hydrology Chapter 7: Rain, Infiltration and Groundwater on the Mesh + +## Problem + +@ref application_manual_ch6_coupled_1d2d "Chapter 6" drove a mesh with +water spilled from the network. The other way to drive one is to rain on +it directly, and then the mesh is doing hydrology: catching rainfall, +losing part of it into the ground, running the rest downhill, and handing +what reaches a drain to the network. + +That raises three questions a subcatchment never has to answer. Which +gage does a cell listen to, when there are several? What does each cell +do with the water that soaks in? And where does that water go — out of the +model, into the old per-subcatchment aquifer, or into the aquifer on the +mesh itself? + +## Deck + +Deck: `docs/figures/decks/mesh_hydrology/mesh_hydrology.inp` + +A 20 × 20 m patch of ground, meshed as eight triangles over nine +vertices, falling gently toward a drain at the centre that is coupled to +a junction. Two rain gages stand at opposite sides reading 20 and +5 mm/hr, so the interpolation has something to interpolate. Three soil +tags — lawn, paved and woods — give the cells three infiltration methods. +One hour of rain, two hours of recession. + +The deck is written for this chapter rather than copied: it is the +smallest model that exercises all three questions at once. + +## Options that select the formulation + +Two gages, each with coordinates, because an un-located gage cannot be +interpolated: + +\snippet mesh_hydrology/mesh_hydrology.inp gages + +The mesh's own options select the rainfall mode and the infiltration +destination: + +\snippet mesh_hydrology/mesh_hydrology.inp twod + +Infiltration resolves per cell, by tag, with a mesh-wide fallback: + +\snippet mesh_hydrology/mesh_hydrology.inp infiltration + +and the aquifer beneath is configured the same way: + +\snippet mesh_hydrology/mesh_hydrology.inp aquifer + +**One warning worth reading.** The first version of this deck gave the +coupling point an exchange area of 1 m² and the engine said: + +> 2D-coupled node 'J1' has exchange AREA 1.000 m² — 14x the largest +> connected conduit area (0.0707 m²). The orifice can inject far more than +> the pipe can convey; expect the node to fill and spill back each window. + +The deck now uses 0.07 m², the pipe's own area. An exchange area is the +size of the hole between the surface and the network, not the size of the +puddle above it. + +## Results + +![Figure 7-1](figures/png/workflow_ch7_rain_and_infiltration.png) + +*Figure 7-1 Interpolated rainfall and infiltrated depth on each cell of a meshed patch of ground* + +**Every cell takes its own rainfall.** Panel (a): the cells nearest the +20 mm/hr gage receive 17.6 mm/hr, those nearest the 5 mm/hr gage 7.4, and +the rest lie between. The Laplace natural-neighbour weights reproduce a +linear field exactly and never leave the range of the gage readings, so +no cell can receive more than 20 or less than 5. With one gage, or with +`RAINFALL_MODE SYSTEM`, every cell would receive the same depth and the +whole distinction would vanish. + +**Each cell infiltrates by its own method.** Panel (b): the lawn cells +run Horton, the paved cells a constant rate, the wooded cells Green-Ampt, +and the amounts differ by a factor of eight across the patch. Part of +that is the method and part is the water available — the cell that +infiltrated 0.01 mm never held more than 0.06 mm of water, and both +sinks ramp off below `DRY_DEPTH`. Infiltration is limited by supply as +much as by soil. + +| Term | Volume (m³) | +|---|---| +| Rainfall inflow | 5.001 | +| Infiltration loss | 1.614 | +| 2D → 1D drain outflow | 3.235 | +| Final stored volume | 0.152 | +| **Continuity error** | **0.000 %** | + +*Table 7-1 The 2D surface water balance for the storm* + +Just under a third of the rain went into the ground and just under +two thirds reached the drain. That split is the answer the mesh exists to +give: a subcatchment would have produced one runoff hydrograph with one +infiltration loss, and would not have said which part of the ground did +what. + +**The destination key is checked at open, not ignored.** Setting +`INFIL_DESTINATION SUBCATCH_AQUIFER` on this deck stops the run: + +> 2D initialization failed: [2D_OPTIONS] INFIL_DESTINATION +> SUBCATCH_AQUIFER needs subcatchments with aquifers to receive the +> recharge; this model has none. + +which is the right behaviour — the alternative is a model that silently +loses its recharge. `LOST` and `AQUIFER_2D` both run here, and the +*surface* ledger is identical under both: the surface has finished with +the water either way, and the difference is what happens to it next. + +## What this chapter does not show + +The mesh aquifer's own state — the water table, the unsaturated store, +the exchange with the node — is configured in this deck and is not +plotted here. Its theory, its state variables, its closures and its +continuity ledger are in +@ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9", and its +non-Gardner soil laws carry \status{Experimental}. A worked example of +the aquifer itself belongs with those, and is not in this round. + +## Where to go next + +- @ref hydrology_ref_ch8_mesh_surface "Hydrology 8" — rainfall + interpolation, per-cell infiltration and the mesh water balance +- @ref hydrology_ref_ch9_mesh_groundwater "Hydrology 9" — the two-layer + aquifer this deck configures +- @ref application_manual_ch6_coupled_1d2d "Chapter 6" — the same kind of + mesh driven by spill instead of rain +- @ref engine_manual_sect_2D_INFILTRATION_DEFAULTS, + @ref engine_manual_sect_2D_INFILTRATION_OPTIONS, + @ref engine_manual_sect_2D_AQUIFER_OPTIONS, + @ref engine_manual_sect_2D_AQUIFER — the grammar of each section diff --git a/docs/manuals/application/sections/Chapter8-TransportEngines.md b/docs/manuals/application/sections/Chapter8-TransportEngines.md new file mode 100644 index 000000000..8156283be --- /dev/null +++ b/docs/manuals/application/sections/Chapter8-TransportEngines.md @@ -0,0 +1,133 @@ +@page application_manual_ch8_transport_engines Chapter 8: The Three Transport Engines + +## Problem + +A constituent enters a network and has to be carried through it. Every +transport engine answers the same question — what concentration is where, +when — and they disagree most where a model usually cares most: at a +front. + +`[OPTIONS] QUALITY_SOLVER` chooses between three. The legacy engine treats +each conduit as a stirred tank. The Eulerian engine cuts the conduit into +cells and advects with a flux-limited scheme. The Lagrangian engine +carries parcels of water that keep their concentration until they mix. +This chapter sends one step of conservative tracer through all three. + +## Deck + +Deck: `docs/figures/decks/transport_demo/transport_demo.inp` + +Five junctions in a line discharging to an outfall through five 100 m +conduits. A constant 0.2 m³/s inflow enters at `J1` from t = 0 carrying a +conservative tracer at 10 mg/L, a first-order decaying constituent at +20 mg/L and an inlet temperature of 18 °C. Because the inflow starts into +a clean system, the tracer arrives at each junction as a step. + +The deck is the SWMMVis tutorial's transport demonstration, with four +process components configured from sidecar files. The same deck carries +@ref application_manual_ch9_msx "Chapter 9" and +@ref application_manual_ch10_age_heat "Chapter 10". + +## Options that select the formulation + +\snippet transport_demo/transport_demo.inp options + +and the inflows that make the front: + +\snippet transport_demo/transport_demo.inp inflows + +The Eulerian engine's own options live in the component's sidecar rather +than in the deck, which is where `TARGET_DX` is set: + +``` +[TRANSPORT_OPTIONS] +DISPERSION FISCHER +SCALAR_SCHEME MUSCL +LIMITER VANLEER +TARGET_DX 25 +``` + +One caution about reporting. The deck reports every five minutes, and the +front crosses the whole line in about five minutes: at that resolution +every engine looks identical because the report steps over the event. The +figures below upsert `REPORT_STEP 0:00:10`. If a comparison of engines +looks like no difference at all, check the reporting step before +concluding anything. + +## Results + +![Figure 8-1](figures/png/workflow_ch8_tracer_breakthrough_three_engines.png) + +*Figure 8-1 A step of conservative tracer at the downstream junction under the three transport engines* + +| `QUALITY_SOLVER` | Half-rise at J5 | Plateau | Run time | +|---|---|---|---| +| `LEGACY` | 0.74 min | 10.000 mg/L | 0.05 s | +| `LAGRANGIAN` | 2.05 min | 10.000 mg/L | 0.15 s | +| `EULERIAN_ARD` | 4.29 min | 10.000 mg/L | 0.12 s | + +*Table 8-1 When half the inflow concentration reaches J5, 400 m downstream* + +**All three conserve mass and all three reach the same plateau.** The +disagreement is entirely about *when*, and it is large: the legacy engine +has half the concentration at J5 within 45 seconds, the Eulerian engine +not for four and a half minutes. A tracer study calibrated against one of +these would be badly wrong under another. + +**Why the legacy engine is early.** A stirred tank has no travel time. +Mass entering a conduit is instantly available at its downstream end in +proportion to the volume ratio, so a front propagates through the network +as fast as the mixing cascade allows rather than as fast as the water +moves. For a long-duration load — a continuous discharge, a storm's worth +of washoff — the difference integrates away, which is why this engine +remains the default and remains adequate for most quality work. + +**Why the Lagrangian engine is between them.** Parcels move with the +water, so the arrival is the water's arrival. The rise is nearly vertical +because a parcel keeps its concentration: what smears the front is the +mixing at each junction, not the advection. + +**Why the Eulerian engine is latest, and not simply diffusive.** It +advects on a fixed mesh with a limited second-order scheme, so the front +arrives with the water and is spread by the dispersion term rather than by +the scheme. The dip near six minutes is the node-by-node structure of the +line showing through: each junction mixes what has arrived so far, and +with dispersion turned on the reach behind the front is still filling. + +## `TARGET_DX`: what refinement buys + +![Figure 8-2](figures/png/workflow_ch8_ard_dx_sensitivity.png) + +*Figure 8-2 The same front under the Eulerian engine at three cell sizes, and what each costs* + +| `TARGET_DX` | Cells per conduit | Half-rise at J5 | Run time | +|---|---|---|---| +| 50 m | 2 | 4.29 min | 0.10 s | +| 25 m | 4 | 4.29 min | 0.12 s | +| 10 m | 10 | 4.35 min | 0.17 s | + +*Table 8-2 The Eulerian engine at three cell sizes on the same deck* + +The arrival time is already converged at two cells per conduit; what +refinement changes is the *sharpness* of the front. The 10 m run rises +almost vertically and overshoots to 9.2 mg/L before settling, where the +coarser runs round the corner off. That overshoot is the limiter working +at a discontinuity, not an instability, and it is bounded by the +neighbouring values. + +Refinement is quadratic in cost in general — halving `TARGET_DX` doubles +both the cell count and the substep count — though on a deck this small +the constant overhead dominates and the ratio is only 1.7×. On a network +model the quadratic term is the one that matters. + +## Where to go next + +- @ref quality_ref_ch7_ard_transport "Quality 7" — the Eulerian and + Lagrangian engines, their schemes, limiters and dispersion closures +- @ref quality_ref_ch5_transport_treatment "Quality 5" — the legacy + routing these two extend +- @ref application_manual_ch9_msx "Chapter 9" — reactions on the same deck +- @ref application_manual_ch10_age_heat "Chapter 10" — water age and heat + on the same deck +- @ref tutorial_transport — the same model in the GUI +- @ref engine_manual_sect_TRANSPORT_OPTIONS — the sidecar's grammar diff --git a/docs/manuals/application/sections/Chapter9-MultispeciesReactions.md b/docs/manuals/application/sections/Chapter9-MultispeciesReactions.md new file mode 100644 index 000000000..56ef8938f --- /dev/null +++ b/docs/manuals/application/sections/Chapter9-MultispeciesReactions.md @@ -0,0 +1,125 @@ +@page application_manual_ch9_msx Chapter 9: Multi-Species Reactions + +## Problem + +A first-order decay coefficient on a `[POLLUTANTS]` row is enough for a +tracer study and not enough for chemistry. Chlorine decays at a rate that +depends on temperature; two species react with each other; a wall demand +differs from a bulk demand. Those need a **reaction system**: species, +coefficients and rate expressions the engine evaluates. + +OpenSWMM configures one as a process component with its own file. This +chapter builds the smallest useful system — one species whose decay rate +follows the water temperature the heat component computes — and is candid +about what this release does and does not let you see. + +## Deck + +Deck: `docs/figures/decks/transport_demo/transport_demo.inp` with +`transport_demo.rxn` + +The five-conduit line of +@ref application_manual_ch8_transport_engines "Chapter 8". The reaction +system adds one bulk species, `CL2`, decaying first order with an +Arrhenius correction: + +``` +[REACTION_OPTIONS] +SOLVER RK5 +COUPLING NONE +RATE_UNITS HR +TEMPERATURE 20 + +[REACTION_SPECIES] +;;Kind Name Units +BULK CL2 MG + +[REACTION_COEFFICIENTS] +;;Kind Name Value +CONSTANT kb 0.30 +CONSTANT theta 1.07 + +[REACTION_PIPES] +;;Form Species Expression +RATE CL2 -kb * theta ^ (TEMP - 20) * CL2 + +[REACTION_QUALITY] +;;Scope Species Value +GLOBAL CL2 2.0 +``` + +`TEMP` in that expression is a hydraulic variable available to every +expression: when the heat component is on it is the computed water +temperature, and when it is off it is the `[REACTION_OPTIONS] TEMPERATURE` +fallback. That single identifier is the whole coupling between the two +components. + +## Options that select the formulation + +\snippet transport_demo/transport_demo.inp components + +A component is named by its identifier and given a configuration file. +Nothing else in the deck changes; remove the line and the system is gone. +The sections may also be embedded directly in the `.inp`, which is +supported as a convenience — but embedded sections are read and not +written back when the model is saved, and the engine warns before that +happens. + +## Results + +![Figure 9-1](figures/png/workflow_ch9_arrhenius_rate_from_temperature.png) + +*Figure 9-1 What the computed water temperature does to a reaction system's rate, through the Arrhenius correction in its expression* + +**The correction is the point of coupling heat to reactions.** At +θ = 1.07 the rate changes by 7 % per degree, so the half-life of `CL2` +runs from 230 minutes in 12 °C water to 139 minutes at 20 °C. A model that +leaves `HEAT_TRANSPORT` off evaluates the same expression at the fallback +temperature and gets the 20 °C answer everywhere, all year. + +**On this deck the effect is small, and it is worth seeing why.** Panel +(b) is the run's own temperature: the line fills from empty, the nodes +pass through a cold-start transient in the first minutes, and by ten +minutes every node sits at the inflow temperature of 18 °C, where the +multiplier is 0.874. The deck is too short and too fast for the water to +warm; a reach with a real residence time is where the correction earns +its keep. + +**Do not read the first minutes.** A node that is nearly dry and filling +carries a temperature computed from a vanishing volume — the 2 °C +excursion at `J5` at three minutes is that, not a physical result. The +same caution applies to every concentration during a cold start. + +## What this release does not report + +`CL2` itself does not appear in Figure 9-1, and it cannot: **the reaction +system's species are computed but not written to the output file.** The +section that would select them for reporting, `[REACTION_REPORT]`, is +\status{Planned} (@ref quality_ref_ch8_msx_reactions "Quality 8, §8.2"). +The output file carries the `[POLLUTANTS]` rows and the reserved rows for +water age and temperature, and nothing else. + +Four other sections of a reaction configuration are also planned and are +**refused**, not ignored: `[REACTION_SOURCES]`, `[REACTION_PARAMETERS]`, +`[REACTION_PATTERNS]` and `[REACTION_SUBCATCHMENTS]`. A configuration +carrying one of them is rejected as a whole, with the phase that will +deliver it named in the message. That is deliberate — a silently ignored +source term would be worse than a refused file. + +So a reaction system today is worth building when the species drive +something you *can* see, or when you are preparing a model for the release +that reports them. The quality reference chapter states the same limits +from the theory side. + +## Where to go next + +- @ref quality_ref_ch8_msx_reactions "Quality 8" — the reaction system, + its solver, its expression language and the status of every section +- @ref quality_ref_ch11_planned "Quality 11" — what is coming for + reactions and reporting +- @ref application_manual_ch10_age_heat "Chapter 10" — the heat component + whose temperature this chapter's expression reads +- @ref engine_manual_sect_PROCESS_COMPONENTS — how a component is named + and configured +- @ref engine_manual_sect_REACTION_OPTIONS and the other + `[REACTION_*]` entries — the grammar of each section diff --git a/docs/manuals/engine/engine_manual.md b/docs/manuals/engine/engine_manual.md new file mode 100644 index 000000000..7c621c41d --- /dev/null +++ b/docs/manuals/engine/engine_manual.md @@ -0,0 +1,98 @@ + +@page engine_manual OpenSWMM Engine Manual + +
+OpenSWMM Engine Manual +===================================== +
+ +
+ +See @ref authors for the full list of authors and contributors. + +
+ +## DISCLAIMER {#engine_manual_disclaimer} + +This software is provided on an "as is" basis and the user assumes responsibility for its use. Although a reasonable effort has been made to assure that the results obtained are correct, the authors are not responsible and assume no liability whatsoever for any results or any use made of the results obtained from these programs, nor for any damages or litigation that result from the use of these programs for any purpose. + +## ABSTRACT {#engine_manual_abstract} + +The Storm Water Management Model (SWMM) is a dynamic rainfall-runoff simulation model used for single event or long-term (continuous) simulation of runoff quantity and quality from primarily urban areas. The runoff component of SWMM operates on a collection of subcatchment areas that receive precipitation and generate runoff and pollutant loads. The routing portion of SWMM transports this runoff through a system of pipes, channels, storage/treatment devices, pumps, and regulators. SWMM tracks the quantity and quality of runoff generated within each subcatchment, and the flow rate, flow depth, and quality of water in each pipe and channel during a simulation period comprised of multiple time steps. + +This manual documents the OpenSWMM **computational engine**: the objects a model is built from, the format of the input file it reads, the files it reads and writes, the reports it produces, the programmatic C and Python interfaces, and the error and warning messages it emits. Detailed descriptions of the theory and numerical methods are in the separate reference manuals; the graphical application is documented separately (see below). + +## FOREWORD {#engine_manual_foreward} + +OpenSWMM is the next generation of the EPA Storm Water Management Model, maintained and advanced as a community-driven open source project. It builds on the foundational work of EPA's SWMM, which was first released in 1971 and has undergone several major upgrades since then. OpenSWMM preserves the rich legacy of SWMM while advancing the codebase with modern architecture, improved modularity, enhanced performance, and support for model coupling through the HydroCouple framework. + +SWMM is used throughout the world for planning, analysis, and design related to stormwater runoff, combined and sanitary sewers, and other drainage systems. It can be used to evaluate gray infrastructure stormwater control strategies, such as pipes and storm drains, and is a useful tool for creating cost-effective green/gray hybrid stormwater control solutions. + +![Urban wet weather flows](figures/figure1_1_urban_sewershed.jpg) + +*Urban wet weather flows* + +## ACKNOWLEDGEMENTS {#engine_manual_acknowledgements} + +OpenSWMM builds on the original EPA Storm Water Management Model (SWMM), developed by the U.S. Environmental Protection Agency, Office of Research and Development. The original user's manual and SWMM 5 software were created by **Lewis A. Rossman**, Environmental Scientist Emeritus at the U.S. EPA. His extraordinary contribution to the field of stormwater modeling is gratefully acknowledged. + +The original SWMM documentation was reviewed by Michelle Simon, Katherine Ratliff, and Anne Mikelonis, all of the U.S. EPA, by Robert Dickinson (Innovyze), Mitch Heineman (CDM Smith), Mike Gregory (CHI), and Nandana Perera (CHI). + +See @ref authors for the complete list of authors and contributors. + +## USING THE GRAPHICAL APPLICATION {#engine_manual_gui} + +This manual does not describe a user interface. The OpenSWMM graphical +application, **SWMMVis**, has its own manual covering the map canvas, layers and +coordinate reference systems, every editor and dialog, running simulations, +plots and result animation, 2D meshing, and a set of tutorials: + + + +Two tables that used to live in this manual now live there, because they are +values typed into an editor rather than engine behaviour: the parameter tables +(units, soil characteristics, curve numbers, Manning's *n*, culvert codes and +standard pipe sizes) are @ref manual_reference_tables, and the per-object +property dictionaries are @ref manual_property_index. The numbered messages this +engine emits are also catalogued there, alongside the API codes the application +shows next to them, as @ref manual_error_codes. + +@tableofcontents + +## Manual Contents + +- @subpage engine_manual_ch1_conceptual_model — CHAPTER 1 - The Conceptual Model +- @subpage engine_manual_ch2_input_file — CHAPTER 2 - Input File Reference +- @subpage engine_manual_ch3_files — CHAPTER 3 - Files and Command-Line Operation +- @subpage engine_manual_ch4_reports — CHAPTER 4 - Status Report; Summary Tables and Output +- @subpage engine_manual_ch5_api — CHAPTER 5 - Programmatic C API; Python Bindings and Plugins +- @subpage engine_manual_appendix_a_messages — APPENDIX A - Error and Warning Messages + +## WHERE THE OLD CHAPTERS WENT {#engine_manual_provenance} + +This manual replaces the former *OpenSWMM User Manual*, which mixed engine +reference material with instructions for the retired Delphi user interface. The +interface chapters are superseded by the SWMMVis manual linked above; the engine +chapters were kept and renumbered. Anyone holding a citation to the old numbering +can find its destination here. + +| Former chapter | Now | +|---|---| +| Ch. 1 – Introduction | this page | +| Ch. 2 – Quick Start Tutorial | @ref tutorial_site_drainage | +| Ch. 3 – SWMM's Conceptual Model | @ref engine_manual_ch1_conceptual_model | +| Ch. 4 – SWMM's Main Window | @ref manual_interface | +| Ch. 5 – Working with Projects | @ref manual_projects | +| Ch. 6 – Working with Objects | @ref manual_map_editing | +| Ch. 7 – Working with the Map | @ref manual_map_navigation and @ref manual_layers | +| Ch. 8 – Running a Simulation | @ref manual_running and @ref manual_simulation_options | +| Ch. 9 – Viewing Results | @ref engine_manual_ch4_reports (report content); @ref manual_results and @ref manual_tabular_results | +| Ch. 10 – Printing and Copying | @ref manual_map_navigation | +| Ch. 11 – Files Used by SWMM | @ref engine_manual_ch3_files | +| Ch. 12 – Using Add-In Tools | retired; superseded by the plugin system | +| Ch. 13 – Programmatic C API | @ref engine_manual_ch5_api | +| App. A – Useful Tables | @ref manual_reference_tables | +| App. B – Visual Object Properties | @ref manual_property_index | +| App. C – Specialized Property Editors | @ref manual_hydrology; @ref manual_hydraulics; @ref manual_water_quality | +| App. D – Command Line SWMM | @ref engine_manual_ch2_input_file (format) and @ref engine_manual_ch3_files (command line) | +| App. E – Error and Warning Messages | @ref engine_manual_appendix_a_messages | diff --git a/docs/manuals/engine/figures/fig3-02-box-culvert.jpg b/docs/manuals/engine/figures/fig3-02-box-culvert.jpg new file mode 100644 index 000000000..260946d83 Binary files /dev/null and b/docs/manuals/engine/figures/fig3-02-box-culvert.jpg differ diff --git a/docs/manuals/user/images/Storm Drain Inlet Grate.png b/docs/manuals/engine/figures/fig3-03-storm-drain-inlet.png similarity index 100% rename from docs/manuals/user/images/Storm Drain Inlet Grate.png rename to docs/manuals/engine/figures/fig3-03-storm-drain-inlet.png diff --git a/docs/manuals/engine/figures/fig3-06-natural-transect.jpg b/docs/manuals/engine/figures/fig3-06-natural-transect.jpg new file mode 100644 index 000000000..2a43513f0 Binary files /dev/null and b/docs/manuals/engine/figures/fig3-06-natural-transect.jpg differ diff --git a/docs/images/Fig1.png b/docs/manuals/engine/figures/fig3-08-dual-drainage.png similarity index 100% rename from docs/images/Fig1.png rename to docs/manuals/engine/figures/fig3-08-dual-drainage.png diff --git a/docs/manuals/user/images/HEC22 Inlets.png b/docs/manuals/engine/figures/fig3-09-hec22-inlets.png similarity index 100% rename from docs/manuals/user/images/HEC22 Inlets.png rename to docs/manuals/engine/figures/fig3-09-hec22-inlets.png diff --git a/docs/manuals/user/images/LID Parameter Adjustment.png b/docs/manuals/engine/figures/fig3-10-lid-adjustment.png similarity index 100% rename from docs/manuals/user/images/LID Parameter Adjustment.png rename to docs/manuals/engine/figures/fig3-10-lid-adjustment.png diff --git a/docs/manuals/engine/figures/figure1_1_urban_sewershed.jpg b/docs/manuals/engine/figures/figure1_1_urban_sewershed.jpg new file mode 100644 index 000000000..fc991c8d6 Binary files /dev/null and b/docs/manuals/engine/figures/figure1_1_urban_sewershed.jpg differ diff --git a/docs/manuals/engine/sections/AppendixA-Messages.md b/docs/manuals/engine/sections/AppendixA-Messages.md new file mode 100644 index 000000000..ebf7741aa --- /dev/null +++ b/docs/manuals/engine/sections/AppendixA-Messages.md @@ -0,0 +1,475 @@ +@page engine_manual_appendix_a_messages APPENDIX A - Error and Warning Messages + +@tableofcontents + +## A.1 Run-Time and Object Errors (101-19x) +ERROR 101: memory allocation error. +There is not enough physical memory in the computer to analyze the study area. + +ERROR 103: cannot solve KW equations for Link xxx. +The internal solver for Kinematic Wave routing failed to converge for the specified link at some stage of the simulation. + +ERROR 105: cannot open ODE solver. +The system could not open its Ordinary Differential Equation solver. + +ERROR 107: cannot compute a valid time step. +A valid time step for runoff or flow routing calculations (i.e., a number greater than 0) could not be computed at some stage of the simulation. + +ERROR 108: ambiguous outlet ID name for Subcatchment xxx. +The name of the element identified as the outlet of a subcatchment belongs to both a node and a subcatchment in the project's data base. + +ERROR 109: invalid parameter values for Aquifer xxx. +The properties entered for an aquifer object were either invalid numbers or were inconsistent with one another (e.g., the soil field capacity was higher than the porosity). + +ERROR 110: ground elevation is below water table for Subcatchment xxx. +The ground elevation assigned to a subcatchment’s groundwater parameters cannot be below the initial water table elevation of the aquifer object used by the subcatchment. + +ERROR 111: invalid length for Conduit xxx. +Conduits cannot have zero or negative lengths. + +ERROR 112: elevation drop exceeds length for Conduit xxx. +The elevation drop across the ends of a conduit cannot be greater than the conduit's length. Check for errors in the length and in both the invert elevations and offsets at the conduit's upstream and downstream nodes. + + +ERROR 113: invalid roughness for Conduit xxx. +Conduits cannot have zero or negative roughness values. + +ERROR 114: invalid number of barrels for Conduit xxx. +Conduits must consist of one or more barrels. + +ERROR 115: adverse slope for Conduit xxx. +Under Steady or Kinematic Wave routing, all conduits must have positive slopes. This can usually be corrected by reversing the inlet and outlet nodes of the conduit (i.e., right click on the conduit and select Reverse from the popup menu that appears). Adverse slopes are permitted under Dynamic Wave routing. + +ERROR 117: no cross-section defined for Link xxx. +Cross-section geometry was never defined for the specified link. + +ERROR 119: invalid cross-section for Link xxx. +Either an invalid shape or invalid set of dimensions was specified for a link's cross-section. + +ERROR 121: missing or invalid pump curve assigned to Pump xxx. +Either no pump curve or an invalid type of curve was specified for a pump. + +ERROR 122: startup depth not higher than shutoff depth for Pump xxx. +Automatic startup for a pump always occurs at a wet well water level that is higher than its automatic shutoff level. + +ERROR 131: the following links form cyclic loops in the drainage system. +The Steady and Kinematic Wave flow routing methods cannot be applied to systems where a cyclic loop exists (i.e., a directed path along a set of links that begins and ends at the same node). Most often the cyclic nature of the loop can be eliminated by reversing the direction of one of its links (i.e., switching the inlet and outlet nodes of the link). The names of the links that form the loop will be listed following this message. + +ERROR 133: Node xxx has more than one outlet link. +Under Steady and Kinematic Wave flow routing, a junction node can have only a single outlet link. + + + +ERROR 134: Node xxx has illegal DUMMY link connections. +Only a single conduit with a DUMMY cross-section or Ideal-type pump can be directed out of a node; a node with an outgoing Dummy conduit or Ideal pump cannot have all of its incoming links be Dummy conduits and Ideal pumps; a Dummy conduit cannot have its upstream end connected to a storage node. + +ERROR 135: Divider xxx does not have two outlet links. +Flow divider nodes must have two outlet links connected to them. + +ERROR 136: Divider xxx has invalid diversion link. +The link specified as being the one carrying the diverted flow from a flow divider node was defined with a different inlet node. + +ERROR 137: Weir Divider xxx has invalid parameters. +The parameters of a Weir-type divider node either are non-positive numbers or are inconsistent (i.e., the value of the discharge coefficient times the weir height raised to the 3/2 power must be greater than the minimum flow parameter). + +ERROR 138: Node xxx has initial depth greater than maximum depth. +Self-explanatory. + +ERROR 139: Regulator xxx is the outlet of a non-storage node. +Under Steady or Kinematic Wave flow routing, orifices, weirs, and outlet links can only be used as outflow links from storage nodes. + +ERROR 140: Storage node xxx has negative volume at full depth. +The storage unit’s Shape data (surface area versus depth) is producing a negative volume at full depth. This can occur when a storage node's surface area curve slopes downward at its highest depth which is below the node's full depth. + +ERROR 141: Outfall xxx has more than 1 inlet link or an outlet link. +An outfall node is only permitted to have one link attached to it. + +ERROR 143: Regulator xxx has invalid cross-section shape. +An orifice must have either a CIRCULAR or RECT_CLOSED shape, while a weir must have either a RECT_OPEN, TRAPEZOIDAL, or TRIANGULAR shape. + + + +ERROR 145: Drainage system has no acceptable outlet nodes. +Under Dynamic Wave flow routing, there must be at least one node designated as an outfall. +ERROR 151: a Unit Hydrograph in set xxx has invalid time base. +The time base of a Unit Hydrograph cannot be negative and if positive, must not be less than the recording interval for its rain gage. + +ERROR 153: a Unit Hydrograph in set xxx has invalid response ratios. +The response ratios for a set of Unit Hydrographs (the short-, medium-, and long-term response hydrographs) must be between 0 and 1.0 and cannot add up to a value greater than 1.0 + +ERROR 155: invalid sewer area for RDII at Node xxx. +The sewer area contributing RDII inflow to a node cannot be a negative number. + +ERROR 156: ambiguous station ID for Rain Gage xxx. +If two Rain Gages use files for their data sources and have the same Station IDs then they must also use the same data files. + +ERROR 157: inconsistent rainfall format for Rain Gage xxx. +If two or more rain gages use the same Time Series for their rainfall data then they must all use the same data format (intensity, volume, or cumulative volume). + +ERROR 158: time series for Rain Gage xxx is also used by another object. +A rainfall Time Series associated with a Rain Gage cannot be used by another object that is not also a Rain Gage. + +ERROR 159: recording interval greater than time series interval for Rain Gage xxx. +The recording time interval specified for the rain gage is greater than the smallest time interval between values in the Time Series used by the gage. + +ERROR 161: cyclic dependency in treatment functions at Node xxx. +An example would be where the removal of pollutant 1 is defined as a function of the removal of pollutant 2 while the removal of pollutant 2 is defined as a function of the removal of pollutant 1. + +ERROR 171: Curve xxx has invalid or out of sequence data. +The X-values of a curve object must be entered in increasing order. + +ERROR 173: Time Series xxx has its data out of sequence. +The time (or date/time) values of a time series must be entered in sequential order. +ERROR 181: invalid Snow Melt Climatology parameters. +The ATI Weight or Negative Melt Ratio parameters are not between 0 and 1 or the site latitude is not between -60 and +60 degrees. + +ERROR 182: invalid parameters for Snow Pack xxx. +A snow pack’s minimum melt coefficient is greater than its maximum coefficient; the fractions of free water capacity or impervious plowable area are not between 0 and 1; or the snow removal fractions sum to more than 1.0. + +ERROR 183: no type specified for LID xxx. +A named LID control has layers defined for it but its LID type was never specified. + +ERROR 184: missing layer for LID xxx. +A required design layer is missing for the specified LID control. + +ERROR 185: invalid parameter value for LID xxx. +An invalid value was supplied for an LID control's design parameter. + +ERROR 187: LID area exceeds total area for Subcatchment xxx. +The area of the LID controls placed within the subcatchment is greater than that of the subcatchment itself. + +ERROR 188: LID capture area exceeds total impervious area for Subcatchment xxx. +The amount of impervious area assigned to be treated by LID controls in the subcatchment exceeds the total amount of impervious area available. + +ERROR 191: simulation start date comes after ending date. +Self-explanatory. + +ERROR 193: report start date comes after ending date. +Self-explanatory. + +ERROR 195: reporting time step is less than routing time step. +Self-explanatory. + + +## A.2 Input File Errors (200-29x) +ERROR 200: one or more errors in input file. +This message appears when one or more input file parsing errors (the 200-series errors) occur. + +ERROR 201: too many characters in input line. +A line in the input file cannot exceed 1024 characters. + +ERROR 203: too few items at line n of input file. +Not enough data items were supplied on a line of the input file. + +ERROR 205: invalid keyword at line n of input file. +An unrecognized keyword was encountered when parsing a line of the input file. + +ERROR 207: duplicate ID name at line n of input file. +An ID name used for an object was already assigned to an object of the same category. + +ERROR 209: undefined object xxx at line n of input file. +A reference was made to an object that was never defined. An example would be if node 123 were designated as the outlet point of a subcatchment, yet no such node was ever defined in the study area. + +ERROR 211: invalid number xxx at line n of input file. +Either a string value was encountered where a numerical value was expected or an invalid number (e.g., a negative value) was supplied. + +ERROR 213: invalid date/time xxx at line n of input file. +An invalid format for a date or time was encountered. Dates must be entered as month/day/year and times as either decimal hours or as hour:minute:second. + +ERROR 217: control rule clause out of sequence at line n of input file. +Errors of this nature can occur when the format for writing control rules is not followed correctly (see Section C.3). + +ERROR 219: data provided for unidentified transect at line n of input file. +A GR line with Station-Elevation data was encountered in the [TRANSECTS] section of the input file after an NC line but before any X1 line that contains the transect’s ID name. + + +ERROR 221: transect station out of sequence at line n of input file. +The station distances specified for the transect of an irregular cross-section must be in increasing numerical order starting from the left bank. + +ERROR 223: Transect xxx has too few stations. +A transect for an irregular cross-section must have at least 2 stations. + +ERROR 225: Transect xxx has too many stations. +A transect cannot have more than 1500 stations defined for it. + +ERROR 227: Transect xxx has no Manning's N. +No Manning’s N was specified for a transect (i.e., there was no NC line in the [TRANSECTS] section of the input file. + +ERROR 229: Transect xxx has invalid overbank locations. +The distance values specified for either the left or right overbank locations of a transect do not match any of the distances listed for the transect's stations. + +ERROR 231: Transect xxx has no depth. +All of the stations for a transect were assigned the same elevation. + +ERROR 233: invalid math expression at line n of input file. +A math expression used for a treatment function, a groundwater flow function or a control rule condition clause is either not correctly formed or contains undefined variables or math functions. + +ERROR 235: invalid infiltration parameters. +Examples are a Horton maximum infiltration rate lower than the minimum rate or a Green-Ampt initial moisture deficit greater than 1. + +## A.3 File Errors (301-35x) +ERROR 301: files share same names. +The input, report, and binary output files specified on the command line cannot have the same names. + +ERROR 303: cannot open input file. +The input file either does not exist or cannot be opened (e.g., it might be in use by another program). + + + +ERROR 305: cannot open report file. +The report file cannot be opened (e.g., it might reside in a directory to which the user does not have write privileges). + +ERROR 307: cannot open binary results file. +The binary output file cannot be opened (e.g., it might reside in a directory to which the user does not have write privileges). + +ERROR 308: amount of output produced will exceed maximum file size. +For the 32-bit command line version of the program, the maximum size of the binary results file is limited to 2 GB. + +ERROR 309: error writing to binary results file. +There was an error in trying to write results to the binary output file (e.g., the disk might be full or the file size exceeds the limit imposed by the operating system). + +ERROR 311: error reading from binary results file. +The command line version of SWMM could not read results saved to the binary output file when writing results to the report file. + +ERROR 313: cannot open scratch rainfall interface file. +SWMM could not open the temporary file it uses to collate data together from external rainfall files. + +ERROR 315: cannot open rainfall interface file xxx. +SWMM could not open the specified rainfall interface file, possibly because it does not exist or because the user does not have write privileges to its directory. + +ERROR 317: cannot open rainfall data file xxx. +An external rainfall data file could not be opened, most likely because it does not exist. + +ERROR 318: date out of sequence in rainfall data file xxx. +An external user-prepared rainfall data file must have its entries appear in chronological order. The first out-of-order entry will be listed. + +ERROR 319: unknown format for rainfall data file. +SWMM could not recognize the format used for a designated rainfall data file. + +ERROR 320: invalid format for rainfall interface file. +SWMM was trying to read data from a designated rainfall interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file). + +ERROR 321: no data in rainfall interface file for gage xxx. +This message occurs when a project wants to use a previously saved rainfall interface file, but cannot find any data for one of its rain gages in the interface file. It can also occur if the gage uses data from a user-prepared rainfall file and the station id entered for the gage cannot be found in the file. + +ERROR 323: cannot open runoff interface file xxx. +A runoff interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory. + +ERROR 325: incompatible data found in runoff interface file. +SWMM was trying to read data from a designated runoff interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file). + +ERROR 327: attempting to read beyond end of runoff interface file. +This error can occur when a previously saved runoff interface file is being used in a simulation with a longer duration than the one that created the interface file. + +ERROR 329: error in reading from runoff interface file. +A format error was encountered while trying to read data from a previously saved runoff interface file. + +ERROR 331: cannot open hot start interface file xxx. +A hot start interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory. + +ERROR 333: incompatible data found in hot start interface file. +SWMM was trying to read data from a designated hot start interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file). + + + +ERROR 335: error in reading from hot start interface file. +A format error was encountered while trying to read data from a previously saved hot start interface file. + +ERROR 336: no climate file specified for evaporation and/or wind speed. +This error occurs when the user specifies that evaporation or wind speed data will be read from an external climate file, but no name is supplied for the file. +ERROR 337: cannot open climate file xxx. +An external climate data file could not be opened, most likely because it does not exist. + +ERROR 338: error in reading from climate file xxx. +SWMM was trying to read data from an external climate file with the wrong format. + +ERROR 339: attempt to read beyond end of climate file xxx. +The specified external climate does not include data for the period of time being simulated. + +ERROR 341: cannot open scratch RDII interface file. +SWMM could not open the temporary file it uses to store RDII flow data. + +ERROR 343: cannot open RDII interface file xxx. +An RDII interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory. + +ERROR 345: invalid format for RDII interface file. +SWMM was trying to read data from a designated RDII interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file). + +ERROR 351: cannot open routing interface file xxx. +A routing interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory. + +ERROR 353: invalid format for routing interface file xxx. +SWMM was trying to read data from a designated routing interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file). + +ERROR 355: mismatched names in routing interface file xxx. +The names of pollutants found in a designated routing interface file do not match the names used in the current project. + +ERROR 357: inflows and outflows interface files have same name. +In cases where a run uses one routing interface file to provide inflows for a set of locations and another to save outflow results, the two files cannot both have the same name. +ERROR 361: could not open external file used for Time Series xxx. +The external file used to provide data for the named time series could not be opened, most likely because it does not exist. + +ERROR 363: invalid data in external file used for used for Time Series xxx. +The external file used to provide data for the named time series has one or more lines with the wrong format. + +Warning Codes + +## A.4 API Errors (500-509) +These are raised by the programmatic interface (see @ref engine_manual_ch5_api) rather than by a model defect. A client sees the number in brackets ahead of any engine message. + +ERROR 500: system exception thrown. +An unexpected exception escaped the engine. This is a defect; please report it with the input file that produced it. + +ERROR 501: project not opened. +An API call that needs a model was made before `swmm_engine_open` succeeded. + +ERROR 502: simulation not started. +An API call that reads simulation state was made before the simulation was started. + +ERROR 503: simulation not ended. +An API call that is only valid after the run was made while the simulation was still in progress. + +ERROR 504: invalid object type. +An object-type code passed to the API is not one the engine recognises. + +ERROR 505: invalid object index. +An object index passed to the API is negative or beyond the number of objects of that type. + +ERROR 506: invalid object name. +No object of the requested type has the name supplied. + +ERROR 507: invalid property type. +The property code is not valid for the object type it was requested on. + +ERROR 508: invalid property value. +The value supplied is outside the range the property accepts. + +ERROR 509: invalid time period. +The reporting period or time index requested lies outside the simulation. + +## A.5 Extended Validation Errors (601-635) +These codes cover objects and checks introduced in SWMM 6 and have no counterpart in SWMM 5. + +ERROR 601: Time Series xxx has no data. +The named time series was declared but contains no value rows, and something referenced it. + +ERROR 603: Time Series xxx contains NaN or Inf values. +A value in the series is not a finite number. This usually means a malformed external file or a spreadsheet exporting an error cell. + +ERROR 605: column count mismatch in data for xxx. +A row of an external multi-column series file has a different number of columns than its header declares. + +ERROR 607: Rain Gage xxx references unknown time series. +The gage names a time series that does not appear in the [TIMESERIES] section. + +ERROR 609: Virtual Junction xxx must connect exactly two conduits. +A virtual junction exists only to join one conduit to the next, so exactly two must meet there. + +ERROR 611: Virtual Junction xxx connects conduits with different cross sections. +The two conduits must share a cross-section; otherwise the junction is a real transition and needs to be a junction node. + +ERROR 613: Virtual Junction xxx has a conduit with a nonzero offset. +Offsets imply a physical structure at the node, which a virtual junction does not have. + +ERROR 615: Virtual Junction xxx conduit inverts do not agree at the node. +The two conduits must meet at the same invert elevation. + +ERROR 617: Virtual Junction xxx cannot be coupled to a 2D surface mesh. +A virtual junction has no surface opening, so it cannot exchange flow with the 2D mesh. A point lateral inflow is still allowed. + +ERROR 619: Virtual Junction xxx requires DYNWAVE or FV flow routing. +Steady and kinematic wave routing have no node-level momentum coupling, so a virtual junction has no meaning under them. + +ERROR 621: too many items for Virtual Junction xxx. +The [VIRTUAL_JUNCTIONS] section takes only the node name. Geometry is derived from the attached conduits. + +ERROR 623: Inlet Junction xxx must connect two STREET conduits. +Curb and gutter inlets require street cross-sections. Drop inlets may instead use open rectangular or trapezoidal conduits. + +ERROR 625: Inlet Junction xxx references an unknown inlet design. +The named design does not appear in the [INLETS] section. + +ERROR 627: Inlet Junction xxx has an invalid capture node. +The capture node is missing, is the inlet junction itself, or is another virtual junction. It must be a real node that can receive the captured flow. + +ERROR 629: Inlet Junction xxx conduit also carries an [INLET_USAGE] entry. +The inlet is defined twice, once on the junction and once on the conduit. Remove one. + +ERROR 631: too many items for Inlet Junction xxx. +The [INLET_JUNCTIONS] section accepts at most eleven fields. + +ERROR 633: Inlet Junction xxx has no inlet design assigned. +An inlet junction without a design captures nothing and should be an ordinary virtual junction. + +ERROR 635: Inlet xxx cannot be used with the cross section of yyy. +The inlet type is not compatible with the conduit's shape; see ERROR 623 for which shapes each type allows. + +## A.6 Warning Messages +WARNING 01: wet weather time step reduced to recording interval for Rain Gage xxx. +The wet weather time step was automatically reduced so that no period with rainfall would be skipped during a simulation. + +WARNING 02: maximum depth increased for Node xxx. +The maximum depth for the node was automatically increased to match the top of the highest connecting conduit. + +WARNING 03: negative offset ignored for Link xxx. +The link’s stipulated offset was below the connecting node's invert so its actual offset was set to 0. + +WARNING 04: minimum elevation drop used for Conduit xxx. +The elevation drop between the end nodes of the conduit was below 0.001 ft (0.00035 m) so the latter value was used instead to calculate its slope. + +WARNING 05: minimum slope used for Conduit xxx. +The conduit's computed slope was below the user-specified Minimum Conduit Slope so the latter value was used instead. + + + +WARNING 06: dry weather time step increased to wet weather time step. +The user-specified time step for computing runoff during dry weather periods was lower than that set for wet weather periods and was automatically increased to the wet weather value. + +WARNING 07: routing time step reduced to wet weather time step. +The user-specified time step for flow routing was larger than the wet weather runoff time step and was automatically reduced to the runoff time step to prevent loss of accuracy. + +WARNING 08: elevation drop exceeds length for Conduit xxx. +The elevation drop across the ends of a conduit exceeds its length. The program computes the conduit's slope as the elevation drop divided by the length instead of using the more accurate right triangle method. The user should check for errors in the length and in both the invert elevations and offsets at the conduit's upstream and downstream nodes. + +WARNING 09: time series interval greater than recording interval for Rain Gage xxx. +The smallest time interval between entries in the precipitation time series used by the rain gage is greater than the recording time interval specified for the gage. If this was not actually intended then what appear to be continuous periods of rainfall in the time series will instead be read with time gaps in between them. + +WARNING 10a: crest elevation is below downstream invert for regulator Link xxx. +For Kinematic Wave or Steady Flow routing, the height of the opening on an orifice, weir, or outlet at a storage node is below the invert elevation of its downstream node. Users should check to see if the regulator's offset height or the downstream node's invert elevation is in error. + +WARNING 10b: crest elevation raised to downstream invert for regulator Link xxx. +For Dynamic Wave routing, the height of the opening on an orifice, weir or outlet will be raised to the invert elevation of its downstream node if necessary. + +WARNING 11: non-matching attributes in Control Rule xxx. +The premise of a control is comparing two different types of attributes to one another (for example, conduit flow and junction water depth). + + +WARNING 12: inlet removed due to unsupported shape for Conduit xxx. +Curb and gutter inlets can only be placed in conduits with a Street shaped cross-section while drop inlets can only be placed in open rectangular and trapezoidal conduits. + +WARNING 13: parameters for same month provided more than once for Unit Hydrograph xxx. +Two or more rows of the [HYDROGRAPHS] section give parameters for the same month of the same unit hydrograph. The last row read wins; the earlier ones are discarded. + +WARNING 101: Time Series xxx has duplicate x values. +The series repeats a time or an abscissa. Interpolation uses the first of each duplicate, which is rarely what was meant. + +WARNING 102: boundary regions overlap for xxx. +Two boundary-condition regions cover the same mesh edges. The later assignment wins on the overlap. + +WARNING 103: [FILES] xxx is not supported and was ignored. +The named interface-file slot is not implemented by this build. The run continues without it, so results will differ from one where the file was read. + +WARNING 104: [2D_OPTIONS] xxx retired with CVODE/ARKODE and was ignored. +The option belonged to a solver that has been removed. Delete it from the input file. + +WARNING 105: xxx has no effect under FLOW_ROUTING FV. +The option is meaningful only for another routing method and is being ignored. + +WARNING 106: xxx is a dynamic wave option and does not apply under FLOW_ROUTING FV. +The option configures dynamic-wave routing; the finite-volume solver has its own controls. + +WARNING 107: unreadable row(s) skipped in rainfall CSV for Rain Gage xxx. +One or more rows of an external rainfall CSV could not be parsed and were skipped. The gage still runs on the rows that were readable, so check the total depth before trusting the result. + +WARNING 108: slot width cap overrides FV_SLOT_CELERITY for xxx. +The Preissmann slot width computed from FV_SLOT_CELERITY exceeded the cap of 5 % of the conduit's top width and was clamped to it. diff --git a/docs/manuals/engine/sections/Chapter1-ConceptualModel.md b/docs/manuals/engine/sections/Chapter1-ConceptualModel.md new file mode 100644 index 000000000..8e1333b1e --- /dev/null +++ b/docs/manuals/engine/sections/Chapter1-ConceptualModel.md @@ -0,0 +1,1089 @@ +@page engine_manual_ch1_conceptual_model CHAPTER 1 - The Conceptual Model + +@tableofcontents + +--- + +This chapter discusses how SWMM models the objects and operational parameters that constitute a stormwater drainage system. Details about how this information is entered into the program are presented in later chapters. An overview is also given on the computational methods that SWMM uses to simulate the hydrology, hydraulics and water quality behavior of a drainage system. + +## Introduction + +SWMM conceptualizes a drainage system as a series of water and material flows between several major environmental compartments. These compartments and the SWMM objects they contain include: +- The Atmosphere compartment, which generates precipitation and deposits pollutants onto the land surface compartment. SWMM uses Rain Gage objects to represent rainfall inputs to the system. +- The Land Surface compartment, which is represented through one or more Subcatchment objects. It receives precipitation from the Atmospheric compartment in the form of rain or snow; it sends outflow in the form of infiltration to the Groundwater compartment and also as surface runoff and pollutant loadings to the Transport compartment. +- The Groundwater compartment receives infiltration from the Land Surface compartment and transfers a portion of this inflow to the Transport compartment. This compartment is modeled using Aquifer objects. +- The Transport compartment contains a network of conveyance elements (channels, pipes, pumps, and regulators) and storage/treatment units that transport water to outfalls or to treatment facilities. Inflows to this compartment can come from surface runoff, groundwater interflow, sanitary dry weather flow, or from user-defined hydrographs. The components of the Transport compartment are modeled with Node and Link objects + +Not all compartments need appear in a particular SWMM model. For example, one could model just the transport compartment, using pre-defined hydrographs as inputs. + +Figure 1-1 maps the compartments, the processes inside each of them and the +alternative formulations OpenSWMM offers for those processes. Every +alternative carries its status — Implemented, Experimental, Planned or +Retired — in the same vocabulary the tables of this manual use. + +![Figure 1-1 Compartments, processes and the formulations that represent them](figures/png/eng_conceptual_map.png) + +*Figure 1-1 Compartments, processes and the formulations that represent them* + +
+@ref hydrology_ref_ch2_meteorology "Precipitation" +@ref engine_manual_sect_RAINGAGES "rain gages" +@ref hydrology_ref_ch6_snowmelt "rain · snow split (SCF)" +@ref hydrology_ref_ch2_meteorology "scale factors" +@ref hydrology_ref_ch2_meteorology "Climate" +@ref engine_manual_sect_TEMPERATURE "temperature" +@ref engine_manual_sect_EVAPORATION "evaporation: constant · monthly · series · Hargreaves · file" +@ref engine_manual_sect_TEMPERATURE "wind" +@ref hydrology_ref_ch2_meteorology "humidity · dew point" +@ref hydrology_ref_ch2_meteorology "prescribed PET (API)" +@ref hydrology_ref_ch6_snowmelt "Snowmelt" +@ref hydrology_ref_ch6_snowmelt "degree-day · heat budget · areal depletion" +@ref hydrology_ref_ch3_surface_runoff "Runoff" +@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir" +@ref engine_manual_sect_SUBAREAS "depression storage" +@ref engine_manual_sect_SUBAREAS "routing to another subcatchment" +@ref hydrology_ref_ch4_infiltration "Infiltration" +@ref hydrology_ref_ch4_infiltration "Horton" +@ref hydrology_ref_ch4_infiltration "modified Horton" +@ref hydrology_ref_ch4_infiltration "Green-Ampt" +@ref hydrology_ref_ch4_infiltration "modified Green-Ampt" +@ref hydrology_ref_ch4_infiltration "curve number" +@ref quality_ref_ch6_lid_controls "LID controls" +@ref quality_ref_ch6_lid_controls "layered units (8 types)" +@ref quality_ref_ch6_lid_controls "LID as storage nodes" +@ref quality_ref_ch6_lid_controls "detailed output" +@ref quality_ref_ch3_pollutant_buildup "Surface quality" +@ref quality_ref_ch3_pollutant_buildup "buildup · washoff by land use" +@ref engine_manual_sect_LANDUSES "street sweeping" +@ref quality_ref_ch10_mesh_quality "MSX species" +@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh" +@ref hydrology_ref_ch8_mesh_surface "natural neighbour" +@ref engine_manual_sect_2D_OPTIONS "system" +@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration" +@ref hydrology_ref_ch8_mesh_surface "Horton · Green-Ampt · CN · constant" +@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment aquifer · mesh aquifer" +@ref hydraulics_ref_ch9_two_dimensional "Overland flow" +@ref hydraulics_ref_ch9_two_dimensional "local inertial" +@ref hydraulics_ref_ch9_two_dimensional "full shallow water" +@ref hydraulics_ref_ch9_two_dimensional "diffusive wave" +@ref hydraulics_ref_ch10_planned "IMEX / CVODE" +@ref hydraulics_ref_ch9_two_dimensional "Mesh and closure" +@ref hydraulics_ref_ch9_two_dimensional "triangles" +@ref hydraulics_ref_ch9_two_dimensional "quads" +@ref hydraulics_ref_ch9_two_dimensional "flat cells" +@ref hydraulics_ref_ch9_two_dimensional "VFR closure" +@ref quality_ref_ch10_mesh_quality "Surface quality · transport" +@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff" +@ref quality_ref_ch10_mesh_quality "species on the mesh" +@ref hydraulics_ref_ch9_two_dimensional "Backends" +@ref hydraulics_ref_ch9_two_dimensional "CPU" +@ref hydraulics_ref_ch9_two_dimensional "OpenMP" +@ref hydraulics_ref_ch9_two_dimensional "CUDA · HIP · SYCL" +@ref hydraulics_ref_ch10_planned "Metal" +@ref hydrology_ref_ch5_groundwater "Two-zone aquifer" +@ref hydrology_ref_ch5_groundwater "unsaturated + saturated zone" +@ref engine_manual_sect_AQUIFERS "percolation · deep percolation · ET" +@ref engine_manual_sect_GWF "lateral interflow, user [GWF]" +@ref hydrology_ref_ch9_mesh_groundwater "Groundwater transport" +@ref hydrology_ref_ch9_mesh_groundwater "advection–dispersion · heat" +@ref hydrology_ref_ch9_mesh_groundwater "Two-layer aquifer" +@ref hydrology_ref_ch9_mesh_groundwater "Gardner" +@ref hydrology_ref_ch9_mesh_groundwater "Russo" +@ref hydrology_ref_ch9_mesh_groundwater "Brooks–Corey" +@ref hydrology_ref_ch9_mesh_groundwater "van Genuchten" +@ref hydrology_ref_ch9_mesh_groundwater "closed form · enslaved · σ column" +@ref hydrology_ref_ch9_mesh_groundwater "Dunne return flow" +@ref hydrology_ref_ch9_mesh_groundwater "node–bed exchange" +@ref hydrology_ref_ch9_mesh_groundwater "capillary rise · boundary ET" +@ref hydrology_ref_ch9_mesh_groundwater "per-subcatchment mode" +@ref engine_manual_sect_JUNCTIONS "Nodes" +@ref engine_manual_sect_JUNCTIONS "junction · storage · divider · outfall" +@ref hydraulics_ref_ch3_dynamic_wave "virtual junction" +@ref hydraulics_ref_ch7_advanced_features "inlet junction" +@ref engine_manual_sect_CONDUITS "Links" +@ref hydraulics_ref_ch5_cross_section "conduits, 26 sections" +@ref hydraulics_ref_ch5_cross_section "street · dummy" +@ref hydraulics_ref_ch10_planned "Chebyshev irregular" +@ref engine_manual_sect_PUMPS "pumps · orifices · weirs · outlets · culverts" +@ref hydraulics_ref_ch5_cross_section "storage shapes" +@ref hydraulics_ref_ch7_advanced_features "HEC-22 inlets" +@ref hydraulics_ref_ch2_hydraulic_model "Flow routing" +@ref hydraulics_ref_ch2_hydraulic_model "steady" +@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave" +@ref hydraulics_ref_ch8_finite_volume "finite volume" +@ref hydraulics_ref_ch8_lts "local time stepping" +@ref hydraulics_ref_ch10_planned "1D GPU backend" +@ref hydraulics_ref_ch3_dynamic_wave "Pressurisation" +@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN" +@ref hydraulics_ref_ch3_dynamic_wave "slot" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic slot" +@ref hydraulics_ref_ch3_dynamic_wave "TPA" +@ref hydraulics_ref_ch8_finite_volume "FV: slot" +@ref hydraulics_ref_ch8_finite_volume "FV: TPA" +@ref hydraulics_ref_ch8_finite_volume "FV: implicit head" +@ref hydraulics_ref_ch3_dynamic_wave "unsteady friction" +@ref hydraulics_ref_ch3_dynamic_wave "Node solution" +@ref hydraulics_ref_ch3_dynamic_wave "explicit continuity" +@ref hydraulics_ref_ch3_dynamic_wave "semi-implicit continuity" +@ref hydraulics_ref_ch3_anderson "Anderson acceleration" +@ref hydraulics_ref_ch10_planned "FV_NODE_* keys" +@ref quality_ref_ch5_transport_treatment "Transport" +@ref quality_ref_ch5_transport_treatment "CSTR" +@ref quality_ref_ch7_ard_transport "Eulerian ARD" +@ref quality_ref_ch7_ard_transport "Lagrangian LARD" +@ref quality_ref_ch7_ard_transport "random-walk dispersion" +@ref quality_ref_ch5_transport_treatment "first-order decay" +@ref quality_ref_ch8_msx_reactions "MSX reactions" +@ref quality_ref_ch9_age_heat "water age" +@ref quality_ref_ch9_age_heat "heat" +@ref quality_ref_ch11_planned "sediment" +@ref engine_manual_sect_TREATMENT "treatment functions" +@ref engine_manual_sect_INFLOWS "Inflows" +@ref engine_manual_sect_DWF "dry weather flow" +@ref hydrology_ref_ch7_rdii "RDII: RTK" +@ref hydrology_ref_ch7_rdii "RDII: IA decay" +@ref engine_manual_sect_INFLOWS "user · interface files" +@ref engine_manual_sect_CONTROLS "control rules" +
+ + + + +## Visual Objects + +Figure 1-2 depicts how a collection of OpenSWMM’s visual objects might be arranged together to represent a stormwater drainage system. These objects can be displayed on a map in the SWMM workspace. The following sections describe each of these objects. + + +![Figure 1-2 Objects of an OpenSWMM model](figures/png/eng_object_sketch.png) + +*Figure 1-2 Objects of an OpenSWMM model* + +
+@ref engine_manual_sect_RAINGAGES "Rain gage" +@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S1" +@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S2" +@ref engine_manual_sect_JUNCTIONS "Junction" +@ref engine_manual_sect_CONDUITS "Conduit" +@ref engine_manual_sect_VIRTUAL_JUNCTIONS "Virtual junction" +@ref engine_manual_sect_INLET_JUNCTIONS "Inlet junction" +@ref engine_manual_sect_STREETS "Street conduit" +@ref engine_manual_sect_DIVIDERS "Divider" +@ref engine_manual_sect_WEIRS "Weir" +@ref engine_manual_sect_ORIFICES "Orifice" +@ref engine_manual_sect_STORAGE "Storage unit" +@ref engine_manual_sect_PUMPS "Pump" +@ref engine_manual_sect_OUTFALLS "Outfall" +@ref engine_manual_sect_2D_TRIANGLES "2D mesh" +@ref engine_manual_sect_2D_VERTEX_NODE_MAP "1D–2D exchange" +
+ +### Rain Gages + +Rain Gages supply precipitation data for one or more subcatchment areas in a study region. The rainfall data can be either a user-defined time series or come from an external file. Several different popular rainfall file formats currently in use are supported, as well as a standard user-defined format. More details on these formats are presented in @ref engine_manual_ch3_files. + +The principal input properties of rain gages include: +- rainfall data type (e.g., intensity, volume, or cumulative volume) +- recording time interval (e.g., hourly, 15-minute, etc.) +- source of rainfall data (input time series or external file) +- name of rainfall data source + +### Subcatchments + +Subcatchments are hydrologic units of land whose topography and drainage system elements direct surface runoff to a single discharge point. The user is responsible for dividing a study area into an appropriate number of subcatchments, and for identifying the outlet point of each subcatchment. Discharge outlet points can be either nodes of the drainage system or other subcatchments. + +Subcatchments are divided into pervious and impervious subareas. Surface runoff can infiltrate into the upper soil zone of the pervious subarea, but not through the impervious subarea. Impervious areas are themselves divided into two subareas - one that contains depression storage and another that does not. Runoff flow from one subarea in a subcatchment can be routed to the other subarea, or both subareas can drain to the subcatchment outlet. + +Infiltration of rainfall from the pervious area of a subcatchment into the unsaturated upper soil zone can be described using five different models: +- Classic Horton infiltration +- Modified Horton infiltration +- Green-Ampt infiltration +- Modified Green-Ampt infiltration +- SCS Curve Number infiltration + +To model the accumulation, re-distribution, and melting of precipitation that falls as snow on a subcatchment, it must be assigned a Snow Pack object. To model groundwater flow between an aquifer underneath the subcatchment and a node of the drainage system, the subcatchment must be assigned a set of Groundwater parameters. Pollutant buildup and washoff from subcatchments are associated with the Land Uses assigned to the subcatchment. Capture and retention of rainfall/runoff using different types of low impact development practices (such as bio-retention cells, infiltration trenches, porous pavement, vegetative swales, and rain barrels) can be modeled by assigning a set of pre-designed LID controls to the subcatchment. + +The other principal input parameters for subcatchments include: +- assigned rain gage +- outlet node or subcatchment +- total area +- percent imperviousness area +- average slope +- characteristic width of overland flow +- Manning's roughness (n) for overland flow on both pervious and impervious areas +- depression storage in both pervious and impervious areas +- percent of impervious area with no depression storage. + +### Junction Nodes + +Junctions are drainage system nodes where links join together. Physically they can represent the confluence of natural surface channels, manholes in a sewer system, or pipe connection fittings. External inflows can enter the system at junctions. Excess water at a junction can become partially pressurized while connecting conduits are surcharged and can either be lost from the system or be allowed to pond atop the junction and subsequently drain back into the junction. + +The principal input parameters for a junction are: +- invert (channel or manhole bottom) elevation +- height to ground surface +- ponded surface area when flooded (optional) +- external inflow data (optional). + +### Outfall Nodes + +Outfalls are terminal nodes of the drainage system used to define final downstream boundaries under Dynamic Wave flow routing. For other types of flow routing they behave as a junction. Only a single link can be connected to an outfall node, and the option exists to have the outfall discharge onto a subcatchment's surface. + +The boundary conditions at an outfall can be described by any one of the following stage relationships: +- the critical or normal flow depth in the connecting conduit +- a fixed stage elevation +- a tidal stage described in a table of tide height versus hour of the day +- a user-defined time series of stage versus time. + +The principal input parameters for outfalls include: +- invert elevation +- boundary condition type and stage description +- presence of a flap gate to prevent backflow through the outfall. +Flow Divider Nodes + +Flow Dividers are drainage system nodes that divert inflows to a specific conduit in a prescribed manner. A flow divider can have no more than two conduit links on its discharge side. Flow dividers are only active under Steady Flow and Kinematic Wave routing and are treated as simple junctions under Dynamic Wave routing. + +There are four types of flow dividers, defined by the manner in which inflows are diverted: + +Cutoff Divider: diverts all inflow above a defined cutoff value. +Overflow Divider: diverts all inflow above the flow capacity of the non-diverted conduit. +Tabular Divider: uses a table that expresses diverted flow as a function of total inflow. +Weir Divider: uses a weir equation to compute diverted flow. + +The flow diverted through a weir divider is computed by the following equation + +\f[ +Q_{div} = C_W \left( f H_W \right)^{1.5} +\f] + +where Qdiv = diverted flow, Cw = weir coefficient, Hw = weir height and f is computed as + +\f[ +f = \frac{Q_{in} - Q_{min}}{Q_{max} - Q_{min}} +\f] + +where Qin is the inflow to the divider, Qmin is the flow at which diversion begins, and Q_max=C_W H_W^1.5. The user-specified parameters for the weir divider are Qmin, Hw, and Cw. + +The principal input parameters for a flow divider are: +- junction parameters (see above) +- name of the link receiving the diverted flow +- method used for computing the amount of diverted flow. + +### Storage Units + +Storage Units are drainage system nodes that provide storage volume. Physically they could represent storage facilities as small as a catch basin or as large as a lake. The volumetric properties of a storage unit are described by a function or table of surface area versus height. In addition to receiving inflows and discharging outflows to other nodes in the drainage network, storage nodes can also lose water from surface evaporation and from seepage into native soil. + +The principal input parameters for storage units include: +- invert (bottom) elevation +- maximum depth +- depth-surface area data +- evaporation potential +- seepage parameters (optional) +- external inflow data (optional). + +### Conduits + +Conduits are pipes or channels that move water from one node to another in the conveyance system. Their cross-sectional shapes can be selected from a variety of standard open and closed geometries as listed in Table 1-1. + +Most open channels can be represented with a rectangular, trapezoidal, or user-defined irregular cross-section shape. For irregular sections a Transect object is used to define how depth varies with distance across the cross-section (see @ref engine_manual_ch1_conceptual_model below). Most new drainage and sewer pipes are circular while culverts typically have elliptical, rectangular or arch shapes. Elliptical and Arch pipes come in standard sizes that are listed in @ref manual_reference_tables and A.13. The Filled Circular shape allows the bottom of a circular pipe to be filled with sediment and thus limit its flow capacity. The Custom Closed Shape allows any closed geometrical shape that is symmetrical about the center line to be defined by supplying a Shape Curve for the cross section (see @ref engine_manual_ch1_conceptual_model below). + +SWMM uses the Manning equation to express the relationship between flow rate (Q), cross-sectional area (A), hydraulic radius (R), and slope (S) in all conduits. For standard U.S. units, + +\f[ +Q = \frac{1.49}{n} A R^{2/3} S^{1/2} +\f] + +where n is the Manning roughness coefficient. The slope S is interpreted as either the conduit slope or the friction slope (i.e., head loss per unit length), depending on the flow routing method used. + + +Table 1-1 Available cross section shapes for conduits +Name Parameters Shape Name Parameters Shape +Circular Full Height Circular Force Main Full Height, +Roughness +Filled Circular Full Height, +Filled Depth Rectangular - Closed Full Height, +Width +Rectangular – Open Full Height, +Width Trapezoidal Full Height, +Base Width, +Side Slopes +Triangular Full Height, +Top Width Horizontal Ellipse Full Height, +Max. Width +Vertical Ellipse Full Height, +Max. Width Arch Full Height, +Max. Width +Parabolic Full Height, +Top Width Power Full Height, +Top Width, +Exponent +Rectangular-Triangular Full Height, +Top Width, +Triangle Height Rectangular-Round Full Height, +Top Width, +Bottom Radius +Modified Baskethandle Full Height, +Bottom Width, +Top Radius Egg Full Height +Horseshoe Full Height Gothic Full Height +Catenary Full Height Semi-Elliptical Full Height +Baskethandle Full Height Semi-Circular Full Height +Irregular Channel Transect Coordinates Custom Closed Shape Full Height, Shape Curve +Coordinates +Street or Roadway See @ref engine_manual_ch1_conceptual_model + + + +For pipes with Circular Force Main cross-sections either the Hazen-Williams or Darcy-Weisbach formula is used in place of the Manning equation for fully pressurized flow. For U.S. units the Hazen-Williams formula is: + +\f[ +Q = 1.318\, C A R^{0.63} S^{0.54} +\f] + +where C is the Hazen-Williams C-factor which varies inversely with surface roughness and is supplied as one of the cross-section’s parameters. The Darcy-Weisbach formula is: + +\f[ +Q = \sqrt{\frac{8g}{f}}\, A R^{1/2} S^{1/2} +\f] + +where g is the acceleration of gravity and f is the Darcy-Weisbach friction factor. For turbulent flow, the latter is determined from the height of the roughness elements on the walls of the pipe (supplied as an input parameter) and the flow’s Reynolds Number using the Colebrook-White equation. The choice of which equation to use is a user-supplied option. + +- A conduit does not have to be assigned a Force Main shape for it to pressurize. Any of the closed cross-section shapes can potentially pressurize and thus function as force mains that use the Manning equation to compute friction losses. + +A constant rate of exfiltration of water along the length of the conduit can be modeled by supplying a Seepage Rate value (in/hr or mm/hr). This only accounts for seepage losses, not infiltration of rainfall dependent groundwater. The latter can be modeled using SWMM’s RDII feature (see @ref engine_manual_ch1_conceptual_model). + +A conduit can also be designated to act as a culvert (see Figure 1-4) if a Culvert Inlet Geometry code number is assigned to it. These code numbers are listed in @ref manual_reference_tables. Culvert conduits are checked continuously during dynamic wave flow routing to see if they operate under Inlet Control as defined in the Federal Highway Administration’s publication Hydraulic Design of Highway Culverts Third Edition (Publication No. FHWA-HIF-12-026, April 2012). Under inlet control a culvert obeys a particular flow versus inlet depth rating curve whose shape depends on the culvert’s shape, size, slope, and inlet geometry. + +Street and channel conduits with storm drain inlet structures (see Figure 1-5) use the methods described in the Federal Highway Administration's publication Urban Drainage Design Manual - HEC-22 (Publication No. FHWA-NHI-10-009, August 2013) to determine the amount of flow they capture. + + +![Figure 1-4 Concrete box culvert](figures/fig3-02-box-culvert.jpg) + +*Figure 1-4 Concrete box culvert* + +![Figure 1-5 Storm drain inlet](figures/fig3-03-storm-drain-inlet.png) + +*Figure 1-5 Storm drain inlet* + +The principal input parameters for conduits are: +- names of the inlet and outlet nodes +- offset height or elevation above the inlet and outlet node inverts +- length +- Manning's roughness coefficient (n) +- cross-sectional geometry +- entrance/exit losses (optional) +- seepage rate (optional) +- presence of a flap gate to prevent reverse flow (optional) +- culvert type code number if the conduit acts as a culvert (optional) +- name of any inlet structure placed in a street or channel conduit (optional). + + +### Pumps + +Pumps are links used to lift water to higher elevations. A pump curve describes the relation between a pump's flow rate and conditions at its inlet and outlet nodes. Five different types of pump curves are supported: + +Type1 (Fixed/Volume) +Consists of a series of constant flow rates that apply over a series of volume intervals at the pump’s inlet node. +Type2 (Fixed/Depth) +Similar to a Type1 pump except that the fixed flow rate levels vary over a set of depth intervals at the pump’s inlet node. +Type3 (Variable/Head) +Uses a pump characteristic curve at some nominal impeller speed to relate flow rate and delivered head. +Type4 (Variable/Depth) +A variable speed pump where flow varies continuously with inlet node water depth. + +Type5 (Variable/Affinity) +A variable speed version of the Type3 pump where the pump curve shifts position when control rules change the pump’s relative speed setting (see @ref engine_manual_ch1_conceptual_model). + +SWMM also supports an "Ideal" transfer pump that does not require a pump curve and is used mainly for preliminary analysis. Its flow rate equals the inflow rate to its inlet node no matter what the head difference is between its inlet and outlet nodes. + +The on/off status of pumps can be controlled dynamically by specifying startup and shutoff water depths at the inlet node or through user-defined Control Rules. Rules can also be used to simulate variable speed drives that modulate pump flow. For a Type 5 pump, its operating curve shifts position such that flow changes in direct proportion to the controlled speed setting while head changes in proportion to the setting squared. + +The principal input parameters for a pump include: +- names of its inlet and outlet nodes +- name of its pump curve (or * for an Ideal pump) +- initial on/off status +- startup and shutoff depths (optional). + +### Flow Regulators + +Flow Regulators are structures or devices used to control and divert flows within a conveyance system. They are typically used to: +- control releases from storage facilities +- prevent unacceptable surcharging +- divert flow to treatment facilities and interceptors + +SWMM can model the following types of flow regulators: Orifices, Weirs, and Outlets. + +### Orifices + +Orifices are used to model outlet and diversion structures in drainage systems, which are typically openings in the wall of a manhole, storage facility, or control gate. They are internally represented in SWMM as a link connecting two nodes. An orifice can have either a circular or rectangular shape, be located either at the bottom or along the side of the upstream node, and have a flap gate to prevent backflow. + +Orifices can be used as storage unit outlets under all types of flow routing. If not attached to a storage unit node, they can only be used in drainage networks that are analyzed with Dynamic Wave flow routing. + +The flow through a fully submerged orifice is computed as +Q=CA√2gh +where Q = flow rate, C = discharge coefficient, A = area of orifice opening, g = acceleration of gravity, and h = head difference across the orifice. The height of an orifice's opening can be controlled dynamically through user-defined Control Rules. This feature can be used to model gate openings and closings. Flow through a partially full orifice is computed using an equivalent weir equation. + +The principal input parameters for an orifice include: +- names of its inlet and outlet nodes +- configuration (bottom or side) +- shape (circular or rectangular) +- height or elevation above the inlet node invert +- discharge coefficient +- time to open or close (optional). + +### Weirs + +Weirs, like orifices, are used to model outlet and diversion structures in a drainage system. Weirs are typically located across a channel, along its side, or at the top of a storage unit. They are internally represented in SWMM as a link connecting two nodes, where the weir itself is placed at the upstream node. A flap gate can be included to prevent backflow. + +Five varieties of weirs are available, each incorporating a different formula for computing flow across the weir as listed in Table 1-2. + +Table 1-2 Available types of weirs +Weir Type Cross Section Shape Flow Formula +Transverse Rectangular C_W Lh^(3/2) +Side flow Rectangular C_W Lh^(5/3) +V-notch Triangular C_W Sh^(5/2) +Trapezoidal Trapezoidal C_W Lh^(3/2)+C_WS Sh^(5/2) +Roadway Rectangular C_W Lh^(3/2) +Cw = weir discharge coefficient, L = weir length, S = side slope of +V-notch or trapezoidal weir, h = head difference across the weir, +Cws = discharge coefficient through sides of trapezoidal weir. + +The Roadway weir is a broad crested rectangular weir used model roadway crossings usually in conjunction with culvert-type conduits (see Figure 1-4). It uses curves from the Federal Highway Administration publication Hydraulic Design of Highway Culverts Third Edition (Publication No. FHWA-HIF-12-026, April 2012) to determine CW as a function of h and roadway width. + +Weirs can be used as storage unit outlets under all types of flow routing. If not attached to a storage unit, they can only be used in drainage networks that are analyzed with Dynamic Wave flow routing. + +The height of the weir crest above the inlet node invert can be controlled dynamically through user-defined Control Rules. This feature can be used to model inflatable dams. + +Weirs can either be allowed to surcharge or not. A surcharged weir will use an equivalent orifice equation to compute the flow through it. Weirs placed in open channels would normally not be allowed to surcharge while those placed in closed diversion structures or those used to represent storm drain inlet openings would be allowed to. + +The principal input parameters for a weir include: +- names of its inlet and outlet nodes +- shape and geometry +- crest height or elevation above the inlet node invert +- discharge coefficient. + +### Outlets + +Outlets are flow control devices that are typically used to control outflows from storage units. They are used to model special head-discharge relationships that cannot be characterized by pumps, orifices, or weirs. Outlets are internally represented in SWMM as a link connecting two nodes. An outlet can also have a flap gate that restricts flow to only one direction. + +Outlets attached to storage units are active under all types of flow routing. If not attached to a storage unit, they can only be used in drainage networks analyzed with Dynamic Wave flow routing. + +A user-defined rating curve determines an outlet's discharge flow as a function of either the freeboard depth above the outlet's opening or the head difference across it. Control Rules can be used to dynamically adjust this flow when certain conditions exist. + +The principal input parameters for an outlet include: +- names of its inlet and outlet nodes +- height or elevation above the inlet node invert +- function or table containing its head (or depth) - discharge relationship. + +### Map Labels + +Map Labels were optional text annotations carried in the `[LABELS]` section. The engine parses the section and discards it; annotations are a concern of the graphical client, which stores its own. See @ref manual_map_editing. + +## Non-Visual Objects + +In addition to physical objects that can be displayed visually on a map, SWMM utilizes several classes of non-visual data objects to describe additional characteristics and processes within a study area. + +### Climatology + +### Temperature + +Air temperature data are used when simulating snowfall and snowmelt processes during runoff calculations. They can also be used to compute daily evaporation rates. If these processes are not being simulated then temperature data are not required. Air temperature data can be supplied to SWMM from one of the following sources: +- a user-defined time series of point values (values at intermediate times are interpolated) +- an external climate file containing daily minimum and maximum values (SWMM fits a sinusoidal curve through these values depending on the day of the year). +For user-defined time series, temperatures are in degrees F for US units and degrees C for metric units. The external climate file can also be used to directly supply evaporation and wind speed as well. + +### Evaporation + +Evaporation can occur for standing water on subcatchment surfaces, for subsurface water in groundwater aquifers, for water traveling through open channels, and for water held in storage units. Evaporation rates can be stated as: +- a single constant value +- a set of monthly average values +- a user-defined time series of values +- values computed from the daily temperatures contained in an external climate file +- daily values read directly from an external climate file. +These values represent potential rates. The actual amount of water evaporated will depend on the amount available. + +If rates are read directly from a climate file, then a set of monthly pan coefficients should also be supplied to convert the pan evaporation data to free water-surface values. An option is also available to allow evaporation only during periods with no precipitation. + +### Wind Speed + +Wind speed is an optional climatic variable that is used only for snowmelt calculations. SWMM can use either a set of monthly average speeds or wind speed data contained in the same climate file used for daily minimum/maximum temperatures. + +### Snowmelt + +Snowmelt parameters are climatic variables that apply across the entire study area when simulating snowfall and snowmelt. They include: +- the air temperature at which precipitation falls as snow +- heat exchange properties of the snow surface +- study area elevation, latitude, and longitude correction + +### Areal Depletion + +Areal depletion refers to the tendency of accumulated snow to melt non-uniformly over the surface of a subcatchment. As the melting process proceeds, the area covered by snow gets reduced. This behavior is described by an Areal Depletion Curve that plots the fraction of total area that remains snow covered against the ratio of the actual snow depth to the depth at which there is 100% snow cover. A typical ADC for a natural area is shown in Figure 1-6. Two such curves can be supplied to SWMM, one for impervious areas and another for pervious areas. + + +![Figure 1-6 Areal depletion curve for a natural area](figures/png/hydrology_ch6_areal_depletion_curve.png) + +*Figure 1-6 Areal depletion curve for a natural area* + +### Climate Adjustments + +Climate Adjustments are optional modifications applied to the temperature, evaporation rate, and rainfall intensity that SWMM would otherwise use at each time step of a simulation. Separate sets of adjustments that vary periodically by month of the year can be assigned to these variables. They provide a simple way to examine the effects of future climate change without having to modify the original climatic time series. + +A set of monthly adjustments can also be applied to the hydraulic conductivity used in computing rainfall infiltration on all pervious land surfaces, including those in all LID units, and for exfiltration from all storage nodes and conduits. These can reflect the increase of hydraulic conductivity with increasing temperature or the effect that seasonal changes in land surface conditions, such as frozen ground, can have on infiltration capacity. They can be overridden for individual subcatchments (and their LID units) by assigning a monthly infiltration adjustment Time Pattern to a subcatchment. Monthly adjustment time patterns for depression storage and pervious surface roughness coefficient (Mannings n) can also be specified for individual subcatchments + + + +### Snow Packs + +Snow Pack objects contain parameters that characterize the buildup, removal, and melting of snow over three types of subareas within a subcatchment: +- The Plowable snow pack area consists of a user-defined fraction of the total impervious area. It is meant to represent such areas as streets and parking lots where plowing and snow removal can be done. +- The Impervious snow pack area covers the remaining impervious area of a subcatchment. +- The Pervious snow pack area encompasses the entire pervious area of a subcatchment. + +Each of these three areas is characterized by the following parameters: +- minimum and maximum snow melt coefficients +- minimum air temperature for snow melt to occur +- snow depth above which 100% areal coverage occurs +- initial snow depth +- initial and maximum free water content in the pack. + +In addition, a set of snow removal parameters can be assigned to the Plowable area. These parameters consist of the depth at which snow removal begins and the fractions of snow moved onto various other areas. + +Subcatchments are assigned a snow pack object through their Snow Pack property. A single snow pack object can be applied to any number of subcatchments. Assigning a snow pack to a subcatchment simply establishes the melt parameters and initial snow conditions for that subcatchment. Internally, SWMM creates a "physical" snow pack for each subcatchment, which tracks snow accumulation and melting for that particular subcatchment based on its snow pack parameters, its amount of pervious and impervious area, and the precipitation history it sees. + +### Aquifers + +Aquifers are sub-surface groundwater zones used to model the vertical movement of water infiltrating from the subcatchments that lie above them. They also permit the infiltration of groundwater into the drainage system, or exfiltration of surface water from the drainage system, depending on the hydraulic gradient that exists. Aquifers are only required in models that need to explicitly account for the exchange of groundwater with the drainage system or to establish base flow and recession curves in natural channels and non-urban systems. The parameters of an aquifer object can be shared by several subcatchments but there is no exchange of groundwater between subcatchments. A drainage system node can exchange groundwater with more than one subcatchment. + +Aquifers are represented using two zones – an un-saturated zone and a saturated zone. Their behavior is characterized using such parameters as soil porosity, hydraulic conductivity, evapotranspiration depth, bottom elevation, and loss rate to deep groundwater. In addition, the initial water table elevation and initial moisture content of the unsaturated zone must be supplied. + +Aquifers are connected to subcatchments and to drainage system nodes through a subcatchment's Groundwater Flow property. This property also contains parameters that govern the rate of groundwater flow between the aquifer's saturated zone and the drainage system node. + +### Unit Hydrographs + +Unit Hydrographs (UHs) estimate rainfall-dependent infiltration and inflow (RDII) into a sewer system. A UH set contains up to three such hydrographs, one for a short-term response, one for an intermediate-term response, and one for a long-term response. A UH group can have up to 12 UH sets, one for each month of the year. Each UH group is considered as a separate object by SWMM, and is assigned its own unique name along with the name of the rain gage that supplies rainfall data to it. + +Each unit hydrograph, as shown in Figure 1-7, is defined by three parameters: +- R: the fraction of rainfall volume that enters the sewer system +- T: the time from the onset of rainfall to the peak of the UH in hours +- K: the ratio of time to recession of the UH to the time to peak + +A unit hydrograph can also have a set of Initial Abstraction (IA) parameters associated with it. These determine how much rainfall is lost to interception and depression storage before any excess rainfall is generated and transformed into RDII flow by the hydrograph. The IA parameters consist of: +- a maximum possible depth of IA (inches or mm), +- a recovery rate (inches/day or mm/day) at which stored IA is depleted during dry periods, +- an initial depth of stored IA (inches or mm). + + +![Figure 1-7 An RDII unit hydrograph](figures/png/eng_rdii_unit_hydrograph.png) + +*Figure 1-7 An RDII unit hydrograph* + +To generate RDII into a drainage system node, the node must identify (through its Inflows property) the UH group and the area of the surrounding sewershed that contributes RDII flow. + +- An alternative to using unit hydrographs to define RDII flow is to create an external RDII interface file, which contains RDII time series data. See @ref engine_manual_ch3_files. + +- Unit hydrographs could also be used to replace SWMM's main rainfall-runoff process that uses Subcatchment objects, provided that properly calibrated UHs are utilized. In this case what SWMM calls RDII inflow to a node would actually represent overland runoff. + +### Transects + +Transects refer to the geometric data that describe how bottom elevation varies with horizontal distance over the cross-section of a natural channel or irregular-shaped conduit. Figure 1-8 displays an example transect for a natural channel. + +Each transect must be given a unique name. Conduits refer to that name to represent their shape. A special Transect Editor is available for editing the station-elevation data of a transect. SWMM internally converts these data into tables of area, top width, and hydraulic radius versus channel depth. In addition, as shown in Figure 1-8, each transect can have a left and right overbank section whose Manning's roughness coefficient can be different from that of the main channel. This feature can provide more realistic estimates of channel conveyance under high flow conditions. + + +![Figure 1-8 Example of a natural channel transect](figures/fig3-06-natural-transect.jpg) + +*Figure 1-8 Example of a natural channel transect* + +### Streets + +Streets are a specialized form of transect that describes the typical cross-section geometry of a street or roadway. The Figure 1-9 shows a half-street layout along with the dimensions a user needs to provide. + + +![Figure 1-9 Definitional sketch of a street cross-section](figures/png/hydraulics_ch5_street_section.png) + +*Figure 1-9 Definitional sketch of a street cross-section* + +Each street section object is assigned an ID name that a conduit can refer to for describing its cross-section geometry. A Street Section Editor is available for providing a street section's dimensions and whether it is one-sided or two-sided. +Inlets + +Street inlets are curb and gutter openings that convey runoff from streets into below-ground sewers. Drop inlets serve a similar purpose for open rectangular and trapezoidal channels. SWMM can compute the amount of flow captured by inlets and sent to designated sewer nodes using the U.S. Federal Highway Administration’s HEC-22 methodology . The type, sizing, and spacing of street inlets will determine if the spread and depth of water on roadways can be maintained at acceptable levels. + +To analyze street drainage with SWMM a site is represented as a dual drainage system consisting of both street conduits along the ground surface and sewer conduits below ground (see Figure 1-10). An inlet structure will divert some portion of the street flow it carries into a designated node of the sewer system with the rest bypassed to downstream street conduits. When an inlet’s sewer node reaches its full depth any excess sewer flow that causes it to flood is routed back into the street's downstream node rather than having it leave the system as it normally would. + +![Figure 1-10 Representation of a dual drainage system](figures/fig3-08-dual-drainage.png) + +*Figure 1-10 Representation of a dual drainage system* + +As shown in Figure 1-10, inlets can be located either on a continuous sloping section of roadway (on-grade, sometimes referred to as a flow-by condition) or at a low point where flow tends to pool (on-sag, sometimes referred to as a sump condition). + +SWMM’s HEC-22 inlet capture equations support the inlet types shown in Figure 1-11. Drop inlets can only be used with open rectangular or trapezoidal channels while the other curb and gutter inlets can only be placed in conduits with Street cross-sections. An additional Custom type of inlet can be used in both streets and channels. Its capture efficiency is described by either a user-supplied Diversion curve (captured flow versus approach flow) or Rating curve (captured flow versus flow depth). + +![Figure 1-11 HEC-22 inlets supported by SWMM](figures/fig3-09-hec22-inlets.png) + +*Figure 1-11 HEC-22 inlets supported by SWMM* + +To add an analysis of street inlets to a SWMM project: +- Create one network layout for streets and another for sewers. +- Create a collection of street cross-section objects. +- For each street conduit, set its Shape property to one of the available street sections. +- Create a set of inlet structure design objects. +- Place a particular inlet structure design into a selected street conduit, assigning it a sewer node that receives its captured flow. +- Assign surface runoff from subcatchments or other external inflows to street conduit nodes. +A similar set of steps would be used to add drop inlets into open rectangular or trapezoidal channels. A summary of results for each street conduit (maximum flow depth and pavement spread) and for each inlet (percent capture at peak flow, frequency of bypass flow and frequency of sewer system backflow) will appear as a separate Street Flow table in SWMM's Summary Results report. +Some additional considerations when modeling inlets are: +- A conduit that carries an inlet diverts captured flow to the inlet's capture node; the two are not connected by a link. +- The rim elevations of nodes that receive captured inlet flow do not have to match the invert elevations of the end node of the conduit containing the inlet. +- Two-sided street conduits (that are symmetric about the street crown) use pairs of inlets placed on each curb side of the street. +- Multiple inlets of the same design can be assigned to a conduit (as pairs for two-sided streets). For on-grade placement the flow captured by each inlet is determined sequentially, so that the approach flow to the next inlet in line is the bypass flow from the inlet before it. +- Flow captured by inlets is limited by the amount that its sewer node can receive before it floods. If the node has no such capacity remaining then any excess flow that would cause it to flood is routed back through the inlet and onto the street. +- Users can stipulate whether an inlet operates on-grade or on-sag or have SWMM decide based on the slopes of the conduits adjoining it. (On-sag refers to a sump or low point that all adjoining conduits slope towards.) +- Inlets can have a degree of clogging and a flow capture restriction assigned to them. +- For Kinematic Wave and Steady Flow routing it is recommended that storage nodes be used at the end of inlet conduits that converge at sag points since otherwise any non-captured flow will simply exit the system. This is not necessary for Dynamic Wave routing as any non-captured water will create a backwater effect raising water levels in the adjoining street conduits. + +### External Inflows + +In addition to inflows originating from subcatchment runoff and groundwater, drainage system nodes can receive three other types of external inflows: +- Direct Inflows - These are user-defined time series of inflows added directly into a node. They can be used to perform flow and water quality routing in the absence of any runoff computations (as in a study area where no subcatchments are defined). +- Dry Weather Inflows - These are continuous inflows that typically reflect the contribution from sanitary sewage in sewer systems or base flows in pipes and stream channels. They are represented by an average inflow rate that can be periodically adjusted on a monthly, daily, and hourly basis by applying Time Pattern multipliers to this average value. +- Rainfall-Dependent Infiltration and Inflow (RDII) - These are stormwater flows that enter sanitary or combined sewers due to "inflow" from direct connections of downspouts, sump pumps, foundation drains, etc. as well as "infiltration" of subsurface water through cracked pipes, leaky joints, poor manhole connections, etc. RDII can be computed for a given rainfall record based on set of triangular unit hydrographs (UH) that determine a short-term, intermediate-term, and long-term inflow response for each time period of rainfall. Any number of UH sets can be supplied for different sewershed areas and different months of the year. RDII flows can also be specified in an external RDII interface file. + +Direct, Dry Weather, and RDII inflows are properties associated with each type of drainage system node (junctions, outfalls, flow dividers, and storage units) and can be specified when nodes are edited. They can be used to perform flow and water quality routing in the absence of any runoff computations (as in a study area where no subcatchments are defined). It is also possible to make the outflows generated from an upstream drainage system be the inflows to a downstream system by using interface files. See @ref engine_manual_ch3_files for further details. + +### Control Rules + +Control Rules determine how pumps and regulators in the drainage system will be adjusted over the course of a simulation. Some examples of these rules are: + +Simple time-based pump control: +RULE R1 +IF SIMULATION TIME > 8 +THEN PUMP 12 STATUS = ON +ELSE PUMP 12 STATUS = OFF + +Multiple-condition orifice gate control: +RULE R2A +IF NODE 23 DEPTH > 12 +AND LINK 165 FLOW > 100 +THEN ORIFICE R55 SETTING = 0.5 + +RULE R2B +IF NODE 23 DEPTH > 12 +AND LINK 165 FLOW > 200 +THEN ORIFICE R55 SETTING = 1.0 + + +RULE R2C +IF NODE 23 DEPTH <= 12 +OR LINK 165 FLOW <= 100 +THEN ORIFICE R55 SETTING = 0 + +Pump station operation: +RULE R3A +IF NODE N1 DEPTH > 5 +THEN PUMP N1A STATUS = ON + +RULE R3B +IF NODE N1 DEPTH > 7 +THEN PUMP N1B STATUS = ON + +RULE R3C +IF NODE N1 DEPTH <= 3 +THEN PUMP N1A STATUS = OFF +AND PUMP N1B STATUS = OFF + +Modulated weir height control: +RULE R4 +IF NODE N2 DEPTH >= 0 +THEN WEIR W25 SETTING = CURVE C25 + +@ref manual_hydrology describes the control rule format in more detail and the special Editor used to edit them. + +### Pollutants + +SWMM can simulate the generation, inflow and transport of any number of user-defined pollutants. Required information for each pollutant includes: +- pollutant name +- concentration units (i.e., milligrams/liter, micrograms/liter, or counts/liter) +- concentration in rainfall +- concentration in groundwater +- concentration in rainfall-dependent infiltration and inflow +- concentration in dry weather flow +- initial concentration throughout the conveyance system +- first-order decay coefficient. + +Co-pollutants can also be defined in SWMM. For example, pollutant X can have a co-pollutant Y, meaning that the runoff concentration of X will have some fixed fraction of the runoff concentration of Y added to it. +Pollutant buildup and washoff from subcatchment areas are determined by the land uses assigned to those areas. Input loadings of pollutants to the drainage system can also originate from external time series inflows as well as from dry weather inflows. + +### Land Uses + +Land Uses are categories of development activities or land surface characteristics assigned to subcatchments. Examples of land use activities are residential, commercial, industrial, and undeveloped. Land surface characteristics might include rooftops, lawns, paved roads, undisturbed soils, etc. Land uses are used solely to account for spatial variation in pollutant buildup and washoff rates within subcatchments. + +The SWMM user has many options for defining land uses and assigning them to subcatchment areas. One approach is to assign a mix of land uses for each subcatchment, which results in all land uses within the subcatchment having the same pervious and impervious characteristics. Another approach is to create subcatchments that have a single land use classification along with a distinct set of pervious and impervious characteristics that reflects the classification. + +The following processes can be defined for each land use category: +- pollutant buildup +- pollutant washoff +- street cleaning. + +### Pollutant Buildup + +Pollutant buildup that accumulates within a land use category is described (or “normalized”) by either a mass per unit of subcatchment area or per unit of curb length. Mass is expressed in pounds for US units and kilograms for metric units. The amount of buildup is a function of the number of preceding dry weather days and can be computed using one of the following functions: + +Power Function: Pollutant buildup (B) accumulates proportionally to time (t) raised to some power, until a maximum limit is achieved, +B=Min(C_1,C_2 t^(C_3 )) +where C1 = maximum buildup possible (mass per unit of area or curb length), C2 = buildup rate constant, and C3 = time exponent. + +Exponential Function: Buildup follows an exponential growth curve that approaches a maximum limit asymptotically, +B=C_1 (1-e^(-C_2 t)) +where C1 = maximum buildup possible (mass per unit of area or curb length) and C2 = buildup rate constant (1/days). + +Saturation Function: Buildup begins at a linear rate that continuously declines with time until a saturation value is reached, +B=(C_1 t)/(C_2+t) +where C1 = maximum buildup possible (mass per unit area or curb length) and C2 = half-saturation constant (days to reach half of the maximum buildup). + +External Time Series: This option allows one to use a Time Series to describe the rate of buildup per day as a function of time. The values placed in the time series would have units of mass per unit area (or curb length) per day. One can also provide a maximum possible buildup (mass per unit area or curb length) with this option and a scaling factor that multiplies the time series values. + +### Pollutant Washoff + +Pollutant washoff from a given land use category occurs during wet weather periods and can be described in one of the following ways: + +Exponential Washoff: The washoff load (W) in units of mass per hour is proportional to the product of runoff raised to some power and to the amount of buildup remaining, +W=C_1 q^(C_2 ) B +where C1 = washoff coefficient, C2 = washoff exponent, q = runoff rate per unit area (inches/hour or mm/hour), and B = pollutant buildup in mass units. The buildup here is the total mass (not per area or curb length) and both buildup and washoff mass units are the same as used to express the pollutant's concentration (milligrams, micrograms, or counts). + +Rating Curve Washoff: The rate of washoff W in mass per second is proportional to the runoff rate raised to some power, +W=C_1 Q^(C_2 ) +where C1 = washoff coefficient, C2 = washoff exponent, and Q = runoff rate in user-defined flow units. +Event Mean Concentration: This is a special case of Rating Curve Washoff where the exponent is 1.0 and the coefficient C1 represents the washoff pollutant concentration in mass per liter (Note: the conversion between user-defined flow units used for runoff and liters is handled internally by SWMM). + +Note that in each case buildup is continuously depleted as washoff proceeds, and washoff ceases when there is no more buildup available. + +Washoff loads for a given pollutant and land use category can be reduced by a fixed percentage by specifying a BMP Removal Efficiency that reflects the effectiveness of any BMP controls associated with the land use. It is also possible to use the Event Mean Concentration option by itself, without having to model any pollutant buildup at all. + +### Street Sweeping + +Street sweeping can be used on each land use category to periodically reduce the accumulated buildup of specific pollutants. The parameters that describe street sweeping include: +- days between sweeping +- days since the last sweeping at the start of the simulation +- the fraction of buildup of all pollutants that is available for removal by sweeping +- the fraction of available buildup for each pollutant removed by sweeping +Note that these parameters can be different for each land use, and the last parameter can vary also with pollutant. + +### Treatment + +Removal of pollutants from the flow streams entering any drainage system node is modeled by assigning a set of treatment functions to the node. A treatment function can be any well-formed mathematical expression involving: +- the pollutant concentration +- the removals of other pollutants +- any of several process variables, such as flow rate, depth, hydraulic residence time, etc. + +The result of the treatment function can be either a concentration (denoted by the letter C) or a fractional removal (denoted by R). For example, a first-order decay expression for BOD exiting from a storage node might be expressed as: +C = BOD * exp(-0.05 * HRT) +where HRT is the reserved variable name for hydraulic residence time. The removal of some trace pollutant that is proportional to the removal of total suspended solids (TSS) could be expressed as: + R = 0.75 * R_TSS +Section C.26 provides more details on how user-defined treatment equations are supplied to the program. + +### Curves + +Curve objects are used to describe a functional relationship between two quantities. The following types of curves are used in SWMM: +- Storage - describes how the surface area of a Storage Unit node varies with water depth. +- Shape - describes how the width of a customized cross-sectional shape varies with height for a Conduit link. +- Diversion - relates diverted outflow to total inflow for a Flow Divider node or a Custom inlet drain. +- Tidal - describes how the stage at an Outfall node changes by hour of the day. +- Pump - relates flow through a Pump link to the depth or volume of water at the upstream node or to the head delivered by the pump. +- Rating - relates flow through an Outlet link to the freeboard depth or head difference of water across it; relates flow captured by a Custom inlet drain to the depth of water above it. +- Control - determines how the control setting of a pump or flow regulator varies as a function of some control variable (such as water level at a particular node) as specified in a Modulated Control rule. +- Weir – allows a weir’s discharge coefficient to vary with the hydraulic head across it. +Each curve must be given a unique name and can be assigned any number of data pairs. + + +### Time Series + +Time Series objects are used to describe how certain object properties vary with time. Time series can be used to describe: + + +- temperature data +- evaporation data +- rainfall data +- water stage at outfall nodes +- external inflow hydrographs at drainage system nodes +- external inflow pollutographs at drainage system nodes +- control settings for pumps and flow regulators.. + +Each time series must be given a unique name and can be assigned any number of time-value data pairs. Time can be specified either as hours from the start of a simulation or as an absolute date and time-of-day. Time series data can either be entered directly into the program or be accessed from a user-supplied Time Series file. + +- For rainfall time series, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage that utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values. +- For times that fall outside the range of the time series, SWMM will use a value of 0 for rainfall and external inflow time series, and either the first or last series value for temperature, evaporation, and water stage time series. + +### Time Patterns + +Time Patterns allow external Dry Weather Flow (DWF) to vary in a periodic fashion. They consist of a set of adjustment factors applied as multipliers to a baseline DWF flow rate or pollutant concentration. The different types of time patterns include: +Monthly - one multiplier for each month of the year +Daily - one multiplier for each day of the week +Hourly - one multiplier for each hour from 12 AM to 11 PM +Weekend - hourly multipliers for weekend days +Each Time Pattern must have a unique name and there is no limit on the number of patterns that can be created. Each dry weather inflow (either flow or quality) can have up to four patterns associated with it, one for each type listed above. +Monthly time patterns can also be used to adjust the baseline values of the following hydrological parameters: +- subcatchment depression storage +- subcatchment pervious surface roughness +- soil infiltration recovery rate +- groundwater evaporation rate. + +### LID Controls + +LID Controls are low impact development practices designed to capture surface runoff and provide some combination of detention, infiltration, and evapotranspiration to it. They are considered as properties of a given subcatchment, similar to how Aquifers and Snow Packs are treated. SWMM can explicitly model eight different generic types of LID controls: + +- Bio-retention Cells are depressions that contain vegetation grown in an engineered soil mixture placed above a gravel drainage bed. They provide storage, infiltration and evaporation of both direct rainfall and runoff captured from surrounding areas. +- Rain Gardens are a type of bio-retention cell consisting of just the engineered soil layer with no gravel bed below it. + +- Green Roofs are another variation of a bio-retention cell that have a soil layer laying atop a special drainage mat material that conveys excess percolated rainfall off of the roof. +- Infiltration Trenches are narrow ditches filled with gravel that intercept runoff from upslope impervious areas. They provide storage volume and additional time for captured runoff to infiltrate the native soil below. + +- Continuous Permeable Pavement systems are excavated areas filled with gravel and paved over with a porous concrete or asphalt mix. Block Paver systems consist of impervious paver blocks placed on a sand or pea gravel bed with a gravel storage layer below. +- Rain Barrels (or Cisterns) are containers that collect roof runoff during storm events and can either release or re-use the rainwater during dry periods. + +- Rooftop Disconnection has downspouts discharge to pervious landscaped areas and lawns instead of directly into storm drains. It can also model roofs with directly connected drains that overflow onto pervious areas. +- Vegetative Swales are channels or depressed areas with sloping sides covered with grass and other vegetation. They slow down the conveyance of collected runoff and allow it more time to infiltrate the native soil beneath it. +Bio-retention cells, infiltration trenches, and permeable pavement systems can contain optional drain systems in their gravel storage beds to convey excess captured runoff off of the site and prevent the unit from flooding. They can also have an impermeable floor or liner that prevents any infiltration into the native soil from occurring. Infiltration trenches and permeable pavement systems can also be subjected to a decrease in hydraulic conductivity over time due to clogging. +LID units that contain drains can have a removal percentage assigned to each pollutant discharged through the drain. LID’s will also provide a reduction in pollutant mass load conveyed in their surface discharge due to the reduction in runoff flow volume they provide. + +There are two different approaches for placing LID controls within a subcatchment: +- place one or more controls in an existing subcatchment that will displace an equal amount of non-LID area from the subcatchment +- create a new subcatchment devoted entirely to just a single LID practice. + +The first approach allows a mix of LIDs to be placed into a subcatchment, each treating a different portion of the runoff generated from the non-LID fraction of the subcatchment. Note that under this option the subcatchment's LIDs act in parallel -- it is not possible to make them act in series (i.e., have the outflow from one LID control become the inflow to another LID). Also, after LID placement the subcatchment's Percent Impervious and Width properties may require adjustment to compensate for the amount of original subcatchment area that has now been replaced by LIDs (see Figure 1-12 below). For example, suppose that a subcatchment which is 40% impervious has 75% of that area converted to a permeable pavement LID. After the LID is added the subcatchment's percent imperviousness should be changed to the percent of impervious area remaining divided by the percent of non-LID area remaining. This works out to (1 - 0.75)*40 / (100 - 0.75*40) or 14.3 %. + + +![Figure 1-12 Adjustment of subcatchment parameters after LID placement](figures/fig3-10-lid-adjustment.png) + +*Figure 1-12 Adjustment of subcatchment parameters after LID placement* + +Under this first approach the runoff available for capture by the subcatchment's LIDs is the runoff generated from its impervious area. If the option to re-route some fraction of this runoff to the pervious area is exercised, then only the remaining impervious runoff (if any) will be available for LID treatment. Also note that green roofs and roof disconnection only treat the precipitation that falls directly on them and do not capture runoff from other impervious areas in their subcatchment. + +The second approach allows LID controls to be strung along in series and also allows runoff from several different upstream subcatchments to be routed onto the LID subcatchment. If these single-LID subcatchments are carved out of existing subcatchments, then once again some adjustment of the Percent Impervious, Width and also the Area properties of the latter may be necessary. In addition, whenever an LID occupies the entire subcatchment the values assigned to the subcatchment's standard surface properties (such as imperviousness, slope, roughness, etc.) are overridden by those that pertain to the LID unit. + + +## Computational Methods + +SWMM is a physically based, discrete-time simulation model. It employs principles of conservation of mass, energy, and momentum wherever appropriate. This section briefly describes the methods SWMM uses to model stormwater runoff quantity and quality through the following physical processes: +- surface runoff +- infiltration +- groundwater +- snowmelt +- surface ponding +- flow routing +- water quality routing +- low impact development + +The theory and numerical methods behind each are in the three OpenSWMM +reference manuals: @ref hydrology_reference_manual, +@ref hydraulics_reference_manual and @ref quality_reference_manual. Figure +1-3 shows how the processes connect, from precipitation on the subcatchments +and on the 2D mesh through the subsurface to routing, transport and the +outfalls. + +![Figure 1-3 Processes modelled by OpenSWMM](figures/png/eng_process_flow.png) + +*Figure 1-3 Processes modelled by OpenSWMM* + +
+@ref hydrology_ref_ch2_meteorology "Precipitation" +@ref engine_manual_sect_RAINGAGES "rain · snow" +@ref hydrology_ref_ch2_meteorology "scale factors" +@ref hydrology_ref_ch6_snowmelt "Snowmelt" +@ref hydrology_ref_ch6_snowmelt "degree-day · areal depletion" +@ref hydrology_ref_ch3_surface_runoff "Initial abstraction · evaporation" +@ref engine_manual_sect_SUBAREAS "depression storage" +@ref hydrology_ref_ch3_surface_runoff "Surface runoff" +@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir" +@ref hydrology_ref_ch4_infiltration "Horton · Green-Ampt · CN" +@ref quality_ref_ch6_lid_controls "LID controls" +@ref quality_ref_ch6_lid_controls "layered units" +@ref quality_ref_ch6_lid_controls "storage nodes" +@ref quality_ref_ch4_surface_washoff "Washoff" +@ref quality_ref_ch3_pollutant_buildup "EMC · exponential · rating" +@ref hydrology_ref_ch5_groundwater "Groundwater" +@ref hydrology_ref_ch5_groundwater "two-zone aquifer per subcatchment" +@ref hydrology_ref_ch9_mesh_groundwater "two-layer aquifer on the mesh" +@ref hydrology_ref_ch9_mesh_groundwater "groundwater transport" +@ref quality_ref_ch3_pollutant_buildup "Pollutant buildup" +@ref quality_ref_ch3_pollutant_buildup "land uses · sweeping" +@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh" +@ref hydrology_ref_ch8_mesh_surface "natural neighbour" +@ref hydraulics_ref_ch9_two_dimensional "2D overland flow" +@ref hydraulics_ref_ch9_two_dimensional "local inertial" +@ref hydraulics_ref_ch9_two_dimensional "full shallow water" +@ref hydraulics_ref_ch9_two_dimensional "diffusive wave" +@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration · evaporation" +@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment · mesh aquifer" +@ref quality_ref_ch10_mesh_quality "2D surface quality" +@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff" +@ref engine_manual_sect_INFLOWS "External inflows" +@ref engine_manual_sect_DWF "dry weather flow" +@ref hydrology_ref_ch7_rdii "RDII: RTK" +@ref hydrology_ref_ch7_rdii "RDII: IA decay" +@ref engine_manual_sect_INFLOWS "user · interface files" +@ref hydraulics_ref_ch7_advanced_features "Street inlets" +@ref hydraulics_ref_ch7_advanced_features "HEC-22 link attribute" +@ref hydraulics_ref_ch7_advanced_features "inlet junction" +@ref hydraulics_ref_ch2_hydraulic_model "Channel, pipe and storage routing" +@ref hydraulics_ref_ch2_hydraulic_model "steady" +@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave" +@ref hydraulics_ref_ch8_finite_volume "finite volume" +@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN · slot · dynamic slot" +@ref hydraulics_ref_ch3_dynamic_wave "TPA" +@ref hydraulics_ref_ch3_dynamic_wave "virtual · inlet junctions" +@ref quality_ref_ch5_transport_treatment "Transport and reactions" +@ref quality_ref_ch5_transport_treatment "CSTR" +@ref quality_ref_ch7_ard_transport "ARD" +@ref quality_ref_ch7_ard_transport "LARD" +@ref quality_ref_ch5_transport_treatment "first-order decay" +@ref quality_ref_ch8_msx_reactions "MSX" +@ref quality_ref_ch9_age_heat "water age" +@ref quality_ref_ch9_age_heat "heat" +@ref quality_ref_ch11_planned "sediment" +@ref engine_manual_sect_TREATMENT "treatment · diversion" +@ref engine_manual_sect_OUTFALLS "Outfalls" +
+ +### Surface Runoff + +The conceptual view of surface runoff used by SWMM is illustrated in Figure 1-13 below. Each subcatchment surface is treated as a nonlinear reservoir. Inflow comes from precipitation and any designated upstream subcatchments. There are several outflows, including infiltration, evaporation, and surface runoff. The capacity of this "reservoir" is the maximum depression storage, which is the maximum surface storage provided by ponding, surface wetting, and interception. Surface runoff per unit area occurs only when the depth of water in the "reservoir" exceeds the maximum depression storage, ds, in which case the outflow is given by Manning's equation. Depth of water over the subcatchment (d) is continuously updated with time by solving numerically a water balance equation over the subcatchment. + + + +![Figure 1-13 Conceptual view of surface runoff](figures/png/hydrology_ch3_nonlinear_reservoir.png) + +*Figure 1-13 Conceptual view of surface runoff* + +### Infiltration + +Infiltration is the process of rainfall penetrating the ground surface into the unsaturated soil zone of pervious subcatchments areas. SWMM offers four choices for modeling infiltration: + +Horton's Method +This method is based on empirical observations showing that infiltration decreases exponentially from an initial maximum rate to some minimum rate over the course of a long rainfall event. Input parameters required by this method include the maximum and minimum infiltration rates, a decay coefficient that describes how fast the rate decreases over time, and a time it takes a fully saturated soil to completely dry. + +Modified Horton Method +This is a modified version of the classical Horton Method that uses the cumulative infiltration in excess of the minimum rate as its state variable (instead of time along the Horton curve), providing a more accurate infiltration estimate when low rainfall intensities occur. It uses the same input parameters as does the traditional Horton Method. + +Green-Ampt Method +This method for modeling infiltration assumes that a sharp wetting front exists in the soil column, separating soil with some initial moisture content below from saturated soil above. The input parameters required are the initial moisture deficit of the soil, the soil's hydraulic conductivity, and the suction head at the wetting front. The recovery rate of moisture deficit during dry periods is empirically related to the hydraulic conductivity. + +Modified Green-Ampt Method +This method modifies the original Green-Ampt procedure by not depleting moisture deficit in the top surface layer of soil during initial periods of low rainfall as was done in the original method. This change can produce more realistic infiltration behavior for storms with long initial periods where the rainfall intensity is below the soil’s saturated hydraulic conductivity. + +Curve Number Method +This approach is adopted from the NRCS (SCS) Curve Number method for estimating runoff. It assumes that the total infiltration capacity of a soil can be found from the soil's tabulated Curve Number. During a rain event this capacity is depleted as a function of cumulative rainfall and remaining capacity. The input parameters for this method are the curve number and the time it takes a fully saturated soil to completely dry. + +SWMM also allows the infiltration recovery rate to be adjusted by a fixed amount on a monthly basis to account for seasonal variation in such factors as evaporation rates and groundwater levels. This optional monthly soil recovery pattern is specified as part of a project's Evaporation data. + +### Groundwater + +Figure 1-14 is a definitional sketch of the two-zone groundwater model that is used in SWMM. The upper zone is unsaturated with a variable moisture content of . The lower zone is fully saturated and therefore its moisture content is fixed at the soil porosity . The fluxes shown in the figure, expressed as volume per unit area per unit time, consist of the following: + + +![Figure 1-14 Two-zone groundwater model](figures/png/hydrology_ch5_two_zone.png) + +*Figure 1-14 Two-zone groundwater model* + +fI infiltration from the surface +fE evapotranspiration from the upper zone which is a fixed fraction of the un-used surface evaporation +fU percolation from the upper to lower zone which depends on the upper zone moisture content  and depth dU +fEL evapotranspiration from the lower zone, which is a function of the depth of the upper zone dU +fL seepage from the lower zone to deep groundwater which depends on the lower zone depth dL +fG lateral groundwater interflow to the drainage system, which depends on the lower zone depth dL as well as the depth in the receiving channel or node. + +After computing the water fluxes that exist during a given time step, a mass balance is written for the change in water volume stored in each zone so that a new water table depth and unsaturated zone moisture content can be computed for the next time step. + +### Snowmelt + +The snowmelt routine in SWMM is a part of the runoff modeling process. It updates the state of the snow packs associated with each subcatchment by accounting for snow accumulation, snow redistribution by areal depletion and removal operations, and snow melt via heat budget accounting. Any snowmelt coming off the pack is treated as an additional rainfall input onto the subcatchment. + +At each runoff time step the following computations are made: +- Air temperature and melt coefficients are updated according to the calendar date. +- Any precipitation that falls as snow is added to the snow pack. +- Any excess snow depth on the plowable area of the pack is redistributed according to the removal parameters established for the pack. +- Areal coverage of snow on the impervious and pervious areas of the pack is reduced according to the Areal Depletion Curves defined for the study area. +- The amount of snow in the pack that melts to liquid water is found using: +- a heat budget equation for periods with rainfall, where melt rate increases with increasing air temperature, wind speed, and rainfall intensity +- a degree-day equation for periods with no rainfall, where melt rate equals the product of a melt coefficient and the difference between the air temperature and the pack's base melt temperature. +- If no melting occurs, the pack temperature is adjusted up or down based on the product of the difference between current and past air temperatures and an adjusted melt coefficient. If melting occurs, the temperature of the pack is increased by the equivalent heat content of the melted snow, up to the base melt temperature. Any remaining melt liquid beyond this is available to runoff from the pack. +- The available snowmelt is then reduced by the amount of free water holding capacity remaining in the pack. The remaining melt is treated the same as an additional rainfall input onto the subcatchment. + +### Flow Routing + +Flow routing within a conduit link in SWMM is governed by the conservation of mass and momentum equations for gradually varied, unsteady flow (i.e., the Saint Venant flow equations). The SWMM user has a choice on the level of sophistication used to solve these equations: + +- Steady Flow Routing +- Kinematic Wave Routing +- Dynamic Wave Routing + +Each of these routing methods employs the Manning equation to relate flow rate to flow depth and bed (or friction) slope. For user-designated Force Main conduits, either the Hazen-Williams or Darcy-Weisbach equation can be used when pressurized flow occurs. + +### Steady Flow Routing + +Steady Flow routing represents the simplest type of routing possible (actually no routing) by assuming that within each computational time step flow is uniform and steady. Thus it simply translates inflow hydrographs at the upstream end of the conduit to the downstream end, with no delay or change in shape. The normal flow equation is used to relate flow rate to flow area (or depth). + +This type of routing cannot account for channel storage, backwater effects, entrance/exit losses, flow reversal or pressurized flow. It can only be used with dendritic conveyance networks, where each node has only a single outflow link (unless the node is a divider in which case two outflow links are required). This form of routing is insensitive to the time step employed and is really only appropriate for preliminary analysis using long-term continuous simulations. + +### Kinematic Wave Routing + +This routing method solves the continuity equation along with a simplified form of the momentum equation in each conduit. The latter assumes that the slope of the water surface equal the slope of the conduit. + +The maximum flow that can be conveyed through a conduit is the full normal flow value. Any flow in excess of this entering the inlet node is either lost from the system or can pond atop the inlet node and be re-introduced into the conduit as capacity becomes available. + +Kinematic wave routing allows flow and area to vary both spatially and temporally within a conduit. This can result in attenuated and delayed outflow hydrographs as inflow is routed through the channel. However this form of routing cannot account for backwater effects, entrance/exit losses, flow reversal, or pressurized flow, and is also restricted to dendritic network layouts. It can usually maintain numerical stability with moderately large time steps, on the order of 1 to 5 minutes. If the aforementioned effects are not expected to be significant then this alternative can be an accurate and efficient routing method, especially for long-term simulations. + +### Dynamic Wave Routing + +Dynamic Wave routing solves the complete one-dimensional Saint Venant flow equations and therefore produces the most theoretically accurate results. These equations consist of the continuity and momentum equations for conduits and a volume continuity equation at nodes. + +With this form of routing it is possible to represent pressurized flow when a closed conduit becomes full, such that flows can exceed the full normal flow value. Flooding occurs when the water depth at a node exceeds the maximum available depth, and the excess flow is either lost from the system or can pond atop the node and re-enter the drainage system. + +Dynamic wave routing can account for channel storage, backwater, entrance/exit losses, flow reversal, and pressurized flow. Because it couples together the solution for both water levels at nodes and flow in conduits it can be applied to any general network layout, even those containing multiple downstream diversions and loops. It is the method of choice for systems subjected to significant backwater effects due to downstream flow restrictions and with flow regulation via weirs and orifices. This generality comes at a price of having to use much smaller time steps, on the order of a thirty seconds or less (SWMM can automatically reduce the user-defined maximum time step as needed to maintain numerical stability). + +### Ponding and Pressurization + +Normally in flow routing, when the flow into a junction exceeds the capacity of the system to transport it further downstream, the excess volume overflows the system and is lost. An option exists to have instead the excess volume be stored atop the junction, in a ponded fashion, and be reintroduced into the system as capacity permits. Under Steady and Kinematic Wave flow routing, the ponded water is stored simply as an excess volume. For Dynamic Wave routing, which is influenced by the water depths maintained at nodes, the excess volume is assumed to pond over the node with a constant surface area. This amount of surface area is an input parameter supplied for the junction. + +Alternatively, the user may wish to represent the surface overflow system explicitly. In open channel systems this can include road overflows at bridges or culvert crossings as well as additional floodplain storage areas. In closed conduit systems, surface overflows may be conveyed down streets, alleys, or other surface routes to the next available stormwater inlet or open channel. Overflows may also be impounded in surface depressions such as parking lots, back yards or other areas. + +In sewer systems with pressurized pipes and force mains the hydraulic head at junction nodes can at times exceed the ground elevation under Dynamic Wave routing. This would normally result in an overflow which, as described above, can either be lost or ponded. SWMM allows the user to specify an additional "surcharge" depth for junction nodes that lets them pressurize and prevents any outflow until this additional depth is exceeded. If both ponding and pressurization are specified for a node ponding takes precedence and the surcharge depth is ignored. Ponding does not apply to storage nodes. + +### Water Quality Routing + +Water quality routing within conduit links assumes that the conduit behaves as a continuously stirred tank reactor (CSTR). Although a plug flow reactor assumption might be more realistic, the differences will be small if the travel time through the conduit is on the same order as the routing time step. The concentration of a constituent exiting the conduit at the end of a time step is found by integrating the conservation of mass equation, using average values for quantities that might change over the time step such as flow rate and conduit volume. + +Water quality modeling within storage unit nodes follows the same approach used for conduits. For other types of nodes that have no volume, the quality of water exiting the node is simply the mixture concentration of all water entering the node. + +The pollutant concentration in both a conduit and a storage node will be reduced by a first-order decay reaction if the pollutant’s first-order decay coefficient is not zero. + +### LID Representation + +LID controls are represented by a combination of vertical layers whose properties are defined on a per-unit-area basis. This allows LIDs of the same design but differing area coverage to easily be placed within different subcatchments of a study area. During a simulation SWMM performs a moisture balance that keeps track of how much water moves between and is stored within each LID layer. As an example, the layers used to model a bio-retention cell and the flow pathways between them are shown in Figure 1-15. The various possible layers consist of the following: + + +![Figure 1-15 Conceptual diagram of a bio-retention cell LID](figures/png/eng_lid_bioretention_layers.png) + +*Figure 1-15 Conceptual diagram of a bio-retention cell LID* + +- The Surface Layer corresponds to the ground (or pavement) surface that receives direct rainfall and runon from upstream land areas, stores excess inflow in depression storage, and generates surface outflow that either enters the drainage system or flows onto downstream land areas. +- The Pavement Layer is the layer of porous concrete or asphalt used in continuous permeable pavement systems, or is the paver blocks and filler material used in modular systems. +- The Soil Layer is the engineered soil mixture used in bio-retention cells to support vegetative growth. It can also be a sand layer placed beneath a pavement layer to provide bedding and filtration. +- The Storage Layer is a bed of crushed rock or gravel that provides storage in bio-retention cells, porous pavement, and infiltration trench systems. For a rain barrel it is simply the barrel itself. +- The Drain System conveys water out of the gravel storage layer of bio-retention cells, permeable pavement systems, and infiltration trenches (typically with slotted pipes) into a common outlet pipe or chamber. For rain barrels it is simply the drain valve at the bottom of the barrel while for rooftop disconnection it is the roof gutter and downspout system. +- The Drainage Mat Layer is a mat or plate placed between the soil media and the roof in a green roof whose purpose is to convey any water that drains through the soil layer off of the roof. +Table 1-3 indicates which combination of layers applies to each type of LID (x means required, o means optional). + +Table 1-3 Layers used to model different types of LID units +LID Type Surface Pavement Soil Storage Drain Drainage Mat +Bio-Retention Cell x x o o +Rain Garden x x +Green Roof x x x +Permeable Pavement x x o x o +Infiltration Trench x x o +Rain Barrel x x +Roof Disconnection x x +Vegetative Swale x + + +All of the LID controls provide some amount of rainfall/runoff storage and evaporation of stored water (except for rain barrels). Infiltration into native soil occurs in vegetative swales and can also occur in bio-retention cells, rain gardens, permeable pavement systems, and infiltration trenches if those systems do not employ an optional impermeable bottom liner. Infiltration trenches and permeable pavement systems can also be subjected to clogging. This reduces their hydraulic conductivity over time proportional to the cumulative hydraulic loading they receive. + +The performance of the LID controls placed in a subcatchment is reflected in the overall runoff, infiltration, and evaporation rates computed for the subcatchment as normally reported by SWMM. SWMM's Status Report also contains a section entitled LID Performance Summary that provides an overall water balance for each LID control placed in each subcatchment. The components of this water balance include total inflow, infiltration, evaporation, surface runoff, drain flow and initial and final stored volumes, all expressed as inches (or mm) over the LID's area. Optionally, the entire time series of flux rates and moisture levels for a selected LID control in a given subcatchment can be written to a tab delimited text file for easy viewing and graphing in a spreadsheet program (such as Microsoft Excel). diff --git a/docs/manuals/engine/sections/Chapter2-InputFileReference.md b/docs/manuals/engine/sections/Chapter2-InputFileReference.md new file mode 100644 index 000000000..e3f17cf4d --- /dev/null +++ b/docs/manuals/engine/sections/Chapter2-InputFileReference.md @@ -0,0 +1,3943 @@ +@page engine_manual_ch2_input_file CHAPTER 2 - Input File Reference + +@tableofcontents + +## 2.1 General Instructions + +EPA SWMM can also be run as a console application from the command line within a DOS window. In this case the study area data are placed into a text file and results are written to a text file. The command line for running SWMM in this fashion is: +runswmm inpfile rptfile outfile +where inpfile is the name of the input file, rptfile is the name of the output report file, and outfile is the name of an optional binary output file. The latter stores all time series results in a special binary format that will require a separate post-processor program for viewing. If no binary output file name is supplied then all time series results will appear in the report file. As written, the above command assumes that you are working in the directory in which EPA SWMM was installed or that this directory has been added to the PATH variable in your user profile. Otherwise full pathnames for the runswmm executable and the files on the command line must be used. + +## 2.2 Input File Format + +The input file for command line SWMM has the same format as the project file used by the Windows version of the program. Figure D-1 illustrates an example SWMM 5 input file. It is organized in sections, where each section begins with a keyword enclosed in brackets. The various section keywords are listed below. + +[TITLE] project title +[OPTIONS] analysis options +[REPORT] output reporting instructions +[FILES] interface file options + +[RAINGAGES] rain gage information +[EVAPORATION] evaporation data +[TEMPERATURE] air temperature and snow melt data +[ADJUSTMENTS] monthly adjustments applied to climate variables + + + + +[SUBCATCHMENTS] basic subcatchment information +[SUBAREAS] subcatchment impervious/pervious subarea data +[INFILTRATION] subcatchment infiltration parameters +[LID_CONTROLS] low impact development control information +[LID_USAGE] assignment of LID controls to subcatchments + +[AQUIFERS] groundwater aquifer parameters +[GROUNDWATER] subcatchment groundwater parameters +[GWF] groundwater flow expressions +[SNOWPACKS] subcatchment snow pack parameters + +[JUNCTIONS] junction node information +[OUTFALLS] outfall node information +[DIVIDERS] flow divider node information +[STORAGE] storage node information + +[CONDUITS] conduit link information +[PUMPS] pump link information +[ORIFICES] orifice link information +[WEIRS] weir link information +[OUTLETS] outlet link information + +[XSECTIONS] conduit, orifice, and weir cross-section geometry +[TRANSECTS] transect geometry for conduits with irregular cross-sections +[STREETS] cross-section geometry for street conduits +[INLETS] design data for storm drain inlets +[INLET_USAGE] assignment of inlets to street and channel conduits +[LOSSES] conduit entrance/exit losses and flap valves +[CONTROLS] rules that control pump and regulator operation + +[POLLUTANTS] pollutant information +[LANDUSES] land use categories +[COVERAGES] assignment of land uses to subcatchments +[LOADINGS] initial pollutant loads on subcatchments +[BUILDUP] buildup functions for pollutants and land uses +[WASHOFF] washoff functions for pollutants and land uses +[TREATMENT] pollutant removal functions at conveyance system nodes + + +[INFLOWS] external hydrograph/pollutograph inflow at nodes +[DWF] baseline dry weather sanitary inflow at nodes +[RDII] rainfall-dependent I/I information at nodes +[HYDROGRAPHS] unit hydrograph data used to construct RDII inflows + +[CURVES] x-y tabular data referenced in other sections +[TIMESERIES] time series data referenced in other sections +[PATTERNS] periodic multipliers referenced in other sections + + + +*Figure D-1 Example SWMM project file* + +*Figure D-1 Example SWMM project file (continued from previous page).* + + + + + + +Section keywords can appear in mixed lower and upper case. The sections can appear in any arbitrary order in the input file, and not all sections must be present. Each section can contain one or more lines of data. Blank lines may appear anywhere in the file. A semicolon (;) can be used to indicate that what follows on the line is a comment, not data. Data items can appear in any column of a line. Observe how in Figure D-1 these features were used to create a tabular appearance for the data, complete with column headings. + +An option is available in the [OPTIONS] section to choose flow units from among cubic feet per second (CFS), gallons per minute (GPM), million gallons per day (MGD), cubic meters per second (CMS), liters per second, (LPS), or million liters per day (MLD). If cubic feet or gallons are chosen for flow units, then US units must be used for all other quantities. If cubic meters or liters are chosen, then metric units must be used for all other quantities. Exceptions are pollutant concentration and Manning’s roughness coefficient (n) which are always expressed in metric units. The default flow units are CFS. @ref manual_reference_tables provides a complete listing of measurement units. + +A detailed description of the data in each section of the input file will now be given. Each section description begins on a new page. When listing the format of a line of data, mandatory keywords are shown in boldface while optional items appear in parentheses. A list of keywords separated by a slash (YES/NO) means that only one of the words should appear in the data line. +  +### Section: [TITLE] {#engine_manual_sect_TITLE} + +Purpose: +Attaches a descriptive title to the project being analyzed. + +Format: +Any number of lines may be entered. The first line will be used as a page header in the output report. + +  +### Section: [OPTIONS] {#engine_manual_sect_OPTIONS} + +Purpose: +Provides values for the analysis options that select the process models, the solvers and their closures, the time steps, and reporting. + +Format: +``` +Keyword Value +``` + +Parameters: + +Every keyword below is matched case-insensitively by the parser (`OptionsHandler.cpp`, `handle_options()`); only the first value token after the keyword is read. A keyword the parser does not recognise is not an error: it is stored upper-cased in the extension-options map (`SimulationOptions::ext_options`), a non-fatal "Unknown option keyword" warning is written to the report file, and the value stays available to plugins through `swmm_options_get_ext()`. An unrecognised value of FLOW_UNITS, INFILTRATION, FLOW_ROUTING, QUALITY_SOLVER, OUTFALL_BACKFLOW_QUALITY or DISPERSION is stored the same way but without a warning; an unrecognised value of any other enumerated keyword is silently ignored and the default stands. Boolean spellings differ by key: the IGNORE_* keys, ALLOW_PONDING, SKIP_STEADY_STATE and WRITE_ABSOLUTE_PATHS take YES, TRUE or 1 as true and anything else as false; FV_COMPACTION, FV_LTS and FV_NODE_FEEDBACK_DT take NO, FALSE, 0 or OFF as false and anything else as true; the remaining switches list their accepted spellings in the Values column. + +Three sections carry a keyword spelled `DISPERSION`, and they mean different things. In `[OPTIONS]`, `DISPERSION RWPT` or `OFF` is the switch for random-walk particle dispersion under `QUALITY_SOLVER LAGRANGIAN` (quality §7.4.1); it takes no coefficient and warns under any other quality solver. In `[TRANSPORT_OPTIONS]`, `DISPERSION OFF`, `FISCHER` or a number sets the longitudinal dispersion coefficient of the Eulerian ARD engine, in project length squared per second (quality §7.3.3). In `[2D_OPTIONS]`, `DISPERSION` is the isotropic species dispersion coefficient of the 2D surface in m²/s, default 0, with negative values refused. (A fourth, `[GW_TRANSPORT_OPTIONS] DISPERSION YES` or `NO`, is a switch of the groundwater-transport sections, which are authored but inert.) The table below documents only the `[OPTIONS]` key. + +#### Units and process models + +| Keyword | Values | Default | Description | +|---|---|---|---| +| FLOW_UNITS | CFS / GPM / MGD / CMS / LPS / MLD | CFS | Selects the flow unit; a US unit puts every other quantity in US customary units, a metric unit in SI. Concentrations and Manning's n stay metric. | +| INFILTRATION | HORTON / MOD_HORTON / MODIFIED_HORTON / GREEN_AMPT / MOD_GREEN_AMPT / MODIFIED_GREEN_AMPT / CURVE_NUMBER | HORTON | Selects the subcatchment infiltration model. MOD_HORTON and MOD_GREEN_AMPT are this engine's aliases of the legacy MODIFIED_* spellings. | +| FLOW_ROUTING | STEADY / NF / KINWAVE / XKINWAVE / KW / EKW / KINEMATIC_WAVE / DYNWAVE / DW / DYNAMIC_WAVE / FV / FINITE_VOLUME / NONE / NO_ROUTING | DYNWAVE | Selects the conveyance routing method; FV is the explicit finite-volume solver (hydraulics Chapter 8). Legacy spellings match as prefixes (STEADYFLOW is STEADY); NONE and NO_ROUTING set IGNORE_ROUTING. | +| LINK_OFFSETS | DEPTH / ELEVATION | DEPTH | Sets whether link offsets are distances above the node invert (DEPTH) or absolute elevations (ELEVATION). | +| ALLOW_PONDING | YES / NO | NO | Lets excess water pond atop nodes and re-enter as conditions permit; a node also needs a non-zero Ponded Area for ponding to occur. | +| IGNORE_RAINFALL | YES / NO | NO | Skips all rainfall and runoff computation; only user-supplied direct and dry-weather inflows are routed. | +| IGNORE_SNOWMELT | YES / NO | NO | Skips snowmelt computation even when the project defines snow packs. | +| IGNORE_GROUNDWATER | YES / NO | NO | Skips groundwater computation even when the project defines aquifers. | +| IGNORE_RDII | YES / NO | NO | Skips rainfall-dependent infiltration and inflow even when unit hydrographs and RDII inflows are supplied. | +| IGNORE_ROUTING | YES / NO | NO | Computes runoff only, even when the project contains nodes and links. | +| IGNORE_QUALITY | YES / NO | NO | Skips pollutant washoff, routing and treatment in a project that defines pollutants. | + +#### Dates and times + +| Keyword | Values | Default | Description | +|---|---|---|---| +| START_DATE | MM/DD/YYYY | 01/01/2004 | Date on which the simulation begins. | +| START_TIME | HH:MM:SS | 00:00:00 | Time of day on START_DATE at which the simulation begins. | +| END_DATE | MM/DD/YYYY | — | Date on which the simulation ends. Required: the engine has no fallback, and a run ending on or before its start is rejected at initialisation. | +| END_TIME | HH:MM:SS | 00:00:00 | Time of day on END_DATE at which the simulation ends. | +| REPORT_START_DATE | MM/DD/YYYY | START_DATE value | Date on which reporting of results begins; when omitted, reporting starts with the simulation. | +| REPORT_START_TIME | HH:MM:SS | 00:00:00 | Time of day on REPORT_START_DATE at which reporting begins. Give it together with REPORT_START_DATE; alone it is added to a zero date. | +| SWEEP_START | MM/DD | 1/1 | Day of the year on which street sweeping begins. | +| SWEEP_END | MM/DD | 12/31 | Day of the year on which street sweeping ends. | +| DRY_DAYS | number | 0 | Antecedent days without rainfall before the simulation starts, which seed the initial pollutant buildup. | + +#### Time steps + +| Keyword | Values | Default | Description | +|---|---|---|---| +| ROUTING_STEP | number or HH:MM:SS | 20 | Routing time step in seconds (fractions allowed) for flows and quality; also the ceiling of the variable dynamic-wave step. | +| VARIABLE_STEP | number | 0.75 | Courant safety factor for the variable dynamic-wave step, which never exceeds ROUTING_STEP; 0 fixes the step. | +| MINIMUM_STEP | number or HH:MM:SS | 0.5 | Smallest routing step, in seconds, the variable dynamic-wave step may take. | +| LENGTHENING_STEP | number | 0 | Time step, in seconds, to which conduits are lengthened to meet the Courant criterion under dynamic wave; 0 lengthens none. | +| WET_STEP | HH:MM:SS | 00:05:00 | Runoff time step during rainfall or while water remains ponded on subcatchments. | +| DRY_STEP | HH:MM:SS | 01:00:00 | Runoff time step (essentially pollutant buildup) during periods with no rainfall and no ponded water. | +| RULE_STEP | number or HH:MM:SS | 0 | Interval, in seconds, at which control rules are evaluated; 0 evaluates them every routing step. | + +#### Reporting + +| Keyword | Values | Default | Description | +|---|---|---|---| +| REPORT_STEP | HH:MM:SS | 00:15:00 | Interval at which computed results are written to the binary output file. | +| REPORT_SIGNED_HEADS | YES / TRUE / ON / 1 / NO | NO | Writes the true signed piezometric head to the output HEAD field, needed to see sub-atmospheric TPA heads; NO keeps legacy bit-parity. DEPTH stays floored either way. | + +#### Dynamic wave solver + +| Keyword | Values | Default | Description | +|---|---|---|---| +| MAX_TRIALS | number | 8 | Maximum trials per time step for the nodal head iteration to converge. | +| HEAD_TOLERANCE | number | 0 | Head change between trials, in project length units, below which the step has converged; 0 selects 0.005 ft (0.0015 m). | +| MIN_SURFAREA | number | 0 | Minimum node surface area, in project units, used in depth updates; 0 selects 12.566 ft² (1.167 m²), a 4-ft manhole. | +| MIN_SLOPE | number | 0 | Minimum conduit slope in percent; 0 imposes none, though the elevation drop is still floored at 0.001 ft (0.00035 m). | +| INERTIAL_DAMPING | NONE / PARTIAL / FULL | PARTIAL | Handling of the momentum inertial terms: kept in full (NONE), reduced toward critical flow and dropped when supercritical (PARTIAL), or dropped (FULL). Hydraulics §3.3.3. | +| NORMAL_FLOW_LIMITED | SLOPE / FROUDE / BOTH / NEITHER | BOTH | Test that flags supercritical flow to be limited to normal flow: water-surface slope, Froude number, both, or neither. Hydraulics §3.3.4. | +| NODE_CONTINUITY | EXPLICIT / SEMI_IMPLICIT | EXPLICIT | Node head update: the legacy two-branch formulation, or the unified semi-implicit one that folds flow gradients into the depth update. Hydraulics §3.5. | +| ANDERSON_ACCEL | YES / TRUE / 1 / NO | NO | Accelerates the Picard head iteration with depth-2 Anderson mixing, typically cutting trials by 25 to 50 percent. Hydraulics §3.6. | + +#### Pressurisation and friction + +| Keyword | Values | Default | Description | +|---|---|---|---| +| SURCHARGE_METHOD | EXTRAN / SLOT / DYNAMIC_SLOT / TPA | EXTRAN | Surcharge treatment under dynamic wave: the EXTRAN algorithm, a Preissmann slot, a dynamic slot with modeller-set celerity (hydraulics §3.3.9), or the two-component pressure approach (§3.3.11; TPA only) \status{Experimental} | +| TPA_CELERITY | number | 100 | Acoustic celerity, in project length units per second, that sizes the constant slot width under SURCHARGE_METHOD TPA. Hydraulics §3.3.11. \status{Experimental} | +| DPS_CELERITY | number | 25.0 | Target pressure-wave celerity in m/s of the dynamic slot; lower values allow larger steps but reduce transient fidelity. Hydraulics §3.3.9. | +| DPS_ALPHA | number | 3.0 | Surcharge shock parameter (at least 2) of the dynamic slot; larger values give a bigger celerity shock at the mixed-flow transition. Hydraulics §3.3.9. | +| DPS_DECAY_TIME | number | 0.5 | Time, in seconds, for the dynamic slot's Preissmann number to decay toward 1; shorter transitions faster but may oscillate. Hydraulics §3.3.9. | +| FORCE_MAIN_EQUATION | H-W / HW / HAZEN-WILLIAMS / D-W / DW / DARCY-WEISBACH | H-W | Friction-loss equation for pressurised flow in Circular Force Main conduits: Hazen-Williams or Darcy-Weisbach. | +| UNSTEADY_FRICTION | NONE / VITKOVSKY | NONE | Adds the Vítkovský-type unsteady friction term to the momentum equation in both the dynamic wave and finite-volume solvers. Hydraulics §3.3.12 and §8.5.4. | +| UF_K3 | number | 0.015 | Brunone-type coefficient k3 of the unsteady friction term; read only when UNSTEADY_FRICTION is not NONE. Literature range 0.005 to 0.020. | + +#### Finite-volume routing (FV_*) + +These keys are read only under FLOW_ROUTING FV; under any other routing model they are accepted and inert, so switching FLOW_ROUTING never invalidates a file (hydraulics §8.9). + +| Keyword | Values | Default | Description | +|---|---|---|---| +| FV_CELL_LENGTH | number | 0 | Target cell length in project length units; 0 sets no target and each conduit gets FV_MIN_CELLS cells. Hydraulics §8.3. | +| FV_MIN_CELLS | number | 4 | Floor on cells per conduit, with or without a length target; a single cell under-conveys at every manhole. Hydraulics §8.3. | +| FV_CFL | number | 0.5 | Courant number bounding the explicit substep. Hydraulics §8.5.5. | +| FV_RIEMANN | HLL / HLLC | HLLC | Face flux solver; HLLC resolves the contact wave that carries advected scalars, HLL is a debugging baseline. Hydraulics §8.5.3. | +| FV_ORDER | 1 / 2 | 1 | Spatial order; 2 enables MUSCL-Hancock reconstruction with the limiter of FV_LIMITER. Hydraulics §8.5.7. | +| FV_LIMITER | MINMOD / VANLEER / SUPERBEE | MINMOD | Slope limiter used with FV_ORDER 2; MINMOD is most robust, SUPERBEE sharpest. Hydraulics §8.5.7. | +| FV_SCALAR_SCHEME | UPWIND / MUSCL / QUICKEST_ULTIMATE / QUICKEST | MUSCL | Reconstruction of the advected scalar field on the finite-volume mesh. Hydraulics §8.8. | +| FV_TIME_INTEGRATION | EULER / RK2 | EULER | Time integrator: forward Euler or SSP-RK2 (Heun); RK2 disables local time stepping. Hydraulics §8.5.5. | +| FV_SLOT_CELERITY | number | 100 | Pressurised wave celerity in project length units per second; sets the slot width and doubles as the TPA acoustic celerity. Hydraulics §8.4.1. | +| FV_PRESSURIZED_IMPLICIT | YES / TRUE / ON / 1 / NO | NO | Integrates the slot's acoustic pair implicitly on pressurised cells, removing the celerity from the time-step law; CPU only, local time stepping stands down. Hydraulics §8.4.4. \status{Experimental} | +| FV_PRESSURE_CLOSURE | SLOT / TPA | SLOT | Pressurisation closure: the Preissmann slot, or the two-component pressure approach that allows sub-atmospheric full-pipe flow. Hydraulics §8.4.5. \status{Experimental} | +| FV_DISPERSION | number | 0 | Longitudinal dispersion coefficient in project length squared per second; 0 disables it. Accepted but inert until finite-volume transport is connected; non-zero warns at open. Hydraulics §8.8. | +| FV_STRUCTURE_COUPLING | SUBSTEP / ROUTING_STEP | SUBSTEP | Cadence at which pump, orifice, weir and outlet flows and outfall stages refresh: every substep, or once per routing step. Hydraulics §8.6.3. | +| FV_COMPACTION | YES / NO / FALSE / 0 / OFF | YES | Skips dry, inactive parts of the network; results-transparent by contract. Hydraulics §8.5.9. | +| FV_LTS | YES / NO / FALSE / 0 / OFF | YES | Local time stepping: stiff cells substep at their own power-of-two tier; NO forces one global substep. Hydraulics §8.5.6. | +| FV_LTS_MAX_TIERS | number | 6 | Cap on the local-time-stepping tier spread; 6 allows a 64-fold spread, and the hard ceiling is 8. Hydraulics §8.5.6. | +| FV_NODE_FEEDBACK_DT | YES / NO / FALSE / 0 / OFF | NO | Bounds the explicit step by the algebraic-junction feedback limit at pressurised junctions; removes oscillation at 10 to 14 times the wall cost. Hydraulics §8.6.1. | +| FV_CFL_CENSUS_INTERVAL | number | 1 | Substeps between full Courant censuses; 1 recomputes every substep. Hydraulics §8.5.5. | +| FV_BACKEND | CPU / AUTO / OMP / CUDA / HIP / SYCL | AUTO | Kernel backend; AUTO tries plugins above FV_MIN_PARALLEL_CELLS and otherwise stays on the CPU. | +| FV_MIN_PARALLEL_CELLS | number | 20000 | Cell count below which FV_BACKEND AUTO stays on the CPU. | + +#### Water quality and transport + +| Keyword | Values | Default | Description | +|---|---|---|---| +| QUALITY_SOLVER | LEGACY / EULERIAN_ARD / ARD / LAGRANGIAN / LARD | LEGACY | Selects the transport engine: legacy tanks-in-series, Eulerian ARD on fixed cells, or Lagrangian parcels (LARD). Quality §7.1. | +| QUALITY_STEP | number or HH:MM:SS | 0 | LARD transport substep in seconds; each routing step splits into equal substeps. 0 follows ROUTING_STEP; warns under other solvers. Quality §7.4. | +| MAX_SEGMENTS_PER_LINK | number | 100 | Cap on LARD parcels per link; the oldest parcels merge when it is reached. Clamped to at least 2; LARD only. Quality §7.4. | +| DISPERSION | RWPT / OFF / NONE | OFF | Random-walk particle dispersion under QUALITY_SOLVER LAGRANGIAN; warns under other solvers. Distinct from the [TRANSPORT_OPTIONS] and [2D_OPTIONS] keys. Quality §7.4.1. | +| RWPT_SEED | number | 0 | Deterministic seed of the RWPT counter random generator; the same seed reproduces a run bit-for-bit at any thread count. Quality §7.4.1. | +| WATER_AGE | ON / YES / OFF / NO | OFF | Tracks transported water age as the reserved species `__WATER_AGE__`; per-source initial ages come from [WATER_AGE_SOURCES]. Quality §9.2. | +| OUTFALL_BACKFLOW_QUALITY | LAST / ZERO | LAST | Quality carried by reverse flow at outfalls: the held last mixed state (legacy), or a fresh zero boundary for every pollutant and water age. | + +#### Heat transport + +| Keyword | Values | Default | Description | +|---|---|---|---| +| HEAT_TRANSPORT | ON / YES / OFF / NO | OFF | Transports temperature as the reserved species `__TEMPERATURE__`; inlet temperatures come from [HEAT_SOURCES]. Quality §9.3. | +| WATER_DENSITY | number | 1000.0 | Water density in kg/m³, which weights surface heat fluxes against advected heat. Quality §9.3.9. | +| WATER_SPECIFIC_HEAT_CAPACITY | number | 4184.0 | Specific heat capacity of water in J/kg/°C used to convert surface heat fluxes into temperature change. Quality §9.3.9. | +| WIND_FUNC_COEFF_A | number | 1.505e-8 | Constant term a of the wind function f(w) = a + b·w in the latent-heat flux (Dunne and Leopold 1978). Quality §9.3.4. | +| WIND_FUNC_COEFF_B | number | 1.6e-8 | Wind-speed coefficient b of the wind function f(w) = a + b·w in the latent-heat flux. Quality §9.3.4. | +| PRESSURE_RATIO | number | 1.0 | Ratio of site to sea-level atmospheric pressure that corrects the Bowen ratio in the sensible-heat flux. Quality §9.3.5. | + +#### 2D, coordinate reference and files + +| Keyword | Values | Default | Description | +|---|---|---|---| +| IGNORE_2D | YES / NO | NO | Disables the 2D surface-routing module even when the model carries a mesh, so the model runs 1D-only without stripping its mesh sections. | +| CRS | EPSG code or quoted PROJ string | — | Coordinate reference system of the model geometry, applied to [COORDINATES], [VERTICES] and [POLYGONS]; readable through swmm_spatial_get_crs(). Empty when omitted. | +| WRITE_ABSOLUTE_PATHS | YES / NO | NO | Makes the .inp writer emit external-file paths absolute instead of rebased relative to the saved file; for tools that reject relative paths. | + +#### Miscellaneous + +| Keyword | Values | Default | Description | +|---|---|---|---| +| THREADS | number | 1 | OpenMP thread count for dynamic-wave and 2D loops; 0 resolves to the runtime maximum, and larger values oversubscribe with a warning. | +| SKIP_STEADY_STATE | YES / NO | NO | Skips routing during steady periods, reusing the last flows, when system flow and lateral inflows change by less than SYS_FLOW_TOL and LAT_FLOW_TOL. | +| SYS_FLOW_TOL | number | 5 | Maximum percent difference between total system inflow and outflow for SKIP_STEADY_STATE to take effect. | +| LAT_FLOW_TOL | number | 5 | Maximum percent difference between current and previous lateral inflows for SKIP_STEADY_STATE to take effect. | + +#### Retired keywords + +| Keyword | Status | Behaviour today | +|---|---|---| +| FV_NODE_COUPLING | \status{Retired} | Parsed; the value EXPLICIT warns and is treated as SEMI_IMPLICIT (storage nodes are always coupled semi-implicitly); any other value is silently ignored. | +| FV_NODE_DT | \status{Retired} | Parsed; the value NONE warns and is treated as STABILITY (the node accuracy bound is always armed); any other value is silently ignored. | +| FV_NODE_PICARD | \status{Retired} | Parsed; a value above 1 warns and is treated as 1 (the semi-implicit node correction is always a single sweep); 1 or less is silently accepted. | +| FV_NODE_CELL_COUPLING | \status{Retired} | Accepted and silently ignored; junctions are always algebraic interfaces (hydraulics §8.6.1). | +| FV_JUNCTION_MODEL | \status{Retired} | Accepted and silently ignored; the BUCKET junction model was removed in favour of the algebraic interface (hydraulics §8.6.1). | +| VIRTUAL_JUNCTION_MOMENTUM | \status{Retired} | Parsed; FULL warns and is treated as BASIC (its cross-junction momentum term was not mass conserving); every value maps to BASIC and the key is never written back. | +| COMPATIBILITY | \status{Retired} | Accepted and silently ignored; a legacy SWMM compatibility flag with no effect in this engine. | + +### Section: [REPORT] {#engine_manual_sect_REPORT} + +Purpose: +Describes the contents of the report file that is produced. + +Formats: +DISABLED YES / NO +INPUT YES / NO +CONTINUITY YES / NO +FLOWSTATS YES / NO +CONTROLS YES / NO +SUBCATCHMENTS ALL / NONE / <list of subcatchment names> +NODES ALL / NONE / <list of node names> +LINKS ALL / NONE / <list of link names> +LID Name Subcatch Fname + +Remarks: +Setting DISABLED to YES disables all reporting (except for error and warning messages) regardless of what other reporting options are chosen. The default is NO. +INPUT specifies whether or not a summary of the input data should be provided in the output report. The default is NO. +CONTINUITY specifies if continuity checks should be reported or not. The default is YES. +FLOWSTATS specifies whether summary flow statistics should be reported or not. The default is YES. +CONTROLS specifies whether all control actions taken during a simulation should be listed or not. The default is NO. +SUBCATCHMENTS gives a list of subcatchments whose results are to be reported. The default is NONE. +NODES gives a list of nodes whose results are to be reported. The default is NONE. +LINKS gives a list of links whose results are to be reported. The default is NONE. +LID specifies that the LID control Name in subcatchment Subcatch should have a detailed performance report for it written to file Fname. +The SUBCATCHMENTS, NODES, LINKS, and LID lines can be repeated multiple times. +### Section: [FILES] {#engine_manual_sect_FILES} + +Purpose: +Identifies optional interface files used or saved by a run. + +Formats: +USE / SAVE RAINFALL Fname +USE / SAVE RUNOFF Fname +USE / SAVE HOTSTART Fname +USE / SAVE RDII Fname +USE INFLOWS Fname +SAVE OUTFLOWS Fname + +Parameters: +Fname is the name of an interface file. + +Remarks: +Refer to @ref engine_manual_ch3_files for a description of interface files. Rainfall, Runoff, and RDII files can either be used or saved in a run, but not both. A run can both use and save a Hot Start file (with different names). +Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. + +  +### Section: [RAINGAGES] {#engine_manual_sect_RAINGAGES} + +Purpose: +Identifies each rain gage that provides rainfall data for the study area. + +Formats: +Name Form Intvl SCF TIMESERIES Tseries +Name Form Intvl SCF FILE Fname (Sta Units) + +Parameters: +Name name assigned to rain gage. +Form form of recorded rainfall, either INTENSITY, VOLUME or CUMULATIVE. +Intvl time interval between gage readings in decimal hours or hours:minutes format (e.g., 0:15 for 15-minute readings). +SCF snow catch deficiency correction factor (use 1.0 for no adjustment). +Tseries name of a time series in the [TIMESERIES] section with rainfall data. +Fname name of an external file with rainfall data. Rainfall files are discussed in @ref engine_manual_ch3_files. +Sta name of the recording station in a user-prepared formatted rain file. +Units rain depth units for the data in a user-prepared formatted rain file, either IN (inches) or MM (millimeters). + +Remarks: +Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. +The station name and depth units entries are only required when using a user-prepared formatted rainfall file. + +**New in OpenSWMM v6:** A multi-column rain file can be referenced by appending a colon and column name to the file path, e.g. `FILE "rain.csv:EAST_GAGE"`. The engine opens the file, locates the column whose header matches the given name (case-insensitive), and reads the rainfall values from that column; an empty column name selects the first data column. Comma- and tab-delimited files with a header row are supported, as is the PCSWMM `.tsf` format (tab-delimited, `IDs:` header row, 12-hour AM/PM date-times) — the format is detected automatically from the file's contents. This allows a single file to supply data for multiple rain gages (and named time series — see the [TIMESERIES] section); each such file is read from disk only once per model open, regardless of how many gages or series reference it. + +  +### Section: [EVAPORATION] {#engine_manual_sect_EVAPORATION} + +Purpose: +Specifies how daily potential evaporation rates vary with time for the study area. + +Formats: +CONSTANT evap +MONTHLY e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12 +TIMESERIES Tseries +TEMPERATURE +FILE (p1 p2 p3 p4 p5 p6 p7 p8 p9 p10 p11 p12) +RECOVERY patternID +DRY_ONLY NO / YES + +Parameters: +evap constant evaporation rate (in/day or mm/day). +e1 evaporation rate in January (in/day or mm/day). +... +e12 evaporation rate in December (in/day or mm/day). +Tseries name of a time series in the [TIMESERIES] section with evaporation data. +p1 pan coefficient for January. +... +p12 pan coefficient for December. +patID name of a monthly time pattern. + +Remarks: +Use only one of the above formats (CONSTANT, MONTHLY, TIMESERIES, TEMPERATURE, or FILE). If no [EVAPORATION] section appears, then evaporation is assumed to be 0. +TEMPERATURE indicates that evaporation rates will be computed from the daily air temperatures contained in an external climate file whose name is provided in the [TEMPERATURE] section. This method also uses the site’s latitude, which can also be specified in the [TEMPERATURE] section. +FILE indicates that evaporation data will be read directly from the same external climate file used for air temperatures as specified in the [TEMPERATURE] section. Supplying monthly pan coefficients for these data is optional. +RECOVERY identifies an optional monthly time pattern of multipliers used to modify infiltration recovery rates during dry periods. For example, if the normal infiltration recovery rate was 1% during a specific time period and a pattern factor of 0.8 applied to this period, then the actual recovery rate would be 0.8%. +DRY_ONLY determines if evaporation only occurs during periods with no precipitation. The default is NO. +The evaporation rates provided in this section are potential rates. The actual amount of water evaporated will depend on the amount available as a simulation progresses. +  +### Section: [TEMPERATURE] {#engine_manual_sect_TEMPERATURE} + +Purpose: +Specifies daily air temperatures, monthly wind speed, and various snowmelt parameters for the study area. Required only when snowmelt is being modeled or when evaporation rates are computed from daily temperatures or are read from an external climate file. + +Formats: +TIMESERIES Tseries +FILE Fname (Start) (Units) +WINDSPEED MONTHLY s1 s2 s3 s4 s5 s6 s7 s8 s9 s10 s11 s12 +WINDSPEED FILE +SNOWMELT Stemp ATIwt RNM Elev Lat DTLong +ADC IMPERVIOUS f.0 f.1 f.2 f.3 f.4 f.5 f.6 f.7 f.8 f.9 +ADC PERVIOUS f.0 f.1 f.2 f.3 f.4 f.5 f.6 f.7 f.8 f.9 + +Parameters: +Tseries name of a time series in the [TIMESERIES] section with temperature data. +Fname name of an external Climate file with temperature data. +Start date to begin reading from the file in month/day/year format (default is the beginning of the file). +Units temperature units for GHCN files (C10 for tenths of a degree C (the default), C for degrees C or F for degrees F. +s1 average wind speed in January (mph or km/hr). +... +s12 average wind speed in December (mph or km/hr). +Stemp air temperature at which precipitation falls as snow (deg F or C). +ATIwt antecedent temperature index weight (default is 0.5). +RNM negative melt ratio (default is 0.6). +Elev average elevation of study area above mean sea level (ft or m) (default is 0). +Lat latitude of the study area in degrees North (default is 50). +DTLong correction, in minutes of time, between true solar time and the standard clock time (default is 0). +f.0 fraction of area covered by snow when ratio of snow depth to depth at 100% cover is 0 +... +f.9 fraction of area covered by snow when ratio of snow depth to depth at 100% cover is 0.9. + +Remarks: +Use the TIMESERIES line to read air temperature from a time series or the FILE line to read it from an external Climate file. Climate files are discussed in @ref engine_manual_ch3_files. If neither format is used, then air temperature remains constant at 70 degrees F. +Enclose the Climate file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. +Temperatures supplied from NOAA's latest Climate Data Online GHCN files should have their units (C or F) specified. Older versions of these files listed temperatures in tenths of a degree C (C10). An asterisk can be entered for the Start date if it defaults to the beginning of the file. +Wind speed can be specified either by monthly average values or by the same Climate file used for air temperature. If neither option appears, then wind speed is assumed to be 0. +Separate Areal Depletion Curves (ADC) can be defined for impervious and pervious subareas. The ADC parameters will default to 1.0 (meaning no depletion) if no data are supplied for a particular type of subarea. + +  +### Section: [ADJUSTMENTS] {#engine_manual_sect_ADJUSTMENTS} + +Purpose: +Specifies optional monthly adjustments to be made to temperature, evaporation rate, rainfall intensity and hydraulic conductivity in each time period of a simulation. + +Formats: +TEMPERATURE t1 t2 t3 t4 t5 t6 t7 t8 t9 t10 t11 t12 +EVAPORATION e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12 +RAINFALL r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 +CONDUCTIVITY c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 + +Parameters: + t1..t12 adjustments to temperature in January, February, etc., as plus or minus degrees F (degrees C). +e1..e12 adjustments to evaporation rate in January, February, etc., as plus or minus in/day (mm/day). +r1..r12 multipliers applied to precipitation rate in January, February, etc. +c1..c12 multipliers applied to soil hydraulic conductivity in January, February, etc. used in either Horton or Green-Ampt infiltration. +Remarks: +The same adjustment is applied for each time period within a given month and is repeated for that month in each subsequent year being simulated. + + + +  +### Section: [SUBCATCHMENTS] {#engine_manual_sect_SUBCATCHMENTS} + +Purpose: +Identifies each subcatchment within the study area. Subcatchments are land area units which generate runoff from rainfall. + +Format: +Name Rgage OutID Area %Imperv Width Slope Clength (Spack) + +Parameters: +Name name assigned to the subcatchment. +Rgage name of a rain gage in the [RAINGAGES] section assigned to the subcatchment. +OutID name of the node or subcatchment that receives runoff from the subcatchment. +Area area of the subcatchment (acres or hectares). +%Imperv percentage of the subcatchment’s area that is impervious. +Width characteristic width of the subcatchment (ft or meters). +Slope the subcatchment’s slope (percent). +Clength total curb length (any length units) used to describe pollutant buildup. Use 0 if not applicable. +Spack optional name of a snow pack object (from the [SNOWPACKS] section) that characterizes snow accumulation and melting over the subcatchment. + +  +### Section: [SUBAREAS] {#engine_manual_sect_SUBAREAS} + +Purpose: +Supplies information about pervious and impervious areas for each subcatchment. Each subcatchment can consist of a pervious subarea, an impervious subarea with depression storage, and an impervious subarea without depression storage. + +Format: +Subcat Nimp Nperv Simp Sperv %Zero RouteTo (%Routed) + +Parameters: +Subcat subcatchment name. +Nimp Manning's coefficient (n) for overland flow over the impervious subarea. +Nperv Manning's coefficient (n) for overland flow over the pervious subarea. +Simp depression storage for the impervious subarea (inches or mm). +Sperv depression storage for the pervious subarea (inches or mm). +%Zero percent of impervious area with no depression storage. +RouteTo IMPERVIOUS if pervious area runoff runs onto impervious area, PERVIOUS if impervious runoff runs onto pervious area, or OUTLET if both areas drain to the subcatchment's outlet (default = OUTLET). +%Routed percent of runoff routed from one type of area to another (default = 100). +  +### Section: [INFILTRATION] {#engine_manual_sect_INFILTRATION} + +Purpose: +Supplies infiltration parameters for each subcatchment. Rainfall lost to infiltration only occurs over the pervious subarea of a subcatchment. + +Format: +Subcat p1 p2 p3 (p4 p5) (Method) + +Parameters: +Subcat subcatchment name. +Method either HORTON, MODIFIED_HORTON, GREEN_AMPT, MODIFIED_GREEN_AMPT, or CURVE_NUMBER. +If not specified then the infiltration method supplied in the [OPTIONS] section is used. +For Horton and Modified Horton Infiltration: +p1 maximum infiltration rate on the Horton curve (in/hr or mm/hr). +p2 minimum infiltration rate on the Horton curve (in/hr or mm/hr). +p3 decay rate constant of the Horton curve (1/hr). +p4 time it takes for a fully saturated soil to dry (days). +p5 maximum infiltration volume possible (0 if not applicable) (in or mm). +For Green-Ampt and Modified Green-Ampt Infiltration: +p1 soil capillary suction (in or mm). +p2 soil saturated hydraulic conductivity (in/hr or mm/hr). +p3 initial soil moisture deficit (porosity minus moisture content) (fraction). +For Curve-Number Infiltration: +p1 SCS Curve Number. +p2 no longer used. +p3 time it takes for a fully saturated soil to dry (days).  +### Section: [LID_CONTROLS] {#engine_manual_sect_LID_CONTROLS} + +Purpose: +Defines scale-independent LID controls that can be deployed within subcatchments. + +Formats: +Name Type +followed by one or more of the following lines depending on Type: +Name SURFACE StorHt VegFrac Rough Slope Xslope +Name SOIL Thick Por FC WP Ksat Kcoeff Suct +Name PAVEMENT Thick Vratio FracImp Perm Vclog (Treg Freg) +Name STORAGE Height Vratio Seepage Vclog (Covrd) +Name DRAIN Coeff Expon Offset Delay (Hopen Hclose Qcrv) +Name DRAINMAT Thick Vratio Rough +Name REMOVALS Pollut Rmvl Pollut Rmvl ... + +Parameters: +Name name assigned to LID process. +Type BC for bio-retention cell; RG for rain garden; GR for green roof; IT for infiltration trench; PP for permeable pavement; RB for rain barrel; RD for rooftop disconnection; VS for vegetative swale. +Pollut name of a pollutant +Rmvl the percent removal the LID achieves for the pollutant (several pollutant removals can be placed on the same line or specified in separate REMOVALS lines). + +For LIDs with Surface Layers: +StorHt when confining walls or berms are present this is the maximum depth to which water can pond above the surface of the unit before overflow occurs (in inches or mm). For LIDs that experience overland flow it is the height of any surface depression storage. For swales, it is the height of its trapezoidal cross-section. +VegFrac fraction of the surface storage volume that is filled with vegetation. +Rough Manning's coefficient (n) for overland flow over surface soil cover, pavement, roof surface or a vegetative swale. Use 0 for other types of LIDs. +Slope slope of a roof surface, pavement surface or vegetative swale (percent). Use 0 for other types of LIDs. +Xslope slope (run over rise) of the side walls of a vegetative swale's cross-section. Use 0 for other types of LIDs. +If either Rough or Slope values are 0 then any ponded water that exceeds the surface storage depth is assumed to completely overflow the LID control within a single time step. + +For LIDs with Pavement Layers: +Thick thickness of the pavement layer (inches or mm). +Vratio void ratio (volume of void space relative to the volume of solids in the pavement for continuous systems or for the fill material used in modular systems). Note that porosity = void ratio / (1 + void ratio). +FracImp ratio of impervious paver material to total area for modular systems; 0 for continuous porous pavement systems. +Perm permeability of the concrete or asphalt used in continuous systems or hydraulic conductivity of the fill material (gravel or sand) used in modular systems (in/hr or mm/hr). +Vclog the number of pavement layer void volumes of runoff treated it takes to completely clog the pavement. Use a value of 0 to ignore clogging. +Treg the number of days that the pavement layer is allowed to clog before its permeability is restored, typically by vacuuming its surface. A value of 0 (the default) indicates that no permeability regeneration occurs. +Freg The fractional degree to which the pavement's permeability is restored when a regeneration interval is reached. The default is 0 (no restoration) while a value of 1 indicates complete restoration to the original permeability value. Once regeneration occurs the pavement begins to clog once again at a rate determined by Vclog. + +For LIDs with Soil Layers: +Thick thickness of the soil layer (inches or mm). +Por soil porosity (pore space volume / total volume). +FC soil field capacity (moisture content of a fully drained soil). +WP soil wilting point (moisture content of a fully dried soil). +Ksat soil’s saturated hydraulic conductivity (in/hr or mm/hr). +Kcoeff slope of the curve of log(conductivity) versus soil moisture deficit (porosity minus soil moisture) (dimensionless). +Suct soil capillary suction (in or mm). + +For LIDs with Storage Layers: +Height thickness of the storage layer or height of a rain barrel (inches or mm). +Vratio void ratio (volume of void space relative to the volume of solids in the layer). Note that porosity = void ratio / (1 + void ratio). +Seepage the rate at which water seeps from the layer into the underlying native soil when first constructed (in/hr or mm/hr). If there is an impermeable floor or liner below the layer then use a value of 0. +Vclog number of storage layer void volumes of runoff treated it takes to completely clog the layer. Use a value of 0 to ignore clogging. +Covrd YES (the default) if a rain barrel is covered, NO if it is not. +Values for Vratio, Seepage, and Vclog are ignored for rain barrels while Covrd applies only to rain barrels. + +For LIDs with Drain Systems: +Coeff coefficient C that determines the rate of flow through the drain as a function of height of stored water above the drain bottom. For Rooftop Disconnection it is the maximum flow rate (in inches/hour or mm/hour) that the roof’s gutters and downspouts can handle before overflowing. +Expon exponent n that determines the rate of flow through the drain as a function of height of stored water above the drain outlet. +Offset height of the drain line above the bottom of the storage layer or rain barrel (inches or mm). +Delay number of dry weather hours that must elapse before the drain line in a rain barrel is opened (the line is assumed to be closed once rainfall begins). A value of 0 signifies that the barrel's drain line is always open and drains continuously. This parameter is ignored for other types of LIDs. +Hopen The height of water (in inches or mm) in the drain's Storage Layer that causes the drain to automatically open. Use 0 to disable this feature. +Hclose The height of water (in inches or mm) in the drain's Storage Layer that causes the drain to automatically close. Use 0 to disable this feature. +Qcurve The name of an optional Control Curve that adjusts the computed drain flow as a function of the head of water above the drain. Leave blank if not applicable. + +For Green Roof LIDs with Drainage Mats: +Thick thickness of the drainage mat (inches or mm). +Vratio ratio of void volume to total volume in the mat. +Rough Manning's coefficient (n) used to compute the horizontal flow rate of drained water through the mat. + +Remarks: +The following table shows which layers are required (x) or are optional (o) for each type of LID process: + +LID Type Surface Pavement Soil Storage Drain Drain Mat +Bio-Retention Cell x x x o +Rain Garden x x +Green Roof x x x +Infiltration Trench x x o +Permeable Pavement x x o x o +Rain Barrel x x +Rooftop Disconnection x x +Vegetative Swale x + +The equation used to compute flow rate out of the underdrain per unit area of the LID (in in/hr or mm/hr) is where q is outflow, h is height of stored water (inches or mm) and Hd is the drain offset height. Note that the units of C depend on the unit system being used as well as the value assigned to n. +The actual dimensions of an LID control are provided in the [LID_USAGE] section when it is placed in a particular subcatchment. + + +Examples: +;A street planter with no drain +Planter BC +Planter SURFACE 6 0.3 0 0 0 +Planter SOIL 24 0.5 0.1 0.05 1.2 2.4 +Planter STORAGE 12 0.5 0.5 0 + +;A green roof with impermeable bottom +GR1 BC +GR1 SURFACE 3 0 0 0 0 +GR1 SOIL 3 0.5 0.1 0.05 1.2 2.4 +GR1 STORAGE 3 0.5 0 0 +GR1 DRAIN 5 0.5 0 0 + +;A rain barrel that drains 6 hours after rainfall ends +RB12 RB +RB12 STORAGE 36 0 0 0 +RB12 DRAIN 10 0.5 0 6 + +;A grass swale 24 in. high with 5:1 side slope +Swale VS +Swale SURFACE 24 0 0.2 3 5 + +  +### Section: [LID_USAGE] {#engine_manual_sect_LID_USAGE} + +Purpose: +Deploys LID controls within specific subcatchment areas. + +Format: +Subcat LID Number Area Width InitSat FromImp ToPerv +(RptFile DrainTo FromPerv) + +Parameters: +Subcat name of the subcatchment using the LID process. +LID name of an LID process defined in the [LID_CONTROLS] section. +Number number of replicate LID units deployed. +Area area of each replicate unit (ft2 or m2). +Width width of the outflow face of each identical LID unit (in ft or m). This parameter applies to roofs, pavement, trenches, and swales that use overland flow to convey surface runoff off of the unit. It can be set to 0 for other LID processes, such as bio-retention cells, rain gardens, and rain barrels that simply spill any excess captured runoff over their berms. +InitSat the percent to which the LID's soil, storage, and drain mat zones are initially filled with water. For soil zones 0 % saturation corresponds to the wilting point moisture content while 100 % saturation has the moisture content equal to the porosity. +FromImp the percent of the impervious portion of the subcatchment’s non-LID area whose runoff is treated by the LID practice. (E.g., if rain barrels are used to capture roof runoff and roofs represent 60% of the impervious area, then the impervious area treated is 60%). If the LID unit treats only direct rainfall, such as with a green roof, then this value should be 0. If the LID takes up the entire subcatchment then this field is ignored. +ToPerv a value of 1 indicates that the surface and drain flow from the LID unit should be routed back onto the pervious area of the subcatchment that contains it. This would be a common choice to make for rain barrels, rooftop disconnection, and possibly green roofs. The default value is 0. + + +RptFile optional name of a file to which detailed time series results for the LID will be written. Enclose the name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. Use ‘*’ if not applicable and an entry for DrainTo or FromPerv follows +DrainTo optional name of subcatchment or node that receives flow from the unit’s drain line, if different from the outlet of the subcatchment that the LID is placed in. Use ‘*’ if not applicable and an entry for FromPerv follows. +FromPerv optional percent of the pervious portion of the subcatchment’s non-LID area whose runoff is treated by the LID practice. The default value is 0. + +Remarks: +If ToPerv is set to 1 and DrainTo set to some other outlet, then only the excess surface flow from the LID unit will be routed back to the subcatchment’s pervious area while the underdrain flow will be sent to DrainTo. +More than one type of LID process can be deployed within a subcatchment as long as their total area does not exceed that of the subcatchment and the total percent impervious area treated does not exceed 100. + +Examples: +;34 rain barrels of 12 sq ft each are placed in +;subcatchment S1. They are initially empty and treat 17% +;of the runoff from the subcatchment’s impervious area. +;The outflow from the barrels is returned to the ;subcatchment’s pervious area. +S1 RB14 34 12 0 0 17 1 + +;Subcatchment S2 consists entirely of a single vegetative ;swale 200 ft long by 50 ft wide. +S2 Swale 1 10000 50 0 0 0 “swale.rpt” + +  +### Section: [AQUIFERS] {#engine_manual_sect_AQUIFERS} + +Purpose: +Supplies parameters for each unconfined groundwater aquifer in the study area. Aquifers consist of two zones – a lower saturated zone and an upper unsaturated zone with a moving boundary between the two. + +Format: +Name Por WP FC Ks Kslp Tslp ETu ETs Seep Ebot Egw Umc (Epat) + +Parameters: +Name name assigned to aquifer. +Por soil porosity (pore space volume / total volume). +WP soil wilting point (moisture content of a fully dried soil). +FC soil field capacity (moisture content of a fully drained soil). +Ks saturated hydraulic conductivity (in/hr or mm/hr). +Kslp slope of the logarithm of hydraulic conductivity versus moisture deficit (porosity minus moisture content) curve (dimensionless). +Tslp slope of soil tension versus moisture content curve (inches or mm). +ETu fraction of total evaporation available for evapotranspiration in the upper unsaturated zone. +ETs maximum depth into the lower saturated zone over which evapotranspiration can occur (ft or m). +Seep seepage rate from saturated zone to deep groundwater when water table is at ground surface (in/hr or mm/hr). +Ebot elevation of the bottom of the aquifer (ft or m). +Egw groundwater table elevation at start of simulation (ft or m). +Umc unsaturated zone moisture content at start of simulation (volumetric fraction). +Epat name of optional monthly time pattern used to adjust the upper zone evaporation fraction for different months of the year. +Remarks: +Local values for Ebot, Egw, and Umc can be assigned to specific subcatchments in the [GROUNDWATER] section. + +### Section: [GROUNDWATER] {#engine_manual_sect_GROUNDWATER} + +Purpose: +Supplies parameters that determine the rate of groundwater flow between the aquifer underneath a subcatchment and a node of the conveyance system. + +Format: +Subcat Aquifer Node Esurf A1 B1 A2 B2 A3 Dsw (Egwt Ebot Egw Umc) + +Parameters: +Subcat subcatchment name. +Aquifer name of groundwater aquifer underneath the subcatchment. +Node name of a node in the conveyance system exchanging groundwater with the aquifer. +Esurf surface elevation of the subcatchment (ft or m). +A1 groundwater flow coefficient (see below). +B1 groundwater flow exponent (see below). +A2 surface water flow coefficient (see below). +B2 surface water flow exponent (see below). +A3 surface water – groundwater interaction coefficient (see below). +Dsw fixed depth of surface water at the receiving node (ft or m) (set to zero if surface water depth will vary as computed by flow routing). +Egwt threshold groundwater table elevation which must be reached before any flow occurs (ft or m). Leave blank (or enter *) to use the elevation of the receiving node's invert. +The following optional parameters can be used to override the values supplied for the subcatchment’s aquifer. +Ebot elevation of the bottom of the aquifer (ft or m). +Egw groundwater table elevation at the start of the simulation (ft or m). +Umc unsaturated zone moisture content at start of simulation (volumetric fraction). + + + + +Remarks: +The flow coefficients are used in the following equation that determines the lateral groundwater flow rate based on groundwater and surface water elevations: + QL = A1 (Hgw – Hcb) B1 – A2 (Hsw – Hcb) B2 + A3 Hgw Hsw +where: +QL = lateral groundwater flow (cfs per acre or cms per hectare), +Hgw = height of saturated zone above the bottom of the aquifer (ft or m), +Hsw = height of surface water at the receiving node above the aquifer bottom (ft or m), +Hcb = height of the channel bottom above the aquifer bottom (ft or m). +  +### Section: [GWF] {#engine_manual_sect_GWF} + +Purpose: +Defines custom groundwater flow equations for specific subcatchments. + +Format: +Subcat LATERAL/DEEP Expr + +Parameters: +Subcat subcatchment name. +Expr a math formula expressing the rate of groundwater flow (in cfs per acre or cms per hectare for lateral flow or in/hr or mm/hr for deep flow) as a function of the following variables: +Hgw (for height of the groundwater table) +Hsw (for height of the surface water) +Hcb (for height of the channel bottom) +Hgs (for height of ground surface) +where all heights are relative to the aquifer bottom and have units of either feet or meters; +Ks (for saturated hydraulic conductivity in in/hr or mm/hr) +K (for unsaturated hydraulic conductivity in in/hr or mm/hr) +Theta (for moisture content of the unsaturated zone) +Phi (for aquifer soil porosity) +Fi (for infiltration rate from the ground surface in in/hr or mm/hr) +Fu (for percolation rate from the upper unsaturated zone in in/hr or mm/hr) +A (for subcatchment area in acres or hectares) + +Remarks: +Use LATERAL to designate an expression for lateral groundwater flow (to a node of the conveyance network) and DEEP for vertical loss to deep groundwater. +See the [TREATMENT] section for a list of built-in math functions that can be used in Expr. In particular, the STEP(x) function is 1 when x > 0 and is 0 otherwise. + + + + +Examples: +;Two-stage linear reservoir for lateral flow +Subcatch1 LATERAL 0.001*Hgw + 0.05*(Hgw–5)*STEP(Hgw–5) + +;Constant seepage rate to deep aquifer +Subactch1 DEEP 0.002  +### Section: [SNOWPACKS] {#engine_manual_sect_SNOWPACKS} + +Purpose: +Specifies parameters that govern how snowfall accumulates and melts on the plowable, impervious and pervious surfaces of subcatchments. + +Formats: +Name PLOWABLE Cmin Cmax Tbase FWF SD0 FW0 SNN0 +Name IMPERVIOUS Cmin Cmax Tbase FWF SD0 FW0 SD100 +Name PERVIOUS Cmin Cmax Tbase FWF SD0 FW0 SD100 +Name REMOVAL Dplow Fout Fimp Fperv Fimelt (Fsub Scatch) + +Parameters: +Name name assigned to snowpack parameter set . +Cmin minimum melt coefficient (in/hr-deg F or mm/hr-deg C). +Cmax maximum melt coefficient (in/hr-deg F or mm/hr-deg C). +Tbase snow melt base temperature (deg F or deg C). +FWF ratio of free water holding capacity to snow depth (fraction). +SD0 initial snow depth (in or mm water equivalent). +FW0 initial free water in pack (in or mm). +SNN0 fraction of impervious area that can be plowed. +SD100 snow depth above which there is 100% cover (in or mm water equivalent). +Dplow depth of snow on plowable areas at which snow removal begins (in or mm). +Fout fraction of snow on plowable area transferred out of watershed. +Fimp fraction of snow on plowable area transferred to impervious area by plowing. +Fperv fraction of snow on plowable area transferred to pervious area by plowing. +Fimelt fraction of snow on plowable area converted into immediate melt. +Fsub fraction of snow on plowable area transferred to pervious area in another subcatchment. +Scatch name of subcatchment receiving the Fsub fraction of transferred snow. + + +Remarks: +Use one set of PLOWABLE, IMPERVIOUS, and PERVIOUS lines for each snow pack parameter set created. Snow pack parameter sets are assigned to specific subcatchments in the [SUBCATCHMENTS] section. Multiple subcatchments can share the same set of snow pack parameters. +The PLOWABLE line contains parameters for the impervious area of a subcatchment that is subject to snow removal by plowing but not to areal depletion. This area is the fraction SNN0 of the total impervious area. The IMPERVIOUS line contains parameter values for the remaining impervious area and the PERVIOUS line does the same for the entire pervious area. Both of the latter two areas are subject to areal depletion. +The REMOVAL line describes how snow removed from the plowable area is transferred onto other areas. The various transfer fractions should sum to no more than 1.0. If the line is omitted then no snow removal takes place. + + +  +### Section: [JUNCTIONS] {#engine_manual_sect_JUNCTIONS} + +Purpose: +Identifies each junction node of the drainage system. Junctions are points in space where channels and pipes connect together. For sewer systems they can be either connection fittings or manholes. + +Format: +Name Elev (Ymax Y0 Ysur Apond) + +Parameters: +Name name assigned to junction node. +Elev elevation of the junction’s invert (ft or m). +Ymax depth from ground to invert elevation (ft or m) (default is 0). +Y0 water depth at the start of the simulation (ft or m) (default is 0). +Ysur maximum additional pressure head above the ground elevation that the junction can sustain under surcharge conditions (ft or m) (default is 0). +Apond area subjected to surface ponding once water depth exceeds Ymax + Ysur (ft2 or m2) (default is 0). + +Remarks: +If Ymax is 0 then SWMM sets the junction’s maximum depth to the distance from its invert to the top of the highest connecting link. +If the junction is part of a force main section of the system then set Ysur to the maximum pressure that the system can sustain. +Surface ponding can only occur when Apond is non-zero and the ALLOW_PONDING analysis option is turned on. + + +  +### Section: [OUTFALLS] {#engine_manual_sect_OUTFALLS} + +Purpose: +Identifies each outfall node (i.e., final downstream boundary) of the drainage system and the corresponding water stage elevation. Only one link can be incident on an outfall node. + +Formats: +Name Elev FREE (Gated) (RouteTo) +Name Elev NORMAL (Gated) (RouteTo) +Name Elev FIXED Stage (Gated) (RouteTo) +Name Elev TIDAL Tcurve (Gated) (RouteTo) +Name Elev TIMESERIES Tseries (Gated) (RouteTo) + +Parameters: +Name name assigned to outfall node. +Elev node’s invert elevation (ft or m). +Stage elevation of a fixed stage outfall (ft or m). +Tcurve name of a curve in the [CURVES] section containing tidal height (i.e., outfall stage) versus hour of day over a complete tidal cycle. +Tseries name of a time series in [TIMESERIES] section that describes how outfall stage varies with time. +Gated YES or NO depending on whether a flap gate is present that prevents reverse flow. The default is NO. +RouteTo optional name of a subcatchment that receives the outfall's discharge. The default is not to route the outfall’s discharge. + + + + + +  +### Section: [DIVIDERS] {#engine_manual_sect_DIVIDERS} + +Purpose: +Identifies each flow divider node of the drainage system. Flow dividers are junctions with exactly two outflow conduits where the total outflow is divided between the two in a prescribed manner. + +Formats: +Name Elev DivLink OVERFLOW (Ymax Y0 Ysur Apond) +Name Elev DivLink CUTOFF Qmin (Ymax Y0 Ysur Apond) +Name Elev DivLink TABULAR Dcurve (Ymax Y0 Ysur Apond) +Name Elev DivLink WEIR Qmin Ht Cd (Ymax Y0 Ysur Apond) + +Parameters: +Name name assigned to divider node. +Elev node’s invert elevation (ft or m). +DivLink name of the link to which flow is diverted. +Qmin flow at which diversion begins for either a CUTOFF or WEIR divider (flow units). +Dcurve name of a curve for a TABULAR divider that relates diverted flow to total flow. +Ht height of a WEIR divider (ft or m). +Cd discharge coefficient for a WEIR divider. +Ymax depth from the ground to the node’s invert elevation (ft or m) (default is 0). +Y0 water depth at the start of the simulation (ft or m) (default is 0). +Ysur maximum additional pressure head above the ground elevation that the node can sustain under surcharge conditions (ft or m) (default is 0). +Apond area subjected to surface ponding once water depth exceeds Ymax + Ysur (ft2 or m2) (default is 0). + + + + +Remarks: +If Ymax is 0 then SWMM sets the node’s maximum depth equal to the distance from its invert to the top of the highest connecting link. +Surface ponding can only occur when Apond is non-zero and the ALLOW_PONDING analysis option is turned on. +Divider nodes are only active under the Steady Flow or Kinematic Wave analysis options. For Dynamic Wave flow routing they behave the same as Junction nodes. + + +  +### Section: [STORAGE] {#engine_manual_sect_STORAGE} + +Purpose: +Identifies each storage node of the drainage system. Storage nodes can have any shape as specified by a surface area versus water depth relation. + +Formats: +Name Elev Ymax Y0 TABULAR Acurve (Ysur Fevap Psi Ksat IMD) +Name Elev Ymax Y0 FUNCTIONAL A1 A2 A0 (Ysur Fevap Psi Ksat IMD) +Name Elev Ymax Y0 Shape L W Z (Ysur Fevap Psi Ksat IMD) + +Parameters: +Name name assigned to storage node. +Elev node’s invert elevation (ft or m). +Ymax water depth when the storage node is full (ft or m). +Y0 water depth at the start of the simulation (ft or m). +Acurve name of a curve in the [CURVES] section that relates surface area (ft2 or m2) to depth (ft or m) for TABULAR geometry. +A1 coefficient of a FUNCTIONAL relation between surface area and depth. +A2 exponent of a FUNCTIONAL relation between surface area and depth. +A0 constant of a FUNCTIONAL relation between surface area and depth. +Shape shape used to relate surface area to depth; choices are CYLINDRICAL, CONICAL, PARABOLOID, or PYRAMIDAL. +Ysur maximum additional pressure head above full depth that a closed storage unit can sustain under surcharge conditions (ft or m) (default is 0). +L, W, Z dimensions of the storage unit's shape (see table below). +Fevap fraction of potential evaporation from the storage unit’s water surface realized (default is 0). +Optional seepage parameters for soil surrounding the storage unit: +Psi suction head (inches or mm). +Ksat saturated hydraulic conductivity (in/hr or mm/hr). +IMD initial moisture deficit (porosity minus moisture content) (fraction). +Remarks: +A1, A2, and A0 are used in the following expression that relates surface area (ft2 or m2) to water depth (ft or m) for a storage unit with FUNCTIONAL geometry: +Area=A0+A1〖Depth〗^A2 +For TABULAR geometry, the surface area curve will be extrapolated outwards to meet the unit's maximum depth if need be. +The dimensions of storage units with other shapes are defined as follows: +Shape L W Z +CYLINDRICAL + major axis length minor axis width not used +CONICAL + major axis length of base minor axis width of base side slope (run/rise) +PARABOLOID + major axis length at full height minor axis width at full height full height +PYRAMIDAL + base length base width side slope (run/rise) + +The parameters Psi, Ksat, and IMD need only be supplied if seepage loss through the soil at the bottom and sloped sides of the storage unit should be considered. They are the same Green-Ampt infiltration parameters described in the [INFILTRATION] section. If Ksat is zero then no seepage occurs while if IMD is zero then seepage occurs at a constant rate equal to Ksat. Otherwise seepage rate will vary with storage depth. +  +### Section: [CONDUITS] {#engine_manual_sect_CONDUITS} + +Purpose: +Identifies each conduit link of the drainage system. Conduits are pipes or channels that convey water from one node to another. + +Format: +Name Node1 Node2 Length N Z1 Z2 (Q0 Qmax) + +Parameters: +Name name assigned to conduit link. +Node1 name of the conduit’s upstream node. +Node2 name of the conduit’s downstream node. +Length conduit length (ft or m). +N Manning’s roughness coefficient (n). +Z1 offset of the conduit’s upstream end above the invert of its upstream node (ft or m). +Z2 offset of the conduit’s downstream end above the invert of its downstream node (ft or m). +Q0 flow in the conduit at the start of the simulation (flow units) (default is 0). +Qmax maximum flow allowed in the conduit (flow units) (default is no limit). + +Remarks: +The figure below illustrates the meaning of the Z1 and Z2 parameters. + +These offsets are expressed as a relative distance above the node invert if the LINK_OFFSETS option is set to DEPTH (the default) or as an absolute elevation if it is set to ELEVATION. + + +### Section: [PUMPS] {#engine_manual_sect_PUMPS} + +Purpose: +Identifies each pump link of the drainage system. + +Format: +Name Node1 Node2 Pcurve (Status Startup Shutoff) + +Parameters: +Name name assigned to pump link. +Node1 name of the pump’s inlet node. +Node2 name of the pump’s outlet node. +Pcurve name of a pump curve listed in the [CURVES] section of the input. +Status pump’s status at the start of the simulation (either ON or OFF; default is ON). +Startup depth at the inlet node when the pump turns on (ft or m) (default is 0). +Shutoff depth at inlet node when the pump shuts off (ft or m) (default is 0). + +Remarks: +See @ref engine_manual_ch1_conceptual_model for a description of the different types of pumps available. + + +  +### Section: [ORIFICES] {#engine_manual_sect_ORIFICES} + +Purpose: +Identifies each orifice link of the drainage system. An orifice link serves to limit the flow exiting a node and is often used to model flow diversions and storage node outlets. + +Format: +Name Node1 Node2 Type Offset Cd (Gated Orate) + +Parameters: +Name name assigned to orifice link. +Node1 name of the orifice’s inlet node. +Node2 name of the orifice’s outlet node. +Type the type of orifice - either SIDE if oriented in a vertical plane or BOTTOM if oriented in a horizontal plane. +Offset amount that a Side Orifice’s bottom or the position of a Bottom Orifice is offset above the invert of inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting). +Cd discharge coefficient (unitless). +Flap YES if a flap gate prevents reverse flow, NO if not (default is NO). +Orate time in decimal hours to open a fully closed orifice (or close a fully open one). Use 0 if the orifice can open/close instantaneously. + +Remarks: +The geometry of an orifice’s opening must be described in the [XSECTIONS] section. The only allowable shapes are CIRCULAR and RECT_CLOSED (closed rectangular). + + + + + + + + + + +### Section: [WEIRS] {#engine_manual_sect_WEIRS} + +Purpose: +Identifies each weir link of the drainage system. Weirs are used to model flow diversions and storage node outlets. + +Format: +Name Node1 Node2 Type CrstHt Cd (Gated EC Cd2 Sur (Width Surf)) + +Parameters: +Name name assigned to weir link. +Node1 name of the weir’s inlet node. +Node2 name of the weir’s outlet node. +Type TRANSVERSE, SIDEFLOW, V-NOTCH, TRAPEZOIDAL or ROADWAY. +CrstHt amount that the weir’s opening is offset above the invert of inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting). +Cd weir discharge coefficient (for CFS if using US flow units or CMS if using metric flow units). +Gated YES if a flap gate prevents reverse flow, NO if not (default is NO). +EC number of end contractions for a TRANSVERSE or TRAPEZOIDAL weir (default is 0). +Cd2 discharge coefficient for the triangular ends of a TRAPEZOIDAL weir (for CFS if using US flow units or CMS if using metric flow units) (default is the value of Cd). +Sur YES if the weir can surcharge (have an upstream water level higher than the height of the weir’s opening); NO if it cannot (default is YES). +The following parameters apply only to ROADWAY weirs: +Width width of road lanes and shoulders for a ROADWAY weir (ft or m). +Surf type of road surface for a ROADWAY weir: PAVED or GRAVEL. + +Remarks: +The geometry of a weir’s opening is described in the [XSECTIONS] section. The following shapes must be used with each type of weir: + +Weir Type Cross-Section Shape +Transverse RECT_OPEN +Sideflow RECT_OPEN +V-Notch TRIANGULAR +Trapezoidal TRAPEZOIDAL +Roadway RECT_OPEN + +The ROADWAY weir is a broad crested rectangular weir used model roadway crossings usually in conjunction with culvert-type conduits. It uses the FHWA HDS-5 method to determine a discharge coefficient as a function of flow depth and roadway width and surface. If no roadway data are provided then the weir behaves as a TRANSVERSE weir with Cd as its discharge coefficient. Note that if roadway data are provided, then values for the other optional weir parameters (NO for Gated, 0 for EC, 0 for Cd2, and NO for Sur) must be entered even though they do not apply to ROADWAY weirs. + + + +  +### Section: [OUTLETS] {#engine_manual_sect_OUTLETS} + +Purpose: +Identifies each outlet flow control device of the drainage system. These are devices used to model outflows from storage units or flow diversions that have a user-defined relation between flow rate and water depth. + +Formats: +Name Node1 Node2 Offset TABULAR/DEPTH Qcurve (Gated) +Name Node1 Node2 Offset TABULAR/HEAD Qcurve (Gated) +Name Node1 Node2 Offset FUNCTIONAL/DEPTH C1 C2 (Gated) +Name Node1 Node2 Offset FUNCTIONAL/HEAD C1 C2 (Gated) + +Parameters: +Name name assigned to outlet link. +Node1 name of the outlet’s inlet node. +Node2 name of the outlet’s outlet node. +Offset amount that the outlet is offset above the invert of its inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting). +Qcurve name of the rating curve listed in the [CURVES] section that describes outflow rate (flow units) as a function of: + water depth above the offset elevation at the inlet node (ft or m) for a TABULAR/DEPTH outlet + head difference (ft or m) between the inlet and outflow nodes for a TABULAR/HEAD outlet. +C1, C2 coefficient and exponent, respectively, of a power function that relates outflow (Q) to: + water depth (ft or m) above the offset elevation at the inlet node for a FUNCTIONAL/DEPTH outlet + head difference (ft or m) between the inlet and outflow nodes for a FUNCTIONAL/HEAD outlet. +(i.e., Q=C1H^C2 where H is either depth or head). +Gated YES if a flap gate prevents reverse flow, NO if not (default is NO). + +### Section: [XSECTIONS] {#engine_manual_sect_XSECTIONS} + +Purpose: +Provides cross-section geometric data for conduit and regulator links of the drainage system. + +Formats: +Link Shape Geom1 Geom2 Geom3 Geom4 (Barrels Culvert) +Link IRREGULAR Tsect +Link STREET Street + +Parameters: +Link name of a conduit, orifice, or weir. +Shape a cross-section shape (see Tables D-1 below or 3-1 for available shapes). +Geom1 full height of the cross-section (ft or m). +Geom2-4 auxiliary parameters (width, side slopes, etc.) as listed in Table D-1. +Barrels number of barrels (i.e., number of parallel pipes of equal size, slope, and roughness) associated with a conduit (default is 1). +Culvert code number from Table A.10 for the conduit’s inlet geometry if it is a culvert subject to possible inlet flow control (leave blank otherwise). +Curve name of a Shape Curve in the [CURVES] section that defines how cross-section width varies with depth. +Tsect name of an entry in the [TRANSECTS] section that describes the cross-section geometry of an irregular channel. +Street name of an entry in the [STREETS] section that describes the cross-section geometry of a street. + +Remarks: +The standard conduit shapes and their geometric parameters are listed in the following table: + + +Table D 2 Geometric parameters of conduit cross sections +Shape Geom1 Geom2 Geom3 Geom4 +CIRCULAR Diameter +FORCE_MAIN Diameter Roughness1 +FILLED_CIRCULAR2 Diameter Sediment Depth +RECT_CLOSED Full Height Top Width +RECT_OPEN Full Height Top Width +TRAPEZOIDAL Full Height Base Width Left Slope3 Right Slope3 +TRIANGULAR Full Height Top Width +HORIZ_ELLIPSE Full Height Max. Width Size Code4 +VERT_ELLIPSE Full Height Max. Width Size Code4 +ARCH Full Height Max. Width Size Code5 +PARABOLIC Full Height Top Width +POWER Full Height Top Width Exponent +RECT_TRIANGULAR Full Height Top Width Triangle Height +RECT_ROUND Full Height Top Width Bottom Radius +MODBASKETHANDLE Full Height Base Width Top Radius6 +EGG Full Height +HORSESHOE Full Height +GOTHIC Full Height +CATENARY Full Height +SEMIELLIPTICAL Full Height +BASKETHANDLE Full Height +SEMICIRCULAR Full Height +CUSTOM Full Height Shape Curve +1C-factors are used when H-W is the FORCE_MAIN_EQUATION choice in the [OPTIONS] section while roughness heights (in inches or mm) are used for D-W. + 2A circular conduit partially filled with sediment to a specified depth. +3Slopes are horizontal run / vertical rise. +4Size code of a standard shaped elliptical pipe as listed in Appendix A12. Leave blank (or 0) if the pipe has custom dimensions. +5Size code of a standard arch pipe as listed in Appendix A13. Leave blank (or 0) if the pipe has custom dimensions). +6Set to zero to use a standard modified baskethandle shape whose top radius is half the base width. +The CUSTOM shape is a closed conduit whose width versus height is described by a user-supplied Shape Curve. +An IRREGULAR cross-section is used to model an open channel whose geometry is described by a Transect object. +A STREET cross-section is used to model street conduits and inlet flow capture (see the [INLETS] and [INLETS_USAGE] sections). +The Culvert code number is used only for closed conduits acting as culverts that should be analyzed for inlet control conditions using the FHWA HDS-5 methodology. +  +### Section: [TRANSECTS] {#engine_manual_sect_TRANSECTS} + +Purpose: +Describes the cross-section geometry of natural channels or conduits with irregular shapes following the HEC-2 data format. + +Formats: +NC Nleft Nright Nchanl +X1 Name Nsta Xleft Xright 0 0 0 Lfactor Wfactor Eoffset +GR Elev Station ... Elev Station + +Parameters: +Nleft Manning’s roughness coefficient (n) of right overbank portion of channel (use 0 if no change from previous NC line). +Nright Manning’s roughness coefficient (n) of right overbank portion of channel (use 0 if no change from previous NC line. +Nchanl Manning’s roughness coefficient (n) of main channel portion of channel (use 0 if no change from previous NC line. +Name name assigned to the transect. +Nsta number of stations across the cross-section’s width at which elevation data is supplied. +Xleft station position which ends the left overbank portion of the channel (ft or m). +Xright station position which begins the right overbank portion of the channel (ft or m). +Lfactor meander modifier that represents the ratio of the length of a meandering main channel to the length of the overbank area that surrounds it (use 0 if not applicable). +Wfactor factor by which distances between stations should be multiplied to increase (or decrease) the width of the channel (enter 0 if not applicable). +Eoffset amount to be added (or subtracted) from the elevation of each station (ft or m). +Elev elevation of the channel bottom at a cross-section station relative to some fixed reference (ft or m). +Station distance of a cross-section station from some fixed reference (ft or m). + + +Remarks: +Transect geometry is described as shown below, assuming that one is looking in a downstream direction: + + +The first line in this section must always be a NC line. After that, the NC line is only needed when a transect has different Manning’s n values than the previous one. +The Manning’s n values on the NC line will supersede any roughness value entered for the conduit which uses the irregular cross-section. +There should be one X1 line for each transect. Any number of GR lines may follow, and each GR line can have any number of Elevation-Station data pairs. (In HEC-2 the GR line is limited to 5 stations.) +The station that defines the left overbank boundary on the X1 line must correspond to one of the station entries on the GR lines that follow. The same holds true for the right overbank boundary. If there is no match, a warning will be issued and the program will assume that no overbank area exists. +The meander modifier is applied to all conduits that use this particular transect for their cross section. It assumes that the length supplied for these conduits is that of the longer main channel. SWMM will use the shorter overbank length in its calculations while increasing the main channel roughness to account for its longer length. +  +### Section: [STREETS] {#engine_manual_sect_STREETS} + +Purpose: +Describes the cross-section geometry of conduits that represent streets. + +Format: +Name Tcrown Hcurb Sx nRoad (a W)(Sides Tback Sback nBack) + +Parameters: +Name name assigned to the street cross-section +Tcrown distance from street’s curb to its crown (ft or m) +Hcurb curb height (ft or m) +Sx street cross slope (%) +nRoad Manning’s roughness coefficient (n) of the road surface +a gutter depression height (in or mm) (default = 0) +W depressed gutter width (ft or m) (default = 0) +Sides 1 for single sided street or 2 for two-sided street (default = 2) +Tback street backing width (ft or m) (default = 0) +Sback street backing slope (%) (default = 0) +nBack street backing Manning’s roughness coefficient (n) (default = 0) + +Remarks: + + +If the street has no depressed gutter (a = 0) then the gutter width entry is ignored. If the street has no backing then the three backing parameters can be omitted. +### Section: [INLETS] {#engine_manual_sect_INLETS} + +Purpose: +Defines inlet structure designs used to capture street and channel flow that are sent to below ground sewers. + +Format: +Name GRATE/DROP_GRATE Length Width Type (Aopen Vsplash) +Name CURB/DROP_CURB Length Height (Throat) +Name SLOTTED Length Width +Name CUSTOM Dcurve/Rcurve + +Parameters: +Name name assigned to the inlet structure. +Length length of the inlet parallel to the street curb (ft or m). +Width width of a GRATE or SLOTTED inlet (ft or m). +Height height of a CURB opening inlet (ft or m). +Type type of GRATE used (see below). +Aopen fraction of a GENERIC grate’s area that is open. +Vsplash splash over velocity for a GENERIC grate (ft/s or m/s). +Throat the throat angle of a CURB opening inlet (HORIZONTAL, INCLINED or VERTICAL). +Dcurve name of a Diversion-type curve (captured flow v. approach flow) for a CUSTOM inlet. +Rcurve name of a Rating-type curve (captured flow v. water depth) for a CUSTOM inlet. + +Remarks: +See @ref engine_manual_ch1_conceptual_model for a description of the different types of inlets that SWMM can model. +Use one line for each inlet design except for a combination inlet where one GRATE line describes its grated inlet and a second CURB line (with the same inlet name) describes its curb opening inlet. + +GRATE, CURB, and SLOTTED inlets are used with STREET conduits, DROP_GRATE and DROP_CURB inlets with open channels, and a CUSTOM inlet with any conduit. +GRATE and DROP_GRATE types can be any of the following: +Grate Type Sketch Description +P_BAR-50 Parallel bar grate with bar spacing 1⅞” on center +P_BAR-50X100 Parallel bar grate with bar spacing 1⅞” on center and ⅜” diameter lateral rods spaced at 4” on center +P_BAR-30 Parallel bar grate with 1⅛” on center bar spacing +CURVED_VANE Curved vane grate with 3¼” longitudinal bar and 4¼” transverse bar spacing on center +TILT_BAR-45 45 degree tilt bar grate with 2¼” longitudinal bar and 4” transverse bar spacing on center +TILT_BAR-30 30 degree tilt bar grate with 3¼” and 4” on center longitudinal and lateral bar spacing respectively +RETICULINE "Honeycomb" pattern of lateral bars and longitudinal bearing bars +GENERIC A generic grate design. + + Only a GENERIC type grate requires that Aopen and Vsplash values be provided. The other standard grate types have predetermined values of these parameters. (Splash over velocity is the minimum velocity that will cause some water to shoot over the inlet thus reducing its capture efficiency). + A CUSTOM inlet takes the name of either a Diversion curve or a Rating curve as its only parameter (see the [CURVES] section). Diversion curves are best suited for on-grade inlets and Rating curves for on-sag inlets. + + +Examples: +; A 2-ft x 2-ft parallel bar grate +InletType1 GRATE 2 2 P-BAR-30 +; A combination inlet +InletType2 GRATE 2 2 CURVED_VANE +InletType2 CURB 4 0.5 HORIZONTAL +; A custom inlet using Curve1 as its capture curve +InletType3 CUSTOM Curve1 +  +### Section: [INLET_USAGE] {#engine_manual_sect_INLET_USAGE} + +Purpose: +Assigns inlet structures to specific street and open channel conduits. + +Format: +Conduit Inlet Node (Number %Clogged Qmax aLocal wLocal Placement) + +Parameters: +Conduit name of a street or open channel conduit containing the inlet. +Inlet name of an inlet structure (from the [INLETS] section) to use. +Node name of the sewer node receiving flow captured by the inlet. +Number number of replicate inlets placed on each side of the street. +%Clogged degree to which inlet capacity is reduced due to clogging (%). +Qmax maximum flow that the inlet can capture (flow units). +aLocal height of local gutter depression (in or mm). +wLocal width of local gutter depression (ft or m). +Placement AUTOMATIC, ON_GRADE, or ON_SAG. + +Remarks: +Only conduits with a STREET cross section can be assigned a curb and gutter inlet while drop inlets can only be assigned to conduits with a RECT_OPEN or TRAPEZOIDAL cross section. +Only the first three parameters are required. The default number of inlets is 1 (for each side of a two-sided street) while the remaining parameters have default values of 0. +A Qmax value of 0 indicates that the inlet has no flow restriction. +The local gutter depression applies only over the length of the inlet unlike the continuous depression for a STREET cross section which exists over the full curb length. +The default inlet placement is AUTOMATIC, meaning that the program uses the network topography to determine whether an inlet operates on-grade or on-sag. On-grade means the inlet is located on a continuous grade. On-sag means the inlet is located at a sag or sump point where all adjacent conduits slope towards the inlet leaving no place for water to flow except into the inlet. +### Section: [LOSSES] {#engine_manual_sect_LOSSES} + +Purpose: +Specifies minor head loss coefficients, flap gates, and seepage rates for conduits. + +Format: +Conduit Kentry Kexit Kavg (Flap Seepage) + +Parameters: +Conduit name of a conduit. +Kentry minor head loss coefficient at the conduit’s entrance. +Kexit minor head loss coefficient at the conduit’s exit. +Kavg average minor head loss coefficient across the length of the conduit. +Flap YES if the conduit has a flap valve that prevents back flow, NO otherwise. (Default is NO). +Seepage Rate of seepage loss into the surrounding soil (in/hr or mm/hr). (Default is 0.) + +Remarks: +Minor losses are only computed for the Dynamic Wave flow routing option (see the [OPTIONS] section). They are computed as Kv2/2g where K = minor loss coefficient, v = velocity, and g = acceleration of gravity. Entrance losses are based on the velocity at the entrance of the conduit, exit losses on the exit velocity, and average losses on the average velocity. +Only enter data for conduits that actually have minor losses, flap valves, or seepage losses. + + + +  +### Section: [CONTROLS] {#engine_manual_sect_CONTROLS} + +Purpose: +Determines how pumps and regulators will be adjusted based on simulation time or conditions at specific nodes and links. + +Formats: +Each control rule is a series of statements of the form: +RULE ruleID +IF condition_1 +AND condition_2 +OR condition_3 +AND condition_4 +Etc. +THEN action_1 +AND action_2 +Etc. +ELSE action_3 +AND action_4 +Etc. +PRIORITY value + +Parameters: + ruleID an ID label assigned to the rule. +condition_n a condition clause. +action_n an action clause. +value a priority value (e.g., a number from 1 to 5). + +Remarks: +Please refer to Section C.3 for a complete description of the control rule format plus examples of different types of rule statements. +  +### Section: [POLLUTANTS] {#engine_manual_sect_POLLUTANTS} + +Purpose: +Identifies the pollutants being analyzed. + +Format: +Name Units Crain Cgw Cii Kd (Sflag CoPoll CoFract Cdwf Cinit) + +Parameters: +Name name assigned to a pollutant. +Units concentration units (MG/L for milligrams per liter, UG/L for micrograms per liter, or #/L for direct count per liter). +Crain concentration of the pollutant in rainfall (concentration units). +Cgw concentration of the pollutant in groundwater (concentration units). +Cii concentration of the pollutant in rainfall-dependent infiltration and inflow (concentration units). +Kdecay first-order decay coefficient (1/days). +Sflag YES if pollutant buildup occurs only when there is snow cover, NO otherwise (default is NO). +CoPoll name of a co-pollutant (default is no co-pollutant designated by a *). +CoFract fraction of the co-pollutant’s concentration (default is 0). +Cdwf pollutant concentration in dry weather flow (default is 0). +Cinit pollutant concentration throughout the conveyance system at the start of the simulation (default is 0). +Remarks: +FLOW is a reserved word and cannot be used to name a pollutant. +Parameters Sflag through Cinit can be omitted if they assume their default values. If there is no co-pollutant but non-default values for Cdwf or Cinit, then enter an asterisk (*) for the co-pollutant name. +When pollutant X has a co-pollutant Y, it means that fraction CoFract of pollutant Y’s runoff concentration is added to pollutant X’s runoff concentration when wash off from a subcatchment is computed. +The dry weather flow concentration can be overridden for any specific node of the conveyance system by editing the node’s Inflows property (see the [INFLOWS] section).  +### Section: [LANDUSES] {#engine_manual_sect_LANDUSES} + +Purpose: +Identifies the various categories of land uses within the drainage area. Each subcatchment area can be assigned a different mix of land uses. Each land use can be subjected to a different street sweeping schedule. Land uses are only used in conjunction with pollutant buildup and wash off. + +Format: +Name (SweepInterval Availability LastSweep) + +Parameters: +Name land use name. +SweepInterval days between street sweeping. +Availability fraction of pollutant buildup available for removal by street sweeping. +LastSweep days since last sweeping at the start of the simulation. +  +### Section: [COVERAGES] {#engine_manual_sect_COVERAGES} + +Purpose: +Specifies the percentage of a subcatchment’s area that is covered by each category of land use. + +Format: + Subcat Landuse Percent Landuse Percent . . . + +Parameters: +Subcat subcatchment name. +Landuse land use name. +Percent percent of the subcatchment’s area covered by the land use. + +Remarks: +More than one pair of land use - percentage values can be entered per line. If more than one line is needed, then the subcatchment name must still be entered first on the succeeding lines. +If a land use does not pertain to a subcatchment, then it does not have to be entered. +If no land uses are associated with a subcatchment then no pollutants will appear in the runoff from the subcatchment. + + + +  +### Section: [LOADINGS] {#engine_manual_sect_LOADINGS} + +Purpose: +Specifies the pollutant buildup that exists on each subcatchment at the start of a simulation. + +Format: +Subcat Pollut InitBuildup Pollut InitBuildup ... + +Parameters: +Subcat name of a subcatchment. +Pollut name of a pollutant. +InitBuildup initial buildup of the pollutant (lbs/acre or kg/hectare). + +Remarks: +More than one pair of pollutant - buildup values can be entered per line. If more than one line is needed, then the subcatchment name must still be entered first on the succeeding lines. +If an initial buildup is not specified for a pollutant, then its initial buildup is computed by applying the DRY_DAYS option (specified in the [OPTIONS] section) to the pollutant’s buildup function for each land use in the subcatchment. + + +  +### Section: [BUILDUP] {#engine_manual_sect_BUILDUP} + +Purpose: +Specifies the rate at which pollutants build up over different land uses between rain events. + +Format: +Landuse Pollutant FuncType C1 C2 C3 PerUnit + +Parameters: +Landuse land use name. +Pollutant pollutant name. +FuncType buildup function type: ( POW / EXP / SAT / EXT ). +C1,C2,C3 buildup function parameters (see Table D-2). +PerUnit AREA if buildup is per unit area, CURBLENGTH if per length of curb. + +Remarks: +Buildup is measured in pounds (kilograms) per unit of area (or curb length) for pollutants whose concentration units are either mg/L or ug/L. If the concentration units are counts/L, then buildup is expressed as counts per unit of area (or curb length). + +Table D 3 Pollutant buildup functions +Name Function Equation* +POW Power Min (C1, C2*tC3) +EXP Exponential C1*(1 – exp(-C2*t)) +SAT Saturation C1*t / (C3 + t) +EXT External See below +*t is antecedent dry days. + +For the EXT buildup function, C1 is the maximum possible buildup (mass per area or curb length), C2 is a scaling factor, and C3 is the name of a Time Series that contains buildup rates (as mass per area or curb length per day) as a function of time. +  +### Section: [WASHOFF] {#engine_manual_sect_WASHOFF} + +Purpose: +Specifies the rate at which pollutants are washed off from different land uses during rain events. + +Format: +Landuse Pollutant FuncType C1 C2 SweepRmvl BmpRmvl + +Parameters: +Landuse land use name. +Pollutant pollutant name. +FuncType washoff function type: EXP / RC / EMC. +C1, C2 washoff function coefficients(see Table D-3). +SweepRmvl street sweeping removal efficiency (percent). +BmpRmvl BMP removal efficiency (percent). + +Remarks: +Table D 4 Pollutant wash off functions +Name Function Equation Units +EXP Exponential C1 (runoff)C2 (buildup) Mass/hour +RC Rating Curve C1 (runoff)C2 Mass/sec +EMC Event Mean +Concentration C1 Mass/Liter + +Each washoff function expresses its results in different units. +For the Exponential function the runoff variable is expressed in catchment depth per unit of time (inches per hour or millimeters per hour), while for the Rating Curve function it is in whatever flow units were specified in the [OPTIONS] section of the input file (e.g., CFS, CMS, etc.). + +The buildup parameter in the Exponential function is the current total buildup over the subcatchment’s land use area in mass units. The units of C1 in the Exponential function are (in/hr) -C2 per hour (or (mm/hr) -C2 per hour). For the Rating Curve function, the units of C1 depend on the flow units employed. For the EMC (event mean concentration) function, C1 is always in concentration units. + + +  +### Section: [TREATMENT] {#engine_manual_sect_TREATMENT} + +Purpose: +Specifies the degree of treatment received by pollutants at specific nodes of the drainage system. + +Format: +Node Pollut Result = Func + +Parameters: +Node Name of the node where treatment occurs. +Pollut Name of pollutant receiving treatment. +Result Result computed by treatment function. Choices are: +C (function computes effluent concentration) +R (function computes fractional removal). +Func mathematical function expressing treatment result in terms of pollutant concentrations, pollutant removals, and other standard variables (see below). + +Remarks: +Treatment functions can be any well-formed mathematical expression involving: + inlet pollutant concentrations (use the pollutant name to represent a concentration) + removal of other pollutants (use R_ pre-pended to the pollutant name to represent removal) + process variables which include: +FLOW for flow rate into node (user’s flow units) +DEPTH for water depth above node invert (ft or m) +AREA for node surface area (ft2 or m2) +DT for routing time step (seconds) +HRT for hydraulic residence time (hours) + +Any of the following math functions can be used in a treatment function: + abs(x) for absolute value of x + sgn(x) which is +1 for x >= 0 or -1 otherwise + step(x) which is 0 for x <= 0 and 1 otherwise + sqrt(x) for the square root of x + log(x) for logarithm base e of x + log10(x) for logarithm base 10 of x + exp(x) for e raised to the x power + the standard trig functions (sin, cos, tan, and cot) + the inverse trig functions (asin, acos, atan, and acot) + the hyperbolic trig functions (sinh, cosh, tanh, and coth) +along with the standard operators +, -, *, /, ^ (for exponentiation ) and any level of nested parentheses. + +Examples: +; 1-st order decay of BOD +Node23 BOD C = BOD * exp(-0.05*HRT) + +; lead removal is 20% of TSS removal +Node23 Lead R = 0.2 * R_TSS + + + + +  +### Section: [INFLOWS] {#engine_manual_sect_INFLOWS} + +Purpose: +Specifies external hydrographs and pollutographs that enter the drainage system at specific nodes. + +Formats: +Node FLOW Tseries (FLOW (1.0 Sfactor Base Pat)) +Node Pollut Tseries (Type (Mfactor Sfactor Base Pat)) + +Parameters: +Node name of the node where external inflow enters. +Pollut name of a pollutant. +Tseries name of a time series in the [TIMESERIES] section describing how external flow or pollutant loading varies with time. +Type CONCEN if pollutant inflow is described as a concentration, MASS if it is described as a mass flow rate (default is CONCEN). +Mfactor the factor that converts the inflow’s mass flow rate units into the project’s mass units per second, where the project’s mass units are those specified for the pollutant in the [POLLUTANTS] section (default is 1.0 - see example below). +Sfactor a scaling factor that multiplies the recorded time series values (default is 1.0). +Base a constant baseline value added to the time series value (default is 0.0). +Pat name of an optional time pattern in the [PATTERNS] section used to adjust the baseline value on a periodic basis. + +Remarks: +External inflows are represented by both a constant and time varying component as follows: +Inflow = (Baseline value)*(Pattern factor) + +(Scaling factor)*(Time series value) +If an external inflow of a pollutant concentration is specified for a node, then there must also be an external inflow of FLOW provided for the same node, unless the node is an Outfall. In that case a pollutant can enter the system during periods when the outfall is submerged and reverse flow occurs. External pollutant mass inflows do not require a FLOW inflow. + +Examples: +; NODE2 receives flow inflow from time series N2FLOW +; and TSS concentration from time series N2TSS +NODE2 FLOW N2FLOW +NODE2 TSS N33TSS CONCEN + +; NODE65 has a mass inflow of BOD from time series N65BOD +; listed in lbs/hr (126 converts lbs/hr to mg/sec) +NODE65 BOD N65BOD MASS 126 + +; Flow inflow to Node N176 consists of the flow time series +; FLOW_176 scaled at 0.5 plus a baseline flow of 12.7 +; adjusted by pattern FlowPat +N176 FLOW FLOW_176 FLOW 1.0 0.5 12.7 FlowPat  +### Section: [DWF] {#engine_manual_sect_DWF} + +Purpose: +Specifies dry weather flow and its quality entering the drainage system at specific nodes. + +Format: +Node Type Base (Pat1 Pat2 Pat3 Pat4) + +Parameters: +Node name of a node where dry weather flow enters. +Type keyword FLOW for flow or a pollutant name for a quality constituent. +Base average baseline value for corresponding constituent (flow or concentration units). +Pat1, +Pat2, +etc. names of up to four time patterns appearing in the [PATTERNS] section. + +Remarks: +The actual dry weather input will equal the product of the baseline value and any adjustment factors supplied by the specified patterns. (If not supplied, an adjustment factor defaults to 1.0.) +The patterns can be any combination of monthly, daily, hourly and weekend hourly patterns, listed in any order. See the [PATTERNS] section for more details. + + +  +### Section: [RDII] {#engine_manual_sect_RDII} + +Purpose: +Specifies the parameters that describe rainfall-dependent infiltration and inflow (RDII) entering the drainage system at specific nodes. + +Format: + Node UHgroup SewerArea + +Parameters: +Node name of a node receiving RDII flow. +UHgroup name of an RDII unit hydrograph group appearing in the [HYDROGRAPHS] section. +SewerArea area of the sewershed that contributes RDII to the node (acres or hectares). + + +  +### Section: [HYDROGRAPHS] {#engine_manual_sect_HYDROGRAPHS} + +Purpose: +Specifies the shapes of the triangular unit hydrographs that determine the amount of rainfall-dependent infiltration and inflow (RDII) entering the drainage system. + +Format: +Name Raingage +Name Month SHORT/MEDIUM/LONG R T K (Dmax Drec D0) + +Remarks: +Name name assigned to a unit hydrograph group. +Raingage name of the rain gage used by the unit hydrograph group. +Month month of the year (e.g., JAN, FEB, etc. or ALL for all months). +R response ratio for the unit hydrograph. +T time to peak (hours) for the unit hydrograph. +K recession limb ratio for the unit hydrograph. +Dmax maximum initial abstraction depth available (in rain depth units). +Drec initial abstraction recovery rate (in rain depth units per day) +D0 initial abstraction depth already filled at the start of the simulation (in rain depth units). + +Remarks: +For each group of unit hydrographs, use one line to specify its rain gage followed by as many lines as are needed to define each unit hydrograph used by the group throughout the year. Three separate unit hydrographs, that represent the short-term, medium-term, and long-term RDII responses, can be defined for each month (or all months taken together). Months not listed are assumed to have no RDII. +The response ratio (R) is the fraction of a unit of rainfall depth that becomes RDII. The sum of the ratios for a set of three hydrographs does not have to equal 1.0. +The recession limb ratio (K) is the ratio of the duration of the hydrograph’s recession limb to the time to peak (T) making the hydrograph time base equal to T*(1+K) hours. The area under each unit hydrograph is 1 inch (or mm). + +The optional initial abstraction parameters determine how much rainfall is lost at the start of a storm to interception and depression storage. If not supplied then the default is no initial abstraction. + +Lines are processed in the order they appear, and an entry for ALL assigns its values to every month of the year. An ALL entry therefore overrides any month-specific values entered on earlier lines (e.g., if entries appear in the order JAN through SEP, ALL, OCT, NOV, DEC, the ALL entry replaces the values entered for JAN through SEP, leaving only OCT, NOV, and DEC with their own values). Whenever parameters for the same month and response type are supplied more than once, the values entered last are used and WARNING 13 is written to the status report. + +Example: +; All three unit hydrographs in this group have the same shapes except those in July, +; which have only a short- and medium-term response and a different shape. +UH101 RG1 +UH101 ALL SHORT 0.033 1.0 2.0 +UH101 ALL MEDIUM 0.300 3.0 2.0 +UH101 ALL LONG 0.033 10.0 2.0 +UH101 JUL SHORT 0.033 0.5 2.0 +UH101 JUL MEDIUM 0.011 2.0 2.0 + +### Section: [CURVES] {#engine_manual_sect_CURVES} + +Purpose: +Describes a relationship between two variables in tabular format. + +Format: +Name Type +Name X-value Y-value ... + +Parameters: +Name name assigned to the curve. +Type the type of curve being defined: +STORAGE / SHAPE / DIVERSION / TIDAL / PUMP1 / PUMP2 / PUMP3 / PUMP4 / PUMP5 / RATING / CONTROL / WEIR. +X-value an X (independent variable) value. +Y-value the Y (dependent variable) value corresponding to X. + +Remarks: +Each curve should have its name and type on the first line with its data points entered on subsequent lines. +Multiple pairs of x-y values can appear on a line. If more than one line is needed, repeat the curve's name on subsequent lines. +X-values must be entered in increasing order. +Choices for curve type have the following meanings (flows are expressed in the user’s choice of flow units set in the [OPTIONS] section): +STORAGE surface area in ft2 (m2) versus depth in ft (m) for a storage unit node +SHAPE width versus depth for a custom closed cross-section, both normalized with respect to full depth +DIVERSION diverted outflow versus total inflow for a flow divider node or a Custom inlet +TIDAL water surface elevation in ft (m) versus hour of the day for an outfall node +PUMP1 pump outflow versus increment of inlet node volume in ft3 (m3) +PUMP2 pump outflow versus increment of inlet node depth in ft (m) +PUMP3 pump outflow versus head difference between outlet and inlet nodes in ft (m) that has decreasing flow with increasing head +PUMP4 pump outflow versus continuous inlet node depth in ft (m) +PUMP5 pump outflow versus head difference between outlet and inlet nodes in ft (m) that has decreasing flow with increasing head +RATING flow versus head in ft (m) for an Outlet link or a Custom inlet +CONTROL control setting for a pump or flow regulator versus a controller variable (such as a node water level) in a modulated control; flow adjustment setting versus head for an LID unit’s underdrain +WEIR discharge coefficient for flow in CFS (CMS) versus head in ft (m) + +Remarks: +See @ref engine_manual_ch1_conceptual_model for illustrations of the different types of pump curves. + +Examples: +; Storage curve (x = depth, y = surface area) +AC1 STORAGE +AC1 0 1000 2 2000 4 3500 6 4200 8 5000 + +; Type 1 pump curve (x = inlet wet well volume, y = flow) +PC1 PUMP1 +PC1 100 5 300 10 500 20 + +; Type 5 pump curve (x = pump head, y = pump flow) +PC2 PUMP5 +PC2 0 4 +PC2 4 2 +PC2 6 0 + + +  +### Section: [TIMESERIES] {#engine_manual_sect_TIMESERIES} + +Purpose: +Describes how a quantity varies over time. + +Formats: +Name ( Date ) Hour Value ... +Name Time Value ... +Name FILE Fname + +Parameters: +Name name assigned to the time series. +Date date in Month/Day/Year format (e.g., June 15, 2001 would be 6/15/2001). +Hour 24-hour military time (e.g., 8:40 pm would be 20:40) relative to the last date specified (or to midnight of the starting date of the simulation if no previous date was specified). +Time hours since the start of the simulation, expressed as a decimal number or as hours:minutes (where hours can be greater than 24). +Value a value corresponding to the specified date and time. +Fname the name of a file in which the time series data are stored + +Remarks: +There are two options for supplying the data for a time series: + directly within this input file section as described by the first two formats + through an external data file named with the third format. +When direct data entry is used, multiple date-time-value or time-value entries can appear on a line. If more than one line is needed, the table's name must be repeated as the first entry on subsequent lines. +When an external file is used, each line in the file must use the same formats listed above, except that only one date-time-value (or time-value) entry is allowed per line. Any line that begins with a semicolon is considered a comment line and is ignored. Blank lines are also permitted. Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. + +**New in OpenSWMM v6:** The external file may also be a multi-column series file — a comma- or tab-delimited file with a header row whose first column holds a full date-time, or a PCSWMM `.tsf` file (tab-delimited with an `IDs:` header and 12-hour AM/PM date-times). Select a column by appending a colon and the column's header name to the file path, e.g. `TS_EAST FILE "rain_2024.csv:EAST_GAGE"`. Without a column name the first data column is used. A single multi-column file can supply any number of time series and rain gages and is read from disk only once per model open. The format (CSV/TSV/TSF) is detected automatically from the file's contents. + +There are two options for describing the occurrence time of time series data: + as calendar date plus time of day (which requires that at least one date, at the start of the series, be entered) + as elapsed hours since the start of the simulation. +For the first method, dates need only be entered at points in time when a new day occurs. +For rainfall time series, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage which utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values. + +Examples: +; Hourly rainfall time series with dates specified using +; one data point per line to emphasize when dates change +TS1 6-15-2001 7:00 0.1 +TS1 8:00 0.2 +TS1 9:00 0.05 +TS1 10:00 0 +TS1 6-21-2001 4:00 0.2 +TS2 5:00 0 +TS2 14:00 0.1 +TS2 15:00 0 + +;Inflow hydrograph - time relative to start of simulation +HY1 0 0 1.25 100 2:30 150 3.0 120 4.5 0 +HY1 32:10 0 34.0 57 35.33 85 48.67 24 50 0 + + + + +  +### Section: [PATTERNS] {#engine_manual_sect_PATTERNS} + +Purpose: +Specifies time patterns of dry weather flow or quality in the form of adjustment factors applied as multipliers to baseline values. + +Format: +Name MONTHLY Factor1 Factor2 ... Factor12 +Name DAILY Factor1 Factor2 ... Factor7 +Name HOURLY Factor1 Factor2 ... Factor24 +Name WEEKEND Factor1 Factor2 ... Factor24 + +Parameters: +Name name used to identify the pattern. +Factor1, +Factor2, +etc. multiplier values. + +Remarks: +The MONTHLY format is used to set monthly pattern factors for dry weather flow constituents. +The DAILY format is used to set dry weather pattern factors for each day of the week, where Sunday is day 1. +The HOURLY format is used to set dry weather factors for each hour of the day starting from midnight. If these factors are different for weekend days than for weekday days then the WEEKEND format can be used to specify hourly adjustment factors just for weekends. +More than one line can be used to enter a pattern’s factors by repeating the pattern’s name (but not the pattern type) at the beginning of each additional line. +The pattern factors are applied as multipliers to any baseline dry weather flows or quality concentrations supplied in the [DWF] section. + +Examples: +; Day of week adjustment factors +D1 DAILY 0.5 1.0 1.0 1.0 1.0 1.0 0.5 +D2 DAILY 0.8 0.9 1.0 1.1 1.0 0.9 0.8 +; Hourly adjustment factors +H1 HOURLY 0.5 0.6 0.7 0.8 0.8 0.9 +H1 1.1 1.2 1.3 1.5 1.1 1.0 +H1 0.9 0.8 0.7 0.6 0.5 0.5 +H1 0.5 0.5 0.5 0.5 0.5 0.5 + + +### Section: [VIRTUAL_JUNCTIONS] {#engine_manual_sect_VIRTUAL_JUNCTIONS} + +Purpose: +Declares junction nodes that exist only to join two conduits, with no physical structure of their own. + +Format: + Name + +Parameters: +Name name of a junction declared in the [JUNCTIONS] section. + +Remarks: +One token per line. Invert elevation and maximum depth are not read here — they are derived from the two attached conduits after parsing, so a virtual junction never imposes a node geometry of its own on the solution. Supplying any extra token is a parse error (ERROR 609). + +This section has no counterpart in SWMM 5. + + +### Section: [INLET_JUNCTIONS] {#engine_manual_sect_INLET_JUNCTIONS} + +Purpose: +Declares a virtual junction that also carries a street inlet, combining the [VIRTUAL_JUNCTIONS] and [INLET_USAGE] roles in one row. + +Format: + Name Elev MaxDepth Inlet CaptureNode (Number %Clogged Qmax aLocal wLocal Placement) + +Parameters: +Name name of the node. +Elev invert elevation (ft or m). +MaxDepth maximum depth, i.e. the street's flood depth (ft or m). +Inlet name of an inlet design in the [INLETS] section. +CaptureNode name of the node that receives the captured flow. +Number number of inlets placed (default 1). +%Clogged degree of clogging as a percent (default 0). +Qmax maximum flow the inlet can capture (flow units; 0 or blank = no limit). +aLocal height of a local gutter depression (in or mm). +wLocal width of a local gutter depression (ft or m). +Placement ON_GRADE, ON_SAG or AUTOMATIC (default AUTOMATIC). + +Remarks: +The node is marked both virtual and inlet-bearing. More than eleven tokens is a parse error (ERROR 623). + +This section has no counterpart in SWMM 5. + + +### Section: [INITIAL_QUALITY] {#engine_manual_sect_INITIAL_QUALITY} + +Purpose: +Sets the initial concentration of a constituent in a node or a link at the start of the simulation. + +Format: + NODE Name Constituent Value + LINK Name Constituent Value + FILE Fname + +Parameters: +Name name of the node or link. +Constituent name of a pollutant, or a constituent of a process component. +Value initial concentration (concentration units). +Fname name of a CSV file holding the same four fields per line. + +Remarks: +The scope keyword must be NODE or LINK; anything else is a parse error. A row with fewer than four tokens is a parse error. + +The FILE form names a sidecar whose lines are `scope,element,constituent,value`, with an optional header row. It is resolved relative to the input file's directory and read when the model is opened, so it may be written by a pre-processor that does not have to rewrite the `.inp`. + + +### Section: [RDII_DECAY] {#engine_manual_sect_RDII_DECAY} + +Purpose: +Applies a seasonal decay to an RDII unit hydrograph group, so that the same hydrograph produces less inflow as antecedent conditions dry out. + +Format: + UHgroup Response Kdep K0 KT Tref ThetaRec Tfreeze + +Parameters: +UHgroup name of a unit hydrograph group in the [HYDROGRAPHS] section. +Response SHORT, MEDIUM or LONG — which of the group's three response terms this row applies to. +Kdep depletion rate coefficient (1/day). +K0 base recovery rate coefficient (1/day). +KT temperature coefficient of the recovery rate (1/day per degree). +Tref reference temperature for KT (deg F or deg C). +ThetaRec recovery threshold as a fraction. +Tfreeze temperature below which recovery stops (deg F or deg C). + +Remarks: +A row with fewer than eight tokens is ignored, as is a row whose Response keyword is not one of the three accepted values or whose Kdep, K0 or KT is negative. + +This section has no counterpart in SWMM 5. + + +### Section: [EVENTS] {#engine_manual_sect_EVENTS} + +Purpose: +Restricts reporting to one or more time windows, so that a long continuous run writes output only for the periods of interest. + +Format: + StartDate StartTime EndDate EndTime + +Parameters: +StartDate date on which the event begins (MM/DD/YYYY). +StartTime time of day at which it begins (HH:MM:SS). +EndDate date on which it ends. +EndTime time of day at which it ends. + +Remarks: +A row with fewer than four tokens is ignored, as is any row whose start is not earlier than its end. Events do not change the simulation period in the [OPTIONS] section; the model still runs continuously. + + +### Section: [TAGS] {#engine_manual_sect_TAGS} + +Purpose: +Attaches a free-text category label to an object, for grouping and filtering. + +Format: + ObjectType Name Tag + +Parameters: +ObjectType NODE, LINK or SUBCATCH. +Name name of the object. +Tag the label. Use double quotes if it contains spaces. + +Remarks: +A row with fewer than three tokens is ignored, as is a row naming an object that does not exist. Tags are stored against the object's position rather than its name, so renaming the object keeps its tag. + + +### Section: [PROFILE] {#engine_manual_sect_PROFILE} + +Purpose: +Names a sequence of links that form a profile path, for a graphical client to plot. + +Format: + Name Link1 Link2 ... + +Remarks: +The engine parses and discards this section; it exists so that a profile defined in a client survives a round trip through the engine's writer. It has no effect on the simulation. + + +### Section: [USER_FLAGS] {#engine_manual_sect_USER_FLAGS} + +Purpose: +Declares a user-defined attribute that can then be given per-object values in the [USER_FLAG_VALUES] section. + +Format: + Name Type (Description) + +Parameters: +Name name of the flag. Stored upper-case, so flag names are case-insensitive. +Type BOOLEAN, INTEGER, REAL or STRING. +Description optional free text; quote it if it contains spaces. + +Remarks: +A row with fewer than two tokens is ignored. An unrecognised Type is treated as STRING and raises WARNING 102. + +This section has no counterpart in SWMM 5. + + +### Section: [USER_FLAG_VALUES] {#engine_manual_sect_USER_FLAG_VALUES} + +Purpose: +Assigns a value for a user-defined flag to one object. + +Format: + ObjectType Name FlagName Value + +Parameters: +ObjectType NODE, LINK or SUBCATCH. +Name name of the object; case is preserved. +FlagName name of a flag declared in [USER_FLAGS]; matched case-insensitively. +Value the value, parsed according to the flag's declared type. + +Remarks: +A row with fewer than four tokens is ignored. Assigning a value for a flag that was never declared is accepted, treated as STRING, and raises WARNING 103 — so ordering the two sections the wrong way round degrades the type rather than failing the run. + +This section has no counterpart in SWMM 5. + + +### Section: [PLUGINS] {#engine_manual_sect_PLUGINS} + +Purpose: +Loads a plugin shared library at start-up. + +Format: + Path (Arg1 Arg2 ...) + +Parameters: +Path path to the plugin library. Relative paths resolve against the plugin search path. +Arg optional initialisation arguments passed to the plugin verbatim. + +Remarks: +See @ref engine_manual_ch5_api for what a plugin can do and where libraries are discovered. + +This section has no counterpart in SWMM 5. + + +### Section: [PROCESS_COMPONENTS] {#engine_manual_sect_PROCESS_COMPONENTS} + +Purpose: +Attaches a process component — an advection-reaction-dispersion solver, a reaction system, water age or heat transport — to the simulation. + +Format: + Id key="value" key="value" ... + +Parameters: +Id identifier of the component. +key="value" configuration arguments. The reserved key CONFIG names a configuration file for the component; every other key is passed through to it. + +Remarks: +An argument that is not a `key="value"` pair is a parse error naming the component and the offending token. + +This section has no counterpart in SWMM 5. + +## 2.3 Map Data Section + +SWMM’s graphical user interface (GUI) can display a schematic map of the drainage area being analyzed. This map displays subcatchments as polygons, nodes as circles, links as polylines, and rain gages as bitmap symbols. In addition it can display text labels and a backdrop image, such as a street map. The GUI has tools for drawing, editing, moving, and displaying these map elements. + + The map’s coordinate data are stored in the format described below. Normally these data are simply appended to the SWMM input file by the GUI so users do not have to concern themselves with it. However it is sometimes more convenient to import map data from some other source, such as a CAD or GIS file, rather than drawing a map from scratch using the GUI. In this case the data can be added to the SWMM project file using any text editor or spreadsheet program. SWMM does not provide any automated facility for converting coordinate data from other file formats into the SWMM map data format. + +SWMM's map data are organized into the following seven sections: +[MAP] X,Y coordinates of the map’s bounding rectangle +[POLYGONS] X,Y coordinates for each vertex of subcatchment polygons +[COORDINATES] X,Y coordinates for nodes +[VERTICES] X,Y coordinates for each interior vertex of polyline links +[LABELS] X,Y coordinates and text of labels +[SYMBOLS] X,Y coordinates for rain gages +[BACKDROP] X,Y coordinates of the bounding rectangle and file name of the backdrop image. +Figure D-2 displays a sample map and Figure D-3 the data that describes it. Note that only one link, 3, has interior vertices which give it a curved shape. Also observe that this map’s coordinate system has no units, so that the positions of its objects may not necessarily coincide to their real-world locations. + + +*Figure D-2 Example study area map* + +*Figure D-3 Data for example study area map* +A detailed description of each map data section will now be given. Remember that map data are only used as a visualization aid for SWMM’s GUI and they play no role in any of the runoff or routing computations. Map data are not needed for running the command line version of SWMM. +--- + +### Section: [MAP] {#engine_manual_sect_MAP} + +Purpose: + Provides dimensions and distance units for the map. + +Formats: +DIMENSIONS X1 Y1 X2 Y2 +UNITS FEET / METERS / DEGREES / NONE + +Parameters: +X1 lower-left X coordinate of full map extent +Y1 lower-left Y coordinate of full map extent +X2 upper-right X coordinate of full map extent +Y2 upper-right Y coordinate of full map extent +--- + +### Section: [COORDINATES] {#engine_manual_sect_COORDINATES} + +Purpose: + Assigns X,Y coordinates to drainage system nodes. + +Format: + Node Xcoord Ycoord + +Parameters: +Node name of node. +Xcoord horizontal coordinate relative to origin in lower left of map. +Ycoord vertical coordinate relative to origin in lower left of map. +--- + + + + + +### Section: [VERTICES] {#engine_manual_sect_VERTICES} + +Purpose: + Assigns X,Y coordinates to interior vertex points of curved drainage system links. + +Format: + Link Xcoord Ycoord + +Parameters: +Link name of link. +Xcoord horizontal coordinate of vertex relative to origin in lower left of map. +Ycoord vertical coordinate of vertex relative to origin in lower left of map. + +Remarks: +Include a separate line for each interior vertex of the link, ordered from the inlet node to the outlet node. + +Straight-line links have no interior vertices and therefore are not listed in this section. +--- + +### Section: [POLYGONS] {#engine_manual_sect_POLYGONS} + +Purpose: +Assigns X,Y coordinates to vertex points of polygons that define a subcatchment boundary. + +Format: + Subcat Xcoord Ycoord + +Parameters: +Subcat name of subcatchment. +Xcoord horizontal coordinate of vertex relative to origin in lower left of map. +Ycoord vertical coordinate of vertex relative to origin in lower left of map. + +Remarks: +Include a separate line for each vertex of the subcatchment polygon, ordered in a consistent clockwise or counter-clockwise sequence. +--- + + + +### Section: [SYMBOLS] {#engine_manual_sect_SYMBOLS} + +Purpose: + Assigns X,Y coordinates to rain gage symbols. + +Format: + Gage Xcoord Ycoord + +Remarks: +Gage name of rain gage. +Xcoord horizontal coordinate relative to origin in lower left of map. +Ycoord vertical coordinate relative to origin in lower left of map. +--- + +### Section: [LABELS] {#engine_manual_sect_LABELS} + +Purpose: + Assigns X,Y coordinates to user-defined map labels. + +Format: + Xcoord Ycoord Label (Anchor Font Size Bold Italic) + +Parameters: +Xcoord horizontal coordinate relative to origin in lower left of map. +Ycoord vertical coordinate relative to origin in lower left of map. +Label text of label surrounded by double quotes. +Anchor name of node or subcatchment that anchors the label on zoom-ins (use an empty pair of double quotes if there is no anchor). +Font name of label’s font (surround by double quotes if the font name includes spaces). +Size font size in points. +Bold YES for bold font, NO otherwise. +Italic YES for italic font, NO otherwise. + +Remarks: +Use of the anchor node feature will prevent the label from moving outside the viewing area when the map is zoomed in on. + +If no font information is provided then a default font is used to draw the label. +--- +### Section: [BACKDROP] {#engine_manual_sect_BACKDROP} + +Purpose: + Specifies file name and coordinates of map’s backdrop image. + +Formats: +FILE Fname +DIMENSIONS X1 Y1 X2 Y2 + +Parameters: +Fname name of file containing backdrop image +X1 lower-left X coordinate of backdrop image +Y1 lower-left Y coordinate of backdrop image +X2 upper-right X coordinate of backdrop image +Y2 upper-right Y coordinate of backdrop image + + +## 2.4 Two-Dimensional Surface and Groundwater Sections + +The twenty-one `[2D_*]` sections configure the two-dimensional overland +surface of @ref hydraulics_ref_ch9_two_dimensional — its mesh, coupling to the +network, boundary conditions, per-cell infiltration and evaporation, the +aquifer beneath it, and surface quality — and the six `[GW_*]` sections carry +the groundwater-transport grammar, which this release parses, validates and +writes back but does not solve. Every row grammar below follows the parser; +where the design notes in `plans/2D_INPUT_FORMAT_SPEC.md` and the parser +disagree, the parser wins and the entry says so. + +### Section: [2D_OPTIONS] {#engine_manual_sect_2D_OPTIONS} + +Purpose: +Sets the options of the two-dimensional overland-flow module: the momentum closure and marcher controls, the wetting and drying thresholds, the coupling to the one-dimensional network, how rainfall, evaporation and infiltration reach the mesh, the groundwater and transport process enables, and the 2D results file. + +Format: +``` +Keyword Value +``` + +One keyword per line. Keywords are matched case-insensitively; an unknown keyword is a parse error (`Unknown 2D_OPTIONS parameter`). The value of `REPORT_2D_VARIABLES` and `REPORT_2D_SPECIES` may span several tokens; every other keyword reads its first value token only. + +Parameters: + +Solver + +| Keyword | Values | Default | Description | +|---|---|---|---| +| MOMENTUM_EQUATION | LOCAL_INERTIAL (LI) / FULL_SWE (SWE, FULL) / DIFFUSIVE_WAVE (DW, DIFFUSIVE) | LOCAL_INERTIAL | Face law of the explicit marcher. LOCAL_INERTIAL is the de Almeida and Bates update; FULL_SWE is the conservative shallow-water form with the convective term (hydrostatic reconstruction, rotated HLLC flux, shock capturing); DIFFUSIVE_WAVE is the Manning quasi-steady flux with no inertia. | +| INTEGRATOR | EXPLICIT | EXPLICIT | The explicit marcher is the only 2D integrator. Any other value is a retired selection (see the Retired keys table). | +| RECONSTRUCTION_ORDER | 1 / 2 | 1 | FULL_SWE only. 1 is piecewise constant (first-order Godunov, forward Euler); 2 is MUSCL on (eta, u, v) with the Barth-Jespersen-limited Green-Gauss gradient and SSP-RK2, run in global-time-step mode (LTS_TIERS is reduced to 1 with a warning). | +| THETA | (0, 1] | 0.8 | Face-update weighting of the local-inertial law: 1 is the pure Bates 2010 update, below 1 blends the reconstructed neighbour discharge to damp thin-film checkerboarding. | +| FROUDE_MAX | > 0 | 1.5 | Clamp on the face Froude number of the local-inertial law. | +| CELL_CLOSURE | FLAT / VFR | FLAT | Volume-to-free-surface closure of a cell. FLAT is the flat-cell relation; VFR is the planar-bed volume/free-surface relationship, which restores the lake-at-rest property at shorelines at the cost of more substeps. | +| FACE_RECONSTRUCTION | MEAN / VFR_FACE | MEAN | Conveyance depth at a shared edge. MEAN uses the upwind cell-mean depth; VFR_FACE reconstructs the wetted depth over the edge's own endpoint elevations, so a crest resolved as a line of high vertices blocks flow until the water reaches it. | +| VFR_MIN_WET_FRAC | (0, 0.5] | 0.01 | Wetted-area-fraction floor of the regularised VFR closure. Used only under CELL_CLOSURE VFR. | +| FLUX_DH_EPS | number, metres | 0.004 | Head-difference floor below which the diffusive flux is linearised. 0 restores the bare square root. Always metres. | +| LIMITER_EPSILON | number | 1.0e-6 | Regularisation of the slope limiter applied to the reported gradient fields. | +| ADVECTION | YES / ON / TRUE / NO / OFF / FALSE | NO | Deprecated spelling of MOMENTUM_EQUATION FULL_SWE (2026-09-06). Still honoured so an old deck keeps its physics; a file load warns and names the replacement. | +| BACKEND | AUTO / CPU / OMP / CUDA / HIP / SYCL | AUTO | Which marcher implementation runs the mesh. CPU is the built-in host marcher; OMP, CUDA, HIP and SYCL name a Kokkos plugin and bypass the mesh-size floors (an absent plugin or device falls back to CPU with a notice). AUTO picks a device plugin above the device floor, the OpenMP plugin above its own floor, else CPU. The OPENSWMM_2D_BACKEND environment variable overrides the key. | + +Time control + +| Keyword | Values | Default | Description | +|---|---|---|---| +| MAX_TIMESTEP | number, seconds | 10.0 | Cap on the marcher step. Also caps the spread of the local-time-stepping tiers and the co-advance batch span. | +| CFL_NUMBER | (0, 1] | 0.7 | Courant fraction of the marcher step. 1.0 is the linear stability limit; the default keeps a 30 percent margin. | +| LTS_TIERS | 1 .. 8 | 4 | Number of local-time-stepping tiers. 1 forces one global step for every cell. | + +Wetting and drying + +| Keyword | Values | Default | Description | +|---|---|---|---| +| DRY_DEPTH | number, metres | 0.001 | Depth below which a cell is dry. Also drives the coupling and outfall wet ramps and the evaporation taper. Always metres. | +| H_MOVE | >= 0, metres | 0.003 | Flux-activation depth: a cell below it is source-only (rain accumulates, no face flux). The on/off hysteresis band is the smaller of 1 mm and half of H_MOVE. Always metres. | +| FRONT_REBUILD | AUTO / YES / ON / NO / OFF | AUTO | Rebuild the flux-active set as soon as a wetting front reaches the edge of the active halo instead of waiting for the fixed rebuild cadence. AUTO is YES for FULL_SWE and DIFFUSIVE_WAVE and NO for LOCAL_INERTIAL. | + +Coupling to the 1D network + +| Keyword | Values | Default | Description | +|---|---|---|---| +| COUPLING_CD | number | 0.65 | Discharge coefficient of every coupling row that does not author its own CD. | +| COUPLING_AREA | AUTO / DEFAULT | DEFAULT | AUTO derives the exchange area of each coupling row that did not author an AREA from the largest connected conduit (1.25 times its full-flow area, clamped to 0.05 .. 2.0 square metres). DEFAULT keeps the authored or default area. | +| COUPLING_SYNC | >= 0, seconds | 0 | 0 co-advances the 2D domain every routing step. A positive value batches the 2D advance over roughly that span (clamped at run time to the routing step .. 60 s); the held-exchange error grows with the span. | +| COUPLING_IN_FLOODING | YES / TRUE / NO / FALSE | NO | YES books the 1D-to-2D spill into the 1D report's Flooding Loss row instead of its own 2D Coupling Outflow row. Changes the report only; routed volumes are identical. | + +Rainfall, evaporation and infiltration + +| Keyword | Values | Default | Description | +|---|---|---|---| +| RAINFALL_MODE | NATURAL_NEIGHBOUR (NATURAL_NEIGHBOR) / NEAREST_NEIGHBOUR (NEAREST_NEIGHBOR) / SYSTEM / NONE | NATURAL_NEIGHBOUR | How rain gage rainfall is mapped onto the cells: natural-neighbour interpolation of the located gages (inverse-distance outside their hull), the closest located gage (first-listed wins a tie), the uniform mean of all gages, or no rain on the mesh. Use NONE when subcatchments already capture the storm. The OPENSWMM_2D_RAINFALL_MODE environment variable overrides the key. | +| EVAPORATION | NO / OFF / YES / ON / FORCING / CLIMATE | YES | NO zeroes the mesh evaporation sink. YES applies only per-cell forcing supplied through the API. CLIMATE evaporates every unforced cell at the project [EVAPORATION] rate; forcing still overrides it. | +| INFILTRATION | YES / ON / NO / OFF / AUTO | AUTO | Process enable for mesh infiltration. AUTO runs it when any [2D_INFILTRATION_DEFAULTS] or [2D_INFILTRATION] row resolves; NO keeps the rows but deactivates them for the run; YES warns when no row resolves. | +| INFIL_STEP | HH:MM:SS, HH:MM or seconds | 0 (unset) | Infiltration update cadence. Unset falls back to [2D_INFILTRATION_OPTIONS] INFIL_STEP, then to the project WET_STEP. When both are present this key wins. | +| INFIL_DEFAULT_METHOD | NONE / HORTON / MOD_HORTON / GREEN_AMPT / MOD_GREEN_AMPT / CURVE_NUMBER / CONSTANT (the legacy spellings MODIFIED_HORTON, MODIFIED_GREEN_AMPT and CURVE_NUM are accepted) | unset | Method of the mesh-wide `*` row of [2D_INFILTRATION_DEFAULTS]. Unset lets that row govern; NONE drops the `*` row for the run; a method must match the `*` row (its parameters live there) - a mismatch is an initialise error, a missing row a warning. | +| INFIL_DESTINATION | LOST / SUBCATCH_AQUIFER / AQUIFER_2D | LOST | Destination applied to every infiltration row that did not spell its own DEST column. SUBCATCH_AQUIFER recharges the legacy aquifer of the subcatchment containing the cell; AQUIFER_2D recharges the integrated two-zone aquifer and requires a resolved [2D_AQUIFER]. | + +Groundwater + +| Keyword | Values | Default | Description | +|---|---|---|---| +| GROUNDWATER | YES / ON / NO / OFF / AUTO | AUTO | Process enable for the integrated 2D subsurface. AUTO runs the kernel when any [2D_AQUIFER_OPTIONS], [2D_AQUIFER] or [2D_AQUIFER_NODE] row was authored; NO keeps the rows and runs without the subsurface; YES with no rows warns. | +| GW_ET | NONE / CAPILLARY_RISE / BOUNDARY_ET / BOTH | NONE | Alias of the [2D_AQUIFER_OPTIONS] key of the same name. A value spelled here is folded into [2D_AQUIFER_OPTIONS] when the model opens and is never stored in two places. | + +Transport + +| Keyword | Values | Default | Description | +|---|---|---|---| +| TRANSPORT_POLLUTANTS | YES / ON / NO / OFF | YES | Carry the [POLLUTANTS] species on the 2D surface. NO drops their rows from the surface transport state; the 1D side is unaffected. | +| TRANSPORT_MSX | YES / ON / NO / OFF | YES | Carry the reactions component's species on the 2D surface. | +| TRANSPORT_AGE | YES / ON / NO / OFF | YES | Carry water age on the 2D surface. | +| TRANSPORT_TEMPERATURE | YES / ON / NO / OFF | YES | Carry temperature on the 2D surface. | +| DISPERSION | >= 0, square metres per second | 0 | Isotropic species dispersion coefficient on the surface. 0 never enters the dispersive face term; a negative value is refused. Always SI. | + +Output + +| Keyword | Values | Default | Description | +|---|---|---|---| +| REPORT_2D | YES / 1 / NO / 0 | YES | NO skips the recomputation of the reported gradient fields at each report step. It does not suppress the 2D results file. | +| OUTPUT_FILE | path (one token; quote a path containing spaces) | none | 2D results file (HDF5, CF/UGRID), resolved relative to the input file's directory. When absent no 2D results file is written. | +| OUTPUT_PRECISION | FLOAT32 (F32, SINGLE) / FLOAT64 (F64, DOUBLE) | FLOAT32 | Storage type of the time-varying datasets and envelopes of the results file. Mesh geometry always stays float64. | +| OUTPUT_COMPRESSION | 0 .. 9 | 4 | zlib level of the chunked datasets; the byte-shuffle filter precedes it whenever the level is above 0. 0 is none. | +| REPORT_2D_VARIABLES | DEFAULT / MINIMAL / ALL / NONE, or any list of DEPTH VELOCITY EDGE_FLUX NODE_HEAD SPECIES RAINFALL INFILTRATION COUPLING GRADIENTS CONTINUITY ENVELOPES BUILDUP GROUNDWATER GW_DETAILED | DEFAULT | Dataset groups written to the results file (space- or comma-separated; presets and tokens may be mixed). DEPTH is always included. DEFAULT is DEPTH VELOCITY EDGE_FLUX NODE_HEAD SPECIES RAINFALL INFILTRATION ENVELOPES BUILDUP GROUNDWATER; MINIMAL is DEPTH NODE_HEAD ENVELOPES. Unselected groups are not created in the file. | +| REPORT_2D_SPECIES | ALL, or a list of species names | ALL | Species rows written to the results file. ALL writes every row the transport layout carries. | +| REPORT_2D_STEP | HH:MM:SS, HH:MM or seconds | 0 | 2D-only report interval. 0 follows [OPTIONS] REPORT_STEP; otherwise it must be a positive multiple of REPORT_STEP (checked at start). | + +Retired keys + +| Keyword | Status | Behaviour today | +|---|---|---| +| MIN_TIMESTEP | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| REL_TOLERANCE | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| ABS_TOLERANCE | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| MAX_CVODE_STEPS | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| MAX_KRYLOV_DIM | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| LINEAR_SOLVER | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| PRECONDITIONER | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| JACOBIAN | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| ATOL_AREA_REF | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| COUPLING_INTERVAL | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. Superseded by COUPLING_SYNC. | +| COUPLING_WINDOW | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. Superseded by COUPLING_SYNC. | +| ACTIVE_SET | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. The active set is always on. | +| ACTIVE_SET_HALO | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. | +| MOMENTUM | \status{Retired} | Ignored on file load with WARNING 104; a hard error on the programmatic option-set path. Superseded by MOMENTUM_EQUATION. | +| INTEGRATOR with any value other than EXPLICIT (CVODE, ARKODE) | \status{Retired} | The value is ignored on file load with WARNING 104 and the marcher runs; a hard error on the programmatic option-set path. | +| ADVECTION YES | \status{Retired} | Deprecated spelling of MOMENTUM_EQUATION FULL_SWE. Accepted and honoured; a file load warns and names the replacement. | + +Remarks: +The keys marked "always metres" or "always SI" (DRY_DEPTH, H_MOVE, FLUX_DH_EPS, DISPERSION) do not follow FLOW_UNITS or the mesh's `;; UNITS:` header; everything the mesh sections carry does (see [2D_VERTICES]). + +WARNING 104 reads: "[2D_OPTIONS] %s was retired with the CVODE/ARKODE 2D solvers and was ignored; the explicit local-inertial marcher is the only 2D integrator." + +The section may also appear in the external mesh file named by [2D_MESH_FILE]; values read there are applied after the inline ones and override them. + +`OUTPUT_FILE` reads a single token, so a path containing spaces must be double-quoted; [2D_MESH_FILE] is the one section that rejoins an unquoted path. + +`INFIL_STEP` here is the canonical home of the [2D_INFILTRATION_OPTIONS] value and `GW_ET` of the [2D_AQUIFER_OPTIONS] value; the writer emits each in its canonical section only. + +The theory behind the solver, wetting and drying, coupling and reporting keys is in @ref hydraulics_ref_ch9_two_dimensional (sections 9.4, 9.5, 9.7, 9.8, 9.9 and 9.11); the groundwater enables refer to hydrology Chapter 9 (mesh groundwater). + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_VERTICES] {#engine_manual_sect_2D_VERTICES} + +Purpose: +Lists the vertices of the two-dimensional mesh: their planimetric coordinates and bed elevation. + +Format: +``` +X Y Z (Tag) +``` + +Parameters: +X horizontal coordinate of the vertex, in the mesh's length units (ft or m). +Y vertical map coordinate of the vertex, in the mesh's length units (ft or m). +Z bed elevation of the vertex, in the mesh's length units (ft or m). +Tag optional name of the vertex, usable instead of its index in [2D_VERTEX_NODE_MAP]. + +Remarks: +Vertices are numbered 0, 1, 2, ... in file order; that 0-based index is what [2D_TRIANGLES], [2D_QUADS], [2D_EDGE_CONVEYANCE] and [2D_VERTEX_NODE_MAP] refer to. A row with fewer than three numeric tokens is a parse error. + +The mesh's length unit follows [OPTIONS] FLOW_UNITS (feet for CFS, GPM and MGD; metres otherwise) unless the file carries a comment line `;; UNITS: SI (m)` (also accepted: `m`, `metre`, `metres`, `meter`, `meters`, case-insensitive), which declares the coordinates, elevations, initial depths, coupling areas and constant stages already metric and suppresses the feet-to-metres scaling at initialise. The header is looked for over the whole file, last match wins; the engine's own writer emits it under this section. + +A mesh needs at least three vertices; the mesh is validated when the model initialises (see @ref hydraulics_ref_ch9_two_dimensional, section 9.3). + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_TRIANGLES] {#engine_manual_sect_2D_TRIANGLES} + +Purpose: +Lists the triangular cells of the mesh, each with its Manning roughness and, optionally, an initial water depth and a classification tag. + +Format: +``` +V1 V2 V3 ManningsN (InitDepth) (Tag) +``` + +Parameters: +V1, V2, V3 0-based indices of the three vertices, from [2D_VERTICES]. +ManningsN Manning's roughness coefficient (n) of the cell. +InitDepth initial water depth in the mesh's length units (ft or m); must be >= 0 (default 0 = dry). +Tag optional classification name of the cell, matched by [2D_INFILTRATION_DEFAULTS] and by the TAG scope of the aquifer, quality and groundwater sections, and usable instead of the index in [2D_TRIANGLE_NODE_MAP]. + +Remarks: +Cells are numbered 0, 1, 2, ... in file order, triangles first and then every [2D_QUADS] row; that unified 0-based index is the TRI column of [2D_INITIAL_VELOCITY], [2D_BOUNDARY_CONDITIONS] and [2D_BOUNDARY_QUALITY], and the CELL column (1-based) of the other cell-addressed sections. A triangle row that follows a quad row is a parse error. + +The fifth column is ambiguous by design: when it parses as a number it is InitDepth and the sixth column is Tag; otherwise it is Tag. The engine's writer emits InitDepth on every row whenever any cell carries a depth or a tag, so files it wrote are unambiguous. + +Edge k of a cell joins vertices V[(k+1) mod 3] and V[(k+2) mod 3]: edge 0 is opposite V1, edge 1 opposite V2 and edge 2 opposite V3. This is the EDGE numbering of [2D_BOUNDARY_CONDITIONS] and [2D_BOUNDARY_QUALITY]. + +Vertex indices must be in range and distinct, the area positive and ManningsN positive; these are checked when the model initialises, not at parse. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_QUADS] {#engine_manual_sect_2D_QUADS} + +Purpose: +Lists the convex quadrilateral cells of the mesh, appended after every triangle. + +Format: +``` +V1 V2 V3 V4 ManningsN (InitDepth) (Tag) +``` + +Parameters: +V1, V2, V3, V4 0-based indices of the four vertices in cyclic order (either orientation). +ManningsN Manning's roughness coefficient (n) of the cell. +InitDepth initial water depth in the mesh's length units (ft or m); must be >= 0 (default 0 = dry). +Tag optional classification name of the cell (see [2D_TRIANGLES]). + +Remarks: +The j-th quad row is cell number (number of triangles + j) in the unified cell index used by every cell-addressed section. Column six is InitDepth when numeric, otherwise Tag; column seven is Tag when InitDepth is present, exactly as for [2D_TRIANGLES]. + +Edge k of a quad joins V[(k+1) mod 4] and V[(k+2) mod 4]: edge 0 = (V2, V3), edge 1 = (V3, V4), edge 2 = (V4, V1), edge 3 = (V1, V2). Non-convex or self-intersecting quads fail validation at initialise. + +The section is written only when the mesh holds quads; an all-triangle file is unchanged. See @ref hydraulics_ref_ch9_two_dimensional, section 9.11b. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_MESH_FILE] {#engine_manual_sect_2D_MESH_FILE} + +Purpose: +Names an external file that holds the mesh and the other 2D sections instead of, or in addition to, the main input file. + +Format: +``` +FILE Path +``` + +Parameters: +Path absolute path, or a path relative to the directory of the input file. Surrounding double quotes are stripped; an unquoted path containing spaces is rejoined from its tokens. + +Remarks: +Only the first FILE line of the section is read. The conventional extension is `.2dm`, but the file is plain input-file text: any of [2D_OPTIONS], [2D_VERTICES], [2D_TRIANGLES], [2D_QUADS], [2D_INITIAL_VELOCITY], [2D_VERTEX_NODE_MAP], [2D_TRIANGLE_NODE_MAP], [2D_BOUNDARY_CONDITIONS], [2D_EDGE_CONVEYANCE], [2D_INITIAL_QUALITY], [2D_BOUNDARY_QUALITY], [2D_INFILTRATION_OPTIONS], [2D_INFILTRATION_DEFAULTS] and [2D_INFILTRATION], with the same grammar as here. It may not contain [2D_MESH_FILE] itself, and it does not carry the aquifer, coverage, loading, curb-length or [GW_*] sections, which stay in the main file. + +The external file is parsed after the main file. Per section, the external file wins: a section present in both replaces the inline rows rather than adding to them, and its [2D_OPTIONS] values override inline ones. Its own `;; UNITS:` header is honoured (see [2D_VERTICES]). A missing or unreadable file is fatal when the model is opened for a run. + +When a mesh file is set, the writer emits only [2D_OPTIONS] and this section into the input file and rewrites the current mesh to the external file. The file slot is described in @ref engine_manual_ch3_files. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_VERTEX_NODE_MAP] {#engine_manual_sect_2D_VERTEX_NODE_MAP} + +Purpose: +Couples a mesh vertex to a node of the one-dimensional network, so that water is exchanged between the cells around the vertex and the node. + +Format: +``` +Vertex Node (Cd) (Area) +``` + +Parameters: +Vertex 0-based index of a vertex, or its Tag from [2D_VERTICES]. +Node name of a junction, storage unit or outfall node. +Cd discharge coefficient of the exchange (default: [2D_OPTIONS] COUPLING_CD, 0.65). +Area exchange area, in the mesh's length units squared (sq ft or sq m; default 1.0). + +Remarks: +The first token is tried as a numeric index first; a number that is not a valid vertex index is looked up as a tag, so purely numeric tags work. An unknown index or tag is a parse error, so this section must follow [2D_VERTICES] in the same file. An unknown node name is fatal when the model initialises. + +The exchange is a bidirectional orifice: positive when the surface drains into the node, negative when the node surcharges onto the surface. It opens once the higher of the two heads reaches the node's rim (invert plus maximum depth), so the node's Elevation + MaxDepth should equal the ground elevation at the inlet. The exchange is spread over the cells incident to the vertex, weighted by the water-surface slope. + +One row per vertex; a repeated vertex overwrites the earlier row. A Cd or Area token that does not parse as a number is ignored, not reported. An Area that was authored explicitly is never replaced by COUPLING_AREA AUTO. + +Naming an outfall couples the outfall's discharge onto the surface and makes the surface stage its dynamic tailwater. See @ref hydraulics_ref_ch9_two_dimensional, section 9.7. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_TRIANGLE_NODE_MAP] {#engine_manual_sect_2D_TRIANGLE_NODE_MAP} + +Purpose: +Couples a mesh cell (triangle or quad) to a node of the one-dimensional network; the whole exchange lands on that cell. + +Format: +``` +Cell Node (Cd) (Area) +``` + +Parameters: +Cell 0-based unified cell index, or the cell's Tag from [2D_TRIANGLES] or [2D_QUADS]. +Node name of a junction, storage unit or outfall node. +Cd discharge coefficient of the exchange (default: [2D_OPTIONS] COUPLING_CD, 0.65). +Area exchange area, in the mesh's length units squared (sq ft or sq m; default 1.0). + +Remarks: +The first token is tried as a numeric index first and falls back to a tag lookup when the number is not a valid cell index. An unknown index or tag is a parse error, so this section must follow the cell sections in the same file. + +Unlike [2D_VERTEX_NODE_MAP], every row appends a coupling: several nodes may couple to one cell. A Cd or Area token that does not parse as a number is ignored. + +The exchange law, the rim gate and the outfall behaviour are those of [2D_VERTEX_NODE_MAP]; see @ref hydraulics_ref_ch9_two_dimensional, section 9.7. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_BOUNDARY_CONDITIONS] {#engine_manual_sect_2D_BOUNDARY_CONDITIONS} + +Purpose: +Assigns a boundary condition to an edge of a cell that lies on the mesh boundary. + +Format: +``` +Cell Edge WALL +Cell Edge NORMAL_FLOW Slope (*) (Group) +Cell Edge SPECIFIED_STAGE Head (*) (Group) +Cell Edge TS_STAGE Tseries (*) (Group) +Cell Edge SPECIFIED_FLOW Flow (*) (Group) +Cell Edge TS_FLOW Tseries (*) (Group) +Cell Edge RATING_CURVE Curve (*) (Group) +``` + +Parameters: +Cell 0-based unified cell index (the TRI column of files the engine writes). +Edge local edge of that cell: 0 .. 2 for a triangle, 0 .. 3 for a quad (see [2D_TRIANGLES] and [2D_QUADS] for the numbering). +Slope bed slope used by the Manning outflow of a NORMAL_FLOW edge (dimensionless). +Head fixed water-surface elevation outside a SPECIFIED_STAGE edge, in the mesh's length units (ft or m). +Flow fixed discharge per metre of edge for a SPECIFIED_FLOW edge, in the project's flow units per metre; outward positive, so an inflow is negative. +Tseries name of a [TIMESERIES] giving the stage (TS_STAGE, project length units) or the per-metre flow (TS_FLOW, project flow units per metre) against time. +Curve name of a [CURVES] table giving discharge per metre of edge (project flow units per metre, outward positive) against stage (project length units) for a RATING_CURVE edge. +* placeholder for the fifth column, which is reserved and ignored. +Group optional label of the edge; stored and written back, never acted on. + +Remarks: +Every boundary edge not listed is a WALL (zero flux). A row needs at least Cell, Edge and the type; the fourth token may be `*` or absent to mean "no value". The fourth token must be numeric for NORMAL_FLOW, SPECIFIED_STAGE and SPECIFIED_FLOW and is a name for the others. The sixth token is Group and is read only when a fifth token is present, so write `*` in the fifth column whenever a Group is given. Edge is checked against the widest cell (0 .. 3) at parse and against the cell's own vertex count at initialise; the Cell index is checked at initialise. + +TS_STAGE and SPECIFIED_STAGE share one internal type, as do TS_FLOW and SPECIFIED_FLOW; the TS_ spelling only signals that the parameter is a name. A NORMAL_FLOW edge with a zero slope behaves as a wall (a warning is raised; the slope is never derived from the geometry). Under FULL_SWE a NORMAL_FLOW edge is transmissive. + +Series and curve names are resolved once, at the first advance, and evaluated every routing step at the absolute date-time; a name that resolves to nothing is treated as a constant. A constant stage follows the mesh's length unit, including the `;; UNITS:` header; a series stage is in the project's display length unit whatever the header says; flows follow FLOW_UNITS (CFS, GPM, MGD, CMS, LPS, MLD). The cumulative volume through each edge, outward positive, enters the 2D mass balance. + +The section may also be placed in the external mesh file. See @ref hydraulics_ref_ch9_two_dimensional, section 9.6. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_EDGE_CONVEYANCE] {#engine_manual_sect_2D_EDGE_CONVEYANCE} + +Purpose: +Partially or fully blocks an interior edge of the mesh, to represent a leaky berm, a fence or a partly blocked wall between two cells. + +Format: +``` +FromVertex ToVertex Conveyance +``` + +Parameters: +FromVertex 0-based index of one end vertex of the edge. +ToVertex 0-based index of the other end vertex; must differ from FromVertex. +Conveyance fraction of the edge's flux that passes, in [0, 1]: 0 blocks the edge, 1 leaves it unobstructed. + +Remarks: +Exactly three tokens. The vertex pair is undirected; a repeated pair takes the last row. A conveyance outside [0, 1] is a parse error; a pair that is not an edge of the mesh is fatal when the model initialises. Edges not listed have a conveyance of 1. + +For a feature that must hold water until a true crest elevation, resolve the crest as a line of high vertices and use [2D_OPTIONS] FACE_RECONSTRUCTION VFR_FACE; edge conveyance is the complementary control for partial blockage. The section may also be placed in the external mesh file. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_INITIAL_VELOCITY] {#engine_manual_sect_2D_INITIAL_VELOCITY} + +Purpose: +Gives a non-zero initial velocity to selected cells, for problems whose initial state is not at rest. + +Format: +``` +Cell U V +``` + +Parameters: +Cell 0-based unified cell index (the TRI column of files the engine writes). +U initial velocity component along the map x-axis (m/s, always SI). +V initial velocity component along the map y-axis (m/s, always SI). + +Remarks: +Rows may cover any subset of cells; unlisted cells start at rest. The index is checked at parse against the cells already read, so the section must follow [2D_TRIANGLES] and [2D_QUADS] in the same file. At initialise the marcher projects (h u, h v) onto its face normals to seed the face discharges, which a depth-only initial condition cannot represent (the Thacker planar oscillation of the verification suite, for instance). See @ref hydraulics_ref_ch9_two_dimensional, section 9.10. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_INFILTRATION_OPTIONS] {#engine_manual_sect_2D_INFILTRATION_OPTIONS} + +Purpose: +Sets the update cadence of infiltration on the mesh. + +Format: +``` +INFIL_STEP Step +``` + +Parameters: +Step infiltration update interval as HH:MM:SS, HH:MM or seconds; must be >= 0. 0 (the default) uses the project's WET_STEP. + +Remarks: +INFIL_STEP is the only keyword accepted; any other is a parse error. [2D_OPTIONS] INFIL_STEP is the canonical spelling of the same value and wins when both are present; the writer emits the key there. The section may also be placed in the external mesh file, where it replaces the inline value. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_INFILTRATION_DEFAULTS] {#engine_manual_sect_2D_INFILTRATION_DEFAULTS} + +Purpose: +Assigns an infiltration method and its parameters to every cell that carries a given tag, or to the whole mesh. + +Format: +``` +Tag NONE +Tag HORTON f0 fmin Decay DryTime Fmax (Dest) +Tag MODIFIED_HORTON f0 fmin Decay DryTime Fmax (Dest) +Tag GREEN_AMPT S Ks IMD (Dest) +Tag MODIFIED_GREEN_AMPT S Ks IMD (Dest) +Tag CURVE_NUMBER CN - DryTime (Dest) +Tag CONSTANT Rate (Dest) +``` + +Parameters: +Tag a cell tag from [2D_TRIANGLES] or [2D_QUADS], or `*` for every cell. +f0 maximum infiltration rate on the Horton curve (in/hr or mm/hr). +fmin minimum infiltration rate on the Horton curve (in/hr or mm/hr). +Decay decay rate constant of the Horton curve (1/hr). +DryTime time for a fully saturated soil to dry completely (days). +Fmax maximum infiltration volume possible (in or mm; 0 if not applicable). +S soil capillary suction head (in or mm). +Ks soil saturated hydraulic conductivity (in/hr or mm/hr). +IMD initial soil moisture deficit (volume of voids / total volume). +CN SCS curve number. +Rate constant infiltration rate (in/hr or mm/hr). +Dest destination of the infiltrated water: LOST (default), SUBCATCH_AQUIFER or AQUIFER_2D. + +Remarks: +The first token is the tag itself (not the keyword TAG); `*` is the mesh-wide fallback and may appear on any row. The parameters are positional, in the project's rainfall units, at most five; a `-` leaves a slot unset (0) and trailing unused columns may be omitted. Dest is recognised as the final token when it is neither numeric nor `-`. NONE assigns no infiltration to the matching cells. The method spellings are those listed above; the [2D_OPTIONS] INFIL_DEFAULT_METHOD short forms (MOD_HORTON, MOD_GREEN_AMPT, CURVE_NUM) are not accepted on a row. + +Precedence at initialise is [2D_INFILTRATION] cell override, then the tag match, then the `*` row. A row's own Dest overrides [2D_OPTIONS] INFIL_DESTINATION. AQUIFER_2D needs a resolved [2D_AQUIFER]; SUBCATCH_AQUIFER needs the cell to lie inside a subcatchment that has a [GROUNDWATER] aquifer, and is refused when the integrated groundwater kernel is also on (the water would be delivered twice). + +The section may also be placed in the external mesh file, where it replaces the inline rows. The formulas are those of the [INFILTRATION] section; the mesh application is in hydrology Chapter 9 (mesh groundwater) and @ref hydraulics_ref_ch9_two_dimensional. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_INFILTRATION] {#engine_manual_sect_2D_INFILTRATION} + +Purpose: +Overrides the infiltration method and parameters of a single cell. + +Format: +``` +Cell Method (P1 P2 P3 P4 P5) (Dest) +``` + +Parameters: +Cell 1-based unified cell index (the first triangle is 1; the first quad is the number of triangles + 1). +Method NONE, HORTON, MODIFIED_HORTON, GREEN_AMPT, MODIFIED_GREEN_AMPT, CURVE_NUMBER or CONSTANT. +P1 .. P5 the method's positional parameters, laid out exactly as in [2D_INFILTRATION_DEFAULTS] (project rainfall units; `-` = unset). +Dest LOST (default), SUBCATCH_AQUIFER or AQUIFER_2D. + +Remarks: +Among the [2D_*] sections that address a cell by a bare index column, this is the only 1-based one; the sections that spell CELL as a scope keyword ([2D_INITIAL_QUALITY], [2D_AQUIFER], the quality and [GW_*] sections) are 1-based as well, whereas the TRI columns of [2D_INITIAL_VELOCITY], [2D_BOUNDARY_CONDITIONS] and [2D_BOUNDARY_QUALITY] are 0-based. Only the lower bound is checked at parse; a cell beyond the mesh is reported at initialise. A cell row wins over any tag or `*` row of [2D_INFILTRATION_DEFAULTS]. + +The section may also be placed in the external mesh file, where it replaces the inline rows. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_AQUIFER_OPTIONS] {#engine_manual_sect_2D_AQUIFER_OPTIONS} + +Purpose: +Sets the global options of the integrated two-zone groundwater kernel that runs beneath the mesh. + +Format: +``` +Keyword Value +``` + +Parameters: + +| Keyword | Values | Default | Description | +|---|---|---|---| +| SOIL_CHAR | RUSSO / GARDNER / BROOKS_COREY / VAN_GENUCHTEN | RUSSO | Soil-characteristic law shaping conductivity and water content against pressure head, for rows that do not set their own. | +| CLOSURE | AUTO / CLOSED_FORM / ENSLAVED / SIGMA | AUTO | Unsaturated-zone closure: a bulk store with a quasi-steady recharge (CLOSED_FORM), that store made algebraic in the water table (ENSLAVED), or an explicit column of sigma layers (SIGMA). AUTO selects per cell at initialise. | +| M_LAYERS | 2 .. 128 | 8 | Number of sigma layers of a SIGMA column, for rows that do not set their own. | +| CAPILLARY_DIFF | YES / TRUE / 1 / NO / FALSE / 0 | NO | Optional diffusive term of the SIGMA column. | +| C_GW | (0, 1] | 0.5 | Stability safety factor of the saturated-zone step. | +| C_COL | (0, 1] | 0.9 | Stability safety factor of the unsaturated column step. | +| FORCE_CLOSED_FORM | YES / TRUE / 1 / NO / FALSE / 0 | NO | Suppress the automatic switch away from CLOSED_FORM on strongly capillary soils. | +| MODE | MESH / PER_SUBCATCH | MESH | MESH runs one aquifer cell under every mesh cell. PER_SUBCATCH runs one degenerate cell per subcatchment with no lateral flow, exchanging with the outlet node. | +| DUNNE | YES / TRUE / 1 / NO / FALSE / 0 | YES | Saturation-excess transfer from the aquifer to the surface cell above it. Exists for comparison runs; NO breaks the mass balance between the two domains. | +| GW_ET | NONE / CAPILLARY_RISE / BOUNDARY_ET / BOTH | NONE | Subsurface evapotranspiration: capillary rise from the water table, removal at the top of the unsaturated column, both, or neither. | +| LINK_SEEPAGE | AUTO / NONE / TWO_WAY | AUTO | AUTO delivers conduit seepage to the aquifer cells crossed by the conduit, weighted by the length in each cell. NONE leaves seepage as a system loss. TWO_WAY uses a signed conductance law, allowing a conduit below the water table to gain water. Per-conduit overrides are set in [2D_AQUIFER_LINKS]. | + +Remarks: +Authoring any [2D_AQUIFER_OPTIONS], [2D_AQUIFER], [2D_AQUIFER_NODE] or [2D_AQUIFER_LINKS] row turns the kernel on unless [2D_OPTIONS] GROUNDWATER NO is set. A value of GW_ET spelled in [2D_OPTIONS] is folded into this section when the model opens. The writer emits only the keys that differ from their defaults. + +The kernel is described in hydrology Chapter 9 (mesh groundwater). + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_AQUIFER] {#engine_manual_sect_2D_AQUIFER} + +Purpose: +Gives the soil properties of the aquifer beneath the whole mesh, beneath every cell carrying a tag, or beneath one cell. + +Format: +``` +* Ks Zs ThetaS ThetaR Alpha (Key value) ... +TAG name Ks Zs ThetaS ThetaR Alpha (Key value) ... +CELL n Ks Zs ThetaS ThetaR Alpha (Key value) ... +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Ks saturated hydraulic conductivity (in/hr or mm/hr); > 0. +Zs thickness of the soil column from the aquifer bottom to the surface (ft or m); > 0. +ThetaS porosity, i.e. saturated water content (fraction); in (0, 1]. +ThetaR residual water content (fraction); in [0, ThetaS). +Alpha sorptive number of the Gardner and Russo laws (1/ft or 1/m); > 0. + +Keyword pairs, in any order after the five positional columns: + +| Keyword | Value | Default | Description | +|---|---|---|---| +| PSI_B | >= 0 (ft or m) | 0.20 | Air-entry pressure head of the Brooks-Corey law. | +| LAMBDA | > 0 | 0.40 | Pore-size distribution index of the Brooks-Corey law. | +| N | > 1 | 1.6 | Shape parameter n of the van Genuchten law (m = 1 - 1/n). | +| L | number | 0.5 | Mualem tortuosity exponent of the van Genuchten law. | +| C_LOSS | >= 0 (in/hr or mm/hr) | 0 | Deep-loss coefficient: the percolation rate out of the aquifer bottom at full saturation, scaled by the saturated fraction of the column. | +| HG0 | >= 0 (ft or m) | unset | Initial saturated thickness above the aquifer bottom, clamped to Zs. Unset leaves the water table at the aquifer bottom. | +| SOIL_CHAR | RUSSO / GARDNER / BROOKS_COREY / VAN_GENUCHTEN | from [2D_AQUIFER_OPTIONS] | Soil-characteristic law of these cells. | +| CLOSURE | AUTO / CLOSED_FORM / ENSLAVED / SIGMA | from [2D_AQUIFER_OPTIONS] | Unsaturated closure of these cells. | +| M_LAYERS | 2 .. 128 | from [2D_AQUIFER_OPTIONS] | Sigma layers of these cells' columns. | + +Remarks: +Rows are resolved in the order `*`, then TAG, then CELL, each pass overwriting the previous, so the most specific scope wins. All five positional columns are required. Values are authored in the project's units and converted to SI once at initialise; the writer emits the rows as authored, so a load-and-save is byte-identical. A CELL index beyond the mesh is reported at initialise. + +The theory of the two zones, the soil laws and the closures is in hydrology Chapter 9 (mesh groundwater). + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_AQUIFER_NODE] {#engine_manual_sect_2D_AQUIFER_NODE} + +Purpose: +Couples a node of the one-dimensional network to the aquifer cell beneath it, optionally through a semi-confining bed layer. + +Format: +``` +Node Cell (KC k) (DC d) (AREA a) +``` + +Parameters: +Node name of a node. +Cell 1-based unified index of the mesh cell containing the node. +k hydraulic conductivity of the bed layer (in/hr or mm/hr); >= 0. 0 (default) means a direct Darcy exchange with no bed. +d thickness of the bed layer (ft or m); >= 0; must be > 0 whenever k > 0. +a exchange area (sq ft or sq m); >= 0. 0 (default) uses the cell's own area. + +Remarks: +The three keyword pairs may appear in any order and any may be omitted. Each node may have one row only; a second row for the same node is an error at initialise, as is an unknown node or a cell beyond the mesh. Values are in the project's units and converted at initialise. + +The exchange law is described in hydrology Chapter 9 (mesh groundwater). + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_AQUIFER_LINKS] {#engine_manual_sect_2D_AQUIFER_LINKS} + +Purpose: +Overrides exchange between an individual conduit and the integrated aquifer beneath the mesh. + +Format: +``` +Link (KC k) (DC d) (EXCHANGE YES|NO) +``` + +Parameters: + +| Parameter | Values | Default | Description | +|---|---|---|---| +| Link | conduit name | required | Conduit whose exchange settings are overridden. | +| KC | finite number >= 0 (in/hr or mm/hr) | 0 | Bed hydraulic conductivity for TWO_WAY exchange. Zero or omission uses the conduit's [LOSSES] seepage rate. | +| DC | finite number >= 0 (ft or m) | 0 | Bed thickness for TWO_WAY exchange. Zero or omission uses the conduit's full depth. | +| EXCHANGE | YES / TRUE / 1 / NO / FALSE / 0 | YES | NO excludes this conduit from aquifer exchange; its ordinary 1D seepage remains a system loss. | + +Remarks: +The keyword pairs are optional and may appear in any order. Unknown keywords, missing values, non-finite numbers and negative KC or DC values are parse errors. An unknown link or a link that is not a conduit produces a warning when exchange links are resolved, and its row is ignored. If several rows name the same conduit, the first matching row supplies its settings. + +Set `LINK_SEEPAGE TWO_WAY` in [2D_AQUIFER_OPTIONS] to use KC and DC. A positive KC can enable exchange for a conduit with no [LOSSES] seepage rate. With the default `LINK_SEEPAGE AUTO`, the existing seepage rate supplies one-way recharge and KC and DC do not change that rate. `LINK_SEEPAGE NONE` disables conduit-to-aquifer exchange globally. + +The engine locates the conduit from its endpoints in [COORDINATES] and any [VERTICES], and assigns exchange to the mesh cells crossed by that polyline. The aquifer must be active and the conduit must overlap the mesh. The writer retains the authored KC and DC values and writes non-default settings. + +Example: +``` +[2D_AQUIFER_OPTIONS] +LINK_SEEPAGE TWO_WAY + +[2D_AQUIFER_LINKS] +;;Link Options +C1 KC 50 DC 2.5 +C2 EXCHANGE NO +``` + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_INITIAL_QUALITY] {#engine_manual_sect_2D_INITIAL_QUALITY} + +Purpose: +Sets the initial concentration of a transported species in the water standing on the mesh at the start of the simulation. + +Format: +``` +* Species Conc +TAG name Species Conc +CELL n Species Conc +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__` when that transport is on. +Conc initial value: concentration in the species' units, water age in hours, temperature in degrees C. Must be finite and >= 0. + +Remarks: +A `*` row has exactly three tokens and a TAG or CELL row exactly four. Rows are applied in the order `*`, then TAG, then CELL, later writes winning. The seeded mass is the concentration times the cell's initial volume, so a dry cell receives nothing. An unknown species, a tag that matches no cell, a cell beyond the mesh, or rows in a model that carries no transported species are fatal at initialise. + +The section may also be placed in the external mesh file. The surface transport scheme is in @ref hydraulics_ref_ch9_two_dimensional. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_BOUNDARY_QUALITY] {#engine_manual_sect_2D_BOUNDARY_QUALITY} + +Purpose: +Sets the concentration of a species carried by the water that enters the mesh through a non-wall boundary edge. + +Format: +``` +Cell Edge Species Conc +``` + +Parameters: +Cell 0-based unified cell index (the TRI column of files the engine writes). +Edge local edge of that cell (0 .. 2 for a triangle, 0 .. 3 for a quad), one that carries a [2D_BOUNDARY_CONDITIONS] row. +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__`. +Conc inflow value: concentration in the species' units, water age in hours, temperature in degrees C. Must be finite and >= 0. + +Remarks: +Exactly four tokens. The value applies whenever the edge's boundary condition brings water in; outflow carries the cell's own concentration. A cell beyond the mesh, an unknown species, or rows in a model that carries no transported species are fatal at initialise. + +The section may also be placed in the external mesh file. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_COVERAGES] {#engine_manual_sect_2D_COVERAGES} + +Purpose: +Assigns land uses, and the percentage of area each covers, to the cells of the mesh, so that pollutant buildup, washoff and street sweeping run on the overland surface as they do on subcatchments. + +Format: +``` +* LandUse Percent (LandUse Percent) ... +TAG name LandUse Percent (LandUse Percent) ... +CELL n LandUse Percent (LandUse Percent) ... +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +LandUse name of a land use from the [LANDUSES] section. +Percent percent of the cell's area covered by that land use; >= 0, and the percents of one row sum to at most 100. + +Remarks: +A row carries the whole coverage set of its scope: a later row with the same scope replaces the earlier one rather than adding to it, and the scopes resolve `*`, then TAG, then CELL, the most specific winning. An unknown land use, a tag that matches no cell or a cell beyond the mesh is fatal at initialise, as is a model with no [LANDUSES] or no transported species. + +Buildup accrues per cell, land use and species with the land use's [BUILDUP] function, is swept on the [LANDUSES] schedule and washed off by the cell's own runoff (its net outflow per runoff step) into the cell's species row. Under [2D_OPTIONS] RAINFALL_MODE NONE the rows are inert (the subcatchments own the surface); a covered cell that lies inside a subcatchment which itself has [COVERAGES] raises a double-counting warning. A land use whose buildup is normalised per curb length needs a [2D_CURB_LENGTH] on every cell it covers. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_LOADINGS] {#engine_manual_sect_2D_LOADINGS} + +Purpose: +Sets the initial pollutant buildup on the cells of the mesh at the start of the simulation. + +Format: +``` +* Species Buildup +TAG name Species Buildup +CELL n Species Buildup +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Species name of a pollutant or of a species of the reactions component (water age and temperature do not build up). +Buildup initial buildup per unit land area (lbs/acre or kg/ha); >= 0. + +Remarks: +Exactly one species and value after the scope. Scopes resolve `*`, then TAG, then CELL. The value is divided among the cell's covered land uses; for a land use normalised per curb length it is converted with the cell's [2D_CURB_LENGTH]. Cells without a row start with the buildup their [BUILDUP] functions reach after [OPTIONS] DRY_DAYS, as subcatchments do. Rows without any [2D_COVERAGES] raise a warning and build up nothing. + +This section has no counterpart in SWMM 5. + + + +### Section: [2D_CURB_LENGTH] {#engine_manual_sect_2D_CURB_LENGTH} + +Purpose: +Gives the length of curb on a mesh cell, for land uses whose pollutant buildup is normalised per unit curb length. + +Format: +``` +* Length +TAG name Length +CELL n Length +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Length curb length on the cell (ft or m); >= 0. + +Remarks: +Exactly one value after the scope. Scopes resolve `*`, then TAG, then CELL. A cell covered by a land use with a per-curb buildup function and no positive curb length is an error at initialise. + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_TRANSPORT_OPTIONS] {#engine_manual_sect_GW_TRANSPORT_OPTIONS} + +Purpose: +\status{Planned} Sets the process switches and thermal boundary conditions of solute and heat transport in the integrated groundwater kernel. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +TRANSPORT_POLLUTANTS YES / NO +TRANSPORT_MSX YES / NO +TRANSPORT_AGE YES / NO +TRANSPORT_TEMPERATURE YES / NO +DISPERSION YES / NO +CONDUCTION YES / NO +SURFACE_THERMAL_BC AIR +SURFACE_THERMAL_BC SURFACE_WATER +SURFACE_THERMAL_BC FIXED Temp +SURFACE_THERMAL_BC TIMESERIES Tseries +DEEP_THERMAL_BC GEOTHERMAL_FLUX Flux (DEPTH z) +DEEP_THERMAL_BC FIXED_TEMP Temp (DEPTH z) +DEEP_THERMAL_BC TIMESERIES Tseries (DEPTH z) +THERMAL_MIXING ARITHMETIC / GEOMETRIC +C_DIFF value +``` + +Parameters: + +| Keyword | Values | Default | Description | +|---|---|---|---| +| TRANSPORT_POLLUTANTS | YES / ON / NO / OFF | YES | Carry the [POLLUTANTS] species in the aquifer. | +| TRANSPORT_MSX | YES / ON / NO / OFF | YES | Carry the reactions component's species in the aquifer. | +| TRANSPORT_AGE | YES / ON / NO / OFF | YES | Carry water age in the aquifer. | +| TRANSPORT_TEMPERATURE | YES / ON / NO / OFF | YES | Carry temperature in the aquifer. | +| DISPERSION | YES / ON / NO / OFF | YES | Activate the dispersivities and molecular diffusivity of [GW_TRANSPORT_PARAMS]. | +| CONDUCTION | YES / ON / NO / OFF | YES | Activate vertical and lateral heat conduction. | +| SURFACE_THERMAL_BC | AIR / SURFACE_WATER / FIXED Temp / TIMESERIES Tseries | AIR | Temperature at the top of the column when it is not inundated: the air temperature, the surface water, a fixed value (degrees C) or a [TIMESERIES]. | +| DEEP_THERMAL_BC | GEOTHERMAL_FLUX Flux / FIXED_TEMP Temp / TIMESERIES Tseries, each optionally followed by DEPTH z | GEOTHERMAL_FLUX | Condition at the bottom of the column: a geothermal heat flux (W per sq m), a fixed temperature (degrees C) or a [TIMESERIES]; DEPTH z (>= 0, metres) places it. | +| THERMAL_MIXING | ARITHMETIC / GEOMETRIC | ARITHMETIC | How the effective thermal conductivity of the soil-water mixture is averaged. | +| C_DIFF | (0, 1] | 0.4 | Explicit diffusion Courant number bounding the transport step. | + +Remarks: +FIXED and FIXED_TEMP require a number and GEOTHERMAL_FLUX a number; TIMESERIES requires a series name. DEPTH is read only as the fourth and fifth tokens of a DEEP_THERMAL_BC line. Naming any [GW_*] section marks subsurface transport as authored, which is what the run-time warning and the writer key on. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +The intended formulation is described in hydrology Chapter 9 (mesh groundwater). + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_TRANSPORT_PARAMS] {#engine_manual_sect_GW_TRANSPORT_PARAMS} + +Purpose: +\status{Planned} Gives the solute and thermal properties of the aquifer matrix beneath the whole mesh, beneath tagged cells, or beneath one cell. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +* (RhoS Cs LambdaS As AlphaL AlphaT Dm Dv GeoFlux) +TAG name (RhoS Cs LambdaS As AlphaL AlphaT Dm Dv GeoFlux) +CELL n (RhoS Cs LambdaS As AlphaL AlphaT Dm Dv GeoFlux) +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +RhoS grain density (kg per cu m; default 2650). +Cs grain specific heat (J per kg per K; default 880). +LambdaS grain thermal conductivity (W per m per K; default 2.0). +As specific surface area of the grains (sq m per kg; default 0). +AlphaL longitudinal dispersivity (m; default 1.0). +AlphaT transverse dispersivity (m; default 0.1). +Dm molecular diffusivity (sq m per s; default 1.0e-9). +Dv vapour diffusivity (sq m per s; default 1.0e-9). +GeoFlux geothermal flux (W per sq m), or the deep temperature (degrees C) when DEEP_THERMAL_BC is FIXED_TEMP; default 0.065. The only signed column. + +Remarks: +All nine columns are positional and optional; an omitted column or a `-` keeps the default. More than nine columns is a parse error, and every column but GeoFlux must be >= 0. Values are SI. Scopes resolve `*`, then TAG, then CELL by order of the rows; a tag that matches no cell or a cell beyond the mesh is reported when the model initialises. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_SORPTION] {#engine_manual_sect_GW_SORPTION} + +Purpose: +\status{Planned} Gives the sorption partition coefficient and, optionally, the first-order decay of a species in the aquifer, by scope. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +* Species Kd (Decay) +TAG name Species Kd (Decay) +CELL n Species Kd (Decay) +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__`. +Kd linear partition coefficient (L per kg); >= 0. +Decay first-order decay rate (1/day); >= 0. Absent or `-`: a pollutant uses its [POLLUTANTS] decay coefficient. + +Remarks: +Scopes resolve `*`, then TAG, then CELL. An unknown species, a tag that matches no cell or a cell beyond the mesh is reported when the model initialises. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_INITIAL_QUALITY] {#engine_manual_sect_GW_INITIAL_QUALITY} + +Purpose: +\status{Planned} Seeds the initial concentration, water age or temperature of a zone of the aquifer column. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +* SAT Species Value +* UNSAT Species Value +* LAYER j Species Value +TAG name Zone Species Value +CELL n Zone Species Value +FILE Fname +``` + +Parameters: +name a cell tag from [2D_TRIANGLES] or [2D_QUADS]. +n 1-based unified cell index. +Zone SAT (the saturated zone), UNSAT (the unsaturated zone) or LAYER j (layer j of a SIGMA column, j >= 1). +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__`. +Value initial value: concentration in the species' units, water age in hours, temperature in degrees C. Concentrations must be >= 0; age and temperature may be negative. +Fname name of a CSV file holding the same tokens per line (scope, zone, species, value). + +Remarks: +The FILE form names a sidecar resolved relative to the input file's directory and read when the model initialises. Its fields may be separated by commas, semicolons, tabs or spaces, and a first line that does not parse is taken as a header. A missing file is reported at initialise, as is an unknown species, a tag that matches no cell, a cell beyond the mesh, or a negative concentration. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_BOUNDARY_QUALITY] {#engine_manual_sect_GW_BOUNDARY_QUALITY} + +Purpose: +\status{Planned} Sets the quality of water crossing a lateral boundary edge of the aquifer. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +Cell Edge Species CONC Value +Cell Edge Species TS Tseries +Cell Edge Species MASSFLUX Value +Cell Edge Species HEATFLUX Value +``` + +Parameters: +Cell 1-based unified cell index. +Edge local edge of that cell, 0-based (0 .. 2 for a triangle, 0 .. 3 for a quad). +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__`. +CONC the value is a concentration in the species' units (temperature in degrees C). +TS the value is the name of a [TIMESERIES] of that quantity. +MASSFLUX the value is a mass flux per metre of edge. +HEATFLUX the value is a heat flux per metre of edge. +Value a number, or the name of a [TIMESERIES] in its place. +Tseries name of a [TIMESERIES]. + +Remarks: +Exactly five tokens. For CONC, MASSFLUX and HEATFLUX a non-numeric fifth token is taken as a series name. The edge is checked against the cell's own vertex count at initialise, as are the cell index, the species name and any series name. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +This section has no counterpart in SWMM 5. + + + +### Section: [GW_SOURCES] {#engine_manual_sect_GW_SOURCES} + +Purpose: +\status{Planned} Declares wells and point sources or sinks in the aquifer, with their flow and the quality of injected water. The rows are parsed, validated, kept and written back unchanged, but no kernel consumes them in this release. + +Format: +``` +Name CELL n FLOW Flow (Species CONC Value) (Species MASS Value) ... +Name TAG tag FLOW Flow (Species CONC Value) ... +Name XY x y FLOW Flow (Species CONC Value) ... +``` + +Parameters: +Name name of the source; unique within the section. +n 1-based unified cell index of the cell holding the source. +tag a cell tag from [2D_TRIANGLES] or [2D_QUADS]; the source applies to every cell carrying it. +x, y map coordinates of the source; it is placed in the cell whose centroid is nearest. +Flow flow rate (cu m per s), positive to inject and negative to extract, or the name of a [TIMESERIES] of the flow. +Species name of a pollutant, of a species of the reactions component, or `__WATER_AGE__` or `__TEMPERATURE__`. +CONC the term's value is a concentration in the injected water. +MASS the term's value is a mass rate. +Value a number, or the name of a [TIMESERIES] in its place. + +Remarks: +A row needs at least Name, a location, FLOW and its value; species terms follow in groups of three and may repeat. A duplicate Name is an error at initialise, not a last-wins overwrite; so are a cell beyond the mesh, a tag that matches no cell, an unknown species and an unknown series. The XY form keeps its coordinates for the writer and resolves to a cell at initialise. + +At run time the engine emits one warning: "[GW_*] subsurface transport is AUTHORED but INERT this run: the integrated 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides the two-zone kernel these sections configure and is not available in this release. The rows are validated, kept and written back unchanged." + +This section has no counterpart in SWMM 5. + + + +## 2.5 Process Component Configuration Sections + +The sections in this part of the chapter are **not** read by the input parser's +section registry. Each belongs to a *process component* — a reaction system, +the Eulerian transport engine, the heat module or the water-age tracker — and +is read by that component from the file named in its +`[PROCESS_COMPONENTS]` row (@ref engine_manual_sect_PROCESS_COMPONENTS): + +``` +[PROCESS_COMPONENTS] +org.hydrocouple.openswmm.reactions config="model.rxn" +org.hydrocouple.openswmm.transport.ard config="model.ard" +org.hydrocouple.openswmm.waterage config="model.age" +org.hydrocouple.openswmm.heat config="model.heat" +``` + +**Dispatch.** Every row is `Id key="value" ...`. The first token is the +component id; every further token must be a `key="value"` pair (the quotes are +optional and are stripped), and one that is not is a parse error naming the +component and the token. The key `CONFIG` (case-insensitive) names the +component's configuration file; any other key is passed to the component +unchanged. At open, after the whole `.inp` has been read, the engine resolves +the rows in file order: an id that appears twice is refused; an id that looks +like a shared-library path (contains a path separator or ends in `.so`, +`.dylib` or `.dll`) is refused until HydroCouple library loading arrives +(plan phase HC2); an unknown id is refused with the list of known ids; a +known id whose implementation has not landed is refused with the plan phase +that delivers it; a row without `CONFIG` is refused. Otherwise the file is +read — a relative path resolves against the directory of the `.inp` — and +handed to the component, which parses its own sections and reports every +error it finds. Errors from any component fail the open unless the engine was +opened leniently, in which case they are recorded and the configuration that +failed is discarded wholesale (no component ever half-applies). + +**File dialect.** A component file uses the bracketed-section dialect of the +`.inp`: `[SECTION]` headers (case-insensitive), `;` comments, blank lines +ignored, one record per line. Content before the first header is an error, and +a component file may not itself contain a `[PROCESS_COMPONENTS]` section (no +recursion). The conventional extensions are `.rxn` (reactions), `.ard` +(Eulerian transport), `.age` (water age) and `.heat` (heat); the engine does +not check the extension. On save, every implemented component renders its +configuration back to its file from the live model state, and a save-as +carries the file alongside the written `.inp`. + +**Embedded form.** The twelve `[REACTION_*]` sections may also be written +directly in the `.inp`. They are captured verbatim by the input parser and +applied after component resolution: when no external reactions component is +registered they take effect with a style warning; when one is registered they +are **ignored** with a warning and the external file wins wholesale. Embedded +sections are not written back into the `.inp` on save — the writer warns that +they are lost from the saved deck — so the external file is the intended +layout. The heat, water-age and transport sections have no embedded form. + +**Cross-component references.** `[TRANSPORT_BOUNDARIES]` and +`[TRANSPORT_SOURCES]` rows name species declared in `[REACTION_SPECIES]`, and +the per-element rows of `[RADIATIVE_FLUXES]` and `[SEDIMENT_EXCHANGE]` name +links, nodes and `[TAGS]` values. These are resolved once, after every +component has applied, so the order of the `[PROCESS_COMPONENTS]` rows does not +matter. + +| Component id | Configuration file | Sections | Status | +|---|---|---|---| +| `org.hydrocouple.openswmm.reactions` | `model.rxn` (or embedded in the `.inp`) | `[REACTION_OPTIONS]` `[REACTION_SPECIES]` `[REACTION_COEFFICIENTS]` `[REACTION_TERMS]` `[REACTION_PIPES]` `[REACTION_TANKS]` `[REACTION_QUALITY]`; `[REACTION_SOURCES]` `[REACTION_PARAMETERS]` `[REACTION_PATTERNS]` `[REACTION_REPORT]` `[REACTION_SUBCATCHMENTS]` are recognised and refused until their phases | \status{Implemented} | +| `org.hydrocouple.openswmm.transport.ard` | `model.ard` | `[TRANSPORT_OPTIONS]` `[CONDUIT_DISPERSION]` `[TRANSPORT_BOUNDARIES]` `[TRANSPORT_SOURCES]`; `[STORAGE_MIXING]` is refused until phase E2b | \status{Implemented} | +| `org.hydrocouple.openswmm.transport.lard` | none | none — the Lagrangian engine is selected by `[OPTIONS] QUALITY_SOLVER LAGRANGIAN` (alias `LARD`) and reads no component file; registering this id is refused with "arrives with plan phase T5" | \status{Planned} | +| `org.hydrocouple.openswmm.heat` | `model.heat` | `[HEAT_SOURCES]` `[HEAT_FLUXES]` `[RADIATIVE_FLUXES]` `[SOLAR_RADIATION]` `[CLOUD_COVER]` `[SEDIMENT_EXCHANGE]` | \status{Implemented} | +| `org.hydrocouple.openswmm.waterage` | `model.age` | `[WATER_AGE_SOURCES]` | \status{Implemented} | +| `org.hydrocouple.openswmm.integrated2d` | none | none — unified 2D surface and two-zone groundwater component; registering this id is refused with "arrives with plan phase S1/G1" | \status{Planned} | + +The four implemented components are registered once, at the first open, so +the id list above is the complete set a `[PROCESS_COMPONENTS]` row may name. + + + +### Component section: [REACTION_OPTIONS] {#engine_manual_sect_REACTION_OPTIONS} + +Purpose: \status{Implemented} +Sets the integrator, coupling, units, tolerances and reference temperature of +the reaction system. + +Format: +``` +SOLVER EUL / RK5 / ROS2 / BDF2 +COUPLING NONE / FULL +RATE_UNITS SEC / MIN / HR / DAY +AREA_UNITS FT2 / M2 / CM2 +TIMESTEP value +ATOL value +RTOL value +TEMPERATURE value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `SOLVER` | Integrator for the RATE species. RK5 is explicit and cheapest for non-stiff kinetics; ROS2 and BDF2 are implicit and are the remedy when RK5 reports its substep cap. | EUL, RK5, ROS2 or BDF2 | RK5 | +| `COUPLING` | NONE integrates one RATE species at a time with the others frozen at their start-of-step values (EPANET-MSX semantics); FULL integrates all RATE species simultaneously. A system with a single RATE species is always coupled. | NONE or FULL | NONE | +| `RATE_UNITS` | Time unit of every RATE expression. The evaluated rate is multiplied by 1, 1/60, 1/3600 or 1/86400 to give a per-second rate. | SEC, MIN, HR or DAY | HR | +| `AREA_UNITS` | Area unit recorded for wall-species expressions. | FT2, M2 or CM2 | FT2 | +| `TIMESTEP` | Reaction step; 0 means follow the quality step. | value, 0 or greater | 0 | +| `ATOL` | Absolute tolerance of the integrator, used for every species that does not carry its own in `[REACTION_SPECIES]`. | value, greater than 0 | 1.0e-6 | +| `RTOL` | Relative tolerance of the integrator, likewise. | value, greater than 0 | 1.0e-4 | +| `TEMPERATURE` | Value of the expression variable `TEMP` for an element that has no heat-transport temperature (`HEAT_TRANSPORT OFF`, or before the heat state is seeded). | degrees C, any finite value | 20 | + +Remarks: +Keys are case-insensitive and may appear in any order; a line with fewer than +two tokens is skipped and an unrecognised key is an error. A bad value is an +error naming the key. `TEMPERATURE` has no range gate — any finite number is +accepted. `AREA_UNITS` and `TIMESTEP` are parsed, stored and written back on +save; see the audit note at the end of this part for their consumers. + + + +### Component section: [REACTION_SPECIES] {#engine_manual_sect_REACTION_SPECIES} + +Purpose: \status{Implemented} +Declares the species of the reaction system. At least one species is required. + +Format: +``` +BULK / WALL Name Units (Atol Rtol) +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Kind | BULK: a dissolved species carried with the water. WALL: a species attached to the wetted wall. | BULK or WALL | required | +| `Name` | Species name, unique among species, coefficients, terms, `[POLLUTANTS]` names and the reserved names. | text | required | +| `Units` | Concentration unit label recorded with the species (for example MG or UG). It is carried to the species registry and the reports; no conversion is applied. | text | required | +| `Atol` | Absolute tolerance for this species; 0 means use the global `ATOL`. | value | 0 | +| `Rtol` | Relative tolerance for this species; 0 means use the global `RTOL`. | value | 0 | + +Remarks: +A row with fewer than three tokens, a kind other than BULK or WALL, a +duplicate species name, or a name that collides with an existing pollutant or +reserved species is an error. A configuration that declares no species is +refused as a whole. Species are entered into the engine's species registry +only after the complete file has validated and every expression has compiled, +so a rejected file leaves no species behind. + + + +### Component section: [REACTION_COEFFICIENTS] {#engine_manual_sect_REACTION_COEFFICIENTS} + +Purpose: \status{Implemented} +Declares named numeric coefficients that expressions may reference. + +Format: +``` +PARAMETER / CONSTANT Name Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Kind | PARAMETER: a coefficient that may later be overridden per element. CONSTANT: a fixed value. | PARAMETER or CONSTANT | required | +| `Name` | Coefficient name, unique among coefficients and species. | text | required | +| `Value` | Numeric value. | value | required | + +Remarks: +A row with fewer than three tokens, a kind other than PARAMETER or CONSTANT, a +name that duplicates a coefficient or species, or a non-numeric value is an +error. The kind keyword must be spelled in full — `PARAM` is not accepted. +Both kinds evaluate identically in this release; the per-element override +table that would distinguish them is `[REACTION_PARAMETERS]`, which is not yet +supported. + + + +### Component section: [REACTION_TERMS] {#engine_manual_sect_REACTION_TERMS} + +Purpose: \status{Implemented} +Declares named intermediate expressions that pipe and tank expressions may +reference, so a closure is defined once rather than copied. + +Format: +``` +Name Expression +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `Name` | Term name, unique among terms, species and coefficients. | text | required | +| `Expression` | The remainder of the row, taken verbatim, including any unquoted commas. A remainder wrapped in double quotes is unwrapped. | expression | required | + +Remarks: +A row with fewer than two tokens or a duplicate name is an error. Terms are +compiled in file order and a term may reference only the terms declared before +it (forward references are compile errors, reported with the term name and +column). Expressions may reference species, coefficients, earlier terms, the +hydraulic variables listed under `[REACTION_PIPES]`, and `[POLLUTANTS]` names +read-only. + + + +### Component section: [REACTION_PIPES] {#engine_manual_sect_REACTION_PIPES} + +Purpose: \status{Implemented} +Gives each species its kinetic expression in the pipe (conduit) scope. + +Format: +``` +RATE / EQUIL / FORMULA Species Expression +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Form | RATE: the expression is the time derivative of the species, in `RATE_UNITS`. EQUIL: the expression is an algebraic residual driven to zero. FORMULA: the expression is the species value itself. | RATE, EQUIL or FORMULA | required | +| `Species` | A species declared in `[REACTION_SPECIES]`. | text | required | +| `Expression` | The remainder of the row, taken verbatim (a double-quoted remainder is unwrapped). | expression | required | + +Remarks: +A row with fewer than three tokens, an unknown form, an undeclared species, or +a second expression for the same species in this scope is an error. Naming a +`[POLLUTANTS]` row here is refused: pollutant kinetics arrive with plan phase +R4b, and until then pollutants may only be referenced read-only inside +expressions (their `[POLLUTANTS]` decay coefficient applies under every +engine). A species with no row in this scope has no reaction in pipes. The +hydraulic variables available to every expression, in the engine's internal +units, are `D` depth (ft), `Q` flow (cfs), `U` velocity (ft/s), `RE` Reynolds +number, `US` shear velocity (ft/s), `FF` Darcy-Weisbach friction factor, `AV` +wetted surface area per volume (1/ft), `HRT` hydraulic residence time (s), `DT` +reaction step (s) and `TEMP` water temperature (degrees C, falling back to +`[REACTION_OPTIONS] TEMPERATURE` when heat transport is off). Variable names +are case-insensitive. If the section is absent every species is given no pipe +expression. + + + +### Component section: [REACTION_TANKS] {#engine_manual_sect_REACTION_TANKS} + +Purpose: \status{Implemented} +Gives each species its kinetic expression in the tank (storage node) scope. + +Format: +``` +RATE / EQUIL / FORMULA Species Expression +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Form | As for `[REACTION_PIPES]`. | RATE, EQUIL or FORMULA | required | +| `Species` | A species declared in `[REACTION_SPECIES]`. | text | required | +| `Expression` | The remainder of the row, taken verbatim. | expression | required | + +Remarks: +The row grammar, validation rules and available variables are exactly those +of `[REACTION_PIPES]`; the two sections share one parser and differ only in +the scope they fill. A species may have a different form in each scope (for +example a wall-demand term in pipes and none in tanks), and one expression per +species per scope is the limit. If the section is absent every species is +given no tank expression. + + + +### Component section: [REACTION_QUALITY] {#engine_manual_sect_REACTION_QUALITY} + +Purpose: \status{Implemented} +Sets the initial concentration of each species, globally and per element. + +Format: +``` +GLOBAL Species Value +NODE Node Species Value +LINK Link Species Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Scope | GLOBAL applies to every element; NODE and LINK apply to one named element and win over GLOBAL there. | GLOBAL, NODE or LINK | required | +| `Node`, `Link` | Name of an existing node or link (NODE and LINK rows only). | text | required | +| `Species` | A species declared in `[REACTION_SPECIES]`. | text | required | +| `Value` | Initial concentration in the species' own units. | value, 0 or greater | 0 | + +Remarks: +A scope other than GLOBAL, NODE or LINK, a row short of its fields, an unknown +element, an undeclared species, a negative value, or a second NODE or LINK row +for the same element and species is an error. Every species starts at 0 when +it has no GLOBAL row, and when the section is absent altogether. Element names +are resolved at open, after the full `.inp` has been read. Rows of +`[INITIAL_QUALITY]` (@ref engine_manual_sect_INITIAL_QUALITY) that name a +reaction species are mirrored into this table, so an element may be seeded +from either place; the same element and species in both is a duplicate error, +and on save a mirrored row is written once, in `[INITIAL_QUALITY]`. The name +REACTION_INITIAL that appears in some older prose is not recognised and is +refused as an unknown section. + + + +### Component section: [REACTION_SOURCES] {#engine_manual_sect_REACTION_SOURCES} + +Purpose: \status{Planned} +Reserved for per-element species sources of the reaction system. The tag is +recognised so that a typo cannot hide behind it, but no row is parsed. + +Format: +``` +[REACTION_SOURCES] +;; no row grammar is defined in this release +``` + +Parameters: +None. No row is read. + +Remarks: +Presence of the section in a `.rxn` file, or embedded in the `.inp`, is an +error — "recognised but not yet supported — arrives with plan phase +R-sources (post-R3)" — and the whole reactions configuration is rejected. +Until it lands, species mass enters through the transport component's +`[TRANSPORT_BOUNDARIES]` and `[TRANSPORT_SOURCES]`. + + + +### Component section: [REACTION_PARAMETERS] {#engine_manual_sect_REACTION_PARAMETERS} + +Purpose: \status{Planned} +Reserved for per-element overrides of PARAMETER coefficients. The tag is +recognised; no row is parsed. + +Format: +``` +[REACTION_PARAMETERS] +;; no row grammar is defined in this release +``` + +Parameters: +None. No row is read. + +Remarks: +Presence of the section is an error — "arrives with plan phase R-parameters +(post-R3)" — and the whole reactions configuration is rejected. Until it +lands, a `[REACTION_COEFFICIENTS]` PARAMETER behaves exactly like a CONSTANT. + + + +### Component section: [REACTION_PATTERNS] {#engine_manual_sect_REACTION_PATTERNS} + +Purpose: \status{Planned} +Reserved for time patterns applied to reaction sources. The tag is +recognised; no row is parsed. + +Format: +``` +[REACTION_PATTERNS] +;; no row grammar is defined in this release +``` + +Parameters: +None. No row is read. + +Remarks: +Presence of the section is an error — "arrives with plan phase R-sources +(post-R3)" — and the whole reactions configuration is rejected. A +time-varying boundary or source is available today as a `TIMESERIES` row of +`[TRANSPORT_BOUNDARIES]` or `[TRANSPORT_SOURCES]`. + + + +### Component section: [REACTION_REPORT] {#engine_manual_sect_REACTION_REPORT} + +Purpose: \status{Planned} +Reserved for reaction-system reporting options. The tag is recognised; no row +is parsed. + +Format: +``` +[REACTION_REPORT] +;; no row grammar is defined in this release +``` + +Parameters: +None. No row is read. + +Remarks: +Presence of the section is an error — "arrives with plan phase R5" — and the +whole reactions configuration is rejected. Species results are written with +the pollutant results under the ordinary `[REPORT]` options. + + + +### Component section: [REACTION_SUBCATCHMENTS] {#engine_manual_sect_REACTION_SUBCATCHMENTS} + +Purpose: \status{Planned} +Reserved for reaction expressions in the subcatchment (runoff) scope. The tag +is recognised; no row is parsed. + +Format: +``` +[REACTION_SUBCATCHMENTS] +;; no row grammar is defined in this release +``` + +Parameters: +None. No row is read. + +Remarks: +Presence of the section is an error — "arrives with plan phase R6" — and the +whole reactions configuration is rejected. Reactions run in the pipe and tank +scopes only. + + + +### Component section: [HEAT_SOURCES] {#engine_manual_sect_HEAT_SOURCES} + +Purpose: \status{Implemented} +Sets the temperature carried by water entering the network through each +source pathway, globally and per node. + +Format: +``` +Source GLOBAL Temperature +Source NODE Node Temperature +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `Source` | The inflow pathway: RAINFALL (runoff), DWF (dry-weather inflow), GW (groundwater), RDII, EXTERNAL_INFLOW (`[INFLOWS]` rows), IFACE (interface-file inflow) or INITIAL_STATE (water in the network at the start). | keyword | required | +| Scope | GLOBAL sets the pathway everywhere; NODE sets it at one node and wins there. | GLOBAL or NODE | required | +| `Node` | Name of an existing node (NODE rows only). | text | required | +| `Temperature` | Inlet temperature. | degrees C, from -50 to 100 | 20 | + +Remarks: +Every pathway without a row enters at 20 degrees C. NODE scope is available for +DWF and EXTERNAL_INFLOW only; any other source takes GLOBAL. A row with fewer +than three tokens, an unknown source, an unknown node, a temperature outside +the range, or a second NODE row for the same source and node is an error. +SUBCATCH scope ("arrives with plan phase H5") and EDGE_BC scope ("arrives with +phase T6") are refused, and a `TIMESERIES` in place of the value is refused — +this table takes constant temperatures. Any error discards the whole heat +configuration. The component warns when `[OPTIONS] HEAT_TRANSPORT` is OFF, +because then no temperature is tracked. + + + +### Component section: [HEAT_FLUXES] {#engine_manual_sect_HEAT_FLUXES} + +Purpose: \status{Implemented} +Switches the energy-flux modules on or off and chooses what a dry element +reports. With every module off, temperature is carried and mixed as a +conservative tracer. + +Format: +``` +SURFACE_EXCHANGE ON / OFF +RADIATIVE_EXCHANGE ON / OFF +LAYER_CONDUCTION ON / OFF +SEDIMENT_EXCHANGE ON / OFF +DRY_ELEMENT_TEMPERATURE HOLD / AIR / DEFAULT +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `SURFACE_EXCHANGE` | Latent and sensible exchange at the free surface, driven by the `[TEMPERATURE]` climate data. | ON or OFF | OFF | +| `RADIATIVE_EXCHANGE` | Shortwave and longwave exchange, parameterised by `[RADIATIVE_FLUXES]`, `[SOLAR_RADIATION]` and `[CLOUD_COVER]`. | ON or OFF | OFF | +| `LAYER_CONDUCTION` | Vertical conduction between LID layers. Its material constants are built in; no section configures them. | ON or OFF | OFF | +| `SEDIMENT_EXCHANGE` | The bed zone beneath conduits — conduction to the bed and deep ground plus hyporheic exchange — parameterised by `[SEDIMENT_EXCHANGE]`. | ON or OFF | OFF | +| `DRY_ELEMENT_TEMPERATURE` | What a dry element reports: HOLD freezes the last wet value; AIR tracks air temperature; DEFAULT falls to 20 degrees C. | HOLD, AIR or DEFAULT | HOLD | + +Remarks: +Each row is exactly two tokens; `YES` and `NO` are accepted for `ON` and +`OFF`. An unknown module name, a toggle value other than these four, or a +`DRY_ELEMENT_TEMPERATURE` value other than the three policies is an error. +Every module defaults OFF so that a deck gets pure transport unless it asks +for physics. The parameter sections may be present while their module is OFF; +they are then parsed and validated but have no effect. `SEDIMENT_EXCHANGE` +here is the toggle; the section of the same name holds its parameters. + + + +### Component section: [RADIATIVE_FLUXES] {#engine_manual_sect_RADIATIVE_FLUXES} + +Purpose: \status{Implemented} +Supplies the incoming shortwave resource and the optical properties of the +water surface and its surroundings for `RADIATIVE_EXCHANGE`. + +Format: +``` +SHORTWAVE GLOBAL Value +SHORTWAVE GLOBAL TIMESERIES Name +SHORTWAVE GLOBAL COMPUTED +ATM_EMISS_COEFF GLOBAL Value +ATM_LW_REFLECTION GLOBAL Value +Parameter GLOBAL Value +Parameter TAG / LINK / NODE Name Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `SHORTWAVE` | Incoming solar radiation: a constant, a `[TIMESERIES]` of measured values, or COMPUTED from solar position and a clear-sky atmosphere using `[SOLAR_RADIATION]`. GLOBAL only. | W/m2, 0 or greater; or TIMESERIES name; or COMPUTED | 0 (constant) | +| `ALBEDO` | Shortwave reflectance of the water surface. | fraction 0 to 1 | 0 | +| `SHADE_FACTOR` | Fraction of insolation blocked by shading. | fraction 0 to 1 | 0 | +| `SKY_VIEW` | Fraction of the hemisphere above the water that is sky rather than land cover. | fraction 0 to 1 | 1 | +| `EMISS_WATER` | Longwave emissivity of the water surface. | fraction 0 to 1 | 0.97 | +| `EMISS_LANDCOVER` | Longwave emissivity of the surrounding land cover. | fraction 0 to 1 | 0.97 | +| `LANDCOVER_TEMPERATURE` | Radiating temperature of the land cover. When unset, air temperature is used. | degrees C, any finite value | air temperature | +| `ATM_EMISS_COEFF` | Brunt clear-sky atmospheric emissivity coefficient. GLOBAL only. | fraction 0 to 1 | 0.5 | +| `ATM_LW_REFLECTION` | Longwave reflectance of the water surface. GLOBAL only. | fraction 0 to 1 | 0.03 | + +Remarks: +Every row carries a scope token. `SHORTWAVE`, `ATM_EMISS_COEFF` and +`ATM_LW_REFLECTION` describe the incident resource or the atmosphere and are +refused at any scope but GLOBAL; the six surface parameters accept GLOBAL, +TAG, LINK or NODE, where TAG matches every link and node carrying that value in +`[TAGS]` (@ref engine_manual_sect_TAGS). Precedence is GLOBAL, then TAG, then +the named element. A TAG that matches nothing, an unknown link or node, or two +rows for the same parameter at the same scope and name are errors. The three +`SHORTWAVE` spellings are mutually exclusive: a second `SHORTWAVE` row is an +error, not an override. `COMPUTED` requires `[SOLAR_RADIATION]` `LATITUDE` and +`LONGITUDE` (they are never taken from the `[TEMPERATURE]` snowmelt line) and +takes no further token; `TIMESERIES` names an existing `[TIMESERIES]`. Fractions +are refused outside 0 to 1 rather than clamped, and a non-finite value is +refused. The section has no effect unless `[HEAT_FLUXES] RADIATIVE_EXCHANGE` +is ON. + + + +### Component section: [SOLAR_RADIATION] {#engine_manual_sect_SOLAR_RADIATION} + +Purpose: \status{Implemented} +Gives the site position and the clear-sky atmosphere used when +`[RADIATIVE_FLUXES] SHORTWAVE` is `COMPUTED`. + +Format: +``` +LATITUDE GLOBAL Value +LONGITUDE GLOBAL Value +TIMEZONE GLOBAL Value +ELEVATION GLOBAL Value +TURBIDITY_380 GLOBAL Value +TURBIDITY_500 GLOBAL Value +PRECIP_WATER GLOBAL Value +OZONE GLOBAL Value +GROUND_ALBEDO GLOBAL Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `LATITUDE` | Site latitude, positive north. Required under COMPUTED. | degrees, -90 to 90 | none | +| `LONGITUDE` | Site longitude, positive east. Required under COMPUTED. | degrees, -180 to 180 | none | +| `TIMEZONE` | Offset of the deck's clock from UTC, positive east (for example -7 for MST). | hours, -14 to 14 | 0 (UTC) | +| `ELEVATION` | Site elevation for the atmospheric pressure term. When unset the `[TEMPERATURE]` climate elevation is used. | metres, -500 to 9000 | climate elevation | +| `TURBIDITY_380` | Aerosol optical depth at 380 nm. | value, 0 or greater | 0.30 | +| `TURBIDITY_500` | Aerosol optical depth at 500 nm. | value, 0 or greater | 0.20 | +| `PRECIP_WATER` | Precipitable water vapour column. | cm, 0 or greater | 1.42 | +| `OZONE` | Ozone column at NTP. | cm, 0 or greater | 0.34 | +| `GROUND_ALBEDO` | Albedo of the ground around the site, for the sky-ground multiple-reflection term. This is not the water's `ALBEDO`. | fraction 0 to 1 | 0.20 | + +Remarks: +Every row is exactly `Parameter GLOBAL Value`; there is no per-element scope. +Ranges are refused rather than clamped (a latitude of 100 is a typo, not the +pole), and a non-finite value is refused. The atmosphere defaults are the +Bird and Hulstrom standard atmosphere. The section is consulted only under +`SHORTWAVE GLOBAL COMPUTED`: when coordinates are given under another +`SHORTWAVE` spelling the component warns that they are unused, and when +COMPUTED is in force without a `TIMEZONE` it warns that local time is taken as +UTC, which can shift the computed solar day by up to 12 hours. + + + +### Component section: [CLOUD_COVER] {#engine_manual_sect_CLOUD_COVER} + +Purpose: \status{Implemented} +Gives one cloud fraction that attenuates the shortwave resource and raises the +atmospheric longwave emissivity, with the coefficients of both corrections. + +Format: +``` +FRACTION GLOBAL Value +FRACTION GLOBAL TIMESERIES Name +SW_ATTEN_K GLOBAL Value +SW_ATTEN_N GLOBAL Value +LW_CLOUD_K GLOBAL Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `FRACTION` | Cloud fraction, constant or from a `[TIMESERIES]`. | fraction 0 to 1; or TIMESERIES name | 0 (clear sky) | +| `SW_ATTEN_K` | Kasten-Czeplak shortwave attenuation coefficient k. | value, 0 or greater | 0.75 | +| `SW_ATTEN_N` | Kasten-Czeplak shortwave attenuation exponent n. | value, 0 or greater | 3.4 | +| `LW_CLOUD_K` | Bolz longwave cloud coefficient. | value, 0 or greater | 0.17 | + +Remarks: +Every row is `Parameter GLOBAL Value`; a constant `FRACTION` outside 0 to 1 is +refused (it is a fraction, not a percent), while a `TIMESERIES` value is +clamped at run time. An unknown parameter, a negative coefficient or a +non-finite value is an error. Both corrections are the identity at a fraction +of 0, so a section holding coefficients but no `FRACTION` row has no effect +and the component warns. It also warns when `[CLOUD_COVER]` is combined with +`SHORTWAVE GLOBAL TIMESERIES`, because a measured record already contains its +clouds and would be attenuated twice; the longwave correction still applies. +The section has no effect unless `RADIATIVE_EXCHANGE` is ON. + + + +### Component section: [SEDIMENT_EXCHANGE] {#engine_manual_sect_SEDIMENT_EXCHANGE} + +Purpose: \status{Implemented} +Parameterises the bed zone beneath conduits for `[HEAT_FLUXES] +SEDIMENT_EXCHANGE`: conduction to the bed and the deep ground, and hyporheic +exchange of heat and dissolved species. + +Format: +``` +Parameter GLOBAL Value +Parameter TAG / LINK Name Value +GROUND_TEMPERATURE GLOBAL TIMESERIES Name +INITIAL_TEMPERATURE GLOBAL Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `THERMAL_DIFFUSIVITY` | Bed thermal diffusivity. | m2/s, greater than 0 | 1.0e-6 | +| `SOLUTE_DIFFUSIVITY` | Bed effective solute diffusivity, one value for every species; 0 selects advection-only exchange. | m2/s, 0 or greater | 1.0e-9 | +| `BED_THICKNESS` | Thickness of the bed layer — the conduction length and the bed's heat capacity. | m, greater than 0 | 0.20 | +| `GROUND_DEPTH` | Depth from the bed to the deep-ground boundary. | m, greater than 0 | 2.0 | +| `GROUND_TEMPERATURE` | Deep-ground temperature, constant or (GLOBAL only) from a `[TIMESERIES]`. | degrees C, any finite value; or TIMESERIES name | 12.0 | +| `HYPORHEIC_VELOCITY` | Exchange velocity across the bed interface; 0 means conduction only. Direction follows the gradient, so a negative value is refused. | m/s, 0 or greater | 0 | +| `SEDIMENT_DENSITY` | Bed bulk density. | kg/m3, greater than 0 | 1670 | +| `SEDIMENT_SPECIFIC_HEAT` | Bed specific heat. | J/kg/K, greater than 0 | 1807 | +| `INITIAL_TEMPERATURE` | Initial bed temperature. GLOBAL only. | degrees C, any finite value | the ground temperature | + +Remarks: +The bed exists beneath conduits only, so NODE scope is refused; the first +eight parameters accept GLOBAL, TAG or LINK, with TAG matching every link +carrying that value in `[TAGS]` and precedence GLOBAL, then TAG, then LINK. +`INITIAL_TEMPERATURE` has no per-element form. Lengths, diffusivities and +material properties are refused at or below zero rather than clamped, because +each is a divisor or a capacity in the exchange kernel. A TAG that matches +nothing, an unknown link, a duplicate row at the same scope and name, or a +non-finite value is an error. `GROUND_TEMPERATURE` has a default but is worth +stating, since the ground term is often the largest in a buried pipe. Under +the Eulerian engine every transport cell carries its own bed slice; under the +other engines the bed exchanges with the link's mean temperature. The section +has no effect unless `[HEAT_FLUXES] SEDIMENT_EXCHANGE` is ON. + + + +### Component section: [WATER_AGE_SOURCES] {#engine_manual_sect_WATER_AGE_SOURCES} + +Purpose: \status{Implemented} +Sets the age carried by water entering the network through each source +pathway, globally and per node, for `[OPTIONS] WATER_AGE ON`. + +Format: +``` +Source GLOBAL Hours +Source NODE Node Hours +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `Source` | The inflow pathway: RAINFALL (runoff), DWF, GW, RDII, EXTERNAL_INFLOW (`[INFLOWS]` rows), IFACE (interface-file inflow) or INITIAL_STATE (water in the network at the start). | keyword | required | +| Scope | GLOBAL sets the pathway everywhere; NODE sets it at one node and wins there. | GLOBAL or NODE | required | +| `Node` | Name of an existing node (NODE rows only). | text | required | +| `Hours` | Age of the arriving water. A negative age extracts age-volume (the receiving water reads younger) and is warned; extraction clamps so age never falls below zero. | hours, any number | 0 (fresh) | + +Remarks: +Ages are entered in hours and held internally in seconds. Every pathway +without a row enters fresh. NODE scope is available for DWF and +EXTERNAL_INFLOW only; any other source takes GLOBAL. A row with fewer than +three tokens, an unknown source, an unknown node, a non-numeric age, or a +second NODE row for the same source and node is an error, as is any section +in the file other than this one. SUBCATCH scope ("arrives with plan phase A3") +and EDGE_BC scope ("arrives with phase T6") are refused. A `TIMESERIES` in +place of the value is refused with a redirect: a time-varying inflow age is +written as an `[INFLOWS]` row naming the reserved constituent `__WATER_AGE__` +(@ref engine_manual_sect_INFLOWS), and such a row wins over this table's +EXTERNAL_INFLOW entry at that node. Any error discards the whole water-age +configuration. The component warns when `[OPTIONS] WATER_AGE` is OFF, because +then no age is tracked. A zero-valued GLOBAL row is not written back on save, +since zero is the default. + + + +### Component section: [TRANSPORT_OPTIONS] {#engine_manual_sect_TRANSPORT_OPTIONS} + +Purpose: \status{Implemented} +Configures the Eulerian advection-reaction-dispersion engine selected by +`[OPTIONS] QUALITY_SOLVER EULERIAN_ARD`: the dispersion model, the scalar +advection scheme, the transport mesh and a per-cell diagnostic output. + +Format: +``` +DISPERSION OFF / FISCHER / Value +SCALAR_SCHEME UPWIND / MUSCL / QUICKEST_ULTIMATE +LIMITER MINMOD / VANLEER / SUPERBEE +TARGET_DX Value +DETAILED_OUTPUT Path +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `DISPERSION` | Global longitudinal dispersion model. OFF applies none; FISCHER computes \f$D = 0.011\,v^{2} B^{2} / (Y\,U_{*})\f$ with \f$U_{*} = \sqrt{g Y S}\f$ per cell; a number applies one uniform coefficient. | OFF, FISCHER, or a coefficient in display units of length squared per second (m2/s under SI flow units, ft2/s under US), 0 or greater | OFF | +| `SCALAR_SCHEME` | Face reconstruction of the transported scalars. An alias of `[OPTIONS] FV_SCALAR_SCHEME`; this file wins because the component applies after the options. | UPWIND, MUSCL or QUICKEST_ULTIMATE | MUSCL | +| `LIMITER` | Slope limiter for the higher-order schemes. An alias of `[OPTIONS] FV_LIMITER`. | MINMOD, VANLEER or SUPERBEE | MINMOD | +| `TARGET_DX` | Transport-mesh cell length under non-FV hydraulic routing. Under `FLOW_ROUTING FV` the solver mesh governs and this key is ignored with a warning. | display length units, greater than 0 | 0 (the `FV_CELL_LENGTH` rules) | +| `DETAILED_OUTPUT` | Path of a per-cell CSV sidecar written during the run. A relative path resolves against the directory of the component file, not the `.inp`. | path | none | + +Remarks: +Keys are case-insensitive and each takes exactly one argument; an unknown key +or a malformed value is an error, and any error discards the whole transport +configuration. Per-conduit dispersion overrides are given in the companion +section `[CONDUIT_DISPERSION]` of the same file, one `Conduit Value` row each +(non-conduit links and duplicate rows are refused); an override wins over the +global model in its conduit, including when `DISPERSION` is OFF. A +`[STORAGE_MIXING]` section is recognised and refused ("arrives with plan phase +E2b"). Because `SCALAR_SCHEME` and `LIMITER` write through to the `[OPTIONS]` +values and the `.inp` writer emits `FV_*` keys only under `FLOW_ROUTING FV`, +this file is the carrier of those choices across a save on a non-FV deck; a +file that never spelled the alias never gains one. `[OPTIONS] FV_DISPERSION` +does not configure this engine and is warned about when set. The component +warns at open whenever its content can reach nothing: `IGNORE_QUALITY YES`, a +`QUALITY_SOLVER` other than `EULERIAN_ARD`, or dispersion configured with no +`[POLLUTANTS]` and no reactions component. + + + +### Component section: [CONDUIT_DISPERSION] {#engine_manual_sect_CONDUIT_DISPERSION} + +Purpose: +\status{Implemented} Overrides, for individual conduits, the longitudinal +dispersion coefficient the Eulerian ARD engine takes from +`[TRANSPORT_OPTIONS] DISPERSION`. + +Format: +``` +Conduit Value +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| Conduit | Name of an existing conduit. A pump, orifice, weir or outlet is refused: structures are zero-volume pass-throughs and carry no dispersion. | link name | — | +| Value | Longitudinal dispersion coefficient for that conduit. | project length squared per second, finite and non-negative | the `[TRANSPORT_OPTIONS] DISPERSION` value | + +Remarks: +One row per conduit; a second row for the same conduit is an error. Rows are +validated when the component configuration is applied, so an unknown link +name fails the open (or, under a lenient open, discards the whole +configuration). See quality §7.3.3 for how the coefficient enters the +implicit dispersion update. + + + +### Component section: [STORAGE_MIXING] {#engine_manual_sect_STORAGE_MIXING} + +Purpose: +\status{Planned} Per-storage-node mixing models for the Eulerian ARD engine. +The section name is recognised by the parser, and any content under it is +refused with an error naming the plan phase that delivers it (E2b); leave the +section out of a configuration file. + +Format: +``` +(no rows are accepted this release) +``` + +Remarks: +Storage nodes are complete-mix reactors under every transport engine in this +release (quality §7.3). The section is listed here so that a file carrying it +is understood rather than mistaken for a typo. + + + +### Component section: [TRANSPORT_BOUNDARIES] {#engine_manual_sect_TRANSPORT_BOUNDARIES} + +Purpose: \status{Implemented} +Sets the concentration of a reaction species carried by the external inflow +water entering at a node, under the Eulerian engine. + +Format: +``` +Node Species VALUE Concentration +Node Species TIMESERIES Name +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `Node` | Name of an existing node. | text | required | +| `Species` | A species declared in the reactions component's `[REACTION_SPECIES]`. | text | required | +| Mode | VALUE gives a constant; TIMESERIES names a `[TIMESERIES]` of concentrations. | VALUE or TIMESERIES | required | +| `Concentration`, `Name` | The constant concentration in the species' own units, or the series name. | value, 0 or greater; or text | required | + +Remarks: +Every row is exactly four tokens; a mode other than VALUE or TIMESERIES, or a +negative or non-numeric VALUE, is an error at parse. The node, the species and +the series are resolved after every component has applied, so the reactions +row may precede or follow the transport row in `[PROCESS_COMPONENTS]`; an +unknown node, an unknown series, an undeclared species, or a second row for +the same node and species is then an error. A `[POLLUTANTS]` name is refused: +pollutants keep their `[INFLOWS]`, dry-weather and washoff loading pathways, +and allowing them here would double-count. The concentration applies to the +node's external inflow water only; it is not a fixed concentration at the +node. Rows are inert, with a warning, unless `QUALITY_SOLVER` is +`EULERIAN_ARD` and `IGNORE_QUALITY` is NO. + + + +### Component section: [TRANSPORT_SOURCES] {#engine_manual_sect_TRANSPORT_SOURCES} + +Purpose: \status{Implemented} +Applies a distributed mass rate of a reaction species along a conduit, +independent of its flow, under the Eulerian engine. A negative rate extracts. + +Format: +``` +Conduit Species VALUE Rate +Conduit Species TIMESERIES Name +``` + +Parameters: + +| Parameter | Meaning | Units / values | Default | +|---|---|---|---| +| `Conduit` | Name of an existing conduit. Other link types are refused. | text | required | +| `Species` | A species declared in the reactions component's `[REACTION_SPECIES]`. | text | required | +| Mode | VALUE gives a constant; TIMESERIES names a `[TIMESERIES]` of rates. | VALUE or TIMESERIES | required | +| `Rate`, `Name` | The constant mass rate in the species' mass units per second, or the series name. | value, any sign; or text | required | + +Remarks: +Every row is exactly four tokens; a mode other than VALUE or TIMESERIES, or a +non-numeric VALUE, is an error at parse. The conduit, the species and the +series are resolved after every component has applied; a link that is not a +conduit, an unknown series, an undeclared species, a `[POLLUTANTS]` name, or a +second row for the same conduit and species is then an error. The rate is +spread over the conduit's cells in proportion to cell length. A negative VALUE +is accepted as extraction and warned once at open; a series that dips negative +extracts likewise. Extraction is clamped to the mass the cells actually hold, +and the unmet portion is counted and summarised at the end of the run. The +mass rate is converted internally by dividing by 28.316846592 litres per cubic +foot, since the engine's store is concentration times cubic feet. Rows are +inert, with a warning, unless `QUALITY_SOLVER` is `EULERIAN_ARD` and +`IGNORE_QUALITY` is NO. + + diff --git a/docs/manuals/engine/sections/Chapter3-Files.md b/docs/manuals/engine/sections/Chapter3-Files.md new file mode 100644 index 000000000..6dbf927d4 --- /dev/null +++ b/docs/manuals/engine/sections/Chapter3-Files.md @@ -0,0 +1,299 @@ +@page engine_manual_ch3_files CHAPTER 3 - Files and Command-Line Operation + +@tableofcontents + +This section describes the various files that SWMM can utilize. They include: the project file, the report and output files, rainfall files, the climate file, calibration data files, time series files, and interface files. The only file required to run SWMM is the project file; the others are optional. + +## Project Files + +A SWMM project file is a plain text file that contains all of the data used to describe a study area and the options used to analyze it. The file is organized into sections, where each section generally corresponds to a particular category of object used by SWMM. Its full format is given in @ref engine_manual_ch2_input_file. + +Normally a SWMM user would not edit the project file directly, since SWMM's graphical user interface can add, delete, or modify a project's data and control settings. However, for large projects where data currently reside in other electronic formats, such as CAD or GIS files, it may be more expeditious to extract data from these sources and save it to a formatted project file before running SWMM. The format of the project file is described in detail in Appendix D of this manual. + +After a project file is saved to disk, a settings file will automatically be saved with it. This file has the same name as the project file except that its extension is .ini (e.g., if the project file were named project1.inp then its settings file would have the name project1.ini). It contains various settings used by SWMM’s graphical user interface, such as map display options, legend colors and intervals, object default values, and calibration file information. Users should not edit this file. A SWMM project will still load and run even if the settings file is missing. + +## Report and Output Files + +The report file is a plain text file created after every SWMM run that contains the contents of both the Status Report and all of the tables included in the Summary Results report. Refer to Sections 9.1 and 9.2 to review their contents. + +The output file is a binary file that contains the numerical results from a successful SWMM run. This file is used by SWMM’s user interface to interactively create time series plots and tables, profile plots, and statistical analyses of a simulation's results. + +Whenever a successfully run project is either saved or closed, the report and output files are saved with the same name as the project file, but with extensions of .rpt and .out. This will happen automatically if the program preference Prompt to Save Results is turned off (see @ref manual_preferences). Otherwise the user is asked if the current results should be saved or not. If results are saved then the next time the project is opened, the results from these files will automatically be available for viewing. + +## Rainfall Files + +SWMM’s rain gage objects can utilize rainfall data stored in external rainfall files. The program currently recognizes the following formats for storing such data: +- Hourly and fifteen minute precipitation data from over 5,500 reporting stations retrieved using NOAA’s National Centers for Environmental Information (NCEI) Climate Data Online service (www.ncdc.noaa.gov/cdo-web) (space-delimited text format only). +- The older DS-3240 and related formats used for hourly precipitation by NCEI. +- The older DS-3260 and related formats used for fifteen minute precipitation by NCEI. +- HLY03 and HLY21 formats for hourly rainfall at Canadian stations, available from Environment Canada at www.climate.weather.gc.ca. +- FIF21 format for fifteen minute rainfall at Canadian stations, also available online from Environment Canada. +- a standard user-prepared format where each line of the file contains the station ID, year, month, day, hour, minute, and non-zero precipitation reading, all separated by one or more spaces. + +When requesting data from NCEI’s online service, be sure to specify the TEXT format option, make sure that the data flags are included, and, for 15-minute data, select the QPCP option and not the QGAG one. + +An excerpt from a sample user-prepared Rainfall file is as follows: +STA01 2004 6 12 00 00 0.12 +STA01 2004 6 12 01 00 0.04 +STA01 2004 6 22 16 00 0.07 +This format can also accept multiple stations within the same file. +When a rain gage is designated as receiving its rainfall data from a standard user-prepared format, the following properties must be supplied for it: the name of the recording station referenced in the file, the rainfall type (e.g., intensity or volume), the recording time interval, and rainfall depth units. For the other file types these properties are defined by their respective file format and are automatically recognized by SWMM. + +## Climate Files + +SWMM can use an external climate file that contains daily air temperature, evaporation, and wind speed data. The program currently recognizes the following formats: +- Global Historical Climatology Network - Daily (GHCN-D) files (TEXT output format) available from NOAA's National Climatic Data Center (NCDC) Climate Data Online service at www.ncdc.noaa.gov/cdo-web. +- Older NCDC DS-3200 or DS-3210 files. +- Canadian climate files available from Environment Canada at www.climate.weather.gc.ca. +- A user-prepared climate file where each line contains a recording station name, the year, month, day, maximum temperature, minimum temperature, and optionally, evaporation rate, and wind speed. If no data are available for any of these items on a given date, then an asterisk should be entered as its value. +When a climate file has days with missing values, SWMM will use the value from the most recent previous day with a recorded value. + +- For a user-prepared climate file, the data must be in the same units as the project being analyzed. For US units, temperature is in degrees F, evaporation is in inches/day, and wind speed is in miles/hour. For metric units, temperature is in degrees C, evaporation is in mm/day, and wind speed is in km/hour. + +## Calibration Files + +Calibration files contain measurements of variables at one or more locations that can be compared with simulated values in Time Series Plots. Separate files can be used for each of the following: +- Subcatchment Runoff +- Subcatchment Groundwater Flow +- Subcatchment Groundwater Elevation +- Subcatchment Snow Pack Depth +- Subcatchment Pollutant Washoff +- Node Depth +- Node Lateral Inflow +- Node Flooding +- Node Water Quality +- Link Flow +- Link Velocity +- Link Depth +Calibration files are named by the client that loads them; the engine itself neither reads nor writes them. + +The format of the file is as follows: +- The name of the first object with calibration data is entered on a single line. +- Subsequent lines contain the following recorded measurements for the object: +- measurement date (month/day/year, e.g., 6/21/2004) or number of whole days since the start of the simulation +- measurement time (hours:minutes) on the measurement date or relative to the number of elapsed days +- measurement value (for pollutants, a value is required for each pollutant). +- Follow the same sequence for any additional objects. +An excerpt from an example calibration file is shown below. It contains flow values for two conduits: 1030 and 1602. Note that a semicolon can be used to begin a comment. In this example, elapsed time rather than the actual measurement date was used. + + + + + + + + + +;Flows for Selected Conduits +;Conduit Days Time Flow +;----------------------------- + 1030 +- 0 0:15 0 +- 0 0:30 0 +- 0 0:45 23.88 +- 0 1:00 94.58 +- 0 1:15 115.37 + 1602 +- 0 0:15 5.76 +- 0 0:30 38.51 +- 0 1:00 67.93 +- 0 1:15 68.01 + + + +## Time Series Files + +Time series files are external text files that contain data for SWMM's time series objects. Examples of time series data include rainfall, evaporation, inflows to nodes of the drainage system, and water stage at outfall boundary nodes. The file must be created and edited outside of SWMM, using a text editor or spreadsheet program. A time series file can be linked to a specific time series object using SWMM's Time Series Editor (see @ref manual_hydraulics). + +The format of a time series file consists of one time series value per line. Comment lines can be inserted anywhere in the file as long as they begin with a semicolon. Time series values can either be in date / time / value format or in time / value format, where each entry is separated by one or more spaces or tab characters. For the date / time / value format, dates are entered as month/day/year (e.g., 7/21/2004) and times as 24-hour military time (e.g., 8:30 pm is 20:30). After the first date, additional dates need only be entered whenever a new day occurs. For the time / value format, time can either be decimal hours or military time since the start of a simulation (e.g., 2 days, 4 hours and 20 minutes can be entered as either 52.333 or 52:20). An example of a time series file is shown below: + + + + + + +;Rainfall Data for Gage G1 +07/01/2003 00:00 0.00000 +- 00:15 0.03200 +- 00:30 0.04800 +- 00:45 0.02400 +- 01:00 0.0100 +07/06/2003 14:30 0.05100 +- 14:45 0.04800 +- 15:00 0.03000 +- 18:15 0.01000 +- 18:30 0.00800 + + +- In earlier releases of SWMM 5, a time series file was required to have two header lines of descriptive text at the start of the file that did not have to begin with the semicolon comment character. These files can still be used as long as they are modified by inserting a semicolon at the front of the first two lines. +- When preparing rainfall time series files, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage which utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values. + +## Interface Files + +SWMM can use several different kinds of interface files that contain either externally imposed inputs (e.g., rainfall or RDII hydrographs) or the results of previously run analyses (e.g., runoff or routing results). These files can help speed up simulations, simplify comparisons of different loading scenarios, and allow large study areas to be broken up into smaller areas that can be analyzed individually. The different types of interface files that are currently available include: +- rainfall interface file +- runoff interface file +- hot start file +- RDII interface file +- routing interface files +Consult @ref engine_manual_sect_OPTIONS for instructions on how to specify interface files for use as input and/or output in a simulation. + +## Rainfall and Runoff Files + +The rainfall and runoff interface files are binary files created internally by SWMM that can be saved and reused from one analysis to the next. + +The rainfall interface file collates a series of separate rain gage files into a single rainfall data file. Normally a temporary file of this type is created for every SWMM analysis that uses external rainfall data files and is then deleted after the analysis is completed. However, if the same rainfall data are being used with many different analyses, requesting SWMM to save the rainfall interface file after the first run and then reusing this file in subsequent runs can save computation time. + +- The rainfall interface file should not be confused with a rainfall data file. The latter is an external text file that provides rainfall time series data for a single rain gage. The former is a binary file created internally by SWMM that processes all of the rainfall data files used by a project. + +The runoff interface file can be used to save the runoff results generated from a simulation run. If runoff is not affected in future runs, the user can request that SWMM use this interface file to supply runoff results without having to repeat the runoff calculations again. + +## Hot Start Files + +Hot start files are binary files created by SWMM that contain the full hydrologic, hydraulic and water quality state of the study area at the end of a run. The following information is saved to the file: +- the ponded depth and its water quality for each subcatchment +- the pollutant mass buildup on each subcatchment +- the infiltration state of each subcatchment +- the conditions of any snowpack on each subcatchment +- the unsaturated zone moisture content, water table elevation, and groundwater outflow for each subcatchment that has a groundwater zone defined for it +- the water depth, lateral inflow, and water quality at each node of the system +- the flow rate, water depth, control setting and water quality in each link of the system. +The hydrologic state of any LID units is not saved. The hot start file saved after a run can be used to define the initial conditions for a subsequent run. + +Hot start files can be used to avoid the initial numerical instabilities that sometimes occur under Dynamic Wave routing. For this purpose they are typically generated by imposing a constant set of base flows (for a natural channel network) or set of dry weather sanitary flows (for a sewer network) over some startup period of time. The resulting hot start file from this run is then used to initialize a subsequent run where the inflows of real interest are imposed. + +It is also possible to both use and save a hot start file in a single run, starting off the run with one file and saving the ending results to another. The resulting file can then serve as the initial conditions for a subsequent run if need be. This technique can be used to divide up extremely long continuous simulations into more manageable pieces. + +Hot start files are named in the [FILES] section — see @ref engine_manual_sect_FILES. A file saved mid-run rather than at the end holds only node, link and groundwater state. + +## RDII Files + +The RDII interface file contains a time series of rainfall-dependent infiltration and inflow flows for a specified set of drainage system nodes. This file can be generated from a previous SWMM run when Unit Hydrographs and nodal RDII inflow data have been defined for the project, or it can be created outside of SWMM using some other source of RDII data (e.g., through measurements or output from a different computer program). RDII files generated by SWMM are saved in a binary format. RDII files created outside of SWMM are text files with the same format used for routing interface files discussed below, where Flow is the only variable contained in the file. + +## Routing Files + +A routing interface file stores a time series of flows and pollutant concentrations that are discharged from the outfall nodes of drainage system model. This file can serve as the source of inflow to another drainage system model that is connected at the outfalls of the first system. A Combine utility is available on the File menu that will combine pairs of routing interface files into a single interface file. This allows very large systems to be broken into smaller sub-systems that can be analyzed separately and linked together through the routing interface file. Figure 11.1 below illustrates this concept. + + + + + + + + + + + + + + + + + + + + +A single SWMM run can utilize an outflows routing file to save results generated at a system's outfalls, an inflows routing file to supply hydrograph and pollutograph inflows at selected nodes, or both. + +## RDII / Routing File Format + +RDII interface files and routing interface files have the same text format: +- the first line contains the keyword "SWMM5" (without the quotes) +- a line of text that describes the file (can be blank) +- the time step used for all inflow records (integer seconds) +- the number of variables stored in the file, where the first variable must always be flow rate +- the name and units of each variable (one per line), where flow rate is the first variable listed and is always named FLOW +- the number of nodes with recorded inflow data +- the name of each node (one per line) +- a line of text that provides column headings for the data to follow (can be blank) +- for each node at each time step, a line with: +- the name of the node +- the date (year, month, and day separated by spaces) +- the time of day (hours, minutes, and seconds separated by spaces) +- the flow rate followed by the concentration of each quality constituent +Time periods with no values at any node can be skipped. An excerpt from an RDII / routing interface file is shown below. + + +SWMM5 +Example File +300 +1 +FLOW CFS +2 +N1 +N2 +Node Year Mon Day Hr Min Sec Flow +N1 2002 04 01 00 20 00 0.000000 +N2 2002 04 01 00 20 00 0.002549 +N1 2002 04 01 00 25 00 0.000000 +N2 2002 04 01 00 25 00 0.002549 + +## 2D Mesh Files + +A two-dimensional surface is described by the `[2D_*]` sections of +@ref engine_manual_ch2_input_file §2.4. Because a mesh can run to hundreds of +thousands of cells, those sections may live in a separate file that the +project references with a single row: + +``` +[2D_MESH_FILE] +FILE meshes/city_basin.2dm +``` + +The path is absolute or relative to the directory of the project file. The +mesh file uses the same bracketed-section dialect as the project file, and the +sections it carries are read as if they appeared in the project itself, so the +same mesh can be shared by several projects. Grammar and rules are in +@ref engine_manual_sect_2D_MESH_FILE. + +## 2D Results Files + +When a project carries a mesh, the two-dimensional results are written to a +separate HDF5 file named by `[2D_OPTIONS] OUTPUT_FILE` rather than to the +binary output file. The file follows the CF-1.11 and UGRID-1.0 conventions +(its `Conventions` attribute says so), so it opens in any UGRID-aware reader +and in `h5py`: + +- **Mesh topology**, written once: `Mesh2_node_x`, `Mesh2_node_y`, + `Mesh2_node_z`, the face–node connectivity `Mesh2_face_nodes` with the + vertex count per face `Mesh2_face_nv` (3 or 4), the face centroids + `Mesh2_face_x`, `Mesh2_face_y`, `Mesh2_face_z`, the per-face roughness + `Mesh2_face_mannings_n` and area `Mesh2_face_area`, and the edge geometry + `Mesh2_edge_length`, `Mesh2_edge_nx`, `Mesh2_edge_ny`. +- **Time**, an unlimited `time` dataset, advanced every `REPORT_2D_STEP` + (or every report step when that key is absent). +- **Per-face series**, one frame per time: `Mesh2_face_depth` and + `Mesh2_face_head` always; `Mesh2_face_vx`, `Mesh2_face_vy`, + `Mesh2_face_rainfall`, `Mesh2_face_rain_cum`, `Mesh2_face_infil_rate`, + `Mesh2_face_infil_cum`, `Mesh2_face_coupling_flux`, `Mesh2_face_net_source`, + the gradient fields `Mesh2_face_grad_hx`, `Mesh2_face_grad_hy` and their + limited counterparts, `Mesh2_face_continuity_err`, and the species field + `Mesh2_face_species_conc` (faces × species) — each present only when its + group is selected by `REPORT_2D_VARIABLES`. +- **Groundwater**, when the mesh carries an aquifer and the `GROUNDWATER` + group is selected: `Mesh2_face_gw_table_elev`, `Mesh2_face_gw_hg` + (saturated thickness), `Mesh2_face_gw_hu` (unsaturated storage), + `Mesh2_face_gw_recharge`, `Mesh2_face_gw_lateral`, + `Mesh2_face_gw_node_exchange`, `Mesh2_face_gw_deep`, `Mesh2_face_gw_et`, + `Mesh2_face_gw_dunne` and `Mesh2_face_gw_infil_in`, with the static + `Mesh2_face_gw_bed_elev` and `Mesh2_face_gw_closure`; the `GW_DETAILED` + group adds the σ-column moisture profile `Mesh2_face_gw_theta_sigma` + (faces × layers). Each dataset carries its meaning and unit as attributes. + +`OUTPUT_PRECISION FLOAT32` halves the file at the cost of single-precision +series; `OUTPUT_COMPRESSION 1`–`9` enables gzip chunk compression. The file is +written with a single writer and is not flushed until the run ends, so it +cannot be read while the simulation is still running. The keys are documented +in @ref engine_manual_sect_2D_OPTIONS; the meaning of each series is in +@ref hydraulics_ref_ch9_two_dimensional §9.9. + +## Process Component Configuration Files + +Reaction systems, the Eulerian transport engine, heat transport and water-age +tracking are configured in their own files, named in the project's +`[PROCESS_COMPONENTS]` section and conventionally suffixed `.rxn`, `.ard`, +`.heat` and `.age`. Each file uses the bracketed-section dialect of the +project file; the sections each component accepts are documented in +@ref engine_manual_ch2_input_file §2.5. On save, every component writes its +configuration back to its file, and a save-as carries the files alongside +the written project. diff --git a/docs/manuals/engine/sections/Chapter4-Reports.md b/docs/manuals/engine/sections/Chapter4-Reports.md new file mode 100644 index 000000000..260631e52 --- /dev/null +++ b/docs/manuals/engine/sections/Chapter4-Reports.md @@ -0,0 +1,220 @@ +@page engine_manual_ch4_reports CHAPTER 4 - Status Report; Summary Tables and Output + +@tableofcontents + +This chapter describes what the engine writes after a run: the status report, the summary tables, and the time-series variables saved to the binary output file. How a client displays them — on a map, as a plot, as a table — is covered by @ref manual_results and @ref manual_tabular_results. + +## 4.1 The Status Report + +A Status Report is available for viewing after each simulation. It contains: +- a summary of the main Simulation Options that are in effect +- a list of any error and warning conditions encountered during the run +- a summary listing of the project’s input data (if requested in the Simulation Options) +- a summary of the data read from each rainfall file used in the simulation +- a description of each control rule action taken during the simulation (if requested in the Simulation Options) +- the system-wide mass continuity errors for: +- runoff quantity and quality +- groundwater flow +- conveyance system flow and water quality +- the two-dimensional surface and the two-dimensional aquifer, when the project carries a mesh (the *2D Surface Routing Continuity* and *2D Aquifer Continuity* blocks) +- solver statistics for the finite-volume and two-dimensional solvers: substeps, flux evaluations, local-time-stepping cycles fired and rejected, and the active fraction of faces or cells (the *FV Solver Statistics* and *2D Solver Statistics* blocks) +- when transport species are enabled, which species classes are carried on each domain; and, when the project carries `[GW_*]` sections, the warning that they are authored but inert this release +- the names of the nodes with the highest individual flow continuity errors +- the names of the conduits that most often determined the size of the time step used for flow routing (only when the Variable Time Step option is used) +- the names of the links with the highest Flow Instability Index values +- the names of the nodes with the highest frequency of non-convergence +- information on the range of routing time steps taken and the percentage of these that were considered steady state. + +## 4.2 Summary Tables + + +The engine writes the following tables to the `.rpt` file. Items marked with an asterisk are also available as per-object time series in the binary output file, so a client can colour a map or draw a plot from them. + + + + + + +Table Columns +Subcatchment Runoff Total precipitation (in or mm)* +Total run-on from other subcatchments (in or mm) +Total evaporation (in or mm)* +Total infiltration (in or mm)* +Total runoff depth from impervious areas (in or mm) +Total runoff depth from pervious areas (in or mm) +Total runoff depth (in or mm)* +Total runoff volume (million gallons or million liters) +Peak runoff (flow units)* +Runoff coefficient (ratio of total runoff to total precipitation)* +LID Performance +- Total inflow volume +Total evaporation loss +Total infiltration loss +Total surface outflow +Total underdrain outflow +Initial storage volume +Final storage volume +Flow continuity error (%) +Note: all quantities are expressed as depths (in or mm) over the LID unit’s surface area. +Groundwater Summary Total surface infiltration (in or mm) +Total evaporation (in or mm) +Total lower seepage (in or mm) +Total lateral outflow (in or mm) +Maximum lateral outflow (flow units) +Average upper zone moisture content (volume fraction) +Average water table elevation (ft or m) +Final upper zone moisture content (volume fraction) +Final water table elevation (ft or m) +Subcatchment Washoff +- Total mass of each pollutant washed off the subcatchment (lbs or kg) + + +Node Depth +- Average water depth (ft or m) +Maximum water depth (ft or m)* +Maximum hydraulic head (HGL) (ft or m)* +Time of maximum depth +Maximum water depth at reporting times (ft or m) +Node Inflow Maximum lateral inflow (flow units)* +Maximum total inflow (flow units) +Time of maximum total inflow +Total lateral inflow volume (million gallons or million liters)* +Total inflow volume (million gallons or million liters) +Flow balance error (%) +Note: Total inflow consists of lateral inflow plus inflow from connecting links. +Node Surcharge Hours surcharged +Maximum height of surcharge above node’s crown (ft or m) +Minimum depth of surcharge below node’s top rim (ft or m) +Note: surcharging occurs when water rises above the crown of the highest conduit and only those conduits that surcharge are listed. +Node Flooding Hours flooded* +Maximum flooding rate (flow units)* +Time of maximum flooding +Total flood volume (million gallons or million liters)* +Peak depth (for dynamic wave routing in ft or m) or peak volume (1000 ft3 or 1000 m3) of ponded surface water +Note: flooding refers to all water that overflows a node, whether it ponds or not, and only those nodes that flood are listed. +Storage Volume Average volume of water in the facility (1000 ft3 or 1000 m3) +Average percent of full storage capacity utilized +Percent of total stored volume lost to evaporation +Percent of total stored volume lost to seepage +Maximum volume of water in the facility (1000 ft3 or 1000 m3) +Maximum percent of full storage capacity utilized +Time of maximum water stored +Maximum outflow rate from the facility (flow units) +Outfall Loading Percent of time that outfall discharges +Average discharge flow (flow units) +Maximum discharge flow (flow units) +Total volume of flow discharged (million gallons or million liters) +Total mass discharged of each pollutant (lbs or kg) +Street Flow +(Street Conduits Only) Peak flow (flow units) +Maximum spread from curb (ft or m) +Maximum depth at curb (ft or m) +For streets with assigned inlets +- name of inlet structure +- inlet location (on-grade or on-sag) +- peak flow capture efficiency (%) +- average flow capture efficiency (%) +- frequency of bypass flow (%) +- frequency of backflow (%) +Link Flow Maximum flow (flow units)* +Time of maximum flow +Maximum velocity (ft/sec or m/sec)* +Ratio of maximum flow to full normal flow +Ratio of maximum flow depth to full depth* +Flow Classification +(Dynamic Wave + Routing Only) Ratio of adjusted conduit length to actual length +Fraction of all time steps spent in the following flow categories: +- dry on both ends +- dry on the upstream end +- dry on the downstream end +- subcritical flow +- supercritical flow +- critical flow at the upstream end +- critical flow at the downstream end +Fraction of all time steps flow is limited to normal flow +Fraction of all time steps flow is inlet controlled (for culverts only) +Conduit Surcharge Hours that conduit is full at: +- both ends* +- upstream end +- downstream end +Hours that conduit flows above full normal flow +Hours that conduit is capacity limited* + +Note: only conduits with one or more non-zero entries are listed and a conduit is considered capacity limited if its upstream end is full and the HGL slope is greater than the conduit slope. +Link Pollutant Loads Total mass load (in lbs or kg) of each pollutant carried by the link over the entire simulation period +Pumping Percent of time that the pump is on line +Number of pump start-ups +Minimum flow pumped (flow units) +Average flow pumped (flow units) +Maximum flow pumped (flow units) +Total volume pumped (million gallons or million liters) +Total energy consumed assuming 100% efficiency (Kw-hrs) +Percent of time that the pump operates below its pump curve +Percent of time that the pump operates above its pump curve + +- The summary results displayed in these tables are based on results found at every computational time step and not just on the results from each reporting time step. + + + +### Tables Added by OpenSWMM + +| Table | Written when | Contents | +|---|---|---| +| Slot Storage Summary | `SURCHARGE_METHOD SLOT` or `DYNAMIC_SLOT`, or `FLOW_ROUTING FV` | Run-averaged and peak share of stored volume held in the Preissmann slot (%), hours with a share above 1 %, and the peak and run share per link (hydraulics §3.3.9, §8.7.1). | +| Virtual Junction Summary | the project has `[VIRTUAL_JUNCTIONS]` | For each virtual junction its upstream and downstream conduit and the maximum and mean momentum residual across the splice (hydraulics §3.3.10, §8.6.2). | +| FV Solver Statistics | `FLOW_ROUTING FV` | Explicit substeps, face flux evaluations, average, minimum and last substep, local-time-stepping macro cycles fired and rejected, and the active-face fraction (hydraulics §8.7). | +| 2D Surface Routing Continuity | the project carries a mesh | Initial stored volume, rainfall inflow, 1D→2D spill inflow, outfall and boundary inflow, 2D→1D drain outflow, outfall withdrawal, boundary outflow, evaporation and infiltration losses with the share delivered to (and in flight to) the aquifer, final stored volume, continuity error. | +| 2D Aquifer Continuity | the mesh carries an aquifer | Initial stored volume, infiltration inflow, lateral net inflow, deep percolation, node exchange outflow, subsurface ET, saturation-excess return, final stored volume, recharge and capillary rise as internal transfers, continuity error. | +| 2D Solver Statistics | the project carries a mesh | Internal steps, face-kernel evaluations, average and last internal step, active-cell fraction (hydraulics §9.9). | +| Subcatchment MSX Washoff Summary | MSX species carry buildup and washoff | Mass washed off per subcatchment and species. | +| 2D Surface Washoff Summary | the mesh carries `[2D_COVERAGES]` | Per species: initial buildup, net buildup, washed off, swept, removed by BMPs and remaining on the mesh; the cell and land-use counts and the buildup basis (per hectare or acre). | + +## 4.3 Time-Series Output Variables + +The engine writes a value for each variable below at every reporting time step, for every subcatchment, node and link selected for detailed reporting. That is all of them unless the [REPORT] section names a subset. The values go to the binary output file described in @ref engine_manual_ch3_files, which is what a client reads to plot, tabulate or animate results. + +**Table 4-1 — Time-series output variables** +Subcatchment Variables +- rainfall rate (in/hr or mm/hr) +- snow depth (in or mm) +- evaporation loss ( in/day or mm/day) +- infiltration loss (in/hr or mm/hr) +- runoff flow (flow units) +- groundwater flow into the drainage network (flow units) +- groundwater elevation (ft or m) +- soil moisture in the unsaturated groundwater zone (volume fraction) +- washoff concentration of each pollutant (mass/liter) + +Node Variables +- water depth (ft or m above the node invert elevation) +- hydraulic head (ft or m, absolute elevation per vertical datum) +- stored water volume (including ponded water, ft3 or m3) +- lateral inflow (runoff + all other external inflows, in flow units) +- total inflow (lateral inflow + upstream conduit inflows, in flow units) +- surface flooding (excess overflow when the node is at full depth, in flow units) +- concentration of each pollutant after any treatment applied at the node (mass/liter) Link Variables +- flow rate (flow units) +- average water depth (ft or m) +- flow velocity (ft/sec or m/sec) +- volume of water (ft3 or m3) +- capacity (fraction of full area filled by flow for conduits; control setting for pumps and regulators) +- concentration of each pollutant (mass/liter) + + +System-Wide Variables +- air temperature (degrees F or C) +- potential evaporation (in/day or mm/day) +- actual evaporation (in/day or mm/day) +- total rainfall (in/hr or mm/hr) +- total snow depth (in or mm) +- average losses (in/hr or mm/hr) +- total runoff flow (flow units) +- total dry weather inflow (flow units) +- total groundwater inflow (flow units) +- total RDII inflow (flow units) +- total direct inflow (flow units) +- total external inflow (flow units) +- total external flooding (flow units) +- total outflow from outfalls (flow units) +- total nodal storage volume ( ft3 or m3) diff --git a/docs/manuals/engine/sections/Chapter5-ProgrammaticApi.md b/docs/manuals/engine/sections/Chapter5-ProgrammaticApi.md new file mode 100644 index 000000000..c0f453a1e --- /dev/null +++ b/docs/manuals/engine/sections/Chapter5-ProgrammaticApi.md @@ -0,0 +1,568 @@ +@page engine_manual_ch5_api CHAPTER 5 - Programmatic C API; Python Bindings and Plugins + +@tableofcontents + +OpenSWMM Engine v6 provides a comprehensive C API for building, running, and querying SWMM models entirely through code, without requiring an input file. This is useful for embedding SWMM in larger simulation frameworks, coupling with other models, or building custom user interfaces. + +## 5.1 Architecture Overview + +The new engine uses an opaque handle (`SWMM_Engine`) that encapsulates all simulation state. This reentrant design allows multiple independent simulations to run within the same process. The engine progresses through a well-defined lifecycle: + +``` +CREATED → OPENED → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED +``` + +When a model is constructed programmatically (no input file), the engine instead begins in a `BUILDING` state and `swmm_finalize_model()` transitions it directly to `INITIALIZED`: + +``` +[BUILDING] → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED +``` + +All API functions return an integer error code (`SWMM_OK` on success) and are organized by domain into separate headers; the master header @ref openswmm_engine.h pulls in all of them: + +| Header | Domain | +|---|---| +| `openswmm_engine.h` | Engine lifecycle, error codes, state machine, timing, master include | +| `openswmm_model.h` | Model building, validation, serialization, options, user flags, `[PLUGINS]`/`[FILES]` access | +| `openswmm_nodes.h` | Junction, outfall, storage, and divider nodes | +| `openswmm_links.h` | Conduit, pump, orifice, weir, and outlet links | +| `openswmm_subcatchments.h` | Subcatchments and infiltration | +| `openswmm_gages.h` | Rain gages | +| `openswmm_pollutants.h` | Pollutants and their properties | +| `openswmm_tables.h` | Time series, curves, and patterns | +| `openswmm_inflows.h` | External inflows, DWF, and RDII | +| `openswmm_controls.h` | Control rules | +| `openswmm_infrastructure.h` | Transects, streets, inlets, LID controls | +| `openswmm_spatial.h` | CRS, coordinates, polylines, polygons | +| `openswmm_quality.h` | Landuse, buildup/washoff, treatment | +| `openswmm_initial_quality.h` | `[INITIAL_QUALITY]` per-element initial concentrations | +| `openswmm_reactions.h` | Multi-species reaction system, expression validation, `.rxn` text | +| `openswmm_process_components.h` | `[PROCESS_COMPONENTS]` registrations and config paths | +| `openswmm_water_age.h` | `[WATER_AGE_SOURCES]` source ages and node overrides | +| `openswmm_heat.h` | Heat-transport fluxes, solar/cloud forcing, `[HEAT_SOURCES]` | +| `openswmm_infil2d.h` | 2-D surface infiltration cells, defaults, and totals | +| `openswmm_massbalance.h` | Continuity errors and flux totals | +| `openswmm_statistics.h` | Post-run node/link/pump statistics | +| `openswmm_forcing.h` | Runtime forcing overrides | +| `openswmm_climate.h` | Evaporation, temperature, snowmelt, adjustments | +| `openswmm_edit.h` | Object rename, delete, convert, impact analysis | +| `openswmm_datetime.h` | SWMM DateTime encode/decode utilities | +| `openswmm_xsect.h` | Cross-section geometry computations | +| `openswmm_output.h` | Binary output (`.out`) file reading | +| `openswmm_geopackage.h` | GeoPackage container queries | +| `openswmm_callbacks.h` | Progress, warning, and step callback typedefs | +| `openswmm_hotstart.h` | Hot start file operations | +| `openswmm_2d.h` | 2-D overland flow mesh (when built with `OPENSWMM_HAS_2D`) | + +## 5.2 Basic Workflow + +Every engine instance moves through the deterministic lifecycle of +Figure 5-1. The file-based path enters at `swmm_engine_open()`; the +programmatic path enters at `swmm_engine_new()` (BUILDING) and joins it +at `swmm_finalize_model()`. + + +
+stateDiagram-v2
+    direction LR
+    [*] --> CREATED : swmm_engine_create
+    CREATED --> OPENED : swmm_engine_open - parse inp, load plugins
+    [*] --> BUILDING : swmm_engine_new
+    BUILDING --> OPENED : swmm_finalize_model
+    OPENED --> INITIALIZED : swmm_engine_initialize
+    INITIALIZED --> STARTED : swmm_engine_start
+    STARTED --> RUNNING : first swmm_engine_step
+    RUNNING --> RUNNING : swmm_engine_step
+    RUNNING --> ENDED : swmm_engine_end
+    ENDED --> ENDED : swmm_engine_report
+    ENDED --> CLOSED : swmm_engine_close
+    CLOSED --> [*] : swmm_engine_delete
+
+ +*Figure 5-1 Engine lifecycle states (SWMM_EngineState in @ref openswmm_engine.h)* + +The typical workflow for building and running a model programmatically (no input file): + +```c +#include + +// 1. Create an empty engine in BUILDING state (no .inp file required) +SWMM_Engine engine = swmm_engine_new(); + +// 2. Set model options (string key/value pairs, same vocabulary as [OPTIONS]) +swmm_options_set(engine, "FLOW_UNITS", "CFS"); +swmm_options_set(engine, "FLOW_ROUTING", "DYNWAVE"); + +// 3. Build the network +swmm_node_add(engine, "J1", SWMM_NODE_JUNCTION); +swmm_node_set_invert_elev(engine, 0, 100.0); +swmm_node_set_max_depth(engine, 0, 6.0); + +swmm_node_add(engine, "Out1", SWMM_NODE_OUTFALL); +swmm_node_set_invert_elev(engine, 1, 95.0); + +swmm_link_add(engine, "C1", SWMM_LINK_CONDUIT); +swmm_link_set_nodes(engine, 0, 0, 1); // from J1 to Out1 +swmm_link_set_length(engine, 0, 500.0); +swmm_link_set_roughness(engine, 0, 0.013); +swmm_link_set_xsect(engine, 0, SWMM_XSECT_CIRCULAR, 2.0, 0, 0, 0); + +// 4. Finalize the built model (validates topology → INITIALIZED) +swmm_finalize_model(engine); + +// 5. Start the simulation (1 = save results) +swmm_engine_start(engine, 1); + +// 6. Step through the simulation +double elapsed = 0.0; +while (swmm_engine_step(engine, &elapsed) == SWMM_OK && elapsed > 0.0) { + // Query results during simulation + double depth; + swmm_node_get_depth(engine, 0, &depth); +} + +// 7. End, close, and destroy +swmm_engine_end(engine); +swmm_engine_close(engine); +swmm_engine_destroy(engine); +``` + +To run an existing input file instead, use `swmm_engine_create()` followed by `swmm_engine_open()` and `swmm_engine_initialize()`: + +```c +SWMM_Engine engine = swmm_engine_create(); +swmm_engine_open(engine, "model.inp", "model.rpt", "model.out", NULL); +swmm_engine_initialize(engine); +swmm_engine_start(engine, 1); + +double elapsed = 0.0; +while (swmm_engine_step(engine, &elapsed) == SWMM_OK && elapsed > 0.0) { + /* ... */ +} + +swmm_engine_end(engine); +swmm_engine_report(engine); +swmm_engine_close(engine); +swmm_engine_destroy(engine); +``` + +The final `NULL` argument to `swmm_engine_open()` selects the built-in `.inp` reader; passing the path of an input-plugin shared library reads the model through that plugin instead (see @ref engine_manual_ch5_api). The single-call helpers `swmm_engine_run()` and `swmm_engine_run_with_callback()` chain the entire lifecycle for batch runs. + +## 5.3 Callbacks {#engine_manual_ch5_callbacks} + +The callback system allows applications to receive notifications during simulation execution: + +- **Progress callback** — Receives periodic updates on simulation progress (0–100%). +- **Warning callback** — Receives warning messages generated during simulation. +- **Step-begin / step-end callbacks** — Called before and after each computational time step. +- **Plugin state callback** — Notifies plugins of engine state transitions. + +Register callbacks before calling `swmm_engine_initialize()`. See @ref openswmm_callbacks.h for details and examples. + +## 5.4 Hot Start Files + +The hot start API enables saving and restoring simulation state for warm-start scenarios: + +```c +#include + +// Save state to a hot start file (engine must be RUNNING or ENDED) +swmm_hotstart_save(engine, "warmup.hsf"); + +// Later, open a hot start file and apply it to an INITIALIZED engine +SWMM_HotStart hs; +swmm_hotstart_open("warmup.hsf", &hs); +swmm_hotstart_apply(engine, hs); +swmm_hotstart_close(hs); +``` + +`swmm_hotstart_apply()` must be called after `swmm_engine_initialize()` but before `swmm_engine_start()`. Objects present in the file but missing from the model (or vice versa) generate warnings rather than errors; they can be enumerated with `swmm_hotstart_warning_count()` / `swmm_hotstart_warning()`. Saving dispatches through any registered state-IO plugins, so alternative hot-start file formats can be provided by plugins (see @ref engine_manual_ch5_api). + +## 5.5 Python Bindings {#engine_manual_ch5_python} + +OpenSWMM 6.0 ships a first-class Python package (`openswmm`) that provides +Pythonic, type-annotated access to the full engine feature set. Install from +PyPI: + +```bash +pip install openswmm +``` + +### 13.5.1 Core Classes (`openswmm.engine`) + +All simulation functionality lives in the `openswmm.engine` sub-package. + +| Class | Purpose | +|---|---| +| `Solver` | Engine lifecycle — open, start, step, end, report | +| `Nodes` | Query and set node attributes and results | +| `Links` | Query and set link attributes and results | +| `Subcatchments` | Query and set subcatchment attributes and results | +| `Gages` | Query rain-gage attributes and recorded rainfall | +| `HotStart` | Save and restore simulation state | +| `MassBalance` | Retrieve continuity error and mass-balance statistics | +| `ModelBuilder` | Construct a SWMM model programmatically without an input file | + +### 13.5.2 Running a Simulation from an Input File + +```python +from openswmm.engine import Solver, Nodes, Links, Subcatchments + +with Solver("model.inp", "model.rpt", "model.out") as solver: + solver.start(save_results=True) + + nodes = Nodes(solver) + links = Links(solver) + subcatchments = Subcatchments(solver) + + while solver.step() > 0: + # Access current time-step values by object name + depth = nodes["J1"].depth + head = nodes["J1"].head + flow = links["C1"].flow + runoff = subcatchments["S1"].runoff + + solver.end() + solver.report() +``` + +### 13.5.3 Accessing Rain Gages + +```python +from openswmm.engine import Solver, Gages + +with Solver("model.inp", "model.rpt", "model.out") as solver: + solver.start(save_results=True) + gages = Gages(solver) + + while solver.step() > 0: + rain = gages["RG1"].rainfall # current rainfall rate (in/hr or mm/hr) +``` + +### 13.5.4 Hot Start Files + +Hot start files allow a long-term simulation to be split into segments, each +beginning from the hydraulic state left by the previous run. + +```python +from openswmm.engine import Solver, HotStart + +# --- Warm-up run: save state at end --- +with Solver("warmup.inp", "warmup.rpt", "warmup.out") as solver: + solver.start(save_results=True) + while solver.step() > 0: + pass + solver.save_hotstart("state.hsf") + solver.end() + solver.report() + +# --- Main run: restore state from hot start file --- +with Solver("main.inp", "main.rpt", "main.out") as solver: + solver.use_hotstart("state.hsf") + solver.start(save_results=True) + while solver.step() > 0: + pass + solver.end() + solver.report() +``` + +### 13.5.5 Mass Balance and Continuity + +```python +from openswmm.engine import Solver, MassBalance + +with Solver("model.inp", "model.rpt", "model.out") as solver: + solver.start(save_results=True) + while solver.step() > 0: + pass + solver.end() + + mb = MassBalance(solver) + print(f"Runoff continuity error : {mb.runoff_error:.4f} %") + print(f"Routing continuity error: {mb.routing_error:.4f} %") +``` + +### 13.5.6 Building a Model Programmatically + +`ModelBuilder` constructs a complete SWMM network without an input file. The +finished model is passed directly to `Solver`. + +```python +from openswmm.engine import ModelBuilder, Solver, Nodes, Links +from openswmm.engine import NodeType, LinkType, FlowUnits, RoutingModel + +# Build the network +mb = ModelBuilder() +mb.flow_units = FlowUnits.CFS +mb.routing_model = RoutingModel.DYNWAVE + +j1 = mb.add_node("J1", NodeType.JUNCTION) +j1.invert_elev = 100.0 +j1.max_depth = 6.0 + +out1 = mb.add_node("Out1", NodeType.OUTFALL) +out1.invert_elev = 95.0 + +c1 = mb.add_link("C1", LinkType.CONDUIT, from_node="J1", to_node="Out1") +c1.length = 500.0 +c1.roughness = 0.013 +c1.set_circular_xsect(diameter=2.0) + +# Simulate the built model +with Solver(mb, "model.rpt", "model.out") as solver: + solver.start(save_results=True) + nodes = Nodes(solver) + while solver.step() > 0: + print(nodes["J1"].depth) + solver.end() + solver.report() +``` + +### 13.5.7 Full API Reference + +The complete class and method documentation, including all attributes, +enumerations, and error types, is published in the +[Python Bindings API Reference](python/index.html). + +See the `python/` directory in the source tree for the Cython source (`.pyx`), +type stubs (`.pyi`), and test suite. + +## 5.6 Building with the API + +To use the OpenSWMM Engine C API in your own project, link against `openswmm_engine` using CMake: + +```cmake +find_package(OpenSWMMCore REQUIRED) +target_link_libraries(my_app PRIVATE OpenSWMMCore::openswmm_engine) +``` + +All public headers are installed under `include/openswmm/engine/`. + +## 5.7 User-Defined Flags {#engine_manual_ch5_user_flags} + +OpenSWMM Engine v6 introduces **user-defined flags** (inspired by InfoWorks ICM custom attributes) that allow metadata to be attached to any model object—nodes, links, or subcatchments. Flags are defined with a name, data type, and optional description and then assigned values per object. + +### Input File Syntax + +Two new sections are recognised in the input file: + +```ini +[USER_FLAGS] +;;Name Type Description +INSPECTED BOOLEAN "Has the object been field-inspected?" +PRIORITY INTEGER "Maintenance priority (1 = highest)" +ROUGHNESS_ADJ REAL "Site-specific roughness multiplier" +ASSET_ID STRING "External asset-management system ID" + +[USER_FLAG_VALUES] +;;ObjectType ObjectName FlagName Value +NODE J1 INSPECTED YES +NODE J1 PRIORITY 2 +LINK C_MAIN ROUGHNESS_ADJ 1.05 +LINK C_MAIN ASSET_ID "AM-00341" +SUBCATCHMENT S_WEST INSPECTED NO +``` + +Supported types are **BOOLEAN** (`YES`/`NO`/`TRUE`/`FALSE`/`1`/`0`), **INTEGER**, **REAL**, and **STRING**. + +### C API + +Flag values can be read or written at runtime through the C API: + +```c +int swmm_userflag_get_bool(SWMM_Engine engine, const char* name, int* value); +int swmm_userflag_set_bool(SWMM_Engine engine, const char* name, int value); + +int swmm_userflag_get_int (SWMM_Engine engine, const char* name, int* value); +int swmm_userflag_set_int (SWMM_Engine engine, const char* name, int value); + +int swmm_userflag_get_real(SWMM_Engine engine, const char* name, double* value); +int swmm_userflag_set_real(SWMM_Engine engine, const char* name, double value); +``` + +See `openswmm_model.h` for the complete set of flag functions. + +## 5.8 Plugin Interface for Output and Reporting {#engine_manual_ch5_plugins} + +The **plugin SDK** enables third-party shared libraries to replace or supplement the engine's built-in file I/O — the model reader/writer, the binary output (`.out`) file, the text-based status report, and the hot-start (state) file. Four abstract C++ interfaces are provided: + +| Interface | Header | Purpose | +|---|---|---| +| `IInputPlugin` | `IInputPlugin.hpp` | Reads model data into the engine (and writes it back out) in alternative container formats | +| `IOutputPlugin` | `IOutputPlugin.hpp` | Writes time-series results at each output time step | +| `IReportPlugin` | `IReportPlugin.hpp` | Writes summary statistics at simulation end | +| `IStateIOPlugin` | `IStateIOPlugin.hpp` | Reads and writes simulation state (hot-start) files | + +All interfaces share a common lifecycle that mirrors the engine's own state machine (enumerated by `PluginState` in `PluginState.hpp`): + +``` +LOADED → initialize() → INITIALIZED → validate() → VALIDATED + → prepare() → PREPARED → update() [N times] + → finalize() → FINALIZED → CLOSED +``` + +Each plugin is compiled as a shared library (`.so` / `.dylib` / `.dll`) that exports a single C factory function: + +```cpp +extern "C" openswmm::IPluginComponentInfo* openswmm_plugin_info(void); +``` + +The `IPluginComponentInfo` class provides metadata (id in reverse-DNS notation, caption, description, version, vendor, license), capability queries (`has_input()`, `has_output()`, `has_report()`, `has_state_io()` — a single plugin may support several roles), optional registration/licensing hooks, and factory methods for creating instances of each interface. Plugins also advertise the file formats they handle through `file_filters()`, one entry per (role, glob-pattern) pair; hosts such as the GUI use these to build file-picker dialogs without hard-coding format lists. + +### Plugin Discovery + +Each engine instance owns a `PluginFactory` that automatically scans the engine library directory and its `plugins/` and `components/` subdirectories for shared libraries exporting `openswmm_plugin_info`. Discovered libraries are registered in a component registry keyed by `id:version`; the built-in default input, output, report, and state-IO plugins are registered alongside them (flagged as built-ins). Hosts that only need to enumerate available formats can call the framework-free discovery facade in `PluginDiscovery.hpp`: + +```cpp +#include + +auto filters = openswmm::discover_all_filters(); // every (plugin, filter) pair +auto plugins = openswmm::discover_plugins_by_id(); // grouped per plugin id +``` + +### Registering Plugins + +Plugins are loaded from the `[PLUGINS]` input-file section: + +```ini +[PLUGINS] +./plugins/hdf5_output.dylib file="results.h5" compress=9 +./plugins/csv_report.dylib file="report.csv" delimiter="," +``` + +Each line begins with the plugin to load — a shared-library path, a plugin id, or an `id:version` pair (ids are resolved against the auto-discovery registry) — followed by initialisation arguments that are forwarded verbatim to the plugin's `initialize()` method. + +Figure 5-2 traces the full resolution path from engine open to an +initialized plugin. + + +
+flowchart TD
+    A[swmm_engine_open] --> B[PluginFactory scans engine lib dir plus plugins and components subdirectories]
+    B --> C[Libraries exporting openswmm_plugin_info registered by id and version]
+    C --> D[Built-in input, output, report and state-IO plugins registered as built-ins]
+    D --> E[Parse PLUGINS section entries]
+    E --> F{Entry form}
+    F -- shared-library path --> G[Load library directly]
+    F -- plugin id --> H[Resolve newest version in registry]
+    F -- id colon version --> I[Resolve exact version in registry]
+    G --> J[Instantiate plugin]
+    H --> J
+    I --> J
+    J --> K[Forward remaining arguments to initialize]
+    K --> L[Plugin receives host callbacks during the run]
+
+
+@ref engine_manual_ch5_plugins "5.8 Plugin interface: discovery" +@ref engine_manual_sect_PLUGINS "[PLUGINS] section" +@ref engine_manual_ch5_plugins "5.8 Plugin interface: instantiation" +@ref engine_manual_ch5_callbacks "5.3 Callbacks" +
+ +*Figure 5-2 Plugin discovery, resolution and loading workflow (rendered diagram)* + +The `[PLUGINS]` section can also be inspected and edited through the C API without re-parsing the input file: `swmm_plugins_count()`, `swmm_plugin_get()`, `swmm_plugin_set()`, and `swmm_plugin_remove()` (declared in @ref openswmm_model.h) read and mutate the in-memory plugin list, which is re-serialised on the next model write. + +### Input Plugins and Model Serialisation + +An `IInputPlugin` reads a model file into the engine's simulation context and can also write the current model back out. The reader is selected per-open through the final argument of `swmm_engine_open()` (`NULL` selects the built-in `.inp` reader). To save the in-memory model through a specific writer plugin — for example a GeoPackage container instead of `.inp` — use: + +```c +// NULL/empty plugin id is equivalent to swmm_model_write() (.inp writer) +swmm_model_write_with_plugin(engine, "model.gpkg", + "org.hydrocouple.openswmm.plugins.geopackage"); +``` + +The plugin id is resolved with the same path / `id` / `id:version` logic as the `[PLUGINS]` section, and the resolved plugin must advertise input capability. + +### State-IO Plugins + +An `IStateIOPlugin` persists and restores simulation state (hot-start). On save, `swmm_hotstart_save()` dispatches through the registered state-IO plugins in order — the first plugin whose `write_state()` succeeds wins. On read, the engine calls each plugin's `can_read()` (a cheap extension/magic-number sniff) to pick the plugin that recognises the file. A built-in `DefaultStateIOPlugin` is always registered as a fallback, so the native binary hot-start format keeps working when no external plugin claims the file. Missing-object mismatches between the state file and the model are reported through the plugin's `warnings()` rather than as hard errors. + +### Data Available to Plugins + +At every output time step the engine passes a read-only **SimulationSnapshot** to `update()`. The snapshot exposes per-object results: + +- **NodeSnapshot** — depth, head, volume, lateral inflow, total inflow, overflow +- **LinkSnapshot** — flow, depth, velocity, capacity fraction +- **SubcatchSnapshot** — rainfall, evaporation, infiltration, runoff, groundwater flow, groundwater elevation, soil moisture +- **GageSnapshot** — current rainfall rate + +See the headers in `include/openswmm/plugin_sdk/` for full details. The engine-side loader, lifecycle dispatcher, and the built-in default plugins live in `src/engine/plugins/` (`PluginFactory.cpp`, `DefaultInputPlugin.cpp`, `DefaultOutputPlugin.cpp`, `DefaultReportPlugin.cpp`, `DefaultStateIOPlugin.cpp`). + +## 5.9 Multi-Column Series-File Inputs (CSV/TSV/TSF) {#engine_manual_ch5_csv} + +A new rain-file format, **USER_CSV**, allows rain gage data to be read from multi-column series files. A single file can serve multiple rain gages by specifying a column name after the file path: + +```ini +[RAINGAGES] +;;Name Format Interval SCF Source +RG1 VOLUME 0:15 1.0 TIMESERIES RAIN1 +RG2 VOLUME 0:15 1.0 FILE "rain.csv:EAST_GAGE" +RG3 VOLUME 0:15 1.0 FILE "rain.csv:WEST_GAGE" +``` + +The syntax `"filename.csv:COLUMN_NAME"` tells the engine to open `filename.csv` and read the column whose header matches `COLUMN_NAME` (case-insensitive). An empty column name selects the file's first data column. The file is expected to have a header row whose first column holds a full date-time; the remaining columns hold values. + +Three file layouts are recognised, detected automatically from the file's contents (the extension does not matter): + +- **CSV** — comma-separated, header row, e.g. `DateTime,EAST_GAGE,WEST_GAGE`. +- **TSV** — the same layout, tab-separated. +- **PCSWMM TSF** — tab-separated with a three-row header: an `IDs:` row naming the columns, a parameter row, and a units row. Date-times use the 12-hour `MM/DD/YYYY hh:mm:ss AM/PM` form. + +Date-times in CSV/TSV files may be ISO-8601 (`YYYY-MM-DD HH:MM[:SS]`) or US (`MM/DD/YYYY HH:MM[:SS]`), with an optional trailing AM/PM token for 12-hour clocks. + +The same `"path:COLUMN_NAME"` reference works for **named time series**: `[TIMESERIES] TS_E FILE "rain.csv:EAST_GAGE"` binds the series `TS_E` to that column, so inflows, outfall stages, and other objects that reference a time series by name can depend on one column of a shared file. + +Each multi-column file is parsed **once** per model open (or per `swmm_gage_reload_rain_files()` call), no matter how many rain gages and time series reference it, and there is no limit on the number of columns or the width of a row. A referenced file that cannot be opened, or that yields no readable rows, fails the model open with an explicit error rather than silently supplying zero values. + +The `RainFileFormat` enumeration now includes: + +| Value | Constant | Description | +|---|---|---| +| 0 | `NWS_15` | NWS 15-minute data | +| 1 | `NWS_HOURLY` | NWS hourly data | +| 2 | `DSI_3240` | NCDC DSI 3240 hourly | +| 3 | `DSI_3260` | NCDC DSI 3260 15-minute | +| 4 | `HLY_PRCP` | HLY_PRCP format | +| 5 | `STAN_PRCP` | Standard SWMM rain file | +| 6 | `USER_CSV` | User-supplied multi-column CSV (**new in v6**) | + +## 5.10 Extension Options (Optional Tags) {#engine_manual_ch5_ext_options} + +The `[OPTIONS]` section now tolerates **extension option keys** that are not part of the standard SWMM vocabulary. Any key the parser does not recognise is stored in an extension-options map as a string key-value pair rather than producing a fatal error (a non-fatal warning is issued). This mechanism allows plugins and coupled models to pass configuration through the familiar `[OPTIONS]` section. + +### Input File Syntax + +```ini +[OPTIONS] +FLOW_UNITS CFS +FLOW_ROUTING DYNWAVE +START_DATE 01/01/2020 +END_DATE 01/02/2020 + +;; Standard new option — Coordinate Reference System (EPSG or PROJ string) +CRS EPSG:4326 + +;; Extension options — stored as-is, available to plugins via API +TURBULENCE_DAMP 0.85 +PLUGIN_TIMEOUT 30 +MY_VENDOR_SETTING value123 +``` + +Extension option keys are **upper-cased** for storage. Plugins (or any code using the C API) can retrieve and set these values at runtime: + +```c +// Retrieve an extension option +char buffer[256]; +swmm_options_get_ext(engine, "TURBULENCE_DAMP", buffer, sizeof(buffer)); +double damp = atof(buffer); + +// Create or update an extension option +swmm_options_set_ext(engine, "MY_VENDOR_SETTING", "new_value"); +``` + +Note that the **CRS** key is a standard option new to v6 and is stored separately in `SimulationOptions::crs`. All other unrecognised keys go into the extension map. + + + diff --git a/docs/manuals/manuals.md b/docs/manuals/manuals.md index 3da6272bd..f7f31ceda 100644 --- a/docs/manuals/manuals.md +++ b/docs/manuals/manuals.md @@ -7,14 +7,27 @@ The following manuals document the use, application, and technical reference for See @ref authors for the full list of authors and contributors. -* User Manual (@ref user_manual) -* Application Manual (@ref application_manual) -* Reference Manuals - * Hydrology Reference Manual (@ref hydrology_reference_manual) - * Hydraulics Reference Manual (@ref hydraulics_reference_manual) - * Quality Reference Manual (@ref quality_reference_manual) +* Engine Manual (@ref engine_manual) — the objects a model is built from, the input + file format, the files the engine reads and writes, its reports, the C and Python + interfaces, and every error and warning message. +* GUI Manual — the graphical application, SWMMVis, is documented separately at + +* Application Manual (@ref application_manual) — which formulation to use and what + changes if you pick another: six decision workflows and thirteen chapters, each + worked from a deck in the repository with every figure generated from its runs. +* Reference Manuals — the theory and numerics behind each formulation, with the + status of each alternative marked Implemented, Experimental, Planned or Retired. + * Hydrology Reference Manual (@ref hydrology_reference_manual) — meteorology, + runoff, infiltration, groundwater, snowmelt, RDII, and the distributed + surface and subsurface processes on the 2D mesh. + * Hydraulics Reference Manual (@ref hydraulics_reference_manual) — the four flow + routers, pressurisation, cross-sections, pumps and regulators, the explicit + finite-volume solver and two-dimensional overland flow. + * Quality Reference Manual (@ref quality_reference_manual) — buildup, washoff, + treatment, LID controls, the three transport engines, multi-species reactions, + water age and heat, and surface quality on the mesh. * C API Reference - * The OpenSWMM Engine v6 C API is organized by domain into 19 public headers. + * The OpenSWMM Engine v6 C API is organized by domain into 31 public headers. See the [Modules](modules.html) page for the full API reference generated from the `include/openswmm/engine/` headers. * Start with @ref openswmm_engine.h for the engine lifecycle, then explore diff --git a/docs/manuals/reference/hydraulics.md b/docs/manuals/reference/hydraulics.md index 7616ca1b8..007d2e1aa 100644 --- a/docs/manuals/reference/hydraulics.md +++ b/docs/manuals/reference/hydraulics.md @@ -41,11 +41,13 @@ water quality and low impact development models. ## List of Figures + + Figure 1-1 Elements of a typical urban drainage system -Figure 1-2 SWMM's conceptual model of a stormwater drainage system +Figure 1-2 Objects of an OpenSWMM model -Figure 1-3 Processes modeled by SWMM +Figure 1-3 Processes modelled by OpenSWMM Figure 1-4 Block diagram of SWMM's state transition process @@ -53,11 +55,13 @@ Figure 1-5 Flow chart of SWMM's simulation procedure Figure 1-6 Interpolation of reported values from computed values +Figure 1-7 The hydraulics of this manual: the 1D network, the 2D surface and their coupling + Figure 2-1 Node-link representation of a sewer system -Figure 2-2 Comparison of dynamic wave and kinematic wave solutions +Figure 2-2 Comparison of dynamic wave and kinematic wave solutions (from Miller, 1984) -Figure 3-1 Node-link representation of a conveyance network in SWMM +Figure 3-1 Node-link representation of a conveyance network in SWMM (from Roesner et al, 1992). Figure 3-2 Special flow conditions for dynamic wave analysis @@ -69,15 +73,15 @@ Figure 3-5 Profile view of example rectangular conduit (not to scale) Figure 3-6 Outflow hydrographs for example conduit -I -Figure 3-7 Outflow hydrographs for example conduit -- II +Figure 3-7 Outflow hydrographs for example conduit – II Figure 3-8 Conceptual representation of the dynamic Preissmann slot -Figure 3-9 State transitions of the dynamic Preissmann slot at a conduit end +Figure 3-9 State transitions of the dynamic Preissmann slot at a conduit end (rendered diagram; states and transitions as implemented in `updateDPSState`) Figure 3-10 Virtual junction representation of a conduit grade break -Figure 3-11 Workflow of one Anderson-accelerated iteration of the successive-approximation loop +Figure 3-11 Workflow of one Anderson-accelerated iteration of the successive-approximation loop (rendered diagram) Figure 4-1 Section factor versus area for a circular shape @@ -103,9 +107,11 @@ Figure 5-8 A natural channel transect Figure 5-9 A transect depth increment with three compound segments -Figure 5-10 Example of a storage curve and its section view +Figure 5-10 A one-sided street cross-section (not to scale) -Figure 5-11 Finding the volume at a given depth for a storage curve +Figure 5-11 Example of a storage curve and its section view + +Figure 5-12 Finding the volume at a given depth for a storage curve Figure 6-1 Orifice orientations @@ -133,20 +139,52 @@ Figure 7-5 SWMM node-link representation of a culvert with a roadway weir Figure 7-6 Discharge coefficients for roadway weirs (from FHWA, 2012) -Figure 8-1 Substep workflow of the explicit finite-volume solver +Figure 7-7 Examples of storm drain inlets. + +Figure 7-8 Standard types of curb and gutter inlets + +Figure 7-9 Performance curve for a custom inlet + +Figure 7-10 Representation of a dual drainage system + +Figure 7-11 Street cross-section divided into gutter and roadway flow + +Figure 7-12 Types of channel drop inlets + +Figure 8-1 Node–link routing against the finite-volume view: one momentum balance per conduit versus a conduit cut into cells with the water surface resolved inside it + +Figure 8-2 The tapered static slot for a 3 ft circular pipe: top width and celerity across the crown at four slot celerities + +Figure 8-3 The Riemann fan at a face: HLL signal speeds for a wet–wet face and the rarefaction-tail estimate at a dry bed + +Figure 8-4 Local time stepping: power-of-two tiers, the macro cycle and flux accumulation across a tier interface + +Figure 8-5 Substep workflow of the explicit finite-volume solver, including the post-step census retry and local time stepping (rendered diagram) + +Figure 8-6 Wet/dry and exception handling in one face flux evaluation (rendered diagram) + +Figure 8-7 Hydrostatic reconstruction at a wet/dry front: an advancing front (left) and an emerged bank acting as a wall (right) -Figure 8-2 Wet/dry and exception handling in one face flux evaluation +Figure 8-8 Node ghost-state construction at a coupling face -Figure 8-3 Hydrostatic reconstruction at a wet/dry front +Figure 9-1 The one-dimensional network and the two-dimensional surface: exchange pathways -Figure 8-4 Node ghost-state construction at a coupling face +Figure 9-2 One 1D–2D co-advance batch and the explicit marcher's substep loop within it (rendered diagram) -Figure 9-1 One 1D–2D co-advance batch and the explicit marcher's substep loop within it +Figure 9-3 Wetting cases of a planar-bed triangular cell and the wetted-edge face gate (placeholder — to be replaced by a final drawing) -Figure 9-2 Wetting cases of a planar-bed triangular cell and the wetted-edge face gate +Figure 9-4 A quadrilateral and a triangle sharing a face: local edge numbering, the padded slot layout and the centroid-to-edge distance + +Figure 9-5 The flux-active set at a wetting front: the default one-ring halo, the front-rebuild halo and the breach that forces an early rebuild + +Figure 9-6 Where a node spill is booked under COUPLING_IN_FLOODING: the same totals and the same continuity error, in two different rows + + ## List of Tables + + Table 1-1 Development history of SWMM Table 1-2 SWMM's modeling objects @@ -193,7 +231,7 @@ Table 6-1 Pump curves recognized by SWMM Table 6-2 Kindsvater-Carter constants for rectangular weir coefficient -Table 6-3 Rectangular broad-crested weir coefficients (ft1/2/sec) +Table 6-3 Rectangular broad-crested weir coefficients (ft1/2/sec) Table 6-4 Formulas for flow derivatives of various types of weirs @@ -205,13 +243,31 @@ Table 7-3 Hazen-Williams C-factors for different pipe materials Table 7-4 Darcy-Weisbach roughness heights for different pipe materials -Table 8-1 Dry-state constants of the explicit finite-volume solver +Table 7-5 Description of grate inlet types1 + +Table 7-6 Splash-over velocity for different types of grate inlets1 + +Table 7-7 Effective depth for curb opening inlets under orifice flow + +Table 8-1 Dry-state constants of the explicit finite-volume solver (internal US units) -Table 9-1 Wetting and drying thresholds and guards of the 2D solver +Table 9-1 Wetting and drying thresholds and guards of the 2D solver (SI units) -Table C-1 Circular section properties as function of area +Table 9-2 Momentum closures of the 2D marcher -Table C-2 Circular section properties as function of depth +Table 9-3 Diagonal selection of the two-plane quadrilateral closure (Begnudelli and Sanders, 2007, Cases 1–3) + +Table 9-4 The fourteen `REPORT_2D_VARIABLES` tokens + +Table 9-5 The forty-two live `[2D_OPTIONS]` keys and the theory each selects + +Table 9-6 The sixteen retired `[2D_OPTIONS]` keys and values + +Table 10-1 Formulations recorded in this chapter + +Table C-1 Circular section properties as function of depth + +Table C-2 Circular section properties as function of area Table D-1 Standard elliptical pipe sizes @@ -247,6 +303,8 @@ Table H-1 Culvert codes Table H-2 Culvert coefficients + + ## List of Symbols | Symbol | Description | @@ -378,5 +436,6 @@ Table H-2 Culvert coefficients - @subpage hydraulics_ref_ch7_advanced_features — Chapter 7: Advanced Features - @subpage hydraulics_ref_ch8_finite_volume — Chapter 8: Explicit Finite-Volume Analysis - @subpage hydraulics_ref_ch9_two_dimensional — Chapter 9: Two-Dimensional Overland Flow Analysis +- @subpage hydraulics_ref_ch10_planned — Chapter 10: Planned and Retired Formulations - @subpage hydraulics_ref_references — References - @subpage hydraulics_ref_appendix — Appendix diff --git a/docs/manuals/reference/hydraulics/SWMM5 Reference Manual II - 2021.md b/docs/manuals/reference/hydraulics/SWMM5 Reference Manual II - 2021.md deleted file mode 100644 index 23b3b9043..000000000 --- a/docs/manuals/reference/hydraulics/SWMM5 Reference Manual II - 2021.md +++ /dev/null @@ -1,9583 +0,0 @@ -EPA/600/R-17/111 - -May 2017 - -(Revised July 2021) - -Storm Water Management Model - -Reference Manual - -Volume II -- Hydraulics - -By: - -Lewis A. Rossman - -Office of Research and Development - -National Risk Management Laboratory - -Cincinnati, OH 45268 - -Center for Environmental Solutions and Emergency Response - -Office of Research and Development - -U.S. Environmental Protection Agency - -26 Martin Luther King Drive - -Cincinnati, OH 45268 - -July 2021 - -# Disclaimer - -The information in this document has been funded wholly or in part by -the U.S. Environmental Protection Agency (EPA). It has been subjected to -the Agency's peer and administrative review, and has been approved for -publication as an EPA document. Mention of trade names or commercial -products does not constitute endorsement or recommendation for use. - -Although a reasonable effort has been made to assure that the results -obtained are correct, the computer programs described in this manual are -experimental. Therefore the author and the U.S. Environmental Protection -Agency are not responsible and assume no liability whatsoever for any -results or any use made of the results obtained from these programs, nor -for any damages or litigation that result from the use of these programs -for any purpose. - -# Abstract - -SWMM is a dynamic rainfall-runoff simulation model used for single event -or long-term (continuous) simulation of runoff quantity and quality from -primarily urban areas. The runoff component of SWMM operates on a -collection of subcatchment areas that receive precipitation and generate -runoff and pollutant loads. The routing portion of SWMM transports this -runoff through a system of pipes, channels, storage/treatment devices, -pumps, and regulators. SWMM tracks the quantity and quality of runoff -generated within each subcatchment, and the flow rate, flow depth, and -quality of water in each pipe and channel during a simulation period -comprised of multiple time steps. The reference manual for this edition -of SWMM is comprised of three volumes. Volume I describes SWMM's -hydrologic models, Volume II its hydraulic models, and Volume III its -water quality and low impact development models. - -# Acknowledgements - -This report was written by Lewis A. Rossman, Environmental Scientist -Emeritus, U.S. Environmental Protection Agency, Cincinnati, OH. - -The author would like to acknowledge the contributions made by the -following individuals to previous versions of SWMM that were drawn -heavily upon in writing this report: John Aldrich, Douglas Ammon, Carl -W. Chen, Brett Cunningham, Robert Dickinson, James Heaney, Wayne Huber, -Miguel Medina, Russell Mein, Charles Moore, Stephan Nix, Alan Peltz, Don -Polmann, Larry Roesner, Charles Rowney, and Robert Shubinsky. The -efforts of Wayne Huber (Oregon State University emeritus), Thomas -Barnwell (US EPA retired), Richard Field (US EPA retired), Harry Torno -(US EPA retired) and William James (University of Guelph emeritus) to -support and maintain the program over the past several decades are also -gratefully acknowledged. - -**Table of Contents** - -[Disclaimer [ii](#disclaimer)](#disclaimer) - -[Abstract [iii](#abstract)](#abstract) - -[Acknowledgements [iv](#acknowledgements)](#acknowledgements) - -[List of Figures [vii](#list-of-figures)](#list-of-figures) - -[List of Tables [ix](#list-of-tables)](#list-of-tables) - -[List of Symbols [xi](#list-of-symbols)](#list-of-symbols) - -[Chapter 1 - SWMM Overview [15](#swmm-overview)](#swmm-overview) - -[1.1 Introduction [15](#introduction)](#introduction) - -[1.2 SWMM's Object Model [16](#swmms-object-model)](#swmms-object-model) - -[1.3 SWMM's Process Models -[21](#swmms-process-models)](#swmms-process-models) - -[1.4 Simulation Process Overview -[23](#simulation-process-overview)](#simulation-process-overview) - -[1.5 Interpolation and Units -[27](#interpolation-and-units)](#interpolation-and-units) - -[Chapter 2 - SWMM's Hydraulic Model -[30](#swmms-hydraulic-model)](#swmms-hydraulic-model) - -[2.1 Network Components [31](#network-components)](#network-components) - -[2.2 Analysis Methods [35](#analysis-methods)](#analysis-methods) - -[2.3 Boundary and Initial Conditions -[38](#boundary-and-initial-conditions)](#boundary-and-initial-conditions) - -[Chapter 3 - Dynamic Wave Analysis -[40](#dynamic-wave-analysis)](#dynamic-wave-analysis) - -[3.1 Governing Equations -[40](#governing-equations)](#governing-equations) - -[3.2 Solution Method [44](#solution-method)](#solution-method) - -[3.3 Computational Details -[46](#computational-details)](#computational-details) - -[3.4 Numerical Stability -[59](#numerical-stability)](#numerical-stability) - -[Chapter 4 - Kinematic Wave Analysis -[65](#kinematic-wave-analysis)](#kinematic-wave-analysis) - -[4.1 Governing Equations -[65](#governing-equations-1)](#governing-equations-1) - -[4.2 Solution Method [67](#solution-method-1)](#solution-method-1) - -[4.3 Computational Details -[69](#computational-details-1)](#computational-details-1) - -[4.4 Numerical Stability -[74](#numerical-stability-1)](#numerical-stability-1) - -[Chapter 5 - Cross-Section Geometry -[76](#cross-section-geometry)](#cross-section-geometry) - -[5.1 Standard Conduit Shapes -[76](#standard-conduit-shapes)](#standard-conduit-shapes) - -[5.2 Custom Conduit Shapes -[94](#custom-conduit-shapes)](#custom-conduit-shapes) - -[5.3 Irregular Natural Channels -[96](#irregular-natural-channels)](#irregular-natural-channels) - -[5.4 Street Cross-Sections -[99](#street-cross-sections)](#street-cross-sections) - -[5.5 Storage Unit Geometry -[100](#storage-unit-geometry)](#storage-unit-geometry) - -[5.6 Critical and Normal Depths -[105](#critical-and-normal-depths)](#critical-and-normal-depths) - -[Chapter 6 - Pumps and Regulators -[109](#pumps-and-regulators)](#pumps-and-regulators) - -[6.1 Pumps [109](#pumps)](#pumps) - -[6.2 Orifices [112](#orifices)](#orifices) - -[6.3 Weirs [120](#weirs)](#weirs) - -[6.4 Outlets [130](#outlets)](#outlets) - -[Chapter 7 - Advanced Features -[132](#advanced-features)](#advanced-features) - -[7.1 Evaporation and Seepage -[132](#evaporation-and-seepage)](#evaporation-and-seepage) - -[7.2 Minor Losses [141](#minor-losses)](#minor-losses) - -[7.3 Force Mains [143](#force-mains)](#force-mains) - -[7.4 Culverts [147](#culverts)](#culverts) - -[7.5 Roadway Weirs [152](#roadway-weirs)](#roadway-weirs) - -[7.6 Storm Drain Inlets [155](#storm-drain-inlets)](#storm-drain-inlets) - -[Appendix [159](#_Toc73193124)](#_Toc73193124) - -[References [193](#references)](#references) - -**\** - -# List of Figures - -[Figure 1‑1 Elements of a typical urban drainage system -[17](#_Toc484694706)](#_Toc484694706) - -[Figure 1‑2 SWMM\'s conceptual model of a stormwater drainage system -[18](#_Toc401645528)](#_Toc401645528) - -[Figure 1‑3 Processes modeled by SWMM -[21](#_Toc401645529)](#_Toc401645529) - -[Figure 1‑4 Block diagram of SWMM\'s state transition process -[23](#_Toc401645530)](#_Toc401645530) - -[Figure 1‑5 Flow chart of SWMM\'s simulation procedure -[26](#_Toc401645531)](#_Toc401645531) - -[Figure 1‑6 Interpolation of reported values from computed values -[28](#_Toc401645532)](#_Toc401645532) - -[Figure 2‑1 Node-link representation of a sewer system -[30](#_Toc484694712)](#_Toc484694712) - -[Figure 2‑2 Comparison of dynamic wave and kinematic wave solutions -[38](#_Toc484694713)](#_Toc484694713) - -[Figure 3‑1 Node-link representation of a conveyance network in SWMM -[43](#_Toc484694714)](#_Toc484694714) - -[Figure 3‑2 Special flow conditions for dynamic wave analysis -[50](#_Toc484694715)](#_Toc484694715) - -[Figure 3‑3 Illustration of a surcharged node -[53](#_Toc484694716)](#_Toc484694716) - -[Figure 3‑4 Ponding of excess water above a junction -[56](#_Toc484694717)](#_Toc484694717) - -[Figure 3‑5 Profile view of example rectangular conduit (not to scale) -[60](#_Toc484694718)](#_Toc484694718) - -[Figure 3‑6 Outflow hydrographs for example conduit -I -[61](#_Toc484694719)](#_Toc484694719) - -[Figure 3‑7 Outflow hydrographs for example conduit -- II -[62](#_Toc484694720)](#_Toc484694720) - -[Figure 4‑1 Section factor versus area for a circular shape -[64](#_Toc484694721)](#_Toc484694721) - -[Figure 4‑2 Space-time grid for kinematic wave analysis -[65](#_Toc484694722)](#_Toc484694722) - -[Figure 4‑3 Outflow hydrograph for example conduit -[73](#_Toc484694723)](#_Toc484694723) - -[Figure 5‑1 Power law cross section shape -[77](#_Toc484694724)](#_Toc484694724) - -[Figure 5‑2 Geometric properties of a partly filled circular shape based -on depth [80](#_Toc484694725)](#_Toc484694725) - -[Figure 5‑3 Geometric properties of a partly filled circular shape based -on area [80](#_Toc484694726)](#_Toc484694726) - -[Figure 5‑4 Ellipsoid and arch pipe cross sectional shapes -[81](#_Toc484694727)](#_Toc484694727) - -[Figure 5‑5 Masonry sewer shapes [84](#_Toc484694728)](#_Toc484694728) - -[Figure 5‑6 Composite cross section shapes -[86](#_Toc484694729)](#_Toc484694729) - -[Figure 5‑7 A Shape Curve with a depth segment shown -[93](#_Toc484694730)](#_Toc484694730) - -[Figure 5‑8 A natural channel transect -[94](#_Toc484694731)](#_Toc484694731) - -[Figure 5‑9 A transect depth increment with three compound segments -[95](#_Toc484694732)](#_Toc484694732) - -[Figure 5‑10 Example of a storage curve and its section view -[98](#_Toc484694733)](#_Toc484694733) - -[Figure 5‑11 Finding the volume at a given depth for a storage curve -[99](#_Toc484694734)](#_Toc484694734) - -[Figure 6‑1 Orifice orientations [107](#_Toc484694735)](#_Toc484694735) - -[Figure 6‑2 Determination of effective head for an orifice -[110](#_Toc484694736)](#_Toc484694736) - -[Figure 6‑3 Orifice with unsubmerged inlet -[110](#_Toc484694737)](#_Toc484694737) - -[Figure 6‑4 Transverse weir shapes -[115](#_Toc484694738)](#_Toc484694738) - -[Figure 6‑5 Coefficient for triangular weirs (from Brater and King, -1976) [118](#_Toc484694739)](#_Toc484694739) - -[Figure 6‑6 Definitions of submerged and surcharged weir flow -[120](#_Toc484694740)](#_Toc484694740) - -[Figure 6‑7 Rating curve for a vortex device compared to an orifice -[125](#_Toc484694741)](#_Toc484694741) - -[Figure 7‑1 Depths used for computing seepage in storage units -[135](#_Toc484694742)](#_Toc484694742) - -[Figure 7‑2 Concrete box culvert (from FHWA, 2012) -[142](#_Toc484694743)](#_Toc484694743) - -[Figure 7‑3 Example of a culvert rating curve (from FHWA, 2012) -[143](#_Toc484694744)](#_Toc484694744) - -[Figure 7‑4 Roadway overtopping (from FHWA, 2012) -[148](#_Toc484694745)](#_Toc484694745) - -[Figure 7‑5 SWMM node-link representation of a culvert with a roadway -weir [148](#_Toc484694746)](#_Toc484694746) - -[Figure 7‑6 Discharge coefficients for roadway weirs (from FHWA, 2012) -[149](#_Toc484694747)](#_Toc484694747) - -# List of Tables - -# - -[Table 1‑1 Development history of SWMM -[16](#_Toc484690413)](#_Toc484690413) - -[Table 1‑2 SWMM's modeling objects [19](#_Toc484690414)](#_Toc484690414) - -[Table 1‑3 State variables used by SWMM -[24](#_Toc484690415)](#_Toc484690415) - -[Table 1‑4 Units of expression used by SWMM -[29](#_Toc484690416)](#_Toc484690416) - -[Table 2‑1 Features and limitations of dynamic wave and kinematic wave -solutions [37](#_Toc484690417)](#_Toc484690417) - -[Table 3‑1 Surface area adjustments for various dynamic wave flow -conditions [51](#_Toc484690418)](#_Toc484690418) - -[Table 5‑1 Geometric properties for open channel shapes as functions of -water depth [75](#_Toc484690419)](#_Toc484690419) - -[Table 5‑2 Geometric properties for open channel shapes as functions of -flow area [76](#_Toc484690420)](#_Toc484690420) - -[Table 5‑3 Geometric properties for the power law shape -[78](#_Toc484690421)](#_Toc484690421) - -[Table 5‑4 Geometric properties of a full circular cross section -[79](#_Toc484690422)](#_Toc484690422) - -[Table 5‑5 Full area and hydraulic radius of custom ellipsoid and arch -pipe sections [83](#_Toc484690423)](#_Toc484690423) - -[Table 5‑6 Number of entries in geometric property tables for masonry -sewer shapes [85](#_Toc484690424)](#_Toc484690424) - -[Table 5‑7 Geometric parameters of masonry sewer sections -[85](#_Toc484690425)](#_Toc484690425) - -[Table 5‑8 Geometric properties for a sediment filled circular cross -section [87](#_Toc484690426)](#_Toc484690426) - -[Table 5‑9 Properties of the rectangular section of a -rectangular-triangular shape [88](#_Toc484690427)](#_Toc484690427) - -[Table 5‑10 Geometric parameters for rectangular-round shapes -[89](#_Toc484690428)](#_Toc484690428) - -[Table 5‑11 Geometric properties for rectangular--round shapes -[90](#_Toc484690429)](#_Toc484690429) - -[Table 5‑12 Properties in the rounded top section of a modified basket -handle shape [91](#_Toc484690430)](#_Toc484690430) - -[Table 5‑13 Area at maximum flow to full area for standard closed -conduits shapes [91](#_Toc484690431)](#_Toc484690431) - -[Table 5‑14 Critical depth formulas for simple section shapes -[101](#_Toc484690432)](#_Toc484690432) - -[Table 6‑1 Pump curves recognized by SWMM -[105](#_Toc484690433)](#_Toc484690433) - -[Table 6‑2 Kindsvater-Carter constants for rectangular weir coefficient -[118](#_Toc484690434)](#_Toc484690434) - -[Table 6‑3 Rectangular broad-crested weir coefficients (ft1/2/sec) -[119](#_Toc484690435)](#_Toc484690435) - -[Table 6‑4 Formulas for flow derivatives of various types of weirs -[123](#_Toc484690436)](#_Toc484690436) - -[Table 7‑1 Relative depth at maximum width for select cross section -shapes [129](#_Toc484690437)](#_Toc484690437) - -[Table 7‑2 Types of minor losses in drainage systems (from Frost, 2006) -[137](#_Toc484690438)](#_Toc484690438) - -[Table 7‑3 Hazen-Williams C-factors for different pipe materials -[139](#_Toc484690439)](#_Toc484690439) - -[Table 7‑4 Darcy-Weisbach roughness heights for different pipe materials -[140](#_Toc484690440)](#_Toc484690440) - -[Table C‑1 Circular section properties as function of area -[153](#_Toc484690441)](#_Toc484690441) - -[Table C‑2 Circular section properties as function of depth -[154](#_Toc484695150)](#_Toc484695150) - -[Table D‑1 Standard elliptical pipe sizes -[155](#_Toc484695151)](#_Toc484695151) - -[Table D‑2 Elliptical section properties as function of depth -[156](#_Toc484695152)](#_Toc484695152) - -[Table E‑1 Standard arch pipe sizes -[157](#_Toc484695153)](#_Toc484695153) - -[Table E‑2 Arch pipe section properties as function of depth -[160](#_Toc484695154)](#_Toc484695154) - -[Table F‑1 Area of masonry sewers as function of depth -[161](#_Toc484695155)](#_Toc484695155) - -[Table F‑2 Width of masonry sewers as function of depth - I -[162](#_Toc484695156)](#_Toc484695156) - -[Table F‑3 Width of masonry sewers as function of depth - II -[163](#_Toc484695157)](#_Toc484695157) - -[Table F‑4 Hydraulic radius of masonry sewers as function of depth -[164](#_Toc484695158)](#_Toc484695158) - -[Table F‑5 Depth of masonry sewers as function of area - I -[165](#_Toc484695159)](#_Toc484695159) - -[Table F‑6 Depth of masonry sewers as function of area - II -[167](#_Toc484695160)](#_Toc484695160) - -[Table F‑7 Section factor for masonry sewers as function of area - I -[169](#_Toc484695161)](#_Toc484695161) - -[Table F‑8 Section factor for masonry sewers as function of area - II -[171](#_Toc484695162)](#_Toc484695162) - -[Table G‑1 Manning's roughness coefficient n for open channels -[173](#_Toc484695163)](#_Toc484695163) - -[Table G‑2 Manning's roughness coefficient n for closed conduits -[177](#_Toc484695164)](#_Toc484695164) - -[Table G‑3 Manning's roughness coefficient n for corrugated steel pipe -[179](#_Toc484695165)](#_Toc484695165) - -[Table H‑1 Culvert codes [180](#_Toc484695166)](#_Toc484695166) - -[Table H‑2 Culvert coefficients [183](#_Toc484695167)](#_Toc484695167) - -# List of Symbols - - -| Symbol | Description | -| --- | --- | -| *A* | cross section flow area within a conduit (ft2) | -| $\overline{A}$ | average cross section flow area along a conduit (ft2) | -| $\overline{\overline{A}}$ | average cross section flow area along a conduit over a time period (ft2) | -| *Afull* | full cross section area of a conduit (ft2) | -| *Amax* | cross section area at depth where a conduit's section factor is a maximum (ft2) | -| *AO* | area of an orifice opening (ft2) | -| *ASP* | surface area of water ponded above a node (ft2) | -| *AS* | surface area of a node and its connected links (ft2) | -| *ASL* | surface area of flow within a link (ft2) | -| *ASlast2) | -| *ASmin* | minimum surface area associated with a node (ft2) | -| *ASN* | surface area associated with a storage node (ft2) | -| *AW* | area of a weir opening (ft2) | -| *b* | bottom or top width (depending on shape) of a conduit's cross section (ft) | -| *c* | wave celerity (ft/sec) | -| *cI* | inlet control constant for submerged culverts | -| *cW* | coefficient for a weir-type flow divider (ft1/2/sec) | -| *Cd* | orifice discharge coefficient (dimensionless) | -| *CHW* | Hazen-Williams C-factor coefficient (dimensionless) | -| *CO* | equivalent orifice constant for a surcharged weir (ft5/2/sec) | -| *Cr* | Courant number (dimensionless) | -| *Cw* | weir coefficient (ft1/2/sec) | -| *D* | circular pipe diameter (ft) | -| *et* | potential evaporation rate at time *t* (ft/sec) | -| *E* | elevation of a node's invert (ft) | -| *EC* | specific head at critical depth (ft) | -| *f* | Darcy-Weisbach friction factor (dimensionless) | -| *fC* | monthly climate adjustment factor (dimensionless) | -| *fE* | storage node evaporation factor (dimensionless) | -| *fS* | weir submergence adjustment factor (dimensionless) | -| *F* | cumulative depth of infiltrated water (ft) | -| *Fr* | Froude number (dimensionless) | -| *g* | acceleration of gravity (ft/sec2) | -| *hL* | minor head loss per unit length of a conduit (ft/ft) | -| *hW* | height of the opening for a weir-type flow divider node (ft) | -| *H* | hydraulic head (ft) | -| *Hcrown* | elevation of the crown of the highest conduit at a node (ft) | -| *He* | effective head seen by an orifice or weir (ft) | -| *HIS* | minimum head at a culvert's inlet for it to be submerged (ft) | -| *HIU* | maximum head at a culvert's inlet for it to be unsubmerged (ft) | -| *Hmax* | maximum head at a node before flooding occurs (ft) | -| *HOutfall* | head assigned to an outfall node (ft) | -| *K* | cross section flow conductance (cfs) (equal to $nAR^{2/3}$) | -| *KI* | inlet control constant for unsubmerged culverts | -| *Km* | minor loss coefficient (dimensionless) | -| *KS* | soil saturated hydraulic conductivity (ft/sec) | -| *L* | conduit length or weir crest length (ft) | -| *Le* | effective weir crest length (ft) | -| *MI* | inlet control exponent for unsubmerged culverts | -| *n* | Manning roughness coefficient (sec/m1/3) | -| *P* | wetted perimeter of a conduit's cross section (ft) | -| *qE* | uniformly distributed evaporation rate along a channel (cfs/ft) | -| *qL* | total uniformly distributed outflow rate along a conduit (cfs/ft) | -| *qMIN* | minimum flow needed to activate a flow divider node (cfs) | -| *qS* | uniformly distributed seepage rate along a conduit (cfs/ft) | -| *qSN* | seepage rate per unit area for a storage node (cfs/ft2) | -| *Q* | flow rate within a conduit, pump, or regulator link (cfs) | -| *Qdiv* | flow rate diverted to a second outflow conduit from a flow divider node (cfs) | -| *QEN* | evaporation loss rate from a storage unit node (cfs) | -| *Qfull* | normal uniform flow rate for a full conduit (cfs) | -| *QIC* | culvert flow rate under inlet control (cfs) | -| *Qin* | total inflow rate to a node (cfs) | -| *QLN* | total loss rate from a storage unit node (cfs) | -| *Qnorm* | normal uniform flow rate (cfs) | -| *Qout* | total outflow rate leaving a node (cfs) | -| *Qovfl* | excess flow that overflows a node (cfs) | -| ${\overline{Q}}_{net}$ | average net inflow minus outflow over a time step (cfs) | -| *QSN* | seepage loss rate from a storage node (cfs) | -| *R* | hydraulic radius of flow cross section in a conduit (ft) | -| $\overline{R}$ | average hydraulic radius of flow cross sections along a conduit (ft) | -| *Re* | Reynolds number (dimensionless) | -| *Rfull* | hydraulic radius of a conduit cross section when full (ft) | -| *s* | seepage rate per unit area for a conduit (ft/sec) | -| *Scf* | culvert slope correction factor | -| *Sf* | friction slope (ft/ft) | -| *S0* | conduit slope (ft/ft) | -| *t* | time (sec) | -| *U* | flow velocity at a point along a conduit (ft/sec) | -| $\overline{U}$ | average flow velocity along a conduit (ft/sec) | -| *V* | node assembly volume (ft3) | -| *VP* | ponded volume (ft3) | -| *VN* | storage node volume (ft3) | -| *VNfull* | volume of a storage node when full (ft3) | -| *W* | top width of the water surface at a point along a conduit (ft) | -| $\overline{W}$ | average top width of the water surface along a conduit (ft) | -| *Wmax* | maximum width of a conduit cross section (ft) | -| *x* | horizontal distance (ft) | -| *y* | vertical distance (ft) | -| *yI* | inlet control constant for submerged culverts | -| *Y* | depth of flow within a conduit or of water in a storage unit (ft) | -| $\overline{Y}$ | average depth of flow along a conduit (ft) | -| *Yc* | critical depth within a conduit at a given flow rate (ft) | -| *Yfull* | full depth of a conduit, orifice opening or weir height (ft) | -| *YN* | normal flow depth (ft) | -| *Y\** | smaller of the critical and normal flow depth in a conduit (ft) | -| *Z* | elevation of a conduit's invert (ft) | -| *ZO* | elevation of the bottom of an orifice's opening (ft) | -| *ZW* | elevation of a weir's crest in its lowest position (ft) | -| *α* | generic coefficient | -| *β* | the square root of a conduit's slope divided by its roughness | -| *∆t* | time step (sec) | -| *ε* | convergence tolerance | -| $\epsilon$ | Darcy-Weisbach roughness length (ft) | -| *γ* | exponent in power law cross section shape | -| *η* | Manning's roughness coefficient (sec/ft1/3) $\left( equal\ to\ \frac{n}{1.486} \right)$ | -| *σ* | inertial damping factor | -| *θ* | time weighting factor, relaxation factor, or subtended angle | -| *φ* | distance weighting factor | -| *θd* | soil moisture deficit (dimensionless) | -| *μ* | kinematic viscosity (ft2/sec) | -| *ω* | pump speed setting or degree to which a regulator is opened | -| $\psi_{S}$ | soil capillary suction head (ft) | -| *Ψ* | conduit section factor (equal to $AR^{2/3}$) (ft8/3) | -| *Ψfull* | section factor of a conduit at full depth (ft8/3) | -| *Ψmax* | maximum section factor for a conduit (ft8/3) | - - -# - SWMM Overview - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -## 1.1 Introduction - -Urban runoff quantity and quality constitute problems of both a -historical and current nature. Cities have long assumed the -responsibility of control of stormwater flooding and treatment of point -sources (e.g., municipal sewage) of wastewater. Since the 1960s, the -severe pollution potential of urban nonpoint sources, principally -combined sewer overflows and stormwater discharges, has been recognized, -both through field observation and federal legislation. The advent of -modern computers has led to the development of complex, sophisticated -tools for analysis of both quantity and quality pollution problems in -urban areas and elsewhere (Singh, 1995). The EPA Storm Water Management -Model, SWMM, first developed in 1969-71, was one of the first such -models. It has been continually maintained and updated and is perhaps -the best known and most widely used of the available urban runoff -quantity/quality models (Huber and Roesner, 2013). - -SWMM is a dynamic rainfall-runoff simulation model used for single event -or long-term (continuous) simulation of runoff quantity and quality from -primarily urban areas. The runoff component of SWMM operates on a -collection of subcatchment areas that receive precipitation and generate -runoff and pollutant loads. The routing portion of SWMM transports this -runoff through a system of pipes, channels, storage/treatment devices, -pumps, and regulators. SWMM tracks the quantity and quality of runoff -generated within each subcatchment, and the flow rate, flow depth, and -quality of water in each pipe and channel during a simulation period -comprised of multiple time steps. - -Table 1-1 summarizes the development history of SWMM. The current -edition, Version 5, is a complete re-write of the previous releases. The -reference manual for this edition of SWMM is comprised of three volumes. -Volume I describes SWMM's hydrologic models, Volume II its hydraulic -models, and Volume III its water quality and low impact development -models. These manuals complement the SWMM 5 User's Manual (US EPA, -2010), which explains how to run the program, and the SWMM 5 -Applications Manual (US EPA, 2009) which presents a number of worked-out -examples. The procedures described in this reference manual are based on -earlier descriptions included in the original SWMM documentation -(Metcalf and Eddy et al., 1971a, 1971b, 1971c, 1971d), intermediate -reports (Huber et al., 1975; Heaney et al., 1975; Huber et al., 1981), -plus new material. This information supersedes the Version 4.0 -documentation (Huber and Dickinson, 1988; Roesner et al., 1992) and -includes descriptions of some newer procedures implemented since 1988. -More information on current documentation and the general status of the -EPA Storm Water Management Model as well as the full program and its -source code is available on the EPA SWMM web site:. -. - -+----------------+----------+--------------------+-----------------------+ -| **Version** | **Year** | **Contributors** | **Comments** | -+:===============+:=========+:===================+:======================+ -| SWMM I | 1971 | Metcalf & Eddy, | First version of | -| | | Inc. | SWMM; focus was CSO | -| | | | modeling; Few of its | -| | | Water Resources | methods are still | -| | | Engineers | used today. | -| | | | | -| | | University of | | -| | | Florida | | -+----------------+----------+--------------------+-----------------------+ -| SWMM II | 1975 | University of | First widely | -| | | Florida | distributed version | -| | | | of SWMM. | -+----------------+----------+--------------------+-----------------------+ -| SWMM 3 | 1981 | University of | Full dynamic wave | -| | | Florida | flow routine, | -| | | | Green-Ampt | -| | | Camp Dresser & | infiltration, snow | -| | | McKee | melt, and continuous | -| | | | simulation added. | -+----------------+----------+--------------------+-----------------------+ -| SWMM 3.3 | 1983 | US EPA | First PC version of | -| | | | SWMM. | -+----------------+----------+--------------------+-----------------------+ -| SWMM 4 | 1988 | Oregon State | Groundwater, RDII, | -| | | University | irregular channel | -| | | | cross-sections and | -| | | Camp Dresser & | other refinements | -| | | McKee | added over a series | -| | | | of updates throughout | -| | | | the 1990's. | -+----------------+----------+--------------------+-----------------------+ -| SWMM 5 | 2005 | US EPA | Complete re-write of | -| | | | the SWMM engine in C; | -| | | CDM-Smith | graphical user | -| | | | interface added; | -| | | | improved algorithms | -| | | | and new features | -| | | | (e.g., LID modeling) | -| | | | added. | -+----------------+----------+--------------------+-----------------------+ - -: []{#_Toc484690413 .anchor}**Table 1‑1 Development history of SWMM** - -## 1.2 SWMM's Object Model - -Figure 1-1 depicts the elements included in a typical urban drainage -system. SWMM conceptualizes this system as a series of water and -material flows between several major environmental compartments. These -compartments include: - -
- -

Figure 1‑1 Elements of a typical urban -drainage system

-
- -- The Atmosphere compartment, which generates precipitation and deposits - pollutants onto the Land Surface compartment. - -- The Land Surface compartment receives precipitation from the - Atmosphere compartment in the form of rain or snow. It sends outflow - in the forms of 1) evaporation back to the Atmosphere compartment, 2) - infiltration into the Sub-Surface compartment and 3) surface runoff - and pollutant loadings on to the Conveyance compartment. - -- The Sub-Surface compartment receives infiltration from the Land - Surface compartment and transfers a portion of this inflow to the - Conveyance compartment as groundwater interflow. - -- The Conveyance compartment contains a network of elements (channels, - pipes, pumps, and regulators) and storage/treatment units that convey - water to outfalls or to treatment facilities. Inflows to this - compartment can come from surface runoff, groundwater interflow, - sanitary dry weather flow, or from user-defined time series. - -Not all compartments need appear in a particular SWMM model. For -example, one could model just the Conveyance compartment, using -pre-defined hydrographs and pollutographs as inputs. As illustrated in -Figure 1-1, SWMM can be used to model any combination of stormwater -collection systems, both separate and combined sanitary sewer systems, -as well as natural catchment and river channel systems. - -Figure 1-2 shows how SWMM conceptualizes the physical elements of the -actual system depicted in Figure 1-1 with a standard set of modeling -objects. The principal objects used to model the rainfall/runoff process -are Rain Gages and Subcatchments. Snowmelt is modeled with Snow Pack -objects placed on top of subcatchments while Aquifer objects placed -below subcatchments are used to model groundwater flow. The conveyance -portion of the drainage system is modeled with a network of Nodes and -Links. Nodes are points that represent simple junctions, flow dividers, -storage units, or outfalls. Links connect nodes to one another with -conduits (pipes and channels), pumps, or flow regulators (orifices, -weirs, or outlets). Land Use and Pollutant objects are used to describe -water quality. Finally, a group of data objects that includes Curves, -Time Series, Time Patterns, and Control Rules, are used to characterize -the inflows and operating behavior of the various physical objects in a -SWMM model. Table 1-2 provides a summary of the various objects used in -SWMM. Their properties and functions will be described in more detail -throughout the course of this manual. - -
-Objects2 -

Figure 1‑2 SWMM's conceptual model of a -stormwater drainage system

-
- -+--------------+---------------+--------------------------------------+ -| **Category** | **Object | **Description** | -| | Type** | | -+:=============+:==============+:=====================================+ -| Hydrology | Rain Gage | Source of precipitation data to one | -| | | or more subcatchments. | -| +---------------+--------------------------------------+ -| | Subcatchment | A land parcel that receives | -| | | precipitation associated with a rain | -| | | gage and generates runoff that flows | -| | | into a drainage system node or to | -| | | another subcatchment. | -| +---------------+--------------------------------------+ -| | Aquifer | A subsurface area that receives | -| | | infiltration from the subcatchment | -| | | above it and exchanges groundwater | -| | | flow with a conveyance system node. | -| +---------------+--------------------------------------+ -| | Snow Pack | Accumulated snow that covers a | -| | | subcatchment. | -| +---------------+--------------------------------------+ -| | Unit | A response function that describes | -| | Hydrograph | the amount of sewer | -| | | inflow/infiltration (RDII) generated | -| | | over time per unit of instantaneous | -| | | rainfall. | -+--------------+---------------+--------------------------------------+ -| Hydraulics | Junction | A point in the conveyance system | -| | | where conduits connect to one | -| | | another with negligible storage | -| | | volume (e.g., manholes, pipe | -| | | fittings, or stream junctions). | -| +---------------+--------------------------------------+ -| | Outfall | An end point of the conveyance | -| | | system where water is discharged to | -| | | a receptor (such as a receiving | -| | | stream or treatment plant) with | -| | | known water surface elevation. | -| +---------------+--------------------------------------+ -| | Divider | A point in the conveyance system | -| | | where the inflow splits into two | -| | | outflow conduits according to a | -| | | known relationship. | -| +---------------+--------------------------------------+ -| | Storage Unit | A pond, lake, impoundment, or | -| | | chamber that provides water storage. | -| +---------------+--------------------------------------+ -| | Conduit | A channel or pipe that conveys water | -| | | from one conveyance system node to | -| | | another. | -| +---------------+--------------------------------------+ -| | Pump | A device that raises the hydraulic | -| | | head of water. | -| +---------------+--------------------------------------+ -| | Regulator | A weir, orifice or outlet used to | -| | | direct and regulate flow between two | -| | | nodes of the conveyance system. | -+--------------+---------------+--------------------------------------+ - -: []{#_Toc484690414 .anchor}**Table 1‑2 SWMM's modeling objects** - -**Table 1-2 Continued** - -+--------------+---------------+--------------------------------------+ -| **Category** | **Object | **Description** | -| | Type** | | -+:=============+:==============+:=====================================+ -| Water | Pollutant | A contaminant that can build up and | -| Quality | | be washed off of the land surface or | -| | | be introduced directly into the | -| | | conveyance system. | -| +---------------+--------------------------------------+ -| | Land Use | A classification used to | -| | | characterize the functions that | -| | | describe pollutant buildup and | -| | | washoff. | -+--------------+---------------+--------------------------------------+ -| Treatment | LID Control | A low impact development control, | -| | | such as a bio-retention cell, porous | -| | | pavement, or vegetative swale, used | -| | | to reduce surface runoff through | -| | | enhanced infiltration. | -| +---------------+--------------------------------------+ -| | Treatment | A user-defined function that | -| | Function | describes how pollutant | -| | | concentrations are reduced at a | -| | | conveyance system node as a function | -| | | of certain variables, such as | -| | | concentration, flow rate, water | -| | | depth, etc. | -+--------------+---------------+--------------------------------------+ -| Data Object | Curve | A tabular function that defines the | -| | | relationship between two quantities | -| | | (e.g., flow rate and hydraulic head | -| | | for a pump, surface area and depth | -| | | for a storage node, etc.). | -| +---------------+--------------------------------------+ -| | Time Series | A tabular function that describes | -| | | how a quantity varies with time | -| | | (e.g., rainfall, outfall surface | -| | | elevation, etc.). | -| +---------------+--------------------------------------+ -| | Time Pattern | A set of factors that repeats over a | -| | | period of time (e.g., diurnal hourly | -| | | pattern, weekly daily pattern, | -| | | etc.). | -| +---------------+--------------------------------------+ -| | Control Rules | IF-THEN-ELSE statements that | -| | | determine when specific control | -| | | actions are taken (e.g., turn a pump | -| | | on or off when the flow depth at a | -| | | given node is above or below a | -| | | certain value). | -+--------------+---------------+--------------------------------------+ - -## 1.3 SWMM's Process Models - -Figure 1-3 depicts the processes that SWMM models using the objects -described previously and how they are tied to one another. The -hydrological processes depicted in this diagram include: - -
-ProcessModels.png -

Figure 1‑3 Processes modeled by -SWMM

-
- -- time-varying precipitation - -- snow accumulation and melting - -- rainfall interception from depression storage (initial abstraction) - -- evaporation of standing surface water - -- infiltration of rainfall into unsaturated soil layers - -- percolation of infiltrated water into groundwater layers - -- interflow between groundwater and the drainage system - -- nonlinear reservoir routing of overland flow - -- infiltration and evaporation of rainfall/runoff captured by Low Impact - Development controls. - -The hydraulic processes occurring within SWMM's conveyance compartment -include: - -- external inflow of surface runoff, groundwater interflow, - rainfall-dependent infiltration/inflow, dry weather sanitary flow, and - user-defined inflows - -- unsteady, non-uniform flow routing through any configuration of open - channels, pipes and storage units - -- various possible flow regimes such as backwater, surcharging, reverse - flow, and surface ponding - -- flow regulation via pumps, weirs, and orifices including time- and - state-dependent control rules that govern their operation. - -Regarding water quality, the following processes can be modeled for any -number of user-defined water quality constituents: - -- dry-weather pollutant buildup over different land uses - -- pollutant washoff from specific land uses during storm events - -- direct contribution of rainfall deposition - -- reduction in dry-weather buildup due to street cleaning - -- reduction in washoff loads due to BMPs - -- entry of dry weather sanitary flows and user-specified external - inflows at any point in the drainage system - -- routing of water quality constituents through the drainage system - -- reduction in constituent concentration through treatment in storage - units or by natural processes in pipes and channels. - -The numerical procedures that SWMM uses to model the hydraulic processes -listed above are discussed in detail in subsequent chapters of this -volume. SWMM's hydrologic and water quality processes are described in -volumes I and III of this manual. - -## 1.4 Simulation Process Overview - -SWMM is a distributed discrete time simulation model. It computes new -values of its state variables over a sequence of time steps, where at -each time step the system is subjected to a new set of external inputs. -As its state variables are updated, other output variables of interest -are computed and reported. This process is represented mathematically -with the following general set of equations that are solved at each time -step as the simulation unfolds: - - -$$X_{t} = f(X_{t - 1},I_{t},P) \qquad \text{(1-1)}$$ - -$$Y_{t} = g(X_{t},P) \qquad \text{(1-2)}$$ - -where - -| Symbol | | Description | -| --- | --- | --- | -| *Xt* | = | a vector of state variables at time *t* | -| *Yt* | = | a vector of output variables at time *t* | -| *It* | = | a vector of inputs at time *t* | -| *P* | = | a vector of constant parameters | -| *f* | = | a vector-valued state transition function | -| *g* | = | a vector-valued output transform function | - - -

Figure 1‑4 Block diagram of SWMM's state -transition process

- - -The variables that make up the state vector *Xt* are listed in Table -1-3. This is a surprisingly small number given the comprehensive nature -of SWMM. All other quantities can be computed from these variables, -external inputs, and fixed input parameters. The meaning of some of the -less obvious state variables, such as those used for snow melt, is -discussed in other sections of this set of manuals. - -+----------------+--------------+---------------------------------+------------+ -| **Process** | **Variable** | **Description** | **Initial | -| | | | Value** | -+:===============+:=============+:================================+:===========+ -| Runoff | *d* | Depth of runoff on a | 0 | -| | | subcatchment surface | | -+----------------+--------------+---------------------------------+------------+ -| Infiltration\* | *tp* | Equivalent time on the Horton | 0 | -| | | curve | | -| +--------------+---------------------------------+------------+ -| | *Fe* | Cumulative excess infiltration | 0 | -| | | volume | | -| +--------------+---------------------------------+------------+ -| | *Fu* | Upper zone moisture content | 0 | -| +--------------+---------------------------------+------------+ -| | *T* | Time until the next rainfall | 0 | -| | | event | | -| +--------------+---------------------------------+------------+ -| | *P* | Cumulative rainfall for current | 0 | -| | | event | | -| +--------------+---------------------------------+------------+ -| | *S* | Soil moisture storage capacity | User | -| | | remaining | supplied | -+----------------+--------------+---------------------------------+------------+ -| Groundwater | *θu* | Unsaturated zone moisture | User | -| | | content | supplied | -| +--------------+---------------------------------+------------+ -| | *dL* | Depth of saturated zone | User | -| | | | supplied | -+----------------+--------------+---------------------------------+------------+ -| Snowmelt | *wsnow* | Snow pack depth | User | -| | | | supplied | -| +--------------+---------------------------------+------------+ -| | *fw* | Snow pack free water depth | User | -| | | | supplied | -| +--------------+---------------------------------+------------+ -| | *ati* | Snow pack surface temperature | User | -| | | | supplied | -| +--------------+---------------------------------+------------+ -| | *cc* | Snow pack cold content | 0 | -+----------------+--------------+---------------------------------+------------+ -| Flow Routing | *H* | Hydraulic head of water at a | User | -| | | node | supplied | -| +--------------+---------------------------------+------------+ -| | *Q* | Flow rate in a link | User | -| | | | supplied | -| +--------------+---------------------------------+------------+ -| | *A* | Flow area in a link | Inferred | -| | | | from *Q* | -+----------------+--------------+---------------------------------+------------+ -| Water Quality | *tsweep* | Time since a subcatchment was | User | -| | | last swept | supplied | -| +--------------+---------------------------------+------------+ -| | *mB* | Pollutant buildup on | User | -| | | subcatchment surface | supplied | -| +--------------+---------------------------------+------------+ -| | *mP* | Pollutant mass ponded on | 0 | -| | | subcatchment | | -| +--------------+---------------------------------+------------+ -| | *cN* | Concentration of pollutant at a | User | -| | | node | supplied | -| +--------------+---------------------------------+------------+ -| | *cL* | Concentration of pollutant in a | User | -| | | link | supplied | -+----------------+--------------+---------------------------------+------------+ - -: []{#_Toc484690415 .anchor}**Table 1‑3 State variables used by SWMM** - -\*Only a sub-set of these variables is used, depending on the user's -choice of infiltration method. - -Examples of user-supplied input variables *It* that produce changes to -these state variables include: - -- meteorological conditions, such as precipitation, air temperature, - evaporation rate and wind speed - -- externally imposed inflow hydrographs and pollutographs at specific - nodes of the conveyance system - -- dry weather sanitary inflows to specific nodes of the conveyance - system - -- water surface elevations at specific outfalls of the conveyance system - -- control settings for pumps and regulators. - -The output vector *Yt* that SWMM computes from its updated state -variables contains such reportable quantities as: - -- runoff flow rate and pollutant concentrations from each subcatchment - -- snow depth, infiltration rate and evaporation losses from each - subcatchment - -- groundwater table elevation and lateral groundwater outflow for each - subcatchment - -- total lateral inflow (from runoff, groundwater flow, dry weather flow, - etc.), water depth, and pollutant concentration for each conveyance - system node - -- overflow rate and ponded volume at each flooded node - -- flow rate, velocity, depth and pollutant concentration for each - conveyance system link. - -Regarding the constant parameter vector *P,* SWMM contains over 150 -different user-supplied constants and coefficients within its collection -of process models. Most of these are either physical dimensions (e.g., -land areas, pipe diameters, invert elevations) or quantities that can be -obtained from field observation (e.g., percent impervious cover), -laboratory testing (e.g., various soil properties), or previously -published data tables (e.g., pipe roughness based on pipe material). A -smaller remaining number might require some degree of model calibration -to determine their proper values. Of course not all parameters are -required for every project (e.g., the 14 groundwater parameters for each -subcatchment are not needed if groundwater is not being modeled). The -subsequent chapters of this manual carefully define each parameter and -make suggestions on how to estimate its value. - -A flowchart of the overall simulation process is shown in Figure 1-5. -The process begins by reading a description of each object and its -parameters from an input file whose format is described in the SWMM 5 -Users Manual (US EPA, 2010). Next the values of all state variables are -initialized, as is the current simulation time (T), runoff time -(Troff), and reporting time (Trpt). - -
- -

Figure 1‑5 Flow chart of SWMM's simulation -procedure

-
- -The program then enters a loop that first determines the time T1 at the -end of the current routing time step (∆Trout). If the current runoff -time Troff is less than T1, then new runoff calculations are -repeatedly made and the runoff time updated until it equals or exceeds -time T1. Each set of runoff calculations accounts for any precipitation, -evaporation, snowmelt, infiltration, ground water seepage, overland -flow, and pollutant buildup and washoff that can contribute flow and -pollutant loads into the conveyance system. - -Once the runoff time is current, all inflows and pollutant loads -occurring at time T are routed through the conveyance system over the -time interval from T to T1. This process updates the flow, depth and -velocity in each conduit, the water elevation at each node, the pumping -rate for each pump, and the water level and volume in each storage unit. -In addition, new values for the concentrations of all pollutants at each -node and within each conduit are computed. Next a check is made to see -if the current reporting time Trpt falls within the interval from T to -T1. If it does, then a new set of output results at time Trpt are -interpolated from the results at times T and T1 and are saved to an -output file. The reporting time is also advanced by the reporting time -step ∆T~rpt.~ The simulation time T is then updated to T1 and the -process continues until T reaches the desired total duration. SWMM's -Windows-based user interface provides graphical tools for building the -aforementioned input file and for viewing the computed output. - -## 1.5 Interpolation and Units - -SWMM uses linear interpolation to obtain values for quantities at times -that fall in between times at which input time series are recorded or at -which output results are computed. The concept is illustrated in Figure -1-6 which shows how reported flow values are derived from the computed -flow values on either side of it for the typical case where the -reporting time step is larger than the routing time step. One exception -to this convention is for precipitation and infiltration rates. These -remain constant within a runoff time step and no interpolation is made -when these values are used within SWMM's runoff algorithms or for -reporting purposes. In other words, if a reporting time falls within a -runoff time step the reported rainfall intensity is the value associated -with the start of the runoff time step. - -![[]{#_Toc401645532 .anchor}**Figure 1‑6 Interpolation of reported -values from computed -values**](VolumeII/media/media/image6.emf){width="6.1097222222222225in" -height="3.4194444444444443in"} - -The units of expression used by SWMM's input variables, parameters, and -output variables depend on the user's choice of flow units. If flow rate -is expressed in US customary units then so are all other quantities; if -SI metric units are used for flow rate then all other quantities use SI -metric units. Table 1-4 lists the units associated with each of SWMM's -major variables and parameters, for both US and SI systems. Internally -within the computer code all calculations are carried out using feet as -the unit of length and seconds as the unit of time. - -+------------------------+----------------------+----------------------+ -| **Variable or | **US Customary | **SI Metric Units** | -| Parameter** | Units** | | -+:=======================+:=====================+:=====================+ -| Area (subcatchment) | acres | hectares | -+------------------------+----------------------+----------------------+ -| Area (storage surface | square feet | square meters | -| area) | | | -+------------------------+----------------------+----------------------+ -| Depression Storage | inches | millimeters | -+------------------------+----------------------+----------------------+ -| Depth | feet | meters | -+------------------------+----------------------+----------------------+ -| Elevation | feet | meters | -+------------------------+----------------------+----------------------+ -| Evaporation | inches/day | millimeters/day | -+------------------------+----------------------+----------------------+ -| Flow Rate | cubic feet/sec (cfs) | cubic meters/sec | -| | | (cms) | -| | gallons/min (gpm) | | -| | | liters/sec (lps) | -| | 106 gallons/day | | -| | (mgd) | 106 liters/day | -| | | (mld) | -+------------------------+----------------------+----------------------+ -| Hydraulic Conductivity | inches/hour | millimeters/hour | -+------------------------+----------------------+----------------------+ -| Hydraulic Head | feet | meters | -+------------------------+----------------------+----------------------+ -| Infiltration Rate | inches/hour | millimeters/hour | -+------------------------+----------------------+----------------------+ -| Length | feet | meters | -+------------------------+----------------------+----------------------+ -| Manning's n | seconds/meter1/3 | seconds/meter1/3 | -+------------------------+----------------------+----------------------+ -| Pollutant Buildup | mass/acre | mass/hectare | -+------------------------+----------------------+----------------------+ -| Pollutant | milligrams/liter | milligrams/liter | -| Concentration | (mg/L) | (mg/L) | -| | | | -| | micrograms/liter | micrograms/liter | -| | (μg/L) | (μg/L) | -| | | | -| | organism | organism | -| | counts/liter | counts/liter | -+------------------------+----------------------+----------------------+ -| Rainfall Intensity | inches/hour | millimeters/hour | -+------------------------+----------------------+----------------------+ -| Rainfall Volume | inches | millimeters | -+------------------------+----------------------+----------------------+ -| Storage Volume | cubic feet | cubic meters | -+------------------------+----------------------+----------------------+ -| Temperature | degrees Fahrenheit | degrees Celsius | -+------------------------+----------------------+----------------------+ -| Velocity | feet/second | meters/second | -+------------------------+----------------------+----------------------+ -| Width | feet | meters | -+------------------------+----------------------+----------------------+ -| Wind Speed | miles/hour | kilometers/hour | -+------------------------+----------------------+----------------------+ - -: []{#_Toc484690416 .anchor}**Table 1‑4 Units of expression used by -SWMM** - -# - SWMM's Hydraulic Model - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -As mentioned in Chapter 1, SWMM models the conveyance portion of a -drainage system as a network of links connected together at nodes. -External flows from various sources enter the network at specific nodes, -are transported along links, are combined together and split apart at -internal nodes while filling and emptying the volume of storage nodes, -and exit the system at terminal nodes. Figure 2-1 shows how a physical -system of sewer lines and their appurtenances are abstracted into a -network of nodes and links of different types (pipe and pump links; -junction, storage and outfall nodes for this particular example). - -![SewerSystem2.png](VolumeII/media/media/image7.png){width="6.5in" -height="5.308333333333334in"} - -[]{#_Toc484694712 .anchor}**Figure 2‑1 Node-link representation of a -sewer system** - -**(Background from http://www.sewerhistory.org/photosgraphics/japan/)** - -Table 1-2 has already summarized the different types of node and link -objects that can appear in a SWMM conveyance network model. The -remainder of this chapter provides more details on the properties of -network objects, briefly describes and compares the capabilities of the -two principal methods used for analyzing the unsteady hydraulic behavior -of a network, and discusses the boundary and initial conditions needed -to compute network hydraulics. - -## 2.1 Network Components - -The two principal components of a SWMM conveyance system network are -nodes and links. Nodes represent the end points of conveyance links that -form the connection between two or more links. They are also the points -where external inflows (runoff, dry weather flows, etc.) can enter the -network or where internal flows leave the network. Links are conveyance -elements that transport flow between nodes. The following paragraphs -describe the different types of nodes and links that SWMM can model. - -### 2.1.1 Junction Nodes - -Junction nodes are points in the drainage system where conveyance links -join together. Physically they can represent the confluence of natural -surface channels, manholes in a sewer system, or pipe connection -fittings. Excess water at a junction can become partially pressurized -when connecting conduits are surcharged and can either be lost from the -system or be allowed to pond atop the junction and subsequently drain -back into the junction. - -The principal input parameters for a junction node are: - -- invert (channel or manhole bottom) elevation - -- height between its invert and the ground surface - -- additional pressure head that can be accepted before flooding occurs - -- ponded surface area when flooded. - -### 2.1.2 Outfall Nodes - -Outfall nodes are terminal nodes of the drainage system used to define -final downstream boundary locations. The boundary conditions at an -outfall can be described by any one of the following stage -relationships: - -- the critical or normal flow depth in the connecting conduit - -- a fixed stage elevation - -- a tidal stage described in a table of tide height versus hour of the - day - -- a user-defined time series of stage versus time. - -The principal input parameters for an outfall node are: - -- invert elevation - -- type of boundary condition and its associated stage data - -- presence of a flap gate to prevent backflow through the outfall. - -### 2.1.3 Flow Divider Nodes - -Flow divider nodes divert inflows to a specific link in a prescribed -manner. A flow divider can have no more than two conduit links on its -discharge side. There are four types of flow dividers, defined by the -manner in which inflows are diverted: - -- *Cutoff* diverts all inflow above a defined cutoff value. - -- *Overflow* diverts all inflow above the flow capacity of the - non-diverted conduit. - -- *Tabular* uses a table that expresses diverted flow as a function of - total inflow. - -- *Weir* uses a weir equation to compute diverted flow. - -The principal input parameters for a flow divider node are: - -- junction parameters (see above) - -- name of the link receiving the diverted flow - -- method used for computing the amount of diverted flow. - -### 2.1.4 Storage Unit Nodes - -Storage unit nodes are the only type of node that can provide storage -volume and possess surface area. Physically they could represent storage -facilities as small as a catch basin or as large as a lake. The -volumetric properties of a storage unit are described by a function or -table of surface area versus height. In addition to receiving inflows -and discharging outflows to other nodes in the drainage network, storage -nodes can also lose water from surface evaporation and from seepage into -native soil. Unlike other nodes, storage nodes are not allowed to -pressurize (i.e., they always maintain a free surface). - -The principal input parameters for a storage unit are: - -- invert (bottom) elevation - -- maximum depth - -- depth-surface area data - -- evaporation potential - -- seepage parameters. - -### 2.1.5 Conduit Links - -Conduit links are pipes or channels that move water from one node to -another in the conveyance network. Their cross-sectional shapes can be -selected from a variety of standard open and closed geometries. Custom -closed shapes for pipes and irregular cross-section profiles for open -channels can also be specified. Conduit geometry is discussed in more -detail in Chapter 5. - -The required input parameters for a conduit link are: - -- identities of the inlet and outlet nodes - -- offset height or elevation above the inlet and outlet node inverts - -- conduit length - -- Manning\'s roughness coefficient - -- cross-section shape and dimensions. - - ---------------------------------------------------------------------------------------------------------------------- - SWMM allows conduits to be offset some ![Link_offset.bmp](VolumeII/media/media/image8.png){width="1.853934820647419in" - distance above the invert of their height="1.8061942257217847in"} - connecting end nodes as shown in the figure - on the right. The offset can be specified - as either a distance above the invert - (i.e., the distance between points 1 and 2 - in the figure) or as the elevation of the - conduit's invert (i.e., the elevation of - point 1). Internally the offset is - maintained as an elevation. - ------------------------------------------- -------------------------------------------------------------------------- - SWMM also makes use of a conduit's slope in ![slope.png](VolumeII/media/media/image9.png){width="2.38575021872266in" - its hydraulic calculations. Slope is not height="1.5002099737532808in"} - provided directly as an input variable but - is instead computed from the elevation of a - conduit's end node inverts and its offsets. - Let *L* be the length of the conduit, *∆y* - be the difference in elevation and *∆x* the - horizontal distance between the invert at - each end of the conduit. Then from the - diagram on the right: - - - -$$\mathrm{\Delta}x = \sqrt{L^{2} - \mathrm{\Delta}y^{2}} \qquad \text{(2-1)}$$ - - - -and the conduit slope *S0* is: - - -$$S_{0} = \frac{\mathrm{\Delta}y}{\mathrm{\Delta}x} \qquad \text{(2-2)}$$ - - - -SWMM does not allow a slope of 0. Therefore it imposes a minimum value -of 0.001 ft on *∆y*. It also allows the user to set a non-zero value for -minimum slope which will override any smaller computed slope. - -SWMM uses the Manning equation to relate conduit flow rate to flow depth -and conduit bed or friction slope. It therefore requires the user to -supply a Manning's "*n*" coefficient that represents the roughness -characteristics of the conduit's surface. Values of the coefficient for -a wide range of channel types and pipe materials can be found in -Appendix G. - -Conduits can also include the following optional parameters: - -- presence of a flap gate to prevent reverse flow - -- entrance/exit loss coefficients - -- seepage rate - -- inlet geometry code number if the conduit acts as a culvert. - -The latter three properties are employed by the advanced modeling -features covered in Chapter 7 of this manual. - -### 2.1.6 Pump Links - -Pump links are used to lift water from an inlet node to an outlet node -at higher elevation. The principal input parameters for a pump include: - -- identities of its inlet and outlet nodes - -- pump curve data - -- initial on/off status - -- startup and shutoff depths. - -A pump curve describes the relation between a pump\'s flow rate and the -head at its inlet and outlet nodes. The inlet node's startup and shutoff -water depths are monitored continuously during the course of a -simulation to allow for automated control of the pump's on/off status. - -Pumps are directional devices that are not allowed to have reverse flow -through them. Their hydraulic performance is described in more detail in -Chapter 6. - -### 2.1.7 Flow Regulator Links - -Flow regulator links model structures or devices used to control and -divert flows within a conveyance system. They are typically used to -control releases from storage facilities, prevent unacceptable -surcharging, and divert flow to treatment facilities and interceptors. - -SWMM can model the following types of flow regulators: orifices, weirs, -and outlets. The hydraulic behavior of orifices and weirs is modeled -using standard rating curves (the nonlinear relation between hydraulic -head applied to the regulator and the flow rate through it). Outlets -utilize a user-supplied rating curve. - -The principal input parameters for a flow regulator link include: - -- identities of its inlet and outlet nodes - -- offset above the invert of its inlet node - -- dimensions of its opening (for orifices and weirs) - -- parameters that describe its rating curve - -- presence of a flap gate to prevent reverse flow. - -The hydraulic performance of regulator links is described in more detail -in Chapter 6. - -### 2.1.8 Control Rules - -Each pump and flow regulator has a setting property that can adjust: - -- a pump's on/off status - - - -- a pump's speed - -- the size of an orifice opening - -- the crest height of a weir - -- the flow through an outlet link - -The setting can be changed during a simulation by using control rules. -These specify conditions, such as water elevation at certain nodes, flow -in certain links, and simulation time, that trigger a specified change -in a link's setting. SWMM's hydraulic analysis methods take into account -the current setting for each pump and flow regulator in the conveyance -network. More details on the formats used for control rules can be found -in the SWMM 5 Users Manual (US EPA, 2010). - -## 2.2 Analysis Methods - -SWMM's hydraulics solves the equations of one-dimensional, gradually -varied, unsteady flow throughout a node-link network to determine the -water level at each node and the flow rate and flow depth within each -link at each time step of an extended simulation period. Flow routing of -inflow hydrographs along channels and sewers entails wave dispersion, -wave attenuation or amplification, and wave retardation or acceleration. -These wave characteristics constitute the hydraulics of flow routing or -propagation and are greatly affected by the geometric characteristics of -the conduits, the characteristics of sources and/or sinks, and by -initial and boundary conditions. - -The hydraulics of unsteady non-uniform flow is represented in SWMM by a -pair of partial differential equations of conservation of mass and -momentum known as the St. Venant equations. Simultaneous solution of -these equations for each conduit, coupled with a conservation of volume -at each node, provides information on the spatial and temporal variation -of water levels and discharge rates throughout the network. SWMM offers -the user two principal alternative methods for solving these equations - -dynamic wave or kinematic wave analysis - -Dynamic wave analysis solves the complete form of the St. Venant flow -equations and therefore produces the most theoretically accurate -results. It can account for channel storage, backwater effects, -entrance/exit losses, culvert flow, flow reversal, and pressurized flow. -Because it couples together the solution for both water levels at nodes -and flow in conduits it can be applied to any general network layout, -even those containing multiple downstream diversions and loops. It is -the method of choice for systems subjected to significant backwater due -to downstream flow restrictions and with flow regulation via weirs and -orifices. This generality comes at a price of having to use small time -steps to maintain numerical stability. - -Kinematic wave analysis solves the continuity equation along with a -simplified form of the momentum equation in each conduit. It cannot -account for backwater effects, entrance/exit losses, flow reversal, or -pressurized flow. It is most applicable to steeply sloped (e.g., \> -0.1%) conduits with shallow flow with high velocity. It can usually -maintain numerical stability with much larger large time steps than are -required for dynamic wave analysis. If the aforementioned effects are -not expected to be significant then this alternative can be an accurate -and efficient hydraulic analysis method, especially for long-term -simulations. - -Because kinematic wave analysis ignores both inertial and pressure -forces there are limits on its applicability: - -1. It can only analyze directed acyclic networks (where conduits are - oriented in the direction of positive slope and there are no paths - that start and end at the same node). - -2. Junction nodes can only have at most one outlet link which must be a - conduit. - -3. Divider nodes must have two outlet links which must be conduits. - -4. Storage nodes can have any number of outlet links of any type. - -5. Upstream offsets for conduits are ignored except at storage nodes. - -SWMM also offers a steady flow analysis option which assumes that within -each computational time step flow is uniform and steady. It simply -translates inflow hydrographs at the upstream end of a conduit to its -downstream end, with no delay or change in shape. The Manning equation -is used to relate flow rate to flow area (or depth). It is subject to -the same limitations as the kinematic wave method. Because it ignores -the dynamics of free surface wave propagation it is only appropriate for -rough preliminary analysis of long-term continuous simulations. - -Table 2-1 compares the features and limitations of the dynamic wave and -kinematic wave methods of hydraulic analysis. Dynamic wave solutions -tend to attenuate and disperse an inflow hydrograph as it routed -downstream through a series of conduits while kinematic wave solutions -show no attenuation, no dispersion, and some distortion of the -hydrograph shape. This behavior is depicted in Figure 2-2 from Miller -(1984) which shows the results of routing an inflow hydrograph down a -100-foot wide rectangular channel of 1% slope with a Manning's *n* of -0.06. - - **Feature** **Dynamic Wave** **Kinematic Wave** - -| | | | -| --- | --- | --- | -| Network topology | branched and looped | branched only | -| Flow splits | yes | with flow divider nodes | -| Adverse slopes | yes | no | -| Invert offsets | yes | ignored | -| Pumping | yes | only from storage nodes | -| Weirs and orifices | yes | only from storage nodes | -| Ponded overflows | yes | yes | -| Lateral seepage | yes | yes | -| Evaporation | yes | yes | -| Minor losses | yes | no | -| Culvert analysis | yes | no | -| Hydrograph attenuation | yes | no | -| Backwater effects | yes | no | -| Surcharge / | yes | no | -| Pressurization | | | -| Reverse flow | yes | no | -| Tidal effects | yes | no | - - - : []{#_Toc484690417 .anchor}**Table 2‑1 Features and limitations of - dynamic wave and kinematic wave solutions** - -![KWvsDW.png](VolumeII/media/media/image10.png){width="6.5in" -height="4.427083333333333in"} - -[]{#_Toc484694713 .anchor}**Figure 2‑2 Comparison of dynamic wave and -kinematic wave solutions** - -> **(from Miller, 1984)** - -## 2.3 Boundary and Initial Conditions - -### 2.3.1 Boundary Conditions - -There are two types of boundary conditions that a user must supply to a -SWMM conveyance network model: - -1. the hydraulic head to be maintained at each outfall node of the - network, - -2. the external inflow received by specific nodes of the network. - -Both types of conditions can vary with time. Outfall node heads are only -required for dynamic wave analysis. The options available for specifying -their values were described in Section 2.1.2. External inflows can -originate from any of the following sources: - -- subcatchment runoff - -- groundwater discharges - -- rainfall-dependent infiltration/inflow (RDII) - -- user-defined values. - -Time-dependent runoff, groundwater, and RDII inflows are normally -provided by SWMM's hydrology module (see Volume I). It automatically -links the computed flow from each of these sources at each time period -to their designated receiving node. (Each SWMM subcatchment object that -generates runoff is assigned a conveyance system node that receives this -runoff. See Figure 1-2.) - -User-defined external inflows can be attached to any node of the -network. They are typically used to describe dry weather sewage flows in -sanitary sewer systems, base flows in natural stream channels, or -inflows in the absence of any hydrologic modeling. They are expressed in -the following general format: - -Flow rate at time *t* = (baseline value) × (baseline pattern factor) + - -> (scale factor) × (time series value at time *t*) - -The baseline value is some constant. The baseline pattern is a -combination of repeating hourly, daily, and monthly multiplier factors -applied to the baseline value. The time series value is a time varying -value and the scale factor is a constant multiplier applied to each time -series value. Time series values can be specified at unequal intervals -of time with interpolation used to obtain values at intermediate times. - -### 2.3.2 Initial Conditions - -A set of initial conditions at time 0 for all node heads and link flows -in the conveyance network must be specified before a hydraulic analysis -can begin. The default is to set all these values to 0, with the user -having the option to specify initial heads at selected nodes and initial -flow rates in selected conduit links. - -Any initial flow rate assigned to a conduit link is assumed to represent -a uniform steady flow. Therefore its flow depth can be set to the normal -depth determined by the Manning equation as described in Section 5.5.2. -From this depth an initial cross-section flow area for the conduit can -be found which is required for kinematic wave analysis. - -For dynamic wave analysis, if a non-storage, non-outfall node has not -had an initial head assigned to it then it's initial head is set equal -to the average elevation of the initial flow depths in the conduits that -deliver flow into it. - -# - Dynamic Wave Analysis - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -The movement of water through a conveyance network of channels and pipes -is governed by the conservation of mass and momentum equations for -gradually varied, unsteady free surface flow. Dynamic wave analysis -solves the complete form of these equations and therefore produces the -most theoretically accurate results. It can account for channel storage, -backwater effects, entrance/exit losses, flow reversal, and pressurized -flow. Because it couples together the solution for both water levels at -nodes and flow in conduits it can be applied to any general network -layout, even those containing multiple downstream diversions and loops. -It is the method of choice for systems subjected to significant -backwater due to downstream flow restrictions and with flow regulation -via weirs and orifices. This generality comes at a price of having to -use small time steps to maintain numerical stability. - -Dynamic wave modeling was first introduced into version 3 of SWMM in -1981 as a separate program module known as EXTRAN (Extended Transport) -(Roesner et al., 1983). The node-link solution method it uses had its -origins in the Sacramento-San Joaquin Delta Model (Shubinski et al., -1965) and the WRE Transport Model (Kibler et al., 1975). Although more -powerful solution techniques are available (such as implicit finite -difference schemes (Cunge et al., 1980) and shock-capturing finite -volume schemes (Toro, 2001)), SWMM 5 continues to use EXTRAN's node-link -approach, with modifications made to enhance its stability, because of -its simplicity and versatility. - -## 3.1 Governing Equations - -The conservation of mass and momentum for unsteady free surface flow -through a channel or pipe are known as the St. Venant equations and can -be expressed as: - - -$$\frac{\partial A}{\partial t} + \frac{\partial Q}{\partial x} = 0 \qquad \text{Continuity} \qquad \text{(3-1)}$$ - -| | | | | -| --- | --- | --- | --- | -| | $\frac{\partial Q}{\partial t} + \frac{\partial\left( \frac{Q^{2}}{A} \right)}{\partial x} + gA\frac{\partial H}{\partial x} + gAS_{f} = 0$ | Momentum | (3-2) | - - -where - - *x* = distance (ft) - -| | | | -| --- | --- | --- | -| *t* | = | time (sec) | -| *A* | = | flow cross-sectional area (ft2) | -| *Q* | = | flow rate (cfs) | -| *H* | = | hydraulic head of water in the conduit (*Z + Y*) (ft) | -| *Z* | = | conduit invert elevation (ft) | -| *Y* | = | conduit water depth (ft) | -| *Sf< | /sub | >* = friction slope (head loss per unit length) | -| *g* | = | acceleration of gravity (ft/sec2) | - - -The derivation of these equations can be found in standard texts such as -Henderson (1966), Cunge et al. (1980) and French (1985). The assumptions -on which they are based are: - -1. flow is one dimensional - -2. pressure is hydrostatic - -3. the cosine of the channel bed slope angle is close to unity - -4. boundary friction can be represented in the same manner as for - steady flow. - -The friction slope *Sf* can be expressed in terms of the Manning -equation used to model steady uniform flow: - - -$$S_{f} = \left( \frac{n}{1.486} \right)^{2}\frac{Q|U|}{AR^{4/3}} \qquad \text{(3-3)}$$ - - - -where - - *n* = the Manning roughness coefficient (sec/m1/3) - -| | | | -| --- | --- | --- | -| *R* | = | the hydraulic radius of the flow cross-section (ft) | -| *U* | = | flow velocity, equal to $\frac{Q}{A}$ (ft/sec). | - - -and 1.486 converts from m1/3 to ft1/3. Use of the absolute value -sign on the velocity term makes *Sf* a directional quantity (since *Q* -can be either positive or negative) and ensures that the frictional -force always opposes the flow. Manning roughness coefficients for wide -range of channel surfaces and pipe materials can be found in Appendix G. - -For a specific cross-sectional geometry, the flow area *A* is a known -function of water depth *Y* which in turn can be obtained from the head -*H*. Thus the dependent variables in these equations are flow rate *Q* -and head *H*, which are functions of distance *x* and time *t*. To solve -these equations over a single conduit of length *L*, one needs a set of -initial conditions for *H* and *Q* at time 0 as well as boundary -conditions at *x* = 0 and *x* = *L* for all times *t*. - -The continuity equation 3-1 can be combined with the momentum equation -3-2 to produce the following form of the momentum equation for a conduit -(see sidebar below for details): - - -$$\frac{\partial Q}{\partial t} = 2U\frac{\partial A}{\partial t} + U^{2}\frac{\partial A}{\partial x} - gA\frac{\partial H}{\partial x} - gAS_{f} \qquad \text{(3-4)}$$ - - - -While this equation can be used to compute the time trajectory of flow -in a conduit, another relationship is needed to do likewise for heads. -SWMM's node -- link representation of the conveyance network, -conceptualized in Figure 3-1, does this by providing a continuity -relationship at junction nodes that connect conduits together within a -conveyance network. As shown in the figure, a continuous water surface -is assumed to exist between the water elevation at a node and in the -conduits that enter and leave it. Two types of nodes are possible. -Non-storage junction nodes are assumed to be points with zero volume and -surface area while storage nodes (such as ponds and tanks) contain both -volume and surface area. - -![Node-Link.bmp](VolumeII/media/media/image11.png){width="5.854166666666667in" -height="2.7916666666666665in"} - -[]{#_Toc484694714 .anchor}**Figure 3‑1 Node-link representation of a -conveyance network in SWMM** - -**(from Roesner et al, 1992).** - -Each "node assembly" consists of the node itself and half the length of -each link connected to it. Conservation of flow for the assembly -requires that the change in volume with respect to time equal the -difference between inflow and outflow. In equation terms: - - -$$\frac{\partial V}{\partial t} = \frac{\partial V}{\partial H}\frac{\partial H}{\partial t} = A_{S}\frac{\partial H}{\partial t} = \sum_{}^{}Q \qquad \text{(3-5)}$$ - - - -where: - - *V* = node assembly volume (ft3) - -| | | | -| --- | --- | --- | -| *AS< | /sub | >* = node assembly surface area (ft2) | -| *ΣQ* | = | net flow into the node assembly (inflow -- outflow) (cfs) | - - -The $\sum_{}^{}Q$ term includes the flow in the conduits connected to -the node as well as any externally imposed inflows such as wet weather -runoff or dry weather sanitary flow. - -Each node assembly's surface area consists of the node's storage surface -area *ASN* (if it's a storage node) plus the surface area contributed -by the links connected to it, $\sum_{}^{}A_{SL}$, where *A~SL\ ~*is the -surface area contributed by a connecting link. Thus the node continuity -equation can be written as: - - -$$\frac{\partial H}{\partial t} = \frac{\sum_{}^{}Q}{A_{SN} + \sum_{}^{}A_{SL}} \qquad \text{(3-6)}$$ - - - -The flow depth at the end of a conduit connected to a node can be -computed as the difference between the head at the node and the invert -elevation of the conduit. The node and link surface areas are computed -as functions of their respective flow depths. - -Equations 3-4 and 3-6 provide a coupled set of partial differential -equations that solve for flow *Q* in the conduits and head *H* at the -nodes of the conveyance network. Because they cannot be solved -analytically a numerical solution procedure must be used instead. - -## 3.2 Solution Method - -The material that follows applies to networks containing only conduits. -Inclusion of flow control devices (pumps, orifices, and weirs) and other -processes (seepage, evaporation, and minor losses) will be covered in -subsequent chapters of this manual. - -The spatial and temporal derivatives in equations 3-4 and 3-6 can be -replaced with the following finite difference approximations: - - -$$\frac{\partial A}{\partial x} = \frac{\left( A_{2} - A_{1} \right)}{L} \qquad \text{(3-7)}$$ - - - - -$$\frac{\partial H}{\partial x} = \frac{\left( H_{2} - H_{1} \right)}{L} \qquad \text{(3-8)}$$ - - - - -$$\frac{\partial A}{\partial t} = \frac{\mathrm{\Delta}\overline{A}}{\mathrm{\Delta}t} \qquad \text{(3-9)}$$ - - - - -$$\frac{\partial Q}{\partial t} = \frac{\mathrm{\Delta}Q}{\mathrm{\Delta}t} \qquad \text{(3-10)}$$ - - - - -$$\frac{\partial H}{\partial t} = \frac{\mathrm{\Delta}H}{\mathrm{\Delta}t} \qquad \text{(3-11)}$$ - - - -where - - *A1* = flow area at the upstream end of the conduit (ft2) - -| | | | -| --- | --- | --- | -| *A2* | | = flow area at the downstream end of the conduit (ft2) | -| *H1* | | = hydraulic head at the upstream end of the conduit (ft) | -| *H2* | | = hydraulic head at the downstream end of the conduit (ft) | -| *L* | = | conduit length (ft) | -| *∆t* | = | time step (sec) | -| *∆*$\ \overline{A}$ | = | change in average flow area, $\left( {\overline{A}}^{t + \mathrm{\Delta}t} - {\overline{A}}^{\ t} \right)$, over time step *∆t* (ft2) | -| *∆Q* | = | change in conduit flow, $\left( Q^{t + \mathrm{\Delta}t} - Q^{t} \right)$, over time step *∆t* (cfs) | -| *∆H* | = | change in nodal head, $\left( H^{t + \mathrm{\Delta}t} - H^{t} \right)$, over time step *∆t* (ft). | - - -with the superscripts referring to time periods. - -Substituting these finite difference approximations into the link -momentum Equation 3-4, replacing *Sf* with Equation 3-3, and replacing -*A, U*, and *R* with their average values over the conduit length (as -indicated by over scores) allows the finite difference form of the link -momentum equation to be written as: - - -$$\frac{\mathrm{\Delta}Q}{\mathrm{\Delta}t} = 2\overline{U}\frac{\mathrm{\Delta}\overline{A}}{\mathrm{\Delta}t} + {\overline{U}}^{2}\frac{\left( A_{2} - A_{1} \right)}{L} - g\overline{A}\frac{\left( H_{2} - H_{1} \right)}{L} - g\eta^{2}\frac{Q\left| \overline{U} \right|}{{\overline{R}}^{4/3}} \qquad \text{(3-12)}$$ - - - -where $\eta = \frac{n}{1.486}$. Average values for *A, U*, and *R* can -be approximated using the heads *H1* and *H2* as described later on -in section 3.3.1. - -The finite difference form of the nodal continuity equation 3-6 is: - - -$$\frac{\mathrm{\Delta}H}{\mathrm{\Delta}t} = \frac{\sum_{}^{}Q}{A_{SN} + \sum_{}^{}A_{SL}} \qquad \text{(3-13)}$$ - - - -Previous versions of SWMM used an explicit forward Euler method (or more -precisely the two-step Modified Euler method) to solve Equation 3-12, -where known values of *Q, H, A*, $\overline{A}$, $\overline{U}$, and -$\overline{R}$ at time *t* were used to solve for *Q* at time *t + ∆t*. -Then Equation 3-13 was solved with the new conduit flows to find new -head values *H* at time *t + ∆t*. - -SWMM 5 uses an implicit backwards Euler method instead to provide -improved stability (Ascher and Petzold, 1998). Under this scheme -Equation 3-12 is re-written as: - - -$$Q^{t + \mathrm{\Delta}t} = \frac{Q^{t} + {\mathrm{\Delta}Q}_{inertia} + {\mathrm{\Delta}Q}_{pressure}}{1 + {\mathrm{\Delta}Q}_{friction}} \qquad \text{(3-14)}$$ - - - -where - - -$${\mathrm{\Delta}Q}_{inertia} = 2\overline{U}\left( {\overline{A}}^{t + \mathrm{\Delta}t} - {\overline{A}}^{\ t} \right) + {\overline{U}}^{2}\frac{\left( A_{2} - A_{1} \right)}{L}\Delta t \qquad \text{(Inertial Term)} \qquad \text{(3-14a)}$$ - -| | | | | -| --- | --- | --- | --- | -| | ${\mathrm{\Delta}Q}_{pressure} = - g\overline{A}\frac{\left( H_{2} - H_{1} \right)}{L}\Delta t$ | (Pressure Term) | (3-14b) | -| | ${\mathrm{\Delta}Q}_{friction} = g\eta^{2}\frac{\left| \overline{U} \right|\Delta t}{{\overline{R}}^{4/3}}$ | (Friction Term) | (3-14c) | - - -and now *H* and the quantities *A*, $\overline{A}$, $\overline{U}$, and -$\overline{R}$ derived from it are all evaluated at the new time *t+∆t*. -The finite difference form of the nodal continuity equation 3-12 can be -expressed as: - - -$$H^{t + \mathrm{\Delta}t} = H^{t} + \frac{\frac{\Delta t}{2}\left( \sum_{}^{}{Q^{t} + \sum_{}^{}Q^{t + \mathrm{\Delta}t}} \right)}{\left( A_{SN} + \sum_{}^{}A_{SL} \right)^{t + \mathrm{\Delta}t}} \qquad \text{for non-outfall} \qquad \text{(3-15a)}$$ - - nodes - -| | | | | -| --- | --- | --- | --- | -| | $H^{t + \mathrm{\Delta}t} = H_{Outfall}$ | for outfall nodes | (3-15b) | - - -*HOutfall* is a user-supplied value that sets the head at a terminal -outfall node. It can be a constant value, a value extracted from a -user-supplied time series, or the elevation of the critical or normal -flow depth in the connecting conduit. For the latter option, critical or -normal depth is computed internally as a function of the conduit's flow -rate and geometry as described in Chapter 5. - -Equations 3-14 and 3-15 can be solved implicitly over a given time step -*∆t* using functional iteration (also known as successive approximations -or Picard's method). The method is described in the sidebar titled -"*Dynamic Wave Solution Procedure*". Because flows and heads are updated -one conduit and node at a time and not simultaneously, the results at -each time step are invariant to the order in which the conduits and -links are evaluated. This allows Steps 2 and 4 of the solution procedure -to be implemented using separate threads running in parallel on -multi-processor computers which can offer a significant reduction in -computation time. - -## 3.3 Computational Details - -### 3.3.1 Average Cross-Section Properties - -Evaluation of the flow updating formula 3-14 requires values for the -average area ($\overline{A}$), hydraulic radius ($\overline{R}$), and -velocity ($\overline{U}$) for the conduit in question. These values are -computed using heads *H1* and *H2* belonging to the most recently -computed head estimates *Hlast* at either end of the conduit. The flow -depth *Y1* at the upstream end of the conduit is computed as: - -+----+----------------------------------+----------------------------------------------+--------+ -| | $$Y_{1} = \left\{ \begin{matrix} | $$for\ H_{1} \leq Z_{1}$$ | (3-16) | -| | 0 \\ | | | -| | H_{1} - Z_{1} \\ | $$for\ Z_{1} < H_{1} \leq Z_{1} + Y_{full}$$ | | -| | Y_{full} | | | -| | \end{matrix} \right.\ $$ | $$for\ H_{1} > {Z_{1} + Y}_{full}$$ | | -+====+==================================+==============================================+========+ - -where Z*1* is the elevation of the invert of the upstream end of the -conduit and *Yfull* is the full depth of the conduit. A similar -expression using *H2* and *Z2* applies to *Y2* at the downstream -end of the conduit. - -Values of $\overline{A}$ and $\overline{R}$ are computed from the -conduit's cross section geometry at the average flow depth -$\frac{\overline{Y} = \left( Y_{1} + Y_{2} \right)}{2}$. Formulas for -doing so are described in Chapter 5 of this manual. The average velocity -$\overline{U}$ is found by dividing the most current flow value -*Qlast* by the average area $\overline{A}$. - -In addition, the average area and hydraulic radius used in the pressure -and friction terms of equation 3-14 are upstream weighted to reflect how -close a conduit's flow is to being supercritical. Supercritical flow is -influenced only by upstream conditions (i.e., wave disturbances -propagate only in the downstream direction). The weight is derived from -the Froude number *Fr* for *Qlast*: - - -$$Fr = \frac{\left| \overline{U} \right|}{\sqrt{g\frac{\overline{A}}{\overline{W}}}} \qquad \text{(3-17)}$$ - - - -where $\overline{W}$ is the top water surface width at the average depth -$\overline{Y}$. (*Fr* is set to 0 for closed conduits flowing full). A -factor *σ* is then computed as: - -+----+-----------------------------------+--------------------------------------+--------+ -| | $$\sigma = \left\{ \begin{matrix} | $$for\ Fr \leq 0.5$$ | (3-18) | -| | 1 \\ | | | -| | 2(1 - Fr) \\ | $$for\ 0.5 < Fr < 1$$ | | -| | 0 | | | -| | \end{matrix} \right.\ $$ | $$for\ Fr \geq 1$$ | | -+====+===================================+======================================+========+ - -It is used to modify the average area in Equation 3-14b and the average -hydraulic radius in Equation 3-14c as follows: - - -$${\overline{A}}' = A_{1} + \ \sigma\left( \overline{A} - A_{1} \right) \qquad \text{(3-19)}$$ - -| | | | -| --- | --- | --- | -| | ${\overline{R}}' = R_{1} + \ \sigma\left( \overline{R} - R_{1} \right)$ | (3-20) | - - -where *A1* and *R1* are the flow area and hydraulic radius, -respectively, based on the upstream flow depth *Y1*. - -### 3.3.2 Surface Area Calculations - -Under normal conditions the surface area that a conduit contributes to -its upstream node (*ASL1*) is the average top width of the water -surface over the upstream half of the conduit times half of the -conduit's length. In equation form: - - -$$A_{SL1} = \left( \frac{W\left( Y_{1} \right) + \ W(\overline{Y})}{2} \right)\frac{L}{2} \qquad \text{(3-21)}$$ - - - -where *W(Y)* is the flow cross-section top width at a given flow depth -*Y* and $\overline{Y} = \frac{\left( Y_{1} + Y_{2} \right)}{2}$. A -similar expression applies to the downstream surface area *ASL2*. -*W(Y)* is computed from the conduit's cross-section geometry as -described in Chapter 5. - -Because sewer systems are frequently built with pipe invert -discontinuities at manholes they can encounter free-fall conditions -where the water elevation in the node receiving flow is below the pipe's -invert elevation or the flow's critical depth. Also during periods of -filling or draining, conduits can have one end or the other dry. These -conditions require that adjustments be made to the way that flow depth -is assigned and to how surface area is computed. - -Figure 3-2 illustrates the various types of special flow conditions that -affect surface area calculations: - -1. Case one is the normal situation of subcritical flow where flow - depths and surface areas are computed as previously described. - -2. Case two represents a critical downstream condition. The conduit has - a downstream offset and the water level at the node is below the - flow's critical depth. The downstream depth is set equal to the - smaller of the critical depth and normal depth for the current flow - and all of the conduit's surface area is assigned to the upstream - node. - -3. Case three is a critical upstream condition. There is reverse flow - with a free-fall discharge into the upstream node. Adjustments - equivalent to those for case two are made but with the definitions - of upstream and downstream reversed. - -4. Case four depicts an upstream dry condition. The upstream end of the - conduit is dry and the water level at the downstream end is below - the upstream conduit invert. If there is an upstream invert offset - then no surface area is assigned to the upstream node. A - complementary set of rules applies to the opposite case of a - downstream dry condition. - -Table 3-1 summarizes the various flow conditions and the adjustments -that are made for each. Procedures for computing the critical depth and -normal depth for a given flow rate and cross-section geometry are -discussed in Chapter 5 of this manual. - -Finally, to guard against the nodal head change formula 3-15 from -becoming unbounded as surface area becomes vanishingly small, a global -minimum surface area *ASmin* is imposed as follows: - - -$$A_{S} = max\left( A_{Smin},\ A_{SN} + \sum_{}^{}A_{SL} \right) \qquad \text{(3-22)}$$ - - - -Its default value is 12.56 sq ft (i.e., the area of a 4-ft diameter -manhole) which can be overridden by the user. This is strictly a -computational device and does not add volume to a junction node (where -*ASN = 0*) nor change it into a storage node. - -![Pipe.bmp](VolumeII/media/media/image12.png){width="5.666666666666667in" -height="2.622649825021872in"} - -![SurfaceArea2.bmp](VolumeII/media/media/image13.png){width="4.864583333333333in" -height="3.2291666666666665in"} - -[]{#_Toc484694715 .anchor}**Figure 3‑2 Special flow conditions for -dynamic wave analysis** - -+-------------------------+-------------------------+--------------------------------------------------------------+ -| **Condition** | **Criteria** | **Adjustments** | -+=========================+=========================+:=============================================================+ -| Upstream Dry | *Y1 = 0* | *ASL1 = 0* if $H_{2} \leq Z_{1}$ | -| | | | -| | *Z1 \> E1* | otherwise use Upstream Critical adjustment | -+-------------------------+-------------------------+--------------------------------------------------------------+ -| Downstream Dry | *Y2 = 0* | *ASL2 = 0* if $H_{1} \leq Z_{2}$ | -| | | | -| | *Z2 \> E2* | otherwise use Downstream Critical adjustment | -+-------------------------+-------------------------+--------------------------------------------------------------+ -| Upstream Critical | *Q \< 0* | *Y1 = Y\** | -| | | | -| | *Z1 \> E1* | *H1 = Y\* + Z1* | -| | | | -| | *H1 -- Z1 \< Y\** | *ASL1 = 0* | -| | | | -| | | $$A_{SL2} = L\frac{\left( \overline{W} + W_{2} \right)}{2}$$ | -+-------------------------+-------------------------+--------------------------------------------------------------+ -| Downstream Critical | *Q \> 0* | *Y2 = Y\** | -| | | | -| | *Z2 \> E2* | *H2 = Y\* + Z2* | -| | | | -| | *H2 -- Z2 \< Y\** | *ASL2 = 0* | -| | | | -| | | $$A_{SL1} = L\frac{\left( \overline{W} + W_{1} \right)}{2}$$ | -+-------------------------+-------------------------+--------------------------------------------------------------+ -| Notes: | -| | -| 1. *E1* = upstream node invert elevation, *E2* = downstream node invert elevation. | -| | -| 2. *Z~1\ ~*= upstream conduit invert elevation, *Z2* = downstream conduit invert elevation. | -| | -| 3\. *Y\** = smaller of critical depth and normal depth at current conduit flow rate. | -| | -| 4\. Adjusted *H* values are only used in the flow updating Equation 3-14 and do not replace nodal head values. | -+------------------------------------------------------------------------------------------------------------------+ - -: []{#_Toc484690418 .anchor}**Table 3‑1 Surface area adjustments for -various dynamic wave flow conditions** - -### 3.3.3 Inertial Damping - -It has been found that reducing the contribution of the inertial terms -in the Saint Venant equation as the flow shifts between sub-critical and -supercritical states improves the solution's stability (see Fread et al. -(1996) where it is referred to as the Local Partial Inertia technique). -SWMM 5 offers the option to use the aforementioned σ factor to dampen -the inertial term ${\mathrm{\Delta}Q}_{inertia}$ in the flow updating -formula 3-14. As seen by equation 3-18, the factor is 1 for Froude -numbers up to 0.5, 0 for Froude numbers at 1 or higher, and varies -linearly in between. The damping factor σ is computed and applied on a -conduit by conduit basis. - -Another option offered by SWMM 5 is to ignore the inertial term -completely. This corresponds to the so-called local inertial formulation -of the St. Venant equation (de Almeida and Bates, 2013). It drops the -convective acceleration term -$\left( \frac{\partial\left( \frac{Q^{2}}{A} \right)}{\partial x} \right)$ -of the momentum equation 3-2 altogether resulting in -${\mathrm{\Delta}Q}_{inertia}$ being 0 in all conduits. (This is not the -same as the diffusion wave formulation which also drops the local -acceleration term $\left( \frac{\partial Q}{\partial t} \right)$ of the -momentum equation as well.) This option can also result in improved -stability particularly during periods of rapid flow change. - -### 3.3.4 Flow Limitations - -Each time a new flow is computed using Equation 3-14 it is checked to -see if it should be limited by the normal flow value for the upstream -flow depth and conduit slope. The following criteria are used to perform -this check: - -1. The computed flow is positive. - -2. The conduit is not flowing full. - -3. The conduit does not fall into any of the categories listed in Table - 3-1 (upstream / downstream dry or upstream / downstream critical). - -4. The water surface slope is less than the conduit's slope or the - flow's Froude number based on upstream velocity and depth is greater - than 1. - -The last criterion can be limited to just slope, just Froude number or -either slope or Froude number as a program option. When all of these -criteria are satisfied the flow is limited to be no greater than that -found by the Manning equation (*Qnorm*) using upstream conditions: - - -$$Q_{norm} = \frac{1.49}{n}A_{1}R_{1}^{2/3}\sqrt{S_{0}} \qquad \text{(3-23)}$$ - - - -where *S0* is the conduit slope. Two other flow limiting conditions -are also checked. If the conduit was assigned an upper flow limit then -the flow is not allowed to exceed that value. If the conduit contains a -flap gate and the computed flow is negative then the flow is set to 0. - -### 3.3.5 Surcharge Conditions - -SWMM defines a node to be in a surcharged condition when all conduits -connected to it are full or when the node's water level exceeds the -crown of the highest conduit connected to it (see Figure 3-3). It should -be noted that surcharged (or pressurized) flow can occur in a closed -conduit without either of its end nodes being surcharged. For example, -if the node water level in Figure 3-3 was above the invert of pipe N+1 -but below its crown, then pipes N and N-1 would remain pressurized -(assuming they were also full at their upstream ends) while the node -itself would no longer be surcharged. - -![Surcharge4.bmp](VolumeII/media/media/image14.png){width="4.191363735783027in" -height="4.183096019247594in"} - -[]{#_Toc484694716 .anchor}**Figure 3‑3 Illustration of a surcharged -node** - -When a node becomes surcharged there is no more volume available in the -conduits forming the node's assembly to absorb the difference between -inflow and outflow at the node. Thus $\frac{\partial V}{\partial t}$ in -the flow continuity Equation 3-5 is 0 and the surcharged nodal -continuity condition becomes: - - -$$\sum_{}^{}Q = 0 \qquad \text{(3-24)}$$ - - - -By itself, this equation is insufficient to update nodal heads at the -new time step since it only contains flows. In addition, because the -flow and head updating equations for the system are not solved -simultaneously, there is no guarantee that the condition will hold at -the surcharged nodes after a flow solution has been reached. - -To enforce the surcharge flow continuity condition, it can be expressed -in the form of a perturbation equation: - - -$$\sum_{}^{}\left\lbrack Q + \frac{\partial Q}{\partial H}\mathrm{\Delta}H \right\rbrack = 0 \qquad \text{(3-25)}$$ - - - -where *∆H* is the adjustment to the node's head that must be made to -achieve a flow balance. Solving for *∆H* yields: - - -$$\mathrm{\Delta}H = \frac{- \sum_{}^{}Q}{\sum_{}^{}\frac{\partial Q}{\partial H}} \qquad \text{(3-26)}$$ - - - -where the summations are made over all conduits that are connected to -the node in question. - -The gradient of flow in a conduit with respect to the head at either end -node can be evaluated by differentiating the flow updating equation 3-14 -resulting in: - - -$$\frac{\partial Q}{\partial H} = \frac{\frac{- g\overline{A}\mathrm{\Delta}t}{L}}{1 + \mathrm{\Delta}Q_{friction}} \qquad \text{(3-27)}$$ - - - -The numerator of $\frac{\partial Q}{\partial H}$ has a negative sign in -front of it because when evaluating ΣQ flow directed out of a node is -considered negative while flow into the node is positive. It is computed -for each link at the same time that the link's flow is updated at Step 2 -of the iterative process described in Section 3.3. The surcharge -equation 3-26 is analogous to the head updating formula used in the -Hardy Cross method for pressurized water distribution networks (Bhave, -1991). - -To accommodate node surcharging, Step 4 of the iterative process that -updates a node's head is modified as follows. First the node is checked -to see if it is in a surcharged state, i.e., that it is not a storage or -outfall node and has *Hlast* greater than the top of the highest -connecting conduit *Hcrown*. If it is not surcharged then Equation -3-15 is used as before to update its head. Otherwise the following -modified form of Equation 3-26 is used to estimate the new head *Hnew* -for time *t + ∆t*: - - -$$H^{new} = H^{last} + \frac{\alpha\sum_{}^{}Q^{new}}{(1 - \beta)\sum_{}^{}\left( \frac{\partial Q}{\partial H} \right)^{last} + \frac{\beta A_{S}^{last}}{\mathrm{\Delta}t}} \qquad \text{(3-28)}$$ - - - -where - -| Symbol | | Description | -| --- | --- | --- | -| *α* | = | 0.6 for upstream terminal nodes with only outflow links and 1.0 otherwise | -| *β* | = | $exp( - 15.0f_{H})$ | -| *fH* | = | $\frac{\left( H^{last} - E \right)}{\left( H_{crown} - E \right) - \ 1}$ | -| *Hcrown* | = | elevation of the crown of the node's highest connecting flowing conduit (ft) | -| *E* | = | elevation of the node's invert (ft) | -| $A_{S}^{last}$ | = | surface area of the node the last time it was not surcharged (ft2) | - -The *α* factor is used to reduce oscillations in head at upstream -terminal nodes that have only outflow links (Roesner et al., 1992). The -*β* factor helps to reduce fluctuations in head when the node first -begins to surcharge (Roesner et al., 1980). At low surcharge depths it -makes the denominator in the head update formula be a weighted -combination of the pure surcharge formula 3-26 and the surface area -formula 3-15. By the time that the water level rises 25% above the -highest conduit, the equation is 98% pure surcharge. - -The flow values used for $\sum_{}^{}Q$ are the new flow estimates found -from Step 3 of the solution procedure. The -$\frac{\partial Q}{\partial H}$ values are those that were last -evaluated at Step 2. And finally, empirical testing has shown that more -robust performance is obtained when under-relaxation is not applied to -*Hnew* at Step 5 of the solution procedure when surcharging occurs. - -### 3.3.6 Preissmann Slot - -As an alternative to the surcharge algorithm described in the previous -section, SWMM can utilize the Preissmann Slot Method (Cunge and Wegner, -1964) for handling pressurized flow in closed conduits. In this case the -conduit's cross-section is assumed to have a thin open slot at its top -which runs down its length. This permits the water level in the conduit -to exceed its full depth while only slightly increasing its flow area. -It thus becomes possible to compute a surface area contribution to the -conduit's end nodes once it reaches full depth. As a result, SWMM is -able to use its regular procedure for solving the open channel flow -equations 3-14 and 3-15 for all flow conditions without having to resort -to the surcharge algorithm. - -In theory the width of the slot should be determined based on having the -celerity of an open channel gravity wave equal the speed of a pressure -wave affected by the compressibility of the elastic pipe wall. This -would result in a slot width *wslot* equal to: - -> $w_{slot} = gA/c^{2}$ (3-29) - -where *g* is the acceleration of gravity, *A* is the conduit's -cross-sectional area when full and *c* is the speed of the pressure -wave. The latter quantity depends on the conduit's diameter, wall -thickness, and modulus of elasticity and typically ranges from a few -hundred to several thousand ft/sec (Yen, 2001). - -Some care is needed in choosing a slot width since too large a value -will result in reduced accuracy while too small a value can cause -numerical instabilities. There is also the issue of maintaining a smooth -transition between almost full flow and slot flow. The choice used by -SWMM is a modified version of a formula proposed by Sjőberg (1982) and -is given by: - -> $\frac{w_{slot}}{W_{\max}} = 0.5423\exp\left( - \left( \frac{Y}{Y_{full}} \right)^{2.4} \right)$ -> (3-30) - -where *Wmax* is the conduit's maximum width, *Yfull* is its full -depth, and Y is depth of flow. This equation applies to -$\frac{Y}{Y_{full}}$ values between 0.985257 and 1.7. Below this range -the slot is not used while above it the slot width relative to *Wmax* -is clamped at 0.01. The range's lower limit was chosen so that the width -computed from equation 3-30 is the same as the width across a circular -pipe at that flow depth. This helps produce a smooth transition between -open channel and pressurized flow regimes. - -When the slot method is employed, equation 3-16 is modified so that *Y* -is no longer limited by *Yfull*. When *Y* reaches the limit at which -the slot formula applies, its resulting width is used to compute the -surface area that a conduit contributes to its end nodes as described in -Section 3.3.2. It also contributes to the conduit's flow area when it -rises above the full depth. It is not used when computing the conduit's -hydraulic radius. - -### 3.3.7 Flooding and Ponding - -Each non-outfall node is assigned a maximum allowable head *Hmax* by -the user. It consists of both a maximum free water surface elevation -that can exist at the node plus an optional "surcharge" depth that -allows for pressurization. For example, if the node were a manhole -junction *Hmax* would typically be the ground surface elevation. If it -were a storage unit it would be the water surface elevation when the -unit is full. For a junction between natural channels it would be the -top of the highest channel. For a fitting that connects pipe segments -together it would be the top of the highest pipe. In the latter case a -large surcharge depth (such as several hundred feet) should be assigned -to the fitting junction so that the connected pipes can pressurize if -need be. A manhole junction might also be assigned a surcharge depth if -it has a bolted cover. - -Normally when the new head estimate *Hnew* at a node computed at Step -5 of the iterative solution process exceeds *Hmax* it is set equal to -*Hmax* and the node becomes flooded. The overflow rate *Qovfl* -associated with this condition is the average net flow rate (inflow -- -outflow) seen by the node over the current time step: - - -$$Q_{ovfl} = 0.5\left( \sum_{}^{}{Q^{t} + \sum_{}^{}Q^{t + \mathrm{\Delta}t}} \right) \qquad \text{(3-31)}$$ - - - -This flow is then lost from the system, the same as the flow entering a -terminal outfall node. - -The option exists for a junction node with no surcharge depth (and thus -always maintaining a free surface) to have excess flooded water pond -atop the node (see Figure 3-4). In this case the user assigns the node a -"ponded area" parameter, *AP*, that creates a virtual storage area on -top of the node and *Hnew* is no longer limited to *Hmax* . When -*Hnew* exceeds *Hmax* the ponded node is treated as a normal storage -node whose head is updated using the normal, non-surcharge formula -Equation 3-15 with *ASN = AP*. The only exception to this is when -the node transitions between having a head below *Hmax* to a flooded -head above *Hmax* (or vice versa) within a time step. In this case the -updated head is restricted to be just a small value above *Hmax* (or -below it in the opposite case) to avoid wide swings in head during the -transition. - -
-Surcharge5.bmp -

Figure 3‑4 Ponding of excess water above a -junction

-
- -When a node is allowed to pond, flooded water is not lost from the -system. The ponded depth above the node will rise during periods of flow -excess (i.e., inflow greater than outflow) and fall during periods of -flow deficit. A node with a large ponded area will see smaller changes -in ponded depth for a given flow excess (or deficit) than will one with -a small ponded area. Selection of which nodes can pond and their -respective ponded areas would depend on local topography, typically -occurring along flat sections or at sag points of the drainage system. - -### 3.3.8 Summary of Special Conditions - -Here is a summary of the special conditions that are applied to the -basic iterative solution process for dynamic wave analysis described -earlier in Section 3.2: - -1. Upstream weighting, based on the current flow's Froude number, is - applied to the average area in the pressure term and to the average - hydraulic radius in the friction term of the flow updating formula - 3-14 (see Section 3.3.1). - -2. Optional inertial damping, again based on the Froude number, is - applied to the inertial term of the flow updating formula 3-14 (see - Section 3.3.2). - -3. The surface area contributed by a conduit to its end nodes in the - head updating formula 3-15 is modified when either critical flow - depth or dry conditions occur (see Section 3.3.3). - -4. A conduit's updated flow is limited to the Manning normal flow if - warranted by water surface slope and/or Froude number criteria (see - Section 3.3.4). - -5. If SWMM's Surcharge Algorithm is used then the head updating formula - 3-15 is replaced with equation 3-28 when a node is in a surcharged - state (see Section 3.3.5). - -6. If SWMM's Slot Method is used then no adjustment to equation 3-15 is - necessary as the computed slot width will be used to compute surface - and flow areas in a full flowing conduit (see Section 3.3.6). - -7. If a node is assigned a ponded area then a virtual storage unit of - constant surface area is used along with equation 3-15 to update its - head when it exceeds the node's maximum value. Otherwise a node's - head cannot exceed its maximum value and any excess inflow it - receives is lost from the system (see Section 3.3.7). - -## 3.4 Numerical Stability - -The numerical stability of SWMM's dynamic wave results can be affected -by the choice of the simulation time step. Numerical instability is -characterized by oscillations in flow and water surface elevation that -do not dampen out over time. Another indicator of numerical instability -is a node which continues to "dry up" on each time-step despite a -constant or increasing inflow from upstream sources. - -Aside from examining the results for each conduit and node, SWMM 5 -provides two metrics in its Status Report that can help determine if a -solution shows signs of instability. One is the overall flow continuity -error for the system. This is the difference between inflow and outflow -for the entire system over the duration of the simulation. If this -number is greater than 5 to 10 percent then the cause may be numerical -instability (although other factors can affect the continuity error as -well). - -A second metric is a link's Flow Instability Index (FII). This index -counts the number of times that the flow value in a link is higher (or -lower) than the flow in both the previous and subsequent time periods. -The index is normalized with respect to the expected number of such -'turns' that would occur for a purely random series of values and can -range from 0 to 150. The Status Report identifies the links having the -five highest FII's. Unfortunately since the FII does not take into -account the magnitude of the flow fluctuations it cannot determine -whether the instability is of engineering significance or not. - -Stable explicit solutions of the St. Venant equations require that the -time step be no longer than the time it takes for a dynamic wave to -travel the length of the conduit (Cunge et al., 1980). This is known as -the Courant-Friedrichs-Lewy (CFL) condition and can be expressed as: - - -$$\mathrm{\Delta}t \leq \frac{L}{\left| \overline{U} + c \right|} \qquad \text{(3-30)}$$ - - - -where *c* is the wave celerity given by: - - -$$c = \sqrt{g\frac{\overline{A}}{\overline{W}}} \qquad \text{(3-31)}$$ - - - -An equivalent form of this condition can be written as: - - -$$\mathrm{\Delta}t \leq \frac{L}{\left| \overline{U} \right|}\left( \frac{Fr}{1 + Fr} \right)Cr \qquad \text{(3-32)}$$ - - - -where *Fr* is the flow's Froude number (see Equation 3-17) and *Cr* is -the Courant number. The latter serves as an adjustment parameter that -determines how conservative (*Cr* \< 1) or liberal (*Cr* \> 1) one -wishes to be in strictly meeting the CFL condition (*Cr* = 1). - -Although the SWMM 5 solution method uses an iterative implicit procedure -in time to update flows and heads, it does so one conduit and node at a -time, not simultaneously. There is no spatial coupling between elements -as would occur in an unconditionally stable implicit solution scheme. -Thus the CFL condition would still apply but perhaps not as strictly (by -allowing one to use a *Cr* value greater than 1). - -One can estimate a *∆t* for each conduit by using the conduit's full -depth *Yfull* in place of $\frac{\overline{A}}{\overline{W}}$ in -Equation 3-31 and ignoring the velocity in Equation 3-30. The solution -time step would then be determined by the conduit with the smallest -value of $\frac{L}{\sqrt{gY_{full}}}$ . Short conduits lead to small -time steps and longer computational times. Time steps of 10 to 30 -seconds should suffice for conduit lengths of 200 to 400 feet (the -typical spacing between sewer manholes) and full depths from 1 to 4 -feet. - -An option is available to artificially lengthen short conduits so that -the CFL condition for a given user-supplied time step *∆t* is met. The -modified length $L'$ is given by - - -$$L' = max\left\{ L,\ \mathrm{\Delta}t\left( \sqrt{gY_{full}\ } + \frac{Q_{full}}{A_{full}} \right) \right\} \qquad \text{(3-33)}$$ - - - -where *Qfull* is the Manning's normal flow value (Equation 3-23) -evaluated at full depth *Y~full\ ~*and *Afull* is the flow area at -full depth. This modified length is used in place of the original length -in the equations presented in section 3.4. To make the artificially -lengthened conduit have a flow resistance equivalent to the original -length, its slope *S0* and roughness coefficient *n* are adjusted so -that the Manning equation produces an equal head loss across both the -original and lengthened conduit for any given flow. The modified slope -$S_{0}'$ for the lengthened conduit is: - - -$$S_{0}' = S_{0}\sqrt{\frac{L}{L'}} \qquad \text{(3-34)}$$ - - - -while its modified roughness $n'$ is: - - -$$n' = n\sqrt{\frac{L}{L'}} \qquad \text{(3-35)}$$ - - - -The conduit lengthening option is applied to all conduits whenever the -user supplies a non-zero value for the "lengthening" time step to be -used in equation 3-33. This time step does not have to be the same as -the computational time step used to solve the dynamic wave equations. - -Another option available in SWMM 5 is to have the program use a variable -computational time step that is adjusted throughout the simulation. The -user supplies values of the smallest allowable time step (*∆tmin*), -the largest allowable time step (*∆tmax*) and a desired Courant number -(*Cr*) to be met. At any time *t*, the next time step is computed from -the smaller of: - -1. The smallest value of - - $$\frac{L}{\left| \overline{U} \right|}\left( \frac{Fr}{1 + Fr} \right)Cr$$ - - -> for all conduits with non-negligible Fr. - -2. The smallest value of - - $$\frac{0.25\left( H_{crown} - E \right)}{{\mathrm{\Delta}H}^{t}}$$ - - -> for all non-outfall nodes that are not surcharged. - -The second condition guards against an excessive change in node head -over a single time step. Both conditions are evaluated using the flow -and head solutions found at time *t* (${\mathrm{\Delta}H}^{t}$ is the -change in head found from the prior time step). The resulting time step -is not allowed to be less than *∆tmin* nor greater than *∆tmax*. The -initial time step used at time 0 is *∆tmin*. - -To illustrate these concepts consider a 2 ft x 2 ft rectangular conduit -that is 2,000 ft long with a 0.05% slope and has a Manning's roughness -of 0.015 (see Figure 3-5). When divided into 10 equal length sections of -200 ft each the estimated stable time step is -$\frac{200}{\sqrt{32.2 \times 2} = 25}$ seconds. When analyzed as just a -single 2,000 ft long section it increases to 250 seconds. - -![Example1a.png](VolumeII/media/media/image16.png){width="6.5in" -height="3.240972222222222in"} - -[]{#_Toc484694718 .anchor}**Figure 3‑5 Profile view of example -rectangular conduit (not to scale)** - -Figure 3-6 shows the outflow hydrographs for these two analysis options -for a 1-hour sinusoidal inflow hydrograph with peak flow of 10 cfs (the -dotted curve in the figure). Both results are completely stable. The -option with the higher spatial resolution produces a more skewed -hydrograph with a slightly lower peak. - -
-Example1b.png -

Figure 3‑6 Outflow hydrographs for example -conduit -I

-
- -Now consider what happens when the 10-section conduit is analyzed with a -fixed time step of 120 seconds which is much larger than the stable -fixed step of 25 seconds. As shown in Figure 3-7 the solution becomes -completely unstable. When 120 seconds is used as the upper limit of a -variable time step a stable result is produced. In this case SWMM's -Status Report shows that the variable time step ranged from 24 to 120 -seconds with the average being 42. - -
-Example1c.png -

Figure 3‑7 Outflow hydrographs for example -conduit – II

-
- -# - Kinematic Wave Analysis - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -The kinematic wave model is derived from a simplified form of the St. -Venant equations that combines the continuity equation with the uniform -flow equation. It cannot model pressurized flow, reverse flow, or -backwater effects. It is most applicable to steeply sloped conduits -subjected to long duration inflow hydrographs that produce shallow flow -with high velocity (Ponce et al., 1978). For these situations its -results will not be far off from those of dynamic wave analysis and can -be computed much more efficiently using much larger time steps. - -Kinematic wave modeling was included in the original release of SWMM in -1971 before a full dynamic wave option was available. The original -method included an enhancement to approximate a backwater effect for -sub-critical flow. SWMM 5 has dropped this enhancement in favor of the -classical kinematic wave formulation since the code now includes a full -dynamic wave option (described in the previous chapter) that rigorously -models backwater effects. - -## 4.1 Governing Equations - -The kinematic wave model for unsteady flow in a channel or pipe is -derived from the same St. Venant equations for conservation of mass and -momentum that were used for dynamic wave analysis: - - -$$\frac{\partial A}{\partial t} + \frac{\partial Q}{\partial x} = 0 \qquad \text{Continuity} \qquad \text{(4-1)}$$ - -| | | | | -| --- | --- | --- | --- | -| | $\frac{\partial Q}{\partial t} + \frac{\partial\left( \frac{Q^{2}}{A} \right)}{\partial x} + gA\frac{\partial H}{\partial x} + gAS_{f} = 0$ | Momentum | (4-2) | - - -where all variables were defined previously in Chapter 3. Expressing -head *H* as *Z + Y* (invert elevation plus flow depth) and recognizing -that $\frac{\partial Z}{\partial x = {- S}_{0}}$ (the conduit's slope) -allows one to write the momentum equation as: - - -$$\frac{\partial Q}{\partial t} + \frac{\partial\left( \frac{Q^{2}}{A} \right)}{\partial x} + gA\frac{\partial Y}{\partial x} = gA(S_{0} - S_{f}) \qquad \text{(4-3)}$$ - - - -If one assumes that the terms on the left hand side of Equation 4-3 are -negligible one is left with the relation: - - -$$S_{0} = S_{f} \qquad \text{(4-4)}$$ - - - -Having the conduit's bottom slope equal the friction slope implies that -the fluid motion caused by gravity is balanced by the frictional -resistance to flow. Using the Manning equation to represent the friction -slope allows one to represent the relationship between flow rate *Q* and -flow area *A* with Manning's equation for steady uniform flow: - - -$$Q = \frac{AR^{2/3}\sqrt{S_{0}}}{\eta} \qquad \text{(4-5)}$$ - - - -where the hydraulic radius *R* is an implicit function of flow area *A* -for a specific conduit cross-sectional shape. (*R* is defined as area -divided by wetted perimeter where the latter can be determined from flow -depth which can be inferred from the flow area *A*.) - -By defining $\beta = \frac{\sqrt{S_{0}}}{\eta}$ and $\Psi = AR^{2/3}$ -the Manning equation can be expressed as: - - -$$Q = \beta\Psi(A) \qquad \text{(4-6)}$$ - - - -*Ψ* is known as the section factor (Chow, 1959) and is a function of the -flow area and conduit geometry. For some closed conduit shapes, such as -circular pipes, the section factor achieves a maximum value at a less -than full flow area (as shown in Figure 4-1) resulting in a maximum flow -that is larger than when the conduit flows full. - -![[]{#_Toc484694721 .anchor}**Figure 4‑1 Section factor versus area for -a circular -shape**](VolumeII/media/media/image19.emf){width="4.847871828521435in" -height="3.6209416010498687in"} - -Thus the governing equations for kinematic wave modeling along a single -conduit are the continuity equation 4-1 along with the "rating curve" -equation 4-6 that relates flow rate to area. The dependent variables in -these equations are flow rate *Q* and flow area *A*, which are functions -of distance *x* and time *t*. To solve these equations over a single -conduit of length *L*, one needs a set of initial conditions for either -*Q* or *A* at time 0 as well as boundary condition for either variable -at *x* = 0 for all times *t*. - -## 4.2 Solution Method - -The material that follows applies to networks containing only conduits -connected by junction nodes, where there is at most one outflow conduit -from each junction. Inclusion of flow control devices (pumps, orifices, -and weirs) and other processes (seepage and evaporation) will be covered -in subsequent chapters of this manual. Allowances for both flow divider -nodes and storage nodes are discussed later in this chapter in Section -4.3. - -The continuity equation 4-1 is solved along a space-time grid depicted -in Figure 4-2. A weighted Wendroff implicit finite difference scheme -(Smith, 1978) is used to re-express the equation as: - - -$$\frac{(1 - \theta)\left( A_{1}^{t + \Delta t} - A_{1}^{t} \right) + \theta\left( A_{2}^{t + \Delta t} - A_{2}^{t} \right)}{\Delta t} + \frac{(1 - \phi)\left( Q_{2}^{t} - Q_{1}^{t} \right) + \phi\left( Q_{2}^{t + \Delta t} - Q_{1}^{t + \Delta t} \right)}{L} = 0 \qquad \text{(4-7)}$$ - - - ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - -
-Grid.png -

Figure 4‑2 Space-time grid for kinematic -wave analysis

-
- -The subscripts 1 and 2 on *A* and *Q* refer to the upstream and -downstream ends of the conduit, respectively. The superscript refers to -the time period. *θ* and *φ* are weights chosen to be between 0.5 and 1. -At each time step this equation is applied conduit by conduit starting -at the most upstream node and working downstream. The only unknowns will -be $A_{2}^{t + \Delta t}$ and $Q_{2}^{t + \Delta t}$. As there is only -one outflow conduit connected to a junction node, $Q_{1}^{t + \Delta t}$ -is known from the sum of the already computed $Q_{2}^{t + \Delta t}$ -values of the upstream conduits that flow into the conduit being -analyzed, and also includes any externally imposed inflows such as wet -weather runoff or dry weather sanitary flow. The area -$A_{1}^{t + \Delta t}$ associated with this flow can be found by -evaluating the inverse of the section factor at the value of -$\frac{Q_{1}^{t + \Delta t}}{\beta}$. - -The Manning equation 4-6 can be substituted into Equation 4-7 which -after some rearrangement results in the following nonlinear equation -with single unknown $A_{2}^{t + \Delta t}$: - - -$$f\left( A_{2}^{t + \Delta t} \right) = \beta\Psi\left( A_{2}^{t + \Delta t} \right) + C1A_{2}^{t + \Delta t} + C2 = 0 \qquad \text{(4-8)}$$ - - - -where the constants C1 and C2 are given by: - - -$$C1 = \frac{L\theta}{\Delta t\phi} \qquad \text{(4-9)}$$ - -| | | | -| --- | --- | --- | -| | $C2 = \frac{L}{\Delta t\phi}\left\lbrack (1 - \theta)\left( A_{1}^{t + \Delta t} - A_{1}^{t} \right) - \theta A_{2}^{t} \right\rbrack + \frac{1 - \phi}{\phi}\left( Q_{2}^{t} - Q_{1}^{t} \right) - Q_{1}^{t + \Delta t}$ | (4-10) | - - -After solving 4-8 for $A_{2}^{t + \Delta t}$ equation 4-6 can then be -used to find the corresponding flow $Q_{2}^{t + \Delta t}$. - -Equation 4-8 is solved using a combination of bisection and -Newton-Raphson methods (Press et al., 1992) with both *θ* and *φ* set to -0.6. As a first step, a bracket -$\left\lbrack A_{LOW},\ A_{HIGH} \right\rbrack$ is sought where -$f(A_{LOW})$ and $f(A_{HIGH})$ are of opposite sign. For conduit shapes -whose section factor has a maximum value at an area *Amax* below -*Afull* (such as the circular conduit of Figure 4-1), these two areas -are tried first. If these areas do not form a valid bracket then *0* to -*Amax* is used. For shapes whose section factor always increases with -increasing area, *0* to *Afull* is used. - -If a valid bracket is found then the procedure described in Appendix A, -"*Newton-Raphson-Bisection Root Finding Method*", is used to find -$A_{2}^{t + \Delta t}$. Its initial estimate is $A_{2}^{t}$ and a -convergence tolerance *ε* of 0.1 percent of *Afull* is used. The -derivative of *f(A)* required by the method is -$f'(A) = \beta\Psi'(A) + C1$ where $\Psi'(A)$ is the derivative of the -section factor with respect to area *A*. If -$\left\lbrack A_{LOW},\ A_{HIGH} \right\rbrack$ does not form a valid -bracket then $A_{2}^{t + \Delta t}$ is set to 0 if both $f(A_{LOW})$ and -$f(A_{HIGH})$ are positive and set to $A_{full}$ if both are negative. - -## 4.3 Computational Details - -### 4.3.1 Order of Network Traversal - -The kinematic wave procedure finds new flows, flow areas, and flow -depths at the downstream end of each conduit at the end of each time -period of the analysis. At time *t* each conduit is examined in its -topologically sorted order when updating it to time *t + ∆t*. This -allows the inflows to a conduit at *t + ∆t* -$\left( Q_{1}^{t + \mathrm{\Delta}t} \right)$ to be determined from the -previously computed downstream outflows -$\left( Q_{2}^{t + \mathrm{\Delta}t} \right)$ of the conduits that flow -into it. - -The topological sort is performed just once, prior to time 0, using -Kahn's algorithm (Cormen et al, 2009) after all links have been oriented -in the direction of positive slope (meaning that the inflow end is at -higher elevation than the outflow end). Nodes with more than a single -outflow link (such as divider and storage nodes) will have those links -appearing consecutively in the sorted list. If the sorting algorithm -detects that a loop exists, then the program is terminated with an error -condition reported. - -### 4.3.2 Cross Section Properties - -The kinematic wave solution requires calculating a cross section's -section factor $\left( AR^{2/3} \right)$, the section factor's -derivative, and the depth of flow, all as a function of a conduit's flow -area. Flow depth is used only for reporting purposes. Chapter 5 provides -details on how these quantities are calculated for different conduit -shapes. - -Also required is the inverse section factor - the area associated with a -particular section factor. It is used to find the upstream area for a -given upstream flow rate (that is, *A* for $\Psi = \frac{Q}{\beta}$). -Its calculation is also described in Chapter 5, in Section 5.1.8. - -### 4.3.3 Flow Divider Nodes - -A flow divider node splits its inflow between two outlet conduits in a -prescribed manner. It is only active for kinematic wave analysis and is -treated as a regular junction node under dynamic wave analysis. - -There are four types of flow dividers available, defined by the manner -in which inflows are diverted: - - *Cutoff diverts all inflow above a user-supplied cutoff value - Divider:* *qMIN*. - -| | | -| --- | --- | -| *Overflow | diverts all inflow above the flow capacity | -| Divider:* | $Q_{full} = \beta\Psi(A_{full})$ of the non-diversion conduit | -| *Tabular | uses a pre-defined table that expresses diverted flow | -| Divider:* | as a function of total inflow. | -| *Weir Divider:* | diverts inflow above a minimum *qMIN* as flow over a weir of full height *hW* with discharge coefficient *cW*. | - - -The diverted flow for a weir divider node with total inflow of *Qin* -is computed as: - -+---+------------------------------------+-------------------------------------------+--------+ -| | $$Q_{div} = \left\{ \begin{matrix} | $$for\ Q_{in} \leq q_{MIN}$$ | (4-11) | -| | 0 \\ | | | -| | q_{MAX}f^{1.5} \\ | $$for\ q_{MIN} < Q_{in} \leq q_{MAX}$$ | | -| | Q_{MAX}\sqrt{f} | | | -| | \end{matrix} \right.\ \ \ $$ | $$for\ Q_{in} > q_{MAX}$$ | | -+===+====================================+===========================================+========+ - -where $q_{MAX} = c_{W}h_{W}^{1.5}$ and -$f = \frac{\left( Q_{in} - q_{MIN} \right)}{\left( q_{MAX} - q_{MIN} \right)}$. - -When the next conduit in sorted order is selected for routing analysis, -its upstream node is checked to see if it is a divider node. If it is, -then depending on its type, the diverted flow *Qdiv* is calculated -from the node's total inflow *Qin*. If the conduit is the node's -diversion link, then its inflow $Q_{1}^{t + \mathrm{\Delta}t}$ is set -equal to *Qdiv*. Otherwise its inflow is set to $Q_{in} - Q_{div}$. - -### 4.3.4 Storage Nodes - -Kinematic wave analysis allows a storage node to have more than one -outlet link of any type connected to it. The flow rate released from the -storage node into the upstream end of an outflow link will be a function -of the water level in the node. Thus whenever a storage node is -encountered as the topologically sorted list of conduits is traversed -its new water level must be determined before the routing process can -continue. Storage units that are terminal nodes (nodes with no outflow -links) are updated after all conduits have been analyzed. - -Storage node updating is carried out using the following mass balance -equation: - - -$$\frac{dV_{N}}{dt} = Q_{in} - Q_{out} \qquad \text{(4-12)}$$ - - - -*VN* is the volume of stored water in the node, *Qin* is the total -rate of inflow to the node and *Qout* is the total rate of outflow -from the node. Replacing $\frac{dV_{N}}{dt}$ with its finite difference -equivalent and using the average flow rates over the time step being -updated produces the following expression for -$V_{N}^{t + \mathrm{\Delta}t}$: - - -$$V_{N}^{t + \mathrm{\Delta}t} = V_{N}^{t} + 0.5\left( Q_{in}^{t} + Q_{in}^{t + \mathrm{\Delta}t} \right)\mathrm{\Delta}t - 0.5\left( Q_{out}^{t} + Q_{out}^{t + \mathrm{\Delta}t} \right)\mathrm{\Delta}t \qquad \text{(4-13)}$$ - - - -Once $V_{N}^{t + \mathrm{\Delta}t}$ is known the corresponding water -surface elevation *H* can be found from the storage node's invert -elevation and its user-supplied relation between surface area and water -depth. A more detailed discussion of how this is done is provided in -Chapter 5. - -Equation 4-13 can be re-written with all of the known values grouped -together in a constant *CN* as follows: - - -$$V_{N}^{t + \mathrm{\Delta}t} = C_{N} - 0.5Q_{out}^{t + \mathrm{\Delta}t} \qquad \text{(4-14)}$$ - - - -where *CN* is - - -$$C_{N} = V_{N}^{t} + 0.5\left( Q_{in}^{t} - Q_{out}^{t} + Q_{in}^{t + \mathrm{\Delta}t} \right)\mathrm{\Delta}t \qquad \text{(4-15)}$$ - - - -and contains the known volumes and flows from time *t* as well as the -known inflow to the storage node at time *t + ∆t*. - -$Q_{out}^{t + \mathrm{\Delta}t}$ will be a function of the storage -unit's water surface elevation *H*. For a conduit outflow link, the flow -at its upstream end that contributes to *Qout* will be determined by -its upstream flow area via Equation 4-6: $Q_{1} = \beta\Psi(A_{1})$. The -upstream flow area *A1* is determined by the conduit's upstream water -depth where it meets the storage node. This depth, *Y1*, is given by: - -+----+----------------------------------+----------------------------------------------+--------+ -| | $$Y_{1} = \left\{ \begin{matrix} | $$for\ H \leq Z_{1}$$ | (4-16) | -| | 0 \\ | | | -| | H - Z_{1} \\ | $$for\ Z_{1} < H \leq Z_{1} + Y_{full}$$ | | -| | Y_{full} | | | -| | \end{matrix} \right.\ $$ | $$for\ H > {Z_{1} + Y}_{full}$$ | | -+====+==================================+==============================================+========+ - -where *Z1* is the elevation of the conduit's upstream invert and -*Yfull* is the conduit's full depth. A similar situation exists for -other types of outflow links, such as pumps, orifices, and weirs as will -be discussed later in Chapter 6. As an example, the flow through an -orifice varies as the square root of the head across it: -$Q_{1} = c\sqrt{H - Z_{1}}$ where *c* is a constant. - -As both $Q_{out}^{t + \mathrm{\Delta}t}$ and -$V_{N}^{t + \mathrm{\Delta}t}$ depend on *H,* equation 4-14 must be -solved in implicit fashion using successive approximations. The details -are given in the side bar entitled "*Updating a Storage Node*". - -The hydraulic head at storage nodes is updated one more time after all -link flows at the end of a time step of size *∆t* have been found. First -a new volume for the node is found from: - - -$$V_{N}^{t + \mathrm{\Delta}t} = V_{N}^{t} + {\overline{Q}}_{net}\mathrm{\Delta}t \qquad \text{(4-17)}$$ - - - -${\overline{Q}}_{net}$ is the average net inflow to the node between -times *t* and *t + ∆t* : - - -$${\overline{Q}}_{net} = \ 0.5\left( Q_{in}^{t} + Q_{in}^{t + \mathrm{\Delta}t} \right) - 0.5\left( Q_{out}^{t} + Q_{out}^{t + \mathrm{\Delta}t} \right) \qquad \text{(4-18)}$$ - - - -with *Qin* being the total inflow entering the node from all upstream -links plus any external sources (such as runoff flow) and *Qout* being -the total flow rate in the links leaving the node. Then the new head at -the node, $H^{t + \mathrm{\Delta}t}$, can be found from the node's curve -of surface area versus depth as described in Chapter 5. - -### 4.3.5 Nodal Heads - -Kinematic wave analysis does not depend on or even define the hydraulic -head that exists at nodes that are not storage units. To make its -reported output compatible with that provided by dynamic wave analysis -the head at a non-storage node is arbitrarily set equal to the highest -water elevation in the links that are connected to it. For inflowing -conduits the water surface elevation at the downstream end of the -conduit, as derived from the downstream area, is considered. For out -flowing conduits it would be the water surface elevation at the upstream -end. It should be noted that kinematic wave analysis ignores the -presence of any offset that an outflow conduit at a non-storage node has -at its upstream end. Under dynamic wave analysis there would be no flow -into such a conduit until the water level at the node reached the offset -elevation. The kinematic wave model also ignores any surcharge depth -that may have been assigned to a node since neither conduits nor nodes -are allowed to pressurize. - -### 4.3.6 Flooding and Ponding - -Normally any excess inflow to a node under kinematic wave analysis over -what the outflow links can handle will be lost from the system. For -non-storage, non-terminal nodes the flooded overflow rate at time *t + -∆t* would be: - - -$$Q_{ovfl}^{t + \mathrm{\Delta}t} = \ max(0,\ {\overline{Q}}_{net}) \qquad \text{(4-19)}$$ - - - -where ${\overline{Q}}_{net}$ is given by Equation 4-18. For storage -nodes it would be: - - -$$Q_{ovfl}^{t + \mathrm{\Delta}t} = \ max\left( 0,\ \ \ {\overline{Q}}_{net} - \frac{\left( V_{Nfull} - V_{N}^{t} \right)}{\mathrm{\Delta}t} \right) \qquad \text{(4-20)}$$ - - - -where $V_{Nfull}$ is the volume of the storage node when full. When -*Qovfl* is non-zero, the head at the node is set equal to its -elevation at full depth for reporting purposes. - -As with dynamic wave analysis, the option exists for a junction or -divider node to have the excess inflow volume over a time step be stored -at the node and then released as external inflow during the next time -step. The node's "ponded area" parameter is used to indicate that -ponding is allowed if it is assigned a non-zero value (and does not -enter into any computations). In this case, the node's ponded volume -*VP* is kept track of as the simulation unfolds. Its initial value is -0. At time *t + ∆t* it is updated as follows: - - -$$V_{P}^{t + \mathrm{\Delta}t} = \ max\left( 0,\ \ \ V_{P}^{t} + {\overline{Q}}_{net}\mathrm{\Delta}t \right) \qquad \text{(4-21)}$$ - - - -The overflow reported for the time period is given by: - - -$$Q_{ovfl}^{t + \mathrm{\Delta}t} = \ max\left( 0,\ \ \ \frac{\left( V_{P}^{t + \mathrm{\Delta}t} - V_{P}^{t} \right)}{\mathrm{\Delta}t} \right) \qquad \text{(4-22)}$$ - - - -The flow added to the node's total inflow at the start of the next time -period is $\frac{V_{P}^{t + \mathrm{\Delta}t}}{\mathrm{\Delta}t}$. And -for reporting purposes, anytime *VP* is greater than 0 the node's head -is set equal to the elevation at full depth. - -## 4.4 Numerical Stability - -The authors of the original version of SWMM's kinematic wave routine -applied the techniques of O'Brien et al. (1951) to show that the method -was unconditionally stable for any choice of *θ* and *φ* both greater -than 0.5 ( Metcalf and Eddy et al., 1971a). Smith (1978, p. 188) showed -that the Wendroff implicit scheme using centered differences (*θ* = *φ = -0.5*) was also unconditionally stable. Because the scheme is stable it -does not employ the variable time step option as does dynamic wave -analysis. And although it is stable, it is still subject to numerical -dispersion when the Courant number differs from 1 and to numerical -diffusion (hydrograph attenuation) due to the discrete grid size (Ponce, -1991). - -To illustrate the stability properties of SWMM's kinematic wave method -the example of Chapter 3 solved earlier under dynamic wave analysis will -now be solved again using the kinematic wave model. The example consists -of a 2,000 ft long, 2 ft x 2 ft rectangular conduit whose slope is 0.05 -percent and Manning's roughness is 0.015. When divided into 10 equal -sub-conduits of 200 ft each the dynamic wave solution required a 25 -second time step to produce a stable outflow hydrograph (refer to Figure -3-6). At a 120 second time step the solution was highly unstable (see -Figure 3-7). - -As shown in Figure 4-3, kinematic wave (KW) is able to produce a stable -outflow hydrograph for the 120 second time step. A stable dynamic wave -(DW) solution required a much smaller time step of 25 seconds. The KW -solution exhibits the properties associated with this approximate method -of flow routing, with a very modest attenuation of the inflow hydrograph -peak and some distortion of the outflow hydrograph. The DW solution -should be considered the more accurate one, with its greater reduction -in peak flow due to the storage effect provided by the additional -inertia and pressure terms included in the dynamic wave formulation. - -
-Example1d.png -

Figure 4‑3 Outflow hydrograph for example -conduit

-
- -# - Cross-Section Geometry - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -The hydraulic modeling procedures described in chapters 3 and 4 require -calculation of several cross-section geometric properties for partially -full conduits. These include the following functions: - - *A(Y)* flow area *A* as a function of flow depth *Y* - -| | | -| --- | --- | -| *W(Y)* | top width *W* as a function of flow depth *Y* | -| *R(Y)* | hydraulic radius *R* as a function of flow depth *Y* | -| *Y(A)* | flow depth *Y* as a function of flow area *A* | -| *Ψ(A)* | section factor *Ψ* as a function of flow area *A* | -| *Ψ'(A)* | derivative of section factor *Ψ* with respect to area *A* | -| *A(Ψ)* | flow area *A* as a function of section factor *Ψ* | - - -as well as the following constants used in evaluating these functions: - - *Afull* area at full depth - -| | | -| --- | --- | -| *Wmax* maximum width | -| *Rfull< | /sub>* hydraulic radius at full depth | -| *Ψfull< | /sub>* section factor at full depth | -| *Ψmax* maximum section factor | -| *Amax* area corresponding to *Ψmax*. | - - -This chapter describes how these properties are computed for the wide -range of conduit shapes, both standard and irregular, included in SWMM. -In addition, the procedures used to compute both the normal and critical -flow depths used in dynamic wave analysis are discussed. - -## 5.1 Standard Conduit Shapes - -SWMM recognizes a number of standard pre-defined conduit shapes. These -include five open channel shapes (rectangular, trapezoidal, triangular, -parabolic and power law), four commonly used closed pipe shapes -(circular, rectangular, ellipsoid and arch), seven closed shapes found -mainly in older masonry sewers, and four closed composite shapes that -are combinations of rectangular, triangular and circular sections. - -### 5.1.1 Open Channel Shapes - -SWMM can analyze the following standard open channel shapes: - -- Rectangular with bottom width *b* - -- Trapezoidal with bottom width *b* and side slope (run over rise) *s* - -- Triangular with side slope *s* - -- Parabolic with top width *b* at full depth *Yfull*. - -Table 5-1 lists the formulas used to compute the geometric properties of -these shapes that are functions of water depth *Y*: A(Y), *W(Y),* and -*R(Y).* Table 5-2 lists the formulas used to compute the properties that -are functions of flow area *A*: *Y(A), R(A),* and the derivative of the -wetted perimeter *P'(A)*). The latter quantity is used for computing the -derivative of the section factor as described below. - -+------------------------------------------------+---------------------------+----------------+--------------------------------------------------+ -| **Shape** | ***A(Y)*** | ***W(Y)*** | ***R(Y)*** | -+:===============================================+:=========================:+:==============:+:================================================:+ -| Rectangular | $$bY$$ | $$b$$ | $$\frac{bY}{b + 2Y}$$ | -+------------------------------------------------+---------------------------+----------------+--------------------------------------------------+ -| Trapezoidal | $$(b + sY)Y$$ | $$b + 2sY$$ | $$\frac{(b + zY)Y}{b + 2Y\sqrt{1 + s^{2}}}$$ | -+------------------------------------------------+---------------------------+----------------+--------------------------------------------------+ -| Triangular | $$sY^{2}$$ | $$2sY$$ | $$\frac{sY}{2\sqrt{1 + s^{2}}}$$ | -+------------------------------------------------+---------------------------+----------------+--------------------------------------------------+ -| Parabolic | $$\frac{4}{3}Y\sqrt{cY}$$ | $$2\sqrt{cY}$$ | $$\frac{2A(Y)}{c\left( xt + ln(x + t) \right)}$$ | -| | | | | -| $$c = \frac{b^{2}}{\left( 4Y_{full} \right)}$$ | | | $$x = 2\sqrt{\frac{Y}{c}}$$ | -| | | | | -| | | | $$t = \sqrt{1 + x^{2}}$$ | -+------------------------------------------------+---------------------------+----------------+--------------------------------------------------+ - -: []{#_Toc484690419 .anchor}**Table 5‑1 Geometric properties for open -channel shapes as functions of water depth** - -+------------------------------------------------+-----------------------------------------------+----------------------------------------+-------------------------------------------+ -| **Shape** | ***Y(A)*** | ***R(A)*** | ***P'(A)*** | -+:===============================================+:=============================================:+:======================================:+:=========================================:+ -| Rectangular | $$\frac{A}{b}$$ | $$\frac{A}{b + 2\frac{A}{b}}$$ | $$\frac{2}{b}$$ | -+------------------------------------------------+-----------------------------------------------+----------------------------------------+-------------------------------------------+ -| Trapezoidal | $$\frac{\sqrt{b^{2} + 4sA}}{2s}$$ | $$\frac{A\sqrt{1 + s^{2}}}{b + Y(A)}$$ | $$\frac{2\sqrt{1 + s^{2}}}{b^{2} + 4sA}$$ | -+------------------------------------------------+-----------------------------------------------+----------------------------------------+-------------------------------------------+ -| Triangular | $$\sqrt{\frac{A}{s}}$$ | $$\frac{A}{2Y(A)\sqrt{1 + s^{2}}}$$ | $$\frac{\sqrt{1 + s^{2}}}{sA}$$ | -+------------------------------------------------+-----------------------------------------------+----------------------------------------+-------------------------------------------+ -| Parabolic | $$\left( \frac{3A}{4\sqrt{c}} \right)^{2/3}$$ | $$2c\left( xt + ln(x + t) \right)$$ | not used | -| | | | | -| $$c = \frac{b^{2}}{\left( 4Y_{full} \right)}$$ | | $$x = 2\sqrt{\frac{Y(A)}{c}}$$ | | -| | | | | -| | | $$t = \sqrt{1 + x^{2}}$$ | | -+------------------------------------------------+-----------------------------------------------+----------------------------------------+-------------------------------------------+ - -: []{#_Toc484690420 .anchor}**Table 5‑2 Geometric properties for open -channel shapes as functions of flow area** - -The section factor *Ψ* for each of these shapes is given by: - - -$$\Psi(A) = A{R(A)}^{2/3} \qquad \text{(5-1)}$$ - - - -With the exception of the parabolic shape, its derivative with respect -to area *A* is: - - -$$\Psi'(A) = (\frac{5}{3} - \frac{2}{3}P'R)R^{2/3} \qquad \text{(5-2)}$$ - - - -where *P'* and *R* are evaluated at the desired value of *A*. For -parabolic channels the section factor derivative is computed using the -difference formula: - - -$$\Psi'(A) = \frac{\Psi(A + \Delta A) - \Psi(A - \Delta A)}{2\Delta A} \qquad \text{(5-3)}$$ - - - -where *∆A* is 0.1% of the full cross section area. - -In addition to the four open sections just described SWMM can also -analyze a cross section whose side wall shape is described by the power -law function: - - -$$y = \alpha x^{\frac{1}{\gamma}} \qquad \text{(5-4)}$$ - - - -where *x* is horizontal distance from the centerline, *y* is vertical -distance, 1/γ is an exponent and α is a constant. To use this shape the -user supplies values for 1/γ, the full depth *Yfull* and the top width -when full *b* (see Figure 5-1). Note that the parabolic shape is a -special case of this power function shape where 1/γ equals 2. - -
-PowerFunc.png -

Figure 5‑1 Power law cross section -shape

-
- -With this shape it is more convenient to work with water surface width -*W* as a function of water depth *Y*, which can be done by re-expressing -Equation 5-4 as: - - -$$W = cY^{\gamma} \qquad \text{(5-5)}$$ - - - -where *c* is another constant. Since *W* = *b* at *Y* = *Yfull*, the -constant *c* equals $\frac{b}{Y_{full}^{\gamma}}$ . The full area -*Afull* is $\frac{bY_{full}}{(\gamma + 1)}$. Table 5-3 lists the -expressions used to compute the geometric properties for partially full -power law shapes. The wetted perimeter *P* table entry is evaluated by -approximating each of the curved sides of the shape by a series of 50 -line segments whose lengths up to height *Y* are added together. - -### 5.1.2 Closed Rectangular Shape - -A closed (or covered) rectangular conduit has the same *A(Y)*, *W(Y)*, -and *Y(A)* functions as its open counterpart. Its *R(Y)* and *Ψ(A)* -functions are also the same up to the point where the conduit becomes -full and the wetted perimeter then includes the top width. This -introduces a discontinuity in the relationship between *R* and *Y* as -well as between *Ψ* and *A*. To avoid this, a maximum section factor is -deemed to occur at 97% full after which it decreases linearly to the -section factor when completely full. These two section factors are given -by: - -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Property** | **Expression** | -+:=============+===============================================================================================================================================================================================================+ -| *c* | $$\frac{b}{Y_{full}^{\gamma}}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *A(Y)* | $$c\frac{Y^{\gamma + 1}}{(\gamma + 1)}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *W(Y)* | $$cY^{\gamma}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *P(Y)* | $$2\sum_{i = 1}^{N}\sqrt{{\Delta x}_{i}^{2} + \Delta y^{2}}\ \ where\ \ \Delta y = 0.02Y_{full},\ \ N = \frac{Y}{\Delta y},$$ | -| | | -| | $$\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ and\ {\Delta x}_{i} = \left( \frac{c}{2} \right)\left\{ (i\Delta y)^{\gamma} - \left( (i - 1)\Delta y \right)^{\gamma} \right\}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *R(Y)* | $$\frac{A(Y)}{P(Y)}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *Y(A)* | $$\left\lbrack \frac{(\gamma + 1)A}{c} \right\rbrack^{\frac{1}{(\gamma + 1)}}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *R(A)* | $$\frac{A}{P(Y(A))}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *Ψ(A)* | $$A{R(A)}^{\frac{2}{3}}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| *Ψ'(A)* | $$\frac{\Psi(A + \Delta A) - \Psi(A - \Delta A)}{2\Delta A}\ \ where\ \Delta A = 0.001A_{full}$$ | -+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -: []{#_Toc484690421 .anchor}**Table 5‑3 Geometric properties for the -power law shape** - - -$$\Psi_{full} = A_{full}\left( \frac{A_{full}}{P_{full}} \right)^{2/3} \qquad \text{(5-6)}$$ - -| | | | -| --- | --- | --- | -| | $\Psi_{\max} = {0.97A}_{full}\left( \frac{{0.97A}_{full}}{P_{\max}} \right)^{2/3}$ | (5-7) | - - -where $A_{full} = bY_{full}$, $P_{full} = 2\left( b + Y_{full} \right)$, -and $P_{\max} = b + 2\left( 0.97Y_{full} \right)$. - -When either *Y* or *A* do not exceed 97% of their full values, the -closed rectangular hydraulic radius and section factor are computed in -the same fashion as for the open rectangular shape described in section -5.2.1. Above this point the hydraulic radius at a given depth *Y* is: - - -$$R(Y) = \frac{A(Y)}{P(Y)} \qquad \text{(5-8)}$$ - - - -where - - -$$P(Y) = 2Y + b + b\frac{\left( \frac{Y}{Y_{full} - 0.97} \right)}{0.03} \qquad \text{(5-9)}$$ - - - -and the section factor and its derivative at a given flow area *A* are: - - -$$\Psi(A) = \Psi_{\max} - \frac{\left( \Psi_{\max} - \Psi_{full} \right)\left( \frac{A}{A_{full} - 0.97} \right)}{0.03} \qquad \text{(5-10)}$$ - -| | | | -| --- | --- | --- | -| | $\Psi'(A) = \frac{\left( \Psi_{full} - \Psi_{\max} \right)}{\left( 0.03A_{full} \right)}$ | (5-11) | - - -### 5.1.3 Circular Shape - -Although analytical formulas are available for the properties of partly -full circular cross sections (see French, 1985), they contain -trigonometric functions that are time consuming to compute. Thus for -reasons of efficiency SWMM uses a set of lookup tables that are based on -those published by Chow (1959). The tables consist of the following: - - *A~tbl\ :~* *A/A~full\ ~* as a function of *Y/Yfull* - -| | | -| --- | --- | -| *W~tbl\ :~* | *W/Wmax* as a function of *Y/Yfull* | -| *R~tbl\ :~* | *R/Rfull* as a function of *Y/Yfull* | -| *Y~tbl\ :~* | *Y/Yfull* as a function of *A/Afull* | -| *Ψ~tbl\ :~* | *Ψ/Ψfull* as a function of *A/Afull* | - - -Each table consists of 51 equally spaced values of *Y/Yfull* or -*A/Afull* between 0 and 1. They are graphed in Figures 5-2 and 5-3 and -are listed in Appendix C. The normalizing factors used in the tables are -for full flow conditions $\left( Y = Y_{full} \right)$ whose formulas -are listed in Table 5-4. - - **Property** **Value** - -| | | -| --- | --- | -| Depth | $Y_{full}$ | -| Area | $A_{full} = 0.7854Y_{full}^{2}$, | -| Maximum Width | $W_{\max} = Y_{full}$ | -| Hydraulic Radius | $R_{full} = 0.25Y_{full}$ | -| Section Factor | $\Psi_{full} = A_{full}R_{full}^{2/3}$ | - - - : []{#_Toc484690422 .anchor}**Table 5‑4 Geometric properties of a full - circular cross section** - -
-Circular1.png -

Figure 5‑2 Geometric properties of a -partly filled circular shape based on depth

-
- -
-Circular2.png -

Figure 5‑3 Geometric properties of a -partly filled circular shape based on area

-
- -To find *A*, *W*, or *R* for a given *Y* one first evaluates -$i = \left( \frac{Y}{Y_{full}} \right)(N - 1)$ rounded down to the -nearest integer value where *N* = 51, linearly interpolates the -appropriate table between the entries at index *i* and *i+1*, and then -multiplies by the appropriate normalizing factor (either *Afull*, -*Yfull*, or *Rfull*). A similar procedure is used to evaluate *Y* or -*Ψ* as a function of *A* normalized by *Afull*. The section factor -derivative is determined directly from the *Ψ~tbl\ ~* as follows: - - -$$\Psi'(A) = \left( \Psi_{tbl}\lbrack i + 1\rbrack - \Psi_{tbl}\lbrack i\rbrack \right)(N - 1)\left( \frac{\Psi_{full}}{A_{full}} \right) \qquad \text{(5-12)}$$ - - - -where *i* is the integer value of -$\left( \frac{A}{A_{full}} \right)(N - 1)$ for *N* = 51. For added -accuracy, analytical functions are used to compute *Y,* *Ψ,* and *Ψ'* -for areas below 4% of *Afull*. They are described in the side bar -entitled "*Analytical Functions for Circular Cross Sections*". - -### 5.1.4 Ellipsoid and Arch Shapes - -Figure 5-4 depicts standard ellipsoid and arch sewer pipe cross -sectional shapes. Next to circular pipes these are the most commonly -used shapes for newly installed sewers and culverts. Each shape is -defined by its "rise" which is its full depth *Yfull*, and its "span" -which is its maximum width *Wmax*. The vertical and horizontal -ellipsoids have the same shape but rotated by 90 degrees (the span of -one is the rise of the other and vice versa). - -
-EllipseArch.png -

Figure 5‑4 Ellipsoid and arch pipe cross -sectional shapes

-
- -SWMM contains a list of 23 standard ellipsoid pipe sizes and 102 -standard arch pipe sizes taken from the American Concrete Pipe -Association's and the American Iron and Steel Institute's design manuals -(American Concrete Pipe Association, 2011; American Iron and Steel -Institute, 1999). The standard ellipsoid and arch pipe sizes are -tabulated in Appendixes D and E, respectively. Each size is -characterized by its rise, span, full area, and full hydraulic radius. -Users can either select from one of these standard sizes or supply their -own values for rise *Yfull* and span *Wmax*, both in feet. In the -latter case the corresponding full area *Afull* and hydraulic radius -*Rfull* are estimated using the formulas in Table 5-5. - - **Property** **Ellipsoid Shape** **Arch Shape** - -| | | | -| --- | --- | --- | -| Full Area $A_{full}$ | $1.2692Y_{full}^{2}$ | $0.7879Y_{full}W_{\max}$ | -| Full Hydraulic Radius | $0.3061Y_{full}$ | $0.2991Y_{full}$ | -| $R_{full}$ | | | - - - : []{#_Toc484690423 .anchor}**Table 5‑5 Full area and hydraulic radius - of custom ellipsoid and arch pipe sections** - -Information in the aforementioned design manuals was used to construct -the following tables for both the ellipsoid and arch shapes (only a -single set of tables is needed for the two ellipsoid shapes since they -are just rotated versions of one another): - - *A~tbl\ :~* *A/A~full\ ~* as a function of *Y/Yfull* - -| | | -| --- | --- | -| *W~tbl\ :~* | *W/Wmax* as a function of *Y/Yfull* | -| *R~tbl\ :~* | *R/Rfull* as a function of *Y/Yfull* | - - -Each table contains entries for *N =* 26 equally spaced values of -*Y/Yfull* between 0 and 1. The tables for ellipsoid pipes are in -Appendix D and those for arch pipes are in Appendix E. To find *A*, *W*, -or *R* for a given *Y* one first determines the integer portion of -$(N - 1)\left( \frac{Y}{Y_{full}} \right)$, linearly interpolates the -appropriate table between the entries at this and the next higher index, -and then multiplies by the appropriate normalizing factor (either -*Afull*, *Wmax*, or *Rfull*). - -To find the depth associated with a given area *Y(A)*, a bisection (or -interval halving) procedure is first used on the appropriate (either -ellipsoid or arch) area table *Atbl* to find the position *i* so that -$A_{tbl}\lbrack i\rbrack \leq \frac{A}{A_{full} \leq A_{tbl}\lbrack i + 1\rbrack}$. -Then the desired depth *Y* is interpolated from this position in the -table using the following expression with *N* = 26: - - -$$Y(A) = \frac{Y_{full}}{(N - 1)}\left( i + \frac{\left( \frac{A}{A_{full} - A_{tbl}\lbrack i\rbrack} \right)}{\left( A_{tbl}\lbrack i + 1\rbrack - A_{tbl}\lbrack i\rbrack \right)} \right) \qquad \text{(5-14)}$$ - - - -The following steps are used to find the section factor associated with -a given area *Ψ(A):* - -1. Use the aforementioned procedure to find the depth *Y* corresponding - to area *A* from the appropriate *Atbl*. - -2. Use the shape's hydraulic radius table *Rtbl* to find the - hydraulic radius *R* for this depth. - -3. Compute the section factor as: $\Psi(A) = AR^{2/3}$. - -The section factor derivative for a given area *Ψ'(A)* is found using -the following central difference equation: - - -$$\Psi'(A) = \frac{\Psi(A + \Delta A) - \Psi(A - \Delta A)}{2\Delta A}\ \ where\ \mathrm{\Delta}A = 0.001A_{full} \qquad \text{(5-15)}$$ - - - -### 5.1.5 Older Masonry Sewer Shapes - -SWMM contains seven pre-defined closed conduit shapes shown in Figure -5-5 that were used primarily in older masonry sewers built over a -century ago. Their geometric properties have been derived from -information and drawings found in Metcalf and Eddy (1914) and Davis -(1952). These properties are represented using the same type of lookup -tables discussed previously for circular cross sections (see section -5.2.3). The number of entries *N* in each table for each shape is listed -in Table 5-6. The full tables are provided in Appendix F. The values of -*Afull, Rfull*, and *Wmax* used to normalize the entries in the -tables for each shape are listed in Table 5-7. The full section factor -*Ψfull* used to normalize the section factor table is computed as -$A_{full}R_{full}^{2/3}$ . - -![OldShapes.png](VolumeII/media/media/image27.png){width="4.834008092738408in" -height="2.510767716535433in"} - -[]{#_Toc484694728 .anchor}**Figure 5‑5 Masonry sewer shapes** - - -------------------------------------------------------------------------------------------- - **Shape** ***Atbl*** ***Rtbl*** ***Wtbl*** ***Ytbl*** ***Ψtbl*** - -| | | | | | | -| --- | --- | --- | --- | --- | --- | -| Basket Handle | 26 | 26 | 26 | 51 | 51 | -| Egg | 26 | 26 | 26 | 51 | 51 | -| Horseshoe | 26 | 26 | 26 | 51 | 51 | -| Catenary | \- | \- | 21 | 51 | 51 | -| Gothic | \- | \- | 21 | 51 | 51 | -| Semi-Circular | \- | \- | 21 | 51 | 51 | -| Semi-Elliptical | \- | \- | 21 | 51 | 51 | - - - : []{#_Toc484690424 .anchor}**Table 5‑6 Number of entries in geometric - property tables for masonry sewer shapes** - - **Shape** ***Afull*** ***Rfull*** ***Wmax*** ***Ψmax*** - -| | | | | | -| --- | --- | --- | --- | --- | -| Basket Handle | ${0.7862\ Y}_{full}^{2}$ | $0.2464\ Y_{full}$ | $0.944{\ Y}_{full}$ | $1.06078{\ \Psi}_{full}$ | -| Egg | $0.5105\ Y_{full}^{2}$ | $0.1931{\ Y}_{full}$ | $0.667\ Y_{full}$ | $1.065\ \Psi_{full}$ | -| Horseshoe | $0.8293\ Y_{full}^{2}$ | $0.2538{\ Y}_{full}$ | $Y_{full}$ | $1.077\ \Psi_{full}$ | -| Catenary | $0.70277\ Y_{full}^{2}$ | ${0.23172\ Y}_{full}$ | $0.9\ Y_{full}$ | $1.05\ \Psi_{full}$ | -| Gothic | $0.6554\ Y_{full}^{2}$ | $0.2269\ Y_{full}$ | $0.84\ Y_{full}$ | $1.065\ \Psi_{full}$ | -| Semi-Circular | $1.2697\ Y_{full}^{2}$ | $0.2946{\ Y}_{full}$ | $1.64{\ Y}_{full}$ | $1.06637\ \Psi_{full}$ | -| Semi-Elliptical | ${0.785\ Y}_{full}^{2}$ | $0.242\ Y_{full}$ | $Y_{full}$ | $1.045\ \Psi_{full}$ | - - - : []{#_Toc484690425 .anchor}**Table 5‑7 Geometric parameters of - masonry sewer sections** - -The tables are used in the same manner as the ones for a circular shape -to directly evaluate *A(Y), W(Y), R(Y), Y(A), Ψ(A),* and *Ψ'(A).* For -the shapes that do not have an *Atbl*, *A(Y)* is determined using the -inverse lookup method on the *Ytbl* described in section 5.2.4 for -ellipsoids and arches. For shapes without an *Rtbl*, *R(Y)* is found -by first finding *A(Y)* as just described, then finding *Ψ(A)* for the -resulting area *A*, and finally -evaluating$\left( \frac{\Psi}{A} \right)^{3/2}$. Equation 5-15 is used -to compute *Ψ'(A).* - -### 5.1.6 Composite Shapes - -Figure 5-6 shows four cross section shapes that are combinations of -circular, rectangular, and triangular sections. The formulas for -computing their geometrical properties are presented in the following -paragraphs. - -
-CompositeShapes.png -

Figure 5‑6 Composite cross section -shapes

-
- -[Sediment Filled Circular Shape]{.underline} - -This is a circular cross section that is partially filled with immobile -sediment to a specified depth *Ybtm*. (This filled depth remains -constant -- SWMM does not model how it might change over time due to -sediment transport processes.) The depth available for flow is -$Y_{full} - Y_{btm}$. To compute the geometric properties of this shape -one first uses the circular shape functions to compute the area -*Abtm*, top width *Wbtm*, and hydraulic radius R*btm* at a depth -of *Ybtm* for the full circular shape with diameter *Yfull*. The -wetted perimeter at this depth, *Pbtm*, is $\frac{A_{btm}}{R_{btm}}$ . -Then the expressions listed in Table 5-8 can be used to find the section -properties for a specific flow depth *Y* above *Ybtm* or area *A* -above *Abtm* . - - **Property** **Value Based on Full Circular Shape Functions** - -| | | -| --- | --- | -| *A(Y)* | $A\left( Y + Y_{btm} \right) - A_{btm}$ | -| *W(Y)* | $W(Y + Y_{btm})$ | -| *R(Y)* | $\frac{A\left( Y + Y_{btm} \right) - A_{btm}}{\left( \frac{A(Y + Y_{btm})}{R(Y + Y_{btm}}) \right) - P_{btm} + W_{btm}}$ | -| *Y(A)* | $Y\left( A + A_{btm} \right) - Y_{btm}$ | -| *Ψ(A)* | $A{R(\mathrm{\Delta}Y)}^{2/3}\ \ where\ \mathrm{\Delta}Y = Y\left( A + A_{btm} \right) - Y_{btm}$ | -| *Ψ'(A)* | $\frac{\Psi(A + \Delta A) - \Psi(A - \Delta A)}{2\Delta A}\ \ where\ \Delta A = 0.001(A_{full} - A_{btm})$ | - - - : []{#_Toc484690426 .anchor}**Table 5‑8 Geometric properties for a - sediment filled circular cross section** - -[Rectangular-Triangular Shape]{.underline} - -This shape consists of a triangular bottom section of height *Ybtm* -connected to a closed rectangular top section of width *b* and height -*Yfull* -- *Ybtm*. The slope of the triangular section's sidewalls -*s* is $\frac{b}{2Y_{btm}}$ . For depths below *Ybtm* (or areas below -$Y_{btm}\frac{b}{2}$) the geometric properties are computed in the same -manner as for the open triangular shape of section 5.2.1. At higher -depths (or areas) the methods used for the closed rectangular shape of -section 5.2.2 are applied with some adjustments made to accommodate the -filled triangular section. The applicable formulas are listed in Table -5-9. - -[Rectangular-Round Shape]{.underline} - -This composite shape consists of a closed rectangular top with a rounded -bottom section. It has full height *Yfull*, top width *b*, and bottom -radius of curvature *r* (see Figure 5-6). Table 5-10 lists the -parameters used to compute the section's properties whose formulas are -given in Table 5-11. - -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| **Property** | **Expression** | -+:================+==========================================================================================================================================+ -| *s* | $$\frac{b}{\left( 2Y_{btm} \right)}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$A_{btm}$$ | $$bY_{btm}/2$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$A_{full}$$ | $$b\left( Y_{full} - \frac{Y_{btm}}{2} \right)$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$R_{full}$$ | $$\frac{A_{full}}{\left( 2Y_{btm}\sqrt{1 + s^{2}} + 2\left( Y_{full} - Y_{btm} \right) + b \right)}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$\Psi_{full}$$ | $$A_{full}R_{full}^{2/3}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *A(Y)* | $$A_{btm} + \left( Y - Y_{btm} \right)b$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *Y(A)* | $$Y_{btm} + \frac{\left( A - A_{btm} \right)}{b}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *W(Y)* | $$b$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *P(Y)* | $$2Y_{btm}\sqrt{\left( 1 + s^{2} \right)} + 2\left( Y - Y_{btm} \right)$$ | -| | | -| | $$if\ \ A(Y) > 0.98A_{full}\ add\ on\ \left( \frac{A(Y)}{A_{full}} - 0.98 \right)\frac{b}{0.02}\ \ $$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *R(Y)* | $$\frac{A(Y)}{P(Y)}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| *R(A)* | $$\frac{A}{P(Y(A))}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$\Psi_{\max}$$ | $$0.98A_{full}{R(0.98A_{full})}^{2/3}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$\Psi(A)$$ | $$A{R(A)}^{2/3}\ \ for\ A \leq 0.98A_{full}$$ | -| | | -| | $$\Psi_{\max} + \left( \Psi_{full} - \Psi_{\max} \right)\frac{\left( \frac{A}{A_{full} - 0.98} \right)}{0.02\ \ for\ A > 0.98A_{full}}$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ -| $$\Psi'(A)$$ | $$\left( \frac{5}{3} - \left( \frac{2}{3} \right)\left( \frac{2}{b} \right)R(A) \right){R(A)}^{2/3}\ \ for\ A \leq 0.98A_{full}$$ | -| | | -| | $$\frac{\left( \Psi_{full} - \Psi_{\max} \right)}{0.02A_{full}\ for\ A > 0.98A_{full}\ }$$ | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------+ - -: []{#_Toc484690427 .anchor}**Table 5‑9 Properties of the rectangular -section of a rectangular-triangular shape** - -[Modified Basket Handle Shape]{.underline} - -The modified basket handle shape is the reverse of the rectangular-round -shape with a rectangular bottom section below a rounded top section. It -has full height *Yfull*, bottom width *b*, and top section radius of -curvature *r* (see Figure 5-6). The central angle *θ* formed by the -rounded top section is: - - -$$\theta = 2\sin^{- 1}\left( \frac{b}{2r} \right) \qquad \text{(5-14)}$$ - - - -The depth *Ybtm* of the bottom rectangular section is: - - -$$Y_{btm} = Y_{full} - r\left( 1 - cos\left( \frac{\theta}{2} \right) \right) \qquad \text{(5-15)}$$ - - - -and its area *Abtm* is *bYbtm* . The shape's full area *Afull* is: - - -$$A_{full} = A_{btm} + \frac{r^{2}}{\left\{ 2(\theta - sin\theta) \right\}} \qquad \text{(5-16)}$$ - - - -For depths up to *Ybtm* and areas up to *Abtm* the open rectangular -shape functions of Tables 5-1 and 5-2, respectively, are used to compute -the modified basket handle's section properties. For depths and areas -above this the functions listed in Table 5-12 are used. - - **Parameter** **Value** - -| | | -| --- | --- | -| Central Angle *θ* | $2\sin^{- 1}\left( \frac{b}{2r} \right)$ | -| Bottom Section Height | $r\left( 1 - cos\left( \frac{\theta}{2} \right) \right)$ | -| *Ybtm* | | -| Bottom Section Area *Abt | m* $\left( \frac{r^{2}}{2} \right)\left( \theta - sin(\theta) \right)$ | -| Full Area *Afull* | $b\left( Y_{full} - Y_{btm} \right) + A_{btm}$ | -| Full Hydraulic Radius | $\frac{A_{full}}{\left\{ r\theta + 2\left( Y_{full} - Y_{btm} \right) + b \right\}}$ | -| *Rfull* | | -| Full Section Factor | $A_{full}R_{full}^{2/3}$ | -| *Ψfull* | | -| Maximum Hydraulic Radius | $\frac{0.98A_{full}}{\left\{ r\theta + \frac{2\left( 0.98A_{full} - A_{btm} \right)}{b} \right\}}$ | -| *Rmax* | | -| Maximum Section Factor | $0.98A_{full}R_{\max}^{2/3}$ | -| *Ψmax* | | - - - : []{#_Toc484690428 .anchor}**Table 5‑10 Geometric parameters for - rectangular-round shapes** - -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| **Property** | **Formula** | **Applicable Region** | -+:=============+=================================================================================================================+:====================================+ -| *A(Y)* | $$0.5r^{2}\left( \phi - sin(\phi) \right)\ \ where\ \phi = 2\cos^{- 1}\left( 1 - \frac{Y}{r} \right)$$ | $$Y \leq Y_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$A_{btm} + \left( Y - Y_{btm} \right)b$$ | $$Y > Y_{btm}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *W(Y)* | $$2\sqrt{Y(2r - Y)}$$ | $$Y \leq Y_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | *b* | $$Y > Y_{btm}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *R(Y)* | $$0.5r\frac{\left( 1 - sin(\phi) \right)}{\phi\ \ where\ \ }\phi = 2\cos^{- 1}\left( 1 - \frac{Y}{r} \right)$$ | $$Y \leq Y_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$R\left( A(Y) \right)\ \ (see\ R(A)function\ below)$$ | $$Y > Y_{btm}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *Y(A)* | $$Y(A)for\ circular\ shape\ with\ Y_{full} = 2r$$ | $$A \leq A_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$Y_{btm} + \frac{\left( A - A_{btm} \right)}{b}$$ | $$A > A_{btm}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *P(A)* | $$2r\cos^{- 1}\left( 1 - \frac{Y(A)}{r} \right)$$ | $$A \leq A_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$2r\sin^{- 1}\left( \frac{b}{2r} \right) + 2\frac{\left( A - A_{btm} \right)}{b}$$ | $$A_{btm} < A \leq {0.98A}_{full}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$2r\sin^{- 1}\left( \frac{b}{2r} \right) + 2\frac{\left( A - A_{btm} \right)}{b}$$ | $$A > 0.98A_{full}$$ | -| | | | -| | $$+ \left( \frac{A}{A_{full} - 0.98} \right)\frac{b}{0.02}$$ | | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *R(A)* | $$\frac{A}{P(A)}$$ | | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *Ψ(A)* | $$\Psi(A)for\ circular\ shape\ with\ Y_{full} = 2r$$ | $$A \leq A_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$A{R(A)}^{2/3}$$ | $$A_{btm} < A \leq {0.98A}_{full}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$\Psi_{\max} + \left( \Psi_{full} - \Psi_{\max} \right)\frac{\left( \frac{A}{A_{full} - 0.98} \right)}{0.02}$$ | $$A > 0.98A_{full}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| *Ψ'(A)* | $$\frac{\left\{ \Psi(A + \Delta A) - \Psi(A - \Delta A) \right\}}{2\Delta A}$$ | $$A \leq A_{btm}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$\left( \frac{5}{3} - \left( \frac{2}{3} \right)\left( \frac{2}{b} \right)R(A) \right){R(A)}^{2/3}$$ | $$A_{btm} < A \leq {0.98A}_{full}$$ | -| +-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ -| | $$\frac{\left( \Psi_{full} - \Psi_{\max} \right)}{\left( 0.02A_{full} \right)}$$ | $$A > 0.98A_{full}$$ | -+--------------+-----------------------------------------------------------------------------------------------------------------+-------------------------------------+ - -: []{#_Toc484690429 .anchor}**Table 5‑11 Geometric properties for -rectangular--round shapes** - - **Property** **Expression** - -| | | -| --- | --- | -| *A(Y)* | $A_{full} - \left( \frac{r^{2}}{2} \right)(\phi - sin\phi)\ \ where\ \phi = 2\cos^{- 1}\left( 1 - \frac{\left( Y_{full} - Y \right)}{r} \right)$ | -| *W(Y)* | $2\sqrt{\left( Y_{full} - Y \right)\left( 2r - \left( Y_{full} - Y \right) \right)}$ | -| *R(Y)* | $R\left( A(Y) \right)\ using\ R(A)function\ below$ | -| *Y(A)* | $Y_{full} - Y\left( A_{full} - A \right)\ \ using\ Y(A)for\ circular\ shape\ with\ Y_{full} = 2r$ | -| *P(A)* | $(\theta - \phi)r + 2\left( Y_{full} - Y(A) \right) + b\ \ where\ \phi = 2\cos^{- 1}\left( 1 - \frac{\left( Y_{full} - Y(A) \right)}{r} \right)$ | -| *R(A)* | $\frac{A}{P(A)}$ | -| $\Psi(A)$ | $A{R(A)}^{2/3}$ | -| $\Psi'(A)$ | $\frac{\left\{ \Psi(A + \Delta A) - \Psi(A - \Delta A) \right\}}{(2\Delta A)}\ \ where\ \Delta A = 0.001A_{full}$ | - - - : []{#_Toc484690430 .anchor}**Table 5‑12 Properties in the rounded top - section of a modified basket handle shape** - -### 5.1.7 Area at Maximum Flow - -The solution method for kinematic wave analysis in a closed conduit -needs to know what cross-sectional area corresponds to the flow depth -where the section factor and hence the Manning equation flow rate is a -maximum (see Sections 4.2 and 4.3.2). Below this point the section -factor is an increasing function of area, after which it decreases until -the conduit becomes full. Table 5-13 lists the ratio of the area at -maximum flow (denoted as *Amax*) to the full area (*Afull*) for the -standard closed conduit shapes recognized by SWMM. For open shapes -*Amax* is the same as *Afull*. - - **Shape** $$\frac{\mathbf{A}_{\mathbf{\max}}}{\mathbf{A}_{\mathbf{full}}}$$ **Shape** $$\frac{\mathbf{A}_{\mathbf{\max}}}{\mathbf{A}_{\mathbf{full}}}$$ - -| | | | | -| --- | --- | --- | --- | -| Rectangular | 0.97 | Circular | 0.9756 | -| Elliptical | 0.96 | Arch | 0.92 | -| Basket Handle | 0.96 | Egg | 0.96 | -| Horseshoe | 0.96 | Catenary | 0.98 | -| Gothic | 0.96 | Semi-Circular | 0.96 | -| Semi-Elliptical | 0.98 | Rectangular-Triangular | 0.98 | -| Rectangular-Round | 0.98 | Modified Basket Handle | 0.96 | - - - : []{#_Toc484690431 .anchor}**Table 5‑13 Area at maximum flow to full - area for standard closed conduits shapes** - -### 5.1.8 Area from Section Factor - -Kinematic wave analysis also needs to know the area *A* corresponding to -a given normal flow rate *Q* from its associated section factor *Ψ*, -where $\Psi = \frac{Q\sqrt{S_{0}}}{\eta}$. For circular shapes and the -seven masonry sewer shapes discussed in section 5.2.5 the following -"reverse" lookup method is used with the shape's *Ψ* versus *A* table -(*Ψtbl*) to determine *A* given *Ψ*. - -Let *Ψ\** be the section factor value whose area is sought and let *N* -be the number of entries in *Ψtbl*. First the interval in the table -that brackets $\frac{\Psi^{*}}{\Psi_{full}}$ is located. Since these are -all closed shapes, there will be a table entry index *imax* after -which the $\frac{\Psi}{\Psi_{full}}$ values begin to decrease. If -$\frac{\Psi^{*}}{\Psi_{full}}$ is between *Ψtbl*\[*imax*\] and -*Ψtbl*\[*N*\] then this portion of the table is examined to find the -index *i\** so that $\frac{\Psi^{*}}{\Psi_{full}}$ is between -*Ψtbl*\[*i\**\] and *Ψtbl*\[*i\*+1*\]. Otherwise a bisection search -is used between index 0 and *imax* to find the interval starting at -*i\** that brackets $\frac{\Psi^{*}}{\Psi_{full}}$. Then the area *A\** -corresponding to *Ψ\** is computed as: - - -$$A^{*} = \frac{A_{full}}{(N - 1)}\left( i^{*} + \frac{\left( \Psi^{*} - \Psi_{tbl}\left\lbrack i^{*} \right\rbrack \right)}{\left( \Psi_{tbl}\left\lbrack i^{*} + 1 \right\rbrack - \Psi_{tbl}\left\lbrack i^{*} \right\rbrack \right)} \right) \qquad \text{(5-17)}$$ - - - -For all other shapes the Newton-Raphson-Bisection method (see Appendix -A) is used to find the solution of - - $f(A) = \Psi(A) - \Psi^{*} = 0$ (5-18) - - -where *Ψ\** is the section factor value whose corresponding area is -sought. The derivative of *f(A)* required by the method is the shape's -*Ψ'(A)* function. If the shape is closed with *Amax \< Afull* and -*Ψ\** is between *Ψfull* and *Ψmax* then the search interval is -\[*Afull, Amax*\]. Otherwise it is \[0, *Amax*\]. The convergence -criterion is 0.01 percent of *Afull* . - -## 5.2 Custom Conduit Shapes - -In addition to its catalog of standard pre-defined shapes, SWMM can also -utilize custom closed shapes that are defined by a Shape Curve supplied -by the user. This curve specifies how the width of the cross-section -varies with height, where both width and height are scaled relative to -the section\'s full height. This allows the same shape curve to be used -for conduits of differing sizes. An example shape curve along with its -table of width versus height is shown in Figure 5-7. - -+--------------------------------------------------------------------------+---------------------------------------------------------------------------+ -| ![ShapeCurve2.png](VolumeII/media/media/image29.png){width="2.50034886264217in" | ----------------------------------------------------------------------- | -| height="2.375331364829396in"} | ***Y/Yfull*** ***W/Yfull*** ***Y/Yfull*** ***W/Yfull*** | -| | ----------------- ----------------- ----------------- ----------------- | -| | 0.00 0.000 0.56 0.928 | -| | | -| | 0.08 0.667 0.64 0.874 | -| | | -| | 0.16 0.930 0.72 0.798 | -| | | -| | 0.24 1.000 0.80 0.697 | -| | | -| | 0.32 0.997 0.88 0.567 | -| | | -| | 0.40 0.988 0.96 0.342 | -| | | -| | 0.48 0.967 1.00 0.000 | -| | ----------------------------------------------------------------------- | -+==========================================================================+===========================================================================+ - -: []{#_Toc484694730 .anchor}**Figure 5‑7 A Shape Curve with a depth -segment shown** - -The flow area *A*, top width *W* and hydraulic radius *R* of a custom -shape are pre-computed at 51 equally spaced vertical values between 0 -and 1 along the shape curve and stored in tables *Atbl, Wtbl*, and -*Rtbl*, respectively. The tables are constructed by analyzing each -depth segment of size 1/50 = 0.02 starting at 0 and working upwards. As -shown in Figure 5-7, each depth segment forms a trapezoid within the -cross section. The area of this trapezoid is added to the shape's total -area *Asum* and the length of its side walls is added to the total -wetted perimeter *Psum*. If the depth segment straddles more than one -shape curve segment, then additional trapezoids are formed at the shape -curve's vertices, each of which contributes to *Asum* and *Psum*. -The *Atbl* entry for the segment is set to *Asum*, the *Rtbl* -entry to $\frac{A_{sum}}{P_{sum}}$, and the *Wtbl* entry to the -segment's top width. - -When a conduit with full depth *Yfull* is assigned a shape curve for -its cross section, the curve's geometry tables are used in the same -manner as the tables for ellipsoid and arch shapes described in section -5.1.4 for evaluating *A(Y), W(Y)*, *R(Y),* *Y(A), Ψ(A),* and *Ψ'(A)*. -The values of *Afull, Rfull*, and *Wmax* used to convert the -normalized values in the tables to actual dimensions are as follows: - - -$$A_{full} = A_{tbl}\lbrack 50\rbrack Y_{full}^{2} \qquad \text{(5-19)}$$ - -| | | | -| --- | --- | --- | -| | $R_{full} = R_{tbl}\lbrack 50\rbrack Y_{full}$ | (5-20) | -| | $W_{\max} = \left\{ \max_{0 \leq i \leq 50}{W_{tbl}\lbrack i\rbrack} \right\} Y_{full}$ | (5-21) | - - -The value of *Amax*, the area of the flow depth where the section -factor is a maximum, is given by: - - -$$A_{\max} = \left\{ \max_{0 \leq i \leq 50}\left( A_{tbl}\lbrack i\rbrack{R_{tbl}\lbrack i\rbrack}^{2/3} \right) \right\} Y_{full}^{2} \qquad \text{(5-22)}$$ - - - -The Newton-Raphson-Bisection method described in section 5.1.8 is used -to evaluate *A(Ψ).* - -## 5.3 Irregular Natural Channels - -SWMM also has the ability to model natural channels with irregular -shaped cross sections. The cross sectional shape is represented by a -transect that begins at the top of the left bank of the channel (looking -downstream) and extends transversely across the channel to the top of -its right bank. The channel's bed elevation (*y*) relative to a known -elevation is recorded at a series of measurement stations (*x*) across -the transect (see Figure 5-8). A single transect is used to represent a -channel's cross section along its entire length. This might require that -longer channels with varying cross section profiles be broken into -smaller more uniform segments. - -As shown in Figure 5-8, transects can contain two overbank areas on -either side. Each is optional and is used to specify a different -Manning's roughness coefficient than that assigned to the main channel. -Each overbank boundary location must coincide with one of the transect's -measurement stations. - -
-Transect2.png -

Figure 5‑8 A natural channel -transect

-
- -The flow area *A*, top width *W* and hydraulic radius *R* of a transect -are pre-computed at 51 equally spaced values of flow depth relative to -full depth $\left( \frac{Y}{Y_{full}} \right)$ and stored in tables -*Atbl, Wtbl*, and *Rtbl*, respectively. The table values are -normalized with respect to the full section area A*full*, the maximum -width *Wmax*, and the full section hydraulic radius *Rfull*, -respectively. These tables are used in the same manner as the tables for -ellipsoid and arch shapes described in section 5.1.4 for evaluating -*A(Y), W(Y)*, *R(Y)*, *Y(A), Ψ(A),* and *Ψ'(A)*. *A(Ψ)* is found using -the Newton-Raphson-Bisection method as described in section 5.1.8. - -The first step in constructing the geometric property tables for a -transect is to find the measurement stations with the lowest and highest -elevations. The full channel depth *Yfull* is set equal to the -difference between these values. If necessary, a new station is added at -either end of the transect so that both ends are at the highest -elevation. Then all station elevation values *y* are converted to the -height above the lowest elevation station. - -Next table entries are generated for a series of depths that divide the -full depth into 50 equal increments starting at 0 (whose table entries -are set to 0). The procedure for finding each table's entry for the -*k-th* depth interval is described in the side bar entitled "*Computing -Geometry Table Entries for Irregular Cross Sections*". It traverses the -cross section's transect, computing the area, width, and wetted -perimeter for each measurement station segment that lays above the -current depth increment. It also finds the conductance (the section -factor times roughness) of compound segments that separate regions of -differing roughness or where valleys occur in the transect's profile. -(Figure 5-9 shows a flow depth increment with three compound segments.) -After the end of the transect is reached the sum of the compound -conductances is used along with the main channel roughness to find the -hydraulic radius for the current depth increment. - -
- -

Figure 5‑9 A transect depth increment with -three compound segments

-
- -Once table entries for all depth increments have been generated, the -following quantities are assigned and used to normalize the entries in -their respective tables: -$A_{full} = A_{tbl}\lbrack 50\rbrack,\ \ W_{\max} = W_{tbl}\lbrack 50\rbrack,\ \ R_{full} = R_{tbl}\lbrack 50\rbrack$. -Another adjustment is to set -$W_{tbl}\lbrack 0\rbrack = W_{tbl}\lbrack 1\rbrack$ since the above -procedure does not calculate a width at zero depth. - -An irregular natural channel can also be assigned a meander modifier. -This is the ratio of the length of a meandering main channel to the -length of the overbank area that surrounds it. While the user-supplied -length for the overall channel is that of the longer main channel, SWMM -will use the shorter overbank length in its calculations. The Manning's -*n* of the main channel will be increased by the square root of the -meander modifier to provide an equivalent friction head loss over the -reduced main channel length. - -## 5.4 Street Cross-Sections - -SWMM defines the geometry of a street or roadway cross-section as a -special case of the irregular channel discussed in the previous section. -The shape of a one-sided street cross-section is shown in Figure 5-10. -In its most basic form it consists of a road surface with downward slope -*Sx* extending a distance of *Tcrown* to a vertical curb of height -*Hcurb*. To this can be added: - -- an optional depressed gutter section of width *W* that extends to a - depth "*a*" below the normal curb height - -- an optional backing section extending beyond the curb a distance - *Tback* that rises at a slope of *Sback* . - -A two sided street cross-section adds a mirror image of the one-sided -street to the right of the street crown with the same roadway, gutter, -curb, and backing dimensions. - -![Street.png](VolumeII/media/media/image32.png){width="5.197267060367454in" -height="1.8747659667541556in"} - -**Figure 5-10 A one-sided street cross-section (not to scale)** - -Street cross-sections use the same procedures as irregular channel -transects, described in section 5.3, to compute tables of flow area, top -width, and hydraulic radius at 50 equally spaced increments of flow -depth (for both one-sided and two-sided streets). This requires that in -addition to the dimensions shown in Figure 5-10, a Manning roughness -coefficient must be specified for the road surface and for the backing -surface if present. - -## 5.5 Storage Unit Geometry - -SWMM's hydraulic modeling procedures require knowledge of how a storage -unit's surface area *A* and volume *V* vary with surface depth *Y* above -the bottom of the unit. It is sufficient to specify either an area or -volume relationship with respect to depth since one can be derived from -the other$\ \left( A = \frac{dV}{dY\ and\ V = \int_{}^{}{AdY}} \right)$. -SWMM uses surface area to describe a storage unit's shape. One can -select either from several standard shapes where *A* is a quadratic -function of *Y*, from a general power law relation between *A* and *Y* -or use a tabular listing of *Y* and *A* values. - -### 5.5.1 Standard Storage Shapes - -SWMM supports several common storage unit shapes, listed in Table 5-14, -whose top surface area A can be expressed as a quadratic function of -height Y: - - -$$A = a_{0} + a_{1}Y + a_{2}Y^{2} \qquad \text{(5-23)}$$ - - - -The constants *a0, a1*, and *a2* depend on the shape's dimensions -as shown in Table 5-14. - -+-------------+----------------------------------------------------------------------------------+--------------------------------------------+------------------------+ -| **Shape** | | **Coefficients** | **Dimensions** | -+:============+:=================================================================================+============================================+========================+ -| Elliptical | ![cylindrical.png](VolumeII/media/media/image33.png){width="0.8334492563429571in" | $$a_{0} = \left( \frac{\pi}{4} \right)LW$$ | *L* = major axis | -| Cylinder | height="0.6667596237970254in"} | | length | -| | | $$a_{1} = a_{2} = 0$$ | | -| | | | *W* = minor axis width | -+-------------+----------------------------------------------------------------------------------+--------------------------------------------+------------------------+ -| Elliptical | ![paraboloid.png](VolumeII/media/media/image34.png){width="0.8332294400699912in" | $$a_{0} = a_{2} = 0$$ | *L* = major axis | -| Paraboloid | height="0.708244750656168in"} | | length | -| | | $$a_{1} = (\frac{\pi}{4})\frac{LW}{H}$$ | | -| | | | *W* = minor axis width | -| | | | | -| | | | *H* = paraboloid | -| | | | height | -+-------------+----------------------------------------------------------------------------------+--------------------------------------------+------------------------+ -| Elliptical | ![ConicStorageShape.bmp](VolumeII/media/media/image35.png){width="0.6979166666666666in" | $$a_{0} = \left( \frac{\pi}{4} \right)LW$$ | *L* = bottom major | -| | height="0.5625in"} | | axis length | -| Cone | | $$a_{1} = \pi WZ$$ | | -| | | | *W* = bottom minor | -| | | $$a_{2} = \pi(\frac{W}{L})Z^{2}$$ | axis width | -| | | | | -| | | | *Z* = side slope | -| | | | (run/rise) along major | -| | | | axis | -+-------------+----------------------------------------------------------------------------------+--------------------------------------------+------------------------+ -| Rectangular | ![PrismaticStorageShape.bmp](VolumeII/media/media/image36.png){width="0.96875in" | $$a_{0} = LW$$ | L = bottom length | -| Pyramid | height="0.4270833333333333in"} | | | -| | | $$a_{1} = 2(L + W)Z$$ | W = bottom width | -| | | | | -| | | $$a_{2} = 4Z^{2}$$ | Z = wall slope | -| | | | (run/rise) (same for | -| | | | each face) | -+-------------+----------------------------------------------------------------------------------+--------------------------------------------+------------------------+ - -: **Table 5-14. Standard storage unit shapes.** - -Dynamic wave analysis needs to know how volume *V* varies with depth -*Y*. Integrating Equation 5-23 over depth yields: - - -$$V = a_{0}Y + {(a}_{1}/2)Y^{2} + (a_{2}/3)Y^{3} \qquad \text{(5-24)}$$ - - - -Kinematic wave analysis needs to know the depth associated with a given -volume. For a cylindrical shape: $Y = V/a_{0}$, while for paraboloid -shape: $Y = \sqrt{2V/a_{1}}$ . For the other shapes the cubic equation -5-24 is solved numerically for *Y* given *V* using the -Newton-Raphson-Bisection method described in Appendix A over the -interval \[0, *Yfull*\] with initial estimate $Y = \frac{V}{a_{0}},$ -convergence tolerance of 0.001 ft and derivative given by Equation 5-23. - -### 5.5.2 Functional Storage Shapes - -SWMM's functional storage shape option uses a power law to relate -surface area to depth: - - -$$A = c_{0} + c_{1}Y^{c_{2}} \qquad \text{(5-25)}$$ - - - -where *c0, c1*, and *c2* are user-supplied constants. - -The surface area at a given depth is found directly from this equation. -The relation between volume *V* and depth *Y* (required for dynamic wave -analysis) is: - - -$$V = c_{0}Y + \left( \frac{c_{1}}{c_{2} + 1} \right)Y^{c_{2} + 1} \qquad \text{(5-26)}$$ - - - -To find the depth associated with a given volume (required for kinematic -wave analysis) one solves the following nonlinear equation for *Y* : - - -$$f(Y) = V - \left( c_{0}Y + \left( \frac{c_{1}}{c_{2} + 1} \right)Y^{c_{2} + 1} \right) = 0 \qquad \text{(5-27)}$$ - - - -It is solved using the Newton-Raphson-Bisection method described in -Appendix A over the interval \[0, *Yfull*\] with initial estimate -$Y = \frac{V}{\left( c_{0} + c_{1} \right)},$ convergence tolerance of -0.001 ft and derivative $f'(Y)$ given by Equation 5-25. - -Some shapes and their coefficients that can be represented with this -functional option include: - - - -- Shapes with vertical sides and constant surface area no matter how - irregular in outline, including cylinders and rectangular prisms: - -*c0* = area of the base - -*c1 = c2 = 0*. - -- An open channel with a trapezoidal cross section and vertical ends: - -$$c_{0} = WL$$ - -$$c_{1} = 2ZL$$ - -$$c_{2} = 1$$ - -> where *W* = bottom width of cross section, *L* = channel length, and -> *Z* = side slope. - -- An open channel with a parabolic cross section and vertical ends: - -$$c_{0} = 0$$ - -$$c_{1} = WLH^{0.5}$$ - -$$c_{2} = 1$$ - -> where *W* = top width, *L* = channel length and *H* = full height. - -- An elliptical paraboloid: - -$$c_{0} = 0$$ - -$$c_{1} = A/H$$ - -$$c_{2} = 1$$ - -where *A* is the surface area at height *H*. - -### 5.5.3 Tabular Storage Shapes - -The shape of a storage unit can also be defined by a Storage Curve which -is a series of user-supplied data pairs *Yi, Ai* that represent the -points on a curve of surface area versus surface depth for the unit. An -example of this type of curve is shown in Figure 5-11. It can represent -natural depressions with irregular shaped contour intervals, spheroid -storage vessels or conventional shapes with different base sizes stacked -on top of one another. The first point supplied to the curve should be -the surface area of the unit\'s base at a depth of 0. Otherwise it will -be assumed that the unit has zero surface area at its base. The curve -will be extrapolated outwards to meet the unit\'s maximum depth if need -be. - -![StorageCurve2.png](VolumeII/media/media/image37.png){width="4.168351924759405in" -height="3.12626312335958in"} - -
-StorageCurve1.png -

Figure 5‑11 Example of a storage curve and -its section view

-
- -To find the area associated with a given storage depth one interpolates -between the data points that bracket the depth value on the storage -curve. Determining the storage volume *V* at a given depth *Y* is -equivalent to finding the area under the storage curve from depth 0 to -*Y*. This can be done by using the Trapezoidal Rule (Atkinson, 1989) -which results in: - - -$$V = \frac{1}{2}\left\{ \sum_{i = 1}^{n}{\left( Y_{i} - Y_{i - 1} \right)\left( A_{i} + A_{i - 1} \right)} \right\} + \ \frac{1}{2}\left( Y - Y_{n} \right)\left( A + A_{n} \right) \qquad \text{(5-28)}$$ - - - -where *n* is the largest data point index with $Y_{n} \leq Y$ and *A* is -the surface area associated with depth *Y* as found from the storage -curve itself. The shaded rectangles in Figure 5-12 illustrate how the -trapezoidal rule is applied to a storage curve to find the stored volume -at a particular depth. This procedure is the same as the widely used -Average-End-Area method except that the area at the desired depth is -first interpolated from the storage curve rather than converting the -original area curve to a volume curve and interpolating directly from -it. - -
-StorageCurve3.png -

Figure 5‑12 Finding the volume at a given -depth for a storage curve

-
- -The depth that corresponds to a particular volume for a storage curve -can be found as follows. Using the trapezoidal rule, sum the volumes -contributed by each curve segment starting from 0 until the accumulated -volume *Vsum* exceeds the target volume *V*. Let the data point index -at the start of this segment be denoted by *i*. Then the depth *Y* that -results in volume *V* is: - - -$$Y = Y_{i} + \frac{\left\lbrack \sqrt{A_{i}^{2} + 2\alpha\left( V - V_{sum} \right)} - A_{i} \right\rbrack}{\alpha} \qquad \text{(5-29)}$$ - - - -where -$\alpha = \frac{\left( A_{i + 1} - A_{i} \right)}{\left( Y_{i + 1} - Y_{i} \right)}$. - -## 5.6 Critical and Normal Depths - -SWMM needs to calculate the critical and normal flow depths in a conduit -for dynamic wave analysis whenever: - -1. the conduit is connected to a free outfall node - -2. a discontinuity exists between the water level in the conduit and in - its connecting node (i.e. a free fall condition exists). - -These depths are functions of flow rate and cross section shape. For all -but the simplest shapes, iterative numerical methods are required to -compute them. - -### 5.6.1 Critical Depth - -Critical depth is defined as the depth *Y* where the specific energy at -a given flow rate *Q* is a minimum and the Froude number *Fr* equals 1 -(Chow, 1959). From the latter condition - - -$$Fr = \frac{U}{\sqrt{g\frac{A}{W}} = 1} \qquad \text{(5-30)}$$ - - - -where *U* is flow velocity and *g* is the acceleration of gravity. Since -$U = \frac{Q}{A}$ and both area and width are functions of flow depth, -at the critical flow depth *YC* the following relation holds: - - -$$\frac{{A\left( Y_{C} \right)}^{3}}{W\left( Y_{C} \right) = \frac{Q^{2}}{g}} \qquad \text{(5-31)}$$ - - - -*YC* can be computed explicitly for several simple conduit shapes. The -formulas are listed in Table 5-14. Other shapes require that an -iterative root finding procedure be applied to the following re-arranged -form of Equation 5-29: - - -$$\frac{{f(Y) = A(Y)}^{3}}{W(Y) - \frac{Q^{2}}{g} = 0} \qquad \text{(5-32)}$$ - - - -Because analytical derivatives of *f(Y)* are not available for most -shapes, derivative-free methods are used instead of the Newton-Raphson -method. Two such methods are interval enumeration and Ridder's method -(Press et al., 1992). Ridder's method is a variation on the method of -false position. The user supplies a set of depths *Y1* and *Y2* that -bracket *YC* along with a stopping tolerance *ε*. The full algorithm -is described in Appendix B. - - **Shape** **Formula** **Remarks** - -| | | | -| --- | --- | --- | -| Rectangular1 | $Y_{C} = \left( \frac{Q^{2}}{gb^{2}} \right)^{1/3}$ | *b* = width | -| Triangular1< | /sup> $Y_{C} = \left( \frac{2Q^{2}}{gs^{2}} \right)^{1/5}$ | *s* = side slope | -| Parabolic2 $Y_{C} = \left( \frac{27\alpha Q^{2}}{32g} \right)^{1/4}$ | Perimeter Equation: $y = \alpha x^{2}$ | -| Power Law2 $$Y_{C} = \left( \frac{(1 + \gamma)^{3}\alpha^{2\gamma}Q^{2}}{4g} \right)^{\frac{1}{(3 + 2\gamm | a)}}$$ Perimeter Equation: $y = \alpha x^{\frac{1}{\gamma}}$ | - - - : []{#_Toc484690432 .anchor}**Table 5‑14 Critical depth formulas for - simple section shapes** - -1French (1985). - -2Swamee (1993). - -With interval enumeration the full depth of the cross section is divided -into *N* equal intervals (SWMM 5 currently uses *N* = 25). Given a flow -*Q* and an initial estimate of its critical depth *YC*, the following -steps are used to calculate its actual value: - -1. Let *i* be the integer part of $N\frac{Y_{C}}{Y_{full}}$ and set - $Y = i\frac{Y_{full}}{N}$. - -2. Find $Q_{0} = \sqrt{g\frac{{A(Y)}^{3}}{W(Y)}}$. - -3. If $Q_{0} < Q$: - - a. Set $i = i + 1$, $Y = i\frac{Y_{full}}{N}$, and - $Q_{C} = \sqrt{g\frac{{A(Y)}^{3}}{W(Y)}}$. - - b. If $Q_{C} \geq Q$ then stop with - $Y_{C} = \left\lbrack \frac{\left( Q - Q_{0} \right)}{\left( Q_{C} - Q_{0} \right) + (i - 1)} \right\rbrack\left( \frac{Y_{full}}{N} \right)$. - - c. Set $Q_{0} = Q_{C}$ and go to step a. - -4. Otherwise: - - a. Set $i = i - 1$, $Y = i\frac{Y_{full}}{N}$, and - $Q_{C} = \sqrt{g\frac{{A(Y)}^{3}}{W(Y)}}$. - - b. If $Q_{C} < Q$ then stop with - $Y_{C} = \left\lbrack \frac{\left( Q - Q_{C} \right)}{\left( Q_{0} - Q_{C} \right) + i} \right\rbrack\left( \frac{Y_{full}}{N} \right)$. - - c. Set $Q_{0} = Q_{C}$ and go to step a. - -Empirical testing has shown that the interval enumeration method tends -to use less iterations than Ridder's method when: - -1. The ratio of the section's full area to that of a circular section - of same full depth is between 0.5 and 2.0 - -2. The initial estimate of *YC* is computed from the following - approximation for circular sections (French 1985): - - -$$Y_{C} = 1.01\frac{\left( \frac{Q^{2}}{g} \right)^{0.25}}{Y_{full}^{0.26}} \qquad \text{(5-33)}$$ - - - -Therefore interval enumeration is used when the first condition listed -above holds, with the second condition used to set the initial estimate -of *YC*. Otherwise Ridder's method is used with Equation 5-30 as the -function whose root *YC* is to be found with a convergence tolerance -of 0.001 feet. The initial bracket \[*Y1 , Y2*\] on *YC* is -determined as follows: - -1. Let $Y_{1/2} = 0.5Y_{full}\ $and *Y0* be the value computed by - Equation 5-31 above. - -2. Compute $Q_{0} = \sqrt{g\frac{{A(Y_{0})}^{3}}{W(Y_{0})}}$ and - $Q_{1/2} = \sqrt{g\frac{{A(Y_{1/2})}^{3}}{W(Y_{1/2})}}$ . - -3. If $Q_{0} > Q$ then: - - a. Set $Y_{2} = Y_{0}$. - - b. If $Q_{1/2} < Q$ then set $Y_{1} = Y_{1/2}$, otherwise set - $Y_{1} = 0$. - -4. Otherwise: - - a. Set $Y_{1} = Y_{0}$. - - b. If $Q_{1/2} > Q$ then set $Y_{2} = Y_{1/2}$, otherwise set - $Y_{2} = 0.99Y_{full}$. - -### 5.6.2 Normal Depth - -Normal depth is defined as the flow depth that results in a given -uniform flow rate along a conduit. When the Manning equation is used to -describe uniform flow, the relation between flow rate *Q* and normal -depth *YN* is: - - -$$A(Y_{N}){R(Y_{N})}^{2/3} = \frac{Q\eta}{\sqrt{S_{0}}} \qquad \text{(5-34)}$$ - - - -where *η is* the Manning roughness expressed in US units and *S0* is -the conduit's slope. From the definition of the section factor *Ψ* -introduced in Chapter 4, Equation 5-32 can be written as: - - -$$\Psi = \frac{Q\eta}{\sqrt{S_{0}}} \qquad \text{(5-33)}$$ - - - -To find *YN* for flow rate *Q* one first computes *Ψ* from Equation -5-33, then finds the flow area *A* that produces this value of *Ψ* using -the methods described in section 5.1.8 and finally evaluates the depth -that produces this area using the *Y(A)* function for the particular -shape being analyzed. In equation terms: - - -$$Y_{N} = Y\left( A\left( \Psi = \frac{Q\eta}{\sqrt{S_{0}}} \right) \right) \qquad \text{(5-35)}$$ - - - -# - Pumps and Regulators - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -Pumps are used in stormwater and wastewater collection systems to lift -water to a higher elevation so that gravity flow at a reasonable -velocity can be maintained. They are also used to produce pressurized -flow within force mains. Regulators act like valves that restrict the -flow rate along a conduit or out of a storage unit. They can also serve -as diverters that split flow between different branches of a conveyance -system (e.g., between the interceptor and an overflow pipe in a combined -sewer system). Specific types of regulators include orifices, weirs, or -general outlets that differ in their geometry and relationship between -flow and head. This chapter describes how the flow rate through pumps -and regulators is computed for both the dynamic and kinematic wave -models. - -## 6.1 Pumps - -SWMM treats pumps as links that have a pre-defined relationship between -flow rate *Q* and head *H* or some suitable surrogate. This relationship -is defined by a user-supplied Pump Curve. Table 6-1 depicts the five -types of pump curves that SWMM recognizes. Although not a requirement, a -pump's inlet node would typically be a storage node that represents a -pump station's wet well. An exception would be an inline booster pump -placed inside a force main line under dynamic wave analysis. A sixth -type of pump, called an Ideal pump, does not use a pump curve but -instead has its flow rate equal the inflow rate into its inlet node. It -must be the only outflow link from its inlet node and is used mainly for -preliminary design. - -A single point on a Type1 or Type2 curve would typically represent an -operating point for a constant flow positive displacement pump. -Additional points might represent flow rates at different pump speeds or -contributions from additional constant speed pumps running in parallel. -The Type3 curve represents the characteristic curve of a centrifugal -pump operating at some fixed speed, where there is a continuous range of -flows available depending on the head required. The Type4 curve could be -a positive displacement pump with continuous speed control or a -centrifugal pump that lifts water to a more or less fixed elevation so -that the required head depends only on the water level at its inlet -node. A Type5 pump is a variable speed version of the Type3 pump. As the -pump's impeller speed varies relative to some nominal value, flow -changes in direct proportion while head changes in proportion to speed -squared. - -Whenever a pump link is encountered in either the dynamic wave or -kinematic wave methods its new flow is found directly from its pump -curve using whatever values were last computed for nodal heads and -volumes. - -+--------------------------------------+------------------------------------------------------------------------+ -| [Type1]{.underline} | > ![pump1.bmp](VolumeII/media/media/image40.png){width="1.5312489063867016in" | -| | > height="1.3897747156605424in"} | -| Consists of a series of constant | | -| flow rates that apply over a | | -| corresponding series of volume | | -| intervals at the pump's inlet node. | | -+:=====================================+:=======================================================================+ -| [Type2]{.underline} | > ![pump2.bmp](VolumeII/media/media/image41.png){width="1.5833311461067368in" | -| | > height="1.433332239720035in"} | -| Similar to a Type1 pump except that | | -| the fixed flow rate levels vary over | | -| a set of depth intervals at the | | -| pump's inlet node. | | -+--------------------------------------+------------------------------------------------------------------------+ -| [Type3]{.underline} | > ![pump3.bmp](VolumeII/media/media/image42.png){width="1.5784765966754155in" | -| | > height="1.3541655730533684in"} | -| A centrifugal pump characteristic | | -| curve at some nominal impeller speed | | -| represented in a piecewise linear | | -| fashion. Flow is a function of the | | -| head difference between the inlet | | -| and outlet nodes. | | -+--------------------------------------+------------------------------------------------------------------------+ -| [Type4]{.underline} | > ![pump4.bmp](VolumeII/media/media/image43.png){width="1.5121522309711286in" | -| | > height="1.395832239720035in"} | -| A variable speed in-line pump where | | -| flow varies continuously with inlet | | -| node depth. | | -+--------------------------------------+------------------------------------------------------------------------+ -| [Type 5]{.underline} | > ![Pump5.bmp](VolumeII/media/media/image44.png){width="1.531058617672791in" | -| | > height="1.313487532808399in"} | -| A variable speed version of the | | -| Type3 pump where the head v. flow | | -| curve shifts position depending on | | -| the pump's speed setting. | | -+--------------------------------------+------------------------------------------------------------------------+ - -: []{#_Toc484690433 .anchor}**Table 6‑1 Pump curves recognized by SWMM** - -For Type1 and Type 2 curves, the curve is searched in step-wise fashion -for the first point whose volume or depth exceeds the volume or depth at -the pump's inlet node. The pump's flow is the flow associated with that -point. For the Type3 and Type5 curves, the flow is determined by first -finding the pair of adjacent data points that bracket the difference in -head between the pump's outlet and inlet nodes and then interpolating a -flow between these points for the given head difference. A similar -lookup procedure is used for the Type4 curve except that water level at -the pump's inlet node is used instead of head difference. A pump's flow -is not allowed to be outside the minimum and maximum values defined by -its pump curve and is not allowed to be negative. - -The Type5 pump curve is shifted depending on what relative speed setting -*ω* the pump is currently operating under, where a setting of 1.0 -applies to the original user-supplied curve. Following the pump affinity -laws (Sanks et al., 1998), a point with head *H* and flow *Q* on the -original curve becomes $\omega^{2}H$ and $\omega Q$, respectively on the -speed-adjusted curve. For the other pump types only the flow value found -from the original curve is multiplied by the speed setting. - -Speed settings can be changed during a simulation by using control -rules. The setting can also be used to control pump operation based on -wet well level (e.g., set *ω* to 1 when the level is above a startup -depth and to 0 when below a shutoff depth). The adjusted pump flow is -checked to insure it does not cause the water level at the inlet node to -drop below 0 over the current time step. If the node is a storage node -then the pumping rate cannot exceed *Qmax* where - - -$$Q_{\max} = Q_{in} + \frac{V_{N}}{\mathrm{\Delta}t} \qquad \text{(6-1)}$$ - - - -and *Qin* is the most recently computed total inflow to the node, -*VN* is the node volume at the start of the time step, and *∆t* is the -current time step interval. If the inlet node is not a storage node and -dynamic wave analysis is being made, Equation 3-15a is used with the -current pumping rate to estimate what the inlet node head at the end of -the time step would be. If this head is below the node's invert -elevation then the pumping rate is set equal to the node's current -inflow. - -Some additional computational details regarding pumps are as follows: - -1. If the inlet node of a Type1 (flow v. volume) pump is not a storage - node then it is assigned a virtual wet well whose volume varies - linearly with depth up to the highest volume on the pump curve at - full node depth. While the normal non-storage node methods are used - to update the node's water level, the virtual wet well volume - corresponding to the node's water level is used to determine the - pumping rate. Equation 6-1 is also used to limit the pump flow to - the maximum flow that the node can release. - -2. For dynamic wave modeling: - - a. Pumps do not contribute any surface area to the node-link - assemblies at their inlet and outlet nodes. - - b. For Type3, Type4 and Type5 pump curves the - $\frac{\partial Q}{\partial H}$ term used for evaluating a - surcharged node is the negative of the slope of the line segment - on which the pumping rate lies. For the other pump types it is - zero since their line segments have zero slope. - - c. No under-relaxation is applied to consecutive pump flows at Step - 3 of the iterative solution method described in Section 3.2. - -3. SWMM computes the power consumed in kilowatt-hours by each pump over - each time step *∆t* as: - - -$$Kwh = 0.7457\left( H_{2} - H_{1} \right)\frac{Q\left( \frac{\mathrm{\Delta}t}{3600} \right)}{8.814} \qquad \text{(6-2)}$$ - - - -> where heads *H1* and *H2* are in feet, flow *Q* is in cfs, and -> time step *∆t* is in seconds. The pump's wire to water efficiency is -> not included in this calculation. The power consumption in each time -> period is totaled up and reported for each pump in SWMM's Pumping -> Summary Report. Also reported are the percent of time each pump is -> online and operates at either the lower or upper end of its pump -> curve. - -## 6.2 Orifices - -Orifices are regularly shaped, submerged openings through which flow is -proportional to the square root of the head across the opening. Orifices -are typically used to: - -- regulate flow out of detention ponds and other storage facilities - -- regulate flow through channels in the form of sluice gates - -- divert excess flow from interceptor sewers to overflow structures - -- model storm drain inlets. - -### 6.2.1 Representation - -SWMM represents an orifice as a link between two nodes. The opening can -be oriented either in a vertical plane for a side orifice or in a -horizontal plane for a bottom orifice (see Figure 6-1) and be elevated -some distance above the inlet node's invert. A riser pipe or inlet box -used as an outlet structure in a detention pond can be modeled as a -bottom orifice with a vertical offset. For kinematic wave analysis the -inlet node must be a storage node since this is the only type of node -for which a true hydraulic head is computed. For dynamic wave analysis -it can be any type of node. - -
-Orifice2.png -

Figure 6‑1 Orifice -orientations

-
- -The properties of an orifice link include: - -- the height of its opening above the invert of its upstream node - -- the shape of its opening which can be either circular or rectangular - -- the dimensions of its opening (the diameter for a circular orifice or - the height and width for a rectangular orifice) - -- its discharge coefficient (described in more detail below) - -- whether or not it contains a flap gate that prevents reverse flow. - -The size of the orifice opening can be changed during a simulation by -having its setting adjusted using control rules. An orifice's setting is -the fraction of its full height that remains open (such as would occur -due to the action of lowering or raising a sluice gate above a side -orifice). In this case an additional optional parameter is the time it -takes to fully close a completely open (or fully open a completely -closed) orifice. - -### 6.2.2 Flow Rate for Submerged Inlet - -Whenever an orifice link is encountered in the dynamic wave or kinematic -wave solution procedure with its inlet side fully submerged its flow -rate *Q* (cfs) can be found using Torricelli's equation (Brater et al., -1996): - - -$$Q = C_{d}A_{O}\sqrt{2gH_{e}} \qquad \text{(6-3)}$$ - - - -where *Cd* is a dimensionless orifice discharge coefficient, *AO* is -the area of the opening (ft2), and *He* is the effective head seen by -the orifice (ft). The following paragraphs describe how each of these -parameters is evaluated. - -[Discharge Coefficient (*Cd*)]{.underline} - -The most commonly cited value for *Cd* is 0.6 while 0.4 is recommended -for ragged edge orifices (Federal Highway Administration, 2009). Brater -et al. (1996) review a number of experimental studies that show the -coefficient varying between 0.59 and 0.67 depending on orifice shape, -size, and effective head. - -[Area of Opening (*AO*)]{.underline} - -The area of the orifice's opening depends on what its setting is. Let -*ω* be the orifice setting (between 0 and 1) in place at the end of the -previous routing time step and *ω\** be the target setting that was -established the last time that a control rule involving the orifice was -activated. If the time to close/open the orifice, *∆t~O\ ~*, is 0 then -for the current time step ω = *ω\**. Otherwise let *∆ω* be defined as -*ω\* - ω* and *ω* gets updated as follows: - -+---+--------------------------------------------------------------+-----------------------------------------------------------+-------+ -| | $$\omega = \left\{ \begin{matrix} | if | (6-4) | -| | \omega + \frac{sgn(\Delta\omega)\Delta t}{{\Delta t}_{O}} \\ | $\frac{\Delta t}{{\Delta t}_{O}} < \mathrm{\Delta}\omega$ | | -| | \omega^{*} | | | -| | \end{matrix} \right.\ $$ | otherwise | | -+===+==============================================================+===========================================================+=======+ - -where *∆t* is the length of the current time step. With the setting -established, the area of the orifice opening is determined using the -methods described in Chapter 5 to find the area of either a circular or -rectangular cross section, depending on orifice shape, at a fraction *ω* -of its full height. - -[Effective Head (*He*)]{.underline} - -The effective head across the orifice depends on whether the water level -on its outflow side is below the orifice opening or not. Let *H1* be -the most recently computed head at the orifice's nominal upstream node -and *H2* be the same at the nominal downstream node. For kinematic -wave analysis, since the upstream node must be a storage node, *H1* is -the water surface elevation in the storage unit while *H2* is the -invert elevation of the downstream node. If $H_{1} < H_{2}$ and the -orifice does not have a flap gate then the head values are reversed (so -*H1* has the higher value) and the computed flow will be opposite to -the nominal downstream direction. - -With *H1* and *H2* established the following rules are used to -determine the effective head across the orifice, where *ZO* is the -elevation of the bottom of the orifice opening and *Yfull* is its full -height: - -1. For a side orifice: - -+---+------------------------------------------------------------+--------------------------------------------+-------+ -| | $$H_{e} = \left\{ \begin{matrix} | for | (6-5) | -| | H_{1} - \left( Z_{O} + \omega\frac{Y_{full}}{2} \right) \\ | $H_{2} < Z_{O} + \omega\frac{Y_{full}}{2}$ | | -| | H_{1} - H_{2} | | | -| | \end{matrix} \right.\ $$ | otherwise | | -+===+============================================================+============================================+=======+ - -2. For a bottom orifice: - -+---+----------------------------------+--------------------------------------------+-------+ -| | $$H_{e} = \left\{ \begin{matrix} | for $H_{2} \leq Z_{O}$ | (6-6) | -| | H_{1} - Z_{O} \\ | | | -| | H_{1} - H_{2} | otherwise | | -| | \end{matrix} \right.\ $$ | | | -+===+==================================+============================================+=======+ - -Figure 6-2 illustrates how *He* is evaluated for a side orifice. - -### 6.2.3 Flow Rate for Unsubmerged Inlet - -When the water level at the inlet to a side orifice is below the top of -its opening the orifice behaves more like a weir and Equation 6-3 no -longer applies (see Figure 6-3). A similar situation occurs when the -head above a bottom orifice is below some threshold level. For these -cases SWMM determines what the threshold head for weir behavior is and -what the equivalent weir coefficient and crest length should be when -using the standard rectangular weir formula to compute the orifice's -flow rate. The details differ for side and bottom orifices as described -below. - - -------------------------------------------------------------------------------------------------------------------------------------------------- - ![Orifice4.png](VolumeII/media/media/image46.png){width="3.518180227471566in" ![Orifice5.png](VolumeII/media/media/image47.png){width="3.5210892388451445in" - height="2.440871609798775in"} height="2.442891513560805in"} - -| | | -| --- | --- | -| Submerged Upstream Only | Submerged Both Up and Downstream | - - -[]{#_Toc484694736 .anchor}**Figure 6‑2 Determination of effective head -for an orifice** - -
-Orifice6.png -

Figure 6‑3 Orifice with unsubmerged -inlet

-
- -[Side Orifices]{.underline} - -For a side orifice, weir behavior occurs when the inlet water level is -below the top of the orifice opening. Thus the threshold head *H\** is: - - -$$H^{*} = Z_{O} + \omega Y_{full} \qquad \text{(6-7)}$$ - - - -When the inlet head *H1* is below this height the flow through the -orifice can be approximated by using the general weir formula: - - -$$Q = C_{W}L\left( H_{1} - Z_{O} \right)^{1.5} \qquad \text{(6-8)}$$ - - - -where *CW* is a weir coefficient (ft1/2/sec) and *L* is the crest -length of the equivalent weir (ft). Equating the flow from this equation -to that from the orifice equation 6-3 when $H_{1} = H^{*}$ and solving -for *CWL* results in: - - -$$C_{W}L = \frac{C_{d}A_{O}\sqrt{g}}{\omega Y_{full}} \qquad \text{(6-9)}$$ - - - -Thus whenever the upstream head *H1* is below *H\**, flow through the -side orifice can be found using the weir formula 6-8 with *CWL* given -by Equation 6-9. - -[Bottom Orifices]{.underline} - -For a bottom orifice it is assumed that the threshold inlet head *H\** -for weir flow will be at a point where the flow through the orifice -using both the orifice and general weir equations will be the same. In -equation terms: - - -$$C_{d}A_{O}\sqrt{2g}\left( H^{*} - Z_{O} \right)^{0.5} = C_{W}L\left( H^{*} - Z_{O} \right)^{1.5} \qquad \text{(6-10)}$$ - - - -Solving for *H\** results in: - - -$$H^{*} = Z_{O} + \frac{C_{d}A_{O}\sqrt{2g}}{C_{W}L} \qquad \text{(6-11)}$$ - - - -In order to evaluate *H\** values for *CW* and *L* must be assigned. -*CW* can be set to the commonly cited value of 3.33 ft^0.5^/sec used -for sharp crested weirs (Mays, 2001). *L* can be set to the -circumference of the opening as follows: - -+---+---------------------------------------+------------------------------------------+--------+ -| | $$L = \left\{ \begin{array}{r} | for a circular opening | (6-12) | -| | \pi\omega Y_{full\ \ } \\ | | | -| | 2\left( b + \omega Y_{full} \right)\ | for a rectangular opening | | -| | \end{array} \right.\ $$ | | | -+===+=======================================+==========================================+========+ - -where *b* is the fixed width of the rectangular opening. Now *H\** can -be determined for a given orifice coefficient and opening dimensions. -Whenever the upstream head *H1* is below *H\**, flow through the -bottom orifice can be found using the general weir formula 6-8 with -*CW* = 3.33 and *L* given by Equation 6-12. - -[Tailwater Submergence Correction]{.underline} - -As described later on in Section 6.3, whenever the downstream water -level is above a weir's crest the Villemonte equation is applied to -account for the effects of submergence (Brater et al., 1996). So when -the general weir equation 6-8 is used to compute orifice flow and the -downstream head *H2* is above the bottom of the orifice opening -*ZO*, the following submergence adjustment factor *fS* is applied to -the computed flow value: - - -$$f_{S} = \left\lbrack 1 - \left( \frac{H_{2}}{H_{1}} \right)^{1.5} \right\rbrack^{0.385} \qquad \text{(6-13)}$$ - - - -### 6.2.4 Flap Gate Head Loss Adjustment - -When an orifice has a flap gate it adds a small amount of head loss for -flow through the gate. An empirical formula for this head loss was -derived from experiments performed at Iowa State University in the -1930's and published by Armco (1978): - - -$$\mathrm{\Delta}H = \frac{4U^{2}}{g}\exp\left( - 1.15\frac{U}{\sqrt{H_{e}}} \right) \qquad \text{(6-14)}$$ - - - -where *∆H* is the head loss added by the flap gate (ft) and *U* is the -velocity through the orifice (ft/sec) which equals $\frac{Q}{A_{O}}$. -After the orifice's flow is first computed without this additional head -loss, *∆H* is computed with Equation 6-14 and subtracted from *He*. -Then the flow is re-computed, this time using the adjusted value of -effective head. - -### 6.2.5 Dynamic Wave Considerations - -Dynamic wave modeling uses the surface area of the links attached to a -node to update the node's head when it is not in a surcharged state (see -Chapter 3). As an orifice has no length, its contribution to a node's -surface area should be zero. However in older versions of SWMM an -orifice was represented as an equivalent pipe that contributed surface -area to its end nodes just as a real conduit did. To maintain -compatibility with previous versions, SWMM 5 computes a surface area -*ASL* for an orifice as - -+---+-------------------------------------+--------------------------------------------+--------+ -| | $$A_{SL} = \left\{ \begin{array}{r} | for a side orifice | (6-15) | -| | W(Y_{O})L_{O} \\ | | | -| | A\left( \omega Y_{full} \right)\ | for a bottom orifice | | -| | \end{array} \right.\ $$ | | | -+===+=====================================+============================================+========+ - -where: - - *YO* = depth of flow through the orifice (ft), equal to - $\min\left( H_{1} - Z_{O}\ ,\ \omega Y_{full} \right)$ - -| | | | -| --- | --- | --- | -| *LO* | = | equivalent conduit length of the orifice (ft), equal to $\max\left( 2{\Delta t}_{\max}\sqrt{gY_{full}}\ ,200 \right)$ | -| *∆tmax* | = | maximum time step assigned by the user to the simulation (sec) | -| *W(Y)* | = | width of orifice opening at flow depth *Y* (ft) | -| *A(Y)* | = | area of orifice opening at flow depth *Y* (ft) | - - -*W(Y)* and *A(Y)* are evaluated using the formulas from Chapter 5 for -either a circular or closed rectangular cross section shape. Half of -*ASL* is assigned to each of the orifice's end nodes providing that -the node is not a storage unit nor has its head below the orifice -opening. - -Dynamic wave analysis also needs a value for the derivative of a link's -flow rate with respect to head (*dQ/dH*) when updating the head for a -surcharged node connected to the link (see section 3.3.5). For submerged -headwater orifices that use Equation 6-3 to compute flow rate *Q*, this -derivative is: - - -$$\frac{dQ}{dH} = 0.5\frac{Q}{H_{e}} \qquad \text{(6-16)}$$ - - - -while for unsubmerged headwater orifices that use Equation 6-8 to -compute *Q* it is: - - -$$\frac{dQ}{dH} = 1.5\frac{Q}{\left( H_{1} - Z_{O} \right)} \qquad \text{(6-17)}$$ - - - -### 6.2.6 Summary of Orifice Computations - -The computational steps used to compute flow through an orifice link can -be summarized as follows. At the start of a time step: - -1. If the orifice setting has not yet reached its target value or the - target value has been changed by a control rule then update the - setting using Equation 6-4. - -2. If the orifice setting has changed then compute the effective area - of its opening *AO*. For side weirs use Equation 6-7 to compute - its critical head *H\** for weir behavior and Equation 6-9 to - compute its equivalent weir constant *CWL*. For bottom weirs, use - Equation 6-12 to find an equivalent weir length *L*, Equation 6-11 - to find the critical head *H\**, and set the equivalent weir - constant to 3.33*L*. - -For each iteration within a time step that requires computing flow -through the orifice: - -1. Let *H1* denote the most recently computed head at the orifice's - upstream node and *H2* be the same at the downstream node. (For - kinematic wave analysis *H2* is the downstream node's invert - elevation.) - -2. If *H1 \< H2* reverse the values so that *H1* as the higher - head and note that reverse flow will occur. If the orifice has a - flap gate or *H1* is below the orifice opening then set its flow - to 0. - -3. If the orifice is not submerged on its upstream side (*H1 \< H\**) - then use Equation 6-8 to find its flow rate along with Equation 6-13 - to correct for any tailwater submergence. Otherwise use Equation 6-5 - (for side orifices) or 6-6 (for bottom orifices) to find the - effective head *He* on the orifice and then use Equation 6-3 to - compute its flow rate. - -4. If the orifice has a flap gate then use Equation 6-14 to reduce its - effective head and repeat the flow calculation of step 2. - -5. If the orifice has reverse flow then make the computed flow - negative. - -6. Under dynamic wave analysis use Equation 6-15 to assign a surface - area to the orifice and use Equation 6-16 (for side orifices) or - 6-17 (for bottom orifices) to compute $\frac{dQ}{dH}$ for the - orifice. - -## 6.3 Weirs - -A transverse weir is a barrier with a cut-out placed across a conduit -perpendicular to the direction of flow. A side weir is a cut-out along -the side wall of a conduit parallel to the direction of flow. Flow -through a weir is proportional to the height of water above the weir's -crest raised to a power greater than one. Weirs are used for the same -types of reasons as orifices: to regulate flow out of storage -facilities, to regulate flow through channels, and to divert excess flow -from interceptor sewers to overflow structures. While orifices normally -operate with their inlet sides submerged, weirs normally maintain a free -surface above them. - -### 6.3.1 Representation - -SWMM represents a weir as a link between two nodes. For kinematic wave -analysis the inlet node must be a storage node since this is the only -type of node for which a true hydraulic head is computed. For dynamic -wave analysis it can be any type of node. - -The properties of a weir link include: - -- the height of its crest above the invert of its upstream node - -- its orientation (transverse or side flow) - -- the shape and dimensions of its opening - -- the number of end contractions - -- its effective weir coefficient - -- whether or not it contains a flap gate that prevents reverse flow. - -Figure 6-4 shows the different shapes of transverse weirs modeled by -SWMM. The only shape allowed for a side weir is rectangular. - -
-Weirs1.png -

Figure 6‑4 Transverse weir -shapes

-
- -A suppressed rectangular weir has its opening extended across the entire -channel while a contracted weir does not. Weirs are also classified as -being sharp-crested or broad-crested. Sharp-crested weirs have a -relatively short crest thickness so that water springs clear of the -crest as it flows over the weir. The crest of a broad-crested weir is -thick enough so that the overflow remains in contact with the crest -surface. - -The elevation of a weir's crest can be changed during a simulation by -having its setting adjusted using control rules. A weir's setting *ω* is -the fraction of its full height that remains open after it's crest is -moved up or down, as might occur with a downward opening weir gate or -inflatable dam. At a setting of 1 the weir's crest position is at its -lowest possible value and the full height of its opening is available -for flow. At a value of 0 the crest has been raised so that no opening -height remains and no flow can pass through the weir. At intermediate -settings the crest elevation equals its lowest possible value plus 1 - -*ω* times its full opening height. - -### 6.3.2 Transverse Weirs - -[General Equations]{.underline} - -The general equation for free flow over a transverse rectangular weir is -(Brater et al., 1996): - - -$$Q = C_{W}L_{e}H_{e}^{3/2} \qquad \text{(6-18)}$$ - - - -and for a triangular weir is (Brater et al., 1996): - - -$$Q = C_{W}\tan\left( \frac{\theta}{2} \right)H_{e}^{5/2} \qquad \text{(6-19)}$$ - - - -In these equations *Q* is the flow rate (cfs), *Le* is the effective -crest length (ft), *θ* is the slot angle of a triangular weir, *He* is -the effective head seen by the inflow side of the weir (ft), and *CW* -is a weir coefficient (ft1/2/sec). A trapezoidal weir can be treated -as a combination of a rectangular weir and two half-triangular weirs -(Featherstone and Nalluri, 1982) leading to the equations: - - -$$Q = Q_{R} + Q_{T} \qquad \text{(6-20a)}$$ - - - - -$$Q_{R} = C_{WR}L_{e}H_{e}^{3/2} \qquad \text{(6-20b)}$$ - - - - -$$Q_{T} = C_{WT}sH_{e}^{5/2} \qquad \text{(6-20c)}$$ - - - -where *s* is the slope (run / rise) of the trapezoidal side wall and -*CWR* and *CWT* are the coefficients that apply to the rectangular -and triangular portions of the weir, respectively. - -[Effective Head]{.underline} (*He*) - -The effective head seen by a weir, accounting for its current setting, -is: - - -$$H_{e} = H_{1} - \left( Z_{W} + (1 - \omega)Y_{full} \right) \qquad \text{(6-21)}$$ - - - -where *H1* is the higher of the heads at the weir's end nodes, *ZW* -is the elevation of the weir's crest when fully open (i.e., when *ω* = -1), and *Yfull* is the full height of the weir's opening. If *H1* -corresponds to the downstream node of the weir then reverse flow occurs -through the weir unless a flap gate is present in which case the flow is -0. Flow will also be 0 if $H_{e} \leq 0.$ - -[Effective Crest Length]{.underline} (*Le*) - -The effective crest length of a rectangular weir is reduced by the -number of end contractions as follows (Mays, 2001): - - -$$L_{e} = L - 0.1nH_{e} \qquad \text{(6-22)}$$ - - - -where *L* is the actual crest length and *n* = 1 if the weir is placed -away from one side wall, *n* = 2 if it is placed away from both side -walls and *n* = 0 if it occupies the entire width of the conduit (see -Figure 6-4). - -When the setting *ω* for a triangular weir is less than 1 its opening -takes the shape of a trapezoidal weir. In this case the trapezoidal weir -equation 6-18 is used with both *CWR* and *CWT* set equal to the -weir's original coefficient, the side wall slope *s* set equal to -$\tan\left( \frac{\theta}{2} \right)$ and the effective length becomes: - - -$$L_{e} = 2s(1 - \omega)Y_{full} \qquad \text{(6-23)}$$ - - - -This equation is also used for a trapezoidal weir whose setting is less -than 1. - -[Weir Coefficient]{.underline} (*CW*) - -The standard weir coefficient *CW* for a sharp crested rectangular -weir is 3.33 ft1/2/sec (Mays, 2001). For -$\frac{H_{W}}{L} > \frac{1}{3}$ the coefficient has been found to vary -with effective head and weir sizing and placement (Bureau of -Reclamation, 2001). The Kindsvater-Carter method (Bureau of Reclamation, -2001) expresses this dependence with the following formula: - - -$$C_{W} = c1\left( \frac{H_{W}}{Z_{W}} \right) + c2 \qquad \text{(6-24)}$$ - - - -where the constants *c1* and *c2* vary with the ratio of the crest -length *L* to the full width *b* of the cross section in which the weir -is placed as listed in Table 6-2. - -Broad crested weir behavior is considered to occur when the ratio of the -water level above the crest to the crest thickness exceeds a certain -limit. Limits of 1 to 2 have been proposed by Brater et al. (1996), 15 -by French (1985), and 2 to 20 by the Bureau of Reclamation (2001). Table -6-3 is a compilation of broad-crested weir coefficients synthesized by -Brater and King (1976) from several different experimental studies. It -shows the dependence of the coefficient on both head and breadth of -crest. Above a ratio of about 2 the weir behaves as sharp-crested with a -coefficient of 3.32. For ratios below 0.5 the coefficient approaches -2.63. - - ***L/b*** ***c1 (ft1/2/sec)*** ***c2 (ft1/2/sec)*** - 0.2 -0.0087 3.152 - - 0.4 0.0317 3.164 - - 0.5 0.0612 3.173 - - 0.6 0.0995 3.178 - - 0.7 0.1602 3.182 - - 0.8 0.2376 3.189 - - 0.9 0.3447 3.205 - - 1.0 0.4000 3.220 - - : []{#_Toc484690434 .anchor}**Table 6‑2 Kindsvater-Carter constants - for rectangular weir coefficient** - -The standard value for the triangular weir coefficient *CW* is 2.5 -ft1/2/sec (Mays, 2001). Figure 6-5 shows the variation of *CW* (in -ft1/2/sec ) with head over the weir *HW* (in feet) presented by -Brater and King (1976). The range of coefficients is rather small, from -2.5 up to 2.8. - -> ![CWT.png](VolumeII/media/media/image50.png){width="2.5626224846894137in" -> height="2.041411854768154in"} - -[]{#_Toc484694739 .anchor}**Figure 6‑5 Coefficient for triangular weirs -(from Brater and King, 1976)** - -+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Head** | **Breadth of Weir Crest (ft)** | -| | | -| **(ft)** | | -| +--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| | **0.5** | **0.75** | **1.00** | **1.5** | **2.0** | **2.5** | **3.00** | **4.00** | **5.00** | **10.00** | **15.00** | -+:========:+:============:+:============:+:============:+:============:+:============:+:============:+:============:+:============:+:============:+:============:+:============:+ -| **0.2** | 2.80 | 2.75 | 2.69 | 2.62 | 2.54 | 2.48 | 2.44 | 2.38 | 2.34 | 2.49 | 2.68 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **0.4** | 2.92 | 2.80 | 2.72 | 2.64 | 2.61 | 2.60 | 2.58 | 2.54 | 2.50 | 2.56 | 2.70 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **0.6** | 3.08 | 2.89 | 2.75 | 2.64 | 2.61 | 2.60 | 2.68 | 2.69 | 2.70 | 2.70 | 2.70 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **0.8** | 3.30 | 3.04 | 2.85 | 2.68 | 2.60 | 2.60 | 2.67 | 2.68 | 2.68 | 2.69 | 2.64 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **1.0** | 3.32 | 3.14 | 2.98 | 2.75 | 2.66 | 2.64 | 2.65 | 2.67 | 2.68 | 2.68 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **1.2** | 3.32 | 3.20 | 3.08 | 2.86 | 2.70 | 2.65 | 2.64 | 2.67 | 2.66 | 2.69 | 2.64 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **1.4** | 3.32 | 3.26 | 3.20 | 2.92 | 2.77 | 2.68 | 2.64 | 2.65 | 2.65 | 2.67 | 2.64 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **1.6** | 3.32 | 3.29 | 3.28 | 3.07 | 2.89 | 2.75 | 2.68 | 2.66 | 2.65 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **1.8** | 3.32 | 3.31 | 3.31 | 3.07 | 2.88 | 2.74 | 2.68 | 2.66 | 2.65 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **2.0** | 3.32 | 3.30 | 3.30 | 3.03 | 2.85 | 2.76 | 2.72 | 2.68 | 2.65 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **2.5** | 3.32 | 3.31 | 3.31 | 3.28 | 3.07 | 2.89 | 2.81 | 2.72 | 2.67 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **3.0** | 3.32 | 3.32 | 3.32 | 3.32 | 3.20 | 3.05 | 2.92 | 2.73 | 2.66 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **3.5** | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.19 | 2.97 | 2.76 | 2.68 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **4.0** | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.07 | 2.79 | 2.70 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **4.5** | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 2.88 | 2.74 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **5.0** | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.07 | 2.79 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ -| **5.5** | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 3.32 | 2.88 | 2.64 | 2.63 | -+----------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+ - -: []{#_Toc484690435 .anchor}**Table 6‑3 Rectangular broad-crested weir -coefficients (ft1/2/sec)** - -### 6.3.3 Rectangular Side Weirs - -Flow through a rectangular side weir is a case of spatially varied flow -with decreasing discharge and varying flow depth with distance along the -weir. Mays (2001) cites a number of different studies that have -developed discharge equations for side weirs where both the head and -weir coefficient vary spatially. Unfortunately these approaches are too -complex to implement in a program like SWMM. The empirical Engels -equation (Metcalf & Eddy, Inc. 1972) is used instead: - - -$$Q = C_{W}L_{e}^{0.83}H_{e}^{1.67} \qquad \text{(6-25)}$$ - - - -Where flow *Q* is in cfs, length *Le* and head *He* are in feet, and -*CW* is in ft1/2/sec. (It should be noted that previous versions of -SWMM used an incorrect form of this equation that had the exponent on -*Le* equal to 1.0) - -Equation 6-25 applies to positive flow through the weir. For reverse -flow the standard rectangular weir equation 6-18 is used. *CW* was -assigned a value of 3.32 in the original Engels equation. Brunner (2014) -notes that side weir coefficients should be lower than the typical -values used for transverse weirs, and suggests a range of 1.5 to 2.6 for -weirs that model levees or roadways along natural channels. - -### 6.3.4 Submerged Weir Flow - -As shown in Figure 6-6, submerged weir flow occurs when the water level -on the downstream side of the weir (*H2*) is above the crest elevation -(*ZW*). Under this condition weir flow is related not only to the head -on the upstream side of the weir (*H1*) but also to *H2* and *ZW* -(Brater et al., 1996). These effects are commonly accounted for by -applying an adjustment factor *fS* developed by Villemonte (1947) to -the flow computed using the free flow equation: - - -$$f_{S} = \left\lbrack 1 - \left( \frac{H_{2}}{H_{1}} \right)^{n} \right\rbrack^{0.385} \qquad \text{(6-26)}$$ - - - -where *n* is the exponent on head used in the weir flow equation and the -heads *H1* and *H2* are in feet. For transverse rectangular weirs -(Equation 6-18) it is 3/2, for side weirs (Equation 6-25) it is 1.67, -and for triangular weirs (Equation 6-19) it is 5/2. For trapezoidal -weirs separate submergence factors are computed for the rectangular flow -portion (*QR* in Equation 6-20b with *n* = 3/2) and for the triangular -flow portion (*QT* in Equation 6-20c with *n* = 5/2). - -
-Weirs2b.png -

Figure 6‑6 Definitions of submerged and -surcharged weir flow

-
- -### 6.3.5 Surcharged Weir Flow - -As shown in Figure 6-4, the weirs modeled by SWMM assume that the top of -the flow opening extends to the top of the structure that houses the -weir. If this structure is an open channel then the highest head that -the weir can see is ${\omega Y}_{full}$ where *ω* reflects the weir's -current setting. If the structure encloses the weir from above, such as -in a sewer pipe, then the head on the upstream side of the weir can -exceed the structure's crown elevation causing the weir to become -surcharged (see Figure 6-6). In this case the weir acts as an orifice -and its flow should be evaluated using the equivalent of Equation 6-3: - - -$$Q = C_{d}A_{O}\sqrt{2gH_{e}} = C_{O}\sqrt{H_{e}} \qquad \text{(6-27)}$$ - - - -where *CO* is an equivalent orifice constant with units of -ft5/2/sec. - -*CO* can be evaluated by setting Equation 6-27 equal to the -appropriate weir equation (6-18, 6-19, 6-20, or 6-25 depending on weir -type) evaluated at a weir head $H_{e} = {\omega Y}_{full}$for which the -corresponding orifice head would be $\frac{{\omega Y}_{full}}{2}$. The -result is: - - -$$C_{O} = \frac{Q_{W}\left( {\omega Y}_{full} \right)}{\sqrt{\frac{{\omega Y}_{full}}{2}}} \qquad \text{(6-28)}$$ - - - -where $Q_{W}\left( {\omega Y}_{full} \right)$ is the flow in cfs from -the relevant weir equation for a head of ${\omega Y}_{full}$ feet. The -constant *C~O\ ~* is re-evaluated each time a weir's setting changes. - -Thus if the user indicates that a weir is allowed to surcharge, then -whenever the upstream head *H1* is above *ZW + Yfull* its flow is -computed using Equation 6-27. The head *He* to be used in this -equation is computed as follows. Let *H\** be the head corresponding to -the elevation at half of the weir's opening height, i.e.: - - -$$H^{*} = Z_{W} + (1 - \omega)Y_{full} + \frac{\omega Y_{full}}{2} \qquad \text{(6-29)}$$ - - - -Then - -+---+----------------------------------+--------------------------------------------+--------+ -| | $$H_{e} = \left\{ \begin{matrix} | for $H_{2} < H^{*}$ | (6-30) | -| | H_{1} - H^{*} \\ | | | -| | H_{1} - H_{2} | otherwise | | -| | \end{matrix} \right.\ $$ | | | -+===+==================================+============================================+========+ - -In addition, the correction for weir submergence is not applied. - -### 6.3.6 Flap Gate Head Loss Adjustment - -When a weir has a flap gate it adds a small amount of head loss for flow -through the gate. The same Armco formula used for orifices is used to -compute this head loss for weirs: - - -$$\mathrm{\Delta}H = \frac{4U^{2}}{g}\exp\left( - 1.15\frac{U}{\sqrt{H_{e}}} \right) \qquad \text{(6-31)}$$ - - - -where *∆H* is the head loss added by the flap gate (ft) and *U* is the -velocity through the weir (ft/sec). To evaluate the velocity term in -this equation one needs to know the effective area *Ae* of flow over -the weir. This area equals - -+---+----------------------------------------------------------+----------------------------------+--------+ -| | $$A_{e} = \left\{ \begin{matrix} | for normal weir flow | (6-32) | -| | A\left( H_{W} + y_{C} \right) - A\left( y_{C} \right) \\ | | | -| | A\left( Y_{full} \right) - A\left( y_{C} \right) | for surcharged weir flow | | -| | \end{matrix} \right.\ $$ | | | -+===+==========================================================+==================================+========+ - -where *Yfull* is the full height of the weir opening, *yC* is the -distance that the weir crest has been raised due to the current setting -(equal to $(1 - \omega)Y_{full}$ ), and *A(y)* is the area of the weir -opening at flow depth *y*. The latter quantity is found using the -geometry functions described in Chapter 5 for either a rectangular, -triangular, or trapezoidal shape. Knowing *Ae*, $U = \frac{Q}{A_{e}}$, -where the flow *Q* has been determined using the methods described in -the previous sections. - -After the orifice's flow is first computed without this additional head -loss, *∆H* is computed with Equation 6-31 and subtracted from *He*. -Then the flow is re-computed, this time using the adjusted value of -effective head. - -### 6.3.7 Dynamic Wave Considerations - -A weir does not contribute any surface area to its end nodes under -dynamic wave modeling. The derivative of its flow rate with respect to -head *(dQ/dH)*, used when updating the head of a surcharged end node -(see section 3.3.5), is computed using the formulas in Table 6-4. - -+----------------------------------+-----------------------------------------------------------------------------------+ -| **Weir Type** | **Flow Derivative *(dQ/dH)*** | -+:=================================+===================================================================================+ -| Transverse Rectangular | $$1.5\frac{|Q|}{H_{e}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ -| Side Flow Rectangular: | | -+----------------------------------+-----------------------------------------------------------------------------------+ -| > a\. $Q \geq 0$ | $$1.67\frac{|Q|}{H_{e}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ -| > b\. $Q < 0$ | $$1.5\frac{|Q|}{H_{e}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ -| Transverse Triangular: | | -+----------------------------------+-----------------------------------------------------------------------------------+ -| > a\. Fully open (*ω* = 1) | $$2.5\frac{|Q|}{H_{e}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ -| > b\. Partly open (*ω* \< 1) | $$1.5\frac{\left| Q_{R} \right|}{H_{e} + 2.5\frac{\left| Q_{T} \right|}{H_{e}}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ -| Transverse Trapezoidal | $$1.5\frac{\left| Q_{R} \right|}{H_{e} + 2.5\frac{\left| Q_{T} \right|}{H_{e}}}$$ | -+----------------------------------+-----------------------------------------------------------------------------------+ - -: []{#_Toc484690436 .anchor}**Table 6‑4 Formulas for flow derivatives of -various types of weirs** - -Note: For trapezoidal openings, *QR* is the flow through the central -rectangular portion and *QT* is the flow through the triangular end -portions (see Equation 6-20). - -### 6.3.8 Summary of Weir Computations - -The computational steps used to compute flow through a weir link can be -summarized as follows. If the weir is allowed to surcharge and its -setting *ω* changes at the start of a time step then use Equation 6-28 -to compute an equivalent orifice coefficient *CO* to use during -surcharge conditions. For each iteration within a time step that -requires computing flow through the weir: - -1. Let *H1* denote the most recently computed head at the weir's - upstream node and *H2* be the same at the downstream node. (For - kinematic wave analysis *H2* is the downstream node's invert - elevation.) - -2. If *H1 \< H2* reverse the values so that *H1* as the higher - head and note that reverse flow will occur. If the weir has a flap - gate or *H1* is below the weir crest then set its flow to 0. - -3. If the head *H1* is above the top of the weir's opening and the - weir is allowed to surcharge then use the equivalent orifice - equation 6-27 to find its flow where the effective head is found - from Equations 6-29 and 6-30. - -4. Otherwise use Equation 6-21 to find the effective head on the weir - and either Equation 6-18, 6-19, 6-20, or 6-25, depending on weir - type, to find its flow rate. - -5. If the weir has a flap gate then use Equation 6-31 to adjust its - effective head and repeat the flow calculation of steps 3 and 4. - -6. If the weir is not surcharged use Equation 6-26 to correct the flow - for any tailwater submergence. - -7. If the weir has reverse flow then make the computed flow negative. - -8. Under dynamic wave analysis use the formulas in Table 6-4 to compute - $\frac{dQ}{dH}$ for the weir. - -## 6.4 Outlets - -SWMM's outlet link is a generic type of flow regulator with a user -defined rating curve that relates flow rate to effective head. It can be -used in cases where the head-flow relationships that SWMM uses for -orifice or weir links do not apply. Some examples would be: - -- a side orifice using the Smith and Coleman weir equation, where flow - rate varies with head raised to the 1.645 power (Metcalf & Eddy, Inc., - 1972), - -- a perforated riser pipe with a grate on top used as a detention pond - outlet structure, - -- a vortex-type flow regulator (Hydro International, 2009; Faram et - al., 2010) that provides more precise flow control than do standard - orifices (see Figure 6-7). - -For kinematic wave analysis the outlet's upstream node must be a storage -node since this is the only type of node for which a true hydraulic head -is computed. For dynamic wave analysis it can be any type of node. - -The properties of an outlet link include: - -- the height of its offset above the invert of its upstream node - -- a rating curve that defines the relationship between head and the - resulting flow rate - -- whether head is defined by just the water level at the upstream node - of the link or by the difference in head between its upstream and - downstream nodes - -- whether or not it contains a flap gate that prevents reverse flow. - -An outlet link can also have a flow setting between 0 and 1 that can be -modified by control rules. The setting serves as a multiplier applied to -the flow determined from the outlet's rating curve. - -The rating curve can be defined either as an analytical power law -function or a tabular listing of points on the curve. The analytical -power function has the form: - - -$$Q = aH_{e}^{b} \qquad \text{(6-33)}$$ - - - -where *Q* is flow rate (cfs), *He* is the effective head (ft), and *a* -and *b* are user-supplied constants. The tabular rating curve consists -of pairs of head (*He*) and flow (*Q*) values for points that the user -chooses to represent the shape of the outlet's rating curve. - -
-hydra-brake4.png -

Figure 6‑7 Rating curve for a vortex -device compared to an orifice

-
- -The following steps are used whenever the flow through an outlet link -must be computed: - -1. Let *H1* denote the most recently computed head at the outlet's - upstream node and *H2* be the same at the downstream node. (For - kinematic wave analysis *H2* is the downstream node's invert - elevation.) - -2. If *H1 \< H2* reverse the values so that *H1* has the higher - head and note that reverse flow will occur. If the outlet has a flap - gate or *H1* is below the outlet's offset elevation then set its - flow to 0. - -3. For dynamic wave modeling, if the outlet's rating curve is based on - head difference then compute an effective head on the outlet as - $H_{e} = H_{1} - max\left( H_{2},\ \ \ Z_{O} \right)$ where *ZO* - is the outlet's offset elevation. Otherwise $H_{e} = H_{1} - Z_{O}$. - -4. For an analytical rating curve use Equation 6-33 to compute the - outlet's flow rate *Q*. For a tabular rating curve find the adjacent - head values in the table that bracket *He* and use linear - interpolation to find a corresponding flow rate *Q*. (If *He* is - below the first entry in the table then use the first entry's flow - value. If it is above the last entry then use the last entry's flow - value.) - -5. Multiply *Q* by whatever outlet setting is currently in effect and - change its sign if reverse flow occurs. - -# - Advanced Features - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -## 7.1 Evaporation and Seepage - -### 7.1.1 Conduits - -SWMM can model evaporation and seepage losses from conduits as a -uniformly distributed lateral outflow along the length of the conduit. -The following paragraphs explain how user-supplied evaporation and -seepage rates per unit area are converted into a distributed loss per -unit length for a conduit and how this loss rate is factored into the -solution of the governing equations for both dynamic and kinematic wave -modeling. - -[Distributed Uniform Evaporation Rate]{.underline} - -SWMM can use time varying evaporation data from several different types -of external sources. These include historical daily values from the -National Weather Service, values computed from an historical record of -daily temperatures, user-supplied monthly average values or a -user-supplied hourly time series. The details are described in Volume I -(Hydrology) of this reference manual. These data express the potential -evaporation rate over the entire study area as a volumetric loss per -unit of area per unit of time, which SWMM converts to internal units of -cfs/ft2. The following expression converts the rate per unit area into -a rate per unit length of channel (only open channels can evaporate) -over the time period *t* to *t+∆t*: - - -$$q_{E} = e_{t}W\left( \overline{\overline{Y}} \right) \qquad \text{(7-1)}$$ - - - -where - - $$q_{E}$$ = uniformly distributed evaporation rate along a channel - (cfs/ft) - -| | | | -| --- | --- | --- | -| $e_{t}$ | = | potential evaporation rate per unit area over the current time period (cfs/ft2) | -| $\overline{\overline{Y}}$ | = | average depth of flow in the channel over the current time period (ft) | -| *W(Y)* | = | width of water surface at depth of flow *Y* (ft). | - - -The program automatically extracts the appropriate rate *et* from the -evaporation data source for the current time period being analyzed. The -water surface width *W* is computed using the procedures described in -Chapter 5 for a particular channel's cross sectional shape. - -The average depth of flow in the channel is computed differently -depending on the hydraulic modeling procedure used. For kinematic wave -modeling, - - -$$\overline{\overline{Y}} = \frac{\left( {Y(A}_{1}^{t}) + {Y(A}_{2}^{t} \right))}{2} \qquad \text{(7-2)}$$ - - - -where $A_{1}^{t}$ is the flow area at the upstream end of the channel -previously computed for time *t*, $A_{2}^{t}$ is the same at the -downstream end of the channel, and *Y(A)* is the flow depth associated -with flow area *A* . The latter function is evaluated using the -procedures described in Chapter 5. - -For dynamic wave modeling the average channel depth is computed as: - - -$$\overline{\overline{Y}} = \frac{\left( {\overline{Y}}^{t} + {\overline{Y}}^{t + \mathrm{\Delta}t} \right)}{2} \qquad \text{(7-3)}$$ - - - -where $\overline{Y} = \frac{\left( Y_{1} + Y_{2} \right)}{2}$. The -*Y1* and *Y2* values for ${\overline{Y}}^{t + \mathrm{\Delta}t}$ are -evaluated with Equation 3-16 for the most recently computed nodal head -solution *Hlast* in the iterative procedure used to solve the dynamic -wave equations. Thus $\overline{\overline{Y}}$ and therefore *qE* can -change as the dynamic wave iterations unfold within a time step. - -[Distributed Uniform Seepage Rate]{.underline} - -The seepage loss from a conduit could be due to infiltration into the -soil beneath an unlined or natural channel or result from a leaking or -perforated pipe. In theory the rate would depend upon such factors as -the flow depth in the conduit, the hydraulic conductivity of the -surrounding soil, the variation in moisture content of this soil and the -depth to groundwater. Rather than try to rigorously model the dynamics -of soil infiltration beneath the seeping conduit SWMM uses a -user-supplied constant seepage rate per unit area that can be different -for each conduit. At any given time period this rate is converted to a -uniformly distributed rate per length of conduit as follows: - - -$$q_{S} = sf_{c}W(\overline{\overline{Y}}) \qquad \text{(7-4)}$$ - - - -where - -+-------------------------------------+------------------------------------+-------------------------------------------------------------+ -| $$q_{S}$$ | = | uniformly distributed seepage rate per length of conduit | -| | | (cfs/ft) | -+:============================+:======+===+================================+=============================================================+ -| *s* | = | user-supplied seepage rate per unit area for the conduit | -| | | (cfs/ft2) | -+-------------------------------------+------------------------------------+-------------------------------------------------------------+ -| *fc* | = | monthly climate adjustment factor for the current time step | -| | | (dimensionless) | -+-----------------------------+-------+---+--------------------------------+-------------------------------------------------------------+ -| $$\overline{\overline{Y}}$$ | = | average depth of flow in the conduit over the current time period (ft). | -+-----------------------------+-----------+----------------------------------------------------------------------------------------------+ - -The monthly climate adjustment factors are a set of 12 user-supplied -constants that apply to the study area as a whole. They allow the -intensity of infiltration-based processes to vary on a seasonal basis. -The average flow depth is computed using Equation 7-2 or 7-3, depending -on the choice of flow routing method. - -Equation 7-4 assumes that seepage occurs only in the vertical direction -so that the area over which it takes place is limited by the largest -horizontal extent of the flow cross section. Thus the average depth of -flow $\overline{\overline{Y}}$ is limited by the depth at which the -cross section width is a maximum. Table 7-1 lists the depth at maximum -width, as a fraction of full conduit depth, for several different cross -section shapes recognized by SWMM. For other shapes not listed the depth -at maximum width is as follows: - -- For the Modified Basket Handle shape it is the height of the bottom - rectangular portion of the shape (see Equation 5-15). - -- For irregular channels and custom conduit shapes it is the entry in - the table of width versus depth just prior to where width starts to - decrease with depth. (If width always keeps increasing with depth then - it is the full depth.) - -- For all other shapes it is the full depth. - - **Shape** **Relative **Shape** **Relative - Depth** Depth** - Circular 0.50 Horseshoe 0.50 - - Ellipsoid 0.48 Catenary 0.25 - - Arch 0.28 Gothic 0.45 - - Basket Handle 0.20 Semi-Circular 0.15 - - Egg 0.64 Semi-Elliptical 0.15 - - : []{#_Toc484690437 .anchor}**Table 7‑1 Relative depth at maximum - width for select cross section shapes** - -[Total Uniform Loss Rate]{.underline} - -The total uniform outflow rate along a conduit *qL* is the sum of the -evaporative and seepage loss rates: - - -$$q_{L} = q_{E} + q_{S} \qquad \text{(7-5)}$$ - - - -Over any given time step *∆t* the total volume lost to this outflow -cannot exceed the average volume contained in the conduit: - - -$$q_{L}L\mathrm{\Delta}t \leq \overline{\overline{A}}L \qquad \text{(7-6)}$$ - - - -where $\overline{\overline{A}}$ is the average flow area over the time -step and *L* is the conduit length. Thus - - -$$q_{L} = \min\left( q_{L},\frac{\overline{\overline{A}}}{\mathrm{\Delta}t} \right) \qquad \text{(7-7)}$$ - - - -For kinematic wave analysis the average flow area over the time step -from *t* to *t+∆t* is: - - -$$\overline{\overline{A}} = \frac{\left( A_{1}^{t} + A_{2}^{t} \right)}{2} \qquad \text{(7-8)}$$ - - - -where $A_{1}^{t}$ is the flow area at the upstream end of the conduit -computed for time *t* and $A_{2}^{t}$ is the same at the downstream end -of the conduit. For dynamic wave analysis: - - -$$\overline{\overline{A}} = \frac{\left( {\overline{A}}^{t} + {\overline{A}}^{t + \mathrm{\Delta}t} \right)}{2} \qquad \text{(7-9)}$$ - - - -where -${\overline{A}}^{t} = \frac{\left( A\left( Y_{1} \right) + A\left( Y_{2} \right) \right)}{2}$ -for *Y1* and *Y2* computed at time *t*, with a similar expression -used for ${\overline{A}}^{t + \mathrm{\Delta}t}$. In the latter case the -flow depths *Y* are computed using the most recently computed nodal -heads (see Equation 3-16) as the iterative dynamic wave solution -unfolds. - -An additional constraint on *qL* is that it cannot be greater than the -inflow rate $Q_{1}^{t + \Delta t}$ to the conduit under kinematic wave -analysis or the last computed flow *Qlast* under dynamic wave -analysis. - -[Dynamic Wave Modifications]{.underline} - -For dynamic wave analysis, including a uniform loss rate adds an -additional term *∆Qlateral* to Equation 3-14 used to update a -conduit's flow rate over a time step. The revised equation is: - - -$$Q_{t + \Delta t} = \frac{Q_{t} + {\mathrm{\Delta}Q}_{inertia} + {\mathrm{\Delta}Q}_{pressure} + \mathrm{\Delta}Q_{lateral}}{1 + {\mathrm{\Delta}Q}_{friction}} \qquad \text{(7-10)}$$ - - - -where $\mathrm{\Delta}Q_{lateral} = 2.5\overline{U}q_{L}$ and all other -*∆Q* terms were defined previously in Section 3.2. See the sidebar below -for the derivation of this modified equation. - -Another modification needed when including a uniform loss rate is to add -*qLL* (the total flow lost over the length of the conduit) to the -total outflow from the upstream node of a conduit with positive flow or -add it to the total inflow of the downstream node of a conduit with -negative flow. This modifies the $\sum_{}^{}Q^{t + \mathrm{\Delta}t}$ -term (the net inflow minus outflow to a node) in Equation 3-15a which is -used to update nodal heads. - -[Kinematic Wave Modifications]{.underline} - -For kinematic wave analysis, adding a uniform loss term modifies the -original continuity equation 4-1 as follows: - - -$$\frac{\partial A}{\partial t} + \frac{\partial Q}{\partial x} + q_{L} = 0 \qquad \text{(7-11)}$$ - - - -Carrying the *qL* term over into the original finite difference form -of this equation (Equation 4-7) produces: - - -$$\frac{(1 - \theta)\left( A_{1}^{t + \Delta t} - A_{1}^{t} \right) + \theta\left( A_{2}^{t + \Delta t} - A_{2}^{t} \right)}{\Delta t} + \frac{(1 - \phi)\left( Q_{2}^{t} - Q_{1}^{t} \right) + \phi\left( Q_{2}^{t + \Delta t} - Q_{1}^{t + \Delta t} \right)}{L} + q_{L} = 0 \qquad \text{(7-12)}$$ - - - -where all notation was defined previously in Section 4.2. After -substituting the Manning equation $Q = \beta\Psi(A)$ into this -expression the same non-linear equation for $A_{2}^{t + \Delta t}$ -results as before (equation 4-8): - - -$$\beta\Psi\left( A_{2}^{t + \Delta t} \right) + C1A_{2}^{t + \Delta t} + C2 = 0 \qquad \text{(7-13)}$$ - - - -with *C1* given by Equation 4-9 and *C2* by Equation 4-10 but with the -additional term $q_{L}\frac{L}{\phi}$ added to it. - -### 7.1.2 Storage Units - -An open storage unit can evaporate water from its top surface and, if -unlined, can have a seepage loss due to water infiltrating into the soil -beneath its bottom and sloped sides. SWMM represents each of these -losses as a flow rate per unit area of surface exposed. The exposed -surface area (top for evaporation, bottom and sides for seepage) is -computed based on the storage unit's water depth at the start of each -computational time step. The combined total loss rate (in cfs) from both -processes is then subtracted from the net inflow to the storage unit so -that its new water depth at the end of the time step can be computed. - -[Evaporation Loss]{.underline} - -The evaporation loss rate from the surface of a storage unit during a -time period is based on the surface area in the unit at the start of the -time period using the following equation: - - -$$Q_{EN} = e_{t}f_{E}A_{SN}\left( Y^{t} \right) \qquad \text{(7-14)}$$ - - - -where - - $$Q_{EN}$$ = evaporation loss rate from a storage unit node (cfs) - -| | | | -| --- | --- | --- | -| *t* | = | starting time for the current computational time period (sec) | -| $e_{t}$ | = | potential evaporation rate per unit area at time *t* (cfs/ft2) | -| *fE* | = | fraction of evaporation rate realized | -| *Yt* | = | depth of stored water at time *t* (ft) | -| *ASN(Y)* | = | storage unit surface area at water depth *Y* (ft). | - - -The potential evaporation rate *et* is the same quantity discussed in -the previous section on conduit evaporation and is automatically -retrieved from a study area's evaporation data source as the simulation -unfolds over time. The fraction of this rate realized, *fE*, is a -user-supplied value for each storage unit that allows the rate to be -adjusted for specific local conditions. It would normally be 1.0 but -could be 0 if the storage unit has a roof over it. The depth of stored -water *Y~t\ ~*is the difference between the water surface elevation -*Ht* at time *t* and the storage unit's invert elevation *E*. The -*A(Y)* function represents the user-supplied curve of surface area -versus depth as described in Section 5.4. - -[Seepage Loss]{.underline} - -The seepage loss from a storage unit is modeled as infiltration of -ponded water into the native soil beneath the unit. The Green-Ampt soil -infiltration method is used to compute the rate of seepage per unit area -over time. Its fundamental formula is: - - -$$q_{SN} = K_{S}f_{C}\left\lbrack 1 + \frac{\left( \psi_{S} + d \right)\theta_{d}}{F} \right\rbrack \qquad \text{(7-15)}$$ - - - -where - - *qSN* = seepage rate per unit area from the storage unit node - (cfs/ft2) - -| | | | -| --- | --- | --- | -| *KS* | = | soil saturated hydraulic conductivity (ft/sec) | -| *fC* | = | monthly climate adjustment factor for the current time step (dimensionless) | -| *d* | = | depth of stored water above the area undergoing seepage (ft) | -| $\psi_{S}$ | = | soil capillary suction head (ft) | -| *θd* | = | soil moisture deficit (dimensionless) | -| *F* | = | cumulative depth of infiltrated water (ft). | - - -The monthly seepage adjustment factor is the same user-supplied set of -multipliers used for conduit seepage described previously for equation -7-4. *KS, ψS*, and the initial value of *θd* are all parameters -associated with the Green-Ampt model. Both *θd* and *F* are modified -by the model over time. Equation 7-15 makes the seepage rate dependent -on the ratio of stored water depth to cumulative infiltrated depth, both -of which will vary over time - -The details of SWMM's implementation of the Green-Ampt infiltration -model are covered in Chapter 4 of Volume I (Hydrology) of this manual. -The only difference when using it for a storage unit is that the -quantity $\psi_{s}$ in the original formulation is replaced with -$\psi_{s} + d$. Volume I also provides guidance on selecting values of -*KS*, $\psi_{s}$, and an initial *θ~d\ ~* based on soil type. If -either $\psi_{s}$ or *θ~d\ ~*are 0 then SWMM assumes a constant seepage -rate equal to *KS* that is independent of storage depth. If *KS* is -0 then no seepage occurs. - -The depth of water to use in the Green-Ampt formula will vary across the -top surface of a storage unit if it has sloped sides as shown in Figure -7-1. SWMM accounts for this by applying the Green-Ampt infiltration -method independently to two separate seepage areas -- one for water in -contact with the flat bottom portion of the unit and a second for water -in contact with the sloped sides. The total seepage loss rate *QSN* -(in cfs) can be expressed as: - - -$$Q_{SN} = q_{btm}\left( d_{btm} \right)A_{btm} + q_{side}\left( d_{side} \right)A_{side} \qquad \text{(7-16)}$$ - - - -where: - - *dbtm* = depth of stored water above bottom of unit (ft) - -| | | | -| --- | --- | --- | -| *qbtm* | = | Green-Ampt infiltration rate based on *d = dbtm* (cfs/ft2) | -| *Abtm* | = | surface area over which bottom seepage occurs (ft2) | -| *dside* | = | average depth of stored water above sloped sides of unit (ft) | -| *qside* | = | Green-Ampt infiltration rate based on *d = dside* (cfs/ft2) | -| *Aside* | = | surface area of sloped sides over which seepage occurs (ft2). | - - -
-StorageUnitSeepage.png -

Figure 7‑1 Depths used for computing -seepage in storage units

-
- -As noted previously, the depth above the bottom of the storage unit -(*dbtm*) is $Y^{t} = H^{t} - E$. The bottom surface area is found from -the unit's storage curve at a depth of 0 (see Section 5.4 for a -discussion of storage curves). The average depth above the sloped sides -is computed as: - -+---+------------------------------------------------------+-------------------------------------+--------+ -| | $$d_{side} = \left\{ \begin{array}{r} | for $Y^{t} < d_{\min}$ | (7-17) | -| | 0 \\ | | | -| | \frac{\left( Y^{t} - d_{\min} \right)}{2} \\ | for | | -| | Y^{t} - \frac{\left( d_{\max} - d_{\min} \right)}{2} | $d_{\min} \leq Y^{t} \leq d_{\max}$ | | -| | \end{array} \right.\ $$ | | | -| | | for $Y^{t} > d_{\max}$ | | -+===+======================================================+=====================================+========+ - -where *dmin* is the storage depth where the sloped sides begin and -*dmax* is the depth where it ends (see Figure 7-1). Both of these -depths can be found from the storage unit's storage curve. The effective -area over which vertical seepage through the sloped sides occurs is -computed as: - - -$$A_{side} = min\left\{ A\left( Y^{t} \right),\ A\left( d_{\max} \right) \right\} - A_{btm} \qquad \text{(7-18)}$$ - - - -[Total Storage Loss]{.underline} - -The total loss rate from a storage unit node, *QLN* (in cfs), over a -given time step is - - -$$Q_{LN} = Q_{EN} + Q_{SN} \qquad \text{(7-19)}$$ - - - -*QLN* is not allowed exceed the volume of water in storage at the -start of the current time step: - - -$$Q_{LN} = min\left\{ Q_{LN},\frac{V_{N}\left( Y^{t} \right)}{\mathrm{\Delta}t} \right\} \qquad \text{(7-20)}$$ - - - -where *VN(Y)* is the storage unit's volume at depth *Y* (see section -5.4 for how it is computed) and *∆t* is the size of the current time -step. - -For a given storage node, *QLN* is computed once at the start of the -current time step based on the known stored water level. For dynamic -wave analysis it is subtracted from the -$\sum_{}^{}Q^{t + \mathrm{\Delta}t}$ term of Equation 3-15a (i.e., is -treated as a nodal outflow) each time the node's head is updated at step -4 of the solution procedure described in Section 3.2. For kinematic wave -analysis, after all link flows have been found, *QLN* is added to the -node's total outflow at the end of the time step (see Equation 4-18) -which is used to update the node's volume and subsequently its hydraulic -head (see Section 4.3.5). - -## 7.2 Minor Losses - -Energy losses caused by rapid changes in magnitude or direction of -velocity are called minor or local losses. They can occur at bends, -contractions, or enlargements in conduit geometry and also be associated -with flows entering a conduit from a larger water body or flows exiting -a conduit to a larger water body. Table 7-2 lists the types of minor -losses most frequently considered in stormwater conveyance networks. - -A minor loss is represented as the product of a loss coefficient and the -local velocity head for a specific location *i* along a conduit: - - -$$\mathrm{\Delta}H_{L} = K_{m,i}\frac{U_{i}^{2}}{2g} \qquad \text{(7-21)}$$ - - - -where $\mathrm{\Delta}H_{L}$ is the minor head loss (ft), *Km,i* is -a loss coefficient, and *Ui* is flow velocity (ft/sec). The location -index *i* is 1 for an entrance loss based on the conduit's upstream -velocity, 2 for an exit loss based on its downstream velocity, or 3 for -an average loss based on its average velocity. - -Minor losses can be included in the St. Venant momentum equation for a -conduit by treating them as a loss per unit length, *hL*, in the same -way that the friction slope *Sf* is treated. This modified version of -the momentum equation (originally equation 3-2 with uniform lateral -outflow rate *qL* included) is: - - -$$\frac{\partial Q}{\partial t} + \frac{\partial\left( \frac{Q^{2}}{A} \right)}{\partial x} + gA\frac{\partial H}{\partial x} + gAS_{f} - U\frac{q_{L}}{2} + gAh_{L} = 0 \qquad \text{(7-22)}$$ - - - -where $h_{L} = \frac{\sum_{i = 1}^{3}{K_{m,i}U_{i}^{2}}}{(2gL)}$ with -*L* being the conduit length. - -+--------------------------+----------------+------------------+-------------+ -| **Type of Loss** | **Frequently** | **Occasionally** | **Rarely** | -| | | | | -| | **Modeled** | **Modeled** | **Modeled** | -+:=========================+:==============:+:================:+:===========:+ -| *Pipes (Full or | | | | -| Partially Full)* | | | | -+--------------------------+----------------+------------------+-------------+ -| Entrance | | x | | -+--------------------------+----------------+------------------+-------------+ -| Exit | | x | | -+--------------------------+----------------+------------------+-------------+ -| Expansion and | | x | | -| Contraction | | | | -+--------------------------+----------------+------------------+-------------+ -| Inlet on branch | | | x | -+--------------------------+----------------+------------------+-------------+ -| Curves or bends | | x | | -+--------------------------+----------------+------------------+-------------+ -| Outfall | | x | | -+--------------------------+----------------+------------------+-------------+ -| *Junctions (Full or | | | | -| Partially Full)* | | | | -+--------------------------+----------------+------------------+-------------+ -| Flow through junction | x | | | -+--------------------------+----------------+------------------+-------------+ -| Bend within junction | x | | | -+--------------------------+----------------+------------------+-------------+ -| Junction with lateral | x | | | -+--------------------------+----------------+------------------+-------------+ -| Junction with inlet | | | x | -+--------------------------+----------------+------------------+-------------+ -| *Channels* | | | | -+--------------------------+----------------+------------------+-------------+ -| Expansion and | | x | | -| Contractions | | | | -+--------------------------+----------------+------------------+-------------+ -| Curves or bends | x | x | | -+--------------------------+----------------+------------------+-------------+ -| Culvert entrance | x | | | -+--------------------------+----------------+------------------+-------------+ -| Culvert exit | x | | | -+--------------------------+----------------+------------------+-------------+ -| Outfall | | x | | -+--------------------------+----------------+------------------+-------------+ - -: []{#_Toc484690438 .anchor}**Table 7‑2 Types of minor losses in -drainage systems (from Frost, 2006)** - -For dynamic wave hydraulics the finite difference form of equation 7-22 -can be found by following the same derivation used earlier in Section -3.2. This results in: - - -$$\frac{\mathrm{\Delta}Q}{\mathrm{\Delta}t} = 2\overline{U}\frac{\mathrm{\Delta}\overline{A}}{\mathrm{\Delta}t} + {\overline{U}}^{2}\frac{\left( A_{2} - A_{1} \right)}{L} - g\overline{A}\frac{\left( H_{2} - H_{1} \right)}{L} - g\eta^{2}\frac{Q\left| \overline{U} \right|}{{\overline{R}}^{4/3}} + 2.5\overline{U}q_{L} - \frac{Q\sum_{i = 1}^{3}{K_{m,i}\left| U_{i} \right|}}{2L} \qquad \text{(7-23)}$$ - - - -After re-arranging terms, the following revised form of the flow -updating equation 3-14 used in step 2 of the dynamic wave solution -procedure of Section 3.2 is: - - -$$Q_{t + \Delta t} = \frac{Q_{t} + {\mathrm{\Delta}Q}_{inertia} + {\mathrm{\Delta}Q}_{pressure} + \mathrm{\Delta}Q_{lateral}}{1 + {\mathrm{\Delta}Q}_{friction} + \mathrm{\Delta}Q_{loss}} \qquad \text{(7-24)}$$ - - - -where - - -$$\mathrm{\Delta}Q_{loss} = \frac{\mathrm{\Delta}t}{2L}\sum_{i = 1}^{3}{K_{m,i}\left| U_{i} \right|} \qquad \text{(7-25)}$$ - - - -and all other *∆Q* terms are as defined previously in Sections 3.2 and -7.1.1. Minor losses are not computed for kinematic wave analysis since -it uses a simplified version of the momentum equation that only accounts -for gravitational and friction forces. Frost (2006) provides guidance on -selecting values for the loss coefficient *Km*. - -## 7.3 Force Mains - -For dynamic wave modeling SWMM allows the user to designate particular -circular pipes as force mains. These pipes will use either the -Hazen-Williams or the Darcy-Weisbach equation to compute their friction -losses when pressurized conditions occur. For free surface flow the -Manning equation continues to be used. - -### 7.3.1 Hazen-Williams Force Mains - -The standard form of the Hazen-Williams equation in US units is (Clark -et al., 1977): - - -$$U = 1.318C_{HW}R_{full}^{0.63}S_{f}^{0.54} \qquad \text{(7-26)}$$ - - - -where *U* is velocity (ft/sec), *Rfull* is the full pipe hydraulic -radius (ft), *Sf* is the friction slope (head loss per unit length) -(ft/ft), and *CHW* is the user-supplied Hazen-Williams C-factor -coefficient. Typical values of the C-factor are listed in Table 7-3. - -Solving Equation 7-26 for *Sf* and putting the result in a form -similar to the Manning equation (see Equation 3-3) gives: - - -$$S_{f} = \frac{0.6|U|^{0.852}Q}{C_{HW}^{1.852}A_{full}R_{full}^{1.667}} \qquad \text{(7-27)}$$ - - - -+-----------------+----------------+-----------------+----------------+ -| **Pipe | **C-factor** | **Pipe | **C-Factor** | -| Material** | | material** | | -+=================+:==============:+=================+:==============:+ -| Asbestos Cement | 140 | Corrugated | 60 | -| | | Steel | | -+-----------------+----------------+-----------------+----------------+ -| Brick Sewer | 100 | Ductile Iron | 140 | -+-----------------+----------------+-----------------+----------------+ -| Cast Iron: | 130 | Galvanized Iron | 120 | -| | | | | -| Unlined | 100 | | | -| | | | | -| Asphalt Coated | 140 | | | -| | | | | -| Cement Lined | | | | -| | +-----------------+----------------+ -| | | Plastic PVC | 130 | -| | +-----------------+----------------+ -| | | Polyethylene | 140 | -| | +-----------------+----------------+ -| | | Vitrified Clay | 110 | -+-----------------+----------------+-----------------+----------------+ -| Concrete | 120 | Welded Steel | 100 | -+-----------------+----------------+-----------------+----------------+ - -: []{#_Toc484690439 .anchor}**Table 7‑3 Hazen-Williams C-factors for -different pipe materials** - -This expression replaces the Manning formula for *Sf* when a force -main flows full. As a result, the friction term in the equation used to -update the conduit's flow in the iterative dynamic wave solution -procedure (Equation 3-14) becomes: - - -$${\mathrm{\Delta}Q}_{friction} = 0.6g\frac{\left| \overline{U} \right|^{0.852}\Delta t}{C_{HW}^{1.852}R_{full}^{1.667}} \qquad \text{(7-28)}$$ - - - -where $\overline{U} = \frac{Q^{last}}{A_{full}}$. - -### 7.3.2 Darcy-Weisbach Force Mains - -The standard form of the Darcy-Weisbach head loss equation is (Clark et -al., 1977): - - -$$S_{f} = \frac{fU^{2}}{2gD} \qquad \text{(7-29)}$$ - - - -where *Sf* is the friction slope (head loss per unit length) (ft/ft), -*U* is flow velocity (ft/sec), *D* is pipe diameter (ft), and *f* is a -dimensionless friction factor. Noting that $D = 4R_{full}$ for a -circular pipe allows this equation to be expressed in a form similar to -the Manning formula: - - -$$S_{f} = \frac{f|U|Q}{8gA_{full}R_{full}} \qquad \text{(7-30)}$$ - - - -As a result, the friction term in the equation used to update a -pressurized force main's flow in the iterative dynamic wave solution -procedure (Equation 3-14) becomes: - - -$${\mathrm{\Delta}Q}_{friction} = \frac{f\left| \overline{U} \right|\Delta t}{8R_{full}} \qquad \text{(7-31)}$$ - - - -The friction factor *f* can be determined graphically from the Moody -diagram as a function of the flow's Reynolds number (*Re*) and the -pipe's relative roughness (Bhave, 1991). For laminar flow (Re ≥ 2000) -the friction factor is: - - -$$f = \frac{64}{Re} \qquad \text{(7-32)}$$ - - - -where $Re = \frac{D\left| \overline{U} \right|}{\mu}$ with *μ* being the -kinematic viscosity of water taken as 1.1×10^-5^ ft2/sec. For -transition and rough turbulent flow (*Re* ≥ 4000) the Swamee and Jain -approximation to the Colebrook-White formula is used (Bhave, 1991): - - -$$f = \frac{0.25}{\left\lbrack \log\left( \frac{\epsilon}{3.7D} + \frac{5.74}{{Re}^{0.9}} \right) \right\rbrack^{2}} \qquad \text{(7-33)}$$ - - - -where $\epsilon$ is the equivalent surface roughness height (ft) of the -pipe wall as supplied by the user. This roughness height serves the same -purpose as the Manning roughness coefficient or the Hazen-Williams -C-factor. Typical values for different pipe materials are given in Table -7-4. For *Re* between 2000 and 4000 linear interpolation is used between -the friction factor at *Re* = 2000 (equal to 0.032) and that at *Re* = -4000 (which will also depend on $\frac{\epsilon}{D}$). - - **Material** $\mathbf{\epsilon}$ **Material** $\mathbf{\epsilon}$ - **(inches)** **(inches)** - Concrete 0.012 -- 0.12 Asphalted Cast 0.0048 - Iron - - Cast Iron 0.010 Welded Steel 0.0018 - - Galvanized iron 0.006 PVC 0.00006 - - : []{#_Toc484690440 .anchor}**Table 7‑4 Darcy-Weisbach roughness - heights for different pipe materials** - -### 7.3.3 Equivalent Manning's n - -For pipes designated as force mains a C-factor or roughness height will -be specified instead of a Manning roughness coefficient. Since the -Manning equation will still be used to analyze free surface flow when -the pipe is only partly full a method is needed to determine a Manning's -*n* that will be consistent with the other forms of pipe roughness. SWMM -does this by equating the Manning full pipe flow to either the -Hazen-Williams or Darcy-Weisbach flow computed under fully turbulent -conditions for a friction slope equal to the pipe's bottom slope. - -When the Manning full normal flow is equated to the Hazen-Williams -formula flow the result is: - - -$$\left( \frac{1.486}{n} \right)^{2}R_{full}^{4/3}S_{O} = \left( 1.318C_{HW}R_{full}^{0.63}S_{O}^{0.54} \right)^{2} \qquad \text{(7-34)}$$ - - - -where *SO* is the pipe's bottom slope (ft/ft), *Rfull* is in feet, -and *n* has units of sec/m1/3. Expressing *Rfull* as $\frac{D}{4}$ -and solving for *n* gives: - - -$$n = \frac{1.067\left( \frac{D}{S_{O}} \right)^{0.04}}{C_{HW}} \qquad \text{(7-35)}$$ - - - -Doing the same for the Darcy-Weisbach formula produces: - - -$$\left( \frac{1.486}{n} \right)^{2}R_{full}^{4/3}S_{O} = \frac{2gDS_{O}}{f(\epsilon,\infty)} \qquad \text{(7-36)}$$ - - - -where - - -$$f(\epsilon,\infty) = \frac{0.25}{\left\lbrack \log\left( \frac{\epsilon}{3.7D} \right) \right\rbrack^{2}} \qquad \text{(7-37)}$$ - - - -Expressing *Rfull* as $\frac{D}{4}$ and solving for *n* gives: - - -$$n = \sqrt{\frac{f(\epsilon,\infty)}{185}}D^{1/6} \qquad \text{(7-38)}$$ - - - -To summarize, when flowing full under dynamic wave analysis, a pipe -designated as a force main uses Equation 7-28 (for Hazen-Williams) or -7-31 (for Darcy-Weisbach) in place of Equation 3-14c to evaluate -${\mathrm{\Delta}Q}_{friction}$ in the iterative flow updating Equation -3-14. For free surface flow it uses the Manning form of -${\mathrm{\Delta}Q}_{friction}$ (Equation 3-14c) with an *n*-value given -by Equation 7-35 (for Hazen-Williams) or 7-38 (for Darcy-Weisbach). - -## 7.4 Culverts - -Culverts are closed conduits that allow water from an open stream or -channel to flow under a road, railroad, trail, or similar obstruction -from one side to the other side (see Figure 7-2). A complete description -of culverts and their hydraulic performance is provided by the Federal -Highway Administration in their Hydraulic Design of Highway Culverts -manual (FHWA, 2012). The equations used by SWMM to model culverts are -taken from this publication. - -
- -

Figure 7‑2 Concrete box culvert (from -FHWA, 2012)

-
- -Culvert flow can be controlled either by the inlet or the outlet. Inlet -control occurs when the conveyance capacity of the culvert's barrel is -higher than what the inlet will accept. Otherwise outlet control occurs, -with the possibility that flow may be limited by backwater effects. -Culverts are usually analyzed under a steady design flow condition to -determine if the resulting inlet water depth will be acceptable. However -for SWMM's unsteady dynamic wave analysis they are analyzed to find the -flow corresponding to known inlet and outlet depths. (Culvert analysis -is not made under kinematic wave analysis.) - -Any SWMM conduit link can be designated as a culvert by assigning it one -of the code numbers associated with a particular shape, material, and -inlet configuration listed in Table H-1 in Appendix H. The choice made -from the table should be consistent with the conduit's designated shape -(circular, rectangular, ellipsoid, or arch). At any given time step of a -simulation the flow through the culvert is first determined using SWMM's -usual dynamic wave procedure. This flow represents the outlet control -condition. Then an inlet controlled flow is computed to see if it -becomes the limiting flow rate. - -### 7.4.1 Inlet Control Flow - -Under inlet control, a rating curve establishes the relationship between -culvert flow rate and inlet head. The shape of the curve varies -depending on the culvert's shape, material, and geometry of its inlet -opening. Figure 7-3 shows a typical inlet control rating curve in -normalized form, where inlet headwater depth (*Y1*) is normalized by -the full barrel depth (*Yfull*) and flow rate (*Q*) is normalized by -$A_{full}\sqrt{Y_{full}}$ where *Afull* is the full cross-section area -of the barrel. When the inlet is submerged it performs as an orifice -while when unsubmerged it performs as a weir. - -
- -

Figure 7‑3 Example of a culvert rating -curve (from FHWA, 2012)

-
- -Based on extensive experimental testing done by the National Bureau of -Standards, FHWA has developed inlet rating curves for a number of -different types of culverts and their inlet configurations. The curves -have been fitted to analytical functions that describe both their -submerged and unsubmerged portions. Table H-1 in Appendix H lists the -different types of culverts for which parameterized rating curves have -been developed. Table H-2 lists the parameter values used for both the -unsubmerged and submerged portions of each curve. - -### 7.4.2 Unsubmerged Inlet Control Curves - -The FHWA procedures identify two types of unsubmerged curves used to -compute inlet control for a culvert. The form 1 equation is: - - -$$\frac{H_{1} - Z_{1}}{Y_{full}} = \frac{E_{C}}{Y_{full}} + K_{I}\left\lbrack \frac{Q_{IC}}{A_{full}\sqrt{Y_{full}}} \right\rbrack^{M_{I}} + ScfS_{O} \qquad \text{(7-39)}$$ - - - -while the form 2 equation is: - - -$$\frac{H_{1} - Z_{1}}{Y_{full}} = K_{I}\left\lbrack \frac{Q_{IC}}{A_{full}\sqrt{Y_{full}}} \right\rbrack^{M_{I}} \qquad \text{(7-40)}$$ - - - -The following definitions apply to these equations: - - *H1* = hydraulic head at the inlet node of the culvert link (ft) - -| | | | -| --- | --- | --- | -| *Z1* | = | elevation of the culvert invert at its inlet end (ft) | -| *QIC* | = | inlet controlled flow rate through the culvert (cfs) | -| *EC* | = | specific head at critical depth for flow *QIC* (ft) | -| *Yfull* | = | full depth of the culvert barrel (ft) | -| *Afull* | = | full area of the culvert barrel cross section (ft2) | -| *SO* | = | culvert barrel slope (ft/ft) | -| *Scf* | = | slope correction factor (0.7 for mitered inlets and -0.5 for all others) | -| *KI, | = | constants from Table H-2 for corresponding culvert type in | -| MI* | | Table H-1. | - - -Table H-2 also specifies which equation is used for each type of -culvert. It should be noted that *KI* has a factor of -$g^{\frac{- M_{I}}{2}}$ embedded in it so that equations 7-39 and 7-40 -are dimensionally consistent. - -The form 2 equation can be solved directly to determine *QIC* for a -given inlet head *H1*: - - -$$Q_{IC} = A_{full}\sqrt{Y_{full}}\left( \frac{H_{1} - Z_{1}}{K_{I}Y_{full}} \right)^{\frac{1}{M_{I}}} \qquad \text{(7-41)}$$ - - - -For the form 1 equation, the specific head at critical depth is defined -as: - - -$$E_{C} = Y_{C} + \frac{U_{C}^{2}}{2g} \qquad \text{(7-42)}$$ - - - -where *YC* is the critical depth for flow *QIC* and *UC* is the -velocity at this depth. From the definition of critical depth given by -Equation 5-28 in Section 5.5.1: - - -$$U_{C}^{2} = g\frac{A\left( Y_{C} \right)}{W\left( Y_{C} \right)} \qquad \text{(7-43)}$$ - - - -and from Equation 5-29: - - -$$Q_{IC} = A\left( Y_{C} \right)\sqrt{g\frac{A\left( Y_{C} \right)}{W\left( Y_{C} \right)}} \qquad \text{(7-44)}$$ - - - -The area *A* and top width *W* values in these equations are evaluated -at flow depth *YC* using the methods described in Chapter 5 that -depend on the culvert's shape and dimensions. - -Substituting these relations into the form 1 equation 7-39 results in -the following nonlinear equation in the single unknown *YC* : - - -$$\frac{Y_{C}}{Y_{full}} = \frac{H_{1} - Z_{1} - \frac{Y_{HC}}{2}}{Y_{full}} - K_{I}\left\lbrack \frac{A\left( Y_{C} \right)}{A_{full}}\sqrt{g\frac{Y_{HC}}{Y_{full}}} \right\rbrack^{M_{I}} - ScfS_{O} \qquad \text{(7-45)}$$ - - - -where $Y_{HC}$ is the critical hydraulic depth defined as -$\frac{A\left( Y_{C} \right)}{W\left( Y_{C} \right)}$. This equation is -solved using Ridder's root finding method (see Appendix B) with an -initial bracket on *YC* of 10 to 100 percent of *H1 -- Z1* and a -stopping tolerance of 0.001 ft. After *YC* is found the corresponding -inlet control flow rate *QIC* can be computed using Equation 7-44. - -### 7.4.3 Submerged Inlet Control Curve - -The FHWA equation for inlet control of a culvert whose inlet is -submerged is: - - -$$\frac{H_{1} - Z_{1}}{Y_{full}} = c_{I}\left\lbrack \frac{Q_{IC}}{A_{full}\sqrt{Y_{full}}} \right\rbrack^{2} + y_{I} + ScfS_{O} \qquad \text{(7-46)}$$ - - - -where *cI* and *yI* are constants from Table H-2 for a particular -culvert type in Table H-1. The *cI* constant has a factor of -$\frac{1}{g}$ embedded in it so that equation 7-46 is dimensionally -consistent. Solving this expression for *QIC* results in: - - -$$Q_{IC} = \left\lbrack \left( \frac{1}{c_{I}} \right)\left( \frac{H_{1} - Z_{1}}{Y_{full}} - y_{I} - ScfS_{O} \right) \right\rbrack^{\frac{1}{2}}A_{full}\sqrt{Y_{full}} \qquad \text{(7-47)}$$ - - - -### 7.4.4 Inlet Control Transition Zone - -The FHWA procedure states that the submerged inlet control equation -should be used for values of -$\frac{Q_{IC}}{\left( A_{full}\sqrt{Y_{full}} \right)}$ above 4.0. -Converting this into a condition on *H1* results in: - - -$$H_{1} > {H_{IS} = Z}_{1} + Y_{full}\left( 16c_{I} + y_{I} + ScfS_{O} \right) \qquad \text{(7-48)}$$ - - - -When this condition is satisfied SWMM uses the submerged portion of the -inlet control curve to compute the inlet control flow rate *QIC*. - -FHWA states that the unsubmerged inlet control equation applies for -$\frac{Q_{IC}}{\left( A_{full}\sqrt{Y_{full}} \right)}$ values below -3.5. This is difficult to convert to an a priori limit on *H1* because -of the *EC* term in the form 1 unsubmerged equation. Therefore SWMM -uses an arbitrary criterion of - - -$$H_{1} < {H_{IU} = Z}_{1} + 0.95Y_{full} \qquad \text{(7-49)}$$ - - - -to determine if the unsubmerged inlet control equations should be used. - -When *H1* is between *HIU* and *HIS* linear interpolation is used -to compute *QIC* as follows: - - -$$Q_{IC} = Q_{IC}\left( H_{IU} \right) + \left( Q_{IC}\left( H_{IS} \right) - Q_{IC}\left( H_{IU} \right) \right)\frac{\left( H_{1} - H_{IU} \right)}{\left( H_{IS} - H_{IU} \right)} \qquad \text{(7-50)}$$ - - - -where $Q_{IC}\left( H_{IU} \right)$ is the flow from the unsubmerged -equation for a head of *HIU* and $Q_{IC}\left( H_{IS} \right)$ is the -flow from the submerged equation for a head of *HIS*. - -### 7.4.5 Flow Derivatives - -SWMM's dynamic wave procedure needs to evaluate the derivative of a -conduit's flow rate with respect to head *(dQ/dH)* for use when updating -the head of a surcharged end node (see section 3.3.5). The derivatives -for the various methods of computing an inlet control flow limit are as -follows: - - -$$\frac{dQ_{IC}}{dH_{1}} = \left\{ \begin{matrix} -\frac{Q_{IC}}{M_{I}H_{1}} & unsubmerged \\ -\frac{0.5A_{full}^{2}}{c_{I}Q_{IC}} & submerged \\ -\frac{Q_{IC}\left( H_{1S} \right) - Q_{IC}\left( H_{1U} \right)}{H_{1S} - H_{1U}} & transition -\end{matrix} \right.\ \qquad \text{(7-51)}$$ - - - -### 7.4.6 Summary of Culvert Analysis - -The following steps summarize how a culvert conduit is checked for inlet -control each time that a new flow is computed for it under dynamic wave -analysis: - -1. Equation 3-14 is used as usual to compute a first flow estimate *Q*. - This represents an outlet control condition. - -2. If the conduit is not flowing full at both ends, a flow limit - *QIC* due to inlet control is computed. Equations 7-41 or 7-45 are - used if the head *H1* at the culvert's inlet node is below - *H1U*, Equation 7-47 is used if *H1* is above *H1S*, or - Equation 7-50 is used if *H1* is in between these limits. - -3. If *QIC* is less than *Q* then it is replaced with *QIC* and - Equation 7-51 is used to compute the conduit's flow derivative with - respect to head. - -## 7.5 Roadway Weirs - -A culvert will become overtopped when the headwater rises to the -elevation of the roadway (see Figure 7-4). SWMM represents the flow -across the road with a special type of weir link designated as a roadway -weir. It is similar to a standard SWMM transverse rectangular weir but -has its own specific methods for computing a weir coefficient and -submergence factor based on road characteristics. Figure 7-5 shows how a -roadway weir would be configured with a culvert in a SWMM node-link -layout. - -
-OvertoppedRoadway.png -

Figure 7‑4 Roadway overtopping (from FHWA, -2012)

-
- -
-RoadwayWeir2.png -

Figure 7‑5 SWMM node-link representation -of a culvert with a roadway weir

-
- -The standard transverse rectangular weir equation can be used to compute -the flow across a roadway weir as follows: (FHWA, 2012): - - -$$Q = {f_{S}C}_{W}LH^{3/2} \qquad \text{(7-52)}$$ - - - -where *Q* is the overtopping flow rate (cfs), *H* is the height of the -upstream water surface above the roadway crest (ft), *L* is the length -of the roadway crest (ft), *CW* is free flow weir discharge -coefficient (ft1/2/sec) and *fS* is a submergence adjustment factor. - -Values for the flow coefficients *CW* and *fS* have been published -by the FHWA as functions of the headwater depth (*H*), tailwater depth -(*ht*), the width of the roadway (*Lr*), and road surface material. -The functions are shown in graphical form in Figure 7-6. - -
-RoadwayWeirCoeffs.png -

Figure 7‑6 Discharge coefficients for -roadway weirs (from FHWA, 2012)

-
- -To summarize, SWMM includes an additional type of weir, a roadway weir, -used to model flow over the top of a road that sits above a culvert or -possibly an embankment. Its properties include the following: - -- crest elevation (typically the elevation of the road surface) - - - -- crest length (determined by the top width of the channel that the road - crosses) - -- width of the roadway (perpendicular to its crest length). - -- whether the road surface is paved or gravel. - -Unlike the other weirs discussed in Chapter 6, a roadway weir has -neither a control setting nor a flap gate. Its flow versus head relation -is given by equation 7-52, where the head *H* is the difference between -the head at its inlet node and its crest elevation, the tailwater head -*ht* is the difference between its outlet node head and its crest -elevation, and its flow coefficients are determined from the curves in -Figure 7-6. - -## 7.6 Storm Drain Inlets - -Storm drain inlets are structures that convey runoff from roadway -pavements into below ground storm sewers (see Figure 7-7). Inlet type, -sizing and spacing are normally chosen to meet limits on the spread and -depth of water across a roadway as set by local drainage agencies to -maintain public safety. The U.S. Department of Transportation Federal -Highway Administration's Urban Drainage Design Manual (HEC-22) (FHWA, -2009) contains experimentally derived equations for computing the amount -of flow captured by different types of inlets. These equations are -widely used throughout North America and have been incorporated into -SWMM's flow routing routines. - - --------------------------------------------------------------------------------------------------------------------------------------------------- - ![Grate.png](VolumeII/media/media/image59.png){width="2.4482589676290463in" ![CurbOpening.png](VolumeII/media/media/image60.png){width="3.0569444444444445in" - height="2.068134295713036in"} height="1.8127537182852143in"} - ---------------------------------------------------------------------- ---------------------------------------------------------------------------- - - --------------------------------------------------------------------------------------------------------------------------------------------------- - -Figure 7-7 Examples of storm drain inlets. - -Figure 7-8 depicts the different types of street inlet structures whose -hydraulic performance is computed using the HEC-22 procedures. In -addition to these standard inlet types, a custom inlet can also be -deployed. Its performance is defined by a user-supplied rating curve of -captured flow as a function of flow depth, a diversion curve of captured -flow as a function of flow upstream of the inlet, or both curves (see -Figure 7-9). These curves are defined by a tabular listing of their data -points. - -> ![Fig2a.png](VolumeII/media/media/image61.png){width="4.448537839020123in" -> height="3.146272965879265in"} - -Figure 7-8 Standard types of curb and gutter inlets - -![](VolumeII/media/media/image62.png){width="2.75in" height="1.8125in"} - -Figure 7-9 Performance curve for a custom inlet - -### 7.6.1 Model Setup - -To add storm drain inlet modeling into SWMM a site is represented as a -dual drainage system consisting of both street conduits along the ground -surface and sewer conduits below it as shown in Figure 7-10. An inlet -structure will divert some portion of the street flow it sees into a -designated node of the sewer system with the rest being bypassed to -downstream streets. When an inlet's sewer node reaches its full depth -any excess flow that would cause it to flood is sent back through the -inlet and onto the street. - -![DualDrainage.png](VolumeII/media/media/image63.png){width="4.908233814523185in" -height="3.2929975940507434in"} - -Figure 7-10 Representation of a dual drainage system - -The HEC-22 procedures assume that the curb and gutter inlets shown in -Figure 7-8 are placed in conduits that have a Street cross-section shape -as described in Section 5.4. Even if a street conduit does not contain -inlets, it should still be assigned a Street cross-section if the spread -and depth of surface water across it needs to be reported. The Street -cross-sections can be either single sided (have a single section that -slopes downward from the street crown) or dual sided (have mirror image -sloping sections on either side of the street crown) as required. - -Streets can be assigned any number of a specific inlet design (grate, -curb opening, combination, or slotted drain). If the cross-section is -dual sided then each side receives the replicate number of inlets. If a -street needs to use a mix of inlet designs then it needs to be divided -into separate street conduits where each utilizes just a single type of -design. - -As shown in Figure 7-10, inlets can be located either on a continuous -sloping section of roadway (on-grade) or at a low point where flow tends -to pool (on-sag). The HEC-22 procedures make flow capture for on-grade -inlets a function of the approach flow rate they see while flow capture -for on-sag inlets depends on the depth of water that pools above them. - -Because there is no physical link in the model, such as a shared -manhole, weir or orifice, that connects the street and sewer system to -one another, there is no need to have the rim elevation of a sewer -manhole match the invert elevation of the street node that sends inlet -flow into it. - -### 7.6.2 Computational Scheme - -To account for the flow capture and diversion provided by inlets, at -each flow routing time step SWMM adjusts the lateral inflows seen at the -downstream nodes of street conduits with inlets and at the sewer nodes -designated to receive inlet flow. These lateral flows contribute to the -node flow continuity equation 3-5 for dynamic wave routing and to the -link flow continuity equation 4-8 for kinematic wave routing. The steps -involved can be summarized as follows: - -1. Compute the flow captured at each street inlet using the HEC-22 - procedures for standard inlets or table lookup for custom inlets, - using current values of street flow rates and flow depths. - -2. Add each inlet's captured flow to the lateral inflow that enters the - inlet's assigned sewer node and subtract that same flow from the - lateral inflow seen by the downstream node of the inlet's street - conduit. - -3. Add any current overflow (i.e., flooding) that an inlet's sewer node - experiences onto the lateral inflow for the inlet's street node - instead of having it leave the system as it normally would. This - allows for a two-way flow exchange between the street and sewer once - the water level in the sewer node reaches the ground elevation. - -4. Apply the usual flow routing step normally taken by SWMM's routing - methods. - -In Step 1, because each side of a two-sided street has the same -cross-section geometry and number of inlets, flow capture is computed -for only one side using half the total street flow as the approach flow -seen by its inlets. The one-sided flow capture is then doubled to -determine the full flow capture for the entire street. - -### 7.6.3 Flow Capture for On-Grade Inlets - -The flow capture efficiency of an inlet placed on-grade is affected by: - -- inlet type and dimensions - -- approach flow rate, velocity, and spread of water on the street - -- street cross slope and curb depression - -- longitudinal street slope and surface roughness. - -[Grate Inlets]{.underline} - -For a standard street grate located on-grade the HEC-22 equation for -flow capture is: - - -$$Q_{c} = Q\left\{ R_{f}E_{0} + R_{s}(1 - E_{0}) \right\} \qquad \text{(7-53)}$$ - - - -where: - - *Qc* = captured flow (cfs) - *Q* = approach flow (cfs) - - *E0* = ratio of flow over the grate's width to total flow - - *Rf* = frontal capture efficiency - - *Rs* = side capture efficiency - -The frontal capture efficiency *Rf* is: - - -$$R_{f} = 1 - 0.09\ max(0,\ V - V_{o}) \qquad \text{(7-54)}$$ - - - -while the side capture efficiency *Rs* is: - - -$$R_{s} = 1/\left\{ 1 + 0.15V^{1.8}/(S_{x}L^{2.3}) \right\} \qquad \text{(7-55)}$$ - - - -with: - - *V* = velocity of flow over the grate (ft/sec) - *V0* = velocity at which water begins to splash over the inlet - (ft/sec) - - *Sx* = street cross slope (ft/ft) - - *L* = grate length (ft) - -FHWA (2009) contains curves showing how the splash-over velocity *V0* -increases with increasing grate length *L* for the common grate designs -listed in Table 7-5. Table 7-6 contains polynomial expressions that were -fit to these curves by UDFCD (2010) that are used by SWMM. For grates -that do not conform to one of the listed designs the splash-over -velocity must be supplied by the user. - -**Table 7-5 Description of grate inlet types1** - -+------------+-------------------------------------------------------------+---------------------------------------------+ -| **Grate | **Layout** | **Description** | -| Type** | | | -+============+:============================================================+:============================================+ -| P-50 | ![](VolumeII/media/media/image64.png){width="0.4270833333333333in" | Parallel bar grate with 1-7/8" bar spacing | -| | height="0.3541666666666667in"} | on center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| P-50x100 | ![](VolumeII/media/media/image65.emf){width="0.5104166666666666in" | Parallel bar grate with 1-7/8" bar spacing | -| | height="0.34375in"} | on center and 3/8" diameter lateral rods | -| | | spaced at 4" on center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| P-30 | ![](VolumeII/media/media/image66.emf){width="0.4583333333333333in" | Parallel bar grate with 1-1/8" bar spacing | -| | height="0.34375in"} | on center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| Curved | ![](VolumeII/media/media/image67.png){width="0.9686286089238845in" | Curved vane grate with 3-1/4" longitudinal | -| Vane | height="0.6457524059492563in"} | bar and 4-1/4" transverse bar spacing on | -| | | center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| 45° Tilt | ![](VolumeII/media/media/image68.png){width="0.9477985564304462in" | 45° tilt-bar grate with 3-1/4" longitudinal | -| Bar | height="0.635336832895888in"} | bar and 4" transverse bar spacing on center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| 30° Tilt | ![](VolumeII/media/media/image69.png){width="0.9269674103237096in" | 30° tilt-bar grate with 3-1/4" longitudinal | -| Bar | height="0.6457524059492563in"} | bar and 4" | -| | | | -| | | transverse bar spacing on center | -+------------+-------------------------------------------------------------+---------------------------------------------+ -| Reticuline | ![](VolumeII/media/media/image70.png){width="0.6769991251093613in" | Honeycomb pattern of lateral bars and | -| | height="0.39578412073490815in"} | longitudinal bearing bars | -+------------+-------------------------------------------------------------+---------------------------------------------+ - -1See FHWA (2009) for more detailed descriptions and pictures. - -**Table 7-6 Splash-over velocity for different types of grate -inlets1** - - **Grate Type** **Splash over velocity *V0* (ft/s) as a function of - grate length *L* (ft)** - P-50 $$V_{0} = 2.22 + 4.03L - 0.65L^{2} + 0.06L^{3}$$ - - P-50x100 $$V_{0} = 0.74 + 2.44L - 0.27L^{2} + 0.02L^{3}$$ - - P-30 $$V_{0} = 1.76 + 3.12L - 0.45L^{2} + 0.03L^{3}$$ - - Curved Vane $$V_{0} = 0.30 + 4.85L - 1.31L^{2} + 0.15L^{3}$$ - - 45° Tilt Bar $$V_{0} = 0.99 + 2.64L - 0.36L^{2} + 0.03L^{3}$$ - - 30° Tilt Bar $$V_{0} = 0.51 + 2.34L - 0.20L^{2} + 0.01L^{3}$$ - - Reticuline $$V_{0} = 0.28 + 2.28L - 0.18L^{2} + 0.01L^{3}$$ - -1 Source: Denver UDFCD (2010). - -[Curb Opening Inlets]{.underline} - -For a curb opening inlet located on-grade, the HEC-22 equation for flow -capture is: - - -$$Q_{c} = Q\left\{ 1 - {(1 - min(1,\ L/L_{T})\ )}^{1.8} \right\} \qquad \text{(7-56)}$$ - - - -*L* is now the length of the curb opening and *LT* is the length at -which complete flow capture occurs. The latter quantity is computed as: - - -$$L_{T} = 0.6Q^{0.42}S_{L}^{0.3}{(nS_{e})}^{- 0.6} \qquad \text{(7-57)}$$ - - - -where: - - *SL* = longitudinal street slope (ft/ft) - *n* = Manning's roughness coefficient for the street surface - - *Se* = $$S_{x} + (\frac{a}{W)E_{0}}$$ - - *a* = curb depression (ft) - - *W* = depressed gutter width (ft) - - *E0* = ratio of flow over depressed gutter width to total flow - -If *L \> LT* then complete capture is obtained. - -[Computing *E0*]{.underline} - -The on-grade flow capture formulas for grate and curb opening inlets -need to know *Eo*, the fraction of total street flow *Q* within a -distance *W* from the curb or as depicted in Figure 7-11, the ratio of -*QW* to *Q*. For grates this distance is the width of the grate. For -curb openings it is the width of the depressed gutter (if present). - -![CompositeStreetSection2.png](VolumeII/media/media/image71.png){width="6.290880358705162in" -height="2.593426290463692in"} - -Figure 7-11 Street cross-section divided into gutter and roadway flow - -HEC-22 bases its determination of *E0* on Izzard's form of the Manning -equation that relates flow spread *T* to flow rate *Q* for a triangular -cross-section. It is derived from the standard Manning equation by -integrating the hydraulic radius across successive increments of street -width. The result for US standard units is: - - -$$Q = (\frac{0.56}{n)S_{x}^{1.67}S_{L}^{0.5}T^{2.67}} \qquad \text{(7-58)}$$ - - - -(Note: the standard Manning equation has the same form except with the -constant being 0.47.) - -Solving for T as a function of Q gives: - - -$$T = \left\lbrack \frac{Qn}{0.56S_{x}^{1.67}S_{L}^{0.5}} \right\rbrack^{0.375} \qquad \text{(7-59)}$$ - - - -If the street has a uniform cross slope ($a = 0$ in Figure 7-12) then -Equation 7-59 can be used to derive the following expression for*E0*: - - -$$E_{0} = 1 - {(1 - \frac{W}{T})}^{2.67} \qquad \text{(7-60)}$$ - - - -where *T* is evaluated at a given flow rate *Q*. - -For a compound street cross-section with depressed curb ($a > 0$ in -Figure 7-12), HEC-22 provides the following equation for *E0*: - - -$$E_{0} = \frac{1}{1 + \frac{\frac{S_{W}}{S_{X}}}{\left\lbrack 1 + \frac{\frac{S_{W}}{S_{X}}}{\left( \frac{T}{W} - 1 \right)} \right\rbrack^{2.67} - 1}} \qquad \text{(7-61)}$$ - - - -where $S_{W} = S_{X} + \frac{a}{W}$. It is not possible to solve -directly for *E0* since Equation 7-59 for *T(Q)* applies only to a -triangular section of uniform slope. - -To solve equation 7-61 let *QX* and *TX* denote the flow and spread, -respectively, across the non-depressed triangular portion of the -street's cross section. Then the following relations apply: - - -$$Q_{X} = Q(1 - E_{0}) \qquad \text{(7-62)}$$ - - -$$T_{X} = T - W \qquad \text{(7-63)}$$ - - -$$\frac{T}{W} - 1 = \frac{T_{X}}{W} \qquad \text{(7-64)}$$ - - -These can be used in the following iterative procedure to find *E0* -for a particular flow rate *Q*: - -1. Assume a value for *TX*. - -2. Use Equation 7-61 to compute *E0*, with *TX/W* substituted for - *T/W -- 1*. - -3. Compute *QX* from Equation 7-62. - -4. Compute a new value for *TX* using Equation 7-59 with *QX* as - the flow rate. - -5. If there is negligible change in *TX* then stop with the last - value of *E0* as the solution. Otherwise return to Step 2. - -In cases where the width of the grate is smaller than the width *W* of -the depressed gutter section, *E0* is adjusted by the ratio of the -flow area over the grate's width to the flow area over the depressed -gutter width. - -[Combination Inlets]{.underline} - -A combination inlet consists of both a grate and curb opening placed -together at the same location. Its on-grade flow capture equals that of -the grate plus any flow captured by the portion of the curb opening that -extends upstream of the grate's length. The latter flow capture is -computed first and is subtracted from the approach flow used to -determine the grate's flow capture. - -[Slotted Inlets]{.underline} - -The flow capture capability of a slotted inlet located on-grade is the -same as that of a curb opening inlet of equal length. - -[Custom Inlets]{.underline} - -If an on-grade custom inlet is supplied with a flow diversion curve -(captured flow v. approach flow) then that curve will be used to -determine its flow capture. If it only has a flow rating curve (captured -flow v. water depth) then that curve will be used in conjunction with -the water surface depth at the downstream end of the conduit containing -the inlet. - -### 7.6.4 On-Sag Inlet Flow Capture - -HEC-22 has flow capture efficiency for an inlet in a sag location depend -on the size of the inlet's opening and the depth of water that collects -next to it at the street curb. At low flow depths the inlet acts as a -weir with - - -$$Q_{c} = C_{W}L_{W}d^{1.5} \qquad \text{(7-66)}$$ - - - -while at higher depths it acts as an orifice with - - -$$Q_{c} = C_{O}A_{O}\sqrt{2gd} \qquad \text{(7-67)}$$ - - - -In these equations: - - *CW* = weir coefficient (ft^0.5^/sec) - *CO* = orifice coefficient - - *g* = acceleration of gravity (ft/sec2) - - *LW* = effective length of inlet (ft) - - *AO* = open area of inlet (ft2) - - *d* = effective depth of water seen by the inlet (ft). - -[Grate Inlets]{.underline} - -For grate inlets the following values are used in Equations 7-66 and -7-67: - - *CW* = 3.0 - *CO* = 0.67 - - *Lw* = *L + 2W* - - *AO* = $$LWf_{O}$$ - - *d* = $$d_{i} - (\frac{W}{2)S_{W}}$$ - -where *L* is the grate's length, *W* its width, *fO* the ratio of open -area to full area, and *di* is the depth of water at the downstream -node of the conduit containing the inlet. Opening ratios for several -types of grate designs are listed in Table 7-5. - -HEC-22 does not provide clear guidance on what depth causes a switch -from weir flow to orifice flow for grates. Therefore it is assumed the -switch occurs at a depth *d* where Equation 7-66 equals Equation 7-67. -This results in weir flow for depths below $1.79\frac{A_{O}}{L_{W}}$ and -orifice flow for depths above it. - -[Curb Opening Inlets]{.underline} - -For streets with uniform cross slope or for openings greater than 12 -feet in length, the values used in Equation 7-66 for weir flow are -*CW* = 3.0 and *LW* = opening length. Otherwise, *CW* = 2.3 and -$L_{W} = L + 1.8W$ where *L* = opening length and *W* = width of the -depressed gutter. The values used in Equation 7-67 for orifice flow are -$C_{O} = 0.67$ and $A_{O} = hL$ where *h* is the height of the opening. -The effective depth *d* seen by the curb opening inlet under orifice -flow depends on the orientation of the opening's throat relative to the -street surface as shown in Table 7-7. - -Table 7-7 Effective depth for curb opening inlets under orifice flow - -+---------------------------------------------------------------------------------------------------------+-------------------------------------+ -| **Throat Angle** | **Effective Depth** | -+:======================+:===============================================================================:+:====================================+ -| Horizontal | ![HorizontalThroat.bmp](VolumeII/media/media/image72.png){width="1.4685662729658793in" | $$d = d_{i} - \frac{h}{2}$$ | -| | height="0.6769991251093613in"} | | -+-----------------------+---------------------------------------------------------------------------------+-------------------------------------+ -| Inclined | ![InclinedThroat.bmp](VolumeII/media/media/image73.png){width="1.4477362204724409in" | $$d = d_{i} - 0.7071(\frac{h}{2})$$ | -| | height="0.6978291776027996in"} | | -+-----------------------+---------------------------------------------------------------------------------+-------------------------------------+ -| Vertical | ![VerticalThroat.bmp](VolumeII/media/media/image74.png){width="1.4789818460192476in" | $$d = d_{i}$$ | -| | height="0.6978291776027996in"} | | -+-----------------------+---------------------------------------------------------------------------------+-------------------------------------+ - -HEC-22 states that weir flow for on-sag curb openings occurs at -effective depths below *h* while orifice flow occurs at depths greater -than *1.4h*. For depths in between these SWMM uses the following -interpolation formula: - - -$$Q_{c} = (1 - r)Q_{weir} + rQ_{orif} \qquad \text{(7-68)}$$ - - - -where *Qweir* is weir flow capture at depth *h*, *Qorif* is orifice -flow capture at depth *1.4h* and $r = \frac{(d - h)}{(0.4h)}$. - -[Slotted Inlets]{.underline} - -For slotted inlets the variables in the weir and orifice equations 7-66 -and 7-67 are as follows: - - *CW* = 2.48 - *CO* = 0.8 - - *Lw* = *L* - - *AO* = $$LW$$ - - *di* = $$d$$ - -where *L* = inlet length and *W* = inlet width. Weir flow holds for -$d \leq 0.2$ feet while orifice flow occurs for $d \geq 0.4$ feet. In -between these values flow capture is computed using Equation 7-68 with -*Qweir* as weir flow capture at depth 0.2, *Qorif* as orifice flow -capture at depth 0.4 and $r = \frac{(d - 0.2)}{0.2}$. - -[Custom Inlets]{.underline} - -If an on-sag custom inlet is supplied with a flow rating curve (captured -flow v. water depth), then that curve is used to determine its flow -capture. The depth supplied to the curve's lookup table is the depth of -the downstream node of the conduit containing the inlet. If the inlet -was only assigned a diversion curve (captured flow v. approach flow) -then that curve is used thus essentially treating the inlet as if it -were on-grade. - -### 7.6.5 Drop Inlets - -Drop inlets, pictured in Figure 7-12, are used to drain water from -roadside ditches, swales and flat bottom channels. SWMM allows these -structures to be placed in open channels that have either a rectangular -or trapezoidal cross-section. Model set-up for utilizing these inlets is -the same as described in section 7.6.2 and the same computational scheme -applies. The methods used to compute their flow capture efficiencies are -described in the following paragraphs. - -> ![Fig2b.png](VolumeII/media/media/image75.png){width="4.469374453193351in" -> height="1.5731364829396326in"} - -Figure 7-12 Types of channel drop inlets - -[Drop Grate Inlets]{.underline} - -The flow capture equation for a drop grate inlet located on-grade is the -same as for a street grate (see equation 7-53) except that the ratio -*E0* of flow over the grate to total cross-section flow *Q* is given -by: - - -$$E_{0} = \frac{1.486\sqrt{S_{L}}{(yW)}^{1.67}}{nQ{(W + 2y)}^{0.67}} \qquad \text{(7-69)}$$ - - - -where - - *W* = side length of grate parallel to flow direction (ft) - *y* = flow depth in the channel (ft) - - *n* = channel Manning's roughness coefficient - - *SL* = channel longitudinal slope (ft/ft) - -A cross slope *SX* of 1% is assumed unless the grate extends across -the entire bottom width of a trapezoidal channel. In that case *SX* is -taken as the slope of the channel's side wall. - -Drop grates located on-sag use the same weir and orifice equations (7-66 -and 7-67) as do street grates with the only difference being that for -weir flow the effective length of the inlet's sides (*LW* in equation -7-66) is the sum of the lengths of all four sides. - -[Drop Curb Inlets]{.underline} - -Flow capture for drop curb inlets is computed the same as for curb -opening inlets located on sag. The only difference is that the effective -length of the opening is the total length of all four sides and the open -area is the height of the opening times the total length of all four -sides. - -### 7.6.6 Additional Considerations - -[]{#_Toc73193124 .anchor} - -# Appendix - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -#### Newton-Raphson-Bisection Root Finding Method - -The following Newton-Raphson procedure adapted from Press et al. (1992) -is used to solve the equation $f(x) = 0$ over the interval -$\left\lbrack x_{LOW},x_{HIGH} \right\rbrack$ that is known to bracket -the solution with initial estimate *x* and convergence tolerance *ε* : - -# - -#### Ridder's Root Finding Method - -Ridder's method uses the following iterative procedure adapted from -Press et al. (1992) to solve the equation $f(x) = 0$ over the interval -$\left\lbrack x_{1},x_{2} \right\rbrack$ that is known to bracket the -solution with a convergence tolerance of *ε*: - -#### Section Properties of Circular Pipes - - ***Y/Yfull*** ***A/Afull*** ***W/Wmax*** ***R/Rfull*** ***Y/Yfull*** ***A/Afull*** ***W/Wmax*** ***R/Rfull*** - 0.00 0.00000 0.00000 0.01000 0.52 0.52550 0.99920 1.02400 - - 0.02 0.00471 0.28000 0.05280 0.54 0.55093 0.99680 1.04800 - - 0.04 0.01340 0.39190 0.10480 0.56 0.57630 0.99280 1.07000 - - 0.06 0.024446 0.47500 0.15560 0.58 0.60135 0.98710 1.09120 - - 0.08 0.03740 0.54260 0.20520 0.60 0.62640 0.97980 1.11000 - - 0.10 0.05208 0.60000 0.25400 0.62 0.65126 0.97080 1.12720 - - 0.12 0.06800 0.64990 0.30160 0.64 0.67580 0.96000 1.14400 - - 0.14 0.08505 0.69400 0.34840 0.66 0.70015 0.94740 1.15960 - - 0.16 0.10330 0.73320 0.39440 0.68 0.72410 0.93300 1.17400 - - 0.18 0.12236 0.76840 0.43880 0.70 0.74764 0.91650 1.18480 - - 0.20 0.14230 0.80000 0.48240 0.72 0.77080 0.89800 1.19400 - - 0.22 0.16310 0.82850 0.52480 0.74 0.79335 0.87730 1.20240 - - 0.24 0.18450 0.85420 0.56640 0.76 0.81540 0.85420 1.21000 - - 0.26 0.20665 0.87730 0.60640 0.78 0.83690 0.82850 1.21480 - - 0.28 0.22920 0.89800 0.64560 0.80 0.85760 0.80000 1.21700 - - 0.30 0.25236 0.91650 0.68360 0.82 0.87764 0.76840 1.21720 - - 0.32 0.27590 0.93300 0.72040 0.84 0.89670 0.73320 1.21500 - - 0.34 0.29985 0.94740 0.75640 0.86 0.91495 0.69400 1.21040 - - 0.36 0.32420 0.96000 0.79120 0.88 0.93200 0.64990 1.20300 - - 0.38 0.34874 0.97080 0.82440 0.90 0.94792 0.60000 1.19200 - - 0.40 0.37360 0.97980 0.85680 0.92 0.96260 0.54260 1.17800 - - 0.42 0.39878 0.98710 0.88800 0.94 0.97555 0.47500 1.15840 - - 0.44 0.42370 0.99280 0.91760 0.96 0.98660 0.39190 1.13200 - - 0.46 0.44907 0.99680 0.94640 0.98 0.99516 0.28000 1.09400 - - 0.48 0.47450 0.99920 0.97360 1.00 1.00000 0.00000 1.00000 - - 0.50 0.50000 1.00000 1.00000 - - : []{#_Toc484695150 .anchor}**Table C‑1 Circular section properties as - function of depth** - - ***A/Afull*** ***Y/Yfull*** ***Ψ/Ψfull*** ***A/Afull*** ***Y/Yfull*** ***Ψ/Ψfull*** - 0.00 0.0000 0.00000 0.52 0.51572 0.52658 - - 0.02 0.05236 0.00529 0.54 0.53146 0.55354 - - 0.04 0.08369 0.01432 0.56 0.54723 0.58064 - - 0.06 0.11025 0.02559 0.58 0.56305 0.60777 - - 0.08 0.13423 0.03859 0.60 0.57892 0.63499 - - 0.10 0.15643 0.05304 0.62 0.59487 0.66232 - - 0.12 0.17755 0.06877 0.64 0.61093 0.68995 - - 0.14 0.19772 0.08551 0.66 0.62710 0.71770 - - 0.16 0.21704 0.10326 0.68 0.64342 0.74538 - - 0.18 0.23581 0.12195 0.70 0.65991 0.77275 - - 0.20 0.25412 0.14144 0.72 0.67659 0.79979 - - 0.22 0.27194 0.16162 0.74 0.69350 0.82658 - - 0.24 0.28948 0.18251 0.76 0.71068 0.85320 - - 0.26 0.30653 0.20410 0.78 0.72816 0.87954 - - 0.28 0.32349 0.22636 0.80 0.74602 0.90546 - - 0.30 0.34017 0.24918 0.82 0.76424 0.93095 - - 0.32 0.35666 0.27246 0.84 0.78297 0.95577 - - 0.34 0.37298 0.29614 0.86 0.80235 0.97976 - - 0.36 0.38915 0.32027 0.88 0.82240 1.00291 - - 0.38 0.40521 0.34485 0.90 0.84353 1.02443 - - 0.40 0.42117 0.36989 0.92 0.86563 1.04465 - - 0.42 0.43704 0.39531 0.94 0.88970 1.06135 - - 0.44 0.45284 0.42105 0.96 0.91444 1.08208 - - 0.46 0.46858 0.44704 0.98 0.94749 1.07662 - - 0.48 0.48430 0.47329 1.00 1.0000 1.00000 - - 0.50 0.50000 0.49980 - - : []{#_Toc484690441 .anchor}**Table C‑2 Circular section properties as - function of area** - -#### Section Properties of Elliptical Pipes - -[]{#_Toc484695151 .anchor} - - **Code** **Minor Axis **Major Axis ***Afull* ***Rfull* - (in)** (in)** (ft2)** (ft)** - 1 14 23 1.80 0.367 - - 2 19 30 3.30 0.490 - - 3 22 34 4.10 0.546 - - 4 24 38 5.10 0.613 - - 5 27 42 6.30 0.686 - - 6 29 45 7.40 0.736 - - 7 32 49 8.80 0.812 - - 8 34 53 10.20 0.875 - - 9 38 60 12.90 0.969 - - 10 43 68 16.60 1.106 - - 11 48 76 20.50 1.229 - - 12 53 83 24.80 1.352 - - 13 58 91 29.50 1.475 - - 14 63 98 34.60 1.598 - - 15 68 106 40.10 1.721 - - 16 72 113 46.10 1.845 - - 17 77 121 52.40 1.967 - - 18 82 128 59.20 2.091 - - 19 87 136 66.40 2.215 - - 20 92 143 74.00 2.340 - - 21 97 151 82.00 2.461 - - 22 106 166 99.20 2.707 - - 23 116 180 118.60 2.968 - - : **Table D‑1 Standard elliptical pipe sizes** - -Note: The Minor Axis is the maximum width for a vertical ellipse and the -full depth for a horizontal ellipse while the Major Axis is the maximum -width for a horizontal ellipse and the full depth for a vertical -ellipse. - -Source: American Concrete Pipe Association (2011). - -+-----------------+----------------------------------------------------+------+----------------------------------------------------+ -| ***Y/Yfull*** | **Horizontal Ellipse** | | **Vertical Ellipse** | -| +-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| | ***A/Afull*** | ***W/Wmax*** | ***R/Rfull*** | | ***A/Afull*** | ***W/Wmax*** | ***R/Rfull*** | -+================:+================:+===============:+================:+=====:+================:+===============:+================:+ -| 0.00 | 0.000 | 0.0000 | 0.0100 | | 0.000 | 0.0000 | 0.0100 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.04 | 0.015 | 0.3919 | 0.0764 | | 0.010 | 0.3919 | 0.1250 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.08 | 0.040 | 0.5426 | 0.1726 | | 0.040 | 0.5426 | 0.2436 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.12 | 0.650 | 0.6499 | 0.2389 | | 0.070 | 0.6499 | 0.3536 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.16 | 0.950 | 0.7332 | 0.3274 | | 0.100 | 0.7332 | 0.4474 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.20 | 0.130 | 0.8000 | 0.4191 | | 0.140 | 0.8000 | 0.5484 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.24 | 0.165 | 0.8542 | 0.5120 | | 0.185 | 0.8542 | 0.6366 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.28 | 0.205 | 0.8980 | 0.5983 | | 0.230 | 0.8980 | 0.7155 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.32 | 0.250 | 0.9330 | 0.6757 | | 0.280 | 0.9330 | 0.7768 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.36 | 0.300 | 0.9600 | 0.7630 | | 0.330 | 0.9600 | 0.8396 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.40 | 0.355 | 0.9798 | 0.8326 | | 0.380 | 0.9798 | 0.8969 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.44 | 0.415 | 0.9928 | 0.9114 | | 0.430 | 0.9928 | 0.9480 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.48 | 0.480 | 0.9992 | 0.9702 | | 0.480 | 0.9992 | 0.9925 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.52 | 0.520 | 0.9992 | 1.030 | | 0.520 | 0.9992 | 1.023 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.56 | 0.585 | 0.9928 | 1.091 | | 0.570 | 0.9928 | 1.053 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.60 | 0.645 | 0.9798 | 1.146 | | 0.620 | 0.9798 | 1.084 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.64 | 0.700 | 0.9600 | 1.185 | | 0.670 | 0.9600 | 1.107 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.68 | 0.750 | 0.9330 | 1.225 | | 0.720 | 0.9330 | 1.130 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.72 | 0.795 | 0.8980 | 1.257 | | 0.770 | 0.8980 | 1.154 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.76 | 0.835 | 0.8542 | 1.274 | | 0.815 | 0.8542 | 1.170 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.80 | 0.870 | 0.8000 | 1.290 | | 0.860 | 0.8000 | 1.177 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.84 | 0.905 | 0.7332 | 1.282 | | 0.900 | 0.7332 | 1.177 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.88 | 0.935 | 0.6499 | 1.274 | | 0.930 | 0.6499 | 1.170 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.92 | 0.960 | 0.5426 | 1.257 | | 0.960 | 0.5426 | 1.162 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 0.96 | 0.985 | 0.3919 | 1.185 | | 0.990 | 0.3919 | 1.122 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ -| 1.00 | 1.000 | 0.0000 | 1.000 | | 1.000 | 0.0000 | 1.000 | -+-----------------+-----------------+----------------+-----------------+------+-----------------+----------------+-----------------+ - -: []{#_Toc484695152 .anchor}**Table D‑2 Elliptical section properties as -function of depth** - -#### Section Properties of Arch Pipes - -[]{#_Toc484695153 .anchor} - -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| **Code** | **Rise (*Yfull*) (in)** | **Span (*Wmax*) (in)** | ***Afull* | ***Rfull* | -| | | | (in2)** | (in)** | -+===============+===============+===============+===============+===============+===============+===============+===============+ -| **Concrete** | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 1 | 11 | 18 | 1.1 | 0.25 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 2 | 13.5 | 22 | 1.65 | 0.30 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 3 | 15.5 | 26 | 2.2 | 0.36 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 4 | 18 | 28.5 | 2.8 | 0.45 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 5 | 22.5 | 36.25 | 4.4 | 0.56 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 6 | 26.625 | 43.75 | 6.4 | 0.68 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 7 | 31.3125 | 51.125 | 8.8 | 0.80 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 8 | 36 | 58.5 | 11.4 | 0.90 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 9 | 40 | 65 | 14.3 | 1.01 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 10 | 45 | 73 | 17.7 | 1.13 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 11 | 54 | 88 | 25.6 | 1.35 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 12 | 62 | 102 | 34.6 | 1.57 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 13 | 72 | 115 | 44.5 | 1.77 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 14 | 77.5 | 122 | 51.7 | 1.92 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 15 | 87.125 | 138 | 66.0 | 2.17 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 16 | 96.875 | 154 | 81.8 | 2.42 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| 17 | 106.5 | 168.75 | 99.1 | 2.65 | -+-------------------------------+-------------------------------+-------------------------------+---------------+---------------+ -| **Corrugated Steel, 2-2/3 x 1/2\" Corrugation** | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 18 | 13 | 17 | 1.1 | 0.324 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 19 | 15 | 21 | 1.6 | 0.374 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 20 | 18 | 24 | 2.2 | 0.449 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 21 | 20 | 28 | 2.9 | 0.499 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 22 | 24 | 35 | 4.5 | 0.598 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 23 | 29 | 42 | 6.5 | 0.723 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 24 | 33 | 49 | 8.9 | 0.823 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 25 | 38 | 57 | 11.6 | 0.947 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 26 | 43 | 64 | 14.7 | 1.072 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 27 | 47 | 71 | 18.1 | 1.171 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 28 | 52 | 77 | 21.9 | 1.296 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ -| 29 | 57 | 83 | 26.0 | 1.421 | -+---------------+-------------------------------+-------------------------------+-------------------------------+---------------+ - -: **Table E‑1 Standard arch pipe sizes** - -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| **Code** | **Rise | **Span (*Wmax*) | ***Afull* | ***Rfull* | -| | (*Yfull*) | (in)** | (in2)** | (in)** | -| | (in)** | | | | -+===================+===================+===================+===================+===================+ -| **Corrugated Steel, 3 x 1\" Corrugation** | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 30 | 31 | 40 | 7.0 | 0.773 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 31 | 36 | 46 | 9.4 | 0.773 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 32 | 41 | 53 | 12.3 | 1.022 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 33 | 46 | 60 | 15.6 | 1.147 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 34 | 51 | 66 | 19.3 | 1.271 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 35 | 55 | 73 | 23.2 | 1.371 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 36 | 59 | 81 | 27.4 | 1.471 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 37 | 63 | 87 | 32.1 | 1.570 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 38 | 67 | 95 | 37.0 | 1.670 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 39 | 71 | 103 | 42.4 | 1.770 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 40 | 75 | 112 | 48.0 | 1.869 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 41 | 79 | 117 | 54.2 | 1.969 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 42 | 83 | 128 | 60.5 | 2.069 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 43 | 87 | 137 | 67.4 | 2.168 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 44 | 91 | 142 | 74.5 | 2.268 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| **Structural Plate, 18\" Corner Radius** | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 45 | 55 | 73 | 22 | 1.371 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 46 | 57 | 76 | 24 | 1.421 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 47 | 59 | 81 | 26 | 1.471 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 48 | 61 | 84 | 28 | 1.520 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 49 | 63 | 87 | 31 | 1.570 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 50 | 65 | 92 | 33 | 1.620 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 51 | 67 | 95 | 35 | 1.670 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 52 | 69 | 98 | 38 | 1.720 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 53 | 71 | 103 | 40 | 1.770 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 54 | 73 | 106 | 43 | 1.820 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 55 | 75 | 112 | 46 | 1.869 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 56 | 77 | 114 | 49 | 1.919 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 57 | 79 | 117 | 52 | 1.969 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 58 | 81 | 123 | 55 | 2.019 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 59 | 83 | 128 | 58 | 2.069 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 60 | 85 | 131 | 61 | 2.119 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 61 | 87 | 137 | 64 | 2.168 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 62 | 89 | 139 | 67 | 2.218 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 63 | 91 | 142 | 71 | 2.268 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 64 | 93 | 148 | 74 | 2.318 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 65 | 95 | 150 | 78 | 2.368 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 66 | 97 | 152 | 81 | 2.418 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ - -: **Table E‑1 Continued** - -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| **Code** | **Rise | **Span (*Wmax*) | ***Afull* | ***Rfull* | -| | (*Yfull*) | (in)** | (in2)** | (in)** | -| | (in)** | | | | -+===================+===================+===================+===================+===================+ -| **Structural Plate, 18\" Corner Radius** | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 67 | 100 | 154 | 85 | 2.493 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 68 | 101 | 161 | 89 | 2.517 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 69 | 103 | 167 | 93 | 2.567 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 70 | 105 | 169 | 97 | 2.617 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 71 | 107 | 171 | 101 | 2.667 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 72 | 109 | 178 | 105 | 2.717 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 73 | 111 | 184 | 109 | 2.767 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 74 | 113 | 186 | 113 | 2.817 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 75 | 115 | 188 | 118 | 2.866 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 76 | 118 | 190 | 122 | 2.941 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 77 | 119 | 197 | 126 | 2.966 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 78 | 121 | 199 | 131 | 3.016 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| **Structural Plate, 31\" Corner Radius** | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 79 | 112 | 159 | 97 | 2.792 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 80 | 114 | 162 | 102 | 2.841 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 81 | 116 | 168 | 105 | 2.891 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 82 | 118 | 170 | 109 | 2.941 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 83 | 120 | 173 | 114 | 2.991 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 84 | 122 | 179 | 118 | 3.041 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 85 | 124 | 184 | 123 | 3.091 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 86 | 126 | 187 | 127 | 3.141 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 87 | 128 | 190 | 132 | 3.190 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 88 | 130 | 195 | 137 | 3.240 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 89 | 132 | 198 | 142 | 3.290 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 90 | 134 | 204 | 146 | 3.340 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 91 | 136 | 206 | 151 | 3.390 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 92 | 138 | 209 | 157 | 3.440 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 93 | 140 | 215 | 161 | 3.490 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 94 | 142 | 217 | 167 | 3.539 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 95 | 144 | 223 | 172 | 3.589 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 96 | 146 | 225 | 177 | 3.639 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 97 | 148 | 231 | 182 | 3.689 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 98 | 150 | 234 | 188 | 3.739 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 99 | 152 | 236 | 194 | 3.789 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 100 | 154 | 239 | 200 | 3.838 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 101 | 156 | 245 | 205 | 3.888 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ -| 102 | 158 | 247 | 211 | 3.938 | -+-------------------+-------------------+-------------------+-------------------+-------------------+ - -: **Table E‑1 Continued** - -Source: American Iron and Steel Institute (1999). - -[]{#_Toc484695154 .anchor}**Table E‑2 Arch pipe section properties as -function of depth** - - ***Y/Yfull*** ***A/Afull*** ***W/Wmax*** ***R/Rfull*** - 0.00 0.000 0.0000 0.0100 - - 0.04 0.020 0.6272 0.0983 - - 0.08 0.060 0.8521 0.1965 - - 0.12 0.100 0.9243 0.2948 - - 0.16 0.140 0.9645 0.3940 - - 0.20 0.190 0.9846 0.4962 - - 0.24 0.240 0.9964 0.5911 - - 0.28 0.290 0.9988 0.6796 - - 0.32 0.340 0.9917 0.7615 - - 0.36 0.390 0.9811 0.8364 - - 0.40 0.440 0.9680 0.9044 - - 0.44 0.490 0.9515 0.9640 - - 0.48 0.540 0.9314 1.018 - - 0.52 0.590 0.9101 1.065 - - 0.56 0.640 0.8864 1.106 - - 0.60 0.690 0.8592 1.142 - - 0.64 0.735 0.8284 1.170 - - 0.68 0.780 0.7917 1.192 - - 0.72 0.820 0.7527 1.208 - - 0.76 0.860 0.7065 1.217 - - 0.80 0.895 0.6544 1.220 - - 0.84 0.930 0.5953 1.213 - - 0.88 0.960 0.5231 1.196 - - 0.92 0.985 0.4355 1.168 - - 0.96 0.995 0.3195 1.112 - - 1.00 1.000 0.000 1.000 - -#### Section Properties of Masonry Sewers - -[]{#_Toc484695155 .anchor} - -+--------------------+-----------------------------------------------------------+ -| ***Y/Yfull*** | ***A/Afull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.00 | 0.0000 | 0.000 | 0.0000 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.04 | 0.0173 | 0.015 | 0.0181 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.08 | 0.0457 | 0.040 | 0.0508 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.12 | 0.0828 | 0.055 | 0.0908 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.16 | 0.1271 | 0.085 | 0.1326 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.20 | 0.1765 | 0.120 | 0.1757 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.24 | 0.2270 | 0.155 | 0.2201 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.28 | 0.2775 | 0.190 | 0.2655 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.32 | 0.3280 | 0.225 | 0.3118 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.36 | 0.3780 | 0.275 | 0.3587 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.40 | 0.4270 | 0.320 | 0.4064 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.44 | 0.4765 | 0.370 | 0.4542 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.48 | 0.5260 | 0.420 | 0.5023 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.52 | 0.5740 | 0.470 | 0.5506 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.56 | 0.6220 | 0.515 | 0.5987 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.60 | 0.6690 | 0.570 | 0.6462 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.64 | 0.7160 | 0.620 | 0.6931 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.68 | 0.7610 | 0.680 | 0.7387 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.72 | 0.8030 | 0.730 | 0.7829 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.76 | 0.8390 | 0.780 | 0.8253 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.80 | 0.8770 | 0.835 | 0.8652 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.84 | 0.9110 | 0.885 | 0.9022 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.88 | 0.9410 | 0.925 | 0.9356 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.92 | 0.9680 | 0.955 | 0.9645 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.96 | 0.9880 | 0.980 | 0.9873 | -+--------------------+-------------------+-------------------+-------------------+ -| 1.00 | 1.0000 | 1.000 | 1.0000 | -+--------------------+-------------------+-------------------+-------------------+ - -: **Table F‑1 Area of masonry sewers as function of depth** - -+--------------------+-----------------------------------------------------------+ -| ***Y/Yfull*** | ***W/Wmax*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.00 | 0.000 | 0.000 | 0.0000 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.04 | 0.490 | 0.298 | 0.5878 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.08 | 0.667 | 0.433 | 0.8772 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.12 | 0.820 | 0.508 | 0.8900 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.16 | 0.930 | 0.582 | 0.9028 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.20 | 1.000 | 0.642 | 0.9156 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.24 | 1.000 | 0.696 | 0.9284 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.28 | 1.000 | 0.746 | 0.9412 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.32 | 0.997 | 0.791 | 0.9540 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.36 | 0.994 | 0.836 | 0.9668 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.40 | 0.988 | 0.866 | 0.9798 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.44 | 0.982 | 0.896 | 0.9928 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.48 | 0.967 | 0.926 | 0.9992 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.52 | 0.948 | 0.956 | 0.9992 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.56 | 0.928 | 0.970 | 0.9928 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.60 | 0.904 | 0.985 | 0.9798 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.64 | 0.874 | 1.000 | 0.9600 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.68 | 0.842 | 0.985 | 0.9330 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.72 | 0.798 | 0.970 | 0.8980 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.76 | 0.750 | 0.940 | 0.8542 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.80 | 0.697 | 0.896 | 0.8000 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.84 | 0.637 | 0.836 | 0.7332 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.88 | 0.567 | 0.764 | 0.6499 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.92 | 0.467 | 0.642 | 0.5426 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.96 | 0.342 | 0.310 | 0.3919 | -+--------------------+-------------------+-------------------+-------------------+ -| 1.00 | 0.000 | 0.000 | 0.0000 | -+--------------------+-------------------+-------------------+-------------------+ - -: []{#_Toc484695156 .anchor}**Table F‑2 Width of masonry sewers as -function of depth - I** - -+-----------------+-----------------------------------------------------------------------------+ -| ***Y/Yfull*** | ***W/Wmax*** | -| +-----------------+-----------------+---------------------+-------------------+ -| | **Gothic** | **Catenary** | **Semi-Elliptical** | **Semi-Circular** | -+:===============:+:===============:+:===============:+:===================:+:=================:+ -| 0 | 0.000 | 0.0000 | 0.00 | 0.0000 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.05 | 0.286 | 0.6667 | 0.70 | 0.5488 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.10 | 0.643 | 0.8222 | 0.98 | 0.8537 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.15 | 0.762 | 0.9111 | 1.00 | 1.0000 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.20 | 0.833 | 0.9778 | 1.00 | 1.0000 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.25 | 0.905 | 1.0000 | 1.00 | 0.9939 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.30 | 0.952 | 1.0000 | 0.99 | 0.9878 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.35 | 0.976 | 0.9889 | 0.98 | 0.9756 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.40 | 0.976 | 0.9778 | 0.96 | 0.9634 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.45 | 1.000 | 0.9556 | 0.94 | 0.9451 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.50 | 1.000 | 0.9333 | 0.91 | 0.9207 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.55 | 0.976 | 0.8889 | 0.88 | 0.8902 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.60 | 0.976 | 0.8444 | 0.84 | 0.8537 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.65 | 0.952 | 0.8000 | 0.80 | 0.8171 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.70 | 0.905 | 0.7556 | 0.75 | 0.7683 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.75 | 0.833 | 0.7000 | 0.70 | 0.7073 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.80 | 0.762 | 0.6333 | 0.64 | 0.6463 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.85 | 0.667 | 0.5556 | 0.56 | 0.5732 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.90 | 0.524 | 0.4444 | 0.46 | 0.4756 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 0.95 | 0.357 | 0.3333 | 0.34 | 0.3354 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ -| 1.00 | 0.000 | 0.0000 | 0.00 | 0.0000 | -+-----------------+-----------------+-----------------+---------------------+-------------------+ - -: []{#_Toc484695157 .anchor}**Table F‑3 Width of masonry sewers as -function of depth - II** - -+--------------------+-----------------------------------------------------------+ -| ***Y/Yfull*** | ***R/Rfull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.00 | 0.010 | 0.010 | 0.0100 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.04 | 0.0952 | 0.097 | 0.1040 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.08 | 0.189 | 0.216 | 0.2065 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.12 | 0.273 | 0.302 | 0.3243 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.16 | 0.369 | 0.386 | 0.4322 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.20 | 0.463 | 0.465 | 0.5284 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.24 | 0.560 | 0.536 | 0.6147 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.28 | 0.653 | 0.611 | 0.6927 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.32 | 0.743 | 0.676 | 0.7636 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.36 | 0.822 | 0.735 | 0.8268 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.40 | 0.883 | 0.791 | 0.8873 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.44 | 0.949 | 0.854 | 0.9417 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.48 | 0.999 | 0.904 | 0.9905 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.52 | 1.055 | 0.941 | 1.036 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.56 | 1.095 | 1.008 | 1.077 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.60 | 1.141 | 1.045 | 1.113 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.64 | 1.161 | 1.076 | 1.143 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.68 | 1.188 | 1.115 | 1.169 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.72 | 1.206 | 1.146 | 1.189 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.76 | 1.206 | 1.162 | 1.202 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.80 | 1.206 | 1.186 | 1.208 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.84 | 1.205 | 1.193 | 1.206 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.88 | 1.196 | 1.186 | 1.195 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.92 | 1.168 | 1.162 | 1.170 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.96 | 1.127 | 1.107 | 1.126 | -+--------------------+-------------------+-------------------+-------------------+ -| 1.00 | 1.000 | 1.000 | 1.000 | -+--------------------+-------------------+-------------------+-------------------+ - -: []{#_Toc484695158 .anchor}**Table F‑4 Hydraulic radius of masonry -sewers as function of depth** - -+--------------------+-----------------------------------------------------------+ -| ***A/Afull*** | ***Y/Yfull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.00 | 0.00000 | 0.00000 | 0.00000 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.02 | 0.04112 | 0.04912 | 0.04146 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.04 | 0.07380 | 0.08101 | 0.07033 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.06 | 0.10000 | 0.11128 | 0.09098 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.08 | 0.12236 | 0.14161 | 0.10962 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.10 | 0.14141 | 0.16622 | 0.12921 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.12 | 0.15857 | 0.18811 | 0.14813 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.14 | 0.17462 | 0.21356 | 0.16701 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.16 | 0.18946 | 0.23742 | 0.18565 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.18 | 0.20315 | 0.25742 | 0.20401 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.20 | 0.21557 | 0.27742 | 0.22211 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.22 | 0.22833 | 0.29741 | 0.23998 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.24 | 0.24230 | 0.31742 | 0.25769 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.26 | 0.25945 | 0.33742 | 0.27524 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.28 | 0.27936 | 0.35747 | 0.29265 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.30 | 0.30000 | 0.37364 | 0.30990 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.32 | 0.32040 | 0.40000 | 0.32704 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.34 | 0.34034 | 0.41697 | 0.34406 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.36 | 0.35892 | 0.43372 | 0.36101 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.38 | 0.37595 | 0.45000 | 0.37790 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.40 | 0.39214 | 0.46374 | 0.39471 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.42 | 0.40802 | 0.47747 | 0.41147 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.44 | 0.42372 | 0.49209 | 0.42818 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.46 | 0.43894 | 0.50989 | 0.44484 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.48 | 0.45315 | 0.53015 | 0.46147 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.50 | 0.46557 | 0.55000 | 0.47807 | -+--------------------+-------------------+-------------------+-------------------+ - -: []{#_Toc484695159 .anchor}**Table F‑5 Depth of masonry sewers as -function of area - I** - -+--------------------+-----------------------------------------------------------+ -| ***A/Afull*** | ***Y/Yfull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.52 | 0.47833 | 0.56429 | 0.49468 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.54 | 0.49230 | 0.57675 | 0.51134 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.56 | 0.50945 | 0.58834 | 0.52803 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.58 | 0.52936 | 0.60000 | 0.54474 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.60 | 0.55000 | 0.61441 | 0.56138 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.62 | 0.57000 | 0.62967 | 0.57804 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.64 | 0.59000 | 0.64582 | 0.59478 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.66 | 0.61023 | 0.66368 | 0.61171 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.68 | 0.63045 | 0.68209 | 0.62881 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.70 | 0.65000 | 0.70000 | 0.64609 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.72 | 0.66756 | 0.71463 | 0.66350 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.74 | 0.68413 | 0.72807 | 0.68111 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.76 | 0.70000 | 0.74074 | 0.69901 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.78 | 0.71481 | 0.75296 | 0.71722 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.80 | 0.72984 | 0.76500 | 0.73583 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.82 | 0.74579 | 0.77784 | 0.75490 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.84 | 0.76417 | 0.79212 | 0.77447 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.86 | 0.78422 | 0.80945 | 0.79471 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.88 | 0.80477 | 0.82936 | 0.81564 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.90 | 0.82532 | 0.85000 | 0.83759 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.92 | 0.85000 | 0.86731 | 0.86067 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.94 | 0.88277 | 0.88769 | 0.88557 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.96 | 0.91500 | 0.91400 | 0.91159 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.98 | 0.95000 | 0.95000 | 0.94520 | -+--------------------+-------------------+-------------------+-------------------+ -| 1.00 | 1.00000 | 1.00000 | 1.00000 | -+--------------------+-------------------+-------------------+-------------------+ - -: **Table F-5 Continued** - -+-----------------+-----------------------------------------------------------------------------+ -| ***A/Afull*** | ***Y/Yfull*** | -| +-----------------+-----------------+-------------------+---------------------+ -| | **Catenary** | **Gothic** | **Semi-Circular** | **Semi-Elliptical** | -+:===============:+:===============:+:===============:+:=================:+:===================:+ -| 0.00 | 0.00000 | 0.00000 | 0.00000 | 0.00000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.02 | 0.02974 | 0.04522 | 0.04102 | 0.03075 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.04 | 0.06439 | 0.07825 | 0.07407 | 0.05137 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.06 | 0.08433 | 0.10646 | 0.10000 | 0.07032 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.08 | 0.10549 | 0.12645 | 0.11769 | 0.09000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.10 | 0.12064 | 0.14645 | 0.13037 | 0.11323 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.12 | 0.13952 | 0.16787 | 0.14036 | 0.13037 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.14 | 0.15560 | 0.18641 | 0.15000 | 0.14519 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.16 | 0.17032 | 0.20129 | 0.16546 | 0.15968 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.18 | 0.18512 | 0.22425 | 0.18213 | 0.18459 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.20 | 0.20057 | 0.24129 | 0.20000 | 0.19531 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.22 | 0.21995 | 0.25624 | 0.22018 | 0.21354 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.24 | 0.24011 | 0.27344 | 0.24030 | 0.22694 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.26 | 0.25892 | 0.29097 | 0.25788 | 0.23947 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.28 | 0.27595 | 0.30529 | 0.27216 | 0.25296 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.30 | 0.29214 | 0.32607 | 0.28500 | 0.26500 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.32 | 0.30802 | 0.33755 | 0.29704 | 0.27784 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.34 | 0.32372 | 0.35073 | 0.30892 | 0.29212 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.36 | 0.33894 | 0.36447 | 0.32128 | 0.30970 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.38 | 0.35315 | 0.37558 | 0.33476 | 0.32982 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.40 | 0.36557 | 0.40000 | 0.35000 | 0.35000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.42 | 0.37833 | 0.41810 | 0.36927 | 0.36738 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.44 | 0.39230 | 0.43648 | 0.38963 | 0.38390 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.46 | 0.40970 | 0.45374 | 0.41023 | 0.40000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.48 | 0.42982 | 0.46805 | 0.43045 | 0.41667 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.50 | 0.45000 | 0.48195 | 0.45000 | 0.43333 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ - -: []{#_Toc484695160 .anchor}**Table F‑6 Depth of masonry sewers as -function of area - II** - -+-----------------+-----------------------------------------------------------------------------+ -| ***A/Afull*** | ***Y/Yfull*** | -| +-----------------+-----------------+-------------------+---------------------+ -| | **Catenary** | **Gothic** | **Semi-Circular** | **Semi-Elliptical** | -+:===============:+:===============:+:===============:+:=================:+:===================:+ -| 0.52 | 0.46769 | 0.49626 | 0.46769 | 0.45000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.54 | 0.48431 | 0.51352 | 0.48431 | 0.46697 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.56 | 0.50000 | 0.53190 | 0.50000 | 0.48372 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.58 | 0.51466 | 0.55000 | 0.51443 | 0.50000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.60 | 0.52886 | 0.56416 | 0.52851 | 0.51374 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.62 | 0.54292 | 0.57787 | 0.54271 | 0.52747 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.64 | 0.55729 | 0.59224 | 0.55774 | 0.54209 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.66 | 0.57223 | 0.60950 | 0.57388 | 0.55950 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.68 | 0.58780 | 0.62941 | 0.59101 | 0.57941 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.70 | 0.60428 | 0.65000 | 0.60989 | 0.60000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.72 | 0.62197 | 0.67064 | 0.63005 | 0.62000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.74 | 0.64047 | 0.69055 | 0.65000 | 0.64000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.76 | 0.65980 | 0.70721 | 0.66682 | 0.66000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.78 | 0.67976 | 0.72031 | 0.68318 | 0.68000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.80 | 0.70000 | 0.73286 | 0.70000 | 0.70000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.82 | 0.71731 | 0.74632 | 0.71675 | 0.71843 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.84 | 0.73769 | 0.76432 | 0.73744 | 0.73865 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.86 | 0.76651 | 0.78448 | 0.76651 | 0.76365 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.88 | 0.80000 | 0.80421 | 0.80000 | 0.79260 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.90 | 0.82090 | 0.82199 | 0.82090 | 0.82088 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.92 | 0.84311 | 0.84363 | 0.84311 | 0.85000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.94 | 0.87978 | 0.87423 | 0.87978 | 0.88341 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.96 | 0.91576 | 0.90617 | 0.91576 | 0.90998 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.98 | 0.95000 | 0.93827 | 0.95000 | 0.93871 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 1.00 | 1.00000 | 1.00000 | 1.00000 | 1.00000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ - -: **Table F-6 Continued** - -+--------------------+-----------------------------------------------------------+ -| ***A/Afull*** | ***Ψ/Ψfull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.00 | 0.00000 | 0.00000 | 0.00000 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.02 | 0.00758 | 0.00295 | 0.00467 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.04 | 0.01812 | 0.01331 | 0.01237 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.06 | 0.03000 | 0.02629 | 0.02268 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.08 | 0.03966 | 0.04000 | 0.03515 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.10 | 0.04957 | 0.05657 | 0.04943 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.12 | 0.06230 | 0.07500 | 0.06525 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.14 | 0.07849 | 0.09432 | 0.08212 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.16 | 0.09618 | 0.11473 | 0.10005 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.18 | 0.11416 | 0.13657 | 0.11891 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.20 | 0.13094 | 0.15894 | 0.13856 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.22 | 0.14808 | 0.18030 | 0.15896 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.24 | 0.16583 | 0.20036 | 0.18004 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.26 | 0.18381 | 0.22000 | 0.20172 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.28 | 0.20294 | 0.23919 | 0.22397 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.30 | 0.22500 | 0.25896 | 0.24677 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.32 | 0.25470 | 0.28000 | 0.27006 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.34 | 0.28532 | 0.30504 | 0.29380 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.36 | 0.31006 | 0.33082 | 0.31790 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.38 | 0.32804 | 0.35551 | 0.34237 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.40 | 0.34555 | 0.37692 | 0.36720 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.42 | 0.36944 | 0.39809 | 0.39239 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.44 | 0.40032 | 0.42000 | 0.41792 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.46 | 0.43203 | 0.44625 | 0.44374 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.48 | 0.46004 | 0.47321 | 0.46984 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.50 | 0.47849 | 0.50000 | 0.49619 | -+--------------------+-------------------+-------------------+-------------------+ - -: []{#_Toc484695161 .anchor}**Table F‑7 Section factor for masonry -sewers as function of area - I** - -+--------------------+-----------------------------------------------------------+ -| ***A/Afull*** | ***Ψ/Ψfull*** | -| +-------------------+-------------------+-------------------+ -| | **Basket Handle** | **Egg** | **Horseshoe** | -+:==================:+:=================:+:=================:+:=================:+ -| 0.52 | 0.49591 | 0.52255 | 0.52276 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.54 | 0.51454 | 0.54481 | 0.54950 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.56 | 0.53810 | 0.56785 | 0.57640 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.58 | 0.56711 | 0.59466 | 0.60345 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.60 | 0.60000 | 0.62485 | 0.63065 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.62 | 0.64092 | 0.65518 | 0.65795 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.64 | 0.68136 | 0.68181 | 0.68531 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.66 | 0.71259 | 0.70415 | 0.71271 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.68 | 0.73438 | 0.72585 | 0.74009 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.70 | 0.75500 | 0.74819 | 0.76738 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.72 | 0.78625 | 0.77482 | 0.79451 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.74 | 0.81880 | 0.80515 | 0.82144 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.76 | 0.85000 | 0.83534 | 0.84814 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.78 | 0.86790 | 0.86193 | 0.87450 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.80 | 0.88483 | 0.88465 | 0.90057 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.82 | 0.90431 | 0.90690 | 0.92652 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.84 | 0.93690 | 0.93000 | 0.95244 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.86 | 0.97388 | 0.95866 | 0.97724 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.88 | 1.00747 | 0.98673 | 0.99988 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.90 | 1.03300 | 1.01238 | 1.02048 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.92 | 1.05000 | 1.03396 | 1.03989 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.94 | 1.05464 | 1.05000 | 1.05698 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.96 | 1.06078 | 1.06517 | 1.07694 | -+--------------------+-------------------+-------------------+-------------------+ -| 0.98 | 1.05500 | 1.05380 | 1.07562 | -+--------------------+-------------------+-------------------+-------------------+ -| 1.00 | 1.00000 | 1.00000 | 1.00000 | -+--------------------+-------------------+-------------------+-------------------+ - -: **Table F-7 Continued** - -+-----------------+-----------------------------------------------------------------------------+ -| ***A/Afull*** | ***Ψ/Ψfull*** | -| +-----------------+-----------------+-------------------+---------------------+ -| | **Catenary** | **Gothic** | **Semi-Circular** | **Semi-Elliptical** | -+:===============:+:===============:+:===============:+:=================:+:===================:+ -| 0.00 | 0.00000 | 0.00000 | 0.00000 | 0.00000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.02 | 0.00605 | 0.00500 | 0.00757 | 0.00438 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.04 | 0.01455 | 0.01740 | 0.01815 | 0.01227 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.06 | 0.02540 | 0.03098 | 0.03000 | 0.02312 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.08 | 0.03863 | 0.04272 | 0.03580 | 0.03638 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.10 | 0.05430 | 0.05500 | 0.04037 | 0.05145 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.12 | 0.07127 | 0.06980 | 0.04601 | 0.06783 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.14 | 0.08778 | 0.08620 | 0.05500 | 0.08500 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.16 | 0.10372 | 0.10461 | 0.07475 | 0.10093 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.18 | 0.12081 | 0.12463 | 0.09834 | 0.11752 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.20 | 0.14082 | 0.14500 | 0.12500 | 0.13530 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.22 | 0.16375 | 0.16309 | 0.15570 | 0.15626 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.24 | 0.18779 | 0.18118 | 0.18588 | 0.17917 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.26 | 0.21157 | 0.20000 | 0.20883 | 0.20296 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.28 | 0.23478 | 0.22181 | 0.22300 | 0.22654 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.30 | 0.25818 | 0.24487 | 0.23472 | 0.24962 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.32 | 0.28244 | 0.26888 | 0.24667 | 0.27269 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.34 | 0.30741 | 0.29380 | 0.26758 | 0.29568 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.36 | 0.33204 | 0.31901 | 0.29346 | 0.31848 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.38 | 0.35505 | 0.34389 | 0.32124 | 0.34152 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.40 | 0.37465 | 0.36564 | 0.35000 | 0.36500 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.42 | 0.39404 | 0.38612 | 0.37720 | 0.38941 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.44 | 0.41426 | 0.40720 | 0.40540 | 0.41442 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.46 | 0.43804 | 0.43000 | 0.43541 | 0.44000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.48 | 0.46531 | 0.45868 | 0.46722 | 0.46636 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.50 | 0.49357 | 0.48895 | 0.50000 | 0.49309 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ - -: []{#_Toc484695162 .anchor}**Table F‑8 Section factor for masonry -sewers as function of area - II** - -+-----------------+-----------------------------------------------------------------------------+ -| ***A/Afull*** | ***Ψ/Ψfull*** | -| +-----------------+-----------------+-------------------+---------------------+ -| | **Catenary** | **Gothic** | **Semi-Circular** | **Semi-Elliptical** | -+:===============:+:===============:+:===============:+:=================:+:===================:+ -| 0.52 | 0.52187 | 0.52000 | 0.53532 | 0.52000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.54 | 0.54925 | 0.55032 | 0.56935 | 0.54628 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.56 | 0.57647 | 0.58040 | 0.60000 | 0.57285 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.58 | 0.60321 | 0.61000 | 0.61544 | 0.60000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.60 | 0.62964 | 0.63762 | 0.62811 | 0.62949 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.62 | 0.65639 | 0.66505 | 0.64170 | 0.65877 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.64 | 0.68472 | 0.69290 | 0.66598 | 0.68624 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.66 | 0.71425 | 0.72342 | 0.70010 | 0.71017 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.68 | 0.74303 | 0.75467 | 0.73413 | 0.73304 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.70 | 0.76827 | 0.78500 | 0.76068 | 0.75578 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.72 | 0.79168 | 0.81165 | 0.78027 | 0.77925 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.74 | 0.81500 | 0.83654 | 0.80000 | 0.80368 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.76 | 0.84094 | 0.86000 | 0.82891 | 0.83114 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.78 | 0.86707 | 0.88253 | 0.85964 | 0.85950 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.80 | 0.89213 | 0.90414 | 0.89000 | 0.88592 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.82 | 0.91607 | 0.92500 | 0.91270 | 0.90848 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.84 | 0.94000 | 0.94486 | 0.93664 | 0.93000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.86 | 0.96604 | 0.96475 | 0.96677 | 0.95292 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.88 | 0.99000 | 0.98567 | 1.00000 | 0.97481 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.90 | 1.00714 | 1.00833 | 1.02661 | 0.99374 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.92 | 1.02158 | 1.03000 | 1.04631 | 1.01084 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.94 | 1.03814 | 1.05360 | 1.05726 | 1.02858 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.96 | 1.05000 | 1.06500 | 1.06637 | 1.04543 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 0.98 | 1.05000 | 1.05500 | 1.06000 | 1.05000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ -| 1.00 | 1.00000 | 1.00000 | 1.00000 | 1.00000 | -+-----------------+-----------------+-----------------+-------------------+---------------------+ - -: **Table F-8 Continued** - -#### Manning's Roughness Coefficients - -[]{#_Toc484695163 .anchor} - -+------------------------------------------+--------------------+--------------------+--------------------+ -| **Type of Channel and Description** | **Minimum** | **Normal** | **Maximum** | -+:=========================================+:===================+:===================+:===================+ -| | -+---------------------------------------------------------------------------------------------------------+ -| **1. Natural streams - minor streams (top width at flood stage \< 100 ft) ** | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   a. clean, straight, full stage, no | 0.025 | 0.030 | 0.033 | -| > rifts or deep pools | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   b. same as above, but more stones | 0.030 | 0.035 | 0.040 | -| > and weeds | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   c. clean, winding, some pools and | 0.033 | 0.040 | 0.045 | -| > shoals | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   d. same as above, but some weeds and | 0.035 | 0.045 | 0.050 | -| > stones | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   e. same as above, lower stages, more | 0.040 | 0.048 | 0.055 | -| > ineffective\ | | | | -| >   slopes and sections | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   f. same as \"d\" with more stones | 0.045 | 0.050 | 0.060 | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   g. sluggish reaches, weedy, deep | 0.050 | 0.070 | 0.080 | -| > pools | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   h. very weedy reaches, deep pools, | 0.075 | 0.100 | 0.150 | -| > or floodways\ | | | | -| >   with heavy stand of timber and | | | | -| > underbrush | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| **2. Mountain streams, no vegetation in channel, banks usually steep, trees and brush along banks | -| submerged at high stages** | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   a. bottom: gravels, cobbles, and few | 0.030 | 0.040 | 0.050 | -| > boulders | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   b. bottom: cobbles with large | 0.040 | 0.050 | 0.070 | -| > boulders | | | | -+------------------------------------------+--------------------+--------------------+--------------------+ -| **3. Floodplains** |   |   |   | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >   a. Pasture, no brush |   |   |   | -+------------------------------------------+--------------------+--------------------+--------------------+ -| > 1.short grass | 0.025 | 0.030 | 0.035 | -+------------------------------------------+--------------------+--------------------+--------------------+ -| > 2\. high grass | 0.030 | 0.035 | 0.050 | -+------------------------------------------+--------------------+--------------------+--------------------+ -| >    b. Cultivated areas |   |   |   | -+------------------------------------------+--------------------+--------------------+--------------------+ -| > 1. no crop | 0.020 | 0.030 | 0.040 | -+------------------------------------------+--------------------+--------------------+--------------------+ -| > 2\. mature row crops | 0.025 | 0.035 | 0.045 | -+------------------------------------------+--------------------+--------------------+--------------------+ -| > 3\. mature field crops | 0.030 | 0.040 | 0.050 | -+------------------------------------------+--------------------+--------------------+--------------------+ - -: **Table G‑1 Manning's roughness coefficient n for open channels** - -+------------------------------------------+-------------+------------+-------------+ -| **Type of Channel and Description** | **Minimum** | **Normal** | **Maximum** | -+:=========================================+:===========:+:==========:+:===========:+ -| | | | | -+------------------------------------------+-------------+------------+-------------+ -| **3. Floodplains** |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| >     c. Brush |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. scattered brush, heavy weeds | 0.035 | 0.050 | 0.070 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. light brush and trees, in winter | 0.035 | 0.050 | 0.060 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. light brush and trees, in summer | 0.040 | 0.060 | 0.080 | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. medium to dense brush, in winter | 0.045 | 0.070 | 0.110 | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. medium to dense brush, in summer | 0.070 | 0.100 | 0.160 | -+------------------------------------------+-------------+------------+-------------+ -| >     d. Trees |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. dense willows, summer, straight | 0.110 | 0.150 | 0.200 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. cleared land with tree stumps, no | 0.030 | 0.040 | 0.050 | -| > sprouts | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. same as above, but with heavy | 0.050 | 0.060 | 0.080 | -| > growth of sprouts | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. heavy stand of timber, a few down | 0.080 | 0.100 | 0.120 | -| > trees, little\ | | | | -| >   undergrowth, flood stage below | | | | -| > branches | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. same as 4. with flood stage | 0.100 | 0.120 | 0.160 | -| > reaching  branches | | | | -+------------------------------------------+-------------+------------+-------------+ -| **4. Excavated or Dredged Channels** |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > a\. Earth, straight, and uniform |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. clean, recently completed | 0.016 | 0.018 | 0.020 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. clean, after weathering | 0.018 | 0.022 | 0.025 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. gravel, uniform section, clean | 0.022 | 0.025 | 0.030 | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. with short grass, few weeds | 0.022 | 0.027 | 0.033 | -+------------------------------------------+-------------+------------+-------------+ -| > b\. Earth winding and sluggish |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\.  no vegetation | 0.023 | 0.025 | 0.030 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. grass, some weeds | 0.025 | 0.030 | 0.033 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. dense weeds or aquatic plants in | 0.030 | 0.035 | 0.040 | -| > deep channels | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. earth bottom and rubble sides | 0.028 | 0.030 | 0.035 | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. stony bottom and weedy banks | 0.025 | 0.035 | 0.040 | -+------------------------------------------+-------------+------------+-------------+ -| > 6\. cobble bottom and clean sides | 0.030 | 0.040 | 0.050 | -+------------------------------------------+-------------+------------+-------------+ -| > c\. Dragline-excavated or dredged |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1.  no vegetation | 0.025 | 0.028 | 0.033 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. light brush on banks | 0.035 | 0.050 | 0.060 | -+------------------------------------------+-------------+------------+-------------+ - -: **Table G-1 Continued** - -+------------------------------------------+-------------+------------+-------------+ -| **Type of Channel and Description** | **Minimum** | **Normal** | **Maximum** | -+:=========================================+:===========:+:==========:+:===========:+ -| | | | | -+------------------------------------------+-------------+------------+-------------+ -| > d\. Rock cuts |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1. smooth and uniform | 0.025 | 0.035 | 0.040 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. jagged and irregular | 0.035 | 0.040 | 0.050 | -+------------------------------------------+-------------+------------+-------------+ -| > e\. Channels not maintained, weeds and |   |   |   | -| > brush uncut | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. dense weeds, high as flow depth | 0.050 | 0.080 | 0.120 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. clean bottom, brush on sides | 0.040 | 0.050 | 0.080 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. same as above, highest stage of | 0.045 | 0.070 | 0.110 | -| > flow | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. dense brush, high stage | 0.080 | 0.100 | 0.140 | -+------------------------------------------+-------------+------------+-------------+ -| **5. Lined or Constructed Channels** |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > a\. Cement |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\.  neat surface | 0.010 | 0.011 | 0.013 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. mortar | 0.011 | 0.013 | 0.015 | -+------------------------------------------+-------------+------------+-------------+ -| > b\. Wood |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1. planed, untreated | 0.010 | 0.012 | 0.014 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\.  planed, creosoted | 0.011 | 0.012 | 0.015 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. unplaned | 0.011 | 0.013 | 0.015 | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. plank with battens | 0.012 | 0.015 | 0.018 | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. lined with roofing paper | 0.010 | 0.014 | 0.017 | -+------------------------------------------+-------------+------------+-------------+ -| > c\. Concrete |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. trowel finish | 0.011 | 0.013 | 0.015 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. float finish | 0.013 | 0.015 | 0.016 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. finished, with gravel on bottom | 0.015 | 0.017 | 0.020 | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. unfinished | 0.014 | 0.017 | 0.020 | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. gunite, good section | 0.016 | 0.019 | 0.023 | -+------------------------------------------+-------------+------------+-------------+ -| > 6\. gunite, wavy section | 0.018 | 0.022 | 0.025 | -+------------------------------------------+-------------+------------+-------------+ -| > 7\. on good excavated rock | 0.017 | 0.020 |   | -+------------------------------------------+-------------+------------+-------------+ -| > 8\. on irregular excavated rock | 0.022 | 0.027 |   | -+------------------------------------------+-------------+------------+-------------+ - -: **Table G-1 Continued** - -+------------------------------------------+-------------+------------+-------------+ -| **Type of Channel and Description** | **Minimum** | **Normal** | **Maximum** | -+:=========================================+:===========:+:==========:+:===========:+ -| | | | | -+------------------------------------------+-------------+------------+-------------+ -| > d\. Concrete bottom float finish with |   |   |   | -| > sides of: | | | | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. dressed stone in mortar | 0.015 | 0.017 | 0.020 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. random stone in mortar | 0.017 | 0.020 | 0.024 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. cement rubble masonry, plastered | 0.016 | 0.020 | 0.024 | -+------------------------------------------+-------------+------------+-------------+ -| > 4\. cement rubble masonry | 0.020 | 0.025 | 0.030 | -+------------------------------------------+-------------+------------+-------------+ -| > 5\. dry rubble or riprap | 0.020 | 0.030 | 0.035 | -+------------------------------------------+-------------+------------+-------------+ -| > e\. Gravel bottom with sides of: |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. formed concrete | 0.017 | 0.020 | 0.025 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. random stone mortar | 0.020 | 0.023 | 0.026 | -+------------------------------------------+-------------+------------+-------------+ -| > 3\. dry rubble or riprap | 0.023 | 0.033 | 0.036 | -+------------------------------------------+-------------+------------+-------------+ -| > f\. Brick |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. glazed | 0.011 | 0.013 | 0.015 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. in cement mortar | 0.012 | 0.015 | 0.018 | -+------------------------------------------+-------------+------------+-------------+ -| > g\. Masonry |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. cemented rubble | 0.017 | 0.025 | 0.030 | -+------------------------------------------+-------------+------------+-------------+ -| > 2\. dry rubble | 0.023 | 0.032 | 0.035 | -+------------------------------------------+-------------+------------+-------------+ -| > h\. Dressed ashlar/stone paving | 0.013 | 0.015 | 0.017 | -+------------------------------------------+-------------+------------+-------------+ -| > i\. Asphalt |   |   |   | -+------------------------------------------+-------------+------------+-------------+ -| > 1\. smooth | 0.013 | 0.013 |   | -+------------------------------------------+-------------+------------+-------------+ -| 2\. rough | 0.016 | 0.016 |   | -+------------------------------------------+-------------+------------+-------------+ -| > j\. Vegetal lining | 0.030 |   | 0.500 | -+------------------------------------------+-------------+------------+-------------+ - -: **Table G-1 Continued** - -Source: Chow, 1959. - ->   - -  - -+--------------------------------------+-------------+------------+-------------+ -| > **Type of Conduit and | **Minimum** | **Normal** | **Maximum** | -| > Description** | | | | -+======================================+:===========:+:==========:+:===========:+ -| > **1. Brass, smooth:** | 0.009 | 0.010 | 0.013 | -+--------------------------------------+-------------+------------+-------------+ -| > **2. Steel:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Lockbar and welded | 0.010 | 0.012 | 0.014 | -+--------------------------------------+-------------+------------+-------------+ -| > Riveted and spiral | 0.013 | 0.016 | 0.017 | -+--------------------------------------+-------------+------------+-------------+ -| > **3. Cast Iron:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Coated | 0.010 | 0.013 | 0.014 | -+--------------------------------------+-------------+------------+-------------+ -| > Uncoated | 0.011 | 0.014 | 0.016 | -+--------------------------------------+-------------+------------+-------------+ -| > **4. Wrought Iron:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Black | 0.012 | 0.014 | 0.015 | -+--------------------------------------+-------------+------------+-------------+ -| > Galvanized | 0.013 | 0.016 | 0.017 | -+--------------------------------------+-------------+------------+-------------+ -| > **5. Corrugated Metal:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Subdrain | 0.017 | 0.019 | 0.021 | -+--------------------------------------+-------------+------------+-------------+ -| > Stormdrain | 0.021 | 0.024 | 0.030 | -+--------------------------------------+-------------+------------+-------------+ -| > **6. Cement:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Neat Surface | 0.010 | 0.011 | 0.013 | -+--------------------------------------+-------------+------------+-------------+ -| > Mortar | 0.011 | 0.013 | 0.015 | -+--------------------------------------+-------------+------------+-------------+ -| > **7. Concrete:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Culvert, straight and free of | 0.010 | 0.011 | 0.013 | -| > debris | | | | -+--------------------------------------+-------------+------------+-------------+ -| > Culvert with bends, connections, | 0.011 | 0.013 | 0.014 | -| > and some debris | | | | -+--------------------------------------+-------------+------------+-------------+ -| > Finished | 0.011 | 0.012 | 0.014 | -+--------------------------------------+-------------+------------+-------------+ -| > Sewer with manholes, inlet, etc., | 0.013 | 0.015 | 0.017 | -| > straight | | | | -+--------------------------------------+-------------+------------+-------------+ -| > Unfinished, steel form | 0.012 | 0.013 | 0.014 | -+--------------------------------------+-------------+------------+-------------+ -| > Unfinished, smooth wood form | 0.012 | 0.014 | 0.016 | -+--------------------------------------+-------------+------------+-------------+ -| > Unfinished, rough wood form | 0.015 | 0.017 | 0.020 | -+--------------------------------------+-------------+------------+-------------+ -| > **8. Wood:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Stave | 0.010 | 0.012 | 0.014 | -+--------------------------------------+-------------+------------+-------------+ -| > Laminated, treated | 0.015 | 0.017 | 0.020 | -+--------------------------------------+-------------+------------+-------------+ - -: []{#_Toc484695164 .anchor}**Table G‑2 Manning's roughness coefficient -n for closed conduits** - ->   -> ->   - -+--------------------------------------+-------------+------------+-------------+ -| > **Type of Conduit and | **Minimum** | **Normal** | **Maximum** | -| > Description** | | | | -+======================================+:===========:+:==========:+:===========:+ -| > **9. Clay:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Common drainage tile | 0.011 | 0.013 | 0.017 | -+--------------------------------------+-------------+------------+-------------+ -| > Vitrified sewer | 0.011 | 0.014 | 0.017 | -+--------------------------------------+-------------+------------+-------------+ -| > Vitrified sewer with manholes, | 0.013 | 0.015 | 0.017 | -| > inlet, etc. | | | | -+--------------------------------------+-------------+------------+-------------+ -| > Vitrified subdrain with open joint | 0.014 | 0.016 | 0.018 | -+--------------------------------------+-------------+------------+-------------+ -| > **10. Brickwork:** |   |   |   | -+--------------------------------------+-------------+------------+-------------+ -| > Glazed | 0.011 | 0.013 | 0.015 | -+--------------------------------------+-------------+------------+-------------+ -| > Lined with cement mortar | 0.012 | 0.015 | 0.017 | -+--------------------------------------+-------------+------------+-------------+ -| > Sanitary sewers coated with sewage | 0.012 | 0.013 | 0.016 | -| > slime with bends and connections | | | | -+--------------------------------------+-------------+------------+-------------+ -| > Paved invert, sewer, smooth bottom | 0.016 | 0.019 | 0.020 | -+--------------------------------------+-------------+------------+-------------+ -| > Rubble masonry, cemented | 0.018 | 0.025 | 0.030 | -+--------------------------------------+-------------+------------+-------------+ - -: **Table G-2 Continued** - -Source: Chow, 1959. - -+-------------------------------------------------------+--------------+ -|   **Type of Pipe, Diameter and Corrugation | **n** | -| Dimension** | | -+=======================================================+:============:+ -| **  1. Annular 2.67 x 1/2 inch (all diameters)** | 0.024 | -+-------------------------------------------------------+--------------+ -| **  2. Helical 1.50 x 1/4 inch** |   | -+-------------------------------------------------------+--------------+ -| > 8\" diameter | 0.012 | -+-------------------------------------------------------+--------------+ -| > 10\" diameter | 0.014 | -+-------------------------------------------------------+--------------+ -| **  3. Helical 2.67 x 1/2 inch** |   | -+-------------------------------------------------------+--------------+ -| > 12\" diameter | 0.011 | -+-------------------------------------------------------+--------------+ -| > 18\" diameter | 0.014 | -+-------------------------------------------------------+--------------+ -| > 24\" diameter | 0.016 | -+-------------------------------------------------------+--------------+ -| > 36\" diameter | 0.019 | -+-------------------------------------------------------+--------------+ -| > 48\" diameter | 0.020 | -+-------------------------------------------------------+--------------+ -| > 60\" diameter | 0.021 | -+-------------------------------------------------------+--------------+ -| **  4. Annular 3x1 inch (all diameters)** | 0.027 | -+-------------------------------------------------------+--------------+ -| **  5. Helical 3x1 inch** |   | -+-------------------------------------------------------+--------------+ -| > 48\" diameter | 0.023 | -+-------------------------------------------------------+--------------+ -| > 54\" diameter | 0.023 | -+-------------------------------------------------------+--------------+ -| > 60\" diameter | 0.024 | -+-------------------------------------------------------+--------------+ -| > 66\" diameter | 0.025 | -+-------------------------------------------------------+--------------+ -| > 72\" diameter | 0.026 | -+-------------------------------------------------------+--------------+ -| > 78\" diameter and larger | 0.027 | -+-------------------------------------------------------+--------------+ -| **  6. Corrugations 6x2 inches** |   | -+-------------------------------------------------------+--------------+ -| > 60\" diameter | 0.033 | -+-------------------------------------------------------+--------------+ -| > 72\" diameter | 0.032 | -+-------------------------------------------------------+--------------+ -| > 120\" diameter | 0.030 | -+-------------------------------------------------------+--------------+ -| > 180\" diameter | 0.028 | -+-------------------------------------------------------+--------------+ - -: []{#_Toc484695165 .anchor}**Table G‑3 Manning's roughness coefficient -n for corrugated steel pipe** - - Source: American Iron and Steel Institute, 1999. - -  - -#### Culvert Coefficients - -[]{#_Toc484695166 .anchor} - -+----------------------------+---------------------------------+----------+ -| **Culvert Shape and | **Inlet Configuration** | **Code** | -| Material** | | | -+:===========================+:================================+:========:+ -| Circular Concrete | Square edge with headwall | 1 | -| +---------------------------------+----------+ -| | Groove end with headwall | 2 | -| +---------------------------------+----------+ -| | Groove end projecting | 3 | -+----------------------------+---------------------------------+----------+ -| Circular Corrugated Metal | Headwall | 4 | -| Pipe | | | -| +---------------------------------+----------+ -| | Mitered to slope | 5 | -| +---------------------------------+----------+ -| | Projecting | 6 | -+----------------------------+---------------------------------+----------+ -| Circular Pipe, Beveled | 45 deg. bevels | 7 | -| Ring Entrance | | | -| +---------------------------------+----------+ -| | 33.7 deg. bevels | 8 | -+----------------------------+---------------------------------+----------+ -| Rectangular Box; Flared | 30-75 deg. wingwall flares | 9 | -| Wingwalls | | | -| +---------------------------------+----------+ -| | 90 or 15 deg. wingwall flares | 10 | -| +---------------------------------+----------+ -| | 0 deg. wingwall flares | 11 | -| | (straight sides) | | -+----------------------------+---------------------------------+----------+ -| Rectangular Box;Flared | 45 deg flare; 0.43D top edge | 12 | -| Wingwalls and Top Edge | bevel | | -| Bevel | | | -| +---------------------------------+----------+ -| | 18-33.7 deg. flare; 0.083D top | 13 | -| | edge bevel | | -+----------------------------+---------------------------------+----------+ -| Rectangular Box, 90-deg | Chamfered 3/4-in. | 14 | -| Headwall, Chamfered / | | | -| Beveled Inlet Edges | | | -| +---------------------------------+----------+ -| | Beveled 1/2-in/ft at 45 deg | 15 | -| | (1:1) | | -| +---------------------------------+----------+ -| | Beveled 1-in/ft at 33.7 deg | 16 | -| | (1:1.5) | | -+----------------------------+---------------------------------+----------+ -| Rectangular Box, Skewed | 3/4\" chamfered edge, 45 deg | 17 | -| Headwall, Chamfered / | skewed headwall | | -| Beveled Inlet Edges | | | -| +---------------------------------+----------+ -| | 3/4\" chamfered edge, 30 deg | 18 | -| | skewed headwall | | -| +---------------------------------+----------+ -| | 3/4\" chamfered edge, 15 deg | 19 | -| | skewed headwall | | -| +---------------------------------+----------+ -| | 45 deg beveled edge, 10-45 deg | 20 | -| | skewed headwall | | -+----------------------------+---------------------------------+----------+ -| Rectangular Box, | 45 deg (1:1) wingwall flare | 21 | -| Non-offset Flared | | | -| Wingwalls, 3/4\" Chamfer | | | -| at Top of Inlet | | | -| +---------------------------------+----------+ -| | 8.4 deg (3:1) wingwall flare | 22 | -| +---------------------------------+----------+ -| | 18.4 deg (3:1) wingwall flare, | 23 | -| | 30 deg inlet skew | | -+----------------------------+---------------------------------+----------+ - -: **Table H‑1 Culvert codes** - -+----------------------------+---------------------------------+----------+ -| **Culvert Shape and | **Inlet Configuration** | **Code** | -| Material** | | | -+:===========================+:================================+:========:+ -| Rectangular Box, Offset | 45 deg (1:1) flare, 0.042D top | 24 | -| Flared Wingwalls, Beveled | edge bevel | | -| Edge at Inlet Top | | | -| +---------------------------------+----------+ -| | 33.7 deg (1.5:1) flare, 0.083D | 25 | -| | top edge bevel | | -| +---------------------------------+----------+ -| | 18.4 deg (3:1) flare, 0.083D | 26 | -| | top edge bevel | | -+----------------------------+---------------------------------+----------+ -| Corrugated Metal Box | 90 deg headwall | 27 | -| +---------------------------------+----------+ -| | Thick wall projecting | 28 | -| +---------------------------------+----------+ -| | Thin wall projecting | 29 | -+----------------------------+---------------------------------+----------+ -| Horizontal Ellipse | Square edge with headwall | 30 | -| Concrete | | | -| +---------------------------------+----------+ -| | Grooved end with headwall | 31 | -| +---------------------------------+----------+ -| | Grooved end projecting | 32 | -+----------------------------+---------------------------------+----------+ -| Vertical Ellipse Concrete | Square edge with headwall | 33 | -| +---------------------------------+----------+ -| | Grooved end with headwall | 34 | -| +---------------------------------+----------+ -| | Grooved end projecting | 35 | -+----------------------------+---------------------------------+----------+ -| Pipe Arch, 18\" Corner | 90 deg headwall | 36 | -| Radius, Corrugated Metal | | | -| +---------------------------------+----------+ -| | Mitered to slope | 37 | -| +---------------------------------+----------+ -| | Projecting | 38 | -+----------------------------+---------------------------------+----------+ -| Pipe Arch, 18\" Corner | Projecting | 39 | -| Radius, Corrugated Metal | | | -| +---------------------------------+----------+ -| | No bevels | 40 | -| +---------------------------------+----------+ -| | 33.7 deg bevels | 41 | -+----------------------------+---------------------------------+----------+ -| Pipe Arch, 31\" Corner | Projecting | 42 | -| Radius,Corrugated Metal | | | -| +---------------------------------+----------+ -| | No bevels | 43 | -| +---------------------------------+----------+ -| | 33.7 deg. bevels | 44 | -+----------------------------+---------------------------------+----------+ -| Arch, Corrugated Metal | 90 deg headwall | 45 | -| +---------------------------------+----------+ -| | Mitered to slope | 46 | -| +---------------------------------+----------+ -| | Thin wall projecting | 47 | -+----------------------------+---------------------------------+----------+ -| Circular Culvert | Smooth tapered inlet throat | 48 | -| +---------------------------------+----------+ -| | Rough tapered inlet throat | 49 | -+----------------------------+---------------------------------+----------+ - -: **Table H-1 Continued** - -**\ -Table H-1 Continued** - -+----------------------------+---------------------------------+----------+ -| **Culvert Shape and | **Inlet Configuration** | **Code** | -| Material** | | | -+:===========================+:================================+:========:+ -| Elliptical Inlet Face | Tapered inlet, beveled edges | 50 | -| +---------------------------------+----------+ -| | Tapered inlet, square edges | 51 | -| +---------------------------------+----------+ -| | Tapered inlet, thin edge | 52 | -| | projecting | | -+----------------------------+---------------------------------+----------+ -| Rectangular | Tapered inlet throat | 53 | -+----------------------------+---------------------------------+----------+ -| Rectangular Concrete | Side tapered, less favorable | 54 | -| | edges | | -| +---------------------------------+----------+ -| | Side tapered, more favorable | 55 | -| | edges | | -| +---------------------------------+----------+ -| | Slope tapered, less favorable | 56 | -| | edges | | -| +---------------------------------+----------+ -| | Slope tapered, more favorable | 57 | -| | edges | | -+----------------------------+---------------------------------+----------+ - -+----------+----------+-------------+-------------+-----------+-----------+ -| Culvert | Equation | Unsubmerged | Unsubmerged | Submerged | Submerged | -| | | | | | | -| Code | Form | K | M | c | y | -+:=========+:========:+:===========:+:===========:+:=========:+:=========:+ -| 1 | 1 | 0.0098 | 2.00 | 0.0398 | 0.67 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 2 | 1 | 0.0018 | 2.00 | 0.0292 | 0.74 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 3 | 1 | 0.0045 | 2.00 | 0.0317 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 4 | 1 | 0.0078 | 2.00 | 0.0379 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 5 | 1 | 0.0210 | 1.33 | 0.0463 | 0.75 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 6 | 1 | 0.0340 | 1.50 | 0.0553 | 0.54 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 7 | 1 | 0.0018 | 2.50 | 0.0300 | 0.74 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 8 | 1 | 0.0018 | 2.50 | 0.0243 | 0.83 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 9 | 1 | 0.026 | 1.0 | 0.0347 | 0.81 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 10 | 1 | 0.061 | 0.75 | 0.0400 | 0.80 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 11 | 1 | 0.061 | 0.75 | 0.0423 | 0.82 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 12 | 2 | 0.510 | 0.667 | 0.0309 | 0.80 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 13 | 2 | 0.486 | 0.667 | 0.0249 | 0.83 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 14 | 2 | 0.515 | 0.667 | 0.0375 | 0.79 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 15 | 2 | 0.495 | 0.667 | 0.0314 | 0.82 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 16 | 2 | 0.486 | 0.667 | 0.0252 | 0.865 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 17 | 2 | 0.545 | 0.667 | 0.04505 | 0.73 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 18 | 2 | 0.533 | 0.667 | 0.0425 | 0.705 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 19 | 2 | 0.522 | 0.667 | 0.0402 | 0.68 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 20 | 2 | 0.498 | 0.667 | 0.0327 | 0.75 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 21 | 2 | 0.497 | 0.667 | 0.0339 | 0.803 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 22 | 2 | 0.493 | 0.667 | 0.0361 | 0.806 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 23 | 2 | 0.495 | 0.667 | 0.0386 | 0.71 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 24 | 2 | 0.497 | 0.667 | 0.0302 | 0.835 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 25 | 2 | 0.495 | 0.667 | 0.0252 | 0.881 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 26 | 2 | 0.493 | 0.667 | 0.0227 | 0.887 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 27 | 1 | 0.0083 | 2.00 | 0.0379 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 28 | 1 | 0.0145 | 1.75 | 0.0419 | 0.64 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 29 | 1 | 0.0340 | 1.50 | 0.0496 | 0.57 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 30 | 1 | 0.0100 | 2.00 | 0.0398 | 0.67 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 31 | 1 | 0.0018 | 2.50 | 0.0292 | 0.74 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 32 | 1 | 0.0045 | 2.00 | 0.0317 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ - -: []{#_Toc484695167 .anchor}**Table H‑2 Culvert coefficients** - -+----------+----------+-------------+-------------+-----------+-----------+ -| Culvert | Equation | Unsubmerged | Unsubmerged | Submerged | Submerged | -| | | | | | | -| Code | Form | K | M | c | y | -+:=========+:========:+:===========:+:===========:+:=========:+:=========:+ -| 33 | 1 | 0.0100 | 2.00 | 0.0398 | 0.67 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 34 | 1 | 0.0018 | 2.50 | 0.0292 | 0.74 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 35 | 1 | 0.0095 | 2.00 | 0.0317 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 36 | 1 | 0.0083 | 2.00 | 0.0379 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 37 | 1 | 0.0300 | 1.00 | 0.0463 | 0.75 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 38 | 1 | 0.0340 | 1.50 | 0.0496 | 0.57 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 39 | 1 | 0.0300 | 1.50 | 0.0496 | 0.57 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 40 | 1 | 0.0088 | 2.00 | 0.0368 | 0.68 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 41 | 1 | 0.0030 | 2.00 | 0.0269 | 0.77 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 42 | 1 | 0.0300 | 1.50 | 0.0496 | 0.57 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 43 | 1 | 0.0088 | 2.00 | 0.0368 | 0.68 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 44 | 1 | 0.0030 | 2.00 | 0.0269 | 0.77 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 45 | 1 | 0.0083 | 2.00 | 0.0379 | 0.69 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 46 | 1 | 0.0300 | 1.00 | 0.0473 | 0.75 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 47 | 1 | 0.0340 | 1.50 | 0.0496 | 0.57 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 48 | 2 | 0.534 | 0.555 | 0.0196 | 0.90 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 49 | 2 | 0.519 | 0.640 | 0.0210 | 0.90 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 50 | 2 | 0.536 | 0.622 | 0.0368 | 0.83 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 51 | 2 | 0.5035 | 0.719 | 0.0478 | 0.80 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 52 | 2 | 0.547 | 0.800 | 0.0598 | 0.75 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 53 | 2 | 0.475 | 0.667 | 0.0179 | 0.97 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 54 | 2 | 0.560 | 0.667 | 0.0446 | 0.85 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 55 | 2 | 0.560 | 0.667 | 0.0378 | 0.87 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 56 | 2 | 0.500 | 0.667 | 0.0446 | 0.65 | -+----------+----------+-------------+-------------+-----------+-----------+ -| 57 | 2 | 0.500 | 0.667 | 0.0378 | 0.71 | -+----------+----------+-------------+-------------+-----------+-----------+ - -: **Table H-2 Continued** - -# References - -\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ - -American Concrete Pipe Association, *Concrete Pipe Design Manual*, -American Concrete Pipe Association, , -2011. - -American Iron and Steel Institute, *Modern Sewer Design*, American Iron -and Steel Institute, 1999. - -Armco, *Handbook of Drainage and Construction Products*, Armco Drainage -& Metal Products, Inc. 1978. (Out of print; see -[http://www.hydrogate.com/sites/hydrogate.com/files/Flap Gates -Brochure.pdf](http://www.hydrogate.com/sites/hydrogate.com/files/Flap%20Gates%20Brochure.pdf) -instead.) - -Ascher, U.M. and Petzold, L.R., *Computer Methods for Ordinary -Differential Equations and Differential-Algebraic Equations*, SIAM, -Philadelphia, 1998. - -Atkinson, K.E., *An Introduction to Numerical Analysis* (2nd ed.), John -Wiley & Sons, New York 1989. - -Bhave, P.R., *Analysis of Flow in Water Distribution Networks*, -Technomic Publishing, Lancaster, PA, 1991. - -Brater, E.F. and King, H.W., *Handbook of Hydraulics*, (6th edition), -McGraw Hill Book Company, New York, NY, 1976. - -Brater, E.F., King, H.W., Lindel, J.E., and Wei, C.Y., *Handbook of -Hydraulics* (7th edition), McGraw-Hill, New York, NY, 1996. - -Brunner,G.W., "Combined 1D and 2D Modeling with HEC-RAS". U.S. Army -Corps of Engineers Hydrologic Engineering Center, October, 2014. - - - -Bureau of Reclamation, *Water Measurement Manual*, U.S. Department of -the Interior, Washington, DC, 2001. - -Chow, V.T., *Open-Channel Hydraulics*, McGraw-Hill, NY, 1959. - -Clark, J.W., Viessman, W. Jr., Hammer, M.J., *Water Supply and Pollution -Control*, (Third Edition), IEP, New York, NY, 1977. - -Cormen, T.H., Leiserson, C.E., Rivest, R.L. and Stein, C. *Introduction -to Algorithms* (3rd edition), MIT Press and McGraw-Hill, 2009. - -Cunge, J.A., Holly, F.M. Jr., and Verwey, A., *Practical Aspects of -Computational River Hydraulics,* Pitman, London, 1980. - -Cunge, J.A. and Wegner, M. "Numerical integration of Barré de -Saint-Venant\'s flow equations by means of an implicit scheme of finite -differences", *La Houille Blanche*, Number 1, 1964. - -Davis, C.V., *Handbook of Applied Hydraulics*, Second Edition, -McGraw-Hill, New York, 1952. - -de Almeida, G.A.M. and Bates, P., "Applicability of the local inertial -approximation of the shallow water equations to flood modeling", *Water -Resour. Res*., 49, 4833--4844, 2013. - -Faram, M.G., Stephenson, A.G. and Andoh, R.Y.G., "Vortex flow controls: -state of the art review and application (from the catchbasin to the -dam)", *Proceedings of the 7th International Conference on Sustainable -Techniques and Strategies in Urban Water Management* (Novatech 2010), -Lyon, France, 27 June -- 1 July, 2010. - -Featherstone, R.E. and Nalluri, C., *Civil Engineering Hydraulics*, -Granada Publishing, Bungay, Great Britain, 1982. - -Federal Highway Administration (FHWA), *Urban Drainage Design Manual*, -Third Edition, Hydraulic Engineering Circular No. 22, FHWA-NHI-10-009, -U.S. Department of Transportation, 2009. - -Federal Highway Administration (FHWA), *Hydraulic Design of Culverts*, -Third Edition, Hydraulic Design Series Number 5, FHWA-HIF-12-026, U.S. -Department of Transportation, April, 2012. - -Fread, D.L., Jin, M. and Lewis, J.M., "An LPI numerical solution for -unsteady mixed flow simulation", Proceedings North American Water and -Environment Congress '96, American Society of Civil Engineers, Anaheim, -California, 1996. - -French, R.H., *Open-Channel Hydraulics*, McGraw-Hill, NY, 1985. - -Frost, W.H., "Minor Loss Coefficients for Storm Drain Modeling with -SWMM", *Journal of Water Management Modeling*, R225-23, doi: -10.14796/JWMM.R225-23, 2006. - -() - -Heaney, J.P., Huber, W.C., Sheikhv, H., Medina, M.A., Doyle, J.R., -Peltz, W.A., and Darling, J.E., "Urban Stormwater Management Modeling -and Decision Making", EPA-670/2-75-022 (NTIS PB-242290), U.S. -Environmental Protection Agency, Cincinnati, OH, 1975. - -Henderson, F.M., *Open Channel Flow*, MacMillan Publishing, NY, 1966. - -Huber, W.C., J.P. Heaney, M.A. Medina, W.A. Peltz, H. Sheikh, and G.F. -Smith, "Storm Water Management Model User's Manual ­ Version II," -EPA-670/2-75-01· (NTIS PB-257809), U.S. Environmental Protection Agency, -Cincinnati, OH, March 1975. - -Huber, W.C., Heaney,J.P., Nix, S.J., Dickinson, R.E. and Polmann, D.J., -"Storm Water Management Model User's Manual, Version III," -EPA-600/2-84-109a (NTIS PB84-198423), U.S. Environmental Protection -Agency, Cincinnati, OH, November 1981. - -Huber, W.C., and Dickinson, R.E., "Storm Water Management Model, Version -4, User\'s Manual"*,* EPA/600/3-88/001a (NTIS PB88-236641/AS), U.S. -Environmental Protection Agency, Athens, GA, 1988. - -Huber, W.C. and Roesner, L., \"The History and Evolution of the EPA -SWMM\" in Fifty Years of Watershed Modeling - Past, Present And Future, -A.S. Donigian and R. Field, eds., ECI Symposium Series, Volume P20, -2013. - -Hydro International, "Reg-U-Flo^®^ Vortex Valves Modeling in SWMM 5.0", -June, 2009. - - - -Kibler, D.F., Monser, J.R. and Roesner, L.A., "San Francisco Stormwater -Model, User's Manual and Program Documentation", prepared for the -Division of Sanitary Engineering City and County of San Francisco, Water -Resources Engineers, Walnut Creek, CA, 1975. - -Mays, L.W., "Storm and Combined Sewer Overflow: Flow Regulation and -Control", Chapter 18 in *Stormwater Collection Systems Design Handbook*, -L.W. Mays editor, McGraw-Hill, NY, 2001. - -Metcalf, L. and Eddy, H.P., *American Sewerage Practice, Design of -Sewers*, Volume 1, McGraw-Hill, New York, 1914. - -Metcalf & Eddy, Inc. *Wastewater Engineering*, McGraw-Hill, New York, -NY, 1972. - -Metcalf and Eddy, Inc., University of Florida, and Water Resources -Engineers, Inc., "Storm Water Management Model, Volume I ­ Final Report," -EPA Report 11024 DOC 07/71 (NTIS PB-203289), U.S. Environmental -Protection Agency, Washington, DC, July 1971a. - -Metcalf and Eddy, Inc., University of Florida, and Water Resources -Engineers, Inc., "Storm Water Management Model, Volume II ­ Verification -and Testing," EPA Report 11024 DOC 08/71 (NTIS PB-203290), U.S. -Environmental Protection Agency, Washington, DC, August 1971b. - -Metcalf and Eddy, Inc., University of Florida, and Water Resources -Engineers, Inc., "Storm Water Management Model, Volume III ­ User's -Manual," EPA-11024 DOC 09/71 (NTIS PB-203291), U.S. Environmental -Protection Agency, Washington, DC, September 1971c. - -Metcalf and Eddy, Inc., University of Florida, and Water Resources -Engineers, Inc., "Storm Water Management Model, Volume IV ­ Program -Listing," EPA Report 11024 DOC 10/71 (NTIS PB-203292), U.S. -Environmental Protection Agency, Washington, DC, October 1971d. - -Miller, J.E., "Basic Concepts of Kinematic-Wave Models", U.S. Geological -Survey Professional Paper 1302, U.S. Geological Survey, Department of -the Interior, Alexandria, VA, 1984. - -O'Brien, G.G., Hyman, M.A., and Kaplan, S. "A Study of the Numerical -Solution of Partial Differential Equations", *Journal Math. and -Physics*, No. 29, pp. 223-251, 1951. - -Ponce, V.M., "The Kinematic Wave Controversy", *Journal of Hydraulic -Engineering*, Vol. 117, No. 4, April, 1991. - -Ponce, V. M., Li, R.M. and Simons, D.B., \"Applicability of Kinematic -and Diffusion Models.\" *Journal of the Hydraulics Division, ASCE*, Vol. -104, No. HY3, March, pp. 353-360, 1978. - -Press, W.H., Teukolsky, S.A., Vetterling, W.T., and Flannery, B.P., -*Numerical Recipes in C*, Second Edition, Cambridge University Press, -1992. - -Roesner, L.A., Kassem, A.M., and Wisner, P.E., "Improvements in EXTRAN", -*Proceedings Stormwater Management Model (SWMM) Users Group Meeting 10 --- 11 January* 1980, EPA-600/9-80-017, U.S. Environmental Protection -Agency, Washington, DC, March 1980. - -Roesner, L.A., Shubinski, R.P. and Aldrich, J.A., "Stormwater Management -Model User's Manual Version III, Addendum I EXTRAN", EPA-600/2-84-109b, -Municipal Environmental Research Laboratory, U.S. Environmental -Protection Agency, Cincinnati, OH, 1983. - -Roesner, L.A., Aldrich, J.A. and Dickinson, R.E., "Storm Water -Management Model, Version 4, User\'s Manual: Extran Addendum", -EPA/600/3-88/001b (NTIS PB88-236658/AS), Environmental Protection -Agency, Athens, GA, 1992. - -Sanks, R.L. et al., *Pumping Station Design*, Second Edition, -Butterworth, London, UK, 1998. - -Shubinski, R.P., McCarty, J.C., and Lindorf, M.R., \"Computer Simulation -of Estuarial Networks\", *Journal of the Hydraulics Division, ASCE*, -vol. 91, HY5 , September 1965. - -Singh, V.P., ed., *Computer Models of Watershed Hydrology*, Water -Resources Publications, Highlands Ranch, CO, 1995. - -Sjőberg, A., "Sewer Network Models DAGVL-A and DAGVL-DIFF" in *Urban -Stormwater Hydraulics and Hydrology*, B.C. Yen, ed., Water Resources -Publications, Highlands Ranch, CO, 1982. - -Smith, G.D., *Numerical Solution of Partial Differential Equations: -Finite Difference Methods*, Second Edition, Clarendon Press, Oxford, -1978. - -Strelkoff, T. "One-Dimensional Equations of Open-Channel Flow", *Journal -of the Hydraulics Division*, ASCE, Vol. 95, No. HY3, May, 1969. - -Swamee, P.K., "Critical depth equations for irrigation canals", *Journal -of Irrigation and Drainage Engineering*, Vol. 119, No. 2, pp. 400--409, -1993. - -Toro, E.F., *Shock-Capturing Methods for Free-Surface Shallow Flows*, -John Wiley, Chichester, U.K., 2001. - -U.S. Environmental Protection Agency (US EPA), "SWMM 5 Applications -Manual", EPA/600/R-09/000, National Risk Management Research Laboratory, -Office of Research and Development, Cincinnati, OH, 2009. - -U.S. Environmental Protection Agency (US EPA), "SWMM 5 User's Manual", -EPA/600/R-05/040, National Risk Management Research Laboratory, Office -of Research and Development, Cincinnati, OH, 2010. - -Villemonte, J.R., "Submerged-weir Discharge Studies", *Engineering News -Record*, p. 866, Dec 25, 1947. - -Yen, B.C., "Hydraulics of Sewer Systems", Chapter 6 in *Stormwater -Collection Systems Design Handbook*, L.W. Mays editor, McGraw-Hill, NY, -2001. diff --git a/docs/manuals/reference/hydraulics/media/media/figure-theta.png b/docs/manuals/reference/hydraulics/media/media/figure-theta.png deleted file mode 100644 index dcb37b96a..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/figure-theta.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/figure3-10-placeholder.png b/docs/manuals/reference/hydraulics/media/media/figure3-10-placeholder.png deleted file mode 100644 index 8812cae0c..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/figure3-10-placeholder.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/figure8-3-placeholder.png b/docs/manuals/reference/hydraulics/media/media/figure8-3-placeholder.png deleted file mode 100644 index 65ef709d0..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/figure8-3-placeholder.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/figure8-4-placeholder.png b/docs/manuals/reference/hydraulics/media/media/figure8-4-placeholder.png deleted file mode 100644 index 4a0680c87..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/figure8-4-placeholder.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/figure9-2-placeholder.png b/docs/manuals/reference/hydraulics/media/media/figure9-2-placeholder.png deleted file mode 100644 index aa1440c2d..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/figure9-2-placeholder.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/figure1-6.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-figure1-6.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/figure1-6.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-figure1-6.png diff --git a/docs/manuals/reference/hydraulics/media/media/image1.jpeg b/docs/manuals/reference/hydraulics/media/media/hydraulics-image1.jpeg similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image1.jpeg rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image1.jpeg diff --git a/docs/manuals/reference/hydraulics/media/media/image10.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image10.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image10.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image10.png diff --git a/docs/manuals/reference/hydraulics/media/media/image11.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image11.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image11.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image11.png diff --git a/docs/manuals/reference/hydraulics/media/media/image12.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image12.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image12.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image12.png diff --git a/docs/manuals/reference/hydraulics/media/media/image13.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image13.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image13.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image13.png diff --git a/docs/manuals/reference/hydraulics/media/media/image14.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image14.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image14.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image14.png diff --git a/docs/manuals/reference/hydraulics/media/media/image15.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image15.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image15.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image15.png diff --git a/docs/manuals/reference/hydraulics/media/media/image16.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image16.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image16.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image16.png diff --git a/docs/manuals/reference/hydraulics/media/media/image17.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image17.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image17.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image17.png diff --git a/docs/manuals/reference/hydraulics/media/media/image18.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image18.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image18.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image18.png diff --git a/docs/manuals/reference/hydraulics/media/media/image20.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image20.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image20.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image20.png diff --git a/docs/manuals/reference/hydraulics/media/media/image21.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image21.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image21.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image21.png diff --git a/docs/manuals/reference/hydraulics/media/media/image23.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image23.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image23.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image23.png diff --git a/docs/manuals/reference/hydraulics/media/media/image24.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image24.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image24.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image24.png diff --git a/docs/manuals/reference/hydraulics/media/media/image29.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image29.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image29.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image29.png diff --git a/docs/manuals/reference/hydraulics/media/media/image30.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image30.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image30.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image30.png diff --git a/docs/manuals/reference/hydraulics/media/media/image31.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image31.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image31.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image31.png diff --git a/docs/manuals/reference/hydraulics/media/media/image37.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image37.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image37.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image37.png diff --git a/docs/manuals/reference/hydraulics/media/media/image38.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image38.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image38.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image38.png diff --git a/docs/manuals/reference/hydraulics/media/media/image39.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image39.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image39.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image39.png diff --git a/docs/manuals/reference/hydraulics/media/media/image4.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image4.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image4.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image4.png diff --git a/docs/manuals/reference/hydraulics/media/media/image49.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image49.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image49.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image49.png diff --git a/docs/manuals/reference/hydraulics/media/media/image5.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image5.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image5.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image5.png diff --git a/docs/manuals/reference/hydraulics/media/media/image50.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image50.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image50.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image50.png diff --git a/docs/manuals/reference/hydraulics/media/media/image51.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image51.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image51.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image51.png diff --git a/docs/manuals/reference/hydraulics/media/media/image52.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image52.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image52.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image52.png diff --git a/docs/manuals/reference/hydraulics/media/media/image8.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image8.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image8.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image8.png diff --git a/docs/manuals/reference/hydraulics/media/media/image9.png b/docs/manuals/reference/hydraulics/media/media/hydraulics-image9.png similarity index 100% rename from docs/manuals/reference/hydraulics/media/media/image9.png rename to docs/manuals/reference/hydraulics/media/media/hydraulics-image9.png diff --git a/docs/manuals/reference/hydraulics/media/media/image19.emf b/docs/manuals/reference/hydraulics/media/media/image19.emf deleted file mode 100644 index 2ec03cc8a..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image19.emf and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image22.png b/docs/manuals/reference/hydraulics/media/media/image22.png deleted file mode 100644 index 0821f4995..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image22.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image25.png b/docs/manuals/reference/hydraulics/media/media/image25.png deleted file mode 100644 index a6540d315..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image25.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image27.png b/docs/manuals/reference/hydraulics/media/media/image27.png deleted file mode 100644 index 14c236506..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image27.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image28.png b/docs/manuals/reference/hydraulics/media/media/image28.png deleted file mode 100644 index a36c98821..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image28.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image3.png b/docs/manuals/reference/hydraulics/media/media/image3.png deleted file mode 100644 index b1dd0457d..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image3.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image32.png b/docs/manuals/reference/hydraulics/media/media/image32.png deleted file mode 100644 index 07833a9ab..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image32.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image33.png b/docs/manuals/reference/hydraulics/media/media/image33.png deleted file mode 100644 index c321b8625..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image33.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image34.png b/docs/manuals/reference/hydraulics/media/media/image34.png deleted file mode 100644 index 643d600b9..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image34.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image35.png b/docs/manuals/reference/hydraulics/media/media/image35.png deleted file mode 100644 index 7b6b958a0..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image35.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image36.png b/docs/manuals/reference/hydraulics/media/media/image36.png deleted file mode 100644 index 78f0dd1c4..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image36.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image40.png b/docs/manuals/reference/hydraulics/media/media/image40.png deleted file mode 100644 index 6537711e1..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image40.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image41.png b/docs/manuals/reference/hydraulics/media/media/image41.png deleted file mode 100644 index 2fc7a57e3..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image41.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image42.png b/docs/manuals/reference/hydraulics/media/media/image42.png deleted file mode 100644 index 635ad459c..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image42.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image43.png b/docs/manuals/reference/hydraulics/media/media/image43.png deleted file mode 100644 index 6c2708db1..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image43.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image44.png b/docs/manuals/reference/hydraulics/media/media/image44.png deleted file mode 100644 index e2c2fec1a..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image44.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image56.png b/docs/manuals/reference/hydraulics/media/media/image56.png index 539f90c8b..967f41da3 100644 Binary files a/docs/manuals/reference/hydraulics/media/media/image56.png and b/docs/manuals/reference/hydraulics/media/media/image56.png differ diff --git a/docs/manuals/reference/hydraulics/media/media/image6.emf b/docs/manuals/reference/hydraulics/media/media/image6.emf deleted file mode 100644 index ab9038fdf..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image6.emf and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image65.emf b/docs/manuals/reference/hydraulics/media/media/image65.emf deleted file mode 100644 index bdd52547d..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image65.emf and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image66.emf b/docs/manuals/reference/hydraulics/media/media/image66.emf deleted file mode 100644 index 8f3bc02cb..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image66.emf and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image7.jpg b/docs/manuals/reference/hydraulics/media/media/image7.jpg new file mode 100644 index 000000000..294f30b69 Binary files /dev/null and b/docs/manuals/reference/hydraulics/media/media/image7.jpg differ diff --git a/docs/manuals/reference/hydraulics/media/media/image7.png b/docs/manuals/reference/hydraulics/media/media/image7.png deleted file mode 100644 index 6b0c595ce..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image7.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/media/media/image71.png b/docs/manuals/reference/hydraulics/media/media/image71.png deleted file mode 100644 index d6a60cdb1..000000000 Binary files a/docs/manuals/reference/hydraulics/media/media/image71.png and /dev/null differ diff --git a/docs/manuals/reference/hydraulics/sections/Appendix.md b/docs/manuals/reference/hydraulics/sections/Appendix.md index 7027f1aa3..7a87d4e13 100644 --- a/docs/manuals/reference/hydraulics/sections/Appendix.md +++ b/docs/manuals/reference/hydraulics/sections/Appendix.md @@ -4,7 +4,7 @@ ____________________________________________________________________________________________ -#### Newton-Raphson-Bisection Root Finding Method +## A. Newton-Raphson-Bisection Root Finding Method The following Newton-Raphson procedure adapted from Press et al. (1992) is used to solve the equation \f$f(x) = 0\f$ over the interval @@ -34,7 +34,7 @@ the solution with initial estimate *x* and convergence tolerance *ε* : > **Step 5:** Return to Step 2. -#### Ridder's Root Finding Method +## B. Ridder's Root Finding Method Ridder's method uses the following iterative procedure adapted from Press et al. (1992) to solve the equation \f$f(x) = 0\f$ over the interval @@ -78,7 +78,7 @@ solution with a convergence tolerance of *ε*: -#### Section Properties of Circular Pipes +## C. Section Properties of Circular Pipes **Table C‑1 Circular section properties as function of depth** | **Y/Yfull** | **A/Afull** | **W/Wmax** | **R/Rfull** | **Y/Yfull** | **A/Afull** | **W/Wmax** | **R/Rfull** | @@ -140,7 +140,7 @@ solution with a convergence tolerance of *ε*: | 0.48 | 0.48430 | 0.47329 | 1.00 | 1.0000 | 1.00000 | | 0.50 | 0.50000 | 0.49980 | | | | -#### Section Properties of Elliptical Pipes +## D. Section Properties of Elliptical Pipes **Table D‑1 Standard elliptical pipe sizes** | **Code** | **Minor Axis (in)** | **Major Axis (in)** | **Afull (ft²)** | **Rfull (ft)** | @@ -206,7 +206,7 @@ Source: American Concrete Pipe Association (2011). | 0.96 | 0.985 | 0.3919 | 1.185 | 0.990 | 0.3919 | 1.122 | | 1.00 | 1.000 | 0.0000 | 1.000 | 1.000 | 0.0000 | 1.000 | -#### Section Properties of Arch Pipes +## E. Section Properties of Arch Pipes **Table E‑1 Standard arch pipe sizes** | **Code** | **Material** | **Rise (Yfull) (in)** | **Span (Wmax) (in)** | **Afull (in²)** | **Rfull (in)** | @@ -351,7 +351,7 @@ Source: American Iron and Steel Institute (1999). | 0.96 | 0.995 | 0.3195 | 1.112 | | 1.00 | 1.000 | 0.000 | 1.000 | -#### Section Properties of Masonry Sewers +## F. Section Properties of Masonry Sewers **Table F‑1 Area of masonry sewers as function of depth** | **Y/Yfull** | **Basket Handle** | **Egg** | **Horseshoe** | @@ -690,7 +690,7 @@ Source: American Iron and Steel Institute (1999). | 1.00 | 1.00000 | 1.00000 | 1.00000 | 1.00000 | -#### Manning's Roughness Coefficients +## G. Manning's Roughness Coefficients **Table G‑1 Manning's roughness coefficient n for open channels** | **Type of Channel and Description** | **Minimum** | **Normal** | **Maximum** | @@ -868,7 +868,7 @@ Source: Chow, 1959. Source: American Iron and Steel Institute, 1999. -#### Culvert Coefficients +## H. Culvert Coefficients **Table H‑1 Culvert codes** | **Culvert Shape and Material** | **Inlet Configuration** | **Code** | diff --git a/docs/manuals/reference/hydraulics/sections/Chapter1-Overview.md b/docs/manuals/reference/hydraulics/sections/Chapter1-Overview.md index 7ee804e09..6a6e58a3e 100644 --- a/docs/manuals/reference/hydraulics/sections/Chapter1-Overview.md +++ b/docs/manuals/reference/hydraulics/sections/Chapter1-Overview.md @@ -70,7 +70,7 @@ system. SWMM conceptualizes this system as a series of water and material flows between several major environmental compartments. These compartments include: -![](hydraulics/media/media/image1.jpeg "image1") +![](hydraulics/media/media/hydraulics-image1.jpeg "image1")

Figure 1‑1 Elements of a typical urban drainage system

@@ -119,10 +119,28 @@ SWMM model. Table 1-2 provides a summary of the various objects used in SWMM. Their properties and functions will be described in more detail throughout the course of this manual. -![](hydraulics/media/media/image2.png "Objects2") +![Figure 1-2 Objects of an OpenSWMM model](figures/png/eng_object_sketch.png) + +
+@ref engine_manual_sect_RAINGAGES "Rain gage" +@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S1" +@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S2" +@ref engine_manual_sect_JUNCTIONS "Junction" +@ref engine_manual_sect_CONDUITS "Conduit" +@ref engine_manual_sect_VIRTUAL_JUNCTIONS "Virtual junction" +@ref engine_manual_sect_INLET_JUNCTIONS "Inlet junction" +@ref engine_manual_sect_STREETS "Street conduit" +@ref engine_manual_sect_DIVIDERS "Divider" +@ref engine_manual_sect_WEIRS "Weir" +@ref engine_manual_sect_ORIFICES "Orifice" +@ref engine_manual_sect_STORAGE "Storage unit" +@ref engine_manual_sect_PUMPS "Pump" +@ref engine_manual_sect_OUTFALLS "Outfall" +@ref engine_manual_sect_2D_TRIANGLES "2D mesh" +@ref engine_manual_sect_2D_VERTEX_NODE_MAP "1D–2D exchange" +

Figure 1‑2 SWMM's conceptual model of a -stormwater drainage system

+class="anchor">Figure 1-2 Objects of an OpenSWMM model

**Table 1-2 SWMM's modeling objects** @@ -155,10 +173,70 @@ Figure 1-3 depicts the processes that SWMM models using the objects described previously and how they are tied to one another. The hydrological processes depicted in this diagram include: -![](hydraulics/media/media/image3.png "image3") +![Figure 1-3 Processes modelled by OpenSWMM](figures/png/eng_process_flow.png) + +
+@ref hydrology_ref_ch2_meteorology "Precipitation" +@ref engine_manual_sect_RAINGAGES "rain · snow" +@ref hydrology_ref_ch2_meteorology "scale factors" +@ref hydrology_ref_ch6_snowmelt "Snowmelt" +@ref hydrology_ref_ch6_snowmelt "degree-day · areal depletion" +@ref hydrology_ref_ch3_surface_runoff "Initial abstraction · evaporation" +@ref engine_manual_sect_SUBAREAS "depression storage" +@ref hydrology_ref_ch3_surface_runoff "Surface runoff" +@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir" +@ref hydrology_ref_ch4_infiltration "Horton · Green-Ampt · CN" +@ref quality_ref_ch6_lid_controls "LID controls" +@ref quality_ref_ch6_lid_controls "layered units" +@ref quality_ref_ch6_lid_controls "storage nodes" +@ref quality_ref_ch4_surface_washoff "Washoff" +@ref quality_ref_ch3_pollutant_buildup "EMC · exponential · rating" +@ref hydrology_ref_ch5_groundwater "Groundwater" +@ref hydrology_ref_ch5_groundwater "two-zone aquifer per subcatchment" +@ref hydrology_ref_ch9_mesh_groundwater "two-layer aquifer on the mesh" +@ref hydrology_ref_ch9_mesh_groundwater "groundwater transport" +@ref quality_ref_ch3_pollutant_buildup "Pollutant buildup" +@ref quality_ref_ch3_pollutant_buildup "land uses · sweeping" +@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh" +@ref hydrology_ref_ch8_mesh_surface "natural neighbour" +@ref hydraulics_ref_ch9_two_dimensional "2D overland flow" +@ref hydraulics_ref_ch9_two_dimensional "local inertial" +@ref hydraulics_ref_ch9_two_dimensional "full shallow water" +@ref hydraulics_ref_ch9_two_dimensional "diffusive wave" +@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration · evaporation" +@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment · mesh aquifer" +@ref quality_ref_ch10_mesh_quality "2D surface quality" +@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff" +@ref engine_manual_sect_INFLOWS "External inflows" +@ref engine_manual_sect_DWF "dry weather flow" +@ref hydrology_ref_ch7_rdii "RDII: RTK" +@ref hydrology_ref_ch7_rdii "RDII: IA decay" +@ref engine_manual_sect_INFLOWS "user · interface files" +@ref hydraulics_ref_ch7_advanced_features "Street inlets" +@ref hydraulics_ref_ch7_advanced_features "HEC-22 link attribute" +@ref hydraulics_ref_ch7_advanced_features "inlet junction" +@ref hydraulics_ref_ch2_hydraulic_model "Channel, pipe and storage routing" +@ref hydraulics_ref_ch2_hydraulic_model "steady" +@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave" +@ref hydraulics_ref_ch8_finite_volume "finite volume" +@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN · slot · dynamic slot" +@ref hydraulics_ref_ch3_dynamic_wave "TPA" +@ref hydraulics_ref_ch3_dynamic_wave "virtual · inlet junctions" +@ref quality_ref_ch5_transport_treatment "Transport and reactions" +@ref quality_ref_ch5_transport_treatment "CSTR" +@ref quality_ref_ch7_ard_transport "ARD" +@ref quality_ref_ch7_ard_transport "LARD" +@ref quality_ref_ch5_transport_treatment "first-order decay" +@ref quality_ref_ch8_msx_reactions "MSX" +@ref quality_ref_ch9_age_heat "water age" +@ref quality_ref_ch9_age_heat "heat" +@ref quality_ref_ch11_planned "sediment" +@ref engine_manual_sect_TREATMENT "treatment · diversion" +@ref engine_manual_sect_OUTFALLS "Outfalls" +

Figure 1‑3 Processes modeled by -SWMM

+class="anchor">Figure 1-3 Processes modelled by OpenSWMM

- time-varying precipitation @@ -248,7 +326,7 @@ where Figure 1-4 depicts the simulation process in block diagram fashion. -![](hydraulics/media/media/image4.png "image4") +![](hydraulics/media/media/hydraulics-image4.png "image4")

Figure 1‑4 Block diagram of SWMM's state transition process

@@ -346,7 +424,7 @@ Users Manual (US EPA, 2010). Next the values of all state variables are initialized, as is the current simulation time (T), runoff time (Troff), and reporting time (Trpt). -![](hydraulics/media/media/image5.png "image5") +![](hydraulics/media/media/hydraulics-image5.png "image5")

Figure 1‑5 Flow chart of SWMM's simulation procedure

@@ -391,7 +469,7 @@ reporting purposes. In other words, if a reporting time falls within a runoff time step the reported rainfall intensity is the value associated with the start of the runoff time step. -![](hydraulics/media/media/figure1-6.png) +![](hydraulics/media/media/hydraulics-figure1-6.png) **Figure 1‑6 Interpolation of reported values from computed values** @@ -430,5 +508,137 @@ the unit of length and seconds as the unit of time. | Width | feet | meters | | Wind Speed | miles/hour | kilometers/hour | - - +## 1.6 The Formulations This Manual Covers + +Figure 1-7 places the hydraulics of this manual on OpenSWMM's process map: the +one-dimensional node–link network with its routing methods, pressurisation +closures and node solution, the two-dimensional overland surface, and the +exchange pathways between them. Each alternative carries its status +(Implemented, Experimental, Planned or Retired); the compartments documented +in @ref hydrology_reference_manual are shown faded. + +![Figure 1-7 The hydraulics of this manual: the 1D network, the 2D surface and their coupling](figures/png/hydraulics_conceptual_map.png) + +Figure 1-7 The hydraulics of this manual: the 1D network, the 2D surface and their coupling + +
+@ref hydrology_ref_ch2_meteorology "Precipitation" +@ref engine_manual_sect_RAINGAGES "rain gages" +@ref hydrology_ref_ch6_snowmelt "rain · snow split (SCF)" +@ref hydrology_ref_ch2_meteorology "scale factors" +@ref hydrology_ref_ch2_meteorology "Climate" +@ref engine_manual_sect_TEMPERATURE "temperature" +@ref engine_manual_sect_EVAPORATION "evaporation: constant · monthly · series · Hargreaves · file" +@ref engine_manual_sect_TEMPERATURE "wind" +@ref hydrology_ref_ch2_meteorology "humidity · dew point" +@ref hydrology_ref_ch2_meteorology "prescribed PET (API)" +@ref hydrology_ref_ch6_snowmelt "Snowmelt" +@ref hydrology_ref_ch6_snowmelt "degree-day · heat budget · areal depletion" +@ref hydrology_ref_ch3_surface_runoff "Runoff" +@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir" +@ref engine_manual_sect_SUBAREAS "depression storage" +@ref engine_manual_sect_SUBAREAS "routing to another subcatchment" +@ref hydrology_ref_ch4_infiltration "Infiltration" +@ref hydrology_ref_ch4_infiltration "Horton" +@ref hydrology_ref_ch4_infiltration "modified Horton" +@ref hydrology_ref_ch4_infiltration "Green-Ampt" +@ref hydrology_ref_ch4_infiltration "modified Green-Ampt" +@ref hydrology_ref_ch4_infiltration "curve number" +@ref quality_ref_ch6_lid_controls "LID controls" +@ref quality_ref_ch6_lid_controls "layered units (8 types)" +@ref quality_ref_ch6_lid_controls "LID as storage nodes" +@ref quality_ref_ch6_lid_controls "detailed output" +@ref quality_ref_ch3_pollutant_buildup "Surface quality" +@ref quality_ref_ch3_pollutant_buildup "buildup · washoff by land use" +@ref engine_manual_sect_LANDUSES "street sweeping" +@ref quality_ref_ch10_mesh_quality "MSX species" +@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh" +@ref hydrology_ref_ch8_mesh_surface "natural neighbour" +@ref engine_manual_sect_2D_OPTIONS "system" +@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration" +@ref hydrology_ref_ch8_mesh_surface "Horton · Green-Ampt · CN · constant" +@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment aquifer · mesh aquifer" +@ref hydraulics_ref_ch9_two_dimensional "Overland flow" +@ref hydraulics_ref_ch9_two_dimensional "local inertial" +@ref hydraulics_ref_ch9_two_dimensional "full shallow water" +@ref hydraulics_ref_ch9_two_dimensional "diffusive wave" +@ref hydraulics_ref_ch10_planned "IMEX / CVODE" +@ref hydraulics_ref_ch9_two_dimensional "Mesh and closure" +@ref hydraulics_ref_ch9_two_dimensional "triangles" +@ref hydraulics_ref_ch9_two_dimensional "quads" +@ref hydraulics_ref_ch9_two_dimensional "flat cells" +@ref hydraulics_ref_ch9_two_dimensional "VFR closure" +@ref quality_ref_ch10_mesh_quality "Surface quality · transport" +@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff" +@ref quality_ref_ch10_mesh_quality "species on the mesh" +@ref hydraulics_ref_ch9_two_dimensional "Backends" +@ref hydraulics_ref_ch9_two_dimensional "CPU" +@ref hydraulics_ref_ch9_two_dimensional "OpenMP" +@ref hydraulics_ref_ch9_two_dimensional "CUDA · HIP · SYCL" +@ref hydraulics_ref_ch10_planned "Metal" +@ref hydrology_ref_ch5_groundwater "Two-zone aquifer" +@ref hydrology_ref_ch5_groundwater "unsaturated + saturated zone" +@ref engine_manual_sect_AQUIFERS "percolation · deep percolation · ET" +@ref engine_manual_sect_GWF "lateral interflow, user [GWF]" +@ref hydrology_ref_ch9_mesh_groundwater "Groundwater transport" +@ref hydrology_ref_ch9_mesh_groundwater "advection–dispersion · heat" +@ref hydrology_ref_ch9_mesh_groundwater "Two-layer aquifer" +@ref hydrology_ref_ch9_mesh_groundwater "Gardner" +@ref hydrology_ref_ch9_mesh_groundwater "Russo" +@ref hydrology_ref_ch9_mesh_groundwater "Brooks–Corey" +@ref hydrology_ref_ch9_mesh_groundwater "van Genuchten" +@ref hydrology_ref_ch9_mesh_groundwater "closed form · enslaved · σ column" +@ref hydrology_ref_ch9_mesh_groundwater "Dunne return flow" +@ref hydrology_ref_ch9_mesh_groundwater "node–bed exchange" +@ref hydrology_ref_ch9_mesh_groundwater "capillary rise · boundary ET" +@ref hydrology_ref_ch9_mesh_groundwater "per-subcatchment mode" +@ref engine_manual_sect_JUNCTIONS "Nodes" +@ref engine_manual_sect_JUNCTIONS "junction · storage · divider · outfall" +@ref hydraulics_ref_ch3_dynamic_wave "virtual junction" +@ref hydraulics_ref_ch7_advanced_features "inlet junction" +@ref engine_manual_sect_CONDUITS "Links" +@ref hydraulics_ref_ch5_cross_section "conduits, 26 sections" +@ref hydraulics_ref_ch5_cross_section "street · dummy" +@ref hydraulics_ref_ch10_planned "Chebyshev irregular" +@ref engine_manual_sect_PUMPS "pumps · orifices · weirs · outlets · culverts" +@ref hydraulics_ref_ch5_cross_section "storage shapes" +@ref hydraulics_ref_ch7_advanced_features "HEC-22 inlets" +@ref hydraulics_ref_ch2_hydraulic_model "Flow routing" +@ref hydraulics_ref_ch2_hydraulic_model "steady" +@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave" +@ref hydraulics_ref_ch8_finite_volume "finite volume" +@ref hydraulics_ref_ch8_lts "local time stepping" +@ref hydraulics_ref_ch10_planned "1D GPU backend" +@ref hydraulics_ref_ch3_dynamic_wave "Pressurisation" +@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN" +@ref hydraulics_ref_ch3_dynamic_wave "slot" +@ref hydraulics_ref_ch3_dynamic_wave "dynamic slot" +@ref hydraulics_ref_ch3_dynamic_wave "TPA" +@ref hydraulics_ref_ch8_finite_volume "FV: slot" +@ref hydraulics_ref_ch8_finite_volume "FV: TPA" +@ref hydraulics_ref_ch8_finite_volume "FV: implicit head" +@ref hydraulics_ref_ch3_dynamic_wave "unsteady friction" +@ref hydraulics_ref_ch3_dynamic_wave "Node solution" +@ref hydraulics_ref_ch3_dynamic_wave "explicit continuity" +@ref hydraulics_ref_ch3_dynamic_wave "semi-implicit continuity" +@ref hydraulics_ref_ch3_anderson "Anderson acceleration" +@ref hydraulics_ref_ch10_planned "FV_NODE_* keys" +@ref quality_ref_ch5_transport_treatment "Transport" +@ref quality_ref_ch5_transport_treatment "CSTR" +@ref quality_ref_ch7_ard_transport "Eulerian ARD" +@ref quality_ref_ch7_ard_transport "Lagrangian LARD" +@ref quality_ref_ch7_ard_transport "random-walk dispersion" +@ref quality_ref_ch5_transport_treatment "first-order decay" +@ref quality_ref_ch8_msx_reactions "MSX reactions" +@ref quality_ref_ch9_age_heat "water age" +@ref quality_ref_ch9_age_heat "heat" +@ref quality_ref_ch11_planned "sediment" +@ref engine_manual_sect_TREATMENT "treatment functions" +@ref engine_manual_sect_INFLOWS "Inflows" +@ref engine_manual_sect_DWF "dry weather flow" +@ref hydrology_ref_ch7_rdii "RDII: RTK" +@ref hydrology_ref_ch7_rdii "RDII: IA decay" +@ref engine_manual_sect_INFLOWS "user · interface files" +@ref engine_manual_sect_CONTROLS "control rules" +
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter10-PlannedFormulations.md b/docs/manuals/reference/hydraulics/sections/Chapter10-PlannedFormulations.md new file mode 100644 index 000000000..907abe9a2 --- /dev/null +++ b/docs/manuals/reference/hydraulics/sections/Chapter10-PlannedFormulations.md @@ -0,0 +1,350 @@ +@page hydraulics_ref_ch10_planned Chapter 10: Planned and Retired Formulations + +@tableofcontents + +\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ + +**Nothing in this chapter is in this release.** \status{Planned} Chapters 2 +through 9 describe formulations the shipped engine executes; this chapter +records the ones it does not — designed, prototyped or measured and set +aside, or once shipped and withdrawn — so that a plan file cited in a +commit, a retired option key met in an old model, or a limitation stated +in an earlier chapter can be followed to its record. *Planned* means +designed and not built, whatever the plan's own optimism; *Retired* means +explored or shipped and withdrawn, with the measurement that withdrew it. +Every section names its plan of record by path; the plans are not part of +the manual, and the code is the source of truth where they disagree. + +| Section | Formulation | Plan of record | Status | +|---|---|---|---| +| 10.1 | Chebyshev spectral geometry for irregular sections | `plans/CHEBYSHEV_XSECT_GEOMETRY_PLAN.md`, `plans/CHEBYSHEV_XSECT_FEASIBILITY_2026-08-21.md` | \status{Planned} | +| 10.2 | An implicit finite-volume solver | `plans/FV_IMPLICIT_HYPRE_SOLVER_EXPLORATION.md` | \status{Planned} | +| 10.3 | The 1D finite-volume solver on Kokkos backends | `plans/EXPLICIT_FV_KOKKOS_1D_SOLVER_PLAN.md` §5, §7B.3; `ROADMAP.md` §7 | \status{Planned} | +| 10.4 | Dynamic wave on GPU | `plans/1d/1D_DYNWAVE_GPU_KOKKOS_STRATEGY.md` | \status{Retired} | +| 10.5 | The 2D solver on Metal | `plans/2d/2D_GPU_METAL_STRATEGY.md` | \status{Planned} | +| 10.6 | A bed-step treatment at finite-volume junction faces | none — `ROADMAP.md` §1.1 only | \status{Planned} | +| 10.7 | The Vasconcelos and Wright (2009) hybrid flux for the TPA filling front — no longer required: the divergence it answered was removed on 2026-09-12 | `plans/FV_SLOT_TPA_REVIEW_2026-08-31.md`, `plans/ISSUE_MIXED_FLOW_TPA_UF.md` | \status{Retired} | +| 10.8 | LID units as storage nodes, the hydraulic side | `plans/LID_StorageNode_Redesign.md`; `ROADMAP.md` §6 | \status{Planned} | +| 10.9 | Retired formulations | `plans/IMEX_LOCAL_INERTIAL_IMPLEMENTATION_PLAN.md`; `ROADMAP.md` §7; `src/engine/input/handlers/OptionsHandler.cpp` | \status{Retired} | + +*Table 10-1 Formulations recorded in this chapter* + +## 10.1 Chebyshev spectral geometry for irregular sections + +The `IRREGULAR`, `STREET` and `CUSTOM` sections of Chapter 4 are evaluated +from 51-row tables of area, width and hydraulic radius against depth, +interpolated piecewise-linearly. The forward lookups are nearly free — +about 15 ns — but the solvers spend their time in the *inverse* +direction: Newton on \f$A(S)\f$ costs 45 to 300 forward lookups, and the +finite-volume depth inversion of §8.4.3 must use a derivative-free Brent +search because the tabulated width is not the derivative of the tabulated +area. On a transect-heavy dynamic-wave deck the irregular chain measured +56 % of the routing wall clock. + +The first study (`plans/CHEBYSHEV_XSECT_FEASIBILITY_2026-08-21.md`) fitted +global Chebyshev series to the table interpolant against the 1e-8 parity +bar of the bit-exact tier and returned a no-go on replacement: the target +has fifty corners, the error frontier stalled five orders short, the fits +rang and were not monotone. It found a conditional go on a narrower use — +a degree-12 inverse *seed* feeding one or two Newton polishes against the +exact evaluators, 1.6–3.4× on the finite-volume inversion — inside the +tolerance-gated fast tier, never the default. + +The plan of record (`plans/CHEBYSHEV_XSECT_GEOMETRY_PLAN.md`, 2026-08-22) +reframes the target and supersedes that verdict. The reference is the +exact continuous geometry between stations — width piecewise linear, area +piecewise quadratic — of which the table is itself a sampling with its +own error (normalized: area \f$10^{-3}\f$, width 0.3, radius 0.1), and the +yardstick becomes "as accurate as the table", demonstrated end to end on +deck outputs. Per transect, at resolve time: up to four panels with +breaks placed first at detected discontinuities of the effective +hydraulic radius (an interior station submerging switches the conveyance +grouping) and then at the strongest width kinks; per panel a degree-10 +Chebyshev fit of \f$p \approx \sqrt{dA/dy}\f$, the area taken as the exact +antiderivative of \f$p^{2}\f$ — monotone by construction, pinned to +\f$A(y_{full})\f$ — the width as \f$p^{2}\f$, the hydrostatic moment as the +antiderivative of the area, the radius fitted per panel at degree 12, +plus a global seed for \f$y(\sqrt{a})\f$. On 43 real transects the area +error matches the table's budget, the seeded inverse beats the table on +43 of 43 with unconditional Newton convergence, and the radius fit beats +the table including the discontinuous transects. A per-transect +acceptance check falls back to the table, so the feature is safe on +geometry the study never saw. Selection is `XSECT_GEOMETRY TABLES` +(default) or `CHEBYSHEV`, behind a CMake switch, with phases from a +benchmark baseline through the fitter, the evaluators and parity harness, +the finite-volume and dynamic-wave integrations and an end-to-end +sign-off, and kill criteria that leave the fitter as a study artifact if +the deck-level gates fail. + +No part of this is in the tree: there is no `XSECT_GEOMETRY` option, no +Chebyshev evaluator in `src/`, no `OPENSWMM_CHEB_XSECT` switch. \status{Planned} + +## 10.2 An implicit finite-volume solver + +`plans/FV_IMPLICIT_HYPRE_SOLVER_EXPLORATION.md` (2026-05-13) is an +exploration, by its own status line, of a fully implicit finite-volume +reformulation of dynamic-wave routing. Each conduit is cut into +\f$N_c \ge 1\f$ control volumes carrying wetted area, with discharge +staggered at faces; junctions are zero-length volumes with a single head. +Backward Euler (or BDF-2) with new-time face fluxes gives a nonlinear +residual solved by Newton, its sparse linear systems preconditioned by +hypre BoomerAMG under GMRES or CG, with an Eigen back end when hypre is +absent. The motivation is the stiffness the Picard solver meets in looped +surcharged systems and mixed flow, and the wish for steps set by accuracy +rather than stability; the recommendation is a parallel, opt-in solver +preceded by a one-trunk-main feasibility prototype. + +The prototype was never built, and two premises have moved beneath the +plan. The explicit solver of @ref hydraulics_ref_ch8_finite_volume +"Chapter 8" took the `FLOW_ROUTING FV` slot and the `FV_` prefix — its +`FV_CELL_LENGTH` and `FV_MIN_CELLS` occupy the ground the plan's +`FV_CELLS_PER_CONDUIT` and `FV_TARGET_CFL` were drawn for, and +`FV_DYNWAVE` does not exist — and the hypre dependency the plan is named +for left the build with the implicit 2D integrators (§10.9). As a plan of +record it would need re-founding on the current tree. \status{Planned} + +## 10.3 The 1D finite-volume solver on Kokkos backends + +The explicit solver of Chapter 8 was planned with a device backend +(`plans/EXPLICIT_FV_KOKKOS_1D_SOLVER_PLAN.md` §5): reconstruction, HLLC +fluxes with the upwinded species flux, a per-chain tridiagonal dispersion +solve, cell and node updates (the face-to-node gather as a deterministic +two-pass CSR), a Courant reduction, wet–dry flags and a small host pass +for structures, with state device-resident across every substep of a +routing step in deliberate parallel with the 2D plugin, and a shared +device cross-section module gated by a bit-exact extraction test. + +What shipped is the option surface and the loader. `FV_BACKEND` accepts +`CPU`, `AUTO`, `OMP`, `CUDA`, `HIP` and `SYCL`, `FV_MIN_PARALLEL_CELLS` +gates `AUTO`, and `NetworkSolverFactory` searches the plugin path for +`openswmm_gpu_` and requires two symbols — `openswmm_gpu_probe` +and `openswmm_make_gpu_network_solver` — before accepting a plugin, +falling through to the CPU solver otherwise. **No plugin in the tree +exports the network-solver symbol**; the 2D plugins export the surface +and inertial-marcher factories only, so every device request resolves to +the CPU solver with a notice, as `ROADMAP.md` §7 records: "the same loader +hooks and option surface but no plugin implementation yet". + +The benchmark campaign that was to gate the port (§7B.3) returned a +no-go at the sizes measured: 2000 conduits at four cells each does not +reach the 20 000-cell gate, and at that size the solver runs 189× serial +dynamic wave, so no parallel efficiency makes it competitive there. The +plan is careful about scope — the dynamic-wave prototype of §10.4 +measured a Picard iteration, the wrong shape for a device, whereas the +explicit solver is local-stencil work of the right shape — and names the +undecided regime, \f$10^{5}\f$ to \f$10^{6}\f$ cells, together with the cheap +way to settle it: the solver's OpenMP thread scaling at those counts. The +Kokkos implementation is on hold pending that measurement (owner ruling +2026-08-08). \status{Planned} + +## 10.4 Dynamic wave on GPU + +`plans/1d/1D_DYNWAVE_GPU_KOKKOS_STRATEGY.md` (2026-06-13) asked whether +the link–node solver of Chapter 3 could be offloaded through Kokkos, and +answered with a working prototype (`plans/prototypes/dynwave_kokkos/`) +reproducing the solver's data flow — the structure-of-arrays conduit +tile, a conveyance kernel, the node-inflow scatter as atomics, the Picard +depth update and the global convergence reduction — with the same kernel +bodies called from a serial reference and the Kokkos loops. The port is +faithful: bit-exact on one thread, within \f$1.5 \times 10^{-8}\f$ ft on +four. The performance result set the direction aside: on the launch-cheap +OpenMP backend the parallel path was slower than serial at every size to +a million nodes (0.06× at 200, 0.81× at \f$10^{6}\f$), because three to +twenty Picard sweeps per step, each with a global reduction and a host +synchronization, are latency-bound until the element count is enormous; +a discrete GPU's crossover lies further right, at sizes that do not occur +in 1D practice. + +The recommendation, adopted, is not to pursue single-model offload of the +dynamic-wave solver. Two reframings survived — Kokkos as a portability +layer for the already-threaded CPU loops, and ensemble parallelism (many +models of one topology in one launch), which the plan identifies as the +credible payoff and for which no design exists. `ROADMAP.md` §7 lists GPU +solvers as no longer deferred on the strength of the 2D plugins and the +hooks of §10.3; the dynamic-wave offload itself is retired on +measurement. \status{Retired} + +## 10.5 The 2D solver on Metal + +The Kokkos backends of §9.11.1 have no Apple-GPU target, because Kokkos +has no production Metal backend. `plans/2d/2D_GPU_METAL_STRATEGY.md` +(2026-07-10) scopes the one path that closes the gap: a native Metal +plugin, `libopenswmm_gpu_metal.dylib`, implementing the same +`ISurfaceSolver` interface and C plugin ABI as the Kokkos plugins and +loaded through the existing factory with three additive lines. The hard +constraint is precision: Apple Silicon GPUs implement no `double`, so the +plan proposes mixed precision by default (fluxes in `float`, the conserved +accumulation and coupling ledger in higher precision), double-single +emulation where validation demands it, and an acceptance bar of parity +within a documented tolerance rather than bit-identity; unified memory +makes the host–device hand-off a coherency matter rather than a copy. + +The plan is stale in one structural respect: its port surface is the +implicit CVODE solver — nine right-hand-side kernels, a Jacobi +preconditioner and a matrix-free SPGMR loop, with a single-precision +SUNDIALS linked into the plugin — and that solver was retired on +2026-07-29 (§10.9). The engine a plugin must now reproduce is the +explicit marcher of §9.5, for which the ABI already reserves the +inertial-solver factory the Kokkos plugins implement. Packaging, +discovery, fallback and the precision analysis carry over; the kernel +inventory, milestones and validation cases do not. \status{Planned} + +## 10.6 A bed-step treatment at finite-volume junction faces + +`ROADMAP.md` §1.1 records, under "Peak attenuation at the default mesh", +that one cell per conduit attenuates the reference model's peaks by 37 % +on average (7 % at \f$\Delta x = 20\f$ ft), and that the cause is geometric +rather than diffusive: a cell-centred scheme places a single cell's bed at +the conduit mid-point, so every manhole presents an artificial bed step — +§8.3 and §8.10 describe the mechanism and its measured cost. +Higher-order reconstruction does not rescue it, because the error is in +where the bed is, not in how the state varies across the cell. +`FV_CELL_LENGTH` is the present workaround; the roadmap names "a bed-step +treatment at junction faces" as the fix. + +**No plan file exists for this item.** It is one line in the roadmap's +remaining-scope list. What such a treatment must do follows from +Chapter 8: the junction face of §8.6.1 would see, on each side, the +conduit's true invert at the node rather than the cell's mid-point bed, +so that the hydrostatic reconstruction of §8.5.1 is performed against the +real step at the manhole and not a fictitious one — the reconstruction a +resolved mesh's interior faces already perform, which is why refinement +removes the attenuation. Whether by extrapolating the bed to the face, a +junction-face reconstruction, or a two-sided invert per cell, is +undecided. \status{Planned} + +## 10.7 The TPA high-celerity filling divergence and the Vasconcelos and Wright (2009) hybrid flux + +The two-component pressure approach of §8.4.5 shipped with one pinned +defect: on filling and reflection decks at high acoustic celerity — the +laboratory fixture at \f$a = 150\f$ m/s — explicit Euler diverged at the +reflected surge within seconds, a *temporal* odd–even pressure–vacuum +oscillation inside the flagged region that a local conservative filter, +tried and measured, could not damp. `plans/ISSUE_MIXED_FLOW_TPA_UF.md` +records the hybrid flux of Vasconcelos and Wright (2009) — the paper's +own post-shock treatment — as the documented contingency and an explicit +non-goal; `ROADMAP.md` §1.1 names it the designated fix path, with the +gate `FvTpa.KnownIssueHighCelerityFillingDiverges` pinning the divergence. + +The review in `plans/FV_SLOT_TPA_REVIEW_2026-08-31.md` §5 then found a +family of divergences attributed to the closure to be an artefact of the +dynamic-wave step floor: the finite-volume substep was clamped *up* to the +legacy 1 ms `MIN_TIMESTEP`, discarding the Courant bound on short cells at +every `FV_CFL`, and the retry loop accepted the violating step silently. +A \f$10^{-6}\f$ s loop guard removed those, but the \f$a = 150\f$ m/s Euler +mode survived and the pin stood, correctly attributed. It fell on +2026-09-12 with the slot/free-surface wave-speed bound of the +closure-kernel program: Davis's symmetric estimate had carried the +acoustic celerity into the wave entering the *free-surface* side of a +pressurization front, and bounding that wave by the Rankine–Hugoniot bore +speed removes the mode. The fixture completes at 0.000 % continuity at +\f$a\f$ = 150, 300, 600, 1000 and 3000 m/s, and the gate is now the positive +test `FvTpa.HighCelerityFillingCompletes` +(`tests/unit/engine/test_fv_tpa_closure.cpp`). The roadmap entry, §8.4.5 +and one test comment still cite the old gate name. + +The hybrid flux is therefore no longer a required fix and has not been +implemented. It remains what the issue called it — a contingency should a +future deck reproduce the post-shock oscillation the paper describes — +with no plan to build it. \status{Planned} + +## 10.8 LID units as storage nodes, the hydraulic side + +`plans/LID_StorageNode_Redesign.md` and `ROADMAP.md` §6 record the design +for moving LID units out of the subcatchment and into the network, on the +argument that a green-infrastructure train's interactions — head-dependent +flow between units, backpressure from a saturated downstream unit, control +structures between units, an underdrain that sees the network's grade +line — are hydraulic phenomena a one-way runon cascade cannot mediate. The +hydraulic side uses machinery this manual already documents. A storage +node (Chapter 5) gains a `[LID_LAYERS]` attribute giving each layer a +fractional depth, porosity, conductivity and moisture limits; its storage +curve is corrected for the void fraction, + +\f[V(d) = A\left\lbrack h_{surface} + \varphi_{media}\,h_{media} + \varphi_{gravel}\,h_{gravel} \right\rbrack\f] + +so the head the node reports is the water surface accounting for media +occupancy, and that head is what the connected links see. The underdrain +is an ordinary orifice at the gravel-base offset — its discharge follows +the orifice law of Chapter 6 on the head difference to the receiving +node and reverses when the network surcharges above it, with no special +casing; surface overflow is a weir at the surface elevation; mid-media +outlets are further offset orifices; a chain of units is ordinary +node–link topology with control rules on the links between them. +Contributing areas drain to the node through the existing runon +mechanism. What is new — a kinematic Richards system for the unsaturated +media, its moisture-to-head mapping and a flux limiter — is hydrology. + +The status is "design recorded, no implementation". The plan's code +sketches target the legacy C sources (`objects.h`, `lid.c`, `node.c`) +rather than the current C++ engine, so an implementation would begin by +re-siting them. \status{Planned} + +## 10.9 Retired formulations + +**The IMEX local-inertial integrator.** \status{Retired} +`plans/IMEX_LOCAL_INERTIAL_IMPLEMENTATION_PLAN.md` proposed advancing the +2D surface with SUNDIALS ARKStep as an implicit–explicit integrator: a +diffusive-wave Phase 1 with the lateral diffusion implicit, a +local-inertial Phase 2 with the state enlarged to cell volumes and edge +discharges, and a Froude-gated blend selected by `MOMENTUM` and +`FROUDE_BLEND`, preconditioned by Casulli's elliptic free-surface operator +under hypre BoomerAMG. Phase 1 was implemented as `ArkodeSurfaceSolver` +and measured on 2026-06-26: correct and conservative, and structurally +slower than CVODE — 2.7× on the road-culvert case, 4.9× to 31× on a +synthetic basin, worsening with scale, at twenty times the Newton and +fifty-nine times the Krylov work — because in the diffusive wave the only +stiff term is the one the split made implicit, so the split merely +exchanged an adaptive-order BDF for a fixed-order DIRK on the same global +solve. The plan's header records the premise as refuted; Phases 2 and 3 +were never built, and the integrator went with the CVODE stack. + +**The CVODE and ARKODE integrators.** \status{Retired} The implicit +integrators were retired on 2026-07-29: the explicit marcher of §9.5 +outperformed them on the benchmark models and removed the SUNDIALS and +hypre dependencies (`ROADMAP.md` §7). `INTEGRATOR` accepts `EXPLICIT` +only; the fourteen keys that configured the retired stack, and any other +`INTEGRATOR` value, are accepted with WARNING 104 and ignored on file +load so legacy models still open, and are errors on the programmatic +option-set path (§9.11.2). + +**`ADVECTION YES`.** \status{Retired} The local-inertial law with a +staggered upwind convective difference added to (9-7) on wet–wet faces +(Stelling and Duinmeijer, 2003) was the first attempt to supply the term +§9.2.1 drops. It was superseded on 2026-09-06 by +`MOMENTUM_EQUATION FULL_SWE`, which supplies the term conservatively with +shock capturing. The key is deprecated rather than removed: a deck that +carries it is warned and keeps the physics it asked for (§9.2.3, +Table 9-2). + +**`VIRTUAL_JUNCTION_MOMENTUM FULL`.** \status{Retired} The cross-junction +momentum term `FULL` added at a virtual junction under dynamic-wave +routing was measured defective, not merely inaccurate: it is +sign-inverted with respect to the per-link convective term it supplements +(at constant discharge \f$\Delta(v^{2}A) = -v^{2}\Delta A\f$) and applied +to both adjacent links on top of each link's own term. On the SWASHES +MacDonald periodic case it destroyed 224–325 % of the routed volume; +negating it restored conservation but left 5.24 % \f$L^{1}\f$ error against +0.163 % for `BASIC`, so no term-level correction was worth keeping. +Retired 2026-08-14: `FULL` is accepted, warned and treated as `BASIC` +(`src/engine/input/handlers/OptionsHandler.cpp`). Under finite-volume +routing the question does not arise — a virtual junction is one interior +face, and conservation across it is a property of the scheme (§8.6.2). + +**The `FV_NODE_*` keys.** \status{Retired} Five keys are retired in two +tiers, on purpose. `FV_NODE_COUPLING`, `FV_NODE_DT` and `FV_NODE_PICARD` +(2026-08-29) once selected explicit versus semi-implicit storage-node +coupling, whether the node bound (8-32) was armed, and the number of +correction sweeps; storage nodes are now always semi-implicit, the bound +always armed, the correction one sweep — each the former default. A deck +spelling the former default is not warned; one asking for the retired +behaviour (`EXPLICIT`, `NONE`, sweeps above one) is warned at open, since +a calibrated model would otherwise change answers silently. +`FV_NODE_CELL_COUPLING` and `FV_JUNCTION_MODEL` were already no-ops — the +bucket-junction model and the coupled-star correction were superseded by +the pass-through interface of §8.6.1 — and stay silent +(`src/engine/input/handlers/OptionsHandler.cpp`; §8.9). + +The works cited above are listed in §8.12 (Vasconcelos, Wright and Roe, +2009) and §9.13 (Stelling and Duinmeijer, 2003). + diff --git a/docs/manuals/reference/hydraulics/sections/Chapter2-HydraulicModel.md b/docs/manuals/reference/hydraulics/sections/Chapter2-HydraulicModel.md index 6d2ce5f6b..f240315f5 100644 --- a/docs/manuals/reference/hydraulics/sections/Chapter2-HydraulicModel.md +++ b/docs/manuals/reference/hydraulics/sections/Chapter2-HydraulicModel.md @@ -14,7 +14,7 @@ system of sewer lines and their appurtenances are abstracted into a network of nodes and links of different types (pipe and pump links; junction, storage and outfall nodes for this particular example). -![SewerSystem2.png](hydraulics/media/media/image7.png) +![SewerSystem2.png](hydraulics/media/media/image7.jpg) **Figure 2-1 Node-link representation of a sewer system** **(Background from http://www.sewerhistory.org/photosgraphics/japan/)** @@ -151,11 +151,11 @@ The required input parameters for a conduit link are: - cross-section shape and dimensions. -![Link_offset.bmp](hydraulics/media/media/image8.png) +![Link_offset.bmp](hydraulics/media/media/hydraulics-image8.png) SWMM allows conduits to be offset some distance above the invert of their connecting end nodes as shown in the figure on the right. The offset can be specified as either a distance above the invert (i.e., the distance between points 1 and 2 in the figure) or as the elevation of the conduit's invert (i.e., the elevation of point 1). Internally the offset is maintained as an elevation. -![slope.png](hydraulics/media/media/image9.png) +![slope.png](hydraulics/media/media/hydraulics-image9.png) SWMM also makes use of a conduit's slope in its hydraulic calculations. Slope is not provided directly as an input variable but is instead computed from the elevation of a conduit's end node inverts and its offsets. Let *L* be the length of the conduit, *∆y* be the difference in elevation and *∆x* the horizontal distance between the invert at each end of the conduit. Then from the diagram on the right: @@ -362,7 +362,7 @@ hydrograph shape. This behavior is depicted in Figure 2-2 from Miller | Reverse flow | yes | no | | Tidal effects | yes | no | -![KWvsDW.png](hydraulics/media/media/image10.png) +![KWvsDW.png](hydraulics/media/media/hydraulics-image10.png) **Figure 2-2 Comparison of dynamic wave and kinematic wave solutions (from Miller, 1984)** diff --git a/docs/manuals/reference/hydraulics/sections/Chapter3-DynamicWave.md b/docs/manuals/reference/hydraulics/sections/Chapter3-DynamicWave.md index 5f6db4e9b..6f64e4daf 100644 --- a/docs/manuals/reference/hydraulics/sections/Chapter3-DynamicWave.md +++ b/docs/manuals/reference/hydraulics/sections/Chapter3-DynamicWave.md @@ -134,7 +134,7 @@ Non-storage junction nodes are assumed to be points with zero volume and surface area while storage nodes (such as ponds and tanks) contain both volume and surface area. -![Node-Link.bmp](hydraulics/media/media/image11.png) +![Node-Link.bmp](hydraulics/media/media/hydraulics-image11.png) **Figure 3-1 Node-link representation of a conveyance network in SWMM (from Roesner et al, 1992).** @@ -421,9 +421,9 @@ manhole) which can be overridden by the user. This is strictly a computational device and does not add volume to a junction node (where *ASN = 0*) nor change it into a storage node. -![Pipe.bmp](hydraulics/media/media/image12.png) +![Pipe.bmp](hydraulics/media/media/hydraulics-image12.png) -![SurfaceArea2.bmp](hydraulics/media/media/image13.png) +![SurfaceArea2.bmp](hydraulics/media/media/hydraulics-image13.png) **Figure 3‑2 Special flow conditions for dynamic wave analysis** @@ -510,7 +510,7 @@ itself would no longer be surcharged. **Figure 3-3 Illustration of a surcharged node** -![Surcharge4.bmp](hydraulics/media/media/image14.png) +![Surcharge4.bmp](hydraulics/media/media/hydraulics-image14.png) When a node becomes surcharged there is no more volume available in the conduits forming the node's assembly to absorb the difference between @@ -631,7 +631,7 @@ is given by: where *W*max is the conduit's maximum width, *Y*full is its full depth, and Y is depth of flow. This equation applies to -\f$\frac{Y}{Y_{full}}\f$ values between 0.985257 and 1.7. Below this range +\f$\frac{Y}{Y_{full}}\f$ values between 0.985257 and 1.78. Below this range the slot is not used while above it the slot width relative to *W*max is clamped at 0.01. The range's lower limit was chosen so that the width computed from equation 3-30 is the same as the width across a circular @@ -687,7 +687,7 @@ updated head is restricted to be just a small value above *H*max (or below it in the opposite case) to avoid wide swings in head during the transition. -![Surcharge5.bmp](hydraulics/media/media/image15.png) +![Surcharge5.bmp](hydraulics/media/media/hydraulics-image15.png) **Figure 3-4 Ponding of excess water above a junction** @@ -747,8 +747,9 @@ based on the generalized, dynamic and transient-storage form of the slot developed by Sharior, Hodges, and Vasconcelos (2023). It is selected by setting the `SURCHARGE_METHOD` option to `DYNAMIC_SLOT` (the other recognized values being `EXTRAN`, the default, for the -surcharge algorithm of Section 3.3.5 and `SLOT` for the static slot of -Section 3.3.6). Under this method the slot's cross-sectional area +surcharge algorithm of Section 3.3.5, `SLOT` for the static slot of +Section 3.3.6, and `TPA` for the two-component pressure approach of +Section 3.3.11). Under this method the slot's cross-sectional area evolves in time as an element of transient storage, and the modeler specifies the maximum pressure-wave celerity directly. @@ -893,6 +894,7 @@ explicit, user-controlled quantity. The pressurization life cycle of a conduit end under the dynamic slot is summarized in Figure 3-9. + 
 stateDiagram-v2
     direction LR
@@ -947,16 +949,29 @@ meant to serve: two collinear conduits of identical cross-section
 meeting at a grade break.
 
 Virtual junctions are declared in a dedicated `[VIRTUAL_JUNCTIONS]`
-input section whose entries carry only a name and an invert elevation:
+input section whose entries carry a name, an invert elevation and an
+optional maximum depth:
 
     [VIRTUAL_JUNCTIONS]
-    ;;Name           Elev
+    ;;Name           Elev        MaxDepth
     VJ1              101.25
-
-All remaining geometry is derived: the maximum depth equals the shared
-pipe's full depth, and the surcharge depth and ponded area are zero.
-In reports and output files a virtual junction appears as an ordinary
-junction whose stored volume is identically zero.
+    VJ2              100.80      4.50
+
+All hydraulic geometry is derived: the maximum depth used by the solver
+equals the shared pipe's full depth, and the surcharge depth and ponded
+area are zero. In reports and output files a virtual junction appears as
+an ordinary junction whose stored volume is identically zero.
+
+The optional third entry, `MaxDepth`, is a **drawing property only**. A
+virtual junction's derived maximum depth is the pipe crown, so a profile
+or section view that draws the ground surface at `invert + maximum depth`
+would sink the terrain to the crown at every break point. Supplying
+`MaxDepth` gives such views the real ground elevation to draw instead. No
+part of the solver, the routing, the reporting or the binary output file
+reads it, so a model produces identical results whether or not it is
+supplied; when it is omitted, viewers fall back to the pipe crown. A
+virtual junction created by splitting a conduit inherits a `MaxDepth`
+interpolated between the two end nodes' ground elevations.
 
 A node is eligible to be a virtual junction only if it satisfies all of
 the following, which are enforced when the input file is processed:
@@ -972,10 +987,12 @@ the following, which are enforced when the input file is processed:
 3.  Both conduit offsets at the node are zero; the node's invert is
     continuous with both conduit inverts.
 
-4.  No lateral inflow of any kind targets the node — external or dry
-    weather inflows, RDII, subcatchment outlets, LID drains, or
-    two-dimensional surface coupling. All inflow must arrive through
-    the upstream conduit.
+4.  The node is not a two-dimensional surface coupling point. A virtual
+    junction has no opening, so it cannot exchange water with an
+    overlying surface mesh. Point lateral inflows — external and dry
+    weather inflows, RDII, subcatchment outlets, LID drains and the
+    runtime lateral-inflow API — are permitted; see *Lateral inflows*
+    below.
 
 5.  The routing method is dynamic wave (or the finite-volume method of
     @ref hydraulics_ref_ch8_finite_volume "Chapter 8", under which a
@@ -1008,22 +1025,32 @@ momentum equations across the break. When flow runs in the pair's
 forward direction, the downstream conduit's upstream-weighted area and
 hydraulic radius (Equations 3-19 and 3-20) take the upstream conduit's
 mid-reach values as their upwind state, carrying the advected momentum
-state across the node instead of restarting it. When the
-`VIRTUAL_JUNCTION_MOMENTUM` option is set to `FULL` (the default is
-`BASIC`), an additional cross-junction convective correction is added
-to the \f$\Delta Q_{inertia}\f$ term of both conduits:
+state across the node instead of restarting it. This upwinding of the
+advected state is the whole of the momentum treatment: a virtual
+junction transmits **no** cross-junction convective momentum flux.
+
+**Retired option.** The `VIRTUAL_JUNCTION_MOMENTUM FULL` setting formerly
+added the cross-junction convective correction of Equation 3-43 to the
+\f$\Delta Q_{inertia}\f$ term of both conduits:
 
 | | | | |
 |---|---|---|---|
 | \f[\Delta Q_{j} = \mathrm{\Delta}t\,\sigma_{j}\frac{\left( \overline{U}^{2}\overline{A} \right)_{dn} - \left( \overline{U}^{2}\overline{A} \right)_{up}}{\Lambda}, \qquad \Lambda = \frac{L_{up} + L_{dn}}{2}\f] | | (3-43) | |
 
-which represents the convective flux difference across a control volume
-spanning the two half-conduits. Here *σ*j is a damping factor of the
-form of Equation 3-18 evaluated from the through-flow Froude number at
-the junction, so the correction is silenced near critical flow just as
-the per-conduit inertial terms are, and the correction vanishes
-whenever the two conduits do not carry flow the same way through the
-node. Pairs in a sag or peak orientation (both conduits pointing into,
+It is retired as of 2026-08-14. For steady discharge
+\f$\Delta\left( U^{2}A \right) = - U^{2}\Delta A\f$, so this correction
+carries the *opposite* sign to the per-conduit convective term it was
+meant to supplement, and adding it to both adjacent conduits applied it
+roughly three times over. On the SWASHES `macdonald-periodic` benchmark
+it destroyed 224–325 % of the routed volume; negating it restored mass
+conservation but still left a profile error of 5.24 % against 0.163 %
+for `BASIC` and 0.141 % for ordinary junctions. The keyword is still
+accepted, issues a warning, and is treated as `BASIC`. Models that need
+genuine momentum transport through a subdivided reach should use the
+finite-volume solver, which on the same benchmark is roughly 60× more
+accurate and 2.6× faster.
+
+Pairs in a sag or peak orientation (both conduits pointing into,
 or out of, the node) receive the zero-storage continuity treatment but
 not the directional momentum coupling. The two conduits of a pair are
 also always solved together: neither is frozen by the converged-node
@@ -1046,6 +1073,36 @@ status report. With identical cross-sections and a shared node head the
 hydrostatic terms cancel, so *R*j measures the discrete momentum-flux
 mismatch directly.
 
+**Lateral inflows.** A point lateral inflow at a virtual junction is
+integrated exactly as at any other node: it enters the flow balance
+\f$\sum Q\f$ of the zero-storage update, so at convergence the
+downstream conduit carries the upstream discharge plus the lateral.
+The node stays sealed — a lateral that exceeds the pair's capacity
+raises the head above the crown without flooding or ponding, as a tap
+into a buried main would — and its committed volume remains zero.
+One guard is added. At a dry pair the natural half-link area vanishes
+and \f$\sum \partial Q/\partial H\f$ is zero, so an imposed inflow
+would either divide a finite volume by nothing or fall into the
+dry-pair hold and be swallowed. While the node carries a lateral its
+surface area is therefore floored at a *wetting floor*: the pair's own
+natural half-link area evaluated at a seed depth of 2 % of the pipe's
+full depth, \f$w(0.02\,y_{full})\,(L_{up}+L_{dn})/2\f$ per barrel. The
+floor is continuous with the natural area (the larger of the two is
+used) and inert once the pair is wetter than the seed depth, so it
+scales with the reach instead of introducing the fixed
+*A*Smin storage the feature removes. Unfed virtual junctions
+keep their unfloored arithmetic. The momentum coupling is unchanged:
+the upwinding of Equations 3-19 and 3-20 hands the upstream conduit's
+state across the node, so with a lateral the treatment is first order
+in \f$q_{lat}/Q\f$ — the same class of approximation a regular junction
+makes for all of its momentum — and the residual *R*j of
+Equation 3-44 is legitimately nonzero at a fed node, which the Virtual
+Junction Summary marks. Under the finite-volume method the lateral is
+divided equally between the two cells adjoining the spliced face as a
+zero-momentum source (Chapter 8, §8.6.2). Re-fusing a fed virtual
+junction removes its inflow rows and unassigns any subcatchment or LID
+drain that targeted it, exactly as deleting the node would.
+
 **Modeling implications.** A virtual junction transmits streamwise
 momentum and is intended for grade breaks between near-collinear
 pipes, where the deflection angle is small and axial momentum
@@ -1059,8 +1116,7 @@ that the same subdivision with regular junctions would introduce.
 Control rules may reference a virtual junction's depth, which is well
 defined; its volume is identically zero.
 
-
-![Figure 3-10](figure3-10-placeholder.png)
+![Figure 3-10](figures/png/hydraulics_ch3_virtual_junction.png)
 
 *Figure 3-10 Virtual junction representation of a conduit grade break*
 
@@ -1082,6 +1138,284 @@ and Bocchi, J.P.P. (2020). "Comparing SWMM 5.1 Calculation Alternatives
 to Represent Unsteady Stormwater Sewer Flows." Journal of Hydraulic
 Engineering, 146(7), 04020046.*
 
+#### Inlet junctions
+
+An *inlet junction* is a virtual junction that also owns a street inlet.
+It is declared in its own `[INLET_JUNCTIONS]` section, whose first three
+entries mirror `[VIRTUAL_JUNCTIONS]` and whose remaining entries are the
+placement columns of `[INLET_USAGE]`:
+
+    [INLET_JUNCTIONS]
+    ;;Name   Elev    MaxDepth  Inlet   CaptureNode  #Inlets  %Clog  Qmax  aLocal  wLocal  Placement
+    IJ1      98.00   0.50      Curb1   MH2          1        10     0     0       0       ON_GRADE
+
+The node obeys every virtual-junction eligibility rule above and, in
+addition, both attached conduits must carry a STREET cross-section
+(error 623), the inlet design must exist (625), the capture node must
+exist, differ from the junction and be a real node (627), neither
+attached conduit may itself carry an `[INLET_USAGE]` row (629), the row
+may carry no extra entries (631), and an inlet junction without a usage
+row is refused (633). A design incompatible with the host section is a
+warning (635) that disarms the inlet, as in legacy SWMM.
+
+**Capture.** At every routing step, after all other lateral inflows have
+been assembled and before the conduits are solved, the HEC-22 capture
+kernel computes the flow the inlet intercepts from the gutter flow
+arriving on the approach conduit — the conduit whose flow is directed
+toward the node; at a sag both conduits contribute — using the street
+geometry and the design dimensions exactly as for a conduit-attribute
+inlet. The captured flow leaves the junction as a negative lateral
+inflow and enters the capture node as a positive one; the bypass
+continues down the street. When the capture node floods, its overflow
+returns to the street through the inlet as backflow, so the transfer runs
+in either direction. Placement `AUTOMATIC` resolves by slope: the node is
+a sag when both conduits fall toward it, on-grade otherwise.
+
+**Continuity.** Unlike a plain virtual junction the node is *not*
+sealed: water that rises above the street section leaves the corridor.
+The head update is the zero-storage virtual-junction form, but the
+flooding logic of an ordinary junction applies above a threshold equal
+to the street section's full depth or, when it is larger, the `MaxDepth`
+entry. `MaxDepth` can therefore raise the threshold — a raised curb line,
+a wall — but never lower it below the section, so a rendering-only rim
+inherited from a conduit split cannot make the node flood early. The node
+has no ponded area, so water above the threshold is lost as flooding.
+Its stored volume is identically zero: the half-link surface area it
+carries is the linearization of the adjacent conduits, not storage of
+its own.
+
+**Momentum.** The pair receives the zero-storage continuity treatment
+only. The directional momentum coupling (the upwind-state carry-over
+across the break) is disabled at an inlet junction, because that
+coupling assumes a sealed pair with no lateral exchange at the node.
+
+**Routing methods.** Inlet junctions require dynamic wave routing. Under
+kinematic or steady routing the virtual-junction rule applies (error
+619); under finite-volume routing, which splices virtual junctions out
+of its mesh (§8.6.2), an inlet junction is also refused with error 619,
+because the spliced node could no longer carry the capture sink.
+
+**Results and files.** The node reports as a JUNCTION in the output
+file. The Street Inlet Flow Summary lists it as `NAME (node)` beside the
+conduit-attribute inlets, with the same performance columns. When a
+model is written for a SWMM 5.x engine (the `SWMM5` write profile of
+`swmm_model_write_compat`), an inlet junction is downgraded to an
+ordinary junction plus an `[INLET_USAGE]` row on its approach conduit
+with the same design and capture node — the legacy-equivalent model —
+and the writer reports the substitution.
+
+Implementation: `src/engine/hydraulics/Inlet.cpp` (the kernel and the
+per-step transfer, `inlet::InletSolver::computeAll`), the unsealed
+flooding branch of `DWSolver::commitNodeDepthState` and the
+mechanism-1-only guard in `DWSolver::vjPrepareIteration`
+(`src/engine/hydraulics/DynamicWave.cpp`), validation in
+`src/engine/input/PostParseResolver.cpp` (`validate_inlet_junctions`),
+and the split/fuse editing operations `ij_split_conduit` / `ij_fuse` in
+`src/engine/edit/VirtualJunctionOps.cpp`.
+
+### 3.3.11 Two-Component Pressure Approach (`SURCHARGE_METHOD TPA`)
+
+All three surcharge treatments described so far share one fidelity
+limit: a head below the pipe crown is always reinterpreted as a free
+surface, so a sealed conduit cannot hold sub-atmospheric pressure
+during a rapid downsurge. OpenSWMM provides a fourth surcharge
+treatment, `SURCHARGE_METHOD TPA`, a pragmatic port of the
+two-component pressure approach of Vasconcelos, Wright and Roe (2006)
+to the node-link scheme. (Its natural home is the finite-volume solver,
+where the full shock-capturing formulation is available as
+`FV_PRESSURE_CLOSURE TPA` —
+@ref hydraulics_ref_ch8_finite_volume "Chapter 8".) It is
+\status{Experimental}: default-off, validated on the Vasconcelos et al.
+(2006) laboratory cases, with the high-celerity filling divergence of
+§8.4.5 still open.
+
+**Requirements.** The method needs a **closed conduit with a defined
+full depth**: an open cross-section, or one whose \f$Y_{full}\f$ is
+zero, never latches and keeps ordinary free-surface geometry — the
+option is inert outside closed pipe, so mixed networks need no special
+arrangement. Setup is the pair `SURCHARGE_METHOD TPA` and
+`TPA_CELERITY` under `FLOW_ROUTING DYNWAVE`. Only a *sealed* conduit
+end — a virtual junction (Section 3.3.10) or a node with positive
+surcharge depth — can hold sub-crown pressure; every other end vents.
+Signed heads reach the binary output only under
+`REPORT_SIGNED_HEADS YES`, and `NODE_CONTINUITY SEMI_IMPLICIT`
+(Section 3.5) is the recommended pairing.
+
+**Above the crown: a constant-width slot.** Where the static slot of
+Section 3.3.6 uses the Sjőberg width function 3-30, TPA uses the
+classical celerity-derived width directly, held constant per conduit:
+
+| | | | |
+|---|---|---|---|
+| \f[w_{tpa} = \frac{gA_{full}}{a^{2}}\f] | | (3-49) | |
+
+where \f$a\f$ is the acoustic celerity given by the `TPA_CELERITY`
+option, in project length units per second (converted internally;
+compare Equation 3-29). There is no Sjőberg decay and no clamp above
+1.78 *Y*full; the crown cutoff at *Y*/*Y*full = 0.985257 applies
+as it does for the other slot methods. Above the crown this is the
+whole story: heads are always updated through the ordinary
+free-surface continuity formula with the slot supplying the surface
+area, and the surcharge branch of Equation 3-28 is never invoked.
+
+**Below the crown: the sub-atmospheric latch.** The new capability is a
+per-conduit *pressurized latch*, recording whether the air pathway to
+the conduit has been cut — physical history, not a numerical device.
+The latch is **set** when the conduit reaches full (both end depths at
+*Y*full, the same condition that engages the slot branch today). While
+it is set, a head below the crown at a *sealed* end does not revert the
+conduit to free-surface geometry: the flow area follows the signed slot
+line \f$A_{full} + w_{tpa}(Y - Y_{full})\f$ — "shrinkage" of the section
+under negative gauge pressure — the top width stays \f$w_{tpa}\f$, the
+hydraulic radius stays at its full-conduit value (the slot carries no
+wetted perimeter), and each end contributes \f$w_{tpa}L/4\f$ of surface
+area to node continuity. Momentum needs no new terms: the solver
+already differences node heads, and a sub-crown head at a sealed node
+is simply a head — the latch's only job is preventing the geometry
+tables from reinterpreting it as a free-surface depth.
+
+The latch is **cleared** when air can actually re-enter: at a *vented*
+end whose flow depth stands below the crown at that end (an
+*unsubmerged* opening — a vented node whose water level stands above
+the crown holds the column, exactly as a submerged inlet holds a
+siphon), or on column separation, when the mid-reach depth falls more
+than 30 ft below the crown — about one atmosphere of water column,
+past which a vapor cavity forms and two-phase dynamics outside the
+model's scope take over. *Sealed* means a virtual junction (Section
+3.3.10) or a node with a positive surcharge depth (a bolted cover);
+everything else is vented. The latch is updated **once per routing
+step, before the iterative solution begins**, so the Picard iteration
+of Section 3.2 iterates a fixed operator — the same reasoning that has
+the dynamic slot advance its state between iterations rather than
+within them. When Anderson acceleration (Section 3.6) is active, the
+end nodes of any conduit whose latch changed this step take the plain
+iterate for that step, since a latch transition is a discrete operator
+switch (see Table 3-2).
+
+**What is and is not captured.** DW node depths are floored at zero, so
+the vacuum representable at a node is bounded by the distance from the
+crown down to the node invert: stations that would fall below their
+own invert under vacuum — the deep sub-atmospheric transients of the
+negative-pressure siphon class — are finite-volume territory
+(@ref hydraulics_ref_ch8_finite_volume "Chapter 8"). DW TPA's value is
+sealed sub-crown behavior: no spurious geometry flip, no spurious
+flooding, and a head that recovers smoothly when inflow returns. On the
+rapid-filling laboratory case of Vasconcelos et al. (2006), DW TPA's
+bore arrival lands within 2 % of the finite-volume timing (10.25 s
+against 10.45 s), where the Sjőberg static slot arrives about 20 %
+early (8.35 s) — measured on the mixed-flow closure study of issue
+#156. Phase 6 of that study, scoring against the digitized laboratory
+record on a shared absolute threshold (head first exceeding 0.15 m at
+the 9.9 m station, measured at 6.69 s), places the columns in absolute
+terms: the dynamic slot lands 0.14 s early (6.55 s), the static slot
+at 9.95 s, DW TPA at 12.25 s, and EXTRAN at 14.35 s — so DW TPA's
+agreement with the finite-volume timing above is scheme consistency,
+not accuracy on this filling case (and the finite-volume columns'
+own timing there is compromised by a documented initial-condition
+seeding defect). On the negative-pressure siphon case, Phase 6
+measured every dynamic-wave column bottoming at 0.231–0.233 m of
+crest head against 0.1035 m for finite-volume TPA — the quantified
+form of the invert-floor limit above. To observe signed heads in the
+binary output file at all, set
+`REPORT_SIGNED_HEADS YES` (default `NO` preserves legacy bit-parity;
+the HEAD field then carries the true signed head while DEPTH stays
+floored — both solvers honor the option).
+
+The method adds one `[OPTIONS]` keyword beside `SURCHARGE_METHOD`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `TPA_CELERITY` | 100 | Acoustic celerity \f$a\f$ in Equation 3-49, in project length units per second. Air content can cut the true value by an order of magnitude, so it is a user parameter, exactly like the finite-volume solver's `FV_SLOT_CELERITY`. |
+
+`NODE_CONTINUITY SEMI_IMPLICIT` (Section 3.5) is the recommended
+pairing: with the constant \f$w_{tpa}\f$ surface area the unified update
+is smooth through the crown.
+
+**Implementation.** The latch update and geometry override are
+`updateTpaLatch` and `applyTpaGeometry` in
+@ref openswmm::dynwave::DWSolver "DWSolver"
+(`src/engine/hydraulics/DynamicWave.cpp`), hooked beside the dynamic
+slot's `applyDPSGeometry`; the per-conduit width (3-49) is computed at
+initialization. Gates: `tests/unit/engine/test_dw_tpa.cpp`.
+
+*Reference: Vasconcelos, J.G., Wright, S.J., and Roe, P.L. (2006).
+"Improved Simulation of Flow Regime Transition in Sewers: Two-Component
+Pressure Approach." Journal of Hydraulic Engineering, 132(6), 553–562.*
+
+### 3.3.12 Unsteady Friction (`UNSTEADY_FRICTION`)
+
+Mixed-flow models that carry only steady friction reproduce observed
+transient damping only by inflating Manning's *n* to unphysical values.
+OpenSWMM offers the remedy of Pinto, Vasconcelos and Soares (2025) — a
+modified Vítkovský et al. (2000) instantaneous-acceleration term with a
+Brunone-type coefficient *k*3 — as an option orthogonal to the
+surcharge method and shared with the finite-volume solver
+(@ref hydraulics_ref_ch8_finite_volume "Chapter 8"). The friction slope
+becomes \f$S_f = S_{fs} + S_{fu}\f$ with the steady term unchanged and
+
+| | | | |
+|---|---|---|---|
+| \f[S_{fu} = \frac{k_{3}}{g}\left( \frac{\partial V}{\partial t} + c\,\mathrm{sgn}(V)\left\lvert \frac{\partial V}{\partial x} \right\rvert \right)\f] | | (3-50) | |
+
+where the celerity *c* is regime-dependent: the acoustic celerity when
+the conduit is pressurized, the gravity-wave celerity otherwise. In
+this solver both come out of the mid-reach top width already in hand —
+the slot width while surcharged under a slot method (so `TPA_CELERITY`
+governs under TPA), the free-surface width otherwise, and the
+near-crown width under `EXTRAN`, which has no acoustic celerity of its
+own and is therefore the weakest pairing.
+
+The term drops into the flow updating formula 3-14 the way every other
+term does. The local-acceleration half integrates semi-implicitly —
+*k*3 joins the denominator alongside \f$\Delta Q_{friction}\f$ and
+\f$k_{3}\overline{A}\,V^{old}\f$ joins the numerator — which also enters
+the flow gradient 3-27, keeping the surcharge iteration and the
+semi-implicit node continuity consistent with the flow update. The
+convective half is an explicit term built from the end velocities. Two
+details are consequences of the node-link discretization rather than
+choices:
+
+- **The velocity gradient uses a cross-link stencil.** Within a single
+  link the gradient estimator is the end-velocity difference, which is
+  *structurally zero* on a full conduit (equal end areas) — exactly the
+  pressurized case the term exists for. The gradient therefore reads
+  the neighboring conduits' previous-iterate velocities across simple
+  two-conduit junctions, sign-mapped into the link's frame, with the
+  within-link difference as the fallback. The modeling consequence:
+  **unsteady-friction damping requires a discretized reach.** A single
+  long conduit has no neighbors to difference against and receives
+  added inertia only; subdividing the reach (virtual junctions serve
+  well, Section 3.3.10) restores the damping term.
+- **Force mains** have equal end areas by construction, so the gradient
+  term vanishes and only the local-acceleration fold acts.
+
+As in the finite-volume implementation, a 0.01 ft/s velocity dead-band
+keeps the added inertia from amplifying numerical settling noise, a
+per-step clamp bounds the update to half the incoming momentum, and
+with `UNSTEADY_FRICTION NONE` (the default) the original expressions
+are evaluated verbatim for bit-parity.
+
+Fidelity expectations must be set honestly: the node-link solver cannot
+reproduce waterhammer (a 1255 m/s valve-closure transient is
+finite-volume-with-implicit-acoustics territory). The dynamic wave
+value proposition is better damping of inertial oscillations and
+post-surcharge transients at ordinary routing steps.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `UNSTEADY_FRICTION` | `NONE` | `NONE` or `VITKOVSKY`. `NONE` is bit-inert in both solvers. |
+| `UF_K3` | 0.015 | Brunone-type coefficient *k*3 in Equation 3-50, used only when the method is not `NONE`. Paper-calibrated range 0.005–0.020, swept to 0.045. |
+
+**Implementation.** The dq-term extension lives in `processManningLink`
+and `processForceMainLink` of @ref openswmm::dynwave::DWSolver
+"DWSolver" (`src/engine/hydraulics/DynamicWave.cpp`), with the
+cross-link stencil tables built in `DWSolver::init`. Gates:
+`tests/unit/engine/test_dw_unsteady_friction.cpp`.
+
+*Reference: Pinto, S.I.G., Vasconcelos, J.G., and Soares, A.K. (2025).
+"Unsteady Friction in Mixed-Flow Models Based on the Saint-Venant
+Equations." Journal of Hydraulic Engineering, 152(1), 04025046.*
+
 ## 3.4 Numerical Stability
 
 The numerical stability of SWMM's dynamic wave results can be affected
@@ -1207,7 +1541,7 @@ of 0.015 (see Figure 3-5). When divided into 10 equal length sections of
 \f$\frac{200}{\sqrt{32.2 \times 2} = 25}\f$ seconds. When analyzed as just a
 single 2,000 ft long section it increases to 250 seconds.
 
-![Example1a.png](hydraulics/media/media/image16.png)
+![Example1a.png](hydraulics/media/media/hydraulics-image16.png)
 
 **Figure 3-5 Profile view of example rectangular conduit (not to scale)**
 
@@ -1217,7 +1551,7 @@ dotted curve in the figure). Both results are completely stable. The
 option with the higher spatial resolution produces a more skewed
 hydrograph with a slightly lower peak.
 
-![](hydraulics/media/media/image17.png "image17")
+![](hydraulics/media/media/hydraulics-image17.png "image17")
 
 **Figure 3-6 Outflow hydrographs for example conduit -I**
 
@@ -1229,7 +1563,7 @@ variable time step a stable result is produced. In this case SWMM's
 Status Report shows that the variable time step ranged from 24 to 120
 seconds with the average being 42.
 
-![](hydraulics/media/media/image18.png "image18")
+![](hydraulics/media/media/hydraulics-image18.png "image18")
 
 **Figure 3-7 Outflow hydrographs for example conduit – II**
 
@@ -1286,7 +1620,7 @@ continuity setting for models containing virtual junctions
 (`src/engine/core/SimulationOptions.hpp`) and parsed in
 `src/engine/input/handlers/OptionsHandler.cpp`.
 
-## 3.6 Anderson Acceleration of the Iterative Solution
+## 3.6 Anderson Acceleration of the Iterative Solution {#hydraulics_ref_ch3_anderson}
 
 The successive-approximation procedure of Section 3.2 is a fixed-point
 (Picard) iteration: each pass applies the same head-update operator to
@@ -1366,6 +1700,7 @@ pair well.
 | Surcharged node | `SURCHARGE_METHOD EXTRAN` with `NODE_CONTINUITY EXPLICIT` | The head update switches from Equation 3-15 to Equation 3-28 at the crown. |
 | Active dynamic slot | `SURCHARGE_METHOD DYNAMIC_SLOT`; node touches a conduit with *A*s > 0 | The slot geometry of Section 3.3.9 is rewritten each iteration, so the operator differs between iterates. |
 | Near the static slot cutoff | `SURCHARGE_METHOD SLOT`; node touches a closed conduit with \f$0.98 \leq \overline{Y}/Y_{full} \leq 1.02\f$ | The slot width of Equation 3-30 engages abruptly at the crown cutoff. |
+| TPA latch transition | `SURCHARGE_METHOD TPA`; node touches a conduit whose pressurized latch changed this routing step | A latch transition is a discrete operator switch (Section 3.3.11). Steadily latched or steadily free conduits remain eligible. |
 | Weir or orifice at its crown | Upstream hydraulic grade line at or above the structure crown; both end nodes | The flow equation switches discontinuously (weir to orifice; partial to full submergence). |
 | Pump end nodes | Always; both end nodes of every pump | Pump on/off status is discrete. |
 
@@ -1381,6 +1716,7 @@ that of Section 3.2.
 
 Figure 3-11 summarizes one accelerated iteration.
 
+
 
 flowchart TD
     A[Start iteration k] --> B[Compute plain iterate G of H_k for every node]
@@ -1397,6 +1733,11 @@ flowchart TD
     J -- no --> B
     J -- yes --> K[Node converged]
 

+

+@ref hydraulics_ref_ch3_anderson "3.6 Anderson acceleration: the residual gate and eligibility"
+@ref hydraulics_ref_ch3_anderson "3.6 Anderson acceleration: the mixing coefficient"
+@ref hydraulics_ref_ch3_anderson "3.6 Anderson acceleration: convergence"
+

 
 *Figure 3-11 Workflow of one Anderson-accelerated iteration of the
 successive-approximation loop (rendered diagram)*
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter4-KinematicWave.md b/docs/manuals/reference/hydraulics/sections/Chapter4-KinematicWave.md
index a1f840704..39f31a352 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter4-KinematicWave.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter4-KinematicWave.md
@@ -101,7 +101,7 @@ in Figure 4-2. A weighted Wendroff implicit finite difference scheme
 
 \f[\frac{(1 - \theta)\left( A_{1}^{t + \Delta t} - A_{1}^{t} \right) + \theta\left( A_{2}^{t + \Delta t} - A_{2}^{t} \right)}{\Delta t} + \frac{(1 - \phi)\left( Q_{2}^{t} - Q_{1}^{t} \right) + \phi\left( Q_{2}^{t + \Delta t} - Q_{1}^{t + \Delta t} \right)}{L} = 0\f]   (4-7)
 
-![](hydraulics/media/media/image20.png "image20")
+![](hydraulics/media/media/hydraulics-image20.png "image20")
 
 **Figure 4-2 Space-time grid for kinematic wave analysis**
 
@@ -441,7 +441,7 @@ should be considered the more accurate one, with its greater reduction
 in peak flow due to the storage effect provided by the additional
 inertia and pressure terms included in the dynamic wave formulation.
 
-![](hydraulics/media/media/image21.png "image21")
+![](hydraulics/media/media/hydraulics-image21.png "image21")
 
 **Figure 4-3 Outflow hydrograph for example conduit**
 
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter5-CrossSection.md b/docs/manuals/reference/hydraulics/sections/Chapter5-CrossSection.md
index 5ccb00328..55ddfa2d5 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter5-CrossSection.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter5-CrossSection.md
@@ -117,7 +117,7 @@ user supplies values for 1/γ, the full depth *Y*full and the top wid
 when full *b* (see Figure 5-1). Note that the parabolic shape is a
 special case of this power function shape where 1/γ equals 2.
 
-![](hydraulics/media/media/image22.png "image22")
+![Figure 5-1 Power law cross section shape](figures/png/hydraulics_ch5_power_law.png)
 
 **Figure 5-1 Power law cross section shape**
 
@@ -224,11 +224,11 @@ are listed in Table 5-4.
 | Hydraulic Radius | \f[R_{full} = 0.25Y_{full}\f] |
 | Section Factor | \f[\Psi_{full} = A_{full}R_{full}^{2/3}\f] |
 
-![](hydraulics/media/media/image23.png "image23")
+![](hydraulics/media/media/hydraulics-image23.png "image23")
 
 **Figure 5-2 Geometric properties of a partly filled circular shape based on depth**
 
-![](hydraulics/media/media/image24.png "image24")
+![](hydraulics/media/media/hydraulics-image24.png "image24")
 
 **Figure 5-3 Geometric properties of a partly filled circular shape based on area**
 
@@ -250,7 +250,7 @@ accuracy, analytical functions are used to compute *Y,* *Ψ,* and *Ψ'*
 for areas below 4% of *A*full. They are described in the side bar
 entitled "*Analytical Functions for Circular Cross Sections*".
 
-![](hydraulics/media/media/figure-theta.png "figure-theta")
+![Definition sketch of the circular section: central angle θ](figures/png/hydraulics_ch5_circular_theta.png)
 
 > **Analytical Functions for Circular Cross Sections**
 > 
@@ -287,7 +287,7 @@ entitled "*Analytical Functions for Circular Cross Sections*".
 
 ### 5.1.4 Ellipsoid and Arch Shapes
 
-![](hydraulics/media/media/image25.png "image25")
+![Figure 5-4 Elliptical and arch pipe cross sectional shapes](figures/png/hydraulics_ch5_shapes_elliptical_arch.png)
 
 **Figure 5-4 Ellipsoid and arch pipe cross sectional shapes**
 
@@ -352,7 +352,7 @@ table using the following expression with *N* = 26:
 
 ### 5.1.5 Older Masonry Sewer Shapes
 
-![OldShapes.png](hydraulics/media/media/image27.png)
+![Figure 5-5 Masonry sewer shapes](figures/png/hydraulics_ch5_shapes_masonry.png)
 
 **Figure 5-5 Masonry sewer shapes**
 
@@ -410,12 +410,9 @@ circular, rectangular, and triangular sections. The formulas for
 computing their geometrical properties are presented in the following
 paragraphs.
 
-![](hydraulics/media/media/image28.png "image28")
+![Figure 5-6 Composite cross section shapes](figures/png/hydraulics_ch5_shapes_composite.png)
 
-Figure 5-6 shows four cross section shapes that are combinations of
-circular, rectangular, and triangular sections. The formulas for
-computing their geometrical properties are presented in the following
-paragraphs.
+**Figure 5-6 Composite cross section shapes**
 
 Sediment Filled Circular Shape
 
@@ -632,7 +629,7 @@ table of width versus height is shown in Figure 5-7.
 
 | | |
 |---|---|
-| ![ShapeCurve2.png](hydraulics/media/media/image29.png) | 
***Y/Y*full******W/Y*full******Y/Y*full******W/Y*full***
0.000.0000.560.928
0.080.6670.640.874
0.160.9300.720.798
0.241.0000.800.697
0.320.9970.880.567
0.400.9880.960.342
0.480.9671.000.000
 |
+| ![ShapeCurve2.png](hydraulics/media/media/hydraulics-image29.png) | 
***Y/Y*full******W/Y*full******Y/Y*full******W/Y*full***
0.000.0000.560.928
0.080.6670.640.874
0.160.9300.720.798
0.241.0000.800.697
0.320.9970.880.567
0.400.9880.960.342
0.480.9671.000.000
 |
 
 **Figure 5-7 A Shape Curve with a depth segment shown**
 
@@ -676,7 +673,7 @@ to evaluate *A(Ψ).*
 
 ## 5.3 Irregular Natural Channels
 
-![](hydraulics/media/media/image30.png "image30")
+![](hydraulics/media/media/hydraulics-image30.png "image30")
 
 **Figure 5-8 A natural channel transect**
 
@@ -731,7 +728,7 @@ After the end of the transect is reached the sum of the compound
 conductances is used along with the main channel roughness to find the
 hydraulic radius for the current depth increment.
 
-![](hydraulics/media/media/image31.png "image31")
+![](hydraulics/media/media/hydraulics-image31.png "image31")
 
 **Figure 5-9 A transect depth increment with three compound segments**
 
@@ -819,7 +816,7 @@ A two sided street cross-section adds a mirror image of the one-sided
 street to the right of the street crown with the same roadway, gutter,
 curb, and backing dimensions.
 
-![Street.png](hydraulics/media/media/image32.png)
+![Figure 5-10 A one-sided street cross-section](figures/png/hydraulics_ch5_street_section.png)
 
 **Figure 5-10 A one-sided street cross-section (not to scale)**
 
@@ -859,10 +856,10 @@ as shown in Table 5-14.
 
 | Shape | | Coefficients | Dimensions |
 |---|---|---|---|
-| Elliptical Cylinder | ![cylindrical.png](hydraulics/media/media/image33.png) | \f[a_{0} = \left( \frac{\pi}{4} \right)LW\f]
\f[a_{1} = a_{2} = 0\f] | *L* = major axis length
*W* = minor axis width |
-| Elliptical Paraboloid | ![paraboloid.png](hydraulics/media/media/image34.png) | \f[a_{0} = a_{2} = 0\f]
\f[a_{1} = (\frac{\pi}{4})\frac{LW}{H}\f] | *L* = major axis length
*W* = minor axis width
*H* = paraboloid height |
-| Elliptical Cone | ![ConicStorageShape.bmp](hydraulics/media/media/image35.png) | \f[a_{0} = \left( \frac{\pi}{4} \right)LW\f]
\f[a_{1} = \pi WZ\f]
\f[a_{2} = \pi(\frac{W}{L})Z^{2}\f] | *L* = bottom major axis length
*W* = bottom minor axis width
*Z* = side slope (run/rise) along major axis |
-| Rectangular Pyramid | ![PrismaticStorageShape.bmp](hydraulics/media/media/image36.png) | \f[a_{0} = LW\f]
\f[a_{1} = 2(L + W)Z\f]
\f[a_{2} = 4Z^{2}\f] | L = bottom length
W = bottom width
Z = wall slope (run/rise) (same for each face) |
+| Elliptical Cylinder | ![Elliptical cylinder](figures/png/hydraulics_ch5_storage_cylinder.png) | \f[a_{0} = \left( \frac{\pi}{4} \right)LW\f]
\f[a_{1} = a_{2} = 0\f] | *L* = major axis length
*W* = minor axis width |
+| Elliptical Paraboloid | ![Elliptical paraboloid](figures/png/hydraulics_ch5_storage_paraboloid.png) | \f[a_{0} = a_{2} = 0\f]
\f[a_{1} = (\frac{\pi}{4})\frac{LW}{H}\f] | *L* = major axis length
*W* = minor axis width
*H* = paraboloid height |
+| Elliptical Cone | ![Elliptical cone](figures/png/hydraulics_ch5_storage_cone.png) | \f[a_{0} = \left( \frac{\pi}{4} \right)LW\f]
\f[a_{1} = \pi WZ\f]
\f[a_{2} = \pi(\frac{W}{L})Z^{2}\f] | *L* = bottom major axis length
*W* = bottom minor axis width
*Z* = side slope (run/rise) along major axis |
+| Rectangular Pyramid | ![Rectangular pyramid](figures/png/hydraulics_ch5_storage_pyramid.png) | \f[a_{0} = LW\f]
\f[a_{1} = 2(L + W)Z\f]
\f[a_{2} = 4Z^{2}\f] | L = bottom length
W = bottom width
Z = wall slope (run/rise) (same for each face) |
 
 Dynamic wave analysis needs to know how volume *V* varies with depth
 *Y*. Integrating Equation 5-23 over depth yields:
@@ -983,9 +980,9 @@ be assumed that the unit has zero surface area at its base. The curve
 will be extrapolated outwards to meet the unit\'s maximum depth if need
 be.
 
-![StorageCurve2.png](hydraulics/media/media/image37.png)
+![StorageCurve2.png](hydraulics/media/media/hydraulics-image37.png)
 
-![](hydraulics/media/media/image38.png "image38")
+![](hydraulics/media/media/hydraulics-image38.png "image38")
 
 **Figure 5-11 Example of a storage curve and its section view**
 
@@ -1009,7 +1006,7 @@ first interpolated from the storage curve rather than converting the
 original area curve to a volume curve and interpolating directly from
 it.
 
-![](hydraulics/media/media/image39.png "image39")
+![](hydraulics/media/media/hydraulics-image39.png "image39")
 
 **Figure 5-12 Finding the volume at a given depth for a storage curve**
 
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter6-PumpsRegulators.md b/docs/manuals/reference/hydraulics/sections/Chapter6-PumpsRegulators.md
index 255d7e0f1..49fab9eb3 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter6-PumpsRegulators.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter6-PumpsRegulators.md
@@ -55,11 +55,11 @@ volumes.
 
 | **Type** | **Description** | **Image** |
 |---|---|---|
-| **Type1** | Consists of a series of constant flow rates that apply over a corresponding series of volume intervals at the pump's inlet node. | ![pump1.bmp](hydraulics/media/media/image40.png) |
-| **Type2** | Similar to a Type1 pump except that the fixed flow rate levels vary over a set of depth intervals at the pump's inlet node. | ![pump2.bmp](hydraulics/media/media/image41.png) |
-| **Type3** | A centrifugal pump characteristic curve at some nominal impeller speed represented in a piecewise linear fashion. Flow is a function of the head difference between the inlet and outlet nodes. | ![pump3.bmp](hydraulics/media/media/image42.png) |
-| **Type4** | A variable speed in-line pump where flow varies continuously with inlet node depth. | ![pump4.bmp](hydraulics/media/media/image43.png) |
-| **Type5** | A variable speed version of the Type3 pump where the head v. flow curve shifts position depending on the pump's speed setting. | ![Pump5.bmp](hydraulics/media/media/image44.png) |
+| **Type1** | Consists of a series of constant flow rates that apply over a corresponding series of volume intervals at the pump's inlet node. | ![Type 1 pump curve](figures/png/hydraulics_ch6_pump_type1.png) |
+| **Type2** | Similar to a Type1 pump except that the fixed flow rate levels vary over a set of depth intervals at the pump's inlet node. | ![Type 2 pump curve](figures/png/hydraulics_ch6_pump_type2.png) |
+| **Type3** | A centrifugal pump characteristic curve at some nominal impeller speed represented in a piecewise linear fashion. Flow is a function of the head difference between the inlet and outlet nodes. | ![Type 3 pump curve](figures/png/hydraulics_ch6_pump_type3.png) |
+| **Type4** | A variable speed in-line pump where flow varies continuously with inlet node depth. | ![Type 4 pump curve](figures/png/hydraulics_ch6_pump_type4.png) |
+| **Type5** | A variable speed version of the Type3 pump where the head v. flow curve shifts position depending on the pump's speed setting. | ![Type 5 pump curve](figures/png/hydraulics_ch6_pump_type5.png) |
 
 For Type1 and Type 2 curves, the curve is searched in step-wise fashion
 for the first point whose volume or depth exceeds the volume or depth at
@@ -516,7 +516,7 @@ The properties of a weir link include:
 Figure 6-4 shows the different shapes of transverse weirs modeled by
 SWMM. The only shape allowed for a side weir is rectangular.
 
-![](hydraulics/media/media/image49.png "image49")
+![](hydraulics/media/media/hydraulics-image49.png "image49")
 
Figure 6‑4 Transverse weir
 shapes

@@ -661,7 +661,7 @@ ft1/2/sec ) with head over the weir *H*W (in feet) present
 Brater and King (1976). The range of coefficients is rather small, from
 2.5 up to 2.8.
 
-> ![CWT.png](hydraulics/media/media/image50.png)
+> ![CWT.png](hydraulics/media/media/hydraulics-image50.png)
 
 **Figure 6‑5 Coefficient for triangular weirs (from Brater and King, 1976)**
 
@@ -734,7 +734,7 @@ weirs separate submergence factors are computed for the rectangular flow
 portion (*Q*R in Equation 6-20b with *n* = 3/2) and for the triangular
 flow portion (*Q*T in Equation 6-20c with *n* = 5/2).
 
-![](hydraulics/media/media/image51.png "image51")
+![](hydraulics/media/media/hydraulics-image51.png "image51")
 
Figure 6‑6 Definitions of submerged and
 surcharged weir flow

@@ -937,7 +937,7 @@ and *b* are user-supplied constants. The tabular rating curve consists
 of pairs of head (*H*e) and flow (*Q*) values for points that the user
 chooses to represent the shape of the outlet's rating curve.
 
-![](hydraulics/media/media/image52.png "image52")
+![](hydraulics/media/media/hydraulics-image52.png "image52")
 
Figure 6‑7 Rating curve for a vortex
 device compared to an orifice

diff --git a/docs/manuals/reference/hydraulics/sections/Chapter7-AdvancedFeatures.md b/docs/manuals/reference/hydraulics/sections/Chapter7-AdvancedFeatures.md
index 88e069741..7f0e12c1f 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter7-AdvancedFeatures.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter7-AdvancedFeatures.md
@@ -1254,7 +1254,7 @@ distance *W* from the curb or as depicted in Figure 7-11, the ratio of
 *Q*W to *Q*. For grates this distance is the width of the grate. For
 curb openings it is the width of the depressed gutter (if present).
 
-![CompositeStreetSection2.png](hydraulics/media/media/image71.png)
+![CompositeStreetSection2.png](figures/png/hydraulics_ch7_street_spread.png)
 
 **Figure 7-11 Street cross-section divided into gutter and roadway flow**
 
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md b/docs/manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md
index 2fa74d9f3..181a69e83 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md
@@ -47,8 +47,9 @@ inertial damping and normal-flow limiting.
 
 Several aspects of the analysis remain unchanged: the method is still
 one-dimensional, still uses the Preissmann slot for pressurized flow
-and therefore still cannot represent sub-atmospheric pipe pressure, and
-still treats a general junction as a stagnation volume (§8.6).
+under its default closure — which cannot represent sub-atmospheric pipe
+pressure; the optional TPA closure of §8.4.5 can — and still treats a
+general junction as a stagnation volume (§8.6).
 
 ## 8.2 Governing equations
 
@@ -81,6 +82,15 @@ placement of terms is what gives the scheme its conservation property.
 
 ## 8.3 The computational mesh
 
+Figure 8-1 contrasts the node–link picture of @ref hydraulics_ref_ch3_dynamic_wave "Chapter 3" — one
+momentum balance per conduit, depth known only at the nodes — with the
+spatially explicit picture of this chapter, in which the conduit itself
+is discretised and profiles, bores and jumps are resolved inside it.
+
+![Figure 8-1](figures/png/hydraulics_ch8_cell_layout.png)
+
+*Figure 8-1 Node–link routing against the finite-volume view: one momentum balance per conduit versus a conduit cut into cells with the water surface resolved inside it*
+
 The mesh is internal numerical discretization. It creates no named
 objects, appears in no report, and is invisible to the model's
 topology. Each conduit is divided into
@@ -109,7 +119,7 @@ deviation from the dynamic wave solver against cells per conduit:
 
 Four cells is a practical compromise rather than a converged result: it
 more than halves the one-cell error for about twice the cost, while
-further refinement improves accuracy more slowly than it adds cost. §8.10 gives the same comparison against \f$\Delta x\f$ targets. Set
+further refinement improves accuracy more slowly than it adds cost. Set
 `FV_CELL_LENGTH`, or raise `FV_MIN_CELLS`, whenever peak flows or
 in-conduit profiles matter.
 
@@ -149,6 +159,19 @@ The default of 100 ft/s is the same order the dynamic wave solver's
 5 % of the section's maximum width so it can never become the dominant
 storage and understate a surge.
 
+Two practical consequences of (8-5) and the cap, measurable through the
+diagnostics of §8.7.1: the slot's share of stored volume scales as
+\f$1/c_{slot}^{2}\f$, and requests **below** the cap-implied celerity
+\f$\sqrt{g A_{full}/(0.05\,W_{max})}\f$ are inert — every such value
+produces byte-identical geometry (WARNING 108 reports the override).
+The cap-implied celerity is shape-dependent, since \f$A_{full}/W_{max}\f$
+varies by a factor of 2–3 across the closed-section catalog: for a
+circular pipe it is reached at \f$c \approx 22.5\sqrt{D}\f$ ft/s
+(≈ 39 ft/s at D = 3 ft, ≈ 67 ft/s at D = 9 ft). Because the slot also
+absorbs part of the friction grade while engaged, steady full-bore head
+loss converges on the Manning value from below as the celerity rises
+(§8.7.1) — a low celerity understates surcharge and head loss together.
+
 ### 8.4.2 The tapered slot mouth
 
 The slot does not appear abruptly at the crown. It opens smoothly over
@@ -167,6 +190,16 @@ Riemann solver's wave-speed estimates; the taper is what prevents both.
 The area is the exact integral of (8-6), so \f$A\f$ and \f$T\f$ remain a
 consistent pair through the transition.
 
+Figure 8-2 draws the closure for a 3 ft circular pipe from the engine's
+own geometry: the mouth opens across \f$[y_c,\,y_{full}]\f$ and the
+celerity climbs smoothly to \f$c_{slot}\f$ instead of diverging where the
+section's width collapses at the crown. The 30 ft/s request lies below
+the cap-implied celerity of §8.4.1 and is inert.
+
+![Figure 8-2](figures/png/hydraulics_ch8_slot_closure.png)
+
+*Figure 8-2 The tapered static slot for a 3 ft circular pipe: top width and celerity across the crown at four slot celerities*
+
 Open sections carry no crown and no taper: above `y_full` the section
 simply continues with vertical walls of width \f$w_{max}\f$, which is one
 code path with the closed case and keeps the celerity physical.
@@ -179,6 +212,15 @@ used here rather than the Dynamic Preissmann Slot: a relaxing slot
 makes bore speed depend on relaxation history, which would destroy the
 Rankine–Hugoniot front speed the method exists to get right.
 
+That argument rules out *relaxing* closures — ones whose pressurized
+celerity evolves with pressurization history, like the dynamic slot —
+and it is worth being precise that it does **not** rule out the TPA
+closure of §8.4.5. TPA's pressurized celerity is the same constant
+\f$a\f$ as the static slot's, so the Rankine–Hugoniot speed of a filling
+bore is unaffected by its history flag; only the \f$\Delta A < 0\f$
+branch — the sub-atmospheric regime, which the static slot handles
+unphysically in any case — consults the flag at all.
+
 ### 8.4.3 Inverting the closure
 
 The solver carries \f$A\f$ and derives the free surface as
@@ -255,9 +297,281 @@ and `h_tbl` members of @ref openswmm::fv::FvGeometry
 (`src/engine/hydraulics/fv/NetworkMeshData.hpp`, `kI1Samples` = 129),
 built in `src/engine/hydraulics/fv/NetworkMeshBuilder.cpp`.
 
+### 8.4.4 The implicit pressurized head update
+
+> **Experimental.** The option and the solver described here are fully
+> functional and gated, but the pass cannot yet compose with the
+> local-time-stepping macro cycle (§8.5.6) — tiering stands down on any
+> substep where the solve engages — and the slot program's next round
+> (R2b) is expected to revise it. The GUI surfaces it as an explicitly
+> experimental checkbox on the Routing & Hydraulics page.
+
+`FV_PRESSURIZED_IMPLICIT YES` removes the slot's wave from the explicit
+time-step law. Above the taper band the closure (8-4) is exactly linear
+in head, so the acoustic pair — slot storage \f$T_{slot}\,\partial H/\partial t\f$
+against the pressure gradient \f$gA\,\partial H/\partial x\f$ — is a
+linear diffusion system in \f$H\f$ that can be integrated implicitly
+(\f$\theta = 1\f$), unconditionally stably. Each substep, every closed-
+section cell at or above the band entry \f$y_c\f$ forms, with its
+like neighbours, a symmetric positive-definite head system
+
+| | | | |
+|---|---|---|---|
+| \f[\frac{T_i\,\Delta x_i}{\Delta t}H_i + \sum_f C_f\,(H_i - H_{nbr}) = \mathrm{RHS}_i,\qquad C_f = \frac{\alpha_f\,\Delta t\,g\,\hat A_f}{L_f},\quad \alpha_f = \frac{1}{1+\Delta t\,\gamma_f}\f] | | (8-24a) | |
+
+solved directly — the Thomas algorithm along pipe chains, Jacobi-
+preconditioned conjugate gradients where a folded junction has three or
+more branches. The solve is a **flux predictor**: the back-substituted
+face discharges overwrite the face mass fluxes, and the ordinary cell
+and node updates then integrate them unchanged, so mass conservation,
+step rejection, hot start and reporting are structurally untouched.
+Membership is a pure function of the instantaneous state — no flags, no
+memory — so the hysteresis and hot-start properties of §8.4 are
+inherited rather than re-proven. (Under the TPA closure of §8.4.5
+membership is instead the regime flag, which is fixed within a substep;
+see that section for the interaction.)
+
+Three details carry the accuracy claims. First, the conductance area
+\f$\hat A_f\f$ and the friction coefficient \f$\gamma_f\f$ use the
+**conveyance** area \f$\min(A, A(y_{full}))\f$ — the slot stores volume
+but must not conduct, the same distinction the dynamic wave solver
+draws when it strips the slot from `conveyArea`. At steady state
+(8-24a) then reduces per face to \f$\Delta H/L = -S_f\f$ exactly, which
+makes full-bore head loss equal to the friction law and **independent
+of `FV_SLOT_CELERITY`** — where the explicit scheme understates it at
+low celerity (§8.4.1). Second, pressurized algebraic junctions whose
+every face joins two pressurized states are folded into the system as
+unknown rows (a lagged junction head would recreate the very feedback
+stiffness the solve removes); a solved head that violates the node's
+rim or invert is demoted to a Dirichlet row at the clamp and the
+imbalance books through the carry ledger into the same flooding and
+ponding paths as always. Third, **transition faces** — one side
+pressurized, one free — stay entirely explicit, Godunov flux and
+Courant bound alike: filling bores keep their shock-captured physics at
+a front-resolving step, and the step census drops the celerity of a
+pressurized side only where the face is covered by the solve. A fully
+pressurized network therefore runs at the advective bound — the slot
+width becomes a pure accuracy parameter with no runtime price — while a
+network that never pressurizes is bit-identical with the option on.
+
+The pass lives in `src/engine/hydraulics/fv/PressurizedHeadSolver.{hpp,cpp}`
+and runs on the CPU solver's global path (a device backend request is
+overridden while the option is on; composing the solve with the local-
+time-stepping macro cycle is future work). Gates:
+`tests/unit/engine/test_fv_pressurized_implicit.cpp`.
+
+### 8.4.5 The two-component pressure approach (`FV_PRESSURE_CLOSURE TPA`)
+
+> **Experimental.** Fully functional and gated, selected with
+> `FV_PRESSURE_CLOSURE TPA`; the default `SLOT` preserves the closure of
+> §8.4.1–§8.4.2 bit for bit. One known limitation is pinned in-tree
+> (high-celerity filling, below).
+
+The slot closure is monotone: a head below the crown *is* a free
+surface, so a full pipe carrying pressure below atmospheric has no
+representation — a sealed reach hit by a rapid downsurge spuriously
+reverts to free-surface geometry instead of holding vacuum. The
+two-component pressure approach of Vasconcelos, Wright and Roe (2006)
+lifts exactly this restriction: pressure is decomposed into a
+hydrostatic component, present in both regimes, and a surcharge
+component \f$h_s\f$ carried only by a pressurized cell, and \f$h_s\f$ may
+be negative — the pipe stays full, at sub-atmospheric pressure, until
+air can physically reach it.
+
+**Requirements.** TPA applies to **closed conduits only**: a cell whose
+cross-section is open never latches (`updateTpaFlags` clears its flag
+unconditionally) and evaluates the free-surface closure verbatim, so
+mixed networks need no special arrangement — the option is inert
+outside closed pipe. Eligibility needs nothing beyond the closed
+section's own full-flow properties, which every closed shape already
+carries for the SLOT closure: \f$A_{crown}\f$, \f$y_{full}\f$, and the
+slot width \f$T_{slot} = gA_{full}/a^{2}\f$. Setup is `FLOW_ROUTING FV`
+with `FV_PRESSURE_CLOSURE TPA`; the acoustic celerity \f$a\f$ comes
+from `FV_SLOT_CELERITY` (§8.4.1). A node is sealed against the venting
+sweep by a positive `SURCHARGE_DEPTH` (a bolted cover); virtual
+junctions are sealed by construction (§8.6.2). Sub-atmospheric heads
+reach the `.out` file **only** under `REPORT_SIGNED_HEADS YES` —
+without it the physics is computed but invisible, the HEAD field
+flooring at the invert. The validated configuration for the
+sub-atmospheric class is the explicit scheme with forward-Euler time
+integration or the implicit acoustic solve (see the scoring below);
+`FV_TIME_INTEGRATION RK2` alters the stability landscape in both
+directions and is not a safe default with TPA (see the known
+limitation).
+
+**The closure pair.** The observation that makes TPA cheap here is that
+the existing slot line *is* the TPA pressurized branch for
+\f$\Delta A = A - A_{crown} \geq 0\f$. TPA extends the same line to both
+signs of \f$\Delta A\f$:
+
+| | | | |
+|---|---|---|---|
+| \f[h(A) = y_{full} + \frac{A - A_{crown}}{T_{slot}}, \qquad h_{s} = h - y_{full} \text{ of either sign}\f] | | (8-34) | |
+| \f[I_{1}(h) = I_{1,crown} + A_{crown}\,\left( h - y_{full} \right)\f] | | (8-35) | |
+
+Equation (8-35) is the paper's Eq. (12b): the pressurized first moment
+drops the \f$\tfrac{1}{2}T_{slot}(h - y_{full})^{2}\f$ term the SLOT
+closure keeps — that term is the slot's own numerical storage pressure,
+not part of the physical decomposition. Free-surface cells evaluate the
+table closure of §8.4.2 **unchanged, including the tapered slot mouth**;
+the two branches are continuous at \f$A = A_{crown}\f$. The pressurized
+celerity is the constant \f$a\f$, the hydraulic radius stays frozen at
+\f$r_{full}\f$, and the pressurized inverse \f$h(A)\f$ is closed-form.
+`FV_SLOT_CELERITY` doubles as the TPA acoustic celerity \f$a\f$ — it is
+the same physical dial, since \f$T_{slot} = gA_{full}/a^{2}\f$ is derived
+from it under either closure.
+
+**The regime flag is physical air-pathway history, not numerical
+relaxation.** Which branch a cell evaluates is decided by a per-cell
+flag recording whether air can reach the cell — the paper's governing
+rule. Its transitions, applied once per substep outside the flux loops:
+
+- **Entry** is unconditional at \f$A \geq A_{crown}\f$ — the cell fills
+  through the taper.
+- **Exit** requires \f$\Delta A \leq 0\f$ past a small hysteresis band
+  (\f$h_s\f$ below about \f$-10^{-4}\f$ ft, so the flag cannot chatter at
+  \f$\Delta A \approx 0\f$) **and** atmosphere contact this step, under
+  the venting rule below.
+- **Column separation** exits unconditionally when \f$h_s\f$ falls below
+  −30 ft — about one atmosphere of water column, past which the column
+  separates and a vapor cavity forms. Cavity dynamics are two-phase and
+  out of scope (the paper's own limitation); the floor bounds the
+  representable vacuum instead.
+- **Every transition refreshes the cell's derived state from the new
+  regime's closure at its current area.** The stored depth belongs to
+  the old regime: without the refresh, a cell that exits deep in vacuum
+  carries its slot-line depth — of order −200 ft at study celerities —
+  through the whole substep's reconstruction, and the resulting
+  free-surface gradients pump a reflected filling surge to NaN (the
+  measured failure class on the rapid-fill validation deck: 5–15 flag
+  flips per substep with heads reaching 2485 ft before the run died).
+  With the refresh the deck completes and bore arrival matches the SLOT
+  closure columns exactly, at 10.45 s.
+
+**Venting.** A cell has atmosphere contact when one of its faces
+touches an *unsealed* node — no `SURCHARGE_DEPTH` seal — whose water
+level at that face stands **below the pipe crown**, or a free-surface
+neighbouring cell whose surface stands below the shared crown. The
+submergence check is load-bearing: air cannot enter through an opening
+that is itself under water, and without the check every sealed reach
+unzips from its vented ends (measured — the sealed-siphon fixture
+drained and then diverged). Two alternative rules were measured and
+rejected rather than assumed away: the paper's literal unconditional
+venting of the regime-transition interface unzips a submerged
+pressurized leg through a chain of momentary exits, and an
+entry-at-\f$A_{full}\f$ island rule broke the V-shaped filling case.
+Virtual junctions need no special casing and get the correct physics by
+construction: a virtual junction is spliced out of the mesh (§8.6.2),
+so it can never seed the venting sweep — a splice has no atmosphere
+contact — while contact still propagates across it, because cell chains
+span the splice.
+
+**Interaction with `FV_PRESSURIZED_IMPLICIT` (§8.4.4).** The pressurized
+branch (8-34) is the same linear closure the implicit solve exploits, so
+the two options compose, with four TPA-specific rules. Membership in the
+implicit set *is* the regime flag — a latched cell with \f$h_s < 0\f$
+sits below the crown yet is exactly the stiff-acoustic case the solve
+exists for — and since the flag is fixed within a substep, the SPD
+structure is unchanged. A sealed node standing against a flagged
+interior cell presents a *pressurized* ghost even though its head is
+below the crown. The Dirichlet floor applied to a folded junction row
+extends below the node invert by the column-separation bound, because a
+solved sub-atmospheric head is now legal. And a flagged cell's storage
+row uses the regime's own width \f$T_{slot}\f$ at *any* head, never the
+free-surface table width — the measured failure without this rule is
+instructive: as a settle transient drives cells across the crown, the
+table width swings five orders of magnitude between the clamped
+zero-width branch and the free-surface branch, and the apex cell's head
+reached 877,208 ft within 50 substeps. With the rules in place,
+implicit × TPA closes continuity at 0.000 %. An earlier probe recorded
+the implicit path under-tracking the explicit vacuum at a crest; the
+Phase 6 scoring against the digitized laboratory record did not
+reproduce that gap — the two land within a millimetre of each other at
+the crest minimum (0.1037 m implicit against 0.1035 m explicit, NSE
+0.9960 against 0.9955 on the 14.1 m pressure trace) — so both are
+validated configurations for the sub-atmospheric class.
+
+**Hot start.** The regime flags are cleared on cold start *and* on
+restore from a hot start file. A restored run whose reach was
+pressurized re-derives the flags from the state within one step; the
+worst case is a single spurious re-pressurization step.
+
+**Reporting.** The `.out` format floors node depth at zero for legacy
+bit-parity, so sub-atmospheric heads are invisible in it by default.
+`REPORT_SIGNED_HEADS YES` publishes the true signed piezometric head in
+the `.out` HEAD field (both solvers; DEPTH stays floored; the default
+NO keeps bit parity). The measured payoff on the negative-pressure
+siphon validation case: a minimum crest head of +0.1035 m — 0.0398 m
+below the crest invert of 0.1433 m — in the output file, where every
+slot-closure column floors at the invert (−0.0003 m, the float32 noise
+of the legacy HEAD field). The case is scored over the 40 s the deck
+runs, which is where its own header puts the boundary of the physics
+the model contains; the vacuum is still deepening monotonically when
+the run ends, so this figure is a lower bound on the closure's reach,
+not a plateau. Phase 6 of the companion study scored this trace
+against the record digitized from the source figures: NSE 0.9955
+(explicit Euler) and 0.9960 (implicit) on the 14.1 m pressure station,
+at an RMSE of ~4 mm — below the source figure's own ±8 mm resolution —
+while the best slot-closure column scores 0.55 and every dynamic-wave
+column goes negative. The sub-atmospheric decline is tracked to within
+what the published figure can resolve; this is the closure's measured
+payoff, and it is only observable with `REPORT_SIGNED_HEADS YES` set.
+
+**Known limitation: high-celerity filling.** At \f$a\f$ = 150 m/s the
+rapid-fill validation case diverges at the reflected return surge — a
+*temporal* odd–even pressure/vacuum oscillation inside the flagged
+region, at a correctly acoustic-bounded step. This is the paper's own
+high-celerity post-shock frontier: their Fig. 7 discussion needs a
+[0.05, 0.90, 0.05] conservative filter already at \f$a\f$ = 100 m/s. A
+flagged-neighbourhood-local, exactly conservative filter of that form
+was implemented, measured — it does not rescue the case at either the
+paper's weight or five times it, because spatial smoothing cannot damp
+a temporal odd–even mode — and reverted. Two further measured results
+bound the frontier. First, the Euler front is knife-edge marginal, not
+threshold-limited: a \f$k_{3}\f$ of \f$10^{-6}\f$ (physically nothing)
+or a 0.002 % change in `FV_SLOT_CELERITY` flips a marginal filling
+case between completing and diverging, so apparent "stability
+thresholds" in that neighbourhood are floating-point luck. Second,
+two-stage RK2 (Heun) time integration damps the temporal mode and
+completes the pinned filling case
+(`FvTpa.Rk2CompletesWhereEulerFillingPinDiverges`), **but it is not a
+remedy**: on the negative-pressure siphon case — the physics TPA
+exists for — RK2 destroys the solution (NSE −6.6×10¹⁰ against 0.996
+under Euler or implicit), and Phase 6 found RK2 completions can hide
+silent divergence: a run that spikes to thousands of feet mid-record
+and returns exits cleanly, with no `ERROR` line and plausible early
+metrics. No single (closure, integrator) pairing measured to date is
+stable across all four validation decks; the integrator is a
+per-problem choice, and a completed run's status line is not evidence
+of a healthy trace — inspect the reported extrema.
+
+**The Euler filling divergence itself has been removed.** It was pinned
+in-tree for months as a known issue; on 2026-09-12 the slot/free-surface
+wave-speed bound of §8.5.3 closed it. Davis's symmetric estimate had
+carried the acoustic celerity into the wave entering the *free-surface*
+side of a pressurization front; bounding that wave by the
+Rankine–Hugoniot bore speed instead removes the temporal mode outright.
+The fixture now completes at 0.000 % continuity at \f$a\f$ = 150, 300,
+600, 1000 and 3000 m/s, and the gate is the positive test
+`FvTpa.HighCelerityFillingCompletes`. The hybrid flux of Vasconcelos,
+Wright and Roe (2009), recorded as the contingency for this front, is
+therefore no longer required for it (@ref hydraulics_ref_ch10_planned
+"Chapter 10" §10.7).
+
+**Implementation.** The pressurized-branch kernels are
+`tpaDepthOfArea`, `tpaAreaOfDepth` and `tpaI1OfDepth` in
+`src/engine/hydraulics/fv/FvKernels.hpp`; the flag transitions, venting
+sweep and regime refresh are
+@ref openswmm::fv::ExplicitFvSolver::updateTpaFlags; the implicit-set
+rules are `cellPressurized` and `ghostPressurized` in
+`src/engine/hydraulics/fv/PressurizedHeadSolver.hpp`. Gates:
+`tests/unit/engine/test_fv_tpa_closure.cpp`. The dynamic wave solver
+carries its own port of the approach as `SURCHARGE_METHOD TPA`
+(@ref hydraulics_ref_ch3_dynamic_wave "Chapter 3").
+
 ## 8.5 Numerical scheme
 
-### 8.5.1 Face reconstruction
+### 8.5.1 Face reconstruction {#hydraulics_ref_ch8_face_reconstruction}
 
 Cell states are reconstructed at each interface using the hydrostatic
 reconstruction of Audusse et al. (2004):
@@ -287,7 +601,7 @@ slope breaks, adverse slopes and while pressurized. This is the
 "C-property", and it holds regardless of any quadrature error in the
 \f$I_1\f$ table, since only single-valuedness is required.
 
-### 8.5.3 Interface flux
+### 8.5.3 Interface flux {#hydraulics_ref_ch8_interface_flux}
 
 The system \f$\mathbf{U} = [A,\ Q]^{T}\f$ is \f$2 \times 2\f$ with two
 genuinely nonlinear fields and no middle wave, so the interface flux is
@@ -316,6 +630,13 @@ the flux is identically zero. No entropy fix is applied: the Davis
 estimates already bound the full wave fan, so a sonic rarefaction
 cannot collapse onto a single-state flux.
 
+Figure 8-3 sketches the fan the estimates bound, for a wet–wet face and
+for a dry right cell.
+
+![Figure 8-3](figures/png/hydraulics_ch8_hll_fan.png)
+
+*Figure 8-3 The Riemann fan at a face: HLL signal speeds for a wet–wet face and the rarefaction-tail estimate at a dry bed*
+
 The hydrodynamic flux is deliberately HLL rather than an Euler-style
 HLLC star-state construction. For the 2 × 2 system the two constructions
 should coincide, and applying the three-wave star states to the
@@ -353,7 +674,7 @@ baseline). It has no effect on the hydraulics.
 @ref openswmm::fv::ExplicitFvSolver::computeFaceFlux in
 `src/engine/hydraulics/fv/ExplicitFvSolver.cpp`.
 
-### 8.5.4 Friction, local losses and positivity
+### 8.5.4 Friction, local losses and positivity {#hydraulics_ref_ch8_friction_positivity}
 
 Manning friction is integrated semi-implicitly, so it imposes no time
 step restriction of its own:
@@ -393,6 +714,63 @@ equivalent friction slope and integrated in the same implicit form:
 so calibrated models carry over unchanged, and \f$K = 0\f$ leaves \f$Q\f$
 bit-unaffected.
 
+#### Unsteady friction (`UNSTEADY_FRICTION VITKOVSKY`)
+
+Steady-friction-only mixed-flow models have a documented failure mode:
+reproducing observed transient damping requires an unphysical Manning
+\f$n\f$ (Pinto, Vasconcelos and Soares (2025) needed \f$n\f$ = 0.013 for an
+acrylic pipe with unsteady friction off). Their remedy — a modified
+Vítkovský et al. (2000) instantaneous-acceleration term with a
+Brunone-type coefficient \f$k_3\f$ — is available in both solvers as an
+option orthogonal to the pressurization closure. The total friction
+slope becomes \f$S_f = S_{fs} + S_{fu}\f$ with the steady term unchanged
+and
+
+| | | | |
+|---|---|---|---|
+| \f[S_{fu} = \frac{k_{3}}{g}\left( \frac{\partial V}{\partial t} + c\,\mathrm{sgn}(V)\left\lvert \frac{\partial V}{\partial x} \right\rvert \right)\f] | | (8-36) | |
+
+The celerity \f$c\f$ is **regime-dependent** — the paper's one
+modification to Vítkovský, and exactly the celerity this solver already
+computes: \f$\sqrt{gA/T}\f$ for a free-surface cell, the constant
+acoustic \f$a\f$ for a pressurized one (under the TPA closure,
+"pressurized" is the regime flag at *any* head; under SLOT,
+\f$h \geq y_{crown}\f$).
+
+The term is split by stiffness. The local-acceleration half folds into
+the update implicitly, like (8-13) — unconditionally stable, no new
+prognostic state, so hot start and step rollback are untouched. The
+convective half enters as an explicit source using neighbour-cell
+velocities within the conduit chain (one-sided at chain ends), gathered
+from a consistent old-state snapshot. Two guards bound it, both
+measured rather than assumed: a velocity dead-band of 0.01 ft/s — below
+it the implicit fold is pure added inertia and, applied to the mm/s
+settling ripple of a storage-coupled pool, it sustained noise that
+steady friction was correctly killing (0.004 → 0.011 cfs); with the
+dead-band a discretely-at-rest deck is bit-identical — and a per-substep
+clamp of the combined change to half the incoming momentum, since the
+paper reports instability for \f$k_3 \gtrsim 0.02\f$ with no such guard.
+
+Set expectations from the mechanism: a uniform-velocity slosh shows
+**no** net damping (\f$\partial V/\partial x \approx 0\f$ leaves pure
+added inertia; measured late amplitude 0.507 against 0.487 without the
+option), while a valve-closure transient — sharp \f$\partial V/\partial t\f$
+with a wave-front \f$\partial V/\partial x\f$ — damps at
+\f$k_3\f$ = 0.02 as the paper reports.
+
+The option surface is shared with the dynamic wave solver
+(@ref hydraulics_ref_ch3_dynamic_wave "Chapter 3"):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `UNSTEADY_FRICTION` | `NONE` | `NONE` or `VITKOVSKY`. `NONE` is bit-inert in both solvers. |
+| `UF_K3` | 0.015 | Brunone-type coefficient \f$k_3\f$, used only when the method is not `NONE`. Paper-calibrated range 0.005–0.020, swept to 0.045. |
+
+**Implementation.** @ref openswmm::fv::kernels::ufUpdate in
+`src/engine/hydraulics/fv/FvKernels.hpp`, with the convective gradients
+gathered by `ExplicitFvSolver::computeUfGradients`. Gates:
+`tests/unit/engine/test_fv_unsteady_friction.cpp`.
+
 Before the update is applied, each control volume's total outgoing mass
 flux is compared with the volume it holds, and every outgoing face flux
 of an over-drafted volume is scaled by
@@ -416,7 +794,7 @@ property either.
 `src/engine/hydraulics/HydClosureKernels.hpp`; the outflow scan is
 @ref openswmm::fv::ExplicitFvSolver::limitPositivity.
 
-### 8.5.5 Time stepping
+### 8.5.5 Time stepping {#hydraulics_ref_ch8_time_stepping}
 
 The solver substeps internally to fill each routing step. The routing
 step therefore serves as a reporting and forcing cadence rather than a
@@ -461,7 +839,7 @@ stability arguments hold. `RK2` and local time stepping are mutually
 exclusive — tiering gives different volumes different steps, so the two
 stages would be averaging states that never shared one.
 
-### 8.5.6 Local time stepping
+### 8.5.6 Local time stepping {#hydraulics_ref_ch8_lts}
 
 Condition (8-14) is *local*, but a single global substep applies the
 smallest value found anywhere to every cell in the model. In a sewer
@@ -485,6 +863,13 @@ sides. One **macro cycle** is \f$2^{K-1}\f$ base substeps, where \f$K\f$ is the
 tier count; a tier-\f$k\f$ volume fires every \f$2^{k}\f$ of them, so every
 volume advances the same total span.
 
+Figure 8-4 lays out the tiers, the macro cycle and the flux bookkeeping
+at a tier interface.
+
+![Figure 8-4](figures/png/hydraulics_ch8_lts_ladder.png)
+
+*Figure 8-4 Local time stepping: power-of-two tiers, the macro cycle and flux accumulation across a tier interface*
+
 Three properties make this a scheduling change rather than a different
 scheme:
 
@@ -549,9 +934,10 @@ separate and the bookkeeping is a small net cost, which is why the tier
 assignment is cached across cycles and refreshed only when the census
 shows the model's stiffness has moved.
 
-Figure 8-1 assembles the pieces of Sections 8.5.5 and 8.5.6 into the
+Figure 8-5 assembles the pieces of Sections 8.5.5 and 8.5.6 into the
 substep workflow the solver executes for every routing step.
 
+
 
 flowchart TD
     A[Routing step begins - forcing and boundary states set] --> B[CFL census over all faces, including boundary ghost states]
@@ -571,8 +957,19 @@ flowchart TD
     M -- no --> B
     M -- yes --> N[Report, couple nodes, advance]
 

-
-*Figure 8-1 Substep workflow of the explicit finite-volume solver,
+

+@ref hydraulics_ref_ch8_time_stepping "8.5.5 Time stepping: the CFL census"
+@ref hydraulics_ref_ch8_time_stepping "8.5.5 Time stepping: the base step"
+@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping"
+@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping: tiers"
+@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping: the macro cycle"
+@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping: windows and accumulators"
+@ref hydraulics_ref_ch8_friction_positivity "8.5.4 Friction, local losses and positivity"
+@ref hydraulics_ref_ch8_time_stepping "8.5.5 Time stepping: the post-step census"
+@ref hydraulics_ref_ch8_network_coupling "8.6 Network coupling"
+

+
+*Figure 8-5 Substep workflow of the explicit finite-volume solver,
 including the post-step census retry and local time stepping (rendered
 diagram)*
 
@@ -613,7 +1010,7 @@ path — which is what makes `FV_ORDER 2` safe to leave on: on an
 unresolved long conduit it reproduces the first-order answer rather than
 producing a wrong one.
 
-### 8.5.8 Wetting and drying
+### 8.5.8 Wetting and drying {#hydraulics_ref_ch8_wetting_drying}
 
 Wet/dry handling is distributed through the scheme rather than
 implemented as a separate front-tracking step. Every rule below acts on
@@ -649,7 +1046,7 @@ celerity and \f$I_1\f$ — and the wave-speed estimates switch to the
 dry-bed forms (8-23). Two dry sides return an exactly zero flux. An
 emerged bank, a bed step whose top stands above the neighbouring water
 surface, is therefore a wall by construction: \f$z^{*}\f$ exceeds \f$\eta\f$ on
-both sides and both reconstructed depths vanish. Figure 8-3 sketches
+both sides and both reconstructed depths vanish. Figure 8-7 sketches
 both configurations.
 
 **Front propagation and positivity.** A wetting front advances at most
@@ -696,9 +1093,10 @@ front half a cell downstream. The volume actually seeded is published
 back to the link before the mass balance opens, so the run's
 initial-storage ledger matches the state the solver integrates.
 
-Figure 8-2 assembles the face-level logic — wet/dry states, gates,
+Figure 8-6 assembles the face-level logic — wet/dry states, gates,
 culvert caps and the positivity scan — into one workflow.
 
+
 
 flowchart TD
     A[Face taken from the active list] --> B[Resolve side beds and z* = max of zL and zR]
@@ -720,23 +1118,25 @@ flowchart TD
     M --> O[Positivity scan over all volumes: scale outgoing fluxes of over-drafted volumes]
     O --> P[Identical scaled flux updates both incident volumes]
 

-
-*Figure 8-2 Wet/dry and exception handling in one face flux evaluation
+

+@ref hydraulics_ref_ch8_face_reconstruction "8.5.1 Face reconstruction"
+@ref hydraulics_ref_ch8_face_reconstruction "8.5.1 Face reconstruction: hydrostatic states"
+@ref hydraulics_ref_ch8_wetting_drying "8.5.8 Wetting and drying"
+@ref hydraulics_ref_ch8_interface_flux "8.5.3 Interface flux: dry-bed signal speeds"
+@ref hydraulics_ref_ch8_interface_flux "8.5.3 Interface flux: Davis signal speeds"
+@ref hydraulics_ref_ch8_interface_flux "8.5.3 Interface flux: HLL and the contact speed"
+@ref hydraulics_ref_ch8_structures "8.6.3 Outfalls, structures and lateral inflow: flap gates"
+@ref hydraulics_ref_ch8_culvert_inlet "8.6.4 Culvert inlet control"
+@ref hydraulics_ref_ch8_friction_positivity "8.5.4 Positivity"
+

+
+*Figure 8-6 Wet/dry and exception handling in one face flux evaluation
 (rendered diagram)*
 
-
-![Figure 8-3](figure8-3-placeholder.png)
+![Figure 8-7](figures/png/hydraulics_ch8_hydrostatic_reconstruction.png)
 
-*Figure 8-3 Hydrostatic reconstruction at a wet/dry front: an advancing
-front (left) and an emerged bank acting as a wall (right) (placeholder)*
+*Figure 8-7 Hydrostatic reconstruction at a wet/dry front: an advancing
+front (left) and an emerged bank acting as a wall (right)*
 
 **Implementation.** The constants are `kDryDepth`, `kDryArea` and
 `kEtaDeadband` in `src/engine/hydraulics/fv/FvKernels.hpp`; the dry-bed
@@ -796,7 +1196,7 @@ One global (untiered) substep executes the following sequence:
 5. Reconstruct second-order slopes of \f$(\eta, v)\f$ under `FV_ORDER 2`.
 6. Evaluate the face fluxes over the active list — hydrostatic
    reconstruction, HLL flux, flap gates, culvert caps, Audusse
-   corrections (Figure 8-2). This loop is the parallel region: it runs
+   corrections (Figure 8-6). This loop is the parallel region: it runs
    under OpenMP when at least 4096 faces are active.
 7. Apply the semi-implicit node relaxation (§8.6.5), which rewrites the
    boundary-face mass fluxes. It precedes the limiter so the limiter
@@ -849,54 +1249,106 @@ is @ref openswmm::fv::ExplicitFvSolver::takeSubstep and
 in `src/engine/hydraulics/fv/FvKernels.hpp` behind the
 `OPENSWMM_KERNEL_FN` marker.
 
-## 8.6 Network coupling
+## 8.6 Network coupling {#hydraulics_ref_ch8_network_coupling}
 
 ### 8.6.1 Regular junctions and storage units
 
-Nodes are zero-dimensional volumes advanced with the same substep. The
-end cell of each conduit exchanges with its node through a ghost state
-built from the node head, and that exchange goes through the *same*
-Riemann solver as an interior face. Wave reflection off the node,
-choking, supercritical approach flow and the surcharge transition are
-therefore resolved by the same shock-capturing machinery as the
-interior, rather than by a \f$dQ/dH\f$ linearization.
+A node is where conduit control volumes meet. The end cell of each
+conduit exchanges with its node through a ghost state built from the
+node head, and that exchange goes through the *same* Riemann solver as
+an interior face. Wave reflection off the node, choking, supercritical
+approach flow and the surcharge transition are therefore resolved by the
+same shock-capturing machinery as the interior, rather than by a
+\f$dQ/dH\f$ linearization.
+
+What differs from node to node is where that head comes from. Three
+models are in use, chosen automatically from the node's own kind and
+connectivity — there is no user option:
 
-The ghost state is built directly from the node head \f$H\f$: with \f$z_f\f$
-the conduit invert at the coupled face,
+| Model | Applies to | Storage | Head |
+|---|---|---|---|
+| **Pass-through** | a *clean* junction of degree 2 with nothing injected at it | none | not a state at all: the two end cells present their centred states directly to each other |
+| **Solved algebraic** | every other storage-less junction with at least one conduit face | none | root of the instantaneous flux balance (8-31) |
+| **Bucket** | storage units, junctions with no conduit face (a pump-only wet well), and junctions demoted by ponding | \f$A_{s}\f$ or a curve | integrated volume ledger, §8.6.5 step 5 |
+
+*Clean* means every incident face is a plain conduit face — no culvert
+inlet, no flap gate. A culvert or gate law is head- and
+direction-dependent and has to act against a solved node state, so it
+revokes both the direct splice and the reported reconstruction of
+§8.7. Outfalls are a fourth case and simpler than any of these: their
+stage is imposed every routing step, including `FREE` and `NORMAL`
+outfalls, whose depth `setAllOutfallDepths` computes from the conduit
+that feeds them. An outfall never integrates a ledger.
+
+The ghost state is built directly from the node head \f$H\f$ — for every
+node that has one, which is all of them but the pass-through case
+below. With \f$z_f\f$ the conduit invert at the coupled face,
 
 | | | | |
 |---|---|---|---|
 | \f[h_{g} = \max\left( 0,\ H - z_{f} \right), \qquad v_{g} = v_{int}, \qquad Q_{g} = A\left( h_{g} \right)\,v_{g}\f] | | (8-28) | |
 
 where \f$v_{int}\f$ is the interior end cell's velocity expressed in the
-face frame — a transmissive momentum condition, sketched in Figure 8-4.
+face frame — a transmissive momentum condition, sketched in Figure 8-8.
 A node standing below the face invert presents a dry ghost, so a
 perched pipe outlet drains as a free overfall. A closed conduit end
 with no node (a dead end) instead mirrors the interior state with
 reversed velocity, which returns exactly zero mass flux and leaves the
 interior its own hydrostatic pressure.
 
-
-![Figure 8-4](figure8-4-placeholder.png)
-
-*Figure 8-4 Node ghost-state construction at a coupling face
-(placeholder)*
-
-Node storage uses SWMM's own convention. A junction, outfall or divider
-is a linear reservoir of area \f$V_{full}/y_{full}\f$ — that is,
-`MIN_SURFAREA` unless a pump wet well overrode it — held fixed for the
-run; a storage unit uses its own curve. Matching the engine's
-definition exactly is what makes the node ledger conservative: the
-volume the solver holds is the same function of depth the mass balance
-reports, so no water is stored where continuity cannot see it.
+![Figure 8-8](figures/png/hydraulics_ch8_node_ghost_state.png)
+
+*Figure 8-8 Node ghost-state construction at a coupling face*
+
+**A plain junction has no storage.** It is an interface, not a state:
+the water standing "in the manhole" is held by the incident end cells,
+which are real control volumes with their own depth. This mirrors the
+dynamic wave solver, where `node_getSurfArea` is exactly zero for a
+non-storage node and all working area belongs to the conduits — here,
+to the cells. The head is then the root of the instantaneous balance
+over the incident faces,
+
+| | | | |
+|---|---|---|---|
+| \f[R(h) = \sum_{f} s_{f}F_{f}(h) + q_{lat} + q_{struct} + \frac{\text{carry}}{\Delta t} = 0\f] | | (8-31) | |
+
+with every face re-solved by the ghost-Riemann machinery (8-28) at each
+trial head, bracketed by geometric expansion and closed by a bracketed
+quasi-Newton step \f$\delta h = R/\sum\sqrt{gAT}\f$. The remainder the
+iteration does not close is *banked, not stored*: it is carried to the
+next substep, and at a pass-through node it is disposed as volume into
+the incident cells, split evenly with zero momentum, because that is
+where an interface junction's water physically stands. The node volume
+the report shows for such a node is that carry ledger and nothing else.
+
+Where a bucket ledger *is* integrated — storage units, structure-only
+junctions, ponding-demoted junctions — the storage relation is the
+engine's own: a linear reservoir of area \f$A_{s} = V_{full}/y_{full}\f$
+(`MIN_SURFAREA` unless the project overrode it) held fixed for the run,
+or the storage unit's own curve flattened to a monotone 129-sample
+depth–volume table. Two properties follow from \f$A_{s}\f$ being
+constant, and both are load-bearing: \f$V = A_{s}d\f$ is a genuine state
+relation, so re-seeding the ledger from the head between routing steps
+is exact rather than creating \f$(A_{s}^{new} - A_{s}^{old})d\f$ of water
+from nothing; and the volume the solver holds is the same function of
+depth the mass balance reports, so no water is stored where continuity
+cannot see it.
+
+**Why not give the node half of each connected link's volume?** That is
+the dynamic wave convention, and it is deliberately not used here. In
+dynamic wave a conduit carries no depth state of its own at the node, so
+\f$\sum \tfrac{1}{2}L\,T\f$ of surface area is how the node acquires any
+storage at all. Under finite volume the end cells already *are* control
+volumes holding exactly that water as explicit state, so adding a
+half-link area to the node books the same water twice. It was measured
+twice and rejected twice: tracking the live conduit top width — the
+obvious first guess — cost about 0.3 % of routing continuity on
+Example1, and the surviving `MIN_SURFAREA`-times-depth volume credit
+re-counted the cells' water at −0.005 % per junction on a 120-junction
+chain and was removed. The finite-volume analogue of the half-link
+volume is not a node term at all; it is the end cells, and the
+pass-through path already routes lateral inflow and residual carry
+*into* those cells, half to each side.
 
 **Mass is conserved exactly at a node. Momentum is intentionally not.**
 At a general junction — several pipes at arbitrary angles, differing
@@ -909,13 +1361,32 @@ solver uses, and like it, it is not an energy balance either — equating
 piezometric head discards the incoming velocity head, a dissipative
 closure appropriate to a chamber.
 
-**The node's coupling to its faces is semi-implicit.** A junction's
-storage area is the `MIN_SURFAREA` floor, which as an effective length
+That dissipation has a measurable consequence, and it is the reason the
+pass-through model exists. Presenting a solved node head to two
+collinear cells splits one interior Riemann problem into two, and the
+split costs roughly a millimetre of head per junction. On a
+199-junction subcritical chain that integrates into a 0.23 m backwater
+(SWASHES `macdonald-long-sub`, L1 depth error 0.228 → 0.0064 once the
+splice is used instead); with lateral inflow at every junction of a
+400-conduit channel it reached an 18–25 % deep bias. A clean degree-2
+junction therefore does not present a head at all — each of its two
+faces shows the *far* cell's full centred state, reproducing the single
+spliced face the pair stands in for. A lateral inflow does not revoke
+this, because a manhole pour carries no directed momentum: the inflow is
+diverted into the two incident cells, half each, as a zero-momentum area
+source. A structure flow or an unbled carry does revoke it, since both
+need a head the fluxes can respond to.
+
+**A bucket node's coupling to its faces is semi-implicit.** Its storage
+area is typically the `MIN_SURFAREA` floor, which as an effective length
 \f$A_{s}/T\f$ is a few feet against a conduit \f$\Delta x\f$ of several
-hundred. Under explicit coupling it is therefore the manhole, rather than the pipe, that
-sets the stable substep for the whole model. `FV_NODE_COUPLING
-SEMI_IMPLICIT` (the default) removes that by linearizing each coupling
-face's mass flux in the node head, using the characteristic relation
+hundred. Under explicit coupling it is therefore the manhole, rather
+than the pipe, that sets the stable substep for the whole model —
+which, before junctions became interfaces, was the whole network's
+substep. The semi-implicit coupling — always on; the explicit
+alternative was retired with `FV_NODE_COUPLING` — removes that by
+linearizing each coupling face's mass flux in the node head, using the
+characteristic relation
 \f$\left| \partial Q/\partial H \right| = gA/c = \sqrt{g\,A\,T}\f$ at the
 ghost state:
 
@@ -967,12 +1438,28 @@ posed — the model declares a virtual junction (see the
 consumed at mesh construction: the two conduits' cell chains are
 concatenated and the junction becomes an ordinary interior face.
 
+An *inlet junction* (`[INLET_JUNCTIONS]`, Chapter 3 §3.3.10) is a
+virtual junction that also owns a street inlet and exchanges captured
+flow with a capture node at every step. Splicing it out would leave that
+transfer with no node to act on, so inlet junctions are not admitted
+under finite-volume routing: the input processor refuses them with
+error 619.
+
 Nothing else is done, and nothing else is needed. Mass and momentum
 flux continuity across a virtual junction are then properties of the
 scheme rather than a special treatment, and a conduit split by a
 virtual junction reproduces the unsplit conduit cell for cell.
 
-### 8.6.3 Outfalls, structures and lateral inflow
+The one node-level quantity a virtual junction can still carry is a
+point lateral inflow (Chapter 3, §3.3.10). The node owns no face, so
+the inflow is divided equally between the two cells adjoining its
+spliced face and enters their mass equations as a zero-momentum source
+— the same treatment a clean degree-2 junction's lateral receives
+(§8.6.3) — and the node reports its through-flow plus the lateral as
+total inflow. A device backend that receives the per-node lateral must
+apply the same split; integrating it on the node would discard it.
+
+### 8.6.3 Outfalls, structures and lateral inflow {#hydraulics_ref_ch8_structures}
 
 Outfalls are stage boundaries: the head computed by the existing
 free/normal/fixed/tidal/time-series logic is imposed, and the ghost
@@ -1005,11 +1492,12 @@ wall only while the flux would run the wrong way; closing it mirrors the
 interior state across the face, which returns exactly zero mass flux and
 leaves the interior its own hydrostatic pressure.
 
-Lateral inflows enter at regular nodes exactly as assembled for any
-other routing method. Distributed conduit losses — evaporation and
-seepage — enter the cell mass equation as \f$q_L\f$ in (8-1).
+Lateral inflows enter at nodes exactly as assembled for any other
+routing method; at a virtual junction the inflow is split between the
+two spliced cells (§8.6.2). Distributed conduit losses — evaporation
+and seepage — enter the cell mass equation as \f$q_L\f$ in (8-1).
 
-### 8.6.4 Culvert inlet control
+### 8.6.4 Culvert inlet control {#hydraulics_ref_ch8_culvert_inlet}
 
 A conduit carrying a culvert code in `[XSECTIONS]` marks its upstream
 boundary face at mesh construction, and the FHWA inlet-control curve
@@ -1053,45 +1541,39 @@ flows of §8.6.3 into a per-node net source \f$q_{struct}\f$. With the
 junction area fixed for the run this re-seed is exact: it reproduces
 the volume the previous step ended with rather than perturbing it.
 
-Each substep then advances every non-virtual node as follows.
+Each substep then advances every non-virtual node as follows. Steps 2
+and 4 through 6 are the **bucket** path; a pass-through junction skips
+the node update entirely (its faces already carry the splice) and a
+solved algebraic junction replaces steps 2–6 with the root find (8-31)
+and its carry ledger.
 
 1. **Face fluxes.** Every boundary face of the node has been evaluated
    against the ghost state (8-28) by the flux pass.
-2. **Semi-implicit correction.** For nodes without a prescribed head,
-   the correction (8-18) is computed from the net residual
-   \f$\sum s_{f} F_{f} + q_{lat} + q_{struct}\f$ and written into the
-   incident face fluxes through (8-29). With `FV_NODE_PICARD` greater
-   than one the correction is iterated: each sweep re-evaluates the
-   storage slope \f$dV/dH\f$, the residual — now including the storage
-   already moved, \f$-\Delta V/\Delta t\f$ — and the resistances at the
-   provisional head, re-solves the incident faces' Riemann problems
-   there, and repeats until the head correction falls below 10⁻⁶ ft or
-   the sweep budget is exhausted; the final sweep writes the linear
-   correction into the face fluxes exactly as the single sweep does.
-   One sweep, the default, reproduces the original linearized scheme
-   bit for bit. Under local time stepping the correction is applied per
-   node at that node's own tier step, and the Riemann re-solve is
-   restricted to faces firing on the current base step — a face held by
-   another tier keeps the flux it will book over its own window.
-3. **End-cell coupling (`FV_NODE_CELL_COUPLING`).** The single-sweep
-   tangent treats the neighbouring cells as frozen reservoirs.
-   Optionally, each end cell — a finite volume of plan area
-   \f$C = \Delta x\,T\f$ that couples to nothing but this node — is
-   eliminated from the joint backward-Euler system in closed form:
-   writing \f$a_{f} = \sqrt{g A_{g} T_{g}}\f$ for the face resistance,
-
-| | | | |
-|---|---|---|---|
-| \f[\tilde{a}_{f} = a_{f}\,\frac{C_{f}}{C_{f} + \Delta t\,a_{f}}, \qquad \phi_{f} = \frac{a_{f}\,\Delta t\,G_{f}^{0}}{C_{f} + \Delta t\,a_{f}}\f] | | (8-31) | |
-
-   with \f$\tilde{a}_{f}\f$ replacing \f$a_{f}\f$ in the resistance sum and
-   \f$\sum \phi_{f}\f$ added to the residual, where \f$G_{f}^{0}\f$ is the flux
-   currently entering the cell through face \f$f\f$. The applied face
-   correction then responds to the head *difference* between the node
-   and the eliminated cell stage. As \f$\Delta t\f$ grows the correction
-   tends to the lumped node-plus-end-cells volume balance — the correct
-   large-step limit. Off by default; intended as the companion to
-   `FV_NODE_DT NONE`.
+2. **Semi-implicit correction.** For bucket nodes without a prescribed
+   head, the correction (8-18) is computed once from the net residual
+   \f$\sum s_{f} F_{f} + q_{lat} + q_{struct}\f$, with the resistances,
+   the storage area and the face fluxes all frozen at the head the
+   substep started from, and written into the incident face fluxes
+   through (8-29). That is exact for the linearized problem; the real
+   problem's nonlinearity is resolved by the node's fine tier under
+   local time stepping (below), where the correction is applied per
+   node at that node's own tier step.
+3. *(Retired.)* Three keywords are accepted and ignored so existing
+   projects still parse. `FV_NODE_CELL_COUPLING` once eliminated each
+   end cell from a joint backward-Euler system with the node, so that
+   the correction responded to the head *difference* between node and
+   cell; it was superseded by the interface treatment above — a junction
+   that holds no volume has nothing to couple *to* its end cells — as
+   was `FV_JUNCTION_MODEL`. `FV_NODE_PICARD` iterated the correction of
+   step 2, re-solving the incident faces at each provisional head; it
+   corrected the mass fluxes only, leaving the momentum fluxes
+   inconsistent with them — the same mass-only-correction defect the
+   interface solve exists to avoid — and shipped with a recorded
+   negative result (it never bought back the coarse step it was meant
+   to). `FV_NODE_COUPLING EXPLICIT` and `FV_NODE_DT NONE` are retired on
+   the same terms (§8.6.1 and the bound below); asking for any of the
+   three retired *behaviours* is answered with a warning at open, while
+   spelling out the former defaults is not.
 4. **Positivity.** The node's total outgoing flux is scaled by (8-26)
    against its stored volume.
 5. **Ledger.**
@@ -1112,34 +1594,35 @@ Each substep then advances every non-virtual node as follows.
    and the conduit exchange is whatever the Riemann solver produced
    against it.
 
-**The node's time-step bound (`FV_NODE_DT`).** A coupled node behaves
-as an extra control volume of effective length \f$A_{s}/T\f$, giving the
-bound
+**The node's time-step bound.** A bucket node behaves as an extra
+control volume of effective length \f$A_{s}/T\f$, giving the bound
 
 | | | | |
 |---|---|---|---|
 | \f[\Delta t \leq \alpha\,\frac{A_{s}/T}{\left\lvert v \right\rvert + c}\f] | | (8-32) | |
 
-evaluated over the node's wet incident end cells. Under explicit
-coupling this is a genuine stability limit and always applies. Under
-the default semi-implicit coupling the correction is unconditionally
-stable and the bound instead controls accuracy: when local time
-stepping is running, the bound is dropped from the global census and
-each node receives its own fine tier from (8-32), which supplies the
-resolution at low cost; when tiering cannot run (`RK2`, or transport),
-the bound is honoured in the global census. `FV_NODE_DT NONE` removes
-it from the base-step computation while leaving nodes tiered. Measured
-against the SWASHES analytic solutions, `NONE` is 24–134× faster and
-degrades the L1 depth error by factors of 3 to 49 on the frictional and
-transcritical cases, so the default remains `STABILITY`. Additional
-Picard sweeps do not substitute for the bound at large steps: they
-converge the node's continuity equation at the step it is handed, which
-is a separate question from that step being small enough to resolve the
-coupling.
+evaluated over the node's wet incident end cells, and always armed. It
+is skipped for the nodes that have no volume state to protect —
+algebraic junctions, whose tier is instead pinned to their incident
+cells so that their faces fire together, and outfalls, whose head is
+imposed — which is why in practice it binds storage nodes only.
+Applying it to plain junctions was how a single `MIN_SURFAREA` bucket
+used to set a millisecond step for the whole network. The semi-implicit
+correction is unconditionally stable, so the bound controls accuracy
+rather than stability: when local time stepping is running, the bound
+is dropped from the global census and each node receives its own fine
+tier from (8-32), which supplies the resolution at low cost; when
+tiering cannot run (`RK2`, or transport), the bound is honoured in the
+global census. It is not optional: measured against the SWASHES
+analytic solutions under the earlier bucket junction model, dropping it
+was 24–134× faster and degraded the L1 depth error by factors of 3 to
+49 on the frictional and transcritical cases (the `FV_NODE_DT NONE`
+switch that produced those numbers is retired; asking for it warns and
+is ignored).
 
 **Implementation.**
 @ref openswmm::fv::ExplicitFvSolver::relaxNodeFluxes and
-@ref openswmm::fv::ExplicitFvSolver::relaxOneNode implement steps 2–3;
+@ref openswmm::fv::ExplicitFvSolver::relaxOneNode implement step 2;
 @ref openswmm::fv::ExplicitFvSolver::updateNodes and
 @ref openswmm::fv::ExplicitFvSolver::fireNodes carry the ledger on the
 global and tiered paths;
@@ -1164,6 +1647,104 @@ volume are instantaneous, as under dynamic wave routing. A virtual
 junction reports the state of the interior face that replaced it, and
 zero volume — it has none by construction.
 
+**Reported link depth is a water depth, truncated at the section's full
+height.** Internally the solver's mean state above the crown is
+piezometric — `depthOfArea` of the slot-inclusive mean area — but the
+published depth is `min(depthOfArea(A_mean), y_full)`, matching the
+dynamic-wave convention. The `.out` LINK_DEPTH column therefore never
+doubles as a head channel, and the Link Flow Summary's "Max/Full Depth"
+reads at most 1.00 for a closed conduit. The surcharge head remains
+fully visible where it belongs: in the **node** depths/heads (which are
+genuine piezometric state) and in the slot-storage accounting below.
+The truncation is publish-only — velocity, capacity, Froude number,
+surcharge hours, and the volume/slot ledgers are computed from the mean
+area or from saturating section geometry and are unaffected.
+
+### 8.7.1 Slot storage accounting and diagnostics
+
+The Preissmann slot's water is genuine storage in the conservation
+ledger: link volume is \f$\sum A\,\Delta x\f$ over the slot-inclusive
+conserved area, with no clamp, and it feeds *Final Stored Volume* and
+`SYS_STORAGE` at full weight. Because plain junctions report zero
+storage under FV (their water stands in the incident cells), the slot
+is the only place surcharge storage can be booked — so on a pressurized
+system a material share of reported storage can stand in the slot.
+The engine separates that share out rather than leaving it folded in:
+
+- **`links.slot_volume`** — per link,
+  \f$\sum \max(0,\,A - A_{crown})\,\Delta x\f$, always a subset of the
+  link volume, zero below the crown and zero under dynamic-wave
+  routing. C API: `swmm_link_get_slot_volume`.
+- **"Final Slot Storage"** — an informational line under *Flow Routing
+  Continuity* (printed only when nonzero): the slot's share of *Final
+  Stored Volume*. It is already inside that total, never added again.
+- **"Slot Storage Summary"** — a report block giving the run-level
+  share (the ratio of time integrals
+  \f$\int V_{slot}\,dt \,/\, \int V_{stored}\,dt\f$ — a ratio of
+  integrals, never an average of instantaneous ratios), the peak
+  instantaneous system share, the hours the share exceeded 1 %, and a
+  per-link table of every conduit whose peak share crossed 1 %.
+  C API: `swmm_link_get_stat_slot_share` (run-level) and
+  `swmm_link_get_stat_peak_slot_share` (peak, 0..1).
+- **`OPENSWMM_FV_SLOT_TRACE=1`** — one CSV row per routing step on
+  stdout (`SLOT_TRACE,t,slot_ft3,stored_ft3,share`), for plotting the
+  slot share through a transient.
+
+The **FV Solver Statistics** block attributes the time step alongside:
+four "dt Argmin" rows give the fraction of CFL censuses whose binding
+element was a pressurized cell (at or above the crown), a taper-band
+cell, a free-surface cell, or a node bound. On a pressurized system
+the pressurized rows dominating is the measured statement that
+`FV_SLOT_CELERITY` — not the free-surface dynamics — is setting the
+run's cost.
+
+Two properties of the slot worth reading off these instruments rather
+than assuming: the slot share of storage scales as \f$1/c^{2}\f$ in the
+celerity, and the steady **full-bore head loss depends on the
+celerity** — the slot absorbs part of the friction grade — converging
+on the Manning value from below as the slot narrows. A low celerity
+therefore understates both pressurization and head loss at once; the
+5 % width cap (§8.4.1) bounds the damage but does not remove it, and
+WARNING 108 reports when the cap has silently overridden the requested
+celerity (every request below the cap-implied celerity produces
+byte-identical geometry).
+
+**Node stage is reconstructed from the incident cells, not read off the
+solver's head.** For a storage-less clean junction of any degree — the
+publish rule is the *clean* test of §8.6.1 without its degree-2
+restriction, since reconstructing a reported stage needs no splice — the
+published head is
+
+| | | | |
+|---|---|---|---|
+| \f[H_{pub} = \max_{f\ \in\ \text{wet},\ z_{f} \leq H} \left[\ \min\left(z_{b,c(f)},\, z_{f}\right) + h_{c(f)}\ \right]\f] | | (8-33) | |
+
+taken over the node's wet incident faces. A dry neighbour's vote would
+be bare ground, and a face perched *above* the node's own surface is
+discharging as a free overfall — its stage describes the pipe's offset,
+not the node — so neither votes; with no wet vote at all the solver's
+head stands. This is the same reconstruction the virtual-junction rule
+uses, which is what keeps a junction and a virtual junction from
+stepping against each other in a plotted HGL.
+
+The reason is that the solver's own head for a solved algebraic junction
+carries a half-cell datum offset of order \f$S_{0}\Delta x/2\f$ against
+the face stage, which appears in a profile plot as a step at the
+manhole. It is a reporting term, not a routing one: it falls
+first-order under mesh refinement, it survives on nodes with no lateral
+inflow at all, and correcting it leaves the routed solution bit-identical.
+Measured on Example1 at `FV_MIN_CELLS 1`, where the comparison against
+the adjacent cell is exact, the largest excess over the adjacent conduit
+surface falls from 0.91 ft to below 0.001 ft. Reporting is deliberately
+the only place this correction is applied: solver-internal heads double
+as ghost boundary states under local time stepping, and changing the
+in-solver estimator turned a 0.007 cfs lake-at-rest residual into a
+70.9 cfs standing oscillation.
+
+Bucket nodes, culvert headwaters, gated nodes and nodes carrying a
+structure flow are excluded and publish the head the solver holds,
+which for them is a genuine state.
+
 ## 8.8 Scalar transport
 
 When the solver carries advected species, the species flux is the
@@ -1213,13 +1794,13 @@ file.
 | `FV_LIMITER` | `MINMOD` | `MINMOD`, `VANLEER` or `SUPERBEE`, with `FV_ORDER 2`. |
 | `FV_SCALAR_SCHEME` | `MUSCL` | `UPWIND`, `MUSCL` or `QUICKEST_ULTIMATE`. |
 | `FV_TIME_INTEGRATION` | `EULER` | `EULER` or `RK2` (Heun, SSP). `RK2` disables local time stepping. |
-| `FV_SLOT_CELERITY` | 100 | Pressurized wave celerity in project length units per second; sets the slot width via (8-5). |
+| `FV_SLOT_CELERITY` | 100 | Pressurized wave celerity in project length units per second; sets the slot width via (8-5) and doubles as the TPA acoustic celerity \f$a\f$ under `FV_PRESSURE_CLOSURE TPA` (§8.4.5) — the same physical dial either way. Slot storage share scales as 1/c²; values below the cap-implied celerity (≈ 22.5·√D ft/s for a circular pipe) are inert — WARNING 108 reports the override. Slot storage is itemized by the §8.7.1 diagnostics. With `FV_PRESSURIZED_IMPLICIT YES` the celerity leaves the time-step law entirely (§8.4.4) and becomes a pure accuracy dial. |
+| `FV_PRESSURE_CLOSURE` | `SLOT` | **Experimental** — `SLOT` or `TPA`. `TPA` selects the two-component pressure approach of §8.4.5: sub-atmospheric full-pipe flow behind a per-cell air-pathway regime flag. `SLOT` (the default) is bit-identical to the closure of §8.4.1–§8.4.2. Pair with `REPORT_SIGNED_HEADS YES` to see sub-atmospheric heads in the `.out` file. |
+| `FV_PRESSURIZED_IMPLICIT` | `NO` | **Experimental** — subject to slot program R2b; surfaced in the GUI as an experimental checkbox. Integrate the slot's acoustic pair implicitly on the pressurized subset (§8.4.4): full-bore head loss becomes slot-width invariant and pressurized reaches run at the advective time-step bound. CPU solver only; local time stepping stands down while the solve engages; a run that never pressurizes is bit-identical either way. Composes with `FV_PRESSURE_CLOSURE TPA` under the rules of §8.4.5. |
 | `FV_DISPERSION` | 0 | Longitudinal dispersion coefficient. 0 disables the parabolic term. Accepted but **inert** until finite-volume transport is connected (§8.8); a non-zero value warns at open. |
 | `FV_STRUCTURE_COUPLING` | `SUBSTEP` | Cadence at which structure flows and outfall stages are refreshed: every substep, or once per routing step. A device backend clamps to `ROUTING_STEP`. |
-| `FV_NODE_COUPLING` | `SEMI_IMPLICIT` | `EXPLICIT` freezes face fluxes across the node update; `SEMI_IMPLICIT` linearizes them in the node head (§8.6.1). |
-| `FV_NODE_PICARD` | 1 | Picard sweeps on the node head inside the semi-implicit coupling (§8.6.5). 1 reproduces the single linearized correction exactly. |
-| `FV_NODE_CELL_COUPLING` | `NO` | Couple the node correction to its adjacent end cells through (8-31); the accuracy-at-large-step companion to `FV_NODE_DT NONE`. |
-| `FV_NODE_DT` | `STABILITY` | Whether the node bound (8-32) enters the base time step. `NONE` removes it from the census; nodes remain tiered under local time stepping. Semi-implicit coupling only. |
+| `FV_NODE_CELL_COUPLING` | — | **Retired.** Accepted and ignored so existing projects still parse; junctions are always interfaces (§8.6.1). `FV_JUNCTION_MODEL` is retired on the same terms. |
+| `FV_NODE_COUPLING`, `FV_NODE_DT`, `FV_NODE_PICARD` | — | **Retired 2026-08-29.** Storage-node coupling is always semi-implicit (§8.6.1), the node bound (8-32) is always armed (§8.6.5), and the correction is always a single sweep — each the former default. Accepted so existing projects still parse; a value asking for the retired behaviour (`EXPLICIT`, `NONE`, sweeps above 1) warns at open and is ignored. |
 | `FV_COMPACTION` | `YES` | Skip dry, inactive parts of the network. Results-transparent. |
 | `FV_LTS` | `YES` | Local time stepping (§8.5.6). `NO` forces one global substep size. |
 | `FV_LTS_MAX_TIERS` | 6 | Cap on the tier spread; 6 allows 64×. |
@@ -1227,64 +1808,64 @@ file.
 | `FV_BACKEND` | `AUTO` | `CPU`, `AUTO`, `OMP`, `CUDA`, `HIP` or `SYCL`. |
 | `FV_MIN_PARALLEL_CELLS` | 20000 | Mesh size below which `AUTO` stays on the CPU. |
 
+Three keys without the `FV_` prefix also affect finite-volume runs and
+are shared with the dynamic wave solver: `UNSTEADY_FRICTION` and
+`UF_K3` (§8.5.4), and `REPORT_SIGNED_HEADS` (§8.4.5), which puts the
+true signed piezometric head in the `.out` HEAD field for both solvers
+(default `NO` keeps legacy bit-parity; DEPTH stays floored either way).
+
 ## 8.10 Choosing between dynamic wave and finite volume
 
-The following are measured on the EPA reference site drainage model
-(`Example1.inp`, 30 h, 5 s routing step), comparing each finite-volume
-configuration against the dynamic wave run of the same file.
+Measured on 2026-08-20 against commit `962fd48c`, on the EPA reference
+site drainage model (`Example1.inp`, 30 h, 5 s routing step) and on
+generated uniform and graded reaches. Reproduce with
+`tests/benchmarks/scripts/fv_perf_baseline.py`; the full tables, the
+per-phase split and the `.out` hashes are in
+`plans/FV1D_PERF_BASELINE_2026-08-20.md`.
 
-| | Dynamic wave | FV, 1 cell | FV, default (4 cells) | FV, \f$\Delta x\f$ = 50 ft | FV, \f$\Delta x\f$ = 20 ft |
-|---|---|---|---|---|---|
-| Routing continuity error | 0.026 % | 0.000 % | 0.000 % | 0.000 % | 0.000 % |
-| Mean absolute peak-flow deviation | — | 37.1 % | 15.3 % | 12.8 % | 7.2 % |
-| Wall-clock, relative | 1× | ~7× | ~15× | ~12× | ~34× |
+| | Dynamic wave | FV, 1 cell | FV, default (4 cells) |
+|---|---|---|---|
+| Routing continuity error | 0.026 % | 0.000 % | −0.000 % |
+| Wall-clock, relative | 1× | 5.3× | 14.9× |
+| Substeps per routing step | — | 1.03 | 2.05 |
 
 The same comparison across network size, on uniform and graded reaches
 of 50 / 500 / 2000 conduits, at the default mesh:
 
 | | 50 | 500 | 2000 |
 |---|---|---|---|
-| uniform reach, × dynamic wave | 117 | 252 | 189 |
-| graded reach, × dynamic wave | 39 | 69 | 49 |
-| routing continuity, finite volume | −0.000 % | −0.000 % | −0.000 % |
-| routing continuity, dynamic wave | −0.16 … −0.50 % | 0.09 / −0.19 % | 0.09 / −0.19 % |
-
-Two observations follow. First, the ratio does not improve with network
-size — it is flat to erratic, so the cost should not be expected to
-amortize on larger models. Second, the finite-volume solver closes on
-the dynamic wave solver where the latter struggles: the graded
-ratios are three to four times better, not because the explicit solver
-got faster (its times are unchanged between the two) but because the
-implicit solver's own step collapses there, from 5.00 s to 1.14 s. Steep,
-graded, stiff networks are where the trade is most favourable.
+| uniform reach, × dynamic wave | 11.3 | 17.3 | 17.5 |
+| graded reach, × dynamic wave | 15.6 | 33.5 | 29.2 |
+| routing continuity, finite volume | 0.000 % | −0.000 % | −0.000 % |
+| routing continuity, dynamic wave | −1.30 / −0.59 % | −0.51 / −0.80 % | −0.51 / −0.64 % |
 
 Three observations follow.
 
 **Conservation is delivered, and is independent of resolution.** The
-finite-volume solver closes continuity exactly on this model where the
-implicit solver does not. That is the property the conservation form
-guarantees.
-
-**Accuracy requires a resolved mesh.** The convergence above is clean
-and monotone, which is what a consistent discretization must show — but
-an unresolved mesh is not a drop-in substitute for dynamic wave
-analysis. The mechanism is the artificial bed step of §8.3 rather than
-numerical diffusion, so second-order reconstruction does not remove it.
-
-**It still costs several times more.** Even at one cell per conduit —
-the same element count the dynamic wave solver carries — the explicit
-method runs about seven times its wall-clock on this model, and the
-default mesh roughly doubles that again. The method should be selected
-for its conservation and shock-capturing properties rather than for
-speed.
-
-Note also that the deviation column is a consistency check against the
-dynamic wave solver rather than a measure of error. Dynamic wave
-routing is not
-the reference truth here, and part of the 37 % at one cell is its own
-departure from the correct answer. Accuracy is instead established
-against closed-form solutions — Ritter, Stoker, and the still-water
-property.
+finite-volume solver closes continuity exactly on every deck and every
+mesh above, where the implicit solver does not — and the gap is widest
+on the plain reaches, where dynamic wave loses 0.5 % to 1.3 % of volume.
+That is the property the conservation form guarantees.
+
+**Accuracy requires a resolved mesh.** An unresolved mesh is not a
+drop-in substitute for dynamic wave analysis. The mechanism is the
+artificial bed step of §8.3 rather than numerical diffusion, so
+second-order reconstruction does not remove it.
+
+**It costs several times more, and the multiple grows with the
+network.** At one cell per conduit — the same element count dynamic
+wave carries — the explicit method runs about five times its wall clock
+on the reference model, and the default mesh roughly triples that
+again. On uniform reaches the ratio rises from 11× at 50 conduits to
+17× at 2000, so the cost should not be expected to amortize on larger
+models. Select the method for its conservation and shock-capturing
+properties, not for speed.
+
+Note that the earlier editions of this section reported ratios of 39× to
+252× across the same reach sizes. Those numbers were measured on the
+bucket-junction solver that `265eb727` (2026-08-11) replaced with
+algebraic junctions, and they no longer describe this solver; the table
+above supersedes them.
 
 Practical guidance:
 
@@ -1303,12 +1884,19 @@ Practical guidance:
 
 ## 8.11 Limitations
 
-- **Sub-atmospheric pressure cannot be represented.** The slot closure
-  is monotone — head below the crown means a free surface — so negative
-  pipe pressures have no representation. Air-phase effects are likewise
-  out of scope. This is the same fidelity limit the dynamic wave
-  solver's slot carries.
-- **Junction momentum is not conserved** (§8.6.1), by choice.
+- **Sub-atmospheric pressure cannot be represented under the default
+  closure.** The slot closure is monotone — head below the crown means
+  a free surface — so negative pipe pressures have no representation.
+  `FV_PRESSURE_CLOSURE TPA` (§8.4.5) lifts this, down to the
+  column-separation bound of about −30 ft of head; air-phase effects
+  remain out of scope under either closure.
+- **Junction momentum is not conserved** (§8.6.1), by choice. Where the
+  connection is genuinely two collinear pipes the loss is avoided
+  outright — by a virtual junction (§8.6.2) or, for a clean degree-2
+  junction, by the pass-through splice — but at a true multi-way
+  junction the stagnation closure discards the incoming velocity head,
+  and on junction-dense subcritical reaches that dissipation integrates
+  into a systematic backwater.
 - **A conduit loop closed entirely by virtual junctions cannot be
   meshed**, because such a cycle has no boundary. Ordinary junctions
   break the cycle and are accepted.
@@ -1341,6 +1929,23 @@ Leonard, B. P. (1979). "A stable and accurate convective modelling
 procedure based on quadratic upstream interpolation." *Computer Methods
 in Applied Mechanics and Engineering*, 19(1), 59–98.
 
+Pinto, S. I. G., Vasconcelos, J. G., and Soares, A. K. (2025).
+"Unsteady friction in mixed-flow models based on the Saint-Venant
+equations." *Journal of Hydraulic Engineering*, 152(1), 04025046.
+
+Vasconcelos, J. G., Wright, S. J., and Roe, P. L. (2006). "Improved
+simulation of flow regime transition in sewers: two-component pressure
+approach." *Journal of Hydraulic Engineering*, 132(6), 553–562.
+
+Vasconcelos, J. G., Wright, S. J., and Roe, P. L. (2009). "Numerical
+oscillations in pipe-filling bore predictions by shock-capturing
+models." *Journal of Hydraulic Engineering*, 135(4), 296–305.
+
+Vítkovský, J. P., Lambert, M. F., Simpson, A. R., and Bergant, A.
+(2000). "Advances in unsteady friction modelling in transient pipe
+flow." *Proc., 8th Int. Conf. on Pressure Surges*, BHR Group, The
+Hague, Netherlands.
+
 Leonard, B. P. (1991). "The ULTIMATE conservative difference scheme
 applied to unsteady one-dimensional advection." *Computer Methods in
 Applied Mechanics and Engineering*, 88(1), 17–74.
diff --git a/docs/manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md b/docs/manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md
index 706dd7075..c0278d655 100644
--- a/docs/manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md
+++ b/docs/manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md
@@ -33,6 +33,138 @@ pools in a sag, and drains into whichever inlet it reaches. Which node
 receives the water is an outcome of the calculation rather than an
 input to it.
 
+Figure 9-1 places the two domains side by side: the node–link network of
+Chapters 3, 4 and 8 with its routing and pressurisation alternatives, the
+overland surface of this chapter with its three momentum closures, and the
+exchange pathways that join them — vertex and cell coupling, street inlet
+capture, and the node–bed exchange of a mesh aquifer.
+
+![Figure 9-1 The one-dimensional network and the two-dimensional surface: exchange pathways](figures/png/hydraulics_conceptual_1d2d.png)
+
+*Figure 9-1 The one-dimensional network and the two-dimensional surface: exchange pathways*
+
+

+@ref hydrology_ref_ch2_meteorology "Precipitation"
+@ref engine_manual_sect_RAINGAGES "rain gages"
+@ref hydrology_ref_ch6_snowmelt "rain · snow split (SCF)"
+@ref hydrology_ref_ch2_meteorology "scale factors"
+@ref hydrology_ref_ch2_meteorology "Climate"
+@ref engine_manual_sect_TEMPERATURE "temperature"
+@ref engine_manual_sect_EVAPORATION "evaporation: constant · monthly · series · Hargreaves · file"
+@ref engine_manual_sect_TEMPERATURE "wind"
+@ref hydrology_ref_ch2_meteorology "humidity · dew point"
+@ref hydrology_ref_ch2_meteorology "prescribed PET (API)"
+@ref hydrology_ref_ch6_snowmelt "Snowmelt"
+@ref hydrology_ref_ch6_snowmelt "degree-day · heat budget · areal depletion"
+@ref hydrology_ref_ch3_surface_runoff "Runoff"
+@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir"
+@ref engine_manual_sect_SUBAREAS "depression storage"
+@ref engine_manual_sect_SUBAREAS "routing to another subcatchment"
+@ref hydrology_ref_ch4_infiltration "Infiltration"
+@ref hydrology_ref_ch4_infiltration "Horton"
+@ref hydrology_ref_ch4_infiltration "modified Horton"
+@ref hydrology_ref_ch4_infiltration "Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "modified Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "curve number"
+@ref quality_ref_ch6_lid_controls "LID controls"
+@ref quality_ref_ch6_lid_controls "layered units (8 types)"
+@ref quality_ref_ch6_lid_controls "LID as storage nodes"
+@ref quality_ref_ch6_lid_controls "detailed output"
+@ref quality_ref_ch3_pollutant_buildup "Surface quality"
+@ref quality_ref_ch3_pollutant_buildup "buildup · washoff by land use"
+@ref engine_manual_sect_LANDUSES "street sweeping"
+@ref quality_ref_ch10_mesh_quality "MSX species"
+@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh"
+@ref hydrology_ref_ch8_mesh_surface "natural neighbour"
+@ref engine_manual_sect_2D_OPTIONS "system"
+@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration"
+@ref hydrology_ref_ch8_mesh_surface "Horton · Green-Ampt · CN · constant"
+@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment aquifer · mesh aquifer"
+@ref hydraulics_ref_ch9_two_dimensional "Overland flow"
+@ref hydraulics_ref_ch9_two_dimensional "local inertial"
+@ref hydraulics_ref_ch9_two_dimensional "full shallow water"
+@ref hydraulics_ref_ch9_two_dimensional "diffusive wave"
+@ref hydraulics_ref_ch10_planned "IMEX / CVODE"
+@ref hydraulics_ref_ch9_two_dimensional "Mesh and closure"
+@ref hydraulics_ref_ch9_two_dimensional "triangles"
+@ref hydraulics_ref_ch9_two_dimensional "quads"
+@ref hydraulics_ref_ch9_two_dimensional "flat cells"
+@ref hydraulics_ref_ch9_two_dimensional "VFR closure"
+@ref quality_ref_ch10_mesh_quality "Surface quality · transport"
+@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff"
+@ref quality_ref_ch10_mesh_quality "species on the mesh"
+@ref hydraulics_ref_ch9_two_dimensional "Backends"
+@ref hydraulics_ref_ch9_two_dimensional "CPU"
+@ref hydraulics_ref_ch9_two_dimensional "OpenMP"
+@ref hydraulics_ref_ch9_two_dimensional "CUDA · HIP · SYCL"
+@ref hydraulics_ref_ch10_planned "Metal"
+@ref hydrology_ref_ch5_groundwater "Two-zone aquifer"
+@ref hydrology_ref_ch5_groundwater "unsaturated + saturated zone"
+@ref engine_manual_sect_AQUIFERS "percolation · deep percolation · ET"
+@ref engine_manual_sect_GWF "lateral interflow, user [GWF]"
+@ref hydrology_ref_ch9_mesh_groundwater "Groundwater transport"
+@ref hydrology_ref_ch9_mesh_groundwater "advection–dispersion · heat"
+@ref hydrology_ref_ch9_mesh_groundwater "Two-layer aquifer"
+@ref hydrology_ref_ch9_mesh_groundwater "Gardner"
+@ref hydrology_ref_ch9_mesh_groundwater "Russo"
+@ref hydrology_ref_ch9_mesh_groundwater "Brooks–Corey"
+@ref hydrology_ref_ch9_mesh_groundwater "van Genuchten"
+@ref hydrology_ref_ch9_mesh_groundwater "closed form · enslaved · σ column"
+@ref hydrology_ref_ch9_mesh_groundwater "Dunne return flow"
+@ref hydrology_ref_ch9_mesh_groundwater "node–bed exchange"
+@ref hydrology_ref_ch9_mesh_groundwater "capillary rise · boundary ET"
+@ref hydrology_ref_ch9_mesh_groundwater "per-subcatchment mode"
+@ref engine_manual_sect_JUNCTIONS "Nodes"
+@ref engine_manual_sect_JUNCTIONS "junction · storage · divider · outfall"
+@ref hydraulics_ref_ch3_dynamic_wave "virtual junction"
+@ref hydraulics_ref_ch7_advanced_features "inlet junction"
+@ref engine_manual_sect_CONDUITS "Links"
+@ref hydraulics_ref_ch5_cross_section "conduits, 26 sections"
+@ref hydraulics_ref_ch5_cross_section "street · dummy"
+@ref hydraulics_ref_ch10_planned "Chebyshev irregular"
+@ref engine_manual_sect_PUMPS "pumps · orifices · weirs · outlets · culverts"
+@ref hydraulics_ref_ch5_cross_section "storage shapes"
+@ref hydraulics_ref_ch7_advanced_features "HEC-22 inlets"
+@ref hydraulics_ref_ch2_hydraulic_model "Flow routing"
+@ref hydraulics_ref_ch2_hydraulic_model "steady"
+@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave"
+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+@ref hydraulics_ref_ch8_lts "local time stepping"
+@ref hydraulics_ref_ch10_planned "1D GPU backend"
+@ref hydraulics_ref_ch3_dynamic_wave "Pressurisation"
+@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN"
+@ref hydraulics_ref_ch3_dynamic_wave "slot"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic slot"
+@ref hydraulics_ref_ch3_dynamic_wave "TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: slot"
+@ref hydraulics_ref_ch8_finite_volume "FV: TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: implicit head"
+@ref hydraulics_ref_ch3_dynamic_wave "unsteady friction"
+@ref hydraulics_ref_ch3_dynamic_wave "Node solution"
+@ref hydraulics_ref_ch3_dynamic_wave "explicit continuity"
+@ref hydraulics_ref_ch3_dynamic_wave "semi-implicit continuity"
+@ref hydraulics_ref_ch3_anderson "Anderson acceleration"
+@ref hydraulics_ref_ch10_planned "FV_NODE_* keys"
+@ref quality_ref_ch5_transport_treatment "Transport"
+@ref quality_ref_ch5_transport_treatment "CSTR"
+@ref quality_ref_ch7_ard_transport "Eulerian ARD"
+@ref quality_ref_ch7_ard_transport "Lagrangian LARD"
+@ref quality_ref_ch7_ard_transport "random-walk dispersion"
+@ref quality_ref_ch5_transport_treatment "first-order decay"
+@ref quality_ref_ch8_msx_reactions "MSX reactions"
+@ref quality_ref_ch9_age_heat "water age"
+@ref quality_ref_ch9_age_heat "heat"
+@ref quality_ref_ch11_planned "sediment"
+@ref engine_manual_sect_TREATMENT "treatment functions"
+@ref engine_manual_sect_INFLOWS "Inflows"
+@ref engine_manual_sect_DWF "dry weather flow"
+@ref hydrology_ref_ch7_rdii "RDII: RTK"
+@ref hydrology_ref_ch7_rdii "RDII: IA decay"
+@ref engine_manual_sect_INFLOWS "user · interface files"
+@ref engine_manual_sect_CONTROLS "control rules"
+

+
 **Flow paths the network does not contain.** Overland routes — a road
 acting as a channel, flow over an embankment, a flow path between two
 otherwise unconnected catchments — exist in the terrain and nowhere in
@@ -63,7 +195,19 @@ Depth-averaged mass conservation over a surface of bed elevation
 where \f$i\f$ is rainfall intensity, \f$e\f$ the evaporation rate and \f$s\f$ the
 exchange with the 1D network, all as velocities normal to the surface.
 
-The momentum equation solved is the **local-inertial** (or
+Three momentum closures supply \f$\mathbf{q}\f$ for the same continuity
+equation, selected by `[2D_OPTIONS] MOMENTUM_EQUATION`. They share one
+time-stepping engine — the tiered local time stepping, the flux-active
+set, the positivity share, the network coupling and the transport of
+§9.5–§9.7 — and differ only in the face law that supplies the discharge
+across each interior face and each boundary edge. The default,
+`LOCAL_INERTIAL`, reproduces the marcher as it stood before September 2026
+bit for bit; the other two are dispatched by one branch per face firing
+and otherwise reuse every array, ledger and rule of §9.5.
+
+### 9.2.1 The local inertial closure
+
+The default momentum equation is the **local-inertial** (or
 inertial-wave) approximation of Bates et al. (2010):
 
 | | | | |
@@ -97,7 +241,123 @@ contraction sets the answer, is outside it.
 
 For steep faces the model would accelerate without bound, since nothing
 in (9-2) limits the velocity a slope can generate. A Froude clamp
-supplies that limit numerically (§9.5.1).
+supplies that limit numerically (§9.5.1). The prognostic state is the
+cell volume \f$V\f$ and one face-normal discharge \f$q_f\f$ per interior face;
+the face law is (9-7)–(9-10).
+
+### 9.2.2 The full shallow-water closure (`FULL_SWE`)
+
+`MOMENTUM_EQUATION FULL_SWE` restores the convective term and solves the
+shallow-water momentum equation in conservation form,
+
+| | | | |
+|---|---|---|---|
+| \f[\frac{\partial \mathbf{q}}{\partial t} + \nabla\cdot\left( \frac{\mathbf{q}\,\mathbf{q}}{h} + \tfrac{1}{2}\,g\,h^{2}\,\mathbf{I} \right) = -\,g\,h\,\nabla z - \frac{g\,n^{2}\,\lvert\mathbf{q}\rvert\,\mathbf{q}}{h^{7/3}}\f] | Momentum, conservative form | (9-31) | |
+
+which is (9-2) with the convective flux \f$\mathbf{q}\mathbf{q}/h\f$ kept and
+the pressure gradient \f$g h \nabla\eta\f$ split into the hydrostatic
+pressure flux \f$\nabla(\tfrac{1}{2} g h^{2})\f$ and the bed-slope source
+\f$-g h \nabla z\f$. The prognostic state changes with the equation: each
+cell carries its volume and a **cell momentum** \f$(hu, hv)\f$, and faces no
+longer hold a prognostic discharge — they evaluate a Godunov flux from the
+two adjacent cell states, after a hydrostatic reconstruction of the two
+depths against the higher of the two beds (Audusse et al., 2004), with a
+rotated HLLC Riemann solver (Toro, 2001) and a per-face bed-slope
+correction that cancels the pressure flux exactly at rest. Manning
+friction is applied per cell after the flux update, in the same
+semi-implicit division the local-inertial face law uses, so it can only
+shrink \f$\lvert\mathbf{q}\rvert\f$ and never reverse it (the stopping
+condition of Liang and Marche, 2009, is satisfied by construction).
+§9.5.10 gives the face flux step by step.
+
+What the term buys is every phenomenon §9.2.1 said the default cannot
+represent: transcritical control over a crest, a hydraulic jump held at
+its Rankine–Hugoniot position, dam-break fronts at the right speed, the
+Bernoulli drawdown of §9.10. The closure is valid at every Froude number
+and needs no Froude clamp; `FROUDE_MAX` is not consulted.
+
+What it costs is a smaller step and more work per face. First-order
+Godunov with hydrostatic reconstruction is positivity-preserving at a
+Courant number of one half on triangles and quadrilaterals, so
+`CFL_NUMBER` is reduced to 0.5 with a notice when set higher, and the
+Courant length is the isoperimetric \f$2A/P\f$ rather than the
+operator-derived \f$L_{char}\f$ of (9-4); the \f$\beta\f$ share of (9-15)
+remains as a backstop rather than the guarantee. Measured on the SWASHES
+strips of §9.10 the closure runs at roughly two to three times the
+wall-clock of the default. Two further switches belong to it:
+`RECONSTRUCTION_ORDER 2` adds MUSCL reconstruction of \f$(\eta, u, v)\f$ with
+a Barth–Jespersen-limited Green–Gauss gradient and SSP-RK2 time stepping
+in global-step mode (§9.5.6, §9.5.10), and is refused with a notice when
+overland transport is active; `FRONT_REBUILD` (§9.5.7) is switched on
+automatically, because a Godunov front outruns the fixed rebuild cadence.
+The Kokkos plugin backends serve only the all-triangle local-inertial
+scheme; a `FULL_SWE` model is announced and run on the CPU marcher
+(§9.11.1).
+
+`FULL_SWE` keeps every property of §9.5: the lake at rest is exact —
+the Audusse correction cancels the \f$\tfrac{1}{2} g h^{*2}\f$ pressure flux
+face by face, including at walls, which contribute a mirror-state
+Riemann flux — a dry higher neighbour is a wall, \f$\sum V\f$ closes to
+round-off across tiers, and species ride the mass flux upwinded on the
+contact wave. Measured on the SWASHES strips of §9.10 (relative
+\f$L^{1}\f$ depth error, local-inertial in parentheses): Stoker wet dam break
+0.7 % (6.5 %), 0.3 % at second order; Ritter dry dam break 1.7 % (13 %),
+1.1 % at second order; subcritical bump 0.5 % (6.8 %); transcritical bump
+4.4 % (27 %); bump with shock 7.3 % (12 %). The transcritical and shock
+residuals are the 25-cell crest resolution of those decks — the 1D
+finite-volume solver of @ref hydraulics_ref_ch8_finite_volume "Chapter 8"
+sits at 7.5 % and 2.5 % on the same cases.
+
+### 9.2.3 The diffusive-wave closure
+
+`MOMENTUM_EQUATION DIFFUSIVE_WAVE` drops both accelerations, so the
+momentum equation reduces to the quasi-steady Manning balance of the
+free-surface slope (Hunter et al., 2005; the explicit diffusive wave of
+LISFLOOD-FP):
+
+| | | | |
+|---|---|---|---|
+| \f[\mathbf{q} = -\,\frac{h^{5/3}}{n}\,\frac{\nabla\eta}{\sqrt{\lvert\nabla\eta\rvert}}\f] | Momentum, diffusive wave | (9-32) | |
+
+The prognostic state is the cell volume alone; a face discharge is
+recomputed from the two adjacent surfaces at every firing and carries no
+memory. Substituting (9-32) into (9-1) gives a nonlinear diffusion
+equation, \f$\partial h/\partial t = \nabla\cdot(K\nabla\eta)\f$ with
+\f$K = h^{5/3}/(n\sqrt{\lvert\nabla\eta\rvert})\f$, and that is both the
+closure's merit and its cost. Steady uniform flow is exact, slow
+floodplain inundation is well represented, and there is nothing to damp:
+no \f$\theta\f$ blend and no Froude clamp are applied. But an explicit
+integration of a diffusion equation is bounded by \f$\Delta t \le L^{2}/(4K)\f$
+— the \f$\Delta x^{2}\f$ restriction that the local-inertial term of §9.2.1
+exists to remove — and the conductance \f$K\f$ diverges on a flat surface,
+the classic explicit diffusive-wave failure. §9.5.11 gives the face law
+with its slope floor and the per-cell step bound. The closure is
+affordable here only because the tiered local time stepping of §9.5.6
+lets each cell pay its own step.
+
+Table 9-2 summarizes the three closures and the retired spelling that
+preceded `FULL_SWE`.
+
+| Closure | Prognostic state | Face law | Valid regime | Cost | Status |
+|---|---|---|---|---|---|
+| `LOCAL_INERTIAL` (default) | \f$V\f$ per cell, \f$q\f$ per face | de Almeida and Bates, (9-7)–(9-10) | \f$Fr \lesssim 0.5\f$: ponds, streets, floodplains | 1× | \status{Implemented} |
+| `FULL_SWE` | \f$V\f$, \f$hu\f$, \f$hv\f$ per cell | hydrostatic reconstruction (9-36), rotated HLLC (9-38), bed-slope correction (9-39), semi-implicit friction per cell (9-40) | all Froude numbers: transcritical control, jumps, dam breaks, drawdown over crests | ≈ 2–3× (Courant ≤ ½ on \f$2A/P\f$, (9-41)); CPU marcher only | \status{Implemented} |
+| `DIFFUSIVE_WAVE` | \f$V\f$ per cell | Manning quasi-steady balance (9-42) with a slope floor | slow floodplain inundation; steady uniform flow (exact) | \f$\Delta x^{2}\f$-bound steps (9-43), carried by the LTS tiers; CPU marcher only | \status{Implemented} |
+| `ADVECTION YES` | as `LOCAL_INERTIAL` | (9-7) plus a staggered upwind convective term (Stelling and Duinmeijer, 2003) | — | — | \status{Retired} |
+
+*Table 9-2 Momentum closures of the 2D marcher*
+
+`ADVECTION YES` is the deprecated (2026-09-06) spelling of the
+convective-term experiment that `FULL_SWE` superseded. A deck that still
+carries it is accepted with a warning naming the replacement and keeps
+the physics it asked for — the local-inertial law with the upwind
+convective difference added to (9-7) on wet–wet faces — rather than being
+remapped, so an old calibrated model does not change its answer silently.
+New models should not use it.
+
+
+
+
 
 ## 9.3 The computational mesh
 
@@ -178,6 +438,89 @@ the cell velocities. Without the latter a model can only start from
 rest, which excludes solutions such as Thacker's oscillating basins
 whose initial state has \f$\mathbf{u} \neq 0\f$.
 
+### 9.3.1 Quadrilateral cells
+
+The mesh may mix triangles with convex quadrilaterals. Quads are listed
+in `[2D_QUADS]` after every triangle, by four vertex indices in cyclic
+order (either orientation — the builder orients every edge normal
+outward from the centroid), with the same roughness, initial-depth and
+tag columns as `[2D_TRIANGLES]`:
+
+```
+[2D_QUADS]
+;;V1  V2  V3  V4  MANNINGS_N  [INIT_DEPTH]  [TAG]
+```
+
+**Cells are numbered triangles first, then quads**, each in file order:
+the \f$j\f$-th quad row is cell \f$n_{tri} + j\f$. Every cell-addressed
+section — `[2D_BOUNDARY_CONDITIONS]`, `[2D_BOUNDARY_QUALITY]`,
+`[2D_INITIAL_VELOCITY]`, `[2D_TRIANGLE_NODE_MAP]`, `[2D_INFILTRATION]` —
+uses this unified index, and their column headers keep the word `TRI`. A
+`[2D_TRIANGLES]` row appearing after a `[2D_QUADS]` row is a parse error,
+which is what keeps the numbering unambiguous. A non-convex or
+self-intersecting quad fails mesh validation with the cell index and
+vertex list; the GUI mesher must never emit one.
+
+Every per-cell and per-edge array is padded to four slots per cell
+(`kMaxCellVerts`), so slot \f$4t + k\f$ addresses local edge \f$k\f$ of cell
+\f$t\f$ whatever its vertex count \f$n_v\f$; a padding slot has zero geometry
+and a neighbour index of \f$-2\f$, so a stray read is inert. **Local edge
+\f$k\f$ has endpoints \f$v_{(k+1) \bmod n_v}\f$ and \f$v_{(k+2) \bmod n_v}\f$.** For
+a triangle this is exactly the opposite-vertex rule of §9.3, so every
+existing `TRI EDGE` row keeps its meaning; for a quad it is a fixed
+rotation of the natural numbering — edge 0 is \f$(v_2, v_3)\f$, edge 1
+\f$(v_3, v_4)\f$, edge 2 \f$(v_4, v_1)\f$ and edge 3 \f$(v_1, v_2)\f$ — and the
+`EDGE` column of a boundary row ranges 0..3. The adjacency hash of §9.3
+is unchanged: an edge claimed twice is interior whichever shapes claim
+it, and a face between a triangle and a quad is an ordinary face. All
+of the face kernels — the three closures of §9.2, the positivity share,
+the transport — see only \f$(h_f, S, n_f, \xi, 1/d_n)\f$ and carry no
+shape branch.
+
+Three quantities need care on a quad. Its **area** is the shoelace
+area, computed as the sum of the two sub-triangles \f$(v_0, v_1, v_2)\f$ and
+\f$(v_0, v_2, v_3)\f$. Its **centroid** is the area-weighted centroid of
+those two sub-triangles — a property of the polygon, independent of
+which diagonal is used — and not the vertex mean, which is not the
+centroid of a skewed quad and would bias the Perot arms of (9-16) and
+the ghost-cell distance of §9.6. Its **mean bed** \f$z_c\f$, used by the
+`FLAT` closure, is the mean of the four vertex elevations. The
+centroid-to-edge distance that a triangle's stage boundary wrote as
+\f$2A/(3L)\f$ is generalized to the normal distance from the centroid to
+the edge midpoint,
+
+| | | | |
+|---|---|---|---|
+| \f[d_{e} = (\mathbf{m}_{e} - \mathbf{x}_{c})\cdot\hat{\mathbf{n}}_{e}\f] | | (9-33) | |
+
+which equals \f$2A/(3L)\f$ for a triangle (that expression *is* the
+centroid-to-edge distance) and is exact for a quad; the triangle
+expression is retained verbatim in the solver so an all-triangle mesh
+stays bit-identical. Two other constants scale with the vertex count:
+the positivity share of (9-15) becomes \f$\beta/n_v\f$ per exporting face,
+since a cell's at most \f$n_v\f$ outgoing faces may take at most \f$\beta V\f$
+in total, and a quad none of whose edges is an interior face keeps
+\f$L_{char} = 2\min_k d_{e,k}\f$ instead of the altitude proxy (which is
+\f$\Delta x\f$ for a square and conservative for a skewed cell). The
+isoperimetric length \f$2A/P\f$ that bounds the `FULL_SWE` step (§9.5.10)
+is computed over all \f$n_v\f$ edges.
+
+Under `CELL_CLOSURE VFR` a quad uses the two-plane storage model of
+§9.4.2. Results of a mixed mesh are written as UGRID mixed topology —
+`Mesh2_face_nodes [nFace, 4]` with `_FillValue = -1`, plus a
+`Mesh2_face_nv` vertex-count array — and the edge datasets and the bulk
+C-API edge arrays use stride 4; an all-triangle mesh keeps the
+`[nFace, 3]`, stride-3 layout byte for byte. The Kokkos plugin backends
+serve all-triangle meshes only; a mixed mesh is announced and run on the
+CPU marcher (§9.11.1).
+
+
+![Figure 9-4](figures/png/hydraulics_ch9_mesh_stencil.png)
+
+*Figure 9-4 A quadrilateral and a triangle sharing a face: local edge numbering, the padded slot layout and the centroid-to-edge distance*
+
+
+
 ## 9.4 Volume–free-surface closure
 
 The conserved variable is cell **volume** \f$V\f$ rather than depth. Depth follows
@@ -309,7 +652,7 @@ and inverse are exact inverses for the same \f$\varepsilon\f$ and
 head-seeded and volume-seeded states round-trip. A dry cell's head
 under VFR is seeded at \f$\eta(0) = \eta_s - \bar{h}_s/\varepsilon \in (z_1, \eta_s)\f$, the value the closure itself returns at \f$V = 0\f$, so
 that seeding the head back through the forward relation reproduces
-exactly zero volume. Figure 9-2 (§9.5.9) sketches the wetting cases.
+exactly zero volume. Figure 9-3 (§9.5.9) sketches the wetting cases.
 
 Implementation: the closure lives in `src/engine/2d/mesh/VfrClosure.hpp`
 — @ref openswmm::twoD::vfrSort3, @ref openswmm::twoD::vfrWetFraction,
@@ -323,6 +666,101 @@ Implementation: the closure lives in `src/engine/2d/mesh/VfrClosure.hpp`
 `src/engine/2d/solver/InertialKernels.hpp`, whose `FLAT` branch is
 (9-5); the flat-relief guard is `kVfrFlatRelief` (\f$10^{-9}\f$ m).
 
+### 9.4.2 The two-plane VFR closure of a quadrilateral
+
+Four vertices do not in general lie on a plane, so the planar-bed
+relations (9-6) do not apply to a quad directly. Begnudelli and Sanders
+(2007) budget the storage of a quadrilateral cell by splitting it along
+one diagonal into two planar sub-triangles, and their piecewise cubic,
+quadratic and linear stage–storage relations (their Eqs. 8–13, with the
+coefficient tables of their appendix) are exactly the area-weighted sum
+of the two planar-triangle closures. The diagonal is chosen from the
+elevation ordering of the four vertices, \f$n_1 \le n_2 \le n_3 \le n_4\f$,
+so that the split follows the fold of the surface:
+
+| Case | Topology | Diagonal | Sub-triangles |
+|---|---|---|---|
+| 1 | \f$n_1\f$ and \f$n_4\f$ diagonally opposite | \f$n_1\f$–\f$n_4\f$ | \f$(n_1, n_2, n_4)\f$ and \f$(n_1, n_3, n_4)\f$ |
+| 2 | \f$n_1\f$ and \f$n_4\f$ adjacent, \f$n_2\f$ adjacent to \f$n_1\f$ | \f$n_2\f$–\f$n_4\f$ | \f$(n_1, n_2, n_4)\f$ and \f$(n_2, n_3, n_4)\f$ |
+| 3 | \f$n_1\f$ and \f$n_4\f$ adjacent, \f$n_2\f$ adjacent to \f$n_4\f$ | \f$n_3\f$–\f$n_4\f$ | \f$(n_1, n_3, n_4)\f$ and \f$(n_2, n_3, n_4)\f$ |
+
+*Table 9-3 Diagonal selection of the two-plane quadrilateral closure
+(Begnudelli and Sanders, 2007, Cases 1–3)*
+
+Ties in elevation keep cyclic order (a stable sort), and any consistent
+choice is a valid split. With sub-triangle areas \f$A_1, A_2\f$ and each
+sub-triangle's sorted elevations, the cell-mean depth at stage \f$\eta\f$ is
+
+| | | | |
+|---|---|---|---|
+| \f[\bar{h}(\eta) = \frac{A_{1}\,\bar{h}_{1}(\eta) + A_{2}\,\bar{h}_{2}(\eta)}{A_{1} + A_{2}}\f] | | (9-34) | |
+
+where \f$\bar{h}_{1}, \bar{h}_{2}\f$ are the regularized planar-triangle
+relations of §9.4.1 — (9-6) above each sub-triangle's switch stage, the
+tangent (9-22) below it, floored at zero — evaluated with the same
+\f$\varepsilon\f$. Quads and triangles therefore share one regularization
+and one round-trip contract, and the closed-form appendix coefficients
+are an optimization the engine does not need. The slope of the sum,
+which the Newton inverse uses, is
+
+| | | | |
+|---|---|---|---|
+| \f[\frac{d\bar{h}}{d\eta} = \frac{A_{1}\,w_{1}^{*}(\eta) + A_{2}\,w_{2}^{*}(\eta)}{A_{1} + A_{2}}\f] | | (9-35) | |
+
+with \f$w_{k}^{*}\f$ the wetted fraction (9-20) of sub-triangle \f$k\f$ above
+its switch stage, \f$\varepsilon\f$ inside its linear tail, and zero once
+that tail has reached zero depth.
+
+The inverse \f$\eta(\bar{h})\f$ follows the same case ladder as §9.4.1,
+with two differences in the fully wet and dry limits. Let \f$\bar{z}_w\f$ be
+the area-weighted mean of the two sub-triangle mean beds — the true
+mean bed of the two-plane surface — and \f$z_{top}\f$, \f$z_{low}\f$ the
+highest and lowest of the six sorted elevations:
+
+1. **Flat cell.** \f$z_{top} - z_{low} < 10^{-9}\f$ m: \f$\eta = \bar{z}_w + \max(\bar{h}, 0)\f$.
+2. **Fully wet.** \f$\bar{h} \ge z_{top} - \bar{z}_w\f$: both sub-triangles
+   are submerged and \f$\eta = \bar{z}_w + \bar{h}\f$ exactly.
+3. **Dry.** \f$\bar{h} \le 0\f$: \f$\eta\f$ is the lower of the two
+   sub-triangles' dry stages \f$\eta_s - \bar{h}_s/\varepsilon\f$ — the
+   stage at which the regularized sum reaches zero.
+4. **Otherwise** a safeguarded Newton iteration on the monotone sum
+   (9-34) over the bracket \f$[\eta_{dry}, z_{top}]\f$, started from the
+   flat guess \f$\bar{z}_w + \bar{h}\f$ (or the bracket midpoint if that
+   lies outside it), with derivative (9-35); a step leaving the bracket
+   is replaced by bisection, and iteration stops at
+   \f$\lvert\Delta\eta\rvert < 10^{-13}(1 + R)\f$ with an 80-iteration cap.
+
+The derivative the coupling needs, \f$d\eta/d\bar{h} = 1/\max(w^{*}, \varepsilon)\f$,
+is bounded by \f$1/\varepsilon\f$ as on a triangle.
+
+One consequence deserves stating. The `FLAT` closure (9-5) writes a quad's
+bed as the vertex mean \f$z_c = \tfrac{1}{4}\sum z\f$, whereas the fully wet
+branch of the two-plane relation uses \f$\bar{z}_w\f$, the mean bed of the
+folded surface. The two coincide for a planar quad and differ otherwise,
+so on a non-planar quad the two closures disagree even when the cell is
+fully wet, by the difference of the two bed means — the flat closure is
+exact for a fully wetted cell only when \f$z_c\f$ is the cell's true mean
+bed, which for a quad the vertex mean is not. Wetting and drying
+classification is unchanged: the `H_MOVE` hysteresis of §9.5.7 acts on
+the cell-mean depth, and the paper's alternative vertex-wise criterion is
+not adopted — its threshold needed per-roughness tuning in the authors'
+own tests, and the flux-active set already plays that role.
+
+Implementation: `src/engine/2d/mesh/QuadVfr.hpp` — `quadVfrPrecompute`
+selects the diagonal once per quad and stores the six sorted elevations
+and the two areas; `quadMeanDepthFromEta`, `quadWetFraction`,
+`quadMeanDepthSlope`, `quadEtaFromMeanDepth` and `quadDEtaDMeanDepth`
+are (9-34), (9-35) and the ladder above. The solver enters through
+@ref openswmm::twoD::inertial::etaDepthQuadScalar and
+@ref openswmm::twoD::inertial::volumeFromEtaQuadScalar in
+`src/engine/2d/solver/InertialKernels.hpp`; the quad branch of
+`cellEtaDepth` is kept out of line on purpose, because inlining its
+Newton loop stopped the compiler inlining the triangle path that every
+cell of every mesh runs. The `MeshBuilder` computes the per-quad data
+(`quad_vfr_z`, `quad_vfr_a`) after the cell geometry.
+
+
+
 ## 9.5 Numerical scheme
 
 The discretization is a cell-centred finite-volume method with a
@@ -593,6 +1031,36 @@ regardless of their Courant number — boundary cells and cells carrying a
 1D coupling point. For these cells the forcing, rather than the
 celerity, sets the resolution requirement.
 
+The per-cell step that feeds the tier assignment is closure-specific:
+(9-17) under the local-inertial law, the Courant bound (9-41) on the
+isoperimetric length under `FULL_SWE`, and the diffusion bound (9-43)
+under `DIFFUSIVE_WAVE`. Each is capped by `MAX_TIMESTEP`, and the tiers
+are built from whichever applies.
+
+**Global-step mode.** `RECONSTRUCTION_ORDER 2` under `FULL_SWE`
+(§9.5.10) integrates with a two-stage SSP-RK2 scheme over the global
+active lists, and a two-stage scheme cannot be tiered: `LTS_TIERS` is
+reduced to 1 with a notice and every active cell and face fires each
+substep at \f$\Delta t_0\f$. `LTS_TIERS 1` selects the same mode by hand for
+any closure; it is bit-identical to the tiered path on a mesh where
+tiering finds nothing to separate.
+
+**Front-cadence tiers.** Under `FRONT_REBUILD` (§9.5.7) the dry cells of
+the widened halo would otherwise be assigned the coarsest tier — a dry
+cell's (9-17) is unbounded — so a front could enter them only every
+\f$2^{K-1}\f$ substeps regardless of how wide the halo is. After the tier
+assignment, every dry active cell is therefore pulled down to the finest
+tier among its active neighbours, and the pull is propagated across the
+halo rings by a Gauss–Seidel sweep over the faces (at most five passes,
+stopping early when nothing changes). The sweep is kept serial on
+purpose: a Jacobi form reaches a different fixed point inside the ring
+budget, and on the Bellinge 30-minute slice that difference changed the
+`DIFFUSIVE_WAVE` inflow and spill volumes materially for a 4 % saving on
+the `FULL_SWE` deck alone. The receiving cells then update at the
+front's own cadence.
+
+
+
 ### 9.5.7 The active set
 
 Most of a rain-on-grid mesh is not flowing. A cell is **flux-active**
@@ -625,6 +1093,40 @@ cycles rather than every substep; the cost of the rebuild is \f$O(n_{cells})\f$
 and dominated everything else when it ran per routing step on a large
 mesh.
 
+**Front-triggered rebuilds (`FRONT_REBUILD`).** Between rebuilds the
+active set is frozen, so a wetting front can cross at most one cell ring
+per rebuild period. Under the local-inertial law that is not a practical
+restriction (§9.5.9): a fast front implies a small \f$\Delta t_0\f$, so the
+four-cycle period shrinks with the front's own time scale. A Godunov
+front under `FULL_SWE` is different — it travels at about \f$2\sqrt{gh}\f$,
+one cell per base substep at Courant ½, and crosses the one-ring halo
+inside a single macro cycle, after which it stalls until the next
+rebuild. That stall is what pinned the Ritter and Thacker results before
+the option existed. `FRONT_REBUILD` replaces the fixed cadence with a
+breach trigger. The halo is widened to five rings (`kFrontHaloRings`,
+enough for such a front to cross a macro cycle of \f$2^{K-1}\f$ substeps),
+its outer ring — an active cell with an inactive neighbour — is marked
+as the *frontier*, and a cell firing that finds a frontier cell at or
+above the activation depth \f$h_{on}\f$ of the last rebuild raises a breach
+flag; the next macro cycle then rebuilds immediately instead of waiting
+out the cadence. The dry cells of the widened halo are pulled to the
+front's tier cadence (§9.5.6), since a wide halo of cells that fire only
+at the coarsest tier would stall the front just as surely.
+
+`AUTO` (the default) switches the trigger on under `FULL_SWE` only. It
+stays off under `LOCAL_INERTIAL`, which keeps that closure bit-identical
+to its earlier results, and off under `DIFFUSIVE_WAVE`, whose
+\f$\Delta x^{2}\f$-bounded step moves a front a fraction of a cell per macro
+cycle so the cheap cadence suffices. `YES` and `NO` force it either way
+for any closure.
+
+
+![Figure 9-5](figures/png/hydraulics_ch9_active_set.png)
+
+*Figure 9-5 The flux-active set at a wetting front: the default one-ring halo, the front-rebuild halo and the breach that forces an early rebuild*
+
+
+
 ### 9.5.8 Data layout and the substep algorithm
 
 The solver's working set is three structure-of-arrays blocks, sized
@@ -699,9 +1201,10 @@ The boundary and coupling loops are serial; they are perimeter- and
 point-count-sized. The quantity \f$\sum_i V_i + \sum_f (\text{acc}_{L,f} + \text{acc}_{R,f})\f$ is invariant under the face phase and is asserted
 directly when `OPENSWMM_2D_MARCHER_CHECK` is set.
 
-Figure 9-1 assembles the co-advance batch of §9.7.3 and the marcher's
+Figure 9-2 assembles the co-advance batch of §9.7.3 and the marcher's
 substep loop into one workflow.
 
+
 
 flowchart TD
     A[1D routing step completes - node heads current] --> B{Pending span reaches the sync batch}
@@ -726,7 +1229,7 @@ flowchart TD
     Q --> A
 

 
-*Figure 9-1 One 1D–2D co-advance batch and the explicit marcher's
+*Figure 9-2 One 1D–2D co-advance batch and the explicit marcher's
 substep loop within it (rendered diagram)*
 
 Implementation:
@@ -842,22 +1345,13 @@ cell integrates in a single lazy pass over the whole interval since
 the last synchronization; the result is floored at zero volume, so a
 forced evaporation override on a dry cell is harmless.
 
-Figure 9-2 sketches the geometry the rules act on: the three wetting
+Figure 9-3 sketches the geometry the rules act on: the three wetting
 cases of the planar-bed cell (§9.4.1) and the wetted-edge face gate
 (§9.5.2).
 
-
-![Figure 9-2](figure9-2-placeholder.png)
-
-*Figure 9-2 Wetting cases of a planar-bed triangular cell and the
+![Figure 9-3](figures/png/hydraulics_ch9_vfr_wetting_cases.png)
+
+*Figure 9-3 Wetting cases of a planar-bed triangular cell and the
 wetted-edge face gate (placeholder — to be replaced by a final
 drawing)*
 
@@ -875,46 +1369,330 @@ evaporation taper is @ref openswmm::twoD::evapSink
 (`src/engine/2d/solver/SurfaceFluxCalculator.hpp`). The slope deadband
 is `kEtaDeadband` in `src/engine/2d/solver/InertialKernels.hpp`.
 
+### 9.5.10 The full shallow-water face flux
+
+Under `MOMENTUM_EQUATION FULL_SWE` a face firing evaluates one Godunov
+flux from the two adjacent cell states — free surface \f$\eta\f$, mean depth
+\f$\bar{h}\f$ and cell momentum \f$\mathbf{q} = (hu, hv)\f$ — and books mass and
+momentum on both sides from the same products. The steps, in the order
+coded:
+
+**Hydrostatic reconstruction.** Each side's bed is taken consistent with
+its storage, \f$z_L = \eta_L - \bar{h}_L\f$ and \f$z_R = \eta_R - \bar{h}_R\f$ —
+the cell mean bed under `FLAT`, the flat-equivalent bed under `VFR`,
+which is what keeps a uniform \f$\eta\f$ an exact rest state under either
+closure — and both depths are reconstructed against the higher of the
+two (Audusse et al., 2004):
+
+| | | | |
+|---|---|---|---|
+| \f[z_{f} = \max(z_{L}, z_{R}), \qquad h_{L}^{*} = \max(0,\ \eta_{L} - z_{f}), \qquad h_{R}^{*} = \max(0,\ \eta_{R} - z_{f})\f] | | (9-36) | |
+
+A side whose cell depth is at or below `DRY_DEPTH`, or whose
+reconstructed depth vanishes, carries zero velocity, which removes the
+\f$q/h\f$ blow-up at fronts; the reconstruction alone already removes the
+"dry cell standing higher" flux. A face dry on both sides carries
+nothing and books nothing. The velocities are rotated into the face
+frame, \f$u_n = \mathbf{u}\cdot\hat{\mathbf{n}}\f$ and
+\f$u_t = \mathbf{u}\cdot\hat{\mathbf{t}}\f$ with \f$\hat{\mathbf{t}} = (-n_y, n_x)\f$.
+
+**Wave speeds.** With \f$c = \sqrt{g h^{*}}\f$ on each side, the
+two-rarefaction estimate (Toro, 2001, §10.4) for a wet–wet face and the
+exact dry-bed front speeds otherwise:
+
+| | | | |
+|---|---|---|---|
+| \f[u^{\star} = \tfrac{1}{2}(u_{L} + u_{R}) + c_{L} - c_{R}, \qquad c^{\star} = \tfrac{1}{2}(c_{L} + c_{R}) + \tfrac{1}{4}(u_{L} - u_{R})\f] | wet–wet | (9-37a) | |
+| \f[S_{L} = \min(u_{L} - c_{L},\ u^{\star} - c^{\star}), \qquad S_{R} = \max(u_{R} + c_{R},\ u^{\star} + c^{\star})\f] | wet–wet | (9-37b) | |
+| \f[S_{L} = u_{L} - c_{L}, \qquad S_{R} = u_{L} + 2c_{L}\f] | dry right | (9-37c) | |
+| \f[S_{L} = u_{R} - 2c_{R}, \qquad S_{R} = u_{R} + c_{R}\f] | dry left | (9-37d) | |
+
+**The HLLC flux.** On the state \f$\mathbf{U} = [h,\ h u_n,\ h u_t]\f$ with
+physical flux \f$\mathbf{F} = [h u_n,\ h u_n^{2} + \tfrac{1}{2} g h^{2},\ h u_n u_t]\f$,
+
+| | | | |
+|---|---|---|---|
+| \f[\mathbf{F}_{f} = \mathbf{F}_{L}\ \ (S_{L} \ge 0); \qquad \mathbf{F}_{f} = \mathbf{F}_{R}\ \ (S_{R} \le 0); \qquad \text{else}\ \ F_{h,n} = \frac{S_{R}F_{L} - S_{L}F_{R} + S_{L}S_{R}(U_{R} - U_{L})}{S_{R} - S_{L}}\f] | mass and normal momentum | (9-38a) | |
+| \f[F_{t} = F_{h}\,u_{t}^{up}, \qquad S^{\star} = \frac{S_{L}\,d_{R} - S_{R}\,d_{L}}{d_{R} - d_{L}}, \quad d = h^{*}(u_{n} - S)\f] | tangential momentum | (9-38b) | |
+
+The HLL middle state serves mass and normal momentum; the tangential
+momentum is a passive scalar upwinded on the contact speed \f$S^{\star}\f$
+(Toro, 2001, Eq. 10.70), which falls back to the mean normal velocity
+when both sides are at rest. Species ride the mass flux from the side
+\f$S^{\star}\f$ points away from. The momentum flux is rotated back to
+\f$(x, y)\f$.
+
+**The bed-slope correction.** Each side receives, per unit face length,
+
+| | | | |
+|---|---|---|---|
+| \f[\mathbf{c}_{L} = \tfrac{1}{2}\,g\left( h_{L}^{*2} - \bar{h}_{L}^{2} \right)\hat{\mathbf{n}}, \qquad \mathbf{c}_{R} = -\,\tfrac{1}{2}\,g\left( h_{R}^{*2} - \bar{h}_{R}^{2} \right)\hat{\mathbf{n}}\f] | | (9-39) | |
+
+At rest the HLLC flux is \f$[0,\ \tfrac{1}{2} g h^{*2},\ 0]\f$ and (9-39)
+cancels it face by face, so a lake at rest over any bed is an exact
+steady state — the C-property of §9.5.3 in conservative form. Walls
+close the same balance: every `WALL` boundary slot of a wet cell
+contributes a mirror-state Riemann flux (same depth, reversed normal
+velocity) that carries no mass but \f$\tfrac{1}{2} g h^{2}\f$ of normal
+momentum, booked at the cell's own cadence from a per-cell list of wall
+slots; without it a cell at rest beside a wall would accelerate away
+from it.
+
+**Booking.** The per-edge conveyance factor of §9.3 scales the whole
+flux vector. The positivity share of (9-15), with \f$\beta/n_v\f$ per face,
+scales mass and momentum together so the two stay consistent; under
+this closure it is a backstop rather than the guarantee (below). The
+stored face discharge is the limited mass flux, \f$\pm\Delta M\f$ is booked
+into the volume accumulators exactly as in (9-13), and the momentum
+accumulators receive \f$(-\mathbf{F} + \mathbf{c}_{L})\,\xi\,\Delta t_f\f$ on
+the exporter side and \f$(+\mathbf{F} + \mathbf{c}_{R})\,\xi\,\Delta t_f\f$
+on the receiver side.
+
+**The cell update.** A cell firing gathers its volume by (9-14) and its
+momentum by
+
+| | | | |
+|---|---|---|---|
+| \f[\mathbf{q}^{\,n+1} = \frac{A\,\mathbf{q}^{\,n} + \sum_{f}\text{macc}_{f,i}}{A}\ \Big/\ \left( 1 + \frac{g\,\Delta t_{c}\,n^{2}\,\lvert\mathbf{q}\rvert}{h_{new}^{7/3}} \right)\f] | | (9-40) | |
+
+— the gathered momentum, then semi-implicit Manning friction against the
+**new** depth, which can only shrink \f$\lvert\mathbf{q}\rvert\f$. Sources
+(rain, coupling, infiltration, evaporation) move volume only, so the
+velocity adjusts with the depth; a cell that fell to `DRY_DEPTH` or below
+carries no momentum. The cell momentum stands in for the Perot vector
+(9-16) of the default closure wherever the marcher needs a cell velocity.
+
+**The step bound.** First-order Godunov with hydrostatic reconstruction
+is positivity-preserving at a Courant number of one half on triangles
+and quadrilaterals, and the bound is enforced rather than assumed:
+
+| | | | |
+|---|---|---|---|
+| \f[\Delta t_{i} = \alpha\,\frac{2A_{i}/P_{i}}{\sqrt{g h_{i}} + \lvert\mathbf{u}_{i}\rvert}, \qquad \alpha \le \tfrac{1}{2}\f] | | (9-41) | |
+
+with \f$P_i\f$ the cell perimeter. `CFL_NUMBER` above ½ is reduced to ½ with
+a notice. The isoperimetric length replaces \f$L_{char}\f$ of (9-4) because
+the positivity argument is about the volume a cell's faces can remove in
+one step, not about the odd–even mode of the staggered operator.
+
+**Second order (`RECONSTRUCTION_ORDER 2`).** A Green–Gauss gradient of
+\f$(\eta, u, v)\f$ is formed over each active cell — the face value is the
+mean of the two cells, and a boundary face contributes the cell's own
+value (zero gradient) — and limited per variable with the
+Barth–Jespersen factor against the minimum and maximum over the cell
+and its face neighbours. Cells that are dry, thin (below ten times
+`DRY_DEPTH`) or touching a dry or inactive cell fall back to first order,
+so the wet–dry front keeps the monotone update. Each side's face state
+is extrapolated along the precomputed centroid-to-midpoint arm; the bed
+stays piecewise constant per cell, and the correction (9-39) pairs
+\f$h^{*}\f$ with the reconstructed face depth \f$\eta_f - z_{cell}\f$, so a
+linear surface keeps its interface pressure difference and zero
+gradients reduce exactly to the first-order well-balanced form. Time
+integration is SSP-RK2 (Heun): \f$\mathbf{U}^{1} = \mathbf{U}^{0} + \Delta t\,L(\mathbf{U}^{0})\f$,
+\f$\mathbf{U}^{2} = \mathbf{U}^{1} + \Delta t\,L(\mathbf{U}^{1})\f$,
+\f$\mathbf{U}^{n+1} = \tfrac{1}{2}(\mathbf{U}^{0} + \mathbf{U}^{2})\f$, over
+the global active lists (§9.5.6), with every per-advance ledger that both
+stages incremented — boundary and coupling volumes, infiltration, the
+node spill budgets — reset to its trapezoidal value. Second order is
+refused with a notice when overland transport is active.
+
+Implementation: `src/engine/2d/solver/SweKernels.hpp` — `faceFlux`
+(first order), `faceFluxRecon` (second order), `hllcFlux`, `waveSpeeds`,
+`bjLimiter`, `frictionUpdate`; the face firing is
+@ref openswmm::twoD::ExplicitInertialSolver::fireFacesSwe, the momentum
+gather and wall booking are the `FULL_SWE` branch of `fireCells`, the
+gradients are `computeLimitedGradientsSwe` and the two-stage step is
+`runRk2Step` in `src/engine/2d/solver/ExplicitInertialSolver.cpp`; the
+perimeter length is `cell_lpos` in `InertialEdges`.
+
+
+
+### 9.5.11 The diffusive-wave face law and its \f$\Delta x^{2}\f$ bound
+
+Under `MOMENTUM_EQUATION DIFFUSIVE_WAVE` a face firing evaluates the
+face depth exactly as the default closure does — (9-11) under `MEAN`,
+(9-12) under `VFR_FACE`, a wall at or below `DRY_DEPTH` with the
+discharge zeroed — applies the \f$10^{-12}\f$ m deadband of §9.5.3 to the
+free-surface difference, and then replaces (9-7) with the quasi-steady
+Manning balance,
+
+| | | | |
+|---|---|---|---|
+| \f[q_{f} = -\,\frac{h_{f}^{5/3}\,S}{n_{f}\,\sqrt{\max(\lvert S \rvert,\ S_{\varepsilon})}}, \qquad S = \frac{\eta_{R} - \eta_{L}}{d_{n}}, \qquad S_{\varepsilon} = \frac{\text{FLUX\_DH\_EPS}}{d_{n}}\f] | | (9-42) | |
+
+with \f$n_f = \tfrac{1}{2}(n_L + n_R)\f$ the face roughness. The floor
+\f$S_{\varepsilon}\f$ is what makes an explicit diffusive wave usable:
+without it the conductance \f$h^{5/3}/(n\sqrt{\lvert S\rvert})\f$ diverges
+as the surface flattens, and the flux across a nearly level pond grows
+without bound. Below the floor the discharge is linear in \f$S\f$, which
+keeps the C-property — the flux still vanishes with the slope — while
+bounding the transmissivity. `FLUX_DH_EPS` is a head difference (default
+4 mm), so the floor scales with the face spacing. The conveyance factor,
+the positivity share \f$\beta/n_v\f$ of (9-15) and the booking (9-13) are
+those of the default closure, and the face discharge is recomputed from
+scratch at every firing — nothing is remembered from the previous one.
+
+Substituting (9-42) into (9-1) makes the scheme a nonlinear diffusion
+\f$\partial h/\partial t = \nabla\cdot(K\nabla\eta)\f$, \f$K = h^{5/3}/(n\sqrt{\lvert S\rvert})\f$,
+and the explicit step of such an equation is bounded by
+\f$\Delta t \le L^{2}/(4K)\f$. Per cell,
+
+| | | | |
+|---|---|---|---|
+| \f[\Delta t_{i} = \alpha\,\frac{L_{char,i}^{2}\,n_{i}\,\sqrt{S_{max,i}}}{4\,h_{i}^{5/3}}, \qquad S_{max,i} = \max\!\left( \max_{f}\lvert S_{f}\rvert,\ \frac{\text{FLUX\_DH\_EPS}}{L_{char,i}} \right)\f] | | (9-43) | |
+
+with \f$\alpha =\f$ `CFL_NUMBER` reused as the safety fraction,
+\f$L_{char}\f$ the operator length of (9-4), and \f$S_{max}\f$ the largest
+free-surface slope over the cell's faces at the rebuild (walled faces
+count as zero); a dry cell is unbounded, and `MAX_TIMESTEP` caps the
+result. The slope census is refreshed at every rebuild and every
+\f$\Delta t_0\f$ re-minimization. Because the bound scales as \f$L^{2}\f$
+while (9-17) scales as \f$L\f$, a fine cell at a coupling point is
+punished far more severely under this closure, and the tier spread of
+§9.5.6 is what keeps the rest of the mesh from paying for it. No Froude
+clamp and no \f$\theta\f$ blend are applied — there is no inertia to damp.
+
+Boundary edges under this closure use the collapsed-Manning conductance
+of §9.6 for every type, and `FRONT_REBUILD` stays off by default because
+a diffusive front cannot outrun the fixed rebuild cadence (§9.5.7).
+
+Implementation: `src/engine/2d/solver/DiffusiveKernels.hpp` —
+`faceDischarge` is (9-42) and `cellDiffusiveDt` is (9-43); the face
+firing is @ref openswmm::twoD::ExplicitInertialSolver::fireFacesDiffusive
+and the slope census `refreshDiffusiveSlopes` in
+`src/engine/2d/solver/ExplicitInertialSolver.cpp`.
+
+
+
 ## 9.6 Boundary conditions
 
-Boundary edges — those claimed by only one triangle — default to
-no-flux walls. `[2D_BOUNDARY_CONDITIONS]` assigns any of five types per
-edge:
+Boundary edges — those claimed by only one cell — default to no-flux
+walls. `[2D_BOUNDARY_CONDITIONS]` assigns any of five types per edge:
+
+```
+[2D_BOUNDARY_CONDITIONS]
+;;TRI  EDGE  TYPE  [PARAM_1  [PARAM_2  [GROUP]]]
+```
 
 | Type | Parameter | Meaning |
 |---|---|---|
 | `WALL` | — | Zero flux (default) |
-| `NORMAL_FLOW` | bed slope \f$S\f$ | Manning outflow \f$q = h^{5/3}\sqrt{S}/n\f$ per metre of edge |
+| `NORMAL_FLOW` | signed bed slope \f$S\f$ | Manning flow \f$q = \mathrm{sign}(S)\,h^{5/3}\sqrt{\lvert S\rvert}/n\f$ per metre of edge; a positive slope falls away from the domain and drains it, a negative one feeds it with the interior depth (it cannot wet a dry cell) |
 | `SPECIFIED_STAGE` / `TS_STAGE` | head, or time series | Prescribed free-surface elevation |
 | `SPECIFIED_FLOW` / `TS_FLOW` | discharge per metre, or time series | Prescribed unit discharge, outward positive |
 | `RATING_CURVE` | curve name | Stage → unit discharge lookup, resolved each step from the boundary cell's stage |
 
+`TRI` is the cell index of §9.3.1 and `EDGE` the local edge — 0..2 for a
+triangle, 0..3 for a quad. `PARAM_2` is reserved and is written as `*`;
+it must be present whenever `GROUP` is. **`GROUP`** is an optional
+label, the sixth token of the row (`*` for none). It is stored with the
+row and written back by the `.inp` writer unchanged, and the engine
+never acts on it: it exists so that the edges of one shoreline, tidal
+reach or outfall line can be addressed together by a user interface or
+a script — assigned, re-typed or deleted as a set — without the engine
+having an opinion about which edges belong together. A row that writes a
+group also writes its `*` placeholder, so the two are never confused.
+
 Time series and curve names are resolved to registry indices once, on
 the first advance, and evaluated every routing step thereafter.
 Prescribed stages share the mesh's vertical datum and prescribed flows
 the project's flow units, so both are converted to SI on the same terms
-as the mesh itself (§9.7.4).
-
-**A stage boundary is integrated with the interior momentum law**, not
-with a conductance. The ghost state holds \f$\eta = \eta_{bc}\f$ with a
-zero-gradient discharge, sitting across the edge at the centroid-to-edge
-distance \f$2A/(3L)\f$, and (9-7) is applied to it exactly as to an interior
-face. The earlier treatment — a collapsed Manning flux toward the
-prescribed stage — was a diffusive-wave law grafted onto an inertial
-interior, and it showed: its conductance saturated the equilibrium
-clamp into a Dirichlet cell, and every boundary-driven steady case
-floated one head jump, of order \f$v^{2}/2g\f$, above the stage it had been
-given. The bump cases of §9.10 pass because of this change.
-
-A per-substep equilibrium clamp remains as a backstop: one substep may
-move a cell at most to the prescribed stage, never past it. At the
-inertial law's gravity-scale fluxes it rarely binds; on a tiny cell it
-prevents overshoot. Exchange is clamped in **volume** space and the
+as the mesh itself (§9.7.4). Under `FACE_RECONSTRUCTION VFR_FACE` every
+type conveys with the wetted-edge depth (9-12) of the driving surface
+over the boundary edge's own endpoint beds, so a cell whose water pools
+away from an outlet edge does not leak through it.
+
+How a boundary edge is integrated depends on the momentum closure.
+
+**Local inertial.** A stage boundary is integrated with the interior
+momentum law, not with a conductance. The ghost state holds
+\f$\eta = \eta_{bc}\f$ with a zero-gradient discharge, sitting across the edge
+at the centroid-to-edge distance \f$d_e\f$ of (9-33) — \f$2A/(3L)\f$ for a
+triangle — and (9-7) is applied to it exactly as to an interior face,
+followed by the Froude clamp (9-10). The earlier treatment — a collapsed
+Manning flux toward the prescribed stage — was a diffusive-wave law
+grafted onto an inertial interior, and it showed: its conductance
+saturated the equilibrium clamp into a Dirichlet cell, and every
+boundary-driven steady case floated one head jump, of order
+\f$v^{2}/2g\f$, above the stage it had been given. The bump cases of §9.10
+pass because of this change. A per-substep equilibrium clamp remains as
+a backstop: one substep may move a cell at most to the prescribed stage,
+never past it. At the inertial law's gravity-scale fluxes it rarely
+binds; on a tiny cell it prevents overshoot. The other three types apply
+their per-metre discharge directly — the Manning law above for
+`NORMAL_FLOW`, the prescribed value for `SPECIFIED_FLOW` and
+`RATING_CURVE` — and the edge's contribution is added to the cell's
+Perot vector (9-16), without which a cell fed through its boundary
+carried a systematic \f$(1-\theta)\f$ drag on every face.
+
+**Full shallow water.** Every boundary edge is a ghost-cell Riemann
+problem: the ghost state per type is chosen in the outward-normal frame
+and (9-36)–(9-39) are evaluated against it, giving both a mass flux and
+a momentum change for the cell.
+
+- `WALL` mirrors the normal velocity; the mass flux is zero and the
+  pressure balance is closed (§9.5.10).
+- `NORMAL_FLOW` prescribes the Manning mass flux above, with the ghost
+  velocity \f$q/h_i\f$; a zero slope, depth or roughness conveys nothing and
+  the ghost is a mirror — a bare zero-gradient ghost is an absorbing
+  boundary and drained a lake at rest through an inert outlet.
+- `SPECIFIED_STAGE` holds \f$\eta_{bc}\f$. For subcritical flow one
+  characteristic leaves the domain, so its Riemann invariant fixes the
+  ghost velocity for the prescribed depth,
+
+| | | | |
+|---|---|---|---|
+| \f[u_{n,g} = u_{n} + 2\left( \sqrt{g h_{i}} - \sqrt{g h_{g}} \right), \qquad h_{g} = \max(0,\ \eta_{bc} - z_{i})\f] | | (9-44) | |
+
+  rather than a bare copy of the interior velocity; under supercritical
+  outflow (\f$u_n \ge \sqrt{g h_i}\f$) no characteristic enters and the
+  ghost is transmissive — the prescribed stage cannot act.
+- `SPECIFIED_FLOW` and `RATING_CURVE` are flux boundaries: the mass flux
+  is the prescribed value verbatim, because the Riemann solve's own
+  mass flux is a wave-speed-weighted blend of the interior and
+  prescribed states that under-delivered the SWASHES bump inflows by
+  7–21 % and reversed a supercritical inlet outright. The ghost still
+  sets the momentum flux and keeps the Audusse pressure balance, so its
+  depth is the physical boundary depth: the critical depth
+  \f$(q^{2}/g)^{1/3}\f$ on a dry cell (dry-bed inflow), the interior depth
+  for outflow or supercritical inflow, and for subcritical inflow the
+  depth that the outgoing invariant \f$r = u_n + 2\sqrt{g h_i}\f$ and the
+  discharge together fix,
+
+| | | | |
+|---|---|---|---|
+| \f[2\sqrt{g}\,s^{3} - r\,s^{2} + q = 0, \qquad s = \sqrt{h_{g}}\f] | | (9-45) | |
+
+  solved by a safeguarded Newton iteration from the interior depth and
+  falling back to it when no physical root converges — a fallback costs
+  accuracy in the momentum flux, never conservation.
+
+No equilibrium clamp is applied under this closure — the Riemann flux is
+bounded by the two states — and when the availability clamp below
+shrinks the requested mass, the momentum already booked is rescaled in
+the same ratio.
+
+**Diffusive wave.** Every type is served by the collapsed-Manning
+conductance the local-inertial stage boundary retired: for
+`SPECIFIED_STAGE` the per-metre flux toward the prescribed stage is
+\f$-\,h_{up}^{5/3}\,\mathrm{sign}(\Delta\eta)\,\rho(\lvert\Delta\eta\rvert)/(n\sqrt{d_e})\f$
+with \f$h_{up}\f$ the upwind depth and \f$\rho\f$ the regularized square root
+of (9-27) with `FLUX_DH_EPS` in place of \f$\varepsilon_o\f$ — the same
+\f$C^{1}\f$ quadratic below the floor, the bare root above it — so the
+transmissivity stays bounded as the two surfaces level; the other three
+types apply their per-metre discharge as above. Under the default
+closure `FLUX_DH_EPS` is not consulted at all: the inertial stage law
+replaced the only place it acted.
+
+Whatever the closure, exchange is clamped in **volume** space and the
 booked flux re-derived from the applied change, so what is reported is
-exactly what was applied.
+exactly what was applied: the provisional volume is floored at zero, and
+under the local-inertial and diffusive laws a stage boundary is also
+held at the prescribed stage by the equilibrium clamp. Cumulative
+boundary volume is tracked per edge, outward positive, and enters the
+2D mass balance of §9.9.
 
-Cumulative boundary volume is tracked per edge, outward positive, and
-enters the 2D mass balance of §9.9.
+
 
 ## 9.7 Coupling to the one-dimensional network
 
@@ -1183,37 +1961,85 @@ orchestration and booking are
 forcing entry points are declared in
 `include/openswmm/engine/openswmm_2d.h`.
 
+### 9.7.6 Where the spill is booked (`COUPLING_IN_FLOODING`)
+
+The 1D routing continuity table of the status report carries a
+**2D Coupling Outflow** row for the water that leaves a coupled junction
+onto the mesh, separate from **Flooding Loss**. That split is the
+accurate reporting: a coupling transfer is not flooding — the water is
+still in the model, on the surface, and returns through the drains and
+the coupled outfalls. `COUPLING_IN_FLOODING YES` books the spill into the
+Flooding Loss row instead, and exists for one reason: comparing a run
+against a build from before the split, where the spill sat inside
+Flooding Loss.
+
+The key changes the report only. The spill is an outflow of the 1D
+system under either grouping, so the routing continuity error is
+identical; every routed volume is identical; and the per-step flooding
+rate that drives the flood reporting and the node flooding statistics
+keeps the spill in both cases, since those statistics are about water
+leaving the node upward, which a spill is whatever row the continuity
+table puts it in. The 2D → 1D drain is external inflow under either
+setting.
+
+
+![Figure 9-6](figures/png/hydraulics_ch9_coupling_modes.png)
+
+*Figure 9-6 Where a node spill is booked under COUPLING_IN_FLOODING: the same totals and the same continuity error, in two different rows*
+
+
+
 ## 9.8 Rainfall and evaporation on the mesh
 
 Rainfall reaches the mesh from the project's rain gages, mapped by
-`RAINFALL_MODE`:
-
-- **`NATURAL_NEIGHBOUR`** (default) interpolates the located gages onto
-  every cell centroid — natural-neighbour (Laplace) weights inside the
-  convex hull of the gages, inverse-distance weighting with power 2
-  outside it. Laplace weights reproduce a linear rainfall field exactly
-  within the hull and require no polygon-area integration: the weight
-  for gage \f$g\f$ is the length of the shared Voronoi facet divided by the
-  distance to \f$g\f$. The Delaunay triangulation of the gage sites is built
-  by Bowyer–Watson; gage counts are small enough that this needs no
-  external geometry library. The weights are static — gage positions do
-  not change during a run — so they are built once and applied each step
-  as a sparse weighted sum. Degenerate cases fall back cleanly: one
-  gage everywhere, two or collinear gages by inverse distance, no
-  located gage at all to the `SYSTEM` mean.
-- **`SYSTEM`** applies the arithmetic mean of all gages uniformly.
-- **`NONE`** applies no rain to the mesh.
-
+`RAINFALL_MODE`: `NATURAL_NEIGHBOUR` (the default) interpolates the
+located gages onto every cell centroid with natural-neighbour (Laplace)
+weights inside the gages' convex hull and inverse-distance weights
+outside it; `NEAREST_NEIGHBOUR` gives every cell the reading of its
+closest located gage; `SYSTEM` applies the arithmetic mean of all gages uniformly
+and is the automatic fallback when no gage has a map location; `NONE`
+applies no rain to the mesh. The interpolation — its weights, its
+Delaunay construction, its degenerate cases and the way the weights are
+built once and applied each step — is hydrology, and
+@ref hydrology_ref_ch8_mesh_surface "Hydrology Chapter 8" gives it.
 **`NONE` is not an optimization, it is a modelling decision.** If the
 project's subcatchments already convert the storm to runoff and deliver
 it to nodes, rain on the mesh double-counts the same storm. Use `NONE`
 whenever the surface is meant to receive only what the network gives it.
 
-Evaporation applies the project's demand rate as a sink, tapered by a
-smoothstep below `DRY_DEPTH` so a drying cell cannot evaporate more
-water than it has.
-
-There is no infiltration on the mesh (§9.12).
+Evaporation on the mesh is governed by `EVAPORATION`:
+
+- **`YES`** (the default) makes evaporation a forcing-only sink: the
+  demand rate is zero unless the C API prescribes one per cell or
+  uniformly (`swmm_2d_force_evap`, §9.7.5). The project's `[EVAPORATION]`
+  section does not reach the mesh.
+- **`CLIMATE`** takes the project's climate evaporation rate — the
+  same rate the subcatchments see, converted to m/s — as the demand on
+  every cell not carrying a forcing override; an override replaces or
+  adds to it per cell as the forcing API directs.
+- **`NO`** holds the sink at zero and ignores forcing.
+
+Whatever supplies the demand, the sink actually applied is the demand
+tapered by the cubic Hermite ramp (9-26) below `DRY_DEPTH`, with
+\f$e_{eff} = 0\f$ for a dry cell or a negative demand: a drying cell cannot
+evaporate more water than it holds, and negative demand is not a
+condensation source. The taper is applied in the same form at every
+point the sink enters — the lazy pass over inactive cells and the cell
+firing of §9.5.8 — and evaporation is taken first, with infiltration
+applied against what is left, so a surface-only project is bitwise
+unchanged by the infiltration machinery; both sinks feed a volume update
+floored at zero, so the pair cannot leave a cell with negative water.
+
+Infiltration on the mesh — the per-cell methods, the destination of the
+infiltrated water (lost, the subcatchment aquifer, or the mesh aquifer)
+and its own step — is hydrology and is documented in
+@ref hydrology_ref_ch8_mesh_surface "Hydrology Chapter 8"; the mesh
+aquifer it can feed is @ref hydrology_ref_ch9_mesh_groundwater
+"Hydrology Chapter 9". With `INFILTRATION NO`, or no infiltration rows,
+water on the surface leaves only by flowing away, evaporating, or
+entering the network.
+
+
 
 ## 9.9 Reporting
 
@@ -1238,7 +2064,12 @@ routing balance:
 
 Volumes are SI. Every term is booked from the volume actually applied —
 after every cap, clamp and rescale — so the balance reflects the
-volumes the solver actually applied.
+volumes the solver actually applied. A mesh that infiltrates, or that
+carries an aquifer, gains the rows those processes book; they are
+described with the processes in @ref hydrology_ref_ch8_mesh_surface
+"Hydrology Chapter 8" and @ref hydrology_ref_ch9_mesh_groundwater
+"Hydrology Chapter 9". Where the spill appears in the *1D* table is the
+subject of §9.7.6.
 
 A **2D Solver Statistics** block reports cumulative substeps,
 face-kernel evaluations, mean and last internal step, the minimum, mean
@@ -1256,6 +2087,11 @@ rather than every routing step, because the six full-mesh passes cost
 several times the solver's own advance on a large mesh, and nothing
 consumes them faster than the reporting interval. Coupling and outfall
 heads read the solver's live state directly, never these derived fields.
+`REPORT_2D NO` skips the derived-gradient refresh; it does not suppress
+the results file. The reported gradients are Green–Gauss gradients of
+the free surface limited by the Jawahar–Kamath (2000) limiter, whose
+regularization is `LIMITER_EPSILON`; the limiter affects the output
+fields only and enters no solver update.
 
 Two distinct vertex reconstructions exist and must not be confused. The
 **solver** field is the pseudo-Laplacian stencil of Kumar et al. (2009),
@@ -1268,12 +2104,63 @@ reaches it. Interpolating the solver field for display would drag water
 surfaces up dry banks and down into thin films; interpolating the
 rendering field in the solver would break the active-set logic.
 
-With `OUTPUT_FILE` set in `[2D_OPTIONS]`, results are written to an
-HDF5 file following the CF-1.11 and UGRID-1.0 conventions for
-unstructured meshes — mesh topology, node and face coordinates, bed
-elevations and roughness written once, then time-varying depth, head,
-velocity and gradient fields appended. The file opens directly in
-ParaView, QGIS, or any CF/UGRID-aware reader.
+**The results file.** With `OUTPUT_FILE` set in `[2D_OPTIONS]`, results
+are written to an HDF5 file following the CF-1.11 and UGRID-1.0
+conventions for unstructured meshes — mesh topology (mixed topology for
+a mesh with quads, §9.3.1), node and face coordinates, bed elevations
+and roughness written once, then the selected time-varying fields
+appended. The file opens directly in ParaView, QGIS, or any
+CF/UGRID-aware reader. Four keys shape it:
+
+- **`OUTPUT_PRECISION`** — `FLOAT32` (the default, halving the file at
+  about seven significant digits) or `FLOAT64` for bit-for-bit parity
+  tooling. Mesh geometry always stays float64: projected coordinates are
+  of order \f$10^{6}\f$ m and single precision would lose centimetres
+  there, whereas depth and velocity fields carry no such offset.
+- **`OUTPUT_COMPRESSION`** — a deflate level 0–9 applied, with the
+  byte-shuffle filter, to the chunked time-varying datasets; 0 writes
+  them uncompressed.
+- **`REPORT_2D_STEP`** — the cadence of the time-varying datasets, in
+  the `HH:MM:SS` spelling of `REPORT_STEP`. It must be a positive
+  multiple of `REPORT_STEP`; unset, the 2D file follows the report
+  step.
+- **`REPORT_2D_VARIABLES`** — which dataset groups are written. The
+  value is a preset or a list of the tokens of Table 9-4; `DEPTH` is
+  always included, since every reader keys the time axis on it, and a
+  group not selected is not created in the file, so readers treat every
+  time-varying dataset as optional. `DEFAULT` is everything a user
+  renders or plots with the solver diagnostics off; `MINIMAL` is the
+  depth map, the render reconstruction and the envelopes; `ALL` is every
+  group; `NONE` is `DEPTH` alone.
+
+| Token | Datasets | In `DEFAULT` |
+|---|---|---|
+| `DEPTH` | `Mesh2_face_depth`, `Mesh2_face_head` | always |
+| `VELOCITY` | `Mesh2_face_vx`, `Mesh2_face_vy` | yes |
+| `EDGE_FLUX` | `Mesh2_edge_flux` (GUI velocity reconstruction, profile flux) | yes |
+| `NODE_HEAD` | `Mesh2_node_head`, `Mesh2_node_depth` (the rendering reconstruction) | yes |
+| `SPECIES` | `Mesh2_face_species_conc`, when transport rows exist | yes |
+| `RAINFALL` | `Mesh2_face_rainfall`, `Mesh2_face_rain_cum` | yes |
+| `INFILTRATION` | `Mesh2_face_infil_rate`, `Mesh2_face_infil_cum` | yes |
+| `COUPLING` | `Mesh2_face_coupling_flux`, `Mesh2_face_net_source` | no |
+| `GRADIENTS` | `Mesh2_face_grad_hx`, `Mesh2_face_grad_hy` and their limited pair (solver diagnostics) | no |
+| `CONTINUITY` | `Mesh2_face_continuity_err` (solver diagnostic) | no |
+| `ENVELOPES` | `Mesh2_face_max_depth`, `Mesh2_face_max_velocity`, `Mesh2_face_max_continuity_err` | yes |
+| `BUILDUP` | `Mesh2_face_buildup`, when `[2D_COVERAGES]` rows resolved | yes |
+| `GROUNDWATER` | the per-cell `Mesh2_face_gw_*` fields, the groundwater ledger and the node-exchange cumulative, when a mesh aquifer resolved | yes |
+| `GW_DETAILED` | `Mesh2_face_gw_theta_sigma` per layer and face — \f$m\f$ layers × nFace per step | no |
+
+*Table 9-4 The fourteen `REPORT_2D_VARIABLES` tokens*
+
+**`REPORT_2D_SPECIES`** narrows the `SPECIES` group to a list of species
+names (`ALL`, the default, writes every transported species). The
+species themselves — pollutants, MSX species, water age and temperature
+on the mesh — are the subject of @ref quality_ref_ch10_mesh_quality
+"Quality Chapter 10"; the groundwater datasets and the aquifer block of
+the status report are described in @ref hydrology_ref_ch9_mesh_groundwater
+"Hydrology Chapter 9".
+
+
 
 ## 9.10 Verification against analytic solutions
 
@@ -1331,52 +2218,137 @@ solver for it.
 
 ## 9.11 Options
 
-All keys live in `[2D_OPTIONS]`. Keys retired with the earlier implicit
-integrator are accepted with a warning and ignored on file load, so
-legacy models still open.
-
-| Key | Default | Meaning |
-|---|---|---|
-| `INTEGRATOR` | `EXPLICIT` | The explicit local-inertial marcher is the only integrator. |
-| `CFL_NUMBER` | 0.7 | \f$\alpha\f$ in (9-17). A true Courant fraction: 1.0 is the linear stability limit on any mesh. |
-| `MAX_TIMESTEP` | 10 s | Cap on the marcher step; also caps the tier spread and the co-advance batch span. |
-| `THETA` | 0.8 | Lateral blend (9-9). 1.0 is pure Bates et al. (2010); below 1 damps thin-film checkerboarding. |
-| `FROUDE_MAX` | 1.5 | Face velocity clamp (9-10). |
-| `LTS_TIERS` | 4 | Local-time-stepping tiers, 1–8. 1 forces a single global step. |
-| `H_MOVE` | 0.003 m | Flux-activation depth (§9.5.7). Cells below it are source-only. |
-| `DRY_DEPTH` | 0.001 m | Dry-cell threshold for face walls, evaporation taper and coupling ramps. |
-| `CELL_CLOSURE` | `FLAT` | `FLAT` or `VFR` (§9.4). |
-| `FACE_RECONSTRUCTION` | `MEAN` | `MEAN` or `VFR_FACE` (§9.5.2). |
-| `VFR_MIN_WET_FRAC` | 0.01 | Wetted-fraction floor \f$\varepsilon\f$ of the regularized VFR closure, in \f$(0, 0.5]\f$. |
-| `RAINFALL_MODE` | `NATURAL_NEIGHBOUR` | `NATURAL_NEIGHBOUR`, `SYSTEM` or `NONE` (§9.8). |
-| `COUPLING_CD` | 0.65 | Default exchange discharge coefficient. |
-| `COUPLING_AREA` | `DEFAULT` | `AUTO` derives an unauthored exchange area as clamp(1.25 × largest connected conduit full-flow area, 0.05, 2.0) m² (§9.7.5). |
-| `COUPLING_SYNC` | 0 s | 0 co-advances every routing step; > 0 batches the 2D advance (§9.7.3). |
-| `FLUX_DH_EPS` | 0.004 m | Head-gradient floor of the diffusive boundary flux. 0 restores the bare \f$\sqrt{\ }\f$. |
-| `LIMITER_EPSILON` | \f$10^{-6}\f$ | Regularization of the output gradient limiter. |
-| `REPORT_2D` | `YES` | Write 2D results. |
-| `OUTPUT_FILE` | — | HDF5 results path, resolved relative to the `.inp` directory. |
-
-The computational backend is selected at runtime rather than from the
-input file. The built-in marcher is OpenMP-threaded on the host and uses
-the project's `THREADS` setting; a Kokkos plugin (`omp`, `cuda`, `hip`
-or `sycl`) is preferred when one is installed and the mesh is large
-enough to amortize per-substep kernel launches. `OPENSWMM_2D_BACKEND`
-overrides the choice. The gate is deliberately high — on a 25 000-cell
-coupled model the OpenMP plugin measured an order of magnitude *slower*
-than the built-in marcher, because the plugin pays a launch cost on
-every substep while the built-in path is already threaded.
+All keys live in `[2D_OPTIONS]`. This section is an index, not a
+reference: the theory each key selects or tunes is in the section named
+beside it, and the accepted values and defaults are documented once, in
+the engine manual (@ref engine_manual_sect_2D_OPTIONS), so that a
+default changed there is not contradicted here. The 2D grammar as a
+whole is @ref engine_manual_ch2_input_file, with the boundary and mesh
+sections at @ref engine_manual_sect_2D_BOUNDARY_CONDITIONS,
+@ref engine_manual_sect_2D_QUADS and @ref engine_manual_sect_2D_MESH_FILE.
+
+| Key | Theory section |
+|---|---|
+| `MAX_TIMESTEP` | §9.5.5; also caps the co-advance span of §9.7.3 |
+| `DRY_DEPTH` | §9.5.9, Table 9-1 |
+| `COUPLING_CD` | §9.7.1, §9.7.5 |
+| `COUPLING_SYNC` | §9.7.3 |
+| `LIMITER_EPSILON` | §9.9 |
+| `FLUX_DH_EPS` | §9.5.11, §9.6 |
+| `RAINFALL_MODE` | §9.8; @ref hydrology_ref_ch8_mesh_surface |
+| `REPORT_2D` | §9.9 |
+| `CELL_CLOSURE` | §9.4, §9.4.2 |
+| `FACE_RECONSTRUCTION` | §9.5.2 |
+| `VFR_MIN_WET_FRAC` | §9.4.1 |
+| `OUTPUT_FILE` | §9.9 |
+| `INTEGRATOR` | §9.5; `EXPLICIT` is the only value, the others are retired (below) |
+| `MOMENTUM_EQUATION` | §9.2, Table 9-2 |
+| `RECONSTRUCTION_ORDER` | §9.5.10, §9.5.6 |
+| `FRONT_REBUILD` | §9.5.7 |
+| `THETA` | §9.5.1 |
+| `CFL_NUMBER` | §9.5.5; clamped to ½ under `FULL_SWE`, §9.5.10; the diffusion safety fraction of §9.5.11 |
+| `H_MOVE` | §9.5.7 |
+| `LTS_TIERS` | §9.5.6 |
+| `FROUDE_MAX` | §9.5.1 |
+| `ADVECTION` | deprecated spelling of the convective term — §9.2.3, Table 9-2, and the retired keys below |
+| `COUPLING_AREA` | §9.7.5 |
+| `COUPLING_IN_FLOODING` | §9.7.6 |
+| `BACKEND` | §9.11.1 |
+| `OUTPUT_PRECISION` | §9.9 |
+| `OUTPUT_COMPRESSION` | §9.9 |
+| `REPORT_2D_VARIABLES` | §9.9, Table 9-4 |
+| `REPORT_2D_SPECIES` | §9.9; @ref quality_ref_ch10_mesh_quality |
+| `REPORT_2D_STEP` | §9.9 |
+| `INFILTRATION` | @ref hydrology_ref_ch8_mesh_surface |
+| `INFIL_STEP` | @ref hydrology_ref_ch8_mesh_surface |
+| `INFIL_DEFAULT_METHOD` | @ref hydrology_ref_ch8_mesh_surface |
+| `INFIL_DESTINATION` | @ref hydrology_ref_ch8_mesh_surface; the `AQUIFER_2D` destination is @ref hydrology_ref_ch9_mesh_groundwater |
+| `EVAPORATION` | §9.8 |
+| `TRANSPORT_POLLUTANTS` | @ref quality_ref_ch10_mesh_quality |
+| `TRANSPORT_MSX` | @ref quality_ref_ch10_mesh_quality |
+| `TRANSPORT_AGE` | @ref quality_ref_ch10_mesh_quality |
+| `TRANSPORT_TEMPERATURE` | @ref quality_ref_ch10_mesh_quality |
+| `GROUNDWATER` | @ref hydrology_ref_ch9_mesh_groundwater |
+| `GW_ET` | @ref hydrology_ref_ch9_mesh_groundwater |
+| `DISPERSION` | @ref quality_ref_ch10_mesh_quality |
+
+*Table 9-5 The forty-two live `[2D_OPTIONS]` keys and the theory each
+selects*
+
+### 9.11.1 The computational backend
+
+The computational backend is chosen by `BACKEND`. The built-in `CPU`
+marcher is OpenMP-threaded on the host and uses the project's `THREADS`
+setting; `OMP`, `CUDA`, `HIP` and `SYCL` name a Kokkos plugin and load it
+outright (a plugin that is not installed, or reports no usable device,
+falls back to `CPU` with a notice — never a hard failure). `AUTO`, the
+default, prefers a device plugin when one is installed and the mesh is
+above the device floor (`OPENSWMM_2D_MIN_PARALLEL_CELLS_DEVICE`, default
+10 000 cells), then the OpenMP plugin above its own, much higher floor
+(`OPENSWMM_2D_MIN_PARALLEL_CELLS`, default 50 000), else `CPU`. The
+`OPENSWMM_2D_BACKEND` environment variable overrides the option when set
+(the same precedence `OPENSWMM_FV_BACKEND` has over `FV_BACKEND`). The
+OpenMP floor is deliberately high — on a 25 000-cell coupled model the
+OpenMP plugin measured an order of magnitude *slower* than the built-in
+marcher, because the plugin pays a launch cost on every substep while the
+built-in path is already threaded. Whether a discrete GPU pays off is
+likewise problem-dependent (§9.7.3: every routing step is a host↔device
+round trip, and the junction-exchange and boundary passes run serially),
+so a model that measures slower on `AUTO` should pin `BACKEND CPU`.
+
+The plugins implement the all-triangle local-inertial scheme without
+transport. A model that mixes in quads (§9.3.1), selects `FULL_SWE` or
+`DIFFUSIVE_WAVE` (§9.2), or carries species, age or temperature rows is
+refused by the plugin loudly — under `AUTO` as well, since a model that
+silently lost its plugin would look like a performance regression — and
+served by the CPU marcher. There is no silent physics substitution.
+
+### 9.11.2 Retired keys
+
+Keys retired with the earlier implicit integrator are accepted with a
+warning and ignored on file load, so legacy models still open; on the
+programmatic option-set path they are errors. Each row names where the
+behaviour it once configured is now described.
+
+| Key | Theory section |
+|---|---|
+| `MIN_TIMESTEP` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9; the marcher's step is §9.5.5 |
+| `REL_TOLERANCE` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `ABS_TOLERANCE` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `MAX_CVODE_STEPS` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `MAX_KRYLOV_DIM` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `LINEAR_SOLVER` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `PRECONDITIONER` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `JACOBIAN` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `ATOL_AREA_REF` | retired with the CVODE/ARKODE integrators — @ref hydraulics_ref_ch10_planned §10.9 |
+| `COUPLING_INTERVAL` | superseded by the per-routing-step co-advance and `COUPLING_SYNC` — §9.7.3 |
+| `COUPLING_WINDOW` | superseded by the per-routing-step co-advance and `COUPLING_SYNC` — §9.7.3 |
+| `ACTIVE_SET` | the flux-active set is always on — §9.5.7 |
+| `ACTIVE_SET_HALO` | the halo is the one-ring (five rings under `FRONT_REBUILD`) — §9.5.7 |
+| `MOMENTUM` | superseded by `MOMENTUM_EQUATION` — §9.2; the IMEX blend it selected is @ref hydraulics_ref_ch10_planned §10.9 |
+| `INTEGRATOR` other than `EXPLICIT` | the CVODE/ARKODE selections — @ref hydraulics_ref_ch10_planned §10.9 |
+| `ADVECTION` | deprecated 2026-09-06 in favour of `MOMENTUM_EQUATION FULL_SWE` — §9.2.2, Table 9-2; still honoured with a warning so an old deck keeps its physics |
+
+*Table 9-6 The sixteen retired `[2D_OPTIONS]` keys and values*
+
+
 
 ## 9.12 Limitations
 
-- **No convective acceleration.** (9-2) omits it. Persistently
-  supercritical flow, drawdown over a crest, and momentum-dominated
-  contractions fall outside the model's validity rather than merely
-  being under-resolved in it. §9.10 quantifies this.
-- **No infiltration on the mesh.** Water on the surface leaves by
-  flowing away, evaporating, or entering the network. Losses to the
-  ground must be represented through the subcatchments.
-- **The Froude clamp is a numerical device.** It
+- **No convective acceleration under the default closure.** (9-2) omits
+  it. Persistently supercritical flow, drawdown over a crest, and
+  momentum-dominated contractions fall outside the local-inertial
+  model's validity rather than merely being under-resolved in it. §9.10
+  quantifies this; `MOMENTUM_EQUATION FULL_SWE` (§9.2.2) restores the
+  term, at the cost of a half-Courant step and CPU-only execution.
+- **Infiltration on the mesh is a hydrology process, not a hydraulic
+  one.** The face laws of this chapter know nothing of the soil; what
+  leaves the surface downward, and where it goes, is set by the
+  infiltration options of @ref hydrology_ref_ch8_mesh_surface
+  "Hydrology Chapter 8". With infiltration off, water on the surface
+  leaves by flowing away, evaporating, or entering the network, and
+  losses to the ground must be represented through the subcatchments.
+- **The Froude clamp is a numerical device** (local-inertial only). It
   bounds a velocity the momentum equation would otherwise leave
   unbounded. Results that sit on the clamp should not be regarded as
   physically meaningful.
@@ -1390,14 +2362,32 @@ every substep while the built-in path is already threaded.
   in time (§9.5.6), never in space. Mesh quality is the modeller's
   responsibility, and it is not a cosmetic one: cell size enters the
   stable step through (9-4), so a handful of tiny cells at a coupling
-  point can set the substep for the entire mesh.
+  point can set the substep for the entire mesh — and under
+  `DIFFUSIVE_WAVE` the penalty is quadratic in the cell size (9-43).
+- **Second order excludes transport, and tiers.** `RECONSTRUCTION_ORDER 2`
+  runs in global-step mode and falls back to first order when overland
+  transport is active (§9.5.10).
+- **The Kokkos backends serve one configuration.** All-triangle meshes
+  under the local-inertial closure without transport; everything else
+  runs on the CPU marcher (§9.11.1).
 - **Frozen 1D heads within a batch.** With `COUPLING_SYNC` > 0 the 1D
   heads a 2D advance sees are held for the batch. The error grows with
   the span.
 - **Hot start files do not carry 2D state.**
 
+
+
 ## 9.13 References for this chapter
 
+Audusse, E., Bouchut, F., Bristeau, M.-O., Klein, R., and Perthame, B.
+(2004). "A fast and stable well-balanced scheme with hydrostatic
+reconstruction for shallow water flows." *SIAM Journal on Scientific
+Computing*, 25(6), 2050–2065.
+
+Barth, T. J., and Jespersen, D. C. (1989). "The design and application
+of upwind schemes on unstructured meshes." *AIAA Paper* 89-0366, 27th
+Aerospace Sciences Meeting, Reno.
+
 Bates, P. D., Horritt, M. S., and Fewtrell, T. J. (2010). "A simple
 inertial formulation of the shallow water equations for efficient
 two-dimensional flood inundation modelling." *Journal of Hydrology*,
@@ -1441,6 +2431,15 @@ shallow water analytic solutions for hydraulic and environmental
 studies." *International Journal for Numerical Methods in Fluids*,
 72(3), 269–300.
 
+Gottlieb, S., Shu, C.-W., and Tadmor, E. (2001). "Strong
+stability-preserving high-order time discretization methods." *SIAM
+Review*, 43(1), 89–112.
+
+Hunter, N. M., Horritt, M. S., Bates, P. D., Wilson, M. D., and Werner,
+M. G. F. (2005). "An adaptive time step solution for raster-based
+storage cell modelling of floodplain inundation." *Advances in Water
+Resources*, 28(9), 975–991.
+
 Jawahar, P., and Kamath, H. (2000). "A high-resolution procedure for
 Euler and Navier–Stokes computations on unstructured grids." *Journal of
 Computational Physics*, 164(1), 165–203.
@@ -1450,6 +2449,10 @@ accurate, finite volume-based, integrated hydrologic modeling (FIHM)
 framework for simulation of surface and subsurface flow." *Vadose Zone
 Journal*, 8(4), 873–890.
 
+Liang, Q., and Marche, F. (2009). "Numerical resolution of
+well-balanced shallow water equations with complex source terms."
+*Advances in Water Resources*, 32(6), 873–884.
+
 Perot, B. (2000). "Conservation properties of unstructured staggered
 mesh schemes." *Journal of Computational Physics*, 159(1), 58–89.
 
@@ -1457,12 +2460,20 @@ Sanders, B. F., Schubert, J. E., and Gallegos, H. A. (2008). "Integral
 formulation of shallow-water equations with anisotropic porosity for
 urban flood modeling." *Journal of Hydrology*, 362(1–2), 19–38.
 
+Stelling, G. S., and Duinmeijer, S. P. A. (2003). "A staggered
+conservative scheme for every Froude number in rapidly varied shallow
+water flows." *International Journal for Numerical Methods in Fluids*,
+43(12), 1329–1354.
+
 Thacker, W. C. (1981). "Some exact solutions to the nonlinear
 shallow-water wave equations." *Journal of Fluid Mechanics*, 107,
 499–508.
 
+Toro, E. F. (2001). *Shock-Capturing Methods for Free-Surface Shallow
+Flows*. Wiley, Chichester.
+
 Watson, D. F. (1981). "Computing the n-dimensional Delaunay tessellation
 with application to Voronoi polytopes." *The Computer Journal*, 24(2),
 167–172.
 
-
+
diff --git a/docs/manuals/reference/hydrology.md b/docs/manuals/reference/hydrology.md
index cecfd76c0..576011191 100644
--- a/docs/manuals/reference/hydrology.md
+++ b/docs/manuals/reference/hydrology.md
@@ -150,12 +150,15 @@ WE water equivalent
 
 ## List of Figures
 
-- **Figure 1-1** Elements of a typical urban drainage system.
-- **Figure 1-2** SWMM's conceptual model of a stormwater drainage system.
-- **Figure 1-3** Processes modeled by SWMM.
-- **Figure 1-4** Block diagram of SWMM's state transition process.
-- **Figure 1-5** Flow chart of SWMM's simulation procedure.
-- **Figure 1-6** Interpolation of reported values from computed values.
+
+
+- **Figure 1-1** Elements of a typical urban drainage system
+- **Figure 1-2** Objects of an OpenSWMM model
+- **Figure 1-3** Processes modelled by OpenSWMM
+- **Figure 1-4** Block diagram of SWMM's state transition process
+- **Figure 1-5** Flow chart of SWMM's simulation procedure
+- **Figure 1-6** Interpolation of reported values from computed values
+- **Figure 1-7** The hydrology of this manual: atmosphere, land surface and subsurface representations
 
 - **Figure 2-1** Sinusoidal interpolation of hourly temperatures.
 
@@ -163,39 +166,39 @@ WE water equivalent
 - **Figure 3-2** Nonlinear reservoir model of a subcatchment.
 - **Figure 3-3** Types of subareas within a subcatchment.
 - **Figure 3-4** Idealized subcatchment partitioning for overland flow.
-- **Figure 3-5** Re-routing of overland flow.
-- **Figure 3-6** Fisk B catchment, Portland, Oregon.
-- **Figure 3-7** Detailed view of two Fisk B subcatchments.
+- **Figure 3-5** Re-routing of overland flow (Huber, 2001).
+- **Figure 3-6** Fisk B catchment, Portland, Oregon (Portland BES, 1996).
+- **Figure 3-7** Detailed view of two Fisk B subcatchments (Portland BES, 1996).
 - **Figure 3-8** Idealized representation of a subcatchment.
 - **Figure 3-9** Rectangular subcatchments for illustration of shape and width effects.
 - **Figure 3-10** Subcatchment hydrographs for different shapes of Figure 3-9.
-- **Figure 3-11** Irregular subcatchment shape for width calculations.
+- **Figure 3-11** Irregular subcatchment shape for width calculations (DiGiano et al., 1977, p. 165).
 - **Figure 3-12** Runoff results for illustrative example.
-- **Figure 3-13** SCS (NRCS) triangular unit hydrograph.
+- **Figure 3-13** SCS (NRCS) triangular unit hydrograph (NRCS, 2007).
 
 - **Figure 4-1** Physical properties for Woodburn silt loam, Benton County, Oregon.
-- **Figure 4-2** The Horton infiltration curve.
-- **Figure 4-3** Cumulative infiltration F as the area under the Horton curve.
-- **Figure 4-4** Regeneration (recovery) of infiltration capacity during dry time steps.
-- **Figure 4-5** Two-zone representation of the Green-Ampt infiltration model.
-- **Figure 4-6** Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method.
-- **Figure 4-7** Green-Ampt recovery parameters as functions of hydraulic conductivity.
+- **Figure 4-2** The Horton infiltration curve
+- **Figure 4-3** Cumulative infiltration F as the area under the Horton curve
+- **Figure 4-4** Regeneration (recovery) of infiltration capacity during dry time steps
+- **Figure 4-5** Two-zone representation of the Green-Ampt infiltration model (after Nicklow et al., 2006)
+- **Figure 4-6** Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method
+- **Figure 4-7** Green-Ampt recovery parameters as functions of hydraulic conductivity
 - **Figure 4-8** Infiltration rates produced by different methods for a 2-inch rainfall event.
 
 - **Figure 5-1** Definitional sketch of the two-zone groundwater model.
 - **Figure 5-2** Heights used to compute lateral groundwater flow rate.
-- **Figure 5-3** Relation between soil moisture limits and soil texture class.
-- **Figure 5-4** SPAW's soil water characteristics calculator.
+- **Figure 5-3** Relation between soil moisture limits and soil texture class (Schroeder et al., 1994).
+- **Figure 5-4** SPAW\'s soil water characteristics calculator.
 - **Figure 5-5** Measured hydraulic conductivity for three soils.
 - **Figure 5-6** Fitting SWMM's hydraulic conductivity equation to a power law equation.
 - **Figure 5-7** Definition sketch for Dupuit-Forcheimer seepage to an adjacent channel.
 - **Figure 5-8** Definition sketch for Hooghoudt's method for flow to circular drains.
 - **Figure 5-9** Surface runoff and groundwater flow for the illustrative groundwater example.
 
-- **Figure 6-1** Typical gage catch deficiency correction.
+- **Figure 6-1** Typical gage catch deficiency correction (Anderson, 2006, p. 8).
 - **Figure 6-2** Subcatchment partitionings used for snowmelt and runoff.
 - **Figure 6-3** Seasonal variation of melt coefficients.
-- **Figure 6-4** Typical areal depletion curve for natural area and temporary curve for new snow.
+- **Figure 6-4** Typical areal depletion curve for natural area (Anderson, 1973, p. 3-15) and temporary curve for new snow.
 - **Figure 6-5** Effect of snow cover on areal depletion curves.
 - **Figure 6-6** Schematic of liquid water routing through snow pack.
 - **Figure 6-7** Continuous air temperature for illustrative snowmelt example.
@@ -206,17 +209,29 @@ WE water equivalent
 - **Figure 7-1** Components of wet-weather wastewater flow.
 - **Figure 7-2** Example of an RDII triangular unit hydrograph.
 - **Figure 7-3** Application of a unit hydrograph to a storm event.
-- **Figure 7-4** Use of three unit hydrographs to represent RDII.
-- **Figure 7-5** Sewershed delineation.
-- **Figure 7-6** Extracting RDII flow from a continuous flow monitor.
-- **Figure 7-7** Fitting unit hydrographs to an RDII flow record.
+- **Figure 7-4** Use of three unit hydrographs to represent RDII (Vallabhaneni et al., 2007).
+- **Figure 7-5** Sewershed delineation (Vallabhaneni et al., 2007).
+- **Figure 7-6** Extracting RDII flow from a continuous flow monitor (Vallabhaneni et al., 2007).
+- **Figure 7-7** Fitting unit hydrographs to an RDII flow record (Vallabhaneni et al., 2007).
 - **Figure 7-8** Unit hydrographs used for the illustrative RDII example.
 - **Figure 7-9** Time series of RDII flows for the illustrative RDII example.
 - **Figure 7-10** Excerpt from the RDII interface file for the illustrative RDII example.
-- **Figure 7-11** Emergent seasonal behavior of the exponential-decay initial abstraction model.
+- **Figure 7-11** Emergent seasonal behavior of the exponential-decay initial abstraction model (schematic, synthetic forcing): available initial abstraction depletes during storms, recovery is suspended on frozen ground and accelerates in warm months, and a single R-T-K set produces a seasonally varying RDII response.
+
+- **Figure 8-1** The water balance of one mesh cell: rainfall, evaporation, infiltration, network exchange and the lateral face fluxes
+- **Figure 8-2** Natural-neighbour rainfall weights inside the gage hull, and inverse-distance weighting outside it
+- **Figure 8-3** Per-cell infiltration: how a cell resolves its method and parameters, and the rate held across an infiltration step
+
+- **Figure 9-1** One aquifer column and its fluxes, with the unsaturated zone held as a bulk store (closure A) and as sigma layers (closure B)
+- **Figure 9-2** Retention and relative conductivity of the four soil-characteristic laws at their default parameters
+- **Figure 9-3** Node-aquifer exchange through a semi-confining bed, in both directions, with the caps that bound it
+
+
 
 ## List of Tables
 
+
+
 - **Table 1-1** Development history of SWMM
 - **Table 1-2** SWMM's modeling objects
 - **Table 1-3** State variables used by SWMM
@@ -247,30 +262,30 @@ WE water equivalent
 - **Table 3-7** Parameters used for illustrative runoff example
 - **Table 3-8** Contents of a typical Routing Interface file
 
-- **Table 4-1** Hydrologic soil group meanings
-- **Table 4-2** Horton parameters for selected Georgia soils
-- **Table 4-3** Horton parameters provided by Horton
-- **Table 4-4** Values of f~∞~ for Hydrologic Soil Groups
-- **Table 4-5** Rate of decay of infiltration capacity for different values of k~d~
-- **Table 4-6** Representative values for f~0~
-- **Table 4-7** Green-Ampt parameters for different soil classes
-- **Table 4-8** Typical values of *θ*~dmax~ for various soil types.
-- **Table 4-9** Runoff curve numbers for selected land uses
+- **Table 4-1** Hydrologic soil group meanings (NRCS, 2009, @ref hydrology_ref_ch7_rdii "Chapter 7")
+- **Table 4-2** Horton parameters for selected Georgia soils (Rawls et al., 1976)
+- **Table 4-3** Horton parameters provided by Horton (1940)
+- **Table 4-4** Values of f∞ for Hydrologic Soil Groups (Musgrave, 1955)
+- **Table 4-5** Rate of decay of infiltration capacity for different values of kd
+- **Table 4-6** Representative values for f₀
+- **Table 4-7** Green-Ampt parameters for different soil classes (Rawls et al., 1983)
+- **Table 4-8** Typical values of θdmax for various soil types.
+- **Table 4-9** Runoff curve numbers for selected land uses (NRCS, 2004a)
 - **Table 4-10** Parameters used in example comparison of infiltration methods
 
-- **Table 5-1** Volumetric moisture content at field capacity and wilting point
-- **Table 5-2** Volumetric moisture content at field capacity and wilting point
-- **Table 5-3** Average moisture limits and saturated hydraulic conductivity for different soil types
-- **Table 5-4** Default properties of low-density soils used in the EPA HELP model
-- **Table 5-5** Default properties of moderate-density soils used in the EPA HELP model
+- **Table 5-1** Volumetric moisture content at field capacity and wilting point (derived from Linsley et al., 1982)
+- **Table 5-2** Volumetric moisture content at field capacity and wilting point (U.S. Army Corps of Engineers, 1956)
+- **Table 5-3** Average moisture limits and saturated hydraulic conductivity for different soil types (Rawls et al., 1983)
+- **Table 5-4** Default properties of low-density soils used in the EPA HELP model (from Rawls et al. (1982) as reported in Schroeder et al. (1994))
+- **Table 5-5** Default properties of moderate-density soils used in the EPA HELP model (Schroeder et al. (1994))
 - **Table 5-6** Soil texture abbreviations
-- **Table 5-7** Regression equations for soil moisture limits
-- **Table 5-8** Regression estimates of soil moisture limits from the SPAW calculator*
+- **Table 5-7** Regression equations for soil moisture limits (Saxton and Rawls, 2006)
+- **Table 5-8** Regression estimates of soil moisture limits from the SPAW calculator
 - **Table 5-9** Estimated HCO for different soil types
-- **Table 5-10** DET (in feet) for different soil types and land cover
+- **Table 5-10** DET (in feet) for different soil types and land cover (Shah et al., 2007)
 - **Table 5-11** Parameters used in groundwater example
 
-- **Table 6-1** Guidelines for level of service in snow and ice control
+- **Table 6-1** Guidelines for level of service in snow and ice control (Richardson et al., 1974)
 - **Table 6-2** Summary of snowmelt parameters (in US customary units)
 - **Table 6-3** Typical areal depletion curve for natural areas
 - **Table 6-4** Subcatchment and snow pack parameters for illustrative snowmelt example
@@ -281,6 +296,10 @@ WE water equivalent
 - **Table 7-2** Parameters of the `[RDII_DECAY]` section
 - **Table 7-3** Typical parameter ranges for the exponential-decay model
 
+- **Table 10-1** Formulations recorded in this chapter
+
+
+
 ## Manual Contents
 
 - @subpage hydrology_ref_ch1_overview — Chapter 1: Overview
@@ -290,5 +309,8 @@ WE water equivalent
 - @subpage hydrology_ref_ch5_groundwater — Chapter 5: Groundwater
 - @subpage hydrology_ref_ch6_snowmelt — Chapter 6: Snowmelt
 - @subpage hydrology_ref_ch7_rdii — Chapter 7: Rainfall Dependent Inflow and Infiltration
+- @subpage hydrology_ref_ch8_mesh_surface — Chapter 8: Distributed Surface Processes on the 2D Mesh
+- @subpage hydrology_ref_ch9_mesh_groundwater — Chapter 9: Spatially Explicit Groundwater on the 2D Mesh
+- @subpage hydrology_ref_ch10_planned — Chapter 10: Planned Formulations
 - @subpage hydrology_ref_glossary — Glossary
 - @subpage hydrology_ref_references — References
diff --git a/docs/manuals/reference/hydrology/SWMM 5 Reference Manual I (20150917).md b/docs/manuals/reference/hydrology/SWMM 5 Reference Manual I (20150917).md
deleted file mode 100644
index d9d36bfcd..000000000
--- a/docs/manuals/reference/hydrology/SWMM 5 Reference Manual I (20150917).md	
+++ /dev/null
@@ -1,9131 +0,0 @@
-United States
-
-EPA/600/R-15/162
-
-July 2015
-
-Storm Water Management Model
-
-Reference Manual
-
-Volume I -- Hydrology
-
-By:
-
-Lewis A. Rossman
-
-National Risk Management Laboratory
-
-Office of Research and Development
-
-U.S. Environmental Protection Agency
-
-Cincinnati, OH 45268
-
-and
-
-Wayne C. Huber
-
-School of Civil and Construction Engineering
-
-Oregon State University
-
-Corvallis, OR 97331
-
-National Risk Management Laboratory
-
-Office of Research and Development
-
-U.S. Environmental Protection Agency
-
-26 Martin Luther King Drive
-
-Cincinnati, OH 45268
-
-July 2015
-
-# Disclaimer
-
-The information in this document has been funded wholly or in part by
-the U.S. Environmental Protection Agency (EPA). It has been subjected to
-the Agency's peer and administrative review, and has been approved for
-publication as an EPA document. Mention of trade names or commercial
-products does not constitute endorsement or recommendation for use.
-
-Although a reasonable effort has been made to assure that the results
-obtained are correct, the computer programs described in this manual are
-experimental. Therefore the author and the U.S. Environmental Protection
-Agency are not responsible and assume no liability whatsoever for any
-results or any use made of the results obtained from these programs, nor
-for any damages or litigation that result from the use of these programs
-for any purpose.
-
-# Abstract
-
-SWMM is a dynamic rainfall-runoff simulation model used for single event
-or long-term (continuous) simulation of runoff quantity and quality from
-primarily urban areas. The runoff component of SWMM operates on a
-collection of subcatchment areas that receive precipitation and generate
-runoff and pollutant loads. The routing portion of SWMM transports this
-runoff through a system of pipes, channels, storage/treatment devices,
-pumps, and regulators. SWMM tracks the quantity and quality of runoff
-generated within each subcatchment, and the flow rate, flow depth, and
-quality of water in each pipe and channel during a simulation period
-comprised of multiple time steps. The reference manual for this edition
-of SWMM is comprised of three volumes. Volume I describes SWMM's
-hydrologic models, Volume II its hydraulic models, and Volume III its
-water quality and low impact development models.
-
-# Acknowledgments
-
-This report was written by Lewis A. Rossman, Environmental Scientist
-Emeritus, U.S. Environmental Protection Agency, Cincinnati, OH and Wayne
-C. Huber, Professor Emeritus, School of Civil and Construction
-Engineering, Oregon State University, Corvallis, OR.
-
-The authors would like to acknowledge the contributions made by the
-following individuals to previous versions of SWMM that we drew heavily
-upon in writing this report: John Aldrich, Douglas Ammon, Carl W. Chen,
-Brett Cunningham, Robert Dickinson, James Heaney, Wayne Huber, Miguel
-Medina, Russell Mein, Charles Moore, Stephan Nix, Alan Peltz, Don
-Polmann, Larry Roesner, Lewis Rossman, Charles Rowney, and Robert
-Shubinsky. Finally, we wish to thank Lewis Rossman, Wayne Huber, Thomas
-Barnwell (US EPA retired), Richard Field (US EPA retired), Harry Torno
-(US EPA retired) and William James (University of Guelph) for their
-continuing efforts to support and maintain the program over the past
-several decades.
-
-Portions of this document were prepared under Purchase Order
-2C-R095-NAEX to Oregon State University.
-
-# 
-
-**Table of Contents**
-
-[Disclaimer [ii](#disclaimer)](#disclaimer)
-
-[Abstract [iii](#abstract)](#abstract)
-
-[Acknowledgments [iv](#acknowledgments)](#acknowledgments)
-
-[List of Figures [vii](#list-of-figures)](#list-of-figures)
-
-[List of Tables [ix](#list-of-tables)](#list-of-tables)
-
-[Acronyms and Abbreviations
-[xi](#acronyms-and-abbreviations)](#acronyms-and-abbreviations)
-
-[Chapter 1 - Overview [13](#section-3)](#section-3)
-
-[1.1 Introduction [13](#introduction)](#introduction)
-
-[1.2 SWMM's Object Model [14](#swmms-object-model)](#swmms-object-model)
-
-[1.3 SWMM's Process Models
-[19](#swmms-process-models)](#swmms-process-models)
-
-[1.4 Simulation Process Overview
-[21](#simulation-process-overview)](#simulation-process-overview)
-
-[1.5 Interpolation and Units
-[25](#interpolation-and-units)](#interpolation-and-units)
-
-[Chapter 2 -- Meteorology [28](#meteorology)](#meteorology)
-
-[2.1 Precipitation [28](#precipitation)](#precipitation)
-
-[2.2 Precipitation Data Sources
-[31](#precipitation-data-sources)](#precipitation-data-sources)
-
-[2.3 Temperature Data [38](#temperature-data)](#temperature-data)
-
-[2.4 Continuous Temperature Records
-[43](#continuous-temperature-records)](#continuous-temperature-records)
-
-[2.5 Evaporation Data [47](#section-4)](#section-4)
-
-[2.6 Wind Speed Data [49](#wind-speed-data)](#wind-speed-data)
-
-[Chapter 3 -- Surface Runoff [50](#surface-runoff)](#surface-runoff)
-
-[3.1 Introduction [50](#introduction-1)](#introduction-1)
-
-[3.2 Governing Equations
-[50](#governing-equations)](#governing-equations)
-
-[3.3 Subcatchment Partitioning
-[53](#subcatchment-partitioning)](#subcatchment-partitioning)
-
-[3.4 Computational Scheme
-[55](#computational-scheme)](#computational-scheme)
-
-[3.5 Time Step Considerations
-[57](#time-step-considerations)](#time-step-considerations)
-
-[3.6 Overland Flow Re-Routing
-[58](#overland-flow-re-routing)](#overland-flow-re-routing)
-
-[3.7 Subcatchment Discretization
-[60](#subcatchment-discretization)](#subcatchment-discretization)
-
-[3.8 Parameter Estimates
-[63](#parameter-estimates)](#parameter-estimates)
-
-[3.9 Numerical Example [78](#numerical-example)](#numerical-example)
-
-[3.10 Approximating Other Runoff Methods
-[79](#approximating-other-runoff-methods)](#approximating-other-runoff-methods)
-
-[Chapter 4 -- Infiltration [85](#infiltration)](#infiltration)
-
-[4.1 Introduction [85](#introduction-2)](#introduction-2)
-
-[4.2 Horton's Method [87](#hortons-method)](#hortons-method)
-
-[4.3 Modified Horton Method
-[99](#modified-horton-method)](#modified-horton-method)
-
-[4.4 Green-Ampt Method [103](#green-ampt-method)](#green-ampt-method)
-
-[4.5 Curve Number Method
-[116](#curve-number-method)](#curve-number-method)
-
-[4.6 Numerical Example
-[124](#numerical-example-1)](#numerical-example-1)
-
-[Chapter 5 -- Groundwater [127](#groundwater)](#groundwater)
-
-[5.1 Introduction [127](#introduction-3)](#introduction-3)
-
-[5.2 Governing Equations
-[128](#governing-equations-5)](#governing-equations-5)
-
-[5.3 Groundwater Flux Terms
-[132](#groundwater-flux-terms)](#groundwater-flux-terms)
-
-[5.4 Computational Scheme
-[139](#computational-scheme-5)](#computational-scheme-5)
-
-[5.5 Parameter Estimates
-[142](#parameter-estimates-5)](#parameter-estimates-5)
-
-[5.6 Numerical Example
-[159](#numerical-example-2)](#numerical-example-2)
-
-[Chapter 6 -- Snowmelt [162](#snowmelt)](#snowmelt)
-
-[6.1 Introduction [162](#introduction-4)](#introduction-4)
-
-[6.2 Preliminaries [163](#preliminaries)](#preliminaries)
-
-[6.3 Governing Equations
-[168](#governing-equations-6)](#governing-equations-6)
-
-[6.4 Areal Depletion [176](#areal-depletion)](#areal-depletion)
-
-[6.5 Net Runoff [181](#net-runoff)](#net-runoff)
-
-[6.6 Computational Scheme
-[182](#computational-scheme-6)](#computational-scheme-6)
-
-[6.7 Parameter Estimates
-[187](#parameter-estimates-6)](#parameter-estimates-6)
-
-[6.8 Numerical Example
-[189](#numerical-example-3)](#numerical-example-3)
-
-[Chapter 7 -- Rainfall Dependent Inflow and Infiltration
-[195](#rainfall-dependent-inflow-and-infiltration)](#rainfall-dependent-inflow-and-infiltration)
-
-[7.1 Introduction [195](#introduction-5)](#introduction-5)
-
-[7.2 Governing Equations
-[195](#governing-equations-7)](#governing-equations-7)
-
-[7.3 Computational Scheme
-[201](#computational-scheme-7)](#computational-scheme-7)
-
-[7.4 Parameter Estimates
-[203](#parameter-estimates-7)](#parameter-estimates-7)
-
-[7.5 Numerical Example
-[206](#numerical-example-4)](#numerical-example-4)
-
-[References [209](#references)](#references)
-
-[Glossary [225](#glossary)](#glossary)
-
-# 
-
-# List of Figures
-
-[**Figure 1‑1 Elements of a typical urban drainage system.**
-[15](#_Toc426447661)](#_Toc426447661)
-
-[**Figure 1‑2 SWMM\'s conceptual model of a stormwater drainage
-system.** [16](#_Toc426447662)](#_Toc426447662)
-
-[**Figure 1‑3 Processes modeled by SWMM.**
-[19](#_Toc426447663)](#_Toc426447663)
-
-[**Figure 1‑4 Block diagram of SWMM\'s state transition process.**
-[21](#_Toc426447664)](#_Toc426447664)
-
-[**Figure 1‑5 Flow chart of SWMM\'s simulation procedure.**
-[24](#_Toc426447665)](#_Toc426447665)
-
-[**Figure 1‑6 Interpolation of reported values from computed values.**
-[26](#_Toc426447666)](#_Toc426447666)
-
-[**Figure 2‑1 Sinusoidal interpolation of hourly temperatures.**
-[43](#_Toc426447667)](#_Toc426447667)
-
-[**Figure 3‑1 Idealized representation of a subcatchment.**
-[50](#_Toc426447668)](#_Toc426447668)
-
-[**Figure 3‑2 Nonlinear reservoir model of a subcatchment.**
-[51](#_Toc426447669)](#_Toc426447669)
-
-[**Figure 3‑3 Types of subareas within a subcatchment.**
-[53](#_Toc426447670)](#_Toc426447670)
-
-[**Figure 3‑4 Idealized subcatchment partitioning for overland flow.**
-[54](#_Toc426447671)](#_Toc426447671)
-
-[**Figure 3‑5 Re-routing of overland flow.**
-[59](#_Toc426447672)](#_Toc426447672)
-
-[**Figure 3‑6 Fisk B catchment, Portland, Oregon.**
-[61](#_Toc426447673)](#_Toc426447673)
-
-[**Figure 3‑7 Detailed view of two Fisk B subcatchments.**
-[62](#_Toc426447674)](#_Toc426447674)
-
-[**Figure 3‑8 Idealized representation of a subcatchment.**
-[67](#_Toc426447675)](#_Toc426447675)
-
-[**Figure 3‑9 Rectangular subcatchments for illustration of shape and
-width effects.** [68](#_Toc426447676)](#_Toc426447676)
-
-[**Figure 3‑10 Subcatchment hydrographs for different shapes of Figure
-3-9.** [69](#_Toc426447677)](#_Toc426447677)
-
-[**Figure 3‑11 Irregular subcatchment shape for width calculations.**
-[71](#_Toc426447678)](#_Toc426447678)
-
-[**Figure 3‑12 Runoff results for illustrative example.**
-[79](#_Toc426447679)](#_Toc426447679)
-
-[**Figure 3‑13 SCS (NRCS) triangular unit hydrograph.**
-[82](#_Toc426447680)](#_Toc426447680)
-
-[**Figure 4‑1 Physical properties for Woodburn silt loam, Benton County,
-Oregon.** [87](#_Toc426447681)](#_Toc426447681)
-
-[**Figure 4‑2 The Horton infiltration curve.**.
-[88](#_Toc426447682)](#_Toc426447682)
-
-[**Figure 4‑3 Cumulative infiltration F as the area under the Horton
-curve.** [89](#_Toc426447683)](#_Toc426447683)
-
-[**Figure 4‑4 Regeneration (recovery) of infiltration capacity during
-dry time steps.** [91](#_Toc426447684)](#_Toc426447684)
-
-[**Figure 4‑5 Two-zone representation of the Green-Ampt infiltration
-model.** [103](#_Toc426447685)](#_Toc426447685)
-
-[**Figure 4‑6 Illustration of infiltration capacity as function of
-cumulative infiltration for the Green-Ampt method.**
-[105](#_Toc426447686)](#_Toc426447686)
-
-[**Figure 4‑7 Green-Ampt recovery parameters as functions of hydraulic
-conductivity.** [108](#_Toc426447687)](#_Toc426447687)
-
-[**Figure 4‑8 Infiltration rates produced by different methods for a
-2-inch rainfall event.** [126](#_Toc426447688)](#_Toc426447688)
-
-[**Figure 5‑1 Definitional sketch of the two-zone groundwater model.**
-[128](#_Toc426447689)](#_Toc426447689)
-
-[**Figure 5‑2 Heights used to compute lateral groundwater flow rate.**
-[137](#_Toc426447690)](#_Toc426447690)
-
-[**Figure 5‑3 Relation between soil moisture limits and soil texture
-class.** [143](#_Toc426447691)](#_Toc426447691)
-
-[**Figure 5‑4 SPAW\'s soil water characteristics calculator.**
-[149](#_Toc426447692)](#_Toc426447692)
-
-[**Figure 5‑5 Measured hydraulic conductivity for three soils.**
-[151](#_Toc426447693)](#_Toc426447693)
-
-[**Figure 5‑6 Fitting SWMM\'s hydraulic conductivity equation to a power
-law equation.** [153](#_Toc426447694)](#_Toc426447694)
-
-[**Figure 5‑7 Definition sketch for Dupuit-Forcheimer seepage to an
-adjacent channel.** [157](#_Toc426447695)](#_Toc426447695)
-
-[**Figure 5‑8 Definition sketch for Hooghoudt's method for flow to
-circular drains.** [158](#_Toc426447696)](#_Toc426447696)
-
-[**Figure 5‑9 Surface runoff and groundwater flow for the illustrative
-groundwater example.** [161](#_Toc426447697)](#_Toc426447697)
-
-[**Figure 6‑1 Typical gage catch deficiency correction.**
-[165](#_Toc426447698)](#_Toc426447698)
-
-[**Figure 6‑2 Subcatchment partitionings used for snowmelt and runoff.**
-[166](#_Toc426447699)](#_Toc426447699)
-
-[**Figure 6‑3 Seasonal variation of melt coefficients.**
-[174](#_Toc426447700)](#_Toc426447700)
-
-[**Figure 6‑4 Typical areal depletion curve for natural area and
-temporary curve for new snow.** [177](#_Toc426447701)](#_Toc426447701)
-
-[**Figure 6‑5 Effect of snow cover on areal depletion curves.**
-[179](#_Toc426447702)](#_Toc426447702)
-
-[**Figure 6‑6 Schematic of liquid water routing through snow pack.**
-[181](#_Toc426447703)](#_Toc426447703)
-
-[**Figure 6‑7 Continuous air temperature for illustrative snowmelt
-example.** [192](#_Toc426447704)](#_Toc426447704)
-
-[**Figure 6‑8 Precipitation amounts for illustrative snowmelt example.**
-[193](#_Toc426447705)](#_Toc426447705)
-
-[**Figure 6‑9 Snow pack depth for illustrative snowmelt example.**
-[193](#_Toc426447706)](#_Toc426447706)
-
-[**Figure 6‑10 Runoff time series for illustrative snowmelt example.**
-[194](#_Toc426447707)](#_Toc426447707)
-
-[**Figure 7‑1 Components of wet-weather wastewater flow.**
-[196](#_Toc426447708)](#_Toc426447708)
-
-[**Figure 7‑2 Example of an RDII triangular unit hydrograph.**
-[197](#_Toc426447709)](#_Toc426447709)
-
-[**Figure 7‑3 Application of a unit hydrograph to a storm event.**
-[198](#_Toc426447710)](#_Toc426447710)
-
-[**Figure 7‑4 Use of three unit hydrographs to represent RDII.**
-[200](#_Toc426447711)](#_Toc426447711)
-
-[**Figure 7‑5 Sewershed delineation.**
-[204](#_Toc426447712)](#_Toc426447712)
-
-[**Figure 7‑6 Extracting RDII flow from a continuous flow monitor.**
-[205](#_Toc426447713)](#_Toc426447713)
-
-[**Figure 7‑7 Fitting unit hydrographs to an RDII flow record.**
-[205](#_Toc426447714)](#_Toc426447714)
-
-[**Figure 7‑8 Unit hydrographs used for the illustrative RDII example.**
-[207](#_Toc426447715)](#_Toc426447715)
-
-[**Figure 7‑9 Time series of RDII flows for the illustrative RDII
-example.** [207](#_Toc426447716)](#_Toc426447716)
-
-[**Figure 7‑10 Excerpt from the RDII interface file for the illustrative
-RDII example.** [208](#_Toc426447717)](#_Toc426447717)
-
-# 
-
-# List of Tables
-
-[**Table 1‑1 Development history of SWMM**
-[14](#_Toc430249121)](#_Toc430249121)
-
-[**Table 1‑2 SWMM\'s modeling objects**
-[17](#_Toc430249122)](#_Toc430249122)
-
-[**Table 1‑3 State variables used by SWMM**
-[22](#_Toc430249123)](#_Toc430249123)
-
-[**Table 1‑4 Units of expression used by SWMM**
-[27](#_Toc430249124)](#_Toc430249124)
-
-[**Table 2‑1 15-minute precipitation data from NCDC Climate Data
-Online** [34](#_Toc430249125)](#_Toc430249125)
-
-[**Table 2‑2 15-minute precipitation data in NCDC FTP file format**
-[34](#_Toc430249126)](#_Toc430249126)
-
-[**Table 2‑3 15-minute precipitation data in comma-delimited format**
-[35](#_Toc430249127)](#_Toc430249127)
-
-[**Table 2‑4 15-minute precipitation data in space-delimited format**
-[36](#_Toc430249128)](#_Toc430249128)
-
-[**Table 2‑5 15-minute precipitation data in fixed-length format**
-[36](#_Toc430249129)](#_Toc430249129)
-
-[**Table 2‑6 Record layout of Canadian HYL0 and HLY21 hourly
-precipitation files** [37](#_Toc430249130)](#_Toc430249130)
-
-[**Table 2‑7 Record layout of Canadian FIF21 15-minute precipitation
-files** [37](#_Toc430249131)](#_Toc430249131)
-
-[**Table 2‑8 Contents of an NCDC GHCN-Daily climate file**
-[40](#_Toc430249132)](#_Toc430249132)
-
-[**Table 2‑9 Contents of an NCDC DS3200 climate file**
-[40](#_Toc430249133)](#_Toc430249133)
-
-[**Table 2‑10 Layout of the ID portion of an NCDC DS3200 climate file
-record** [41](#_Toc430249134)](#_Toc430249134)
-
-[**Table 2‑11 Layout of the data portion of an NCDC DS3200 climate file
-record** [41](#_Toc430249135)](#_Toc430249135)
-
-[**Table 2‑12 Record layout of Canadian DLY daily climatologic files**
-[42](#_Toc430249136)](#_Toc430249136)
-
-[**Table 2‑13 Example user-prepared climate file**
-[42](#_Toc430249137)](#_Toc430249137)
-
-[**Table 2‑14 Time zones and standard meridians (degrees west
-longitude)** [46](#_Toc430249138)](#_Toc430249138)
-
-[**Table 3‑1 Impervious area as a percentage of land use.**
-[65](#_Toc430249139)](#_Toc430249139)
-
-[**Table 3‑2 Coefficients for Southerland\'s EIA equations.**
-[66](#_Toc430249140)](#_Toc430249140)
-
-[**Table 3‑3 Data for example of effect of subcatchment width.**
-[68](#_Toc430249141)](#_Toc430249141)
-
-[**Table 3‑4 Width computations for Portland example.**
-[70](#_Toc430249142)](#_Toc430249142)
-
-[**Table 3‑5 Estimates of Manning\'s roughness coefficient for overland
-flow** [74](#_Toc430249143)](#_Toc430249143)
-
-[**Table 3‑6 Sensitivity of runoff volume and peak flow to surface
-runoff parameters.** [77](#_Toc430249144)](#_Toc430249144)
-
-[**Table 3‑7 Parameters used for illustrative runoff example**
-[78](#_Toc430249145)](#_Toc430249145)
-
-[**Table 3‑8 Contents of a typical Routing Interface file**
-[84](#_Toc430249146)](#_Toc430249146)
-
-[**Table 4‑1 Hydrologic soil group meanings**
-[86](#_Toc430249147)](#_Toc430249147)
-
-[**Table 4‑2 Horton parameters for selected Georgia soils**
-[94](#_Toc430249148)](#_Toc430249148)
-
-[**Table 4‑3 Horton parameters provided by Horton**
-[95](#_Toc430249149)](#_Toc430249149)
-
-[**Table 4‑4 Values of f~∞~ for Hydrologic Soil Groups**
-[96](#_Toc430249150)](#_Toc430249150)
-
-[**Table 4‑5 Rate of decay of infiltration capacity for different values
-of kd** [97](#_Toc430249151)](#_Toc430249151)
-
-[**Table 4‑6 Representative values for f0**
-[98](#_Toc430249152)](#_Toc430249152)
-
-[**Table 4‑7 Green-Ampt parameters for different soil classes**
-[113](#_Toc430249153)](#_Toc430249153)
-
-[**Table 4‑8 Typical values of *θ*dmax for various soil types.**
-[115](#_Toc430249154)](#_Toc430249154)
-
-[**Table 4‑9 Runoff curve numbers for selected land uses**
-[123](#_Toc430249155)](#_Toc430249155)
-
-[**Table 4‑10 Parameters used in example comparison of infiltration
-methods** [125](#_Toc430249156)](#_Toc430249156)
-
-[**Table 5‑1 Volumetric moisture content at field capacity and wilting
-point** [144](#_Toc430249157)](#_Toc430249157)
-
-[**Table 5‑2 Volumetric moisture content at field capacity and wilting
-point** [144](#_Toc430249158)](#_Toc430249158)
-
-[**Table 5‑3 Average moisture limits and saturated hydraulic
-conductivity for different soil types**
-[145](#_Toc430249159)](#_Toc430249159)
-
-[**Table 5‑4 Default properties of low-density soils used in the EPA
-HELP model** [146](#_Toc430249160)](#_Toc430249160)
-
-[**Table 5‑5 Default properties of moderate-density soils used in the
-EPA HELP model** [147](#_Toc430249161)](#_Toc430249161)
-
-[**Table 5‑6 Soil texture abbreviations**
-[147](#_Toc430249162)](#_Toc430249162)
-
-[**Table 5‑7 Regression equations for soil moisture limits**
-[149](#_Toc430249163)](#_Toc430249163)
-
-[**Table 5‑8 Regression estimates of soil moisture limits from the SPAW
-calculator\*** [150](#_Toc430249164)](#_Toc430249164)
-
-[**Table 5‑9 Estimated HCO for different soil types**
-[154](#_Toc430249165)](#_Toc430249165)
-
-[**Table 5‑10 DET (in feet) for different soil types and land cover**
-[155](#_Toc430249166)](#_Toc430249166)
-
-[**Table 5‑11 Parameters used in groundwater example**
-[160](#_Toc430249167)](#_Toc430249167)
-
-[**Table 6‑1 Guidelines for level of service in snow and ice control**
-[169](#_Toc430249168)](#_Toc430249168)
-
-[**Table 6‑2 Summary of snowmelt parameters (in US customary units)**
-[187](#_Toc430249169)](#_Toc430249169)
-
-[**Table 6‑3 Typical areal depletion curve for natural areas**
-[188](#_Toc430249170)](#_Toc430249170)
-
-[**Table 6‑4 Subcatchment and snow pack parameters for illustrative
-snowmelt example** [189](#_Toc430249171)](#_Toc430249171)
-
-[**Table 6‑5 Daily temperatures for illustrative snowmelt example**
-[190](#_Toc430249172)](#_Toc430249172)
-
-[**Table 6‑6 Periods of precipitation for illustrative snowmelt
-example** [191](#_Toc430249173)](#_Toc430249173)
-
-[**Table 7‑1 Rainfall time series for the illustrative RDII example**
-[206](#_Toc430249174)](#_Toc430249174)
-
-# Acronyms and Abbreviations
-
-AASHTO American Association of State Highway and Transportation
-Officials
-
-ADC areal depletion curve
-
-ADT average daily traffic
-
-AMC antecedent moisture condition
-
-ASCE American Society of Civil Engineers
-
-AWND average daily wind speed
-
-BES Bureau of Environmental Services
-
-BMP best management practice
-
-BWF base wastewater flow
-
-CDO Climate Data Online
-
-CFS cubic feet per second
-
-CMS cubic meters per second
-
-CSO combined sewer overflow
-
-DCIA directly connected impervious area
-
-EIA effective impervious area
-
-EPA Environmental Protection Agency
-
-ET evapotranspiration
-
-EVAP daily pan evaporation
-
-FTP file transfer protocol
-
-GHCN Global Historical Climatology Network
-
-GIS geographic information system
-
-GPM gallons per minute
-
-GWI groundwater infiltration
-
-HELP Hydrological Evaluation of Landfill Performance
-
-HSPF Hydrologic Simulation Program - Fortran
-
-IDF intensity- duration-frequency
-
-ILLUDAS Illinois Urban Drainage Area Simulator
-
-LID low impact development
-
-LPS liters per second
-
-MGD million gallons per day
-
-MLD million liters per day
-
-NCDC National Climatic Data Center
-
-NOAA National Oceanic and Atmospheric Administration
-
-NRCS Natural Resources Conservation Service
-
-NWS National Weather Service
-
-PRMS Precipitation-Runoff Modeling System
-
-RDII rainfall dependent inflow and infiltration
-
-SCF Snow Catch Factor
-
-SCS Soil Conservation Service
-
-SFWMD South Florida Water Management District
-
-SPAW Soil-Plant-Air-Water
-
-STORM Storage, Treatment, Overflow, Runoff Model
-
-SWMM Storm Water Management Model
-
-TMAX maximum daily temperature
-
-TMIN minimum daily temperature
-
-TVA Tennessee Valley Authority
-
-UDFCD Urban Drainage and Flood Control District
-
-UH unit hydrograph
-
-USCS Unified Soil Classification System
-
-USDA United States Department of Agriculture
-
-USGS United States Geological Survey
-
-WDMV 24-hour wind movement
-
-WE water equivalent
-
-**\**
-
-# 
-
-# - Overview
-
-## 1.1 Introduction
-
-Urban runoff quantity and quality constitute problems of both a
-historical and current nature. Cities have long assumed the
-responsibility of control of stormwater flooding and treatment of point
-sources (e.g., municipal sewage) of wastewater. Since the 1960s, the
-severe pollution potential of urban nonpoint sources, principally
-combined sewer overflows and stormwater discharges, has been recognized,
-both through field observation and federal legislation. The advent of
-modern computers has led to the development of complex, sophisticated
-tools for analysis of both quantity and quality pollution problems in
-urban areas and elsewhere (Singh, 1995). The EPA Storm Water Management
-Model, SWMM, first developed in 1969-71, was one of the first such
-models. It has been continually maintained and updated and is perhaps
-the best known and most widely used of the available urban runoff
-quantity/quality models (Huber and Roesner, 2013).
-
-SWMM is a dynamic rainfall-runoff simulation model used for single event
-or long-term (continuous) simulation of runoff quantity and quality from
-primarily urban areas. The runoff component of SWMM operates on a
-collection of subcatchment areas that receive precipitation and generate
-runoff and pollutant loads. The routing portion of SWMM transports this
-runoff through a system of pipes, channels, storage/treatment devices,
-pumps, and regulators. SWMM tracks the quantity and quality of runoff
-generated within each subcatchment, and the flow rate, flow depth, and
-quality of water in each pipe and channel during a simulation period
-comprised of multiple time steps.
-
-Table 1-1 summarizes the development history of SWMM. The current
-edition, Version 5, is a complete re-write of the previous releases. The
-reference manual for this edition of SWMM is comprised of three volumes.
-Volume I describes SWMM's hydrologic models, Volume II its hydraulic
-models, and Volume III its water quality and low impact development
-models. These manuals complement the SWMM 5 User's Manual (US EPA,
-2010), which explains how to run the program, and the SWMM 5
-Applications Manual (US EPA, 2009) which presents a number of worked-out
-examples. The procedures described in this reference manual are based on
-earlier descriptions included in the original SWMM documentation
-(Metcalf and Eddy et al., 1971a, 1971b, 1971c, 1971d), intermediate
-reports (Huber et al., 1975; Heaney et al., 1975; Huber et al., 1981),
-plus new material. This information supersedes the Version 4.0
-documentation (Huber and Dickinson, 1988; Roesner et al., 1988) and
-includes descriptions of some newer procedures implemented since 1988.
-More information on current documentation and the general status of the
-EPA Storm Water Management Model as well as the full program and its
-source code is available on the EPA SWMM web site:.
-.
-
-+-----------------+----------+-------------------+-----------------------+
-| **Version**     | **Year** | **Contributors**  | **Comments**          |
-+:================+:=========+:==================+:======================+
-| SWMM I          | 1971     | Metcalf & Eddy,   | First version of      |
-|                 |          | Inc.              | SWMM; focus was CSO   |
-|                 |          |                   | modeling; few of its  |
-|                 |          | Water Resources   | methods are still     |
-|                 |          | Engineers         | used today.           |
-|                 |          |                   |                       |
-|                 |          | University of     |                       |
-|                 |          | Florida           |                       |
-+-----------------+----------+-------------------+-----------------------+
-| SWMM II         | 1975     | University of     | First widely          |
-|                 |          | Florida           | distributed version   |
-|                 |          |                   | of SWMM.              |
-+-----------------+----------+-------------------+-----------------------+
-| SWMM 3          | 1981     | University of     | Full dynamic wave     |
-|                 |          | Florida           | flow routine,         |
-|                 |          |                   | Green-Ampt            |
-|                 |          | Camp Dresser &    | infiltration, snow    |
-|                 |          | McKee             | melt, and continuous  |
-|                 |          |                   | simulation added.     |
-+-----------------+----------+-------------------+-----------------------+
-| SWMM 3.3        | 1983     | US EPA            | First PC version of   |
-|                 |          |                   | SWMM.                 |
-+-----------------+----------+-------------------+-----------------------+
-| SWMM 4          | 1988     | Oregon State      | Groundwater, RDII,    |
-|                 |          | University        | irregular channel     |
-|                 |          |                   | cross-sections and    |
-|                 |          | Camp Dresser &    | other refinements     |
-|                 |          | McKee             | added over a series   |
-|                 |          |                   | of updates throughout |
-|                 |          |                   | the 1990's.           |
-+-----------------+----------+-------------------+-----------------------+
-| SWMM 5          | 2005     | US EPA            | Complete re-write of  |
-|                 |          |                   | the SWMM engine in C; |
-|                 |          | CDM-Smith         | graphical user        |
-|                 |          |                   | interface added;      |
-|                 |          |                   | improved algorithms   |
-|                 |          |                   | and new features      |
-|                 |          |                   | (e.g., LID modeling)  |
-|                 |          |                   | added.                |
-+-----------------+----------+-------------------+-----------------------+
-
-: []{#_Toc430249121 .anchor}**Table 1‑1 Development history of SWMM**
-
-## 1.2 SWMM's Object Model
-
-Figure 1-1 depicts the elements included in a typical urban drainage
-system. SWMM conceptualizes this system as a series of water and
-material flows between several major environmental compartments. These
-compartments include:
-
-

-
-
Figure 1‑1 Elements of a typical urban
-drainage system.

-

-
-- The Atmosphere compartment, which generates precipitation and deposits
-  pollutants onto the Land Surface compartment.
-
-- The Land Surface compartment receives precipitation from the
-  Atmosphere compartment in the form of rain or snow. It sends outflow
-  in the forms of 1) evaporation back to the Atmosphere compartment, 2)
-  infiltration into the Sub-Surface compartment and 3) surface runoff
-  and pollutant loadings on to the Conveyance compartment.
-
-- The Sub-Surface compartment receives infiltration from the Land
-  Surface compartment and transfers a portion of this inflow to the
-  Conveyance compartment as groundwater interflow.
-
-- The Conveyance compartment contains a network of elements (channels,
-  pipes, pumps, and regulators) and storage/treatment units that convey
-  water to outfalls or to treatment facilities. Inflows to this
-  compartment can come from surface runoff, groundwater interflow,
-  sanitary dry weather flow, or from user-defined time series.
-
-Not all compartments need appear in a particular SWMM model. For
-example, one could model just the Conveyance compartment, using
-pre-defined hydrographs and pollutographs as inputs. As illustrated in
-Figure 1-1, SWMM can be used to model any combination of stormwater
-collection systems, both separate and combined sanitary sewer systems,
-as well as natural catchment and river channel systems.
-
-Figure 1-2 shows how SWMM conceptualizes the physical elements of the
-actual system depicted in Figure 1-1 with a standard set of modeling
-objects. The principal objects used to model the rainfall/runoff process
-are Rain Gages and Subcatchments. Snowmelt is modeled with Snow Pack
-objects placed on top of subcatchments while Aquifer objects placed
-below subcatchments are used to model groundwater flow. The conveyance
-portion of the drainage system is modeled with a network of Nodes and
-Links. Nodes are points that represent simple junctions, flow dividers,
-storage units, or outfalls. Links connect nodes to one another with
-conduits (pipes and channels), pumps, or flow regulators (orifices,
-weirs, or outlets). Land Use and Pollutant objects are used to describe
-water quality. Finally, a group of data objects that includes Curves,
-Time Series, Time Patterns, and Control Rules, are used to characterize
-the inflows and operating behavior of the various physical objects in a
-SWMM model. Table 1-2 provides a summary of the various objects used in
-SWMM. Their properties and functions will be described in more detail
-throughout the course of this manual.
-
-

-Objects1.png
-
Figure 1‑2 SWMM's conceptual model of a
-stormwater drainage system.

-

-
-+--------------+---------------+--------------------------------------+
-| **Category** | **Object      | **Description**                      |
-|              | Type**        |                                      |
-+:=============+:==============+:=====================================+
-| Hydrology    | Rain Gage     | Source of precipitation data to one  |
-|              |               | or more subcatchments.               |
-|              +---------------+--------------------------------------+
-|              | Subcatchment  | A land parcel that receives          |
-|              |               | precipitation associated with a rain |
-|              |               | gage and generates runoff that flows |
-|              |               | into a drainage system node or to    |
-|              |               | another subcatchment.                |
-|              +---------------+--------------------------------------+
-|              | Aquifer       | A subsurface area that receives      |
-|              |               | infiltration from the subcatchment   |
-|              |               | above it and exchanges groundwater   |
-|              |               | flow with a conveyance system node.  |
-|              +---------------+--------------------------------------+
-|              | Snow Pack     | Accumulated snow that covers a       |
-|              |               | subcatchment.                        |
-|              +---------------+--------------------------------------+
-|              | Unit          | A response function that describes   |
-|              |               | the amount of sewer                  |
-|              | Hydrograph    | inflow/infiltration generated over   |
-|              |               | time per unit of instantaneous       |
-|              |               | rainfall.                            |
-+--------------+---------------+--------------------------------------+
-| Hydraulics   | Junction      | A point in the conveyance system     |
-|              |               | where conduits connect to one        |
-|              |               | another with negligible storage      |
-|              |               | volume (e.g., manholes, pipe         |
-|              |               | fittings, or stream junctions).      |
-|              +---------------+--------------------------------------+
-|              | Outfall       | An end point of the conveyance       |
-|              |               | system where water is discharged to  |
-|              |               | a receptor (such as a receiving      |
-|              |               | stream or treatment plant) with      |
-|              |               | known water surface elevation.       |
-|              +---------------+--------------------------------------+
-|              | Divider       | A point in the conveyance system     |
-|              |               | where the inflow splits into two     |
-|              |               | outflow conduits according to a      |
-|              |               | known relationship.                  |
-|              +---------------+--------------------------------------+
-|              | Storage Unit  | A pond, lake, impoundment, or        |
-|              |               | chamber that provides water storage. |
-|              +---------------+--------------------------------------+
-|              | Conduit       | A channel or pipe that conveys water |
-|              |               | from one conveyance system node to   |
-|              |               | another.                             |
-|              +---------------+--------------------------------------+
-|              | Pump          | A device that raises the hydraulic   |
-|              |               | head of water.                       |
-|              +---------------+--------------------------------------+
-|              | Regulator     | A weir, orifice or outlet used to    |
-|              |               | direct and regulate flow between two |
-|              |               | nodes of the conveyance system.      |
-+--------------+---------------+--------------------------------------+
-
-: []{#_Toc430249122 .anchor}**Table 1‑2 SWMM\'s modeling objects**
-
-**Table 1-2 SWMM's modeling objects (continued)**
-
-+--------------+---------------+--------------------------------------+
-| **Category** | **Object      | **Description**                      |
-|              | Type**        |                                      |
-+:=============+:==============+:=====================================+
-| Water        | Pollutant     | A contaminant that can build up and  |
-| Quality      |               | be washed off of the land surface or |
-|              |               | be introduced directly into the      |
-|              |               | conveyance system.                   |
-|              +---------------+--------------------------------------+
-|              | Land Use      | A classification used to             |
-|              |               | characterize the functions that      |
-|              |               | describe pollutant buildup and       |
-|              |               | washoff.                             |
-+--------------+---------------+--------------------------------------+
-| Treatment    | LID Control   | A low impact development control,    |
-|              |               | such as a bio-retention cell, porous |
-|              |               | pavement, or vegetative swale, used  |
-|              |               | to reduce surface runoff through     |
-|              |               | enhanced infiltration.               |
-|              +---------------+--------------------------------------+
-|              | Treatment     | A user-defined function that         |
-|              |               | describes how pollutant              |
-|              | Function      | concentrations are reduced at a      |
-|              |               | conveyance system node as a function |
-|              |               | of certain variables, such as        |
-|              |               | concentration, flow rate, water      |
-|              |               | depth, etc.                          |
-+--------------+---------------+--------------------------------------+
-| Data Object  | Curve         | A tabular function that defines the  |
-|              |               | relationship between two quantities  |
-|              |               | (e.g., flow rate and hydraulic head  |
-|              |               | for a pump, surface area and depth   |
-|              |               | for a storage node, etc.).           |
-|              +---------------+--------------------------------------+
-|              | Time Series   | A tabular function that describes    |
-|              |               | how a quantity varies with time      |
-|              |               | (e.g., rainfall, outfall surface     |
-|              |               | elevation, etc.).                    |
-|              +---------------+--------------------------------------+
-|              | Time Pattern  | A set of factors that repeats over a |
-|              |               | period of time (e.g., diurnal hourly |
-|              |               | pattern, weekly daily pattern,       |
-|              |               | etc.).                               |
-|              +---------------+--------------------------------------+
-|              | Control Rules | IF-THEN-ELSE statements that         |
-|              |               | determine when specific control      |
-|              |               | actions are taken (e.g., turn a pump |
-|              |               | on or off when the flow depth at a   |
-|              |               | given node is above or below a       |
-|              |               | certain value).                      |
-+--------------+---------------+--------------------------------------+
-
-## 1.3 SWMM's Process Models
-
-Figure 1-3 depicts the processes that SWMM models using the objects
-described previously and how they are tied to one another. The
-hydrological processes depicted in this diagram include:
-
-[]{#_Toc426447663 .anchor}**Figure 1‑3 Processes modeled by SWMM.**
-
-- time-varying precipitation
-
-- snow accumulation and melting
-
-- rainfall interception from depression storage (initial abstraction)
-
-- evaporation of standing surface water
-
-- infiltration of rainfall into unsaturated soil layers
-
-- percolation of infiltrated water into groundwater layers
-
-- interflow between groundwater and the drainage system
-
-- nonlinear reservoir routing of overland flow
-
-- infiltration and evaporation of rainfall/runoff captured by Low Impact
-  Development controls.
-
-The hydraulic processes occurring within SWMM's conveyance compartment
-include:
-
-- external inflow of surface runoff, groundwater interflow,
-  rainfall-dependent infiltration/inflow, dry weather sanitary flow, and
-  user-defined inflows
-
-- unsteady, non-uniform flow routing through any configuration of open
-  channels, pipes and storage units
-
-- various possible flow regimes such as backwater, surcharging, reverse
-  flow, and surface ponding
-
-- flow regulation via pumps, weirs, and orifices including time- and
-  state-dependent control rules that govern their operation.
-
-Regarding water quality, the following processes can be modeled for any
-number of user-defined water quality constituents:
-
-- dry-weather pollutant buildup over different land uses
-
-- pollutant washoff from specific land uses during storm events
-
-- direct contribution of rainfall deposition
-
-- reduction in dry-weather buildup due to street cleaning
-
-- reduction in washoff loads due to BMPs
-
-- entry of dry weather sanitary flows and user-specified external
-  inflows at any point in the drainage system
-
-- routing of water quality constituents through the drainage system
-
-- reduction in constituent concentration through treatment in storage
-  units or by natural processes in pipes and channels.
-
-The numerical procedures that SWMM uses to model the hydrologic
-processes listed above are discussed in detail in subsequent chapters of
-this volume. SWMM's hydraulic, water quality, treatment and low impact
-development processes are described in subsequent volumes of this
-manual.
-
-## 1.4 Simulation Process Overview
-
-SWMM is a distributed discrete time simulation model. It computes new
-values of its state variables over a sequence of time steps, where at
-each time step the system is subjected to a new set of external inputs.
-As its state variables are updated, other output variables of interest
-are computed and reported. This process is represented mathematically
-with the following general set of equations that are solved at each time
-step as the simulation proceeds:
-
-$X_{t} = f(X_{t - 1},\ I_{t},\ P)$ (1-1)
-
-$Y_{t} = g(X_{t},\ P)$ (1-2)
-
-where
-
-| Symbol | Description |
-| :--- | :--- |
-| *Xt* | a vector of state variables at time *t*, |
-| *Yt* | a vector of output variables at time *t*, |
-| *It* | a vector of inputs at time *t*, |
-| *P* | a vector of constant parameters, |
-| *f* | a vector-valued state transition function, |
-| *g* | a vector-valued output transform function. |
-
-Figure 1-4 depicts the simulation process in block diagram fashion.
-
-[]{#_Toc426447664 .anchor}**Figure 1‑4 Block diagram of SWMM\'s state
-transition process.**
-
-The variables that make up the state vector *Xt* are listed in Table
-1-3. This is a surprisingly small number given the comprehensive nature
-of SWMM. All other quantities can be computed from these variables,
-external inputs, and fixed input parameters. The meaning of some of the
-less obvious state variables, such as those used for snow melt, is
-discussed in later chapters.
-
-+----------------+--------------+----------------------------------+------------+
-| **Process**    | **Variable** | **Description**                  | **Initial  |
-|                |              |                                  | Value**    |
-+:===============+:=============+:=================================+:===========+
-| Runoff         | *d*          | Depth of runoff on a             | 0          |
-|                |              | subcatchment surface             |            |
-+----------------+--------------+----------------------------------+------------+
-| Infiltration\* | *tp*       | Equivalent time on the Horton    | 0          |
-|                |              | curve                            |            |
-|                +--------------+----------------------------------+------------+
-|                | *Fe*       | Cumulative excess infiltration   | 0          |
-|                |              | volume                           |            |
-|                +--------------+----------------------------------+------------+
-|                | *Fu*         | Upper zone moisture content      | 0          |
-|                +--------------+----------------------------------+------------+
-|                | *T*          | Time until the next rainfall     | 0          |
-|                |              | event                            |            |
-|                +--------------+----------------------------------+------------+
-|                | *P*          | Cumulative rainfall for current  | 0          |
-|                |              | event                            |            |
-|                +--------------+----------------------------------+------------+
-|                | *S*          | Soil moisture storage capacity   | User       |
-|                |              | remaining                        | supplied   |
-+----------------+--------------+----------------------------------+------------+
-| Groundwater    | *θu*       | Unsaturated zone moisture        | User       |
-|                |              | content                          | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *dL*       | Depth of saturated zone          | User       |
-|                |              |                                  | supplied   |
-+----------------+--------------+----------------------------------+------------+
-| Snowmelt       | *wsnow*    | Snow pack depth                  | User       |
-|                |              |                                  | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *fw*         | Snow pack free water depth       | User       |
-|                |              |                                  | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *ati*        | Snow pack surface temperature    | User       |
-|                |              |                                  | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *cc*         | Snow pack cold content           | 0          |
-+----------------+--------------+----------------------------------+------------+
-| Flow Routing   | *y*          | Depth of water at a node         | User       |
-|                |              |                                  | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *q*          | Flow rate in a link              | User       |
-|                |              |                                  | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *a*          | Flow area in a link              | Inferred   |
-|                |              |                                  | from *q*   |
-+----------------+--------------+----------------------------------+------------+
-| Water Quality  | *tsweep*   | Time since a subcatchment was    | User       |
-|                |              | last swept                       | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *mB*       | Mass of pollutant on             | User       |
-|                |              | subcatchment surface             | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *mP*       | Mass of pollutant ponded on      | 0          |
-|                |              | subcatchment                     |            |
-|                +--------------+----------------------------------+------------+
-|                | *cN*       | Concentration of pollutant at a  | User       |
-|                |              | node                             | supplied   |
-|                +--------------+----------------------------------+------------+
-|                | *cL*       | Concentration of pollutant in a  | User       |
-|                |              | link                             | supplied   |
-+----------------+--------------+----------------------------------+------------+
-
-: []{#_Toc430249123 .anchor}**Table 1‑3 State variables used by SWMM**
-
-\*Only a sub-set of these variables is used, depending on the user's
-choice of infiltration method.
-
-Examples of user-supplied input variables *It* that produce changes to
-these state variables include:
-
-- meteorological conditions, such as precipitation, air temperature,
-  potential evaporation rate and wind speed
-
-- externally imposed inflow hydrographs and pollutographs at specific
-  nodes of the conveyance system
-
-- dry weather sanitary inflows to specific nodes of the conveyance
-  system
-
-- water surface elevations at specific outfalls of the conveyance system
-
-- control settings for pumps and regulators.
-
-The output vector *Yt* that SWMM computes from its updated state
-variables contains such reportable quantities as:
-
-- runoff flow rate and pollutant concentrations from each subcatchment
-
-- snow depth, infiltration rate and evaporation losses from each
-  subcatchment
-
-- groundwater table elevation and lateral groundwater outflow for each
-  subcatchment
-
-- total lateral inflow (from runoff, groundwater flow, dry weather flow,
-  etc.), water depth, and pollutant concentration for each conveyance
-  system node
-
-- overflow rate and ponded volume at each flooded node
-
-- flow rate, velocity, depth and pollutant concentration for each
-  conveyance system link.
-
-Regarding the constant parameter vector *P,* SWMM contains over 150
-different user-supplied constants and coefficients within its collection
-of process models. Most of these are either physical dimensions (e.g.,
-land areas, pipe diameters, invert elevations) or quantities that can be
-obtained from field observation (e.g., percent impervious cover),
-laboratory testing (e.g., various soil properties), or previously
-published data tables (e.g., pipe roughness based on pipe material). A
-smaller remaining number might require some degree of model calibration
-to determine their proper values. Not all parameters are required for
-every project (e.g., the 14 groundwater parameters for each subcatchment
-are not needed if groundwater is not being modeled). The subsequent
-chapters of this manual carefully define each parameter and make
-suggestions on how to estimate its value.
-
-A flowchart of the overall simulation process is shown in Figure 1-5.
-The process begins by reading a description of each object and its
-parameters from an input file whose format is described in the SWMM 5
-UsersManual (US EPA, 2010). Next the values of all state variables are
-initialized, as is the current simulation time (T), runoff time
-(Troff), and reporting time (Trpt).
-
-[]{#_Toc426447665 .anchor}**Figure 1‑5 Flow chart of SWMM\'s simulation
-procedure.**
-
-The program then enters a loop that first determines the time T1 at the
-end of the current routing time step (∆Trout). If the current runoff
-time Troff is less than T1, then new runoff calculations are
-repeatedly made and the runoff time updated until it equals or exceeds
-time T1. Each set of runoff calculations accounts for any precipitation,
-evaporation, snowmelt, infiltration, ground water seepage, overland
-flow, and pollutant buildup and washoff that can contribute flow and
-pollutant loads into the conveyance system.
-
-Once the runoff time is current, all inflows and pollutant loads
-occurring at time T are routed through the conveyance system over the
-time interval from T to T1. This process updates the flow, depth and
-velocity in each conduit, the water elevation at each node, the pumping
-rate for each pump, and the water level and volume in each storage unit.
-In addition, new values for the concentrations of all pollutants at each
-node and within each conduit are computed. Next a check is made to see
-if the current reporting time Trpt falls within the interval from T to
-T1. If it does, then a new set of output results at time Trpt are
-interpolated from the results at times T and T1 and are saved to an
-output file. The reporting time is also advanced by the reporting time
-step ∆Trpt. The simulation time T is then updated to T1 and the
-process continues until T reaches the desired total duration. SWMM's
-Windows-based user interface provides graphical tools for building the
-aforementioned input file and for viewing the computed output.
-
-## 1.5 Interpolation and Units
-
-SWMM uses linear interpolation to obtain values for quantities at times
-that fall in between times at which input time series are recorded or at
-which output results are computed. The concept is illustrated in Figure
-1-6 which shows how reported flow values are derived from the computed
-flow values on either side of it for the typical case where the
-reporting time step is larger than the routing time step. One exception
-to this convention is for precipitation and infiltration rates. These
-remain constant within a runoff time step and no interpolation is made
-when these values are used within SWMM's runoff algorithms or for
-reporting purposes. In other words, if a reporting time falls within a
-runoff time step the reported rainfall intensity is the value associated
-with the start of the runoff time step.
-
-![[]{#_Toc426447666 .anchor}**Figure 1‑6 Interpolation of reported
-values from computed
-values.**](VolumeI/media/media/image3.emf){width="6.1097222222222225in"
-height="3.4194444444444443in"}
-
-The units of expression used by SWMM's input variables, parameters, and
-output variables depend on the user's choice of flow units. If flow rate
-is expressed in US customary units then so are all other quantities; if
-SI metric units are used for flow rate then all other quantities use SI
-metric units. Table 1-4 lists the units associated with each of SWMM's
-major variables and parameters, for both US and SI systems. Internally
-within the computer code all calculations are carried out using feet as
-the unit of length and seconds as the unit of time and then converted
-back to the user's choice of unit system.
-
-[]{#_Toc430249124 .anchor}**Table 1‑4 Units of expression used by SWMM**
-
-+------------------------+----------------------+----------------------+
-| **Variable or          | **US Customary       | **SI Metric Units**  |
-| Parameter**            | Units**              |                      |
-+:=======================+:=====================+:=====================+
-| Area (subcatchment)    | acres                | hectares             |
-+------------------------+----------------------+----------------------+
-| Area (storage surface  | square feet          | square meters        |
-| area)                  |                      |                      |
-+------------------------+----------------------+----------------------+
-| Depression Storage     | inches               | millimeters          |
-+------------------------+----------------------+----------------------+
-| Depth                  | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Elevation              | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Evaporation            | inches/day           | millimeters/day      |
-+------------------------+----------------------+----------------------+
-| Flow Rate              | cubic feet/sec (cfs) | cubic meters/sec     |
-|                        |                      | (cms)                |
-|                        | gallons/min (gpm)    |                      |
-|                        |                      | liters/sec (lps)     |
-|                        | 106 gallons/day    |                      |
-|                        | (mgd)                | 106 liters/day     |
-|                        |                      | (mld)                |
-+------------------------+----------------------+----------------------+
-| Hydraulic Conductivity | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Hydraulic Head         | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Infiltration Rate      | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Length                 | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Manning's n            | seconds/meter1/3   | seconds/meter1/3   |
-+------------------------+----------------------+----------------------+
-| Pollutant Buildup      | mass/acre            | mass/hectare         |
-+------------------------+----------------------+----------------------+
-| Pollutant              | milligrams/liter     | milligrams/liter     |
-| Concentration          | (mg/L)               | (mg/L)               |
-|                        |                      |                      |
-|                        | micrograms/liter     | micrograms/liter     |
-|                        | (μg/L)               | (μg/L)               |
-|                        |                      |                      |
-|                        | organism             | organism             |
-|                        | counts/liter         | counts/liter         |
-+------------------------+----------------------+----------------------+
-| Rainfall Intensity     | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Rainfall Volume        | inches               | millimeters          |
-+------------------------+----------------------+----------------------+
-| Storage Volume         | cubic feet           | cubic meters         |
-+------------------------+----------------------+----------------------+
-| Temperature            | degrees Fahrenheit   | degrees Celsius      |
-+------------------------+----------------------+----------------------+
-| Velocity               | feet/second          | meters/second        |
-+------------------------+----------------------+----------------------+
-| Width                  | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Wind Speed             | miles/hour           | kilometers/hour      |
-+------------------------+----------------------+----------------------+
-
-#  -- Meteorology
-
-## 2.1 Precipitation
-
-### 2.1.1 Representation
-
-Precipitation is the principal driving force in rainfall-runoff-quality
-simulation. Stormwater runoff and nonpoint source runoff quality are
-directly dependent on the precipitation time series. These time series
-can range from just a few time periods for a single event to thousands
-of time periods used for a multi-year simulation. Within SWMM, the Rain
-Gage object is used to represent a source of precipitation data. Any
-number of Rain Gages may be used, data permitting, to represent spatial
-variability in precipitation patterns. Precipitation data for a specific
-Rain Gage is supplied either as a user-defined Time Series or through an
-external data file. Several different file formats are supported for
-data distributed by the U.S. National Climatic Data Center and
-Environment Canada as well as a standard user-prepared format. Because
-SWMM is a fully dynamic model that accounts for physical processes whose
-time scales are on the order of minutes or less, SWMM should not be run
-with either daily average or storm-averaged precipitation data.
-
-Note that precipitation is often used synonymously with rainfall, but
-precipitation data may also include snowfall. Because both are simply
-reported as incremental intensities or depths, the SWMM program
-differentiates between rainfall and snowfall by a user-supplied dividing
-temperature. In natural areas, a surface temperature of 34° to 35° F
-(1-2° C) provides the dividing line between equal probabilities of rain
-and snow (Eagleson, 1970; Corps of Engineers, 1956). However, this
-separation temperature might need to be somewhat lower in urban areas
-due to warmer surface temperatures.
-
-### 2.1.2 Single Event v. Continuous Simulation
-
-Models might be used to aid in urban drainage design for protection
-against flooding for a certain return period (e.g., five or ten years),
-or to protect against pollution of receiving waters at a certain
-frequency (e.g., only one combined sewer overflow per year). In these
-contexts, the frequency or return period needs to be associated with a
-very specific parameter. That is, for rainfall one may speak of
-frequency distributions of inter-event times, total storm depth, total
-storm duration or average storm intensity, all of which are different
-(Eagleson, 1970, pp. 183-190). But for the aforementioned objectives,
-and in fact, for almost all urban hydrology work, the frequencies of
-runoff and quality parameters are required, not those of rainfall. Thus,
-one may speak of the frequencies of maximum flow rate, total runoff
-volume, or total pollutant loads. These distributions are in no way the
-same as for similar rainfall parameters, although they may be related
-through analytical methods (Howard, 1976; Chan and Bras, 1979;
-Hydroscience, 1979; Adams and Papa, 2000). Finally, for pollution
-control, the real interest may lie in the frequency of water quality
-standards violations in the receiving water, which leads to further
-complications.
-
-SWMM is capable of simulating both single rainfall events as well as
-long-term time histories (e.g. several years or more) of a continuous
-precipitation record. In fact, the only distinctions between the two as
-far as SWMM is concerned is the simulation duration requested by the
-user and the need to supply meaningful initial conditions when only a
-single event is simulated.
-
-Continuous simulation offers an excellent, if not the only method for
-obtaining the frequency of events of interest, be they related to
-quantity or quality. But it has the disadvantages of a higher run time
-and the need for a continuous rainfall record. This has led to the use
-of a "design storm" or "design rainfall" or "design event" in a single
-event simulation instead. Of course, this idea long preceded continuous
-simulation, before the advent of modern computers. However, because of
-inherent simplifications, the choice of a design event leads to
-problems.
-
-### 2.1.3 Temporal Rainfall Variations
-
-The required time interval used to describe rainfall variations over
-time is a function of the catchment response to rainfall input. Small,
-steep, smooth, impervious catchments have fast response times, while
-large, flat, pervious catchments have slower response times. As a
-generality, shorter time increment data are preferable to longer time
-increment data, but for a large (e.g., 10 mi2 or 26 km2)
-subcatchment (coarse schematization), even the hourly inputs usually
-used for continuous simulation may be appropriate. Rainfall data with
-intervals larger than 1-hour (such as average daily rainfall or
-event-averaged rainfall) must be suitably disaggregated (Socolofsky et
-al., 2001) before they can be used in SWMM.
-
-The rain gage itself is usually the limiting factor. It is possible to
-reduce data from 24-hour charts from standard 24-hour, weighing-bucket
-gages to obtain 7.5-minute or 5-minute increment data, and some USGS
-float gages produce no better than 5-minute values. Shorter time
-increment data may usually be obtained only from tipping bucket gage
-installations.
-
-The rainfall records obtained from a gage may be of mixed quality. It
-may be possible to define some storms down to 1 to 5 minute rainfall
-intensities, while other events may be of such poor quality (because of
-poor reproduction of charts or blurred traces of ink) that only 1-hour
-increments can be obtained.
-
-### 2.1.4 Spatial Rainfall Variations
-
-Even for small catchments, runoff and consequent model predictions (and
-prototype measurements) may be very sensitive to spatial variations of
-the rainfall. For instance, thunderstorms (convective rainfall) may be
-highly localized, and nearby gages may have very dissimilar readings.
-For modeling accuracy (or even more specifically, for a successful
-calibration of SWMM), it is essential that rain gages be located within
-and adjacent to the catchment.
-
-SWMM accounts for the spatial variability of rainfall by allowing the
-user to define any number of Rain Gage objects along with their
-individual data sources, and assign any rain gage to a particular SWMM
-Subcatchment object (i.e., land parcel) from which runoff is computed.
-If multiple gages are available, this is a much better procedure than is
-the use of spatially averaged (e.g., Thiessen weighted) data, because
-averaged data tend to have short-term time variations removed (i.e.,
-rainfall pulses are "lowered" and "spread out"). In general, if the
-rainfall is uniform spatially, as might be expected from cyclonic (e.g.,
-frontal) systems, these spatial considerations are not as important. In
-making this judgment, the storm size and speed in relation to the total
-study area size must be considered.
-
-Storm movement can significantly affect hydrographs computed at the
-catchment outlet (Yen and Chow, 1968; Surkan, 1974; James and Drake,
-1980; James and Shtifter, 1981).When more than one gage is available to
-apply to the simulation, it is possible to simulate moving storms, as
-rainfall in one part of the basin may be different from rainfall in
-another part of the basin. Movement of a storm in the downstream
-direction increases the hydrograph peak, while movement upstream tends
-to level out the hydrograph (Surkan, 1974; James and Drake, 1980; James
-and Shtifter, 1981).
-
-For detailed simulation of large cities, radar rainfall data are very
-useful. Commercial firms specializing in provision of radar rainfall
-values may be able to place highly spatially and temporally variable
-rainfall data into a time series format easily input to SWMM (e.g.,
-Hoblit and Curtis, 2002; Meeneghan et al., 2002, 2003; Vallabhaneni,
-2002). Radar data are spatially averaged over uniform grid cells of 1
-km2 or larger and therefore each cell would cover a number of runoff
-subcatchments. In this case one could simply use a separate Rain Gage
-object for each grid cell that overlaps the study area, and assign the
-nearest cell as the subcatchment's source of rainfall data. A more
-sophisticated approach is to define a separate Rain Gage for each
-subcatchment along with a weighting matrix ***W*** whose entries
-***wij*** represent the fraction of area from subcatchment *i* that is
-contained in grid cell *j*. Then at any time *t* the vector of
-subcatchment rainfalls ***It*** would equal the vector of cell
-rainfall values ***Rt*** multiplied by the weighting matrix ***W***.
-These data for each time period could be placed in a standard SWMM
-user-prepared rainfall file for direct use by SWMM (see below).
-
-## 2.2 Precipitation Data Sources
-
-### 2.2.1 User-Supplied Data
-
-Many SWMM analyses will rely upon rainfall data supplied by the user, on
-the basis of measurements made at the closest rain gages to the
-catchment, or on an assumed design storm, either "real" (that is,
-derived from actual measurements) or "synthetic" (derived from an
-assumed duration and temporal distribution). Construction of synthetic
-design storms is described in many texts and manuals, e.g., Chow et al.
-(1988), King County Department of Public Works (1995), Bedient et al.
-(2013); SWMM does not supply synthetic design storms automatically,
-since the emphasis is more properly on use of measured data. Measured
-data may be from National Weather Service (NWS) or Environment Canada
-sites, as described below, from local agencies (e.g., utilities), from
-special monitoring programs (e.g., by the USGS or at a university), or
-from several other sources, even from home weather stations. Naturally,
-the quality of any data source should be investigated.
-
-User-supplied rainfall data are provided to SWMM using a Rain Gage
-object. The user specifies the format in which the rainfall data were
-recorded (as intensity, volume, or cumulative volume), the time interval
-associated with each rainfall reading (e.g., 15 minutes, 1 hour, etc.),
-the source of the data (the name of a Time Series object or name of a
-Rainfall file), and the ID name of the recording station or data source
-if a file is being used.
-
-For rainfall time series, only periods with non-zero precipitation need
-be included in the series. Using a Time Series object for user-supplied
-rainfall data makes sense for single-event or short duration simulation
-periods where there are a limited number of Rain Gage objects. In fact
-it is possible to create several different time series for a given rain
-gage in a SWMM project, where each contains a different rainfall event
-to be analyzed. Then all one needs to do is select the appropriate time
-series for the scenario of interest.
-
-If a Rainfall file is used for user-supplied rainfall data then it must
-follow SWMM's standard user-prepared format. Each line of the file
-contains the station ID, year, month, day, hour, minute, and non-zero
-precipitation reading, each separated by one or more spaces. There is no
-need to include time periods with zero readings. An excerpt from a
-sample user-prepared Rainfall data file might look as follows (i.e.,
-Station STA01 recorded 0.12 inches of rainfall between midnight and one
-am on June 12, 2004):
-
-Using a Rainfall file to provide precipitation data is more convenient
-when a long-term continuous simulation is being made or when there are
-many rain gages in a project. Note that it is possible for a single
-user-prepared Rainfall file to contain data from more than one recording
-station or external data source as would be the case in the radar data
-example discussed previously.
-
-SWMM's rainfall Time Series and user-prepared Rainfall files treat the
-data as "start-of-interval" values, meaning that each rainfall intensity
-or depth is assumed to occur at the start of its associated date/time
-value and last for a period of time equal to the gage's recording
-interval. Most rainfall recording devices report their readings as
-"end-of-interval" values, meaning that the time stamp associated with a
-rainfall value is for the end of the recording interval. If such data
-are being used to populate a SWMM rainfall time series or user-prepared
-rainfall file then their date/time values should be shifted back one
-recording interval to make them represent "start-of-interval" values
-(e.g., for hourly rainfall, a reading with a time stamp of 10:00 am
-should be entered into the time series or file as a 9:00 am value).
-
-### 2.2.2 Data from Government Agencies
-
-SWMM can also use rainfall data from files provided directly from US and
-Canadian government agencies. The National Weather Service (NWS) makes
-available historical hourly precipitation values (including water
-equivalent of snowfall depths) for about 5,500 observational stations
-around the U.S., with the periods of record usually beginning in the
-late 1940s. Fifteen-minute data are available for over 2,400 stations,
-with records typically beginning in the early 1970s. The repository for
-U.S. weather data is the National Oceanic and Atmospheric Administration
-(NOAA) National Climatic Data Center (NCDC), located in Asheville, North
-Carolina. Key access information is provided below:
-
-> National Climatic Data Center
->
-> Climate Services Branch
->
-> 151 Patton Avenue
->
-> Asheville, NC 28801
->
-> Telephone: 828-271-4800
->
-> Web: 
-
-The NCDC digital data bases that house the precipitation data are
-designated as DSI-3240 for hourly precipitation and DSI-3260 for
-15-minute precipitation. NOAA's Climate Data Online (CDO) service at
- provides free access to these
-archives in addition to station history information. It features an
-interactive map application that helps locate a recording station
-closest to a site of interest and allows one to request precipitation
-data for a stipulated period of record. After a data request has been
-made through CDO the user receives an email with a link to a web page
-where the data can be viewed with a web browser. The page can then be
-saved to file for future use with SWMM.
-
-When requesting data from CDO be sure to specify the TEXT format option
-and not the CSV option so that SWMM can automatically recognize the file
-format and parse its contents. In addition, select the QPCP
-precipitation option, not the QGAG option, for 15-minute precipitation
-and make sure that the data flags are included.
-
-Table 2.1 shows 15-minute precipitation data downloaded for station
-410427 from Austin, Texas. The column headings represent:
-
-| Field | Description |
-| :--- | :--- |
-| Station: | cooperative recording station identifier. |
-| Date: | date and time at end of fifteen minute recording period. |
-| QPCP: | precipitation amount in hundredths of an inch (where 9999 or 99999 indicates a missing value). |
-| Measurement Flag: | if present, a flag that denotes either the start or end of an accumulation period, a deleted period or a missing period. |
-| Quality Flag: | if present, a flag that indicates if the data value is erroneous. |
-| Units: | a flag indicating the precision of the recorded value where HI is for hundredths and HT for tenths of an inch. |
-
-Hourly precipitation has a similar format except that the label 'HPCP'
-(for hourly precipitation) replaces 'QPCP' and there is no Units column
-since the data precision is always HT. These data sets only include
-periods with non-zero precipitation, use time stamps that mark the end
-of the recording interval, and use a time of '00:00' to refer to
-midnight of the previous day. SWMM recognizes these conventions, as well
-as missing value codes, when it reads a precipitation data file.
-
-[]{#_Toc430249125 .anchor}**Table 2‑1 15-minute precipitation data from
-NCDC Climate Data Online**
-
-The NOAA-NCDC web site also allows one to access the complete set of
-hourly and 15-minute precipitation data for a particular station through
-an FTP server (see ). For
-each station, there is one file that houses data from 1948 (1971 for
-15-minute data) to 1998 and then separate files for each year afterward.
-Each line in these files contains one day's worth of precipitation data
-using the format shown in Table 2.2. Note that the third and fourth
-lines are "wrapped around" as a continuation of the long second line.
-These are the same Austin, Texas data listed in Table 2.1 with the
-addition of an hour '2500' entry on each line that contains the daily
-total. Also these files use hour '2400' to represent midnight unlike
-hour '00:00' used in the Climate Data Online format.
-
-[]{#_Toc430249126 .anchor}**Table 2‑2 15-minute precipitation data in
-NCDC FTP file format**
-
-Earlier online data formats used by NCDC can also be recognized by SWMM.
-Examples of these formats, for the 15-minute Austin, Texas data, are
-shown in Tables 2.3 through 2.5. The formats for hourly data are
-identical, except that HPCP replaces QPCP and time stamps are always for
-hours only.
-
-Long precipitation records are subject to meter malfunctions and missing
-data (for any reason). The NWS has special codes for its DSI-3240 and
-DSI-3260 formats denoting these conditions. They are explained in the
-NCDC documentation for each type. SWMM will note the number of recording
-periods with missing data, often denoted with a 9999 in the rainfall
-column. Rainfall time series used by the subcatchment object contain
-only good, non-zero precipitation data.
-
-+-------------------------------------------------------------------------+
-| **COOPID,CD,ELEM,UN,YEAR,MO,DA,TIME, VALUE,F,F**                        |
-|                                                                         |
-| **-----,--,----,--,----,--,--,----,-----,-,-** |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,29,0745, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,29,2500, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1615, 00070, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1630, 00020, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1645, 00030, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1700, 00050, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1715, 00030, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1730, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1800, 00020, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1815, 00020, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1845, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,1930, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,30,2500, 00270, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,31,0830, 00010, ,**                         |
-|                                                                         |
-| **410427,07,QPCP,HT,1997,07,31,2500, 00010, ,**                         |
-+=========================================================================+
-
-: []{#_Toc430249127 .anchor}**Table 2‑3 15-minute precipitation data in
-comma-delimited format**
-
-**\**
-
-+-----------------------------------------------------------------------+
-| **COOPID CD ELEM UN YEAR MO DA TIME VALUE F F**                       |
-|                                                                       |
-| **------ -- ---- -- ---- -- -- ---- ----- - -**                     |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 29 0745 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 29 2500 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1615 00070**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1630 00020**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1645 00030**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1700 00050**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1715 00030**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1730 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1800 00020**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1815 00020**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1845 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 1930 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 30 2500 00270**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 31 0830 00010**                           |
-|                                                                       |
-| **410427 07 QPCP HT 1997 07 31 2500 00010**                           |
-+=======================================================================+
-
-: []{#_Toc430249128 .anchor}**Table 2‑4 15-minute precipitation data in
-space-delimited format**
-
-+-----------------------------------------------------------------------+
-| **15M41042707QPCPHT19970700290020745 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700290022500 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111615 00070**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111630 00020**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111645 00030**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111700 00050**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111715 00030**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111730 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111800 00020**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111815 00020**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111845 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300111930 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700300112500 00270**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700310020830 00010**                          |
-|                                                                       |
-| **15M41042707QPCPHT19970700310022500 00010**                          |
-+=======================================================================+
-
-: []{#_Toc430249129 .anchor}**Table 2‑5 15-minute precipitation data in
-fixed-length format**
-
-SWMM can also automatically recognize and read Canadian precipitation
-data that are stored in climatologic files available from Environment
-Canada: (). SWMM accepts hourly data
-from HLY03 and HLY21 files and 15-minute data from FIF21 files:
-
-().
-Tables 2-6 and 2-7 show the layout of the data records in these files,
-respectively. The "*ELEM*" field would contain the code 123 for
-rainfall, the "*S*" field is for a numerical sign, the "*VALUE*" field
-has units of 0.1 mm, and the "*F*" and "*FLG*" fields are for data
-quality flags. SWMM makes the proper adjustment from "end-of-interval"
-to "start-of-interval" when processing the Canadian precipitation files.
-As of this writing, these files are only available through custom
-requests made to Environment Canada for a fee.
-
-[]{#_Toc430249130 .anchor}**Table 2‑6 Record layout of Canadian HYL0 and
-HLY21 hourly precipitation files**
-
-[]{#_Toc430249131 .anchor}**Table 2‑7 Record layout of Canadian FIF21
-15-minute precipitation files**
-
-When a SWMM rain gage object utilizes any of the standard NCDC or
-Canadian formatted files, the only information required from the user is
-the name of file that contains the data and a station ID. The latter
-need not be the same as the station ID referenced in the file. Other
-user-editable rain gage properties, such as data format, interval, and
-units are overridden by the values associated with the particular data
-file. SWMM will also convert the depth units used in the file to the
-user's choice of unit system. For example, if an NCDC fifteen-minute
-rainfall file is used in a SWMM project that employs SI metric units
-then SWMM knows that the file's data must first be converted from tenths
-of an inch per fifteen minute period to mm/hr before they are used for
-any runoff calculations.
-
-### 2.2.3 Rainfall Interface File
-
-When precipitation data are supplied to SWMM from one or more external
-data files, the program first collates the data from these files into a
-single binary formatted Rainfall Interface file. It is this file that is
-accessed during the time steps of a SWMM simulation rather than the
-original rainfall data files. The Rainfall Interface file can be saved
-to disk and re-used in subsequent runs should the user care to do so.
-The layout of the interface file is as follows:
-
-The date/time value used here represents the number of decimal days from
-midnight of December 31, 1899 (i.e., the start of year 1900) expressed
-as a double precision floating point number. This is the same
-representation that SWMM uses internally for all date/time values.
-
-## 2.3 Temperature Data
-
-SWMM requires representative air temperature data when simulating snow
-melt or when using the Hargreaves method to compute potential
-evapotranspiration. A single set of time-dependent temperatures is
-applied throughout the study area. These data can come either from a
-user-generated time series or from a climate file. If a time series is
-used, then linear interpolation is used to obtain temperature values for
-times that fall in between those recorded in the time series. The first
-recorded temperature in the series is used for dates prior to the
-beginning date of the series while the last recorded temperature is used
-for dates beyond the end of the series. Temperatures should be in
-degrees F for SWMM projects built in US units or in degrees C for
-projects built in metric units.
-
-A SWMM climate file contains values for minimum and maximum daily
-temperatures, (and optionally, evaporation and wind speed). Three
-climate file formats are supported:
-
-- the current NCDC GHCN-Daily Climate Data Online format
-
-- the older NCDC DS3200 (aka TD-3200) format,
-
-- Environment Canada's DLY daily climatologic file format, and
-
-- a standard user-prepared format.
-
-The National Climatic Data Center's Global Historical Climatology
-Network - Daily (GHCN-Daily) dataset integrates daily climate
-observations from approximately 30 different data sources for about
-30,000 stations across the globe. As with precipitation data, NOAA's
-Climate Data Online (CDO) service ()
-provides free access to these archives. When making an online request
-for data to be used with SWMM users should do the following:
-
-- select the "Daily Summaries" dataset
-
-- select a range of dates to retrieve data from
-
-- use the interactive search feature to identify the recording station
-  of interest
-
-- select the "Custom GHCN-Daily Text" output format
-
-- do not select any of the Station Detail and Data Flag options
-
-- select the maximum (TMAX) and minimum (TMIN) air temperature data
-  types
-
-- select the average daily wind speed (AWND) and pan evaporation rate
-  (EVAP) data types if available and if so desired.
-
-Some stations will offer 24-hour wind movement (WDMV) instead of average
-daily wind speed which can be also be selected.
-
-Table 2-8 shows the format of the data retrieved for Austin, Texas using
-the steps listed above. Note that the pan evaporation has units of
-tenths of millimeters, temperatures are in tenths of a degree Celsius,
-and 24-hour wind movement is in kilometers. (Had average daily wind
-speed (AWND) been available it would have units of tenths of meters per
-second). Data fields with all 9's in them indicate missing values. SWMM
-automatically makes the necessary unit conversions when reading this
-type of climate file.
-
-The DS3200 (aka TD-3200) dataset was a predecessor to the GHCN that was
-discontinued in 2011. SWMM is able to read data files in this older
-format, an example of which is shown in Table 2-9 for June 1997 for
-Austin, Texas. Each line of the file begins with "DLY" and contains
-daily data for an entire month for a specific variable; hence the lines
-in the table are displayed in wrap around fashion. Table 2-10 describes
-the format of the ID portion of each record while Table 2-11 does the
-same for the data portion of the record.
-
-[]{#_Toc430249132 .anchor}**Table 2‑8 Contents of an NCDC GHCN-Daily
-climate file**
-
-[]{#_Toc430249133 .anchor}**Table 2‑9 Contents of an NCDC DS3200 climate
-file**
-
-+-----------------------------------------------------------+-----------+
-| **Field**                                                 | **Width** |
-+===========================================================+===========+
-| Record Type (always = DLY)                                | 3         |
-+-----------------------------------------------------------+-----------+
-| Station ID                                                | 8         |
-+-----------------------------------------------------------+-----------+
-| Element Type. Possible types used by SWMM are:            | 4         |
-|                                                           |           |
-| TMAX = daily maximum temperature, deg. F                  |           |
-|                                                           |           |
-| TMIN = daily minimum temperature, deg. F                  |           |
-|                                                           |           |
-| EVAP = daily evaporation, in or 1/100 in                  |           |
-|                                                           |           |
-| WDMV = daily wind movement, miles                         |           |
-+-----------------------------------------------------------+-----------+
-| Element Measurement Units Code                            | 2         |
-+-----------------------------------------------------------+-----------+
-| Year                                                      | 4         |
-+-----------------------------------------------------------+-----------+
-| Month                                                     | 2         |
-+-----------------------------------------------------------+-----------+
-| Filler (= 9999)                                           | 4         |
-+-----------------------------------------------------------+-----------+
-| Number of data portions that follow                       | 3         |
-+-----------------------------------------------------------+-----------+
-
-: []{#_Toc430249134 .anchor}**Table 2‑10 Layout of the ID portion of an
-NCDC DS3200 climate file record**
-
-[]{#_Toc430249135 .anchor}**Table 2‑11 Layout of the data portion of an
-NCDC DS3200 climate file record**
-
-| **Field** | **Width** |
-| --- | --- |
-| Day of Month | 2 |
-| Hour of Observation | 2 |
-| Sign of Measured Value | 1 |
-| Measured Value | 5 |
-| Quality Control Flag 1 | 1 |
-| Quality Control Flag 2 | 1 |
-
-(Repeated as many times as needed to contain one month of data).
-
-The record layout of the Canadian DLY daily climatologic files is
-depicted in Table 2-12. The "*ELEM*" field contains 001 for daily
-maximum temperature and 002 for daily minimum temperature, the "*S*"
-field is for a numerical sign, the "*VALUE*" field has units of 0.1 deg
-C, and the "*F*" field is for a data quality flag. Note that only a
-single temperature file is used containing records for both daily
-maximum and daily minimum temperatures. More information on how to
-obtain these files from Environment Canada can be found at
-.
-
-[]{#_Toc430249136 .anchor}**Table 2‑12 Record layout of Canadian DLY
-daily climatologic files**
-
-A user-prepared climate file is a plain text file where each line
-contains the following items, each separated by one or more spaces:
-
-- recording station name (no spaces allowed)
-
-- 4-digit year,
-
-- 2-digit month (Jan =1, Feb = 2, etc),
-
-- day of the month,
-
-- maximum temperature (deg F or C ),
-
-- minimum temperature (deg F or C),
-
-- evaporation rate (optional, in/day or mm/day),
-
-- wind speed (optional, miles/hr or km/hr).
-
-The units used for the various data items must be compatible with the
-unit system being used in the SWMM project. For temperatures, this means
-degrees F for US units or degrees C for metric units. If no data are
-available for a given item on a particular date, then an asterisk should
-be entered as its value. Table 2-13 is an example of how the contents of
-the GHCN-Daily file of Table 2-1 would look in user-prepared format
-under US units.
-
-+-----------------------------------------------------------------------+
-| **410427 1997 07 06 95.0 73.0 0.051 0.7**                             |
-|                                                                       |
-| **410427 1997 07 07 96.1 73.9 0.059 0.8**                             |
-|                                                                       |
-| **410427 1997 07 08 93.9 75.0 0.039 1.0**                             |
-|                                                                       |
-| **410427 1997 07 09 96.1 71.1 0.071 2.5**                             |
-|                                                                       |
-| **410427 1997 07 10 97.0 72.0 0.240 1.9**                             |
-|                                                                       |
-| **410427 1997 07 11 96.1 72.0 0.118 1.0**                             |
-|                                                                       |
-| **410427 1997 07 12 96.1 72.0 0.161 0.8**                             |
-+=======================================================================+
-
-: []{#_Toc430249137 .anchor}**Table 2‑13 Example user-prepared climate
-file**
-
-Whenever a climate file is used in SWMM the user can specify a date,
-different from the simulation starting date, where the program begins
-reading from. From this date on the daily values are read from the file
-sequentially, without regard for what date the simulation clock is
-actually at. This feature is useful if one wants to use a rainfall file
-that covers one span of years and a climate file that covers another. An
-error message is issued and the program terminates if this starting date
-does not fall within the dates contained in the file. The same holds
-true if no file start date was supplied and the simulation start date
-does not fall within the dates contained in the climate file. When the
-simulation reaches a date that falls outside the last date in the file,
-then he program will keep using the temperature values that were last
-read from the file. The same convention applies whenever there is a gap
-of missing days or missing data in the file.
-
-## 2.4 Continuous Temperature Records
-
-When temperature data come from a climate file, a mechanism is needed to
-convert the daily max-min readings into instantaneous values at any
-point in time during the day. To do this, the minimum temper­ature is
-assumed to occur at sunrise each day, and the maximum is assumed to
-occur three hours prior to sunset. This scheme obviously cannot account
-for many meteorological phenomena that would create other
-temperature-time distributions but is apparently an appropriate one
-under the circumstances. Given the max-min temperatures and their
-assumed hours of occurrence, temperatures at any other time between
-these are found by sinusoidal interpolation, as sketched in Figure 2-2.
-The interpolation is performed, using three different periods: 1)
-between the maximum of the previous day and the minimum of the present,
-2) between the minimum and maximum of the present, and 3) between the
-maximum of the present and minimum of the following day.
-
-

-ii_01
-
Figure 2‑1 Sinusoidal interpolation of
-hourly temperatures.

-

-
-The time of day of sunrise and sunset are easily obtained as a function
-of latitude and longitude of the catchment and the date. Techniques for
-these computations are explained, for example, by List (1966) and by the
-TVA (1972). Approximate (but sufficiently accurate) formulas used in
-SWMM are given in the latter reference. (Snowmelt computations that
-utilize temperatures are generally insensitive to these effects in
-SWMM.) Their use is explained briefly below.
-
-The hour angle of the sun, *h*, is the angular distance between the
-instan­taneous meridian of the sun (i.e., the meridian through which
-passes a line from the center of the earth to the sun) and the meridian
-of the observer (i.e., the meridian of the catchment). It may be
-measured in degrees or radians or readily converted to hours, since 24
-hours is equivalent to 360 degrees or 2 π radians. The hour angle is a
-function of latitude, declination of the earth, and time of day and is
-zero at noon, true solar time, and positive in the afternoon. However,
-at sunrise and sunset, the solar altitude of the sun (vertical angle of
-the sun measured from the earth's surface) is zero, and the hour angle
-is computed only as a function of latitude and declination,
-
-+-----------------------------------+-----------------------------------+
-| > *cos h = ­ tan δ · tan φ*        | (2-1)                             |
-+===================================+===================================+
-
-where
-
-| Symbol | Description |
-| :--- | :--- |
-| *h* | hour angle at sunrise or sunset, radians, |
-| *δ* | earth's declination, a function of season (date), radians, and |
-| *φ* | latitude of observer, radians. |
-
-The earth's declination is provided in tables (e.g., List, 1966), but
-for programming purposes an approximate formula is used (TVA, 1972):
-
-+--------------------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$\delta = \left( \frac{23.45\ \pi}{180} \right)\cos\left\lbrack \frac{2\pi}{365}(172 - D) \right\rbrack$$ | (2-2)                             |
-+==============================================================================================================+===================================+
-
-where *D* is number of the day of the year (no leap year correction is
-war­ranted) and *δ* is in radians. Having the latitude as an input
-parameter, the hour angle is thus computed in [hours]{.underline},
-positive for sunset, negative for sun­rise, as
-
-+-------------------------------------------------------------------------+-----------------------------------+
-| > $h = (\frac{12}{\pi)\cos^{- 1}( - \tan\delta\  \bullet \tan\varphi}$) | (2-3)                             |
-+=========================================================================+===================================+
-
-The computation is valid for any latitude between the Arctic and
-Antarctic Circles, and no correction is made for obstruction of the
-horizon.
-
-The hour of sunrise and sunset is symmetric about noon, true solar time.
-True solar noon occurs when the sun is at its highest elevation for the
-day. It differs from standard zone time, i.e., the time on clocks)
-because of a longitude effect and because of the "equation of time". The
-latter is of astronomical origin and causes a correction that varies
-seasonally between approximately ± 15 minutes; it is neglected here. The
-longitude correction accounts for the time difference due to the
-separation of the meridian of the observer and the meridian of the
-standard time zone. These are listed in Table 2-14. Note that time zone
-boundaries are very irregular and often are quite displaced from what
-might be expected on the basis of the local longitude, e.g., most of
-Alaska is much further west than the standard meridian for Alaska time
-of 135oW. The longitude correction is readily computed as
-
-$$\mathrm{\Delta}T_{LONG} = 4\frac{minutes}{degree}(\theta - SM) \qquad \text{(2-4)}$$
-
-where ∆TLONG = longitude correction, minutes (of time), *θ* =
-longitude of the observer, degrees, and SM = standard meridian of the
-time zone, degrees, from Table 2-14.
-
-Note that *∆TLONG* can be either positive or negative, and the sign
-should be retained. For instance, Boston at approximately 71°W has
-*∆TLONG* = -16 min­utes, meaning that mean solar noon precedes EST noon
-by 16 minutes. (Mean solar time differs from true solar time by the
-neglected "equation of time.")
-
-The time of day of sunrise is then
-
-+--------------------------------------------------+-----------------------------------+
-| > $H_{SR} = 12 - h + \mathrm{\Delta}T_{LONG}/60$ | (2-5)                             |
-+==================================================+===================================+
-
-and the time of day of sunset is
-
-+----------------------------------------------------+-----------------------------------+
-| > $$H_{SS} = 12 + h + \mathrm{\Delta}T_{LONG}/60$$ | (2-6)                             |
-+====================================================+===================================+
-
-From these times, the hours at which the minimum (*Tmin*) and maximum
-(*Tmax*) temperatures
-
-occur are *Hmin = HSR* and *Hmax = HSS -- 3*, respectively.
-
-+-------------------------+-------------------------+-------------------------+
-| **Time Zone**           | **Example Cities**      | **Standard Meridian**   |
-+:========================+:========================+:========================+
-| Newfoundland Std. Time  | St. Johns's,            | 52.5a                 |
-|                         | Newfoundland            |                         |
-+-------------------------+-------------------------+-------------------------+
-| Atlantic Std. Time      | Halifax, Nova Scotia    | 60                      |
-|                         |                         |                         |
-|                         | San Juan, Puerto Rico   |                         |
-+-------------------------+-------------------------+-------------------------+
-| Eastern Std. Time       | New York, New York      | 75                      |
-|                         |                         |                         |
-|                         | Toronto, Ontario        |                         |
-+-------------------------+-------------------------+-------------------------+
-| Central Std. Time       | Chicago, Illinois       | 90                      |
-|                         |                         |                         |
-|                         | Winnipeg, Manitoba      |                         |
-|                         |                         |                         |
-|                         | Saskatoon,              |                         |
-|                         | Saskatchewanb         |                         |
-+-------------------------+-------------------------+-------------------------+
-| Mountain Std. Time      | Denver, Colorado        | 105                     |
-|                         |                         |                         |
-|                         | Edmonton, Alberta       |                         |
-+-------------------------+-------------------------+-------------------------+
-| Pacific Std. Time       | San Francisco,          | 120                     |
-|                         | California              |                         |
-|                         |                         |                         |
-|                         | Vancouver, British      |                         |
-|                         | Columbia                |                         |
-|                         |                         |                         |
-|                         | Whitehorse, Yukon       |                         |
-+-------------------------+-------------------------+-------------------------+
-| Alaska Std. Time        | Anchorage, Alaska       | 135                     |
-+-------------------------+-------------------------+-------------------------+
-| Aleutian Std. Time      | Atka, Alaska            | 150                     |
-|                         |                         |                         |
-| Hawaiian Std. Time      | Honolulu, Hawaii        |                         |
-+-------------------------+-------------------------+-------------------------+
-| aThe time zone of the island of Newfoundland is offset one half hour from |
-| other zones.                                                                |
-|                                                                             |
-| bSaskatchewan summer time is Mountain, winter is Central.                 |
-+-----------------------------------------------------------------------------+
-
-: []{#_Toc430249138 .anchor}**Table 2‑14 Time zones and standard
-meridians (degrees west longitude)**
-
-The temperature *T* at any hour *H* of the day can now be computed as
-follows:
-
-1.  If *H \< Hmin* then
-
-+----------------------------------------------------------------------------------------------------------------------------------------+--------------+
-| > $$T = T_{\min} + \frac{\mathrm{\Delta}T_{1}}{2}\ sin\left( \frac{\pi\left( H_{\min} - H \right)}{H_{\min} + 24 - H_{\max}} \right)$$ | (2-7)        |
-+========================================================================================================================================+==============+
-
-> where *∆T1* is the difference between the previous day's maximum
-> temperature and the current day's minimum temperature.
-
-2.  If *Hmin ≤ H ≤ Hmax* then
-
-+-----------------------------------------------------------------------------------------------------------------------------+--------------+
-| > $$T = T_{avg} + \frac{\mathrm{\Delta}T}{2}\ sin\left( \frac{\pi\left( H_{avg} - H \right)}{H_{\min} - H_{\max}} \right)$$ | (2-8)        |
-+=============================================================================================================================+==============+
-
-> where *Tavg* is the average of *Tmin* and *Tmax*, *∆T* is the
-> difference between *Tmax* and *Tmin*, and *Havg* is the average
-> of *Hmin* and *Hmax*.
-
-3.  If *H \> Hmax* then
-
-+-----------------------------------------------------------------------------------------------------------------------------------+--------------+
-| > $$T = T_{\max} - \frac{\mathrm{\Delta}T}{2}\ sin\left( \frac{\pi\left( H - H_{max} \right)}{H_{\min} + 24 - H_{\max}} \right)$$ | (2-9)        |
-+===================================================================================================================================+==============+
-
-## 
-
-## 2.5 Evaporation Data
-
-Evaporation can occur in SWMM for standing water on subcatchment
-surfaces, for subsurface water in groundwater aquifers, for water
-flowing in open channels, for water held in storage units, and for water
-held in low impact development controls (e.g., green roofs, rain
-gardens, etc.). Single event simulations are usually insensitive to the
-evaporation rate, but evaporation can make up a significant component of
-the water budget during continuous simulation. SWMM allows evaporation
-rates to be stated as:
-
-- a single constant value,
-
-- a set of monthly average values,
-
-- a user-defined time series of daily values,
-
-- daily values read from an external climate file,
-
-- daily values computed from the daily temperatures in an external
-  climate file.
-
-Monthly and seasonal averages for evaporation are available in NOAA
-(1974) and Farnsworth and Thompson (1982). Another source of evaporation
-and evapotranspiration data in the U.S. is the AgriMet program of the
-U.S. Bureau of Reclamation:
-
-().
-
-However, AgriMet is aimed primarily at agricultural use, containing
-information on crop water use requirements, for instance. Generally,
-local evaporation data are difficult to obtain. Fortunately, totals are
-likely to represent large spatial areas more so than for precipitation.
-State climate agencies are often useful when searching for weather data.
-For instance, the Oregon Climate Service ()
-includes daily pan evaporation data among its weather archives, and
-links are provided to other climate agencies regionally and nationwide.
-
-The climate file source of evaporation data is the same climate file
-used to supply daily max-min temperatures that was described in section
-2.3. For NCDC GHCN-Daily files one would request that records for the
-element EVAP be included in the file while for the Canadian DLY files
-one would do the same for daily pan evaporation (element code 151). For
-the user-supplied climate file, one simply adds an evaporation rate
-value after the daily minimum temperature entry in each record. If the
-file were only being used to supply evaporation and not temperatures one
-still has to enter asterisks (\*) in the max and min temperature fields
-so that the file is read correctly.
-
-Note that both the NCDC and Canadian DLY files report pan evaporation
-while SWMM expects actual evaporation. SWMM will accept a set of monthly
-pan coefficients, typically on the order of 0.7, used to convert pan
-evaporation to actual evaporation (Chow et al., 1988; Bedient et al.,
-2013). Also SWMM will automatically convert the units used for
-evaporation in these files into the ft/sec units used internally by
-SWMM. For all other data sources, the evaporation rate values must be in
-the same unit system as the rest of the data in a project. For US
-standard units this is inches/day while for SI metric units it is
-mm/day.
-
-SWMM can also use the Hargreaves method (Hargreaves and Samani, 1985) to
-compute evaporation rates from the daily max-min temperatures contained
-in a climate file and the study area's latitude. The governing equation
-is:
-
-+------------------------------------------------------------------------------------------+-----------------------------------+
-| > $E = 0.0023\left( \frac{R_{a}}{\lambda} \right)T_{r}^{1/2}\left( T_{a} + 17.8 \right)$ | (2-10)                            |
-+==========================================================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *E* | evaporation rate (mm/day) |
-| *Ra* | water equivalent of incoming extraterrestrial radiation (MJm-2d-1) |
-| *Tr* | average daily temperature range for a period of days (deg C) |
-| *Ta* | average daily temperature for a period of days (deg C) |
-| *λ* | latent heat of vaporization (MJkg-1) = *2.50 -- 0.002361Ta* |
-
-As noted in Hargreaves and Merkley (1998), for the equation to provide
-satisfactory results *Tr* and *Ta* must be averaged over a period of
-5 or more days. SWMM therefore uses a 7-day running average of these
-variables derived from the record of daily max-min temperatures. The
-extraterrestrial radiation Ra is computed as:
-
-+--------------------------------------------------------------------------------------------------------------+-----------+
-| > $R_{a} = 37.6d_{r}\left( w_{s}sin(\varphi)\ sin(\delta) + cos(\varphi)\ cos(\delta)\ sin{(w}_{s} \right))$ | (2-11)    |
-+==============================================================================================================+===========+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *dr* | relative earth-sun distance = $1 + 0.033cos\left( \frac{2\pi J}{365} \right)$ |
-| *J* | Julian day (1 to 365) |
-| *ws* | sunset hour angle (radians) = $\cos^{- 1}\left( - \tan{\varphi\tan{\ \delta}} \right)$ |
-| *φ* | latitude (radians) |
-| *δ* | solar declination (radians) = $0.4093sin\left( \frac{2\pi(284 + J)}{365} \right)$ |
-
-## 2.6 Wind Speed Data
-
-SWMM uses wind speed to refine the calculation of a melting rate for
-accumulated snow during times when there is precipitation in the form of
-rainfall (see Section 6.3.2). There are two options for providing wind
-speed data to SWMM:
-
-- as an average value for each month of the year (January -- December)
-
-- from the same climate file used to supply daily max-min temperature
-  and evaporation.
-
-For the first option the same monthly average applies no matter which
-year is being simulated. The wind speed units are miles/hour for US
-units or km/hour for metric units. The default monthly values are all 0.
-The NCDC has compiled average monthly wind speeds for various locations
-throughout the US which can be found at:
-
-[http://www.ncdc.noaa.gov/sites/default/files/attachments/wind1996.pdf](%20http:/www.ncdc.noaa.gov/sites/default/files/attachments/wind1996.pdf).
-
-For the NCDC GHCN-Daily climate file, one can request that records for
-the average daily wind speed data element AWND or the 24-hour wind
-movement data element WDMV, whichever is available, be included in the
-file. For the user-supplied file, wind speed is added after the field
-for evaporation in each daily record (remember to place a \* in the
-evaporation field if evaporation data is being supplied from some other
-source). SWMM automatically converts the units used for wind speed by
-the NCDC file, but for the user-supplied file they must be in miles/hour
-for US unit system data sets or in km/hour for metric data sets. The
-Canadian DLY file does not report daily wind speed.
-
-#  -- Surface Runoff
-
-## 3.1 Introduction
-
-This chapter describes how SWMM converts precipitation excess (rainfall
-and/or snowmelt less infiltration, evaporation, and initial abstraction)
-into surface runoff (overland flow). Because SWMM is a distributed model
-it allows a study area to be subdivided into any number of irregularly
-shaped subcatchment areas to best capture the effect that spatial
-variability in topography, drainage pathways, land cover, and soil
-characteristics have on runoff generation. Generation of runoff is
-therefore computed on a subcatchment by subcatchment basis.
-
-SWMM uses a nonlinear reservoir model to estimate surface runoff
-produced by rainfall over a subcatchment. The model was first published
-by Chen and Shubinski (1971) and included in the original release of
-SWMM (Metcalf and Eddy et al., 1971a). Discussions of ancillary
-processes that serve as components of the runoff model, such as
-infiltration and snowmelt, are covered elsewhere in this manual.
-
-## 3.2 Governing Equations
-
-SWMM conceptualizes a subcatchment as a rectangular surface that has a
-uniform slope *S* and a width *W* that drains to a single outlet channel
-as shown in Figure 3-1. Overland flow is generated by modeling the
-subcatchment as a nonlinear reservoir, as sketched in Figure 3-2.
-
-![[]{#_Toc426447668 .anchor}**Figure 3‑1 Idealized representation of a
-subcatchment.**](VolumeI/media/media/image5.emf){width="3.6402449693788275in"
-height="2.5085629921259844in"}
-
-[]{#_Toc426447669 .anchor}**Figure 3‑2 Nonlinear reservoir model of a
-subcatchment.**
-
-In this representation, the subcatchment experiences inflow from
-precipitation (rainfall and snowmelt) and losses from evaporation and
-infiltration. The net excess ponds atop the subcatchment surface to a
-depth *d*. Ponded water above the depression storage depth *ds* can
-become runoff outflow *q*. Depression storage accounts for initial
-rainfall abstractions such as surface ponding, interception by flat
-roofs and vegetation, and surface wetting.
-
-From conservation of mass, the net change in depth *d* per unit of time
-*t* is simply the difference between inflow and outflow rates over the
-subcatchment:
-
-+-----------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial d}{\partial t} = i - e - f - q$$ | (3-1)                             |
-+=====================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *i* | rate of rainfall + snowmelt (ft/s) |
-| *e* | surface evaporation rate (ft/s) |
-| *f* | infiltration rate (ft/s) |
-| *q* | runoff rate (ft/s). |
-
-Note that the fluxes *i, e, f,* and *q* are expressed as flow rates per
-unit area (cfs/ft2 = ft/s).
-
-Assuming that flow across the subcatchment's surface behaves as if it
-were uniform flow within a rectangular channel of width *W* (ft), height
-*d--ds*, and slope *S*, the Manning equation can be used to express
-the runoff's volumetric flow rate Q (cfs) as:
-
-+-------------------------------------------------+-----------------------------------+
-| > $$Q = \frac{1.49}{n}S^{1/2}R_{X}^{2/3}A_{X}$$ | (3-2)                             |
-+=================================================+===================================+
-
-Here *n* is a surface roughness coefficient, *S* the apparent or average
-slope of the subcatchment (ft/ft), *Ax* the area across the
-subcatchment's width through which the runoff flows (ft2), and *Rx*
-is the hydraulic radius associated with this area (ft). Referring to
-Figures 3-1 and 3-2, *Ax* is a rectangular area with width *W* and
-height *d-ds*. Because *W* will always be much larger than *d* it
-follows that $A_{X} = W(d - d_{S})$ and $R_{X} = d - d_{S}$.
-Substituting these expressions into Equation 3-2 gives:
-
-+----------------------------------------------------------------+-----------------------------------+
-| > $$Q = \frac{1.49}{n}WS^{1/2}\left( d - d_{S} \right)^{5/3}$$ | (3-3)                             |
-+================================================================+===================================+
-
-To obtain a runoff flow rate per unit of surface area, *q*, Equation 3-3
-is divided by the surface area of the subcatchment, *A* (which should
-not be confused with the cross-section area *Ax* through which the
-runoff passes):
-
-+-------------------------------------------------------------------+-----------------------------------+
-| > $$q = \frac{1.49WS^{1/2}}{A\ n}\left( d - d_{S} \right)^{5/3}$$ | (3-4)                             |
-+===================================================================+===================================+
-
-Substituting this equation into the original mass balance relation 3-1
-results in:
-
-+----------------------------------------------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial d}{\partial t} = i - e - f - \alpha\left( d - d_{S} \right)^{5/3}$$ | (3-5)                             |
-+========================================================================================+===================================+
-
-where *α* is defined as:
-
-+------------------------------------------+-----------------------------------+
-| > $$\alpha = \frac{1.49WS^{1/2}}{A\ n}$$ | (3-6)                             |
-+==========================================+===================================+
-
-Equation 3-5 is an ordinary nonlinear differential equation. For known
-values of *i, e, f, ds* and *α* it can be solved numerically over each
-time step for ponded depth *d.* Once *d* is known, values of the runoff
-rate *q* can be found from Equation 3-4. Note that Equation 3-5 only
-applies when *d* is greater than *ds*. When *d \<= ds*, runoff *q*
-is zero and the mass balance on *d* becomes simply:
-
-+-------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial d}{\partial t} = i - e - f$$ | (3-7)                             |
-+=================================================+===================================+
-
-## 3.3 Subcatchment Partitioning
-
-The equation used to generate surface runoff was developed on the basis
-of an idealized rectangular subcatchment area with uniform properties.
-Urban areas usually contain a mix of land surface types which can
-conveniently be divided into two primary categories: pervious surfaces
-(e.g., lawns, fields, and forested areas) which allow rainfall to
-infiltrate into the soil and impervious surfaces (e.g., roofs, roads,
-and parking lots) over which no infiltration occurs. Therefore SWMM
-allows each subcatchment to have both a pervious and impervious subarea
-over which Equation 3-5 is solved. The user-supplied parameter *Percent
-Imperviousness* determines how much of the total subcatchment is devoted
-to each type of surface.
-
-In addition, it is not uncommon for impervious surfaces to begin
-generating runoff almost immediately after a rainfall event occurs, well
-before its depression storage depth fills up. To model this behavior,
-SWMM allows the impervious area of a subcatchment to be further divided
-into two subareas: one with depression storage and one without. The
-input parameter *% Zero-Imperv* determines what fraction of a
-subcatchment's impervious area has no depression storage. Thus overall,
-a subcatchment can contain three types of subareas as shown in Figure
-3-3. Note that under these definitions all impervious area is directly
-connected to the subcatchment's outlet point (typically a drainage pipe
-or channel). How to model indirectly connected areas, such as roof
-drains that discharge to pervious lawn areas, is discussed in section
-3.6 below.
-
-

-
-
Figure 3‑3 Types of subareas within a
-subcatchment.

-

-
-Conceptually, these three sub-areas are incorporated into the idealized
-subcatchment as shown in Figure 3-4. Of course in reality the areas will
-not align in this fashion nor will they necessarily be compact and
-connected. The arrangement used here is merely a modeling convenience.
-Symbols A1, A2, and A3 refer to the pervious subarea and two types of
-impervious subareas (with and without depression storage), respectively,
-and they discharge their runoff independently of one another to the same
-outlet location.
-
-[]{#_Toc426447671 .anchor}**Figure 3‑4 Idealized subcatchment
-partitioning for overland flow.**
-
-With this refinement the governing differential equation 3-5 for
-subcatchment runoff is solved individually for each subarea. Thus a
-separate accounting of the ponded depth *d* over each subarea is
-maintained. At the end of each time step, the runoff flows from each
-subarea are combined together to determine a total runoff flow for the
-entire subcatchment. The following conventions apply when solving the
-runoff equation for each subarea individually:
-
-- The same precipitation and evaporation rate applies to each subarea.
-
-- The contribution from snowmelt will vary by subarea. See Chapter 6 for
-  details.
-
-- The infiltration rate *f* is always zero for the two impervious
-  subareas.
-
-- Different values of depression storage *ds* can be assigned to the
-  pervious (A1) and impervious area (A2), where by definition d*s* is
-  zero for the impervious area with no depression storage (A3).
-
-- Different values of the Manning roughness *n* can be used for the
-  pervious (A1) and impervious areas (A2 and A3).
-
-- The same values of *W* and *S* apply for all subareas.
-
-The applicable *α*-terms to be used in Equation 3-5 for each subarea
-are:
-
-+---------------------------------------------------------------------------+---------------------------------+------------+
-| > $$\alpha_{P} = \frac{1.49WS^{1/2}}{A_{1}n_{P}}$$                        | for the pervious subarea A1     | (3-8)      |
-+===========================================================================+:================================+===========:+
-|                                                                           |                                 |            |
-+---------------------------------------------------------------------------+---------------------------------+------------+
-| > $$\alpha_{P} = \frac{1.49WS^{1/2}}{\left( A_{2} + A_{3} \right)n_{I}}$$ | for both impervious subareas A2 | (3-9)      |
-|                                                                           | and A3                          |            |
-+---------------------------------------------------------------------------+---------------------------------+------------+
-
-where *nP* is the roughness for the pervious area, *nI* is the
-roughness for both impervious areas, and *Ai* is the surface area
-(ft2) associated with sub-area *i.*
-
-The reason that the same *α* applies to both impervious subareas even
-though their areas are different arises from how the *W/A* term is
-evaluated for the idealized arrangement shown in Figure 3-4. For area
-A2, *W2 = A2W / (A2 + A3)* so that *W2 / A2 = W / (A2 +
-A3).* For A3, *W3 = A3W / (A2 + A3)* which results in *W3 /
-A3 = W / (A2 + A3)*. Thus both types of impervious areas use the
-same factor *W / (A2 + A3)*.
-
-## 3.4 Computational Scheme
-
-The detailed computational scheme for computing the runoff generated
-from each subcatchment within a study area over a single time step of a
-simulation is presented in the sidebar below.
-
-## 3.5 Time Step Considerations
-
-SWMM allows the user to specify two different time steps that will be
-used when evaluating surface runoff during a simulation: a "wet" step
-and a "dry" step. The wet time step is used when there is precipitation
-or overland flow on any subcatchment within the study area. The longer
-dry time step applies when there is both no precipitation input and all
-depression storage remains unfilled.
-
-Typically the wet time step will be an integer fraction of the rainfall
-interval. Five-minute rainfall might have wet time steps of 1, 2.5 or
-5.0 min, for example. If the wet time step is not an integer fraction of
-or is larger than the rainfall interval, SWMM will automatically reduce
-the time step so that the rainfall intensity remains constant over the
-adjusted time step. A smaller wet time step would be desirable when the
-subcatchment is small and the time of concentration is a fraction of the
-rainfall interval. When using 1-hour rainfall, wet time steps of 10 min,
-15 min or longer can be used by the model, unless subcatchments are very
-small. The key concept is that the wet step should be less than or equal
-to the response time of a subcatchment. Time of concentration, tc, is
-one measure of response time (Eagleson, 1970; Bedient et al., 2013);
-hence, the wet step should be no greater than tc. For subcatchments of
-a few to several acres, wet steps of 1 to 5 min or longer should
-suffice. But for simulation of very small rain gardens or runoff from
-individual roofs onto lawns, for instance, values less than 1 min might
-be necessary. The latter situation could be encountered when simulating
-low-impact development (LID) options.
-
-The dry time step is typically several hours or even days. It is used to
-update the infiltration parameters, generate groundwater flow, and
-provide hydrograph continuity for inflow to channels and conduits (i.e.,
-for downstream flow objects) when there is no rainfall or standing water
-anywhere on the study area. The dry time step may be hours to a day in
-wet climates and a day or more in very dry climates.
-
-Substantial time savings can be achieved with judicious usage of wet and
-dry time steps for longer simulations. As an example consider the
-execution time saving using a wet step of 15 min and a dry step of 1 day
-versus using a single time step of 1 hr for a year. Using Florida
-rainfall as input (average annual rainfall between 50 and 60 in. \[1250
-to 1500 mm\]) gives 300 wet hours per year, flow for approximately 60
-days per year, and 205 completely dry days per year. Assuming overland
-flow only occurs when it is raining (an underestimate of wet time
-steps), this translates to 300 x 4 = 1200 wet time steps, plus at least
-60 transition (wet) time steps, plus 205 dry time steps for a total of
-1465. A constant hourly time step for one year requires 8760 time steps.
-This is greater than a 500 percent savings in computer time with a
-better representation of the flow hydrograph due to the 15 min wet time
-step.
-
-A separate, usually much smaller time step is used in SWMM for hydraulic
-flow routing. Typically, flow routing through channels and conduits
-requires a much shorter time step than for overland flow, often down to
-a few seconds when using dynamic wave routing. SWMM will linearly
-interpolate surface runoff hydrographs computed at longer time steps to
-obtain the inflows at shorter time steps needed during flow routing.
-
-## 3.6 Overland Flow Re-Routing
-
-Huber (2001) extended SWMM's traditional surface runoff model to allow
-overland flow to be re-routed in three different ways:
-
-1.  a specified fraction of the runoff from a subcatchment's impervious
-    areas A2 and A3 can be routed onto its pervious area A1,
-
-2.  a specified fraction of runoff from the pervious area A1 can be
-    routed onto the impervious area with depression storage A2,
-
-3.  the total runoff from the subcatchment can be routed onto another
-    subcatchment.
-
-The first of these schemes is illustrated in Figure 3-5.
-
-![](VolumeI/media/media/image9.wmf){width="3.8383213035870516in"
-height="3.3943667979002625in"}
-
-[]{#_Toc426447672 .anchor}**Figure 3‑5 Re-routing of overland flow
-(Huber, 2001).**
-
-For a given subcatchment, schemes 1 and 2 are mutually exclusive, while
-scheme 3 can be combined with either 1 or 2 if desired. For internal
-re-routing, the fraction to be routed is a user-specified input
-parameter. When flows are re-routed in this manner, the re-routed flow
-is distributed uniformly over the downstream subarea or subcatchment, in
-the same manner as rainfall. The flow is also delayed at least one time
-step longer than it would have been without this extra routing.
-
-The modified overland flow algorithm permits routing of flow from the
-impervious subarea over the pervious subarea of the subcatchment, or
-vice versa. In the first instance, runoff from a rooftop might flow over
-a lawn. In the second instance, runoff from a lawn might flow over a
-sidewalk. This option is especially useful for simulation of "low impact
-development" (LID) practices (Wright and Heaney, 2001; Wright et al.,
-2000; Lee, 2003).
-
-By routing flow from one subcatchment to another subcatchment, buffer
-strips or riparian zones may be simulated. Inflow to the downstream
-subcatchment is distributed uniformly over the downstream subcatchment
-in the same manner as rainfall. This can be done because of the
-nonlinear reservoir flow routing method in which there is no spatial
-variation through the subcatchment. However, it also means that outflow
-from one subcatchment cannot be directed just to the pervious area of a
-downstream subcatchment that contains both pervious and impervious
-sub-areas.
-
-If such routing were desired, the downstream subcatchment should be
-separated into two: a pervious subcatchment and an impervious
-subcatchment. There is no limit on the length of the overland flow
-"chain" that can be assembled. Outflow from the most downstream
-subcatchment will flow into a pipe or channel inlet (node), or directly
-to an outfall node, as usual.
-
-To accommodate these options the computational scheme described in
-section 3.4 is modified as follows:
-
-1.  For each subcatchment that receives runoff from one or more other
-    subcatchments, the precipitation rate *i* for each of its subareas
-    has *Qr / A* added to it, where *Qr* is the total runoff (cfs)
-    routed onto it from the contributing subcatchments, as computed at
-    the end of the previous time step, and *A* is the total surface area
-    of the receiving subcatchment.
-
-2.  For subcatchments where a fraction *f* of impervious runoff is
-    routed internally to the pervious area, the precipitation rate *i*
-    for the pervious area has
-    $f\left( q_{2}A_{2} + q_{3}A_{3} \right)/A_{1}$ added to it, where
-    *qj* is the runoff per unit area (ft/sec) from subarea *j* at the
-    end of the previous time step and *Aj* is the area of subarea *j*.
-
-3.  For subcatchments where a fraction *f* of the pervious runoff is
-    routed internally to the impervious area with depression storage,
-    the precipitation rate *i* for the latter subarea has
-    $q_{1}A_{1}/A_{2}$ added to it.
-
-After the runoff from each of its subareas is computed, the total runoff
-reported for the subcatchment is the flow that actually exits the
-subcatchment. For example, if 100% of the impervious runoff was directed
-onto the pervious area, then the reported runoff for the subcatchment
-would consist only of the computed runoff from the pervious area.
-
-## 3.7 Subcatchment Discretization
-
-Most study areas will require some level of discretization into multiple
-subcatchments in order to properly characterize the spatial variability
-in overland drainage pathways, surface properties, and connections into
-drainage pipes and channels. Discretization begins with the
-identification of drainage boundaries (drainage divides) using a
-topographic map, the location of major sewer inlets using a sewer system
-map, and the selection of channel/pipes to be simulated "downstream" in
-the model. In an urban area, drainage divides based strictly on
-topography might not apply, since the subsurface drainage network might
-transport water in a direction opposite to the surface gradient. Hence,
-drainage boundaries must be determined with the aid of both a
-topographic map and sewer plans.
-
-For instance, consider the Fisk B Catchment in Portland, Oregon, shown
-in Figure 3-6 (Portland BES, 1996). The discretization relies upon both
-surface contours and invert slopes of the collection sewers. Additional
-detail of Subcatchments 8412 and 9412 (highlighted in Figure 3-6) is
-shown in Figure 3-7. The surface drainage in Subcatchment 9412 is to the
-south, but the pipe connecting junctions 412 and 712 drains north! If
-only the surface contours were considered a quite different catchment
-response to rainfall would result than what actually exists.
-
-

-
-
Figure 3‑6 Fisk B catchment, Portland,
-Oregon (Portland BES, 1996).

-

-
-

-
-
Figure 3‑7 Detailed view of two Fisk B
-subcatchments (Portland BES, 1996).

-

-
-It is possible with SWMM to provide detail down to the parcel
-(individual lot) level, if desired and to simulate virtually every
-drainage pipe or channel (e.g., Huber and Cannon, 2002). The amount of
-detail actually required depends upon the purpose of the simulation. For
-screening purposes with continuous simulation, a coarse discretization
-with a few or just one subcatchment will generally suffice, with one or
-no channel/pipes. On the other hand, if hydraulic conditions are being
-studied within the catchment, enough detail in the drainage system and
-in the subcatchments that feed it must be provided. That is, obviously,
-a pipe must be simulated in order to study it, and every channel or pipe
-must have a source of inflow (subcatchment or channel/pipe) at the
-upstream end. The most upstream end of a series of channel/pipes must
-have a subcatchment draining to it or it will remain dry (and useless)
-during the simulation. If the principal interest is in flow at the
-outlet of the catchment, it is usually acceptable to provide minimal
-detail (e.g., few or one subcatchment and one or no channel/pipes). The
-trade-off, however, is that the coarser the schematization, the more
-decisions must be made on how to aggregate catchment properties.
-
-For both single-event and continuous simulations, the amount of detail
-should be the minimum consistent with requirements for within-catchment
-information. Obviously, no information can be obtained about upstream
-surcharging if the upstream conduits are not simulated and subcatchments
-are not provided to feed them. In addition, sufficient detail needs to
-be provided to allow within-system control options to be tried for
-different areas and land uses. If, however, the primary objective is
-simply to produce a hydrograph and pollutograph at the outlet, using a
-single rain gage, then one subcatchment will often (but not always)
-serve as well as many.
-
-## 3.8 Parameter Estimates
-
-### 3.8.1 Subcatchment Conceptualization
-
-Each subcatchment is schematized as in Figure 3-4, in which three
-sub-areas A1, A2, and A3 are used to represent different pervious and
-impervious surfaces. The slope of the idealized subcatchment is in the
-direction perpendicular to the flow width. The normal option is for
-outflow from each subarea to move directly to an inlet node of a
-drainage pipe or channel and not pass over any other subarea. That is,
-the impervious area is assumed to be *directly connected impervious
-area* (DCIA) or *hydraulically effective impervious area*. Rooftops or
-other surfaces that drain onto adjacent pervious areas are not directly
-connected and, if the user wishes, runoff from such non-DCIA surfaces
-may be directed to the pervious area of the subcatchment and vice versa.
-All sub-areas are assumed to have the same width perpendicular to the
-overland flow path. If desired, any subcatchment may consist entirely of
-any one (or more) types of the three subarea categories.
-
-Actual subcatchments seldom exhibit the uniform rectangular geometries
-shown in Figure 3-4. In terms of runoff generation, all geometrical
-properties are merely parameters (as explained below) and no inherent
-"shape" can be assumed in the nonlinear reservoir technique. Parameter
-selection is aided with reference to Figure 3-2 and Equation 3-5 in
-which the subcatchment "reservoir" is shown in relation to inflows and
-outflows (or losses). Subcatchment outflow is a function of the
-coefficient $\alpha = \frac{1.49WS^{1/2}}{A\ n}$ and the excess in
-ponded depth above depression storage. Note that the relative area *A*,
-width *W*, slope *S*, and roughness *n* are combined into the single
-parameter *α*. Equivalent changes in computed runoff may be caused by
-appropriate alteration of any of these parameters. Note also that the
-width and slope are the same for both the pervious and impervious
-subareas. Manning's roughness and relative area are the only parameters
-available to the modeler to characterize the relative contributions of
-pervious and impervious areas to the outlet hydrograph. (However, see
-further comments below on the subcatchment width.)
-
-The following subsections discuss how values for subcatchment area,
-imperviousness, width, slope, roughness, and depression storage can be
-assigned and the implications they entail.
-
-### 3.8.2 Subcatchment Area
-
-In principle, the catchment and subcatchment area can be defined by
-constructing drainage divides on topographic maps. In practice, this may
-or may not be easy because of the lack of detailed contour information
-and the presence of unknown inflows and outflows. This may be most
-noticeably brought to the modeler\'s attention when the measured runoff
-volume exceeds the measured rainfall volume, if the latter is correct.
-Actual storm rainfall is seldom accurately measured over all
-subcatchments.
-
-From the modeling standpoint, there are no upper or lower bounds on
-subcatchment area. Subcatchments are usually chosen to coincide with
-different land uses, with drainage divides, and to ease parameter
-estimation, i.e., homogeneous slopes, soils, etc.
-
-### 3.8.3 Imperviousness
-
-The percent imperviousness of a subcatchment is another parameter that
-can, in principle, be measured accurately from aerial photos or land use
-maps. In practice, unless impervious layers are included in a GIS
-representation of the basin, such work tends to be tedious, and it is
-common to make careful measurements for only a few representative areas
-and extrapolate to the rest. Runoff volume and flow rates are strongly
-sensitive to estimates of imperviousness; hence, care should be taken in
-imperviousness estimates.
-
-One approach to estimating impervious area across large areas with
-multiple land uses is to associate a percent impervious area with each
-category of land use. Then by knowing the percentage of each land use
-within a subcatchment one can calculate its percentage impervious area.
-Table 3-1 lists estimates of percent impervious area for different land
-uses taken from EPA's Rouge River Project (Kluitenberg 1994) and
-incorporated into EPA technical guidance for MS4 stormwater permitting
-in Region I (US EPA, 2014).
-
-| **Land Use** | **Percent Impervious Area** |
-| --- | --- |
-| Commercial | 56 |
-| Industrial | 76 |
-| High density residential | 51 |
-| Medium density residential | 38 |
-| Low density residential | 19 |
-| Institutional | 34 |
-| Agricultural | 2 |
-| Forest | 1.9 |
-| Open Urban Land | 11 |
-
-  : []{#_Toc430249139 .anchor}**Table 3‑1 Impervious area as a
-  percentage of land use.**
-
-As mentioned earlier, impervious areas in SWMM are hydraulically
-(directly) connected to the drainage system -- called directly connected
-impervious areas (DCIA). For instance, if rooftops drain onto adjacent
-pervious lawn areas, they should not be treated as a hydraulically
-effective impervious area. Such areas are non-effective impervious areas
-(Doyle and Miller, 1980). On the other hand, if a driveway drains to a
-street and then to a stormwater inlet, the driveway would be considered
-hydraulically connected. Rooftops with downspouts connected directly to
-a sewer are clearly hydraulically connected. An example of careful
-measurements and statistics on imperviousness may be found in Field et
-al. (2000), Lee (2003), and Roy and Shuster (2007). Lee and Heaney
-(2003) provide detailed comparisons of imperviousness computations and
-their implications for modeling.
-
-Should rooftops be treated as "pervious," the real surrounding pervious
-area is subject to more incoming water than rainfall alone and thus
-might produce runoff sooner than if rainfall alone were considered. In
-the possible event that this effect is important (a judgment based on
-infiltration parameters) it can be modeled using the overland flow
-re-routing option discussed earlier in Section 3.7. For example, if
-disconnected rooftops comprised 25 percent of the total impervious area
-of a subcatchment (as opposed to the total DCIA) then one could tell
-SWMM that this percentage of impervious area should be internally routed
-onto the pervious sub-area of the subcatchment.
-
-Another method of estimating the effective impervious area given
-measured data is to plot the runoff (in. or mm) vs. rainfall (in. or mm)
-for small storms. The slope of the regression line is a good estimate of
-the effective impervious area (Doyle and Miller, 1980).
-
-Southerland (2000) has proposed a series of regression equations
-relating effective impervious area (EIA) to total impervious area (TIA)
-based on data from over 40 sub-basins collected by the USGS in Oregon.
-Each equation has the form $EIA = a{TIA}^{b}$ where the coefficients *a*
-and *b* are listed in Table 3-1. Further information on the concept of
-directly connected (or "hydraulically effective") impervious areas is
-contained in the review article by Shuster et al. (2005).
-
-| ***a*** | ***b*** | **Condition** |
-| --- | --- | --- |
-| 0.1 | 1.5 | Average basins served by storm sewers and residential rooftops are not directly connected to sewers. |
-| 0.4 | 1.2 | Highly connected basins with residential rooftops directly connected to storm sewers. |
-| 1.0 | 1.0 | Totally connected basins that are completely served by storm sewers to which all impervious surfaces are directly connected. |
-| 0.04 | 1.7 | Partly disconnected basins where more 50% of the area is served by grassy swales or roadside ditches instead of storm sewers and residential rooftops are not directly connected to sewers. |
-| 0.01 | 2.0 | Highly disconnected basins where only a small percentage of area is served by storm sewers or has 70 percent or more draining to infiltration areas. |
-
-  : []{#_Toc430249140 .anchor}**Table 3‑2 Coefficients for
-  Southerland\'s EIA equations.**
-
-### 3.8.4 Subcatchment Width
-
-If overland flow is visualized as running down-slope off of an
-idealized, rectangular catchment, then the width of the subcatchment is
-the physical width of overland flow. This may be seen for the idealized
-catchment shown once again in Figure 3-8 in which the lateral flow per
-unit width, *qL*, is computed and multiplied by the width to obtain
-the total inflow into the channel. (As mentioned previously, the SWMM
-channel/pipes can only receive a concentrated inflow at their inlet
-nodes, however, and do not receive inflow distributed along their
-length.) Note also in Figure 3-8 that for this idealized case, if the
-two sides of the subcatchment are symmetrical the total width is twice
-the length of the drainage channel.
-
-![[]{#_Toc426447675 .anchor}**Figure 3‑8 Idealized representation of a
-subcatchment.**](VolumeI/media/media/image5.emf){width="3.6402449693788275in"
-height="2.5085629921259844in"}
-
-Because real subcatchments will not be rectangular with properties of
-symmetry and uniformity, it is necessary to adopt other procedures to
-obtain the width for more general cases. This is of special importance
-because if the slope and roughness are fixed (see Equation 3-4), the
-width can be used to alter the hydrograph shape.
-
-For example, consider the five different subcatchment shapes shown on
-Figure 3-9. Catchment hydraulic properties, routing parameters are given
-in Table 3-3. Outflow hydrographs for continuous rainfall and for
-rainfall of duration 20 min are shown on Figure 3-10. These were
-computed using the nonlinear reservoir equation (Section 3.1) with a
-time step of 5 min. Clearly, as the subcatchment width is narrowed
-(i.e., the outlet is constricted), the time to equilibrium outflow
-increases. Thus, equilibrium is achieved quite rapidly for cases A and B
-and more slowly for cases C, D and E.
-
-Two routing effects may be observed. A storage effect is very
-noticeable, especially when comparing hydrographs A and E for duration
-of 20 minutes. The subcatchment thus behaves in the familiar manner of a
-reservoir. For case E, the outflow is constricted (narrow); hence, for
-the same amount of inflow (rainfall) more water is stored and less
-released. For case A, on the other hand, water is released rapidly and
-little is stored. Thus case A has both the fastest rising and recession
-limbs of the hydrographs.
-
-A shape effect is also evident. Theoretically, all the hydrographs peak
-simultaneously (at the cessation of rainfall). However, a large width
-(e.g., case A) will cause equilibrium outflow to be achieved rapidly,
-producing a flat-topped hydrograph for the remainder of the (constant)
-rainfall. Thus, for a catchment schematized with several subcatchments
-and subject to variable rainfall, increasing the widths tends to cause
-peak flows to occur sooner. In general, however, shifting hydrograph
-peaks in time is difficult to achieve through adjustment of subcatchment
-flow routing parameters. The time distribution of runoff is by far most
-sensitive to the time distribution of rainfall.
-
-[]{#_Toc426447676 .anchor}**Figure 3‑9 Rectangular subcatchments for
-illustration of shape and width effects.**
-
-+---------------------------------------------------------------------------+-----------------------------------+
-| +-----------------+-----------------+-----------------+-----------------+ | Slope = 1%                        |
-| | Shape           | A               | W               | L               | |                                   |
-| |                 |                 |                 |                 | | Imperviousness = 100%             |
-| |                 | (ft2)         | (ft)            | (ft)            | |                                   |
-| +:================+:================+:================+:================+ | Depression Storage = 0            |
-| | A               | 40,000          | 800             | 50              | |                                   |
-| |                 |                 |                 |                 | | n = 0.02                          |
-| | B               | 40,000          | 400             | 100             | |                                   |
-| |                 |                 |                 |                 | | Equilibrium outflow = i\*A =      |
-| | C               | 40,000          | 200             | 200             | | 0.926 cfs                         |
-| |                 |                 |                 |                 | |                                   |
-| | D               | 40,000          | 100             | 400             | | Δt = 5 min = 300 sec              |
-| |                 |                 |                 |                 | |                                   |
-| | E               | 40,000          | 50              | 800             | | i\* = Rainfall excess             |
-| +-----------------+-----------------+-----------------+-----------------+ |                                   |
-|                                                                           | = 1.0 in./hr = 0.000023148 ft/sec |
-+===========================================================================+===================================+
-
-: []{#_Toc430249141 .anchor}**Table 3‑3 Data for example of effect of
-subcatchment width.**
-
-

-4_15
-
Figure 3‑10 Subcatchment hydrographs for
-different shapes of Figure 3-9.

-

-
-So what is the best estimate of subcatchment width? If the subcatchment
-has the appearance of Figure 3-8, then the width is approximately twice
-the length of the main drainage channel through the catchment. However,
-if the drainage channel is on the side of the catchment as in Figure
-3-9, the width is just the length of the channel. A good estimate for
-the width can be obtained by determining the average maximum length of
-overland flow and dividing the area by this length.
-
-For example, consider Subcatchment 8412 of the Fisk B Catchment, shown
-in Figure 3-7. The area of Subcatchment 8412 is approximately 72,820 ft2
-(1.67 ac). A crude estimate of the average distance from the street to
-the drainage divide for overland flow is made by measuring the length on
-the map ten times (Table 3-4). The street in the lower part of the
-subcatchment is divided into six equal segments, approximately 57 ft in
-length. Distances to the boundary (drainage divide) from the centerline
-of the street are then measured normal to the contours from each of the
-five internal locations along the street:
-
-The width is then estimated as *W* ≈ 72,820 / 119 = 612 ft. Clearly, the
-average length estimate can be improved with several additional
-measurements off the figure. But in practice, this may even be done "by
-eye," since width is sometimes used as a calibration parameter. The
-distances are measured to each side of the street under the assumptions
-that travel times along the street are much less than off the lots. This
-may not be true if roof drains are directly connected to the street
-(unknown for this example).
-
-+-------------------------------------+-------------------------------------+
-| **North side of street to boundary, | **South side of street to boundary, |
-| ft**                                | ft**                                |
-+:===================================:+:===================================:+
-| 247                                 | 31                                  |
-+-------------------------------------+-------------------------------------+
-| 247                                 | 74                                  |
-+-------------------------------------+-------------------------------------+
-| 232                                 | 74                                  |
-+-------------------------------------+-------------------------------------+
-| 103                                 | 74                                  |
-+-------------------------------------+-------------------------------------+
-| 74                                  | 60                                  |
-+-------------------------------------+-------------------------------------+
-| Sum: 1,186 ft; Average: 119 ft                                            |
-+---------------------------------------------------------------------------+
-
-: []{#_Toc430249142 .anchor}**Table 3‑4 Width computations for Portland
-example.**
-
-When assigning an overland flow path length, particularly for sites with
-natural land cover, one must recognize that there is a maximum distance
-over which true sheet flow prevails. Beyond this, runoff consolidates
-into rivulet flow with much faster travel times and less opportunity for
-infiltration. There is no general agreement on what distance should be
-used as a maximum overland flow path length. The Natural Resources
-Conservation Service recommends a maximum length of 100 ft (NRCS, 2010)
-while Denver's Urban Drainage and Flood Control District uses a maximum
-of 500 ft. (UDFCD, 2007).
-
-Another estimate for the width is twice the length of the main drainage
-channel, the street in this instance. The street is approximately 360 ft
-long, which would give an estimate of about 720 ft for the Subcatchment
-8412. However, this estimate assumes approximately equal areas on both
-sides of the drainage channel whereas most real subcatchments will be
-irregular in shape and have a drainage channel that is off center, as in
-Figure 3-11. This is especially true of rural or undeveloped catchments.
-A simple way of handling this case is given by DiGiano et al. (1977). A
-skew factor may be computed,
-
-+-----------------------------------+-----------------------------------+
-| > $$Z = \frac{A_{m}}{A}$$         | (‎3-10)                            |
-+===================================+===================================+
-
-where:
-
-> Z = skew factor, 0.5 ≤ Z ≤ 1,
->
-> Am = larger of the two areas on each side of the channel
->
-> A = total area.
-
-

-4_16
-
Figure 3‑11 Irregular subcatchment shape
-for width calculations (DiGiano et al., 1977, p.
-165).

-

-
-If *L* is the length of the main drainage channel then the width *W* is
-simply weighted sum between the two limits of *L* and *2L*:
-
-+-----------------------------------+-----------------------------------+
-| > $W = L + 2L(1 - Z)$             | (3-11)                            |
-+===================================+===================================+
-
-Applying this idea to Subcatchment 8412 of Figure 3-7, the area north of
-the street centerline is approximately 1.19 ac, and the area of the
-street and south is approximately 0.48 ac. Hence,
-
-*Z* = 1.19 / 1.67 = 0.71
-
-and an estimate for the width is,
-
-*W* = 360 + 2 • 360 • (1 -- 0.71) = 567 ft
-
-This estimate is not far from the estimate of roughly 610 ft obtained by
-dividing the area by the average maximum flow length.
-
-A more fundamental approach to estimating both subcatchment width and
-slope has recently been developed by Guo and Urbonas (2007). The idea is
-to use "shape factors" to convert a natural watershed as pictured in
-Figure 3-11 into the idealized overland flow plane of Figure 3-8. A
-shape factor is an index that reflects how overland flows are collected
-in a watershed. The shape factor X for the actual watershed is defined
-as $\frac{A}{L^{2}}$ where A is the watershed area and L is the length
-of the watershed's main drainage channel (not necessarily the length of
-overland flow). The shape factor Y for the idealized watershed is $W/L$.
-Requiring that the areas of the actual and idealized watersheds be the
-same and that the potential energy in terms of the vertical fall along
-the drainage channel be preserved, Guo and Urbonas (2007) derive the
-following expression for the shape factor Y of the idealized watershed:
-
-+------------------------------------------+------------------------------+
-| > $$Y = 2X(1.5 - \ Z)(2K - X)/(2K - 1)$$ | (3-12)                       |
-+==========================================+==============================+
-
-where K is an upper limit on the watershed shape factor. Guo and Urbonas
-(2007) recommend that K be between 4 and 6 and note that a value of 4 is
-used by Denver's Urban Drainage and Flood Control District. Once Y is
-determined, the equivalent width W for the idealized watershed is
-computed as $YL$.
-
-Applying this approach to Subcatchment 8412 (using K = 4) produces the
-following:
-
-> X = (1.67 acres • 43,560 ft2/acre) / (3602) = 0.56
->
-> Z = 1.19 / 1.67 = 0.71
->
-> Y = (2 • 0.56) • (1.5 -- 0.71) • (0.56 -- 2•4) / (1 -- 2•4) = 0.94
->
-> W = 360 • 0.94 = 338 ft.
-
-This width value is considerably lower than those derived from direct
-estimates of either the longest flow path length or the drainage channel
-length. As a result, it would most likely produce a longer time to peak
-for the runoff hydrograph.
-
-To reiterate, changing the subcatchment width changes the routing
-parameter *α* of Equation 3-5. Thus, identical effects to those
-discussed above may be created by appropriate variation of the roughness
-and/or slope.
-
-### 3.8.5 Slope
-
-The subcatchment slope should reflect the average slope along the
-pathway of overland flow to inlet locations. For a simple geometry
-(e.g., Figures 3-8 and 3-9) the calculation is simply the elevation
-difference divided by the length of flow. For more complex geometries,
-several overland flow pathways may be delineated, their slopes
-determined, and a weighted slope computed using a path-length weighted
-average. Such a procedure is described by DiGiano et al. (1977, pp.
-101-102).
-
-Alternatively it may be sufficient to assume that overland flow occurs
-along what the user considers to be the hydrological dominant slope for
-the conditions being simulated. One would then choose the appropriate
-overland flow length, slope, and roughness for this equivalent plane.
-The Guo and Urbonas (2007) Shape Factor approach discussed in the
-previous section computes the slope of this equivalent plane as
-$\frac{S_{o}L}{(A/YL + YL)}$ where So is the slope of the drainage
-channel and the other variables are as defined in Section 3.8.4.
-
-Finally, if there are clearly two different slopes to consider for the
-subcatchment, it may be subdivided into two subcatchments and the
-overland flow re-routing option be used to route flow from the upper
-subcatchment onto the lower subcatchment.
-
-### 3.8.6 Manning's Roughness Coefficient, n
-
-Values of Manning's roughness coefficient, *n*, are not as well known
-for overland flow as for channel flow because of the considerable
-variability in landscape features, transitions between laminar and
-turbulent flow, very small flow depths, etc. Most studies indicate that
-for a given surface cover, *n* varies inversely in proportion to depth,
-discharge or Reynold's number. Such studies may be consulted for
-guidance (e.g., Petryk and Bosmajian, 1975; Chen, 1976; Christensen,
-1976; Graf and Chun, 1976; Turner et al., 1978; Emmett, 1978), or
-generalized values used (e.g., Chow, 1959; Crawford and Linsley, 1966;
-Huggins and Burney, 1982; French, 1985; Engman, 1986; Yen, 2001).
-
-Roughness values used in the Stanford Watershed Model (Crawford and
-Linsley, 1966) are given in Table 3-5 along with values from Engman
-(1986) and Yen (2001). Engman also provides values for other
-agricultural land uses and a good literature review. There is no
-consensus among the three sources of data in the table, reflecting the
-uncertainty in these estimates. However, recall the discussion of
-Equation 3-5 in Section 3.8.1. For SWMM, it is common to fix estimates
-of slope and Manning's *n* and calibrate with the subcatchment width.
-
-### 3.8.7 Depression Storage
-
-Depression (retention) storage (depth *dS* in Figure 3-2) is a volume
-that must be filled prior to the occurrence of runoff on both pervious
-and impervious areas (Viessman and Lewis, 2003). It represents a loss or
-"initial abstraction" caused by such phenomena as surface ponding,
-surface wetting, interception and evaporation. In the SWMM
-rainfall-runoff algorithm (Section 3.1), water stored as depression
-storage on pervious areas is subject to infiltration (and evaporation),
-so that available storage capacity is continuously and rapidly
-replenished. Water stored in depression storage on impervious areas is
-depleted only by evaporation and therefore it takes much longer to
-restore such storage to its full capacity.
-
-+----------------------+----------------------------+-------------------+-------------------+
-| Source               | Ground Cover               | n                 | Range             |
-+:=====================+:===========================+:==================+:==================+
-| Crawford and Linsley | Smooth asphalt             | 0.01              |                   |
-| (1966)a            |                            |                   |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Asphalt of concrete paving | 0.014             |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Packed clay                | 0.03              |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Light turf                 | 0.20              |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Dense turf                 | 0.35              |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Dense shrubbery and forest | 0.4               |                   |
-|                      | litter                     |                   |                   |
-+----------------------+----------------------------+-------------------+-------------------+
-| Engman (1986)b     | Concrete or asphalt        | 0.011             | 0.010-0.013       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Bare sand                  | 0.010             | 0.01-0.016        |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Graveled surface           | 0.02              | 0.012-0.03        |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Bare clay-loam (eroded)    | 0.02              | 0.012-0.033       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Range (natural)            | 0.13              | 0.01-0.32         |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Bluegrass sod              | 0.45              | 0.39-0.63         |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Short grass prairie        | 0.15              | 0.10-0.20         |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Bermuda grass              | 0.41              | 0.30-0.48         |
-+----------------------+----------------------------+-------------------+-------------------+
-| Yen (2001)c        | Smooth asphalt pavement    | 0.012             | 0.010-0.015       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Smooth impervious surface  | 0.013             | 0.011-0.015       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Tar and sand pavement      | 0.014             | 0.012-0.016       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Concrete pavement          | 0.017             | 0.014-0.020       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Rough impervious surface   | 0.019             | 0.015-0.023       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Smooth bare packed soil    | 0.021             | 0.017-0.025       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Moderate bare packed soil  | 0.030             | 0.025-0.035       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Rough bare packed soil     | 0.038             | 0.032-0.045       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Gravel soil                | 0.032             | 0.025-0.045       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Mowed poor grass           | 0.038             | 0.030-0.045       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Average grass, closely     | 0.050             | 0.040-0.060       |
-|                      | clipped sod                |                   |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Pasture                    | 0.055             | 0.040-0.070       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Timberland                 | 0.090             | 0.060-0.120       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Dense grass                | 0.090             | 0.060-0.120       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Shrubs and bushes          | 0.120             | 0.080-0.180       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Business land use          | 0.022             | 0.014-0.035       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Semi-business land use     | 0.035             | 0.022-0.050       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Industrial land use        | 0.035             | 0.020-0.050       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Dense residential land use | 0.040             | 0.025-0.060       |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Suburban residential land  | 0.055             | 0.030-0.080       |
-|                      | use                        |                   |                   |
-|                      +----------------------------+-------------------+-------------------+
-|                      | Parks and lawns            | 0.075             | 0.040-0.120       |
-+----------------------+----------------------------+-------------------+-------------------+
-| aObtained by calibration of Stanford Watershed Model.                                   |
-|                                                                                           |
-| bComputed by Engman (1986) by kinematic wave and storage analysis of measured           |
-| rainfall-runoff data.                                                                     |
-|                                                                                           |
-| cComputed on basis of kinematic wave analysis.                                          |
-+-------------------------------------------------------------------------------------------+
-
-: []{#_Toc430249143 .anchor}**Table 3‑5 Estimates of Manning\'s
-roughness coefficient for overland flow**
-
-Depression storage may be used to simulate interception, the storage of
-rainfall on vegetation. Perhaps counter-intuitively, a tree, for
-instance, that intercepts rainfall can be simulated as an impervious
-surface, with depression storage (interception), whose runoff is onto an
-adjacent or underlying pervious surface. In this way, the interception
-capacity is regenerated only by evaporation.
-
-As described earlier, a percent "*% Zero-Imperv*" of the impervious area
-is assigned zero depression storage in order to promote immediate
-runoff. Another option to achieve zero depression storage on impervious
-areas (and thus immediate runoff) is to set *% Zero-Imperv* to zero, and
-enter zero values for depression storage for the impervious area of each
-subcatchment, as desired.
-
-Depression storage may be derived from rainfall-runoff data for
-impervious areas by plotting runoff volume *V* (depth) as the ordinate
-against rainfall volume *P* as the abscissa for several storms. The
-rainfall intercept at zero runoff is the depth of depression storage
-*ds*, i.e., a regression of the form
-
-+-------------------------------------+-----------------------------------+
-| > $$V = C\left( P - d_{S} \right)$$ | (‎3-13)                            |
-+=====================================+===================================+
-
-where *C* is a coefficient. This kind of analysis tends to work better
-for longer averaging periods than individual storm events, but for storm
-events will work better for small, more impervious catchments than for
-larger mixed catchments. The reason is that even for small rainfall
-amounts, impervious surfaces (DCIA) will generate some runoff (one
-reason for the *% Zero-Imperv* parameter). Hence, a depression storage
-value found as the intercept may be appropriate for a longer term water
-balance than for simulation of hydrographs.
-
-Data obtained in this manner from 18 urban European catchments (Falk and
-Niemczynowicz, 1978, Kidd, 1978a, Van den Berg, 1978) showed that
-depression storages ranged between 0.005 and 0.059 inches, depending on
-slope, with an average of 0.023 inches. Kidd (1978b) presented the
-following regression for these data:
-
-+-----------------------------------+-----------------------------------+
-| > $$d_{S} = 0.303S^{0.49}$$       | (‎3-14)                            |
-+===================================+===================================+
-
-where *ds* is depression storage (inches) and *S* is catchment slope
-(percent).
-
-Viessman and Lewis (2003, p. 140) present a linear relation between
-depression storage and slope based on four small impervious areas near
-Baltimore, MD:
-
-+-----------------------------------+-----------------------------------+
-| > $$d_{S} = 0.136 - 0.032S$$      | (‎3-15)                            |
-+===================================+===================================+
-
-where the observed values of *ds* ranged from 0.06 to 0.11 inches.
-
-Separate values of depression storage can be used for the pervious and
-impervious subareas within a subcatchment. Representative values for the
-latter can probably be obtained from the European data just discussed.
-Pervious area measurements are lacking; most reported values are derived
-from successful simulation of measured runoff hydrographs. Although
-pervious area values are expected to exceed those for impervious areas,
-it must be remembered that the infiltration loss, often included as an
-initial abstraction in simpler models, is computed explicitly in SWMM.
-Hence, pervious area depression storage might best be represented as an
-interception loss, based on the type of surface vegetation. Many
-interception estimates are available for natural and agricultural areas
-(Linsley et al., 1949; Maidment, 1993; Viessman and Lewis, 2003). For
-grassed urban surfaces a value of 0.10 inches (2.5 mm) may be
-appropriate.
-
-As mentioned earlier, several studies have determined depression storage
-values in order to achieve successful modeling results. For instance,
-Hicks (1944) in Los Angeles used values of 0.20, 0.15 and 0.10 inches
-(5.1, 3.8, 2.5 mm) for sand, loam and clay soils, respectively, in the
-urban area. Tholin and Keifer (1960) used values of 0.25 and 0.0625
-inches (6.4 and 1.6 mm) for pervious and impervious areas, respectively,
-for their Chicago hydrograph method. Brater (1968) found a value of 0.2
-inches (5.1 mm) for three basins in metropolitan Detroit. Miller and
-Viessman (1972) give an initial abstraction (depression storage) of
-between 0.10 and 0.15 inches (2.5 and 3.8 mm) for four composite urban
-catchments. The American Society of Civil Engineers (1992) suggests
-depression storage of 1/16 inch for impervious areas and 1/4 inch for
-pervious areas. The Denver Urban Drainage and Flood Control District
-(UDFCD, 2007) recommends depression storage losses of 0.1 inches for
-large paved areas and flat roofs, 0.05 inches for sloped roofs, 0.35
-inches for lawn grass, and 0.4 inches for open fields.
-
-In SWMM, depression storage may be treated as a calibration parameter,
-particularly to adjust runoff volumes. If so, extensive preliminary work
-to obtain an accurate a priori value may be unnecessary since the value
-will be changed during calibration anyway. Depression storage is most
-sensitive for small storms; as the depth increases it becomes a smaller
-and smaller relative component of the water budget.
-
-### 3.8.8 Parameter Sensitivity
-
-Sensitivity of surface runoff volume and peak flow estimates to key
-surface runoff parameters is listed in Table ‎3-6. The influence of storm
-depth is not represented in the table.
-
-| **Parameter** | **Typical effect on hydrograph** | **Effect of increase on runoff volume** | **Effect of increase on runoff peak** | **Comments** |
-| --- | --- | --- | --- | --- |
-| Area | Significant | Increase | Increase | Less effect for a highly porous catchment |
-| Imperviousness | Significant | Increase | Increase | Less effect when pervious areas have low infiltration capacity. |
-| Width | Affects shape | Decrease | Increase | For storms of varying intensity, increasing the width tends to produce higher and earlier hydrograph peaks, a generally faster response. Only affects volume to the extent that reduced width on pervious areas provides more time for infiltration. |
-| Slope | Affects shape | Decrease | Increase | Same as for width, but less sensitive, since flow is proportional to square root of slope. |
-| Roughness | Affects shape | Increase | Decrease | Inverse effect as for width. |
-| Depression storage | Moderate | Decrease | Decrease | Significant effect only for low-depth storms. |
-
-  : []{#_Toc430249144 .anchor}**Table 3‑6 Sensitivity of runoff volume
-  and peak flow to surface runoff parameters.**
-
-Losses (ET, depression storage, infiltration) are relatively less
-important as the storm depth increases. That is, for flooding the land
-surface behaves more and more like an impervious surface, which is one
-reason why urbanization has less impact on high-return period events
-than on common events. If ground saturation is an important
-consideration, then the groundwater routines (Chapter 5) might be
-invoked to allow the water table to rise to the surface, or the maximum
-infiltration volume option used (Chapter 4). When calibrating for more
-common (lower depth) events, depression storage becomes more important,
-especially as the storm depth drops to just a few tenths of an inch.
-Calibration for small storms is often difficult, since depression
-storage is difficult to estimate and dependent on initial conditions.
-
-## 3.9 Numerical Example
-
-Earlier in section 3.8.4 a numerical example was presented showing the
-effect that the width parameter had on the runoff hydrographs from a
-completely impervious subcatchment subjected to constant rainfall
-intensity. This section presents a more realistic example that
-highlights the difference in runoff responses between impervious and
-pervious subcatchments that are subjected to the same design storm
-hyetograph. Table 3-7 lists the parameters used for each subcatchment.
-Note that normally a single subcatchment could be used to contain both
-of these sub-areas, but they are represented here as separate
-subcatchments so that the runoff from each can be compared more readily.
-
-+---------------+---------------------------+------------------+------------------+
-| **Item**      | **Parameter**             | **Impervious**   | **Pervious**     |
-|               |                           |                  |                  |
-|               |                           | **Subcatchment** | **Subcatchment** |
-+:==============+:==========================+:=================+:=================+
-| Subcatchment  | Area (acres)              | 5                | 5                |
-|               +---------------------------+------------------+------------------+
-|               | Percent Impervious        | 100              | 0                |
-|               +---------------------------+------------------+------------------+
-|               | Percent Slope             | 0.5              | 0.5              |
-|               +---------------------------+------------------+------------------+
-|               | Width (ft)                | 140              | 140              |
-|               +---------------------------+------------------+------------------+
-|               | Roughness                 | 0.01             | 0.1              |
-|               +---------------------------+------------------+------------------+
-|               | Depression Storage (in)   | 0.05             | 0.05             |
-|               +---------------------------+------------------+------------------+
-|               | Percent with No           | 25               | 0                |
-|               | Depression Storage        |                  |                  |
-|               +---------------------------+------------------+------------------+
-|               | Evaporation (in/hr)       | 0                | 0                |
-+---------------+---------------------------+------------------+------------------+
-| Horton        | Initial Capacity (in/hr)  | N/A              | 1.2              |
-| Infiltration  |                           |                  |                  |
-|               +---------------------------+------------------+------------------+
-|               | Final Capacity (in/hr)    | N/A              | 0.1              |
-|               +---------------------------+------------------+------------------+
-|               | Decay Coefficient         | N/A              | 2.0              |
-|               | (hr-1)                  |                  |                  |
-+---------------+---------------------------+------------------+------------------+
-| Design Storm  | Duration (hr)             | 6.0              | 6.0              |
-|               +---------------------------+------------------+------------------+
-|               | Total Depth (in)          | 2.0              | 2.0              |
-|               +---------------------------+------------------+------------------+
-|               | Time-to-Peak / Duration   | 0.375            | 0.375            |
-+---------------+---------------------------+------------------+------------------+
-
-: []{#_Toc430249145 .anchor}**Table 3‑7 Parameters used for illustrative
-runoff example**
-
-The two subcatchments were given identical area, slope, width, and
-depression storage. The roughness of the pervious subcatchment was made
-ten times higher than the impervious roughness as reflected in Table
-3-7. The infiltration parameters for the pervious area are
-representative of a well-drained sandy loam soil. A description of the
-Horton infiltration method used in SWMM is supplied in the next chapter.
-The design storm is a 6-hour, 2-inch event with a triangular-shaped
-hyetograph.
-
-Figure 3-12 shows the runoff hydrographs that result for the example
-design event. Flow rates are represented on a per unit area basis so
-that they can be compared against the rainfall intensities. For the
-impervious area, runoff from the 25% of the area with no depression
-storage begins immediately, while runoff from the remaining area is
-delayed by the available depression storage at the start of the storm.
-After this storage is filled, the impervious runoff hydrograph follows
-that of the storm hyetograph. About 97% of the rain that falls on the
-impervious area becomes runoff and there is a slight reduction in peak
-runoff rate. For the pervious area there is no runoff at all for the
-first 2 hours of the storm, as the depression storage and available
-infiltration capacity are sufficient to capture all of the rainfall
-volume during this period. After this, the remaining infiltration
-capacity is such that only 30% of the total storm volume becomes runoff.
-The peak runoff rate is only one third of the peak rainfall rate. When
-taken together, the total hydrograph (equal to half the sum of the two
-sub-area hydrographs, since flows are expressed per unit area) reduces
-the peak storm intensity by 50% and the total storm volume by 64%.
-
-[]{#_Toc426447679 .anchor}**Figure 3‑12 Runoff results for illustrative
-example.**
-
-## 3.10 Approximating Other Runoff Methods
-
-To varying degrees it is possible to have the results of SWMM's runoff
-computations approximate those obtained from other well known methods.
-The following sub-sections describe how to do this for the runoff
-coefficient method, the SCS Curve Number method, and the unit hydrograph
-method.
-
-### 3.10.1 Runoff Coefficient Method
-
-This method is sometimes used in preliminary screening-level models to
-generate runoff flows from long-term rainfall records or rainfall
-probability distributions with a minimum of site-specific data required
-(see STORM (Corps of Engineers, 1977); NetSTORM (Heineman, 2004); Adams
-and Papa, 2000). It computes runoff *Q* (cfs) after all depression
-storage has been filled as:
-
-+-----------------------------------+-----------------------------------+
-| > $$Q = CiA$$                     | (‎3-16)                            |
-+===================================+===================================+
-
-where *C* is a runoff coefficient, *i* is the rainfall rate (ft/s), and
-*A* is the subcatchment area (ft2). If infiltration over the pervious
-area is considered then
-
-+-------------------------------------------------------------------+-----------------------------------+
-| > $$Q = \left\lbrack Ci + (1 - C)max(0,\ i - f) \right\rbrack A$$ | (‎3-17)                            |
-+===================================================================+===================================+
-
-where *f* is a constant infiltration rate (ft/s) and *C* can be
-interpreted as the fraction of impervious area. Values of C have been
-tabulated for various types of land uses (see ASCE, 1992 or UDFCD,
-2007).
-
-To implement this approach in SWMM one could do the following:
-
-1.  Set the subcatchment's percent imperviousness to *100C* and its
-    percent of imperviousness with no depression storage to 0.
-
-2.  Assign the same depression storage depth to both the pervious and
-    impervious areas.
-
-3.  Use any values for slope and width, and 0 for both the pervious and
-    impervious Manning's *n*.
-
-4.  Use the Horton infiltration option (discussed in Chapter 4) and let
-    its maximum and minimum infiltration rates be the same (either a
-    very large value if 3-16 is being used or to *f* for 3-17).
-
-Setting up a model in this fashion will produce exactly the same results
-as if Equations 3-16 or 3-17 were implemented directly. When the Manning
-roughness *n* is 0, SWMM bypasses Equation 3-1 and simply converts all
-rainfall excess at each time step into instantaneous runoff.
-
-Note that this method completely ignores any storage or delay that
-overland flow contributes to the shape of a runoff hydrograph as well as
-the declining rate of infiltration that occurs over time. It can,
-however, allow one to perform preliminary screening types of analyses
-relatively quickly with a minimum of site data required.
-
-### 3.10.2 SCS Curve Number Method
-
-The SCS (Soil Conservation Service, now known as the Natural Resources
-Conservation Service) Curve Number method is a widely used procedure for
-computing runoff from single-event design storms. As implemented in
-NRCS's TR-55 manual (NRCS, 1986) it consists of three separate
-runoff--related computations: one computes total runoff volume for any
-given rainfall event while the other two estimate a peak discharge and a
-runoff hydrograph for a synthetic 24-hour design storm with a given
-return period. These latter two computations utilize a kinematic wave
-approach to overland flow as well as a standard 24-hour design storm
-time distribution and are therefore incompatible with SWMM's approach to
-generating runoff hydrographs. SWMM can however, approximate the Curve
-Number method's estimate of total runoff volume from a subcatchment by
-doing the following:
-
-1.  Set the percent impervious area of the subcatchment to zero.
-
-2.  Select the Curve Number method for computing infiltration (see
-    Chapter 4) and use the same curve number that one would use with the
-    SCS method.
-
-3.  Set the pervious area depression storage equal to the initial
-    abstraction depth that one would otherwise use with the SCS method.
-
-4.  Set the pervious area roughness coefficient to 0 to prevent any
-    delay in runoff flow.
-
-As an example, consider a residential area with a Curve Number of 80
-subjected to a uniform storm of 4 inches over 4 hours. The SCS method
-for computing runoff volume (for US units) is:
-
-+-------------------------------------------+-----------------------------------+
-| > $$R = \frac{(P - Ia)^{2}}{P - Ia + S}$$ | (‎3-18)                            |
-+===========================================+===================================+
-
-where
-
-+-----------------------------------+-----------------------------------+
-| > $$S = \frac{1000}{CN} - 10$$    | (‎3-19)                            |
-+===================================+===================================+
-
-and
-
-| Symbol | Description |
-| :--- | :--- |
-| *R* | cumulative runoff volume (inches) |
-| *P* | cumulative rainfall (inches) |
-| *Ia* | initial abstraction (inches) |
-| *S* | soil moisture storage capacity (inches) |
-| *CN* | curve number. |
-
-Using the SCS recommended initial abstraction of *0.2S* = 0.5 inches,
-the resulting SCS runoff volume is 2.04 inches. Running SWMM for a
-single subcatchment in the manner prescribed above produces a total
-runoff volume of 1.98 inches. When a roughness of 0.1 (along with a
-width of 100 ft and slope of 0.5%) is used to allow SWMM to produce a
-more realistic runoff hydrograph, the total runoff volume drops to 1.67
-inches due to the increased time available for ponded water to
-infiltrate as it flows over the surface.
-
-### 3.10.3 Unit Hydrograph Method
-
-A unit hydrograph (UH) is a linear transfer function used to convert a
-time series of rainfall excess into a runoff hydrograph. A unit
-hydrograph can be derived from observed rainfall-runoff records within a
-specific catchment or be chosen from a number of synthetic unit
-hydrographs that have been developed over the years. The shapes of
-synthetic hydrographs have been parameterized with respect to certain
-geographic and land cover variables. Specific examples include Snyder's
-UH, Clark's UH, the Espey-Altman UH, the SCS (NRCS) Dimensionless UH,
-the SCS (NRCS) Triangular UH, the Santa Barbara Urban Hydrograph, and
-the Colorado Urban Hydrograph (see Nicklow et al, 2006 for further
-details). As an example, the SCS (NRCS) triangular UH is shown in Figure
-3-13. The parameters *Qp* and *tp* are functions of the catchment's
-time of concentration and its area.
-
-![[]{#_Toc426447680 .anchor}**Figure 3‑13 SCS (NRCS) triangular unit
-hydrograph (NRCS,
-2007).**](VolumeI/media/media/image14.emf){width="4.436111111111111in"
-height="2.598611111111111in"}
-
-SWMM normally uses a unit hydrograph approach to empirically model the
-process by which rainfall causes subsurface inflow into leaky sewer
-pipes, otherwise known as rainfall dependent inflow/infiltration (RDII).
-The details are described in Chapter 7. Any location within the drainage
-system can have a set of RDII UH's assigned to it. Each set of UH's can
-consist of up to three individual triangular UH's (like the one shown in
-Figure 3-13). One can therefore use an RDII-type analysis to replace
-SWMM's normal rainfall-runoff computational scheme by doing the
-following:
-
-1.  For each subcatchment, define a triangular unit hydrograph that
-    represents the subcatchment's runoff response to rainfall (as
-    opposed to inflow/infiltration into leaky sewer pipes as would
-    normally be the case). Assign the same rain gage to the unit
-    hydrograph as one would otherwise use for the subcatchment. The same
-    unit hydrograph object can be used by multiple subcatchments.
-
-2.  Specify the appropriate depression storage (i.e., initial
-    abstraction) as part of each subcatchment's unit hydrograph
-    description.
-
-3.  If the SWMM data set already had subcatchments delineated in it,
-    either delete them or create a dummy rain gage that has no rainfall
-    associated with it and assign this gage to all subcatchments.
-
-4.  For each drainage system node that is the outflow point of a
-    subcatchment, designate an external RDII inflow for it that uses the
-    subcatchment's unit hydrograph and its full area as the sewershed
-    area that contributes to RDII at the node.
-
-After running SWMM with these modifications, the runoff hydrographs for
-each subcatchment are equivalent to the Lateral Inflow results produced
-at each subcatchment's outlet node.
-
-There are clearly some limitations to keep in mind when considering this
-approach. First, SWMM can only utilize triangular shaped unit
-hydrographs. This might require some approximation if one wishes to use
-one of the standard synthetic unit hydrographs whose shape is not
-triangular. Second, any losses from infiltration must be taken into
-account when the unit hydrographs are constructed. SWMM's RDII procedure
-does not account for the details of soil infiltration in the manner that
-SWMM's normal runoff modeling does. Finally, in by-passing SWMM's normal
-runoff procedure one also loses the ability to model other
-subcatchment-related phenomena, such as overland flow re-routing as
-described in section 3.7 or pollutant buildup and washoff.
-
-### 3.10.4 Using Externally-Generated Runoff Data
-
-Finally, it should be mentioned that it is possible to use any set of
-externally generated runoff data to drive SWMM's flow and pollutant
-routing routines. This can be done by placing the runoff time series
-data in a specially formatted Routing Interface file. This is a text
-file whose format is described in the SWMM 5.0 Users Manual (EPA, 2013).
-An excerpt from such a file that supplies runoff hydrographs to two
-nodes within a drainage network is reproduced in Table 3-8. A Routing
-Interface file can be used in lieu of defining any subcatchments and
-rainfall data for a study area. Or it can be used as a replacement for
-the runoff that would have been generated by SWMM for the subcatchments
-and rainfall data already defined for the study area. In this case
-SWMM's *Ignore Rainfall/Runoff* option must be invoked to prevent the
-program from adding any internally computed runoff to that being
-provided by the interface file.
-
-+------------------------------------+---------------------------------+
-| **File Entry**                     | **Remarks**                     |
-+:===================================+:================================+
-| SWMM5                              | Required identifier             |
-+------------------------------------+---------------------------------+
-| Example File                       | Data file description (can be   |
-|                                    | blank)                          |
-+------------------------------------+---------------------------------+
-| 300                                | Time step for all data (        |
-|                                    | seconds)                        |
-+------------------------------------+---------------------------------+
-| 1                                  | Number of variables provided by |
-|                                    | the file                        |
-+------------------------------------+---------------------------------+
-| FLOW CFS                           | Name and units of each variable |
-|                                    | (one per line)                  |
-+------------------------------------+---------------------------------+
-| 2                                  | Number of nodes with inflow     |
-|                                    | data                            |
-+------------------------------------+---------------------------------+
-| N1                                 | Name of each node (one per      |
-|                                    | line)                           |
-| N2                                 |                                 |
-+------------------------------------+---------------------------------+
-| Node Year Mon Day Hr Min Sec Flow  | Column headings for data to     |
-|                                    | follow (can be blank)           |
-+------------------------------------+---------------------------------+
-| N1 2002 04 01 00 20 00 0.000000    | Node, year, month, day, hour,   |
-|                                    | minute, second, and value for   |
-| N2 2002 04 01 00 20 00 0.002549    | each time step                  |
-|                                    |                                 |
-| N1 2002 04 01 00 25 00 0.000000    |                                 |
-|                                    |                                 |
-| N2 2002 04 01 00 25 00 0.002549    |                                 |
-|                                    |                                 |
-| etc.                               |                                 |
-+------------------------------------+---------------------------------+
-
-: []{#_Toc430249146 .anchor}**Table 3‑8 Contents of a typical Routing
-Interface file**
-
-#  -- Infiltration
-
-## 4.1 Introduction
-
-Infiltration is the process by which rainfall penetrates the ground
-surface and fills the pores of the underlying soil (Akan and Houghtalen,
-2003). It often accounts for the largest portion of rainfall losses over
-pervious areas. Theoretically, infiltration is governed by the Richards
-equation (Richards, 1931) which requires that the relationship between
-soil permeability and pore water tension as a function of soil moisture
-content be known. The difficulty in solving this highly nonlinear
-partial differential equation makes it unsuitable for use in a general
-purpose model like SWMM, especially for long-term continuous
-simulations. Engineers have developed several simpler algebraic
-infiltration models that capture the general dependence of infiltration
-capacity on soil characteristics and the volume of previously
-infiltrated water during the course of a storm event. Because there is
-no universal agreement as to which model is best, SWMM allows the user
-to choose from among four of the most widely used methods: Horton's
-method, a modified Horton method, the Green-Ampt method, and the Curve
-Number method.
-
-No matter which infiltration method is used, the parameters that define
-the method are highly dependent on the type and condition of the soil
-being infiltrated. The NRCS (Natural Resources Conservation Service,
-formerly the Soil Conservation Service or SCS) has classified most soils
-into Hydrologic Soil Groups, A, B, C, and D, depending on their limiting
-infiltra­tion capacities. Well drained, sandy soils are "A"; poorly
-drained, clayey soils are "D," as described in Table 4-1. Every soil in
-the United States has an A-D classification, or sometimes a dual
-classification, such as B/D, meaning drained (artificially) and
-undrained (natural) condition.
-
-The group assigned to specific types of soils and locations can be found
-by consulting:
-
-- the Natural Resources Conservation Service's (NRCS) Field Office
-  Technical Guide
-
-- the NRCS Soil Data Access Web site:
-  
-
-- the Web Soil Survey Web site: .
-
-Additional soil characterization (physics and chemical) data are
-available at the aforementioned web sites.
-
-| **Group** | **Meaning** |
-| --- | --- |
-| A | Low runoff potential. Soils having high infiltration rates even when thoroughly wetted and consisting chiefly of deep, well to excessively drained sands or gravels. |
-| B | Soils having moderate infiltration rates when thoroughly wetted and consisting chiefly of moderately deep to deep, moderately well to well-drained soils with moderately fine to moderately coarse textures. E.g., shallow loess, sandy loam. |
-| C | Soils having slow infiltration rates when thoroughly wetted and consisting chiefly of soils with a layer that impedes downward movement of water, or soils with moderately fine to fine textures. E.g., clay loams, shallow sandy loam. |
-| D | High runoff potential. Soils having very slow infiltration rates when thoroughly wetted and consisting chiefly of clay soils with a high swelling potential, soils with a permanent high water table, soils with a clay-pan or clay layer at or near the surface, and shallow soils over nearly impervious material. |
-
-  : []{#_Toc430249147 .anchor}**Table 4‑1 Hydrologic soil group meanings
-  (NRCS, 2009, Chapter 7)**
-
-The best source of information about a particular soil type is the Soil
-Survey Interpretation, available from a local NRCS office in the U.S.
-Data for soils in each county are often summarized in a county soil
-survey document; the latter is often available in a local Soil and Water
-Conservation District. Because printed versions of these documents are
-increasingly difficult to obtain, on-line access is more likely
-(). Of particular interest is the
-"Physical Properties" report that includes parameters of interest
-regarding infiltration. This report may be downloaded for any soil, as
-illustrated in Figure 4-1. These data include saturated hydraulic
-conductivity, for instance. Other potentially useful reports include:
-
-- Water Features, including information such as hydrologic soil group (B
-  for the Woodburn Silt Loam), water table depth, and ponding frequency.
-
-- RUSLE2 Related Attributes, with data for application of the Universal
-  Soil Loss Equation.
-
-- Engineering Properties, including soil horizon depths, soil
-  classifications (USDA, Unified, AASHTO), sieve analysis, liquid limit,
-  and plasticity index.
-
-In short, the NRCS provides an invaluable resource for information on
-soils and drainage of soils. The agency's data are ever more valuable as
-they increasingly reside on-line on the Web.
-
-![[]{#_Toc426447681 .anchor}**Figure 4‑1 Physical properties for
-Woodburn silt loam, Benton County,
-Oregon.**](VolumeI/media/media/image15.png){width="6.614583333333333in"
-height="2.7604166666666665in"}
-
-## 4.2 Horton's Method
-
-Horton's method is empirical in nature and is perhaps the best known of
-the infiltration equations. Many hydrologists have a "feel" for the best
-values of its three parameters despite the fact that little published
-information is available. In its usual form it is applicable only to
-events for which the rainfall intensity always exceeds the infiltration
-capacity; however, the modified form used in SWMM is intended to
-overcome this limitation. The Horton method has been a part of SWMM
-since the program was first released (Metcalf and Eddy et al., 1971a).
-
-### 4.2.1 Governing Equations
-
-Horton (1933, 1940) proposed the following exponential equation to
-predict the reduction in infiltration capacity over time as observed
-from field measurements:
-
-+--------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{p} = f_{\infty} + \left( f_{0} - f_{\infty} \right)e^{- k_{d}t}$$ | (4-1)                             |
-+==========================================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *fp* | infiltration capacity into soil (ft/sec) |
-| *f∞* | minimum or equilibrium value of *fp* (at t = ∞) (ft/sec) |
-| *f0* | maximum or initial value of *fp* (at t = 0) (ft/sec) |
-| *t* | time from beginning of storm (sec) |
-| *kd* | decay coefficient (sec-1). |
-
-Equation 4-1 is sketched in Figure 4-2 and can be derived theoretically
-from the Richards equation under the proper set of assumptions
-(Eagleson, 1970). Note that actual infiltration will be the lesser of
-actual rainfall and infiltration capacity:
-
-+------------------------------------------------------------+-----------------------------------+
-| > $$f(t) = min\left\lbrack f_{p}(t),\ i(t) \right\rbrack$$ | (4-2)                             |
-+============================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *f* | actual infiltration into the soil (ft/sec) |
-| *i* | rainfall intensity (ft/sec). |
-
-Thus for the case illustrated in Figure 4-2 runoff would be
-intermittent.
-
-![[]{#_Toc426447682 .anchor}**Figure 4‑2 The Horton infiltration
-curve**.](VolumeI/media/media/image16.png)
-
-Typical values for parameters *fo* and *f~∞~* are usually greater than
-typical rainfall intensities. Thus, when Equation 4-1 is used such that
-*fp* is a function of time only, the exponential term will cause
-*fp* to decrease even if rainfall intensities are very light, as
-sketched in Figure 4-2. This results in a reduction in infiltration
-capacity regardless of the actual amount of entry of water into the
-soil.
-
-To correct this problem, the integrated form of Horton's equation 4-1 is
-used in SWMM:
-
-+----------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+
-| > $$F\left( t_{p} \right) = \int_{0}^{t_{p}}{f_{p}dt = f_{\infty}t_{p} + \frac{\left( f_{0} - f_{\infty} \right)}{k_{d}}\left( 1 - e^{- k_{d}t_{p}} \right)}$$ | (4-3)      |
-+================================================================================================================================================================+============+
-
-where *F* is the cumulative infiltration capacity at time *tp* in
-feet. This function is plotted in Figure 4-3 where it is assumed that
-actual infiltration has been equal to *fp* over all time *t*. As noted
-before, there will in fact be times when infiltration *f* is less than
-*fp*, so that the true cumulative infiltration will be:
-
-+---------------------------------------------------------------------------+-----------------------------------+
-| > $$F(t) = \int_{0}^{t}{\min\left\lbrack f_{p},\ i \right\rbrack d\tau}$$ | (4-4)                             |
-+===========================================================================+===================================+
-
-![[]{#_Toc426447683 .anchor}**Figure 4‑3 Cumulative infiltration F as
-the area under the Horton curve.**](VolumeI/media/media/image17.png)
-
-Equations 4-3 and 4-4 can thus be used to define the time *tp* along
-the Horton curve at which the next value of *fp* can be found. That
-is, *F* is updated with the actual infiltration *f* over the current
-time step and then the following equation, with *tp* as the only
-unknown, is solved:
-
-+----------------------------------------------------------------------------------------------------------------+------------------------+
-| > $$F = f_{\infty}t_{p} + \frac{\left( f_{0} - f_{\infty} \right)}{k_{d}}\left( 1 - e^{- k_{d}t_{p}} \right)$$ | (4-5)                  |
-+================================================================================================================+========================+
-
-Once the new *tp* is known, the infiltration capacity *fp* for the
-next time step can be found from Equation 4-1.
-
-An additional optional parameter *Fmax* can be specified that limits
-the total volume of water that can infiltrate the soil. When cumulative
-infiltration exceeds this value, saturation conditions exist, and no
-more infiltration occurs; the land surface behaves as if it were
-impermeable. Thus *F(t)* in Equation 4-4 is not allowed to exceed
-*Fmax*.
-
-### 4.2.2 Recovery of Infiltration Capacity
-
-For simulations that consist of multiple storm events over a set period
-of time, infiltration capacity will be regenerated (recovered) during
-dry weather periods. With Horton's method, SWMM performs this function
-whenever a subcatchment is dry -- meaning it receives no precipitation
-and has no ponded surface water -- according to the hypothetical drying
-curve sketched in Figure 4-4:
-
-+--------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{p} = f_{0} - \left( f_{0} - f_{\infty} \right)e^{- k_{r}\left( t - t_{w} \right)}$$ | (4-6)                             |
-+============================================================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *kr* | decay coefficient for the recovery curve (sec-1) |
-| *tw* | hypothetical projected time at which *fp* = *f∞* on the recovery curve (sec). |
-
-New values of *tp* are then generated as indicated in Figure 4-4 as
-recovery proceeds. For example, let *tpr* be the *tp* value at which
-recovery begins with *fr* as the corresponding infiltration capacity.
-According to the recovery curve,
-
-+-------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{r} = f_{0} - \left( f_{0} - f_{\infty} \right)e^{- k_{r}\left( t_{pr} - t_{w} \right)}$$ | (4-7)                             |
-+=================================================================================================+===================================+
-
-one can compute *tw* as:
-
-+--------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$t_{w} = t_{pr} - \frac{1}{k_{r}}\ln\left( \frac{f_{0} - f_{\infty}}{f_{0} - f_{r}} \right)$$ | (4-8)                             |
-+==================================================================================================+===================================+
-
-![[]{#_Toc426447684 .anchor}**Figure 4‑4 Regeneration (recovery) of
-infiltration capacity during dry time
-steps.**](VolumeI/media/media/image18.png)
-
-Then after a recovery time to *tw1* = *tpr* + ∆*t*, the new
-infiltration capacity *f1* is found from:
-
-+-------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{1} = f_{0} - \left( f_{0} - f_{\infty} \right)e^{- k_{r}\left( t_{w1} - t_{w} \right)}$$ | (4-9)                             |
-+=================================================================================================+===================================+
-
-Finally, the new equivalent time *tp1* on the infiltration curve from
-which the infiltration process would re-start under a wet condition is:
-
-+-----------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$t_{p1} = \frac{1}{k_{d}}\ln\left( \frac{f_{0} - f_{\infty}}{f_{1} - f_{\infty}} \right)$$ | (4-10)                            |
-+===============================================================================================+===================================+
-
-These steps can be combined into the following equation:
-
-+---------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
-| > $$t_{p1} = \frac{1}{k_{d}}\ln\left\lbrack 1 - e^{- k_{r}\mathrm{\Delta}t}\left( 1 - e^{- k_{d}t_{pr}} \right) \right\rbrack$$ | (4-11)                        |
-+=================================================================================================================================+===============================+
-
-On succeeding time steps, *tp1* may be substituted for *tpr*, and
-*tp2* substituted for *tp1*, etc. Note that *fp* has reached its
-maximum value of *f0* when *tp* = *0*.
-
-Although this recovery method gives sensible results, it is somewhat
-unsatisfactory inasmuch as there is no dependence of infiltration
-recovery on evapotranspiration (ET). Drying of the soil through ET and
-deep infiltration should influence the recovery of infiltration
-capacity, but these mechanisms are replaced in SWMM by the more
-empirical approach just discussed.
-
-### 4.2.3 Computational Scheme
-
-The detailed computational scheme for computing Horton infiltration for
-each subcatchment within a study area over a single time step of a
-simulation is presented in the sidebar below.
-
-### 4.2.4 Parameter Estimates
-
-The parameters that a user must supply for each subcatchment for the
-Horton infiltration method are:
-
-> *f0* - the maximum or initial infiltration capacity (in/hr or
-> mm/hr),
->
-> *f~∞~* - the minimum or equilibrium infiltration capacity (in/hr or
-> mm/hr),
->
-> *kd* - the decay coefficient (hr-1),
->
-> *kr* - the regeneration coefficient (days-1), and, optionally,
->
-> *Fmax* - the maximum infiltration volume (in or mm).
-
-Conversions between the user-supplied units of these parameters (such as
-in, mm or hr) and those used internally (ft and sec) are handled
-automatically by the program.
-
-Although the Horton equation is probably the best-known of the several
-infiltration equations available, there is little to help the user
-select values of parame­ters *f0* and *kd* for a particular
-application. (Fortunately, some guidance can be found for the value of
-*f~∞~*.). Since the ac­tual values of *f0* and *kd* (and often
-*f~∞~*.) depend on the soil, vege­tation, and initial moisture content,
-ideally these parameters should be estimated using re­sults from field
-infiltrometer tests for a number of sites of the watershed and for a
-number of ante­cedent wetness conditions. An example of Horton parameters
-for Georgia soils is given in Table 4-2 (Rawls et al., 1976). Horton's
-(1940) estimates are shown in Table 4-3. Skaggs and Khaleel (1982)
-provide Horton-type decay curves on the basis of theoretical estimates.
-
-+-----------------------+--------------+--------------+---------------+
-| **Soil Type**         | **f~∞~**     | **fo**     | **kd**      |
-|                       |              |              |               |
-|                       | **in/hr**    | **in/hr**    | **hr-1**    |
-+:======================+:============:+:============:+:=============:+
-| Alpha loamy sand      | 1.40         | 19.0         | 38.29         |
-+-----------------------+--------------+--------------+---------------+
-| Carnegie sandy loam   | 1.77         | 14.77        | 19.64         |
-+-----------------------+--------------+--------------+---------------+
-| Cowarts loamy sand    | 1.95         | 15.28        | 10.65         |
-+-----------------------+--------------+--------------+---------------+
-| Dothan loamy sand     | 2.63         | 3.47         | 1.40          |
-+-----------------------+--------------+--------------+---------------+
-| Fuquay pebbly loamy   | 2.42         | 6.24         | 4.70          |
-| sand                  |              |              |               |
-+-----------------------+--------------+--------------+---------------+
-| Leefield loamy sand   | 1.73         | 11.34        | 7.70          |
-+-----------------------+--------------+--------------+---------------+
-| Robersdale loamy sand | 1.18         | 12.41        | 21.75         |
-+-----------------------+--------------+--------------+---------------+
-| Stilson loamy sand    | 1.55         | 8.11         | 6.55          |
-+-----------------------+--------------+--------------+---------------+
-| Tooup sand            | 1.80         | 23.01        | 32.71         |
-+-----------------------+--------------+--------------+---------------+
-
-: []{#_Toc430249148 .anchor}**Table 4‑2 Horton parameters for selected
-Georgia soils (Rawls et al., 1976)**
-
-+-----------------------------+---------------+-----------+------------+
-| **Soil and Cover**          | **f~∞~**      | **fo**  | **kd**   |
-|                             |               |           |            |
-|                             | **in/hr**     | **in/hr** | **hr-1** |
-+:============================+:=============:+:=========:+:==========:+
-| Standard agricultural       | 0.24 -- 8.9   | 11.4      | 96         |
-| (bare)                      |               |           |            |
-+-----------------------------+---------------+-----------+------------+
-| Standard agricultural       | 8.2 -- 11.8   | 36.7      | 48         |
-| (turfed)                    |               |           |            |
-+-----------------------------+---------------+-----------+------------+
-| Peat                        | 0.82 -- 11.8  | 13.3      | 108        |
-+-----------------------------+---------------+-----------+------------+
-| Fine sandy clay (bare)      | 0.82 -- 1.0   | 8.6       | 120        |
-+-----------------------------+---------------+-----------+------------+
-| Fine sandy clay (turfed)    | 4.1 -- 1.2    | 27.4      | 84         |
-+-----------------------------+---------------+-----------+------------+
-
-: []{#_Toc430249149 .anchor}**Table 4‑3 Horton parameters provided by
-Horton (1940)**
-
-If it is not possible to use field data to find estimates of *f0,
-f~∞~,* and *kd* for each subcatchment, the following guidelines should
-be helpful. Often, NRCS data may be used directly. For instance, for the
-two upper horizons (soil layers) of Woodburn silt loam (Figure 4-1),
-saturated hydraulic conductivity is listed as 4 - 14 micrometers per
-second, or 0.6 - 2.0 in/hr (14 - 50 mm/hr). Unfortunately, this wide
-range in values is commonly encountered among soil survey data.
-Fortunately, the range also serves as a reminder that infiltration rates
-are notoriously variable in space as well as in time and should not be
-considered "exact." Note that saturated hydraulic conductivity is the
-more appropriate word for parameter *Ks*, also termed "permeability"
-on older soil survey interpretation tables.
-
-[Minimum Infiltration Capacity (*f~∞~*)]{.underline}
-
-The Horton parameter *f~∞~* is essentially equal to saturated hydraulic
-conductivity, *Ks*, that is, *f~∞~ ≈ Ks*. The *f~∞~* value is also
-the limiting infiltration rate when water is ponded on the surface, at
-low depths. Generalized estimates for *Ks* will also be discussed in
-conjunction with the Green-Ampt infiltration method later in this
-chapter and are the best source of values for *f~∞~* in the absence of
-site-specific data.
-
-Alternatively, values for *f~∞~* according to Musgrave (1955) are given
-in Table 4-4. To help select a value within the range given for each
-soil group, the user should consider the texture of the layer of least
-hydraulic conduc­tivity in the profile. Depending on whether that layer
-is sand, loam, or clay, the *f~∞~* value should be chosen near the top,
-middle, and bottom of the range respectively. For example, the data
-sheet for Woodburn silt loam iden­tifies it as being in Hydrologic Soil
-Group B, which puts the estimate of *f~∞\ ~*into the range of 0.15 -
-0.30 in/hr (3.8 -7.6 mm/hr), much lower than the *Ks* value dis­cussed
-above. Examina­tion of the texture of the layers in the soil profile
-indicates that they are silty in nature, sug­gesting that the estimate of
-the *f~∞~* value should be in the low end of the range, say 0.15 - 0.20
-in/hr (3.8 - 5.1 mm/hr). A sensitivity test on the *f~∞~* value will
-indicate the importance of this parameter to the overall result; in
-fact, *f~∞~* is usually the most sensitive of the three Horton curve
-parameters.
-
-+-----------------------------------+----------------------------------+
-| **Hydrologic Soil Group**         | **f~∞~**                         |
-|                                   |                                  |
-|                                   | **(in/hr)**                      |
-+:==================================+:================================:+
-| A                                 | 0.45 - 0.30                      |
-+-----------------------------------+----------------------------------+
-| B                                 | 0.30 - 0.15                      |
-+-----------------------------------+----------------------------------+
-| C                                 | 0.15 - 0.05                      |
-+-----------------------------------+----------------------------------+
-| D                                 | 0.05 - 0                         |
-+-----------------------------------+----------------------------------+
-
-: []{#_Toc430249150 .anchor}**Table 4‑4 Values of f~∞~ for Hydrologic
-Soil Groups (Musgrave, 1955)**
-
-Caution should be used in applying values from Table 4-4 to sandy soils
-(group A) since reported *Ks* values are often much higher. For
-instance, sandy soils in Florida can have *Ks* values from 7 to 18
-in/hr (180 - 450 mm/hr) (Carlisle et al., 1981). Unless the water table
-rises to the surface, minimum infil­tration capacity will be very high,
-and rainfall rates will almost always be less than *f~∞~*, leading to
-little or no overland flow from such soils.
-
-[Decay Coefficient (*kd*)]{.underline}
-
-For any field infiltration test the rate of decrease (or "decay") of
-in­fil­tration capacity from the initial value depends on the initial
-moisture content. Thus the *kd*-value determined for the same soil
-will vary from test to test. It is postulated here that, if *f0* is
-always specified in relation to a particular soil moisture condition
-(e.g., dry), and for moisture contents other than this the time scale is
-changed accordingly (i.e., time "zero" is adjusted to correspond with
-the constant f0), then kd can be considered a constant for the soil
-independent of initial moisture content. Put another way, this means
-that infiltration curves for the same soil, but different antecedent
-condi­tions, can be made coincident if they are moved along the time
-axis. Butler (1957) makes a similar assumption.
-
-Values of *kd* found in the literature (Overton and Meadows, 1976;
-Wanielista, 1978; Maidment, 1993; ASCE, 1996) range from 0.67 to 120
-hr-1. Nevertheless most of the values cited appear to be in the range
-3 - 6 hr-1. The evidence is not clear as to whether there is any
-relationship between soil texture and the *kd* value although several
-pub­lished curves seem to indicate a lower value for sandy soils. If no
-field data are available, an estimate of 4 hr-1 could be used. Use of
-such an estimate implies that, under ponded conditions, the infiltra­tion
-capacity will fall 98 percent of the way towards its minimum value in
-the first hour, a not uncommon observation. Rates of decay of
-infiltration for several values of *kd* are shown in Table 4-5.
-
-+--------------------+-------------------------------------------------+
-| **kd,**          | **Percent of decline of infiltration capacity   |
-|                    | towards limiting value f~∞~ after 1 hour**      |
-| **hr-1**         |                                                 |
-+:==================:+:===============================================:+
-| 2                  | 76                                              |
-+--------------------+-------------------------------------------------+
-| 3                  | 95                                              |
-+--------------------+-------------------------------------------------+
-| 4                  | 98                                              |
-+--------------------+-------------------------------------------------+
-| 5                  | 99                                              |
-+--------------------+-------------------------------------------------+
-
-: []{#_Toc430249151 .anchor}**Table 4‑5 Rate of decay of infiltration
-capacity for different values of kd**
-
-[Initial Infiltration Capacity (*f0*)]{.underline}
-
-The initial infiltration capacity, *f0* depends primarily on soil
-type, initial moisture content, and surface vegetation conditions. For
-example, Linsley et al. (1982) present data that show, for a sandy loam
-soil, a 60 to 70 percent reduction in the *f0* value due to wet
-initial conditions. They also show that lower *f0* values apply for a
-loam soil than for a sandy loam soil. As to the effect of vegetation,
-Jens and McPherson (1964, pp. 20.20-20.38) list data that show that
-dense grass vegetation nearly doubles the infiltra­tion capacities over
-those measured for bare soil surfaces.
-
-For the assumption to hold that the decay coefficient *kd* is
-indepen­dent of initial moisture content, *f0* must be specified for
-the dry soil condition. For long-term continuous simulations SWMM
-automatically adjusts the effective *f0* value as part of the
-infiltration capacity regeneration routine. How­ever, for a single-event
-simulation, the user must specify the *f0* value for the storm in
-question, which may be less than the value for dry soil condi­tions.
-
-Published values of *f0* vary depending on the soil, moisture, and
-vegeta­tion conditions for the particular test measurement. The *f0*
-values listed in Table 4-6 can be used as a rough guide. Interpolation
-between the values may be required.
-
-+-----------------------------------------------------------------------+
-| A. DRY soils (with little or no vegetation):                          |
-|                                                                       |
-| > Sandy soils: 5 in/hr                                                |
-| >                                                                     |
-| > Loam soils: 3 in/hr                                                 |
-| >                                                                     |
-| > Clay soils: 1 in/hr                                                 |
-+:======================================================================+
-| B. DRY soils (with dense vegetation):                                 |
-|                                                                       |
-| > Multiply values given in A by 2 (after Jens and McPherson, 1964).   |
-+-----------------------------------------------------------------------+
-| C. MOIST soils (change from dry *f0* value required for single      |
-| event simulation only):                                               |
-|                                                                       |
-| > Soils which have drained but not dried out (i.e., field capacity):  |
-| > divide values from A and B by 3.                                    |
-| >                                                                     |
-| > Soils close to saturation: Choose value close to *f~∞~* value.      |
-| >                                                                     |
-| > Soils which have partially dried out: divide values from A and B by |
-| > 1.5-2.5.                                                            |
-+-----------------------------------------------------------------------+
-
-: []{#_Toc430249152 .anchor}**Table 4‑6 Representative values for f0**
-
-[Regeneration Coefficient (*kr*)]{.underline}
-
-For continuous simulation, infiltration capacity will be regenerated
-(recovered) during dry weather according to Equation 4-6. Instead of
-asking the user to supply a value for *kr*, SWMM instead asks for an
-estimate of drying time *Tdry* in days. This is the time it takes for
-a saturated soil to fully recover to a dry state. Drying times are
-typically longer than wetting times, implying *kr \< kd*. On
-well-drained porous soils (e.g., medium to coarse sands), recovery of
-infiltration capacity is quite rapid and could well be complete in a
-couple of days. For heavier soils, the recovery rate is likely to be
-slower, say 7 to 14 days. The choice of the value can also be related to
-the interval between a heavy storm and wilting of vegetation.
-
-The Green-Ampt method (discussed below in Section 4.4), bases its
-recovery time solely on the soil's saturated hydraulic conductivity
-*Ks*. Adopting its approach produces the following estimate for
-*Tdry* in days:
-
-+--------------------------------------------+-----------------------------------+
-| > $$T_{dry} = \frac{3.125}{\sqrt{K_{s}}}$$ | (4-12)                            |
-+============================================+===================================+
-
-where *Ks* is expressed in in/hr. Thus this equation predicts a drying
-time of 2 days for a sandy soil with *Ks* = 2.0 in/hr versus 10 days
-for a clay soil with *Ks* of 0.1 in/hr.
-
-Since mathematically, the exponential term in Equation 4-6 would require
-an infinite amount of time to allow infiltration capacity to return to
-its initial value *f0*, SWMM considers "full recovery" to occur when
-98 percent of the difference between the initial and minimum capacities
-has been achieved. Thus from Equation 4-6 (for *kr* in days-1),
-
-+---------------------------------------------------------------------------------------------------+-----------------------------+
-| > $$0.02\left( f_{0} - f_{\infty} \right) = \left( f_{0} - f_{\infty} \right)e^{- k_{r}T_{dry}}$$ | (4-13)                      |
-+===================================================================================================+=============================+
-
-which leads to the following estimate of *kr* expressed in days-1:
-
-+------------------------------------------------------------------+-----------------------------------+
-| > $$k_{r} = \frac{- ln(0.02)}{T_{dry}} = \frac{3.912}{T_{dry}}$$ | (4-14)                            |
-+==================================================================+===================================+
-
-This computation of *kr* from a user-supplied value of *Tdry* and
-its subsequent conversion from days-1 to sec-1 is done internally by
-SWMM.
-
-## 4.3 Modified Horton Method
-
-A. O. Akan developed a modified version of the Horton infiltration
-method (Akan, 1992; Akan and Houghtalen, 2003) that has been added as a
-separate infiltration option in SWMM 5. The method uses the same
-parameters as the original Horton method but instead of tracking the
-time along the Horton decay curve it uses the cumulative infiltration
-volume in excess of the minimum infiltration rate as its state variable.
-It assumes that part of the infiltrating water will percolate deeper
-into the soil at the minimum infiltration rate (commonly taken as the
-soil's saturated hydraulic conductivity). As a result, it is the
-difference between the actual and minimum infiltration rates that
-accumulates just below the surface that causes infiltration capacity to
-decrease with time. This method is purported to give more accurate
-infiltration estimates when low rainfall intensities occur.
-
-### 4.3.1 Governing Equations
-
-The modified method starts with the same exponential decay equation as
-the original Horton method:
-
-+--------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{p} = f_{\infty} + \left( f_{0} - f_{\infty} \right)e^{- k_{d}t}$$ | (4-15)                            |
-+==========================================================================+===================================+
-
-where all symbols have been previously defined.
-
-As with the original Horton method, the actual infiltration rate *f* is
-the smaller of *fp* and the rainfall rate *i*. Integrating Equation
-4-15 from 0 to time t produces the following equation for the cumulative
-infiltration through time t:
-
-+--------------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$F = f_{\infty}t + \frac{\left( f_{0} - f_{\infty} \right)}{k_{d}}\left( 1 - e^{- k_{d}t} \right)$$ | (4-16)                            |
-+========================================================================================================+===================================+
-
-Solving for $e^{- k_{d}t}$ from (4-15) and substituting into (4-16)
-gives:
-
-+-----------------------------------------------------+-----------------------------------+
-| > $$F = f_{\infty}t + \frac{f_{0} - f_{p}}{k_{d}}$$ | (4-17)                            |
-+=====================================================+===================================+
-
-and solving for *fp* gives:
-
-+----------------------------------------------+-----------------------------------+
-| > $$f_{p} = f_{0} - k_{d}(F - f_{\infty}t)$$ | (4-18)                            |
-+==============================================+===================================+
-
-The last term in parenthesis is equivalent
-to$\int_{0}^{t}{\left( f - f_{\infty} \right)dt}$. So one can
-approximate Eq. (4-18) by
-
-+------------------------------------+-----------------------------------+
-| > $$f_{p} = f_{0} - {k_{d}F}_{e}$$ | (4-19)                            |
-+====================================+===================================+
-
-where $F_{e} = \sum_{i}^{}{(f_{i} - f_{\infty})\mathrm{\Delta}t_{i}}$
-and $f_{i}$ is the actual infiltration over a previous time interval
-$\mathrm{\Delta}t_{i}$.
-
-### 4.3.2 Recovery of Infiltration Capacity
-
-Regarding recovery of infiltration capacity during dry periods, one can
-assume that the instantaneous recovery rate is proportional to the
-difference between the current capacity and the maximum capacity:
-
-+------------------------------------------------+-----------------------------------+
-| > $$\frac{df_{r}}{dt} = k_{r}(f_{0} - f_{r})$$ | (4-20)                            |
-+================================================+===================================+
-
-where $f_{r}$ represents the infiltration capacity during recovery and
-$k_{r}$ is the same regeneration coefficient (1/sec) used in the
-conventional Horton method. Integrating this equation starting at some
-time where the infiltration capacity is $f_{r0}$ produces the following
-result for the capacity after a recovery time of *t:*
-
-+----------------------------------------------------+-----------------------------------+
-| > $$f_{r} = f_{0} - (f_{0} - f_{r0})e^{- k_{r}t}$$ | (4-21)                            |
-+====================================================+===================================+
-
-From Eq. 4-19, the cumulative excess infiltration volume corresponding
-to this capacity,$F_{er}$, would be:
-
-+--------------------------------------+-----------------------------------+
-| > $$F_{er} = (f_{0} - f_{r})/k_{d}$$ | (4-22)                            |
-+======================================+===================================+
-
-and substituting 4-21 for $f_{r}$ gives:
-
-+------------------------------------------------------------------------+-----------------------------------+
-| > $$F_{er} = \frac{\left( f_{0} - f_{r0} \right)}{k_{d}}e^{- k_{r}t}$$ | (4-23)                            |
-+========================================================================+===================================+
-
-But again from 4-19,
-
-+--------------------------------------+-----------------------------------+
-| > $$(f_{0} - f_{r0})/k_{d} = F_{e}$$ | (4-24)                            |
-+======================================+===================================+
-
-so the new cumulative volume after recovery is simply:
-
-+-----------------------------------+-----------------------------------+
-| > $$F_{er} = F_{e}e^{- k_{r}t}$$  | (4-25)                            |
-+===================================+===================================+
-
-### 4.3.3 Computational Scheme
-
-The detailed computational scheme for computing the Modified Horton
-infiltration rate for each subcatchment within a study area over a
-single time step of a simulation is presented in the sidebar titled
-**[Computational Scheme for Modified Horton Infiltration]{.underline}**.
-
-### 4.3.4 Parameter Estimates
-
-Because the modified Horton method utilizes the same parameters as the
-original Horton method, the description in section 4.2.4 of how to
-estimate their values also applies to the modified method.
-
-## 4.4 Green-Ampt Method
-
-The Green-Ampt equation (Green and Ampt, 1911) has received considerable
-attention in recent years. The original equation was for infiltration
-with excess water at the surface at all times. Mein and Larson (1973)
-showed how it could be adapted to a steady rainfall input and proposed a
-way in which the capillary suction parameter could be determined. Chu
-(1978) has shown the applicability of the equation to the unsteady
-rainfall situation, using data for a field catchment. The Green-Ampt
-method was added into SWMM III in 1981 by R.G. Mein and W. Huber (Huber
-et al., 1981).
-
-### 4.4.1 Governing Equations
-
-The Green-Ampt conceptualization of the infiltration process is one in
-which infiltrated water moves vertically downward in a saturated layer,
-beginning at the surface (Figure 4-5). In the wetted zone the moisture
-content *θ* is at saturation *θ s* while the moisture content in the
-un-wetted zone is at some known initial level *θ i*.
-
-[]{#_Toc426447685 .anchor}**Figure 4‑5 Two-zone representation of the
-Green-Ampt infiltration model (after Nicklow et al., 2006).**
-
-The water velocity within the wetted zone is given by Darcy's Law as a
-function of the saturated hydraulic conductivity *Ks*, the capillary
-suction head along the wetting front *ψs*, the depth of ponded water
-at the surface *d*, and the depth of the saturated layer below the
-surface *Ls*:
-
-+----------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{p} = K_{s}\left\lbrack \frac{d + L_{s} + \psi_{s}}{L_{s}} \right\rbrack$$ | (4-26)                            |
-+==================================================================================+===================================+
-
-The depth of the saturated layer *Ls* can be expressed in terms of the
-cumulative infiltration, *F*, and the initial moisture deficit to be
-filled below the wetting front, *θ d* = *θ s - θi* as
-![](VolumeI/media/media/image20.wmf). Substituting this into Equation 4-26 and
-assuming that *d* is small compared to the other depths gives the
-Green-Ampt equation for saturated conditions:
-
-+--------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{p} = K_{s}\left\lbrack 1 + \frac{\psi_{s}\theta_{d}}{F} \right\rbrack$$ | (4-27)                            |
-+================================================================================+===================================+
-
-Equation 4-27 applies only after a saturated layer develops at the
-ground surface. Prior to this point in time the infiltration capacity
-will equal the rainfall intensity:
-
-+-----------------------------------+-----------------------------------+
-| > $$f_{p} = i$$                   | (4-28)                            |
-+===================================+===================================+
-
-As time increases, one can test whether saturation has been reached by
-solving 4-27 for *F* (which will be denoted as *Fs*) with *fp* set
-equal to *i* and check if this value equals or exceeds the actual
-cumulative infiltration *F*:
-
-+---------------------------------------------------------+-----------------------------------+
-| > $$F_{s} = \frac{K_{s}\psi_{s}\theta_{d}}{i - K_{s}}$$ | (4-29)                            |
-+=========================================================+===================================+
-
-Note that there is no calculation of *Fs* when *i \<= Ks*, although
-*F* still gets updated during such periods. Finally, in this scheme the
-actual infiltration *f* is the same as the potential value *fp*:
-
-+-----------------------------------+-----------------------------------+
-| > $$f = f_{p}$$                   | (4-30)                            |
-+===================================+===================================+
-
-The two equations are illustrated in Figure 4-6 for the situation *Ks*
-= 0.25 in/hr, *ψs* = 6.5 in, and *θd* = 0.20. The initial, flat
-portion of the curve corresponds to *f = i*, up to the point where *F =
-Fs* (Equation 4-29). The remainder of the curve corresponds to the
-potential rate computed with Equation 4-27. Note that the infiltration
-rate approaches *Ks* (0.25 in/hr) asymptotically.
-
-![[]{#_Toc426447686 .anchor}**Figure 4‑6 Illustration of infiltration
-capacity as function of cumulative infiltration for the Green-Ampt
-method.**](VolumeI/media/media/image21.emf){width="5.114583333333333in"
-height="3.09375in"}
-
-Equation 4-27 shows that the infiltration capacity after surface
-saturation depends on the infiltrated volume, which in turn depends on
-the infiltration rates in previous time steps. To avoid numerical errors
-over long time steps, the integrated form of the Green-Ampt equation is
-more suitable. That is, *fp* is replaced by *dF/dt* and integrated to
-obtain:
-
-+----------------------------------------------------------------------------------------+-----------------------------------+
-| > $$F = K_{s} + \psi_{s}\theta_{d}\ln\left( 1 + \frac{F}{\psi_{s}\theta_{d}} \right)$$ | (4-31)                            |
-+========================================================================================+===================================+
-
-If *F1* is the known cumulative infiltration at the start of the time
-step and *F2* the unknown cumulative infiltration at the end of the
-time step then one can write:
-
-+----------------------------------------------------------------------------------+-----------------------------------+
-| > $$F_{2} = C + \psi_{s}\theta_{d}\ln\left( F_{2} + \psi_{s}\theta_{d} \right)$$ | (4-32)                            |
-+==================================================================================+===================================+
-
-where
-$C = K_{s}\Delta t + F_{1} - \psi_{s}\theta_{d}\ln\left( F_{1} + \psi_{s}\theta_{d} \right)$
-is a known constant. Equation 4-32 can be solved numerically for *F2*.
-The average infiltration capacity *fp* over the time step can then be
-computed as $\left( F_{2} - F_{1} \right)/\Delta t$.
-
-### 4.4.2 Recovery of Infiltration Capacity
-
-Evaporation, subsurface drainage, and moisture redistribution between
-rainfall events decrease the soil moisture content in the upper soil
-zone and increase the infiltration capacity of the soil. The processes
-involved are complex and depend on many factors. In SWMM a simple
-empirical routine (Huber et al., 1981) is used as outlined below;
-commonly used units are given in the equations to make the description
-easier to understand. Note that this procedure suffers from the same
-lack of relationship to ET as does the Horton recovery, discussed
-earlier.
-
-Infiltration is usually dominated by conditions in the uppermost layer
-of the soil. The thickness of this layer depends on the soil type; for a
-sandy soil it could be several inches, for heavy clay it would be less.
-The equation used to determine the thickness of the layer *Lu* is:
-
-+-----------------------------------+-----------------------------------+
-| > $$L_{u} = 4\sqrt{K_{s}}$$       | (4-33)                            |
-+===================================+===================================+
-
-where *Lu* has units of inches and *Ks* is expressed in in/hr. Thus
-for a high *Ks* of 0.5 in/hr (12.7 mm/hr) the thickness computed by
-Equation 4-33 is 2.83 inches (71.8 mm). For a soil with a low hydraulic
-conductivity, say *Ks* = 0.1 in/hr (2.5 mm/hr), the computed thickness
-is 1.26 inches (32.1 mm). This constant thickness is different from the
-saturated zone thickness *Ls* shown in Figure 4-5 which grows over
-time as infiltration proceeds.
-
-In the Green-Ampt model, the initial soil moisture deficit at the start
-of a rainfall event determines how much infiltration capacity is
-available during the event itself. Recall that the moisture deficit
-*θd* is the difference between the saturated moisture content *θs*
-and the initial moisture content *θi*. During a dry period the
-moisture deficit in the upper soil zone, *θdu*, is regenerated, i.e.,
-its value is increased. Thus SWMM keeps continuous track of this
-quantity. At the start of a simulation, *θdu* is set equal to the
-user-supplied initial value of *θdmax*. During a wet period when
-infiltration occurs at a rate *f* over a time step of *∆t*, *θdu* is
-decreased according to:
-
-+--------------------------------------------------------------------+-----------------------------------+
-| > $$\theta_{du} \leftarrow \theta_{du} - \frac{f\Delta t}{L_{u}}$$ | (4-34)                            |
-+====================================================================+===================================+
-
-down to a possible limiting value of 0. During a dry period it increases
-as follows:
-
-+-----------------------------------------------------------------------+-----------------------------------+
-| > $$\theta_{du} \leftarrow \theta_{du} + k_{r}\theta_{dmax}\Delta t$$ | (4-35)                            |
-+=======================================================================+===================================+
-
-up to a maximum possible value of *θdmax* , where *kr* is a recovery
-constant (hr-1).
-
-One can assume that the recovery constant is also dependent on *Ks*,
-such that tight, clay soils with low *Ks* take longer to recover than
-do loose, sandy soils with high *Ks*. The following relationship is
-used for *kr*:
-
-+---------------------------------------+-----------------------------------+
-| > $$k_{r} = \frac{\sqrt{K_{s}}}{75}$$ | (4-36)                            |
-+=======================================+===================================+
-
-where the constant 75 has units of (in-hr)1/2. Note that the time it
-would take a fully saturated soil to recovery to its maximum capacity is
-simply:
-
-+---------------------------------------------------+-----------------------------------+
-| > $$\frac{1}{k_{r}} = \frac{75}{\sqrt{K_{s}}}\ $$ |                                   |
-+===================================================+===================================+
-
-hours (or $3.125/\sqrt{K_{s}}$ days).
-
-To complete the recovery process it is necessary to define the minimum
-amount of time that a soil must remain in recovery before any further
-rainfall would be considered as an independent event. This time *Tr*
-(hr) is computed as:
-
-+-------------------------------------------------------------+-----------------------------------+
-| > $$T_{r} = \frac{0.06}{k_{r}} = \frac{4.5}{\sqrt{K_{s}}}$$ | (4-37)                            |
-+=============================================================+===================================+
-
-Thus when a new period of rainfall occurs after a recovery interval of
-at least *Tr* hours, the two-stage Green-Ampt infiltration process is
-re-started with *θd* = *θdu* and *F* = 0. Figure 4-7 summarizes the
-functional dependence of the three internally computed recovery
-parameters *Lu*, *kr*, and *Tr* on the saturated hydraulic
-conductivity *Ks*.
-
-![[]{#_Toc426447687 .anchor}**Figure 4‑7 Green-Ampt recovery parameters
-as functions of hydraulic
-conductivity.**](VolumeI/media/media/image22.emf){width="6.0in"
-height="3.9270833333333335in"}
-
-### 4.4.3 Computational Scheme
-
-The detailed computational scheme for computing the Green-Ampt
-infiltration rate for each subcatchment within a study area over a
-single time step of a simulation is presented in the sidebar below.
-
-### 4.4.4 Parameter Estimates
-
-The soil parameters that a user must supply for each subcatchment for
-the Green-Ampt infiltration method are:
-
-- *Ks* - the saturated hydraulic conductivity (in/hr or mm/hr),
-
-- *ψs* - the suction head at the wetting front (in or mm),
-
-- *θdmax* - the maximum moisture deficit available (volume of dry
-  voids per volume of soil).
-
-Conversions between the user-supplied units of these parameters (in (or
-mm) and hr) and those used internally (ft and sec) are handled
-automatically by the program.
-
-[Saturated Hydraulic Conductivity (*Ks*)]{.underline}
-
-Probably the best single source for estimates of saturated hydraulic
-conductivity (*Ks*) and suction head (*ψs*) for a wide range of
-soils -- and one that makes use of the Green-Ampt method relatively
-attractive -- is the data by Rawls et al. (1983), shown in Table 4-7.
-These data were derived from measurements made on roughly 5000 soils
-across the United States and while they will never be truly site
-specific, they are certainly consistent and defensible. Although there
-is considerable variation in the parameter estimates, a good first
-approximation may be made using the table. Values of hydraulic
-conductivity may also be used for estimates of the Horton parameter
-*f~∞~*. But the range of values shown for porosity and suction head (the
-authors do not provide ranges for *Ks*) should be a warning about
-placing too much faith in such generalized estimates.
-
-The NRCS Soil Survey Physical Data (see Figure 4-1) values for hydraulic
-conductivity could also be used as a preliminary estimate. A better
-guide for the *Ks* values is as given for parameter *f~∞~* for the
-Horton equation; theoreti­cally these parameters (i.e., *f~∞~* and
-*Ks*) should be equal for the same soil. Note that, in general, the
-range of *Ks* values encountered will be of the order of tenths of an
-inch per hour.
-
-Another source of conductivity estimates is the regression equation
-developed by Saxton and Rawls (2006) that predicts *Ks* from the sand,
-clay and organic matter content of a soil. See Section 5.5.2 of the
-Groundwater chapter for more details.
-
-[]{#_Toc430249153 .anchor}**Table 4‑7 Green-Ampt parameters for
-different soil classes (Rawls et al., 1983)**
-
-(Numbers in parentheses are ± one standard deviation from the parameter
-value shown.)
-
-+-------------+----------------+----------------+---------------+-------------------+
-| **Soil      | **Porosity,    | **Effective**  | **Wetting     | **Saturated**     |
-| Class**     | φ**            |                | Front**       |                   |
-|             |                | **Porosity,    |               | **Hydraulic**     |
-|             |                | φ*e*\***   | **Suction     |                   |
-|             |                |                | Head,**       | **Conductivity,** |
-|             |                |                |               |                   |
-|             |                |                | ***ψs*      | ***Ks*          |
-|             |                |                | (in)**        | (in/hr)**         |
-+=============+:==============:+:==============:+:=============:+:=================:+
-| Sand        | 0.437          | 0.417          | 1.95          | 4.74              |
-|             |                |                |               |                   |
-|             | (0.374--0.500) | (0.354--0.480) | (0.38--9.98)  |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Loamy sand  | 0.437          | 0.401          | 2.41          | 1.18              |
-|             |                |                |               |                   |
-|             | (0.363--0.506) | (0.329--0.473) | (0.53--11.00) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Sandy loam  | 0.453          | 0.412          | 4.33          | 0.43              |
-|             |                |                |               |                   |
-|             | (0.351--0.555) | (0.283--0.541) | (1.05--17.90) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Loam        | 0.463          | 0.434          | 3.50          | 0.13              |
-|             |                |                |               |                   |
-|             | (0.375--0.551) | (0.334--0.534) | (0.52--23.38) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Silt loam   | 0.501          | 0.486          | 6.57          | 0.26              |
-|             |                |                |               |                   |
-|             | (0.420--0.582) | (0.394--0.578) | (1.15--37.56) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Sandy clay  | 0.398          | 0.330          | 8.60          | 0.06              |
-|             |                |                |               |                   |
-| loam        | (0.332--0.464) | (0.235--0.425) | (1.74--42.52) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Clay loam   | 0.464          | 0.309          | 8.22          | 0.04              |
-|             |                |                |               |                   |
-|             | (0.409--0.519) | (0.279--0.501) | (1.89--35.87) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Silty clay  | 0.471          | 0.432          | 10.75         | 0.04              |
-|             |                |                |               |                   |
-| loam        | (0.418--0.524) | (0.347--0.517) | (2.23--51.77) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Sandy clay  | 0.430          | 0.321          | 9.41          | 0.02              |
-|             |                |                |               |                   |
-|             | (0.370--0.490) | (0.207--0.435) | (1.61--55.20) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Silty clay  | 0.479          | 0.423          | 11.50         | 0.02              |
-|             |                |                |               |                   |
-|             | (0.425--0.533) | (0.334--0.512) | (2.41--54.88) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-| Clay        | 0.475          | 0.385          | 12.45         | 0.01              |
-|             |                |                |               |                   |
-|             | (0.427--0.523) | (0.269--0.501) | (2.52--61.61) |                   |
-+-------------+----------------+----------------+---------------+-------------------+
-
-\*Effective porosity is the difference between the porosity *φ* and the
-residual moisture content *φr* that remains after a saturated soil is
-allowed to drain thoroughly.
-
-Urban soils are usually highly disturbed (Pitt et al., 1999, 2001; Pitt
-and Voorhees, 2000). Construction has often occurred on or nearby the
-locations in question, and soils may be compacted from their natural
-state. Alternatively, soils are sometimes imported for horticultural
-purposes. Such imported soils (e.g., for lawns) may exhibit relatively
-high infiltration rates. The parameter estimates discussed previously
-are based on data for *undisturbed* soils, e.g., using Natural Resources
-Conservation Service (NRCS) data. Parameters for natural, undisturbed
-soils are likely to *overestimate* the infiltration characteristics for
-urban soils. Modelers should bear in mind that only site-specific
-infiltrometer and/or soil physics tests can determine local infiltration
-properties, and that high spatial variability is the rule, rather than
-the exception.
-
-[Suction Head (*ψs*)]{.underline}
-
-The suction head, *ψs *(also referred to as capillary tension), is
-perhaps the most difficult parame­ter to measure. It can be derived from
-soil moisture - conductivity data (Mein and Larsen, 1973) of the type
-shown in Figures 5-5 in Chapter 5 for groundwater. Unfortunately, such
-detailed data are rare for most soils. Fortunately the results obtained
-for Green-Ampt infiltration are not highly sensitive to the estimate of
-*ψs* (Brakensiek and Onstad, 1977).
-
-An excellent local data source can often be found in Soil Science
-departments at state universities. Tests are run on a variety of soils
-found within the state, including soil moisture versus soil tension
-data, from which *ψs* can be derived. For example, Carlisle et al.
-(1981) provide such data for Florida soils along with information on
-*Ks*, bulk density, and other physical and chemical properties.
-
-Approximate values may also be found from several authors: Mein and
-Larsen (1973), Brakensiek and Onstad (1977), Clapp and Hornberger
-(1978), Chu (1978), Rawls et al. (1983). Published values vary
-considerably and conflict; however, a range of 2 to 15 inches (50 to 380
-mm) covers virtually all soil textures. But as with *Ks*, probably the
-best single source for estimates for capillary suction (*ψs*) is the
-data by Rawls et al. (1983) listed in Table 4-7. Brakensiek et al.
-(1981) noted that *ψs* was highly correlated with hydraulic
-conductivity over all soil classes. Using nonlinear regression on the
-average values for these two variables listed in Table 4-7 produces the
-following relationship for *KS* in in/hr and *ψs* in inches:
-
-+----------------------------------------------+-----------------------+
-| > $\psi_{s} = 3.237K_{S}^{- 0.328}$ (*R2*  | (4-38)                |
-| > = 0.9)                                     |                       |
-+==============================================+=======================+
-
-[Maximum Moisture Deficit (*θdmax*)]{.underline}
-
-The maximum moisture deficit, *θdmax* is defined as the difference
-between the moisture content at saturation and at the start of the
-simulation. Because this parameter is the most sensitive of the three
-parameters for estimates of runoff from pervious areas (Brakensiek and
-Onstad, 1977), some care should be taken in deter­mining the best
-*θdmax* value to use. The saturated moisture content is approximately
-equal to the soil's porosity *φ* (i.e., the fraction of voids), assuming
-one ignores the 5 - 10% of trapped air that typically exists at
-saturation. After a saturated soil is allowed to drain thoroughly, the
-residual moisture content that remains is *φr*. The effective porosity
-*φe* is defined as ![](VolumeI/media/media/image23.wmf)and can be used to
-represent *θdmax* for dry antecedent conditions. Typical values of
-*φe* are included in the Rawls et al. (1983) data set listed in Table
-4-7.
-
-Sandy soils tend to have lower porosities than clay soils, but drain to
-lower moisture contents between storms because the water is not held so
-strongly in the soil pores. Conse­quently, values of *θdmax* for dry
-antecedent conditions tend to be higher for sandy soils than for clay
-soils. Table 4-8, derived from Clapp and Hornberger (1973), is another
-source of *θdmax* values for various soil types.
-
-| Soil Texture | Typical *θdmax* at Soil Wilting Point |
-| --- | --- |
-| Sand | 0.34 |
-| Sandy Loam | 0.33 |
-| Silt Loam | 0.32 |
-| Loam | 0.31 |
-| Sandy Clay Loam | 0.26 |
-| Clay Loam | 0.24 |
-| Clay | 0.21 |
-
-  : []{#_Toc430249154 .anchor}**Table 4‑8 Typical values of *θ*dmax
-  for various soil types.**
-
-These *θdmax* values would be suitable for input for long term
-continuous simulation; the soil type selected should correspond to the
-surface layer for the particu­lar sub­catchment. For single event
-simulation the values of Table 4-8 would apply only to very dry
-antecedent conditions. For moist or wet antecedent conditions lower
-values of *θdmax* should be used. When estimating the particular value
-it should be borne in mind that sandy soils drain more quickly than
-clayey soils, i.e., for the same time since the previous event, the
-*θdmax* value for a sandy soil will be closer in value to that of
-Table 4-8 than it would be for a clayey soil.
-
-Another estimate for *θdmax* may be based on the NRCS Soil Survey
-Physical Data as "Available Moisture Capacity" in/in of soil
-(dimensionless fraction), which is defined as the difference between
-field capacity and the wilting point. Thus, it is an underestimate of
-the maximum *θd* value. Furthermore, Available Moisture Capacity
-values listed may exhibit similar variability (or lack thereof) as for
-hydraulic conductivity estimates discussed earlier, but these values are
-at least specific to the soil in question. For instance, for the
-Woodburn silt loam illustrated in Figure 4-1, *θdmax* might be at the
-high end of the range of 0.19 -- 0.24 for the surface layer
-(considerably less than the generic value of 0.32 for silt loam in Table
-4-8 or the range of 0.394 to 0.578 given in Table 4-7).
-
-Finally, the initial moisture deficit can be related to another very
-general measure of a soil: its storage capacity, S, which can be
-expressed as:
-
-+-----------------------------------+-----------------------------------+
-| > $$S = d_{wt}\theta_{dmax}$$     | (4-39)                            |
-+===================================+===================================+
-
-where *dwt* is the depth to the sub-surface water table. Estimates of
-soil storage capacity, *S*, are available using the Curve Number method,
-discussed below. That is, *S* is a function of the curve number (Section
-4.5.4), for which a vast literature is available. If depth to water
-table is known, or if typical depths are given for a soil on its Soil
-Survey Interpretation data, then Equation 4-39 may be solved for
-*θdmax*.
-
-## 4.5 Curve Number Method
-
-The Curve Number infiltration method is new to SWMM 5. It is based on
-the widely used SCS (Soil Conservation Service, now known as the NRCS --
-Natural Resource Conservation Service) curve number method for
-evaluating rainfall excess. First developed in 1954, the method is
-embodied in the widely used TR-20 and TR-55 computer models (NRCS, 1986)
-as well as most hydrology handbooks and textbooks (e.g., Bedient et al.,
-2013). It was added into SWMM to take advantage of its familiarity to
-most practicing engineers and the availability of tabulated curve
-numbers for a wide range of land use and soil groups. The original curve
-number method is a combined loss method that lumps together all losses
-due to interception, depression storage, and infiltration to predict the
-total rainfall excess from a rainfall event. The SWMM uses a modified,
-incremental form of the method that accounts only for infiltration
-losses, since the other abstractions are modeled separately. Other
-incremental applications of the curve number method have been proposed
-by Chen (1975), Aron et al. (1977) and Akan and Houghtalen (2003).
-
-### 4.5.1 Governing Equations
-
-In its classic form, the Curve Number model uses the following equation
-to relate total event runoff *Q* (in) to total event precipitation *P*
-(in) (Haan et al., 1994; McCuen, 1998; Bedient et al., 2013; NRCS,
-2004b):
-
-+--------------------------------------+-----------------------------------+
-| > $$Q = \frac{P^{2}}{P + S_{\max}}$$ | (4-40)                            |
-+======================================+===================================+
-
-where *Smax* = the soil's maximum moisture storage capacity (inches).
-*Smax* can also be thought of as the difference in water volume
-contained in a fully saturated soil versus a fully drained soil. In this
-sense it is similar to the maximum moisture deficit parameter *θdmax*
-used in the Green-Ampt model, except it is expressed on a volumetric
-basis rather than as a fraction (see Equation 4-39). *Smax* is derived
-from a tabulated "curve number" *CN* that varies with soil type and
-antecedent conditions:
-
-+---------------------------------------+-----------------------------------+
-| > $$S_{\max} = \frac{1000}{CN} - 10$$ | (4-41)                            |
-+=======================================+===================================+
-
-It should be emphasized that Equation 4-40 and subsequent equations use
-units of [inches]{.underline}. Curve numbers for various soil types and
-land covers are tabulated in the NRCS's National Engineering Handbook
-(NRCS, 2004a) and in many text books.
-
-In the formal SCS method, Equation 4-40 is written with *P* replaced by
-*P -- Ia* where *Ia* is an initial abstraction (in) that accounts
-for the volume of rainfall captured by vegetative interception, filling
-of depression storage, and initial soil wetting. Because SWMM already
-accounts for these phenomena through its depression storage parameter,
-*dp*, this refinement is not included here.
-
-Assuming that all rainfall that does not run off is lost to infiltration
-(i.e., *P -- Q = F*), Equation 4-40 can be extended to predict total
-(cumulative) infiltration *F* (in) as:
-
-+------------------------------------------+-----------------------------------+
-| > $$F = P - \frac{P^{2}}{P + S_{\max}}$$ | (4-42)                            |
-+==========================================+===================================+
-
-For a continuous model like SWMM, Equation 4-42 can be applied in an
-incremental fashion to compute an infiltration rate *f* at each time
-step. Let *P1* and *F1* be the cumulative precipitation and
-infiltration, respectively, at the start of the time step. At the end of
-the time step:
-
-+-----------------------------------+-----------------------------------+
-| > $$P_{2} = P_{1} + i\Delta t$$   | (4-43)                            |
-+===================================+===================================+
-
-and
-
-+-------------------------------------------------------+-----------------------------------+
-| > $$F_{2} = P_{2} - \frac{P_{2}^{2}}{P_{2} + S_{e}}$$ | (4-44)                            |
-+=======================================================+===================================+
-
-where *P2* and *F2* are the cumulative precipitation and
-infiltration values, respectively, at the end of a time step *∆t* (hr),
-*i* (in/hr) is the rainfall rate over the time step, and *Se* is the
-moisture storage capacity at the start of the rainfall event to which
-the time step belongs. For a single event simulation, *Se* equals
-*Smax *but may be lower when moisture storage capacity depletion and
-recovery occur over a longer simulation period as discussed in the next
-section.
-
-The infiltration rate *f* (ft/sec) can then be computed as:
-
-+-------------------------------------------------+-----------------------------------+
-| > $$f = \left( F_{2} - F_{1} \right)/\Delta t$$ | (4-45)                            |
-+=================================================+===================================+
-
-and the cumulative values get updated to *P1 = P2* and *F1 = F2*
-to prepare for the next time step. Note that as it stands, this model
-would not allow for any infiltration of ponded water when there is a
-period of no rainfall within an event. To overcome this limitation it is
-assumed that the infiltration rate for such periods remains the same as
-in the immediately preceding period. Also, when overland flow re-routing
-occurs (see Section 3.6), the rainfall rate *i* in Equation 4-43 does
-not include the additional re-routed flow.
-
-### 4.5.2 Recovery of Storage Capacity
-
-As with the other infiltration methods discussed, a soil's moisture
-storage capacity is depleted during wet periods and replenished during
-dry periods. To model this behavior with the Curve Number method, the
-variable *S* is introduced to track the remaining storage capacity
-(i.e., moisture deficit) over time. It is analogous to the state
-variable *θdu* used in the Green-Ampt method. Initially, *S = Smax*.
-Whenever infiltration at rate *f* occurs over a time step *∆t*, *S* is
-reduced by *f∆t*. During a period with no infiltration *S* is assumed to
-be replenished at a rate proportional to *Smax*:
-
-+------------------------------------------------------+-----------------------------------+
-| > $$S \leftarrow S + k_{r}S_{\max}\mathrm{\Delta}t$$ | (4-46)                            |
-+======================================================+===================================+
-
-where *kr* is a storage capacity recovery constant (hr-1). This
-recovery expression has the same form as used in the Green-Ampt model
-and the coefficient *kr* has a similar meaning in both models.
-
-Because the Curve Number method was originally meant to be applied to
-single, discrete rainfall events, a mechanism is needed to define when
-separate events occur. At the start of a new event, the cumulative
-variables *P* and *F* are reset to 0 and *Se* is set equal to the
-current remaining storage capacity *S*. Once again borrowing from the
-Green-Ampt method, a period of *Tr* hours without rainfall must occur
-before the next rainfall period is deemed to begin a new event. *Tr*
-is assumed to be related to the recovery constant *kr* through
-Equation 4-25 which is repeated here:
-
-+-----------------------------------+-----------------------------------+
-| > $$T_{r} = \frac{0.06}{k_{r}}$$  | (4-47)                            |
-+===================================+===================================+
-
-### 4.5.3 Computational Scheme
-
-The detailed computational scheme for computing Curve Number
-infiltration for each subcatchment within a study area over a single
-time step of a simulation is presented in the sidebar below.
-
-### 4.5.4 Parameter Estimates
-
-There are only two parameters required for each subcatchment using the
-Curve Number infiltration method:
-
-- the curve number
-
-- the drying time (i.e., the time it takes a fully saturated soil to
-  recover to a dry state).
-
-The curve number is used to compute the maximum soil moisture storage
-capacity (*Smax*) using Equation 4-41. The drying time *Tdry* in
-days is used to compute the regeneration constant *kr* in hours-1
-as:
-
-+-----------------------------------+-----------------------------------+
-| > $$k_{r} = \frac{1}{24T_{dry}}$$ | (4-48)                            |
-+===================================+===================================+
-
-The minimum inter-event recovery time *Tr* is then computed from
-*kr* using Equation 4-47.
-
-A highly structured method for estimating curve numbers is provided by
-the NRCS (NRCS, 2004a; McCuen, 1998, Bedient et al., 2013 and virtually
-every hydrology text). Such estimates are embedded in engineering
-practice through Table 4-9 in which curve number values are given as
-function of land use and soil Hydrologic Soil Group (A through D).
-Hydrologic Soil Group is provided on the NRCS Soil Survey data discussed
-in Section 4.1. For instance, the Woodburn silt loam of Figure 4-1 is in
-Hydrologic Soil Group B.
-
-There are several things to keep in mind when using curve numbers from
-Table 4-9. First, these curve numbers apply only to normal antecedent
-moisture conditions (AMC II). For AMC I (low moisture) or AMC III (high
-moisture) the following adjustments can be made to the tabulated values
-(NRCS, 2004a):
-
-+-------------------------------------------------------+-----------------------------------+
-| > $$CN_{I} = \frac{4.2CN_{II}}{10 - 0.058{CN}_{II}}$$ | (4-49)                            |
-+=======================================================+===================================+
-
-+-----------------------------------------------------------+-----------------------------------+
-| > $${CN}_{III} = \frac{23{CN}_{II}}{10 - 0.13{CN}_{II}}$$ | (4-50)                            |
-+===========================================================+===================================+
-
-where *CNi* refers to the curve number for antecedent moisture
-condition *i*. For long-term simulations the AMC I curve number should
-be used to allow the soil to reach its maximum possible moisture
-retention capacity during extended dry periods.
-
-Second, the urban land use descriptions included in Table 4-9 lump
-together the pervious and impervious portions of the subcatchment area
-to which a curve number is assigned. This means that the subcatchment in
-question must be modeled as being completely pervious, with no
-partitioning into separate pervious and impervious areas as is normally
-done in SWMM (refer to Section 3.3). Otherwise too much runoff will be
-generated. If one wants to continue to partition their subcatchments
-into pervious and impervious areas, they will have to either adjust the
-curve numbers taken from Table 4-9 to remove the effects of
-imperviousness or find another source of curve numbers, such as from
-calibration against field measurements (see Shuster and Pappas, 2011).
-
-[]{#_Toc430249155 .anchor}**Table 4‑9 Runoff curve numbers for selected
-land uses (NRCS, 2004a)**
-
-(For antecedent moisture condition II)
-
-+--------------------------------------------------+-----------------------------------+
-|                                                  | Hydrologic Soil Group             |
-+=======================+==========================+:======:+:======:+:======:+:======:+
-| Land Use Description                             | A      | B      | C      | D      |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Cultivated land1                               |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Without conservation treatment                   | 72     | 81     | 88     | 91     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| With conservation treatment                      | 62     | 71     | 78     | 81     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Pasture or range land                            |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Poor condition                                   | 68     | 79     | 86     | 89     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Good condition                                   | 39     | 61     | 74     | 80     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Meadow                                           |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Good condition                                   | 30     | 58     | 71     | 78     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Wood or forest land                              |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Thin stand, poor cover, no mulch                 | 45     | 66     | 77     | 83     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Good cover2                                    | 25     | 55     | 70     | 77     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Open spaces, lawns, parks, golf courses,         |        |        |        |        |
-| cemeteries, etc.                                 |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Good condition: grass cover on 75% or more of    | 39     | 61     | 74     | 80     |
-| the area                                         |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Fair condition: grass cover on 50 -- 75% of the  | 49     | 69     | 79     | 84     |
-| area                                             |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Commercial and business areas (85% impervious)   | 89     | 92     | 94     | 95     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Industrial districts (72% impervious)            | 81     | 88     | 91     | 93     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Residential3                                   |        |        |        |        |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| Average lot size      | Average % impervious4  |        |        |        |        |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| 1/8 ac or less        | 65                       | 77     | 85     | 90     | 92     |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| 1/4 ac                | 38                       | 61     | 75     | 83     | 87     |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| 1/3 ac                | 30                       | 57     | 72     | 81     | 86     |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| 1/2 ac                | 25                       | 54     | 70     | 80     | 85     |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| 1 ac                  | 20                       | 51     | 68     | 79     | 84     |
-+-----------------------+--------------------------+--------+--------+--------+--------+
-| Paved parking lots, roofs, driveways, etc.5    | 98     | 98     | 98     | 98     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Streets and roads                                |        |        |        |        |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Paved with curbs and storm sewers5             | 98     | 98     | 98     | 98     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Gravel                                           | 76     | 85     | 89     | 91     |
-+--------------------------------------------------+--------+--------+--------+--------+
-| Dirt                                             | 72     | 82     | 87     | 89     |
-+--------------------------------------------------+--------+--------+--------+--------+
-
-(Footnotes appear on following page)
-
-Estimates of a soil's drying time have been discussed previously in
-conjunction with both the Horton regeneration constant in Section 4.2.4
-and the Green-Ampt recovery process in Section 4.3.2. It was suggested
-that the drying time *Tdry* in days could be related to a soil's
-saturated hydraulic conductivity *Ks* in in/hr as follows:
-
-+--------------------------------------------+-----------------------------------+
-| > $$T_{dry} = \frac{3.125}{\sqrt{K_{s}}}$$ | (4-51)                            |
-+============================================+===================================+
-
-where estimates of *Ks* based on soil type can be found from Table
-4-7.
-
-## 4.6 Numerical Example
-
-Because the four infiltration methods discussed in this chapter have
-very different formulations, it is interesting to compare the results
-they produce for a specific set of modeling conditions. Each method was
-used to simulate infiltration over a relatively flat, completely
-pervious subcatchment containing a well-drained Group B soil. The
-subcatchment properties, rainfall event, and infiltration parameters for
-each method are listed in Table 4-10. The infiltration parameters were
-chosen to have each method produce about the same amount of runoff for
-the design storm yet be within the normal ranges discussed in previous
-sections of this chapter.
-
-+-------------------------+------------------------------------+-----------+
-| **Item**                | **Parameter**                      | **Value** |
-+=========================+====================================+===========+
-| Subcatchment            | Percent Impervious                 | 0         |
-|                         +------------------------------------+-----------+
-|                         | Percent Slope                      | 0.5       |
-|                         +------------------------------------+-----------+
-|                         | Width (ft)                         | 140       |
-|                         +------------------------------------+-----------+
-|                         | Roughness                          | 0.1       |
-|                         +------------------------------------+-----------+
-|                         | Depression Storage (in)            | 0.05      |
-+-------------------------+------------------------------------+-----------+
-| Rainfall Event          | Duration (hr)                      | 6.0       |
-|                         +------------------------------------+-----------+
-|                         | Total Depth (in)                   | 2.0       |
-|                         +------------------------------------+-----------+
-|                         | Time-to-Peak / Duration            | 0.375     |
-|                         +------------------------------------+-----------+
-|                         | Evaporation (in/hr)                | 0         |
-+-------------------------+------------------------------------+-----------+
-| Horton Infiltration     | Initial Capacity (in/hr)           | 1.2       |
-|                         +------------------------------------+-----------+
-|                         | Ultimate Capacity (in/hr)          | 0.1       |
-|                         +------------------------------------+-----------+
-|                         | Decay Coefficient (hr-1)         | 2.0       |
-|                         +------------------------------------+-----------+
-|                         | Drying Time (days)                 | 7.0       |
-+-------------------------+------------------------------------+-----------+
-| Green-Ampt Infiltration | Saturated Hydraulic Conductivity   | 0.1       |
-|                         | (in/hr)                            |           |
-|                         +------------------------------------+-----------+
-|                         | Suction Head (in)                  | 2.0       |
-|                         +------------------------------------+-----------+
-|                         | Initial Moisture Deficit           | 0.2       |
-+-------------------------+------------------------------------+-----------+
-| Curve Number            | Curve Number                       | 80        |
-| Infiltration            |                                    |           |
-|                         +------------------------------------+-----------+
-|                         | Drying Time (days)                 | 7.0       |
-+-------------------------+------------------------------------+-----------+
-
-: []{#_Toc430249156 .anchor}**Table 4‑10 Parameters used in example
-comparison of infiltration methods**
-
-Figure 4-8 shows the infiltration rates obtained with each infiltration
-method under these conditions. The numbers in the chart's legend are the
-fraction of rainfall that becomes runoff for each method. Even though
-similar amounts of runoff are produced, the methods display distinctly
-different infiltration patterns over time. These patterns are influenced
-not only by the parameters that were chosen for each method, but also by
-the temporal pattern of rainfall intensity that occurs during an event.
-
-

-InfilExample.png
-
Figure 4‑8 Infiltration rates produced by
-different methods for a 2-inch rainfall event.

-

-
-(Numbers in parentheses are the fraction of rainfall that becomes
-runoff.)
-
-#  -- Groundwater
-
-## 5.1 Introduction
-
-Because SWMM was originally developed to simulate combined sewer
-overflows in urban catchments, the fate of infiltrated water was
-considered insignificant. Since its development, however, SWMM has been
-used on areas ranging from highly urban to completely rural. Many
-undeveloped, and even some developed areas, especially in areas like
-south Florida, are very flat with high water tables, and their primary
-drainage pathway is through the surficial groundwater aquifer and the
-unsaturated zone above it, rather than by overland flow. In these areas,
-underlain by permeable sub-soils and dynamic water tables, a storm will
-cause a rise in the water table and subsequent slow release of
-groundwater back to the receiving water (Capece et al., 1984). For this
-case, the fate of the infiltrated water is a highly significant part of
-the local water cycle. By assuming that the infiltration is lost from
-the system, an important part of the subsurface flow system is not
-properly described (Gagliardo, 1986). In unlined channels and natural
-streams, the complete water balance in the near surface soils needs to
-be maintained in order to compute baseflow. Saturated zone outflow is a
-critical component of models such as HSPF (Bicknell et al. 1997) for
-realistic simulation of streamflow in areas in which overland flow
-rarely exists, which is characteristic of most non-urban soils except
-for very clayey areas.
-
-Groundwater discharge accounts for the time-delayed recession curve that
-is prevalent in most non-urban watersheds (Fetter, 1980). This process
-cannot, however, be satisfactorily modeled by surface runoff methods
-alone. By modifying infiltration parameters to account for subsurface
-storage, attempts have been made to overcome the fact that SWMM assumes
-infiltration is lost from the system (Downs et al., 1986). Although the
-modeled and measured peak flows matched well, the volumes did not match
-well, and the values of the infiltration parameters were unrealistic.
-Some research on the nature of the soil storage capacity has been done
-in south Florida (SFWMD, 1984). However, it was directed towards
-determining an initial storage capacity for the start of a storm.
-
-Another need is to combine the groundwater discharge hydrograph with the
-surface runoff hydrograph and determine when the water table will rise
-to the surface. Additionally, a threshold saturated water zone storage
-is needed (corresponding to the bottom of a stream channel), below which
-no saturated zone outflow will occur. This is required to simulate dry
-watershed conditions. Finally, it is also desirable to simulate bank
-storage, the movement of water from a stream channel into the saturated
-groundwater zone when the stream water level is higher than the adjacent
-groundwater table.
-
-To address these needs, a simple, two-zone groundwater routine was
-incorporated into version 4 of SWMM in 1987 by W. Huber and B.
-Cunningham, based on Gagliardo's (1986) MS thesis. The intent was to
-develop a physically-based model whose parameters were based on readily
-available soil properties. The current version of SWMM has reformulated
-and simplified the original model's governing equations and solution
-procedure. This section describes the theory and limitations of these
-methods.
-
-## 5.2 Governing Equations
-
-SWMM analyzes groundwater flow for each subcatchment independently. It
-represents the subsurface region beneath a subcatchment as consisting of
-an unsaturated upper zone that lies above a lower saturated zone,
-illustrated in Figure 5-1. The height of the water table (i.e., the
-boundary between the two zones) changes with time depending on the rates
-of inflow and outflow of the saturated lower zone. This variable volume,
-two-zone configuration is similar to that used by Dawdy and O'Donnell
-(1965) and serves as an alternative pathway for infiltrated rainfall to
-pass between a subcatchment and a point in the conveyance system in an
-attenuated and delayed fashion.
-
-[]{#_Toc426447689 .anchor}**Figure 5‑1 Definitional sketch of the
-two-zone groundwater model.**
-
-Flow from the unsaturated upper zone to the saturated lower zone is
-controlled by a percolation equation for which parameters may either be
-estimated or calibrated, depending on the availability of the necessary
-soils data. The upper zone receives vertical inflow from infiltrating
-rainfall as described in Chapter 4 and can also lose moisture through
-evapotranspiration. For time steps where the water table has risen to
-the surface (reducing the unsaturated zone volume to zero), infiltration
-ceases and runoff is produced by saturation excess.
-
-Losses and outflow from the lower zone consist of deep percolation,
-saturated zone evapotranspiration, and lateral groundwater flow. The
-latter is a user-defined power function of water table stage and depth
-of water in the receiving node of the conveyance system. If the water
-elevation at the node is higher than the saturated zone water table,
-back-flow (bank storage) can occur into the saturated zone.
-
-This two-zone representation of surface runoff-groundwater interaction
-is modeled as follows (refer to Figure 5-1). The ground surface has a
-known elevation (relative to some fixed reference) of *EG* (ft) and
-the bottom of the saturated zone has a known elevation of *EB* (ft).
-The unsaturated upper zone has a varying moisture content denoted as
-*θ*. The lower zone is completely saturated, and therefore its moisture
-content is fixed at the soil porosity *φ*. Aside from *θ*, the other
-principal unknown is *dL*, the depth of the saturated zone (i.e., the
-water table depth). Because the depth from the ground surface to the
-bottom of the lower zone is fixed, the depth of the unsaturated zone
-*dU* is simply $E_{G} - E_{B} - d_{L}$.
-
-The depths of the two zones and the water content of the upper zone are
-controlled by the volumetric water fluxes shown in Figure 5-1. These
-fluxes, expressed as volume per unit horizontal area per unit time (or
-ft/sec internally in SWMM), consist of the following:
-
-| Symbol | Description |
-| :--- | :--- |
-| *fI* | infiltration from the subcatchment surface, which is the value computed in Chapter 4 multiplied by the fraction of pervious area *Fperv*. |
-| *fEU* | evapotranspiration from the upper zone, which is a fixed fraction of the unused surface evaporation, $e \times F_{perv}$. |
-| *fU* | percolation from the upper to lower zone, which depends on the upper zone moisture content *θ* and upper zone depth *dU*. |
-| *fEL* | evapotranspiration from the lower zone, which is a function of the depth of the upper zone *dU*. |
-| *fL* | percolation from the lower zone to deep groundwater, which depends on the lower zone depth *dL*. |
-| *fG* | lateral groundwater seepage to the conveyance network which depends on the lower zone depth *dL* as well as the water surface elevation in the receiving node. |
-
-Computation of these fluxes will be discussed subsequently, but keep in
-mind that they are either supplied externally or depend on the unknown
-variables *θ* , *dU* and *dL*.
-
-The conservation of mass equation for the upper zone can be written as:
-
-+--------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial V_{U}}{\partial t} = f_{UZ}$$ | (5-1)                             |
-+==================================================+===================================+
-
-where *VU* is the volume of water per unit area (ft) in the upper zone
-and *fUZ* (ft/sec) is the net influx rate to the upper zone. The
-latter is equal to:
-
-+---------------------------------------+-----------------------------------+
-| > $$f_{UZ} = f_{I} - f_{EU} - f_{U}$$ | (5-2)                             |
-+=======================================+===================================+
-
-The conservation of mass equation for the lower zone is:
-
-+--------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial V_{L}}{\partial t} = f_{LZ}$$ | (5-3)                             |
-+==================================================+===================================+
-
-where *VL* is the volume of water per unit area (ft) in the lower zone
-and *fLZ* is the net influx rate into the lower zone given by:
-
-+-----------------------------------------------+-----------------------------------+
-| > $$f_{LZ} = f_{U} - f_{EL} - f_{L} - f_{G}$$ | (5-4)                             |
-+===============================================+===================================+
-
-A third equation is needed to express the change in lower zone depth as
-a function of change in lower zone volume:
-
-+--------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$(\phi - \theta)\frac{\partial d_{L}}{\partial t} = \frac{\partial V_{L}}{\partial t}$$ | (5-5)                             |
-+============================================================================================+===================================+
-
-This equation accounts for the fact that as the lower zone contracts or
-expands it is consuming or vacating a portion of upper zone which has a
-moisture content of *θ*. For example, if the lower zone expands it
-absorbs an amount of moisture *θ* contained in the upper zone. Because
-the lower zone always has a fixed moisture content of *φ*, its expansion
-must be accompanied by a volume increase of *φ - θ* to make up the
-difference. Substituting Equation 5-5 into 5-3 results in the following
-expression for the rate of change of the lower zone depth:
-
-+--------------------------------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial d_{L}}{\partial t} = \frac{f_{LZ}}{(\phi - \theta)}$$ | (5-6)                             |
-+==========================================================================+===================================+
-
-And since $V_{U} = \theta d_{U}$, Equation 5-1 can be expanded as:
-
-+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+
-| > $$\frac{\partial V_{U}}{\partial t} = \frac{\partial\left( \theta d_{U} \right)}{\partial t} = d_{U}\frac{\partial\theta}{\partial t} + \theta\frac{\partial d_{U}}{\partial t} = f_{UZ}$$ | (5-7)                   |
-+==============================================================================================================================================================================================+=========================+
-
-From the relation $d_{U} = E_{G} - E_{B} - d_{L}$ and Equation 5-6 one
-can write:
-
-+------------------------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$\frac{\partial d_{U}}{\partial t} = - \frac{\partial d_{L}}{\partial t} = - \frac{f_{LZ}}{(\phi - \theta)}$$ | (5-8)                             |
-+==================================================================================================================+===================================+
-
-Substituting this into 5-7 and solving for
-![](VolumeI/media/media/image28.wmf) gives:
-
-+---------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+
-| > $$\frac{\partial\theta}{\partial t} = \frac{\theta f_{LZ} + (\phi - \theta)f_{UZ}}{(\phi - \theta)\left( E_{G} - E_{B} - d_{L} \right)}$$ | (5-9)                   |
-+=============================================================================================================================================+=========================+
-
-Equations 5-6 and 5-9 form a system of ordinary differential equations
-in *θ* and *dL* that can be solved using a standard fifth-order
-Runge-Kutta integration routine with adaptive step size control (Press
-et al., 1992). The integration is applied over each runoff time step as
-the calculation of surface runoff unfolds (see Section 3.4). The initial
-conditions at time zero are *dL = dL0*and *θ = θ0* where *dL0*
-is the initial depth of the saturated zone and *θ0* is the initial
-moisture content of the unsaturated zone. Additional conditions that
-must be honored during each time step *∆t* are:
-
-- The volume of infiltration that enters the upper zone over a time step
-  must not exceed the available pore volume, i.e.,
-  $f_{I}\Delta t \leq d_{U}(\phi - \theta) + f_{U}\mathrm{\Delta}t$. Any
-  excess is subtracted off and returned to the surface in the form of a
-  reduced infiltration rate.
-
-- The upper zone moisture content cannot be less than the soil's wilting
-  point moisture content nor greater than its porosity, i.e.,
-  $\theta_{WP} \leq \theta \leq \phi$ where *θWP* is the sub-soil
-  wilting point moisture content.
-
-- The depth of the lower layer cannot be greater than the distance from
-  the ground surface to the bottom of the saturated zone, i.e.,
-  $d_{L} \leq E_{G} - E_{B}$
-
-This simple two-zone groundwater model has a number of limitations that
-the reader should be aware of:
-
-- Since the moisture content of the unsaturated zone is taken as an
-  average over the entire zone, the shape of the moisture profile is
-  totally obscured. Therefore, infiltrated water cannot be modeled more
-  realistically as an expanding volume of saturated soil moving downward
-  through the unsaturated zone (which is the Green-Ampt
-  conceptualization). Furthermore, water from the capillary fringe of
-  the saturated zone cannot move upward by diffusion or capillary
-  suction into the unsaturated zone.
-
-- The simplistic representation of subsurface storage by one unsaturated
-  "tank" and one saturated "tank" limits the ability of the user to
-  match non-uniform soil columns.
-
-- The assumption that the infiltrated water is spread uniformly over the
-  entire catchment area, not just over the pervious area means that
-  mounding under a pervious area cannot be simulated.
-
-- Groundwater cannot be routed from the saturated zone under one
-  subcatchment to that of another subcatchment, i.e., lateral
-  groundwater flow within an aquifer system that underlies several
-  subcatchment areas cannot be simulated.
-
-- No attempt is made to model the fate of any water quality constituents
-  entering the groundwater system. The concentration of all pollutants
-  in the water infiltrating into the subsurface zone is set to zero. One
-  can, however, assign a constant concentration to the discharge *fG*
-  out of the saturated zone. If true quality routing through the
-  subsurface region is needed, a model such as HSPF (Bicknell et
-  al., 1997) might be considered.
-
-## 5.3 Groundwater Flux Terms
-
-In order to integrate the groundwater conservation of mass equations
-over a succession of time steps one must compute the various flux terms
-that transport water into and out of the two sub-surface zones. This
-section discusses how each of these terms is modeled.
-
-### 5.3.1 Surface Infiltration (fI)
-
-The surface infiltration flux rate *fI* is set equal to the runoff
-infiltration rate *f* computed as described in Chapter 4, multiplied by
-the fraction of the subcatchment that is pervious, *Fperv*. (The
-groundwater zones extend over the entire subcatchment area while surface
-infiltration is computed only for the pervious portion of this area.)
-*fI* is considered a constant quantity over the current runoff time
-step *∆t*. However, it is not allowed to exceed a rate that would fill
-up the available pore volume of the upper unsaturated zone by the end of
-the time step. This rate *fImax* can be computed as:
-
-+----------------------------------------------------------------+-----------------------------------+
-| > $$f_{Imax} = \frac{d_{U}(\phi - \theta)}{\Delta t} + f_{U}$$ | (5-10)                            |
-+================================================================+===================================+
-
-where *fU* is an estimate of the percolation flux rate between the
-upper and lower zones at the start of the time period and is computed
-using the equations given in Section 5.3.2 below. Thus if the
-infiltration computed from the surface runoff calculation, *fI,* is
-greater than *fImax* then *fI* is set equal to *fImax* and the
-infiltration rate used for surface runoff calculations is reduced to
-*fI /Fperv*.
-
-### 5.3.2 Upper Zone Evapotranspiration (fEU)
-
-Evapotranspiration (ET) from the upper zone, *fEU,* represents soil
-moisture lost via cover vegetation and by direct evaporation from the
-pervious area of the subcatchment. This ET is a portion of the overall
-potential evaporation rate for the study area supplied externally to the
-program using the data sources described in Section 2.5. The order in
-which this overall rate is allocated to the various types of ET losses
-is as follows: 1) land surface evaporation, 2) upper zone
-evapotranspiration, and 3) lower zone transpiration. Upper zone ET is
-computed as:
-
-+------------------------------------------------------------+---------------------------+
-| > $$f_{EU} = min(e_{\max} - e_{s},\ UEF \times e_{\max})$$ | (5-11)                    |
-+============================================================+===========================+
-
-where *UEF* is a fraction of available evaporation that is apportioned
-to the upper zone, $e_{\max} = eF_{perv}$, *e* is the maximum potential
-evaporation rate (ft/s) available for the current time period supplied
-externally, *Fperv* is the fraction of the subcatchment that is
-pervious, and *es* is the evaporation loss (ft/s) seen by any rainfall
-and ponded water on the pervious subcatchment surface. The latter is
-computed as:
-
-+--------------------------------------------------------------------+---------------------------+
-| > $$e_{s} = {\frac{{\min{(e,}d}_{a}}{\mathrm{\Delta}t})F}_{perv}$$ | (5-12)                    |
-+====================================================================+===========================+
-
-where *da* is the depth of available moisture on the pervious area of
-the subcatchment (ft). The latter quantity was evaluated at Step 3b of
-the procedure used to compute surface runoff (see Section 3.4). In
-addition, *fEU* is set to *0* whenever the upper zone soil moisture
-drops below the wilting point or when the infiltration rate *fI \> 0*
-(since it is assumed that the resulting vapor pressure will be high
-enough to prevent any evapotranspiration from the unsaturated zone).
-Note the need to adjust the surface evaporation rates by *Fperv*
-because although evaporation from the groundwater zone extends over the
-entire subsurface area of the subcatchment it can only be released
-through the pervious portion of the subcatchment.
-
-### 5.3.3 Lower Zone Evapotranspiration (fEL)
-
-Lower zone evapotranspiration, *fEL*, represents the ET, or more
-properly just the transpiration, lost from the saturated lower zone. It
-is assumed to vary in direct proportion to the distance that the water
-table sits above some reference level below which no ET can occur. In
-equation form:
-
-+---------------------------------------------------------+---------------------------+
-| > $$f_{EL} = (1 - UEF)e_{\max}\frac{DEL - d_{U}}{DEL}$$ | (5-13)                    |
-+=========================================================+===========================+
-
-where *DEL* is the depth from the ground surface below which no lower
-zone ET is possible (ft). The *fEL* value computed from (5-12) is
-constrained to be non-negative and be no greater than
-$e_{\max} - e_{s} - f_{EU}$.
-
-### 5.3.4 Percolation (fU)
-
-Percolation, *fU*, represents the flow of water from the unsaturated
-zone to the saturated zone, and apart from possible bank storage is the
-only inflow for the saturated zone. The percolation equation is
-formulated from Darcy's Law for unsaturated flow, in which the hydraulic
-conductivity, K, is a function of the moisture content, *θ*. For
-one-dimensional, vertical flow, Darcy's Law may be written as:
-
-+------------------------------------------+---------------------------+
-| > $$v = K(\theta)\frac{dh}{dz}$$         | (5-14)                    |
-+==========================================+===========================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *v* | velocity (specific discharge), positive in the downward direction of z (ft/s), |
-| *z* | vertical coordinate with respect to the ground surface (ft), |
-| *K(θ)* | hydraulic conductivity (ft/s), |
-| *θ* | moisture content (dimensionless), and |
-| *h* | hydraulic potential or head (ft). |
-
-The hydraulic potential is the sum of the elevation (gravity) and
-pressure heads,
-
-+------------------------------------------+---------------------------+
-| > $$h = z + \psi$$                       | (5-15)                    |
-+==========================================+===========================+
-
-where *ψ* = soil water tension (negative pressure head) in the
-unsaturated zone. Note that the wetting front suction, *ψS*, used in
-the Green-Ampt equations is simply the average value of *ψ* along the
-wetting front during the infiltration process. Equating vertical
-velocity to percolation, and differentiating the hydraulic potential,
-*h*, yields:
-
-+-----------------------------------------------+---------------------------+
-| > $$f_{U} = K(\theta)(1 + \frac{d\psi}{dz})$$ | (5-16)                    |
-+===============================================+===========================+
-
-A choice is customarily made between using the tension, *ψ*, or the
-moisture content, *θ*, as parameters in equations for unsaturated zone
-water flow. Since the quantity of water in the unsaturated zone is
-identified by *θ* in previous equations, it is the choice here.
-Parameter *ψ* can be related to *θ* if the characteristics of the
-unsaturated soil are known. Thus, for use in Equation 5-16, the
-derivative is:
-
-+------------------------------------------------------------------+---------------------------+
-| > $$\frac{d\psi}{dz} = \frac{d\psi}{d\theta}\frac{d\theta}{dz}$$ | (5-17)                    |
-+==================================================================+===========================+
-
-However, since *θ* is assumed constant throughout the upper zone,
-$\frac{d\theta}{dz = 0}$ and the percolation flux becomes simply:
-
-+------------------------------------------+---------------------------+
-| > $$f_{U} = K(\theta)$$                  | (5-18)                    |
-+==========================================+===========================+
-
-The hydraulic conductivity *K* as a function of moisture content *θ* is
-approximated functionally in the moisture range of interest as:
-
-+-------------------------------------------------+---------------------------+
-| > $$K(\theta) = K_{s}e^{- (\phi - \theta)HCO}$$ | (5-19)                    |
-+=================================================+===========================+
-
-where *KS* is the saturated hydraulic conductivity (ft/s) and *HCO* is
-a calibration parameter. Estimates of HCO can be made from soil test
-data and some examples will be given in section 5.4 below. Substituting
-5-19 into 5-16 yields the final form of the percolation rate expression:
-
-+---------------------------------------------+---------------------------+
-| > $$f_{U} = K_{s}e^{- (\phi - \theta)HCO}$$ | (5-20)                    |
-+=============================================+===========================+
-
-If the moisture content *θ* is less than or equal to field capacity *θ
-FC*, then the percolation rate becomes zero. This limit is in
-accordance with the concept of field capacity as the drainable soil
-water that cannot be removed by gravity alone (Hillel, 1982, p. 243).
-Once *θ* drops below field capacity, it can only be further reduced by
-upper zone evapotranspiration (to a lower bound of the wilting point
-moisture content).
-
-### 5.3.4 Deep Percolation (fL)
-
-Deep percolation, *fL*, represents a lumped sink term for
-un-quantified losses from the saturated zone. The two primary losses are
-assumed to be percolation through the confining layer and lateral
-outflow to somewhere other than the conveyance system. The arbitrarily
-chosen equation for deep percolation is:
-
-+---------------------------------------------+-----------------------------------+
-| > $$f_{L} = DP\frac{d_{L}}{E_{G} - E_{B}}$$ | (5-21)                            |
-+=============================================+===================================+
-
-where *DP* is a recession coefficient derived from inter-event water
-table recession curves. The dependence of *fL* on *dL* allows it to
-be a function of the static pressure head above the confining layer.
-
-### 5.3.5 Groundwater Discharge (fG)
-
-Groundwater discharge, *fG*, (lateral flow per horizontal area of the
-groundwater region or cfs/ft2) represents lateral flow from the
-saturated zone to elements in the conveyance system. The latter can take
-the form of an adjacent stream or channel or under-drains in the
-groundwater region, with the recognition that groundwater discharge in
-SWMM is actually to (and from) nodes, not directly to channels or pipes.
-(If need be, refer back to Section 1.2 for a description of how SWMM
-represents a conveyance system as a network of links and nodes.) If a
-channel receives groundwater, then its upstream node is used instead.
-The flux equation for groundwater discharge takes on the following
-general form:
-
-+----------------------------------------------------------------------------------------------------------+---------------+
-| > $$f_{G} = A1\left( d_{L} - h^{*} \right)^{B1} - A2\left( h_{SW} - h^{*} \right)^{B2} + A3d_{L}h_{SW}$$ | (5-22)        |
-+==========================================================================================================+===============+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *fG* | groundwater flow rate (cfs/ft2), |
-| *hSW* | height of surface water above the bottom of the groundwater zone (ft), |
-| *h\** | reference height above the bottom of the groundwater zone (ft), |
-| *A1, B1* | groundwater flow coefficient and exponent, |
-| *A2, B2* | surface water flow coefficient and exponent, |
-| *A3* | surface-groundwater interaction coefficient. |
-
-Figure 5-2 illustrates the meaning of each of the water depths used in
-this expression. The reference height *h\** is typically chosen as the
-height to the bottom of the conveyance system node, but other choices
-are possible. The coefficients *A1, A2,* and *A3* are units-dependent.
-As shown here *A1* has units of ft(1-*B1*)/s, *A2* has units of
-ft(1-*B2*)/s, while *A3* is in (ft-s)-1. In an actual SWMM input
-data set the user would use coefficients that produce flow rates
-measured in cfs/ac for US units or cms/ha for metric units. SWMM
-automatically converts these input coefficients so that Equation 5-22 is
-evaluated internally using cfs/ft2.
-
-The particular function form of Equation 5-22 was selected in order to
-approximate various horizontal flow conditions as will be illustrated
-later. The reference height *h\** sets the minimum elevation at which
-groundwater flow is possible (i.e., *fG* becomes *0* when either
-*dL* or h*SW* is below *h\**). If *h\** is not explicitly set by the
-user it defaults to the height of the receiving node's invert as shown
-in Figure 5-2. Also note that the conveyance system node receiving
-groundwater flow need not be the same node that receives runoff from the
-subcatchment that lies above the groundwater zones.
-
-[]{#_Toc426447690 .anchor}**Figure 5‑2 Heights used to compute lateral
-groundwater flow rate.**
-
-The effects of channel water on groundwater flow can be dealt with in
-two different ways. The first option entails setting *hSW* (water
-surface height in the receiving node) to a constant value greater than
-or equal to *h\** and *A2, B2* and/or *A3* to values greater than zero.
-If this method is chosen, then the user is specifying an average
-tailwater influence over the entire run to be used at each time step.
-
-The second option uses the actual water surface height at the receiving
-node, as determined during the flow routing calculations for the
-conveyance system (flow routing is discussed in Volume II of this
-manual). In this case *hSW* can vary over time and the value used in
-Equation 5-22 is the flow routing result at the start of the current
-time step.
-
-Note that when conditions warrant, the groundwater flux, *fG*, can be
-negative, simulating flow into the aquifer from the channel, in the
-manner of bank storage. An exception occurs when *A3 ≠ 0*, since the
-surface water -- groundwater interaction term is usually derived from
-groundwater flow models that assume unidirectional flow (examples are
-provided below). Otherwise, to ensure that negative *fG* values will
-not occur, one can make *A1* greater than or equal to *A2,* *B1* greater
-than or equal to *B2*, and *A3* equal to zero. More examples of
-adjusting the flow coefficients and exponents to reproduce specific
-physical conditions are provided in section 5.5 on Parameter Estimation.
-
-### 5.3.6 User-Defined Flux Equations
-
-SWMM also has the ability to employ custom user-defined equations for
-the lateral groundwater discharge flux (*fG*) and the deep percolation
-flux (*fL*). These can be any well-formed mathematical expression
-relating *fG* (in cfs/acre or cms/ha) or *fL* (in in/hr or mm/hr) to
-any of several pre-defined variables. More details can be found in the
-SWMM 5 User's Manual (US EPA, 2010).
-
-For example, a two-stage linear reservoir model for lateral groundwater
-outflow could be expressed as:
-
-***fG* = 0.001\*Hgw + 0.05\*(Hgw--5)\*STEP(Hgw--5)**
-
-where **Hgw** is the pre-defined variable name used for height of the
-groundwater table (i.e., *dL* as used here) and **STEP** is a special
-cutoff function pre-defined as **STEP(x)** = 0 if x \< 0 and is 1
-otherwise. The expression says that there is some small background flow
-out of the aquifer that is proportional to the height of the saturated
-zone plus a second larger source of outflow that only occurs when the
-saturated zone height exceeds 5. It would not be possible to express
-this type of behavior using just the standard discharge equation 5-21.
-
-An example for deep percolation flux might be
-
-***fL* = 2.5\*Hgw -- 0.1**
-
-which is equivalent to expressing *fL* through Darcy's Law as:
-
-$f_{L} = K_{c}(d_{L} - H_{c})/d_{c}$
-
-where *Kc* is the hydraulic conductivity of the confining layer
-beneath the shallow aquifer, *dc* is the thickness of this layer, and
-*Hc* is the hydraulic head below the layer. The values 2.5 and 0.1 in
-the user-defined expression would come from knowing specific values of
-*Kc*, *dc*, and *Hc*.
-
-## 5.4 Computational Scheme
-
-Groundwater computations are a sub-procedure implemented as part of
-SWMM's runoff calculations. They are made at each runoff time step, for
-each subcatchment that has a groundwater component, immediately after
-infiltration over the subcatchment's pervious area has been computed.
-This is at Step 3c of the runoff procedure described in Section 3.4. The
-detailed steps involved are described in the sidebar below.
-
-## 5.5 Parameter Estimates
-
-Estimates of the following constants are required in order to implement
-the two-zone groundwater model:
-
-- soil moisture limits (*φ*, *θ FC,* and *θ WP*)
-
-- percolation parameters (*KS, HCO,* and *DP*)
-
-- ET coefficients (*UEF* and *DEL*)
-
-- groundwater discharge constants (*A1, B1, A2, B2*, and *A3*).
-
-SWMM uses an **Aquifer** object to bundle together a common set of soil
-moisture limits, ET coefficients, and percolation parameters that can be
-shared by any number of subcatchments. This helps to reduce the amount
-of input values that must be supplied to the program. Multiple Aquifer
-objects can be defined to accommodate variations in subsurface
-conditions across the study area. On the other hand, a distinct set of
-groundwater discharge constants must be supplied for each subcatchment
-that experiences groundwater flow.
-
-### 5.5.1 Soil Moisture Limits
-
-Porosity (*φ*) is defined as the volumetric water content of a soil
-(volume of water per total volume) when its pore spaces are at
-saturation. No distinction is made here between the actual porosity and
-the apparent porosity, which includes trapped air, since no mechanism
-exists for adjusting for the latter and the difference is usually minor
-(5-10 %). Porosity is a critical parameter because of its role in
-determining moisture storage. Field capacity (*θFC*) is usually
-considered to be the amount of water a well-drained soil holds after
-free water has drained off, or the maximum amount it can hold against
-gravity (Linsley et al., 1982; SCS, 1991). This occurs at soil moisture
-tensions of from 0.1 to 0.7 atmospheres, depending on soil texture.
-Moisture content at a tension of 1/3 atmosphere is often used. The
-wilting point (or permanent wilting point) (*θ WP*), is the soil
-moisture content at which plants can no longer obtain enough moisture to
-meet transpiration requirements; they wilt and die unless water is added
-to the soil. The moisture content at a tension of 15 atmospheres is
-accepted as a good estimate of the wilting point (Linsley et al., 1982;
-Jensen et al., 1990; SCS, 1991). The field capacity must be greater than
-the wilting point and less than the porosity. The general relationship
-among soil moisture parameters is shown in Figure 5-3.
-
-![[]{#_Toc426447691 .anchor}**Figure 5‑3 Relation between soil moisture
-limits and soil texture class (Schroeder et al.,
-1994).**](VolumeI/media/media/image29.png){width="6.260416666666667in"
-height="3.78125in"}
-
-Data for soil moisture limits are available from the NRCS, agricultural
-extension offices and university soil science departments. Generalized
-values for porosity, field capacity, and wilting point are available
-from several published sources. Tables 5-1 and 5-2 contain
-representative values of field capacity and wilting point from Linsley
-et al. (1982) and the U.S. Army Corps of Engineers (1956), respectively.
-Table 5-3 is a summary of average parameter values for different soil
-types presented by Rawls et al. (1983). These data were published
-primarily to provide estimates of the Green-Ampt infiltration parameters
-that were listed previously in Table 4-7, but also included values for
-field capacity and wilting point.
-
-+-------------------------+-------------------------+-------------------------+
-| **Soil Type**           | **Field Capacity**      | **Wilting Point**       |
-|                         |                         |                         |
-|                         | **(ft3/ft3)**       | **(ft3/ft3)**       |
-+=========================+:=======================:+:=======================:+
-| Sand                    | 0.08                    | 0.03                    |
-+-------------------------+-------------------------+-------------------------+
-| Sandy loam              | 0.17                    | 0.07                    |
-+-------------------------+-------------------------+-------------------------+
-| Loam                    | 0.26                    | 0.14                    |
-+-------------------------+-------------------------+-------------------------+
-| Silt loam               | 0.28                    | 0.17                    |
-+-------------------------+-------------------------+-------------------------+
-| Clay loam               | 0.31                    | 0.19                    |
-+-------------------------+-------------------------+-------------------------+
-| Clay                    | 0.36                    | 0.26                    |
-+-------------------------+-------------------------+-------------------------+
-| Peat                    | 0.56                    | 0.30                    |
-+-------------------------+-------------------------+-------------------------+
-| \*Fraction moisture content = fraction dry weight × dry density / density   |
-| of water.                                                                   |
-+-----------------------------------------------------------------------------+
-
-: []{#_Toc430249157 .anchor}**Table 5‑1 Volumetric moisture content at
-field capacity and wilting point (derived from Linsley et al., 1982)**
-
-+-----------------------+----------------------+----------------------+
-| **Soil Type**         | **Field Capacity**   | **Wilting Point**    |
-|                       |                      |                      |
-|                       | **(ft3/ft3)**    | **(ft3/ft3)**    |
-+=======================+:====================:+:====================:+
-| Sand                  | 0.10                 | 0.03                 |
-+-----------------------+----------------------+----------------------+
-| Fine sand             | 0.12                 | 0.03                 |
-+-----------------------+----------------------+----------------------+
-| Sandy loam            | 0.16                 | 0.05                 |
-+-----------------------+----------------------+----------------------+
-| Fine sandy loam       | 0.22                 | 0.07                 |
-+-----------------------+----------------------+----------------------+
-| Silty loam            | 0.28                 | 0.12                 |
-+-----------------------+----------------------+----------------------+
-| Light clay loam       | 0.30                 | 0.13                 |
-+-----------------------+----------------------+----------------------+
-| Clay loam             | 0.32                 | 0.15                 |
-+-----------------------+----------------------+----------------------+
-| Heavy clay loam       | 0.33                 | 0.18                 |
-+-----------------------+----------------------+----------------------+
-| Clay                  | 0.33                 | 0.21                 |
-+-----------------------+----------------------+----------------------+
-
-: []{#_Toc430249158 .anchor}**Table 5‑2 Volumetric moisture content at
-field capacity and wilting point (U.S. Army Corps of Engineers, 1956)**
-
-+----------------+-----------------+-----------------+-----------------+------------------+
-| **Soil Type**  | **Porosity      | **Field         | **Wilting Point | **Saturated**    |
-|                | (ft3/ft3)** | Capacity        | (ft3/ft3)** |                  |
-|                |                 | (ft3/ft3)** |                 | **Hydraulic**    |
-|                |                 |                 |                 |                  |
-|                |                 |                 |                 | **Conductivity** |
-|                |                 |                 |                 |                  |
-|                |                 |                 |                 | **(in/hr)**      |
-+================+:===============:+:===============:+:===============:+:================:+
-| Sand           | 0.437           | 0.062           | 0.024           | 4.74             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Loamy sand     | 0.437           | 0.105           | 0.047           | 1.18             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Sandy loam     | 0.453           | 0.190           | 0.085           | 0.43             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Loam           | 0.463           | 0.232           | 0.116           | 0.13             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Silt loam      | 0.501           | 0.284           | 0.135           | 0.26             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Sandy clay     | 0.398           | 0.244           | 0.136           | 0.06             |
-| loam           |                 |                 |                 |                  |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Clay loam      | 0.464           | 0.310           | 0.187           | 0.04             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Silty clay     | 0.471           | 0.342           | 0.210           | 0.04             |
-| loam           |                 |                 |                 |                  |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Sandy clay     | 0.430           | 0.321           | 0.221           | 0.02             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Silty clay     | 0.479           | 0.371           | 0.251           | 0.02             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-| Clay           | 0.475           | 0.378           | 0.265           | 0.01             |
-+----------------+-----------------+-----------------+-----------------+------------------+
-
-: []{#_Toc430249159 .anchor}**Table 5‑3 Average moisture limits and
-saturated hydraulic conductivity for different soil types (Rawls et al.,
-1983)**
-
-Schroeder et al. (1994) developed more extensive tables of soil moisture
-limits that were used to provide default parameter values for the U.S.
-EPA HELP (Hydrological Evaluation of Landfill Performance) model. They
-were derived from the large data base of soil measurements reported by
-Rawls et al. (1982). Table 5-4 contains a version of the HELP table for
-uncompacted, low-density soils while Table 5-5 does the same for
-compacted, moderate-density soils. The soils in these tables are
-referred to by both their USDA and Unified Soil Classification System
-(USCS) textures. Table 5-6 explains the abbreviations used for these
-classifications.
-
-+---------------------+-----------------+-----------------+-----------------+-------------------+
-| **Soil Texture      | **Porosity      | **Field         | **Wilting Point | **Saturated**     |
-| Class**             | (ft3/ft3)** | Capacity        | (ft3/ft3)** |                   |
-|                     |                 | (ft3/ft3)** |                 | **Hydraulic**     |
-|                     |                 |                 |                 |                   |
-|                     |                 |                 |                 | **Conductivity,** |
-|                     |                 |                 |                 |                   |
-|                     |                 |                 |                 | **in/hr**         |
-+----------+----------+                 |                 |                 |                   |
-| **USDA** | **USCS** |                 |                 |                 |                   |
-+==========+==========+:===============:+:===============:+:===============:+:=================:+
-| CoS      | SP       | 0.417           | 0.045           | 0.018           | 14.173            |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| S        | SW       | 0.437           | 0.062           | 0.024           | 8.220             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| FS       | SW       | 0.457           | 0.083           | 0.033           | 4.394             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| LS       | SM       | 0.437           | 0.105           | 0.047           | 2.409             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| LFS      | SM       | 0.457           | 0.131           | 0.058           | 1.417             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SL       | SM       | 0.453           | 0.190           | 0.085           | 1.020             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| FSL      | SM       | 0.473           | 0.222           | 0.104           | 0.737             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| L        | ML       | 0.463           | 0.232           | 0.116           | 0.524             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SiL      | ML       | 0.501           | 0.284           | 0.135           | 0.269             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SCL      | SC       | 0.398           | 0.244           | 0.136           | 0.170             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| CL       | CL       | 0.464           | 0.310           | 0.187           | 0.091             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SiCL     | CL       | 0.471           | 0.342           | 0.210           | 0.060             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SC       | SC       | 0.430           | 0.321           | 0.221           | 0.047             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| SiC      | CH       | 0.479           | 0.371           | 0.251           | 0.035             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-| C        | CH       | 0.475           | 0.378           | 0.251           | 0.035             |
-+----------+----------+-----------------+-----------------+-----------------+-------------------+
-
-: []{#_Toc430249160 .anchor}**Table 5‑4 Default properties of
-low-density soils used in the EPA HELP model (from Rawls et al. (1982)
-as reported in Schroeder et al. (1994))**
-
-+---------------------------+-------------+-------------+-------------+-----------------------+
-| **Soil Texture Class**    | **Porosity  | **Field     | **Wilting   | **Saturated Hydraulic |
-|                           | (ft3/ft3)** | Capacity    | Point       | Conductivity(in/hr)** |
-|                           |             | (ft3/ft3)** | (ft3/ft3)** |                       |
-+-------------+-------------+             |             |             |                       |
-| **USDA**    | **USCS**    |             |             |             |                       |
-+=============+=============+:===========:+:===========:+:===========:+:=====================:+
-| L           | ML          | 0.419       | 0.307       | 0.180       | 0.027                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| SiL         | ML          | 0.461       | 0.360       | 0.203       | 0.013                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| SCL         | SC          | 0.365       | 0.305       | 0.202       | 0.004                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| CL          | CL          | 0.437       | 0.373       | 0.266       | 0.005                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| SiCL        | CL          | 0.445       | 0.393       | 0.277       | 0.003                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| SC          | SC          | 0.400       | 0.366       | 0.288       | 0.001                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| SiC         | CH          | 0.452       | 0.411       | 0.311       | 0.002                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-| C           | CH          | 0.451       | 0.419       | 0.332       | 0.001                 |
-+-------------+-------------+-------------+-------------+-------------+-----------------------+
-
-: []{#_Toc430249161 .anchor}**Table 5‑5 Default properties of
-moderate-density soils used in the EPA HELP model (Schroeder et al.
-(1994))**
-
-+---------------------------------------------+----------------------------------------------+
-| **USDA Soil Texture**                       | **Unified Soil Classification System**       |
-+===================+=========================+===================+==========================+
-| **Symbol**        | **Meaning**             | **Symbol**        | **Meaning**              |
-+-------------------+-------------------------+-------------------+--------------------------+
-| S                 | Sand                    | S                 | Sand                     |
-+-------------------+-------------------------+-------------------+--------------------------+
-| Si                | Silt                    | M                 | Silt                     |
-+-------------------+-------------------------+-------------------+--------------------------+
-| C                 | Clay                    | C                 | Clay                     |
-+-------------------+-------------------------+-------------------+--------------------------+
-| L                 | Loam (mixture of sand,  | P                 | Poorly graded            |
-|                   | silt, clay and humus)   |                   |                          |
-+-------------------+-------------------------+-------------------+--------------------------+
-| Co                | Coarse                  | W                 | Well graded              |
-+-------------------+-------------------------+-------------------+--------------------------+
-| F                 | Fine                    | H                 | High plasticity or       |
-|                   |                         |                   | compressibility          |
-+-------------------+-------------------------+-------------------+--------------------------+
-|                   |                         | L                 | Low plasticity or        |
-|                   |                         |                   | compressibility          |
-+-------------------+-------------------------+-------------------+--------------------------+
-
-: []{#_Toc430249162 .anchor}**Table 5‑6 Soil texture abbreviations**
-
-More specific soil parameter estimates can be obtained from the NRCS
-Soil Survey reports available for each county in the U.S. These were
-discussed previously in Section 4.1. An excerpt from the Physical
-Properties portion of one such report was displayed in Figure 4-1. Using
-the bulk density *ρb* value provided in these reports, an estimate of
-the porosity can be derived from:
-
-+--------------------------------------------+-----------------------------------+
-| > $$\phi = 1 - \frac{\rho_{b}}{\rho_{s}}$$ | (5-23)                            |
-+============================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *φ* | porosity, |
-| *ρb* | bulk density (mass of dried soil to total volume of soil and voids), g/cm3, |
-| *ρs* | soil particle density, typically in range 2.6-2.7 g/cm3 for quartz particles. |
-
-As an example, the bulk density for the Woodburn silt loam listed in
-Figure 4-1 is *1.35* g/cm3 and using a *ρs* = 2.65 g/cm3 in
-Equation 5-23 yields a *φ* *= 0.49.* This corresponds well with the
-general value of *0.501* for silt loam given in Tables 5-4 and 5-5.
-Carrying the example further, when Primary Characterization Data are
-obtained for Woodburn silt loam (Benton County, Oregon) from the NRCS
-web site, the moisture content at 1500 kPa (15 atm) for the surface
-layer is 13.7 percent, a good estimate for the wilting point for this
-soil (Jensen et al., 1990). Similarly, the moisture content listed at 33
-kPa (0.33 atm) representing the field capacity is about 28 percent.
-
-Another approach to estimating soil moisture limits are the empirical
-equations developed by Saxton and Rawls (2006) from a data base of over
-2,000 soil samples. These utilize the standard soil grain size
-classification of percent sand, silt, and clay along with organic
-content to estimate a soil's porosity, field capacity and wilting point.
-Sand and clay percentages should be determined using a grain size
-distribution chart and particle sizes defined by the U.S. Department of
-Agriculture textural soil classification system. According to this
-system, sand particles range in size from 0.05 mm to 2.0 mm, silt
-particles from 0.002 mm to 0.05 mm, and clay particles are less than
-0.002 mm. The relevant equations are listed in Table 5-7.
-
-The SPAW computer model (), used to
-analyze the hydrology of agricultural fields, contains a stand-alone
-calculator that implements these equations within a graphical user
-interface and also makes adjustments for salinity, gravel content and
-degree of compaction (see Figure 5-4). Table 5-8 shows the results from
-this calculator for the same soil classes listed previously in Table
-5-3. For the Woodburn silt loam discussed earlier, the program yields
-moisture limits of 13.7, 32.1 and 48.2 percent for the wilting point,
-field capacity, and porosity, respectively.
-
-+-----------------+--------------------------------------------------------------------------------------------------------------------------+
-| **Soil Moisture | **Equation2**                                                                                                          |
-| Limit1**      |                                                                                                                          |
-+=================+==========================================================================================================================+
-| Wilting Point   | $\theta_{WP} = \theta_{1500t} + (0.14\theta_{1500t} - 0.02)$ where                                                       |
-| (*θ WP*)      |                                                                                                                          |
-|                 | $$\theta_{1500t} = - 0.024S + 0.487C + 0.006OM + 0.005(S \times OM) - 0.013(C \times OM) + 0.068(S \times C) + 0.031$$   |
-+-----------------+--------------------------------------------------------------------------------------------------------------------------+
-| Field Capacity  | $\theta_{FC} = \theta_{33t} + (1.283\theta_{33t}^{2} - 0.374\theta_{33t} - 0.015)$ where                                 |
-| (*θ FC*)      |                                                                                                                          |
-|                 | $$\theta_{33t} = - 0.251S + 0.195C + 0.011OM + 0.006(S \times OM) - 0.027(C \times OM) + 0.452(S \times C) + 0.299$$     |
-+-----------------+--------------------------------------------------------------------------------------------------------------------------+
-| Porosity (*φ*)  | $\varphi = \theta_{FC} + \theta_{(S - 33)} - 0.097S + 0.043$ where                                                       |
-|                 |                                                                                                                          |
-|                 | $\theta_{(S - 33)} = \theta_{(S - 33)t} + 0.636\theta_{(S - 33)t} - 0.107$ and                                           |
-|                 |                                                                                                                          |
-|                 | $$\theta_{(S - 33)t} = 0.278S + 0.034C + 0.022OM - 0.018(S \times OM) - 0.027(C \times OM) - 0.584(S \times C) + 0.078$$ |
-+-----------------+--------------------------------------------------------------------------------------------------------------------------+
-
-: []{#_Toc430249163 .anchor}**Table 5‑7 Regression equations for soil
-moisture limits (Saxton and Rawls, 2006)**
-
-1Moisture limits are fractional volumes.
-
-2*S* = weight fraction of sand, *C* = weight fraction of clay, *OM* =
-percent organic matter.
-
-![[]{#_Toc426447692 .anchor}**Figure 5‑4 SPAW\'s soil water
-characteristics
-calculator.**](VolumeI/media/media/image30.png){width="5.740153105861768in"
-height="4.112449693788276in"}
-
-+----------------+---------------+---------------+---------------+--------------+
-| **Soil Type**  | **Porosity**  | **Field       | **Wilting     | **Saturated  |
-|                |               | Capacity**    | Point**       | Hydraulic    |
-|                | **(ft3/ft3)** |               |               | Conductivity |
-|                |               | **(ft3/ft3)** | **(ft3/ft3)** | (in/hr)**    |
-+================+:=============:+:=============:+:=============:+:============:+
-| Sand           | 0.463         | 0.094         | 0.050         | 4.49         |
-+----------------+---------------+---------------+---------------+--------------+
-| Loamy sand     | 0.457         | 0.121         | 0.057         | 3.59         |
-+----------------+---------------+---------------+---------------+--------------+
-| Sandy loam     | 0.450         | 0.179         | 0.081         | 1.98         |
-+----------------+---------------+---------------+---------------+--------------+
-| Loam           | 0.458         | 0.267         | 0.126         | 0.73         |
-+----------------+---------------+---------------+---------------+--------------+
-| Silt loam      | 0.482         | 0.321         | 0.137         | 0.48         |
-+----------------+---------------+---------------+---------------+--------------+
-| Sandy clay     | 0.432         | 0.283         | 0.183         | 0.31         |
-| loam           |               |               |               |              |
-+----------------+---------------+---------------+---------------+--------------+
-| Clay loam      | 0.472         | 0.350         | 0.213         | 0.18         |
-+----------------+---------------+---------------+---------------+--------------+
-| Silty clay     | 0.510         | 0.379         | 0.210         | 0.23         |
-| loam           |               |               |               |              |
-+----------------+---------------+---------------+---------------+--------------+
-| Sandy clay     | 0.440         | 0.371         | 0.260         | 0.03         |
-+----------------+---------------+---------------+---------------+--------------+
-| Silty clay     | 0.532         | 0.416         | 0.278         | 0.15         |
-+----------------+---------------+---------------+---------------+--------------+
-| Clay           | 0.488         | 0.420         | 0.299         | 0.03         |
-+----------------+---------------+---------------+---------------+--------------+
-
-: []{#_Toc430249164 .anchor}**Table 5‑8 Regression estimates of soil
-moisture limits from the SPAW calculator\***
-
-\*For 2.5% organic matter content by weight.
-
-### 5.5.2 Percolation Parameters
-
-The two parameters that govern the percolation rate between the upper
-and lower groundwater zones are the soil's saturated hydraulic
-conductivity *KS* and the coefficient *HCO* that characterizes the
-exponential decrease in hydraulic conductivity with decreasing moisture
-content. The most accurate way of estimating these parameters is from
-laboratory tests that measure hydraulic conductivity *K* as a function
-of soil moisture content *θ* for the particular soil under
-consideration. Such data for three particular soils -- sand, sandy loam,
-and silty loam -- are shown in Figure 5-5. They were generated from
-disturbed soil samples under desaturation (draining) conditions (see
-Brooks and Corey (1964) and Laliberte et al. (1966)). In some cases
-(e.g., sand), *K(θ)* may range through several orders of magnitude.
-Soils data of this type are becoming more readily available; for
-example, soil science departments at universities often publish such
-information (e.g., Carlisle et al., 1981).
-
-![TouchetSiltLoam.png](VolumeI/media/media/image31.png){width="4.51104658792651in"
-height="2.4690944881889765in"}
-
-![ColumbiaSandyLoam.png](VolumeI/media/media/image32.png){width="4.3964468503937in"
-height="2.5524398512685913in"}
-
-

-UnconsolidatedSand.png
-
Figure 5‑5 Measured hydraulic conductivity
-for three soils.

-

-
-When soil data like this are available, *KS* and *HCO* can be
-estimated by fitting Equation 5-20 to the data, i.e., fitting a straight
-line to the plot of the logarithm of *K* versus *θ. * The fits are not
-optimal over the entire data range because the fit is only performed for
-the high moisture content region between field capacity and porosity.
-
-When laboratory data are not available general estimates of *KS* based
-on soil texture class can be obtained from Tables 5-3, 5-4, and 5-5.
-Another alternative is the regression equation derived by Saxton and
-Rawls (2006) from the same soils data base used to derive the moisture
-limit equations listed in Table 5-7. The equation for *KS* (in/hr) is:
-
-+--------------------------------------------------------+-----------------------------------+
-| > $$K_{s} = 76{(\phi - \theta_{FC})}^{(3 - \lambda)}$$ | (5-24)                            |
-+========================================================+===================================+
-
-where $\lambda = 0.262ln\left( \frac{\theta_{FC}}{\theta_{WP}} \right)$
-and *φ* = soil porosity, *θFC* = field capacity and *θWP* = the
-wilting point. This equation is also included in the SPAW soil water
-characteristics calculator described in the previous section and shown
-in Figure 5-4. The estimates of *KS* it produces for the different
-soil classes are shown in Table 5-8. For the Woodburn silt loam soil in
-Section 5.5.1, it estimates a saturated hydraulic conductivity of 0.48
-in/hr (see Figure 5-4). This value falls within the range of 0.2 - 2.0
-in/hr (1.4 - 14 µm/sec) listed in the Physical Properties report of
-Figure 4-1.
-
-*HCO* can be estimated by utilizing Campbell's theoretical power law
-relation (Campbell, 1974) as described in Saxton and Rawls (2006):
-
-+---------------------------------------------------------------------------+-----------------------------------+
-| > $$K(\theta) = K_{S}\left( \frac{\theta}{\phi} \right)^{3 + 2/\lambda}$$ | (5-25)                            |
-+===========================================================================+===================================+
-
-One can then estimate a value for *HCO* that gives a best fit between
-Equation 5-19 and Equation 5-25 as *θ* ranges between *φ* and *θFC*.
-Figure 5-6 shows one such fit for the soil limits associated with the
-Woodburn Silt Loam discussed earlier (*φ* = 0.482, *θFC* = 0.321, and
-*θWP* = 0.137). The data points come from evaluating Equation 5-25 for
-a series of different moisture levels *θ*. The line of best fit that
-passes through the origin has a slope of 28.864 which would be the
-estimate of HCO for this soil.
-
-

-HydConFit.png
-
Figure 5‑6 Fitting SWMM's hydraulic
-conductivity equation to a power law equation.

-

-
-Repeating this fitting process for the sand and clay content of the
-various standard soil classes under a variety of organic contents, using
-the SPAW calculator to estimate the associated moisture limits, produced
-the following regression estimate for HCO:
-
-+-------------------------------------------------+--------------------+
-| > $HCO = 0.48(\% Sand) + 0.85(\% Clay)$ R2 =  | (5-26)             |
-| > 0.99                                          |                    |
-+=================================================+====================+
-
-The resulting HCO values for the different soil classes are shown in
-Table 5-9.
-
-A third percolation parameter, *DP*, governs the rate of at which water
-is lost from the lower saturated zone by seepage through a confining
-layer into a deeper groundwater aquifer. *DP* essentially represents the
-saturated hydraulic conductivity of this confining bottom layer and will
-therefore typically have very low values, similar to those for compacted
-clay soils. If water table measurements are available, *DP* can also be
-estimated from the rate at which the water table elevation drops over a
-prolonged dry period.
-
-| **Soil Type** | **Percent Sand** | **Percent Clay** | **HCO** |
-| --- | --- | --- | --- |
-| Sand | 92 | 5 | 48 |
-| Loamy sand | 82 | 6 | 44 |
-| Sandy loam | 65 | 10 | 40 |
-| Loam | 42 | 18 | 35 |
-| Silt loam | 20 | 20 | 27 |
-| Sandy clay loam | 60 | 28 | 53 |
-| Clay loam | 33 | 34 | 45 |
-| Silty clay loam | 10 | 34 | 34 |
-| Sandy clay | 52 | 42 | 61 |
-| Silty clay | 7 | 47 | 43 |
-| Clay | 30 | 50 | 57 |
-
-  : []{#_Toc430249165 .anchor}**Table 5‑9 Estimated HCO for different
-  soil types**
-
-### 5.5.3 ET Parameters
-
-The two evapotranspiration parameters used by the groundwater routine
-are *CET*, the fraction of the available evaporation apportioned to the
-upper unsaturated zone, and *DET*, the depth from the ground surface
-below which no lower zone ET is possible (ft). The total rate available
-for subsurface evaporation is the external evaporation rate supplied to
-the program for the current month or day (see Section 2.5) minus the
-rate used for surface evaporation (Equation 5-12). The *CET* parameter
-determines what fraction of this remaining evaporation rate is used in
-the upper subsurface zone. In general, higher *CET* values will be
-associated with looser soils, lower water table elevations, and surface
-vegetation with shallow root zones.
-
-The amount of ET available to the saturated lower zone is *1 -- CET* of
-the total subsurface available ET. The fraction of this amount actually
-utilized is proportional to the height that the water table rises above
-a depth *DET* measured from the ground surface. *DET* is the maximum
-depth from which water may be removed by evapotranspiration. Because the
-lower zone is saturated, ET losses reflect mainly plant transpiration.
-Where surface vegetation is present, *DET* should at least equal the
-expected average depth of root penetration. The influence of plant roots
-usually extends somewhat below the depth of root penetration because of
-capillary suction to the roots. The depth of capillary draw to the
-surface without vegetation may be 4 to 8 inches for sands, about 8 to 18
-inches in silts, and in clays about 12 to 60 inches. Rooting depth is
-dependent on many factors \-- species, moisture availability,
-maturation, soil type, and plant density. In humid areas where moisture
-is readily available near the surface, grasses may have rooting depths
-of 6 to 24 inches. In drier areas, the rooting depth is very sensitive
-to plant species and to the depth to which moisture is stored and may
-range from 6 to 48 inches. The evaporative zone depth would be somewhat
-greater than the rooting depth. The local Agricultural Extension Service
-office can provide information on characteristic rooting depths for
-vegetation in specific areas. Table 5-10 presents values of DET for
-different combinations of soil type and ground cover that were derived
-from unsaturated-saturated flow simulations (Shah et al., 2007).
-
-| **Soil Type** | **Bare Soil** | **Grass** | **Forest** |
-| --- | --- | --- | --- |
-| Sand | 2 | 5 | 8 |
-| Loamy Sand | 2 | 6 | 9 |
-| Sandy Loam | 4 | 8 | 11 |
-| Sandy clay loam | 7 | 10 | 13 |
-| Sandy clay | 7 | 10 | 13 |
-| Loam | 9 | 12 | 15 |
-| Silty clay | 11 | 14 | 17 |
-| Clay loam | 13 | 17 | 20 |
-| Silt loam | 14 | 17 | 20 |
-| Silt | 14 | 17 | 21 |
-| Silty clay loam | 15 | 18 | 21 |
-| Clay loam | 20 | 23 | 27 |
-
-  : []{#_Toc430249166 .anchor}**Table 5‑10 DET (in feet) for different
-  soil types and land cover (Shah et al., 2007)**
-
-### 5.5.4 Groundwater Discharge Constants
-
-The groundwater discharge constants *A1, B1, A2, B2*, and *A3* appear in
-Equation 5-22 and determine the rate of groundwater exchange with a
-specific node in the conveyance system. The equation is repeated here
-for easy reference:
-
-+----------------------------------------------------------------------------------------------------------+---------------+
-| > $$f_{G} = A1\left( d_{L} - h^{*} \right)^{B1} - A2\left( h_{SW} - h^{*} \right)^{B2} + A3d_{L}h_{SW}$$ | (5-27)        |
-+==========================================================================================================+===============+
-
-where the heights *dL*, *hSW*, and *h\** are defined in Figure 5-2.
-Because of its general nature this equation can assume a variety of
-functional forms. Several specific examples will now be discussed.
-
-[Linear Reservoir]{.underline}
-
-The saturated groundwater zone can be thought of as a storage reservoir
-whose lateral outflow is linearly proportional to the water table depth
-*dL*. Two cases are possible -- with and without surface water
-interaction. Without surface water interaction, the groundwater flow
-rate is simply:
-
-+----------------------------------------------+-----------------------------------+
-| > $$f_{G} = A1\left( d_{L} - h^{*} \right)$$ | (5-28)                            |
-+==============================================+===================================+
-
-In terms of Equation 5-27 this implies that *A1 \> 0*, *B1 = 1*, and *A2
-= A3 = 0*. Note that the user-supplied value of *A1* would be expressed
-as cfs/ac-ft for US units and cms/ha-m for metric units. With surface
-water interaction, the groundwater flow rate is proportional to the
-difference between the groundwater table height and the surface water
-height:
-
-+-----------------------------------------------+-----------------------------------+
-| > $$f_{G} = A1\left( d_{L} - h_{SW} \right)$$ | (5-29)                            |
-+===============================================+===================================+
-
-which can be achieved with *A1 = A2 \> 0, B1 = B2 = 1*, and *A3 = 0*.
-*A1* would have the same units as before (cfs/ac-ft or cms/ha-m).
-Because both of these cases are empirical simplifications, *A1* would
-have to be determined through model calibration against observed
-groundwater table and conveyance system head measurements.
-
-[Dupuit-Forcheimer Lateral Seepage]{.underline}
-
-Under the assumption of uniform infiltration and horizontal flow by the
-Dupuit-Forcheimer approximation, the relationship between water table
-elevation and groundwater flow rate for the configuration shown in
-Figure 5-7 is (Bouwer, 1978, p.51):
-
-+------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{G} = \frac{K_{S}}{2L^{2}}\left( h_{1}^{2} - h_{2}^{2} \right)$$ | (5-30)                            |
-+========================================================================+===================================+
-
-where *KS* is the saturated hydraulic conductivity and the other
-parameters are defined in Figure 5-7.
-
-While *h2* is the same as the surface water height *hSW*, *h1* is
-the [maximum]{.underline} groundwater table height. The height *dL*
-that SWMM computes is only an average over the catchment. One can,
-however, assume this average is equivalent to the average of *h1* and
-*h2*, i.e.:
-
-+---------------------------------------+-----------------------------------+
-| > $$d_{L} = \frac{h_{1} + h_{2}}{2}$$ | (5-31)                            |
-+=======================================+===================================+
-
-so that $h_{1} = 2d_{L} - h_{2}$. Substituting this and $h_{2} = h_{SW}$
-into Equation 5-30 and simplifying terms results in:
-
-

-
-
Figure 5‑7 Definition sketch for
-Dupuit-Forcheimer seepage to an adjacent
-channel.

-

-
-+-------------------------------------------------------------------------------------------------------------+-----------------------------------+
-| > $$f_{G} = \left( \frac{2K_{S}}{L^{2}} \right)d_{L}^{2} - \left( \frac{2K_{S}}{L^{2}} \right)d_{L}h_{SW}$$ | (5-32)                            |
-+=============================================================================================================+===================================+
-
-Comparing Equation 5-32 with Equation 5-27 shows that the two will be
-equivalent if *A1 = -A3* *= 2KS / L2, A2 = 0,* *B1 = 2*, and *h\** =
-0. Note that Equation 5-30 is only valid for unidirectional flow into
-the receiving node, but because *A3 ≠ 0*, SWMM will set *fG* to *0*
-should *dL* drop below *hSW*.
-
-[Hooghoudt's Equation for Tile Drainage]{.underline}
-
-The geometry of a tile drainage installation is illustrated in Figure
-5-8. Hooghoudt's relationship (Bouwer, 1978, p. 295) among the indicated
-parameters is
-
-+--------------------------------------------------------------+-----------------------------------+
-| > $$f_{G} = \left( 2D_{e} + m \right)4K_{S}\frac{m}{L^{2}}$$ | (5-33)                            |
-+==============================================================+===================================+
-
-where *De* = effective depth of the impermeable layer below the drain
-center, and the other parameters are defined in Figure ‎5-8. *De* is
-less than or equal to *b0* in Figure 5-8 and is a function of *b0*,
-drain diameter, and drain spacing *L*; the complicated relationship is
-given by Bear (1972, p. 412) and graphed by Bouwer (1978, p. 296).
-
-

-
-
Figure 5‑8 Definition sketch for
-Hooghoudt’s method for flow to circular
-drains.

-

-
-From Figure 5-8, the maximum rise of the water table, *m*, is:
-
-+-----------------------------------+-----------------------------------+
-| > $$m = h_{1} - b_{0}$$           | (5-34)                            |
-+===================================+===================================+
-
-Once again approximating the average water table depth above the
-impermeable layer by:
-
-+---------------------------------------+-----------------------------------+
-| > $$d_{L} = \frac{h_{1} + b_{0}}{2}$$ | (5-35)                            |
-+=======================================+===================================+
-
-results in:
-
-+-----------------------------------------+-----------------------------------+
-| > $$m = 2\left( d_{L} - b_{0} \right)$$ | (5-36)                            |
-+=========================================+===================================+
-
-Substituting 5-36 into 5-33 gives:
-
-+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------+
-| > $$f_{G} = \left( \frac{16K_{S}}{L^{2}} \right)\left\lbrack \left( d_{L} - b_{0} \right)^{2} - D_{e}b_{0} + D_{e}d_{L} \right\rbrack$$ | (5-37)            |
-+=========================================================================================================================================+===================+
-
-This can be written in a format compatible with the general groundwater
-discharge equation 5-27 as follows:
-
-+------------------------------------------------------------+-----------------------------------+
-| > $$f_{G} = A1{(d_{L} - h^{*})}^{2} - A2 + A3d_{L}h_{SW}$$ | (5-38)                            |
-+============================================================+===================================+
-
-where
-
-$A1 = 16K_{S}/L^{2}$,
-
-> $B1 = 2$,
->
-> $A2 = A1D_{e}b_{0}$,
->
-> $B2 = 0$,
->
-> $A3 = A1(\frac{D_{e}}{b_{0}})$,
-
-*h\** is set equal to *b0* and a constant value of *hSW* only
-slightly higher than *b0* is used.
-
-The internal units of both *A1* and *A3* are (ft-s)-1 while *A2* has
-units of ft/s. In terms of the program input though, where *fG* is
-expressed as flow per acre (or per hectare), the units on *A1* and *A3*
-would be would be ft/s/ac (or m/s/ha) and for *A2* would be ft3/s/ac
-(or m3/s/ha). Since *A3 ≠ 0*, flow back into the groundwater zone
-would not be allowed should *dL* drop below *b0*. The mathematics of
-drainage to ditches or circular drains is complex; several alternative
-formulations are described by van Schilfgaarde (1974).
-
-## 5.6 Numerical Example
-
-A simple numerical example will help illustrate the effect that
-groundwater can have on the runoff generated from a subcatchment. It is
-a variation of the runoff example used in Section 3.10 which consists of
-a single relatively flat, completely pervious subcatchment containing a
-well-drained Group B soil that is subjected to a 2-inch, 6-hour rain
-event. The subsurface zone beneath the subcatchment extends to a depth
-of 6 feet and its initial water table height is 3.5 feet. Because a
-conveyance node is required to complete a groundwater model, a single
-such node is included that receives both the surface runoff and the
-groundwater flow from the subcatchment. Its invert elevation is 0.5 feet
-above the initial water table level. The Linear Reservoir form of the
-groundwater discharge equation without surface water interaction is
-used. Table 5-11 summarizes the pertinent parameters for this example.
-The initial moisture content of the unsaturated zone is 0.4, midway
-between fully saturated and fully drained.
-
-+-------------------------+------------------------------------+-----------+
-| **Item**                | **Parameter**                      | **Value** |
-+=========================+====================================+:=========:+
-| Subcatchment            | Percent Impervious                 | 0         |
-|                         +------------------------------------+-----------+
-|                         | Percent Slope                      | 0.5       |
-|                         +------------------------------------+-----------+
-|                         | Width (ft)                         | 140       |
-|                         +------------------------------------+-----------+
-|                         | Roughness                          | 0.1       |
-|                         +------------------------------------+-----------+
-|                         | Depression Storage (in)            | 0.05      |
-+-------------------------+------------------------------------+-----------+
-| Rainfall Event          | Duration (hr)                      | 6.0       |
-|                         +------------------------------------+-----------+
-|                         | Total Depth (in)                   | 2.0       |
-|                         +------------------------------------+-----------+
-|                         | Time-to-Peak / Duration            | 0.375     |
-|                         +------------------------------------+-----------+
-|                         | Evaporation Rate (in/hr)           | 0.0       |
-+-------------------------+------------------------------------+-----------+
-| Horton Infiltration     | Initial Capacity (in/hr)           | 1.2       |
-|                         +------------------------------------+-----------+
-|                         | Ultimate Capacity (in/hr)          | 0.1       |
-|                         +------------------------------------+-----------+
-|                         | Decay Coefficient (hr-1)         | 2.0       |
-+-------------------------+------------------------------------+-----------+
-| Groundwater             | Porosity                           | 0.5       |
-|                         +------------------------------------+-----------+
-|                         | Field Capacity                     | 0.3       |
-|                         +------------------------------------+-----------+
-|                         | Wilting Point                      | 0.15      |
-|                         +------------------------------------+-----------+
-|                         | Saturated Hydraulic Conductivity   | 0.1       |
-|                         | (in/hr)                            |           |
-|                         +------------------------------------+-----------+
-|                         | Conductivity Curve Parameter (HCO) | 12.0      |
-|                         +------------------------------------+-----------+
-|                         | Deep Percolation Constant (DP)     | 0.002     |
-|                         +------------------------------------+-----------+
-|                         | Reference Depth (*h\**) (ft)       | 4.0       |
-|                         +------------------------------------+-----------+
-|                         | GW Flow Coefficient (A1)           | 0.5       |
-|                         | (cfs/ac-ft)                        |           |
-|                         +------------------------------------+-----------+
-|                         | GW Flow Exponent (B1)              | 1.0       |
-|                         +------------------------------------+-----------+
-|                         | A2, A3 and B2                      | 0.0       |
-+-------------------------+------------------------------------+-----------+
-
-: []{#_Toc430249167 .anchor}**Table 5‑11 Parameters used in groundwater
-example**
-
-The surface runoff and the groundwater flow seen by the outlet node over
-a 24-hour simulation period are shown in Figure 5-9. The surface runoff
-is unaffected by inclusion of the subsurface zones, since the upper zone
-never fully saturates. Its hydrograph looks the same as for the example
-in Section 3.10 (see the pervious curve in Figure 3-12). However, as the
-infiltrated water percolates through the upper soil zone, the depth of
-the lower saturated zone rises and begins to produce groundwater outflow
-into the receiving node. This outflow continues long after the surface
-runoff ceases, creating an extended recession limb on the total outflow
-hydrograph.
-
-[]{#_Toc426447697 .anchor}**Figure 5‑9 Surface runoff and groundwater
-flow for the illustrative groundwater example.**
-
-#  -- Snowmelt
-
-## 6.1 Introduction
-
-Snowmelt is an additional mechanism by which urban runoff may be
-generated. Although flow rates are typically low, they may be sustained
-over several days and remove a significant fraction of pollutants
-deposited during the winter. Rainfall events superimposed upon snowmelt
-baseflow may produce higher runoff peaks and volumes as well as add to
-the melt rate of the snow. In the context of long term continuous
-simulation, runoff and pollutant loads are distributed quite differently
-in time between the cases when snowmelt is and is not simulated. The
-water and pollutant storage that occurs during winter months in colder
-climates cannot be simulated without including snowmelt.
-
-As part of a broad program of testing and adaptation to Canadian
-conditions, a snowmelt routine was placed in SWMM for single event
-simulation by Proctor and Redfern, Ltd. and James F. MacLaren, Ltd.,
-abbreviated PR-JFM (1976a, 1976b, 1977), during 1974-1976. The basic
-melt computations were based on routines developed by the U.S. National
-Weather Service, NWS (Anderson, 1973). The current SWMM implementation
-utilizes the Canadian SWMM snowmelt routines as a starting point and
-extends their capabilities to model long term continuous simulations. In
-addition, features were added to adapt the snowmelt process to urban
-conditions, since the snowmelt routines used in other watershed runoff
-models are aimed primarily at simulation of spring melts in large river
-basins. The work of the National Weather Service (Anderson, 1973, 2006)
-as reflected in their SNOW-17 model was heavily utilized, especially for
-the extension to continuous simulation and the resulting inclusion of
-cold content, variable melt coefficients, and areal depletion.
-
-Several hydrologic models include snowmelt computations, e.g., Stanford
-Watershed Model (Crawford and Linsley, 1966), HSPF (Bicknell et al.,
-1997), NWS (Anderson, 1973, 1976), STORM (Corps of Engineers, 1977;
-Roesner et al., 1974), SSARR (Corps of Engineers, 1971), and PRMS
-(Leavesley et al., 1983). Useful summaries of snowmelt modeling
-techniques are available in texts by Eagleson (1970), Gray (1970),
-Fleming (1975), Linsley et al. (1975), Bedient et al. (2013), and
-Viessman and Lewis (2003). All of these draw upon the classic work,
-*Snow Hydrology*, of the Corps of Engineers (1956).
-
-A review of snowmelt components of urban drainage models has been
-performed by Semádeni-Davies (2000). Three models were reviewed in some
-detail: SWMM (version 4), MouseNAM (Danish Hydraulic Institute, 1994),
-and HBV (Bergström, 1976; Lindström et al., 1997). Semádeni-Davies
-(2000) concludes that urban snowmelt routines (including those in SWMM)
-have been adapted directly from models developed for rural situations
-and therefore may not represent urban conditions well. Degree-day
-methods are used in all three models that she reviewed, and only limited
-information is available regarding coefficients in urban areas. Plowing
-and piling of snow in urban areas, and the change in the nature of its
-albedo and density are also important considerations, for which SWMM
-includes options for their representation. Overall, SWMM appears to be
-no better -- and no worse -- than the other two models reviewed. The
-descriptions of SWMM snowmelt algorithms that follow do not reflect any
-general improvements recommended by Semádeni-Davies (2000).
-
-## 6.2 Preliminaries
-
-### 6.2.1 Snow Depth
-
-SWMM treats all snow depths as "depth of water equivalent" to avoid
-specification of the specific gravity of the snow pack, which is highly
-variable with time. The specific gravity of new snow is of the order of
-0.09; an 11:1 or 10:1 ratio of snow pack depth to water equivalent depth
-is often used as a rule of thumb. With time, the pack compresses until
-the specific gravity can be considerably greater, to 0.5 and above. In
-urban areas, lingering snow piles may resemble ice more than snow with
-specific gravities approaching 1.0. Although snow pack heat conduction
-and storage depend on specific gravity, sufficient accuracy may be
-obtained without involving specific gravity. It is adequate to maintain
-continuity through the use of depth of water equivalent. Most input
-parameters are in units of inches or mm of water equivalent (in w.e., or
-mm w.e.). For all internal computations, conversions are made to feet of
-water equivalent.
-
-### 6.2.2 Meteorological Inputs
-
-Snowfall rates are determined directly from precipitation inputs by
-using a dividing temperature *SNOTMP*. If the current air temperature is
-at or below *SNOTMP*, the precipitation falls as snow. Otherwise it
-falls as rain. In natural areas, a surface temperature of 34° to 35°F
-(1-2°C) provides the dividing line between equal probabilities of rain
-and snow (Eagleson, 1970; Corps of Engineers, 1956). However, this
-separation temperature might need to be somewhat lower in urban areas
-due to warmer surface temperatures.
-
-Precipitation gages tend to produce inaccurate snowfall measurements
-because of the complicated aerodynamics of snowflakes falling into the
-gage. Snowfall totals are generally underestimated as a result, by a
-factor that varies considerably depending upon gage exposure, wind
-velocity and whether or not the gage has a wind shield. The program
-includes a multiplier for each Rain gage object, the Snow Catch Factor
-(*SCF*), which adjusts for these effects. The *SCF* is only applied when
-precipitation falls as snow.
-
-Although it will vary considerably from storm to storm, *SCF* acts as a
-mean correction factor over a season in the model. Anderson (1973)
-provides typical values of *SCF* as a function of wind speed, as shown
-in Figure 6-1, which may be helpful in establishing an initial estimate.
-The value of *SCF* can also be used to account for other factors, such
-as losses of snow due to interception and sublimation not accounted for
-in the model. Anderson (1973) states that both losses are usually small
-compared to the gage catch deficiency.
-
-As discussed in Section 2.3, air temperature data is supplied to a SWMM
-data set from either a user-generated time series or from a climate
-file. If a time series is used, the entries represent instantaneous
-temperature readings at given points in time. Linear interpolation is
-used to obtain temperature values for times that fall in between those
-recorded in the time series. If a climate file is used, then a
-continuous record of maximum and minimum daily temperatures is provided.
-The sinusoidal interpolation method described in Section 2.4 is used to
-obtain an instantaneous value at any point in time during a day based on
-the day's max-min values. (Any missing days in the record are filled in
-with the max-min values from the previous day).
-
-During the simulation, melt is generated at each time step using a
-degree-day type equation during dry weather and a heat balance equation
-during rainfall periods. The latter equation makes an adjustment for
-wind speed (higher melt rates at higher wind speeds). The input of wind
-speed data to the program was discussed in Section 2.4. There are two
-options: 1) as average values for each month of the year, or 2) as daily
-values from the same climate file used to supply daily max-min
-temperatures. Should wind speed data not be available, the adjustment to
-the melt equation is simply ignored.
-
-The coefficients used in the degree-day melt equation vary sinusoidally,
-from a maximum on June 21 to a minimum on December 21. In addition, a
-record of the cold content of the snow is maintained. Thus, before melt
-can occur, the pack must be "ripened," that is, heated to a specified
-base temperature. Specified, constant areas of each subcatchment may be
-designated as snow covered, or, following the practice of melt
-computations in natural basins, "areal depletion curves" may be used to
-describe the spatial extent of snow cover as the pack melts. For
-instance, shaded areas would be expected to retain a snow cover longer
-than exposed areas. Thus, the snow covered area of each subcatchment
-changes with time during the simulation. Melt, after routing through the
-remaining snow pack, is combined with rainfall to form the spatially
-weighted "effective rainfall" for overland flow routing.
-
-

-snow-scf.png
-
Figure 6‑1 Typical gage catch deficiency
-correction (Anderson, 2006, p. 8).

-

-
-### 6.2.3 Subcatchment Partitioning
-
-Just as it was convenient to partition a subcatchment into three
-distinct areas for computing runoff (a pervious area and impervious
-areas both with and without depression storage -- see Section 3.2), the
-same is true for snowmelt. The partitioning is made to facilitate the
-modeling of both snow removal (i.e. plowing) operations and the areal
-depletion phenomenon. It uses the same fractions of pervious and total
-impervious areas as for runoff, but instead of dividing the impervious
-area on the presence or absence of depression storage, it does so based
-on snow removal capability. That is, one fraction of the impervious area
-can be subjected to snow removal but not areal depletion while the
-reverse is true for the remaining fraction. Streets, sidewalks, and
-parking lots would fall into the first category, which can be considered
-almost normally bare of snow. Rooftops would better fit the second.
-Figure 6-2 illustrates the subcatchment partitioning used for snowmelt
-and compares it with the one used for runoff.
-
-[]{#_Toc426447699 .anchor}**Figure 6‑2 Subcatchment partitionings used
-for snowmelt and runoff.**
-
-A separate accounting is kept for snow accumulation and melting from
-each of these fractions (pervious, plowable impervious, and remaining
-impervious). After snowmelt calculations are made at the start of each
-time step, the net precipitation over the plowable and remaining
-impervious areas are summed together and then, for the purpose of
-computing runoff, are re-distributed between the fractions of impervious
-areas with and without depression storage. Because the pervious areas
-for runoff and snowmelt are the same, the snowmelt result over this
-sub-area can be used directly for computing pervious area runoff.
-
-### 6.2.4 Redistribution and Snow Removal
-
-Snow removal practices form a major difference between the snow
-hydrology of urban and rural areas. Much of the snow cover may be
-completely removed from heavily urbanized areas, or plowed into windrows
-or piles, with melt characteristics that differ markedly from those of
-undisturbed snow. Management practices in cities vary according to
-location, climate, topography and the storm itself; they are summarized
-in Table 6.1. It is probably not possible to treat them all in a
-simulation model. However, provision is made to simulate approximately
-some of these practices.
-
-### 6.2.5 Effect on Infiltration
-
-A snow pack tends to insulate the surface beneath it. If ground has
-frozen prior to snowfall, it will tend to remain so, even as the snow
-begins to melt. Conversely, unfrozen ground is generally not frozen by
-subsequent snowfall. The infiltration characteristics of frozen versus
-unfrozen ground are not well understood and depend upon the moisture
-content at the time of freezing. For these and other reasons, SWMM
-assumes that snow has no effect on infiltration or other parameters,
-such as surface roughness or detention storage (although the latter is
-altered in a sense through the use of the free water holding capacity of
-the snow). In addition, all heat transfer calculations cease when the
-water becomes "net runoff". Thus, water in temporary surface storage
-during the overland flow routing will not refreeze as the temperature
-drops and is also subject to evaporation beneath the snow pack.
-
-It is assumed that all snow subject to "redistribution", (e.g., plowing)
-resides on a user-specified fraction of the total impervious area (area
-SA2 in Figure 6-2) that might consist of streets, sidewalks, parking
-lots, etc. (The desired degree of definition may be obtained by using
-several subcatchments, although a coarse schematization, e.g., one or
-two subcatchments, may be sufficient for some continuous simulations.)
-The following five parameters, which can vary by subcatchment, govern
-how snow is removed or re-distributed from this sub-area:
-
-*Fimp*: fraction of current snow transferred to the remaining impervious
-sub-area (SA3)
-
-*Fperv*: fraction of current snow transferred to the pervious area (SA1)
-
-*Fsub*: fraction of current snow transferred to the pervious area of
-another designated subcatchment.
-
-*Fout*: fraction of current snow transferred out of the watershed
-
-*Fimelt*: fraction of current snow converted into immediate melt
-
-An instantaneous redistribution of the current snow depth begins when
-the latter exceeds the user-supplied parameter *WEPLOW.*
-
-*Fimp* or *Fperv* are used if snow is usually windrowed onto adjacent
-impervious or pervious areas. If it is trucked to the pervious area of
-another subcatchment, the fraction *Fsub* will so indicate, or *Fout*
-can be used if the snow is removed entirely from the simulated
-watershed. In the latter case, such removals are tabulated and included
-in the final continuity check. Finally, excess snow may be immediately
-"melted" (i.e., treated as rainfall), using *Fimelt.* The five fractions
-can sum to less than 1.0 in which case some residual snow will remain on
-the surface. See Table ‎6-1 for guidelines on typical levels of service
-for snow and ice control (Richardson et al., 1974). The snow
-redistribution process does not account for snow management practices
-that use chemicals, such as roadway salting. This is handled using the
-melt equations, as described subsequently.
-
-No pollutants are transferred with the snow. The transfers listed above
-are assumed to have no effect on pollutant washoff and regeneration. In
-addition, all the redistribution parameters remain constant throughout
-the simulation and can only represent averages over a snow season.
-
-## 6.3 Governing Equations
-
-### 6.3.1 Overview
-
-Excellent descriptions of the processes of snowmelt and accumulation are
-available in several texts and simulation model reports and in the
-well-known 1956 *Snow Hydrology* report by the Corps of Engineers. The
-important heat budget and melt components are mentioned briefly here;
-any of the above sources may be consulted for detailed explanations. A
-brief justification for the techniques adopted for snowmelt calculations
-in SWMM is presented below.
-
-+----------------+------------------------+----------------+----------------+----------------+----------------+
-| Road           | Level of Service       | Snow Depth to  | Max.           | Full Pavement  | Full Pavement  |
-| Classification |                        | Start Plowing  |                | Clear of Snow  | Clear of Ice   |
-|                |                        |                | Snow Depth on  |                |                |
-|                |                        | (Inches)       | Pavement       | After Storm    | After Storm    |
-|                |                        |                |                |                |                |
-|                |                        |                | (Inches)       | (Hours)        | (Hours)        |
-+:===============+:=======================+================+================+================+================+
-| Low-Speed      | Roadway routinely      | 0.5 to 1       | 1              | 1              | 12             |
-| Multilane      | patrolled during       |                |                |                |                |
-| Urban          | storms                 |                |                |                |                |
-| Expressway     |                        |                |                |                |                |
-|                | All traffic lanes      |                |                |                |                |
-|                | treated with chemicals |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | All lanes (including   |                |                |                |                |
-|                | breakdown lanes)       |                |                |                |                |
-|                | operable at all times  |                |                |                |                |
-|                | but at reduced speeds  |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Occasional patches of  |                |                |                |                |
-|                | well sanded snow pack  |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Roadway repeatedly     |                |                |                |                |
-|                | cleared by echelons of |                |                |                |                |
-|                | plows to minimize      |                |                |                |                |
-|                | traffic disruption     |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Clear pavement         |                |                |                |                |
-|                | obtained as soon as    |                |                |                |                |
-|                | possible               |                |                |                |                |
-+----------------+------------------------+----------------+----------------+----------------+----------------+
-| High Speed     | Roadway routinely      | 1              | 2              | 1.5            | 12             |
-| 4-Lane Divided | patrolled during       |                |                |                |                |
-| Highways;      | storms                 |                |                |                |                |
-| Interstate     |                        |                |                |                |                |
-| System;        | Driving and passing    |                |                |                |                |
-|                | lanes treated with     |                |                |                |                |
-| ADT greater    | chemicals              |                |                |                |                |
-| than 10,000a |                        |                |                |                |                |
-|                | Driving lane operable  |                |                |                |                |
-|                | at all times at        |                |                |                |                |
-|                | reduced speeds         |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Passing lane operable  |                |                |                |                |
-|                | depending on equipment |                |                |                |                |
-|                | availability           |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Clear pavement         |                |                |                |                |
-|                | obtained as soon as    |                |                |                |                |
-|                | possible               |                |                |                |                |
-+----------------+------------------------+----------------+----------------+----------------+----------------+
-| Primary        | Roadway is routinely   | 1              | 2.5            | 2              | 24             |
-| Highways;      | patrolled during       |                |                |                |                |
-|                | storms                 |                |                |                |                |
-| Undivided 2    |                        |                |                |                |                |
-| and 3 lanes;   | Mostly clear pavement  |                |                |                |                |
-|                | after storm stops      |                |                |                |                |
-| ADT            |                        |                |                |                |                |
-| 500-5000a    | Hazardous areas        |                |                |                |                |
-|                | receive treatment of   |                |                |                |                |
-|                | chemicals or abrasive  |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Remaining snow and ice |                |                |                |                |
-|                | removed when thawing   |                |                |                |                |
-|                | occurs                 |                |                |                |                |
-+----------------+------------------------+----------------+----------------+----------------+----------------+
-| Secondary      | Roadway is patrolled   | 2              | 3              | 3              | 48             |
-| Roads          | at least once during a |                |                |                |                |
-|                | storm                  |                |                |                |                |
-| ADT less than  |                        |                |                |                |                |
-| 500a         | Bare left-wheel track  |                |                |                |                |
-|                | with intermittent snow |                |                |                |                |
-|                | cover                  |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Hazardous areas are    |                |                |                |                |
-|                | plowed and treated     |                |                |                |                |
-|                | with chemicals or      |                |                |                |                |
-|                | abrasives as a first   |                |                |                |                |
-|                | order of work          |                |                |                |                |
-|                |                        |                |                |                |                |
-|                | Full width of road is  |                |                |                |                |
-|                | cleared as equipment   |                |                |                |                |
-|                | becomes available      |                |                |                |                |
-+----------------+------------------------+----------------+----------------+----------------+----------------+
-| aADT -- average daily traffic                                                                             |
-+-------------------------------------------------------------------------------------------------------------+
-
-: []{#_Toc430249168 .anchor}**Table 6‑1 Guidelines for level of service
-in snow and ice control (Richardson et al., 1974)**
-
-[Snowpack Heat Budget]{.underline}
-
-Heat may be added or removed from a snowpack by the following processes:
-
-- Absorbed solar radiation (addition).
-
-- Net long wave radiation exchange with the surrounding environment
-  (addition or removal).
-
-- Convective (diffusive) transfer of sensible heat from/to air (addition
-  or removal).
-
-- Release of latent heat of vaporization by condensate (addition) or,
-  the opposite, its removal by sublimation (removing the latent heat of
-  vaporization plus the latent heat of fusion).
-
-- Advection of heat by rain (addition) plus addition of the heat of
-  fusion if the rain freezes.
-
-- Conduction of heat from underlying ground (removal or addition).
-
-The terms may be summed, with appropriate signs, and equated to the
-change of heat stored in the snowpack to form a conservation of heat
-equation. All of the processes listed above vary in relative importance
-with topography, season, climate, local meteorological conditions, etc.,
-but items 1-4 are the most important. Item 5 is of less importance on a
-seasonal basis, and item 6 is often neglected. A snow pack is termed
-"ripe" when any additional heat will produce liquid runoff. Rainfall
-(item 5) will rapidly ripen a snowpack by release of its latent heat of
-fusion as it freezes in subfreezing snow, followed by quickly filling
-the free water holding capacity of the snow.
-
-[Melt Prediction Techniques]{.underline}
-
-Prediction of melt follows from prediction of the heat storage of the
-snow pack. Energy budget techniques are the most exact formulation since
-they evaluate each of the heat budget terms individually, requiring as
-meteorological input quantities such as solar radiation, air
-temperature, dew point or relative humidity, wind speed, and
-precipitation. Assumptions must be made about the density, surface
-roughness and heat and water storage (mass balance) of the snow pack as
-well as on related topographical and vegetative parameters. Further
-complications arise in dealing with heat conduction and roughness of the
-underlying ground and whether or not it is permeable.
-
-Several models treat some or all of these effects individually, for
-instance, the NWS river forecast system developed by Anderson (1976).
-Interestingly, under many conditions he found that results obtained
-using his energy balance model were not significantly better than those
-obtained using simpler (e.g., degree-day or temperature-index)
-techniques in his earlier model (Anderson, 1973). The more open and
-variable the condition, the better is the energy balance technique.
-Closest agreement between his two models was for heavily forested
-watersheds.
-
-The minimal data needed to apply an energy balance model are a good
-estimate of incoming solar radiation, plus measurements of air
-temperature, vapor pressure (or dew point or relative humidity) and wind
-speed. All of these data, except possibly solar radiation, are available
-for at least one location (e.g., the airport) for almost all reasonably
-sized cities. Even solar radiation measurements are taken at several
-locations in most states. Predictive techniques are also available, for
-solar radiation and other parameters, based on available measurements
-(TVA, 1972; Franz, 1974).
-
-[Choice of Predictive Method]{.underline}
-
-Two major reasons suggest that simpler, e.g., temperature-index,
-techniques should be used for simulation of snowmelt and accumulation in
-urban areas. First, even though required meteorological data for energy
-balance models are likely to be available, there is a large local
-variation in the magnitude of these parameters due to the urbanization
-itself. For example, radiation melt will be influenced heavily by
-shading of buildings and albedo (reflection coefficient) reduced by
-urban pollutants. In view of the many unknown properties of the snowpack
-itself in urban areas, it may be overly ambitious to attempt to predict
-melt at all! But at the least, simpler techniques are probably all that
-are warranted. They have the added advantage of considerably reducing
-the already extensive input data to a model such as SWMM.
-
-Second, the objective of the modeling should be examined. Although it
-may contribute, snowmelt seldom causes flooding or hydrologic extremes
-in an urban area itself. Hence, exact prediction of flow magnitudes does
-not assume nearly the importance it has in the models of, say, the NWS,
-in which river flood forecasting for large mountainous catchments is of
-paramount importance. For planning purposes in urban areas, exact
-quantity (or quality) prediction is not the objective in any event;
-rather, these efforts produce a statistical evaluation of a complex
-system and help identify critical time periods for more detailed
-analysis.
-
-For these and other reasons, simple snowmelt prediction techniques are
-incorporated into SWMM. Anderson's NWS (1973) temperature-index method
-is also well documented and tested, and is used in SWMM. As described
-subsequently, the snowmelt modeling follows Anderson's work in several
-areas, not just in the melt equations. It may be noted that the STORM
-model (Corps of Engineers, 1977; Roesner et al., 1974) also uses the
-temperature-index method for snowmelt prediction, in a considerably less
-complex manner than is programmed in SWMM.
-
-### 6.3.2 Melt Equations
-
-Anderson's NWS model (1973) treats two different melt situations: with
-and without rainfall. When there is rainfall (greater than 0.1 in/hr or
-2.5 mm/hr in the NWS model, (greater than 0.02 in/hr or 0.51 mm/hr in
-SWMM), accurate assumptions can be made about several energy budget
-terms. These are: zero solar radiation, incoming long wave radiation
-equals blackbody radiation at the ambient air temperature, the snow
-surface temperature is 32° F (0° C), and the dew point and rain water
-temperatures equal the ambient air temperature. Anderson combines the
-appropriate terms for each heat budget component into one equation for
-the melt rate *SMELT*:
-
-+--------------------------------------------------------------------------------------------------------------------+--------+
-| > $$SMELT = \left( 0.001167 + 7.5\gamma U_{A} + 0.007i \right)\left( T_{a} - 32 \right) + 8.5U_{A}(e_{a} - 0.18)$$ | (6-1)  |
-+====================================================================================================================+========+
-
-where
-
-| Symbol | Description |
-| :--- | :--- |
-| *SMELT* | melt rate (in/hr) |
-| *Ta* | air temperature (° F) |
-| *γ* | psychrometric constant (in Hg/° F) |
-| *UA* | wind speed adjustment factor (in/in Hg -- hr) |
-| *i* | rainfall intensity (in/hr) |
-| *ea* | saturation vapor pressure at air temperature (in Hg). |
-
-The origin of the numerical constants found in Equation 6-1 is given by
-Anderson (1973), and reflect units conversions as well as U.S. customary
-units for physical properties. The psychrometric constant, γ, is
-calculated as:
-
-+-------------------------------------------------------------+--------+
-| > $$\gamma = 0.000359P_{a}$$                                | (6-2)  |
-+=============================================================+========+
-
-where *Pa* is the atmospheric pressure (in Hg). The latter, in turn,
-is calculated as a function of elevation, z:
-
-+----------------------------------------------------------------------------+--------+
-| > $$P_{a} = 29.9 - 1.02(\frac{z}{1000) + 0.0032{(\frac{z}{1000)}}^{2.4}}$$ | (6-3)  |
-+============================================================================+========+
-
-where z is the average catchment elevation (ft). The wind adjustment
-factor, *UA*, accounts for turbulent transport of sensible heat and
-water vapor. Anderson (1973) gives:
-
-+-------------------------------------------------------------+--------+
-| > $$U_{A} = 0.006U$$                                        | (6-4)  |
-+=============================================================+========+
-
-where *U* is the average wind speed 1.64 ft (0.5 m) above the snow
-surface (mi/hr). In practice, available wind data are used and are
-seldom corrected for the actual elevation of the anemometer. Section
-6.2.2 (as well as Section 2.6) discusses how wind data are supplied to
-SWMM. If no such data are available on a particular date then *UA* is
-set equal to *0*. Finally, the saturation vapor pressure, *ea*, is
-given accurately by the convenient exponential approximation:
-
-+------------------------------------------------------------------------------------------+--------+
-| > $$e_{a} = 8.1175 \times 10^{6}\exp\left( \frac{- 7701.544}{T_{a} + 405.0265} \right)$$ | (6-5)  |
-+==========================================================================================+========+
-
-During non-rain periods, melt is calculated as a linear function of the
-difference between the air temperature, *Ta*, and a base temperature,
-*Tbase*, using a degree-day or temperature-index type equation:
-
-+-------------------------------------------------------------+--------+
-| > $$SMELT = DHM\left( T_{a} - Tbase \right)$$               | (6-6)  |
-+=============================================================+========+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *SMELT* | melt rate (in/hr), |
-| *Ta* | air temperature (° F) |
-| *Tbase* | base melt temperature (° F) |
-| *DHM* | melt coefficient (in/hr-° F) |
-
-Different values of *Tbase* and *DHM* may be used for each of the three
-types of snow surfaces within a subcatchment. For instance, these
-parameters may be used to account for street salting, which lowers the
-base melt temperature. If desired, rooftops could be simulated using a
-lower value of *Tbase* to reflect heat transfer vertically through the
-roof. Suggested values for *Tbase* and *DHM* are provided in the
-Parameter Estimates section (6.7) below.
-
-During the simulation, *Tbase* remains constant, but *DHM* is allowed a
-seasonal variation, as illustrated in Figure ‎6-3. Following Anderson
-(1973), the minimum melt coefficient is assumed to occur on December 21
-and the maximum on June 21. Parameters *DHMIN* and *DHMAX* are supplied
-as input for the three snowpack areas of each subcatchment, and
-sinusoidal interpolation is used to produce a value of *DHM* that is
-constant over each day of the year:
-
-+-----------------------------------------------------------------------------------------------------------------------------------------+-------+
-| > $$DHM = \left( \frac{DHMAX + DHMIN}{2} \right) + \left( \frac{DHMAX - DHMIN}{2} \right)\sin\left( \frac{\pi}{182}(day - 81) \right)$$ | (6-7) |
-+=========================================================================================================================================+=======+
-
-where
-
-| Symbol | Description |
-| :--- | :--- |
-| *DHMIN* | minimum melt coefficient, occurring Dec. 21 (in/hr-°F) |
-| *DHMAX* | maximum melt coefficient, occurring June 21 (in/hr-°F) |
-| *day* | number of the day of the year. |
-
-No special allowance is made for leap year. However, the correct date
-(and day number) is maintained.
-
-![Cmelt](VolumeI/media/media/image38.png){width="5.427083333333333in"
-height="2.8125in"}
-
-[]{#_Toc426447700 .anchor}**Figure 6‑3 Seasonal variation of melt
-coefficients.**
-
-### 6.3.3 Snow Pack Heat Exchange
-
-During subfreezing weather, the snow pack does not melt, and heat
-exchange with the atmosphere can either warm or cool the pack. The
-difference between the heat content of the subfreezing pack and the
-(higher) base melt temperature is taken as positive and termed the "cold
-content" of the pack. No melt will occur until the cold content is
-reduced to zero. It is maintained in inches (or feet) of water
-equivalent. That is, a cold content of 0.1 in. (2.5 mm) is equivalent to
-the heat required to melt 0.1 in. (2.5 mm) of snow. Following Anderson
-(1973), the heat exchange altering the cold content within each 6-hour
-period is proportional to the difference between the air temperature,
-*Ta*, and an antecedent temperature index, *ATI*, indicative of the
-temperature of the surface layer of the snow pack. The value of *ATI* is
-updated at the start of each time step as follows:
-
-+-------------------------------------------------------------+--------+
-| > $$ATI \leftarrow ATI + {TIPM}_{t}(T_{a} - ATI)$$          | (6-8)  |
-+=============================================================+========+
-
-where *TIPMt* is given by (Anderson, 2006):
-
-+-------------------------------------------------------------+--------+
-| > $${TIPM}_{t} = 1 - {(1 - TIPM)}^{\mathrm{\Delta}t/6}$$    | (6-9)  |
-+=============================================================+========+
-
-for a time step *∆t* in hours. *TIPM* is a 6-hour weighting factor whose
-value lies between *0* and *1.0*. The value of *ATI* is not allowed to
-exceed *Tbase*, and when snowfall is occurring, *ATI* takes on the
-current air temperature.
-
-The weighting factor *TIPM* is a user-supplied constant that applies
-over the entire watershed. It is an indication of the thickness of the
-"surface" layer of snow. Values less than *0.1* give significant weight
-to temperatures over the past week or more and would thus indicate a
-deeper layer than values greater than, say, *0.5*, which would
-essentially only give weight to temperatures during the past day. In
-other words, the pack will both warm and cool more slowly with low
-values of *TIPM*. Anderson states that *TIPM* *= 0.5* has given
-reasonable results in natural watersheds, although there is some
-evidence that a lower value may be more appropriate. No calibration has
-been attempted on urban watersheds.
-
-After the antecedent temperature index is calculated, the cold content
-*COLDC* is changed by an amount
-
-+----------------------------------------------------------------------------------------------------+--------+
-| > $$\mathrm{\Delta}CC = RNM \times DHM \times \left( ATI - T_{a} \right) \times \mathrm{\Delta}t$$ | (6-10) |
-+====================================================================================================+========+
-
-where
-
-| Symbol | Description |
-| :--- | :--- |
-| *∆CC* | change in cold content (inches water equivalent) |
-| *RNM* | ratio of negative melt coefficient to melt coefficient, |
-| *DHM* | melt coefficient (in/hr-° F) |
-| *ATI* | antecedent temperature index (°F) |
-| *Δt* | time step (hr). |
-
-Note that the cold content is increased, (*∆CC* is positive) when the
-air temperature is less (colder) than the antecedent temperature index.
-Since heat transfer during non-melt periods is less than during melt
-periods, Anderson uses a "negative melt coefficient" in the heat
-exchange computation. SWMM computes this simply as a fraction, *RNM*, of
-the melt coefficient, *DHM*. Hence, the negative melt coefficient, i.e.,
-the product ![](VolumeI/media/media/image39.wmf)also varies seasonally. As
-with *TIPM*, a single user-supplied value of *RNM* is used throughout
-the study area. A typical value is 0.6.
-
-During melting periods, cold content of the pack is reduced by an
-amount:
-
-+----------------------------------------------------------------------+--------+
-| > $$\mathrm{\Delta}CC = - SMELT \times RNM \times \mathrm{\Delta}t$$ | (6-11) |
-+======================================================================+========+
-
-with an equal reduction made in *SMELT*. Thus no liquid melt actually
-occurs until the snow pack cold content is reduced to *0*. Even then,
-runoff will not occur, until the "free water holding capacity" of the
-snow pack is filled. This is discussed subsequently. The value of
-*COLDC* is in units of inches of water equivalent over the area in
-question. The cold content "volume," equivalent to calories or BTUs, is
-obtained by multiplying by the area. Finally, an adjustment is made to
-Equations 6-10 and 6-11 depending on the areal extent of snow cover.
-This is discussed below.
-
-## 6.4 Areal Depletion
-
-The snow pack on a catchment rarely melts uniformly over the total area.
-Rather, due to shading, drifting, topography, etc., certain portions of
-the catchment will become bare before others, and only a fraction,
-*ASC*, will be snow covered. This fraction must be known in order to
-compute the snow covered area available for heat exchange and melt, and
-to know how much rain falls on bare ground. Because of year to year
-similarities in topography, vegetation, drift patterns, etc., the
-fraction, *ASC*, is primarily a function of the amount of snow on the
-catchment at a given time; this function, called an "areal depletion
-curve", is discussed below. These functions are used as an option to
-describe the seasonal growth and recession of the snow pack. For short,
-single event simulation, fractions of snow covered area may be fixed for
-the pervious and impervious areas of each subcatchment.
-
-As used in most snowmelt models, it is assumed that there is a depth,
-*SI*, above which there will always be *100* percent cover. In some
-models, the value of *SI* is adjusted during the simulation; in SWMM it
-remains constant. The amount of snow present at any time is indicated by
-the state variable *WSNOW*, which is the depth (water equivalent) over
-each of the three possible snow covered areas of each subcatchment (see
-Figure ‎6-2). This depth is made non-dimensional by dividing it by *SI*
-for use in calculating *ASC*. Thus, an areal depletion curve (ADC) is a
-plot of *WSNOW / SI* versus *ASC*; a typical ADC for a natural catchment
-is shown in Figure 6-4. For values of the ratio *AWESI = WSNOW / SI*
-greater than *1.0*, *ASC = 1.0*, that is, the area is *100* percent snow
-covered.
-
-

-
-
Figure 6‑4 Typical areal depletion curve
-for natural area (Anderson, 1973, p. 3-15) and temporary curve for new
-snow.

-

-
-Some of the implications of different functional forms of the ADC may be
-seen in Figure ‎6-5. Since the program maintains snow quantities,
-*WSNOW*, as the depth over the total area, *AT*, the actual snow
-depth, *WS*, and actual area covered, *AS*, are related by continuity:
-
-+-------------------------------------------------------------+--------+
-| > $$WSNOW \times A_{T} = WS \times AS$$                     | (6-12) |
-+=============================================================+========+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *WSNOW* | depth of snow over total area (inches water equivalent) |
-| *AT* | total area (ft2), |
-| *WS* | actual snow depth (inches water equivalent), and |
-| *AS* | snow covered area (ft2). |
-
-In terms of parameters shown on the ADC, this equation may be rearranged
-to read:
-
-+--------------------------------------------------------------------------------------------------------------------------------+--------+
-| > $$AWESI = \frac{WSNOW}{SI = \left( \frac{WS}{SI} \right)\left( \frac{AS}{A_{T}} \right) = \left( \frac{WS}{SI} \right)ASC}$$ | (6-13) |
-+================================================================================================================================+========+
-
-This equation can be used to compute the actual snow depth, *WS*, from
-known ADC parameters, if desired. It is unnecessary to do this in the
-program, but it is helpful in understanding the curves of Figure ‎6-5.
-Thus:
-
-+-------------------------------------------------------------+--------+
-| > $$WS = \left( \frac{AWESI}{ASC} \right)\ SI$$             | (6-14) |
-+=============================================================+========+
-
-Consider the three ADC curves B, C and D of Figure 6-5. For curve B,
-*AWESI* is always less than *ASC*; hence *WS* is always less than *SI*
-as shown in Figure 6-5d. For curve C, *AWESI = ASC*, hence *WS = SI*, as
-shown in Figure ‎6-5e. Finally, for curve D, *AWESI* is always greater
-than *ASC*; hence, *WS* is always greater than *SI*, as shown in Figure
-‎6-5f. Constant values of *ASC* at *100* percent cover and *40* percent
-cover are illustrated in Figure ‎6-5c, curve A, and Figure 6-5g, curve E,
-respectively. At a given time (e.g., *t1* in Figure ‎6-5), the area of
-each snow depth versus area curve is the same and equal to
-$AWESI \times SI$, (e.g., *0.8 SI* for time *t1*).
-
-Curve B on Figure ‎6-5a is the most common type of ADC occurring in
-nature, as shown in Figure 6-4. The convex curve D requires some
-mechanism for raising snow levels above their original depth, *SI*. In
-nature, drifting provides such a mechanism; in urban areas, plowing and
-windrowing could cause a similar effect. A complex curve could be
-generated to represent specific snow removal practices in a city.
-However, the program uses only one ADC curve for all impervious areas
-(e.g., area SA3 of Figure 6-2 for all subcatchments) and only one ADC
-curve for all pervious areas (e.g., area SA1 of Figure 6-2 for all
-subcatchments). This limitation should not hinder an adequate simulation
-since the effects of variations in individual locations are averaged out
-in the city-wide scope of most continuous simulations.
-
-The program does not require the ADC curves to pass through the origin,
-*AWESI = ASC = 0*; they may intersect the abscissa at a value of *ASC \>
-0* in order to maintain some snow covered area up until the instant that
-all snow disappears (see Figure ‎6-4). However, the curves may not
-intersect the ordinate, *AWESI \> 0* when *ASC = 0*.
-
-The preceding paragraphs have centered on the situation where a depth of
-snow greater than or equal to *SI* has fallen and is melting. (The ADC
-curves are not employed until *WSNOW* becomes less than *SI*.) The
-situation when there is new snow needs to be discussed, starting from
-both zero and non-zero initial cover. The SWMM procedure again follows
-Anderson's NWS method (1973).
-
-

-ii_07
-
Figure 6‑5 Effect of snow cover on areal
-depletion curves.

-

-
-When there is new snow and *WSNOW* is already greater than or equal to
-*SI*, *ASC* remains unchanged at *1.0*. However, when there is new snow
-on bare or partially bare ground, it is assumed that the total area is
-*100* percent covered for a period of time, and a "temporary" ADC is
-established as shown in Figure ‎6-4. This temporary curve returns to the
-same point on the ADC as the snow melts. Let the depth of new snow be
-*SNO,* measured in equivalent inches of water. Then the value of *AWESI*
-will be changed from an initial value of *AWE* to a new value of *SNEW*
-by:
-
-+-------------------------------------------------------------+--------+
-| > $$SNEW = AWE + \frac{SNO}{SI}$$                           | (6-15) |
-+=============================================================+========+
-
-It is assumed that the areal snow cover remains at *100* percent until
-*25* percent of the new snow melts. This defines the value of *SBWS* of
-Figure 6-4 as:
-
-+-------------------------------------------------------------+--------+
-| > $$SBWS = AWE + 0.75\left( \frac{SNO}{SI} \right)$$        | (6-16) |
-+=============================================================+========+
-
-Anderson (1973) reports low sensitivity of model results to the
-arbitrary *25* percent assumption. When melt produces a value of *AWESI*
-between *SBWS* and *AWE*, linear interpolation of the temporary curve is
-used to find *ASC* until the actual ADC curve is again reached. When new
-snow has fallen, the program thus maintains values of *AWE*, *SBA* and
-*SBWS* (Figure ‎6-4).
-
-The interactive nature of melt and fraction of snow cover is not
-accounted for during each time step. It is sufficient to use the value
-of *ASC* at the beginning of each time step, especially with a short
-(e.g., one-hour) time step for the simulation.
-
-The fraction of area that is snow covered, *ASC*, is used to adjust 1)
-the volume of melt that occurs, and 2) the "volume" of cold content
-change, since it is assumed that heat transfer occurs only over the snow
-covered area. The melt rate is computed from either of the two equations
-for *SMELT*. The snow depth is then reduced by an amount *∆WSNOW* which
-equals:
-
-+-----------------------------------------------------------------------+--------+
-| > $$\mathrm{\Delta}WSNOW = SMELT \times ASC \times \mathrm{\Delta}t$$ | (6-17) |
-+=======================================================================+========+
-
-and includes appropriate continuity checks to avoid melting more snow
-than is there, etc.
-
-Cold content changes are also adjusted by the value of *ASC*. Thus,
-using Equation ‎6-10, cold content, *COLDC*, is changed by an amount
-*∆CC* given by:
-
-+---------------------------------------------------------------------------------------------------------------+--------+
-| > $$\mathrm{\Delta}CC = RNM \times DHM \times \left( ATI - T_{a} \right) \times \mathrm{\Delta}t \times ASC$$ | (6-18) |
-+===============================================================================================================+========+
-
-where variables are as previously defined. Again there are program
-checks for negative values of *COLDC*, etc.
-
-## 6.5 Net Runoff
-
-Production of melt does not necessarily mean that there will be liquid
-runoff at a given time step since a snow pack, acting as a porous medium
-with a "porosity," has a certain "free water holding capacity" at a
-given instant in time. Conway and Benedict (1994) describe the physics
-of the various processes underway as melt infiltrates into a snowpack.
-Following PR-JFM (1976a, 1976b), this capacity is taken to be a constant
-fraction, *FWFRAC*, of the variable snow depth, *WSNOW*, at each time
-step. This volume (depth) must be filled before runoff from the snow
-pack occurs. The program maintains the depth of free water, *FW*, inches
-of water, for use in these computations. When
-![](VolumeI/media/media/image42.wmf), the snow pack is fully ripe. The
-procedure is sketched in Figure ‎6-6.
-
-

-ii_08
-
Figure 6‑6 Schematic of liquid water
-routing through snow pack.

-

-
-The inclusion of the free water holding capacity via this simple
-reservoir-type routing delays and somewhat attenuates the appearance of
-liquid runoff. When rainfall occurs, it is added to the melt rate
-entering storage as free water. No free water is released when melt does
-not occur, but remains in storage, available for release when the pack
-is again ripe. This re-frozen free water is not included in subsequent
-cold content or melt computations.
-
-Melt from snow covered areas and rainfall on bare surfaces is area
-weighted and combined to produce net runoff onto the surface as follows:
-
-+-------------------------------------------------------------+--------+
-| > $$RI = ASC \times SMELT + (1.0 - ASC) \times i$$          | (6-19) |
-+=============================================================+========+
-
-where *RI* is the net equivalent precipitation input onto the
-subcatchment surface (in/hr) and *i* is the liquid rainfall intensity
-(in/h). *RI* is used in place of the externally supplied rainfall value
-in subsequent overland flow and infiltration calculations.
-
-If immediate melt is produced through the use of the snow redistribution
-fraction *Fimelt* it is added to the last equation. Furthermore, all
-melt calculations are ended when the depth of snow water equivalent
-becomes less than 0.001 in. (0.025 mm), and any remaining snow and free
-water are converted to immediate melt and added to Equation ‎6-19.
-
-## 6.6 Computational Scheme
-
-Snowmelt computations are a sub-procedure implemented as part of SWMM's
-runoff calculations. They are made at each runoff time step, for each
-subcatchment that has snow pack parameters assigned to it, immediately
-after atmospheric precipitation has been determined. This is at Step 3a
-of the runoff procedure described in Section 3.4. The snowmelt routine
-returns an adjusted precipitation rate (in/h), consisting of liquid
-rainfall and/or snowmelt, over each runoff sub-area of the subcatchment.
-These rates serve as the actual precipitation input used in the
-remainder of the surface runoff computation. The steps used to compute
-snow accumulation and snowmelt are listed in the sidebar below.
-
-Step 5 of the snowmelt process uses Areal Depletion curves to compute
-the fraction of snow covered area (*ASC*) for both the pervious (SA1)
-and impervious (SA3) areas subject to areal depletion. Note that at this
-stage of the calculations any snow that has fallen during the time step
-has already been added on to the accumulated snow depth *WSNOW*. The
-scheme used to update the fraction of snow covered area is described in
-the sidebar below.
-
-## 6.7 Parameter Estimates
-
-Table 6-2 summarizes the parameters used by the snowmelt routine as well
-as their typical range of values. The first four entries (*SNOTMP, SCF,
-TIPM*, and *RNM*) are system-wide parameters that apply to the entire
-study area. Values for the remaining parameters are specified for each
-snow surface within each subcatchment where snowmelt can occur. SWMM
-uses a **Snow Pack** object to bundle together a common set of these
-parameters that can be applied to an entire group of subcatchments. This
-helps reduce the amount of input that a user must provide.
-
-| **Parameter** | **Meaning** | **Typical Range** |
-| --- | --- | --- |
-| *SNOTMP* | dividing temperature between snowfall and rainfall (°F) | 32 to 36 |
-| *SCF* | rain gage snow capture factor (ratio) | 1 to 2 |
-| *TIPM* | ATI weighting factor (fraction) | 0.5 |
-| *RNM* | negative melt ratio (fraction) | 0.6 |
-| *WEPLOW* | depth at which snow redistribution begins (inches) | 0.5 to 2 |
-| *Tbase* | temperature at which snow begins to melt (°F) | 25 to 32 |
-| *DHMIN* | melt coefficient for December 21 (in/hr-°F) | 0.001 to 0.003 |
-| *DHMAX* | melt coefficient for June 21 (in/hr-°F) | 0.006 to 0.007 |
-| *SI* | depth at which surface remains 100% snow covered (inches) | 1 to 4 |
-| *FWFRAC* | free water fraction to produce liquid runoff from pack | 0.02 to 0.10 |
-
-  : []{#_Toc430249169 .anchor}**Table 6‑2 Summary of snowmelt parameters
-  (in US customary units)**
-
-Snowmelt results will be sensitive to the values used for the degree-day
-melt coefficient *DHM.* In rural areas, the melt coefficient ranges from
-0.03 ­ 0.15 in/day-°F (1.4 ­ 6.9 mm/day-°C) or from 0.001 ­ 0.006 in/h-°F
-(0.057 ­ 0.29 mm/h-°C). Gray and Prowse (1993) provide a useful summary
-of such equations. In urban areas, values may tend toward the higher
-part of the range due to compression of the pack by vehicles,
-pedestrians, etc. and due to reflection of radiation onto the snow from
-adjacent buildings (Semádeni-Davies, 2000). Most of the available data
-are summarized by Semádeni-Davies (2000). Bengtsson (1981) and
-Westerström (1981) describe results of urban snowmelt studies in Sweden,
-including degree-day coefficients, which range from 3 to 8 mm/°C-day
-(0.07 ­ 0.17 in/°F-day). Additional data for snowmelt on an asphalt
-surface (Westerström, 1984) gave degree-day coefficients of 1.7 ­ 6.5
-mm/°C-day (0.04 ­ 0.14 in/°F-day). Values of *Tbase* will probably range
-between 25 and 32 °F (-4 and 0 °C). Unfortunately, few urban area data
-exist to define adequately appropriate modified values for *Tbase* and
-*DHM*, and they may be considered calibration parameters.
-
-The value of *FWFRAC* will normally be less than 0.10 and usually
-between 0.02 ­ 0.05 for deep snow packs (*WSNOW* \> 10 inches or 254 mm
-water equivalent). However, Anderson (1973) reports that a value of 0.25
-is not unreasonable for shallow snow packs that may form a slush layer.
-
-An additional set of parameters not listed in Table 6-2 are those used
-to characterize the Areal Depletion Curves (ADCs). An ADC is
-characterized in SWMM by providing values of ASC (fraction of area with
-snow cover) for snow depth ratios (ratio of depth to depth at 100% areal
-coverage) that range from 0.0 to 0.9 in 0.1 increments. (By definition
-ASC is 1.0 for a snow depth ratio of 1.0). Table 6.3 lists the points of
-the ADC shown previously in Figure 6-4 that is typical of natural areas.
-Two ADC curves, one for pervious area and one for impervious areas, are
-assumed to apply across the entire watershed. The curves are not
-required to pass through the origin, *AWE* = *ASC = 0*; they may
-intersect the abscissa at a value of *ASC \> 0* in order to maintain
-some snow covered area up until the instant that all snow disappears
-(see Figure ‎6-4). However, the curves may not intersect the ordinate,
-*AWE* must be greater than 0 when *ASC = 0*. A curve whose *ASC* values
-are all 1.0 causes the areal depletion phenomenon to be ignored.
-
-| **Depth Ratio** | **ASC** |
-| --- | --- |
-| 0.0 | 0.10 |
-| 0.1 | 0.35 |
-| 0.2 | 0.53 |
-| 0.3 | 0.66 |
-| 0.4 | 0.75 |
-| 0.5 | 0.82 |
-| 0.6 | 0.87 |
-| 0.7 | 0.92 |
-| 0.8 | 0.95 |
-| 0.9 | 0.98 |
-
-  : []{#_Toc430249170 .anchor}**Table 6‑3 Typical areal depletion curve
-  for natural areas**
-
-## 6.8 Numerical Example
-
-The following numerical example illustrates the dynamic nature of snow
-accumulation, snow melt, and subsequent runoff. A one acre, completely
-impervious subcatchment is modeled over an 18 day period during which
-temperature fluctuates between 0 and 50 °F. The simulation begins with 1
-inch of snow accumulation over the subcatchment. Table 6-4 lists the
-relevant subcatchment and snowpack parameters, while Tables 6-5 and 6-6
-list the daily temperatures and hourly precipitation, respectively, used
-in the simulation. The meteorological conditions are recorded data for
-Raleigh, NC. Neither snow removal nor areal depletion is considered.
-
-| **Parameter** | **Value** |
-| --- | --- |
-| Area (acres) | 1 |
-| Width (ft) | 140 |
-| Slope (%) | 0.5 |
-| Percent Impervious | 100 |
-| Roughness Coefficient | 0.01 |
-| Depression Storage (in) | 0.25 |
-| Minimum Melt Coefficient (in/h/°F) | 0.001 |
-| Maximum Melt Coefficient (in/h/°F) | 0.006 |
-| Base Temperature (*Tbase*) (°F) | 30 |
-| Free Water Fraction (*FWFRAC*) | 0.05 |
-| Initial Snow Depth (in) | 1.0 |
-| Initial Free Water (in) | 0.2 |
-| Dividing Temperature (*SNOTMP*) (°F) | 34 |
-| ATI Weighting Factor (TIPM) | 0.5 |
-| Negative Melt Ratio (RNM) | 0.6 |
-| Latitude (°) | 42 |
-
-  : []{#_Toc430249171 .anchor}**Table 6‑4 Subcatchment and snow pack
-  parameters for illustrative snowmelt example**
-
-| **Month/Day** | **Maximum Temperature (°F)** | **Minimum Temperature (°F)** |
-| --- | --- | --- |
-| 1/24 | 49 | 30 |
-| 1/25 | 50 | 32 |
-| 1/26 | 46 | 28 |
-| 1/27 | 50 | 27 |
-| 1/28 | 45 | 24 |
-| 1/29 | 36 | 14 |
-| 1/30 | 46 | 21 |
-| 1/31 | 51 | 22 |
-| 2/1 | 46 | 26 |
-| 2/2 | 27 | -5 |
-| 2/3 | 29 | -7 |
-| 2/4 | 42 | 27 |
-| 2/5 | 46 | 18 |
-| 2/6 | 54 | 19 |
-| 2/7 | 45 | 28 |
-| 2/8 | 41 | 20 |
-| 2/9 | 51 | 20 |
-| 2/10 | 45 | 25 |
-
-  : []{#_Toc430249172 .anchor}**Table 6‑5 Daily temperatures for
-  illustrative snowmelt example**
-
-| **Date** | **Time** | **Precipitation (in)** |
-| --- | --- | --- |
-| 01/26 | 04:00:00 | 0.26 |
-| 01/29 | 18:00:00 | 0.11 |
-| 01/29 | 19:00:00 | 0.01 |
-| 01/29 | 20:00:00 | 0.08 |
-| 02/01 | 23:00:00 | 0.02 |
-| 02/02 | 00:00:00 | 0.06 |
-| 02/02 | 01:00:00 | 0.08 |
-| 02/02 | 02:00:00 | 0.14 |
-| 02/02 | 03:00:00 | 0.19 |
-| 02/02 | 04:00:00 | 0.09 |
-| 02/02 | 05:00:00 | 0.01 |
-| 02/02 | 22:00:00 | 0.02 |
-| 02/02 | 23:00:00 | 0.06 |
-| 02/03 | 00:00:00 | 0.12 |
-| 02/03 | 01:00:00 | 0.22 |
-| 02/03 | 02:00:00 | 0.17 |
-| 02/03 | 03:00:00 | 0.05 |
-| 02/03 | 12:00:00 | 0.02 |
-| 02/03 | 13:00:00 | 0.00 |
-| 02/03 | 14:00:00 | 0.02 |
-| 02/09 | 00:00:00 | 0.01 |
-| 02/09 | 01:00:00 | 0.02 |
-| 02/09 | 02:00:00 | 0.00 |
-| 02/09 | 03:00:00 | 0.00 |
-| 02/09 | 04:00:00 | 0.00 |
-| 02/09 | 05:00:00 | 0.06 |
-
-  : []{#_Toc430249173 .anchor}**Table 6‑6 Periods of precipitation for
-  illustrative snowmelt example**
-
-Figures 6-7 through 6-10 show the resulting temperature, precipitation,
-snow depth and runoff amounts, respectively produced by SWMM for this
-example. The original inch of snow takes about four days to melt
-completely. Runoff during this time is sporadic, due to the fluctuation
-in temperature around the base melt temperature. The first storm event
-arrives just before the end of day 2 and falls mainly as snow. This
-bumps up the snow cover during its 3-hour duration as shown in Figure
-6-9. Snow levels rise again with the arrival of the second storm during
-the morning of day 5, when temperatures are below freezing. By day 6,
-temperatures again rise above the base melt temperature (30 °F) for part
-of the day and the snow from the second storm is completely melted by
-the start of day 7. The next storm arrives at noon of day 8 and lasts
-for 7 hours. The runoff spike of 0.15 in/hr seen in Figure 6-10 occurs
-during the first hour of this event when the temperature is still above
-freezing. The remainder of the storm falls as snow and starts the
-buildup of a snow pack once again. The next two storms add onto the
-pack, and no melting occurs until day 10, when temperatures again rise
-above the base melt value for portions of the day. Runoff from the
-melting pack is delayed until its free water fraction is exceeded. The
-pack takes another 6 days to melt during which time the runoff is
-sporadic as the temperature fluctuates above and below the base melt
-level.
-
-![[]{#_Toc426447704 .anchor}**Figure 6‑7 Continuous air temperature for
-illustrative snowmelt
-example.**](VolumeI/media/media/image44.emf){width="6.5in" height="3.34375in"}
-
-![[]{#_Toc426447705 .anchor}**Figure 6‑8 Precipitation amounts for
-illustrative snowmelt
-example.**](VolumeI/media/media/image45.emf){width="6.5in" height="3.34375in"}
-
-![[]{#_Toc426447706 .anchor}**Figure 6‑9 Snow pack depth for
-illustrative snowmelt
-example.**](VolumeI/media/media/image46.emf){width="6.5in" height="3.34375in"}
-
-![[]{#_Toc426447707 .anchor}**Figure 6‑10 Runoff time series for
-illustrative snowmelt
-example.**](VolumeI/media/media/image47.emf){width="6.489583333333333in"
-height="3.71875in"}
-
-#  -- Rainfall Dependent Inflow and Infiltration
-
-## 7.1 Introduction
-
-Rainfall dependent (or rainfall-derived) inflow and infiltration (RDII)
-are stormwater flows that enter sanitary or combined sewers due to
-\"inflow\" from direct connections of downspouts, sump pumps, foundation
-drains, etc. as well as \"infiltration\" of subsurface water through
-cracked pipes, leaky joints, poor manhole connections, etc. RDII can be
-a significant cause of sanitary sewer overflows (SSOs) of untreated
-wastewater into basements, streets and other properties, as well as
-receiving streams. It can also cause significant flow increases to
-wastewater treatment plants resulting in hydraulic overloading and
-disruption of plant processes.
-
-SWMM treats RDII as a separate category of external inflows that enters
-the conveyance system at specific user-designated nodes. It is computed
-independently of the surface runoff, infiltration, snowmelt and
-groundwater processes described in previous chapters of this manual.
-RDII flow is added onto the other inflow categories (such as dry weather
-sanitary flow, overland runoff, and groundwater interflow) during each
-time step of a simulation. RDII calculations were added to version 4 of
-SWMM by C. Moore of CDM in 1993. This chapter describes how these RDII
-flows are computed from the precipitation records supplied to a SWMM
-data set.
-
-## 7.2 Governing Equations
-
-Figure 7-1 depicts the three major components of wet-weather wastewater
-flow within a sanitary sewer system (Vallabhaneni et al., 2007). These
-are base sanitary flow (BSF), groundwater infiltration (GWI), and RDII.
-BSF is the flow discharged to sanitary sewers by homes, businesses,
-institutions, and industrial water users throughout the normal course of
-a day. It exhibits a typical diurnal pattern, with higher flows during
-the morning and early evening hours and lower flows overnight. The
-average daily BSF remains more or less constant during the week, but can
-vary by both month and season.
-
-GWI consists of groundwater that enters the collection system through
-cracked pipes, pipe joints and manhole walls during extended periods of
-time when water table levels are high, even in the absence of any
-rainfall. It is different from RDII because it does not occur as a
-direct response to a rainfall event. GWI varies throughout the year,
-with the highest rates in late winter and spring as groundwater levels
-rise, and the lowest rates (or no GWI at all) during late summer or
-after an extended dry period.
-
-RDII is the flow that can be directly attributed to a rainfall event.
-This flow is zero before the start of the event, increases during the
-event, and declines back to zero sometime after the event is over. The
-start of the RDII response may be delayed during the time it takes for
-surfaces to capture a portion of the initial rainfall and for soils to
-become saturated. If the event is small enough, then no RDII at all may
-be generated. The maximum volume of rainfall that does not produce any
-RDII response is referred to as "initial abstraction" (Vallabhaneni et
-al., 2007).
-
-

-Flows
-
Figure 7‑1 Components of wet-weather
-wastewater flow.

-

-
-Quantitative estimates of RDII are almost always derived from actual
-wastewater flow records as opposed to attempting to model the
-distributed set of small scale physical processes directly responsible
-for RDII. Methods for modeling RDII are reviewed by Bennet et al. (1999)
-and Lai (2008). SWMM uses the RTK unit hydrograph approach, which is
-among the most flexible and widely used RDII methods (Vallabhaneni et
-al., 2007). (The initials RTK stand for the three parameters that
-characterize the unit hydrographs used by the method.)
-
-The RTK unit hydrograph method was first developed by CDM-Smith
-consultants in an RDII study for the East Bay Municipal Utility District
-in Oakland, CA (Giguere and Riek, 1983). It represents the response of a
-sewershed to a rainfall event through a series of up to three triangular
-unit hydrographs. These unit hydrographs can be applied to any
-particular storm event to produce a resulting time history of RDII flow
-rates.
-
-Figure 7-2 shows a single triangular unit hydrograph assumed to
-represent the RDII flow induced by one unit of rainfall over a unit of
-time. This unit hydrograph is characterized by the following parameters:
-
-*R*: the fraction of rainfall volume that enters the sewer system and
-equals the volume under the hydrograph
-
-*T*: the time from the onset of rainfall to the peak of the unit
-hydrograph
-
-*K*: the ratio of time to recession of the unit hydrograph to the time
-to peak
-
-*Qpeak*: peak flow (per unit area) on the unit hydrograph.
-
-[]{#_Toc426447709 .anchor}**Figure 7‑2 Example of an RDII triangular
-unit hydrograph.**
-
-Figure 7-3 shows how this single unit hydrograph would be applied to a
-storm that consists of three time periods of varying rainfall volume.
-The original unit hydrograph is replicated for each rainfall time
-period, with its origin offset by the time period and its ordinates
-multiplied by the rainfall volume for that period. The overall response
-to the storm is the hydrograph obtained by summing the ordinates of the
-volume-adjusted hydrographs at each time point. The volumetric RDII
-inflow into the conveyance system is the ordinate of the composite
-hydrograph multiplied by the contributing area of the affected
-sewershed. This process of adding together the rainfall-adjusted,
-time-shifted hydrographs is known as convolution (Chow et al, 1988) and
-is expressed mathematically as:
-
-+----------------------------------------------------+-----------------------------------+
-| > $$Q_{t} = \sum_{j = 1}^{t}{U_{t - j + 1}P_{j}}$$ | (7-1)                             |
-+====================================================+===================================+
-
-where:
-
-| Symbol | Description |
-| :--- | :--- |
-| *Qt* | RDII flow per unit area during time period *t*, |
-| *Ut* | ordinate of the unit hydrograph for time period *t*, |
-| *Pj* | depth of rainfall for time period *j*. |
-
-[]{#_Toc426447710 .anchor}**Figure 7‑3 Application of a unit hydrograph
-to a storm event.**
-
-The ordinate value *Uj* for time period *j* is determined from the
-shape parameters *R, T*, and *K* of the unit hydrograph as follows. One
-can write:
-
-+-----------------------------------+-----------------------------------+
-| > $$U_{j} = f_{j}Q_{peak}$$       | (7-2)                             |
-+===================================+===================================+
-
-where *fj* is the fraction of the rising limb (or falling limb) that
-corresponds to time period *j*. Because the area under the unit
-hydrograph is *R*, the value of *Qpeak* is:
-
-+------------------------------------+-----------------------------------+
-| > $$Q_{peak} = \frac{2R}{T + KT}$$ | (7-3)                             |
-+====================================+===================================+
-
-Thus *Uj *can be expressed as:
-
-+--------------------------------------+-----------------------------------+
-| > $$U_{j} = \frac{2Rf_{j}}{T + KT}$$ | (7-4)                             |
-+======================================+===================================+
-
-By convention, the time *τj* on the unit hydrograph base corresponding
-to time period *j* is taken as the midpoint between either ends of the
-time interval:
-
-+--------------------------------------+-----------------------------------+
-| > $$\tau_{j} = (j - 0.5)\Delta\tau$$ | (7-5)                             |
-+======================================+===================================+
-
-where *∆τ* is the time interval over which precipitation is recorded.
-The fraction *fj* is then determined as:
-
-+-------------------------------------------+-----------------------+-----------------------+
-| > $$f_{j} = \frac{\tau_{j}}{T}$$          | for *τj \<= T*      | (7-6)                 |
-+===========================================+:======================+======================:+
-| > $$f_{j} = 1 - \frac{\tau_{j - T}}{KT}$$ | for *T* \< *τj \<=  | (7-7)                 |
-|                                           | T + KT*               |                       |
-+-------------------------------------------+-----------------------+-----------------------+
-| > $$f_{j} = 0$$                           | for *τj \> T + KT*  | (7-8)                 |
-+-------------------------------------------+-----------------------+-----------------------+
-
-Because actual RDII hydrographs have complex shapes, three different
-hydrographs of increasing durations are typically used to represent the
-overall RDII unit response (Vallabhaneni et al., 2007). The first
-hydrograph models the most rapidly responding inflow component usually
-caused by direct sources of inflow, and has a time to peak *T* of one to
-three hours. The second includes both rainfall-derived inflow and
-infiltration, and has a longer *T* value. The third represents
-infiltration that may continue long after the storm event has ended and
-has the longest *T* value. Figure 7-4 depicts how the three unit
-hydrographs are summed together to produce a total RDII hydrograph in
-response to a unit of rainfall over one unit of time. Equation 7-1 is
-still used to compute the overall RDII hydrograph to any given storm
-event, with a separate *Qt* computed for each of the three unit
-hydrographs. These are then added together to produce the total flow per
-unit area for time period *t*.
-
-![RDII%20Hydrographs](VolumeI/media/media/image49.png){width="6.114583333333333in"
-height="3.34375in"}
-
-[]{#_Toc426447711 .anchor}**Figure 7‑4 Use of three unit hydrographs to
-represent RDII (Vallabhaneni et al., 2007).**
-
-Not all storms will result in measurable inflow/infiltration. Just as
-with ordinary runoff, a certain initial volume of rainfall will be
-captured by surface ponding, interception by flat roofs and vegetation,
-and surface wetting and will not contribute to RDII. This phenomenon is
-represented in SWMM by three user-supplied "initial abstraction" (*IA*)
-parameters that accompany each RDII unit hydrograph. *IAmax* (in or
-mm) is the maximum depth of initial abstraction capacity available for
-the sewershed. *IA0* (in or mm) is the amount of that capacity already
-used up at the start of the simulation. *IAr* (in/day or mm/day) is
-the rate at which capacity becomes available again during periods of no
-rainfall. During storm events, the volume of rainfall applied to the
-unit hydrograph convolution formula, Equation 7-1, is reduced by the
-amount of initial abstraction capacity remaining. During dry periods,
-this capacity is regenerated based on the user-supplied recovery rate.
-
-## 7.3 Computational Scheme
-
-SWMM generates RDII inflows for specific nodes of a sewer system. Recall
-from Section 1.2 that SWMM uses a network of links and nodes to
-represent the conveyance portion of a drainage area. For RDII
-applications this network would be the sewer system (either sanitary or
-combined), the links are the sewer pipes and the nodes are points where
-pipes connect to one another (e.g., manholes or pipe fittings).
-
-It should be noted once again that RDII is computed independently from
-any surface runoff or groundwater flow generated from the subcatchments
-contained in a SWMM model. The sewershed that produces RDII flow for a
-specific sewer system node is not represented explicitly in SWMM and
-need not correspond to any of the runoff subcatchments defined for the
-study area. In fact it is perfectly acceptable (and quite common for
-sanitary sewer systems) to conduct an RDII analysis without including
-any subcatchments in the model. In this case the model would consist of
-a set of Rain Gage objects (and their data sources), the node and link
-objects that make up the sewer network and sets of user-supplied time
-series that describe groundwater (GWI) and sanitary (BSF) flows.
-
-SWMM computes all RDII inflow time series prior to the start of a
-simulation and saves these inflow values to an interface file. Each line
-of the file contains, in chronological order, a node ID name, a date, a
-time of day, and the RDII inflow value for that node. Dates with no RDII
-inflows are not recorded. To compute the entries of this file the
-following quantities are assumed known for each node of the conveyance
-system node that receives RDII inflows:
-
-- the area (*A*) of the sewershed that contributes RDII to the node,
-
-- the *R-T-K* parameters for each of three RDII unit hydrographs,
-
-- the initial abstraction parameters (*IAmax, IA0*, and *IAr*)
-  associated with each RDII unit hydrograph,
-
-- the time series of rain volumes that fall on the sewershed and their
-  recording interval *∆τ* (sec) as provided by a SWMM Rain Gage object.
-
-> The steps used to process a precipitation record against a set of unit
-> hydrographs to produce a record of RDII inflows for a specific
-> conveyance node are described in the sidebar shown below.
-
-## 7.4 Parameter Estimates
-
-To use SWMM's RDII option a user must supply estimates of the three
-parameters (R, T, and K) that define each of three unit hydrographs for
-each node where RDII enters the sewer system. Each unit hydrograph can
-also have a set of initial abstraction parameters (Ia0, Iamax, and
-Iar). SWMM also allows one to specify different sets of unit
-hydrographs and initial abstraction parameters for different months of
-the year. In addition, the area of the RDII contributing sewershed must
-also be specified.
-
-R-T-K parameters are derived from site-specific flow monitoring data.
-There are no general values that can be applied in the absence of actual
-field data. All of these parameters require that a continuous flow
-monitoring program be implemented at strategic points in the sewer
-system. As described in Vallabhaneni et al., 2007, estimating the RDII
-unit hydrograph parameters for a sewershed involves the following
-activities:
-
-1.  Identify the sewershed areas that are tributary to the flow monitor
-    (see Figure 7-5).
-
-2.  Extract the RDII portion of the recorded flow at the monitoring
-    station during a wet weather event (see Figure 7-6).
-
-3.  Estimate the R-T-K values for each of three unit hydrographs whose
-    resultant hydrograph best matches the RDII flow extracted from the
-    flow record (see Figure 7-7).
-
-

-RDII_Sewersheds
-
Figure 7‑5 Sewershed delineation
-(Vallabhaneni et al., 2007).

-

-
-

-RDII_Flow_History
-
Figure 7‑6 Extracting RDII flow from a
-continuous flow monitor (Vallabhaneni et al.,
-2007).

-

-
-![RDII_UH_Estimate](VolumeI/media/media/image52.png){width="6.270833333333333in"
-height="3.824905949256343in"}
-
-[]{#_Toc426447714 .anchor}**Figure 7‑7 Fitting unit hydrographs to an
-RDII flow record (Vallabhaneni et al., 2007).**
-
-## 7.5 Numerical Example
-
-A simple example illustrates how SWMM constructs an RDII interface file
-for use within a hydraulic simulation. Assume there is a single rain
-gage whose rainfall time series is shown in Table 7-1. Note that the
-recording interval is 1 hour, and that there are two events separated by
-22 hours. SWMM will use data from this gage to construct a time series
-of RDII flows for a node named N1 in the conveyance system that services
-an area of 10 acres. There is a single group of 3 unit hydrographs used
-to derive RDII from the rain gage data. The shapes and parameters of the
-unit hydrographs (UH1, UH2, and UH3) are shown in Figure 7-8. Note that
-the R-values of this set of unit hydrographs sum to 0.36, implying that
-36 percent of total rainfall volume winds up as RDII. To keep things
-simple, initial abstraction is not considered in this example.
-
-| **Hour** | **Rainfall (inches)** |
-| --- | --- |
-| 0:00 | 0.0 |
-| 1:00 | 0.25 |
-| 2:00 | 0.5 |
-| 3:00 | 0.8 |
-| 4:00 | 0.4 |
-| 5:00 | 0.1 |
-| 6:00 | 0.0 |
-| 27:00 | 0.0 |
-| 28:00 | 0.4 |
-| 29:00 | 0.2 |
-| 30:00 | 0.0 |
-
-  : []{#_Toc430249174 .anchor}**Table 7‑1 Rainfall time series for the
-  illustrative RDII example**
-
-![[]{#_Toc426447715 .anchor}**Figure 7‑8 Unit hydrographs used for the
-illustrative RDII
-example.**](VolumeI/media/media/image53.emf){width="6.510416666666667in"
-height="3.5in"}
-
-The resulting RDII flows are depicted in Figure 7-9. SWMM places these
-flows into an RDII interface file, a portion of which is displayed in
-Figure 7-10. This file is accessed during the flow routing portion of a
-SWMM run to add RDII inflow into node N1 at each time step of the
-routing process.
-
-![[]{#_Toc426447716 .anchor}**Figure 7‑9 Time series of RDII flows for
-the illustrative RDII
-example.**](VolumeI/media/media/image54.emf){width="5.822916666666667in"
-height="3.5in"}
-
-+-----------------------------------------------------------------------+
-| SWMM5 Interface File                                                  |
-|                                                                       |
-| 900 - reporting time step in sec                                      |
-|                                                                       |
-| 1 - number of constituents as listed below:                           |
-|                                                                       |
-| FLOW CFS                                                              |
-|                                                                       |
-| 1 - number of nodes as listed below:                                  |
-|                                                                       |
-| N1                                                                    |
-|                                                                       |
-| Node Year Mon Day Hr Min Sec FLOW                                     |
-|                                                                       |
-| N1 2002 02 02 01 15 00 0.204195                                       |
-|                                                                       |
-| N1 2002 02 02 01 30 00 0.204195                                       |
-|                                                                       |
-| N1 2002 02 02 01 45 00 0.204195                                       |
-|                                                                       |
-| N1 2002 02 02 02 00 00 0.204195                                       |
-|                                                                       |
-| N1 2002 02 02 02 15 00 0.554604                                       |
-|                                                                       |
-| N1 2002 02 02 02 30 00 0.554604                                       |
-|                                                                       |
-| N1 2002 02 02 02 45 00 0.554604                                       |
-|                                                                       |
-| N1 2002 02 02 03 00 00 0.554604                                       |
-|                                                                       |
-| N1 2002 02 02 03 15 00 1.021479                                       |
-|                                                                       |
-| N1 2002 02 02 03 30 00 1.021479                                       |
-|                                                                       |
-| N1 2002 02 02 03 45 00 1.021479                                       |
-|                                                                       |
-| N1 2002 02 02 04 00 00 1.021479                                       |
-|                                                                       |
-| N1 2002 02 02 04 15 00 1.001312                                       |
-|                                                                       |
-| N1 2002 02 02 04 30 00 1.001312                                       |
-|                                                                       |
-| N1 2002 02 02 04 45 00 1.001312                                       |
-|                                                                       |
-| N1 2002 02 02 05 00 00 1.001312                                       |
-|                                                                       |
-| N1 2002 02 02 05 15 00 0.703842                                       |
-|                                                                       |
-| N1 2002 02 02 05 30 00 0.703842                                       |
-|                                                                       |
-| N1 2002 02 02 05 45 00 0.703842                                       |
-|                                                                       |
-| N1 2002 02 02 06 00 00 0.703842                                       |
-+=======================================================================+
-
-: []{#_Toc426447717 .anchor}**Figure 7‑10 Excerpt from the RDII
-interface file for the illustrative RDII example.**
-
-# References
-
-Adams, B.J. and F. Papa, Urban Stormwater Management Planning, with
-Analytical Probabilistic Models, John Wiley and Sons, New York, 2000.
-
-Akan, A.O., "Horton Infiltration Formula Revisited", Journal of
-Irrigation and Drainage Engineering, ASCE, 118:828-830, 1992.
-
-Akan, A.O. and R.J. Houghtalen, *Urban Hydrology, Hydraulics, and
-Stormwater Quality*, John Wiley & Sons, Inc., 2003.
-
-American Society of Civil Engineers (ASCE), *Design and Construction of
-Urban Stormwater Management Systems*, American Society of Civil
-Engineers, New York, NY, 1992.
-
-American Society of Civil Engineers, *Hydrology Handbook*, ASCE Manuals
-and Reports on Engineering Practice No. 28, Reston, VA, Second Edition,
-1996.
-
-Anderson, E.A., "National Weather Service River Forecast System -- Snow
-Accumulation and Ablation Model, NOAA Tech. Memo NWS HYDRO-17, U.S.
-Department of Commerce, Washington, DC, 1973.
-
-Anderson, E.A., "A Point Energy and Mass Balance Model of a Snow Cover",
-NOAA Tech. Report NWS 19, U.S. Department of Commerce, Washington, DC,
-1976.
-
-Anderson, E., "Snow Accumulation and Ablation Model -- SNOW-17", NWSRFS
-User Manual Documentation, Chapter II.2: Snow Models, National Weather
-Service, NOAA, Washington, DC January, 2006.
-(http://www.nws.noaa.gov/oh/hrl/nwsrfs/users_manual/htm/xrfsdocpdf.php).
-
-Aron, G.M., A.C. Miller and D.F. Lakatos, "Infiltration formula based on
-SCS curve number", *Journal of Irrigation and Drainage Division*, ASCE,
-103(4), pp. 419-427, 1977.
-
-Bear, J., *Dynamics of Fluids in Porous Media*, Elsevier, New York,
-1972.
-
-Bedient, P.B., W.C. Huber and B.E. Vieux, *Hydrology and Floodplain
-Analysis*, Prentice-Hall, Inc., Upper Saddle River, NJ, Fifth Edition,
-2013.
-
-Bengtsson, L., "Snowmelt-Generated Runoff in Urban Areas" in Urban
-Stormwater Hydraulics and Hydrology, B.C. Yen, ed., Proc. Second
-International Conference on Urban Storm Drainage, Urbana, IL, Water
-Resources Publications, Littleton, CO, June, 1981, Vol. I, pp. 444-451.
-
-Bennett, D., Rowe, R., Strum, M., Wood, D., *Using Flow Prediction
-Technologies to Control Sanitary Sewer Overflows*, Water Environment
-Research Foundation (WERF), Project 97-CTS-8, 1999.
-
-Bergström, S., "Development and Application of a Conceptual Runoff Model
-for Scandinavian Catchments," *Hydrologi och Oceanografi*, No. RHO 7,
-SMI, Norrköping, Sweden, 1976.
-
-Betson, R.P., "What Is Watershed Runoff?", *Journal of Geophysical
-Research*, Vol. 69, 1964, pp. 1541-1522.
-
-Bicknell, B.R., Imhoff, J.C., Kittle, J.L., Jr., Donigian, A.S., Jr. and
-R.C. Johanson, *Hydrologic Simulation Program -- Fortran: User's Manual
-for Release 11*, U.S. Environmental Protection Agency, Office of
-Research and Development, Athens, GA, 1997.
-
-Bouwer, H. *Groundwater Hydrology*, McGraw-Hill, New York, 1978.
-
-Brakensiek, D.L. and C.A. Onstad, "Parameter Estimation of the
-Green-Ampt Equations", *Water Resources Research*, Vol. 13, No. 6,
-December, 1977, pp. 1009-1012.
-
-Brakensiek, D. L., Engleman, R. L., and Rawls, W. J. "Variation within
-Texture Classes
-
-of Soil Water Parameters." *Transactions of the ASAE*, Vol. 24, No. 2,
-1981, pp. 335-39.
-
-Brater, E.F., "Steps Toward a Better Understanding of Urban Runoff
-Processes", *Water Resources Research*, Vol. 4, No. 2, April, 1968, pp.
-335-347.
-
-Brooks, R.H., and A.T. Corey, "Hydraulic properties of porous media",
-Hydrology Paper No. 3, Colorado State Univ., Ft. Collins, CO, 1964.
-
-Butler, S.S., *Engineering Hydrology*, Prentice-Hall, New York, 1957.
-
-Campbell, G.S., "A simple method for determining unsaturated
-conductivity from moisture retention data", *Soil Sci*., Vol. 117, 1974,
-pp. 311--314.
-
-Capece, J.C., J.C. Cambell and L.B. Baldwin, "Estimating Peak Rates and
-Volumes from Flat, High-water-table Watersheds", paper No. 84-2020,
-American Society of Agricultural Engineers, St. Joseph, MI, June 1984.
-
-Carlisle, V.W., C.T. Hallmark, F. Sodek III, R.E. Caldwell, L.C.
-Hammond, and V.E. Berkheiser, "Characterization Data for Selected
-Florida Soils", Soil Science Research Report No. 81-1, Soil Science
-Department, University of Florida, Gainesville, June 1981.
-
-Chan, S. and R.L. Bras, "Urban Storm Water Management: Distribution of
-Flood Volumes", *Water Resources Research*, Vol. 15, No. 2, April 1979,
-pp. 371-382.
-
-Chen, C.N., "Design of Sediment Retention Basins," Proceedings National
-Sym­posium on Urban Hydrology and Sediment Control, Publication UKY
-BU109, University of Kentucky, Lexington, July 1975, pp. 285-298.
-
-Chen, C., "Flow Resistance in Broad Shallow Grassed Channels", Journal
-of the Hydraulics Division, ASCE, Vol. 102, No. HY3, March 1976, pp.
-307-322.
-
-Chen, C.W. and Shubinski, R.P., "Computer Simulation of Urban Storm
-Water Runoff", *J. Hydraul. Div., Proc. ASCE*, 97(HY2):289-301, 1971.
-
-Chow, V.T., *Open-Channel Hydraulics*, McGraw-Hill, New York, 1959.
-
-Chow, V.T., Maidment, D.R. and L.W. Mays, *Applied Hydrology*,
-McGraw-Hill, New York, 1988.
-
-Christensen, B.A., ""Hydraulics of Sheet Flow in Wetlands", Symposium on
-Inland Waterways for Navigation, Flood Control and Water Diversions,
-Colorado State University, ASCE, New York, August 1976, pp. 746-759.
-
-Chu, S.T., "Infiltration During an Unsteady Rain", *Water Resources
-Research*, Vol. 14, No. 3, June 1978, pp. 461-466.
-
-Clapp, R.B. and G.M. Hornberger, "Empirical Equations for Some Soil
-Properties", Water Resources Research, Vol. 14, No. 4, August 1978, pp.
-601-604.
-
-Conway, H. and R. Benedict, "Infiltration of Water into Snow," *Water
-Resources Research*, Vol. 30, No. 3, March 1994, pp. 641-649.
-
-Corps of Engineers, "Snow Hydrology", NTIS PB-151660, North pacific
-Division, U.S. Army Corps of Engineers, Portland, OR, 1956.
-
-Corps of Engineers, "Runoff Evaluation and Streamflow Simulation by
-Computer", Tech. Report, North Pacific Division, U.S. Army Corps of
-Engineers, Portland, OR, 1971.
-
-Corps of Engineers, "Storage, Treatment, Overflow, Runoff Model, STORM,"
-User's Manual, Generalized Computer Program 723-S8-L7520, Hydrologic
-Engineering Center, U.S. Army Corps of Engineers, Davis, CA, August
-1977.
-
-Crawford, N.H. and R.K. Linsley, "Digital Simulation in Hydrology:
-Stanford Watershed Model IV", Tech Report No. 39, Civil Engineering
-Department, Stanford University, Palo Alto, CA, July 1966.
-
-Danish Hydraulic Institute, *MouseNAM Reference Manual 1.0*, Hørsholm,
-Denmark, 1994.
-
-Dawdy, D.R. and T. O'Donnell, "Mathematical Models of Catchment
-Behavior", *Journal of the Hydraulics Division, Proc. ASCE*, Vol. 91,
-No. HY4, July 1965, 123-137.
-
-Urban Drainage and Flood Control District (UDFCD) (2007). "Drainage
-Criteria Manual, Chapter 5 -- Runoff", Urban Drainage and Flood Control
-District, Denver, CO.
-
-(http://www.udfcd.org/downloads/down_critmanual_volI.htm).
-
-DiGiano, F.A., D.D. Adrian, and P.A. Mangarella, Eds., "Short Course
-Proceddings -- Applications of Stormwater Management Models, 1976",
-EPA-600/2-77-065 (NTIS PB-265321), U.S. Environmental Protection Agency,
-Cincinnati, OH, March 1977.
-
-Dingman, S. L., *Physical Hydrology*, Prentice-Hall, Inc., Upper Saddle
-River, NJ, Second Edition, 2002.
-
-Downs, W.C., J.P. Dobson, and R.E. Wiles, "The Use of SWMM to Predict
-Runoff from Natural Watersheds in Florida", Proceedings of Stormwater
-and Water Quality Model Users Group, Meeting, Orlando, Floroda,
-EPA-600/9-86/023 (NTIS PB87-117438/AS), U.S. Environmental Protection
-Agency, Athens, GA, March 1986.
-
-Doyle, H.W. and J.E. Miller, "Calibration of a Distributed
-Routing-Runoff Model at Four Urban Sites Near Miami, Florida", Water
-Resources Investigations 80-1, U.S. Geological Survey, NSTL Station, MS,
-February 1980.
-
-Eagleson, P.S., *Dynamic Hydrology*, McGraw-Hill, New York, 1970
-
-Emmett, W.W., "Overland Flow", M.J. Kirby ed., *Hillslope Hydrology*,
-John Wiley and Sons,New York, 1978.
-
-Engman, E.T., "Roughness Coefficients for Routing Surface Runoff",
-*Journal of Irrigation and Drainage Engineering*, ASCE, Vol. 112, No. 1,
-February 1986, pp. 39-53.
-
-Falk, J. and J. Niemczynowicz, "Characteristics of the Above-Ground
-Runoff in Sewered catchments", *Urban Storm Drainage*, Proceedings
-International Conference on Urban Storm Drainage, University of
-Southampton, April 1978, P.R. Helliwell, ed., Pentech Press, London,
-1978.
-
-Farnsworth, R.K. and Thompson, E.S., "Mean Monthly, Seasonal, and Annual
-Pan Evaporation for the United States," NOAA Technical Report NWS 34,
-Office of Hydrology, National Weather Service, Washington, DC, December
-1982.
-
-Fetter, C.W. Jr., *Applied Hydrogeology*, Charles E. Merrill, Columbis,
-OH, 1980.
-
-Field, R.I., Heaney, J.P. and R. Pitt, *Innovative Urban Wet-Weather
-Flow Management Systems*, Technomic Publishing Co., Lancaster, PA, 2000.
-
-Fleming, G., *Computer Simulation Techniques in Hydrology*, American
-Elsevier Publishing Co., New York, 1975.
-
-Franz, D.D, "Prediction for Dew Point Temperature, Solar Radiation and
-Wind Movement Data for Simulation and Operations Research Models",
-Report for Office of Water Resources Research, Hydrocomp, Inc., Palo
-Alto, CA, April 1974.
-
-French, R.H., *Open-Channel Hydraulics*, McGraw-Hill, New York, 1985.
-
-Gagliardo, V., "A Subsurface Drainage Model for Florida Conditions",
-M.E. Project Report (unpublished), Dept. of Environmental Engineering
-Sciences, University of Florida, Gainesville, FL, 1986.
-
-Giguere, P.R. and Riek, G.C., "Infiltration/Inflow Modeling for the East
-Bay (Oakland-Berkeley Area) I/I Study." Proceedings of the 1983
-International Symposium on Urban Hydrology, Hydraulics and Sediment
-Control. University of Kentucky, July 25-28, 1983, Lexington, KY, 1983.
-
-Gironás, J., L.A. Roesner, and J. Davis, "Storm Water Management Model
-Applications Manual", EPA/600/R-09/077, U.S. Environmental Protection
-Agency, Cincinnati, OH, July, 2009.
-
-Graf, W.H. and V.H. Chun, "Mannings Roughness for Artificial Grasses",
-*Journal of the Irrigation and Drainage Division*, ASCE, Vol. 102, No.
-IR4, December 1976, pp. 413-423.
-
-Gray, D.M., ed., *Handbook on the Principles of Hydrology*, Water
-Information Center, Port Washington, NY, 1970.
-
-Gray, D.M. and T.D. Prowse, "Snow and Floating Ice," Chapter 7 in
-*Handbook of Hydrology*, D.R. Maidment, ed., McGraw-Hill, New York,
-1993.
-
-Green, W.H. and G.A. Ampt, "Studies on Soil Physics, 1. The Flow of Air
-and Water Through Soils", *Journal of Agricultural Sciences*, Vol. 4,
-1911, pp. 11-24.
-
-Guo, J.C.Y. and Urbonas, B., "Conversion of Natural Watershed to
-Kinematic Wave Cascading Plane", *Journal of Hydrologic Engineering*,
-Vol. 14, No. 8, pp. 839-846, July/August 2009.
-
-Haan, C.T., Barfield, B.J. and J.C. Hayes, *Design Hydrology and
-Sedimentology for Small Catchments*, Academic Press, New York, 1994.
-
-Hargreaves, G.H. and Z.A. Samani, "Reference Crop Evapotranspiration
-from Temperature", *Applied Engineering in Agriculture*, 1(2):96-99,
-1985.
-
-Hargreaves, G.H and G.P. Merkley, *Irrigation Fundamentals*, Water
-Resources Publications, LLC, Highlands Ranch, CO, 1998.
-
-Heaney, J.P., W.C. Huber, H. Sheikhv, M.A. Medina, J.R. Doyle, W.A.
-Peltz, and J.E. Darling, "Urban Stormwater Management Modeling and
-Decision Making", EPA-670/2-75-022 (NTIS PB-242290), U.S. Environmental
-Protection Agency, Cincinnati, OH, 1975.
-
-Heineman, M.C., "NetSTORM - A Computer Program for Rainfall-Runoff
-Simulation and Precipitation Analysis", Critical Transitions in Water
-and Environmental Resources Management, G. Sehlke, D. F. Hayes, and D.K.
-Stevens, eds., Proceedings of the 2004 World Water and Environmental
-Resources Congress, American Society of Civil Engineers, Reston, VA,
-2004.
-
-Hicks, W.I., "A Method of Computing Urban Runoff", *Transactions ASCE*,
-Vol. 109, 1944, pp. 1217-1253.
-
-Hillel, D., *Introduction to Soil Physics*, Academic Press, Orlando, FL,
-1982.
-
-Hoblit, B.C. and D.C. Curtis, "Integration of Radar Rainfall into
-Hydrologic Models" In *Global Solutions for Urban Drainage*, Proc. Ninth
-International Conference on Urban Drainage, E.W. Strecker and W.C.
-Huber, eds., Portland, OR, American Society of Civil Engineers, Reston,
-VA, CD-ROM, September (2002).
-
-Horton, R.E., "The Role of Infiltration in the Hydrologic Cycle",
-*Transactions American Geophysical Union*, Vol. 14, 1933, pp. 446-460.
-
-Horton, R.E., "An Approach Toward a Physical Interpretation of
-Infiltration Capacity", *Proceeding Soil Science of America*, Vol. 5,
-1940, pp. 399-417.
-
-Howard, C.D.D., "Theory of Storage and Treatment-Plant Overflows",
-*Journal of the Environmental Engineering Division*, ASCE, Vol. 102, No.
-EE4, August 1976, pp. 709-722.
-
-Huber, W.C., J.P. Heaney, M.A. Medina, W.A. Peltz, H. Sheikh, and G.F.
-Smith, "Storm Water Management Model User's Manual ­ Version II,"
-EPA-670/2-75-01· (NTIS PB-257809), U.S. Environmental Protection Agency,
-Cincinnati, OH, March 1975.
-
-Huber, W.C., J.P. Heaney, S.J. Nix, R.E. Dickinson, and D.J. Polmann,
-"Storm Water Management Model User's Manual, Version III,"
-EPA-600/2-84-109a (NTIS PB84-198423), U.S. Environmental Protection
-Agency, Cincinnati, OH, November 1981.
-
-Huber, W.C., and R.E. Dickinson, *Storm Water Management Model, Version
-4, User\'s Manual,* EPA/600/3-88/001a (NTIS PB88-236641/AS), U.S.
-Environmental Protection Agency, Athens, GA, 1988.
-
-Huber, W.C., "New Options for Overland Flow Routing in SWMM," *Urban
-Drainage Modeling*, R.W. Brashear and C. Maksimovic, eds., Proc. of the
-Specialty Symposium of the World Water and Environmental Resources
-Conference, ASCE, Environmental and Water Resources Institute, Orlando,
-FL, May 2001, pp. 22-29.
-
-Huber, W.C. and L. Cannon, "Modeling Non-Directly Connected Impervious
-Areas in Dense Neighborhoods," In *Global Solutions for Urban Drainage*,
-Proc. Ninth International Conference on Urban Drainage, E.W. Strecker
-and W.C. Huber, eds., Portland, OR. American Society of Civil Engineers,
-Reston, VA, CD-ROM, September 2002.
-
-Huber, W.C. and L. Roesner, \"The History and Evolution of the EPA
-SWMM\" in *Fifty Years of Watershed Modeling - Past, Present And
-Future*, A.S. Donigian and R. Field, eds., ECI Symposium Series, Volume
-P20, 2013. 
-
-Huggins, L.F. and J.R. Burney, "Surface Runoff, Storage and Routing,"
-*Hydro­logic Modeling of Small Watersheds*, C.T. Haan, H.P. Johnson and
-D.L. Braken­siek, eds., American Society of Agricultural Engineers, St.
-Joseph, MI, 1982, Chapter 5, pp. 169-225.
-
-Hydroscience, Inc., "A Statistical Method for the Assessment of Urban
-Storm­water," EPA-440/3-79-023, Environmental Protection Agency,
-Washington, DC, May 1979.
-
-James, W. and J.J. Drake, "Kinematic Design Storms Incorporating Spatial
-and Time Averaging," Proceedings Storm Water Management Model User's
-Group Meeting, June 1980, EPA-600/9-80-064 (PB81-173858), U.S.
-Environmental Protection Agency, Athens, GA, December 1980, pp. 133-149.
-
-James, W. and Shtifter, Z., "Implications of Storm Dynamics on Design
-Storm Inputs," Proceedings, Stormwater and Water Quality Management
-Modeling and SWMM Users Group Meeting, September 28-29, 1981, USEPA and
-Ontario Ministry of the Environment, Dept. of Civil Engineering,
-McMaster University, Hamilton, Ontario, September 1981, pp. 55-78.
-
-Jens, S.W. and McPherson, M.B., "Hydrology of Urban Areas," in *Handbook
-of Applied Hydrology*, V.T. Chow, ed., McGraw-Hill, New York, 1964.
-
-Jensen, M.E., Burman, R.D. and R.G. Allen, eds., *Evapotranspiration and
-Irrigation Water Requirements*, ASCE Manuals and Reports on Engineering
-Practice No. 70, American Society of Civil Engineers, Reston, VA, 1990.
-
-Kidd, C.H.R., "A Calibrated Model for the Simulation of the Inlet
-Hydrograph for Fully Sewered Catchments," in *Urban Storm Drainage*,
-Proceedings Interna­tional Conference on Urban Storm Drainage, University
-of Southampton, April 1978, Helliwell, P.R., ed., Pentech Press, London,
-1978a, pp. 172-186.
-
-Kidd, C.H.R., "Rainfall-Runoff Processes Over Urban Surfaces,"
-Proceedings International Workshop held at the Institute of Hydrology,
-Wallingford, Oxon, England, April 1978b.
-
-King County Department of Public Works. 1995. King County Public Rules
-Department of Department and Environmental Services.
-
-
-Kluitenberg, E., "Determination of Impervious Area and Directly
-Connected Impervious Area", Supplemental Report, Rouge River National
-Wet Weather Demonstration Project, August 1994
-(http://www.rougeriver.com/pdfs/modeling/RPO-MOD-SR35.pdf).
-
-Lai, F-h., "Review of Sewer Design Criteria and RDII Prediction
-Methods", EPA/600/R-08/010,
-
-U.S. Environmental Protection Agency, Cincinnati, OH, January, 2008.
-
-Laliberte, G.E., Corey, A.T. and Brooks, R.H., "Properties of
-Unsaturated Porous Media," Hydrology Paper No. 17, Colorado State
-University, Fort Col­lins, CO, November 1966.
-
-Leavesley, G.H., Lichty, R.W., Troutman, B.M., and Saindon, L.G.,
-*Precipitation-Runoff Modeling System: User\'s Manual*, U.S. Geological
-Survey Water-Resources Investigations Report 83-4238, 1983.
-
-Lee, J.G., *Process Analysis and Optimization of Distributed Urban
-Stormwater Management Strategies*, Ph.D. Thesis, Department of Civil,
-Environmental and Architectural Engineering, University of Colorado,
-Boulder, 2003.
-
-Lee, J.G. and J.P. Heaney, "Estimation of Urban Imperviousness and its
-Impacts on Storm Water Systems," *Journal of Water Resources Planning
-and Management*, Vol. 129, No. 5, 2003, pp. 419-426.
-
-Linsley, R.K., Jr., Kohler, M.A. and Paulhus, J.L.H., *Applied
-Hydrology*, McGraw-Hill, New York, 1949.
-
-Linsley, R.K., M.A. Kohler and J.L.H Paulus, *Hydrology for Engineers*,
-McGraw-Hill, New York, Second Edition, 1975.
-
-Linsley, R.K., Kohler, M.A. and Paulhus, J.L.H., *Hydrology for
-Engineers*, McGraw-Hill, New York, Third Edition, 1982.
-
-Lindström, G., Johansson, B., Persson, M., Gardelin, M. and S.
-Bergström, "Development and Test of the Distributed HBV-96 Hydrological
-Model," *Journal of Hydrology*, Vol. 201, 1997, pp. 272-288.
-
-List, R.J., ed., *Smithsonian Meteorological Tables*, Smithsonian
-Institution, Washington, DC, Sixth Revised Edition, 1966.
-
-Maidment, D.R., ed., *Handbook of Hydrology*, McGraw-Hill, New York,
-1993.
-
-Marsalek, J., "Synthesized and Historical Storms for Urban Drainage
-Design," in *Urban Storm Drainage*, Proceedings International Conference
-on Urban Storm Drainage, University of Southampton, April 1978,
-Helliwell, P.R., ed., Pentech Press, London, 1978a, pp. 87-99.
-
-McCuen, R.H., *Hydrologic Analysis and Design*, Prentice-Hall, Inc.,
-Upper Saddle River, NJ, Second Edition, 1998.
-
-Meeneghan, T.J., Loehlein, M.D., Dickinson, R.E., Myers, R.D. and T.
-Prevost, "Impacts of Rainfall Data on Model Refinement in the Greater
-Pittsburgh Area," In *Global Solutions for Urban Drainage*, Proc. Ninth
-International Conference on Urban Drainage, E.W. Strecker and W.C.
-Huber, eds., Portland, OR, American Society of Civil Engineers, Reston,
-VA, CD-ROM, September 2002.
-
-Meeneghan, T.J., Loehlein, M.D., Dickinson, R.E., and T. Prevost, "Model
-Calibration of a Large Urban Sewer System Using Radar Precipitation
-Information," Chapter 11 in James, W., ed., *Practical Modeling of Urban
-Water Systems*, Monograph 11, Proceedings of Conference on Urban Water
-Systems Modeling, Toronto, 2002, Computational Hydraulics International,
-Guelph, ON, 2003, pp. 199-216.
-
-Mein, R.G. and Larson, C.L., " Modeling Infiltration During a Steady
-Rain," *Water Resources Research*, Vol. 9, No. 2, April 1973, pp.
-384-394.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume I ­ Final Report,"
-EPA Report 11024 DOC 07/71 (NTIS PB-203289), U.S. Environmental
-Protection Agency, Washington, DC, July 1971a.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume II ­ Verification
-and Testing," EPA Report 11024 DOC 08/71 (NTIS PB-203290), U.S.
-Environmental Protection Agency, Washington, DC, August 1971b.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume III ­ User's
-Manual," EPA-11024 DOC 09/71 (NTIS PB-203291), U.S. Environmental
-Protection Agency, Washington, DC, September 1971c.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume IV ­ Program
-Listing," EPA Report 11024 DOC 10/71 (NTIS PB-203292), U.S.
-Environmental Protection Agency, Washington, DC, October 1971d.
-
-Miller, C.R. and W. Viessman, Jr., "Runoff Volumes from Small Urban
-Water­sheds," *Water Resources Research*, Vol. 8, No. 2, April 1972, pp.
-429-434.
-
-Musgrave, G.W., "How Much Water Enters the Soils," *U.S.D.A. Yearbook*,
-U.S. Department of Agriculture, Washington, DC, 1955, pp. 151-159.
-
-Nicklow, J.W., Boulos, P.F., and Muleta, M.K., *Comprehensive Urban
-Hydrologic Modeling Handbook for Engineers and Planners,* MWH Soft,
-Inc., Pasadena, CA, 2006.
-
-National Oceanic and Atmospheric Administration, *Climates of the
-States*, Vol­umes I and II, Water Information Center, Inc., Port
-Washington, NY, 1974.
-
-Natural Resource Conservation Service (NRCS), *Urban Hydrology for Small
-Watersheds*, Technical Release 55, Second Ed., U.S. Department of
-Agriculture, Washington, DC, June, 1986.
-
-Natural Resource Conservation Service (NRCS), "Hydrologic Soil-Cover
-Complexes", *National Engineering Handbook*, Part 630, Chapter 9, U.S.
-Dept. of Agriculture, Washington, DC, July, 2004a.
-
-Natural Resource Conservation Service (NRCS), "Estimation of Direct
-Runoff from Storm Rainfall", *National Engineering Handbook*, Part 630,
-Chapter 10, U.S. Dept. of Agriculture, Washington, DC, July, 2004b.
-
-Natural Resource Conservation Service (NRCS), "Hydrographs", *National
-Engineering Handbook*, Part 630, Chapter 7, U.S. Dept. of Agriculture,
-Washington, DC, March, 2007.
-
-Natural Resource Conservation Service (NRCS), "Hydrologic Soil Groups",
-*National Engineering Handbook*, Part 630, Chapter 7, U.S. Dept. of
-Agriculture, Washington, DC, January, 2009.
-
-Natural Resource Conservation Service (NRCS), "Time of Concentration",
-*National Engineering Handbook*, Part 630, Chapter 15, U.S. Dept. of
-Agriculture, Washington, DC, May, 2010.
-
-Overton, D.E. and Meadows, M.E., *Stormwater Modeling*, Academic Press,
-New York, 1976.
-
-Petryk, S. and Bosmajian, G, "Analysis of Flow Through Vegetation,"
-*Journal of the Hydraulics Division, ASCE*, Vol. 101, No. HY7, July
-1975, pp. 871-884.
-
-Pitt, R.E. and J. Voorhees, *The Source Loading and Management Model
-(SLAMM), A Water Quality Management Planning Model for Urban Stormwater
-Runoff*, University of Alabama, Department of Civil and Environmental
-Engineering, Tuscaloosa, AL, 2000.
-
-Pitt, R., Lantrip, J., Harrison, R., Henry, C.L., and D. Xue,
-*Infiltration Through Disturbed Urban Soils and Compost-Amended Soil
-Effects on Runoff Quality and Quantity*, EPA/600/R-00/016, Environmental
-Protection Agency, Cincinnati, OH, December 1999.
-
-Pitt, R., Chen, S-E., Ong, C.K., and S. Clark, "Measurements of
-Infiltration Rates in Compacted Urban Soils," in *Linking Stormwater BMP
-Designs and Performance to Receiving Water Impact Mitigation*, B.R.
-Urbonas, ed., Proceedings of Engineering Foundation Conference,
-Snowmass, CO, American Society of Civil Engineers, Reston, VA, 2001, pp.
-534-538.
-
-Portland Bureau of Environmental Services, *SWMM Modeling Training
-Manual*, BES Design Staff Edition, City of Portland, Bureau of
-Environmental Services, Portland, OR, 1996.
-
-Press, W.H., Teukolsky, S.A., Vetterling, W.T. and B.P. Flannery,
-*Numerical Recipes in C, The art of Scientific Computing*, Cambridge
-University Press, New York, Second Edition, 1992.
-
-Proctor and Redfern, Ltd. and James F. MacLaren, Ltd., "Stormwater
-Management Model Study ­ Vol. I, Final Report," Research Report No. 47,
-Canada-Ontario Research Program, Environmental Protection Service,
-Environment Canada, Ot­tawa, Ontario, September 1976a.
-
-Proctor and Redfern, Ltd. and James F. MacLaren, Ltd., "Storm Water
-Management Model Study ­ Volume II, Technical Background," Research
-Report No. 48, Canada-Ontario Research Program, Environmental Protection
-Service, Environment Canada, Ottawa, Ontario, September 1976b.
-
-Proctor and Redfern, Ltd. and James F. MacLaren, Ltd., "Storm Water
-Management Model Study ­ Volume III, User's Manual," Research Report No.
-62, Canada-Ontario Research Program, Environmental Protection Service,
-Environment Can­ada, Ottawa, Ontario, 1977.
-
-Rawls, W.J., P. Yates and L. Asmussen, *Calibration of Selected
-Infiltration Equations for the Georgia Coastal Plain*, Report ARS-S-113,
-U.S. Department of Agriculture, Agricultural Research Service,
-Washington, DC, 1976.
-
-Rawls, W.J., and D.L. Brakensiek, \"Estimating Soil Water Retention from
-Soil Properties.\", *Journal of Irrigation and Drainage* ASCE, vol.108,
-no 2:166-71, 1982.
-
-Rawls, W.J., D.L. Brakensiek, and N. Miller, "Green-Ampt Infiltration
-Parameters from Soils Data", *Journal of Hydraulic Engineering*, vol.
-109, no 1:62-70, 1983.
-
-Richards, L.A., \"Capillary conduction of liquids through porous
-mediums\". *Physics* 1 (5): 318--333, 1931.
-
-Richardson, D.L., Terry, R.C., Metzger, J.B., Carroll, R.J. and Little,
-A.D., "Manual for Deicing Chemicals: Application Practices,"
-EPA-670/2-74-045 (NTIS PB-236152), U.S. Environmental Protection Agency,
-Cincinnati, OH, December 1974.
-
-Roesner, L.A., Nichandros, H.M., Shubinski, R.P., Feldman, A.D., Abbott,
-J.W. and Friedland, A.O., "A Model for Evaluating Runoff-Quality in
-Metropolitan Master Planning," ASCE Urban Water Resources Research
-Program Tech. Memo No. 23 (NTIS PB-234312), ASCE, New York, NY, April
-1974.
-
-Roesner, L.A., Aldrich, J.A. and R.E. Dickinson, *Storm Water Management
-Model, Version 4, User\'s Manual: Extran Addendum,* EPA/600/3-88/001b
-(NTIS PB88-236658/AS), Environmental Protection Agency, Athens, GA,
-1988.
-
-Roy, A.H. and Shuster, W.D., "Assessing Impervious Surface Connectivity
-and Applications for Watershed Management", *Journal of the American
-Water Resources Association*, Vol. 45, No. 1, February 2007, pp.
-198--209.
-
-Saxton, K.E. and W.J. Rawls, "Soil Water Characteristic Estimates by
-Texture and Organic Matter for Hydrologic Solutions",*Soil Science
-American Journal*. 70:1569-1578. 2006.
-
-Schroeder, P. R., Aziz, N. M., Lloyd, C. M. and Zappi, P. A., \"The
-Hydrologic Evaluation of Landfill Performance (HELP) Model: User's Guide
-for Version 3,\" EPA/600/R-94/168a, U.S.
-
-Environmental Protection, Washington, DC, September 1994.
-
-Shah, N., Nachabe, M. and Ross, M., "Extinction Depth and
-Evapotranspiration from Ground Water under Selected Land Covers",
-*Groundwater*, Vol. 45, No. 3, May-June 2007, pp. 329-338.
-
-Shuster, W.D., Bonta, J., Thurston, H., Warnemuende, E., and Smith,
-D.R., "Impacts of impervious surface on watershed hydrology: A review",
-*Urban Water Journal*, Vol. 2, No. 4, 2005, pp. 263-275.
-
-Shuster, W. and Pappas, E., "Laboratory Simulation of Urban Runoff and
-Estimation of Runoff Hydrographs with Experimental Curve Numbers
-Implemented in USEPA SWMM." *J. Irrig. Drain Eng.,* Vol. 137, No.6,
-2011, pp. 343--351.
-
-Soil Conservation Service (SCS), "Soil-Plant-Water Relationships",
-*National Engineering Handbook*, Section 15, Chapter 1, U.S. Dept. of
-Agriculture, Washington, DC, December, 1991.
-
-Semádeni-Davies, S., "Representation of Snow in Urban Drainage Models,"
-*Journal of Hydrologic Engineering*, Vol. 5, No. 4, October 2000, pp.
-363-370.
-
-Singh, V.P., ed., *Computer Models of Watershed Hydrology*, Water
-Resources Publications, Highlands Ranch, CO, 1995.
-
-Skaggs, R.W. and R. Khaleel, "Infiltration," Chapter 4 in ,
-"Infiltration," Chapter 4 in *Hydrologic Modeling of Small Watersheds*,
-ASAE Monograph No. 5, American Society of Agricultural Engineers, St.
-Joseph, MI, 1982.
-
-Socolofsky, S., Adams, E., and Entekhabi, D., "Disaggregation of Daily
-Rainfall for Continuous Watershed Modeling." *Journal of Hydrologic
-Engineering*, 6(4), 300--309, 2001.
-
-South Florida Water Management District (SFWMD), "Permit Information
-Manual, Volume IV, Management and Storage of Surface Waters," South
-Florida Water Management District, West Palm Beach, FL, January 1984.
-
-Southerland, R.C., "Methods for Estimating Effective Impervious Cover"
-Article 32 in *The Practice of Watershed Protection*, Center for
-Watershed Protection, Ellicott City, MD, 2000.
-
-Surkan, A.J., "Simulation of Storm Velocity Effects of Flow from
-Distributed Channel Networks," *Water Resources Research*, Vol. 10, No.
-6, December 1974, pp. 1149-1160.
-
-Tholin, A.L. and Keifer, C.J., "Hydrology of Urban Runoff," with
-discussions, *Transactions* *ASCE*, Paper No. 3061, Vol. 125, 1960, pp.
-1308-1355.
-
-Turner, A.K., Langford, K.J., Win, M. and Clift, T.R., "Discharge-Depth
-Equa­tion for Shallow Flow," *Journal of the Irrigation and Drainage
-Division, ASCE*, Vol. 104, No. IR1, March 1978, pp. 95-110.
-
-Tennessee Valley Authority (TVA), "Heat and Mass Transfer Between a
-Water Surface and the Atmosphere," Water Resources Research Lab, Report
-No. 14, Engineering Laboratory, Norris, TN, April 1972.
-
-U.S. Environmental Protection Agency, "SWMM 5 Applications Manual",
-EPA/600/R-09/000, National Risk Management Research Laboratory, Office
-of Research and Development, Cincinnati, OH, 2009.
-
-U.S. Environmental Protection Agency, "SWMM 5 User's Manual",
-EPA/600/R-05/040, National Risk Management Research Laboratory, Office
-of Research and Development, Cincinnati, OH, 2010.
-
-U.S. Environmental Protection Agency, "Estimating Change in Impervious
-Area (IA) and Directly Connected Impervious Areas (DCIA) for New
-Hampshire Small MS4 Permit", Small MS4 Permit Technical Support
-Document, U.S. Environmental Protection Agency Region I, Boston, MA,
-2014 (http://www.epa.gov/region1/npdes/stormwater/nh/NHDCIA.pdf).
-
-Vallabhaneni, S., Vieux, S.B.E., Donovan, S. and S. Moisio,
-"Interpretation of Radar and Rain Gauge Measurements for Sewer System
-Modeling," In *Global Solutions for Urban Drainage*, Proc. Ninth
-International Conference on Urban Drainage, E.W. Strecker and W.C.
-Huber, eds., Portland, OR, American Society of Civil Engineers, Reston,
-VA, CD-ROM, September 2002.
-
-Vallabhaneni, S., Chan, C.C, and Burgess, E.H., "Computer Tools for
-Sanitary Sewer System
-
-Capacity Analysis and Planning", EPA/600/R-07/111, U.S. Environmental
-Protection Agency, Cincinnati, OH, October, 2007.
-
-Van den Berg, J.A., "Quick and Slow Response to Rainfall by an Urban
-Area," in *Urban Storm Drainage*, Proceedings International Conference
-on Urban Storm Drainage, University of Southampton, April 1978,
-Helliwell, P.R., ed., Pentech Press, London, 1978, pp. 705-712.
-
-van Schilfgaarde, J., ed., *Drainage for Agriculture*, Agronomy Series
-No. 17, American Society of Agronomy, Madison, WI, 1974.
-
-Viessman, W., Jr. and G.L. Lewis, *Introduction to Hydrology*,
-Prentice-Hall, Upper Saddle River, NJ, Fifth Edition, 2003.
-
-Wanielista, M.P., *Stormwater Management - Quantity and Quality*, Ann
-Arbor Sci­ence Publishers, Ann Arbor, MI, 1978.
-
-Westerström, G., "Snowmelt Runoff from Urban Plot," in *Urban Stormwater
-Hydraulics and Hydrology*, B.C. Yen, ed., Proc. Second International
-Conference on Urban Storm Drainage, Urbana, IL, Water Resources
-Publications, Littleton, CO, June 1981, pp. 452-459.
-
-Westerström, G., 1984. *"Snowmelt runoff from Porsön residential area.
-Luleå, Sweden*." 3rd International Conference on Urban Storm Drainage,
-Gothenburg, Sweden, pp. 315--323.
-
-Wright, L.T., Heaney, J.P., and N. Weinstein, "Modeling of Low Impact
-Development Stormwater Practices," *Proc. ASCE Conf. on Water Resources
-Engineering and Water Resources Planning and Management* (CD-ROM),
-Minneapolis, MN. ASCE, Reston, VA, 2000, 10 pp.
-
-Wright, L.T. and J.P. Heaney, "Design of Distributed Stormwater Control
-and Reuse Systems," Chapter 11 in Mays, L. (ed.) *Stormwater Collection
-Systems Design Handbook*, McGraw-Hill, New York, 2001.
-
-Yen, B.C., "Hydraulics of Sewer Systems," Chapter 6 in *Stormwater
-Collection Systems Design Handbook*, L.M. Mays, ed., McGraw-Hill, New
-York, 2001.
-
-Yen, B.C. and Chow, V.T., "A Study of Surface Runoff Due to Moving
-Rain­storms," Hydraulic Engineering Series Report No. 17, Dept. of Civil
-Engineer­ing, University of Illinois, Urbana, June 1968.
-
-# Glossary
-
-**A**
-
-**Aquifer --** as defined in SWMM, it is the underground water bearing
-layer below a land surface, containing both an upper unsaturated zone
-and a lower saturated zone.
-
-**Areal Depletion -** the process by which the land area covered by snow
-decreases as the total volume of snow decreases due to melting.
-
-**C**
-
-**Capillary Suction Head -** the soil water tension at the interface
-between a fully saturated and partly saturated soil.
-
-**Climate Data Online -** an interactive web based data retrieval
-service operated by NOAA's National Climatologic Data Center for
-retrieving historical rainfall and climate data.
-
-**Cold Content -** the difference between the heat content of a frozen
-snow pack and its base melt temperature.
-
-**Continuous Simulation -** refers to a simulation run that extends over
-more than just a single rainfall event.
-
-**Curve Number -** a factor, dependent on land cover, used to compute a
-soil's maximum moisture storage capacity.
-
-**Curve Number Method -** a method that uses a soil's maximum moisture
-storage capacity as derived from its curve number to determine how
-cumulative infiltration changes with cumulative rainfall during a
-rainfall event. Not to be confused with the NRCS (formerly SCS) Curve
-Number runoff method as embodied in TR-55.
-
-**D**
-
-**Darcy's Law -** states that flow velocity of water through a porous
-media equals the hydraulic conductivity of the media times the gradient
-of the hydraulic head it experiences.
-
-**Depression Storage --** the volume over a surface that must be filled
-prior to the occurrence of runoff. It represents such initial
-abstractions as surface ponding, interception by flat roofs and
-vegetation, and surface wetting.
-
-**Design Storm -** a rainfall hyetograph of a specific duration whose
-total depth corresponds to a particular return period (or recurrence
-interval), usually chosen from an IDF curve.
-
-**Directly Connected Impervious Area -** impervious area whose runoff
-flows directly into the collection system without the opportunity to run
-onto pervious areas such as lawns.
-
-**Dividing Temperature - t**he temperature below which precipitation
-falls in the form of snow.
-
-**F**
-
-**Field Capacity -** the amount of water a well-drained soil holds after
-free water has drained off, or the maximum soil moisture held against
-gravity. Usually defined as the moisture content at a tension of 1/3
-atmospheres.
-
-**G**
-
-**Global Historical Climatology Network -** a data base administered by
-NOAA's National Climatic Data Center that archives daily climate
-observations from approximately 30 different sources for about 30,000
-stations across the globe.
-
-**Green-Ampt Method -** a method for computing infiltration of rainfall
-into soil that is based on Darcy's Law and assumes there is a sharp
-wetting front that moves downward from the surface, separating saturated
-soil above from drier soil below.
-
-**H**
-
-**Hargreaves Method -** an empirical formula for estimating daily
-evaporation that depends on air temperature and solar radiation.
-
-**Horton Curve -** an empirical curve that describes the exponential
-decrease in infiltration rate with time during a rainfall event.
-
-**Horton Method -** a method for computing infiltration of rainfall into
-soil that uses the Horton Curve to relate infiltration rate to time,
-with modifications made to consider times where the rainfall rate is
-less than the curve's infiltration rate.
-
-**Hydraulic Conductivity -** the rate of water movement through soil
-under a unit gradient of hydraulic head. Its value increases with
-increasing soil moisture, up to a maximum for a completely saturated
-soil (known as the saturated hydraulic conductivity or Ksat).
-
-**Hydrograph -** a plot that shows how runoff flow varies with time.
-
-**Hydrologic Soil Group -** a classification that indicates a soil's
-ability to infiltrate water.
-
-**Hyetograph -** a plot that shows how rainfall rate varies with time.
-
-**I**
-
-**IDF Curves** -- a series of curves that determine the average rainfall
-intensity (I) for a given duration of storm (D) that occurs at a
-specific annual frequency (F), e.g., the intensity of a 6-hour storm
-that occurs once every 10 years.
-
-**Impervious Surface** -- a surface that does not allow infiltration of
-rain water, such as a roof, roadway or parking lot.
-
-**Infiltration** -- the process by which rainfall penetrates the ground
-surface and fills the pores of the underlying soil.
-
-**Infiltrometer** - a device used to measure the rate of water
-infiltration into soil or other porous media.
-
-**Initial Abstraction** -- precipitation that is captured on vegetative
-cover or within surface depressions that is not available to become
-runoff and is removed by either infiltration or evaporation.
-
-**L**
-
-**LID Control** -- a low impact development practice that provides
-detention storage, enhanced infiltration and evapotranspiration of
-runoff from localized surrounding areas. Examples include rain gardens,
-rain barrels, green roofs, vegetative swales, and bio-retention cells.
-
-**Link** -- a connection between two nodes of a SWMM conveyance network
-that transports water. Channels, pipes, pumps, and regulators (weirs and
-orifices) are all represented as links in a SWMM model.
-
-**M**
-
-**Manning Equation** -- the equation that relates flow rate to the slope
-of the hydraulic grade line for gravity flow in open channels.
-
-**Manning Roughness** -- a coefficient that accounts for friction losses
-in the Manning flow equation.
-
-**Modified Horton Method** -- a modified form of the Horton infiltration
-method that tracks cumulative infiltration volume instead of time along
-the Horton curve to determine how infiltration rate changes with time
-during a rainfall event.
-
-**Moisture Deficit** -- the difference between a soil's current moisture
-content and its moisture content at saturation.
-
-**N**
-
-**Newton-Raphson Method** -- a commonly used iterative numerical method
-for solving nonlinear equations that makes use of the derivative of the
-equation with respect to the unknown variable.
-
-**Node** -- a point in a runoff conveyance system that receives runoff
-and other inflows, that connects conveyance links together, or that
-discharges water out of the system. Nodes can be simple junctions, flow
-dividers, storage units, or outfalls. Every conveyance system link is
-attached to both an upstream and downstream node.
-
-**Nonlinear Reservoir Model** -- a simple conceptual model of a storage
-reservoir where the change in volume with respect to time equals the
-difference between a known inflow rate and an outflow rate that is a
-nonlinear function of the current stored volume.
-
-**O**
-
-**Overland Flow Path** -- the path that runoff follows as it flows over
-the surface of a catchment area until it reaches a collection channel or
-storm drain.
-
-**P**
-
-**Pervious Surface** -- a surface that allows water to infiltrate into
-the soil below it, such as a natural undeveloped area, a lawn or a
-gravel roadway.
-
-**Pollutograph** -- a plot of the concentration of a pollutant in runoff
-versus time.
-
-**Porosity** - the fraction of void (or air) space in a volume of soil.
-
-**R**
-
-**Rainfall File** -- an external text file that contains rainfall data
-for a single rain gage in one of the several different formats that SWMM
-can recognize.
-
-**Rainfall Interface File** -- a binary file generated by SWMM that
-contains the rainfall time series used in a simulation for all of the
-rain gages in the project. This file can be used to input rainfall in
-subsequent simulation runs.
-
-**Rain Gage** -- a SWMM object that provides precipitation data, either
-as an internal time series or through an external data file, to one or
-more subcatchment areas in a SWMM model.
-
-**RDII** -- rainfall dependent inflow and infiltration are stormwater
-flows that enter sanitary or combined sewers due to \"inflow\" from
-direct connections of downspouts, sump pumps, foundation drains, etc. as
-well as \"infiltration\" of subsurface water through cracked pipes,
-leaky joints, poor manhole connections, etc.
-
-**Richards Equation** -- the nonlinear partial differential equation
-that describes the physics of water flow in unsaturated soil as a
-function of moisture content and moisture tension.
-
-**Routing Interface File** -- a text file that contains the time history
-of external flow and water quality inflow to different locations of the
-conveyance network of a SWMM model. It can be generated from a previous
-SWMM run or can serve as a replacement for SWMM's runoff calculations.
-
-**RTK Unit Hydrograph** -- a triangular unit hydrograph that represents
-the time pattern of rainfall entering a sewer system as RDII. R is the
-fraction of total rainfall entering the system (i.e., the area under the
-hydrograph), T is the time at the hydrograph peak, and K is the ratio of
-the length of the receding limb of the hydrograph to the time to peak.
-
-**Runge-Kutta Method** -- a numerical method for solving systems of
-ordinary differential equations over a series of sequential time steps.
-
-**Runoff Coefficient** -- the ratio of total runoff to total rainfall
-over a study area.
-
-**S**
-
-**Shape Factor** -- the ratio of a watershed's area to the length of its
-main drainage channel squared. It is used to estimate the runoff width
-of a catchment area.
-
-**Snow Catch Factor** -- a multiplier used to correct for inaccurate
-snowfall measurements due to wind blowing snow away from the
-precipitation gage.
-
-**Snow Pack** -- the accumulation of snow cover that blankets an area.
-Snow pack depth increases as new snow falls and decreases as snow melts.
-
-**Subcatchment** -- a sub-area of a larger catchment area whose runoff
-flows into a single drainage pipe or channel (or onto another
-subcatchment).
-
-**Subcatchment Discretization** -- the process of dividing a study area
-into subcatchments that properly characterize the spatial variability in
-overland drainage pathways, surface properties and connections into
-drainage pipes and channels.
-
-**T**
-
-**Two-Zone Groundwater Model** -- a conceptual model that represents the
-subsurface region beneath a subcatchment as consisting of an unsaturated
-upper zone that lies above a lower saturated zone. The extent of each
-zone and the moisture content of the upper zone can change in response
-to variations in surface infiltration, evapotranspiration, and
-groundwater outflow.
-
-**U**
-
-**Unit Hydrograph** -- represents the unit response of a watershed (in
-terms of runoff volume and timing) to a unit input of rainfall. Unit
-hydrographs are specific to particular catchments and typically have
-either a triangular or bell curve shape.
-
-**W**
-
-**Wilting Point** - the soil moisture content at which plants can no
-longer extract moisture to meet their transpiration requirements.
-Usually defined as the moisture content at a tension of 15 atmospheres.
diff --git a/docs/manuals/reference/hydrology/media/media/Figure3-1.png b/docs/manuals/reference/hydrology/media/media/Figure3-1.png
index 977594db7..0b87095c3 100644
Binary files a/docs/manuals/reference/hydrology/media/media/Figure3-1.png and b/docs/manuals/reference/hydrology/media/media/Figure3-1.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/Figure3-12.png b/docs/manuals/reference/hydrology/media/media/Figure3-12.png
index 473314702..d366aa5f0 100644
Binary files a/docs/manuals/reference/hydrology/media/media/Figure3-12.png and b/docs/manuals/reference/hydrology/media/media/Figure3-12.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/Figure3-13.png b/docs/manuals/reference/hydrology/media/media/Figure3-13.png
index 2b87e78b1..c1a65f7d5 100644
Binary files a/docs/manuals/reference/hydrology/media/media/Figure3-13.png and b/docs/manuals/reference/hydrology/media/media/Figure3-13.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/Figure3-2.png b/docs/manuals/reference/hydrology/media/media/Figure3-2.png
deleted file mode 100644
index 2df52d6d3..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/Figure3-2.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/Figure3-8.png b/docs/manuals/reference/hydrology/media/media/Figure3-8.png
deleted file mode 100644
index 977594db7..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/Figure3-8.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/Figure7-1.png b/docs/manuals/reference/hydrology/media/media/Figure7-1.png
index 2602213fe..9ea2c95a6 100644
Binary files a/docs/manuals/reference/hydrology/media/media/Figure7-1.png and b/docs/manuals/reference/hydrology/media/media/Figure7-1.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure1-3.png b/docs/manuals/reference/hydrology/media/media/figure1-3.png
deleted file mode 100644
index 17db1c14f..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure1-3.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure4-2.png b/docs/manuals/reference/hydrology/media/media/figure4-2.png
deleted file mode 100644
index e19cd6983..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure4-2.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure4-3.png b/docs/manuals/reference/hydrology/media/media/figure4-3.png
deleted file mode 100644
index 13b5e5023..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure4-3.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure4-4.png b/docs/manuals/reference/hydrology/media/media/figure4-4.png
deleted file mode 100644
index 137445025..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure4-4.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure4-6.png b/docs/manuals/reference/hydrology/media/media/figure4-6.png
deleted file mode 100644
index a227ef01c..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure4-6.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure4-7.png b/docs/manuals/reference/hydrology/media/media/figure4-7.png
deleted file mode 100644
index 2ae297a80..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure4-7.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure5-1.png b/docs/manuals/reference/hydrology/media/media/figure5-1.png
deleted file mode 100644
index 648835b09..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure5-1.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure5-2.png b/docs/manuals/reference/hydrology/media/media/figure5-2.png
deleted file mode 100644
index 6bd283ce1..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure5-2.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure5-9.png b/docs/manuals/reference/hydrology/media/media/figure5-9.png
index 5b8fafa91..b1e8b8c7b 100644
Binary files a/docs/manuals/reference/hydrology/media/media/figure5-9.png and b/docs/manuals/reference/hydrology/media/media/figure5-9.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure7-11-schematic.png b/docs/manuals/reference/hydrology/media/media/figure7-11-schematic.png
deleted file mode 100644
index 5d8dc2149..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/figure7-11-schematic.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/figure1-6.png b/docs/manuals/reference/hydrology/media/media/hydrology-figure1-6.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/figure1-6.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-figure1-6.png
diff --git a/docs/manuals/reference/hydrology/media/media/image1.jpeg b/docs/manuals/reference/hydrology/media/media/hydrology-image1.jpeg
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image1.jpeg
rename to docs/manuals/reference/hydrology/media/media/hydrology-image1.jpeg
diff --git a/docs/manuals/reference/hydrology/media/media/hydrology-image10.jpg b/docs/manuals/reference/hydrology/media/media/hydrology-image10.jpg
new file mode 100644
index 000000000..8da85470a
Binary files /dev/null and b/docs/manuals/reference/hydrology/media/media/hydrology-image10.jpg differ
diff --git a/docs/manuals/reference/hydrology/media/media/hydrology-image11.png b/docs/manuals/reference/hydrology/media/media/hydrology-image11.png
new file mode 100644
index 000000000..26cbaf844
Binary files /dev/null and b/docs/manuals/reference/hydrology/media/media/hydrology-image11.png differ
diff --git a/docs/manuals/reference/hydrology/media/media/image12.png b/docs/manuals/reference/hydrology/media/media/hydrology-image12.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image12.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image12.png
diff --git a/docs/manuals/reference/hydrology/media/media/image13.png b/docs/manuals/reference/hydrology/media/media/hydrology-image13.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image13.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image13.png
diff --git a/docs/manuals/reference/hydrology/media/media/image15.png b/docs/manuals/reference/hydrology/media/media/hydrology-image15.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image15.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image15.png
diff --git a/docs/manuals/reference/hydrology/media/media/image24.png b/docs/manuals/reference/hydrology/media/media/hydrology-image24.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image24.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image24.png
diff --git a/docs/manuals/reference/hydrology/media/media/image29.png b/docs/manuals/reference/hydrology/media/media/hydrology-image29.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image29.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image29.png
diff --git a/docs/manuals/reference/hydrology/media/media/image30.png b/docs/manuals/reference/hydrology/media/media/hydrology-image30.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image30.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image30.png
diff --git a/docs/manuals/reference/hydrology/media/media/image31.png b/docs/manuals/reference/hydrology/media/media/hydrology-image31.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image31.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image31.png
diff --git a/docs/manuals/reference/hydrology/media/media/image32.png b/docs/manuals/reference/hydrology/media/media/hydrology-image32.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image32.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image32.png
diff --git a/docs/manuals/reference/hydrology/media/media/image33.png b/docs/manuals/reference/hydrology/media/media/hydrology-image33.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image33.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image33.png
diff --git a/docs/manuals/reference/hydrology/media/media/image34.png b/docs/manuals/reference/hydrology/media/media/hydrology-image34.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image34.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image34.png
diff --git a/docs/manuals/reference/hydrology/media/media/image35.png b/docs/manuals/reference/hydrology/media/media/hydrology-image35.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image35.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image35.png
diff --git a/docs/manuals/reference/hydrology/media/media/image36.png b/docs/manuals/reference/hydrology/media/media/hydrology-image36.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image36.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image36.png
diff --git a/docs/manuals/reference/hydrology/media/media/image37.png b/docs/manuals/reference/hydrology/media/media/hydrology-image37.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image37.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image37.png
diff --git a/docs/manuals/reference/hydrology/media/media/image38.png b/docs/manuals/reference/hydrology/media/media/hydrology-image38.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image38.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image38.png
diff --git a/docs/manuals/reference/hydrology/media/media/image4.png b/docs/manuals/reference/hydrology/media/media/hydrology-image4.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image4.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image4.png
diff --git a/docs/manuals/reference/hydrology/media/media/image41.png b/docs/manuals/reference/hydrology/media/media/hydrology-image41.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image41.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image41.png
diff --git a/docs/manuals/reference/hydrology/media/media/image43.png b/docs/manuals/reference/hydrology/media/media/hydrology-image43.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image43.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image43.png
diff --git a/docs/manuals/reference/hydrology/media/media/image50.png b/docs/manuals/reference/hydrology/media/media/hydrology-image50.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image50.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image50.png
diff --git a/docs/manuals/reference/hydrology/media/media/image51.png b/docs/manuals/reference/hydrology/media/media/hydrology-image51.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image51.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image51.png
diff --git a/docs/manuals/reference/hydrology/media/media/image52.png b/docs/manuals/reference/hydrology/media/media/hydrology-image52.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image52.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image52.png
diff --git a/docs/manuals/reference/hydrology/media/media/image8.png b/docs/manuals/reference/hydrology/media/media/hydrology-image8.png
similarity index 100%
rename from docs/manuals/reference/hydrology/media/media/image8.png
rename to docs/manuals/reference/hydrology/media/media/hydrology-image8.png
diff --git a/docs/manuals/reference/hydrology/media/media/image10.png b/docs/manuals/reference/hydrology/media/media/image10.png
deleted file mode 100644
index 167617512..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image10.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image11.png b/docs/manuals/reference/hydrology/media/media/image11.png
deleted file mode 100644
index d433a93cd..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image11.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image14.emf b/docs/manuals/reference/hydrology/media/media/image14.emf
deleted file mode 100644
index 455860cb0..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image14.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image16.png b/docs/manuals/reference/hydrology/media/media/image16.png
deleted file mode 100644
index 3bbeeee97..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image16.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image17.png b/docs/manuals/reference/hydrology/media/media/image17.png
deleted file mode 100644
index 64c847774..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image17.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image18.png b/docs/manuals/reference/hydrology/media/media/image18.png
deleted file mode 100644
index 395adee82..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image18.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image2.png b/docs/manuals/reference/hydrology/media/media/image2.png
deleted file mode 100644
index 71bd5b5ca..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image2.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image20.wmf b/docs/manuals/reference/hydrology/media/media/image20.wmf
deleted file mode 100644
index c721645f4..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image20.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image21.emf b/docs/manuals/reference/hydrology/media/media/image21.emf
deleted file mode 100644
index c40f90251..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image21.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image22.emf b/docs/manuals/reference/hydrology/media/media/image22.emf
deleted file mode 100644
index d7ccce32b..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image22.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image23.wmf b/docs/manuals/reference/hydrology/media/media/image23.wmf
deleted file mode 100644
index ce2c57c64..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image23.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image28.wmf b/docs/manuals/reference/hydrology/media/media/image28.wmf
deleted file mode 100644
index 14a244e25..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image28.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image3.emf b/docs/manuals/reference/hydrology/media/media/image3.emf
deleted file mode 100644
index ab9038fdf..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image3.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image39.wmf b/docs/manuals/reference/hydrology/media/media/image39.wmf
deleted file mode 100644
index c0c649e11..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image39.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image40.png b/docs/manuals/reference/hydrology/media/media/image40.png
deleted file mode 100644
index 1c0b5aa29..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image40.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image42.wmf b/docs/manuals/reference/hydrology/media/media/image42.wmf
deleted file mode 100644
index 080295c66..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image42.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image44.emf b/docs/manuals/reference/hydrology/media/media/image44.emf
deleted file mode 100644
index 2e7f1ea72..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image44.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image45.emf b/docs/manuals/reference/hydrology/media/media/image45.emf
deleted file mode 100644
index fe538fe60..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image45.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image46.emf b/docs/manuals/reference/hydrology/media/media/image46.emf
deleted file mode 100644
index 1030449b5..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image46.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image47.emf b/docs/manuals/reference/hydrology/media/media/image47.emf
deleted file mode 100644
index 324170503..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image47.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image48.emf b/docs/manuals/reference/hydrology/media/media/image48.emf
deleted file mode 100644
index cb847ba33..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image48.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image49.png b/docs/manuals/reference/hydrology/media/media/image49.png
deleted file mode 100644
index 163b0a862..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image49.png and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image5.emf b/docs/manuals/reference/hydrology/media/media/image5.emf
deleted file mode 100644
index c7e89514a..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image5.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image53.emf b/docs/manuals/reference/hydrology/media/media/image53.emf
deleted file mode 100644
index 79f558c54..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image53.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image54.emf b/docs/manuals/reference/hydrology/media/media/image54.emf
deleted file mode 100644
index 255d54d9e..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image54.emf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/media/media/image9.wmf b/docs/manuals/reference/hydrology/media/media/image9.wmf
deleted file mode 100644
index f30ed0ffb..000000000
Binary files a/docs/manuals/reference/hydrology/media/media/image9.wmf and /dev/null differ
diff --git a/docs/manuals/reference/hydrology/sections/Chapter1-Overview.md b/docs/manuals/reference/hydrology/sections/Chapter1-Overview.md
index 0ad094ff9..1bad06705 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter1-Overview.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter1-Overview.md
@@ -72,7 +72,7 @@ system. SWMM conceptualizes this system as a series of water and
 material flows between several major environmental compartments. These
 compartments include:
 
-![](hydrology/media/media/image1.jpeg "image1")
+![](hydrology/media/media/hydrology-image1.jpeg "image1")
 Figure 1-1 Elements of a typical urban drainage system
 
 
@@ -122,8 +122,27 @@ SWMM model. Table 1-2 provides a summary of the various objects used in
 SWMM. Their properties and functions will be described in more detail
 throughout the course of this manual.
 
-![](hydrology/media/media/image2.png "image2")
-Figure 1-2 SWMM's conceptual model of a stormwater drainage system
+![Figure 1-2 Objects of an OpenSWMM model](figures/png/eng_object_sketch.png)
+Figure 1-2 Objects of an OpenSWMM model
+
+

+@ref engine_manual_sect_RAINGAGES "Rain gage"
+@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S1"
+@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S2"
+@ref engine_manual_sect_JUNCTIONS "Junction"
+@ref engine_manual_sect_CONDUITS "Conduit"
+@ref engine_manual_sect_VIRTUAL_JUNCTIONS "Virtual junction"
+@ref engine_manual_sect_INLET_JUNCTIONS "Inlet junction"
+@ref engine_manual_sect_STREETS "Street conduit"
+@ref engine_manual_sect_DIVIDERS "Divider"
+@ref engine_manual_sect_WEIRS "Weir"
+@ref engine_manual_sect_ORIFICES "Orifice"
+@ref engine_manual_sect_STORAGE "Storage unit"
+@ref engine_manual_sect_PUMPS "Pump"
+@ref engine_manual_sect_OUTFALLS "Outfall"
+@ref engine_manual_sect_2D_TRIANGLES "2D mesh"
+@ref engine_manual_sect_2D_VERTEX_NODE_MAP "1D–2D exchange"
+

 
 **Table 1-2 SWMM's modeling objects**
 
@@ -157,8 +176,69 @@ throughout the course of this manual.
 
 ## 1.3 SWMM's Process Models
 
-![](hydrology/media/media/figure1-3.png "Processes modeled by SWMM")
-Figure 1-3 Processes modeled by SWMM
+![Figure 1-3 Processes modelled by OpenSWMM](figures/png/eng_process_flow.png)
+Figure 1-3 Processes modelled by OpenSWMM
+
+

+@ref hydrology_ref_ch2_meteorology "Precipitation"
+@ref engine_manual_sect_RAINGAGES "rain · snow"
+@ref hydrology_ref_ch2_meteorology "scale factors"
+@ref hydrology_ref_ch6_snowmelt "Snowmelt"
+@ref hydrology_ref_ch6_snowmelt "degree-day · areal depletion"
+@ref hydrology_ref_ch3_surface_runoff "Initial abstraction · evaporation"
+@ref engine_manual_sect_SUBAREAS "depression storage"
+@ref hydrology_ref_ch3_surface_runoff "Surface runoff"
+@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir"
+@ref hydrology_ref_ch4_infiltration "Horton · Green-Ampt · CN"
+@ref quality_ref_ch6_lid_controls "LID controls"
+@ref quality_ref_ch6_lid_controls "layered units"
+@ref quality_ref_ch6_lid_controls "storage nodes"
+@ref quality_ref_ch4_surface_washoff "Washoff"
+@ref quality_ref_ch3_pollutant_buildup "EMC · exponential · rating"
+@ref hydrology_ref_ch5_groundwater "Groundwater"
+@ref hydrology_ref_ch5_groundwater "two-zone aquifer per subcatchment"
+@ref hydrology_ref_ch9_mesh_groundwater "two-layer aquifer on the mesh"
+@ref hydrology_ref_ch9_mesh_groundwater "groundwater transport"
+@ref quality_ref_ch3_pollutant_buildup "Pollutant buildup"
+@ref quality_ref_ch3_pollutant_buildup "land uses · sweeping"
+@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh"
+@ref hydrology_ref_ch8_mesh_surface "natural neighbour"
+@ref hydraulics_ref_ch9_two_dimensional "2D overland flow"
+@ref hydraulics_ref_ch9_two_dimensional "local inertial"
+@ref hydraulics_ref_ch9_two_dimensional "full shallow water"
+@ref hydraulics_ref_ch9_two_dimensional "diffusive wave"
+@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration · evaporation"
+@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment · mesh aquifer"
+@ref quality_ref_ch10_mesh_quality "2D surface quality"
+@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff"
+@ref engine_manual_sect_INFLOWS "External inflows"
+@ref engine_manual_sect_DWF "dry weather flow"
+@ref hydrology_ref_ch7_rdii "RDII: RTK"
+@ref hydrology_ref_ch7_rdii "RDII: IA decay"
+@ref engine_manual_sect_INFLOWS "user · interface files"
+@ref hydraulics_ref_ch7_advanced_features "Street inlets"
+@ref hydraulics_ref_ch7_advanced_features "HEC-22 link attribute"
+@ref hydraulics_ref_ch7_advanced_features "inlet junction"
+@ref hydraulics_ref_ch2_hydraulic_model "Channel, pipe and storage routing"
+@ref hydraulics_ref_ch2_hydraulic_model "steady"
+@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave"
+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN · slot · dynamic slot"
+@ref hydraulics_ref_ch3_dynamic_wave "TPA"
+@ref hydraulics_ref_ch3_dynamic_wave "virtual · inlet junctions"
+@ref quality_ref_ch5_transport_treatment "Transport and reactions"
+@ref quality_ref_ch5_transport_treatment "CSTR"
+@ref quality_ref_ch7_ard_transport "ARD"
+@ref quality_ref_ch7_ard_transport "LARD"
+@ref quality_ref_ch5_transport_treatment "first-order decay"
+@ref quality_ref_ch8_msx_reactions "MSX"
+@ref quality_ref_ch9_age_heat "water age"
+@ref quality_ref_ch9_age_heat "heat"
+@ref quality_ref_ch11_planned "sediment"
+@ref engine_manual_sect_TREATMENT "treatment · diversion"
+@ref engine_manual_sect_OUTFALLS "Outfalls"
+

 
 Figure 1-3 depicts the processes that SWMM models using the objects
 described previously and how they are tied to one another. The
@@ -384,7 +464,7 @@ aforementioned input file and for viewing the computed output.
 
 ## 1.5 Interpolation and Units
 
-![](hydrology/media/media/figure1-6.png "Interpolation of reported values from computed values")
+![](hydrology/media/media/hydrology-figure1-6.png "Interpolation of reported values from computed values")
 Figure 1-6 Interpolation of reported values from computed values
 
 SWMM uses linear interpolation to obtain values for quantities at times
@@ -438,6 +518,137 @@ back to the user's choice of unit system.
 | Width | feet | meters |
 | Wind Speed | miles/hour | kilometers/hour |
 
-
-
-
+## 1.6 The Formulations This Manual Covers
+
+Figure 1-7 places the hydrology of this manual on OpenSWMM's process map: the
+atmosphere, the two representations of the land surface — lumped
+subcatchments and the distributed 2D mesh — and the two representations of
+the subsurface. Each alternative carries its status (Implemented,
+Experimental, Planned or Retired); the conveyance compartment, documented in
+@ref hydraulics_reference_manual, is shown faded.
+
+![Figure 1-7 The hydrology of this manual: atmosphere, land surface and subsurface representations](figures/png/hydrology_conceptual_map.png)
+
+Figure 1-7 The hydrology of this manual: atmosphere, land surface and subsurface representations
+
+

+@ref hydrology_ref_ch2_meteorology "Precipitation"
+@ref engine_manual_sect_RAINGAGES "rain gages"
+@ref hydrology_ref_ch6_snowmelt "rain · snow split (SCF)"
+@ref hydrology_ref_ch2_meteorology "scale factors"
+@ref hydrology_ref_ch2_meteorology "Climate"
+@ref engine_manual_sect_TEMPERATURE "temperature"
+@ref engine_manual_sect_EVAPORATION "evaporation: constant · monthly · series · Hargreaves · file"
+@ref engine_manual_sect_TEMPERATURE "wind"
+@ref hydrology_ref_ch2_meteorology "humidity · dew point"
+@ref hydrology_ref_ch2_meteorology "prescribed PET (API)"
+@ref hydrology_ref_ch6_snowmelt "Snowmelt"
+@ref hydrology_ref_ch6_snowmelt "degree-day · heat budget · areal depletion"
+@ref hydrology_ref_ch3_surface_runoff "Runoff"
+@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir"
+@ref engine_manual_sect_SUBAREAS "depression storage"
+@ref engine_manual_sect_SUBAREAS "routing to another subcatchment"
+@ref hydrology_ref_ch4_infiltration "Infiltration"
+@ref hydrology_ref_ch4_infiltration "Horton"
+@ref hydrology_ref_ch4_infiltration "modified Horton"
+@ref hydrology_ref_ch4_infiltration "Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "modified Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "curve number"
+@ref quality_ref_ch6_lid_controls "LID controls"
+@ref quality_ref_ch6_lid_controls "layered units (8 types)"
+@ref quality_ref_ch6_lid_controls "LID as storage nodes"
+@ref quality_ref_ch6_lid_controls "detailed output"
+@ref quality_ref_ch3_pollutant_buildup "Surface quality"
+@ref quality_ref_ch3_pollutant_buildup "buildup · washoff by land use"
+@ref engine_manual_sect_LANDUSES "street sweeping"
+@ref quality_ref_ch10_mesh_quality "MSX species"
+@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh"
+@ref hydrology_ref_ch8_mesh_surface "natural neighbour"
+@ref engine_manual_sect_2D_OPTIONS "system"
+@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration"
+@ref hydrology_ref_ch8_mesh_surface "Horton · Green-Ampt · CN · constant"
+@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment aquifer · mesh aquifer"
+@ref hydraulics_ref_ch9_two_dimensional "Overland flow"
+@ref hydraulics_ref_ch9_two_dimensional "local inertial"
+@ref hydraulics_ref_ch9_two_dimensional "full shallow water"
+@ref hydraulics_ref_ch9_two_dimensional "diffusive wave"
+@ref hydraulics_ref_ch10_planned "IMEX / CVODE"
+@ref hydraulics_ref_ch9_two_dimensional "Mesh and closure"
+@ref hydraulics_ref_ch9_two_dimensional "triangles"
+@ref hydraulics_ref_ch9_two_dimensional "quads"
+@ref hydraulics_ref_ch9_two_dimensional "flat cells"
+@ref hydraulics_ref_ch9_two_dimensional "VFR closure"
+@ref quality_ref_ch10_mesh_quality "Surface quality · transport"
+@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff"
+@ref quality_ref_ch10_mesh_quality "species on the mesh"
+@ref hydraulics_ref_ch9_two_dimensional "Backends"
+@ref hydraulics_ref_ch9_two_dimensional "CPU"
+@ref hydraulics_ref_ch9_two_dimensional "OpenMP"
+@ref hydraulics_ref_ch9_two_dimensional "CUDA · HIP · SYCL"
+@ref hydraulics_ref_ch10_planned "Metal"
+@ref hydrology_ref_ch5_groundwater "Two-zone aquifer"
+@ref hydrology_ref_ch5_groundwater "unsaturated + saturated zone"
+@ref engine_manual_sect_AQUIFERS "percolation · deep percolation · ET"
+@ref engine_manual_sect_GWF "lateral interflow, user [GWF]"
+@ref hydrology_ref_ch9_mesh_groundwater "Groundwater transport"
+@ref hydrology_ref_ch9_mesh_groundwater "advection–dispersion · heat"
+@ref hydrology_ref_ch9_mesh_groundwater "Two-layer aquifer"
+@ref hydrology_ref_ch9_mesh_groundwater "Gardner"
+@ref hydrology_ref_ch9_mesh_groundwater "Russo"
+@ref hydrology_ref_ch9_mesh_groundwater "Brooks–Corey"
+@ref hydrology_ref_ch9_mesh_groundwater "van Genuchten"
+@ref hydrology_ref_ch9_mesh_groundwater "closed form · enslaved · σ column"
+@ref hydrology_ref_ch9_mesh_groundwater "Dunne return flow"
+@ref hydrology_ref_ch9_mesh_groundwater "node–bed exchange"
+@ref hydrology_ref_ch9_mesh_groundwater "capillary rise · boundary ET"
+@ref hydrology_ref_ch9_mesh_groundwater "per-subcatchment mode"
+@ref engine_manual_sect_JUNCTIONS "Nodes"
+@ref engine_manual_sect_JUNCTIONS "junction · storage · divider · outfall"
+@ref hydraulics_ref_ch3_dynamic_wave "virtual junction"
+@ref hydraulics_ref_ch7_advanced_features "inlet junction"
+@ref engine_manual_sect_CONDUITS "Links"
+@ref hydraulics_ref_ch5_cross_section "conduits, 26 sections"
+@ref hydraulics_ref_ch5_cross_section "street · dummy"
+@ref hydraulics_ref_ch10_planned "Chebyshev irregular"
+@ref engine_manual_sect_PUMPS "pumps · orifices · weirs · outlets · culverts"
+@ref hydraulics_ref_ch5_cross_section "storage shapes"
+@ref hydraulics_ref_ch7_advanced_features "HEC-22 inlets"
+@ref hydraulics_ref_ch2_hydraulic_model "Flow routing"
+@ref hydraulics_ref_ch2_hydraulic_model "steady"
+@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave"
+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+@ref hydraulics_ref_ch8_lts "local time stepping"
+@ref hydraulics_ref_ch10_planned "1D GPU backend"
+@ref hydraulics_ref_ch3_dynamic_wave "Pressurisation"
+@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN"
+@ref hydraulics_ref_ch3_dynamic_wave "slot"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic slot"
+@ref hydraulics_ref_ch3_dynamic_wave "TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: slot"
+@ref hydraulics_ref_ch8_finite_volume "FV: TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: implicit head"
+@ref hydraulics_ref_ch3_dynamic_wave "unsteady friction"
+@ref hydraulics_ref_ch3_dynamic_wave "Node solution"
+@ref hydraulics_ref_ch3_dynamic_wave "explicit continuity"
+@ref hydraulics_ref_ch3_dynamic_wave "semi-implicit continuity"
+@ref hydraulics_ref_ch3_anderson "Anderson acceleration"
+@ref hydraulics_ref_ch10_planned "FV_NODE_* keys"
+@ref quality_ref_ch5_transport_treatment "Transport"
+@ref quality_ref_ch5_transport_treatment "CSTR"
+@ref quality_ref_ch7_ard_transport "Eulerian ARD"
+@ref quality_ref_ch7_ard_transport "Lagrangian LARD"
+@ref quality_ref_ch7_ard_transport "random-walk dispersion"
+@ref quality_ref_ch5_transport_treatment "first-order decay"
+@ref quality_ref_ch8_msx_reactions "MSX reactions"
+@ref quality_ref_ch9_age_heat "water age"
+@ref quality_ref_ch9_age_heat "heat"
+@ref quality_ref_ch11_planned "sediment"
+@ref engine_manual_sect_TREATMENT "treatment functions"
+@ref engine_manual_sect_INFLOWS "Inflows"
+@ref engine_manual_sect_DWF "dry weather flow"
+@ref hydrology_ref_ch7_rdii "RDII: RTK"
+@ref hydrology_ref_ch7_rdii "RDII: IA decay"
+@ref engine_manual_sect_INFLOWS "user · interface files"
+@ref engine_manual_sect_CONTROLS "control rules"
+

diff --git a/docs/manuals/reference/hydrology/sections/Chapter10-PlannedFormulations.md b/docs/manuals/reference/hydrology/sections/Chapter10-PlannedFormulations.md
new file mode 100644
index 000000000..439e7285f
--- /dev/null
+++ b/docs/manuals/reference/hydrology/sections/Chapter10-PlannedFormulations.md
@@ -0,0 +1,298 @@
+@page hydrology_ref_ch10_planned Chapter 10: Planned Formulations
+
+@tableofcontents
+
+\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Nothing in this chapter is in this release as designed.** \status{Planned}
+Chapters 2 through 9 describe formulations the shipped engine executes; this
+chapter records the ones it does not — designed and not built, or built with
+a stated gap between what the code does and what its design or the literature
+says it should — so that a plan file cited in a commit, a warning met in a
+report, or a limitation stated in an earlier chapter can be followed to its
+record. *Planned* means designed and not built, whatever the plan's own
+optimism; *Experimental* means in the code and usable, with the gap named.
+Every section names its plan of record by path; the plans are not part of the
+manual, and the code is the source of truth where they disagree. The
+hydraulic half of the same record is
+@ref hydraulics_ref_ch10_planned "Hydraulics Chapter 10".
+
+| Section | Formulation | Plan of record | Status |
+|---|---|---|---|
+| 10.1 | Groundwater transport in the mesh aquifer, the hydrology side | Groundwater-transport design, 2026-09-04 (@ref quality_ref_ch11_planned "Quality Chapter 11" §11.2); `ROADMAP.md` §2.3 | \status{Planned} |
+| 10.2 | LID controls as storage nodes, the hydrology side | `plans/LID_StorageNode_Redesign.md`; `ROADMAP.md` §6 | \status{Planned} |
+| 10.3 | LID detailed output | `plans/LID_DETAIL_OUTPUT_PLAN_2026-08-13.md` | \status{Planned} |
+| 10.4 | The non-Gardner recharge closures and the benchmarks that would promote them | `plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md` §9 steps 4, 7, 13, 18; `plans/TWO_ZONE_GROUNDWATER_FV_INTEGRATION_PLAN.md` §5 | \status{Experimental} |
+| 10.5 | `MODE PER_SUBCATCH` for the mesh aquifer | `plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md` §9 steps 8, 22 | \status{Experimental} |
+
+*Table 10-1 Formulations recorded in this chapter*
+
+## 10.1 Groundwater transport in the mesh aquifer, the hydrology side
+
+The engine accepts six `[GW_*]` sections — @ref engine_manual_sect_GW_TRANSPORT_OPTIONS,
+@ref engine_manual_sect_GW_TRANSPORT_PARAMS, @ref engine_manual_sect_GW_SORPTION,
+@ref engine_manual_sect_GW_INITIAL_QUALITY, @ref engine_manual_sect_GW_BOUNDARY_QUALITY
+and @ref engine_manual_sect_GW_SOURCES. They are registered and parsed,
+validated at open against the mesh, the species registry and the time series
+(cells on the mesh, an edge in \f$0 \ldots n_v - 1\f$ of its own cell, species
+through the one registry, a duplicate source name an error), written back by
+the input writer and editable through the C API of
+`openswmm_gw_transport.h`. **They drive nothing.** Every run that authors any
+of them puts one warning in the report:
+
+> [GW_*] subsurface transport is AUTHORED but INERT this run: the integrated
+> 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides
+> the two-zone kernel these sections configure and is not available in this
+> release. The rows are validated, kept and written back unchanged.
+
+**What the design intends.** The plan of record moves every species class the
+project carries through the two-zone aquifer of
+@ref hydrology_ref_ch9_mesh_groundwater "Chapter 9": pollutants with
+retardation, dispersion and first-order decay; MSX species of
+@ref quality_ref_ch8_msx_reactions "Quality Chapter 8" under a new
+`SUBSURFACE` reaction scope; water age; and temperature with conduction. In
+the saturated zone the state is species mass in the cell's water,
+\f$n h_g A C\f$, and the balance is
+
+\f[ R_f\,\frac{\partial (n h_g C)}{\partial t} = -\nabla\cdot(\mathbf{q}\,C) + \nabla\cdot\bigl(n h_g \mathbf{D}\,\nabla C\bigr) + S_C - \lambda\, n h_g C, \qquad R_f = 1 + \frac{1-n}{n}\,\rho_s K_d \f]
+
+with \f$\mathbf{D}\f$ from molecular diffusion and longitudinal and transverse
+dispersivities on the Darcy velocity. In the unsaturated zone closure A's
+single store is a well-mixed reactor fed at the surface-water concentration
+and drained by \f$q_0\f$ at its own; closure B's σ layers carry a
+one-dimensional vertical advection on the column's own ALE fluxes, first-order
+upwind, plus vertical dispersion. Heat follows the same pattern with effective
+properties taken from the actual moisture state,
+
+\f[ (\rho c)_{eff}\,\frac{\partial T}{\partial t} = -\rho_w c_w\,\nabla\cdot(\mathbf{q}\,T) + \nabla\cdot\bigl(\lambda_{eff}\,\nabla T\bigr) + \sum S_H, \qquad (\rho c)_{eff} = \theta\,\rho_w c_w + (1-n)\,\rho_s c_s \f]
+
+a vertical conduction chain from the surface boundary through the layers to a
+geothermal or fixed deep boundary, lateral conduction on the saturated edges,
+and latent removal where evapotranspiration takes water — solutes stay behind
+(evapoconcentration). Advection is not a solver of its own: each volume flux
+the kernel books in `fireGwFaces` and `fireGwCells` (§9.9) carries a tuple of
+species mass, age-volume and enthalpy at the donor's concentration, so
+conservation across the tier ladder is inherited from the kernel and proved
+once.
+
+**Coupling to the surface transport.** Infiltration enters the top of the
+column at the 2D cell's water concentration where the cell is inundated and at
+the rainfall or runon concentration otherwise; rejected infiltration and the
+Dunne return flow of §9.7 go back up at the top layer's concentration; the
+node–aquifer exchange of §9.6 carries the tuple in both directions, so
+exfiltration takes mass and heat out of a node and groundwater inflow brings
+the aquifer's in. That replaces the constant groundwater concentration,
+temperature and age the legacy aquifer supplies at the node seam today — on
+positive groundwater flow only, with exfiltration carrying nothing — which the
+plan would migrate to `[GW_INITIAL_QUALITY] * SAT` rows on open, as initial
+conditions rather than eternal constants.
+
+**No kernel exists.** `src/engine/2d/gw/` holds the data, the parsers, the
+validator and the C API only; none of the planned `SubsurfaceTransportState`,
+`SubsurfaceTransport` or `SoilThermal` sources is in the tree, no reaction file
+accepts a `SUBSURFACE` scope, and phases T7.1 to T7.4 of the plan are gated on
+the flow kernel. The plan's own baseline states that the 2D subsurface kernel
+does not exist — true when it was written, overtaken by Chapter 9 since — so
+its first act would be re-verification against the kernel that now runs. \status{Planned}
+
+
+
+## 10.2 LID controls as storage nodes, the hydrology side
+
+The LID controls of @ref quality_ref_ch6_lid_controls "Quality Chapter 6"
+are subcatchment attributes: a unit occupies a fraction of its subcatchment,
+its layers form a downward cascade — surface to soil by infiltration, soil to
+storage by percolation at field capacity, storage to underdrain by an orifice
+law on the storage depth alone — and it hands its outflow on through the runon
+mechanism as a flow rate, never a head. The plan of record's problem statement
+is that this cannot express anything hydraulic: a saturated downstream unit
+cannot throttle the one above it, a control structure between units has no
+place in the topology, and an underdrain beneath a surcharged pipe keeps
+draining because its driving head is one-sided.
+
+**What changes for hydrology.** The LID unit becomes a node of the network —
+a storage node (@ref engine_manual_sect_STORAGE) carrying a new
+`[LID_LAYERS]` attribute that gives each layer a fractional depth, porosity,
+conductivity and moisture limits — and takes over the water balance the
+subcatchment used to run for it: its own rainfall and evaporation on its
+surface, inflow by runon from the contributing area (the existing mechanism;
+no new hydrological machinery), and a head resolved at every hydraulic step.
+The media layer keeps a hydrological model, a kinematic-wave reduction of
+Richards' equation that drops the matric-potential gradient on the argument
+that engineered media drain by gravity,
+
+\f[ \frac{\partial\theta}{\partial t} = \frac{\partial}{\partial z}\,K(\theta), \qquad K(\theta) = K_s\left(\frac{\theta}{\theta_s}\right)^{n} \f]
+
+discretised by the method of lines into \f$N\f$ sublayers,
+\f$d\theta_i/dt = (q_{i-1} - q_i)/\Delta z_i\f$ plus any link sink mapped to
+that elevation, every flux limited to the water the sublayer holds,
+\f$q_i = \min\bigl(K(\theta_i),\ (\theta_i - \theta_r)\,\Delta z_i/\Delta t\bigr)\f$.
+No retention curve is needed: the node's head partitions the profile into a
+saturated lower zone whose head is the node's and an unsaturated upper zone
+governed by moisture content alone, and percolation at the media base is free
+drainage at \f$K(\theta_N)\f$ above field capacity. The two domains keep
+their own clocks — the media on the hydrological step, the gravel layer (the
+storage node itself) and its links on the hydraulic step — joined by the
+slowly varying percolation flux.
+
+**What stays.** The eight layered unit types, `[LID_CONTROLS]` and
+`[LID_USAGE]` (@ref engine_manual_sect_LID_CONTROLS,
+@ref engine_manual_sect_LID_USAGE) and the subcatchment cascade remain the
+default representation, by the roadmap's compatibility clause; the storage-node
+form is an alternative a modeller would opt into for the units whose behaviour
+is hydraulic. The other half of the design — the porosity-corrected storage
+curve, the underdrain as an offset orifice with the network's head on its far
+side, overflow as a weir, chains as ordinary node–link topology — is hydraulic
+and recorded in @ref hydraulics_ref_ch10_planned "Hydraulics Chapter 10, §10.8".
+
+The status is design recorded, no implementation. No `[LID_LAYERS]` parser,
+no LID node type and no kinematic media solver exists in `src/`; the plan's
+code sketches target the legacy C sources and would be re-sited. The
+`LidLayerSpeciesData` block that is in the tree is the per-layer species state
+of the quality transport, not this design. \status{Planned}
+
+
+
+## 10.3 LID detailed output
+
+Legacy SWMM writes, for every `[LID_USAGE]` row whose ninth field names a
+file, a per-unit report at the runoff step: fourteen tab-separated columns —
+date, elapsed time, then total inflow, evaporation, surface infiltration,
+pavement percolation, soil percolation, storage exfiltration, surface runoff
+and drain outflow as rates, and surface, pavement, soil-moisture and storage
+levels — with dry spells compressed to their first and last rows. The modern
+engine parses that field, resolves it as a path, round-trips it through the
+input writer, the GeoPackage tables and the C API, and reads it nowhere: a
+model that names report files silently produces none. The only LID output
+today is the cumulative LID Performance Summary of the `.rpt`.
+
+**What the plan would report.** One twelve-variable record per unit per
+instant — the eight rates in internal ft/s, the four depths in ft, soil
+moisture dimensionless — converted once at the sink boundary, to three sinks
+selected in `[REPORT]` (@ref engine_manual_sect_REPORT): legacy-compatible
+per-unit files written by a runoff-step recorder immediately after the LID
+step, so they are byte-comparable with legacy; one consolidated tab-delimited
+file keyed by subcatchment and unit, written at the report step with rates
+averaged over the report interval and no dry-period compression; and
+GeoPackage result time series under a new `LID` object type. Two producers
+rather than one because LID advances at the runoff step and snapshots are
+built at the report step. The keys the plan proposes,
+`LID_DETAIL` (`NONE`, `UNITS`, `FILE` or `ALL`) and `LID_FILE`, are **not
+parsed by this release**.
+
+Nothing has shipped: no `LidDetailRecorder`, `LidOutputPlugin`,
+`fillLidSnapshot`, `rpt_*` retention arrays or `lid_unit_count` snapshot field
+exists in `src/`. Of the four blockers the plan's survey recorded, the one it
+made a blocking Phase 0 — LID layer parameters never unit-converted, so a
+report would print the wrong internal state — has since been fixed: the LID
+solver now converts every layer parameter out of the deck's display units at
+initialisation. The others stand as far as the tree shows: the three
+inter-layer fluxes have no retention arrays, the plan found `evap_loss` and
+`infil_loss` to mean different things in different unit types, and the cadence
+mismatch above is structural. \status{Planned}
+
+
+
+## 10.4 The non-Gardner recharge closures and the benchmarks that would promote them
+
+Chapter 9 §9.3 states the caveat and §9.11 carries it. Of the four soil laws,
+Gardner's quasi-steady recharge across the water table is Qu and Duffy's
+equation 22 verbatim, (9-3), and is verified against it. Russo, Brooks–Corey
+and van Genuchten use the engine's generalisation (9-5),
+
+\f[ q_0 = \frac{\bar K}{\sigma(L)}\,\bigl[\sigma(L) - \tilde h_u\bigr], \qquad \bar K = K\!\left(\psi = \tfrac12 L\right) \f]
+
+whose equilibrium (\f$q_0 = 0\f$ at hydrostatic storage) and sign are the
+law's own and whose *rate* — the conductivity at the column's mean suction
+over the law's equilibrium storage — is a modelling choice the code makes
+explicit rather than a published closed form. It reduces to Gardner's order and
+limits, which is the consistency it rests on, and no more. The header names
+what would license it — "Plan step 18's closure-ladder benchmark and step 4's
+HYDRUS-1D comparison" — and until those run the three laws carry
+\status{Experimental}, Gardner or Russo are preferred for anything
+quantitative, and closure B (`SIGMA`), which integrates the real Richards flux
+and needs none of this, is preferred where the answer matters. The caveat is
+confined to closure A's recharge: the σ column and the `ENSLAVED` equilibrium
+use each law's retention and conductivity directly.
+
+**The benchmarks on the record.** The explicit-kernel plan's G1/G2 track
+schedules, in order: step 4, the σ column against the Broadbridge–White exact
+Richards solution and a HYDRUS-1D single column with layer-count convergence at
+\f$m \in \{4, 8, 16\}\f$ — the in-house reference for everything after it;
+step 7, dry-down under evaporative demand against the HYDRUS reference, both
+closures; step 13, the Brooks–Corey and van Genuchten closure-A laws behind
+the earlier draft's gates, of which the finite-volume plan states the
+acceptance — van Genuchten's \f$q_0\f$ agreeing with HYDRUS-1D on a single
+column within 2 %, with the cost over Gardner measured; and step 18, the
+closure ladder, \f$\alpha L \in \{0.5, 1, 3, 5, 10\}\f$ across closures A and
+B and the Russo and Gardner laws, a publishable crossover measurement that
+confirms or adjusts the `AUTO` thresholds and sets the `C_GW` and `C_COL`
+defaults. The finite-volume plan's acceptance for the ladder is recharge
+volume over the storm, peak groundwater outflow timing and magnitude,
+wall-clock per simulated day, and the \f$L^2\f$ error against a
+one-dimensional Richards reference on a single prism.
+
+**Current state.** None of them has run. No test under `tests/` mentions
+HYDRUS or a closure ladder, and Broadbridge–White appears in the tree only as
+a comment. The kernel already seeds closure A and closure B from the same
+hydrostatic storage so that the ladder will compare trajectories rather than
+initial conditions — the harness is anticipated, not built.
+
+**What Implemented would require.** For each of the three laws, the closure-A
+recharge trajectory on a single column — wetting, drainage and dry-down under
+ET — against closure B and a HYDRUS-1D reference across the ladder's
+\f$\alpha L\f$ range, within a stated tolerance (the plan's 2 %), with the
+result recorded in the manual. Either that agreement licenses the rate as it
+stands, or a published closed form or a fitted rate constant replaces
+\f$\bar K/\sigma(L)\f$ in (9-5) and the header's warning comes out. The ladder
+as drafted measures Russo and Gardner only, so Brooks–Corey and van Genuchten
+would have to be added to it; and since the ladder's purpose in the plan is
+the `AUTO` crossover, the per-law HYDRUS comparison is the promotion gate
+proper. \status{Experimental}
+
+
+
+## 10.5 `MODE PER_SUBCATCH` for the mesh aquifer
+
+`[2D_AQUIFER_OPTIONS] MODE` (@ref engine_manual_sect_2D_AQUIFER_OPTIONS)
+accepts `MESH`, the default, and `PER_SUBCATCH`. The design of the second is
+one degenerate cell per subcatchment, no mesh sections, lateral flux zero and
+node exchange with the subcatchment's outlet node — the vehicle by which a
+pipe-only project with no mesh would get the Chapter 9 kernel (head-driven
+groundwater inflow and exfiltration through the outlet, the legacy `[GWF]`
+override winning where authored) and the vehicle the transport plan of §10.1
+keys its migration on. Its gates were step 8 of the G1 track and, at step 22,
+an overhead under 1.2× the legacy solver of
+@ref hydrology_ref_ch5_groundwater "Chapter 5".
+
+The code implements less. The token is parsed, written back and readable
+through the API; at initialisation it sets the lateral edge count to zero, so
+no Darcy faces are built and no lateral flux is booked. Everything else is the
+mesh path: the state is sized to the mesh's cell count — a deck with
+`MODE PER_SUBCATCH` and no mesh fails with "[2D_AQUIFER] authored but the
+mesh is empty" — and the cell-to-subcatchment and outlet-node mappings the
+vehicle needs, `subcatch_outlet_node_` and `cell_subcatch_`, are declared in
+the solver and neither assigned nor read anywhere in the tree. (The surface
+router has a member of the same name, populated by centroid-in-polygon for the
+`SUBCATCH_AQUIFER` infiltration destination of
+@ref hydrology_ref_ch8_mesh_surface "Chapter 8" §8.4; it is not the
+solver's.) What `PER_SUBCATCH` means today is "the mesh kernel with lateral
+flow removed" (§9.1, §9.11): usable, and not what the design says.
+\status{Experimental}
+
+
+
+## 10.6 Where the rest of the record is
+
+`ROADMAP.md` carries three of these items. §2.3 is the groundwater
+advection–dispersion model, still listed as planned scope with no status line,
+which §10.1 details; §5.2 is the spatially explicit groundwater of Chapter 9,
+whose status line still reads "no implementation yet" — the roadmap has not
+caught up with the kernel, and the two Experimental items of §10.4 and §10.5
+are what remains open in it; §6 is LID as storage nodes, §10.2 here and §10.8
+of the hydraulics reference. LID detailed output has no roadmap entry and
+lives in its plan alone. For the modeller rather than the developer, the
+application manual's "What is coming" chapter lists the same items with their
+badges and the option keys that must not be mistaken for working ones.
+
+
diff --git a/docs/manuals/reference/hydrology/sections/Chapter2-Meteorology.md b/docs/manuals/reference/hydrology/sections/Chapter2-Meteorology.md
index 48eca9925..e2eabd10a 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter2-Meteorology.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter2-Meteorology.md
@@ -246,6 +246,47 @@ The factors are stored in @ref openswmm::GageData (`scale_factor`,
 src/engine/input/handlers/CatchmentHandler.cpp, and exposed for runtime
 modification in src/engine/core/openswmm_subcatchments_impl.cpp.
 
+### 2.1.6 The Rain–Snow Split and the Snow Catch Factor
+
+Equations (2-13) and (2-14) give the rain and snow a subcatchment receives;
+this section states the decision that selects between them and the order of
+the factors, both once sources of drift between the engine's two runoff paths.
+For subcatchment \f$j\f$ served by gage \f$g\f$, at each runoff step:
+
+1. **The ignore-snowmelt guard.** If `[OPTIONS] IGNORE_SNOWMELT` is set, all
+   precipitation is rain regardless of temperature. The guard is part of the
+   split itself, not a downstream concern.
+2. **The temperature test.** Otherwise the precipitation is snow when the
+   current air temperature is at or below the rain–snow dividing temperature
+   of the `[TEMPERATURE] SNOWMELT` line (Chapter 6), and rain when it is
+   above:
+
+\f[\text{snow} \iff \neg\,\text{IGNORE\_SNOWMELT} \ \wedge\ T_a \le T_{div}\f]  (2-14a)
+
+3. **The gage snow catch factor** \f$SCF_g\f$ is applied on the snow branch
+   only; the gage-level scale factor of (2-12) is already inside \f$I_g\f$.
+4. **Conversion to internal units** (ft/s) by the rainfall unit factor.
+5. **The subcatchment scale factor** of the selected branch is applied last,
+   after the conversion, matching the legacy order (`gage_getPrecip` divides
+   by the unit factor before `getNetPrecip` applies the subcatchment factor):
+
+\f[
+P_{rain,j} = \frac{I_g}{u}\ \varphi_{R,j}\ [\text{rain}], \qquad
+P_{snow,j} = \frac{I_g\ SCF_g}{u}\ \varphi_{S,j}\ [\text{snow}]
+\f]  (2-14b)
+
+where \f$u\f$ is the unit conversion and exactly one of the two is non-zero.
+
+The split runs for **every** subcatchment, not only those with a snow pack:
+legacy calls `gage_getPrecip` unconditionally, and a pack-less subcatchment
+receives rain plus snow as its net precipitation; since the snow branch
+carries \f$SCF_g\f$, skipping the split for them diverged from legacy whenever
+the catch factor was not 1.0. Rainfall prescribed through the runtime API is
+applied *after* the split (override replaces, addition augments) and is not
+scaled by any factor. A subcatchment with no gage receives nothing.
+
+
+
 ## 2.2 Precipitation Data Sources
 
 ### 2.2.1 User-Supplied Data
@@ -772,6 +813,41 @@ then he program will keep using the temperature values that were last
 read from the file. The same convention applies whenever there is a gap
 of missing days or missing data in the file.
 
+### 2.3.1 Relative Humidity and Dew Point
+
+Relative humidity is read from the `[TEMPERATURE]` section
+(@ref engine_manual_sect_TEMPERATURE "[TEMPERATURE]") in three forms, each
+optionally preceded by `DEWPOINT`:
+
+```
+HUMIDITY            65                      ; one value, all twelve months
+HUMIDITY  MONTHLY   72 70 66 60 58 55 52 54 60 66 70 73
+HUMIDITY  TIMESERIES  RH_2024
+HUMIDITY  DEWPOINT  MONTHLY  30 31 36 42 50 58 62 61 55 45 38 32
+```
+
+A bare value fills all twelve months; `MONTHLY` gives one value per month;
+`TIMESERIES` names a series looked up at each step. Without a `HUMIDITY` line
+the humidity is 50 % in every month — the default the running state carried,
+unwritten, before this key existed. With `DEWPOINT` the values are dew-point
+temperatures in the project's temperature units (°F US, °C SI) and are
+converted to relative humidity at every step from the air temperature
+\f$T_a\f$ of §2.3:
+
+\f[RH = 100\ \frac{e_s(T_d)}{e_s(T_a)}\f]  (2-14c)
+
+with \f$e_s\f$ the saturation vapour pressure and the result clamped to
+0–100 %. A dew point above the air temperature therefore reads as 100 %.
+
+Relative humidity is consumed by the heat-transport component's surface and
+radiative exchange modules — the evaporation rate, latent flux and Bowen ratio
+of the surface-exchange evaluator and the atmospheric longwave of the
+radiative one — where it sets the air's vapour pressure. It is updated with
+air temperature and wind speed at the start of each runoff step, before the
+watershed heat balance runs. Nothing in this chapter's hydrology reads it.
+
+
+
 ## 2.4 Continuous Temperature Records
 
 When temperature data come from a climate file, a mechanism is needed to
@@ -789,7 +865,7 @@ between the maximum of the previous day and the minimum of the present,
 2) between the minimum and maximum of the present, and 3) between the
 maximum of the present and minimum of the following day.
 
-![](hydrology/media/media/image4.png "ii_01")
+![](hydrology/media/media/hydrology-image4.png "ii_01")
 
Figure 2-1 Sinusoidal interpolation of
 hourly temperatures.

diff --git a/docs/manuals/reference/hydrology/sections/Chapter3-SurfaceRunoff.md b/docs/manuals/reference/hydrology/sections/Chapter3-SurfaceRunoff.md
index 611885935..18f0f0071 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter3-SurfaceRunoff.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter3-SurfaceRunoff.md
@@ -29,7 +29,7 @@ subcatchment as a nonlinear reservoir, as sketched in Figure 3-2.
 
 ![](hydrology/media/media/Figure3-1.png "Figure 3-1")
 
-![Figure 3-2](hydrology/media/media/Figure3-2.png)
+![Figure 3-2](figures/png/hydrology_ch3_nonlinear_reservoir.png)
 
 **Figure 3-1 Idealized representation of a subcatchment.**
 
@@ -133,7 +133,7 @@ or channel). How to model indirectly connected areas, such as roof
 drains that discharge to pervious lawn areas, is discussed in section
 3.6 below.
 
-![Figure 3-3](hydrology/media/media/image8.png)
+![Figure 3-3](hydrology/media/media/hydrology-image8.png)
 
 **Figure 3-3 Types of subareas within a subcatchment.**
 
@@ -392,11 +392,11 @@ south, but the pipe connecting junctions 412 and 712 drains north! If
 only the surface contours were considered a quite different catchment
 response to rainfall would result than what actually exists.
 
-![Figure 3-6](hydrology/media/media/image10.png)
+![Figure 3-6](hydrology/media/media/hydrology-image10.jpg)
 
 **Figure 3-6 Fisk B catchment, Portland, Oregon (Portland BES, 1996).**
 
-![Figure 3-7](hydrology/media/media/image11.png)
+![Figure 3-7](hydrology/media/media/hydrology-image11.png)
 
 **Figure 3-7 Detailed view of two Fisk B subcatchments (Portland BES, 1996).**
 
@@ -583,7 +583,7 @@ length.) Note also in Figure 3-8 that for this idealized case, if the
 two sides of the subcatchment are symmetrical the total width is twice
 the length of the drainage channel.
 
-![](hydrology/media/media/Figure3-8.png "Figure 3-8")
+![](hydrology/media/media/Figure3-1.png "Figure 3-8")
 
 **Figure 3-8 Idealized representation of a subcatchment.**
 
@@ -639,7 +639,7 @@ sensitive to the time distribution of rainfall.
 
 **Parameters:** Slope = 1%, Imperviousness = 100%, Depression Storage = 0, n = 0.02, Equilibrium outflow = i*A = 0.926 cfs, *∆t* = 5 min = 300 sec, i* = Rainfall excess = 1.0 in./hr = 0.000023148 ft/sec
 
-![Figure 3-10](hydrology/media/media/image12.png)
+![Figure 3-10](hydrology/media/media/hydrology-image12.png)
 
 **Figure 3-10 Subcatchment hydrographs for different shapes of Figure 3-9.**
 
@@ -711,7 +711,7 @@ where:
 >
 > A = total area.
 
-![Figure 3-11](hydrology/media/media/image13.png)
+![Figure 3-11](hydrology/media/media/hydrology-image13.png)
 
 **Figure 3-11 Irregular subcatchment shape for width calculations (DiGiano et al., 1977, p. 165).**
 
diff --git a/docs/manuals/reference/hydrology/sections/Chapter4-Infiltration.md b/docs/manuals/reference/hydrology/sections/Chapter4-Infiltration.md
index 14997ffb5..85da29c73 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter4-Infiltration.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter4-Infiltration.md
@@ -82,7 +82,7 @@ In short, the NRCS provides an invaluable resource for information on
 soils and drainage of soils. The agency's data are ever more valuable as
 they increasingly reside on-line on the Web.
 
-![NRCS Table](hydrology/media/media/image15.png)
+![NRCS Table](hydrology/media/media/hydrology-image15.png)
 
 **Figure 4-1 Physical properties for Woodburn silt loam, Benton County, Oregon.**
 
@@ -134,7 +134,7 @@ where:
   : Thus for the case illustrated in Figure 4-2 runoff would be
   intermittent.
 
-![Horton infiltration curve](hydrology/media/media/figure4-2.png)
+![Horton infiltration curve](figures/png/hydrology_ch4_horton_curve.png)
 
 **Figure 4-2 The Horton infiltration curve**
 
@@ -159,7 +159,7 @@ before, there will in fact be times when infiltration *f* is less than
 
 \f[F(t) = \int_{0}^{t}{\min\left\lbrack f_{p},\ i \right\rbrack d\tau}\f] (4-4) 
 
-![Cumulative infiltration F as the area under the Horton curve](hydrology/media/media/figure4-3.png)
+![Cumulative infiltration F as the area under the Horton curve](figures/png/hydrology_ch4_horton_cumulative.png)
 
 **Figure 4-3 Cumulative infiltration F as the area under the Horton curve**
 
@@ -210,7 +210,7 @@ one can compute *t*w as:
 
 \f[t_{w} = t_{pr} - \frac{1}{k_{r}}\ln\left( \frac{f_{0} - f_{\infty}}{f_{0} - f_{r}} \right)\f] (4-8) 
 
-![Regeneration (recovery) of infiltration capacity during dry time steps](hydrology/media/media/figure4-4.png)
+![Regeneration (recovery) of infiltration capacity during dry time steps](figures/png/hydrology_ch4_horton_recovery.png)
 
 **Figure 4-4 Regeneration (recovery) of infiltration capacity during dry time steps**
 
@@ -746,7 +746,7 @@ F~s~* (Equation 4-29). The remainder of the curve corresponds to the
 potential rate computed with Equation 4-27. Note that the infiltration
 rate approaches *K*S (0.25 in/hr) asymptotically.
 
-![Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method](hydrology/media/media/figure4-6.png)
+![Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method](figures/png/hydrology_ch4_green_ampt_curve.png)
 
 **Figure 4-6 Illustration of infiltration capacity as function of cumulative infiltration for the Green-Ampt method**
 
@@ -849,7 +849,7 @@ functional dependence of the three internally computed recovery
 parameters *L*u, *k*r, and *T*r on the saturated hydraulic
 conductivity *K*S.
 
-![Green-Ampt recovery parameters as functions of hydraulic conductivity](hydrology/media/media/figure4-7.png)
+![Green-Ampt recovery parameters as functions of hydraulic conductivity](figures/png/hydrology_ch4_green_ampt_recovery_params.png)
 
 **Figure 4-7 Green-Ampt recovery parameters as functions of hydraulic conductivity**
 
@@ -1046,6 +1046,51 @@ table is known, or if typical depths are given for a soil on its Soil
 Survey Interpretation data, then Equation 4-39 may be solved for
 *θ*dmax.
 
+### 4.4.5 The Modified Green-Ampt Variant
+
+`[OPTIONS] INFILTRATION MODIFIED_GREEN_AMPT` (the legacy spelling; the engine
+also accepts `MOD_GREEN_AMPT`) selects a variant of §4.4 that differs from the
+original in exactly one branch of the unsaturated-surface calculation. Both
+share the saturation volume \f$F_s\f$ of (4-29), the saturated-phase solution
+(4-31)–(4-32) and the recovery routine of §4.4.2.
+
+Besides the cumulative infiltration \f$F\f$ and the upper-zone storage
+\f$F_u\f$, the engine keeps a timer \f$T\f$ — the time to drain the upper zone
+— set to \f$5400/L_u\f$ seconds whenever the intensity exceeds \f$K_s\f$ and
+counting down every step; when it has expired the soil is treated as having
+had a complete inter-event break. In the branch where rain falls but does not
+exceed \f$K_s\f$ (all of it infiltrates and the surface stays unsaturated):
+
+- **`GREEN_AMPT`** adds the step's infiltration to \f$F\f$ and \f$F_u\f$ and,
+  if \f$T\f$ has expired, recomputes the deficit from the upper-zone storage,
+  \f$\theta_d = (F_{u,max} - F_u)/L_u\f$, and **resets \f$F\f$ to zero** —
+  the wetting front's memory is discarded.
+- **`MODIFIED_GREEN_AMPT`** adds the step's infiltration to \f$F\f$ and
+  \f$F_u\f$ and nothing else; \f$F\f$ keeps accumulating.
+
+The no-rain recovery branch is shared: \f$F_u\f$ drains at \f$k_r F_{u,max}\f$
+with \f$k_r = L_u/90000\f$, the deficit is recomputed and \f$F\f$ reset once
+the timer has expired, and both reset the deficit to its maximum when
+\f$F_u\f$ reaches zero.
+
+**When to prefer it.** The difference shows on storms with a long,
+low-intensity leading period — hours of drizzle below \f$K_s\f$ before the
+main burst. Under the original the timer expires during the drizzle and
+\f$F\f$ is zeroed step after step, so the burst must infiltrate the full
+\f$F_s\f$ again before ponding: runoff starts late and infiltration is
+overstated. Under the modified variant the drizzle counts toward \f$F_s\f$ and
+runoff starts when the soil is actually full; for short intense events the two
+are identical. Prefer it for continuous simulation and for design storms with
+a leading tail — the reason SWMM 5.1 introduced it.
+
+**A note on the keyword.** Until 2026 the deck keyword `MODIFIED_GREEN_AMPT`
+was mapped to the original model, so eleven parity-corpus decks ran with
+\f$F\f$ reset between low-intensity steps. Both spellings now select the
+modified variant, carried into the kernel as the model enumerator (Chapter 8's
+per-cell infiltration selects it the same way).
+
+
+
 ## 4.5 Curve Number Method
 
 The Curve Number infiltration method is new to SWMM 5. It is based on
@@ -1395,7 +1440,7 @@ different infiltration patterns over time. These patterns are influenced
 not only by the parameters that were chosen for each method, but also by
 the temporal pattern of rainfall intensity that occurs during an event.
 
-![](hydrology/media/media/image24.png "image24")
+![](hydrology/media/media/hydrology-image24.png "image24")
 
Figure 4-8 Infiltration rates produced by
 different methods for a 2-inch rainfall event.

diff --git a/docs/manuals/reference/hydrology/sections/Chapter5-Groundwater.md b/docs/manuals/reference/hydrology/sections/Chapter5-Groundwater.md
index 318e03c93..5f9747c1b 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter5-Groundwater.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter5-Groundwater.md
@@ -70,7 +70,7 @@ two-zone configuration is similar to that used by Dawdy and O'Donnell
 pass between a subcatchment and a point in the conveyance system in an
 attenuated and delayed fashion.
 
-![Figure 5-1: Two-zone groundwater model showing upper unsaturated zone and lower saturated zone with water flow paths](hydrology/media/media/figure5-1.png)
+![Figure 5-1: Two-zone groundwater model showing upper unsaturated zone and lower saturated zone with water flow paths](figures/png/hydrology_ch5_two_zone.png)
 
 **Figure 5-1 Definitional sketch of the two-zone groundwater model.**
 
@@ -458,7 +458,7 @@ in Figure 5-2. Also note that the conveyance system node receiving
 groundwater flow need not be the same node that receives runoff from the
 subcatchment that lies above the groundwater zones.
 
-![Figure 5-2: Cross-sectional diagram showing groundwater zones and height parameters for lateral flow calculation](hydrology/media/media/figure5-2.png)
+![Figure 5-2: Cross-sectional diagram showing groundwater zones and height parameters for lateral flow calculation](figures/png/hydrology_ch5_lateral_flow_heights.png)
 
 **Figure 5-2 Heights used to compute lateral groundwater flow rate.**
 
@@ -664,7 +664,7 @@ Jensen et al., 1990; SCS, 1991). The field capacity must be greater than
 the wilting point and less than the porosity. The general relationship
 among soil moisture parameters is shown in Figure 5-3.
 
-![Soil Moisture](hydrology/media/media/image29.png)
+![Soil Moisture](hydrology/media/media/hydrology-image29.png)
 
 **Figure 5-3 Relation between soil moisture limits and soil texture class (Schroeder et al., 1994).**
 
@@ -844,7 +844,7 @@ field capacity, and porosity, respectively.
 
 ²S = weight fraction of sand, C = weight fraction of clay, OM = percent organic matter.
 
-![Soil Water Calc](hydrology/media/media/image30.png)
+![Soil Water Calc](hydrology/media/media/hydrology-image30.png)
 
 **Figure 5-4 SPAW\'s soil water characteristics calculator.**
 
@@ -884,11 +884,11 @@ Soils data of this type are becoming more readily available; for
 example, soil science departments at universities often publish such
 information (e.g., Carlisle et al., 1981).
 
-![TouchetSiltLoam.png](hydrology/media/media/image31.png)
+![TouchetSiltLoam.png](hydrology/media/media/hydrology-image31.png)
 
-![ColumbiaSandyLoam.png](hydrology/media/media/image32.png)
+![ColumbiaSandyLoam.png](hydrology/media/media/hydrology-image32.png)
 
-![](hydrology/media/media/image33.png "image33")
+![](hydrology/media/media/hydrology-image33.png "image33")
 
Figure 5-5 Measured hydraulic conductivity
 for three soils.

@@ -932,7 +932,7 @@ a series of different moisture levels *θ*. The line of best fit that
 passes through the origin has a slope of 28.864 which would be the
 estimate of HCO for this soil.
 
-![](hydrology/media/media/image34.png "image34")
+![](hydrology/media/media/hydrology-image34.png "image34")
 
Figure 5-6 Fitting SWMM's hydraulic
 conductivity equation to a power law equation.

@@ -1088,7 +1088,7 @@ however, assume this average is equivalent to the average of *h1* and
 so that \f$h_{1} = 2d_{L} - h_{2}\f$. Substituting this and \f$h_{2} = h_{SW}\f$
 into Equation 5-30 and simplifying terms results in:
 
-![](hydrology/media/media/image35.png "x_08")
+![](hydrology/media/media/hydrology-image35.png "x_08")
 
Figure 5-7 Definition sketch for
 Dupuit-Forcheimer seepage to an adjacent
@@ -1116,7 +1116,7 @@ less than or equal to *b0* in Figure 5-8 and is a function of *b
 drain diameter, and drain spacing *L*; the complicated relationship is
 given by Bear (1972, p. 412) and graphed by Bouwer (1978, p. 296).
 
-![](hydrology/media/media/image36.png "x_09")
+![](hydrology/media/media/hydrology-image36.png "x_09")
 
Figure 5-8 Definition sketch for
 Hooghoudt's method for flow to circular
diff --git a/docs/manuals/reference/hydrology/sections/Chapter6-Snowmelt.md b/docs/manuals/reference/hydrology/sections/Chapter6-Snowmelt.md
index aca51812d..1b0e4ed99 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter6-Snowmelt.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter6-Snowmelt.md
@@ -141,7 +141,7 @@ changes with time during the simulation. Melt, after routing through the
 remaining snow pack, is combined with rainfall to form the spatially
 weighted "effective rainfall" for overland flow routing.
 
-![](hydrology/media/media/image37.png "image37")
+![](hydrology/media/media/hydrology-image37.png "image37")
 
Figure 6-1 Typical gage catch deficiency
 correction (Anderson, 2006, p. 8).

@@ -475,7 +475,7 @@ where
 No special allowance is made for leap year. However, the correct date
 (and day number) is maintained.
 
-![Cmelt](hydrology/media/media/image38.png){width="5.427083333333333in"
+![Cmelt](hydrology/media/media/hydrology-image38.png){width="5.427083333333333in"
 height="2.8125in"}
 
 **Figure 6-3 Seasonal variation of melt coefficients.**
@@ -590,7 +590,7 @@ is shown in Figure 6-4. For values of the ratio *AWESI = WSNOW / SI*
 greater than *1.0*, *ASC = 1.0*, that is, the area is *100* percent snow
 covered.
 
-![](hydrology/media/media/image40.png "ii_06")
+![Figure 6-4 Typical areal depletion curve for natural area and temporary curve for new snow](figures/png/hydrology_ch6_areal_depletion_curve.png)
 
Figure 6-4 Typical areal depletion curve
 for natural area (Anderson, 1973, p. 3-15) and temporary curve for new
@@ -662,7 +662,7 @@ situation when there is new snow needs to be discussed, starting from
 both zero and non-zero initial cover. The SWMM procedure again follows
 Anderson's NWS method (1973).
 
-![](hydrology/media/media/image41.png "ii_07")
+![](hydrology/media/media/hydrology-image41.png "ii_07")
 
Figure 6-5 Effect of snow cover on areal
 depletion curves.

@@ -733,7 +733,7 @@ of water, for use in these computations. When
 *[Figure image not available in this format]*, the snow pack is fully ripe. The
 procedure is sketched in Figure 6-6.
 
-![](hydrology/media/media/image43.png "ii_08")
+![](hydrology/media/media/hydrology-image43.png "ii_08")
 
Figure 6-6 Schematic of liquid water
 routing through snow pack.

diff --git a/docs/manuals/reference/hydrology/sections/Chapter7-RDII.md b/docs/manuals/reference/hydrology/sections/Chapter7-RDII.md
index 87755c239..31cf4e5d3 100644
--- a/docs/manuals/reference/hydrology/sections/Chapter7-RDII.md
+++ b/docs/manuals/reference/hydrology/sections/Chapter7-RDII.md
@@ -173,7 +173,7 @@ event, with a separate *Qt* computed for each of the three unit
 hydrographs. These are then added together to produce the total flow per
 unit area for time period *t*.
 
-![RDII%20Hydrographs](hydrology/media/media/image49.png)
+![Figure 7-4 Use of three unit hydrographs to represent RDII](figures/png/hydrology_ch7_rtk_unit_hydrographs.png)
 
 **Figure 7-4 Use of three unit hydrographs to represent RDII (Vallabhaneni et al., 2007).**
 
@@ -277,18 +277,18 @@ activities:
     resultant hydrograph best matches the RDII flow extracted from the
     flow record (see Figure 7-7).
 
-![](hydrology/media/media/image50.png "RDII_Sewersheds")
+![](hydrology/media/media/hydrology-image50.png "RDII_Sewersheds")
 
Figure 7-5 Sewershed delineation
 (Vallabhaneni et al., 2007).

 
-![](hydrology/media/media/image51.png "RDII_Flow_History")
+![](hydrology/media/media/hydrology-image51.png "RDII_Flow_History")
 
Figure 7-6 Extracting RDII flow from a
 continuous flow monitor (Vallabhaneni et al.,
 2007).

 
-![RDII_UH_Estimate](hydrology/media/media/image52.png)
+![RDII_UH_Estimate](hydrology/media/media/hydrology-image52.png)
 
 **Figure 7-7 Fitting unit hydrographs to an RDII flow record (Vallabhaneni et al., 2007).**
 
@@ -416,7 +416,7 @@ Section 7.2.
 
-![Figure 7-11](figure7-11-schematic.png)
+![Figure 7-11](figures/png/hydrology_ch7_ia_seasonal.png)
 
 *Figure 7-11 Emergent seasonal behavior of the exponential-decay initial
 abstraction model (schematic, synthetic forcing): available initial
diff --git a/docs/manuals/reference/hydrology/sections/Chapter8-MeshSurfaceProcesses.md b/docs/manuals/reference/hydrology/sections/Chapter8-MeshSurfaceProcesses.md
new file mode 100644
index 000000000..6a00b5c76
--- /dev/null
+++ b/docs/manuals/reference/hydrology/sections/Chapter8-MeshSurfaceProcesses.md
@@ -0,0 +1,464 @@
+@page hydrology_ref_ch8_mesh_surface Chapter 8: Distributed Surface Processes on the 2D Mesh
+
+@tableofcontents
+
+## 8.1 Scope
+
+Chapters 2 through 7 describe hydrology on a **lumped** land surface: each
+subcatchment receives one rainfall intensity from one gage, converts it to
+runoff through one infiltration model and one nonlinear reservoir, and delivers
+the result to one outlet. Everything that happens between the rain and the
+outlet is integrated over the subcatchment's area before the conveyance system
+sees it.
+
+The two-dimensional overland-flow mesh of
+@ref hydraulics_ref_ch9_two_dimensional "Hydraulics Chapter 9" offers a second,
+**distributed** representation of the same surface. Rain can be applied to every
+cell of the mesh, each cell can infiltrate through its own soil parameters, and
+each cell evaporates from its own water. Runoff is then not a subcatchment
+quantity at all: it is the depth field the shallow-water solver routes over the
+terrain, and it enters the network wherever the terrain and the coupling points
+put it. This chapter documents those three cell-level processes — rainfall,
+infiltration and evaporation — and how they are accounted for. The mesh's own
+subsurface, which can receive the infiltrated water, is
+@ref hydrology_ref_ch9_mesh_groundwater "Chapter 9".
+
+
+![Figure 8-1](figures/png/hydrology_ch8_cell_budget.png)
+
+*Figure 8-1 The water balance of one mesh cell: rainfall, evaporation, infiltration, network exchange and the lateral face fluxes*
+
+**When rain on the mesh replaces subcatchment runoff.** Water reaches the mesh
+by four routes — rainfall on the cells, spill from surcharged nodes, outfall
+discharge and boundary inflow — and only the first is hydrology in the sense
+of this manual. It is on by default: a project with a mesh and rain gages rains
+on the mesh unless told not to. Three configurations are intended. In
+**rain-on-grid** the mesh covers the catchment with no subcatchments over it;
+every cell receives rain, infiltrates (§8.3) and drains to the network across
+the terrain, and the subcatchment machinery of Chapters 3 and 4 is not
+involved. In a **network-fed surface** the subcatchments convert the storm as
+before and the mesh only routes what the network cannot hold;
+`[2D_OPTIONS] RAINFALL_MODE NONE` keeps rain off it. A **hybrid** has
+subcatchments over part of the terrain and rain on the mesh elsewhere.
+
+**The double-counting rule.** Where a subcatchment polygon and rained-on mesh
+cells cover the same ground, the same storm is delivered twice — as runoff at
+the outlet node and as depth on the cells — and the outfall volume is wrong by
+exactly the overlap. The engine does not detect this for rainfall:
+`RAINFALL_MODE` is the modeller's statement of which representation owns the
+surface, and `NONE` is a modelling decision, not an optimisation. The one
+check is in the surface-quality resolver, which warns when a `[2D_COVERAGES]`
+cell lies inside a subcatchment carrying its own `[COVERAGES]`. A related
+consequence: because the mesh reads every gage, a gage no subcatchment names
+is now *used* and its state machine advances, where the legacy rule held its
+first record for the whole run.
+
+
+
+## 8.2 Rainfall interpolation
+
+### 8.2.1 Modes
+
+`[2D_OPTIONS] RAINFALL_MODE` selects how the project's gages map onto the cells:
+
+| Mode | Cell value |
+|---|---|
+| `NATURAL_NEIGHBOUR` (default) | Spatial interpolation of the located gages onto each cell centroid: Laplace natural-neighbour weights inside the convex hull of the gages, inverse-distance weights outside it |
+| `NEAREST_NEIGHBOUR` (alias `NEAREST_NEIGHBOR`) | The reading of the single closest located gage, inside or outside the hull; an exact distance tie goes to the gage listed first. A dry closest gage keeps the cell dry |
+| `SYSTEM` | One uniform value, the arithmetic mean of every gage's current intensity |
+| `NONE` | No rain on the mesh |
+
+A gage is **located** when it has a `[SYMBOLS]` coordinate; a coordinate of
+exactly (0, 0) marks it un-located and excludes it. Only the first of two
+coincident gages is kept, since the triangulation would otherwise degenerate.
+With no located gage at all, `NATURAL_NEIGHBOUR` and `NEAREST_NEIGHBOUR` fall
+back to the `SYSTEM` mean. Initialisation reports, as warnings, the number of
+un-located, non-finite and duplicate gages it skipped, the `SYSTEM` fallback,
+and the number of cells that received inverse-distance weights. The
+environment variable `OPENSWMM_2D_RAINFALL_MODE` (`natural`, `nearest`,
+`system`, `none`) overrides the deck key at initialisation.
+
+### 8.2.2 The weights
+
+Gage positions do not change during a run, so the interpolation is split into
+a one-time construction of per-cell weights and a per-step sparse weighted sum.
+For cell \f$i\f$ with weights \f$w_{ig}\f$ over the located gages \f$g\f$, the
+cell rainfall is
+
+\f[ r_i = \sum_{g} w_{ig}\, R_g, \qquad \sum_{g} w_{ig} = 1 \f]  (8-1)
+
+where \f$R_g\f$ is gage \f$g\f$'s current intensity converted to m/s. Because
+the conversion is linear, converting then interpolating equals interpolating
+then converting.
+
+**Inside the hull — Laplace (non-Sibsonian) natural-neighbour weights.** The
+Delaunay triangulation of the gage sites is built by a self-contained
+Bowyer–Watson insertion (gage counts are small, typically under thirty, so no
+geometry library is involved). A cell centroid \f$p\f$ is inside the hull when
+it lies in some Delaunay triangle. Inserting \f$p\f$ as a new site carves a
+cavity — the triangles whose circumcircles contain \f$p\f$ — and fans it with
+triangles \f$(p, u, v)\f$ over the cavity's boundary edges. The Voronoi facet
+between \f$p\f$ and a boundary site \f$s\f$ runs between the circumcentres of
+the two fan triangles incident to \f$s\f$, and the Laplace weight is that
+facet's length divided by the distance to the site:
+
+\f[
+w_{ps} = \frac{\ell_{ps}}{\lvert p - x_s \rvert}, \qquad
+\ell_{ps} = \bigl\lvert c(p, s_{\mathrm{prev}}, s) - c(p, s, s_{\mathrm{next}}) \bigr\rvert
+\f]
+(8-2)
+
+with \f$c(\cdot)\f$ the circumcentre and the weights normalised to sum to one.
+Laplace weights reproduce a linear field exactly inside the hull and need no
+polygon-area integration, which distinguishes them from Sibson's weights. A
+centroid coincident with a gage takes that gage alone.
+
+
+![Figure 8-2](figures/png/hydrology_ch8_nn_weights.png)
+
+*Figure 8-2 Natural-neighbour rainfall weights inside the gage hull, and inverse-distance weighting outside it*
+
+**Outside the hull — inverse-distance weights.** A centroid outside every
+Delaunay triangle, or one whose fan construction degenerates (a collinear fan
+triangle), takes power-2 inverse-distance weights over all located gages:
+
+\f[ w_{pg} = \frac{1 / d_{pg}^{2}}{\sum_{g'} 1 / d_{pg'}^{2}}, \qquad d_{pg} = \lvert p - x_g \rvert \f]  (8-3)
+
+IDW never leaves the range of the gage readings, tends to the nearest gage as
+the cell approaches it, and to the plain mean far from every gage.
+
+**Degenerate site sets.** One located gage gives that gage everywhere; two,
+or three or more all collinear (an empty triangulation), give IDW everywhere;
+three or more non-collinear gages give Laplace inside the hull and IDW outside.
+Gage coordinates are in project map units and the centroids in SI metres, so
+the same feet-to-metres factor the mesh received is applied to the gage
+coordinates before triangulation.
+
+### 8.2.3 Cadence
+
+Rainfall on the cells is refreshed with the other forcings on the co-advance
+cadence: at the first step, whenever a forcing prescription changes, and
+otherwise every 30 s of simulated time. Between refreshes each cell's intensity
+is held. Per-cell rainfall forcing through the API then overrides
+(`OVERRIDE`) or augments (`ADD`) the interpolated value.
+
+### 8.2.4 A three-gage example in words
+
+Take three gages A, B and C at the corners of a triangle covering most of a
+mesh, reading 10, 20 and 30 mm/hr; the hull is that triangle.
+
+- A cell at the centroid receives 20 mm/hr. More generally, because Laplace
+  weights reproduce linear fields and three readings define a unique plane,
+  *every* cell inside the triangle receives that plane's value at its
+  centroid — with three gages the interpolation is exactly linear.
+- A cell inside the triangle near gage A has a weight near one on A; its value
+  approaches 10 mm/hr and equals it if the centroid coincides with the gage.
+- A cell outside the triangle beyond A is an IDW cell: bounded between 10 and
+  30 mm/hr, dominated by A nearby, tending to the mean of 20 mm/hr far away.
+- If gage C had no `[SYMBOLS]` coordinate it would be excluded; the remaining
+  pair is collinear, every cell becomes an IDW cell over A and B, and C's
+  reading never reaches the mesh (it still drives any subcatchment naming it).
+- Under `SYSTEM` every cell receives 20 mm/hr; under `NONE`, nothing.
+
+
+
+## 8.3 Per-cell infiltration
+
+### 8.3.1 A held rate on its own cadence
+
+Infiltration on the mesh is a **held rate**, not a quantity evaluated inside the
+marcher. Every `INFIL_STEP` seconds the hydrology kernels of
+@ref hydrology_ref_ch4_infiltration "Chapter 4" are advanced once for every
+cell that carries a model, and the resulting capacity is published as a
+per-cell rate \f$f_i\f$ (m/s) that the shallow-water substeps consume unchanged
+until the next evaluation. Evaluating the kernels per substep would be a
+different model — the Chapter 4 kernels are written for the runoff step — and
+would drag infiltration into the local-time-stepping tiers.
+
+The cadence resolves as `[2D_OPTIONS] INFIL_STEP`, else
+`[2D_INFILTRATION_OPTIONS] INFIL_STEP` (the older home of the same value),
+else the project's `WET_STEP`. At initialisation the kernels are advanced once
+so the very first substep infiltrates rather than running a whole cadence dry;
+thereafter they receive the true elapsed interval. Kernel state is advanced for
+**every** model-carrying cell, including cells the marcher has deactivated as
+dry: a cell that sat inactive through a dry spell must not present its full
+initial capacity when rain arrives — its Horton capacity should have
+recovered and its Green-Ampt upper zone drained, as a subcatchment's would.
+
+### 8.3.2 The six methods
+
+The cell-level methods are the Chapter 4 kernels, called through the same
+functions the runoff module calls and therefore bit-for-bit the same
+arithmetic:
+
+| Method token | Kernel | Positional parameters (project units) |
+|---|---|---|
+| `HORTON` | `horton_getInfil` (§4.2) | f0, fmin, decay (1/hr), dry time (d), Fmax |
+| `MODIFIED_HORTON` | `modHorton_getInfil` (§4.3) | f0, fmin, decay (1/hr), dry time (d), Fmax |
+| `GREEN_AMPT` | `grnampt_getInfil` (§4.4) | suction S, Ks, IMD |
+| `MODIFIED_GREEN_AMPT` | `grnampt_getInfil` with the modified flag (§4.4.5) | suction S, Ks, IMD |
+| `CURVE_NUMBER` | `curvenum_getInfil` (§4.5) | CN, (unused), dry time (d) |
+| `CONSTANT` | `constant_getInfil` | rate |
+
+Rates (f0, fmin, Ks, rate) are in in/hr or mm/hr and depths (S, Fmax) in inches
+or mm, matching what a user types in `[INFILTRATION]`; the `*_init` functions
+convert them exactly as the runoff module does. `CONSTANT` is stored as a
+degenerate Horton state with \f$f_0 = f_{min}\f$ and no decay, which gives it
+the same unit conversion for free. The curve-number row keeps the legacy
+column layout, so its drying time is the third value and the second is
+ignored.
+
+The kernels work in feet and ft/s for every project; the 2D solver is SI. All
+conversion happens at the call boundary: the cell's rainfall and depth go in as
+feet, and the returned rate is scaled by 0.3048 and floored at zero:
+
+\f[ f_i = \max\bigl(0,\; 0.3048\, f_{\mathrm{kernel}}(3.2808\, r_i,\; 3.2808\, h_i,\; \Delta t_{infil})\bigr) \f]  (8-4)
+
+A mesh cell has no run-on from a neighbouring subarea, so the ponded depth is
+passed to the curve-number kernel unchanged where the runoff module would fold
+inter-subarea run-on into it.
+
+### 8.3.3 Parameter resolution
+
+Parameters resolve once, at initialisation, in the order
+
+\f[
+\text{cell override} \;>\; \text{TAG row} \;>\; \text{`*' row} \;>\; \text{none}
+\f]
+
+from three sections: `[2D_INFILTRATION_DEFAULTS]` (`TAG METHOD [P1..P5] [DEST]`,
+where the tag `*` is the mesh-wide fallback and may appear anywhere),
+`[2D_INFILTRATION]` (`CELL METHOD [P1..P5] [DEST]`, cells 1-based in the file)
+and `[2D_INFILTRATION_OPTIONS]` (`INFIL_STEP`). A TAG or CELL row whose method
+is `NONE` deliberately clears the `*` default for its cells. A `-` in a
+parameter column leaves that parameter unset. The solver never consults tags;
+the provenance of each cell's parameters is retained only so the writer can
+re-emit a compact file rather than one row per cell.
+
+Three `[2D_OPTIONS]` keys sit above the sections. `INFILTRATION YES|NO|AUTO`
+is the process enable: `AUTO` (unset) runs infiltration when any row resolved,
+`NO` keeps the rows but deactivates them for the run (with a warning), and
+`YES` with nothing resolved warns that no cell infiltrates.
+`INFIL_DEFAULT_METHOD` names the method of the `*` row and must agree with it,
+since the parameters belong to the row: a mismatch is an error, a missing row
+a warning, and `NONE` drops the `*` row. `INFIL_DESTINATION` is §8.4.
+Validation refuses negative Horton rates, negative Ks, an IMD outside 0..1, a
+curve number outside 1..100, a negative constant rate, and a cell index beyond
+the mesh.
+
+### 8.3.4 The sink in the cell budget
+
+The marcher consumes the held rate through a depth-limited sink. For a cell of
+depth \f$h_i\f$ and the solver's `DRY_DEPTH` \f$h_d\f$,
+
+\f[
+f^{\ast}_i =
+\begin{cases}
+0 & h_i \le 0 \\
+f_i\, t^{2}(3 - 2t), \quad t = h_i / h_d & 0 < h_i < h_d \\
+f_i & h_i \ge h_d
+\end{cases}
+\f]
+(8-5)
+
+The cubic Hermite ramp is the same one the evaporation sink uses, so both
+sinks shut off together as a cell dries. The cell's volume update in every
+tier is then
+
+\f[
+V_i \leftarrow \max\Bigl(0,\; V_i + \Delta t\, A_i\,\bigl(r_i + s_i + g_i - e^{\ast}_i - f^{\ast}_i\bigr) + \sum_{\text{faces}} \Delta V\Bigr)
+\f]
+(8-6)
+
+with \f$s_i\f$ the held coupling flux, \f$g_i\f$ the aquifer's return (Chapter
+9, zero without an aquifer) and \f$e^{\ast}_i\f$ the ramped evaporation. The
+plan states the sink order as rainfall, then evaporation, then infiltration
+"against the remaining depth"; in the code both sinks are evaluated from the
+same start-of-substep depth and summed, and the floor at zero in (8-6) is what
+keeps a cell non-negative. The two agree in effect, since both ramps vanish
+together, and a project with no infiltration rows is bitwise unchanged. The
+applied depth \f$f^{\ast}_i \Delta t\f$ is accumulated per cell as it is
+removed, in active and lazy tiers alike and before any early exit (rain exactly
+cancelling the sink still infiltrated); that accumulator, not a re-derivation
+from the end-of-step depth, is what the ledger and the cumulative output read.
+
+
+![Figure 8-3](figures/png/hydrology_ch8_infiltration_strip.png)
+
+*Figure 8-3 Per-cell infiltration: how a cell resolves its method and parameters, and the rate held across an infiltration step*
+
+
+
+## 8.4 Infiltration destination
+
+Where infiltrated water goes is a per-row `DEST` column, defaulted for rows
+that do not spell one by `[2D_OPTIONS] INFIL_DESTINATION`:
+
+| Destination | Meaning |
+|---|---|
+| `LOST` (default) | Leaves the modelled system; booked as the 2D surface ledger's infiltration loss |
+| `SUBCATCH_AQUIFER` | Recharges the legacy per-subcatchment aquifer of @ref hydrology_ref_ch5_groundwater "Chapter 5" that contains the cell |
+| `AQUIFER_2D` | Recharges the two-zone mesh aquifer of Chapter 9 |
+
+The writer emits `DEST` only for rows that spelled it, so a deck round-trips
+unchanged.
+
+**`AQUIFER_2D`** is legal exactly when a `[2D_AQUIFER]` section resolved.
+Without one it is refused with a message naming the section to add, rather
+than read as `LOST`: silently draining a model the author believed was
+recharging is the worse failure.
+
+**`SUBCATCH_AQUIFER`** resolves each routed cell to the subcatchment whose
+`[Polygons]` contain its centroid (ray-crossing test in map units); the first
+by index wins, an overlap is reported once, and cells outside every polygon
+stay `LOST` with a warning. The marcher does not deliver the recharge: the
+applied depth is accumulated per subcatchment on the once-per-routing-step
+ledger pass, and the runoff step drains the accumulator, converts it to a rate
+over the full subcatchment area and adds it to that subcatchment's
+infiltration rate before the groundwater solver runs. It is booked to the 1D
+groundwater ledger and to the 2D ledger's "to Aquifer (delivered)" row at the
+moment of delivery, so the two ledgers sum the same volumes; the applied but
+not yet drained remainder is the "in flight" row. Because a subcatchment's
+aquifer has one owner, the destination is refused alongside the registered
+`org.hydrocouple.openswmm.integrated2d` component or a `[2D_AQUIFER]`.
+
+**The aquifer owns infiltration.** With a `[2D_AQUIFER]` present, *every*
+infiltrating cell's water is booked to the cell's aquifer column — in the
+active tier and in the lazy tier alike — whatever its `DEST` token says.
+`LOST` then reads as `AQUIFER_2D`. That is what a user means by putting an
+aquifer under the mesh, and it keeps the water to one owner. The 2D surface
+ledger still prints the volume as "Infiltration Loss", since it left the
+surface; the same volume appears as "Infiltration Inflow" in the aquifer's own
+block (Chapter 9 §9.10).
+
+
+
+## 8.5 Evaporation on the mesh
+
+`[2D_OPTIONS] EVAPORATION NO|YES|CLIMATE` sets the base rate every cell
+evaporates at:
+
+| Value | Base rate on an unforced cell |
+|---|---|
+| `YES` (default) | Zero. Only per-cell forcing through the API (`swmm_2d_force_evap*`) evaporates — the behaviour before the key existed |
+| `CLIMATE` | The project's `[EVAPORATION]` rate, converted from the internal ft/s to m/s |
+| `NO` | Zero, and forcing is ignored |
+
+This differs from the subcatchments and is worth stating plainly: a mesh with
+the default setting and no forcing **does not evaporate**, whatever
+`[EVAPORATION]` says; `CLIMATE` makes it follow the project's climate. Per-cell
+forcing replaces (`OVERRIDE`) or adds to (`ADD`) the base rate, on the same
+30 s refresh cadence as rainfall.
+
+The rate reaches the cell budget through the same depth-limited ramp as
+infiltration, (8-5) with \f$e_i\f$ in place of \f$f_i\f$, so a drying cell
+cannot evaporate more water than it has. Evaporation removes water and no
+solute: when species are transported on the mesh, both intensive rows are
+sunk at the cell's own mean so that concentrations rise, which is the
+up-concentration a drying pond should show.
+
+
+
+## 8.6 Mass balance terms and reporting
+
+### 8.6.1 The 2D Surface Routing Continuity block
+
+The 2D domain keeps its own ledger in SI cubic metres, printed as a separate
+block after the flow-routing continuity when `[REPORT] CONTINUITY` is on. Its
+rows and how each is accumulated:
+
+| Row | Accumulation |
+|---|---|
+| Initial Stored Volume | Surface volume at the start |
+| Rainfall Inflow | \f$\sum_i r_i A_i\, \Delta t\f$ per routing step, from the per-cell rate after forcing |
+| 1D to 2D Spill Inflow, 2D to 1D Drain Outflow | Signed junction exchange, per node per batch |
+| Outfall Inflow, Outfall Withdrawal | Signed outfall exchange |
+| Boundary Inflow, Boundary Outflow | Non-wall boundary edges, outward-positive |
+| Evaporation Loss | \f$\sum_i e^{\ast}_i A_i\, \Delta t\f$ re-derived at the accepted end-of-step depth (exact while cells stay wetter than `DRY_DEPTH`, first-order through dry-out) |
+| Infiltration Loss | The applied depth the marcher actually removed, summed as it was removed — not a re-derivation |
+| to Aquifer (delivered), to Aquifer (in flight) | The `SUBCATCH_AQUIFER` share; printed only when non-zero |
+| Final Stored Volume | Surface volume at the end |
+
+The infiltration row is deliberately not re-derived from end-of-step state:
+re-deriving (8-5) at the accepted depth is first-order and under-books on
+exactly the cells that matter — a cell drying mid-step is sunk at the higher
+early-step rate, and the lazy tier integrates a stale depth across a whole
+sync interval. On the rain-on-grid gate that left 0.0117 m³ of a 3.775 m³
+budget unaccounted.
+
+The continuity error is
+
+\f[
+\varepsilon_{2D} = \frac{V_{in} - V_{out}}{V_{in}}, \qquad
+V_{in} = V_0 + R + S_{1D\to2D} + O_{in} + B_{in} + G_{in}, \quad
+V_{out} = V_1 + S_{2D\to1D} + O_{out} + B_{out} + E + F
+\f]
+(8-7)
+
+with \f$G_{in}\f$ the water a Chapter 9 aquifer returned to the surface
+(Dunne excess and top-layer rejection, less what is still waiting to be picked
+up). \f$G_{in}\f$ enters the error but is not printed as a row of the block in
+this release.
+
+### 8.6.2 Results-file output
+
+Two `REPORT_2D_VARIABLES` groups, both in `DEFAULT`, carry the per-cell series:
+
+| Group | Datasets | Content |
+|---|---|---|
+| `RAINFALL` | `Mesh2_face_rainfall`, `Mesh2_face_rain_cum` | Per-cell rate after forcing (m/s) and cumulative depth |
+| `INFILTRATION` | `Mesh2_face_infil_rate`, `Mesh2_face_infil_cum` | The held rate (m/s) and the ledger-consistent applied cumulative depth (m) |
+
+The cumulative series is `SurfaceRouter2D::infilCumulative()`, which drains
+the same applied-depth accumulator the ledger books, so
+\f$\sum_i \mathrm{infil\_cum}_i A_i\f$ equals the Infiltration Loss row by
+construction; `Infil2D::cumulative()`, the integral of the unramped capacity
+the kernels offered, is a kernel-side diagnostic that exceeds the applied loss
+on drying cells. The C API's `*_get_cum_bulk` reports the former.
+
+
+
+## 8.7 Alternatives
+
+| Family | Alternative | Behaviour | Status |
+|---|---|---|---|
+| Rain mode | `NATURAL_NEIGHBOUR` | Laplace weights inside the gage hull, IDW outside; static weights | \status{Implemented} |
+| Rain mode | `NEAREST_NEIGHBOUR` | Closest located gage, weight 1; first-listed gage wins a tie; static weights | \status{Implemented} |
+| Rain mode | `SYSTEM` | Uniform mean of all gages; automatic fallback with no located gage | \status{Implemented} |
+| Rain mode | `NONE` | No rain on the mesh; the subcatchments own the surface | \status{Implemented} |
+| Infiltration | `HORTON` | Chapter 4 §4.2 kernel, per cell | \status{Implemented} |
+| Infiltration | `MODIFIED_HORTON` | Chapter 4 §4.3 kernel, per cell | \status{Implemented} |
+| Infiltration | `GREEN_AMPT` | Chapter 4 §4.4 kernel, per cell | \status{Implemented} |
+| Infiltration | `MODIFIED_GREEN_AMPT` | Chapter 4 §4.4.5 variant, per cell | \status{Implemented} |
+| Infiltration | `CURVE_NUMBER` | Chapter 4 §4.5 kernel, per cell, no run-on | \status{Implemented} |
+| Infiltration | `CONSTANT` | Fixed rate, stored as a degenerate Horton state | \status{Implemented} |
+| Destination | `LOST` | Exit from the modelled system | \status{Implemented} |
+| Destination | `SUBCATCH_AQUIFER` | Delivered to the containing subcatchment's Chapter 5 aquifer at the runoff step | \status{Implemented} |
+| Destination | `AQUIFER_2D` | Delivered to the Chapter 9 mesh aquifer; owns all infiltration when present | \status{Implemented} |
+| Destination | Exfiltration (negative rate) from the ground to the mesh | Not a destination; the sink floors at zero. Return flow arrives through the Chapter 9 aquifer instead | \status{Retired} |
+| Evaporation | `YES` | Forcing only | \status{Implemented} |
+| Evaporation | `CLIMATE` | Project `[EVAPORATION]` rate on unforced cells | \status{Implemented} |
+| Evaporation | `NO` | No sink, forcing ignored | \status{Implemented} |
+
+
+
+## 8.8 Implementation
+
+| Concern | Where |
+|---|---|
+| Rainfall weights and application | `src/engine/2d/mesh/RainfallInterpolator.hpp`, `.cpp` — `build()` once from `SurfaceRouter2D::initialize()`, `apply()` from `SurfaceRouter2D::updateRainfall()` |
+| Rain mode, process enables, evaporation mode | `src/engine/2d/data/SolverOptions2D.hpp` (`RainfallMode`, `infiltration`, `infil_step`, `infil_default_method`, `infil_destination`, `evaporation`); parsed in `src/engine/2d/input/SectionHandlers2D.cpp` |
+| Per-cell infiltration state and kernels | `src/engine/2d/infil/Infil2D.hpp`, `.cpp` — `resolve()` at initialise, `updateRates()` on the cadence from `SurfaceRouter2D::coAdvanceStep()`; kernels in `src/engine/hydrology/Infiltration.hpp` |
+| Section grammar | `[2D_INFILTRATION_OPTIONS]`, `[2D_INFILTRATION_DEFAULTS]`, `[2D_INFILTRATION]` in `SectionHandlers2D.cpp`; documented in @ref engine_manual_sect_2D_INFILTRATION_OPTIONS "[2D_INFILTRATION_OPTIONS]", @ref engine_manual_sect_2D_INFILTRATION_DEFAULTS "[2D_INFILTRATION_DEFAULTS]" and @ref engine_manual_sect_2D_INFILTRATION "[2D_INFILTRATION]"; the `[2D_OPTIONS]` keys in @ref engine_manual_sect_2D_OPTIONS "[2D_OPTIONS]", all in @ref engine_manual_ch2_input_file "the input-file chapter" |
+| The sinks in the cell budget | `src/engine/2d/solver/SurfaceFluxCalculator.hpp` (`evapSink`, `infilSink`); consumed in `src/engine/2d/solver/ExplicitInertialSolver.cpp` (`lazySourcesOnly`, `syncAndRebuild`, `fireCellsImpl`) |
+| Destination routing | `SurfaceRouter2D::initialize()` (validation, cell-to-subcatchment map), `accumulateMassBalance()` (per-subcatchment accumulation), `src/engine/core/SWMMEngine.cpp` runoff step (delivery); the marcher books to the Chapter 9 kernel directly |
+| Ledger and report | `SimulationContext::MassBalance2D`; `src/engine/plugins/DefaultReportPlugin.cpp` (2D Surface Routing Continuity) |
+| Results file | `src/engine/2d/output/Default2DOutputPlugin.cpp` (`Mesh2_face_rainfall`, `_rain_cum`, `_infil_rate`, `_infil_cum`); group masks in `src/engine/2d/data/Report2DVars.hpp` |
+
+The design record is `plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md`
+§5.5 (decisions D-I1 to D-I6). Two of its statements are superseded and this
+chapter follows the code: D-I4's "`LOST` is the only destination accepted" was
+amended when `SUBCATCH_AQUIFER` and `AQUIFER_2D` landed (§8.4), and the
+sequential sink ordering is realised as the summed, floored update (8-6).
+
+
diff --git a/docs/manuals/reference/hydrology/sections/Chapter9-MeshGroundwater.md b/docs/manuals/reference/hydrology/sections/Chapter9-MeshGroundwater.md
new file mode 100644
index 000000000..aacb82f57
--- /dev/null
+++ b/docs/manuals/reference/hydrology/sections/Chapter9-MeshGroundwater.md
@@ -0,0 +1,710 @@
+@page hydrology_ref_ch9_mesh_groundwater Chapter 9: Spatially Explicit Groundwater on the 2D Mesh
+
+@tableofcontents
+
+## 9.1 Motivation and relation to Chapter 5
+
+The two-zone aquifer of @ref hydrology_ref_ch5_groundwater "Chapter 5" is
+integrated per subcatchment: one unsaturated moisture content and one
+water-table depth each, lateral outflow by the empirical power function of
+§5.3.5, no communication between neighbouring aquifers, and one feedback to
+the rest of the engine — the end-of-step infiltration cap. Four physically
+real processes are therefore not representable in it:
+
+1. **Saturation-excess (Dunne) overland flow** where the water table reaches
+   the ground, with rainfall rejected there.
+2. **Return flow** — water that travelled laterally through the saturated zone
+   and re-emerges downslope with no rain falling.
+3. **Head-driven exchange between the aquifer and the pipes** — the mechanism
+   behind groundwater inflow and sewer exfiltration, derived from heads rather
+   than fitted per pipe.
+4. **True capillary rise** meeting evaporative demand from below.
+
+This chapter documents the opt-in kernel that supplies them: a vertically
+integrated two-zone subsurface on the cells of the 2D mesh of
+@ref hydraulics_ref_ch9_two_dimensional "Hydraulics Chapter 9", following the
+semi-discrete finite-volume formulation of Qu and Duffy (2007). Each cell
+carries a saturated thickness and an unsaturated store joined at a moving water
+table; neighbouring saturated zones exchange by Darcy's law across the mesh's
+own edges; nodes on the mesh exchange with the aquifer beneath them by a
+conductance; and water a saturated column cannot hold returns to the surface
+cell above it, where the shallow-water solver routes it.
+
+**It is opt-in and changes nothing else.** The kernel runs only when a
+`[2D_AQUIFER]` section is authored (or `[2D_OPTIONS] GROUNDWATER YES` says
+so); every deck without one is unchanged and the Chapter 5 aquifers keep their
+own path. The two cannot own the same water: a cell whose infiltration is
+routed to a subcatchment aquifer (Chapter 8 §8.4) cannot coexist with a
+`[2D_AQUIFER]`, and a storage node with a bed on the mesh has its `[STORAGE]`
+exfiltration replaced by the node exchange of §9.6.
+
+**`MODE PER_SUBCATCH`.** The design intends a second vehicle for the same
+kernel — one degenerate cell per subcatchment, no lateral flux, exchange with
+the outlet node. The code implements less: the token is parsed, written, and
+removes the lateral edge topology, but the kernel still runs on the mesh cells
+(the per-subcatchment cell list and outlet mapping are declared and never
+populated). Today it means "the mesh kernel without lateral flow" (§9.11).
+
+
+
+## 9.2 State variables and geometry
+
+Everything in the kernel is SI; the authored `[2D_AQUIFER]` rows stay in the
+project's units and are converted once, into the per-cell state (§9.12).
+
+
+![Figure 9-1](figures/png/hydrology_ch9_two_layer_column.png)
+
+*Figure 9-1 One aquifer column and its fluxes, with the unsaturated zone held as a bulk store (closure A) and as sigma layers (closure B)*
+
+Per cell \f$i\f$ of planimetric area \f$A_i\f$ and bed elevation \f$z_{c,i}\f$:
+
+| Symbol | Meaning | Source |
+|---|---|---|
+| \f$z_s\f$ | Soil column thickness, bottom to surface (m) | `ZS` |
+| \f$z_{bed} = z_c - z_s\f$ | Aquifer bottom elevation (m) | derived |
+| \f$h_g \in [0, z_s]\f$ | Saturated thickness above the bottom (m); the saturated state | `HG0` seeds it; default 0 |
+| \f$L = z_s - h_g\f$ | Unsaturated column thickness (m) | derived |
+| \f$H = z_{bed} + h_g\f$ | Water-table elevation, the head for lateral flow and node exchange (m) | derived |
+| \f$h_u\f$ | Closure A: bulk unsaturated storage as an equivalent depth of water (m) | seeded hydrostatic |
+| \f$\theta_j,\ j = 0..m-1\f$ | Closure B: water content of σ layer \f$j\f$, layer 0 at the surface | seeded hydrostatic |
+| \f$K_s, \theta_s, \theta_r, \alpha, \psi_b, \lambda, n, L_M, c_{loss}\f$ | Soil parameters (§9.3, §9.5) | row columns and keywords |
+
+Water in the cell — the continuity ledger's storage term (§9.10) — is
+
+\f[
+W_i = \bigl(\theta_s\, h_g + S_{col}\bigr)\, A_i, \qquad
+S_{col} = \begin{cases} h_u & \text{closures A and ENSLAVED} \\ \sum_j \theta_j\, L\, \Delta\sigma & \text{closure B} \end{cases}
+\f]
+(9-1)
+
+Rows resolve onto cells by scope, `*` then `TAG` then `CELL`, and by authored
+order within a scope; a residual content at or above the porosity is clamped
+to half the porosity with a warning. The closure-B layer count \f$m\f$ is
+global (`M_LAYERS`, default 8, range 2..128; a per-row value is parsed but
+unused).
+
+
+
+## 9.3 Soil characteristics
+
+Four laws are selectable, globally through `[2D_AQUIFER_OPTIONS] SOIL_CHAR` or
+per row. Each supplies an effective saturation \f$S_e(\psi)\f$, a water
+content \f$\theta(\psi) = \theta_r + S_e(\theta_s - \theta_r)\f$ and a
+relative conductivity \f$K_r(\psi)\f$, with suction \f$\psi \ge 0\f$ measured
+upward from the water table (\f$\psi = L\f$ at the surface) and
+\f$K(\psi) = K_s K_r(\psi)\f$:
+
+| Law | \f$S_e(\psi)\f$ | \f$K_r(\psi)\f$ | Beyond \f$K_s, \theta_s, \theta_r\f$ |
+|---|---|---|---|
+| `GARDNER` (1958) | \f$e^{-\alpha\psi}\f$ | \f$e^{-\alpha\psi}\f$ | \f$\alpha\f$ |
+| `RUSSO` (1988), default | \f$\bigl[(1 + \tfrac12\alpha\psi)\, e^{-\alpha\psi/2}\bigr]^{2/(2+L_M)}\f$ | \f$\bigl[(1 + \tfrac12\alpha\psi)\, e^{-\alpha\psi/2}\bigr]^{2}\f$ | \f$\alpha\f$, Mualem \f$L_M\f$ (0.5) |
+| `BROOKS_COREY` (1964) | 1 for \f$\psi \le \psi_b\f$, else \f$(\psi_b/\psi)^{\lambda}\f$ | 1 for \f$\psi \le \psi_b\f$, else \f$(\psi_b/\psi)^{2 + 3\lambda}\f$ | \f$\psi_b, \lambda\f$ |
+| `VAN_GENUCHTEN` (1980) | \f$\bigl[1 + (\alpha\psi)^{n}\bigr]^{-m},\ m = 1 - 1/n\f$ | \f$S_e^{L_M}\bigl[1 - (1 - S_e^{1/m})^{m}\bigr]^{2}\f$ | \f$\alpha, n, L_M\f$ |
+
+Russo's retention is the Mualem-consistent inverse of his conductivity, so it
+costs the same as Gardner and is the default; Brooks–Corey's air-entry branch
+is the one non-smooth law; van Genuchten opens the Rosetta and UNSODA
+databases. \f$S_e\f$ is kept in \f$[10^{-8}, 1]\f$.
+
+
+![Figure 9-2](figures/png/hydrology_ch9_soil_characteristics.png)
+
+*Figure 9-2 Retention and relative conductivity of the four soil-characteristic laws at their default parameters*
+
+**Hydrostatic-equilibrium storage.** The water a column of thickness \f$L\f$
+holds when hydrostatic above the table is
+
+\f[ h_u^{\ast}(L) = \int_0^{L} \theta(\psi)\, d\psi = \theta_r L + (\theta_s - \theta_r)\, \sigma(L), \qquad \sigma(L) = \int_0^{L} S_e(\psi)\, d\psi \f]  (9-2)
+
+with \f$\sigma(L)\f$ closed-form for Gardner, \f$(1 - e^{-\alpha L})/\alpha\f$,
+and for Brooks–Corey,
+\f$\psi_b + \psi_b\bigl[(L/\psi_b)^{1-\lambda} - 1\bigr]/(1 - \lambda)\f$ for
+\f$L > \psi_b\f$ (else \f$L\f$; \f$\lambda = 1\f$ takes the logarithm), and by
+four-point Gauss–Legendre quadrature for Russo and van Genuchten; \f$L\f$ is
+floored at 1 mm. This integral is the ENSLAVED closure's whole unsaturated
+state and the initial condition of every column.
+
+**The closed-form recharge.** For Gardner, the quasi-steady recharge across the
+table is Qu and Duffy's equation 22 verbatim, on the saturation scale
+\f$\tilde h_u = (h_u - \theta_r L)/(\theta_s - \theta_r)\f$:
+
+\f[ q_0(h_u, h_g) = K_s\, \frac{1 - e^{-\alpha L} - \alpha\, \tilde h_u}{\alpha L\,\bigl(1 - e^{-\alpha L}\bigr)}, \qquad L = z_s - h_g \f]  (9-3)
+
+positive downward, negative for capillary rise, smooth in both states. It is
+identical to a relaxation of the stored water toward its hydrostatic
+equilibrium at a conductivity-set rate,
+
+\f[ q_0 = C(L)\,\bigl[\tilde\sigma^{\ast}(L) - \tilde h_u\bigr], \qquad \tilde\sigma^{\ast}(L) = \frac{1 - e^{-\alpha L}}{\alpha}, \quad C(L) = \frac{K_s}{L\,\bigl(1 - e^{-\alpha L}\bigr)} \f]  (9-4)
+
+**The other three laws generalise (9-4)**: the equilibrium is the law's own
+\f$\sigma(L)\f$ from (9-2) and the rate is the conductivity at the column's
+mean suction over that integral,
+
+\f[ q_0 = \frac{\bar K}{\sigma(L)}\,\bigl[\sigma(L) - \tilde h_u\bigr], \qquad \bar K = K\!\left(\psi = \tfrac12 L\right) \f]  (9-5)
+
+which for Gardner gives the same order and limits as (9-4).
+
+**The Experimental caveat.** The code states, and this manual repeats: (9-5)
+is the engine's generalisation, not the literature's. Gardner reproduces the
+published closed form exactly and is verified against it. Russo, Brooks–Corey
+and van Genuchten reproduce the correct equilibrium and sign, but their
+relaxation *rate* is a modelling choice rather than a published result. The
+closure-ladder benchmark and HYDRUS-1D comparison the plan schedules would
+license them; until those run the three carry \status{Experimental} in §9.11,
+Gardner or Russo are preferred for anything quantitative, and closure B — which
+integrates the real Richards flux and needs none of this — is preferred where
+the answer matters. The caveat concerns the recharge closure only.
+
+**The dimensionless group** read by the closure selection is \f$\alpha L\f$,
+the column thickness in capillary lengths; for Brooks–Corey the law's own
+inverse length replaces \f$\alpha\f$ (\f$\alpha L \equiv L/\psi_b\f$).
+
+**The wilting stress** reducing evaporative demand is a smooth Feddes-style
+multiplier of the suction,
+
+\f[ S(\psi) = \begin{cases} 1 & \psi \le 0 \\ s^{2}(3 - 2s),\ s = 1 - \psi/\psi_w & 0 < \psi < \psi_w \\ 0 & \psi \ge \psi_w \end{cases} \f]  (9-6)
+
+deliberately not the legacy `if (infil <= 0)` gate and not piecewise-linear: a
+kink here shows up as a kink in the ET ledger that reads like a solver artefact.
+
+
+
+## 9.4 Unsaturated-zone closures
+
+The unsaturated store is represented per cell by `CLOSURE` (in
+`[2D_AQUIFER_OPTIONS]` or on a row), resolved from `AUTO` at initialisation.
+
+### 9.4.1 The AUTO rule
+
+`AUTO` reads \f$\alpha L\f$ of the cell's *initial* column:
+
+| \f$\alpha L\f$ | Closure | Reasoning |
+|---|---|---|
+| \f$< 1\f$ | `ENSLAVED` | The column equilibrates far faster than the table moves; its storage is a function of the table |
+| \f$1 \le \alpha L < 5\f$, or `FORCE_CLOSED_FORM YES` | `CLOSED_FORM` | The quasi-steady recharge (9-3)/(9-5) holds |
+| \f$\ge 5\f$ | `SIGMA` | The quasi-steady assumption fails: travel time, profile memory and a localised capillary fringe are the physics, and only a resolved column carries them |
+
+A warning reports how many cells resolved to each. The design record also
+describes a soft warning near \f$\alpha L \approx 3\f$ and a refusal of
+`ENSLAVED` above \f$\alpha L = 2\f$; neither is in the code, which accepts
+`CLOSURE ENSLAVED` on any column.
+
+### 9.4.2 `CLOSED_FORM` (closure A)
+
+One bulk state \f$h_u\f$ driven by the quasi-steady recharge. At a firing of
+step \f$\Delta t\f$, with the table moving from \f$L_0\f$ to \f$L_1\f$ (§9.5),
+
+\f[ h_u^{\,1} = h_u^{\,0} + \bigl(q^{+} - q_{ET} - q_0\bigr)\,\Delta t + \theta_{bot}\,(L_1 - L_0) \f]  (9-7)
+
+where \f$q^{+}\f$ is the infiltration delivered from the surface (Chapter 8),
+\f$q_{ET}\f$ the demand of §9.8, \f$q_0\f$ from (9-3) or (9-5), and the last
+term the **handover** — the water the moving table carries across the zone
+boundary. The slab content is the bulk store's own mean,
+\f$\theta_{bot} = \mathrm{clamp}(h_u^{\,0}/L_0,\ \theta_r,\ \theta_s)\f$, and
+it is the *same* number the saturated update pairs with its storage coefficient
+\f$S_y = \theta_s - \theta_{bot}\f$; if the two zones disagreed on how much
+water a moving table carries, the cell would leak at a rate proportional to
+\f$\lvert \dot h_g \rvert\f$. Drained, it reduces to \f$\theta_s - \theta_r\f$.
+
+Two caps keep the books. Above \f$\theta_s L_1\f$ the excess is *rejected* to
+the surface (§9.7). Below \f$\theta_r L_1\f$ — a table rising faster than the
+fluxes refill the column — the shortfall is drawn back up out of the saturated
+zone in the same firing, lowering the table by
+\f$\delta = (\theta_r L_1 - h_u^{\,1})/(\theta_s - \theta_r)\f$ (bounded by
+its thickness); a shortfall no water anywhere can meet is booked as ET that was
+never available rather than invented. The recharge is also capped by
+availability: downward, \f$q_0 \le (h_u - \theta_r L_0)/\Delta t\f$; upward,
+\f$-q_0 \le h_g(\theta_s - \theta_r)/\Delta t\f$. Without the first cap a cell
+that cannot reach equilibrium drains past residual and keeps "delivering" at
+\f$\bar K\f$ forever.
+
+### 9.4.3 `ENSLAVED`
+
+The shallow-water-table reduction of Qu and Duffy's equation 39: \f$h_u\f$ is
+algebraic in \f$h_g\f$, \f$h_u = h_u^{\ast}(L)\f$ from (9-2), and the cell has
+one state. Since \f$d h_u^{\ast}/dL = \theta(L)\f$, the column contributes its
+*surface* water content as a storage debit, \f$S_y = \theta_s - \theta(L)\f$,
+and infiltration drives the table with no lag: \f$q_0 = q^{+} - q_{ET}\f$.
+
+The table is not updated by (9-10) alone. The balance
+\f$W(h) = \theta_s h + h_u^{\ast}(z_s - h)\f$ is monotone, so the new table
+solves \f$W(h_g^{\,1}) = W(h_g^{\,0}) + \Delta V_{sat}/A\f$ on \f$[0, z_s]\f$
+by a safeguarded Newton with bisection fallback on the volume residual
+(\f$W\f$ is flat across the capillary fringe, where only bisection works).
+What the interval cannot hold is booked exactly: above \f$z_s\f$ as Dunne
+excess, below 0 as a refund to the sinks (§9.5). The unguarded Newton this
+replaced created 23.5 m³ on a two-cell exfiltration deck.
+
+### 9.4.4 `SIGMA` (closure B)
+
+An explicit column of \f$m\f$ layers on \f$\sigma = z/L \in [0, 1]\f$,
+\f$z\f$ downward from the ground, \f$\Delta\sigma = 1/m\f$. Layers stretch and
+compress as the table moves with no regridding and a fixed SoA stride, so a
+layer sweep vectorises across columns. The **conserved** quantity is the water
+depth per layer \f$w_j = \theta_j L \Delta\sigma\f$; \f$\theta\f$ is
+re-derived from \f$w\f$ and the *new* \f$L\f$ at the end of the sweep, which
+makes the compression exact. With \f$\dot L = (L_1 - L_0)/\Delta t\f$ and face
+\f$j + \tfrac12\f$ at \f$\sigma_f = (j+1)/m\f$, the downward-positive flux is
+
+\f[ F_{j+1/2} = K\!\bigl(\psi(\theta_j)\bigr) \;-\; \theta_{donor}\,\sigma_f\,\dot L \;-\; \frac{\bar D_{j+1/2}}{L_0\,\Delta\sigma}\,\bigl(\theta_{j+1} - \theta_j\bigr) \f]  (9-8)
+
+Gravity is downward, so the advective donor is the layer above (first-order
+upwind; MUSCL is a recorded follow-up). The grid term is upwinded on its own
+sign: with \f$\dot L > 0\f$ (table falling) the donor is the layer below. The
+capillary term, \f$D = K\, d\psi/d\theta\f$ harmonic-mean across the face, is
+included only under `CAPILLARY_DIFF YES` (default off). The boundaries:
+
+\f[ F_{top} = \min\!\bigl(q^{+},\ (\theta_s - \theta_0)\, L_0 \Delta\sigma / \Delta t\bigr) - q_{ET}^{taken}, \qquad F_{bot} = q_{0,phys} - \theta_{m-1}\,\dot L \f]  (9-9)
+
+At the top, the first layer's headroom caps the infiltration accepted and the
+remainder is **rejected** to the surface (§9.7); the ET taken is the demand
+reduced by (9-6) at the top layer's own suction (wilting suction at 1 %
+effective saturation) and limited to what the layer holds above residual. At
+the bottom, \f$q_{0,phys}\f$ is the bottom layer's gravity drainage
+\f$K(\psi(\theta_{m-1}))\f$ and the second term is the **handover** swept
+across the moving boundary. Both together are what the saturated zone gains,
+which is why (9-10) books \f$q_{0,phys}\f$ with
+\f$S_y = \theta_s - \theta_{m-1}\f$ rather than \f$F_{bot}\f$ with
+\f$\theta_s\f$: the same equation, but only the first conserves once the
+column retains water above a falling table. The design record writes
+\f$\theta_s\f$; \f$\theta_s - \theta_{bot}\f$ is the textbook specific yield
+and what the code uses.
+
+Positivity is a per-layer availability share: a layer may not export more than
+it holds above residual in one step. After the update \f$\theta\f$ is
+re-derived from the new geometry. A rising table compresses every layer, and a
+layer whose water then exceeds \f$\theta_s L_1 \Delta\sigma\f$ is saturated:
+the surplus cascades downward and whatever reaches the bottom is reported as an
+**overflow to the saturated zone** applied to \f$h_g\f$ in the same firing; a
+deficit below residual is drawn upward the same way. Clamping the surplus away
+inside the sweep is the classic σ-grid failure and lost 0.39 m of water on the
+closed-column oscillation gate. Columns are seeded hydrostatic above their
+initial table, layer centres at \f$\psi = L(1 - \sigma)\f$.
+
+
+
+## 9.5 Saturated zone: lateral Darcy flow and deep loss
+
+### 9.5.1 The explicit finite-volume balance
+
+At a cell's firing every saturated source shares one storage coefficient:
+
+\f[ \Delta V_{sat} = \bigl(q_0 - q_{deep}\bigr)\, A\, \Delta t \;+\; V_{lat} \;-\; V_{node} \;+\; V_{link}, \qquad h_g^{\,1} = h_g^{\,0} + \frac{\Delta V_{sat}}{S_y\, A} \f]  (9-10)
+
+where \f$V_{lat}\f$ is the lateral volume gathered from the cell's edge
+accumulators since its last firing (positive in), \f$V_{node}\f$ the node
+exchange gathered from its bed accumulators (positive out, §9.6),
+\f$V_{link}\f$ the conduit seepage delivered (§9.6), and \f$S_y\f$ the
+closure's specific yield of §9.4, floored at \f$10^{-3}\f$. The split is:
+recharge from the current column state, then (9-10), then the clamp, then the
+column sweep at the *clamped* \f$\dot L\f$, then the column's overflow or
+deficit applied to \f$h_g\f$, then Dunne. Deriving \f$\dot L\f$ from the
+clamped table is what makes the clamp harmless: no water is created at
+\f$h_g = z_s\f$ or destroyed at \f$h_g = 0\f$.
+
+**The clamp keeps its books.** A table above \f$z_s\f$ becomes Dunne volume
+\f$(h_g^{\,1} - z_s)\, S_y A\f$ (§9.7). A negative table means the sinks asked
+for more than the aquifer holds; the shortfall \f$-h_g^{\,1} S_y A\f$ is
+refunded to the sinks that overdrew — deep loss first, then the node exchange
+— and the refunded amounts are what the ledger records.
+
+### 9.5.2 Lateral Darcy flow
+
+Per unique interior edge \f$e\f$ between cells \f$l\f$ and \f$r\f$, of length
+\f$\xi_e\f$ and centroid distance \f$d_e\f$,
+
+\f[ Q_e = \bar K_e\, T_e\, \xi_e\, \frac{H_l - H_r}{d_e}, \qquad \bar K_e = \frac{2 K_{s,l} K_{s,r}}{K_{s,l} + K_{s,r}}, \qquad T_e = h_{g,\mathrm{donor}} \f]  (9-11)
+
+positive from \f$l\f$ to \f$r\f$. The conductivity is the **harmonic mean**
+(zero if either side is) and the transmissivity is the **donor** cell's
+saturated thickness, upwind on the head difference — the mean here is the
+classic way to make a drying aquifer pump water it does not have. Positivity is
+a per-face share of the donor's drainable water, split across the donor's faces
+so a cell with many wet neighbours cannot be emptied several times over:
+
+\f[ \lvert Q_e \rvert \le \frac{\tfrac12\, T_e\, S_{y,\mathrm{donor}}\, A_{\mathrm{donor}}}{n_{f,\mathrm{donor}}\, \Delta t} \f]  (9-12)
+
+The volume \f$Q_e \Delta t\f$ is booked \f$\mp\f$ into the edge's two side
+accumulators at the face's cadence and gathered by each cell at its own firing
+— the surface marcher's strategy, which makes conservation across tiers
+inherited rather than re-proved (§9.9). Under `MODE PER_SUBCATCH` the edge
+topology is empty and (9-11) is never evaluated.
+
+### 9.5.3 Deep loss
+
+\f[ q_{deep} = c_{loss}\, \frac{h_g}{z_s} \f]  (9-13)
+
+a linear sink at full-saturation rate \f$c_{loss}\f$ (`C_LOSS`, default 0) —
+exactly Chapter 5's deep percolation (5-21), with \f$c_{loss}\f$ as \f$DP\f$
+and \f$h_g/z_s\f$ as \f$d_L/(E_G - E_B)\f$. The design record also allows a
+`[GWF] DEEP` expression; the code implements the linear form only.
+
+
+
+## 9.6 Node–aquifer exchange
+
+A 1D node on the mesh exchanges with the aquifer of the cell containing it
+through a MODFLOW-River conductance, sign-determined by heads. With the pipe
+head \f$H_{pipe} = z_{inv} + d\f$ (converted to metres) and the aquifer head
+\f$H_{gw} = z_{bed} + h_g\f$,
+
+\f[
+Q_{node} = C\,\bigl(H_{gw} - H_{pipe}\bigr), \qquad
+C = \begin{cases} \dfrac{K_c\, A_b}{d_C} & \text{semi-confining bed given (config b)} \\[1.2em] \dfrac{K_s\, A_b}{\tfrac12 z_s} & \text{no bed: direct Darcy over half the column (config a)} \end{cases}
+\f]
+(9-14)
+
+positive out of the aquifer into the pipe. \f$K_c\f$ and \f$d_C\f$ are the
+bed's conductivity and thickness (`KC`, `DC`); \f$A_b\f$ is `AREA`, or the
+cell's area when omitted. Table above pipe head is groundwater inflow, pipe
+head above table is exfiltration: one equation, no fitted coefficients.
+
+
+![Figure 9-3](figures/png/hydrology_ch9_node_bed_exchange.png)
+
+*Figure 9-3 Node-aquifer exchange through a semi-confining bed, in both directions, with the caps that bound it*
+
+**Caps.** A drain (\f$Q > 0\f$) may take at most half the cell's drainable
+water per step, \f$\tfrac12 h_g S_y A / \Delta t\f$. A recharge
+(\f$Q < 0\f$) is guarded three ways: a column whose table is within
+\f$10^{-4} z_s\f$ of the ground takes nothing (it would come straight back as
+Dunne excess and ping-pong against the frozen node head); the saturated zone's
+headroom \f$(z_s - h_g)\, S_y A\f$ is taken in the same half-per-step share;
+and the node cannot give more than it holds for the batch plus what flows
+through it — a junction stores nothing below its rim but can lose water at the
+rate it is fed.
+
+**Cadence and booking.** The exchange is sampled at the marcher's tier-0
+cadence against the batch-frozen 1D heads, like the surface's junction
+exchange, and booked into the bed's accumulator; the aquifer cell gathers its
+share when *it* fires, and neither side is pinned to the other's tier. Per
+node, the batch's volume is added to the node's coupling volume for the next
+routing step's lateral-inflow assembly — without entering the surface ledger;
+its home is the aquifer's `led_node`.
+
+**Which nodes exchange.** `NODE_ENROLMENT AUTO` (default) enrols every node
+whose `[COORDINATES]` fall in a mesh cell with a direct-Darcy bed over the
+cell's area unless a `[2D_AQUIFER_NODE]` row names it; a row overrides with its
+own bed (cell given explicitly, 1-based, or as `CELL AUTO`) or opts out with
+`EXCHANGE NO`; `ROWS` limits exchange to the authored rows. One bed per node
+is enforced; a bed off the mesh is a warning and the node exchanges with
+nothing. A storage node with a bed has its `[STORAGE]` exfiltration switched
+off, since both would lose the same water twice.
+
+**Conduit seepage.** With `LINK_SEEPAGE AUTO` (default), every conduit with a
+`[LOSSES]` seepage rate whose polyline crosses the mesh delivers its seepage
+volume into the cells it crosses, weighted by the length inside each (exact
+Cyrus–Beck clipping). The 1D side keeps booking the loss; the volume lands in
+`led_link` and rides (9-10) as \f$V_{link}\f$. `NONE` keeps it a system loss.
+
+
+
+## 9.7 Saturation excess (Dunne) return flow and rejected infiltration
+
+Two physically distinct routes carry water back to the surface cell above, and
+both are booked to the same per-cell accumulator:
+
+- **Dunne excess** — the table itself arriving at the ground: whatever
+  \f$h_g^{\,1}\f$ exceeds \f$z_s\f$ by, after (9-10) and the column's overflow,
+  becomes \f$(h_g^{\,1} - z_s)\, S_y A\f$ of surface water (under `ENSLAVED`,
+  the volume above \f$W(z_s)\f$) and the table is held at \f$z_s\f$.
+- **Rejected infiltration** — water the top of the column would not take:
+  under closure A the excess of (9-7) above \f$\theta_s L_1\f$, under closure B
+  \f$q^{+} - F_{top}\f$ from (9-9). `ENSLAVED` has no column to reject from.
+
+\f[ V_{\to surf} = \bigl[\,\mathrm{DUNNE}\,\bigr]\, V_{Dunne} + q_{rej}\, A\, \Delta t \f]  (9-15)
+
+Together they *are* the mass balance, which is why `DUNNE` defaults on; the
+flag exists for compatibility comparisons and disables only the first route.
+The volume waits in the cell's surface-bound accumulator until the surface cell
+fires and drains it as a source in its own budget (Chapter 8, equation 8-6).
+A dry surface cell above a saturating column would otherwise hold that water
+forever, so the marcher pins every cell with pending surface-bound water active
+at each rebuild — the one seed of the active set that does not come from the
+surface's own state, and what lets return flow re-emerge in a valley bottom
+with no rain falling. Rainfall on such a cell simply lands on the surface,
+where the column accepts none of it and the surface routes it.
+
+
+
+## 9.8 Evapotranspiration modes
+
+`GW_ET` — in `[2D_AQUIFER_OPTIONS]`, or as a `[2D_OPTIONS]` alias folded into
+the same option at open — selects how the subsurface meets evaporative demand:
+
+| Mode | Capillary rise (negative \f$q_0\f$) | Demand at the column top |
+|---|---|---|
+| `NONE` (default) | Suppressed: a negative \f$q_0\f$ is zeroed | None |
+| `CAPILLARY_RISE` | Allowed | None |
+| `BOUNDARY_ET` | Suppressed | Yes |
+| `BOTH` | Allowed | Yes |
+
+**The demand** is the surface cell's evaporation rate of Chapter 8 §8.5 — zero
+under the default `[2D_OPTIONS] EVAPORATION YES` with no forcing, the
+project's `[EVAPORATION]` under `CLIMATE` — reduced by (9-6) at the column's
+mean suction with the wilting suction at 150 m (about \f$-15\f$ bar):
+
+\f[ q_{ET} = e_i\; S\bigl(\psi(\bar S_e)\bigr), \qquad \bar S_e = \mathrm{clamp}\!\left(\frac{h_u/L_0 - \theta_r}{\theta_s - \theta_r},\ 10^{-6},\ 1\right), \quad \psi_w = 150\ \mathrm{m} \f]  (9-16)
+
+with \f$\psi(\bar S_e)\f$ the law's retention inverse. Under closure A and
+`ENSLAVED` this \f$q_{ET}\f$ is removed from the column (or, enslaved, from the
+table) and booked. Under closure B it is offered to the column sweep, which
+applies its own stress at the *top layer's* suction with the wilting suction
+at 1 % effective saturation and limits the take to what the top layer holds;
+the amount actually removed is booked. The two stresses therefore compound
+under `SIGMA` — an implementation detail of the column rather than a documented
+design choice.
+
+This replaces Chapter 5's three-parameter split — upper-zone fraction,
+lower-zone depth and the `if (infil <= 0)` gate — with one boundary condition
+at the top of the unsaturated zone and one physical path from below: there is
+no separate lower-zone ET term, water reaches the top by capillary rise (the
+negative branch of (9-3)/(9-5), or the σ column's upward propagation), and the
+closure that governs recharge downward governs capillary rise upward. The
+wilting point survives; the lower-zone depth does not. Capillary rise is capped
+by what the table holds (§9.4.2) and counted as the negative share of recharge.
+
+
+
+## 9.9 Time stepping and local time stepping
+
+The subsurface has no loop of its own. It joins the surface marcher's
+halving-order tier ladder through four hooks — tier assignment at every
+rebuild, a face phase and a cell phase per due tier, and a settle before any
+re-tier — under two guarantees enforced by construction. **G-A,
+independence:** a cell's tier comes only from its own bound
+\f$\min(\Delta t_g, \Delta t_u)\f$; the surface's pin-to-tier-0 rule for
+coupling cells is not applied, so a cell with node exchange, infiltration or
+Dunne transfer keeps its tier and the cross-domain volume accumulates until it
+fires. **G-B, conservation:** every flux channel books \f$\pm\Delta V\f$ into a
+side accumulator at the producer's cadence and is gathered by the owner at its
+own firing — lateral Darcy on the edges, node exchange on the beds,
+infiltration and seepage per cell, Dunne on the surface-bound accumulator.
+
+**The saturated bound** is that of explicit diffusion on the head:
+
+\f[ \Delta t_g \le C_{gw}\, \frac{A\, S_y}{\displaystyle \sum_e \bar K_e\, T_e\, \xi_e / d_e \;+\; c_{loss} A / z_s \;+\; \sum_{beds} C_b}, \qquad T_e = \max\bigl(h_{g,i},\ h_{g,j},\ 0.01\, z_s\bigr) \f]  (9-17)
+
+with \f$S_y = \theta_s - \theta_r\f$ (floored), the wetter of the pair with a
+floor for the transmissivity so an empty aquifer does not report an infinite
+step and then take one, and the deep-loss and node conductances folded in as
+linear sinks. `C_GW` defaults to 0.5, range (0, 1]. For realistic
+conductivities the bound is minutes to hours — orders above the surface tiers,
+which is what local time stepping exploits.
+
+**The unsaturated bound** depends on the closure. A σ column's own bound is
+
+\f[ \Delta t_u \le C_{col}\, \min_j \frac{L\, \Delta\sigma}{c(\theta_j) + \lvert \sigma_j \dot L \rvert + 2\bar D_j / (L\Delta\sigma)}, \qquad c(\theta) = \frac{dK}{d\theta} \f]  (9-18)
+
+with the celerity by a centred difference through the retention inverse and
+\f$\dot L\f$ estimated from the previous firing, \f$-q_{0,last}/S_y\f$.
+Closure A is a relaxation whose stiffness \f$C = -\partial q_0/\partial h_u\f$
+is taken numerically, so \f$\Delta t_u \le C_{col}/C\f$ covers every soil law;
+`ENSLAVED` has no unsaturated bound. `C_COL` defaults to 0.9.
+
+**Tiers and ordering.** A cell's rung is
+\f$\lfloor \log_2(\Delta t_{cell}/dt_0) \rfloor\f$ by the same `ilogb`
+arithmetic the surface uses, clamped to the ladder. The base step is the
+minimum of the surface's and the aquifer's finest bound, so a groundwater cell
+finer than every wet surface cell (or a whole domain with a dry surface) does
+not fire beyond its bound on rung 0. The ladder height is the surface's
+`LTS_TIERS` (default 4, at most 8); a slower cell lands on the coarsest rung
+and fires more often than it needs — the design record's runtime tier count
+(D-N1) is deliberately not taken, and `requiredTiers()` is unused. A face
+fires at the finer of its two cells' rungs. Within a base substep the order is
+surface faces, subsurface faces, surface cells, subsurface cells (so a cell
+that infiltrated hands the water down within the substep), then node sampling
+at tier 0. A routing window that does not fit a whole macro cycle ends with
+global tail steps in which every aquifer rung fires once.
+
+**Settling** does not apply pending volumes: turning a volume into a table
+rise also moves the unsaturated store, so all volume goes through the cell
+firing. Nothing strands, since accumulators are gathered through incidences a
+re-tier does not change; continuity audits between firings must add them (§9.10).
+
+
+
+## 9.10 Continuity ledger and reporting
+
+### 9.10.1 The ledger
+
+The kernel keeps cumulative domain totals in m³:
+
+| Term | Meaning | Sign |
+|---|---|---|
+| `infil_in` | \f$q^{+}\f$ delivered from the surface | in |
+| `link` | Conduit seepage delivered | in |
+| `lateral` | Net lateral Darcy across the domain edge | net in |
+| `deep` | Deep percolation | out |
+| `node` | Node exchange | out of the aquifer |
+| `et` | Subsurface ET | out |
+| `dunne` | Saturation excess and rejection returned to the surface | out |
+| `recharge`, `caprise` | Unsaturated to saturated transfer and its negative share | internal |
+| `init_storage`, `storage` | Water at the start; water now | — |
+
+Three storage views exist. `storage()` is (9-1) summed over cells. The
+**live** storage adds every side accumulator (lateral edge pairs, water in
+flight to or from the surface, seepage in flight) and is what the results file
+and the C API report. The **ledgered** storage adds only the lateral
+accumulators, since the surface accumulators are always one firing out of
+phase with `infil_in` and `dunne`. The continuity residual is
+
+\f[ \mathcal{R} = S_{ledgered} - S_0 - \bigl[(F_{in} + Q_{lat} + F_{link}) - (F_{deep} + F_{node} + F_{ET} + F_{Dunne})\bigr] \f]  (9-19)
+
+zero to machine precision for a conserving kernel; recharge and capillary rise
+are internal to a cell and do not appear.
+
+### 9.10.2 The report
+
+When `[REPORT] CONTINUITY` is on and the kernel ran, a **2D Aquifer
+Continuity** block follows the 2D Surface Routing Continuity block, in cubic
+metres: Initial Stored Volume, Infiltration Inflow, Conduit Seepage Inflow,
+Lateral Net Inflow, Deep Percolation, Node Exchange Outflow, Subsurface ET,
+Saturation Excess Return, Final Stored Volume (the live storage), then Recharge
+and Capillary Rise listed as internal. Its continuity error is (9-19) as a
+percentage of \f$S_0 + F_{in} + F_{link} + \max(0, Q_{lat})\f$. By design the
+surface block's Infiltration Loss (Chapter 8 §8.6) is this block's
+Infiltration Inflow, and this block's Saturation Excess Return is the
+surface's aquifer inflow term.
+
+### 9.10.3 The results file
+
+With the `GROUNDWATER` group of `REPORT_2D_VARIABLES` (in `DEFAULT`), the
+results file carries per-cell fields held from each cell's last firing:
+
+| Dataset | Content | Units |
+|---|---|---|
+| `Mesh2_face_gw_table_elev` | Water-table elevation \f$z_{bed} + h_g\f$ | m |
+| `Mesh2_face_gw_hg` | Saturated thickness | m |
+| `Mesh2_face_gw_hu` | Closure A unsaturated storage (0 under closure B) | m |
+| `Mesh2_face_gw_recharge` | \f$q_0\f$, positive down, negative capillary rise | m/s |
+| `Mesh2_face_gw_lateral` | Net lateral Darcy into the cell | m³/s |
+| `Mesh2_face_gw_node_exchange` | Exchange with the node bed, positive into the pipe | m³/s |
+| `Mesh2_face_gw_deep` | Deep percolation | m/s |
+| `Mesh2_face_gw_et` | Subsurface ET | m/s |
+| `Mesh2_face_gw_dunne` | Saturation excess returned to the surface | m³/s |
+| `Mesh2_face_gw_infil_in` | Infiltration delivered from the surface | m/s |
+| `Mesh2_face_gw_link_seepage` | Conduit seepage delivered | m³/s |
+
+plus two static descriptors, `Mesh2_face_gw_bed_elev` and
+`Mesh2_face_gw_closure` (0 closed form, 1 enslaved, 2 sigma); the domain
+series `groundwater_ledger` of shape [time, 12] in the order recharge, lateral,
+deep, node, dunne, caprise, et, infil_in, init_storage, storage, link,
+continuity_residual (read its `terms` attribute — the seepage term was
+appended and moved the residual); and `groundwater_node_exchange_cum`, the
+cumulative exchange per bed, positive out of the aquifer, with node names as
+an attribute. The `GW_DETAILED` group adds `Mesh2_face_gw_theta_sigma` of
+shape [time, layer, face], layer 0 at the ground, zero for a non-sigma cell;
+it is \f$m \times\f$ the cell count per step and off by default.
+
+
+
+## 9.11 Alternatives
+
+| Family | Alternative | Behaviour | Status |
+|---|---|---|---|
+| Soil characteristic | `GARDNER` | Exponential retention and conductivity; recharge by equation 22 verbatim, verified against it | \status{Implemented} |
+| Soil characteristic | `RUSSO` (default) | Mualem-consistent retention at Gardner's cost; recharge by (9-5), whose rate is the engine's | \status{Experimental} |
+| Soil characteristic | `BROOKS_COREY` | Air-entry branch, closed-form equilibrium storage; recharge by (9-5) | \status{Experimental} |
+| Soil characteristic | `VAN_GENUCHTEN` | Rosetta/UNSODA parameters, quadrature equilibrium; recharge by (9-5) | \status{Experimental} |
+| Closure | `AUTO` | Per-cell selection from \f$\alpha L\f$ at 1 and 5 | \status{Implemented} |
+| Closure | `CLOSED_FORM` | Bulk \f$h_u\f$ with quasi-steady recharge and the handover term | \status{Implemented} |
+| Closure | `ENSLAVED` | \f$h_u\f$ algebraic in \f$h_g\f$; bracketed volume solve | \status{Implemented} |
+| Closure | `SIGMA` | Explicit ALE σ column, first-order upwind | \status{Implemented} |
+| Closure | `SIGMA` with MUSCL reconstruction | Recorded follow-up in the column's contract | \status{Planned} |
+| Column option | `CAPILLARY_DIFF YES` | Harmonic-mean diffusive term in (9-8) and its bound | \status{Implemented} |
+| Mode | `MODE MESH` (default) | Kernel on the mesh cells with lateral Darcy | \status{Implemented} |
+| Mode | `MODE PER_SUBCATCH` | Today: the mesh kernel with lateral topology removed; the one-cell-per-subcatchment vehicle is not in the code | \status{Experimental} |
+| Deep loss | Linear \f$c_{loss} h_g / z_s\f$ | Chapter 5's (5-21) form | \status{Implemented} |
+| Deep loss | `[GWF] DEEP` expression | Named in the design record only | \status{Planned} |
+| Node exchange | `NODE_ENROLMENT AUTO` | Every node inside the mesh, direct Darcy over the cell area | \status{Implemented} |
+| Node exchange | `NODE_ENROLMENT ROWS` | Authored `[2D_AQUIFER_NODE]` rows only | \status{Implemented} |
+| Node exchange | Semi-confining bed (`KC`, `DC`) | MODFLOW-River config b conductance | \status{Implemented} |
+| Conduit seepage | `LINK_SEEPAGE AUTO` | Length-weighted delivery of `[LOSSES]` seepage into crossed cells | \status{Implemented} |
+| Conduit seepage | `LINK_SEEPAGE NONE` | Seepage stays a system loss | \status{Implemented} |
+| Return flow | `DUNNE YES` (default) | Table-at-ground excess to the surface | \status{Implemented} |
+| Return flow | `DUNNE NO` | Compatibility only; rejection still returns | \status{Implemented} |
+| ET | `GW_ET NONE`, `CAPILLARY_RISE`, `BOUNDARY_ET`, `BOTH` | §9.8 | \status{Implemented} |
+| Time stepping | Shared tier ladder, height `LTS_TIERS` | §9.9 | \status{Implemented} |
+| Time stepping | Runtime tier count reaching the slowest cell (D-N1) | `requiredTiers()` exists; the marcher does not grow the ladder | \status{Planned} |
+| Verification law | Broadbridge–White | Exact Richards benchmark in the test harness; not selectable | \status{Retired} |
+| Backend | GPU or OpenMP plugin marchers | The kernel runs on the CPU explicit marcher only; refused otherwise | \status{Planned} |
+
+
+
+## 9.12 Parameter estimation
+
+A `[2D_AQUIFER]` row is `*`, `TAG name` or `CELL n`, then five positional
+columns `KS ZS THETA_S THETA_R ALPHA`, then keyword pairs (so a fifth law
+never renumbers a file). Values are authored in project units, converted once:
+
+| Column or keyword | Symbol | US units | SI units | Default |
+|---|---|---|---|---|
+| `KS` | \f$K_s\f$ | in/hr | mm/hr | 1e-5 m/s internally |
+| `ZS` | \f$z_s\f$ | ft | m | 5 m |
+| `THETA_S`, `THETA_R` | \f$\theta_s, \theta_r\f$ | — | — | 0.45, 0.10 |
+| `ALPHA` | \f$\alpha\f$ | 1/ft | 1/m | 2 /m |
+| `PSI_B`, `LAMBDA` | \f$\psi_b, \lambda\f$ | ft, — | m, — | 0.2 m, 0.4 |
+| `N`, `L` | \f$n, L_M\f$ | — | — | 1.6, 0.5 |
+| `C_LOSS` | \f$c_{loss}\f$ | in/hr | mm/hr | 0 |
+| `HG0` | initial \f$h_g\f$ | ft | m | 0 (empty aquifer) |
+| `KC`, `DC`, `AREA` (node rows) | \f$K_c, d_C, A_b\f$ | in/hr, ft, ft² | mm/hr, m, m² | 0, 0, cell area |
+
+Validation requires \f$K_s, z_s, \alpha, \lambda > 0\f$,
+\f$0 < \theta_s \le 1\f$, \f$0 \le \theta_r < \theta_s\f$, \f$n > 1\f$,
+\f$\psi_b, c_{loss} \ge 0\f$, and a positive `DC` wherever `KC` is given.
+
+**Shared with Chapter 5.** The tables of §5.5 apply directly where the
+parameter is the same physical quantity:
+
+| This chapter | Chapter 5 | Where |
+|---|---|---|
+| \f$\theta_s\f$ | porosity \f$\varphi\f$ | §5.5.1 and its soil-texture tables and pedotransfer relations |
+| \f$\theta_r\f$ | nearest analogue is the wilting point \f$\theta_{WP}\f$ (an upper bound on residual content) | §5.5.1 |
+| \f$K_s\f$ | saturated hydraulic conductivity \f$K_S\f$ | §5.5.2 |
+| \f$z_s\f$ | \f$E_G - E_B\f$, ground minus aquifer-bottom elevation | §5.2 |
+| `HG0` | initial water-table depth \f$d_L\f$ | §5.2 |
+| \f$c_{loss}\f$ | the deep-percolation coefficient \f$DP\f$ of (5-21) | §5.3.4 |
+
+**Not carried over.** The percolation equation's conductivity and tension
+slopes (§5.5.2) are replaced by the soil law's own \f$K(\psi)\f$; the ET
+coefficients \f$UEF\f$ and \f$DEL\f$ (§5.5.3) by the boundary condition of
+§9.8; the discharge constants \f$A1, B1, A2, B2, A3\f$ (§5.5.4) by the
+head-driven exchange of §9.6. Calibrated values of these do not apply.
+
+**New parameters.** \f$\alpha\f$ is the Gardner/Russo sorptive number, the
+inverse capillary length (order 1 to 10 /m for sands, below 1 /m for clays; a
+5 m column with \f$\alpha = 2\f$ /m starts at \f$\alpha L = 10\f$ and resolves
+to `SIGMA` under `AUTO`). Brooks–Corey's \f$\psi_b, \lambda\f$ come from
+engineering soil tests, van Genuchten's \f$\alpha, n\f$ from Rosetta or
+UNSODA, and \f$K_c, d_C\f$ from a MODFLOW River package of the same area.
+
+
+
+## 9.13 Implementation
+
+| Concern | Where |
+|---|---|
+| State, options, rows, ledger | `src/engine/2d/subsurface/SubsurfaceData.hpp`, `.cpp` (`SubsurfaceState`, `GwOptions`, `GwAquiferRow`, `GwNodeBed`, `GwLinkShare`; the three storage views and the residual) |
+| Soil laws, equilibrium storage, recharge, stress | `src/engine/2d/subsurface/SoilCharacteristic.hpp`, `.cpp` |
+| The σ column | `src/engine/2d/subsurface/SigmaColumn.hpp`, `.cpp` (`advanceColumn`, `columnDtLimit`, `seedHydrostatic`, `columnStorage`) |
+| The kernel | `src/engine/2d/subsurface/SubsurfaceSolver.hpp`, `.cpp` — `initialize()`; the hooks `refreshDtCell()`, `assignTiers()`, `fireGwFaces()`, `fireGwCells()`, `settle()`; `sampleNodeExchange()`; `bookInfiltrationFromSurface()`, `bookLinkSeepage()`, `takeToSurface()`; the per-cell `fireCell()` |
+| Grammar, units, resolution, writer | `src/engine/2d/subsurface/SubsurfaceSections.cpp` — `[2D_AQUIFER_OPTIONS]`, `[2D_AQUIFER]`, `[2D_AQUIFER_NODE]`; `gwUnitFactors()`, `resolveSubsurface()`, `resolveLinkSeepage()`; documented in @ref engine_manual_sect_2D_AQUIFER_OPTIONS "[2D_AQUIFER_OPTIONS]", @ref engine_manual_sect_2D_AQUIFER "[2D_AQUIFER]" and @ref engine_manual_sect_2D_AQUIFER_NODE "[2D_AQUIFER_NODE]", with the `GROUNDWATER` and `GW_ET` keys in @ref engine_manual_sect_2D_OPTIONS "[2D_OPTIONS]" of @ref engine_manual_ch2_input_file "the input-file chapter" |
+| Wiring into the router and marcher | `src/engine/2d/SurfaceRouter2D.cpp` `initialize()` (enable, resolve, `setSubsurface`, one-owner checks), `coAdvanceStep()` (node volumes to `coupling_volume`), `advancePostRouting()` (seepage booking); `src/engine/2d/solver/ExplicitInertialSolver.cpp` `syncAndRebuild()` (dt0 fold, tiers, pending-cell pinning), `runMacroCycle()` (hook order), `fireCellsImpl()` (infiltration down, return up) |
+| Report and results | `src/engine/plugins/DefaultReportPlugin.cpp` (2D Aquifer Continuity); `src/engine/2d/output/Default2DOutputPlugin.cpp` (`Mesh2_face_gw_*`, `groundwater_ledger`, `groundwater_node_exchange_cum`) |
+| C API | `include/openswmm/engine/openswmm_gw2d.h` (`swmm_gw2d_*`, `SWMM_GW2D_LED_*`); `src/engine/2d/api/ApiGw2D.cpp` |
+
+The design records are `plans/TWO_ZONE_GROUNDWATER_FV_INTEGRATION_PLAN.md`
+(manuscript summary, the four feedbacks) and
+`plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md` (the explicit
+formulation, the σ column, the LTS guarantees). Where this chapter and those
+documents differ, the chapter follows the code, and the differences are named
+where they arise: the specific yield \f$\theta_s - \theta_{bot}\f$ in place of
+\f$\theta_s\f$ (§9.4.4), the closure thresholds without the
+\f$\alpha L \approx 3\f$ warning or the `ENSLAVED` refusal (§9.4.1), the linear
+deep loss without a `[GWF] DEEP` expression (§9.5.3), the fixed ladder height
+in place of the runtime tier count (§9.9), and `MODE PER_SUBCATCH` as
+implemented (§9.1).
+
+
diff --git a/docs/manuals/reference/quality.md b/docs/manuals/reference/quality.md
index f1c075618..040248397 100644
--- a/docs/manuals/reference/quality.md
+++ b/docs/manuals/reference/quality.md
@@ -68,47 +68,167 @@ managing stormwater runoff quality.
 
 ## List of Figures
 
-Figure 1-1. SWMM's Object Model
+
 
-Figure 1-2. SWMM's Process Models
+Figure 1-1. Elements of a typical urban drainage system
 
-Figure 1-3. Simulation Process Overview
+Figure 1-2. Objects of an OpenSWMM model
 
-Figure 2-1. Pollutant Sources in Urban Areas
+Figure 1-3. Processes modelled by OpenSWMM
+
+Figure 1-4. Block diagram of SWMM's state transition process
+
+Figure 1-5. Flow chart of SWMM's simulation procedure
+
+Figure 1-6. Interpolation of reported values from computed values
+
+Figure 1-7. The water quality of this manual: buildup, washoff, transport and reactions across the compartments
+
+Figure 2-1. Hourly domestic sewage time patterns
 
 Figure 2-2. Pollutant Buildup on Land Surfaces
 
 Figure 2-3. Pollutant Washoff During Storm Events
 
-Figure 3-1. Street Cleaning Effectiveness
+Figure 3-1. Accumulation of solids on urban streets versus time (Sartor and Boyd, 1972)
+
+Figure 3-2. Buildup of street solids in San Jose (from Pitt, 1979)
+
+Figure 3-3. Comparison of buildup equations for a hypothetical pollutant
+
+Figure 3-4. Evolution of buildup after a storm event
+
+Figure 4-1. Washoff of street solids by flushing with a sprinkler system (from Sartor and Boyd, 1972)
+
+Figure 4-2. Comparison of washoff functions
+
+Figure 4-3. Two-stream approach to modeling pollutant washoff
+
+Figure 4-4. Simulated load variations within a storm as a function of runoff rate
+
+Figure 5-1. Representation of the conveyance network in SWMM
+
+Figure 5-2. Comparison of completely mixed reactor equations for time varying inflow
+
+Figure 5-3. Comparison of completely mixed reactor equations for a step inflow
 
-Figure 4-1. Pollutant Transport in Drainage System
+Figure 5-4. Gravity settling treatment of TSS within a detention pond
 
-Figure 5-1. Treatment Processes
+Figure 6-1. A typical bio-retention cell
 
-Figure 6-1. LID Control Types
+Figure 6-2. Flow path across the surface of a green roof
 
-Figure 6-2. LID Control Performance
+Figure 6-3. Representation of a permeable pavement system
+
+Figure 6-4. Representation of rooftop disconnection
+
+Figure 6-5. Representation of a vegetative swale
+
+Figure 6-6. Different options for placing LID controls
+
+Figure 6-7. Storm event used for the LID example
+
+Figure 6-8. Flux rates through the bio-retention cell with no underdrain
+
+Figure 6-9. Moisture levels in the bio-retention cell with no underdrain
+
+Figure 6-10. Moisture levels in the bio-retention cell with underdrain
+
+Figure 6-11. Flux rates through the bio-retention cell with underdrain
+
+Figure 7-1. Flux-limited advection in the Eulerian engine: the face stencil and a step front under UPWIND and the three MUSCL limiters
+
+Figure 7-2. The five phases of a Lagrangian transport step: drain, mix, release, decay and publish on one conduit's parcel slab
+
+Figure 9-1. The heat budget of a water body: the six surface terms of the net flux by module, and the bed zone's conduction and hyporheic exchange
+
+Figure 10-1. The transport policy matrix: which species class moves in which domain, and the gate ladder the 2D surface passes
+
+Figure 10-2. Buildup and washoff on one mesh cell: land-use slices, accrual, sweeping and the mass handed to the network
+
+
 
 ## List of Tables
 
-Table 1-1. SWMM Object Types
+
+
+Table 1-1. Development history of SWMM
+
+Table 1-2. SWMM's modeling objects
+
+Table 1-3. State variables used by SWMM
+
+Table 1-4. Units of expression used by SWMM
+
+Table 2-1. Sources of contaminants in urban storm water runoff (US EPA, 1999)
+
+Table 2-2. Typical pollutant loadings from runoff by urban land use (lbs/acre-yr)
+
+Table 2-3. Median event mean concentrations for urban land uses
+
+Table 2-4. Potency factors for the Detroit metropolitan area (mg/gram) Source: Roesner (1982).
+
+Table 2-5. Potency factors for the Patuxent River Basin (mg/gram) Source: Aqua Terra (1994).
+
+Table 2-6. Representative concentrations of constituents in rainfall
+
+Table 2-7. Average daily dry weather flow in 29 cities Source: ASCE-WPCF (1969)
+
+Table 2-8. Quality properties of untreated domestic wastewater Source: Metcalf and Eddy, Inc. (2003)
+
+Table 2-9. Unit quality loads for domestic sewage, including effects of garbage grinders Source: Haseltine (1950); Metcalf and Eddy et al. (1971a).
+
+Table 2-10. Autumn water use for six homes near Wheaton, MD Source: Tucker (1967).
+
+Table 2-11. Typical hourly DWF correction factors Source: Metcalf and Eddy, Inc. (2003).
+
+Table 2-12. Required temporal detail for receiving water analysis Source: Driscoll (1979) and Hydroscience (1979).
+
+Table 3-1. Measured dust and dirt (DD) accumulation in Chicago Source: APWA (1969).
+
+Table 3-2. Milligrams of pollutant per gram of dust and dirt (parts per thousand by mass) for four Chicago land uses Source: APWA (1969).
+
+Table 3-3. Summary of buildup function coefficients
+
+Table 3-4. Removal efficiencies from street cleaner path for various street cleaning programs (Pitt, 1979)
+
+Table 3-5. Nationwide data on linear dust and dirt buildup rates and on pollutant fractions (after Manning et al., 1977)
+
+Table 4-1. Units of the washoff coefficient *KW* for different washoff models
+
+Table 4-2. Percent removals for vegetated swales and filter strips Source: ASCE (2001).
+
+Table 4-3. Buildup/washoff calibration against annual loading rate for high-density residential land use Source: Tetra Tech (2010).
+
+Table 4-4. National EMC's for stormwater Source: CWP (2003).
+
+Table 4-5. EMC's for different regions Source: CWP (2003)
+
+Table 5-1. Treatment processes used by various types of BMPs
+
+Table 5-2. Median inlet and outlet EMCs for selected stormwater treatment practices
+
+Table 5-3. Median pollutant removal percentages for select stormwater BMPs
+
+Table 5-4. Variables available in treatment expressions
+
+Table 5-5. Math functions available in treatment expressions
 
-Table 2-1. Pollutant Types
+Table 6-1. Design manuals used as sources for LID parameter values
 
-Table 2-2. Land Use Categories
+Table 6-2. Typical ranges for bio-retention cell parameters
 
-Table 3-1. Buildup Parameters
+Table 6-3. Soil characteristics for a typical bio-retention cell soil
 
-Table 4-1. Washoff Parameters
+Table 6-4. Typical ranges for green roof parameters
 
-Table 5-1. Treatment Parameters
+Table 6-5. Typical ranges for infiltration trench parameters
 
-Table 5-4. Variables Available in Treatment Expressions
+Table 6-6. Typical ranges for permeable pavement parameters
 
-Table 5-5. Math Functions Available in Treatment Expressions
+Table 6-7. Typical ranges for vegetative swale parameters
 
-Table 6-1. LID Control Parameters
+
 
 ## Manual Contents
 
@@ -118,5 +238,10 @@ Table 6-1. LID Control Parameters
 - @subpage quality_ref_ch4_surface_washoff — Chapter 4: Surface Washoff
 - @subpage quality_ref_ch5_transport_treatment — Chapter 5: Transport and Treatment
 - @subpage quality_ref_ch6_lid_controls — Chapter 6: Low Impact Development Controls
+- @subpage quality_ref_ch7_ard_transport — Chapter 7: Advection–Reaction–Dispersion Transport
+- @subpage quality_ref_ch8_msx_reactions — Chapter 8: Multi-Species Reactions
+- @subpage quality_ref_ch9_age_heat — Chapter 9: Water Age and Heat Transport
+- @subpage quality_ref_ch10_mesh_quality — Chapter 10: Surface Quality and Transport on the 2D Mesh
+- @subpage quality_ref_ch11_planned — Chapter 11: Planned Formulations
 - @subpage quality_ref_glossary — Glossary
 - @subpage quality_ref_references — References
diff --git a/docs/manuals/reference/quality/SWMM 5 Reference Manual III20160705.md b/docs/manuals/reference/quality/SWMM 5 Reference Manual III20160705.md
deleted file mode 100644
index 526290e98..000000000
--- a/docs/manuals/reference/quality/SWMM 5 Reference Manual III20160705.md	
+++ /dev/null
@@ -1,7414 +0,0 @@
-EPA/600/R-16/093
-
-July 2016
-
-Storm Water Management Model
-
-Reference Manual
-
-Volume III -- Water Quality
-
-By:
-
-Lewis A. Rossman
-
-Office of Research and Development
-
-National Risk Management Laboratory
-
-Cincinnati, OH 45268
-
-and
-
-Wayne C. Huber
-
-School of Civil and Construction Engineering
-
-Oregon State University
-
-Corvallis, OR 97331
-
-National Risk Management Laboratory
-
-Office of Research and Development
-
-U.S. Environmental Protection Agency
-
-26 Martin Luther King Drive
-
-Cincinnati, OH 45268
-
-July 2016
-
-# Disclaimer
-
-The information in this document has been funded wholly or in part by
-the U.S. Environmental Protection Agency (EPA). It has been subjected to
-the Agency's peer and administrative review, and has been approved for
-publication as an EPA document. Mention of trade names or commercial
-products does not constitute endorsement or recommendation for use.
-
-Although a reasonable effort has been made to assure that the results
-obtained are correct, the computer programs described in this manual are
-experimental. Therefore the author and the U.S. Environmental Protection
-Agency are not responsible and assume no liability whatsoever for any
-results or any use made of the results obtained from these programs, nor
-for any damages or litigation that result from the use of these programs
-for any purpose.
-
-# Abstract
-
-SWMM is a dynamic rainfall-runoff simulation model used for single event
-or long-term (continuous) simulation of runoff quantity and quality from
-primarily urban areas. The runoff component of SWMM operates on a
-collection of subcatchment areas that receive precipitation and generate
-runoff and pollutant loads. The routing portion of SWMM transports this
-runoff through a system of pipes, channels, storage/treatment devices,
-pumps, and regulators. SWMM tracks the quantity and quality of runoff
-generated within each subcatchment, and the flow rate, flow depth, and
-quality of water in each pipe and channel during a simulation period
-comprised of multiple time steps. The reference manual for this edition
-of SWMM is comprised of three volumes. Volume I describes SWMM's
-hydrologic models, Volume II its hydraulic models, and Volume III its
-water quality and low impact development models.
-
-# Acknowledgements
-
-This report was written by Lewis A. Rossman, Environmental Scientist
-Emeritus, U.S. Environmental Protection Agency, Cincinnati, OH and Wayne
-C. Huber, Professor Emeritus, School of Civil and Construction
-Engineering, Oregon State University, Corvallis, OR.
-
-The authors would like to acknowledge the contributions made by the
-following individuals to previous versions of SWMM that we drew heavily
-upon in writing this report: John Aldrich, Douglas Ammon, Carl W. Chen,
-Brett Cunningham, Robert Dickinson, James Heaney, Wayne Huber, Miguel
-Medina, Russell Mein, Charles Moore, Stephan Nix, Alan Peltz, Don
-Polmann, Larry Roesner, Lewis Rossman, Charles Rowney, and Robert
-Shubinsky. Finally, we wish to thank Lewis Rossman, Wayne Huber, Thomas
-Barnwell (US EPA retired), Richard Field (US EPA retired), Harry Torno
-(US EPA retired) and William James (University of Guelph) for their
-continuing efforts to support and maintain the program over the past
-several decades.
-
-Portions of this document were prepared under Purchase Order
-2C-R095-NAEX to Oregon State University.
-
-**Table of Contents**
-
-[Disclaimer [ii](#disclaimer)](#disclaimer)
-
-[Abstract [iii](#abstract)](#abstract)
-
-[Acknowledgements [iv](#acknowledgements)](#acknowledgements)
-
-[List of Figures [vii](#list-of-figures)](#list-of-figures)
-
-[List of Tables [viii](#list-of-tables)](#list-of-tables)
-
-[Acronyms and Abbreviations
-[x](#acronyms-and-abbreviations)](#acronyms-and-abbreviations)
-
-[Chapter 1 -- Overview [12](#chapter-1-overview)](#chapter-1-overview)
-
-[1.1 Introduction [12](#introduction)](#introduction)
-
-[1.2 SWMM's Object Model [13](#swmms-object-model)](#swmms-object-model)
-
-[1.3 SWMM's Process Models
-[18](#swmms-process-models)](#swmms-process-models)
-
-[1.4 Simulation Process Overview
-[20](#simulation-process-overview)](#simulation-process-overview)
-
-[1.5 Interpolation and Units
-[24](#interpolation-and-units)](#interpolation-and-units)
-
-[Chapter 2 - Urban Runoff Quality
-[27](#chapter-2---urban-runoff-quality)](#chapter-2---urban-runoff-quality)
-
-[2.1 Introduction [27](#introduction-1)](#introduction-1)
-
-[2.2 Pollutant Sources [29](#pollutant-sources)](#pollutant-sources)
-
-[2.3 Pollutant and Land Use Objects
-[32](#pollutant-and-land-use-objects)](#pollutant-and-land-use-objects)
-
-[2.4 Wet Deposition [35](#wet-deposition)](#wet-deposition)
-
-[2.5 Dry Weather Flow [37](#dry-weather-flow)](#dry-weather-flow)
-
-[2.6 Simulating Runoff Quality
-[42](#simulating-runoff-quality)](#simulating-runoff-quality)
-
-[Chapter 3 - Surface Buildup
-[46](#chapter-3---surface-buildup)](#chapter-3---surface-buildup)
-
-[3.1 Introduction [46](#introduction-2)](#introduction-2)
-
-[3.2 Governing Equations
-[48](#governing-equations)](#governing-equations)
-
-[3.3 Computational Steps
-[53](#computational-steps)](#computational-steps)
-
-[3.4 Street Cleaning [54](#street-cleaning)](#street-cleaning)
-
-[3.5 Parameter Estimates
-[57](#parameter-estimates)](#parameter-estimates)
-
-[Chapter 4 - Surface Washoff
-[62](#chapter-4---surface-washoff)](#chapter-4---surface-washoff)
-
-[4.1 Introduction [62](#introduction-3)](#introduction-3)
-
-[4.2 Governing Equations
-[62](#governing-equations-1)](#governing-equations-1)
-
-[4.3 Computational Steps
-[71](#computational-steps-1)](#computational-steps-1)
-
-[4.4 Parameter Estimates
-[74](#parameter-estimates-1)](#parameter-estimates-1)
-
-[Chapter 5 - Transport and Treatment
-[80](#chapter-5---transport-and-treatment)](#chapter-5---transport-and-treatment)
-
-[5.1 Introduction [80](#introduction-4)](#introduction-4)
-
-[5.2 Governing Equations
-[81](#governing-equations-2)](#governing-equations-2)
-
-[5.3 Computational Steps
-[85](#computational-steps-2)](#computational-steps-2)
-
-[5.4 Treatment [88](#treatment)](#treatment)
-
-[Chapter 6 - Low Impact Development Controls
-[97](#chapter-6---low-impact-development-controls)](#chapter-6---low-impact-development-controls)
-
-[6.1 Introduction [97](#introduction-5)](#introduction-5)
-
-[6.2 Governing Equations
-[99](#governing-equations-3)](#governing-equations-3)
-
-[6.3 LID Deployment [118](#lid-deployment)](#lid-deployment)
-
-[6.4 Computational Steps
-[121](#computational-steps-3)](#computational-steps-3)
-
-[6.5 Parameter Estimates
-[125](#parameter-estimates-2)](#parameter-estimates-2)
-
-[6.6 Numerical Example [136](#numerical-example)](#numerical-example)
-
-[References [141](#references)](#references)
-
-[Glossary [153](#glossary)](#glossary)
-
-**\**
-
-# List of Figures
-
-[**Figure 1‑1 Elements of a typical urban drainage system**
-[14](#_Toc401645527)](#_Toc401645527)
-
-[**Figure 1‑2 SWMM\'s conceptual model of a stormwater drainage system**
-[15](#_Toc401645528)](#_Toc401645528)
-
-[**Figure 1‑3 Processes modeled by SWMM**
-[18](#_Toc401645529)](#_Toc401645529)
-
-[**Figure 1‑4 Block diagram of SWMM\'s state transition process**
-[20](#_Toc401645530)](#_Toc401645530)
-
-[**Figure 1‑5 Flow chart of SWMM\'s simulation procedure**
-[23](#_Toc401645531)](#_Toc401645531)
-
-[**Figure 1‑6 Interpolation of reported values from computed values**
-[25](#_Toc401645532)](#_Toc401645532)
-
-[**Figure 2‑1 Hourly domestic sewage time patterns**
-[41](#_Ref100452456)](#_Ref100452456)
-
-[**Figure 3‑1 Accumulation of solids on urban streets versus time
-(Sartor and Boyd, 1972)** [48](#_Toc454288765)](#_Toc454288765)
-
-[**Figure 3‑2 Buildup of street solids in San Jose (from Pitt, 1979)**
-[49](#_Toc454288766)](#_Toc454288766)
-
-[**Figure 3‑3 Comparison of buildup equations for a hypothetical
-pollutant** [51](#_Toc454288767)](#_Toc454288767)
-
-[**Figure 3‑4 Evolution of buildup after a storm event**
-[53](#_Toc454288768)](#_Toc454288768)
-
-[**Figure 4‑1 Washoff of street solids by flushing with a sprinkler
-system (from Sartor and Boyd, 1972)**
-[63](#_Toc454288769)](#_Toc454288769)
-
-[**Figure 4‑2 Comparison of washoff functions**
-[67](#_Toc454288770)](#_Toc454288770)
-
-[**Figure 4‑3 Two-stream approach to modeling pollutant washoff**
-[69](#_Toc454288771)](#_Toc454288771)
-
-[**Figure 4‑4 Simulated load variations within a storm as a function of
-runoff rate** [75](#_Toc454288772)](#_Toc454288772)
-
-[**Figure 5‑1 Representation of the conveyance network in SWMM**
-[80](#_Toc454288773)](#_Toc454288773)
-
-[**Figure 5‑2 Comparison of completely mixed reactor equations for time
-varying inflow** [84](#_Toc454288774)](#_Toc454288774)
-
-[**Figure 5‑3 Comparison of completely mixed reactor equations for a
-step inflow** [85](#_Toc454288775)](#_Toc454288775)
-
-[**Figure 5‑4 Gravity settling treatment of TSS within a detention
-pond** [96](#_Toc454288776)](#_Toc454288776)
-
-[**Figure 6‑1 A typical bio-retention cell**
-[100](#_Toc454288777)](#_Toc454288777)
-
-[**Figure 6‑2 Flow path across the surface of a green roof**
-[108](#_Toc454288778)](#_Toc454288778)
-
-[**Figure 6‑3 Representation of a permeable pavement system**
-[110](#_Toc454288779)](#_Toc454288779)
-
-[**Figure 6‑4 Representation of rooftop disconnection**
-[114](#_Toc454288780)](#_Toc454288780)
-
-[**Figure 6‑5 Representation of a vegetative swale**
-[116](#_Toc454288781)](#_Toc454288781)
-
-[**Figure 6‑6 Different options for placing LID controls**
-[120](#_Toc454288782)](#_Toc454288782)
-
-[**Figure 6‑7 Storm event used for the LID example**
-[137](#_Toc454288783)](#_Toc454288783)
-
-[**Figure 6‑8 Flux rates through the bio-retention cell with no
-underdrain** [137](#_Toc454288784)](#_Toc454288784)
-
-[**Figure 6‑9 Moisture levels in the bio-retention cell with no
-underdrain** [138](#_Toc454288785)](#_Toc454288785)
-
-[**Figure 6‑10 Moisture levels in the bio-retention cell with
-underdrain** [140](#_Toc454288786)](#_Toc454288786)
-
-[**Figure 6‑11 Flux rates through the bio-retention cell with
-underdrain** [140](#_Toc454288787)](#_Toc454288787)
-
-# List of Tables
-
-[**Table 1‑1 Development history of SWMM**
-[13](#_Toc454288788)](#_Toc454288788)
-
-[**Table 1‑2 SWMM\'s modeling objects**
-[16](#_Toc401645586)](#_Toc401645586)
-
-[**Table 1‑3 State variables used by SWMM**
-[21](#_Toc401645587)](#_Toc401645587)
-
-[**Table 1‑4 Units of expression used by SWMM**
-[26](#_Toc401645588)](#_Toc401645588)
-
-[**Table 2‑1 Sources of contaminants in urban storm water runoff (US
-EPA, 1999)** [27](#_Toc454288792)](#_Toc454288792)
-
-[**Table 2‑2 Typical pollutant loadings from runoff by urban land use
-(lbs/acre-yr)** [28](#_Toc454288793)](#_Toc454288793)
-
-[**Table 2‑3 Median event mean concentrations for urban land uses**
-[29](#_Toc454288794)](#_Toc454288794)
-
-[**Table 2‑4 Potency factors for the Detroit metropolitan area
-(mg/gram)** [34](#_Toc454288795)](#_Toc454288795)
-
-[**Table 2‑5 Potency factors for the Patuxent River Basin (mg/gram)**
-[34](#_Toc454288796)](#_Toc454288796)
-
-[**Table 2‑6 Representative concentrations of constituents in rainfall**
-[36](#_Toc454288797)](#_Toc454288797)
-
-[**Table 2‑7 Average daily dry weather flow in 29 cities**
-[38](#_Toc454288798)](#_Toc454288798)
-
-[**Table 2‑8 Quality properties of untreated domestic wastewater**
-[39](#_Toc454288799)](#_Toc454288799)
-
-[**Table 2‑9 Unit quality loads for domestic sewage, including effects
-of garbage grinders** [40](#_Toc454288800)](#_Toc454288800)
-
-[**Table 2‑10 Autumn water use for six homes near Wheaton, MD**
-[41](#_Toc454288801)](#_Toc454288801)
-
-[**Table 2‑11 Typical hourly DWF correction factors**
-[42](#_Toc454288802)](#_Toc454288802)
-
-[**Table 2‑12 Required temporal detail for receiving water analysis**
-[44](#_Toc454288803)](#_Toc454288803)
-
-[**Table 3‑1 Measured dust and dirt (DD) accumulation in Chicago**
-[46](#_Toc454288804)](#_Toc454288804)
-
-[**Table 3‑2 Milligrams of pollutant per gram of dust and dirt (parts
-per thousand by mass) for four Chicago land uses**
-[47](#_Toc454288805)](#_Toc454288805)
-
-[**Table 3‑3 Summary of buildup function coefficients**
-[51](#_Toc454288806)](#_Toc454288806)
-
-[**Table 3‑4 Removal efficiencies from street cleaner path for various
-street cleaning programs (Pitt, 1979)**
-[56](#_Toc454288807)](#_Toc454288807)
-
-[**Table 3‑5 Nationwide data on linear dust and dirt buildup rates and
-on pollutant fractions (after Manning et al., 1977)**
-[59](#_Toc454288808)](#_Toc454288808)
-
-[**Table 4‑1 Units of the washoff coefficient *KW* for different
-washoff models** [66](#_Toc454288809)](#_Toc454288809)
-
-[**Table 4‑2 Percent removals for vegetated swales and filter strips**
-[70](#_Toc454288810)](#_Toc454288810)
-
-[**Table 4‑3 Buildup/washoff calibration against annual loading rate for
-high-density residential land use**
-[76](#_Toc454288811)](#_Toc454288811)
-
-[**Table 4‑4 National EMC\'s for stormwater**
-[78](#_Toc454288812)](#_Toc454288812)
-
-[**Table 4‑5 EMC\'s for different regions**
-[79](#_Toc454288813)](#_Toc454288813)
-
-[**Table 5‑1 Treatment processes used by various types of BMPs**
-[89](#_Toc454288814)](#_Toc454288814)
-
-[**Table 5‑2 Median inlet and outlet EMCs for selected stormwater
-treatment practices** [90](#_Toc454288815)](#_Toc454288815)
-
-[**Table 5‑3 Median pollutant removal percentages for select stormwater
-BMPs** [91](#_Toc454288816)](#_Toc454288816)
-
-[**Table 6‑1 Design manuals used as sources for LID parameter values**
-[126](#_Toc454288817)](#_Toc454288817)
-
-[**Table 6‑2 Typical ranges for bio-retention cell parameters**
-[127](#_Toc454288818)](#_Toc454288818)
-
-[**Table 6‑3 Soil characteristics for a typical bio-retention cell
-soil** [127](#_Toc454288819)](#_Toc454288819)
-
-[**Table 6‑4 Typical ranges for green roof parameters**
-[128](#_Toc454288820)](#_Toc454288820)
-
-[**Table 6‑5 Typical ranges for infiltration trench parameters**
-[129](#_Toc454288821)](#_Toc454288821)
-
-[**Table 6‑6 Typical ranges for permeable pavement parameters**
-[130](#_Toc454288822)](#_Toc454288822)
-
-[**Table 6‑7 Typical ranges for vegetative swale parameters**
-[132](#_Toc454288823)](#_Toc454288823)
-
-# Acronyms and Abbreviations
-
-APWA American Public Works Association
-
-ASCE American Society of Civil Engineers
-
-BMP Best Management Practice
-
-BOD Biochemical Oxygen Demand
-
-BOD5 Five-Day Biochemical Oxygen Demand
-
-C Carbon
-
-Cd Cadmium
-
-COD Chemical Oxygen Demand
-
-COV Coefficient of Variation
-
-Cr Chromium
-
-CSO Combined Sewer Overflow
-
-Cu Copper
-
-DCIA Directly Connected Impervious Area
-
-DD Dust and Dirt
-
-DWF Dry Weather Flow
-
-EMC Event Mean Concentration
-
-EPA Environmental Protection Agency
-
-ET Evapotranspiration
-
-Fe Iron
-
-GI Green Infrastructure
-
-IMP Integrated Management Practice
-
-JTU Jackson Turbidity Units
-
-LID Low Impact Development
-
-Mn Manganese
-
-MPN Most Probable Number
-
-MTBE Methyl Tertiary Butyl Ether
-
-NADP National Atmospheric Deposition Program
-
-NH3-N Ammonia Nitrogen
-
-NH4 Ammonium
-
-Ni Nickel
-
-NO2 Nitrite
-
-NO3 Nitrate
-
-NPDES National Pollution Discharge Elimination System
-
-NURP National Urban Runoff Program
-
-PAH Polycyclic Aromatic Hydrocarbons
-
-Pb Lead
-
-PCU Platinum-Cobalt Units
-
-PO4 Phosphate
-
-RDII Rainfall Dependent Inflow and Infiltration
-
-Sr Strontium
-
-SCM Stormwater Control Measure
-
-SUDS Sustainable Urban Drainage Systems
-
-SWMM Storm Water Management Model
-
-TDS Total Dissolved Solids
-
-TKN Total Kjeldahl Nitrogen
-
-TN Total Nitrogen
-
-TOC Total Organic Carbon
-
-TP Total Phosphorus
-
-TPH Total Petroleum Hydrocarbons
-
-TSS Total Suspended Solids
-
-UK United Kingdom
-
-USGS United States Geological Survey
-
-VOC Volatile Organic Carbon
-
-WPCF Water Pollution Control Federation
-
-WWTP Waste Water Treatment Plant
-
-Zn Zinc
-
-# Chapter 1 -- Overview
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 1.1 Introduction
-
-Urban runoff quantity and quality constitute problems of both a
-historical and current nature. Cities have long assumed the
-responsibility of control of stormwater flooding and treatment of point
-sources (e.g., municipal sewage) of wastewater. Since the 1960s, the
-severe pollution potential of urban nonpoint sources, principally
-combined sewer overflows and stormwater discharges, has been recognized,
-both through field observation and federal legislation. The advent of
-modern computers has led to the development of complex, sophisticated
-tools for analysis of both quantity and quality pollution problems in
-urban areas and elsewhere (Singh, 1995). The EPA Storm Water Management
-Model, SWMM, first developed in 1969-71, was one of the first such
-models. It has been continually maintained and updated and is perhaps
-the best known and most widely used of the available urban runoff
-quantity/quality models (Huber and Roesner, 2013).
-
-SWMM is a dynamic rainfall-runoff simulation model used for single event
-or long-term (continuous) simulation of runoff quantity and quality from
-primarily urban areas. The runoff component of SWMM operates on a
-collection of subcatchment areas that receive precipitation and generate
-runoff and pollutant loads. The routing portion of SWMM transports this
-runoff through a system of pipes, channels, storage/treatment devices,
-pumps, and regulators. SWMM tracks the quantity and quality of runoff
-generated within each subcatchment, and the flow rate, flow depth, and
-quality of water in each pipe and channel during a simulation period
-comprised of multiple time steps.
-
-Table 1-1 summarizes the development history of SWMM. The current
-edition, Version 5, is a complete re-write of the previous releases. The
-reference manual for this edition of SWMM is comprised of three volumes.
-Volume I describes SWMM's hydrologic models, Volume II its hydraulic
-models, and Volume III its water quality and low impact development
-models. These manuals complement the SWMM 5 User's Manual (US EPA,
-2010), which explains how to run the program, and the SWMM 5
-Applications Manual (US EPA, 2009) which presents a number of worked-out
-examples. The procedures described in this reference manual are based on
-earlier descriptions included in the original SWMM documentation
-(Metcalf and Eddy et al., 1971a, 1971b, 1971c, 1971d), intermediate
-reports (Huber et al., 1975; Heaney et al., 1975; Huber et al., 1981b),
-plus new material. This information supersedes the Version 4.0
-documentation (Huber and Dickinson, 1988; Roesner et al., 1988) and
-includes descriptions of some newer procedures implemented since 1988.
-More information on current documentation and the general status of the
-EPA Storm Water Management Model as well as the full program and its
-source code is available on the EPA SWMM web site:.
-.
-
-+----------------+----------+--------------------+-----------------------+
-| **Version**    | **Year** | **Contributors**   | **Comments**          |
-+:===============+:=========+:===================+:======================+
-| SWMM I         | 1971     | Metcalf & Eddy,    | First version of      |
-|                |          | Inc.               | SWMM; written in      |
-|                |          |                    | FORTRAN, its focus    |
-|                |          | Water Resources    | was CSO modeling; Few |
-|                |          | Engineers          | of its methods are    |
-|                |          |                    | still used today.     |
-|                |          | University of      |                       |
-|                |          | Florida            |                       |
-+----------------+----------+--------------------+-----------------------+
-| SWMM II        | 1975     | University of      | First widely          |
-|                |          | Florida            | distributed version   |
-|                |          |                    | of SWMM.              |
-+----------------+----------+--------------------+-----------------------+
-| SWMM 3         | 1981     | University of      | Full dynamic wave     |
-|                |          | Florida            | flow routine,         |
-|                |          |                    | Green-Ampt            |
-|                |          | Camp Dresser &     | infiltration, snow    |
-|                |          | McKee              | melt, and continuous  |
-|                |          |                    | simulation added.     |
-+----------------+----------+--------------------+-----------------------+
-| SWMM 3.3       | 1983     | US EPA             | First PC version of   |
-|                |          |                    | SWMM.                 |
-+----------------+----------+--------------------+-----------------------+
-| SWMM 4         | 1988     | Oregon State       | Groundwater, RDII,    |
-|                |          | University         | irregular channel     |
-|                |          |                    | cross-sections and    |
-|                |          | Camp Dresser &     | other refinements     |
-|                |          | McKee              | added over a series   |
-|                |          |                    | of updates throughout |
-|                |          |                    | the 1990's.           |
-+----------------+----------+--------------------+-----------------------+
-| SWMM 5         | 2005     | US EPA             | Complete re-write of  |
-|                |          |                    | the SWMM engine in C; |
-|                |          | CDM-Smith          | graphical user        |
-|                |          |                    | interface added;      |
-|                |          |                    | improved algorithms   |
-|                |          |                    | and new features      |
-|                |          |                    | (e.g., LID modeling)  |
-|                |          |                    | added.                |
-+----------------+----------+--------------------+-----------------------+
-
-: []{#_Toc454288788 .anchor}**Table 1‑1 Development history of SWMM**
-
-## 1.2 SWMM's Object Model
-
-Figure 1-1 depicts the elements included in a typical urban drainage
-system. SWMM conceptualizes this system as a series of water and
-material flows between several major environmental compartments. These
-compartments include:
-
-

-
-
Figure 1‑1 Elements of a typical urban
-drainage system

-

-
-- The Atmosphere compartment, which generates precipitation and deposits
-  pollutants onto the Land Surface compartment.
-
-- The Land Surface compartment receives precipitation from the
-  Atmosphere compartment in the form of rain or snow. It sends outflow
-  in the forms of 1) evaporation back to the Atmosphere compartment, 2)
-  infiltration into the Sub-Surface compartment and 3) surface runoff
-  and pollutant loadings on to the Conveyance compartment.
-
-- The Sub-Surface compartment receives infiltration from the Land
-  Surface compartment and transfers a portion of this inflow to the
-  Conveyance compartment as lateral groundwater flow.
-
-- The Conveyance compartment contains a network of elements (channels,
-  pipes, pumps, and regulators) and storage/treatment units that convey
-  water to outfalls or to treatment facilities. Inflows to this
-  compartment can come from surface runoff, groundwater flow, sanitary
-  dry weather flow, or from user-defined time series.
-
-Not all compartments need appear in a particular SWMM model. For
-example, one could model just the Conveyance compartment, using
-pre-defined hydrographs and pollutographs as inputs. As illustrated in
-Figure 1-1, SWMM can be used to model any combination of stormwater
-collection systems, both separate and combined sanitary sewer systems,
-as well as natural catchment and river channel systems.
-
-Figure 1-2 shows how SWMM conceptualizes the physical elements of the
-actual system depicted in Figure 1-1 with a standard set of modeling
-objects. The principal objects used to model the rainfall/runoff process
-are Rain Gages and Subcatchments. Snowmelt is modeled with Snow Pack
-objects placed on top of subcatchments while Aquifer objects placed
-below subcatchments are used to model groundwater flow. The conveyance
-portion of the drainage system is modeled with a network of Nodes and
-Links. Nodes are points that represent simple junctions, flow dividers,
-storage units, or outfalls. Links connect nodes to one another with
-conduits (pipes and channels), pumps, or flow regulators (orifices,
-weirs, or outlets). Land Use and Pollutant objects are used to describe
-water quality. Finally, a group of data objects that includes Curves,
-Time Series, Time Patterns, and Control Rules, are used to characterize
-the inflows and operating behavior of the various physical objects in a
-SWMM model. Table 1-2 provides a summary of the various objects used in
-SWMM. Their properties and functions will be described in more detail
-throughout the course of this manual.
-
-

-Objects2
-
Figure 1‑2 SWMM's conceptual model of a
-stormwater drainage system

-

-
-+--------------+---------------+--------------------------------------+
-| **Category** | **Object      | **Description**                      |
-|              | Type**        |                                      |
-+:=============+:==============+:=====================================+
-| Hydrology    | Rain Gage     | Source of precipitation data to one  |
-|              |               | or more subcatchments.               |
-|              +---------------+--------------------------------------+
-|              | Subcatchment  | A land parcel that receives          |
-|              |               | precipitation associated with a rain |
-|              |               | gage and generates runoff that flows |
-|              |               | into a drainage system node or to    |
-|              |               | another subcatchment.                |
-|              +---------------+--------------------------------------+
-|              | Aquifer       | A subsurface area that receives      |
-|              |               | infiltration from the subcatchment   |
-|              |               | above it and exchanges groundwater   |
-|              |               | flow with a conveyance system node.  |
-|              +---------------+--------------------------------------+
-|              | Snow Pack     | Accumulated snow that covers a       |
-|              |               | subcatchment.                        |
-|              +---------------+--------------------------------------+
-|              | Unit          | A response function that describes   |
-|              | Hydrograph    | the amount of sewer                  |
-|              |               | inflow/infiltration generated over   |
-|              |               | time per unit of instantaneous       |
-|              |               | rainfall.                            |
-+--------------+---------------+--------------------------------------+
-| Hydraulics   | Junction      | A point in the conveyance system     |
-|              |               | where conduits connect to one        |
-|              |               | another with negligible storage      |
-|              |               | volume (e.g., manholes, pipe         |
-|              |               | fittings, or stream junctions).      |
-|              +---------------+--------------------------------------+
-|              | Outfall       | An end point of the conveyance       |
-|              |               | system where water is discharged to  |
-|              |               | a receptor (such as a receiving      |
-|              |               | stream or treatment plant) with      |
-|              |               | known water surface elevation.       |
-|              +---------------+--------------------------------------+
-|              | Divider       | A point in the conveyance system     |
-|              |               | where the inflow splits into two     |
-|              |               | outflow conduits according to a      |
-|              |               | known relationship.                  |
-|              +---------------+--------------------------------------+
-|              | Storage Unit  | A pond, lake, impoundment, or        |
-|              |               | chamber that provides water storage. |
-|              +---------------+--------------------------------------+
-|              | Conduit       | A channel or pipe that conveys water |
-|              |               | from one conveyance system node to   |
-|              |               | another.                             |
-|              +---------------+--------------------------------------+
-|              | Pump          | A device that raises the hydraulic   |
-|              |               | head of water.                       |
-|              +---------------+--------------------------------------+
-|              | Regulator     | A weir, orifice or outlet used to    |
-|              |               | direct and regulate flow between two |
-|              |               | nodes of the conveyance system.      |
-+--------------+---------------+--------------------------------------+
-
-: []{#_Toc401645586 .anchor}**Table 1‑2 SWMM\'s modeling objects**
-
-**Table 1-2 SWMM's modeling objects (continued)**
-
-+--------------+---------------+--------------------------------------+
-| **Category** | **Object      | **Description**                      |
-|              | Type**        |                                      |
-+:=============+:==============+:=====================================+
-| Water        | Pollutant     | A contaminant that can build up and  |
-| Quality      |               | be washed off of the land surface or |
-|              |               | be introduced directly into the      |
-|              |               | conveyance system.                   |
-|              +---------------+--------------------------------------+
-|              | Land Use      | A classification used to             |
-|              |               | characterize the functions that      |
-|              |               | describe pollutant buildup and       |
-|              |               | washoff.                             |
-+--------------+---------------+--------------------------------------+
-| Treatment    | LID Control   | A low impact development control,    |
-|              |               | such as a bio-retention cell, porous |
-|              |               | pavement, or vegetative swale, used  |
-|              |               | to reduce surface runoff through     |
-|              |               | enhanced infiltration.               |
-|              +---------------+--------------------------------------+
-|              | Treatment     | A user-defined function that         |
-|              | Function      | describes how pollutant              |
-|              |               | concentrations are reduced at a      |
-|              |               | conveyance system node as a function |
-|              |               | of certain variables, such as        |
-|              |               | concentration, flow rate, water      |
-|              |               | depth, etc.                          |
-+--------------+---------------+--------------------------------------+
-| Data Object  | Curve         | A tabular function that defines the  |
-|              |               | relationship between two quantities  |
-|              |               | (e.g., flow rate and hydraulic head  |
-|              |               | for a pump, surface area and depth   |
-|              |               | for a storage node, etc.).           |
-|              +---------------+--------------------------------------+
-|              | Time Series   | A tabular function that describes    |
-|              |               | how a quantity varies with time      |
-|              |               | (e.g., rainfall, outfall surface     |
-|              |               | elevation, etc.).                    |
-|              +---------------+--------------------------------------+
-|              | Time Pattern  | A set of factors that repeats over a |
-|              |               | period of time (e.g., diurnal hourly |
-|              |               | pattern, weekly daily pattern,       |
-|              |               | etc.).                               |
-|              +---------------+--------------------------------------+
-|              | Control Rules | IF-THEN-ELSE statements that         |
-|              |               | determine when specific control      |
-|              |               | actions are taken (e.g., turn a pump |
-|              |               | on or off when the flow depth at a   |
-|              |               | given node is above or below a       |
-|              |               | certain value).                      |
-+--------------+---------------+--------------------------------------+
-
-## 1.3 SWMM's Process Models
-
-Figure 1-3 depicts the processes that SWMM models using the objects
-described previously and how they are tied to one another. The
-hydrological processes depicted in this diagram include:
-
-

-ProcessModels.png
-
Figure 1‑3 Processes modeled by
-SWMM

-

-
-- time-varying precipitation
-
-- snow accumulation and melting
-
-- rainfall interception from depression storage (initial abstraction)
-
-- evaporation of standing surface water
-
-- infiltration of rainfall into unsaturated soil layers
-
-- percolation of infiltrated water into groundwater layers
-
-- interflow between groundwater and the drainage system
-
-- nonlinear reservoir routing of overland flow
-
-- infiltration and evaporation of rainfall/runoff captured by Low Impact
-  Development controls.
-
-The hydraulic processes occurring within SWMM's conveyance compartment
-include:
-
-- external inflow of surface runoff, groundwater interflow,
-  rainfall-dependent infiltration/inflow, dry weather sanitary flow, and
-  user-defined inflows
-
-- unsteady, non-uniform flow routing through any configuration of open
-  channels, pipes and storage units
-
-- various possible flow regimes such as backwater, surcharging, reverse
-  flow, and surface ponding
-
-- flow regulation via pumps, weirs, and orifices including time- and
-  state-dependent control rules that govern their operation.
-
-Regarding water quality, the following processes can be modeled for any
-number of user-defined water quality constituents:
-
-- dry-weather pollutant buildup over different land uses
-
-- pollutant washoff from specific land uses during storm events
-
-- direct contribution of rainfall deposition
-
-- reduction in dry-weather buildup due to street cleaning
-
-- reduction in washoff loads due to BMPs
-
-- entry of dry weather sanitary flows and user-specified external
-  inflows at any point in the drainage system
-
-- routing of water quality constituents through the drainage system
-
-- reduction in constituent concentration through treatment in storage
-  units or by natural processes in pipes and channels.
-
-The numerical procedures that SWMM uses to model the water quality
-processes listed above as well as Low Impact Development practices are
-discussed in detail in subsequent chapters of this volume. SWMM's
-hydrologic and hydraulic processes are described in volumes I and II of
-this manual.
-
-## 1.4 Simulation Process Overview
-
-SWMM is a distributed discrete time simulation model. It computes new
-values of its state variables over a sequence of time steps, where at
-each time step the system is subjected to a new set of external inputs.
-As its state variables are updated, other output variables of interest
-are computed and reported. This process is represented mathematically
-with the following general set of equations that are solved at each time
-step as the simulation unfolds:
-
-$$X_{t} = f(X_{t - 1},I_{t},P) \qquad \text{(1-1)}$$
-
-$$Y_{t} = g(X_{t},P) \qquad \text{(1-2)}$$
-
-where
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *Xt* | = | a vector of state variables at time *t*, |
-| *Yt* | = | a vector of output variables at time *t*, |
-| *It* | = | a vector of inputs at time *t*, |
-| *P* | = | a vector of constant parameters, |
-| *f* | = | a vector-valued state transition function, |
-| *g* | = | a vector-valued output transform function, |
-
-Figure 1-4 depicts the simulation process in block diagram fashion.
-
-

-
-
Figure 1‑4 Block diagram of SWMM's state
-transition process

-

-
-The variables that make up the state vector *Xt* are listed in Table
-1-3. This is a surprisingly small number given the comprehensive nature
-of SWMM. All other quantities can be computed from these variables,
-external inputs, and fixed input parameters. The meaning of some of the
-less obvious state variables, such as those used for snow melt, is
-discussed in other sections of this set of manuals.
-
-+----------------+--------------+---------------------------------+------------+
-| **Process**    | **Variable** | **Description**                 | **Initial  |
-|                |              |                                 | Value**    |
-+:===============+:=============+:================================+:===========+
-| Runoff         | *d*          | Depth of runoff on a            | 0          |
-|                |              | subcatchment surface            |            |
-+----------------+--------------+---------------------------------+------------+
-| Infiltration\* | *tp*       | Equivalent time on the Horton   | 0          |
-|                |              | curve                           |            |
-|                +--------------+---------------------------------+------------+
-|                | *Fe*       | Cumulative excess infiltration  | 0          |
-|                |              | volume                          |            |
-|                +--------------+---------------------------------+------------+
-|                | *Fu*         | Upper zone moisture content     | 0          |
-|                +--------------+---------------------------------+------------+
-|                | *T*          | Time until the next rainfall    | 0          |
-|                |              | event                           |            |
-|                +--------------+---------------------------------+------------+
-|                | *P*          | Cumulative rainfall for current | 0          |
-|                |              | event                           |            |
-|                +--------------+---------------------------------+------------+
-|                | *S*          | Soil moisture storage capacity  | User       |
-|                |              | remaining                       | supplied   |
-+----------------+--------------+---------------------------------+------------+
-| Groundwater    | *θu*       | Unsaturated zone moisture       | User       |
-|                |              | content                         | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *dL*       | Depth of saturated zone         | User       |
-|                |              |                                 | supplied   |
-+----------------+--------------+---------------------------------+------------+
-| Snowmelt       | *wsnow*      | Snow pack depth                 | User       |
-|                |              |                                 | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *fw*         | Snow pack free water depth      | User       |
-|                |              |                                 | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *ati*        | Snow pack surface temperature   | User       |
-|                |              |                                 | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *cc*         | Snow pack cold content          | 0          |
-+----------------+--------------+---------------------------------+------------+
-| Flow Routing   | *y*          | Depth of water at a node        | User       |
-|                |              |                                 | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *q*          | Flow rate in a link             | User       |
-|                |              |                                 | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *a*          | Flow area in a link             | Inferred   |
-|                |              |                                 | from *q*   |
-+----------------+--------------+---------------------------------+------------+
-| Water Quality  | *tsweep*   | Time since a subcatchment was   | User       |
-|                |              | last swept                      | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *mB*       | Pollutant buildup on            | User       |
-|                |              | subcatchment surface            | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *mP*       | Pollutant mass ponded on        | 0          |
-|                |              | subcatchment                    |            |
-|                +--------------+---------------------------------+------------+
-|                | *cN*       | Concentration of pollutant at a | User       |
-|                |              | node                            | supplied   |
-|                +--------------+---------------------------------+------------+
-|                | *cL*       | Concentration of pollutant in a | User       |
-|                |              | link                            | supplied   |
-+----------------+--------------+---------------------------------+------------+
-
-: []{#_Toc401645587 .anchor}**Table 1‑3 State variables used by SWMM**
-
-\*Only a sub-set of these variables is used, depending on the user's
-choice of infiltration method.
-
-Examples of user-supplied input variables *It* that produce changes to
-these state variables include:
-
-- meteorological conditions, such as precipitation, air temperature,
-  evaporation rate and wind speed
-
-- externally imposed inflow hydrographs and pollutographs at specific
-  nodes of the conveyance system
-
-- dry weather sanitary inflows to specific nodes of the conveyance
-  system
-
-- water surface elevations at specific outfalls of the conveyance system
-
-- control settings for pumps and regulators.
-
-The output vector *Yt* that SWMM computes from its updated state
-variables contains such reportable quantities as:
-
-- runoff flow rate and pollutant concentrations from each subcatchment
-
-- snow depth, infiltration rate and evaporation losses from each
-  subcatchment
-
-- groundwater table elevation and lateral groundwater outflow for each
-  subcatchment
-
-- total lateral inflow (from runoff, groundwater flow, dry weather flow,
-  etc.), water depth, and pollutant concentration for each conveyance
-  system node
-
-- overflow rate and ponded volume at each flooded node
-
-- flow rate, velocity, depth and pollutant concentration for each
-  conveyance system link.
-
-Regarding the constant parameter vector *P,* SWMM contains over 150
-different user-supplied constants and coefficients within its collection
-of process models. Most of these are either physical dimensions (e.g.,
-land areas, pipe diameters, invert elevations) or quantities that can be
-obtained from field observation (e.g., percent impervious cover),
-laboratory testing (e.g., various soil properties), or previously
-published data tables (e.g., pipe roughness based on pipe material). A
-smaller remaining number might require some degree of model calibration
-to determine their proper values. Of course not all parameters are
-required for every project (e.g., the 14 groundwater parameters for each
-subcatchment are not needed if groundwater is not being modeled). The
-subsequent chapters of this manual carefully define each parameter and
-make suggestions on how to estimate its value.
-
-A flowchart of the overall simulation process is shown in Figure 1-5.
-The process begins by reading a description of each object and its
-parameters from an input file whose format is described in the SWMM 5
-Users' Manual (US EPA, 2010). Next the values of all state variables are
-initialized, as is the current simulation time (T), runoff time
-(Troff), and reporting time (Trpt).
-
-

-
-
Figure 1‑5 Flow chart of SWMM's simulation
-procedure

-

-
-The program then enters a loop that first determines the time T1 at the
-end of the current routing time step (∆Trout). If the current runoff
-time Troff is less than T1, then new runoff calculations are
-repeatedly made and the runoff time updated until it equals or exceeds
-time T1. Each set of runoff calculations accounts for any precipitation,
-evaporation, snowmelt, infiltration, ground water seepage, overland
-flow, and pollutant buildup and washoff that can contribute flow and
-pollutant loads into the conveyance system.
-
-Once the runoff time is current, all inflows and pollutant loads
-occurring at time T are routed through the conveyance system over the
-time interval from T to T1. This process updates the flow, depth and
-velocity in each conduit, the water elevation at each node, the pumping
-rate for each pump, and the water level and volume in each storage unit.
-In addition, new values for the concentrations of all pollutants at each
-node and within each conduit are computed. Next a check is made to see
-if the current reporting time Trpt falls within the interval from T to
-T1. If it does, then a new set of output results at time Trpt are
-interpolated from the results at times T and T1 and are saved to an
-output file. The reporting time is also advanced by the reporting time
-step ∆Trpt. The simulation time T is then updated to T1 and the
-process continues until T reaches the desired total duration. SWMM's
-Windows-based user interface provides graphical tools for building the
-aforementioned input file and for viewing the computed output.
-
-## 1.5 Interpolation and Units
-
-SWMM uses linear interpolation to obtain values for quantities at times
-that fall in between times at which input time series are recorded or at
-which output results are computed. The concept is illustrated in Figure
-1-6 which shows how reported flow values are derived from the computed
-flow values on either side of it for the typical case where the
-reporting time step is larger than the routing time step. One exception
-to this convention is for precipitation and infiltration rates. These
-remain constant within a runoff time step and no interpolation is made
-when these values are used within SWMM's runoff algorithms or for
-reporting purposes. In other words, if a reporting time falls within a
-runoff time step the reported rainfall intensity is the value associated
-with the start of the runoff time step.
-
-![[]{#_Toc401645532 .anchor}**Figure 1‑6 Interpolation of reported
-values from computed
-values**](./media/media/image6.emf){width="6.1097222222222225in"
-height="3.4194444444444443in"}
-
-The units of expression used by SWMM's input variables, parameters, and
-output variables depend on the user's choice of flow units. If flow rate
-is expressed in US customary units then so are all other quantities; if
-SI metric units are used for flow rate then all other quantities use SI
-metric units. Table 1-4 lists the units associated with each of SWMM's
-major variables and parameters, for both US and SI systems. Internally
-within the computer code all calculations are carried out using feet as
-the unit of length and seconds as the unit of time.
-
-[]{#_Toc401645588 .anchor}**Table 1‑4 Units of expression used by SWMM**
-
-+------------------------+----------------------+----------------------+
-| **Variable or          | **US Customary       | **SI Metric Units**  |
-| Parameter**            | Units**              |                      |
-+:=======================+:=====================+:=====================+
-| Area (subcatchment)    | acres                | hectares             |
-+------------------------+----------------------+----------------------+
-| Area (storage surface  | square feet          | square meters        |
-| area)                  |                      |                      |
-+------------------------+----------------------+----------------------+
-| Depression Storage     | inches               | millimeters          |
-+------------------------+----------------------+----------------------+
-| Depth                  | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Elevation              | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Evaporation            | inches/day           | millimeters/day      |
-+------------------------+----------------------+----------------------+
-| Flow Rate              | cubic feet/sec (cfs) | cubic meters/sec     |
-|                        |                      | (cms)                |
-|                        | gallons/min (gpm)    |                      |
-|                        |                      | liters/sec (lps)     |
-|                        | 106 gallons/day    |                      |
-|                        | (mgd)                | 106 liters/day     |
-|                        |                      | (mld)                |
-+------------------------+----------------------+----------------------+
-| Hydraulic Conductivity | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Hydraulic Head         | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Infiltration Rate      | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Length                 | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Manning's n            | seconds/meter1/3   | seconds/meter1/3   |
-+------------------------+----------------------+----------------------+
-| Pollutant Buildup      | mass/acre            | mass/hectare         |
-+------------------------+----------------------+----------------------+
-| Pollutant              | milligrams/liter     | milligrams/liter     |
-| Concentration          | (mg/L)               | (mg/L)               |
-|                        |                      |                      |
-|                        | micrograms/liter     | micrograms/liter     |
-|                        | (μg/L)               | (μg/L)               |
-|                        |                      |                      |
-|                        | organism             | organism             |
-|                        | counts/liter         | counts/liter         |
-+------------------------+----------------------+----------------------+
-| Rainfall Intensity     | inches/hour          | millimeters/hour     |
-+------------------------+----------------------+----------------------+
-| Rainfall Volume        | inches               | millimeters          |
-+------------------------+----------------------+----------------------+
-| Storage Volume         | cubic feet           | cubic meters         |
-+------------------------+----------------------+----------------------+
-| Temperature            | degrees Fahrenheit   | degrees Celsius      |
-+------------------------+----------------------+----------------------+
-| Velocity               | feet/second          | meters/second        |
-+------------------------+----------------------+----------------------+
-| Width                  | feet                 | meters               |
-+------------------------+----------------------+----------------------+
-| Wind Speed             | miles/hour           | kilometers/hour      |
-+------------------------+----------------------+----------------------+
-
-# Chapter 2 - Urban Runoff Quality
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 2.1 Introduction
-
-Storm water runoff from urbanized areas can contain significant
-concentrations of harmful pollutants that can contribute to adverse
-water quality impacts in receiving streams. Effects can include such
-things as beach closures, shellfish bed closures, limits on fishing and
-limits on recreational contact in waters that receive storm water
-discharges.
-
-Contaminants enter storm water from a variety of sources in the urban
-landscape. The major sources include residential and commercial areas,
-industrial activities, construction, streets and parking lots, and
-atmospheric deposition. Contaminants commonly found in storm water
-runoff and their likely sources are summarized in Table 2-1. Table 2-2
-lists typical pollutant loadings from different urban land uses.
-
-+-----------------------------------+-----------------------------------+
-| **Contaminant**                   | **Contaminant Sources**           |
-+===================================+===================================+
-| Sediment and Floatables           | Streets, lawns, driveways, roads, |
-|                                   | construction                      |
-|                                   |                                   |
-|                                   | activities, atmospheric           |
-|                                   | deposition, drainage              |
-|                                   |                                   |
-|                                   | channel erosion                   |
-+-----------------------------------+-----------------------------------+
-| Pesticides and Herbicides         | Residential lawns and gardens,    |
-|                                   | roadsides,                        |
-|                                   |                                   |
-|                                   | utility right-of-ways, commercial |
-|                                   | and                               |
-|                                   |                                   |
-|                                   | industrial landscaped areas, soil |
-|                                   | wash-off                          |
-+-----------------------------------+-----------------------------------+
-| Organic Materials                 | Residential lawns and gardens,    |
-|                                   | commercial                        |
-|                                   |                                   |
-|                                   | landscaping, animal wastes        |
-+-----------------------------------+-----------------------------------+
-| Metals                            | Automobiles, bridges, atmospheric |
-|                                   | deposition,                       |
-|                                   |                                   |
-|                                   | industrial areas, soil erosion,   |
-|                                   | corroding metal                   |
-|                                   |                                   |
-|                                   | surfaces, combustion processes    |
-+-----------------------------------+-----------------------------------+
-| Oil and Grease / Hydrocarbons     | Roads, driveways, parking lots,   |
-|                                   | vehicle                           |
-|                                   |                                   |
-|                                   | maintenance areas, gas stations,  |
-|                                   | illicit                           |
-|                                   |                                   |
-|                                   | dumping to storm drains           |
-+-----------------------------------+-----------------------------------+
-| Bacteria and Viruses              | Lawns, roads, leaky sanitary      |
-|                                   | sewer lines,                      |
-|                                   |                                   |
-|                                   | sanitary sewer cross-connections, |
-|                                   | animal                            |
-|                                   |                                   |
-|                                   | waste, septic systems             |
-+-----------------------------------+-----------------------------------+
-| Nitrogen and Phosphorus           | Lawn fertilizers, atmospheric     |
-|                                   | deposition,                       |
-|                                   |                                   |
-|                                   | automobile exhaust, soil erosion, |
-|                                   | animal waste, detergents          |
-+-----------------------------------+-----------------------------------+
-
-: []{#_Toc454288792 .anchor}**Table 2‑1 Sources of contaminants in urban
-storm water runoff (US EPA, 1999)**
-
-  ----------------------------------------------------------------------------------------------------------------------------
-  **Land Use**    **TSS**   **TP**   **TKN**   **NH3-N**   **NO2+NO3-N**   **BOD**   **COD**   **Pb**   **Zn**   **Cu**
-
-|  |  |  |  |  |  |  |  |  |  |  |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| Commercial | 1000 | 1.5 | 6.7 | 1.9 | 3.1 | 62 | 420 | 2.7 | 2.1 | 0.4 |
-| Parking Lot | 400 | 0.7 | 5.1 | 2 | 2.9 | 47 | 270 | 0.8 | 0.8 | 0.04 |
-| HDR | 420 | 1 | 4.2 | 0.8 | 2 | 27 | 170 | 0.8 | 0.7 | 0.03 |
-| MDR | 190 | 0.5 | 2.5 | 0.5 | 1.4 | 13 | 72 | 0.2 | 0.2 | 0.14 |
-| LDR | 10 | 0.04 | 0.03 | 0.02 | 0.1 | NA | NA | 0.01 | 0.04 | 0.01 |
-| Freeway | 880 | 0.9 | 7.9 | 1.5 | 4.2 | NA | NA | 4.5 | 2.1 | 0.37 |
-| Industrial | 860 | 1.3 | 3.8 | 0.2 | 1.3 | NA | NA | 2.4 | 7.3 | 0.5 |
-| Park | 3 | 0.03 | 1.5 | NA | 0.3 | NA | 2 | 0 | NA | NA |
-| Construction | 6000 | 80 | NA | NA | NA | NA | NA | NA | NA | NA |
-
-
-  : []{#_Toc454288793 .anchor}**Table 2‑2 Typical pollutant loadings
-  from runoff by urban land use (lbs/acre-yr)**
-
-HDR: High Density Residential, MDR: Medium Density Residential, LDR: Low
-Density Residential
-
-NA: Not available; insufficient data to characterize loadings
-
-Source: Burton and Pitt (2002).
-
-The most comprehensive study of urban runoff was conducted by US EPA
-between 1978 and 1983 as part of the National Urban Runoff Program
-(NURP) (US EPA, 1983). Sampling was conducted for 28 NURP projects which
-included 81 specific sites and more than 2,300 separate storm events.
-NURP also examined coliform bacteria and priority pollutants at a subset
-of sites. Median event mean concentrations (EMCs) for ten general NURP
-pollutants for various urban land use categories are presented in Table
-2-3. Fecal coliform is the most widely used indicator for the presence
-of harmful pathogens. Its concentration measured in separate urban storm
-sewers has varied widely, ranging between 400-50,000 MPN/100 ml.
-
-+---------------+-----------+-----------------------+----------------------+----------------------+------------------------+
-| **Pollutant** | **Units** | **Residential**       | **Mixed**            | **Commercial**       | **Open/Non-Urban**     |
-|               |           +------------+----------+------------+---------+------------+---------+------------+-----------+
-|               |           | **Median** | **COV**  | **Median** | **COV** | **Median** | **COV** | **Median** | **COV**   |
-+===============+===========+============+==========+============+=========+============+=========+============+===========+
-| BOD           | mg/L      | 10         | 0.41     | 7.8        | 0.52    | 9.3        | 0.31    | \-         | \-        |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| COD           | mg/L      | 73         | 0.55     | 65         | 0.58    | 57         | 0.39    | 40         | 0.78      |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| TSS           | mg/L      | 101        | 0.96     | 67         | 1.14    | 69         | 0.85    | 70         | 2.92      |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Total Lead    | μg/L      | 144        | 0.75     | 114        | 1.35    | 104        | 0.68    | 30         | 1.52      |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Total Copper  | μg/L      | 33         | 0.99     | 27         | 1.32    | 29         | 0.81    | \-         | \-        |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Total Zinc    | μg/L      | 135        | 0.84     | 154        | 0.78    | 226        | 1.07    | 195        | 0.66      |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Total         | μg/L      | 1900       | 0.73     | 1288       | 0.50    | 1179       | 0.43    | 965        | 1.00      |
-| Kjeldahl      |           |            |          |            |         |            |         |            |           |
-| Nitrogen      |           |            |          |            |         |            |         |            |           |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Nitrate +     | μg/L      | 736        | 0.83     | 558        | 0.67    | 572        | 0.48    | 543        | 0.91      |
-| Nitrite       |           |            |          |            |         |            |         |            |           |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Total         | μg/L      | 383        | 0.69     | 263        | 0.75    | 201        | 0.67    | 121        | 1.66      |
-| Phosphorus    |           |            |          |            |         |            |         |            |           |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-| Soluble       | μg/L      | 143        | 0.46     | 56         | 0.75    | 80         | 0.71    | 26         | 2.11      |
-| Phosphorus    |           |            |          |            |         |            |         |            |           |
-+---------------+-----------+------------+----------+------------+---------+------------+---------+------------+-----------+
-
-: []{#_Toc454288794 .anchor}**Table 2‑3 Median event mean concentrations
-for urban land uses**
-
-COV: Coefficient of variation
-
-Source: Nationwide Urban Runoff Program (US EPA 1983)
-
-## 2.2 Pollutant Sources
-
-SWMM can consider several different types of pollutant sources that
-contribute to water quality impairment in urban catchments.
-
-[Precipitation]{.underline}
-
-The chemical composition associated with precipitation, also known as
-wet deposition, represents a direct contribution to the water quality
-associated with surface runoff. Precipitation quality has been
-extensively monitored and varies widely by location and time of year. It
-can contain significant amounts of nitrates, nitrites, sulfates,
-sulfides, and even mercury (US EPA, 1997). SWMM accounts for this source
-by allowing the user to specify a constant concen­tration of con­stituents
-in precipitation.
-
-[Surface Runoff]{.underline}
-
-For most SWMM applications, surface runoff will be the primary origin of
-water qual­ity constituents. Several mechanisms contribute to stormwater
-runoff quality, most notably *buildup* and *washoff*. In an impervious
-urban area, it is usually as­sumed that a supply of constituents builds
-up on the land surface during dry weather preceding a storm. Such a
-buildup may or may not be a function of time and factors such as traffic
-flow, dry fallout (dry deposition) and street sweeping (James and
-Boregowda, 1985). When a storm event occurs, some fraction of this
-material is then washed off into the drainage system. The phys­ics of the
-washoff may involve rainfall energy, as in some erosion calcula­tions, or
-may be a function of bottom shear stress in the flow as in sediment
-transport theory. Most often, however, washoff is treated by an
-empirical equation with slight physical justification. Methods for
-predicting urban runoff quality constituents are reviewed extensively by
-Huber (1985, 1986), Donigian and Huber (1991), Novotny and Olem (1994),
-and Donigian et al. (1995).
-
-Erosion of "solids" from soil covering the undeveloped, pervious areas
-of a subcatchment is another likely source of constituents. This can be
-modeled as a separate land use category with an unlimited amount of
-buildup with its own dedicated washoff equation.
-
-[Dry Weather Flow]{.underline}
-
-Dry weather flow (DWF) is the continuous discharge of sanitary or
-industrial wastewater directly into the conveyance portion of a SWMM
-model, typically at junction nodes of a sanitary sewer network (refer to
-Figure 1-2). Thus it is only relevant when modeling sanitary or combined
-sewer systems. DWF usually follows some repeating pattern on both a
-diurnal, daily, and monthly basis. SWMM allows one to define how both
-the flow rate and concentration of water quality constituents vary
-periodically with time at any specific node of the drainage network.
-More information on dry weather source concentrations and flow patterns
-is presented in section 2.5.
-
-[Groundwater Flow]{.underline}
-
-SWMM models that contain a groundwater component can generate lateral
-groundwater flow out of the saturated zone of a subcatchment's
-sub-surface area into a node of the conveyance network (see Chapter 5 of
-Volume I). This process is usually reserved for modeling recession
-curves and base flows in the open channel portions of the drainage
-network. One can assign constant concentrations to this flow for each
-water quality constituent being modeled. No attempt is made to track the
-transport and transformation of constituents that infiltrate from the
-surface into the unsaturated groundwater zone and then percolate into
-the saturated zone from which they enter the drainage network. Likewise,
-the migration of constituents from other parts of the groundwater
-aquifer is also ignored. Although there are many unsaturated/saturated
-2-D/3-D groundwater models available that can consider such phenomena
-(Bear and Cheng, 2010), their complexity precludes their use within a
-general purpose urban drainage model like SWMM.
-
-[Inflow/Infiltration (I/I)]{.underline}
-
-SWMM's hydrology module is also capable of estimating rainfall dependent
-inflow and infiltration (RDII) in to sewers. These are flows due to
-\"inflow\" from direct connections of downspouts, sump pumps, foundation
-drains, etc. as well as \"infiltration\" of subsurface water through
-cracked pipes, leaky joints, and poor manhole connections. As with
-groundwater, one can assign a constant concentration to water quality
-constituents associated with RDII flows. The same limitations of using a
-constant concentration here as for groundwater flow applies. Because
-RDII analysis is most commonly used to assess the hydraulic capacity of
-sanitary sewer systems, such analyses rarely consider water quality.
-
-[External Inflows]{.underline}
-
-SWMM's hydraulic module (see Volume II) allows one to introduce
-externally imposed flows at any point in the conveyance network of
-channels, pipes and sewers. These flows can have water quality
-constituents associated with them. The constituent concentration of the
-inflow at some point in time is given by the following expression:
-
-Concentration at time t = (baseline value) × (baseline pattern factor) +
-
-> (scale factor) × (time series value at time t)
-
-The baseline value is some constant, the baseline pattern is either a
-repeating hourly, daily, or monthly multiplier factor applied to the
-baseline value, the time series value is a time varying value, and the
-scale factor is a constant multiplier applied to each time series value.
-All values and factors are user-supplied. Time series values can be
-specified at unequal intervals of time. Interpolation is used to obtain
-values at intermediate times.
-
-The expression for constituent concentration is multiplied by the flow
-rate associated with the external inflow to arrive at an external mass
-inflow rate (in units of mass per time). Instead of specifying the
-concentration of the external inflow one can instead use the above
-expression to model a time-varying mass loading of a constituent. In
-this case it is not necessary to provide an external flow rate to
-introduce a pollutant into the drainage system.
-
-To summarize, SWMM can model water quality constituents entering a
-drainage system from direct precipitation, from surface runoff, from
-lateral groundwater flow, from rainfall dependent inflow/infiltration,
-from dry weather base flow or sanitary sewage flow, and from
-user-supplied external time series flows.
-
-## 2.3 Pollutant and Land Use Objects
-
-### 2.3.1 Pollutant Object
-
-SWMM represents a water quality constituent through a **Pollutant**
-object. Any number of pollutants may be defined in a SWMM model and be
-included in a simulation provided that:
-
-1.  they can be expressed as a concentration of either mass or number
-    (for biological organisms) per volume of water,
-
-2.  their masses are additive, meaning that the concentration of two
-    equal volumes of water mixed together is the sum of the individual
-    concentrations.
-
-Note that these conditions would preclude naming pH as a constituent
-since it is expressed as the logarithm of a concentration and the pH of
-a mixture also depends in a nonlinear fashion on the alkalinity in the
-volumes being mixed. Other constituents not meeting these criteria
-include conductivity, turbidity, and color.
-
-The following user-supplied properties are associated with each
-pollutant object:
-
-- Units -- either mg/L or μg/L for chemical constituents or counts/L for
-  biological constituents.
-
-- Rain Concentration -- the concentration of the constituent in direct
-  precipitation.
-
-- Groundwater Concentration -- the concentration of the constituent in
-  the saturated groundwater zone associated with all subcatchments in
-  which groundwater is modeled.
-
-- Inflow/Infiltration Concentration -- the concentration of the
-  constituent in any flow that enters the conveyance system (which would
-  typically be a sanitary sewer system) due to rainfall dependent
-  inflow/infiltration.
-
-- Dry Weather Flow Concentration -- the average concentration of the
-  constituent in any dry weather flow (typically sanitary sewage flow)
-  introduced externally into the conveyance system.
-
-- Decay Coefficient -- a first order reaction coefficient (in units of
-  1/days) used to compute the rate at which the constituent decays due
-  to reaction or other processes once it enters the conveyance portion
-  of a SWMM model.
-
-- Snow Only Flag -- a flag used to indicate if the constituent only
-  builds up on the land surface when snow is present (such as might be
-  the case for chlorides associated with street de-icing operations).
-
-- Co-Pollutant -- the name of another pollutant whose concentration adds
-  to the concentration of the current pollutant.
-
-- Co-Fraction -- the fraction of the co-pollutant that adds to the
-  concentration of the current pollutant.
-
-Co-pollutants are useful for representing constituents that can appear
-in either dissolved or solid forms (e.g., BOD, metals, phosphorus) and
-may be adsorbed onto other constituents (e.g., pesticides onto "solids")
-and thus be generated as a portion or fraction of such other
-constituents. This co-fraction, also known as a potency factor, is
-commonly used in agricultural and sediment runoff models, such as HSPF
-(Bicknell et al., 1997), to relate concentrations of particulate forms
-of specific constituents (such as phosphorous, BOD, heavy metals, and
-organic nitrogen) to suspended solids concentrations. The co-fractions
-(or potency factor) must honor the units used for the two constituents
-being related. Thus a co-fraction can be greater than 1. In SWMM
-co-pollutants only apply to buildup/washoff processes -- not to the
-user-specified concentrations in rainwater, groundwater, sewer
-inflow/infiltration (I/I), and dry weather flow.
-
-Table 2-4 lists potency factors for suspended solids derived from wet
-weather sampling for different constituents and land uses in the Detroit
-Metropolitan area. Table 2-5 does the same for the Patuxent River basin
-in Maryland. The differences in factors for the same constituent at the
-two locations underscore how site-specific these factors can be.
-
-### 2.3.2 Land Use Object
-
-Because buildup data clearly show that different rates apply to
-different land uses, SWMM allows one to define different buildup and
-washoff functions for each combination of pollutant and land use. SWMM's
-Land Use object is used to identify a particular type of land use and to
-store the buildup (and washoff) functions for each SWMM Pollutant.
-
-**Land Uses** are categories of development activities or land surface
-characteristics assigned to subcatchments. Examples of land use
-activities are residential, commercial, industrial, and undeveloped.
-Land surface characteristics might include rooftops, lawns, paved roads,
-undisturbed soils, etc. Land uses are used solely to account for spatial
-variation in pollutant buildup and washoff rates within subcatchments.
-
-  -----------------------------------------------------------------------------------------
-  **Constituent**    **Residential**   **Commercial/Industrial**   **Roads**    **Rural**
-
-|  |  |  |  |  |
-| --- | --- | --- | --- | --- |
-| BOD5 | 34 | 45 | 10 | 18 |
-| Fecal | 87,000 | 37,000 | 200,000 | 300,000 |
-| Coliformsa |  |  |  |
-| NH4 | 0. | 8                    2.4 |  | 0.35         0.45 |
-| NO2 + N | O3 | 1.7 | 6.4 | 0.07         3.5 |
-| Total Organic N | 4.3 | 4.1 | 1.22 | 7.0 |
-| Total P | 1.9 | 1.7 | 0.26 | 1.5 |
-| PO4 | 0.2 | 4                   0.47 |  | 0.20         2.4 |
-| Oil & Grease | 25 | 80 | 100 | 13 |
-| Lead | 1.8 | 1.4 | 0.41 | 0.21 |
-
-
-  : []{#_Toc454288795 .anchor}**Table 2‑4 Potency factors for the
-  Detroit metropolitan area (mg/gram)**
-
-a (organisms/100ml) / (gram/L TSS)
-
-Source: Roesner (1982).
-
-  ----------------------------------------------------------------------------------
-  **Land Use**                        **NO3**    **NH4**    **PO4**   **BOD**
-
-|  |  |  |  |  |
-| --- | --- | --- | --- | --- |
-| Low Density Residential | 1.5 | 0.4 | 1.1 | 90 |
-| Medium/High Density Residential | 6.0 | 2.0 | 1.6 | 180 |
-| Commercial/Industrial | 10.0 | 3.2 | 2.7 | 270 |
-| Forest and Wetland | 0.1-0.18 | 0.011-0.018 | 0.04-0.07 | 11-17 |
-| Pasture | 3.6 | 0.4 | 0.27 | 60 |
-| Idle Agricultural Land | 2.0 | 0.2 | 0.16 | 30 |
-
-
-  : []{#_Toc454288796 .anchor}**Table 2‑5 Potency factors for the
-  Patuxent River Basin (mg/gram)**
-
-Source: Aqua Terra (1994).
-
-The SWMM user has many options for defining land uses and assigning them
-to subcatchment areas. One approach is to assign a mix of land uses for
-each subcatchment, which results in all land uses within the
-subcatchment having the same pervious and impervious characteristics.
-Another approach is to create subcatchments that have a single land use
-classification along with a distinct set of pervious and impervious
-characteristics that reflects the classification. If surface buildup and
-washoff is not being modeled, such as when pollutant inflows come only
-from wet deposition, dry weather sanitary flows, and external time
-series flows, then there is no need to add land uses into a project.
-
-## 2.4 Wet Deposition
-
-There is considerable public awareness of the fact that precipitation is
-by no means "pure" and does not have characteristics of distilled water.
-Low pH (acid rain) is the best known parameter but many substances can
-also be found in precipitation, including organics, solids, nutrients,
-metals and pesticides (Novotny and Olem, 1994). Atmospheric deposition
-is an important loading factor in coastal waters (NRC, 2000). Compared
-to surface sources, rainfall is probably an important contributor mainly
-of some nutrients in urban runoff, although it may contribute
-substantially to other constituents as well. In particular, Kluesener
-and Lee (1974) found ammonia levels in rainfall higher than in runoff in
-a residential catchment in Madison, Wisconsin; rainfall nitrate
-accounted for 20 to 90 percent of the nitrate in stormwater runoff to
-Lake Wingra. Mattraw and Sherwood (1977) report similar findings for
-nitrate and total nitrogen for a residential area near Fort Lauderdale,
-Florida. Data from the latter study are presented in Table 2-6 in which
-rainfall may be seen to be an important contributor to all nitrogen
-forms, plus COD, although the instance of a higher COD value in rainfall
-than in runoff is probably anomalous.
-
-In addition to the two references first cited, Weibel et al. (1964,
-1966) report concentrations of constituents in Cincinnati rainfall
-(Table 2-6), and a summary is also given by Manning et al. (1977). Other
-data on rainfall chemistry and loadings are given by Uttormark et al.
-(1974), Betson (1978), Hendry and Brezonik (1980), Novotny and Kincaid
-(1981), Randall et al. (1981), Mills et al., (1985), and Novotny and
-Olem (1994). A comprehensive summary is presented by Brezonik (1975)
-from which it may be seen in Table 2-6 that there is a wide range of
-concentrations observed in rainfall. Again, the most important
-parameters relative to urban runoff are probably the various nitrogen
-forms.
-
-The previous cited literature reflects relevant but older information
-regarding precipitation chemistry. A very useful web site is
-http://nadp.sws.uiuc.edu/, for the National Atmospheric Deposition
-Program (NADP). Data may be downloaded from this site for hundreds of
-monitoring locations across the U.S., permitting good estimates of
-regional precipitation concentrations. Annual, seasonal, and time series
-data and plots may be downloaded for wet and dry deposition of
-parameters such as pH, nitrogen species, calcium, chloride, and whatever
-else is measured at a site. A bonus for some sites is daily
-precipitation data. Dry deposition values might be included with buildup
-on the land surface, although other buildup factors, such as wind
-erosion, traffic, etc. make it very difficult to separate causative
-factors (James and Boregowda, 1985).
-
-+:---------------+:-----------------+:---------------:+:-----------------:+:--------------:+:--------------:+
-| **Parameter**                     | **Ft.           | **Cincinnatib** | **Lodi,        | **"Typical     |
-|                                   | Lauderdalea** |                   | NJc**        | Range"d**    |
-+-----------------------------------+-----------------+-------------------+----------------+----------------+
-| Acidity (pH)                      |                 |                   |                | 3-6            |
-+-----------------------------------+-----------------+-------------------+----------------+----------------+
-| Organics                          |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | BOD5, mg/L       | 4-22            | 16                |                | 1-13           |
-|                |                  |                 |                   |                |                |
-|                | COD, mg/L        | 1-3             |                   |                | 9-16           |
-|                |                  |                 |                   |                |                |
-|                | TOC, mg/L        | 0-2             |                   |                | Few            |
-|                |                  |                 |                   |                |                |
-|                | Inorg. C, mg/L   |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-| Color, PCU                        | 5-10            |                   |                |                |
-+-----------------------------------+-----------------+-------------------+----------------+----------------+
-| Solids                            |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Total Solids,    | 18-24           | 13                |                |                |
-|                | mg/L             |                 |                   |                |                |
-|                |                  | 2-10            |                   |                |                |
-|                | Suspended        |                 |                   |                |                |
-|                | Solids, mg/L     | 4-7             |                   |                |                |
-|                |                  |                 |                   |                |                |
-|                | Turbidity, JTU   |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-| Nutrients                         |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Org. N, mg/L     | 0.09-0.15       | 0.58              |                | 0.05-1.0       |
-|                |                  |                 |                   |                |                |
-|                | NH3-N, mg/L    | 0.01-0.04       | 1.27e           |                | 0.05-1.0       |
-|                |                  |                 |                   |                |                |
-|                | NO2-N, mg/L    | 0.00-0.01       | 0.08              |                | 0.2-1.5        |
-|                |                  |                 |                   |                |                |
-|                | NO3-N, mg/L    | 0.12-0.73       |                   |                | 0.0-0.05       |
-|                |                  |                 |                   |                |                |
-|                | Total N, mg/L    | 0.29-0.84       |                   |                | 0.02-0.15      |
-|                |                  |                 |                   |                |                |
-|                | Orthophosphorus, | 0.01-0.03       |                   |                |                |
-|                | mg/L             |                 |                   |                |                |
-|                |                  | 0.01-0.05       |                   |                |                |
-|                | Total P, mg/L    |                 |                   |                |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-| Pesticides, μg/L                  |                 | 3-600             |                | Few            |
-+-----------------------------------+-----------------+-------------------+----------------+----------------+
-| Heavy metals, μg/L                |                 |                   |                | Few            |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Lead, μg/L       |                 |                   | 45             | 30-70          |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Nickel, μg/L     |                 |                   | 3              |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Copper, μg/L     |                 |                   | 6              |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-|                | Zinc, μg/L       |                 |                   | 44             |                |
-+----------------+------------------+-----------------+-------------------+----------------+----------------+
-| aRange for three storms (Mattraw and Sherwood, 1977)                                                    |
-|                                                                                                           |
-| bAverage of 35 storms (Weibel et al., 1966)                                                             |
-|                                                                                                           |
-| cWilbur and Hunter (1980)                                                                               |
-|                                                                                                           |
-| dBrezonik (1975)                                                                                        |
-|                                                                                                           |
-| eSum of NH3-N, NO2-N, NO3-N                                                                       |
-+-----------------------------------------------------------------------------------------------------------+
-
-: []{#_Toc454288797 .anchor}**Table 2‑6 Representative concentrations of
-constituents in rainfall**
-
-Constituent concentrations in precipitation are associated with a SWMM
-Pollutant object. All surface runoff, including snowmelt, is assumed to
-have at least this concentration, and the precipitation load is
-calculated by multiplying this concentration by the runoff rate and
-adding to the load already generated by other mechanisms. It may be
-inappropriate to add a precipitation load to loads generated by a
-calibration of buildup-washoff or rating curve parameters against
-measured runoff concentrations, since the latter already reflect the sum
-of all contributions, land surface and otherwise. But precipitation
-loads might well be included if starting with buildup-washoff data from
-other sources. They also provide another simple means for imposing a
-constant concentration on any subcatchment constituent.
-
-## 2.5 Dry Weather Flow
-
-For most of this discussion, "dry-weather flow" (DWF), equivalent to
-base flow in a natural stream, is derived from sanitary sewage or
-industrial flows entering the drainage system -- usually a combined
-sewer. Since SWMM can also be used to simulate sanitary sewers and
-systems with cross connections, DWF might also be applied to simulations
-of those systems. The estimation of DWF quantity and quality in a sewer
-system can be broken into two parts: 1) estimates of average quantities,
-and 2) estimates of time patterns to apply to these averages. The
-discussion that follows addresses each of these aspects.
-
-### 2.5.1 Average Dry-Weather Flow Estimates
-
-Like almost all SWMM input parameters, DWF hydrographs and pollutographs
-are best determined through monitoring. Monitoring of inflows to a
-municipal wastewater treatment plant (WWTP) is routinely performed, at
-least for flow. This end-of-pipe discharge may then be apportioned back
-through the sewer system on the basis of population through census tract
-data, as a first approximation. Similarly, population estimates are
-often used as the basis to determine DWF, on a per capita basis. These
-per capita estimates vary considerably. For instance, ASCE-WPCF (1969)
-report per capita data for 34 cities, as summarized in Table 2-7. Data
-in this table are from the 1960s and reflect sewage discharges at that
-time; modern cities tend to have less per capita water use due to
-low-volume plumbing fixtures, etc. Water use itself is another surrogate
-for DWF measurements, especially winter values that reflect indoor use
-only (no irrigation, car washing, etc.).
-
-Many other sources contribute to average DWF, including commercial
-establishments, hospitals, municipal and institutional buildings,
-apartment buildings, etc., none of which are easily represented on a per
-capita basis. Environmental engineering texts, such as Metcalf & Eddy,
-Inc. (2003) provide tables with data from such locations. Industries can
-generate large quantities of DWF and must be evaluated individually.
-Another alternative for DWF estimates is on a per area basis, but such
-design curves (gallons per acre per day vs. acres) are highly
-site-specific (ASCE-WPCF, 1969).
-
-+----+----------------+:-----------+----+------------------+:-----------+
-|    | **City**       | **Avg.     |    | **City**         | **Avg.     |
-|    |                | Sewage     |    |                  | Sewage**   |
-|    |                | Flow,      |    |                  |            |
-|    |                | gpd/cap**  |    |                  | **Flow,    |
-|    |                |            |    |                  | gpd/cap**  |
-+----+----------------+------------+----+------------------+------------+
-| 1  | Baltimore, MD  | 100        | 19 | Los Angeles 2,   | 70         |
-|    |                |            |    | CA               |            |
-+----+----------------+------------+----+------------------+------------+
-| 2  | Berkeley, CA   | 60         | 20 | Greater Peoria,  | 75         |
-|    |                |            |    | IL               |            |
-+----+----------------+------------+----+------------------+------------+
-| 3  | Boston, MA     | 140        | 21 | Milwaukee, WI    | 125        |
-+----+----------------+------------+----+------------------+------------+
-| 4  | Cleveland, OH  | 100        | 22 | Memphis, TN      | 100        |
-+----+----------------+------------+----+------------------+------------+
-| 5  | Cranston, RI   | 119        | 23 | Orlando, FL      | 70         |
-+----+----------------+------------+----+------------------+------------+
-| 6  | Des Moines, IA | 100        | 24 | Painesville, OH  | 125        |
-+----+----------------+------------+----+------------------+------------+
-| 7  | Grand Rapids,  | 190        | 25 | Rapid City, SD   | 121        |
-|    | MI             |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 8  | Greenville     | 150        | 26 | Santa Monica, CA | 92         |
-|    | County, SC     |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 9  | Hagerstown, MD | 100        | 27 | St. Joseph, MO   | 125        |
-+----+----------------+------------+----+------------------+------------+
-| 10 | Jefferson      | 100        | 28 | Washington, DC   | 100        |
-|    | County, AL     |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 11 | Johnson        | 60         | 29 | Wyoming, MI      | 82         |
-|    | County-1, KS   |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 12 | Johnson County | 60         |    |                  |            |
-|    | 2, KS          |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 13 | Kansas City,   | 60         |    | Average          | 101        |
-|    | MO             |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 14 | Lancaster      | 92         |    | CV\*             | 0.38       |
-|    | County, NB     |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 15 | Las Vegas, NV  | 209        |    | Maximum          | 209        |
-+----+----------------+------------+----+------------------+------------+
-| 16 | Lincoln, NB    | 60         |    | Minimum          | 50         |
-+----+----------------+------------+----+------------------+------------+
-| 17 | Little Rock,   | 50         |    | Median           | 100        |
-|    | AR             |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-| 18 | Los Angeles,   | 85         |    |                  |            |
-|    | CA             |            |    |                  |            |
-+----+----------------+------------+----+------------------+------------+
-
-: []{#_Toc454288798 .anchor}**Table 2‑7 Average daily dry weather flow
-in 29 cities**
-
-\*CV = coefficient of variation = standard deviation/average.
-
-Source: ASCE-WPCF (1969)
-
-+------------------------------------+----------+------------------------------------------+
-| **Contaminant**                    | **Unit** | **Concentration**                        |
-|                                    |          +-------------+-------------+--------------+
-|                                    |          | **Weak**    | **Medium**  | **Strong**   |
-+====================================+==========+=============+=============+==============+
-| Solids, total                      | mg/L     | 390         | 720         | 1230         |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Solids, total dissolved (TDS)      | mg/L     | 270         | 500         | 860          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Fixed                              | mg/L     | 160         | 300         | 520          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Volatile                           | mg/L     | 110         | 200         | 340          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Solids, suspended, total (TSS)     | mg/L     | 120         | 210         | 400          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Fixed                              | mg/L     | 25          | 50          | 85           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Volatile                           | mg/L     | 95          | 160         | 315          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Solids, settleable                 | mg/L     | 5           | 10          | 20           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Biochemical oxygen demand, 5-day   | mg/L     | 110         | 190         | 350          |
-| (BOD5)                             |          |             |             |              |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Total organic carbon (TOC)         | mg/L     | 80          | 140         | 260          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Chemical oxygen demand (COD)       | mg/L     | 250         | 430         | 800          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Nitrogen, total as N (TN)          | mg/L     | 20          | 40          | 70           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Organic                            | mg/L     | 8           | 15          | 25           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Free ammonia (NH3)                 | mg/L     | 12          | 25          | 45           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Nitrite (NO2)                      | mg/L     | 0           | 0           | 0            |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Nitrate (NO3)                      | mg/L     | 0           | 0           | 0            |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Phosphorus, total as P (TP)        | mg/L     | 4           | 7           | 12           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Organic                            | mg/L     | 1           | 2           | 4            |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Inorganic                          | mg/L     | 3           | 5           | 10           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Chlorides                          | mg/L     | 30          | 50          | 90           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Sulfate                            | mg/l     | 20          | 30          | 50           |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Oil and Grease                     | mg/l     | 50          | 90          | 100          |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Volatile organic compounds (VOCs)  | mg/L     | \<100       | 100-400     | \>400        |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Total coliform                     | #/100 mL | 106-108 | 107-109 | 107-1010 |
-+------------------------------------+----------+-------------+-------------+--------------+
-| Fecal coliform                     | #/100 mL | 103-105 | 104-106 | 105-108  |
-+------------------------------------+----------+-------------+-------------+--------------+
-
-: []{#_Toc454288799 .anchor}**Table 2‑8 Quality properties of untreated
-domestic wastewater**
-
-"Weak" is based on an approximate wastewater flow rate of 200 gpd/day
-(750 L/capita-day, "medium" of 120 gpd/day (460 L/capita-day), and
-"strong" of 60 gpd/day (240 L/capita-day).
-
-Source: Metcalf and Eddy, Inc. (2003)
-
-Domestic wastewater quality is variable, but well documented. Typical
-values are shown in Table 2-8 (Metcalf and Eddy, Inc., 2003). Estimates
-are also available on a per capita basis (unit loads) of the type shown
-in Table 2-9 and expanded upon in texts such as Metcalf and Eddy, Inc.
-(2003). Commercial, industrial, and institutional quality is typically
-stronger (higher concentrations) than domestic wastewater and should be
-evaluated individually. Guidelines may be found in several sources, such
-as Tchobanoglous and Burton (1991) and Metcalf and Eddy Inc. (2003).
-Earlier SWMM documentation provides additional literature reviews on
-these topics (Metcalf and Eddy et al., 1971a; Huber and Dickinson,
-1988).
-
-+-------------------------+-------------------+------------------------+
-| **Constituent**         | **Sewage**        | **Ground Garbage**     |
-|                         |                   |                        |
-|                         | **lb/capita-day** | **lb/capita-day**      |
-+=========================+:=================:+:======================:+
-| Total solids            | 0.55              | 0.15                   |
-+-------------------------+-------------------+------------------------+
-| Total volatile solids   | 0.32              | 0.13                   |
-+-------------------------+-------------------+------------------------+
-| Suspended matter        | 0.20              | 0.10                   |
-+-------------------------+-------------------+------------------------+
-| BOD5                    | 0.17              | 0.08                   |
-+-------------------------+-------------------+------------------------+
-| Fats and greases        | 0.05              | 0.03                   |
-+-------------------------+-------------------+------------------------+
-| Total nitrogen          | 0.04              | 0.002                  |
-+-------------------------+-------------------+------------------------+
-
-: []{#_Toc454288800 .anchor}**Table 2‑9 Unit quality loads for domestic
-sewage, including effects of garbage grinders**
-
-Source: Haseltine (1950); Metcalf and Eddy et al. (1971a).
-
-### 2.5.2 Temporal Variations in Dry-Weather Flow
-
-Dry-weather flow quantity and quality varies seasonally, weekly, and
-daily. SWMM provides monthly (one multiplier for each month of year),
-daily (one multiplier for each day of week), hourly (one multiplier for
-each hour of day), and weekend (one multiplier for each hour of weekend
-days) adjustment factors to be applied to average DWF quantities.
-Typical sinusoidal variations are shown in texts such as Metcalf and
-Eddy Inc. (2003) and in ASCE and WPCF (1969), but these variations are
-best obtained by examination of WWTP inflow hydrographs. Variations in
-daily water use (surrogate for wastewater discharge) reported for nine
-homes monitored in November 1964 by Tucker (1967) are shown in Table
-2-10. Typical hourly variations in domestic wastewater flow and strength
-given by Metcalf and Eddy, Inc. (2003) are shown in Figure 2-1 and Table
-2-11.
-
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-|            | **Week**  | **Sun** | **Mon** | **Tues** | **Wed** | **Thurs** | **Fri** | **Sat** | **Average** |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-| **Six home | 10/18/64  | 1722    | 2137    | 1941     | 1938    | 1706      | 1777    | 1762    | 1855        |
-| use, gal** |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-| **Ratio to |           | 0.928   | 1.152   | 1.047    | 1.045   | 0.920     | 0.958   | 0.950   |             |
-| avg.**     |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-|            |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-| **Six home | 11/1/64   | 1774    | 1569    | 1966     | 1714    | 1663      | 1861    | 1784    | 1762        |
-| use, gal** |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-| **Ratio to |           | 1.007   | 0.891   | 1.116    | 0.973   | 0.944     | 1.056   | 1.013   |             |
-| avg.**     |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-|            |           |         |         |          |         |           |         |         |             |
-+------------+-----------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-| **Average ratios**     | 0.968   | 1.021   | 1.081    | 1.009   | 0.932     | 1.007   | 0.981   | 1.000       |
-+------------------------+---------+---------+----------+---------+-----------+---------+---------+-------------+
-
-: []{#_Toc454288801 .anchor}**Table 2‑10 Autumn water use for six homes
-near Wheaton, MD**
-
-Source: Tucker (1967).
-
-![](./VolumeIII/media/media/image7.emf){width="4.817361111111111in"
-height="3.2840277777777778in"}
-
-[]{#_Ref100452456 .anchor}
-
-**Figure 2‑1 Hourly domestic sewage time patterns**
-
-(Based on data from Metcalf and Eddy, Inc.(2003). Ratios are based on
-indicated daily averages.)
-
-  ---------- ---------- --------- --------- ------------- ---------- --------- ---------
-  **Hour**   **Flow**   **BOD**   **TSS**   **Hour**      **Flow**   **BOD**   **TSS**
-
-  1          0.78       0.73      0.80      13            1.33       1.28      1.49
-
-  2          0.58       0.55      0.63      14            1.23       1.22      1.31
-
-  3          0.45       0.37      0.40      15            1.16       1.16      1.14
-
-  4          0.36       0.24      0.29      16            1.07       1.10      0.97
-
-  5          0.32       0.30      0.23      17            1.04       0.97      0.91
-
-  6          0.39       0.49      0.23      18            1.07       0.97      0.86
-
-  7          0.65       0.73      0.57      19            1.13       1.16      0.91
-
-  8          0.97       0.97      1.20      20            1.26       1.52      1.20
-
-  9          1.36       1.22      1.49      21            1.29       1.83      1.26
-
-  10         1.39       1.28      1.54      22            1.26       1.04      1.20
-
-  11         1.42       1.34      1.60      23            1.13       1.22      1.14
-
-  Noon       1.39       1.34      1.54      Midnight      0.97       0.97      1.09
-
-                                            **Average**   100        1.00      1.00
-  ---------- ---------- --------- --------- ------------- ---------- --------- ---------
-
-  : []{#_Toc454288802 .anchor}**Table 2‑11 Typical hourly DWF correction
-  factors**
-
-Source: Metcalf and Eddy, Inc. (2003).
-
-## 2.6 Simulating Runoff Quality
-
-Simulation of urban runoff quality is a very inexact science if it can
-even be called such. Very large uncertainties arise both in the
-representa­tion of the physical, chemical and biological processes and in
-the acquisition of data and parameters for model algorithms. For
-instance, subsequent sec­tions will discuss the concept of "buildup" of
-pollutants on land surfaces and "washoff" during storm events. The true
-mechanisms of buildup involve factors such as wind, traffic, atmospheric
-fallout, land surface activities, erosion, street cleaning and other
-imponderables. Al­though efforts have been made to include such factors
-in physically-based equations (James and Boregowda, 1985), it is
-unrealistic to assume that they can be represented with enough accuracy
-to determine *a priori* the amount of pollutants on the surface at the
-beginning of the storm. Equally naive is the idea that empirical washoff
-equations truly represent the complex hydrodynamic (and chemical and
-biologi­cal) processes that occur while overland flow moves in random
-patterns over the land surface. The many difficulties of simulation of
-urban runoff quality are discussed by Huber (1985, 1986).
-
-Such uncertainties can be dealt with in two ways. The first option is to
-collect enough calibration and verification data to be able to calibrate
-the model equations used for quality simulation. Given sufficient data,
-the equa­tions used in SWMM can usually be manipulated to reproduce
-measured con­centra­tions and loads. This is essentially the option
-discussed at length in the following sections. The second option is to
-abandon the notion of de­tailed quality simulation altogether and either
-use a constant concentration (event mean concentration or EMC) applied
-to quantity predictions (i.e., obtain storm loads by multiplying
-pre­dicted volumes by an assumed concentration) (Johansen et al., 1984)
-or use a statis­tical method (Hydroscience, 1979; Driscoll and Assoc.,
-1981; US EPA, 1983b; DiToro, 1984; Adams and Papa, 2000). EMC values may
-be entered directly into SWMM 5. Statistical methods are based in part
-upon strong evidence that storm event mean concentrations are
-lognor­mally distributed (Driscoll, 1986). The statistical methods
-recognize the frustrations of physically-based modeling and move
-directly to a stochastic result (e.g., a frequency distri­bution of
-EMCs), but they are even more de­pendent on available data than meth­ods
-such as those found in SWMM. That is, statistical parameters such as
-mean, median and variance must be available from other studies in order
-to use the statis­tical meth­ods. Furthermore, it is harder to study the
-effect of controls and catch­ment modifications using statistical
-methods.
-
-Table 4-12 on p. 4-77.The main point is that there are alternatives to
-the buildup-washoff approach available in SWMM; the latter can involve
-extensive effort at parameter estimation and model calibration to
-produce quality predictions that may vary greatly from an unknown
-"reality." But SWMM also offers simpler options, including the constant
-concentration or EMC approach. Before delving into the arcane methods
-incorporated in SWMM and other urban runoff quality simulation models,
-the user should try to determine whether or not the effort will be worth
-it in view of the uncertain­ties of the process and whether or not
-simpler alternative methods might suf­fice. The discussions that follow
-provide a comprehensive view of the options available in SWMM, which are
-more than in almost any other comparable model, but the extent of the
-discussion should not be interpreted as a guarantee of success in
-applying the methods.
-
-Although the conceptualization of the quality processes is not
-diffi­cult, the reliability and credibility of quality parameter
-simulation is very challenging to establish. In fact, quality
-predictions by SWMM or almost any other surface runoff model are mostly
-hypothetical unless local data for the catchment being simulated are
-available to use for calibration and validation. If such data are
-lack­ing, results may still be used to compare *relative* effects of
-changes, but parameter magnitudes (i.e., actual values of pre­dicted
-concentrations) will forever be in doubt. This is in marked con­trast to
-quantity prediction for which reasonable estimates of hydrographs may be
-made in advance of calibra­tion.
-
-Moreover, there is disagreement in the literature as to what are the
-important and appropriate physical and chemical mechanisms that should
-be included in a model to generate surface runoff quality. The objective
-in SWMM has been to provide flexibility in mechanisms and the
-opportunity for calibration. But this places a considerable burden on
-the user to obtain adequate data for model usage and to be familiar with
-quality mechanisms that may apply to the catchment being studied. This
-burden is all too often ig­nored, leading ultimately to model results
-being discredited.
-
-In the end then, there is no substitute for local data (rain, flow, and
-concentration measurements) with which to calibrate and verify the
-quality predictions. *Without such data, little reliability can be
-placed in the predicted magnitudes of quality parameters.*
-
-Early quality modeling efforts with SWMM emphasized generation of
-detailed pollutographs, in which concentrations versus time were
-generated for short time increments during a storm event (e.g., Metcalf
-and Eddy et al., 1971b). Depending upon the application, such detail may
-be entirely unnecessary because the receiving waters cannot respond to
-such rapid changes in concentration or loads. Instead, only the total
-storm event load is necessary for most studies of receiving water
-quality. Time scales for the response of various receiving waters are
-presented in Table 2-12 (Driscoll, 1979; Hydroscience, 1979).
-Concentration transients occurring within a storm event are unlikely to
-affect any common quality parameter within the receiving water, with the
-possible exception of bacteria. Detailed temporal concentration
-variations within a storm event are needed primarily when they will
-affect control alternatives. For example, a storage device may need to
-trap the "first flush" of pollutants, if one exists.
-
-+-------------------------+----------------------+--------------------+
-| **Type of**             | **Key**              | **Response**       |
-|                         |                      |                    |
-| **Receiving Water**     | **Constituents**     | **Time**           |
-+-------------------------+----------------------+--------------------+
-| Lakes, Bays             | Nutrients            | Weeks - Years      |
-+-------------------------+----------------------+--------------------+
-| Estuaries               | Nutrients, DO        | Days - Weeks       |
-+-------------------------+----------------------+--------------------+
-| Large Rivers            | DO, Nitrogen         | Days               |
-+-------------------------+----------------------+--------------------+
-| Streams                 | DO, Nitrogen         | Hours - Days       |
-|                         |                      |                    |
-|                         | Bacteria             | Hours              |
-+-------------------------+----------------------+--------------------+
-| Ponds                   | DO, Nutrients        | Hours - Weeks      |
-+-------------------------+----------------------+--------------------+
-| Beaches                 | Bacteria             | Hours              |
-+-------------------------+----------------------+--------------------+
-
-: []{#_Toc454288803 .anchor}**Table 2‑12 Required temporal detail for
-receiving water analysis**
-
-Source: Driscoll (1979) and Hydroscience (1979).
-
-The significant point is that calibration and verification ordinarily
-need only be performed on total storm event loads, or on event mean
-concentra­tions. This is a much easier task than trying to match detailed
-concentration transients within a storm event.
-
-#  Chapter 3 - Surface Buildup
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 3.1 Introduction
-
-Simulation of pollutant buildup on the subcatchment surface is only
-required if SWMM's Exponential option is used to describe wash off,
-since that function depends on the amount of buildup present (see
-Chapter 4). However, even when washoff quality is estimated using an
-Event Mean Concentration (EMC) or Rating Curve option, buildup
-simulation could still be useful to establish a maximum mass of
-pollutant that could be removed during any given storm event.
-
-One of the most influential of the early studies of storm­water pollution
-was conducted in Chicago by the American Public Works Association
-(1969). As part of this project, street surface accumulation of "dust
-and dirt" (DD) (anything passing through a quarter-inch mesh screen) was
-measured by sweeping with brooms and vacuum cleaners. The accumulations
-were measured for differ­ent land uses and curb length, and the data were
-normalized in terms of pounds of dust and dirt per dry day per 100 ft of
-curb or gutter. These well known results are shown in Table 3-1 and
-imply that dust and dirt buildup is a linear function of time. The dust
-and dirt samples were analyzed chemically, and the fraction of sample
-consisting of various constituents for each of four land uses was
-de­termined, leading to the results shown in Table 3-2.
-
-  ---------- -------------------------------- -----------------------------
-  **Type**   **Land Use**                      **Pounds DD/dry day per 100
-                                                        ft-curb**
-
-  1          Single Family Residential                     0.7
-
-  2          Multi-Family Residential                      2.3
-
-  3          Commercial                                    3.3
-
-  4          Industrial                                    4.6
-
-  5          Undeveloped or Park                           1.5
-  ---------- -------------------------------- -----------------------------
-
-  : []{#_Toc454288804 .anchor}**Table 3‑1 Measured dust and dirt (DD)
-  accumulation in Chicago**
-
-Source: APWA (1969).
-
-+:------------------+:-----------------:+:-----------------:+:-----------------:+:-----------------:+
-| **Parameter**     | **Land Use Type**                                                             |
-|                   +-------------------+-------------------+-------------------+-------------------+
-|                   | **Single Family** | **Multi-Family**  | **Commercial**    | **Industrial**    |
-|                   |                   |                   |                   |                   |
-|                   | **Residential**   | **Residential**   |                   |                   |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| BOD5              | 5.0               | 3.6               | 7.7               | 3.0               |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| COD               | 40.0              | 40.0              | 39.0              | 40.0              |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| Total             | 1.3 × 106       | 2.7 × 106       | 1.7 × 106       | 1.0 × 106       |
-| Coliformsa      |                   |                   |                   |                   |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| Total N           | 0.48              | 0.61              | 0.41              | 0.43              |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| Total PO4 (as   | 0.05              | 0.05              | 0.07              | 0.03              |
-| PO4)            |                   |                   |                   |                   |
-+-------------------+-------------------+-------------------+-------------------+-------------------+
-| aUnits for coliforms are MPN/gram.                                                              |
-+---------------------------------------------------------------------------------------------------+
-
-: []{#_Toc454288805 .anchor}**Table 3‑2 Milligrams of pollutant per gram
-of dust and dirt (parts per thousand by mass) for four Chicago land
-uses**
-
-Source: APWA (1969).
-
-From the values shown in Tables 3-1 and 3-2, the buildup of each
-con­stituent (also linear with time) can be computed simply by
-multiplying dust and dirt by the appropriate fraction. Since the APWA
-study was published during the original SWMM project (1968-1971), it
-represented the state of the art at the time and linear buildup was used
-extensively in the development of the surface quality routines in the
-original SWMM program (Metcalf and Eddy et al., 1971a, Section 11).
-Ammon (1979) summarized many subsequent studies of pollutant buildup on
-urban surfaces and found evidence to suggest several nonlinear buildup
-relationships as alternatives to the linear one. Upper limits for
-buildup are also likely. Several options for both buildup and washoff
-were proposed by Ammon and incorporated into SWMM III (Huber et al.,
-1981b).
-
-Of course, the whole buildup idea essentially ignores the physics of
-generation of pollutants from sources such as street pavement, vehicles,
-at­mospheric fallout, vegetation, land surfaces, litter, spills,
-anti-skid com­pounds and chemicals, construction, and drainage networks.
-Novotny and Olem (1994) and Novotny (1995) summarize empirical
-relationships for the urban street surface pollution accumulation
-process. Lager et al. (1977) and James and Boregowda (1985) consider
-each source in turn and give guidance on buildup rates. To summarize,
-several studies and voluminous data exist from the 1960s and 1970s with
-which to formu­late buildup relationships, most of which are purely
-empirical and data-based, ignoring the underlying physics and chemistry
-of the generation processes. Nonetheless, they represent what is
-available, and modeling techniques in SWMM are designed to accommodate
-them in their heuristic form.
-
-## 3.2 Governing Equations
-
-There is ample evidence that buildup is a nonlinear function of dry
-days; Sartor and Boyd's (1972) data are most often cited as examples
-(Figure 3-1). Later data from Pitt (Figure 3-2) for San Jose indicate
-almost linear accumu­lation, although some of the best fit lines
-indicated in the figure had very poor correlation coefficients, ranging
-from 0.35 ≤ R ≤ 0.9. (The actual data points are not shown in Pitt's
-figures.) Even in data collected as carefully as in the San Jose study,
-the scatter (not shown in the report) is considerable. Thus, the choice
-of the best functional form is not obvious.
-
-

-
-
Figure 3‑1 Accumulation of solids on urban
-streets versus time (Sartor and Boyd, 1972)

-

-
-Because buildup data clearly show that different rates apply to
-different land uses, SWMM allows one to define a different buildup
-function for each combination of pollutant and land use. The Pollutant
-object used to describe water quality constituents was described
-previously in section 2.3. SWMM's Land Use object is used to identify a
-particular type of land use and to store the buildup (and washoff)
-functions for each SWMM Pollutant.
-
-![[]{#_Toc454288766 .anchor}**Figure 3‑2 Buildup of street solids in San
-Jose (from Pitt, 1979)**](./media/media/image9.png){width="6.5in"
-height="4.351602143482065in"}
-
-The buildup of each pollutant that accumulates over a category of land
-use is described by either a mass per unit of subcatchment area or per
-unit of curb length. For microbial constituents, numbers of organisms is
-used instead of mass. The choice of quantity to normalize against (area
-or curb length) can vary by pollutant and land use. In the discussion
-that follows \[B\] will denote the units being used to express buildup.
-
-Because there is no obviously proper functional form that describes
-pollutant buildup over time, SWMM provides the user with three different
-functional options for any combination of constituent and land use.
-These are:
-
-1.  power function (of which linear buildup is a special case),
-
-2.  exponential, or
-
-3.  saturation.
-
-Power function buildup accumulates proportional to time raised to some
-power, until a maximum limit is achieved,
-
-$$b = Min(B_{\max},\ K_{B}t^{N_{B}}) \qquad \text{(3-1a)}$$
-
-where
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *b* | = | buildup, [B] |
-| *t* | = | buildup time interval, days |
-| *Bmax* | = | maximum buildup possible, [B] |
-| *KB* | = | buildup rate constant, [B]-days-*N**B* |
-| *NB* | = | buildup time exponent, dimensionless |
-
-The time exponent, *NB,* should be ≤ 1 so that a decreasing rate of
-buildup occurs as time increases. When *NB* is set equal to 1, a
-linear buildup function is obtained.
-
-Exponential buildup follows an exponential growth curve that approaches
-a maximum limit asymptotically,
-
-$$b = B_{\max}\left( 1 - e^{- K_{B}t} \right) \qquad \text{(3-1b)}$$
-
-where the rate constant *KB* now has units of days-1.
-
-Saturation buildup begins at a linear rate which proceeds to decline
-constantly over time until a saturation value is reached,
-
-$$b = \frac{B_{\max}t}{\left( K_{B} + t \right)} \qquad \text{(3-1c)}$$
-
-where now *KB* is a half saturation constant (days to reach half of
-the maximum buildup).
-
-Table 3-3 summarizes the meaning and units of the coefficients used in
-each of the buildup functions. The following expression will convert
-from mass of buildup per unit of area or curb length for a specific land
-use to total mass
-
-> $$m_{B} = bNf_{LU}$$
-
-where *mB* = mass of buildup, *b* = mass per unit of either area or
-curb length, *N* = total area or curb length for the subcatchment in
-question, and *fLU* = fraction of the subcatchment's area devoted to
-the land use in question.
-
-The shapes of the three functions are compared in Figure 3-3 using a
-hypothetical pollutant as an example that reaches a maximum buildup of 2
-kg/ac in about 14 days. The Exponential and Saturation func­tions have
-clearly defined asymptotes or upper limits (2 kg/ac in this figure).
-Upper limits for linear or power function buildup may be imposed if
-desired. "Instantaneous buildup" may be easily achieved using the power
-function with *NB* set to 0 and *KB* set equal to *Bmax*. This
-would result in a constant buildup of *Bmax* which would always be
-available at the beginning of any storm event.
-
-+-----------------+-------------------------------------------------------------------------------------+
-| **Coefficient** | **Buildup Function**                                                                |
-|                 +---------------------------------------+----------------------+----------------------+
-|                 | **Power**                             | **Exponential**      | **Saturation**       |
-+=================+:======================================+:=====================+:=====================+
-| *Bmax*          | buildup limit \[B\]                   | buildup limit \[B\]  | buildup limit \[B\]  |
-+-----------------+---------------------------------------+----------------------+----------------------+
-| *KB*          | rate constant,                        | rate constant,       | ½ saturation         |
-|                 | $\lbrack B\rbrack{days}^{- \eta_{B}}$ | days-1             | constant, days       |
-+-----------------+---------------------------------------+----------------------+----------------------+
-| *NB*          | time exponent                         |                      |                      |
-+-----------------+---------------------------------------+----------------------+----------------------+
-
-: []{#_Toc454288806 .anchor}**Table 3‑3 Summary of buildup function
-coefficients**
-
-

-BuildupFuncs.png
-
Figure 3‑3 Comparison of buildup equations
-for a hypothetical pollutant

-

-
-Fig. 4-27 on p. 4-86.Fig. 4-28 on p. 4-87.Table 4-16 on p. 4-88.Table
-4-17 on p. 4-89.Table 4-18 on p. 4-90.It is apparent from Figure 3-3
-that different options may be used to accomplish the same objective
-(e.g., nonlinear buildup); the choice may well be made on the basis of
-available data to which one of the functional forms has been fit. If an
-asymptotic form is desired, either the exponential or saturation option
-may be used depending upon ease of comprehension of the parameters. For
-instance, for exponential buildup the rate constant, *KB*, is the
-familiar exponential decay constant. It may be obtained from the slope
-of a semi-log plot of buildup versus time. As a numerical example, if
-its value were 0.33 day‑1, then it would take 7 days to reach 90
-percent of the maximum buildup, as in Figure 3-3.
-
-For saturation buildup the parameter *KB* has the interpretation of
-the half saturation constant, that is, the time at which buildup is half
-of the maximum (asym­ptotic) value. For instance, the *KB* of 1 day for
-the saturation curve in Figure 3-3 corresponds to the time where the
-buildup reaches half the maximum amount. If the asymptotic value
-*Bmax* is known or estimated, K*B* may be obtained from buildup data
-from the slope of a plot of *b* versus *t* × (*Bmax* - *b*).
-Generally, the saturation for­mulation will rise steeply (in fact,
-linearly for small *t*) and then approach the asymptote slowly.
-
-The power function may be easily adjusted to resemble asymptotic
-behav­ior, but it must always ultimately exceed the maximum value (if
-used). The parameters are readily found from a log-log plot of buildup
-versus time. This is a common way of analyzing data, (e.g., Miller et
-al., 1978; Ammon, 1979; Smolenyak, 1979; Jewell et al., 1980; Wallace,
-1980).
-
-When applying a buildup function in dry periods in conjunction with a
-washoff function in wet periods it is useful to know the number of days
-*t* it takes to reach a given amount of buildup *b*. This can be found
-by re-arranging Equation 3-1 as follows:
-
-$$t = \left( \frac{b}{K_{B}} \right)^{\frac{1}{N_{B}}} \qquad \text{for power buildup} \qquad \text{(3-2a)}$$
-
-$$t = \frac{- ln\left( 1 - \frac{b}{B_{\max}} \right)}{K_{B}} \qquad \text{for exponential buildup} \qquad \text{(3-2b)}$$
-
-$$t = \frac{bK_{B}}{\left( B_{\max} - b \right)} \qquad \text{for saturation buildup} \qquad \text{(3-2c)}$$
-
-Note that when *NB = 0* for power buildup then buildup *b* is a
-constant value *Bmax* for all times *t*. Figure 3-4 shows how buildup
-is adjusted between and after storm events. Assume that b*0* represents
-the amount of buildup present at the start of a storm event. The event
-washes off part of that buildup leaving an amount *b1* remaining.
-Equation 3-2 is used to find the time *t1* associated with buildup *b1*.
-If a dry period of length *∆t* occurs before the start of the next
-storm, then the amount of buildup available, *b2*, is found by
-evaluating the buildup function at time *t2* = *t1* + *∆t*.
-
-

-Evolution of Buildup.png
-
Figure 3‑4 Evolution of buildup after a
-storm event

-

-
-## 3.3 Computational Steps
-
-Pollutant buildup computations are a sub-procedure implemented as part
-of SWMM's runoff calculations. They are made at each runoff time step
-for each subcatchment immediately after surface runoff has been computed
-as described in Section 3.4 of Volume I. The following constant
-quantities are known for each subcatchment:
-
-- *A* (the subcatchment area),
-
-- *L* (the curb length of streets in the subcatchment (if used to
-  normalize buildup)),
-
-- *fLU* ( the fraction of the subcatchment's area devoted to a
-  particular land use,
-
-- *Bmax*, *KB,* and *NB* for each combination of pollutant and
-  land use.
-
-Note that a pollutant's buildup constants vary by land use, not by
-subcatchment. That is, if residential land is assigned a set of buildup
-constants then those constants apply to the residential portion of all
-subcatchments. Also available is the buildup *mB* (in mass units) for
-each pollutant on each land use in the subcatchment at the start of the
-current time period. Initially at time zero, *mB* is established in
-one of two ways:
-
-1.  If the user specified an initial buildup (as mass per area) of the
-    pollutant over the entire subcatchment, then the initial *mB*
-    equals that buildup times the area devoted to the particular land
-    use.
-
-2.  Otherwise a user-supplied antecedent dry days value is used with
-    Equation 3-1 to determine an initial buildup per area (or curb
-    length) with the result multiplied by the area (or curb length)
-    associated with the land use to obtain an initial mass *mB*.
-
-The computational steps for updating the buildup of a specific
-pollutant - land use combination within a subcatchment over a single
-time step are:
-
-1.  If the runoff rate is greater than 0.001 in/hr then the time step is
-    assumed to belong to a wet weather event and no buildup addition
-    occurs (buildup will actually be reduced according to the amount of
-    washoff produced as described later in Chapter 4).
-
-2.  If buildup for the pollutant has been designated to occur only when
-    snow is present and the current snow depth is less than 0.001 inches
-    then no buildup addition occurs.
-
-3.  Convert the total mass of buildup *mB* to a normalized mass *b* by
-    dividing it by $f_{LU}A$ if buildup is normalized with respect to
-    area or $f_{LU}L$ if normalized with respect to curb length.
-
-4.  Use Equation 3-2 to find the time *t* corresponding to normalized
-    buildup *b*.
-
-5.  Add the length of the current runoff time step to *t* and use this
-    value in Equation 3-1 to find an updated value for *b*.
-
-6.  Convert the new normalized buildup *b* back to total mass *mB* by
-    multiplying it by the normalizing factor (either $f_{LU}A$ or
-    $f_{LU}L$).
-
-This process will produce a new set of pollutant mass buildups *mB* at
-the end of the runoff time step for each land use within each
-subcatchment. These buildups will then be used to compute washoff loads
-(as described in Section 4) when the next wet period occurs.
-
-## 3.4 Street Cleaning
-
-Street cleaning is performed in most urban areas for control of solids
-and trash deposited along street gutters. Although it has long been
-assumed that street cleaning has a beneficial effect upon the quality of
-urban runoff, until recently, few data have been available to quantify
-this effect. Unless performed on a daily basis, EPA Nationwide Urban
-Runoff Program (NURP) studies generally found little improvement of
-runoff quality by street cleaning (EPA, 1983b). On the other hand, more
-recent studies indicate that technological advances in cleaning
-equipment can produce much better results (Sutherland and Jelen, 1997).
-
-The most elaborate studies are probably those of Pitt (1979, 1985) in
-which street surface loadings were carefully monitored along with runoff
-quality in order to determine the effectiveness of street cleaning. In
-San Jose, California Pitt (1979) found that frequent street cleaning on
-smooth asphalt surfaces (once or twice per day) can remove up to 50
-percent of the total solids and heavy metal yields of urban runoff.
-Under more typical cleaning programs of once or twice a month, less than
-5 percent of these contaminants were removed. Organics and nutrients in
-the runoff cannot be effectively controlled by intensive street cleaning
--- typically much less than 10 percent removal, even for daily cleaning.
-This is because the latter originate primarily in runoff and erosion
-from off-street areas during storms. In Bellevue, Washington, Pitt
-(1985) reached similar conclusions, with a maximum projected
-effectiveness for pollutant removal from runoff of about 10 percent.
-
-The removal effectiveness of street cleaning depends upon many factors
-such as the type of sweeper, whether flushing is included, the presence
-of parked cars, the quantity of total solids, the constituent being
-considered, and the relative frequency of rainfall events. Obviously, if
-street sweeping is performed infrequently in relation to rainfall
-events, it will not be effective. Removal efficiencies for several
-constituents are shown in Table 3-4 (Pitt, 1979). Clearly, efficiencies
-are greater for constituents that behave as particulates.
-
-SWMM allows pollutant buildup within a given land use area to be reduced
-by street sweeping operations. This reduction is accounted for by having
-the user supply the following set of parameters:
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *SS1* | = | month/day of the year when street sweeping operations start |
-| *SS2* | = | month/day of the year when street sweeping operations end |
-| *SSI* | = | number of days between street sweeping for a given land use |
-| *SS0* | = | number of days since the land use was last swept at the start of the simulation |
-| *SSA* | = | fraction of buildup on the land use that is available for removal by sweeping |
-| *SSE* | = | fraction of the available buildup of a pollutant on a given land use that is removed by sweeping |
-
-The availability factor, SSA, is intended to account for the fraction of
-a land use's area that is actually "sweepable." A single set of *SS1*
-and *SS2* values is supplied for the entire study area, *SSI*, *SS0*,
-and *SSA* values are supplied for each land use category within the
-study area, and an SSE value is supplied for each combination of
-pollutant and land use category.
-
-+:--------------+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+:--------------:+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+:-------------:+
-| **Street      | **Total**     | **BOD5**    | **COD**       | **KN**        | **PO4**     | **Pesticides** | **Cd**        | **Sr**        | **Cu**        | **Ni**        | **Cr**        | **Zn**        | **Mn**        | **Pb**        | **Fe**        |
-| Cleaning      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Program and   | **Solids**    |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Street        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Surface**     |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| **Loading     |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Conditions**  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Vacuum Street | 31            | 24            | 16            | 26            | 8             | 33             | 23            | 27            | 30            | 37            | 34            | 34            | 37            | 40            | 40            |
-| Cleaner       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               | 45            | 35            | 22            | 37            | 12            | 50             | 34            | 35            | 45            | 54            | 53            | 52            | 56            | 59            | 59            |
-| 20 - 200      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               | 53            | 41            | 27            | 45            | 14            | 59             | 40            | 48            | 52            | 63            | 60            | 59            | 65            | 70            | 68            |
-| lb/curb mile  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| total solids  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 1 pass        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 2 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 3 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Vacuum Street | 37            | 29            | 21            | 31            | 12            | 40             | 30            | 34            | 36            | 43            | 42            | 41            | 45            | 49            | 59            |
-| Cleaner       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               | 51            | 42            | 29            | 46            | 17            | 59             | 43            | 48            | 49            | 59            | 60\           | 59            | 63            | 68            | 68            |
-| 200 - 1,000   |               |               |               |               |               |                |               |               |               |               | 66            |               |               |               |               |
-|               | 58            | 47            | 35            | 51            | 20            | 67             | 50            | 53            | 59            | 68            |               | 67            | 70            | 76            | 75            |
-| lb/curb mile  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| total solids  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 1 pass        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 2 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 3 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Vacuum Street | 48            | 38            | 33            | 43            | 20            | 57             | 45            | 44            | 49            | 55            | 53            | 55            | 58            | 62            | 63            |
-| Cleaner       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               | 60            | 50            | 42            | 54            | 25            | 72             | 57            | 55            | 63            | 70            | 68            | 69            | 72            | 79            | 77            |
-| 1,000 -       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 10,000        | 63            | 52            | 44            | 57            | 26            | 75             | 60            | 58            | 66            | 73            | 72            | 73            | 76            | 83            | 82            |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| lb/curb mile  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| total solids  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 1 pass        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 2 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 3 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Mechanical    | 54            | 40            | 31            | 40            | 20            | 40             | 28            | 40            | 38            | 45            | 44            | 43            | 47            | 44            | 49            |
-| Street        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Cleaner       | 75            | 58            | 48            | 58            | 35            | 60             | 45            | 59            | 58            | 65            | 64            | 64            | 64            | 65            | 71            |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 180 - 1,800   | 85            | 69            | 59            | 69            | 46            | 72             | 57            | 70            | 69            | 76            | 75            | 75            | 79            | 77            | 82            |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| lb/curb mile  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| total solids  |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 1 pass        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 2 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-|               |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| 3 passes      |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Flusher       | 30            | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)          | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)         | \(a\)         |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| Mechanical    | 80            | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)          | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)         | \(b\)         |
-| Street        |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Cleaner       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| followed by a |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-| Flusher       |               |               |               |               |               |                |               |               |               |               |               |               |               |               |               |
-+---------------+---------------+---------------+---------------+---------------+---------------+----------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+---------------+
-| (a) 15 - 40 percent estimated                                                                                                                                                                                                                                  |
-|                                                                                                                                                                                                                                                                |
-| (b) 35 - 100 percent estimated                                                                                                                                                                                                                                 |
-|                                                                                                                                                                                                                                                                |
-| \*These removal values assume all the pollutants would lie within the cleaner path (0 to 8 ft. from the curb)                                                                                                                                                  |
-+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-: []{#_Toc454288807 .anchor}**Table 3‑4 Removal efficiencies from street
-cleaner path for various street cleaning programs (Pitt, 1979)**
-
-If the date of the current time step falls within *SS1* and *SS2*
-then the buildup *mB* found from the previous steps of Section 3.3
-(for a specific pollutant and land use) is modified as follows:
-
-1.  If the current rainfall is above 0.001 in/hr or there is more than
-    0.05 inches of snow on the plowable impervious area of the
-    subcatchment or *SSI* was set to zero then no sweeping occurs.
-
-2.  If the time between the current date and the date when the land use
-    was last swept is less than *SSI* then no sweeping occurs.
-
-3.  Otherwise set$\ m_{B} = m_{B}(1 - SSA \bullet SSE)$ for each of the
-    land uses's pollutants and set the date when the land use was last
-    swept to the current date.
-
-## 3.5 Parameter Estimates
-
-There is no single choice of buildup function or parameter values (which
-are pollutant- and land use-specific) that can be applied universally.
-Although data from the literature can help determine representative
-estimates there is no substitute for field data collected for the site
-in question. The discussion that follows presents sources of buildup
-data from studies that were made mainly in the 1970's or earlier.
-
-The previously mentioned 1969 APWA study (APWA, 1969) was followed by
-several more efforts, notably AVCO (1970) (reporting extensive data from
-Tulsa, Oklahoma), Sartor and Boyd (1972) (reporting a cross section of
-data from ten U.S. cities), and Shaheen (1975) (reporting data for
-highways in the Washington, DC area). Pitt and Amy (1973) followed the
-Sartor and Boyd (1972) study with an analysis of heavy metals on street
-surfaces from the same ten cities. Later, Pitt (1979) reported on
-extensive data gathered both on the street surface and in run­off for San
-Jose. A drawback of the earlier studies is that it is diffi­cult to draw
-conclusions from them on the relationship between street surface
-ac­cumulation and stormwater concentra­tions since the two were seldom
-measured si­multaneously.
-
-Amy et al. (1974) provide a summary of data available in 1974 while
-Lager et al. (1977) provide a similar summary as of 1977 without the
-extensive data tabulations given by Amy et al. Perhaps the most
-comprehen­sive summary of surface accumulation and pollutant fraction
-data is pro­vided by Manning et al. (1977) in which the many problems and
-facets of sampling and measurements are also discussed. For instance,
-some data are obtained by sweeping, others by flushing; the particle
-size characteristics and degree of removal from the street surface
-differ for each method. Some results of Manning et al. (1977) will be
-presented later. Surface ac­cumulation data may be gleaned, somewhat less
-directly, from references on loading functions that include McElroy et
-al. (1976), Heaney et al. (1977) and Huber et al. (1981a). Regrettably,
-there seem to be no studies since the 1970s in which pollutant
-accumulation has been measured directly.
-
-Manning et al. (1977) have perhaps the best summary of linear buildup
-rates; these are presented in Table 3-5. It may be noted that dust and
-dirt buildup varies considerably among three different studies.
-Individual constituent buildup may be taken directly from values in the
-table or computed as a fraction of dust and dirt (simulated as a
-pollutant) using the "Co-pollutant and Co-fraction" option described
-subsequently. It is apparent that although a large number of
-constituents have been sampled, little distinction can be made on the
-basis of land uses for most of them.
-
-As an example, suppose dust and dirt (DD) is to be simulated as a
-co-pollutant and values are taken for commercial land use and from the
-"All Data" row in Table 3-5. Since the data are given as lb ·
-curb-mile-1 · day-1, linear buildup is assumed and for commercial
-land use DD buildup (average for all data) is 116 lb/(curb-mile -- day).
-Converting from pounds to milligrams (453,592 mg/lb) and mile to 1000-ft
-(5.28 1000-ft/mi) yields *KB* = 9.97 x 106 mg/1000-ft-day in
-Equation 3-1a, and of course, *NB* = 1. Constituent fractions are
-available from the table. For instance, BOD5 as a fraction of DD for
-commercial land use would be 7.19 mg/g (or 0.00719 as a SWMM
-Co-fraction), 0.06 mg/g for total phosphorus, 0.00002 mg/g for Hg, and
-36,900 MPN/g for fecal coliforms (36.9 MPN/mg as a SWMM input
-co-fraction). Direct loading rates could be computed for each
-constituent as an alternative. For instance, for BOD5, the linear
-buildup rate would equal 9.97 x 106 · 0.00719 = 3,800 mg / (1000-ft
-curb - day).
-
-Table 4-19 on pp. 4-94, 4-95, 4-96.It must be stressed once again that
-the generalized buildup data of Table 3-5 are merely informational and
-*are never a substitute for local sampling* or even a calibration using
-measured concentrations. They may serve as a first trial value for a
-calibration, however. In this respect it is important to point out that
-the concentrations and loads computed by the SWMM buildup-washoff
-algorithms are usu­ally linearly proportional to buildup rates. If twice
-the quantity is avail­able at the beginning of a storm, the
-concentrations and loads will be usually be doubled. Calibration is
-probably easiest with linear buildup parameters, but it depends on the
-rate at which the limiting build­up, i.e., *Bmax*, is approached. If
-the limiting value is reached during the inter­val between most storms,
-then calibration using it will also have almost a linear effect on
-concentrations and loads.
-
-+:----------------+:--------------+:---------------:+:-------------:+:--------------:+:--------------:+:--------------+
-| **Pollutant**   |               | **Land Use Categories**                                           | **All Data**  |
-|                 |               +-----------------+---------------+----------------+----------------+               |
-|                 |               | **Single        | **Multiple    | **Commercial** | **Industrial** |               |
-|                 |               | Family**        | Family        |                |                |               |
-|                 |               |                 | Residential** |                |                |               |
-|                 |               | **Residential** |               |                |                |               |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Dust and Dirt   |                                                                                                   |
-| Accumulation    |                                                                                                   |
-| kg/curb-km/ day |                                                                                                   |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Chicago(1)    | Mean          | 10              | 31            | 51             | 92             | 44            |
-|                 |               |                 |               |                |                |               |
-|                 | Range         | 5-27            | 17-43         | 80-151         | 80-151         | 5-15          |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 60              | 93            | 126            | 55             | 334           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Washington(2) | Mean          |                |              | 38             |               | 38            |
-|                 |               |                 |               |                |                |               |
-|                 | Range         |                |              | 10-103         |               | 10-103        |
-|                 |               |                 |               |                |                |               |
-|                 | N             |                |              | 22             |               | 22            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Multi-City(3) | Mean          | 51              | 44            | 13             | 81             | 49            |
-|                 |               |                 |               |                |                |               |
-|                 | Range         | 1-268           | 2-217         | 1-73           | 1-423          | 1-423         |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 14              | 8             | 10             | 12             | 44            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| All Data        | Mean          | 17              | 32            | 47             | 90             | 45            |
-|                 |               |                 |               |                |                |               |
-|                 | Range         | 1-268           | 2-217         | 1-103          | 1-423          | 1-423         |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 74              | 101           | 158            | 67             | 400           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| BOD g/kg        | Mean          | 5.26            | 3.37          | 7.19           | 2.92           | 5.03          |
-|                 |               |                 |               |                |                |               |
-|                 | Range         | 1.72-9.43       | 2.03-6.32     | 1.28-14.54     | 2.82-2.95      | 1.29-14.54    |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 59              | 93            | 102            | 56             | 292           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| COD g/kg        | Mean          | 39.25           | 41.97         | 61.73          | 25.08          | 46.12         |
-|                 |               |                 |               |                |                |               |
-|                 | Range         | 18.30-72.80     | 24.6-61.3     | 24.8-498.41    | 23.0-31.8      | 18.3-498.41   |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 59              | 93            | 102            | 38             | 292           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Total N-N       | Mean          | 460             | 550           | 420            | 430            | 480           |
-|                 |               |                 |               |                |                |               |
-| (mg/kg)         | Range         | 325-525         | 356-961       | 323-480        | 410-431        | 323-480       |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 59              | 93            | 80             | 38             | 270           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Kjeldahl N      | Mean          |                |              | 640            |               | 640           |
-| (mg/kg)         |               |                 |               |                |                |               |
-|                 | Range         |                |              | 230-1,790      |               | 230-1,790     |
-|                 |               |                 |               |                |                |               |
-|                 | N             |                |              | 22             |               | 22            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| NO3           | Mean          |                |              | 24             |               | 24            |
-|                 |               |                 |               |                |                |               |
-| (mg/kg)         | Range         |                |              | 10-35          |               | 10-35         |
-|                 |               |                 |               |                |                |               |
-|                 | N             |                |              | 21             |               | 21            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| NO2-N         | Mean          |                |              | 0              |               | 15            |
-|                 |               |                 |               |                |                |               |
-| (mg/kg)         | Range         |                |              | 0              |               | 0             |
-|                 |               |                 |               |                |                |               |
-|                 | N             |                |              | 15             |               | 15            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| Total P         | Mean          |                |              | 170            |               | 170           |
-|                 |               |                 |               |                |                |               |
-| (mg/kg)         | Range         |                |              | 90-340         |               | 90-340        |
-|                 |               |                 |               |                |                |               |
-|                 | N             |                |              | 21             |               | 21            |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-| PO4-P         | Mean          | 49              | 58            | 60             | 26             | 53            |
-|                 |               |                 |               |                |                |               |
-| (mg/kg)         | Range         | 20-109          | 20-73         | 0-142          | 14-30          | 0-142         |
-|                 |               |                 |               |                |                |               |
-|                 | N             | 59              | 93            | 101            | 38             | 291           |
-+-----------------+---------------+-----------------+---------------+----------------+----------------+---------------+
-
-: []{#_Toc454288808 .anchor}**Table 3‑5 Nationwide data on linear dust
-and dirt buildup rates and on pollutant fractions (after Manning et al.,
-1977)**
-
-+:--------------+:------+:---------------:+:-------------:+:--------------:+:--------------:+:-------------+
-| **Pollutant** |       | **Land Use Categories**                                           | **All Data** |
-|               |       +-----------------+---------------+----------------+----------------+              |
-|               |       | **Single        | **Multiple    | **Commercial** | **Industrial** |              |
-|               |       | Family**        | Family        |                |                |              |
-|               |       |                 | Residential** |                |                |              |
-|               |       | **Residential** |               |                |                |              |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Chlorides     | Mean  |                |              | 220            |               | 220          |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range |                |              | 100-370        |               | 100-370      |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 22             |               | 22           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Asbestos      | Mean  |                |              | 126×106      |               | 126×106    |
-|               |       |                 |               |                |                |              |
-| fibers/kg     | Range |                |              | 0-380×106    |               | 0-380×106  |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 16             |               | 16           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Silver        | Mean  |                |              | 200            |               | 200          |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range |                |              | 0-600          |               | 0-600        |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 3              |               | 3            |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Arsenic       | Mean  |                |              | 0              |               | 0            |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range |                |              | 0              |               | 0            |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 3              |               | 3            |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Barium        | Mean  |                |              | 38             |               | 38           |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range |                |              | 0-80           |               | 0-80         |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 8              |               | 8            |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Cadmium       | Mean  | 3.3             | 2.7           | 2.9            | 3.6            | 3.1          |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 0-8.8           | 0.3-6.0       | 0-9.3          | 0.3-11.0       | 0-11.0       |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 22             | 13             | 57           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Chromium      | Mean  | 200             | 180           | 140            | 240            | 180          |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 111-325         | 75-325        | 10-430         | 159-335        | 10-430       |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 30             | 13             | 65           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Copper        | Mean  | 91              | 73            | 95             | 87             | 90           |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 33-150          | 34-170        | 25-810         | 32-170         | 25-810       |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 30             | 13             | 65           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Iron          | Mean  | 21,280          | 18,500        | 21,580         | 22,540         | 21,220       |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 11,000-48,000   | 11,000-25,000 | 5,000-44,000   | 14,000-43,000  | 5,000-48,000 |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 10             | 13             | 45           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Mercury       | Mean  |                |              | 0.02           |               | 0.02         |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range |                |              | 0-0.1          |               | 0-0.1        |
-|               |       |                 |               |                |                |              |
-|               | N     |                |              | 6              |               | 6            |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Manganese     | Mean  | 450             | 340           | 380            | 430            | 410          |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 250-700         | 230-450       | 160-540        | 240-620        | 160-700      |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 10             | 13             | 45           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Nickel        | Mean  | 38              | 18            | 94             | 44             | 62           |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 0-120           | 0-80          | 6-170          | 1-120          | 1-170        |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 30             | 13             | 75           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-| Lead          | Mean  | 1,570           | 1,980         | 2,330          | 1,590          | 1,970        |
-|               |       |                 |               |                |                |              |
-| (mg/kg)       | Range | 220-5,700       | 470-3,700     | 0-7,600        | 260-3,500      | 0-7,600      |
-|               |       |                 |               |                |                |              |
-|               | N     | 14              | 8             | 29             | 13             | 64           |
-+---------------+-------+-----------------+---------------+----------------+----------------+--------------+
-
-: **Table 3-5 Continued**
-
-+:--------------+:------+:----------------:+:----------------:+:----------------:+:----------------:+:-----------------+
-| **Pollutant** |       | **Land Use Categories**                                                   | **All Data**     |
-|               |       +------------------+------------------+------------------+------------------+                  |
-|               |       | **Single         | **Multiple       | **Commercial**   | **Industrial**   |                  |
-|               |       | Family**         | Family           |                  |                  |                  |
-|               |       |                  | Residential**    |                  |                  |                  |
-|               |       | **Residential**  |                  |                  |                  |                  |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Antimony      | Mean  |                 |                 | 54               |                 | 54               |
-|               |       |                  |                  |                  |                  |                  |
-| (mg/kg)       | Range |                 |                 | 50-60            |                 | 50-60            |
-|               |       |                  |                  |                  |                  |                  |
-|               | N     |                 |                 | 3                |                 | 3                |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Selenium      | Mean  |                 |                 | 0                |                 | 0                |
-|               |       |                  |                  |                  |                  |                  |
-| (mg/kg)       | Range |                 |                 | 0                |                 | 0                |
-|               |       |                  |                  |                  |                  |                  |
-|               | N     |                 |                 | 3                |                 | 3                |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Tin           | Mean  |                 |                 | 17               |                 | 17               |
-|               |       |                  |                  |                  |                  |                  |
-| (mg/kg)       | Range |                 |                 | 0-50             |                 | 0-50             |
-|               |       |                  |                  |                  |                  |                  |
-|               | N     |                 |                 | 3                |                 | 3                |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Strontium     | Mean  | 32               | 18               | 17               | 13               | 21               |
-|               |       |                  |                  |                  |                  |                  |
-| (mg/kg)       | Range | 5-110            | 12-24            | 7-38             | 0-24             | 0-110            |
-|               |       |                  |                  |                  |                  |                  |
-|               | N     | 14               | 8                | 10               | 13               | 45               |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Zinc          | Mean  | 310              | 280              | 690              | 280              | 470              |
-|               |       |                  |                  |                  |                  |                  |
-| (mg/kg)       | Range | 110-810          | 210-490          | 90-3,040         | 140-450          | 90-3,040         |
-|               |       |                  |                  |                  |                  |                  |
-|               | N     | 14               | 8                | 30               | 13               | 65               |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Fecal Strep   | Geo.  |                 |                 | 370              |                 | 370              |
-|               | Mean  |                  |                  |                  |                  |                  |
-| No./gram      |       |                 |                 | 44-2,420         |                 | 44-2,420         |
-|               | Range |                  |                  |                  |                  |                  |
-|               |       |                 |                 | 17               |                 | 17               |
-|               | N     |                  |                  |                  |                  |                  |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Fecal Coli    | Geo.  | 82,500           | 38,800           | 36,900           | 30,700           | 94,700           |
-|               | Mean  |                  |                  |                  |                  |                  |
-| No./gram      |       | 26-130,000       | 1,500-106      | 140-970,000      | 67-530,000       | 26-1,000,000     |
-|               | Range |                  |                  |                  |                  |                  |
-|               |       | 65               | 96               | 84               | 42               | 287              |
-|               | N     |                  |                  |                  |                  |                  |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-| Total         | Geo.  | 891,000          | 1,900,000        | 1,000,000        | 419,000          | 1,070,000        |
-| Coliform      | Mean  |                  |                  |                  |                  |                  |
-|               |       | 25,000-3,000,000 | 80,000-5,600,000 | 18,000-3,500,000 | 27,000-2,600,000 | 18,000-5,600,000 |
-| No./gram      | Range |                  |                  |                  |                  |                  |
-|               |       | 65               | 97               | 85               | 43               | 290              |
-|               | N     |                  |                  |                  |                  |                  |
-+---------------+-------+------------------+------------------+------------------+------------------+------------------+
-
-: **Table 3-5 Continued**
-
-# Chapter 4 - Surface Washoff
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 4.1 Introduction
-
-Washoff is the process of erosion or dissolving of constituents from a
-subcatchment surface during a period of runoff. If the water depth is
-more than a few millimeters, erosion may be described by sediment
-transport theory in which the mass flow rate of sediment is proportional
-to flow and bottom shear stress, and a critical shear stress can be used
-to determine incipient motion of a particle resting on the bottom of a
-stream channel (Graf, 1971; Vanoni, 1975). Such a mechanism might apply
-over pervious areas and in street gutters and larger channels. For thin
-overland flow, however, rainfall energy can also cause particle
-detachment and motion. This effect is often incorporated into predictive
-methods for erosion from pervious areas (Wischmeier and Smith, 1958;
-Haan et al., 1994; Bicknell et al., 1997) and may also apply to washoff
-from impervious surfaces, although in this latter case, the effect of a
-limited supply (buildup) of the material must be considered.
-
-## 4.2 Governing Equations
-
-Ammon (1979) reviewed several theoretical approaches for urban runoff
-washoff and concluded that although the sediment transport based theory
-is attractive, it is often insufficient in practice because of lack of
-data for parameter (e.g., shear stress) evaluation, sensitivity to time
-step and discretization and because simpler methods usually work as well
-(still with some theoretical basis) and are usually able to duplicate
-observed washoff phenomena. SWMM therefore incorporates three different
-choices of empirical models to represent pollutant washoff: exponential
-washoff, rating curve washoff, and event mean concentration (EMC)
-washoff.
-
-### 4.2.1 Exponential Washoff
-
-The most oft-cited results for pollutant washoff behavior are those of
-Sartor and Boyd (1972), shown in Figure 4-1, in which constituents were
-flushed from streets using a sprinkler system. From the figure it would
-appear that an exponential relationship could be developed to describe
-washoff of the form:
-
-$$W(t) = m_{B}(0)(1 - e^{- kt}) \qquad \text{(4-1)}$$
-
-where *W* = the cumulative mass of constituent washed off at time *t*,
-*mB(0)* = the initial mass of constituent on the surface at time 0,
-and *k* = a coefficient.
-
-It is clear that the coefficient, *k*, is a function of both particle
-size and runoff rate. An analysis of the Sartor and Boyd (1972) data by
-Ammon (1979) indicates that *k* increases with runoff rate, as would be
-expected, and decreases with particle size.
-
-

-
-
Figure 4‑1 Washoff of street solids by
-flushing with a sprinkler system (from Sartor and Boyd,
-1972)

-

-
-The Sartor and Boyd data lend credibility to the washoff assumption
-included in the original SWMM release (and all versions to date) that
-the rate of washoff, *w*, (e.g., mg/hr) at any time is proportional to
-the remaining pollutant buildup:
-
-$$w = \frac{dm_{B}}{dt} = - km_{B} \qquad \text{(4-2)}$$
-
-It follows then that the amount of buildup *B* remaining on the surface
-after a time *t* of washoff is:
-
-$$m_{B}(t) = m_{B}(0)e^{- kt} \qquad \text{(4-3)}$$
-
-This relation was first proposed by Mr. Allen J. Burdoin, a consultant
-to Metcalf and Eddy, during the original SWMM development. The
-coefficient *k* may be evaluated by assuming it is proportional to
-runoff rate:
-
-$$k = K_{W}q \qquad \text{(4-4)}$$
-
-where *KW* = a washoff coefficient (in-1) and *q* = the runoff rate
-over the subcatchment (in/hr).
-
-Burdoin assumed that one-half inch of total runoff in one hour would
-wash off 90 percent of the initial surface load, leading to the now
-familiar (in SWMM modeling circles) value of *KW* of 4.6 in.-1. (The
-actual time distribution of intensity does not affect the calculation of
-*KW.*) To the authors' knowledge, there are no direct measurements to
-validate this assumption, which is so often employed.
-
-Sonnen (1980) estimated values for *KW* from sediment transport theory
-ranging from 0.052 to 6.6 in.-1, increasing as particle diameter
-decreases, rainfall intensity decreases, and as catchment area
-decreases. He pointed out that 4.6 in.-1 is relatively large compared
-to most of his calculated values. Although the exponential washoff
-formulation of Equations 4-2 and 4-3 is not completely satisfactory as
-explained below, it has been verified experimentally by Nakamura (1984a,
-1984b), who also showed the dependence of the coefficient *k* on slope,
-runoff rate and cumulative runoff volume.
-
-It was found that the original exponential washoff formulation did not
-adequately fit some data (Huber and Dickinson, 1988) since making *k* be
-linearly dependent on runoff rate *q* always produced decreasing washoff
-concentrations as a function of time. To see this, substitute (4-4) into
-(4-2) and convert the mass rate *w* to a concentration by dividing by
-the volumetric runoff rate *qA*, where *A* is the subcatchment area:
-
-$$c = \frac{(\frac{dm_{B}}{dt})}{qA} = \frac{K_{W}qm_{B}}{qA} = \frac{K_{W}m_{B}}{A} \qquad \text{(4-5)}$$
-
-Thus concentration *c* would decrease continually as the remaining
-buildup *mB* does the same over time. To avoid this behavior, the
-relationship in (4-4) was modified to be:
-
-$$k = K_{W}q^{N_{W}} \qquad \text{(4-6)}$$
-
-where *NW* is a washoff exponent. The resulting equation for
-exponential washoff now becomes:
-
-$$w = K_{W}q^{N_{W}}m_{B} \qquad \text{(4-7)}$$
-
-with units of mass/hour.
-
-### 4.2.2 Rating Curve Washoff
-
-In natural catchments and rivers, both theory and data support the
-result that load rate of sediment is proportional to flow rate raised to
-a power. For instance, sediment data from streams can usually be
-described by a sediment rating curve of the form
-
-$$w = K_{W}Q^{N_{W}} \qquad \text{(4-8)}$$
-
-where *w* is sediment loading rate (mass/sec), *Q* is flow rate (cfs),
-and *KW* and *NW* are coefficients. Due to a hysteresis effect,
-such relationships may vary during the passing of a flood wave, but the
-functional form is evident in many rivers, e.g., Vanoni (1975), pp.
-220-225, Graf (1971), pp. 234-241, and Simons and Senturk (1977), p.
-602. Of particular relevance to overland flow washoff is the appearance
-of similar relationships describing sediment yield from a catchment
-e.g., Vanoni (1975), pp. 472-481.
-
-Note the similarity of Equation 4-8 to the exponential washoff function
-4-7. The presence of buildup *mB* in Equation 4-7 reflects the fact
-that the total quantity of sediment washed off a largely impervious
-urban area is likely to be limited to the amount built up during dry
-weather. Natural catchments and rivers from which Equation 4-8 is
-derived generally have no source limitation.
-
-Also note that the form of the runoff rate used in the two functions is
-different. Exponential washoff uses a normalized runoff rate, *q* in
-(inches/hr), over the total subcatchment surface (both pervious and
-impervious areas). Rating curve washoff uses the volumetric runoff rate
-*Q* in cfs, over the fraction *fLU* of total subcatchment area *A* (in
-acres) devoted to the land use being analyzed. That is,
-
-$$Q = qf_{LU}A \qquad \text{(4-9)}$$
-
-The rating curve approach may be combined with constituent buildup if
-desired to limit the total mass that can be washed off. Otherwise, there
-is no buildup between storms during continuous simulation, nor will
-measures like street sweeping have any effect. Constituents will be
-generated solely on the basis of flow rate.
-
-If buildup is simulated when a rating curve is used, the maximum amount
-that can be removed is the amount built up prior to the storm. It will
-have an effect only if this limit is reached, at which time loads and
-concentrations will suddenly drop to zero. They will not assume non-zero
-values again until dry-weather time steps occur to allow buildup. Street
-sweeping will have an effect if the buildup limit is reached.
-
-The rating curve method is generally easiest to use when only total
-runoff volumes and pollutant loads are available for calibration.
-
-### 4.2.3 EMC Washoff
-
-As a part of NPDES stormwater permitting and as a result of many special
-studies, there are numerous sources of local event mean concentration
-(EMC) data available for stormwater. EMC values are usually measured by
-laboratory analysis of flow- and time-weighted composite samples. EMCs
-are often the only samples available, in order to save on laboratory
-costs that would be involved in measurements of several points along the
-storm hydrograph, although the latter, intra-event samples are
-particularly valuable data. As a practical matter, EMCs are the most
-common parameters used to estimate nonpoint water quality loads in SWMM
-and in most other models. The EMC washoff function has the form:
-
-$$w = K_{W}qf_{LU}A \qquad \text{(4-10)}$$
-
-where now *KW* is the EMC concentration expressed in the same
-volumetric units as flow rate (e.g., if the EMC is in mg/L and flow is
-in cfs then *KW* = EMC × 28.3 L/ft3). As with rating curve washoff,
-$qf_{LU}A$ is the fraction of the total runoff rate that applies to the
-land use being analyzed. With EMC washoff all storms will have identical
-within-storm washoff concentrations. Only the loading rate will vary in
-direct proportion to runoff rate.
-
-### 4.2.4 Comparison of Models
-
-Table 4-1 lists the units of the washoff coefficient *KW* for the
-three different washoff models, assuming pollutant mass units of
-milligrams. Take note that the units of washoff rate *w* are mass/hr for
-exponential washoff and mass/sec for the other two functions. Also note
-that the runoff rate used in the washoff equations, whether *q* or *Q*,
-is based on the runoff computed for the entire subcatchment before any
-internal routing between the impervious and pervious sub-areas takes
-place (see Volume I for more details on internal runoff routing). The
-runoff rate actually leaving the subcatchment, which is what SWMM
-reports to the user, will always be a lower number when the internal
-routing option is used.
-
-  -----------------------------------------------------------------------
-  **Model (Washoff          **US Units (flow in     **SI Units (flow in
-  Units)**                        cfs)**                  cms)**
-
-|  |  |  |
-| --- | --- | --- |
-| Exponential (mg/hr) | (in/hr)-NW hr-1   (mm/hr)-NW hr-1 |
-| Rating Curve (mg/sec) | (mg/sec) (cfs)-NW   (mg/sec) (cms)-NW |
-| EMC (mg/sec) | mg/ft3 | mg/m3 |
-
-
-  : []{#_Toc454288809 .anchor}**Table 4‑1 Units of the washoff
-  coefficient *KW* for different washoff models**
-
-Figure 4-2 compares the shapes of the runoff pollutgraphs for the three
-different washoff functions for an initial buildup of 20 lbs of
-pollutant over a one acre catchment subjected to a 2-inch, 6-hour storm
-with a triangular-shaped runoff hydrograph. To make the functions
-comparable, their coefficients were selected so that the storm would
-remove about 45 percent of the initial buildup. The resulting
-coefficient values are:
-
-  -----------------------------------------------------------------------
-  **Function**                     ***KW***              ***NW***
-
-|  |  |  |
-| --- | --- | --- |
-| Exponential | 0.45 (in/hr)-1.5(h | r)-1          1.5 |
-| Rating Curve | 850 (mg/sec)(cfs)-1.5< | /sup>           1.5 |
-| EMC | 20 mg/L x 28.3 L/ft3            \- |
-
-
-

-washoff.png
-
Figure 4‑2 Comparison of washoff
-functions

-

-
-It is possible to estimate a *KW* for rating curve washoff that will
-produce results roughly similar to those for exponential washoff by
-multiplying the exponential *KW* by an average buildup seen over a
-storm event and converting from mass/hr to mass/sec. So for this
-example, assuming an average buildup of 15 lb over the event, the result
-is:
-
-> $$K_{W,\ RC} = 0.45 \times 15\ lb\  \times 454000\ (\frac{mg}{lb)\  \times (\frac{1}{3600)\ (\frac{hr}{sec) \approx 850}}}$$
-
-The exponential *KW* value of 0.45 was selected by trial and error to
-achieve the target of removing 45 percent of the initial buildup.
-
-### 4.2.5 Wet Deposition and Runon
-
-In addition to the washoff of constituents deposited during dry periods,
-subcatchment runoff may also contain pollutant loads contributed by
-direct rainfall and by runon from upstream subcatchments. The
-instantaneous loading rates from these two streams cannot simply be
-added onto the loads computed from the washoff functions described
-earlier because they must first be routed through the volume of water
-(shallow as it may be) that ponds atop the surface of the subcatchment.
-See Volume I for a description of how SWMM uses a nonlinear reservoir
-model to describe surface runoff. Consistent with the way that the flow
-from direct rainfall and runon is treated, these pollutant streams are
-completely mixed with the current contents of the ponded water and a
-mass balance is performed to find the pollutant mass from these sources
-leaving the ponded surface water over the computational time step. This
-mass flux is added to the mass flux computed from the washoff functions
-to arrive at a total washoff amount.
-
-Figure 4-3 depicts this two stream approach to handling washoff from
-both pollutant buildup and from rainfall/runon. A mass balance for the
-pollutant and volume of the washoff stream originating from the ponded
-surface water that receives upstream run-on and direct deposition can be
-written as:
-
-$$\frac{d\left( V_{ponded}C_{ponded} \right)}{dt} = Q_{runon}C_{runon} + Q_{ppt}C_{ppt} - C_{ponded}\left( Q_{infil} + Q_{out} \right) \qquad \text{(4-11)}$$
-
-$$\frac{dV_{ponded}}{dt} = Q_{runon} + Q_{ppt} - Q_{infil} - Q_{evap} - Q_{out} \qquad \text{(4-12)}$$
-
-with the variables defined as follows:
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *Vponded* | = | volume of water ponded over the subcatchment (ft3) |
-| *Cponded* | = | concentration of pollutant in the ponded water (mg/L) |
-| *Qrunon* | = | flow rate of runon onto the subcatchment (cfs) |
-| *Crunon* | = | concentration of pollutant in the runon stream (mg/L) |
-| *Qppt* | = | precipitation rate (cfs) |
-| *Cppt* | = | concentration of pollutant in precipitation (mg/L) |
-| *Qinfil* | = | infiltration rate (cfs) |
-| *Qevap* | = | evaporation rate (cfs) |
-| *Qout* | = | rate of runoff leaving the subcatchment (cfs). |
-
-

-PollutWashoff.png
-
Figure 4‑3 Two-stream approach to modeling
-pollutant washoff

-

-
-Note the following:
-
-1.  Equations 4-11 and 4-12 are applied to the subcatchment as a whole,
-    not to its separate impervious and pervious sub-areas.
-
-2.  Precipitation, infiltration, and evaporation rates have been
-    converted from their more conventional units of inches/hr to cfs by
-    multiplying by the subcatchment's area.
-
-3.  Infiltration removes a proportional amount of mass regardless of
-    constituent.
-
-4.  Evaporation removes volume but not mass causing *Cponded* to
-    increase.
-
-5.  *Qout* is the total runoff flow leaving the subcatchment. It can
-    be lower than the *Qrunoff* used in the buildup washoff functions
-    if internal routing between sub-areas is employed.
-
-6.  The only unknown to solve for is *Cponded*, since all flow rates
-    and volumes are known from the runoff calculations done prior to
-    washoff analysis.
-
-*Wwashoff* is the total washoff rate obtained by adding together the
-washoff rates *w* computed for the buildup on each land use. The runoff
-load from ponded surface storage, *Wponded*, is *Qout Cponded.*
-The total mass flow rate of pollutant leaving the subcatchment,
-*Wout*, is *Wwashoff* + *Wponded*. And finally, the concentration
-of pollutant in the subcatchment's runoff is *Wout / Qout*.
-
-Note that this scheme requires that an additional set of state variables
-be kept track of over a simulation, namely the ponded mass
-($m_{P} = V_{ponded}C_{ponded}$) for each pollutant in each
-subcatchment.
-
-### 4.2.6 BMP Removal
-
-Both washoff and ponded pollutant loads may be reduced by applying a BMP
-removal factor to them. This factor is meant to reflect the effect that
-some assumed best management practice (BMP) would have in removing a
-surface runoff pollutant. Examples of such BMPs are vegetated swales,
-overland flow, and riparian buffer strips. Typical removals for these
-practices are listed in Table 4-2.
-
-  -----------------------------------------------------------------------
-  **Constituent**          **Vegetated Swales**      **Buffer Strips**
-
-|  |  |  |
-| --- | --- | --- |
-| Total Nitrogen | 0 -- 25 | 20 -- 60 |
-| Total Phosphorus | 29 -- 45 | 20 -- 60 |
-| Suspended Solids | 60 -- 83 | 20 -- 80 |
-| Heavy Metals | 35 | 20 - 80 |
-
-
-  : []{#_Toc454288810 .anchor}**Table 4‑2 Percent removals for vegetated
-  swales and filter strips**
-
-Source: ASCE (2001).
-
-A different BMP removal factor can be associated with each pollutant and
-category of land use. For washoff of surface buildup, they are applied
-separately to the washoff rate computed for each pollutant in each land
-use in a given subcatchment:
-
-$$W_{washoff} = \sum_{j}^{}{w_{jp}(1 - R_{jp})} \qquad \text{(4-13)}$$
-
-where *Wwashoff* is the total washoff rate (mass/sec) from buildup of
-pollutant *p* over the subcatchment, *wjp* is the washoff rate of
-pollutant *p* over land use *j* in the subcatchment*,* and *Rjp* is
-the BMP removal factor for pollutant p and land use j.
-
-For the pollutant load from rainfall/runon across the entire
-subcatchment (and therefore all land uses) an area weighted average
-removal factor is used:
-
-$$R_{avg,p} = \frac{\sum_{j}^{}{R_{jp}A_{j}}}{\sum_{j}^{}A_{j}} \qquad \text{(4-14)}$$
-
-where *Aj* is the area of land use *j* in the subcatchment. Thus
-*Wponded* for pollutant *p* in the subcatchment becomes:
-
-$$W_{ponded} = Q_{out}C_{ponded}(1 - R_{avg,p}) \qquad \text{(4-15)}$$
-
-where it is understood that *Qout* and *Cponded* refer to the
-pollutant and subcatchment of interest.
-
-## 4.3 Computational Steps
-
-Pollutant washoff computations are a sub-procedure implemented as part
-of SWMM's runoff calculations. They are made at each runoff time step
-for each subcatchment immediately after surface runoff has been computed
-as described in Section 3.4 of Volume I. They follow a three-stage
-process that first computes the loading rate for each constituent due to
-washoff of surface buildup, then adds to that the loading rate from
-rainfall/runon, and finally divides the total loading rate by the runoff
-flow rate to arrive at a constituent concentration in the runoff leaving
-the subcatchment.
-
-### 4.3.1 Washoff Load from Buildup
-
-This first phase finds the mass flow rate of each pollutant resulting
-from washoff of dry deposition buildup. The following quantities are
-known for each subcatchment, pollutant, and user-defined land use at the
-start of the current time step of length *∆t*:
-
-| Symbol | Description |
-| --- | --- |
-| *KW*, *NW* | washoff coefficients for each pollutant -- land use combination |
-| *Rjp* | BMP removal factor for each pollutant -- land use combination |
-| *A* | subcatchment area (acres) |
-| $f_{LUj}$ | fraction of subcatchment area occupied by each land use *j* |
-| *q* | runoff rate per unit area before any internal re-routing is made (in/hr) |
-| $m_{Bjp}$ | mass of buildup of each pollutant *p* on each land use area *j* of the subcatchment |
-
-The computational steps for finding the washoff rate from pollutant
-buildup on a particular subcatchment at the current time step are:
-
-1.  Initialize the washoff rate of each pollutant *p* over the entire
-    subcatchment, *Wwashoff,p*, to 0.
-
-2.  For each combination of pollutant *p* and land use *j* do the
-    following:
-
-    a.  If the runoff rate *q* is less than 0.001 in/hr or if buildup is
-        being modeled and its current value is zero then the washoff
-        rate *wjp* = 0.
-
-    b.  Otherwise use the appropriate washoff function (Equation 4-7,
-        4-8, or 4-10) to find the washoff rate $w_{jp}$ for each
-        pollutant and land use. For rating curve and EMC functions use a
-        flow rate of$\ Q = qf_{LUj}A$.
-
-    c.  Reduce the buildup by the amount of washoff over the time step:
-        $m_{Bjp} = m_{Bjp} - w_{jp}\mathrm{\Delta}t$.
-
-    d.  Reduce the washoff rate by the BMP removal factor:
-        $w_{jp} = w_{jp}(1 - R_{jp})$.
-
-    e.  Add the washoff rate for this land use to the total rate
-        *Wwashoff,p* for the subcatchment:
-        $W_{washoff,p} = W_{washoff,p} + w_{jp}$.
-
-3.  After all land uses and pollutants have been evaluated, increase the
-    total washoff rate of pollutant *p* by the amount contributed by any
-    co-pollutant *k*:
-    $W_{washoff,p} = W_{washoff,p} + f_{pk}W_{washoff,k}$ where *fpk*
-    is the co-pollutant fraction.
-
-### 4.3.2 Washoff Load from Rainfall/Runon
-
-The next phase of the washoff calculations evaluates the contribution
-that pollutant loads in direct rainfall and upstream runon make to the
-total washoff load from a given subcatchment. The following quantities
-are known for each subcatchment and pollutant at the start of the
-current time step of length *∆t* seconds:
-
-| Symbol | Description |
-| --- | --- |
-| *Qppt* | precipitation rate over the subcatchment (cfs) |
-| *Cppt* | concentration of pollutant in precipitation (mass/ft3) |
-| *Qrunon* | rate of runon flow onto the subcatchment (cfs) |
-| *Wrunon* | rate of mass flow of pollutant in runon to subcatchment (mass/sec) |
-| *Qout* | flow rate of runoff leaving the subcatchment (cfs) |
-| *d1* | depth of ponded water over the subcatchment at the start of the time step (ft) |
-| *d2* | depth of ponded water over the subcatchment at the end of the time step (ft) |
-| *mP* | mass of ponded pollutant over the subcatchment at the start of the time step |
-| *Ravg* | area averaged BMP removal factor for the pollutant |
-| *A* | area of the subcatchment (ft2) |
-
-*Qppt, Qrunon, Qout*, *d1* and *d2* are known from the runoff
-calculation that has already been made for the current time step.
-*Wrunon* was also evaluated by summing the products of runoff flow and
-concentration from the previous time step for each of the upstream
-subcatchments that send their runoff to the subcatchment being analyzed.
-
-The following steps are used to compute the rate at which pollutant mass
-from rainfall/runon is washed off a given subcatchment.
-
-1.  Find the initial ponded surface volume plus the volume of
-    rainfall/runon over the current time step:
-    $V_{ponded} = d_{1}A + (Q_{ppt} + Q_{runon})\mathrm{\Delta}t$.
-
-2.  Do the same for the pollutant mass:
-    $M_{Ponded} = m_{p} + {(Q}_{ppt}C_{ppt} + W_{runon})\mathrm{\Delta}t$.
-
-3.  Compute a concentration for this pollutant mass:
-    $C_{ponded} = M_{ponded}/V_{ponded}$.
-
-4.  Find the rainfall/runon mass remaining at the end of the time step:
-    $m_{p} = C_{ponded}d_{2}A$.
-
-5.  Find the rate of mass leaving the subcatchment volume, adjusted for
-    any BMP removal: $W_{ponded} = Q_{out}C_{ponded}(1 - R_{avg})$.
-
-Note that the effects of mass lost to infiltration and volume loss due
-to evaporation are implicitly accounted for in step 5 where the
-end-of-time step volume *d2A* is used to find the mass of pollutant
-remaining on the subcatchment.
-
-### 4.3.3 Total Washoff Load and Concentration
-
-The final phase of the calculation adds together the two mass flow
-streams to arrive at a total washoff loading rate, *Wout*for the
-subcatchment and pollutant being analyzed:
-
-$$W_{out} = W_{washoff} + W_{ponded} \qquad \text{(4-16)}$$
-
-The concentration of pollutant in the subcatchment's outflow runoff at
-the end of the current time step is then:
-
-$$C_{out} = \frac{W_{out}}{28.3Q_{out}} \qquad \text{(4-17)}$$
-
-with units of mass//L. If the subcatchment in question sends its runoff
-to another subcatchment then *Wout* becomes part of *Wrunon* for the
-receiving subcatchment at the subsequent time step. If the runoff is
-sent to a node of the conveyance network then *Wout*, along with any
-other pollutant inflow loads from other subcatchments or external
-sources (such as dry weather flows and user-supplied inflows), become
-inputs to SWMM's quality routing routine which is described in the next
-chapter of this manual.
-
-## 4.4 Parameter Estimates
-
-As with buildup, there is no single choice of washoff function or
-parameter values (which are pollutant- and land use-specific) that can
-be applied universally. Although data from the literature can help
-determine representative estimates there is no substitute for field data
-collected for the site in question.
-
-Results from sediment transport theory can be used to provide guidance
-for the magnitude of parameters *KW* and *NW* used for exponential
-and rating curve washoff. Values of the exponent *NW* range between
-1.1 and 2.6 for rivers and sediment yield from catchments, with most
-values near 2.0. Typically, the exponent tends to decrease (approach
-1.0) at high flow rates (Vanoni, 1975, p. 476), indicating a constant
-concentration (not a function of flow). In SWMM, constituent
-concentrations will follow runoff rates better if *NW* is higher. A
-reasonable first guess for *NW* would appear to be in the range of
-1.5-2.5.
-
-Values of *KW* are much harder to infer from the sediment rating curve
-data since the latter vary in nature by almost five orders of magnitude.
-The issue is further complicated by the fact that Equation ‎4-7 includes
-the quantity remaining to be washed off, *mB*, which decreases
-steadily during an event. At this point it will suffice to say that
-values of *KW* between 1.0 and 10 (U.S. units) appear to give
-concentrations in the range of most observed values in urban runoff.
-Both *KW* and *NW* may be varied in order to calibrate the model to
-observed data.
-
-The preceding discussion assumes that urban runoff quality constituents
-will behave in some manner similar to "sediment" of sediment transport
-theory. Since many constituents are in particulate form the assumption
-may not be too bad. If the concentration of a dissolved constituent is
-observed to decrease strongly with increasing flow rate, a value of
-*NW* \< 1.0 could be used.
-
-Although the development has ignored the physics of rainfall energy in
-eroding particles, the runoff rate, *q*, in Equation 4-7 closely follows
-rainfall intensity. Hence, to some degree at least, greater washoff will
-be experienced with greater rainfall rates. As an option, soil erosion
-literature could be surveyed to infer a value of *NW* if erosion is
-proportional to rainfall intensity to a power.
-
-Figure 4-4 illustrates the effect that different values of *KW* and
-*NW* can have on the washoff rate as runoff rate varies during a storm
-event. The results are for an initial buildup load of 1000 mg on a 1
-acre catchment. By varying *NW* especially, the shape of the curve may
-be varied to match local data. Also note the hysteresis effect that the
-decreasing level of *mB* has on washoff for the triangular hydrograph.
-Washoff is higher for flows on the ascending limb of the hydrograph
-because there is higher buildup available and lower during the
-descending limb since there is less buildup present.
-
-  ---------------------------------------------------------------------------------------------------------------------------
-  ![](./VolumeIII/media/media/image15.png){width="3.3472222222222223in"   ![](./VolumeIII/media/media/image16.png){width="3.3in"
-  height="2.49375in"}                                           height="2.573611111111111in"}
-  ------------------------------------------------------------- -------------------------------------------------------------
-  ![](./VolumeIII/media/media/image17.png){width="3.3069444444444445in"   ![](./VolumeIII/media/media/image18.png){width="3.3069444444444445in"
-  height="2.573611111111111in"}                                 height="2.573611111111111in"}
-
-  ---------------------------------------------------------------------------------------------------------------------------
-
-  : []{#_Toc454288772 .anchor}**Figure 4‑4 Simulated load variations
-  within a storm as a function of runoff rate**
-
-Procedures for calibrating SWMM's buildup and washoff parameters have
-been developed by Jewell et al. (1978), Alley (1981), and Baffaut and
-Delleur (1990). The challenge of calibrating the exponential washoff
-parameters to individual storm events is that different events will
-produce different parameter estimates. An example of this is the study
-made by Avellaneda et al. (2009). Estimating washoff parameters by
-minimizing the sum of squared differences between the observed and
-predicted suspended solids concentrations for each of 22 different storm
-events on a 7.4 acre parking lot resulted in a coefficient of variation
-(CV or standard deviation / mean) for *KW* of 1.8. (The CV for *NW*
-was only 0.2). Such variability presents problems in selecting a single
-set of values that will generate reliable pollutographs in future
-simulations.
-
-Reproducing the time variation of washoff concentration within a storm
-event may be too lofty a goal to achieve given the simplified
-representation of the washoff process in SWMM. Instead, it might be more
-realistic to calibrate against the total mass of washoff produced over a
-number of storm events. This is the approach used by Behera et al.
-(2006) using a probabilistic model and by Tetra Tech (2010) using SWMM
-itself. In the latter case, the choice of parameter values was based on
-achieving a target annual pollutant loading (lbs/ac-yr) for each
-combination of pollutant and land use over a multi-year period of
-rainfall record. Table 4-3 shows the results achieved for the power
-buildup model and exponential washoff model for high-density residential
-land use.
-
-+------------------+----------------------------------------+-------------------------+-----------------------------------------+
-| **Pollutant1** | **Buildup**                            | **Washoff**             | **Calibration Results (kg/ac/yr)**      |
-|                  +--------------+------------+------------+------------+------------+------------+----------------+-----------+
-|                  | ***Bmax*** | ***KB*** | ***NB*** | ***KW*** | ***NW*** | **Target** | **Calibrated** | **Error** |
-+==================+:============:+:==========:+:==========:+:==========:+:==========:+:==========:+:==============:+:=========:+
-| TP               | 4.75         | 0.031      | 0.42       | 0.71       | 1.37       | 0.45       | 0.449          | 0.2%      |
-+------------------+--------------+------------+------------+------------+------------+------------+----------------+-----------+
-| TSS              | 28.12        | 0.76       | 1.26       | 5.91       | 1.46       | 190.51     | 190.57         | 0%        |
-+------------------+--------------+------------+------------+------------+------------+------------+----------------+-----------+
-| TN               | 18.94        | 0.027      | 0.88       | 4.31       | 0.57       | 2.81       | 2.811          | 0.04%     |
-+------------------+--------------+------------+------------+------------+------------+------------+----------------+-----------+
-| Zn               | 4.78         | 0.013      | 0.088      | 7.22       | 1.11       | 0.32       | 0.322          | 0.6%      |
-+------------------+--------------+------------+------------+------------+------------+------------+----------------+-----------+
-
-: []{#_Toc454288811 .anchor}**Table 4‑3 Buildup/washoff calibration
-against annual loading rate for high-density residential land use**
-
-1TP = total phosphorus, TSS = total suspended solids, TN = total
-nitrogen and Zn = zinc.
-
-Source: Tetra Tech (2010).
-
-The exponential washoff model is most suitable when the pollutant load
-(mass/sec) versus runoff flow monitored during a storm event plot as a
-loop, as in Figure 4-4, since it tends to produce lower loads at the end
-of storm events as the buildup supply becomes depleted. The rating curve
-washoff model will work better when the load versus flow data plot as a
-straight line on log-log axes. On the basis of the previous discussion
-of rating curves based on sediment data, it is expected that the
-exponent, *NW*, would be in the range of 1.5 to 3.0 for constituents
-that behave like particulates. For dissolved constituents, the exponent
-will tend to be less than 1.0 since concentration often decreases as
-flow increases, and concentration is proportional to flow to the power
-*NW* - 1. (Constant concentration would use *NW* = 1.0.) Much more
-variability is expected for *KW*. The rating curve method is generally
-easiest to use when only total runoff volumes and pollutant loads are
-available for calibration. In this case a pure regression approach
-should suffice to determine parameters *KW* and *NW*.
-
-As a part of the NPDES stormwater permitting program and as a result of
-many special studies, there are numerous sources of local event mean
-concentration (EMC) data available for stormwater. EMC values are
-usually measured by laboratory analysis of flow- and time-weighted
-composite samples. EMCs are often the only samples available, in order
-to save on laboratory costs that would be involved in measurements of
-several points along the storm hydrograph, although the latter,
-intra-event samples are particularly valuable data. As a practical
-matter, EMCs are the most common parameters used to estimate nonpoint
-water quality loads in SWMM and in most other models.
-
-A primary source of EMC data is the Nationwide Urban Runoff Program
-(NURP), conducted by EPA in the early 1980s (US EPA, 1983). Sampling was
-conducted for 28 NURP projects which included 81 specific sites and more
-than 2,300 separate storm events. Table 2-3 presents a summary of the
-EMCs found from that study. The Center for Watershed Protection has put
-together a more comprehensive list of national EMCs that includes not
-just the NURP results but also additional data obtained from the U.S.
-Geological Survey (USGS), as well as stormwater monitoring conducted for
-EPA's National Pollutant Discharge Elimination System (NPDES) stormwater
-program. These are shown in Table 4-4.
-
-When evaluating stormwater EMC data, it is important to keep in mind
-that regional EMCs can differ sharply from the reported national
-pollutant EMCs. Differences in EMCs between regions are often attributed
-to the variation in the amount and frequency of rainfall and snowmelt.
-Table 4-5 presents a breakdown of EMCs by different regions of the US
-classified by rainfall amounts.
-
-+---------------------+--------------------+--------------------+--------------------+
-| **Pollutant**       | **Mean EMC**       | **Median EMC**     | **Number of Events |
-|                     |                    |                    | Sampled**          |
-+:===================:+:==================:+:==================:+:==================:+
-| **Sediment (mg/L)**                                                                |
-+---------------------+--------------------+--------------------+--------------------+
-| TSS                 | 78.4               | 54.5               | 3047               |
-+---------------------+--------------------+--------------------+--------------------+
-| **Organic Carbon (mg/L)**                                                          |
-+---------------------+--------------------+--------------------+--------------------+
-| TOC                 | 17                 | 15.2               | 19 studies         |
-+---------------------+--------------------+--------------------+--------------------+
-| BOD                 | 14.1               | 11.5               | 1035               |
-+---------------------+--------------------+--------------------+--------------------+
-| COD                 | 52.8               | 44.7               | 2639               |
-+---------------------+--------------------+--------------------+--------------------+
-|                                                                                    |
-+---------------------+--------------------+--------------------+--------------------+
-| MTBE                | N/R                | 1.6                | 592                |
-+---------------------+--------------------+--------------------+--------------------+
-| **Nutrients (mg/L)**                                                               |
-+---------------------+--------------------+--------------------+--------------------+
-| Total P             | 0.32               | 0.26               | 3094               |
-+---------------------+--------------------+--------------------+--------------------+
-| Soluble P           | 0.13               | 0.10               | 1091               |
-+---------------------+--------------------+--------------------+--------------------+
-| Total N             | 2.39               | 2.00               | 2016               |
-+---------------------+--------------------+--------------------+--------------------+
-| Total Kjeldahl N    | 1.73               | 1.47               | 2693               |
-+---------------------+--------------------+--------------------+--------------------+
-| Nitrite and Nitrate | 0.66               | 0.53               | 2016               |
-+---------------------+--------------------+--------------------+--------------------+
-| **Metals (ug/L)**                                                                  |
-+---------------------+--------------------+--------------------+--------------------+
-| Copper              | 13.4               | 11.1               | 1657               |
-+---------------------+--------------------+--------------------+--------------------+
-| Lead                | 67.5               | 50.7               | 2713               |
-+---------------------+--------------------+--------------------+--------------------+
-| Zinc                | 162                | 129                | 2234               |
-+---------------------+--------------------+--------------------+--------------------+
-| Cadmium             | 0.7                | 0.5                | 150                |
-+---------------------+--------------------+--------------------+--------------------+
-| Chromium            | 4.0                | 7.0                | 164                |
-+---------------------+--------------------+--------------------+--------------------+
-| **Hydrocarbons (mg/L)**                                                            |
-+---------------------+--------------------+--------------------+--------------------+
-| PAH                 | 3.5                | N/R                | N/R                |
-+---------------------+--------------------+--------------------+--------------------+
-| Oil & Grease        | 3                  | N/R                | N/R                |
-+---------------------+--------------------+--------------------+--------------------+
-| **Bacteria and Pathogens (colonies/100 mL)**                                       |
-+---------------------+--------------------+--------------------+--------------------+
-| Fecal Coliform      | 15,038             | N/R                | 34                 |
-+---------------------+--------------------+--------------------+--------------------+
-| Fecal Streptococci  | 35,351             | N/R                | 17                 |
-+---------------------+--------------------+--------------------+--------------------+
-| **Pesticides (ug/L)**                                                              |
-+---------------------+--------------------+--------------------+--------------------+
-| Diazinon            | N/R                | 0.025              | 326                |
-+---------------------+--------------------+--------------------+--------------------+
-| Atrazine            | N/R                | 0.023              | 327                |
-+---------------------+--------------------+--------------------+--------------------+
-| Prometon            | N/R                | 0.031              | 327                |
-+---------------------+--------------------+--------------------+--------------------+
-| Simazine            | N/R                | 0.039              | 327                |
-+---------------------+--------------------+--------------------+--------------------+
-| **Chloride (mg/L)**                                                                |
-+---------------------+--------------------+--------------------+--------------------+
-| Chloride            | N/R                | 397                | 282                |
-+---------------------+--------------------+--------------------+--------------------+
-
-: []{#_Toc454288812 .anchor}**Table 4‑4 National EMC\'s for stormwater**
-
-Source: CWP (2003).
-
-[]{#_Toc454288813 .anchor}**Table 4‑5 EMC\'s for different regions**
-
-(units are mg/L except for metals which are in ug/L)
-
-+--------------------------------+-----------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------+--------------+
-|                                | **Low Rainfall**                                          | **Moderate Rainfall**                        | **High Rainfall**                                            | **Snow**     |
-+:==============+:===============+:=============+:=============+:=============+:=============+:=============+:===============+:=============+:=============+:================+:=============+:=============+:=============+
-|               | > **National** | > **Phoenix, | > **San      | > **Boise,   | > **Denver,  | > **Dallas,  | > **Marquette, | > **Austin,  | > **MD**     | > **Louisville, | > **GA**     | > **FL**     | > **MN**     |
-|               |                | > AZ**       | > Diego,     | > ID**       | > CO**       | > TX**       | > MI**         | > TX**       |              | > KY**          |              |              |              |
-|               |                |              | > CA**       |              |              |              |                |              |              |                 |              |              |              |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Annual        | N/A            | 7.1          | 10           | 11           | 15           | 28           | 32             | 32           | 41           | 43              | 51           | 52           | N/R          |
-| Rainfall (in) |                |              |              |              |              |              |                |              |              |                 |              |              |              |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Number of     | 3000           | 40           | 36           | 15           | 35           | 32           | 12             | N/R          | 107          | 21              | 81           | N/R          | 49           |
-| Events        |                |              |              |              |              |              |                |              |              |                 |              |              |              |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| **Pollutant** |                                                                                                                                                                                                         |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| TSS           | 78.4           | 227          | 330          | 116          | 242          | 663          | 159            | 190          | 67           | 98              | 258          | 43           | 112          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Total N       | 2.39           | 3.26         | 4.55         | 4.13         | 4.06         | 2.7          | 1.87           | 2.35         | N/R          | 2.37            | 2.52         | 1.74         | 4.30         |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Total P       | 0.32           | 0.41         | 0.7          | 0.75         | 0.65         | 0.78         | 0.29           | 0.32         | 0.33         | 0.32            | 0.33         | 0.38         | 0.70         |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Soluble P     | 0.13           | 0.17         | 0.4          | 0.47         | N/R          | N/R          | 0.04           | 0.24         | N/R          | 0.21            | 0.14         | 0.23         | 0.18         |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Copper        | 14             | 47           | 25           | 34           | 60           | 40           | 22             | 16           | 18           | 15              | 32           | 1.4          | N/R          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Lead          | 68             | 72           | 44           | 46           | 250          | 330          | 49             | 38           | 12.5         | 60              | 28           | 8.5          | 100          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| Zinc          | 162            | 204          | 180          | 342          | 350          | 540          | 111            | 190          | 143          | 190             | 148          | 55           | N/R          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| BOD           | 14.1           | 109          | 21           | 89           | N/R          | 112          | 15.4           | 14           | 14.4         | 88              | 14           | 11           | N/R          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-| COD           | 52.8           | 239          | 105          | 261          | 227          | 106          | 66             | 98           | N/R          | 38              | 73           | 64           | 112          |
-+---------------+----------------+--------------+--------------+--------------+--------------+--------------+----------------+--------------+--------------+-----------------+--------------+--------------+--------------+
-
-N/R: Not Recorded
-
-Source: CWP (2003)
-
-# Chapter 5 - Transport and Treatment
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 5.1 Introduction
-
-Water quality constituents in surface runoff and from other external
-sources will typically be transported through a conveyance system until
-they are discharged into a receiving water body, a treatment facility,
-or some other type of destination (such as back to the land surface for
-irrigation purposes). Figure 5-1 shows how SWMM represents this
-conveyance system as a network of Nodes and Links. Nodes are points that
-represent simple junctions, flow dividers, storage units, or outfalls.
-Links connect nodes to one another with conduits (pipes and channels),
-pumps, or flow regulators (orifices, weirs, or outlets). Inflows to
-nodes can come from surface runoff, groundwater interflow, RDII
-(rainfall dependent inflow/infiltration), sanitary dry weather flow, or
-from user-defined time series. Pollutants can be removed by natural
-decay processes as they flow through conduits and storage nodes, and
-they can also be reduced by treatment processes applied at both
-non-storage nodes (e.g., high-rate solids separators) and storage nodes
-(e.g., physical sedimentation). This chapter describes how SWMM computes
-pollutant concentrations within all conduits and nodes of the conveyance
-network at each computational time step after its hydraulic state has
-been determined. The latter consists of the flow rate and volume of
-water in each link and the volume of water within each storage node. The
-methods used to obtain this hydraulic solution are described in Volume
-II of this manual.
-
-

-Objects2
-
Figure 5‑1 Representation of the
-conveyance network in SWMM

-

-
-## 5.2 Governing Equations
-
-### 5.2.1 The 1-D Advection Dispersion Equation
-
-The one-dimensional transport of dissolved constituents along the length
-of a conduit (a pipe or natural channel) is described by the following
-conservation of mass equation (Martin and McCutcheon, 1999):
-
-$$\frac{\partial c}{\partial t} = - \frac{\partial(uc)}{\partial x} + \frac{\partial}{\partial x}\left( D\frac{\partial c}{dx} \right) + r(c) \qquad \text{(5-1)}$$
-
-where *c* = constituent concentration (ML-3), *u* = longitudinal
-velocity (LT-1), *D* = longitudinal dispersion coefficient (L2/T),
-*r(c)* = reaction rate term (ML-3T-1)), *x* = longitudinal distance
-(L), and *t* = time (T). Note that *c* is a continuous function of both
-distance *x* and time *t*. In general, c can be a vector of constituents
-in which case a separate Equation 5-1 would apply for each constituent
-and the reaction rate *r* could be a function of more than one
-constituent. The first term on the right hand side of Equation 5-1
-represents advective transport where the constituent mass within a
-parcel of water moves along the conduit at the same velocity as the bulk
-fluid. The second term represents longitudinal dispersion where, due to
-velocity and concentration gradients, some portion of the mass inside a
-parcel mixes with the contents of parcels on either side of it. The
-final term represents any reactions that modify the concentration within
-a parcel regardless of any fluid motion.
-
-A set of boundary and initial conditions is needed to solve Equation
-5-1. In a conveyance network of the type modeled by SWMM the boundary
-conditions would be the concentrations at the nodes at either end of a
-conduit. For a simple junction node that has no storage volume
-associated with it the instantaneous concentration is simply the
-instantaneous flow weighted average concentration of all inflows that
-the junction receives:
-
-$$c_{Nj} = \frac{\sum_{i \rightarrow j}^{}{c_{L2i}q_{2i} + W_{j}}}{\sum_{i \rightarrow j}^{}q_{2i} + Q_{j}} \qquad \text{(5-2)}$$
-
-where *cNj* is the concentration at node *j*, *cL2i* is the
-concentration at the end of link *i* that connects to node *j*, *q2i*
-is the flow rate at the end of link *i*, *Wj* is the mass flow rate of
-any direct external source of constituent to node *j*, *Qj* is the
-flow rate of the external source, and the summations are over all links
-that have flow directed into node *j*. For a storage node where it is
-assumed that the contents of the stored volume are completely mixed, the
-uniform concentration within the node is governed by the following
-conservation of mass equation:
-
-$$\frac{d(V_{Nj}c_{Nj})}{dt} = \sum_{i \rightarrow j}^{}{c_{L2i}q_{2i} - \sum_{j \rightarrow k}^{}{c_{Nj}q_{1k} + W_{j} - V_{Nj}r(c_{Nj})}} \qquad \text{(5-3)}$$
-
-where *VNj* is the volume of water stored at node *j*, *q2i* is the
-flow at the end of a link *i* directed into node *j*, *q1k* is the
-flow at the start of a link *k* directed out of node *j*, *Wj* is the
-mass flow rate of any direct external source into node *j*, and *r* is a
-reaction rate term.
-
-Formal numerical methods of solving the advection-dispersion equation
-5-1 along a single conduit are discussed by Ewing and Wang (2001). The
-solution process is made even more difficult because there is one such
-equation for each pipe and channel in the conveyance network. These are
-linked together by the boundary conditions 5-2 and 5-3. The result is a
-large system of algebraic differential equations that must be solved
-simultaneously.
-
-### 5.2.2 The Tanks in Series Model
-
-SWMM uses a less rigorous but more pragmatic approach to solving
-constituent transport where the conduits are represented as completely
-mixed reactors connected together at junctions or at completely mixed
-storage nodes. This "box model" or "tanks in series" approach is also
-employed by the widely used EPA WASP model (Ambrose et al., 1988) and
-the UK QUASAR model (Whitehead et al., 1997). It simplifies the problem
-by eliminating the need to compute the spatial variation of
-concentration along the length of a conduit. Equations 5-1 and 5-3 are
-replaced with the conservation of mass equation for a completely mixed
-reactor (either a conduit or storage node)
-
-$$\frac{d(Vc)}{dt} = {C_{in}Q}_{in} - cQ_{out} - \ Vr(c) \qquad \text{(5-4)}$$
-
-where *V* is the volume within the reactor, *c* is the concentration
-within the reactor, *Cin* is the concentration of any inflow to the
-reactor, *Qin* is the volumetric flow rate of this inflow, *Qout* is
-the volumetric flow rate leaving the reactor, and *r(c)* is a function
-that determines the rate of loss due to reaction.
-
-Medina et al. (1981) present an analytical solution to Equation 5-4
-under the assumptions that:
-
-1.  *Cin, Qin,* and *Qout*, are constant over a solution time step
-    *t* to *t* + ∆*t,*
-
-2.  *V* is represented by an average value over the time step,
-
-3.  $r(c) = K_{1}c$, where *K1* is a first-order reaction constant.
-
-Under these conditions the concentration within the conduit or storage
-node at the end of a time step *∆t* can be expressed as:
-
-$$c(t + \mathrm{\Delta}t) = c(t)e^{- \propto \mathrm{\Delta}t} + \frac{{C_{in}Q}_{in}}{\propto \overline{V}}\left( 1 - e^{- \propto \mathrm{\Delta}t} \right) \qquad \text{(5-5)}$$
-
-where
-$\propto = K_{1} + \left( Q_{out} + \frac{\mathrm{\Delta}V}{\mathrm{\Delta}t} \right)/\overline{V}$,
-$\mathrm{\Delta}V = V(t + \mathrm{\Delta}t) - \ V(t)$, and
-$\overline{V} = 0.5\left\lbrack V(t + \mathrm{\Delta}t) + V(t) \right\rbrack$.
-Note that values of *Qin*, *Qout* and both the initial and final
-volumes *V* are known from having already routed flow through the
-conveyance network over the period *t* to *t +* *∆t*.
-
-This equation was used in previous versions of SWMM (pre-SWMM 5) for
-water quality routing. However it can exhibit numerical problems, such
-as when conveyance elements dry up and their volume approaches 0 or when
-a relatively large, rapid loss of volume causes α to become negative.
-
-To avoid these issues, SWMM 5 uses a simpler form of the mixing equation
-which looks as follows:
-
-$$c(t + \mathrm{\Delta}t) = \left\lbrack c(t)V(t)e^{- K_{1}\mathrm{\Delta}t} + C_{in}Q_{in}\mathrm{\Delta}t \right\rbrack/(V(t) + Q_{in}\mathrm{\Delta}t) \qquad \text{(5-6)}$$
-
-This equation makes the new concentration in the "reactor" equal the
-original mass left after any reaction has occurred plus the mass
-introduced by any inflow which is then divided by the original volume
-plus the inflow volume. It can be shown that it approximates Equation
-5-5 for small time steps where the change in reactor volume is not very
-large. Because the time step used for quality routing is the same as for
-flow routing and is typically quite small (e.g., less than a minute) to
-avoid hydraulic instabilities, Equation 5-6 tends to produce quite
-acceptable results.
-
-Figure 5-2 compares the results obtained by the two equations (5-5 and
-5-6) at the end of a 1-mile stretch of pipeline that receives time
-varying runoff at its upstream end (*Qin* and *Cin* in the figure)
-and has a decay coefficient of 10 days-1. The pipeline consists of
-seven 800-foot sections of 18" pipe at a 0.5 percent slope. The routing
-time step was 30 seconds. For this particular example the difference
-between the equations is insignificant.
-
-

-QualRoute1.png
-
Figure 5‑2 Comparison of completely mixed
-reactor equations for time varying inflow

-

-
-Figure 5-3 provides another comparison of Equations 5-5 and 5-6 at the
-end of the same pipeline. This time the upstream inflow hydrograph is a
-square pulse of 3 hour duration with a constant concentration of 100
-mg/L and no reaction. Under these conditions the concentration in the
-water carried by the pipeline must always be 100 mg/L since there are no
-other sources or sinks and longitudinal dispersion is not explicitly
-included in either Equation 5-5 or 5-6. Figure 5-3 shows that the simple
-mixing equation 5-6 is able to achieve this result while the analytical
-solution, Equation 5-5, cannot. In fact the latter shows concentrations
-above 100 mg/L, which are not physically possible. These results support
-using the simple mixing equation 5-6 in place of the analytical solution
-for SWMM 5 as it provides accurate and robust water quality solutions.
-
-

-QuakRoute2.png
-
Figure 5‑3 Comparison of completely mixed
-reactor equations for a step inflow

-

-
-## 5.3 Computational Steps
-
-Water quality routing computations are implemented as part of SWMM's
-conveyance system routing calculations. They are made at each flow
-routing time step immediately after a new set of flow rates and volumes
-has been computed for all elements of the conveyance network. Volume II
-of this manual describes in detail the procedures used for hydraulic
-routing.
-
-The following quantities are therefore known for each pollutant and each
-network link:
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *QL1(t+∆t)* | = | flow rate entering the link at time *t+∆t* (cfs) |
-| *QL2(t+∆t)* | = | flow rate exiting the link at time *t+∆t* (cfs) |
-| *VL(t)* | = | the volume of water stored in the link at time t (ft3) |
-| *cL(t)* | = | the concentration of the pollutant in the link at time t (mass/ft3) |
-
-In addition, the following quantities are known for each pollutant at
-each node of the network at time *t*:
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *VN(t)* | = | the volume of water stored at the node (ft3) |
-| *cN(t)* | = | the concentration of the pollutant at the node at time t (mass/ft3) |
-
-Note that for computational purposes, concentration is expressed as
-mass/ft3. After computations are completed, they are converted back to
-mass/L for reporting purposes. The objective is to compute values of
-*cL* for each link and *cN* for each node at time *t+∆t*.
-
-Using Equation 5-6 as its mixing equation for both conduit links and
-storage nodes, SWMM 5 carries out the following three step process to
-update pollutant concentrations for each node and link in the conveyance
-network at the end of each flow routing time step:
-
-1.  First the cumulative mass flow rate of each pollutant into each node
-    of the network at the current time step is found. It includes
-    pollutant loads from subcatchment runoff, dry weather sanitary flow,
-    user-defined external time series loads, and possible groundwater
-    and RDII flows, all evaluated at time *t*. To this is added the mass
-    loads from all links (pipes, channels, pumps, etc.) that flow into
-    the node. These are computed by multiplying the current outflow rate
-    of the inflowing link (*QL2(t+∆t))* by the link's current
-    pollutant concentration (*cL(t))*.
-
-2.  Then a new concentration is computed for each node in the network.
-    If the node is a non-storage node, the concentration is simply the
-    cumulative mass flow rate divided by the cumulative inflow rate
-    (Equation 5-2 above). For a storage node, Equation 5-6 is used to
-    compute a new mixture concentration *cN(t+∆t)* where *Qin* is the
-    cumulative inflow rate from step 1 and *Cin* is step 1's cumulative
-    mass inflow divided by *Qin*.
-
-3.  Finally, Equation 5-6 is applied to determine a new concentration
-    for each pollutant in each conduit, *cL(t+∆t)*. In this equation,
-    *Qin* is the flow rate sent into conduit from its upstream node,
-    *QL1(t+∆t),* and *Cin* is the newly updated concentration of this
-    node, *cN(t+∆t),* found in step 2. For links that have no volume
-    (pumps, regulators, and dummy conduits) *cL(t+∆t)* is set equal to
-    the upstream node concentration *cN(t+∆t)*.
-
-Certain modifications must be made to this basic procedure to handle the
-following special conditions.
-
-[Evaporation Losses]{.underline}
-
-Both open conduits and storage units can lose water through evaporation.
-When water is evaporated, the pollutant mass stays behind (unless it
-volatilizes, which is not explicitly modeled by SWMM, although it could
-be approximated through the first order decay process). Thus when
-evaporation occurs pollutant concentrations will increase. SWMM computes
-this increase as a multiplier$f_{evap}$:
-
-$$f_{evap} = 1 + V_{evap}(t)/V(t) \qquad \text{(5-7)}$$
-
-where $V_{evap}(t)$ is the volume lost to evaporation over the time step
-and $V(t)$ is either *VN(t)* for a storage node at Step 2 or *VL(t)*
-for a conduit link at Step 3. This multiplier is then used to adjust the
-concentration *cN(t)* before Step 2 is carried out for a storage node
-or *cL(t)* before Step 3 is carried out for a conduit link.
-
-[Dynamic Wave Flow Routing]{.underline}
-
-When SWMM's Dynamic Wave flow routing option (see Volume II) is used
-there is only one flow rate associated with each conduit, so that
-*QL1* and *QL2* have the same values. This might suggest that there
-would be no volume change within the conduit over a time step. However
-the routing process actually does produce a change in volume due to
-changes in flow depths at either end of the conduit. To make the flow
-rates consistent with this volume change, the value of *QL1* is
-adjusted by an amount ∆$Q_{L1}$ found from the following flow balance
-equation:
-
-$$\mathrm{\Delta}Q_{L1} = V_{L}(t + \mathrm{\Delta}t) + V_{losses}(t) - V_{L}(t) \qquad \text{(5-8)}$$
-
-where $V_{losses}(t)$ is the volume of evaporation and seepage loss over
-the time period $\mathrm{\Delta}t$.
-
-[Steady Flow Routing]{.underline}
-
-SWMM's Steady Flow routing option (see Volume II) simply translates the
-inflow to a conduit instantaneously to its outlet node. That is, the
-inflow to the conduit completely replaces the previous contents over the
-time step. So there is no mixing of the previous contents with new
-inflow from the upstream node. Thus Step 3 of the basic water quality
-routing procedure becomes:
-
-$$c_{L}(t + \mathrm{\Delta}t) = f_{evap}c_{N}(t + \mathrm{\Delta}t)exp( - K_{1}\mathrm{\Delta}t) \qquad \text{(5-9)}$$
-
-where $c_{N}(t + \mathrm{\Delta}t)$ is the newly computed concentration
-at the conduit's upstream node.
-
-## 5.4 Treatment
-
-### 5.4.1 Background
-
-Management of stormwater quality is usually performed through a
-combination of so-called "best management practices" (BMPs) and a form
-of hydrologic source control popularly known as "low impact development"
-(LID). Treatment of stormwater runoff, either by natural means or by
-engineered devices, can occur at both the source of the generated runoff
-or at locations within the conveyance network. Source treatment through
-LID is discussed in the next chapter. This section describes how SWMM
-models treatment applied to flows already captured and transported
-within a conveyance system.
-
-Table 5-1, adapted from Huber et al. (2006), categorizes the different
-unit treatment processes used by various types of conveyance system
-BMPs. Ideally one would like to model these processes at a fundamental
-level, to be able to estimate pollutant removal based on physical design
-parameters, hydraulic variables, and intrinsic chemical properties and
-reaction rates. With a few exceptions, the state of our knowledge does
-not permit this, at least within the scope of a general purpose
-stormwater management model like SWMM. Instead one has to rely on
-empirical relationships developed from site-specific monitoring data.
-
-Strecker et al. (2001) discuss the challenges of using monitoring data
-to develop consistent estimates of BMP effectiveness and pollutant
-removal. The International Stormwater BMP Database
-([www.bmpdatabase.org](http://www.bmpdatabase.org)) provides a
-comprehensive compilation of BMP performance data from over 500 BMP
-studies on 17 different categories of BMPs and LID practices. It is
-continually updated with new data contributed by the stormwater
-management community. Table 5-2 lists the median influent and effluent
-event mean concentrations (EMCs) for a variety of BMP categories and
-pollutants that were compiled from this database. The cells highlighted
-in yellow indicate that a statistically significant removal of the
-pollutant was achieved by the BMP category. A summary of the median
-removal percentages of several common pollutants treated by filtration,
-ponds, and wetlands published in the Minnesota Stormwater Manual is
-listed in Table 5-3. Most of these percentages are consistent with those
-inferred from median EMC numbers in the BMP database table 5-2.
-
-  ---------------------------------------------------------------------------
-  **Process**        **Definition**                   **Example BMPs**
-
-|  |  |  |
-| --- | --- | --- |
-| Sedimentation | Gravitational settling of suspended particles from the water column. | Ponds, wetlands, vaults, and tanks. |
-| Flotation | Separation of particulates with a specific gravity less than water (e.g., trash, oil and grease). | Oil-water separators, density separators, dissolved-air flotation. |
-| Filtration | Removal of particulates by passing water through a porous medium like sand, gravel, soil, etc. | Sand filters, screens, and bar racks. |
-| Infiltration | Allowing captured runoff to infiltrate into the ground reducing both runoff volume and loadings of particulates and dissolved nutrients and heavy metals. | Infiltration basins, ponds, and constructed wetlands. |
-| Adsorption | Binding of contaminants to clay particles, vegetation or certain filter media. | Infiltration systems, sand filters with iron oxide, constructed wetlands. |
-| Biological Uptake | Uptake of nutrients by aquatic | Ponds and wetlands. |
-| and Conversion | plants and microorganisms; conversion of organics to less harmful compounds by bacteria and other organisms. |  |
-| Chemical Treatment | Chemicals used to promote settling and filtration. Disinfectants used to treat combined sewer overflows. | Ponds, wetlands, rapid mixing devices. |
-| Natural | Chemical decomposition or | Ponds and wetlands. |
-| Degradation | conversion to a gaseous state by |  |
-| (volatilization, | natural processes. |  |
-| hydrolysis, |  |  |
-| photolysis) |  |  |
-| Hydrodynamic | Uses the physics of flowing | Swirl concentrators, |
-| Separation | water to create a swirling vortex to remove both settleable particulates and flotables. | secondary current devices, oil-water separators. |
-
-
-  : []{#_Toc454288814 .anchor}**Table 5‑1 Treatment processes used by
-  various types of BMPs**
-
-+-----------------+------------------+------------------+------------------+------------------+------------------+
-| Pollutant       | Media Filtration | Detention Basin  | Retention Pond   | Wetland Basin    | Manufactured     |
-|                 |                  |                  |                  |                  | Device           |
-|                 +--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-|                 | **In** | **Out** | **In** | **Out** | **In** | **Out** | **In** | **Out** | **In** | **Out** |
-+=================+:======:+:=======:+:======:+:=======:+:======:+:=======:+:======:+:=======:+:======:+:=======:+
-| TSS mg/L        | 52.7   | 8.7     | 66.8   | 24.2    | 70.7   | 13.5    | 20.4   | 9.06    | 34.5   | 18.4    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| F. Coliform,    | 1350   | 542     | 1480   | 1030    | 1920   | 707     | 13000  | 6140    | 2210   | 2750    |
-| #/100mL         |        |         |        |         |        |         |        |         |        |         |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Cadmium, ug/L   | 0.31   | 0.16    | 0.39   | 0.31    | 0.49   | 0.23    | 0.31   | 0.18    | 0.40   | 0.28    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Chromium, ug/L  | 2.02   | 1.02    | 5.02   | 2.97    | 4.09   | 1.36    |        |         | 3.66   | 2.82    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Copper, ug/L    | 11.28  | 6.01    | 10.62  | 5.67    | 9.57   | 4.99    | 5.61   | 3.57    | 13.42  | 10.16   |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Lead, ug/L      | 10.5   | 1.69    | 6.08   | 3.10    | 8.48   | 2.76    | 2.03   | 1.21    | 8.24   | 4.63    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Nickel, ug/L    | 3.51   | 2.20    | 5.64   | 3.35    | 4.46   | 2.19    |        |         | 3.84   | 4.51    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Zinc, ug/L      | 77.3   | 17.9    | 70.0   | 17.9    | 53.6   | 21.2    | 48.0   | 22.0    | 87.7   | 58.5    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Total P, mg/L   | 0.18   | 0.09    | 0.28   | 0.22    | 0.30   | 0.13    | 0.13   | 0.08    | 0.19   | 0.12    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Orthophosphate, | 0.05   | 0.03    | 0.53   | 0.39    | 0.10   | 0.04    | 0.04   | 0.02    | 0.21   | 0.10    |
-| mg/L            |        |         |        |         |        |         |        |         |        |         |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| Total N, mg/L   | 1.06   | 0.82    | 1.40   | 2.37    | 1.83   | 1.28    | 1.14   | 1.19    | 2.27   | 2.22    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| TKN, mg/L       | 0.96   | 0.57    | 1.49   | 1.61    | 1.28   | 1.05    | 0.95   | 1.01    | 1.59   | 1.48    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-| NOX, mg/L     | 0.33   | 0.51    | 0.55   | 0.36    | 0.43   | 0.18    | 0.24   | 0.08    | 0.41   | 0.41    |
-+-----------------+--------+---------+--------+---------+--------+---------+--------+---------+--------+---------+
-
-: []{#_Toc454288815 .anchor}**Table 5‑2 Median inlet and outlet EMCs for
-selected stormwater treatment practices**
-
-Source: International Stormwater BMP Database, "International Stormwater
-Best Management Practices (BMP) Database Pollutant Category Summary
-Statistical Addendum: TSS, Bacteria, Nutrients, and Metals", July 2012
-([www.bmpdatabase.org](http://www.bmpdatabase.org)).
-
-  --------------------------------------------------------------------------
-  **Pollutant**                   **Sand Filter**  **Ponds**   **Wetlands**
-
-|  |  |  |  |
-| --- | --- | --- | --- |
-| Total Suspended Solids | 85 | 84 | 73 |
-| Total Phosphorus | 77 | 50 | 38 |
-| Particulate Phosphorus | 91 | 91 | 69 |
-| Dissolved Phosphorus | 60 | 0 | 0 |
-| Total Nitrogen | 35 | 30 | 30 |
-| Zinc and Copper | 50 | 70 | 70 |
-| Bacteria | 80 | 60 | 60 |
-
-
-  : []{#_Toc454288816 .anchor}**Table 5‑3 Median pollutant removal
-  percentages for select stormwater BMPs**
-
-Source: Minnesota Stormwater Manual (http://stormwater.pca.state.mn.us).
-
-### 5.4.2 Treatment Representation
-
-SWMM 5 allows treatment to be applied to any water quality constituent
-at any node of the conveyance network. Treatment will act to reduce the
-nodal concentration of the constituent from the value it had after Step
-2 of the water quality routing procedure described in section 5.3 (after
-a new mixture concentration has been computed for the node but before
-any outflow from the node is sent into any downstream links). The degree
-of treatment for a constituent is prescribed by the user, either as a
-concentration remaining after treatment or as the fractional removal
-achieved. It can be a function of the current concentration or
-fractional removal of any set of constituents as well as the current
-flow rate. For storage nodes, it can also depend on water depth, surface
-area, routing time step, and hydraulic residence time. Because treatment
-is applied at every time step, the resulting pollutant concentrations
-can vary throughout a storm event and will not necessarily represent an
-event mean concentration (EMC). The exception, of course, would be if
-treatment is specified as simply a constant concentration that is not
-dependent on any other variables.
-
-The effect of treatment for a particular pollutant at a particular node
-can be expressed mathematically using one of the following general
-expressions (some specific examples will be presented later on):
-
-$$c(t + \mathrm{\Delta}t) = c(\mathbf{C},\ \mathbf{R},\ \mathbf{H}) \qquad \text{(5-10)}$$
-
-$$c(t + \mathrm{\Delta}t) = \left( 1 - r\left( \mathbf{C},\ \mathbf{R},\ \mathbf{H} \right) \right)C_{in}(t + \mathrm{\Delta}t) \qquad \text{(5-11)}$$
-
-where:
-
-  -----------------------------------------------------------------------------------------------
-      $$c$$                          =   nodal pollutant concentration after treatment is applied
-
-|  |  |  |  |
-| --- | --- | --- | --- |
-|  | $C_{in}$ | = | pollutant concentration in the node's inflow stream |
-|  | $c(\ldots)$ | = | concentration-based treatment function |
-|  | $r(\ldots)$ | = | removal-based treatment function |
-|  | $\mathbf{C}$ | = | vector of nodal pollutant concentrations before treatment is applied |
-|  | $\mathbf{C}_{\mathbf{in}}$ | = | vector of pollutant concentrations in the node's inflow stream |
-|  | $\mathbf{R}$ | = | vector of fractional removals resulting from treatment |
-|  | $\mathbf{H}$ | = | vector of hydraulic variables at the current time step*.* |
-
-
-Note that if treatment is made a function of pollutant concentrations,
-then for concentration-based treatment these represent the
-concentrations at the node prior to treatment while for removal-based
-functions they are the concentrations in the node's combined influent
-stream. If the node has no volume (e.g., is a non-storage node) then
-these two types of concentrations are equivalent.
-
-The hydraulic variables that can appear in a treatment expression
-include the following:
-
-  ----------------------------------------------------------------------------
-      ***FLOW***    flow rate into the node in user defined flow units
-
-|  |  |  |
-| --- | --- | --- |
-|  | ***DEPTH*** | average water depth in the node over the time step (ft or m) |
-|  | ***AREA*** | average surface area of the node over the time step (ft2 or m2) |
-|  | ***DT*** | current routing time step (seconds) |
-|  | ***HRT*** | hydraulic residence time of water in a storage node (hours). |
-
-
-The hydraulic residence time is the average time that water has spent
-within a completely mixed storage node. It is continuously updated for
-each storage node as the simulation progresses by evaluating the
-following expression:
-
-$$\theta(t + \mathrm{\Delta}t) = (\theta(t) + \mathrm{\Delta}t)\frac{V(t)}{V(t) + Q_{in}\mathrm{\Delta}t} \qquad \text{(5-12)}$$
-
-where $\theta(t)$ is the hydraulic residence time at time *t* in
-seconds, $V(t)$ is the cubic feet of stored water at time t, $Q_{in}$ is
-the inflow rate to the storage node in cfs, and $\mathrm{\Delta}t$ is
-the current time step in seconds.
-
-SWMM applies the following conditions when evaluating a treatment
-expression:
-
-1.  The concentration after treatment cannot be less than 0 or greater
-    than the concentration prior to treatment.
-
-2.  A fractional removal cannot be greater than 1.0.
-
-3.  A removal-based treatment function evaluates to 0 if there is no
-    inflow into the node in question.
-
-4.  If a pollutant with a global first order decay coefficient is
-    assigned a treatment expression at some storage node then the
-    treatment expression takes precedence (i.e., the decay coefficient
-    *K1* in Equation 5-6 is set to 0).
-
-5.  Co-pollutants do not automatically receive an equivalent amount of
-    co-treatment as their dependent pollutant receives.
-
-The latter condition is necessary because co-pollutants only apply to
-buildup/washoff processes -- not to the user-specified concentrations in
-rainwater, groundwater, I/I, dry weather flow, and externally imposed
-inflows.
-
-### 5.4.3 Example Treatment Expressions
-
-Several concrete examples of treatment expressions, in the format used
-by SWMM 5's input file, will be given to illustrate how different types
-of treatment mechanisms can be modeled.
-
-[EMC Treatment]{.underline}
-
-Treatment results in a constant concentration. As an example, if this
-concentration were 10 mg/L then the treatment expression supplied to
-SWMM would be:
-
-***c = 10***
-
-[Constant Removal Treatment]{.underline}
-
-Treatment results in a constant percent removal. For example, if this
-removal was 85% then the treatment expression would be:
-
-***r = 0.85***
-
-[Co-Removal Treatment]{.underline}
-
-The removal of some pollutant is proportional to the removal of some
-other pollutant. For example, if the removal of pollutant X was 75% of
-the removal of suspended solids (TSS) then the treatment expression
-would be:
-
-***r = 0.75 \* R_TSS***
-
-where ***R_TSS*** is the fractional removal computed for pollutant TSS.
-
-[Concentration-Dependent Removal]{.underline}
-
-Some empirical performance data indicate higher pollutant removal
-efficiencies with higher influent concentrations (Strecker et al.,
-2001). Suppose that the removal of pollutant X is 50% for inflow
-concentrations below 50 mg/L and 75% for concentrations above 50. The
-resulting treatment expression would be:
-
-***r = (1 - STEP(C_X -- 50)) \* 0.5 + STEP(C_X -- 50) \* 0.75***
-
-where ***C_X*** is the influent concentration of pollutant X and
-***STEP*** is the unit step function whose value is zero for negative
-argument and one for positive argument.
-
-[N-th Order Reaction Kinetics]{.underline}
-
-Suppose that during treatment pollutant X exhibits n-th order reaction
-kinetics where the instantaneous reaction rate is $kC^{n}$ with *k*
-being the rate constant and *n* the reaction order. This can be
-represented as the following SWMM treatment expression for the specific
-case where *k* = 0.02 and *n* = 1.5:
-
-***c = C_X -- 0.02 \* (C_X\^1.5) \* DT***
-
-[The k-C\* Model]{.underline}
-
-This is a first-order model with background concentration made popular
-by Kadlec and Knight (1996) for long-term treatment performance of
-wetlands. The general model can be expressed as:
-
-$$c - C^{*} = \left( C_{in} - C^{*} \right)exp( - \frac{k\theta}{d}) \qquad \text{(5-13)}$$
-
-where $C^{*}$ is a constant residual concentration that always remains,
-*k* is a rate coefficient with units of length/time, *θ* is the
-hydraulic residence time, and *d* is water depth. This equation can be
-re-arranged into a removal function as follows:
-
-$$r = 1 - \frac{c}{C_{in}} = \left\lbrack 1 - \exp\left( - \frac{k\theta}{d} \right) \right\rbrack\left\lbrack 1 - \frac{C^{*}}{C_{in}} \right\rbrack \qquad \text{(5-14)}$$
-
-The corresponding SWMM removal expression of some pollutant X with *k* =
-0.02 (ft/hr) and $C^{*}$ = 20 would look as follows:
-
-***r = STEP(C_X -- 20) \* ((1 -- exp(-0.02\*HRT/DEPTH)) \*
-(1-20/C_X))***
-
-The ***STEP(C_X -- 20)*** term insures that no removal occurs when the
-inflow concentration is below the residual concentration.
-
-[Gravity Settling]{.underline}
-
-Consider a size range of suspended particles with average settling
-velocity *ui*. During a quiescent period of time *∆t* within a storage
-volume the fraction of these particles that will settle out is
-$u_{i}\mathrm{\Delta}t/d$ where *d* is the water depth. Summing over all
-particle size ranges leads to the following expression for the change in
-TSS concentration *ΔC* during a time step *Δt*:
-
-$$\mathrm{\Delta}c = c(t)\sum_{i}^{}{f_{i}u_{i}}\left( \frac{\mathrm{\Delta}t}{d} \right) \qquad \text{(5-15)}$$
-
-where $f_{i}$ is the fraction of particles with settling velocity
-$u_{i}$. Because $\sum_{}^{}{f_{i}u_{i}}$ is generally not known, it can
-be replaced with a fitting parameter *k* and in the limit Equation 5-15
-becomes:
-
-$$\frac{\partial c}{\partial t} = - \frac{k}{d}c(t) \qquad \text{(5-16)}$$
-
-Note that *k* has units of velocity (length/time) and can be thought of
-as a representative settling velocity for the particles that make up the
-total suspended solids in solution. Integrating 5-16 between times *t*
-*and t + ∆t*, and assuming there is some residual amount of suspended
-solids *C\** that is non-settleable leads to the following expression
-for $c(t + \mathrm{\Delta}t)$:
-
-$$c(t + \mathrm{\Delta}t) = C^{*} + \left( c(t) - C^{*} \right)exp( - \frac{k\mathrm{\Delta}t}{d}) \qquad \text{(5-17)}$$
-
-For particular values of *C\** = 20 and *k* = 0.01 ft/hr this equation
-would be represented by the following treatment expression for a
-pollutant named TSS:
-
-***C = STEP(0.1 - FLOW) \****
-
-***(20 + (C_TSS -- 20) \* exp(-0.01/DEPTH\*DT/3600)) +***
-
-***(1 -- STEP(0.1 - FLOW)) \* C_TSS***
-
-Note that ***DT*** is converted from seconds to hours to be compatible
-with the time units of *k* and that the ***STEP*** function is used to
-define quiescent conditions by an inflow rate below 0.1 cfs.
-
-Figure 5.4 shows the result of using this treatment expression when
-routing a 6-hour runoff hydrograph with a peak flow of 20 cfs through a
-half acre dry detention pond whose outlet is a 9" high by 18" wide
-orifice. The TSS in the runoff has a constant EMC of 100 mg/L. The
-resulting TSS concentration in the pond over both the filling and
-emptying periods are plotted in the figure, as are the inflow hydrograph
-and pond water depth. Note that during the inflow period the TSS remains
-at 100 mg/L and begins to settle out once the inflow ceases. As the pond
-depth decreases while it empties more solids settle out reducing the TSS
-level until the residual concentration of 20 mg/L is reached.
-
-![TreatmentExample.png](./VolumeIII/media/media/image21.png){width="6.5in"
-height="4.156944444444444in"}
-
-[]{#_Toc454288776 .anchor}**Figure 5‑4 Gravity settling treatment of TSS
-within a detention pond**
-
-# Chapter 6 - Low Impact Development Controls
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-## 6.1 Introduction
-
-Low impact development (LID) controls are landscaping practices designed
-to capture and retain stormwater generated from impervious surfaces that
-would otherwise run off of a site. They are also referred to as green
-infrastructure (GI), integrated management practices (IMPs) sustainable
-urban drainage systems (SUDS), and stormwater control measures (SCMs).
-See Fletcher et al. (2015) for a review of this terminology. Prince
-Georges County (1999a) describes the LID concept and its application to
-stormwater management in more detail. Additional informational resources
-are available from the following US EPA web sites:
-
-- 
-
-- 
-
-and from the Low Impact Development Center
-().
-
-SWMM 5 can explicitly model the following types of LID practices:
-
-  ------------------------------------------------------------------------------------------------------------------------------------
-  ***Bio-retention Cells*** are depressions that        ![StreetPlanter](./VolumeIII/media/media/image22.png){width="1.34375in"
-  contain vegetation grown in an engineered soil        height="0.9375in"}
-  mixture placed above a gravel storage bed. They       
-  provide storage, infiltration and evaporation of both 
-  direct rainfall and runoff captured from surrounding  
-  areas. Street planters and bio-swales are common      
-  examples of bio-retention cells.                      
-  ----------------------------------------------------- ------------------------------------------------------------------------------
-  ***Rain Gardens*** are a type of bio-retention cell   ![RainGarden](./VolumeIII/media/media/image23.png){width="1.34375in"
-  consisting of just the engineered soil layer with no  height="0.9895833333333334in"}
-  gravel bed below it.                                  
-
-  ***Green Roofs*** are another variation of a          ![GreenRoof](./VolumeIII/media/media/image24.png){width="1.34375in"
-  bio-retention cell that have a soil layer above a     height="1.0208333333333333in"}
-  thin layer of synthetic drainage mat material or      
-  coarse aggregate that conveys excess water draining   
-  through the soil layer off of the roof.               
-
-  ***Infiltration Trenches*** are narrow ditches filled ![InfilTrench](./VolumeIII/media/media/image25.png){width="1.34375in" height="1.0in"}
-  with gravel that intercept runoff from upslope        
-  impervious areas. They provide storage volume and     
-  additional time for captured runoff to infiltrate     
-  into the native soil below.                           
-
-  ***Continuous Permeable Pavement*** systems are       ![PermPavement2.png](./VolumeIII/media/media/image26.png){width="1.3751924759405074in"
-  street or parking areas paved with a porous concrete  height="0.8647036307961505in"}
-  or asphalt mix that sits above a gravel storage       
-  layer. Rainfall passes through the pavement into the  
-  storage layer where it can infiltrate into the        
-  site\'s native soil.                                  
-
-  ***Block Paver*** systems consist of impervious paver ![BlockPavers.png](./VolumeIII/media/media/image27.png){width="1.3146347331583552in"
-  blocks placed on a sand or pea gravel bed with a      height="0.7199179790026247in"}
-  gravel storage layer below. Rainfall is captured in   
-  the open spaces between the blocks and conveyed to    
-  the storage zone where it can infiltrate into the     
-  site\'s native soil.                                  
-
-  ***Rain Barrels*** (or ***Cisterns***) are containers ![cistern](./VolumeIII/media/media/image28.png){width="1.3229166666666667in"
-  that collect roof runoff during storm events and can  height="1.0in"}
-  either release or re-use the rainwater during dry     
-  periods.                                              
-
-  ***Rooftop Disconnection*** has roof downspouts       ![](./VolumeIII/media/media/image29.png){width="1.3210028433945757in"
-  discharge to pervious landscaped areas and lawns      height="0.9893350831146107in"}
-  instead of directly into storm drains. It can also    
-  model roofs with directly connected drains that       
-  overflow onto pervious areas.                         
-
-  ***Vegetative Swales*** are channels or depressed     ![VegSwale](./VolumeIII/media/media/image30.png){width="1.3229166666666667in"
-  areas with sloping sides covered with grass and other height="0.8645833333333334in"}
-  vegetation. They slow down the conveyance of          
-  collected runoff and allow it more time to infiltrate 
-  into the native soil.                                 
-  ------------------------------------------------------------------------------------------------------------------------------------
-
-Bio-retention cells, infiltration trenches, and permeable pavement
-systems can contain optional underdrain systems in their gravel storage
-beds to convey excess captured runoff off of the site and prevent the
-unit from flooding. They can also have an impermeable floor or liner
-that prevents any infiltration into the native soil from occurring.
-Infiltration trenches and permeable pavement systems can also be
-subjected to a decrease in hydraulic conductivity over time due to
-clogging. Other LID practices, such as preservation of natural areas,
-reduction of impervious cover, and soil restoration, can be modeled by
-using SWMM's conventional runoff elements.
-
-LID is a distributed method of runoff source control, that uses surface
-and landscape modifications located on or adjacent to impervious areas
-that generate most of the runoff in urbanized areas. For this reason
-SWMM considers LID controls to be part of its Subcatchment object, where
-each control is assigned a fraction of the subcatchment's impervious
-area whose runoff it captures. The design variables that affect the
-hydrologic performance of LID controls include the properties of the
-media (soil and gravel) contained within the unit, the vertical depth of
-its media layers, the hydraulic capacity of any underdrain system used,
-and the surface area of the unit itself. Although some LID practices can
-also provide significant pollutant reduction benefits (Hunt et al.,
-2006; Li and Davis, 2009), at this time SWMM only captures the reduction
-in runoff mass load resulting from the reduction in runoff flow volume.
-
-Several different approaches have been used in the past to model LID
-hydrology. One simple scheme uses the void volume available in the LID
-unit (Davis and McCuen, 2005), possibly combined with a modified Curve
-Number for LID areas (Prince Georges County, 1999b), to determine what
-depth of storm event will be captured. Although useful for initial
-sizing, it ignores the effects that varying rainfall intensity and event
-frequency have on surface infiltration, soil moisture retention, and
-storage capacity. At the other end of the spectrum are detailed soil
-physics models, typically based on the Richards equation, that estimate
-the flows and moisture levels for a single LID unit over the course of a
-rainfall event (see Dussaillant et al., (2004) and He and Davis,
-(2011)). These approaches are too computationally intensive to be used
-in a general purpose engineering model like SWMM, where hundreds of LID
-units might be deployed throughout a large study area. A third approach,
-suggested by Huber et al. (2006) is to utilize SWMM's conventional
-elements and features, such as internal routing within subcatchments and
-multiple storage units connected by flow regulator links, to approximate
-the behavior of LID units. Unfortunately, an accurate representation of
-LID behavior can require a very complex arrangement of SWMM elements
-(see Zhang et al. (2006) and Lucas (2010) for examples). To circumvent
-these issues, SWMM 5 treats LID controls as an additional type of
-discrete element, using a unit process-based representation of their
-behavior (Rossman, 2010) that provides a reasonable level of accuracy
-for simulating dynamic rainfall events in a computationally efficient
-manner.
-
-##  6.2 Governing Equations
-
-### 6.2.1 Bio-Retention Cells
-
-A typical bio-retention cell (see panel A of Figure 6-1) will serve as
-an example for developing a generic LID performance model. This generic
-model can then be customized as need be to describe the behavior of
-other types of LID controls.
-
-Conceptually a bio-retention cell can be represented by a number of
-horizontal layers as shown in panel B of Figure 6-1. The surface layer
-(layer 1) receives both direct rainfall and runoff captured from other
-areas. It loses water through infiltration into the soil layer below it,
-by evapotranspiration (ET) of any ponded surface water, and by any
-surface runoff that might occur. The soil layer (layer 2) contains an
-engineered soil mix that can support vegetative growth. It receives
-infiltration from the surface layer and loses water through ET and by
-percolation into the storage layer below it. The storage layer (layer 3)
-consists of coarse crushed stone or gravel. It receives percolation from
-the soil zone above it and loses water by infiltration into the
-underlying natural soil and by outflow through a perforated pipe
-underdrain system if present.
-
-  ---------------------------------------------------------------------------------------------------------
-   ![planter.bmp](./VolumeIII/media/media/image31.png){width="2.8232895888014in"    ![](./VolumeIII/media/media/image32.png)
-                      height="2.941583552055993in"}                     
-
-|  |  |
-| --- | --- |
-| **(A)** | **(B)** |
-
-
-  : []{#_Toc454288777 .anchor}**Figure 6‑1 A typical bio-retention
-  cell**
-
-To model the hydrologic performance of this LID unit the following
-simplifying assumptions are made:
-
-1.  The cross-sectional area of the unit remains constant throughout its
-    depth.
-
-2.  Flow through the unit is one-dimensional in the vertical direction.
-
-3.  Inflow to the unit is distributed uniformly over the top surface.
-
-4.  Moisture content is uniformly distributed throughout the soil layer.
-
-5.  Matric forces within the storage layer are negligible so that it
-    acts as a simple reservoir that stores water from the bottom up.
-
-Under these assumptions the LID unit can be modeled by solving a set of
-simple flow continuity equations. Each equation describes the change in
-water content in a particular layer over time as the difference between
-the inflow and the outflow water flux rates that the layer sees,
-expressed as volume per unit area per unit time. These equations can be
-written as follows:
-
-
-$$\phi_{1}\frac{\partial d_{1}}{\partial t} = i + q_{0} - e_{1} - f_{1} - q_{1} \qquad \text{Surface Layer} \qquad \text{(6-1)}$$
-
-
-$$D_{2}\frac{\partial\theta_{2}}{\partial t} = f_{1} - e_{2} - f_{2} \qquad \text{Soil Layer} \qquad \text{(6-2)}$$
-
-
-$$\phi_{3}\frac{\partial d_{3}}{\partial t} = f_{2} - {e_{3} - f}_{3} - q_{3} \qquad \text{Storage Layer} \qquad \text{(6-3)}$$
-
-
-where:
-
-  *d1*          =  depth of water stored on the surface (ft),
-  *θ2*          =  soil layer moisture content (volume of water / total volume of
-                     soil),
-
-  *d3*          =  depth of water in the storage layer (ft),
-
-                     
-
-  *i*             =  precipitation rate falling directly on the surface layer
-                     (ft/sec),
-
-  *q0*          =  inflow to the surface layer from runoff captured from other
-                     areas (ft/sec),
-
-                     
-
-  *q1*          =  surface layer runoff or overflow rate (ft/sec),
-
-  *q3*          =  storage layer underdrain outflow rate (ft/sec),
-
-                     
-
-  *e1*          =  surface ET rate (ft/sec),
-
-  *e2*          =  soil layer ET rate (ft/sec),
-
-  *e3*          =  storage layer ET rate (ft/sec),
-
-                     
-
-  *f1*          =  infiltration rate of surface water into the soil layer
-                     (ft/sec),
-
-  *f2*          =  percolation rate of water through the soil layer into the
-                     storage layer (ft/sec),
-
-  *f3*          =  exfiltration rate of water from the storage layer into native
-                     soil (ft/sec),
-
-                     
-
-  $$\phi_{1}$$    =  void fraction of any surface volume (i.e., the fraction of
-                     freeboard above the surface not filled with vegetation)
-
-  $$\phi_{2}$$    =  porosity (void volume / total volume) of the soil layer (used
-                     later on),
-
-  $$\phi_{3}$$    =  void fraction of the storage layer (void volume / total
-                     volume),
-
-                     
-
-  *D1*          =  freeboard height for surface ponding (ft) (used later on),
-
-  *D2*          =  thickness of the soil layer (ft),
-
-  *D3*          =  thickness of the storage layer (ft) (used later on).
-
-The flux terms (*q, e,* and *f*) in these equations are functions of the
-current water content in the various layers (*d1, θ2,* and *d3*)
-and specific site and soil characteristics. This set of coupled
-equations can be solved numerically at each runoff time step to
-determine how an inflow hydrograph to the LID unit (*i + q0*) is
-converted into hydrographs for surface runoff (*q1*), underdrain
-outflow (*q3*), and exfiltration into the surrounding native soil
-(*f3*). As applied to a bio-retention cell, this generic model is
-similar in spirit to the RECARGA model developed at the University of
-Wisconsin -- Madison (Atchison and Severson, 2004) for rain gardens with
-no gravel storage zone. How each of the flux terms in Equations 6-1 to
-6-3 is computed will now be discussed.
-
-[Surface Inflow (*i + q0*)]{.underline}
-
-Inflow to the surface layer comes from both direct rainfall (*i*) and
-runoff from impervious areas captured by the bio-retention cell
-(*q0*). Within each runoff time step these values are provided by
-SWMM's runoff computation as described in Chapter 3 of Volume I of this
-manual.
-
-[Surface Infiltration (*f1*)]{.underline}
-
-The infiltration of surface water into the soil layer, *f1*, can be
-modeled with the Green-Ampt equation:
-
-$$f_{1} = K_{2S}\left( 1 + \frac{\left( \phi_{2} - \theta_{20} \right)(d_{1} + \psi_{2})}{F} \right) \qquad \text{(6-4)}$$
-
-where
-
-| Symbol | | Description |
-| --- | --- | --- |
-| *f1* | = | infiltration rate (ft/sec), |
-| *K2S* | = | soil's saturated hydraulic conductivity (ft/sec) |
-| *θ20* | = | moisture content at the top of the soil layer (fraction), |
-| *ψ2* | = | suction head at the infiltration wetting front formed in the soil (ft) |
-| *F* | = | cumulative infiltration volume per unit area over a storm event (ft) |
-
-This equation applies only after a saturated condition develops at the
-top of the soil zone. Prior to this all inflow (*i + q0*) infiltrates.
-The initial value of *θ20* for a dry soil would be its residual
-moisture content or its wilting point. It increases after each rainfall
-event, then decreases during dry periods. The details of implementing
-the Green-Ampt model over successive time steps are described in Chapter
-4 of Volume I of this manual. The properties *K2S*, *φ2*, and *ψ2*
-for the bio-retention cell's amended soil can be different from those of
-the site's natural soil. This can produce a different infiltration rate
-into the LID unit when compared to that for rest of the subcatchment.
-
-[Evapotranspiration (*e*)]{.underline}
-
-Evapotranspiration (ET) of water stored within the bio-retention cell is
-computed from the same user-supplied time series of daily potential ET
-rates that are used in SWMM's runoff module (see Chapter 2 of Volume I).
-The calculation proceeds from the surface layer downwards, where any
-un-used potential ET is made available to the next lower layer. So at
-any time *t*:
-
-
-$$e_{1} = min\left\lbrack E_{0}(t),\ \frac{d_{1}}{\Delta t} \right\rbrack \qquad \text{(6-5)}$$
-
-
-$$e_{2} = min\left\lbrack E_{0}(t) - e_{1}\ ,\frac{\left( \theta_{2} - \theta_{WP} \right)D_{2}}{\mathrm{\Delta}t} \right\rbrack \qquad \text{(6-6)}$$
-
-
-$$e_{3} = \left\{ \begin{aligned}
-\min\left\lbrack E_{0}(t) - e_{1} - e_{2}\ ,\ \frac{\phi_{3}d_{3}}{\mathrm{\Delta}t} \right\rbrack,\ \ \  & \theta_{2} < \phi_{2} \\
-0,\ \  & \theta_{2} \geq \phi_{2}
-\end{aligned} \right.\ \qquad \text{(6-7)}$$
-
-
-where $E_{0}(t)$ is the potential ET rate that applies for time *t*,
-*∆t* is the time step used to numerically evaluate the governing flow
-balance equations 6-1 to 6-3, and $\theta_{WP}$ is the user-supplied
-wilting point soil moisture content. A soil's wilting point is the
-moisture content below which plants can no longer extract water from the
-soil. Thus when the soil moisture *θ2* reaches the wilting point there
-is no contribution to ET from the soil layer.
-
-Note how ET from each layer is limited by the amount of potential ET
-remaining and the amount of water stored in the layer. In addition:
-
-- *e3* is zero when the soil zone becomes saturated.
-
-- *e2* and *e3* are zero during periods with surface infiltration
-  ($f_{1} > 0$) since it is assumed that the resulting vapor pressure
-  will be high enough to prevent any ET from occurring.
-
-[Soil Percolation (*f2*)]{.underline}
-
-The rate of percolation of water through the soil layer into the storage
-layer below it (*f2)* can be modeled using Darcy's Law in the same
-manner used in SWMM's existing groundwater module (see Chapter 5 of
-Volume I). The resulting equation for this flux is:
-
-
-$$f_{2} = \left\{ \begin{aligned}
-K_{2S}\exp\left( - HCO\left( \phi_{2} - \theta_{2} \right) \right),\ \ \  & \theta_{2} > \theta_{FC} \\
-0,\ \  & \theta_{2} \leq \theta_{FC}
-\end{aligned} \right.\ \qquad \text{(6-8)}$$
-
-
-
-where *K2S* is the soil's saturated hydraulic conductivity (ft/sec),
-*HCO* is a decay constant derived from moisture retention curve data
-that describes how conductivity decreases with decreasing moisture
-content, and *θFC* is the soil's field capacity moisture content. The
-same expression for unsaturated soil percolation is used in SWMM's
-groundwater module. When the moisture content *θ2* drops below the
-field capacity moisture level *θFC* then the percolation rate becomes
-zero. This limit is in accordance with the concept of field capacity as
-the drainable soil water that cannot be removed by gravity alone
-(Hillel, 1982, p. 243).
-
-[Bottom Exfiltration (*f3*)]{.underline}
-
-The exfiltration rate from the bottom of the storage zone into native
-soil would normally depend on the depth of stored water and the moisture
-profile of the soil beneath the LID unit. Since the latter is not known,
-SWMM assumes that the exfiltration rate $f_{3}$ is simply the
-user-supplied saturated hydraulic conductivity of the native soil
-beneath the LID unit, *K3S*. Setting *K3S*to zero indicates that
-the bio-retention cell has an impermeable bottom.
-
-[Underdrain Flow (*q3*)]{.underline}
-
-Because the hydraulics of perforated pipe underdrains can be complicated
-(see van Schilfgaarde 1974) SWMM uses a simple empirical power law to
-model underdrain outflow *q3*:
-
-
-$$q_{3} = C_{3D}\left( h_{3} \right)^{\eta_{3D}} \qquad \text{(6-9)}$$
-
-
-
-where
-
-  *h3*     =  hydraulic head seen by underdrain, (ft)
-  *C3D*    =  underdrain discharge coefficient
-                ($\frac{{ft}^{- (\eta_{3D} - 1)}}{\sec}$)
-
-  *η3D*    =  underdrain discharge exponent
-
-The hydraulic head *h3* seen by the underdrain varies with the height
-of water above it in the following fashion:
-
-         $h_{3} = 0$                                                                                                                              for $d_{3} \leq D_{3D}$
-         $$h_{3} = d_{3} - D_{3D}$$                                                                                                               for $D_{3D} < d_{3} < D_{3}$
-
-         $$h_{3} = \left( D_{3} - D_{3D} \right) + \frac{\left( \theta_{2} - \theta_{FC} \right)}{\left( \phi_{2} - \theta_{FC} \right)D_{2}}$$   for $d_{3} = D_{3}$ and
-                                                                                                                                                  $\theta_{FC} < \theta_{2} < \phi_{2}$
-
-         $$h_{3} = \left( D_{3} - D_{3D} \right) + D_{2} + d_{1}$$                                                                                for $d_{3} = D_{3}$ and
-                                                                                                                                                  $\theta_{2} = \phi_{2}$
-
-where *D3D* is the height of drain opening above bottom of storage
-layer (ft) and $\theta_{FC}$ is the soil layer's field capacity moisture
-content below which water does not drain freely from the soil.
-
-Underdrains introduce three additional parameters *C3D, η3D,* and
-*D3D*, into the description of a bio-retention cell. There is no
-underdrain flow until the depth of water in the storage layer reaches
-the drain offset height. Choosing a value of 0.5 for *η3D* makes the
-drain flow formula equivalent to the standard orifice equation, where
-*C3D* incorporates both the normal orifice discharge coefficient and
-available flow area. Setting *C3D* to zero indicates that no
-underdrain is present. The flow rate computed with Equation 6-9 should
-be considered a maximum potential value. The actual underdrain flow at
-any time step will be the smaller of this value and the amount of water
-available to the underdrain.
-
-[Surface Runoff (*q1*)]{.underline}
-
-It is assumed that any ponded surface water in excess of the maximum
-freeboard (or depression storage) height *D1* becomes immediate
-overflow. Therefore:
-
-
-$$q_{1} = max\left\lbrack \frac{\left( d_{1} - D_{1} \right)}{\mathrm{\Delta}t},\ 0 \right\rbrack \qquad \text{(6-10)}$$
-
-
-
-[Flux Limits]{.underline}
-
-Limits must be imposed on the various bio-retention cell flux rates to
-insure that at any given time step the moisture levels in the soil and
-storage layers do not go negative nor exceed the layer's capacity. These
-limits are evaluated in the order listed below.
-
-1.  The soil percolation rate *f2* is limited by the amount of
-    drainable water currently in the soil layer plus the net amount of
-    water added to it over the time step:
-
-
-$$f_{2} = min\left\lbrack \frac{f_{2}\ ,\left( \theta_{2} - \theta_{FC} \right)D_{2}}{\mathrm{\Delta}t} + f_{1} - e_{2} \right\rbrack \qquad \text{(6-11)}$$
-
-
-
-2.  The storage exfiltration rate *f3* is limited by the amount of
-    water currently in the storage layer plus the net amount of water
-    added to it over the time step:
-
-
-$$f_{3} = min\left\lbrack \frac{f_{3}\ ,d_{3}\phi_{3}}{\mathrm{\Delta}t} + f_{2} - e_{3} \right\rbrack \qquad \text{(6-12)}$$
-
-
-
-3.  When an underdrain is used, the drain flow *q3* is limited by the
-    amount of water stored above the drain offset plus any excess inflow
-    from the soil layer that remains after storage exfiltration is
-    accounted for:
-
-
-$$q_{3} = min\left\lbrack \frac{q_{3}\ ,{\left( d_{3} - D_{3D} \right)\phi}_{3}}{\mathrm{\Delta}t} + f_{2} - f_{3} - e_{3} \right\rbrack \qquad \text{(6-13)}$$
-
-
-
-4.  The soil percolation rate is also limited by the amount of unused
-    volume in the storage layer plus the net amount of water removed
-    from storage over the time step.
-
-
-$$f_{2} = min\left\lbrack \frac{f_{2}\ ,{\left( D_{3} - d_{3} \right)\phi}_{3}}{\mathrm{\Delta}t} + f_{3} + q_{3} + e_{3} \right\rbrack \qquad \text{(6-14)}$$
-
-
-
-5.  The rate *f1* at which water can infiltrate into the soil layer is
-    limited by the amount of empty pore space available plus the volume
-    removed by drainage and evaporation over the time step.
-
-
-$$f_{1} = min\left\lbrack \frac{f_{1}\ ,{\left( \phi_{2} - \theta_{2} \right)D}_{2}}{\mathrm{\Delta}t} + f_{2} + e_{2} \right\rbrack \qquad \text{(6-15)}$$
-
-
-
-When the unit becomes completely saturated (i.e., *θ2 = φ2* and
-*d3 = D3*) then the vertical flux of water through both the soil and
-storage layers has to be the same since there is a common fully wetted
-interface between them. For this special case, if
-$f_{2} > f_{3} + q_{3}$ then $f_{2} = f_{3} + q_{3}$. Otherwise
-$f_{3} = min\left\lbrack f_{3}\ ,f_{2} \right\rbrack$ and
-$q_{3} = max\left\lbrack f_{3} - f_{2}\ ,0 \right\rbrack.$ In addition
-the surface infiltration rate *f1* cannot exceed the adjusted soil
-percolation rate: $f_{1} = min\left\lbrack f_{1},f_{2} \right\rbrack$.
-(Note that because the unit is saturated no sub-surface ET occurs and
-therefore does not influence these limits.)
-
-It is worth noting that this simple representation of a bio-retention
-cell uses a total of 15 user-supplied parameters in its description: two
-surface layer parameters (*φ1, D1*) seven soil layer parameters
-(*φ2, θFC, θWP, K2S, ψ2, HCO, D2*), three storage layer
-parameters *(φ3, K3S*, *D3)* and three underdrain parameters
-(*C3D, η3D*, *D3D*). The six constants that define the soil
-layer's moisture limits
-($\phi_{2},\ {\psi_{2},\ \theta}_{FC},\ \theta_{WP}$) and hydraulic
-conductivity ($K_{2S},\ HCO$) are the same parameters used for
-infiltration and groundwater flow in SWMM's hydrology module (see
-Chapters 4 and 5 of Volume I). Because the soil used in a bio-retention
-cell is an engineered mix chosen to provide good drainage and support
-plant growth its properties will likely be different than those of the
-site's native soil. Recommended values for the various parameters
-associated with all types of LID controls will be presented later on in
-Section 6.6.
-
-The governing flow balance equations for the other LID controls modeled
-by SWMM are similar in form to those for bio-retention cells. The
-following sub-sections discuss the models for rain gardens, green roofs,
-infiltration trenches, permeable pavement, rain barrels, rooftop
-disconnection, and vegetative swales in that order.
-
-### 6.2.2 Rain Gardens
-
-SWMM defines a rain garden as a bio-retention cell without a storage
-layer. Its governing equations are therefore:
-
-
-$$\phi_{1}\frac{\partial d_{1}}{\partial t} = i + q_{0} - e_{1} - f_{1} - q_{1} \qquad \text{Surface Layer} \qquad \text{(6-16)}$$
-
-
-$$D_{2}\frac{\partial\theta_{2}}{\partial t} = f_{1} - e_{2} - f_{2} \qquad \text{Soil Layer} \qquad \text{(6-17)}$$
-
-
-The nominal soil percolation rate *f2* is computed via Equation 6-8.
-It is then limited to the smaller of this value, the amount of drainable
-water available in the soil layer (Equation 6-11) and the saturated
-hydraulic conductivity of the native soil beneath the rain garden
-(*K3S*). The remaining flux rates are computed as described earlier.
-
-### 6.2.3 Green Roofs
-
-SWMM's green roof is also similar to a bio-retention cell, except it
-uses a drainage mat instead of gravel aggregate in its storage layer.
-Drainage mats are thin, multi-layer fabric mats with ribbed undersides
-that convey water. They have somewhat limited water storage and drainage
-capacity and are therefore mostly used on sloped roofs. Another type of
-roof drainage system also suitable for flatter roofs uses slotted pipes
-placed in a gravel bed and is therefore functionally equivalent to a
-bio-retention cell with an impermeable bottom ($K_{3S} = 0$) and an
-underdrain.
-
-The governing equations for a green roof with a drainage mat would be:
-
-
-$$\phi_{1}\frac{\partial d_{1}}{\partial t} = i - e_{1} - f_{1} - q_{1} \qquad \text{Surface Layer} \qquad \text{(6-18)}$$
-
-
-$$D_{2}\frac{\partial\theta_{2}}{\partial t} = f_{1} - e_{2} - f_{2} \qquad \text{Soil Layer} \qquad \text{(6-19)}$$
-
-
-$$\phi_{3}\frac{\partial d_{3}}{\partial t} = f_{2} - e_{3} - q_{3} \qquad \text{Drainage Mat Layer} \qquad \text{(6-20)}$$
-
-
-Note the absence of the captured runoff term *q0* in Equation 6-18
-since a green roof would only be capturing direct rainfall. There is
-also no exfiltration term *f3* since the bottom of a green roof
-consists of an impermeable membrane.
-
-The runoff rate from the soil layer surface (*q1*) is computed using
-the Manning equation for uniform overland flow. Under the assumption
-that the width of the flow area is much greater than the depth of flow
-the Manning equation becomes:
-
-
-$$q_{1} = \frac{1.49}{n_{1}}\sqrt{S_{1}}(\frac{W_{1}}{A_{1})\phi_{1}\left( d_{1} - D_{1} \right)^{\frac{5}{3}}} \qquad \text{(6-21)}$$
-
-
-
-where
-
-  *n1*    =  surface roughness coefficient,
-  *S1*    =  surface slope (ft/ft),
-
-  *W1*    =  total length along edge of the roof where runoff is collected
-               (ft),
-
-  *D1*    =  surface depression storage depth (ft),
-
-  *A1*    =  roof surface area (ft2).
-
-All of these surface parameters are supplied by the user as part of the
-green roof's design. The "surface" that these parameters describe is the
-surface of the soil layer. The $\frac{W_{1}}{A_{1}}$ term represents the
-length of the flow path that excess water takes before it enters the
-roof's drain system (see Figure 6-2). When the depth of ponded water
-*d1* is at or below the depression storage depth *D1* then no
-surface outflow occurs.
-
-![[]{#_Toc454288778 .anchor}**Figure 6‑2 Flow path across the surface of
-a green roof**](./media/media/image33.png){width="3.09375in"
-height="2.2604166666666665in"}
-
-Another option for surface outflow is to have any ponded surface water
-in excess of the depression storage *D1* become instantaneous runoff
-using Equation 6-10. This is done by setting either *n1*, *S1*, or
-*W1* to zero. This may be a better choice for roofs with short flow
-path lengths or flat roofs that use internal roof drains.
-
-The drainage mat flow rate *q3*in Equation 6-20 is assumed to obey
-uniform open channel flow within the channels of the mat. Thus it can be
-expressed as:
-
-
-$$q_{3} = \frac{1.49}{n_{3}}\sqrt{S_{1}}(\frac{W_{1}}{A_{1}){\phi_{3}\left( d_{3} \right)}^{\frac{5}{3}}} \qquad \text{(6-22)}$$
-
-
-
-where *n3* is a roughness coefficient for the mat and *S1*, *W1*,
-and *A1* are the same slope, outflow face width, and roof surface
-area, respectively, used to evaluate surface overflow (*q1*).
-
-The remaining flux rates in Equations 6-18 to 6-20 are evaluated in the
-same fashion as for the bio-retention cell. In addition, the same flux
-limiting conditions for the bio-retention cell (Equations 6-11 through
-6-15) are applied to the green roof to insure that the values used for
-*f1*, *f2*, and *q3* maintain feasible moisture levels for the
-soil and drainage layers after each time step.
-
-### 6.2.4 Infiltration Trenches
-
-An infiltration trench can be represented in the same fashion as a
-bio-retention cell but having just a surface and a storage layer. The
-governing equations are:
-
-
-$$\frac{\partial d_{1}}{\partial t} = i + q_{0} - e_{1} - f_{1} - q_{1} \qquad \text{Surface Layer} \qquad \text{(6-23)}$$
-
-
-$$\phi_{3}\frac{\partial d_{3}}{\partial t} = f_{1} - {e_{3} - f}_{3} - q_{3} \qquad \text{Storage Layer} \qquad \text{(6-24)}$$
-
-
-where now *f1* is the trench's external inflow plus any ponded surface
-water that drains into the storage layer over the time step:
-
-
-$$f_{1} = i + \ q_{0} + \frac{d_{1}}{\mathrm{\Delta}t} \qquad \text{(6-25)}$$
-
-
-
-Nominal values for the remaining flux terms are evaluated in the same
-fashion as for the bio-retention cell. The surface void fraction *φ1*
-does not appear in the surface layer equation since a gravel-filled
-trench would have no vegetative growth above it.
-
-These nominal rates are subject to the following constraints:
-
-1.  The storage exfiltration rate *f3* is limited by the amount of
-    water currently in the storage layer plus the net amount of water
-    added to it over the time step:
-
-
-$$f_{3} = min\left\lbrack \frac{f_{3}\ ,d_{3}\phi_{3}}{\mathrm{\Delta}t} + f_{1} - e_{3} \right\rbrack \qquad \text{(6-26)}$$
-
-
-
-2.  When an underdrain is used, the drain flow *q3* is limited by the
-    amount of water stored above the drain offset plus any excess inflow
-    from the surface that remains after storage exfiltration is
-    accounted for:
-
-
-$$q_{3} = min\left\lbrack \frac{q_{3}\ ,{\left( d_{3} - D_{3D} \right)\phi}_{3}}{\mathrm{\Delta}t} + f_{1} - f_{3} - e_{3} \right\rbrack \qquad \text{(6-27)}$$
-
-
-
-3.  The surface inflow rate *f1* is limited by the amount of empty
-    storage layer space available plus the volume removed by
-    exfiltration, underdrain flow, and evaporation over the time step:
-
-
-$$f_{1} = min\left\lbrack \frac{f_{1}\ ,\left( D_{3} - d_{3} \right)\phi_{3}}{\mathrm{\Delta}t} + f_{3} + q_{3} + e_{3} \right\rbrack \qquad \text{(6-28)}$$
-
-
-
-### 6.2.5 Permeable Pavement
-
-Figure 6-3 illustrates a typical continuous permeable pavement system.
-It consists of a pervious concrete or asphalt top layer, an optional
-sand filter or bedding layer beneath that and a gravel storage layer on
-the bottom which can contain an optional slotted pipe underdrain system.
-It introduces a new type of layer, a pavement layer (layer 4), which is
-characterized by its thickness (*D4*), porosity (*φ4*), and
-permeability *K4*. A block paver system would look the same but with
-an additional parameter (*F4*) representing the fraction of the
-surface area taken up by the impermeable paver blocks and where the
-porosity and permeability refer to the fine gravel used to fill the
-seams between blocks. For continuous systems *F4* would be 0.
-
-

-PermPavement.png
-
Figure 6‑3 Representation of a permeable
-pavement system

-

-
-The governing equations for permeable pavement with a sand layer
-included are:
-
-
-$$\frac{\partial d_{1}}{\partial t} = i + q_{0} - e_{1} - f_{1} - q_{1} \qquad \text{Surface Layer} \qquad \text{(6-29)}$$
-
-
-$$D_{4}\left( 1 - F_{4} \right)\frac{\partial\theta_{4}}{\partial t} = f_{1} - e_{4} - f_{4} \qquad \text{Pavement Layer} \qquad \text{(6-30)}$$
-
-
-$$D_{2}\frac{\partial\theta_{2}}{\partial t} = f_{4} - e_{2} - f_{2} \qquad \text{Sand Layer} \qquad \text{(6-31)}$$
-
-
-$$\phi_{3}\frac{\partial d_{3}}{\partial t} = f_{2} - {e_{3} - f}_{3} - q_{3} \qquad \text{Storage Layer} \qquad \text{(6-32)}$$
-
-
-where $\theta_{4}$ is the moisture content of the permeable pavement
-layer, $f_{4}$ is the rate at which water drains out of the pavement
-layer, and all other terms have been defined previously. Note that when
-no sand layer is present, Equation 6-31 is removed and $f_{4}$ replaces
-$f_{2}$ in the storage layer Equation 6-32. Also, the surface void
-fraction *φ1* does not appear in the surface layer equation since a
-paved surface would have no vegetative growth above it.
-
-The flux terms in these equations are evaluated in the same manner as
-for the bio-retention cell with the following exceptions:
-
-1.  Evaporation of any water stored in the pavement layer, *e4*, would
-    proceed at the rate:
-
-
-$$e_{4} = min\left\lbrack E_{0}(t) - e_{1}\ ,\frac{\theta_{4}D_{4}\left( 1 - F_{4} \right)}{\mathrm{\Delta}t} \right\rbrack \qquad \text{(6-33)}$$
-
-
-
-with *E0(t)* subsequently reduced by *e4* when ET from the layers
-below it is evaluated.
-
-2.  The nominal flux rate from the surface layer into the pavement layer
-    (*f1*) is the same as for an infiltration trench:
-
-
-$$f_{1} = i + \ q_{0} + \frac{d_{1}}{\mathrm{\Delta}t} \qquad \text{(6-34)}$$
-
-
-
-3.  The nominal flux rate leaving the pavement layer (*f4*) is equal
-    to the pavement's permeability *K4*.
-
-4.  When evaluating underdrain outflow *q3*, once both the storage
-    layer and sand layer (if present) become saturated, the head on the
-    underdrain becomes:
-
-
-$$h_{3} = \left( D_{3} - D_{3D} \right) + D_{2} + \frac{\theta_{4}D_{4}}{\phi_{4}} \qquad \text{(6-35)}$$
-
-
-
-5.  The flux rate from the surface into the pavement is limited by the
-    rate at which the pavement can accept inflow:
-
-The following adjustments are applied to the nominal flux rates in the
-order listed so that feasible moisture levels are maintained:
-
-1.  Pavement flux rate *f4* :
-
-
-$$f_{4} = min\left\lbrack \frac{f_{4}\ ,\theta_{4}D_{4}}{\mathrm{\Delta}t} + f_{1} - e_{4} \right\rbrack \qquad \text{(6-36)}$$
-
-
-
-2.  Soil percolation rate *f2* :
-
-
-$$f_{2} = min\left\lbrack \frac{f_{2}\ ,\left( \theta_{2} - \theta_{FC} \right)D_{2}}{\mathrm{\Delta}t} + f_{4} - e_{4} \right\rbrack \qquad \text{(6-37)}$$
-
-
-
-3.  Storage exfiltration rate *f3* :
-
-
-$$f_{3} = min\left\lbrack \frac{f_{3}\ ,d_{3}\phi_{3}}{\mathrm{\Delta}t} + f_{2} - e_{3} \right\rbrack \qquad \text{(6-38)}$$
-
-
-
-> where *f2 = f4* if there is no soil layer.
-
-4.  Underdrain flow *q3* (when present):
-
-
-$$q_{3} = min\left\lbrack \frac{q_{3}\ ,{\left( d_{3} - D_{3D} \right)\phi}_{3}}{\mathrm{\Delta}t} + f_{2} - f_{3} - e_{3} \right\rbrack \qquad \text{(6-39)}$$
-
-
-
-> where again *f2 = f4* if there is no soil layer.
-
-5.  Pavement flux rate *f4* :
-
-        $\frac{f_{4} = min\lbrack f_{4}\ ,\left( \phi_{2} - \theta_{2} \right)D_{2}}{\mathrm{\Delta}t + f_{2} + e_{2}\rbrack}$             with soil layer   (6-40)
-                                                                                                                                                           
-
-
-$$\frac{f_{4} = min\lbrack f_{4}\ ,\left( D_{3} - d_{3} \right)\phi_{3}}{\mathrm{\Delta}t + e_{3} + f_{3} + q_{3}\rbrack} \qquad \text{without soil layer} \qquad \text{(6-41)}$$
-
-
-6.  Soil percolation rate *f2* :
-
-
-$$f_{2} = min\left\lbrack \frac{f_{2}\ ,{\left( D_{3} - d_{3} \right)\phi}_{3}}{\mathrm{\Delta}t} + f_{3} + q_{3} + e_{3} \right\rbrack \qquad \text{(6-42)}$$
-
-
-
-7.  Pavement inflow rate *f1* :
-
-
-$$f_{1} = min\left\lbrack f_{1}\ ,\ \frac{\left( \phi_{4} - \theta_{4} \right)D_{4}\left( 1 - F_{4} \right)}{\mathrm{\Delta}t} + f_{4} + e_{4} \right\rbrack \qquad \text{(6-43)}$$
-
-
-
-The flux adjustments for fully saturated storage and sand layers follow
-those used for a bio-retention cell. When all of the sub-surface layers
-become saturated *(θ2* = *φ2*, *d3 = D3* and *θ4 = φ4*), and
-the unit is still receiving rainfall/runon then all flux rates are set
-equal to the limiting rate. The latter is the smaller of *f1, f4,
-f2* (if a sand layer is present), and *f3 + q3*. If the storage
-layer does not contain the limiting flux f\*, then its outflow streams
-are adjusted as follows:
-$q_{3} = min\left\lbrack q_{3}\ ,f^{*} \right\rbrack$ and
-$f_{3} = f^{*} - q_{3}$.
-
-### 6.2.6 Rain Barrels
-
-A rain barrel can be modeled as just a storage layer that is all void
-space with a drain valve placed above an impermeable bottom. Only a
-single continuity equation is required:
-
-
-$$\frac{\partial d_{3}}{\partial t} = f_{1} - q_{1} - q_{3} \qquad \text{Storage Layer} \qquad \text{(6-44)}$$
-
-
-
-where *f1* now represents the amount of surface inflow captured by the
-barrel. Because the barrel is assumed to be covered there is no
-precipitation input and no evaporation flux. The general underdrain
-equation 6-7 would still be used to compute the barrel's drain flow
-*q3*. If the standard orifice equation is used to compute the drain
-outflow, then *η3D* in Equation 6-7 would be 0.5 and *C3D* would be:
-
-
-$$C_{3D} = 0.6\left( \frac{A_{3}}{A_{1}} \right)\sqrt{2g} \qquad \text{(6-45)}$$
-
-
-
-where *A1* is the surface area of the barrel, *A3* is the area of
-the drain valve opening (ft2) and *g* is the acceleration of gravity
-(i.e., 32.2 ft/sec2). The outflow over a time step *∆t* would be
-limited by the volume of water stored in the barrel:
-
-
-$$q_{3} = min\left\lbrack q_{3}\ ,\frac{d_{3}}{\mathrm{\Delta}t} \right\rbrack \qquad \text{(6-46)}$$
-
-
-
-SWMM allows the drain valve to be closed prior to a rainfall event and
-then opened at some stipulated number of hours after rainfall ceases. If
-the valve is closed then *q3* would be 0.
-
-The inflow to the barrel is the smaller of the external runoff *q0*
-applied to the barrel and the amount of empty storage available over the
-time step:
-
-
-$$f_{1} = min\left\lbrack q_{0}\ ,\frac{\left( D_{3} - d_{3} \right)}{\mathrm{\Delta}t + q_{3}} \right\rbrack \qquad \text{(6-47)}$$
-
-
-
-And finally the barrel overflows at a rate *q1* when the runoff
-applied to the barrel exceeds its capacity to accept that amount of
-inflow:
-
-
-$$q_{1} = max\left\lbrack 0\ ,q_{0} - f_{1} \right\rbrack \qquad \text{(6-48)}$$
-
-
-
-### 6.2.7 Rooftop Disconnection
-
-Rooftop areas contained within a SWMM subcatchment are normally treated
-as impervious surfaces whose runoff is directly connected to the
-subcatchment's storm drain outlet. By using SWMM's overland flow
-re-routing option it is possible to disconnect the rooftop area and make
-its runoff flow over the subcatchment's pervious area where it has the
-opportunity to infiltrate into the soil (see Section 3.6 of Volume I).
-The rooftop disconnection LID control provides another alternative to
-model rooftop runoff that allows for a higher level of detail than
-overland flow re-routing.
-
-Figure 6-4 shows the physical configuration modeled by rooftop
-disconnection. Runoff from the roof surface is collected in a drain
-system of gutters, downspouts, and leaders. Any flow that exceeds the
-capacity of the roof drain system becomes overflow that can be re-routed
-onto pervious area. The roof drain flow can also be routed back onto
-pervious area (to disconnect the roof) or be sent to a storm sewer to
-keep the roof directly connected. Another option, used when modeling
-dual drainage systems (both street flow and sewer flow), is to allow the
-overflow to contribute to the major (street) system and the roof drain
-flow to the minor (sewer) system.
-
-

-RoofDiscon.png
-
Figure 6‑4 Representation of rooftop
-disconnection

-

-
-To model a rooftop in the same fashion as the other LID controls
-requires a single flow continuity equation for the roof surface:
-
-
-$$\frac{\partial d_{1}}{\partial t} = i - e_{1} - q_{1} - q_{3} \qquad \text{Surface Layer} \qquad \text{(6-49)}$$
-
-
-
-where now *q3* is interpreted as the flow rate per unit of roof area
-through the roof drain system and *q1* is the overflow rate from that
-system.
-
-Evaporation from the roof surface (*e1*) is computed in the same
-fashion as for the surface of a bio-retention cell (Equation 6-4). The
-nominal runoff *q1* from the roof's surface, prior to entering the
-roof gutter, is also computed the same as for a green roof. The Manning
-equation 6-21 is used if information is provided on the roof's width,
-slope, and surface roughness. However now the roughness is for the roof
-surface itself and not the growth media found on a green roof. Otherwise
-Equation 6-10 is used to convert all flow in excess of any rooftop
-depression storage (*D1*) into immediate runoff. The amount of flow
-through the roof drain, *q3*, is the smaller of the nominal *q1* and
-the flow capacity of the roof drain system (*q3max*):
-
-
-$$q_{3} = min\left\lbrack q_{1}\ ,q_{3max} \right\rbrack \qquad \text{(6-50)}$$
-
-
-
-Note that *q3max* is a user-supplied parameter with units of cfs per
-square foot of roof area. The actual overflow rate *q1* is simply the
-difference between its nominal rate and *q3*.
-
-### 6.2.8 Vegetative Swale
-
-As shown in Figure 6-5, SWMM considers a vegetative swale to be a
-natural grass-lined trapezoidal channel that conveys captured runoff to
-another location while allowing it to infiltrate into the soil beneath
-it. It can be modeled with a single surface layer whose continuity
-equation is:
-
-
-$$A_{1}\frac{\partial d_{1}}{\partial t} = \left( i + q_{0} \right)A - (e_{1} + f_{1})A_{1} - q_{1}A \qquad \text{Surface Layer} \qquad \text{(6-51)}$$
-
-
-
-where *A1* is the surface area at water depth *d1* and *A* is the
-user-supplied surface area occupied by the swale across its full height
-*D1*. Unlike the other LID controls that were assumed to have a
-constant surface area throughout all layers, this equation accounts for
-a varying surface area as the depth of water in the swale changes.
-
-

-VegSwale.png
-
Figure 6‑5 Representation of a vegetative
-swale

-

-
-From simple geometry, the relation between surface area *A1* and depth
-of flow *d1* is:
-
-
-$$A_{1} = \frac{A}{W_{1}}\left\lbrack W_{1} - 2S_{X}\left( D_{1} - d_{1} \right) \right\rbrack \qquad \text{(6-52)}$$
-
-
-
-where *W1* is the width of the swale at its full height *D1* and
-*SX* is the slope (run over rise) of its trapezoidal side walls. The
-volume of water contained in the swale, *V1*, is the longitudinal
-length of the swale, $\frac{A}{W_{1}}$, multiplied by the area of the
-wetted cross-section, *AX*:
-
-
-$$V_{1} = \left( \frac{A}{W_{1}} \right)A_{X} \qquad \text{(6-53)}$$
-
-
-
-The wetted cross-sectional area is:
-
-
-$$A_{X} = d_{1}\left( W_{X} + d_{1}S_{X} \right)\phi_{1} \qquad \text{(6-54)}$$
-
-
-
-where *WX* is the width across the bottom of the swale's cross section
-(equal to $W_{1} - 2S_{X}D_{1}$) and *φ1* is the fraction of the
-volume above the surface not occupied by vegetation.
-
-The volumetric rate of evaporation of surface water in the swale,
-$e_{1}A_{1}$, is the smaller of the external potential ET rate,
-$E_{0}(t)A_{1}$ and the available volume of surface water over the time
-step, $\frac{V_{1}}{\mathrm{\Delta}t}$. Because the swale is assumed to
-sit on top of the subcatchment's native soil, the infiltration rate
-*f1* is the same value computed for the pervious area of the
-subcatchment by SWMM's runoff module (see Chapter 4 of Volume I for
-details).
-
-The swale's volumetric outflow rate, *q1A*, is computed using the
-Manning equation:
-
-
-$$q_{1}A = \frac{1.49}{n_{1}}\sqrt{S_{1}}\ A_{X}\ R_{X}^{\frac{2}{3}} \qquad \text{(6-55)}$$
-
-
-
-where *n1* is the roughness of the swale's surface, *S1* is its
-slope in the direction of flow, and *RX* is its hydraulic radius (ft).
-The latter quantity is given by:
-
-
-$$R_{X} = \frac{A_{X}}{\left( W_{X} + 2d_{1}\sqrt{1 + S_{X}^{2}} \right)} \qquad \text{(6-56)}$$
-
-
-
-To summarize, the parameters required to model a vegetative swale
-include its total surface area *A*, its top width *W1*, its maximum
-depth *D1*, its surface roughness *n1*, its longitudinal slope
-*S1*, the slope of its side walls *Sx*, and fraction of its volume
-not occupied by vegetation *φ1*.
-
-### 6.2.9 Clogging
-
-Clogging from fine sediment deposited within permeable pavement systems
-degrades infiltration rates over time (Ferguson, 2005) and their
-surfaces must be periodically vacuumed to maintain their performance
-(PWD, 2014). Infiltration trenches are also susceptible to clogging (US
-EPA, 1999) and typically require pretreatment with other BMPs, such as
-vegetated buffer strips, to remove coarse sediments (MDE, 2009).
-
-SWMM uses a simplified approach to determine how clogging will reduce
-the hydraulic conductivity of permeable pavement and of the soil
-underneath a gravel storage layer over time. It is based on the
-empirically derived model proposed by Siriwardene et al. (2007) and its
-linearized form used by Lee et al. (2015). In those models the hydraulic
-conductivity of the media in question decreases over time as a
-continuous function of the cumulative sediment mass load passing through
-it. Because clogging is a long-term phenomenon, cumulative sediment mass
-load can be replaced by cumulative inflow volume by assuming a constant
-long-term average sediment inflow concentration. This inflow volume can
-be adjusted for the amount of void space in the relevant LID layer so
-that hydraulic conductivity reduction becomes a function of the number
-of the layer's void volumes processed by the LID unit.
-
-If one defines a clogging factor *CF* as the number of layer void
-volumes treated to completely clog the layer and assumes a linear loss
-of conductivity with number of void volumes treated, then the
-conductivity *K* at some time *t* can be estimated as:
-
-
-$$K(t) = K(0)\left( 1 - \frac{Q(t)V_{void}}{CF} \right) \qquad \text{(6-57)}$$
-
-
-
-where *K(0)* is the initial conductivity, *Vvoid* is the volume of
-void space per unit area in the LID layer, and *Q(t)* is the cumulative
-inflow volume (per unit area) to the LID unit up through time *t*. The
-latter quantity can be evaluated as:
-
-
-$$Q(t) = \int_{0}^{t}{\left( i(\tau) + q_{0}(\tau) \right)d\tau} \qquad \text{(6-58)}$$
-
-
-
-where $i(\tau) + q_{0}(\tau)$ is the rainfall plus captured runoff
-inflow seen by the LID unit at time *τ*.
-
-Applying Equation 6-57 to the storage layer of an infiltration trench
-results in using the following value of *K3S* to evaluate the
-exfiltration rate from the bottom of the unit at time *t* (via Equation
-6-9):
-
-
-$$K_{3S}(t) = K_{3S}(0)\left( 1 - \frac{Q(t)D_{3}\phi_{3}}{{CF}_{3}} \right) \qquad \text{(6-59)}$$
-
-
-
-where *K3S(0)* is the initial saturated hydraulic conductivity of the
-soil beneath the bottom of the trench and *CF3* is the clogging factor
-for the trench.
-
-Doing the same for the pavement layer of a permeable pavement unit, the
-pavement's permeability *K4* at time *t* would be:
-
-
-$$K_{4}(t) = K_{4}(0)\left( 1 - \frac{Q(t)D_{4}\phi_{4}\left( 1 - F_{4} \right)}{{CF}_{4}} \right) \qquad \text{(6-60)}$$
-
-
-
-where *K4(0)* is the pavement's permeability at time 0 and *CF4* is
-the pavement's clogging factor.
-
-This simple clogging model requires only a single user-supplied
-parameter for each LID control that is subject to clogging, namely its
-clogging factor CF. If no value is provided (or its value is set to 0)
-then clogging is ignored.
-
-## 6.3 LID Deployment
-
-Before discussing the computational steps used to solve the governing
-LID equations it will be useful to describe the various options
-available for deploying LID controls within a SWMM project. Utilizing
-LID controls is a two phase process that first creates a set of
-scale-independent LID designs and then assigns any desired mix and
-sizing of these designs to selected subcatchments. Because all
-calculations are made on a per unit area basis, this approach also
-allows one to treat replicate units of a given design (e.g., forty
-50-gallon rain barrels) as if it were one larger LID unit.
-
-There are two different approaches for placing LID controls within the
-subcatchments of a SWMM model:
-
-1.  One or more controls are assigned to an existing subcatchment. Each
-    control receives some specified fraction of the runoff generated by
-    the subcatchment's impervious area.
-
-2.  A single LID control (or replicate units of the same design)
-    occupies the full area of a subcatchment. Its inflow consists of
-    direct rainfall plus runoff from any upstream subcatchments
-    connected to the subcatchment containing the LID unit.
-
-The first approach would typically be used in larger, area-wide studies
-where a mix of controls would be deployed over many different
-subcatchments. The second approach might apply to smaller study areas
-where detailed analysis of a particular LID treatment train would be
-desired.
-
-If a subcatchment with multiple LID units receives runoff from upstream
-subcatchments then that flow is first distributed uniformly over the
-pervious and impervious areas. The resulting impervious area runoff is
-then routed onto the various LID units. The options for routing any
-surface overflow and underdrain flow generated by an LID unit can be
-summarized as follows:
-
-1.  The default is to send these flows to the parent subcatchment's
-    outlet destination.
-
-2.  If so desired, underdrain flow from each unit can be routed to a
-    separate destination.
-
-3.  Another option, particularly appropriate for rain barrels, is to
-    route the unit's entire outflow back onto the subcatchment's
-    pervious area.
-
-Figure 6-6 illustrates some the options available for placing LID
-controls. Panel A of the figure shows a subcatchment containing two
-different types of controls, each receiving a different fraction of the
-subcatchment's impervious area runoff. LID1 contains an underdrain while
-LID2 does not. Any surface or underdrain flows from the units are sent
-to the same outlet node that was designated for the subcatchment as a
-whole. Panel B is similar to Panel A except that LID1 sends its
-underdrain flow to a different outlet than the subcatchment as a whole.
-In Panel C of the figure, LID1 now sends its surface overflow and
-underdrain flow back to the subcatchment's pervious area. Finally Panel
-D illustrates the case of two LID units in series, where each unit
-occupies its entire subcatchment. The inflow to LID1 comes from an
-upstream subcatchment and its surface overflow is routed to LID2. Its
-underdrain flow is sent to the same outlet location used by LID2.
-
-![LidOptions.png](./VolumeIII/media/media/image37.png){width="6.5in"
-height="8.046527777777778in"}
-
-[]{#_Toc454288782 .anchor}**Figure 6‑6 Different options for placing LID
-controls**
-
-## 6.4 Computational Steps
-
-LID computations are a sub-procedure of SWMM's runoff calculations. They
-are made at each runoff time step, for each subcatchment that contains
-LID controls, immediately after the runoff from the non-LID portions
-(both pervious and impervious) of the subcatchment have been found and
-before any groundwater calculations are made (see Section 3.4 of Volume
-I). The computations for an individual LID unit include the following
-four steps:
-
-1.  Determine the amount of inflow ($i + q_{0}$) treated by the LID
-    unit.
-
-2.  Evaluate the various flux terms (*e, f* and *q*) on the right-hand
-    side of the applicable flow continuity equations.
-
-3.  Solve the continuity equations for the new value of each layer's
-    moisture level at the end of the time step.
-
-4.  Add the unit's surface runoff (*q1*), infiltration (*f3*), and
-    underdrain flow (*q3*) to the subcatchment's totals.
-
-The process of determining the inflow to the LID unit in step 1 depends
-on whether the unit comprises only a portion of its subcatchment's area
-or if it occupies the entire subcatchment. In the former case the runoff
-rate *q0* treated by the unit can be computed as:
-
-
-$$q_{0} = q_{imp}F_{out}R_{LID} \qquad \text{(6-61)}$$
-
-
-
-where
-
-  *qimp*    =  total impervious area runoff rate (ft/sec),
-  *Fout*    =  fraction of impervious area runoff routed to the
-                 subcatchment's outlet,
-
-  *RLID*    =  capture ratio of the LID unit.
-
-Note that *Fout* accounts for the possibility that the user has
-assigned some portion of the subcatchment's impervious area runoff to be
-re-routed onto its pervious area using SWMM's overland flow re-routing
-option (explained in Section 3.6 of Volume I). When there is no internal
-re-routing (or disconnecting) of impervious area *Fout* is equal to
-1.0. Also introduced is a new parameter, the LID unit's capture ratio
-*RLID*. It is defined as the amount of the subcatchment's impervious
-area that is directly connected to the LID unit divided by the area of
-the LID unit itself.
-
-When a single LID unit occupies the entire subcatchment *q0* is
-comprised of any external overland flow routed onto the subcatchment.
-Such flow can consist of runoff originating from other upstream
-subcatchments as well as any underdrain flow from other LID units routed
-onto the subcatchment.
-
-Step 2 of the computational procedure evaluates the flux terms on the
-right hand side of the governing continuity equation for each layer of
-the LID unit being analyzed. These terms depend on the current moisture
-level stored in each layer. Section 6.2 has discussed in detail how each
-flux term is computed. Recall that evapotranspiration is evaluated
-first, moving from the top to the bottom of the LID unit. The remaining
-flux terms are then evaluated in the opposite direction, moving from the
-bottom to the topmost layer of the unit.
-
-Step 3 integrates the governing continuity equations over a single time
-step to find new values for the moisture content in each of the LID
-unit's layers. Let ***x*** be the vector of the layer moisture contents,
-where ***x*** = \[*φ1d1, D2θ2, φ3d3, D4(1-F4)θ4*\],
-and let ***Γ*** = \[*Γ1, Γ2, Γ3, Γ4*\] be the vector of the net
-flux (inflow minus outflow) of water through each layer (i.e., the right
-hand side value of each layer's continuity equation). If a particular
-layer *i* does not apply to a given LID unit, such as the soil layer for
-a rain barrel, then both *xi* and *Γi*would be zero. Now the flow
-continuity equations can be written more compactly as:
-
-
-$$\frac{\partial\mathbf{x}}{\partial t} = \mathbf{\Gamma}(\mathbf{x(}t\mathbf{)}) \qquad \text{(6-62)}$$
-
-
-
-where in general ***Γ*** is a nonlinear function of ***x***.
-
-This system of equations can be solved numerically by using the
-trapezoidal method (Ascher and Petzold, 1998) to discretize them in time
-as follows:
-
-
-$$\mathbf{x}(t + \mathrm{\Delta}t) = \mathbf{x}(t)\mathbf{+}\left\lbrack \Omega\mathbf{\Gamma}(\mathbf{x}(t + \mathrm{\Delta}t)\mathbf{+ (}1 - \Omega\mathbf{)\Gamma}(\mathbf{x}(t)\mathbf{)} \right\rbrack\mathbf{\mathrm{\Delta}}t \qquad \text{(6-63)}$$
-
-
-
-where *Ω =* 0.5 and ∆t is the wet hydrologic time step used for
-computing runoff. (See Section 3.5 of Volume I for a discussion of
-SWMM's runoff time steps.) This equation makes the new moisture content
-in the LID unit equal to the previous moisture content plus the average
-net flow volume occurring over the time step. At time 0 the moisture
-content in the LID unit's soil and storage layers is set to a
-user-supplied percent of saturation while the other layer moisture
-levels 00start at 0.
-
-Because ***Γ**(**x**(t+∆t))* appearing on the right hand side of
-Equation 6-55 depends on the unknown new moisture content, an iterative
-method must be used to solve the equation. Let ***x**(t+∆t)ν* be the
-estimate of ***x**(t+∆t)* at iteration *ν*, where initially
-***x**(t+∆t)0 = **x**(t)*. (Note that *ν* is an iteration counter, not
-a power.) Then for iteration *ν+1* the new estimate of ***x**(t+∆t)* is:
-
-
-$$\mathbf{x}{(t + \mathrm{\Delta}t)}^{\nu + 1}\mathbf{= x}(t)\mathbf{+}\left\lbrack \Omega\mathbf{\Gamma}(\mathbf{x}(t + \mathrm{\Delta}t)^{\nu}\mathbf{+ (}1 - \Omega\mathbf{)\Gamma}(\mathbf{x}(t)\mathbf{)} \right\rbrack\mathbf{\mathrm{\Delta}}t \qquad \text{(6-64)}$$
-
-
-
-with the iterations stopping when the change in ***x**(t+∆t)* is
-sufficiently small. SWMM uses a tolerance of 0.00328 feet (or 1.0
-millimeter) as a stopping tolerance.
-
-If *Ω* is chosen as 0, then Equation 6-64 becomes equivalent to the
-Euler method and thus:
-
-
-$$\mathbf{x}(t + \mathrm{\Delta}t) = \mathbf{x}(t)\mathbf{+ \Gamma}(\mathbf{x}(t))\mathbf{\mathrm{\Delta}}t \qquad \text{(6-65)}$$
-
-
-
-which can be solved directly without resorting to any iterative scheme.
-Numerical testing has shown that the simpler Euler method works well
-with all types of controls except for vegetative swales. The latter
-requires the iterative trapezoidal method with a *Ω* of 0.5 to produce
-results with acceptable continuity errors.
-
-When using either Equation 6-64 or 6-65 to update the LID unit's
-moisture state at each time step, the following lower and upper physical
-limits on moisture levels must be enforced:
-
-         $$0 \leq d_{1} \leq D_{1}$$                                
-         $$\theta_{WP} \leq \theta_{2} \leq \phi_{2}$$              
-
-         $$0 \leq d_{3} \leq D_{3}$$                                
-
-         $$0 \leq \theta_{4} \leq \phi_{4}$$                        
-
-Finally, Step 4 merges the outflows from the LID unit with those of the
-subcatchment as a whole. Any infiltration into the native soil produced
-by the LID unit is added onto the total infiltration for the
-subcatchment, which is eventually passed onto SWMM's groundwater module.
-Any underdrain flow from the LID unit is kept track of separately, so
-that it can be routed to its designated destination (either another
-subcatchment or some location in the conveyance system). It is not
-included as part of the subcatchment's reported surface runoff. Any
-surface runoff or overflow from the unit $\left( q_{1}A \right)$ is
-added to the subcatchment's total runoff flow rate, except if the unit's
-outflow has been designated for return to the subcatchment's pervious
-area. In the latter case a separate account is kept of the total return
-flow and the LID surface flow is added to it.
-
-As regards to water quality, no explicit changes in constituent
-concentrations are computed as runoff passes through or over an LID
-control. A subcatchment's pollutant washoff concentration is computed as
-described in Section 4.3, as if no LID controls existed. Any surface
-outflow or underdrain flow from each of the subcatchment's LID controls
-is assigned this concentration.
-
-There are two exceptions to this convention. One applies when the LID
-units take up less than the full area of the subcatchment and a
-pollutant has a non-zero rainfall concentration. In that case the
-washoff load from the non-LID portion of the subcatchment (which already
-accounts for any wet deposition) is combined with the direct rainfall
-load from the LID areas to arrive at a modified outflow concentration:
-
-
-$$C_{out} = \frac{\left\lbrack \left( C_{out}Q_{out} \right)_{non - LID} + C_{ppt}iA_{LID} \right\rbrack}{Q_{out,non - LID} + iA_{LID}} \qquad \text{(6-66)}$$
-
-
-
-where
-
-  *Cout*            =  concentration of a pollutant in the subcatchment's
-                         outflow streams after LID treatment (mass/L),
-  *Cout,non-LID*    =  concentration of a pollutant in the subcatchment's
-                         outflow streams prior to LID treatment (mass/L),
-
-  *Qout,non-LID*    =  surface runoff flow rate leaving the subcatchment prior
-                         to any LID treatment (cfs),
-
-  *Cppt*            =  concentration of the pollutant in rainfall (mass/L),
-
-  *i*                 =  rainfall rate (ft/sec),
-
-  *ALID*            =  total surface area of all LID units in the subcatchment
-                         (ft2).
-
-The second exception is when a single LID unit occupies its entire
-subcatchment. In that case there would be no washoff load generated by
-any non-LID surfaces and the pollutant concentration in the unit's
-outflow streams would equal that of its inflow stream. Thus for any
-particular pollutant,
-
-
-$$C_{out} = \frac{\left( \left( \frac{W_{runon}}{28.3} \right) + C_{ppt}iA_{LID} \right)}{Q_{runon} + iA_{LID}} \qquad \text{(6-67)}$$
-
-
-
-where *Qrunon* is the combined runoff flow rate (cfs) of all upstream
-subcatchments routed onto the LID subcatchment, *Wrunon* is the total
-pollutant load (mass/sec) contained in this runoff inflow, and the
-factor 28.3 converts from cubic feet to liters.
-
-Thus although an LID control does not modify the concentration of a
-water quality constituent it sees in its inflow stream, it does reduce
-the total pollutant load passed on to downstream locations in direct
-proportion to the reduction in runoff it produces. When a storm is
-completely captured by an LID unit its effective pollutant removal
-efficiency is 100 percent.
-
-## 6.5 Parameter Estimates
-
-The variety of LID controls modeled by SWMM introduces a significant
-number of design variables and parameters that must be assigned values
-by the user. These include sizing parameters (surface area, layer
-depths, and capture ratio), surface parameters (freeboard depth, outflow
-face width, slope, and roughness), soil parameters (moisture limits and
-hydraulic conductivity), pavement parameters (void ratio and
-permeability), storage parameters (void ratio and native soil
-conductivity), drain parameters (discharge coefficient and exponent,
-roof drain capacity, and drain mat roughness), and clogging parameter.
-Because of the high interest and acceptance of LID, many local and state
-agencies have prepared design manuals that recommend ranges for many key
-parameters. Table 6-1 lists a selection of these manuals, all available
-online. Unless otherwise noted, these manuals served as the source of
-the LID parameter values described in the sub-sections that follow.
-
-### 6.5.1 Bio-Retention Cells and Rain Gardens
-
-Table 6-2 lists ranges of parameter values for bio-retention cells and
-rain gardens, expressed in their typical US units of inches and hours.
-They are internally converted to feet and seconds for use in the
-governing conservation equations.
-
-The soil moisture limits in the table are based on ranges computed for
-sand, loamy sand, and sandy loam textures using the SPAW model (Saxton
-and Rawls, 2006) with organic contents ranging between 2.5 and 8%. The
-model can be used to estimate specific limits from knowledge of a soil's
-sand, clay and organic content. For example, a typical engineered soil
-might consist of 85% sand, 5% clay and 5% organic matter by weight.
-Using the SPAW calculator for this soil produces the characteristics
-listed in Table 6-3. The percolation decay constant *HCO* was estimated
-by using the calculator to compute hydraulic conductivity *K2* for a
-range of moisture contents *θ* and then regressing
-$- ln\left( \frac{K_{2}}{K_{2S}} \right)$ against $\phi_{2} - \theta$ to
-find a best-fit value for *HCO*. The equation used to estimate suction
-head was introduced in Section 4.4 of Volume I.
-
-  Organization      Manual Title           Year  URL
-  Prince Georges    Low-Impact             1999  
-  County Maryland   Development Design:          
-                    An Integrated Design         
-                    Approach                     
-
-  Denver Urban      Urban Storm Drainage   2010  
-  Drainage and      Criteria Manual,             
-  Flood Control     Volume 3 Best                
-  District          Management Practices         
-
-  Toronto and       Low Impact             2010  
-  Region            Development                  
-  Conservation      Stormwater Management        
-  Authority         Planning and Design          
-                    Guide                        
-
-  Washington State  Low Impact             2012  
-  University        Development Technical        
-  Extension         Guidance Manual for          
-                    Puget Sound                  
-
-  District of       Stormwater Management  2013  
-  Columbia          Guidebook                    
-
-  Philadelphia      Stormwater Management  2014  
-  Water Department  Guidance Manual,             
-                    Version 2.1                  
-
-  University of New UNHSC Design           2014  
-  Hampshire         Specifications for           
-  Stormwater Center Porous Asphalt               
-                    Pavement and                 
-                    Infiltration Beds            
-
-  NY State          Stormwater Management  2015  
-  Department of     Design Manual                
-  Environmental                                  
-  Conservation                                   
-
-  : []{#_Toc454288817 .anchor}**Table 6‑1 Design manuals used as sources
-  for LID parameter values**
-
-+-------------------------------------------------+--------------------+
-| **Parameter**                                   | **Range**          |
-+=================================================+:==================:+
-| Maximum Freeboard, inches (*D1*)              | 6 -- 12            |
-+-------------------------------------------------+--------------------+
-| Surface Void Fraction (*φ1*)                  | 0.8 -- 1.0         |
-+-------------------------------------------------+--------------------+
-| Soil Layer Thickness, inches (*D2*)           | 24 -- 48           |
-+-------------------------------------------------+--------------------+
-| Soil Properties:                                |                    |
-+-------------------------------------------------+--------------------+
-| > Porosity (*φ2*)                             | 0.45 -- 0.6        |
-+-------------------------------------------------+--------------------+
-| > Field Capacity (*θFC*)                      | 0.15 -- 0.25       |
-+-------------------------------------------------+--------------------+
-| > Wilting Point *(θWP*)                       | 0.05 -- 0.15       |
-+-------------------------------------------------+--------------------+
-| > Saturated Hydraulic Conductivity, in/hr       | 2.0 -- 5.5         |
-| > (*K2S*)                                     |                    |
-+-------------------------------------------------+--------------------+
-| > Wetting Front Suction Head, inches (*ψ2*)   | 2 -- 4             |
-+-------------------------------------------------+--------------------+
-| > Percolation Decay Constant (*HCO*)            | 30 -- 55           |
-+-------------------------------------------------+--------------------+
-| Storage Layer Thickness, inches (*D3*)        | 6 -- 36            |
-+-------------------------------------------------+--------------------+
-| Storage Void Fraction (*φ3*)                  | 0.2 -- 0.4         |
-+-------------------------------------------------+--------------------+
-| Capture Ratio (*RLID*)                        | 5 -- 15            |
-+-------------------------------------------------+--------------------+
-
-: []{#_Toc454288818 .anchor}**Table 6‑2 Typical ranges for bio-retention
-cell parameters**
-
-  **Soil Property**                                       **Value**
-  Porosity (*φ2*)                                         0.52
-
-  Field Capacity (*θFC*)                                  0.15
-
-  Wilting Point *(θWP*)                                   0.08
-
-  Saturated Hydraulic Conductivity, in/hr (*K2S*)          4.7
-
-  Percolation Decay Constant (*HCO*)                        39.3
-
-  Wetting Front Suction Head, inches (*ψ2 =                1.9
-  3.23(K2S*)-0.328)                             
-
-  : []{#_Toc454288819 .anchor}**Table 6‑3 Soil characteristics for a
-  typical bio-retention cell soil**
-
-### 6.5.2 Green Roofs
-
-Typical ranges of parameter values for Green Roofs are listed in Table
-6-4. These are for extensive green roofs of relatively shallow
-thickness.
-
-+-------------------------------------------------+--------------------+
-| **Parameter**                                   | **Range**          |
-+=================================================+:==================:+
-| Maximum Freeboard, inches (*D1*)              | 0 -- 3             |
-+-------------------------------------------------+--------------------+
-| Surface Void Fraction (*φ1*)                  | 0.8 -- 1.0         |
-+-------------------------------------------------+--------------------+
-| Soil Layer Thickness, inches (*D2*)           | 2 -- 6             |
-+-------------------------------------------------+--------------------+
-| Soil Parameters:                                |                    |
-+-------------------------------------------------+--------------------+
-| > Porosity (*φ2*)                             | 0.45 -- 0.6        |
-+-------------------------------------------------+--------------------+
-| > Field Capacity (*θFC*)                      | 0.3 -- 0.5         |
-+-------------------------------------------------+--------------------+
-| > Wilting Point (*θWP*)                       | 0.05 -- 0.2        |
-+-------------------------------------------------+--------------------+
-| > Plant Available Water (*θFC* - *θWP*)     | 0.25 -- 0.3        |
-+-------------------------------------------------+--------------------+
-| > Saturated Hydraulic Conductivity, in/hr       | 40 -- 140          |
-| > (*K2S*)                                     |                    |
-+-------------------------------------------------+--------------------+
-| > Wetting Front Suction Head, inches (*ψ2*)   | 2 -- 4             |
-+-------------------------------------------------+--------------------+
-| > Percolation Parameter (*HCO*)                 | 30 -- 55           |
-+-------------------------------------------------+--------------------+
-| Drainage Layer Thickness, inches (*D3*)       | 0.5 -- 2           |
-+-------------------------------------------------+--------------------+
-| Drainage Layer Void Fraction (*φ3*)           | 0.2 -- 0.4         |
-+-------------------------------------------------+--------------------+
-| Drainage Layer Roughness (*n3*)               | 0.01 -- 0.03       |
-+-------------------------------------------------+--------------------+
-| Capture Ratio (*RLID*)                        | 0                  |
-+-------------------------------------------------+--------------------+
-
-: []{#_Toc454288820 .anchor}**Table 6‑4 Typical ranges for green roof
-parameters**
-
-The "soil" used as a growth media for green roofs is very different from
-naturally occurring soils. It is an engineered mixture of aggregate
-(such as expanded slate or shale, pumice, or zeolite), sand, and organic
-matter producing a light weight product with high porosity and water
-holding capacity. There is a limited amount of information on the
-standard agronomic properties of such mixtures. The moisture limits and
-conductivity values listed in Table 6-4 are based on a literature review
-provided by Perelli (2014). When compared to the properties for
-bio-retention cell media, the green roof media's hydraulic conductivity
-is much higher. The ranges for suction head and the percolation
-parameter were defaulted to those typical of loam and sandy loam soils.
-The capture ratio for a green roof should be 0 since its only inflow is
-direct rainfall.
-
-### 6.5.3 Infiltration Trenches
-
-Suggested ranges for the parameters associated with infiltration
-trenches are listed in Table 6-5. Because there is no soil layer to slow
-down and retain water in excess of gravity drainage, the trench acts as
-a simple "storage pit" whose change in stored volume over a given time
-step is simply the difference between the captured runoff/rainfall rate
-entering through its surface and the rate of exfiltration leaving
-through its bottom (assuming no underdrain).
-
-  **Parameter**                                           **Range**
-  Maximum Freeboard, inches (*D1*)                       0 -- 12
-
-  Surface Void Fraction (*φ1*)                             1.0
-
-  Storage Layer Thickness, inches (*D3*)                36 -- 144
-
-  Storage Void Fraction (*φ3*)                         0.2 -- 0.4
-
-  Contributing Area, acres                                 1 -- 5
-
-  Capture Ratio (*RLID*)                                 5 -- 20
-
-  : []{#_Toc454288821 .anchor}**Table 6‑5 Typical ranges for
-  infiltration trench parameters**
-
-### 6.5.4 Permeable Pavement
-
-Table 6-6 lists typical parameter ranges for permeable pavement
-installations. The maximum storage height on the surface layer, *D1*,
-now represents the depth of depression storage on the pavement surface.
-Its suggested range is characteristic of impervious surfaces in general
-(ASCE, 1992). The pavement layer properties in the table distinguish
-between continuous concrete or asphalt pavement systems and block paver
-systems.
-
-UNHSC (2009) recommends that the optional sand filter layer be composed
-of coarse sand/fine gravel (bank run gravel). It aids in pollutant
-removal and in slowing down the movement of water through the unit.
-Because of the very high conductivity of permeable pavement, with no
-sand layer present the unit acts in the same manner as an infiltration
-trench whose change in water level over each time step is simply the
-difference between the applied surface inflow rate and the exfiltration
-rate out of the bottom (assuming no underdrain).
-
-+-------------------------------------------------+--------------------+
-| **Parameter**                                   | **Range**          |
-+=================================================+:==================:+
-| Surface Depression Storage, inches (*D1*)     | 0 -- 0.1           |
-+-------------------------------------------------+--------------------+
-| Surface Void Fraction (*φ1*)                  | 1.0                |
-+-------------------------------------------------+--------------------+
-| Pavement Thickness, inches (*D4*)             | 3 -- 8             |
-+-------------------------------------------------+--------------------+
-| Continuous Pavement:                            |                    |
-+-------------------------------------------------+--------------------+
-| > Porosity (*φ4*)                             | 0.15 -- 0.25       |
-+-------------------------------------------------+--------------------+
-| > Permeability, in/hr (*K4*)                  | 28 -- 1750         |
-+-------------------------------------------------+--------------------+
-| > Surface Opening Fraction (*1 -- F4*)        | 0                  |
-+-------------------------------------------------+--------------------+
-| Block Pavers:                                   |                    |
-+-------------------------------------------------+--------------------+
-| > Porosity (*φ4*)                             | 0.1 -- 0.4         |
-+-------------------------------------------------+--------------------+
-| > Permeability, in/hr (*K4*)                  | 5 -- 150           |
-+-------------------------------------------------+--------------------+
-| > Surface Opening Fraction (*1 -- F4*)        | 0.08 -- 0.10       |
-+-------------------------------------------------+--------------------+
-| Sand Filter Layer:                              |                    |
-+-------------------------------------------------+--------------------+
-| > Thickness, inches (*D2*)                    | 8 -- 12            |
-+-------------------------------------------------+--------------------+
-| > Porosity (*φ2*)                             | 0.25 -- 0.35       |
-+-------------------------------------------------+--------------------+
-| > Field Capacity (*θFC*)                      | 0.15 -- 0.25       |
-+-------------------------------------------------+--------------------+
-| > Wilting Point *(θWP*)                       | 0.05 -- 0.10       |
-+-------------------------------------------------+--------------------+
-| > Saturated Hydraulic Conductivity, in/hr       | 5 -- 30            |
-| > (*K2S*)                                     |                    |
-+-------------------------------------------------+--------------------+
-| > Wetting Front Suction Head, inches (*ψ2*)   | 2 -- 4             |
-+-------------------------------------------------+--------------------+
-| > Percolation Parameter (*HCO*)                 | 30 -- 55           |
-+-------------------------------------------------+--------------------+
-| Storage Layer Thickness, inches (*D3*)        | 6 -- 36            |
-+-------------------------------------------------+--------------------+
-| Storage Void Fraction (*φ3*)                  | 0.2 -- 0.4         |
-+-------------------------------------------------+--------------------+
-| Capture Ratio (*RLID*)                        | 0 -- 5             |
-+-------------------------------------------------+--------------------+
-
-: []{#_Toc454288822 .anchor}**Table 6‑6 Typical ranges for permeable
-pavement parameters**
-
-### 6.5.5 Rain Barrels
-
-The Rain Barrel LID control can be used to model both rain barrels and
-cisterns. Rain barrels are typically 50 to 100 gallons in capacity and
-are used at individual home lots to collect roof runoff for possible
-landscape irrigation. Cisterns have much larger capacity, typically from
-250 to 30,000 gallons, used to harvest rainwater from both homes and
-commercial facilities for non-potable indoor use. The parameters
-required for Rain Barrels/Cisterns are the height of the storage vessel
-(*D3*), its volume (from which its surface area *ALID* can be
-derived), its drain parameters, and possibly its drain delay time.
-
-The height and volume of the rain barrel/cistern would be determined by
-commercially available sizes. The drain offset is typically 6 inches
-from the bottom (to trap sediment). Alternatively, one could use an
-offset of 0 and reduce the vessel height accordingly.
-
-The drain flow parameters can be established from the orifice equation
-(Equation 6-38). The flow exponent would be 0.5 and the flow coefficient
-would be 4.8 times the ratio of the drain diameter to the barrel
-diameter squared. The latter quantity has units of ft0.5/sec. To
-convert to the in0.5/hr (or mm0.5/hr) used in SWMM's input data set
-multiply by 12,471 (or 62,768).
-
-As an example, a 2-foot diameter rain barrel with a 3/4 inch spigot
-would have a drain flow coefficient of 4.8 × (0.75 / (2×12))2 × 12,471
-= 58.5 in0.5/hr. This is high enough to drain 4 feet of captured water
-(94 gallons) in less than 15 minutes. A slower release rate for
-landscape irrigation can be achieved by leaving the spigot valve only
-partially open or by using a soaker hose. This action can be simulated
-by using a reduced drain diameter when computing a drain flow
-coefficient.
-
-The drain delay time is the period of time after rainfall ceases until
-the rain barrel is allowed to drain. If the delay time is set to 0 then
-the drain line is considered to be always open. This option might be
-appropriate for modeling rainwater harvesting with larger cisterns.
-Otherwise a choice of delay time will depend on what assumptions one
-makes about homeowner behavior.
-
-### 6.5.6 Rooftop Disconnection
-
-The parameters required for rooftop disconnection are the length of the
-flow path for roof runoff (the inverse of the W1/A1 term in Equation
-6-21), the roof slope, the roughness coefficient for the roof surface,
-the depression storage depth of the roof's surface, and the flow
-capacity of the roof drain system (*q3max*).
-
-The flow path length and its slope are obtained directly from the roof's
-dimensions. Roughness coefficients for roofing material would be similar
-to those for asphalt and clay tile, 0.013 to 0.016. Depression storage
-would range from 0.05 to 0.1 inches with sloped roofs at the low end of
-this range and flat roofs having possibly higher values. The flow
-capacity of the roof's gutters in ft/sec can be estimated from the
-following equations (Beij, 1934):
-
-         $q_{3max} = 0.52\frac{w_{g}^{2.5}}{A_{r}}$ for semicircular gutters                                                    (6-68)
-                                                                                                                              
-
-         $q_{3max} = 7.75\left( \frac{d_{g}}{w_{g}} \right)^{1.6}\left( \frac{w_{g}}{L_{g}} \right)^{0.3}w_{g}^{2.5}/A_{r}$     (6-69)
-         for rectangular gutters                                                                                              
-
-where *wg* is the gutter width in feet, *dg* is the gutter depth in
-feet, *Ar* is the area of the roof serviced by the gutter in square
-feet, and *Lg* is the length of the gutter in feet. To convert
-*q3max* to the in/hr or mm/hr required by the SWMM 5 input format,
-multiply by 43,200 or 1,097,280, respectively.
-
-### 6.5.7 Vegetative Swales
-
-Typical values for the parameters associated with vegetative swales are
-listed in table 6-7. The top width of the swale at full depth (*W1*)
-equals $W_{X} + 2D_{1}S_{X}$. The maximum surface area covered by the
-swale (*ALID*) can be found by multiplying *W1* by the length of the
-swale.
-
-  **Parameter**                                           **Range**
-  Maximum Depth, feet (*D1*)                           0.5 -- 2.0
-
-  Surface Void Fraction (*φ1*)                          0.8 - 1.0
-
-  Bottom Width, feet (*WX*)                            2.0 -- 8.0
-
-  Surface Slope, percent (*S1*)                        0.5 -- 3.0
-
-  Side Slope, horizontal : vertical (*SX*)          2.5 : 1 -- 4 : 1
-
-  Surface Roughness (*n1*)                             0.03 -- 0.2
-
-  Capture Ratio (*RLID*)                                 5 -- 10
-
-  : []{#_Toc454288823 .anchor}**Table 6‑7 Typical ranges for vegetative
-  swale parameters**
-
-### 6.5.8 Underdrains
-
-Underdrains are either recommended or required when the natural soil
-infiltration rate is insufficient to prevent the LID unit from flooding.
-There are three user-supplied parameters that describe underdrain flow:
-a discharge coefficient (*C3D*), a discharge exponent (*η3D*), and a
-drain offset height (*DD3*). While the drain offset is part of the
-cell's physical design, the discharge coefficient and exponent must be
-inferred from the hydraulics of underdrain flow. There are several
-approaches that can be used for this:
-
-1.  Assume the flow rate is limited by the flow capacity of the slotted
-    pipe used as the underdrain.
-
-2.  Assume the flow rate is limited by the rate at which water can enter
-    the slots in the drain pipes.
-
-3.  Assume the flow rate is limited by a flow restriction (such as a
-    throttling valve or cap orifice) on the drain's discharge line.
-
-To use option 1, the full flow capacity of the drain pipe can be
-computed from the Manning equation as follows:
-
-
-$$Q_{full} = \left( \frac{0.464}{n_{pipe}} \right)S_{pipe}^{0.5}D_{pipe}^{2.67} \qquad \text{(6-70)}$$
-
-
-
-where *Qfull* is the flow rate (cfs), *npipe* is the roughness
-coefficient for the pipe's material, *Spipe* is the slope at which the
-pipe is laid (ft/ft), and *Dpipe* is the pipe's diameter (ft). To
-convert this value into a set of underdrain discharge parameters, set
-the drain exponent *η3D* to zero and the drain coefficient *C3D* to
-
-
-$$C_{3D} = \frac{N_{pipe}Q_{full}}{A_{LID}} \qquad \text{(6-71)}$$
-
-
-
-where *Npipe* is the number of drain pipes in the unit and *ALID* is
-the area (ft2) of the unit. Because *η3D* is zero, the units of
-*C3D* are ft/sec. To convert these to the in/hr or mm/hr required by
-the SWMM 5 input format, multiply by 43,200 or 1,097,280, respectively.
-
-As an example, using this method to specify the underdrain parameters
-for two 4-inch diameter plastic drain lines with roughness of 0.01
-placed at a 0.5% slope in a 1,000 sq. ft. bio-retention cell would
-produce a drain coefficient equal to
-
-$C_{3D} = \frac{2\left( \frac{0.464}{0.01} \right){(0.005)}^{0.5}{(\frac{4}{12)}}^{2.67}}{1000} = 0.00035\ \frac{ft}{\sec} = 15\ \frac{in}{hr}$
-.
-
-Once the water height in the storage layer reaches the drain's offset
-height, any inflow from percolation out of the soil layer will
-immediately flow out of the underdrain as long as its flow rate is below
-15 in/hr (as per Equation 6-8) and the storage volume above the offset
-height will never be used.
-
-For option 2, one can assume that the standard orifice equation can
-replace the underdrain flow expression Equation 6-7 so that:
-
-
-$$q_{3} = C_{3D}\left( h_{3} \right)^{0.5} \qquad \text{(6-72)}$$
-
-
-
-where the discharge exponent *η3D* has been set to 0.5 and the
-discharge coefficient now becomes:
-
-
-$$C_{3D} = 0.6\sqrt{2g}\left( \frac{A_{slot}}{A_{LID}} \right) \qquad \text{(6-73)}$$
-
-
-
-with *Aslot* being the total area (ft2) of the slots in the drain
-pipe and *g* the acceleration of gravity (32.2 ft/sec2). Note that the
-units of *C3D* are ft0.5/sec so when used in Equation 6-63 the
-resulting underdrain flux has units of ft/sec (or cfs/ft2). To convert
-*C3D* to in0.5/hr, which are the US units used in the program's
-input, one would multiply by 12,471. To convert to mm0.5/hr for SI
-units, multiply by 62,852.
-
-The ratio of the total slot area to LID area can be determined from the
-dimensions of a slot, the spacing between slots along the drain pipe,
-and the spacing between individual drain pipes:
-
-
-$$\frac{A_{slot}}{A_{LID} =}\frac{N_{pipe}{N_{slot}A}_{slot}}{\left( N_{pipe} + 1 \right)\Delta_{pipe}} \qquad \text{(6-74)}$$
-
-
-
-where
-
-  *Npipe*    =  number of underdrain pipes
-  *Nslot*    =  number of slots per length of pipe (ft-1)
-
-  *Aslot*    =  area of a single slot (ft2)
-
-  *∆pipe*    =  spacing between pipes (ft)
-
-As an example, consider an underdrain system consisting of two slotted
-pipes with inlet area of 1 in2 per foot of pipe spaced 50 ft apart.
-The area ratio used to compute *C3D* would be:
-
-         $$\frac{A_{slot}}{A_{LID} = \frac{2 \times \left( \frac{1}{144} \right)}{(3 \times 50) = 0.0000926}}$$   
-
-
-Using this value in Equation 6-64 to compute *C3D* produces:
-
-         $C_{3D} = 0.6 \times \sqrt{64.4} \times 0.0000926 = 0.00045\ \frac{{ft}^{0.5}}{\sec} = 5.5\ \frac{{in}^{0.5}}{hr}$   
-
-
-Regarding the third option for underdrain parameters, the underdrain
-flow expression can again be replaced by the standard orifice equation,
-this time applied to the discharge point of the underdrain system (such
-as the outlet of a pipe manifold fitted with a cap orifice):
-
-
-$$C_{3D} = 0.6\sqrt{2g}\left( \frac{A_{out}}{A_{LID}} \right) \qquad \text{(6-75)}$$
-
-
-
-where Aout is the cross-sectional area (ft2) of the outlet fitting.
-The same conversion factors described previously would be used to
-convert *C3D*from ft0.5/sec to either in0.5/hr or mm0.5/hr.
-
-Applying this approach to the previously mentioned pair of 4-inch
-diameter drain pipes servicing a 1,000 ft2 cell without any flow
-restriction would result in a *C3D* value of 10.5 in0.5/hr. This is
-much higher than the 5.5 in0.5/hr based on inlet control. Hence the
-latter number would be used for *C3D* under these particular
-circumstances. If the two underdrain pipes were connected by a tee
-fitting to a single 4-inch diameter outflow then the discharge
-coefficient would be 5.25 in0.5/hr and the drain would operate under
-outlet control.
-
-### 6.5.9 Clogging
-
-Because clogging is a long-term process, it would only apply to
-simulations of several months or more duration. SWMM assumes that
-clogging (i.e., reduction of infiltration rates for permeable pavement
-systems and infiltration trenches) proceeds at a constant rate
-proportional to the number of void volumes that the LID unit treats over
-time. The clogging rate constant (or clogging factor *CF*) can be
-computed from the number of years *Tclog* it takes to fractionally
-reduce an infiltration rate to a degree *Fclog*. For example, a CF for
-permeable pavement can be estimated from:
-
-
-$${CF}_{4} = \frac{I_{a}\left( 1 + R_{LID} \right)T_{clog}}{\phi_{4}D_{4}\left( 1 - F_{4} \right)F_{clog}} \qquad \text{(6-76)}$$
-
-
-
-where *Ia* is the annual volume of rainfall in inches, *RLID* is the
-unit's capture ratio, *φ4* is the porosity of the pavement layer,
-*D4* is the thickness of the pavement layer, and *F4* is the
-fraction of the surface area covered by impermeable pavers. A similar
-expression would apply to the CF of an infiltration trench's storage
-layer using the layer's porosity and thickness in the expression with
-*F4* set to 0.
-
-For permeable pavement, the rate at which clogging proceeds depends on
-many factors, such as the type of permeable pavement system employed,
-the pore sizes in the pavement or in the fill material between paver
-blocks, the amount and size of the particulate matter in the runoff it
-treats, and the amount of vehicular traffic passing over it. Perhaps the
-most important factor for both permeable pavement and infiltration
-trenches is the capture ratio since that will affect how much solids
-loading the unit receives over a given span of years. That is, with all
-other factors being equal, an LID unit with a higher capture ratio will
-clog in less time than one with a lower capture ratio.
-
-Kumar et al. (2016) measured reductions in infiltration rates of 71 to
-85 % after 3 years for a permeable pavement parking lot. Pitt and
-Voorhees (2000) quote a possible 50 % drop in permeable pavement
-permeability in 3 years. In simulated loading conditions, Yong et al.
-(2013) found that permeable asphalt pavement became completely clogged
-in 8 to 12 years. Bergman et al. (2011) found a 74 % drop in
-infiltration rate over 15 years for a pair of infiltration trenches in
-Copenhagen.
-
-## 6.6 Numerical Example
-
-A numerical example will help demonstrate how SWMM is able to model the
-dynamic behavior that LID controls exhibit during a rainfall event.
-Consider a bio-retention cell that captures all of the runoff from a
-parking lot. It consists of a 24 inch soil layer above a 12 inch gravel
-reservoir and has a 6-inch high berm surrounding it. The growth medium
-in the soil layer is the same 85% sand, 5% clay and 5% organic matter
-blend whose properties were listed previously in Table 6-3 (porosity of
-0.52, field capacity of 0.15, wilting point of 0.08, saturated hydraulic
-conductivity of 4.7 in/hr, suction head of 1.9 inches, and percolation
-decay constant of 39.3). The void fraction of the gravel storage layer
-is 0.4 and the exfiltration rate out of this layer into the native soil
-is 0.4 in/hr. Initially it is assumed that the bio-retention cell is not
-equipped with an underdrain.
-
-The parking lot is completely impervious and is modeled so that all
-rainfall becomes immediate runoff. The bio-retention cell takes up 5 %
-of the total catchment area. Thus its Capture Ratio is (1 -- 0.05) /
-0.05 = 19. The total storage volume contained in the bio-retention cell
-is 6 inches of above ground surface storage plus 24 × (0.52 -- 0.08)
-inches of soil pore volume plus 12 × 0.4 inches of gravel volume for a
-total of 21.36 inches. Considering the unit's capture ratio of 19 plus
-the area of the unit itself translates into a capacity of 21.36 /
-(19 + 1) = 1.07 inches for the entire catchment area. Thus it should be
-capable of completely capturing and infiltrating all storms at or below
-this depth. This is just an estimate since it ignores the effect that
-the 0.4 in/hr exfiltration rate out of the bottom of the unit has in
-making more storage available as an event unfolds.
-
-The parking lot and bio-retention cell were subjected to the 1 inch
-storm event depicted in Figure 6-7. This is an actual event recorded at
-a rain gage in Philadelphia, PA during the month of May. The potential
-evaporation rate for that time of year was 0.18 in/day. SWMM 5 was used
-to compute the hydrologic response of the parking lot and its LID
-control to this storm event over a 48-hour period starting with
-completely dry conditions. Results for the bio-retention cell are shown
-in Figures 6-8 and 6-9. Figure 6-8 shows the variation over time of the
-surface inflow, soil layer percolation, and storage layer exfiltration.
-Figure 6-9 shows how the moisture level within each layer, as a
-percentage of its full storage capacity, varies with time.
-
-![[]{#_Toc454288783 .anchor}**Figure 6‑7 Storm event used for the LID
-example**](./media/media/image38.png){width="6.462293307086614in"
-height="3.76in"}
-
-![[]{#_Toc454288784 .anchor}**Figure 6‑8 Flux rates through the
-bio-retention cell with no
-underdrain**](./media/media/image39.png){width="6.328590332458442in"
-height="3.76in"}
-
-![[]{#_Toc454288785 .anchor}**Figure 6‑9 Moisture levels in the
-bio-retention cell with no
-underdrain**](./media/media/image40.png){width="6.34721675415573in"
-height="4.181228127734033in"}
-
-The bio-retention cell is able to completely capture this 1-inch storm.
-Although both the storage and soil zones become saturated and some
-surface ponding occurs (up to a maximum 0.25 × 6 = 1.5 inches), no
-runoff is produced. The dynamics of flow through the unit can be broken
-up into five distinct phases:
-
-1.  Wetting Phase:
-
-For the first 5 hours of the storm event the soil fills with water up to
-its field capacity of 0.15 (29% of saturation). During this time the
-soil layer accepts all inflow to the unit without sending any outflow to
-the storage layer.
-
-2.  Filling Phase:
-
-During the next 6 hours as the unit continues to receive inflow, water
-begins to percolate out of the soil layer and into the storage layer at
-an increasing rate. For the first 3 hours of this period, while the
-percolation rate is below the bottom exfiltration rate, all of this
-water leaves the unit and keeps the storage layer dry. Eventually the
-soil moisture content becomes high enough so that the percolation rate
-exceeds the exfiltration rate and the storage layer fills in a matter of
-3 hours. During this entire phase the unit is still able to accept all
-of the inflow as shown by the absence of any ponded surface water.
-
-3.  Saturation Phase:
-
-After approximately 11 hours both the soil and storage layers have
-become full. At this point even though the soil conductivity has risen
-above 4 in/hr, it cannot transmit water any faster than the full storage
-layer can exfiltrate it at only 0.4 in/hr. During the next 4 hours as
-the unit continues to receive inflow while full, the excess ponds atop
-the surface.
-
-4.  Draining Phase:
-
-Once inflow to the unit ceases at about 15 hours it begins to drain and
-water levels recede from the top on down. Surface ponding is gone by
-16.5 hours. Then the soil begins to drain down at a rate still limited
-by the slower bottom exfiltration rate since the storage layer remains
-full. At about hour 21 the soil percolation rate becomes less than the
-exfiltration rate and the storage layer begins to empty. It then takes
-another 15 hours for the storage layer to drain down completely.
-
-5.  Drying Phase:
-
-After the storage layer has completely drained, water continues to drain
-out of the soil layer at a rate lower than the bottom exfiltration rate,
-so all of it infiltrates into the native soil. This continues until the
-soil's field capacity moisture is reached. After that, the soil will
-continue to dry by evapotranspiration until its wilting point is
-reached.
-
-Now consider what happens when an underdrain is added to the
-bio-retention cell. The drain is placed at the top of the storage layer
-so that the layer's full storage capacity can be utilized. It is assumed
-to be over-designed so its discharge coefficient is assigned a very
-large value. The resulting time history of moisture content throughout
-the cell with the underdrain is shown in Figure 6-10. The drain has
-prevented any inflow from ponding on top of the unit. As shown in Figure
-6-11, the drain carries flow only during the period of time that the
-storage layer is full. Because it is oversized, it can accept the full
-amount of water remaining from soil percolation after the bottom
-exfiltration is accounted for. Compare this with the case of no drain in
-Figure 6-8, where the soil percolation rate is limited by the
-exfiltration rate during the time that the storage layer is full.
-
-The total volume of flow carried away by the underdrain is about 14 % of
-the total storm volume. If this flow is sent to a storm sewer which is
-typically the case, then the bio-retention cell can no longer be said to
-have fully captured and eliminated runoff from this 1-inch storm.
-
-![[]{#_Toc454288786 .anchor}**Figure 6‑10 Moisture levels in the
-bio-retention cell with
-underdrain**](./media/media/image41.png){width="6.264479440069992in"
-height="3.765628827646544in"}
-
-![[]{#_Toc454288787 .anchor}**Figure 6‑11 Flux rates through the
-bio-retention cell with
-underdrain**](./media/media/image42.png){width="6.254458661417323in"
-height="3.76in"}
-
-# References
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-Adams, B.J. and Papa, F., *Urban Stormwater Management Planning, with
-Analytical Probabilistic Models*, John Wiley and Sons, New York, 2000.
-
-Ascher, U.M. and Petzold, L.R., *Computer Methods for Ordinary
-Differential Equations and Differential-Algebraic Equations*, SIAM,
-Philadelphia, 1998.
-
-Avellaneda, P., Ballestero, T.P., Roseen, R.M., and Houle, J.J., "On
-Parameter Estimation of Urban Storm-Water Runoff Model", *Journal of
-Environmental Engineering*, Vol. 135, No. 8, August 2009, pp. 595-608.
-
-Alley, W.M., "Estimation of impervious area washoff parameters", *Water
-Resources Research*, Vol. 17, No. 4, 1981, pp. 1161--1166.
-
-Ambrose, R.B. Jr., Wool, T.A., Connolly, J.P, and Schanz, R.W., \"WASP4,
-A Hydrodynamic and Water Quality Model - Model Theory, User\'s Manual,
-and Programmer\'s Guide\", EPA/600/3-87/039, U.S. Environmental
-Protection Agency, Athens, GA 1988.
-
-American Public Works Association, "Water Pollution Aspects of Urban
-Runoff," Federal Water Pollution Control Administration, Contract
-WP-20-15, Washington, DC, 1969.
-
-American Society of Civil Engineers (ASCE) and Water Pollution Control
-Federation (WPCF), *Design and Construction of Sanitary and Storm
-Sewers*, Water Pollution Control Federation, Washington, DC, 1969.
-
-American Society of Civil Engineers (ASCE), "Guide for Best Management
-Practice (BMP) Selection in Urban Developed Areas", Urban Water
-Infrastructure Management Committee's Task Committee for Evaluating Best
-Management Practices, ASCE, Reston, VA, 2001.
-
-American Society of Civil Engineers (ASCE), "Design and Construction of
-Urban Stormwater Management Systems." American Society of Civil
-Engineers, New York, NY, 1992.
-
-Ammon, D.C., "Urban Stormwater Pollutant Buildup and Washoff
-Relationships," Master of Engineering Thesis, Dept. of Environmental
-Engineering Sciences, University of Florida, Gainesville, FL, 1979.
-
-Amy, G., Pitt, R., Singh, R., Bradford, W.L. and LaGraff, M.B., \"Water
-Quality Management Planning for Urban Runoff," EPA-440/9-75-004 (NTIS
-PB-241689), U.S. Environmental Protection Agency, Washington, DC,
-December 1974.
-
-Atchison, D. and Severson, L., "RECARGA User's Manual, Version 2.3",
-University of Wisconsin -- Madison, Civil & Environmental Engineering
-Department, October, 2004.
-
-AQUA TERRA Consultants, "Patuxent River Basin Watershed Model", U.S.
-Geological Survey, Towson, MD, 1994.
-
-AVCO Economic Systems Corporation, "Storm Water Pollution from Urban
-Land Activity," EPA 111034FKL07/70 (NTIS PB-19528l), Environmental
-Protection Agency, Washington, DC, July 1970.
-
-Baffaut, C. and Delleur, J.W., "Calibration of SWMM Runoff Quality Model
-with Expert System", *Journal of Water Resources Planning and
-Management*, Vol. 116, No. 2, March/April, 1990, pp. 247-261.
-
-Bear, J. and Cheng, A. H.-D., *Modeling Groundwater Flow and Contaminant
-Transport*, Springer, Dordrecht, 2010.
-
-Behera, P.K., Adams, B.J, and Li, J.Y., "Runoff quality analysis of
-urban catchments with analytical probabilistic models", *Journal of
-Water Resources Planning and Management,* Vol. 132, No. 1, 2006, pp
-4--14.
-
-Beij, K.H., "Flow in Roof Gutters", Research Paper RP644, *Bureau of
-Standards Journal of Research*, Vol. 12, February 1934, pp. 193-213.
-
-Bergman, M., Hedegaard, M.R., Petersen, M.F., Binning, P., Mark, O., and
-Mikkelsen, P.S., "Evaluation of two stormwater infiltration trenches in
-central Copenhagen after 15 years of operation", *Water Science and
-Technology*, Vol. 63, No. 10, 2011, pp. 2279-2286.
-
-Betson, R.P., "Bulk Precipitation and Streamflow Quality Relationships
-in an Urban Area," *Water Resources Research*, Vol. 14, No. 6, December
-1978, pp. 1165-1169.
-
-Bicknell, B.R., Imhoff, J.C., Kittle, J.L., Jr., Donigian, A.S., Jr. and
-R.C. Johanson, *Hydrologic Simulation Program -- Fortran: User's Manual
-for Release 11*, U.S. Environmental Protection Agency, Office of
-Research and Development, Athens, GA, 1997.
-
-Brezonik, P.L., "Nutrients and Other Biologically Active Substances in
-Atmo­spheric Precipitation," Proceedings Symposium on Atmospheric
-Contribution to the Chemistry of Lake Waters, International Association
-Great Lakes Research, September 1975, pp. 166-186.
-
-Burton, G.A. and Pitt, R.E., *Stormwater Effects Handbook*. Lewis
-Publishers, CRC Press, Boca Raton, FL, 2002.
-
-Center for Watershed Protection (CWP), *Impacts of Impervious Cover on
-Aquatic Systems*, Watershed Protection Research Monograph No.1, Center
-for Watershed Protection, Ellicott City, MD, March 2003.
-
-Davis, A.P. and McCuen, R.H., *Stormwater Management for Smart Growth*,
-Springer, 2005.
-
-Di Toro, D.M., "Probability Model of Stream Quality Due to Runoff*,"
-Journal of Environmental Engineering, ASCE*, Vol. 110, No. 3, June 1984,
-pp. 607-628.
-
-Donigian, A.S., Jr. and W.C. Huber, *Modeling of Nonpoint Source Water
-Quality in Urban and Non‑Urban Areas*, EPA/600/3‑91/039 (NTIS
-PB92-109115), U.S. Environmental Protec­tion Agency, Athens, GA, 1991.
-
-Donigian, A.S., Jr., W.C. Huber and T.O. Barnwell, Jr., "Modeling of
-Nonpoint Source Water Quality in Urban and Nonurban Areas," Chapter 7 in
-*Nonpoint Pollution and Urban Stormwater Management*, V. Novotny, ed.,
-Technomic Publishing Co., Inc., Lancaster, PA, 1995, pp. 293-345.
-
-Driscoll, E.D., in "Benefit Analysis for Combined Sewer Overflow
-Control," Seminar Publication, EPA-652/4-79-013, U.S. Environmental
-Protection Agency, Cin­cinnati, OH, April 1979.
-
-Driscoll, E.D., "Lognormality of Point and Non-Point Source Pollutant
-Concentrations," in *Proc. Stormwater and Water Quality Users Group
-Meeting*, T.O. Barnwell and W.C. Huber, eds., Orlando, FL,
-EPA/600/9-86/023 (NTIS PB87-117438/AS), Environmental Protection Agency,
-Athens, GA, September 1986.
-
-Driscoll, E.D. and Assoc., "Combined Sewer Overflow Analysis Handbook
-for Use in 201 Facility Planning," Report to Environmental Protection
-Agency, Facility Requirements Division, Washington, DC, July 1981.
-
-Dussaillant, A.R., Wu, C.H., and Potter, K.W., "Richards Equation Model
-of a Rain Garden", *Journal of Hydrologic Engineering*, Vol. 9, No. 3,
-May, 2004, pp. 219-225.
-
-Ewing, R.E. and Wang, H., "A summary of numerical methods for
-time-dependent advection-dominated partial differential equations",
-*Journal of Computational and Applied Mathematics*, Vol. 128., 2001, pp.
-423-445.
-
-Ferguson, B., *Porous Pavements*, CRC Press, Boca Raton, 2005.
-
-Fletcher, T.D., Shuster, W., Hunt, W.F., Ashley, R., Butler, D., Arthur,
-S., Trowsdale, S., Barraud, S., Semadeni-Davies, A., Bertrand-Krajewski,
-J-L., Mikkelsen, P.S., Rivard, G., Uhl, M., Dagenais, D., and Viklander,
-M., "SUDS, LID, BMPs, WSUD and more -- The evolution and application of
-terminology surrounding urban drainage", *Urban Water Journal*, Vol. 12,
-Issue 7, 2015, pp. 525-542.
-
-Graf, W.H., *Hydraulics of Sediment Transport*, McGraw-Hill, New York,
-1971.
-
-Haan, C.T., Barfield, B.J. and J.C. Hayes, *Design Hydrology and
-Sedimentology for Small Catchments*, Academic Press, New York, 1994.
-
-Haseltine, T.R., "Addition of Garbage to Sewage," *Water and Sewage
-Works*, 1950.
-
-He, Z., and Davis, A.P., "Process Modeling of Storm-Water Flow in a
-Bioretention Cell", Journal of Irrigation and Drainage Engineering, Vol.
-137, No. 3, March, 2011, pp. 121-131.
-
-Heaney, J.P., Huber, W.C., Sheikhv, H., Medina, M.A., Doyle, J.R.,
-Peltz, W.A., and Darling, J.E., "Urban Stormwater Management Modeling
-and Decision Making", EPA-670/2-75-022 (NTIS PB-242290), U.S.
-Environmental Protection Agency, Cincinnati, OH, 1975.
-
-Heaney, J.P., Huber, W.C., Medina, M.A., Jr., Murphy, M.P., Nix, S.J.
-and Haasan, S.M., "Nationwide Evaluation of Combined Sewer Overflows and
-Urban Stormwater Discharges ­ Vol. II: Cost Assessment and Impacts,"
-EPA-600/2-77-064b (NTIS PB-266005), U.S. Environmental Protection
-Agency, Cincinnati, OH, March 1977.
-
-Hendry, C.D. and Brezonik, P.L., "Chemistry of Precipitation at
-Gainesville, Florida," *Environmental Science and Technology*, Vol. 14,
-No. 7, July 1980, pp. 843-849.
-
-Hillel, D., *Introduction to Soil Physics*, Academic Press, Orlando, FL,
-1982.
-
-Huber, W.C., "Deterministic Modeling of Urban Runoff Quality," *Urban
-Runoff Pollution*, H. Torno, J. Marsalek and M. Desbordes, eds., NATO
-ASI Series, Series G: Ecological Sciences, Vol. 10, Springer-Verlag, New
-York, 1985, pp. 166-242.
-
-Huber, W.C., "Modeling Urban Runoff Quality: State-of-the-Art," *Urban
-Runoff Quality-Impact and Quality Enhancement Technology*, B. Urbonas
-and L.A. Roes­ner, eds., Proceedings of an Engineering Foundation
-Conference, American Soci­ety of Civil Engineers, New York, June 1986,
-pp. 34-48.
-
-Huber, W.C., J.P. Heaney, M.A. Medina, W.A. Peltz, H. Sheikh, and G.F.
-Smith, "Storm Water Management Model User's Manual ­ Version II,"
-EPA-670/2-75-01· (NTIS PB-257809), U.S. Environmental Protection Agency,
-Cincinnati, OH, March 1975.
-
-Huber, W.C., Heaney, J.P., Aggidis, D.A., Dickinson, R.E. and Wallace,
-R.W., "Urban Rainfall-Runoff-Quality Data Base," EPA-600/2-81-238¸ (NTIS
-PB82-221094), Environmental Protection Agency, Cincinnati, OH, October
-1981a.
-
-Huber, W.C., J.P. Heaney, S.J. Nix, R.E. Dickinson, and D.J. Polmann,
-"Storm Water Management Model User's Manual, Version III,"
-EPA-600/2-84-109a (NTIS PB84-198423), U.S. Environmental Protection
-Agency, Cincinnati, OH, November 1981b.
-
-Huber, W.C., and R.E. Dickinson, *Storm Water Management Model, Version
-4, User\'s Manual,* EPA/600/3-88/001a (NTIS PB88-236641/AS), U.S.
-Environmental Protection Agency, Athens, GA, 1988.
-
-Huber, W.C., L. Cannon, and M. Stouder, "BMP Modeling Concepts and
-Simulation", EPA/600/R-06/033, U.S. Environmental Protection Agency,
-Cincinnati, OH, July 2006.
-
-Huber, W.C. and L. Roesner, \"The History and Evolution of the EPA
-SWMM\" in Fifty Years of Watershed Modeling - Past, Present And Future,
-A.S. Donigian and R. Field, eds., ECI Symposium Series, Volume P20,
-2013. 
-
-Hunt, W.F., A.R. Jarrett, J.T. Smith, and L.J. Sharkey, "Evaluating
-Bioretention Hydrology and Nutrient Removal at Three Field Sites in
-North Carolina", *ASCE Journal of Irrigation and Drainage Engineering*,
-Vol. 132, No.6, 2006, pp. 600-608.
-
-Hydroscience, Inc., "A Statistical Method for the Assessment of Urban
-Storm­water," EPA-440/3-79-023, U.S. Environmental Protection Agency,
-Washington, DC, May 1979.
-
-James, W. and Boregowda, S., "Continuous Mass-Balance of Pollutant
-Build-up Processes," *Urban Runoff Pollution*, H.C. Torno, J. Marsalek
-and M. Desbordes, eds., NATO ASI Series, Series G: Ecological Sciences,
-Vol. 10, Springer-Verlag, New York, 1985, pp. 243-271.
-
-Jewell, T.K., Nunno, T.J. and Adrian, D.D., "Methodology for Calibrating
-Stormwater Models," *Journal of the Environmental Engineering Division,
-ASCE*, Vol. 104, No. EE5, June 1978, pp. 485-501.
-
-Jewell, T.K., Adrian, D.D, and DiGiano, F.A., "Urban Stormwater
-Pollutant Loadings," Water Resources Research Center Publication No.
-113, University of Massachusetts, Amherst, MA, May 1980.
-
-Johansen, N.B., Linde-Jensen, J.J. and P. Harremoes, "Computing Combined
-System Overflow Based on Historical Rain Series," Proc. Third
-International Conference on Urban Storm Drainage, Chalmers University,
-Goteborg, Sweden, June 1984, Vol. 3, pp. 909-918.
-
-Kluesener, J.W. and Lee, G.F., "Nutrient Loading from a Separate Storm
-Sewer in Madison, Wisconsin," *Journal Water Pollution Control
-Federation*, Vol. 46, No. 5, May 1974, pp. 920-936.
-
-Kadlec, R.H. and Knight, R.L., *Treatment Wetlands*, Lewis Publishers,
-Boca Raton, F, 1996.
-
-Kumar, K., Kozak, J., Hundal, L., Cox, A., Zhang, H., and Granato, T.,
-\"In-situ infiltration performance of different permeable pavements in a
-employee used parking lot - A four-year study\", Journal of
-Environmental Management 167:8-14, 2016.
-
-Lager, J.A., Smith, W.G., Lynard, W.G., Finn, R.F. and Finnemore, E.J.,
-"Urban Stormwater Management and Technology: Update and User's Guide,"
-EPA-600/8-77-014 (NTIS PB-275264), U.S. Environmental Protection Agency,
-Cincinnati, OH, Septem­ber 1977.
-
-Lee, J., Borst, M., Brown, R., Rossman, L., and Simon, M., "Modeling the
-Hydrologic Processes of a Permeable Pavement System", Journal of
-Hydrologic Engineering, Vol. 20, No. 5, 2015.
-
-Li, H. and Davis, A.P., "Water Quality Improvement through Reductions of
-Pollutant Loads using Bioretention", *Journal of Environmental
-Engineering*, Vol.135, No.8, 2009, pp. 567-576.
-
-Lucas, W. C., "Design of integrated bioinfiltration-detention urban
-retrofits with design storm and continuous simulation methods", *Journal
-of Hydrologic Engineering*, Vol. 15, No. 6, 2010, pp. 486-498.
-
-Manning, M.J., Sullivan, R.H. and Kipp, T.M., "Nationwide Evaluation of
-Com­bined Sewer Overflows and Urban Stormwater Discharges ­ Vol. III:
-Character­ization of Discharges," EPA-600/2-77-064c (NTIS PB-272107),
-U.S. Environmental Protection Agency, Cincinnati, OH, August 1977.
-
-Martin, J.L, and McCutcheon, S.C., *Hydrodynamics and Transport for
-Water Quality Modeling*, Lewis Publishers, Boca Raton, FL, 1999.
-
-Maryland Department of the Environment (MDE), *Maryland Stormwater
-Design Manual, Chapter 3 -- Performance Criteria for Urban BMP Design*,
-2009.
-
-Mattraw, H.C., Jr., and Sherwood, C.B., "Quality of Storm Water Runoff
-From a Residential Area, Broward County, Florida," *Journal Research
-U.S. Geological Survey*, Vol. 5, No. 6, November-December 1977, pp.
-823-834.
-
-McElroy, A.D., Chiu, S.Y., Nebgen, J.W., Aleti, A. and Bennett, F.W.,
-"Loading Functions for Assessment of Water Pollution from Non-point
-Sources, EPA-600/2-76-151 (NTIS PB-253325), U.S. Environmental
-Protection Agency, Washington, DC, May 1976.
-
-Medina, M.A., Huber, W.C., and Heaney, J.P., "Modeling Stormwater
-Storage/Treatment Transients: Theory", *Journal of the Environmental
-Engineering Division*, ASCE, Vol. 107, No. EE4, August 1981, pp.
-787-797.
-
-Metcalf & Eddy, Inc., *Wastewater Engineering: Treatment and Reuse*,
-Revised by G. Tchobanoglous, F.L. Burton, and H.D. Stensel,
-Mc-Graw-Hill, New York, Fourth Edition, 2003.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume I ­ Final Report,"
-EPA Report 11024 DOC 07/71 (NTIS PB-203289), U.S. Environmental
-Protection Agency, Washington, DC, July 1971a.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume II ­ Verification
-and Testing," EPA Report 11024 DOC 08/71 (NTIS PB-203290), U.S.
-Environmental Protection Agency, Washington, DC, August 1971b.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume III ­ User's
-Manual," EPA-11024 DOC 09/71 (NTIS PB-203291), U.S. Environmental
-Protection Agency, Washington, DC, September 1971c.
-
-Metcalf and Eddy, Inc., University of Florida, and Water Resources
-Engineers, Inc., "Storm Water Management Model, Volume IV ­ Program
-Listing," EPA Report 11024 DOC 10/71 (NTIS PB-203292), U.S.
-Environmental Protection Agency, Washington, DC, October 1971d.
-
-Miller, R.A., Mattraw, H.C., Jr. and Jennings, M.E., "Statistical
-Modeling of Urban Storm Water Processes, Broward County, Florida,"
-Proceedings Interna­tional Symposium on Urban Storm Water Management,
-University of Kentucky, Lexington, July 1978, pp. 269-273.
-
-Mills, W.B., Porcella, D.B., Ungs, M.J., Gherini, S.A., Summers, K.V.,
-Mok, L., Rupp, G.L., Bowie, G.L. and D.A. Haith, *Water Quality
-Assessment: A Screening Procedure for Toxic and Conventional Pollutants
-in Surface and Ground Water (Revised 1985)*, Parts 1 and 2,
-EPA/600/6-85/002a (NTIS PB86-122496) and EPA/600/6-85/002b (NTIS
-PB86-122504), Environmental Protection Agency, Athens, GA, September
-1985.
-
-Nakamura, E., "Factors Affecting Stormwater Quality Decay Coefficient,"
-Pro­ceedings of the Third International Conference on Urban Storm
-Drainage, Chal­mers University, Goteborg, Sweden, June 1984a, Vol. 3, pp.
-979-988.
-
-Nakamura, E., "Factors Affecting the Removal Rate of Street Surface
-Contami­nants by Overland Flow," *Journal of Research*, Public Works
-Research Institute, Ministry of Construction, Japan, November 1984b.
-
-National Research Council (NRC), *Clean Coastal Waters, Understanding
-and Reducing the Effects of Nutrient Pollution*, National Academy Press,
-Washington, DC, 2000.
-
-Novotny, V., ed., *Nonpoint Pollution and Urban Stormwater Management*,
-Water Quality Management Library Volume 9, Technomic Publishing Co.,
-Inc., Lancaster, PA, 1995.
-
-Novotny, V. and Kincaid, B.W., "Acidity of Urban Precipitation and its
-Buffer­ing During Overland Flow," in *Urban Stormwater Quality,
-Management and Plan­ning*, B.C. Yen, ed., Proceedings of the Second
-International Conference on Urban Storm Drainage, Urbana, IL, Water
-Resources Publications, Littleton, CO, June 1981, pp. 1-9.
-
-Novotny, V. and H. Olem, *Water Quality: Prevention, Identification, and
-Management of Diffuse Pollution*, van Nostrand Reinhold, New York, 1994.
-
-Perelli, G.A., \"Characterization of the Green Roof Growth Media\",
-University of Western Ontario, Electronic Thesis and Dissertation
-Repository, Paper 2205, 2014.
-
-Philadelphia Water Department, *Stormwater Management Guidance Manual,
-Version 2.1*, City of Philadelphia, February, 2014.
-
-Pitt, R., "Demonstration of Non-point Pollution Abatement Through
-Improved Street Cleaning Practices," EPA-600/279-161 (NTIS PB80-108988),
-U.S. Environ­mental Protection Agency, Cincinnati, OH, August 1979.
-
-Pitt, R., "Characterizing and Controlling Urban Runoff through Street
-and Sewerage Cleaning", EPA/600/2-85/038, (NTIS PB85-186500), U.S.
-Environmental Protection Agency, Cincinnati, OH, April 1985.
-
-Pitt, R. and Amy, G., "Toxic Materials Analysis of Street Surface
-Contami­nants," EPA-R2-73-283 (NTIS PB-224677), U.S. Environmental
-Protection Agency, Wash­ington, DC, August 1973.
-
-Pitt, R. and Voorhees, J., *The Source Loading and Management Model
-(SLAMM): A Water Quality Management Planning Model for Urban Stormwater
-Runoff*,
-,
-2000.
-
-Prince Georges County (PGC), "Low-Impact Development Design: An
-Integrated Design Approach" Prince George\'s County, Maryland,
-Department of Environmental Resources, June 1999a.
-
-Prince Georges County (PGC), "Low-Impact Development Hydrologic
-Analysis" Prince George\'s County, Maryland, Department of Environmental
-Resources, July 1999b.
-
-Randall,C.W., Grizzard, T.J., Helsel, D.R. and Griffin, D.M., Jr.,
-"Comparison of Pollutant Mass Loads in Precipitation and Runoff in Urban
-Areas," in *Urban Stormwater Quality, Management and Planning*, B.C.
-Yen, ed., Proceedings of the Second International Conference on Urban
-Storm Drainage, Urbana, IL, Water Resources Publications, Littleton, CO,
-June 1981, pp. 29-38.
-
-Roesner, L.A., "Quality of Urban Runoff" in *Urban Stormwater
-Hydrology*, edited by D.F. Kibler, American Geophysical Union,
-Washington DC, 1982.
-
-Roesner, L.A., Aldrich, J.A. and R.E. Dickinson, *Storm Water Management
-Model, Version 4, User\'s Manual: Extran Addendum,* EPA/600/3-88/001b
-(NTIS PB88-236658/AS), Environmental Protection Agency, Athens, GA,
-1988.
-
-Rossman, L.A., "Modeling Low Impact Development Alternatives with SWMM"
-in *Dynamic Modeling of Urban Systems, Monograph 18* (W. James, editor),
-CHI, Guelph, Ontario, 2010.
-
-Sartor, J.D. and Boyd, G.B., "Water Pollution Aspects of Street Surface
-Con­taminants," EPA-R2-72-081 (NTIS PB-214408), U.S. Environmental
-Protection Agency, Washington, DC, November 1972.
-
-Saxton, K.E. and Rawls, W.J., "Soil Water Characteristic Estimates by
-Texture and Organic Matter for Hydrologic Solutions", Soil Science
-American Journal, 70:1569-1578, 2006.
-
-Shaheen, D.G., "Contributions of Urban Roadway Usage to Water
-Pollution," EPA-600/2-75-004 (NTIS PB-245854), U.S. Environmental
-Protection Agency, Washington, DC, April l975.
-
-Simons, D.B. and Senturk, F., *Sediment Transport Technology*, Water
-Resources Publications, Ft. Collins, CO, 1977.
-
-Singh, V.P., ed., *Computer Models of Watershed Hydrology*, Water
-Resources Publications, Highlands Ranch, CO, 1995.
-
-Siriwardene, N. R., Deletic, A., and Fletcher, T. D. "Clogging of
-stormwater gravel infiltration systems and filters: Insights from a
-laboratory study." *Water Research*, Vol. 41, No. 7, 2007, pp.
-1433--1440.
-
-Smolenyak, K.J., "Urban Wet-Weather Pollutant Loadings," M.E. Thesis,
-Dept. of Environmental Engineering Sciences, University of Florida,
-Gainesville, 1979.
-
-Sonnen, M.B., "Urban Runoff Quality: Information Needs," *Journal of the
-Tech­nical Councils, ASCE*, Vol. 106, No. TC1, August 1980, pp. 29-40.
-
-Sutherland, R.C. and Jelen, S.J., "Contrary to Conventional Wisdom,
-Street Sweeping Can Be an Effective BMP," Chapter 9 in *Advances in
-Modeling the Management of Stormwater Impacts*, W. James, ed., Proc. of
-the Stormwater and Water Quality Modeling Conference, Toronto, February
-1996, Computational Hydraulics International, Guelph, ON, 1997, pp.
-179-190.
-
-Strecker, E.W., Quigley, M.M., Urbonas, B.R., Jones, J.E. and Clary,
-J.K., "Determining Urban Storm Water BMP Effectiveness," *Journal of
-Water Resources Planning and Management*, 127(3), 2001, pp.144-149.
-
-Tchobanoglous, G. and Burton, F., *Wastewater Engineering, Treatment,
-Disposal, Reuse*, Third Edition, Metcalf & Eddy, Inc., Boston, MA, 1991.
-
-Tetra Tech, Inc., "Stormwater Best Management Practices (BMP)
-Performance Analysis", Report prepared for U.S. Environmental Protection
-Agency -- Region 1, Fairfax, VA, March, 2010.
-
-Tucker, L.S., "Sewage Flow Variations in Individual Homes," ASCE
-Combined Sewer Separation Project Tech. Memo No. 2, ASCE, New York,
-1967, p. 8.
-
-U.S. Environmental Protection Agency (US EPA), "Results of the
-Nationwide Urban Runoff Pro­gram, Volume I Final Report," NTIS
-PB84-185552, Environmental Protection Agency, Washington, DC, December
-1983.
-
-U.S. Environmental Protection Agency (US EPA), "Mercury Study Report to
-Congress: Volume III: Fate and Transport of Mercury in the Environment",
-EPA-452/R-97-005, Office of Air Quality Planning & Standards and Office
-of Research and Development, U.S. Environmental Protection Agency,
-Washington, DC, 1997.
-
-U. S. Environmental Protection Agency (US EPA), "Storm Water Technology
-Fact Sheet: Infiltration Trench", EPA-832-F-99-019, Office of Water,
-Washington, D.C., September 1999.
-
-U.S. Environmental Protection Agency (US EPA), "SWMM 5 Applications
-Manual", EPA/600/R-09/000, National Risk Management Research Laboratory,
-Office of Research and Development, Cincinnati, OH, 2009.
-
-U.S. Environmental Protection Agency (US EPA), "SWMM 5 User's Manual",
-EPA/600/R-05/040, National Risk Management Research Laboratory, Office
-of Research and Development, Cincinnati, OH, 2010.
-
-University of New Hampshire Stormwater Center (UNHSC), Design
-Specifications for Porous Asphalt Pavement and Infiltration Beds,
-University of New Hampshire Stormwater Center (UNHSC), Durham, NH 2009.
-
-Uttormark, P.D., Chaplin, J.D. and Green, K.M., "Estimating Nutrient
-Loadings of Lakes from Non-point Sources," EPA-660/3-74-020,
-Environmental Protection Agency, Washington, DC, August 1974.
-
-Vanoni, V.A., ed., *Sedimentation Engineering*, ASCE, New York, 1975.
-
-van Schilfgaarde, J., ed., *Drainage for Agriculture*, Agronomy Series
-No. 17, American Society of Agronomy, Madison, WI, 1974.
-
-Wallace, R.W., "Statistical Modeling of Water Quality Parameters in
-Urban Runoff," Master of Engineering Technical Report (unpublished),
-Department of Environmental Engineering Sciences, University of Florida,
-Gainesville, 1980.
-
-Weibel, S.R. Anderson, R.J. and Woodward, R.L., "Urban Land Runoff as a
-Factor in Stream Pollution," *Journal Water Pollution Control
-Federation*, Vol. 36. No. 7, July 1964, pp. 914-924.
-
-Weibel, S.R., Weidner, R.B., Cohen, J.M. and Christianson, A.G.,
-"Pesticides and Other Contaminants in Rainfall and Runoff," *Journal
-American Water Works Association*, Vol. 58, No. 8, August 1966, pp.
-1075-1084.
-
-Whitehead, P.G., Williams, R.J., and Lewis, D.R., "Quality simulation
-along river systems (QUASAR): model theory and development", *Sci. Tot.
-Environ*., Vol. 194/195, pp. 447-456, 1997.
-
-Wilber, W. G., and Hunter, J.V., "The Influence of Urbanization on the
-Transport of Heavy Metals in New Jersey Streams", Water Resources
-Research Institute, Rutgers University, New Brunswick, NJ. 1980.
-
-Wischmeier, W.H. and Smith, D.D., "Rainfall Energy and Its Relationship
-to Soil Loss," *Transactions American Geophysical Union*, Vol. 39, No.
-2, April 1958, pp. 285-291.
-
-Zhang, G., Hamlett, J.M., and Saravanapavan, T., "Representation of Low
-Impact Development (LID) Scenarios in SWMM", *Intelligent Modeling of
-Urban Water Systems - Monograph 14*, W. James (editor), CHI, Guelph, ON,
-Canada, 2006.
-
-# Glossary
-
-\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
-
-**A**
-
-**Advection-Dispersion Equation** -- the partial differential equation
-that expresses conservation of mass for a water quality constituent with
-respect to time and space across an element of fluid.
-
-**Aquifer --** as defined in SWMM, it is the underground water bearing
-layer below a land surface, containing both an upper unsaturated zone
-and a lower saturated zone.
-
-**Availability Factor** -- the fraction of buildup on a land use that is
-available for removal by street sweeping.
-
-**B**
-
-**Best Management Practice** - structural or engineered control devices
-and systems (e.g. retention ponds) as well as operational or procedural
-practices used to treat polluted stormwater.
-
-**Bio-Retention Cell** -- a LID control that contains vegetation grown
-in an engineered soil mixture placed above a gravel storage bed
-providing storage, infiltration and evaporation of both direct rainfall
-and runoff captured from surrounding areas.
-
-**BMP Removal Factor** -- the fractional reduction in runoff pollutant
-load achieved by implementing a specific BMP.
-
-**C**
-
-**Capillary Suction Head -** the soil water tension at the interface
-between a fully saturated and partly saturated soil.
-
-**Capture Ratio** -- the amount of the subcatchment's impervious area
-that is directly connected to an LID unit divided by the area of the LID
-unit itself.
-
-**Completely Mixed Reactor** -- a reactor where the concentration of all
-water quality constituents are uniform throughout the reactor's volume.
-
-**Continuous Simulation -** refers to a simulation run that extends over
-more than just a single rainfall event.
-
-**Co-Pollutant** -- a pollutant whose runoff concentration is a fixed
-fraction of some other pollutant (e.g., phosphorus adsorbed onto
-suspended solids).
-
-**Curve Number -** a factor, dependent on land cover, used to compute a
-soil's maximum moisture storage capacity.
-
-**Curve Number Method -** a method that uses a soil's maximum moisture
-storage capacity as derived from its curve number to determine how
-cumulative infiltration changes with cumulative rainfall during a
-rainfall event. Not to be confused with the NRCS (formerly SCS) Curve
-Number runoff method as embodied in TR-55.
-
-**D**
-
-**Darcy's Law -** states that flow velocity of water through a porous
-media equals the hydraulic conductivity of the media times the gradient
-of the hydraulic head it experiences.
-
-**Depression Storage --** the volume over a surface that must be filled
-prior to the occurrence of runoff. It represents such initial
-abstractions as surface ponding, interception by flat roofs and
-vegetation, and surface wetting.
-
-**Design Storm -** a rainfall hyetograph of a specific duration whose
-total depth corresponds to a particular return period (or recurrence
-interval), usually chosen from an IDF curve.
-
-**Directly Connected Impervious Area -** impervious area whose runoff
-flows directly into the collection system without the opportunity to run
-onto pervious areas such as lawns.
-
-**Drainage Mat** - thin, multi-layer fabric mats with ribbed undersides
-that carries away any water that drains through the soil layer of a
-green roof.
-
-**Dry Deposition** -- pollutants deposited on land surfaces, typically
-in the form of particles, during periods of dry weather.
-
-**Dry Weather Flow** - the continuous discharge of sanitary or
-industrial wastewater directly into a sewer system.
-
-**Dust and Dirt** -- street surface accumulation that passes through a
-quarter-inch mesh screen.
-
-**Dynamic Wave Flow Routing** -- a method of modeling non-uniform
-unsteady open channel flow that solves the full Saint Venant equations
-for both continuity and momentum. It can account for channel storage,
-backwater effects, and flow reversals.
-
-**E**
-
-**Event Mean Concentration** -- the average concentration of a pollutant
-in the runoff produced by a single storm event.
-
-**F**
-
-**Field Capacity -** the amount of water a well-drained soil holds after
-free water has drained off, or the maximum soil moisture held against
-gravity. Usually defined as the moisture content at a tension of 1/3
-atmospheres.
-
-**First Order Decay** -- a pollutant decay reaction whose rate is
-proportional to the concentration of pollutant remaining.
-
-**G**
-
-**Green-Ampt Method -** a method for computing infiltration of rainfall
-into soil that is based on Darcy's Law and assumes there is a sharp
-wetting front that moves downward from the surface, separating saturated
-soil above from drier soil below.
-
-**Green Roof** -- a type of bio-retention cell used on a roof that has a
-soil layer above a thin layer of synthetic drainage mat material that
-conveys excess water draining through the soil layer off of the roof.
-
-**H**
-
-**Hydraulic Conductivity -** the rate of water movement through soil
-under a unit gradient of hydraulic head. Its value increases with
-increasing soil moisture, up to a maximum for a completely saturated
-soil (known as the saturated hydraulic conductivity or Ksat).
-
-**Hydraulic Residence Time -** the average time that water has spent
-within a completely mixed reactor.
-
-**I**
-
-**Impervious Surface** -- a surface that does not allow infiltration of
-rain water, such as a roof, roadway or parking lot.
-
-**Infiltration** -- the process by which rainfall penetrates the ground
-surface and fills the pores of the underlying soil.
-
-**Infiltration Trench** -- a narrow ditch filled with gravel that
-intercepts runoff from upslope impervious areas and provides storage
-volume and additional time for captured runoff to infiltrate into the
-native soil.
-
-**Initial Abstraction** -- precipitation that is captured on vegetative
-cover or within surface depressions that is not available to become
-runoff and is removed by either infiltration or evaporation.
-
-**L**
-
-**Land Use Object** - categories of development activities or land
-surface characteristics used to account for spatial variation in
-pollutant buildup and washoff rates.
-
-**LID Control** -- a low impact development practice that provides
-detention storage, enhanced infiltration and evapotranspiration of
-runoff from localized surrounding areas. Examples include rain gardens,
-rain barrels, green roofs, vegetative swales, and bio-retention cells.
-
-**Link** -- a connection between two nodes of a SWMM conveyance network
-that transports water. Channels, pipes, pumps, and regulators (weirs and
-orifices) are all represented as links in a SWMM model.
-
-**Longitudinal Dispersion** -- the process whereby a portion of a
-constituent's mass inside a parcel of water mixes with the contents of
-parcels on either side of it due to velocity and concentration
-gradients.
-
-**M**
-
-**Manning Equation** -- the equation that relates flow rate to the slope
-of the hydraulic grade line for gravity flow in open channels.
-
-**Manning Roughness** -- a coefficient that accounts for friction losses
-in the Manning flow equation.
-
-**Moisture Deficit** -- the difference between a soil's current moisture
-content and its moisture content at saturation.
-
-**N**
-
-**Node** -- a point in a runoff conveyance system that receives runoff
-and other inflows, that connects conveyance links together, or that
-discharges water out of the system. Nodes can be simple junctions, flow
-dividers, storage units, or outfalls. Every conveyance system link is
-attached to both an upstream and downstream node.
-
-**O**
-
-**Overland Flow Path** -- the path that runoff follows as it flows over
-a surface until it reaches a collection channel or drain.
-
-**P**
-
-**Permeable Pavement** - street or parking areas paved with a porous
-concrete or asphalt mix that sits above a gravel storage layer allowing
-rainfall to pass through it into the storage layer where it can
-infiltrate into the site\'s native soil.
-
-**Pervious Surface** -- a surface that allows water to infiltrate into
-the soil below it, such as a natural undeveloped area, a lawn or a
-gravel roadway.
-
-**Pollutant Object** -- the representation of a water quality
-constituent within SWMM.
-
-**Pollutograph** -- a plot of the concentration of a pollutant in runoff
-versus time.
-
-**Porosity** - the fraction of void (or air) space in a volume of soil.
-
-**Potency Factor** -- relates the concentration of the particulate form
-of a pollutant (such as phosphorous or heavy metals) to the
-concentration of total suspended solids.
-
-**R**
-
-**Rainfall Dependent Inflow and Infiltration** - stormwater flows that
-enter sanitary or combined sewers due to \"inflow\" from direct
-connections of downspouts, sump pumps, foundation drains, etc. as well
-as \"infiltration\" of subsurface water through cracked pipes, leaky
-joints, poor manhole connections, etc.
-
-**Rain Barrel** -- a container that collects roof runoff during storm
-events and can either release or re-use the rainwater during dry
-periods.
-
-**Rain Garden** - a type of bio-retention cell consisting of just an
-engineered soil layer with no gravel bed below it.
-
-**Richards Equation** -- the nonlinear partial differential equation
-that describes the physics of water flow in unsaturated soil as a
-function of moisture content and moisture tension.
-
-**Rooftop Disconnection** -- the practice of directing roof downspouts
-onto pervious landscaped areas and lawns instead of directly into storm
-drains.
-
-**S**
-
-**Steady Flow Routing** -- a method of modeling uniform steady open
-channel flow that translates inflow hydrographs at the upstream end of
-the channel to the downstream end, with no delay or change in shape.
-
-**Subcatchment** -- a sub-area of a larger catchment area whose runoff
-flows into a single drainage pipe or channel (or onto another
-subcatchment).
-
-**T**
-
-**Tanks in Series Model** -- an approach to solving constituent
-transport where conduits are represented as completely mixed reactors
-connected together at junctions or at completely mixed storage nodes.
-
-**U**
-
-**Underdrain** -- slotted pipes placed in the storage layer of an LID
-unit that conveys excess captured runoff off of the site and prevents
-the unit from flooding.
-
-**V**
-
-**Vegetative Swale** - channels or depressed areas with sloping sides
-covered with grass and other vegetation that slows down the conveyance
-of collected runoff and allows it more time to infiltrate into the
-native soil.
-
-**W**
-
-**Wet Deposition** - pollutant loads contributed by direct rainfall on a
-catchment.
-
-**Wilting Point** - the soil moisture content at which plants can no
-longer extract moisture to meet their transpiration requirements. It is
-usually defined as the moisture content at a tension of 15 atmospheres.
diff --git a/docs/manuals/reference/quality/media/media/image12.png b/docs/manuals/reference/quality/media/media/image12.png
deleted file mode 100644
index 0e0ff4f08..000000000
Binary files a/docs/manuals/reference/quality/media/media/image12.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image2.png b/docs/manuals/reference/quality/media/media/image2.png
deleted file mode 100644
index 938c22370..000000000
Binary files a/docs/manuals/reference/quality/media/media/image2.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image22.png b/docs/manuals/reference/quality/media/media/image22.png
deleted file mode 100644
index 015f9b3a2..000000000
Binary files a/docs/manuals/reference/quality/media/media/image22.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image23.png b/docs/manuals/reference/quality/media/media/image23.png
deleted file mode 100644
index d2d8db4cd..000000000
Binary files a/docs/manuals/reference/quality/media/media/image23.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image24.png b/docs/manuals/reference/quality/media/media/image24.png
deleted file mode 100644
index 515d3a5af..000000000
Binary files a/docs/manuals/reference/quality/media/media/image24.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image25.png b/docs/manuals/reference/quality/media/media/image25.png
deleted file mode 100644
index eb36b048a..000000000
Binary files a/docs/manuals/reference/quality/media/media/image25.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image26.png b/docs/manuals/reference/quality/media/media/image26.png
deleted file mode 100644
index f76544950..000000000
Binary files a/docs/manuals/reference/quality/media/media/image26.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image27.png b/docs/manuals/reference/quality/media/media/image27.png
deleted file mode 100644
index e60f65bf9..000000000
Binary files a/docs/manuals/reference/quality/media/media/image27.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image28.png b/docs/manuals/reference/quality/media/media/image28.png
deleted file mode 100644
index 8b915293f..000000000
Binary files a/docs/manuals/reference/quality/media/media/image28.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image29.png b/docs/manuals/reference/quality/media/media/image29.png
deleted file mode 100644
index c92b6c9bc..000000000
Binary files a/docs/manuals/reference/quality/media/media/image29.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image3.png b/docs/manuals/reference/quality/media/media/image3.png
deleted file mode 100644
index b1dd0457d..000000000
Binary files a/docs/manuals/reference/quality/media/media/image3.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image30.png b/docs/manuals/reference/quality/media/media/image30.png
deleted file mode 100644
index ad8096b4d..000000000
Binary files a/docs/manuals/reference/quality/media/media/image30.png and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image6.emf b/docs/manuals/reference/quality/media/media/image6.emf
deleted file mode 100644
index ab9038fdf..000000000
Binary files a/docs/manuals/reference/quality/media/media/image6.emf and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/image7.emf b/docs/manuals/reference/quality/media/media/image7.emf
deleted file mode 100644
index a7091f6ec..000000000
Binary files a/docs/manuals/reference/quality/media/media/image7.emf and /dev/null differ
diff --git a/docs/manuals/reference/quality/media/media/figure1-6.png b/docs/manuals/reference/quality/media/media/quality-figure1-6.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/figure1-6.png
rename to docs/manuals/reference/quality/media/media/quality-figure1-6.png
diff --git a/docs/manuals/reference/quality/media/media/image1.jpeg b/docs/manuals/reference/quality/media/media/quality-image1.jpeg
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image1.jpeg
rename to docs/manuals/reference/quality/media/media/quality-image1.jpeg
diff --git a/docs/manuals/reference/quality/media/media/image10.png b/docs/manuals/reference/quality/media/media/quality-image10.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image10.png
rename to docs/manuals/reference/quality/media/media/quality-image10.png
diff --git a/docs/manuals/reference/quality/media/media/image11.png b/docs/manuals/reference/quality/media/media/quality-image11.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image11.png
rename to docs/manuals/reference/quality/media/media/quality-image11.png
diff --git a/docs/manuals/reference/quality/media/media/quality-image12.png b/docs/manuals/reference/quality/media/media/quality-image12.png
new file mode 100644
index 000000000..b8ea09f92
Binary files /dev/null and b/docs/manuals/reference/quality/media/media/quality-image12.png differ
diff --git a/docs/manuals/reference/quality/media/media/image13.png b/docs/manuals/reference/quality/media/media/quality-image13.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image13.png
rename to docs/manuals/reference/quality/media/media/quality-image13.png
diff --git a/docs/manuals/reference/quality/media/media/image14.png b/docs/manuals/reference/quality/media/media/quality-image14.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image14.png
rename to docs/manuals/reference/quality/media/media/quality-image14.png
diff --git a/docs/manuals/reference/quality/media/media/image15.png b/docs/manuals/reference/quality/media/media/quality-image15.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image15.png
rename to docs/manuals/reference/quality/media/media/quality-image15.png
diff --git a/docs/manuals/reference/quality/media/media/image16.png b/docs/manuals/reference/quality/media/media/quality-image16.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image16.png
rename to docs/manuals/reference/quality/media/media/quality-image16.png
diff --git a/docs/manuals/reference/quality/media/media/image17.png b/docs/manuals/reference/quality/media/media/quality-image17.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image17.png
rename to docs/manuals/reference/quality/media/media/quality-image17.png
diff --git a/docs/manuals/reference/quality/media/media/image18.png b/docs/manuals/reference/quality/media/media/quality-image18.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image18.png
rename to docs/manuals/reference/quality/media/media/quality-image18.png
diff --git a/docs/manuals/reference/hydraulics/media/media/image2.png b/docs/manuals/reference/quality/media/media/quality-image2.png
similarity index 100%
rename from docs/manuals/reference/hydraulics/media/media/image2.png
rename to docs/manuals/reference/quality/media/media/quality-image2.png
diff --git a/docs/manuals/reference/quality/media/media/image20.png b/docs/manuals/reference/quality/media/media/quality-image20.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image20.png
rename to docs/manuals/reference/quality/media/media/quality-image20.png
diff --git a/docs/manuals/reference/quality/media/media/image21.png b/docs/manuals/reference/quality/media/media/quality-image21.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image21.png
rename to docs/manuals/reference/quality/media/media/quality-image21.png
diff --git a/docs/manuals/reference/quality/media/media/image31.png b/docs/manuals/reference/quality/media/media/quality-image31.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image31.png
rename to docs/manuals/reference/quality/media/media/quality-image31.png
diff --git a/docs/manuals/reference/quality/media/media/image32.png b/docs/manuals/reference/quality/media/media/quality-image32.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image32.png
rename to docs/manuals/reference/quality/media/media/quality-image32.png
diff --git a/docs/manuals/reference/quality/media/media/image33.png b/docs/manuals/reference/quality/media/media/quality-image33.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image33.png
rename to docs/manuals/reference/quality/media/media/quality-image33.png
diff --git a/docs/manuals/reference/quality/media/media/image34.png b/docs/manuals/reference/quality/media/media/quality-image34.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image34.png
rename to docs/manuals/reference/quality/media/media/quality-image34.png
diff --git a/docs/manuals/reference/quality/media/media/image35.png b/docs/manuals/reference/quality/media/media/quality-image35.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image35.png
rename to docs/manuals/reference/quality/media/media/quality-image35.png
diff --git a/docs/manuals/reference/quality/media/media/image36.png b/docs/manuals/reference/quality/media/media/quality-image36.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image36.png
rename to docs/manuals/reference/quality/media/media/quality-image36.png
diff --git a/docs/manuals/reference/quality/media/media/image37.png b/docs/manuals/reference/quality/media/media/quality-image37.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image37.png
rename to docs/manuals/reference/quality/media/media/quality-image37.png
diff --git a/docs/manuals/reference/quality/media/media/image38.png b/docs/manuals/reference/quality/media/media/quality-image38.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image38.png
rename to docs/manuals/reference/quality/media/media/quality-image38.png
diff --git a/docs/manuals/reference/quality/media/media/image39.png b/docs/manuals/reference/quality/media/media/quality-image39.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image39.png
rename to docs/manuals/reference/quality/media/media/quality-image39.png
diff --git a/docs/manuals/reference/quality/media/media/image4.png b/docs/manuals/reference/quality/media/media/quality-image4.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image4.png
rename to docs/manuals/reference/quality/media/media/quality-image4.png
diff --git a/docs/manuals/reference/quality/media/media/image40.png b/docs/manuals/reference/quality/media/media/quality-image40.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image40.png
rename to docs/manuals/reference/quality/media/media/quality-image40.png
diff --git a/docs/manuals/reference/quality/media/media/image41.png b/docs/manuals/reference/quality/media/media/quality-image41.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image41.png
rename to docs/manuals/reference/quality/media/media/quality-image41.png
diff --git a/docs/manuals/reference/quality/media/media/image42.png b/docs/manuals/reference/quality/media/media/quality-image42.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image42.png
rename to docs/manuals/reference/quality/media/media/quality-image42.png
diff --git a/docs/manuals/reference/quality/media/media/image5.png b/docs/manuals/reference/quality/media/media/quality-image5.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image5.png
rename to docs/manuals/reference/quality/media/media/quality-image5.png
diff --git a/docs/manuals/reference/quality/media/media/image8.png b/docs/manuals/reference/quality/media/media/quality-image8.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image8.png
rename to docs/manuals/reference/quality/media/media/quality-image8.png
diff --git a/docs/manuals/reference/quality/media/media/image9.png b/docs/manuals/reference/quality/media/media/quality-image9.png
similarity index 100%
rename from docs/manuals/reference/quality/media/media/image9.png
rename to docs/manuals/reference/quality/media/media/quality-image9.png
diff --git a/docs/manuals/reference/quality/sections/Chapter1-Overview.md b/docs/manuals/reference/quality/sections/Chapter1-Overview.md
index f39cd5d55..5d357a442 100644
--- a/docs/manuals/reference/quality/sections/Chapter1-Overview.md
+++ b/docs/manuals/reference/quality/sections/Chapter1-Overview.md
@@ -70,7 +70,7 @@ system. SWMM conceptualizes this system as a series of water and
 material flows between several major environmental compartments. These
 compartments include:
 
-![](quality/media/media/image1.jpeg "image1")
+![](quality/media/media/quality-image1.jpeg "image1")
 
Figure 1‑1 Elements of a typical urban
 drainage system

@@ -119,10 +119,28 @@ SWMM model. Table 1-2 provides a summary of the various objects used in
 SWMM. Their properties and functions will be described in more detail
 throughout the course of this manual.
 
-![](quality/media/media/image2.png "Objects2")
+![Figure 1-2 Objects of an OpenSWMM model](figures/png/eng_object_sketch.png)
+
+

+@ref engine_manual_sect_RAINGAGES "Rain gage"
+@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S1"
+@ref engine_manual_sect_SUBCATCHMENTS "Subcatchment S2"
+@ref engine_manual_sect_JUNCTIONS "Junction"
+@ref engine_manual_sect_CONDUITS "Conduit"
+@ref engine_manual_sect_VIRTUAL_JUNCTIONS "Virtual junction"
+@ref engine_manual_sect_INLET_JUNCTIONS "Inlet junction"
+@ref engine_manual_sect_STREETS "Street conduit"
+@ref engine_manual_sect_DIVIDERS "Divider"
+@ref engine_manual_sect_WEIRS "Weir"
+@ref engine_manual_sect_ORIFICES "Orifice"
+@ref engine_manual_sect_STORAGE "Storage unit"
+@ref engine_manual_sect_PUMPS "Pump"
+@ref engine_manual_sect_OUTFALLS "Outfall"
+@ref engine_manual_sect_2D_TRIANGLES "2D mesh"
+@ref engine_manual_sect_2D_VERTEX_NODE_MAP "1D–2D exchange"
+

 
Figure 1‑2 SWMM's conceptual model of a
-stormwater drainage system

+class="anchor">Figure 1-2 Objects of an OpenSWMM model

 
 **Table 1‑2 SWMM's modeling objects**
 
@@ -160,10 +178,70 @@ Figure 1-3 depicts the processes that SWMM models using the objects
 described previously and how they are tied to one another. The
 hydrological processes depicted in this diagram include:
 
-![](quality/media/media/image3.png "image3")
+![Figure 1-3 Processes modelled by OpenSWMM](figures/png/eng_process_flow.png)
+
+

+@ref hydrology_ref_ch2_meteorology "Precipitation"
+@ref engine_manual_sect_RAINGAGES "rain · snow"
+@ref hydrology_ref_ch2_meteorology "scale factors"
+@ref hydrology_ref_ch6_snowmelt "Snowmelt"
+@ref hydrology_ref_ch6_snowmelt "degree-day · areal depletion"
+@ref hydrology_ref_ch3_surface_runoff "Initial abstraction · evaporation"
+@ref engine_manual_sect_SUBAREAS "depression storage"
+@ref hydrology_ref_ch3_surface_runoff "Surface runoff"
+@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir"
+@ref hydrology_ref_ch4_infiltration "Horton · Green-Ampt · CN"
+@ref quality_ref_ch6_lid_controls "LID controls"
+@ref quality_ref_ch6_lid_controls "layered units"
+@ref quality_ref_ch6_lid_controls "storage nodes"
+@ref quality_ref_ch4_surface_washoff "Washoff"
+@ref quality_ref_ch3_pollutant_buildup "EMC · exponential · rating"
+@ref hydrology_ref_ch5_groundwater "Groundwater"
+@ref hydrology_ref_ch5_groundwater "two-zone aquifer per subcatchment"
+@ref hydrology_ref_ch9_mesh_groundwater "two-layer aquifer on the mesh"
+@ref hydrology_ref_ch9_mesh_groundwater "groundwater transport"
+@ref quality_ref_ch3_pollutant_buildup "Pollutant buildup"
+@ref quality_ref_ch3_pollutant_buildup "land uses · sweeping"
+@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh"
+@ref hydrology_ref_ch8_mesh_surface "natural neighbour"
+@ref hydraulics_ref_ch9_two_dimensional "2D overland flow"
+@ref hydraulics_ref_ch9_two_dimensional "local inertial"
+@ref hydraulics_ref_ch9_two_dimensional "full shallow water"
+@ref hydraulics_ref_ch9_two_dimensional "diffusive wave"
+@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration · evaporation"
+@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment · mesh aquifer"
+@ref quality_ref_ch10_mesh_quality "2D surface quality"
+@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff"
+@ref engine_manual_sect_INFLOWS "External inflows"
+@ref engine_manual_sect_DWF "dry weather flow"
+@ref hydrology_ref_ch7_rdii "RDII: RTK"
+@ref hydrology_ref_ch7_rdii "RDII: IA decay"
+@ref engine_manual_sect_INFLOWS "user · interface files"
+@ref hydraulics_ref_ch7_advanced_features "Street inlets"
+@ref hydraulics_ref_ch7_advanced_features "HEC-22 link attribute"
+@ref hydraulics_ref_ch7_advanced_features "inlet junction"
+@ref hydraulics_ref_ch2_hydraulic_model "Channel, pipe and storage routing"
+@ref hydraulics_ref_ch2_hydraulic_model "steady"
+@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave"
+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN · slot · dynamic slot"
+@ref hydraulics_ref_ch3_dynamic_wave "TPA"
+@ref hydraulics_ref_ch3_dynamic_wave "virtual · inlet junctions"
+@ref quality_ref_ch5_transport_treatment "Transport and reactions"
+@ref quality_ref_ch5_transport_treatment "CSTR"
+@ref quality_ref_ch7_ard_transport "ARD"
+@ref quality_ref_ch7_ard_transport "LARD"
+@ref quality_ref_ch5_transport_treatment "first-order decay"
+@ref quality_ref_ch8_msx_reactions "MSX"
+@ref quality_ref_ch9_age_heat "water age"
+@ref quality_ref_ch9_age_heat "heat"
+@ref quality_ref_ch11_planned "sediment"
+@ref engine_manual_sect_TREATMENT "treatment · diversion"
+@ref engine_manual_sect_OUTFALLS "Outfalls"
+

 
Figure 1‑3 Processes modeled by
-SWMM

+class="anchor">Figure 1-3 Processes modelled by OpenSWMM

 
 - time-varying precipitation
 
@@ -258,7 +336,7 @@ where
 
 Figure 1-4 depicts the simulation process in block diagram fashion.
 
-![](quality/media/media/image4.png "image4")
+![](quality/media/media/quality-image4.png "image4")
 
Figure 1‑4 Block diagram of SWMM's state
 transition process

@@ -358,7 +436,7 @@ Users' Manual (US EPA, 2010). Next the values of all state variables are
 initialized, as is the current simulation time (T), runoff time
 (Troff), and reporting time (Trpt).
 
-![](quality/media/media/image5.png "image5")
+![](quality/media/media/quality-image5.png "image5")
 
Figure 1‑5 Flow chart of SWMM's simulation
 procedure

@@ -403,7 +481,7 @@ reporting purposes. In other words, if a reporting time falls within a
 runoff time step the reported rainfall intensity is the value associated
 with the start of the runoff time step.
 
-![](quality/media/media/figure1-6.png)
+![](quality/media/media/quality-figure1-6.png)
 
 **Figure 1‑6 Interpolation of reported values from computed values**
 
@@ -442,5 +520,136 @@ the unit of length and seconds as the unit of time.
 | Width | feet | meters |
 | Wind Speed | miles/hour | kilometers/hour |
 
-
-
+## 1.6 The Formulations This Manual Covers
+
+Figure 1-7 places the water quality of this manual on OpenSWMM's process map:
+buildup and washoff on the subcatchments and on the 2D mesh, the transport
+engines and reaction systems of the conveyance network, water age and heat.
+Each alternative carries its status (Implemented, Experimental, Planned or
+Retired); the subsurface compartments are shown faded.
+
+![Figure 1-7 The water quality of this manual: buildup, washoff, transport and reactions across the compartments](figures/png/quality_conceptual_map.png)
+
+Figure 1-7 The water quality of this manual: buildup, washoff, transport and reactions across the compartments
+
+

+@ref hydrology_ref_ch2_meteorology "Precipitation"
+@ref engine_manual_sect_RAINGAGES "rain gages"
+@ref hydrology_ref_ch6_snowmelt "rain · snow split (SCF)"
+@ref hydrology_ref_ch2_meteorology "scale factors"
+@ref hydrology_ref_ch2_meteorology "Climate"
+@ref engine_manual_sect_TEMPERATURE "temperature"
+@ref engine_manual_sect_EVAPORATION "evaporation: constant · monthly · series · Hargreaves · file"
+@ref engine_manual_sect_TEMPERATURE "wind"
+@ref hydrology_ref_ch2_meteorology "humidity · dew point"
+@ref hydrology_ref_ch2_meteorology "prescribed PET (API)"
+@ref hydrology_ref_ch6_snowmelt "Snowmelt"
+@ref hydrology_ref_ch6_snowmelt "degree-day · heat budget · areal depletion"
+@ref hydrology_ref_ch3_surface_runoff "Runoff"
+@ref hydrology_ref_ch3_surface_runoff "nonlinear reservoir"
+@ref engine_manual_sect_SUBAREAS "depression storage"
+@ref engine_manual_sect_SUBAREAS "routing to another subcatchment"
+@ref hydrology_ref_ch4_infiltration "Infiltration"
+@ref hydrology_ref_ch4_infiltration "Horton"
+@ref hydrology_ref_ch4_infiltration "modified Horton"
+@ref hydrology_ref_ch4_infiltration "Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "modified Green-Ampt"
+@ref hydrology_ref_ch4_infiltration "curve number"
+@ref quality_ref_ch6_lid_controls "LID controls"
+@ref quality_ref_ch6_lid_controls "layered units (8 types)"
+@ref quality_ref_ch6_lid_controls "LID as storage nodes"
+@ref quality_ref_ch6_lid_controls "detailed output"
+@ref quality_ref_ch3_pollutant_buildup "Surface quality"
+@ref quality_ref_ch3_pollutant_buildup "buildup · washoff by land use"
+@ref engine_manual_sect_LANDUSES "street sweeping"
+@ref quality_ref_ch10_mesh_quality "MSX species"
+@ref hydrology_ref_ch8_mesh_surface "Rain on the mesh"
+@ref hydrology_ref_ch8_mesh_surface "natural neighbour"
+@ref engine_manual_sect_2D_OPTIONS "system"
+@ref hydrology_ref_ch8_mesh_surface "Per-cell infiltration"
+@ref hydrology_ref_ch8_mesh_surface "Horton · Green-Ampt · CN · constant"
+@ref engine_manual_sect_2D_INFILTRATION_OPTIONS "→ lost · subcatchment aquifer · mesh aquifer"
+@ref hydraulics_ref_ch9_two_dimensional "Overland flow"
+@ref hydraulics_ref_ch9_two_dimensional "local inertial"
+@ref hydraulics_ref_ch9_two_dimensional "full shallow water"
+@ref hydraulics_ref_ch9_two_dimensional "diffusive wave"
+@ref hydraulics_ref_ch10_planned "IMEX / CVODE"
+@ref hydraulics_ref_ch9_two_dimensional "Mesh and closure"
+@ref hydraulics_ref_ch9_two_dimensional "triangles"
+@ref hydraulics_ref_ch9_two_dimensional "quads"
+@ref hydraulics_ref_ch9_two_dimensional "flat cells"
+@ref hydraulics_ref_ch9_two_dimensional "VFR closure"
+@ref quality_ref_ch10_mesh_quality "Surface quality · transport"
+@ref quality_ref_ch10_mesh_quality "coverages · buildup · washoff"
+@ref quality_ref_ch10_mesh_quality "species on the mesh"
+@ref hydraulics_ref_ch9_two_dimensional "Backends"
+@ref hydraulics_ref_ch9_two_dimensional "CPU"
+@ref hydraulics_ref_ch9_two_dimensional "OpenMP"
+@ref hydraulics_ref_ch9_two_dimensional "CUDA · HIP · SYCL"
+@ref hydraulics_ref_ch10_planned "Metal"
+@ref hydrology_ref_ch5_groundwater "Two-zone aquifer"
+@ref hydrology_ref_ch5_groundwater "unsaturated + saturated zone"
+@ref engine_manual_sect_AQUIFERS "percolation · deep percolation · ET"
+@ref engine_manual_sect_GWF "lateral interflow, user [GWF]"
+@ref hydrology_ref_ch9_mesh_groundwater "Groundwater transport"
+@ref hydrology_ref_ch9_mesh_groundwater "advection–dispersion · heat"
+@ref hydrology_ref_ch9_mesh_groundwater "Two-layer aquifer"
+@ref hydrology_ref_ch9_mesh_groundwater "Gardner"
+@ref hydrology_ref_ch9_mesh_groundwater "Russo"
+@ref hydrology_ref_ch9_mesh_groundwater "Brooks–Corey"
+@ref hydrology_ref_ch9_mesh_groundwater "van Genuchten"
+@ref hydrology_ref_ch9_mesh_groundwater "closed form · enslaved · σ column"
+@ref hydrology_ref_ch9_mesh_groundwater "Dunne return flow"
+@ref hydrology_ref_ch9_mesh_groundwater "node–bed exchange"
+@ref hydrology_ref_ch9_mesh_groundwater "capillary rise · boundary ET"
+@ref hydrology_ref_ch9_mesh_groundwater "per-subcatchment mode"
+@ref engine_manual_sect_JUNCTIONS "Nodes"
+@ref engine_manual_sect_JUNCTIONS "junction · storage · divider · outfall"
+@ref hydraulics_ref_ch3_dynamic_wave "virtual junction"
+@ref hydraulics_ref_ch7_advanced_features "inlet junction"
+@ref engine_manual_sect_CONDUITS "Links"
+@ref hydraulics_ref_ch5_cross_section "conduits, 26 sections"
+@ref hydraulics_ref_ch5_cross_section "street · dummy"
+@ref hydraulics_ref_ch10_planned "Chebyshev irregular"
+@ref engine_manual_sect_PUMPS "pumps · orifices · weirs · outlets · culverts"
+@ref hydraulics_ref_ch5_cross_section "storage shapes"
+@ref hydraulics_ref_ch7_advanced_features "HEC-22 inlets"
+@ref hydraulics_ref_ch2_hydraulic_model "Flow routing"
+@ref hydraulics_ref_ch2_hydraulic_model "steady"
+@ref hydraulics_ref_ch4_kinematic_wave "kinematic wave"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic wave"
+@ref hydraulics_ref_ch8_finite_volume "finite volume"
+@ref hydraulics_ref_ch8_lts "local time stepping"
+@ref hydraulics_ref_ch10_planned "1D GPU backend"
+@ref hydraulics_ref_ch3_dynamic_wave "Pressurisation"
+@ref hydraulics_ref_ch3_dynamic_wave "EXTRAN"
+@ref hydraulics_ref_ch3_dynamic_wave "slot"
+@ref hydraulics_ref_ch3_dynamic_wave "dynamic slot"
+@ref hydraulics_ref_ch3_dynamic_wave "TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: slot"
+@ref hydraulics_ref_ch8_finite_volume "FV: TPA"
+@ref hydraulics_ref_ch8_finite_volume "FV: implicit head"
+@ref hydraulics_ref_ch3_dynamic_wave "unsteady friction"
+@ref hydraulics_ref_ch3_dynamic_wave "Node solution"
+@ref hydraulics_ref_ch3_dynamic_wave "explicit continuity"
+@ref hydraulics_ref_ch3_dynamic_wave "semi-implicit continuity"
+@ref hydraulics_ref_ch3_anderson "Anderson acceleration"
+@ref hydraulics_ref_ch10_planned "FV_NODE_* keys"
+@ref quality_ref_ch5_transport_treatment "Transport"
+@ref quality_ref_ch5_transport_treatment "CSTR"
+@ref quality_ref_ch7_ard_transport "Eulerian ARD"
+@ref quality_ref_ch7_ard_transport "Lagrangian LARD"
+@ref quality_ref_ch7_ard_transport "random-walk dispersion"
+@ref quality_ref_ch5_transport_treatment "first-order decay"
+@ref quality_ref_ch8_msx_reactions "MSX reactions"
+@ref quality_ref_ch9_age_heat "water age"
+@ref quality_ref_ch9_age_heat "heat"
+@ref quality_ref_ch11_planned "sediment"
+@ref engine_manual_sect_TREATMENT "treatment functions"
+@ref engine_manual_sect_INFLOWS "Inflows"
+@ref engine_manual_sect_DWF "dry weather flow"
+@ref hydrology_ref_ch7_rdii "RDII: RTK"
+@ref hydrology_ref_ch7_rdii "RDII: IA decay"
+@ref engine_manual_sect_INFLOWS "user · interface files"
+@ref engine_manual_sect_CONTROLS "control rules"
+

diff --git a/docs/manuals/reference/quality/sections/Chapter10-MeshSurfaceQuality.md b/docs/manuals/reference/quality/sections/Chapter10-MeshSurfaceQuality.md
new file mode 100644
index 000000000..15cd6533f
--- /dev/null
+++ b/docs/manuals/reference/quality/sections/Chapter10-MeshSurfaceQuality.md
@@ -0,0 +1,456 @@
+@page quality_ref_ch10_mesh_quality Chapter 10: Surface Quality and Transport on the 2D Mesh
+
+@tableofcontents
+
+## 10.1 The Transport Policy
+
+This chapter describes what the water of the overland flow solver
+(@ref hydraulics_ref_ch9_two_dimensional) carries. The mesh is a fourth
+*domain* species can occupy, beside subcatchment runoff, the legacy aquifers
+and the 1D network, and the first question is which classes travel there.
+
+That question is answered in one place — the **transport policy** — rather
+than re-derived by each solver. Four classes are recognised: pollutants
+(`[POLLUTANTS]`), the reaction system's species (Chapter 8), water age
+(`__WATER_AGE__`) and temperature (`__TEMPERATURE__`). For each domain, each
+class resolves to **enabled** with a row count, **disabled by the user**
+naming the key, or **unavailable** with the reason. For the 2D surface the
+gates fire in this order: no mesh — unavailable; the class off at project
+level ("no [POLLUTANTS]", "no reactions component", "WATER_AGE OFF",
+"HEAT_TRANSPORT OFF") — unavailable; `[OPTIONS] IGNORE_2D YES` — disabled;
+`IGNORE_QUALITY YES` — disabled, for **pollutants and MSX species only**,
+since age and temperature are their own options on the mesh as in 1D; a
+`WALL` species in the reaction system — MSX unavailable, since a
+wall-attached species has no meaning on a sheet of water and the class is
+left off with a warning rather than carried half; the matching
+`[2D_OPTIONS]` key below set to `NO` — disabled, naming the key; otherwise
+enabled.
+
+| Key | Values | Default | Effect on the mesh |
+|---|---|---|---|
+| `TRANSPORT_POLLUTANTS` | `YES` or `NO` | `YES` | Carry the `[POLLUTANTS]` rows |
+| `TRANSPORT_MSX` | `YES` or `NO` | `YES` | Carry the reaction system's species |
+| `TRANSPORT_AGE` | `YES` or `NO` | `YES` | Carry `__WATER_AGE__` when `WATER_AGE ON` |
+| `TRANSPORT_TEMPERATURE` | `YES` or `NO` | `YES` | Carry `__TEMPERATURE__` when `HEAT_TRANSPORT ON` |
+| `DISPERSION` | m²/s, finite, non-negative | 0 | Isotropic dispersion (§10.2); negative is refused, not clamped |
+
+The policy is *inherit-on* (@ref engine_manual_sect_2D_OPTIONS): a class
+enabled at project level runs in every domain whose solver carries it unless
+a key says otherwise. Rows take the canonical order the Eulerian 1D engine
+uses — pollutants, MSX species in declaration order, the age row, the
+temperature row **last**. Whenever a project declares any class, the
+resolved matrix is printed in the `.rpt` header, one row per domain, with
+`on(n)`, `off:KEY` or `n/a` per class and one explanatory line per `n/a`
+cell; the C API and the GUI read the same matrix. Transport rows are
+integrated by the CPU marcher; the Kokkos backends carry none, so a project
+with any class enabled on the mesh runs on the CPU whatever the backend
+setting.
+
+
+![Figure 10-1](figures/png/quality_ch10_transport_policy.png)
+
+*Figure 10-1 The transport policy matrix: which species class moves in which domain, and the gate ladder the 2D surface passes*
+
+
+
+## 10.2 Species Transport on the Mesh
+
+### 10.2.1 Mass, not concentration
+
+The hydraulic solver's integrated state is the cell **volume**; depth and head
+are reconstructed from it. The transport state follows the same rule: what
+is stored per cell is species **mass** \f$m_{s,i}\f$, species-major, and
+concentration is derived,
+
+| | | | |
+|---|---|---|---|
+| \f[c_{s,i} = \frac{m_{s,i}}{V_i}\f] | | (10-1) | |
+
+reported as zero when \f$V_i\f$ lies below the hydraulics' dry-volume
+threshold. A cell that empties keeps what it held, and no concentration has
+to be extrapolated against a vanishing volume. The temperature row is the
+one **signed** row — water below 0 °C is a state — so every non-negativity
+guard in the marcher and the coupling queue skips it, as in 1D (Chapter 9).
+
+### 10.2.2 The governing equation
+
+Per cell \f$i\f$ and species \f$s\f$, in mass form:
+
+| | | | |
+|---|---|---|---|
+| \f[\frac{dm_{s,i}}{dt} = -\sum_{e \in \partial i} Q_e\, c_{s,\mathrm{donor}(e)} + \sum_{e \in \partial i} \frac{D\, h_e\, \xi_e}{d_e}\,(c_{s,j(e)} - c_{s,i}) + V_i\, r_s(\mathbf{c}_i, T_i) + S_{s,i}\f] | | (10-2) | |
+
+with \f$Q_e\f$ the face volume flux the marcher computed, \f$D\f$ the
+isotropic dispersion coefficient, \f$h_e\f$ the face depth, \f$\xi_e\f$ the
+face length, \f$d_e\f$ the normal centroid distance, \f$r_s\f$ the reaction
+rate and \f$S_{s,i}\f$ the sources of §10.2.5 — Chapter 7's equation for a
+cell of the mesh, differing chiefly in how the first term is evaluated.
+
+### 10.2.3 Advection rides the face fluxes
+
+The advective flux is booked **inside the same face firing** that moves the
+water. When the marcher commits a volume \f$\Delta M\f$ across a face —
+after the Froude cap and the positivity share, so it is the volume that
+actually moves — the mass \f$\Delta M \cdot c_{\mathrm{donor}}\f$ leaves the
+donor and arrives at the receiver, with the donor concentration read at that
+substep against the same published volume the share was budgeted from.
+First-order donor-cell upwinding is the only scheme on the mesh; the limited
+second-order reconstructions of the 1D engines are not offered (§10.11).
+
+Two properties follow: the species flux cannot disagree with the volume flux
+about cadence, direction or magnitude, so a uniform field stays uniform
+under arbitrary flow, across local-time-stepping tiers and through wet/dry
+fronts; and the scheme conserves to round-off, one writer per face. The
+donor read guards on \f$V > 0\f$ alone, not on the dry depth, so a face that
+fires at a wet/dry front exports at the exporter's true concentration.
+
+### 10.2.4 Dispersion
+
+`[2D_OPTIONS] DISPERSION` sets one isotropic coefficient in m²/s. The
+exchange is an explicit two-point flux booked on the same face, at the same
+cadence, into the same accumulators as advection:
+
+| | | | |
+|---|---|---|---|
+| \f[\Delta m_{a \to b} = D\, h_e\, \xi_e\, \frac{\Delta t_e}{d_e}\,(c_a - c_b)\f] | | (10-3) | |
+
+An explicit parabolic term has its own stability limit,
+\f$D\,\Delta t / d_e^2 \lesssim \tfrac{1}{2}\f$, and the marcher's substep is
+set by gravity waves, not by \f$D\f$. Rather than couple the global step to a
+local term the exchange is **limited** so the pair can never cross: at most
+one third (one quarter for a quadrilateral receiver) of the amount that would
+equalise the two concentrations — pairwise bounds do not compose across a
+cell's faces — and at most the \f$\beta\f$ share of the giver's mass the
+volume flux is held to; the signed temperature row takes the equalisation
+bound alone. A face on which the limiter binds is **counted** and reported
+as a warning at the end of the run: the physics stayed bounded, but the
+dispersion rate there was less than asked for. With `DISPERSION 0` the block
+is not entered.
+
+### 10.2.5 Sources, sinks and the reserved rows
+
+| Pathway | Pollutants and MSX | Age | Temperature |
+|---|---|---|---|
+| Rainfall | At the `[POLLUTANTS]` rain concentration; MSX rows rain in clean | Age 0 | The `RAINFALL` source temperature of `[HEAT_SOURCES]` |
+| Evaporation | Removes water and **no** solute — the concentration rises | Removed at the cell's mean age | Removed at the cell's mean temperature |
+| Infiltration | Removes mass at the cell concentration; booked to a named ledger | Same | Same |
+| Boundary outflow | Leaves at the cell concentration | Same | Same |
+| Boundary inflow | At the `[2D_BOUNDARY_QUALITY]` value, else clean | Same | Same |
+| 1D coupling | §10.4 | §10.4 | §10.4 |
+| Washoff | §10.7 | Does not build up | Does not build up |
+
+Age and temperature are carried as age-volume and temperature-volume, so for
+them the evaporative sink is applied at the cell's own mean — leaving either
+untouched while the volume fell would age or heat the cell by evaporating it.
+
+### 10.2.6 Aging and reactions
+
+After each advance the age row gains exactly \f$\Delta t\,V_i\f$, so every
+wet cell's mean age grows by the step — Chapter 9's law. The reaction stage
+then runs on a concentration view of the **wet** cells (volume above
+`DRY_DEPTH`·area) through the same `reactArdStage` the Eulerian 1D engine
+uses: pollutant first-order decay by exact exponential, booked to the reacted
+ledger, and multi-species kinetics in **pipe** scope — an overland cell is a
+flowing element, not a tank — against the cell's own temperature row where
+heat is on. Dry cells are skipped; the age and temperature rows do not react.
+
+
+
+## 10.3 Initial and Boundary Quality
+
+Two sections seed and force the rows; both may be placed in the `.inp` or in
+the external mesh file named by `[2D_MESH_FILE]`.
+
+**`[2D_INITIAL_QUALITY]`** (@ref engine_manual_sect_2D_INITIAL_QUALITY) sets
+the starting concentration by scope — `*` for the whole mesh, `TAG name`,
+or `CELL n` with a **1-based** index, triangles first then quadrilaterals. A
+species is named as it appears in the row list: a pollutant id, a reaction
+species id, `__WATER_AGE__` (authored in **hours**, carried in seconds) or
+`__TEMPERATURE__` (°C). Negative and non-finite values are refused rather
+than clamped; a species the mesh does not carry is an open-time error.
+Without a row, pollutant, MSX and age rows start at zero and the temperature
+row at the `INITIAL_STATE` source temperature, as in 1D.
+
+**`[2D_BOUNDARY_QUALITY]`** (@ref engine_manual_sect_2D_BOUNDARY_QUALITY)
+gives the concentration carried by water **entering** through a boundary
+edge:
+
+```
+[2D_BOUNDARY_QUALITY]
+;; cell  edge  species          conc
+   812   1     TSS              35.0
+   812   1     __TEMPERATURE__  14.0
+```
+
+The edge is addressed by its owning cell and local edge index (0–2 on a
+triangle, 0–3 on a quadrilateral). The cell index here is **0-based** — the
+`TRI` column of `[2D_BOUNDARY_CONDITIONS]`, which the row mirrors — unlike
+the 1-based `CELL n` scope of the other sections. The edge must be a
+non-`WALL` boundary edge; a wall admits no water, so a row on one is refused
+at initialization. Only inflow carries the value; outflow always leaves at the
+cell's concentration. An edge with no row admits clean water — zero
+concentration, age zero, zero temperature-volume. Rows in a model that
+carries no transport rows are an error, not a silent no-op.
+
+
+
+## 10.4 Exchange with the 1D Network
+
+Everywhere the coupling moves water between a node and the mesh, a species
+tuple moves with it at the **donor's** value.
+
+**Mesh to network.** A 2D→1D drain leaves at the cell's concentration,
+accumulated per coupling point over the exchange window. At the window's end
+the router hands each node the drained mass through the same queue the
+volume takes, in the 1D engines' units, so mass over volume is still the
+cell's concentration exactly. Rows route by kind: pollutant rows into the
+node's species queue, the age row into the age-volume queue, the temperature
+row into the temperature-volume queue. **MSX rows go nowhere** — the 1D node
+has no reaction-species inflow accumulator for any loader yet — and their
+drained mass stays in the surface's coupling-loss ledger (§10.11). A rim that
+flip-flops within one window would hand the node gross mass with net water
+and make a junction fed at \f$c_0\f$ read above \f$c_0\f$, so the router
+pairs the window's spill against its drain first, at the node's published
+value, and leaves only the net-negative remainder to the node's volume drop,
+which removes it at the mixed concentration.
+
+**Network to mesh.** A junction spill arrives at the **node's published row
+values**, frozen for the batch like the node head. All three 1D engines
+publish `nodes.conc`, the reaction system its node concentrations, the age
+and heat modules their node states, so the coupling reads one array and is
+engine-independent; nothing is queued back, since the node's CSTR mix already
+takes the spill at the mixed concentration. An outfall discharging onto the
+mesh carries its published values through a per-cell mass-rate density that
+scatters exactly as its volume does. Water arriving this way, or through an
+inflow boundary, is not runoff the cell produced (§10.7). Every pathway is
+ledgered per species.
+
+
+
+## 10.5 Coverages
+
+Chapters 3 and 4 (@ref quality_ref_ch3_pollutant_buildup,
+@ref quality_ref_ch4_surface_washoff) describe buildup and washoff on a
+subcatchment through its land-use coverages. The mesh adopts the same
+convention: land uses are **not** redefined; a cell only says which of the
+model's `[LANDUSES]` cover it and by what percent, and the relations come
+from the same `[BUILDUP]` and `[WASHOFF]` tables.
+
+```
+[2D_COVERAGES]
+;; scope          LANDUSE      PERCENT  [LANDUSE PERCENT] ...
+*                 Residential  60       Commercial 25
+TAG  street       Street       100
+CELL 812          Park         100
+```
+
+The ladder is `*`, then `TAG`, then `CELL` (1-based), later scopes
+overriding earlier ones (@ref engine_manual_sect_2D_COVERAGES). A row
+**replaces** the whole coverage set for its scope rather than merging —
+exactly as a subcatchment's `[COVERAGES]` line does — so `CELL 812` above
+carries `Park` alone. Percentages per scope sum to at most 100; the
+remainder carries no land use. An unknown land use, a tag matching no cell,
+or a cell beyond the mesh is an open-time error, as is a model with no
+`[LANDUSES]` or no transported rows. The rows are **inert with a warning**
+under `[2D_OPTIONS] RAINFALL_MODE NONE` — no rain falls on the mesh, so the
+subcatchments own the surface — and when loadings or curb lengths are given
+without any coverage.
+
+**Ownership.** A subcatchment whose footprint is meshed and rained on already
+sends its own washoff to its outlet; cells under it that also carry coverages
+would load the same storm twice. At open, every covered cell whose centroid
+lies inside a subcatchment polygon that itself has `[COVERAGES]` is reported
+in **one** warning naming the subcatchments, and the run proceeds.
+
+
+![Figure 10-2](figures/png/quality_ch10_cell_buildup_washoff.png)
+
+*Figure 10-2 Buildup and washoff on one mesh cell: land-use slices, accrual, sweeping and the mass handed to the network*
+
+
+
+## 10.6 Buildup
+
+Buildup is held per (cell, land use, surface species) in **user mass per
+normalizer unit**, the quantity a subcatchment's store holds, where the
+normalizer is the covered land area or the covered curb length:
+
+| | | | |
+|---|---|---|---|
+| \f[N_{c,l} = f_{c,l}\,A_c \quad (\text{per area}), \qquad N_{c,l} = f_{c,l}\,L_{c} \quad (\text{per curb})\f] | | (10-4) | |
+
+with \f$f_{c,l}\f$ the coverage fraction, \f$A_c\f$ the cell area in acres
+or hectares and \f$L_c\f$ its curb length in project units. The functions
+are Chapter 3's, unchanged: power, exponential and saturation accrue through
+the inverse-days form the subcatchment step uses — the store is converted
+back to an equivalent age, the step added, the function re-evaluated — and
+`EXTERNAL` integrates its series rate, capped at the maximum. Accrual runs at
+the **runoff step**, right after the subcatchment surface-quality step, so
+cells and subcatchments share one calendar.
+
+The initial store follows the subcatchment rule. A `[2D_LOADINGS]` row
+(@ref engine_manual_sect_2D_LOADINGS), user mass per unit land area in the
+same scope grammar, seeds the store directly — for a per-curb land use it is
+converted by the cell's area-to-curb ratio. Without a row, the buildup
+function is evaluated at `[OPTIONS] DRY_DAYS`. A loading may name a pollutant
+or a reaction species; age and temperature do not build up. A land use whose
+buildup is `PER_CURB` needs a curb length on every cell it covers, from
+`[2D_CURB_LENGTH]` (@ref engine_manual_sect_2D_CURB_LENGTH), same scope
+ladder, length in project units; a covered cell without one is an
+**open-time error**, refused rather than silently given zero curb.
+
+
+
+## 10.7 Washoff
+
+The washoff laws of Chapter 4 need a **runoff rate** for the cell, and the
+right definition took two attempts. The one implemented is the cell's *net*
+outflow over the runoff step, per unit area:
+
+| | | | |
+|---|---|---|---|
+| \f[q_c = \frac{\max\!\left(0,\ V_{\mathrm{out},c} - V_{\mathrm{in},c}\right)}{A_c\,\Delta t_{\mathrm{runoff}}}\f] | | (10-5) | |
+
+where \f$V_{\mathrm{out}}\f$ is what left across the cell's faces, open
+boundary edges and drains to nodes, and \f$V_{\mathrm{in}}\f$ what arrived
+across faces, from node spills, outfall discharge, prescribed inflow and
+inflow boundaries — accumulated by the marcher at every site the species
+ledgers already book, so the water side and the runoff side cannot disagree.
+Rainfall is *generation*, not inflow, and is not subtracted; infiltration is
+not runoff and is not added. By continuity the positive part is rain excess
+plus storage release — the runoff the cell **itself** produced, the analogue
+of the subcatchment's outflow over area: zero on a still pond, zero on a cell
+that only passes upstream water through, and independent of how finely a
+plane is meshed. A gross outward face flux was tried and withdrawn — it
+counts the same water once per cell it crosses — and rainfall excess alone
+rejected because it stops washing during the recession.
+
+Each covering land use then applies its own relation per surface species,
+with the subcatchment step's unit conventions and minimum-runoff threshold:
+**`EXP`**, \f$W = C_1\, q_c^{\,C_2}\, B\, N\f$; **`RC`**,
+\f$W = C_1\,(q_c A_c)^{C_2}\f$; **`EMC`**, \f$W = C_{\mathrm{emc}}\, q_c A_c\f$.
+`EXP` and `RC` are capped at the buildup available; `EMC` is not, and where
+no buildup function exists the mass it removes is booked to the buildup
+ledger so the closure holds. BMP removal is taken before delivery. What
+remains is **added to the cell's species row** and booked to the washoff
+ledger, from where it advects with the following steps' water and reaches
+the 1D node through the tuple of §10.4; every law reduces the store. The
+washoff of step \f$n\f$ is computed from the runoff accumulated *during* step
+\f$n\f$ and enters the rows at its end, one runoff step behind the water
+that produced it, and a hydrograph's last washoff stays on the drying cell
+until the next event. Co-pollutant fractions are not mirrored on cells.
+
+
+
+## 10.8 Street Sweeping
+
+Sweeping follows the `[LANDUSES]` schedule — interval and removal per land
+use — with one *days since last swept* counter per (cell, land use). The
+counter advances by the runoff step on days that are **dry** and inside the
+season given by `[OPTIONS] SWEEP_START` and `SWEEP_END` (a season wrapping
+the year end is handled); when it reaches the interval it resets and a
+sweeping event removes, per surface species,
+
+| | | | |
+|---|---|---|---|
+| \f[\Delta B = B \cdot \frac{R_{\mathrm{removal}}}{100} \cdot \frac{E_{\mathrm{sweep}}}{100}\f] | | (10-6) | |
+
+with \f$R_{\mathrm{removal}}\f$ the land use's removal percentage and
+\f$E_{\mathrm{sweep}}\f$ the species' sweeping efficiency from `[WASHOFF]`,
+booking the removed mass to the sweeping ledger. This is the subcatchment
+rule with the cell index in place of the subcatchment index; both counters
+start at zero, so a cell and a subcatchment with the same land use sweep on
+the same day.
+
+
+
+## 10.9 MSX Species on the Surface
+
+Surface species are the **union** of the `[POLLUTANTS]` rows and the reaction
+system's species. `[BUILDUP]`, `[WASHOFF]`, `[LOADINGS]` and `[2D_LOADINGS]`
+accept a reaction species name as `[INITIAL_QUALITY]` and `[INFLOWS]` do,
+and the cell store is indexed by surface species from the outset —
+pollutants, then reaction species, the row order the policy fixes — so
+nothing in the arithmetic is pollutant-shaped. The one species-dependent
+input is the unit factor from concentration-mass to user mass: for a
+pollutant, the `[POLLUTANTS]` units as in Chapter 4; for a reaction species,
+its declared units — `MG` takes the mass conversion, `UG` a thousandth of
+it, anything else (`MMOL`, counts, dimensionless) is carried as-is, the
+pollutant `COUNTS` rule. Three pollutant-only mechanisms are deliberately
+not mirrored: co-pollutant fractions, rain concentration (reaction species
+rain in clean), and kinetics inside the dry store — a built-up reaction
+species is inert until washed into water, where it reacts under the normal
+pipe-scope expressions per cell. The `WALL` and node-accumulator limits of
+§10.1 and §10.4 apply.
+
+
+
+## 10.10 Reporting
+
+**The `.rpt` file.** The transport matrix of §10.1 is printed in the header.
+When coverages are active, a **2D Surface Washoff Summary** follows the
+subcatchment summaries: one row per surface species with the initial
+buildup, net buildup, mass washed off into the cell rows, mass swept, BMP
+removal and the store still on the mesh, in user mass (a reaction species
+declared in `UG` or as a count keeps its own unit), with the cell and
+land-use counts and the per-acre or per-hectare basis in the heading;
+"washed off" is what entered the rows, not a node load.
+
+**The `.h5` results file.** The `REPORT_2D_VARIABLES` tokens `SPECIES` and
+`BUILDUP`, both in the `DEFAULT` set, add two time-indexed variables;
+`REPORT_2D_SPECIES` narrows the rows written and `REPORT_2D_STEP` sets the
+cadence. The `.out` format has no 2D record.
+
+| Variable | Shape | Units | Notes |
+|---|---|---|---|
+| `Mesh2_face_species_conc` | time × species × cell | species units | Created on the first step that carries rows; `species_names` lists the rows written; `__WATER_AGE__` in hours |
+| `Mesh2_face_buildup` | time × species × cell | user mass per acre or hectare | Pollutant and reaction-species rows; `species_names` and `units` attributes |
+
+**The C API.** Coverage, loading and curb-length rows are readable and
+editable through `openswmm_sq2d.h`, sharing the file's parsers so the
+grammar exists once, and per-cell buildup is read with
+`swmm_2d_get_buildup_bulk`. Not in this release: a `Mesh2_face_washoff`
+variable, hotstart carry of the store and sweeping counters, per-species
+continuity rows for the mesh in the `.rpt` (the 2D continuity block reports
+water only), and Python and MCP mirrors of the coverage API.
+
+
+
+## 10.11 Alternatives
+
+| Formulation | Status | Where it stands |
+|---|---|---|
+| Mass-form state, donor-cell advection on the marcher's face fluxes (S1) | \status{Implemented} | The only advection scheme on the mesh |
+| Isotropic explicit dispersion with the max-principle limiter (S2) | \status{Implemented} | `[2D_OPTIONS] DISPERSION`; binds counted and warned |
+| Initial and boundary species; rainfall and evaporation rules (S2) | \status{Implemented} | §10.3, §10.2.5 |
+| 1D↔2D species, age and temperature tuple (S3) | \status{Implemented} | §10.4; reaction-species drain not received by the node |
+| Age, temperature and per-cell reactions (S4) | \status{Implemented} | §10.2.6 |
+| Cell coverages, buildup, washoff and sweeping (S7) | \status{Implemented} | §10.5–10.8; the meshed-vs-lumped band gate is open |
+| Reaction species that build up and wash off (BW-MSX) | \status{Implemented} | §10.9 |
+| Limited second-order advection on the mesh | \status{Planned} | The plan placed it in S2 behind the 1D key names |
+| Anisotropic dispersion tensor | \status{Planned} | Deferred until a field case shows the difference |
+| Per-cell surface heat fluxes and shading (S5), then a cell-resolved bed layer | \status{Planned} | The `CELL2D` token exists; no flux evaluation on cells |
+| GPU transport kernels (S6) | \status{Planned} | Rows run on the CPU marcher |
+| `WALL` species on the mesh; node-side MSX inflow accumulator; kinetics in the built-up store | \status{Planned} | Recorded seams of §10.1, §10.4 and §10.9 |
+| `Mesh2_face_washoff`, hotstart carry, 2D species continuity rows | \status{Planned} | §10.10 |
+
+
+
+## 10.12 Implementation
+
+The transport state is `src/engine/2d/data/SurfaceTransportState.hpp`; the
+species flux, dispersion, sinks and sources are booked inside the marcher,
+`src/engine/2d/solver/ExplicitInertialSolver.cpp` (`bookFaceSpecies`,
+`sinkMassAtCellConc`, `addRainMass`, `sinkIntensiveRowsWithEvap`,
+`addCouplingSourceMass`). The router, `src/engine/2d/SurfaceRouter2D.cpp`,
+sizes the rows from the policy, resolves the initial and boundary rows,
+publishes the node row values, hands the drained tuple to the 1D queues and
+runs the aging and reaction stage. The policy is
+`src/engine/transport/TransportPolicy.cpp`. Coverages, buildup, washoff and
+sweeping are `src/engine/2d/quality/SurfaceQuality2D.cpp`, stepped from
+`SWMMEngine::stepRunoff` after the subcatchment and reaction-species surface
+steps (`src/engine/quality/MsxSurfaceQuality.cpp`). The `.h5` variables are
+written by `src/engine/2d/output/Default2DOutputPlugin.cpp`, the `.rpt`
+blocks by `src/engine/plugins/DefaultReportPlugin.cpp`.
+
+
diff --git a/docs/manuals/reference/quality/sections/Chapter11-PlannedFormulations.md b/docs/manuals/reference/quality/sections/Chapter11-PlannedFormulations.md
new file mode 100644
index 000000000..48174a47b
--- /dev/null
+++ b/docs/manuals/reference/quality/sections/Chapter11-PlannedFormulations.md
@@ -0,0 +1,218 @@
+@page quality_ref_ch11_planned Chapter 11: Planned Formulations
+
+@tableofcontents
+
+**Nothing in this chapter is complete in this release.** \status{Planned}
+The formulations below are recorded because a modeller will meet their
+traces — a section the parser accepts and warns about, an option key that is
+stored but reaches nothing, a component id the registry knows by name — and
+the manual should say plainly what each trace means. Where a design record
+exists it is cited; where only a roadmap entry exists, that is said too.
+Every statement of "parsed but inert" is made against the parser and the
+consumer that does not exist.
+
+| Formulation | Status | What exists today | What is missing |
+|---|---|---|---|
+| Sediment transport (§11.1) | \status{Planned} | A roadmap scope statement | Design record, sections, kernel |
+| Groundwater transport (§11.2) | \status{Planned} | Six `[GW_*]` sections parsed, validated and written back; a design plan | The transport kernel and the component that hosts it |
+| Finite-volume species transport on `[POLLUTANTS]` (§11.3) | \status{Planned} | Contact-upwinded, flux-corrected species kernels verified on their own gates | The connection to the project's species; `FV_DISPERSION` is inert |
+| Per-element heat attributes — constants per tag, link or node, and climate per element through the API (§11.4) | \status{Implemented} | Parsed, resolved, honoured by every flux evaluator, written back | — |
+| Per-element heat attributes — time series, computed shading, scoped API and GUI (§11.4) | \status{Planned} | The identity plumbing the constants ride on | Series resolution, a shade model, the editor table |
+| The five later-phase `[REACTION_*]` sections (§11.5) | \status{Planned} | Recognised by name and refused with their phase | Sources, per-element parameters, patterns, report selection, subcatchment scope |
+
+
+
+## 11.1 Sediment Transport
+
+Sediment is a planned theme of the engine roadmap and nothing more yet: there
+is **no design record** in the transport plans and no code. The roadmap's
+scope, quoted so that the reader knows what "planned" covers, is overland
+erosion (USLE/RUSLE or physically based detachment driven by rainfall and
+runoff shear), bedload and suspended-load routing in channels and pipes by
+empirical or process-based closures, multi-fraction particle sizes including
+cohesive material, deposition in basins, ponds and low-velocity reaches, and
+coupling to the water-quality transport so that particle-bound constituents
+ride the sediment. None of those items has been scoped against the engine's
+transport representations — the tanks-in-series, Eulerian and Lagrangian
+engines of Chapters 5 and 7 or the mesh of Chapter 10 — and no section, key
+or warning refers to sediment in this release. The bed *zone* of §9.3.11 is
+a heat and solute exchange layer, not a sediment store, and should not be
+read as a first step toward this item.
+
+
+
+## 11.2 Groundwater Transport
+
+The engine accepts six `[GW_*]` sections that configure solute, reaction
+species, age and temperature transport in a spatially explicit two-zone
+aquifer beneath the 2D mesh: @ref engine_manual_sect_GW_TRANSPORT_OPTIONS,
+@ref engine_manual_sect_GW_TRANSPORT_PARAMS, @ref engine_manual_sect_GW_SORPTION,
+@ref engine_manual_sect_GW_INITIAL_QUALITY,
+@ref engine_manual_sect_GW_BOUNDARY_QUALITY and
+@ref engine_manual_sect_GW_SOURCES. The rows are parsed, validated at open —
+species and time-series names, cell and tag references, an `XY` source
+snapped to the nearest cell centroid, duplicate source names refused rather
+than last-wins — kept, and written back unchanged on save. **No kernel
+consumes them.** A model that carries any of them receives this warning once:
+
+> [GW_*] subsurface transport is AUTHORED but INERT this run: the integrated
+> 2D groundwater component (org.hydrocouple.openswmm.integrated2d) provides
+> the two-zone kernel these sections configure and is not available in this
+> release. The rows are validated, kept and written back unchanged.
+
+The component id named in that warning, `org.hydrocouple.openswmm.integrated2d`,
+is a *planned* entry in the process-component registry: a
+`[PROCESS_COMPONENTS]` row naming it does not fail as an unknown id but is
+refused with a diagnostic naming the phase it arrives with. The same registry
+convention gives the reactions, ARD, LARD, heat and water-age components
+their ids, and it is how a deck written against the design can be recognised
+before the implementation lands.
+
+What the groundwater domain does today is recorded by the transport policy of
+§10.1: every species class reads *unavailable* there, with the reason. For
+pollutants the legacy aquifer supplies a constant groundwater concentration at
+the node seam on positive groundwater flow only, and exfiltration carries
+nothing; for age and temperature the aquifer is a source volume — new water
+enters at age zero and at the `GW` source temperature of `[HEAT_SOURCES]`.
+
+The design (2026-09-04, amended 2026-09-07 for the mixed
+triangle/quadrilateral mesh) is summarized here. Its saturated
+zone carries mass \f$M_s = n\,h_g\,A\,C\f$ and solves the retarded
+advection–dispersion equation on the kernel's own Darcy face fluxes,
+
+| | | | |
+|---|---|---|---|
+| \f[R_f\,\frac{\partial (n h_g C)}{\partial t} = -\nabla\cdot(\mathbf{q}\,C) + \nabla\cdot(n h_g D\,\nabla C) + S_C - \lambda\, n h_g C, \qquad R_f = 1 + \frac{1-n}{n}\,\rho_s K_d\f] | | (11-1) | |
+
+with a hydrodynamic dispersion \f$D = D_m + \alpha_L |v|\f$ and the sorbed
+phase folded into the retardation rather than carried as a second species.
+The unsaturated zone is a well-mixed store under the kernel's closure A and
+a column of \f$\sigma\f$-layers advected by the kernel's moving-grid fluxes
+under closure B. Heat uses effective properties from the actual moisture
+state, \f$(\rho c)_{\mathrm{eff}} = \theta \rho_w c_w + (1-n)\rho_s c_s\f$,
+with conduction, a geothermal boundary and latent removal at
+evapotranspiration; age is an ordinary species slot; reaction species run
+the shared integrator per aquifer cell under a new `SUBSURFACE` scope. Every
+water flux the kernel moves — infiltration, recharge, capillary rise, return
+flow, node and conduit exchange — carries the donor's tuple, which is the
+rule the surface coupling of §10.4 already follows. The degenerate
+`PER_SUBCATCH` mode, one column per subcatchment, is what would replace the
+constant groundwater columns above on a network-only model.
+
+
+
+## 11.3 Finite-Volume Species Transport Wired to `[POLLUTANTS]`
+
+The finite-volume routing solver of the Hydraulics Reference Manual (Chapter
+8, §8.8) carries a species transport layer at *scheme level*: the species
+flux is the same mass flux the water used, upwinded on the HLLC contact
+speed so that solute mass is conserved exactly and a uniform field stays
+uniform through reversal, wetting and drying; `UPWIND`, `MUSCL` and
+`QUICKEST_ULTIMATE` reconstructions are limited by Zalesak's flux-corrected
+transport so the discrete maximum principle holds; and longitudinal
+dispersion is treated implicitly, one tridiagonal solve per cell chain, so
+the parabolic step limit never binds. When species are carried the solver
+stands local time stepping down, because the limiter bounds a cell against
+the extrema of its whole neighbourhood in one synchronous sweep and a tiered
+correction would be a new scheme. The kernels live in
+`src/engine/transport/fvkernels/` and are verified on the solver's own
+analytic gates.
+
+What is missing is the wiring. The router sizes the finite-volume state with
+**zero species rows** — `fv_state_.resize(nc, nn, 0)` — so no `[POLLUTANTS]`
+row, land-use load, inflow or treatment ever reaches the mesh, and under
+`FLOW_ROUTING FV` water quality is routed by the `QUALITY_SOLVER` engines of
+Chapters 5 and 7 as it is under dynamic wave. Three consequences follow, and
+the engine states each of them at open rather than leaving a calibrated deck
+to discover them:
+
+- `[OPTIONS] FV_DISPERSION` is parsed and stored, converted to internal units
+  exactly as the honoured `FV_*` lengths are, and then reaches nothing; a
+  non-zero value raises the *FV option inert* warning naming the key.
+- `FV_SCALAR_SCHEME` set to anything but its default raises the same warning.
+- Under `QUALITY_SOLVER EULERIAN_ARD` a non-zero `FV_DISPERSION` additionally
+  warns that the Eulerian engine reads its dispersion from the transport
+  component (`[TRANSPORT_OPTIONS] DISPERSION` and `[CONDUIT_DISPERSION]`,
+  Chapter 7 §7.3.3) and applies nothing from this key.
+
+The open design questions the roadmap records are how `QUALITY_SOLVER` would
+select finite-volume transport beside the three engines that exist, how the
+species rows would take their loads through the loader seam every other
+engine shares, and how cell-resolved concentrations would be reported.
+Unifying the `FV_*` and transport-component option surfaces is the phase the
+warning above names.
+
+
+
+## 11.4 Per-Element Heat Attributes
+
+Chapter 9 documents the radiative and bed-zone parameters as one number per
+model. Shading, sky view, land-cover emissivity and temperature, burial
+depth, ground temperature and hyporheic velocity are properties of *a place*,
+and collapsing them to a scalar removes the spatial signal a heat model
+exists to produce. The per-element program (2026-09-01) makes them
+specifiable per element, with the per-element value overriding the global.
+
+**Landed (PE1, PE2, PE4 — validated and committed 2026-09-01).** Every flux
+evaluator takes an element identity, so the same physics can be handed a
+different configuration per call. In `[RADIATIVE_FLUXES]` the rows `ALBEDO`,
+`SHADE_FACTOR`, `SKY_VIEW`, `EMISS_WATER`, `EMISS_LANDCOVER` and
+`LANDCOVER_TEMPERATURE` accept the scopes `GLOBAL`, `TAG name`, `LINK name`
+and `NODE name`; `SHORTWAVE`, `ATM_EMISS_COEFF` and `ATM_LW_REFLECTION` stay
+`GLOBAL` because they describe the incident resource and the atmosphere, not
+the reach. In `[SEDIMENT_EXCHANGE]` the bed attributes accept `GLOBAL`, `TAG`
+and `LINK`; `NODE` is refused because the bed zone exists beneath conduits
+only, and `INITIAL_TEMPERATURE` is the bed's own seed and stays `GLOBAL`.
+Precedence is `GLOBAL` under `TAG` under the named element; two rows at the
+same scope for the same target are refused rather than letting one silently
+win; global and per-element values pass one validator. Air temperature,
+humidity, wind and incident shortwave remain global in the deck and can be
+pushed per element only through the runtime forcing API, which is where a
+coupled shade or atmospheric model belongs. A deck with no override rows is
+byte-identical to one written before the program.
+
+**Open (PE3, PE5, PE6).** Per-element `TIMESERIES` spellings of the same
+attributes; computed shading from sun position and bank vegetation, for which
+the recommendation on record is *not to build* — a prescribed `SHADE_FACTOR`
+series covers the seasonal case at a fraction of the cost; the scoped C API
+getters and setters and the GUI's per-element table; per-element
+wind-function coefficients; and the `CELL2D` scope that would let the 2D
+surface of Chapter 10 take per-cell shading — the element token exists, the
+flux evaluation on cells does not (§10.11).
+
+
+
+## 11.5 Later-Phase `[REACTION_*]` Sections
+
+The reaction component recognises twelve section names (Chapter 8 §8.2).
+Seven are consumed. The other five are **recognised and refused** with the
+phase that delivers them — never silently accepted, because a section that
+parses without effect is a modelling error that looks like a working model:
+
+| Section | Refusal names phase | Intended meaning |
+|---|---|---|
+| `[REACTION_SOURCES]` | R-sources (post-R3) | Species mass or concentration sources at nodes, in the EPANET-MSX convention |
+| `[REACTION_PARAMETERS]` | R-parameters (post-R3) | Per-conduit and per-node overrides of `PARAMETER` coefficients |
+| `[REACTION_PATTERNS]` | R-sources (post-R3) | Time patterns that modulate sources |
+| `[REACTION_REPORT]` | R5 | Selection of species and elements to report |
+| `[REACTION_SUBCATCHMENTS]` | R6 | Subcatchment-scope expressions — an OpenSWMM extension with no MSX counterpart |
+
+The refusal is an **error**, not a warning: a configuration file carrying any
+of the five is rejected as a whole, so a deck cannot run with half of its
+reaction system honoured. An unknown `[REACTION_*]` name is rejected on the
+same terms, as a probable typo. Two of the planned sections already have
+working substitutes: under the Eulerian ARD component, `[TRANSPORT_BOUNDARIES]`
+and `[TRANSPORT_SOURCES]` (Chapter 7 §7.5) address reaction species at nodes
+and along conduits, including negative rates for extraction, and `[INFLOWS]`
+rows may name a reaction species. `[REACTION_PARAMETERS]` has none — every
+`PARAMETER` coefficient is a single value for the whole model today, which is
+why Chapter 8's declarations subsection treats `PARAMETER` and `CONSTANT` as
+synonyms for now.
+
+A related refusal belongs in the same list: a `RATE`, `EQUIL` or `FORMULA`
+expression on a **pollutant** in `[REACTION_PIPES]` or `[REACTION_TANKS]` is
+refused with the note that pollutant kinetics arrive with phase R4b.
+Pollutants may be referenced read-only in reaction-species expressions, and
+their first-order `Kdecay` applies under every engine.
+
+
diff --git a/docs/manuals/reference/quality/sections/Chapter3-PollutantBuildup.md b/docs/manuals/reference/quality/sections/Chapter3-PollutantBuildup.md
index bef27e75f..398702196 100644
--- a/docs/manuals/reference/quality/sections/Chapter3-PollutantBuildup.md
+++ b/docs/manuals/reference/quality/sections/Chapter3-PollutantBuildup.md
@@ -91,7 +91,7 @@ figures.) Even in data collected as carefully as in the San Jose study,
 the scatter (not shown in the report) is considerable. Thus, the choice
 of the best functional form is not obvious.
 
-![](quality/media/media/image8.png "Sartor&Boyd.bmp")
+![](quality/media/media/quality-image8.png "Sartor&Boyd.bmp")
 
Figure 3‑1 Accumulation of solids on urban
 streets versus time (Sartor and Boyd, 1972)

@@ -104,7 +104,7 @@ previously in section 2.3. SWMM's Land Use object is used to identify a
 particular type of land use and to store the buildup (and washoff)
 functions for each SWMM Pollutant.
 
-![](quality/media/media/image9.png)
+![](quality/media/media/quality-image9.png)
 
 **Figure 3‑2 Buildup of street solids in San Jose (from Pitt, 1979)**
 
@@ -196,7 +196,7 @@ available at the beginning of any storm event.
 | *NB* | time exponent | | |
 
 
-![](quality/media/media/image10.png "image10")
+![](quality/media/media/quality-image10.png "image10")
 
Figure 3‑3 Comparison of buildup equations
 for a hypothetical pollutant

@@ -256,7 +256,7 @@ If a dry period of length *∆t* occurs before the start of the next
 storm, then the amount of buildup available, *b2*, is found by
 evaluating the buildup function at time *t2* = *t1* + *∆t*.
 
-![](quality/media/media/image11.png "image11")
+![](quality/media/media/quality-image11.png "image11")
 
Figure 3‑4 Evolution of buildup after a
 storm event

diff --git a/docs/manuals/reference/quality/sections/Chapter4-SurfaceWashoff.md b/docs/manuals/reference/quality/sections/Chapter4-SurfaceWashoff.md
index b1a3a7929..24e35461f 100644
--- a/docs/manuals/reference/quality/sections/Chapter4-SurfaceWashoff.md
+++ b/docs/manuals/reference/quality/sections/Chapter4-SurfaceWashoff.md
@@ -52,7 +52,7 @@ size and runoff rate. An analysis of the Sartor and Boyd (1972) data by
 Ammon (1979) indicates that *k* increases with runoff rate, as would be
 expected, and decreases with particle size.
 
-![](quality/media/media/image12.png "sartor and boyd washoff plots")
+![](quality/media/media/quality-image12.png "sartor and boyd washoff plots")
 
Figure 4‑1 Washoff of street solids by
 flushing with a sprinkler system (from Sartor and Boyd,
@@ -238,7 +238,7 @@ Rating Curve               850 (mg/sec)(cfs)-1.5           1.5
 
 EMC                        20 mg/L × 28.3 L/ft3            \-
 
-![](quality/media/media/image13.png "image13")
+![](quality/media/media/quality-image13.png "image13")
 
Figure 4‑2 Comparison of washoff
 functions

@@ -305,7 +305,7 @@ with the variables defined as follows:
 
 *Qout*       =   rate of runoff leaving the subcatchment (cfs).
 
-![](quality/media/media/image14.png "image14")
+![](quality/media/media/quality-image14.png "image14")
 
Figure 4‑3 Two-stream approach to modeling
 pollutant washoff

@@ -596,9 +596,9 @@ Washoff is higher for flows on the ascending limb of the hydrograph
 because there is higher buildup available and lower during the
 descending limb since there is less buildup present.
 
-![](quality/media/media/image15.png)   ![](quality/media/media/image16.png)
+![](quality/media/media/quality-image15.png)   ![](quality/media/media/quality-image16.png)
 
-![](quality/media/media/image17.png) ![](quality/media/media/image18.png)
+![](quality/media/media/quality-image17.png) ![](quality/media/media/quality-image18.png)
 
 **Figure 4‑4 Simulated load variations within a storm as a function of runoff rate**
 
diff --git a/docs/manuals/reference/quality/sections/Chapter5-TransportAndTreatment.md b/docs/manuals/reference/quality/sections/Chapter5-TransportAndTreatment.md
index 1ea95242e..d78b53b30 100644
--- a/docs/manuals/reference/quality/sections/Chapter5-TransportAndTreatment.md
+++ b/docs/manuals/reference/quality/sections/Chapter5-TransportAndTreatment.md
@@ -27,7 +27,7 @@ water in each link and the volume of water within each storage node. The
 methods used to obtain this hydraulic solution are described in Volume
 II of this manual.
 
-![](quality/media/media/image2.png "Objects2")
+![](quality/media/media/quality-image2.png "Objects2")
 
Figure 5‑1 Representation of the
 conveyance network in SWMM

@@ -190,7 +190,7 @@ above 100 mg/L, which are not physically possible. These results support
 using the simple mixing equation 5-6 in place of the analytical solution
 for SWMM 5 as it provides accurate and robust water quality solutions.
 
-![](quality/media/media/image20.png "image20")
+![](quality/media/media/quality-image20.png "image20")
 
Figure 5‑3 Comparison of completely mixed
 reactor equations for a step inflow

@@ -651,7 +651,7 @@ at 100 mg/L and begins to settle out once the inflow ceases. As the pond
 depth decreases while it empties more solids settle out reducing the TSS
 level until the residual concentration of 20 mg/L is reached.
 
-![TreatmentExample.png](quality/media/media/image21.png)
+![TreatmentExample.png](quality/media/media/quality-image21.png)
 
 **Figure 5‑4 Gravity settling treatment of TSS within a detention pond**
 
@@ -751,5 +751,11 @@ mass-balance accounting are implemented in
 during quality initialization in `src/engine/core/SWMMEngine.cpp`, and
 the C API entry points are declared in @ref openswmm_quality.h.
 
-
-
+@note The transport model described in this chapter — one or more
+continuously stirred tanks per link — remains the default and is
+unchanged. OpenSWMM additionally provides two engines that resolve
+concentration *along* a conduit rather than treating it as fully mixed:
+an Eulerian finite-volume engine and a Lagrangian parcel-tracking
+engine, both described in @ref quality_ref_ch7_ard_transport. They are
+selected with `[OPTIONS] QUALITY_SOLVER` and share this chapter's
+external loads, treatment expressions and mass-balance ledger.
diff --git a/docs/manuals/reference/quality/sections/Chapter6-LowImpactDevelopmentControls.md b/docs/manuals/reference/quality/sections/Chapter6-LowImpactDevelopmentControls.md
index f2948e7a4..1016a7bcc 100644
--- a/docs/manuals/reference/quality/sections/Chapter6-LowImpactDevelopmentControls.md
+++ b/docs/manuals/reference/quality/sections/Chapter6-LowImpactDevelopmentControls.md
@@ -25,15 +25,15 @@ SWMM 5 can explicitly model the following types of LID practices:
 
 | LID Control Type | Description | Image |
 |---|---|---|
-| **Bio-retention Cells** | Depressions that contain vegetation grown in an engineered soil mixture placed above a gravel storage bed. They provide storage, infiltration and evaporation of both direct rainfall and runoff captured from surrounding areas. Street planters and bio-swales are common examples of bio-retention cells. | ![StreetPlanter](quality/media/media/image22.png) |
-| **Rain Gardens** | A type of bio-retention cell consisting of just the engineered soil layer with no gravel bed below it. | ![RainGarden](quality/media/media/image23.png) |
-| **Green Roofs** | Another variation of a bio-retention cell that have a soil layer above a thin layer of synthetic drainage mat material or coarse aggregate that conveys excess water draining through the soil layer off of the roof. | ![GreenRoof](quality/media/media/image24.png) |
-| **Infiltration Trenches** | Narrow ditches filled with gravel that intercept runoff from upslope impervious areas. They provide storage volume and additional time for captured runoff to infiltrate into the native soil below. | ![InfilTrench](quality/media/media/image25.png) |
-| **Continuous Permeable Pavement** | Street or parking areas paved with a porous concrete or asphalt mix that sits above a gravel storage layer. Rainfall passes through the pavement into the storage layer where it can infiltrate into the site's native soil. | ![PermPavement2.png](quality/media/media/image26.png)|
-| **Block Paver** | Systems consist of impervious paver blocks placed on a sand or pea gravel bed with a gravel storage layer below. Rainfall is captured in the open spaces between the blocks and conveyed to the storage zone where it can infiltrate into the site's native soil. | ![BlockPavers.png](quality/media/media/image27.png) |
-| **Rain Barrels** (or **Cisterns**) | Containers that collect roof runoff during storm events and can either release or re-use the rainwater during dry periods. | ![cistern](quality/media/media/image28.png) |
-| **Rooftop Disconnection** | Has roof downspouts discharge to pervious landscaped areas and lawns instead of directly into storm drains. It can also model roofs with directly connected drains that overflow onto pervious areas. | ![](quality/media/media/image29.png) |
-| **Vegetative Swales** | Channels or depressed areas with sloping sides covered with grass and other vegetation. They slow down the conveyance of collected runoff and allow it more time to infiltrate into the native soil. | ![VegSwale](quality/media/media/image30.png)|
+| **Bio-retention Cells** | Depressions that contain vegetation grown in an engineered soil mixture placed above a gravel storage bed. They provide storage, infiltration and evaporation of both direct rainfall and runoff captured from surrounding areas. Street planters and bio-swales are common examples of bio-retention cells. | ![Bio-retention cell layer stack](figures/png/quality_ch6_lid_bio_cell.png) |
+| **Rain Gardens** | A type of bio-retention cell consisting of just the engineered soil layer with no gravel bed below it. | ![Rain garden layer stack](figures/png/quality_ch6_lid_rain_garden.png) |
+| **Green Roofs** | Another variation of a bio-retention cell that have a soil layer above a thin layer of synthetic drainage mat material or coarse aggregate that conveys excess water draining through the soil layer off of the roof. | ![Green roof layer stack](figures/png/quality_ch6_lid_green_roof.png) |
+| **Infiltration Trenches** | Narrow ditches filled with gravel that intercept runoff from upslope impervious areas. They provide storage volume and additional time for captured runoff to infiltrate into the native soil below. | ![Infiltration trench layer stack](figures/png/quality_ch6_lid_infiltration_trench.png) |
+| **Continuous Permeable Pavement** | Street or parking areas paved with a porous concrete or asphalt mix that sits above a gravel storage layer. Rainfall passes through the pavement into the storage layer where it can infiltrate into the site's native soil. | ![Continuous permeable pavement layer stack](figures/png/quality_ch6_lid_permeable_pavement.png)|
+| **Block Paver** | Systems consist of impervious paver blocks placed on a sand or pea gravel bed with a gravel storage layer below. Rainfall is captured in the open spaces between the blocks and conveyed to the storage zone where it can infiltrate into the site's native soil. | ![Block paver layer stack](figures/png/quality_ch6_lid_block_paver.png) |
+| **Rain Barrels** (or **Cisterns**) | Containers that collect roof runoff during storm events and can either release or re-use the rainwater during dry periods. | ![Rain barrel layer stack](figures/png/quality_ch6_lid_rain_barrel.png) |
+| **Rooftop Disconnection** | Has roof downspouts discharge to pervious landscaped areas and lawns instead of directly into storm drains. It can also model roofs with directly connected drains that overflow onto pervious areas. | ![Rooftop disconnection layer stack](figures/png/quality_ch6_lid_rooftop_disconnection.png) |
+| **Vegetative Swales** | Channels or depressed areas with sloping sides covered with grass and other vegetation. They slow down the conveyance of collected runoff and allow it more time to infiltrate into the native soil. | ![Vegetative swale layer stack](figures/png/quality_ch6_lid_vegetative_swale.png)|
                              
 
 Bio-retention cells, infiltration trenches, and permeable pavement
@@ -110,7 +110,7 @@ the soil zone above it and loses water by infiltration into the
 underlying natural soil and by outflow through a perforated pipe
 underdrain system if present.
 
-   ![planter.bmp](quality/media/media/image31.png)    ![](quality/media/media/image32.png)
+   ![planter.bmp](quality/media/media/quality-image31.png)    ![](quality/media/media/quality-image32.png)
                                          
                   **(A)**                                              **(B)**
 
@@ -529,7 +529,7 @@ roof's drain system (see Figure 6-2). When the depth of ponded water
 *d1* is at or below the depression storage depth *D1* then no
 surface outflow occurs.
 
-![](quality/media/media/image33.png)
+![](quality/media/media/quality-image33.png)
 
 **Figure 6‑2 Flow path across the surface of a green roof**
 
@@ -625,7 +625,7 @@ surface area taken up by the impermeable paver blocks and where the
 porosity and permeability refer to the fine gravel used to fill the
 seams between blocks. For continuous systems *F4* would be 0.
 
-![](quality/media/media/image34.png "image34")
+![](quality/media/media/quality-image34.png "image34")
 
Figure 6‑3 Representation of a permeable
 pavement system

@@ -829,7 +829,7 @@ dual drainage systems (both street flow and sewer flow), is to allow the
 overflow to contribute to the major (street) system and the roof drain
 flow to the minor (sewer) system.
 
-![](quality/media/media/image35.png "image35")
+![](quality/media/media/quality-image35.png "image35")
 
Figure 6‑4 Representation of rooftop
 disconnection

@@ -885,7 +885,7 @@ user-supplied surface area occupied by the swale across its full height
 constant surface area throughout all layers, this equation accounts for
 a varying surface area as the depth of water in the swale changes.
 
-![](quality/media/media/image36.png "image36")
+![](quality/media/media/quality-image36.png "image36")
 
Figure 6‑5 Representation of a vegetative
 swale

@@ -1150,7 +1150,7 @@ occupies its entire subcatchment. The inflow to LID1 comes from an
 upstream subcatchment and its surface overflow is routed to LID2. Its
 underdrain flow is sent to the same outlet location used by LID2.
 
-![LidOptions.png](quality/media/media/image37.png)
+![LidOptions.png](quality/media/media/quality-image37.png)
 
 **Figure 6‑6 Different options for placing LID controls**
 
@@ -1848,15 +1848,15 @@ surface inflow, soil layer percolation, and storage layer exfiltration.
 Figure 6-9 shows how the moisture level within each layer, as a
 percentage of its full storage capacity, varies with time.
 
-![](quality/media/media/image38.png)
+![](quality/media/media/quality-image38.png)
 
 **Figure 6‑7 Storm event used for the LID example**
 
-![](quality/media/media/image39.png)
+![](quality/media/media/quality-image39.png)
 
 **Figure 6‑8 Flux rates through the bio-retention cell with no underdrain**
 
-![](quality/media/media/image40.png)
+![](quality/media/media/quality-image40.png)
 
 **Figure 6‑9 Moisture levels in the bio-retention cell with no underdrain**
 
@@ -1932,11 +1932,11 @@ the total storm volume. If this flow is sent to a storm sewer which is
 typically the case, then the bio-retention cell can no longer be said to
 have fully captured and eliminated runoff from this 1-inch storm.
 
-![](quality/media/media/image41.png)
+![](quality/media/media/quality-image41.png)
 
 **Figure 6‑10 Moisture levels in the bio-retention cell with underdrain**
 
-![](quality/media/media/image42.png)
+![](quality/media/media/quality-image42.png)
 
 **Figure 6‑11 Flux rates through the bio-retention cell with underdrain**
 
diff --git a/docs/manuals/reference/quality/sections/Chapter7-AdvectionReactionDispersion.md b/docs/manuals/reference/quality/sections/Chapter7-AdvectionReactionDispersion.md
new file mode 100644
index 000000000..7c2e0ea56
--- /dev/null
+++ b/docs/manuals/reference/quality/sections/Chapter7-AdvectionReactionDispersion.md
@@ -0,0 +1,353 @@
+@page quality_ref_ch7_ard_transport Chapter 7: Advection–Reaction–Dispersion Transport
+
+@tableofcontents
+
+## 7.1 Introduction
+
+Chapter 5 describes the transport model SWMM has always used: each conduit is
+treated as a continuously stirred tank reactor (CSTR), or optionally as a
+short series of them. That model is robust and inexpensive, and it is exact
+for the quantity it tracks — the mass leaving a link over a routing step — but
+it carries no information about *where inside the link* mass is. A slug
+entering a long conduit appears at the outlet immediately, diluted across the
+whole link volume, rather than travelling down it as a front.
+
+OpenSWMM adds two transport engines that resolve position along a conduit, and
+retains the original as the default. They are selected per model with the
+`[OPTIONS] QUALITY_SOLVER` key:
+
+| `QUALITY_SOLVER` | Engine | Representation |
+|---|---|---|
+| `LEGACY` (default) | Tanks-in-series | One or more CSTRs per link (Chapter 5) |
+| `EULERIAN_ARD` | Eulerian finite volume | Fixed cells along each conduit |
+| `LAGRANGIAN` | Lagrangian (LARD) | Water parcels that move with the flow |
+
+All three engines share the same external loads, the same treatment
+expressions, the same mass-balance ledger and the same reporting surfaces. A
+model can be switched between them without editing anything but the one key,
+which is what makes the comparison meaningful: differences in results are
+differences in the transport representation, not in the problem being solved.
+
+**The default is unchanged.** A model that does not set `QUALITY_SOLVER`
+behaves exactly as it did before, bit for bit.
+
+## 7.2 Governing Equation
+
+Both new engines solve the one-dimensional advection–reaction–dispersion
+equation, which is Chapter 5's Equation 5.1 with the dispersion term retained
+rather than absorbed into the tank model:
+
+\f[\frac{\partial c}{\partial t} = -\frac{\partial(uc)}{\partial x} + \frac{\partial}{\partial x}\left(D\frac{\partial c}{\partial x}\right) + r(c)\f]
+
+where \f$c\f$ is concentration, \f$u\f$ the cross-sectionally averaged
+velocity, \f$D\f$ the longitudinal dispersion coefficient, and \f$r(c)\f$ the
+reaction rate. The three terms are advection, dispersion and reaction, and the
+two engines differ chiefly in how they treat the first.
+
+The equation is solved by **operator splitting**: within a transport step,
+advection is applied first and dispersion second, each as a complete step
+(a Lie, or first-order, split). Reaction is applied afterwards. The splitting
+error is therefore \f$O(\Delta t)\f$ rather than the \f$O(\Delta t^2)\f$ a
+symmetric Strang split would give. This is a deliberate choice rather than an
+accuracy claim: the advective substep is already limited by a Courant
+condition, and the dispersion solve is unconditionally stable, so the
+first-order split costs little and keeps the sequence simple to reason about.
+
+## 7.3 The Eulerian Engine (ARD)
+
+### 7.3.1 Spatial discretization
+
+Each conduit is divided into a fixed number of cells of length
+\f$\Delta x\f$, sized at initialization from the conduit length and the
+`[TRANSPORT_OPTIONS] TARGET_DX` key. Node storage is represented separately;
+cells hold only conduit water. Species are stored species-major, so all cells
+of one species are contiguous — the layout the flux kernels sweep.
+
+Cell wetted area is taken from the hydraulic solution each routing step, so
+the transport mesh always describes the same water the hydraulic engine
+routed. A cell whose area falls below a dryness threshold is skipped rather
+than divided by, and its mass is held rather than discarded.
+
+### 7.3.2 Advection
+
+Face fluxes are computed with a **flux-limited high-resolution scheme**. A
+first-order upwind flux is computed for stability, a higher-order correction
+is computed for accuracy, and the correction is limited so that the result
+introduces no new extrema — the flux-corrected transport idea, applied here in
+the form Leonard describes for conservative advection schemes
+(Leonard, 1991). Without limiting, a second-order scheme produces oscillations
+ahead of and behind a sharp front, which for a concentration means values
+below zero.
+
+The scheme is selected with `[TRANSPORT_OPTIONS] SCALAR_SCHEME` and the
+limiter with `LIMITER`:
+
+| Key | Value | Behaviour |
+|---|---|---|
+| `SCALAR_SCHEME` | `UPWIND` | First-order upwind alone — monotone, strongly diffusive |
+| | `MUSCL` | Second-order reconstruction with limiting (default) |
+| `LIMITER` | `MINMOD` | Most diffusive of the limited options; safest on rough data |
+| | `VANLEER` | Smooth, symmetric; the usual default |
+| | `SUPERBEE` | Least diffusive; sharpens fronts, can over-steepen smooth profiles |
+
+A useful way to read the table: `UPWIND` never produces a value outside the
+range of its neighbours but smears a sharp front over many cells;
+`SUPERBEE` keeps the front nearly intact but will convert a smooth gradient
+into a staircase. `VANLEER` is between them and is what a model should use
+unless a specific reason argues otherwise.
+
+Figure 7-1 shows the face stencil and what each choice does to a step
+front after sixty cells of travel: the ordering of the table, made
+visible.
+
+![Figure 7-1](figures/png/quality_ch7_ard_stencil.png)
+
+*Figure 7-1 Flux-limited advection in the Eulerian engine: the face stencil and a step front under UPWIND and the three MUSCL limiters*
+
+The advective step is subcycled to satisfy a Courant condition
+
+\f[C = \frac{u\,\Delta t_{sub}}{\Delta x} \le C_{max}\f]
+
+with the substep count chosen so the condition holds in every wet cell. The
+subcycling is internal to the transport step; the hydraulic solution is frozen
+across it, which means refining the transport step refines transport alone.
+
+**A worked example.** A 400 ft conduit at `TARGET_DX = 50` ft has eight
+cells. Water moving at 4 ft/s over a 60 s routing step covers 240 ft — nearly
+five cells — so a single explicit step would be violently unstable. The
+engine computes \f$C = 4 \times 60 / 50 = 4.8\f$, and with
+\f$C_{max} = 0.9\f$ takes \f$\lceil 4.8/0.9 \rceil = 6\f$ substeps of
+10 s each. Nothing in the deck changes; the cost is six flux sweeps instead
+of one. Halving `TARGET_DX` doubles both the cell count and the substep
+count, so refinement is quadratic in cost — which is why `TARGET_DX` is the
+key worth thinking about before reaching for a shorter routing step.
+
+### 7.3.3 Dispersion
+
+The dispersion term is solved implicitly along each conduit chain with a
+tridiagonal (Thomas) solve, which is unconditionally stable and so places no
+additional restriction on the step size. Chains span splice junctions, so a
+conduit interrupted by a virtual junction disperses as one length rather than
+as two.
+
+The coefficient \f$D\f$ is set by `[TRANSPORT_OPTIONS] DISPERSION`:
+
+| Mode | Coefficient |
+|---|---|
+| `OFF` (default) | \f$D = 0\f$; the dispersion solve is skipped entirely |
+| `VALUE` | A single user-supplied \f$D\f$, in ft²/s or m²/s |
+| `FISCHER` | Computed per conduit from the local hydraulics |
+
+The `FISCHER` closure follows the shear-flow dispersion relations collected by
+Fischer et al. (1979), which build on Taylor's analysis of dispersion in a
+tube (Taylor, 1953) and Elder's extension to open-channel shear:
+
+\f[D = 0.011\,\frac{u^2 B^2}{Y\,u_*}, \qquad u_* = \sqrt{g Y S}\f]
+
+with \f$B\f$ the surface width, \f$Y\f$ the mean depth, \f$S\f$ the
+friction slope and \f$u_*\f$ the shear velocity. The coefficient is
+recomputed each step from the current hydraulics, so it responds to a
+rising limb rather than describing one design condition.
+
+In a shear-dominated open channel, mechanical dispersion arising from the
+velocity profile exceeds molecular diffusion by several orders of magnitude,
+so the coefficient is a property of the flow field rather than of the
+transported substance — which is why the same coefficient is applied to every
+species, including temperature (§9.4).
+
+**Magnitudes worth recognising.** For the 1.5 ft pipe at 4 ft/s used above,
+flowing half full, \f$D\f$ from the Fischer closure lands in the range of a
+few ft²/s. Molecular diffusion of a dissolved solute is around
+\f$10^{-8}\f$ ft²/s — eight orders of magnitude smaller, which is why no
+mode of this key offers it. A user-supplied `VALUE` far below 0.1 ft²/s is
+almost always a unit error rather than a modelling choice.
+
+When `DISPERSION OFF` is in effect the dispersion kernel is not merely passed
+a zero coefficient; it is not entered at all, so results are identical to a
+build without the dispersion path.
+
+## 7.4 The Lagrangian Engine (LARD)
+
+The Lagrangian engine represents each conduit as an ordered slab of water
+**parcels** — segments with a volume and a concentration — that move with the
+flow rather than past a fixed mesh. Numerical diffusion of a front is
+therefore not introduced by the advection scheme at all: a parcel carries its
+concentration unchanged until it mixes.
+
+Each transport step proceeds in five phases:
+
+1. **Drain.** Every conduit sends the volume that left it over the step, taken
+   from its downstream end, into its receiving node's inflow ledger, carrying
+   the corresponding mass. A link whose volume has fallen below its remaining
+   parcel volume sheds the difference through its upstream face, so the parcel
+   volumes always sum exactly to the link volume the hydraulic engine reports.
+2. **Mix.** Nodes are processed in flow-aware topological order. Each node
+   mixes its own held volume with everything that arrived, as a CSTR — the
+   same formula junctions, dividers, storage units and outfalls all reduce to.
+   External loads join here, through the same loader seam the other two
+   engines use. Zero-volume links (pumps, orifices, weirs, outlets) pass the
+   node's *new* concentration through within the same step, which is why the
+   ordering must be topological.
+3. **Release.** Each conduit gains a new parcel at its upstream node's new
+   concentration, sized so the slab total again equals the link volume.
+   Adjacent parcels whose concentrations agree within a tolerance are merged,
+   which is what keeps plug flow from growing an unbounded number of parcels.
+4. **Decay.** First-order decay is applied to parcels and node stores by exact
+   exponential, and the removed mass is booked to the reacted ledger row.
+5. **Publish.** Link concentration is reported as the volume-weighted mean of
+   the parcels, so outfall loads and final-storage accounting see the same
+   mass the parcels hold.
+
+Cycles in the node ordering are broken in index order, and the residue is
+carried in the ledger to the next step rather than dropped.
+
+Figure 7-2 follows one conduit's slab through the five phases.
+
+![Figure 7-2](figures/png/quality_ch7_lard_parcels.png)
+
+*Figure 7-2 The five phases of a Lagrangian transport step: drain, mix, release, decay and publish on one conduit's parcel slab*
+
+**The parcel budget is what makes this tractable.** Left alone, a conduit
+under steady flow gains one parcel per step forever. Two mechanisms bound it:
+adjacent parcels whose concentrations agree within a tolerance are merged at
+the RELEASE phase, and `[OPTIONS] MAX_SEGMENTS_PER_LINK` (default 100) caps
+the slab, with the oldest parcels merged when the cap is reached. Under plug
+flow with a constant inlet concentration, merging collapses the whole link
+back to a single parcel every step and the cost is trivial; under a rapidly
+varying inlet, the cap is what stops the memory growing without limit — at
+the price of blending the oldest resolution first, which is the right end to
+lose.
+
+`[OPTIONS] QUALITY_STEP` substeps the whole five-phase sequence within a
+routing step. Unlike the ARD subcycling above, this is user-chosen rather
+than derived from a stability condition: LARD has no Courant limit, because
+parcels move with the flow rather than past a mesh. The key exists for
+accuracy of the node mixing, not for stability, and omitting it (or setting
+it at or above the routing step) degenerates to a single substep and is
+bit-identical to a model that never set it.
+
+### 7.4.1 Dispersion under LARD
+
+Because parcels do not exchange mass by construction, dispersion under LARD is
+introduced explicitly, by a **random-walk particle method**: particles sample
+the vertical shear profile to estimate inter-parcel exchange, and the estimated
+exchange is applied to the parcel field. Particles carry no mass themselves —
+they are an instrument for estimating the exchange coefficient, not a second
+representation of the solute. The random draw is keyed by a deterministic seed
+(`[OPTIONS] RWPT_SEED`), so a model gives the same answer on every run and on
+every machine.
+
+## 7.5 Boundaries, Sources and Extraction
+
+Two sections supply species mass directly to the transport domain, independent
+of the hydraulic inflows:
+
+- **`[TRANSPORT_BOUNDARIES]`** sets the concentration carried by water
+  entering at a node.
+- **`[TRANSPORT_SOURCES]`** applies a distributed mass rate along a conduit,
+  spread over its cells in proportion to cell length.
+
+A **negative** rate denotes *extraction* rather than an error. Extraction is
+clamped to the mass the element actually holds, so a request larger than the
+available mass removes what is there and no more; the unmet portion is counted
+and summarized at the end of the run rather than silently satisfied by driving
+a concentration negative. Extraction clamps routinely while a system fills —
+a near-empty element cannot satisfy any withdrawal — so a nonzero clamp count
+is not by itself a modelling error.
+
+Both sections address **multi-species reaction species** (Chapter 8) rather
+than `[POLLUTANTS]` rows, which take their loads through the ordinary
+`[INFLOWS]` and washoff pathways. A worked pair:
+
+```
+[PROCESS_COMPONENTS]
+org.hydrocouple.openswmm.transport.ard  config="model.ard"
+```
+
+and in `model.ard`:
+
+```
+[TRANSPORT_OPTIONS]
+DISPERSION        FISCHER
+TARGET_DX         50
+SCALAR_SCHEME     MUSCL
+LIMITER           VANLEER
+
+[TRANSPORT_BOUNDARIES]
+J0   CL2   VALUE       1.2          ; mg/L on water entering at J0
+J4   CL2   TIMESERIES  TS_PLANT     ; a measured plant residual
+
+[TRANSPORT_SOURCES]
+C7   CL2   VALUE      -0.004        ; a withdrawal, 4 mg/s along C7
+```
+
+A boundary sets the concentration carried by water **entering** at a node; a
+source injects (or, negative, extracts) mass along a conduit independent of
+its flow. Per-conduit dispersion overrides live in the same file and win over
+the global model on the conduits they name.
+
+One `[OPTIONS]` key governs what an outfall hands back to the network when
+flow reverses — a tidal boundary, or a downstream surcharge pushing water up
+the last conduit. `OUTFALL_BACKFLOW_QUALITY` takes `LAST` or `ZERO`
+(@ref engine_manual_sect_OPTIONS). Under `LAST`, the default and the legacy
+behaviour, an outfall that receives no inflow in a step simply holds its last
+mixed state, and reverse flow re-enters the network carrying that held
+concentration — water that left dirty comes back dirty. Under `ZERO` the
+outfall is a **fresh boundary**: whenever it supplies water its held state
+reads zero for every pollutant, every reaction species and `__WATER_AGE__`,
+so backflow re-enters clean and at age zero, as if the receiving water body
+were of unbounded volume and unpolluted. The rule is applied at the same
+site in every engine — the node mix of the tanks-in-series engine, the
+node-store donor of the Eulerian engine, and the mix and release phases of
+the Lagrangian engine — so switching `QUALITY_SOLVER` does not change what a
+reversal imports. The outfall's store keeps the mass that arrived; the key
+only guarantees that mass never re-enters. Choose `ZERO` when the outfall is
+a large receiving body; keep `LAST` when it stands for a pipe that continues
+beyond the model and the returning water is the water that left.
+
+The temperature row is outside this contract in the present release: the
+tanks-in-series heat binding holds the last temperature on reversal
+regardless of the key, while the Eulerian and Lagrangian engines zero the
+row with the others. A model that depends on the temperature of returning
+water should state its outfall temperature explicitly rather than rely on
+either reading.
+
+
+
+## 7.6 Mass Balance
+
+All three engines report through the same continuity table described in
+Chapter 5. Two caveats apply to the newer engines:
+
+- Species declared through the multi-species reaction system (Chapter 8) are
+  carried on the transport mesh but do **not** yet have per-species
+  mass-balance rows; the continuity table is indexed by pollutant. Mass
+  delivered by `[TRANSPORT_SOURCES]`, which addresses reaction species,
+  therefore appears in the continuity *error* rather than as a labelled inflow
+  term.
+All three engines now apply treatment expressions, the multi-species reaction
+system, and the bed zone of §9.3.11; there are no remaining silent bypasses,
+and any configuration an engine cannot honour is refused or warned by name at
+model open rather than quietly ignored.
+
+## 7.7 Implementation
+
+The Eulerian engine is implemented in
+`src/engine/transport/components/EulerianArdComponent/`, with the shared flux
+and dispersion kernels in `src/engine/transport/fvkernels/`. The Lagrangian
+engine is in `src/engine/quality/lard/` — `SegmentStore.hpp` for the parcel
+slabs, `LagrangianSolver.hpp` for the five-phase step, and
+`RwptDispersion.hpp` for the random-walk closure. Engine selection is resolved
+in `src/engine/core/SWMMEngine.cpp`, and the shared clamp bookkeeping for
+negative sources is in `src/engine/quality/NegativeSources.hpp`.
+
+Input grammar is in the engine manual: @ref engine_manual_sect_TRANSPORT_OPTIONS,
+@ref engine_manual_sect_CONDUIT_DISPERSION,
+@ref engine_manual_sect_TRANSPORT_BOUNDARIES and
+@ref engine_manual_sect_TRANSPORT_SOURCES for the component file, and
+@ref engine_manual_sect_OPTIONS for the `[OPTIONS]` keys this chapter uses —
+`QUALITY_SOLVER`, `QUALITY_STEP`, `MAX_SEGMENTS_PER_LINK`, `RWPT_SEED` and
+`OUTFALL_BACKFLOW_QUALITY`. The same configuration is readable and editable
+through the C API declared in @ref openswmm_transport.h.
+
+
diff --git a/docs/manuals/reference/quality/sections/Chapter8-MultiSpeciesReactions.md b/docs/manuals/reference/quality/sections/Chapter8-MultiSpeciesReactions.md
new file mode 100644
index 000000000..37a905d22
--- /dev/null
+++ b/docs/manuals/reference/quality/sections/Chapter8-MultiSpeciesReactions.md
@@ -0,0 +1,317 @@
+@page quality_ref_ch8_msx_reactions Chapter 8: Multi-Species Reactions
+
+@tableofcontents
+
+## 8.1 Introduction
+
+Chapters 3 through 5 describe pollutants that build up, wash off, are
+transported, and decay by a first-order rate. That model has one reaction per
+pollutant and no interaction between them. It cannot express chlorine decaying
+in proportion to the concentration of the material it oxidizes, a disinfection
+by-product forming as a consequence, or an equilibrium partition between
+dissolved and sorbed phases.
+
+OpenSWMM adds a **multi-species reaction system** in which the user declares
+species and writes their reaction expressions directly. The conventions follow
+EPANET-MSX (Shang, Uber and Rossman, 2008), which introduced the same facility
+for drinking-water distribution networks: species are declared, intermediate
+terms are named, and each species is given a rate, equilibrium or formula
+expression evaluated at every element.
+
+The reaction system is optional and is inert unless configured. Models that do
+not declare a reaction system are unaffected.
+
+## 8.2 Declaring a Reaction System
+
+A reaction system is supplied through a **process component**: a row in
+`[PROCESS_COMPONENTS]` names the reactions component and points at a
+configuration file, conventionally `model.rxn`.
+
+```
+[PROCESS_COMPONENTS]
+org.hydrocouple.openswmm.reactions  config="model.rxn"
+```
+
+The configuration file uses the same bracketed-section dialect as the `.inp`.
+Its sections are:
+
+| Section | Purpose | Grammar | Status |
+|---|---|---|---|
+| `[REACTION_OPTIONS]` | Solver, coupling, rate and area units, timestep, tolerances, fallback temperature | @ref engine_manual_sect_REACTION_OPTIONS | \status{Implemented} |
+| `[REACTION_SPECIES]` | Species declarations: `BULK` or `WALL`, units, per-species tolerances | @ref engine_manual_sect_REACTION_SPECIES | \status{Implemented} |
+| `[REACTION_COEFFICIENTS]` | Named constants and parameters | @ref engine_manual_sect_REACTION_COEFFICIENTS | \status{Implemented} |
+| `[REACTION_TERMS]` | Named intermediate expressions | @ref engine_manual_sect_REACTION_TERMS | \status{Implemented} |
+| `[REACTION_PIPES]` | Per-species `RATE`, `EQUIL` or `FORMULA` expressions in conduit scope | @ref engine_manual_sect_REACTION_PIPES | \status{Implemented} |
+| `[REACTION_TANKS]` | The same forms in node scope | @ref engine_manual_sect_REACTION_TANKS | \status{Implemented} |
+| `[REACTION_QUALITY]` | Initial concentrations: `GLOBAL`, `NODE` or `LINK` | @ref engine_manual_sect_REACTION_QUALITY | \status{Implemented} |
+| `[REACTION_SOURCES]` | Species sources at nodes | @ref engine_manual_sect_REACTION_SOURCES | \status{Planned} |
+| `[REACTION_PARAMETERS]` | Per-element overrides of `PARAMETER` coefficients | @ref engine_manual_sect_REACTION_PARAMETERS | \status{Planned} |
+| `[REACTION_PATTERNS]` | Time patterns for sources | @ref engine_manual_sect_REACTION_PATTERNS | \status{Planned} |
+| `[REACTION_REPORT]` | Report selection | @ref engine_manual_sect_REACTION_REPORT | \status{Planned} |
+| `[REACTION_SUBCATCHMENTS]` | Subcatchment-scope expressions | @ref engine_manual_sect_REACTION_SUBCATCHMENTS | \status{Planned} |
+
+The five sections marked planned are recognised by name and **refused** with
+the phase that delivers them; a configuration carrying one is rejected as a
+whole (Chapter 11 §11.5). An unknown `[REACTION_*]` name is rejected on the
+same terms.
+
+
+
+Sections may also be embedded directly in the `.inp`. This is supported as a
+convenience, but the external file is the intended layout: embedded sections
+are read but are not written back when a model is saved, and the engine warns
+when that is about to happen.
+
+A complete small system — chlorine decaying against a reactive wall material,
+with the by-product it forms:
+
+```
+[REACTION_OPTIONS]
+SOLVER            RK5
+RTOL              0.001
+ATOL              0.0001
+TIMESTEP          300
+
+[REACTION_SPECIES]
+BULK   CL2   MG   0.01   0.0001      ; free chlorine
+BULK   THM   UG   0.01   0.0001      ; trihalomethane by-product
+WALL   BIO   UG   0.01   0.0001      ; attached biomass
+
+[REACTION_COEFFICIENTS]
+PARAMETER   Kb     0.30      ; bulk decay, 1/day
+PARAMETER   Kw     1.00      ; wall demand
+PARAMETER   Yield  0.20      ; THM formed per unit CL2 consumed
+
+[REACTION_TERMS]
+Kf     1.5826e-4 * RE^0.88 / D       ; mass-transfer coefficient
+
+[REACTION_PIPES]
+RATE   CL2   -Kb*CL2 - (4/D)*Kw*Kf/(Kw+Kf)*CL2
+RATE   THM    Yield*Kb*CL2
+FORMULA BIO   Kw*CL2/(Kw+Kf)
+
+[REACTION_TANKS]
+RATE   CL2   -Kb*CL2
+RATE   THM    Yield*Kb*CL2
+
+[REACTION_QUALITY]
+GLOBAL   CL2   0.8
+LINK     C1    CL2   1.2
+```
+
+Two things in that listing are worth pointing out. `[REACTION_TERMS]`
+defines `Kf` once and both pipe expressions reference it, so the
+mass-transfer closure has a single definition rather than two copies that can
+drift. And the pipe and tank expressions for `CL2` differ deliberately: a
+storage unit has no wall in the sense a pipe does, so the wall-demand term is
+absent from the tank form.
+
+### 8.2.1 Species and coefficient declarations
+
+A species is declared once, as `BULK` or `WALL`, with a units token and
+optional absolute and relative tolerances. Species names are **globally
+unique**: a name that collides with a `[POLLUTANTS]` id, a reserved name or
+another species is refused, because every downstream surface —
+`[INITIAL_QUALITY]`, `[INFLOWS]`, the results file, the buildup and washoff
+tables — addresses a species by name alone. The units token is free text in
+the MSX manner (`MG`, `UG`, `MMOL`, a count), and it is load-bearing in one
+place beyond labelling: the buildup and washoff machinery of Chapters 3, 4
+and 10 converts a species' concentration-mass to user mass from it — `MG`
+takes the project mass conversion, `UG` a thousandth of it, anything else is
+carried unconverted. The per-species tolerances, when given, replace the
+global `ATOL` and `RTOL` of `[REACTION_OPTIONS]` for that species alone.
+
+`WALL` species are surface-attached: their concentration is per unit wall
+area, they are not advected, and they enter bulk expressions through the
+area-to-volume ratio. Declaring one has two consequences worth knowing before
+choosing it: the Eulerian engine falls back to the tanks-in-series binding
+for the reaction stage, and the 2D mesh carries no reaction species at all
+(Chapter 10 §10.1).
+
+A coefficient is declared as `CONSTANT` or `PARAMETER` with a value. In the
+MSX convention a `PARAMETER` may later be overridden per pipe or tank; that
+override section (`[REACTION_PARAMETERS]`) is planned, so in this release
+both kinds are single model-wide values and the distinction is a declaration
+of intent. A coefficient may not share a name with a species or another
+coefficient. `[REACTION_TERMS]` names an intermediate expression evaluated
+before the species expressions that reference it; a term may not share a
+name with a species, a coefficient or another term, and it may use species,
+coefficients, other terms and the hydraulic variables of §8.3. Declaration
+order in the file does not matter — species are resolved first, then
+coefficients and terms, then expressions — but every reference must resolve
+or the whole configuration is rejected.
+
+
+
+### 8.2.2 Rate and equilibrium terms
+
+Each species may carry **one** expression per scope: `RATE`, `EQUIL` or
+`FORMULA` in `[REACTION_PIPES]` for conduits and `[REACTION_TANKS]` for
+nodes, with the meanings of §8.3. A species with no expression in a scope is
+inert there — it is transported and mixed but not reacted — which is the
+normal state of a conservative tracer or of a by-product that forms only in
+pipes. A second expression for the same species in the same scope is
+refused. The pipe scope is also what the Eulerian engine's cells, the
+Lagrangian parcels and the cells of the 2D mesh evaluate; the tank scope is
+evaluated on node stores against the node's hydraulic residence time.
+
+An expression on a **pollutant** — a `[POLLUTANTS]` id rather than a
+declared species — is refused with the note that pollutant kinetics arrive
+with a later phase. Pollutants may be referenced read-only inside a species
+expression, and their own first-order `Kdecay` is applied by the decay stage
+under every engine, in a separate stage from the reaction integrator (§8.5).
+
+Expressions are compiled at open, transactionally: a configuration that
+leaves any expression uncompilable is rejected and rolled back, so the model
+never holds a reaction system that cannot run.
+
+
+
+### 8.2.3 Initial quality and sources
+
+`[REACTION_QUALITY]` seeds the species rows. A `GLOBAL` row sets a species'
+initial concentration everywhere; a `NODE name` or `LINK name` row overrides
+it on one element. Values are non-negative; a duplicate row for the same
+species on the same element is refused rather than letting the later one
+win. A species with no row starts at zero. The element names are resolved
+against the model after the whole `.inp` has been read, so the component
+file may be listed before or after the elements it names. Reaction-species
+rows written in the `.inp`'s own `[INITIAL_QUALITY]` are mirrored into the
+same store, so either spelling seeds the same state.
+
+Mass enters through the loader seam every engine shares. `[INFLOWS]` rows
+may name a reaction species, exactly as they name a pollutant, and are
+delivered as external species loads; under the Eulerian ARD component,
+`[TRANSPORT_BOUNDARIES]` sets the concentration carried by water entering at
+a node and `[TRANSPORT_SOURCES]` a distributed mass rate along a conduit,
+negative for extraction (Chapter 7 §7.5). On the land surface a reaction
+species may build up and wash off through `[BUILDUP]`, `[WASHOFF]`,
+`[LOADINGS]` and, on the 2D mesh, `[2D_LOADINGS]` (Chapters 3, 4 and 10).
+`[REACTION_SOURCES]` and `[REACTION_PATTERNS]`, the MSX spellings of node
+sources, are planned (Chapter 11 §11.5).
+
+
+
+## 8.3 Expression Forms
+
+Each species is given an expression in each scope it participates in. Three
+forms are available, following the MSX conventions:
+
+- **`RATE`** — the expression gives \f$dc/dt\f$, and the species is
+  integrated over the reaction step.
+- **`EQUIL`** — the expression is an algebraic residual driven to zero, for
+  species assumed to equilibrate faster than the transport step resolves.
+- **`FORMULA`** — the expression gives the concentration directly, for a
+  species that is a stated function of others rather than a state variable.
+
+Expressions may reference declared species, coefficients, intermediate terms,
+declared pollutants, and a set of hydraulic variables supplied by the engine.
+The available names are enumerated by the engine rather than fixed in
+documentation, so an editor or API can list exactly what the current model
+admits — but the usual set is:
+
+| Name | Meaning |
+|---|---|
+| `D` | Hydraulic diameter |
+| `Q` | Flow rate |
+| `U` | Flow velocity |
+| `RE` | Reynolds number |
+| `US` | Shear velocity |
+| `AR` | Surface-area-to-volume ratio |
+| `LEN` | Element length |
+| `T` | Water temperature, when heat transport is on |
+
+`T` is the connection between Chapters 8 and 9: with `HEAT_TRANSPORT` on,
+each element's reaction expressions see **that element's own** temperature,
+so an Arrhenius or \f$Q_{10}\f$ term responds to the simulated thermal
+field rather than to a single constant. Without heat transport it falls back
+to the `[REACTION_OPTIONS] TEMPERATURE` constant.
+
+Species declared `WALL` are surface-attached: their concentrations are per
+unit wall area rather than per unit volume, they are not advected, and they
+appear in bulk expressions through the surface-area-to-volume ratio.
+
+Expressions are **compiled at model open**, not interpreted per element per
+step: they are parsed once into a compact form and evaluated by a small stack
+machine over a flat pool of values. Compilation is transactional — a change
+that leaves any expression uncompilable is rejected and rolled back, so a
+model can never be left holding a reaction system that cannot run.
+
+## 8.4 Integration
+
+`[REACTION_OPTIONS] SOLVER` selects the integrator applied to the `RATE`
+species:
+
+| Solver | Method | Suited to |
+|---|---|---|
+| `EUL` | Explicit Euler | Non-stiff systems, small steps |
+| `RK5` | Explicit Runge–Kutta with error control | Non-stiff, accuracy-controlled |
+| `ROS2` | Second-order Rosenbrock | Moderately stiff systems |
+| `BDF2` | Second-order backward differentiation | Stiff systems |
+
+Stiffness arises whenever a system contains reactions on widely separated
+timescales — a fast equilibrium alongside a slow decay — and an explicit
+method must then take steps set by the fastest reaction rather than by the
+accuracy required. The Rosenbrock and BDF families are the standard responses
+(Hairer and Wanner, 1996). `EQUIL` species are solved by Newton iteration at
+each step, and `FORMULA` species are evaluated directly.
+
+**Choosing one.** Start with `RK5`: it is accuracy-controlled, needs no
+Jacobian, and handles most disinfection and by-product systems. Move to
+`ROS2` when `RK5` is taking many internal substeps per reaction step, which
+is the observable symptom of stiffness. Reserve `BDF2` for systems that
+remain expensive under `ROS2`. `EUL` exists for reference and for systems
+known to be non-stiff at the chosen `TIMESTEP`; it does no error control, so
+a wrong answer from it is silent.
+
+`RTOL` and `ATOL` govern the error-controlled integrators. `ATOL` should be
+set near the smallest concentration that matters for each species — set it
+too large and a trace species is integrated as zero; too small and the
+integrator wastes work resolving numerical noise. The per-species tolerance
+columns in `[REACTION_SPECIES]` override the global values for exactly this
+reason.
+
+## 8.5 Coupling to Transport
+
+The reaction system is bound to the transport engines rather than duplicated
+inside them. Species declared in the reaction system are carried as additional
+rows on the same transport state the pollutants use:
+
+- Under **`LEGACY`**, expressions are evaluated on the node and link stores
+  after mixing, and a pollutant's `Kdecay` is treated as an equivalent rate
+  expression so that the two mechanisms cannot disagree.
+- Under **`EULERIAN_ARD`**, species ride the cell mesh and react per cell.
+- Under **`LAGRANGIAN`**, species ride the parcels: each parcel carries its
+  own species column and reacts against its own pollutant concentrations and
+  its own temperature (pipe scope), while node stores react on the node's
+  hydraulic residence time (tank scope).
+
+Because the reaction species share the transport representation with the
+pollutants, they are advected and dispersed by the same schemes described in
+Chapter 7, with the same coefficient. Where a bed zone is configured
+(§9.3.11) they also exchange with it, so a reactive species can be stored and
+released by the sediment as well as transported by the water.
+
+Pollutant first-order decay and MSX kinetics are integrated in **separate
+stages** under every engine. This matters because a pollutant referenced in
+an MSX expression is read-only there: its decay is owned by the decay stage,
+and the integrator handles only the species' own kinetics, so no pathway
+applies a rate twice.
+
+## 8.6 Implementation
+
+The reaction module is in
+`src/engine/transport/components/ReactionModule/` — the component and its
+parser, the expression compiler and stack machine, the integrators, and
+`ReactionsWriter.cpp`, which renders a reaction system back to its canonical
+`.rxn` form. The binding to the tanks-in-series engine is in
+`src/engine/quality/QualityRouting.cpp` — with `MsxLegacyTransport.cpp`
+carrying the species between elements on that engine's CSTR mirror — the
+binding to the Eulerian mesh is in the ARD component's
+`ReactionArdBinding.hpp`, and the Lagrangian binding is stage 4b of
+`LagrangianSolver.hpp`.
+
+The C API for inspecting and editing a reaction system is declared in
+@ref openswmm_reactions.h, including `swmm_reaction_validate_expression`,
+which compiles an expression against the live model vocabulary without
+changing state — the entry point an editor uses to validate as the user types.
diff --git a/docs/manuals/reference/quality/sections/Chapter9-WaterAgeAndHeatTransport.md b/docs/manuals/reference/quality/sections/Chapter9-WaterAgeAndHeatTransport.md
new file mode 100644
index 000000000..c0bd1a459
--- /dev/null
+++ b/docs/manuals/reference/quality/sections/Chapter9-WaterAgeAndHeatTransport.md
@@ -0,0 +1,769 @@
+@page quality_ref_ch9_age_heat Chapter 9: Water Age and Heat Transport
+
+@tableofcontents
+
+## 9.1 Introduction
+
+Water age and temperature are not pollutants, but both are scalar fields
+carried by the same water, mixed by the same junctions and advected by the
+same flows. OpenSWMM therefore transports them through the same machinery
+that carries pollutants and reaction species, as **reserved species** — rows
+on the transport state that no `[POLLUTANTS]` declaration creates and that
+obey slightly different laws.
+
+Treating them as reserved rows rather than as separate subsystems is what
+lets a single mixing formula serve all of them: when two flows meet, the
+volume-weighted mean is the correct answer for a concentration, for an age
+and for a temperature alike. What differs is not the mixing but the source
+terms and the constraints, and those are stated explicitly below rather than
+left to fall out of the code.
+
+Both are enabled by an `[OPTIONS]` key and are inert otherwise:
+
+| Key | Reserved species | Internal unit | Reported unit |
+|---|---|---|---|
+| `WATER_AGE` | `__WATER_AGE__` | seconds | hours |
+| `HEAT_TRANSPORT` | `__TEMPERATURE__` | °C | °C |
+
+## 9.2 Water Age
+
+### 9.2.1 Definition and aging
+
+Water age is the time elapsed since a parcel of water entered the system.
+Every element's age advances by exactly the routing step before transport is
+applied:
+
+\f[a(t + \Delta t) = a(t) + \Delta t\f]
+
+and then mixes by volume weight wherever flows combine, exactly as a
+concentration does:
+
+\f[a_{mix} = \frac{\sum_i a_i V_i}{\sum_i V_i}\f]
+
+Age therefore has no decay and no reaction. It grows without bound in water
+that never leaves, which is the intended reading: a storage unit whose age
+climbs steadily is a storage unit that is not turning over.
+
+### 9.2.2 Sources
+
+`[WATER_AGE_SOURCES]` sets the age carried by water entering the system, by
+scope. The common cases are:
+
+- **`INITIAL_STATE`** — the age assigned to water already in the network at
+  \f$t = 0\f$. Setting this to zero models a system flushed at the start;
+  setting it to a nonzero value models one that has been standing.
+- **Per-pathway sources** — the age of water arriving by dry-weather flow,
+  groundwater, RDII, external inflow, and the remaining loader pathways.
+
+Water entering with age zero is fresh; water entering with a nonzero age is
+treated as having already spent that long in transit elsewhere, which is how
+a boundary at the edge of a modelled area represents the network beyond it.
+
+With `[OPTIONS] OUTFALL_BACKFLOW_QUALITY ZERO` (§7.5), water that re-enters
+through an outfall during reverse flow arrives at age zero — the outfall is
+a fresh boundary — whereas the default `LAST` lets the held boundary water
+keep aging one-for-one and re-import that age on every reversal.
+
+
+
+**Example.** A collection system fed by an upstream trunk that is not
+modelled, whose travel time is known to be about four hours:
+
+```
+[WATER_AGE_SOURCES]
+INITIAL_STATE     GLOBAL   0.0
+EXTERNAL_INFLOW   GLOBAL   4.0
+DWF               GLOBAL   0.0
+```
+
+Ages here are in **hours**, the reported unit. Water arriving through
+`[INFLOWS]` is treated as four hours old on arrival; dry-weather flow enters
+fresh; the network starts empty of aged water.
+
+### 9.2.3 State and reporting
+
+Age is held in seconds internally and reported in **hours**, which is the
+scale users read. The distinction matters when reading the output file
+directly rather than through the reporting layer.
+
+A **dry** element keeps aging in state while its reported age is masked.
+Those are deliberately separate: the state must keep advancing because the
+element may refill and the water in it has genuinely been there, while
+reporting an age for an element holding no water would be meaningless. A
+restart therefore carries the aged state, not the masked report.
+
+## 9.3 Heat Transport
+
+### 9.3.1 Temperature as a transported scalar
+
+Temperature is carried as a reserved species and mixed by volume weight,
+which is the correct mixing rule when the specific heat of water is taken as
+constant across the modelled range — mixing enthalpies then reduces to mixing
+temperatures:
+
+\f[T_{mix} = \frac{\sum_i T_i V_i}{\sum_i V_i}\f]
+
+Unlike age, temperature does **not** advance with time by itself, does not
+decay, and is **not** constrained to be non-negative: water below 0 °C is a
+legitimate model state, and the non-negativity clamp applied to
+concentrations is deliberately not applied to this row.
+
+Inlet temperatures are set per source by `[HEAT_SOURCES]`, with a global
+value for each of the seven water sources and node-scope overrides where a
+particular inflow point differs:
+
+```
+[HEAT_SOURCES]
+;;source           scope   [name]  degC
+RAINFALL           GLOBAL           12.0
+DWF                GLOBAL           18.5
+GW                 GLOBAL           11.0
+INITIAL_STATE      GLOBAL           15.0
+DWF                NODE     J12     22.0
+```
+
+Temperatures are °C and must lie between −50 and 100. A source with no row
+takes 20 °C. NODE-scope overrides apply to `DWF` and `EXTERNAL_INFLOW`; other
+sources take their global value.
+
+Transport alone — advection and mixing, with no flux modules enabled — is the
+default and is often enough: it answers "where does the warm water go?" A
+model that additionally needs "how does it warm or cool on the way?" enables
+one or more of the flux modules below.
+
+### 9.3.2 Meteorological forcing
+
+The flux modules are driven by the model's **existing climate data**, not by
+a heat-specific meteorology section. Air temperature, wind speed and relative
+humidity come from `[TEMPERATURE]`, `[WINDSPEED]` and the humidity series
+already used by evaporation and snowmelt, which means a model that has been
+calibrated for hydrology is already carrying most of what heat transport
+needs.
+
+| Forcing | Source | Native unit | Used as |
+|---|---|---|---|
+| Air temperature \f$T_a\f$ | `[TEMPERATURE]` | °F | °C |
+| Wind speed \f$w\f$ | `[WINDSPEED]` | mph | m/s |
+| Relative humidity \f$RH\f$ | climate series | % | fraction |
+| Incoming shortwave \f$J_{in}\f$ | `[RADIATIVE_FLUXES]` / computed | W/m² | W/m² |
+| Cloud fraction \f$C\f$ | `[CLOUD_COVER]` | 0–1 | 0–1 |
+
+The unit conversions are worth stating because they are a common source of
+confusion when reading intermediate values: the climate state stores air
+temperature in **°F** and wind in **mph** for historical reasons, while every
+heat formulation is written in SI. The conversion happens in exactly one
+place so the two cannot drift apart.
+
+### 9.3.2a The Physical Constants
+
+Five `[OPTIONS]` keys (@ref engine_manual_sect_OPTIONS) set the constants
+every flux module shares. They are model-wide by design — a water density
+that varied by reach would be two descriptions of one fluid — and their
+defaults are the CSH reference's Table 4.1 values.
+
+| Key | Symbol | Default | Where it enters |
+|---|---|---|---|
+| `WATER_DENSITY` | \f$\rho_w\f$ | 1000 kg/m³ | The latent flux \f$J_e = \rho_w L_v E\f$ (§9.3.4); the heat capacity \f$\rho_w c_p V\f$ the relaxation of §9.3.9 divides by; the water-side capacity and the hyporheic advective conductance of the bed zone (§9.3.11); LID layer conduction (§9.3.10) |
+| `WATER_SPECIFIC_HEAT_CAPACITY` | \f$c_p\f$ | 4184 J/kg/°C | With \f$\rho_w\f$ in every capacity and conductance above |
+| `WIND_FUNC_COEFF_A` | \f$a\f$ | 1.505e-8 | The wind function \f$f(w) = a + b\,w\f$ in the evaporation rate \f$E = f(w)\,(e_s(T_w) - e_a)\f$ (§9.3.4); Dunne and Leopold (1978) |
+| `WIND_FUNC_COEFF_B` | \f$b\f$ | 1.6e-8 | As above; \f$w\f$ is wind speed in m/s, floored at zero |
+| `PRESSURE_RATIO` | \f$P_a / P\f$ | 1.0 | The Bowen ratio \f$B = \gamma\,(P_a/P)\,(T_w - T_a)/(e_w - e_a)\f$ of §9.3.5, an elevation correction; 1 at sea level |
+
+`WATER_DENSITY` and the specific heat were deliberately absent from the first
+heat phase: with no flux modules enabled they cancel identically and no gate
+could observe them. They became load-bearing with surface exchange, where
+they set the weight of a surface flux against advected heat.
+
+
+
+### 9.3.3 The surface energy balance
+
+With `[HEAT_FLUXES] SURFACE_EXCHANGE ON` and/or `RADIATIVE_EXCHANGE ON`, the
+free surface exchanges heat with the atmosphere. The modules use a consistent
+sign convention throughout:
+
+> **Positive flux is heat leaving the water.**
+
+The net flux out of the surface is the sum of the enabled modules' terms:
+
+\f[J_{net} = \underbrace{J_e + J_h}_{\text{surface exchange}} + \underbrace{J_{br} - J_{sn} - J_{an} - J_{lc}}_{\text{radiative exchange}}\f]
+
+where \f$J_e\f$ is latent, \f$J_h\f$ sensible, \f$J_{br}\f$ back longwave
+radiated by the water, \f$J_{sn}\f$ net shortwave absorbed, \f$J_{an}\f$
+atmospheric longwave absorbed, and \f$J_{lc}\f$ land-cover longwave absorbed.
+Three radiative terms warm the water and one cools it, which is why only
+\f$J_{br}\f$ carries a positive sign in the sum.
+
+The two modules are independent. A model may enable surface exchange without
+radiation (evaporative cooling only), radiation without surface exchange
+(a covered channel), or both.
+
+Figure 9-1 collects the terms of (the balance above) with the bed-zone
+exchange of §9.3.11, grouped by the module that enables each.
+
+![Figure 9-1](figures/png/quality_ch9_heat_budget.png)
+
+*Figure 9-1 The heat budget of a water body: the six surface terms of the net flux by module, and the bed zone's conduction and hyporheic exchange*
+
+### 9.3.4 Latent heat — evaporation and condensation
+
+Latent exchange follows the mass-transfer formulation given for surface-water
+quality modelling by Martin and McCutcheon (1999). Saturation vapour pressure
+over water uses the Magnus form, in kPa:
+
+\f[e_s(T) = 0.61275\,\exp\!\left(\frac{17.27\,T}{237.3 + T}\right)\f]
+
+The air's actual vapour pressure follows from relative humidity evaluated at
+the **air** temperature, while the water surface is saturated at the **water**
+temperature:
+
+\f[e_a = \frac{RH}{100}\,e_s(T_a), \qquad e_w = e_s(T_w)\f]
+
+The evaporative mass flux is the vapour-pressure deficit driven by a linear
+wind function:
+
+\f[E = f(w)\,(e_w - e_a), \qquad f(w) = a + b\,w\f]
+
+with \f$E\f$ in m/s and \f$f(w)\f$ in m/s/kPa. The coefficients \f$a\f$ and
+\f$b\f$ are the calibration handles of this module. The latent heat flux is
+then
+
+\f[J_e = \rho_w\,L_v(T_w)\,E, \qquad L_v(T) = 1000\,(2499 - 2.36\,T)\ \text{J/kg}\f]
+
+**\f$E\f$ is signed.** When \f$e_a > e_w\f$ — humid air over cold water — the
+deficit is negative, \f$E\f$ is negative, and the term becomes condensation
+*warming* the water rather than evaporation cooling it. The formulation is
+not clamped to evaporation only, because condensation onto a cold surface is
+a real process and suppressing it would bias the balance in one direction.
+
+### 9.3.5 Sensible heat — the Bowen ratio
+
+Sensible exchange is obtained from the latent flux through the Bowen ratio
+rather than by an independent transfer coefficient, which is the standard
+closure and keeps the two terms consistent by construction:
+
+\f[B_r = \gamma\,\frac{p}{p_0}\,\frac{T_w - T_a}{e_w - e_a}, \qquad J_h = B_r\,J_e\f]
+
+where \f$\gamma\f$ is the Bowen coefficient (kPa/°C) and \f$p/p_0\f$ the
+ratio of site to sea-level pressure.
+
+The ratio has a removable singularity: as the vapour-pressure deficit
+approaches zero the quotient diverges, but the product \f$B_r J_e\f$ remains
+finite because \f$J_e\f$ carries the same deficit as a factor. The
+implementation returns \f$B_r = 0\f$ when \f$|e_w - e_a| < 10^{-12}\f$, which
+is the correct value of the limiting product and not an error suppression.
+
+### 9.3.6 Radiative exchange
+
+Four terms are computed when `RADIATIVE_EXCHANGE ON`. All longwave terms use
+the Stefan–Boltzmann law with absolute temperature.
+
+**Net absorbed shortwave.** Incident shortwave, reduced by surface reflection
+and by shading:
+
+\f[J_{sn} = (1 - R_s)\,J_{in}\,\max(0,\,1 - f_s)\f]
+
+The \f$\max\f$ guard means an over-unity shade factor shades completely rather
+than inverting the sign into negative insolation.
+
+**Back longwave radiated by the water:**
+
+\f[J_{br} = \varepsilon_w\,\sigma\,T_w^4\f]
+
+**Atmospheric longwave absorbed.** Clear-sky atmospheric emissivity uses the
+Brunt (1932) form, with vapour pressure in pascals:
+
+\f[\varepsilon_a = A_a + 0.0027\,\sqrt{1000\,e_a}\f]
+
+\f[J_{an} = \sigma\,T_a^4\,\varepsilon_a\,(1 - R_L)\,f_{sky}\f]
+
+where \f$R_L\f$ is the longwave reflectance of the water surface and
+\f$f_{sky}\f$ the sky-view fraction.
+
+**Land-cover longwave absorbed.** The complement of the sky view is occupied
+by vegetation or structures, which radiate toward the water:
+
+\f[J_{lc} = \varepsilon_{lc}\,\sigma\,(1 - f_{sky})\,T_a^4\f]
+
+@note This term uses **air** temperature as the land-cover temperature. A
+canopy is usually warmer than the air during the day, so this understates
+daytime longwave gain from the surroundings. It is a recorded, deliberate
+simplification: carrying a separate land-cover temperature state would
+require a canopy energy balance of its own.
+
+### 9.3.7 Shortwave forcing
+
+`[RADIATIVE_FLUXES] SHORTWAVE` selects where \f$J_{in}\f$ comes from. The
+three spellings are mutually exclusive:
+
+| Spelling | Source |
+|---|---|
+| `SHORTWAVE GLOBAL ` | A constant |
+| `SHORTWAVE GLOBAL TIMESERIES ` | A measured record, interpolated |
+| `SHORTWAVE GLOBAL COMPUTED` | Solar position and a clear-sky model |
+
+Under `COMPUTED`, solar position is evaluated from the Fourier-series
+representation of Spencer (1971) — declination, equation of time, and hour
+angle — giving the solar zenith angle \f$\theta_z\f$. Relative optical air
+mass then follows Kasten and Young (1989):
+
+\f[m = \frac{1}{\cos\theta_z + 0.50572\,(96.07995 - \theta_z)^{-1.6364}}\f]
+
+with \f$\theta_z\f$ in degrees. This form is used rather than the simple
+\f$\sec\theta_z\f$ because the secant diverges at the horizon, where a
+low-sun model spends a meaningful part of every day.
+
+Station pressure is derived from site elevation by the standard-atmosphere
+relation
+
+\f[p = p_0\,(1 - 2.25577 \times 10^{-5}\,z)^{5.25588}\f]
+
+and clear-sky global horizontal irradiance from the Bird and Hulstrom (1981)
+model, which resolves direct-beam and diffuse components through separate
+transmittances for Rayleigh scattering, ozone, mixed gases, water vapour and
+aerosols. Site parameters — latitude, longitude, elevation, turbidity,
+precipitable water, ozone — are set in `[SOLAR_RADIATION]`.
+
+```
+[SOLAR_RADIATION]
+LATITUDE      41.88
+LONGITUDE    -87.63
+TIMEZONE       -6
+ELEVATION     181.0
+```
+
+Night is represented by \f$J_{in} = 0\f$ rather than by a special case, so no
+branch distinguishes it. A **negative** internal sentinel, not zero, marks
+"no resolved value, fall back to the configured constant" — because zero is a
+legal night-time irradiance and must not read as unset.
+
+### 9.3.8 Cloud cover
+
+`[CLOUD_COVER]` supplies a cloud fraction \f$C \in [0,1]\f$, constant or as a
+time series. Cloud attenuates **both** radiative directions, and the two
+corrections are different functions:
+
+**Shortwave**, following Kasten and Czeplak (1980):
+
+\f[J_{in} \leftarrow J_{in}\,\max\!\left(0,\ 1 - k\,C^{\,n}\right)\f]
+
+**Longwave**, following Bolz — cloud raises the effective atmospheric
+emissivity:
+
+\f[\varepsilon_a \leftarrow \varepsilon_a\,(1 + k_{lw}\,C^2)\f]
+
+Clouds therefore reduce incoming solar radiation while *increasing* downward
+longwave. Applying cloud to only one direction — the tempting simplification —
+would bias the net balance systematically, which is why both corrections are
+present and why the cloud fraction feeds two separate paths.
+
+Both factors return a **literal** 1.0 when \f$C \le 0\f$, so a model with no
+cloud configuration produces bit-identical results to one built before cloud
+existed. This is stronger than "equal within rounding" and is deliberate.
+
+### 9.3.9 Applying the flux to a water body
+
+Given \f$J_{net}(T_w)\f$ over a surface area \f$A\f$ and volume \f$V\f$, the
+naive explicit update is
+
+\f[\Delta T_{expl} = -\,\frac{J_{net}(T_0)\,A\,\Delta t}{\rho_w c_p V}\f]
+
+which is accurate for small steps but can **overshoot** — a shallow, fast-
+cooling element can be driven past equilibrium and oscillate, or leave the
+physical range entirely, when the routing step is long relative to the
+thermal response time.
+
+OpenSWMM therefore applies the flux with a **linearized semi-implicit
+relaxation**. The flux is probed at \f$T_0\f$ and at \f$T_0 + h\f$ to obtain
+its local slope,
+
+\f[J' = \frac{J(T_0 + h) - J(T_0)}{h}, \qquad k = \frac{A\,J'}{\rho_w c_p V}\f]
+
+and the update becomes an exponential relaxation toward the equilibrium
+temperature \f$T_{eq} = T_0 - J_0/J'\f$:
+
+\f[\Delta T = \frac{J_0}{J'}\left(e^{-k\,\Delta t} - 1\right)\f]
+
+Because \f$J\f$ increases with \f$T_w\f$ over the physical range (a warmer
+surface radiates and evaporates more), \f$J' > 0\f$ and \f$k > 0\f$, so the
+step **cannot overshoot** \f$T_{eq}\f$ regardless of \f$\Delta t\f$: it
+approaches it asymptotically. When \f$J' \le 0\f$ — outside the physical
+regime, or where the probe is dominated by rounding — the scheme falls back
+to the explicit form rather than dividing by a slope it does not trust.
+
+### 9.3.10 LID layer conduction
+
+With `[HEAT_FLUXES] LAYER_CONDUCTION ON`, vertical conduction is solved
+between the layers of an LID control — surface, pavement, soil and storage —
+so a bioretention or permeable-pavement column has a thermal profile rather
+than a single mixed temperature.
+
+Each layer's effective conductivity is the volume-weighted mean of its water
+and solid fractions, with \f$\theta\f$ the water content:
+
+\f[k_{eff} = \theta\,k_w + (1 - \theta)\,k_s\f]
+
+Defaults are \f$k_w = 0.606\f$ W/m/K for water and \f$k_s = 2.6\f$ W/m/K for
+the solid matrix, with a matrix density of 1970 kg/m³ and specific heat
+2758 J/kg/K. A wet layer therefore conducts differently from a dry one, which
+is the point: a saturated storage layer couples to the soil above it far more
+strongly than an empty one.
+
+Conductance across the interface between adjacent layers is the **series
+resistance** of their half-thicknesses:
+
+\f[U_{i,i+1} = \left(\frac{d_i}{2 k_i} + \frac{d_{i+1}}{2 k_{i+1}}\right)^{-1}\f]
+
+and the resulting one-dimensional system is solved **implicitly** by a
+tridiagonal (Thomas) solve, so a thin surface film — which has a very short
+thermal time constant — does not force the whole model onto a short step.
+
+A layer that is dry but present still participates in conduction: it has a
+temperature and a thermal mass even with no water in it, and removing it from
+the system would break the column into disconnected pieces.
+
+### 9.3.11 The bed zone — conduction and hyporheic exchange
+
+A buried conduit exchanges heat with more than its free surface. Its wetted
+perimeter is in contact with the pipe wall and the sediment beyond it, that
+sediment conducts to the deeper ground, and in an unlined or permeable
+channel water itself moves between the channel and the pore space beneath it.
+`[HEAT_FLUXES] SEDIMENT_EXCHANGE ON` adds all three.
+
+The formulation follows the transient-storage zone of HydroCouple's
+`HTSComponent`, whose lineage is the stream transient-storage literature
+(Bencala and Walters, 1983; Runkel, 1998). The zone is a **second body**: a
+bed of thickness \f$Y_{bed}\f$ beneath each conduit, with its own temperature
+\f$T_b\f$ and its own thermal mass, exchanging with the water above and with
+a deep-ground boundary below.
+
+**Three conductances.** Writing \f$A_{bed}\f$ for the contact area and
+\f$\rho_s c_s\f$ for the volumetric heat capacity of the saturated sediment:
+
+\f[G_{cond} = \frac{\alpha_{sed}\,\rho_s c_s\, A_{bed}}{Y_{bed}}\f]
+
+\f[G_{adv} = \rho_w c_p\, v_{hyp}\, A_{bed}\f]
+
+\f[G_{bg} = \frac{\alpha_{sed}\,\rho_s c_s\, A_{bed}}{Y_{gr}}\f]
+
+where \f$\alpha_{sed}\f$ is the bed thermal diffusivity (m²/s), \f$v_{hyp}\f$
+the hyporheic exchange velocity across the interface (m/s), and \f$Y_{gr}\f$
+the depth to the deep-ground boundary. The grouping \f$\alpha\rho c\f$ has
+units of W/m/K and is an effective thermal conductivity; it is written this
+way rather than as a conductivity \f$k\f$ because the diffusivity is the
+parameter the deck supplies.
+
+Conduction and hyporheic advection both move heat between the same two
+bodies and are therefore summed into a single water–bed conductance,
+\f$G_{wb} = G_{cond} + G_{adv}\f$. The pair of bodies then obeys
+
+\f[C_w \frac{dT_w}{dt} = -A_s J(T_w) + G_{wb}(T_b - T_w)\f]
+
+\f[C_b \frac{dT_b}{dt} = G_{wb}(T_w - T_b) + G_{bg}(T_{gr} - T_b)\f]
+
+with \f$C_w = \rho_w c_p V_w\f$ and \f$C_b = \rho_s c_s A_{bed} Y_{bed}\f$.
+
+**The exchange is conservative by construction.** Adding the two equations,
+\f$G_{wb}\f$ cancels identically and leaves
+\f$C_w \dot T_w + C_b \dot T_b = -A_s J + G_{bg}(T_{gr} - T_b)\f$: whatever
+the water loses to the bed, the bed gains. The ground term is the only true
+source or sink in the pair, which is why a bed that is well insulated from
+the deep ground eventually equilibrates with the water rather than draining
+it.
+
+**Integration.** The two bodies are stepped **simultaneously**, not one after
+the other. Each body's equilibrium moves as the other responds, so there is
+no fixed target for a single-body relaxation (§9.3.9) to relax toward, and
+stepping them in sequence makes the answer depend on which went last. The
+linearized 2×2 system is advanced by its exact matrix exponential. Both
+eigenvalues are real and non-positive — the discriminant is
+\f$(a_{11}-a_{22})^2 + 4a_{12}a_{21}\f$ with non-negative off-diagonals — so
+the pair can neither oscillate nor overshoot at any step length.
+
+**Contact area is the wetted perimeter**, \f$P = A/R\f$, times length times
+barrels. This is a deliberate departure from the open-channel reference,
+which uses top width: the two coincide in a wide channel, but for a
+surcharged circular pipe the top width is zero while the contact area is at
+its maximum. Using top width would switch the module off exactly where a
+buried pipe conducts most. The consequence worth knowing is that a **closed**
+conduit, which has no free surface and therefore no latent, sensible or
+radiative exchange at all, still exchanges with its bed — for much of a
+buried network this is the only heat transfer there is.
+
+**Solutes.** The same zone acts as transient storage for pollutants and
+multi-species reactants. The exchange discharge is
+
+\f[Q_{exch} = \frac{D_{sed} A_{bed}}{Y_{bed}} + v_{hyp} A_{bed}\f]
+
+and the channel/bed concentration pair is advanced in total-and-difference
+coordinates: the total mass is invariant and the difference decays as
+\f$\exp(-\mu \Delta t)\f$ with
+\f$\mu = Q_{exch}(1/V_w + 1/V_b)\f$. Solving in those coordinates makes mass
+conservation structural rather than a bookkeeping step. This is what produces
+the long concentration tail characteristic of a stream with a storage zone: a
+tracer slug leaves mass behind in the bed and that mass returns slowly after
+the peak has passed. There is deliberately **no** bed-to-ground solute
+exchange, matching the reference.
+
+**Parameters** (`[SEDIMENT_EXCHANGE]`, all `GLOBAL` scope):
+
+| Key | Symbol | Default | Meaning |
+|---|---|---|---|
+| `THERMAL_DIFFUSIVITY` | \f$\alpha_{sed}\f$ | 1.0e-6 | Bed thermal diffusivity, m²/s |
+| `SOLUTE_DIFFUSIVITY` | \f$D_{sed}\f$ | 1.0e-9 | Bed effective solute diffusivity, m²/s |
+| `BED_THICKNESS` | \f$Y_{bed}\f$ | 0.20 | Bed layer thickness, m |
+| `GROUND_DEPTH` | \f$Y_{gr}\f$ | 2.0 | Depth to the deep-ground boundary, m |
+| `GROUND_TEMPERATURE` | \f$T_{gr}\f$ | 12.0 | Deep-ground temperature, °C (or `TIMESERIES`) |
+| `HYPORHEIC_VELOCITY` | \f$v_{hyp}\f$ | 0.0 | Exchange velocity across the interface, m/s |
+| `SEDIMENT_DENSITY` | \f$\rho_s\f$ | 1670 | Bed bulk density, kg/m³ |
+| `SEDIMENT_SPECIFIC_HEAT` | \f$c_s\f$ | 1807 | Bed specific heat, J/kg/K |
+| `INITIAL_TEMPERATURE` | — | \f$T_{gr}\f$ | Initial bed temperature, °C |
+
+The default sediment properties describe **streambed sediment** and are
+deliberately different from the `LAYER_CONDUCTION` defaults of §9.3.10, which
+describe a bioretention soil column. They are different materials and a
+single pair of numbers cannot stand for both.
+
+Every length, diffusivity and material property is **refused** at zero or
+below rather than clamped, because each is a divisor or a capacity: a
+silently repaired zero produces either an infinite conductance or a massless
+bed that tracks the water exactly, both of which look like a working model.
+`SOLUTE_DIFFUSIVITY` and `HYPORHEIC_VELOCITY` accept zero, each selecting a
+meaningful configuration (conduction-only transport, and conduction-only
+exchange respectively).
+
+`GROUND_TEMPERATURE` has a default but the engine **warns** when a deck
+leaves it unstated: for a buried conduit it is frequently the largest term in
+the balance, so the default is unlikely to be what was meant.
+
+**A worked bed configuration** — a buried sewer in cool ground with modest
+hyporheic exchange:
+
+```
+[HEAT_FLUXES]
+SEDIMENT_EXCHANGE      ON
+
+[SEDIMENT_EXCHANGE]
+GROUND_TEMPERATURE     GLOBAL 11.5
+GROUND_DEPTH           GLOBAL 2.0
+BED_THICKNESS          GLOBAL 0.25
+THERMAL_DIFFUSIVITY    GLOBAL 1.1e-6
+HYPORHEIC_VELOCITY     GLOBAL 5.0e-6
+SOLUTE_DIFFUSIVITY     GLOBAL 1.0e-9
+```
+
+### 9.3.12 Parameter reference
+
+The six sections of the heat component, with every key, its symbol, its
+default and its scope. Rows are `  [name] `; the scope
+token is **required** on every row of every section. `GLOBAL` is always
+accepted; where a key takes `TAG name`, `LINK name` or `NODE name`, the
+per-element value overrides the global for that element (Chapter 11 §11.4).
+
+**`[HEAT_SOURCES]`** (@ref engine_manual_sect_HEAT_SOURCES) — inlet
+temperature per water source, °C, in \f$[-50, 100]\f$; default 20 °C for a
+source with no row.
+
+| Source | Scope | Default | Meaning |
+|---|---|---|---|
+| `RAINFALL` | `GLOBAL` | 20.0 | Rain on subcatchments and on the 2D mesh |
+| `DWF` | `GLOBAL`, `NODE` | 20.0 | Dry-weather flow |
+| `GW` | `GLOBAL` | 20.0 | Groundwater inflow from the legacy aquifers |
+| `RDII` | `GLOBAL` | 20.0 | Rainfall-derived inflow and infiltration |
+| `EXTERNAL_INFLOW` | `GLOBAL`, `NODE` | 20.0 | `[INFLOWS]` |
+| `IFACE` | `GLOBAL` | 20.0 | Interface-file inflow |
+| `INITIAL_STATE` | `GLOBAL` | 20.0 | Water in the network, and on the mesh, at \f$t = 0\f$ |
+
+`TIMESERIES` temperatures, `SUBCATCH` scope and `EDGE_BC` scope are refused
+with the phase that delivers them.
+
+**`[HEAT_FLUXES]`** (@ref engine_manual_sect_HEAT_FLUXES) — module toggles,
+one row per module, `ON` or `OFF` (`YES` and `NO` accepted); no scope token.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `SURFACE_EXCHANGE` | `OFF` | Latent and sensible exchange (§9.3.4, §9.3.5) |
+| `RADIATIVE_EXCHANGE` | `OFF` | The four radiative terms (§9.3.6) |
+| `LAYER_CONDUCTION` | `OFF` | LID layer conduction (§9.3.10) |
+| `SEDIMENT_EXCHANGE` | `OFF` | The bed zone (§9.3.11) |
+| `DRY_ELEMENT_TEMPERATURE` | `HOLD` | `HOLD`, `AIR` or `DEFAULT`: what a dry element reports — the last wet value, the air temperature, or 20 °C |
+
+**`[RADIATIVE_FLUXES]`** (@ref engine_manual_sect_RADIATIVE_FLUXES)
+
+| Key | Symbol | Default | Scope | Meaning |
+|---|---|---|---|---|
+| `SHORTWAVE` | \f$J_{in}\f$ | 0.0 | `GLOBAL` only | Incoming solar, W/m², as a constant; or `TIMESERIES name`; or `COMPUTED` (§9.3.7). The three spellings are mutually exclusive |
+| `ALBEDO` | \f$R_s\f$ | 0.0 | `GLOBAL`, `TAG`, `LINK`, `NODE` | Shortwave reflectance of the water surface, in \f$[0,1]\f$ |
+| `SHADE_FACTOR` | \f$f_s\f$ | 0.0 | `GLOBAL`, `TAG`, `LINK`, `NODE` | Fraction of insolation blocked; 0 = unshaded |
+| `SKY_VIEW` | \f$f_{sky}\f$ | 1.0 | `GLOBAL`, `TAG`, `LINK`, `NODE` | Fraction of the hemisphere that is sky |
+| `EMISS_WATER` | \f$\varepsilon_w\f$ | 0.97 | `GLOBAL`, `TAG`, `LINK`, `NODE` | Longwave emissivity of water |
+| `EMISS_LANDCOVER` | \f$\varepsilon_{lc}\f$ | 0.97 | `GLOBAL`, `TAG`, `LINK`, `NODE` | Longwave emissivity of the surroundings |
+| `LANDCOVER_TEMPERATURE` | \f$T_{lc}\f$ | air temperature | `GLOBAL`, `TAG`, `LINK`, `NODE` | Temperature of the surroundings radiating to the water, °C; unset means "use the air temperature" |
+| `ATM_EMISS_COEFF` | \f$A_a\f$ | 0.5 | `GLOBAL` only | Brunt clear-sky coefficient, in \f$[0,1]\f$ |
+| `ATM_LW_REFLECTION` | \f$R_L\f$ | 0.03 | `GLOBAL` only | Longwave reflectance of the surface, in \f$[0,1]\f$ |
+
+Fractions are refused outside \f$[0,1]\f$ rather than clamped — a 97 typed
+for an emissivity of 0.97 would otherwise scale every longwave term by a
+hundred.
+
+**`[SOLAR_RADIATION]`** (@ref engine_manual_sect_SOLAR_RADIATION) — site
+geometry and the Bird–Hulstrom atmosphere, read only under
+`SHORTWAVE GLOBAL COMPUTED`; every row is `GLOBAL`.
+
+| Key | Symbol | Default | Meaning |
+|---|---|---|---|
+| `LATITUDE` | \f$\phi\f$ | required | Degrees, +N, in \f$[-90, 90]\f$; an error if absent under `COMPUTED`. Not taken from the `[TEMPERATURE]` snowmelt line |
+| `LONGITUDE` | \f$\lambda\f$ | required | Degrees, +E, in \f$[-180, 180]\f$; an error if absent under `COMPUTED` |
+| `TIMEZONE` | — | 0 | Hours from UTC, in \f$[-14, 14]\f$; absent means the deck clock is UTC, and the engine **warns**, because a wrong offset shifts the whole diurnal curve |
+| `ELEVATION` | \f$z\f$ | 0.0 | Site elevation, m, in \f$[-500, 9000]\f$ |
+| `TURBIDITY_380` | \f$\tau_{380}\f$ | 0.30 | Aerosol optical depth at 380 nm |
+| `TURBIDITY_500` | \f$\tau_{500}\f$ | 0.20 | Aerosol optical depth at 500 nm |
+| `PRECIP_WATER` | \f$w_p\f$ | 1.42 | Precipitable water vapour, cm |
+| `OZONE` | \f$O_3\f$ | 0.34 | Ozone column, cm at NTP |
+| `GROUND_ALBEDO` | \f$\rho_g\f$ | 0.20 | Surface albedo for the sky–ground reflection term, in \f$[0,1]\f$ |
+
+A `[SOLAR_RADIATION]` section in a model whose `SHORTWAVE` is not `COMPUTED`
+is harmless and warned about: the coordinates are read by nothing.
+
+**`[CLOUD_COVER]`** (@ref engine_manual_sect_CLOUD_COVER) — every row is
+`GLOBAL`.
+
+| Key | Symbol | Default | Meaning |
+|---|---|---|---|
+| `FRACTION` | \f$C\f$ | 0.0 | Cloud fraction in \f$[0,1]\f$, or `TIMESERIES name`; the series path clamps at run time, the constant is refused outside the range |
+| `SW_ATTEN_K` | \f$k\f$ | 0.75 | Kasten–Czeplak shortwave attenuation coefficient |
+| `SW_ATTEN_N` | \f$n\f$ | 3.4 | Kasten–Czeplak exponent |
+| `LW_CLOUD_K` | \f$k_{lw}\f$ | 0.17 | Bolz longwave cloud coefficient |
+
+Coefficients without a `FRACTION` row leave the cloud fraction at zero, where
+both corrections are the identity; the engine says so. A `[CLOUD_COVER]`
+applied on top of a measured `SHORTWAVE TIMESERIES` attenuates the clouds
+twice and is warned about.
+
+**`[SEDIMENT_EXCHANGE]`** (@ref engine_manual_sect_SEDIMENT_EXCHANGE) — the
+bed zone of §9.3.11, whose table already lists these keys. Scopes: `GLOBAL`,
+`TAG` and `LINK` for every attribute but `INITIAL_TEMPERATURE`, which is
+`GLOBAL` only; `NODE` is refused because the bed exists beneath conduits
+only.
+
+| Key | Symbol | Default | Meaning |
+|---|---|---|---|
+| `THERMAL_DIFFUSIVITY` | \f$\alpha_{sed}\f$ | 1.0e-6 | Bed thermal diffusivity, m²/s; must be positive |
+| `SOLUTE_DIFFUSIVITY` | \f$D_{sed}\f$ | 1.0e-9 | Bed effective solute diffusivity, m²/s; zero selects advection-only exchange |
+| `BED_THICKNESS` | \f$Y_{bed}\f$ | 0.20 | Bed layer thickness, m; positive |
+| `GROUND_DEPTH` | \f$Y_{gr}\f$ | 2.0 | Depth to the deep-ground boundary, m; positive |
+| `GROUND_TEMPERATURE` | \f$T_{gr}\f$ | 12.0 | Deep-ground temperature, °C, or `GLOBAL TIMESERIES name`; the engine warns when it is left at the default |
+| `HYPORHEIC_VELOCITY` | \f$v_{hyp}\f$ | 0.0 | Exchange velocity across the bed interface, m/s; non-negative, zero is conduction only |
+| `SEDIMENT_DENSITY` | \f$\rho_s\f$ | 1670 | Bed bulk density, kg/m³; positive |
+| `SEDIMENT_SPECIFIC_HEAT` | \f$c_s\f$ | 1807 | Bed specific heat, J/kg/K; positive |
+| `INITIAL_TEMPERATURE` | \f$T_{bed,0}\f$ | \f$T_{gr}\f$ | Initial bed temperature, °C; the ground temperature when unset |
+
+
+
+### 9.3.13 A worked configuration
+
+A shaded urban stream reach with computed solar forcing, partial cloud, and
+both exchange modules active:
+
+```
+[PROCESS_COMPONENTS]
+org.hydrocouple.openswmm.heat  config="model.heat"
+```
+
+```
+;; model.heat
+[HEAT_SOURCES]
+DWF             GLOBAL   18.5
+EXTERNAL_INFLOW GLOBAL   14.0
+INITIAL_STATE   GLOBAL   15.0
+
+[HEAT_FLUXES]
+SURFACE_EXCHANGE    ON
+RADIATIVE_EXCHANGE  ON
+
+[RADIATIVE_FLUXES]
+SHORTWAVE     GLOBAL   COMPUTED
+ALBEDO        GLOBAL   0.06
+SHADE_FACTOR  GLOBAL   0.65
+SKY_VIEW      GLOBAL   0.35
+EMISS_WATER   GLOBAL   0.97
+
+[SOLAR_RADIATION]
+LATITUDE      GLOBAL   41.88
+LONGITUDE     GLOBAL  -87.63
+TIMEZONE      GLOBAL   -6
+ELEVATION     GLOBAL   181.0
+
+[CLOUD_COVER]
+FRACTION      GLOBAL   0.4
+```
+
+The `[HEAT_FLUXES]` rows are the one exception: they are ` ON|OFF`
+with no scope token, and the listing already has them right. With the
+per-element scopes of Chapter 11 §11.4 the same reach could shade one
+conduit differently — `SHADE_FACTOR LINK C12 0.95` — while the rest of the
+network keeps the global value.
+
+
+
+Note that `SHADE_FACTOR 0.65` and `SKY_VIEW 0.35` are consistent with one
+another — riparian canopy blocking roughly two-thirds of the sky both shades
+the shortwave and replaces sky longwave with canopy longwave. They are
+independent keys, and setting one without the other is a common way to
+produce a reach that is shaded from the sun but still radiating to an open
+sky.
+
+## 9.4 Engine Coverage
+
+Both reserved species are carried by all three transport engines:
+
+| | `LEGACY` | `EULERIAN_ARD` | `LAGRANGIAN` |
+|---|---|---|---|
+| Water age | yes | yes | yes |
+| Temperature | yes | yes | yes |
+| Dispersion of either | n/a | yes | yes |
+| Surface + radiative fluxes | yes | yes | yes |
+| Bed zone (§9.3.11) | per link | per cell | per link |
+
+The bed zone is resolved differently by engine. Under `EULERIAN_ARD` each
+mesh cell has its own bed slice, so a bed beneath a long conduit resolves the
+same along-length variation the water above it does. Under `LEGACY` and
+`LAGRANGIAN` the bed is one well-mixed body per conduit; the Lagrangian
+engine solves the exchange against the volume-weighted parcel mean and
+applies the resulting increment uniformly, which preserves the along-link
+profile the parcels carry.
+
+Where dispersion is active, temperature and age are dispersed with the **same
+coefficient** as the solutes. In shear-dominated open-channel flow the
+dispersion coefficient is a property of the velocity field rather than of the
+transported quantity (§7.3.3), so applying a separate coefficient to heat
+would be less physical, not more conservative.
+
+Temperature is **exempt** from three behaviours the other rows have, and each
+exemption is deliberate:
+
+- **No aging.** The \f$+\Delta t\f$ advance is the age row's law alone.
+- **No decay.** First-order decay applies to pollutants, not to temperature.
+- **No non-negativity clamp.** Sub-zero °C is a legal state — 0 is not
+  special for temperature the way it is for a mass, so the floor that keeps
+  concentrations non-negative is not applied to the temperature row in any
+  engine.
+
+## 9.5 Implementation
+
+Water age is implemented in
+`src/engine/transport/components/WaterAgeModule/`, heat in
+`src/engine/transport/components/HeatModule/` (`HeatComponent.cpp` for the
+configuration, `HeatLid.cpp` for layer conduction), and the flux modules in
+`HeatFluxModules/` — `SurfaceExchange` for the latent and sensible terms and
+the relaxation stepper, `RadiativeExchange` for the four radiative terms,
+`SolarRadiation` for the Spencer, Kasten–Young and Bird–Hulstrom
+computations, and `BedExchange` for the bed zone's conductances, its coupled
+two-body stepper and the two-body solute exchange (`BedZoneData.hpp` holds
+its configuration and state). Both reserved rows are allocated by the transport engines'
+species-row layout: `ArdEngine.cpp` for the Eulerian mesh, and `rowLayout()`
+in `LagrangianSolver.hpp` for the segment store.
+
+C API surfaces are declared in @ref openswmm_waterage.h and
+@ref openswmm_heat.h; the transport-engine configuration itself is in
+@ref openswmm_transport.h.
diff --git a/docs/manuals/reference/quality/sections/References.md b/docs/manuals/reference/quality/sections/References.md
index 5cb25a5bc..23a2342fa 100644
--- a/docs/manuals/reference/quality/sections/References.md
+++ b/docs/manuals/reference/quality/sections/References.md
@@ -89,11 +89,25 @@ R.C. Johanson, *Hydrologic Simulation Program -- Fortran: User's Manual
 for Release 11*, U.S. Environmental Protection Agency, Office of
 Research and Development, Athens, GA, 1997.
 
+Bencala, K.E. and Walters, R.A., "Simulation of Solute Transport in a
+Mountain Pool-and-Riffle Stream: A Transient Storage Model",
+*Water Resources Research*, 19(3), 718-724, 1983.
+
+Bird, R.E. and Hulstrom, R.L., *A Simplified Clear Sky Model for Direct
+and Diffuse Insolation on Horizontal Surfaces*, Technical Report
+SERI/TR-642-761, Solar Energy Research Institute, Golden, CO, 1981.
+
+Bolz, H.M., "Die Abhangigkeit der infraroten Gegenstrahlung von der
+Bewolkung", *Zeitschrift fur Meteorologie*, Vol. 3, pp. 201-203, 1949.
+
 Brezonik, P.L., "Nutrients and Other Biologically Active Substances in
 Atmo­spheric Precipitation," Proceedings Symposium on Atmospheric
 Contribution to the Chemistry of Lake Waters, International Association
 Great Lakes Research, September 1975, pp. 166-186.
 
+Brunt, D., "Notes on Radiation in the Atmosphere", *Quarterly Journal of
+the Royal Meteorological Society*, Vol. 58, No. 247, pp. 389-420, 1932.
+
 Burton, G.A. and Pitt, R.E., *Stormwater Effects Handbook*. Lewis
 Publishers, CRC Press, Boca Raton, FL, 2002.
 
@@ -142,6 +156,9 @@ time-dependent advection-dominated partial differential equations",
 
 Ferguson, B., *Porous Pavements*, CRC Press, Boca Raton, 2005.
 
+Fischer, H.B., List, E.J., Koh, R.C.Y., Imberger, J., and Brooks, N.H.,
+*Mixing in Inland and Coastal Waters*, Academic Press, New York, 1979.
+
 Fletcher, T.D., Shuster, W., Hunt, W.F., Ashley, R., Butler, D., Arthur,
 S., Trowsdale, S., Barraud, S., Semadeni-Davies, A., Bertrand-Krajewski,
 J-L., Mikkelsen, P.S., Rivard, G., Uhl, M., Dagenais, D., and Viklander,
@@ -155,6 +172,10 @@ Graf, W.H., *Hydraulics of Sediment Transport*, McGraw-Hill, New York,
 Haan, C.T., Barfield, B.J. and J.C. Hayes, *Design Hydrology and
 Sedimentology for Small Catchments*, Academic Press, New York, 1994.
 
+Hairer, E. and Wanner, G., *Solving Ordinary Differential Equations II:
+Stiff and Differential-Algebraic Problems*, 2nd ed., Springer-Verlag,
+Berlin, 1996.
+
 Haseltine, T.R., "Addition of Garbage to Sewage," *Water and Sewage
 Works*, 1950.
 
@@ -246,6 +267,14 @@ System Overflow Based on Historical Rain Series," Proc. Third
 International Conference on Urban Storm Drainage, Chalmers University,
 Goteborg, Sweden, June 1984, Vol. 3, pp. 909-918.
 
+Kasten, F. and Czeplak, G., "Solar and Terrestrial Radiation Dependent
+on the Amount and Type of Cloud", *Solar Energy*, Vol. 24, No. 2, pp.
+177-189, 1980.
+
+Kasten, F. and Young, A.T., "Revised Optical Air Mass Tables and
+Approximation Formula", *Applied Optics*, Vol. 28, No. 22, pp.
+4735-4738, 1989.
+
 Kluesener, J.W. and Lee, G.F., "Nutrient Loading from a Separate Storm
 Sewer in Madison, Wisconsin," *Journal Water Pollution Control
 Federation*, Vol. 46, No. 5, May 1974, pp. 920-936.
@@ -267,6 +296,10 @@ Lee, J., Borst, M., Brown, R., Rossman, L., and Simon, M., "Modeling the
 Hydrologic Processes of a Permeable Pavement System", Journal of
 Hydrologic Engineering, Vol. 20, No. 5, 2015.
 
+Leonard, B.P., "The ULTIMATE Conservative Difference Scheme Applied to
+Unsteady One-Dimensional Advection", *Computer Methods in Applied
+Mechanics and Engineering*, Vol. 88, No. 1, pp. 17-74, 1991.
+
 Li, H. and Davis, A.P., "Water Quality Improvement through Reductions of
 Pollutant Loads using Bioretention", *Journal of Environmental
 Engineering*, Vol.135, No.8, 2009, pp. 567-576.
@@ -418,6 +451,11 @@ Rossman, L.A., "Modeling Low Impact Development Alternatives with SWMM"
 in *Dynamic Modeling of Urban Systems, Monograph 18* (W. James, editor),
 CHI, Guelph, Ontario, 2010.
 
+Runkel, R.L., *One-Dimensional Transport with Inflow and Storage
+(OTIS): A Solute Transport Model for Streams and Rivers*,
+Water-Resources Investigations Report 98-4018, U.S. Geological
+Survey, Denver, CO, 1998.
+
 Sartor, J.D. and Boyd, G.B., "Water Pollution Aspects of Street Surface
 Con­taminants," EPA-R2-72-081 (NTIS PB-214408), U.S. Environmental
 Protection Agency, Washington, DC, November 1972.
@@ -430,6 +468,10 @@ Shaheen, D.G., "Contributions of Urban Roadway Usage to Water
 Pollution," EPA-600/2-75-004 (NTIS PB-245854), U.S. Environmental
 Protection Agency, Washington, DC, April l975.
 
+Shang, F., Uber, J.G., and Rossman, L.A., *EPANET Multi-Species
+Extension User's Manual*, EPA/600/S-07/021, U.S. Environmental Protection
+Agency, Cincinnati, OH, 2008.
+
 Simons, D.B. and Senturk, F., *Sediment Transport Technology*, Water
 Resources Publications, Ft. Collins, CO, 1977.
 
@@ -448,6 +490,9 @@ Gainesville, 1979.
 Sonnen, M.B., "Urban Runoff Quality: Information Needs," *Journal of the
 Tech­nical Councils, ASCE*, Vol. 106, No. TC1, August 1980, pp. 29-40.
 
+Spencer, J.W., "Fourier Series Representation of the Position of the
+Sun", *Search*, Vol. 2, No. 5, p. 172, 1971.
+
 Sutherland, R.C. and Jelen, S.J., "Contrary to Conventional Wisdom,
 Street Sweeping Can Be an Effective BMP," Chapter 9 in *Advances in
 Modeling the Management of Stormwater Impacts*, W. James, ed., Proc. of
@@ -459,6 +504,10 @@ Strecker, E.W., Quigley, M.M., Urbonas, B.R., Jones, J.E. and Clary,
 J.K., "Determining Urban Storm Water BMP Effectiveness," *Journal of
 Water Resources Planning and Management*, 127(3), 2001, pp.144-149.
 
+Taylor, G.I., "Dispersion of Soluble Matter in Solvent Flowing Slowly
+Through a Tube", *Proceedings of the Royal Society of London, Series A*,
+Vol. 219, No. 1137, pp. 186-203, 1953.
+
 Tchobanoglous, G. and Burton, F., *Wastewater Engineering, Treatment,
 Disposal, Reuse*, Third Edition, Metcalf & Eddy, Inc., Boston, MA, 1991.
 
diff --git a/docs/manuals/user/figures/figure1_1_urban_sewershed.png b/docs/manuals/user/figures/figure1_1_urban_sewershed.png
deleted file mode 100644
index 658c8c5bb..000000000
Binary files a/docs/manuals/user/figures/figure1_1_urban_sewershed.png and /dev/null differ
diff --git a/docs/manuals/user/figures/figure2_1_example_study_area.png b/docs/manuals/user/figures/figure2_1_example_study_area.png
deleted file mode 100644
index 227ccc92e..000000000
Binary files a/docs/manuals/user/figures/figure2_1_example_study_area.png and /dev/null differ
diff --git a/docs/manuals/user/figures/figure2_2_project_defaults_dialog.png b/docs/manuals/user/figures/figure2_2_project_defaults_dialog.png
deleted file mode 100644
index 0ce378ef2..000000000
Binary files a/docs/manuals/user/figures/figure2_2_project_defaults_dialog.png and /dev/null differ
diff --git a/docs/manuals/user/figures/figure2_3_map_options_dialog.png b/docs/manuals/user/figures/figure2_3_map_options_dialog.png
deleted file mode 100644
index 2f3369d82..000000000
Binary files a/docs/manuals/user/figures/figure2_3_map_options_dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/3d-graph-example.png b/docs/manuals/user/images/3d-graph-example.png
deleted file mode 100644
index 945c88ea8..000000000
Binary files a/docs/manuals/user/images/3d-graph-example.png and /dev/null differ
diff --git a/docs/manuals/user/images/Arch Shape.png b/docs/manuals/user/images/Arch Shape.png
deleted file mode 100644
index bbc183e50..000000000
Binary files a/docs/manuals/user/images/Arch Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Areal Depletion Curve.png b/docs/manuals/user/images/Areal Depletion Curve.png
deleted file mode 100644
index b1d2ceabd..000000000
Binary files a/docs/manuals/user/images/Areal Depletion Curve.png and /dev/null differ
diff --git a/docs/manuals/user/images/Baskethandle Shape.png b/docs/manuals/user/images/Baskethandle Shape.png
deleted file mode 100644
index 86a7345ad..000000000
Binary files a/docs/manuals/user/images/Baskethandle Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Bio-retention Cell.png b/docs/manuals/user/images/Bio-retention Cell.png
deleted file mode 100644
index 015f9b3a2..000000000
Binary files a/docs/manuals/user/images/Bio-retention Cell.png and /dev/null differ
diff --git a/docs/manuals/user/images/Catenary Shape.png b/docs/manuals/user/images/Catenary Shape.png
deleted file mode 100644
index 40113865c..000000000
Binary files a/docs/manuals/user/images/Catenary Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Circular Conduit Shape.png b/docs/manuals/user/images/Circular Conduit Shape.png
deleted file mode 100644
index 52d284355..000000000
Binary files a/docs/manuals/user/images/Circular Conduit Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Circular Force Main Shape.png b/docs/manuals/user/images/Circular Force Main Shape.png
deleted file mode 100644
index e8222dda7..000000000
Binary files a/docs/manuals/user/images/Circular Force Main Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Conceptual View of Surface Runoff.png b/docs/manuals/user/images/Conceptual View of Surface Runoff.png
deleted file mode 100644
index 52e7c55d4..000000000
Binary files a/docs/manuals/user/images/Conceptual View of Surface Runoff.png and /dev/null differ
diff --git a/docs/manuals/user/images/Concrete Box Culvert.png b/docs/manuals/user/images/Concrete Box Culvert.png
deleted file mode 100644
index c88964add..000000000
Binary files a/docs/manuals/user/images/Concrete Box Culvert.png and /dev/null differ
diff --git a/docs/manuals/user/images/Conduit%20Shape%20Circular.png b/docs/manuals/user/images/Conduit%20Shape%20Circular.png
deleted file mode 100644
index c96ef4d0e..000000000
Binary files a/docs/manuals/user/images/Conduit%20Shape%20Circular.png and /dev/null differ
diff --git a/docs/manuals/user/images/Custom Closed Shape.png b/docs/manuals/user/images/Custom Closed Shape.png
deleted file mode 100644
index a9f5a73bc..000000000
Binary files a/docs/manuals/user/images/Custom Closed Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Data Series Selection dialog.jpg b/docs/manuals/user/images/Data Series Selection dialog.jpg
deleted file mode 100644
index 02481184f..000000000
Binary files a/docs/manuals/user/images/Data Series Selection dialog.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Diagram showing various physical objects.png b/docs/manuals/user/images/Diagram showing various physical objects.png
deleted file mode 100644
index 938c22370..000000000
Binary files a/docs/manuals/user/images/Diagram showing various physical objects.png and /dev/null differ
diff --git a/docs/manuals/user/images/Dual Drainage System.png b/docs/manuals/user/images/Dual Drainage System.png
deleted file mode 100644
index 188c2c15d..000000000
Binary files a/docs/manuals/user/images/Dual Drainage System.png and /dev/null differ
diff --git a/docs/manuals/user/images/EPA-Logo.jpg b/docs/manuals/user/images/EPA-Logo.jpg
deleted file mode 100644
index 5ebe99ccd..000000000
Binary files a/docs/manuals/user/images/EPA-Logo.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Egg Shape.png b/docs/manuals/user/images/Egg Shape.png
deleted file mode 100644
index b2662da00..000000000
Binary files a/docs/manuals/user/images/Egg Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Example Study Area Diagram.png b/docs/manuals/user/images/Example Study Area Diagram.png
deleted file mode 100644
index 227ccc92e..000000000
Binary files a/docs/manuals/user/images/Example Study Area Diagram.png and /dev/null differ
diff --git a/docs/manuals/user/images/Filled Circular Shape.png b/docs/manuals/user/images/Filled Circular Shape.png
deleted file mode 100644
index f44b69bad..000000000
Binary files a/docs/manuals/user/images/Filled Circular Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Gothic Shape.png b/docs/manuals/user/images/Gothic Shape.png
deleted file mode 100644
index a499f1309..000000000
Binary files a/docs/manuals/user/images/Gothic Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Graph of TSS concentration for Subcatchments S1 and S3.png b/docs/manuals/user/images/Graph of TSS concentration for Subcatchments S1 and S3.png
deleted file mode 100644
index cad0b7bdb..000000000
Binary files a/docs/manuals/user/images/Graph of TSS concentration for Subcatchments S1 and S3.png and /dev/null differ
diff --git a/docs/manuals/user/images/Graph showing flow for Link C1 and Link C2.png b/docs/manuals/user/images/Graph showing flow for Link C1 and Link C2.png
deleted file mode 100644
index 32e92f53d..000000000
Binary files a/docs/manuals/user/images/Graph showing flow for Link C1 and Link C2.png and /dev/null differ
diff --git a/docs/manuals/user/images/Green Roof.jpg b/docs/manuals/user/images/Green Roof.jpg
deleted file mode 100644
index 110e6ce5f..000000000
Binary files a/docs/manuals/user/images/Green Roof.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Group Editor Dialog.png b/docs/manuals/user/images/Group Editor Dialog.png
deleted file mode 100644
index fdb73be86..000000000
Binary files a/docs/manuals/user/images/Group Editor Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Horizontal Ellipse Shape.jpg b/docs/manuals/user/images/Horizontal Ellipse Shape.jpg
deleted file mode 100644
index 62ba3d4ae..000000000
Binary files a/docs/manuals/user/images/Horizontal Ellipse Shape.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Horseshoe Shape.png b/docs/manuals/user/images/Horseshoe Shape.png
deleted file mode 100644
index 7bc027001..000000000
Binary files a/docs/manuals/user/images/Horseshoe Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Infiltration Trench.jpg b/docs/manuals/user/images/Infiltration Trench.jpg
deleted file mode 100644
index 91c29530a..000000000
Binary files a/docs/manuals/user/images/Infiltration Trench.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Irregular Channel Shape.png b/docs/manuals/user/images/Irregular Channel Shape.png
deleted file mode 100644
index 2d7a1c4c2..000000000
Binary files a/docs/manuals/user/images/Irregular Channel Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/LID Conceptual Diagram.png b/docs/manuals/user/images/LID Conceptual Diagram.png
deleted file mode 100644
index cb6000611..000000000
Binary files a/docs/manuals/user/images/LID Conceptual Diagram.png and /dev/null differ
diff --git a/docs/manuals/user/images/Land Use Assignment Dialog.png b/docs/manuals/user/images/Land Use Assignment Dialog.png
deleted file mode 100644
index 194333ad1..000000000
Binary files a/docs/manuals/user/images/Land Use Assignment Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Land Use Editor - Buildup Tab.png b/docs/manuals/user/images/Land Use Editor - Buildup Tab.png
deleted file mode 100644
index 7e3170774..000000000
Binary files a/docs/manuals/user/images/Land Use Editor - Buildup Tab.png and /dev/null differ
diff --git a/docs/manuals/user/images/Land Use Editor Dialog.png b/docs/manuals/user/images/Land Use Editor Dialog.png
deleted file mode 100644
index 9b5d607ed..000000000
Binary files a/docs/manuals/user/images/Land Use Editor Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Map Options Dialog.png b/docs/manuals/user/images/Map Options Dialog.png
deleted file mode 100644
index 2f3369d82..000000000
Binary files a/docs/manuals/user/images/Map Options Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Map showing subcatchments.png b/docs/manuals/user/images/Map showing subcatchments.png
deleted file mode 100644
index 963a0306a..000000000
Binary files a/docs/manuals/user/images/Map showing subcatchments.png and /dev/null differ
diff --git a/docs/manuals/user/images/Modified Baskethandle Shape.png b/docs/manuals/user/images/Modified Baskethandle Shape.png
deleted file mode 100644
index 268aded31..000000000
Binary files a/docs/manuals/user/images/Modified Baskethandle Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Natural Channel Transect.png b/docs/manuals/user/images/Natural Channel Transect.png
deleted file mode 100644
index bf7877f73..000000000
Binary files a/docs/manuals/user/images/Natural Channel Transect.png and /dev/null differ
diff --git a/docs/manuals/user/images/Parabolic Shape.png b/docs/manuals/user/images/Parabolic Shape.png
deleted file mode 100644
index 4a5f857c6..000000000
Binary files a/docs/manuals/user/images/Parabolic Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Permeable Pavement.jpg b/docs/manuals/user/images/Permeable Pavement.jpg
deleted file mode 100644
index da0e5d776..000000000
Binary files a/docs/manuals/user/images/Permeable Pavement.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Pollutant Editor Dialog.png b/docs/manuals/user/images/Pollutant Editor Dialog.png
deleted file mode 100644
index 6b1f69139..000000000
Binary files a/docs/manuals/user/images/Pollutant Editor Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Power Shape.png b/docs/manuals/user/images/Power Shape.png
deleted file mode 100644
index 5cb531a70..000000000
Binary files a/docs/manuals/user/images/Power Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Profile Plot Selection Dialog.png b/docs/manuals/user/images/Profile Plot Selection Dialog.png
deleted file mode 100644
index bfbd6cc03..000000000
Binary files a/docs/manuals/user/images/Profile Plot Selection Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Project Defaults Dialog.png b/docs/manuals/user/images/Project Defaults Dialog.png
deleted file mode 100644
index 0ce378ef2..000000000
Binary files a/docs/manuals/user/images/Project Defaults Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Property Editor for Subcatchment.png b/docs/manuals/user/images/Property Editor for Subcatchment.png
deleted file mode 100644
index 4bb31359c..000000000
Binary files a/docs/manuals/user/images/Property Editor for Subcatchment.png and /dev/null differ
diff --git a/docs/manuals/user/images/RDII Unit Hydrograph.png b/docs/manuals/user/images/RDII Unit Hydrograph.png
deleted file mode 100644
index 1e4b3568e..000000000
Binary files a/docs/manuals/user/images/RDII Unit Hydrograph.png and /dev/null differ
diff --git a/docs/manuals/user/images/Rain Barrel.jpg b/docs/manuals/user/images/Rain Barrel.jpg
deleted file mode 100644
index 24d0da37a..000000000
Binary files a/docs/manuals/user/images/Rain Barrel.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Rain Garden.jpg b/docs/manuals/user/images/Rain Garden.jpg
deleted file mode 100644
index 87550332d..000000000
Binary files a/docs/manuals/user/images/Rain Garden.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Rectangular Closed Shape.jpg b/docs/manuals/user/images/Rectangular Closed Shape.jpg
deleted file mode 100644
index d4ce0313d..000000000
Binary files a/docs/manuals/user/images/Rectangular Closed Shape.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Rectangular Open Shape.png b/docs/manuals/user/images/Rectangular Open Shape.png
deleted file mode 100644
index 4e1d06a97..000000000
Binary files a/docs/manuals/user/images/Rectangular Open Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Rectangular-Round Shape.jpg b/docs/manuals/user/images/Rectangular-Round Shape.jpg
deleted file mode 100644
index e7937779b..000000000
Binary files a/docs/manuals/user/images/Rectangular-Round Shape.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Rectangular-Triangular Shape.png b/docs/manuals/user/images/Rectangular-Triangular Shape.png
deleted file mode 100644
index d73b1b4a0..000000000
Binary files a/docs/manuals/user/images/Rectangular-Triangular Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Rooftop Disconnection.jpg b/docs/manuals/user/images/Rooftop Disconnection.jpg
deleted file mode 100644
index 820069abc..000000000
Binary files a/docs/manuals/user/images/Rooftop Disconnection.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/SWMM Main Window displaying simulation results.png b/docs/manuals/user/images/SWMM Main Window displaying simulation results.png
deleted file mode 100644
index 214028387..000000000
Binary files a/docs/manuals/user/images/SWMM Main Window displaying simulation results.png and /dev/null differ
diff --git a/docs/manuals/user/images/Semi-Circular Shape.png b/docs/manuals/user/images/Semi-Circular Shape.png
deleted file mode 100644
index 8e6660a80..000000000
Binary files a/docs/manuals/user/images/Semi-Circular Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Semi-Elliptical Shape.png b/docs/manuals/user/images/Semi-Elliptical Shape.png
deleted file mode 100644
index 3c2aa98eb..000000000
Binary files a/docs/manuals/user/images/Semi-Elliptical Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Simulation Options Dialog - Dynamic Wave Tab.png b/docs/manuals/user/images/Simulation Options Dialog - Dynamic Wave Tab.png
deleted file mode 100644
index 5af9dc6c1..000000000
Binary files a/docs/manuals/user/images/Simulation Options Dialog - Dynamic Wave Tab.png and /dev/null differ
diff --git a/docs/manuals/user/images/Simulation Options Dialog.png b/docs/manuals/user/images/Simulation Options Dialog.png
deleted file mode 100644
index 0ed3ed929..000000000
Binary files a/docs/manuals/user/images/Simulation Options Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Statistics Report Selection Dialog.png b/docs/manuals/user/images/Statistics Report Selection Dialog.png
deleted file mode 100644
index 8a380081f..000000000
Binary files a/docs/manuals/user/images/Statistics Report Selection Dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Statistics Report Summary Page.png b/docs/manuals/user/images/Statistics Report Summary Page.png
deleted file mode 100644
index 4b0b456bc..000000000
Binary files a/docs/manuals/user/images/Statistics Report Summary Page.png and /dev/null differ
diff --git a/docs/manuals/user/images/Street Cross Section.png b/docs/manuals/user/images/Street Cross Section.png
deleted file mode 100644
index 7573ade3d..000000000
Binary files a/docs/manuals/user/images/Street Cross Section.png and /dev/null differ
diff --git a/docs/manuals/user/images/Street or Roadway Shape.jpg b/docs/manuals/user/images/Street or Roadway Shape.jpg
deleted file mode 100644
index 039a556ba..000000000
Binary files a/docs/manuals/user/images/Street or Roadway Shape.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Summary Results for Conduit Surcharge.png b/docs/manuals/user/images/Summary Results for Conduit Surcharge.png
deleted file mode 100644
index 96789630b..000000000
Binary files a/docs/manuals/user/images/Summary Results for Conduit Surcharge.png and /dev/null differ
diff --git a/docs/manuals/user/images/Summary Results for Node Flooding.jpg b/docs/manuals/user/images/Summary Results for Node Flooding.jpg
deleted file mode 100644
index c5aed0421..000000000
Binary files a/docs/manuals/user/images/Summary Results for Node Flooding.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Time Series Editor dialog.png b/docs/manuals/user/images/Time Series Editor dialog.png
deleted file mode 100644
index d1b2a3071..000000000
Binary files a/docs/manuals/user/images/Time Series Editor dialog.png and /dev/null differ
diff --git a/docs/manuals/user/images/Time Series Plot Selection.jpg b/docs/manuals/user/images/Time Series Plot Selection.jpg
deleted file mode 100644
index 8834dcb63..000000000
Binary files a/docs/manuals/user/images/Time Series Plot Selection.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/TitleNotes Editor.png b/docs/manuals/user/images/TitleNotes Editor.png
deleted file mode 100644
index f7e9c5c81..000000000
Binary files a/docs/manuals/user/images/TitleNotes Editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/Trapezoidal Shape.jpg b/docs/manuals/user/images/Trapezoidal Shape.jpg
deleted file mode 100644
index be7de6f47..000000000
Binary files a/docs/manuals/user/images/Trapezoidal Shape.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Triangular Shape.png b/docs/manuals/user/images/Triangular Shape.png
deleted file mode 100644
index c30b7179a..000000000
Binary files a/docs/manuals/user/images/Triangular Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Two-Zone Groundwater Model.png b/docs/manuals/user/images/Two-Zone Groundwater Model.png
deleted file mode 100644
index 5e2f716e0..000000000
Binary files a/docs/manuals/user/images/Two-Zone Groundwater Model.png and /dev/null differ
diff --git a/docs/manuals/user/images/Type 1 Pump Curve Graph.jpg b/docs/manuals/user/images/Type 1 Pump Curve Graph.jpg
deleted file mode 100644
index 3f5a22a49..000000000
Binary files a/docs/manuals/user/images/Type 1 Pump Curve Graph.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Type 2 Pump Curve Graph.jpg b/docs/manuals/user/images/Type 2 Pump Curve Graph.jpg
deleted file mode 100644
index f473b4cbf..000000000
Binary files a/docs/manuals/user/images/Type 2 Pump Curve Graph.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Type 3 Pump Curve Graph.jpg b/docs/manuals/user/images/Type 3 Pump Curve Graph.jpg
deleted file mode 100644
index 319523909..000000000
Binary files a/docs/manuals/user/images/Type 3 Pump Curve Graph.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Type 4 Pump Curve Graph.jpg b/docs/manuals/user/images/Type 4 Pump Curve Graph.jpg
deleted file mode 100644
index 9a850329a..000000000
Binary files a/docs/manuals/user/images/Type 4 Pump Curve Graph.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/Type 5 Pump Curve Graph.png b/docs/manuals/user/images/Type 5 Pump Curve Graph.png
deleted file mode 100644
index 0ae3b582b..000000000
Binary files a/docs/manuals/user/images/Type 5 Pump Curve Graph.png and /dev/null differ
diff --git a/docs/manuals/user/images/Urban Wet Weather Flows Diagram.png b/docs/manuals/user/images/Urban Wet Weather Flows Diagram.png
deleted file mode 100644
index cf138ca15..000000000
Binary files a/docs/manuals/user/images/Urban Wet Weather Flows Diagram.png and /dev/null differ
diff --git a/docs/manuals/user/images/Vegetative Swale.png b/docs/manuals/user/images/Vegetative Swale.png
deleted file mode 100644
index 4c581b329..000000000
Binary files a/docs/manuals/user/images/Vegetative Swale.png and /dev/null differ
diff --git a/docs/manuals/user/images/Vertical Ellipse Shape.png b/docs/manuals/user/images/Vertical Ellipse Shape.png
deleted file mode 100644
index 35169d27c..000000000
Binary files a/docs/manuals/user/images/Vertical Ellipse Shape.png and /dev/null differ
diff --git a/docs/manuals/user/images/Water Elevation Profile Plot from Node J1 to Out1.png b/docs/manuals/user/images/Water Elevation Profile Plot from Node J1 to Out1.png
deleted file mode 100644
index 521b87a53..000000000
Binary files a/docs/manuals/user/images/Water Elevation Profile Plot from Node J1 to Out1.png and /dev/null differ
diff --git a/docs/manuals/user/images/aquifer-editor.png b/docs/manuals/user/images/aquifer-editor.png
deleted file mode 100644
index 141ef1d5d..000000000
Binary files a/docs/manuals/user/images/aquifer-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/backdrop-dimensions.png b/docs/manuals/user/images/backdrop-dimensions.png
deleted file mode 100644
index aa794ba26..000000000
Binary files a/docs/manuals/user/images/backdrop-dimensions.png and /dev/null differ
diff --git a/docs/manuals/user/images/backdrop-image.png b/docs/manuals/user/images/backdrop-image.png
deleted file mode 100644
index ce88d0f9b..000000000
Binary files a/docs/manuals/user/images/backdrop-image.png and /dev/null differ
diff --git a/docs/manuals/user/images/backdrop-selector.png b/docs/manuals/user/images/backdrop-selector.png
deleted file mode 100644
index c6b701a93..000000000
Binary files a/docs/manuals/user/images/backdrop-selector.png and /dev/null differ
diff --git a/docs/manuals/user/images/calibration-data.jpg b/docs/manuals/user/images/calibration-data.jpg
deleted file mode 100644
index d1f41838c..000000000
Binary files a/docs/manuals/user/images/calibration-data.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-adjustments.png b/docs/manuals/user/images/climatology-adjustments.png
deleted file mode 100644
index 439da50fe..000000000
Binary files a/docs/manuals/user/images/climatology-adjustments.png and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-areal.png b/docs/manuals/user/images/climatology-areal.png
deleted file mode 100644
index 2ba639b25..000000000
Binary files a/docs/manuals/user/images/climatology-areal.png and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-evap.png b/docs/manuals/user/images/climatology-evap.png
deleted file mode 100644
index 0ae2116ab..000000000
Binary files a/docs/manuals/user/images/climatology-evap.png and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-snowmelt.png b/docs/manuals/user/images/climatology-snowmelt.png
deleted file mode 100644
index 785ed7945..000000000
Binary files a/docs/manuals/user/images/climatology-snowmelt.png and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-temp.png b/docs/manuals/user/images/climatology-temp.png
deleted file mode 100644
index c3fbc4804..000000000
Binary files a/docs/manuals/user/images/climatology-temp.png and /dev/null differ
diff --git a/docs/manuals/user/images/climatology-wind.png b/docs/manuals/user/images/climatology-wind.png
deleted file mode 100644
index 6385170ba..000000000
Binary files a/docs/manuals/user/images/climatology-wind.png and /dev/null differ
diff --git a/docs/manuals/user/images/conduit-offset.png b/docs/manuals/user/images/conduit-offset.png
deleted file mode 100644
index 950e625a4..000000000
Binary files a/docs/manuals/user/images/conduit-offset.png and /dev/null differ
diff --git a/docs/manuals/user/images/control-rules-editor.png b/docs/manuals/user/images/control-rules-editor.png
deleted file mode 100644
index a959044dd..000000000
Binary files a/docs/manuals/user/images/control-rules-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/copy-chart.png b/docs/manuals/user/images/copy-chart.png
deleted file mode 100644
index f6bd033b6..000000000
Binary files a/docs/manuals/user/images/copy-chart.png and /dev/null differ
diff --git a/docs/manuals/user/images/cross-section-editor.png b/docs/manuals/user/images/cross-section-editor.png
deleted file mode 100644
index 6ae17cbd4..000000000
Binary files a/docs/manuals/user/images/cross-section-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/curb-horizontal.png b/docs/manuals/user/images/curb-horizontal.png
deleted file mode 100644
index 93c338da6..000000000
Binary files a/docs/manuals/user/images/curb-horizontal.png and /dev/null differ
diff --git a/docs/manuals/user/images/curb-inclined.png b/docs/manuals/user/images/curb-inclined.png
deleted file mode 100644
index 8438cb92c..000000000
Binary files a/docs/manuals/user/images/curb-inclined.png and /dev/null differ
diff --git a/docs/manuals/user/images/curb-vertical.png b/docs/manuals/user/images/curb-vertical.png
deleted file mode 100644
index 31c96b8a6..000000000
Binary files a/docs/manuals/user/images/curb-vertical.png and /dev/null differ
diff --git a/docs/manuals/user/images/custom-inlet-curve.png b/docs/manuals/user/images/custom-inlet-curve.png
deleted file mode 100644
index 52542780e..000000000
Binary files a/docs/manuals/user/images/custom-inlet-curve.png and /dev/null differ
diff --git a/docs/manuals/user/images/data-series-selection.png b/docs/manuals/user/images/data-series-selection.png
deleted file mode 100644
index 2aa9940f5..000000000
Binary files a/docs/manuals/user/images/data-series-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/events-editor.png b/docs/manuals/user/images/events-editor.png
deleted file mode 100644
index 618b30724..000000000
Binary files a/docs/manuals/user/images/events-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/figure-11-1.png b/docs/manuals/user/images/figure-11-1.png
deleted file mode 100644
index 9c1131393..000000000
Binary files a/docs/manuals/user/images/figure-11-1.png and /dev/null differ
diff --git a/docs/manuals/user/images/figure-d-2.png b/docs/manuals/user/images/figure-d-2.png
deleted file mode 100644
index b3ff0bb2d..000000000
Binary files a/docs/manuals/user/images/figure-d-2.png and /dev/null differ
diff --git a/docs/manuals/user/images/flow-instability-graph.png b/docs/manuals/user/images/flow-instability-graph.png
deleted file mode 100644
index 9602715b7..000000000
Binary files a/docs/manuals/user/images/flow-instability-graph.png and /dev/null differ
diff --git a/docs/manuals/user/images/graph-options-general.png b/docs/manuals/user/images/graph-options-general.png
deleted file mode 100644
index e13ad3a12..000000000
Binary files a/docs/manuals/user/images/graph-options-general.png and /dev/null differ
diff --git a/docs/manuals/user/images/grate-curved-vane.jpg b/docs/manuals/user/images/grate-curved-vane.jpg
deleted file mode 100644
index 784f989d2..000000000
Binary files a/docs/manuals/user/images/grate-curved-vane.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/grate-pbar30.png b/docs/manuals/user/images/grate-pbar30.png
deleted file mode 100644
index a5abbad47..000000000
Binary files a/docs/manuals/user/images/grate-pbar30.png and /dev/null differ
diff --git a/docs/manuals/user/images/grate-pbar50.png b/docs/manuals/user/images/grate-pbar50.png
deleted file mode 100644
index 2ee3faaf6..000000000
Binary files a/docs/manuals/user/images/grate-pbar50.png and /dev/null differ
diff --git a/docs/manuals/user/images/grate-pbar50x100.png b/docs/manuals/user/images/grate-pbar50x100.png
deleted file mode 100644
index f45549b7d..000000000
Binary files a/docs/manuals/user/images/grate-pbar50x100.png and /dev/null differ
diff --git a/docs/manuals/user/images/grate-reticuline.png b/docs/manuals/user/images/grate-reticuline.png
deleted file mode 100644
index cc389ffa3..000000000
Binary files a/docs/manuals/user/images/grate-reticuline.png and /dev/null differ
diff --git a/docs/manuals/user/images/grate-tilt30.jpg b/docs/manuals/user/images/grate-tilt30.jpg
deleted file mode 100644
index 56e320834..000000000
Binary files a/docs/manuals/user/images/grate-tilt30.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/grate-tilt45.jpg b/docs/manuals/user/images/grate-tilt45.jpg
deleted file mode 100644
index 64fbd2ead..000000000
Binary files a/docs/manuals/user/images/grate-tilt45.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/groundwater-flow-editor.png b/docs/manuals/user/images/groundwater-flow-editor.png
deleted file mode 100644
index 805c7281d..000000000
Binary files a/docs/manuals/user/images/groundwater-flow-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/group-editor.png b/docs/manuals/user/images/group-editor.png
deleted file mode 100644
index 4a854e073..000000000
Binary files a/docs/manuals/user/images/group-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/gw-equation-editor.png b/docs/manuals/user/images/gw-equation-editor.png
deleted file mode 100644
index 7d7419477..000000000
Binary files a/docs/manuals/user/images/gw-equation-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-conduit.png b/docs/manuals/user/images/icon-add-conduit.png
deleted file mode 100644
index 6fa2cfe4e..000000000
Binary files a/docs/manuals/user/images/icon-add-conduit.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-divider.png b/docs/manuals/user/images/icon-add-divider.png
deleted file mode 100644
index 21552aa7b..000000000
Binary files a/docs/manuals/user/images/icon-add-divider.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-junction.png b/docs/manuals/user/images/icon-add-junction.png
deleted file mode 100644
index 44b8c8823..000000000
Binary files a/docs/manuals/user/images/icon-add-junction.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-orifice.png b/docs/manuals/user/images/icon-add-orifice.png
deleted file mode 100644
index 354fce380..000000000
Binary files a/docs/manuals/user/images/icon-add-orifice.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-outfall.png b/docs/manuals/user/images/icon-add-outfall.png
deleted file mode 100644
index 3562eee95..000000000
Binary files a/docs/manuals/user/images/icon-add-outfall.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-outlet.png b/docs/manuals/user/images/icon-add-outlet.png
deleted file mode 100644
index 4136371e4..000000000
Binary files a/docs/manuals/user/images/icon-add-outlet.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-pump.png b/docs/manuals/user/images/icon-add-pump.png
deleted file mode 100644
index 001a2b637..000000000
Binary files a/docs/manuals/user/images/icon-add-pump.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-raingage.png b/docs/manuals/user/images/icon-add-raingage.png
deleted file mode 100644
index 602bfa03f..000000000
Binary files a/docs/manuals/user/images/icon-add-raingage.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-storage.png b/docs/manuals/user/images/icon-add-storage.png
deleted file mode 100644
index dee88e455..000000000
Binary files a/docs/manuals/user/images/icon-add-storage.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-subcatchment.png b/docs/manuals/user/images/icon-add-subcatchment.png
deleted file mode 100644
index 17a62fa77..000000000
Binary files a/docs/manuals/user/images/icon-add-subcatchment.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-text.png b/docs/manuals/user/images/icon-add-text.png
deleted file mode 100644
index fea284f5e..000000000
Binary files a/docs/manuals/user/images/icon-add-text.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-add-weir.png b/docs/manuals/user/images/icon-add-weir.png
deleted file mode 100644
index 9cd0e70bf..000000000
Binary files a/docs/manuals/user/images/icon-add-weir.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-cascade.png b/docs/manuals/user/images/icon-cascade.png
deleted file mode 100644
index deccd72c5..000000000
Binary files a/docs/manuals/user/images/icon-cascade.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-copy.png b/docs/manuals/user/images/icon-copy.png
deleted file mode 100644
index 5a1d20d7c..000000000
Binary files a/docs/manuals/user/images/icon-copy.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-customize.png b/docs/manuals/user/images/icon-customize.png
deleted file mode 100644
index b8d33f22b..000000000
Binary files a/docs/manuals/user/images/icon-customize.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-find.png b/docs/manuals/user/images/icon-find.png
deleted file mode 100644
index 202b50f98..000000000
Binary files a/docs/manuals/user/images/icon-find.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-full-extent.png b/docs/manuals/user/images/icon-full-extent.png
deleted file mode 100644
index eb2dd7ab0..000000000
Binary files a/docs/manuals/user/images/icon-full-extent.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-measure.png b/docs/manuals/user/images/icon-measure.png
deleted file mode 100644
index 63b6983d0..000000000
Binary files a/docs/manuals/user/images/icon-measure.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-new.png b/docs/manuals/user/images/icon-new.png
deleted file mode 100644
index 890438623..000000000
Binary files a/docs/manuals/user/images/icon-new.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-open.png b/docs/manuals/user/images/icon-open.png
deleted file mode 100644
index f5654558e..000000000
Binary files a/docs/manuals/user/images/icon-open.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-overview.png b/docs/manuals/user/images/icon-overview.png
deleted file mode 100644
index 1874d27d7..000000000
Binary files a/docs/manuals/user/images/icon-overview.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-pan.png b/docs/manuals/user/images/icon-pan.png
deleted file mode 100644
index e0f7f2914..000000000
Binary files a/docs/manuals/user/images/icon-pan.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-print.png b/docs/manuals/user/images/icon-print.png
deleted file mode 100644
index 0165d4133..000000000
Binary files a/docs/manuals/user/images/icon-print.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-profile.png b/docs/manuals/user/images/icon-profile.png
deleted file mode 100644
index 294d5eb56..000000000
Binary files a/docs/manuals/user/images/icon-profile.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-query.png b/docs/manuals/user/images/icon-query.png
deleted file mode 100644
index 508466c5c..000000000
Binary files a/docs/manuals/user/images/icon-query.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-report.png b/docs/manuals/user/images/icon-report.png
deleted file mode 100644
index cb84f6524..000000000
Binary files a/docs/manuals/user/images/icon-report.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-run-error.png b/docs/manuals/user/images/icon-run-error.png
deleted file mode 100644
index ad9d4d37c..000000000
Binary files a/docs/manuals/user/images/icon-run-error.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-run-not-available.png b/docs/manuals/user/images/icon-run-not-available.png
deleted file mode 100644
index b17cd468d..000000000
Binary files a/docs/manuals/user/images/icon-run-not-available.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-run-ok.png b/docs/manuals/user/images/icon-run-ok.png
deleted file mode 100644
index 586cf9ab9..000000000
Binary files a/docs/manuals/user/images/icon-run-ok.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-run-outdated.png b/docs/manuals/user/images/icon-run-outdated.png
deleted file mode 100644
index 5477f197e..000000000
Binary files a/docs/manuals/user/images/icon-run-outdated.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-run.png b/docs/manuals/user/images/icon-run.png
deleted file mode 100644
index 887f3ee9b..000000000
Binary files a/docs/manuals/user/images/icon-run.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-save.png b/docs/manuals/user/images/icon-save.png
deleted file mode 100644
index 4b56f3127..000000000
Binary files a/docs/manuals/user/images/icon-save.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-scatter.png b/docs/manuals/user/images/icon-scatter.png
deleted file mode 100644
index f6ac3882d..000000000
Binary files a/docs/manuals/user/images/icon-scatter.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-select-object.png b/docs/manuals/user/images/icon-select-object.png
deleted file mode 100644
index ef461988a..000000000
Binary files a/docs/manuals/user/images/icon-select-object.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-select-region.png b/docs/manuals/user/images/icon-select-region.png
deleted file mode 100644
index a4a73cc36..000000000
Binary files a/docs/manuals/user/images/icon-select-region.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-select-vertex.png b/docs/manuals/user/images/icon-select-vertex.png
deleted file mode 100644
index e45199ccc..000000000
Binary files a/docs/manuals/user/images/icon-select-vertex.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-statistics.png b/docs/manuals/user/images/icon-statistics.png
deleted file mode 100644
index 9c10c08b1..000000000
Binary files a/docs/manuals/user/images/icon-statistics.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-table.png b/docs/manuals/user/images/icon-table.png
deleted file mode 100644
index 64b9bf78b..000000000
Binary files a/docs/manuals/user/images/icon-table.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-time-series.png b/docs/manuals/user/images/icon-time-series.png
deleted file mode 100644
index 79b00f27d..000000000
Binary files a/docs/manuals/user/images/icon-time-series.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-zoom-in.png b/docs/manuals/user/images/icon-zoom-in.png
deleted file mode 100644
index f97d66638..000000000
Binary files a/docs/manuals/user/images/icon-zoom-in.png and /dev/null differ
diff --git a/docs/manuals/user/images/icon-zoom-out.png b/docs/manuals/user/images/icon-zoom-out.png
deleted file mode 100644
index f958b7c9c..000000000
Binary files a/docs/manuals/user/images/icon-zoom-out.png and /dev/null differ
diff --git a/docs/manuals/user/images/image-formula1.png b/docs/manuals/user/images/image-formula1.png
deleted file mode 100644
index 60c00ef9b..000000000
Binary files a/docs/manuals/user/images/image-formula1.png and /dev/null differ
diff --git a/docs/manuals/user/images/image002.png b/docs/manuals/user/images/image002.png
deleted file mode 100644
index f3589bf38..000000000
Binary files a/docs/manuals/user/images/image002.png and /dev/null differ
diff --git a/docs/manuals/user/images/image007.png b/docs/manuals/user/images/image007.png
deleted file mode 100644
index 58885d1e4..000000000
Binary files a/docs/manuals/user/images/image007.png and /dev/null differ
diff --git a/docs/manuals/user/images/image011.png b/docs/manuals/user/images/image011.png
deleted file mode 100644
index 98b32efbc..000000000
Binary files a/docs/manuals/user/images/image011.png and /dev/null differ
diff --git a/docs/manuals/user/images/image019.png b/docs/manuals/user/images/image019.png
deleted file mode 100644
index 93b435058..000000000
Binary files a/docs/manuals/user/images/image019.png and /dev/null differ
diff --git a/docs/manuals/user/images/image023.png b/docs/manuals/user/images/image023.png
deleted file mode 100644
index 1cae409ba..000000000
Binary files a/docs/manuals/user/images/image023.png and /dev/null differ
diff --git a/docs/manuals/user/images/image043.png b/docs/manuals/user/images/image043.png
deleted file mode 100644
index c96ef4d0e..000000000
Binary files a/docs/manuals/user/images/image043.png and /dev/null differ
diff --git a/docs/manuals/user/images/image044.png b/docs/manuals/user/images/image044.png
deleted file mode 100644
index cef9800b5..000000000
Binary files a/docs/manuals/user/images/image044.png and /dev/null differ
diff --git a/docs/manuals/user/images/image045.png b/docs/manuals/user/images/image045.png
deleted file mode 100644
index 2e75746e3..000000000
Binary files a/docs/manuals/user/images/image045.png and /dev/null differ
diff --git a/docs/manuals/user/images/image046.png b/docs/manuals/user/images/image046.png
deleted file mode 100644
index 32a3e4879..000000000
Binary files a/docs/manuals/user/images/image046.png and /dev/null differ
diff --git a/docs/manuals/user/images/image072.png b/docs/manuals/user/images/image072.png
deleted file mode 100644
index 6da3bae43..000000000
Binary files a/docs/manuals/user/images/image072.png and /dev/null differ
diff --git a/docs/manuals/user/images/image073.png b/docs/manuals/user/images/image073.png
deleted file mode 100644
index 31efc50e3..000000000
Binary files a/docs/manuals/user/images/image073.png and /dev/null differ
diff --git a/docs/manuals/user/images/image081.png b/docs/manuals/user/images/image081.png
deleted file mode 100644
index c62da8d65..000000000
Binary files a/docs/manuals/user/images/image081.png and /dev/null differ
diff --git a/docs/manuals/user/images/image082.png b/docs/manuals/user/images/image082.png
deleted file mode 100644
index d27cb7012..000000000
Binary files a/docs/manuals/user/images/image082.png and /dev/null differ
diff --git a/docs/manuals/user/images/image084.png b/docs/manuals/user/images/image084.png
deleted file mode 100644
index 6b102371f..000000000
Binary files a/docs/manuals/user/images/image084.png and /dev/null differ
diff --git a/docs/manuals/user/images/image085.png b/docs/manuals/user/images/image085.png
deleted file mode 100644
index 829f5576e..000000000
Binary files a/docs/manuals/user/images/image085.png and /dev/null differ
diff --git a/docs/manuals/user/images/image092.png b/docs/manuals/user/images/image092.png
deleted file mode 100644
index bbbcd0467..000000000
Binary files a/docs/manuals/user/images/image092.png and /dev/null differ
diff --git a/docs/manuals/user/images/image093.png b/docs/manuals/user/images/image093.png
deleted file mode 100644
index 7668bc526..000000000
Binary files a/docs/manuals/user/images/image093.png and /dev/null differ
diff --git a/docs/manuals/user/images/image094.png b/docs/manuals/user/images/image094.png
deleted file mode 100644
index bc1e2b616..000000000
Binary files a/docs/manuals/user/images/image094.png and /dev/null differ
diff --git a/docs/manuals/user/images/image095.png b/docs/manuals/user/images/image095.png
deleted file mode 100644
index 8df715ab9..000000000
Binary files a/docs/manuals/user/images/image095.png and /dev/null differ
diff --git a/docs/manuals/user/images/image096.png b/docs/manuals/user/images/image096.png
deleted file mode 100644
index f91f2bfdd..000000000
Binary files a/docs/manuals/user/images/image096.png and /dev/null differ
diff --git a/docs/manuals/user/images/image097.png b/docs/manuals/user/images/image097.png
deleted file mode 100644
index a0515a4b2..000000000
Binary files a/docs/manuals/user/images/image097.png and /dev/null differ
diff --git a/docs/manuals/user/images/image146.png b/docs/manuals/user/images/image146.png
deleted file mode 100644
index ee57dd401..000000000
Binary files a/docs/manuals/user/images/image146.png and /dev/null differ
diff --git a/docs/manuals/user/images/image147.png b/docs/manuals/user/images/image147.png
deleted file mode 100644
index b023172d2..000000000
Binary files a/docs/manuals/user/images/image147.png and /dev/null differ
diff --git a/docs/manuals/user/images/image148.png b/docs/manuals/user/images/image148.png
deleted file mode 100644
index ce7bcf4ba..000000000
Binary files a/docs/manuals/user/images/image148.png and /dev/null differ
diff --git a/docs/manuals/user/images/image149.png b/docs/manuals/user/images/image149.png
deleted file mode 100644
index 2439579ea..000000000
Binary files a/docs/manuals/user/images/image149.png and /dev/null differ
diff --git a/docs/manuals/user/images/image151.png b/docs/manuals/user/images/image151.png
deleted file mode 100644
index cb97a0521..000000000
Binary files a/docs/manuals/user/images/image151.png and /dev/null differ
diff --git a/docs/manuals/user/images/image152.png b/docs/manuals/user/images/image152.png
deleted file mode 100644
index 6011a0aac..000000000
Binary files a/docs/manuals/user/images/image152.png and /dev/null differ
diff --git a/docs/manuals/user/images/image153.png b/docs/manuals/user/images/image153.png
deleted file mode 100644
index de618cebf..000000000
Binary files a/docs/manuals/user/images/image153.png and /dev/null differ
diff --git a/docs/manuals/user/images/image169.png b/docs/manuals/user/images/image169.png
deleted file mode 100644
index 93b2df473..000000000
Binary files a/docs/manuals/user/images/image169.png and /dev/null differ
diff --git a/docs/manuals/user/images/image171.png b/docs/manuals/user/images/image171.png
deleted file mode 100644
index 7ea10878a..000000000
Binary files a/docs/manuals/user/images/image171.png and /dev/null differ
diff --git a/docs/manuals/user/images/image180.png b/docs/manuals/user/images/image180.png
deleted file mode 100644
index a864160dd..000000000
Binary files a/docs/manuals/user/images/image180.png and /dev/null differ
diff --git a/docs/manuals/user/images/image192.png b/docs/manuals/user/images/image192.png
deleted file mode 100644
index 7b44508ec..000000000
Binary files a/docs/manuals/user/images/image192.png and /dev/null differ
diff --git a/docs/manuals/user/images/image195.png b/docs/manuals/user/images/image195.png
deleted file mode 100644
index 317b4f087..000000000
Binary files a/docs/manuals/user/images/image195.png and /dev/null differ
diff --git a/docs/manuals/user/images/image196.png b/docs/manuals/user/images/image196.png
deleted file mode 100644
index eb03440ab..000000000
Binary files a/docs/manuals/user/images/image196.png and /dev/null differ
diff --git a/docs/manuals/user/images/image197.png b/docs/manuals/user/images/image197.png
deleted file mode 100644
index 1d2f5b763..000000000
Binary files a/docs/manuals/user/images/image197.png and /dev/null differ
diff --git a/docs/manuals/user/images/image198.png b/docs/manuals/user/images/image198.png
deleted file mode 100644
index deeeca214..000000000
Binary files a/docs/manuals/user/images/image198.png and /dev/null differ
diff --git a/docs/manuals/user/images/image199.png b/docs/manuals/user/images/image199.png
deleted file mode 100644
index 189d64cf1..000000000
Binary files a/docs/manuals/user/images/image199.png and /dev/null differ
diff --git a/docs/manuals/user/images/image213.png b/docs/manuals/user/images/image213.png
deleted file mode 100644
index da89f8dd1..000000000
Binary files a/docs/manuals/user/images/image213.png and /dev/null differ
diff --git a/docs/manuals/user/images/image217.png b/docs/manuals/user/images/image217.png
deleted file mode 100644
index 22bf7f809..000000000
Binary files a/docs/manuals/user/images/image217.png and /dev/null differ
diff --git a/docs/manuals/user/images/image221.png b/docs/manuals/user/images/image221.png
deleted file mode 100644
index 6036a93b2..000000000
Binary files a/docs/manuals/user/images/image221.png and /dev/null differ
diff --git a/docs/manuals/user/images/image222.gif b/docs/manuals/user/images/image222.gif
deleted file mode 100644
index aef6f756c..000000000
Binary files a/docs/manuals/user/images/image222.gif and /dev/null differ
diff --git a/docs/manuals/user/images/image229.png b/docs/manuals/user/images/image229.png
deleted file mode 100644
index 2be96367f..000000000
Binary files a/docs/manuals/user/images/image229.png and /dev/null differ
diff --git a/docs/manuals/user/images/image233.png b/docs/manuals/user/images/image233.png
deleted file mode 100644
index 49704fc2a..000000000
Binary files a/docs/manuals/user/images/image233.png and /dev/null differ
diff --git a/docs/manuals/user/images/image234.png b/docs/manuals/user/images/image234.png
deleted file mode 100644
index a700bcc81..000000000
Binary files a/docs/manuals/user/images/image234.png and /dev/null differ
diff --git a/docs/manuals/user/images/image239.png b/docs/manuals/user/images/image239.png
deleted file mode 100644
index 93ee29bf1..000000000
Binary files a/docs/manuals/user/images/image239.png and /dev/null differ
diff --git a/docs/manuals/user/images/image255.png b/docs/manuals/user/images/image255.png
deleted file mode 100644
index 2e3eea321..000000000
Binary files a/docs/manuals/user/images/image255.png and /dev/null differ
diff --git a/docs/manuals/user/images/image262.png b/docs/manuals/user/images/image262.png
deleted file mode 100644
index 779972dcc..000000000
Binary files a/docs/manuals/user/images/image262.png and /dev/null differ
diff --git a/docs/manuals/user/images/image269.png b/docs/manuals/user/images/image269.png
deleted file mode 100644
index 7867a57fc..000000000
Binary files a/docs/manuals/user/images/image269.png and /dev/null differ
diff --git a/docs/manuals/user/images/image270.png b/docs/manuals/user/images/image270.png
deleted file mode 100644
index 848b910ad..000000000
Binary files a/docs/manuals/user/images/image270.png and /dev/null differ
diff --git a/docs/manuals/user/images/image271.png b/docs/manuals/user/images/image271.png
deleted file mode 100644
index 5099dad86..000000000
Binary files a/docs/manuals/user/images/image271.png and /dev/null differ
diff --git a/docs/manuals/user/images/image272.png b/docs/manuals/user/images/image272.png
deleted file mode 100644
index c6df38114..000000000
Binary files a/docs/manuals/user/images/image272.png and /dev/null differ
diff --git a/docs/manuals/user/images/image273.png b/docs/manuals/user/images/image273.png
deleted file mode 100644
index f0e16d78d..000000000
Binary files a/docs/manuals/user/images/image273.png and /dev/null differ
diff --git a/docs/manuals/user/images/image274.png b/docs/manuals/user/images/image274.png
deleted file mode 100644
index 9263b2f61..000000000
Binary files a/docs/manuals/user/images/image274.png and /dev/null differ
diff --git a/docs/manuals/user/images/image275.png b/docs/manuals/user/images/image275.png
deleted file mode 100644
index ea92ff746..000000000
Binary files a/docs/manuals/user/images/image275.png and /dev/null differ
diff --git a/docs/manuals/user/images/image276.png b/docs/manuals/user/images/image276.png
deleted file mode 100644
index b6aa7dd11..000000000
Binary files a/docs/manuals/user/images/image276.png and /dev/null differ
diff --git a/docs/manuals/user/images/image277.png b/docs/manuals/user/images/image277.png
deleted file mode 100644
index 93b0f84cf..000000000
Binary files a/docs/manuals/user/images/image277.png and /dev/null differ
diff --git a/docs/manuals/user/images/image278.png b/docs/manuals/user/images/image278.png
deleted file mode 100644
index 3a2120bdc..000000000
Binary files a/docs/manuals/user/images/image278.png and /dev/null differ
diff --git a/docs/manuals/user/images/image279.png b/docs/manuals/user/images/image279.png
deleted file mode 100644
index 0b97b68d8..000000000
Binary files a/docs/manuals/user/images/image279.png and /dev/null differ
diff --git a/docs/manuals/user/images/image287.png b/docs/manuals/user/images/image287.png
deleted file mode 100644
index 650f01288..000000000
Binary files a/docs/manuals/user/images/image287.png and /dev/null differ
diff --git a/docs/manuals/user/images/image288.png b/docs/manuals/user/images/image288.png
deleted file mode 100644
index 840a6ae7d..000000000
Binary files a/docs/manuals/user/images/image288.png and /dev/null differ
diff --git a/docs/manuals/user/images/image289.png b/docs/manuals/user/images/image289.png
deleted file mode 100644
index cfe618674..000000000
Binary files a/docs/manuals/user/images/image289.png and /dev/null differ
diff --git a/docs/manuals/user/images/image290.png b/docs/manuals/user/images/image290.png
deleted file mode 100644
index ee4a80a6e..000000000
Binary files a/docs/manuals/user/images/image290.png and /dev/null differ
diff --git a/docs/manuals/user/images/image291.jpg b/docs/manuals/user/images/image291.jpg
deleted file mode 100644
index 01c84bec6..000000000
Binary files a/docs/manuals/user/images/image291.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image292.jpg b/docs/manuals/user/images/image292.jpg
deleted file mode 100644
index dd6707209..000000000
Binary files a/docs/manuals/user/images/image292.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image293.png b/docs/manuals/user/images/image293.png
deleted file mode 100644
index 5119ad3d7..000000000
Binary files a/docs/manuals/user/images/image293.png and /dev/null differ
diff --git a/docs/manuals/user/images/image294.jpg b/docs/manuals/user/images/image294.jpg
deleted file mode 100644
index 49a3a5997..000000000
Binary files a/docs/manuals/user/images/image294.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image295.png b/docs/manuals/user/images/image295.png
deleted file mode 100644
index dd8b758c7..000000000
Binary files a/docs/manuals/user/images/image295.png and /dev/null differ
diff --git a/docs/manuals/user/images/image296.png b/docs/manuals/user/images/image296.png
deleted file mode 100644
index a64dd1a84..000000000
Binary files a/docs/manuals/user/images/image296.png and /dev/null differ
diff --git a/docs/manuals/user/images/image297.png b/docs/manuals/user/images/image297.png
deleted file mode 100644
index b01409e7e..000000000
Binary files a/docs/manuals/user/images/image297.png and /dev/null differ
diff --git a/docs/manuals/user/images/image298.png b/docs/manuals/user/images/image298.png
deleted file mode 100644
index a4ee6dbc2..000000000
Binary files a/docs/manuals/user/images/image298.png and /dev/null differ
diff --git a/docs/manuals/user/images/image299.jpg b/docs/manuals/user/images/image299.jpg
deleted file mode 100644
index da1bdda5a..000000000
Binary files a/docs/manuals/user/images/image299.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image300.jpg b/docs/manuals/user/images/image300.jpg
deleted file mode 100644
index 2963d42ca..000000000
Binary files a/docs/manuals/user/images/image300.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image301.jpg b/docs/manuals/user/images/image301.jpg
deleted file mode 100644
index e7e26c83c..000000000
Binary files a/docs/manuals/user/images/image301.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/image303.png b/docs/manuals/user/images/image303.png
deleted file mode 100644
index b34e908b5..000000000
Binary files a/docs/manuals/user/images/image303.png and /dev/null differ
diff --git a/docs/manuals/user/images/imagexx.png b/docs/manuals/user/images/imagexx.png
deleted file mode 100644
index e8459ee37..000000000
Binary files a/docs/manuals/user/images/imagexx.png and /dev/null differ
diff --git a/docs/manuals/user/images/infiltration-editor.png b/docs/manuals/user/images/infiltration-editor.png
deleted file mode 100644
index fc09f33f7..000000000
Binary files a/docs/manuals/user/images/infiltration-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/inflows-direct.png b/docs/manuals/user/images/inflows-direct.png
deleted file mode 100644
index 6781b180c..000000000
Binary files a/docs/manuals/user/images/inflows-direct.png and /dev/null differ
diff --git a/docs/manuals/user/images/inflows-dry.png b/docs/manuals/user/images/inflows-dry.png
deleted file mode 100644
index 0f0830a98..000000000
Binary files a/docs/manuals/user/images/inflows-dry.png and /dev/null differ
diff --git a/docs/manuals/user/images/initial-buildup-editor.png b/docs/manuals/user/images/initial-buildup-editor.png
deleted file mode 100644
index 9d8aa12e8..000000000
Binary files a/docs/manuals/user/images/initial-buildup-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/initial-buildup-editor2.png b/docs/manuals/user/images/initial-buildup-editor2.png
deleted file mode 100644
index 9428bb59e..000000000
Binary files a/docs/manuals/user/images/initial-buildup-editor2.png and /dev/null differ
diff --git a/docs/manuals/user/images/inlet-structure-editor.png b/docs/manuals/user/images/inlet-structure-editor.png
deleted file mode 100644
index f10f11346..000000000
Binary files a/docs/manuals/user/images/inlet-structure-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/inlet-usage-editor.png b/docs/manuals/user/images/inlet-usage-editor.png
deleted file mode 100644
index 84c74636a..000000000
Binary files a/docs/manuals/user/images/inlet-usage-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/interface-file-selector.png b/docs/manuals/user/images/interface-file-selector.png
deleted file mode 100644
index c17e3eb33..000000000
Binary files a/docs/manuals/user/images/interface-file-selector.png and /dev/null differ
diff --git a/docs/manuals/user/images/land-use-assignment.png b/docs/manuals/user/images/land-use-assignment.png
deleted file mode 100644
index 7480cc744..000000000
Binary files a/docs/manuals/user/images/land-use-assignment.png and /dev/null differ
diff --git a/docs/manuals/user/images/land-use-assignment2.png b/docs/manuals/user/images/land-use-assignment2.png
deleted file mode 100644
index 37e5a003f..000000000
Binary files a/docs/manuals/user/images/land-use-assignment2.png and /dev/null differ
diff --git a/docs/manuals/user/images/land-use-editor-buildup.png b/docs/manuals/user/images/land-use-editor-buildup.png
deleted file mode 100644
index 1da3ce749..000000000
Binary files a/docs/manuals/user/images/land-use-editor-buildup.png and /dev/null differ
diff --git a/docs/manuals/user/images/land-use-editor-general.png b/docs/manuals/user/images/land-use-editor-general.png
deleted file mode 100644
index e8150dbdc..000000000
Binary files a/docs/manuals/user/images/land-use-editor-general.png and /dev/null differ
diff --git a/docs/manuals/user/images/land-use-editor-washoff.png b/docs/manuals/user/images/land-use-editor-washoff.png
deleted file mode 100644
index 735e0222e..000000000
Binary files a/docs/manuals/user/images/land-use-editor-washoff.png and /dev/null differ
diff --git a/docs/manuals/user/images/legend-editor.png b/docs/manuals/user/images/legend-editor.png
deleted file mode 100644
index 37f9e3e1b..000000000
Binary files a/docs/manuals/user/images/legend-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/lid-control-editor.png b/docs/manuals/user/images/lid-control-editor.png
deleted file mode 100644
index c59d9e287..000000000
Binary files a/docs/manuals/user/images/lid-control-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/lid-group-editor.jpg b/docs/manuals/user/images/lid-group-editor.jpg
deleted file mode 100644
index b622fa271..000000000
Binary files a/docs/manuals/user/images/lid-group-editor.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/lid-usage-editor.png b/docs/manuals/user/images/lid-usage-editor.png
deleted file mode 100644
index 51d5d50a7..000000000
Binary files a/docs/manuals/user/images/lid-usage-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/link-offset.png b/docs/manuals/user/images/link-offset.png
deleted file mode 100644
index af926106f..000000000
Binary files a/docs/manuals/user/images/link-offset.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-browser.jpg b/docs/manuals/user/images/map-browser.jpg
deleted file mode 100644
index fccdf95cf..000000000
Binary files a/docs/manuals/user/images/map-browser.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/map-dimensions.png b/docs/manuals/user/images/map-dimensions.png
deleted file mode 100644
index ec0cdf0f8..000000000
Binary files a/docs/manuals/user/images/map-dimensions.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-export.png b/docs/manuals/user/images/map-export.png
deleted file mode 100644
index 728fb1c8d..000000000
Binary files a/docs/manuals/user/images/map-export.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-finder.png b/docs/manuals/user/images/map-finder.png
deleted file mode 100644
index 6164dab8f..000000000
Binary files a/docs/manuals/user/images/map-finder.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-legend.jpg b/docs/manuals/user/images/map-legend.jpg
deleted file mode 100644
index 309936cc7..000000000
Binary files a/docs/manuals/user/images/map-legend.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/map-options.png b/docs/manuals/user/images/map-options.png
deleted file mode 100644
index 5ca192e34..000000000
Binary files a/docs/manuals/user/images/map-options.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-query.png b/docs/manuals/user/images/map-query.png
deleted file mode 100644
index 86375115c..000000000
Binary files a/docs/manuals/user/images/map-query.png and /dev/null differ
diff --git a/docs/manuals/user/images/map-theme.png b/docs/manuals/user/images/map-theme.png
deleted file mode 100644
index f199f1803..000000000
Binary files a/docs/manuals/user/images/map-theme.png and /dev/null differ
diff --git a/docs/manuals/user/images/overview-map.png b/docs/manuals/user/images/overview-map.png
deleted file mode 100644
index f74b42bd5..000000000
Binary files a/docs/manuals/user/images/overview-map.png and /dev/null differ
diff --git a/docs/manuals/user/images/page-setup-headers.png b/docs/manuals/user/images/page-setup-headers.png
deleted file mode 100644
index 9c766bb2b..000000000
Binary files a/docs/manuals/user/images/page-setup-headers.png and /dev/null differ
diff --git a/docs/manuals/user/images/page-setup-margins.png b/docs/manuals/user/images/page-setup-margins.png
deleted file mode 100644
index 3c88b92a4..000000000
Binary files a/docs/manuals/user/images/page-setup-margins.png and /dev/null differ
diff --git a/docs/manuals/user/images/pollutant-editor.png b/docs/manuals/user/images/pollutant-editor.png
deleted file mode 100644
index bfd766a39..000000000
Binary files a/docs/manuals/user/images/pollutant-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/preferences.png b/docs/manuals/user/images/preferences.png
deleted file mode 100644
index 75a633730..000000000
Binary files a/docs/manuals/user/images/preferences.png and /dev/null differ
diff --git a/docs/manuals/user/images/preferences2.png b/docs/manuals/user/images/preferences2.png
deleted file mode 100644
index e885b187c..000000000
Binary files a/docs/manuals/user/images/preferences2.png and /dev/null differ
diff --git a/docs/manuals/user/images/profile-plot-options.png b/docs/manuals/user/images/profile-plot-options.png
deleted file mode 100644
index c0cf48118..000000000
Binary files a/docs/manuals/user/images/profile-plot-options.png and /dev/null differ
diff --git a/docs/manuals/user/images/profile-plot-selection.png b/docs/manuals/user/images/profile-plot-selection.png
deleted file mode 100644
index bfbd6cc03..000000000
Binary files a/docs/manuals/user/images/profile-plot-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/profile-plot.png b/docs/manuals/user/images/profile-plot.png
deleted file mode 100644
index a75530626..000000000
Binary files a/docs/manuals/user/images/profile-plot.png and /dev/null differ
diff --git a/docs/manuals/user/images/project-browser.jpg b/docs/manuals/user/images/project-browser.jpg
deleted file mode 100644
index fc98cdcdd..000000000
Binary files a/docs/manuals/user/images/project-browser.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/project-data.png b/docs/manuals/user/images/project-data.png
deleted file mode 100644
index d426b9e11..000000000
Binary files a/docs/manuals/user/images/project-data.png and /dev/null differ
diff --git a/docs/manuals/user/images/project-defaults.png b/docs/manuals/user/images/project-defaults.png
deleted file mode 100644
index 2d96e688e..000000000
Binary files a/docs/manuals/user/images/project-defaults.png and /dev/null differ
diff --git a/docs/manuals/user/images/property-editor-conduit.png b/docs/manuals/user/images/property-editor-conduit.png
deleted file mode 100644
index 833f3ec8d..000000000
Binary files a/docs/manuals/user/images/property-editor-conduit.png and /dev/null differ
diff --git a/docs/manuals/user/images/pump-curve-editor.png b/docs/manuals/user/images/pump-curve-editor.png
deleted file mode 100644
index 864b4cead..000000000
Binary files a/docs/manuals/user/images/pump-curve-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/reporting-options.png b/docs/manuals/user/images/reporting-options.png
deleted file mode 100644
index 7f56221a1..000000000
Binary files a/docs/manuals/user/images/reporting-options.png and /dev/null differ
diff --git a/docs/manuals/user/images/run-status-success.png b/docs/manuals/user/images/run-status-success.png
deleted file mode 100644
index 2f5d15dc6..000000000
Binary files a/docs/manuals/user/images/run-status-success.png and /dev/null differ
diff --git a/docs/manuals/user/images/run-status.png b/docs/manuals/user/images/run-status.png
deleted file mode 100644
index 3b37ac0b1..000000000
Binary files a/docs/manuals/user/images/run-status.png and /dev/null differ
diff --git a/docs/manuals/user/images/scatter-plot-selection.png b/docs/manuals/user/images/scatter-plot-selection.png
deleted file mode 100644
index ea762804e..000000000
Binary files a/docs/manuals/user/images/scatter-plot-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/scatter-plot.png b/docs/manuals/user/images/scatter-plot.png
deleted file mode 100644
index 8035e74d2..000000000
Binary files a/docs/manuals/user/images/scatter-plot.png and /dev/null differ
diff --git a/docs/manuals/user/images/sim-options-files.png b/docs/manuals/user/images/sim-options-files.png
deleted file mode 100644
index 2758245dd..000000000
Binary files a/docs/manuals/user/images/sim-options-files.png and /dev/null differ
diff --git a/docs/manuals/user/images/sim-options-general.png b/docs/manuals/user/images/sim-options-general.png
deleted file mode 100644
index f9063e990..000000000
Binary files a/docs/manuals/user/images/sim-options-general.png and /dev/null differ
diff --git a/docs/manuals/user/images/snow-pack-editor-params.png b/docs/manuals/user/images/snow-pack-editor-params.png
deleted file mode 100644
index 67106bfc6..000000000
Binary files a/docs/manuals/user/images/snow-pack-editor-params.png and /dev/null differ
diff --git a/docs/manuals/user/images/snow-pack-editor-removal.png b/docs/manuals/user/images/snow-pack-editor-removal.png
deleted file mode 100644
index c6254a637..000000000
Binary files a/docs/manuals/user/images/snow-pack-editor-removal.png and /dev/null differ
diff --git a/docs/manuals/user/images/stats-report-selection.png b/docs/manuals/user/images/stats-report-selection.png
deleted file mode 100644
index d08369e8f..000000000
Binary files a/docs/manuals/user/images/stats-report-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/stats-report.png b/docs/manuals/user/images/stats-report.png
deleted file mode 100644
index 951c42b64..000000000
Binary files a/docs/manuals/user/images/stats-report.png and /dev/null differ
diff --git a/docs/manuals/user/images/status-bar.jpg b/docs/manuals/user/images/status-bar.jpg
deleted file mode 100644
index 944e6c651..000000000
Binary files a/docs/manuals/user/images/status-bar.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/storage-shape-editor.png b/docs/manuals/user/images/storage-shape-editor.png
deleted file mode 100644
index 42458344a..000000000
Binary files a/docs/manuals/user/images/storage-shape-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/street-section-editor.png b/docs/manuals/user/images/street-section-editor.png
deleted file mode 100644
index ea57a2809..000000000
Binary files a/docs/manuals/user/images/street-section-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/study-area-map.png b/docs/manuals/user/images/study-area-map.png
deleted file mode 100644
index 982faeb82..000000000
Binary files a/docs/manuals/user/images/study-area-map.png and /dev/null differ
diff --git a/docs/manuals/user/images/summary-results.png b/docs/manuals/user/images/summary-results.png
deleted file mode 100644
index bbf91a7ee..000000000
Binary files a/docs/manuals/user/images/summary-results.png and /dev/null differ
diff --git a/docs/manuals/user/images/swmm-main-window.jpg b/docs/manuals/user/images/swmm-main-window.jpg
deleted file mode 100644
index f4aeaf0ba..000000000
Binary files a/docs/manuals/user/images/swmm-main-window.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/table-by-object-selection.png b/docs/manuals/user/images/table-by-object-selection.png
deleted file mode 100644
index 4a30b28ba..000000000
Binary files a/docs/manuals/user/images/table-by-object-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/table-by-object.png b/docs/manuals/user/images/table-by-object.png
deleted file mode 100644
index b91a749cd..000000000
Binary files a/docs/manuals/user/images/table-by-object.png and /dev/null differ
diff --git a/docs/manuals/user/images/table-by-variable-selection.png b/docs/manuals/user/images/table-by-variable-selection.png
deleted file mode 100644
index fc802310f..000000000
Binary files a/docs/manuals/user/images/table-by-variable-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/table-by-variable.png b/docs/manuals/user/images/table-by-variable.png
deleted file mode 100644
index 0be8b66cf..000000000
Binary files a/docs/manuals/user/images/table-by-variable.png and /dev/null differ
diff --git a/docs/manuals/user/images/themes.jpg b/docs/manuals/user/images/themes.jpg
deleted file mode 100644
index 7519a8322..000000000
Binary files a/docs/manuals/user/images/themes.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/themes2.jpg b/docs/manuals/user/images/themes2.jpg
deleted file mode 100644
index 2087539ac..000000000
Binary files a/docs/manuals/user/images/themes2.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/themes3.jpg b/docs/manuals/user/images/themes3.jpg
deleted file mode 100644
index b32c76c46..000000000
Binary files a/docs/manuals/user/images/themes3.jpg and /dev/null differ
diff --git a/docs/manuals/user/images/time-pattern-editor.png b/docs/manuals/user/images/time-pattern-editor.png
deleted file mode 100644
index bc0ff6730..000000000
Binary files a/docs/manuals/user/images/time-pattern-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/time-series-editor.png b/docs/manuals/user/images/time-series-editor.png
deleted file mode 100644
index 8290e859d..000000000
Binary files a/docs/manuals/user/images/time-series-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/time-series-plot.png b/docs/manuals/user/images/time-series-plot.png
deleted file mode 100644
index 3f7583bf2..000000000
Binary files a/docs/manuals/user/images/time-series-plot.png and /dev/null differ
diff --git a/docs/manuals/user/images/time-series-selection.png b/docs/manuals/user/images/time-series-selection.png
deleted file mode 100644
index 9b7154acf..000000000
Binary files a/docs/manuals/user/images/time-series-selection.png and /dev/null differ
diff --git a/docs/manuals/user/images/title-notes-editor.png b/docs/manuals/user/images/title-notes-editor.png
deleted file mode 100644
index 7f7708cc5..000000000
Binary files a/docs/manuals/user/images/title-notes-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/tool-options.png b/docs/manuals/user/images/tool-options.png
deleted file mode 100644
index 4fb958124..000000000
Binary files a/docs/manuals/user/images/tool-options.png and /dev/null differ
diff --git a/docs/manuals/user/images/tool-properties.png b/docs/manuals/user/images/tool-properties.png
deleted file mode 100644
index f29fcff62..000000000
Binary files a/docs/manuals/user/images/tool-properties.png and /dev/null differ
diff --git a/docs/manuals/user/images/tools-menu.png b/docs/manuals/user/images/tools-menu.png
deleted file mode 100644
index 0329aa7e1..000000000
Binary files a/docs/manuals/user/images/tools-menu.png and /dev/null differ
diff --git a/docs/manuals/user/images/transect-editor.png b/docs/manuals/user/images/transect-editor.png
deleted file mode 100644
index 517895de2..000000000
Binary files a/docs/manuals/user/images/transect-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/treatment-editor.png b/docs/manuals/user/images/treatment-editor.png
deleted file mode 100644
index ba9b9d6a3..000000000
Binary files a/docs/manuals/user/images/treatment-editor.png and /dev/null differ
diff --git a/docs/manuals/user/images/uh-editor.png b/docs/manuals/user/images/uh-editor.png
deleted file mode 100644
index edfb382d8..000000000
Binary files a/docs/manuals/user/images/uh-editor.png and /dev/null differ
diff --git a/docs/manuals/user/manual/AppendixA.md b/docs/manuals/user/manual/AppendixA.md
deleted file mode 100644
index 2ed6a51e1..000000000
--- a/docs/manuals/user/manual/AppendixA.md
+++ /dev/null
@@ -1,496 +0,0 @@
-@page user_manual_appendix_a APPENDIX A - USEFUL TABLES
-
-@tableofcontents
-
-## A.1 Units of Measurement {#user_manual_appendix_tbl_a_1}
-
-| **PARAMETER**                | **US CUSTOMARY**                                   | **SI METRIC**                                |
-|------------------------------|---------------------------------------------------|---------------------------------------------|
-| Area (Subcatchment)          | acres                                             | hectares                                    |
-| Area (Storage Unit)          | square feet                                       | square meters                               |
-| Area (Ponding)               | square feet                                       | square meters                               |
-| Capillary Suction            | inches                                            | millimeters                                 |
-| Concentration                | mg/L (milligrams/liter), ug/L (micrograms/liter), #/L (counts/liter) | mg/L, ug/L, #/L                             |
-| Decay Constant (Infiltration)| 1/hours                                           | 1/hours                                     |
-| Decay Constant (Pollutants)  | 1/days                                            | 1/days                                      |
-| Depression Storage           | inches                                            | millimeters                                 |
-| Depth                        | feet                                              | meters                                      |
-| Diameter                     | feet                                              | meters                                      |
-| Discharge Coefficient:       |                                                   |                                             |
-| - Orifice                    | dimensionless                                     | dimensionless                               |
-| - Weir                       | CFS/footⁿ                                         | CMS/meterⁿ                                  |
-| Elevation                    | feet                                              | meters                                      |
-| Evaporation                  | inches/day                                        | millimeters/day                             |
-| Flow                         | CFS (cubic feet/second), GPM (gallons/minute), MGD (million gallons/day) | CMS (cubic meters/second), LPS (liters/second), MLD (million liters/day) |
-| Head                         | feet                                              | meters                                      |
-| Hydraulic Conductivity       | inches/hour                                       | millimeters/hour                            |
-| Infiltration Rate            | inches/hour                                       | millimeters/hour                            |
-| Length                       | feet                                              | meters                                      |
-| Manning's Coefficient (n)    | seconds/meter^(1/3)                               | seconds/meter^(1/3)                         |
-| Pollutant Buildup            | mass/length, mass/acre                            | mass/length, mass/hectare                   |
-| Rainfall Intensity           | inches/hour                                       | millimeters/hour                            |
-| Rainfall Volume              | inches                                            | millimeters                                 |
-| Slope (Subcatchments)        | percent                                           | percent                                     |
-| Slope (Cross Section)        | rise/run                                          | rise/run                                    |
-| Street Cleaning Interval     | days                                              | days                                        |
-| Volume                       | cubic feet                                        | cubic meters                                |
-| Width                        | feet                                              | meters                                      |
-
-| **Soil Texture Class** | **K (in/hr)** | **\f$\psi\f$ (in)** | **\f$\phi\f$ (fraction)** | **FC (fraction)** | **WP (fraction)** |
-|-------------------------|---------------|-------------|-------------------|-------------------|-------------------|
-| Sand                   | 4.74          | 1.93        | 0.437             | 0.062             | 0.024             |
-| Loamy Sand             | 1.18          | 2.40        | 0.437             | 0.105             | 0.047             |
-| Sandy Loam             | 0.43          | 4.33        | 0.453             | 0.190             | 0.085             |
-| Loam                   | 0.13          | 3.50        | 0.463             | 0.232             | 0.116             |
-| Silt Loam              | 0.26          | 6.69        | 0.501             | 0.284             | 0.135             |
-| Sandy Clay Loam        | 0.06          | 8.66        | 0.398             | 0.244             | 0.136             |
-| Clay Loam              | 0.04          | 8.27        | 0.464             | 0.310             | 0.187             |
-| Silty Clay Loam        | 0.04          | 10.63       | 0.471             | 0.342             | 0.210             |
-| Sandy Clay             | 0.02          | 9.45        | 0.430             | 0.321             | 0.221             |
-| Silty Clay             | 0.02          | 11.42       | 0.479             | 0.371             | 0.251             |
-| Clay                   | 0.01          | 12.60       | 0.475             | 0.378             | 0.265             |
-
-- K = saturated hydraulic conductivity, in/hr
-- \f$\psi\f$ = suction head, in.
-- \f$\phi\f$ = porosity, fraction
-- FC = field capacity, fraction
-- WP = wilting point, fraction
-
-Source: Rawls, W.J. et al., (1983). J. Hyd. Engr., 109:1316. 

-
-**Note:** The following relation between \f$\psi\f$ and K can be derived from this table:
-
-\f$\psi = 3.23 \, K^{-0.328} \quad (R^{2} = 0.9)\f$
-
-
-
-## A.3 NRCS Hydrologic Soil Group Definitions {#user_manual_appendix_tbl_a_3}
-
-| **Group** | **Meaning**                                                                                                           | **Saturated Hydraulic Conductivity (in/hr)** |
-|-----------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------|
-| **A**     | Low runoff potential. Water is transmitted freely through the soil. Group A soils typically have less than 10% clay and more than 90% sand or gravel and have gravel or sand textures. | > 1.42                                      |
-| **B**     | Moderately low runoff potential. Water transmission through the soil is unimpeded. Group B soils typically have between 10% and 20% clay and 50% to 90% sand and have loamy sand or sandy loam textures. | 0.57 – 1.42                                 |
-| **C**     | Moderately high runoff potential. Water transmission through the soil is somewhat restricted. Group C soils typically have between 20% and 40% clay and less than 50% sand and have loam, silt loam, sandy clay loam, clay loam, and silty clay loam textures. | 0.06 – 0.57                                 |
-| **D**     | High runoff potential. Water movement through the soil is restricted or very restricted. Group D soils typically have greater than 40% clay, less than 50% sand, and have clayey textures. | < 0.06                                      |
-
-Source: *Hydrology National Engineering Handbook, Chapter 7, Natural Resources Conservation Service, U.S. Department of Agriculture, January 2009.*
-
-
-## A.4 SCS Curve Numbers {#user_manual_appendix_tbl_a_4}
-
-| **Land Use Description**                              | **Hydrologic Soil Group** | **A** | **B** | **C** | **D** |
-|-------------------------------------------------------|---------------------------|-------|-------|-------|-------|
-| Cultivated land                                       |                           |       |       |       |       |
-| - Without conservation treatment                      |                           | 72    | 81    | 88    | 91    |
-| - With conservation treatment                         |                           | 62    | 71    | 78    | 81    |
-| Pasture or range land                                 |                           |       |       |       |       |
-| - Poor condition                                      |                           | 68    | 79    | 86    | 89    |
-| - Good condition                                      |                           | 39    | 61    | 74    | 80    |
-| Meadow                                                | - Good condition          | 30    | 58    | 71    | 78    |
-| Wood or forest land                                   |                           |       |       |       |       |
-| - Thin stand, poor cover, no mulch                    |                           | 45    | 66    | 77    | 83    |
-| - Good cover²                                         |                           | 25    | 55    | 70    | 77    |
-| Open spaces, lawns, parks, golf courses, cemeteries   |                           |       |       |       |       |
-| - Good condition: grass cover on 75% or more of area  |                           | 39    | 61    | 74    | 80    |
-| - Fair condition: grass cover on 50-75% of area       |                           | 49    | 69    | 79    | 84    |
-| Commercial and business areas (85% impervious)        |                           | 89    | 92    | 94    | 95    |
-| Industrial districts (72% impervious)                |                           | 81    | 88    | 91    | 93    |
-| Residential³                                          |                           |       |       |       |       |
-| - Average lot size (% Impervious⁴)                   |                           |       |       |       |       |
-| - 1/8 ac or less (65)                                 |                           | 77    | 85    | 90    | 92    |
-| - 1/4 ac (38)                                         |                           | 61    | 75    | 83    | 87    |
-| - 1/3 ac (30)                                         |                           | 57    | 72    | 81    | 86    |
-| - 1/2 ac (25)                                         |                           | 54    | 70    | 80    | 85    |
-| - 1 ac (20)                                           |                           | 51    | 68    | 79    | 84    |
-| Paved parking lots, roofs, driveways, etc.⁵           |                           | 98    | 98    | 98    | 98    |
-| Streets and roads                                     |                           |       |       |       |       |
-| - Paved with curbs and storm sewers⁵                  |                           | 98    | 98    | 98    | 98    |
-| - Gravel                                              |                           | 76    | 85    | 89    | 91    |
-| - Dirt                                                |                           | 72    | 82    | 87    | 89    |
-
-¹ Antecedent moisture condition II.  
-² Good cover is protected from grazing and litter and brush cover soil.  
-³ Curve numbers are computed assuming that the runoff from the house and driveway is directed toward the street with a minimum of roof water directed to lawns where additional infiltration could occur.  
-⁴ The remaining pervious areas (lawn) are considered to be in good pasture condition for these curve numbers.  
-⁵ In some warmer climates of the country, a curve number of 95 may be used.  
-
-Source: SCS Urban Hydrology for Small Watersheds, 2nd Ed., (TR-55), June 1986.
-
-
-## A.5 Depression Storage {#user_manual_appendix_tbl_a_5}
-
-| **Surface Type**       | **Depression Storage (inches)** |
-|-------------------------|---------------------------------|
-| Impervious Surfaces     | 0.05 - 0.10                   |
-| Lawns                  | 0.10 - 0.20                   |
-| Pasture                | 0.20                          |
-| Forest Litter          | 0.30                          |
-
-Source:    ASCE, (1992). Design & Construction of Urban Stormwater Management Systems, New York, NY.
-
-## A.6 Manning’s Coefficient (n) – Overland Flow {#user_manual_appendix_tbl_a_6}
-
-| **Surface**                     | **n**   |
-|---------------------------------|---------|
-| Smooth asphalt                  | 0.011   |
-| Smooth concrete                 | 0.012   |
-| Ordinary concrete lining        | 0.013   |
-| Good wood                       | 0.014   |
-| Brick with cement mortar        | 0.014   |
-| Vitrified clay                  | 0.015   |
-| Cast iron                       | 0.015   |
-| Corrugated metal pipes          | 0.024   |
-| Cement rubble surface           | 0.024   |
-| Fallow soils (no residue)       | 0.05    |
-| Cultivated soils                |         |
-| - Residue cover < 20%           | 0.06    |
-| - Residue cover > 20%           | 0.17    |
-| Range (natural)                 | 0.13    |
-| Grass                           |         |
-| - Short, prairie                | 0.15    |
-| - Dense                         | 0.24    |
-| - Bermuda grass                 | 0.41    |
-| Woods                           |         |
-| - Light underbrush              | 0.40    |
-| - Dense underbrush              | 0.80    |
-
-Source:    McCuen, R. et al. (1996), Hydrology, FHWA-SA-96-067, Federal Highway Administration, Washington, DC
-
-## A.7 Manning’s Coefficient (n) – Closed Conduits {#user_manual_appendix_tbl_a_7}
-
-| **Conduit Material**            | **n**               |
-|----------------------------------|---------------------|
-| Asbestos-cement pipe             | 0.011 - 0.015       |
-| Brick                            | 0.013 - 0.017       |
-| Cast iron pipe                   |                     |
-| - Cement-lined & seal coated     | 0.011 - 0.015       |
-| Concrete (monolithic)            |                     |
-| - Smooth forms                   | 0.012 - 0.014       |
-| - Rough forms                    | 0.015 - 0.017       |
-| Concrete pipe                    | 0.011 - 0.015       |
-| Corrugated-metal pipe            |                     |
-| - Plain                          | 0.022 - 0.026       |
-| - Paved invert                   | 0.018 - 0.022       |
-| - Spun asphalt lined             | 0.011 - 0.015       |
-| Plastic pipe (smooth)            | 0.011 - 0.015       |
-| Vitrified clay                   |                     |
-| - Pipes                          | 0.011 - 0.015       |
-| - Liner plates                   | 0.013 - 0.017       |
-
-Source:    ASCE (1982). Gravity Sanitary Sewer Design and Construction, ASCE Manual of Practice No. 60, New York, NY.
-
- 
-## A.8 Manning’s Coefficient (n) – Open Channels {#user_manual_appendix_tbl_a_8}
-
-| **Channel Type**                | **n**           |
-|----------------------------------|-----------------|
-| **Lined Channels**              |                 |
-| - Asphalt                        | 0.013 - 0.017   |
-| - Brick                          | 0.012 - 0.018   |
-| - Concrete                       | 0.011 - 0.020   |
-| - Rubble or riprap               | 0.020 - 0.035   |
-| - Vegetal                        | 0.030 - 0.40    |
-| **Excavated or dredged**         |                 |
-| - Earth, straight and uniform    | 0.020 - 0.030   |
-| - Earth, winding, fairly uniform | 0.025 - 0.040   |
-| - Rock                           | 0.030 - 0.045   |
-| - Unmaintained                   | 0.050 - 0.140   |
-| **Natural channels (minor streams, top width at flood stage < 100 ft)** | |
-| - Fairly regular section         | 0.030 - 0.070   |
-| - Irregular section with pools   | 0.040 - 0.100   |
-
-Source:    ASCE (1982). Gravity Sanitary Sewer Design and Construction, ASCE Manual of Practice No. 60, New York, NY.
-
-
-## A.9 Water Quality Characteristics of Urban Runoff {#user_manual_appendix_tbl_a_9}
-
-| **Constituent** | **Event Mean Concentration** |
-|------------------|-----------------------------|
-| TSS (mg/L)      | 180 - 548                   |
-| BOD (mg/L)      | 12 - 19                     |
-| COD (mg/L)      | 82 - 178                    |
-| Total P (mg/L)  | 0.42 - 0.88                 |
-| Soluble P (mg/L)| 0.15 - 0.28                 |
-| TKN (mg/L)      | 1.90 - 4.18                 |
-| NO2/NO3-N (mg/L)| 0.86 - 2.2                  |
-| Total Cu (ug/L) | 43 - 118                    |
-| Total Pb (ug/L) | 182 - 443                   |
-| Total Zn (ug/L) | 202 - 633                   |
-
-Source: U.S. Environmental Protection Agency. (1983). Results of the Nationwide Urban Runoff Program (NURP), Vol. 1, NTIS PB 84-185552), Water Planning Division, Washington, DC.
-
-
-## A.10 Culvert Code Numbers {#user_manual_appendix_tbl_a_10}
-
-
-| **Culvert Type**                                   | **Code** | **Description**                                   |
-|----------------------------------------------------|----------|---------------------------------------------------|
-| Circular Concrete                                  | 1        | Square edge with headwall                         |
-|                                                    | 2        | Groove end with headwall                          |
-|                                                    | 3        | Groove end projecting                             |
-| Circular Corrugated Metal Pipe                    | 4        | Headwall                                          |
-|                                                    | 5        | Mitered to slope                                  |
-|                                                    | 6        | Projecting                                        |
-| Circular Pipe, Beveled Ring Entrance              | 7        | 45 deg. bevels                                    |
-|                                                    | 8        | 33.7 deg. bevels                                  |
-| Rectangular Box; Flared Wingwalls                 | 9        | 30-75 deg. wingwall flares                        |
-|                                                    | 10       | 90 or 15 deg. wingwall flares                     |
-|                                                    | 11       | 0 deg. wingwall flares (straight sides)           |
-| Rectangular Box; Flared Wingwalls and Top Edge Bevel | 12     | 45 deg flare; 0.43D top edge bevel               |
-|                                                    | 13       | 18-33.7 deg. flare; 0.083D top edge bevel         |
-| Rectangular Box, 90-deg Headwall, Chamfered / Beveled Inlet Edges | 14 | Chamfered 3/4-in.                                |
-|                                                    | 15       | Beveled 1/2-in/ft at 45 deg (1:1)                 |
-|                                                    | 16       | Beveled 1-in/ft at 33.7 deg (1:1.5)               |
-| Rectangular Box, Skewed Headwall, Chamfered / Beveled Inlet Edges | 17 | 3/4" chamfered edge, 45 deg skewed headwall      |
-|                                                    | 18       | 3/4" chamfered edge, 30 deg skewed headwall       |
-|                                                    | 19       | 3/4" chamfered edge, 15 deg skewed headwall       |
-|                                                    | 20       | 45 deg beveled edge, 10-45 deg skewed headwall    |
-| Rectangular Box, Non-offset Flared Wingwalls, 3/4" Chamfer at Top of Inlet | 21 | 45 deg (1:1) wingwall flare                      |
-|                                                    | 22       | 8.4 deg (3:1) wingwall flare                     |
-|                                                    | 23       | 18.4 deg (3:1) wingwall flare, 30 deg inlet skew |
-| Rectangular Box, Offset Flared Wingwalls, Beveled Edge at Inlet Top | 24 | 45 deg (1:1) flare, 0.042D top edge bevel       |
-|                                                    | 25       | 33.7 deg (1.5:1) flare, 0.083D top edge bevel     |
-|                                                    | 26       | 18.4 deg (3:1) flare, 0.083D top edge bevel       |
-| Corrugated Metal Box                               | 27       | 90 deg headwall                                   |
-|                                                    | 28       | Thick wall projecting                             |
-|                                                    | 29       | Thin wall projecting                              |
-| Horizontal Ellipse Concrete                        | 30       | Square edge with headwall                         |
-|                                                    | 31       | Grooved end with headwall                         |
-|                                                    | 32       | Grooved end projecting                            |
-| Vertical Ellipse Concrete                          | 33       | Square edge with headwall                         |
-|                                                    | 34       | Grooved end with headwall                         |
-|                                                    | 35       | Grooved end projecting                            |
-| Pipe Arch, 18" Corner Radius, Corrugated Metal     | 36       | 90 deg headwall                                   |
-|                                                    | 37       | Mitered to slope                                  |
-|                                                    | 38       | Projecting                                        |
-| Pipe Arch, 18" Corner Radius, Corrugated Metal     | 39       | Projecting                                        |
-|                                                    | 40       | No bevels                                         |
-|                                                    | 41       | 33.7 deg bevels                                   |
-| Pipe Arch, 31" Corner Radius, Corrugated Metal     | 42       | Projecting                                        |
-|                                                    | 43       | No bevels                                         |
-|                                                    | 44       | 33.7 deg. bevels                                  |
-| Arch, Corrugated Metal                             | 45       | 90 deg headwall                                   |
-|                                                    | 46       | Mitered to slope                                  |
-|                                                    | 47       | Thin wall projecting                              |
-| Circular Culvert                                   | 48       | Smooth tapered inlet throat                       |
-|                                                    | 49       | Rough tapered inlet throat                        |
-| Elliptical Inlet Face                              | 50       | Tapered inlet, beveled edges                      |
-|                                                    | 51       | Tapered inlet, square edges                       |
-|                                                    | 52       | Tapered inlet, thin edge projecting               |
-| Rectangular                                        | 53       | Tapered inlet throat                              |
-| Rectangular Concrete                               | 54       | Side tapered, less favorable edges               |
-|                                                    | 55       | Side tapered, more favorable edges               |
-|                                                    | 56       | Slope tapered, less favorable edges              |
-|                                                    | 57       | Slope tapered, more favorable edges              |
-
- 
-## A.11 Culvert Entrance Loss Coefficients {#user_manual_appendix_tbl_a_11}
-
-| **Type of Structure and Design of Entrance**                     | **Coefficient** |
-|-------------------------------------------------------------------|-----------------|
-| **Pipe, Concrete**                                                |                 |
-| Projecting from fill, socket end (groove-end)                     | 0.2             |
-| Projecting from fill, square cut end                              | 0.5             |
-| Headwall or headwall and wingwalls:                               |                 |
-| - Socket end of pipe (groove-end)                                 | 0.2             |
-| - Square-edge                                                     | 0.5             |
-| - Rounded (radius = D/12)                                         | 0.2             |
-| - Mitered to conform to fill slope                                | 0.7             |
-| - *End-Section conforming to fill slope*                          | 0.5             |
-| - Beveled edges, 33.7° or 45° bevels                              | 0.2             |
-| - Side- or slope-tapered inlet                                    | 0.2             |
-| **Pipe or Pipe-Arch, Corrugated Metal**                           |                 |
-| Projecting from fill (no headwall)                                | 0.9             |
-| Headwall or headwall and wingwalls, square-edge                   | 0.5             |
-| Mitered to conform to fill slope, paved or unpaved slope          | 0.7             |
-| *End-Section conforming to fill slope*                            | 0.5             |
-| Beveled edges, 33.7° or 45° bevels                                | 0.2             |
-| Side- or slope-tapered inlet                                      | 0.2             |
-| **Box, Reinforced Concrete**                                      |                 |
-| Headwall parallel to embankment (no wingwalls):                   |                 |
-| - Square-edged on 3 edges                                         | 0.5             |
-| - Rounded on 3 edges to radius of D/12 or B/12, or beveled edges  | 0.2             |
-| Wingwalls at 30° to 75° to barrel:                                |                 |
-| - Square-edged at crown                                           | 0.4             |
-| - Crown edge rounded to radius of D/12, or beveled top edge       | 0.2             |
-| Wingwalls at 10° to 25° to barrel:                                |                 |
-| - Square-edged at crown                                           | 0.5             |
-| Wingwalls parallel (extension of sides):                          |                 |
-| - Square-edged at crown                                           | 0.7             |
-| Side- or slope-tapered inlet                                      | 0.2             |
-
-**Note:**  
-*"End Sections conforming to fill slope,"* made of either metal or concrete, are the sections commonly available from manufacturers. From limited hydraulic tests, they are equivalent in operation to a headwall in both inlet and outlet control. Some end sections, incorporating a closed taper in their design, have superior hydraulic performance. These latter sections can be designed using the information given for the beveled inlet.
-
-Source: Federal Highway Administration (2005). Hydraulic Design of Highway Culverts, Publication No. FHWA-NHI-01-020. 
-
-## A.12 Standard Elliptical Pipe Sizes {#user_manual_appendix_tbl_a_12}
-
-
-| **Code** | **Minor Axis (in)** | **Major Axis (in)** | **Minor Axis (mm)** | **Major Axis (mm)** |
-|----------|----------------------|----------------------|----------------------|----------------------|
-| 1        | 14                   | 23                   | 356                  | 584                  |
-| 2        | 19                   | 30                   | 483                  | 762                  |
-| 3        | 22                   | 34                   | 559                  | 864                  |
-| 4        | 24                   | 38                   | 610                  | 965                  |
-| 5        | 27                   | 42                   | 686                  | 1067                 |
-| 6        | 29                   | 45                   | 737                  | 1143                 |
-| 7        | 32                   | 49                   | 813                  | 1245                 |
-| 8        | 34                   | 53                   | 864                  | 1346                 |
-| 9        | 38                   | 60                   | 965                  | 1524                 |
-| 10       | 43                   | 68                   | 1092                 | 1727                 |
-| 11       | 48                   | 76                   | 1219                 | 1930                 |
-| 12       | 53                   | 83                   | 1346                 | 2108                 |
-| 13       | 58                   | 91                   | 1473                 | 2311                 |
-| 14       | 63                   | 98                   | 1600                 | 2489                 |
-| 15       | 68                   | 106                  | 1727                 | 2692                 |
-| 16       | 72                   | 113                  | 1829                 | 2870                 |
-| 17       | 77                   | 121                  | 1956                 | 3073                 |
-| 18       | 82                   | 128                  | 2083                 | 3251                 |
-| 19       | 87                   | 136                  | 2210                 | 3454                 |
-| 20       | 92                   | 143                  | 2337                 | 3632                 |
-| 21       | 97                   | 151                  | 2464                 | 3835                 |
-| 22       | 106                  | 166                  | 2692                 | 4216                 |
-| 23       | 116                  | 180                  | 2946                 | 4572                 |
-
-**Note:** The Minor Axis is the maximum width for a vertical ellipse and the full depth for a horizontal ellipse, while the Major Axis is the maximum width for a horizontal ellipse and the full depth for a vertical ellipse.
-
-Source: Concrete Pipe Design Manual, American Concrete Pipe Association, 2011 (www.concrete-pipe.org).
-
- 
-## A.13 Standard Arch Pipe Sizes {#user_manual_appendix_tbl_a_13}
-
-### Concrete Arch Pipes {#user_manual_appendix_tbl_a_13_concrete}
-
-| **Code** | **Rise (in)** | **Span (in)** | **Rise (mm)** | **Span (mm)** |
-|----------|---------------|---------------|---------------|---------------|
-| 1        | 11            | 18            | 279           | 457           |
-| 2        | 13.5          | 22            | 343           | 559           |
-| 3        | 15.5          | 26            | 394           | 660           |
-| 4        | 18            | 28.5          | 457           | 724           |
-| 5        | 22.5          | 36.25         | 572           | 921           |
-| 6        | 26.625        | 43.75         | 676           | 1111          |
-| 7        | 31.3125       | 51.125        | 795           | 1299          |
-| 8        | 36            | 58.5          | 914           | 1486          |
-| 9        | 40            | 65            | 1016          | 1651          |
-| 10       | 45            | 73            | 1143          | 1854          |
-| 11       | 54            | 88            | 1372          | 2235          |
-| 12       | 62            | 102           | 1575          | 2591          |
-| 13       | 72            | 115           | 1829          | 2921          |
-| 14       | 77.5          | 122           | 1969          | 3099          |
-| 15       | 87.125        | 138           | 2213          | 3505          |
-| 16       | 96.875        | 154           | 2461          | 3912          |
-| 17       | 106.5         | 168.75        | 2705          | 4286          |
-
-
-### Corrugated Steel, 2-2/3 x 1/2" Corrugation {#user_manual_appendix_tbl_a_13_cs_small}
-
-| **Code** | **Rise (in)** | **Span (in)** | **Rise (mm)** | **Span (mm)** |
-|----------|---------------|---------------|---------------|---------------|
-| 18       | 13            | 17            | 330           | 432           |
-| 19       | 15            | 21            | 381           | 533           |
-| 20       | 18            | 24            | 457           | 610           |
-| 21       | 20            | 28            | 508           | 711           |
-| 22       | 24            | 35            | 610           | 889           |
-| 23       | 29            | 42            | 737           | 1067          |
-| 24       | 33            | 49            | 838           | 1245          |
-| 25       | 38            | 57            | 965           | 1448          |
-| 26       | 43            | 64            | 1092          | 1626          |
-| 27       | 47            | 71            | 1194          | 1803          |
-| 28       | 52            | 77            | 1321          | 1956          |
-| 29       | 57            | 83            | 1448          | 2108          |
-
-
-### Corrugated Steel, 3 x 1" Corrugation {#user_manual_appendix_tbl_a_13_cs_large}
-
-| **Code** | **Rise (in)** | **Span (in)** | **Rise (mm)** | **Span (mm)** |
-|----------|---------------|---------------|---------------|---------------|
-| 30       | 31            | 40            | 787           | 1016          |
-| 31       | 36            | 46            | 914           | 1168          |
-| 32       | 41            | 53            | 1041          | 1346          |
-| 33       | 46            | 60            | 1168          | 1524          |
-| 34       | 51            | 66            | 1295          | 1676          |
-| 35       | 55            | 73            | 1397          | 1854          |
-| 36       | 59            | 81            | 1499          | 2057          |
-| 37       | 63            | 87            | 1600          | 2210          |
-| 38       | 67            | 95            | 1702          | 2413          |
-| 39       | 71            | 103           | 1803          | 2616          |
-| 40       | 75            | 112           | 1905          | 2845          |
-| 41       | 79            | 117           | 2007          | 2972          |
-| 42       | 83            | 128           | 2108          | 3251          |
-| 43       | 87            | 137           | 2210          | 3480          |
-| 44       | 91            | 142           | 2311          | 3607          |
- 
-### Structural Plate, 18" Corner Radius {#user_manual_appendix_tbl_a_13_sp18}
-
-| **Code** | **Rise (in)** | **Span (in)** | **Rise (mm)** | **Span (mm)** |
-|----------|---------------|---------------|---------------|---------------|
-| 45       | 55            | 73            | 1397          | 1854          |
-| 46       | 57            | 76            | 1448          | 1930          |
-| 47       | 59            | 81            | 1499          | 2057          |
-| 48       | 61            | 84            | 1549          | 2134          |
-| 49       | 63            | 87            | 1600          | 2210          |
-| 50       | 65            | 92            | 1651          | 2337          |
-| 51       | 67            | 95            | 1702          | 2413          |
-| 52       | 69            | 98            | 1753          | 2489          |
-| 53       | 71            | 103           | 1803          | 2616          |
-| 54       | 73            | 106           | 1854          | 2692          |
-| 55       | 75            | 112           | 1905          | 2845          |
-| 56       | 77            | 114           | 1956          | 2896          |
-| 57       | 79            | 117           | 2007          | 2972          |
-| 58       | 81            | 123           | 2057          | 3124          |
-| 59       | 83            | 128           | 2108          | 3251          |
-| 60       | 85            | 131           | 2159          | 3327          |
-| 61       | 87            | 137           | 2210          | 3480          |
-| 62       | 89            | 139           | 2261          | 3531          |
-| 63       | 91            | 142           | 2311          | 3607          |
-| 64       | 93            | 148           | 2362          | 3759          |
-| 65       | 95            | 150           | 2413          | 3810          |
-| 66       | 97            | 152           | 2464          | 3861          |
-| 67       | 100           | 154           | 2540          | 3912          |
-| 68       | 101           | 161           | 2565          | 4089          |
-| 69       | 103           | 167           | 2616          | 4242          |
-| 70       | 105           | 169           | 2667          | 4293          |
-| 71       | 107           | 171           | 2718          | 4343          |
-| 72       | 109           | 178           | 2769          | 4521          |
-| 73       | 111           | 184           | 2819          | 4674          |
-| 74       | 113           | 186           | 2870          | 4724          |
-| 75       | 115           | 188           | 2921          | 4775          |
-| 76       | 118           | 190           | 2997          | 4826          |
-| 77       | 119           | 197           | 3023          | 5004          |
-| 78       | 121           | 199           | 3073          | 5055          |
-
- 
-### Structural Plate, 31" Corner Radius {#user_manual_appendix_tbl_a_13_sp31}
-
-| **Code** | **Rise (in)** | **Span (in)** | **Rise (mm)** | **Span (mm)** |
-|----------|---------------|---------------|---------------|---------------|
-| 79       | 112           | 159           | 2845          | 4039          |
-| 80       | 114           | 162           | 2896          | 4115          |
-| 81       | 116           | 168           | 2946          | 4267          |
-| 82       | 118           | 170           | 2997          | 4318          |
-| 83       | 120           | 173           | 3048          | 4394          |
-| 84       | 122           | 179           | 3099          | 4547          |
-| 85       | 124           | 184           | 3150          | 4674          |
-| 86       | 126           | 187           | 3200          | 4750          |
-| 87       | 128           | 190           | 3251          | 4826          |
-| 88       | 130           | 195           | 3302          | 4953          |
-| 89       | 132           | 198           | 3353          | 5029          |
-| 90       | 134           | 204           | 3404          | 5182          |
-| 91       | 136           | 206           | 3454          | 5232          |
-| 92       | 138           | 209           | 3505          | 5309          |
-| 93       | 140           | 215           | 3556          | 5461          |
-| 94       | 142           | 217           | 3607          | 5512          |
-| 95       | 144           | 223           | 3658          | 5664          |
-| 96       | 146           | 225           | 3708          | 5715          |
-| 97       | 148           | 231           | 3759          | 5867          |
-| 98       | 150           | 234           | 3810          | 5944          |
-| 99       | 152           | 236           | 3861          | 5994          |
-| 100      | 154           | 239           | 3912          | 6071          |
-| 101      | 156           | 245           | 3962          | 6223          |
-| 102      | 158           | 247           | 4013          | 6274          |
-
-Source: Modern Sewer Design (Fourth Edition), American Iron and Steel Institute, Washington, DC, 1999.
-
-
-
diff --git a/docs/manuals/user/manual/AppendixB.md b/docs/manuals/user/manual/AppendixB.md
deleted file mode 100644
index 1db8065a7..000000000
--- a/docs/manuals/user/manual/AppendixB.md
+++ /dev/null
@@ -1,294 +0,0 @@
-@page user_manual_appendix_b APPENDIX B - VISUAL OBJECT PROPERTIES
-
-@tableofcontents
-
----
-
-## B.1 Rain Gage Properties {#user_manual_appendix_b_1}
-
-| **Property**         | **Description**                                                                                                                                                                                                 |
-|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**             | User-assigned rain gage name.                                                                                                                                                                                  |
-| **X-Coordinate**     | Horizontal location of the rain gage on the Study Area Map. If left blank, the rain gage will not appear on the map.                                                                                            |
-| **Y-Coordinate**     | Vertical location of the rain gage on the Study Area Map. If left blank, the rain gage will not appear on the map.                                                                                              |
-| **Description**      | Click the ellipsis button (or press Enter) to edit an optional description of the rain gage.                                                                                                                    |
-| **Tag**              | Optional label used to categorize or classify the rain gage.                                                                                                                                                    |
-| **Rain Format**      | Format in which the rain data are supplied: 
 - **INTENSITY**: Rainfall value is an average rate in inches/hour (or mm/hour) over the recording interval. 
 - **VOLUME**: Rainfall value is the volume of rain that fell in the recording interval (in inches or millimeters). 
 - **CUMULATIVE**: Rainfall value represents the cumulative rainfall since the start of the last series of non-zero values (in inches or millimeters). |
-| **Time Interval**    | Recording time interval between gage readings in either decimal hours or hours:minutes format.                                                                                                                  |
-| **Snow Catch Factor**| Factor that corrects gage readings for snowfall.                                                                                                                                                                |
-| **Data Source**      | Source of rainfall data; either **TIMESERIES** for user-supplied time series data or **FILE** for an external data file.                                                                                         |
-| **TIME SERIES**      |                                                                                                                                                                                                                 |
-| - **Series Name**    | Name of time series with rainfall data if Data Source selection was **TIMESERIES**; leave blank otherwise (double-click to edit the series).                                                                    |
-| **DATA FILE**        |                                                                                                                                                                                                                 |
-| - **File Name**      | Name of external file containing rainfall data (see Section 11.3).                                                                                                                                              |
-| - **Station ID**     | Recording gage station identifier.                                                                                                                                                                              |
-| - **Rain Units**     | Depth units (**IN** or **MM**) for rainfall values in user-prepared files (other standard file formats have fixed units depending on the format).                                                                |
- 
-## B.2 Subcatchment Properties {#user_manual_appendix_b_2}
-
-| **Property**         | **Description**                                                                                                                                                                                                 |
-|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**             | User-assigned subcatchment name.                                                                                                                                                                                |
-| **X-Coordinate**     | Horizontal location of the subcatchment's centroid on the Study Area Map. If left blank, the subcatchment will not appear on the map.                                                                            |
-| **Y-Coordinate**     | Vertical location of the subcatchment's centroid on the Study Area Map. If left blank, the subcatchment will not appear on the map.                                                                              |
-| **Description**      | Click the ellipsis button (or press Enter) to edit an optional description of the subcatchment.                                                                                                                  |
-| **Tag**              | Optional label used to categorize or classify the subcatchment.                                                                                                                                                  |
-| **Rain Gage**        | Name of the rain gage associated with the subcatchment.                                                                                                                                                          |
-| **Outlet**           | Name of the node or subcatchment which receives the subcatchment's runoff.                                                                                                                                       |
-| **Area**             | Area of the subcatchment, including any LID controls (acres or hectares).                                                                                                                                        |
-| **Width**            | Characteristic width of the overland flow path for sheet flow runoff (feet or meters).                                                                                                                           |
-| **% Slope**          | Average percent slope of the subcatchment.                                                                                                                                                                       |
-| **% Imperv**         | Percent of land area (excluding the area used for LID controls) which is impervious.                                                                                                                             |
-| **N-Imperv**         | Manning's coefficient (n) for overland flow over the impervious portion of the subcatchment (see Section A.6 for typical values).                                                                                |
-| **N-Perv**           | Manning's coefficient (n) for overland flow over the pervious portion of the subcatchment (see Section A.6 for typical values).                                                                                  |
-| **Dstore-Imperv**    | Depth of depression storage on the impervious portion of the subcatchment (inches or millimeters) (see Section A.5 for typical values).                                                                          |
-| **Dstore-Perv**      | Depth of depression storage on the pervious portion of the subcatchment (inches or millimeters) (see Section A.5 for typical values).                                                                            |
-| **% Zero-Imperv**    | Percent of the impervious area with no depression storage.                                                                                                                                                        |
-| **Subarea Routing**  | Choice of internal routing of runoff between pervious and impervious areas: 
 - **IMPERV**: runoff from pervious area flows to impervious area. 
 - **PERV**: runoff from impervious area flows to pervious area. 
 - **OUTLET**: runoff from both areas flows directly to outlet. |
-| **Percent Routed**   | Percent of runoff routed between subareas.                                                                                                                                                                       |
-| **Infiltration Data**| Click the ellipsis button (or press Enter) to edit infiltration parameters for the subcatchment.                                                                                                                 |
-| **Groundwater**      | Click the ellipsis button (or press Enter) to edit groundwater flow parameters for the subcatchment.                                                                                                             |
-| **Snow Pack**        | Name of snow pack parameter set (if any) assigned to the subcatchment.                                                                                                                                           |
-| **LID Controls**     | Click the ellipsis button (or press Enter) to edit the use of low impact development controls in the subcatchment.                                                                                               |
-| **Land Uses**        | Click the ellipsis button (or press Enter) to assign land uses to the subcatchment. Only needed if pollutant buildup/washoff is modeled.                                                                          |
-| **Initial Buildup**  | Click the ellipsis button (or press Enter) to specify initial quantities of pollutant buildup over the subcatchment.                                                                                              |
-| **Curb Length**      | Total length of curbs in the subcatchment (any length units). Used only when pollutant buildup is normalized to curb length.                                                                                       |
-| **N-Perv Pattern**   | Name of optional monthly pattern that adjusts pervious Manning’s n.                                                                                                                                              |
-| **Dstore Pattern**   | Name of optional monthly pattern that adjusts depression storage.                                                                                                                                                |
-| **Infil. Pattern**   | Name of optional monthly pattern that adjusts infiltration rate.                                                                                                                                                 |
-
-**Note:** An initial estimate of the characteristic width is given by the subcatchment area divided by the average maximum overland flow length. The maximum overland flow length is the length of the flow path from the furthest drainage point of the subcatchment before the flow becomes channelized. Maximum lengths from several different possible flow paths should be averaged. These paths should reflect slow flow, such as over pervious surfaces, more than rapid flow over pavement, for example. Adjustments should be made to the width parameter to produce good fits to measured runoff hydrographs.
-
-## B.3 Junction Properties {#user_manual_appendix_b_3}
-
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned junction name.                                                                                                                                                                                   |
-| **X-Coordinate**   | Horizontal location of the junction on the Study Area Map. If left blank, the junction will not appear on the map.                                                                                              |
-| **Y-Coordinate**   | Vertical location of the junction on the Study Area Map. If left blank, the junction will not appear on the map.                                                                                                |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the junction.                                                                                                                     |
-| **Tag**            | Optional label used to categorize or classify the junction.                                                                                                                                                     |
-| **Inflows**        | Click the ellipsis button (or press Enter) to assign external direct, dry weather, or RDII inflows to the junction.                                                                                              |
-| **Treatment**      | Click the ellipsis button (or press Enter) to edit a set of treatment functions for pollutants entering the node.                                                                                                |
-| **Invert El.**     | Invert elevation of the junction (feet or meters).                                                                                                                                                              |
-| **Max. Depth**     | Maximum depth of the junction (i.e., from ground surface to invert) (feet or meters). If zero, the distance from the invert to the top of the highest connecting link will be used.                               |
-| **Initial Depth**  | Depth of water at the junction at the start of the simulation (feet or meters).                                                                                                                                 |
-| **Surcharge Depth**| Additional depth of water beyond the maximum depth that the junction can sustain before overflowing (feet or meters). This parameter can be used to simulate bolted manhole covers or force main connections.    |
-| **Ponded Area**    | Area occupied by ponded water atop the junction after flooding occurs (sq. feet or sq. meters). If the Allow Ponding simulation option is turned on, a non-zero value of this parameter will allow ponded water to be stored and subsequently returned to the conveyance system when capacity exists. |
-
-
-## B.4 Outfall Properties {#user_manual_appendix_b_4}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned outfall name.                                                                                                                                                                                     |
-| **X-Coordinate**   | Horizontal location of the outfall on the Study Area Map. If left blank, the outfall will not appear on the map.                                                                                                |
-| **Y-Coordinate**   | Vertical location of the outfall on the Study Area Map. If left blank, the outfall will not appear on the map.                                                                                                  |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the outfall.                                                                                                                       |
-| **Tag**            | Optional label used to categorize or classify the outfall.                                                                                                                                                       |
-| **Inflows**        | Click the ellipsis button (or press Enter) to assign external direct, dry weather, or RDII inflows to the outfall.                                                                                               |
-| **Treatment**      | Click the ellipsis button (or press Enter) to edit a set of treatment functions for pollutants entering the node.                                                                                                |
-| **Invert El.**     | Invert elevation of the outfall (feet or meters).                                                                                                                                                               |
-| **Tide Gate**      | **YES**: Tide gate present to prevent backflow. 
 **NO**: No tide gate present.                                                                                                                               |
-| **Route To**       | Optional name of a subcatchment that receives the outfall's discharge.                                                                                                                                           |
-| **Type**           | Type of outfall boundary condition: 
 - **FREE**: Outfall stage determined by the minimum of critical flow depth and normal flow depth in the connecting conduit. 
 - **NORMAL**: Outfall stage based on normal flow depth in the connecting conduit. 
 - **FIXED**: Outfall stage set to a fixed value. 
 - **TIDAL**: Outfall stage given by a table of tide elevation versus time of day. 
 - **TIMESERIES**: Outfall stage supplied from a time series of elevations. |
-| **Fixed Stage**    | Water elevation for a **FIXED** type of outfall (feet or meters).                                                                                                                                                |
-| **Tidal Curve Name** | Name of the Tidal Curve relating water elevation to hour of the day for a **TIDAL** outfall (double-click to edit the curve).                                                                                   |
-| **Time Series Name** | Name of the time series containing the time history of outfall elevations for a **TIMESERIES** outfall (double-click to edit the series).                                                                       |
-
-
-## B.5 Flow Divider Properties {#user_manual_appendix_b_5}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
-| **Name**           | User-assigned divider name.                                                                                                                                                                                     |
-| **X-Coordinate**   | Horizontal location of the divider on the Study Area Map. If left blank, the divider will not appear on the map.                                                                                                |
-| **Y-Coordinate**   | Vertical location of the divider on the Study Area Map. If left blank, the divider will not appear on the map.                                                                                                  |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the divider.                                                                                                                       |
-| **Tag**            | Optional label used to categorize or classify the divider.                                                                                                                                                       |
-| **Inflows**        | Click the ellipsis button (or press Enter) to assign external direct, dry weather, or RDII inflows to the divider.                                                                                               |
-| **Treatment**      | Click the ellipsis button (or press Enter) to edit a set of treatment functions for pollutants entering the node.                                                                                                |
-| **Invert El.**     | Invert elevation of the divider (feet or meters).                                                                                                                                                               |
-| **Max. Depth**     | Maximum depth of the divider (feet or meters). See description for Junctions.                                                                                                                                   |
-| **Initial Depth**  | Depth of water at the divider at the start of the simulation (feet or meters).                                                                                                                                  |
-| **Surcharge Depth**| Additional depth of water beyond the maximum depth that the divider can sustain before overflowing (feet or meters).                                                                                           |
-| **Ponded Area**    | Area occupied by ponded water atop the junction after flooding occurs (sq. feet or sq. meters). See description for Junctions.                                                                                   |
-| **Diverted Link**  | Name of the link which receives the diverted flow.                                                                                                                                                              |
-| **Type**           | Type of flow divider: 
 - **CUTOFF**: Diverts all inflow above a defined cutoff value. 
 - **OVERFLOW**: Diverts all inflow above the flow capacity of the non-diverted link. 
 - **TABULAR**: Uses a Diversion Curve to express diverted flow as a function of the total inflow. 
 - **WEIR**: Uses a weir equation to compute diverted flow. |
-
-### CUTOFF Divider
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Cutoff Flow**    | Cutoff flow value used for a CUTOFF divider (flow units).                                                                                                                                                        |
-
-### TABULAR Divider
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Curve Name**     | Name of the Diversion Curve for a TABULAR divider (double-click to edit).                                                                                                                                       |
-
-### WEIR Divider
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Min. Flow**      | Minimum flow at which diversion begins for a WEIR divider (flow units).                                                                                                                                         |
-| **Max. Depth**     | Vertical height of the WEIR opening (feet or meters).                                                                                                                                                           |
-| **Coefficient**    | Product of the WEIR's discharge coefficient and its length. Typical values range from 2.65 to 3.10 per foot for flows in CFS.                                                                                   |
-
-**Note:** Flow dividers are operational only for Steady Flow and Kinematic Wave flow routing. For Dynamic Wave flow routing, they behave as Junction nodes.
-
-
-## B.6 Storage Unit Properties {#user_manual_appendix_b_6}    
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned storage unit name.                                                                                                                                                                                |
-| **X-Coordinate**   | Horizontal location of the storage unit on the Study Area Map. If left blank, the storage unit will not appear on the map.                                                                                       |
-| **Y-Coordinate**   | Vertical location of the storage unit on the Study Area Map. If left blank, the storage unit will not appear on the map.                                                                                         |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the storage unit.                                                                                                                  |
-| **Tag**            | Optional label used to categorize or classify the storage unit.                                                                                                                                                  |
-| **Inflows**        | Click the ellipsis button (or press Enter) to assign external direct, dry weather, or RDII inflows to the storage unit.                                                                                          |
-| **Treatment**      | Click the ellipsis button (or press Enter) to edit a set of treatment functions for pollutants within the storage unit.                                                                                          |
-| **Invert El.**     | Elevation of the bottom of the storage unit (feet or meters).                                                                                                                                                    |
-| **Max. Depth**     | Maximum depth of the storage unit (feet or meters).                                                                                                                                                             |
-| **Initial Depth**  | Initial depth of water in the storage unit at the start of the simulation (feet or meters).                                                                                                                     |
-| **Surcharge Depth**| Additional depth of water above full depth that a storage unit can sustain before overflowing (feet or meters). Only used for covered units.                                                                    |
-| **Evap. Factor**   | Fraction of the potential evaporation from the storage unit’s water surface that is realized.                                                                                                                   |
-| **Seepage Loss**   | Click the ellipsis button (or press Enter) to specify optional soil properties that determine seepage loss through the bottom and sloped sides of the storage unit.                                               |
-| **Storage Shape**  | Click the ellipsis button (or press Enter) to specify the shape of the storage unit by relating surface area to depth.                                                                                           |
-
-
-## B.7 Conduit Properties {#user_manual_appendix_b_7}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned conduit name.                                                                                                                                                                                     |
-| **Inlet Node**     | Name of the node on the inlet end of the conduit (normally the end at higher elevation).                                                                                                                         |
-| **Outlet Node**    | Name of the node on the outlet end of the conduit (normally the end at lower elevation).                                                                                                                         |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the conduit.                                                                                                                       |
-| **Tag**            | Optional label used to categorize or classify the conduit.                                                                                                                                                       |
-| **Shape**          | Click the ellipsis button (or press Enter) to edit the geometric properties of the conduit’s cross-section.                                                                                                     |
-| **Max. Depth**     | Maximum depth of the conduit’s cross-section (feet or meters).                                                                                                                                                  |
-| **Length**         | Conduit length (feet or meters).                                                                                                                                                                                |
-| **Roughness**      | Manning’s roughness coefficient (n). See Section A.7 for closed conduit values or Section A.8 for open channel values.                                                                                          |
-| **Inlet Offset**   | Depth or elevation of the conduit invert above the node invert at the upstream end of the conduit (feet or meters).                                                                                             |
-| **Outlet Offset**  | Depth or elevation of the conduit invert above the node invert at the downstream end of the conduit (feet or meters).                                                                                           |
-| **Initial Flow**   | Initial flow in the conduit (flow units).                                                                                                                                                                       |
-| **Maximum Flow**   | Maximum flow allowed in the conduit (flow units). Use 0 or leave blank if not applicable.                                                                                                                       |
-| **Entry Loss Coeff.** | Head loss coefficient associated with energy losses at the entrance of the conduit. For culverts, refer to Table A.11.                                                                                       |
-| **Exit Loss Coeff.** | Head loss coefficient associated with energy losses at the exit of the conduit. For culverts, use a value of 1.0.                                                                                             |
-| **Avg. Loss Coeff.** | Head loss coefficient associated with energy losses along the length of the conduit.                                                                                                                          |
-| **Seepage Loss Rate** | Rate of seepage loss into surrounding soil (inches or millimeters per hour).                                                                                                                                 |
-| **Flap Gate**      | **YES** if a flap gate exists that prevents backflow through the conduit, or **NO** if no flap gate exists.                                                                                                     |
-| **Culvert Code**   | If the conduit is a culvert subject to possible inlet flow control, click the ellipsis button (or press Enter) to select a code number for its inlet geometry from those listed in Appendix A.10.                                                      |
-| **Inlets**         | Click the ellipsis button (or press Enter) to assign a storm drain inlet to a street or open channel conduit.                                                                                                   |
-
-**Note:** Conduits and flow regulators (orifices, weirs, and outlets) can be offset some distance above the invert of their connecting end nodes. The choice of offset convention (Depth or Elevation) can be made on the Status Bar of SWMM’s main window or on the Node/Link Properties page of the Project Defaults dialog.
-
-
-## B.8 Pump Properties {#user_manual_appendix_b_8}
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned pump name.                                                                                                                                                                                        |
-| **Inlet Node**     | Name of the node on the inlet side of the pump.                                                                                                                                                                 |
-| **Outlet Node**    | Name of the node on the outlet side of the pump.                                                                                                                                                                |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the pump.                                                                                                                          |
-| **Tag**            | Optional label used to categorize or classify the pump.                                                                                                                                                         |
-| **Pump Curve**     | Name of the Pump Curve which contains the pump’s operating data (double-click to edit the curve). Enter * for an Ideal pump.                                                                                     |
-| **Initial Status** | Status of the pump (**ON** or **OFF**) at the start of the simulation.                                                                                                                                           |
-| **Startup Depth**  | Depth at the inlet node when the pump turns on (feet or meters). Enter 0 if not applicable.                                                                                                                      |
-| **Shutoff Depth**  | Depth at the inlet node when the pump shuts off (feet or meters). Must be lower than the Startup Depth. Enter 0 if not applicable.                                                                               |
-…
-
-## B.9 Orifice Properties {#user_manual_appendix_b_9}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned orifice name.                                                                                                                                                                                     |
-| **Inlet Node**     | Name of the node on the inlet side of the orifice.                                                                                                                                                              |
-| **Outlet Node**    | Name of the node on the outlet side of the orifice.                                                                                                                                                             |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the orifice.                                                                                                                       |
-| **Tag**            | Optional label used to categorize or classify the orifice.                                                                                                                                                       |
-| **Type**           | Type of orifice (**SIDE** or **BOTTOM**).                                                                                                                                                                       |
-| **Shape**          | Orifice shape (**CIRCULAR** or **RECT_CLOSED**).                                                                                                                                                                |
-| **Height**         | Height of the orifice opening when fully open (feet or meters). Corresponds to the diameter of a circular orifice or the height of a rectangular orifice.                                                       |
-| **Width**          | Width of a rectangular orifice when fully opened (feet or meters).                                                                                                                                              |
-| **Inlet Offset**   | Depth or elevation of the bottom of the orifice above the invert of the inlet node (feet or meters).                                                                                                            |
-| **Discharge Coeff.** | Discharge coefficient (unitless). A typical value is 0.65.                                                                                                                                                    |
-| **Flap Gate**      | **YES** if the orifice has a flap gate that prevents backflow, **NO** otherwise.                                                                                                                                |
-| **Time to Open/Close** | Time it takes to open a closed (or close an open) gated orifice in decimal hours. Use 0 or leave blank if timed openings/closings do not apply. Use Control Rules to adjust gate position.                                                         |
-
-
-## B.10 Weir Properties {#user_manual_appendix_b_10}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned weir name.                                                                                                                                                                                        |
-| **Inlet Node**     | Name of the node on the inlet side of the weir.                                                                                                                                                                 |
-| **Outlet Node**    | Name of the node on the outlet side of the weir.                                                                                                                                                                |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the weir.                                                                                                                          |
-| **Tag**            | Optional label used to categorize or classify the weir.                                                                                                                                                         |
-| **Type**           | Weir type: **TRANSVERSE**, **SIDEFLOW**, **V-NOTCH**, **TRAPEZOIDAL**, or **ROADWAY**.                                                                                                                           |
-| **Height**         | Vertical height of the weir opening (feet or meters).                                                                                                                                                           |
-| **Length**         | Horizontal length of the weir opening (feet or meters).                                                                                                                                                         |
-| **Side Slope**     | Slope (run/rise) of side walls for a **V-NOTCH** or **TRAPEZOIDAL** weir.                                                                                                                                       |
-| **Inlet Offset**   | Depth or elevation of the bottom of the weir opening from the invert of the inlet node (feet or meters).                                                                                                        |
-| **Discharge Coeff.** | Discharge coefficient for flow through the central portion of the weir. Typical values are: 
 - 3.33 US (1.84 SI) for sharp-crested transverse weirs. 
 - 2.5–3.3 US (1.38–1.83 SI) for broad-crested rectangular weirs. 
 - 2.4–2.8 US (1.35–1.55 SI) for V-notch weirs. |
-| **Flap Gate**      | **YES** if the weir has a flap gate that prevents backflow, **NO** otherwise.                                                                                                                                   |
-| **End Contractions** | Number of end contractions for a **TRANSVERSE** or **TRAPEZOIDAL** weir whose length is shorter than the channel it is placed in. Values will be 0, 1, or 2 depending on the number of beveled ends.                                                |
-| **End Coeff.**     | Discharge coefficient for flow through the triangular ends of a **TRAPEZOIDAL** weir.                                                                                                                           |
-| **Can Surcharge**  | **YES** if the weir can surcharge (have an upstream water level higher than the height of the opening), or **NO** if it cannot.                                                                                 |
-| **Coeff. Curve**   | Name of an optional Weir Curve that allows the central Discharge Coeff. to vary with head (ft or m) across the weir. Does not apply to Roadway weirs.                                                            |
-
-## 6.1 ROADWAY WEIR (Used Only for Roadway Weirs)
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Road Width**     | Width of the roadway and shoulders (feet or meters).                                                                                                                                                            |
-| **Road Surface**   | Type of road surface: **PAVED** or **GRAVEL**.                                                                                                                                                                  |
-
----
-
-## B.17 Outlet Properties {#user_manual_appendix_b_17}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Name**           | User-assigned outlet name.                                                                                                                                                                                      |
-| **Inlet Node**     | Name of the node on the inflow side of the outlet.                                                                                                                                                              |
-| **Outlet Node**    | Name of the node on the discharge side of the outlet.                                                                                                                                                           |
-| **Description**    | Click the ellipsis button (or press Enter) to edit an optional description of the outlet.                                                                                                                        |
-| **Tag**            | Optional label used to categorize or classify the outlet.                                                                                                                                                       |
-| **Inlet Offset**   | Depth or elevation of the outlet above the inlet node invert (feet or meters).                                                                                                                                  |
-| **Flap Gate**      | **YES** if the outlet has a flap gate that prevents backflow, **NO** otherwise.                                                                                                                                 |
-| **Rating Curve**   | Method of defining flow (Q) as a function of depth or head (y) across the outlet: 
 - **FUNCTIONAL/DEPTH**: Uses a power function (Q = Ay^B) where y is the depth of water above the outlet’s opening at the inlet node. 
 - **FUNCTIONAL/HEAD**: Uses the same power function except y is the difference in head across the outlet’s nodes. 
 - **TABULAR/DEPTH**: Uses a tabulated curve of flow versus depth of water above the outlet’s opening at the inlet node. 
 - **TABULAR/HEAD**: Uses a tabulated curve of flow versus the difference in head across the outlet’s nodes. |
-
-### FUNCTIONAL (Used Only for a Functional Rating Curve)
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Coefficient**    | Coefficient (A) for the functional relationship between depth or head and flow rate.                                                                                                                            |
-| **Exponent**       | Exponent (B) used for the functional relationship between depth or head and flow rate.                                                                                                                          |
-
-### TABULAR (Used Only for a Tabular Rating Curve)
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Curve Name**     | Name of the Rating Curve containing the relationship between depth or head and flow rate (double-click to edit the curve).                                                                                       |
-
----
-
-## B.18 Map Label Properties {#user_manual_appendix_b_18}
-
-| **Property**       | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Text**           | Text of the label.                                                                                                                                                                                              |
-| **X-Coordinate**   | Horizontal location of the upper-left corner of the label on the Study Area Map.                                                                                                                                |
-| **Y-Coordinate**   | Vertical location of the upper-left corner of the label on the Study Area Map.                                                                                                                                  |
-| **Anchor Node**    | Name of the node (or subcatchment) that anchors the label's position when the map is zoomed in (i.e., the pixel distance between the node and the label remains constant). Leave blank if anchoring is not used.  |
-| **Font**           | Click the ellipsis button (or press Enter) to modify the font used to draw the label.                                                                                                                           |
-
-
-
-
diff --git a/docs/manuals/user/manual/AppendixC.md b/docs/manuals/user/manual/AppendixC.md
deleted file mode 100644
index f1f6ac930..000000000
--- a/docs/manuals/user/manual/AppendixC.md
+++ /dev/null
@@ -1,1429 +0,0 @@
-@page user_manual_appendix_c APPENDIX C - SPECIALIZED PROPERTY EDITORS
-
-@tableofcontents
-
-## C.1 Aquifer Editor {#user_manual_appendix_c_1}
-
-The Aquifer Editor is invoked whenever a new aquifer object is created or an existing aquifer object is selected for editing. It contains the following data fields:
-
- 
-## Aquifer Properties {#user_manual_appendix_c_1_aquifer_properties}
-
-| **Property**               | **Description**                                                                                                                                                     |
-|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Aquifer Name**           | User-assigned aquifer name.                                                                                                                                        |
-| **Porosity**               | Volume of voids / total soil volume (volumetric fraction).                                                                                                         |
-| **Wilting Point**          | Volume of pore water relative to total volume for a well-dried soil where only bound water remains. The moisture content of the soil cannot fall below this limit. |
-| **Field Capacity**         | Volume of pore water relative to total volume after the soil has been allowed to drain fully. Below this level, vertical drainage does not occur.                  |
-| **Conductivity**           | Soil's saturated hydraulic conductivity (in/hr or mm/hr).                                                                                                         |
-| **Conductivity Slope**     | Average slope of log(conductivity) versus soil moisture deficit (porosity minus moisture content) curve (unitless).                                                |
-| **Tension Slope**          | Average slope of soil tension versus soil moisture content curve (inches or mm).                                                                                  |
-| **Upper Evaporation Fraction** | Fraction of total evaporation available for evapotranspiration in the upper unsaturated zone.                                                                  |
-| **Lower Evaporation Depth** | Maximum depth below the surface at which evapotranspiration from the lower saturated zone can still occur (ft or m).                                              |
-| **Lower Groundwater Loss Rate** | Rate of percolation to deep groundwater when the water table reaches the ground surface (in/hr or mm/hr).                                                     |
-| **Bottom Elevation**       | Elevation of the bottom of the aquifer (ft or m).                                                                                                                 |
-| **Water Table Elevation**  | Elevation of the water table in the aquifer at the start of the simulation (ft or m).                                                                              |
-| **Unsaturated Zone Moisture** | Moisture content of the unsaturated upper zone of the aquifer at the start of the simulation (volumetric fraction) (cannot exceed soil porosity).               |
-| **Upper Evaporation Pattern** | Name of the monthly time pattern of adjustments applied to the upper evaporation fraction (optional – leave blank if not applicable).                           |
-
-## C.2 Climatology Editor {#user_manual_appendix_c_2}
-
-The Climatology Editor is used to enter values for various climate-related variables required by certain SWMM simulations. The dialog is divided into six tabbed pages, where each page provides a separate editor for a specific category of climate data.
-
-Temperature Page
-
- 
-
-The Temperature page of the Climatology Editor dialog is used to specify the source of temperature data used for snowmelt computations. It is also used to select a climate file as a possible source for evaporation rates. There are three choices available:
-
-| **Option**               | **Description**                                                                                                                                                                                                 |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **No Data**              | Select this choice if snowmelt is not being simulated and evaporation rates are not based on data in a climate file.                                                                                           |
-| **Time Series**          | Select this choice if the variation in temperature over the simulation period will be described by one of the project's time series. Also, enter (or select) the name of the time series. Click the button to make the Time Series Editor appear for the selected time series. |
-| **External Climate File**| Select this choice if min/max daily temperatures will be read from an external climate file (see Section 11.4). Also choose this option if you want daily evaporation rates to be estimated from daily temperatures or be read directly from the file. Then do the following: 
  • Click the button to search for a climate file or click the button to clear the file name.
  • To start reading the climate file at a particular date in time that is different than the start date of the simulation (as specified in the Simulation Options), check off the “Start Reading File at” box and enter a starting date (month/day/year) in the date entry field next to it.
  • If using a NOAA-GHCN file, specify the temperature units used by the file.
|
-
- 
-Evaporation Page
-
- 
-The Evaporation page of the Climatology Editor dialog is used to specify evaporation rates for a study area. These rates are provided in inches/day (or mm/day). There are five options for specifying evaporation rates, selected from the **Source of Evaporation Rates** combo box:
-
-| **Option**                          | **Description**                                                                                                                                                                                                 |
-|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Constant Value**                  | Use this option if evaporation remains constant over time. Enter the value in the provided edit box.                                                                                                           |
-| **Time Series**                     | Select this option if evaporation rates are specified in a time series. Enter or select the name of the time series in the dropdown combo box. Note that for each date in the time series, the evaporation rate remains constant until the next date in the series (interpolation is not used). |
-| **Climate File**                    | This option indicates that daily evaporation rates will be read from the same climate file specified for temperature. Enter monthly pan coefficients in the data grid (these convert pan evaporation to actual evaporation and are typically around 0.7). |
-| **Monthly Averages**                | Use this option to supply an average evaporation rate for each month of the year. Enter the value for each month in the data grid. Rates remain constant within each month.                                    |
-| **Temperatures**                    | The Hargreaves method will compute daily evaporation rates from the daily air temperature record in the external climate file specified on the Temperature page. This method also uses the site’s latitude, which can be entered on the Snowmelt page, even if snowmelt is not simulated. |
-| **Evaporate Only During Dry Periods** | Select this option if evaporation occurs only during periods without precipitation.                                                                                                                           |
-
-In addition this page allows one to specify an optional **Monthly Soil Recovery Pattern**. This is a time pattern whose factors adjust the rate at which infiltration capacity is recovered during periods with no precipitation. It applies to all subcatchments for any choice of infiltration method. For example, if the normal infiltration recovery rate was 1% during a specific time period and a pattern factor of 0.8 applied to this period, then the actual recovery rate would be 0.8%. The Soil Recovery Pattern allows one to account for seasonal soil drying rates. In principle, the variation in pattern factors should mirror the variation in evaporation rates but might be influenced by other factors such as seasonal groundwater levels. The   button is used to launch the Time Pattern Editor for the selected pattern.
- 
-Wind Speed Page
-
-
-The Wind Speed page of the Climatology Editor dialog is used to provide average monthly wind speeds. These are used when computing snowmelt rates under rainfall conditions, as melt rates increase with increasing wind speed. Units of wind speed are miles/hour for US units and km/hour for metric units. There are two options for specifying wind speeds:
-
-
-| **Option**          | **Description**                                                                                                                                                                                                 |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Climate File Data** | Wind speeds will be read from the same climate file that was specified for temperature.                                                                                                                       |
-| **Monthly Averages**  | Wind speed is specified as an average value that remains constant in each month of the year. Enter a value for each month in the data grid provided. The default values are all zero.                                                               |
-
-Snowmelt Page
-
-
-The Snowmelt page of the Climatology Editor dialog is used to supply values for the following parameters related to snowmelt calculations:
-
-| **Parameter**                     | **Description**                                                                                                                                                                                                 |
-|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Dividing Temperature Between Snow and Rain** | Temperature below which precipitation falls as snow instead of rain. Use degrees F for US units or degrees C for metric units.                                                                              |
-| **ATI (Antecedent Temperature Index) Weight** | Reflects the degree to which heat transfer within a snowpack during non-melt periods is affected by prior air temperatures. Smaller values reflect a thicker surface layer of snow, resulting in reduced rates of heat transfer. Values must be between 0 and 1. Default is 0.5. |
-| **Negative Melt Ratio**           | Ratio of the heat transfer coefficient of a snowpack during non-melt conditions to the coefficient during melt conditions. Must be a number between 0 and 1. Default value is 0.6.                              |
-| **Elevation Above MSL**           | Average elevation above mean sea level for the study area, in feet or meters. Used to provide a more accurate estimate of atmospheric pressure. Default is 0.0, which results in a pressure of 29.9 inches Hg. Higher pressures (lower elevations) increase the effect of wind on snowmelt rates during rainfall periods. |
-| **Latitude**                      | Latitude of the study area in degrees North. Used to compute hours of sunrise and sunset, which extend min/max daily temperatures into continuous values. Also used to compute daily evaporation rates from daily temperatures. Default is 50 degrees North. |
-| **Longitude Correction**          | Correction, in minutes of time, between true solar time and standard clock time. Depends on a location's longitude (θ) and the standard meridian of its time zone (SM) through the expression 4(θ-SM). Adjusts hours of sunrise and sunset when extending daily min/max temperatures into continuous values. Default value is 0. |
- 
-Areal Depletion Page
-
- 
-
-The Areal Depletion page of the Climatology Editor Dialog is used to specify points on the Areal Depletion Curves for both impervious and pervious surfaces within a project's study area. These curves define the relation between the area that remains snow covered and snow pack depth. Each curve is defined by 10 equal increments of relative depth ratio between 0 and 0.9. (Relative depth ratio is the ratio of an area's current snow depth to the depth at which there is 100% areal coverage).  Enter values in the data grid provided for the fraction of each area that remains snow covered at each specified relative depth ratio. Valid numbers must be between 0 and 1, and be increasing with increasing depth ratio.
-
-Clicking the Natural Area button fills the grid with values that are typical of natural areas. Clicking the No Depletion button will fill the grid with all 1's, indicating that no areal depletion occurs. This is the default for new projects.
-
-Adjustments Page
-
- 
-
-The Adjustments page of the Climatology Editor Dialog is used to supply a set of monthly adjustments applied to the temperature, evaporation rate, rainfall, and soil hydraulic conductivity that SWMM uses at each time step of a simulation:
-    The monthly Temperature adjustment (plus or minus in either degrees F or C) is added to the temperature value that SWMM would otherwise use in a specific month of the year.
-    The monthly Evaporation adjustment (plus or minus in either in/day or mm/day) is added to the evaporation rate value that SWMM would otherwise use in a specific month of the year.
-    The monthly Rainfall adjustment is a multiplier applied to the precipitation value that SWMM would otherwise use in a specific month of the year.
-    The monthly Conductivity adjustment is a multiplier applied to the soil hydraulic conductivity used compute rainfall infiltration, groundwater percolation, and exfiltration from channels and storage units.
-
-The same adjustment is applied for each time period within a given month and is repeated for that month in each subsequent year being simulated. Leaving a monthly adjustment blank means that there is no adjustment made in that month.
- 
-    Control Rules Editor
-
-The Control Rules Editor is invoked whenever a new control rule is created or an existing rule is selected for editing. The editor contains a memo field where the entire collection of control rules is displayed and can be edited.
-
- 
-
-Control Rule Format
-
-Each control rule is a series of statements of the form:
-```
-RULE  ruleID
-IF    condition_1
-AND   condition_2
-OR    condition_3
-AND   condition_4
-Etc.
-THEN  action_1
-AND   action_2
-Etc.
-ELSE  action_3
-AND   action_4
-Etc.
-PRIORITY value
-```
-where keywords are shown in boldface and ruleID is an ID label assigned to the rule, condition_n is a Condition Clause, action_n is an Action Clause, and value is a priority value (e.g., a number from 1 to 5). The formats used for Condition and Action clauses are discussed below.
-
-Only the RULE, IF and THEN portions of a rule are required; the ELSE and PRIORITY portions are optional.
-
-Blank lines between clauses are permitted and any text to the right of a semicolon is considered a comment.
-
-When mixing AND and OR clauses, the OR operator has higher precedence than AND, i.e.,
-
-```
-IF A or B and C
-is equivalent to
-IF (A or B) and C.
-If the interpretation was meant to be
-IF A or (B and C)
-then this can be expressed using two rules as in
-IF A THEN ...
-IF B and C THEN ...
-```
-The PRIORITY value is used to determine which rule applies when two or more rules require that conflicting actions be taken on a link. A conflicting rule with a higher priority value has precedence over one with a lower value (e.g., PRIORITY 5 outranks PRIORITY 1). A rule without a priority value always has a lower priority than one with a value. For two rules with the same priority value, the rule that appears first is given the higher priority.
-
-Condition Clauses
-
-A Condition Clause of a control rule has the following formats:
- object id attribute relation value
- object id attribute relation object id attribute
-where:
-object        =    a category of object
-id                =    the object's ID name
-attribute    =    an attribute or property of the object
-relation        =    a relational operator (=, <>, <, <=, >, >=)
-value            =    an attribute value
-
-Some examples of condition clauses are:
-
-GAGE  G1   6-HR_DEPTH > 0.5 
-NODE  N23  DEPTH  >  10
-NODE  N23  DEPTH  >  NODE N25 DEPTH
-PUMP  P45  STATUS =  OFF
-SIMULATION CLOCKTIME = 22:45:00
-
-The objects and attributes that can appear in a condition clause are as follows:
-
-```
-Object    Attributes    Value
-GAGE    INTENSITY
-n-HR_DEPTH    numerical value
-NODE    DEPTH
-MAXDEPTH
-HEAD
-VOLUME
-INFLOW    numerical value
-
-LINK or
-CONDUIT
-    FLOW
-FULLFLOW
-DEPTH
-MAXDEPTH
-VELOCITY
-LENGTH
-SLOPE    numerical value
-
-    STATUS    OPEN or CLOSED
-    TIMEOPEN
-TIMECLOSED
-    decimal hours or hr:min
-PUMP    STATUS    ON or OFF
-    SETTING    pump curve multiplier
-    FLOW    numerical value
-ORIFICE    SETTING    fraction open
-WEIR    SETTING    fraction open
-OUTLET    SETTING    rating curve multiplier
-SIMULATION    TIME    elapsed time in decimal hours or hr:min:sec
-    DATE    month/day/year
-    MONTH    month of year (January = 1)
-    DAY    day of week (Sunday = 1)
-    CLOCKTIME    time of day in hr:min:sec
-```
-Gage INTENSITY is the rainfall intensity for a specific rain gage in the current simulation time period. Gage n-HR_DEPTH is a gage's total rainfall depth over the past n hours where n is a number between 1 and 48.
-
-TIMEOPEN is the duration a link has been in an OPEN or ON state or have its SETTING be greater than zero; TIMECLOSED is the duration it has remained in a CLOSED or OFF state or have its SETTING be zero. Both TIMEOPEN and TIMECLOSED apply to all link objects, including pumps, orifices, weirs, and outlets.
-
-Action Clauses
-
-An Action Clause of a control rule can have one of the following formats:
-CONDUIT id STATUS = OPEN/CLOSED
-PUMP id STATUS = ON/OFF
-PUMP/ORIFICE/WEIR/OUTLET id SETTING = value
-where the meaning of SETTING depends on the object being controlled:
-    for Pumps it is a multiplier applied to the flow computed from the pump curve (for a Type5 pump curve it is a relative speed setting that shifts the curve up or down),
-    for Orifices it is the fractional amount that the orifice is fully open,
-    for Weirs it is the fractional amount of the original freeboard that exists (i.e., weir control is accomplished by moving the crest height up or down),
-    for Outlets it is a multiplier applied to the flow computed from the outlet's rating curve.
-
-Some examples of action clauses are:
-PUMP P67 STATUS = OFF
-ORIFICE O212 SETTING = 0.5
-
-Modulated Controls
-
-Modulated controls are control rules that provide for a continuous degree of control applied to a pump or flow regulator as determined by the value of some controller variable, such as water depth at a node, or by time. The functional relation between the control setting and the controller variable can be specified by using a Control Curve, a Time Series, or a PID Controller. Some examples of modulated control rules are:
-
-RULE MC1
-IF NODE N2 DEPTH >= 0
-THEN WEIR W25 SETTING = CURVE C25
-
-
-RULE MC2
-IF SIMULATION TIME > 0
-THEN PUMP P12 SETTING = TIMESERIES TS101 
-
-RULE MC3
-IF LINK L33 FLOW <> 1.6
-THEN ORIFICE O12 SETTING = PID 0.1 0.0 0.0
-
-Note how a modified form of the action clause is used to specify the name of the control curve, time series or PID parameter set that defines the degree of control. A PID parameter set contains three values -- a proportional gain coefficient, an integral time (in minutes), and a derivative time (in minutes). Also, by convention the controller variable used in a Control Curve or PID Controller will always be the object and attribute named in the last condition clause of the rule. As an example, in rule MC1 above Curve C25 would define how the fractional setting at Weir W25 varied with the water depth at Node N2. In rule MC3, the PID controller adjusts the opening of Orifice O12 to maintain a flow of 1.6 in Link L33.
-
-PID Controllers
-
-A PID (Proportional-Integral-Derivative) Controller is a generic closed-loop control scheme that tries to maintain a desired set-point on some process variable by computing and applying a corrective action that adjusts the process accordingly. In the context of a hydraulic conveyance system a PID controller might be used to adjust the opening on a gated orifice to maintain a target flow rate in a specific conduit or to adjust a variable speed pump to maintain a desired depth in a storage unit. The classical PID controller has the form:
-
-m(t)=K_p [e(t)+1/T_i  ∫▒e(τ)dτ+T_d  (de(t))/dt]
-
-where m(t) = controller output, Kp = proportional coefficient (gain), Ti = integral time, Td = derivative time, e(t) = error (difference between setpoint and observed variable value), and t = time. The performance of a PID controller is determined by the values assigned to the coefficients Kp, Ti, and Td.
-
-The controller output m(t) has the same meaning as a link setting used in a rule's Action Clause while dt is the current flow routing time step in minutes. Because link settings are relative values (with respect to either a pump's standard operating curve or to the full opening height of an orifice or weir) the error e(t) used by the controller is also a relative value. It is defined as the difference between the control variable setpoint x* and its value at time t, x(t), normalized to the setpoint value: e(t) = (x* - x(t)) / x*.
-
-Note that for direct action control, where an increase in the link setting causes an increase in the controlled variable, the sign of Kp must be positive. For reverse action control, where the controlled variable decreases as the link setting increases, the sign of Kp must be negative. The user must recognize whether the control is direct or reverse action and use the proper sign on Kp accordingly. For example, adjusting an orifice opening to maintain a desired downstream flow is direct action. Adjusting it to maintain an upstream water level is reverse action. Controlling a pump to maintain a fixed wet well water level would be reverse action while using it to maintain a fixed downstream flow is direct action.
-
-Named Variables
-
-Named Variables are aliases used to represent the triplet of <object type | object id | object attribute> (or a doublet for Simulation times) that appear in the condition clauses of control rules. They allow condition clauses to be written as:
-variable relation value
-variable relation variable
-where variable is defined on a separate line before its first use in a rule using the format:
-VARIABLE  name = object id attribute
-
-Here is an example of using this feature:
-VARIABLE  N123_Depth = NODE N123 DEPTH
-VARIABLE  N456_Depth = NODE N456 DEPTH
-VARIABLE  P45 = PUMP 45 STATUS
-RULE 1
-IF    N123_Depth > N456_Depth
-AND   P45 = OFF
-THEN  PUMP 45 STATUS = ON
-
-RULE 2
-IF   N123_Depth < 1
-THEN PUMP 45 STATUS = OFF
-
-A variable is not allowed to have the same name as an object attribute.
-
-Aside from saving some typing, named variables are required when using arithmetic expressions in rule condition clauses.
-Arithmetic Expressions
-
-In addition to a simple condition placed on a single variable, a control condition clause can also contain an arithmetic expression formed from several variables whose value is compared against. Thus the format of a condition clause can be extended as follows:
-expression  relation  value
-expression  relation  variable
-where expression is defined on a separate line before its first use in a rule using the format:
-EXPRESSION  name = f(variable1, variable2, ...)
-
-The function f(...) can be any well-formed mathematical expression containing one or more named variables as well as any of the following math functions (which are case insensitive) and operators:
-    abs(x) for absolute value of x
-    sgn(x) which is +1 for x >= 0 or -1 otherwise
-    step(x) which is 0 for x <= 0 and 1 otherwise
-    sqrt(x) for the square root of x
-    log(x) for logarithm base e of x
-    log10(x) for logarithm base 10 of x
-    exp(x) for e raised to the x power
-    the standard trig functions (sin, cos, tan, and cot)
-    the inverse trig functions (asin, acos, atan, and acot)
-    the hyperbolic trig functions (sinh, cosh, tanh, and coth)
-    the standard operators  +, -, *, /, ^ (for exponentiation ) and any level of nested parentheses.
-
-Here is an example of using this feature:
-VARIABLE  P1_flow = LINK 1 FLOW
-VARIABLE  P2_flow = LINK 2 FLOW
-VARIABLE  O3_flow = Link 3 FLOW
-EXPRESSION Net_Inflow = (P1_flow + P2_flow)/2 - O3_flow
-
-RULE 1
-IF   Net_Inflow > 0.1
-THEN ORIFICE 3 SETTING = 1
-ELSE ORIFICE 3 SETTING = 0.5
-    Cross-Section Editor
-
-The Cross-Section Editor dialog is used to specify the shape and dimensions of a conduit's cross-section.
-
- 
-
-When a shape is selected from the image list an appropriate set of edit fields appears for describing the dimensions of that shape. Length dimensions are in units of feet for US units and meters for SI units. Slope values represent ratios of horizontal to vertical distance. The Barrels field specifies how many identical parallel conduits exist between its end nodes.
-
-The Force Main shape option is a circular conduit that uses either the Hazen-Williams or Darcy-Weisbach formulas to compute friction losses for pressurized flow during Dynamic Wave flow routing. In this case the appropriate C-factor (for Hazen-Williams) or roughness height (for Darcy-Weisbach) is supplied as a cross-section property. The choice of friction loss equation is made on the Dynamic Wave Simulation Options dialog. Note that a conduit does not have to be assigned a Force Main shape for it to pressurize. Any of the other closed cross-section shapes can potentially pressurize and thus function as force mains using the Manning equation to compute friction losses.
-
-If a Custom shaped section is chosen, a drop-down edit box will appear where one can enter or select the name of a Shape Curve that will be used to define the geometry of the section. This curve specifies how the width of the cross-section varies with height, where both width and height are scaled relative to the section's maximum depth. This allows the same shape curve to be used for conduits of differing sizes. Clicking the Edit button    next to the shape curve box will bring up the Curve Editor where the shape curve's coordinates can be edited.
-
-If a Street shaped section is chosen, a drop-down edit box will appear where one can enter or select the name of a Street object that describes the cross-section's geometry. Clicking the Edit button    next to the edit box will bring up the Street Section Editor where one can edit the street’s geometry.
-
-If an Irregular shaped section is chosen, a drop-down edit box will appear where one can enter or select the name of a Transect object that describes the cross-section's geometry. Clicking the Edit button    next to the edit box will bring up the Transect Editor where one can edit the transect data.
- 
-    Curve Editor
-
-The Curve Editor dialog is invoked whenever a new curve object is created or an existing curve object is selected for editing. The editor adapts itself to the type of curve being edited (Control, Diversion, Pump, Rating, Shape, Storage, Tidal or Weir). 
-
- 
-
-To use the Curve Editor:
-    Enter values for the following data entry fields:
-Name                Name of the curve.
-Type     (Pump Curves Only). Choice of pump curve type as described in Section 3.2.8. 
-Description    Optional comment or description of what the curve represents. Click the   button to launch a multi-line comment editor if more than one line is needed. 
-Data Grid            The curve's X,Y data.
-    Click the View button to see a graphical plot of the curve drawn in a separate window.
-    If additional rows are needed in the Data Grid, simply press the Enter key when in the last row.
-    Right-clicking over the Data Grid will make a popup Edit menu appear. It contains commands to cut, copy, insert, and paste selected cells in the grid as well as options to insert or delete a row.
-    Press OK to accept the curve entries or Cancel to cancel the edits made.
-One can also click the Load button to load in a curve that was previously saved to file or click the Save button to save the current curve's data to a file.
- 
-    Groundwater Flow Editor
-
-The Groundwater Flow Editor dialog is invoked when the Groundwater property of a subcatchment is being edited. It is used to link a subcatchment to both an aquifer and to a node of the drainage system that exchanges groundwater with the aquifer.
-
- 
-
-The editor also specifies coefficients that determine the rate of lateral groundwater flow between the aquifer and the node. These coefficients (A1, A2, B1, B2, and A3) appear in the following equation that computes groundwater flow as a function of groundwater and surface water levels:
-Q_L=A1〖(H_gw-H_cb)〗^B1-A2〖(H_sw-H_cb)〗^B2+A3H_gw H_sw
-where:
-QL        =   lateral groundwater flow (cfs per acre or cms per hectare)
-Hgw     =   height of saturated zone above bottom of aquifer (ft or m)
-Hsw     =   height of surface water at receiving node above aquifer bottom (ft or m)
-Hcb        =   height of channel bottom above aquifer bottom (ft or m).
-Note that QL can also be expressed in inches/hr for US units.
-The rate of percolation to deep groundwater, QD, in in/hr (or mm/hr) is given by the following equation:
-Q_D=LGLR(H_GW/H_GS )
-where LGLR is the lower groundwater loss rate parameter assigned to the subcatchment's aquifer (in/hr or mm/hr) and HGS is the distance from the ground surface to the aquifer bottom (ft or m).
-
-In addition to the standard lateral flow equation, the dialog allows one to define a custom equation whose results will be added onto those of the standard equation. One can also define a custom equation for deep groundwater flow that will replace the standard one. Finally, the dialog offers the option to override certain parameters that were specified for the aquifer to which the subcatchment belongs. The properties listed in the editor are as follows:
-
-Aquifer Name
-Name of the aquifer object that describes the subsurface soil properties, thickness, and initial conditions. Leave this field blank if you want the subcatchment not to generate any groundwater flow.
-
-Receiving Node
-Name of node that receives groundwater from the aquifer.
-
-Surface Elevation
-Elevation of ground surface for the subcatchment that lies above the aquifer in feet or meters.
-
-Groundwater Flow Coefficient
-Value of A1 in the groundwater flow formula.
-
-Groundwater Flow Exponent
-Value of B1 in the groundwater flow formula.
-
-Surface Water Flow Coefficient
-Value of A2 in the groundwater flow formula.
-
-Surface Water Flow Exponent
-Value of B2 in the groundwater flow formula.
-
-Surface-GW Interaction Coefficient
-Value of A3 in the groundwater flow formula.
-Surface Water Depth
-Fixed depth of surface water above receiving node’s invert (feet or meters). Set to zero if surface water depth will vary as computed by flow routing.
-
-Threshold Water Table Elevation
-Minimum water table elevation that must be reached before any flow occurs (feet or meters). Leave blank to use the receiving node's invert elevation.
-
-Aquifer Bottom Elevation
-Elevation of the bottom of the aquifer below this particular subcatchment (feet or meters). Leave blank to use the value from the parent aquifer.
-
-Initial Water Table Elevation
-Initial water table elevation at the start of the simulation for this particular subcatchment (feet or meters). Leave blank to use the value from the parent aquifer.
-
-Unsaturated Zone Moisture
-Moisture content of the unsaturated upper zone above the water table for this particular subcatchment at the start of the simulation (volumetric fraction). Leave blank to use the value from the parent aquifer.
-
-Custom Lateral Flow Equation
-Click the ellipsis button (or press Enter) to launch the Custom Groundwater Flow Equation editor for lateral groundwater flow QL (see section C.7). The equation supplied by this editor will be used in addition to the standard equation to compute groundwater outflow from the subcatchment.
-
-Custom Deep Flow Equation
-Click the ellipsis button (or press Enter) to launch the Custom Groundwater Flow Equation editor for deep groundwater flow QD. The equation supplied by this editor will be used to replace the standard equation for deep groundwater flow.
-
-The coefficients supplied to the groundwater flow equations must be in units that are consistent with the groundwater flow units, which can either be cfs/acre (equivalent to inches/hr) for US units or cms/ha for SI units.
-
-     Note that elevations are used to specify the ground surface, water table height, and aquifer bottom in the dialog’s data entry fields but that the groundwater flow equation uses depths above the aquifer bottom.
-     If groundwater flow is simply proportional to the difference in groundwater and surface water heads, then set the Groundwater and Surface Water Flow Exponents (B1 and B2) to 1.0, set the Groundwater Flow Coefficient (A1) to the proportionality factor, set the Surface Water Flow Coefficient (A2) to the same value as A1, and set the Interaction Coefficient (A3) to zero.
-     When conditions warrant, the groundwater flux can be negative, simulating flow into the aquifer from the channel, in the manner of bank storage. An exception occurs when A3  0, since the surface water - groundwater interaction term is usually derived from groundwater flow models that assume unidirectional flow. Otherwise, to ensure that negative fluxes will not occur, one can make A1 greater than or equal to A2, B1 greater than or equal to B2, and A3 equal to zero. 
-     To completely replace the standard groundwater flow equation with the custom equation, set all of the standard equation coefficients to 0. 
- 
-    Groundwater Equation Editor
-
-The Groundwater Equation Editor is used to supply a custom equation for computing groundwater flow between the saturated sub-surface zone of a subcatchment and either a node in the conveyance network (lateral flow) or to a deeper groundwater aquifer (deep flow). It is invoked from the Groundwater Flow Editor form. 
-
- 
-
-For lateral groundwater flow the result of evaluating the custom equation will be added onto the result of the standard equation. To replace the standard equation completely set all of its coefficients to 0. Remember that lateral groundwater flow units are cfs/acre (equivalent to inches/hr) for US units and cms/ha for metric units.
-
- The following symbols can be used in the equation:
-      Hgw    (for height of the groundwater table)
-      Hsw     (for height of the surface water)
-      Hcb     (for height of the channel bottom)
-    Hgs        (for height of the ground surface)
-    Phi        (for porosity of the subsurface soil)
-    Theta    (for moisture content of the upper unsaturated zone)
-    Ks        (for saturated hydraulic conductivity in inches/hr or mm/hr)
-    K        (for hydraulic conductivity at the current moisture content in inches/hr or mm/hr)
-    Fi        (for infiltration rate from the ground surface in inches/hr or mm/hr)
-    Fu        (for percolation rate from the upper unsaturated zone in inches/hr or mm/hr)
-    A        (for subcatchment area in acres or hectares)
-where all heights are relative to the aquifer's bottom elevation in feet (or meters).
-The STEP function can be used to have flow only when the groundwater level is above a certain threshold. For example, the expression:
-   0.001 * (Hgw - 5) * STEP(Hgw - 5)
-would generate flow only when Hgw was above 5. See Section C.22 (Treatment Editor) for a list of additional math functions that can be used in a groundwater flow expression.
-    Infiltration Editor
-
-The Infiltration Editor dialog is used to specify the method and its parameters that model the rate at which rainfall infiltrates into the upper soil zone of a subcatchment's pervious area. It is invoked when editing the Infiltration property of a Subcatchment. The infiltration parameters depend on which infiltration method is selected for the subcatchment: Horton and Modified Horton, Green-Ampt and Modified Green-Ampt, or Curve Number. The infiltration method is normally the default one set by project's Simulation Options (see Section 8.1.1) or its Default Properties (see Section 5.4.2). The dialog allows one to override the default method for the subcatchment being edited.
-
- 
-
-Horton Infiltration Parameters
-
-The following data fields appear in the Infiltration Editor for Horton infiltration:
-Max. Infil. Rate
-Maximum infiltration rate on the Horton curve (in/hr or mm/hr). Representative values are as follows:
-    DRY soils (with little or no vegetation):
-    Sandy soils: 5 in/hr
-    Loam soils: 3 in/hr
-    Clay soils: 1 in/hr
-    DRY soils (with dense vegetation):
-    Multiply values in A. by 2
-    MOIST soils:
-    Soils which have drained but not dried out (i.e., field capacity):
-Divide values from A and B by 3.
-    Soils close to saturation:
-Choose value close to minimum infiltration rate.
-    Soils which have partially dried out:
-Divide values from A and B by 1.5 - 2.5. 
-
-Min. Infil. Rate
-Minimum infiltration rate on the Horton curve (in/hr or mm/hr). Equivalent to the soil’s saturated hydraulic conductivity. See the Soil Characteristics Table in Section A.2 for typical values.
-
-Decay Constant
-Infiltration rate decay constant for the Horton curve (1/hours). Typical values range between 2 and 7.
-
-Drying Time
-Time in days for a fully saturated soil to dry completely. Typical values range from 2 to 14 days.
-
-Max. Infil. Vol.
-Maximum infiltration volume possible (inches or mm, 0 if not applicable). It can be estimated as the difference between a soil's porosity and its wilting point times the depth of the infiltration zone.
-
-Green-Ampt Infiltration Parameters
-
-The following data fields appear in the Infiltration Editor for Green-Ampt infiltration:
-Suction Head
-Average value of soil capillary suction along the wetting front (inches or mm).
-
-Conductivity
-Soil saturated hydraulic conductivity (in/hr or mm/hr).
-
-
-
-Initial Deficit
-Fraction of soil volume that is initially dry (i.e., difference between soil porosity and initial moisture content). For a completely drained soil, it is the difference between the soil's porosity and its field capacity.
-
-Typical values for all of these parameters can be found in the Soil Characteristics Table in Section A.2.
-
-Curve Number Infiltration Parameters
-
-The following data fields appear in the Infiltration Editor for Curve Number infiltration:
-Curve Number
-This is the SCS curve number which is tabulated in the publication SCS Urban Hydrology for Small Watersheds, 2nd Ed., (TR-55), June 1986. Consult the Curve Number Table (Section A.4) for a listing of values by soil group, and the accompanying Soil Group Table (Section A.3) for the definitions of the various groups.
-
-Conductivity
-This property has been deprecated and is no longer used.
-
-Drying Time
-The number of days it takes a fully saturated soil to dry. Typical values range between 2 and 14 days.
- 
-    Inflows Editor
-
-The Inflows Editor dialog is used to assign Direct, Dry Weather, and RDII inflow into a node of the drainage system. It is invoked whenever the Inflows property of a Node object is selected in the Property Editor. The dialog consists of three tabbed pages that provide a special editor for each type of inflow.
-
- 
-
-Direct Inflows Page
-
-The Direct page on the Inflows Editor dialog is used to specify the time history of direct external flow and water quality entering a node of the drainage system. These inflows are represented by both a constant and time varying component as follows:
-
-Inflow at time t = (baseline value)*(baseline pattern factor) + 
-   (scale factor)*(time series value at time t)
-
-The page contains the following input fields that define the properties of this relation:
-
-Constituent
-Selects the constituent (FLOW or one of the project's specified pollutants) whose direct inflow will be described.
-
-Baseline
-Specifies the value of the constant baseline component of the constituent's inflow. For FLOW, the units are the project's flow units. For pollutants, the units are the pollutant's concentration units if inflow is a concentration, or can be any mass flow units if the inflow is a mass flow (see Conversion Factor below). If left blank then no baseline inflow is assumed.
-
-Baseline Pattern
-An optional Time Pattern whose factors adjust the baseline inflow on either an hourly, daily, or monthly basis (depending on the type of time pattern specified). Clicking the   button will bring up the Time Pattern Editor dialog for the selected time pattern. If left blank, then no adjustment is made to the baseline inflow.
-
-Time Series
-Specifies the name of the time series that contains inflow data for the selected constituent. If left blank then no direct inflow will occur for the selected constituent at the node in question. You can click the   button to bring up the Time Series Editor dialog for the selected time series.
-
-Scale Factor
-A multiplier used to adjust the values of the constituent's inflow time series. The baseline value is not adjusted by this factor. The scale factor can have several uses, such as allowing one to easily change the magnitude of an inflow hydrograph while keeping its shape the same, without having to re-edit the entries in the hydrograph time series. Or it can allow a group of nodes sharing the same time series to have their inflows behave in a time-synchronized fashion while letting their individual magnitudes be different. If left blank the scale factor defaults to 1.0.
-
-Inflow Type
-For pollutants, selects the type of inflow data contained in the time series as being either a concentration (mass/volume) or mass flow rate (mass/time). This field does not appear for FLOW inflow.
-
-Units Factor
-A numerical factor used to convert the units of pollutant mass flow rate in the time series data into concentration mass units per second. For example, if the time series data were in pounds per day and the pollutant concentration defined in the project was mg/L, then the conversion factor value would be (453,590 mg/lb) / (86400 sec/day) = 5.25 (mg/sec) per (lb/day).
-
-More than one constituent can be edited while the dialog is active by simply selecting another choice for the Constituent property. However, if the Cancel button is clicked then any changes made to all constituents will be ignored.
-
-     If a pollutant is assigned a direct inflow in terms of concentration, then one must also assign a direct inflow to flow, otherwise no pollutant inflow will occur. An exception is at submerged outfalls where pollutant intrusion can occur during periods of reverse flow. If pollutant inflow is defined in terms of mass, then a flow inflow time series is not required.
-
-Dry Weather Inflows Page
-
- 
-The Dry Weather page of the Inflows Editor dialog is used to specify a continuous source of dry weather flow entering a node of the drainage system. The page contains the following input fields:
-
-Constituent
-Selects the constituent (FLOW or one of the project's specified pollutants) whose dry weather inflow will be specified.
-
-Average Value
-Specifies the average (or baseline) value of the dry weather inflow of the constituent in the relevant units (flow units for flow, concentration units for pollutants). Leave blank if there is no dry weather flow for the selected constituent.
-
-Time Patterns
-Specifies the names of the time patterns to be used to allow the dry weather flow to vary in a periodic fashion by month of the year, by day of the week, and by time of day (for both weekdays and weekends). One can either type in a name or select a previously defined pattern from the dropdown list of each combo box. Up to four different types of patterns can be assigned. You can click the   button next to each Time Pattern field to edit the respective pattern.
-
-More than one constituent can be edited while the dialog is active by simply selecting another choice for the Constituent property. However, if the Cancel button is clicked then any changes made to all constituents will be ignored.
-
-RDII Inflow Page
-
-The RDII Inflow page of the Inflows Editor dialog form is used to specify RDII (Rainfall-Dependent Infiltration and Inflow) for the node in question. The page contains the following two input fields:
-
-Unit Hydrograph Group
-Enter (or select from the dropdown list) the name of the Unit Hydrograph group that applies to the node in question. The unit hydrographs in the group are used in combination with the group's assigned rain gage to develop a time series of RDII inflows per unit area over the period of the simulation. Leave this field blank to indicate that the node receives no RDII inflow. Clicking the   button will launch the Unit Hydrograph Editor for the UH group specified.
-
-
-
-
-Sewershed Area
-Enter the area (in acres or hectares) of the sewershed that contributes RDII to the node in question. Note this area will typically be only a small, localized portion of the subcatchment area that contributes surface runoff to the node.
- 
-Initial Buildup Editor
-
-The Initial Buildup Editor is invoked from the Property Editor when editing the Initial Buildup property of a subcatchment. It specifies the amount of pollutant buildup existing over the subcatchment at the start of the simulation.
-
- 
- 
-
-The editor consists of a data entry grid with two columns. The first column lists the name of each pollutant in the project and the second column contains edit boxes for entering the initial buildup values. If no buildup value is supplied for a pollutant, it is assumed to be 0. The units for buildup are either pounds per acre when US customary units are in use or kilograms per hectare when SI metric units are in use. 
-
-If a non-zero value is specified for the initial buildup of a pollutant, it will override any initial buildup computed from the Antecedent Dry Days parameter specified on the Dates page of the Simulation Options dialog.
- 
-Inlet Structure Editor
-
-The Inlet Structure Editor is invoked when a new Inlet object is created or is selected for editing. As shown below it contains an Inlet Name field used to uniquely identify the inlet structure and an Inlet Type field to select the type of structure.
-
- 
-
-The design parameters shown in the data entry panel depend on the choice of inlet type.
-
-Grate Inlet
-
-The design parameters for a grated inlet include:
-
-Grate Type
-Select from the choices shown in Table C-1 below.
-
-Length
-The grate's length parallel to the street curb (feet or meters).
-
-Width
-The grate's width (feet or meters).
-
-Open Fraction (for GENERIC grates only)
-The fraction of the grate's area that is open. Values are predetermined for non-Generic grates.
-Splash Velocity (for GENERIC grates only)
-The minimum velocity that causes some water to shoot over the inlet thus reducing its capture efficiency (ft/sec or m/sec). Values are predetermined for non-Generic grates.
-
-Table C 1 Types of grate inlets
-Grate Type    Sketch    Description
-P_BAR-50         Parallel bar grate with bar spacing 1⅞” on center 
-P_BAR-50X100         Parallel bar grate with bar spacing 1⅞” on center and ⅜” diameter lateral rods spaced at 4” on center
-P_BAR-30         Parallel bar grate with 1⅛” on center bar spacing
-CURVED_VANE         Curved vane grate with 3¼” longitudinal bar and 4¼” transverse bar spacing on center
-TILT_BAR-45         45 degree tilt bar grate with 2¼” longitudinal bar and 4” transverse bar spacing on center
-TILT_BAR-30         30 degree tilt bar grate with 3¼” and 4” on center longitudinal and lateral bar spacing respectively
-RETICULINE         "Honeycomb" pattern of lateral bars and longitudinal bearing bars
-GENERIC        A generic grate design.
-
-Curb Opening Inlet
-
-The design parameters for a curb opening inlet are:
-
-Length
-The length of the opening (feet or meters).
-
-Height
-The height of the opening (feet or meters).
-Throat Angle
-The orientation of the curb opening's throat relative to the street surface. Choices are:
-
-Vertical     
-Inclined     
-Horizontal     
-Combination Inlet
-
-Combination inlets use the parameters for both a grate and curb opening inlet. For the curb opening, only the portion that extends beyond the length of the grate contributes to the overall capture efficiency.
-
-Slotted Drain Inlet
-
-The design parameters for a slotted drain inlet are:
-
-Length
-The drain's length parallel to the street curb (feet or meters).
-
-Width
-The drain's width (feet or meters).
-
-Drop Grate Inlet
-
-Drop grate inlets use the same parameters as a grated inlet.
-
-Drop Curb Inlet
-
-Drop curb inlets use the same length and height parameters as a curb opening inlet.
-
-Custom Inlet
-
-The only design parameter for a custom inlet is the name of a user-defined flow capture curve. Two options for this curve are available:
-    a Diversion Curve (normally used for Divider nodes) that has captured flow be a function of the inlet's approach flow
-    a Rating Curve (normally used for Outlet links) that makes the captured flow be a function of water depth.
-
-Diversion curves are best suited for on-grade inlets and Rating curves for on-sag inlets.
-
- 
-
-Clicking the    button next to the curve’s name field will open a Curve Editor dialog.
-
-
- 
-Inlet Usage Editor
-
-The Inlet Usage Editor is used to place an Inlet Structure into a Street or open channel conduit. It is accessed by selecting a conduit into the Property Editor and then clicking the ellipsis button in its Inlets property. The following information is requested by the editor:
-
-     Inlet Structure
-Select the name of an inlet structure that was created with the Inlet Structure Editor (Section C.11) from the drop-down list. The list will contain only those inlets that are compatible with the conduit's cross-section (i.e., curb and gutter inlets for street sections or drop inlets for trapezoidal or rectangular channel sections). Selecting the blank first item will remove the inlet from the conduit.
-
-Capture Node
-Enter the name of the node that receives flow captured by the inlet. You can select the node by clicking it on the Study Area Map or by selecting it from the Project Browser.
-
-Number of Inlets
-The number of identical inlets placed in the conduit. For two-sided street conduits this number refers to pairs of inlets placed on each side of the street
-
-Percent Clogged
-The degree to which each inlet is clogged. For example, if a value of 40% is entered then the normal flow capture computed for the inlet is reduced by 40%.
-
-Flow Restriction
-The maximum flow (in the project's flow units) that can be captured by a single inlet. A value of 0 indicates that flow capture is unrestricted.
-
-Depression Height
-The height of any local gutter depression that exists over the length of the inlet (in feet or meters). A value of 0 indicates no local depression. This parameter is ignored for drop inlets.
-Depression Width
-The width of any local gutter depression in feet or meters. It should be at least as large as the width that the inlet extends out into the gutter. This value is ignored if the depression height is 0 or if a drop inlet is used.
-
-Inlet Placement
-Specifies whether the inlet is placed in an on-grade or on-sag location. Selecting AUTOMATIC has the program determine the placement based on the topography of the street layout.
-
-     Grated, curb opening and slotted drain inlets can only be used by Street conduits. Drop grates and drop curb inlets can only be used by open rectangular or trapezoidal channels. Custom inlets can be used in any conduit.
- 
-Land Use Assignment Editor
-
-The Land Use Assignment editor is invoked from the Property Editor when editing the Land Uses property of a subcatchment. Its purpose is to assign land uses to the subcatchment for water quality simulations. The percent of land area in the subcatchment covered by each land use is entered next to its respective land use category. If the land use is not present its field can be left blank. The percentages entered do not necessarily have to add up to 100.
-
- 
- 
-
- 
-Land Use Editor
-
-The Land Use Editor dialog is used to define a category of land use for the study area and to define its pollutant buildup and washoff characteristics.
-
- 
-
-The dialog contains three tabbed pages of land use properties:
-    General Page (provides land use name and street sweeping parameters)
-    Buildup Page (defines rate at which pollutant buildup occurs)
-    Washoff Page (defines rate at which pollutant washoff occurs)
-
-General Page
-
-The General page of the Land Use Editor dialog describes the following properties of a particular land use category:
-
-Land Use Name
-The name assigned to the land use.
-
-
-
-Description
-An optional comment or description of the land use (click the ellipsis button or press Enter to edit).
-
-Street Sweeping Interval
-Days between street sweeping within the land use (0 for no sweeping).
-
-Street Sweeping Availability
-Fraction of the buildup of all pollutants that is available for removal by sweeping.
-
-Last Swept
-Number of days since last swept at the start of the simulation.
-
-If street sweeping does not apply to the land use, then the last three properties can be left blank.
-
-Buildup Page
-
- 
-
-The Buildup page of the Land Use Editor dialog describes the properties associated with pollutant buildup over the land during dry weather periods. These consist of:
-
-Pollutant
-Select the pollutant whose buildup properties are being edited.
-
-Function
-The type of buildup function to use for the pollutant. The choices are NONE for no buildup, POW for power function buildup, EXP for exponential function buildup SAT for saturation function buildup, and EXT for buildup supplied by an external time series. See the discussion of Pollutant Buildup in Section 3.3.11 for explanations of these different functions. Select NONE if no buildup occurs.
-
-Max. Buildup
-The maximum buildup that can occur, expressed as lbs (or kg) of the pollutant per unit of the normalizer variable (see below). This is the same as the C1 coefficient used in the buildup formulas discussed in Section 3.3.11.
-
-The following two properties apply to the POW, EXP, and SAT buildup functions:
-Rate Constant
-The time constant that governs the rate of pollutant buildup. This is the C2 coefficient in the Power and Exponential buildup formulas discussed in Section 3.3.11. For Power buildup its units are mass/days raised to a power, while for Exponential buildup its units are 1/days.
-Power/Sat. Constant
-The exponent C3 used in the Power buildup formula, or the half-saturation constant C2 used in the Saturation buildup formula discussed in Section 3.3.11. For the latter case, its units are days.
-
-The following two properties apply to the EXT (External Time Series) option:
-Scaling Factor
-A multiplier used to adjust the buildup rates listed in the time series.
-Time Series
-The name of the Time Series that contains buildup rates (as mass per normalizer per day).
-
-Normalizer
-The variable to which buildup is normalized on a per unit basis. The choices are either land area (in acres or hectares) or curb length. Any units of measure can be used for curb length, as long as they remain the same for all subcatchments in the project.
-
-When there are multiple pollutants, each pollutant must be selected separately from the Pollutant dropdown list and have its pertinent buildup properties specified.
-
-Washoff Page
-
- 
-
-The Washoff page of the Land Use Editor dialog describes the properties associated with pollutant washoff over the land use during wet weather events. These consist of:
-
-Pollutant
-The name of the pollutant whose washoff properties are being edited.
-
-Function
-The choice of washoff function to use for the pollutant. The choices are:
-    NONE    no washoff
-    EXP    exponential washoff
-    RC        rating curve washoff
-    EMC    event-mean concentration washoff.
-The formula for each of these functions is discussed in Section 3.3.11 (Land Uses) under the Pollutant Washoff topic.
-
-Coefficient
-This is the value of C1 in the exponential and rating curve formulas, or the event-mean concentration.
-Exponent
-The exponent used in the exponential and rating curve washoff formulas.
-
-Cleaning Efficiency
-The street cleaning removal efficiency (percent) for the pollutant. It represents the fraction of the amount that is available for removal on the land use as a whole (set on the General page of the editor) which is actually removed.
-
-BMP Efficiency
-Removal efficiency (percent) associated with any Best Management Practice that might have been implemented (but is not explicitly represented in the model). The washoff load computed at each time step is simply reduced by this amount.
-
-As with the Buildup page, each pollutant must be selected in turn from the Pollutant dropdown list and have its pertinent washoff properties defined. 
- 
-LID Control Editor
-
-The LID Control Editor is used to define a low impact development control that can be deployed throughout a study area to store, infiltrate, and evaporate subcatchment runoff. The design of the control is made on a per-unit-area basis so that it can be placed in any number of subcatchments at different sizes or number of replicates.
-
- 
-
-The editor contains the following data entry fields:
-
-Control Name
-A name used to identify the particular LID control.
-
-LID Type
-The generic type of LID being defined (bio-retention cell, rain garden, green roof, infiltration trench, permeable pavement, rain barrel, or vegetative swale).
-
-Process Layers
-These are a tabbed set of pages containing data entry fields for the vertical layers and drain system that comprise an LID control. They include some combination of the following, depending on the type of LID selected: Surface Layer, Pavement Layer, Soil Layer, Storage Layer, and Drain System or Drainage Mat.
-Surface Layer Properties
-
-The Surface Layer page of the LID Control Editor is used to describe the surface properties of all types of LID controls except rain barrels. Surface layer properties include:
-
-Berm Height (or Storage Depth)
-When confining walls or berms are present this is the maximum depth to which water can pond above the surface of the unit before overflow occurs (in inches or mm). For Rooftop Disconnection it is the roof’s depression storage depth, and for Vegetative Swales it is the height of the trapezoidal cross-section.
-
-Vegetative Volume Fraction
-The fraction of the volume within the storage depth filled with vegetation. This is the volume occupied by stems and leaves, not their surface area coverage. Normally this volume can be ignored, but may be as high as 0.1 to 0.2 for very dense vegetative growth.
-
-Surface Roughness
-Manning's roughness coefficient (n) for overland flow over surface soil cover, pavement, roof surface or vegetative swale. Use 0 for other types of LIDs.
-
-Surface Slope
-Slope of a roof surface, pavement surface or vegetative swale (percent). Use 0 for other types of LIDs. 
-
-Swale Side Slope
-Slope (run over rise) of the side walls of a vegetative swale's cross-section. This value is ignored for other types of LIDs.
-
-     If either Surface Roughness or Surface Slope values are 0 then any ponded water that exceeds the surface storage depth is assumed to completely overflow the LID control within a single time step.
-
-Pavement Layer Properties
-
-The Pavement Layer page of the LID Control Editor supplies values for the following properties of a permeable pavement LID:
-
-
-
-Thickness
-The thickness of the pavement layer (inches or mm). Typical values are 4 to 6 inches (100 to 150 mm).
-
-Void Ratio
-The volume of void space relative to the volume of solids in the pavement for continuous systems or for the fill material used in modular systems. Typical values for pavements are 0.12 to 0.21. Note that porosity = void ratio / (1 + void ratio).
-
-Impervious Surface Fraction
-Ratio of impervious paver material to total area for modular systems; 0 for continuous porous pavement systems.
-
-Permeability
-Permeability of the concrete or asphalt used in continuous systems or hydraulic conductivity of the fill material (gravel or sand) used in modular systems (in/hr or mm/hr). In the latter case the fill's nominal conductivity should be multiplied by the fraction of the total area it covers. The permeability of new porous concrete or asphalt is very high (e.g., hundreds of in/hr) but can drop off over time due to clogging by fine particulates in the runoff (see below).
-
-Clogging Factor
-Number of pavement layer void volumes of runoff treated it takes to completely clog the pavement. Use a value of 0 to ignore clogging. Clogging progressively reduces the pavement's permeability in direct proportion to the cumulative volume of runoff treated.
-
-If one has an estimate of the number of years it takes to fully clog the system (Yclog), the Clogging Factor can be computed as: Yclog * Pa * CR * (1 + VR) * (1 - ISF) / (T * VR) where Pa is the annual rainfall amount over the site, CR is the pavement's capture ratio (area that contributes runoff to the pavement divided by area of the pavement itself), VR is the system's Void Ratio, ISF is the Impervious Surface Fraction, and T is the pavement layer Thickness.
-
-As an example, suppose it takes 5 years to clog a continuous porous pavement system that serves an area where the annual rainfall is 36 inches/year. If the pavement is 6 inches thick, has a void ratio of 0.2 and captures runoff only from its own surface, then the Clogging Factor is 5 x 36 x (1 + 0.2) / 6 / 0.2 = 180.
-
-Regeneration Interval
-The number of days that the pavement layer is allowed to clog before its permeability is restored, typically by vacuuming its surface. A value of 0 (the default) indicates that no permeability regeneration occurs.
-Regeneration Fraction
-The fractional degree to which the pavement's permeability is restored when a regeneration interval is reached. The default is 0 (no restoration) while a value of 1 indicates complete restoration to the original permeability value. Once a regeneration occurs the pavement begins to clog once again at a rate determined by the Clogging Factor.
-
-Soil Layer properties
-
-The Soil Layer page of the LID Control Editor describes the properties of the engineered soil mixture used in bio-retention types of LIDs and the optional sand layer beneath permeable pavement. These properties are:
-
-Thickness
-The thickness of the soil layer (inches or mm). Typical values range from 18 to 36 inches (450 to 900 mm) for rain gardens, street planters and other types of land-based bio-retention units, but only 3 to 6 inches (75 to 150 mm) for green roofs.
-
-Porosity
-The volume of pore space relative to total volume of soil (as a fraction).
-
-Field Capacity
-Volume of pore water relative to total volume after the soil has been allowed to drain fully. Below this level, vertical drainage of water through the soil layer does not occur.
-
-Wilting Point
-Volume of pore water relative to total volume for a well dried soil where only bound water remains. The moisture content of the soil cannot fall below this limit.
-
-Conductivity
-Hydraulic conductivity for the fully saturated soil (in/hr or mm/hr).
-
-Conductivity Slope
-Average slope of the curve of log(conductivity) versus soil moisture deficit (porosity minus moisture content) (unitless). Typical values range from 30 to 60. It can be estimated from a standard soil grain size analysis as 0.48(%Sand) + 0.85(%Clay).
-
-Suction Head
-The average value of soil capillary suction along the wetting front (inches or mm). This is the same parameter as used in the Green-Ampt infiltration model. 
-
-     Porosity, field capacity, conductivity and conductivity slope are the same soil properties used for Aquifer objects when modeling groundwater, while suction head is the same parameter used for Green-Ampt infiltration. Except here they apply to the special soil mixture used in a LID unit rather than the site's naturally occurring soil. See Appendix A.2 for typical values of these properties.
-
-Storage Layer Properties
-
-The Storage Layer page of the LID Control Editor describes the properties of the crushed stone or gravel layer used in bio-retention cells, permeable pavement systems, and infiltration trenches as a bottom storage/drainage layer. It is also used to specify the height of a rain barrel (or cistern). The following data fields are displayed:
-
-Thickness (or Barrel Height)
-This is the thickness of a gravel layer or the height of a rain barrel (inches or mm). Crushed stone and gravel layers are typically 6 to 18 inches (150 to 450 mm) thick while single family home rain barrels range in height from 24 to 36 inches (600 to 900 mm).
-
-The following data fields do not apply to Rain Barrels.
-
-Void Ratio
-The volume of void space relative to the volume of solids in the layer. Typical values range from 0.5 to 0.75 for gravel beds. Note that porosity = void ratio / (1 + void ratio).
-
-Seepage Rate
-The rate at which water seeps into the native soil below the layer (in inches/hour or mm/hour). This would typically be the Saturated Hydraulic Conductivity of the surrounding subcatchment if Green-Ampt infiltration is used or the Minimum Infiltration Rate for Horton infiltration. If there is an impermeable floor or liner below the layer then use a value of 0.
-
-Clogging Factor
-Total volume of treated runoff it takes to completely clog the bottom of the layer divided by the void volume of the layer. Use a value of 0 to ignore clogging. Clogging progressively reduces the Infiltration Rate in direct proportion to the cumulative volume of runoff treated and may only be of concern for infiltration trenches with permeable bottoms and no under drains. 
-
-The following data field applies only to Rain Barrels.
-
-
-Covered
-Specifies if the rain barrel is covered or not.  A covered rain barrel receives no direct rainfall.
-
-Storage Drain Properties
-
-LID storage layers can contain an optional drainage system that collects water entering the layer and conveys it to a conventional storm drain or other location (which can be different than the outlet of the LID's subcatchment). Drain flow can also be returned to the pervious area of the LID's subcatchment. The drain can be offset some distance above the bottom of the storage layer, to allow some volume of runoff to be stored (and eventually infiltrated) before any excess is captured by the drain. For Rooftop Disconnection, the drain system consists of the roof’s gutters and downspouts that have some maximum conveyance capacity.
-
-The Drain page of the LID Control Editor describes the properties of this system. It contains the following data entry fields:
-
-Drain Flow Coefficient and Drain Flow Exponent
-The drain coefficient C and exponent n determines the rate of flow through a drain as a function of the height of stored water above the drain’s offset. The following equation is used to compute this flow rate (per unit area of the LID unit):
-q=Ch^n
-where q is outflow (in/hr or mm/hr) and h is the height of saturated media above the drain (inches or mm). A typical value for n would be 0.5 (making the drain act like an orifice). Note that the units of C depend on the unit system being used as well as the value assigned to n.  If the layer has no drain then set C  to 0.
-
-A typical value for n would be 0.5 (making the drain act like an orifice). Note that the units of C depend on the unit system being used as well as the value assigned to n.
-
-Drain Offset Height
-This is the height of the drain line above the bottom of a storage layer or rain barrel (inches or mm).
-
-Drain Delay (for Rain Barrels only)
-The number of dry weather hours that must elapse before the drain line in a rain barrel is opened (the line is assumed to be closed once rainfall begins). A value of 0 signifies that the barrel's drain line is always open and drains continuously. This parameter is ignored for other types of LIDs.
-
-Flow Capacity (for Rooftop Disconnection only)
-This is the maximum flow rate that the roof's gutters and downspouts can handle (in inches/hour or mm/hour) before overflowing. This is the only drain parameter used for Rooftop Disconnection.
-
-Open Level
-The height (in inches or mm) in the drain's Storage Layer that causes the drain to automatically open when the water level rises above it. The default is 0 which means that this feature is disabled.
-
-Closed Level
-The height (in inches or mm) in the drain's Storage Layer that causes the drain to automatically close when the water level falls below it. The default is 0.
-
-Control Curve
-The name of an optional Control Curve that adjusts the computed drain flow as a function of the head of water above the drain. Leave blank if not applicable.
-
-There are several things to keep in mind when specifying the parameters of an LID's underdrain:
-    If the storage layer that contains the drain has an impermeable bottom then it's best to place the drain at the bottom with a zero offset. Otherwise, to allow the full storage volume to fill before draining occurs, one would place the drain at the top of the storage layer.
-    If the storage layer has no drain then set the drain coefficient to 0.
-    If the drain can carry whatever flow enters the storage layer up to some specific limit then set the drain coefficient to the limit and the drain exponent to 0.
-    If the underdrain consists of slotted pipes where the slots act as orifices, then the drain exponent would be 0.5 and the drain coefficient would be 60,000 times the ratio of total slot area to LID area. For example, drain pipe with five 1/4" diameter holes per foot spaced 50 feet apart would have an area ratio of 0.000035 and a drain coefficient of 2.
-    If the goal is to drain a fully saturated unit in a specific amount of time then set the drain exponent to 0.5 (to represent orifice flow) and the drain coefficient to 2D1/2/T where D is the distance from the drain to the surface plus any berm height (in inches or mm) and T is the time in hours to drain. For example, to drain a depth of 36 inches in 12 hours requires a drain coefficient of 1. If this drain consisted of the slotted pipes described in the previous bullet, whose coefficient was 2, then a flow regulator, such as a cap orifice, would have to be placed on the drain outlet to achieve the reduced flow rate.
-
-
-Drainage Mat Properties
-
-Green Roofs usually contain a drainage mat or plate that lies below the soil media and above the roof structure. Its purpose is to convey any water that drains through the soil layer off of the roof. The Drainage Mat page of the LID Control Editor for Green Roofs lists the properties of this layer which include:
-
-Thickness
-The thickness of the mat or plate (inches or mm). It typically ranges between 1 to 2 inches.
-
-Void Fraction
-The ratio of void volume to total volume in the mat. It typically ranges from 0.5 to 0.6.
-
-Roughness
-This is the Manning's roughness coefficient (n) used to compute the horizontal flow rate of drained water through the mat. It is not a standard product specification provided by manufacturers and therefore must be estimated. Previous modeling studies have suggested using a relatively high value such as from 0.1 to 0.4.
-
-LID Pollutant Removal
-
-The Pollutant Removal page of the LID Control Editor allows one to specify the degree to which pollutants are removed by an LID control as seen by the flow leaving the unit through its underdrain system. Thus it only applies to LID practices that contain an underdrain (bio-retention cells,permeable pavement, infiltration trenches, and rain barrels).
-
-The page contains a data entry grid with the project's pollutant names listed in one column and the percent removal that each receives by the LID unit in the second editable column. If a percent removal value is left blank it is assumed to be 0.
-
-The removals specified on this page are applied to the unit's underdrain when it sends flow onto either a subcatchment or into a conveyance system node. They do not apply to any surface flow that leaves the LID unit. As an example, if the runoff treated by the LID unit had a TSS concentration of 100 mg/L and a removal percentage of 90, then if 5 cfs flowed from its drain into a conveyance system node the mass loading contribution to the node would be 100 x (1.0 – 0.9) x 5 x 28.3 L/ft3 = 1,415 mg/sec. If in addition the unit had a surface outflow of 1 cfs into the same node, the mass loading from this flow stream would be 100 x 1 x 28.3 = 2,830 mg/sec.
- 
-LID Group Editor
-
-The LID Group Editor is invoked when the LID Controls property of a Subcatchment is selected for editing. It is used to identify a group of previously defined LID controls that will be placed within the subcatchment, the sizing of each control, and what percent of runoff from the non-LID portion of the subcatchment each should treat.
-
- 
-
-The editor displays the current group of LIDs placed in the subcatchment along with buttons for adding an LID unit, editing a selected unit, and deleting a selected unit. These actions can also be chosen by hitting the Insert key, the Enter key, and the Delete key, respectively. Selecting Add or Edit will bring up an LID Usage Editor where one can enter values for the data fields shown in the Group Editor.
-
-Note that the total % of Area for all of the LID units within a subcatchment must not exceed 100%. The same applies to % From Impervious and % From Pervious. Refer to the LID Usage Editor for the meaning of these parameters.
-
-
-
-
-
-
-
-
-
-
-
-
-LID Usage Editor
-
-The LID Usage Editor is invoked from a subcatchment's LID Group Editor to specify how a particular LID control will be deployed within the subcatchment. It contains the following data entry fields:
-
- 
-
-Control Name
-The name of a previously defined LID control to be used in the subcatchment.
-
-LID Occupies Full Subcatchment
-Select this checkbox option if the LID control occupies the full subcatchment (i.e., the LID is placed in its own separate subcatchment and accepts runoff from upstream subcatchments).
-
-Area of Each Unit
-The surface area devoted to each replicate LID unit (sq. ft or sq. m). If the LID Occupies Full Subcatchment box is checked, then this field becomes disabled and will display the total subcatchment area divided by the number of replicate units.  (See Section 3.3.16 for options on placing LIDs within subcatchments.) The label below this field indicates how much of the total subcatchment area is devoted to the particular LID being deployed and gets updated as changes are made to the number of units and area of each unit.
-
-Number of Replicate Units
-The number of equal size units of the LID practice (e.g., the number of rain barrels) deployed within the subcatchment.
-
-Surface Width Per Unit
-The width of the outflow face of each identical LID unit (in ft or m). This parameter applies to roofs, pavement, trenches, and swales that use overland flow to convey surface runoff off of the unit. It can be set to 0 for other LID processes, such as bio-retention cells, rain gardens, and rain barrels that simply spill any excess captured runoff over their berms.
-
-% Initially Saturated
-For LID units with a soil layer this is the degree to which the layer is initially filled with water (0 % saturation corresponds to the wilting point moisture content, 100 % saturation has the moisture content equal to the porosity). For units with a storage layer it corresponds to the initial depth of water in the layer.
-
-% of Impervious Area Treated
-The percent of the impervious portion of the subcatchment's non-LID area whose runoff is treated by the LID practice. (E.g., if rain barrels are used to capture roof runoff and roofs represent 60% of the impervious area, then the impervious area treated is 60%). If the LID unit treats only direct rainfall, such as with a green roof or roof disconnection, then this value should be 0. If the LID unit takes up the entire subcatchment then this field is ignored.
-
-% of Pervious Area Treated
-The percent of the pervious portion of the subcatchment's non-LID area whose runoff is treated by the LID practice. If the LID unit treats only direct rainfall, such as with a green roof or roof disconnection, then this value should be 0. If the LID unit takes up the entire subcatchment then this field is ignored.
-
-Send Drain Flow To
-Provide the name of the Node or Subcatchment that receives any drain flow produced by the LID unit. This field can be left blank if this flow goes to the same outlet as the LID unit’s subcatchment. 
-
-Return All Outflow to Pervious Area
-Select this option if outflow from the LID unit should be routed back onto the pervious area of the subcatchment that contains it. If drain outflow was selected to be routed to a different location than the subcatchment outlet then only surface outflow will be returned. Otherwise both surface and drain flow will be returned. Selecting this option would be a common choice to make for Rain Barrels, Rooftop Disconnection and possibly Green Roofs. 
-Detailed Report File
-The name of an optional file where detailed time series results for the LID will be written. Click the browse button    to select a file using the standard Windows File Save dialog or click the delete button    to remove any detailed reporting. The detailed report file will be a tab delimited text file that can be easily opened and viewed with any text editor or spreadsheet program (such as Microsoft Excel) outside of SWMM.
-
-     If the subcatchment containing the LID internally routes some portion of the impervious area runoff onto the pervious area then the percent of impervious area treated by the LID unit refers to the remaining impervious area that is not internally routed. For example, if the subcatchment has 2 acres of impervious area with runoff from 50% of this area routed onto its pervious area then an LID unit which treats 20% of the impervious area would receive runoff from 0.2 acres of impervious area. This same convention applies to the percent of pervious area treated when there is internal routing from pervious to impervious areas.
-
- 
-Pollutant Editor
-
-The Pollutant Editor is invoked when a new pollutant object is created or an existing pollutant is selected for editing. It contains the following fields:
-
- 
-
-Name
-The name assigned to the pollutant.
-
-Units
-The concentration units (mg/L, ug/L, or #/L (counts/L)) in which the pollutant concentration is expressed.
-
-Rain Concentration
-Concentration of the pollutant in rain water (concentration units).
-
-GW Concentration
-Concentration of the pollutant in ground water (concentration units).
-
-Initial Concentration
-Concentration of the pollutant throughout the conveyance system at the start of the simulation.
-
-I&I Concentration
-Concentration of the pollutant in any rainfall-dependent infiltration and inflow (concentration units).
-
-DWF Concentration
-Concentration of the pollutant in any dry weather sanitary flow (concentration units). This value can be overridden for any specific node of the conveyance system by editing the node's Inflows property.
-
-Decay Coefficient
-First-order decay coefficient of the pollutant (1/days).
-
-Snow Only
-YES if pollutant buildup occurs only when there is snow cover, NO otherwise (default is NO).
-
-Co-Pollutant
-Name of another pollutant whose runoff concentration contributes to the runoff concentration of the current pollutant.
-
-Co-Fraction
-Fraction of the co-pollutant's runoff concentration that contributes to the runoff concentration of the current pollutant.
-
-An example of a co-pollutant relationship would be where the runoff concentration of a particular heavy metal is some fixed fraction of the runoff concentration of suspended solids. In this case suspended solids would be declared as the co-pollutant for the heavy metal.
-
-
-
-
-
-
-
- 
-Snow Pack Editor
-
-The Snow Pack Editor is invoked when a new snow pack object is created or an existing snow pack is selected for editing. The editor contains a data entry field for the snow pack’s name and two tabbed pages, one for snow pack parameters and one for snow removal parameters.
-
- 
-
-Snow Pack Parameters Page
-
-The Parameters page of the Snow Pack Editor dialog provides snow melt parameters and initial conditions for snow that accumulates over three different types of areas: the impervious area that is plowable (i.e., subject to snow removal), the remaining impervious area, and the entire pervious area. The page contains a data entry grid which has a column for each type of area and a row for each of the following parameters:
-
-
-
-Minimum Melt Coefficient
-The degree-day snow melt coefficient that occurs on December 21. Units are either in/hr-deg F or mm/hr-deg C.
-
-Maximum Melt Coefficient
-The degree-day snow melt coefficient that occurs on June 21. Units are either in/hr-deg F or mm/hr-deg C. For a short term simulation of less than a week or so it is acceptable to use a single value for both the minimum and maximum melt coefficients.
-
-The minimum and maximum snow melt coefficients are used to estimate a melt coefficient that varies by day of the year. The latter is used in the following degree-day equation to compute the melt rate for any particular day:
-    Melt Rate = (Melt Coefficient) * (Air Temperature – Base Temperature).
-
-Base Temperature
-Temperature at which snow begins to melt (degrees F or C).
-
-Fraction Free Water Capacity
-The volume of a snow pack's pore space which must fill with melted snow before liquid runoff from the pack begins, expressed as a fraction of snow pack depth.
-
-Initial Snow Depth
-Depth of snow at the start of the simulation (water equivalent depth in inches or millimeters).
-
-Initial Free Water
-Depth of melted water held within the pack at the start of the simulation (inches or mm). This number should be at or below the product of the initial snow depth and the fraction free water capacity.
-
-Depth at 100% Cover
-The depth of snow beyond which the entire area remains completely covered and is not subject to any areal depletion effect (inches or mm).
-
-Fraction of Impervious Area That is Plowable
-The fraction of impervious area that is plowable and therefore is not subject to areal depletion.
-
-
-
-
-
-Snow Removal Parameters Page
-
- 
-
-The Snow Removal page of the Snow Pack Editor describes how snow removal occurs within the Plowable area of a snow pack. The following parameters govern this process:
-
-Depth at which snow removal begins (in or mm)
-Depth which must be reached before any snow removal begins.
-
-Fraction transferred out of the watershed
-The fraction of snow depth that is removed from the system (and does not become runoff).
-
-Fraction transferred to the impervious area
-The fraction of snow depth that is added to snow accumulation on the pack's impervious area.
-
-Fraction transferred to the pervious area
-The fraction of snow depth that is added to snow accumulation on the pack's pervious area.
-Fraction converted to immediate melt
-The fraction of snow depth that becomes liquid water which runs onto any subcatchment associated with the snow pack.
-
-Fraction moved to another subcatchment
-The fraction of snow depth which is added to the snow accumulation on some other subcatchment. The name of the subcatchment must also be provided.
-
-The various removal fractions must add up to 1.0 or less. If less than 1.0, then some remaining fraction of snow depth will be left on the surface after all of the redistribution options are satisfied.
- 
-Storage Shape Editor
-
-The Storage Shape Editor is used to describe how a storage unit's surface area varies with depth above the bottom of the unit. It is invoked when the Storage Shape property of a storage node is selected for editing (see Section B.6).There are six types of shapes one can choose from: 
-
- 
-
-
-Cylindrical
-The storage unit has vertical sides and an elliptical base. The equation for surface area A is:
-        A=(π⁄4)LW
-where L = base major axis length and W = base minor axis width. If only the surface area is known then one can use the Functional storage option instead.
-
-
-Conical
-The storage unit is shaped as a truncated elliptical cone. The equation for surface area A as a function of water depth D is:
-A=π[L(W⁄4)+WZD+(W⁄L) 〖(ZD)〗^2 ]
-where L = base major axis length, W = base minor axis width and Z = side slope (run / rise) of a vertical slice through the major axis.
-
-Parabolic
-The storage unit has the shape of an elliptical paraboloid. The equation for surface area A as a function of water depth D is:
-A=(π⁄4)L(W⁄H)D
- where L = major axis length at height H and W = minor axis width at height H. This shape can also be described using the Functional storage option. 
-
-Pyramidal
-This is for storage units shaped as a truncated rectangular pyramid or a rectangular box. The equation for surface area A as a function of water depth D is: 
-A=LW+2(L+W)ZD+〖(2ZD)〗^2
-where L = base length, W = base width and Z = side slope (run / rise) (which would be 0 for a box). 
-
-Functional
-The following general function is used to relate surface area A to water depth D:
-A=a0+a1D^a2
-Where a0, a1, and a2 are user supplied coefficients. The coefficient values for some particular types of shapes are as follows:
-    Shapes with vertical sides (such as a cylinder or rectangular prism):
-    a0 = area of the base
-    a1 = a2 = 0
-    Open channel with a trapezoidal cross-section and vertical ends (i.e., a trapezoidal prism):
-    a0=WL
-    a1=2ZL
-    a2=1
-where W = bottom width of cross-section, L = channel length, and Z = side slope.
-
-
-    Open channel with a parabolic cross-section and vertical ends:
-    a0 = 0
-    a1=WLH^0.5
-    a2 = 1
-where W = top width, L = channel length and H = full height.
-    Elliptical paraboloid:
-    a0 = 0
-    a1=πL W⁄H
-    a2 = 1
-where L is the length of the major axis and W the length of the minor axis at full height H.
-    Circular non-truncated cone:
-    a0 = 0
-    a1=(π⁄4) (W⁄H)^2
-    a2 = 2
-where W is the cone's diameter at height H.
-
-Tabular
-This option uses a tabular Storage Curve to relate surface area to depth. It can represent natural depressions with irregular shaped contour intervals, spheroid storage vessels or conventional shapes with different base sizes stacked on top of one another. The first point supplied to the curve should be the surface area of the unit's base at a depth of 0. Otherwise it will be assumed that the unit has zero surface area at its base. The curve will be extrapolated outwards to meet the unit's maximum depth if need be.
-
-For each of these options, depth is measured in feet and surface area in square feet for US units, while meters and square meters, respectively, are used for SI units.
-
-Clicking the Show Volume Calculator label will display a panel where one can see what the surface area and stored volume will be for a specified water depth for the currently selected storage shape.
- 
-Street Section Editor
-
-The Street Section Editor is used to define the dimensions of a street or roadway cross-section. It is invoked when a new Street object is created or an existing one is selected for editing.
-
- 
-
-The editor asks that the following dimensions be provided for the portion of the street extending from the high point of the roadway to the curb and beyond to any backing that might exist:
-
-Street Section Name
-The name assigned to the street cross-section. Conduits with a STREET shape cross-section will refer to this name to identify its cross-section dimensions.
-
-Road Width (Tcrown)
-The distance from the curb to the high point of the street roadway (i.e., the street crown) (feet or meters). Traffic lanes are typically 10 to 12 feet (3.3 to 3.7 meters) wide with gutters being 1 to 3 feet (0.3 to 1 meter) wide.
-
-Curb Height (Hcurb)
-The height of the curb with respect to the street's cross slope (feet or meters). Typical heights are 0.33 to 0.67 feet (0.1 to 0.2 meters) with 0.5 feet (0.15 meters) being standard in the U.S.
-
-Cross Slope (Sx)
-The slope of the roadway portion of the cross-section (percent). Cross slopes range between 1 to 4 percent with 2 percent being a common value.
-
-Road Roughness
-Manning's roughness coefficient (n) for the road surface. Typical values range from 0.013 to 0.017.
-
-One or Two Sided
-Select One Sided if the street section extends only to the street crown or Two Sided if the same street section shape exists on the opposite side of the street crown.
-
-Gutter Depression (a)
-The distance that the gutter portion of the street is depressed below where the cross slope of the roadway would intersect the curb (feet or meters). Depressed gutter sections increase the conveyance capacity of a street. A typical value would be 0.17 feet (2 inches or 0.05 meters). Conventional gutters maintain the same slope as the roadway and would therefore have a 0 depression depth.
-
-Gutter Width (W)
-The width between the curb and the roadway for a depressed gutter (feet or meters). A typical value would be 2 feet (0.6 meters). For conventional gutters with no depression depth use a value of 0.
-
-Backing Width (Tback)
-The width of the area that the street backs up against (such as a sidewalk or lawn area) (feet or meters). Enter 0 if there is no backing.
-
-Backing Slope (Sback)
-The slope of the backing area (percent). If the backing width is non-zero then this must be a positive number. Otherwise it is ignored.
-Backing Roughness
-Manning's roughness coefficient (n) for the backing's surface. This parameter is ignored if the backing width is 0.
- 
-Time Pattern Editor
-
-The Time Pattern Editor is invoked when a new time pattern object is created or an existing time pattern is selected for editing.
-
- 
-
-The editor contains that following data entry fields:
-
-Name
-The name assigned to the time pattern.
-
-Type
-The type of time pattern being specified. The choices are Monthly, Daily, Hourly and Weekend Hourly.
-
-Description
-Provide an optional comment or description for the time pattern. If more than one line is needed, click the   button to launch a multi-line comment editor.
-
-Multipliers
-Enter a value for each multiplier. The number and meaning of the multipliers changes with the type of time pattern selected:
-
-    MONTHLY        One multiplier for each month of the year.
-    DAILY            One multiplier for each day of the week.
-    HOURLY        One multiplier for each hour from 12 midnight to 11 PM.
-    WEEKEND        Same as for HOURLY except applied to weekend days.
-
-     In order to maintain an average dry weather flow or pollutant concentration at its specified value (as entered on the Inflows Editor), the multipliers for a pattern should average to 1.0.
-
- 
-Time Series Editor
-
-The Time Series Editor is invoked whenever a new time series object is created or an existing time series is selected for editing. 
-
- 
-
-To use the Time Series Editor:
-
-    Enter values for the following standard items:
-Name    Name of the time series.
-Description    Optional comment or description of what the time series represents. Click the   button to launch a multi-line comment editor if more than one line is needed. 
-    Select whether to use an external file as the source of the data or to enter the data directly into the form's data entry grid.
-    If the external file option is selected, click the   button to locate the file's name. The file's contents must be formatted in the same manner as the direct data entry option discussed below. See the description of Time Series Files in Section 11.6 for details.
-    For direct data entry, enter values in the data entry grid as follows:
-Date Column    Optional date (in month/day/year format) of the time series values (only needed at points in time where a new date occurs). 
-Time Column    If dates are used, enter the military time of day for each time series value (as hours:minutes or decimal hours). If dates are not used, enter time as hours since the start of the simulation.
-Value Column    The time series’ numerical values.
-A graphical plot of the data in the grid can be viewed in a separate window by clicking the View button. Right clicking over the grid will make a popup Edit menu appear. It contains commands to cut, copy, insert, and paste selected cells in the grid as well as options to insert or delete a row.
-    Press OK to accept the time series or Cancel to cancel the edits.
-
-     Note that there are two methods for describing the occurrence time of time series data:
-    as calendar date/time of day (which requires that at least one date, at the start of the series,  be entered in the Date column)
-    as elapsed hours since the start of the simulation (where the Date column remains empty).
- 
-     For rainfall time series, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage which utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values.
-
- 
-Title/Notes Editor
-
-The Title/Notes editor is invoked when a project’s Title/Notes data category is selected for editing. As shown below, the editor contains a multi-line edit field where a description of a project can be entered. It also contains a check box used to indicate whether or not the first line of notes should be used as a header for printing.
-
- 
-
- 
-Transect Editor
-
-The Transect Editor is invoked when a new transect object is created or an existing transect is selected for editing. It contains the following data entry fields:
-
- 
-
-Name
-The name assigned to the transect.
-
-Description
-An optional comment or description of the transect.
-
-Station/Elevation Data Grid
-Values of distance from the left side of the channel along with the corresponding elevation of the channel bottom as one moves across the channel from left to right, looking in the downstream direction. Up to 1500 data values can be entered.
-
-
-
-Roughness
-Values of Manning's roughness coefficient (n) for the left overbank, right overbank, and main channel portion of the transect. The overbank roughness values can be zero if no overbank exists.
-
-Bank Stations
-The distance values appearing in the Station/Elevation grid that mark the end of the left overbank and the start of the right overbank. Use 0 to denote the absence of an overbank.
-
-Modifiers
-    The Stations modifier is a factor by which the distance between each station will be multiplied when the transect data is processed by SWMM. Use a value of 0 if no such factor is needed.
-    The Elevations modifier is a constant value that will be added to each elevation value.
-    The Meander modifier is the ratio of the length of a meandering main channel to the length of the overbank area that surrounds it. This modifier is applied to all conduits that use this particular transect for their cross-section. It assumes that the length supplied for these conduits is that of the longer main channel. SWMM will use the shorter overbank length in its calculations while increasing the main channel roughness to account for its longer length. The modifier is ignored if it is left blank or set to 0.
-
-Right-clicking over the Data Grid will make a popup Edit menu appear. It contains commands to cut, copy, insert, and paste selected cells in the grid as well as options to insert or delete a row. 
-
-Clicking the View button will bring up a window that illustrates the shape of the transect cross- section.
- 
-Treatment Editor
-
-The Treatment Editor is invoked whenever the Treatment property of a node is selected from the Property Editor. It displays a list of the project's pollutants with an edit box next to each as shown below. Enter a valid treatment expression in the box next to each pollutant which receives treatment.
-
- 
-
-A treatment function can be any well-formed mathematical expression involving:
-    the pollutant concentration (use the pollutant name to represent its concentration) – for non-storage nodes this is the mixture concentration of all flow streams entering the node while for storage nodes it is the pollutant concentration within the node’s stored volume
-    the removals of other pollutants (use R_ prefixed to the pollutant name to represent removal)
-    any of the following process variables:
-- FLOW for flow rate into node (in user-defined flow units)
-- DEPTH for water depth above node invert (ft or m)
-- AREA for node surface area (ft2 or m2)
-- DT for routing time step (sec)
-- HRT for hydraulic residence time (hours)
-Any of the following math functions (which are case insensitive) can be used in a treatment expression:
-•    abs(x) for absolute value of x
-•    sgn(x) which is +1 for x >= 0 or -1 otherwise
-•    step(x) which is 0 for x <= 0 and 1 otherwise
-•    sqrt(x) for the square root of x
-•    log(x) for logarithm base e of x
-•    log10(x) for logarithm base 10 of x
-•    exp(x) for e raised to the x power
-•    the standard trig functions (sin, cos, tan, and cot)
-•    the inverse trig functions (asin, acos, atan, and acot)
-•    the hyperbolic trig functions (sinh, cosh, tanh, and coth)
-along with the standard operators +, -, *, /, ^ (for exponentiation ) and any level of nested parentheses.
-
-     Care must be taken to avoid circular references when specifying treatment functions.  For example, the expression R = 0.75 * R_TSS would not be computable if it were used to compute fractional removal of TSS. 
- 
-Unit Hydrograph Editor
-
-The Unit Hydrograph Editor is invoked whenever a new unit hydrograph object is created or an existing one is selected for editing. It is used to specify the shape parameters and rain gage for a group of triangular unit hydrographs. These hydrographs are used to compute rainfall-dependent infiltration and inflow (RDII) flow at selected nodes of the drainage system.
-
- 
-
-A UH group can contain up to 12 sets of unit hydrographs (one for each month of the year), and each set can consist of up to 3 individual hydrographs (for short-term, intermediate-term, and long-term responses, respectively) as well as parameters that describe any initial abstraction losses. The editor contains the following data entry fields:
-
-Name of UH Group
-Enter the name assigned to the UH Group.
-
-
-
-Rain Gage Used
-Type in (or select from the dropdown list) the name of the rain gage that supplies rainfall data to the unit hydrographs in the group.
-
-Hydrographs For: 
-Select a month from the dropdown list box for which hydrograph parameters will be defined. Select All Months to specify a default set of hydrographs that apply to all months of the year. Then select specific months that need to have special hydrographs defined. Months listed with a (*) next to them have had hydrographs assigned to them. 
-
-Unit Hydrographs 
-Select this tab to provide the R-T-K shape parameters for each set of unit hydrographs in selected months of the year. The first row is used to specify parameters for a short-term response hydrograph (i.e., small value of T), the second for a medium-term response hydrograph, and the third for a long-term response hydrograph (largest value of T). It is not required that all three hydrographs be defined and the sum of the three R-values do not have to equal 1. The shape parameters for each UH consist of: 
-    R: the fraction of rainfall volume that enters the sewer system  
-    T: the time from the onset of rainfall to the peak of the UH in hours  
-    K: the ratio of time to recession of the UH to the time to peak  
- 
-Initial Abstraction Depth 
-Select this tab to provide parameters that describe how rainfall will be reduced by any initial abstraction depth available (i.e., interception and depression storage) before it is processed through the unit hydrographs defined for a specific month of the year. Different initial abstraction parameters can be assigned to each of the three unit hydrograph responses. These parameters are: 
-    Dmax: the maximum depth of initial abstraction available (in rain depth units)  
-    Drec: the rate at which any utilized initial abstraction is made available again (in rain depth units per day)  
-    Do: the amount of initial abstraction that has already been utilized at the start of the simulation (in rain depth units).  
-
-If a grid cell is left empty its corresponding parameter value is assumed to be 0. Right-clicking over a data entry grid will make a popup Edit menu appear. It contains commands to cut, copy, and paste text to or from selected cells in the grid.
-
-
-
diff --git a/docs/manuals/user/manual/AppendixD.md b/docs/manuals/user/manual/AppendixD.md
deleted file mode 100644
index c644790dd..000000000
--- a/docs/manuals/user/manual/AppendixD.md
+++ /dev/null
@@ -1,1849 +0,0 @@
-@page user_manual_appendix_d APPENDIX D - COMMAND LINE SWMM
-
-@tableofcontents
-
-## D.1 General Instructions
-
-EPA SWMM can also be run as a console application from the command line within a DOS window. In this case the study area data are placed into a text file and results are written to a text file. The command line for running SWMM in this fashion is:
-runswmm inpfile rptfile outfile
-where inpfile is the name of the input file, rptfile is the name of the output report file, and outfile is the name of an optional binary output file. The latter stores all time series results in a special binary format that will require a separate post-processor program for viewing. If no binary output file name is supplied then all time series results will appear in the report file. As written, the above command assumes that you are working in the directory in which EPA SWMM was installed or that this directory has been added to the PATH variable in your user profile. Otherwise full pathnames for the runswmm executable and the files on the command line must be used. 
-
-## D.2 Input File Format
-
-The input file for command line SWMM has the same format as the project file used by the Windows version of the program. Figure D-1 illustrates an example SWMM 5 input file. It is organized in sections, where each section begins with a keyword enclosed in brackets. The various section keywords are listed below.
-
-[TITLE]                project title
-[OPTIONS]            analysis options
-[REPORT]                output reporting instructions
-[FILES]                interface file options
-
-[RAINGAGES]        rain gage information
-[EVAPORATION]        evaporation data
-[TEMPERATURE]        air temperature and snow melt data
-[ADJUSTMENTS]        monthly adjustments applied to climate variables
-
-
-
-
-[SUBCATCHMENTS]    basic subcatchment information
-[SUBAREAS]            subcatchment impervious/pervious subarea data
-[INFILTRATION]    subcatchment infiltration parameters
-[LID_CONTROLS]    low impact development control information
-[LID_USAGE]        assignment of LID controls to subcatchments
-
-[AQUIFERS]            groundwater aquifer parameters
-[GROUNDWATER]        subcatchment groundwater parameters
-[GWF]                    groundwater flow expressions
-[SNOWPACKS]        subcatchment snow pack parameters
-
-[JUNCTIONS]        junction node information
-[OUTFALLS]            outfall node information
-[DIVIDERS]            flow divider node information
-[STORAGE]            storage node information
-
-[CONDUITS]            conduit link information
-[PUMPS]                pump link information
-[ORIFICES]            orifice link information
-[WEIRS]                weir link information
-[OUTLETS]            outlet link information
-
-[XSECTIONS]        conduit, orifice, and weir cross-section geometry
-[TRANSECTS]        transect geometry for conduits with irregular cross-sections
-[STREETS]            cross-section geometry for street conduits
-[INLETS]                design data for storm drain inlets
-[INLET_USAGE]        assignment of inlets to street and channel conduits
-[LOSSES]                conduit entrance/exit losses and flap valves
-[CONTROLS]            rules that control pump and regulator operation
-
-[POLLUTANTS]        pollutant information
-[LANDUSES]            land use categories
-[COVERAGES]        assignment of land uses to subcatchments
-[LOADINGS]            initial pollutant loads on subcatchments
-[BUILDUP]            buildup functions for pollutants and land uses
-[WASHOFF]            washoff functions for pollutants and land uses
-[TREATMENT]        pollutant removal functions at conveyance system nodes
-
-
-[INFLOWS]            external hydrograph/pollutograph inflow at nodes
-[DWF]                    baseline dry weather sanitary inflow at nodes
-[RDII]                rainfall-dependent I/I information at nodes
-[HYDROGRAPHS]        unit hydrograph data used to construct RDII inflows
-
-[CURVES]                x-y tabular data referenced in other sections
-[TIMESERIES]        time series data referenced in other sections
-[PATTERNS]            periodic multipliers referenced in other sections
-
-
- 
-*Figure D-1 Example SWMM project file*
-
-*Figure D-1 Example SWMM project file (continued from previous page).*
-
-
-
-
-
-
-Section keywords can appear in mixed lower and upper case. The sections can appear in any arbitrary order in the input file, and not all sections must be present. Each section can contain one or more lines of data. Blank lines may appear anywhere in the file. A semicolon (;) can be used to indicate that what follows on the line is a comment, not data. Data items can appear in any column of a line. Observe how in Figure D-1 these features were used to create a tabular appearance for the data, complete with column headings.
-
-An option is available in the [OPTIONS] section to choose flow units from among cubic feet per second (CFS), gallons per minute (GPM), million gallons per day (MGD), cubic meters per second (CMS), liters per second, (LPS), or million liters per day (MLD). If cubic feet or gallons are chosen for flow units, then US units must be used for all other quantities. If cubic meters or liters are chosen, then metric units must be used for all other quantities. Exceptions are pollutant concentration and Manning’s roughness coefficient (n) which are always expressed in metric units. The default flow units are CFS. Appendix A.1 provides a complete listing of measurement units.
-
-A detailed description of the data in each section of the input file will now be given. Each section description begins on a new page. When listing the format of a line of data, mandatory keywords are shown in boldface while optional items appear in parentheses. A list of keywords separated by a slash (YES/NO) means that only one of the words should appear in the data line.
- 
-### Section: [TITLE]
-
-Purpose:
-Attaches a descriptive title to the project being analyzed.
-
-Format:
-Any number of lines may be entered. The first line will be used as a page header in the output report.
-
- 
-### Section: [OPTIONS]
-
-Purpose:
-Provides values for various analysis options.
-
-Format:
-FLOW_UNITS                    CFS / GPM / MGD / CMS / LPS / MLD
-INFILTRATI0N                HORTON / MODIFIED_HORTON / GREEN_AMPT /
-MODIFIED_GREEN_AMPT / CURVE_NUMBER
-FLOW_ROUTING                STEADY / KINWAVE / DYNWAVE
-LINK_OFFSETS                DEPTH / ELEVATION
-FORCE_MAIN_EQUATION        H-W / D-W
-IGNORE_RAINFALL            YES / NO
-IGNORE_SNOWMELT            YES / NO
-IGNORE_GROUNDWATER        YES / NO
-IGNORE_RDII                YES / NO
-IGNORE_ROUTING            YES / NO
-IGNORE_QUALITY            YES / NO
-ALLOW_PONDING                YES / NO
-SKIP_STEADY_STATE        YES / NO
-SYS_FLOW_TOL                value
-LAT_FLOW_TOL                value
-START_DATE                    month/day/year
-START_TIME                    hours:minutes
-END_DATE                        month/day/year
-END_TIME                        hours:minutes
-REPORT_START_DATE        month/day/year
-REPORT_START_TIME        hours:minutes
-SWEEP_START                month/day
-SWEEP_END                    month/day
-DRY_DAYS                        days
-REPORT_STEP                hours:minutes:seconds
-WET_STEP                        hours:minutes:seconds
-DRY_STEP                        hours:minutes:seconds
-ROUTING_STEP                seconds
-LENGTHENING_STEP            seconds
-VARIABLE_STEP                value
-MINIMUM_STEP                seconds
-INERTIAL_DAMPING            NONE / PARTIAL / FULL
-NORMAL_FLOW_LIMITED        SLOPE / FROUDE / BOTH
-SURCHARGE_METHOD            EXTRAN / SLOT
-MIN_SURFAREA                value
-MIN_SLOPE                    value
-MAX_TRIALS                    value
-HEAD_TOLERANCE            value
-THREADS                        value
-
-Remarks:
-    FLOW_UNITS makes a choice of flow units. Selecting a US flow unit means that all other quantities will be expressed in US customary units, while choosing a metric flow unit will force all quantities to be expressed in SI metric units. (Exceptions are pollutant concentration and Manning’s roughness coefficient (n) which are always in metric units). The default is CFS.
-INFILTRATION selects a model for computing infiltration of rainfall into the upper soil zone of subcatchments. The default model is HORTON.
-FLOW_ROUTING determines which method is used to route flows through the drainage system. STEADY refers to sequential steady state routing (i.e. hydrograph translation), KINWAVE to kinematic wave routing, DYNWAVE to dynamic wave routing. The default routing method is DYNWAVE.
-LINK_OFFSETS determines the convention used to specify the position of a link offset above the invert of its connecting node. DEPTH indicates that offsets are expressed as the distance between the node invert and the link while ELEVATION indicates that the absolute elevation of the offset is used. The default is DEPTH.
-
-FORCE_MAIN_EQUATION establishes whether the Hazen-Williams (H-W) or the Darcy-Weisbach (D-W) equation will be used to compute friction losses for pressurized flow in conduits that have been assigned a Circular Force Main cross-section shape. The default is H-W.
-IGNORE_RAINFALL is set to YES if all rainfall data and runoff calculations should be ignored. In this case SWMM only performs flow and pollutant routing based on user-supplied direct and dry weather inflows. The default is NO.
-IGNORE_SNOWMELT is set to YES if snowmelt calculations should be ignored when a project file contains snow pack objects. The default is NO.
-IGNORE_GROUNDWATER is set to YES if groundwater calculations should be ignored when a project file contains aquifer objects. The default is NO.
-IGNORE_RDII is set to YES if rainfall-dependent infiltration and inflow should be ignored when RDII unit hydrographs and RDII inflows have been supplied to a project file. The default is NO.
-IGNORE_ROUTING is set to YES if only runoff should be computed even if the project contains drainage system links and nodes. The default is NO.
-IGNORE_QUALITY is set to YES if pollutant washoff, routing, and treatment should be ignored in a project that has pollutants defined. The default is NO.
-ALLOW_PONDING determines whether excess water is allowed to collect atop nodes and be re-introduced into the system as conditions permit. The default is NO ponding. In order for ponding to actually occur at a particular node, a non-zero value for its Ponded Area attribute must be used.
-SKIP_STEADY_STATE should be set to YES if flow routing computations should be skipped during steady state periods of a simulation during which the last set of computed flows will be used. A time step is considered to be in steady state if the percent difference between total system inflow and total system outflow is below the SYS_FLOW_TOL and the percent difference between current and previous lateral inflows are below the LAT_FLOW_TOL. The default for this option is NO.
-SYS_FLOW_TOL is the maximum percent difference between total system inflow and total system outflow which can occur in order for the SKIP_STEADY_STATE option to take effect. The default is 5 percent.
-LAT_FLOW_TOL is the maximum percent difference between the current and previous lateral inflow at all nodes in the conveyance system in order for the SKIP_STEADY_STATE option to take effect. The default is 5 percent.
-START_DATE is the date when the simulation begins. If not supplied, a date of 1/1/2004 is used.
-START_TIME is the time of day on the starting date when the simulation begins. The default is 12 midnight (0:00:00).
-END_DATE is the date when the simulation is to end. The default is the start date.
-END_TIME is the time of day on the ending date when the simulation will end. The default is 24:00:00.
-REPORT_START_DATE is the date when reporting of results is to begin. The default is the simulation start date.
-REPORT_START_TIME is the time of day on the report starting date when reporting is to begin. The default is the simulation start time of day.
-SWEEP_START is the day of the year (month/day) when street sweeping operations begin. The default is 1/1.
-SWEEP_END is the day of the year (month/day) when street sweeping operations end. The default is 12/31.
-DRY_DAYS is the number of days with no rainfall prior to the start of the simulation. The default is 0.
-REPORT_STEP is the time interval for reporting of computed results. The default is 0:15:00.
-WET_STEP    is the time step length used to compute runoff from subcatchments during periods of rainfall or when ponded water still remains on the surface. The default is 0:05:00.
-DRY_STEP is the time step length used for runoff computations (consisting essentially of pollutant buildup) during periods when there is no rainfall and no ponded water. The default is 1:00:00.
-ROUTING_STEP is the time step length in seconds used for routing flows and water quality constituents through the conveyance system. The default is 20 sec. This can be increased if dynamic wave routing is not used. Fractional values (e.g., 2.5) are permissible as are values entered in hours:minutes:seconds format. 
-LENGTHENING_STEP is a time step, in seconds, used to lengthen conduits under dynamic wave routing, so that they meet the Courant stability criterion under full-flow conditions (i.e., the travel time of a wave will not be smaller than the specified conduit lengthening time step). As this value is decreased, fewer conduits will require lengthening. A value of 0 (the default) means that no conduits will be lengthened.
-VARIABLE_STEP is a safety factor applied to a variable time step computed for each time period under dynamic wave flow routing. The variable time step is computed so as to satisfy the Courant stability criterion for each conduit and yet not exceed the ROUTING_STEP value. If the safety factor is 0 (the default), then no variable time step is used.
-MINIMUM_STEP is the smallest time step allowed when variable time steps are used for dynamic wave flow routing. The default value is 0.5 seconds. 
-INERTIAL_DAMPING    indicates how the inertial terms in the Saint Venant momentum equation will be handled under dynamic wave flow routing. Choosing NONE maintains these terms at their full value under all conditions. Selecting PARTIAL (the default) will reduce the terms as flow comes closer to being critical (and ignores them when flow is supercritical). Choosing FULL will drop the terms altogether.
-NORMAL_FLOW_LIMITED specifies which condition is checked to determine if flow in a conduit is supercritical and should thus be limited to the normal flow. Use SLOPE to check if the water surface slope is greater than the conduit slope, FROUDE to check if the Froude number is greater than 1.0, or BOTH to check both conditions. The default is BOTH.
-SURCHARGE_METHOD selects which method will be used to handle surcharge conditions. The EXTRAN option uses a variation of the Surcharge Algorithm from previous versions of SWMM to update nodal heads when all connecting links become full. The SLOT option uses a Preissmann Slot to add a small amount of virtual top surface width to full flowing pipes so that SWMM's normal procedure for updating nodal heads can continue to be used. The default is EXTRAN.
-MIN_SURFAREA is a minimum surface area used at nodes when computing changes in water depth under dynamic wave routing. If 0 is entered, then the default value of 12.566 ft2 (1.167 m2) (i.e., the area of a 4-ft diameter manhole) is used.
-MIN_SLOPE is the minimum value allowed for a conduit’s slope (%). If zero (the default) then no minimum is imposed (although SWMM uses a lower limit on elevation drop of 0.001 ft (0.00035 m) when computing a conduit slope).
-MAX_TRIALS is the maximum number of trials allowed during a time step to reach convergence when updating hydraulic heads at the conveyance system’s nodes. The default value is 8.
-HEAD_TOLERANCE is the difference in computed head at each node between successive trials below which the flow solution for the current time step is assumed to have converged. The default tolerance is 0.005 ft (0.0015 m).
-THREADS is the number of parallel computing threads to use for dynamic wave flow routing on machines equipped with multi-core processors. The default is 1.
-
-**New in OpenSWMM v6:**
-
-CRS specifies a Coordinate Reference System for the model geometry, given as an EPSG code (e.g. `EPSG:4326`) or a PROJ string. This value is stored in `SimulationOptions::crs` and is available through the C API via `swmm_spatial_get_crs()`. When a CRS is set, all coordinate and polygon data in the `[COORDINATES]`, `[VERTICES]`, and `[POLYGONS]` sections are assumed to be in that reference system.
-
-Any option keyword not recognized by the parser is stored in an extension-options map as a key–value string pair (the key is upper-cased). A non-fatal warning is issued for each unrecognised key. Extension options can be queried at runtime with `swmm_options_get_ext()` and set with `swmm_options_set_ext()`. This allows plugins and coupled models to receive configuration through the `[OPTIONS]` section. 
-### Section: [REPORT]
-
-Purpose:
-Describes the contents of the report file that is produced.
-
-Formats:
-DISABLED            YES / NO
-INPUT                YES / NO
-CONTINUITY        YES / NO
-FLOWSTATS        YES / NO
-CONTROLS            YES / NO
-SUBCATCHMENTS    ALL / NONE / <list of subcatchment names>
-NODES                ALL / NONE / <list of node names>
-LINKS                ALL / NONE / <list of link names>
-LID                Name  Subcatch  Fname
-
-Remarks:
-Setting DISABLED to YES disables all reporting (except for error and warning messages) regardless of what other reporting options are chosen.  The default is NO.
-INPUT specifies whether or not a summary of the input data should be provided in the output report. The default is NO.
-CONTINUITY specifies if continuity checks should be reported or not. The default is YES.
-FLOWSTATS specifies whether summary flow statistics should be reported or not. The default is YES.
-CONTROLS specifies whether all control actions taken during a simulation should be listed or not. The default is NO.
-SUBCATCHMENTS gives a list of subcatchments whose results are to be reported. The default is NONE.
-NODES gives a list of nodes whose results are to be reported. The default is NONE.
-LINKS gives a list of links whose results are to be reported. The default is NONE.
-LID specifies that the LID control Name in subcatchment Subcatch should have a detailed performance report for it written to file Fname.
-The SUBCATCHMENTS, NODES, LINKS, and LID lines can be repeated multiple times. 
-### Section: [FILES]
-
-Purpose:
-Identifies optional interface files used or saved by a run.
-
-Formats:
-USE / SAVE    RAINFALL        Fname        
-USE / SAVE    RUNOFF        Fname        
-USE / SAVE    HOTSTART        Fname        
-USE / SAVE    RDII            Fname
-USE      INFLOWS                Fname
-SAVE    OUTFLOWS                Fname
-
-Parameters:
-Fname     is the name of an interface file.
-
-Remarks:
-Refer to Section 11.7 for a description of interface files. Rainfall, Runoff, and RDII files can either be used or saved in a run, but not both. A run can both use and save a Hot Start file (with different names).
-Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. 
-
- 
-### Section: [RAINGAGES]
-
-Purpose:
-Identifies each rain gage that provides rainfall data for the study area.
-
-Formats:
-Name Form Intvl SCF TIMESERIES Tseries
-Name Form Intvl SCF FILE Fname (Sta Units)
-
-Parameters:
-Name    name assigned to rain gage.
-Form     form of recorded rainfall, either INTENSITY, VOLUME or CUMULATIVE.
-Intvl    time interval between gage readings in decimal hours or hours:minutes format (e.g., 0:15 for 15-minute readings).
-SCF     snow catch deficiency correction factor (use 1.0 for no adjustment).
-Tseries    name of a time series in the [TIMESERIES] section with rainfall data.
-Fname    name of an external file with rainfall data. Rainfall files are discussed in Section 11.3.
-Sta    name of the recording station in a user-prepared formatted rain file.
-Units    rain depth units for the data in a user-prepared formatted rain file, either IN (inches) or MM (millimeters).
-
-Remarks:
-Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file.
-The station name and depth units entries are only required when using a user-prepared formatted rainfall file.
-
-**New in OpenSWMM v6:** A multi-column CSV rain file can be referenced by appending a colon and column name to the file path, e.g. `FILE "rain.csv:EAST_GAGE"`. The engine opens the CSV, locates the column whose header matches the given name, and reads the rainfall values from that column. This allows a single CSV file to supply data for multiple rain gages.
-
- 
-### Section: [EVAPORATION]
-
-Purpose:
-Specifies how daily potential evaporation rates vary with time for the study area.
-
-Formats:
-CONSTANT        evap
-MONTHLY        e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12
-TIMESERIES    Tseries
-TEMPERATURE
-FILE            (p1 p2 p3 p4 p5 p6 p7 p8 p9 p10 p11 p12)
-RECOVERY        patternID
-DRY_ONLY        NO / YES
-
-Parameters:
-evap        constant evaporation rate (in/day or mm/day).
-e1            evaporation rate in January (in/day or mm/day).
-...
-e12        evaporation rate in December (in/day or mm/day).
-Tseries    name of a time series in the [TIMESERIES] section with evaporation data.
-p1            pan coefficient for January.
-...
-p12        pan coefficient for December.
-patID        name of a monthly time pattern.
-
-Remarks:
-Use only one of the above formats (CONSTANT, MONTHLY, TIMESERIES, TEMPERATURE, or FILE). If no [EVAPORATION] section appears, then evaporation is assumed to be 0.
-TEMPERATURE indicates that evaporation rates will be computed from the daily air temperatures contained in an external climate file whose name is provided in the [TEMPERATURE] section. This method also uses the site’s latitude, which can also be specified in the [TEMPERATURE] section.
-FILE indicates that evaporation data will be read directly from the same external climate file used for air     temperatures as specified in the [TEMPERATURE] section. Supplying monthly pan coefficients for these data is optional.
-RECOVERY identifies an optional monthly time pattern of multipliers used to modify infiltration recovery rates during dry periods. For example, if the normal infiltration recovery rate was 1% during a specific time period and a pattern factor of 0.8 applied to this period, then the actual recovery rate would be 0.8%.
-DRY_ONLY determines if evaporation only occurs during periods with no precipitation. The default is NO.
-The evaporation rates provided in this section are potential rates. The actual amount of water evaporated will depend on the amount available as a simulation progresses.
- 
-### Section: [TEMPERATURE]
-
-Purpose:    
-Specifies daily air temperatures, monthly wind speed, and various snowmelt parameters for the study area. Required only when snowmelt is being modeled or when evaporation rates are computed from daily temperatures or are read from an external climate file.
-
-Formats:
-TIMESERIES    Tseries
-FILE    Fname (Start) (Units)
-WINDSPEED     MONTHLY s1 s2 s3 s4 s5 s6 s7 s8 s9 s10 s11 s12
-WINDSPEED    FILE
-SNOWMELT         Stemp  ATIwt  RNM  Elev  Lat  DTLong
-ADC IMPERVIOUS     f.0 f.1 f.2 f.3 f.4 f.5 f.6 f.7 f.8 f.9
-ADC PERVIOUS       f.0 f.1 f.2 f.3 f.4 f.5 f.6 f.7 f.8 f.9
-
-Parameters:
-Tseries    name of a time series in the [TIMESERIES] section with temperature data.
-Fname    name of an external Climate file with temperature data.
-Start    date to begin reading from the file in month/day/year format (default is the beginning of the file).
-Units    temperature units for GHCN files (C10 for tenths of a degree C (the default), C for degrees C or F for degrees F.
-s1    average wind speed in January (mph or km/hr).
-...
-s12    average wind speed in December (mph or km/hr). 
-Stemp    air temperature at which precipitation falls as snow (deg F or C).
-ATIwt    antecedent temperature index weight (default is 0.5).
-RNM    negative melt ratio (default is 0.6).
-Elev    average elevation of study area above mean sea level (ft or m) (default is 0).
-Lat    latitude of the study area in degrees North (default is 50).
-DTLong    correction, in minutes of time, between true solar time and the standard clock time (default is 0).
-f.0    fraction of area covered by snow when ratio of snow depth to depth at 100% cover is 0
-...
-f.9    fraction of area covered by snow when ratio of snow depth to depth at 100% cover is 0.9.
-
-Remarks:
-Use the TIMESERIES line to read air temperature from a time series or the FILE line to read it from an external Climate file. Climate files are discussed in Section 11.4. If neither format is used, then air temperature remains constant at 70 degrees F.
-Enclose the Climate file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file.
-Temperatures supplied from NOAA's latest Climate Data Online GHCN files should have their units (C or F) specified. Older versions of these files listed temperatures in tenths of a degree C (C10). An asterisk can be entered for the Start date if it defaults to the beginning of the file.
-Wind speed can be specified either by monthly average values or by the same Climate file used for air temperature. If neither option appears, then wind speed is assumed to be 0.
-Separate Areal Depletion Curves (ADC) can be defined for impervious and pervious subareas. The ADC parameters will default to 1.0 (meaning no depletion) if no data are supplied for a particular type of subarea.
-
- 
-### Section: [ADJUSTMENTS]
-
-Purpose:
-Specifies optional monthly adjustments to be made to temperature, evaporation rate, rainfall intensity and hydraulic conductivity in each time period of a simulation.
-
-Formats:
-TEMPERATURE    t1 t2 t3 t4 t5 t6 t7 t8 t9 t10 t11 t12 
-EVAPORATION    e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12
-RAINFALL        r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 
-CONDUCTIVITY    c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12
-
-Parameters:
-  t1..t12    adjustments to temperature in January, February, etc., as plus or minus degrees F (degrees C).
-e1..e12    adjustments to evaporation rate in January, February, etc., as plus or minus in/day (mm/day).
-r1..r12    multipliers applied to precipitation rate in January, February, etc.
-c1..c12    multipliers applied to soil hydraulic conductivity in January, February, etc. used in either Horton or Green-Ampt infiltration.
-Remarks:
-The same adjustment is applied for each time period within a given month and is repeated for that month in each subsequent year being simulated.
-
-
-
- 
-### Section: [SUBCATCHMENTS]
-
-Purpose:
-Identifies each subcatchment within the study area. Subcatchments are land area units which generate runoff from rainfall.
-
-Format:
-Name Rgage OutID Area %Imperv Width Slope Clength (Spack)
-
-Parameters:
-Name    name assigned to the subcatchment.
-Rgage    name of a rain gage in the [RAINGAGES] section assigned to the subcatchment.
-OutID    name of the node or subcatchment that receives runoff from the subcatchment.
-Area    area of the subcatchment (acres or hectares).
-%Imperv    percentage of the subcatchment’s area that is impervious.
-Width    characteristic width of the subcatchment (ft or meters).
-Slope    the subcatchment’s slope (percent).
-Clength    total curb length (any length units) used to describe pollutant buildup. Use 0 if not applicable.
-Spack    optional name of a snow pack object (from the [SNOWPACKS] section) that characterizes snow accumulation and melting over the subcatchment.
-
- 
-### Section: [SUBAREAS]
-
-Purpose:
-Supplies information about pervious and impervious areas for each subcatchment. Each subcatchment can consist of a pervious subarea, an impervious subarea with depression storage, and an impervious subarea without depression storage.
-
-Format:
-Subcat Nimp Nperv Simp Sperv %Zero RouteTo (%Routed)
-
-Parameters:
-Subcat    subcatchment name.
-Nimp    Manning's coefficient (n) for overland flow over the impervious subarea.
-Nperv    Manning's coefficient (n) for overland flow over the pervious subarea.
-Simp    depression storage for the impervious subarea (inches or mm).
-Sperv    depression storage for the pervious subarea (inches or mm).
-%Zero    percent of impervious area with no depression storage.
-RouteTo    IMPERVIOUS if pervious area runoff runs onto impervious area,  PERVIOUS if impervious runoff runs onto pervious area, or OUTLET if both areas drain to the subcatchment's outlet (default = OUTLET).
-%Routed    percent of runoff routed from one type of area to another (default = 100).
- 
-### Section: [INFILTRATION]
-
-Purpose:
-Supplies infiltration parameters for each subcatchment. Rainfall lost to infiltration only occurs over the pervious subarea of a subcatchment.
-
-Format:
-Subcat  p1  p2  p3  (p4  p5)  (Method)
-
-Parameters:
-Subcat    subcatchment name.
-Method    either HORTON, MODIFIED_HORTON, GREEN_AMPT,   MODIFIED_GREEN_AMPT, or CURVE_NUMBER.
-If not specified then the infiltration method supplied in the [OPTIONS] section is used.
-For Horton and Modified Horton Infiltration:
-p1    maximum infiltration rate on the Horton curve (in/hr or mm/hr).
-p2    minimum infiltration rate on the Horton curve (in/hr or mm/hr).
-p3    decay rate constant of the Horton curve (1/hr).
-p4    time it takes for a fully saturated soil to dry  (days).
-p5    maximum infiltration volume possible (0 if not applicable) (in or mm).
-For Green-Ampt and Modified Green-Ampt Infiltration:
-p1    soil capillary suction (in or mm).
-p2    soil saturated hydraulic conductivity (in/hr or mm/hr).
-p3    initial soil moisture deficit (porosity minus moisture content) (fraction).
-For Curve-Number Infiltration:
-p1    SCS Curve Number.
-p2    no longer used.
-p3    time it takes for a fully saturated soil to dry (days). 
-### Section: [LID_CONTROLS]
-
-Purpose:
-Defines scale-independent LID controls that can be deployed within subcatchments.
-
-Formats:
-Name     Type
-followed by one or more of the following lines depending on Type:
-Name SURFACE  StorHt VegFrac Rough Slope Xslope
-Name SOIL     Thick Por FC WP Ksat Kcoeff Suct
-Name PAVEMENT Thick Vratio FracImp Perm Vclog (Treg Freg)
-Name STORAGE  Height Vratio Seepage Vclog (Covrd)
-Name DRAIN    Coeff Expon Offset Delay (Hopen Hclose Qcrv)
-Name DRAINMAT Thick Vratio Rough
-Name REMOVALS Pollut Rmvl Pollut Rmvl ... 
-
-Parameters:
-Name    name assigned to LID process.
-Type    BC for bio-retention cell; RG for rain garden; GR for green roof; IT for infiltration trench; PP for permeable pavement; RB for rain barrel; RD for rooftop disconnection; VS for vegetative swale.
-Pollut    name of a pollutant
-Rmvl    the percent removal the LID achieves for the pollutant (several pollutant removals can be placed on the same line or specified in separate REMOVALS lines).
-
-For LIDs with Surface Layers:
-StorHt    when confining walls or berms are present this is the maximum depth to which water can pond above the surface of the unit before overflow occurs (in inches or mm). For LIDs that experience overland flow it is the height of any surface depression storage. For swales, it is the height of its trapezoidal cross-section.
-VegFrac    fraction of the surface storage volume that is filled with vegetation.
-Rough    Manning's coefficient (n) for overland flow over surface soil cover, pavement, roof surface or a vegetative swale. Use 0 for other types of LIDs.
-Slope     slope of a roof surface, pavement surface or vegetative swale (percent). Use 0 for other types of LIDs.
-Xslope    slope (run over rise) of the side walls of a vegetative swale's cross-section. Use 0 for other types of LIDs.
-If either Rough or Slope values are 0 then any ponded water that exceeds the surface storage depth is assumed to completely overflow the LID control within a single time step.
-
-For LIDs with Pavement Layers:
-Thick    thickness of the pavement layer (inches or mm).
-Vratio    void ratio (volume of void space relative to the volume of solids in the pavement for continuous systems or for the fill material used in modular systems). Note that porosity = void ratio / (1 + void ratio).
-FracImp    ratio of impervious paver material to total area for modular systems; 0 for continuous porous pavement systems.
-Perm    permeability of the concrete or asphalt used in continuous systems or hydraulic conductivity of the fill material (gravel or sand) used in modular systems (in/hr or mm/hr).
-Vclog    the number of pavement layer void volumes of runoff treated it takes to completely clog the pavement. Use a value of 0 to ignore clogging.
-Treg    the number of days that the pavement layer is allowed to clog before its permeability is restored, typically by vacuuming its surface. A value of 0 (the default) indicates that no permeability regeneration occurs.
-Freg    The fractional degree to which the pavement's permeability is restored when a regeneration interval is reached. The default is 0 (no restoration) while a value of 1 indicates complete restoration to the original permeability value. Once regeneration occurs the pavement begins to clog once again at a rate determined by Vclog.
-
-For LIDs with Soil Layers:
-Thick    thickness of the soil layer (inches or mm).
-Por    soil porosity (pore space volume / total volume).
-FC    soil field capacity (moisture content of a fully drained soil).
-WP    soil wilting point (moisture content of a fully dried soil).
-Ksat    soil’s saturated hydraulic conductivity (in/hr or mm/hr).
-Kcoeff    slope of the curve of log(conductivity) versus soil moisture deficit (porosity minus soil moisture) (dimensionless).
-Suct    soil capillary suction (in or mm).
-
-For LIDs with Storage Layers:
-Height    thickness of the storage layer or height of a rain barrel (inches or mm).
-Vratio    void ratio (volume of void space relative to the volume of solids in the layer). Note that porosity = void ratio / (1 + void ratio). 
-Seepage    the rate at which water seeps from the layer into the underlying native soil when first constructed (in/hr or mm/hr). If there is an impermeable floor or liner below the layer then use a value of 0.
-Vclog    number of storage layer void volumes of runoff treated it takes to completely clog the layer. Use a value of 0 to ignore clogging.
-Covrd    YES (the default) if a rain barrel is covered, NO if it is not. 
-Values for Vratio, Seepage, and Vclog  are ignored for rain barrels while Covrd applies only to rain barrels.
-
-For LIDs with Drain Systems:
-Coeff    coefficient C that determines the rate of flow through the drain as a function of height of stored water above the drain bottom. For Rooftop Disconnection it is the maximum flow rate (in inches/hour or mm/hour) that the roof’s gutters and downspouts can handle before overflowing.
-Expon    exponent n that determines the rate of flow through the drain as a function of height of stored water above the drain outlet.
-Offset    height of the drain line above the bottom of the storage layer or rain barrel (inches or mm).
-Delay     number of dry weather hours that must elapse before the drain line in a rain barrel is opened (the line is assumed to be closed once rainfall begins). A value of 0 signifies that the barrel's drain line is always open and drains continuously.  This parameter is ignored for other types of LIDs.
-Hopen    The height of water  (in inches or mm) in the drain's Storage Layer that causes the drain to automatically open. Use 0 to disable this feature.
-Hclose    The height of water (in inches or mm) in the drain's Storage Layer that causes the drain to automatically close. Use 0 to disable this feature.
-Qcurve    The name of an optional Control Curve that adjusts the computed drain flow as a function of the head of water above the drain. Leave blank if not applicable.
-
-For Green Roof LIDs with Drainage Mats:
-Thick    thickness of the drainage mat (inches or mm).
-Vratio     ratio of void volume to total volume in the mat.
-Rough    Manning's coefficient (n) used to compute the horizontal flow rate of drained water through the mat.
-
-Remarks:
-The following table shows which layers are required (x) or are optional (o) for each type of LID process:
-
-LID Type    Surface    Pavement    Soil    Storage    Drain    Drain Mat
-Bio-Retention Cell    x        x    x    o    
-Rain Garden    x        x            
-Green Roof    x        x            x
-Infiltration Trench    x            x    o    
-Permeable Pavement    x    x    o    x    o    
-Rain Barrel                x    x    
-Rooftop Disconnection    x                x    
-Vegetative Swale    x                    
-
-The equation used to compute flow rate out of the underdrain per unit area of the LID (in in/hr or mm/hr) is   where q is outflow, h is height of stored water (inches or mm) and Hd is the drain offset height. Note that the units of C depend on the unit system being used as well as the value assigned to n.
-The actual dimensions of an LID control are provided in the [LID_USAGE] section when it is placed in a particular subcatchment.
-
-
-Examples:
-;A street planter with no drain
-Planter  BC
-Planter  SURFACE   6  0.3  0    0     0
-Planter  SOIL     24  0.5  0.1  0.05  1.2  2.4
-Planter  STORAGE  12  0.5  0.5  0
-
-;A green roof with impermeable bottom
-GR1  BC
-GR1  SURFACE  3  0    0    0     0
-GR1  SOIL     3  0.5  0.1  0.05  1.2  2.4
-GR1  STORAGE  3  0.5  0    0
-GR1  DRAIN    5  0.5  0    0
-
-;A rain barrel that drains 6 hours after rainfall ends
-RB12  RB
-RB12  STORAGE  36  0    0  0
-RB12  DRAIN    10  0.5  0  6
-
-;A grass swale 24 in. high with 5:1 side slope
-Swale  VS
-Swale  SURFACE  24  0  0.2  3  5
-
- 
-### Section: [LID_USAGE]
-
-Purpose:
-Deploys LID controls within specific subcatchment areas.
-
-Format:
-Subcat LID Number Area Width InitSat FromImp ToPerv
-(RptFile DrainTo FromPerv)                                                   
-                                        
-Parameters:
-Subcat    name of the subcatchment using the LID process.
-LID    name of an LID process defined in the [LID_CONTROLS] section.
-Number    number of replicate LID units deployed.
-Area    area of each replicate unit (ft2 or m2).
-Width    width of the outflow face of each identical LID unit (in ft or m). This parameter applies to roofs, pavement, trenches, and swales that use overland flow to convey surface runoff off of the unit. It can be set to 0 for other LID processes, such as bio-retention cells, rain gardens, and rain barrels that simply spill any excess captured runoff over their berms.
-InitSat    the percent to which the LID's soil, storage, and drain mat zones are initially filled with water. For soil zones 0 % saturation corresponds to the wilting point moisture content while 100 % saturation has the moisture content equal to the porosity.
-FromImp    the percent of the impervious portion of the subcatchment’s non-LID area whose runoff is treated by the LID practice. (E.g., if rain barrels are used to capture roof runoff and roofs represent 60% of the impervious area, then the impervious area treated is 60%). If the LID unit treats only direct rainfall, such as with a green roof, then this value should be 0. If the LID takes up the entire subcatchment then this field is ignored.
-ToPerv    a value of 1 indicates that the surface and drain flow from the LID unit should be routed back onto the pervious area of the subcatchment that contains it. This would be a common choice to make for rain barrels, rooftop disconnection, and possibly green roofs. The default value is 0.
-
-
-RptFile    optional name of a file to which detailed time series results for the LID will be written. Enclose the name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. Use ‘*’ if not applicable and an entry for DrainTo or FromPerv follows
-DrainTo     optional name of subcatchment or node that receives flow from the unit’s drain line, if different from the outlet of the subcatchment that the LID is placed in. Use ‘*’ if not applicable and an entry for FromPerv follows.
-FromPerv    optional percent of the pervious portion of the subcatchment’s non-LID area whose runoff is treated by the LID practice. The default value is 0.
-
-Remarks:
-If ToPerv is set to 1 and DrainTo set to some other outlet, then only the excess surface flow from the LID unit will be routed back to the subcatchment’s pervious area while the underdrain flow will be sent to DrainTo.
-More than one type of LID process can be deployed within a subcatchment as long as their total area does not exceed that of the subcatchment and the total percent impervious area treated does not exceed 100.
-
-Examples:
-;34 rain barrels of 12 sq ft each are placed in
-;subcatchment S1. They are initially empty and treat 17%
-;of the runoff from the subcatchment’s impervious area.
-;The outflow from the barrels is returned to the ;subcatchment’s pervious area.
-S1  RB14  34  12  0  0  17  1
-
-;Subcatchment S2 consists entirely of a single vegetative ;swale 200 ft long by 50 ft wide.
-S2  Swale  1  10000  50  0  0  0  “swale.rpt”
-
- 
-### Section: [AQUIFERS]
-
-Purpose:
-Supplies parameters for each unconfined groundwater aquifer in the study area. Aquifers consist of two zones – a lower saturated zone and an upper unsaturated zone with a moving boundary between the two.
-
-Format:
-Name Por WP FC Ks Kslp Tslp ETu ETs Seep Ebot Egw Umc (Epat)                      
-
-Parameters:
-Name    name assigned to aquifer.
-Por    soil porosity (pore space volume / total volume).
-WP    soil wilting point (moisture content of a fully dried soil).
-FC    soil field capacity (moisture content of a fully drained soil).
-Ks    saturated hydraulic conductivity (in/hr or mm/hr).
-Kslp    slope of the logarithm of hydraulic conductivity versus moisture deficit (porosity minus moisture content) curve (dimensionless).
-Tslp    slope of soil tension versus moisture content curve (inches or mm).
-ETu    fraction of total evaporation available for evapotranspiration in the upper unsaturated zone.
-ETs    maximum depth into the lower saturated zone over which evapotranspiration can occur (ft or m).
-Seep    seepage rate from saturated zone to deep groundwater when water table is at ground surface (in/hr or mm/hr).
-Ebot    elevation of the bottom of the aquifer (ft or m).
-Egw    groundwater table elevation at start of simulation (ft or m).
-Umc    unsaturated zone moisture content at start of simulation (volumetric fraction).
-Epat    name of optional monthly time pattern used to adjust the upper zone evaporation fraction for different months of the year.
-Remarks:
-Local values for Ebot, Egw, and Umc can be assigned to specific subcatchments in the [GROUNDWATER] section.
- 
-### Section: [GROUNDWATER]
-
-Purpose:
-Supplies parameters that determine the rate of groundwater flow between the aquifer underneath a subcatchment and a node of the conveyance system.
-
-Format:
-Subcat Aquifer Node Esurf A1 B1 A2 B2 A3 Dsw (Egwt Ebot Egw Umc)
-
-Parameters:
-Subcat    subcatchment name.
-Aquifer    name of groundwater aquifer underneath the subcatchment.
-Node    name of a node in the conveyance system exchanging groundwater with the aquifer.
-Esurf    surface elevation of the subcatchment (ft or m).
-A1    groundwater flow coefficient (see below).
-B1    groundwater flow exponent (see below).
-A2    surface water flow coefficient (see below).
-B2    surface water flow exponent (see below).
-A3    surface water – groundwater interaction coefficient (see below).
-Dsw    fixed depth of surface water at the receiving node (ft or m) (set to zero if surface water depth will vary as computed by flow routing).
-Egwt    threshold groundwater table elevation which must be reached before any flow occurs (ft or m). Leave blank (or enter *) to use the elevation of the receiving node's invert.
-The following optional parameters can be used to override the values supplied for the subcatchment’s aquifer.
-Ebot    elevation of the bottom of the aquifer (ft or m).
-Egw    groundwater table elevation at the start of the simulation (ft or m).
-Umc    unsaturated zone moisture content at start of simulation (volumetric fraction).
-
-
-
-
-Remarks:
-The flow coefficients are used in the following equation that determines the lateral groundwater flow rate based on groundwater and surface water elevations:
-    QL  =  A1 (Hgw  –  Hcb) B1  –  A2 (Hsw  –  Hcb) B2  +  A3 Hgw Hsw
-where:
-QL   =    lateral groundwater flow (cfs per acre or cms per hectare),
-Hgw   =     height of saturated zone above the bottom of the aquifer (ft or m),
-Hsw   =    height of surface water at the receiving node above the aquifer bottom (ft or m),
-Hcb   =    height of the channel bottom above the aquifer bottom (ft or m).
- 
-### Section: [GWF]
-
-Purpose:
-Defines custom groundwater flow equations for specific subcatchments.
-
-Format:
-Subcat  LATERAL/DEEP  Expr
-
-Parameters:
-Subcat    subcatchment name.
-Expr    a math formula expressing the rate of groundwater flow (in cfs per acre or cms per hectare for lateral flow or in/hr or mm/hr for deep flow) as a function of the following variables:
-Hgw    (for height of the groundwater table)
-Hsw     (for height of the surface water)
-Hcb     (for height of the channel bottom)
-Hgs    (for height of ground surface)
-where all heights are relative to the aquifer bottom and have units of either feet or meters;
-Ks        (for saturated hydraulic conductivity in in/hr or mm/hr)
-K        (for unsaturated hydraulic conductivity in in/hr or mm/hr)
-Theta    (for moisture content of the unsaturated zone)
-Phi    (for aquifer soil porosity)
-Fi        (for infiltration rate from the ground surface in in/hr or mm/hr)
-Fu    (for percolation rate from the upper unsaturated zone in in/hr or mm/hr)
-A        (for subcatchment area in acres or hectares)
-
-Remarks:
-Use LATERAL to designate an expression for lateral groundwater flow (to a node of the conveyance network) and DEEP for vertical loss to deep groundwater.
-See the [TREATMENT] section for a list of built-in math functions that can be used in Expr. In particular, the STEP(x) function is 1 when x > 0 and is 0 otherwise. 
-
-
-
-
-Examples:
-;Two-stage linear reservoir for lateral flow
-Subcatch1 LATERAL 0.001*Hgw + 0.05*(Hgw–5)*STEP(Hgw–5)
-
-;Constant seepage rate to deep aquifer
-Subactch1  DEEP  0.002 
-### Section: [SNOWPACKS]
-
-Purpose:
-Specifies parameters that govern how snowfall accumulates and melts on the plowable, impervious and pervious surfaces of subcatchments.
-
-Formats:
-Name PLOWABLE   Cmin  Cmax  Tbase  FWF  SD0  FW0  SNN0
-Name IMPERVIOUS Cmin  Cmax  Tbase  FWF  SD0  FW0  SD100  
-Name PERVIOUS   Cmin  Cmax  Tbase  FWF  SD0  FW0  SD100
-Name REMOVAL      Dplow Fout Fimp Fperv Fimelt (Fsub Scatch)
-
-Parameters:
-Name    name assigned to snowpack parameter set .
-Cmin    minimum melt coefficient (in/hr-deg F or mm/hr-deg C).
-Cmax    maximum melt coefficient (in/hr-deg F or mm/hr-deg C).
-Tbase    snow melt base temperature (deg F or deg C).
-FWF    ratio of free water holding capacity to snow depth (fraction).
-SD0    initial snow depth (in or mm water equivalent).
-FW0    initial free water in pack (in or mm).
-SNN0    fraction of impervious area that can be plowed.
-SD100    snow depth above which there is 100% cover (in or mm water equivalent).
-Dplow    depth of snow on plowable areas at which snow removal begins (in or mm).
-Fout    fraction of snow on plowable area transferred out of watershed.
-Fimp    fraction of snow on plowable area transferred to impervious area by plowing.
-Fperv    fraction of snow on plowable area transferred to pervious area by plowing.
-Fimelt    fraction of snow on plowable area converted into immediate melt.
-Fsub    fraction of snow on plowable area transferred to pervious area in another subcatchment.
-Scatch    name of subcatchment receiving the Fsub fraction of transferred snow.
-
-
-Remarks:
-Use one set of PLOWABLE, IMPERVIOUS, and PERVIOUS lines for each snow pack parameter set created. Snow pack parameter sets are assigned to specific subcatchments in the [SUBCATCHMENTS] section. Multiple subcatchments can share the same set of snow pack parameters.
-The PLOWABLE line contains parameters for the impervious area of a subcatchment that is subject to snow removal by plowing but not to areal depletion. This area is the fraction SNN0 of the total impervious area. The IMPERVIOUS line contains parameter values for the remaining impervious area and the PERVIOUS line does the same for the entire pervious area. Both of the latter two areas are subject to areal depletion. 
-The REMOVAL line describes how snow removed from the plowable area is transferred onto other areas. The various transfer fractions should sum to no more than 1.0. If the line is omitted then no snow removal takes place.
-
-
- 
-### Section: [JUNCTIONS]
-
-Purpose:
-Identifies each junction node of the drainage system.  Junctions are points in space where channels and pipes connect together. For sewer systems they can be either connection fittings or manholes.
-
-Format:
-Name  Elev  (Ymax  Y0  Ysur  Apond)
-
-Parameters:
-Name    name assigned to junction node.
-Elev    elevation of the junction’s invert (ft or m).
-Ymax    depth from ground to invert elevation (ft or m) (default is 0).
-Y0    water depth at the start of the simulation (ft or m) (default is 0).
-Ysur    maximum additional pressure head above the ground elevation that the junction can sustain under surcharge conditions (ft or m) (default is 0).
-Apond    area subjected to surface ponding once water depth exceeds Ymax + Ysur  (ft2 or m2) (default is 0).
-
-Remarks:
-If Ymax is 0 then SWMM sets the junction’s maximum depth to the distance from its invert to the top of the highest connecting link.
-If the junction is part of a force main section of the system then set Ysur to the maximum pressure that the system can sustain.
-Surface ponding can only occur when Apond is non-zero and the ALLOW_PONDING analysis option is turned on.
-
-
- 
-### Section: [OUTFALLS]
-
-Purpose:
-Identifies each outfall node (i.e., final downstream boundary) of the drainage system and the corresponding water stage elevation.  Only one link can be incident on an outfall node. 
-
-Formats:
-Name  Elev  FREE        (Gated)    (RouteTo)
-Name  Elev  NORMAL      (Gated)    (RouteTo)
-Name  Elev  FIXED       Stage   (Gated)    (RouteTo)
-Name  Elev  TIDAL       Tcurve  (Gated)    (RouteTo)
-Name  Elev  TIMESERIES  Tseries (Gated)    (RouteTo)
-
-Parameters:
-Name    name assigned to outfall node.
-Elev    node’s invert elevation (ft or m).
-Stage    elevation of a fixed stage outfall (ft or m).
-Tcurve     name of a curve in the [CURVES] section containing tidal height (i.e., outfall stage) versus hour of day over a complete tidal cycle.
-Tseries    name of a time series in [TIMESERIES] section that describes how outfall stage varies with time.
-Gated    YES or NO depending on whether a flap gate is present that prevents reverse flow. The default is NO.
-RouteTo    optional name of a subcatchment that receives the outfall's discharge. The default is not to route the outfall’s discharge.
-
-
-
-
-
- 
-### Section: [DIVIDERS]
-
-Purpose:
-Identifies each flow divider node of the drainage system. Flow dividers are junctions with exactly two outflow conduits where the total outflow is divided between the two in a prescribed manner.
-
-Formats:
-Name Elev DivLink OVERFLOW (Ymax Y0 Ysur Apond)
-Name Elev DivLink CUTOFF  Qmin (Ymax Y0 Ysur Apond)
-Name Elev DivLink TABULAR Dcurve (Ymax Y0 Ysur Apond)
-Name Elev DivLink WEIR    Qmin Ht Cd (Ymax Y0 Ysur Apond)
-
-Parameters:
-Name    name assigned to divider node.
-Elev    node’s invert elevation (ft or m).
-DivLink    name of the link to which flow is diverted.
-Qmin    flow at which diversion begins for either a CUTOFF or WEIR divider (flow units).
-Dcurve    name of a curve for a TABULAR divider that relates diverted flow to total flow.
-Ht    height of a WEIR divider (ft or m).
-Cd    discharge coefficient for a WEIR divider.
-Ymax    depth from the ground to the node’s invert elevation (ft or m) (default is 0).
-Y0    water depth at the start of the simulation (ft or m) (default is 0).
-Ysur    maximum additional pressure head above the ground elevation that the node can sustain under surcharge conditions (ft or m) (default is 0).
-Apond    area subjected to surface ponding once water depth exceeds Ymax + Ysur  (ft2 or m2) (default is 0).
-
-
-
-
-Remarks:
-If Ymax is 0 then SWMM sets the node’s maximum depth equal to the distance from its invert to the top of the highest connecting link.
-Surface ponding can only occur when Apond is non-zero and the ALLOW_PONDING analysis option is turned on.
-Divider nodes are only active under the Steady Flow or Kinematic Wave analysis options. For Dynamic Wave flow routing they behave the same as Junction nodes.
-
-
- 
-### Section: [STORAGE]
-
-Purpose:
-Identifies each storage node of the drainage system. Storage nodes can have any shape as specified by a surface area versus water depth relation.
-
-Formats:    
-Name Elev Ymax Y0 TABULAR    Acurve   (Ysur Fevap Psi Ksat IMD)
-Name Elev Ymax Y0 FUNCTIONAL A1 A2 A0 (Ysur Fevap Psi Ksat IMD)
-Name Elev Ymax Y0 Shape      L  W  Z  (Ysur Fevap Psi Ksat IMD)
-
-Parameters:
-Name    name assigned to storage node.
-Elev    node’s invert elevation (ft or m).
-Ymax    water depth when the storage node is full (ft or m).
-Y0    water depth at the start of the simulation (ft or m).
-Acurve    name of a curve in the [CURVES] section that relates surface area (ft2 or m2) to depth (ft or m) for TABULAR geometry.
-A1    coefficient of a FUNCTIONAL relation between surface area and depth.
-A2    exponent of a FUNCTIONAL relation between surface area and depth.
-A0    constant of a FUNCTIONAL relation between surface area and depth.
-Shape    shape used to relate surface area to depth; choices are CYLINDRICAL, CONICAL, PARABOLOID, or PYRAMIDAL.
-Ysur    maximum additional pressure head above full depth that a closed storage unit can sustain under surcharge conditions (ft or m) (default is 0).
-L, W, Z    dimensions of the storage unit's shape (see table below).  
-Fevap    fraction of potential evaporation from the storage unit’s water surface realized (default is 0).
-Optional seepage parameters for soil surrounding the storage unit:
-Psi     suction head (inches or mm).
-Ksat    saturated hydraulic conductivity  (in/hr or mm/hr).
-IMD    initial moisture deficit (porosity minus moisture content) (fraction).
-Remarks:
-A1, A2, and A0 are used in the following expression that relates surface area (ft2 or m2) to water depth (ft or m) for a storage unit with FUNCTIONAL geometry:
-Area=A0+A1〖Depth〗^A2
-For TABULAR geometry, the surface area curve will be extrapolated outwards to meet the unit's maximum depth if need be.
-The dimensions of storage units with other shapes are defined as follows:
-Shape    L    W    Z
-CYLINDRICAL
-      major axis length    minor axis width    not used
-CONICAL
-            major axis length of base    minor axis width of base    side slope (run/rise)
-PARABOLOID
-         major axis length at full height    minor axis width at full height    full height
-PYRAMIDAL
-         base length    base width    side slope (run/rise)
-
-The parameters Psi, Ksat, and IMD need only be supplied if seepage loss through the soil at the bottom and sloped sides of the storage unit should be considered. They are the same Green-Ampt infiltration parameters described in the [INFILTRATION] section. If Ksat is zero then no seepage occurs while if IMD is zero then seepage occurs at a constant rate equal to Ksat. Otherwise seepage rate will vary with storage depth.
- 
-### Section: [CONDUITS]
-
-Purpose:
-Identifies each conduit link of the drainage system. Conduits are pipes or channels that convey water from one node to another.
-
-Format:
-Name  Node1  Node2  Length  N  Z1  Z2  (Q0  Qmax)
-
-Parameters:
-Name    name assigned to conduit link.
-Node1    name of the conduit’s upstream node.
-Node2    name of the conduit’s downstream node.
-Length    conduit length (ft or m).
-N    Manning’s roughness coefficient (n).
-Z1    offset of the conduit’s upstream end above the invert of its upstream node (ft or m).
-Z2    offset of the conduit’s downstream end above the invert of its downstream node (ft or m).
-Q0    flow in the conduit at the start of the simulation (flow units) (default is 0).
-Qmax    maximum flow allowed in the conduit (flow units) (default is no limit).
-
-Remarks:
-The figure below illustrates the meaning of the Z1 and Z2 parameters. 
-     
-These offsets are expressed as a relative distance above the node invert if the LINK_OFFSETS option is set to DEPTH (the default) or as an absolute elevation if it is set to ELEVATION. 
-
-
-### Section: [PUMPS]
-
-Purpose:
-Identifies each pump link of the drainage system.
-
-Format:
-Name  Node1  Node2  Pcurve  (Status  Startup  Shutoff)
-
-Parameters:
-Name        name assigned to pump link. 
-Node1        name of the pump’s inlet node.
-Node2        name of the pump’s outlet node.
-Pcurve        name of a pump curve listed in the [CURVES] section of the input.
-Status    pump’s status at the start of the simulation (either ON or OFF; default is ON).
-Startup        depth at the inlet node when the pump turns on (ft or m) (default is 0).
-Shutoff        depth at inlet node when the pump shuts off (ft or m) (default is 0).
-
-Remarks:
-See Section 3.2 for a description of the different types of pumps available.
-
-
- 
-### Section: [ORIFICES]
-
-Purpose:
-Identifies each orifice link of the drainage system. An orifice link serves to limit the flow exiting a node and is often used to model flow diversions and storage node outlets.
-
-Format:
-Name  Node1  Node2  Type  Offset  Cd  (Gated  Orate)
-
-Parameters:
-Name    name assigned to orifice link.
-Node1    name of the orifice’s inlet node.
-Node2    name of the orifice’s outlet node.
-Type    the type of orifice - either SIDE if oriented in a vertical plane or BOTTOM if oriented in a horizontal plane.
-Offset    amount that a Side Orifice’s bottom or the position of a Bottom Orifice is offset above the invert of inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting).
-Cd    discharge coefficient (unitless).
-Flap    YES if a flap gate prevents reverse flow, NO if not (default is NO).
-Orate    time in decimal hours to open a fully closed orifice (or close a fully open one). Use 0 if the orifice can open/close instantaneously.
-
-Remarks:
-The geometry of an orifice’s opening must be described in the [XSECTIONS] section. The only allowable shapes are CIRCULAR and RECT_CLOSED (closed rectangular).
-
-
-
-
-
-
-
-
-
- 
-### Section: [WEIRS]
-
-Purpose:
-Identifies each weir link of the drainage system. Weirs are used to model flow diversions and storage node outlets.
-
-Format:    
-Name Node1 Node2 Type CrstHt Cd (Gated EC Cd2 Sur (Width Surf))
-
-Parameters:
-Name    name assigned to weir link.
-Node1    name of the weir’s inlet node.
-Node2    name of the weir’s outlet node.
-Type    TRANSVERSE, SIDEFLOW, V-NOTCH, TRAPEZOIDAL or ROADWAY.
-CrstHt    amount that the weir’s opening is offset above the invert of inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting).
-Cd    weir discharge coefficient (for CFS if using US flow units or CMS if using metric flow units).
-Gated    YES if a flap gate prevents reverse flow, NO if not (default is NO).
-EC    number of end contractions for a TRANSVERSE or TRAPEZOIDAL weir (default is 0).
-Cd2    discharge coefficient for the triangular ends of a TRAPEZOIDAL weir (for CFS if using US flow units or CMS if using metric flow units) (default is the value of Cd).
-Sur    YES if the weir can surcharge (have an upstream water level higher than the height of the weir’s opening); NO if it cannot (default is YES).
-The following parameters apply only to ROADWAY weirs:
-Width    width of road lanes and shoulders for a ROADWAY weir (ft or m).
-Surf    type of road surface for a ROADWAY weir: PAVED or GRAVEL.
-
-Remarks:
-The geometry of a weir’s opening is described in the [XSECTIONS] section. The following shapes must be used with each type of weir:
-
-Weir Type    Cross-Section Shape
-Transverse    RECT_OPEN
-Sideflow    RECT_OPEN
-V-Notch    TRIANGULAR
-Trapezoidal    TRAPEZOIDAL
-Roadway    RECT_OPEN
-
-The ROADWAY weir is a broad crested rectangular weir used model roadway crossings usually in conjunction with culvert-type conduits. It uses the FHWA HDS-5 method to determine a discharge coefficient as a function of flow depth and roadway width and surface. If no roadway data are provided then the weir behaves as a TRANSVERSE weir with Cd as its discharge coefficient. Note that if roadway data are provided, then values for the other optional weir parameters (NO for Gated, 0 for EC, 0 for Cd2, and NO for Sur) must be entered even though they do not apply to ROADWAY weirs.
-
-
-
- 
-### Section: [OUTLETS]
-
-Purpose:
-Identifies each outlet flow control device of the drainage system. These are devices used to model outflows from storage units or flow diversions that have a user-defined relation between flow rate and water depth.
-
-Formats:
-Name Node1 Node2 Offset TABULAR/DEPTH Qcurve (Gated)
-Name Node1 Node2 Offset TABULAR/HEAD  Qcurve (Gated)
-Name Node1 Node2 Offset FUNCTIONAL/DEPTH C1 C2 (Gated)
-Name Node1 Node2 Offset FUNCTIONAL/HEAD C1 C2 (Gated)
-
-Parameters:
-Name    name assigned to outlet link.
-Node1    name of the outlet’s inlet node.
-Node2    name of the outlet’s outlet node.
-Offset    amount that the outlet is offset above the invert of its inlet node (ft or m, expressed as either a depth or as an elevation, depending on the LINK_OFFSETS option setting).
-Qcurve    name of the rating curve listed in the [CURVES] section that describes outflow rate (flow units) as a function of:
-    water depth above the offset elevation at the inlet node (ft or m) for a TABULAR/DEPTH outlet
-    head difference (ft or m) between the inlet and outflow nodes for a TABULAR/HEAD outlet.
-C1, C2    coefficient and exponent, respectively, of a power function that relates outflow (Q) to:
-    water depth (ft or m) above the offset elevation at the inlet node for a FUNCTIONAL/DEPTH outlet
-    head difference  (ft or m) between the inlet and outflow nodes for a FUNCTIONAL/HEAD outlet.
-(i.e.,  Q=C1H^C2 where H  is either depth or head).
-Gated    YES if a flap gate prevents reverse flow, NO if not (default is NO).
-
-### Section: [XSECTIONS]
-
-Purpose:
-Provides cross-section geometric data for conduit and regulator links of the drainage system.
-
-Formats:
-Link    Shape            Geom1 Geom2 Geom3 Geom4 (Barrels Culvert)
-Link    IRREGULAR    Tsect
-Link    STREET          Street
-
-Parameters:
-Link    name of a conduit, orifice, or weir.
-Shape    a cross-section shape (see Tables D-1 below or 3-1 for available shapes).
-Geom1    full height of the cross-section (ft or m).
-Geom2-4    auxiliary parameters (width, side slopes, etc.) as listed in Table D-1.
-Barrels    number of barrels (i.e., number of parallel pipes of equal size, slope, and roughness) associated with a conduit (default is 1).
-Culvert    code number from Table A.10 for the conduit’s inlet geometry if it is a culvert subject to possible inlet flow control (leave blank otherwise).
-Curve    name of a Shape Curve in the [CURVES] section that defines how cross-section width varies with depth.
-Tsect    name of an entry in the [TRANSECTS] section that describes the cross-section geometry of an irregular channel.
-Street    name of an entry in the [STREETS] section that describes the cross-section geometry of a street.
-
-Remarks:
-The standard conduit shapes and their geometric parameters are listed in the following table:
-
-
-Table D 2 Geometric parameters of conduit cross sections
-Shape    Geom1    Geom2    Geom3    Geom4
-CIRCULAR    Diameter            
-FORCE_MAIN    Diameter    Roughness1        
-FILLED_CIRCULAR2    Diameter    Sediment Depth        
-RECT_CLOSED     Full Height    Top Width        
-RECT_OPEN    Full Height    Top Width        
-TRAPEZOIDAL    Full Height    Base Width    Left  Slope3    Right Slope3
-TRIANGULAR    Full Height    Top Width        
-HORIZ_ELLIPSE    Full Height    Max. Width    Size Code4    
-VERT_ELLIPSE    Full Height    Max. Width    Size Code4    
-ARCH     Full Height    Max. Width    Size Code5    
-PARABOLIC    Full Height    Top Width        
-POWER    Full Height    Top Width    Exponent    
-RECT_TRIANGULAR     Full Height    Top Width    Triangle Height    
-RECT_ROUND    Full Height    Top Width    Bottom Radius    
-MODBASKETHANDLE    Full Height    Base Width    Top Radius6    
-EGG    Full Height            
-HORSESHOE    Full Height            
-GOTHIC    Full Height            
-CATENARY    Full Height            
-SEMIELLIPTICAL    Full Height            
-BASKETHANDLE    Full Height            
-SEMICIRCULAR    Full Height            
-CUSTOM    Full Height    Shape Curve        
-1C-factors are used when H-W is the FORCE_MAIN_EQUATION choice in the [OPTIONS] section while roughness heights (in inches or mm) are used for D-W.
- 2A circular conduit partially filled with sediment to a specified depth.
-3Slopes are horizontal run / vertical rise.
-4Size code of a standard shaped elliptical pipe as listed in Appendix A12. Leave blank (or 0) if the pipe has custom dimensions.
-5Size code of a standard arch pipe as listed in Appendix A13. Leave blank (or 0) if the pipe has custom dimensions).
-6Set to zero to use a standard modified baskethandle shape whose top radius is half the base width.
-The CUSTOM shape is a closed conduit whose width versus height is described by a user-supplied Shape Curve.
-An IRREGULAR cross-section is used to model an open channel whose geometry is described by a Transect object.
-A STREET cross-section is used to model street conduits and inlet flow capture (see the [INLETS] and [INLETS_USAGE] sections).
-The Culvert code number is used only for closed conduits acting as culverts that should be analyzed for inlet control conditions using the FHWA HDS-5 methodology.
- 
-### Section: [TRANSECTS]
-
-Purpose:
-Describes the cross-section geometry of natural channels or conduits with irregular shapes following the HEC-2 data format.
-
-Formats:
-NC  Nleft Nright  Nchanl
-X1  Name  Nsta Xleft Xright 0 0 0 Lfactor Wfactor Eoffset
-GR  Elev  Station  ...  Elev  Station
-
-Parameters:
-Nleft    Manning’s roughness coefficient (n) of right overbank portion of channel (use 0 if no change from previous NC line).
-Nright    Manning’s roughness coefficient (n) of right overbank portion of channel (use 0 if no change from previous NC line.
-Nchanl    Manning’s roughness coefficient (n) of main channel portion of channel (use 0 if no change from previous NC line.
-Name    name assigned to the transect.
-Nsta    number of stations across the cross-section’s width at which elevation data is supplied.
-Xleft    station position which ends the left overbank portion of the channel (ft or m).
-Xright    station position which begins the right overbank portion of the channel (ft or m).
-Lfactor    meander modifier that represents the ratio of the length of a meandering main channel to the length of the overbank area that surrounds it (use 0 if not applicable).
-Wfactor    factor by which distances between stations should be multiplied to increase (or decrease) the width of the channel (enter 0 if not applicable).
-Eoffset    amount to be added (or subtracted) from the elevation of each station (ft or m).
-Elev    elevation of the channel bottom at a cross-section station relative to some fixed reference (ft or m).
-Station    distance of a cross-section station from some fixed reference (ft or m).
-
-
-Remarks:
-Transect geometry is described as shown below, assuming that one is looking in a downstream direction:
- 
-
-The first line in this section must always be a NC line. After that, the NC line is only needed when a transect has different Manning’s n values than the previous one.
-The Manning’s n values on the NC line will supersede any roughness value entered for the conduit which uses the irregular cross-section.
-There should be one X1 line for each transect. Any number of GR lines may follow, and each GR line can have any number of Elevation-Station data pairs. (In HEC-2 the GR line is limited to 5 stations.)
-The station that defines the left overbank boundary on the X1 line must correspond to one of the station entries on the GR lines that follow. The same holds true for the right overbank boundary. If there is no match, a warning will be issued and the program will assume that no overbank area exists.
-The meander modifier is applied to all conduits that use this particular transect for their cross section. It assumes that the length supplied for these conduits is that of the longer main channel. SWMM will use the shorter overbank length in its calculations while increasing the main channel roughness to account for its longer length.
- 
-### Section: [STREETS]
-
-Purpose:
-Describes the cross-section geometry of conduits that represent streets.
-
-Format:
-Name Tcrown Hcurb Sx nRoad (a W)(Sides Tback Sback nBack)
-
-Parameters:
-Name     name assigned to the street cross-section
-Tcrown     distance from street’s curb to its crown (ft or m)
-Hcurb     curb height (ft or m)
-Sx     street cross slope (%)
-nRoad     Manning’s roughness coefficient (n) of the road surface
-a     gutter depression height (in or mm) (default = 0)
-W     depressed gutter width (ft or m) (default = 0)
-Sides     1 for single sided street or 2 for two-sided street (default = 2)
-Tback     street backing width (ft or m) (default = 0)
-Sback     street backing slope (%) (default = 0)
-nBack     street backing Manning’s roughness coefficient (n) (default = 0)
-
-Remarks:
- 
-
-If the street has no depressed gutter (a = 0) then the gutter width entry is ignored. If the street has no backing then the three backing parameters can be omitted.
-### Section: [INLETS]
-
-Purpose:
-Defines inlet structure designs used to capture street and channel flow that are sent to below ground sewers.
-
-Format:
-Name  GRATE/DROP_GRATE Length Width Type (Aopen Vsplash)
-Name  CURB/DROP_CURB Length Height (Throat)
-Name  SLOTTED Length Width
-Name  CUSTOM Dcurve/Rcurve
-
-Parameters:
-Name     name assigned to the inlet structure.
-Length     length of the inlet parallel to the street curb (ft or m).
-Width     width of a GRATE or SLOTTED inlet (ft or m).
-Height     height of a CURB opening inlet (ft or m).
-Type     type of GRATE used (see below).
-Aopen     fraction of a GENERIC grate’s area that is open.
-Vsplash     splash over velocity for a GENERIC grate (ft/s or m/s).
-Throat     the throat angle of a CURB opening inlet (HORIZONTAL, INCLINED or VERTICAL).
-Dcurve     name of a Diversion-type curve (captured flow v. approach flow) for a CUSTOM inlet.
-Rcurve     name of a Rating-type curve (captured flow v. water depth) for a CUSTOM inlet.
-
-Remarks:
-See Section 3.3.7 for a description of the different types of inlets that SWMM can model. 
-Use one line for each inlet design except for a combination inlet where one GRATE line describes its grated inlet and a second CURB line (with the same inlet name) describes its curb opening inlet.
-
-GRATE, CURB, and SLOTTED inlets are used with STREET conduits, DROP_GRATE and DROP_CURB inlets with open channels, and a CUSTOM inlet with any conduit.
-GRATE and DROP_GRATE  types can be any of the following:
-Grate Type    Sketch    Description
-P_BAR-50         Parallel bar grate with bar spacing 1⅞” on center 
-P_BAR-50X100         Parallel bar grate with bar spacing 1⅞” on center and ⅜” diameter lateral rods spaced at 4” on center
-P_BAR-30         Parallel bar grate with 1⅛” on center bar spacing
-CURVED_VANE         Curved vane grate with 3¼” longitudinal bar and 4¼” transverse bar spacing on center
-TILT_BAR-45         45 degree tilt bar grate with 2¼” longitudinal bar and 4” transverse bar spacing on center
-TILT_BAR-30         30 degree tilt bar grate with 3¼” and 4” on center longitudinal and lateral bar spacing respectively
-RETICULINE         "Honeycomb" pattern of lateral bars and longitudinal bearing bars
-GENERIC        A generic grate design.
-
- Only a GENERIC type grate requires that Aopen and Vsplash values be provided. The other standard grate types have predetermined values of these parameters. (Splash over velocity is the minimum velocity that will cause some water to shoot over the inlet thus reducing its capture efficiency).
- A CUSTOM inlet takes the name of either a Diversion curve or a Rating curve as its only parameter (see the [CURVES] section).  Diversion curves are best suited for on-grade inlets and Rating curves for on-sag inlets.
-
-
-Examples:
-; A 2-ft x 2-ft parallel bar grate
-InletType1  GRATE  2  2  P-BAR-30
-; A combination inlet
-InletType2  GRATE  2  2  CURVED_VANE
-InletType2  CURB   4  0.5  HORIZONTAL
-; A custom inlet using Curve1 as its capture curve
-InletType3  CUSTOM  Curve1
- 
-### Section: [INLET_USAGE]
-
-Purpose:
-Assigns inlet structures to specific street and open channel conduits.
-
-Format:
-Conduit Inlet Node (Number %Clogged Qmax aLocal wLocal Placement)
-
-Parameters:
-Conduit     name of a street or open channel conduit containing the inlet.
-Inlet     name of an inlet structure (from the [INLETS] section) to use.
-Node     name of the sewer node receiving flow captured by the inlet.
-Number     number of replicate inlets placed on each side of the street.
-%Clogged     degree to which inlet capacity is reduced due to clogging (%).
-Qmax     maximum flow that the inlet can capture (flow units).
-aLocal     height of local gutter depression (in or mm).
-wLocal     width of local gutter depression (ft or m).
-Placement     AUTOMATIC, ON_GRADE, or ON_SAG.
-
-Remarks:
-Only conduits with a STREET cross section can be assigned a curb and gutter inlet while drop inlets can only be assigned to conduits with a RECT_OPEN or TRAPEZOIDAL cross section.
-Only the first three parameters are required. The default number of inlets is 1 (for each side of a two-sided street) while the remaining parameters have default values of 0.
-A Qmax value of 0 indicates that the inlet has no flow restriction.
-The local gutter depression applies only over the length of the inlet unlike the continuous depression for a STREET cross section which exists over the full curb length.
-The default inlet placement is AUTOMATIC, meaning that the program uses the network topography to determine whether an inlet operates on-grade or on-sag. On-grade means the inlet is located on a continuous grade. On-sag means the inlet is located at a sag or sump point where all adjacent conduits slope towards the inlet leaving no place for water to flow except into the inlet.
-### Section: [LOSSES]
-
-Purpose:
-Specifies minor head loss coefficients, flap gates, and seepage rates for conduits.
-
-Format:
-Conduit  Kentry  Kexit  Kavg  (Flap  Seepage)
-
-Parameters:
-Conduit    name of a conduit.
-Kentry    minor head loss coefficient at the conduit’s entrance.
-Kexit    minor head loss coefficient at the conduit’s exit.
-Kavg    average minor head loss coefficient across the length of the conduit.
-Flap    YES if the conduit has a flap valve that prevents back flow, NO otherwise. (Default is NO).
-Seepage    Rate of seepage loss into the surrounding soil (in/hr or mm/hr). (Default is 0.)
-
-Remarks:
-Minor losses are only computed for the Dynamic Wave flow routing option (see the [OPTIONS] section). They are computed as Kv2/2g where K = minor loss coefficient, v = velocity, and g = acceleration of gravity. Entrance losses are based on the velocity at the entrance of the conduit, exit losses on the exit velocity, and average losses on the average velocity.
-Only enter data for conduits that actually have minor losses, flap valves, or seepage losses.
-
-
-
- 
-### Section: [CONTROLS]
-
-Purpose:
-Determines how pumps and regulators will be adjusted based on simulation time or conditions at specific nodes and links.
-
-Formats:
-Each control rule is a series of statements of the form:
-RULE    ruleID
-IF        condition_1
-AND    condition_2
-OR        condition_3
-AND    condition_4
-Etc.
-THEN    action_1
-AND    action_2
-Etc.
-ELSE    action_3
-AND    action_4
-Etc.
-PRIORITY value
-
-Parameters:
- ruleID            an ID label assigned to the rule.
-condition_n    a condition clause.
-action_n            an action clause.
-value            a priority value (e.g., a number from 1 to 5).
-
-Remarks:
-Please refer to Section C.3 for a complete description of the control rule format plus examples of different types of rule statements.
- 
-### Section: [POLLUTANTS]
-
-Purpose:
-Identifies the pollutants being analyzed.
-
-Format:
-Name Units Crain Cgw Cii Kd (Sflag CoPoll CoFract Cdwf Cinit)
-
-Parameters:
-Name    name assigned to a pollutant.
-Units    concentration units (MG/L for milligrams per liter, UG/L for micrograms per liter, or #/L for direct count per liter).
-Crain    concentration of the pollutant in rainfall (concentration units).
-Cgw    concentration of the pollutant in groundwater (concentration units).
-Cii    concentration of the pollutant in rainfall-dependent infiltration and inflow (concentration units).
-Kdecay    first-order decay coefficient (1/days).
-Sflag    YES if pollutant buildup occurs only when there is snow cover, NO otherwise (default is NO).
-CoPoll    name of a co-pollutant (default is no co-pollutant designated by a *).
-CoFract    fraction of the co-pollutant’s concentration (default is 0).
-Cdwf     pollutant concentration in dry weather flow (default is 0).
-Cinit     pollutant concentration throughout the conveyance system at the start of the simulation (default is 0).
-Remarks:
-FLOW  is a reserved word and cannot be used to name a pollutant.
-Parameters Sflag through Cinit can be omitted if they assume their default values. If there is no co-pollutant but non-default values for Cdwf or Cinit, then enter an asterisk (*) for the co-pollutant name.
-When pollutant X has a co-pollutant Y, it means that fraction CoFract of pollutant Y’s runoff concentration is added to pollutant X’s runoff concentration when wash off from a subcatchment is computed.
-The dry weather flow concentration can be overridden for any specific node of the conveyance system by editing the node’s Inflows property (see the [INFLOWS] section). 
-### Section: [LANDUSES]
-
-Purpose:
-Identifies the various categories of land uses within the drainage area. Each subcatchment area can be assigned a different mix of land uses. Each land use can be subjected to a different street sweeping schedule. Land uses are only used in conjunction with pollutant buildup and wash off.
-
-Format:
-Name  (SweepInterval  Availability  LastSweep)
-
-Parameters:
-Name            land use name.
-SweepInterval    days between street sweeping.
-Availability    fraction of pollutant buildup available for removal by street sweeping.
-LastSweep        days since last sweeping at the start of the simulation.
- 
-### Section: [COVERAGES]
-
-Purpose:
-Specifies the percentage of a subcatchment’s area that is covered by each category of land use.
-
-Format:
-    Subcat  Landuse  Percent  Landuse  Percent  . . .
-
-Parameters:
-Subcat    subcatchment name.
-Landuse    land use name.
-Percent    percent of the subcatchment’s area covered by the land use.
-
-Remarks:
-More than one pair of land use - percentage values can be entered per line. If more than one line is needed, then the subcatchment name must still be entered first on the succeeding lines.
-If a land use does not pertain to a subcatchment, then it does not have to be entered.
-If no land uses are associated with a subcatchment then no pollutants will appear in the runoff from the subcatchment.
-
-
-
- 
-### Section: [LOADINGS]
-
-Purpose:
-Specifies the pollutant buildup that exists on each subcatchment at the start of a simulation.
-
-Format:
-Subcat  Pollut  InitBuildup  Pollut  InitBuildup ...
-
-Parameters:
-Subcat            name of a subcatchment.
-Pollut            name of a pollutant.
-InitBuildup    initial buildup of the pollutant (lbs/acre or kg/hectare).
-
-Remarks:
-More than one pair of pollutant - buildup values can be entered per line. If more than one line is needed, then the subcatchment name must still be entered first on the succeeding lines.
-If an initial buildup is not specified for a pollutant, then its initial buildup is computed by applying the DRY_DAYS option (specified in the [OPTIONS] section) to the pollutant’s buildup function for each land use in the subcatchment.
-
-
- 
-### Section: [BUILDUP]
-
-Purpose:
-Specifies the rate at which pollutants build up over different land uses between rain events.
-
-Format:
-Landuse  Pollutant  FuncType  C1  C2  C3  PerUnit
-
-Parameters:
-Landuse        land use name.
-Pollutant    pollutant name.
-FuncType        buildup function type: ( POW / EXP / SAT / EXT ).
-C1,C2,C3        buildup function parameters (see Table D-2).
-PerUnit        AREA if buildup is per unit area, CURBLENGTH if per length of curb.
-
-Remarks:
-Buildup is measured in pounds (kilograms) per unit of area (or curb length) for pollutants whose concentration units are either mg/L or ug/L. If the concentration units are counts/L, then buildup is expressed as counts per unit of area (or curb length).
-
-Table D 3 Pollutant buildup functions
-Name    Function    Equation*
-POW    Power    Min (C1, C2*tC3)
-EXP    Exponential    C1*(1 – exp(-C2*t))
-SAT    Saturation    C1*t / (C3 + t)
-EXT    External    See below
-*t is antecedent dry days.
-
-For the EXT buildup function, C1 is the maximum possible buildup (mass per area or curb length), C2 is a scaling factor, and C3 is the name of a Time Series that contains buildup rates (as mass per area or curb length per day) as a function of time.
- 
-### Section: [WASHOFF]
-
-Purpose:
-Specifies the rate at which pollutants are washed off from different land uses during rain events.
-
-Format:
-Landuse  Pollutant  FuncType  C1  C2  SweepRmvl BmpRmvl
-
-Parameters:
-Landuse        land use name.
-Pollutant    pollutant name.
-FuncType        washoff function type: EXP / RC / EMC.
-C1, C2        washoff function coefficients(see Table D-3).
-SweepRmvl    street sweeping removal efficiency (percent).        
-BmpRmvl        BMP removal efficiency (percent).
-
-Remarks:
-Table D 4 Pollutant wash off functions
-Name    Function    Equation    Units
-EXP    Exponential    C1 (runoff)C2 (buildup)    Mass/hour
-RC    Rating Curve    C1 (runoff)C2    Mass/sec
-EMC    Event Mean
-Concentration    C1    Mass/Liter
-
-Each washoff function expresses its results in different units.
-For the Exponential function the runoff variable is expressed in catchment depth per unit of time (inches per hour or millimeters per hour), while for the Rating Curve function it is in whatever flow units were specified in the [OPTIONS] section of the input file (e.g., CFS, CMS, etc.).
-
-The buildup parameter in the Exponential function is the current total buildup over the subcatchment’s land use area in mass units. The units of C1 in the Exponential function are (in/hr) -C2 per hour (or (mm/hr) -C2 per hour). For the Rating Curve function, the units of C1 depend on the flow units employed. For the EMC (event mean concentration) function, C1 is always in concentration units.
-
-
- 
-### Section: [TREATMENT]
-
-Purpose:
-Specifies the degree of treatment received by pollutants at specific nodes of the drainage system.
-
-Format:
-Node  Pollut  Result = Func  
-
-Parameters:
-Node    Name of the node where treatment occurs.
-Pollut    Name of pollutant receiving treatment.
-Result    Result computed by treatment function. Choices are:
-C  (function computes effluent concentration)
-R  (function computes fractional removal).
-Func    mathematical function expressing treatment result in terms of pollutant concentrations, pollutant removals, and other standard variables (see below).
-
-Remarks:
-Treatment functions can be any well-formed mathematical expression involving:
-    inlet pollutant concentrations (use the pollutant name to represent a concentration)
-    removal of other pollutants (use R_ pre-pended to the pollutant name to represent removal)
-    process variables which include:
-FLOW     for flow rate into node (user’s flow units)
-DEPTH     for water depth above node invert (ft or m)
-AREA     for node surface area (ft2 or m2)
-DT         for routing time step (seconds)
-HRT     for hydraulic residence time (hours)
-
-Any of the following math functions can be used in a treatment function:
-    abs(x) for absolute value of x
-    sgn(x) which is +1 for x >= 0 or -1 otherwise
-    step(x) which is 0 for x <= 0 and 1 otherwise
-    sqrt(x) for the square root of x
-    log(x) for logarithm base e of x
-    log10(x) for logarithm base 10 of x
-    exp(x) for e raised to the x power
-    the standard trig functions (sin, cos, tan, and cot)
-    the inverse trig functions (asin, acos, atan, and acot)
-    the hyperbolic trig functions (sinh, cosh, tanh, and coth)
-along with the standard operators +, -, *, /, ^ (for exponentiation ) and any level of nested parentheses.
-
-Examples:
-; 1-st order decay of BOD
-Node23  BOD   C = BOD * exp(-0.05*HRT)
-
-; lead removal is 20% of TSS removal
-Node23  Lead  R = 0.2 * R_TSS     
-
-
-
-
- 
-### Section: [INFLOWS]
-
-Purpose:
-Specifies external hydrographs and pollutographs that enter the drainage system at specific nodes.
-
-Formats:
-Node FLOW   Tseries  (FLOW (1.0     Sfactor Base Pat)) 
-Node Pollut Tseries  (Type (Mfactor Sfactor Base Pat))                     
-
-Parameters:
-Node    name of the node where external inflow enters.
-Pollut    name of a pollutant.
-Tseries    name of a time series in the [TIMESERIES] section describing how external flow or pollutant loading varies with time.
-Type    CONCEN if pollutant inflow is described as a concentration, MASS if it is described as a mass flow rate (default is CONCEN). 
-Mfactor    the factor that converts the inflow’s mass flow rate units into the project’s mass units per second, where the project’s mass units are those specified for the pollutant in the [POLLUTANTS] section (default is 1.0 - see example below).
-Sfactor    a scaling factor that multiplies the recorded time series values (default is 1.0).
-Base    a constant baseline value added to the time series value (default is 0.0).
-Pat    name of an optional time pattern in the [PATTERNS] section used to adjust the baseline value on a periodic basis.
-
-Remarks:
-External inflows are represented by both a constant and time varying component as follows:
-Inflow = (Baseline value)*(Pattern factor) +
-(Scaling factor)*(Time series value)
-If an external inflow of a pollutant concentration is specified for a node, then there must also be an external inflow of FLOW provided for the same node, unless the node is an Outfall. In that case a pollutant can enter the system during periods when the outfall is submerged and reverse flow occurs. External pollutant mass inflows do not require a FLOW inflow.
-
-Examples:
-; NODE2 receives flow inflow from time series N2FLOW
-; and TSS concentration from time series N2TSS
-NODE2   FLOW  N2FLOW
-NODE2   TSS   N33TSS  CONCEN
-
-; NODE65 has a mass inflow of BOD from time series N65BOD
-; listed in lbs/hr (126 converts lbs/hr to mg/sec)
-NODE65  BOD  N65BOD  MASS  126
-
-; Flow inflow to Node N176 consists of the flow time series
-; FLOW_176 scaled at 0.5 plus a baseline flow of 12.7
-; adjusted by pattern FlowPat
-N176  FLOW  FLOW_176  FLOW  1.0  0.5  12.7  FlowPat 
-### Section: [DWF]
-
-Purpose:
-Specifies dry weather flow and its quality entering the drainage system at specific nodes.
-
-Format:
-Node  Type  Base  (Pat1  Pat2  Pat3  Pat4)
-
-Parameters:
-Node    name of a node where dry weather flow enters.
-Type    keyword FLOW for flow or a pollutant name for a quality constituent.
-Base    average baseline value for corresponding constituent  (flow or concentration units).
-Pat1,    
-Pat2,
-etc.    names of up to four time patterns appearing in the [PATTERNS] section.
-
-Remarks:
-The actual dry weather input will equal the product of the baseline value and any adjustment factors supplied by the specified patterns. (If not supplied, an adjustment factor defaults to 1.0.)
-The patterns can be any combination of monthly, daily, hourly and weekend hourly patterns, listed in any order. See the [PATTERNS] section for more details.
-
-
- 
-### Section: [RDII]
-
-Purpose:
-Specifies the parameters that describe rainfall-dependent infiltration and inflow (RDII) entering the drainage system at specific nodes.
-
-Format:
-    Node  UHgroup  SewerArea
-
-Parameters:
-Node    name of a node receiving RDII flow.
-UHgroup    name of an RDII unit hydrograph group appearing in the [HYDROGRAPHS] section.
-SewerArea    area of the sewershed that contributes RDII to the node (acres or hectares).
-
-
- 
-### Section: [HYDROGRAPHS]
-
-Purpose:
-Specifies the shapes of the triangular unit hydrographs that determine the amount of rainfall-dependent infiltration and inflow (RDII) entering the drainage system.
-
-Format:
-Name  Raingage
-Name  Month  SHORT/MEDIUM/LONG  R  T  K (Dmax Drec D0)
-
-Remarks:
-Name    name assigned to a unit hydrograph group.
-Raingage    name of the rain gage used by the unit hydrograph group.
-Month    month of the year (e.g., JAN, FEB, etc. or ALL for all months).
-R    response ratio for the unit hydrograph.
-T    time to peak (hours) for the unit hydrograph.
-K    recession limb ratio for the unit hydrograph.
-Dmax    maximum initial abstraction depth available (in rain depth units).
-Drec    initial abstraction recovery rate (in rain depth units per day)
-D0    initial abstraction depth already filled at the start of the simulation (in rain depth units).
-
-Remarks:
-For each group of unit hydrographs, use one line to specify its rain gage followed by as many lines as are needed to define each unit hydrograph used by the group throughout the year. Three separate unit hydrographs, that represent the short-term, medium-term, and long-term RDII responses, can be defined for each month (or all months taken together). Months not listed are assumed to have no RDII.
-The response ratio (R) is the fraction of a unit of rainfall depth that becomes RDII. The sum of the ratios for a set of three hydrographs does not have to equal 1.0.
-The recession limb ratio (K) is the ratio of the duration of the hydrograph’s recession limb to the time to peak (T) making the hydrograph time base equal to T*(1+K) hours. The area under each unit hydrograph is 1 inch (or mm).
-
-The optional initial abstraction parameters determine how much rainfall is lost at the start of a storm to interception and depression storage. If not supplied then the default is no initial abstraction.
-
-Lines are processed in the order they appear, and an entry for ALL assigns its values to every month of the year. An ALL entry therefore overrides any month-specific values entered on earlier lines (e.g., if entries appear in the order JAN through SEP, ALL, OCT, NOV, DEC, the ALL entry replaces the values entered for JAN through SEP, leaving only OCT, NOV, and DEC with their own values). Whenever parameters for the same month and response type are supplied more than once, the values entered last are used and WARNING 13 is written to the status report.
-
-Example:
-;  All three unit hydrographs in this group have the same shapes except those in July,
-;  which have only a short- and medium-term response and a different shape.
-UH101  RG1
-UH101  ALL SHORT  0.033 1.0  2.0
-UH101  ALL MEDIUM 0.300 3.0  2.0
-UH101  ALL LONG   0.033 10.0 2.0
-UH101  JUL SHORT  0.033 0.5  2.0
-UH101  JUL MEDIUM 0.011 2.0  2.0
- 
-### Section: [CURVES]
-
-Purpose:
-Describes a relationship between two variables in tabular format. 
-
-Format:
-Name  Type
-Name  X-value  Y-value  ...
-
-Parameters:
-Name    name assigned to the curve.
-Type    the type of curve being defined:
-STORAGE / SHAPE / DIVERSION / TIDAL / PUMP1 / PUMP2 / PUMP3 / PUMP4 / PUMP5 / RATING / CONTROL / WEIR.
-X-value    an X (independent variable) value.
-Y-value    the Y (dependent variable) value corresponding to X.
-
-Remarks:
-Each curve should have its name and type on the first line with its data points entered on subsequent lines.
-Multiple pairs of x-y values can appear on a line. If more than one line is needed, repeat the curve's name on subsequent lines.
-X-values must be entered in increasing order.
-Choices for curve type have the following meanings (flows are expressed in the user’s choice of flow units set in the [OPTIONS] section):
-STORAGE    surface area in ft2 (m2) versus depth in ft (m) for a storage unit node
-SHAPE    width versus depth for a custom closed cross-section, both normalized with respect to full depth
-DIVERSION    diverted outflow versus total inflow for a flow divider node or a Custom inlet
-TIDAL    water surface elevation in ft (m) versus hour of the day for an outfall node
-PUMP1    pump outflow versus increment of inlet node volume in ft3 (m3)
-PUMP2    pump outflow versus increment of inlet node depth in ft (m)
-PUMP3    pump outflow versus head difference between outlet and inlet nodes in ft (m) that has decreasing flow with increasing head
-PUMP4    pump outflow versus continuous inlet node depth in ft (m)
-PUMP5    pump outflow versus head difference between outlet and inlet nodes in ft (m) that has decreasing flow with increasing head
-RATING    flow versus head in ft (m) for an Outlet link or a Custom inlet
-CONTROL    control setting for a pump or flow regulator versus a controller variable (such as a node water level) in a modulated control; flow adjustment setting versus head for an LID unit’s underdrain
-WEIR    discharge coefficient for flow in CFS (CMS) versus head in ft (m)
-
-Remarks:
-See Section 3.2 for illustrations of the different types of pump curves.
-
-Examples:
-; Storage curve (x = depth, y = surface area)
-AC1  STORAGE
-AC1  0  1000  2  2000  4  3500  6  4200  8  5000
-
-; Type 1 pump curve (x = inlet wet well volume, y = flow)
-PC1  PUMP1
-PC1  100  5  300  10  500  20
-
-; Type 5 pump curve (x = pump head, y = pump flow)
-PC2  PUMP5
-PC2  0  4
-PC2  4  2
-PC2  6  0
-
-
- 
-### Section: [TIMESERIES]
-
-Purpose:
-Describes how a quantity varies over time.
-
-Formats:
-Name  ( Date )  Hour  Value  ...
-Name  Time  Value  ...
-Name  FILE  Fname
-
-Parameters:
-Name    name assigned to the time series.
-Date    date in Month/Day/Year format (e.g., June 15, 2001 would be 6/15/2001).
-Hour    24-hour military time (e.g., 8:40 pm would be 20:40) relative to the last date specified (or to midnight of the starting date of the simulation if no previous date was specified).
-Time    hours since the start of the simulation, expressed as a decimal number or as hours:minutes (where hours can be greater than 24).
-Value    a value corresponding to the specified date and time.
-Fname    the name of a file in which the time series data are stored
-
-Remarks:
-There are two options for supplying the data for a time series:
-    directly within this input file section as described by the first two formats
-    through an external data file named with the third format.
-When direct data entry is used, multiple date-time-value or time-value entries can appear on a line. If more than one line is needed, the table's name must be repeated as the first entry on subsequent lines.
-When an external file is used, each line in the file must use the same formats listed above, except that only one date-time-value (or time-value) entry is allowed per line. Any line that begins with a semicolon is considered a comment line and is ignored. Blank lines are also permitted. Enclose the external file name in double quotes if it contains spaces and include its full path if it resides in a different directory than the SWMM input file. 
-
-There are two options for describing the occurrence time of time series data:  
-    as calendar date plus time of day (which requires that at least one date, at the start of the series, be entered)  
-    as elapsed hours since the start of the simulation.
-For the first method, dates need only be entered at points in time when a new day occurs.
-For rainfall time series, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage which utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values.
-
-Examples:
-; Hourly rainfall time series with dates specified using
-; one data point per line to emphasize when dates change
-TS1 6-15-2001 7:00  0.1
-TS1           8:00  0.2
-TS1           9:00  0.05
-TS1           10:00 0
-TS1 6-21-2001 4:00  0.2
-TS2           5:00  0
-TS2           14:00 0.1
-TS2           15:00 0
-
-;Inflow hydrograph - time relative to start of simulation
-HY1  0  0  1.25 100  2:30 150  3.0 120  4.5 0
-HY1  32:10 0  34.0 57  35.33 85  48.67 24  50 0
-
-
-
-      
- 
-### Section: [PATTERNS]
-
-Purpose:
-Specifies time patterns of dry weather flow or quality in the form of adjustment factors applied as multipliers to baseline values.
-
-Format:
-Name  MONTHLY        Factor1  Factor2  ...  Factor12
-Name  DAILY        Factor1  Factor2  ...  Factor7
-Name  HOURLY        Factor1  Factor2  ...  Factor24
-Name  WEEKEND        Factor1  Factor2  ...  Factor24
-
-Parameters:
-Name    name used to identify the pattern.
-Factor1,
-Factor2,
-etc.    multiplier values.
-
-Remarks:
-The MONTHLY format is used to set monthly pattern factors for dry weather flow constituents.
-The DAILY format is used to set dry weather pattern factors for each day of the week, where Sunday is day 1.
-The HOURLY format is used to set dry weather factors for each hour of the day starting from midnight. If these factors are different for weekend days than for weekday days then the WEEKEND format can be used to specify hourly adjustment factors just for weekends.
-More than one line can be used to enter a pattern’s factors by repeating the pattern’s name (but not the pattern type) at the beginning of each additional line.
-The pattern factors are applied as multipliers to any baseline dry weather flows or quality concentrations supplied in the [DWF] section. 
-
-Examples:
-; Day of week adjustment factors
-D1  DAILY  0.5  1.0  1.0  1.0  1.0  1.0  0.5
-D2  DAILY  0.8  0.9  1.0  1.1  1.0  0.9  0.8
-; Hourly adjustment factors 
-H1 HOURLY  0.5 0.6 0.7 0.8 0.8 0.9
-H1         1.1 1.2 1.3 1.5 1.1 1.0
-H1         0.9 0.8 0.7 0.6 0.5 0.5
-H1         0.5 0.5 0.5 0.5 0.5 0.5  
-
-## D.3 Map Data Section
-
-SWMM’s graphical user interface (GUI) can display a schematic map of the drainage area being analyzed. This map displays subcatchments as polygons, nodes as circles, links as polylines, and rain gages as bitmap symbols. In addition it can display text labels and a backdrop image, such as a street map. The GUI has tools for drawing, editing, moving, and displaying these map elements.
-
- The map’s coordinate data are stored in the format described below. Normally these data are simply appended to the SWMM input file by the GUI so users do not have to concern themselves with it. However it is sometimes more convenient to import map data from some other source, such as a CAD or GIS file, rather than drawing a map from scratch using the GUI. In this case the data can be added to the SWMM project file using any text editor or spreadsheet program. SWMM does not provide any automated facility for converting coordinate data from other file formats into the SWMM map data format. 
-
-SWMM's map data are organized into the following seven sections:
-[MAP]    X,Y coordinates of the map’s bounding rectangle
-[POLYGONS]    X,Y coordinates for each vertex of subcatchment polygons
-[COORDINATES]    X,Y coordinates for nodes
-[VERTICES]    X,Y coordinates for each interior vertex of polyline links
-[LABELS]    X,Y coordinates and text of labels
-[SYMBOLS]    X,Y coordinates for rain gages
-[BACKDROP]    X,Y coordinates of the bounding rectangle and file name of the backdrop image.
-Figure D-2 displays a sample map and Figure D-3 the data that describes it. Note that only one link, 3, has interior vertices which give it a curved shape. Also observe that this map’s coordinate system has no units, so that the positions of its objects may not necessarily coincide to their real-world locations. 
-
- 
-*Figure D-2 Example study area map*
-
-*Figure D-3 Data for example study area map*
-A detailed description of each map data section will now be given. Remember that map data are only used as a visualization aid for SWMM’s GUI and they play no role in any of the runoff or routing computations. Map data are not needed for running the command line version of SWMM.
----
-
-### Section: [MAP]
-
-Purpose:
-    Provides dimensions and distance units for the map.
-
-Formats:
-DIMENSIONS    X1 Y1 X2 Y2
-UNITS           FEET / METERS / DEGREES / NONE
-
-Parameters:
-X1    lower-left X coordinate of full map extent
-Y1    lower-left  Y coordinate of full map extent
-X2    upper-right X coordinate of full map extent
-Y2    upper-right Y coordinate of full map extent
----
-
-### Section: [COORDINATES]
-
-Purpose:
-    Assigns X,Y coordinates to drainage system nodes.
-
-Format:
-    Node  Xcoord  Ycoord
-
-Parameters:
-Node    name of node.
-Xcoord    horizontal coordinate relative to origin in lower left of map.
-Ycoord    vertical coordinate relative to origin in lower left of map.
----
-
-
-
-
-
-### Section: [VERTICES]
-
-Purpose:
-    Assigns X,Y coordinates to interior vertex points of curved drainage system links.
-
-Format:
-    Link  Xcoord  Ycoord
-
-Parameters:
-Link    name of link.
-Xcoord    horizontal coordinate of vertex relative to origin in lower left of map.
-Ycoord    vertical coordinate of vertex relative to origin in lower left of map.
-
-Remarks:
-Include a separate line for each interior vertex of the link, ordered from the inlet node to the outlet node.
-
-Straight-line links have no interior vertices and therefore are not listed in this section.
----
-
-### Section: [POLYGONS]
-
-Purpose:
-Assigns X,Y coordinates to  vertex points of polygons that define a subcatchment boundary.
-
-Format:
-    Subcat  Xcoord  Ycoord
-
-Parameters:
-Subcat    name of subcatchment.
-Xcoord    horizontal coordinate of vertex relative to origin in lower left of map.
-Ycoord    vertical coordinate of vertex relative to origin in lower left of map.
-
-Remarks:
-Include a separate line for each vertex of the subcatchment polygon, ordered in a consistent clockwise or counter-clockwise sequence.
----
-
-
-
-### Section: [SYMBOLS]
-
-Purpose:
-    Assigns X,Y coordinates to rain gage symbols.
-
-Format:
-    Gage  Xcoord  Ycoord
-
-Remarks:
-Gage    name of rain gage.
-Xcoord    horizontal coordinate relative to origin in lower left of map.
-Ycoord    vertical coordinate relative to origin in lower left of map.
----
-
-### Section: [LABELS]
-
-Purpose:
-    Assigns X,Y coordinates to user-defined map labels.
-
-Format:
-    Xcoord  Ycoord  Label (Anchor  Font  Size  Bold  Italic)
-
-Parameters:
-Xcoord    horizontal coordinate relative to origin in lower left of map.
-Ycoord    vertical coordinate relative to origin in lower left of map.
-Label    text of label surrounded by double quotes.
-Anchor    name of node or subcatchment that anchors the label on zoom-ins (use an empty pair of double quotes if there is no anchor).
-Font    name of label’s font (surround by double quotes if the font name includes spaces).
-Size    font size in points.
-Bold    YES for bold font, NO otherwise.
-Italic    YES for italic font, NO otherwise.
-
-Remarks:
-Use of the anchor node feature will prevent the label from moving outside the viewing area when the map is zoomed in on. 
-
-If no font information is provided then a default font is used to draw the label.
----
-### Section: [BACKDROP]
-
-Purpose:
-    Specifies file name and coordinates of map’s backdrop image.
-
-Formats:
-FILE           Fname
-DIMENSIONS    X1 Y1 X2 Y2
-
-Parameters:
-Fname    name of file containing backdrop image
-X1    lower-left X coordinate of backdrop image
-Y1    lower-left  Y coordinate of backdrop image
-X2    upper-right X coordinate of backdrop image
-Y2    upper-right Y coordinate of backdrop image
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/manuals/user/manual/AppendixE.md b/docs/manuals/user/manual/AppendixE.md
deleted file mode 100644
index 0b944111a..000000000
--- a/docs/manuals/user/manual/AppendixE.md
+++ /dev/null
@@ -1,357 +0,0 @@
-@page user_manual_appendix_e APPENDIX E - ERROR AND WARNING MESSAGES
-
-@tableofcontents
-
-ERROR 101:     memory allocation error.
-There is not enough physical memory in the computer to analyze the study area.
-
-ERROR 103:    cannot solve KW equations for Link xxx.
-The internal solver for Kinematic Wave routing failed to converge for the specified link at some stage of the simulation.
-
-ERROR 105:     cannot open ODE solver.
-The system could not open its Ordinary Differential Equation solver.
-
-ERROR 107:     cannot compute a valid time step.
-A valid time step for runoff or flow routing calculations (i.e., a number greater than 0) could not be computed at some stage of the simulation.
-
-ERROR 108:    ambiguous outlet ID name for Subcatchment xxx.
-The name of the element identified as the outlet of a subcatchment belongs to both a node and a subcatchment in the project's data base.
-
-ERROR 109:     invalid parameter values for Aquifer xxx.
-The properties entered for an aquifer object were either invalid numbers or were inconsistent with one another (e.g., the soil field capacity was higher than the porosity).
-
-ERROR 110:     ground elevation is below water table for Subcatchment xxx.
-The ground elevation assigned to a subcatchment’s groundwater parameters cannot be below the initial water table elevation of the aquifer object used by the subcatchment.
-
-ERROR 111:     invalid length for Conduit xxx.
-Conduits cannot have zero or negative lengths.
-
-ERROR 112:     elevation drop exceeds length for Conduit xxx.
-The elevation drop across the ends of a conduit cannot be greater than the conduit's length. Check for errors in the length and in both the invert elevations and offsets at the conduit's upstream and downstream nodes.
-
-
-ERROR 113:     invalid roughness for Conduit xxx.
-Conduits cannot have zero or negative roughness values.
-
-ERROR 114:     invalid number of barrels for Conduit xxx.
-Conduits must consist of one or more barrels.
-
-ERROR 115:     adverse slope for Conduit xxx.
-Under Steady or Kinematic Wave routing, all conduits must have positive slopes.  This can usually be corrected by reversing the inlet and outlet nodes of the conduit (i.e., right click on the conduit and select Reverse from the popup menu that appears). Adverse slopes are permitted under Dynamic Wave routing.
-
-ERROR 117:     no cross-section defined for Link xxx.
-Cross-section geometry was never defined for the specified link.
-
-ERROR 119:     invalid cross-section for Link xxx.
-Either an invalid shape or invalid set of dimensions was specified for a link's cross-section.
-
-ERROR 121:     missing or invalid pump curve assigned to Pump xxx.
-Either no pump curve or an invalid type of curve was specified for a pump.
-
-ERROR 122:     startup depth not higher than shutoff depth for Pump xxx.
-Automatic startup for a pump always occurs at a wet well water level that is higher than its automatic shutoff level.
-
-ERROR 131:     the following links form cyclic loops in the drainage system.
-The Steady and Kinematic Wave flow routing methods cannot be applied to systems where a cyclic loop exists (i.e., a directed path along a set of links that begins and ends at the same node). Most often the cyclic nature of the loop can be eliminated by reversing the direction of one of its links (i.e., switching the inlet and outlet nodes of the link). The names of the links that form the loop will be listed following this message.
-
-ERROR 133:     Node xxx has more than one outlet link.
-Under Steady and Kinematic Wave flow routing, a junction node can have only a single outlet link. 
-
-
-
-ERROR 134:     Node xxx has illegal DUMMY link connections.
-Only a single conduit with a DUMMY cross-section or Ideal-type pump can be directed out of a node; a node with an outgoing Dummy conduit or Ideal pump cannot have all of its incoming links be Dummy conduits and Ideal pumps; a Dummy conduit cannot have its upstream end connected to a storage node. 
-
-ERROR 135:     Divider xxx does not have two outlet links.
-Flow divider nodes must have two outlet links connected to them.
-
-ERROR 136:     Divider xxx has invalid diversion link.
-The link specified as being the one carrying the diverted flow from a flow divider node was defined with a different inlet node.
-
-ERROR 137:     Weir Divider xxx has invalid parameters.
-The parameters of a Weir-type divider node either are non-positive numbers or are inconsistent (i.e., the value of the discharge coefficient times the weir height raised to the 3/2 power must be greater than the minimum flow parameter).
-
-ERROR 138:     Node xxx has initial depth greater than maximum depth.
-Self-explanatory.
-
-ERROR 139:     Regulator xxx is the outlet of a non-storage node.
-Under Steady or Kinematic Wave flow routing, orifices, weirs, and outlet links can only be used as outflow links from storage nodes. 
-
-ERROR 140:     Storage node xxx has negative volume at full depth.
-The storage unit’s Shape data (surface area versus depth) is producing a negative volume at full depth. This can occur when a storage node's surface area curve slopes downward at its highest depth which is below the node's full depth.
-
-ERROR 141:     Outfall xxx has more than 1 inlet link or an outlet link.
-An outfall node is only permitted to have one link attached to it.
-
-ERROR 143:     Regulator xxx has invalid cross-section shape.
-An orifice must have either a CIRCULAR or RECT_CLOSED shape, while a weir must have either a RECT_OPEN, TRAPEZOIDAL, or TRIANGULAR shape.
-
-
-
-ERROR 145:     Drainage system has no acceptable outlet nodes.
-Under Dynamic Wave flow routing, there must be at least one node designated as an outfall.
-ERROR 151:     a Unit Hydrograph in set xxx has invalid time base.
-The time base of a Unit Hydrograph cannot be negative and if positive, must not be less than the recording interval for its rain gage.
-
-ERROR 153:     a Unit Hydrograph in set xxx has invalid response ratios.
-The response ratios for a set of Unit Hydrographs (the short-, medium-, and long-term response hydrographs) must be between 0 and 1.0 and cannot add up to a value greater than 1.0
-
-ERROR 155:     invalid sewer area for RDII at Node xxx.
-The sewer area contributing RDII inflow to a node cannot be a negative number.
-
-ERROR 156:     ambiguous station ID for Rain Gage xxx.
-If two Rain Gages use files for their data sources and have the same Station IDs then they must also use the same data files. 
-
-ERROR 157:     inconsistent rainfall format for Rain Gage xxx.
-If two or more rain gages use the same Time Series for their rainfall data then they must all use the same data format (intensity, volume, or cumulative volume).
-
-ERROR 158:     time series for Rain Gage xxx is also used by another object.
-A rainfall Time Series associated with a Rain Gage cannot be used by another object that is not also a Rain Gage. 
-
-ERROR 159:     recording interval greater than time series interval for Rain Gage xxx.
-The recording time interval specified for the rain gage is greater than the smallest time interval between values in the Time Series used by the gage.
-
-ERROR 161:     cyclic dependency in treatment functions at Node xxx.
-An example would be where the removal of pollutant 1 is defined as a function of the removal of pollutant 2 while the removal of pollutant 2 is defined as a function of the removal of pollutant 1.
-
-ERROR 171:     Curve xxx has invalid or out of sequence data.
-The X-values of a curve object must be entered in increasing order.
-
-ERROR 173:     Time Series xxx has its data out of sequence.
-The time (or date/time) values of a time series must be entered in sequential order.
-ERROR 181:     invalid Snow Melt Climatology parameters.
-The ATI Weight or Negative Melt Ratio parameters are not between 0 and 1 or the site latitude is not between -60 and +60 degrees.
-
-ERROR 182:     invalid parameters for Snow Pack xxx.
-A snow pack’s minimum melt coefficient is greater than its maximum coefficient; the fractions of free water capacity or impervious plowable area are not between 0 and 1; or the snow removal fractions sum to more than 1.0.
-
-ERROR 183:     no type specified for LID xxx.
-A named LID control has layers defined for it but its LID type was never specified.
-
-ERROR 184:        missing layer for LID xxx.
-A required design layer is missing for the specified LID control.
-
-ERROR 185:        invalid parameter value for LID xxx.
-An invalid value was supplied for an LID control's design parameter.
-
-ERROR 187:        LID area exceeds total area for Subcatchment xxx.
-The area of the LID controls placed within the subcatchment is greater than that of the subcatchment itself.
-
-ERROR 188:    LID capture area exceeds total impervious area for Subcatchment xxx.
-The amount of impervious area assigned to be treated by LID controls in the subcatchment exceeds the total amount of impervious area available.
-
-ERROR 191:     simulation start date comes after ending date.
-Self-explanatory.
-
-ERROR 193:     report start date comes after ending date.
-Self-explanatory.
-
-ERROR 195:     reporting time step is less than routing time step.
-Self-explanatory.
- 
-
-ERROR 200:     one or more errors in input file.
-This message appears when one or more input file parsing errors (the 200-series errors) occur.
-
-ERROR 201:     too many characters in input line. 
-A line in the input file cannot exceed 1024 characters.
-
-ERROR 203:     too few items at line n of input file.
-Not enough data items were supplied on a line of the input file.
-
-ERROR 205:     invalid keyword at line n of input file.
-An unrecognized keyword was encountered when parsing a line of the input file.
-
-ERROR 207:     duplicate ID name at line n of input file.
-An ID name used for an object was already assigned to an object of the same category.
-
-ERROR 209:     undefined object xxx at line n of input file.
-A reference was made to an object that was never defined. An example would be if node 123 were designated as the outlet point of a subcatchment, yet no such node was ever defined in the study area.
-
-ERROR 211:     invalid number xxx at line n of input file.
-Either a string value was encountered where a numerical value was expected or an invalid number (e.g., a negative value) was supplied.
-
-ERROR 213:     invalid date/time xxx at line n of input file.
-An invalid format for a date or time was encountered. Dates must be entered as month/day/year and times as either decimal hours or as hour:minute:second.
-
-ERROR 217:     control rule clause out of sequence at line n of input file.
-Errors of this nature can occur when the format for writing control rules is not followed correctly (see Section C.3).
-
-ERROR 219:     data provided for unidentified transect at line n of input file.
-A GR line with Station-Elevation data was encountered in the [TRANSECTS] section of the input file after an NC line but before any X1 line that contains the transect’s ID name.
-
-
-ERROR 221:     transect station out of sequence at line n of input file.
-The station distances specified for the transect of an irregular cross-section must be in increasing numerical order starting from the left bank.
-
-ERROR 223:     Transect xxx has too few stations.
-A transect for an irregular cross-section must have at least 2 stations.
-
-ERROR 225:     Transect xxx has too many stations.
-A transect cannot have more than 1500 stations defined for it.
-
-ERROR 227:     Transect xxx has no Manning's N.
-No Manning’s N was specified for a transect (i.e., there was no NC line in the [TRANSECTS] section of the input file.
-
-ERROR 229:     Transect xxx has invalid overbank locations.
-The distance values specified for either the left or right overbank locations of a transect do not match any of the distances listed for the transect's stations.
-
-ERROR 231:     Transect xxx has no depth.
-All of the stations for a transect were assigned the same elevation.
-
-ERROR 233:     invalid math expression at line n of input file.
-A math expression used for a treatment function, a groundwater flow function or a control rule condition clause is either not correctly formed or contains undefined variables or math functions.
-
-ERROR 235:     invalid infiltration parameters.
-Examples are a Horton maximum infiltration rate lower than the minimum rate or a Green-Ampt initial moisture deficit greater than 1.
-
-ERROR 301:     files share same names.
-The input, report, and binary output files specified on the command line cannot have the same names.
-
-ERROR 303:     cannot open input file.
-The input file either does not exist or cannot be opened (e.g., it might be in use by another program).
-
-
-
-ERROR 305:     cannot open report file.
-The report file cannot be opened (e.g., it might reside in a directory to which the user does not have write privileges).
-
-ERROR 307:     cannot open binary results file.
-The binary output file cannot be opened (e.g., it might reside in a directory to which the user does not have write privileges).
-
-ERROR 308:     amount of output produced will exceed maximum file size.
-For the 32-bit command line version of the program, the maximum size of the binary results file is limited to 2 GB.
-
-ERROR 309:     error writing to binary results file.
-There was an error in trying to write results to the binary output file (e.g., the disk might be full or the file size exceeds the limit imposed by the operating system).
-
-ERROR 311:     error reading from binary results file.
-The command line version of SWMM could not read results saved to the binary output file when writing results to the report file.
-
-ERROR 313:     cannot open scratch rainfall interface file.
-SWMM could not open the temporary file it uses to collate data together from external rainfall files.
-
-ERROR 315:     cannot open rainfall interface file xxx.
-SWMM could not open the specified rainfall interface file, possibly because it does not exist or because the user does not have write privileges to its directory.
-
-ERROR 317:     cannot open rainfall data file xxx.
-An external rainfall data file could not be opened, most likely because it does not exist.
-
-ERROR 318:     date out of sequence in rainfall data file xxx.
-An external user-prepared rainfall data file must have its entries appear in chronological order. The first out-of-order entry will be listed.
-
-ERROR 319:     unknown format for rainfall data file.
-SWMM could not recognize the format used for a designated rainfall data file.
-
-ERROR 320:     invalid format for rainfall interface file.
-SWMM was trying to read data from a designated rainfall interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file).
-
-ERROR 321:     no data in rainfall interface file for gage xxx.
-This message occurs when a project wants to use a previously saved rainfall interface file, but cannot find any data for one of its rain gages in the interface file. It can also occur if the gage uses data from a user-prepared rainfall file and the station id entered for the gage cannot be found in the file.
-
-ERROR 323:     cannot open runoff interface file xxx.
-A runoff interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory.
-
-ERROR 325:     incompatible data found in runoff interface file.
-SWMM was trying to read data from a designated runoff interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file).
-
-ERROR 327:     attempting to read beyond end of runoff interface file.
-This error can occur when a previously saved runoff interface file is being used in a simulation with a longer duration than the one that created the interface file.
-
-ERROR 329:     error in reading from runoff interface file.
-A format error was encountered while trying to read data from a previously saved runoff interface file.
-
-ERROR 331:     cannot open hot start interface file xxx.
-A hot start interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory.
-
-ERROR 333:     incompatible data found in hot start interface file.
-SWMM was trying to read data from a designated hot start interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file).
-
-
-
-ERROR 335:     error in reading from hot start interface file.
-A format error was encountered while trying to read data from a previously saved hot start interface file.
-
-ERROR 336:     no climate file specified for evaporation and/or wind speed.
-This error occurs when the user specifies that evaporation or wind speed data will be read from an external climate file, but no name is supplied for the file.
-ERROR 337:     cannot open climate file xxx.
-An external climate data file could not be opened, most likely because it does not exist.
-
-ERROR 338:     error in reading from climate file xxx.
-SWMM was trying to read data from an external climate file with the wrong format.
-
-ERROR 339:     attempt to read beyond end of climate file xxx.
-The specified external climate does not include data for the period of time being simulated.
-
-ERROR 341:     cannot open scratch RDII interface file.
-SWMM could not open the temporary file it uses to store RDII flow data.
-
-ERROR 343:     cannot open RDII interface file xxx.
-An RDII interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory.
-
-ERROR 345:     invalid format for RDII interface file.
-SWMM was trying to read data from a designated RDII interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file).
-
-ERROR 351:     cannot open routing interface file xxx.
-A routing interface file could not be opened, possibly because it does not exist or because the user does not have write privileges to its directory.
-
-ERROR 353:     invalid format for routing interface file xxx.
-SWMM was trying to read data from a designated routing interface file with the wrong format (i.e., it may have been created for some other project or actually be some other type of file).
-
-ERROR 355:     mismatched names in routing interface file xxx.
-The names of pollutants found in a designated routing interface file do not match the names used in the current project.
-
-ERROR 357:     inflows and outflows interface files have same name.
-In cases where a run uses one routing interface file to provide inflows for a set of locations and another to save outflow results, the two files cannot both have the same name.
-ERROR 361:     could not open external file used for Time Series xxx. 
-The external file used to provide data for the named time series could not be opened, most likely because it does not exist.
-
-ERROR 363:     invalid data in external file used for used for Time Series xxx. 
-The external file used to provide data for the named time series has one or more lines with the wrong format.
-
-Warning Codes
-
-WARNING 01:     wet weather time step reduced to recording interval for Rain Gage xxx.
-The wet weather time step was automatically reduced so that no period with rainfall would be skipped during a simulation.
-
-WARNING 02:     maximum depth increased for Node xxx.
-The maximum depth for the node was automatically increased to match the top of the highest connecting conduit.
-
-WARNING 03:     negative offset ignored for Link xxx.
-The link’s stipulated offset was below the connecting node's invert so its actual offset was set to 0.
-
-WARNING 04:     minimum elevation drop used for Conduit xxx.
-The elevation drop between the end nodes of the conduit was below 0.001 ft (0.00035 m) so the latter value was used instead to calculate its slope.
-
-WARNING 05:     minimum slope used for Conduit xxx.
-The conduit's computed slope was below the user-specified Minimum Conduit Slope so the latter value was used instead.
-
-
-
-WARNING 06:     dry weather time step increased to wet weather time step.
-The user-specified time step for computing runoff during dry weather periods was lower than that set for wet weather periods and was automatically increased to the wet weather value. 
-
-WARNING 07:     routing time step reduced to wet weather time step.
-The user-specified time step for flow routing was larger than the wet weather runoff time step and was automatically reduced to the runoff time step to prevent loss of accuracy. 
-
-WARNING 08:     elevation drop exceeds length for Conduit xxx.
-The elevation drop across the ends of a conduit exceeds its length. The program computes the conduit's slope as the elevation drop divided by the length instead of using the more accurate right triangle method. The user should check for errors in the length and in both the invert elevations and offsets at the conduit's upstream and downstream nodes.
-
-WARNING 09:     time series interval greater than recording interval for Rain Gage xxx.
-The smallest time interval between entries in the precipitation time series used by the rain gage is greater than the recording time interval specified for the gage. If this was not actually intended then what appear to be continuous periods of rainfall in the time series will instead be read with time gaps in between them.
-
-WARNING 10a:         crest elevation is below downstream invert for regulator Link xxx. 
-For Kinematic Wave or Steady Flow routing, the height of the opening on an orifice, weir, or outlet at a storage node is below the invert elevation of its downstream node. Users should check to see if the regulator's offset height or the downstream node's invert elevation is in error.
-
-WARNING 10b:     crest elevation raised to downstream invert for regulator Link xxx. 
-For Dynamic Wave routing, the height of the opening on an orifice, weir or outlet will be raised to the invert elevation of its downstream node if necessary.
-
-WARNING 11:     non-matching attributes in Control Rule xxx. 
-The premise of a control is comparing two different types of attributes to one another (for example, conduit flow and junction water depth).
-
-
-WARNING 12:     inlet removed due to unsupported shape for Conduit xxx. 
-Curb and gutter inlets can only be placed in conduits with a Street shaped cross-section while drop inlets can only be placed in open rectangular and trapezoidal conduits.
-
-
-
diff --git a/docs/manuals/user/manual/Chapter1.md b/docs/manuals/user/manual/Chapter1.md
deleted file mode 100644
index ec35777f3..000000000
--- a/docs/manuals/user/manual/Chapter1.md
+++ /dev/null
@@ -1,151 +0,0 @@
-@page user_manual_introductions CHAPTER 1 – INTRODUCTION
-
-@tableofcontents
-
-## 1.1 What is SWMM?
-
-The EPA Storm Water Management Model (SWMM) is a dynamic rainfall-runoff simulation model used for single event or long-term (continuous) simulation of runoff quantity and quality from primarily urban areas. The runoff component of SWMM operates on a collection of subcatchment areas that receive precipitation and generate runoff and pollutant loads. The routing portion of SWMM transports this runoff through a system of pipes, channels, storage/treatment devices, pumps, and regulators. SWMM tracks the quantity and quality of runoff generated within each subcatchment, and the flow rate, flow depth, and quality of water in each pipe and channel during a simulation period comprised of multiple time steps. 
-
-![A schematic diagram showing the generation and fate of urban wet weather flows.](figures/figure1_1_urban_sewershed.png "Figure 1-1. A schematic diagram showing the generation and fate of urban wet weather flows."){#user_manual_figure1_1}
-
-SWMM was first released in 1971 and has undergone several major upgrades since then. It continues to be widely used throughout the world for planning, analysis and design related to storm water runoff, combined sewers, sanitary sewers, and other drainage systems in urban areas, with many applications in non-urban areas as well. The current edition, Version 5, is a complete re-write of previous releases.
-
-Running under Windows, SWMM 5 provides an integrated environment for editing study area input data, running hydrologic, hydraulic and water quality simulations, and viewing the results in a variety of formats. These include color-coded drainage area and conveyance system maps, time series graphs and tables, profile plots, and statistical frequency analyses.
-
-**OpenSWMM 6.0** represents a major architectural overhaul of the engine, re-implemented in C++20 with a clean plugin-extensible design. It introduces the `openswmm` Python package, which provides first-class programmatic access to all simulation capabilities. See [Chapter 13](@ref user_manual_chapter_13) for a full description of the new engine and Python API.
-
-## 1.2 Modeling Capabilities
-
-SWMM accounts for various hydrologic processes that produce runoff from land surfaces. These include:
-
-- time-varying rainfall  
-- evaporation of standing surface water  
-- snow accumulation and melting  
-- rainfall interception from depression storage  
-- infiltration of rainfall into unsaturated soil layers  
-- percolation of infiltrated water into groundwater layers  
-- interflow between groundwater and the drainage system  
-- nonlinear reservoir routing of overland flow
-- rainfall-dependent infiltration and inflow (RDII) for sanitary sewersheds
-- capture and retention of rainfall/runoff with various types of low impact development (LID) practices.
- 
-Spatial variability in all of these processes is achieved by dividing a study area into a collection of smaller, homogeneous subcatchment areas, each containing its own fraction of pervious and impervious subareas. Overland flow can be routed between subareas, between subcatchments, or between entry points of a drainage system. 
-
-SWMM also contains a flexible set of hydraulic modeling capabilities used to route runoff and external inflows through a drainage system network of pipes, channels, storage/treatment units and diversion structures. These include the ability to: 
-
-- handle networks of unlimited size  
-- use a wide variety of standard closed and open conduit shapes as well as natural channels  
-- model special elements such as storage/treatment units, curb and gutter inlets, culverts, flow dividers, pumps, weirs, and orifices  
-- apply external flows and water quality inputs from surface runoff, groundwater interflow, rainfall-dependent infiltration and inflow, dry weather- sanitary flow, and user-defined inflows  
-- utilize either kinematic wave or full dynamic wave flow routing methods  
-- model various flow regimes, such as backwater, surcharging, reverse flow, and surface ponding  
-- apply user-defined dynamic control rules to simulate the operation of pumps, orifice openings, and weir crest levels.
- 
-In addition to modeling the generation and transport of runoff flows, SWMM can also estimate the production of pollutant loads associated with this runoff. The following processes can be modeled for any number of user-defined water quality constituents: 
-
-- dry-weather pollutant buildup over different land uses  
-- pollutant washoff from specific land uses during storm events  
-- direct contribution of rainfall deposition  
-- reduction in dry-weather buildup due to street cleaning  
-- reduction in washoff load due to BMPs  
-- entry of dry weather sanitary flows and user-specified external inflows at any point in the drainage system  
-- routing of water quality constituents through the drainage system  
-- reduction in constituent concentration through treatment in storage units or by natural processes in pipes and channels.   
-
-## 1.3 Typical Applications of SWMM
-
-Since its inception, SWMM has been used in thousands of sewer and stormwater studies throughout the world. Typical applications include:
-
-- design and sizing of drainage system components for flood control  
-- sizing of detention facilities and their appurtenances for flood control and water quality protection
-- flood plain mapping of natural channel systems
-- designing control strategies for minimizing combined sewer overflows
-- evaluating the impact of rainfall-dependent infiltration and inflow on sanitary sewer overflows
-- generating non-point source pollutant loadings for waste load allocation studies
-- evaluating the effectiveness of BMPs for reducing wet weather pollutant loadings.
-
-## 1.4    Installing EPA SWMM
-
-EPA SWMM 5.3 runs on both 32- and 64-bit versions of Microsoft Windows. It is distributed as a single file named swmm52#(x86)_setup.exe for the 32-bit edition or swmm52#(x64)_setup.exe for the 64-bit edition (where # is the current release number which as of this writing is 0) that contains a self-extracting setup program. To install EPA SWMM:
-    
-1. Select the Search icon from the Windows Taskbar and enter the word Run.
-
-2. In the Run dialog that appears click the Browse button to locate the SWMM setup file on your computer.
-
-3. Click the OK button type to begin the setup process.
-
-The setup program will ask you to choose a folder (directory) where the SWMM program files will be placed. After the files are installed your Start Menu will have a new item named EPA SWMM 5.2.# where # is the current release number. To launch SWMM, select this item off of the Start Menu, and then select SWMM 5.2 from the submenu that appears. (The name of the executable file that runs SWMM under Windows is epaswmm5.exe.)
-
-A user’s personal settings for running SWMM are stored in a folder named EPASWMM under the user’s Application Data directory (e.g., Users\\AppData\Roaming\EPASWMM ). If you need to save these settings to a different location, you can install a shortcut to SWMM 5 on the desktop whose target entry includes the full path name of the SWMM 5 executable followed by /s <userfolder>, where <userfolder> is the name of the folder where the personal settings will be stored. An example might be:
-
-“c:\Program Files\EPA SWMM 5.2\epaswmm5.exe” /s “My Folders\SWMM5\”.
-
-Several example data sets have been included with the installation package to help users become familiar with the program. They are placed in a sub-folder named EPA SWMM Projects\Sample Projects in the user’s Documents folder. Each example consists of an .INP file that holds the project’s data along with a .TXT file that describes the system being modeled. 
-
-To remove EPA SWMM from your computer, do the following:
-
-1. Select Settings from the Windows Start menu.
-
-2. Select Apps from the Settings page.
-
-3. Select EPA SWMM 5.2.# from the list of programs that appears.
-
-4. Click the Uninstall button.
-
-## 1.5    Steps in Using SWMM
-
-One typically carries out the following steps when using EPA SWMM to model a study area: 
-
-1. Specify a default set of options and object properties to use (see Section 5.4).
-
-2. Draw a network representation of the physical components of the study area (see Section 6.2).
-
-3. Edit the properties of the objects that make up the system (see Section 6.4).
-
-4. Select a set of analysis options (see Section 8.1).
-
-5. Run a simulation (see Section 8.4).
-
-6. View the results of the simulation (see Chapter 9).  
- 
-For building larger systems from scratch it might be more convenient to replace Step 2 by collecting study area data from various sources, such as CAD drawings or GIS files, and transferring these data into a SWMM input file whose format is described in Appendix D of this manual.
-
-## 1.6 About This Manual
-
-[Chapter 2](@ref user_manual_chapter_2) presents a short tutorial to help get started using EPA SWMM. It shows how to add objects to a SWMM project, how to edit the properties of these objects, how to run a single event simulation for both hydrology and water quality, and how to run a long-term continuous simulation.
-
-[Chapter 3](@ref user_manual_chapter_3) provides background material on how SWMM models stormwater runoff within a drainage area. It discusses the behavior of the physical components that comprise a stormwater drainage area and collection system as well as how additional modeling information, such as rainfall quantity, dry weather sanitary inflows, and operational control, are handled. It also provides an overview of how the numerical simulation of system hydrology, hydraulics and water quality behavior is carried out.
-
-[Chapter 4](@ref user_manual_chapter_4) shows how the EPA SWMM graphical user interface is organized. It describes the functions of the various menu options and toolbar buttons, and how the three main windows – the Study Area Map, the Browser panel, and the Property Editor—are used. 
-
-[Chapter 5](@ref user_manual_chapter_5) discusses the project files that store all of the information contained in a SWMM model of a drainage system. It shows how to create, open, and save these files as well as how to set default project options. It also discusses how to register calibration data that are used to compare simulation results against actual measurements.
-
-[Chapter 6](@ref user_manual_chapter_6) describes how one goes about building a network model of a drainage system with SWMM. It shows how to create the various physical objects (subcatchment areas, drainage pipes and channels, pumps, weirs, storage units, etc.) that make up a system, how to edit the properties of these objects, and how to describe the way that externally imposed inflows, boundary conditions and operational controls change over time.
-
-[Chapter 7](@ref user_manual_chapter_7) explains how to use the study area map that provides a graphical view of the system being modeled. It shows how to view different design and computed variables in color-coded fashion on the map, how to re-scale, zoom, and pan the map, how to locate objects by name on the map, how to utilize a backdrop image, and what options are available to customize the appearance of the map.
-
-[Chapter 8](@ref user_manual_chapter_8) shows how to run a simulation of a SWMM model. It describes the options that control how the analysis is made and offers some troubleshooting tips to use when examining simulation results.
-
-[Chapter 9](@ref user_manual_chapter_9) discusses the various ways in which the results of an analysis can be viewed. These include different views of the study area map, various kinds of graphs and tables, and several different types of special reports. 
-
-[Chapter 10](@ref user_manual_chapter_10) explains how to print and copy the results discussed in Chapter 9. 
-
-[Chapter 11](@ref user_manual_chapter_11) describes how EPA SWMM can use different types of interface files to make simulations runs more efficient.
-
-[Chapter 12](@ref user_manual_chapter_12) describes how add-in tools can be registered and share data with SWMM. These tools are external applications launched from SWMM’s graphical user interface that can extend its capabilities.
-
-[Chapter 13](@ref user_manual_chapter_13) introduces the OpenSWMM Engine v6 programmatic C API, which allows models to be built, run, and queried entirely through code without requiring an input file. It covers the engine lifecycle, building a network, callbacks, hot start files, Python bindings, and integration with CMake.
-
-The manual also contains several appendixes:
-
-[Appendix A](@ref user_manual_appendix_a) -    provides several useful tables of parameter values, including a table of units of expression for all design and computed quantities.
-
-[Appendix B](@ref user_manual_appendix_b) -    lists the editable properties of all visual objects that can be displayed on the study area map and be selected for editing using point and click.
-
-[Appendix C](@ref user_manual_appendix_c) -    describes the specialized editors available for setting the properties of non-visual objects.
-
-[Appendix D](@ref user_manual_appendix_d) -    provides instructions for running the command line version of SWMM and includes a detailed description of the format of a project file.
-
-[Appendix E](@ref user_manual_appendix_e) -    lists all of the error messages and their meaning that SWMM can produce.
- 
-
diff --git a/docs/manuals/user/manual/Chapter10.md b/docs/manuals/user/manual/Chapter10.md
deleted file mode 100644
index 8091689cd..000000000
--- a/docs/manuals/user/manual/Chapter10.md
+++ /dev/null
@@ -1,70 +0,0 @@
-@page user_manual_chapter_10 CHAPTER 10 - PRINTING AND COPYING
-
-@tableofcontents
-
-This chapter describes how to print, copy to the Windows clipboard, or copy to file the contents of the currently active window in the SWMM workspace. This can include the study area map, a graph, a table, or a report.
-
-Selecting a Printer
-
-To select a printer from among your installed Windows printers and set its properties:
-    Select File >> Page Setup from the Main Menu.
-    Click the Printer button on the Page Setup dialog that appears (see below).
-    Select a printer from the choices available in the combo box in the Print Setup dialog that appears.
-    Click the Properties button to select the appropriate printer properties (which vary with choice of printer).
-    Click OK on each dialog to accept your selections.
-
-
- 
-
-Setting the Page Format
-
-To format the printed page:
-    Select File >> Page Setup from the main menu.
-    Use the Margins page of the Page Setup dialog form that appears (see below) to:
-    Select a printer.
-    Select the paper orientation (Portrait or Landscape).
-    Set left, right, top, and bottom margins.
-    Use the Headers/Footers page of the dialog box (see below) to:
-    Supply the text for a header that will appear on each page.
-    Indicate whether the header should be printed or not and how its text should be aligned.
-    Supply the text for a footer that will appear on each page.
-    Indicate whether the footer should be printed or not and how its text should be aligned.
-    Indicate whether pages should be numbered.
-    Click OK to accept your choices.
-
- 
-Print Preview
-
-To preview a printout select File >> Print Preview from the Main Menu. A Preview form will appear which shows how each page being printed will appear. While in preview mode, the left mouse button will re-center and zoom in on the image and the right mouse button will re-center and zoom out.
-
-Printing the Current View
-
-To print the contents of the current window being viewed in the SWMM workspace, either select File >> Print from the Main Menu or click   on the Main Toolbar. The following views can be printed:
-    Study Area Map (at the current zoom level)
-    Status Report.
-    Summary report (for the current table being viewed)
-    Graphs (Time Series, Profile, and Scatter plots)
-    Tabular Reports
-    Statistical Reports.
-
-Copying to the Clipboard or to a File
-
-SWMM can copy the text and graphics of the current window being viewed to the Windows clipboard or to a file. Views that can be copied in this fashion include the Study Area Map, summary report tables, graphs, time series tables, and statistical reports. To copy the current view to the clipboard or to file: 
-    If the current view is a time series table, select the cells of the table to copy by dragging the mouse over them or copy the entire table by selecting Edit >> Select All from the Main Menu.  
-    Select Edit >> Copy To from the Main Menu or click the   button on the Main Toolbar.  
-    Select choices from the Copy dialog that appears (see below) and click the OK button.
-    If copying to file, enter the name of the file in the Save As dialog that appears and click OK.  
- 
-
-Use the Copy dialog as follows to define how you want your data copied and to where:
-    Select a destination for the material being copied (Clipboard or File)
-    Select a format to copy in:
-    Bitmap (graphics only)
-    Metafile (graphics only)
-    Data (text, selected cells in a table, or data used to construct a graph)
-    Click OK to accept your selections or Cancel to cancel the copy request.
-
-The bitmap format copies the individual pixels of a graphic. The metafile format copies the instructions used to create the graphic and is more suitable for pasting into word processing documents where the graphic can be re-scaled without losing resolution. When data is copied, it can be pasted directly into a spreadsheet program to create customized tables or charts.
-
-
-
diff --git a/docs/manuals/user/manual/Chapter11.md b/docs/manuals/user/manual/Chapter11.md
deleted file mode 100644
index 9bab2ac27..000000000
--- a/docs/manuals/user/manual/Chapter11.md
+++ /dev/null
@@ -1,231 +0,0 @@
-@page user_manual_chapter_11 CHAPTER 11 - FILES USED BY SWMM
-
-@tableofcontents
-
-This section describes the various files that SWMM can utilize. They include: the project file, the report and output files, rainfall files, the climate file, calibration data files, time series files, and interface files. The only file required to run SWMM is the project file; the others are optional.
-
-Project Files
-
-A SWMM project file is a plain text file that contains all of the data used to describe a study area and the options used to analyze it. The file is organized into sections, where each section generally corresponds to a particular category of object used by SWMM. The contents of the file can be viewed from within SWMM while it is open by selecting Project >> Details from the Main Menu. An existing project file can be opened by selecting File >> Open from the Main Menu and be saved by selecting File >> Save (or File >> Save As).
-
-Normally a SWMM user would not edit the project file directly, since SWMM's graphical user interface can add, delete, or modify a project's data and control settings. However, for large projects where data currently reside in other electronic formats, such as CAD or GIS files, it may be more expeditious to extract data from these sources and save it to a formatted project file before running SWMM. The format of the project file is described in detail in Appendix D of this manual.
-
-After a project file is saved to disk, a settings file will automatically be saved with it. This file has the same name as the project file except that its extension is .ini (e.g., if the project file were named project1.inp then its settings file would have the name project1.ini). It contains various settings used by SWMM’s graphical user interface, such as map display options, legend colors and intervals, object default values, and calibration file information. Users should not edit this file. A SWMM project will still load and run even if the settings file is missing.
-
-Report and Output Files
-
-The report file is a plain text file created after every SWMM run that contains the contents of both the Status Report and all of the tables included in the Summary Results report. Refer to Sections 9.1 and 9.2 to review their contents.
-
-The output file is a binary file that contains the numerical results from a successful SWMM run. This file is used by SWMM’s user interface to interactively create time series plots and tables, profile plots, and statistical analyses of a simulation's results.
-
-Whenever a successfully run project is either saved or closed, the report and output files are saved with the same name as the project file, but with extensions of .rpt and .out.  This will happen automatically if the program preference Prompt to Save Results is turned off (see Section 4.9). Otherwise the user is asked if the current results should be saved or not. If results are saved then the next time the project is opened, the results from these files will automatically be available for viewing.
-
-Rainfall Files
-
-SWMM’s rain gage objects can utilize rainfall data stored in external rainfall files. The program currently recognizes the following formats for storing such data:
-    Hourly and fifteen minute precipitation data from over 5,500 reporting stations retrieved using NOAA’s National Centers for Environmental Information (NCEI) Climate Data Online service (www.ncdc.noaa.gov/cdo-web) (space-delimited text format only).
-    The older DS-3240 and related formats used for hourly precipitation by NCEI.
-    The older DS-3260 and related formats used for fifteen minute precipitation by NCEI. 
-    HLY03 and HLY21 formats for hourly rainfall at Canadian stations, available from Environment Canada at www.climate.weather.gc.ca.
-    FIF21 format for fifteen minute rainfall at Canadian stations, also available online from Environment Canada.
-    a standard user-prepared format where each line of the file contains the station ID, year, month, day, hour, minute, and non-zero precipitation reading, all separated by one or more spaces.
-
-When requesting data from NCEI’s online service, be sure to specify the TEXT format option,   make sure that the data flags are included, and, for 15-minute data, select the QPCP option and not the QGAG one.
-
-An excerpt from a sample user-prepared Rainfall file is as follows:
-STA01  2004  6  12  00  00  0.12
-STA01  2004  6  12  01  00  0.04
-STA01  2004  6  22  16  00  0.07
-This format can also accept multiple stations within the same file.
-When a rain gage is designated as receiving its rainfall data from a standard user-prepared format, the following properties must be supplied for it: the name of the recording station referenced in the file, the rainfall type (e.g., intensity or volume), the recording time interval, and rainfall depth units. For the other file types these properties are defined by their respective file format and are automatically recognized by SWMM.
-
-Climate Files
-
-SWMM can use an external climate file that contains daily air temperature, evaporation, and wind speed data. The program currently recognizes the following formats:
-    Global Historical Climatology Network - Daily (GHCN-D) files (TEXT output format) available from NOAA's National Climatic Data Center (NCDC) Climate Data Online service at www.ncdc.noaa.gov/cdo-web.
-    Older NCDC DS-3200 or DS-3210 files.
-    Canadian climate files available from Environment Canada at www.climate.weather.gc.ca.
-    A user-prepared climate file where each line contains a recording station name, the year, month, day, maximum temperature, minimum temperature, and optionally, evaporation rate, and wind speed. If no data are available for any of these items on a given date, then an asterisk should be entered as its value.
-When a climate file has days with missing values, SWMM will use the value from the most recent previous day with a recorded value. 
-
-     For a user-prepared climate file, the data must be in the same units as the project being analyzed. For US units, temperature is in degrees F, evaporation is in inches/day, and wind speed is in miles/hour. For metric units, temperature is in degrees C, evaporation is in mm/day, and wind speed is in km/hour.
-
-Calibration Files
-
-Calibration files contain measurements of variables at one or more locations that can be compared with simulated values in Time Series Plots. Separate files can be used for each of the following:
-    Subcatchment Runoff
-    Subcatchment Groundwater Flow
-    Subcatchment Groundwater Elevation
-    Subcatchment Snow Pack Depth
-    Subcatchment Pollutant Washoff
-    Node Depth
-    Node Lateral Inflow
-    Node Flooding
-    Node Water Quality
-    Link Flow
-    Link Velocity
-    Link Depth
-Calibration files are registered to a project by selecting Project >> Calibration Data from the main menu (see Section 5.7). 
-
-The format of the file is as follows:
-    The name of the first object with calibration data is entered on a single line.
-    Subsequent lines contain the following recorded measurements for the object:
-    measurement date (month/day/year, e.g., 6/21/2004) or number of whole days since the start of the simulation
-    measurement time (hours:minutes) on the measurement date or relative to the number of elapsed days
-    measurement value (for pollutants, a value is required for each pollutant).
-    Follow the same sequence for any additional objects.
-An excerpt from an example calibration file is shown below. It contains flow values for two conduits: 1030 and 1602. Note that a semicolon can be used to begin a comment. In this example, elapsed time rather than the actual measurement date was used.
-
-
-
-
-
-
-
-
-
-;Flows for Selected Conduits    
-;Conduit  Days    Time  Flow
-;-----------------------------
- 1030            
-            0     0:15  0
-            0     0:30  0
-            0     0:45  23.88
-            0     1:00  94.58
-            0     1:15  115.37
- 1602            
-            0     0:15  5.76
-            0     0:30  38.51
-            0     1:00  67.93
-            0     1:15  68.01
-
-
-
-Time Series Files
-
-Time series files are external text files that contain data for SWMM's time series objects. Examples of time series data include rainfall, evaporation, inflows to nodes of the drainage system, and water stage at outfall boundary nodes. The file must be created and edited outside of SWMM, using a text editor or spreadsheet program. A time series file can be linked to a specific time series object using SWMM's Time Series Editor (see Appendix C.23). 
-
-The format of a time series file consists of one time series value per line. Comment lines can be inserted anywhere in the file as long as they begin with a semicolon. Time series values can either be in date / time / value format or in time / value format, where each entry is separated by one or more spaces or tab characters. For the date / time / value format, dates are entered as month/day/year (e.g., 7/21/2004) and times as 24-hour military time (e.g., 8:30 pm is 20:30). After the first date, additional dates need only be entered whenever a new day occurs. For the time / value format, time can either be decimal hours or military time since the start of a simulation (e.g., 2 days, 4 hours and 20 minutes can be entered as either 52.333 or 52:20). An example of a time series file is shown below:
-
-
-
-
-
-
-;Rainfall Data for Gage G1
-07/01/2003  00:00 0.00000
-            00:15 0.03200
-            00:30 0.04800
-            00:45 0.02400
-            01:00 0.0100
-07/06/2003  14:30 0.05100
-            14:45 0.04800
-            15:00 0.03000
-            18:15 0.01000
-               18:30 0.00800
-
-
-     In earlier releases of SWMM 5, a time series file was required to have two header lines of descriptive text at the start of the file that did not have to begin with the semicolon comment character. These files can still be used as long as they are modified by inserting a semicolon at the front of the first two lines. 
-     When preparing rainfall time series files, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage which utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values.
-
-Interface Files
-
-SWMM can use several different kinds of interface files that contain either externally imposed inputs (e.g., rainfall or RDII hydrographs) or the results of previously run analyses (e.g., runoff or routing results). These files can help speed up simulations, simplify comparisons of different loading scenarios, and allow large study areas to be broken up into smaller areas that can be analyzed individually. The different types of interface files that are currently available include:
-    rainfall interface file
-    runoff interface file
-    hot start file
-    RDII interface file
-    routing interface files
-Consult Section 8.1 for instructions on how to specify interface files for use as input and/or output in a simulation.
-
-Rainfall and Runoff Files
-
-The rainfall and runoff interface files are binary files created internally by SWMM that can be saved and reused from one analysis to the next.
-
-The rainfall interface file collates a series of separate rain gage files into a single rainfall data file. Normally a temporary file of this type is created for every SWMM analysis that uses external rainfall data files and is then deleted after the analysis is completed. However, if the same rainfall data are being used with many different analyses, requesting SWMM to save the rainfall interface file after the first run and then reusing this file in subsequent runs can save computation time.
-
-     The rainfall interface file should not be confused with a rainfall data file. The latter is an external text file that provides rainfall time series data for a single rain gage. The former is a binary file created internally by SWMM that processes all of the rainfall data files used by a project.
-
-The runoff interface file can be used to save the runoff results generated from a simulation run. If runoff is not affected in future runs, the user can request that SWMM use this interface file to supply runoff results without having to repeat the runoff calculations again.
-
-Hot Start Files
-
-Hot start files are binary files created by SWMM that contain the full hydrologic, hydraulic and water quality state of the study area at the end of a run. The following information is saved to the file:
-    the ponded depth and its water quality for each subcatchment
-    the pollutant mass buildup on each subcatchment
-    the infiltration state of each subcatchment
-    the conditions of any snowpack on each subcatchment
-    the unsaturated zone moisture content, water table elevation, and groundwater outflow for each subcatchment that has a groundwater zone defined for it
-    the water depth, lateral inflow, and water quality at each node of the system
-    the flow rate, water depth, control setting and water quality in each link of the system.
-The hydrologic state of any LID units is not saved. The hot start file saved after a run can be used to define the initial conditions for a subsequent run.
-
-Hot start files can be used to avoid the initial numerical instabilities that sometimes occur under Dynamic Wave routing. For this purpose they are typically generated by imposing a constant set of base flows (for a natural channel network) or set of dry weather sanitary flows (for a sewer network) over some startup period of time. The resulting hot start file from this run is then used to initialize a subsequent run where the inflows of real interest are imposed.
-
-It is also possible to both use and save a hot start file in a single run, starting off the run with one file and saving the ending results to another. The resulting file can then serve as the initial conditions for a subsequent run if need be. This technique can be used to divide up extremely long continuous simulations into more manageable pieces.
-
-Instructions to save and/or use a hot start file can be issued when editing the Interface Files options available in the Project Browser (see Section 8.1, Setting Simulation Options). One can also use the File >> Export >> Hot Start File Main Menu command to save the results of a current run at any particular time period to a hot start file. However, in this case only the results for nodes, links and groundwater elevation will be saved.
-
-RDII Files
-
-The RDII interface file contains a time series of rainfall-dependent infiltration and inflow flows for a specified set of drainage system nodes. This file can be generated from a previous SWMM run when Unit Hydrographs and nodal RDII inflow data have been defined for the project, or it can be created outside of SWMM using some other source of RDII data (e.g., through measurements or output from a different computer program). RDII files generated by SWMM are saved in a binary format. RDII files created outside of SWMM are text files with the same format used for routing interface files discussed below, where Flow is the only variable contained in the file.
-
-Routing Files
-
-A routing interface file stores a time series of flows and pollutant concentrations that are discharged from the outfall nodes of drainage system model. This file can serve as the source of inflow to another drainage system model that is connected at the outfalls of the first system. A Combine utility is available on the File menu that will combine pairs of routing interface files into a single interface file. This allows very large systems to be broken into smaller sub-systems that can be analyzed separately and linked together through the routing interface file. Figure 11.1 below illustrates this concept.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Figure 11 1  Combining routing interface files
-
-A single SWMM run can utilize an outflows routing file to save results generated at a system's outfalls, an inflows routing file to supply hydrograph and pollutograph inflows at selected nodes, or both. 
-
-RDII / Routing File Format
-
-RDII interface files and routing interface files have the same text format:
-    the first line contains the keyword "SWMM5" (without the quotes)
-    a line of text that describes the file (can be blank)
-    the time step used for all inflow records (integer seconds)
-    the number of variables stored in the file, where the first variable must always be flow rate
-    the name and units of each variable (one per line), where flow rate is the first variable listed and is always named FLOW
-    the number of nodes with recorded inflow data
-    the name of each node (one per line)
-    a line of text that provides column headings for the data to follow (can be blank)
-    for each node at each time step, a line with:
-    the name of the node
-    the date (year, month, and day separated by spaces)
-    the time of day (hours, minutes, and seconds separated by spaces)
-    the flow rate followed by the concentration of each quality constituent
-Time periods with no values at any node can be skipped. An excerpt from an RDII / routing interface file is shown below.
-
-
-SWMM5
-Example File
-300
-1
-FLOW CFS
-2
-N1
-N2
-Node Year Mon Day Hr Min Sec Flow
-N1   2002 04  01  00 20  00  0.000000
-N2   2002 04  01  00 20  00  0.002549
-N1   2002 04  01  00 25  00  0.000000
-N2   2002 04  01  00 25  00  0.002549
-
-
diff --git a/docs/manuals/user/manual/Chapter12.md b/docs/manuals/user/manual/Chapter12.md
deleted file mode 100644
index 6334697ed..000000000
--- a/docs/manuals/user/manual/Chapter12.md
+++ /dev/null
@@ -1,66 +0,0 @@
-@page user_manual_chapter_12 CHAPTER 12 - USING ADD-IN TOOLS
-
-@tableofcontents
-
-SWMM 5 has the ability to launch external applications from its graphical user interface that can extend its capabilities. This section describes how such tools can be registered and share data with SWMM 5.
-
-What Are Add-In Tools
-
-Add-in tools are third party applications that users can add to the Tools menu of the main SWMM menu bar and be launched while SWMM is still running. SWMM can interact with these applications to a limited degree by exchanging data through its pre-defined files (see Chapter 11) or through the Windows clipboard. Add-in tools can provide additional modeling capabilities to what SWMM already offers. Some examples of useful add-ins might include:
-    a tool that performs a statistical analysis of long-term rainfall data prior to adding it to a SWMM rain gage,
-    an external spreadsheet program that would facilitate the editing of a SWMM data set,
-    a unit hydrograph estimator program that would derive the R-T-K parameters for a set of  RDII unit hydrographs which could then be copied and pasted directly into SWMM’s Unit Hydrograph Editor,
-    a post-processor program that uses SWMM’s hydraulic results to compute suspended solids removal through a storage unit,
-    a third-party dynamic flow routing program used as a substitute for SWMM’s own internal procedure.
-
-The screenshot below shows what the Tools menu might look like after several add-in tools (an Excel Editor and a Climate Adjustment tool) have been registered with it. The Configure Tools option is used to add, delete, or modify add-in tools. The options below this are the individual tools that have been made available (by this particular user) and can be launched by selecting them from the menu.
- 
-
-Configuring Add-In Tools
-
-To configure one’s personal collection of add-in tools, select Configure Tools from the Tools menu. This will bring up the Tool Options dialog as shown below. The dialog lists the currently available tools and has command buttons for adding a new tool and for deleting or editing an existing tool. The up and down arrow buttons are used to change the order in which the registered tools are listed on the Tools menu.
-
- 
-
-Whenever the Add or Edit button is clicked on this dialog a Tool Properties dialog will appear. This dialog is used to describe the properties of the new tool being added or the existing tool being edited. 
-
-
-
-
- 
-
-The data entry fields of the Tool Properties dialog consist of the following:
-
-Tool Name
-This is the name to be used for the tool when it is displayed in the Tools Menu.
-
-Program
-Enter the full path name to the program that will be launched when the tool is selected. You can click the   button to bring up a standard Windows file selection dialog from which you can search for the tool’s executable file name.
-
-Working Directory
-This field contains the name of the directory that will be used as the working directory when the tool is launched. You can click the   button to bring up a standard directory selection dialog from which you can search for the desired directory. You can also enter the macro symbol `$PROJDIR` to utilize the current SWMM project’s directory or `$SWMMDIR` to use the directory where the SWMM 5 executable resides. Either of these macros can also be inserted into the Working Directory field by selecting its name in the list of macros provided on the dialog and then clicking the   button. This field can be left blank, in which case the system’s current directory will be used.
-
-Parameters
-This field contains the list of command line arguments that the tool’s executable program expects to see when it is launched. Multiple parameters can be entered as long as they are separated by spaces. A number of special macro symbols have been pre-defined, as listed in the Macros list box of the dialog, to simplify the process of listing the command line parameters. When one of these macro symbols is inserted into the list of parameters, it will be expanded to its true value when the tool is launched. A specific macro symbol can either be typed into the Parameters field or be selected from the Macros list (by clicking on it) and then added to the parameter list by clicking the   button. The available macro symbols and their meanings are:
-
-`$PROJDIR`    The directory where the current SWMM project file resides.
-`$SWMMDIR`    The directory where the SWMM 5 executable is installed.
-`$INPFILE`    The name of a temporary file containing the current project’s data that is created just before the tool is launched.
-`$RPTFILE`    The name of a temporary file that is created just before the tool is launched and can be displayed after the tool closes by using the Report >> Status command from the main SWMM menu.
-`$OUTFILE`    The name of a temporary file to which the tool can write simulation results in the same format used by SWMM 5, which can then be displayed after the tool closes in the same fashion as if a SWMM run were made.
-`$RIFFILE`    The name of the Runoff Interface File, as specified in the Interface Files page of the Simulation Options dialog, to which runoff simulation results were saved from a previous SWMM run (see Sections 8.1 and 11.7).
-
-As an example of how the macro expansion works, consider the entries in the Tool Properties dialog shown previously. This Spreadsheet Editor tool will launch Microsoft Excel and pass it the name of the SWMM input data file to be opened by Excel. SWMM will issue the following command line to do this
-`C:\Program Files (x86)\Microsoft Office\Office12\EXCEL.EXE $INPFILE`
-where the string `$INPFILE` will be replaced by the name of the temporary file that SWMM creates internally that contains the current project’s data.
-
-Disable SWMM while executing
-Check this option if SWMM should be hidden and disabled while the tool is executing. Normally you will need to employ this option if the tool produces a modified input file or output file, such as when the `$INPFILE` or `$OUTFILE` macros are used as command line parameters. When this option is enabled, SWMM’s main window will be hidden from view until the tool is terminated.
-
-Update SWMM after closing
-Check this option if SWMM should be updated after the tool finishes executing. This option can only be selected if the option to disable SWMM while the tool is executing was first selected. Updating can occur in two ways. If the `$INPFILE` macro was used as a command line parameter for the tool and the corresponding temporary input file produced by SWMM was updated by the tool, then the current project’s data will be replaced with the data contained in the updated temporary input file. If the `$OUTFILE` macro was used as a command line parameter, and its corresponding file is found to contain a valid set of output results after the tool closes, then the contents of this file will be used to display simulation results within the SWMM workspace.
-
-Generally speaking, the suppliers of third-party tools will provide instructions on what settings should be used in the Tool Properties dialog to properly register their tool with SWMM.
-
- 
-
diff --git a/docs/manuals/user/manual/Chapter13.md b/docs/manuals/user/manual/Chapter13.md
deleted file mode 100644
index 2b60d2162..000000000
--- a/docs/manuals/user/manual/Chapter13.md
+++ /dev/null
@@ -1,542 +0,0 @@
-@page user_manual_chapter_13 CHAPTER 13 – PROGRAMMATIC C API
-
-@tableofcontents
-
-OpenSWMM Engine v6 provides a comprehensive C API for building, running, and querying SWMM models entirely through code, without requiring an input file. This is useful for embedding SWMM in larger simulation frameworks, coupling with other models, or building custom user interfaces.
-
-## 13.1 Architecture Overview
-
-The new engine uses an opaque handle (`SWMM_Engine`) that encapsulates all simulation state. This reentrant design allows multiple independent simulations to run within the same process. The engine progresses through a well-defined lifecycle:
-
-```
-CREATED → OPENED → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED
-```
-
-When a model is constructed programmatically (no input file), the engine instead begins in a `BUILDING` state and `swmm_finalize_model()` transitions it directly to `INITIALIZED`:
-
-```
-[BUILDING] → INITIALIZED → STARTED → [RUNNING] → ENDED → CLOSED
-```
-
-All API functions return an integer error code (`SWMM_OK` on success) and are organized by domain into separate headers; the master header @ref openswmm_engine.h pulls in all of them:
-
-| Header | Domain |
-|---|---|
-| `openswmm_engine.h` | Engine lifecycle, error codes, state machine, timing, master include |
-| `openswmm_model.h` | Model building, validation, serialization, options, user flags, `[PLUGINS]`/`[FILES]` access |
-| `openswmm_nodes.h` | Junction, outfall, storage, and divider nodes |
-| `openswmm_links.h` | Conduit, pump, orifice, weir, and outlet links |
-| `openswmm_subcatchments.h` | Subcatchments and infiltration |
-| `openswmm_gages.h` | Rain gages |
-| `openswmm_pollutants.h` | Pollutants and their properties |
-| `openswmm_tables.h` | Time series, curves, and patterns |
-| `openswmm_inflows.h` | External inflows, DWF, and RDII |
-| `openswmm_controls.h` | Control rules |
-| `openswmm_infrastructure.h` | Transects, streets, inlets, LID controls |
-| `openswmm_spatial.h` | CRS, coordinates, polylines, polygons |
-| `openswmm_quality.h` | Landuse, buildup/washoff, treatment |
-| `openswmm_massbalance.h` | Continuity errors and flux totals |
-| `openswmm_statistics.h` | Post-run node/link/pump statistics |
-| `openswmm_forcing.h` | Runtime forcing overrides |
-| `openswmm_climate.h` | Evaporation, temperature, snowmelt, adjustments |
-| `openswmm_edit.h` | Object rename, delete, convert, impact analysis |
-| `openswmm_datetime.h` | SWMM DateTime encode/decode utilities |
-| `openswmm_xsect.h` | Cross-section geometry computations |
-| `openswmm_output.h` | Binary output (`.out`) file reading |
-| `openswmm_geopackage.h` | GeoPackage container queries |
-| `openswmm_callbacks.h` | Progress, warning, and step callback typedefs |
-| `openswmm_hotstart.h` | Hot start file operations |
-| `openswmm_2d.h` | 2-D overland flow mesh (when built with `OPENSWMM_HAS_2D`) |
-
-## 13.2 Basic Workflow
-
-Every engine instance moves through the deterministic lifecycle of
-Figure 13-1. The file-based path enters at `swmm_engine_open()`; the
-programmatic path enters at `swmm_engine_new()` (BUILDING) and joins it
-at `swmm_finalize_model()`.
-
-
-stateDiagram-v2
-    direction LR
-    [*] --> CREATED : swmm_engine_create
-    CREATED --> OPENED : swmm_engine_open - parse inp, load plugins
-    [*] --> BUILDING : swmm_engine_new
-    BUILDING --> OPENED : swmm_finalize_model
-    OPENED --> INITIALIZED : swmm_engine_initialize
-    INITIALIZED --> STARTED : swmm_engine_start
-    STARTED --> RUNNING : first swmm_engine_step
-    RUNNING --> RUNNING : swmm_engine_step
-    RUNNING --> ENDED : swmm_engine_end
-    ENDED --> ENDED : swmm_engine_report
-    ENDED --> CLOSED : swmm_engine_close
-    CLOSED --> [*] : swmm_engine_delete
-

-
-*Figure 13-1 Engine lifecycle states (SWMM_EngineState in @ref openswmm_engine.h)*
-
-The typical workflow for building and running a model programmatically (no input file):
-
-```c
-#include 
-
-// 1. Create an empty engine in BUILDING state (no .inp file required)
-SWMM_Engine engine = swmm_engine_new();
-
-// 2. Set model options (string key/value pairs, same vocabulary as [OPTIONS])
-swmm_options_set(engine, "FLOW_UNITS", "CFS");
-swmm_options_set(engine, "FLOW_ROUTING", "DYNWAVE");
-
-// 3. Build the network
-swmm_node_add(engine, "J1", SWMM_NODE_JUNCTION);
-swmm_node_set_invert_elev(engine, 0, 100.0);
-swmm_node_set_max_depth(engine, 0, 6.0);
-
-swmm_node_add(engine, "Out1", SWMM_NODE_OUTFALL);
-swmm_node_set_invert_elev(engine, 1, 95.0);
-
-swmm_link_add(engine, "C1", SWMM_LINK_CONDUIT);
-swmm_link_set_nodes(engine, 0, 0, 1);  // from J1 to Out1
-swmm_link_set_length(engine, 0, 500.0);
-swmm_link_set_roughness(engine, 0, 0.013);
-swmm_link_set_xsect(engine, 0, SWMM_XSECT_CIRCULAR, 2.0, 0, 0, 0);
-
-// 4. Finalize the built model (validates topology → INITIALIZED)
-swmm_finalize_model(engine);
-
-// 5. Start the simulation (1 = save results)
-swmm_engine_start(engine, 1);
-
-// 6. Step through the simulation
-double elapsed = 0.0;
-while (swmm_engine_step(engine, &elapsed) == SWMM_OK && elapsed > 0.0) {
-    // Query results during simulation
-    double depth;
-    swmm_node_get_depth(engine, 0, &depth);
-}
-
-// 7. End, close, and destroy
-swmm_engine_end(engine);
-swmm_engine_close(engine);
-swmm_engine_destroy(engine);
-```
-
-To run an existing input file instead, use `swmm_engine_create()` followed by `swmm_engine_open()` and `swmm_engine_initialize()`:
-
-```c
-SWMM_Engine engine = swmm_engine_create();
-swmm_engine_open(engine, "model.inp", "model.rpt", "model.out", NULL);
-swmm_engine_initialize(engine);
-swmm_engine_start(engine, 1);
-
-double elapsed = 0.0;
-while (swmm_engine_step(engine, &elapsed) == SWMM_OK && elapsed > 0.0) {
-    /* ... */
-}
-
-swmm_engine_end(engine);
-swmm_engine_report(engine);
-swmm_engine_close(engine);
-swmm_engine_destroy(engine);
-```
-
-The final `NULL` argument to `swmm_engine_open()` selects the built-in `.inp` reader; passing the path of an input-plugin shared library reads the model through that plugin instead (see Section 13.8). The single-call helpers `swmm_engine_run()` and `swmm_engine_run_with_callback()` chain the entire lifecycle for batch runs.
-
-## 13.3 Callbacks
-
-The callback system allows applications to receive notifications during simulation execution:
-
-- **Progress callback** — Receives periodic updates on simulation progress (0–100%).
-- **Warning callback** — Receives warning messages generated during simulation.
-- **Step-begin / step-end callbacks** — Called before and after each computational time step.
-- **Plugin state callback** — Notifies plugins of engine state transitions.
-
-Register callbacks before calling `swmm_engine_initialize()`. See @ref openswmm_callbacks.h for details and examples.
-
-## 13.4 Hot Start Files
-
-The hot start API enables saving and restoring simulation state for warm-start scenarios:
-
-```c
-#include 
-
-// Save state to a hot start file (engine must be RUNNING or ENDED)
-swmm_hotstart_save(engine, "warmup.hsf");
-
-// Later, open a hot start file and apply it to an INITIALIZED engine
-SWMM_HotStart hs;
-swmm_hotstart_open("warmup.hsf", &hs);
-swmm_hotstart_apply(engine, hs);
-swmm_hotstart_close(hs);
-```
-
-`swmm_hotstart_apply()` must be called after `swmm_engine_initialize()` but before `swmm_engine_start()`. Objects present in the file but missing from the model (or vice versa) generate warnings rather than errors; they can be enumerated with `swmm_hotstart_warning_count()` / `swmm_hotstart_warning()`. Saving dispatches through any registered state-IO plugins, so alternative hot-start file formats can be provided by plugins (see Section 13.8).
-
-## 13.5 Python Bindings {#user_manual_chapter_13_python}
-
-OpenSWMM 6.0 ships a first-class Python package (`openswmm`) that provides
-Pythonic, type-annotated access to the full engine feature set.  Install from
-PyPI:
-
-```bash
-pip install openswmm
-```
-
-### 13.5.1 Core Classes (`openswmm.engine`)
-
-All simulation functionality lives in the `openswmm.engine` sub-package.
-
-| Class | Purpose |
-|---|---|
-| `Solver` | Engine lifecycle — open, start, step, end, report |
-| `Nodes` | Query and set node attributes and results |
-| `Links` | Query and set link attributes and results |
-| `Subcatchments` | Query and set subcatchment attributes and results |
-| `Gages` | Query rain-gage attributes and recorded rainfall |
-| `HotStart` | Save and restore simulation state |
-| `MassBalance` | Retrieve continuity error and mass-balance statistics |
-| `ModelBuilder` | Construct a SWMM model programmatically without an input file |
-
-### 13.5.2 Running a Simulation from an Input File
-
-```python
-from openswmm.engine import Solver, Nodes, Links, Subcatchments
-
-with Solver("model.inp", "model.rpt", "model.out") as solver:
-    solver.start(save_results=True)
-
-    nodes = Nodes(solver)
-    links = Links(solver)
-    subcatchments = Subcatchments(solver)
-
-    while solver.step() > 0:
-        # Access current time-step values by object name
-        depth  = nodes["J1"].depth
-        head   = nodes["J1"].head
-        flow   = links["C1"].flow
-        runoff = subcatchments["S1"].runoff
-
-    solver.end()
-    solver.report()
-```
-
-### 13.5.3 Accessing Rain Gages
-
-```python
-from openswmm.engine import Solver, Gages
-
-with Solver("model.inp", "model.rpt", "model.out") as solver:
-    solver.start(save_results=True)
-    gages = Gages(solver)
-
-    while solver.step() > 0:
-        rain = gages["RG1"].rainfall   # current rainfall rate (in/hr or mm/hr)
-```
-
-### 13.5.4 Hot Start Files
-
-Hot start files allow a long-term simulation to be split into segments, each
-beginning from the hydraulic state left by the previous run.
-
-```python
-from openswmm.engine import Solver, HotStart
-
-# --- Warm-up run: save state at end ---
-with Solver("warmup.inp", "warmup.rpt", "warmup.out") as solver:
-    solver.start(save_results=True)
-    while solver.step() > 0:
-        pass
-    solver.save_hotstart("state.hsf")
-    solver.end()
-    solver.report()
-
-# --- Main run: restore state from hot start file ---
-with Solver("main.inp", "main.rpt", "main.out") as solver:
-    solver.use_hotstart("state.hsf")
-    solver.start(save_results=True)
-    while solver.step() > 0:
-        pass
-    solver.end()
-    solver.report()
-```
-
-### 13.5.5 Mass Balance and Continuity
-
-```python
-from openswmm.engine import Solver, MassBalance
-
-with Solver("model.inp", "model.rpt", "model.out") as solver:
-    solver.start(save_results=True)
-    while solver.step() > 0:
-        pass
-    solver.end()
-
-    mb = MassBalance(solver)
-    print(f"Runoff continuity error : {mb.runoff_error:.4f} %")
-    print(f"Routing continuity error: {mb.routing_error:.4f} %")
-```
-
-### 13.5.6 Building a Model Programmatically
-
-`ModelBuilder` constructs a complete SWMM network without an input file.  The
-finished model is passed directly to `Solver`.
-
-```python
-from openswmm.engine import ModelBuilder, Solver, Nodes, Links
-from openswmm.engine import NodeType, LinkType, FlowUnits, RoutingModel
-
-# Build the network
-mb = ModelBuilder()
-mb.flow_units = FlowUnits.CFS
-mb.routing_model = RoutingModel.DYNWAVE
-
-j1 = mb.add_node("J1", NodeType.JUNCTION)
-j1.invert_elev = 100.0
-j1.max_depth = 6.0
-
-out1 = mb.add_node("Out1", NodeType.OUTFALL)
-out1.invert_elev = 95.0
-
-c1 = mb.add_link("C1", LinkType.CONDUIT, from_node="J1", to_node="Out1")
-c1.length = 500.0
-c1.roughness = 0.013
-c1.set_circular_xsect(diameter=2.0)
-
-# Simulate the built model
-with Solver(mb, "model.rpt", "model.out") as solver:
-    solver.start(save_results=True)
-    nodes = Nodes(solver)
-    while solver.step() > 0:
-        print(nodes["J1"].depth)
-    solver.end()
-    solver.report()
-```
-
-### 13.5.7 Full API Reference
-
-The complete class and method documentation, including all attributes,
-enumerations, and error types, is published in the
-[Python Bindings API Reference](python/index.html).
-
-See the `python/` directory in the source tree for the Cython source (`.pyx`),
-type stubs (`.pyi`), and test suite.
-
-## 13.6 Building with the API
-
-To use the OpenSWMM Engine C API in your own project, link against `openswmm_engine` using CMake:
-
-```cmake
-find_package(OpenSWMMCore REQUIRED)
-target_link_libraries(my_app PRIVATE OpenSWMMCore::openswmm_engine)
-```
-
-All public headers are installed under `include/openswmm/engine/`.
-
-## 13.7 User-Defined Flags {#user_manual_chapter_13_user_flags}
-
-OpenSWMM Engine v6 introduces **user-defined flags** (inspired by InfoWorks ICM custom attributes) that allow metadata to be attached to any model object—nodes, links, or subcatchments. Flags are defined with a name, data type, and optional description and then assigned values per object.
-
-### Input File Syntax
-
-Two new sections are recognised in the input file:
-
-```ini
-[USER_FLAGS]
-;;Name            Type      Description
-INSPECTED         BOOLEAN   "Has the object been field-inspected?"
-PRIORITY          INTEGER   "Maintenance priority (1 = highest)"
-ROUGHNESS_ADJ     REAL      "Site-specific roughness multiplier"
-ASSET_ID          STRING    "External asset-management system ID"
-
-[USER_FLAG_VALUES]
-;;ObjectType   ObjectName   FlagName        Value
-NODE           J1           INSPECTED       YES
-NODE           J1           PRIORITY        2
-LINK           C_MAIN       ROUGHNESS_ADJ   1.05
-LINK           C_MAIN       ASSET_ID        "AM-00341"
-SUBCATCHMENT   S_WEST       INSPECTED       NO
-```
-
-Supported types are **BOOLEAN** (`YES`/`NO`/`TRUE`/`FALSE`/`1`/`0`), **INTEGER**, **REAL**, and **STRING**.
-
-### C API
-
-Flag values can be read or written at runtime through the C API:
-
-```c
-int swmm_userflag_get_bool(SWMM_Engine engine, const char* name, int* value);
-int swmm_userflag_set_bool(SWMM_Engine engine, const char* name, int  value);
-
-int swmm_userflag_get_int (SWMM_Engine engine, const char* name, int* value);
-int swmm_userflag_set_int (SWMM_Engine engine, const char* name, int  value);
-
-int swmm_userflag_get_real(SWMM_Engine engine, const char* name, double* value);
-int swmm_userflag_set_real(SWMM_Engine engine, const char* name, double  value);
-```
-
-See `openswmm_model.h` for the complete set of flag functions.
-
-## 13.8 Plugin Interface for Output and Reporting {#user_manual_chapter_13_plugins}
-
-The **plugin SDK** enables third-party shared libraries to replace or supplement the engine's built-in file I/O — the model reader/writer, the binary output (`.out`) file, the text-based status report, and the hot-start (state) file. Four abstract C++ interfaces are provided:
-
-| Interface | Header | Purpose |
-|---|---|---|
-| `IInputPlugin` | `IInputPlugin.hpp` | Reads model data into the engine (and writes it back out) in alternative container formats |
-| `IOutputPlugin` | `IOutputPlugin.hpp` | Writes time-series results at each output time step |
-| `IReportPlugin` | `IReportPlugin.hpp` | Writes summary statistics at simulation end |
-| `IStateIOPlugin` | `IStateIOPlugin.hpp` | Reads and writes simulation state (hot-start) files |
-
-All interfaces share a common lifecycle that mirrors the engine's own state machine (enumerated by `PluginState` in `PluginState.hpp`):
-
-```
-LOADED → initialize() → INITIALIZED → validate() → VALIDATED
-       → prepare()    → PREPARED     → update() [N times]
-       → finalize()   → FINALIZED    → CLOSED
-```
-
-Each plugin is compiled as a shared library (`.so` / `.dylib` / `.dll`) that exports a single C factory function:
-
-```cpp
-extern "C" openswmm::IPluginComponentInfo* openswmm_plugin_info(void);
-```
-
-The `IPluginComponentInfo` class provides metadata (id in reverse-DNS notation, caption, description, version, vendor, license), capability queries (`has_input()`, `has_output()`, `has_report()`, `has_state_io()` — a single plugin may support several roles), optional registration/licensing hooks, and factory methods for creating instances of each interface. Plugins also advertise the file formats they handle through `file_filters()`, one entry per (role, glob-pattern) pair; hosts such as the GUI use these to build file-picker dialogs without hard-coding format lists.
-
-### Plugin Discovery
-
-Each engine instance owns a `PluginFactory` that automatically scans the engine library directory and its `plugins/` and `components/` subdirectories for shared libraries exporting `openswmm_plugin_info`. Discovered libraries are registered in a component registry keyed by `id:version`; the built-in default input, output, report, and state-IO plugins are registered alongside them (flagged as built-ins). Hosts that only need to enumerate available formats can call the framework-free discovery facade in `PluginDiscovery.hpp`:
-
-```cpp
-#include 
-
-auto filters = openswmm::discover_all_filters();     // every (plugin, filter) pair
-auto plugins = openswmm::discover_plugins_by_id();   // grouped per plugin id
-```
-
-### Registering Plugins
-
-Plugins are loaded from the `[PLUGINS]` input-file section:
-
-```ini
-[PLUGINS]
-./plugins/hdf5_output.dylib     file="results.h5"  compress=9
-./plugins/csv_report.dylib      file="report.csv"   delimiter=","
-```
-
-Each line begins with the plugin to load — a shared-library path, a plugin id, or an `id:version` pair (ids are resolved against the auto-discovery registry) — followed by initialisation arguments that are forwarded verbatim to the plugin's `initialize()` method.
-
-Figure 13-2 traces the full resolution path from engine open to an
-initialized plugin.
-
-
-flowchart TD
-    A[swmm_engine_open] --> B[PluginFactory scans engine lib dir plus plugins and components subdirectories]
-    B --> C[Libraries exporting openswmm_plugin_info registered by id and version]
-    C --> D[Built-in input, output, report and state-IO plugins registered as built-ins]
-    D --> E[Parse PLUGINS section entries]
-    E --> F{Entry form}
-    F -- shared-library path --> G[Load library directly]
-    F -- plugin id --> H[Resolve newest version in registry]
-    F -- id colon version --> I[Resolve exact version in registry]
-    G --> J[Instantiate plugin]
-    H --> J
-    I --> J
-    J --> K[Forward remaining arguments to initialize]
-    K --> L[Plugin receives host callbacks during the run]
-

-
-*Figure 13-2 Plugin discovery, resolution and loading workflow (rendered diagram)*
-
-The `[PLUGINS]` section can also be inspected and edited through the C API without re-parsing the input file: `swmm_plugins_count()`, `swmm_plugin_get()`, `swmm_plugin_set()`, and `swmm_plugin_remove()` (declared in @ref openswmm_model.h) read and mutate the in-memory plugin list, which is re-serialised on the next model write.
-
-### Input Plugins and Model Serialisation
-
-An `IInputPlugin` reads a model file into the engine's simulation context and can also write the current model back out. The reader is selected per-open through the final argument of `swmm_engine_open()` (`NULL` selects the built-in `.inp` reader). To save the in-memory model through a specific writer plugin — for example a GeoPackage container instead of `.inp` — use:
-
-```c
-// NULL/empty plugin id is equivalent to swmm_model_write() (.inp writer)
-swmm_model_write_with_plugin(engine, "model.gpkg",
-                             "org.hydrocouple.openswmm.plugins.geopackage");
-```
-
-The plugin id is resolved with the same path / `id` / `id:version` logic as the `[PLUGINS]` section, and the resolved plugin must advertise input capability.
-
-### State-IO Plugins
-
-An `IStateIOPlugin` persists and restores simulation state (hot-start). On save, `swmm_hotstart_save()` dispatches through the registered state-IO plugins in order — the first plugin whose `write_state()` succeeds wins. On read, the engine calls each plugin's `can_read()` (a cheap extension/magic-number sniff) to pick the plugin that recognises the file. A built-in `DefaultStateIOPlugin` is always registered as a fallback, so the native binary hot-start format keeps working when no external plugin claims the file. Missing-object mismatches between the state file and the model are reported through the plugin's `warnings()` rather than as hard errors.
-
-### Data Available to Plugins
-
-At every output time step the engine passes a read-only **SimulationSnapshot** to `update()`. The snapshot exposes per-object results:
-
-- **NodeSnapshot** — depth, head, volume, lateral inflow, total inflow, overflow
-- **LinkSnapshot** — flow, depth, velocity, capacity fraction
-- **SubcatchSnapshot** — rainfall, evaporation, infiltration, runoff, groundwater flow, groundwater elevation, soil moisture
-- **GageSnapshot** — current rainfall rate
-
-See the headers in `include/openswmm/plugin_sdk/` for full details. The engine-side loader, lifecycle dispatcher, and the built-in default plugins live in `src/engine/plugins/` (`PluginFactory.cpp`, `DefaultInputPlugin.cpp`, `DefaultOutputPlugin.cpp`, `DefaultReportPlugin.cpp`, `DefaultStateIOPlugin.cpp`).
-
-## 13.9 CSV Rain-File Inputs {#user_manual_chapter_13_csv}
-
-A new rain-file format, **USER_CSV**, allows rain gage data to be read from multi-column CSV files. A single CSV file can serve multiple rain gages by specifying a column name after the file path:
-
-```ini
-[RAINGAGES]
-;;Name   Format   Interval  SCF   Source
-RG1      VOLUME   0:15      1.0   TIMESERIES RAIN1
-RG2      VOLUME   0:15      1.0   FILE "rain.csv:EAST_GAGE"
-RG3      VOLUME   0:15      1.0   FILE "rain.csv:WEST_GAGE"
-```
-
-The syntax `"filename.csv:COLUMN_NAME"` tells the engine to open `filename.csv` and read the column whose header matches `COLUMN_NAME`. The CSV file is expected to have a header row; columns are separated by commas.
-
-The `RainFileFormat` enumeration now includes:
-
-| Value | Constant | Description |
-|---|---|---|
-| 0 | `NWS_15` | NWS 15-minute data |
-| 1 | `NWS_HOURLY` | NWS hourly data |
-| 2 | `DSI_3240` | NCDC DSI 3240 hourly |
-| 3 | `DSI_3260` | NCDC DSI 3260 15-minute |
-| 4 | `HLY_PRCP` | HLY_PRCP format |
-| 5 | `STAN_PRCP` | Standard SWMM rain file |
-| 6 | `USER_CSV` | User-supplied multi-column CSV (**new in v6**) |
-
-## 13.10 Extension Options (Optional Tags) {#user_manual_chapter_13_ext_options}
-
-The `[OPTIONS]` section now tolerates **extension option keys** that are not part of the standard SWMM vocabulary. Any key the parser does not recognise is stored in an extension-options map as a string key-value pair rather than producing a fatal error (a non-fatal warning is issued). This mechanism allows plugins and coupled models to pass configuration through the familiar `[OPTIONS]` section.
-
-### Input File Syntax
-
-```ini
-[OPTIONS]
-FLOW_UNITS           CFS
-FLOW_ROUTING         DYNWAVE
-START_DATE           01/01/2020
-END_DATE             01/02/2020
-
-;; Standard new option — Coordinate Reference System (EPSG or PROJ string)
-CRS                  EPSG:4326
-
-;; Extension options — stored as-is, available to plugins via API
-TURBULENCE_DAMP      0.85
-PLUGIN_TIMEOUT       30
-MY_VENDOR_SETTING    value123
-```
-
-Extension option keys are **upper-cased** for storage. Plugins (or any code using the C API) can retrieve and set these values at runtime:
-
-```c
-// Retrieve an extension option
-char buffer[256];
-swmm_options_get_ext(engine, "TURBULENCE_DAMP", buffer, sizeof(buffer));
-double damp = atof(buffer);
-
-// Create or update an extension option
-swmm_options_set_ext(engine, "MY_VENDOR_SETTING", "new_value");
-```
-
-Note that the **CRS** key is a standard option new to v6 and is stored separately in `SimulationOptions::crs`. All other unrecognised keys go into the extension map.
-
-
-
diff --git a/docs/manuals/user/manual/Chapter2.md b/docs/manuals/user/manual/Chapter2.md
deleted file mode 100644
index 9b5921309..000000000
--- a/docs/manuals/user/manual/Chapter2.md
+++ /dev/null
@@ -1,462 +0,0 @@
-@page user_manual_chapter_2 CHAPTER 2 – QUICK START TUTORIAL
-
-@tableofcontents
-
-This chapter provides a tutorial on how to use EPA SWMM. If you are not familiar with the elements that comprise a drainage system, and how these are represented in a SWMM model, you might want to review the material in Chapter 3 first.
-
-## 2.1 Example Study Area
-
-In this tutorial we will model the drainage system serving a 12-acre residential area. The system layout is shown in Figure 2-1(@ref user_manual_figure2_1) and consists of subcatchment areas [^1]  S1 through S3, storm sewer conduits C1 through C4, and conduit junctions J1 through J4. The system discharges to a creek at the point labeled Out1. We will first go through the steps of creating the objects shown in this diagram on SWMM's study area map and setting the various properties of these objects. Then we will simulate the water quantity and quality response to a 3-inch, 6-hour rainfall event, as well as a continuous, multi-year rainfall record.
-
-![Figure 2-1. A schematic diagram of the study area being analyzed in the example tutorial.](./figures/figure2_1_example_study_area.png "Figure 2-1. A schematic diagram of the study area being analyzed in the example tutorial."){#user_manual_figure2_1}
-
-[^1]: A subcatchment is an area of land containing a mix of pervious and impervious surfaces whose runoff drains to a common outlet point, which could be either a node of the drainage network or another subcatchment.
-
-## 2.2 Project Setup
-
-Our first task is to create a new SWMM project and make sure that certain default options are selected. Using these defaults will simplify the data entry tasks later on.
-
-1. Launch EPA SWMM if it is not already running and select File >> New from the Main Menu bar to create a new project.
-
-2. Select Project >> Defaults to open the Project Defaults dialog.
-
-3. On the ID Labels page of the dialog, set the ID Prefixes as shown below. This will make SWMM automatically label new objects with consecutive numbers following the designated prefix.
-
-    ![Figure 2-2. SWMM's Project Defaults dialog form showing the default ID labeling used for the tutorial example.](./figures/figure2_2_project_defaults_dialog.png "Figure 2-2. SWMM's Project Defaults dialog form showing the default ID labeling used for the tutorial example."){#user_manual_figure2_2}
-
-4. On the Subcatchments page of the dialog set the following default values:
-
-    ```
-    Area                    4
-    Width                    400    
-    % Slope                    0.5    
-    % Imperv.                50    
-    N-Imperv.                0.01
-    N-Perv.                    0.10
-    Dstore-Imperv.            0.05
-    Dstore-Perv                0.05
-    %Zero-Imperv.            25
-    Infil. Model            
-    -  Method                Modified Green-Ampt
-    -  Suction Head            3.5
-    -  Conductivity            0.5
-    -  Initial Deficit        0.26
-    ```
-
-5. On the Nodes/Links page set the following default values:
-
-    ```
-    Node Invert                 0
-    Node Max. Depth         4
-    Node Ponded Area        0
-    Conduit Length             400
-    Conduit Geometry         
-        - Barrels            1
-        - Shape                Circular
-        - Max. Depth        1.0
-    Conduit Roughness         0.01
-    Flow Units                 CFS
-    Link Offsets                DEPTH
-    Routing Model            Kinematic Wave
-    ```
-6. Click OK to accept these choices and close the dialog. If you wanted to save these choices for all future new projects you could check the Save box at the bottom of the form before accepting it.
-
-Next we will set some map display options so that ID labels and symbols will be displayed as we add objects to the study area map, and links will have direction arrows.
-
-1. Select **Tools >> Map Display Options** to bring up the Map Options dialog .
-
-2. Select the Subcatchments page, set the Fill Style to Diagonal and the Symbol Size to 5.
-
-3. Then select the Nodes page and set the Node Size to 5.
-
-4. Select the Annotation page and check off the boxes that will display ID labels for Subcatchments, Nodes, and Links. Leave the others un-checked.
-
-5. Finally, select the Flow Arrows page, select the Filled arrow style, and set the arrow size to 7.
-    
-6. Click the **OK** button to accept these choices and close the dialog.
-
-    ![Figure 2-3. SWMM's Map Options dialog form.](./figures/figure2_3_map_options_dialog.png "Figure 2-3. SWMM's Map Options dialog form."){#user_manual_figure2_3} 
-
-Before placing objects on the map we should set its dimensions.
-    Select View >> Dimensions to bring up the Map Dimensions dialog.
-    You can leave the dimensions at their default values for this example.
-
-Finally, look in the status bar at the bottom of the main window and check that the Auto-Length feature is off. If it is on, then click the down arrow button and select "Auto-Length: Off" from the popup menu that appears. Also make sure that the Offsets option is set to Depth. If set to Elevation then click the down arrow button and select "Depth Offsets" from the popup menu that appears.
-
-
-
-
-
-## 2.3 Drawing Objects
-
-We are now ready to begin adding components to the Study Area Map . We will start with the subcatchments. 
-    Begin by selecting the Subcatchments category (under Hydrology) in the Project Browser panel (on the left side of the main window).
-    Then click the   button on the toolbar underneath the object category listing in the Project panel (or select Project | Add a New Subcatchment from the main menu). Notice how the mouse cursor changes shape to a pencil when you move it over the map.
-    Move the mouse to the map location where one of the corners of subcatchment S1 lies and left-click the mouse.
-    Do the same for the next three corners and then right-click the mouse (or hit the Enter key) to close up the rectangle that represents subcatchment S1. You can press the Esc key if instead you wanted to cancel your partially drawn subcatchment and start over again. Don't worry if the shape or position of the object isn't quite right. We will go back later and show how to fix this.
-    Repeat this process for subcatchments S2 and S3 . 
-Observe how sequential ID labels are generated automatically as we add objects to the map.
-
-Next we will add in the junction nodes and the outfall node that comprise part of the drainage network. 
-    To begin adding junctions, select the Junctions category from the Project Browser (under Hydraulics -> Nodes) and click the   button or select Project | Add a New Junction from the main menu.
-    Move the mouse to the position of junction J1 and left-click it. Do the same for junctions J2 through J4.
-    To add the outfall node, select Outfalls from the Project Browser, click the   button or select Project | Add a New Outfall from the main menu, move the mouse to the outfall's location on the map, and left-click. Note how the outfall was automatically given the name Out1.
-At this point your map should look something like that shown in Figure 2-2.
-
-
- 
-Figure 2 2  Subcatchments and nodes for example study area
-
-Now we will add the storm sewer conduits that connect our drainage system nodes to one another. (You must have created a link's end nodes as described previously before you can create the link.) We will begin with conduit C1, which connects junction J1 to J2.
-    Select the Conduits category from the Project Browser (under Hydraulics -> Links) and press the   button or select Project | Add a New Conduit from the main menu. The mouse cursor will change shape to a cross hair when moved onto the map.
-    Left-click the mouse on junction J1. Note how the mouse cursor changes shape to a pencil. 
-    Move the mouse over to junction J2 (note how an outline of the conduit is drawn as you move the mouse) and left-click to create the conduit. You could have cancelled the operation by either right clicking or by hitting the <Esc> key.
-    Repeat this procedure for conduits C2 through C4.
-
-Although all of our conduits were drawn as straight lines, it is possible to draw a curved link by left-clicking at intermediate points where the direction of the link changes before clicking on the end node.
-
-
-
-To complete the construction of our study area schematic we need to add a rain gage.
-    Select the Rain Gages category from the Project Browser panel (under Hydrology) and either click the   button or select Project | Add a New Rain Gage from the main menu.
-    Move the mouse over the Study Area Map to where the gage should be located and left-click the mouse.
-
-At this point we have completed drawing the example study area. Your system should look like the one in Figure 2-1. If a rain gage, subcatchment or node is out of position you can move it by doing the following:
-    If the   button on the Map Toolbar is not already depressed, click it to place the map in Object Selection mode.
-    Click on the object to be moved.
-    Drag the object with the left mouse button held down to its new position.
-
-To re-shape a subcatchment's outline:
-    With the map in Object Selection mode, click on the subcatchment's centroid (indicated by a solid square within the subcatchment) to select it.
-    Then click the   button on the Map Toolbar to put the map into Vertex Selection mode.
-    Select a vertex point on the subcatchment outline by clicking on it (note how the selected vertex is indicated by a filled solid square).
-    Drag the vertex to its new position with the left mouse button held down.
-    If need be, vertices can be added or deleted from the outline by right-clicking the mouse and selecting the appropriate option from the popup menu that appears.
-    When finished, click the   button to return to Object Selection mode.
-
-This same procedure can also be used to re-shape a link.
-
-## 2.4 Setting Object Properties
-
-As visual objects are added to our project, SWMM assigns them a default set of properties. To change the value of a specific property for an object we must select the object into the Property Editor. There are several different ways to do this. If the Editor is already visible, then you can simply click on the object or select it from the Project Browser. If the Editor is not visible then you can make it appear by one of the following actions:
-    double-click the object on the map,
-    or right-click on the object and select Properties from the pop-up menu that appears, 
-    or select the object from the Project Browser and then click the Browser’s    button,
-    or after selecting the object choose Edit >> Edit Object from the Main Menu.    
-
-
- 
-
-Whenever the Property Editor has the focus you can press the F1 key to obtain a more detailed description of the properties listed.
-
-Two key properties of our subcatchments that need to be set are the rain gage that supplies rainfall data to the subcatchment and the node of the drainage system that receives runoff from the subcatchment. Since all of our subcatchments utilize the same rain gage, Gage1, we can use a shortcut method to set this property for all subcatchments at once:
-    From the Main Menu select Edit >>Select All.
-    Then select Edit >> Group Edit to make a Group Editor dialog appear.
-    Select Subcatchment as the type of object to edit, Rain Gage as the property to edit, and type in Gage1 as the new value.
-    Click OK to change the rain gage of all subcatchments to Gage1. A confirmation dialog will appear noting that 3 subcatchments have changed. Select “No” when asked to continue editing.
-
- 
-
-To set the outlet node of our subcatchments we have to proceed one by one, since these vary by subcatchment:
-    Double click on subcatchment S1 or select it from the Project Browser and click the Browser's   button to bring up the Property Editor.
-    Type J1 in the Outlet field and press Enter. Note how a dotted line is drawn between the subcatchment and the node.
-    Click on subcatchment S2 and enter J2 as its Outlet.
-    Click on subcatchment S3 and enter J3 as its Outlet.
-We also wish to represent area S3 as being less developed than the others. Select S3 into the Property Editor and set its % Imperviousness to 25.
-
-The junctions and outfall of our drainage system need to have invert elevations assigned to them. As we did with the subcatchments, select each junction individually into the Property Editor and set its Invert Elevation to the value shown below . 
-
-
-
-Node      Invert
-J1            96
-J2            90
-J3            93
-J4            88
-Out1        85
-
-Only one of the conduits in our example system has a non-default property value. This is conduit C4, the outlet pipe, whose diameter should be 1.5 instead of 1 ft. To change its diameter, select conduit C4 into the Property Editor and set the Max. Depth value to 1.5.
-
-In order to provide a source of rainfall input to our project we need to set the rain gage’s properties. Select Gage1 into the Property Editor and set the following properties:
-
-Rain Format    INTENSITY
-Rain Interval    1:00
-Data Source    TIMESERIES
-Series Name    TS1
-
-As mentioned earlier, we want to simulate the response of our study area to a 3-inch, 6-hour design storm. A time series named TS1 will contain the hourly rainfall intensities that make up this storm. Thus we need to create a time series object and populate it with data. To do this:
-    From the Project Browser select the Time Series category of objects.
-    Click the   button on the Browser to bring up the Time Series Editor dialog .
-    Enter TS1 in the Time Series Name field.
-    Enter the values shown in the dialog on the next page into the Time and Value columns of the data entry grid (leave the Date column blank ).
-    You can click the View button on the dialog to see a graph of the time series values. Click the OK button to accept the new time series.
- 
- 
-
-Having completed the initial design of our example project it is a good idea to give it a title and save our work to a file at this point. To do this:
-    Select the Title/Notes category from the Project Browser and click the   button.
-    In the Project Title/Notes dialog that appears, enter “Tutorial Example” as the title of our project and click the OK button to close the dialog.
-    From the File menu select the Save As option.
-    In the Save As dialog that appears, select a folder and file name under which to save this project. We suggest naming the file tutorial.inp. (An extension of .inp will be added to the file name if one is not supplied.)
-    Click Save to save the project to file.
-
- 
-
-The project data are saved to the file in a readable text format. You can view what the file looks like by selecting Project >> Details from the main menu. To open our project at some later time, you would select the Open command from the File menu.
-
-## 2.5 Running a Simulation
-
-Setting Simulation Options
-
-Before analyzing the performance of our example drainage system we need to set some options that determine how the analysis will be carried out. To do this:
-    From the Project Browser, select the Options category and click the   button.
-    On the General page of the Simulation Options dialog that appears (see next page), select Kinematic Wave as the flow routing method. The infiltration method should already be set to Modified Green-Ampt. The Allow Ponding option should be unchecked.
-    On the Dates page of the dialog, set the End Analysis time to 12:00:00.
-    On the Time Steps page, set the Routing Time Step to 60 seconds.
-    Click OK to close the Simulation Options dialog.
-
-
- 
-
-Starting a Simulation
-
-We are now ready to run the simulation. To do so, select Project >> Run Simulation (or click the   button). If there was a problem with the simulation, a Status Report will appear describing what errors occurred. Upon successfully completing a run, there are numerous ways in which to view the results of the simulation. We will illustrate just a few here.
-
-Viewing the Status Report
-
-The Status Report contains useful information about the quality of a simulation run, including a mass balance on rainfall, infiltration, evaporation, runoff, and inflow/outflow for the conveyance system. To view the report select Report >> Status (or click the   button on the Standard Toolbar and then select Status Report from the drop down menu). A portion of the report for the system just analyzed is shown below:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-For the system we just analyzed the report indicates the quality of the simulation is quite good, with negligible mass balance continuity errors for both runoff and routing (-0.39% and 0.03%, respectively, if all data were entered correctly). Also, of the 3 inches of rain that fell on the study area, 1.75 infiltrated into the ground and essentially the remainder became runoff.
-
-Viewing the Summary Report
-
-The Summary Report contains tables listing summary results for each subcatchment, node and link in the drainage system. Total rainfall, total runoff, and peak runoff for each subcatchment, peak depth and hours flooded for each node, and peak flow, velocity, and depth for each conduit are just some of the outcomes included in the summary report.
-
-To view the Summary Report select Report | Summary from the main menu (or click the    button on the Standard Toolbar and then select Summary Report from the drop down menu). The report's window has a drop down list from which you select a particular report to view. For our example, the Node Flooding Summary table indicates there was internal flooding in the system at node J2. Note. The Conduit Surcharge Summary table shows that Conduit C2, just downstream of node J2, was at full capacity and therefore appears to be slightly undersized.
-
- 
-
- 
-
-In SWMM flooding will occur whenever the water surface at a node exceeds the maximum assigned depth. Normally such water will be lost from the system. The option also exists to have this water pond atop the node and be re-introduced into the drainage system when capacity exists to do so.
-
-
-
-
-
-Viewing Results on the Map
-
-Simulation results (as well as some design parameters, such as subcatchment area, node invert elevation, and link maximum depth) can be viewed in color-coded fashion on the study area map. 
-
- 
-
-To view a particular variable in this fashion:
-    Select the Map page of the Browser panel.
-    Select the variables to view for Subcatchments, Nodes, and Links from the dropdown combo boxes appearing in the Themes panel. As shown above, subcatchment runoff and link flow have been selected for viewing.
-    The color-coding used for a particular variable is displayed with a legend on the study area map. To toggle the display of a legend, select View >> Legends.
-    To move a legend to another location, drag it with the left mouse button held down.
-    To change the color-coding and the breakpoint values for different colors, select View >> Legends >> Modify and then the pertinent class of object (or if the legend is already visible, simply right-click on it). To view numerical values for the variables being displayed on the map, select Tools >> Map Display Options and then select the Annotation page of the Map Options dialog. Use the check boxes for Subcatchment Values, Node Values, and Link Values to specify what kind of annotation to add.
-    The Date / Time of Day / Elapsed Time controls on the Map Browser can be used to move through the simulation results in time. The map view shown above depicts results at 5 hours and 45 minutes into the simulation.
-    You can use the controls in the Animator panel of the Map Browser to animate the map display through time. For example, pressing the   button will run the animation forward in time.
-
-Viewing a Time Series Plot
-
-To generate a time series plot of a simulation result:
-    Select Report >> Graph >> Time Series or simply click     on the Standard Toolbar.
-    A Time Series Plot Selection dialog will appear. It is used to select the objects and variables to be plotted.
-
-For our example, the Time Series Plot Selection dialog can be used to graph the flow in conduits C1 and C2 as follows (refer to the dialog forms shown below):
-    Click the Add button on the dialog to view the Data Series Selection dialog.
-     Select conduit C1 (either on the map or in the Project Browser) and select Flow as the variable to be plotted. Click the Accept button to return to the Time Series Plot Selection dialog.
-    Repeat steps 1 and 2 for conduit C2.
-    Press OK to create the plot which should look like the graph shown below.
-
-
-
-
-
-
-
-    
- 
-
-     
- 
-
-
-
-After a plot is created you can:
-    customize its appearance by selecting Report >> Customize or by clicking the    button on the Standard Toolbar or by simply right clicking on the plot,
-    copy it to the clipboard and paste it into another application by selecting Edit >> Copy To or clicking   on the Standard Toolbar
-    print it by selecting File >> Print or File >> Print Preview (use File >> Page Setup first to set margins, orientation, etc.).
-
-Viewing a Profile Plot
-
-SWMM can generate profile plots showing how water surface depth varies across a path of connected nodes and links. Let's create such a plot for the conduits connecting junction J1 to the outfall Out1 of our example drainage system. To do this:
-    Select Report >> Graph >> Profile on the main menu or click   on the main Toolbar.
-    Either enter J1 in the Start Node field of the Profile Plot Selection dialog or select it on the map or from the Project Browser and click the   button next to the field. 
-    Do the same for node Out1 in the End Node field of the dialog.
-    Click the Find Path button. An ordered list of the links forming a connected path between the specified Start and End nodes will be displayed in the Links in Profile box. You can edit the entries in this box if need be.
-
- 
-    Click the OK button to create the plot, showing the water surface profile as it exists at the simulation time currently selected in the Map Browser (hour 02:45 for the plot shown below).
-
- 
-
-As you move through time using the Map Browser or with the Animator control, the water depth profile on the plot will be updated. Observe how node J2 becomes flooded between hours 2 and 3 of the storm event. A Profile Plot’s appearance can be customized and it can be copied or printed using the same procedures as for a Time Series Plot.
-
-Running a Full Dynamic Wave Analysis
-
-In the analysis just run we chose to use the Kinematic Wave method of routing flows through our drainage system. This is an efficient but simplified approach that cannot deal with such phenomena as backwater effects, pressurized flow, flow reversal, and non-dendritic layouts. SWMM also includes a Dynamic Wave routing procedure that can represent these conditions. This procedure, however, requires more computation time, due to the need for smaller time steps to maintain numerical stability.
-
-Most of the effects mentioned above would not apply to our example. However we had one conduit, C2, which flowed full and caused its upstream junction to flood. It could be that this pipe is actually being pressurized and could therefore convey more flow than was computed using Kinematic Wave routing. We would now like to see what would happen if we apply Dynamic Wave routing instead.
-
-To run the analysis with Dynamic Wave routing:
-    From the Project Browser, select the Options category and click the   button.
-    On the General page of the Simulation Options dialog that appears, select Dynamic Wave as the flow routing method.
-    On the Dynamic Wave page of the dialog, use the settings shown below .
-
- 
-    Click OK to close the form and select Project >> Run Simulation (or click the    button) to re-run the analysis.
-If you look at the Summary Report for this run, you will see that there is no longer any junction flooding and that the peak flow carried by conduit C2 has been increased from 3.52 cfs to 4.04 cfs.
-
-## 2.6 Simulating Water Quality
-
-In the next phase of this tutorial we will add water quality analysis to our example project. SWMM has the ability to analyze the buildup, washoff, transport and treatment of any number of water quality constituents. The steps needed to accomplish this are:
-    Identify the pollutants to be analyzed.
-    Define the categories of land uses that generate these pollutants.
-    Set the parameters of buildup and washoff functions that determine the quality of runoff from each land use.
-    Assign a mixture of land uses to each subcatchment area
-    Define pollutant removal functions for nodes within the drainage system that contain treatment facilities.
-We will now apply each of these steps, with the exception of number 5, to our example project .
-
-We will define two runoff pollutants; total suspended solids (TSS), measured as mg/L, and total Lead, measured in ug/L. In addition, we will specify that the concentration of Lead in runoff is a fixed fraction (0.25) of the TSS concentration. To add these pollutants to our project:
-    Under the Quality category in the project Browser, select the Pollutants sub-category beneath it.
-    Click the   button to add a new pollutant to the project.
-    In the Pollutant Editor dialog that appears, enter TSS for the pollutant name and leave the other data fields at their default settings.
-    Click the OK button to close the Editor.
-    Click the   button on the Project Browser again to add our next pollutant.
-    In the Pollutant Editor, enter Lead for the pollutant name, select UG/L for the concentration units, enter TSS as the name of the Co-Pollutant, and enter 0.25 as the Co-Fraction value.
-    Click the OK button to close the Editor.
-
- 
-
-In SWMM, pollutants associated with runoff are generated by specific land uses assigned to subcatchments. In our example, we will define two categories of land uses: Residential and Undeveloped. To add these land uses to the project:
-    Under the Quality category in the Project Browser, select the Land Uses sub-category and click the   button.
-    In the Land Use Editor dialog that appears (see Figure 2-20), enter Residential in the Name field and then click the OK button.
-    Repeat steps 1 and 2 to create the Undeveloped land use category.
-
-
- 
-
-Next we need to define buildup and washoff functions for TSS in each of our land use categories. Functions for Lead are not needed since its runoff concentration was defined to be a fixed fraction of the TSS concentration. Normally, defining these functions requires site-specific calibration.
-
-In this example we will assume that suspended solids in Residential areas builds up at a constant rate of 1 pound per acre per day until a limit of 50 lbs per acre is reached. For the Undeveloped area we will assume that buildup is only half as much. For the washoff function, we will assume a constant event mean concentration of 100 mg/L for Residential land and 50 mg/L for Undeveloped land. When runoff occurs, these concentrations will be maintained until the available buildup is exhausted. To define these functions for the Residential land use:
-    Select the Residential land use category from the Project Browser and click .
-    In the Land Use Editor dialog, move to the Buildup page.
-    Select TSS as the pollutant and POW (for Power function) as the function type.
-    Assign the function a maximum buildup of 50, a rate constant of 1.0, a power of 1 and select AREA as the normalizer.
-
-
- 
-
-    Move to the Washoff page of the dialog and select TSS as the pollutant, EMC as the function type, and enter 100 for the coefficient. Fill the other fields with 0.
-    Click the OK button to accept your entries.
-Now do the same for the Undeveloped land use category, except use a maximum buildup of 25, a buildup rate constant of 0.5, a buildup power of 1, and a washoff EMC of 50.
-
-The final step in our water quality example is to assign a mixture of land uses to each subcatchment area:
-    Select subcatchment S1 into the Property Editor.
-    Select the Land Uses property and click the ellipsis button (or press Enter).
-    In the Land Use Assignment dialog that appears, enter 75 for the % Residential and 25 for the % Undeveloped. Then click the OK button to close the dialog.
-
- 
-    Repeat the same three steps for subcatchment S2.
-    Repeat the same for subcatchment S3, except assign the land uses as 25% Residential and 75% Undeveloped.
-
-Before we simulate the runoff quantities of TSS and Lead from our study area, an initial buildup of TSS should be defined so it can be washed off during our single rainfall event. We can either specify the number of antecedent dry days prior to the simulation or directly specify the initial buildup mass on each subcatchment. We will use the former method:
-    From the Options category of the Project Browser, select the Dates sub-category and click the   button.
-    In the Simulation Options dialog that appears, enter 5 into the Antecedent Dry Days field.
-    Leave the other simulation options the same as they were for the dynamic wave flow routing we just completed.
-    Click the OK button to close the dialog.
-Now run the simulation by selecting Project >> Run Simulation or by clicking   on the Standard Toolbar.
-
-When the run is completed, view its Status Report. Note that two new sections have been added for Runoff Quality Continuity and Quality Routing Continuity. From the Runoff Quality Continuity table we see that there was an initial buildup of 47.5 lbs of TSS on the study area and an additional 2.2 lbs of buildup added during the dry periods of the simulation. About 47.9 lbs were washed off during the rainfall event. The quantity of Lead washed off is a fixed percentage (25% times 0.001 to convert from mg to ug) of the TSS as was specified.
-If you plot the runoff concentration of TSS for subcatchment S1 and S3 together on the same time series graph as shown below, you will see the difference in concentrations resulting from the different mix of land uses in these two areas. You can also see that the duration over which pollutants are washed off is much shorter than the duration of the entire runoff hydrograph (i.e., 1 hour versus about 6 hours). This results from having exhausted the available buildup of TSS over this period of time.  
-
- 
-
-## 2.7 Running a Continuous Simulation
-
-As a final exercise in this tutorial we will demonstrate how to run a long-term continuous simulation using a historical rainfall record and how to perform a statistical frequency analysis on the results. The rainfall record will come from a file named sta310301.dat that was included with the example data sets provided with EPA SWMM. It contains several years of hourly rainfall beginning in January 1998. The data are stored in the National Climatic Data Center's DSI 3240 format, which SWMM can automatically recognize.
-
-To run a continuous simulation with this rainfall record:
-    Select the rain gage Gage1 into the Property Editor.
-    Change the selection of Data Source to FILE.
-    Select the File Name data field and click the ellipsis button (or press the Enter key) to bring up a standard Windows File Selection dialog.
-    Navigate to the folder where the SWMM example files were stored, select the file named sta310301.dat, and click Open to select the file and close the dialog.
-    In the Station No. field of the Property Editor enter 310301. 
-    Select the Options category in the Project Browser and click the   button to bring up the Simulation Options form.
-    On the General page of the form, select Kinematic Wave as the Routing Method (this will help speed up the computations).
-    On the Dates page of the form, set both the Start Analysis and Start Reporting dates to 01/01/1998, and set the End Analysis date to 01/01/2000.
-    On the Time Steps page of the form, set the Routing Time Step to 300 seconds.
-    Close the Simulation Options form by clicking the OK button and start the simulation by selecting Project >> Run Simulation (or by clicking  on the Standard Toolbar).
-
-After our continuous simulation is completed we can perform a statistical frequency analysis on any of the variables produced as output. For example, to determine the distribution of rainfall volumes within each storm event over the two-year period simulated:
-    Select Report >> Statistics or click the   button on the Standard Toolbar.
-    In the Statistics Report Selection dialog that appears, enter the values shown below.
- 
-    Click the OK button to close the form.
-
-The results of this request will be a Statistics Report form containing four tabbed pages: a Summary page, an Events page containing a rank-ordered listing of each event, a Histogram page containing a plot of the occurrence frequency versus event magnitude, and a Frequency Plot page that plots event magnitude versus cumulative frequency.
-
- 
-
-The summary page shows that there were a total of 213 rainfall events. The Events page shows that the largest rainfall event had a volume of 3.35 inches and occurred over a 24- hour period. There were no events that matched the 3-inch, 6-hour design storm event used in our previous single-event analysis that had produced some internal flooding. In fact, the Summary Report for this continuous simulation indicates that there were no flooding or surcharge occurrences over the simulation period.
-
-We have only touched the surface of SWMM's capabilities. Some additional features of the program that you will find useful include:
-    adding low impact development (LID) controls (i.e., green infrastructure) to reduce or delay runoff from subcatchments
-    utilizing additional types of drainage elements, such as storage units, flow dividers, pumps, and regulators, to model more complex types of systems
-    using control rules to simulate real-time operation of pumps and regulators
-    employing different types of externally-imposed inflows at drainage system nodes, such as direct time series inflows, dry weather inflows, and rainfall-dependent infiltration and inflow
-    modeling groundwater interflow between aquifers beneath subcatchment areas and drainage system nodes
-    modeling snow fall accumulation and melting within subcatchments
-    adding calibration data to a project so that simulated results can be compared with measured values
-    utilizing a background street, site plan, or topo map to assist in laying out a system's drainage elements and to help relate simulated results to real-world locations.
-You can find more information on these and other features in the remaining chapters of this manual.
- 
-
diff --git a/docs/manuals/user/manual/Chapter3.md b/docs/manuals/user/manual/Chapter3.md
deleted file mode 100644
index 6b47a4d7e..000000000
--- a/docs/manuals/user/manual/Chapter3.md
+++ /dev/null
@@ -1,832 +0,0 @@
-@page user_manual_chapter_3 CHAPTER 3 - SWMM’S CONCEPTUAL MODEL
-
-@tableofcontents
-
----
-
-This chapter discusses how SWMM models the objects and operational parameters that constitute a stormwater drainage system. Details about how this information is entered into the program are presented in later chapters. An overview is also given on the computational methods that SWMM uses to simulate the hydrology, hydraulics and water quality behavior of a drainage system.
-
-    Introduction
-
-SWMM conceptualizes a drainage system as a series of water and material flows between several major environmental compartments. These compartments and the SWMM objects they contain include:
-    The Atmosphere compartment, which generates precipitation and deposits pollutants onto the land surface compartment. SWMM uses Rain Gage objects to represent rainfall inputs to the system.
-    The Land Surface compartment, which is represented through one or more Subcatchment objects. It receives precipitation from the Atmospheric compartment in the form of rain or snow; it sends outflow in the form of infiltration to the Groundwater compartment and also as surface runoff and pollutant loadings to the Transport compartment.
-    The Groundwater compartment receives infiltration from the Land Surface compartment and transfers a portion of this inflow to the Transport compartment. This compartment is modeled using Aquifer objects.
-    The Transport compartment contains a network of conveyance elements (channels, pipes, pumps, and regulators) and storage/treatment units that transport water to outfalls or to treatment facilities. Inflows to this compartment can come from surface runoff, groundwater interflow, sanitary dry weather flow, or from user-defined hydrographs. The components of the Transport compartment are modeled with Node and Link objects
-
-Not all compartments need appear in a particular SWMM model. For example, one could model just the transport compartment, using pre-defined hydrographs as inputs. 
-
-
-
-    Visual Objects
-
-Figure 3-1 depicts how a collection of SWMM’s visual objects might be arranged together to represent a stormwater drainage system. These objects can be displayed on a map in the SWMM workspace. The following sections describe each of these objects.
-
- 
-Figure 3 1  Physical objects used to model a drainage system
-
-Rain Gages
-
-Rain Gages supply precipitation data for one or more subcatchment areas in a study region. The rainfall data can be either a user-defined time series or come from an external file. Several different popular rainfall file formats currently in use are supported, as well as a standard user-defined format. More details on these formats are presented in Section 11.3.
-
-The principal input properties of rain gages include:
-    rainfall data type (e.g., intensity, volume, or cumulative volume)
-    recording time interval (e.g., hourly, 15-minute, etc.)
-    source of rainfall data (input time series or external file)
-    name of rainfall data source
-
-Subcatchments
-
-Subcatchments are hydrologic units of land whose topography and drainage system elements direct surface runoff to a single discharge point. The user is responsible for dividing a study area into an appropriate number of subcatchments, and for identifying the outlet point of each subcatchment. Discharge outlet points can be either nodes of the drainage system or other subcatchments.
-
-Subcatchments are divided into pervious and impervious subareas. Surface runoff can infiltrate into the upper soil zone of the pervious subarea, but not through the impervious subarea. Impervious areas are themselves divided into two subareas - one that contains depression storage and another that does not. Runoff flow from one subarea in a subcatchment can be routed to the other subarea, or both subareas can drain to the subcatchment outlet.
-
-Infiltration of rainfall from the pervious area of a subcatchment into the unsaturated upper soil zone can be described using five different models:
-    Classic Horton infiltration
-    Modified Horton infiltration
-    Green-Ampt infiltration
-    Modified Green-Ampt infiltration
-    SCS Curve Number infiltration
-
-To model the accumulation, re-distribution, and melting of precipitation that falls as snow on a subcatchment, it must be assigned a Snow Pack object. To model groundwater flow between an aquifer underneath the subcatchment and a node of the drainage system, the subcatchment must be assigned a set of Groundwater parameters. Pollutant buildup and washoff from subcatchments are associated with the Land Uses assigned to the subcatchment. Capture and retention of rainfall/runoff using different types of low impact development practices (such as bio-retention cells, infiltration trenches, porous pavement, vegetative swales, and rain barrels) can be modeled by assigning a set of pre-designed LID controls to the subcatchment.
-
-The other principal input parameters for subcatchments include:
-    assigned rain gage
-    outlet node or subcatchment
-    total area
-    percent imperviousness area
-    average slope
-    characteristic width of overland flow
-    Manning's roughness (n) for overland flow on both pervious and impervious areas
-    depression storage in both pervious and impervious areas
-    percent of impervious area with no depression storage.
-
-Junction Nodes
-
-Junctions are drainage system nodes where links join together. Physically they can represent the confluence of natural surface channels, manholes in a sewer system, or pipe connection fittings. External inflows can enter the system at junctions. Excess water at a junction can become partially pressurized while connecting conduits are surcharged and can either be lost from the system or be allowed to pond atop the junction and subsequently drain back into the junction.
-
-The principal input parameters for a junction are:
-    invert (channel or manhole bottom) elevation
-    height to ground surface
-    ponded surface area when flooded (optional)
-    external inflow data (optional).
-
-Outfall Nodes
-
-Outfalls are terminal nodes of the drainage system used to define final downstream boundaries under Dynamic Wave flow routing. For other types of flow routing they behave as a junction. Only a single link can be connected to an outfall node, and the option exists to have the outfall discharge onto a subcatchment's surface.
-
-The boundary conditions at an outfall can be described by any one of the following stage relationships:
-    the critical or normal flow depth in the connecting conduit
-    a fixed stage elevation
-    a tidal stage described in a table of tide height versus hour of the day
-    a user-defined time series of stage versus time.
-
-The principal input parameters for outfalls include:
-    invert elevation
-    boundary condition type and stage description
-    presence of a flap gate to prevent backflow through the outfall.
-Flow Divider Nodes
-
-Flow Dividers are drainage system nodes that divert inflows to a specific conduit in a prescribed manner. A flow divider can have no more than two conduit links on its discharge side. Flow dividers are only active under Steady Flow and Kinematic Wave routing and are treated as simple junctions under Dynamic Wave routing.
-
-There are four types of flow dividers, defined by the manner in which inflows are diverted:
-
-Cutoff Divider:    diverts all inflow above a defined cutoff value.
-Overflow Divider:    diverts all inflow above the flow capacity of the non-diverted conduit.
-Tabular Divider:    uses a table that expresses diverted flow as a function of total inflow.
-Weir Divider:    uses a weir equation to compute diverted flow.
-
-The flow diverted through a weir divider is computed by the following equation
-
-Q_div=C_W 〖(fH_W)〗^1.5
-
-where Qdiv = diverted flow, Cw = weir coefficient, Hw = weir height and f is computed as
-
-f=(Q_in-Q_min)/(Q_max-Q_min )
-
-where Qin is the inflow to the divider, Qmin is the flow at which diversion begins, and Q_max=C_W H_W^1.5. The user-specified parameters for the weir divider are Qmin, Hw, and Cw.
-
-The principal input parameters for a flow divider are:
-    junction parameters (see above)
-    name of the link receiving the diverted flow
-    method used for computing the amount of diverted flow.
-
-Storage Units
-
-Storage Units are drainage system nodes that provide storage volume. Physically they could represent storage facilities as small as a catch basin or as large as a lake. The volumetric properties of a storage unit are described by a function or table of surface area versus height. In addition to receiving inflows and discharging outflows to other nodes in the drainage network, storage nodes can also lose water from surface evaporation and from seepage into native soil.
-
-The principal input parameters for storage units include:
-    invert (bottom) elevation
-    maximum depth
-    depth-surface area data
-    evaporation potential
-    seepage parameters (optional)
-    external inflow data (optional).
-
-Conduits
-
-Conduits are pipes or channels that move water from one node to another in the conveyance system. Their cross-sectional shapes can be selected from a variety of standard open and closed geometries as listed in Table 3-1.
-
-Most open channels can be represented with a rectangular, trapezoidal, or user-defined irregular cross-section shape. For irregular sections a Transect object is used to define how depth varies with distance across the cross-section (see Section 3.3.5 below). Most new drainage and sewer pipes are circular while culverts typically have elliptical, rectangular or arch shapes. Elliptical and Arch pipes come in standard sizes that are listed in Appendix A.12 and A.13. The Filled Circular shape allows the bottom of a circular pipe to be filled with sediment and thus limit its flow capacity. The Custom Closed Shape allows any closed geometrical shape that is symmetrical about the center line to be defined by supplying a Shape Curve for the cross section (see Section 3.3.13 below).
-
-SWMM uses the Manning equation to express the relationship between flow rate (Q), cross-sectional area (A), hydraulic radius (R), and slope (S) in all conduits. For standard U.S. units,
-
-Q=1.49/n AR^(2/3) S^(1/2)
-
-where n is the Manning roughness coefficient. The slope S is interpreted as either the conduit slope or the friction slope (i.e., head loss per unit length), depending on the flow routing method used. 
-
-
-Table 3-1 Available cross section shapes for conduits
-Name    Parameters    Shape    Name    Parameters    Shape
-Circular    Full Height         Circular Force Main    Full Height,
-Roughness     
-Filled Circular    Full Height,
-Filled Depth         Rectangular - Closed    Full Height,
-Width     
-Rectangular – Open    Full Height,
-Width         Trapezoidal    Full Height,
-Base Width,
-Side Slopes     
-Triangular    Full Height,
-Top Width         Horizontal Ellipse    Full Height,
-Max. Width     
-Vertical Ellipse    Full Height,
-Max. Width         Arch    Full Height,
-Max. Width     
-Parabolic    Full Height,
-Top Width         Power    Full Height,
-Top Width,
-Exponent     
-Rectangular-Triangular    Full Height,
-Top Width,
-Triangle Height         Rectangular-Round    Full Height,
-Top Width,
-Bottom Radius     
-Modified Baskethandle    Full Height,
-Bottom Width,
-Top Radius         Egg    Full Height     
-Horseshoe    Full Height         Gothic    Full Height     
-Catenary    Full Height         Semi-Elliptical    Full Height     
-Baskethandle    Full Height         Semi-Circular    Full Height     
-Irregular Channel    Transect Coordinates         Custom Closed Shape    Full Height, Shape Curve
-Coordinates      
-Street or Roadway    See Section 3.3.6         
-
-
-
-For pipes with Circular Force Main cross-sections either the Hazen-Williams or Darcy-Weisbach formula is used in place of the Manning equation for fully pressurized flow. For U.S. units the Hazen-Williams formula is:
-
-Q=1.318CAR^0.63 S^0.54
-
-where C is the Hazen-Williams C-factor which varies inversely with surface roughness and is supplied as one of the cross-section’s parameters. The Darcy-Weisbach formula is:
-
-Q=√(8g/f) AR^(1/2) S^(1/2)
-
-where g is the acceleration of gravity and f is the Darcy-Weisbach friction factor. For turbulent flow, the latter is determined from the height of the roughness elements on the walls of the pipe (supplied as an input parameter) and the flow’s Reynolds Number using the Colebrook-White equation. The choice of which equation to use is a user-supplied option.
-
-     A conduit does not have to be assigned a Force Main shape for it to pressurize. Any of the closed cross-section shapes can potentially pressurize and thus function as force mains that use the Manning equation to compute friction losses. 
-
-A constant rate of exfiltration of water along the length of the conduit can be modeled by supplying a Seepage Rate value (in/hr or mm/hr). This only accounts for seepage losses, not infiltration of rainfall dependent groundwater. The latter can be modeled using SWMM’s RDII feature (see Section 3.3.8).
-
-A conduit can also be designated to act as a culvert (see Figure 3-2) if a Culvert Inlet Geometry code number is assigned to it. These code numbers are listed in Appendix A.10. Culvert conduits are checked continuously during dynamic wave flow routing to see if they operate under Inlet Control as defined in the Federal Highway Administration’s publication Hydraulic Design of Highway Culverts Third Edition (Publication No. FHWA-HIF-12-026, April 2012). Under inlet control a culvert obeys a particular flow versus inlet depth rating curve whose shape depends on the culvert’s shape, size, slope, and inlet geometry.
-
-Street and channel conduits with storm drain inlet structures (see Figure 3-3) use the methods described in the Federal Highway Administration's publication Urban Drainage Design Manual - HEC-22 (Publication No. FHWA-NHI-10-009, August 2013) to determine the amount of flow they capture.
-
- 
-Figure 3 2  Concrete box culvert
- 
-Figure 3 3  Storm drain inlet
-
-The principal input parameters for conduits are:
-    names of the inlet and outlet nodes
-    offset height or elevation above the inlet and outlet node inverts
-    length
-    Manning's roughness coefficient (n)
-    cross-sectional geometry
-    entrance/exit losses (optional)
-    seepage rate (optional)
-    presence of a flap gate to prevent reverse flow (optional)
-    culvert type code number if the conduit acts as a culvert (optional)
-    name of any inlet structure placed in a street or channel conduit (optional).
-
-
-Pumps
-
-Pumps are links used to lift water to higher elevations. A pump curve describes the relation between a pump's flow rate and conditions at its inlet and outlet nodes. Five different types of pump curves are supported:
-
-Type1 (Fixed/Volume)
-Consists of a series of constant flow rates that apply over a series of volume intervals at the pump’s inlet node.     
-Type2 (Fixed/Depth)
-Similar to a Type1 pump except that the fixed flow rate levels vary over a set of depth intervals at the pump’s inlet node.     
-Type3 (Variable/Head)
-Uses a pump characteristic curve at some nominal impeller speed to relate flow rate and delivered head.     
-Type4 (Variable/Depth)
-A variable speed pump where flow varies continuously with inlet node water depth.
-     
-Type5 (Variable/Affinity)
-A variable speed version of the Type3 pump where the pump curve shifts position when control rules change the pump’s relative speed setting (see Section 3.3.9).     
-
-SWMM also supports an "Ideal" transfer pump that does not require a pump curve and is used mainly for preliminary analysis. Its flow rate equals the inflow rate to its inlet node no matter what the head difference is between its inlet and outlet nodes. 
-
-The on/off status of pumps can be controlled dynamically by specifying startup and shutoff water depths at the inlet node or through user-defined Control Rules. Rules can also be used to simulate variable speed drives that modulate pump flow. For a Type 5 pump, its operating curve shifts position such that flow changes in direct proportion to the controlled speed setting while head changes in proportion to the setting squared.
-
-The principal input parameters for a pump include:
-    names of its inlet and outlet nodes
-    name of its pump curve (or * for an Ideal pump)
-    initial on/off status
-    startup and shutoff depths (optional).
-
-Flow Regulators
-
-Flow Regulators are structures or devices used to control and divert flows within a conveyance system. They are typically used to:
-    control releases from storage facilities
-    prevent unacceptable surcharging
-    divert flow to treatment facilities and interceptors
-
-SWMM can model the following types of flow regulators: Orifices, Weirs, and Outlets.
-
-Orifices
-
-Orifices are used to model outlet and diversion structures in drainage systems, which are typically openings in the wall of a manhole, storage facility, or control gate. They are internally represented in SWMM as a link connecting two nodes. An orifice can have either a circular or rectangular shape, be located either at the bottom or along the side of the upstream node, and have a flap gate to prevent backflow.
-
-Orifices can be used as storage unit outlets under all types of flow routing. If not attached to a storage unit node, they can only be used in drainage networks that are analyzed with Dynamic Wave flow routing.
-
-The flow through a fully submerged orifice is computed as
-Q=CA√2gh
-where Q = flow rate, C = discharge coefficient, A = area of orifice opening, g = acceleration of gravity, and h = head difference across the orifice. The height of an orifice's opening can be controlled dynamically through user-defined Control Rules. This feature can be used to model gate openings and closings. Flow through a partially full orifice is computed using an equivalent weir equation.
-
-The principal input parameters for an orifice include:
-    names of its inlet and outlet nodes
-    configuration (bottom or side)
-    shape (circular or rectangular)
-    height or elevation above the inlet node invert
-    discharge coefficient
-    time to open or close (optional).
-
-Weirs
-
-Weirs, like orifices, are used to model outlet and diversion structures in a drainage system. Weirs are typically located across a channel, along its side, or at the top of a storage unit. They are internally represented in SWMM as a link connecting two nodes, where the weir itself is placed at the upstream node. A flap gate can be included to prevent backflow.
-
-Five varieties of weirs are available, each incorporating a different formula for computing flow across the weir as listed in Table 3-2.
-
-Table 3 2 Available types of weirs
-Weir Type    Cross Section Shape    Flow Formula
-Transverse     Rectangular    C_W Lh^(3/2)
-Side flow     Rectangular    C_W Lh^(5/3)
-V-notch     Triangular    C_W Sh^(5/2)
-Trapezoidal    Trapezoidal    C_W Lh^(3/2)+C_WS Sh^(5/2)
-Roadway    Rectangular    C_W Lh^(3/2)
-Cw = weir discharge coefficient, L = weir length, S = side slope of 
-V-notch or trapezoidal weir, h = head difference across the weir,
-Cws = discharge coefficient through sides of trapezoidal weir.
-
-The Roadway weir is a broad crested rectangular weir used model roadway crossings usually in conjunction with culvert-type conduits (see Figure 3-2). It uses curves from the Federal Highway Administration publication Hydraulic Design of Highway Culverts Third Edition (Publication No. FHWA-HIF-12-026, April 2012) to determine CW as a function of h and roadway width.
-
-Weirs can be used as storage unit outlets under all types of flow routing. If not attached to a storage unit, they can only be used in drainage networks that are analyzed with Dynamic Wave flow routing.
-
-The height of the weir crest above the inlet node invert can be controlled dynamically through user-defined Control Rules. This feature can be used to model inflatable dams.
-
-Weirs can either be allowed to surcharge or not. A surcharged weir will use an equivalent orifice equation to compute the flow through it. Weirs placed in open channels would normally not be allowed to surcharge while those placed in closed diversion structures or those used to represent storm drain inlet openings would be allowed to.
-
-The principal input parameters for a weir include:
-    names of its inlet and outlet nodes
-    shape and geometry
-    crest height or elevation above the inlet node invert
-    discharge coefficient. 
-
-Outlets
-
-Outlets are flow control devices that are typically used to control outflows from storage units. They are used to model special head-discharge relationships that cannot be characterized by pumps, orifices, or weirs. Outlets are internally represented in SWMM as a link connecting two nodes. An outlet can also have a flap gate that restricts flow to only one direction.
-
-Outlets attached to storage units are active under all types of flow routing. If not attached to a storage unit, they can only be used in drainage networks analyzed with Dynamic Wave flow routing.
-
-A user-defined rating curve determines an outlet's discharge flow as a function of either the freeboard depth above the outlet's opening or the head difference across it. Control Rules can be used to dynamically adjust this flow when certain conditions exist.
- 
-The principal input parameters for an outlet include:
-    names of its inlet and outlet nodes
-    height or elevation above the inlet node invert
-    function or table containing its head (or depth) - discharge relationship.
-
-Map Labels
-
-Map Labels are optional text labels added to SWMM's Study Area Map to help identify particular objects or regions of the map. The labels can be drawn in any Windows font, freely edited and be dragged to any position on the map.
-
-    Non-Visual Objects
-
-In addition to physical objects that can be displayed visually on a map, SWMM utilizes several classes of non-visual data objects to describe additional characteristics and processes within a study area.
-
-Climatology
-
-Temperature
-
-Air temperature data are used when simulating snowfall and snowmelt processes during runoff calculations. They can also be used to compute daily evaporation rates. If these processes are not being simulated then temperature data are not required. Air temperature data can be supplied to SWMM from one of the following sources:
-    a user-defined time series of point values (values at intermediate times are interpolated)
-    an external climate file containing daily minimum and maximum values (SWMM fits a sinusoidal curve through these values depending on the day of the year).
-For user-defined time series, temperatures are in degrees F for US units and degrees C for metric units. The external climate file can also be used to directly supply evaporation and wind speed as well.
-
-Evaporation
-
-Evaporation can occur for standing water on subcatchment surfaces, for subsurface water in groundwater aquifers, for water traveling through open channels, and for water held in storage units. Evaporation rates can be stated as:
-    a single constant value  
-    a set of monthly average values  
-    a user-defined time series of values
-    values computed from the daily temperatures contained in an external climate file  
-    daily values read directly from an external climate file. 
-These values represent potential rates. The actual amount of water evaporated will depend on the amount available.
-
-If rates are read directly from a climate file, then a set of monthly pan coefficients should also be supplied to convert the pan evaporation data to free water-surface values. An option is also available to allow evaporation only during periods with no precipitation.
-
-Wind Speed
-
-Wind speed is an optional climatic variable that is used only for snowmelt calculations.  SWMM can use either a set of monthly average speeds or wind speed data contained in the same climate file used for daily minimum/maximum temperatures.
-
-Snowmelt
-
-Snowmelt parameters are climatic variables that apply across the entire study area when simulating snowfall and snowmelt. They include:
-    the air temperature at which precipitation falls as snow
-    heat exchange properties of the snow surface
-    study area elevation, latitude, and longitude correction
-
-Areal Depletion
-
-Areal depletion refers to the tendency of accumulated snow to melt non-uniformly over the surface of a subcatchment. As the melting process proceeds, the area covered by snow gets reduced. This behavior is described by an Areal Depletion Curve that plots the fraction of total area that remains snow covered against the ratio of the actual snow depth to the depth at which there is 100% snow cover. A typical ADC for a natural area is shown in Figure 3-4. Two such curves can be supplied to SWMM, one for impervious areas and another for pervious areas.
-
- 
-Figure 3 4  Areal depletion curve for a natural area
-
-Climate Adjustments
-
-Climate Adjustments are optional modifications applied to the temperature, evaporation rate, and rainfall intensity that SWMM would otherwise use at each time step of a simulation. Separate sets of adjustments that vary periodically by month of the year can be assigned to these variables. They provide a simple way to examine the effects of future climate change without having to modify the original climatic time series.
-
-A set of monthly adjustments can also be applied to the hydraulic conductivity used in computing rainfall infiltration on all pervious land surfaces, including those in all LID units, and for exfiltration from all storage nodes and conduits. These can reflect the increase of hydraulic conductivity with increasing temperature or the effect that seasonal changes in land surface conditions, such as frozen ground, can have on infiltration capacity. They can be overridden for individual subcatchments (and their LID units) by assigning a monthly infiltration adjustment Time Pattern to a subcatchment.  Monthly adjustment time patterns for depression storage and pervious surface roughness coefficient (Mannings n) can also be specified for individual subcatchments
-
-
-
-Snow Packs
-
-Snow Pack objects contain parameters that characterize the buildup, removal, and melting of snow over three types of subareas within a subcatchment: 
-    The Plowable snow pack area consists of a user-defined fraction of the total impervious area. It is meant to represent such areas as streets and parking lots where plowing and snow removal can be done.
-    The Impervious snow pack area covers the remaining impervious area of a subcatchment.
-    The Pervious snow pack area encompasses the entire pervious area of a subcatchment.
-
-Each of these three areas is characterized by the following parameters:
-    minimum and maximum snow melt coefficients
-    minimum air temperature for snow melt to occur
-    snow depth above which 100% areal coverage occurs
-    initial snow depth
-    initial and maximum free water content in the pack.
-
-In addition, a set of snow removal parameters can be assigned to the Plowable area. These parameters consist of the depth at which snow removal begins and the fractions of snow moved onto various other areas.
-
-Subcatchments are assigned a snow pack object through their Snow Pack property. A single snow pack object can be applied to any number of subcatchments. Assigning a snow pack to a subcatchment simply establishes the melt parameters and initial snow conditions for that subcatchment. Internally, SWMM creates a "physical" snow pack for each subcatchment, which tracks snow accumulation and melting for that particular subcatchment based on its snow pack parameters, its amount of pervious and impervious area, and the precipitation history it sees.
-
-Aquifers
-
-Aquifers are sub-surface groundwater zones used to model the vertical movement of water infiltrating from the subcatchments that lie above them. They also permit the infiltration of groundwater into the drainage system, or exfiltration of surface water from the drainage system, depending on the hydraulic gradient that exists. Aquifers are only required in models that need to explicitly account for the exchange of groundwater with the drainage system or to establish base flow and recession curves in natural channels and non-urban systems. The parameters of an aquifer object can be shared by several subcatchments but there is no exchange of groundwater between subcatchments. A drainage system node can exchange groundwater with more than one subcatchment.
-
-Aquifers are represented using two zones – an un-saturated zone and a saturated zone. Their behavior is characterized using such parameters as soil porosity, hydraulic conductivity, evapotranspiration depth, bottom elevation, and loss rate to deep groundwater. In addition, the initial water table elevation and initial moisture content of the unsaturated zone must be supplied.
-
-Aquifers are connected to subcatchments and to drainage system nodes through a subcatchment's Groundwater Flow property. This property also contains parameters that govern the rate of groundwater flow between the aquifer's saturated zone and the drainage system node. 
-
-Unit Hydrographs
-
-Unit Hydrographs (UHs) estimate rainfall-dependent infiltration and inflow (RDII) into a sewer system. A UH set contains up to three such hydrographs, one for a short-term response, one for an intermediate-term response, and one for a long-term response. A UH group can have up to 12 UH sets, one for each month of the year. Each UH group is considered as a separate object by SWMM, and is assigned its own unique name along with the name of the rain gage that supplies rainfall data to it.
-
-Each unit hydrograph, as shown in Figure 3-5, is defined by three parameters:
-    R: the fraction of rainfall volume that enters the sewer system
-    T: the time from the onset of rainfall to the peak of the UH in hours
-    K: the ratio of time to recession of the UH to the time to peak
-
-A unit hydrograph can also have a set of Initial Abstraction (IA) parameters associated with it. These determine how much rainfall is lost to interception and depression storage before any excess rainfall is generated and transformed into RDII flow by the hydrograph. The IA parameters consist of:
-    a maximum possible depth of IA (inches or mm),
-    a recovery rate (inches/day or mm/day) at which stored IA is depleted during dry periods,
-    an initial depth of stored IA (inches or mm).
-
- 
-Figure 3 5  An RDII unit hydrograph
-
-To generate RDII into a drainage system node, the node must identify (through its Inflows property) the UH group and the area of the surrounding sewershed that contributes RDII flow.
-
-     An alternative to using unit hydrographs to define RDII flow is to create an external RDII interface file, which contains RDII time series data. See Section 11.7.
-
-     Unit hydrographs could also be used to replace SWMM's main rainfall-runoff process that uses Subcatchment objects, provided that properly calibrated UHs are utilized. In this case what SWMM calls RDII inflow to a node would actually represent overland runoff.
-
-Transects
-
-Transects refer to the geometric data that describe how bottom elevation varies with horizontal distance over the cross-section of a natural channel or irregular-shaped conduit. Figure 3-6 displays an example transect for a natural channel.
-
-Each transect must be given a unique name. Conduits refer to that name to represent their shape. A special Transect Editor is available for editing the station-elevation data of a transect. SWMM internally converts these data into tables of area, top width, and hydraulic radius versus channel depth. In addition, as shown in Figure 3-6, each transect can have a left and right overbank section whose Manning's roughness coefficient can be different from that of the main channel. This feature can provide more realistic estimates of channel conveyance under high flow conditions.
-
- 
-Figure 3 6  Example of a natural channel transect
-
-Streets
-
-Streets are a specialized form of transect that describes the typical cross-section geometry of a street or roadway. The Figure 3-7 shows a half-street layout along with the dimensions a user needs to provide.
-
- 
-Figure 3 7 Definitional sketch of a Street cross-section
-
-Each street section object is assigned an ID name that a conduit can refer to for describing its cross-section geometry. A Street Section Editor is available for providing a street section's dimensions and whether it is one-sided or two-sided.
-Inlets
-
-Street inlets are curb and gutter openings that convey runoff from streets into below-ground sewers. Drop inlets serve a similar purpose for open rectangular and trapezoidal channels. SWMM can compute the amount of flow captured by inlets and sent to designated sewer nodes using the U.S. Federal Highway Administration’s HEC-22 methodology . The type, sizing, and spacing of street inlets will determine if the spread and depth of water on roadways can be maintained at acceptable levels. 
-
-To analyze street drainage with SWMM a site is represented as a dual drainage system consisting of both street conduits along the ground surface and sewer conduits below ground (see Figure 3-8).  An inlet structure will divert some portion of the street flow it carries into a designated node of the sewer system with the rest bypassed to downstream street conduits. When an inlet’s sewer node reaches its full depth any excess sewer flow that causes it to flood is routed back into the street's downstream node rather than having it leave the system as it normally would.
- 
-Figure 3 8  Representation of a dual drainage system
-
-As shown in Figure 3-8, inlets can be located either on a continuous sloping section of roadway (on-grade, sometimes referred to as a flow-by condition) or at a low point where flow tends to pool (on-sag, sometimes referred to as a sump condition).
-
-SWMM’s HEC-22 inlet capture equations support the inlet types shown in Figure 3-9. Drop inlets can only be used with open rectangular or trapezoidal channels while the other curb and gutter inlets can only be placed in conduits with Street cross-sections. An additional Custom type of inlet can be used in both streets and channels. Its capture efficiency is described by either a user-supplied Diversion curve (captured flow versus approach flow) or Rating curve (captured flow versus flow depth).
- 
-Figure 3 9  HEC-22 inlets supported by SWMM
-
-To add an analysis of street inlets to a SWMM project:
-    Create one network layout for streets and another for sewers.
-    Create a collection of street cross-section objects. 
-    For each street conduit, set its Shape property to one of the available street sections.  
-    Create a set of inlet structure design objects. 
-    Place a particular inlet structure design into a selected street conduit, assigning it a sewer node that receives its captured flow. 
-    Assign surface runoff from subcatchments or other external inflows to street conduit nodes. 
-A similar set of steps would be used to add drop inlets into open rectangular or trapezoidal channels. A summary of results for each street conduit (maximum flow depth and pavement spread) and for each inlet (percent capture at peak flow, frequency of bypass flow and frequency of sewer system backflow) will appear as a separate Street Flow table in SWMM's Summary Results report.
-Some additional considerations when modeling inlets are:
-    Conduits with inlets will be displayed on the Study Area Map with a   symbol near their midpoint and show their downstream node connected to the inlet's capture node with a dotted line when the Map Option to display link symbols is turned on.
-    The rim elevations of nodes that receive captured inlet flow do not have to match the invert elevations of the end node of the conduit containing the inlet.
-    Two-sided street conduits (that are symmetric about the street crown) use pairs of inlets placed on each curb side of the street.
-    Multiple inlets of the same design can be assigned to a conduit (as pairs for two-sided streets). For on-grade placement the flow captured by each inlet is determined sequentially, so that the approach flow to the next inlet in line is the bypass flow from the inlet before it.
-    Flow captured by inlets is limited by the amount that its sewer node can receive before it floods. If the node has no such capacity remaining then any excess flow that would cause it to flood is routed back through the inlet and onto the street.
-    Users can stipulate whether an inlet operates on-grade or on-sag or have SWMM decide based on the slopes of the conduits adjoining it. (On-sag refers to a sump or low point that all adjoining conduits slope towards.)
-    Inlets can have a degree of clogging and a flow capture restriction assigned to them.
-    For Kinematic Wave and Steady Flow routing it is recommended that storage nodes be used at the end of inlet conduits that converge at sag points since otherwise any non-captured flow will simply exit the system. This is not necessary for Dynamic Wave routing as any non-captured water will create a backwater effect raising water levels in the adjoining street conduits.
-
-External Inflows
-
-In addition to inflows originating from subcatchment runoff and groundwater, drainage system nodes can receive three other types of external inflows:
-    Direct Inflows - These are user-defined time series of inflows added directly into a node. They can be used to perform flow and water quality routing in the absence of any runoff computations (as in a study area where no subcatchments are defined).
-    Dry Weather Inflows - These are continuous inflows that typically reflect the contribution from sanitary sewage in sewer systems or base flows in pipes and stream channels. They are represented by an average inflow rate that can be periodically adjusted on a monthly, daily, and hourly basis by applying Time Pattern multipliers to this average value.
-    Rainfall-Dependent Infiltration and Inflow (RDII) - These are stormwater flows that enter sanitary or combined sewers due to "inflow" from direct connections of downspouts, sump pumps, foundation drains, etc. as well as "infiltration" of subsurface water through cracked pipes, leaky joints, poor manhole connections, etc. RDII can be computed for a given rainfall record based on set of triangular unit hydrographs (UH) that determine a short-term, intermediate-term, and long-term inflow response for each time period of rainfall. Any number of UH sets can be supplied for different sewershed areas and different months of the year. RDII flows can also be specified in an external RDII interface file.
-
-Direct, Dry Weather, and RDII inflows are properties associated with each type of drainage system node (junctions, outfalls, flow dividers, and storage units) and can be specified when nodes are edited. They can be used to perform flow and water quality routing in the absence of any runoff computations (as in a study area where no subcatchments are defined). It is also possible to make the outflows generated from an upstream drainage system be the inflows to a downstream system by using interface files. See Section 11.7 for further details.
-
-Control Rules
-
-Control Rules determine how pumps and regulators in the drainage system will be adjusted over the course of a simulation. Some examples of these rules are:
-
-Simple time-based pump control:
-RULE R1  
-IF SIMULATION TIME > 8  
-THEN PUMP 12 STATUS = ON  
-ELSE PUMP 12 STATUS = OFF
-
-Multiple-condition orifice gate control:
-RULE R2A  
-IF NODE 23 DEPTH > 12  
-AND LINK 165 FLOW > 100  
-THEN ORIFICE R55 SETTING = 0.5 
- 
-RULE R2B  
-IF NODE 23 DEPTH > 12  
-AND LINK 165 FLOW > 200  
-THEN ORIFICE R55 SETTING = 1.0  
- 
-
-RULE R2C  
-IF NODE 23 DEPTH <= 12  
-OR LINK 165 FLOW <= 100  
-THEN ORIFICE R55 SETTING = 0  
-
-Pump station operation:
-RULE R3A  
-IF NODE N1 DEPTH > 5  
-THEN PUMP N1A STATUS = ON  
- 
-RULE R3B  
-IF NODE N1 DEPTH > 7  
-THEN PUMP N1B STATUS = ON  
- 
-RULE R3C  
-IF NODE N1 DEPTH <= 3  
-THEN PUMP N1A STATUS = OFF  
-AND PUMP N1B STATUS = OFF
-
-Modulated weir height control:
-RULE R4
-IF NODE N2 DEPTH >= 0
-THEN WEIR W25 SETTING = CURVE C25
-
-Appendix C.3 describes the control rule format in more detail and the special Editor used to edit them.
-
-Pollutants
-
-SWMM can simulate the generation, inflow and transport of any number of user-defined pollutants. Required information for each pollutant includes: 
-    pollutant name  
-    concentration units (i.e., milligrams/liter, micrograms/liter, or counts/liter)  
-    concentration in rainfall
-    concentration in groundwater
-    concentration in rainfall-dependent infiltration and inflow
-    concentration in dry weather flow
-    initial concentration throughout the conveyance system
-    first-order decay coefficient.  
-
-Co-pollutants can also be defined in SWMM. For example, pollutant X can have a co-pollutant Y, meaning that the runoff concentration of X will have some fixed fraction of the runoff concentration of Y added to it.
-Pollutant buildup and washoff from subcatchment areas are determined by the land uses assigned to those areas. Input loadings of pollutants to the drainage system can also originate from external time series inflows as well as from dry weather inflows.
-
-Land Uses
-
-Land Uses are categories of development activities or land surface characteristics assigned to subcatchments. Examples of land use activities are residential, commercial, industrial, and undeveloped. Land surface characteristics might include rooftops, lawns, paved roads, undisturbed soils, etc. Land uses are used solely to account for spatial variation in pollutant buildup and washoff rates within subcatchments. 
-
-The SWMM user has many options for defining land uses and assigning them to subcatchment areas. One approach is to assign a mix of land uses for each subcatchment, which results in all land uses within the subcatchment having the same pervious and impervious characteristics. Another approach is to create subcatchments that have a single land use classification along with a distinct set of pervious and impervious characteristics that reflects the classification.
-
-The following processes can be defined for each land use category: 
-    pollutant buildup
-    pollutant washoff
-    street cleaning.
-
-Pollutant Buildup
-
-Pollutant buildup that accumulates within a land use category is described (or “normalized”) by either a mass per unit of subcatchment area or per unit of curb length. Mass is expressed in pounds for US units and kilograms for metric units. The amount of buildup is a function of the number of preceding dry weather days and can be computed using one of the following functions: 
-
-Power Function: Pollutant buildup (B) accumulates proportionally to time (t) raised to some power, until a maximum limit is achieved, 
-B=Min(C_1,C_2 t^(C_3 ))
-where C1 = maximum buildup possible (mass per unit of area or curb length), C2 = buildup rate constant, and C3 = time exponent. 
-
-Exponential Function: Buildup follows an exponential growth curve that approaches a maximum limit asymptotically, 
-B=C_1 (1-e^(-C_2 t))
-where C1 = maximum buildup possible (mass per unit of area or curb length) and C2 = buildup rate constant (1/days). 
-
-Saturation Function: Buildup begins at a linear rate that continuously declines with time until a saturation value is reached, 
-B=(C_1 t)/(C_2+t)
-where C1 = maximum buildup possible (mass per unit area or curb length) and C2 = half-saturation constant (days to reach half of the maximum buildup).
-
-External Time Series: This option allows one to use a Time Series to describe the rate of buildup per day as a function of time. The values placed in the time series would have units of mass per unit area (or curb length) per day. One can also provide a maximum possible buildup (mass per unit area or curb length) with this option and a scaling factor that multiplies the time series values.
- 
-Pollutant Washoff
-
-Pollutant washoff from a given land use category occurs during wet weather periods and can be described in one of the following ways: 
-
-Exponential Washoff: The washoff load (W) in units of mass per hour is proportional to the product of runoff raised to some power and to the amount of buildup remaining,
-W=C_1 q^(C_2 ) B
-where C1 = washoff coefficient, C2 = washoff exponent, q = runoff rate per unit area (inches/hour or mm/hour), and B = pollutant buildup in mass units. The buildup here is the total mass (not per area or curb length) and both buildup and washoff mass units are the same as used to express the pollutant's concentration (milligrams, micrograms, or counts).
-
-Rating Curve Washoff: The rate of washoff W in mass per second is proportional to the runoff rate raised to some power, 
-W=C_1 Q^(C_2 )
-where C1 = washoff coefficient, C2 = washoff exponent, and Q = runoff rate in user-defined flow units. 
-Event Mean Concentration: This is a special case of Rating Curve Washoff where the exponent is 1.0 and the coefficient C1 represents the washoff pollutant concentration in mass per liter (Note: the conversion between user-defined flow units used for runoff and liters is handled internally by SWMM). 
-
-Note that in each case buildup is continuously depleted as washoff proceeds, and washoff ceases when there is no more buildup available.
-
-Washoff loads for a given pollutant and land use category can be reduced by a fixed percentage by specifying a BMP Removal Efficiency that reflects the effectiveness of any BMP controls associated with the land use. It is also possible to use the Event Mean Concentration option by itself, without having to model any pollutant buildup at all. 
-
-Street Sweeping
-
-Street sweeping can be used on each land use category to periodically reduce the accumulated buildup of specific pollutants. The parameters that describe street sweeping include: 
-    days between sweeping  
-    days since the last sweeping at the start of the simulation  
-    the fraction of buildup of all pollutants that is available for removal by sweeping  
-    the fraction of available buildup for each pollutant removed by sweeping  
-Note that these parameters can be different for each land use, and the last parameter can vary also with pollutant.
-
-Treatment
-
-Removal of pollutants from the flow streams entering any drainage system node is modeled by assigning a set of treatment functions to the node. A treatment function can be any well-formed mathematical expression involving:
-    the pollutant concentration 
-    the removals of other pollutants 
-    any of several process variables, such as flow rate, depth, hydraulic residence time, etc.
-
-The result of the treatment function can be either a concentration (denoted by the letter C) or a fractional removal (denoted by R). For example, a first-order decay expression for BOD exiting from a storage node might be expressed as:
-C = BOD * exp(-0.05 * HRT)
-where HRT is the reserved variable name for hydraulic residence time. The removal of some trace pollutant that is proportional to the removal of total suspended solids (TSS) could be expressed as:
- R = 0.75 * R_TSS
-Section C.26 provides more details on how user-defined treatment equations are supplied to the program.
-
-Curves
-
-Curve objects are used to describe a functional relationship between two quantities. The following types of curves are used in SWMM:
-    Storage - describes how the surface area of a Storage Unit node varies with water depth.
-    Shape - describes how the width of a customized cross-sectional shape varies with height for a Conduit link.
-    Diversion - relates diverted outflow to total inflow for a Flow Divider node or a Custom inlet drain.
-    Tidal - describes how the stage at an Outfall node changes by hour of the day.
-    Pump - relates flow through a Pump link to the depth or volume of water at the upstream node or to the head delivered by the pump.
-    Rating - relates flow through an Outlet link to the freeboard depth or head difference of water across it; relates flow captured by a Custom inlet drain to the depth of water above it.
-    Control - determines how the control setting of a pump or flow regulator varies as a function of some control variable (such as water level at a particular node) as specified in a Modulated Control rule.
-    Weir – allows a weir’s discharge coefficient to vary with the hydraulic head across it.
-Each curve must be given a unique name and can be assigned any number of data pairs.
-
-
-Time Series 
-
-Time Series objects are used to describe how certain object properties vary with time. Time series can be used to describe: 
-
-
-    temperature data
-    evaporation data  
-    rainfall data 
-    water stage at outfall nodes  
-    external inflow hydrographs at drainage system nodes  
-    external inflow pollutographs at drainage system nodes
-    control settings for pumps and flow regulators..  
- 
-Each time series must be given a unique name and can be assigned any number of time-value data pairs. Time can be specified either as hours from the start of a simulation or as an absolute date and time-of-day. Time series data can either be entered directly into the program or be accessed from a user-supplied Time Series file.
-
-     For rainfall time series, it is only necessary to enter periods with non-zero rainfall amounts. SWMM interprets the rainfall value as a constant value lasting over the recording interval specified for the rain gage that utilizes the time series. For all other types of time series, SWMM uses interpolation to estimate values at times that fall in between the recorded values.
-     For times that fall outside the range of the time series, SWMM will use a value of 0 for rainfall and external inflow time series, and either the first or last series value for temperature, evaporation, and water stage time series.
-
-Time Patterns
-
-Time Patterns allow external Dry Weather Flow (DWF) to vary in a periodic fashion. They consist of a set of adjustment factors applied as multipliers to a baseline DWF flow rate or pollutant concentration. The different types of time patterns include: 
-Monthly     - one multiplier for each month of the year  
-Daily         - one multiplier for each day of the week  
-Hourly         - one multiplier for each hour from 12 AM to 11 PM  
-Weekend     - hourly multipliers for weekend days  
-Each Time Pattern must have a unique name and there is no limit on the number of patterns that can be created. Each dry weather inflow (either flow or quality) can have up to four patterns associated with it, one for each type listed above.
-Monthly time patterns can also be used to adjust the baseline values of the following hydrological parameters:
-    subcatchment depression storage
-    subcatchment pervious surface roughness 
-    soil infiltration recovery rate
-    groundwater evaporation rate.
-
-LID Controls
-
-LID Controls are low impact development practices designed to capture surface runoff and provide some combination of detention, infiltration, and evapotranspiration to it. They are considered as properties of a given subcatchment, similar to how Aquifers and Snow Packs are treated. SWMM can explicitly model eight different generic types of LID controls:
-
-     Bio-retention Cells are depressions that contain vegetation grown in an engineered soil mixture placed above a gravel drainage bed. They provide storage, infiltration and evaporation of both direct rainfall and runoff captured from surrounding areas.
-     Rain Gardens are a type of bio-retention cell consisting of just the engineered soil layer with no gravel bed below it.
-
-     Green Roofs are another variation of a bio-retention cell that have a soil layer laying atop a special drainage mat material that conveys excess percolated rainfall off of the roof.
-     Infiltration Trenches are narrow ditches filled with gravel that intercept runoff from upslope impervious areas. They provide storage volume and additional time for captured runoff to infiltrate the native soil below.
-
-     Continuous Permeable Pavement systems are excavated areas filled with gravel and paved over with a porous concrete or asphalt mix. Block Paver systems consist of impervious paver blocks placed on a sand or pea gravel bed with a gravel storage layer below.
-     Rain Barrels (or Cisterns) are containers that collect roof runoff during storm events and can either release or re-use the rainwater during dry periods. 
-
-     Rooftop Disconnection has downspouts discharge to pervious landscaped areas and lawns instead of directly into storm drains. It can also model roofs with directly connected drains that overflow onto pervious areas.
-     Vegetative Swales are channels or depressed areas with sloping sides covered with grass and other vegetation. They slow down the conveyance of collected runoff and allow it more time to infiltrate the native soil beneath it.
-Bio-retention cells, infiltration trenches, and permeable pavement systems can contain optional drain systems in their gravel storage beds to convey excess captured runoff off of the site and prevent the unit from flooding. They can also have an impermeable floor or liner that prevents any infiltration into the native soil from occurring. Infiltration trenches and permeable pavement systems can also be subjected to a decrease in hydraulic conductivity over time due to clogging. 
-LID units that contain drains can have a removal percentage assigned to each pollutant discharged through the drain. LID’s will also provide a reduction in pollutant mass load conveyed in their surface discharge due to the reduction in runoff flow volume they provide. 
-
-There are two different approaches for placing LID controls within a subcatchment:
-    place one or more controls in an existing subcatchment that will displace an equal amount of non-LID area from the subcatchment
-    create a new subcatchment devoted entirely to just a single LID practice.
-
-The first approach allows a mix of LIDs to be placed into a subcatchment, each treating a different portion of the runoff generated from the non-LID fraction of the subcatchment. Note that under this option the subcatchment's LIDs act in parallel -- it is not possible to make them act in series (i.e., have the outflow from one LID control become the inflow to another LID). Also, after LID placement the subcatchment's Percent Impervious and Width properties may require adjustment to compensate for the amount of original subcatchment area that has now been replaced by LIDs (see Figure 3-10 below). For example, suppose that a subcatchment which is 40% impervious has 75% of that area converted to a permeable pavement LID. After the LID is added the subcatchment's percent imperviousness should be changed to the percent of impervious area remaining divided by the percent of non-LID area remaining. This works out to (1 - 0.75)*40 / (100 - 0.75*40) or 14.3 %.
-
- 
-Figure 3 10  Adjustment of subcatchment parameters after LID placement
-
-Under this first approach the runoff available for capture by the subcatchment's LIDs is the runoff generated from its impervious area. If the option to re-route some fraction of this runoff to the pervious area is exercised, then only the remaining impervious runoff (if any) will be available for LID treatment. Also note that green roofs and roof disconnection only treat the precipitation that falls directly on them and do not capture runoff from other impervious areas in their subcatchment.
-
-The second approach allows LID controls to be strung along in series and also allows runoff from several different upstream subcatchments to be routed onto the LID subcatchment. If these single-LID subcatchments are carved out of existing subcatchments, then once again some adjustment of the Percent Impervious, Width and also the Area properties of the latter may be necessary. In addition, whenever an LID occupies the entire subcatchment the values assigned to the subcatchment's standard surface properties (such as imperviousness, slope, roughness, etc.) are overridden by those that pertain to the LID unit.
-
-
-    Computational Methods
-
-SWMM is a physically based, discrete-time simulation model. It employs principles of conservation of mass, energy, and momentum wherever appropriate. This section briefly describes the methods SWMM uses to model stormwater runoff quantity and quality through the following physical processes:
-    Surface Runoff
-    Groundwater
-    Surface Ponding        Infiltration
-    Snowmelt
-    Water Quality Routing        Groundwater
-    Flow Routing
-    Low Impact Development
-More detailed descriptions of SWMM’s computational procedures can be found in a series of three reference manuals      available on EPA’s SWMM web site. 
-
-Surface Runoff
-
-The conceptual view of surface runoff used by SWMM is illustrated in Figure 3-11 below. Each subcatchment surface is treated as a nonlinear reservoir. Inflow comes from precipitation and any designated upstream subcatchments. There are several outflows, including infiltration, evaporation, and surface runoff. The capacity of this "reservoir" is the maximum depression storage, which is the maximum surface storage provided by ponding, surface wetting, and interception. Surface runoff per unit area occurs only when the depth of water in the "reservoir" exceeds the maximum depression storage, ds, in which case the outflow is given by Manning's equation. Depth of water over the subcatchment (d) is continuously updated with time by solving numerically a water balance equation over the subcatchment.
-
-
- 
-Figure 3 11  Conceptual view of surface runoff
-
-Infiltration
-
-Infiltration is the process of rainfall penetrating the ground surface into the unsaturated soil zone of pervious subcatchments areas. SWMM offers four choices for modeling infiltration: 
-
-Horton's Method 
-This method is based on empirical observations showing that infiltration decreases exponentially from an initial maximum rate to some minimum rate over the course of a long rainfall event. Input parameters required by this method include the maximum and minimum infiltration rates, a decay coefficient that describes how fast the rate decreases over time, and a time it takes a fully saturated soil to completely dry. 
-
-Modified Horton Method
-This is a modified version of the classical Horton Method that uses the cumulative infiltration in excess of the minimum rate as its state variable (instead of time along the Horton curve),    providing a more accurate infiltration estimate when low rainfall intensities occur. It uses the same input parameters as does the traditional Horton Method.
-
-Green-Ampt Method 
-This method for modeling infiltration assumes that a sharp wetting front exists in the soil column, separating soil with some initial moisture content below from saturated soil above. The input parameters required are the initial moisture deficit of the soil, the soil's hydraulic conductivity, and the suction head at the wetting front. The recovery rate of moisture deficit during dry periods is empirically related to the hydraulic conductivity.
-
-Modified Green-Ampt Method
-This method modifies the original Green-Ampt procedure by not depleting moisture deficit in the top surface layer of soil during initial periods of low rainfall as was done in the original method. This change can produce more realistic infiltration behavior for storms with long initial periods where the rainfall intensity is below the soil’s saturated hydraulic conductivity.
-
-Curve Number Method 
-This approach is adopted from the NRCS (SCS) Curve Number method for estimating runoff. It assumes that the total infiltration capacity of a soil can be found from the soil's tabulated Curve Number. During a rain event this capacity is depleted as a function of cumulative rainfall and remaining capacity. The input parameters for this method are the curve number and the time it takes a fully saturated soil to completely dry.
-
-SWMM also allows the infiltration recovery rate to be adjusted by a fixed amount on a monthly basis to account for seasonal variation in such factors as evaporation rates and groundwater levels. This optional monthly soil recovery pattern is specified as part of a project's Evaporation data.
-
-Groundwater
-
-Figure 3-12 is a definitional sketch of the two-zone groundwater model that is used in SWMM. The upper zone is unsaturated with a variable moisture content of . The lower zone is fully saturated and therefore its moisture content is fixed at the soil porosity . The fluxes shown in the figure, expressed as volume per unit area per unit time, consist of the following:
-
- 
-Figure 3 12  Two-zone groundwater model
-
-fI    infiltration from the surface 
-fE     evapotranspiration from the upper zone which is a fixed fraction of the un-used surface evaporation
-fU      percolation from the upper to lower zone which depends on the upper zone moisture content  and depth dU
-fEL    evapotranspiration from the lower zone, which is a function of the depth of the upper zone dU 
-fL     seepage from the lower zone to deep groundwater which depends on the lower zone depth dL
-fG     lateral groundwater interflow to the drainage system, which depends on the lower zone depth dL as well as the depth in the receiving channel or node.
-
-After computing the water fluxes that exist during a given time step, a mass balance is written for the change in water volume stored in each zone so that a new water table depth and unsaturated zone moisture content can be computed for the next time step.
-
-Snowmelt
-
-The snowmelt routine in SWMM is a part of the runoff modeling process. It updates the state of the snow packs associated with each subcatchment by accounting for snow accumulation, snow redistribution by areal depletion and removal operations, and snow melt via heat budget accounting. Any snowmelt coming off the pack is treated as an additional rainfall input onto the subcatchment.
-
-At each runoff time step the following computations are made:
-    Air temperature and melt coefficients are updated according to the calendar date.
-    Any precipitation that falls as snow is added to the snow pack.
-    Any excess snow depth on the plowable area of the pack is redistributed according to the removal parameters established for the pack.
-    Areal coverage of snow on the impervious and pervious areas of the pack is reduced according to the Areal Depletion Curves defined for the study area.
-    The amount of snow in the pack that melts to liquid water is found using:
-    a heat budget equation for periods with rainfall, where melt rate increases with increasing air temperature, wind speed, and rainfall intensity
-    a degree-day equation for periods with no rainfall, where melt rate equals the product of a melt coefficient and the difference between the air temperature and the pack's base melt temperature.
-    If no melting occurs, the pack temperature is adjusted up or down based on the product of the difference between current and past air temperatures and an adjusted melt coefficient. If melting occurs, the temperature of the pack is increased by the equivalent heat content of the melted snow, up to the base melt temperature. Any remaining melt liquid beyond this is available to runoff from the pack.
-    The available snowmelt is then reduced by the amount of free water holding capacity remaining in the pack. The remaining melt is treated the same as an additional rainfall input onto the subcatchment.
-
-Flow Routing
-
-Flow routing within a conduit link in SWMM is governed by the conservation of mass and momentum equations for gradually varied, unsteady flow (i.e., the Saint Venant flow equations). The SWMM user has a choice on the level of sophistication used to solve these equations: 
-
-    Steady Flow Routing
-    Kinematic Wave Routing  
-    Dynamic Wave Routing  
-
-Each of these routing methods employs the Manning equation to relate flow rate to flow depth and bed (or friction) slope. For user-designated Force Main conduits, either the Hazen-Williams or Darcy-Weisbach equation can be used when pressurized flow occurs.
-
-Steady Flow Routing
-
-Steady Flow routing represents the simplest type of routing possible (actually no routing) by assuming that within each computational time step flow is uniform and steady. Thus it simply translates inflow hydrographs at the upstream end of the conduit to the downstream end, with no delay or change in shape. The normal flow equation is used to relate flow rate to flow area (or depth). 
-
-This type of routing cannot account for channel storage, backwater effects, entrance/exit losses, flow reversal or pressurized flow. It can only be used with dendritic conveyance networks, where each node has only a single outflow link (unless the node is a divider in which case two outflow links are required). This form of routing is insensitive to the time step employed and is really only appropriate for preliminary analysis using long-term continuous simulations.
-
-Kinematic Wave Routing
-
-This routing method solves the continuity equation along with a simplified form of the momentum equation in each conduit. The latter assumes that the slope of the water surface equal the slope of the conduit.
-
-The maximum flow that can be conveyed through a conduit is the full normal flow value. Any flow in excess of this entering the inlet node is either lost from the system or can pond atop the inlet node and be re-introduced into the conduit as capacity becomes available.
-
-Kinematic wave routing allows flow and area to vary both spatially and temporally within a conduit. This can result in attenuated and delayed outflow hydrographs as inflow is routed through the channel. However this form of routing cannot account for backwater effects, entrance/exit losses, flow reversal, or pressurized flow, and is also restricted to dendritic network layouts. It can usually maintain numerical stability with moderately large time steps, on the order of 1 to 5 minutes. If the aforementioned effects are not expected to be significant then this alternative can be an accurate and efficient routing method, especially for long-term simulations.
-
-Dynamic Wave Routing
-
-Dynamic Wave routing solves the complete one-dimensional Saint Venant flow equations and therefore produces the most theoretically accurate results. These equations consist of the continuity and momentum equations for conduits and a volume continuity equation at nodes. 
-
-With this form of routing it is possible to represent pressurized flow when a closed conduit becomes full, such that flows can exceed the full normal flow value. Flooding occurs when the water depth at a node exceeds the maximum available depth, and the excess flow is either lost from the system or can pond atop the node and re-enter the drainage system.
-
-Dynamic wave routing can account for channel storage, backwater, entrance/exit losses, flow reversal, and pressurized flow. Because it couples together the solution for both water levels at nodes and flow in conduits it can be applied to any general network layout, even those containing multiple downstream diversions and loops. It is the method of choice for systems subjected to significant backwater effects due to downstream flow restrictions and with flow regulation via weirs and orifices. This generality comes at a price of having to use much smaller time steps, on the order of a thirty seconds or less (SWMM can automatically reduce the user-defined maximum time step as needed to maintain numerical stability).
-
-Ponding and Pressurization
-
-Normally in flow routing, when the flow into a junction exceeds the capacity of the system to transport it further downstream, the excess volume overflows the system and is lost. An option exists to have instead the excess volume be stored atop the junction, in a ponded fashion, and be reintroduced into the system as capacity permits. Under Steady and Kinematic Wave flow routing, the ponded water is stored simply as an excess volume. For Dynamic Wave routing, which is influenced by the water depths maintained at nodes, the excess volume is assumed to pond over the node with a constant surface area. This amount of surface area is an input parameter supplied for the junction.
-
-Alternatively, the user may wish to represent the surface overflow system explicitly. In open channel systems this can include road overflows at bridges or culvert crossings as well as additional floodplain storage areas. In closed conduit systems, surface overflows may be conveyed down streets, alleys, or other surface routes to the next available stormwater inlet or open channel. Overflows may also be impounded in surface depressions such as parking lots, back yards or other areas.
-
-In sewer systems with pressurized pipes and force mains the hydraulic head at junction nodes can at times exceed the ground elevation under Dynamic Wave routing. This would normally result in an overflow which, as described above, can either be lost or ponded. SWMM allows the user to specify an additional "surcharge" depth for junction nodes that lets them pressurize and prevents any outflow until this additional depth is exceeded. If both ponding and pressurization are specified for a node ponding takes precedence and the surcharge depth is ignored. Ponding does not apply to storage nodes.
-
-Water Quality Routing
-
-Water quality routing within conduit links assumes that the conduit behaves as a continuously stirred tank reactor (CSTR). Although a plug flow reactor assumption might be more realistic, the differences will be small if the travel time through the conduit is on the same order as the routing time step. The concentration of a constituent exiting the conduit at the end of a time step is found by integrating the conservation of mass equation, using average values for quantities that might change over the time step such as flow rate and conduit volume. 
-
-Water quality modeling within storage unit nodes follows the same approach used for conduits. For other types of nodes that have no volume, the quality of water exiting the node is simply the mixture concentration of all water entering the node.
-
-The pollutant concentration in both a conduit and a storage node will be reduced by a first-order decay reaction if the pollutant’s first-order decay coefficient is not zero.
-
-LID Representation
-
-LID controls are represented by a combination of vertical layers whose properties are defined on a per-unit-area basis. This allows LIDs of the same design but differing area coverage to easily be placed within different subcatchments of a study area. During a simulation SWMM performs a moisture balance that keeps track of how much water moves between and is stored within each LID layer. As an example, the layers used to model a bio-retention cell and the flow pathways between them are shown in Figure 3-13. The various possible layers consist of the following:
-
- 
-Figure 3 13  Conceptual diagram of a bio-retention cell LID
-
-    The Surface Layer corresponds to the ground (or pavement) surface that receives direct rainfall and runon from upstream land areas, stores excess inflow in depression storage, and generates surface outflow that either enters the drainage system or flows onto downstream land areas.
-    The Pavement Layer is the layer of porous concrete or asphalt used in continuous permeable pavement systems, or is the paver blocks and filler material used in modular systems.
-    The Soil Layer is the engineered soil mixture used in bio-retention cells to support vegetative growth. It can also be a sand layer placed beneath a pavement layer to provide bedding and filtration.
-    The Storage Layer is a bed of crushed rock or gravel that provides storage in bio-retention cells, porous pavement, and infiltration trench systems. For a rain barrel it is simply the barrel itself.
-    The Drain System conveys water out of the gravel storage layer of bio-retention cells, permeable pavement systems, and infiltration trenches (typically with slotted pipes) into a common outlet pipe or chamber. For rain barrels it is simply the drain valve at the bottom of the barrel while for rooftop disconnection it is the roof gutter and downspout system.
-    The Drainage Mat Layer is a mat or plate placed between the soil media and the roof in a green roof whose purpose is to convey any water that drains through the soil layer off of the roof.
-Table 3-3 indicates which combination of layers applies to each type of LID (x means required, o means optional). 
-
-Table 3 3 Layers used to model different types of LID units
-LID Type    Surface    Pavement    Soil    Storage    Drain    Drainage Mat
-Bio-Retention Cell    x        x    o    o    
-Rain Garden    x        x            
-Green Roof    x        x            x
-Permeable Pavement    x    x    o    x    o    
-Infiltration Trench    x            x    o    
-Rain Barrel                x    x    
-Roof Disconnection    x                x    
-Vegetative Swale    x                    
-
-
-All of the LID controls provide some amount of rainfall/runoff storage and evaporation of stored water (except for rain barrels). Infiltration into native soil occurs in vegetative swales and can also occur in bio-retention cells, rain gardens, permeable pavement systems, and infiltration trenches if those systems do not employ an optional impermeable bottom liner. Infiltration trenches and permeable pavement systems can also be subjected to clogging. This reduces their hydraulic conductivity over time proportional to the cumulative hydraulic loading they receive.
-
-The performance of the LID controls placed in a subcatchment is reflected in the overall runoff, infiltration, and evaporation rates computed for the subcatchment as normally reported by SWMM. SWMM's Status Report also contains a section entitled LID Performance Summary that provides an overall water balance for each LID control placed in each subcatchment. The components of this water balance include total inflow, infiltration, evaporation, surface runoff, drain flow and initial and final stored volumes, all expressed as inches (or mm) over the LID's area. Optionally, the entire time series of flux rates and moisture levels for a selected LID control in a given subcatchment can be written to a tab delimited text file for easy viewing and graphing in a spreadsheet program (such as Microsoft Excel).
-
-
diff --git a/docs/manuals/user/manual/Chapter4.md b/docs/manuals/user/manual/Chapter4.md
deleted file mode 100644
index 2440d83c6..000000000
--- a/docs/manuals/user/manual/Chapter4.md
+++ /dev/null
@@ -1,371 +0,0 @@
-@page user_manual_chapter_4 CHAPTER 4 - SWMM’S MAIN WINDOW
-
-@tableofcontents
-
-This chapter discusses the essential features of SWMM’s workspace. It describes the main menu bar, the tool and status bars, and the three windows used most often – the Study Area Map, the Browser, and the Property Editor. It also shows how to set program preferences.
-
-    Overview
-
-The EPA SWMM main window is pictured below. It consists of the following user interface elements: a Main Menu, a Main Toolbar, a Status Bar, the Study Area Map window containing a Map Toolbar, a Browser panel, and a Property Editor window. A description of each of these elements is provided in the sections that follow. 
-
- 
-
-
-          
- 
-    Main Menu
-
-The Main Menu located across the top of the EPA SWMM main window contains a collection of menus used to control the program. These include:
-    File Menu
-    Edit Menu
-    View Menu
-    Project Menu
-    Report Menu
-    Tools Menu
-    Window Menu
-    Help Menu
-
-File Menu
-
-The File Menu contains commands for opening and saving data files and for printing:
-Command    Description
-New    Creates a new SWMM project
-Open    Opens an existing project
-Reopen    Reopens a recently used project
-Save    Saves the current project
-Save As    Saves the current project under a different name
-Export    Exports study area map to a file in a variety of formats;
-Exports current results to a Hot Start file;
-Exports the current result’s Status/Summary reports
-Combine    Combines two Routing Interface files together
-Page Setup    Sets page margins and orientation for printing
-Print Preview    Previews a printout of the currently active view (map, report, graph, or table)
-Print    Prints the current view
-Exit    Exits SWMM
-
- 
-Edit Menu
-The Edit Menu contains commands for editing and copying:
-Command    Description
-Copy To    Copies the currently active view (map, report, graph or table) to the clipboard or to a file
-Select Object    Enables the user to select an object on the map
-Select Vertex    Enables the user to select the vertex of a subcatchment or link 
-Select Region    Enables the user to delineate a region on the map for selecting multiple objects
-Select All    Selects all objects when the map is the active window or all cells of a table when a tabular report is the active window
-Find Object    Locates a specific object by name on the map
-Edit Object    Edits the properties of the currently selected object
-Delete Object    Deletes the currently selected object
-Group Edit    Edits a property for the group of objects that fall within the outlined region of the map
-Group Delete    Deletes a group of objects that fall within the outlined region of the map
-
-View Menu
-
-The View Menu contains commands for viewing the Study Area Map:
-Command    Description
-Dimensions    Sets reference coordinates and distance units for the study area map 
-Backdrop    Allows a backdrop image to be added, positioned, and viewed behind the map
-Pan    Pans across the map
-Zoom In    Zooms in on the map
-Zoom Out    Zooms out on the map
-Full Extent    Redraws the map at full extent
-Query    Highlights objects on the map that meet specific criteria
-Overview    Toggles the display of the Overview Map
-Layers    Toggles display of object layers on the map
-Legends    Controls display of the map legends
-Toolbar    Toggles display of the toolbar
-Project Menu
-
-The Project menu contains commands related to the current project being analyzed:
-Command    Description
-Summary    Lists the number of each type of object in the project
-Details    Shows a detailed listing of all project data
-Defaults    Edits a project’s default properties
-Calibration Data    Registers files containing calibration data with the project
-Add a New Object    Adds a new context sensitive object to the project
-Run a Simulation    Runs a simulation
-
-Report Menu
-
-The Report menu contains commands used to report analysis results in different formats:
-Command    Description
-Status    Displays a status report for the most recent simulation run
-Summary    Displays summary results in tabular form
-Graph    Displays simulation results in graphical form
-Table    Displays simulation results in tabular form
-Statistics    Displays a statistical analysis of simulation results
-Customize    Customizes the display style of the currently active graph
-
-Tools Menu
-
-The Tools menu contains commands used to configure program preferences, study area map display options, and external add-in tools:
-Command    Description
-Program Preferences    Sets program preferences, such as font size, confirm deletions, number of decimal places displayed, etc.
-Map Display Options    Sets appearance options for the Map, such as object size,  annotation, flow direction arrows, and back-ground color
-Configure Tools    Adds, deletes, or modifies external add-in tools
-
-
-
-
-Window Menu
-
-The Window Menu contains commands for arranging and selecting windows within the SWMM workspace:
-Command    Description
-Cascade    Arranges windows in cascaded style, with the study area map filling the entire display area
-Tile    Minimizes the study area map and tiles the remaining windows vertically in the display area
-Close All    Closes all open windows except for the study area map
-Window List    Lists all open windows; the currently selected window has the focus and is denoted with a check mark
-
-Help Menu
-
-The Help Menu contains commands for getting help in using EPA SWMM:
-Command    Description
-User Guide    Displays the User Guide’s Table of Contents
-How Do I    Displays a list of topics covering the most common operations
-What’s New    Lists new program features that have been added
-Keyboard Shortcuts    Displays a list of keyboard shortcuts for main menu commands
-Measurement Units    Shows measurement units for all of SWMM’s parameters
-Error Messages    Lists the meaning of all error messages
-Tutorials    Lists tutorials that show how to use EPA SWMM
-Welcome Screen    Displays SWMM’s Welcome screen
-About    Displays information about the version of EPA SWMM being used
-
-
-
-
-
-
-
-
-
-
-    Keyboard Shortcuts
-
-Several main menu commands have keyboard shortcuts that can be used to select them. They are listed below.
-
-Menu Command    Shortcut Key
-File | New    Ctrl-N
-File | Open    Ctrl-O
-File | Save    Ctrl-S
-File | Save As    Ctrl-Alt-S
-File | Exit    Alt-F4
-Edit | Copy To    Ctrl-C
-Edit | Select All    Ctrl-A
-Edit | Find Object    Ctrl-F
-Edit | Edit Object    F2
-Edit | Delete Object    Ctrl-Delete
-Edit | Group Edit    Shift-F2
-View | Query    Ctrl-Q
-Project | Add a New <object>    Ctrl-Insert
-Project | Run Simulation    F9
-Report | Graph | Time Series    Ctrl-G
-Window | Cascade    Shift-F5
-Window | Tile    Shift-F4
-Window | Close All    Shift-Ctrl-F4
-Help | User Guide    Ctrl-F1
-
-In addition the F1 key can be used to bring up context-sensitive Help in most of SWMM's data editing windows
-
-    Toolbars
-
-The Main Toolbar appears at the top of SWMM's Main Window and provides shortcuts to the following Main Menu commands:
-
-
-     Creates a new project (File >> New)
-     Opens an existing project (File >> Open)
-     Saves the current project (File >> Save)
-     Prints the currently active window (File >> Print)
-     Copies selection to the clipboard or to a file (Edit >> Copy To)
-     Finds a specific object on the Study Area Map (Edit >> Find Object) 
-     Makes a visual query of the Study Area Map (View >> Query)
-     Toggles the display of the Overview Map (View >> Overview)
-     Runs a simulation (Project >> Run Simulation)
-     Displays a run’s Status or Summary reports (Report >> Status and Report >> Summary appear in a dropdown menu)
-     Creates a profile plot of simulation results (Report >> Graph >> Profile)
-     Creates a time series plot of simulation results (Report >> Graph >> Time Series)
-     Creates a time series table of simulation results (Report >> Table)
-     Creates a scatter plot of simulation results (Report >> Graph >> Scatter)
-     Performs a statistical analysis of simulation results (Report >> Statistics)
-     Modifies display options for the currently active view (Tools >> Map Display Options or Report >> Customize)
-     Arranges windows in cascaded style, with the Study Area Map filling the entire display area (Window >> Cascade) 
-
-The Main Toolbar can be made visible or invisible by selecting View >> Toolbar from the Main Menu.
-
-The Map Toolbar appears on the right side of the Study Area Map and contains buttons for selecting items and viewing the Study Area Map:
-     Selects an object on the map (Edit >> Select Object)
-     Selects link or subcatchment vertex points (Edit >> Select Vertex)
-     Selects a region on the map (Edit >> Select Region)
-     Pans across the map (View >> Pan)
-     Zooms in on the map (View >> Zoom In)
-     Zooms out on the map (View >> Zoom Out)
-     Draws map at full extent (View >> Full Extent)
-     Measures a length or area on the map
-
-The mouse wheel can also be used to pan, zoom in or zoom out of the map at any time without having to select the Pan, Zoom In or Zoom Out buttons.
-
-The Map Toolbar also contains buttons used to add objects to a project via the Study Area Map:
-     Adds a rain gage to the map.
-     Adds a subcatchment to the map
-     Adds a junction node to the map
-     Adds an outfall node to the map
-     Adds a flow divider node to the map
-     Adds a storage unit node to the map 
-     Adds a conduit link to the map
-     Adds a pump link to the map
-     Adds an orifice link to the map
-     Adds a weir link to the map
-     Adds an outlet link to the map
-     Adds a text label to the map
-
-    Status Bar
-
-The Status Bar appears at the bottom of SWMM's Main Window and is divided into six sections: 
-
- 
-
-Auto-Length 
-Indicates whether the automatic computation of conduit lengths and subcatchment areas is turned on or off. The setting can be changed by clicking the drop down arrow.
-
-
-
-Offsets
-Indicates whether the positions of links above the invert of their connecting nodes are expressed as a Depth above the node invert or as the Elevation of the offset. Click the drop down arrow to change this option. If changed, a dialog box will appear asking if all existing offsets in the current project should be changed or not (i.e., convert Depth offsets to Elevation offsets or Elevation offsets to Depth offsets, depending on the option selected)
-
-
-Flow Units 
-Displays the current flow units that are in effect. Click the drop down arrow to change the choice of flow units. Selecting a US flow unit means that all other quantities will be expressed in US units, while choosing a metric flow unit will force all quantities to be expressed in metric units. The units of previously entered data are not automatically adjusted if the unit system is changed.
-
-Run Status 
-
-     results are not available because no simulation has been run yet.
-     results are up to date.
-     results are out of date because project data have changed.
-     results are not available because the last simulation had errors.
-
-Zoom Level 
-Displays the current zoom level for the map (100% is full-scale). 
- 
-XY Location 
-Displays the map coordinates of the current position of the mouse pointer.
-
-    Study Area Map
-
-The Study Area Map (shown below) provides a planar schematic diagram of the objects comprising a drainage system. Its pertinent features are as follows:
-    The location of objects and the distances between them do not necessarily have to conform to their actual physical scale.
-    Selected properties of these objects, such as water quality at nodes or flow velocity in links, can be displayed by using different colors. The color-coding is described in a Legend, which can be edited.
-    New objects can be directly added to the map and existing objects can be selected for editing, deleting, and repositioning.
-    A backdrop drawing (such as a street or topographic map) can be placed behind the network map for reference.
-    The map can be zoomed to any scale and panned from one position to another.
-    Nodes and links can be drawn at different sizes, flow direction arrows added, and object symbols, ID labels and numerical property values displayed.
-    The map can be printed, copied onto the Windows clipboard, or exported as a DXF file or Windows metafile.
-
- 
-
-    Project Browser
-
-The Project Browser panel (shown below) appears when the Project tab on the left panel of SWMM’s main window is selected. It provides access to all of the data objects in a project. The vertical sizes of the list boxes in the browser can be adjusted by using the splitter bar located just below the upper list box. The width of the Browser panel can be adjusted by using the splitter bar located along its right edge.
-
-     The upper list box displays the various categories of data objects available to a SWMM project. The lower list box lists the name of each individual object of the currently selected data category. 
-
-The buttons between the two list boxes are used as follows:
-   adds a new object
-   deletes the selected object
-   edits the selected object
-   moves the selected object up one position
-   moves the selected object down one position
-   sorts the objects in ascending order
-      
-Selections made in the Project Browser are coordinated with objects highlighted on the Study Area Map, and vice versa. For example, selecting a conduit in the Browser will cause that conduit to be highlighted on the map, while selecting it on the map will cause it to become the selected object in the Browser.
-
-
-    Map Browser
-
-The Map Browser panel (shown below) appears when the Map tab on the left panel of the SWMM’s main window is selected. It controls the mapping themes and time periods viewed on the Study Area Map. The width of the Map Browser panel can be adjusted by using the splitter bar located along its right edge. The Map Browser consists of the following three panels that control what results are displayed on the map:
-
-
-
-
-
-
-
-
-
- 
-    
-The Themes panel selects a set of variables to view in color-coded fashion on the Map:
-Subcatchments - selects the theme to display for the subcatchment areas shown on the Map.
-Nodes - selects the theme to display for the drainage system nodes shown on the Map.
- Links - selects the theme to display for the drainage system links shown on the Map.
-The Time Period panel selects which time period of the simulation results are viewed on the Map.
-Date - selects the day for which simulation results will be viewed.
-Time of Day - selects the time of the current date for which simulation results will be viewed.
-Elapsed Time - selects the elapsed time from the start of the simulation (in days.hours:minutes:seconds) for which results will be viewed.
-The Animator panel controls the animated display of the Study Area Map and all Profile Plots over time.
-  Returns to the starting period.
-  Starts animating backwards in time
-  Stops the animation
-  Starts animating forwards in time
-The slider bar is used to adjust the animation speed.
-
-
-
-
-
-
-
-
-
-
-
-    Property Editor
-
-The Property Editor (shown to the right) is used to edit the properties of data objects that can appear on the Study Area Map. It is invoked when one of these objects is selected (either on the map or in the Project Browser) and double-clicked or when the Project Browser's Edit button   is clicked. 
-
-Key features of the Property Editor include:
-    The Editor is a grid with two columns - one for the property's name and the other for its value.
-    The columns can be re-sized by re-sizing the header at the top of the Editor with the mouse.
-    A hint area is displayed at the bottom of the Editor with an expanded description of the property being edited. The size of this area can be adjusted by dragging the splitter bar located just above it.     
-    The Editor window can be moved and re-sized via the normal Windows operations.
-    Depending on the property, the value field can be one of the following:
-    a text box in which you enter a value
-    a dropdown combo box from which you select a value from a list of choices
-    a dropdown combo box in which you can enter a value or select from a list of choices
-    an ellipsis button which you click to bring up a specialized editor.
-    The field in the Editor that currently has the focus will have a focus rectangle drawn around it.
-    Both the mouse and the Up and Down arrow keys on the keyboard can be used to move between property fields.
-    The Page Up key can be used to select the previous object of the same type (as listed in the Project Browser) into the Editor, while the Page Down key will select the next object of the same type into the Editor.
-    To begin editing the property with the focus, either begin typing a value or hit the Enter key.
-    To have the program accept edits made in a property field, either press the Enter key or move to another property. To cancel the edits, press the Esc key.
-    The Property Editor can be hidden by clicking the button in the upper right corner of its title bar.
-
-Setting Program Preferences
-
-Program preferences allow one to customize certain program features. To set program preferences, select Program Preferences from the Tools menu. A Preferences dialog form will appear containing two tabbed pages – one for General Preferences and one for Numerical Precision. 
-
-      
-
-
-
-
-
-
-
-The following preferences can be set on the General Preferences page of the Preferences dialog:
-
-Preference    Description
-Blinking Map Highlighter    Check to make the selected object on the study area map blink on and off.
-Flyover Map Labeling    Check to display the ID label and current theme value in a hint-style box whenever the mouse is placed over an object on the study area map.
-Confirm Deletions    Check to display a confirmation dialog box before deleting any object.
-Automatic Backup File    Check to save a backup copy of a newly opened project to disk named with a .bak extension.
-Tab Delimited Project File    Check to use tabs to delimit data values when saving a project to file.
-Report Elapsed Time by Default    Check to use elapsed time (rather than date/time) as the default for time series graphs and tables.
-Prompt to Save Results    If left unchecked then simulation results are automatically saved to disk when the current project is closed. Otherwise the user will be asked if results should be saved.
-Show Welcome Screen at Startup    Check to have SWMM display a welcome screen when started.
-Clear Recent Project List    Check to clear the list of most recently used files appearing when File >> Reopen is selected from the Main Menu.
-Style Theme     Selects a color theme to use for SWMM’s user interface (see below for some examples).
-
-
-           
-
-The Numerical Precision page of the Preferences dialog controls the number of decimal places displayed when simulation results are reported. Use the dropdown list boxes to select a specific Subcatchment, Node or Link parameter, and then use the edit boxes next to them to select the number of decimal places to use when displaying computed results for the parameter. . Note that there is no such limit to the number of decimal places displayed for any particular input design parameter, such as slope, diameter, length, etc. The number of decimal places displayed is whatever the user enters.
- 
-
diff --git a/docs/manuals/user/manual/Chapter5.md b/docs/manuals/user/manual/Chapter5.md
deleted file mode 100644
index b737637c6..000000000
--- a/docs/manuals/user/manual/Chapter5.md
+++ /dev/null
@@ -1,153 +0,0 @@
-@page user_manual_chapter_5 CHAPTER 5 - WORKING WITH PROJECTS
-
-@tableofcontents
-
-Project files contain all of the information used to model a study area. They are usually named with a .INP extension. This section describes how to create, open, and save EPA SWMM projects as well as setting their default properties.
-
-    Creating a New Project
-
-To create a new project:
-    Select File >> New from the Main Menu or click  on the Main Toolbar.
-    You will be prompted to save the existing project (if changes were made to it) before the new project is created.
-    A new, unnamed project is created with all options set to their default values.
-
-A new project is automatically created whenever EPA SWMM first begins.
-
-     If you are going to use a backdrop image with automatic area and length calculation, then it is recommended that you set the map dimensions immediately after creating the new project (see Section 7.2 Setting the Map's Dimensions).
-
-    Opening an Existing Project
-
-To open an existing project stored on disk:
-    Either select File >> Open from the Main Menu or click   on the Main Toolbar.
-    You will be prompted to save the current project (if changes were made to it).
-    Select the file to open from the Open File dialog form that will appear. 
-    Click Open to open the selected file.
- 
-To open a project that was worked on recently: 
-    Select File >> Reopen from the Main Menu.  
-    Select a file from the list of recently used files to open.  
-
-
-    Saving a Project
-
-To save a project under its current name either select File >> Save from the Main Menu or click   on the Main Toolbar.
-
- To save a project using a different name:
-    Select File >> Save As from the Main Menu.
-    A standard File Save dialog form will appear from which you can select the folder and name that the project should be saved under.
-
-    Setting Project Defaults
-
-Each project has a set of default values that are used unless overridden by the SWMM user. These values fall into three categories:
-    Default ID labels (labels used to identify nodes and links when they are first created)
-    Default subcatchment properties (e.g., area, width, slope, etc.)
-    Default node/link properties (e.g., node invert, conduit length, routing method).
-
-To set default values for a project:
-    Select Project >> Defaults from the Main Menu.
-    A Project Defaults dialog will appear with three pages, one for each category listed above.     
-    Check the box in the lower left of the dialog form if you want to save your choices for use in all new future projects as well.
-    Click OK to accept your choice of defaults.
-
-The specific items for each category of defaults will be discussed next.
-
-Default ID Labels
-
-The ID Labels page of the Project Defaults dialog form is used to determine how SWMM will assign default ID labels for the visual project components when they are first created. For each type of object you can enter a label prefix in the corresponding entry field or leave the field blank if an object's default name will simply be a number. In the last field you can enter an increment to be used when adding a numerical suffix to the default label. As an example, if C were used as a prefix for Conduits along with an increment of 5, then as conduits are created they receive default names of C5, C10, C15, and so on. An object’s default name can be changed by using the Property Editor for visual objects or the object-specific editor for non-visual objects. 
-
-Default Subcatchment Properties
-
-The Subcatchment page of the Project Defaults dialog sets default property values for newly created subcatchments. These properties include: 
-    Subcatchment Area  
-    Characteristic Width  
-    Slope  
-    % Impervious  
-    Impervious Area Roughness  
-    Pervious Area Roughness  
-    Impervious Area Depression Storage  
-    Pervious Area Depression Storage  
-    % of Impervious Area with No Depression Storage  
-    Infiltration Method  
- 
-The default properties of a subcatchment can be modified later by using the Property Editor. 
-
-Default Node/Link Properties
-
-The Nodes/Links page of the Project Defaults dialog sets default property values for newly created nodes and links. These properties include: 
-    Node Invert Elevation  
-    Node Maximum Depth
-    Node Ponded Area  
-    Conduit Length  
-    Conduit Shape and Size
-    Conduit Roughness  
-    Flow Units
-    Link Offsets Convention  
-    Routing Method
-    Force Main Equation  
- 
-The defaults automatically assigned to individual objects can be changed by using the object’s Property Editor. The choice of Flow Units and Link Offsets Convention can be changed directly on the main window’s Status Bar.
-
-    Measurement Units
-
-SWMM can use either US customary units or SI metric units. The choice of flow units determines what unit system is used for all other quantities: 
-    selecting CFS (cubic feet per second), GPM (gallons per minutes), or MGD (million gallons per day) for flow units implies that US customary units will be used throughout
-    selecting CMS (cubic meters per second), LPS (liters per second), or MLD (million liters per day) as flow units implies that SI metric units will be used throughout
-     pollutant concentration  and Manning’s roughness coefficient (n) are always expressed in metric units.
-
-Flow units can be selected directly on the main window's Status Bar or by setting a project's default values. In the latter case the selection can be saved so that all new future projects will automatically use those units.
-
-     The units of previously entered data are not automatically adjusted if the unit system is changed.  
-
-
-
-
-
-
-    Link Offset Conventions
-
-Conduits and flow regulators (orifices, weirs, and outlets) can be offset some distance above the invert of their connecting end nodes as depicted below:
-
- 
-
-There are two different conventions available for specifying the location of these offsets. The Depth convention uses the offset distance from the node's invert (distance between  and ‚ in the figure above). The Elevation convention uses the absolute elevation of the offset location (the elevation of point  in the figure). The choice of convention can be made on the Status Bar of SWMM's main window or on the Node/Link Properties page of the Project Defaults dialog. When this convention is changed, a dialog will appear giving one the option to automatically re-calculate all existing link offsets in the current project using the newly selected convention.
-
-    Calibration Data
-
-SWMM can compare the results of a simulation with measured field data in its Time Series Plots, which are discussed in Section 9.4. Before SWMM can use such calibration data they must be entered into a specially formatted text file and registered with the project.
-
-Calibration Files
-
-Calibration Files contain measurements of a single parameter at one or more locations that can be compared with simulated values in Time Series Plots. Separate files can be used for each of the following parameters: 
-    Subcatchment Runoff  
-    Subcatchment Pollutant Washoff  
-    Groundwater Flow
-    Groundwater Elevation
-    Snow Pack Depth
-    Node Depth 
-    Node Lateral Inflow 
-    Node Flooding
-    Node Water Quality  
-    Link Flow Rate
-    Link Flow Depth
-    Link Flow Velocity 
-The format of the file is described in Section 11.5. 
-
-Registering Calibration Data
-
-To register calibration data residing in a Calibration File:
-    Select Project >> Calibration Data from the Main Menu.
-    In the Calibration Data dialog form shown below, click in the box next to the parameter (e.g., node depth, link flow, etc.) whose calibration data will be registered.
-    Then click the Add button to select a Calibration File from a standard Windows file selection dialog box.
-    Click the Edit button if you want to open the Calibration File in Windows NotePad for editing.
-    Click the Delete button if you wish to remove the Calibration File from the form.
-    Repeat steps 2 - 4 for any other parameters that have calibration data.
-    Click OK to accept your selections.
-
- 
-
-
-    Viewing All Project Data
-
-A listing of all project data (with the exception of map coordinates) can be viewed in a non-editable window, formatted for input to SWMM's computational engine (see below). This can be useful for checking data consistency and to make sure that no key components are missing. To view such a listing select Project >> Details from the Main Menu. The format of the data in this listing is the same as that used when the file is saved to disk. It is described in detail in Appendix D.2.
-
-
diff --git a/docs/manuals/user/manual/Chapter6.md b/docs/manuals/user/manual/Chapter6.md
deleted file mode 100644
index f7a378c27..000000000
--- a/docs/manuals/user/manual/Chapter6.md
+++ /dev/null
@@ -1,179 +0,0 @@
-@page user_manual_chapter_6 CHAPTER 6 - WORKING WITH OBJECTS
-
-@tableofcontents
-
-SWMM uses various types of objects to model a drainage area and its conveyance system. This section describes how these objects can be created, selected, edited, deleted, and repositioned.
-
-    Types of Objects
-
-SWMM contains both physical objects that can appear on its Study Area Map, and non-physical objects that encompass design, loading, and operational information. These objects, which are listed in the Project Browser and were described in Chapter 3, consist of the following:
-
-Project Title/Notes                Nodes
-Simulation Options                Links
-Climatology                        Transects
-Rain Gages                        Streets
-Subcatchments                    Inlets
-Aquifers                        Control Rules
-Snow Packs                        Curves
-Unit Hydrographs                Time Series
-LID Controls                    Time Patterns
-Pollutants                         Map Labels
-Land Uses
-
-    Adding Objects
-
-To add a new object to a project, select the type of object from the upper pane of the Project Browser and either select Project >> Add a New ... from the Main Menu or click the Browser's     button. If the object has a button on the Map Toolbar you can simply click the button instead.
-
-If the object is a visual object that appears on the Study Area Map (a Rain Gage, Subcatchment, Node, Link, or Map Label) it will automatically receive a default ID name and a prompt will appear in the Status Bar telling you how to proceed. The steps used to draw each of these objects on the map are detailed below:
-
-Rain Gages
-Move the mouse to the desired location on the Map and left-click. 
-Subcatchments
-Use the mouse to draw a polygon outline of the subcatchment on the Map:
-    left-click at each vertex 
-    right-click or press <Enter> to close the polygon 
-    press the <Esc> key if you wish to cancel the action. 
-
-Nodes (Junctions, Outfalls, Flow Dividers, and Storage Units)
-Move the mouse to the desired location on the Study Area Map and left-click.
-
- Links (Conduits, Pumps, Orifices, Weirs, and Outlets)
-    Left-click the mouse on the link's inlet (upstream) node.  
-    Move the mouse (without pressing any button) in the direction of the link's outlet (downstream) node, clicking at all intermediate points necessary to define the link's alignment.  
-    Left-click the mouse a final time over the link's outlet (downstream) node. (Pressing the right mouse button or the <Esc> key while drawing a link will cancel the operation.) 
-
-Map Labels
-    Left-click the mouse on the map location where the top left corner of the label should appear.  
-    Enter the text for the label.  
-    Press <Enter> to accept the label or <Esc> to cancel. 
-
- For all other non-visual types of objects, an object-specific dialog form will appear that allows you to name the object and edit its properties.
-
-    Selecting and Moving Objects
-
-To select an object on the map:
-    Make sure that the map is in Selection mode (the mouse cursor has the shape of an arrow pointing up to the left). To switch to this mode, either click the Select Object button   on the Map Toolbar or choose Edit >> Select Object from the Main Menu.
-    Click the mouse over the desired object on the map.
-
-
-To select an object using the Project Browser:
-    Select the object’s category from the upper list in the Browser.
-    Select the object from the lower list in the Browser.
-
-Rain gages, subcatchments, nodes, and map labels can be moved to another location on the Study Area Map. To move an object to another location: 
-    Select the object on the map.
-    With the left mouse button held down over the object, drag it to its new location.
-    Release the mouse button.
-
-The following alternative method can also be used:
-    Select the object to be moved from the Project Browser (it must either be a rain gage, subcatchment, node, or map label).
-    With the left mouse button held down, drag the item from the Items list box of the Data Browser to its new location on the map.
-    Release the mouse button.
-
-Note that the second method can be used to place objects on the map that were imported from a project file that had no coordinate information included in it. 
-
-    Editing Objects
-
-To edit an object appearing on the Study Area Map: 
-    Select the object on the map.
-    If the Property Editor is not visible either:
-    double click on the object
-    or right-click on the object and select Properties from the pop-up menu that appears
-    or click on   in the Project Browser
-    or select Edit >> Edit Object from the Main Menu.
-    Edit the object’s properties in the Property Editor.
-
-Appendix B lists the properties associated with each of SWMM’s visual objects.
-
-To edit an object listed in the Project Browser: 
-    Select the object in the Project Browser.
-    Either:
-    click on   in the Project Browser,
-    or select Edit >> Edit Object from the Main Menu,
-    or double-click the item in the Objects list,
-    or press the <Enter> key.
-
-Depending on the class of object selected, a special property editor will appear in which the object’s properties can be modified. Appendix C describes all of the special property editors used with SWMM’s non-visual objects.
-
-     The unit system in which object properties are expressed depends on the choice of units for flow rate. Using a flow rate expressed in cubic feet, gallons or acre-feet implies that US customary units will be used for all quantities. Using a flow rate expressed in liters or cubic meters means that SI metric units will be used. Flow units are selected either from the project’s default Node/Link properties (see Section 5.4) or directly from the main window’s Status Bar (see Section 4.5). The units used for all properties are listed in Appendix A.1.
-
-    Converting an Object
-
-It is possible to convert a node or link from one type to another without having to first delete the object and add a new one in its place. An example would be converting a Junction node into an Outfall node, or converting an Orifice link into a Weir link. To convert a node or link to another type:
-    Right-click the object on the map.
-    Select Convert To from the popup menu that appears.
-    Select the new type of node or link to convert to from the sub-menu that appears.
-    Edit the object to provide any data that was not included with the previous type of object.
-
-Only data that is common to both types of objects will be preserved after an object is converted to a different type. For nodes this includes its name, position, description, tag, external inflows, treatment functions, and invert elevation. For links it includes just its name, end nodes, description, and tag.
-
-    Copying and Pasting Objects
-
-The properties of an object displayed on the Study Area Map can be copied and pasted into another object from the same category.
- 
-To copy the properties of an object to SWMM's internal clipboard: 
-    Right-click the object on the map.
-    Select Copy from the pop-up menu that appears.
-
-To paste copied properties into an object: 
-    Right-click the object on the map.
-    Select Paste from the pop-up menu that appears.
-
-Only data that can be shared between objects of the same type can be copied and pasted. Properties not copied include the object's name, coordinates, end nodes (for links), tag property and any descriptive comment associated with the object. For Map Labels, only font properties are copied and pasted.
-
-    Shaping and Reversing Links
-
-Links can be drawn as polylines containing any number of straight-line segments that define the alignment or curvature of the link. Once a link has been drawn on the map, interior points that define these line segments can be added, deleted, and moved. To edit the interior points of a link:
-    Select the link to edit on the map and put the map in Vertex Selection mode either by clicking   on the Map Toolbar, selecting Edit >> Select Vertex from the Main Menu, or right clicking on the link and selecting Vertices from the popup menu.  
-    The mouse pointer will change shape to an arrow tip, and any existing vertex points on the link will be displayed as small open squares. The currently selected vertex will be displayed as a filled square. To select a particular vertex, click the mouse over it.  
-    To add a new vertex to the link, right-click the mouse and select Add Vertex from the popup menu (or simply press the <Insert> key on the keyboard).  
-    To delete the currently selected vertex, right-click the mouse and select Delete Vertex from the popup menu (or simply press the <Delete> key on the keyboard).  
-    To move a vertex to another location, drag it to its new position with the left mouse button held down.  
-While in Vertex Selection mode you can begin editing the vertices for another link by simply clicking on the link. To leave Vertex Selection mode, right-click on the map and select Quit Editing from the popup menu, or simply select one of the other buttons on the Map Toolbar.  
-
-A link can also have its direction reversed (i.e., its end nodes switched) by right clicking on it and selecting Reverse from the pop-up menu that appears. Normally, links should be oriented so that the upstream end is at a higher elevation than the downstream end.
-
-    Shaping a Subcatchment
-
-Subcatchments are drawn on the Study Area Map as closed polygons. To edit or add vertices to the polygon, follow the same procedures used for links. If the subcatchment is originally drawn or is edited to have two or less vertices, then only its centroid symbol will be displayed on the Study Area Map.
-
-    Deleting an Object
-
-To delete an object:
-    Select the object on the Study Area Map or from the Project Browser.
-    Either click the   button on the Project Browser or press the <Delete> key on the keyboard, or select Edit >> Delete Object from the Main Menu, or right-click the object on the map and select Delete from the pop-up menu that appears.
-
-      You can require that all deletions be confirmed before they take effect. See the General Preferences page of the Program Preferences dialog box described in Section 4.9.
-
-Editing or Deleting a Group of Objects
-
-A group of objects located within an irregular region of the Study Area Map can have a common property edited or be deleted all together. To select such a group of objects:
-
-
-
-    Choose Edit >> Select Region from the Main Menu or click    on the Map Toolbar.
-    Draw a polygon around the region of interest on the map by clicking the left mouse button at each successive vertex of the polygon.
-    Close the polygon by clicking the right button or by pressing the <Enter> key; cancel the selection by pressing the <Esc> key.
-To select all objects in the project, whether in view or not, select Edit >> Select All from the Main Menu.
-  
-Once a group of objects has been selected, you can edit a common property shared among them:
-    Select Edit >> Group Edit from the Main Menu.
-    Use the Group Editor dialog that appears to select a property and specify its new value.
-
-The Group Editor dialog, shown below, is used to modify a property for a selected group of objects. To use the dialog:
-
- 
-
-    Select a type of object (Subcatchments, Infiltration, Junctions, Storage Units, or Conduits) to edit.  
-    Check the "with Tag equal to" box if you want to add a filter that will limit the objects selected for editing to those with a specific Tag value. (For Infiltration, the Tag will be that of the subcatchment to which the infiltration parameters belong.)
-    Enter a Tag value to filter on if you have selected that option.  
-    Select the property to edit.
-    Select whether to replace, multiply, or add to the existing value of the property. Note that for some non-numerical properties the only available choice is to replace the value.  
-    In the lower-right edit box, enter the value that should replace, multiply, or be added to the existing value for all selected objects. Some properties will have an ellipsis button displayed in the edit box which should be clicked to bring up a specialized editor for the property.
-    Click OK to execute the group edit.  
-
-After the group edit is executed a confirmation dialog box will appear informing you of how many items were modified. It will ask if you wish to continue editing or not. Select Yes to return to the Group Edit dialog box to edit another parameter or No to dismiss the Group Edit dialog.
-
-To delete the objects located within a selected area of the map, select Edit >> Group Delete from the Main Menu. Then select the categories of objects you wish to delete from the dialog box that appears. As an option, you can specify that only objects within the selected area that have a specific Tag property should be deleted. Keep in mind that deleting a node will also delete any links connected to the node. 
-
-
diff --git a/docs/manuals/user/manual/Chapter7.md b/docs/manuals/user/manual/Chapter7.md
deleted file mode 100644
index 44ea40597..000000000
--- a/docs/manuals/user/manual/Chapter7.md
+++ /dev/null
@@ -1,317 +0,0 @@
-@page user_manual_chapter_7 CHAPTER 7 - WORKING WITH THE MAP
-
-@tableofcontents
-
-EPA SWMM can display a map of the study area being modeled. This section describes how you can manipulate this map to enhance your visualization of the system.
-
-    Viewing Map Layers
-
-The layers that can be viewed on the Study Area consist of rain gages, subcatchments, nodes, links, labels, and the backdrop image. The display of each of these can be toggled on or off by selecting View >> Layers from the Main Menu or by right-clicking on the map and selecting Layers from the pop-up menu that appears.
-    
-    Selecting a Map Theme
-
- 
-A map theme corresponds to a specific layer property whose value is drawn in color-coded fashion on the Study Area Map. The dropdown list boxes on the Map Browser are used for selecting a theme to display for the subcatchment, node and link layers. Methods for changing the color-coding associated with a theme are discussed in Section 7.10 below. 
-
-    Setting the Map’s Dimensions
-
-The physical dimensions of the map can be defined so that map coordinates can be properly scaled to the computer’s video display. To set the map's dimensions:
-    Select View >> Dimensions from the Main Menu.
-    Enter coordinates for the lower-left and upper-right corners of the map into the Map Dimensions dialog (see below) that appears or click the Auto-Size button to automatically set the dimensions based on the coordinates of the objects currently included in the map.
-
- 
-
-    Select the distance units to use for these coordinates.
-    If the Auto-Length option is in effect, check the “Re-compute all lengths and areas” box if you would like SWMM to re-calculate all conduit lengths and subcatchment areas under the new set of map dimensions.  
-    Click the OK button to resize the map.  
- 
-     If you are going to use a backdrop image with the automatic distance and area calculation feature, then it is recommended that you set the map dimensions immediately after creating a new project. Map distance units can be different from conduit length units. The latter (feet or meters) depend on whether flow rates are expressed in US or metric units. SWMM will automatically convert from map units if necessary.  
-     If you just want to re-compute conduit lengths and subcatchment areas without changing the map's dimensions, then just check the Re-compute Lengths and Areas box and leave the coordinate boxes as they are.
-
-    Utilizing a Backdrop Image
-
-SWMM can display a backdrop image behind the Study Area Map. The backdrop image might be a street map, utility map, topographic map, site development plan, or any other relevant picture or drawing. For example, using a street map would simplify the process of adding sewer lines to the project since one could essentially digitize the drainage system's nodes and links directly on top of it. 
-
- 
-The backdrop image must be a Windows metafile, bitmap, JPEG, or PNG image created outside of SWMM. Once imported, its features cannot be edited, although its scale and viewing area will change as the map window is zoomed and panned. For this reason metafiles work better than the other formats since they will not lose resolution when re-scaled. Most CAD and GIS programs have the ability to save their drawings and maps as metafiles. 
-
-Selecting View >> Backdrop from the Main Menu will display a sub-menu with the following commands:
-    Load (loads a backdrop image file into the project)
-    Unload (unloads the backdrop image from the project)
-    Align (aligns the drainage system schematic with the backdrop) 
-    Resize (resizes the map dimensions of the backdrop)
-    Watermark (toggles the backdrop image appearance between normal and lightened)
-
-To load a backdrop image select View >> Backdrop >> Load from the Main Menu. A Backdrop Image Selector dialog form will be displayed. The entries on this form are as follows:
-
- 
-
-
-Backdrop Image File
-Enter the name of the file that contains the image. You can click the   button to bring up a standard Windows file selection dialog from which you can search for the image file.
-
-World Coordinates File
-If a “world” file exists for the image, enter its name here, or click the   button to search for it. A world file contains geo-referencing information for the image and can be created from the software that produced the image file or by using a text editor. It contains six lines with the following information:
-Line 1:    real world width of a pixel in the horizontal direction.
-Line 2:    X rotation parameter (not used).
-Line 3:    Y rotation parameter (not used).
-Line 4:    negative of the real world height of a pixel in the vertical direction.
-Line 5:    real world X coordinate of the upper left corner of the image.
-Line 6:    real world Y coordinate of the upper left corner of the image.
-If no world file is specified, then the backdrop will be scaled to fit into the center of the map display window.
-
-Scale Map to Backdrop Image
-
-This option is only available when a world file has been specified. Selecting it forces the dimensions of the Study Area Map to coincide with those of the backdrop image. In addition, all existing objects on the map will have their coordinates adjusted so that they appear within the new map dimensions yet maintain their relative positions to one another. Selecting this option may then require that the backdrop be re-aligned so that its position relative to the drainage area objects is correct. How to do this is described below.
-
-The backdrop image can be re-positioned relative to the drainage system by selecting View >> Backdrop >> Align. This allows the backdrop image to be moved across the drainage system (by moving the mouse with the left button held down) until one decides that it lines up properly.
-
-The backdrop image can also be resized by selecting View >> Backdrop >> Resize. In this case a Backdrop Dimensions dialog will appear (see next page). The dialog lets you manually enter the X,Y coordinates of the backdrop’s lower left and upper right corners. The Study Area Map’s dimensions are also displayed for reference. While the dialog is visible you can view map coordinates by moving the mouse over the map window and noting the X,Y values displayed in SWMM’s Status Panel (at the bottom of the main window).
-
-Selecting the Resize Backdrop Image Only button will resize only the backdrop, and not the Study Area Map, according to the coordinates specified. Selecting the Scale Backdrop Image to Map button will position the backdrop image in the center of the Study Area Map and have it resized to fill the display window without changing its aspect ratio. The map's lower left and upper right coordinates will be placed in the data entry fields for the backdrop coordinates, and these fields will become disabled. Selecting Scale Map to Backdrop Image makes the dimensions of the map coincide with the dimensions being set for the backdrop image. Note that this option will change the coordinates of all objects currently on the map so that their positions relative to one another remain unchanged. Selecting this option may then require that the backdrop be re-aligned so that its position relative to the drainage area objects is correct.
-
- 
-
-
-     Exercise caution when selecting the Scale Map to Backdrop Image option in either the Backdrop Image Selector dialog or the Backdrop Dimensions dialog as it will modify the coordinates of all existing objects currently on the Study Area Map. You might want to save your project before carrying out this step in case the results are not what you expected.
-
-The name of the backdrop image file and its map dimensions are saved along with the rest of a project’s data whenever the project is saved to file.
-
-For best results in using a backdrop image:
-    Use a metafile, not a bitmap.
-    If the image is loaded before any objects are added to the project then scale the map to it.
-    Measuring Distances
-
-To measure a distance or area on the Study Area Map:
- 
-    Click   on the Map Toolbar.
-
-    Left-click on the map where you wish to begin measuring from.
-
-    Move the mouse over the distance being measured, left-clicking at each intermediate location where the measured path changes direction.
-
-    Right-click the mouse or press <Enter> to complete the measurement.
-
-    The distance measured in project units (feet or meters) will be displayed in a dialog box. If the last point on the measured path coincides with the first point then the area of the enclosed polygon will also be displayed.
-
-    Zooming the Map
-
-To Zoom In on the Study Area Map:
-    Select View >> Zoom In from the Main Menu or click   on the Map Toolbar.
-    To zoom in 100% (i.e., 2X), move the mouse to the center of the zoom area and click the left button.
-    To perform a custom zoom, move the mouse to the upper left corner of the zoom area and with the left button pressed down, draw a rectangular outline around the zoom area. Then release the left button.
-
-To Zoom Out on the Study Area Map:
-    Select View >> Zoom Out from the Main Menu or click   on the Toolbar.
-    The map will be returned to the view in effect at the previous zoom level.
-
-The mouse wheel can also be used to zoom in and out on the map at any time.
-
-
-
-
-
-    Panning the Map
-
-To pan across the Study Area Map window:
-    Select View >> Pan from the Main Menu or click   on the Map Toolbar.
-    With the left button held down over any point on the map, drag the mouse in the direction you wish to pan.
-    Release the mouse button to complete the pan.
-
-To pan using the Overview Map (which is described in Section 7.11 below):
-    If not already visible, bring up the Overview Map by selecting View >> Overview Map from the Main Menu or click the   button on the Main Toolbar.
-    If the Study Area Map has been zoomed in, an outline of the current viewing area will appear on the Overview Map. Position the mouse within this outline on the Overview Map.
-    With the left button held down, drag the outline to a new position.
-    Release the mouse button and the Study Area Map will be panned to an area corresponding to the outline on the Overview Map.
-
-The mouse wheel can also be use to pan the Study Area Map at any time by holding it down and dragging the mouse in the direction you wish to pan.
-
-    Viewing at Full Extent
-
-To view the Study Area Map at full extent, either:
-    select View >> Full Extent from the Main Menu, or
-    press   on the Map Toolbar.
-
-    Finding an Object
-
-To find an object on the Study Area Map whose name is known:
-    Select View >> Find Object from the Main Menu or click   on the Main Toolbar.
-    In the Map Finder dialog that appears, select the type of object to find and enter its name.
-    Click the Go button.
-
- 
-
-If the object exists, it will be highlighted on the map and in the Data Browser. If the map is currently zoomed in and the object falls outside the current map boundaries, the map will be panned so that the object comes into view. 
-
-     User-assigned object names in SWMM are not case sensitive. E.g., NODE123 is equivalent to Node123.
-
-After an object is found, the Map Finder dialog will also list: 
-    the outlet connections for a subcatchment  
-    the connecting links for a node  
-    the connecting nodes for a link.
-
-    Submitting a Map Query
-
-A Map Query identifies objects on the study area map that meet a specific criterion (e.g., nodes which flood, links with velocity below 2 ft/sec, etc.). It can also identify which subcatchments have LID controls and which nodes have external inflows. To submit a map query:
-    Select a time period in which to query the map from the Map Browser.
-    Select View >> Query or click    on the Main Toolbar.
-    Fill in the following information in the Query dialog that appears:
-    Select whether to search for Subcatchments, Nodes, Links, LID Subcatchments or Inflow Nodes.
-    Select a parameter to query or the type of LID or inflow to locate.
-    Select the appropriate operator: Above, Below, or Equals.
-    Enter a value to compare against.
-    Click the Go button. The number of objects that meet the criterion will be displayed in the Query dialog and each such object will be highlighted on the Study Area Map.
-    As a new time period is selected in the Browser, the query results are automatically updated.
-    You can submit another query using the dialog box or close it by clicking the button in the upper right corner.
-
- 
-
-After the Query box is closed the map will revert back to its original display.
-
-
-
-
-Using the Map Legends
-
-     Map Legends associate a color with a range of values for the current theme being viewed. Separate legends exist for Subcatchments, Nodes, and Links. A Date/Time Legend is also available for displaying the date and clock time of the simulation period being viewed on the map. 
-
-To display or hide a map legend:
-    Select View >> Legends from the Main Menu or right-click on the map and select Legends from the pop-up menu that appears
-    Click on the type of legend whose display should be toggled on or off.
-A visible legend can also be hidden by double clicking on it.
-
-To move a legend to another location press the left mouse button over the legend, drag the legend to its new location with the button held down, and then release the button.
-
-To edit a legend, either select View >> Legends >> Modify from the Main Menu or right-click on the legend if it is visible. Then use the Legend Editor dialog that appears to modify the legend's colors and intervals.
-
- 
-
-The Legend Editor is used to set numerical ranges to which different colors are assigned for viewing a particular parameter on the network map. It works as follows:
-    Numerical values, in increasing order, are entered in the edit boxes to define the ranges. Not all four boxes need to have values.
-    To change a color, click on its color band in the Editor and then select a new color from the Color Dialog that will appear.
-    Click the Auto-Scale button to automatically assign ranges based on the minimum and maximum values attained by the parameter in question at the current time period.  
-    The Color Ramp button is used to select from a list of built-in color schemes.
-    The Reverse Colors button reverses the ordering of the current set of colors (the color in the lowest range becomes that of the highest range and so on).
-    Check Framed if you want a frame drawn around the legend.
-Changes made to a legend are saved with the project's settings and remain in effect when the project is re-opened in a subsequent session.
-
-Using the Overview Map
-
-The Overview Map, as pictured below, allows one to see where in terms of the overall system the main Study Area Map is currently focused. This zoom area is depicted by the rectangular outline displayed on the Overview Map. As you drag this rectangle to another position the view within the main map will be redrawn accordingly. The Overview Map can be toggled on and off by selecting View >> Overview Map from the Main Menu or by clicking   on the Main Toolbar. The Overview Map window can also be dragged to any position as well as be re-sized.
- 
-Setting Map Display Options
-
-The Map Options dialog (shown below) is used to change the appearance of the Study Area Map. There are several ways to invoke it:
-    select Tools >> Map Display Options from the Main Menu or,
-    click the Options button   on the Main Toolbar when the Study Area Map window has the focus or,
-    right-click on any empty portion of the map and select Options from the popup menu that appears.
-
- 
-
-The dialog contains a separate page, selected from the panel on the left side of the form, for each of the following display option categories:
-    Subcatchments (controls fill style, symbol size, and outline thickness of subcatchment areas)
-    Nodes (controls size of nodes and making size be proportional to value)
-    Links (controls thickness of links and making thickness be proportional to value)
-    Labels (turns display of map labels on/off)
-    Annotation (displays or hides node/link ID labels and parameter values)
-    Symbols (turns display of storage unit, pump, and regulator symbols on/off)
-    Flow Arrows (selects visibility and style of flow direction arrows)
-    Background (changes color of map's background).
-
-Subcatchment Options
-The Subcatchments page of the Map Options dialog controls how subcatchment areas are displayed on the study area map.
-
-Option    Description
-Fill Style    Selects style used to fill interior of subcatchment area
-Symbol Size    Sets the size of the symbol (in pixels) placed at the centroid of a subcatchment area
-Border Size    Sets the thickness of the line used to draw a subcatchment's border; if set to zero then only the subcatchment centroid will be displayed
-Display Link to Outlet    If checked then a dashed line is drawn between the subcatchment centroid and the subcatchment's outlet node (or outlet subcatchment)
-
-
-Node Options
-The Nodes page of the Map Options dialog controls how nodes are displayed on the study area map.
-
-Option    Description
-Node Size    Selects node diameter in pixels
-Proportional to Value    Select if node size should increase as the viewed parameter increases in value
-Display Border    Select if a border should be drawn around each node (recommended for light-colored backgrounds)
-
-
-
-
-
-
-
-Link Options
-The Links page of the Map Options dialog controls how links are displayed on the map. 
-
-Option    Description
-Link Size    Sets thickness of links displayed on map (in pixels)
-Proportional to Value    Select if link thickness should increase as the viewed parameter increases in value
-Display Border    Check if a black border should be drawn around each link
-
-
-Label Options
-The Labels page of the Map Options dialog controls how user-created map labels are displayed on the study area map. 
-
-Option    Description
-Use Transparent Text    Check to display label with a transparent background (otherwise an opaque background is used)
-At Zoom Of    Selects minimum zoom at which labels should be displayed; labels will be hidden at zooms smaller than this 
-
-
-Annotation Options
-The Annotation page of the Map Options dialog form determines what kind of annotation is provided alongside of the objects on the study area map. 
-
-Option    Description
-Rain Gage IDs    Check to display rain gage ID names
-Subcatch IDs    Check to display subcatchment ID names
-Node IDs    Check to display node ID names
-Link IDs    Check to display link ID names
-Subcatch Values    Check to display value of current subcatchment variable
-Node Values    Check to display value of current node variable
-Link Values    Check to display value of current link variable
-Use Transparent Text    Check to display text with a transparent background (otherwise an opaque background is used)
-Font Size    Adjusts the size of the font used to display annotation
-At Zoom Of    Selects minimum zoom at which annotation should be displayed; all annotation will be hidden at zooms smaller than this
-
-
-Symbol Options
-The Symbols page of the Map Options dialog determines which types of objects are represented with special symbols on the map. 
-
-Option    Description
-Display Node Symbols    If checked then special node symbols will be used
-Display Link Symbols    If checked then special link symbols will be used
-At Zoom Of    Selects minimum zoom at which symbols should be displayed; symbols will be hidden at zooms smaller than this
-
-
-Flow Arrow Options
-The Flow Arrows page of the Map Options dialog controls how flow-direction arrows are displayed on the map.
-
-Option    Description
-Arrow Style    Selects style (shape) of arrow to display (select None to hide arrows)
-Arrow Size    Sets arrow size
-At Zoom Of    Selects minimum zoom at which arrows should be displayed; arrows will be hidden at zooms smaller than this
-
-     Flow direction arrows will only be displayed after a successful simulation has been made and a computed parameter has been selected for viewing. Otherwise the direction arrow will point from the user-designated start node to end node.
-
-Background Options
-The Background page of the Map Options dialog offers a selection of colors used to paint the map’s background.
-Exporting the Map
-
-The full extent view of the study area map can be saved to file using either:
-    Autodesk's DXF (Drawing Exchange Format) format,
-    the Windows enhanced metafile (EMF) format,
-    EPA SWMM's own ASCII text (.map) format.
-The DXF format is readable by many Computer Aided Design (CAD) programs. Metafiles can be inserted into word processing documents and loaded into drawing programs for re-scaling and editing. Both formats are vector-based and will not lose resolution when they are displayed at different scales.
-
-To export the map to a DXF, metafile, or text file: 
-    Select File >> Export >> Map. 
-    In the Map Export dialog that appears select the format that you want the map saved in. 
-
- 
-
-If you select DXF format, you have a choice of how nodes will be represented in the DXF file. They can be drawn as filled circles, as open circles, or as filled squares. Not all DXF readers can recognize the format used in the DXF file to draw a filled circle. Also note that map annotation, such as node and link ID labels will not be exported, but map label objects will be. 
-
-After choosing a format, click OK and enter a name for the file in the Save As dialog that appears.
-
-
diff --git a/docs/manuals/user/manual/Chapter8.md b/docs/manuals/user/manual/Chapter8.md
deleted file mode 100644
index 2248f7f9e..000000000
--- a/docs/manuals/user/manual/Chapter8.md
+++ /dev/null
@@ -1,283 +0,0 @@
-@page user_manual_chapter_8 CHAPTER 8 - RUNNING A SIMULATION
-
-@tableofcontents
-
-After a study area has been suitably described, its runoff response, flow routing and water quality behavior can be simulated. This section describes how to specify options to be used in the analysis, how to run the simulation and how to troubleshoot common problems that might occur.
-
-    Setting Simulation Options
-
-SWMM has a number of options that control how the simulation of a stormwater drainage system is carried out. To set these options:
-    Select the Options category from the Project Browser.  
-    Select one of the following categories of options to edit:
-    General Options
-    Date Options
-    Time Step Options
-    Dynamic Wave Routing Options
-    Interface File Options
-    Reporting Options
-    Event Options
-    Click the    button on the Browser panel or select Edit >> Edit Object to invoke the appropriate editor for the chosen option category (the Simulation Options dialog is used for the first five categories while the Reporting Options dialog and the Events Editor dialog are used, respectively, for the last two).
-
-The Simulations Options dialog contains a separate tabbed page for each of the first five option categories listed above. Each page is described in more detail below.
-
-
-
- 
-
-General Options
-
-The General page of the Simulation Options dialog sets values for the following options:
-
-Process Models
-This section selects which of SWMM’s process models will be applied to the current project. For example, a model that contained Aquifer and Groundwater elements could be run first with the groundwater computations turned on and then again with them turned off to see what effect this process had on the site’s hydrology. Note that if there are no elements in the project needed to model a given process then that process option is disabled (e.g., if there were no Aquifers defined for the project then the Groundwater check box will appear disabled in an unchecked state).
-
-
-
-Infiltration Model 
-This option selects the default method used to model infiltration of rainfall into the upper soil zone of subcatchments. The choices are: 
-    Horton  
-    Modified Horton
-    Green-Ampt
-    Modified Green-Ampt  
-    Curve Number  
-
-Each of these methods is briefly described in Section 3.4.2. All new subcatchments added to a project will default to using the selected method. For existing subcatchments, their infiltration method will only change if they had been using the previous default option. That would require re-entering values for the infiltration parameters in each such subcatchment, unless the change was between the two Horton options or the two Green-Ampt options. A prompt is issued asking if SWMM should automatically assign a default set of parameter values to all subcatchments that switch between two incompatible types of infiltration methods. Different infiltration models can be used with different subcatchments by editing their Infiltration property.
-
-Routing Model 
-This option determines which method is used to route flows through the conveyance system. The choices are: 
-    Steady Flow
-    Kinematic Wave  
-    Dynamic Wave  
-Review Section 3.4.5 for a brief description of each of these alternatives.
-
-Allow Ponding 
-Checking this option will allow excess water to collect atop nodes and be re-introduced into the system as conditions permit. In order for ponding to actually occur at a particular node, a non-zero value for its Ponded Area attribute must be used.
-
-Minimum Conduit Slope
-This is the minimum value allowed for a conduit's slope (%). If blank or zero (the default) then no minimum is imposed (although SWMM uses a lower limit on elevation drop of 0.001 ft (0.00035 m) when computing a conduit slope).
-Date Options
-
-The Dates page of the Simulation Options dialog determines the starting and ending dates/times of a simulation. 
-
-Start Analysis On 
-Enter the date (month/day/year) and time of day when the simulation begins. 
-
-Start Reporting On 
-Enter the date and time of day when reporting of simulation results is to begin. Using a date prior to the start date is the same as using the start date. 
-
-End Analysis On 
-Enter the date and time when the simulation is to end.
- 
-Start Sweeping On
-Enter the day of the year (month/day) when street sweeping operations begin. The default is January 1.
-
-End Sweeping On
-Enter the day of the year (month/day) when street sweeping operations end. The default is December 31.
-
-Antecedent Dry Days 
-Enter the number of days with no rainfall prior to the start of the simulation. This value is used to compute an initial buildup of pollutant load on the surface of subcatchments. 
-
-     If rainfall or climate data are read from external files, then the simulation dates should be set to coincide with the dates recorded in these files.
-
-Time Step Options
-
-The Time Steps page of the Simulation Options dialog establishes the length of the time steps used for runoff computation, routing computation and results reporting. Time steps are specified in days and hours:minutes:seconds except for flow routing which is entered as decimal seconds.
-
-Reporting Time Step 
-Enter the time interval for reporting of computed results. 
-
-Runoff - Wet Weather Time Step 
-Enter the time step length used to compute runoff from subcatchments during periods of rainfall, or when ponded water still remains on the surface, or when LID controls are still infiltrating or evaporating runoff.
- 
-Runoff - Dry Weather Time Step 
-Enter the time step length used for runoff computations (consisting essentially of pollutant buildup) during periods when there is no rainfall, no ponded water, and LID controls are dry. This must be greater or equal to the Wet Weather time step.
-
-Control Rule Time Step 
-Enter the time step length used for evaluating Control Rules. The default is 0 which means that controls are evaluated at every routing time step.
-
-Routing Time Step 
-Enter the time step length in decimal seconds used for routing flows and water quality constituents through the conveyance system. Note that Dynamic Wave routing requires a much smaller time step than the other methods of flow routing. 
-
-Steady Flow Periods
-This set of options tells SWMM how to identify and treat periods of time when system hydraulics is not changing. The system is considered to be in a steady flow period if:
-    The percent difference between total system inflow and total system outflow is below the System Flow Tolerance, 
-    The percent differences between the current lateral inflow and that from the previous time step for all points in the conveyance system are below the Lateral Flow Tolerance. 
-Checking the Skip Steady Flow Periods box will make SWMM keep using the most recently computed conveyance system flows (instead of computing a new flow solution) whenever the above criteria are met. Using this feature can help speed up simulation run times at the expense of reduced accuracy.
-
-
-
-Dynamic Wave Options
-
-The Dynamic Wave page of the Simulation Options dialog sets several parameters that control how the dynamic wave flow routing computations are made. These parameters have no effect for the other flow routing methods. 
-
-Inertial Terms 
-Indicates how the inertial terms in the St. Venant momentum equation will be handled.
-    KEEP maintains these terms at their full value under all conditions.
-    DAMPEN reduces the terms as flow comes closer to being critical and ignores them when flow is supercritical.
-    IGNORE drops the terms altogether from the momentum equation, producing what is essentially a Diffusion Wave solution.
-
-Define Supercritical Flow By
-Selects the basis used to determine when supercritical flow occurs in a conduit. The choices are:
-    water surface slope only (i.e., water surface slope > conduit slope)
-    Froude number only (i.e., Froude number > 1.0)
-    both water surface slope and Froude number.
-The first two choices were used in earlier versions of SWMM while the third choice, which checks for either condition, is now the recommended one.
-
-Force Main Equation
-Selects which equation will be used to compute friction losses during pressurized flow for conduits that have been assigned a Circular Force Main cross-section. The choices are either the Hazen-Williams equation or the Darcy-Weisbach equation. 
-
-Surcharge Method
-Selects which method will be used to handle surcharge conditions. The Extran option uses a variation of the Surcharge Algorithm from previous versions of SWMM to update nodal heads when all connecting links become full. The Slot option uses a Preissmann Slot to add a small amount of virtual top surface width to full flowing pipes so that SWMM's normal procedure for updating nodal heads can continue to be used. 
-
-
-
-Use Variable Time Steps
-Check the box if an internally computed variable time step should be used at each routing time period and select an adjustment (or safety) factor to apply to this time step. The variable time step is computed so as to satisfy the Courant condition within each conduit. A typical adjustment factor would be 75% to provide some margin of conservatism. The computed variable time step will not be less than the minimum variable step discussed below nor be greater than the fixed time step specified on the Time Steps page of the dialog. 
-
-Minimum Variable Time Step
-This is the smallest time step allowed when variable time steps are used. The default value is 0.5 seconds. Smaller steps may be warranted, but they can lead to longer simulations runs without much improvement in solution quality.
-
-Time Step for Conduit Lengthening
-This is a time step, in seconds, used to artificially lengthen conduits so that they meet the Courant stability criterion under full-flow conditions (i.e., the travel time of a wave will not be smaller than the specified conduit lengthening time step). As this value is decreased, fewer conduits will require lengthening. A value of zero means that no conduits will be lengthened. The ratio of the artificial length to the original length for each conduit is listed in the Flow Classification table that appears in the simulation’s Summary Report (see Section 9.2).
-
-Minimum Nodal Surface Area
-This is a minimum surface area used at nodes when computing changes in water depth. If 0 is entered, then the default value of 12.566 ft2 (1.167 m2) is used. This is the area of a 4-ft diameter manhole. The value entered should be in square feet for US units or square meters for SI units.
-
-Head Convergence Tolerance
-This is the maximum difference in computed heads between successive trials of SWMM’s iterative method for computing a dynamic wave hydraulic solution that determines when convergence is reached within a given time step. The default tolerance is 0.005 ft (0.0015 m).
-
-Maximum Trials per Time Step
-This is the maximum number of trials that SWMM will use in its iterative method for computing a dynamic wave hydraulic solution within each time step. The default value is 8.
-
-
-Number of Parallel Threads to Use
-This selects the number of parallel computing threads to use on machines equipped with multi-core processors. The default is 1. Clicking the   button will display the number of physical cores and logical processors available.  
-
-Clicking the Apply Defaults label will set all the Dynamic Wave options to their default values.
-
-File Options
-
-The Files page of the Simulation Options dialog is used to specify which interface files will be used or saved during the simulation. (Interface files are described in Chapter 11.) The page contains a list box with three buttons underneath it. The list box lists the currently selected files, while the buttons are used as follows:
-Add    adds a new interface file specification to the list.
-Edit     edits the properties of the currently selected interface file.
-Delete     deletes the currently selected interface from the project (but not from your hard drive).
-
- 
-
-When the Add or Edit buttons are clicked, an Interface File Selector dialog appears where one can specify the type of interface file, whether it should be used or saved, and its name. The entries on this dialog are as follows:
-
- 
-
-File Type
-Select the type of interface file to be specified.
-
-Use / Save Buttons
-Select whether the named interface file will be used to supply input to a simulation run or whether simulation results will be saved to it.
-
-File Name
-Click the Select File button   to specify the file name from a standard Windows file selection dialog box.
-
-    Setting Reporting Options
-
-The Reporting Options dialog is used to select individual subcatchments, nodes, and links that will have detailed time series results saved for viewing after a simulation has been run. The default for new projects is that all objects will have detailed results saved for them. The dialog is invoked by selecting the Reporting category of Options from the Project Browser and clicking the    button (or by selecting Edit >> Edit Object from the main menu).
-
-The dialog contains three tabbed pages - one each for subcatchments, nodes, and links. It is a stay-on-top form which means that you can select items directly from the Study Area Map or Project Browser while the dialog remains visible.
-
- 
-
-To include an object in the set that is reported on:
-    Select the tab to which the object belongs (Subcatchments, Nodes or Links).
-    Unselect the "All" check box if it is currently checked.
-    Select the specific object either from the Study Area Map or from the listing in the Project Browser.
-    Click the Add button on the dialog.
-    Repeat the above steps for any additional objects.
-
-To remove an item from the set selected for reporting:
-    Select the desired item in the dialog's list box.
-    Click the Remove button to remove the item.
-
-To remove all items from the reporting set of a given object category, select the object category's page and click the Clear button.
-
-To include all objects of a given category in the reporting set, check the "All" box on the page for that category (i.e., subcatchments, nodes, or links). This will override any individual items that may be currently listed on the page. To dismiss the dialog click the Close button. In addition the following reporting options can be selected from this dialog:
-
-Report Input Summary
-Check this option to have the simulation's Status Report list a summary of the project's input data.
-
-Report Control Actions
-Check this option to have the simulation's Status Report list all discrete control actions taken by the Control Rules associated with a project (continuous modulated control actions are not listed). This option should only be used for short-term simulation.
-
-Report Average Results
-Check this option to have the average of the results for all routing time steps that fall within a reporting time step be reported instead of the instantaneous point results that occur at the end of the reporting time step.
-
-    Selecting Event Periods
-
-Simulation events allow one to limit the periods of time in which a full unsteady hydraulic analysis of the drainage network is performed. For times outside of these periods, the hydraulic state of the network stays the same as it was at the end of the previous hydraulic event. Although hydraulic calculations are restricted to these pre-defined event periods, a full accounting of the system's hydrology is still computed over the entire simulation duration. During inter-event periods any inflows to the network, from runoff, groundwater flow, dry weather flow, etc., are ignored. The purpose of only computing hydraulics for particular time periods is to speed up long-term continuous simulations where one knows in advance which periods of time (such as representative or critical storm events) are of most interest.
-
-To define a set of simulation events select the Events sub-category of Options from the Project Browser and click the    button on the Browser panel or select Edit >> Edit Object from the Main Menu. This will bring up the Events Editor in which multiple event time periods can be defined.
-
-
-
- 
-
-The editor consists of a table listing the start and end date of each event, plus a blank line at the end of the list used for adding a new event. The events do not have to be entered in chronological order. There are date and time selection controls below the table used to edit the dates of a selected event. Clicking the Replace Event button will replace the row with the entries in these controls. The Delete Event button will delete the selected event and the Delete All button will delete all events from the table. The first column of the table contains a check box which determines if the event should be used in the analysis or not.
-
-     To identify event periods of interest, one can first run a simulation with Flow Routing turned off and then perform a statistical frequency analysis on the system's rainfall record (see Section 9.8 Viewing a Statistics Report).
-     When a new event occurs, the water in a storage unit node will remain at the same level it had at the end of the previous event. Therefore one may want to choose event intervals long enough to minimize the effect that storage carryover might have.
-
-    Starting a Simulation
-
-To start a simulation either select Project >> Run Simulation from the Main Menu or click   on the Main Toolbar. A Run Status window will appear which displays the progress of the simulation.
-
- 
-
-To stop a run before its normal termination, click the Stop button on the Run Status window or press the <Esc> key. Simulation results up until the time when the run was stopped will be available for viewing. To minimize the SWMM program while a simulation is running, click the Minimize button on the Run Status window.
-
-If the analysis runs successfully the    icon will appear in the Run Status section of the Status Bar at the bottom of SWMM’s main window. Any error or warning messages will appear in a Status Report window. If you modify the project after a successful run has been made, the status flag changes to   indicating that the current computed results no longer apply to the modified project.
-
-    Troubleshooting Results
-
-When a run ends prematurely, the Run Status dialog will indicate the run was unsuccessful and direct the user to the Status Report for details. The Status Report will include an error statement, code, and description of the problem (e.g., ERROR 138: Node TG040 has initial depth greater than maximum depth). Consult Appendix E for a description of SWMM’s error messages. Even if a run completes successfully, one should check to insure that the results are reasonable. The following are the most common reasons for a run to end prematurely or to contain questionable results.
-
-Unknown ID Error Message
-This message typically appears when an object references another object that was never defined. An example would be a subcatchment whose outlet was designated as N29, but no such subcatchment or node with that name exists. Similar situations can exist for incorrect references made to Curves, Time Series, Time Patterns, Aquifers, Snow Packs, Streets, Inlets, Transects, Pollutants, and Land Uses.
-
-File Errors
-File errors can occur when:
-    a file cannot be located on the user's computer
-    a file being used has the wrong format
-    a file to be written to cannot be opened because the user does not have write privileges for the directory (folder) where the file is to be stored.
-
-Drainage System Layout Errors
-A valid drainage system layout must obey the following conditions:
-    An outfall node can have only one conduit link connected to it.
-    A flow divider node must have exactly two outflow links.
-    A node cannot have more than one dummy link connected to it.
-    Under Kinematic Wave routing, a junction node can only have one outflow link and a regulator link cannot be the outflow link of a non-storage node.
-    Under Dynamic Wave routing there must be at least one outfall node in the network.
-An error message will be generated if any of these conditions are violated.
-
-Excessive Continuity Errors
-When a run completes successfully, the mass continuity errors for runoff, flow routing, and pollutant routing will be displayed in the Run Status window. These errors represent the percent difference between initial storage + total inflow and final storage + total outflow for the entire drainage system. If they exceed some reasonable level, such as 10 percent, then the validity of the analysis results must be questioned. The most common reasons for an excessive continuity error are computational time steps that are too long or conduits that are too short.
- 
-
-In addition to the system continuity error, the Status Report produced by a run (see Section 9.1) will list those nodes of the drainage network that have the largest flow continuity errors. If the error for a node is excessive, then one should first consider if the node in question is of importance to the purpose of the simulation. If it is, then further study is warranted to determine how the error might be reduced.
-
-Unstable Flow Routing Results
-Due to the explicit nature of the numerical methods used for Dynamic Wave routing (and to a lesser extent, Kinematic Wave routing), the flows in some links or water depths at some nodes may fluctuate or oscillate significantly at certain periods of time as a result of numerical instabilities in the solution method. SWMM does not automatically identify when such conditions exist, so it is up to the user to verify the numerical stability of the model and to determine if the simulation results are valid for the modeling objectives. Time series plots at key locations in the network can help identify such situations as can a scatter plot between a link’s flow and the corresponding water depth at its upstream node (see Section 9.5, Viewing Results with a Graph).
-
-Numerical instabilities can occur over short durations and may not be apparent when time series are plotted with a long time interval. When detecting such instabilities, it is recommended that a reporting time step of 1 minute or less be used, at least for an initial screening of results.
-
-The run’s Status Report lists the links having the five highest values of a Flow Instability Index (FII). This index counts the number of times that the flow value in a link is higher (or lower) than the flow in both the previous and subsequent time periods. The index is normalized with respect to the expected number of such ‘turns’ that would occur for a purely random series of values and can range from 0 to 150.
-
-As an example of how the Flow Instability Index can be used, consider Figure 8-1. The solid line plots the flow hydrograph for the link identified as having the highest FII value (100) in a dynamic wave flow routing run that used a fixed time step of 30 seconds. The dashed line shows the hydrograph that results when a variable time step was used instead, which is now completely stable.
-
- 
-Figure 8 1  Flow Instability Index for a flow hydrograph
-
-Flow time series plots for the links having the highest FII’s should be inspected to insure that flow routing results are acceptably stable. Numerical instabilities under Dynamic Wave flow routing can be reduced by:
-    reducing the routing time step
-    utilizing the variable time step option with a smaller time step factor
-    selecting to ignore the inertial terms of the momentum equation
-    selecting the option to lengthen short conduits.
-
-
diff --git a/docs/manuals/user/manual/Chapter9.md b/docs/manuals/user/manual/Chapter9.md
deleted file mode 100644
index 310e1f353..000000000
--- a/docs/manuals/user/manual/Chapter9.md
+++ /dev/null
@@ -1,499 +0,0 @@
-@page user_manual_chapter_9 CHAPTER 9 - VIEWING RESULTS
-
-@tableofcontents
-
-This chapter describes the different ways in which the results of a simulation can be viewed. These include a status report, a summary report, various map views, graphs, tables, and a statistical frequency report.
-
-    Viewing a Status Report
-
-A Status Report is available for viewing after each simulation. It contains:
-    a summary of the main Simulation Options that are in effect
-    a list of any error and warning conditions encountered during the run
-    a summary listing of the project’s input data (if requested in the Simulation Options)
-    a summary of the data read from each rainfall file used in the simulation
-    a description of each control rule action taken during the simulation (if requested in the Simulation Options)
-    the system-wide mass continuity errors for:
-    runoff quantity and quality
-    groundwater flow
-    conveyance system flow and water quality
-    the names of the nodes with the highest individual flow continuity errors
-    the names of the conduits that most often determined the size of the time step used for flow routing (only when the Variable Time Step option is used)
-    the names of the links with the highest Flow Instability Index values
-    the names of the nodes with the highest frequency of non-convergence
-    information on the range of routing time steps taken and the percentage of these that were considered steady state.
-To view the Status Report select Report >> Status from the Main Menu or click the   button on the Main Toolbar and select Status Report from the drop-down menu that appears.
-To copy selected text from the Status Report to a file or to the Windows Clipboard, first select the text to copy with the mouse and then choose Edit >> Copy To from the Main Menu (or press the    button on the Main Toolbar).
-To save both the entire Status Report and Summary Report (discussed next) to file, select File >> Export >> Status/Summary Report from the Main Menu.
-
-    Viewing Summary Results
-
-SWMM's Summary Results report lists summary results for each subcatchment, node, and link in the project through a selectable list of tables. To view the various summary results tables, select Report >> Summary from the Main Menu or click the    button on the Main Toolbar and select Summary Results from the drop-down menu that appears. The Summary Results window looks as follows:
- 
-The drop-down box at the upper left allows you to choose the type of results to view. The selection of tables and the results they display are as follows (items marked with an asterisk can also be viewed as color coded themes on the Study Area Map by selecting them from the Map Browser – see Section 7.1):
-
-
-
-
-
-
-Table    Columns
-Subcatchment Runoff    Total precipitation (in or mm)*
-Total run-on from other subcatchments (in or mm)
-Total evaporation (in or mm)*
-Total infiltration (in or mm)*
-Total runoff depth from impervious areas (in or mm)
-Total runoff depth from pervious areas (in or mm)
-Total runoff depth (in or mm)*
-Total runoff volume (million gallons or million liters)
-Peak runoff (flow units)*
-Runoff coefficient (ratio of total runoff to total precipitation)*
-LID Performance
-    Total inflow volume
-Total evaporation loss 
-Total infiltration loss 
-Total surface outflow 
-Total underdrain outflow 
-Initial storage volume 
-Final storage volume
-Flow continuity error (%) 
-Note: all quantities are expressed as depths (in or mm) over the LID unit’s surface area.
-Groundwater Summary    Total surface infiltration (in or mm)
-Total evaporation (in or mm)
-Total lower seepage (in or mm)
-Total lateral outflow (in or mm)
-Maximum lateral outflow (flow units)
-Average upper zone moisture content (volume fraction)
-Average water table elevation (ft or m)
-Final upper zone moisture content (volume fraction)
-Final water table elevation (ft or m)
-Subcatchment Washoff
-    Total mass of each pollutant washed off the subcatchment (lbs or kg)
-
-
-Node Depth
-    Average water depth (ft or m)
-Maximum water depth (ft or m)*
-Maximum hydraulic head (HGL) (ft or m)*
-Time of maximum depth
-Maximum water depth at reporting times (ft or m)
-Node Inflow    Maximum lateral inflow (flow units)*
-Maximum total inflow (flow units)
-Time of maximum total inflow
-Total lateral inflow volume (million gallons or million liters)*
-Total inflow volume (million gallons or million liters)
-Flow balance error (%)
-Note: Total inflow consists of lateral inflow plus inflow from connecting links.
-Node Surcharge    Hours surcharged
-Maximum height of surcharge above node’s crown (ft or m)
-Minimum depth of surcharge below node’s top rim (ft or m)
-Note: surcharging occurs when water rises above the crown of the highest conduit and only those conduits that surcharge are listed.
-Node Flooding    Hours flooded*
-Maximum flooding rate (flow units)*
-Time of maximum flooding
-Total flood volume (million gallons or million liters)*
-Peak depth (for dynamic wave routing in ft or m) or peak volume (1000 ft3 or 1000 m3) of ponded surface water
-Note: flooding refers to all water that overflows a node, whether it ponds or not, and only those nodes that flood are listed.
-Storage Volume    Average volume of water in the facility (1000 ft3 or 1000 m3)
-Average percent of full storage capacity utilized
-Percent of total stored volume lost to evaporation
-Percent of total stored volume lost to seepage
-Maximum volume of water in the facility (1000 ft3 or 1000 m3)
-Maximum  percent of full storage capacity utilized
-Time of maximum water stored
-Maximum outflow rate from the facility (flow units)
-Outfall Loading    Percent of time that outfall discharges
-Average discharge flow (flow units)
-Maximum discharge flow (flow units)
-Total volume of flow discharged (million gallons or million liters)
-Total mass discharged of each pollutant (lbs or kg)
-Street Flow
-(Street Conduits Only)    Peak flow (flow units)
-Maximum spread from curb (ft or m)
-Maximum depth at curb (ft or m)
-For streets with assigned inlets
-    name of inlet structure
-    inlet location (on-grade or on-sag)
-    peak flow capture efficiency (%)
-    average flow capture efficiency (%)
-    frequency of bypass flow (%)
-    frequency of backflow (%)
-Link Flow    Maximum flow (flow units)*
-Time of maximum flow
-Maximum velocity (ft/sec or m/sec)*
-Ratio of maximum flow to full normal flow
-Ratio of maximum flow depth to full depth*
-Flow Classification
-(Dynamic Wave
- Routing Only)    Ratio of adjusted conduit length to actual length
-Fraction of all time steps spent in the following flow categories:
-    dry on both ends
-    dry on the upstream end
-    dry on the downstream end
-    subcritical flow
-    supercritical flow
-    critical flow at the upstream end
-    critical flow at the downstream end
-Fraction of all time steps flow is limited to normal flow
-Fraction of all time steps flow is inlet controlled (for culverts only)
-Conduit Surcharge    Hours that conduit is full at:
-    both ends*
-    upstream end
-    downstream end
-Hours that conduit flows above full normal flow
-Hours that conduit is capacity limited*
-
-Note: only conduits with one or more non-zero entries are listed and a conduit is considered capacity limited if its upstream end is full and the HGL slope is greater than the conduit slope. 
-Link Pollutant Loads    Total mass load (in lbs or kg) of each pollutant carried by the link over the entire simulation period
-Pumping    Percent of time that the pump is on line
-Number of pump start-ups
-Minimum flow pumped (flow units)
-Average flow pumped (flow units)
-Maximum flow pumped (flow units)
-Total volume pumped (million gallons or million liters)
-Total energy consumed assuming 100% efficiency (Kw-hrs)
-Percent of time that the pump operates below its pump curve
-Percent of time that the pump operates above its pump curve
-
-     The summary results displayed in these tables are based on results found at every computational time step and not just on the results from each reporting time step.
-
-Clicking on the name of an object in the first column of the table will locate that object both in the Project Browser and on the Study Area Map. Clicking on a column heading will sort the entries in the table by the values in that column (alternating between ascending and descending order with each click.
-
-Selecting Edit >> Copy To from the Main Menu or clicking   on the Main Toolbar will allow you to copy the contents of the table to either the Windows Clipboard or to a file. To save both the entire Status Report and all tables of the Summary Report to a file select File >> Export >> Status/Summary Report from the Main Menu.
-
-    Time Series Results
-
-Computed results at each reporting time step for the variables listed in Table 9-1 are available for viewing on the map and can be plotted, tabulated, and statistically analyzed. These variables can be viewed only for those subcatchments, nodes, and links that were selected to have detailed time series results saved for them. This normally includes all objects in the project unless the Reporting option (under the Options category in the Project Browser) was used to select specific objects to report on.
-
-Table 9 1 Time series variables available for viewing
-Subcatchment Variables
-    rainfall rate (in/hr or mm/hr)
-    snow depth (in or mm)
-    evaporation loss ( in/day or mm/day)
-    infiltration loss (in/hr or mm/hr)
-    runoff flow (flow units)
-    groundwater flow into the drainage network (flow units)
-    groundwater elevation (ft or m)
-    soil moisture in the unsaturated groundwater zone (volume fraction)
-    washoff concentration of each pollutant (mass/liter)
-
-Node Variables
-    water depth (ft or m above the node invert elevation)
-    hydraulic head (ft or m, absolute elevation per vertical datum)
-    stored water volume (including ponded water, ft3 or m3)
-    lateral inflow (runoff + all other external inflows, in flow units)
-    total inflow (lateral inflow + upstream conduit inflows, in flow units)
-    surface flooding (excess overflow when the node is at full depth, in flow units)
-    concentration of each pollutant after any treatment applied at the node (mass/liter)    Link Variables
-    flow rate (flow units)
-    average water depth (ft or m)
-    flow velocity (ft/sec or m/sec)
-    volume of water (ft3 or m3)
-    capacity (fraction of full area filled by flow for conduits; control setting for pumps and regulators)
-    concentration of each pollutant (mass/liter)
-
-
-System-Wide Variables
-    air temperature (degrees F or C)
-    potential evaporation (in/day or mm/day)
-    actual evaporation (in/day or mm/day)
-    total rainfall (in/hr or mm/hr)
-    total snow depth (in or mm)
-    average losses (in/hr or mm/hr)
-    total runoff flow (flow units)
-    total dry weather inflow (flow units)
-    total groundwater inflow (flow units)
-    total RDII inflow (flow units)
-    total direct inflow (flow units)
-    total external inflow (flow units)
-    total external flooding (flow units)
-    total outflow from outfalls (flow units)
-    total nodal storage volume ( ft3 or m3)
-
-    Viewing Results on the Map
-
-There are several ways to view the values of certain input parameters and simulation results directly on the Study Area Map: 
-    For the current settings on the Map Browser, the subcatchments, nodes and links of the map will be colored according to their respective Map Legends. The map's color coding will be updated as a new time period is selected in the Map Browser.  
-    When the Flyover Map Labeling program preference is selected (see Section 4.10), moving the mouse over any map object will display its ID name and the value of its current theme parameter in a hint-style box.  
-    ID names and parameter values can be displayed next to all subcatchments, nodes and/or links by selecting the appropriate options on the Annotation page of the Map Options dialog (see Section 7.12).  
-    Subcatchments, nodes or links meeting a specific criterion can be identified by submitting a Map Query (see Section 7.9).  
-    One can animate the display of results on the network map either forward or backward in time by using the controls on the Animator panel of the Map Browser (see Section 4.8).  
-    The map can be printed, copied to the Windows clipboard, or saved as a DXF file or Windows metafile (see Section 7.13).     
- 
-    Viewing Results with a Graph
-
-Analysis results can be viewed using several different types of graphs. Graphs can be printed, copied to the Windows clipboard, or saved to a text file or to a Windows metafile. The following types of graphs can be created from available simulation results: 
-
-
-    Time Series Plot:     
-
-    Profile Plot:     
-
-    Scatter Plot:     
-
-You can zoom in or out of any graph by holding down the <Shift> key while drawing a zoom rectangle with the mouse's left button held down. Drawing the rectangle from left to right zooms in, drawing it from right to left zooms out. The plot can also be panned in any direction by moving the mouse across the plot with the left button held down
-
-An opened graph will normally be redrawn when a new simulation is run. To prevent the automatic updating of a graph once a new set of results is computed you can lock the current graph by clicking the   icon in the upper left corner of the graph. To unlock the graph, click the icon again.
-
-Time Series Plots 
-
-A Time Series Plot graphs the values over time of specific combinations of objects and variables. Up to six time series can be plotted on the same graph. When only a single time series is plotted, and that item has calibration data registered for the plotted variable, then the calibration data will be plotted along with the simulated results (see Section 5.7.2 for instructions on how to register calibration data with a project). 
-
-To create a Time Series Plot, select Report >> Graph >> Time Series from the Main Menu or click   on the Main Toolbar. A Time Series Plot Selection dialog will appear. Use it to describe what objects and quantities should be plotted.
-
- 
-The Time Series Plot Selection dialog selects a set of objects and their variables whose computed time series will be graphed in a Time Series Plot. The dialog is used as follows: 
-    Select a Start Date and End Date for the plot (the default is the entire simulation period).
-    Choose whether to show time as Elapsed Time or as Date/Time values.
-    Add up to six different data series to the plot by clicking the Add button above the data series list box.
-    Use the Edit button to make changes to a selected data series or the Delete button to delete a data series.
-    Use the Up and Down buttons to change the order in which the data series will be plotted.
-    Click the OK button to create the plot.
-
-When you click the Add or Edit buttons a Data Series Selection dialog will be displayed for selecting a particular object and variable to plot. It contains the following data fields:
-
- 
-
-
-
-
-Object Type:     The type of object to plot (Subcatchment, Node, Link or System). 
-
-Object Name:     The ID name of the object to be plotted. (This field is disabled for System variables). 
-
-Variable:     The variable whose time series will be plotted (choices vary by object type). 
-
-Legend Label:     The text to use in the legend for the data series. If left blank, a default label made up of the object type, name, variable and units will be used (e.g. Link C16 Flow (CFS)). 
-
-Axis:     Whether to use the left or right vertical axis to plot the data series.
- 
-     As you select objects on the Study Area Map or in the Project Browser their types and ID names will automatically appear in this dialog.
-
-Click the Accept button to add/update the data series into the plot or click the Cancel button to disregard your edits. You will then be returned to the Time Series Plot Selection dialog where you can add or edit another data series.
-
-     To make a precipitation time series display in inverted fashion on a plot, assign it to the right axis and after the plot is displayed, use the Graph Options Dialog (see Section 9.6)  to invert the right axis and expand the scales of both the left and right axes (so it doesn't overlap another data series).
-
-Profile Plots
-
-A Profile Plot displays the variation in simulated water depth with distance over a connected path of drainage system links and nodes at a particular point in time. Once the plot has been created it will be automatically updated as a new time period is selected using the Map Browser.
-
-To create a Profile Plot:
-    Select Report >> Graph >> Profile from the main menu or press   on the Main Toolbar
-    A Profile Plot Selection dialog will appear (see below). Use it to identify the path along which the profile plot is to be drawn.
-
- 
-
-The Profile Plot Selection dialog is used to select a path of connected conveyance system links along which a water depth profile versus distance should be drawn. To define a path using the dialog:
-    Enter the ID of the upstream node of the first link in the path in the Start Node edit field (or click on the node on the Study Area Map and then on the   button next to the edit field).
-    Enter the ID of the downstream node of the last link in the path in the End Node edit field (or click the node on the map and then click the   button next to the edit field).
-    Click the Find Path button to have the program automatically identify the path with the smallest number of links between the start and end nodes. These will be listed in the Links in Profile box.
-    You can insert a new link into the Links in Profile list by selecting the new link either on the Study Area Map or in the Project Browser and then clicking the   button underneath the Links in Profile list box.
-    Entries in the Links in Profile list can be deleted or rearranged by using the  ,  , and   buttons underneath the list box.
-    Click the OK button to view the profile plot.
-
-To save the current set of links listed in the dialog for future use:
-    Click the Save Current Profile button.
-    Supply a name for the profile when prompted.
-
-To use a previously saved profile:
-    Click the Use Saved Profile button.
-    Select the profile to use from the Profile Selection dialog that appears.
-
-Profile plots can also be created before any simulation results are available, to help visualize and verify the vertical layout of a drainage system. Plots created in this manner will contain a refresh button   in the upper left corner that can be used to redraw the plot after edits are made to any elevation data appearing in the plot.
-
-Scatter Plots
-
-A Scatter Plot displays the relationship between a pair of variables, such as flow rate in a pipe versus water depth at a node. To create a Scatter Plot, select Report >> Graph >> Scatter from the main menu or press    on the Main Toolbar. Then use the Scatter Plot Selection dialog that appears (see below) to specify what time interval and what pair of objects and their variables to plot using the.
-
- 
-
-The Scatter Plot Selection dialog is used to select the objects and variables to be graphed against one another in a scatter plot. Use the dialog as follows:
-    Select a Start Date and End Date for the plot (the default is the entire simulation period).
-    Select the following choices for the X-variable (the quantity plotted along the horizontal axis):
-    Object Category (Subcatchment, Node or Link)
-    Object ID (enter a value or click on the object either on the Study Area Map or in the Project Browser and then click the   button on the dialog)
-    Variable to plot (choices depend on the category of object selected).
-    Do the same for the Y-variable (the quantity plotted along the vertical axis).
-    Click the OK button to create the plot.
-
-    Customizing a Graph’s Appearance
-
-To customize the appearance of a graph:
-    Make the graph the active window (click on its title bar).
-    Select Report >> Customize from the Main Menu, or click   on the Main Toolbar, or right-click on the graph.
-    Use the Graph Options dialog that appears to customize the appearance of a Time Series or Scatter Plot, or use the Profile Plot Options dialog for a Profile Plot.
-
-The Graph Options dialog is used to customize the appearance of a time series plot, a scatter plot, or a frequency plot (described in Section9.8). To use the dialog: 
-    Select from among the four tabbed pages that cover the following categories of options: General, Axes, Legend, and Styles.
-    Check the Default box to use the current settings as defaults for all new graphs as well.
-    Select OK to accept your selections.
-
- 
-
-Graph Options - General
-
-The following options can be set on the General page of the Graph Options dialog box:
-Panel Color    Color of the panel that contains the graph
-Start Background Color    Starting gradient color of graph's plotting area
-End Background Color    Ending gradient color of graph’s plotting area
-View in 3D    Check if graph should be drawn in 3D
-3D Effect Percent    Degree to which 3D effect is drawn
-Main Title    Text of graph's main title
-Font    Click to set the font used for the main title
-
-The figure below shows a 3D graph with White as the Start Background Color and Sky Blue as the End Background Color.
-
- 
-
-Graph Options - Axes
-
-The Axes page of the Graph Options dialog box adjust the way that the axes are drawn on a graph. One first selects an axis (Bottom, Left or Right (if present)) to work with and then selects from the following options:
-
-Gridlines    Displays grid lines on the graph.
-Inverted    Inverts the scale of the right vertical axis.
-Auto Scale    Fills in the Minimum, Maximum and Increment boxes with an automatic axis scaling.
-Minimum    Sets the minimum axis value (the minimum data value is shown in parentheses). Can be left blank.
-Maximum    Sets the maximum axis value (the maximum data value is shown in parentheses). Can be left blank.
-Increment    Sets the increment between axis labels. If left blank or set to zero the program will automatically select an increment.
-Axis Title    Text of axis title.
-Font    Click to select a font for the axis title.
-
-Graph Options - Legend
-
-The Legend page of the Graph Options dialog box controls how the legend is displayed on the graph.
-
-Position    Selects where to place the legend.
-Color    Selects color to use for legend background.
-Check Boxes    If selected, check boxes will appear next to each legend entry, allowing one to make the data series visible or invisible on the graph.
-Framed    Places a frame around the legend.
-Shadowed    Places a shadow behind the legend’s text.
-Transparent    Makes the legend background transparent.
-Visible    Makes the legend visible.
-Symbol Width    Selects the width used to draw the symbol portion of a legend item, as a percentage of the length of the longest legend label.
-
-Graph Options - Styles
-
-The Styles page of the Graph Options dialog box controls how individual data series (or curves) are displayed on a graph. To use this page: 
-    Select a data series to work with from the Series combo box.
-    Edit the title used to identify this series in the legend.
-    Click the Font button to change the font used for the legend. (Other legend properties are selected on the Legend page of the dialog.)
-    Select a property of the data series you would like to modify (not all properties are available for some types of graphs). The choices are: 
-    Lines
-    Markers
-    Patterns
-    Labels
-
-
-
-Profile Plot Options Dialog
-
-The Profile Plot Options dialog is used to customize the appearance of a Profile Plot. The dialog contains five pages:
-
- 
- 
-Colors:
-    Selects the color to use for the plot window panel, the plot background, a conduit’s interior, and the depth of filled water.
-Styles:
-    Selects to use thick lines or not when drawing conduits and the ground profile.
-    Selects to display the ground profile or not.
-    Includes a "Display Conduits Only" check box that provides a closer look at the water levels within conduits by removing all other details from the plot.
-Axes:
-    Edits the main and axis titles, including their fonts.
-    Selects to display horizontal and vertical axis grid lines.
-
-
-Vertical Scale:
-    Lets one choose the minimum, maximum, and increment values for the vertical axis scale, or have SWMM set the scale automatically. If the increment field contains 0 or is left blank the program will automatically select an increment to use.
-Node Labels:
-    Selects to display node ID labels either along the plot’s top axis, directly on the plot above the node’s crown height, or both.
-    Selects the length of arrow to draw between the node label and the node’s crown on the plot (use 0 for no arrows).
-    Selects the font size of the node ID labels.
-
-Check the Default box to have these options (except the Vertical Scale) apply to all new profile plots when they are first created.
-
-    Viewing Results with a Table
-
-Time series results for selected variables and objects can also be viewed in a tabular format. There are two types of formats available: 
-    Table by Object - tabulates the time series of several variables for a single object (e.g., flow and water depth for a conduit).
-
- 
-  
-    Table by Variable - tabulates the time series of a single variable for several objects of the same type (e.g., runoff for a group of subcatchments).  
-
- 
-
-To create a tabular report: 
-    Select Report >> Table from the Main Menu or click   on the Main Toolbar.  
-    Choose the table format (either By Object or By Variable) from the sub-menu that appears.  
-    Fill in the Table by Object or Table by Variable dialogs to specify what information the table should contain.  
- 
-The Table by Object dialog is used when creating a time series table of several variables for a single object. Use the dialog as follows:
-
- 
-
-
-    Select a Start Date and End Date for the table (the default is the entire simulation period).
-    Choose whether to show time as Elapsed Time or as Date/Time values.
-    Choose an Object Category (Subcatchment, Node, Link, or System).
-    Identify a specific object in the category by clicking the object either on the Study Area Map or in the Project Browser and then clicking the   button on the dialog. Only a single object can be selected for this type of table.
-    Check off the variables to be tabulated for the selected object. The available choices depend on the category of object selected.
-    Click the OK button to create the table.
-
-The Table by Variable dialog is used when creating a time series table of a single variable for one or more objects. Use the dialog as follows:
-
- 
-
-    Select a Start Date and End Date for the table (the default is the entire simulation period).
-    Choose whether to show time as Elapsed Time or as Date/Time values.
-    Choose an Object Category (Subcatchment, Node or Link).
-    Select a simulated variable to be tabulated. The available choices depend on the category of object selected.
-    Identify one or more objects in the category by successively clicking the object either on the Study Area Map or in the Project Browser and then clicking the    button on the dialog.
-    Click the OK button to create the table.
-
-Objects already selected can be deleted, moved up in the order or moved down in the order by clicking the  ,  , and   buttons, respectively.
-
-    Viewing a Statistics Report
-
-A Statistics Report can be generated from the time series of simulation results. For a given object and variable this report will do the following: 
-    segregate the simulation period into a sequence of non-overlapping events, either by day, month, or by flow (or volume) above some minimum threshold value, 
-    compute a statistical value that characterizes each event, such as the mean, maximum, or total sum of the variable over the event's time period,
-    compute summary statistics for the entire set of event values (mean, standard deviation and skewness),
-    perform a frequency analysis on the set of event values. 
-The frequency analysis of event values will determine the frequency at which a particular event value has occurred and will also estimate a return period for each event value. Statistical analyses of this nature are most suitable for long-term continuous simulation runs. 
-
-To generate a Statistics Report: 
-    Select Report >> Statistics from the Main Menu or click   on the Main Toolbar.  
-    Fill in the Statistics Report Selection dialog that appears, specifying the object, variable, and event definition to be analyzed.  
-
- 
-
-Object Category
-Select the category of object to analyze (Subcatchment, Node, Link or System).
-
-Object Name
-Enter the ID name of the object to analyze. Instead of typing in an ID name, you can select the object on the Study Area Map or in the Project Browser and then click the   button to select it into the Object Name field.
-
-Variable Analyzed
-Select the variable to be analyzed. The available choices depend on the object category selected (e.g., rainfall, losses, or runoff for subcatchments; depth, inflow, or flooding for nodes; depth, flow, velocity, or capacity for links; water quality for all categories).
-
-Event Time Period
-Select the length of the time period that defines an event. The choices are daily, monthly, or event-dependent. In the latter case, the event period depends on the number of consecutive reporting periods where simulation results are above the threshold values defined below.
-
-Statistic
-Choose an event statistic to be analyzed. The available choices depend on the choice of variable to be analyzed and include such quantities as mean value, peak value, event total, event duration, and inter-event time (i.e., the time interval between the midpoints of successive events). For water quality variables the choices include mean concentration, peak concentration, mean loading, peak loading, and event total load.
-
-Event Thresholds
-These define minimum values that must be exceeded for an event to occur:
-    The Analysis Variable threshold specifies the minimum value of the variable being analyzed that must be exceeded for a time period to be included in an event.
-    The Event Volume threshold specifies a minimum flow volume (or rainfall volume) that must be exceeded for a result to be counted as part of an event.
-    Separation Time sets the minimum number of hours that must occur between the end of one event and the start of the next event. Events with fewer hours are combined together. This value applies only to event-dependent time periods (not to daily or monthly event periods).
-If a particular type of threshold does not apply, then leave the field blank.
- 
-After the choices made on the Statistics Selection dialog form are processed, a Statistics Report is produced as shown below. It consists of four tabbed pages that contain: 
-    a table of event summary statistics
-    a table of rank-ordered event periods, including their date, duration, and magnitude
-    a histogram plot of the chosen event statistic
-    an exceedance frequency plot of the event values.
-
-The exceedance frequencies included in the Statistics Report are computed with respect to the number of events that occur, not the total number of reporting periods. 
-
-
diff --git a/docs/manuals/user/user_manual.md b/docs/manuals/user/user_manual.md
deleted file mode 100644
index f71fc9529..000000000
--- a/docs/manuals/user/user_manual.md
+++ /dev/null
@@ -1,58 +0,0 @@
-
-@page user_manual OpenSWMM User Manual
-
-

-OpenSWMM User Manual
-=====================================
-

-
-

-
-See @ref authors for the full list of authors and contributors.
-
-

-
-## DISCLAIMER {#user_manual_disclaimer}
-
-This software is provided on an "as is" basis and the user assumes responsibility for its use. Although a reasonable effort has been made to assure that the results obtained are correct, the authors are not responsible and assume no liability whatsoever for any results or any use made of the results obtained from these programs, nor for any damages or litigation that result from the use of these programs for any purpose.
-
-## ABSTRACT {#user_manual_abstract}
-
-The Storm Water Management Model (SWMM) is a dynamic rainfall-runoff simulation model used for single event or long-term (continuous) simulation of runoff quantity and quality from primarily urban areas. The runoff component of SWMM operates on a collection of subcatchment areas that receive precipitation and generate runoff and pollutant loads. The routing portion of SWMM transports this runoff through a system of pipes, channels, storage/treatment devices, pumps, and regulators. SWMM tracks the quantity and quality of runoff generated within each subcatchment, and the flow rate, flow depth, and quality of water in each pipe and channel during a simulation period comprised of multiple time steps. This user's manual describes in detail how to use the OpenSWMM computational engine. It includes instructions on how to build a drainage system model, how to set various simulation options, and how to view results in a variety of formats. It also describes the different types of files used and provides useful tables of parameter values. Detailed descriptions of the theory and numerical methods can be found in the separate reference manuals.
-
-## FOREWORD {#user_manual_foreward}
-
-OpenSWMM is the next generation of the EPA Storm Water Management Model, maintained and advanced as a community-driven open source project. It builds on the foundational work of EPA's SWMM, which was first released in 1971 and has undergone several major upgrades since then. OpenSWMM preserves the rich legacy of SWMM while advancing the codebase with modern architecture, improved modularity, enhanced performance, and support for model coupling through the HydroCouple framework.
-
-SWMM is used throughout the world for planning, analysis, and design related to stormwater runoff, combined and sanitary sewers, and other drainage systems. It can be used to evaluate gray infrastructure stormwater control strategies, such as pipes and storm drains, and is a useful tool for creating cost-effective green/gray hybrid stormwater control solutions.
-
-## ACKNOWLEDGEMENTS {#user_manual_acknowledgements}
-
-OpenSWMM builds on the original EPA Storm Water Management Model (SWMM), developed by the U.S. Environmental Protection Agency, Office of Research and Development. The original user's manual and SWMM 5 software were created by **Lewis A. Rossman**, Environmental Scientist Emeritus at the U.S. EPA. His extraordinary contribution to the field of stormwater modeling is gratefully acknowledged.
-
-The original SWMM documentation was reviewed by Michelle Simon, Katherine Ratliff, and Anne Mikelonis, all of the U.S. EPA, by Robert Dickinson (Innovyze), Mitch Heineman (CDM Smith), Mike Gregory (CHI), and Nandana Perera (CHI).
-
-See @ref authors for the complete list of authors and contributors.
-
-@tableofcontents
-
-## Manual Contents
-
-- @subpage user_manual_introductions — CHAPTER 1 – INTRODUCTION
-- @subpage user_manual_chapter_2 — CHAPTER 2 – QUICK START TUTORIAL
-- @subpage user_manual_chapter_3 — CHAPTER 3 - SWMM’S CONCEPTUAL MODEL
-- @subpage user_manual_chapter_4 — CHAPTER 4 - SWMM’S MAIN WINDOW
-- @subpage user_manual_chapter_5 — CHAPTER 5 - WORKING WITH PROJECTS
-- @subpage user_manual_chapter_6 — CHAPTER 6 - WORKING WITH OBJECTS
-- @subpage user_manual_chapter_7 — CHAPTER 7 - WORKING WITH THE MAP
-- @subpage user_manual_chapter_8 — CHAPTER 8 - RUNNING A SIMULATION
-- @subpage user_manual_chapter_9 — CHAPTER 9 - VIEWING RESULTS
-- @subpage user_manual_chapter_10 — CHAPTER 10 - PRINTING AND COPYING
-- @subpage user_manual_chapter_11 — CHAPTER 11 - FILES USED BY SWMM
-- @subpage user_manual_chapter_12 — CHAPTER 12 - USING ADD-IN TOOLS
-- @subpage user_manual_chapter_13 — CHAPTER 13 – PROGRAMMATIC C API
-- @subpage user_manual_appendix_a — APPENDIX A - USEFUL TABLES
-- @subpage user_manual_appendix_b — APPENDIX B - VISUAL OBJECT PROPERTIES
-- @subpage user_manual_appendix_c — APPENDIX C - SPECIALIZED PROPERTY EDITORS
-- @subpage user_manual_appendix_d — APPENDIX D - COMMAND LINE SWMM
-- @subpage user_manual_appendix_e — APPENDIX E - ERROR AND WARNING MESSAGES
diff --git a/docs/releases/RELEASE_NOTES_6.0.0-alpha.4.md b/docs/releases/RELEASE_NOTES_6.0.0-alpha.4.md
new file mode 100644
index 000000000..29735f596
--- /dev/null
+++ b/docs/releases/RELEASE_NOTES_6.0.0-alpha.4.md
@@ -0,0 +1,56 @@
+# OpenSWMM Engine 6.0.0-alpha.4
+
+**Pre-release.** APIs, file formats and defaults may still change before 6.0.0.
+
+Covers everything merged since [`v6.0.0-alpha.3`](https://github.com/HydroCouple/openswmm.engine/releases/tag/v6.0.0-alpha.3) (2026-08-11) — 285 commits. See [`CHANGELOG.md`](https://github.com/HydroCouple/openswmm.engine/blob/main/CHANGELOG.md) for the itemized record.
+
+---
+
+## Licence change
+
+The engine is **relicensed from MIT to the Apache License, Version 2.0** (#123, #122). Apache 2.0 keeps the permissive terms downstream users rely on and adds an explicit patent grant and contribution clause. If you redistribute the engine, review your attribution and NOTICE handling before upgrading.
+
+## Highlights
+
+### A finite-volume 1D routing solver
+
+`FLOW_ROUTING FV` selects an explicit, conservative finite-volume solver alongside the existing dynamic-wave routing. It arrives with second-order MUSCL reconstruction (`FV_ORDER 2`), local time stepping (`FV_LTS`, on by default), semi-implicit node coupling (`FV_NODE_COUPLING`), `FV_TIME_INTEGRATION RK2`, cell-resolved Eulerian scalar transport on the FV mesh, DUMMY-link routing, and FV solver statistics in the report file. `RouteModel.FV` is exposed in the Python bindings and `FV` in the MCP server.
+
+Several mass-balance defects found while validating it are fixed in this cycle: junction storage lost from the FV routing balance, storage-node evaporation and exfiltration charged to the wrong term, conduit seepage 43,200× too large under US units, and a model the mesher could not handle running with no routing at all rather than failing. The depth inversion is also 3.2× faster at bit-identical results, and published node stages no longer stand above the conduits they connect.
+
+### Pressurized flow and unsteady friction
+
+A **two-component pressure approach (TPA)** models sub-atmospheric pressurized flow, and **unsteady friction** (`UNSTEADY_FRICTION VITKOVSKY`, `UF_K3`) is available in both solvers. `REPORT_SIGNED_HEADS` writes true signed piezometric heads to the `.out` file, and virtual-junction initial state is now seeded under dynamic-wave routing.
+
+### 2D: momentum closures and mixed meshes
+
+`MOMENTUM_EQUATION FULL_SWE | DIFFUSIVE_WAVE` selects the 2D momentum closure, and the mesh may now mix triangles and quadrilaterals. `swmm_2d_get_run_stats` / `Surface2D.run_stats` report the solver backend, momentum closure and local-time-stepping tiers actually used for a run. A prescribed-discharge boundary under `FULL_SWE` now delivers exactly what it prescribes, per-cell cumulative rainfall volume is written to the 2D sidecar, and the 2D results file records what its coordinates mean (`Mesh2_node_x/y`). A performance regression introduced by the tri-quad and `FULL_SWE` work is fixed, with LOCAL_INERTIAL results byte-identical before and after.
+
+### Street inlets
+
+A legacy-parity **HEC-22 capture kernel**, `[INLET_JUNCTIONS]`, and an inlet editor round-trip. `[INLETS]` two-line combination inlets are now merged correctly, and `[INLET_USAGE]` — previously parsed but never written — round-trips.
+
+### Transport and water quality
+
+A **Lagrangian transport engine (LARD)** joins the quality solvers, MSX species now ride LARD segments and react, and water age and ARD write their own configuration files, completing the IO3 save work. `TEMP` is available in reaction expressions for temperature-dependent kinetics, and heat transport gains incoming shortwave forcing (`[RADIATIVE_FLUXES]`). A `[POLLUTANTS]` Kdecay defect that applied decay **86,400× too fast** is fixed.
+
+### Round-trip integrity
+
+A family of save-path defects is closed. Groundwater was **silently lost on every save** (`[AQUIFERS]`, `[GROUNDWATER]`); a `[GROUNDWATER]` receiving node declared later in the file was never resolved; links declared before the node sections orphaned silently; five writers emitted `*` where the name was known, three of them fatally; four external-file slots were written verbatim rather than as authored; and a `[2D_MESH_FILE]` reference dangled after Save As. The `.inp` writer now emits authored form for offsets and conduit orientation, and a GUI-editor round-trip API exists for `[GWF]` expressions.
+
+### Interfaces and performance
+
+**Live `.out` reading** — `swmm_output_open_live(path)` opens a binary results file while the run that is writing it is still going. The **C / Python / MCP parity matrix is at zero gaps in all three columns**, with Python bindings for the five transport-process headers and Preissmann slot / 2-D name and bulk accessors. Model load and initialization are **up to 17× faster**.
+
+---
+
+## Upgrading
+
+- Review the licence change above before redistributing.
+- `FLOW_ROUTING FV` and `MOMENTUM_EQUATION` are opt-in; existing models keep their previous routing.
+- Models that relied on the Kdecay defect will now decay at the authored rate.
+- Models with groundwater that were saved by an earlier build should be checked — `[AQUIFERS]` and `[GROUNDWATER]` may have been dropped on save.
+
+## Acknowledgements
+
+Thanks to everyone who filed the issues driving this cycle, in particular the pressurized-flow, inlet and groundwater reports.
diff --git a/docs/tags/swmmvis-manual.tag b/docs/tags/swmmvis-manual.tag
new file mode 100644
index 000000000..d0b34526d
--- /dev/null
+++ b/docs/tags/swmmvis-manual.tag
@@ -0,0 +1,214 @@
+
+
+  
+    manual_introduction
+    01 — Introduction and Getting Started
+    df/d83/manual_introduction.html
+  
+  
+    manual_interface
+    02 — The Interface
+    d0/d85/manual_interface.html
+  
+  
+    manual_projects
+    03 — Working with Projects
+    d7/d3e/manual_projects.html
+  
+  
+    manual_preferences
+    04 — Preferences
+    d3/dd3/manual_preferences.html
+  
+  
+    manual_map_navigation
+    05 — The Map Canvas
+    d3/dfe/manual_map_navigation.html
+  
+  
+    manual_crs
+    06 — Coordinate Reference Systems
+    dc/d46/manual_crs.html
+  
+  
+    manual_layers
+    07 — Layers and Data Sources
+    dc/da0/manual_layers.html
+  
+  
+    manual_styling
+    08 — Styling, Labels and Legends
+    df/dd8/manual_styling.html
+  
+  
+    manual_selection
+    09 — Selection and Search
+    d7/d49/manual_selection.html
+  
+  
+    manual_object_browser
+    10 — Object Browser, Properties and Section View
+    d5/d1b/manual_object_browser.html
+  
+  
+    manual_attribute_tables
+    11 — Attribute Tables and the Attribute Calculator
+    d0/d53/manual_attribute_tables.html
+  
+  
+    manual_map_editing
+    12 — Editing the Network on the Map
+    d2/dec/manual_map_editing.html
+  
+  
+    manual_hydrology
+    13 — Hydrology: Rain Gages, Subcatchments, LID, Snow, Groundwater and RDII
+    d5/dbf/manual_hydrology.html
+  
+  
+    manual_hydraulics
+    14 — Hydraulics: Nodes, Links, Cross-Sections, Streets, Inlets and Controls
+    d2/d7e/manual_hydraulics.html
+  
+  
+    manual_climate
+    15 — Climate: Temperature, Evaporation, Wind, Snowmelt and Solar Radiation
+    d8/d0f/manual_climate.html
+    climate_solar
+  
+  
+    manual_water_quality
+    16 — Water Quality, Reaction Systems, Water Age and Heat
+    dc/dc1/manual_water_quality.html
+  
+  
+    manual_data_objects
+    17 — Time Series, Curves, Patterns and Calibration Data
+    db/d1f/manual_data_objects.html
+  
+  
+    manual_simulation_options
+    18 — Simulation Options
+    d6/d35/manual_simulation_options.html
+  
+  
+    manual_2d_mesh
+    19 — 2D Overland Flow: Meshes, Cell Parameters, Boundary Conditions and 1D–2D Coupling
+    d5/d72/manual_2d_mesh.html
+  
+  
+    manual_running
+    20 — Running a Simulation
+    db/d53/manual_running.html
+  
+  
+    manual_results
+    21 — Results Layers, Result Styling and Animation
+    d5/ddc/manual_results.html
+  
+  
+    manual_time_series_plots
+    22 — Time-Series and Comparison Plots
+    d5/d38/manual_time_series_plots.html
+  
+  
+    manual_profile_plots
+    23 — Profile Plots
+    db/d2d/manual_profile_plots.html
+  
+  
+    manual_tabular_results
+    24 — Tabular Results and Reports
+    d9/da8/manual_tabular_results.html
+  
+  
+    manual_analysis_tools
+    25 — Analysis Tools: Flow Balance, Travel Time, Rainfall Visualisation, 2D Cell Time Series
+    de/d19/manual_analysis_tools.html
+  
+  
+    manual_shortcuts
+    A1 — Keyboard Shortcuts
+    df/db3/manual_shortcuts.html
+  
+  
+    manual_file_formats
+    A2 — File Formats
+    d5/db9/manual_file_formats.html
+  
+  
+    manual_plugins
+    A3 — Plugins
+    d3/dbc/manual_plugins.html
+  
+  
+    manual_performance
+    A4 — Performance and Redraw Policy
+    db/d32/manual_performance.html
+  
+  
+    manual_troubleshooting
+    A5 — Troubleshooting
+    d3/dad/manual_troubleshooting.html
+  
+  
+    manual_about
+    A6 — About, Credits and Licences
+    dc/d47/manual_about.html
+  
+  
+    manual_reference_tables
+    A7 — Reference Tables
+    dd/d60/manual_reference_tables.html
+  
+  
+    manual_error_codes
+    A8 — Error and Warning Codes
+    d0/db8/manual_error_codes.html
+  
+  
+    manual_property_index
+    A9 — Object Property Index
+    d8/d06/manual_property_index.html
+  
+  
+    tutorial_site_drainage
+    T1 — Site Drainage with Water Quality
+    d1/d79/tutorial_site_drainage.html
+  
+  
+    tutorial_street_inlets
+    T2 — Streets, Inlets and the Inlet Junction
+    d9/dee/tutorial_street_inlets.html
+  
+  
+    tutorial_2d_inundation
+    T3 — From a DTM to an Animated 2D Inundation Map
+    db/dfb/tutorial_2d_inundation.html
+  
+  
+    tutorial_1d2d_coupling
+    T4 — Capped Street Inlets Coupled to a 2D Surface
+    da/d26/tutorial_1d2d_coupling.html
+  
+  
+    tutorial_2d_boundaries
+    T5 — Culverts, Embankments, Boundary Conditions and Edge Conveyance
+    d9/da6/tutorial_2d_boundaries.html
+  
+  
+    tutorial_pure_2d
+    T6 — A Stand-alone 2D Overland-Flow Model
+    d7/d3b/tutorial_pure_2d.html
+  
+  
+    tutorial_transport
+    T7 — Transport: ARD Solvers, Reaction Systems, Water Age and Heat
+    de/dc6/tutorial_transport.html
+  
+  
+    tutorial_bellinge
+    T8 — Bellinge: A Real-World Catchment with an External Mesh; DEM; Long Rain Records and Basemaps
+    d1/dd8/tutorial_bellinge.html
+  
+  
diff --git a/examples/2d_complete_example.inp b/examples/2d_complete_example.inp
index d39169afa..d7b47fbef 100644
--- a/examples/2d_complete_example.inp
+++ b/examples/2d_complete_example.inp
@@ -80,6 +80,7 @@ J1      99.0       1.5       0.0        0.0       0.0
 [OUTFALLS]
 ;;Name  Elevation  Type   Stage      Gated   Route To
 OUT1    98.0       FREE   *          NO
+OUT2    98.0       FREE   *          NO
 
 
 [STORAGE]
@@ -92,7 +93,7 @@ ST1     99.5   1.5       0.0        FUNCTIONAL  0      0    5.0    0         0
 [CONDUITS]
 ;;Name  FromNode  ToNode  Length  Roughness  InOffset  OutOffset  InitFlow  MaxFlow
 C1      J1        OUT1    100     0.013      0         0          0         0
-C2      ST1       OUT1     50     0.013      0         0          0         0
+C2      ST1       OUT2     50     0.013      0         0          0         0
 
 
 [XSECTIONS]
@@ -238,6 +239,7 @@ OUTPUT_FILE             2d_complete_example.h5   ;; HDF5 output (relative to thi
 J1       10.0      10.0
 ST1      15.0      15.0
 OUT1     22.0       0.0
+OUT2     22.0      15.0
 
 
 [MAP]
diff --git a/examples/inlets/README.md b/examples/inlets/README.md
new file mode 100644
index 000000000..bd9cc258b
--- /dev/null
+++ b/examples/inlets/README.md
@@ -0,0 +1,103 @@
+# Street inlets and the inlet junction
+
+`street_inlet_junction.inp` is a five-link model that puts the two ways of
+attaching a street inlet side by side on one street reach, so their report
+output can be compared directly.
+
+```
+J_TOP --ST_A--> J_MID --ST_B--> [IJ1] --ST_C--> OUT_ST   street, on grade
+          |            capture     |  capture
+          +--> MH1 --SW_1--> MH2 --+--SW_2--> OUT_SEW    sewer, buried
+```
+
+A two-hour gutter hydrograph (peak 12 cfs) enters at `J_TOP`. Both inlets are
+on grade; neither is flow-limited; both are 10 % clogged.
+
+| | Attachment | Design | Captures to |
+|---|---|---|---|
+| Conduit-attribute inlet | `[INLET_USAGE]` on conduit `ST_A` | `Combo1` (2 inlets) | `MH1` |
+| Inlet junction | `[INLET_JUNCTIONS]` node `IJ1`, between `ST_B` and `ST_C` | `Curb1` (1 inlet) | `MH2` |
+
+## What the two forms differ in
+
+A conduit-attribute inlet is an *attribute of a link*: capture is booked at the
+host conduit's downstream node, and the bypass simply stays there. There is no
+object at the inlet — you cannot give it a coordinate, a flood volume, or a
+ponded depth of its own.
+
+An inlet junction is a *node*. It sits at a real point on the street, so the
+gutter depth at the inlet is the node depth, it can flood above the curb, and
+the momentum of the street flow passes through it (it is a virtual junction:
+zero storage, exactly two conduits of the same cross-section, zero offsets,
+DYNWAVE only). Backflow from a surcharging capture node re-enters the street
+at that point rather than at an abstract node.
+
+A conduit attached to an inlet junction may not also carry an `[INLET_USAGE]`
+row — that would capture the same water twice (rule 629). That is why the
+conduit-attribute inlet in this deck sits on `ST_A`, upstream of the pair.
+
+## Running it
+
+```
+openswmm-cli examples/inlets/street_inlet_junction.inp street_inlet_junction.rpt
+```
+
+## What to look for in the report
+
+**Street Flow Summary** — one row per STREET conduit, with peak flow, maximum
+spread (the width of water on the pavement) and maximum depth.
+
+* `ST_A` carries the full hydrograph. Its peak spread is the widest in the
+  model; compare it to the street's `Tcrown` of 20 ft to see how close the
+  water gets to the crown.
+* `ST_B` carries what `Combo1` did not capture, so its peak flow is lower than
+  `ST_A`'s by the peak capture reported below, and its spread is narrower.
+* `ST_C` carries what `Curb1` did not capture, and is narrower again. The
+  three rows read as a staircase down the reach — that staircase is the whole
+  point of putting inlets on a street.
+
+**Street Inlet Flow Summary** — one row per inlet placement. The conduit
+inlet is listed under its host link name (`ST_A`); the inlet junction is
+listed under its node name with a `(node)` marker (`IJ1 (node)`).
+
+* *Peak Flow* is the approach flow the inlet saw; *Peak Capture Pcnt* is the
+  capture efficiency at that peak, and *Avg. Capture Pcnt* the average over
+  every period with capture. A curb-opening inlet on grade loses efficiency
+  as flow rises, so expect the peak-flow efficiency to sit below the average.
+* *Bypass Flow Pcnt* is how often capture was partial. On a on-grade inlet
+  with a rising hydrograph it should approach 100 %.
+* *Back Flow Pcnt* is how often the capture node pushed water back up onto the
+  street. It is 0 in this deck — the sewer never surcharges. To make it
+  non-zero, shrink `SW_2` to `1.0` ft or raise the hydrograph peak, then watch
+  `IJ1`'s backflow column and `ST_C`'s spread grow together.
+* *Vol. Captured* / *Vol. Bypassed* close against the street continuity: the
+  volume `ST_A` delivered equals what `Combo1` captured plus what it passed to
+  `ST_B`.
+
+**Node Depth / Flooding summaries** — `IJ1` appears as an ordinary junction.
+Its `MaxDepth` of 0.5 ft is the flood threshold at the curb, so a peak that
+exceeds the inlet's capacity floods `IJ1` rather than backing up into a
+fictitious storage volume. `J_MID`, the conduit inlet's capture point, has no
+such threshold of its own: that is the modelling difference the two forms make.
+
+## Variations worth trying
+
+* **Swap in the custom capture curve.** `Custom1` (a `CUSTOM` design reading
+  the `DIV_CAP` `DIVERSION` curve — captured flow as a function of approach
+  flow) is defined but unplaced. Put it on the inlet junction by changing the
+  `Inlet` column of the `[INLET_JUNCTIONS]` row from `Curb1` to `Custom1`, and
+  the HEC-22 curb-opening equations are replaced by a table lookup. The
+  `[INLETS]` `CUSTOM` line carries no kind token — the curve's own `[CURVES]`
+  type decides whether it is read as a diversion curve (approach flow) or a
+  rating curve (ponded depth).
+* **Use the unplaced grate.** `Grate1` is a plain `GRATE` design; swapping it
+  for `Combo1` on the `[INLET_USAGE]` row shows how much of the combination
+  inlet's capture came from the curb opening rather than the grate.
+* **Make the inlet junction a sag.** Raise `OUT_ST` above `IJ1` so both `ST_B`
+  and `ST_C` fall toward the node, and set the `Placement` column to
+  `AUTOMATIC`. The inlet switches to the sag (weir/orifice) equations and the
+  capture becomes a function of the ponded depth at `IJ1`.
+* **Fuse the inlet junction away.** Through the editing API,
+  `editor.fuse_inlet_junction("IJ1")` merges `ST_B` and `ST_C` back into one
+  conduit and drops the usage row; `editor.split_conduit_inlet(...)` is the
+  inverse.
diff --git a/examples/inlets/street_inlet_junction.inp b/examples/inlets/street_inlet_junction.inp
new file mode 100644
index 000000000..b08e2197c
--- /dev/null
+++ b/examples/inlets/street_inlet_junction.inp
@@ -0,0 +1,234 @@
+;;============================================================================
+;; OpenSWMM — Street Inlets and the Inlet Junction
+;;
+;; One street reach draining to a parallel sewer through two street inlets,
+;; each attached a different way:
+;;
+;;   1. A conduit-attribute inlet — the legacy form. [INLET_USAGE] puts design
+;;      Combo1 on street conduit ST_A; captured flow is booked at ST_A's
+;;      downstream node (J_MID) and delivered to manhole MH1. The uncaptured
+;;      (bypass) flow stays on the street and continues down ST_B.
+;;
+;;   2. An inlet junction — the spatially explicit form. IJ1 is a node of its
+;;      own between street conduits ST_B and ST_C: it captures the gutter flow
+;;      arriving on ST_B, delivers it to MH2, passes the bypass on through
+;;      ST_C, can flood above the curb, and takes MH2's surcharge back onto
+;;      the street as backflow. An inlet junction is a virtual junction
+;;      (zero storage, momentum transmitting) that also carries an inlet, so
+;;      it obeys every [VIRTUAL_JUNCTIONS] rule: exactly two conduits, the
+;;      same cross-section on both, zero offsets, DYNWAVE routing.
+;;
+;; [INLETS] shows all four design grammars: a GRATE line, a CURB line with a
+;; throat angle, the two-line COMBO encoding (one GRATE line and one CURB line
+;; sharing a name, merged into a single combination design), and a CUSTOM
+;; design pointing at a DIVERSION curve. Grate1 and Custom1 are library
+;; designs here — nothing places them; see README.md for how to swap one in.
+;;
+;;   J_TOP --ST_A--> J_MID --ST_B--> [IJ1] --ST_C--> OUT_ST   (street, at grade)
+;;             |            capture     |  capture
+;;             +--> MH1 --SW_1--> MH2 --+--SW_2--> OUT_SEW    (sewer, buried)
+;;
+;; A conduit attached to an inlet junction may not also carry an [INLET_USAGE]
+;; row (that would capture the same water twice, engine rule 629), which is
+;; why the conduit-attribute inlet sits on ST_A rather than on ST_B or ST_C.
+;;
+;; Run:  openswmm-cli street_inlet_junction.inp street_inlet_junction.rpt
+;; Then read the Street Flow Summary and the Street Inlet Flow Summary in the
+;; .rpt — README.md says what to look for.
+;;============================================================================
+
+[TITLE]
+Street Inlets and the Inlet Junction
+A conduit-attribute inlet and an inlet junction on one street reach.
+
+
+[OPTIONS]
+FLOW_UNITS           CFS
+INFILTRATION         HORTON
+FLOW_ROUTING         DYNWAVE
+LINK_OFFSETS         DEPTH
+MIN_SLOPE            0
+ALLOW_PONDING        NO
+SKIP_STEADY_STATE    NO
+
+START_DATE           01/01/2026
+START_TIME           00:00:00
+REPORT_START_DATE    01/01/2026
+REPORT_START_TIME    00:00:00
+END_DATE             01/01/2026
+END_TIME             03:00:00
+SWEEP_START          01/01
+SWEEP_END            12/31
+DRY_DAYS             0
+REPORT_STEP          00:01:00
+WET_STEP             00:05:00
+DRY_STEP             01:00:00
+ROUTING_STEP         00:00:05
+
+
+;;----------------------------------------------------------------------------
+;; Nodes
+;;----------------------------------------------------------------------------
+;; Street nodes carry a shallow MaxDepth: the street surface, not a manhole.
+;; IJ1 is NOT listed here — an inlet junction lives in [INLET_JUNCTIONS].
+
+[JUNCTIONS]
+;;Name             Elev         MaxDepth     InitDepth    SurDepth     Aponded
+;;---------------- ------------ ------------ ------------ ------------ ------------
+J_TOP                100.0000       1.5000       0.0000       0.0000       0.0000
+J_MID                 99.0000       1.5000       0.0000       0.0000       0.0000
+MH1                   90.0000       8.0000       0.0000       0.0000       0.0000
+MH2                   89.0000       9.0000       0.0000       0.0000       0.0000
+
+;; Tokens 1-3 are exactly [VIRTUAL_JUNCTIONS] (name, invert, MaxDepth); here
+;; MaxDepth is the flood threshold above the invert, not just a drawing hint.
+;; Tokens 4-11 are exactly the [INLET_USAGE] tail (design, capture node,
+;; #Inlets, %Clog, Qmax, aLocal, wLocal, Placement).
+
+[INLET_JUNCTIONS]
+;;Name             Elev         MaxDepth     Inlet            CaptureNode      #Inlets  %Clog    Qmax       aLocal     wLocal     Placement
+;;---------------- ------------ ------------ ---------------- ---------------- -------- -------- ---------- ---------- ---------- ----------
+IJ1                   98.0000       0.5000 Curb1            MH2                     1       10          0          0          0 ON_GRADE
+
+[OUTFALLS]
+;;Name             Elev         Type         Stage Data       Gated    Route To
+;;---------------- ------------ ------------ ---------------- -------- ----------------
+OUT_ST                97.0000 FREE                          NO
+OUT_SEW               88.0000 FREE                          NO
+
+
+;;----------------------------------------------------------------------------
+;; Links
+;;----------------------------------------------------------------------------
+;; ST_B and ST_C must share one cross-section and have zero offsets: they are
+;; the pair IJ1 sits between.
+
+[CONDUITS]
+;;Name             From             To               Length     N          Z1         Z2         Q0
+;;---------------- ---------------- ---------------- ---------- ---------- ---------- ---------- ----------
+ST_A             J_TOP            J_MID                200.00     0.0160          0          0          0
+ST_B             J_MID            IJ1                  200.00     0.0160          0          0          0
+ST_C             IJ1              OUT_ST               200.00     0.0160          0          0          0
+SW_1             MH1              MH2                  200.00     0.0130          0          0          0
+SW_2             MH2              OUT_SEW              200.00     0.0130          0          0          0
+
+[XSECTIONS]
+;;Link             Shape        Geom1        Geom2      Geom3      Geom4      Barrels
+;;---------------- ------------ ------------ ---------- ---------- ---------- ----------
+ST_A             STREET       ST_MAIN
+ST_B             STREET       ST_MAIN
+ST_C             STREET       ST_MAIN
+SW_1             CIRCULAR           2.0000          0          0          0          1
+SW_2             CIRCULAR           2.0000          0          0          0          1
+
+
+;;----------------------------------------------------------------------------
+;; Street cross-section
+;;----------------------------------------------------------------------------
+;; Tcrown  half-width of the crowned roadway (ft)
+;; Hcurb   curb height (ft)          Sx  cross slope (%)
+;; nRoad   pavement Manning's n      a   gutter depression (in)
+;; W       depressed gutter width (ft)   Sides  1 = curb on one side only
+;; Tback / Sback / nBack  the backing (parkway) strip behind the curb
+
+[STREETS]
+;;Name             Tcrown     Hcurb      Sx         nRoad      a          W          Sides    Tback      Sback      nBack
+;;---------------- ---------- ---------- ---------- ---------- ---------- ---------- -------- ---------- ---------- ----------
+ST_MAIN               20.0000     0.5000     4.0000     0.0160     2.0000     2.0000        1    10.0000     4.0000     0.0160
+
+
+;;----------------------------------------------------------------------------
+;; Inlet designs
+;;----------------------------------------------------------------------------
+;; GRATE       Name GRATE      Length Width  GrateType [OpenArea SplashVeloc]
+;; CURB        Name CURB       Length Height [ThroatType]
+;; COMBO       (no keyword) a GRATE line and a CURB line under ONE name
+;; SLOTTED     Name SLOTTED    Length Width
+;; DROP_GRATE  Name DROP_GRATE Length Width  GrateType   (drainage channels)
+;; DROP_CURB   Name DROP_CURB  Length Height             (drainage channels)
+;; CUSTOM      Name CUSTOM     CurveID   (a DIVERSION or RATING curve)
+
+[INLETS]
+;;Name             Type         Param1     Param2     Param3
+;;---------------- ------------ ---------- ---------- ----------
+Grate1           GRATE            2.0000     2.0000 P_BAR-50
+Curb1            CURB             3.0000     0.5000 HORIZONTAL
+;; Combo1: the legacy two-line combination inlet — a grate in the gutter plus
+;; a curb opening beside it. The reader merges the pair into one COMBO design
+;; and the writer emits it back as these same two lines.
+Combo1           GRATE            2.0000     2.0000 CURVED_VANE
+Combo1           CURB             3.0000     0.5000 VERTICAL
+Custom1          CUSTOM       DIV_CAP
+
+
+;;----------------------------------------------------------------------------
+;; Inlet placement — the conduit-attribute form
+;;----------------------------------------------------------------------------
+;; Captured flow leaves ST_A at its downstream node and arrives at MH1; the
+;; bypass stays on the street. Qmax = 0 means the inlet is not flow-limited;
+;; aLocal / wLocal = 0 means no local depression beyond the street's own
+;; gutter. %Clog 10 keeps 90 % of the theoretical capacity.
+
+[INLET_USAGE]
+;;Link             Inlet            Node             #Inlets  %Clog    Qmax       aLocal     wLocal     Placement
+;;---------------- ---------------- ---------------- -------- -------- ---------- ---------- ---------- ----------
+ST_A             Combo1           MH1                     2       10          0          0          0 ON_GRADE
+
+
+;;----------------------------------------------------------------------------
+;; Capture curve for the CUSTOM design (captured flow vs. approach flow)
+;;----------------------------------------------------------------------------
+;; The [INLETS] CUSTOM line carries no curve-kind token: the curve's own type
+;; is the kind. DIVERSION = captured flow as a function of approach flow;
+;; RATING = captured flow as a function of ponded depth (sag inlets).
+
+[CURVES]
+;;Name             Type         X-Value    Y-Value
+;;---------------- ------------ ---------- ----------
+DIV_CAP          DIVERSION            0.0        0.0
+DIV_CAP                               1.0        0.9
+DIV_CAP                               3.0        2.1
+DIV_CAP                               6.0        3.0
+DIV_CAP                              12.0        3.6
+
+
+;;----------------------------------------------------------------------------
+;; Forcing — a two-hour gutter hydrograph entering the top of the street
+;;----------------------------------------------------------------------------
+
+[INFLOWS]
+;;Node             Constituent      Time Series      Type     Mfactor  Sfactor  Baseline Pattern
+;;---------------- ---------------- ---------------- -------- -------- -------- -------- --------
+J_TOP            FLOW             GUTTER_TS        FLOW     1.0      1.0
+
+[TIMESERIES]
+;;Name             Date         Time         Value
+;;---------------- ------------ ------------ ----------
+GUTTER_TS                     0:00          0.0
+GUTTER_TS                     0:15          2.0
+GUTTER_TS                     0:30          8.0
+GUTTER_TS                     0:45         12.0
+GUTTER_TS                     1:00          8.0
+GUTTER_TS                     1:30          3.0
+GUTTER_TS                     2:00          0.0
+GUTTER_TS                     3:00          0.0
+
+
+[REPORT]
+INPUT                NO
+CONTROLS             NO
+SUBCATCHMENTS        ALL
+NODES                ALL
+LINKS                ALL
+
+
+[COORDINATES]
+;;Node             X-Coord            Y-Coord
+;;---------------- ------------------ ------------------
+J_TOP                          0.000              0.000
+J_MID                        200.000              0.000
+IJ1                          400.000              0.000
+OUT_ST                       600.000              0.000
+MH1                          200.000           -100.000
+MH2                          400.000           -100.000
+OUT_SEW                      600.000           -100.000
diff --git a/include/openswmm/engine/openswmm_2d.h b/include/openswmm/engine/openswmm_2d.h
index f74955e71..4ce86dbc1 100644
--- a/include/openswmm/engine/openswmm_2d.h
+++ b/include/openswmm/engine/openswmm_2d.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_2d.h
  * @brief Optional 2D surface routing module — C API.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_2D_H
@@ -111,13 +127,87 @@ SWMM_ENGINE_API int swmm_2d_vertex_get_xyz_bulk(SWMM_Engine engine,
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_set_vertex_z(SWMM_Engine engine, int idx, double z);
 
+/** @brief Set EVERY vertex Z in one call.
+ *
+ *  Equivalent to calling ::swmm_2d_set_vertex_z for each vertex in turn — the
+ *  dependent geometry (`tri_cz`, `edge_mz`) ends up bitwise identical — but the
+ *  scalar setter rescans all triangles on every call, so doing that per vertex
+ *  is O(nVertices x nTriangles). This writes all Zs first and recomputes the
+ *  dependent geometry in a single pass, i.e. O(nVertices + nTriangles). On a
+ *  million-cell mesh that is the difference between minutes and milliseconds,
+ *  which is why editors that rewrite a whole mesh should prefer it.
+ *
+ *  XY-derived fields (`tri_area`, `tri_cx`, `tri_cy`, `edge_length`,
+ *  `edge_nx`, `edge_ny`, `edge_mx`, `edge_my`) are unaffected.
+ *
+ *  When called while the engine is RUNNING, the solver state (`head`,
+ *  `depth`) is intentionally **not** rewritten — `head` remains the value
+ *  the solver is integrating; the implied `depth = head - bed` therefore changes
+ *  by the same amount as bed. This is the expected physical semantics
+ *  ("raising the bed under water reduces water depth there").
+ *
+ *  @param z     Array of `count` new ground elevations (project vertical
+ *               units), indexed by vertex.
+ *  @param count Must equal ::swmm_2d_vertex_count, else SWMM_ERR_BADPARAM.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_set_vertex_z_bulk(SWMM_Engine engine,
+                                                const double* z, int count);
+
 /** @brief Get triangle connectivity (3 vertex indices).
- *  @param idx Triangle index (0-based).
+ *  @param idx Cell index (0-based). Returns SWMM_ERR_BADPARAM when the cell
+ *             is a quadrilateral — use ::swmm_2d_cell_get_vertices.
  *  @param v0,v1,v2 Output vertex indices.
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_triangle_get_vertices(SWMM_Engine engine, int idx,
                                                     int* v0, int* v1, int* v2);
 
+/* -------------------------------------------------------------------------
+ * Mixed triangle / quadrilateral meshes (2D_TRI_QUAD_MESH_PLAN_2026-09-06).
+ *
+ * A "triangle index" everywhere in this header is a CELL index: cells are
+ * numbered triangles first (the [2D_TRIANGLES] rows), then quads (the
+ * [2D_QUADS] rows). Every swmm_2d_triangle_* accessor that reads a per-cell
+ * scalar (area, centroid, Manning, init depth/velocity, tag, coupling) works
+ * on a quad too; only the two 3-slot connectivity getters refuse quads.
+ * Local edge k of a cell has endpoints v[(k+1)%nv], v[(k+2)%nv].
+ * ------------------------------------------------------------------------- */
+
+/** @brief Number of cells (triangles + quads) — same value as
+ *  ::swmm_2d_triangle_count.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_cell_count(SWMM_Engine engine, int* count);
+
+/** @brief Number of quadrilateral cells (0 for an all-triangle mesh).
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_quad_count(SWMM_Engine engine, int* count);
+
+/** @brief Edge-slot stride of the bulk edge arrays
+ *  (::swmm_2d_get_edge_flux_bulk, ::swmm_2d_edge_get_geometry_bulk,
+ *  ::swmm_2d_get_edge_conveyance_bulk): 3 for an all-triangle mesh (the
+ *  historical `[tri*3 + localEdge]` layout, byte-compatible), 4 once the mesh
+ *  holds any quad (`[cell*4 + localEdge]`, padding slots of a triangle row
+ *  are 0). Size every bulk buffer as `triangle_count * stride`.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_edge_stride(SWMM_Engine engine, int* stride);
+
+/** @brief Vertices (== edges) of a cell: 3 or 4.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_cell_vertex_count(SWMM_Engine engine, int idx, int* nv);
+
+/** @brief Cell connectivity for any shape.
+ *  @param v  Caller-provided int[4]; slots beyond @p nv are −1.
+ *  @param nv Output vertex count (3 or 4).
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_cell_get_vertices(SWMM_Engine engine, int idx,
+                                              int* v, int* nv);
+
+/** @brief Neighbour cell across each local edge, any shape.
+ *  @param n  Caller-provided int[4]; −1 = boundary edge, −2 = padding slot.
+ *  @param nv Output edge count (3 or 4).
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_cell_get_neighbours(SWMM_Engine engine, int idx,
+                                                int* n, int* nv);
+
 /** @brief Get triangle area.
  *  @param idx Triangle index.
  *  @param area Output area (m² or ft²).
@@ -341,19 +431,26 @@ SWMM_ENGINE_API int swmm_2d_set_vertex_coupling_cd(SWMM_Engine engine,
                                                      double cd);
 
 /** @brief Get the coupling exchange area of a vertex
- *         (`[2D_VERTEX_NODE_MAP]` AREA column, m²; default 1.0).
+ *         (`[2D_VERTEX_NODE_MAP]` AREA column; default 1.0).
+ *
+ *  Units follow the MESH: mesh length units squared as authored (ft² for a
+ *  US-FLOW_UNITS project unless the mesh file declares `;; UNITS: SI (m)`),
+ *  converted to m² in place by swmm_engine_initialize() together with the
+ *  vertex coordinates. Before initialize the value is therefore in mesh
+ *  (project) units; after it, m².
  *  @param vertex_idx Vertex index in `[0, vertex_count)`.
- *  @param area Output exchange area (m²).
+ *  @param area Output exchange area (mesh length units²).
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_get_vertex_coupling_area(SWMM_Engine engine,
                                                        int vertex_idx,
                                                        double* area);
 
 /** @brief Set the coupling exchange area of a vertex
- *         (`[2D_VERTEX_NODE_MAP]` AREA column, m²). Persisted by the `.inp`
- *         writer.
+ *         (`[2D_VERTEX_NODE_MAP]` AREA column). Persisted by the `.inp`
+ *         writer. Same units convention as the getter: mesh length units²
+ *         (project units before initialize, m² after).
  *  @param vertex_idx Vertex index in `[0, vertex_count)`.
- *  @param area Exchange area in m²; must be > 0.
+ *  @param area Exchange area in mesh length units²; must be > 0.
  *  @return SWMM_OK on success; SWMM_ERR_BADPARAM on non-positive area.
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_set_vertex_coupling_area(SWMM_Engine engine,
@@ -384,6 +481,25 @@ SWMM_ENGINE_API int swmm_2d_get_coupling_flux(SWMM_Engine engine, int idx,
 SWMM_ENGINE_API int swmm_2d_get_rainfall(SWMM_Engine engine, int idx,
                                            double* rainfall);
 
+/** @brief Inspect how RAINFALL_MODE maps the gages onto one triangle.
+ *
+ *  Diagnoses a cell that receives no rain: a zero from a dry contributing
+ *  gage is a valid reading, not a missing weight.
+ *
+ *  @param method       Receives 0 natural neighbour, 1 inverse-distance
+ *                      fallback, 2 single nearest gage, or -1 when no per-cell
+ *                      weights apply (SYSTEM / NONE, or no located gage).
+ *  @param gage_indices Receives up to @p capacity contributing gage indices
+ *                      (may be NULL when @p capacity is 0).
+ *  @param weights      Receives the matching normalized weights (sum to 1).
+ *  @param count        Receives the total number of contributing gages, which
+ *                      may exceed @p capacity.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_rainfall_weights(SWMM_Engine engine, int idx,
+                                                   int* method, int* gage_indices,
+                                                   double* weights, int capacity,
+                                                   int* count);
+
 /** @brief Get net source/sink rate at a triangle (m/s).
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_get_net_source(SWMM_Engine engine, int idx,
@@ -403,6 +519,42 @@ SWMM_ENGINE_API int swmm_2d_get_heads_bulk(SWMM_Engine engine, double* heads);
 SWMM_ENGINE_API int swmm_2d_get_coupling_fluxes_bulk(SWMM_Engine engine,
                                                        double* fluxes);
 
+/** @brief Bulk get the rainfall intensity (m/s) applied to every triangle
+ *  this step — the same field the HDF5 `Mesh2_face_rainfall` dataset
+ *  carries. Output pre-allocated to `triangle_count`.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_rainfall_bulk(SWMM_Engine engine,
+                                               double* rainfall);
+
+/** @brief Bulk get the cumulative rainfall VOLUME (m³) booked onto every
+ *  triangle since the start of the run — the `Mesh2_face_rain_cum` field;
+ *  sums over cells to the 2D mass balance's rainfall inflow. Output
+ *  pre-allocated to `triangle_count`.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_rain_volume_bulk(SWMM_Engine engine,
+                                                  double* volumes);
+
+/** @brief Bulk get the SIGNED cumulative 1D↔2D coupling exchange VOLUME (m³)
+ *  per triangle since the start of the run.
+ *
+ *  Sign is from the 2D cell's point of view: **positive = the 1D node
+ *  delivered water INTO this cell** (spill, submerged-outfall discharge);
+ *  **negative = the node abstracted water FROM it** (drain). Output
+ *  pre-allocated to `triangle_count`.
+ *
+ *  Summing the array gives `coupling_1d_to_2d_in − coupling_2d_to_1d_out`
+ *  from the 2D mass balance — the identity that ties this per-cell series to
+ *  the domain totals, and the natural check for a validator.
+ *
+ *  Why signed and per cell: the two domain accumulators are unsigned and
+ *  cannot answer "what did THIS cell give or take", which is exactly the
+ *  question at a coupling point that reverses within a batch — the two
+ *  directions cancel in the net and neither is visible in the totals.
+ *  `swmm_2d_get_coupling_flux` is a rate that is overwritten every step.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_coupling_volume_bulk(SWMM_Engine engine,
+                                                     double* volumes);
+
 /** @brief Bulk get normal edge flux at every edge of every triangle.
  *
  *  Output array must be pre-allocated to `triangle_count * 3` doubles,
@@ -529,6 +681,32 @@ SWMM_ENGINE_API int swmm_2d_get_solver_steps(SWMM_Engine engine, long* steps);
 SWMM_ENGINE_API int swmm_2d_get_solver_last_step(SWMM_Engine engine,
                                                    double* h_last);
 
+/** @brief Cumulative explicit-marcher run statistics plus the backend and
+ *  closure this run is on — the numbers the .rpt "2D Solver Statistics"
+ *  block prints, readable DURING the run (after swmm_engine_start).
+ *  @ingroup engine_2d */
+typedef struct SWMM_2DRunStats {
+    char   backend[64];        /**< Solver label chosen at initialize, e.g.
+                                    "cpu (explicit marcher)", "omp (Kokkos OpenMP …)". */
+    int    momentum;           /**< 0 LOCAL_INERTIAL, 1 FULL_SWE, 2 DIFFUSIVE_WAVE. */
+    int    lts_tiers;          /**< Configured [2D_OPTIONS] LTS_TIERS. */
+    long   steps;              /**< Cumulative internal (marcher) substeps. */
+    long   face_evals;         /**< Cumulative face-kernel evaluations. */
+    double last_step;          /**< Last accepted internal step (s). */
+    double active_frac_min;    /**< Active-cell fraction over rebuild samples; -1 = not populated. */
+    double active_frac_mean;
+    double active_frac_max;
+    int    n_tiers;            /**< Populated entries of tier_cells (0 = no LTS telemetry). */
+    long   tier_cells[8];      /**< Cumulative rebuild-sampled cells per LTS tier. */
+} SWMM_2DRunStats;
+
+/** @brief Read the cumulative marcher statistics and backend of the 2D run.
+ *  Counters are zero (and n_tiers 0) before the first advance and again once
+ *  the solver has been finalised at swmm_engine_end; backend stays filled.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_run_stats(SWMM_Engine engine,
+                                          SWMM_2DRunStats* stats);
+
 /** @brief Get per-triangle max depth statistics (cumulative).
  *  @param max_depths Output array (pre-allocated to triangle_count).
  *  @ingroup engine_2d */
@@ -676,12 +854,17 @@ SWMM_ENGINE_API int swmm_2d_set_edge_bc_type(SWMM_Engine engine,
                                                int bc_type);
 
 /** @brief Get specified stage boundary head for an edge.
+ *
+ *  Units follow the mesh vertical datum: mesh length units as authored
+ *  (feet for a US project without an SI mesh header) before
+ *  swmm_engine_initialize(), metres after it.
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_get_edge_bc_head(SWMM_Engine engine,
                                                int tri_idx, int edge,
                                                double* head);
 
-/** @brief Set specified stage boundary head for an edge.
+/** @brief Set specified stage boundary head for an edge (same units
+ *         convention as the getter).
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_set_edge_bc_head(SWMM_Engine engine,
                                                int tri_idx, int edge,
@@ -711,14 +894,31 @@ SWMM_ENGINE_API int swmm_2d_set_edge_bc_tseries_name(SWMM_Engine engine,
                                                        int edge,
                                                        const char* name);
 
-/** @brief Get prescribed flow per metre of edge (m³/s/m) for a
- *         SPECIFIED_FLOW edge. V-E4.
+/** @brief Get the timeseries NAME driving a SPECIFIED_STAGE edge.
+ *
+ *  SVBC A8 — the setter's mirror, so a caller can verify what the engine
+ *  holds after an edit push. Works in the OPENED state (mesh guard, like
+ *  the setter). Truncating copy into \p buf, always NUL-terminated.
+ *  @ingroup engine_2d */
+SWMM_ENGINE_API int swmm_2d_get_edge_bc_tseries_name(SWMM_Engine engine,
+                                                       int tri_idx,
+                                                       int edge,
+                                                       char* buf, int buflen);
+
+/** @brief Get prescribed flow per metre of edge for a SPECIFIED_FLOW edge.
+ *         V-E4.
+ *
+ *  Units: project display flow units per metre (the `[2D_BOUNDARY_CONDITIONS]`
+ *  file contract, e.g. CFS/m) before swmm_engine_initialize(); m³/s/m after
+ *  it (initialize scales the constants in place; the writers scale back).
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_get_edge_bc_flow(SWMM_Engine engine,
                                                int tri_idx, int edge,
                                                double* flow);
 
-/** @brief Set prescribed flow per metre of edge (m³/s/m). V-E4. */
+/** @brief Set prescribed flow per metre of edge (same units convention as
+ *         the getter: display flow units/m before initialize, m³/s/m after).
+ *         V-E4. */
 SWMM_ENGINE_API int swmm_2d_set_edge_bc_flow(SWMM_Engine engine,
                                                int tri_idx, int edge,
                                                double flow);
@@ -730,6 +930,14 @@ SWMM_ENGINE_API int swmm_2d_set_edge_bc_flow_tseries_name(SWMM_Engine engine,
                                                             int edge,
                                                             const char* name);
 
+/** @brief Get the timeseries NAME driving a SPECIFIED_FLOW edge.
+ *  SVBC A8 — same contract as `swmm_2d_get_edge_bc_tseries_name`. */
+SWMM_ENGINE_API int swmm_2d_get_edge_bc_flow_tseries_name(SWMM_Engine engine,
+                                                            int tri_idx,
+                                                            int edge,
+                                                            char* buf,
+                                                            int buflen);
+
 /** @brief Set the curve NAME to drive a RATING_CURVE edge.
  *
  *  V-E5. Stage → flow lookup is resolved against the existing
@@ -740,12 +948,40 @@ SWMM_ENGINE_API int swmm_2d_set_edge_bc_rating_curve_name(SWMM_Engine engine,
                                                             int edge,
                                                             const char* name);
 
+/** @brief Get the curve NAME driving a RATING_CURVE edge.
+ *  SVBC A8 — same contract as `swmm_2d_get_edge_bc_tseries_name`. */
+SWMM_ENGINE_API int swmm_2d_get_edge_bc_rating_curve_name(SWMM_Engine engine,
+                                                            int tri_idx,
+                                                            int edge,
+                                                            char* buf,
+                                                            int buflen);
+
 /** @brief Get cumulative boundary flux at an edge (m³, + = outflow).
  *  @ingroup engine_2d */
 SWMM_ENGINE_API int swmm_2d_get_edge_bc_cum_flux(SWMM_Engine engine,
                                                     int tri_idx, int edge,
                                                     double* cum_flux);
 
+
+/* =========================================================================
+ * Results-file variable selection ([2D_OPTIONS] REPORT_2D_VARIABLES)
+ * =========================================================================
+ * Engine-independent helpers so a host can build a checklist without
+ * re-implementing the token vocabulary. Tokens are listed in bit order; the
+ * presets DEFAULT / MINIMAL / ALL map to masks. Use swmm_options_get_ext /
+ * swmm_options_set_ext with key "REPORT_2D_VARIABLES" to read/write a model.
+ */
+
+/** Number of selectable dataset groups. */
+SWMM_ENGINE_API int swmm_2d_output_variable_count(void);
+/** Token of group @p i (0-based, bit i), or "" when out of range. */
+SWMM_ENGINE_API const char* swmm_2d_output_variable_name(int i);
+/** Bitmask for a preset name ("DEFAULT", "MINIMAL", "ALL") or a token list;
+ *  returns 0 for an unparseable string. */
+SWMM_ENGINE_API unsigned swmm_2d_output_variable_mask(const char* text);
+/** Preset name or token list for @p mask (static buffer, valid until the next call). */
+SWMM_ENGINE_API const char* swmm_2d_output_variable_text(unsigned mask);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/include/openswmm/engine/openswmm_callbacks.h b/include/openswmm/engine/openswmm_callbacks.h
index 2499b44a4..b8989b73b 100644
--- a/include/openswmm/engine/openswmm_callbacks.h
+++ b/include/openswmm/engine/openswmm_callbacks.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_callbacks.h
  * @brief Callback function typedefs for the OpenSWMM Engine C API.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_CALLBACKS_H
diff --git a/include/openswmm/engine/openswmm_climate.h b/include/openswmm/engine/openswmm_climate.h
index 7a77464a2..619212e19 100644
--- a/include/openswmm/engine/openswmm_climate.h
+++ b/include/openswmm/engine/openswmm_climate.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_climate.h
  * @brief OpenSWMM Engine — Climatology configuration C API.
@@ -35,7 +51,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CLIMATE_H
@@ -81,6 +97,24 @@ typedef enum SWMM_WindType {
     SWMM_WIND_FILE    = 1  /**< Wind speed from the climate file.   */
 } SWMM_WindType;
 
+/**
+ * @brief Humidity data source (matches [TEMPERATURE] HUMIDITY).
+ */
+typedef enum SWMM_HumidityType {
+    SWMM_HUMIDITY_CONSTANT   = 0, /**< Single constant value.              */
+    SWMM_HUMIDITY_MONTHLY    = 1, /**< Twelve monthly values.              */
+    SWMM_HUMIDITY_TIMESERIES = 2  /**< Value from an in-model time series. */
+} SWMM_HumidityType;
+
+/**
+ * @brief Quantity the HUMIDITY values express.
+ */
+typedef enum SWMM_HumidityVar {
+    SWMM_HUMIDITY_RELATIVE = 0, /**< Relative humidity, %.                              */
+    SWMM_HUMIDITY_DEWPOINT = 1  /**< Dew-point temperature (deg F US / deg C SI);
+                                     converted to RH each step from air temperature. */
+} SWMM_HumidityVar;
+
 /* =========================================================================
  * Temperature  ([TEMPERATURE])
  * ========================================================================= */
@@ -174,6 +208,34 @@ SWMM_ENGINE_API int swmm_climate_get_wind_monthly(SWMM_Engine engine, double* bu
 /** @brief Set the 12 monthly average wind speeds; @p count must equal SWMM_CLIMATE_MONTHS. */
 SWMM_ENGINE_API int swmm_climate_set_wind_monthly(SWMM_Engine engine, const double* values, int count);
 
+/* =========================================================================
+ * Humidity  ([TEMPERATURE] HUMIDITY) — heat-model met input
+ * ========================================================================= */
+
+/** @brief Get the humidity data source (see @ref SWMM_HumidityType). */
+SWMM_ENGINE_API int swmm_climate_get_humidity_type(SWMM_Engine engine, int* type);
+/** @brief Set the humidity data source (0..2, see @ref SWMM_HumidityType).
+ *  @returns SWMM_ERR_BADPARAM if out of range. */
+SWMM_ENGINE_API int swmm_climate_set_humidity_type(SWMM_Engine engine, int type);
+
+/** @brief Get the humidity quantity (see @ref SWMM_HumidityVar). */
+SWMM_ENGINE_API int swmm_climate_get_humidity_variable(SWMM_Engine engine, int* var);
+/** @brief Set the humidity quantity (0..1, see @ref SWMM_HumidityVar).
+ *  @returns SWMM_ERR_BADPARAM if out of range. */
+SWMM_ENGINE_API int swmm_climate_set_humidity_variable(SWMM_Engine engine, int var);
+
+/** @brief Get the 12 monthly humidity values (RH % or dew point, per the variable).
+ *  With the CONSTANT source all twelve hold the constant.
+ *  @param count Must equal SWMM_CLIMATE_MONTHS. */
+SWMM_ENGINE_API int swmm_climate_get_humidity_monthly(SWMM_Engine engine, double* buf, int count);
+/** @brief Set the 12 monthly humidity values; @p count must equal SWMM_CLIMATE_MONTHS. */
+SWMM_ENGINE_API int swmm_climate_set_humidity_monthly(SWMM_Engine engine, const double* values, int count);
+
+/** @brief Get the humidity time-series id (empty if none). */
+SWMM_ENGINE_API int swmm_climate_get_humidity_timeseries(SWMM_Engine engine, char* buf, int buflen);
+/** @brief Assign the humidity time-series id and set the source to TIMESERIES. */
+SWMM_ENGINE_API int swmm_climate_set_humidity_timeseries(SWMM_Engine engine, const char* ts_id);
+
 /* =========================================================================
  * Snowmelt globals  ([TEMPERATURE] SNOWMELT)
  * ========================================================================= */
diff --git a/include/openswmm/engine/openswmm_controls.h b/include/openswmm/engine/openswmm_controls.h
index fc3d32584..1cbfba0b8 100644
--- a/include/openswmm/engine/openswmm_controls.h
+++ b/include/openswmm/engine/openswmm_controls.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_controls.h
  * @brief OpenSWMM Engine — Control Rules C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CONTROLS_H
diff --git a/include/openswmm/engine/openswmm_datetime.h b/include/openswmm/engine/openswmm_datetime.h
index a8b5fec5d..988c3bbae 100644
--- a/include/openswmm/engine/openswmm_datetime.h
+++ b/include/openswmm/engine/openswmm_datetime.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_datetime.h
  * @brief OpenSWMM Engine — SWMM DateTime conversion utilities (C API).
@@ -46,7 +62,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DATETIME_H
diff --git a/include/openswmm/engine/openswmm_edit.h b/include/openswmm/engine/openswmm_edit.h
index 46628c1e3..d31271ed0 100644
--- a/include/openswmm/engine/openswmm_edit.h
+++ b/include/openswmm/engine/openswmm_edit.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_edit.h
  * @brief OpenSWMM Engine — Model editing C API (deletion and type conversion).
@@ -26,7 +42,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_EDIT_H
@@ -235,6 +251,53 @@ SWMM_ENGINE_API int swmm_subcatch_delete(
 SWMM_ENGINE_API int swmm_gage_delete(
     SWMM_Engine engine, int idx, SWMM_ImpactReport* cascade_out);
 
+/**
+ * @brief Delete many nodes in one call — equivalent to sequential
+ *        @ref swmm_node_delete calls in DESCENDING index order, with ONE
+ *        name-index rebuild for the whole batch.
+ *
+ * @details The per-object path rebuilds the entire name→index hash after
+ *          EVERY delete, which dominates bulk deletions on large models
+ *          (K deletes = K full rehashes over every remaining name).  The
+ *          batch runs the identical per-object cascade logic — semantics,
+ *          cascade behaviour and final state match the sequential
+ *          descending equivalent exactly — but rehashes once.
+ *
+ *          `indices` are pre-batch indices; duplicates are tolerated
+ *          (deduplicated internally).  Every index is validated BEFORE any
+ *          mutation: an out-of-range entry fails the whole call with
+ *          SWMM_ERR_BADINDEX and no changes.  Cascade entries in
+ *          `cascade_out` carry the indices the sequential-descending
+ *          equivalent would report.
+ *
+ * @param engine       Engine handle.
+ * @param indices      Array of `n` zero-based node indices (pre-batch).
+ * @param n            Number of entries in `indices`; 0 is a no-op.
+ * @param cascade_out  If non-NULL, receives the aggregate cascade report.
+ *                     Caller must free with @ref swmm_impact_report_free.
+ * @returns SWMM_OK, SWMM_ERR_LIFECYCLE if not BUILDING/OPENED,
+ *          SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM if `indices` is NULL with
+ *          n > 0, or SWMM_ERR_BADINDEX.
+ */
+SWMM_ENGINE_API int swmm_node_delete_many(
+    SWMM_Engine engine, const int* indices, int n,
+    SWMM_ImpactReport* cascade_out);
+
+/** @copydoc swmm_node_delete_many */
+SWMM_ENGINE_API int swmm_link_delete_many(
+    SWMM_Engine engine, const int* indices, int n,
+    SWMM_ImpactReport* cascade_out);
+
+/** @copydoc swmm_node_delete_many */
+SWMM_ENGINE_API int swmm_subcatch_delete_many(
+    SWMM_Engine engine, const int* indices, int n,
+    SWMM_ImpactReport* cascade_out);
+
+/** @copydoc swmm_node_delete_many */
+SWMM_ENGINE_API int swmm_gage_delete_many(
+    SWMM_Engine engine, const int* indices, int n,
+    SWMM_ImpactReport* cascade_out);
+
 /**
  * @brief Delete a time series or curve and nullify all referencing objects.
  *
@@ -462,6 +525,36 @@ SWMM_ENGINE_API int swmm_conduit_split(
 SWMM_ENGINE_API int swmm_virtual_junction_fuse(
     SWMM_Engine engine, int node_idx, int* surviving_link_idx);
 
+/**
+ * @brief Split a STREET conduit at `t` and make the inserted node an inlet
+ *        junction with the given design and capture node (2026-09-05).
+ *
+ * @details Equivalent to swmm_conduit_split(make_virtual=1) followed by
+ *          swmm_node_set_inlet(1) and swmm_inlet_usage_set(host=node), but
+ *          atomic: on any failure after the split the split is undone
+ *          (fused back) and the error returned. The usage row is created
+ *          with num_inlets=1, 0 % clogged, no flow limit, no local
+ *          depression, AUTOMATIC placement; adjust with swmm_inlet_usage_set.
+ *
+ * @param inlet_id      Existing inlet design name.
+ * @param capture_node  Existing node name (not virtual, not the new node).
+ * @returns SWMM_OK; generic codes; ERR_VJ_ / ERR_IJ_ rule codes; 625 for an
+ *          unknown design; 627 for a bad capture node.
+ */
+SWMM_ENGINE_API int swmm_conduit_split_inlet(
+    SWMM_Engine engine, int link_idx, double t,
+    const char* new_node_name, const char* new_link_name,
+    const char* inlet_id, const char* capture_node,
+    int* new_node_idx, int* new_link_idx);
+
+/**
+ * @brief Inverse of swmm_conduit_split_inlet: removes the inlet junction's
+ *        usage row, then re-fuses the conduit pair exactly as
+ *        swmm_virtual_junction_fuse does.
+ */
+SWMM_ENGINE_API int swmm_inlet_junction_fuse(
+    SWMM_Engine engine, int node_idx, int* surviving_link_idx);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/include/openswmm/engine/openswmm_engine.h b/include/openswmm/engine/openswmm_engine.h
index 814328538..cf36e71de 100644
--- a/include/openswmm/engine/openswmm_engine.h
+++ b/include/openswmm/engine/openswmm_engine.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_engine.h
  * @brief OpenSWMM Engine — primary transparent C API (master header).
@@ -63,7 +79,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_H
@@ -304,6 +320,90 @@ SWMM_ENGINE_API const char* swmm_get_error_at      (SWMM_Engine engine, int inde
 SWMM_ENGINE_API int         swmm_get_warning_count (SWMM_Engine engine);
 SWMM_ENGINE_API const char* swmm_get_warning_at    (SWMM_Engine engine, int index);
 
+/* =========================================================================
+ * Thread capability query (engine-independent)
+ * ========================================================================= */
+
+/**
+ * Hardware / OpenMP thread limits as seen by the engine process. Lets a host
+ * show the user what [OPTIONS] THREADS can usefully be set to and why the
+ * effective count may differ from the request.
+ */
+typedef struct {
+    int logical_cpus;       /**< Logical processors (SMT included); 0 if unknown.   */
+    int omp_max_threads;    /**< omp_get_max_threads() in this process. Lower than
+                                 logical_cpus when OMP_NUM_THREADS / OMP_THREAD_LIMIT
+                                 / CPU affinity limit the process. 1 without OpenMP. */
+    int omp_available;      /**< 1 if the engine was built with OpenMP.             */
+    int perf_cores;         /**< macOS: logical CPUs on the performance cluster;
+                                 0 elsewhere / unknown.                              */
+    int kokkos_omp_threads; /**< Threads the Kokkos OpenMP 2D backend initialised
+                                 with in this process; 0 = not initialised.         */
+} SWMM_ThreadInfo;
+
+/** Fill @p out. Returns SWMM_OK, or SWMM_ERR_BADPARAM when @p out is NULL. */
+SWMM_ENGINE_API int swmm_get_thread_info(SWMM_ThreadInfo* out);
+
+/**
+ * Resolve the thread counts the engine WOULD use for @p threads_option
+ * ([OPTIONS] THREADS; 0 = auto) with the engine's current model, applying
+ * the same rules as swmm_engine_start: explicit values are honoured; auto
+ * applies omp_get_max_threads(), the model-size gates and (macOS) the
+ * performance-core clamp. Any of the out-pointers may be NULL. Returns
+ * SWMM_OK, or SWMM_ERR_BADPARAM when @p engine is NULL.
+ *
+ * @param global_threads  Team size for runoff / quality / general loops.
+ * @param dw_threads      Dynamic-wave Picard team (0 when routing is not DYNWAVE
+ *                        or the model is not open).
+ * @param twod_threads    2D CPU marcher team (0 when the model has no 2D mesh).
+ */
+SWMM_ENGINE_API int swmm_get_effective_threads(SWMM_Engine engine, int threads_option,
+                                               int* global_threads, int* dw_threads,
+                                               int* twod_threads);
+
+/* =========================================================================
+ * Transport matrix (E2, 2026-09-07) — which species classes run in which
+ * domain, and why not. Engine-computed from the open model's options
+ * (IGNORE_QUALITY, WATER_AGE, HEAT_TRANSPORT, the reactions component,
+ * IGNORE_2D and the [2D_OPTIONS] TRANSPORT_* keys); the .rpt prints the
+ * same table. Valid after swmm_engine_open; re-read after option edits.
+ * ========================================================================= */
+
+#define SWMM_TRANSPORT_DOMAIN_RUNOFF       0
+#define SWMM_TRANSPORT_DOMAIN_GROUNDWATER  1
+#define SWMM_TRANSPORT_DOMAIN_NETWORK_1D   2
+#define SWMM_TRANSPORT_DOMAIN_SURFACE_2D   3
+#define SWMM_TRANSPORT_DOMAIN_COUNT        4
+
+#define SWMM_TRANSPORT_CLASS_POLLUTANTS    0
+#define SWMM_TRANSPORT_CLASS_MSX           1
+#define SWMM_TRANSPORT_CLASS_AGE           2
+#define SWMM_TRANSPORT_CLASS_TEMPERATURE   3
+#define SWMM_TRANSPORT_CLASS_COUNT         4
+
+#define SWMM_TRANSPORT_ENABLED             0
+#define SWMM_TRANSPORT_DISABLED_BY_USER    1   /**< reason = the option key */
+#define SWMM_TRANSPORT_UNAVAILABLE         2   /**< reason = why nothing is carried */
+
+typedef struct SWMM_TransportCell {
+    int  state;        /**< SWMM_TRANSPORT_ENABLED / _DISABLED_BY_USER / _UNAVAILABLE */
+    int  count;        /**< rows of this class carried in the domain (0 unless ENABLED) */
+    char reason[96];   /**< key or explanation; "" when ENABLED */
+} SWMM_TransportCell;
+
+typedef struct SWMM_TransportMatrix {
+    SWMM_TransportCell cell[SWMM_TRANSPORT_DOMAIN_COUNT][SWMM_TRANSPORT_CLASS_COUNT];
+} SWMM_TransportMatrix;
+
+/** Fill @p out for the open model (an unopened engine reports every cell
+ *  UNAVAILABLE). Returns SWMM_OK, or SWMM_ERR_BADPARAM when @p engine or
+ *  @p out is NULL. */
+SWMM_ENGINE_API int swmm_get_transport_matrix(SWMM_Engine engine, SWMM_TransportMatrix* out);
+
+/** Display names for the matrix axes ("" when out of range). */
+SWMM_ENGINE_API const char* swmm_transport_domain_name(int domain);
+SWMM_ENGINE_API const char* swmm_transport_class_name(int species_class);
+
 /* =========================================================================
  * Simulation timing
  * ========================================================================= */
@@ -482,6 +582,9 @@ SWMM_ENGINE_API int swmm_runoff_iface_close(SWMM_Engine engine);
 #include "openswmm_hotstart.h"
 #include "openswmm_spatial.h"
 #include "openswmm_pollutants.h"
+#include "openswmm_initial_quality.h"
+#include "openswmm_reactions.h"
+#include "openswmm_process_components.h"
 #include "openswmm_tables.h"
 #include "openswmm_inflows.h"
 #include "openswmm_controls.h"
@@ -494,6 +597,7 @@ SWMM_ENGINE_API int swmm_runoff_iface_close(SWMM_Engine engine);
 
 #ifdef OPENSWMM_HAS_2D
 #include "openswmm_2d.h"
+#include "openswmm_gw_transport.h"   /* U4 (2026-09-07) */
 #endif
 
 #endif /* OPENSWMM_ENGINE_H */
diff --git a/include/openswmm/engine/openswmm_forcing.h b/include/openswmm/engine/openswmm_forcing.h
index c3c19ad38..4047c5b35 100644
--- a/include/openswmm/engine/openswmm_forcing.h
+++ b/include/openswmm/engine/openswmm_forcing.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_forcing.h
  * @brief Runtime forcing API — inject fluxes with mass-balance tracking.
@@ -40,7 +56,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_FORCING_H
@@ -97,9 +113,22 @@ typedef enum SWMM_ForcingType {
     SWMM_FORCE_CLIMATE_WIND        = 9,  /**< System-wide; idx ignored. */
     SWMM_FORCE_SUBCATCH_SNOWFALL   = 10,
     SWMM_FORCE_CLIMATE_EVAP        = 11, /**< System-wide; idx ignored. */
-    SWMM_FORCE_LINK_QUALITY        = 12
+    SWMM_FORCE_LINK_QUALITY        = 12,
+    /* PE4 — per-ELEMENT climate. `idx` is the element index and the kind is
+       given separately; see swmm_forcing_element_climate. */
+    SWMM_FORCE_ELEM_AIR_TEMPERATURE = 13,
+    SWMM_FORCE_ELEM_HUMIDITY        = 14,
+    SWMM_FORCE_ELEM_WIND_SPEED      = 15,
+    SWMM_FORCE_ELEM_SHORTWAVE       = 16,
+    SWMM_FORCE_LINK_SEEPAGE         = 17  /**< G-X4: conduit ⇄ groundwater exchange. */
 } SWMM_ForcingType;
 
+/** @brief Which element a per-element climate forcing targets (PE4). */
+typedef enum SWMM_HeatElemKind {
+    SWMM_HEAT_ELEM_NODE = 0,
+    SWMM_HEAT_ELEM_LINK = 1
+} SWMM_HeatElemKind;
+
 /* =========================================================================
  * Node forcing
  * ========================================================================= */
@@ -148,6 +177,35 @@ SWMM_ENGINE_API int swmm_forcing_node_quality(
     SWMM_Engine engine, int node_idx, int pollutant_idx,
     double mass_rate, int mode, int persist);
 
+/**
+ * @brief Force the water temperature at a node (U2, 2026-09-07).
+ *
+ * @details The reserved-species twin of @ref swmm_forcing_node_quality.
+ *          OVERRIDE sets the node's PUBLISHED temperature (degC) directly —
+ *          not mass-balanced, exactly like the pollutant OVERRIDE. ADD
+ *          injects a rate (degC × ft3/s, the `node_temp_vol_in` convention
+ *          every quality engine already reads), so the arriving water is
+ *          mixed with the store instead of replacing it.
+ *          Requires [OPTIONS] HEAT_TRANSPORT YES; otherwise SWMM_ERR_BADPARAM.
+ *
+ * @ingroup engine_forcing
+ */
+SWMM_ENGINE_API int swmm_forcing_node_temperature(
+    SWMM_Engine engine, int node_idx, double value, int mode, int persist);
+
+/**
+ * @brief Force the water age at a node (U2, 2026-09-07).
+ *
+ * @details OVERRIDE sets the node's published age in HOURS (the
+ *          [WATER_AGE_SOURCES] and [INFLOWS] __WATER_AGE__ unit); ADD
+ *          injects an age-volume rate (hours × ft3/s) into the loader
+ *          accumulator. Requires [OPTIONS] WATER_AGE YES.
+ *
+ * @ingroup engine_forcing
+ */
+SWMM_ENGINE_API int swmm_forcing_node_age(
+    SWMM_Engine engine, int node_idx, double value, int mode, int persist);
+
 /* =========================================================================
  * Link forcing
  * ========================================================================= */
@@ -180,6 +238,40 @@ SWMM_ENGINE_API int swmm_forcing_link_flow(
 SWMM_ENGINE_API int swmm_forcing_link_setting(
     SWMM_Engine engine, int idx, double value, int mode, int persist);
 
+/**
+ * @brief Force a conduit's groundwater exchange rate (G-X4, 2026-09-20).
+ *
+ * @details The HydroCouple inlet for an external groundwater model: the
+ *          value REPLACES (OVERRIDE) or adds to (ADD) the conduit's seepage
+ *          rate for the step, in the engine's own flow units, positive OUT
+ *          of the conduit. A negative value is a gaining reach — water the
+ *          host's aquifer hands to the pipe — and lands in the mass balance
+ *          as SWMM_ROUTING_LINK_GW_INFLOW, exactly like the internal signed
+ *          law's gain.
+ *
+ *          When the built-in `[2D_AQUIFER]` is also coupled to this conduit
+ *          (`LINK_SEEPAGE AUTO` or `TWO_WAY`), the forced rate is what the
+ *          2D aquifer is debited or credited as well — the host is then
+ *          steering the internal aquifer, not replacing it. To drive a
+ *          conduit from an external aquifer instead, leave the internal one
+ *          out of the reach (`LINK_SEEPAGE NONE`, or `EXCHANGE NO` on a
+ *          `[2D_AQUIFER_LINKS]` row).
+ *
+ *          Non-conduit links have no seepage and ignore this.
+ *
+ * @param engine   Engine handle.
+ * @param idx      Link index (a conduit).
+ * @param value    Exchange rate, + out of the conduit, in the same units
+ *                 @ref swmm_forcing_link_flow takes — the engine's internal
+ *                 flow unit, which is CFS whatever FLOW_UNITS says.
+ * @param mode     SWMM_FORCING_OVERRIDE or SWMM_FORCING_ADD.
+ * @param persist  SWMM_FORCING_RESET or SWMM_FORCING_PERSIST.
+ * @returns SWMM_OK or error code.
+ * @ingroup engine_forcing
+ */
+SWMM_ENGINE_API int swmm_forcing_link_seepage(
+    SWMM_Engine engine, int idx, double value, int mode, int persist);
+
 /**
  * @brief Force pollutant quality on a link.
  *
@@ -407,6 +499,64 @@ SWMM_ENGINE_API int swmm_forcing_gage_rainfall(
  * @returns SWMM_OK or error code.
  * @ingroup engine_forcing
  */
+/* =========================================================================
+ * PE4 — per-element climate
+ *
+ * Air temperature, humidity, wind and incoming shortwave are GLOBAL in every
+ * deck and per-element ONLY here. There is no deck syntax for per-element
+ * meteorology at any phase, deliberately: `ClimateState` is shared with
+ * hydrology, snowmelt and evaporation, so a hand-maintained file that could
+ * set a per-conduit air temperature would assert something the snowpack on
+ * the subcatchment above permanently disagrees with. A caller of THIS API is
+ * a coupled driver asserting the heterogeneity per step and answerable for
+ * it — which is how the reference works too: HydroCouple's RHEComponent and
+ * CSHComponent receive per-element meteorology through EXCHANGE ITEMS.
+ *
+ * Values are resolved AT THE FLUX CALL, never written into the climate
+ * state, so a per-link push cannot reach snowmelt or evaporation.
+ * ========================================================================= */
+
+/**
+ * @brief Prescribe a climate variable for ONE element.
+ *
+ * @details Only LINK and NODE are accepted. Neither has a competing consumer
+ *          for air temperature — snowmelt runs on subcatchments, evaporation
+ *          on subcatchment and storage surfaces — so no subsystem divergence
+ *          is possible. A subcatchment DOES have competing consumers, so
+ *          there is deliberately no subcatchment spelling here; that would
+ *          be a distributed-climate feature, not a heat-transport one.
+ *
+ * @param kind      SWMM_HeatElemKind.
+ * @param index     Element index within that kind.
+ * @param variable  One of the SWMM_FORCE_ELEM_* channels.
+ * @param value     Air temperature °F/°C by unit system, humidity %,
+ *                  wind mph/kph, shortwave W/m².
+ * @param mode      SWMM_FORCING_OVERRIDE or SWMM_FORCING_ADD. **ADD is
+ *                  usually what a coupled driver wants**: a model that knows
+ *                  a reach runs 2 °C cooler than the gauge pushes ADD -2 and
+ *                  never needs the gauge value.
+ * @param persist   SWMM_FORCING_RESET or SWMM_FORCING_PERSIST. **RESET is
+ *                  the right default for a driver that pushes every step.**
+ *                  Under PERSIST, a driver that pushes on some steps and not
+ *                  others silently reuses a stale field that looks like data
+ *                  and is hours old; under RESET the value falls back to the
+ *                  global broadcast the moment the driver stops feeding it.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM for an unsupported kind/channel.
+ * @ingroup engine_forcing
+ */
+SWMM_ENGINE_API int swmm_forcing_element_climate(
+    SWMM_Engine engine, int kind, int index, int variable, double value,
+    int mode, int persist);
+
+/**
+ * @brief Read back a per-element climate forcing.
+ * @param mode  Receives SWMM_FORCING_NONE when nothing is set.
+ * @ingroup engine_forcing
+ */
+SWMM_ENGINE_API int swmm_forcing_element_climate_get(
+    SWMM_Engine engine, int kind, int index, int variable, double* value,
+    int* mode);
+
 SWMM_ENGINE_API int swmm_forcing_clear(SWMM_Engine engine, int type, int idx);
 
 /**
diff --git a/include/openswmm/engine/openswmm_gages.h b/include/openswmm/engine/openswmm_gages.h
index a3f53ad7b..b66bdb234 100644
--- a/include/openswmm/engine/openswmm_gages.h
+++ b/include/openswmm/engine/openswmm_gages.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_gages.h
  * @brief OpenSWMM Engine — Rain Gage C API.
@@ -9,7 +25,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GAGES_H
@@ -127,10 +143,13 @@ SWMM_ENGINE_API int swmm_gage_set_timeseries(SWMM_Engine engine, int idx, const
  *                    file grammar `Fname Station Units`).
  * @returns SWMM_OK on success, or an error code.
  *
- * @details Sets the data source to FILE and selects the standard SWMM rain
- *          file format (STAN_PRCP). The station id is stored in the gage's
- *          `station_id` slot (the token matched against the file's first
- *          column), not the CSV column-name slot.
+ * @details Sets the data source to FILE. The file format is preserved when
+ *          the gage is already USER_CSV (multi-column "path:col"), otherwise
+ *          it is auto-detected: a non-empty file column implies USER_CSV and
+ *          anything else selects the standard SWMM rain file format
+ *          (STAN_PRCP). The station id is stored in the gage's `station_id`
+ *          slot (the token matched against the file's first column), not the
+ *          CSV column-name slot — see swmm_gage_set_file_column().
  */
 SWMM_ENGINE_API int swmm_gage_set_filename(SWMM_Engine engine, int idx, const char* path,
                                                    const char* station_id);
@@ -144,6 +163,45 @@ SWMM_ENGINE_API int swmm_gage_set_filename(SWMM_Engine engine, int idx, const ch
  */
 SWMM_ENGINE_API int swmm_gage_set_station_id(SWMM_Engine engine, int idx, const char* station_id);
 
+/**
+ * @brief Set the data column name for a multi-column rain-file gage.
+ * @param engine  Engine handle.
+ * @param idx     Zero-based gage index.
+ * @param column  Column header name inside the file (empty = use the first
+ *                data column).
+ * @returns SWMM_OK on success, or an error code.
+ *
+ * @details Stores the column selector used by the "FILE path:col" form
+ *          (multi-column CSV/TSV/TSF). Setting a non-empty column switches
+ *          the gage's file format to USER_CSV; clearing it leaves the format
+ *          unchanged (an empty column on a USER_CSV gage reads the file's
+ *          first data column).
+ */
+SWMM_ENGINE_API int swmm_gage_set_file_column(SWMM_Engine engine, int idx, const char* column);
+
+/**
+ * @brief Set the rain file format for a file-based gage.
+ * @param engine  Engine handle.
+ * @param idx     Zero-based gage index.
+ * @param format  RainFileFormat code (-1 = UNKNOWN, 5 = STAN_PRCP standard
+ *                SWMM rain file, 6 = USER_CSV multi-column CSV/TSV/TSF).
+ * @returns SWMM_OK on success, or SWMM_ERR_BADPARAM for a code that is not a
+ *          RainFileFormat value.
+ *
+ * @details The counterpart of swmm_gage_get_file_format(), and the only way
+ *          back out of USER_CSV: swmm_gage_set_file_column() and
+ *          swmm_gage_set_filename() both preserve USER_CSV by design, so
+ *          without this a host that ever set a column could not return the
+ *          gage to a standard rain file.
+ *
+ *          The two formats' row selectors are mutually exclusive, so this
+ *          clears the one that does not apply: selecting USER_CSV clears the
+ *          gage's `station_id` (a multi-column file has no station column),
+ *          and selecting any station-based format — STAN_PRCP included —
+ *          clears its file column name.
+ */
+SWMM_ENGINE_API int swmm_gage_set_file_format(SWMM_Engine engine, int idx, int format);
+
 /**
  * @brief Set the snow-catch deficiency correction factor (SCF) for a gage.
  * @param engine  Engine handle.
@@ -248,6 +306,29 @@ SWMM_ENGINE_API int swmm_gage_get_timeseries(SWMM_Engine engine, int idx, char*
  */
 SWMM_ENGINE_API int swmm_gage_get_station_id(SWMM_Engine engine, int idx, char* buf, int buflen);
 
+/**
+ * @brief Get the data column name for a multi-column rain-file gage.
+ * @param engine       Engine handle.
+ * @param idx          Zero-based gage index.
+ * @param[out] buf     Caller buffer that receives the NUL-terminated column
+ *                    name (empty string when none is set).
+ * @param buflen       Size of @p buf in bytes.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gage_get_file_column(SWMM_Engine engine, int idx, char* buf, int buflen);
+
+/**
+ * @brief Get the rain file format for a file-based gage.
+ * @param engine        Engine handle.
+ * @param idx           Zero-based gage index.
+ * @param[out] format   Receives the RainFileFormat code (-1 = UNKNOWN,
+ *                      5 = STAN_PRCP standard SWMM rain file, 6 = USER_CSV
+ *                      multi-column CSV/TSV/TSF). Meaningful only when the
+ *                      data source is FILE.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gage_get_file_format(SWMM_Engine engine, int idx, int* format);
+
 /**
  * @brief Get the rain-depth units declared for a file-based gage.
  * @param engine        Engine handle.
@@ -290,6 +371,80 @@ SWMM_ENGINE_API int swmm_gage_get_rainfall_bulk(SWMM_Engine engine, double* buf,
  *  idx is out of range. */
 SWMM_ENGINE_API int swmm_gage_rename(SWMM_Engine engine, int idx, const char* newId);
 
+/* =========================================================================
+ * Resolved rainfall series
+ * ========================================================================= */
+
+/**
+ * @brief Number of entries in a gage's resolved rainfall series.
+ *
+ * @details Works for both data sources: a TIMESERIES gage reports its table's
+ *          length, a FILE gage the length of the series loaded from disk at
+ *          open. A FILE gage reports 0 when its file could not be read or its
+ *          format is not one the engine loads — in which case that gage also
+ *          contributes no rainfall to the run.
+ *
+ * @param engine     Engine handle.
+ * @param idx        Zero-based gage index.
+ * @param[out] count Receives the entry count.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gage_get_rainfall_series_count(SWMM_Engine engine, int idx,
+                                                        int* count);
+
+/**
+ * @brief Copy a gage's resolved rainfall series.
+ *
+ * @details Returns the rainfall the engine will ACTUALLY apply, so a caller
+ *          never has to know how a gage stores its data. The rain-type
+ *          transform, the rain-file units factor, and the gage scale factor
+ *          are all applied, using the same conversion the routing update runs
+ *          — so a series read back here and replayed through a TIMESERIES gage
+ *          of type INTENSITY reproduces the original gage.
+ *
+ *          Each entry is the intensity that applies from its own time stamp
+ *          until the recording interval elapses or the next entry begins,
+ *          whichever comes first; rainfall is zero in between. Pair this with
+ *          swmm_gage_get_rain_interval() to reconstruct that behaviour.
+ *
+ * @note A FILE gage's series is windowed to the [OPTIONS] simulation dates
+ *       (± one day) and reflects the file as it was read at open. Call
+ *       swmm_gage_reload_rain_files() first if the path, station, units, or
+ *       simulation dates have changed since.
+ *
+ * @param engine      Engine handle.
+ * @param idx         Zero-based gage index.
+ * @param[out] times  Receives entry times as SWMM DateTime (decimal days),
+ *                    matching swmm_table_get_point(). May be NULL.
+ * @param[out] values Receives rainfall INTENSITY in the project's rain units
+ *                    per hour (in/hr for US flow units, mm/hr for SI).
+ *                    May be NULL.
+ * @param count       Capacity of each output array; at most this many entries
+ *                    are written.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gage_get_rainfall_series(SWMM_Engine engine, int idx,
+                                                  double* times, double* values,
+                                                  int count);
+
+/**
+ * @brief Re-read every FILE-source rain gage's data from disk.
+ *
+ * @details Rain files are loaded once, during open(). Nothing re-runs that
+ *          afterwards, so changing a gage's path, station id, or rain units —
+ *          or the simulation dates the data is windowed to — has no effect
+ *          until the model is reopened, and readers keep seeing the previous
+ *          file's contents. Call this after such an edit.
+ *
+ *          Rebuilds the resolved series and the rainfall-file summary
+ *          statistics for every FILE gage. Requires the model to be editable
+ *          (BUILDING or OPENED); it is not valid mid-run.
+ *
+ * @param engine Engine handle.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gage_reload_rain_files(SWMM_Engine engine);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/include/openswmm/engine/openswmm_geopackage.h b/include/openswmm/engine/openswmm_geopackage.h
index c9555cee7..569948693 100644
--- a/include/openswmm/engine/openswmm_geopackage.h
+++ b/include/openswmm/engine/openswmm_geopackage.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_geopackage.h
  * @brief OpenSWMM Engine — GeoPackage C API.
@@ -55,7 +71,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_H
diff --git a/include/openswmm/engine/openswmm_gw2d.h b/include/openswmm/engine/openswmm_gw2d.h
new file mode 100644
index 000000000..3585d43bc
--- /dev/null
+++ b/include/openswmm/engine/openswmm_gw2d.h
@@ -0,0 +1,303 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_gw2d.h
+ * @brief G-step 19 — the two-zone groundwater kernel's C API: authoring the
+ *        `[2D_AQUIFER*]` rows, and reading the state and ledger while a run
+ *        is in flight.
+ *
+ * @details The API has two halves and they obey different rules.
+ *
+ *          **Authoring** (`swmm_gw2d_option_*`, `swmm_gw2d_row_*`,
+ *          `swmm_gw2d_node_*`) edits the rows the kernel is built from, so it
+ *          requires BUILDING or OPENED — exactly like the 2D boundary and
+ *          infiltration APIs. A mid-run edit would be silently ignored, which
+ *          is worse than being refused. Values are in the PROJECT's units
+ *          (see SubsurfaceSections.hpp's table); the API does not convert,
+ *          because a host that sets what it read back must get the same
+ *          number.
+ *
+ *          **State** (`swmm_gw2d_get_*`) reads the running kernel and is
+ *          available whenever a run has started. Everything it returns is
+ *          **SI** — metres, seconds, m³ — because that is what the kernel
+ *          holds and converting on the way out would make a reader's units
+ *          depend on the project's, which is precisely the bug class the
+ *          engine's 1D↔2D seam already had once.
+ *
+ *          **Cell-generic.** Every index is a CELL (`0 .. cell_count−1` here;
+ *          1-based in the `.inp`). Nothing assumes three edges.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_GW2D_H
+#define OPENSWMM_GW2D_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ---- Scopes (same encoding as the [GW_*] transport API) ------------------ */
+
+#define SWMM_GW2D_SCOPE_GLOBAL 0   /**< the `*` row */
+#define SWMM_GW2D_SCOPE_TAG    1   /**< every cell carrying a tag */
+#define SWMM_GW2D_SCOPE_CELL   2   /**< one cell, 0-based here */
+
+/* ---- Soil-characteristic laws ------------------------------------------- */
+
+#define SWMM_GW2D_SOIL_RUSSO         0
+#define SWMM_GW2D_SOIL_GARDNER       1
+#define SWMM_GW2D_SOIL_BROOKS_COREY  2
+#define SWMM_GW2D_SOIL_VAN_GENUCHTEN 3
+
+/* ---- Unsaturated-zone closures ------------------------------------------ */
+
+#define SWMM_GW2D_CLOSURE_AUTO        (-1)
+#define SWMM_GW2D_CLOSURE_CLOSED_FORM 0
+#define SWMM_GW2D_CLOSURE_ENSLAVED    1
+#define SWMM_GW2D_CLOSURE_SIGMA       2
+
+/* ---- Per-cell state selectors ------------------------------------------- */
+
+#define SWMM_GW2D_VAR_HG        0   /**< saturated thickness (m) */
+#define SWMM_GW2D_VAR_HU        1   /**< unsaturated storage (m of water) */
+#define SWMM_GW2D_VAR_TABLE_EL  2   /**< water-table elevation (m) */
+#define SWMM_GW2D_VAR_Q0        3   /**< recharge (m/s), + down */
+#define SWMM_GW2D_VAR_QLAT      4   /**< net lateral Darcy in (m3/s) */
+#define SWMM_GW2D_VAR_QNODE     5   /**< node exchange (m3/s), + out */
+#define SWMM_GW2D_VAR_QDEEP     6   /**< deep loss (m/s) */
+#define SWMM_GW2D_VAR_QET       7   /**< subsurface ET (m/s) */
+#define SWMM_GW2D_VAR_DUNNE     8   /**< saturation excess to surface (m3/s) */
+#define SWMM_GW2D_VAR_QPLUS     9   /**< infiltration delivered in (m/s) */
+#define SWMM_GW2D_VAR_DT_CELL   10  /**< min(dt_g, dt_u) (s) */
+#define SWMM_GW2D_VAR_TIER      11  /**< assigned LTS tier */
+#define SWMM_GW2D_VAR_CLOSURE   12  /**< resolved closure (AUTO already gone) */
+#define SWMM_GW2D_VAR_QLINK     13  /**< G-X3: conduit seepage delivered in (m3/s) */
+
+/* ---- Ledger selectors (m3, cumulative) ---------------------------------- */
+
+#define SWMM_GW2D_LED_RECHARGE      0
+#define SWMM_GW2D_LED_LATERAL       1
+#define SWMM_GW2D_LED_DEEP          2
+#define SWMM_GW2D_LED_NODE          3
+#define SWMM_GW2D_LED_DUNNE         4
+#define SWMM_GW2D_LED_CAPRISE       5
+#define SWMM_GW2D_LED_ET            6
+#define SWMM_GW2D_LED_INFIL_IN      7
+#define SWMM_GW2D_LED_INIT_STORAGE  8
+#define SWMM_GW2D_LED_STORAGE       9   /**< storage NOW, incl. accumulators */
+#define SWMM_GW2D_LED_LINK          10  /**< G-X3: conduit seepage delivered in */
+
+/* ---- T7.5: the transported tuple (read-only results) --------------------- */
+
+/** Zone selector for the species accessors. */
+#define SWMM_GW2D_ZONE_SAT    0   /**< the saturated zone */
+#define SWMM_GW2D_ZONE_UNSAT  1   /**< the unsaturated column store */
+
+/** Species ledger terms — the `groundwater_species_ledger` order. */
+#define SWMM_GW2D_SPL_INIT        0
+#define SWMM_GW2D_SPL_STORAGE     1   /**< ledgered storage NOW */
+#define SWMM_GW2D_SPL_INFIL_IN    2
+#define SWMM_GW2D_SPL_NODE_IN     3
+#define SWMM_GW2D_SPL_LINK_IN     4
+#define SWMM_GW2D_SPL_LATERAL_NET 5
+#define SWMM_GW2D_SPL_DEEP_OUT    6
+#define SWMM_GW2D_SPL_NODE_OUT    7
+#define SWMM_GW2D_SPL_LINK_OUT    8
+#define SWMM_GW2D_SPL_DUNNE_OUT   9
+#define SWMM_GW2D_SPL_ET_OUT      10
+#define SWMM_GW2D_SPL_REACTED     11
+#define SWMM_GW2D_SPL_RESIDUAL    12  /**< storage + out - in - init */
+
+/** How many species rows the aquifer transports (0 when it carries none). */
+SWMM_ENGINE_API int swmm_gw2d_species_count(SWMM_Engine engine, int* count);
+
+/** One species row's name (TransportPolicy order: pollutants, MSX,
+ *  `__WATER_AGE__`, `__TEMPERATURE__`). */
+SWMM_ENGINE_API int swmm_gw2d_species_name(SWMM_Engine engine, int species,
+                                           char* buf, int buflen);
+
+/** Per-cell CONCENTRATION of one species in one zone, in the species' own
+ *  units (mass / m3 of that zone's water). A zone with no water reports 0.
+ *  Writes at most @p len values and sets @p written. */
+SWMM_ENGINE_API int swmm_gw2d_get_cell_conc(SWMM_Engine engine, int zone,
+                                            int species, double* out, int len,
+                                            int* written);
+
+/** One term of one species' cumulative ledger — see SWMM_GW2D_SPL_*. */
+SWMM_ENGINE_API int swmm_gw2d_get_species_ledger(SWMM_Engine engine,
+                                                 int species, int term,
+                                                 double* value);
+
+/* =========================================================================
+ * [2D_AQUIFER_OPTIONS]
+ * ========================================================================= */
+
+/** Read one option as text. Keys: SOIL_CHAR, CLOSURE, M_LAYERS,
+ *  CAPILLARY_DIFF, C_GW, C_COL, FORCE_CLOSED_FORM, MODE, DUNNE, GW_ET,
+ *  NODE_ENROLMENT (AUTO | ROWS — G-X2), LINK_SEEPAGE (AUTO | NONE — G-X3). */
+SWMM_ENGINE_API int swmm_gw2d_option_get(SWMM_Engine engine, const char* key,
+                                         char* buf, int buflen);
+
+/** Set one option from text. Same keys and the same token spellings the
+ *  `.inp` accepts — one parser, so the file and the API cannot drift. */
+SWMM_ENGINE_API int swmm_gw2d_option_set(SWMM_Engine engine, const char* key,
+                                         const char* value);
+
+/* =========================================================================
+ * [2D_AQUIFER] rows
+ * ========================================================================= */
+
+/** Number of authored rows. */
+SWMM_ENGINE_API int swmm_gw2d_row_count(SWMM_Engine engine, int* count);
+
+/**
+ * @brief Append one row. Values are in the PROJECT's units.
+ *
+ * @param scope   SWMM_GW2D_SCOPE_*
+ * @param tag     tag name for SCOPE_TAG, else ignored (may be NULL)
+ * @param cell    0-based cell for SCOPE_CELL, else ignored
+ * @param ks      saturated conductivity (in/hr | mm/hr)
+ * @param zs      soil column thickness (ft | m)
+ * @param theta_s porosity
+ * @param theta_r residual water content
+ * @param alpha   sorptive number (1/ft | 1/m)
+ */
+SWMM_ENGINE_API int swmm_gw2d_row_add(SWMM_Engine engine, int scope,
+                                      const char* tag, int cell,
+                                      double ks, double zs,
+                                      double theta_s, double theta_r,
+                                      double alpha);
+
+/** Read row @p index back, in the units it was authored in. Any out pointer
+ *  may be NULL. @p tag needs @p taglen bytes. */
+SWMM_ENGINE_API int swmm_gw2d_row_get(SWMM_Engine engine, int index,
+                                      int* scope, char* tag, int taglen,
+                                      int* cell, double* ks, double* zs,
+                                      double* theta_s, double* theta_r,
+                                      double* alpha);
+
+/** Set one of a row's optional properties. Keys: PSI_B, LAMBDA, N, L,
+ *  C_LOSS, HG0, SOIL_CHAR, CLOSURE, M_LAYERS. The numeric-valued keys take
+ *  @p value; SOIL_CHAR and CLOSURE take the SWMM_GW2D_SOIL_* /
+ *  SWMM_GW2D_CLOSURE_* codes as a double, which keeps this one entry point
+ *  instead of nine. */
+SWMM_ENGINE_API int swmm_gw2d_row_set_property(SWMM_Engine engine, int index,
+                                               const char* key, double value);
+
+/** Read one optional property back. */
+SWMM_ENGINE_API int swmm_gw2d_row_get_property(SWMM_Engine engine, int index,
+                                               const char* key, double* value);
+
+/** Remove row @p index. */
+SWMM_ENGINE_API int swmm_gw2d_row_remove(SWMM_Engine engine, int index);
+
+/* =========================================================================
+ * [2D_AQUIFER_NODE] beds
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_gw2d_node_count(SWMM_Engine engine, int* count);
+
+/** Add a node bed. @p kc in in/hr | mm/hr, @p dc in ft | m, @p area in
+ *  ft2 | m2 (0 = the cell's own area). @p kc == 0 means direct Darcy. */
+SWMM_ENGINE_API int swmm_gw2d_node_add(SWMM_Engine engine, const char* node,
+                                       int cell, double kc, double dc,
+                                       double area);
+
+SWMM_ENGINE_API int swmm_gw2d_node_get(SWMM_Engine engine, int index,
+                                       char* node, int nodelen, int* cell,
+                                       double* kc, double* dc, double* area);
+
+SWMM_ENGINE_API int swmm_gw2d_node_remove(SWMM_Engine engine, int index);
+
+/** G-X2 (2026-09-19): a bed's enrolment state. `locate` — the cell is found
+ *  from the node's [COORDINATES] at initialize (`CELL AUTO`; pass cell −1 to
+ *  swmm_gw2d_node_add); `exchange` — 0 when the row opts the node OUT
+ *  (`EXCHANGE NO`); `automatic` — enrolled by NODE_ENROLMENT AUTO rather than
+ *  authored (present after initialize only; not written back). Any pointer
+ *  may be NULL. */
+SWMM_ENGINE_API int swmm_gw2d_node_get_flags(SWMM_Engine engine, int index,
+                                             int* locate, int* exchange,
+                                             int* automatic);
+
+/** G-X2: set a row's EXCHANGE flag (0 = the node exchanges with nothing). */
+SWMM_ENGINE_API int swmm_gw2d_node_set_exchange(SWMM_Engine engine, int index,
+                                                int exchange);
+
+/* =========================================================================
+ * Running state — SI throughout
+ * ========================================================================= */
+
+/** Non-zero once a `[2D_AQUIFER]` row has resolved and the kernel is live. */
+SWMM_ENGINE_API int swmm_gw2d_is_active(SWMM_Engine engine, int* active);
+
+/** Cells the kernel covers, and the sigma layer count (1 when no cell uses
+ *  closure B). Either pointer may be NULL. */
+SWMM_ENGINE_API int swmm_gw2d_get_dimensions(SWMM_Engine engine,
+                                             int* n_cells, int* m_layers);
+
+/** One cell, one variable — see SWMM_GW2D_VAR_*. */
+SWMM_ENGINE_API int swmm_gw2d_get_cell(SWMM_Engine engine, int cell, int var,
+                                       double* value);
+
+/** Bulk read of one variable over `[0, n_cells)`. @p len must be at least
+ *  the cell count; the number written is returned through @p written. */
+SWMM_ENGINE_API int swmm_gw2d_get_cell_bulk(SWMM_Engine engine, int var,
+                                            double* out, int len,
+                                            int* written);
+
+/** The sigma column of one cell: `m_layers` water contents, layer 0 at the
+ *  ground surface. Refused with SWMM_ERR_BADPARAM when the cell's closure is
+ *  not SIGMA — an all-zero buffer would read as a bone-dry column. */
+SWMM_ENGINE_API int swmm_gw2d_get_column(SWMM_Engine engine, int cell,
+                                         double* theta, int len,
+                                         int* written);
+
+/** One ledger term — see SWMM_GW2D_LED_*. */
+SWMM_ENGINE_API int swmm_gw2d_get_ledger(SWMM_Engine engine, int term,
+                                         double* value);
+
+/**
+ * @brief Continuity residual (m3): `storage_now − storage_init − (in − out)`.
+ *
+ * @details The single number that says whether the kernel is conserving.
+ *          `storage_now` includes anything still parked in a side
+ *          accumulator, because between firings that water is real and is
+ *          simply not on a cell yet — a residual computed without it reports
+ *          a leak that is not there. See SubsurfaceSolver::settle.
+ */
+SWMM_ENGINE_API int swmm_gw2d_get_continuity_error(SWMM_Engine engine,
+                                                   double* value);
+
+/** Cumulative firings per LTS tier — the G-A telemetry. Writes
+ *  `min(len, tier_count)` entries. */
+SWMM_ENGINE_API int swmm_gw2d_get_tier_histogram(SWMM_Engine engine,
+                                                 long* out, int len,
+                                                 int* written);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_GW2D_H */
diff --git a/include/openswmm/engine/openswmm_gw_transport.h b/include/openswmm/engine/openswmm_gw_transport.h
new file mode 100644
index 000000000..1b33c8f28
--- /dev/null
+++ b/include/openswmm/engine/openswmm_gw_transport.h
@@ -0,0 +1,189 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_gw_transport.h
+ * @brief U4 (2026-09-07) — C API for the `[GW_*]` subsurface-transport
+ *        authoring sections.
+ *
+ * @details These sections round-trip authored subsurface transport inputs.
+ *          The integrated two-zone groundwater kernel consumes them at
+ *          initialization. Runtime availability depends on the model and
+ *          enabled transport classes; query swmm_get_transport_matrix() for
+ *          capabilities and openswmm_gw2d.h for runtime state and ledgers.
+ *
+ *          **Cell-generic.** Every index is a CELL (`0 .. swmm_2d_cell_count-1`
+ *          through this API; 1-based in the `.inp`), and an edge is the LOCAL
+ *          edge `0 .. nv-1` of ITS cell — 3 for a triangle, 4 for a quad.
+ *
+ *          **Editing state.** Setters require BUILDING or OPENED, the same
+ *          contract as the 2D boundary API: the rows seed the kernel at
+ *          initialize, so a mid-run edit would silently no-op.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_GW_TRANSPORT_H
+#define OPENSWMM_GW_TRANSPORT_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ---- Scopes and zones ---------------------------------------------------- */
+
+#define SWMM_GW_SCOPE_GLOBAL 0   /**< the `*` row */
+#define SWMM_GW_SCOPE_TAG    1   /**< every cell carrying a tag */
+#define SWMM_GW_SCOPE_CELL   2   /**< one cell, 0-based here */
+
+#define SWMM_GW_ZONE_SAT     0
+#define SWMM_GW_ZONE_UNSAT   1
+#define SWMM_GW_ZONE_LAYER   2   /**< with an explicit 1-based layer index */
+
+/* =========================================================================
+ * [GW_TRANSPORT_OPTIONS]
+ * =========================================================================
+ * Key/value like swmm_options_get_ext: TRANSPORT_POLLUTANTS, TRANSPORT_MSX,
+ * TRANSPORT_AGE, TRANSPORT_TEMPERATURE, DISPERSION, CONDUCTION,
+ * SURFACE_THERMAL_BC, DEEP_THERMAL_BC, THERMAL_MIXING, C_DIFF. Values use the
+ * section's own spelling; SURFACE_THERMAL_BC / DEEP_THERMAL_BC read back with
+ * their argument appended ("FIXED 12.5", "GEOTHERMAL_FLUX 0.065 DEPTH 20").
+ */
+
+/** @brief Read one option into @p buf. SWMM_ERR_BADPARAM on an unknown key. */
+SWMM_ENGINE_API int swmm_gw_transport_option_get(SWMM_Engine engine,
+        const char* key, char* buf, int buflen);
+
+/** @brief Set one option (BUILDING/OPENED). */
+SWMM_ENGINE_API int swmm_gw_transport_option_set(SWMM_Engine engine,
+        const char* key, const char* value);
+
+/** @brief 1 when any `[GW_*]` row was authored, else 0. */
+SWMM_ENGINE_API int swmm_gw_transport_authored(SWMM_Engine engine);
+
+/* =========================================================================
+ * [GW_TRANSPORT_PARAMS]
+ * ========================================================================= */
+
+typedef struct SWMM_GwParams {
+    int    scope;      /**< SWMM_GW_SCOPE_* */
+    int    cell;       /**< 0-based; -1 for GLOBAL/TAG */
+    double rho_s;      /**< grain density (kg/m3) */
+    double c_s;        /**< grain specific heat (J/kg/K) */
+    double lambda_s;   /**< grain thermal conductivity (W/m/K) */
+    double a_s;        /**< specific surface area (m2/kg) */
+    double alpha_L;    /**< longitudinal dispersivity (m) */
+    double alpha_T;    /**< transverse dispersivity (m) */
+    double D_m;        /**< molecular diffusivity (m2/s) */
+    double D_v;        /**< vapour diffusivity (m2/s) */
+    double geo_flux;   /**< geothermal flux (W/m2) or deep temperature (degC) */
+} SWMM_GwParams;
+
+SWMM_ENGINE_API int swmm_gw_params_count(SWMM_Engine engine);
+/** @brief Read row @p idx; @p tag_buf receives the TAG (empty otherwise). */
+SWMM_ENGINE_API int swmm_gw_params_get(SWMM_Engine engine, int idx,
+        SWMM_GwParams* row, char* tag_buf, int tag_len);
+/** @brief Append or replace the row for (@p scope, @p tag/@p cell). */
+SWMM_ENGINE_API int swmm_gw_params_set(SWMM_Engine engine,
+        const SWMM_GwParams* row, const char* tag);
+SWMM_ENGINE_API int swmm_gw_params_remove(SWMM_Engine engine, int idx);
+
+/* =========================================================================
+ * [GW_SORPTION]
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_gw_sorption_count(SWMM_Engine engine);
+/** @param decay 1/day; negative means "use the [POLLUTANTS] kdecay". */
+SWMM_ENGINE_API int swmm_gw_sorption_get(SWMM_Engine engine, int idx,
+        int* scope, char* tag_buf, int tag_len, int* cell,
+        char* species_buf, int species_len, double* kd, double* decay);
+SWMM_ENGINE_API int swmm_gw_sorption_set(SWMM_Engine engine, int scope,
+        const char* tag, int cell, const char* species, double kd, double decay);
+SWMM_ENGINE_API int swmm_gw_sorption_remove(SWMM_Engine engine, int idx);
+
+/* =========================================================================
+ * [GW_INITIAL_QUALITY]
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_gw_init_quality_count(SWMM_Engine engine);
+/** @param layer 1-based, meaningful only when @p zone is SWMM_GW_ZONE_LAYER. */
+SWMM_ENGINE_API int swmm_gw_init_quality_get(SWMM_Engine engine, int idx,
+        int* scope, char* tag_buf, int tag_len, int* cell,
+        int* zone, int* layer, char* species_buf, int species_len, double* value);
+SWMM_ENGINE_API int swmm_gw_init_quality_set(SWMM_Engine engine, int scope,
+        const char* tag, int cell, int zone, int layer,
+        const char* species, double value);
+SWMM_ENGINE_API int swmm_gw_init_quality_remove(SWMM_Engine engine, int idx);
+/** @brief The `FILE ` sidecar reference ("" when none). */
+SWMM_ENGINE_API int swmm_gw_init_quality_file_get(SWMM_Engine engine,
+        char* buf, int buflen);
+SWMM_ENGINE_API int swmm_gw_init_quality_file_set(SWMM_Engine engine,
+        const char* path);
+
+/* =========================================================================
+ * [GW_BOUNDARY_QUALITY]
+ * =========================================================================
+ * `kind` is "CONC", "TS", "MASSFLUX" or "HEATFLUX". A row carries either a
+ * constant value or a series name (never both).
+ */
+
+SWMM_ENGINE_API int swmm_gw_boundary_quality_count(SWMM_Engine engine);
+SWMM_ENGINE_API int swmm_gw_boundary_quality_get(SWMM_Engine engine, int idx,
+        int* cell, int* edge, char* species_buf, int species_len,
+        char* kind_buf, int kind_len, double* value,
+        char* ts_buf, int ts_len);
+/** @param edge LOCAL edge 0..nv-1 of @p cell (3 for a triangle, 4 for a quad). */
+SWMM_ENGINE_API int swmm_gw_boundary_quality_set(SWMM_Engine engine,
+        int cell, int edge, const char* species, const char* kind,
+        double value, const char* ts_name);
+SWMM_ENGINE_API int swmm_gw_boundary_quality_remove(SWMM_Engine engine, int idx);
+
+/* =========================================================================
+ * [GW_SOURCES]
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_gw_source_count(SWMM_Engine engine);
+SWMM_ENGINE_API int swmm_gw_source_get(SWMM_Engine engine, int idx,
+        char* name_buf, int name_len, int* scope, char* tag_buf, int tag_len,
+        int* cell, double* flow, char* flow_ts_buf, int flow_ts_len);
+/** @brief Append or replace the source named @p name. */
+SWMM_ENGINE_API int swmm_gw_source_set(SWMM_Engine engine, const char* name,
+        int scope, const char* tag, int cell, double flow, const char* flow_ts);
+SWMM_ENGINE_API int swmm_gw_source_remove(SWMM_Engine engine, int idx);
+
+/** @brief Species terms carried by source @p src_idx. */
+SWMM_ENGINE_API int swmm_gw_source_species_count(SWMM_Engine engine, int src_idx);
+SWMM_ENGINE_API int swmm_gw_source_species_get(SWMM_Engine engine, int src_idx,
+        int term_idx, char* species_buf, int species_len,
+        char* kind_buf, int kind_len, double* value, char* ts_buf, int ts_len);
+/** @param kind "CONC" or "MASS". Upserts on the species name. */
+SWMM_ENGINE_API int swmm_gw_source_species_set(SWMM_Engine engine, int src_idx,
+        const char* species, const char* kind, double value, const char* ts_name);
+SWMM_ENGINE_API int swmm_gw_source_species_remove(SWMM_Engine engine,
+        int src_idx, int term_idx);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* OPENSWMM_GW_TRANSPORT_H */
diff --git a/include/openswmm/engine/openswmm_heat.h b/include/openswmm/engine/openswmm_heat.h
new file mode 100644
index 000000000..736f0c90d
--- /dev/null
+++ b/include/openswmm/engine/openswmm_heat.h
@@ -0,0 +1,337 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_heat.h
+ * @brief Heat-transport configuration as an editable surface (phase H6a).
+ *
+ * @details The `model.heat` component configuration — flux-module toggles,
+ *          `[RADIATIVE_FLUXES]` parameters, and H6a's `[SOLAR_RADIATION]`
+ *          and `[CLOUD_COVER]` sections — reachable from C. This is the
+ *          header `UNIFIED_PLAN_STATUS_2026-08-29.md` §6 names as the
+ *          blocker on GUI task **G4g** (heat configuration editor).
+ *
+ * @par [HEAT_SOURCES]
+ *      The inlet-temperature table was the one section H6a left without an
+ *      API; step 3 (2026-08-30) added it below — discovery + CRUD in
+ *      `openswmm_reactions.h`'s count/get/add shape, refusing exactly what
+ *      the parser refuses.
+ *
+ * @par Edits are live
+ *      Setters mutate engine state; the flux modules re-read the config
+ *      every step, so a mid-run edit takes effect on the next routing step.
+ *      This is the same contract `openswmm_water_age.h` documents.
+ *
+ * @warning `swmm_heat_set_shortwave_mode` with
+ *          ::SWMM_HEAT_SW_COMPUTED returns ::SWMM_ERR_BADPARAM unless BOTH
+ *          latitude and longitude have been set. The engine will not fall
+ *          back on the `[TEMPERATURE]` SNOWMELT latitude: that field
+ *          defaults to 0, so borrowing it would silently model equatorial
+ *          noon (heat plan §2.5).
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §5, §6 H6a
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_HEAT_H
+#define OPENSWMM_HEAT_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Flux modules of heat plan §2, each independently toggleable. */
+typedef enum SWMM_HeatFluxModule {
+    SWMM_HEAT_SURFACE_EXCHANGE   = 0, /**< Latent + sensible (H2). */
+    SWMM_HEAT_RADIATIVE_EXCHANGE = 1, /**< Shortwave + longwave (H3). */
+    SWMM_HEAT_LAYER_CONDUCTION   = 2  /**< LID vertical conduction (H5b). */
+} SWMM_HeatFluxModule;
+
+/** @brief Where incoming shortwave comes from (plan §2.5, D-H6a-3).
+ *
+ *  The three are MUTUALLY EXCLUSIVE in EFFECT — exactly one is read, and
+ *  there is no precedence ladder behind them.
+ *
+ *  Switching modes does NOT erase the other modes' settings: a constant
+ *  stays stored while a timeseries is active, and vice versa, so a GUI can
+ *  offer three radio buttons without destroying what the user typed under
+ *  the other two. Only the selected one reaches the model. (A deck cannot
+ *  express that ambiguity at all — the parser refuses a second SHORTWAVE
+ *  row outright.) */
+typedef enum SWMM_HeatShortwaveMode {
+    SWMM_HEAT_SW_CONSTANT   = 0, /**< Fixed W/m². */
+    SWMM_HEAT_SW_TIMESERIES = 1, /**< Measured record. */
+    SWMM_HEAT_SW_COMPUTED   = 2  /**< Solar position + Bird clear-sky. */
+} SWMM_HeatShortwaveMode;
+
+/** @brief `[RADIATIVE_FLUXES]` scalar parameters. */
+typedef enum SWMM_HeatRadiativeParam {
+    SWMM_HEAT_RAD_SHORTWAVE        = 0, /**< W/m², CONSTANT mode only. */
+    SWMM_HEAT_RAD_ALBEDO           = 1, /**< Water reflectance Rs [0,1]. */
+    SWMM_HEAT_RAD_SHADE_FACTOR     = 2, /**< fs [0,1]. */
+    SWMM_HEAT_RAD_SKY_VIEW         = 3, /**< fsky [0,1]. */
+    SWMM_HEAT_RAD_EMISS_WATER      = 4, /**< εw [0,1]. */
+    SWMM_HEAT_RAD_EMISS_LANDCOVER  = 5, /**< εlc [0,1]. */
+    SWMM_HEAT_RAD_ATM_EMISS_COEFF  = 6, /**< Brunt Aa [0,1]. */
+    SWMM_HEAT_RAD_LW_REFLECTION    = 7  /**< RL [0,1]. */
+} SWMM_HeatRadiativeParam;
+
+/** @brief `[SOLAR_RADIATION]` parameters (consulted under COMPUTED only). */
+typedef enum SWMM_HeatSolarParam {
+    SWMM_HEAT_SOLAR_LATITUDE      = 0, /**< Degrees, +N, [-90, 90]. */
+    SWMM_HEAT_SOLAR_LONGITUDE     = 1, /**< Degrees, +E, [-180, 180]. */
+    SWMM_HEAT_SOLAR_TIMEZONE      = 2, /**< Hours from UTC, +E. */
+    SWMM_HEAT_SOLAR_ELEVATION     = 3, /**< Metres, [-500, 9000]. Below sea
+                                        *   level is legal. Never written =
+                                        *   take the climate state's elev. */
+    SWMM_HEAT_SOLAR_TURBIDITY_380 = 4, /**< Bird AOD at 380 nm. */
+    SWMM_HEAT_SOLAR_TURBIDITY_500 = 5, /**< Bird AOD at 500 nm. */
+    SWMM_HEAT_SOLAR_PRECIP_WATER  = 6, /**< Precipitable water, cm. */
+    SWMM_HEAT_SOLAR_OZONE         = 7, /**< Ozone column, cm. */
+    SWMM_HEAT_SOLAR_GROUND_ALBEDO = 8  /**< LAND albedo [0,1] — NOT the
+                                        *   water's SWMM_HEAT_RAD_ALBEDO. */
+} SWMM_HeatSolarParam;
+
+/** @brief `[CLOUD_COVER]` parameters. */
+typedef enum SWMM_HeatCloudParam {
+    SWMM_HEAT_CLOUD_FRACTION   = 0, /**< C [0,1], constant spelling. */
+    SWMM_HEAT_CLOUD_SW_ATTEN_K = 1, /**< Kasten–Czeplak k. */
+    SWMM_HEAT_CLOUD_SW_ATTEN_N = 2, /**< Kasten–Czeplak n. */
+    SWMM_HEAT_CLOUD_LW_CLOUD_K = 3  /**< Bolz k_lw. */
+} SWMM_HeatCloudParam;
+
+/* ---------------------------------------------------------------- toggles */
+
+/** @brief Is `[OPTIONS] HEAT_TRANSPORT` on? */
+SWMM_ENGINE_API int swmm_heat_get_enabled(SWMM_Engine engine, int* enabled);
+
+/** @brief Read one `[HEAT_FLUXES]` module toggle. */
+SWMM_ENGINE_API int swmm_heat_get_module(SWMM_Engine engine, int module,
+                                         int* on);
+/** @brief Write one `[HEAT_FLUXES]` module toggle. */
+SWMM_ENGINE_API int swmm_heat_set_module(SWMM_Engine engine, int module,
+                                         int on);
+
+/* ------------------------------------------------------------- radiative */
+
+/** @brief Read one `[RADIATIVE_FLUXES]` parameter. */
+SWMM_ENGINE_API int swmm_heat_get_radiative(SWMM_Engine engine, int param,
+                                            double* value);
+/** @brief Write one `[RADIATIVE_FLUXES]` parameter.
+ *  @returns ::SWMM_ERR_BADPARAM if a fraction is outside [0,1]; if
+ *           SHORTWAVE is negative; or if SHORTWAVE is written while the
+ *           mode is not ::SWMM_HEAT_SW_CONSTANT — a constant is not read in
+ *           the other two modes, and storing one there would look
+ *           configured while changing nothing. Switch the mode first.
+ *
+ *           Values are REFUSED, not clamped — the parser's rule, so the API
+ *           and the deck agree. A refused write does not take effect. */
+SWMM_ENGINE_API int swmm_heat_set_radiative(SWMM_Engine engine, int param,
+                                            double value);
+
+/** @brief Read the incoming-shortwave mode (::SWMM_HeatShortwaveMode). */
+SWMM_ENGINE_API int swmm_heat_get_shortwave_mode(SWMM_Engine engine,
+                                                 int* mode);
+/** @brief Set the incoming-shortwave mode.
+ *  @returns ::SWMM_ERR_BADPARAM for ::SWMM_HEAT_SW_COMPUTED when latitude
+ *           or longitude is unset, and for ::SWMM_HEAT_SW_TIMESERIES when
+ *           no series has been bound by
+ *           ::swmm_heat_set_shortwave_timeseries. */
+SWMM_ENGINE_API int swmm_heat_set_shortwave_mode(SWMM_Engine engine,
+                                                 int mode);
+
+/** @brief Bind a `[TIMESERIES]` (by name) as the shortwave record and
+ *         switch the mode to ::SWMM_HEAT_SW_TIMESERIES.
+ *  @returns ::SWMM_ERR_BADPARAM if no timeseries of that name exists. */
+SWMM_ENGINE_API int swmm_heat_set_shortwave_timeseries(SWMM_Engine engine,
+                                                       const char* name);
+
+/** @brief Name of the `[TIMESERIES]` bound as the shortwave record, or ""
+ *         when none is bound. NUL-terminated, truncated to `buflen`.
+ *  @details The read half `swmm_heat_set_shortwave_timeseries` never had —
+ *           an editor could rebind a series but only display "(keep current
+ *           series)" for the one already bound (the G4g gap, recorded
+ *           2026-08-31). Valid in every mode: the binding survives a switch
+ *           to CONSTANT or COMPUTED, exactly as the parser's does. */
+SWMM_ENGINE_API int swmm_heat_get_shortwave_timeseries(SWMM_Engine engine,
+                                                       char* buf, int buflen);
+
+/** @brief Resolved incoming shortwave at the CURRENT step, W/m², cloud
+ *         already applied. Read-only: this is state, not configuration.
+ *         0 before the first step, and whenever radiative exchange is off. */
+SWMM_ENGINE_API int swmm_heat_get_current_shortwave(SWMM_Engine engine,
+                                                    double* wm2);
+
+/* ----------------------------------------------------------------- solar */
+
+/** @brief Read one `[SOLAR_RADIATION]` parameter. */
+SWMM_ENGINE_API int swmm_heat_get_solar(SWMM_Engine engine, int param,
+                                        double* value);
+/** @brief Write one `[SOLAR_RADIATION]` parameter.
+ *  @returns ::SWMM_ERR_BADPARAM if out of range. Setting LATITUDE or
+ *           LONGITUDE also marks it as explicitly provided, which is what
+ *           ::SWMM_HEAT_SW_COMPUTED checks for. */
+SWMM_ENGINE_API int swmm_heat_set_solar(SWMM_Engine engine, int param,
+                                        double value);
+
+/** @brief Have latitude AND longitude both been explicitly set?
+ *  @details The precondition for ::SWMM_HEAT_SW_COMPUTED. A GUI should
+ *           gate the COMPUTED radio button on this rather than discovering
+ *           the refusal after the fact. */
+SWMM_ENGINE_API int swmm_heat_get_solar_sited(SWMM_Engine engine, int* sited);
+
+/* ----------------------------------------------------------------- cloud */
+
+/** @brief Is a `[CLOUD_COVER]` section in effect? */
+SWMM_ENGINE_API int swmm_heat_get_cloud_configured(SWMM_Engine engine,
+                                                   int* configured);
+
+/** @brief Read one `[CLOUD_COVER]` parameter. */
+SWMM_ENGINE_API int swmm_heat_get_cloud(SWMM_Engine engine, int param,
+                                        double* value);
+/** @brief Write one `[CLOUD_COVER]` parameter. Writing any of them marks
+ *         cloud cover as configured.
+ *  @returns ::SWMM_ERR_BADPARAM if FRACTION is outside [0,1] (it is a
+ *           fraction, not a percent) or a coefficient is negative. */
+SWMM_ENGINE_API int swmm_heat_set_cloud(SWMM_Engine engine, int param,
+                                        double value);
+
+/** @brief Bind a `[TIMESERIES]` (by name) as the cloud-fraction record.
+ *  @returns ::SWMM_ERR_BADPARAM if no timeseries of that name exists. */
+SWMM_ENGINE_API int swmm_heat_set_cloud_timeseries(SWMM_Engine engine,
+                                                   const char* name);
+
+/** @brief Name of the `[TIMESERIES]` bound as the cloud-fraction record, or
+ *         "" when none is bound. NUL-terminated, truncated to `buflen`.
+ *  @details The shortwave getter's sibling — see
+ *           ::swmm_heat_get_shortwave_timeseries. */
+SWMM_ENGINE_API int swmm_heat_get_cloud_timeseries(SWMM_Engine engine,
+                                                   char* buf, int buflen);
+
+/** @brief Clear `[CLOUD_COVER]` entirely — back to clear sky.
+ *  @details Restores the exact H3 longwave path, not an approximation of
+ *           it: the cloud factor becomes a literal 1.0 that
+ *           `atmosphericEmissivity` short-circuits. */
+SWMM_ENGINE_API int swmm_heat_clear_cloud(SWMM_Engine engine);
+
+/** @brief Cloud fraction in effect at the CURRENT step, [0,1]. Read-only. */
+SWMM_ENGINE_API int swmm_heat_get_current_cloud(SWMM_Engine engine,
+                                                double* fraction);
+
+/* -------------------------------------------------------- [HEAT_SOURCES]
+ *
+ * The per-source inlet temperature table: a GLOBAL °C for each of the seven
+ * water sources, plus NODE-scope overrides. Added for the G4g editor, which
+ * cannot round-trip a table the API cannot read.
+ *
+ * Every refusal below mirrors `HeatComponent.cpp`'s parser exactly, so a
+ * value the deck rejects is a value this API rejects, and the two cannot
+ * disagree about what a model contains. Values are REFUSED, never clamped.
+ */
+
+/** @brief `[HEAT_SOURCES]` water sources. Mirrors `openswmm::HeatSource`. */
+typedef enum SWMM_HeatSourceKind {
+    SWMM_HEAT_SRC_RAINFALL        = 0, /**< washoff runoff. */
+    SWMM_HEAT_SRC_DWF             = 1, /**< dry-weather flow. */
+    SWMM_HEAT_SRC_GW              = 2, /**< groundwater. */
+    SWMM_HEAT_SRC_RDII            = 3, /**< rainfall-derived infiltration. */
+    SWMM_HEAT_SRC_EXTERNAL_INFLOW = 4, /**< `[INFLOWS]`. */
+    SWMM_HEAT_SRC_IFACE           = 5, /**< interface file. */
+    SWMM_HEAT_SRC_INITIAL_STATE   = 6  /**< water present at t = 0. */
+} SWMM_HeatSourceKind;
+
+/** @brief Number of sources the table carries (7). Never fails on a model
+ *         with no heat configured — the table is a fixed enum extent, not a
+ *         parsed list. */
+SWMM_ENGINE_API int swmm_heat_source_count(SWMM_Engine engine, int* count);
+
+/** @brief Read one source's GLOBAL inlet temperature (°C).
+ *  @returns ::SWMM_ERR_BADINDEX for a source outside the enum. A source with
+ *           no row reads the 20 °C default — use
+ *           ::swmm_heat_get_source_configured to tell the two apart. */
+SWMM_ENGINE_API int swmm_heat_get_source_temp(SWMM_Engine engine, int source,
+                                              double* temp_c);
+
+/** @brief Write one source's GLOBAL inlet temperature (°C).
+ *  @returns ::SWMM_ERR_BADPARAM outside [-50, 100] — the parser's own range
+ *           (`HeatComponent.cpp` `parse_celsius`). REFUSED, not clamped, and
+ *           a refused write does not take effect. Marks the source
+ *           configured. */
+SWMM_ENGINE_API int swmm_heat_set_source_temp(SWMM_Engine engine, int source,
+                                              double temp_c);
+
+/** @brief Did the model set this source explicitly, or is it taking the
+ *         default? The editor needs the distinction to avoid writing rows a
+ *         user never asked for. */
+SWMM_ENGINE_API int swmm_heat_get_source_configured(SWMM_Engine engine,
+                                                    int source,
+                                                    int* configured);
+
+/** @brief Return a source to the 20 °C default and mark it unconfigured, so
+ *         the writer emits no row for it. NODE overrides are untouched —
+ *         they are separate rows and removing them silently would delete
+ *         model the caller did not name. */
+SWMM_ENGINE_API int swmm_heat_clear_source_temp(SWMM_Engine engine,
+                                                int source);
+
+/** @brief Number of NODE-scope override rows. */
+SWMM_ENGINE_API int swmm_heat_node_override_count(SWMM_Engine engine,
+                                                  int* count);
+
+/** @brief Read one NODE override by row index. Any out-pointer may be NULL. */
+SWMM_ENGINE_API int swmm_heat_get_node_override(SWMM_Engine engine, int index,
+                                                int* source, int* node,
+                                                double* temp_c);
+
+/** @brief Add or update the NODE override for (@p source, @p node).
+ *  @returns ::SWMM_ERR_BADPARAM if @p source is not DWF or EXTERNAL_INFLOW —
+ *           **the H1 scope rule, refused rather than deferred silently**, the
+ *           same answer the deck gets; if @p node is out of range; or if
+ *           @p temp_c is outside [-50, 100].
+ *  @note An existing (source, node) pair is UPDATED rather than duplicated.
+ *        The parser refuses a duplicate row because a deck cannot mean two
+ *        temperatures at once; through an API, setting the same pair twice
+ *        is an edit, and refusing it would make the editor unable to change
+ *        a value it just wrote. Same invariant — one row per pair — reached
+ *        the way each caller means it. */
+SWMM_ENGINE_API int swmm_heat_set_node_override(SWMM_Engine engine,
+                                                int source, int node,
+                                                double temp_c);
+
+/** @brief Remove one NODE override by row index. Later rows shift down, so a
+ *         caller iterating by index must re-read the count after removing. */
+SWMM_ENGINE_API int swmm_heat_remove_node_override(SWMM_Engine engine,
+                                                   int index);
+
+/** @brief The temperature @p source water actually enters @p node at (°C) —
+ *         the NODE override when one exists, else the GLOBAL value. This is
+ *         `HeatConfigData::source_temp`, exposed so a caller reads the same
+ *         resolution the engine uses rather than re-deriving the precedence
+ *         and drifting from it. */
+SWMM_ENGINE_API int swmm_heat_get_effective_source_temp(SWMM_Engine engine,
+                                                        int source, int node,
+                                                        double* temp_c);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_HEAT_H */
diff --git a/include/openswmm/engine/openswmm_hotstart.h b/include/openswmm/engine/openswmm_hotstart.h
index 7aad38cb0..c2eea6070 100644
--- a/include/openswmm/engine/openswmm_hotstart.h
+++ b/include/openswmm/engine/openswmm_hotstart.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_hotstart.h
  * @brief Hot start file management — transparent C API.
@@ -52,7 +68,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_HOTSTART_H
diff --git a/include/openswmm/engine/openswmm_infil2d.h b/include/openswmm/engine/openswmm_infil2d.h
new file mode 100644
index 000000000..0d00eca5c
--- /dev/null
+++ b/include/openswmm/engine/openswmm_infil2d.h
@@ -0,0 +1,435 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_infil2d.h
+ * @brief Per-cell infiltration for the 2D overland-flow mesh — C API.
+ *
+ * @details Implements the API surface of
+ *          `plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md` §5.5.6
+ *          (track I, step I6). This is the `GROUNDWATER OFF` infiltration path:
+ *          a per-cell loss model so surface-only 2D runs do not overestimate
+ *          pervious runoff. It supersedes the `swmm_gw2d_infil_set/get`
+ *          sketch in §8.5 — the capability ships first and owns this header;
+ *          `openswmm_gw2d.h` will refer to it rather than redeclare it.
+ *
+ *          Configuration mirrors the three input sections:
+ *
+ *          | section                      | API                                          |
+ *          |------------------------------|----------------------------------------------|
+ *          | `[2D_INFILTRATION_OPTIONS]`  | @ref swmm_infil2d_get_options / `set_options` |
+ *          | `[2D_INFILTRATION_DEFAULTS]` | the `*_default` family (tag rows, incl. `*`)  |
+ *          | `[2D_INFILTRATION]`          | the `*_cell` family (sparse per-cell override)|
+ *
+ *          **Resolution order (D-I3), most specific wins:**
+ *          `per-cell override > tag row > '*' row > no infiltration`.
+ *          Resolution happens ONCE, when the 2D surface initializes; the
+ *          solver never consults tags afterwards.
+ *
+ *          **Units — read this before touching any row.** Every value in
+ *          @ref SWMM_Infil2DRow::p is in **PROJECT UNITS** — the same number a
+ *          user types into a legacy `[INFILTRATION]` row (in/hr and in on a
+ *          US-`FLOW_UNITS` project, mm/hr and mm on an SI project). This
+ *          deliberately differs from the SI convention of the rest of the 2D
+ *          API, so that `[INFILTRATION]` and `[2D_INFILTRATION*]` cannot
+ *          disagree. The *readback* channels are the exception and are SI, as
+ *          the rest of the 2D API is: @ref swmm_infil2d_get_rate_bulk is m/s,
+ *          @ref swmm_infil2d_get_cum_bulk is m, and
+ *          @ref swmm_infil2d_get_total_volume is m³.
+ *
+ *          **Lifecycle.** The readers work in any state (see each function).
+ *          Every setter that changes parameters is rejected with
+ *          `SWMM_ERR_LIFECYCLE` unless the engine is in `SWMM_STATE_OPENED`
+ *          (or `BUILDING`) — see the "Staleness" note on
+ *          @ref swmm_infil2d_set_options.
+ *
+ *          All functions return `SWMM_ERR_BADPARAM` when the 2D module carries
+ *          no mesh, and require the engine to have been compiled with
+ *          `OPENSWMM_BUILD_2D`.
+ *
+ * @defgroup engine_infil2d 2D Infiltration API
+ * @ingroup  engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_INFIL2D_H
+#define OPENSWMM_INFIL2D_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* =========================================================================
+ * Codes and limits
+ * ========================================================================= */
+
+/** @brief Number of positional parameter columns carried per row.
+ *
+ *  Matches the widest legacy `[INFILTRATION]` method (Horton:
+ *  `f0 fmin decay dry_time Fmax`). Mirrors
+ *  `openswmm::twoD::kInfil2DMaxParams`.
+ *  @ingroup engine_infil2d */
+#define SWMM_INFIL2D_MAX_PARAMS 5
+
+/** Infiltration method codes. Mirror `openswmm::InfilModel` value-for-value
+ *  (D-I6: six methods). `CONSTANT` has no legacy `[INFILTRATION]` token — it
+ *  is 2D-only. */
+#define SWMM_INFIL2D_HORTON         0  /**< Horton. */
+#define SWMM_INFIL2D_MOD_HORTON     1  /**< Modified Horton (linear decay). */
+#define SWMM_INFIL2D_GREEN_AMPT     2  /**< Green-Ampt. */
+#define SWMM_INFIL2D_MOD_GREEN_AMPT 3  /**< Modified Green-Ampt (F not reset). */
+#define SWMM_INFIL2D_CURVE_NUMBER   4  /**< SCS curve number. */
+#define SWMM_INFIL2D_CONSTANT       5  /**< Constant rate, capacity-bounded. */
+
+/** Destination codes for infiltrated water. Mirror
+ *  `openswmm::twoD::Infil2DDest`.
+ *
+ *  D-I4: `LOST` is the only destination this release routes. The other two
+ *  exist so the grammar is stable and are rejected at validation with a
+ *  "not supported in this release" message. */
+#define SWMM_INFIL2D_DEST_LOST             0  /**< Leaves the domain; booked to the `infil_out` ledger row. */
+#define SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER 1  /**< Reserved — legacy subcatchment aquifer. */
+#define SWMM_INFIL2D_DEST_AQUIFER_2D       2  /**< Reserved — the two-zone 2D kernel. */
+
+/* =========================================================================
+ * Value types
+ * ========================================================================= */
+
+/** @brief `[2D_INFILTRATION_OPTIONS]` — POD mirror of
+ *         `openswmm::twoD::Infil2DOptions`.
+ *  @ingroup engine_infil2d */
+typedef struct SWMM_Infil2DOptions {
+    /** Evaluation cadence in SECONDS (D-I1: infiltration is a held rate,
+     *  recomputed on this cadence and held constant between updates).
+     *  `<= 0` means "use the project `WET_STEP`", which the 2D surface
+     *  resolves when it initializes. */
+    double infil_step;
+} SWMM_Infil2DOptions;
+
+/**
+ * @brief One infiltration specification — POD mirror of
+ *        `openswmm::twoD::Infil2DRow`.
+ *
+ * @details Parameters are POSITIONAL and in **PROJECT UNITS**, matching legacy
+ *          `[INFILTRATION]` exactly:
+ *
+ *          | method                        | p[0]      | p[1] | p[2]         | p[3]        | p[4] |
+ *          |-------------------------------|-----------|------|--------------|-------------|------|
+ *          | `SWMM_INFIL2D_HORTON`         | f0        | fmin | decay (1/hr) | dry_time (d)| Fmax |
+ *          | `SWMM_INFIL2D_MOD_HORTON`     | f0        | fmin | decay (1/hr) | dry_time (d)| Fmax |
+ *          | `SWMM_INFIL2D_GREEN_AMPT`     | S suction | Ks   | IMD          | —           | —    |
+ *          | `SWMM_INFIL2D_MOD_GREEN_AMPT` | S suction | Ks   | IMD          | —           | —    |
+ *          | `SWMM_INFIL2D_CURVE_NUMBER`   | CN        | —    | dry_time (d) | —           | —    |
+ *          | `SWMM_INFIL2D_CONSTANT`       | rate      | —    | —            | —           | —    |
+ *
+ *          `f0` / `fmin` / `Ks` / `rate` are in/hr (US) or mm/hr (SI); `S` and
+ *          `Fmax` are in (US) or mm (SI). `CURVE_NUMBER`'s `p[1]` is unused
+ *          and ignored, matching the legacy column layout where the middle
+ *          value is a no-op. Slots a method does not use are ignored; write 0.
+ *
+ * @ingroup engine_infil2d
+ */
+typedef struct SWMM_Infil2DRow {
+    /** 0 = `NONE` (the cell/tag has no infiltration model). When 0, every
+     *  other field is meaningless and is ignored on write. */
+    int    has_method;
+    /** One of the `SWMM_INFIL2D_*` method codes. */
+    int    method;
+    /** Positional parameters in PROJECT UNITS — see the table above. */
+    double p[SWMM_INFIL2D_MAX_PARAMS];
+    /** One of the `SWMM_INFIL2D_DEST_*` codes. Only
+     *  `SWMM_INFIL2D_DEST_LOST` is accepted in this release (D-I4). */
+    int    dest;
+} SWMM_Infil2DRow;
+
+/* =========================================================================
+ * Options — `[2D_INFILTRATION_OPTIONS]`
+ * ========================================================================= */
+
+/** @brief Get the 2D infiltration options (`INFIL_STEP`).
+ *
+ *  Valid in any state once a 2D mesh is present. Reports the AUTHORED value,
+ *  which may still be `<= 0` ("use `WET_STEP`") — the cadence the solver
+ *  actually resolved is not exposed here.
+ *
+ *  @param engine  Engine handle.
+ *  @param options Output; must not be NULL.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE` on a bad handle;
+ *           `SWMM_ERR_BADPARAM` on a NULL argument or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_options(SWMM_Engine engine,
+                                             SWMM_Infil2DOptions* options);
+
+/** @brief Set the 2D infiltration options (`INFIL_STEP`, seconds).
+ *
+ *  Persisted in `[2D_INFILTRATION_OPTIONS]` on save.
+ *
+ *  **Staleness (applies to every setter in this header).** Infiltration
+ *  parameters are baked into per-cell Horton / Green-Ampt / curve-number
+ *  kernel state ONCE, when the 2D surface initializes. The only re-entry
+ *  point rebuilds that state for the WHOLE mesh and zeroes the per-cell
+ *  cumulative-depth array, which would discard the integration history of
+ *  every cell the caller never touched and desynchronize the `infil_out`
+ *  ledger row. Rather than corrupt a run, parameter setters are **rejected
+ *  after initialize()**: they return `SWMM_ERR_LIFECYCLE` unless the engine is
+ *  in `SWMM_STATE_OPENED` (the state the GUI edits in) or the programmatic
+ *  `BUILDING` state. Re-open or re-initialize to apply a change.
+ *
+ *  @param engine  Engine handle.
+ *  @param options New options; must not be NULL. `infil_step <= 0` selects
+ *                 the project `WET_STEP`; non-finite values are rejected.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on a NULL /
+ *           non-finite argument or when no 2D mesh exists;
+ *           `SWMM_ERR_LIFECYCLE` when called after initialize().
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_set_options(SWMM_Engine engine,
+                                             const SWMM_Infil2DOptions* options);
+
+/* =========================================================================
+ * Tag defaults — `[2D_INFILTRATION_DEFAULTS]`
+ * ========================================================================= */
+
+/** @brief Number of authored tag-default rows, including the `'*'` row.
+ *
+ *  The `*_count` companion for @ref swmm_infil2d_get_default /
+ *  @ref swmm_infil2d_get_default_tag.
+ *
+ *  @param engine Engine handle.
+ *  @param count  Output row count (0 when the model authors no defaults).
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on NULL
+ *           @p count or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_defaults_count(SWMM_Engine engine, int* count);
+
+/** @brief Read one tag-default row by index.
+ *
+ *  Row parameters are in **PROJECT UNITS** — see @ref SWMM_Infil2DRow.
+ *  Pair with @ref swmm_infil2d_get_default_tag to learn which tag the row
+ *  belongs to.
+ *
+ *  @param engine Engine handle.
+ *  @param idx    Row index in `[0, swmm_infil2d_defaults_count)`.
+ *  @param row    Output row; must not be NULL.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADINDEX` on an out-of-range index;
+ *           `SWMM_ERR_BADPARAM` on NULL @p row or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_default(SWMM_Engine engine, int idx,
+                                             SWMM_Infil2DRow* row);
+
+/** @brief Read the TAG of one default row by index.
+ *
+ *  Copies up to `buflen-1` bytes into @p buf and always NUL-terminates
+ *  (the `swmm_2d_get_triangle_tag` convention). `"*"` identifies the
+ *  mesh-wide fallback row.
+ *
+ *  @param engine Engine handle.
+ *  @param idx    Row index in `[0, swmm_infil2d_defaults_count)`.
+ *  @param buf    Caller-allocated output buffer.
+ *  @param buflen Capacity of @p buf in bytes; must be > 0.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADINDEX`; `SWMM_ERR_BADPARAM`.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_default_tag(SWMM_Engine engine, int idx,
+                                                 char* buf, int buflen);
+
+/** @brief Add or replace the default row for a tag.
+ *
+ *  Upsert semantics: any existing rows carrying @p tag are removed and one
+ *  row is appended, so a tag never has two definitions. Pass `"*"` to set the
+ *  mesh-wide fallback. A row with `has_method == 0` (`NONE`) is meaningful and
+ *  is stored — for a tag it deliberately CLEARS the `'*'` default for that
+ *  tag's cells.
+ *
+ *  Row parameters are in **PROJECT UNITS** — see @ref SWMM_Infil2DRow.
+ *  Persisted in `[2D_INFILTRATION_DEFAULTS]` on save. Subject to the
+ *  staleness rule documented on @ref swmm_infil2d_set_options.
+ *
+ *  @param engine Engine handle.
+ *  @param tag    Tag to define; must be non-empty.
+ *  @param row    Row to store; must not be NULL.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on a NULL /
+ *           empty tag, a NULL row, an unknown method code, a destination
+ *           other than `SWMM_INFIL2D_DEST_LOST`, an out-of-range parameter,
+ *           or when no 2D mesh exists; `SWMM_ERR_LIFECYCLE` after
+ *           initialize().
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_set_default(SWMM_Engine engine,
+                                             const char* tag,
+                                             const SWMM_Infil2DRow* row);
+
+/** @brief Remove every default row carrying a tag.
+ *
+ *  Removing the `'*'` row leaves cells with no tag row resolving to no
+ *  infiltration. Subject to the staleness rule documented on
+ *  @ref swmm_infil2d_set_options.
+ *
+ *  @param engine Engine handle.
+ *  @param tag    Tag to remove; must be non-empty.
+ *  @returns `SWMM_OK` (also when the tag was not present);
+ *           `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on a NULL / empty tag
+ *           or when no 2D mesh exists; `SWMM_ERR_LIFECYCLE` after
+ *           initialize().
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_remove_default(SWMM_Engine engine,
+                                                const char* tag);
+
+/* =========================================================================
+ * Per-cell overrides — `[2D_INFILTRATION]`
+ * ========================================================================= */
+
+/** @brief Read the infiltration specification in force at one triangle.
+ *
+ *  Row parameters are in **PROJECT UNITS** — see @ref SWMM_Infil2DRow.
+ *
+ *  Behaviour depends on whether the 2D surface has resolved yet:
+ *
+ *  - **After initialize()** the RESOLVED row is reported (D-I3 precedence
+ *    already applied) and `*is_override` is 1 exactly when the resolved
+ *    provenance is the per-cell `[2D_INFILTRATION]` layer.
+ *  - **Before initialize()** only the per-cell override layer is visible, so
+ *    the authored override for @p tri is reported with `*is_override == 1`,
+ *    and a cell with no override reports `has_method == 0` with
+ *    `*is_override == 0` even when a tag or `'*'` default would later apply.
+ *    Combine with @ref swmm_infil2d_get_default and the triangle's tag
+ *    (`swmm_2d_get_triangle_tag`) to preview the resolution in that state.
+ *
+ *  @param engine      Engine handle.
+ *  @param tri         Triangle index (0-based) in `[0, triangle_count)`.
+ *  @param row         Output row; must not be NULL.
+ *  @param is_override Output flag, 1 / 0. May be NULL.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADINDEX` on an out-of-range triangle;
+ *           `SWMM_ERR_BADPARAM` on NULL @p row or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_cell(SWMM_Engine engine, int tri,
+                                          SWMM_Infil2DRow* row,
+                                          int* is_override);
+
+/** @brief Set (or clear) the per-cell `[2D_INFILTRATION]` override of one
+ *         triangle.
+ *
+ *  Row parameters are in **PROJECT UNITS** — see @ref SWMM_Infil2DRow.
+ *  Passing `row == NULL` CLEARS the override, so the cell falls back to its
+ *  tag row / the `'*'` row / no infiltration. Passing a row with
+ *  `has_method == 0` is different: it stores an explicit `NONE` override,
+ *  which suppresses the tag and `'*'` defaults for that cell.
+ *
+ *  Persisted as one `[2D_INFILTRATION]` row on save. Subject to the staleness
+ *  rule documented on @ref swmm_infil2d_set_options.
+ *
+ *  @param engine Engine handle.
+ *  @param tri    Triangle index (0-based) in `[0, triangle_count)`.
+ *  @param row    Row to store, or NULL to clear the override.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADINDEX` on an out-of-range triangle;
+ *           `SWMM_ERR_BADPARAM` on an invalid row or when no 2D mesh exists;
+ *           `SWMM_ERR_LIFECYCLE` after initialize().
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_set_cell(SWMM_Engine engine, int tri,
+                                          const SWMM_Infil2DRow* row);
+
+/** @brief Assign one specification to many triangles in a single call.
+ *
+ *  The GUI's select-many-cells-then-assign entry point: one validation pass,
+ *  then one apply. **All-or-nothing** — the row and EVERY entry of @p tris are
+ *  validated first, and if any triangle index is out of range (or the row is
+ *  invalid) nothing at all is written. Duplicate indices are tolerated; the
+ *  cell simply ends up with the one row.
+ *
+ *  Row parameters are in **PROJECT UNITS** — see @ref SWMM_Infil2DRow.
+ *  Passing `row == NULL` clears the override on every listed triangle, with
+ *  the same all-or-nothing contract. Subject to the staleness rule documented
+ *  on @ref swmm_infil2d_set_options.
+ *
+ *  @param engine Engine handle.
+ *  @param tris   Caller-owned array of `n` 0-based triangle indices.
+ *  @param n      Number of entries in @p tris; must be > 0.
+ *  @param row    Row to store on every listed triangle, or NULL to clear.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADINDEX` when any entry of @p tris is out
+ *           of range (nothing applied); `SWMM_ERR_BADPARAM` on a NULL @p tris,
+ *           `n <= 0`, an invalid row, or when no 2D mesh exists;
+ *           `SWMM_ERR_LIFECYCLE` after initialize().
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_set_cells(SWMM_Engine engine,
+                                           const int* tris, int n,
+                                           const SWMM_Infil2DRow* row);
+
+/* =========================================================================
+ * State readback (SI, like the rest of the 2D API)
+ * ========================================================================= */
+
+/** @brief Bulk get the held per-cell infiltration rate (m/s, >= 0).
+ *
+ *  This is the rate the marcher is consuming — recomputed on the `INFIL_STEP`
+ *  cadence and held constant between updates (D-I1), NOT re-evaluated per
+ *  sub-step. Values are SI regardless of the project unit system.
+ *
+ *  Fills `min(n, triangle_count)` entries. A mesh with no resolved
+ *  infiltration model is a legitimate configuration, not an error: the buffer
+ *  is zero-filled and `SWMM_OK` is returned.
+ *
+ *  @param engine Engine handle.
+ *  @param f      Caller-allocated output buffer of at least @p n doubles.
+ *  @param n      Capacity of @p f; must be > 0.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on a NULL
+ *           buffer, `n <= 0`, or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_rate_bulk(SWMM_Engine engine,
+                                               double* f, int n);
+
+/** @brief Bulk get the cumulative infiltrated depth per cell (m).
+ *
+ *  The `infil_cum` sidecar variable: the running time-integral of the loss the
+ *  solver actually applied (the held rate after the wet/dry depth ramp), so
+ *  `sum(F[i] * cell_area[i])` equals @ref swmm_infil2d_get_total_volume.
+ *  Values are SI regardless of the project unit system.
+ *
+ *  Fills `min(n, triangle_count)` entries, and zero-fills + returns `SWMM_OK`
+ *  when no infiltration model is resolved (same contract as
+ *  @ref swmm_infil2d_get_rate_bulk).
+ *
+ *  @param engine Engine handle.
+ *  @param F      Caller-allocated output buffer of at least @p n doubles.
+ *  @param n      Capacity of @p F; must be > 0.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on a NULL
+ *           buffer, `n <= 0`, or when no 2D mesh exists.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_cum_bulk(SWMM_Engine engine,
+                                              double* F, int n);
+
+/** @brief Get the cumulative 2D infiltration loss (m³) — the `infil_out`
+ *         mass-balance ledger row.
+ *
+ *  The whole-domain companion to @ref swmm_infil2d_get_cum_bulk, reported
+ *  beside `evap_out` in the continuity report. Reads the same ledger as
+ *  @ref swmm_2d_get_mass_balance and, like it, requires the 2D mass balance
+ *  to be live.
+ *
+ *  @param engine Engine handle.
+ *  @param volume Output volume in m³; must not be NULL.
+ *  @returns `SWMM_OK`; `SWMM_ERR_BADHANDLE`; `SWMM_ERR_BADPARAM` on NULL
+ *           @p volume or when the 2D mass balance is not active.
+ *  @ingroup engine_infil2d */
+SWMM_ENGINE_API int swmm_infil2d_get_total_volume(SWMM_Engine engine,
+                                                  double* volume);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* OPENSWMM_INFIL2D_H */
diff --git a/include/openswmm/engine/openswmm_inflows.h b/include/openswmm/engine/openswmm_inflows.h
index 112d34a01..4c60d54de 100644
--- a/include/openswmm/engine/openswmm_inflows.h
+++ b/include/openswmm/engine/openswmm_inflows.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_inflows.h
  * @brief OpenSWMM Engine — Inflows (External, DWF, RDII) C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INFLOWS_H
@@ -35,7 +51,12 @@ extern "C" {
  *
  * @param engine     Engine handle.
  * @param node_idx   Zero-based index of the receiving node.
- * @param constituent Constituent name ("FLOW" for flow, or a pollutant name).
+ * @param constituent Constituent name ("FLOW" for flow, a pollutant name,
+ *                   or the reserved species "__WATER_AGE__" — such a row
+ *                   prescribes the AGE, in HOURS, carried by the node's
+ *                   external inflow water, and wins over the
+ *                   [WATER_AGE_SOURCES] EXTERNAL_INFLOW entry (Z1,
+ *                   amendment D-Y4). It adds no water and no mass.
  * @param ts_name    Time series name (NULL or "" for constant baseline only).
  * @param type       Inflow type: "FLOW", "CONCEN", or "MASS".
  * @param m_factor   Multiplier applied to the time series values.
diff --git a/include/openswmm/engine/openswmm_infrastructure.h b/include/openswmm/engine/openswmm_infrastructure.h
index 529372902..2e6b399b7 100644
--- a/include/openswmm/engine/openswmm_infrastructure.h
+++ b/include/openswmm/engine/openswmm_infrastructure.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_infrastructure.h
  * @brief OpenSWMM Engine — Infrastructure (Transects, Streets, Inlets, LIDs) C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INFRASTRUCTURE_H
@@ -287,6 +303,25 @@ SWMM_ENGINE_API int swmm_transect_remove(SWMM_Engine engine, int idx);
  */
 SWMM_ENGINE_API int swmm_street_add(SWMM_Engine engine, const char* id);
 
+/**
+ * @brief Rename a street cross-section in place.
+ *
+ * @details Unlike the other named infrastructure objects, a street is
+ *          referenced BY NAME after parsing: STREET_XSECT links carry it in
+ *          their named cross-section slot, which @ref swmm_link_get_xsect
+ *          resolves and the .inp writer emits as [XSECTIONS] Geom1. This call
+ *          rewrites every such reference, so renaming cannot leave a link
+ *          pointing at a street that no longer exists.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Street index.
+ * @param new_id  New unique name (non-empty), compared case-insensitively
+ *                against the other streets. A pure case-respelling of this
+ *                same street is allowed.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.
+ */
+SWMM_ENGINE_API int swmm_street_rename(SWMM_Engine engine, int idx, const char* new_id);
+
 /**
  * @brief Set the geometric parameters for a street cross-section.
  *
@@ -371,6 +406,21 @@ SWMM_ENGINE_API int swmm_street_get_params(SWMM_Engine engine, int idx,
  */
 SWMM_ENGINE_API int swmm_inlet_add(SWMM_Engine engine, const char* id, const char* type);
 
+/**
+ * @brief Rename an inlet design in place.
+ *
+ * @details [INLET_USAGE] rows hold an inlet INDEX, not a name, so usages
+ *          follow automatically.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Inlet index.
+ * @param new_id  New unique name (non-empty), compared case-insensitively
+ *                against the other inlets. A pure case-respelling of this
+ *                same inlet is allowed.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.
+ */
+SWMM_ENGINE_API int swmm_inlet_rename(SWMM_Engine engine, int idx, const char* new_id);
+
 /**
  * @brief Set the geometric parameters for an inlet.
  * @param engine        Engine handle.
@@ -443,6 +493,174 @@ SWMM_ENGINE_API int swmm_inlet_get_params(SWMM_Engine engine, int idx,
  */
 SWMM_ENGINE_API int swmm_inlet_get_type(SWMM_Engine engine, int idx, char* buf, int buflen);
 
+/* -------------------------------------------------------------------------
+ * Full inlet-design surface (2026-09-05). swmm_inlet_set_params/get_params
+ * above remain as a GRATE/SLOTTED convenience; the struct API below covers
+ * every field of the [INLETS] grammar including curb height, throat angle,
+ * combination inlets and custom capture curves.
+ * ------------------------------------------------------------------------- */
+
+/** Inlet design type codes (match legacy InletType ordering). */
+enum SWMM_InletType {
+    SWMM_INLET_GRATE      = 0,
+    SWMM_INLET_CURB       = 1,
+    SWMM_INLET_COMBO      = 2,
+    SWMM_INLET_SLOTTED    = 3,
+    SWMM_INLET_DROP_GRATE = 4,
+    SWMM_INLET_DROP_CURB  = 5,
+    SWMM_INLET_CUSTOM     = 6
+};
+
+/** Grate bar patterns (HEC-22). */
+enum SWMM_GrateType {
+    SWMM_GRATE_P_BAR_50     = 0,
+    SWMM_GRATE_P_BAR_50x100 = 1,
+    SWMM_GRATE_P_BAR_30     = 2,
+    SWMM_GRATE_CURVED_VANE  = 3,
+    SWMM_GRATE_TILT_BAR_45  = 4,
+    SWMM_GRATE_TILT_BAR_30  = 5,
+    SWMM_GRATE_RETICULINE   = 6,
+    SWMM_GRATE_GENERIC      = 7
+};
+
+/** Curb-opening throat orientation (legacy ThroatAngleWords order). */
+enum SWMM_ThroatType {
+    SWMM_THROAT_HORIZONTAL = 0,
+    SWMM_THROAT_INCLINED   = 1,
+    SWMM_THROAT_VERTICAL   = 2
+};
+
+/** Custom-inlet curve kind. */
+enum SWMM_InletCurveKind {
+    SWMM_INLET_CURVE_NONE      = 0,
+    SWMM_INLET_CURVE_DIVERSION = 1,  /**< captured flow vs approach flow */
+    SWMM_INLET_CURVE_RATING    = 2   /**< captured flow vs water depth */
+};
+
+/** Inlet placement mode. */
+enum SWMM_InletPlacement {
+    SWMM_INLET_AUTOMATIC = 0,
+    SWMM_INLET_ON_GRADE  = 1,
+    SWMM_INLET_ON_SAG    = 2
+};
+
+/**
+ * @brief Complete description of an inlet design. All dimensions are in the
+ *        project's display units (ft or m; ft/s or m/s).
+ */
+typedef struct SWMM_InletDesign {
+    int    type;          /**< SWMM_InletType */
+    /* GRATE / DROP_GRATE / COMBO */
+    double grate_length;
+    double grate_width;
+    int    grate_type;    /**< SWMM_GrateType */
+    double open_area;     /**< GENERIC only, fraction (0,1] */
+    double splash_veloc;  /**< GENERIC only */
+    /* CURB / DROP_CURB / COMBO */
+    double curb_length;
+    double curb_height;
+    int    throat;        /**< SWMM_ThroatType (ignored for DROP_CURB) */
+    /* SLOTTED */
+    double slot_length;
+    double slot_width;
+    /* CUSTOM */
+    char   curve_id[64];
+    int    curve_kind;    /**< SWMM_InletCurveKind */
+} SWMM_InletDesign;
+
+/**
+ * @brief Read every field of an inlet design.
+ * @param engine  Engine handle.
+ * @param idx     Zero-based inlet index.
+ * @param[out] out  Receives the design (must not be NULL).
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_inlet_get_design(SWMM_Engine engine, int idx, SWMM_InletDesign* out);
+
+/**
+ * @brief Overwrite every field of an inlet design (type may change).
+ * @details Validation: lengths/widths/heights used by `type` must be > 0;
+ *          open_area in (0,1] when grate_type is GENERIC; CUSTOM requires a
+ *          non-empty curve_id. BUILDING or OPENED state.
+ *
+ *          CUSTOM curve_kind: the [INLETS] grammar has no kind token, so the
+ *          named curve's own table type is the authority. If the curve already
+ *          exists, the kind is taken from it and a contradicting `curve_kind`
+ *          (or a curve that is neither DIVERSION nor RATING) is rejected with
+ *          SWMM_ERR_BADPARAM; if it does not exist yet, `curve_kind` is stored
+ *          as given and re-derived when the model is validated.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM on a violated constraint.
+ */
+SWMM_ENGINE_API int swmm_inlet_set_design(SWMM_Engine engine, int idx, const SWMM_InletDesign* design);
+
+/**
+ * @brief Get/set the free-text description of an inlet design.
+ */
+SWMM_ENGINE_API int swmm_inlet_get_comment(SWMM_Engine engine, int idx, char* buf, int buflen);
+SWMM_ENGINE_API int swmm_inlet_set_comment(SWMM_Engine engine, int idx, const char* text);
+
+/* -------------------------------------------------------------------------
+ * Inlet usage rows — one per placement. Two host kinds:
+ *   host_kind = SWMM_INLET_HOST_LINK : a conduit ([INLET_USAGE] row)
+ *   host_kind = SWMM_INLET_HOST_NODE : an inlet junction ([INLET_JUNCTIONS] row)
+ * ------------------------------------------------------------------------- */
+
+enum SWMM_InletHostKind {
+    SWMM_INLET_HOST_LINK = 0,
+    SWMM_INLET_HOST_NODE = 1
+};
+
+typedef struct SWMM_InletUsage {
+    int    host_kind;        /**< SWMM_InletHostKind */
+    int    host_idx;         /**< link index or node index per host_kind */
+    int    design_idx;       /**< inlet design index */
+    int    capture_node_idx; /**< receiving (underdrain) node index */
+    int    num_inlets;       /**< inlets per side (>= 1) */
+    double pct_clogged;      /**< 0..99 */
+    double flow_limit;       /**< max capture per inlet, display flow units; 0 = none */
+    double local_depress;    /**< local gutter depression, display length units */
+    double local_width;      /**< local depression width, display length units */
+    int    placement;        /**< SWMM_InletPlacement */
+} SWMM_InletUsage;
+
+/** @returns number of usage rows (both host kinds), or -1 on error. */
+SWMM_ENGINE_API int swmm_inlet_usage_count(SWMM_Engine engine);
+
+/** @returns usage row index hosted by conduit `link_idx`, or -1 if none / error. */
+SWMM_ENGINE_API int swmm_inlet_usage_find_link(SWMM_Engine engine, int link_idx);
+
+/** @returns usage row index hosted by inlet-junction node `node_idx`, or -1 if none / error. */
+SWMM_ENGINE_API int swmm_inlet_usage_find_node(SWMM_Engine engine, int node_idx);
+
+/**
+ * @brief Read a usage row.
+ * @returns SWMM_OK, SWMM_ERR_BADINDEX, or SWMM_ERR_BADPARAM (NULL out).
+ */
+SWMM_ENGINE_API int swmm_inlet_usage_get(SWMM_Engine engine, int usage_idx, SWMM_InletUsage* out);
+
+/**
+ * @brief Create or replace the usage row for a host.
+ * @details At most one row per host: if a row already exists for
+ *          (host_kind, host_idx) it is overwritten, otherwise a row is
+ *          appended. Validation: design_idx and capture_node_idx must exist;
+ *          capture node must not be the host node, nor a virtual/inlet
+ *          junction; a link host must be a conduit; a node host must have
+ *          is_inlet set (see swmm_node_set_inlet); num_inlets >= 1;
+ *          pct_clogged in [0,99]. Shape compatibility (STREET vs drop) is
+ *          checked here and reported as ERR_INLET_USAGE_SHAPE (635).
+ *          BUILDING or OPENED state.
+ * @param[out] usage_idx  Receives the row index (may be NULL).
+ * @returns SWMM_OK, SWMM_ERR_BADINDEX / SWMM_ERR_BADPARAM, or 635.
+ */
+SWMM_ENGINE_API int swmm_inlet_usage_set(SWMM_Engine engine, const SWMM_InletUsage* usage, int* usage_idx);
+
+/**
+ * @brief Remove a usage row. Removing the row of an inlet junction leaves the
+ *        node flagged is_inlet; the model then fails validation with 633
+ *        until a design is assigned or the node is demoted.
+ */
+SWMM_ENGINE_API int swmm_inlet_usage_remove(SWMM_Engine engine, int usage_idx);
+
 /* =========================================================================
  * LID controls
  * ========================================================================= */
@@ -461,6 +679,24 @@ SWMM_ENGINE_API int swmm_inlet_get_type(SWMM_Engine engine, int idx, char* buf,
  */
 SWMM_ENGINE_API int swmm_lid_add(SWMM_Engine engine, const char* id, int type);
 
+/**
+ * @brief Rename an LID control in place.
+ *
+ * @details Updates both the name vector (read by swmm_lid_id() and the
+ *          [LID_CONTROLS] writer) and the name registry (read by
+ *          swmm_lid_index() and the [LID_USAGE] writer). Usage rows hold an
+ *          LID INDEX, so subcatchment deployments follow automatically.
+ *          Lifecycle: BUILDING or OPENED.
+ *
+ * @param engine  Engine handle.
+ * @param idx     LID control index.
+ * @param new_id  New unique name (non-empty). A pure case-respelling of this
+ *                same control is allowed.
+ * @returns SWMM_OK, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or
+ *          SWMM_ERR_BADPARAM on an empty or duplicate name.
+ */
+SWMM_ENGINE_API int swmm_lid_rename(SWMM_Engine engine, int idx, const char* new_id);
+
 /**
  * @brief Set the surface layer properties for a LID control.
  * @param engine     Engine handle.
diff --git a/include/openswmm/engine/openswmm_initial_quality.h b/include/openswmm/engine/openswmm_initial_quality.h
new file mode 100644
index 000000000..6cff5d3fd
--- /dev/null
+++ b/include/openswmm/engine/openswmm_initial_quality.h
@@ -0,0 +1,127 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_initial_quality.h
+ * @brief C API — [INITIAL_QUALITY] per-element initial concentrations (E-A4).
+ *
+ * @details Row-based surface over the section store, mirroring the
+ *          swmm_ext_inflow_* family: entries are indexed 0..count-1 in file
+ *          order, `set` is an UPSERT keyed on (is_link, elem_idx,
+ *          constituent), and `remove` deletes by entry index (subsequent
+ *          entries shift down by one).
+ *
+ *          Constituent is a name: a [POLLUTANTS] pollutant, or the reserved
+ *          species "__WATER_AGE__" (value in HOURS, signed) or
+ *          "__TEMPERATURE__" (value in degC). Pollutant values are
+ *          concentrations in the pollutant's own units and must be
+ *          non-negative.
+ *
+ *          Rows only seed state at initialize(), so mutation is guarded to
+ *          the editable states (BUILDING/OPENED) — the same contract as
+ *          swmm_pollutant_set_init_conc.
+ *
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_INITIAL_QUALITY_H
+#define OPENSWMM_INITIAL_QUALITY_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Number of [INITIAL_QUALITY] entries.
+ * @param engine Engine handle.
+ * @return Entry count, or -1 on a bad handle.
+ */
+SWMM_ENGINE_API int swmm_init_quality_count(SWMM_Engine engine);
+
+/**
+ * @brief Read one entry.
+ * @param engine           Engine handle.
+ * @param entry_idx        Entry index (0..count-1).
+ * @param is_link          [out] 0 = node row, 1 = link row.
+ * @param elem_idx         [out] Resolved node/link index (-1 if unresolved).
+ * @param constituent_buf  [out] Constituent name (NUL-terminated).
+ * @param constituent_len  Buffer size in bytes.
+ * @param value            [out] Raw value (pollutant units / hours / degC).
+ * @return SWMM_OK, SWMM_ERR_BADINDEX, or SWMM_ERR_BADPARAM.
+ */
+SWMM_ENGINE_API int swmm_init_quality_get(SWMM_Engine engine, int entry_idx,
+                                          int* is_link, int* elem_idx,
+                                          char* constituent_buf,
+                                          int constituent_len, double* value);
+
+/**
+ * @brief Upsert one entry keyed on (is_link, elem_idx, constituent).
+ * @details BUILDING/OPENED only. Unknown constituent name, bad element
+ *          index, or a negative pollutant value returns SWMM_ERR_BADPARAM.
+ *          (Negative values are legal for "__WATER_AGE__" and
+ *          "__TEMPERATURE__".)
+ * @param engine       Engine handle.
+ * @param is_link      0 = node row, 1 = link row.
+ * @param elem_idx     Node/link index.
+ * @param constituent  Pollutant name or reserved species name.
+ * @param value        Raw value (pollutant units / hours / degC).
+ * @return SWMM_OK, SWMM_ERR_LIFECYCLE, SWMM_ERR_BADINDEX, or
+ *         SWMM_ERR_BADPARAM.
+ */
+SWMM_ENGINE_API int swmm_init_quality_set(SWMM_Engine engine, int is_link,
+                                          int elem_idx,
+                                          const char* constituent,
+                                          double value);
+
+/**
+ * @brief Remove the entry at @p entry_idx. Subsequent entries shift down by
+ *        one — callers holding cached indices must re-enumerate.
+ * @details BUILDING/OPENED only.
+ * @return SWMM_OK, SWMM_ERR_LIFECYCLE, or SWMM_ERR_BADINDEX.
+ */
+SWMM_ENGINE_API int swmm_init_quality_remove(SWMM_Engine engine,
+                                             int entry_idx);
+
+/* ---- U2 (2026-09-07): the `[INITIAL_QUALITY] FILE ` sidecar --------
+ * Rows read from the sidecar carry is_file = 1 in swmm_init_quality_is_file
+ * and are not written back inline; the FILE line is. The CSV format is
+ * scope,element,constituent,value per line (comma / whitespace separated,
+ * optional header). The file is read at the next open; set/clear here only
+ * records the reference.
+ */
+
+/** @brief The FILE path as written ("" when none). */
+SWMM_ENGINE_API int swmm_init_quality_file_get(SWMM_Engine engine, char* buf, int buflen);
+
+/** @brief Set (or clear with "" / NULL) the FILE reference. */
+SWMM_ENGINE_API int swmm_init_quality_file_set(SWMM_Engine engine, const char* path);
+
+/** @brief 1 when row @p entry_idx was loaded from the FILE sidecar, else 0. */
+SWMM_ENGINE_API int swmm_init_quality_is_file(SWMM_Engine engine, int entry_idx);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_INITIAL_QUALITY_H */
diff --git a/include/openswmm/engine/openswmm_links.h b/include/openswmm/engine/openswmm_links.h
index f6a83c422..dbb8665ab 100644
--- a/include/openswmm/engine/openswmm_links.h
+++ b/include/openswmm/engine/openswmm_links.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_links.h
  * @brief OpenSWMM Engine — Link (conduit/pump/orifice/weir/outlet) C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_LINKS_H
@@ -187,6 +203,22 @@ SWMM_ENGINE_API int swmm_link_get_from_node(SWMM_Engine engine, int idx, int* no
  */
 SWMM_ENGINE_API int swmm_link_get_to_node(SWMM_Engine engine, int idx, int* node_idx);
 
+/**
+ * @brief Restore authored From/To orientation on every conduit the parser
+ *        reversed for adverse slope (DYNWAVE/FV routing).
+ *
+ * @details At open, adverse-slope conduits have node1/node2, offset1/offset2,
+ *          initial flow sign and inlet/outlet losses swapped in place. An
+ *          editing host that displays and saves the live context should call
+ *          this once after open so the user sees and edits the orientation
+ *          they authored. Not needed for simulation-only hosts. The .inp
+ *          writer undoes the reversal on its own regardless.
+ * @param engine      Engine handle.
+ * @param[out] count  Optional; receives the number of conduits restored.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_links_restore_authored_orientation(SWMM_Engine engine, int* count);
+
 /* =========================================================================
  * Geometry setters (BUILDING or OPENED)
  * ========================================================================= */
@@ -596,6 +628,19 @@ SWMM_ENGINE_API int swmm_link_get_capacity(SWMM_Engine engine, int idx, double*
  */
 SWMM_ENGINE_API int swmm_link_get_volume(SWMM_Engine engine, int idx, double* volume);
 
+/**
+ * @brief Get the portion of a link's stored volume held in the Preissmann slot.
+ * @details Finite-volume routing only: the water standing above the pipe crown
+ *          in the slot (`sum over cells of max(0, A - A_crown) * dx`). Always a
+ *          subset of @ref swmm_link_get_volume; reads 0.0 under the dynamic-wave
+ *          router and whenever the conduit is below its crown.
+ * @param engine       Engine handle.
+ * @param idx          Zero-based link index.
+ * @param[out] volume  Receives the slot volume in project volume units.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_link_get_slot_volume(SWMM_Engine engine, int idx, double* volume);
+
 /* --- Runtime forcing (RUNNING state only) --- */
 
 /**
@@ -904,6 +949,21 @@ SWMM_ENGINE_API int swmm_link_get_stat_max_velocity(SWMM_Engine engine, int idx,
  */
 SWMM_ENGINE_API int swmm_link_get_stat_max_filling(SWMM_Engine engine, int idx, double* val);
 
+/**
+ * @brief Peak instantaneous Preissmann-slot storage share of a link.
+ * @details FV routing only: max over the run of slot_volume/volume (0..1).
+ *          Reads 0.0 under the dynamic-wave router.
+ */
+SWMM_ENGINE_API int swmm_link_get_stat_peak_slot_share(SWMM_Engine engine, int idx, double* val);
+
+/**
+ * @brief Run-level Preissmann-slot storage share of a link.
+ * @details FV routing only: the ratio of time integrals
+ *          (∫ slot_volume dt)/(∫ volume dt) over the run (0..1) — never an
+ *          average of instantaneous ratios. Reads 0.0 under dynamic wave.
+ */
+SWMM_ENGINE_API int swmm_link_get_stat_slot_share(SWMM_Engine engine, int idx, double* val);
+
 /**
  * @brief Get the total volume conveyed through a link.
  * @param engine    Engine handle.
diff --git a/include/openswmm/engine/openswmm_massbalance.h b/include/openswmm/engine/openswmm_massbalance.h
index 4f61932a2..1876ea4f4 100644
--- a/include/openswmm/engine/openswmm_massbalance.h
+++ b/include/openswmm/engine/openswmm_massbalance.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_massbalance.h
  * @brief OpenSWMM Engine — Mass Balance / Continuity C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_MASSBALANCE_H
@@ -48,7 +64,9 @@ typedef enum SWMM_RunoffTotal {
     SWMM_RUNOFF_RUNOFF     = 3, /**< Cumulative surface runoff volume. */
     SWMM_RUNOFF_SNOWREMOV  = 4, /**< Cumulative snow removal volume. */
     SWMM_RUNOFF_INITSTORE  = 5, /**< Initial surface storage volume. */
-    SWMM_RUNOFF_FINALSTORE = 6  /**< Final surface storage volume. */
+    SWMM_RUNOFF_FINALSTORE = 6, /**< Final surface storage volume. */
+    SWMM_RUNOFF_INITSNOW   = 7, /**< Initial snow cover volume (SWE + free water). */
+    SWMM_RUNOFF_FINALSNOW  = 8  /**< Final snow cover volume (SWE + free water). */
 } SWMM_RunoffTotal;
 
 /** @brief Routing mass balance component codes. */
@@ -73,6 +91,32 @@ typedef enum SWMM_RoutingTotal {
                                        *   counts INP `[INFLOWS]`-derived,
                                        *   interface-file, and 2D-coupling
                                        *   inflow (issue #113). */
+    ,
+    SWMM_ROUTING_LINK_GW_INFLOW = 13 /**< G-X4 (2026-09-20): cumulative volume
+                                       *   the two-zone [2D_AQUIFER] handed to
+                                       *   conduits below the water table
+                                       *   (gaining reaches). The negative half
+                                       *   of the signed conduit seepage; the
+                                       *   losing half stays
+                                       *   SWMM_ROUTING_SEEP_LOSS. */
+    ,
+    SWMM_ROUTING_COUPLING_OUT = 12   /**< C2 (2026-09-07): cumulative volume
+                                       *   the 1D→2D coupling spill removed
+                                       *   from coupled nodes.
+                                       *
+                                       *   Previously folded into
+                                       *   `SWMM_ROUTING_FLOODING`, which
+                                       *   reported a coupling TRANSFER as
+                                       *   flooding. It is still an OUTFLOW of
+                                       *   the 1D system and still enters the
+                                       *   routing continuity error, so a host
+                                       *   summing the outflow categories must
+                                       *   now add this one too.
+                                       *
+                                       *   Zero (and the volume stays in
+                                       *   `SWMM_ROUTING_FLOODING`) under
+                                       *   `[2D_OPTIONS] COUPLING_IN_FLOODING
+                                       *   YES`. */
 } SWMM_RoutingTotal;
 
 /**
diff --git a/include/openswmm/engine/openswmm_model.h b/include/openswmm/engine/openswmm_model.h
index 83e449ffc..a4dd90f7c 100644
--- a/include/openswmm/engine/openswmm_model.h
+++ b/include/openswmm/engine/openswmm_model.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_model.h
  * @brief OpenSWMM Engine — Model building and options C API.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_MODEL_H
@@ -92,6 +108,64 @@ SWMM_ENGINE_API int swmm_finalize_model(SWMM_Engine engine);
  */
 SWMM_ENGINE_API int swmm_model_write(SWMM_Engine engine, const char* new_inp_path);
 
+/** Physical-output mapping for swmm_model_write_staged(). Kind is 0=model,
+ * 1=mesh, 2=component configuration. final_path and the returned path are UTF-8.
+ * Return NULL/empty to refuse output. The returned storage must remain valid
+ * until the next callback. Called synchronously once per output actually written.
+ * Callbacks must not throw or modify/reenter the engine. */
+typedef const char* (*SWMM_StageOutputCallback)(void* user_data,
+                                              const char* final_path,
+                                              int kind);
+/** Serialize the built-in INP writer's outputs through a mandatory mapper.
+ * References are based on final_inp_path, never on the mapped staging names.
+ * Only mapped output directories may be created. Staging paths must be distinct
+ * from final outputs and from each other; the caller owns cleanup, validation
+ * and publication. Success means serialization only, not a committed project.
+ * Diagnostics are appended to the engine warning list. Plugins are excluded. */
+SWMM_ENGINE_API int swmm_model_write_staged(SWMM_Engine engine,
+                                           const char* final_inp_path,
+                                           SWMM_StageOutputCallback mapper,
+                                           void* user_data);
+
+/** Write profile for swmm_model_write_compat(). */
+typedef enum SWMM_InpProfile {
+    SWMM_INP_PROFILE_FULL        = 0,  /**< native OpenSWMM format (= swmm_model_write) */
+    SWMM_INP_PROFILE_SWMM5       = 1,  /**< readable by the OpenSWMM legacy 5.3.0 engine */
+    SWMM_INP_PROFILE_SWMM5_STOCK = 2   /**< readable by a stock EPA SWMM 5 engine (5.2.4) */
+} SWMM_InpProfile;
+
+/**
+ * @brief Write the current model state as an .inp for a given engine profile.
+ *
+ * @details `SWMM_INP_PROFILE_SWMM5` produces a file a SWMM 5.x engine reads:
+ *          v6-only sections ([VIRTUAL_JUNCTIONS], [INLET_JUNCTIONS], [2D_*],
+ *          [PLUGINS], [PROCESS_COMPONENTS], [USER_FLAGS], [USER_FLAG_VALUES],
+ *          [RDII_DECAY]) and option keys are omitted, `FLOW_ROUTING FV` is
+ *          written as `DYNWAVE`, `SURCHARGE_METHOD DYNAMIC_SLOT`/`TPA` as
+ *          `SLOT`, a virtual junction becomes an ordinary junction, and an
+ *          inlet junction becomes an ordinary junction plus an [INLET_USAGE]
+ *          row on its approach conduit (same design, same capture node).
+ *          Each substitution is appended to the engine's warning list
+ *          (swmm_get_warning_count / swmm_get_warning_at). The file is a run
+ *          artifact: the model held by the engine is not changed.
+ *
+ *          `SWMM_INP_PROFILE_SWMM5_STOCK` is the same for a STOCK EPA SWMM 5
+ *          engine: it also drops the positional extensions only the OpenSWMM
+ *          legacy 5.3.0 engine parses — subcatchment rain/snow scale factors
+ *          (and the `*` snowpack placeholder that holds their position) and
+ *          the rain-gage scale factor — which a stock parser rejects as an
+ *          undefined object. A dropped factor other than 1.0 is reported as
+ *          a warning. Use it for any 5.x engine that is not the in-tree one.
+ *
+ * @param engine       Engine handle (SWMM_STATE_OPENED or later).
+ * @param new_inp_path Path where the file should be written.
+ * @param profile      SWMM_InpProfile value.
+ * @returns SWMM_OK on success; SWMM_ERR_BADPARAM for an unknown profile or
+ *          NULL path; SWMM_ERR_* on a write failure.
+ */
+SWMM_ENGINE_API int swmm_model_write_compat(SWMM_Engine engine, const char* new_inp_path,
+                                            int profile);
+
 /**
  * @brief Write the current model state via a named writer plugin.
  *
@@ -309,8 +383,17 @@ typedef enum SWMM_FilePathRole {
                                        *  `owner` is decimal index "0".."N-1" */
     SWMM_FILE_RAINGAGE_DATA     = 9,  /**< ctx.gages.file_path[i],
                                        *  `owner` is the gage id     */
-    SWMM_FILE_TIMESERIES_DATA   = 10  /**< ctx.tables.tables[i].file_path,
+    SWMM_FILE_TIMESERIES_DATA   = 10, /**< ctx.tables.tables[i].file_path,
                                        *  `owner` is the series id   */
+
+    /* Scalar slots — `owner` ignored. Unavailable (SWMM_ERR_BADPARAM) in
+     * builds without 2D support. */
+    SWMM_FILE_MESH_2D           = 11, /**< [2D_MESH_FILE] external .2dm   */
+    SWMM_FILE_OUTPUT_2D         = 12, /**< [2D_OPTIONS] OUTPUT_FILE .h5   */
+
+    /* Vector slot — `owner` selects the entry. */
+    SWMM_FILE_LID_REPORT        = 13  /**< ctx.lid_usage.rpt_file[i],
+                                       *  `owner` is decimal index "0".."N-1" */
 } SWMM_FilePathRole;
 
 /**
diff --git a/include/openswmm/engine/openswmm_nodes.h b/include/openswmm/engine/openswmm_nodes.h
index b23d72ccf..7cc4d2908 100644
--- a/include/openswmm/engine/openswmm_nodes.h
+++ b/include/openswmm/engine/openswmm_nodes.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_nodes.h
  * @brief OpenSWMM Engine — Node C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_NODES_H
@@ -164,6 +180,27 @@ SWMM_ENGINE_API int swmm_node_set_pond_area(SWMM_Engine engine, int idx, double
  */
 SWMM_ENGINE_API int swmm_node_set_initial_depth(SWMM_Engine engine, int idx, double depth);
 
+/**
+ * @brief Set a node's rendering-only rim (ground) depth above the invert.
+ *
+ * @details RENDERING ONLY — no hydraulics, routing, reporting or output-file
+ *          code reads this value, so setting it can never change a result.
+ *          It exists for virtual junctions, whose max depth is derived (always
+ *          the shared pipe crown): without it every viewer drawing a ground
+ *          line collapses the surface to the crown at each break point. It is
+ *          the optional third token of a [VIRTUAL_JUNCTIONS] row.
+ *
+ *          On other node types the value is simply carried; renderers use the
+ *          real max depth there. Pass 0 to clear it ("unset" — renderers fall
+ *          back to the max depth). Negative values are clamped to 0.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Zero-based node index.
+ * @param depth   Rim depth above the invert in project length units.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_node_set_rim_depth(SWMM_Engine engine, int idx, double depth);
+
 /* =========================================================================
  * Geometry getters
  * ========================================================================= */
@@ -208,7 +245,9 @@ SWMM_ENGINE_API int swmm_node_is_virtual(SWMM_Engine engine, int idx, int* is_vi
  *          distinct rule code on a violated usage rule so callers can render
  *          actionable messages: 609 = not exactly two conduits, 611 =
  *          cross-section mismatch, 613 = nonzero offset at the node, 617 =
- *          a lateral inflow source targets the node.
+ *          the node is a 2D surface-coupling point. Point lateral inflows
+ *          ([INFLOWS], [DWF], RDII, subcatchment outlets, LID drains, the
+ *          runtime lateral-inflow API) are permitted at a virtual junction.
  */
 SWMM_ENGINE_API int swmm_node_set_virtual(SWMM_Engine engine, int idx, int make_virtual);
 
@@ -217,8 +256,8 @@ SWMM_ENGINE_API int swmm_node_set_virtual(SWMM_Engine engine, int idx, int make_
  *
  * @details Read-only: evaluates the same structural rules that
  *          swmm_node_set_virtual() enforces (exactly two attached conduits of
- *          identical cross-section, zero offsets, no lateral inflow sources,
- *          dynamic-wave routing) without changing any state and without
+ *          identical cross-section, zero offsets, no 2D surface coupling,
+ *          dynamic-wave or FV routing) without changing any state and without
  *          requiring the node to currently be a JUNCTION — so callers can
  *          offer "convert to virtual junction" only when it would succeed.
  *
@@ -231,6 +270,38 @@ SWMM_ENGINE_API int swmm_node_set_virtual(SWMM_Engine engine, int idx, int make_
  */
 SWMM_ENGINE_API int swmm_node_virtual_eligible(SWMM_Engine engine, int idx, int* rule_code);
 
+/* -------------------------------------------------------------------------
+ * Inlet junctions (2026-09-05). An inlet junction is a virtual junction
+ * (is_virtual = 1) that additionally carries is_inlet = 1, sits between two
+ * STREET conduits (or RECT_OPEN/TRAPEZOIDAL for drop-inlet designs), owns one
+ * inlet-usage row (swmm_inlet_usage_set with SWMM_INLET_HOST_NODE) naming the
+ * inlet design and the capture node, and — unlike a plain virtual junction —
+ * is NOT sealed: it floods above the street section's full depth (or the
+ * [INLET_JUNCTIONS] MaxDepth when supplied) and receives the capture node's
+ * overflow back as street flow.
+ * ------------------------------------------------------------------------- */
+
+/** @param[out] is_inlet Receives 1 if the node is an inlet junction. */
+SWMM_ENGINE_API int swmm_node_is_inlet(SWMM_Engine engine, int idx, int* is_inlet);
+
+/**
+ * @brief Dry-run check of the inlet-junction rules (all virtual-junction
+ *        rules plus 623: both attached conduits are STREET; drop-inlet shapes
+ *        are accepted when `for_drop_inlet` is nonzero).
+ * @param[out] rule_code 0 when eligible, else the violated ERR_VJ_ / ERR_IJ_ code.
+ */
+SWMM_ENGINE_API int swmm_node_inlet_eligible(SWMM_Engine engine, int idx, int for_drop_inlet, int* rule_code);
+
+/**
+ * @brief Promote a node to an inlet junction (sets is_virtual and is_inlet,
+ *        applying the virtual-junction derived-geometry contract) or demote
+ *        it. Demoting with `make_inlet = 0` clears is_inlet only — the node
+ *        stays a virtual junction; use swmm_node_set_virtual(idx, 0) to
+ *        return it to a plain junction. Demotion removes the node's usage row.
+ * @returns SWMM_OK; generic codes; or a distinct rule code (609/611/613/617/623).
+ */
+SWMM_ENGINE_API int swmm_node_set_inlet(SWMM_Engine engine, int idx, int make_inlet);
+
 /**
  * @brief Get a node's invert elevation.
  * @param engine  Engine handle.
@@ -249,6 +320,20 @@ SWMM_ENGINE_API int swmm_node_get_invert_elev(SWMM_Engine engine, int idx, doubl
  */
 SWMM_ENGINE_API int swmm_node_get_max_depth(SWMM_Engine engine, int idx, double* depth);
 
+/**
+ * @brief Get a node's rendering-only rim (ground) depth above the invert.
+ *
+ * @details See swmm_node_set_rim_depth(). 0 means unset: a renderer drawing a
+ *          ground line should fall back to swmm_node_get_max_depth(), which
+ *          for a virtual junction is the pipe crown.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Zero-based node index.
+ * @param[out] depth  Receives the rim depth in project length units, or 0.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_node_get_rim_depth(SWMM_Engine engine, int idx, double* depth);
+
 /* =========================================================================
  * Hydraulic state getters/setters
  * ========================================================================= */
diff --git a/include/openswmm/engine/openswmm_output.h b/include/openswmm/engine/openswmm_output.h
index c09d37162..129df5a2b 100644
--- a/include/openswmm/engine/openswmm_output.h
+++ b/include/openswmm/engine/openswmm_output.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_output.h
  * @brief OpenSWMM Engine — Output File Reader C API.
@@ -37,7 +53,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_OUTPUT_H
@@ -143,6 +159,42 @@ typedef enum SWMM_OutSystemVar {
  */
 SWMM_ENGINE_API SWMM_Output swmm_output_open(const char* path);
 
+/**
+ * @brief Open a binary output file that is still being written.
+ *
+ * @details Unlike swmm_output_open(), this does not need the closing
+ *          records: offsets come from a forward parse of the header and the
+ *          period count from the file size (whole records only). Use it to
+ *          tail a run in progress — both the 6.x engine and the legacy 5.x
+ *          engines flush the file after every report period — or to salvage
+ *          the completed periods of a run that died before finishing. Poll
+ *          swmm_output_refresh() for growth. Never modifies the file.
+ *
+ * @param path  Path to a .out file whose header is complete.
+ * @returns Opaque handle, or NULL if the header cannot be parsed yet.
+ */
+SWMM_ENGINE_API SWMM_Output swmm_output_open_live(const char* path);
+
+/**
+ * @brief Re-count the periods of a file opened with swmm_output_open_live().
+ *
+ * @details Once the writer's closing records appear, they are adopted
+ *          (period count + error code) and the handle stops being live; it
+ *          then behaves exactly like one from swmm_output_open(). On a
+ *          non-live handle this is a no-op that reports the current count.
+ *
+ * @param handle   Output reader handle.
+ * @param periods  Optional out: current period count.
+ * @returns 0 on success, -1 on a NULL handle.
+ */
+SWMM_ENGINE_API int swmm_output_refresh(SWMM_Output handle, int* periods);
+
+/**
+ * @brief 1 while a handle from swmm_output_open_live() has not yet seen the
+ *        closing records, 0 otherwise, -1 on NULL.
+ */
+SWMM_ENGINE_API int swmm_output_is_live(SWMM_Output handle);
+
 /**
  * @brief Close the output file and free all resources.
  *
@@ -258,6 +310,23 @@ SWMM_ENGINE_API const char* swmm_output_get_node_id(SWMM_Output handle,
 SWMM_ENGINE_API const char* swmm_output_get_link_id(SWMM_Output handle,
                                                       int index);
 
+/**
+ * @brief Get the string ID of a species (pollutant) column by index.
+ *
+ * @details The `.out` header carries one name per species column. Reading
+ *          it is the ONLY way to identify a column's meaning: the per-column
+ *          unit field is a three-value concentration enum, so the water-age
+ *          column (`__WATER_AGE__`, reported in HOURS) necessarily reuses a
+ *          concentration code. Consumers plotting or converting a species
+ *          column must key on this name, not on the unit code.
+ *
+ * @param handle  Output reader handle.
+ * @param index   Zero-based species index (0 .. pollut_count-1).
+ * @returns  Null-terminated string owned by the reader, or NULL on error.
+ */
+SWMM_ENGINE_API const char* swmm_output_get_pollut_id(SWMM_Output handle,
+                                                        int index);
+
 /* =========================================================================
  * Per-period result retrieval (all objects, one variable, one period)
  * ========================================================================= */
diff --git a/include/openswmm/engine/openswmm_pollutants.h b/include/openswmm/engine/openswmm_pollutants.h
index 1e5561827..dce716eac 100644
--- a/include/openswmm/engine/openswmm_pollutants.h
+++ b/include/openswmm/engine/openswmm_pollutants.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_pollutants.h
  * @brief OpenSWMM Engine — Pollutant / Water Quality C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_POLLUTANTS_H
diff --git a/include/openswmm/engine/openswmm_process_components.h b/include/openswmm/engine/openswmm_process_components.h
new file mode 100644
index 000000000..946fe1810
--- /dev/null
+++ b/include/openswmm/engine/openswmm_process_components.h
@@ -0,0 +1,101 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_process_components.h
+ * @brief C API — [PROCESS_COMPONENTS] registrations (E-C3 subset of the
+ *        transport IO plan §5): enumerate, find, register, remove.
+ *
+ * @details The GUI's file-binding surface: an editor locates its component's
+ *          config path here, and the "create component + config file" flow
+ *          registers first, then writes the file (registration with a
+ *          not-yet-existing config path is legal — resolve reads it at the
+ *          next open).
+ *
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_PROCESS_COMPONENTS_H
+#define OPENSWMM_PROCESS_COMPONENTS_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Number of [PROCESS_COMPONENTS] registrations. -1 on bad handle. */
+SWMM_ENGINE_API int swmm_process_component_count(SWMM_Engine engine);
+
+/**
+ * @brief Read one registration.
+ * @param id_buf        [out] Component id (NUL-terminated).
+ * @param config_buf    [out] The config="…" argument as written (may be "").
+ * @param resolved_buf  [out] Effective path the config was READ from at the
+ *                      last open ("" until resolution).
+ */
+SWMM_ENGINE_API int swmm_process_component_get(SWMM_Engine engine, int idx,
+        char* id_buf, int id_len, char* config_buf, int config_len,
+        char* resolved_buf, int resolved_len);
+
+/** @brief Registration index for @p id, or -1. */
+SWMM_ENGINE_API int swmm_process_component_find(SWMM_Engine engine,
+        const char* id);
+
+/**
+ * @brief Register a component (BUILDING/OPENED). Duplicate id refused.
+ *        The config file need not exist yet.
+ */
+SWMM_ENGINE_API int swmm_process_component_register(SWMM_Engine engine,
+        const char* id, const char* config_path);
+
+/** @brief Remove registration @p idx (BUILDING/OPENED). Indexes shift. */
+SWMM_ENGINE_API int swmm_process_component_remove(SWMM_Engine engine,
+        int idx);
+
+/* ---- Built-in component catalogue (U1, 2026-09-07) -----------------------
+ * The ids the engine knows how to bind, independent of any model: the six
+ * planned/implemented built-ins of the process-global registry. This is the
+ * catalogue the GUI's Process Components table offers in its Id combo. The
+ * external component-library discovery (`swmm_component_library_*`,
+ * PROG stream D) is a separate, later seam; this one never scans disk.
+ */
+
+/** @brief Number of built-in component ids. */
+SWMM_ENGINE_API int swmm_process_component_known_count(void);
+
+/**
+ * @brief Read built-in id @p idx.
+ * @param id_buf       [out] The id (e.g. "org.hydrocouple.openswmm.reactions").
+ * @param desc_buf     [out] Short description.
+ * @param implemented  [out] 1 when the component has an apply hook in this
+ *                     build, 0 when it is a planned placeholder (its
+ *                     registration line is diagnosed at open).
+ */
+SWMM_ENGINE_API int swmm_process_component_known_get(int idx,
+        char* id_buf, int id_len, char* desc_buf, int desc_len,
+        int* implemented);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_PROCESS_COMPONENTS_H */
diff --git a/include/openswmm/engine/openswmm_quality.h b/include/openswmm/engine/openswmm_quality.h
index cabbbf02a..cfad11e83 100644
--- a/include/openswmm/engine/openswmm_quality.h
+++ b/include/openswmm/engine/openswmm_quality.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_quality.h
  * @brief OpenSWMM Engine — Water Quality (Landuse / Buildup / Washoff / Treatment) C API.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_QUALITY_H
@@ -90,7 +106,10 @@ SWMM_ENGINE_API int swmm_buildup_set(SWMM_Engine engine, int lu_idx, int pollut_
  *
  * @param engine     Engine handle.
  * @param lu_idx     Landuse index.
- * @param pollut_idx Pollutant index.
+ * @param pollut_idx Surface-species index: a pollutant index, or
+ *                   `n_pollutants + m` for the reactions component's m-th
+ *                   species (BW-MSX, 2026-09-19 — MSX species build up and
+ *                   wash off by the same relations).
  * @param[out] func_type  Buildup function type (0=NONE, 1=POW, 2=EXP, 3=SAT, 4=EXT).
  * @param[out] c1         Coefficient 1.
  * @param[out] c2         Coefficient 2.
@@ -111,7 +130,8 @@ SWMM_ENGINE_API int swmm_buildup_get(SWMM_Engine engine, int lu_idx, int pollut_
  *
  * @param engine       Engine handle.
  * @param lu_idx       Landuse index.
- * @param pollut_idx   Pollutant index.
+ * @param pollut_idx   Surface-species index (pollutant, or `n_pollutants + m`
+ *                     for the m-th reactions-component species — BW-MSX).
  * @param func_type    Washoff function type (0=NONE, 1=EXP, 2=RC, 3=EMC).
  * @param coeff        Washoff coefficient.
  * @param expon        Washoff exponent.
diff --git a/include/openswmm/engine/openswmm_reactions.h b/include/openswmm/engine/openswmm_reactions.h
new file mode 100644
index 000000000..5f986b531
--- /dev/null
+++ b/include/openswmm/engine/openswmm_reactions.h
@@ -0,0 +1,246 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_reactions.h
+ * @brief C API — the reaction system ([REACTION_*] / .rxn) surface for GUI
+ *        editors (E-C1: validation + discovery).
+ *
+ * @details The discovery getters are the AUTHORITATIVE completer/highlighter
+ *          vocabulary (MSX plan GUI contract): a GUI must enumerate species,
+ *          coefficients, terms, hydraulic variables, and functions from here
+ *          rather than hard-coding lists, so vocabulary drift is structural,
+ *          not disciplinary. The hydraulic-variable and function getters are
+ *          engine-less statics — usable before any model is open, and there
+ *          is exactly one copy of the truth (the expression compiler's own
+ *          tables).
+ *
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_REACTIONS_H
+#define OPENSWMM_REACTIONS_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Expression scopes for validation. */
+#define SWMM_RXN_SCOPE_TERM 0
+#define SWMM_RXN_SCOPE_PIPE 1
+#define SWMM_RXN_SCOPE_TANK 2
+
+/* Expression forms — mirrors ReactionExprForm. */
+#define SWMM_RXN_FORM_NONE    0
+#define SWMM_RXN_FORM_RATE    1
+#define SWMM_RXN_FORM_EQUIL   2
+#define SWMM_RXN_FORM_FORMULA 3
+
+/**
+ * @brief Compile-only validation of a reaction expression against the
+ *        model's live vocabulary (species, coefficients, terms, pollutants,
+ *        hydraulic variables). No state change.
+ * @details Scope selects the identifier-resolution vocabulary. For
+ *          SWMM_RXN_SCOPE_TERM, references to ALL terms are accepted — the
+ *          forward-only ordering rule stays enforced at file-apply time,
+ *          where ordinal position exists (D-RC1): validation answers "is
+ *          this well-formed against the vocabulary," not "is the file
+ *          orderable."
+ * @param engine  Engine handle.
+ * @param scope   SWMM_RXN_SCOPE_*.
+ * @param expr    Expression text.
+ * @param errbuf  [out, optional] Diagnostic (NUL-terminated).
+ * @param buflen  Size of errbuf in bytes.
+ * @param col_out [out, optional] 1-based error column; -1 when not
+ *                attributable.
+ * @return SWMM_OK if the expression compiles; SWMM_ERR_BADPARAM otherwise.
+ */
+SWMM_ENGINE_API int swmm_reaction_validate_expression(SWMM_Engine engine,
+        int scope, const char* expr, char* errbuf, int buflen, int* col_out);
+
+/* ---- Model discovery (require an engine with a parsed model) ----------- */
+
+/** @brief Number of declared MSX species (0 when no reactions configured). */
+SWMM_ENGINE_API int swmm_reaction_species_count(SWMM_Engine engine);
+
+/** @brief Read one species: name, BULK(0)/WALL(1), units, tolerances. */
+SWMM_ENGINE_API int swmm_reaction_species_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, int* is_wall,
+        char* units, int units_len, double* atol, double* rtol);
+
+/** @brief Number of [REACTION_COEFFICIENTS] entries. */
+SWMM_ENGINE_API int swmm_reaction_coeff_count(SWMM_Engine engine);
+
+/** @brief Read one coefficient: name, PARAMETER(1)/CONSTANT(0), value. */
+SWMM_ENGINE_API int swmm_reaction_coeff_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, int* is_param, double* value);
+
+/** @brief Number of [REACTION_TERMS] entries. */
+SWMM_ENGINE_API int swmm_reaction_term_count(SWMM_Engine engine);
+
+/** @brief Read one term: name and its source expression. */
+SWMM_ENGINE_API int swmm_reaction_term_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, char* expr, int expr_len);
+
+/**
+ * @brief Read a species' expression in one scope (PIPE or TANK).
+ * @param form [out] SWMM_RXN_FORM_* (NONE when the species has none).
+ */
+SWMM_ENGINE_API int swmm_reaction_expr_get(SWMM_Engine engine, int scope,
+        int species_idx, int* form, char* expr, int expr_len);
+
+/**
+ * @brief Read a [REACTION_OPTIONS] value as its canonical token.
+ * @param key SOLVER, COUPLING, RATE_UNITS, AREA_UNITS, TIMESTEP, ATOL, RTOL,
+ *            TEMPERATURE (degC fallback for the TEMP expression variable).
+ */
+SWMM_ENGINE_API int swmm_reaction_option_get(SWMM_Engine engine,
+        const char* key, char* value, int value_len);
+
+/* ---- CRUD (E-C2) — BUILDING/OPENED only (rows only seed at start).
+ * Every mutator validates eagerly: the whole system is recompiled before
+ * the call returns, and a mutation that leaves any expression uncompilable
+ * is rolled back and refused (SWMM_ERR_BADPARAM) — the GUI can never store
+ * an uncompilable model (D-RC5). Species add/remove rebuild the species
+ * registry's MSX block in place (D-RC3); removal of a species still
+ * referenced by any compiled expression is refused. --------------------- */
+
+/** @brief Declare a species (is_wall: 0 BULK, 1 WALL; atol/rtol 0 = global). */
+SWMM_ENGINE_API int swmm_reaction_species_add(SWMM_Engine engine,
+        const char* name, int is_wall, const char* units, double atol,
+        double rtol);
+
+/** @brief Remove species @p idx. Refused while any expression references it. */
+SWMM_ENGINE_API int swmm_reaction_species_remove(SWMM_Engine engine, int idx);
+
+/** @brief Add a coefficient (is_param: 1 PARAMETER, 0 CONSTANT). */
+SWMM_ENGINE_API int swmm_reaction_coeff_add(SWMM_Engine engine,
+        const char* name, int is_param, double value);
+
+/** @brief Change a coefficient's value. */
+SWMM_ENGINE_API int swmm_reaction_coeff_set_value(SWMM_Engine engine, int idx,
+        double value);
+
+/** @brief Remove coefficient @p idx. Refused while referenced. */
+SWMM_ENGINE_API int swmm_reaction_coeff_remove(SWMM_Engine engine, int idx);
+
+/** @brief Add an intermediate term (referencable by later terms only). */
+SWMM_ENGINE_API int swmm_reaction_term_add(SWMM_Engine engine,
+        const char* name, const char* expr);
+
+/** @brief Replace term @p idx's expression. */
+SWMM_ENGINE_API int swmm_reaction_term_set_expr(SWMM_Engine engine, int idx,
+        const char* expr);
+
+/** @brief Remove term @p idx. Refused while referenced. */
+SWMM_ENGINE_API int swmm_reaction_term_remove(SWMM_Engine engine, int idx);
+
+/**
+ * @brief Set (or clear, with SWMM_RXN_FORM_NONE) a species' expression in
+ *        one scope (PIPE or TANK).
+ */
+SWMM_ENGINE_API int swmm_reaction_expr_set(SWMM_Engine engine, int scope,
+        int species_idx, int form, const char* expr);
+
+/** @brief Set a [REACTION_OPTIONS] value from its canonical token. */
+SWMM_ENGINE_API int swmm_reaction_option_set(SWMM_Engine engine,
+        const char* key, const char* value);
+
+/* ---- Initial quality (GLOBAL + the E-B NODE/LINK rows) ----------------- */
+
+SWMM_ENGINE_API int swmm_reaction_init_global_get(SWMM_Engine engine,
+        int species_idx, double* value);
+SWMM_ENGINE_API int swmm_reaction_init_global_set(SWMM_Engine engine,
+        int species_idx, double value);
+SWMM_ENGINE_API int swmm_reaction_init_elem_count(SWMM_Engine engine);
+SWMM_ENGINE_API int swmm_reaction_init_elem_get(SWMM_Engine engine,
+        int entry_idx, int* is_link, int* elem_idx, int* species_idx,
+        double* value);
+/** @brief Upsert on (is_link, elem_idx, species_idx). Value must be >= 0. */
+SWMM_ENGINE_API int swmm_reaction_init_elem_set(SWMM_Engine engine,
+        int is_link, int elem_idx, int species_idx, double value);
+SWMM_ENGINE_API int swmm_reaction_init_elem_remove(SWMM_Engine engine,
+        int entry_idx);
+
+/* ---- Whole-file text surface (E-C3) — the GUI text tab's contract.
+ * serialize -> apply_text -> serialize is byte-identical (D-RC6). -------- */
+
+/**
+ * @brief Canonical .rxn text from engine state.
+ * @param buf        Caller buffer (may be NULL to size).
+ * @param buflen     Size of buf in bytes.
+ * @param needed_len [out] Required size INCLUDING the NUL — always set.
+ * @return SWMM_OK when written; SWMM_ERR_BADPARAM when buf is too small
+ *         (needed_len still tells the caller how much to allocate).
+ */
+SWMM_ENGINE_API int swmm_reactions_serialize(SWMM_Engine engine, char* buf,
+        int buflen, int* needed_len);
+
+/**
+ * @brief Dry-run full-file parse+compile of .rxn TEXT against this model.
+ *        Zero state change, success or failure.
+ * @return SWMM_OK when the text would apply; SWMM_ERR_BADPARAM with the
+ *         first diagnostic in errbuf otherwise.
+ */
+SWMM_ENGINE_API int swmm_reactions_check_text(SWMM_Engine engine,
+        const char* text, char* errbuf, int buflen);
+
+/**
+ * @brief Transactional replace of the whole reaction system from .rxn TEXT.
+ * @details BUILDING/OPENED only. Staged: on ANY error the previous system —
+ *          reaction state and registry block — is byte-identical to before
+ *          the call (today's clear-on-error is fine at open where there is
+ *          nothing to lose; on a live model it would be destructive).
+ */
+SWMM_ENGINE_API int swmm_reactions_apply_text(SWMM_Engine engine,
+        const char* text, char* errbuf, int buflen);
+
+/**
+ * @brief Serialize to the bound component config path (or @p path_or_null
+ *        when given). SWMM_ERR_BADPARAM when neither names a path.
+ */
+SWMM_ENGINE_API int swmm_reactions_save(SWMM_Engine engine,
+        const char* path_or_null);
+
+/* ---- Static vocabulary (no engine handle needed) ----------------------- */
+
+/** @brief Number of built-in hydraulic variables (D Q U RE US FF AV HRT DT
+ *         TEMP). */
+SWMM_ENGINE_API int swmm_reaction_hydvar_count(void);
+
+/** @brief Read one hydraulic variable's name and description. */
+SWMM_ENGINE_API int swmm_reaction_hydvar_get(int idx, char* name,
+        int name_len, char* description, int desc_len);
+
+/** @brief Number of built-in functions (EXP … TAN arity 1; MIN MAX POW 2). */
+SWMM_ENGINE_API int swmm_reaction_function_count(void);
+
+/** @brief Read one function's name and arity. */
+SWMM_ENGINE_API int swmm_reaction_function_get(int idx, char* name,
+        int name_len, int* arity);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_REACTIONS_H */
diff --git a/include/openswmm/engine/openswmm_spatial.h b/include/openswmm/engine/openswmm_spatial.h
index 19d38b023..0474d24fe 100644
--- a/include/openswmm/engine/openswmm_spatial.h
+++ b/include/openswmm/engine/openswmm_spatial.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_spatial.h
  * @brief OpenSWMM Engine — Spatial Frame C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_SPATIAL_H
diff --git a/include/openswmm/engine/openswmm_sq2d.h b/include/openswmm/engine/openswmm_sq2d.h
new file mode 100644
index 000000000..563f012bf
--- /dev/null
+++ b/include/openswmm/engine/openswmm_sq2d.h
@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_sq2d.h
+ * @brief S7 (2026-09-19) — C API for the 2D surface-quality rows
+ *        (`[2D_COVERAGES]`, `[2D_LOADINGS]`, `[2D_CURB_LENGTH]`) and the
+ *        cell buildup store.
+ *
+ * @details Rows are authored per SCOPE — the `*` row, a TAG row (every cell
+ *          carrying the tag) or a CELL row — and resolve GLOBAL < TAG < CELL
+ *          at initialize, exactly as the `.inp` sections do (one parser, one
+ *          rule). A coverage row is the WHOLE land-use set of its scope:
+ *          setting it replaces any earlier row with the same scope key.
+ *
+ *          Row edits need the engine OPENED or BUILDING (SWMM_ERR_LIFECYCLE
+ *          otherwise); the read-backs work in every state, and the buildup
+ *          store reads back once the run has started.
+ *
+ *          Units follow the project: percent for coverages, user mass per
+ *          acre | hectare for loadings and buildup (lbs | kg; a reactions
+ *          species declared in UG scales through its own unit factor), and
+ *          the project's length unit for curb lengths.
+ */
+
+#ifndef OPENSWMM_SQ2D_H
+#define OPENSWMM_SQ2D_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define SWMM_SQ2D_SCOPE_GLOBAL 0   /**< the `*` row */
+#define SWMM_SQ2D_SCOPE_TAG    1   /**< every cell carrying a tag */
+#define SWMM_SQ2D_SCOPE_CELL   2   /**< one cell, 0-based here (1-based in the file) */
+
+/* =========================================================================
+ * [2D_COVERAGES]
+ * ========================================================================= */
+
+/** Number of authored coverage rows. */
+SWMM_ENGINE_API int swmm_2d_coverage_count(SWMM_Engine engine, int* count);
+
+/**
+ * @brief Set the coverage set of one scope. The row is `n` (land use,
+ *        percent) pairs; the percents must sum to 100 or less and every
+ *        land use must exist. Replaces an existing row with the same scope.
+ * @param scope     SWMM_SQ2D_SCOPE_*
+ * @param tag       tag name for SCOPE_TAG (ignored otherwise; may be NULL)
+ * @param cell      0-based cell for SCOPE_CELL (ignored otherwise)
+ * @param landuses  `n` land-use names
+ * @param percents  `n` percents
+ */
+SWMM_ENGINE_API int swmm_2d_coverage_set(SWMM_Engine engine, int scope,
+                                         const char* tag, int cell,
+                                         const char* const* landuses,
+                                         const double* percents, int n);
+
+/** Number of (land use, percent) pairs in row @p index. */
+SWMM_ENGINE_API int swmm_2d_coverage_row_size(SWMM_Engine engine, int index, int* n);
+
+/**
+ * @brief Read row @p index back. Any out pointer may be NULL; @p tag needs
+ *        @p taglen bytes; @p landuse needs @p lulen bytes and receives the
+ *        name of pair @p k (0-based), @p percent its percent.
+ */
+SWMM_ENGINE_API int swmm_2d_coverage_get(SWMM_Engine engine, int index, int k,
+                                         int* scope, char* tag, int taglen,
+                                         int* cell, char* landuse, int lulen,
+                                         double* percent);
+
+/** Remove row @p index. */
+SWMM_ENGINE_API int swmm_2d_coverage_remove(SWMM_Engine engine, int index);
+
+/* =========================================================================
+ * [2D_LOADINGS]
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_2d_loading_count(SWMM_Engine engine, int* count);
+
+/** Set the initial buildup of @p species (a pollutant or a reactions
+ *  species that builds up) on one scope, user mass per acre | hectare.
+ *  Replaces an existing row with the same scope and species. */
+SWMM_ENGINE_API int swmm_2d_loading_set(SWMM_Engine engine, int scope,
+                                        const char* tag, int cell,
+                                        const char* species, double value);
+
+SWMM_ENGINE_API int swmm_2d_loading_get(SWMM_Engine engine, int index,
+                                        int* scope, char* tag, int taglen,
+                                        int* cell, char* species, int splen,
+                                        double* value);
+
+SWMM_ENGINE_API int swmm_2d_loading_remove(SWMM_Engine engine, int index);
+
+/* =========================================================================
+ * [2D_CURB_LENGTH]
+ * ========================================================================= */
+
+SWMM_ENGINE_API int swmm_2d_curb_length_count(SWMM_Engine engine, int* count);
+
+/** Set the curb length (project length units, > 0) of one scope. Replaces
+ *  an existing row with the same scope. */
+SWMM_ENGINE_API int swmm_2d_curb_length_set(SWMM_Engine engine, int scope,
+                                            const char* tag, int cell,
+                                            double length);
+
+SWMM_ENGINE_API int swmm_2d_curb_length_get(SWMM_Engine engine, int index,
+                                            int* scope, char* tag, int taglen,
+                                            int* cell, double* length);
+
+SWMM_ENGINE_API int swmm_2d_curb_length_remove(SWMM_Engine engine, int index);
+
+/* =========================================================================
+ * Buildup store (running model)
+ * ========================================================================= */
+
+/**
+ * @brief Per-cell buildup of @p species (name of a pollutant or a
+ *        reactions species), user mass per acre | hectare, summed over the
+ *        cell's land uses — the value the results file reports. @p n is
+ *        the length of @p out (at least the cell count). Returns
+ *        SWMM_ERR_LIFECYCLE before the run started or when no row
+ *        resolved (no coverages, IGNORE_QUALITY, RAINFALL_MODE NONE).
+ */
+SWMM_ENGINE_API int swmm_2d_get_buildup_bulk(SWMM_Engine engine,
+                                             const char* species,
+                                             double* out, int n);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_SQ2D_H */
diff --git a/include/openswmm/engine/openswmm_statistics.h b/include/openswmm/engine/openswmm_statistics.h
index 821ae2045..8d55702b1 100644
--- a/include/openswmm/engine/openswmm_statistics.h
+++ b/include/openswmm/engine/openswmm_statistics.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_statistics.h
  * @brief OpenSWMM Engine — Statistics Query C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_STATISTICS_H
diff --git a/include/openswmm/engine/openswmm_subcatchments.h b/include/openswmm/engine/openswmm_subcatchments.h
index 9c73f8652..12672a65b 100644
--- a/include/openswmm/engine/openswmm_subcatchments.h
+++ b/include/openswmm/engine/openswmm_subcatchments.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_subcatchments.h
  * @brief OpenSWMM Engine — Subcatchment C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_SUBCATCHMENTS_H
@@ -839,6 +855,23 @@ SWMM_ENGINE_API const char* swmm_aquifer_id(SWMM_Engine engine, int idx);
  */
 SWMM_ENGINE_API int swmm_aquifer_add(SWMM_Engine engine, const char* id);
 
+/**
+ * @brief Rename an aquifer in place.
+ *
+ * @details Updates both the name vector and the name registry so
+ *          swmm_aquifer_id() and swmm_aquifer_index() stay in agreement.
+ *          [GROUNDWATER] holds an aquifer INDEX, not a name, so subcatchment
+ *          references follow automatically.
+ *          Lifecycle: BUILDING or OPENED.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Aquifer index.
+ * @param new_id  New unique name (non-empty). A pure case-respelling of this
+ *                same aquifer is allowed.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.
+ */
+SWMM_ENGINE_API int swmm_aquifer_rename(SWMM_Engine engine, int idx, const char* new_id);
+
 /**
  * @brief Aquifer parameter codes for swmm_aquifer_get_param / _set_param.
  *
@@ -969,6 +1002,25 @@ SWMM_ENGINE_API const char* swmm_snowpack_id(SWMM_Engine engine, int idx);
  */
 SWMM_ENGINE_API int swmm_snowpack_add(SWMM_Engine engine, const char* id);
 
+/**
+ * @brief Rename a snow pack in place.
+ *
+ * @details Updates both the name vector (read by swmm_snowpack_id() and the
+ *          [SNOWPACKS] writer) and the name registry (read by
+ *          swmm_snowpack_index() and the [SUBCATCHMENTS] snow-pack column),
+ *          plus the deferred-resolution name held per subcatchment. Melt
+ *          parameters and subcatchment assignments are index-based and follow
+ *          automatically.
+ *          Lifecycle: BUILDING or OPENED.
+ *
+ * @param engine  Engine handle.
+ * @param idx     Snow pack index.
+ * @param new_id  New unique name (non-empty). A pure case-respelling of this
+ *                same snow pack is allowed.
+ * @returns SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.
+ */
+SWMM_ENGINE_API int swmm_snowpack_rename(SWMM_Engine engine, int idx, const char* new_id);
+
 /* -------------------------------------------------------------------------
  * Snowpack surface parameters
  *
@@ -1101,6 +1153,133 @@ SWMM_ENGINE_API int swmm_subcatch_set_snow_scale_factor(SWMM_Engine engine, int
 SWMM_ENGINE_API int swmm_subcatch_get_snow_scale_factor(SWMM_Engine engine, int idx,
                                             double* factor);
 
+/* =========================================================================
+ * Custom groundwater flow expressions ([GWF] section)
+ * ========================================================================= */
+
+/**
+ * @brief Which of a subcatchment's two custom groundwater flow expressions.
+ *
+ * @details LATERAL is added to the standard A1/A2/A3 lateral flow; DEEP
+ *          replaces the standard deep-percolation term. Expressions may use
+ *          the variables listed by @ref swmm_gwf_variable_name, the functions
+ *          listed by @ref swmm_gwf_function_name, and the operators
+ *          `+ - * / ^ ( )`; names are case-insensitive.
+ */
+typedef enum SWMM_GwfType {
+    SWMM_GWF_LATERAL = 0,
+    SWMM_GWF_DEEP = 1
+} SWMM_GwfType;
+
+/**
+ * @brief Read a subcatchment's custom groundwater flow expression.
+ *
+ * @details Writes a NUL-terminated string into `buf` (empty when no
+ *          expression is set), truncating if `buflen` is too small.
+ *
+ * @param engine   Engine handle.
+ * @param index    Zero-based subcatchment index.
+ * @param type     A SWMM_GwfType code.
+ * @param[out] buf Destination buffer for the expression text.
+ * @param buflen   Size of `buf` in bytes (must be > 0).
+ * @returns SWMM_OK on success, SWMM_ERR_BADPARAM for a bad type, or an error code.
+ */
+SWMM_ENGINE_API int swmm_subcatch_get_gwf_expression(SWMM_Engine engine, int index, int type,
+                                                     char* buf, int buflen);
+
+/**
+ * @brief Set or clear a subcatchment's custom groundwater flow expression.
+ *
+ * @details Inverse of @ref swmm_subcatch_get_gwf_expression. A null or empty
+ *          string clears the expression. The text is stored as given and is
+ *          NOT validated here (so files with legacy quirks still load);
+ *          use @ref swmm_gwf_validate_expression first. An invalid expression
+ *          fails start() with ERROR 233. Pre-start-only (BUILDING / OPENED):
+ *          the expression is compiled when the simulation starts, so a
+ *          mid-run change returns SWMM_ERR_LIFECYCLE.
+ *
+ * @param engine  Engine handle.
+ * @param index   Zero-based subcatchment index.
+ * @param type    A SWMM_GwfType code.
+ * @param expr    Expression text, or null/empty to clear.
+ * @returns SWMM_OK on success, SWMM_ERR_BADPARAM for a bad type, or an error code.
+ */
+SWMM_ENGINE_API int swmm_subcatch_set_gwf_expression(SWMM_Engine engine, int index, int type,
+                                                     const char* expr);
+
+/**
+ * @brief Validate a [GWF] expression WITHOUT modifying engine state.
+ *
+ * @details Editor-support peer of swmm_treatment_validate_expression:
+ *          grammar-only, never mutates the engine, so it is safe to invoke
+ *          per keystroke. Stricter than the runtime parser: unknown
+ *          characters, unknown identifiers (must be a GW variable or a
+ *          function), unbalanced parentheses, misplaced operators and wrong
+ *          function arity (min/max take 2 arguments, all others 1) are
+ *          errors. An empty or whitespace-only expression is INVALID
+ *          ("expression is empty") — callers treat empty as "clear"
+ *          themselves.
+ *
+ * @param engine        Engine handle (grammar only; no model data is read).
+ * @param expr          Expression text.
+ * @param[out] errbuf   Receives the diagnostic on failure ("" on success).
+ *                      May be NULL.
+ * @param buflen        Size of errbuf in bytes.
+ * @param[out] col_out  Receives the 0-based character offset of the error,
+ *                      or -1 when not attributable. May be NULL.
+ * @returns SWMM_OK when the expression is valid, SWMM_ERR_BADPARAM when
+ *          invalid (diagnostic in errbuf/col_out) or on NULL expr.
+ */
+SWMM_ENGINE_API int swmm_gwf_validate_expression(SWMM_Engine engine, const char* expr,
+                                                 char* errbuf, int buflen, int* col_out);
+
+/**
+ * @brief Number of variables a [GWF] expression may reference.
+ * @param engine  Engine handle.
+ * @returns Variable count, or -1 on error.
+ */
+SWMM_ENGINE_API int swmm_gwf_variable_count(SWMM_Engine engine);
+
+/**
+ * @brief Name of the i-th [GWF] variable (upper-case, e.g. "HGW").
+ * @param engine   Engine handle.
+ * @param i        Zero-based index, < swmm_gwf_variable_count().
+ * @param[out] buf Destination buffer (NUL-terminated, truncated if too small).
+ * @param buflen   Size of `buf` in bytes (must be > 0).
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gwf_variable_name(SWMM_Engine engine, int i, char* buf, int buflen);
+
+/**
+ * @brief Short English description of the i-th [GWF] variable, with a units
+ *        placeholder, e.g. "Water table height above aquifer bottom (ft or m)".
+ * @param engine   Engine handle.
+ * @param i        Zero-based index, < swmm_gwf_variable_count().
+ * @param[out] buf Destination buffer (NUL-terminated, truncated if too small).
+ * @param buflen   Size of `buf` in bytes (must be > 0).
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gwf_variable_description(SWMM_Engine engine, int i, char* buf, int buflen);
+
+/**
+ * @brief Number of built-in functions a [GWF] expression may call.
+ * @param engine  Engine handle.
+ * @returns Function count, or -1 on error.
+ */
+SWMM_ENGINE_API int swmm_gwf_function_count(SWMM_Engine engine);
+
+/**
+ * @brief Name of the i-th expression function (lower-case, stable order:
+ *        abs, sgn, sqrt, log, exp, sin, cos, tan, asin, acos, atan, step, min,
+ *        max, cot, sinh, cosh, tanh, coth, log10, acot).
+ * @param engine   Engine handle.
+ * @param i        Zero-based index, < swmm_gwf_function_count().
+ * @param[out] buf Destination buffer (NUL-terminated, truncated if too small).
+ * @param buflen   Size of `buf` in bytes (must be > 0).
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_gwf_function_name(SWMM_Engine engine, int i, char* buf, int buflen);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/include/openswmm/engine/openswmm_tables.h b/include/openswmm/engine/openswmm_tables.h
index 88d3f70ca..f13497177 100644
--- a/include/openswmm/engine/openswmm_tables.h
+++ b/include/openswmm/engine/openswmm_tables.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_tables.h
  * @brief OpenSWMM Engine — Tables (Time Series & Curves) and Patterns C API.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_TABLES_H
@@ -143,6 +159,47 @@ SWMM_ENGINE_API int swmm_table_get_point(SWMM_Engine engine, int idx, int pt_idx
  */
 SWMM_ENGINE_API int swmm_table_clear(SWMM_Engine engine, int idx);
 
+/**
+ * @brief Get a timeseries' time-only (relative) row info.
+ *
+ * Rows authored without a date in a `[TIMESERIES]` section are elapsed
+ * times anchored at the simulation start (legacy SWMM seeds every series'
+ * date anchor with START_DATE + START_TIME). The engine stores those rows
+ * as absolute date/times after resolution; this reports how many leading
+ * rows were authored that way and the start_date offset currently baked
+ * into their x-values, so a caller can recover the authored elapsed times
+ * as `x - anchor` and the .inp writer emits them back in time-only form.
+ *
+ * @param engine           Engine handle.
+ * @param idx              Zero-based table index (must be a TIMESERIES).
+ * @param[out] n_relative  Leading rows authored as elapsed time (0 = all
+ *                         rows carry explicit dates).
+ * @param[out] anchor      OADate offset baked into those rows' x-values.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_timeseries_get_relative_info(SWMM_Engine engine, int idx,
+                                                      int* n_relative, double* anchor);
+
+/**
+ * @brief Declare a timeseries' leading rows as time-only (relative).
+ *
+ * Use after rebuilding a series through swmm_table_clear() /
+ * swmm_table_add_point() to restore its authored time-only format: the
+ * first @p n_relative points' x-values are treated as absolute date/times
+ * containing @p anchor as their simulation-start offset, and the .inp
+ * writer emits them as elapsed times (`x - anchor`) rather than dates.
+ * Pass 0 to mark every row as explicitly dated.
+ *
+ * @param engine      Engine handle.
+ * @param idx         Zero-based table index (must be a TIMESERIES).
+ * @param n_relative  Leading rows authored as elapsed time (clamped to the
+ *                    current point count).
+ * @param anchor      OADate offset baked into those rows' x-values.
+ * @returns SWMM_OK on success, or an error code.
+ */
+SWMM_ENGINE_API int swmm_timeseries_set_relative_info(SWMM_Engine engine, int idx,
+                                                      int n_relative, double anchor);
+
 /* =========================================================================
  * Lookup (cursor-optimized)
  * ========================================================================= */
diff --git a/include/openswmm/engine/openswmm_transport.h b/include/openswmm/engine/openswmm_transport.h
new file mode 100644
index 000000000..46ed664cb
--- /dev/null
+++ b/include/openswmm/engine/openswmm_transport.h
@@ -0,0 +1,139 @@
+/* SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2026 Caleb Buahin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file openswmm_transport.h
+ * @brief E6 — the ARD transport configuration surface ([TRANSPORT_OPTIONS],
+ *        [TRANSPORT_BOUNDARIES], [TRANSPORT_SOURCES]).
+ *
+ * @details The last quality subsystem with no C API of its own: heat,
+ *          reactions, water age and the pollutant tables all have theirs,
+ *          and G7g (the dispersion/boundary property editors) was gated on
+ *          this header existing. Follows `openswmm_water_age.h`'s
+ *          conventions: values cross the boundary in the CONFIG FILE'S
+ *          units, the engine's internal units stay internal, and setters
+ *          mark the config `configured` so a save renders it.
+ *
+ *          **Boundary/source rows are read-only in this revision.** The
+ *          rows resolve names to indices once, at open
+ *          (`resolveArdTransportRows`), with failures fatal there where the
+ *          row text is available for the diagnostic; a runtime add would
+ *          need that resolution re-entrant and its failures survivable,
+ *          which is its own round (recorded in the E6 handoff). Editors
+ *          read here and write through the component file.
+ */
+
+#ifndef OPENSWMM_TRANSPORT_H
+#define OPENSWMM_TRANSPORT_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief `[TRANSPORT_OPTIONS] DISPERSION` mode. */
+typedef enum SWMM_TransportDispersionMode {
+    SWMM_DISPERSION_OFF     = 0, /**< No global dispersion (per-conduit
+                                      overrides still apply). */
+    SWMM_DISPERSION_FISCHER = 1, /**< Fischer et al. (1979) closure from the
+                                      local hydraulics. */
+    SWMM_DISPERSION_VALUE   = 2  /**< One user coefficient, display len²/s. */
+} SWMM_TransportDispersionMode;
+
+/** @brief 1 if a transport.ard component is configured on the model. */
+SWMM_ENGINE_API int swmm_transport_get_configured(SWMM_Engine engine,
+                                                  int* configured);
+
+/** @brief The dispersion mode (SWMM_TransportDispersionMode). */
+SWMM_ENGINE_API int swmm_transport_get_dispersion_mode(SWMM_Engine engine,
+                                                       int* mode);
+
+/**
+ * @brief Set the dispersion mode.
+ * @details Setting VALUE without a coefficient leaves the previous
+ *          coefficient in force — set both. Marks the config present.
+ */
+SWMM_ENGINE_API int swmm_transport_set_dispersion_mode(SWMM_Engine engine,
+                                                       int mode);
+
+/** @brief VALUE-mode coefficient, display units (ft²/s or m²/s). */
+SWMM_ENGINE_API int swmm_transport_get_dispersion_value(SWMM_Engine engine,
+                                                        double* value);
+
+/** @brief Set the VALUE-mode coefficient (must be >= 0 and finite). */
+SWMM_ENGINE_API int swmm_transport_set_dispersion_value(SWMM_Engine engine,
+                                                        double value);
+
+/** @brief `TARGET_DX`, display length units; 0 means engine default. */
+SWMM_ENGINE_API int swmm_transport_get_target_dx(SWMM_Engine engine,
+                                                 double* dx);
+
+/** @brief Set `TARGET_DX` (must be >= 0 and finite; 0 restores default). */
+SWMM_ENGINE_API int swmm_transport_set_target_dx(SWMM_Engine engine,
+                                                 double dx);
+
+/** @brief Number of per-conduit dispersion override rows. */
+SWMM_ENGINE_API int swmm_transport_conduit_disp_count(SWMM_Engine engine,
+                                                      int* count);
+
+/** @brief Override row `index`: link index + coefficient (display units). */
+SWMM_ENGINE_API int swmm_transport_get_conduit_disp(SWMM_Engine engine,
+                                                    int index,
+                                                    int* link_index,
+                                                    double* value);
+
+/** @brief Number of `[TRANSPORT_BOUNDARIES]` rows (raw, as configured). */
+SWMM_ENGINE_API int swmm_transport_boundary_count(SWMM_Engine engine,
+                                                  int* count);
+
+/**
+ * @brief Read boundary row `index`.
+ * @param element   Node name buffer (may be NULL to skip).
+ * @param elem_len  Its capacity, including the terminator.
+ * @param species   Species name buffer (may be NULL).
+ * @param spec_len  Its capacity.
+ * @param is_ts     1 if TIMESERIES mode. The series name is returned in
+ *                  `ts_name` when set; `value` is the VALUE-mode
+ *                  concentration otherwise (species units).
+ */
+SWMM_ENGINE_API int swmm_transport_get_boundary(SWMM_Engine engine, int index,
+                                                char* element, int elem_len,
+                                                char* species, int spec_len,
+                                                int* is_ts, double* value,
+                                                char* ts_name, int ts_len);
+
+/** @brief Number of `[TRANSPORT_SOURCES]` rows (raw, as configured). */
+SWMM_ENGINE_API int swmm_transport_source_count(SWMM_Engine engine,
+                                                int* count);
+
+/**
+ * @brief Read source row `index`. Same contract as the boundary reader;
+ *        `value` is the VALUE-mode mass rate (species mass units per
+ *        second; negative = extraction, D-NS1).
+ */
+SWMM_ENGINE_API int swmm_transport_get_source(SWMM_Engine engine, int index,
+                                              char* element, int elem_len,
+                                              char* species, int spec_len,
+                                              int* is_ts, double* value,
+                                              char* ts_name, int ts_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OPENSWMM_TRANSPORT_H */
diff --git a/include/openswmm/engine/openswmm_water_age.h b/include/openswmm/engine/openswmm_water_age.h
new file mode 100644
index 000000000..a05aec325
--- /dev/null
+++ b/include/openswmm/engine/openswmm_water_age.h
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_water_age.h
+ * @brief Water-age source-table CRUD (subplan X5 = water-age plan A6, the
+ *        minimal GUI-facing subset; TRANSPORT_QUALITY_GUI_PLAN §6 prereq 5).
+ *
+ * @details The `[WATER_AGE_SOURCES]` configuration (waterage component,
+ *          `model.age`) as a keyed table: a GLOBAL age per source pathway,
+ *          plus per-NODE overrides for the DWF and EXTERNAL_INFLOW
+ *          pathways (the A1a scope rule — other pathways refuse NODE
+ *          scope, exactly like the parser). Values are HOURS, the config
+ *          file's unit; **negative values are legal** — a negative source
+ *          age EXTRACTS age-volume, clamped so age never goes below zero
+ *          (D-NS1, subplan §3.1). Edits mutate live engine state (the
+ *          loaders re-read the table every step, so mid-simulation edits
+ *          take effect on the next routing step); `swmm_water_age_save`
+ *          persists the table to a component file.
+ *
+ *          The full A6 surface (Python/MCP bindings, node/link age state
+ *          getters) is deferred — this header is exactly what the GUI's
+ *          Water Age Sources editor (G3g) binds to.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_WATER_AGE_H
+#define OPENSWMM_WATER_AGE_H
+
+#include "openswmm_engine.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Source pathways (mirrors the engine's WaterAgeSource order — the
+ *        values are the storage indices, do not renumber).
+ */
+typedef enum SWMM_WaterAgeSource {
+    SWMM_AGE_SRC_RAINFALL        = 0,
+    SWMM_AGE_SRC_DWF             = 1,
+    SWMM_AGE_SRC_GW              = 2,
+    SWMM_AGE_SRC_RDII            = 3,
+    SWMM_AGE_SRC_EXTERNAL_INFLOW = 4,
+    SWMM_AGE_SRC_IFACE           = 5,
+    SWMM_AGE_SRC_INITIAL_STATE   = 6,
+    SWMM_AGE_SRC_COUNT           = 7
+} SWMM_WaterAgeSource;
+
+/** @brief 1 if [OPTIONS] WATER_AGE is ON, else 0. */
+SWMM_ENGINE_API int swmm_water_age_get_enabled(SWMM_Engine engine,
+                                               int* enabled);
+
+/** @brief GLOBAL age for one source pathway, HOURS (signed per D-NS1). */
+SWMM_ENGINE_API int swmm_water_age_get_global_source(SWMM_Engine engine,
+                                                     int source,
+                                                     double* hours);
+
+/**
+ * @brief Set the GLOBAL age for one source pathway, HOURS.
+ * @details Negative hours are legal (age-volume extraction, D-NS1). Marks
+ *          the config as present so the engine consumes it.
+ */
+SWMM_ENGINE_API int swmm_water_age_set_global_source(SWMM_Engine engine,
+                                                     int source,
+                                                     double hours);
+
+/** @brief Number of per-node override rows. */
+SWMM_ENGINE_API int swmm_water_age_override_count(SWMM_Engine engine,
+                                                  int* count);
+
+/**
+ * @brief Read override row `index` (0-based): its source, node index, and
+ *        HOURS. Row order is stable across edits within a session.
+ */
+SWMM_ENGINE_API int swmm_water_age_get_override(SWMM_Engine engine, int index,
+                                                int* source, int* node_index,
+                                                double* hours);
+
+/**
+ * @brief Add or update the override for (source, node_index), HOURS.
+ * @details Only SWMM_AGE_SRC_DWF and SWMM_AGE_SRC_EXTERNAL_INFLOW take
+ *          NODE scope (the parser's A1a rule) — others return
+ *          SWMM_ERR_BADPARAM. Negative hours are legal (D-NS1).
+ */
+SWMM_ENGINE_API int swmm_water_age_set_override(SWMM_Engine engine,
+                                                int source, int node_index,
+                                                double hours);
+
+/** @brief Remove the override for (source, node_index); BADINDEX if none. */
+SWMM_ENGINE_API int swmm_water_age_remove_override(SWMM_Engine engine,
+                                                   int source,
+                                                   int node_index);
+
+/**
+ * @brief Write the current table as a `[WATER_AGE_SOURCES]` component file
+ *        (the `model.age` format the waterage component parses) — the
+ *        GUI editor's save path.
+ */
+SWMM_ENGINE_API int swmm_water_age_save(SWMM_Engine engine,
+                                        const char* path);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // OPENSWMM_WATER_AGE_H
diff --git a/include/openswmm/engine/openswmm_xsect.h b/include/openswmm/engine/openswmm_xsect.h
index 16cf3859e..25c1e4b30 100644
--- a/include/openswmm/engine/openswmm_xsect.h
+++ b/include/openswmm/engine/openswmm_xsect.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_xsect.h
  * @brief OpenSWMM Engine — standalone cross-section geometry C API.
@@ -38,7 +54,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_XSECT_H
diff --git a/include/openswmm/plugin_sdk/IInputPlugin.hpp b/include/openswmm/plugin_sdk/IInputPlugin.hpp
index 1cf03519e..a524736e4 100644
--- a/include/openswmm/plugin_sdk/IInputPlugin.hpp
+++ b/include/openswmm/plugin_sdk/IInputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IInputPlugin.hpp
  * @brief Interface for input file reader/writer plugins.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_IINPUT_PLUGIN_HPP
diff --git a/include/openswmm/plugin_sdk/IOutputPlugin.hpp b/include/openswmm/plugin_sdk/IOutputPlugin.hpp
index 96cac769e..bd8645b29 100644
--- a/include/openswmm/plugin_sdk/IOutputPlugin.hpp
+++ b/include/openswmm/plugin_sdk/IOutputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IOutputPlugin.hpp
  * @brief Interface for output-writing plugins.
@@ -34,7 +50,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_IOUTPUT_PLUGIN_HPP
diff --git a/include/openswmm/plugin_sdk/IPluginComponentInfo.hpp b/include/openswmm/plugin_sdk/IPluginComponentInfo.hpp
index 3051843f1..2c7802ecf 100644
--- a/include/openswmm/plugin_sdk/IPluginComponentInfo.hpp
+++ b/include/openswmm/plugin_sdk/IPluginComponentInfo.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
  /**
  * @file IPluginComponentInfo.hpp
  * @brief Interface that describes a plugin component — metadata and factory methods.
@@ -27,7 +43,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_IPLUGIN_COMPONENT_INFO_HPP
diff --git a/include/openswmm/plugin_sdk/IReportPlugin.hpp b/include/openswmm/plugin_sdk/IReportPlugin.hpp
index 02000917b..5b09bfd4e 100644
--- a/include/openswmm/plugin_sdk/IReportPlugin.hpp
+++ b/include/openswmm/plugin_sdk/IReportPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IReportPlugin.hpp
  * @brief Interface for report-writing plugins.
@@ -23,7 +39,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_IREPORT_PLUGIN_HPP
diff --git a/include/openswmm/plugin_sdk/IStateIOPlugin.hpp b/include/openswmm/plugin_sdk/IStateIOPlugin.hpp
index 7361fd9bd..5951b717a 100644
--- a/include/openswmm/plugin_sdk/IStateIOPlugin.hpp
+++ b/include/openswmm/plugin_sdk/IStateIOPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IStateIOPlugin.hpp
  * @brief Interface for state / hot-start IO plugins.
@@ -31,7 +47,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ISTATE_IO_PLUGIN_HPP
diff --git a/include/openswmm/plugin_sdk/PluginDiscovery.hpp b/include/openswmm/plugin_sdk/PluginDiscovery.hpp
index 9e32cd5d7..9f58f5cb6 100644
--- a/include/openswmm/plugin_sdk/PluginDiscovery.hpp
+++ b/include/openswmm/plugin_sdk/PluginDiscovery.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginDiscovery.hpp
  * @brief Public, framework-free facade for enumerating plugin file filters.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_PLUGIN_DISCOVERY_HPP
diff --git a/include/openswmm/plugin_sdk/PluginState.hpp b/include/openswmm/plugin_sdk/PluginState.hpp
index b68e905b4..4c5b65238 100644
--- a/include/openswmm/plugin_sdk/PluginState.hpp
+++ b/include/openswmm/plugin_sdk/PluginState.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginState.hpp
  * @brief Plugin lifecycle state enumerator.
@@ -50,7 +66,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_PLUGIN_STATE_HPP
diff --git a/include/openswmm/plugin_sdk/SimulationSnapshot.hpp b/include/openswmm/plugin_sdk/SimulationSnapshot.hpp
index 7571be912..140b690df 100644
--- a/include/openswmm/plugin_sdk/SimulationSnapshot.hpp
+++ b/include/openswmm/plugin_sdk/SimulationSnapshot.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SimulationSnapshot.hpp
  * @brief Read-only snapshot of simulation state passed to plugins.
@@ -20,7 +36,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_SIMULATION_SNAPSHOT_HPP
@@ -150,6 +166,21 @@ struct SimulationSnapshot {
     double sys_storage        = 0.0;  ///< Total storage volume
     double sys_pet            = 0.0;  ///< Potential evapotranspiration
 
+    /**
+     * @brief Whether the model has any subcatchments.
+     * @details Legacy assigns SYS_TEMPERATURE and SYS_PET — and applies the SI
+     *          temperature conversion — at the end of
+     *          output_saveSubcatchResults, which is called only behind
+     *          `if (Nobjects[SUBCATCH] > 0)` (output.c:489-490). With no
+     *          subcatchments both stay at the zero-initialised value of
+     *          SysResults and are never converted, so a raw 0 is reported
+     *          whatever the unit system. Carried on the snapshot because the
+     *          display-unit conversion is where that has to be honoured: the
+     *          degF->degC conversion is AFFINE, so converting a zero yields
+     *          -17.78 degC rather than zero.
+     */
+    bool has_subcatchments = true;
+
     // -----------------------------------------------------------------------
     // Pollutant concentrations (optional; populated only if quality routing active)
     // -----------------------------------------------------------------------
@@ -208,9 +239,13 @@ struct SimulationSnapshot {
     // 2D surface routing state (optional; populated only when the engine was
     // built with OPENSWMM_BUILD_2D and the input file contains a 2D mesh)
     //
-    // Layout: per-triangle vectors are sized `surface_tri_count`; per-vertex
-    // vectors are sized `surface_vert_count`. `surface_edge_flux` is flat
-    // [tri * 3 + edge] of size `surface_tri_count * 3`.
+    // Layout: per-cell vectors are sized `surface_tri_count` (a "tri" is any
+    // cell — triangle or quadrilateral, triangles first); per-vertex vectors
+    // are sized `surface_vert_count`. `surface_edge_flux` is flat
+    // [cell * surface_edge_stride + edge] of size
+    // `surface_tri_count * surface_edge_stride`, where the stride is 3 for an
+    // all-triangle mesh (byte-compatible with pre-quad consumers) and 4 once
+    // any quad exists; padding slots of a triangle row are 0.
     //
     // Fields are deep-copied from `SurfaceRouter2D::state()` on the main
     // simulation thread; consumers (Default2DOutputPlugin and any third-party
@@ -222,8 +257,13 @@ struct SimulationSnapshot {
     // `surface_tri_count == 0` to skip 2D-specific work in that case.
     // -----------------------------------------------------------------------
 
-    int surface_tri_count  = 0;             ///< Number of triangles (faces)
+    int surface_tri_count  = 0;             ///< Number of cells (faces): triangles + quads
     int surface_vert_count = 0;             ///< Number of vertices (nodes)
+    int surface_quad_count = 0;             ///< Number of quadrilateral cells (0 = all triangles)
+    int surface_edge_stride = 3;            ///< Edge slots per cell row in surface_edge_flux (3 | 4)
+    /// Vertices per cell (3 or 4), sized surface_tri_count. Empty when the
+    /// mesh is all triangles (consumers may treat empty as "all 3").
+    std::vector surface_cell_nv;
 
     std::vector surface_depth;          ///< Overland flow depth ψ_o (m), per face
     std::vector surface_head;           ///< Total head h_o = z_s + ψ_o (m), per face
@@ -234,6 +274,89 @@ struct SimulationSnapshot {
     std::vector surface_rainfall;       ///< Rainfall intensity (m/s), per face
     std::vector surface_coupling_flux;  ///< Coupling flux to SWMM node (m/s, + = into 2D), per face
     std::vector surface_net_source;     ///< Net source/sink (m/s), per face
+    std::vector surface_infil_rate;     ///< Held infiltration loss rate (m/s, ≥ 0), per face — all zero when no [2D_INFILTRATION*] model resolved
+    std::vector surface_infil_cum;      ///< Cumulative infiltrated depth (m), per face
+    std::vector surface_rain_cum;       ///< Cumulative rainfall volume (m³), per face
+    /**
+     * @brief 2D surface species concentration (overland transport S1/S2).
+     * @details Layout: [species * surface_tri_count + face], species-major to
+     *          match the engine's own cell store. `surface_species_count`
+     *          rows in the 1D row order (pollutants, MSX, age,
+     *          temperature — see `surface_species_names`).
+     *          A dry cell reports 0 (its mass is held, not divided).
+     *          Empty when the model carries no 2D transport.
+     */
+    std::vector surface_species_conc;
+    int surface_species_count = 0;
+    /// S4: the 2D row names in row order (pollutant ids, MSX ids,
+    /// `__WATER_AGE__`, `__TEMPERATURE__`) — `surface_species_count` entries.
+    /// Null before S4 / when 2D transport is off; consumers fall back to
+    /// `pollut_names`.
+    const std::vector* surface_species_names = nullptr;
+    /// S4b: per-row unit labels in the same order as `surface_species_names`
+    /// (pollutant units "MG/L" | "UG/L" | "#/L", the MSX species' declared
+    /// units, "hours" for `__WATER_AGE__`, "degC" for `__TEMPERATURE__`).
+    /// Null when 2D transport is off.
+    const std::vector* surface_species_units = nullptr;
+    /**
+     * @brief S7: buildup on the cells' land-use surfaces, per surface species
+     *        (the pollutant and MSX rows only — the first
+     *        `surface_buildup_count` rows of `surface_species_names`), user
+     *        mass per acre (US) or hectare (SI), summed over the cell's land
+     *        uses. Layout `[species * surface_tri_count + face]`. Empty when
+     *        no `[2D_COVERAGES]` row resolved.
+     */
+    std::vector surface_buildup;
+    int surface_buildup_count = 0;
+    /**
+     * @brief G-O: the two-zone `[2D_AQUIFER]` kernel's per-cell state, SI,
+     *        one value per face (`surface_tri_count`), empty when no aquifer
+     *        resolved. Rates are the cell's LAST firing (held between
+     *        firings, like the surface's held infiltration rate).
+     */
+    bool                gw2d_active = false;
+    std::vector gw2d_table_elev;    ///< water-table elevation (m) = bed + hg
+    std::vector gw2d_hg;            ///< saturated thickness (m)
+    std::vector gw2d_hu;            ///< closure A bulk unsaturated storage (m of water); 0 under closure B
+    std::vector gw2d_recharge;      ///< q0 (m/s), + down, − capillary rise
+    std::vector gw2d_lateral;       ///< net lateral Darcy into the cell (m³/s)
+    std::vector gw2d_node_exchange; ///< exchange with a 1D node (m³/s), + out of the aquifer
+    std::vector gw2d_deep;          ///< deep loss (m/s)
+    std::vector gw2d_et;            ///< subsurface ET (m/s, ≥ 0 out)
+    std::vector gw2d_dunne;         ///< saturation excess returned to the surface (m³/s)
+    std::vector gw2d_infil_in;      ///< infiltration delivered from the surface (m/s)
+    std::vector gw2d_link_seepage;  ///< G-X3: conduit seepage delivered in (m³/s)
+    /// T7.5: the aquifer's transported tuple, `[s * n_cells + c]`, as
+    /// CONCENTRATIONS (mass / water volume of the zone) — the quantity a
+    /// reader plots, derived here so no consumer has to know how the kernel
+    /// stores it. A zone with no water reports 0 rather than dividing.
+    std::vector gw2d_sat_conc;
+    std::vector gw2d_unsat_conc;
+    /// `[s * kTerms + t]` cumulative species ledger; the term order is the
+    /// `terms` attribute the writer emits.
+    std::vector gw2d_species_ledger;
+    int                 gw2d_species_count = 0;
+    const std::vector* gw2d_species_names = nullptr;
+    /// Static per-cell descriptors (filled every snapshot; the writer stores
+    /// them once): aquifer bottom elevation (m) and the resolved closure
+    /// (SWMM_GW2D_CLOSURE_*: 0 closed form, 1 enslaved, 2 sigma).
+    std::vector gw2d_bed_elev;
+    std::vector    gw2d_closure;
+    /// Closure B water content per σ layer, `[layer * surface_tri_count + face]`,
+    /// layer 0 at the ground surface; `gw2d_m_layers` layers. A cell not under
+    /// closure B carries 0 in every layer (mask with `gw2d_closure`).
+    std::vector gw2d_theta_sigma;
+    int                 gw2d_m_layers = 0;
+    /// Domain ledger (m³, cumulative): recharge, lateral, deep, node, dunne,
+    /// caprise, et, infil_in, init_storage, storage (live, incl. accumulators),
+    /// link (G-X3, conduit seepage in), continuity residual (ledgered) — the
+    /// SWMM_GW2D_LED_* order plus the residual last.
+    std::vector gw2d_ledger;
+    /// Cumulative exchange per `[2D_AQUIFER_NODE]` bed (m³, + out of the
+    /// aquifer into the pipe), in the authored bed order; `gw2d_node_names`
+    /// is the parallel name list (null when there are no beds).
+    std::vector             gw2d_bed_exchange_cum;
+    const std::vector* gw2d_node_names = nullptr;
     std::vector surface_edge_flux;      ///< Normal flux through each edge, flat [tri*3+edge]
     std::vector surface_vert_head;      ///< Reconstructed head at vertices (m) — SOLVER field (dry-cell head = bed)
     std::vector surface_vert_depth;     ///< SIGNED vertex depth η_v − z_v (m) — wet-masked, wetted-contact-gated render reconstruction; > 0 where water reaches the vertex, 0 = no-data sentinel (older engines also emitted negatives on the dry side of partially wet cells — readers stay negative-tolerant)
diff --git a/packages/gpu-omp/openswmm_gpu_omp/__init__.py b/packages/gpu-omp/openswmm_gpu_omp/__init__.py
index 08ab80d88..29eeff8c7 100644
--- a/packages/gpu-omp/openswmm_gpu_omp/__init__.py
+++ b/packages/gpu-omp/openswmm_gpu_omp/__init__.py
@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """openswmm-gpu-omp -- OpenMP (Kokkos) acceleration plugin for OpenSWMM 2D.
 
 This companion distribution ships a single native plugin
@@ -12,7 +28,7 @@
 returns 2D runs to the serial CPU solver.
 
 :author: Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 
 import importlib.metadata
diff --git a/packages/gpu-omp/pyproject.toml b/packages/gpu-omp/pyproject.toml
index 728c869b3..2dfe60e76 100644
--- a/packages/gpu-omp/pyproject.toml
+++ b/packages/gpu-omp/pyproject.toml
@@ -21,7 +21,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openswmm-gpu-omp"
-version = "6.0.0a3"
+version = "6.0.0a4.dev1"
 description = "OpenMP (Kokkos) GPU-plugin companion for the OpenSWMM 2D surface solver."
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -41,7 +41,7 @@ classifiers = [
 # Runtime version-locked to the base package: the plugin and the engine share
 # the GpuPluginAbi C ABI, and the loader additionally enforces the ABI version
 # at dlopen() time (GpuPluginAbi.h OPENSWMM_GPU_ABI_VERSION).
-dependencies = ["openswmm == 6.0.0a3"]
+dependencies = ["openswmm == 6.0.0a4.dev1"]
 
 [project.urls]
 Homepage   = "https://github.com/hydrocouple/openswmm.engine"
@@ -52,7 +52,9 @@ Repository = "https://github.com/hydrocouple/openswmm.engine"
 # ============================================================================
 [tool.scikit-build]
 minimum-version  = "build-system.requires"
-cmake.version    = ">=3.24"
+# >=4.3: same reason as the base wheel — configure runs the vcpkg toolchain,
+# and vcpkg 2026.07.29 needs string(JSON ... STRING_ENCODE ...), new in 4.3.
+cmake.version    = ">=4.3"
 cmake.build-type = "Release"
 ninja.make-fallback = true
 build-dir = "build/{wheel_tag}"
@@ -104,9 +106,12 @@ else
   apt-get update && apt-get install -y curl zip unzip tar git ninja-build libgomp1
 fi
 
-# Pin CMake < 4 (same rationale as the base wheel: vcpkg-tool's bundled cmakerc
-# dep rejects CMake 4.x on arm64).
-/opt/python/cp312-cp312/bin/pip install --quiet 'cmake<4'
+# Pin CMake >= 4.3 (same rationale as the base wheel: vcpkg 2026.07.29's SPDX
+# generation needs string(JSON ... STRING_ENCODE ...), which arrived in CMake
+# 4.3; the old `cmake<4` pin failed on the first port downloaded. The cmakerc
+# cmake_minimum_required(VERSION 3.3) problem the old pin guarded against on
+# arm64 is covered by CMAKE_POLICY_VERSION_MINIMUM=3.5 in `environment`).
+/opt/python/cp312-cp312/bin/pip install --quiet 'cmake>=4.3'
 export PATH="/opt/python/cp312-cp312/bin:$PATH"
 
 case "$(uname -m)" in
@@ -118,7 +123,7 @@ esac
 # in downloads/tools. Those bundled binaries are glibc-linked; on musllinux
 # (Alpine) they cannot exec, so vcpkg's compiler-hash detection dies the instant
 # it invokes the downloaded ninja. The system tools are installed above (apk
-# ninja/samurai, yum/apt ninja-build) with the pinned cmake<4 on PATH. No-op on
+# ninja/samurai, yum/apt ninja-build) with the pinned cmake>=4.3 on PATH. No-op on
 # manylinux (glibc), where the same system tools are valid too.
 export VCPKG_FORCE_SYSTEM_BINARIES=1
 # /host persists across the manylinux and musllinux container runs within a
diff --git a/plans/parity/overrides.tsv b/plans/parity/overrides.tsv
new file mode 100644
index 000000000..35eabd23d
--- /dev/null
+++ b/plans/parity/overrides.tsv
@@ -0,0 +1,379 @@
+# Manually-curated parity matrix overrides.
+#
+# Format: c_functionstatusnote
+# Status enum: parity | py-gap | mcp-gap | mcp-gap-2d | intentional | internal
+#
+# Use this file when:
+#   - The auto-matcher missed a real Python equivalent (override to `parity`
+#     with a `via:` note pointing to the actual binding).
+#   - A C function is deliberately not exposed to Python (override to
+#     `intentional` with a one-line reason).
+#   - A C function is a build/dev helper rather than a public API entry point
+#     (override to `internal`).
+#
+# Re-run `python3 docs/parity/tools/build_matrix.py` after edits.
+
+# ----------------------------------------------------------------------------
+# Intentional non-exposures (Python idioms supersede C-level facilities).
+# ----------------------------------------------------------------------------
+swmm_conversion_result_free	intentional	Python uses GC; _edit.ConversionResult is a TypedDict.
+swmm_impact_report_free	intentional	Python uses GC; _edit.ImpactEntry list is GC-managed.
+swmm_get_last_error	intentional	Python raises EngineError instead of polling last-error state.
+swmm_get_last_error_msg	intentional	Python raises EngineError carrying the message.
+swmm_engine_new	intentional	Solver.__init__ handles engine creation transparently.
+swmm_get_event_count	intentional	Alias of swmm_events_count per inline doc; same Phase 1 wrapping.
+swmm_get_current_time	intentional	Not called directly; current time via _solver.Solver.current_datetime (start_datetime + elapsed). C func returns elapsed seconds, not an OADate.
+
+# ----------------------------------------------------------------------------
+# False negatives (matcher missed a real Python wrapping under a different name).
+# ----------------------------------------------------------------------------
+swmm_2d_triangle_count	parity	via _2d.Surface2D.n_triangles (property).
+swmm_2d_vertex_count	parity	via _2d.Surface2D.n_vertices (property).
+swmm_2d_vertex_get_head	parity	via _2d.Surface2D.get_vertex_heads (bulk-only on Py side, single via index).
+swmm_2d_vertex_get_xyz	parity	via _2d.Surface2D.get_vertex_xyz, reached by MCP twod.get_vertex_head (per-vertex x/y/z alongside the head).
+swmm_2d_vertex_get_xyz_bulk	parity	via _2d.Surface2D.get_vertex_coords (returns (x,y,z) NumPy arrays).
+# 2D surface — MCP-reach override (the symbol IS wrapped in Python).
+swmm_2d_prepare_for_edit	intentional	Wrapped as _2d.Surface2D.prepare_for_edit but structurally unreachable from MCP: every twod tool is gated on surface.is_active, which the engine only sets in initialize(), which has already drained the authored rows this call exists to drain.
+swmm_ext_inflow_add	parity	via _inflows.Inflows.add_external.
+swmm_finalize_model	parity	via _model.ModelBuilder.finalize.
+swmm_validate_model	parity	via _model.ModelBuilder.validate.
+swmm_hotstart_warning	parity	via _hotstart.HotStart.get_warning.
+swmm_hydrograph_add_gage	parity	via _inflows.Inflows.add_hydrograph_gage.
+swmm_output_open	parity	via _output_reader.OutputReader.__init__.
+swmm_gpkg_open	parity	via _geopackage.GeoPackage.__init__.
+swmm_set_progress_callback	parity	via _solver.run_with_callback (function-level convenience).
+swmm_get_crs	parity	via _spatial.Spatial.get_crs (Python routes top-level CRS through Spatial).
+swmm_gpkg_node_count	parity	via _geopackage.GeoPackage.object_counts (aggregate dict).
+swmm_gpkg_link_count	parity	via _geopackage.GeoPackage.object_counts (aggregate dict).
+swmm_gpkg_subcatch_count	parity	via _geopackage.GeoPackage.object_counts (aggregate dict).
+swmm_gpkg_gage_count	parity	via _geopackage.GeoPackage.object_counts (aggregate dict).
+swmm_gpkg_simulation_id	parity	via _geopackage.GeoPackage.simulation_ids (plural, returns list).
+
+# Date getters/setters wrapped as datetime properties on both classes.
+swmm_options_get_start_date	parity	via _solver.Solver.start_datetime / _model.ModelBuilder.start_datetime properties.
+swmm_options_set_start_date	parity	via _solver.Solver.start_datetime / _model.ModelBuilder.start_datetime setters.
+swmm_options_get_end_date	parity	via _solver.Solver.end_datetime / _model.ModelBuilder.end_datetime properties.
+swmm_options_set_end_date	parity	via _solver.Solver.end_datetime / _model.ModelBuilder.end_datetime setters.
+swmm_options_get_report_start	parity	via _solver.Solver.report_start_datetime / _model.ModelBuilder.report_start_datetime properties.
+swmm_options_set_report_start	parity	via _solver.Solver.report_start_datetime / _model.ModelBuilder.report_start_datetime setters.
+
+# Output reader (Phase 2.5): metadata / count getters subsumed by the
+# analysis.output_metadata aggregate tool.
+swmm_output_close	intentional	OutputReader lifecycle managed by SimSession; no standalone close tool.
+swmm_output_get_version	parity	via analysis.output_metadata.
+swmm_output_get_flow_units	parity	via analysis.output_metadata; also surfaced via lifecycle.open_model summary.
+swmm_output_get_node_count	parity	via analysis.output_metadata; also via query.get_node_info / lifecycle summary.
+swmm_output_get_link_count	parity	via analysis.output_metadata.
+swmm_output_get_subcatch_count	parity	via analysis.output_metadata.
+swmm_output_get_pollut_count	parity	via analysis.output_pollutant_count + analysis.output_metadata.
+swmm_output_get_report_step	parity	via analysis.output_metadata.
+swmm_output_get_start_date	parity	via analysis.output_metadata.
+swmm_output_get_error_code	parity	via analysis.output_metadata; engine surfaces failures as EngineError elsewhere.
+swmm_output_get_node_id	parity	via query.get_node_info (string id round-trip) + lifecycle summary listings.
+swmm_output_get_link_id	parity	via query.get_link_info + listings.
+swmm_output_get_subcatch_id	parity	via query.get_subcatchment_info + listings.
+
+# Output reader (Phase 2.5): time-series readers subsumed by
+# analysis.get_time_series (handles node / link / subcatchment / system).
+swmm_output_get_node_series	parity	via analysis.get_time_series with element_type='node'.
+swmm_output_get_link_series	parity	via analysis.get_time_series with element_type='link'.
+swmm_output_get_subcatch_series	parity	via analysis.get_time_series with element_type='subcatchment'.
+swmm_output_get_system_series	parity	via analysis.get_time_series with element_type='system'.
+
+# Output reader: per-period "result" arrays (one variable across all
+# objects at one period).
+swmm_output_get_node_result	parity	via analysis.output_node_results (plural; returns {id, index, value} records).
+swmm_output_get_link_result	parity	via analysis.output_link_results (plural).
+swmm_output_get_subcatch_result	parity	via analysis.output_subcatch_results (plural).
+
+# ----------------------------------------------------------------------------
+# Nodes domain (Phase 2.6): basic property getter/setter pairs are covered
+# in batched form by query.get_node_info (read) and editing.set_node_properties
+# (write). The new nodes_mcp module exposes the SUBTYPE-specific accessors
+# (storage / outfall / divider), bulk arrays, statistics, and quality —
+# but does not duplicate the basic property pairs.
+# ----------------------------------------------------------------------------
+swmm_node_count	parity	via lifecycle.open_model summary + query.find_elements counts.
+swmm_node_id	parity	via query.get_node_info (id lookup by index returned in listings).
+swmm_node_index	parity	via query.find_elements / get_node_info (string id -> index resolved internally).
+swmm_node_get_invert_elev	parity	via query.get_node_info (returns invert_elev field).
+swmm_node_get_max_depth	parity	via query.get_node_info.
+swmm_node_get_initial_depth	parity	via query.get_node_info.
+swmm_node_get_surcharge_depth	parity	via query.get_node_info.
+swmm_node_get_ponded_area	parity	via query.get_node_info.
+swmm_node_get_crown_elev	parity	via query.get_node_info (invert_elev + max_depth).
+swmm_node_get_full_volume	parity	via query.get_node_info.
+swmm_node_get_losses	parity	via query.get_node_info.
+swmm_node_get_degree	parity	via query.get_node_info.
+swmm_node_get_head	parity	via query.get_node_info (read during running/ended).
+swmm_node_get_inflow	parity	via query.get_node_info.
+swmm_node_get_outflow	parity	via query.get_node_info.
+swmm_node_get_lateral_inflow	parity	via query.get_node_info.
+swmm_node_set_invert_elev	parity	via editing.set_node_properties.
+swmm_node_set_initial_depth	parity	via editing.set_node_properties.
+swmm_node_set_surcharge_depth	parity	via editing.set_node_properties.
+swmm_node_set_pond_area	parity	via editing.set_node_properties.
+swmm_node_set_lateral_inflow	parity	via forcing.set_forcing (target_type='node', variable='lateral_inflow').
+swmm_node_set_head_boundary	parity	via forcing.set_forcing (target_type='node', variable='head').
+swmm_node_rename	parity	via editing.rename_node (Phase 2 wave 2).
+
+# ----------------------------------------------------------------------------
+# Links domain (Phase 2.7): basic property pairs covered in batched form by
+# query.get_link_info and editing.set_link_properties; rename remains an
+# honest gap pending a Phase 2 wave 2 editing.rename_link tool.
+# ----------------------------------------------------------------------------
+swmm_link_count	parity	via lifecycle.open_model summary + query.find_elements counts.
+swmm_link_id	parity	via query.get_link_info / find_elements listings.
+swmm_link_index	parity	via query.find_elements (string id -> index resolved internally).
+swmm_link_get_type	parity	via query.get_link_info.
+swmm_link_get_length	parity	via query.get_link_info.
+swmm_link_get_roughness	parity	via query.get_link_info.
+swmm_link_get_slope	parity	via query.get_link_info.
+swmm_link_get_offset_up	parity	via query.get_link_info.
+swmm_link_get_offset_dn	parity	via query.get_link_info.
+swmm_link_get_depth	parity	via query.get_link_info (read during running/ended).
+swmm_link_get_capacity	parity	via query.get_link_info.
+swmm_link_get_from_node	parity	via query.get_link_info (returns endpoints).
+swmm_link_get_to_node	parity	via query.get_link_info.
+swmm_link_get_xsect	parity	via query.get_link_info (returns cross-section dict).
+swmm_link_set_length	parity	via editing.set_link_properties.
+swmm_link_set_roughness	parity	via editing.set_link_properties.
+swmm_link_set_offset_up	parity	via editing.set_link_properties.
+swmm_link_set_offset_dn	parity	via editing.set_link_properties.
+swmm_link_set_initial_flow	parity	via editing.set_link_properties.
+swmm_link_set_xsect	parity	via editing.set_link_properties + nodes.set_xsect (Links.set_xsect, the Phase 1 addition).
+swmm_link_set_nodes	parity	via building.add_link (sets nodes on creation); no in-place re-route tool yet.
+swmm_link_rename	parity	via editing.rename_link.
+
+# ----------------------------------------------------------------------------
+# Subcatchments domain (Phase 2.8): basic property pairs covered by
+# query.get_subcatchment_info and editing.set_subcatchment_properties.
+# ----------------------------------------------------------------------------
+swmm_subcatch_count	parity	via lifecycle.open_model summary + query.find_elements counts.
+swmm_subcatch_id	parity	via query.get_subcatchment_info / find_elements listings.
+swmm_subcatch_index	parity	via query.find_elements (string id -> index).
+swmm_subcatch_get_area	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_width	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_slope	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_imperv_pct	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_n_imperv	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_n_perv	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_ds_imperv	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_ds_perv	parity	via query.get_subcatchment_info.
+swmm_subcatch_get_outlet	parity	via query.get_subcatchment_info (returns outlet node id).
+swmm_subcatch_get_outlet_subcatch	parity	via query.get_subcatchment_info.
+swmm_subcatch_set_area	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_width	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_slope	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_imperv_pct	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_n_imperv	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_n_perv	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_ds_imperv	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_ds_perv	parity	via editing.set_subcatchment_properties.
+swmm_subcatch_set_outlet	parity	via editing.set_subcatchment_properties (outlet_node_id field).
+swmm_subcatch_set_outlet_subcatch	parity	via editing.set_subcatchment_properties (cascade outlet); supported in same field.
+swmm_subcatch_rename	parity	via editing.rename_subcatchment.
+
+# Quality / landuse sweep accessors: matcher strips the 'landuse_' prefix
+# differently than the tool names; explicit overrides.
+swmm_landuse_get_sweep_interval	parity	via quality.get_sweep_interval.
+swmm_landuse_get_sweep_removal	parity	via quality.get_sweep_removal.
+swmm_landuse_set_sweep_interval	parity	via quality.set_sweep_interval.
+swmm_landuse_set_sweep_removal	parity	via quality.set_sweep_removal.
+
+# ----------------------------------------------------------------------------
+# Statistics domain (Phase 2.6-2.8): all per-element stats are wrapped by the
+# corresponding nodes / links / subcatchments stat_* tools.
+# ----------------------------------------------------------------------------
+swmm_stat_node_max_depth	parity	via nodes.stat_max_depth.
+swmm_stat_node_max_overflow	parity	via nodes.stat_max_overflow.
+swmm_stat_node_vol_flooded	parity	via nodes.stat_vol_flooded.
+swmm_stat_node_time_flooded	parity	via nodes.stat_time_flooded.
+swmm_stat_node_max_depth_bulk	parity	via nodes.get_depths_bulk + analysis.get_flooding_summary aggregates.
+swmm_stat_link_max_flow	parity	via links.stat_max_flow.
+swmm_stat_link_max_velocity	parity	via links.stat_max_velocity.
+swmm_stat_link_max_filling	parity	via links.stat_max_filling.
+swmm_stat_link_vol_flow	parity	via links.stat_vol_flow.
+swmm_stat_link_surcharge_time	parity	via links.stat_surcharge_time.
+swmm_stat_link_max_flow_bulk	parity	via links.get_flows_bulk + analysis.get_capacity_summary aggregates.
+swmm_stat_subcatch_precip	parity	via subcatchments.stat_precip.
+swmm_stat_subcatch_runoff_vol	parity	via subcatchments.stat_runoff_vol.
+swmm_stat_subcatch_max_runoff	parity	via subcatchments.stat_max_runoff.
+swmm_stat_subcatch_runoff_vol_bulk	parity	via subcatchments.get_runoff_bulk + analysis aggregates.
+
+# ----------------------------------------------------------------------------
+# Mass balance domain: analysis.get_mass_balance returns a batched dict with
+# all continuity errors and component totals in one call.
+# ----------------------------------------------------------------------------
+swmm_get_runoff_continuity_error	parity	via analysis.get_mass_balance (runoff_continuity field).
+swmm_get_routing_continuity_error	parity	via analysis.get_mass_balance (routing_continuity field).
+swmm_get_quality_continuity_error	parity	via analysis.get_mass_balance (quality_continuity per pollutant).
+swmm_get_runoff_total	parity	via analysis.get_mass_balance (runoff totals: rainfall/evap/infil/runoff/etc.).
+swmm_get_routing_total	parity	via analysis.get_mass_balance (routing totals: DWF/WWF/RDII/external/etc.).
+swmm_get_routing_stats	parity	via analysis.get_mass_balance routing_diagnostics field.
+swmm_get_max_courant	parity	via analysis.get_mass_balance routing_diagnostics.max_courant.
+swmm_get_quality_evap_loss	parity	via analysis.get_mass_balance (quality losses per pollutant).
+swmm_get_quality_seep_loss	parity	via analysis.get_mass_balance (quality losses per pollutant).
+
+# ----------------------------------------------------------------------------
+# Forcing domain: forcing.set_forcing is a dispatcher covering all 8
+# (target_type, variable) combinations plus forcing.clear_forcing for cleanup.
+# ----------------------------------------------------------------------------
+swmm_forcing_node_lat_inflow	parity	via forcing.set_forcing (target_type='node', variable='lateral_inflow').
+swmm_forcing_node_head_boundary	parity	via forcing.set_forcing (target_type='node', variable='head').
+swmm_forcing_node_quality	parity	via forcing.set_forcing (target_type='node', variable='quality').
+swmm_forcing_link_flow	parity	via forcing.set_forcing (target_type='link', variable='flow').
+swmm_forcing_link_setting	parity	via forcing.set_forcing (target_type='link', variable='setting') and controls.set_link_setting.
+swmm_forcing_subcatch_rainfall	parity	via forcing.set_forcing (target_type='subcatchment', variable='rainfall').
+swmm_forcing_subcatch_evap	parity	via forcing.set_forcing (target_type='subcatchment', variable='evap').
+swmm_forcing_gage_rainfall	parity	via forcing.set_forcing (target_type='gage', variable='rainfall') and forcing.set_rainfall_override.
+swmm_forcing_clear_all	parity	via forcing.clear_forcing (no target_type/element_id) and forcing.clear_forcing per-target.
+
+# ----------------------------------------------------------------------------
+# Spatial domain: spatial_quality_mcp already exposes the full surface;
+# matcher misses the rename because the tools live under the 'spatial'
+# namespace (mounted from spatial_quality_mcp) rather than 'spatial_quality'.
+# ----------------------------------------------------------------------------
+swmm_spatial_get_node_coord	parity	via spatial.get_coordinates (element_type='node').
+swmm_spatial_set_node_coord	parity	via spatial.set_coordinates (element_type='node').
+swmm_spatial_get_link_coord	parity	via spatial.get_coordinates (element_type='link').
+swmm_spatial_set_link_coord	parity	via spatial.set_coordinates (element_type='link').
+swmm_spatial_get_subcatch_coord	parity	via spatial.get_coordinates (element_type='subcatchment').
+swmm_spatial_set_subcatch_coord	parity	via spatial.set_coordinates (element_type='subcatchment').
+swmm_spatial_get_gage_coord	parity	via spatial.get_coordinates (element_type='gage'); spatial.get_model_geometry returns all gage coords.
+swmm_spatial_set_gage_coord	parity	via spatial.set_coordinates (element_type='gage').
+swmm_spatial_get_link_vertices	parity	via spatial.get_vertices (returns full polyline incl. endpoints).
+swmm_spatial_set_link_vertices	parity	via spatial.set_vertices (takes interior vertices only per the API asymmetry).
+swmm_spatial_get_link_vertex_count	parity	via spatial.get_vertices (count derivable from returned list).
+swmm_spatial_get_subcatch_polygon	parity	via spatial.get_polygon.
+swmm_spatial_set_subcatch_polygon	parity	via spatial.set_polygon.
+swmm_spatial_get_subcatch_polygon_count	parity	via spatial.get_polygon (count derivable from returned list).
+swmm_spatial_get_node_coords_bulk	parity	via spatial.get_all_coordinates (element_type='node') and spatial.get_model_geometry.
+swmm_spatial_set_node_coords_bulk	parity	mcp-gap-bulk-write: no MCP tool currently writes node coords in bulk; per-node spatial.set_coordinates loop suffices for small models.
+
+# ----------------------------------------------------------------------------
+# Engine domain: lifecycle.* tools cover all session-managed ops. Events and
+# steady-state skip and the per-step callbacks are Python-level wrappers
+# without dedicated MCP tools today; flagged for a follow-up batch.
+# ----------------------------------------------------------------------------
+swmm_engine_create	intentional	SessionManager.create_session owns the engine lifecycle; no standalone tool.
+swmm_engine_destroy	intentional	SessionManager.close_session / cleanup_all own destruction.
+swmm_engine_initialize	parity	via lifecycle.open_model (calls initialize after open).
+swmm_engine_start	parity	via lifecycle.run_simulation / step_simulation (start before stepping).
+swmm_engine_end	parity	via lifecycle.run_simulation / close_model.
+swmm_engine_report	parity	via lifecycle.run_simulation (auto-reports at end) and analysis.get_report_snapshot.
+swmm_engine_run_with_callback	parity	via lifecycle.run_simulation (background-thread variant).
+swmm_engine_stride	parity	via lifecycle.step_simulation (num_steps parameter).
+swmm_get_start_time	parity	via lifecycle.get_simulation_time.
+swmm_get_end_time	parity	via lifecycle.get_simulation_time.
+swmm_get_routing_step	parity	via lifecycle.get_simulation_time.
+
+# Events + steady-state skip: closed in Phase 2 wave 2 (lifecycle.events_*
+# / get/set_steady_state_skip + lifecycle.is_between_events).
+swmm_events_count	parity	via lifecycle.events_count.
+swmm_events_get	parity	via lifecycle.events_get.
+swmm_events_add	parity	via lifecycle.events_add.
+swmm_events_set	parity	via lifecycle.events_set.
+swmm_events_remove	parity	via lifecycle.events_remove.
+swmm_events_clear	parity	via lifecycle.events_clear.
+swmm_is_between_events	parity	via lifecycle.is_between_events.
+swmm_get_steady_state_skip	parity	via lifecycle.get_steady_state_skip.
+swmm_set_steady_state_skip	parity	via lifecycle.set_steady_state_skip.
+
+# Per-step callbacks: Python methods exist on Solver but the
+# request/response MCP transport can't natively bridge an LLM-side
+# callback. Deferred to a Phase 4 callback-bridging tool that polls a
+# per-session event queue.
+swmm_set_warning_callback	intentional	MCP transport can't host LLM-side callbacks; bridge in Phase 4.
+swmm_set_step_begin_callback	intentional	MCP transport can't host LLM-side callbacks; bridge in Phase 4.
+swmm_set_step_end_callback	intentional	MCP transport can't host LLM-side callbacks; bridge in Phase 4.
+
+# ----------------------------------------------------------------------------
+# Gages domain: all coverage is already in editing.configure_gage (write),
+# query.get_gage_info (read), and forcing.set_rainfall_override (runtime).
+# editing.rename_gage closes the rename. Just need matcher overrides.
+# ----------------------------------------------------------------------------
+swmm_gage_count	parity	via lifecycle.open_model summary + query.find_elements counts.
+swmm_gage_id	parity	via query.get_gage_info / find_elements listings.
+swmm_gage_index	parity	via query.find_elements (string id -> index).
+swmm_gage_get_rain_type	parity	via query.get_gage_info (rain_type field).
+swmm_gage_get_data_source	parity	via query.get_gage_info.
+swmm_gage_get_rainfall	parity	via query.get_gage_info (current rate during running/ended).
+swmm_gage_get_rainfall_bulk	parity	via spatial.get_model_geometry / analysis.get_time_series with element_type='system'.
+swmm_gage_set_rain_type	parity	via editing.configure_gage (rain_type field).
+swmm_gage_set_data_source	parity	via editing.configure_gage (data_source field).
+swmm_gage_set_rain_interval	parity	via editing.configure_gage (rain_interval field).
+swmm_gage_set_filename	parity	via editing.configure_gage (filename + station_id fields).
+swmm_gage_set_rainfall	parity	via forcing.set_forcing (target='gage', variable='rainfall').
+
+# ----------------------------------------------------------------------------
+# Pollutants domain: query.get_pollutant_info handles id/index lookups.
+# ----------------------------------------------------------------------------
+swmm_pollutant_id	parity	via query.get_pollutant_info / find_elements.
+swmm_pollutant_index	parity	via query.find_elements (string id -> index).
+
+# ----------------------------------------------------------------------------
+# Model domain follow-up (Phase 2 wave 2 closed via model.* tools).
+# ----------------------------------------------------------------------------
+swmm_plugins_count	parity	via model.plugins_count.
+swmm_plugin_get	parity	via model.plugin_get.
+swmm_plugin_set	parity	via model.plugin_set.
+swmm_plugin_remove	parity	via model.plugin_remove.
+swmm_files_get	parity	via model.files_get.
+swmm_files_set	parity	via model.files_set.
+swmm_model_write_with_plugin	parity	via model.write_with_plugin.
+
+# ----------------------------------------------------------------------------
+# Hotstart domain: state-management methods are reachable via
+# hotstart.save_hotstart / load_hotstart / clone_session (load handles
+# open + apply + close internally); set_*_depth/flow/head/runoff modifiers
+# are exposed on the HotStart instance returned by load but no standalone
+# MCP tool wraps them. Mark covered where the aggregate handles them.
+# ----------------------------------------------------------------------------
+swmm_hotstart_open	parity	via hotstart.load_hotstart (opens + applies + closes internally).
+swmm_hotstart_close	intentional	HotStart lifecycle managed by load_hotstart's context.
+swmm_hotstart_apply	parity	via hotstart.load_hotstart (calls apply after open).
+swmm_hotstart_get_crs	parity	via hotstart.load_hotstart result includes crs.
+swmm_hotstart_get_sim_time	parity	via hotstart.load_hotstart result includes sim_time.
+swmm_hotstart_node_count	parity	via hotstart.load_hotstart result includes node_count.
+swmm_hotstart_link_count	parity	via hotstart.load_hotstart result includes link_count.
+swmm_hotstart_warning_count	parity	via hotstart.load_hotstart result includes warnings list (count derivable).
+swmm_hotstart_set_node_depth	mcp-gap	State-modify-then-apply pattern; no standalone tool. Phase 4 follow-up.
+swmm_hotstart_set_node_head	mcp-gap	Same as set_node_depth.
+swmm_hotstart_set_link_depth	mcp-gap	Same pattern.
+swmm_hotstart_set_link_flow	mcp-gap	Same pattern.
+swmm_hotstart_set_subcatch_runoff	mcp-gap	Same pattern.
+swmm_hotstart_saves_get_path	parity	via hotstart.saves_get (returns path + datetime).
+swmm_hotstart_saves_get_datetime	parity	via hotstart.saves_get.
+swmm_hotstart_saves_set_path	parity	via hotstart.saves_set (path field).
+swmm_hotstart_saves_set_datetime	parity	via hotstart.saves_set (datetime_oadate field).
+
+# ----------------------------------------------------------------------------
+# GeoPackage domain: high-level aggregate tools cover most C functions.
+# ----------------------------------------------------------------------------
+swmm_gpkg_register	intentional	Registration handled internally when opening; no standalone tool.
+swmm_gpkg_is_registered	intentional	Same.
+swmm_gpkg_begin	intentional	Transaction lifecycle owned by individual write tools.
+swmm_gpkg_commit	intentional	Same.
+swmm_gpkg_rollback	intentional	Same.
+swmm_gpkg_last_error	intentional	Errors surface as ToolError directly; no separate query tool.
+swmm_gpkg_query_int	intentional	Direct SQL escape hatch; intentionally not exposed (security risk + LLM use case mismatch).
+swmm_gpkg_query_double	intentional	Same.
+swmm_gpkg_simulation_count	parity	via geopackage.list_simulations (returns count + ids).
+swmm_gpkg_topology_edge_count	parity	via geopackage.list_simulations result includes object_counts.
+swmm_gpkg_variable_count	parity	via geopackage.get_result_summary (lists available variables).
+swmm_gpkg_result_ts_count	parity	via geopackage.get_result_timeseries (count derivable from response).
+swmm_gpkg_read_result_ts	parity	via geopackage.get_result_timeseries.
+swmm_gpkg_read_summary	parity	via geopackage.get_result_summary.
+swmm_gpkg_create_observed_series	parity	via geopackage.import_observed_data.
+swmm_gpkg_write_observed_value	parity	via geopackage.import_observed_data (batched).
+swmm_gpkg_write_observed_values	parity	via geopackage.import_observed_data.
+swmm_gpkg_observed_series_count	parity	via geopackage.compare_sim_vs_observed (lists observed series).
+swmm_gpkg_observed_value_count	parity	via geopackage.compare_sim_vs_observed.
+swmm_gpkg_read_observed_values	parity	via geopackage.compare_sim_vs_observed.
+
+# ----------------------------------------------------------------------------
+# True py-gaps confirmed (Phase 1 implementation targets).
+# Listed here only when they need a richer note than the default classification.
+# Leaving them out keeps the auto status `py-gap`.
+# ----------------------------------------------------------------------------
diff --git a/plans/parity/provenance_gaps.json b/plans/parity/provenance_gaps.json
new file mode 100644
index 000000000..ec9e550d2
--- /dev/null
+++ b/plans/parity/provenance_gaps.json
@@ -0,0 +1,8 @@
+{
+  "counts": {},
+  "gaps": {},
+  "gym_reach": {
+    "reached": 472,
+    "total": 1173
+  }
+}
diff --git a/plans/parity/tools/build_matrix_provenance.py b/plans/parity/tools/build_matrix_provenance.py
new file mode 100644
index 000000000..489cc9f25
--- /dev/null
+++ b/plans/parity/tools/build_matrix_provenance.py
@@ -0,0 +1,429 @@
+#!/usr/bin/env python3
+"""Call-graph *provenance* parity matrix — the low-false-positive successor
+to the fuzzy ``build_matrix.py``.
+
+Motivation
+----------
+The fuzzy matcher (``build_matrix.py``) matches C functions to Python methods
+by guessing name variants (verb-object reversal, ``get_``/``set_`` promotion,
+etc.). On the 2026-07-06 tree it produced **358 "py-gap" rows that are all
+false** — every one of those C functions *is* wrapped, the matcher just
+couldn't guess the Python name. That makes its py-gap / mcp-gap counts
+unusable as a drift signal.
+
+This builder derives the mapping from the **actual call graph** instead of
+name similarity, so there are essentially no false positives:
+
+  * C -> Python is *exact*: a Cython wrapper must call the C symbol by name,
+    so we parse each ``.pyx`` method body for ``swmm_*`` calls and attribute
+    them to the enclosing ``def``. Inverting gives, per C symbol, the exact
+    wrapping method(s).
+  * Python -> MCP is *catalog-reachable*: the MCP server (v2) dispatches any
+    member listed in ``openswmm.engine.catalog`` through its generic tools, so
+    a C symbol is MCP-reachable when a catalogued member (other than the
+    callback setters, which cannot cross MCP) lists it among its C symbols.
+  * Python -> Gymnasium is *catalog-reachable* for the C symbols behind
+    numeric element fields (observable and actuatable by catalog path), plus
+    a name-precise scan of the adapter for anything it calls directly.
+
+Outputs ``provenance_matrix.md`` and ``provenance_gaps.json`` next to the
+fuzzy artefacts (additive — it does not touch ``parity_matrix.md``).
+
+``--check`` exits non-zero if any C symbol has **no** Python wrapper and is
+not an intentional non-exposure (the real, reliable drift guard).
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+PARITY_DIR = Path(__file__).resolve().parents[1]
+REPO_ROOT = PARITY_DIR.parents[1]
+ENGINE_DIR = REPO_ROOT / "python" / "openswmm" / "engine"
+HEADER_DIR = REPO_ROOT / "include" / "openswmm" / "engine"
+OVERRIDES_TSV = PARITY_DIR / "overrides.tsv"
+CATALOG_JSON = ENGINE_DIR / "catalog.json"
+GYM_SRC_DEFAULT = (REPO_ROOT.parent / "openswmm.gymnasium" / "src"
+                   / "openswmm_gymnasium")
+MATRIX_MD = PARITY_DIR / "provenance_matrix.md"
+GAPS_JSON = PARITY_DIR / "provenance_gaps.json"
+
+# Share the strict tokenizer with the release gate: comments, strings and
+# declarations do not establish reachability; .pxd helpers do.
+import importlib.util
+_spec = importlib.util.spec_from_file_location("_binding_audit", REPO_ROOT / "python/scripts/api_drift_audit.py")
+_audit = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_audit)
+
+_SWMM_TOKEN = re.compile(r"\b(swmm_[a-z0-9_]+)\b")
+_SWMM_CALL = re.compile(r"\b(swmm_[a-z0-9_]+)\s*\(")
+_CDEF_EXTERN = re.compile(r"cdef\s+extern\b")
+_CLASS_RE = re.compile(r"^(?P\s*)(?:cdef\s+)?class\s+(?P\w+)")
+_DEF_RE = re.compile(r"^(?P\s*)(?:cdef|cpdef|def)\s+(?:[\w\.\[\], \*]+?\s+)??(?P\w+)\s*\(")
+
+
+# ---------------------------------------------------------------------------
+# C side
+# ---------------------------------------------------------------------------
+def c_symbols() -> dict[str, str]:
+    """Return {c_function: domain} for every SWMM_ENGINE_API export."""
+    return {fn: Path(header).stem.removeprefix("openswmm_")
+            for fn, header in _audit.collect_c_functions().items()}
+
+
+
+# ---------------------------------------------------------------------------
+# C -> Python (exact, via .pyx call graph)
+# ---------------------------------------------------------------------------
+def pyx_callgraph() -> dict[str, set[tuple[str, str, str]]]:
+    """Return {c_symbol: {(module, class, method), ...}} from real call sites."""
+    c_to_py: dict[str, set[tuple[str, str, str]]] = defaultdict(set)
+    for pyx in sorted([*ENGINE_DIR.glob("*.pyx"), *ENGINE_DIR.glob("*.pxd")]):
+        module = pyx.stem
+        scopes: list[tuple[int, str, str]] = []   # (indent, kind, name)
+        in_extern = False
+        extern_indent = 0
+        for raw in _audit.executable_cython(pyx.read_text(encoding="utf-8")).splitlines():
+            code = raw.split("#", 1)[0]
+            if not code.strip():
+                continue
+            indent = len(code) - len(code.lstrip())
+            if _CDEF_EXTERN.match(code.strip()):
+                in_extern = True
+                extern_indent = indent
+                continue
+            if in_extern:
+                if indent <= extern_indent:
+                    in_extern = False
+                else:
+                    continue
+            cm = _CLASS_RE.match(code)
+            if cm:
+                ci = len(cm.group("i"))
+                while scopes and scopes[-1][0] >= ci:
+                    scopes.pop()
+                scopes.append((ci, "class", cm.group("name")))
+                continue
+            dm = _DEF_RE.match(code)
+            if dm:
+                di = len(dm.group("i"))
+                while scopes and scopes[-1][0] >= di:
+                    scopes.pop()
+                scopes.append((di, "def", dm.group("name")))
+                continue
+            calls = _SWMM_TOKEN.findall(code)
+            if not calls:
+                continue
+            # attribute to the innermost def scope; enclosing class = nearest
+            # class scope beneath it.
+            cur_def = next((s for s in reversed(scopes) if s[1] == "def"), None)
+            cur_cls = next((s for s in reversed(scopes) if s[1] == "class"), None)
+            method = cur_def[2] if cur_def else ""
+            cls = cur_cls[2] if cur_cls else ""
+            for sym in calls:
+                c_to_py[sym].add((module, cls, method))
+    return c_to_py
+
+
+# ---------------------------------------------------------------------------
+# Catalog reach (MCP and Gymnasium)
+# ---------------------------------------------------------------------------
+_NUMERIC = {"float", "int", "bool"}
+
+
+def catalog_reach() -> tuple[set[str], set[str]]:
+    """Return (C symbols the MCP reaches, C symbols behind numeric element fields).
+
+    Empty sets when the catalog has not been generated yet.
+    """
+    if not CATALOG_JSON.is_file():
+        return set(), set()
+    cat = json.loads(CATALOG_JSON.read_text(encoding="utf-8"))
+    targets = cat["targets"]
+
+    def element_kind(target: str) -> bool:
+        entry = targets.get(target, {})
+        while "collection" not in entry:
+            parent = entry.get("parent")
+            if parent is None or parent not in targets:
+                return False
+            entry = targets[parent]
+        return True
+
+    skip: set[str] = set()
+    mcp: set[str] = set()
+    fields: set[str] = set()
+    for name, t in targets.items():
+        if name not in skip:
+            mcp |= set(t.get("c", []))
+    for funcs in cat.get("functions", {}).values():
+        for f in funcs.values():
+            mcp |= set(f.get("c", []))
+    for m in cat["members"]:
+        syms = set(m.get("c", []))
+        if m["target"] in skip or (m["target"] == "solver" and m["name"].endswith("_callback")):
+            continue  # Python callables cannot cross MCP
+        mcp |= syms
+        if m["form"] == "property" and m.get("type") in _NUMERIC and element_kind(m["target"]):
+            fields |= syms
+    return mcp, fields
+
+
+# C functions with no meaning over MCP, and why. They are reported as
+# ``mcp-na`` instead of ``mcp-review``.
+MCP_NOT_APPLICABLE = {
+    "swmm_set_progress_callback": "Python callables cannot cross MCP.",
+    "swmm_set_step_begin_callback": "Python callables cannot cross MCP.",
+    "swmm_set_step_end_callback": "Python callables cannot cross MCP.",
+    "swmm_set_warning_callback": "Python callables cannot cross MCP.",
+    "swmm_engine_run": "One-shot run; the MCP run tool steps the session instead.",
+    "swmm_engine_run_with_callback": "One-shot run with a callback; see swmm_engine_run.",
+    "swmm_error_message": "Error text; every MCP error already carries it.",
+    "swmm_gpkg_register": "The GeoPackage plugin registers itself on import.",
+    "swmm_gpkg_is_registered": "The GeoPackage plugin registers itself on import.",
+    "swmm_transport_class_name": "Enum-to-name helper; describe('enum:TransportClass').",
+    "swmm_transport_domain_name": "Enum-to-name helper; describe('enum:TransportDomain').",
+    "swmm_xsect_shape_name": "Enum-to-name helper; describe('enum:XSectShape').",
+}
+
+
+# Explicit provenance marker a gymnasium module (or .pyx wrapper) can carry to
+# pin exact coverage, e.g. ``# wraps: swmm_forcing_link_flow``.
+_WRAPS_RE = re.compile(r"wraps:\s*((?:swmm_[a-z0-9_]+\s*,?\s*)+)", re.IGNORECASE)
+
+
+def _py_refs(paths: list[Path]) -> tuple[set[str], set[str], set[str]]:
+    """Return (attribute_names, bare_names, explicitly_wrapped_c_symbols)."""
+    attrs: set[str] = set()
+    names: set[str] = set()
+    wrapped: set[str] = set()
+    for p in paths:
+        src = p.read_text(encoding="utf-8")
+        for m in _WRAPS_RE.finditer(src):
+            wrapped.update(re.findall(r"swmm_[a-z0-9_]+", m.group(1)))
+        try:
+            tree = ast.parse(src)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Attribute):
+                attrs.add(node.attr)
+            elif isinstance(node, ast.Name):
+                names.add(node.id)
+    return attrs, names, wrapped
+
+
+def gym_refs(gym_src: Path) -> tuple[set[str], set[str], set[str]]:
+    """Return the same triple for the gymnasium adapter surface.
+
+    ``openswmm.gymnasium`` reaches the engine through exactly one module --
+    ``_engine/solver_adapter.py``, a hand-written per-method shim. Everything
+    else in the package takes a ``SolverAdapter``. Scanning the whole package
+    would therefore report the adapter's *own* method names as engine
+    coverage; scanning only the adapter is the honest signal.
+
+    Any other module that imports ``openswmm`` directly is included too, so
+    that a new bypass of the choke point shows up rather than hiding.
+    """
+    adapter = gym_src / "_engine" / "solver_adapter.py"
+    paths = [adapter] if adapter.is_file() else []
+    for p in sorted(gym_src.rglob("*.py")):
+        if p == adapter:
+            continue
+        src = p.read_text(encoding="utf-8")
+        if re.search(r"^\s*(from|import)\s+openswmm\b", src, re.MULTILINE):
+            paths.append(p)
+    return _py_refs(paths)
+
+
+# ---------------------------------------------------------------------------
+# Overrides (reused verbatim from the fuzzy builder's format)
+# ---------------------------------------------------------------------------
+def load_overrides() -> dict[str, tuple[str, str]]:
+    out: dict[str, tuple[str, str]] = {}
+    if not OVERRIDES_TSV.is_file():
+        return out
+    for line in OVERRIDES_TSV.read_text(encoding="utf-8").splitlines():
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            out[parts[0].strip()] = (parts[1].strip(),
+                                     parts[2].strip() if len(parts) > 2 else "")
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+def build(gym_src: Path | None = None) -> list[dict]:
+    csyms = c_symbols()
+    c_to_py = pyx_callgraph()
+    mcp_reach, field_reach = catalog_reach()
+    if gym_src is not None and gym_src.is_dir():
+        gym_attrs, gym_names, gym_wrapped = gym_refs(gym_src)
+    else:
+        gym_attrs, gym_names, gym_wrapped = set(), set(), set()
+    overrides = load_overrides()
+
+    # binding method-name universe (from the call graph) so the gymnasium
+    # name scan is restricted to real binding methods.
+    binding_methods = {m for tgts in c_to_py.values() for (_, _, m) in tgts}
+
+    rows: list[dict] = []
+    for fn, domain in sorted(csyms.items()):
+        ov_status, ov_note = overrides.get(fn, ("", ""))
+        py = sorted(c_to_py.get(fn, set()))
+        py_methods = {m for (_, _, m) in py}
+        py_classes = {c for (_, c, _) in py if c}
+
+        mcp = "catalog" if fn in mcp_reach else "none"
+
+        # Gymnasium reach. Advisory only: gymnasium is an RL surface, not an
+        # API mirror, so "none" is the expected default and is never a gate.
+        gym_explicit = fn in gym_wrapped
+        gym_heuristic = bool(
+            (py_methods & gym_attrs & binding_methods)
+            or (py_classes & (gym_names | gym_attrs))
+        )
+        gym = ("exact" if gym_explicit else "field" if fn in field_reach
+               else "heuristic" if gym_heuristic else "none")
+
+        if fn in _audit.KNOWN_UNBOUND:
+            status = "intentional"
+        elif not py:
+            status = "py-gap"                       # REAL, exact: no wrapper
+        elif mcp == "catalog":
+            status = "parity"
+        elif fn in MCP_NOT_APPLICABLE:
+            status = "mcp-na"
+            ov_note = ov_note or MCP_NOT_APPLICABLE[fn]
+        elif domain == "2d":
+            status = "mcp-review-2d"                # advisory (2D build-cond.)
+        else:
+            status = "mcp-review"                   # advisory candidate
+        rows.append(dict(function=fn, domain=domain,
+                         py=[f"{mod}.{c + '.' if c else ''}{m}" for (mod, c, m) in py],
+                         mcp=mcp, gym=gym, status=status, note=ov_note))
+    return rows
+
+
+def render_markdown(rows: list[dict], fuzzy_pygaps: int | None) -> str:
+    buf: list[str] = []
+    buf.append("# C ↔ Python ↔ MCP Parity Matrix — provenance (call-graph) build\n")
+    buf.append("Generated by `plans/parity/tools/build_matrix_provenance.py`. "
+               "Unlike `parity_matrix.md` (fuzzy name matching), the Python "
+               "column here is the **exact** wrapper derived from `.pyx` call "
+               "sites, so `py-gap` means a genuinely unwrapped C function.\n")
+    buf.append("**Reliability tiers:**\n")
+    buf.append("- `py-gap` / `parity` (C↔Python) — **exact**: a wrapper either "
+               "calls the C symbol or it doesn't. Trust these; `--check` gates on "
+               "`py-gap`.\n")
+    buf.append("- MCP column — `catalog` means catalog-reachable: the MCP "
+               "server's generic tools dispatch every member of "
+               "`openswmm.engine.catalog`, and a catalogued member lists this "
+               "C symbol. `mcp-na` rows have no meaning over MCP (the note "
+               "says why); `mcp-review*` rows are wrapped in Python but reached "
+               "by no catalogued member.\n")
+    totals: dict[str, int] = defaultdict(int)
+    mcp_tier: dict[str, int] = defaultdict(int)
+    for r in rows:
+        totals[r["status"]] += 1
+        mcp_tier[r["mcp"]] += 1
+    buf.append("## Summary\n")
+    buf.append("| Status | Count |")
+    buf.append("|---|---:|")
+    for s in ["parity", "py-gap", "mcp-review", "mcp-review-2d", "mcp-na",
+              "intentional", "internal"]:
+        buf.append(f"| `{s}` | {totals.get(s, 0)} |")
+    buf.append(f"| **Total** | **{len(rows)}** |\n")
+    buf.append(f"MCP reach: `catalog` {mcp_tier.get('catalog', 0)}, "
+               f"`none` {mcp_tier.get('none', 0)}.\n")
+    gym_tier: dict[str, int] = defaultdict(int)
+    for r in rows:
+        gym_tier[r.get("gym", "none")] += 1
+    reached = len(rows) - gym_tier.get("none", 0)
+    buf.append(f"Gymnasium reach: **{reached}** of {len(rows)} C symbols are "
+               f"reachable (`field` — behind a numeric element field, "
+               f"{gym_tier.get('field', 0)}; `exact` {gym_tier.get('exact', 0)}; "
+               f"`heuristic` {gym_tier.get('heuristic', 0)}). This column is "
+               f"**advisory and never gated** — gymnasium is an RL surface, not "
+               f"an API mirror, so most of the C API is legitimately out of "
+               f"scope. It is tracked so that a capability the RL layer *should* "
+               f"have adopted does not go unnoticed.\n")
+    if fuzzy_pygaps is not None:
+        buf.append(f"> Fuzzy `build_matrix.py` reported **{fuzzy_pygaps}** py-gaps "
+                   f"on the same tree; provenance reports **{totals.get('py-gap', 0)}** "
+                   f"real py-gaps (false-positive reduction: "
+                   f"{fuzzy_pygaps - totals.get('py-gap', 0)}).\n")
+
+    by_domain: dict[str, list[dict]] = defaultdict(list)
+    for r in rows:
+        by_domain[r["domain"]].append(r)
+    buf.append("## Per-domain counts\n")
+    buf.append("| Domain | C funcs | parity | py-gap | mcp-gap | other |")
+    buf.append("|---|---:|---:|---:|---:|---:|")
+    for d in sorted(by_domain):
+        dr = by_domain[d]
+        par = sum(1 for r in dr if r["status"] == "parity")
+        pg = sum(1 for r in dr if r["status"] == "py-gap")
+        mg = sum(1 for r in dr if r["status"] in ("mcp-review", "mcp-review-2d"))
+        buf.append(f"| `{d}` | {len(dr)} | {par} | {pg} | {mg} | "
+                   f"{len(dr) - par - pg - mg} |")
+    buf.append("")
+    for d in sorted(by_domain):
+        buf.append(f"## Domain: `{d}`\n")
+        buf.append("| C function | Python (call-graph) | MCP | Gym | Status | Note |")
+        buf.append("|---|---|---|---|---|---|")
+        for r in sorted(by_domain[d], key=lambda x: x["function"]):
+            pycell = ", ".join(f"`{p}`" for p in r["py"]) or "—"
+            buf.append(f"| `{r['function']}` | {pycell} | {r['mcp']} | "
+                       f"{r.get('gym', 'none')} | `{r['status']}` | {r['note']} |")
+        buf.append("")
+    return "\n".join(buf) + "\n"
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--gym-root", type=Path, default=GYM_SRC_DEFAULT,
+                    help="openswmm_gymnasium package root (advisory column)")
+    ap.add_argument("--check", action="store_true",
+                    help="exit non-zero if any real py-gap exists")
+    ap.add_argument("--fuzzy-pygaps", type=int, default=None,
+                    help="py-gap count from build_matrix.py, for the comparison note")
+    args = ap.parse_args(argv[1:])
+
+    rows = build(args.gym_root)
+    MATRIX_MD.write_text(render_markdown(rows, args.fuzzy_pygaps), encoding="utf-8")
+
+    summary: dict[str, list[str]] = defaultdict(list)
+    for r in rows:
+        if r["status"] in ("py-gap", "mcp-review", "mcp-review-2d"):
+            summary[r["status"]].append(r["function"])
+    gym_reached = sum(1 for r in rows if r.get("gym", "none") != "none")
+    GAPS_JSON.write_text(json.dumps(
+        {"counts": {k: len(v) for k, v in summary.items()},
+         "gym_reach": {"reached": gym_reached, "total": len(rows)},
+         "gaps": dict(summary)}, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    totals: dict[str, int] = defaultdict(int)
+    for r in rows:
+        totals[r["status"]] += 1
+    print(f"Wrote {MATRIX_MD.name} and {GAPS_JSON.name}.", file=sys.stderr)
+    print(f"Status counts: {dict(totals)}", file=sys.stderr)
+
+    real_pygaps = [r["function"] for r in rows if r["status"] == "py-gap"]
+    if args.check and real_pygaps:
+        print(f"error: {len(real_pygaps)} real py-gap(s): {real_pygaps}",
+              file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt
index b9ee9533c..35dce5e69 100644
--- a/python/CMakeLists.txt
+++ b/python/CMakeLists.txt
@@ -57,31 +57,34 @@ if(NOT DEFINED CACHE{VCPKG_MANIFEST_DIR})
 endif()
 
 # ============================================================================
-# Base wheel stays CPU-only / portable.
+# Base wheel builds the Kokkos-OpenMP plugin, like every other build.
 #
-# As of the GPU-default-on change, the engine vcpkg.json lists "gpu" in
-# default-features (pulling Kokkos) and OPENSWMM_BUILD_GPU_PLUGIN
-# defaults ON. That is right for source/dev/C++-release builds, but the published
-# `openswmm` wheel must remain Kokkos-free and portable: OpenMP acceleration is
-# shipped separately via the `openswmm-gpu-omp` companion wheel (see
-# packages/gpu-omp/ and the discovery shim in openswmm/__init__.py).
+# The engine's vcpkg.json lists "gpu" in default-features (pulling Kokkos) and
+# OPENSWMM_BUILD_GPU_PLUGIN defaults ON. The wheel follows that default rather
+# than opting out of it: OpenMP acceleration of the 2D surface solver is a
+# shipped default everywhere, not something a user has to go and find.
 #
-# So, unless the builder explicitly overrides them, opt the wheel out of the gpu
-# feature here — BEFORE project() loads the vcpkg toolchain, which reads these.
-# A developer who wants a GPU-enabled local build passes the trio explicitly
-# (e.g. CMAKE_ARGS="-DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON
-#  -DVCPKG_MANIFEST_FEATURES=2d;gpu -DOPENSWMM_BUILD_GPU_PLUGIN=ON").
+# The `openswmm-gpu-omp` companion wheel (packages/gpu-omp/) still exists and
+# still builds the same plugin — it remains the way to add or refresh the
+# plugin against an already-installed base. Both copies are the same artifact
+# from the same source; the discovery shim in openswmm/__init__.py prefers the
+# in-wheel one, so exactly one is ever dlopen()ed (see the note there about
+# OpenMP runtimes).
+#
+# The features are still pinned explicitly rather than left to
+# default-features, so the wheel's dependency set is stated here and does not
+# silently follow a future edit of vcpkg.json.
 # ============================================================================
 if(NOT DEFINED CACHE{VCPKG_MANIFEST_NO_DEFAULT_FEATURES})
     set(VCPKG_MANIFEST_NO_DEFAULT_FEATURES ON CACHE BOOL
-        "Base wheel opts out of vcpkg default-features (excludes gpu/Kokkos)" FORCE)
+        "Wheel states its vcpkg features explicitly instead of following default-features" FORCE)
 endif()
 if(NOT DEFINED CACHE{VCPKG_MANIFEST_FEATURES})
-    # 2d → HDF5 for the CF-1.11/UGRID output of the explicit marcher (the only
-    #      2D integrator since the D2 retirement — no SUNDIALS, no hypre).
-    #      Keeps the wheel CPU-only/Kokkos-free.
-    set(VCPKG_MANIFEST_FEATURES "2d" CACHE STRING
-        "Explicit vcpkg features for the CPU-only base wheel (2d)" FORCE)
+    # 2d  → HDF5 for the CF-1.11/UGRID output of the explicit marcher (the only
+    #       2D integrator since the D2 retirement — no SUNDIALS, no hypre).
+    # gpu → Kokkos, for the OpenMP surface-solver plugin built below.
+    set(VCPKG_MANIFEST_FEATURES "2d;gpu" CACHE STRING
+        "Explicit vcpkg features for the base wheel (2d, gpu)" FORCE)
 endif()
 
 # Auto-load vcpkg toolchain when VCPKG_ROOT is set in the environment.
@@ -139,10 +142,25 @@ else()
     set(OPENSWMM_BUILD_REGRESSION_TESTS  OFF CACHE BOOL "" FORCE)
     set(OPENSWMM_BUILD_BENCHMARKS        OFF CACHE BOOL "" FORCE)
     set(OPENSWMM_BUILD_PYTHON            OFF CACHE BOOL "" FORCE)
-    # Base wheel is CPU-only (companion-out): never build the Kokkos GPU plugin
-    # into the engine here. Pairs with the vcpkg gpu-feature opt-out above.
+    # Build the Kokkos-OpenMP surface plugin into the wheel. Pairs with the
+    # "gpu" vcpkg feature selected above.
     if(NOT DEFINED CACHE{OPENSWMM_BUILD_GPU_PLUGIN})
-        set(OPENSWMM_BUILD_GPU_PLUGIN    OFF CACHE BOOL "" FORCE)
+        set(OPENSWMM_BUILD_GPU_PLUGIN    ON CACHE BOOL "" FORCE)
+    endif()
+    # The plugin is dlopen()ed by path, so it has to land inside the import
+    # package rather than at the engine's installed-tree default of lib/ (or
+    # bin/ on Windows) — src/engine/2d/gpu/CMakeLists.txt exposes this cache
+    # variable for exactly this purpose, and packages/gpu-omp/ overrides it the
+    # same way to its own package dir.
+    #
+    # openswmm/engine specifically: it is where openswmm_engine and its bundled
+    # runtime dependencies (libomp included) already install, so the plugin sits
+    # beside the one libomp copy the wheel carries — the arrangement the macOS
+    # @rpath rewrite in the engine's plugin CMake assumes — and the factory's
+    # engine-directory search finds it with no environment variable at all.
+    if(NOT DEFINED CACHE{OPENSWMM_GPU_PLUGIN_INSTALL_DESTINATION})
+        set(OPENSWMM_GPU_PLUGIN_INSTALL_DESTINATION "openswmm/engine"
+            CACHE STRING "" FORCE)
     endif()
 
     # Disable WINDOWS_EXPORT_ALL_SYMBOLS: the cmake -E __create_def step
diff --git a/python/LICENSE b/python/LICENSE
index f44af6b10..bd27b19f9 100644
--- a/python/LICENSE
+++ b/python/LICENSE
@@ -1,9 +1,203 @@
-MIT License
+Copyright 2026 HydroCouple Developers
 
-Copyright 2026 Caleb Buahin
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+   1. Definitions.
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/python/NOTICE b/python/NOTICE
new file mode 100644
index 000000000..7a406d8c0
--- /dev/null
+++ b/python/NOTICE
@@ -0,0 +1,35 @@
+OpenSWMM Python Bindings
+Copyright 2026 HydroCouple Developers
+
+This product includes software developed by the OpenSWMM authors
+(https://github.com/HydroCouple/openswmm.engine).
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file for the
+full license text.
+
+--------------------------------------------------------------------------------
+PUBLIC DOMAIN MATERIAL
+--------------------------------------------------------------------------------
+
+These bindings wrap, and binary distributions of this package embed, the
+OpenSWMM Engine. Portions of that engine are derived from the Storm Water
+Management Model (SWMM) developed and released by the United States
+Environmental Protection Agency (USEPA). That material was prepared by or for
+the United States Government and resides in the public domain: domestic
+copyright protection is not available for it under 17 USC § 105, and no
+copyright is claimed over it by the OpenSWMM authors.
+
+The Apache License, Version 2.0 applies to the original contributions of the
+OpenSWMM authors. It does not extend copyright to, and places no restriction
+on, the public domain material described above.
+
+The USEPA does not endorse this product, and the names "EPA", "USEPA", and
+"SWMM" are used solely to describe the origin of the public domain material.
+
+--------------------------------------------------------------------------------
+THIRD-PARTY COMPONENTS
+--------------------------------------------------------------------------------
+
+Binary wheels of this package may bundle third-party libraries required by the
+OpenSWMM Engine. Each such component remains subject to its own license terms,
+which accompany the component in the wheel.
diff --git a/python/README.md b/python/README.md
index 1539bf386..82456104e 100644
--- a/python/README.md
+++ b/python/README.md
@@ -10,7 +10,7 @@
 [![Unit Testing Python](https://github.com/HydroCouple/openswmm.engine/actions/workflows/unit_testing_python.yml/badge.svg)](https://github.com/HydroCouple/openswmm.engine/actions/workflows/unit_testing_python.yml)
 [![Documentation](https://github.com/HydroCouple/openswmm.engine/actions/workflows/documentation.yml/badge.svg)](https://github.com/HydroCouple/openswmm.engine/actions/workflows/documentation.yml)
 [![Issues](https://img.shields.io/github/issues/HydroCouple/openswmm.engine)](https://github.com/HydroCouple/openswmm.engine/issues)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/openswmm.svg)](https://pypi.org/project/openswmm)
 [![Downloads](https://pepy.tech/badge/openswmm)](https://pepy.tech/project/openswmm)
 [![Python](https://img.shields.io/pypi/pyversions/openswmm.svg)](https://pypi.org/project/openswmm)
@@ -20,13 +20,37 @@
 
 | | Site | Contents |
 |---|---|---|
-| **C / C++ Engine** | **[hydrocouple.org/openswmm.engine](https://hydrocouple.org/openswmm.engine)** | Full C API reference, hydrology / hydraulics / water-quality reference manuals, user manual, architecture notes. |
+| **C / C++ Engine** | **[hydrocouple.org/openswmm.engine](https://hydrocouple.org/openswmm.engine)** | Full C API reference, hydrology / hydraulics / water-quality reference manuals, engine manual (input format, files, reports, C API), architecture notes. |
 | **Python Bindings** | **[hydrocouple.org/openswmm.engine/python](https://hydrocouple.org/openswmm.engine/python)** | Quickstart, per-domain user guide, Cython API reference, SWMM 5 → v6 migration. |
 
 Both sites cross-link from their top navigation.
 
 ---
 
+## Python API coverage and testing
+
+The modern bindings include groundwater authoring/results and transport,
+surface-quality tables, transport capability diagnostics, batch editing and
+live output reading. Guides document their units, lifecycle and immutable
+snapshot behavior under `python/docs/guide/`. The strict API coverage check is
+`python python/scripts/api_drift_audit.py --strict` from the repository root.
+
+For local validation use the `openswmm` Conda environment. After building and
+installing to a staging prefix, run
+`conda run -n openswmm python python/scripts/test_staged_package.py STAGE python/tests --ignore=python/tests/typing`.
+This verifies the selected native binaries and avoids an editable install
+silently redirecting tests to an older extension. CI runs the complete modern,
+legacy and top-level suites against built wheels, plus independent source and
+typing gates. Source reachability is not a claim of numerical validation.
+
+`openswmm.engine.catalog` is a machine-readable map of this API: every target
+reachable from a `Solver` (services such as `forcing`, element kinds such as
+`node` and sub-views such as `node.stats`) with each property's type, access,
+units and lifecycle phases, and each method's signature. The MCP server and
+gymnasium use it to reach the whole API without per-function code. It is
+generated by `python python/scripts/gen_catalog.py`; CI runs the same script
+with `--check` and fails when the catalog is stale or a class is unreachable.
+
 ## Overview
 
 OpenSWMM Engine is a community-driven, open-source continuation of the EPA Storm Water Management Model — a dynamic hydrology, hydraulic, and water-quality simulator for urban runoff. The project preserves the SWMM legacy under QA/QC and builds the community needed for long-term maintenance, working with ASCE/EWRI and the Water Environment Federation.
@@ -211,7 +235,7 @@ Signing is automated through [CLA Assistant](https://cla-assistant.io) — when
 
 ## License
 
-MIT — see [LICENSE](LICENSE). Original EPA SWMM material is in the public domain under 17 USC § 105.
+Apache License, Version 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Original EPA SWMM material is in the public domain under 17 USC § 105 and is not subject to the Apache license grant.
 
 ## Acknowledgements
 
diff --git a/python/cmake/CythonHelpers.cmake b/python/cmake/CythonHelpers.cmake
index 4767d0340..330f5164e 100644
--- a/python/cmake/CythonHelpers.cmake
+++ b/python/cmake/CythonHelpers.cmake
@@ -118,6 +118,9 @@ function(add_cython_extension)
     # `datetime`'s namespace and breaking every later `datetime.date(...)`
     # call.  ${_gen_dir} only ever contains Cython output, never importable
     # top-level names that could shadow the stdlib.
+    # Shared extension layouts and declarations must invalidate consumers.
+    file(GLOB_RECURSE _pxd_deps CONFIGURE_DEPENDS
+         "${PROJECT_SOURCE_DIR}/openswmm/*.pxd")
     add_custom_command(
         OUTPUT  "${_cxx_out}"
         COMMAND ${OPENSWMM_CYTHON_EXECUTABLE}
@@ -127,7 +130,7 @@ function(add_cython_extension)
                 "${_pyx_abs}"
                 --output-file "${_cxx_out}"
         WORKING_DIRECTORY "${_gen_dir}"
-        DEPENDS "${_pyx_abs}"
+        DEPENDS "${_pyx_abs}" ${_pxd_deps}
         COMMENT "Cythonizing ${ACE_SOURCE} → ${ACE_NAME}.cxx"
         VERBATIM
     )
diff --git a/python/docs/LEGACY_API_EXPANSION_PLAN.md b/python/docs/LEGACY_API_EXPANSION_PLAN.md
deleted file mode 100644
index 97ccdeeb4..000000000
--- a/python/docs/LEGACY_API_EXPANSION_PLAN.md
+++ /dev/null
@@ -1,586 +0,0 @@
-# Legacy SWMM Python API Expansion Plan
-
-**Status:** All Phases Complete (1-4)
-**Date:** 2026-03-25
-**Last Updated:** 2026-03-25
-**Package:** `openswmm.legacy.engine` / `openswmm.legacy.output`
-
----
-
-## 1. Objective
-
-Validate the existing legacy C API (`openswmm_solver.h`) against the Python
-bindings (`_solver.pyx`), identify gaps compared to the PySWMM ecosystem, and
-expand the Python API to provide full coverage of all SWMM element types with
-proper mass-balance and flux tracking.
-
----
-
-## 2. Current State Audit
-
-### 2.1 C API Functions (openswmm_solver.h) — 27 functions
-
-| C Function | Python Binding | Notes |
-|------------|---------------|-------|
-| `swmm_run` | `run_solver()` | OK |
-| `swmm_run_with_callback` | `run_solver(callback=)` | OK |
-| `swmm_open` | `Solver.open()` | OK |
-| `swmm_start` | `Solver.start()` | OK |
-| `swmm_step` | `Solver.step()` | OK |
-| `swmm_stride` | `Solver.step(stride=)` | OK |
-| `swmm_useHotStart` | `Solver.use_hotstart()` | OK |
-| `swmm_saveHotStart` | `Solver.save_hotstart()` | OK |
-| `swmm_end` | `Solver.end()` | OK |
-| `swmm_report` | `Solver.report()` | OK |
-| `swmm_close` | `Solver.close()` | OK |
-| `swmm_getMassBalErr` | `Solver.get_mass_balance_error()` | OK — returns (runoff%, flow%, qual%) |
-| `swmm_getVersion` | `version()` | OK |
-| `swmm_getError` | `Solver.__get_error()` | OK (private) |
-| `swmm_getErrorFromCode` | `get_error_message()` | OK |
-| `swmm_getWarnings` | **NOT WRAPPED** | **GAP** |
-| `swmm_getCount` | `Solver.get_object_count()` | OK |
-| `swmm_getName` | `Solver.get_object_name()` | OK |
-| `swmm_getIndex` | `Solver.get_object_index()` | OK |
-| `swmm_getValue` | `Solver.get_value()` | OK (deprecated, delegates to Expanded) |
-| `swmm_getValueExpanded` | `Solver.get_value()` | OK |
-| `swmm_setValue` | `Solver.set_value()` | OK (deprecated, delegates to Expanded) |
-| `swmm_setValueExpanded` | `Solver.set_value()` | OK |
-| `swmm_getSavedValue` | **NOT WRAPPED** | **GAP** — read from .out during sim |
-| `swmm_writeLine` | **NOT WRAPPED** | **GAP** — write to report file |
-| `swmm_decodeDate` | `decode_swmm_datetime()` | OK |
-| `swmm_encodeDate` | `encode_swmm_datetime()` | OK |
-
-### 2.2 C API Enums vs Python Enums
-
-#### Rain Gage Properties (C: 3, Python: 3) — COMPLETE
-All 3 properties exposed.
-
-#### Subcatchment Properties (C: 48, Python: 17) — **31 MISSING**
-
-| C Enum Value | Python Enum | Status |
-|-------------|-------------|--------|
-| `swmm_SUBCATCH_AREA` (200) | `AREA` | OK |
-| `swmm_SUBCATCH_RAINGAGE` (201) | `RAINGAGE` | OK |
-| `swmm_SUBCATCH_RAINFALL` (202) | `RAINFALL` | OK |
-| `swmm_SUBCATCH_EVAP` (203) | `EVAPORATION` | OK |
-| `swmm_SUBCATCH_INFIL` (204) | `INFILTRATION` | OK |
-| `swmm_SUBCATCH_RUNOFF` (205) | `RUNOFF` | OK |
-| `swmm_SUBCATCH_RPTFLAG` (206) | `REPORT_FLAG` | OK |
-| `swmm_SUBCATCH_WIDTH` (207) | `WIDTH` | OK |
-| `swmm_SUBCATCH_SLOPE` (208) | `SLOPE` | OK |
-| `swmm_SUBCATCH_OUTLET_TYPE` (209) | — | **MISSING** |
-| `swmm_SUBCATCH_OUTLET_INDEX` (210) | — | **MISSING** |
-| `swmm_SUBCATCH_INFILTRATION_MODEL` (211) | — | **MISSING** |
-| `swmm_SUBCATCH_FRACTION_IMPERVIOUS` (212) | — | **MISSING** |
-| `swmm_SUBCATCH_SUB_AREA_ROUTE_TO` (213) | — | **MISSING** |
-| `swmm_SUBCATCH_SUB_AREA_FRACTION_OUTLET` (214) | — | **MISSING** |
-| `swmm_SUBCATCH_SUB_AREA_MANNINGS_N` (215) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_SUB_AREA_FRACTION_AREA` (216) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_SUB_AREA_DEPRESSION_STORAGE` (217) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_SUB_AREA_INFLOW` (218) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_SUB_AREA_RUNOFF` (219) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_SUB_AREA_DEPTH` (220) | — | **MISSING** (sub_index needed) |
-| `swmm_SUBCATCH_LID_UNITS_COUNT` (221) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNITS_PERV_AREA` (222) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNITS_FLOW_TO_PERV_AREA` (223) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNITS_DRAIN_FLOW` (224) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_REPLICATES` (225) | — | **MISSING** (sub_index=LID unit) |
-| `swmm_SUBCATCH_LID_UNIT_AREA` (226) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_FULL_WIDTH` (227) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_BOTTOM_WIDTH` (228) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_INIT_SATURATION` (229) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_FROM_IMPERVIOUS` (230) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_FROM_PERVIOUS` (231) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_TO_PERVIOUS` (232) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_TYPE` (233) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_RECEIVING_OUTLET_INDEX` (234) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_SURFACE_DEPTH` (235) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_SOIL_MOISTURE` (236) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_CAPILLARY_SUCTION` (237) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_SATURATED_CONDUCTIVITY` (238) | — | **MISSING** |
-| `swmm_SUBCATCH_LID_UNIT_GREEN_AMPT_MAX_SOIL_MOISTURE_DEFICIT` (239) | — | **MISSING** |
-| `swmm_SUBCATCH_CURB_LENGTH` (240) | `CURB_LENGTH` | OK |
-| `swmm_SUBCATCH_API_RAINFALL` (241) | `API_RAINFALL` | OK |
-| `swmm_SUBCATCH_API_SNOWFALL` (242) | `API_SNOWFALL` | OK |
-| `swmm_SUBCATCH_POLLUTANT_BUILDUP` (243) | `POLLUTANT_BUILDUP` | OK |
-| `swmm_SUBCATCH_EXTERNAL_POLLUTANT_BUILDUP` (244) | `EXTERNAL_POLLUTANT_BUILDUP` | OK |
-| `swmm_SUBCATCH_POLLUTANT_RUNOFF_CONCENTRATION` (245) | `POLLUTANT_RUNOFF_CONCENTRATION` | OK |
-| `swmm_SUBCATCH_POLLUTANT_PONDED_CONCENTRATION` (246) | `POLLUTANT_PONDED_CONCENTRATION` | OK |
-| `swmm_SUBCATCH_POLLUTANT_TOTAL_LOAD` (247) | `POLLUTANT_TOTAL_LOAD` | OK |
-
-#### Node Properties (C: 15, Python: 15) — COMPLETE
-
-#### Link Properties (C: 29, Python: 29) — COMPLETE
-
-#### System Properties (C: 41, Python: 37) — **4 MISSING**
-
-Missing in Python enum: `HEAD_TOL` (38), `SYS_FLOW_TOL` (39), `LAT_FLOW_TOL` (40)
-were listed in C but mapped differently in Python. Need audit.
-
----
-
-## 3. Gap Analysis vs PySWMM
-
-### 3.1 Features PySWMM has that we lack
-
-| Feature | PySWMM | Our API | Priority |
-|---------|--------|---------|----------|
-| Per-node statistics (peak inflow, flood duration, etc.) | `node.statistics` | Not exposed | **HIGH** |
-| Per-link statistics (peak flow, surcharge time, etc.) | `link.conduit_statistics` | Not exposed | **HIGH** |
-| Pump statistics | `link.pump_statistics` | Not exposed | **HIGH** |
-| Storage statistics | `node.storage_statistics` | Not exposed | **HIGH** |
-| Outfall statistics | `node.outfall_statistics` | Not exposed | **HIGH** |
-| Subcatchment statistics (total precip, runoff, etc.) | `subcatchment.statistics` | Not exposed | **HIGH** |
-| System routing statistics (mass balance breakdown) | `SystemStats.routing_stats` | Only `get_mass_balance_error()` | **HIGH** |
-| System runoff statistics (mass balance breakdown) | `SystemStats.runoff_stats` | Only `get_mass_balance_error()` | **HIGH** |
-| LID unit properties (area, width, saturation, etc.) | `LidUnit.*` | Enum exists in C, not in Python | **MEDIUM** |
-| LID layer results (surface depth, soil moisture, etc.) | `LidUnit.surface.depth` | Enum exists in C, not in Python | **MEDIUM** |
-| LID water balance (inflow, evap, infil, drain flow) | `LidUnit.water_balance` | Not exposed | **MEDIUM** |
-| Subarea properties (Manning's n, depression storage) | via toolkit | Enum exists in C, not in Python | **MEDIUM** |
-| Node inflow control (`generated_inflow`) | `node.generated_inflow()` | Via `set_value(NODE, LATERAL_INFLOW)` | OK |
-| Outfall stage control | `outfall.outfall_stage()` | Not exposed as dedicated method | **LOW** |
-| Pollutant quality at nodes/links | `node.pollut_quality` | Via `get_value()` with sub_index | OK but clunky |
-| Warning count | `swmm_getWarnings` | **NOT WRAPPED** | **MEDIUM** |
-| Write to report file | `swmm_writeLine` | **NOT WRAPPED** | **LOW** |
-| Read saved output values | `swmm_getSavedValue` | **NOT WRAPPED** | **LOW** |
-
-### 3.2 Mass Balance / Flux Tracking Gaps
-
-**Current:** Only `get_mass_balance_error() -> (runoff_err%, flow_err%, qual_err%)`.
-
-**Needed (matching PySWMM `SystemStats`):**
-
-Routing totals:
-- `dry_weather_inflow`, `wet_weather_inflow`, `groundwater_inflow`
-- `ii_inflow` (I&I), `external_inflow`
-- `flooding`, `outflow`, `evaporation_loss`, `seepage_loss`
-- `reacted` (quality)
-- `initial_storage`, `final_storage`
-- `routing_error` (% continuity)
-
-Runoff totals:
-- `rainfall`, `evaporation`, `infiltration`, `runoff`
-- `drains` (LID drains), `runon`
-- `init_storage`, `final_storage`
-- `init_snow_cover`, `final_snow_cover`, `snow_removed`
-- `runoff_error` (% continuity)
-
-**These require new C API functions** or access to internal SWMM global
-variables. The existing `swmm_getMassBalErr` only returns the 3 percentage
-errors.
-
----
-
-## 4. Implementation Plan
-
-### Phase 1: Complete the Python enum coverage (no C changes)
-
-**Goal:** Expose all 48 subcatchment properties and the 4 missing system
-properties in the Python `SWMMSubcatchmentProperties` and
-`SWMMSystemProperties` enums. No C code changes needed — the C API already
-supports these via `swmm_getValueExpanded` / `swmm_setValueExpanded`.
-
-**Tasks:**
-
-- [x] **1.1** Add missing subcatchment enum members to `SWMMSubcatchmentProperties`:
-  - Added 31 members to both `solver.pxd` and `_solver.pyx`
-  - Outlet: `OUTLET_TYPE`, `OUTLET_INDEX`
-  - Infiltration: `INFILTRATION_MODEL`, `FRACTION_IMPERVIOUS`
-  - Subareas (sub_index = 0=imperv, 1=perv):
-    `SUB_AREA_ROUTE_TO`, `SUB_AREA_FRACTION_OUTLET`, `SUB_AREA_MANNINGS_N`,
-    `SUB_AREA_FRACTION_AREA`, `SUB_AREA_DEPRESSION_STORAGE`,
-    `SUB_AREA_INFLOW`, `SUB_AREA_RUNOFF`, `SUB_AREA_DEPTH`
-  - LID aggregates: `LID_UNITS_COUNT`, `LID_UNITS_PERV_AREA`,
-    `LID_UNITS_FLOW_TO_PERV_AREA`, `LID_UNITS_DRAIN_FLOW`
-  - LID unit (sub_index = LID unit index):
-    `LID_UNIT_REPLICATES`, `LID_UNIT_AREA`, `LID_UNIT_FULL_WIDTH`,
-    `LID_UNIT_BOTTOM_WIDTH`, `LID_UNIT_INIT_SATURATION`,
-    `LID_UNIT_FROM_IMPERVIOUS`, `LID_UNIT_FROM_PERVIOUS`,
-    `LID_UNIT_TO_PERVIOUS`, `LID_UNIT_RECEIVING_OUTLET_TYPE`,
-    `LID_UNIT_RECEIVING_OUTLET_INDEX`, `LID_UNIT_SURFACE_DEPTH`,
-    `LID_UNIT_SOIL_MOISTURE`, `LID_UNIT_GREEN_AMPT_CAPILLARY_SUCTION`,
-    `LID_UNIT_GREEN_AMPT_SATURATED_CONDUCTIVITY`,
-    `LID_UNIT_GREEN_AMPT_MAX_SOIL_MOISTURE_DEFICIT`
-- [x] **1.2** System enum members already complete — `HEAD_TOL`, `SYS_FLOW_TOL`, `LAT_FLOW_TOL` were already present (plan audit was incorrect)
-- [ ] **1.3** Update `.pyi` stubs with all new enum members and docstrings (deferred — .pyi file does not yet exist)
-- [x] **1.4** Wrap `swmm_getWarnings` as `Solver.get_warnings() -> int`
-- [x] **1.5** Wrap `swmm_writeLine` as `Solver.write_line(text: str)`
-- [x] **1.6** Wrap `swmm_getSavedValue` as `Solver.get_saved_value(property, index, period) -> float`
-- [x] **1.7** Write unit tests for all new enum values and wrapped functions
-- [x] **1.8** (Bug fix) Fixed `get_mass_balance_error()` — was missing `return` statement and not capturing error code from `swmm_getMassBalErr()`
-- [x] **1.9** Updated `__init__.py` exports to include `SWMMLinkTypes`, `CallbackType`, `get_error_message`
-
-**Files modified:**
-- `openswmm/legacy/engine/solver.pxd` — added 31 subcatchment enum members
-- `openswmm/legacy/engine/_solver.pyx` — expanded enums, fixed bug, added 3 new methods
-- `openswmm/legacy/engine/__init__.py` — added missing exports
-- `openswmm/solver/__init__.py` — updated backward-compat shim
-- `tests/legacy/test_phase1_enum_coverage.py` — **new** comprehensive test suite (13 test classes)
-
-### Phase 2: Statistics and Mass Balance C API + Python bindings
-
-**Goal:** Expose per-element statistics and detailed mass-balance
-breakdowns. This requires new C functions in `openswmm_solver.h` since the
-existing generic `swmm_getValue/swmm_setValue` interface does not provide
-access to the internal statistics structures.
-
-**New C Functions Needed:**
-
-```c
-// --- Node statistics ---
-int swmm_getNodeStats(int index, double *avgDepth, double *maxDepth,
-                      double *maxDepthDate, double *maxInflow,
-                      double *maxOverflow, double *floodVolume,
-                      double *floodDuration, double *surchargeDuration,
-                      double *courantCritDuration);
-
-// --- Storage statistics ---
-int swmm_getStorageStats(int index, double *initVolume, double *avgVolume,
-                         double *maxVolume, double *maxVolDate,
-                         double *maxFlow, double *evapLoss,
-                         double *exfilLoss);
-
-// --- Outfall statistics ---
-int swmm_getOutfallStats(int index, double *avgFlow, double *maxFlow,
-                         double *totalVolume, int *totalPeriods,
-                         double *pollutLoads, int nPolluts);
-
-// --- Link/conduit statistics ---
-int swmm_getLinkStats(int index, double *peakFlow, double *peakFlowDate,
-                      double *peakVelocity, double *peakDepth,
-                      double *timeNormalFlow, double *timeInletControl,
-                      double *timeSurcharged, double *timeFullUpstream,
-                      double *timeFullDownstream, double *timeFullFlow,
-                      double *timeCapLimited, double *timeCourantCrit);
-
-// --- Pump statistics ---
-int swmm_getPumpStats(int index, double *utilized, double *minFlow,
-                      double *avgFlow, double *maxFlow,
-                      double *totalVolume, double *energyConsumed,
-                      double *offCurveLow, double *offCurveHigh,
-                      int *startups, int *totalPeriods);
-
-// --- Subcatchment statistics ---
-int swmm_getSubcatchStats(int index, double *precip, double *runon,
-                          double *evap, double *infil, double *runoff,
-                          double *maxFlow);
-
-// --- System mass balance ---
-int swmm_getRoutingTotals(double *dryWeatherInflow, double *wetWeatherInflow,
-                          double *groundwaterInflow, double *iiInflow,
-                          double *externalInflow, double *flooding,
-                          double *outflow, double *evapLoss,
-                          double *seepageLoss, double *reacted,
-                          double *initStorage, double *finalStorage,
-                          double *pctError);
-
-int swmm_getRunoffTotals(double *rainfall, double *evap, double *infil,
-                         double *runoff, double *drains, double *runon,
-                         double *initStorage, double *finalStorage,
-                         double *initSnowCover, double *finalSnowCover,
-                         double *snowRemoved, double *pctError);
-```
-
-**Tasks:**
-
-- [x] **2.1** Implement new C functions in `src/legacy/engine/swmm5_stats.c`
-      accessing internal SWMM globals via extern linkage. Uses struct-based
-      API (swmm_SubcatchStats, swmm_NodeStats, etc.) rather than flat
-      parameter lists. Original EPA files remain unmodified.
-- [x] **2.2** Add 8 struct typedefs + 8 function declarations to `openswmm_solver.h`
-- [x] **2.3** Add `cdef extern` struct + function declarations to `solver.pxd`
-- [x] **2.4** Python wrapper methods on `Solver` class (all return dicts):
-  - `get_subcatchment_statistics(idx) -> dict`
-  - `get_node_statistics(idx) -> dict`
-  - `get_storage_statistics(idx) -> dict`
-  - `get_outfall_statistics(idx) -> dict` (includes pollutant loads array)
-  - `get_link_statistics(idx) -> dict` (includes 7-element flow class array)
-  - `get_pump_statistics(idx) -> dict`
-  - `get_routing_totals() -> dict` (with mass balance equation in docstring)
-  - `get_runoff_totals() -> dict` (with mass balance equation in docstring)
-- [ ] **2.5** Update `.pyi` stubs (deferred — .pyi file does not yet exist)
-- [x] **2.6** Write unit tests validating statistics against known model outputs
-- [x] **2.7** Write unit tests validating mass balance closure:
-  - `routing_totals`: verify `inflows - outflows ≈ storage_change` within `pct_error`
-  - External inflow test: verify `set_value(LATERAL_INFLOW)` appears in `ex_inflow`
-  - Rainfall override test: verify `API_RAINFALL` override appears in `rainfall`
-
-**Files created:**
-- `src/legacy/engine/swmm5_stats.c` — **new** C statistics implementation (8 functions)
-- `tests/legacy/test_phase2_statistics.py` — **new** comprehensive test suite (11 test classes)
-
-**Files modified:**
-- `include/openswmm/legacy/engine/openswmm_solver.h` — 8 structs + 8 function declarations
-- `include/openswmm/legacy/engine/openswmm_solver.h` — new declarations
-- `openswmm/legacy/engine/solver.pxd` — Cython extern declarations
-- `openswmm/legacy/engine/_solver.pyx` — Python methods
-- `openswmm/legacy/engine/_solver.pyi` — type stubs
-- `tests/legacy/test_solver.py` — statistics and mass balance tests
-
-### Phase 3: Dedicated element-access classes (Pythonic API layer)
-
-**Goal:** Add PySWMM-style object-oriented wrappers that sit on top of the
-generic `get_value`/`set_value` interface, providing property-based access
-with docstrings, type safety, and mass-balance awareness.
-
-**New classes** (in `openswmm/legacy/engine/`):
-
-```
-_nodes.py      -> LegacyNodes, LegacyNode
-_links.py      -> LegacyLinks, LegacyLink
-_subcatchments.py -> LegacySubcatchments, LegacySubcatchment
-_raingages.py  -> LegacyRainGages, LegacyRainGage
-_system.py     -> LegacySystem
-_lid.py        -> LegacyLidUnits, LegacyLidUnit
-```
-
-Each class wraps the `Solver` and provides typed properties:
-
-```python
-class LegacyNode:
-    """Property-based access to a single SWMM node."""
-
-    def __init__(self, solver: Solver, index: int): ...
-
-    # Parameters (get/set)
-    @property
-    def invert_elevation(self) -> float: ...
-    @invert_elevation.setter
-    def invert_elevation(self, value: float): ...
-
-    @property
-    def max_depth(self) -> float: ...
-    @property
-    def surcharge_depth(self) -> float: ...
-    @property
-    def ponded_area(self) -> float: ...
-    @property
-    def initial_depth(self) -> float: ...
-
-    # Results (get only, during simulation)
-    @property
-    def depth(self) -> float: ...
-    @property
-    def head(self) -> float: ...
-    @property
-    def volume(self) -> float: ...
-    @property
-    def lateral_inflow(self) -> float: ...
-    @property
-    def total_inflow(self) -> float: ...
-    @property
-    def flooding(self) -> float: ...
-
-    # Pollutants
-    @property
-    def pollutant_concentration(self) -> dict[str, float]: ...
-
-    # Control
-    def set_lateral_inflow(self, flow: float): ...
-    def set_pollutant_concentration(self, pollutant: str, value: float): ...
-
-    # Statistics (Phase 2)
-    @property
-    def statistics(self) -> dict: ...
-```
-
-**Tasks:**
-
-- [x] **3.1** Implement `LegacyNodes` / `LegacyNode` — `_nodes.py`
-      All 15 node properties as typed Python properties, plus node_type,
-      get_pollutant_concentration, statistics
-- [x] **3.2** Implement `LegacyLinks` / `LegacyLink` — `_links.py`
-      All 29 link properties, link_type, statistics, pump_statistics
-- [x] **3.3** Implement `LegacySubcatchments` / `LegacySubcatchment` — `_subcatchments.py`
-      All subcatchment properties including subareas (via get_subarea_*),
-      LID access (via get_lid_unit_*), pollutant access, statistics
-- [x] **3.4** Implement `LegacyRainGages` / `LegacyRainGage` — `_raingages.py`
-- [x] **3.5** Implement `LegacySystem` — `_system.py`
-      Flow units, routing/runoff totals, mass balance error, tolerances
-- [x] **3.6** LID access integrated into `LegacySubcatchment` as methods
-      (get_lid_unit_area, get_lid_unit_surface_depth, etc.) using sub_index
-- [ ] **3.7** Add `.pyi` stubs for all new classes (deferred)
-- [x] **3.8** Comprehensive unit tests — `test_phase3_oop_wrappers.py`
-- [ ] **3.9** Sphinx API documentation (deferred)
-
-### Phase 4: Mass-balance-aware set functions
-
-**Goal:** For every `set_*` method that modifies a flux or state variable,
-document the mass-balance implications and optionally log the external
-forcing for post-simulation audit.
-
-**Design:**
-
-```python
-class LegacyNode:
-    def set_lateral_inflow(self, flow: float):
-        """Prescribe an external lateral inflow at this node.
-
-        Mass balance impact:
-            This adds *flow* to the node's lateral inflow for the current
-            timestep. The value is reset each timestep — call again in the
-            next step to sustain. The injected volume appears in the routing
-            mass balance under "external inflow".
-
-        Args:
-            flow: Inflow rate in project flow units. Positive = inflow.
-        """
-        ...
-
-    def set_pollutant_concentration(self, pollutant: str, conc: float):
-        """Set pollutant concentration of the lateral inflow at this node.
-
-        Mass balance impact:
-            The mass flux = lateral_inflow * concentration * timestep.
-            This mass is added to the quality routing mass balance.
-            Must be called together with set_lateral_inflow for the
-            mass to be non-zero.
-        """
-        ...
-```
-
-**Properties with mass-balance implications (document in docstrings):**
-
-| Set Property | Object | Mass Balance Category |
-|-------------|--------|----------------------|
-| `NODE_LATFLOW` | Node | External inflow (routing totals) |
-| `NODE_POLLUTANT_LATMASS_FLUX` | Node | Quality mass balance |
-| `NODE_DEPTH` | Node | Changes stored volume — affects storage balance |
-| `LINK_SETTING` | Link | Changes flow capacity — affects routing |
-| `LINK_FLOW` | Link | Direct flow override — bypasses hydraulics |
-| `SUBCATCH_API_RAINFALL` | Subcatchment | Overrides rainfall — affects runoff totals |
-| `SUBCATCH_API_SNOWFALL` | Subcatchment | Overrides snowfall — affects snow balance |
-| `SUBCATCH_EXTERNAL_POLLUTANT_BUILDUP` | Subcatchment | Adds pollutant mass — quality balance |
-| `GAGE_RAINFALL` | Rain Gage | Overrides rainfall for all linked subcatchments |
-
-**Tasks:**
-
-- [x] **4.1** All mass-balance-aware setters include detailed docstrings:
-      - `LegacyNode.set_lateral_inflow` → routing.ex_inflow
-      - `LegacyNode.set_pollutant_lateral_mass_flux` → quality.external
-      - `LegacyNode.set_depth` → routing.storage_override
-      - `LegacyLink.set_setting` → routing.flow_capacity
-      - `LegacyLink.set_flow` → routing.flow_override
-      - `LegacySubcatchment.set_api_rainfall` → runoff.rainfall
-      - `LegacySubcatchment.set_api_snowfall` → runoff.snow
-      - `LegacySubcatchment.set_external_pollutant_buildup` → quality.buildup
-      - `LegacyRainGage.set_rainfall` → runoff.rainfall
-- [x] **4.2** `ExternalForcingLog` class — `_forcing_log.py`
-      Records (time, object_type, object_id, property, value, mass_balance_category).
-      Has `records`, `to_dataframe()`, `clear()`, `__len__()`.
-      All setter methods accept optional `log=` parameter.
-- [x] **4.3** Validation tests in `test_phase3_oop_wrappers.py`:
-      - Log integration with node/link/subcatchment setters
-      - End-to-end: inject 100 steps of inflow, verify log has 100 entries,
-        verify routing_totals.ex_inflow > 0, verify pct_error < 5%
-
----
-
-## 5. File Inventory
-
-### Files to CREATE
-
-| File | Phase | Purpose |
-|------|-------|---------|
-| `openswmm/legacy/engine/_nodes.py` | 3 | LegacyNodes/LegacyNode classes |
-| `openswmm/legacy/engine/_links.py` | 3 | LegacyLinks/LegacyLink classes |
-| `openswmm/legacy/engine/_subcatchments.py` | 3 | LegacySubcatchments/LegacySubcatchment |
-| `openswmm/legacy/engine/_raingages.py` | 3 | LegacyRainGages/LegacyRainGage |
-| `openswmm/legacy/engine/_system.py` | 3 | LegacySystem |
-| `openswmm/legacy/engine/_lid.py` | 3 | LegacyLidUnits/LegacyLidUnit |
-| `openswmm/legacy/engine/_forcing_log.py` | 4 | ExternalForcingLog |
-| `tests/legacy/test_enum_coverage.py` | 1 | Validate all enum values |
-| `tests/legacy/test_statistics.py` | 2 | Statistics tests |
-| `tests/legacy/test_mass_balance.py` | 2,4 | Mass balance validation |
-| `tests/legacy/test_nodes.py` | 3 | Node property tests |
-| `tests/legacy/test_links.py` | 3 | Link property tests |
-| `tests/legacy/test_subcatchments.py` | 3 | Subcatchment property tests |
-| `tests/legacy/test_lid.py` | 3 | LID access tests |
-
-### Files to MODIFY
-
-| File | Phase | Changes |
-|------|-------|---------|
-| `include/openswmm/legacy/engine/openswmm_solver.h` | 2 | New C function declarations |
-| `src/legacy/engine/*.c` | 2 | New C function implementations |
-| `openswmm/legacy/engine/solver.pxd` | 1,2 | New cdef extern declarations |
-| `openswmm/legacy/engine/_solver.pyx` | 1,2 | Expanded enums, new methods |
-| `openswmm/legacy/engine/_solver.pyi` | 1,2,3 | Updated type stubs |
-| `openswmm/legacy/engine/__init__.py` | 3 | Export new classes |
-| `docs/api.rst` | 3 | Document new classes |
-
----
-
-## 6. Testing Strategy
-
-### Mass Balance Validation Tests
-
-```python
-def test_routing_mass_balance_closure(solver_with_completed_sim):
-    """Verify routing totals close within tolerance."""
-    totals = solver.get_routing_totals()
-
-    total_inflow = (
-        totals['dry_weather_inflow'] +
-        totals['wet_weather_inflow'] +
-        totals['groundwater_inflow'] +
-        totals['ii_inflow'] +
-        totals['external_inflow']
-    )
-    total_outflow = (
-        totals['flooding'] +
-        totals['outflow'] +
-        totals['evaporation_loss'] +
-        totals['seepage_loss']
-    )
-    storage_change = totals['final_storage'] - totals['initial_storage']
-
-    balance = total_inflow - total_outflow - storage_change
-    assert abs(balance) / max(total_inflow, 1e-6) < 0.01  # < 1% error
-
-def test_external_inflow_appears_in_routing_totals(solver):
-    """Verify that set_lateral_inflow contributes to routing totals."""
-    solver.start()
-    for _ in range(100):
-        solver.set_value(SWMMObjects.NODE, SWMMNodeProperties.LATERAL_INFLOW,
-                        index=0, value=1.0)
-        solver.step()
-    solver.end()
-
-    totals = solver.get_routing_totals()
-    assert totals['external_inflow'] > 0
-
-def test_rainfall_override_appears_in_runoff_totals(solver):
-    """Verify that API rainfall override appears in runoff totals."""
-    solver.start()
-    for _ in range(100):
-        solver.set_value(SWMMObjects.SUBCATCHMENT,
-                        SWMMSubcatchmentProperties.API_RAINFALL,
-                        index=0, value=2.0)
-        solver.step()
-    solver.end()
-
-    totals = solver.get_runoff_totals()
-    assert totals['rainfall'] > 0
-```
-
----
-
-## 7. Priority Order
-
-1. **Phase 1** (enum expansion) — Low risk, high value, no C changes
-2. **Phase 2** (statistics + mass balance) — Requires C changes but critical for scientific use
-3. **Phase 3** (Pythonic wrappers) — Pure Python, can be done in parallel with Phase 2
-4. **Phase 4** (mass-balance-aware setters) — Polish, documentation, audit trail
-
----
-
-## 8. Notes for Agent Continuation
-
-- The C API uses a generic `swmm_getValueExpanded(objType, property, index, subIndex, pollutantIndex)` pattern. The `subIndex` is overloaded:
-  - For subcatchment subareas: 0=impervious, 1=pervious
-  - For LID units: the LID unit index within the subcatchment
-  - For pollutants: the pollutant index (0-based)
-- The `_solver.pyx` already handles string-to-index resolution in `get_value()`/`set_value()` — pass a string name as `index` and it calls `swmm_getIndex()`.
-- The existing `Solver.get_mass_balance_error()` returns `(runoff_err, flow_err, qual_err)` as percentages. The new `get_routing_totals()` / `get_runoff_totals()` should return the raw volumes so users can do their own mass balance checks.
-- Statistics structs in SWMM (`NodeStats`, `LinkStats`, etc.) are populated during `swmm_end()`. The new C functions should be callable after `end()` but before `close()`.
diff --git a/python/docs/api.rst b/python/docs/api.rst
index bea6946c8..4d6d0ad18 100644
--- a/python/docs/api.rst
+++ b/python/docs/api.rst
@@ -190,6 +190,46 @@ Water quality  (landuse, buildup, washoff, treatment)
    :undoc-members:
    :show-inheritance:
 
+Initial quality  (per-element starting concentrations)
+-------------------------------------------------------
+
+.. automodule:: openswmm.engine._initial_quality
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Reactions  (multi-species reaction system)
+-------------------------------------------
+
+.. automodule:: openswmm.engine._reactions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Process components  (``[PROCESS_COMPONENTS]`` registrations)
+-------------------------------------------------------------
+
+.. automodule:: openswmm.engine._process_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Water age  (source ages and node overrides)
+--------------------------------------------
+
+.. automodule:: openswmm.engine._water_age
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Heat transport  (fluxes, solar, cloud, heat sources)
+-----------------------------------------------------
+
+.. automodule:: openswmm.engine._heat
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Tables  (time series, curves, patterns)
 ---------------------------------------
 
@@ -246,6 +286,14 @@ Spatial  (CRS, coordinates, vertices, polygons)
    :undoc-members:
    :show-inheritance:
 
+Engine catalog
+--------------
+
+Machine-readable map of this API; see :doc:`guide/catalog`.
+
+.. automodule:: openswmm.engine.catalog
+   :members:
+
 Enumerations
 ------------
 
diff --git a/python/docs/conf.py b/python/docs/conf.py
index f388acfe8..0344ab2c0 100644
--- a/python/docs/conf.py
+++ b/python/docs/conf.py
@@ -91,7 +91,7 @@ def exec_module(self, module):
     version = openswmm.__version__
     release = openswmm.__version__
 except Exception:
-    version = '6.0.0a3'
+    version = '6.0.0a4.dev1'
     release = version
 
 # -- General configuration ------------------------------------------------
diff --git a/python/docs/guide/2d.rst b/python/docs/guide/2d.rst
index 0c29a849e..b97d4d290 100644
--- a/python/docs/guide/2d.rst
+++ b/python/docs/guide/2d.rst
@@ -82,6 +82,10 @@ zero-based.
      - Scalar ``(x, y, z)`` for one vertex.
    * - ``set_vertex_z(idx, z)``
      - Set a vertex ground elevation.
+   * - ``set_vertex_z_bulk(z)``
+     - Set **every** vertex ground elevation in one call (one mesh rescan
+       instead of one per vertex; GIL released). ``len(z)`` must equal
+       ``n_vertices``.
    * - ``get_triangle_vertices(idx)``
      - ``(v0, v1, v2)`` vertex indices.
    * - ``get_triangle_area(idx)``
@@ -307,12 +311,17 @@ type is a :class:`SurfaceBoundaryType`: ``WALL`` (closed), ``NORMAL_FLOW``,
      - Cumulative flux across the edge.
    * - ``get_edge_bc_flow`` (runtime)
      - Instantaneous flow across the edge.
-   * - ``set_edge_bc_tseries_name``
-     - Name the timeseries driving a SPECIFIED_STAGE edge.
-   * - ``set_edge_bc_flow_tseries_name``
-     - Name the timeseries driving a SPECIFIED_FLOW edge.
-   * - ``set_edge_bc_rating_curve_name``
-     - Name the rating curve driving a RATING_CURVE edge.
+   * - ``get_edge_bc_tseries_name`` / ``set_edge_bc_tseries_name``
+     - Name the timeseries driving a SPECIFIED_STAGE edge; the getter
+       returns ``""`` when the slot is clear.
+   * - ``get_edge_bc_flow_tseries_name`` /
+       ``set_edge_bc_flow_tseries_name``
+     - Name the timeseries driving a SPECIFIED_FLOW edge; ``""`` when
+       clear.
+   * - ``get_edge_bc_rating_curve_name`` /
+       ``set_edge_bc_rating_curve_name``
+     - Name the rating curve driving a RATING_CURVE edge; ``""`` when
+       clear.
 
 Edge conveyance
 ---------------
diff --git a/python/docs/guide/binding_updates.rst b/python/docs/guide/binding_updates.rst
new file mode 100644
index 000000000..eb2754b3b
--- /dev/null
+++ b/python/docs/guide/binding_updates.rst
@@ -0,0 +1,74 @@
+Editing, forcing and live output
+================================
+
+Batch editing
+-------------
+
+``ModelEditor`` retains its engine owner and checks it before every operation.
+``delete_nodes``, ``delete_links``, ``delete_subcatchments`` and ``delete_gages``
+accept iterables of names or zero-based indices. All refer to the model before
+the batch. Duplicates are ignored and invalid indices fail before any deletion.
+A successful nonempty batch invalidates element views and returns the aggregate
+cascade report. Reacquire views after an edit; the editor itself remains usable.
+
+Live output
+-----------
+
+``OutputReader(path, live=True)`` opens an output whose header is complete,
+even before the writer finishes. ``refresh()`` returns the number of complete
+periods and clears cached timestamps. Partial trailing records are excluded.
+``is_live`` becomes false when closing records arrive. This supports monitoring
+runs and recovering completed records from interrupted runs; it never modifies
+the file. Concurrent access to a reader during a native series read raises
+``LifecycleError``; independent readers can operate concurrently.
+Close the reader or use its context manager. Reads after close raise
+``BadHandleError``.
+
+.. code-block:: python
+
+   from openswmm.engine import OutputReader, OutNodeVar
+
+   with OutputReader('run.out', live=True) as output:
+       count = output.refresh()
+       if count:
+           depths = output.node_result(count - 1, OutNodeVar.DEPTH)
+
+Staged serialization
+--------------------
+
+``solver.write_staged(final_path, mapper)`` routes each physical file through
+``mapper(final_path, kind)``. Kind 0 identifies the INP file, 1 the mesh and 2 a
+component configuration. Return a distinct staging path, or None to refuse.
+References inside files are computed from final paths. Success confirms only
+serialization; the caller owns validation, cleanup and publication of every
+output. Plugin writers are excluded. Engine access inside the mapper raises
+``LifecycleError``. Python callback exceptions are re-raised after the native
+writer returns safely.
+
+Additional forcing and diagnostics
+----------------------------------
+
+``forcing.node_temperature`` uses degrees C for REPLACE, and degrees C times
+ft³/s for ADD. ``forcing.node_age`` uses hours for REPLACE and hours times ft³/s
+for ADD. Enable heat or water-age transport before initialization respectively.
+``forcing.link_seepage`` uses ft³/s even for SI projects, positive out of the
+conduit. Negative values supply water from groundwater. If the built-in aquifer
+is coupled, the forced exchange also updates that aquifer; disable the internal
+reach exchange when an external groundwater model supplies the water.
+
+``forcing.element_climate`` takes ``HeatElemKind``, a node/link name or index,
+and an ELEM_* ``ForcingType``. Air temperature and wind use project units;
+humidity uses percent and shortwave uses W/m². ``element_climate_get`` returns
+``(value, mode)``, with None for mode when no forcing is present. Setters accept
+REPLACE or ADD, with the existing one-shot/persistent policy.
+
+``surface2d.get_rainfall_bulk()`` returns m/s. ``get_rain_volume_bulk()`` and
+``get_coupling_volume_bulk()`` return cumulative m³, with positive coupling from
+1D to 2D. Arrays are independent snapshots covering triangles and quads.
+``rainfall_weights(cell)`` returns method, gage indices and weights. Method -1
+means not applicable, 0 natural neighbour, 1 inverse distance, and 2 nearest.
+
+``Surface2D.output_variables()`` discovers available output names.
+``output_variable_mask(text)`` accepts DEFAULT, MINIMAL, ALL or a variable list;
+invalid selections raise ValueError. ``output_variable_text(mask)`` returns the
+canonical text for storing the selection.
diff --git a/python/docs/guide/catalog.rst b/python/docs/guide/catalog.rst
new file mode 100644
index 000000000..b6a7cc47d
--- /dev/null
+++ b/python/docs/guide/catalog.rst
@@ -0,0 +1,126 @@
+==============
+Engine catalog
+==============
+
+:mod:`openswmm.engine.catalog` is a machine-readable map of the Python API,
+shipped in the wheel as ``catalog.json``. It lists every service, element
+kind, sub-view and standalone class, and for each member:
+
+* a **property**'s type, access (``r`` or ``rw``), unit kind and the
+  lifecycle phases it can be read in;
+* a **method**'s parameters, defaults and return type;
+* the C API functions behind it;
+* the bulk array that reads a whole collection at once, where there is one.
+
+The OpenSWMM MCP server and ``openswmm.gymnasium`` use it to reach engine
+fields and methods by path. Existing generic dispatchers can adopt new scalar
+fields and compatible method signatures, but availability, lifecycle, argument
+marshalling and domain-specific behavior still require consumer tests.
+
+Paths
+=====
+
+A **target** is a class reachable from a :class:`~openswmm.engine.Solver`:
+a service (``"forcing"``, ``"surface2d.groundwater"``), an element kind
+(``"node"``, ``"link"``), a sub-view of one (``"node.stats"``,
+``"link.xsect"``) or a standalone class (``"xsect"``, ``"output"``). A
+**member path** is a target plus a member name: ``"node.depth"``,
+``"link.stats.max_filling"``, ``"forcing.node_lat_inflow"``.
+
+.. code-block:: python
+
+   from openswmm.engine import Solver, catalog
+
+   entry = catalog.lookup("link.stats.max_filling")
+   entry["type"], entry["access"], entry["units"]      # ('float', 'r', 'fraction')
+
+   [m["name"] for m in catalog.members("node.stats")]  # max_depth, max_overflow, ...
+
+   call = catalog.lookup("forcing.node_lat_inflow")
+   [(p["name"], p["required"]) for p in call["params"]]
+   # [('node', True), ('value', True), ('mode', False), ('persist', False)]
+
+   with Solver("model.inp", "model.rpt", "model.out") as solver:
+       stats = catalog.resolve(solver, "node.stats", "J1")   # the live NodeStatsView
+       catalog.lookup("node.depth")["bulk"]                  # 'nodes.depths'
+
+Functions
+=========
+
+``load()``
+   The whole catalog as a dict (``targets``, ``members``, ``functions``,
+   ``records``, ``enums`` and the C exports).
+``targets()``
+   Every target by name, with its class, module and, for element kinds, the
+   collection that holds them.
+``members(target)``
+   The members of one target (or of all targets).
+``lookup(path)``
+   One member by path; raises :class:`KeyError` naming the path.
+``resolve(solver, target, key)``
+   The live object for a target on an open solver; ``key`` is an element ID
+   or index for element targets.
+``unit_label(kind, unit_system, flow_units)``
+   The label for a unit kind in a model's units.
+
+Units
+=====
+
+Ordinary 1D fields use model units; fixed-unit fields, including many 2D
+quantities and temperature values, retain the units documented by their APIs.
+The catalog records a **unit
+kind** per float field: a system-dependent kind (``length``, ``volume``,
+``flow``, ``velocity``, ...), a fixed one (``fraction``, ``percent``,
+``dimensionless``, ``temperature``, ...) or a literal unit (``m/s``).
+``unit_label`` turns a kind into the label for a model:
+
+.. code-block:: python
+
+   with Solver("model.inp", "model.rpt", "model.out") as solver:
+       kind = catalog.lookup("node.depth")["units"]                      # 'length'
+       catalog.unit_label(kind, solver.unit_system, solver.flow_units)   # 'ft'
+       catalog.unit_label("flow", solver.unit_system, solver.flow_units) # 'CFS'
+
+``UNIT_KINDS`` is the set of symbolic kinds that have a label.
+
+Keeping the catalog current
+===========================
+
+``python/scripts/gen_catalog.py`` generates ``catalog.json`` from the type
+stubs, the Cython sources and the C header documentation. Units, exclusions
+and member corrections the sources cannot express live in
+``python/scripts/catalog_overrides.json``. After changing a stub, a ``.pyx``
+file or a header, regenerate it:
+
+.. code-block:: bash
+
+   python python/scripts/gen_catalog.py          # rewrite catalog.json
+   python python/scripts/gen_catalog.py --check  # what CI runs
+
+``--check`` fails when the committed catalog is stale, when a public class is
+neither reachable nor excluded, or when a float field has no unit kind (mark
+a true ratio ``dimensionless``). ``python/tests/test_catalog.py`` adds the
+runtime contract: every catalogued member exists on its compiled class,
+every public attribute is catalogued or excluded, and every target resolves
+on an opened model.
+
+
+Consumer compatibility
+======================
+
+* Gymnasium ``add_field`` consumes scalar numeric element properties; its
+  per-cell collector supports selected 2D service methods. Writable metadata
+  does not guarantee that a field can be actuated during a running episode.
+* MCP dispatches JSON-compatible catalog operations. Session-owned lifecycle
+  methods and Python callbacks are deliberately restricted; new standalone
+  classes require constructor handling.
+* WASM generates a raw C API from its **pinned engine submodule**, plus numeric
+  enums from the Python source. This is independent of the Python catalog.
+  Its current 1D build excludes 2D, mesh groundwater and surface quality; its
+  TypeScript convenience classes cover only part of the Python object API.
+
+After adding native exports or changing a stub, rebuild the compiled extensions,
+regenerate the catalog, and run both engine and consumer contract tests. An
+unchanged package version does not prove that two development builds expose the
+same catalog or native symbols. A missing newly added extension (for example
+``_transport``) requires a complete rebuild/reinstall, not an import fallback.
diff --git a/python/docs/guide/concepts.rst b/python/docs/guide/concepts.rst
index 402980f70..11d0a72ca 100644
--- a/python/docs/guide/concepts.rst
+++ b/python/docs/guide/concepts.rst
@@ -53,6 +53,22 @@ EngineState — what's legal when
 The Solver moves through a strict sequence of states.  The current
 state is exposed via :attr:`Solver.state`:
 
+.. mermaid::
+
+   stateDiagram-v2
+       direction LR
+       [*] --> CREATED : Solver(...)
+       CREATED --> OPENED : open()
+       [*] --> BUILDING : ModelBuilder
+       BUILDING --> OPENED : finalize()
+       OPENED --> INITIALIZED : initialize()
+       INITIALIZED --> STARTED : start()
+       STARTED --> RUNNING : first step()
+       RUNNING --> RUNNING : step()
+       RUNNING --> ENDED : end()
+       ENDED --> CLOSED : close()
+       CLOSED --> [*]
+
 .. list-table::
    :header-rows: 1
    :widths: 20 12 68
diff --git a/python/docs/guide/groundwater.rst b/python/docs/guide/groundwater.rst
new file mode 100644
index 000000000..7c32bef8a
--- /dev/null
+++ b/python/docs/guide/groundwater.rst
@@ -0,0 +1,98 @@
+Two-zone groundwater
+====================
+
+``solver.surface2d.groundwater`` exposes aquifer authoring and runtime results.
+The view retains its solver and is invalidated when the solver closes or its
+structure changes. Edits require BUILDING or OPENED. Use an explicit
+``solver.open()`` before editing; the solver context manager starts the run.
+
+Authoring units and precedence
+------------------------------
+
+``add_row(scope, ks, zs, theta_s, theta_r, alpha, tag="", cell=-1)`` appends
+an aquifer row. ``CellScope`` selects GLOBAL, TAG or CELL. Runtime resolution
+uses the more specific row; cells are zero-based in Python on both triangular
+and quadrilateral meshes.
+
+* ``ks`` uses project rainfall-rate units (in/hr or mm/hr).
+* ``zs`` uses project length (ft or m), and ``alpha`` inverse length.
+* ``theta_s`` and ``theta_r`` are dimensionless water contents.
+* Optional row properties include HG0, PSI_B, LAMBDA, N, L, C_LOSS,
+  SOIL_CHAR, CLOSURE and M_LAYERS. Use ``GroundwaterSoil`` and
+  ``GroundwaterClosure`` for their numeric selectors.
+
+``options`` is a text mapping using native INP keys and values. ``rows`` and
+``nodes`` are immutable snapshots. Removing a row shifts subsequent indices.
+``add_node`` accepts a zero-based cell or -1 for coordinate-based location;
+its conductivity is in/hr or mm/hr, thickness is ft or m, and area is ft² or
+m². Zero area uses cell area, and zero conductivity requests direct Darcy
+exchange. Node snapshots distinguish authored, located and automatically
+enrolled beds and expose the exchange opt-out flag.
+
+Runtime units
+-------------
+
+After initialization/start, ``active`` indicates that the kernel is available.
+Runtime hydrology uses SI regardless of the input project's unit system.
+``dimensions`` returns cell and sigma-layer counts. ``cell(index, variable)``
+reads one value and ``cells(variable)`` returns an owned float64 NumPy snapshot.
+``GroundwaterVariable`` selectors distinguish thickness/elevation (m), flux
+rates (m/s or m³/s), timestep (s), tier and closure codes.
+
+``column(cell)`` returns water contents from the surface down and requires a
+SIGMA closure; the engine refuses other closures instead of returning a
+misleading zero-filled array. ``ledger(term)`` returns m³. The
+``continuity_error`` is a residual in m³, not a percentage.
+``tier_histogram`` uses the platform's C-long dtype, including on Windows.
+
+``species`` lists the transported names in native policy order.
+``concentrations(zone, species_index)`` returns per-cell concentrations in the
+species' own mass units per m³ of zone water; dry zones report zero.
+``species_ledger`` exposes the corresponding cumulative native ledger.
+
+.. automodule:: openswmm.engine._groundwater
+   :members:
+
+Transport authoring
+-------------------
+
+``groundwater.transport`` edits the groundwater transport tables before
+initialization. Its ``options`` mapping takes native text keys such as
+TRANSPORT_POLLUTANTS, TRANSPORT_MSX, TRANSPORT_AGE and TRANSPORT_TEMPERATURE.
+Use YES/NO for switches. ``authored`` distinguishes an authored transport
+configuration from an absent one; consult ``solver.transport_matrix`` for
+runtime availability.
+
+The ``parameters``, ``sorption``, ``initial_quality``, ``boundaries`` and
+``sources`` properties return tuples of frozen records. Their ``set_*`` methods
+upsert by native row identity. Change a field with ``dataclasses.replace`` and
+submit the new record; modifying a snapshot does not mutate the model.
+``remove_*`` takes a zero-based row index, and subsequent indices shift.
+Source-species terms have a separate table indexed by the source row.
+
+.. code-block:: python
+
+   from openswmm.engine import GroundwaterParameters, GroundwaterInitialQuality
+
+   transport = solver.surface2d.groundwater.transport  # after solver.open()
+   transport.options['TRANSPORT_POLLUTANTS'] = 'YES'
+   transport.set_parameters(GroundwaterParameters(rho_s=2700))
+   transport.set_initial_quality(
+       GroundwaterInitialQuality(species='TSS', value=5)
+   )
+
+Parameter records use SI: density kg/m³, heat capacity J/(kg K), conductivity
+W/(m K), dispersivity m, diffusivity m²/s and geothermal flux W/m². Source flow
+is m³/s regardless of project FLOW_UNITS. Sorption ``kd`` is L/kg and decay is
+1/day; a negative decay inherits the pollutant value. Initial quality uses
+native species authoring units, which must not be confused with runtime
+mass-per-m³ arrays.
+
+``GroundwaterTransportZone`` selects SAT, UNSAT or LAYER. LAYER requires the
+native one-based layer number; cell, edge and table indices are zero-based.
+Boundary edge indices follow the cell geometry, including edge 3 of a quad.
+``initial_quality_file`` accepts a path or None to clear the reference. The
+reference is authored metadata; it does not read or apply the file immediately.
+
+.. automodule:: openswmm.engine._gw_transport
+   :members:
diff --git a/python/docs/guide/heat.rst b/python/docs/guide/heat.rst
new file mode 100644
index 000000000..3eb99890e
--- /dev/null
+++ b/python/docs/guide/heat.rst
@@ -0,0 +1,234 @@
+==========================================================
+Heat transport  (fluxes, solar, cloud, source temperature)
+==========================================================
+
+.. note::
+
+   **Engine:** OpenSWMM 6 — refactored.
+
+.. currentmodule:: openswmm.engine
+
+``solver.heat`` is the editable view over the ``model.heat`` component:
+the ``[HEAT_FLUXES]`` module toggles, the ``[RADIATIVE_FLUXES]`` scalar
+parameters, H6a's ``[SOLAR_RADIATION]`` and ``[CLOUD_COVER]`` sections,
+and the ``[HEAT_SOURCES]`` inlet-temperature table. Every refusal below
+mirrors the deck parser exactly, so a value the ``.inp`` rejects is a
+value this API rejects.
+
+Reference: ``openswmm_heat.h``.
+
+.. warning::
+
+   **Out-of-range values are REFUSED, not clamped**, and a refused write
+   does not take effect. Read back after a write only if you want to
+   confirm; do not assume a clamp happened.
+
+----
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from openswmm.engine import (
+        Solver, HeatFluxModule, HeatShortwaveMode,
+        HeatRadiativeParam, HeatSolarParam, HeatCloudParam, HeatSourceKind,
+    )
+
+    with Solver("model.inp") as s:
+        print(s.heat.enabled)                       # [OPTIONS] HEAT_TRANSPORT
+
+        s.heat.modules[HeatFluxModule.RADIATIVE_EXCHANGE] = True
+        s.heat.radiative[HeatRadiativeParam.ALBEDO] = 0.06
+
+        # COMPUTED needs an explicit site first — gate on solar_sited.
+        s.heat.solar[HeatSolarParam.LATITUDE] = 40.76
+        s.heat.solar[HeatSolarParam.LONGITUDE] = -111.89
+        assert s.heat.solar_sited
+        s.heat.shortwave_mode = HeatShortwaveMode.COMPUTED
+
+        s.heat.cloud[HeatCloudParam.FRACTION] = 0.4   # fraction, not percent
+
+        s.heat.sources[HeatSourceKind.DWF] = 18.0     # degC
+        s.heat.node_overrides.set(HeatSourceKind.DWF, "J1", 21.5)
+
+        s.run()
+        print(s.heat.current_shortwave, s.heat.cloud.current)
+
+.. note::
+
+   Edits are **live**: the flux modules re-read the configuration every
+   step, so a mid-run write takes effect on the next routing step.
+
+----
+
+Flux modules
+============
+
+:attr:`Heat.modules` is a keyed, iterable mapping of
+:class:`HeatFluxModule` to ``bool``; the three modules —
+``SURFACE_EXCHANGE`` (latent + sensible), ``RADIATIVE_EXCHANGE``
+(shortwave + longwave) and ``LAYER_CONDUCTION`` (LID vertical
+conduction) — toggle independently.
+
+----
+
+Radiative parameters and the shortwave mode
+===========================================
+
+:attr:`Heat.radiative` maps :class:`HeatRadiativeParam` to ``float``.
+Every entry except ``SHORTWAVE`` is a fraction restricted to ``[0, 1]``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 44 56
+
+   * - Parameter
+     - Units / range
+   * - ``SHORTWAVE``
+     - Incoming shortwave, W/m². Non-negative.
+   * - ``ALBEDO``
+     - **Water** reflectance R\ :sub:`s`.
+   * - ``SHADE_FACTOR`` / ``SKY_VIEW`` / ``EMISS_WATER`` /
+       ``EMISS_LANDCOVER`` / ``ATM_EMISS_COEFF`` / ``LW_REFLECTION``
+     - Shading, sky view, the two emissivities, the Brunt coefficient
+       and longwave reflection.
+
+:attr:`Heat.shortwave_mode` selects one of three
+:class:`HeatShortwaveMode` spellings, which are **mutually exclusive in
+effect** — exactly one is read, and there is no precedence ladder.
+
+* ``CONSTANT`` reads ``HeatRadiativeParam.SHORTWAVE``.
+* ``TIMESERIES`` reads the record bound by
+  :meth:`Heat.set_shortwave_timeseries` (which also switches the mode).
+* ``COMPUTED`` runs a Spencer/NOAA solar position through a Bird
+  clear-sky model, using ``[SOLAR_RADIATION]``.
+
+Two refusals matter here:
+
+* Writing ``HeatRadiativeParam.SHORTWAVE`` while the mode is **not**
+  ``CONSTANT`` is refused. A constant is not read in the other two modes,
+  so storing one there would look configured while changing nothing.
+  Switch the mode first.
+* Selecting ``HeatShortwaveMode.COMPUTED`` is refused unless **both**
+  latitude and longitude have been set explicitly. The engine will not
+  borrow the ``[TEMPERATURE]`` snowmelt latitude, which defaults to 0 and
+  would silently model equatorial noon.
+
+**Switching modes does not erase the other modes' stored settings.** A
+constant stays stored while a timeseries is active, and vice versa, so an
+editor can offer three radio buttons without destroying what the user
+typed under the other two.
+
+:attr:`Heat.current_shortwave` is the resolved incoming shortwave at the
+current step in W/m², cloud already applied. It is **read-only state, not
+configuration**: it is ``0.0`` before the first step and whenever
+radiative exchange is off.
+
+----
+
+Solar siting
+============
+
+:attr:`Heat.solar` maps :class:`HeatSolarParam` to ``float`` and is
+consulted under ``COMPUTED`` only. ``LATITUDE`` is degrees ``[-90, 90]``,
+``LONGITUDE`` degrees ``[-180, 180]``, ``ELEVATION`` metres
+``[-500, 9000]`` (below sea level is legal), plus the Bird atmosphere
+terms ``TURBIDITY_380``, ``TURBIDITY_500``, ``PRECIP_WATER`` and
+``OZONE``.
+
+.. warning::
+
+   ``HeatSolarParam.GROUND_ALBEDO`` is the **land** albedo used by the
+   Bird model. It is *not* the water reflectance — that is
+   ``HeatRadiativeParam.ALBEDO``. They are separate values with separate
+   meanings, and writing one does not change the other.
+
+:attr:`Heat.solar_sited` is ``True`` once latitude **and** longitude have
+both been written explicitly. Gate a ``COMPUTED`` control on this rather
+than discovering the refusal after the fact.
+
+----
+
+Cloud cover
+===========
+
+:attr:`Heat.cloud` maps :class:`HeatCloudParam` to ``float``. Writing any
+of them marks cloud cover configured, which ``cloud.configured``
+reports. ``FRACTION`` is a fraction in ``[0, 1]`` — not a percent — and
+the Kasten–Czeplak / Bolz coefficients must be non-negative.
+
+.. code-block:: python
+
+    s.heat.cloud.set_timeseries("CLOUD_OBS")   # bind a [TIMESERIES]
+    print(s.heat.cloud.configured, s.heat.cloud.current)
+    s.heat.cloud.clear()                       # back to clear sky
+
+``cloud.clear()`` restores the exact clear-sky longwave path, not an
+approximation of it. ``cloud.current`` is the cloud fraction in effect at
+the current step — read-only state, zero before the first step.
+
+----
+
+Heat sources and node overrides
+===============================
+
+:attr:`Heat.sources` maps :class:`HeatSourceKind` to a **global** inlet
+temperature in degC. The table is a fixed enum extent of seven entries,
+so ``len(s.heat.sources)`` never depends on what the model configured.
+
+.. code-block:: python
+
+    s.heat.sources[HeatSourceKind.RDII] = 12.0
+    s.heat.sources.is_configured(HeatSourceKind.RDII)   # True
+    s.heat.sources.clear(HeatSourceKind.RDII)           # back to the 20 degC default
+
+    # Resolution the engine itself uses: override if present, else global.
+    s.heat.sources.effective(HeatSourceKind.DWF, "J1")
+
+Temperatures outside ``[-50, 100]`` degC are refused — the parser's own
+range. An unconfigured source reads the 20 degC default;
+``sources.is_configured()`` is what tells the two apart, and
+``sources.clear()`` returns a source to the default so the writer emits
+no row for it (node overrides are left alone).
+
+:attr:`Heat.node_overrides` is a row-indexed sequence of
+:class:`HeatNodeOverride` named tuples:
+
+.. code-block:: python
+
+    s.heat.node_overrides.set(HeatSourceKind.EXTERNAL_INFLOW, "J1", 25.0)
+    for row in s.heat.node_overrides:
+        print(row.source, row.node_index, row.temp_c)
+    s.heat.node_overrides.remove(0)
+
+.. warning::
+
+   Only ``HeatSourceKind.DWF`` and ``HeatSourceKind.EXTERNAL_INFLOW``
+   accept node scope. Any other source is **refused**, not silently
+   deferred to the global value.
+
+Setting the same ``(source, node)`` pair twice is an **update**, not a
+duplicate row. ``node_overrides.remove()`` shifts later rows down,
+so re-read ``len()`` when iterating by index.
+
+----
+
+See also
+========
+
+* :doc:`water_age` — the same source/override table shape, in hours.
+* :doc:`initial_quality` — seeding ``__TEMPERATURE__`` per element.
+* :doc:`climate` — the temperature and wind the surface-exchange module
+  consumes.
+* :doc:`process_components` — where ``model.heat``'s config path lives.
+* :doc:`error_handling` — what a refused write raises.
+
+Timeseries names
+================
+
+``heat.shortwave_timeseries`` and ``heat.cloud.timeseries`` return the assigned
+series name, or an empty string when no series is bound. Use the corresponding
+``set_shortwave_timeseries(name)`` and ``cloud.set_timeseries(name)`` methods
+to assign an existing series. Shortwave values are W/m²; cloud values are
+fractions in [0, 1].
diff --git a/python/docs/guide/index.rst b/python/docs/guide/index.rst
index 10e1267d7..5f9f5b948 100644
--- a/python/docs/guide/index.rst
+++ b/python/docs/guide/index.rst
@@ -34,7 +34,9 @@ Running a simulation
 
    solver
    error_handling
+   native_safety
    datetime
+   catalog
 
 Domain access
 =============
@@ -76,6 +78,25 @@ Pollutants, landuse, buildup/washoff, treatment.
 
    pollutants
    quality
+   initial_quality
+
+Transport processes
+===================
+
+Heat transport, water age, multi-species reactions, and
+process-component registration.
+
+.. toctree::
+   :maxdepth: 1
+
+   heat
+   water_age
+   reactions
+   process_components
+   transport
+   groundwater
+   surface_quality
+   binding_updates
 
 Outputs
 =======
@@ -110,7 +131,7 @@ configure complex hydraulic infrastructure; spatial / CRS handling.
 ===================================
 
 Overlay a triangular mesh on the 1-D network and route the surface with a
-CVODE solver; persist results and observed data to a GeoPackage.
+explicit finite-volume solver; persist results and observed data to a GeoPackage.
 
 .. toctree::
    :maxdepth: 1
diff --git a/python/docs/guide/initial_quality.rst b/python/docs/guide/initial_quality.rst
new file mode 100644
index 000000000..298a76023
--- /dev/null
+++ b/python/docs/guide/initial_quality.rst
@@ -0,0 +1,150 @@
+========================================
+Initial quality  (``[INITIAL_QUALITY]``)
+========================================
+
+.. note::
+
+   **Engine:** OpenSWMM 6 — refactored.
+
+.. currentmodule:: openswmm.engine
+
+``solver.initial_quality`` is the row-based view over
+``[INITIAL_QUALITY]``: per-element starting concentrations for nodes and
+links. Rows are indexed ``0 .. len-1`` in file order and seed state at
+``initialize()``.
+
+Reference: ``openswmm_initial_quality.h``.
+
+----
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from openswmm.engine import Solver, InitialQuality
+
+    s = Solver("model.inp")
+    try:
+        s.open()
+        s.initial_quality.set("TSS", 12.5, node="J1")
+        s.initial_quality.set("TSS", 3.0, link="C1")
+
+        # Reserved species: hours (signed) and degC.
+        s.initial_quality.set(InitialQuality.WATER_AGE, 6.0, node="J1")
+        s.initial_quality.set(InitialQuality.TEMPERATURE, 14.2, node="J1")
+
+        for row in s.initial_quality:
+            print(row.is_link, row.elem_index, row.constituent, row.value)
+
+        s.initial_quality.remove(0)     # later rows shift down
+    finally:
+        s.close()
+        s.destroy()
+
+.. warning::
+
+   Mutation is **BUILDING/OPENED only**. Rows seed state at
+   ``initialize()``, so writing them mid-run would change nothing — the
+   same contract as :attr:`Pollutant.init_conc`.
+
+----
+
+Rows are an upsert
+==================
+
+:meth:`InitialQuality.set` is an **upsert keyed on**
+``(is_link, elem_index, constituent)``. Writing the same triple twice
+updates the existing row rather than appending a duplicate, so an editor
+can change a value it just wrote.
+
+Pass exactly one of ``node=`` or ``link=``; either accepts an ``int``
+index or a ``str`` id.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 42 58
+
+   * - Operation
+     - Behaviour
+   * - ``len(s.initial_quality)``
+     - Number of rows.
+   * - ``s.initial_quality[row_index]``
+     - One :class:`InitialQualityEntry` —
+       ``(is_link, elem_index, constituent, value)``.
+   * - ``for row in s.initial_quality:``
+     - Iterate rows in file order.
+   * - ``.set(constituent, value, *, node=..., link=...)``
+     - Upsert on the ``(is_link, elem_index, constituent)`` key.
+   * - ``.remove(row_index)``
+     - Delete by **row index**.
+
+.. warning::
+
+   :meth:`InitialQuality.remove` shifts every later row down by one, so a
+   cached row index goes **stale** the moment anything before it is
+   removed. Re-enumerate after removing, or remove from the highest index
+   downward.
+
+``elem_index`` reads ``-1`` when the row's element could not be resolved.
+
+----
+
+Constituents
+============
+
+The constituent is a **name**: either a ``[POLLUTANTS]`` pollutant, or
+one of two reserved species exposed as class attributes so you never have
+to spell the sentinel by hand.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 32 20 48
+
+   * - Constituent
+     - Units
+     - Notes
+   * - A ``[POLLUTANTS]`` name
+     - Pollutant's own units
+     - Concentration. **Must be non-negative** — a negative value is
+       refused.
+   * - :attr:`InitialQuality.WATER_AGE`
+     - hours
+     - The literal ``"__WATER_AGE__"``. **Signed** — negative values are
+       legal.
+   * - :attr:`InitialQuality.TEMPERATURE`
+     - degC
+     - The literal ``"__TEMPERATURE__"``. Signed.
+
+An unknown constituent name, a bad element index, or a negative pollutant
+value is refused.
+
+.. code-block:: python
+
+    InitialQuality.WATER_AGE     # "__WATER_AGE__"
+    InitialQuality.TEMPERATURE   # "__TEMPERATURE__"
+
+----
+
+See also
+========
+
+* :doc:`pollutants` — declaring the pollutants these rows may name, and
+  the model-wide :attr:`Pollutant.init_conc` default.
+* :doc:`quality` — buildup, washoff, and treatment.
+* :doc:`water_age` — the source-age table the ``__WATER_AGE__`` rows seed
+  against.
+* :doc:`heat` — the source-temperature table behind ``__TEMPERATURE__``.
+* :doc:`error_handling` — what a refused row raises.
+
+Sidecar provenance
+==================
+
+``initial_quality.file_path`` preserves the authored CSV reference. Assign a
+path to record it, or ``None``/an empty string to clear it. Assignment does not
+read the file: the engine loads it on the next open. ``is_file(row_index)``
+identifies loaded sidecar rows and accepts negative sequence indices. Inline
+rows and sidecar rows retain their native save/provenance behavior.
+
+Keys must be unique across inline and sidecar rows; duplicate element/species
+rows cause a parse error when opening the model.
diff --git a/python/docs/guide/links.rst b/python/docs/guide/links.rst
index ed40d280e..fe0fc60da 100644
--- a/python/docs/guide/links.rst
+++ b/python/docs/guide/links.rst
@@ -209,6 +209,11 @@ Wrapper: :class:`Link`
      - ``float``
      - read-only
      -
+   * - ``slot_volume``
+     - ``float``
+     - read-only
+     - Water in the Preissmann slot — the part of ``volume`` above the
+       crown. Finite-volume routing only; ``0.0`` under dynamic wave.
    * - ``hyd_power``
      - ``float``
      - read-only
@@ -328,6 +333,8 @@ links:
     print(c1.stats.max_filling)
     print(c1.stats.vol_flow)
     print(c1.stats.surcharge_time)
+    print(c1.stats.peak_slot_share)
+    print(c1.stats.slot_share)
 
     p1 = s.links["P1"]
     print(p1.stats.pump_cycles)
@@ -336,6 +343,13 @@ links:
 
 These values are only meaningful after :meth:`Solver.end`.
 
+``peak_slot_share`` is the peak instantaneous ``slot_volume / volume``
+over the run; ``slot_share`` is the run-level
+``(∫ slot_volume dt) / (∫ volume dt)`` — a ratio of time integrals, never
+an average of instantaneous ratios. Both are ``0..1``, and both are
+finite-volume-routing only: under the dynamic-wave router they read
+``0.0``, which is indistinguishable from "no slot flow occurred".
+
 ----
 
 Staleness, equality, repr
@@ -361,3 +375,12 @@ See also
 * :doc:`controls` — runtime control of link ``control_setting`` and
   ``target_setting``.
 * :doc:`error_handling` — every exception type referenced on this page.
+
+Authored conduit orientation
+=============================
+
+Editing hosts can call ``solver.links.restore_authored_orientation()`` after
+opening to undo adverse-slope conduit reversal. The return value is the number
+of conduits restored; a repeated call returns zero. Reacquire retained object
+views after a change. Simulation-only hosts do not need this operation, and
+the INP writer already restores authored orientation during serialization.
diff --git a/python/docs/guide/massbalance.rst b/python/docs/guide/massbalance.rst
index c01cfd49c..42377c3fa 100644
--- a/python/docs/guide/massbalance.rst
+++ b/python/docs/guide/massbalance.rst
@@ -18,8 +18,8 @@ simulation. Reach the view via :attr:`Solver.mass_balance`:
             pass
 
         mb = s.mass_balance
-        print(mb.runoff_continuity_error)        # %
-        print(mb.routing_continuity_error)       # %
+        print(mb.runoff_continuity_error)        # fraction
+        print(mb.routing_continuity_error)       # fraction
 
 Reference: ``openswmm_massbalance.h``.
 
@@ -37,13 +37,13 @@ Continuity errors
      - Meaning
    * - ``runoff_continuity_error``
      - ``float``
-     - Runoff continuity error (%).
+     - Runoff continuity error (fraction).
    * - ``routing_continuity_error``
      - ``float``
-     - Flow routing continuity error (%).
+     - Flow routing continuity error (fraction).
    * - ``quality_continuity_error(pollutant)``
      - ``float``
-     - Per-pollutant quality continuity error (%); accepts id or index.
+     - Per-pollutant quality continuity error (fraction); accepts id or index.
 
 ----
 
@@ -115,3 +115,13 @@ See also
 * :doc:`output_reader` — read mass-balance data from a written ``.out``
   file without an active engine.
 * :doc:`error_handling`.
+
+Snapshot accounting
+===================
+
+The three ``MassBalance`` continuity-error accessors return fractions: 0.001
+means 0.1 percent. ``get_report_snapshot(solver)`` converts these to percentages
+in fields named ``continuity_error_pct`` and uses the current typed routing
+diagnostics. Its runoff record includes initial/final snow storage. Its routing
+record includes forcing inflow, coupling outflow and link-groundwater inflow.
+Forcing inflow is a subset of external inflow, so do not add those two totals.
diff --git a/python/docs/guide/native_safety.rst b/python/docs/guide/native_safety.rst
new file mode 100644
index 000000000..79b48a4b9
--- /dev/null
+++ b/python/docs/guide/native_safety.rst
@@ -0,0 +1,59 @@
+Engine ownership and callbacks
+==============================
+
+A ``Solver`` owns its native engine. Its domain views retain that owner, so a
+view cannot outlive the Python object that manages its native memory. Calling
+``close()`` or ``destroy()`` invalidates retained 2D and infiltration views;
+structural edits also invalidate these views. Reacquire ``solver.surface2d``
+after reopening or editing a model. Invalidated views raise
+``StaleObjectError`` before entering the native library.
+
+Use ``solver.surface2d`` or ``Surface2D(solver)``. Passing ``solver.handle`` to
+``Surface2D`` is deprecated. For compatibility it is accepted only when the
+address belongs to a live registered Python owner. Arbitrary native addresses
+are rejected with ``BadHandleError``.
+
+``ModelBuilder.to_solver()`` transfers ownership once. Existing builder views
+become stale, and a second transfer raises ``BadHandleError``. The returned
+solver has the same initialized Python state as a normally constructed solver.
+
+Threads
+-------
+
+Different solvers may advance on different threads. Calls that release the
+Python GIL pin their engine owner for the duration of the native operation.
+Access from another thread to that same engine raises ``LifecycleError``
+promptly. This includes attempts to destroy the engine while it is advancing.
+Coordinate access in the application and collect snapshots between steps.
+
+Callbacks
+---------
+
+Step callbacks run on the advancing thread. They may inspect results and apply
+forcing supported at that stage by the engine. They must not reenter lifecycle
+operations such as ``step()``, ``close()`` or ``destroy()``, or replace callback
+registrations while a callback is active; these operations raise
+``LifecycleError``.
+
+A Python exception cannot unwind through the native callback ABI. The binding
+captures the first exception and re-raises that same exception when the native
+operation returns. Later callbacks in that operation are suppressed. The
+current native step may finish, so callback failure does not roll back the
+simulation. This behavior applies to ``step()``, ``stride()``, ``steps()`` and
+``until()``. Unregister or repair the failing callback before advancing again.
+
+Testing a local build
+---------------------
+
+Use the project's ``openswmm`` Conda environment for validation::
+
+    conda run --no-capture-output -n openswmm python -m pytest tests/engine
+
+Run this command from ``python/`` after building/installing the checkout into
+that environment, or set ``PYTHONPATH`` to a staged build. Verify the loaded
+extension path before testing::
+
+    conda run -n openswmm python -c "import openswmm.engine._solver as m; print(m.__file__)"
+
+A successful test of an older installed package does not validate a changed
+checkout. Rebuild all extensions after changing a shared ``.pxd`` declaration.
diff --git a/python/docs/guide/process_components.rst b/python/docs/guide/process_components.rst
new file mode 100644
index 000000000..0627efeec
--- /dev/null
+++ b/python/docs/guide/process_components.rst
@@ -0,0 +1,147 @@
+==============================================
+Process components  (``[PROCESS_COMPONENTS]``)
+==============================================
+
+.. note::
+
+   **Engine:** OpenSWMM 6 — refactored.
+
+.. currentmodule:: openswmm.engine
+
+``solver.process_components`` enumerates and edits the
+``[PROCESS_COMPONENTS]`` registrations — the file-binding surface that
+tells the engine which optional process components (heat, water age,
+reactions, …) are active and where each one's config file lives.
+
+Reference: ``openswmm_process_components.h``.
+
+----
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from openswmm.engine import Solver
+
+    with Solver("model.inp") as s:
+        for c in s.process_components:
+            print(c.component_index, c.id, c.config, c.resolved)
+
+        "heat" in s.process_components          # membership by id
+        s.process_components["heat"].config     # config="…" as written
+
+        # Register first, then write the file it points at.
+        s.process_components.register("waterage", "model.age")
+        open("model.age", "w").write("[WATER_AGE_SOURCES]\n")
+
+        s.process_components.remove("waterage")
+
+.. warning::
+
+   ``register`` and ``remove`` are **BUILDING/OPENED only**.
+
+----
+
+The registration record
+=======================
+
+Each entry is a :class:`ProcessComponent` named tuple.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Field
+     - Meaning
+   * - ``component_index``
+     - Position in the section, ``0 .. len-1``.
+   * - ``id``
+     - Component id, e.g. ``"heat"``.
+   * - ``config``
+     - The ``config="…"`` argument **exactly as written**. May be ``""``
+       when the registration named no file.
+   * - ``resolved``
+     - The effective path the config was actually **read from** at the
+       last open.
+
+.. important::
+
+   ``resolved`` is ``""`` until the last open resolved it. An empty
+   ``resolved`` therefore means "not resolved yet", not "no file" — check
+   ``config`` to tell the two apart. On a model built programmatically
+   and never opened, every ``resolved`` is empty.
+
+----
+
+Enumerating and finding
+=======================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 44 56
+
+   * - Operation
+     - Behaviour
+   * - ``len(s.process_components)``
+     - Number of registrations.
+   * - ``s.process_components[key]``
+     - One :class:`ProcessComponent` by ``int`` index or ``str`` id.
+   * - ``for c in s.process_components:``
+     - Iterate in section order.
+   * - ``"heat" in s.process_components``
+     - Membership test on the component id.
+   * - ``.get_index(component_id)``
+     - Registration index for an id.
+   * - ``.register(component_id, config_path="")``
+     - Add a registration; returns the new
+       :class:`ProcessComponent`.
+   * - ``.remove(key)``
+     - Delete by index or id.
+
+----
+
+Registering before the file exists
+==================================
+
+The "create a component and its config file" flow **registers first,
+then writes the file**. A ``config_path`` that does not exist yet is
+legal: the path is stored as written, and resolution happens at the next
+open.
+
+.. code-block:: python
+
+    c = s.process_components.register("reactions", "chlorine.rxn")
+    assert c.resolved == ""              # nothing resolved it yet
+    s.reactions.save("chlorine.rxn")     # now the file exists
+
+.. warning::
+
+   * A **duplicate id is refused.** Check with ``in`` or
+     :meth:`ProcessComponents.get_index` before registering, rather than
+     relying on a retry.
+   * :meth:`ProcessComponents.remove` **shifts** the indices of every
+     later registration. Cached ``component_index`` values go stale — re-enumerate,
+     or address components by id.
+
+----
+
+See also
+========
+
+* :doc:`heat` — the ``model.heat`` component.
+* :doc:`water_age` — the ``model.age`` component, and
+  :meth:`WaterAge.save`.
+* :doc:`reactions` — the ``.rxn`` component, and :meth:`Reactions.save`.
+* :doc:`model_builder` — building a model that registers components from
+  scratch.
+* :doc:`error_handling` — what a duplicate id or a bad index raises.
+
+Built-in registry
+=================
+
+``solver.process_components.known()`` returns immutable registry entries with
+``id``, ``description`` and ``implemented`` fields. The registry describes the
+build's vocabulary; it differs from the components configured on a model.
+Entries with ``implemented=False`` are placeholders and cannot supply a process
+implementation merely by being registered in the model.
diff --git a/python/docs/guide/reactions.rst b/python/docs/guide/reactions.rst
new file mode 100644
index 000000000..67bc40a92
--- /dev/null
+++ b/python/docs/guide/reactions.rst
@@ -0,0 +1,203 @@
+========================================================
+Reactions  (multi-species: species, coefficients, terms)
+========================================================
+
+.. note::
+
+   **Engine:** OpenSWMM 6 — refactored.
+
+.. currentmodule:: openswmm.engine
+
+``solver.reactions`` is the editable multi-species reaction system — the
+``[REACTION_*]`` sections of a ``.rxn`` component file — as live objects:
+species with per-scope expressions, coefficients, intermediate terms,
+initial-quality rows, a whole-file text surface, and an engine-less
+static vocabulary for completers.
+
+Reference: ``openswmm_reactions.h``.
+
+----
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from openswmm.engine import Solver, ReactionScope, ReactionExprForm
+
+    with Solver("model.inp") as s:
+        k = s.reactions.coefficients.add("Kb", parameter=False, value=0.3)
+        cl = s.reactions.species.add("CL2", units="MG", atol=1e-4, rtol=1e-4)
+
+        cl.set_expression(ReactionScope.PIPE, ReactionExprForm.RATE, "-Kb*CL2")
+        cl.set_expression(ReactionScope.TANK, ReactionExprForm.RATE, "-Kb*CL2")
+
+        diag = s.reactions.validate("-Kb*CL2", ReactionScope.PIPE)
+        print(diag.valid, diag.message, diag.column)
+
+        text = s.reactions.serialize()      # canonical .rxn text
+        s.reactions.apply_text(text)        # transactional round trip
+        s.reactions.save("model.rxn")
+
+.. warning::
+
+   Mutation is **BUILDING/OPENED only** — reaction rows seed state at
+   ``initialize()``, so there is nothing meaningful to change once a run
+   is under way.
+
+----
+
+Eager validation: a stored model is never uncompilable
+======================================================
+
+Every mutator validates **eagerly**. The whole reaction system is
+recompiled before the call returns, and a mutation that would leave any
+expression uncompilable is **rolled back and refused**. There is no
+deferred check at run time and no "save now, discover later": if the call
+succeeded, the system compiles.
+
+Two consequences follow directly:
+
+* Removing a species, coefficient, or term that any compiled expression
+  still references is **refused**. Rewrite the referring expressions
+  first, then remove.
+* An editor can never store an uncompilable model, so it does not need a
+  separate "is this model still valid?" pass after each keystroke.
+
+:meth:`Reactions.validate` is the read-only counterpart — compile-only,
+zero state change — returning an :class:`ExpressionDiagnostic` named
+tuple of ``(valid, message, column)``. ``column`` is 1-based, or ``-1``
+when the diagnostic is not attributable to a position.
+
+.. note::
+
+   Under :attr:`ReactionScope.TERM`, validation accepts references to
+   **all** terms, including ones defined later. The forward-only ordering
+   rule is enforced at file-apply time, where ordinal position exists.
+   Validation answers "is this well-formed against the vocabulary", not
+   "is the file orderable".
+
+----
+
+Species, coefficients, terms
+============================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Collection
+     - Contents
+   * - :attr:`Reactions.species`
+     - :class:`ReactionSpecies` — ``name``, ``is_wall``, ``units``,
+       ``atol``, ``rtol``, ``initial``, and the two scope expressions.
+   * - :attr:`Reactions.coefficients`
+     - :class:`ReactionCoefficient` — ``name``, ``is_param``
+       (PARAMETER vs CONSTANT), ``value``.
+   * - :attr:`Reactions.terms`
+     - :class:`ReactionTerm` — ``name`` and its source ``expression``.
+   * - :attr:`Reactions.initial`
+     - :class:`ReactionInitialEntry` rows —
+       ``(is_link, elem_index, species_index, value)``.
+
+All three collections support ``len()``, iteration, ``in``, indexing by
+``int | str``, ``get_index(key)``, ``add(...)`` and ``remove(key)``.
+
+.. code-block:: python
+
+    for sp in s.reactions.species:
+        print(sp.index, sp.name, sp.units, sp.is_wall)
+
+    "CL2" in s.reactions.species          # True
+    s.reactions.species.get_index("CL2")  # 0
+
+    s.reactions.terms.add("Kf", "1.5826e-4*RE^0.88/D")
+
+Per-scope expressions
+---------------------
+
+A species carries one expression per scope. Read them through
+:attr:`ReactionSpecies.pipe_expression` /
+:attr:`ReactionSpecies.tank_expression`, or generically through
+:meth:`ReactionSpecies.get_expression`; both return a
+``(ReactionExprForm, str)`` pair.
+:meth:`ReactionSpecies.set_expression` writes one, and passing
+:attr:`ReactionExprForm.NONE` **clears** it.
+
+.. code-block:: python
+
+    form, expr = s.reactions.species["CL2"].get_expression(ReactionScope.PIPE)
+    s.reactions.species["CL2"].set_expression(
+        ReactionScope.TANK, ReactionExprForm.NONE)
+
+Options are canonical string tokens via :meth:`Reactions.get_option` /
+:meth:`Reactions.set_option`, keyed on ``SOLVER``, ``COUPLING``,
+``RATE_UNITS``, ``AREA_UNITS``, ``TIMESTEP``, ``ATOL`` and ``RTOL``.
+
+----
+
+Whole-file text surface
+=======================
+
+:meth:`Reactions.serialize` renders canonical ``.rxn`` text from engine
+state; :meth:`Reactions.apply_text` replaces the whole system from text;
+:meth:`Reactions.check_text` is the dry run, with zero state change on
+success or failure. :meth:`Reactions.save` writes to the component's
+bound config path, or to an explicit ``path``.
+
+.. code-block:: python
+
+    text = s.reactions.serialize()
+    diag = s.reactions.check_text(text)      # ExpressionDiagnostic
+    s.reactions.apply_text(text)
+    assert s.reactions.serialize() == text   # byte-identical
+
+Two guarantees this surface makes:
+
+* **Round trip.** ``serialize() -> apply_text() -> serialize()`` is
+  byte-identical. A text editor tab can hand the user its own output back
+  without churn.
+* **Transactional apply.** :meth:`Reactions.apply_text` is staged: on
+  **any** error, the previous system — reaction state and registry block
+  alike — is byte-identical to what it was before the call. A failed
+  paste costs nothing.
+
+----
+
+Static vocabulary  (completers)
+===============================
+
+:meth:`Reactions.hydraulic_variables` and :meth:`Reactions.functions` are
+``staticmethod``\ s: they need **no engine and no open model**, and are
+usable before anything is loaded.
+
+.. code-block:: python
+
+    from openswmm.engine import Reactions
+
+    for hv in Reactions.hydraulic_variables():
+        print(hv.name, hv.description)        # ReactionHydVar
+
+    for fn in Reactions.functions():
+        print(fn.name, fn.arity)              # ReactionFunction
+
+.. important::
+
+   These two are the **authoritative** completer and syntax-highlighter
+   vocabulary, sourced from the expression compiler's own tables. Tooling
+   must enumerate them rather than hard-code a list — that is what makes
+   vocabulary drift structurally impossible instead of a matter of
+   discipline. Combine them with the live
+   :attr:`Reactions.species` / :attr:`Reactions.coefficients` /
+   :attr:`Reactions.terms` names for the full identifier set.
+
+----
+
+See also
+========
+
+* :doc:`pollutants` — reaction expressions may reference pollutants.
+* :doc:`initial_quality` — the ``[INITIAL_QUALITY]`` sibling surface.
+* :doc:`process_components` — registering the ``.rxn`` config path.
+* :doc:`quality` — single-species buildup/washoff and treatment.
+* :doc:`error_handling` — what a refused mutation raises.
diff --git a/python/docs/guide/solver.rst b/python/docs/guide/solver.rst
index d17ca91a4..52e4c574c 100644
--- a/python/docs/guide/solver.rst
+++ b/python/docs/guide/solver.rst
@@ -402,3 +402,12 @@ See also
 * :doc:`datetime` — SWMM DateTime ↔ Python ``datetime`` conversion.
 * :doc:`nodes`, :doc:`links`, :doc:`subcatchments`, :doc:`output_reader` —
   the most-used domain accessors.
+
+Compatibility output
+====================
+
+``solver.write_compat(path, InpProfile.FULL)`` writes native OpenSWMM input.
+``InpProfile.SWMM5`` targets the OpenSWMM legacy engine, while
+``InpProfile.SWMM5_STOCK`` targets stock EPA SWMM 5 input. Compatibility profiles
+may substitute or omit unsupported features. Inspect ``solver.open_warnings``
+after writing for conversion diagnostics. The live model is not modified.
diff --git a/python/docs/guide/surface_quality.rst b/python/docs/guide/surface_quality.rst
new file mode 100644
index 000000000..56a58a070
--- /dev/null
+++ b/python/docs/guide/surface_quality.rst
@@ -0,0 +1,35 @@
+Surface water quality
+=====================
+
+``solver.surface2d.quality`` exposes 2D land-use coverage, initial buildup and
+curb-length tables. Acquire it after ``solver.open()`` and edit before
+initialization. The view retains its solver and becomes stale after structural
+or lifecycle changes; reacquire it after adding land uses or pollutants.
+
+``CellScope`` selects GLOBAL, TAG or CELL. More specific rows override broader
+ones at runtime. Cell indices are zero-based for both triangles and quads.
+
+.. code-block:: python
+
+   from openswmm.engine import CellScope
+
+   quality = solver.surface2d.quality
+   quality.set_coverage(CellScope.GLOBAL, {'URBAN': 100})
+   quality.set_loading(CellScope.GLOBAL, 'TSS', 10)
+   quality.set_loading(CellScope.TAG, 'TSS', 20, tag='PAN')
+   quality.set_curb_length(CellScope.GLOBAL, 25)
+
+``set_coverage`` replaces the entire land-use mapping at a scope. Values are
+percentages; names must identify existing land uses and the engine validates
+the total. Use ``remove_coverage(index)`` to clear a row. The ``coverages``,
+``loadings`` and ``curb_lengths`` properties are immutable snapshots. Removing
+a row shifts subsequent indices.
+
+Initial loading and runtime ``buildup(species)`` use project pollutant mass per
+acre/hectare. Curb length uses project length units. ``buildup`` requires an
+active surface-quality kernel and returns an owned float64 array in cell order.
+Changing the returned array never changes the model. The native buildup and
+washoff configuration determines whether the kernel is active.
+
+.. automodule:: openswmm.engine._surface_quality
+   :members:
diff --git a/python/docs/guide/tables.rst b/python/docs/guide/tables.rst
index a2a2da9e9..82e8dfe53 100644
--- a/python/docs/guide/tables.rst
+++ b/python/docs/guide/tables.rst
@@ -148,3 +148,13 @@ See also
 * :doc:`inflows` — DWF uses pattern ids; external inflows use time
   series ids.
 * :doc:`datetime` — how the time axis works.
+
+Relative-time metadata
+======================
+
+``timeseries.relative_info`` returns ``(leading_row_count, anchor)``. The anchor
+is a SWMM OADate in days. Stored point times remain absolute; subtract the
+anchor to recover the authored elapsed days. After rebuilding points, use
+``set_relative_info(count, anchor)`` to restore time-only INP serialization.
+A count of zero marks every row as explicitly dated. This operation changes
+metadata, not the stored point values.
diff --git a/python/docs/guide/transport.rst b/python/docs/guide/transport.rst
new file mode 100644
index 000000000..a91e307aa
--- /dev/null
+++ b/python/docs/guide/transport.rst
@@ -0,0 +1,55 @@
+Transport configuration and availability
+========================================
+
+``solver.transport`` exposes the configured ARD transport options. Dispersion
+coefficients use project length squared per second (ft²/s or m²/s), and
+``target_dx`` uses project length. Set both mode and coefficient for a uniform
+coefficient::
+
+    from openswmm.engine import Solver, TransportDispersionMode
+
+    solver = Solver("model.inp")
+    try:
+        solver.open()
+        solver.options["QUALITY_SOLVER"] = "EULERIAN_ARD"
+        component = "org.hydrocouple.openswmm.transport.ard"
+        if component not in solver.process_components:
+            solver.process_components.register(component, "model.ard")
+        solver.transport.dispersion_mode = TransportDispersionMode.VALUE
+        solver.transport.dispersion_value = 0.5
+        solver.transport.target_dx = 10.0
+        solver.initialize()
+        solver.start()
+        for elapsed in solver.steps():
+            pass
+        solver.end()
+    finally:
+        solver.close()
+        solver.destroy()
+
+For persistence, the model must register
+``org.hydrocouple.openswmm.transport.ard`` with a configuration-file path.
+``solver.write()`` then renders the live configuration to that component file.
+Setting values alone does not add a process-component registration.
+
+Configure transport before initialization. Setters mark the configuration as
+present; this does not establish that a particular backend carries every
+species in every domain. Inspect ``solver.transport_matrix`` after opening or
+editing options. It maps ``TransportDomain`` to ``TransportClass`` to immutable
+``TransportCell(state, count, reason)`` records. Disabled or unavailable cells
+explain why the process is absent.
+
+``transport.boundaries``, ``transport.sources`` and ``transport.conduit_dispersion``
+are tuples of snapshot records. Boundary/source rows are read-only in this
+native API revision; author them in the component file before opening. For a
+VALUE row, a boundary value is concentration in species units, and a source
+value is a mass rate in species mass units per second. For a TIMESERIES row,
+use the ``timeseries`` name instead of the numeric value.
+
+``solver.thread_info`` reports process-wide CPU and OpenMP limits.
+``solver.effective_threads(requested=0)`` reports the team sizes the engine
+would select for the current model; zero requests automatic selection. This
+query does not start a run or change the ``THREADS`` option.
+
+.. automodule:: openswmm.engine._transport
+   :members:
diff --git a/python/docs/guide/water_age.rst b/python/docs/guide/water_age.rst
new file mode 100644
index 000000000..9076a71e7
--- /dev/null
+++ b/python/docs/guide/water_age.rst
@@ -0,0 +1,146 @@
+====================================
+Water age  (``[WATER_AGE_SOURCES]``)
+====================================
+
+.. note::
+
+   **Engine:** OpenSWMM 6 — refactored.
+
+.. currentmodule:: openswmm.engine
+
+``solver.water_age`` is the editable view over the ``[WATER_AGE_SOURCES]``
+table of the ``model.age`` component: a **global** age per source
+pathway, plus per-node overrides for the two pathways that take node
+scope. All values are **hours**, the config file's own unit.
+
+Reference: ``openswmm_water_age.h``.
+
+----
+
+Quickstart
+==========
+
+.. code-block:: python
+
+    from openswmm.engine import Solver, WaterAgeSource
+
+    with Solver("model.inp") as s:
+        print(s.water_age.enabled)              # [OPTIONS] WATER_AGE
+
+        s.water_age.globals[WaterAgeSource.RAINFALL] = 0.0
+        s.water_age.globals[WaterAgeSource.GW] = 720.0        # hours
+        s.water_age.globals[WaterAgeSource.EXTERNAL_INFLOW] = -6.0
+
+        s.water_age.node_overrides.set(WaterAgeSource.DWF, "J1", 12.0)
+        for row in s.water_age.node_overrides:
+            print(row.source, row.node_index, row.hours)
+
+        s.water_age.save("model.age")
+
+.. note::
+
+   Edits are **live**: the loaders re-read the table every step, so a
+   mid-simulation write takes effect on the next routing step.
+
+----
+
+Global source ages
+==================
+
+:attr:`WaterAge.globals` maps :class:`WaterAgeSource` to ``float`` hours
+and supports ``len()``, iteration, ``in``, and ``int | str`` keys.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 66
+
+   * - Source
+     - Pathway
+   * - ``RAINFALL``
+     - Rainfall-derived water.
+   * - ``DWF``
+     - Dry-weather flow. **Takes node scope.**
+   * - ``GW``
+     - Groundwater.
+   * - ``RDII``
+     - Rainfall-derived infiltration and inflow.
+   * - ``EXTERNAL_INFLOW``
+     - ``[INFLOWS]``. **Takes node scope.**
+   * - ``IFACE``
+     - Interface file.
+   * - ``INITIAL_STATE``
+     - Water present at ``t = 0``.
+
+.. important::
+
+   **Negative values are legal.** A negative source age *extracts*
+   age-volume rather than adding it, and the result is clamped so the
+   computed age never goes below zero. Do not add a client-side
+   non-negative guard — it would reject a modelling construct the engine
+   supports deliberately. (Contrast :doc:`initial_quality`, where
+   *pollutant* values must be non-negative.)
+
+The C enum's trailing ``COUNT = 7`` sentinel is deliberately not mirrored
+in Python: ``len(WaterAgeSource)`` is the count.
+
+----
+
+Node overrides
+==============
+
+:attr:`WaterAge.node_overrides` is a row-indexed sequence of
+:class:`WaterAgeOverride` named tuples
+``(source, node_index, hours)``. Row order is stable across edits within
+a session.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 44 56
+
+   * - Operation
+     - Behaviour
+   * - ``len(s.water_age.node_overrides)``
+     - Number of override rows.
+   * - ``s.water_age.node_overrides[row]``
+     - One :class:`WaterAgeOverride` by row index.
+   * - ``.set(source, node, hours)``
+     - Add **or update** the row for ``(source, node)``.
+   * - ``.remove(source, node)``
+     - Delete by key, not by row index.
+
+.. warning::
+
+   Only ``WaterAgeSource.DWF`` and ``WaterAgeSource.EXTERNAL_INFLOW``
+   accept node scope — the parser's own rule. Any other source is
+   **refused**, not silently folded into the global value.
+
+Setting the same ``(source, node)`` pair twice is an update, so an editor
+can change a value it just wrote. Negative hours are legal here too.
+
+----
+
+Saving
+======
+
+:meth:`WaterAge.save` writes the current table as a
+``[WATER_AGE_SOURCES]`` component file — the ``model.age`` format the
+water-age component parses on the next open. It accepts ``str`` or any
+:class:`os.PathLike`.
+
+.. code-block:: python
+
+    from pathlib import Path
+
+    s.water_age.save(Path("scenarios") / "baseline.age")
+
+----
+
+See also
+========
+
+* :doc:`heat` — the same source/override table shape, in degC.
+* :doc:`initial_quality` — seeding ``__WATER_AGE__`` per element.
+* :doc:`inflows` — the DWF and ``[INFLOWS]`` pathways that take node
+  scope.
+* :doc:`process_components` — registering the ``model.age`` config path.
+* :doc:`error_handling` — what a refused write raises.
diff --git a/python/docs/index.rst b/python/docs/index.rst
index 3dfacf523..874f13b5c 100644
--- a/python/docs/index.rst
+++ b/python/docs/index.rst
@@ -137,7 +137,7 @@ Project at a glance
    * - **Build system**
      - scikit-build-core + CMake + Cython.
    * - **License**
-     - MIT.
+     - Apache License, Version 2.0.
 
 Related documentation
 =====================
diff --git a/python/docs/license.rst b/python/docs/license.rst
index 9f476a163..9c6e0ddaa 100644
--- a/python/docs/license.rst
+++ b/python/docs/license.rst
@@ -4,4 +4,15 @@
 License
 =======
 
+The OpenSWMM Python bindings are distributed under the Apache License,
+Version 2.0.
+
 .. literalinclude:: ../LICENSE
+
+Notice
+======
+
+The following attribution notice is distributed with the package and must be
+reproduced in derivative works, per section 4(d) of the License.
+
+.. literalinclude:: ../NOTICE
diff --git a/python/openswmm/__init__.py b/python/openswmm/__init__.py
index 7903d3075..2bc485657 100644
--- a/python/openswmm/__init__.py
+++ b/python/openswmm/__init__.py
@@ -1,9 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 openswmm -- Python bindings for the OpenSWMM stormwater modelling engine.
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Subpackages
 -----------
@@ -55,31 +71,39 @@
 
 
 # ---------------------------------------------------------------------------
-# Optional GPU/OpenMP acceleration companion
+# GPU/OpenMP acceleration of the 2D surface solver
 #
-# The base `openswmm` wheel is CPU-only and portable (Kokkos-free). OpenMP
-# acceleration of the 2D surface solver is shipped separately as the
-# `openswmm-gpu-omp` companion distribution, which installs a sibling import
-# package (`openswmm_gpu_omp`) containing the `libopenswmm_gpu_omp` plugin.
+# The plugin can be present twice:
 #
-# The C++ engine discovers the plugin at runtime via the OPENSWMM_GPU_PLUGIN_PATH
-# search path (SurfaceSolverFactory::search_dirs). When the companion is
-# installed, surface its directory to the engine by PREPENDING it to that env
-# var — without clobbering a value the user set deliberately. With no companion
-# installed this is a silent no-op and 2D runs on the serial CPU solver.
+#   1. IN-WHEEL — this wheel builds it and installs it into openswmm/engine/,
+#      beside openswmm_engine and the single bundled libomp.
+#   2. COMPANION — the `openswmm-gpu-omp` distribution installs a sibling
+#      import package (`openswmm_gpu_omp`) holding the same plugin, so it can
+#      be added or refreshed against an already-installed base.
 #
-# This must happen before any 2D model is initialised; import time (here) is
-# comfortably early enough, since the factory reads the env var lazily when it
-# builds a solver.
+# The engine discovers the plugin at runtime through the
+# OPENSWMM_GPU_PLUGIN_PATH search path (SurfaceSolverFactory::search_dirs), and
+# loads the FIRST match. Only one may ever be dlopen()ed: each copy is linked
+# against the libomp bundled next to it, and loading two OpenMP runtimes into
+# one process aborts every 2D run with "OMP: Error #15".
+#
+# So the in-wheel copy wins when it exists. It is the one guaranteed to match
+# both the engine binary it ships with and that engine's libomp; a companion
+# installed from a different build could satisfy neither. The companion is
+# registered only as a fallback, which is exactly the situation it was built
+# for — no in-wheel plugin, so nothing to conflict with.
+#
+# An OPENSWMM_GPU_PLUGIN_PATH the caller set is preserved, not clobbered — but
+# it is appended after ours, so it does not override the chosen copy. That is
+# the pre-existing behaviour of this shim, kept deliberately: prepending is what
+# makes the packaged plugin the default without the user opting in. A caller who
+# needs their own build to win should point the env var at it and uninstall the
+# packaged copy, or set it after import.
+#
+# This must happen before any 2D model is initialised; import time is early
+# enough, since the factory reads the env var lazily when it builds a solver.
 # ---------------------------------------------------------------------------
-def _register_gpu_companion() -> None:
-    try:
-        import openswmm_gpu_omp
-    except ImportError:
-        return  # companion not installed → CPU-only, nothing to do
-    plugin_dir = os.path.dirname(os.path.abspath(openswmm_gpu_omp.__file__))
-    if not os.path.isdir(plugin_dir):
-        return
+def _prepend_plugin_dir(plugin_dir: str) -> None:
     sep = os.pathsep  # ';' on Windows, ':' elsewhere — matches search_dirs()
     existing = os.environ.get("OPENSWMM_GPU_PLUGIN_PATH", "")
     parts = existing.split(sep) if existing else []
@@ -93,7 +117,34 @@ def _register_gpu_companion() -> None:
         os.add_dll_directory(plugin_dir)
 
 
-_register_gpu_companion()
+def _in_wheel_plugin_dir() -> "str | None":
+    """openswmm/engine/ if it holds a built GPU plugin, else None."""
+    engine_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "engine")
+    if not os.path.isdir(engine_dir):
+        return None
+    for name in os.listdir(engine_dir):
+        # libopenswmm_gpu_omp.{so,dylib} / openswmm_gpu_omp.dll, and the same
+        # for any other backend the wheel was built with (cuda, hip, sycl).
+        if "openswmm_gpu_" in name and name.endswith((".so", ".dylib", ".dll")):
+            return engine_dir
+    return None
+
+
+def _register_gpu_plugin() -> None:
+    in_wheel = _in_wheel_plugin_dir()
+    if in_wheel is not None:
+        _prepend_plugin_dir(in_wheel)
+        return  # do NOT also register the companion — see the note above
+    try:
+        import openswmm_gpu_omp
+    except ImportError:
+        return  # no plugin anywhere → 2D runs on the serial CPU solver
+    plugin_dir = os.path.dirname(os.path.abspath(openswmm_gpu_omp.__file__))
+    if os.path.isdir(plugin_dir):
+        _prepend_plugin_dir(plugin_dir)
+
+
+_register_gpu_plugin()
 
 # ---------------------------------------------------------------------------
 # Version
diff --git a/python/openswmm/engine/CMakeLists.txt b/python/openswmm/engine/CMakeLists.txt
index fa8041a53..0d06ec237 100644
--- a/python/openswmm/engine/CMakeLists.txt
+++ b/python/openswmm/engine/CMakeLists.txt
@@ -29,6 +29,12 @@ set(_engine_modules
     _controls
     _infrastructure
     _quality
+    _initial_quality
+    _reactions
+    _heat
+    _water_age
+    _transport
+    _process_components
     _statistics
     _output_reader
     _spatial
@@ -48,6 +54,13 @@ endforeach()
 
 # Optional 2-D module (off by default).
 if(OPENSWMM_BUILD_2D)
+    add_cython_extension(NAME _surface_quality TARGET engine__surface_quality SOURCE _surface_quality.pyx
+        INSTALL_DIR openswmm/engine LIBS openswmm::engine)
+    add_cython_extension(NAME _gw_transport TARGET engine__gw_transport SOURCE _gw_transport.pyx
+        INSTALL_DIR openswmm/engine LIBS openswmm::engine)
+    add_cython_extension(
+        NAME _groundwater TARGET engine__groundwater SOURCE _groundwater.pyx
+        INSTALL_DIR openswmm/engine LIBS openswmm::engine)
     add_cython_extension(
         NAME        _2d
         TARGET      engine__2d
diff --git a/python/openswmm/engine/_2d.pxd b/python/openswmm/engine/_2d.pxd
index d0d93cf1b..1646cc19d 100644
--- a/python/openswmm/engine/_2d.pxd
+++ b/python/openswmm/engine/_2d.pxd
@@ -15,6 +15,8 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_vertex_get_xyz_bulk(void* engine,
                                      double* x, double* y, double* z) nogil
     int swmm_2d_set_vertex_z(void* engine, int idx, double z)
+    # Bulk ground-elevation write — a pure C memory op over an owned buffer.
+    int swmm_2d_set_vertex_z_bulk(void* engine, const double* z, int count) nogil
     int swmm_2d_prepare_for_edit(void* engine)
     int swmm_2d_triangle_get_vertices(void* engine, int idx,
                                        int* v0, int* v1, int* v2)
@@ -35,6 +37,13 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_get_vertex_tag(void* engine, int idx, char* buf, int buflen)
     int swmm_2d_triangle_get_neighbours(void* engine, int idx,
                                          int* n0, int* n1, int* n2)
+    # Mixed triangle/quad meshes (2D_TRI_QUAD_MESH_PLAN_2026-09-06)
+    int swmm_2d_cell_count(void* engine, int* count)
+    int swmm_2d_quad_count(void* engine, int* count)
+    int swmm_2d_edge_stride(void* engine, int* stride)
+    int swmm_2d_cell_vertex_count(void* engine, int idx, int* nv)
+    int swmm_2d_cell_get_vertices(void* engine, int idx, int* v, int* nv)
+    int swmm_2d_cell_get_neighbours(void* engine, int idx, int* n, int* nv)
     int swmm_2d_edge_get_geometry_bulk(void* engine,
                                         double* length, double* nx, double* ny) nogil
 
@@ -79,6 +88,19 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_get_total_exchange_flow(void* engine, double* flow)
     int swmm_2d_get_solver_steps(void* engine, long* steps)
     int swmm_2d_get_solver_last_step(void* engine, double* h_last)
+    ctypedef struct SWMM_2DRunStats:
+        char   backend[64]
+        int    momentum
+        int    lts_tiers
+        long   steps
+        long   face_evals
+        double last_step
+        double active_frac_min
+        double active_frac_mean
+        double active_frac_max
+        int    n_tiers
+        long   tier_cells[8]
+    int swmm_2d_get_run_stats(void* engine, SWMM_2DRunStats* stats)
     int swmm_2d_get_stat_max_depths(void* engine, double* max_depths)
     int swmm_2d_get_stat_max_velocities(void* engine, double* max_velocities)
     int swmm_2d_get_stat_max_continuity_err(void* engine, double* max_errs)
@@ -130,6 +152,10 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_set_edge_bc_tseries_name(void* engine, int tri_idx, int edge, const char* name)
     int swmm_2d_set_edge_bc_flow_tseries_name(void* engine, int tri_idx, int edge, const char* name)
     int swmm_2d_set_edge_bc_rating_curve_name(void* engine, int tri_idx, int edge, const char* name)
+    # SVBC A8 — the setters' mirrors, so an edit can be read back.
+    int swmm_2d_get_edge_bc_tseries_name(void* engine, int tri_idx, int edge, char* buf, int buflen)
+    int swmm_2d_get_edge_bc_flow_tseries_name(void* engine, int tri_idx, int edge, char* buf, int buflen)
+    int swmm_2d_get_edge_bc_rating_curve_name(void* engine, int tri_idx, int edge, char* buf, int buflen)
 
     # Edge conveyance factor (§11A) — per-edge [0,1] multiplier on the
     # diffusion-wave flux; default 1.0; setter mirrors to the partner slot.
@@ -137,3 +163,37 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_set_edge_conveyance(void* engine, int tri, int edge, double conveyance)
     int swmm_2d_get_edge_conveyance_bulk(void* engine, double* conveyance) nogil
     int swmm_2d_reset_edge_conveyance(void* engine)
+
+
+# Per-cell 2D infiltration (plan §5.5.6, track I step I6).
+#
+# Row parameters (`p`) are in PROJECT UNITS — the same numbers a user types
+# into a legacy [INFILTRATION] row. The readback channels are SI like the rest
+# of the 2D API: rate is m/s, cumulative depth is m, total volume is m^3.
+# `p` is declared with the literal width of SWMM_INFIL2D_MAX_PARAMS (5).
+cdef extern from "openswmm_infil2d.h":
+    ctypedef struct SWMM_Infil2DOptions:
+        double infil_step
+
+    ctypedef struct SWMM_Infil2DRow:
+        int has_method
+        int method
+        double p[5]
+        int dest
+
+    int swmm_infil2d_get_options(void* engine, SWMM_Infil2DOptions* options)
+    int swmm_infil2d_set_options(void* engine, const SWMM_Infil2DOptions* options)
+    int swmm_infil2d_defaults_count(void* engine, int* count)
+    int swmm_infil2d_get_default(void* engine, int idx, SWMM_Infil2DRow* row)
+    int swmm_infil2d_get_default_tag(void* engine, int idx, char* buf, int buflen)
+    int swmm_infil2d_set_default(void* engine, const char* tag,
+                                  const SWMM_Infil2DRow* row)
+    int swmm_infil2d_remove_default(void* engine, const char* tag)
+    int swmm_infil2d_get_cell(void* engine, int tri, SWMM_Infil2DRow* row,
+                               int* is_override)
+    int swmm_infil2d_set_cell(void* engine, int tri, const SWMM_Infil2DRow* row)
+    int swmm_infil2d_set_cells(void* engine, const int* tris, int n,
+                                const SWMM_Infil2DRow* row)
+    int swmm_infil2d_get_rate_bulk(void* engine, double* f, int n) nogil
+    int swmm_infil2d_get_cum_bulk(void* engine, double* F, int n) nogil
+    int swmm_infil2d_get_total_volume(void* engine, double* volume)
diff --git a/python/openswmm/engine/_2d.pyi b/python/openswmm/engine/_2d.pyi
index db333653e..eea87504f 100644
--- a/python/openswmm/engine/_2d.pyi
+++ b/python/openswmm/engine/_2d.pyi
@@ -1,28 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 2D Surface Routing
 ==================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._2d`.
 
 The :class:`Surface2D` class provides read/write access to the optional 2D
-surface routing module (requires ``OPENSWMM_BUILD_2D=ON`` and SUNDIALS).
+surface routing module (requires ``OPENSWMM_BUILD_2D=ON``).
 """
 
+from collections.abc import Iterator, MutableMapping, Sequence
+from typing import Any, NamedTuple
+
 import numpy as np
 import numpy.typing as npt
 
-from ._enums import SurfaceForcingMode, ForcingPersist, SurfaceBoundaryType
+from ._surface_quality import SurfaceQuality
+from ._groundwater import Groundwater
+from ._solver import Solver
+from ._model import ModelBuilder
+
+from ._enums import (
+    SurfaceForcingMode,
+    ForcingPersist,
+    SurfaceBoundaryType,
+    SurfaceInfilMethod,
+    SurfaceInfilDest,
+)
 
 
 class Surface2D:
     """Read/write interface to the optional 2D surface routing module.
 
     The module solves the depth-averaged shallow-water equations on an
-    unstructured triangular mesh and is integrated in time with the
+    unstructured mixed-cell mesh and is integrated in time with the
     explicit local-inertial finite-volume marcher. Two-way coupling with
     the 1D drainage network is supported per-vertex and per-triangle.
 
@@ -32,20 +62,36 @@ class Surface2D:
         from openswmm.engine._2d import Surface2D
 
         with Solver("model.inp", "model.rpt", "model.out") as s:
-            mesh = Surface2D(s.handle)
+            mesh = s.surface2d
             if mesh.is_active:
                 depths = mesh.get_depths()
 
     @ivar _engine: Internal pointer to the underlying C{SWMM_Engine}
         handle (managed by the Cython extension).
     """
+    def get_rainfall_bulk(self) -> np.ndarray: ...
+    def get_rain_volume_bulk(self) -> np.ndarray: ...
+    def get_coupling_volume_bulk(self) -> np.ndarray: ...
+    def rainfall_weights(self, cell: int) -> tuple[int, np.ndarray, np.ndarray]: ...
+    @staticmethod
+    def output_variables() -> tuple[str, ...]: ...
+    @staticmethod
+    def output_variable_mask(text: str) -> int: ...
+    @staticmethod
+    def output_variable_text(mask: int) -> str: ...
+
+
+    @property
+    def quality(self) -> SurfaceQuality: ...
+
+    @property
+    def groundwater(self) -> Groundwater: ...
 
-    def __init__(self, engine_ptr: int) -> None:
-        """Construct a L{Surface2D} accessor from a raw engine handle.
+    def __init__(self, owner: Solver | ModelBuilder | int) -> None:
+        """Construct an accessor retaining its engine owner. Raw registered
+        pointers are deprecated; use ``solver.surface2d``.
 
-        @param engine_ptr: The raw engine handle (C{SWMM_Engine} cast to
-            an integer via C{solver.handle}).
-        @type engine_ptr: int
+        @param owner: The owning solver or model builder.
         """
         ...
 
@@ -59,7 +105,7 @@ class Surface2D:
 
         @return: Activation flag.
         @rtype: bool
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -73,7 +119,7 @@ class Surface2D:
 
         @return: Vertex count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -83,10 +129,37 @@ class Surface2D:
 
         @return: Triangle count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
+    @property
+    def n_cells(self) -> int:
+        """Number of mesh cells (triangles + quads)."""
+        ...
+
+    @property
+    def n_quads(self) -> int:
+        """Number of quadrilateral cells (0 for an all-triangle mesh)."""
+        ...
+
+    @property
+    def edge_stride(self) -> int:
+        """Edge slots per cell row in the bulk edge arrays (3 all-tri, 4 mixed)."""
+        ...
+
+    def get_cell_vertex_count(self, idx: int) -> int:
+        """Vertices (== edges) of a cell: 3 or 4."""
+        ...
+
+    def get_cell_vertices(self, idx: int) -> tuple[int, ...]:
+        """Vertex indices of any cell (length 3 or 4)."""
+        ...
+
+    def get_cell_neighbours(self, idx: int) -> tuple[int, ...]:
+        """Neighbour cell across each local edge (-1 = boundary), length 3 or 4."""
+        ...
+
     def get_vertex_coords(
         self,
     ) -> tuple[
@@ -100,7 +173,7 @@ class Surface2D:
         @return: Tuple C{(x, y, z)}, each of shape C{(n_vertices,)} with
             dtype C{float64}.
         @rtype: tuple[np.ndarray, np.ndarray, np.ndarray]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -121,7 +194,21 @@ class Surface2D:
         @type idx: int
         @param z: New ground elevation (project vertical units).
         @type z: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
+        """
+        ...
+
+    def set_vertex_z_bulk(self, z: Sequence[float] | npt.NDArray[np.float64]) -> None:
+        """Set EVERY vertex ground elevation in one call.
+
+        Equivalent to calling :meth:`set_vertex_z` per vertex, but rescans the
+        mesh once instead of once per vertex. GIL is released during the C
+        call.
+
+        @param z: One ground elevation per vertex (project vertical units).
+        @type z: Sequence[float] | np.ndarray
+        @raise ValueError: If C{len(z)} does not equal L{n_vertices}.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -145,7 +232,7 @@ class Surface2D:
         @type idx: int
         @return: Tuple of three vertex indices.
         @rtype: tuple[int, int, int]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -156,7 +243,7 @@ class Surface2D:
         @type idx: int
         @return: Triangle area in project units squared.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -167,7 +254,7 @@ class Surface2D:
         @type idx: int
         @return: Tuple C{(cx, cy, cz)} centroid coordinates.
         @rtype: tuple[float, float, float]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -178,7 +265,7 @@ class Surface2D:
         @type idx: int
         @return: Manning's M{n} roughness.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -226,7 +313,7 @@ class Surface2D:
         @return: Tuple of three neighbour triangle indices; C{-1}
             indicates a boundary edge.
         @rtype: tuple[int, int, int]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -240,7 +327,7 @@ class Surface2D:
 
         @return: Coupling count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -250,7 +337,7 @@ class Surface2D:
 
         @return: Coupling count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -261,7 +348,7 @@ class Surface2D:
         @type vertex_idx: int
         @return: Node index, or C{-1} if no coupling exists.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -279,7 +366,7 @@ class Surface2D:
         @type vertex_idx: int
         @return: Discharge coefficient.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -297,7 +384,7 @@ class Surface2D:
         @type vertex_idx: int
         @return: Exchange area in m^2.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -312,7 +399,7 @@ class Surface2D:
         @type tri_idx: int
         @return: Node index, or C{-1} if no coupling exists.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -352,7 +439,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -362,7 +449,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -373,7 +460,7 @@ class Surface2D:
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
             Positive values denote flux into the 2D surface.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -407,7 +494,7 @@ class Surface2D:
         @type idx: int
         @return: Water depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -418,7 +505,7 @@ class Surface2D:
         @type idx: int
         @return: Total head.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -429,7 +516,7 @@ class Surface2D:
         @type idx: int
         @return: Rainfall rate.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -440,7 +527,7 @@ class Surface2D:
         @type idx: int
         @return: Net source term.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -451,7 +538,7 @@ class Surface2D:
         @type idx: int
         @return: Coupling flux value (positive = into 2D surface).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -465,7 +552,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_vertices,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -478,7 +565,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_vertices,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -492,7 +579,7 @@ class Surface2D:
 
         @return: Maximum depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -502,7 +589,7 @@ class Surface2D:
 
         @return: Total volume.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -513,7 +600,7 @@ class Surface2D:
         @return: Exchange flow rate in C{m^3/s} (positive = into 1D
             network).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -525,7 +612,7 @@ class Surface2D:
 
         @return: Step count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -538,7 +625,26 @@ class Surface2D:
 
         @return: Step size.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
+        """
+        ...
+
+    @property
+    def run_stats(self) -> dict[str, Any]:
+        """Cumulative marcher statistics and the backend of this 2D run.
+
+        Keys: C{backend}, C{momentum}, C{lts_tiers}, C{steps},
+        C{face_evals}, C{last_step}, C{active_frac} (min, mean, max) and
+        C{tier_cells} (one entry per populated LTS tier).
+
+        The value type is C{Any} because the mapping is heterogeneous:
+        C{str} for C{backend}, C{str} or C{int} for C{momentum}, C{int}
+        counts, C{float} for C{last_step}, a 3-tuple for C{active_frac} and
+        a list for C{tier_cells}.
+
+        @return: Statistics dictionary.
+        @rtype: dict[str, Any]
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -547,7 +653,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in m.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -556,7 +662,7 @@ class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in m/s.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -566,7 +672,7 @@ class Surface2D:
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in
             C{m^3/s}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -577,7 +683,7 @@ class Surface2D:
         @return: M{(total_in - total_out) / total_in}, the domain mass-balance
             error as a fraction.
         @rtype: float
-        @raise RuntimeError: If the 2D module did not run.
+        @raise EngineError: If the 2D module did not run.
         """
         ...
 
@@ -589,7 +695,7 @@ class Surface2D:
             C{outfall_in}, C{boundary_in}, C{boundary_out}, C{evap_out}
             (all C{m^3}) and C{continuity_error} (fraction).
         @rtype: dict[str, float]
-        @raise RuntimeError: If the 2D module did not run.
+        @raise EngineError: If the 2D module did not run.
         """
         ...
 
@@ -616,7 +722,7 @@ class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
         ...
 
@@ -636,7 +742,7 @@ class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
         ...
 
@@ -663,7 +769,7 @@ class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
         ...
 
@@ -683,7 +789,7 @@ class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
         ...
 
@@ -706,14 +812,14 @@ class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
         ...
 
     def force_clear_all(self) -> None:
         """Clear all 2D forcings.
 
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -727,7 +833,7 @@ class Surface2D:
 
         @return: Threshold depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -737,7 +843,7 @@ class Surface2D:
 
         @param value: New threshold depth (m).
         @type value: float
-        @raise RuntimeError: If the C API rejects the value.
+        @raise EngineError: If the C API rejects the value.
         """
         ...
 
@@ -747,7 +853,7 @@ class Surface2D:
 
         @return: Boundary edge count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -760,7 +866,7 @@ class Surface2D:
         @type edge: int
         @return: Boundary condition type.
         @rtype: L{SurfaceBoundaryType}
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -775,7 +881,7 @@ class Surface2D:
         @type edge: int
         @param bc_type: Boundary condition type.
         @type bc_type: L{SurfaceBoundaryType}
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         ...
 
@@ -788,7 +894,7 @@ class Surface2D:
         @type edge: int
         @return: Boundary head value.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -801,7 +907,7 @@ class Surface2D:
         @type edge: int
         @param head: Boundary head value.
         @type head: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         ...
 
@@ -814,7 +920,7 @@ class Surface2D:
         @type edge: int
         @return: Boundary slope.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -829,7 +935,7 @@ class Surface2D:
         @type edge: int
         @param slope: Boundary slope.
         @type slope: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         ...
 
@@ -842,7 +948,7 @@ class Surface2D:
         @type edge: int
         @return: Cumulative boundary flux through the edge.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -855,7 +961,7 @@ class Surface2D:
         @type edge: int
         @return: Prescribed flow per metre of edge (C{m^3/s/m}).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -868,7 +974,7 @@ class Surface2D:
         @type edge: int
         @param flow: Prescribed flow per metre of edge (C{m^3/s/m}).
         @type flow: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         ...
 
@@ -883,7 +989,20 @@ class Surface2D:
         @type edge: int
         @param name: Timeseries name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
+        """
+        ...
+
+    def get_edge_bc_tseries_name(self, tri_idx: int, edge: int) -> str:
+        """Return the timeseries name driving a SPECIFIED_STAGE edge.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Timeseries name; C{""} when the slot is clear.
+        @rtype: str
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -898,7 +1017,20 @@ class Surface2D:
         @type edge: int
         @param name: Timeseries name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
+        """
+        ...
+
+    def get_edge_bc_flow_tseries_name(self, tri_idx: int, edge: int) -> str:
+        """Return the timeseries name driving a SPECIFIED_FLOW edge.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Timeseries name; C{""} when the slot is clear.
+        @rtype: str
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -913,7 +1045,20 @@ class Surface2D:
         @type edge: int
         @param name: Rating-curve name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
+        """
+        ...
+
+    def get_edge_bc_rating_curve_name(self, tri_idx: int, edge: int) -> str:
+        """Return the rating-curve name driving a RATING_CURVE edge.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Rating-curve name; C{""} when the slot is clear.
+        @rtype: str
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -930,7 +1075,7 @@ class Surface2D:
         @type edge: int
         @return: Conveyance factor (1.0 = unrestricted, 0.0 = wall).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         ...
 
@@ -946,7 +1091,7 @@ class Surface2D:
         @type edge: int
         @param conveyance: New value in C{[0, 1]}.
         @type conveyance: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         ...
 
@@ -961,3 +1106,101 @@ class Surface2D:
     def reset_edge_conveyance(self) -> None:
         """Reset every edge's conveyance factor to 1.0 (unrestricted)."""
         ...
+
+    # ====================================================================
+    # Per-cell infiltration
+    # ====================================================================
+
+    @property
+    def infiltration(self) -> "Infiltration2DView":
+        """``surface2d.infiltration`` — the per-cell infiltration sub-view.
+
+        @rtype: Infiltration2DView
+        """
+        ...
+
+
+class Infil2DRow(NamedTuple):
+    """One infiltration specification.
+
+    C{method} is C{None} for "no infiltration model". C{params} carries up
+    to five POSITIONAL values in B{PROJECT UNITS} (the same numbers a user
+    types into a legacy C{[INFILTRATION]} row). Only
+    C{SurfaceInfilDest.LOST} is routed in this release.
+    """
+
+    method: SurfaceInfilMethod | None
+    params: tuple[float, ...] = (0.0, 0.0, 0.0, 0.0, 0.0)
+    dest: SurfaceInfilDest = SurfaceInfilDest.LOST
+
+
+class Infil2DCell(NamedTuple):
+    """The infiltration specification in force at one cell."""
+
+    row: Infil2DRow
+    is_override: bool
+
+
+class Infil2DDefaults(MutableMapping[str, Infil2DRow]):
+    """``surface2d.infiltration.defaults`` — tag → L{Infil2DRow} mapping.
+
+    Mirrors C{[2D_INFILTRATION_DEFAULTS]}. The key C{"*"} is the mesh-wide
+    fallback.
+    """
+
+    def __init__(self, owner: Solver | ModelBuilder | int) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __getitem__(self, key: str) -> Infil2DRow: ...
+    def __setitem__(self, key: str, value: Infil2DRow | None) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+
+
+class Infiltration2DView:
+    """``surface2d.infiltration`` — per-cell infiltration on the 2D mesh.
+
+    Row parameters are in B{project units}; every readback channel is SI.
+    Writers raise C{RuntimeError} once the solver has been initialized.
+    """
+
+    def __init__(self, owner: Solver | ModelBuilder | int) -> None: ...
+
+    @property
+    def infil_step(self) -> float:
+        """Evaluation cadence in seconds; C{<= 0} means "use C{WET_STEP}"."""
+        ...
+
+    @infil_step.setter
+    def infil_step(self, seconds: float) -> None: ...
+
+    @property
+    def defaults(self) -> Infil2DDefaults:
+        """The C{[2D_INFILTRATION_DEFAULTS]} tag → row mapping."""
+        ...
+
+    def cell(self, tri: int) -> Infil2DCell:
+        """Return C{(row, is_override)} for one triangle."""
+        ...
+
+    def set_cell(self, tri: int, row: Infil2DRow | None) -> None:
+        """Set (C{row}) or clear (C{None}) the per-cell override."""
+        ...
+
+    def set_cells(
+        self, tris: Sequence[int], row: Infil2DRow | None
+    ) -> None:
+        """Assign one row to many triangles — all-or-nothing."""
+        ...
+
+    def rate(self) -> npt.NDArray[np.float64]:
+        """Held per-cell infiltration rate (m/s), one entry per triangle."""
+        ...
+
+    def cumulative(self) -> npt.NDArray[np.float64]:
+        """Cumulative infiltrated depth (m), one entry per triangle."""
+        ...
+
+    @property
+    def total_volume(self) -> float:
+        """Cumulative 2D infiltration loss (m³) — the C{infil_out} row."""
+        ...
diff --git a/python/openswmm/engine/_2d.pyx b/python/openswmm/engine/_2d.pyx
index 82d5c2406..40cb6d245 100644
--- a/python/openswmm/engine/_2d.pyx
+++ b/python/openswmm/engine/_2d.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 2D Surface Routing
 ==================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Cython wrapper for the 2D surface routing C API.
 
@@ -18,43 +34,136 @@ cimport numpy as np
 import numpy as np
 from libc.stdint cimport uintptr_t
 
+from collections import namedtuple
+from collections.abc import MutableMapping
+
 from ._2d cimport *
-from ._enums import SurfaceForcingMode, ForcingPersist, SurfaceBoundaryType
+from ._enums import (SurfaceForcingMode, ForcingPersist, SurfaceBoundaryType,
+                     SurfaceInfilMethod, SurfaceInfilDest)
 
 
-cdef inline void _check(int rc) except *:
-    """Raise L{RuntimeError} if a C API call returns non-zero.
-
-    @param rc: Return code from a C{swmm_2d_*} call.
-    @type rc: int
-    @raise RuntimeError: If C{rc != 0}.
-    """
-    if rc != 0:
-        raise RuntimeError(f"SWMM 2D API error code {rc}")
+from ._common cimport _check
+from ._access import resolve_owner
+from ._exceptions import StaleObjectError
 
 
 cdef class Surface2D:
     """Read/write interface to the optional 2D surface routing module.
 
     The module solves the depth-averaged shallow-water equations on an
-    unstructured triangular mesh and is integrated in time with the
+    unstructured mixed-cell mesh and is integrated in time with the
     explicit local-inertial finite-volume marcher. Two-way coupling with
     the 1D drainage network is supported per-vertex and per-triangle.
 
-    @ivar _engine: Internal pointer to the underlying C{SWMM_Engine}
-        handle (managed by the Cython extension).
+    Views retain their engine owner and raise C{StaleObjectError} after
+    close, destroy, or structural edits. Use C{solver.surface2d}.
     """
 
-    cdef void* _engine
+    cdef object _owner
+    cdef long long _generation
+    cdef object _infiltration
 
-    def __cinit__(self, uintptr_t engine_ptr):
-        """Construct a L{Surface2D} accessor from a raw engine handle.
+    def __cinit__(self, owner):
+        self._owner = resolve_owner(owner)
+        self._generation = self._owner.generation
+        self._infiltration = None
 
-        @param engine_ptr: The raw engine handle (C{SWMM_Engine} cast to
-            C{uintptr_t}).
-        @type engine_ptr: int
-        """
-        self._engine = engine_ptr
+    @property
+    def quality(self):
+        """Surface land-use coverages, initial loadings, curb lengths and buildup."""
+        self._h()
+        from ._surface_quality import SurfaceQuality
+        return SurfaceQuality(self._owner)
+
+    def get_rainfall_bulk(self):
+        """Current rainfall rate per cell, m/s. Returns an owned float64 array."""
+        cdef int n = 0
+        _check(swmm_2d_cell_count(self._h(), &n))
+        cdef double[::1] values = np.zeros(max(n, 1), dtype=np.float64)
+        cdef void* h = self._h()
+        cdef int rc
+        with self._owner._operation(h):
+            with nogil:
+                rc = swmm_2d_get_rainfall_bulk(h, &values[0])
+        _check(rc)
+        return np.asarray(values)[:n]
+
+    def get_rain_volume_bulk(self):
+        """Cumulative rain volume per cell, m³. Returns an owned float64 array."""
+        cdef int n = 0
+        _check(swmm_2d_cell_count(self._h(), &n))
+        cdef double[::1] values = np.zeros(max(n, 1), dtype=np.float64)
+        cdef void* h = self._h()
+        cdef int rc
+        with self._owner._operation(h):
+            with nogil:
+                rc = swmm_2d_get_rain_volume_bulk(h, &values[0])
+        _check(rc)
+        return np.asarray(values)[:n]
+
+    def get_coupling_volume_bulk(self):
+        """Cumulative signed coupling volume, m³; positive from 1D to 2D. Returns an owned float64 array."""
+        cdef int n = 0
+        _check(swmm_2d_cell_count(self._h(), &n))
+        cdef double[::1] values = np.zeros(max(n, 1), dtype=np.float64)
+        cdef void* h = self._h()
+        cdef int rc
+        with self._owner._operation(h):
+            with nogil:
+                rc = swmm_2d_get_coupling_volume_bulk(h, &values[0])
+        _check(rc)
+        return np.asarray(values)[:n]
+
+    def rainfall_weights(self, int cell):
+        """Return (method, gage indices, weights) as owned snapshots.
+
+        Method: 0 natural neighbour, 1 IDW, 2 nearest, -1 not applicable.
+        """
+        cdef int method = -1
+        cdef int count = 0
+        cdef void* h = self._h()
+        _check(swmm_2d_get_rainfall_weights(h, cell, &method, NULL, NULL, 0, &count))
+        cdef int[::1] indices = np.zeros(max(count, 1), dtype=np.intc)
+        cdef double[::1] weights = np.zeros(max(count, 1), dtype=np.float64)
+        if count:
+            _check(swmm_2d_get_rainfall_weights(h, cell, &method, &indices[0], &weights[0], count, &count))
+        return method, np.asarray(indices)[:count], np.asarray(weights)[:count]
+
+    @staticmethod
+    def output_variables():
+        """Supported 2D output variable names in native order."""
+        return tuple(swmm_2d_output_variable_name(i).decode('utf-8')
+                     for i in range(swmm_2d_output_variable_count()))
+
+    @staticmethod
+    def output_variable_mask(str text):
+        """Parse DEFAULT/MINIMAL/ALL or a native variable list into a mask."""
+        cdef bytes encoded = text.encode('utf-8')
+        cdef unsigned mask = swmm_2d_output_variable_mask(encoded)
+        if not mask:
+            raise ValueError("Invalid or empty 2D output variable selection")
+        return mask
+
+    @staticmethod
+    def output_variable_text(unsigned mask):
+        """Return canonical variable text for a mask."""
+        cdef const char* text = swmm_2d_output_variable_text(mask)
+        return text.decode('utf-8') if text != NULL else ''
+
+    @property
+    def groundwater(self):
+        """Two-zone aquifer authoring and runtime snapshots."""
+        self._h()
+        from ._groundwater import Groundwater
+        return Groundwater(self._owner)
+
+    def _is_current(self):
+        return self._generation == self._owner.generation
+
+    cdef void* _h(self) except NULL:
+        if not self._is_current():
+            raise StaleObjectError("2D view was invalidated; reacquire solver.surface2d")
+        return self._owner.handle
 
     # ====================================================================
     # Mesh definition - status
@@ -66,10 +175,10 @@ cdef class Surface2D:
 
         @return: Activation flag.
         @rtype: bool
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int active = 0
-        _check(swmm_2d_is_active(self._engine, &active))
+        _check(swmm_2d_is_active(self._h(), &active))
         return bool(active)
 
     # ====================================================================
@@ -87,9 +196,9 @@ cdef class Surface2D:
         so the changes take effect and are written on save. No-op when the
         engine is already initialized/drained.
 
-        @raise RuntimeError: If no 2D mesh is present.
+        @raise EngineError: If no 2D mesh is present.
         """
-        _check(swmm_2d_prepare_for_edit(self._engine))
+        _check(swmm_2d_prepare_for_edit(self._h()))
 
     @property
     def n_vertices(self) -> int:
@@ -97,43 +206,88 @@ cdef class Surface2D:
 
         @return: Vertex count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_vertex_count(self._engine, &count))
+        _check(swmm_2d_vertex_count(self._h(), &count))
         return count
 
     @property
     def n_triangles(self) -> int:
-        """Number of mesh triangles.
+        """Number of mesh cells (triangles + quads; historical name).
 
-        @return: Triangle count.
+        @return: Cell count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_triangle_count(self._engine, &count))
+        _check(swmm_2d_triangle_count(self._h(), &count))
+        return count
+
+    @property
+    def n_cells(self) -> int:
+        """Number of mesh cells (triangles + quads)."""
+        cdef int count = 0
+        _check(swmm_2d_cell_count(self._h(), &count))
         return count
 
+    @property
+    def n_quads(self) -> int:
+        """Number of quadrilateral cells (0 for an all-triangle mesh)."""
+        cdef int count = 0
+        _check(swmm_2d_quad_count(self._h(), &count))
+        return count
+
+    @property
+    def edge_stride(self) -> int:
+        """Edge slots per cell row in the bulk edge arrays: 3 for an
+        all-triangle mesh (historical C{[tri*3 + localEdge]} layout), 4 once
+        the mesh holds any quad (C{[cell*4 + localEdge]})."""
+        cdef int stride = 3
+        _check(swmm_2d_edge_stride(self._h(), &stride))
+        return stride
+
+    def get_cell_vertex_count(self, int idx) -> int:
+        """Vertices (== edges) of a cell: 3 or 4."""
+        cdef int nv = 0
+        _check(swmm_2d_cell_vertex_count(self._h(), idx, &nv))
+        return nv
+
+    def get_cell_vertices(self, int idx):
+        """Vertex indices of any cell as a tuple of length 3 or 4.
+        Local edge k has endpoints v[(k+1)%nv], v[(k+2)%nv]."""
+        cdef int v[4]
+        cdef int nv = 0
+        _check(swmm_2d_cell_get_vertices(self._h(), idx, v, &nv))
+        return tuple(v[k] for k in range(nv))
+
+    def get_cell_neighbours(self, int idx):
+        """Neighbour cell across each local edge (-1 = boundary), length 3 or 4."""
+        cdef int n[4]
+        cdef int nv = 0
+        _check(swmm_2d_cell_get_neighbours(self._h(), idx, n, &nv))
+        return tuple(n[k] for k in range(nv))
+
     def get_vertex_coords(self):
         """Return (x, y, z) NumPy arrays for all vertices.
 
         @return: Tuple C{(x, y, z)}, each of shape C{(n_vertices,)} with
             dtype C{float64}.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_vertices
         cdef np.ndarray[double, ndim=1] x = np.empty(n, dtype=np.float64)
         cdef np.ndarray[double, ndim=1] y = np.empty(n, dtype=np.float64)
         cdef np.ndarray[double, ndim=1] z = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* px = x.data
         cdef double* py = y.data
         cdef double* pz = z.data
         cdef int err
-        with nogil:
-            err = swmm_2d_vertex_get_xyz_bulk(eng, px, py, pz)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_vertex_get_xyz_bulk(eng, px, py, pz)
         _check(err)
         return x, y, z
 
@@ -150,9 +304,42 @@ cdef class Surface2D:
         @type idx: int
         @param z: New ground elevation (project vertical units).
         @type z: float
-        @raise RuntimeError: If the C API call fails.
-        """
-        _check(swmm_2d_set_vertex_z(self._engine, idx, z))
+        @raise EngineError: If the C API call fails.
+        """
+        _check(swmm_2d_set_vertex_z(self._h(), idx, z))
+
+    def set_vertex_z_bulk(self, z) -> None:
+        """Set EVERY vertex ground elevation in one call.
+
+        Equivalent to calling :meth:`set_vertex_z` for each vertex in turn —
+        the dependent geometry (centroid Z, per-edge midpoint Z) ends up
+        bitwise identical — but the whole mesh is rescanned once instead of
+        once per vertex, so this is C{O(n_vertices + n_triangles)} rather than
+        C{O(n_vertices * n_triangles)}. Editors rewriting a whole mesh should
+        prefer it. XY-derived fields are unaffected, and solver state (head,
+        depth) is not rewritten when the engine is running.
+
+        @param z: Sequence or NumPy array of C{n_vertices} ground elevations
+            (project vertical units), indexed by vertex.
+        @type z: collections.abc.Sequence or np.ndarray
+        @raise ValueError: If C{len(z)} does not equal L{n_vertices}.
+        @raise EngineError: If the C API call fails.
+        """
+        cdef np.ndarray[double, ndim=1] arr = np.ascontiguousarray(
+            z, dtype=np.float64).reshape(-1)
+        cdef int n = arr.shape[0]
+        cdef int expected = self.n_vertices
+        if n != expected:
+            raise ValueError(
+                f"set_vertex_z_bulk expects one Z per vertex: got {n}, "
+                f"mesh has {expected}")
+        cdef void* eng = self._h()
+        cdef const double* p = arr.data
+        cdef int err
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_set_vertex_z_bulk(eng, p, n)
+        _check(err)
 
     def get_vertex_xyz(self, int idx):
         """Return the C{(x, y, z)} coordinates of one mesh vertex.
@@ -164,10 +351,10 @@ cdef class Surface2D:
         @type idx: int
         @return: C{(x, y, z)}.
         @rtype: tuple[float, float, float]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double x = 0.0, y = 0.0, z = 0.0
-        _check(swmm_2d_vertex_get_xyz(self._engine, idx, &x, &y, &z))
+        _check(swmm_2d_vertex_get_xyz(self._h(), idx, &x, &y, &z))
         return (x, y, z)
 
     def get_vertex_head(self, int idx) -> float:
@@ -180,10 +367,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Head at the vertex.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double head = 0.0
-        _check(swmm_2d_vertex_get_head(self._engine, idx, &head))
+        _check(swmm_2d_vertex_get_head(self._h(), idx, &head))
         return head
 
     def get_vertex_tag(self, int idx) -> str:
@@ -196,10 +383,10 @@ cdef class Surface2D:
         @type idx: int
         @return: The tag string; empty when the vertex has no tag.
         @rtype: str
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef char buf[256]
-        _check(swmm_2d_get_vertex_tag(self._engine, idx, buf, 256))
+        _check(swmm_2d_get_vertex_tag(self._h(), idx, buf, 256))
         return buf.decode('utf-8')
 
     def set_vertex_tag(self, int idx, str tag) -> None:
@@ -209,10 +396,10 @@ cdef class Surface2D:
         @type idx: int
         @param tag: New tag; an empty string clears it.
         @type tag: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         cdef bytes b = (tag or "").encode('utf-8')
-        _check(swmm_2d_set_vertex_tag(self._engine, idx, b))
+        _check(swmm_2d_set_vertex_tag(self._h(), idx, b))
 
     def get_triangle_vertices(self, int idx):
         """Return the (v0, v1, v2) vertex indices for a triangle.
@@ -221,10 +408,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Tuple of three vertex indices.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int v0, v1, v2
-        _check(swmm_2d_triangle_get_vertices(self._engine, idx, &v0, &v1, &v2))
+        _check(swmm_2d_triangle_get_vertices(self._h(), idx, &v0, &v1, &v2))
         return v0, v1, v2
 
     def get_triangle_area(self, int idx) -> float:
@@ -234,10 +421,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Triangle area in project units squared.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double area
-        _check(swmm_2d_triangle_get_area(self._engine, idx, &area))
+        _check(swmm_2d_triangle_get_area(self._h(), idx, &area))
         return area
 
     def get_triangle_centroid(self, int idx):
@@ -247,10 +434,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Tuple C{(cx, cy, cz)} centroid coordinates.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double cx, cy, cz
-        _check(swmm_2d_triangle_get_centroid(self._engine, idx, &cx, &cy, &cz))
+        _check(swmm_2d_triangle_get_centroid(self._h(), idx, &cx, &cy, &cz))
         return cx, cy, cz
 
     def get_triangle_mannings(self, int idx) -> float:
@@ -260,10 +447,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Manning's M{n} roughness.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double n
-        _check(swmm_2d_triangle_get_mannings(self._engine, idx, &n))
+        _check(swmm_2d_triangle_get_mannings(self._h(), idx, &n))
         return n
 
     def set_triangle_mannings(self, int idx, double n) -> None:
@@ -275,9 +462,9 @@ cdef class Surface2D:
         @type idx: int
         @param n: New Manning's roughness; must be strictly positive.
         @type n: float
-        @raise RuntimeError: If the C API rejects the value (e.g. C{n <= 0}).
+        @raise EngineError: If the C API rejects the value (e.g. C{n <= 0}).
         """
-        _check(swmm_2d_set_triangle_mannings(self._engine, idx, n))
+        _check(swmm_2d_set_triangle_mannings(self._h(), idx, n))
 
     def get_triangle_init_depth(self, int idx) -> float:
         """Return the initial water depth of a triangle.
@@ -290,10 +477,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Initial depth; C{0.0} means the triangle starts dry.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double d
-        _check(swmm_2d_triangle_get_init_depth(self._engine, idx, &d))
+        _check(swmm_2d_triangle_get_init_depth(self._h(), idx, &d))
         return d
 
     def set_triangle_init_depth(self, int idx, double depth) -> None:
@@ -306,9 +493,9 @@ cdef class Surface2D:
         @type idx: int
         @param depth: Initial depth in mesh length units; must be M{>= 0}.
         @type depth: float
-        @raise RuntimeError: If the C API rejects the value (e.g. negative).
+        @raise EngineError: If the C API rejects the value (e.g. negative).
         """
-        _check(swmm_2d_set_triangle_init_depth(self._engine, idx, depth))
+        _check(swmm_2d_set_triangle_init_depth(self._h(), idx, depth))
 
     def get_triangle_init_velocity(self, int idx):
         """Return the C{(u, v)} initial velocity of a triangle.
@@ -317,10 +504,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Tuple C{(u, v)} in m/s; C{(0.0, 0.0)} when at rest.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double u, v
-        _check(swmm_2d_triangle_get_init_velocity(self._engine, idx, &u, &v))
+        _check(swmm_2d_triangle_get_init_velocity(self._h(), idx, &u, &v))
         return u, v
 
     def set_triangle_init_velocity(self, int idx, double u, double v) -> None:
@@ -337,9 +524,9 @@ cdef class Surface2D:
         @type u: float
         @param v: Y-component of velocity in m/s; must be finite.
         @type v: float
-        @raise RuntimeError: If the C API rejects a non-finite value.
+        @raise EngineError: If the C API rejects a non-finite value.
         """
-        _check(swmm_2d_set_triangle_init_velocity(self._engine, idx, u, v))
+        _check(swmm_2d_set_triangle_init_velocity(self._h(), idx, u, v))
 
     def get_triangle_tag(self, int idx) -> str:
         """Return the descriptive tag of a triangle (C{[2D_TRIANGLES]} TAG).
@@ -348,10 +535,10 @@ cdef class Surface2D:
         @type idx: int
         @return: The tag string; empty when the triangle has no tag.
         @rtype: str
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef char buf[256]
-        _check(swmm_2d_get_triangle_tag(self._engine, idx, buf, 256))
+        _check(swmm_2d_get_triangle_tag(self._h(), idx, buf, 256))
         return buf.decode('utf-8')
 
     def set_triangle_tag(self, int idx, str tag) -> None:
@@ -361,10 +548,10 @@ cdef class Surface2D:
         @type idx: int
         @param tag: New tag; an empty string clears it.
         @type tag: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         cdef bytes b = (tag or "").encode('utf-8')
-        _check(swmm_2d_set_triangle_tag(self._engine, idx, b))
+        _check(swmm_2d_set_triangle_tag(self._h(), idx, b))
 
     def get_triangle_neighbours(self, int idx):
         """Return the (n0, n1, n2) neighbour triangle indices.
@@ -374,10 +561,10 @@ cdef class Surface2D:
         @return: Tuple of three neighbour triangle indices; C{-1}
             indicates a boundary edge.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n0, n1, n2
-        _check(swmm_2d_triangle_get_neighbours(self._engine, idx, &n0, &n1, &n2))
+        _check(swmm_2d_triangle_get_neighbours(self._h(), idx, &n0, &n1, &n2))
         return n0, n1, n2
 
     # ====================================================================
@@ -390,10 +577,10 @@ cdef class Surface2D:
 
         @return: Coupling count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_vertex_coupling_count(self._engine, &count))
+        _check(swmm_2d_vertex_coupling_count(self._h(), &count))
         return count
 
     @property
@@ -402,10 +589,10 @@ cdef class Surface2D:
 
         @return: Coupling count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_triangle_coupling_count(self._engine, &count))
+        _check(swmm_2d_triangle_coupling_count(self._h(), &count))
         return count
 
     def get_vertex_coupled_node(self, int vertex_idx) -> int:
@@ -415,10 +602,10 @@ cdef class Surface2D:
         @type vertex_idx: int
         @return: Node index, or C{-1} if no coupling exists.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int node_idx
-        _check(swmm_2d_vertex_get_coupled_node(self._engine, vertex_idx,
+        _check(swmm_2d_vertex_get_coupled_node(self._h(), vertex_idx,
                                                  &node_idx))
         return node_idx
 
@@ -433,11 +620,11 @@ cdef class Surface2D:
         @type vertex_idx: int
         @param node_name: Target 1D node id, or C{""} to clear.
         @type node_name: str
-        @raise RuntimeError: If the C API rejects the assignment (e.g. the
+        @raise EngineError: If the C API rejects the assignment (e.g. the
             node name does not resolve).
         """
         cdef bytes b = (node_name or "").encode('utf-8')
-        _check(swmm_2d_set_vertex_coupled_node(self._engine, vertex_idx, b))
+        _check(swmm_2d_set_vertex_coupled_node(self._h(), vertex_idx, b))
 
     def get_vertex_coupling_cd(self, int vertex_idx) -> float:
         """Return the coupling discharge coefficient of a vertex.
@@ -449,10 +636,10 @@ cdef class Surface2D:
         @type vertex_idx: int
         @return: Discharge coefficient.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double cd = 0.0
-        _check(swmm_2d_get_vertex_coupling_cd(self._engine, vertex_idx, &cd))
+        _check(swmm_2d_get_vertex_coupling_cd(self._h(), vertex_idx, &cd))
         return cd
 
     def set_vertex_coupling_cd(self, int vertex_idx, double cd) -> None:
@@ -465,10 +652,10 @@ cdef class Surface2D:
         @type vertex_idx: int
         @param cd: Discharge coefficient; must be > 0.
         @type cd: float
-        @raise RuntimeError: If the C API rejects the value (e.g. a
+        @raise EngineError: If the C API rejects the value (e.g. a
             non-positive coefficient).
         """
-        _check(swmm_2d_set_vertex_coupling_cd(self._engine, vertex_idx, cd))
+        _check(swmm_2d_set_vertex_coupling_cd(self._h(), vertex_idx, cd))
 
     def get_vertex_coupling_area(self, int vertex_idx) -> float:
         """Return the coupling exchange area of a vertex.
@@ -480,10 +667,10 @@ cdef class Surface2D:
         @type vertex_idx: int
         @return: Exchange area in m^2.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double area = 0.0
-        _check(swmm_2d_get_vertex_coupling_area(self._engine, vertex_idx,
+        _check(swmm_2d_get_vertex_coupling_area(self._h(), vertex_idx,
                                                   &area))
         return area
 
@@ -497,10 +684,10 @@ cdef class Surface2D:
         @type vertex_idx: int
         @param area: Exchange area in m^2; must be > 0.
         @type area: float
-        @raise RuntimeError: If the C API rejects the value (e.g. a
+        @raise EngineError: If the C API rejects the value (e.g. a
             non-positive area).
         """
-        _check(swmm_2d_set_vertex_coupling_area(self._engine, vertex_idx,
+        _check(swmm_2d_set_vertex_coupling_area(self._h(), vertex_idx,
                                                   area))
 
     def get_triangle_coupled_node(self, int tri_idx) -> int:
@@ -510,10 +697,10 @@ cdef class Surface2D:
         @type tri_idx: int
         @return: Node index, or C{-1} if no coupling exists.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int node_idx
-        _check(swmm_2d_triangle_get_coupled_node(self._engine, tri_idx,
+        _check(swmm_2d_triangle_get_coupled_node(self._h(), tri_idx,
                                                     &node_idx))
         return node_idx
 
@@ -536,11 +723,11 @@ cdef class Surface2D:
         @type cd: float
         @param area: Effective exchange area in m^2; must be > 0.
         @type area: float
-        @raise RuntimeError: If the C API rejects the row (bad triangle
+        @raise EngineError: If the C API rejects the row (bad triangle
             index, empty name, or non-positive cd/area).
         """
         cdef bytes b = (node_name or "").encode('utf-8')
-        _check(swmm_2d_add_triangle_coupling(self._engine, tri_idx, b,
+        _check(swmm_2d_add_triangle_coupling(self._h(), tri_idx, b,
                                               cd, area))
 
     def clear_triangle_couplings(self) -> None:
@@ -549,9 +736,9 @@ cdef class Surface2D:
         Also clears the legacy per-triangle mirror (coupled node, CD and
         AREA back to defaults). Vertex couplings are untouched.
 
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
-        _check(swmm_2d_clear_triangle_couplings(self._engine))
+        _check(swmm_2d_clear_triangle_couplings(self._h()))
 
     @property
     def triangle_coupling_rows(self) -> int:
@@ -562,10 +749,10 @@ cdef class Surface2D:
 
         @return: Row count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_triangle_coupling_rows(self._engine, &count))
+        _check(swmm_2d_triangle_coupling_rows(self._h(), &count))
         return count
 
     def get_triangle_coupling_row(self, int row_idx):
@@ -576,13 +763,13 @@ cdef class Surface2D:
         @return: Tuple C{(tri_idx, node_idx, cd, area)} where C{node_idx}
             is C{-1} if the node name is unresolved.
         @rtype: tuple[int, int, float, float]
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int tri_idx = 0
         cdef int node_idx = 0
         cdef double cd = 0.0
         cdef double area = 0.0
-        _check(swmm_2d_get_triangle_coupling_row(self._engine, row_idx,
+        _check(swmm_2d_get_triangle_coupling_row(self._h(), row_idx,
                                                   &tri_idx, &node_idx,
                                                   &cd, &area))
         return (tri_idx, node_idx, cd, area)
@@ -596,15 +783,16 @@ cdef class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_get_depths_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_get_depths_bulk(eng, p)
         _check(err)
         return arr
 
@@ -614,15 +802,16 @@ cdef class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_get_heads_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_get_heads_bulk(eng, p)
         _check(err)
         return arr
 
@@ -633,15 +822,16 @@ cdef class Surface2D:
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
             Positive values denote flux into the 2D surface.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_get_coupling_fluxes_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_get_coupling_fluxes_bulk(eng, p)
         _check(err)
         return arr
 
@@ -649,21 +839,22 @@ cdef class Surface2D:
         """Return normal edge fluxes for all triangle edges as a NumPy array.
         The GIL is released during the C call.
 
-        The array is indexed as C{[tri*3 + localEdge]} where C{localEdge}
-        is the edge opposite vertex C{localEdge} (0, 1, or 2). Positive
+        The array is indexed as C{[cell*edge_stride + localEdge]} (stride 3 for
+        an all-triangle mesh, 4 when quads exist; see L{edge_stride}). Positive
         flux flows outward through the edge's outward normal.
 
-        @return: Array of shape C{(n_triangles*3,)} with dtype C{float64}.
+        @return: Array of shape C{(n_triangles*edge_stride,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
-        cdef int n = self.n_triangles * 3
+        cdef int n = self.n_triangles * self.edge_stride
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_get_edge_flux_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_get_edge_flux_bulk(eng, p)
         _check(err)
         return arr
 
@@ -678,19 +869,20 @@ cdef class Surface2D:
         @return: Tuple C{(length, nx, ny)}, each of shape
             C{(n_triangles*3,)} with dtype C{float64}.
         @rtype: tuple
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
-        cdef int n = self.n_triangles * 3
+        cdef int n = self.n_triangles * self.edge_stride
         cdef np.ndarray[double, ndim=1] length = np.empty(n, dtype=np.float64)
         cdef np.ndarray[double, ndim=1] nx = np.empty(n, dtype=np.float64)
         cdef np.ndarray[double, ndim=1] ny = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* pL = length.data
         cdef double* pX = nx.data
         cdef double* pY = ny.data
         cdef int err
-        with nogil:
-            err = swmm_2d_edge_get_geometry_bulk(eng, pL, pX, pY)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_edge_get_geometry_bulk(eng, pL, pX, pY)
         _check(err)
         return length, nx, ny
 
@@ -705,10 +897,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Water depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_depth(self._engine, idx, &val))
+        _check(swmm_2d_get_depth(self._h(), idx, &val))
         return val
 
     def get_head(self, int idx) -> float:
@@ -718,10 +910,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Total head.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_head(self._engine, idx, &val))
+        _check(swmm_2d_get_head(self._h(), idx, &val))
         return val
 
     def get_rainfall(self, int idx) -> float:
@@ -731,10 +923,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Rainfall rate.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_rainfall(self._engine, idx, &val))
+        _check(swmm_2d_get_rainfall(self._h(), idx, &val))
         return val
 
     def get_net_source(self, int idx) -> float:
@@ -744,10 +936,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Net source term.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_net_source(self._engine, idx, &val))
+        _check(swmm_2d_get_net_source(self._h(), idx, &val))
         return val
 
     def get_coupling_flux(self, int idx) -> float:
@@ -757,10 +949,10 @@ cdef class Surface2D:
         @type idx: int
         @return: Coupling flux value (positive = into 2D surface).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_coupling_flux(self._engine, idx, &val))
+        _check(swmm_2d_get_coupling_flux(self._h(), idx, &val))
         return val
 
     # ====================================================================
@@ -772,15 +964,16 @@ cdef class Surface2D:
 
         @return: Array of shape C{(n_vertices,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_vertices
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_vertex_get_heads_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_vertex_get_heads_bulk(eng, p)
         _check(err)
         return arr
 
@@ -797,15 +990,16 @@ cdef class Surface2D:
 
         @return: Array of shape C{(n_vertices,)} with dtype C{float64}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_vertices
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        cdef void* eng = self._engine
+        cdef void* eng = self._h()
         cdef double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_2d_vertex_get_render_depths_bulk(eng, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_vertex_get_render_depths_bulk(eng, p)
         _check(err)
         return arr
 
@@ -819,10 +1013,10 @@ cdef class Surface2D:
 
         @return: Maximum depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_max_depth(self._engine, &val))
+        _check(swmm_2d_get_max_depth(self._h(), &val))
         return val
 
     @property
@@ -831,10 +1025,10 @@ cdef class Surface2D:
 
         @return: Total volume.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_total_volume(self._engine, &val))
+        _check(swmm_2d_get_total_volume(self._h(), &val))
         return val
 
     @property
@@ -844,10 +1038,10 @@ cdef class Surface2D:
         @return: Exchange flow rate in C{m^3/s} (positive = into 1D
             network).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_total_exchange_flow(self._engine, &val))
+        _check(swmm_2d_get_total_exchange_flow(self._h(), &val))
         return val
 
     @property
@@ -858,10 +1052,10 @@ cdef class Surface2D:
 
         @return: Step count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef long val
-        _check(swmm_2d_get_solver_steps(self._engine, &val))
+        _check(swmm_2d_get_solver_steps(self._h(), &val))
         return val
 
     @property
@@ -873,22 +1067,52 @@ cdef class Surface2D:
 
         @return: Step size.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_solver_last_step(self._engine, &val))
+        _check(swmm_2d_get_solver_last_step(self._h(), &val))
         return val
 
+    @property
+    def run_stats(self) -> dict:
+        """Cumulative marcher statistics and the backend of this 2D run.
+
+        Readable during the run (after C{start}). Keys: C{backend} (solver
+        label chosen at initialize), C{momentum} (C{LOCAL_INERTIAL} /
+        C{FULL_SWE} / C{DIFFUSIVE_WAVE}), C{lts_tiers} (configured),
+        C{steps}, C{face_evals}, C{last_step}, C{active_frac}
+        (min, mean, max; -1 = not populated) and C{tier_cells} (cumulative
+        rebuild-sampled cells per LTS tier, C{n_tiers} entries).
+
+        @return: Statistics dictionary.
+        @rtype: dict
+        @raise EngineError: If the C API call fails.
+        """
+        cdef SWMM_2DRunStats st
+        _check(swmm_2d_get_run_stats(self._h(), &st))
+        names = ("LOCAL_INERTIAL", "FULL_SWE", "DIFFUSIVE_WAVE")
+        return {
+            "backend": (st.backend).decode("utf-8", "replace"),
+            "momentum": names[st.momentum] if 0 <= st.momentum < 3 else st.momentum,
+            "lts_tiers": st.lts_tiers,
+            "steps": st.steps,
+            "face_evals": st.face_evals,
+            "last_step": st.last_step,
+            "active_frac": (st.active_frac_min, st.active_frac_mean,
+                            st.active_frac_max),
+            "tier_cells": [st.tier_cells[k] for k in range(st.n_tiers)],
+        }
+
     def get_stat_max_depths(self):
         """Return cumulative maximum-depth envelope for all triangles.
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in m.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        _check(swmm_2d_get_stat_max_depths(self._engine, &arr[0]))
+        _check(swmm_2d_get_stat_max_depths(self._h(), &arr[0]))
         return arr
 
     def get_stat_max_velocities(self):
@@ -896,11 +1120,11 @@ cdef class Surface2D:
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in m/s.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        _check(swmm_2d_get_stat_max_velocities(self._engine, &arr[0]))
+        _check(swmm_2d_get_stat_max_velocities(self._h(), &arr[0]))
         return arr
 
     def get_stat_max_continuity_err(self):
@@ -909,11 +1133,11 @@ cdef class Surface2D:
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}, in
             C{m^3/s}.
         @rtype: np.ndarray
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int n = self.n_triangles
         cdef np.ndarray[double, ndim=1] arr = np.empty(n, dtype=np.float64)
-        _check(swmm_2d_get_stat_max_continuity_err(self._engine, &arr[0]))
+        _check(swmm_2d_get_stat_max_continuity_err(self._h(), &arr[0]))
         return arr
 
     @property
@@ -923,10 +1147,10 @@ cdef class Surface2D:
         @return: M{(total_in - total_out) / total_in}, the domain mass-balance
             error as a fraction.
         @rtype: float
-        @raise RuntimeError: If the 2D module did not run.
+        @raise EngineError: If the 2D module did not run.
         """
         cdef double val
-        _check(swmm_2d_get_continuity_error(self._engine, &val))
+        _check(swmm_2d_get_continuity_error(self._h(), &val))
         return val
 
     def get_mass_balance(self):
@@ -937,7 +1161,7 @@ cdef class Surface2D:
             C{outfall_in}, C{outfall_out}, C{boundary_in}, C{boundary_out},
             C{evap_out} (all C{m^3}) and C{continuity_error} (fraction).
         @rtype: dict[str, float]
-        @raise RuntimeError: If the 2D module did not run.
+        @raise EngineError: If the 2D module did not run.
         """
         cdef double init_storage = 0.0
         cdef double final_storage = 0.0
@@ -950,13 +1174,13 @@ cdef class Surface2D:
         cdef double boundary_out = 0.0
         cdef double evap_out = 0.0
         cdef double err = 0.0
-        _check(swmm_2d_get_mass_balance(self._engine,
+        _check(swmm_2d_get_mass_balance(self._h(),
                                         &init_storage, &final_storage,
                                         &rainfall_in, &coupling_in,
                                         &coupling_out, &outfall_in,
                                         &outfall_out, &boundary_in,
                                         &boundary_out, &evap_out))
-        _check(swmm_2d_get_continuity_error(self._engine, &err))
+        _check(swmm_2d_get_continuity_error(self._h(), &err))
         return {
             "init_storage": init_storage,
             "final_storage": final_storage,
@@ -990,9 +1214,9 @@ cdef class Surface2D:
         @param persist: C{PERSIST} holds the forcing until cleared; C{RESET}
             applies it for a single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
-        _check(swmm_2d_force_rainfall(self._engine, idx, value,
+        _check(swmm_2d_force_rainfall(self._h(), idx, value,
                                       int(mode), int(persist)))
 
     def force_rainfall_uniform(self, double value, *,
@@ -1007,9 +1231,9 @@ cdef class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
-        _check(swmm_2d_force_rainfall_uniform(self._engine, value,
+        _check(swmm_2d_force_rainfall_uniform(self._h(), value,
                                               int(mode), int(persist)))
 
     def force_evap(self, int idx, double value, *,
@@ -1031,9 +1255,9 @@ cdef class Surface2D:
         @param persist: C{PERSIST} holds the forcing until cleared; C{RESET}
             applies it for a single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
-        _check(swmm_2d_force_evap(self._engine, idx, value,
+        _check(swmm_2d_force_evap(self._h(), idx, value,
                                   int(mode), int(persist)))
 
     def force_evap_uniform(self, double value, *,
@@ -1048,9 +1272,9 @@ cdef class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
-        _check(swmm_2d_force_evap_uniform(self._engine, value,
+        _check(swmm_2d_force_evap_uniform(self._h(), value,
                                           int(mode), int(persist)))
 
     def force_coupling_flux(self, int idx, double value, *,
@@ -1067,17 +1291,17 @@ cdef class Surface2D:
         @param persist: C{PERSIST} to hold until cleared; C{RESET} for a
             single step.
         @type persist: L{ForcingPersist}
-        @raise RuntimeError: If the C API rejects the forcing.
+        @raise EngineError: If the C API rejects the forcing.
         """
-        _check(swmm_2d_force_coupling_flux(self._engine, idx, value,
+        _check(swmm_2d_force_coupling_flux(self._h(), idx, value,
                                            int(mode), int(persist)))
 
     def force_clear_all(self):
         """Clear all 2D forcings.
 
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
-        _check(swmm_2d_force_clear_all(self._engine))
+        _check(swmm_2d_force_clear_all(self._h()))
 
     # ====================================================================
     # Mesh definition - solver options
@@ -1089,10 +1313,10 @@ cdef class Surface2D:
 
         @return: Threshold depth.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double val
-        _check(swmm_2d_get_dry_depth(self._engine, &val))
+        _check(swmm_2d_get_dry_depth(self._h(), &val))
         return val
 
     @dry_depth.setter
@@ -1101,9 +1325,9 @@ cdef class Surface2D:
 
         @param value: New threshold depth (m).
         @type value: float
-        @raise RuntimeError: If the C API rejects the value.
+        @raise EngineError: If the C API rejects the value.
         """
-        _check(swmm_2d_set_dry_depth(self._engine, value))
+        _check(swmm_2d_set_dry_depth(self._h(), value))
 
     # ====================================================================
     # Boundary conditions - boundary edges
@@ -1115,10 +1339,10 @@ cdef class Surface2D:
 
         @return: Boundary edge count.
         @rtype: int
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int count = 0
-        _check(swmm_2d_boundary_edge_count(self._engine, &count))
+        _check(swmm_2d_boundary_edge_count(self._h(), &count))
         return count
 
     def get_edge_bc_type(self, int tri_idx, int edge):
@@ -1130,10 +1354,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Boundary condition type.
         @rtype: L{SurfaceBoundaryType}
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef int bc_type = 0
-        _check(swmm_2d_get_edge_bc_type(self._engine, tri_idx, edge, &bc_type))
+        _check(swmm_2d_get_edge_bc_type(self._h(), tri_idx, edge, &bc_type))
         return SurfaceBoundaryType(bc_type)
 
     def set_edge_bc_type(self, int tri_idx, int edge, bc_type):
@@ -1145,9 +1369,9 @@ cdef class Surface2D:
         @type edge: int
         @param bc_type: Boundary condition type.
         @type bc_type: L{SurfaceBoundaryType}
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
-        _check(swmm_2d_set_edge_bc_type(self._engine, tri_idx, edge,
+        _check(swmm_2d_set_edge_bc_type(self._h(), tri_idx, edge,
                                         int(bc_type)))
 
     def get_edge_bc_head(self, int tri_idx, int edge) -> float:
@@ -1159,10 +1383,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Boundary head value.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double head = 0.0
-        _check(swmm_2d_get_edge_bc_head(self._engine, tri_idx, edge, &head))
+        _check(swmm_2d_get_edge_bc_head(self._h(), tri_idx, edge, &head))
         return head
 
     def set_edge_bc_head(self, int tri_idx, int edge, double head):
@@ -1174,9 +1398,9 @@ cdef class Surface2D:
         @type edge: int
         @param head: Boundary head value.
         @type head: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
-        _check(swmm_2d_set_edge_bc_head(self._engine, tri_idx, edge, head))
+        _check(swmm_2d_set_edge_bc_head(self._h(), tri_idx, edge, head))
 
     def get_edge_bc_slope(self, int tri_idx, int edge) -> float:
         """Return the boundary slope for a triangle edge.
@@ -1187,10 +1411,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Boundary slope.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double slope = 0.0
-        _check(swmm_2d_get_edge_bc_slope(self._engine, tri_idx, edge, &slope))
+        _check(swmm_2d_get_edge_bc_slope(self._h(), tri_idx, edge, &slope))
         return slope
 
     def set_edge_bc_slope(self, int tri_idx, int edge, double slope):
@@ -1202,9 +1426,9 @@ cdef class Surface2D:
         @type edge: int
         @param slope: Boundary slope.
         @type slope: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
-        _check(swmm_2d_set_edge_bc_slope(self._engine, tri_idx, edge, slope))
+        _check(swmm_2d_set_edge_bc_slope(self._h(), tri_idx, edge, slope))
 
     def get_edge_bc_cum_flux(self, int tri_idx, int edge) -> float:
         """Return the cumulative boundary flux for a triangle edge.
@@ -1215,10 +1439,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Cumulative boundary flux through the edge.
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double cum_flux = 0.0
-        _check(swmm_2d_get_edge_bc_cum_flux(self._engine, tri_idx, edge, &cum_flux))
+        _check(swmm_2d_get_edge_bc_cum_flux(self._h(), tri_idx, edge, &cum_flux))
         return cum_flux
 
     def get_edge_bc_flow(self, int tri_idx, int edge) -> float:
@@ -1230,10 +1454,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Prescribed flow per metre of edge (C{m^3/s/m}).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double flow = 0.0
-        _check(swmm_2d_get_edge_bc_flow(self._engine, tri_idx, edge, &flow))
+        _check(swmm_2d_get_edge_bc_flow(self._h(), tri_idx, edge, &flow))
         return flow
 
     def set_edge_bc_flow(self, int tri_idx, int edge, double flow):
@@ -1245,9 +1469,9 @@ cdef class Surface2D:
         @type edge: int
         @param flow: Prescribed flow per metre of edge (C{m^3/s/m}).
         @type flow: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
-        _check(swmm_2d_set_edge_bc_flow(self._engine, tri_idx, edge, flow))
+        _check(swmm_2d_set_edge_bc_flow(self._h(), tri_idx, edge, flow))
 
     def set_edge_bc_tseries_name(self, int tri_idx, int edge, str name):
         """Set the timeseries name driving a SPECIFIED_STAGE edge.
@@ -1262,10 +1486,31 @@ cdef class Surface2D:
         @type edge: int
         @param name: Timeseries name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         cdef bytes b = name.encode("utf-8")
-        _check(swmm_2d_set_edge_bc_tseries_name(self._engine, tri_idx, edge, b))
+        _check(swmm_2d_set_edge_bc_tseries_name(self._h(), tri_idx, edge, b))
+
+    def get_edge_bc_tseries_name(self, int tri_idx, int edge) -> str:
+        """Return the timeseries name driving a SPECIFIED_STAGE edge.
+
+        The mirror of L{set_edge_bc_tseries_name}, so an edit can be read
+        back and verified. Names longer than the internal buffer are
+        truncated.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Timeseries name; C{""} when the slot is clear (the edge uses
+            the constant C{edge_bc_head}).
+        @rtype: str
+        @raise EngineError: If the C API call fails.
+        """
+        cdef char buf[256]
+        _check(swmm_2d_get_edge_bc_tseries_name(
+            self._h(), tri_idx, edge, buf, 256))
+        return buf.decode('utf-8')
 
     def set_edge_bc_flow_tseries_name(self, int tri_idx, int edge, str name):
         """Set the timeseries name driving a SPECIFIED_FLOW edge.
@@ -1279,10 +1524,29 @@ cdef class Surface2D:
         @type edge: int
         @param name: Timeseries name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         cdef bytes b = name.encode("utf-8")
-        _check(swmm_2d_set_edge_bc_flow_tseries_name(self._engine, tri_idx, edge, b))
+        _check(swmm_2d_set_edge_bc_flow_tseries_name(self._h(), tri_idx, edge, b))
+
+    def get_edge_bc_flow_tseries_name(self, int tri_idx, int edge) -> str:
+        """Return the timeseries name driving a SPECIFIED_FLOW edge.
+
+        Same contract as L{get_edge_bc_tseries_name}.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Timeseries name; C{""} when the slot is clear (no series
+            bound).
+        @rtype: str
+        @raise EngineError: If the C API call fails.
+        """
+        cdef char buf[256]
+        _check(swmm_2d_get_edge_bc_flow_tseries_name(
+            self._h(), tri_idx, edge, buf, 256))
+        return buf.decode('utf-8')
 
     def set_edge_bc_rating_curve_name(self, int tri_idx, int edge, str name):
         """Set the rating-curve name driving a RATING_CURVE edge.
@@ -1297,10 +1561,29 @@ cdef class Surface2D:
         @type edge: int
         @param name: Rating-curve name, or C{""} to clear.
         @type name: str
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
         cdef bytes b = name.encode("utf-8")
-        _check(swmm_2d_set_edge_bc_rating_curve_name(self._engine, tri_idx, edge, b))
+        _check(swmm_2d_set_edge_bc_rating_curve_name(self._h(), tri_idx, edge, b))
+
+    def get_edge_bc_rating_curve_name(self, int tri_idx, int edge) -> str:
+        """Return the rating-curve name driving a RATING_CURVE edge.
+
+        Same contract as L{get_edge_bc_tseries_name}.
+
+        @param tri_idx: Triangle index.
+        @type tri_idx: int
+        @param edge: Edge index in C{0}-C{2}.
+        @type edge: int
+        @return: Rating-curve name; C{""} when the slot is clear (no curve
+            bound).
+        @rtype: str
+        @raise EngineError: If the C API call fails.
+        """
+        cdef char buf[256]
+        _check(swmm_2d_get_edge_bc_rating_curve_name(
+            self._h(), tri_idx, edge, buf, 256))
+        return buf.decode('utf-8')
 
     # ------------------------------------------------------------------
     # Edge conveyance factor (§11A of docs/2dModelStrategy.md)
@@ -1315,10 +1598,10 @@ cdef class Surface2D:
         @type edge: int
         @return: Conveyance factor (1.0 = unrestricted, 0.0 = wall).
         @rtype: float
-        @raise RuntimeError: If the C API call fails.
+        @raise EngineError: If the C API call fails.
         """
         cdef double c = 1.0
-        _check(swmm_2d_get_edge_conveyance(self._engine, tri, edge, &c))
+        _check(swmm_2d_get_edge_conveyance(self._h(), tri, edge, &c))
         return c
 
     def set_edge_conveyance(self, int tri, int edge, double conveyance):
@@ -1333,26 +1616,448 @@ cdef class Surface2D:
         @type edge: int
         @param conveyance: New value in C{[0, 1]}.
         @type conveyance: float
-        @raise RuntimeError: If the C API rejects the assignment.
+        @raise EngineError: If the C API rejects the assignment.
         """
-        _check(swmm_2d_set_edge_conveyance(self._engine, tri, edge, conveyance))
+        _check(swmm_2d_set_edge_conveyance(self._h(), tri, edge, conveyance))
 
     def get_edge_conveyance_bulk(self):
         """Return a NumPy array of all per-edge conveyance factors.
 
-        Length is C{triangle_count * 3}, indexed C{[tri*3 + edge]}.
+        Length is C{triangle_count * edge_stride}, indexed C{[cell*stride + edge]}.
         """
         import numpy as np
         cdef int nt = 0
-        _check(swmm_2d_triangle_count(self._engine, &nt))
-        cdef double[::1] out = np.empty(nt * 3, dtype=np.float64)
+        _check(swmm_2d_triangle_count(self._h(), &nt))
+        cdef int stride = 3
+        _check(swmm_2d_edge_stride(self._h(), &stride))
+        cdef double[::1] out = np.empty(nt * stride, dtype=np.float64)
+        if nt == 0:
+            return np.asarray(out)
+        cdef void* eng = self._h()
         cdef double* p = &out[0]
         cdef int err
-        with nogil:
-            err = swmm_2d_get_edge_conveyance_bulk(self._engine, p)
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_2d_get_edge_conveyance_bulk(eng, p)
         _check(err)
         return np.asarray(out)
 
     def reset_edge_conveyance(self):
         """Reset every edge's conveyance factor to 1.0 (unrestricted)."""
-        _check(swmm_2d_reset_edge_conveyance(self._engine))
+        _check(swmm_2d_reset_edge_conveyance(self._h()))
+
+    # ------------------------------------------------------------------
+    # Per-cell infiltration (plan §5.5, track I)
+    # ------------------------------------------------------------------
+
+    @property
+    def infiltration(self):
+        """``surface2d.infiltration`` — the L{Infiltration2DView} sub-view.
+
+        Per-cell infiltration for the C{GROUNDWATER OFF} path: options,
+        the tag-default mapping, per-cell overrides, and the held-rate /
+        cumulative-depth readers.
+
+        @return: The cached L{Infiltration2DView} for this mesh.
+        @rtype: Infiltration2DView
+        """
+        self._h()
+        if self._infiltration is None:
+            self._infiltration = Infiltration2DView(self._owner)
+        return self._infiltration
+
+
+# ========================================================================
+# Per-cell infiltration (plan §5.5.6, track I step I6)
+# ========================================================================
+
+Infil2DRow = namedtuple(
+    "Infil2DRow", "method params dest",
+    defaults=((0.0, 0.0, 0.0, 0.0, 0.0), SurfaceInfilDest.LOST),
+)
+Infil2DRow.__doc__ = """One infiltration specification.
+
+``method`` is a L{SurfaceInfilMethod}, or ``None`` for "no infiltration
+model" (the C{NONE} token). ``params`` is a tuple of up to five
+POSITIONAL values in B{PROJECT UNITS} — the same numbers a user types
+into a legacy C{[INFILTRATION]} row (in/hr and in on a US-C{FLOW_UNITS}
+project, mm/hr and mm on SI):
+
+    ==================  =========  ====  ============  ============  ====
+    method              params[0]  [1]   [2]           [3]           [4]
+    ==================  =========  ====  ============  ============  ====
+    HORTON              f0         fmin  decay (1/hr)  dry_time (d)  Fmax
+    MOD_HORTON          f0         fmin  decay (1/hr)  dry_time (d)  Fmax
+    GREEN_AMPT          suction    Ks    IMD           --            --
+    MOD_GREEN_AMPT      suction    Ks    IMD           --            --
+    CURVE_NUMBER        CN         --    dry_time (d)  --            --
+    CONSTANT            rate       --    --            --            --
+    ==================  =========  ====  ============  ============  ====
+
+``dest`` is a L{SurfaceInfilDest}; only C{LOST} is routed in this release.
+"""
+
+Infil2DCell = namedtuple("Infil2DCell", "row is_override")
+Infil2DCell.__doc__ = """The infiltration specification in force at one cell.
+
+Unpacks as ``row, is_override = surface2d.infiltration.cell(tri)``.
+``is_override`` is C{True} when the row came from the per-cell
+C{[2D_INFILTRATION]} layer rather than a tag / C{'*'} default.
+"""
+
+
+cdef void _infil_row_to_c(object row, SWMM_Infil2DRow* out) except *:
+    """Fill a C{SWMM_Infil2DRow} from an L{Infil2DRow} (or a NONE row).
+
+    @param row: The row to convert; C{None} or a row whose C{method} is
+        C{None} produces the C{NONE} specification.
+    @raise ValueError: If more than five parameters are supplied.
+    """
+    cdef int k
+    out.has_method = 0
+    out.method = 0
+    for k in range(5):
+        out.p[k] = 0.0
+    out.dest = SurfaceInfilDest.LOST
+
+    if row is None or row.method is None:
+        return
+
+    params = tuple(row.params) if row.params is not None else ()
+    if len(params) > 5:
+        raise ValueError(
+            f"at most 5 infiltration parameters, got {len(params)}")
+
+    out.has_method = 1
+    out.method = int(SurfaceInfilMethod(row.method))
+    for k in range(len(params)):
+        out.p[k] = float(params[k])
+    out.dest = int(SurfaceInfilDest(row.dest))
+
+
+cdef object _infil_row_from_c(SWMM_Infil2DRow* c):
+    """Build an L{Infil2DRow} from a C{SWMM_Infil2DRow}."""
+    cdef object params = (c.p[0], c.p[1], c.p[2], c.p[3], c.p[4])
+    if not c.has_method:
+        return Infil2DRow(None, params, SurfaceInfilDest.LOST)
+    return Infil2DRow(SurfaceInfilMethod(c.method), params,
+                      SurfaceInfilDest(c.dest))
+
+
+class Infil2DDefaults(MutableMapping):
+    """``surface2d.infiltration.defaults`` — tag → L{Infil2DRow} mapping.
+
+    Mirrors C{[2D_INFILTRATION_DEFAULTS]}. The key C{"*"} is the mesh-wide
+    fallback; every other key matches the C{TAG} column of
+    C{[2D_TRIANGLES]}. Resolution order is
+    C{per-cell override > tag row > '*' row > none}.
+
+    .. code-block:: python
+
+        infil = solver.surface2d.infiltration
+        infil.defaults["*"] = Infil2DRow(None)                  # no default
+        infil.defaults["LAWN"] = Infil2DRow(
+            SurfaceInfilMethod.HORTON, (3.0, 0.5, 4.14, 7.0, 0.0))
+        del infil.defaults["WOODS"]
+
+    Assignment is only accepted before the solver initializes — see
+    L{Infiltration2DView} for the staleness rule.
+    """
+
+    def __init__(self, owner):
+        self._owner = resolve_owner(owner)
+        self._generation = self._owner.generation
+
+    def _address(self):
+        if self._generation != self._owner.generation:
+            raise StaleObjectError("Infiltration defaults were invalidated")
+        return self._owner.handle
+
+    def __len__(self):
+        cdef void* eng = self._address()
+        cdef int n = 0
+        _check(swmm_infil2d_defaults_count(eng, &n))
+        return n
+
+    def _tags(self):
+        """Return the authored tags in file order (C{'*'} may be anywhere)."""
+        cdef void* eng = self._address()
+        cdef int n = 0
+        cdef char buf[256]
+        cdef int i
+        _check(swmm_infil2d_defaults_count(eng, &n))
+        out = []
+        for i in range(n):
+            _check(swmm_infil2d_get_default_tag(eng, i, buf, 256))
+            out.append(buf.decode("utf-8"))
+        return out
+
+    def __iter__(self):
+        # Materialised deliberately: a generator would put the C{char[256]}
+        # scratch buffer in a closure, which Cython cannot do.
+        return iter(self._tags())
+
+    def __getitem__(self, key):
+        cdef void* eng = self._address()
+        cdef SWMM_Infil2DRow row
+        cdef int i
+        tags = self._tags()
+        for i in range(len(tags)):
+            if tags[i] != key:
+                continue
+            _check(swmm_infil2d_get_default(eng, i, &row))
+            return _infil_row_from_c(&row)
+        raise KeyError(key)
+
+    def __setitem__(self, key, value):
+        cdef void* eng = self._address()
+        cdef bytes tag = str(key).encode("utf-8")
+        cdef SWMM_Infil2DRow row
+        _infil_row_to_c(value, &row)
+        _check(swmm_infil2d_set_default(eng, tag, &row))
+
+    def __delitem__(self, key):
+        cdef void* eng = self._address()
+        cdef bytes tag
+        if key not in self:
+            raise KeyError(key)
+        tag = str(key).encode("utf-8")
+        _check(swmm_infil2d_remove_default(eng, tag))
+
+    def __repr__(self):
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+cdef class Infiltration2DView:
+    """``surface2d.infiltration`` — per-cell infiltration on the 2D mesh.
+
+    The C{GROUNDWATER OFF} loss model (plan §5.5): a held per-cell rate,
+    recomputed on the C{INFIL_STEP} cadence and consumed by the explicit
+    marcher. Wraps C{openswmm_infil2d.h}.
+
+    .. code-block:: python
+
+        infil = solver.surface2d.infiltration
+        infil.infil_step = 300.0                       # seconds
+        infil.defaults["LAWN"] = Infil2DRow(
+            SurfaceInfilMethod.HORTON, (3.0, 0.5, 4.14, 7.0, 0.0))
+        infil.set_cells([12, 13, 14], Infil2DRow(
+            SurfaceInfilMethod.CURVE_NUMBER, (85.0, 0.0, 7.0)))
+
+        row, is_override = infil.cell(12)
+        f = infil.rate()          # m/s, per triangle
+        F = infil.cumulative()    # m,   per triangle
+        infil.total_volume        # m^3, the infil_out ledger row
+
+    B{Units.} Row parameters are in B{project units} (see L{Infil2DRow});
+    every readback channel is SI, like the rest of the 2D API.
+
+    B{Staleness.} Parameters are baked into per-cell kernel state once,
+    when the 2D surface initializes, and there is no per-cell re-init path.
+    Every writer here therefore raises C{LifecycleError} (engine
+    C{SWMM_ERR_LIFECYCLE}) once the solver has been initialized; edit in the
+    opened state, then initialize.
+
+    @ivar _engine: Internal pointer to the underlying C{SWMM_Engine} handle.
+    """
+
+    cdef object _owner
+    cdef long long _generation
+    cdef object _defaults
+
+    def __cinit__(self, owner):
+        self._owner = resolve_owner(owner)
+        self._generation = self._owner.generation
+        self._defaults = None
+
+    cdef void* _h(self) except NULL:
+        if self._generation != self._owner.generation:
+            raise StaleObjectError("Infiltration view was invalidated")
+        return self._owner.handle
+
+    # -- options -------------------------------------------------------
+
+    @property
+    def infil_step(self) -> float:
+        """Evaluation cadence in B{seconds} (C{[2D_INFILTRATION_OPTIONS]}).
+
+        C{<= 0} means "use the project C{WET_STEP}", which the 2D surface
+        resolves when it initializes. The value reported is the authored
+        one, not the resolved one.
+
+        @rtype: float
+        @raise EngineError: If the C API call fails.
+        """
+        cdef SWMM_Infil2DOptions opts
+        _check(swmm_infil2d_get_options(self._h(), &opts))
+        return opts.infil_step
+
+    @infil_step.setter
+    def infil_step(self, double seconds) -> None:
+        cdef SWMM_Infil2DOptions opts
+        opts.infil_step = seconds
+        _check(swmm_infil2d_set_options(self._h(), &opts))
+
+    # -- tag defaults --------------------------------------------------
+
+    @property
+    def defaults(self):
+        """The C{[2D_INFILTRATION_DEFAULTS]} tag → L{Infil2DRow} mapping.
+
+        @rtype: Infil2DDefaults
+        """
+        self._h()
+        if self._defaults is None:
+            self._defaults = Infil2DDefaults(self._owner)
+        return self._defaults
+
+    # -- per-cell overrides --------------------------------------------
+
+    def cell(self, int tri):
+        """Return the infiltration specification in force at one triangle.
+
+        After the solver initializes this is the B{resolved} row, with
+        C{is_override} reporting the resolved provenance. Before it
+        initializes only the per-cell override layer is visible, so a cell
+        carrying no override reports a C{NONE} row even when a tag or
+        C{'*'} default would later apply.
+
+        @param tri: Triangle index (0-based).
+        @type tri: int
+        @return: C{(row, is_override)}.
+        @rtype: Infil2DCell
+        @raise EngineError: If the C API call fails.
+        """
+        cdef SWMM_Infil2DRow row
+        cdef int is_override = 0
+        _check(swmm_infil2d_get_cell(self._h(), tri, &row, &is_override))
+        return Infil2DCell(_infil_row_from_c(&row), bool(is_override))
+
+    def set_cell(self, int tri, row) -> None:
+        """Set (or clear) the per-cell override of one triangle.
+
+        C{row=None} CLEARS the override so the cell falls back to its tag
+        row / the C{'*'} row. That differs from an L{Infil2DRow} whose
+        C{method} is C{None}, which stores an explicit C{NONE} override and
+        so suppresses the defaults for that cell.
+
+        @param tri: Triangle index (0-based).
+        @type tri: int
+        @param row: Row to store (parameters in B{project units}), or
+            C{None} to clear the override.
+        @type row: Infil2DRow or None
+        @raise EngineError: If the C API rejects the assignment (including
+            after the solver has been initialized).
+        """
+        cdef SWMM_Infil2DRow crow
+        if row is None:
+            _check(swmm_infil2d_set_cell(self._h(), tri, NULL))
+            return
+        _infil_row_to_c(row, &crow)
+        _check(swmm_infil2d_set_cell(self._h(), tri, &crow))
+
+    def set_cells(self, tris, row) -> None:
+        """Assign one specification to many triangles in a single call.
+
+        The select-many-cells-then-assign entry point: one validation pass,
+        then one apply. B{All-or-nothing} — if any index is out of range
+        nothing at all is written. An empty C{tris} is a no-op.
+
+        @param tris: Iterable of 0-based triangle indices.
+        @type tris: sequence[int]
+        @param row: Row to store on every listed triangle (parameters in
+            B{project units}), or C{None} to clear their overrides.
+        @type row: Infil2DRow or None
+        @raise EngineError: If the C API rejects the assignment.
+        """
+        cdef SWMM_Infil2DRow crow
+        cdef np.ndarray[int, ndim=1] arr = np.ascontiguousarray(
+            tris, dtype=np.intc).reshape(-1)
+        cdef int n = arr.shape[0]
+        if n == 0:
+            return
+        if row is None:
+            _check(swmm_infil2d_set_cells(self._h(), arr.data, n, NULL))
+            return
+        _infil_row_to_c(row, &crow)
+        _check(swmm_infil2d_set_cells(self._h(), arr.data, n, &crow))
+
+    # -- state readback (SI) -------------------------------------------
+
+    def rate(self):
+        """Return the held per-cell infiltration rate as a NumPy array.
+
+        Units are B{m/s}, C{>= 0}, one entry per triangle. The rate is
+        recomputed on the C{INFIL_STEP} cadence and held constant between
+        updates. A mesh with no resolved model returns all zeros.
+
+        @rtype: np.ndarray
+        @raise EngineError: If the C API call fails.
+        """
+        cdef int nt = 0
+        _check(swmm_2d_triangle_count(self._h(), &nt))
+        cdef double[::1] out = np.zeros(max(nt, 1), dtype=np.float64)
+        cdef double* p = &out[0]
+        cdef void* eng = self._h()
+        cdef int err
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_infil2d_get_rate_bulk(eng, p, nt if nt > 0 else 1)
+        _check(err)
+        return np.asarray(out)[:nt]
+
+    def cumulative(self):
+        """Return the cumulative infiltrated depth per cell as a NumPy array.
+
+        Units are B{m}, one entry per triangle — the C{infil_cum} sidecar
+        variable. A mesh with no resolved model returns all zeros.
+
+        @rtype: np.ndarray
+        @raise EngineError: If the C API call fails.
+        """
+        cdef int nt = 0
+        _check(swmm_2d_triangle_count(self._h(), &nt))
+        cdef double[::1] out = np.zeros(max(nt, 1), dtype=np.float64)
+        cdef double* p = &out[0]
+        cdef void* eng = self._h()
+        cdef int err
+        with self._owner._operation(eng):
+            with nogil:
+                err = swmm_infil2d_get_cum_bulk(eng, p, nt if nt > 0 else 1)
+        _check(err)
+        return np.asarray(out)[:nt]
+
+    @property
+    def total_volume(self) -> float:
+        """Cumulative 2D infiltration loss in B{m³} (the C{infil_out} row).
+
+        The whole-domain companion to L{cumulative}. Requires the 2D mass
+        balance to be live (the same contract as
+        C{Surface2D.get_mass_balance}).
+
+        @rtype: float
+        @raise EngineError: If the 2D mass balance is not active.
+        """
+        cdef double v = 0.0
+        _check(swmm_infil2d_get_total_volume(self._h(), &v))
+        return v
+
+    def __repr__(self) -> str:
+        try:
+            return (f"")
+        except Exception:
+            return ""
+
+cdef extern from "openswmm/engine/openswmm_2d.h":
+    int swmm_2d_get_rainfall_bulk(void*, double*) noexcept nogil
+    int swmm_2d_get_rain_volume_bulk(void*, double*) noexcept nogil
+    int swmm_2d_get_coupling_volume_bulk(void*, double*) noexcept nogil
+    int swmm_2d_get_rainfall_weights(void*, int, int*, int*, double*, int, int*)
+    int swmm_2d_output_variable_count()
+    const char* swmm_2d_output_variable_name(int)
+    unsigned swmm_2d_output_variable_mask(const char*)
+    const char* swmm_2d_output_variable_text(unsigned)
diff --git a/python/openswmm/engine/__init__.pxd b/python/openswmm/engine/__init__.pxd
index e27947a8f..a376f1151 100644
--- a/python/openswmm/engine/__init__.pxd
+++ b/python/openswmm/engine/__init__.pxd
@@ -1,6 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # :author: Caleb Buahin
 # :copyright: Copyright (c) 2026 Caleb Buahin
-# :license: MIT
+# :license: Apache-2.0
 
 # cython: language_level=3
 from ._common cimport *
diff --git a/python/openswmm/engine/__init__.py b/python/openswmm/engine/__init__.py
index a702ca6fa..c738f03d4 100644
--- a/python/openswmm/engine/__init__.py
+++ b/python/openswmm/engine/__init__.py
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 openswmm.engine
 ===============
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Cython bindings for the OpenSWMM Engine 6.0 C API.
 
@@ -58,6 +74,21 @@
    * - :class:`Quality`
      - ``openswmm_quality.h``
      - Landuse, buildup, washoff, treatment
+   * - :class:`InitialQuality`
+     - ``openswmm_initial_quality.h``
+     - ``[INITIAL_QUALITY]`` per-element starting concentrations
+   * - :class:`Reactions`
+     - ``openswmm_reactions.h``
+     - Multi-species reaction system: species, coefficients, terms, expressions
+   * - :class:`Heat`
+     - ``openswmm_heat.h``
+     - Heat-transport fluxes, solar/cloud forcing, inlet temperatures
+   * - :class:`WaterAge`
+     - ``openswmm_water_age.h``
+     - ``[WATER_AGE_SOURCES]`` per-pathway source ages
+   * - :class:`ProcessComponents`
+     - ``openswmm_process_components.h``
+     - ``[PROCESS_COMPONENTS]`` registrations and config-file bindings
    * - :class:`Tables`
      - ``openswmm_tables.h``
      - Time series, curves, patterns
@@ -93,11 +124,9 @@
     with Solver("model.inp", "model.rpt", "model.out") as s:
         nodes = Nodes(s)
         links = Links(s)
-        while s.state == EngineState.RUNNING:
-            if s.step() != 0:
-                break
-            depths = nodes.get_depths_bulk()  # numpy array
-            flows  = links.get_flows_bulk()   # numpy array
+        for elapsed in s.steps():
+            depths = nodes.depths
+            flows = links.flows
 
 Programmatic model building
 ----------------------------
@@ -119,9 +148,7 @@
 
     solver = m.to_solver()
     solver.start()
-    while solver.state == EngineState.RUNNING:
-        if solver.step() != 0:
-            break
+    for elapsed in solver.steps():
         pass
     solver.end()
     solver.destroy()
@@ -209,12 +236,30 @@
 # =============================================================================
 from ._pollutants import Pollutants
 from ._quality import Quality
+from ._initial_quality import InitialQuality, InitialQualityEntry
 from ._tables import Tables, Patterns
 from ._inflows import Inflows
 from ._controls import Controls
 from ._forcing import Forcing
 from ._climate import Climate
 
+# =============================================================================
+# Transport processes — heat, water age, reactions, process components
+# =============================================================================
+from ._heat import Heat, HeatNodeOverride
+from ._water_age import WaterAge, WaterAgeOverride
+from ._reactions import (
+    Reactions,
+    ReactionSpecies,
+    ReactionCoefficient,
+    ReactionTerm,
+    ReactionInitialEntry,
+    ReactionHydVar,
+    ReactionFunction,
+    ExpressionDiagnostic,
+)
+from ._process_components import ProcessComponents, ProcessComponent
+
 # =============================================================================
 # Spatial / infrastructure / 2D
 # =============================================================================
@@ -225,15 +270,20 @@
 # Optional extensions (require specific build flags)
 # =============================================================================
 try:
-    from ._2d import Surface2D
+    from ._2d import (Surface2D, Infiltration2DView, Infil2DDefaults,
+                      Infil2DRow, Infil2DCell)
     HAS_2D = True
-except ImportError:
+except ModuleNotFoundError as error:
+    if error.name != __name__ + "._2d":
+        raise
     HAS_2D = False
 
 try:
     from ._geopackage import GeoPackage
     HAS_GEOPACKAGE = True
-except ImportError:
+except ModuleNotFoundError as error:
+    if error.name != __name__ + "._geopackage":
+        raise
     HAS_GEOPACKAGE = False
 
 # =============================================================================
@@ -256,17 +306,25 @@
     # Water quality / LID
     ConcentrationUnits, BuildupFunc, WashoffFunc, LidType,
     # Hydrology parameters
-    AquiferParam,
+    AquiferParam, GwfType,
     # Output variables
     OutSubcatchVar, OutNodeVar, OutLinkVar, OutSystemVar,
     # Forcing & patterns
     ForcingMode, ForcingTarget, ForcingType, ForcingPersist, PatternType,
     # 2D surface routing
     SurfaceForcingMode, SurfaceBoundaryType,
+    SurfaceInfilMethod, SurfaceInfilDest,
     # Nodes / editing
     DividerType, RefType,
     # Tables / model files
     TableType, FilePathRole, UserFlagType,
+    # Transport processes — heat, water age, reactions
+    HeatFluxModule, HeatShortwaveMode, HeatRadiativeParam, HeatSolarParam,
+    HeatCloudParam, HeatSourceKind, WaterAgeSource,
+    ReactionScope, ReactionExprForm,
+    # Street inlets
+    InletType, GrateType, ThroatType, InletCurveKind,
+    InletPlacement, InletHostKind,
     # Mass-balance totals
     RunoffTotal, RoutingTotal,
 )
@@ -299,10 +357,18 @@
     "HotStart", "MassBalance", "Statistics", "OutputReader",
     # --- Hydrology, water quality, and time-varying inputs ---
     "Pollutants", "Quality", "Tables", "Patterns", "Inflows", "Controls", "Forcing",
-    "Climate",
+    "Climate", "InitialQuality", "InitialQualityEntry",
+    # --- Transport processes — heat, water age, reactions ---
+    "Heat", "HeatNodeOverride",
+    "WaterAge", "WaterAgeOverride",
+    "Reactions", "ReactionSpecies", "ReactionCoefficient", "ReactionTerm",
+    "ReactionInitialEntry", "ReactionHydVar", "ReactionFunction",
+    "ExpressionDiagnostic",
+    "ProcessComponents", "ProcessComponent",
     # --- Spatial / infrastructure / 2D ---
     "Infrastructure", "Spatial",
     "Surface2D", "HAS_2D",
+    "Infiltration2DView", "Infil2DDefaults", "Infil2DRow", "Infil2DCell",
     # --- Optional extensions ---
     "HAS_GEOPACKAGE",
     # --- Enumerations: lifecycle / errors ---
@@ -316,15 +382,58 @@
     # --- Enumerations: water quality / LID ---
     "ConcentrationUnits", "BuildupFunc", "WashoffFunc", "LidType",
     # --- Enumerations: hydrology parameters ---
-    "AquiferParam",
+    "AquiferParam", "GwfType",
     # --- Enumerations: output variables ---
     "OutSubcatchVar", "OutNodeVar", "OutLinkVar", "OutSystemVar",
     # --- Enumerations: forcing & patterns ---
     "ForcingMode", "ForcingTarget", "ForcingType", "ForcingPersist", "PatternType",
     # --- Enumerations: 2D surface routing ---
     "SurfaceForcingMode", "SurfaceBoundaryType",
+    "SurfaceInfilMethod", "SurfaceInfilDest",
     "DividerType", "RefType",
     "TableType", "FilePathRole", "UserFlagType",
+    # --- Enumerations: transport processes ---
+    "HeatFluxModule", "HeatShortwaveMode", "HeatRadiativeParam", "HeatSolarParam",
+    "HeatCloudParam", "HeatSourceKind", "WaterAgeSource",
+    "ReactionScope", "ReactionExprForm",
+    # --- Enumerations: street inlets ---
+    "InletType", "GrateType", "ThroatType", "InletCurveKind",
+    "InletPlacement", "InletHostKind",
     # --- Enumerations: mass-balance totals ---
     "RunoffTotal", "RoutingTotal",
 ]
+
+# Native climate, transport, writer and unit-system selectors.
+from ._enums import (
+    EvapType as EvapType, TempSource as TempSource, WindType as WindType, HumidityType as HumidityType, HumidityVar as HumidityVar, HeatElemKind as HeatElemKind, InpProfile as InpProfile, TransportDispersionMode as TransportDispersionMode, UnitSystem as UnitSystem
+)
+__all__ += ['EvapType', 'TempSource', 'WindType', 'HumidityType', 'HumidityVar', 'HeatElemKind', 'InpProfile', 'TransportDispersionMode', 'UnitSystem']
+
+from ._transport import (Transport as Transport, ThreadInfo as ThreadInfo, EffectiveThreads as EffectiveThreads, TransportCell as TransportCell, TransportRow as TransportRow, ConduitDispersion as ConduitDispersion, transport_domain_name as transport_domain_name, transport_class_name as transport_class_name)
+from ._enums import (TransportDomain as TransportDomain, TransportClass as TransportClass, TransportState as TransportState)
+__all__ += ['Transport', 'ThreadInfo', 'EffectiveThreads', 'TransportCell', 'TransportRow', 'ConduitDispersion', 'transport_domain_name', 'transport_class_name', 'TransportDomain', 'TransportClass', 'TransportState']
+
+if not HAS_2D:
+    __all__ = [name for name in __all__ if name not in {
+        "Surface2D", "Infiltration2DView", "Infil2DDefaults", "Infil2DRow", "Infil2DCell"}]
+if HAS_GEOPACKAGE:
+    __all__.append("GeoPackage")
+
+from ._process_components import KnownProcessComponent as KnownProcessComponent
+__all__.append("KnownProcessComponent")
+
+from ._enums import (CellScope as CellScope, GroundwaterSoil as GroundwaterSoil, GroundwaterClosure as GroundwaterClosure, GroundwaterVariable as GroundwaterVariable, GroundwaterLedger as GroundwaterLedger, GroundwaterZone as GroundwaterZone, GroundwaterSpeciesLedger as GroundwaterSpeciesLedger)
+__all__ += ['CellScope', 'GroundwaterSoil', 'GroundwaterClosure', 'GroundwaterVariable', 'GroundwaterLedger', 'GroundwaterZone', 'GroundwaterSpeciesLedger']
+if HAS_2D:
+    from ._groundwater import Groundwater, AquiferRow, AquiferNode
+    __all__ += ["Groundwater", "AquiferRow", "AquiferNode"]
+
+from ._enums import GroundwaterTransportZone as GroundwaterTransportZone
+__all__.append("GroundwaterTransportZone")
+if HAS_2D:
+    from ._gw_transport import (GroundwaterTransport, GroundwaterParameters, GroundwaterSorption, GroundwaterInitialQuality, GroundwaterBoundary, GroundwaterSource, GroundwaterSourceTerm)
+    __all__ += ['GroundwaterTransport', 'GroundwaterParameters', 'GroundwaterSorption', 'GroundwaterInitialQuality', 'GroundwaterBoundary', 'GroundwaterSource', 'GroundwaterSourceTerm']
+
+if HAS_2D:
+    from ._surface_quality import (SurfaceQuality, SurfaceCoverage, SurfaceLoading, SurfaceCurbLength)
+    __all__ += ['SurfaceQuality', 'SurfaceCoverage', 'SurfaceLoading', 'SurfaceCurbLength']
diff --git a/python/openswmm/engine/__init__.pyi b/python/openswmm/engine/__init__.pyi
index c7252b107..b0f9e8811 100644
--- a/python/openswmm/engine/__init__.pyi
+++ b/python/openswmm/engine/__init__.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 openswmm.engine
 ===============
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for the L{openswmm.engine} package.
 
@@ -74,17 +90,41 @@ from ._output_reader import OutputReader as OutputReader
 # =============================================================================
 from ._pollutants import Pollutants as Pollutants
 from ._quality import Quality as Quality
+from ._initial_quality import InitialQuality as InitialQuality
+from ._initial_quality import InitialQualityEntry as InitialQualityEntry
 from ._tables import Tables as Tables
 from ._inflows import Inflows as Inflows
 from ._controls import Controls as Controls
 from ._forcing import Forcing as Forcing
 
+# =============================================================================
+# Transport processes — heat, water age, reactions, process components
+# =============================================================================
+from ._heat import Heat as Heat
+from ._heat import HeatNodeOverride as HeatNodeOverride
+from ._water_age import WaterAge as WaterAge
+from ._water_age import WaterAgeOverride as WaterAgeOverride
+from ._reactions import Reactions as Reactions
+from ._reactions import ReactionSpecies as ReactionSpecies
+from ._reactions import ReactionCoefficient as ReactionCoefficient
+from ._reactions import ReactionTerm as ReactionTerm
+from ._reactions import ReactionInitialEntry as ReactionInitialEntry
+from ._reactions import ReactionHydVar as ReactionHydVar
+from ._reactions import ReactionFunction as ReactionFunction
+from ._reactions import ExpressionDiagnostic as ExpressionDiagnostic
+from ._process_components import ProcessComponents as ProcessComponents
+from ._process_components import ProcessComponent as ProcessComponent
+
 # =============================================================================
 # Spatial / infrastructure / 2D
 # =============================================================================
 from ._infrastructure import Infrastructure as Infrastructure
 from ._spatial import Spatial as Spatial
 from ._2d import Surface2D as Surface2D
+from ._2d import Infiltration2DView as Infiltration2DView
+from ._2d import Infil2DDefaults as Infil2DDefaults
+from ._2d import Infil2DRow as Infil2DRow
+from ._2d import Infil2DCell as Infil2DCell
 
 # =============================================================================
 # Optional GeoPackage I/O (only available with OPENSWMM_WITH_GEOPACKAGE build)
@@ -125,10 +165,28 @@ from ._enums import (
     InfilModel as InfilModel,
     # Water quality / LID
     AquiferParam as AquiferParam,
+    GwfType as GwfType,
     BuildupFunc as BuildupFunc,
     ConcentrationUnits as ConcentrationUnits,
     LidType as LidType,
     WashoffFunc as WashoffFunc,
+    # Transport processes — heat, water age, reactions
+    HeatFluxModule as HeatFluxModule,
+    HeatShortwaveMode as HeatShortwaveMode,
+    HeatRadiativeParam as HeatRadiativeParam,
+    HeatSolarParam as HeatSolarParam,
+    HeatCloudParam as HeatCloudParam,
+    HeatSourceKind as HeatSourceKind,
+    WaterAgeSource as WaterAgeSource,
+    ReactionScope as ReactionScope,
+    ReactionExprForm as ReactionExprForm,
+    # Street inlets
+    InletType as InletType,
+    GrateType as GrateType,
+    ThroatType as ThroatType,
+    InletCurveKind as InletCurveKind,
+    InletPlacement as InletPlacement,
+    InletHostKind as InletHostKind,
     # Output variables
     OutLinkVar as OutLinkVar,
     OutNodeVar as OutNodeVar,
@@ -143,6 +201,8 @@ from ._enums import (
     # 2D surface routing
     SurfaceForcingMode as SurfaceForcingMode,
     SurfaceBoundaryType as SurfaceBoundaryType,
+    SurfaceInfilMethod as SurfaceInfilMethod,
+    SurfaceInfilDest as SurfaceInfilDest,
     # Nodes / editing
     DividerType as DividerType,
     RefType as RefType,
@@ -154,3 +214,21 @@ from ._enums import (
 HAS_GEOPACKAGE: bool
 
 __all__: list[str]
+
+# Native climate, transport, writer and unit-system selectors.
+from ._enums import (
+    EvapType as EvapType, TempSource as TempSource, WindType as WindType, HumidityType as HumidityType, HumidityVar as HumidityVar, HeatElemKind as HeatElemKind, InpProfile as InpProfile, TransportDispersionMode as TransportDispersionMode, UnitSystem as UnitSystem
+)
+
+from ._transport import (Transport as Transport, ThreadInfo as ThreadInfo, EffectiveThreads as EffectiveThreads, TransportCell as TransportCell, TransportRow as TransportRow, ConduitDispersion as ConduitDispersion, transport_domain_name as transport_domain_name, transport_class_name as transport_class_name)
+from ._enums import (TransportDomain as TransportDomain, TransportClass as TransportClass, TransportState as TransportState)
+
+from ._process_components import KnownProcessComponent as KnownProcessComponent
+
+from ._enums import (CellScope as CellScope, GroundwaterSoil as GroundwaterSoil, GroundwaterClosure as GroundwaterClosure, GroundwaterVariable as GroundwaterVariable, GroundwaterLedger as GroundwaterLedger, GroundwaterZone as GroundwaterZone, GroundwaterSpeciesLedger as GroundwaterSpeciesLedger)
+from ._groundwater import Groundwater as Groundwater, AquiferRow as AquiferRow, AquiferNode as AquiferNode
+
+from ._enums import GroundwaterTransportZone as GroundwaterTransportZone
+from ._gw_transport import (GroundwaterTransport as GroundwaterTransport, GroundwaterParameters as GroundwaterParameters, GroundwaterSorption as GroundwaterSorption, GroundwaterInitialQuality as GroundwaterInitialQuality, GroundwaterBoundary as GroundwaterBoundary, GroundwaterSource as GroundwaterSource, GroundwaterSourceTerm as GroundwaterSourceTerm)
+
+from ._surface_quality import (SurfaceQuality as SurfaceQuality, SurfaceCoverage as SurfaceCoverage, SurfaceLoading as SurfaceLoading, SurfaceCurbLength as SurfaceCurbLength)
diff --git a/python/openswmm/engine/_access.py b/python/openswmm/engine/_access.py
new file mode 100644
index 000000000..fe6b5eb82
--- /dev/null
+++ b/python/openswmm/engine/_access.py
@@ -0,0 +1,154 @@
+"""Lifetime and native-call coordination shared by engine views.
+
+Independent engines may advance concurrently. Access to one engine from a
+second thread during a native call fails promptly instead of racing its state
+or deadlocking a callback waiting for that thread. Callbacks on the advancing
+thread may inspect state and apply supported forcing; lifecycle reentry is
+refused by the owner. Raw pointer compatibility only accepts registered owners.
+"""
+from contextlib import contextmanager
+from threading import RLock
+from weakref import WeakValueDictionary
+from typing import Any, Callable, Iterator
+
+from ._enums import ErrorCode
+from ._exceptions import BadHandleError, LifecycleError, StaleObjectError
+
+_owners: WeakValueDictionary[int, Any] = WeakValueDictionary()
+
+
+def register_owner(owner: Any, address: int) -> int:
+    if address:
+        _owners[address] = owner
+    return address
+
+
+def resolve_owner(owner: Any) -> Any:
+    if isinstance(owner, int):
+        import warnings
+        warnings.warn("Pass the Solver to Surface2D instead of solver.handle",
+                      DeprecationWarning, stacklevel=3)
+        address = owner
+        try:
+            owner = _owners[address]
+        except KeyError:
+            raise BadHandleError(ErrorCode.BADHANDLE,
+                                 "Pointer has no live Python engine owner") from None
+        if owner.handle != address:
+            raise BadHandleError(ErrorCode.BADHANDLE, "Pointer no longer belongs to its owner")
+    if not hasattr(owner, "handle") or not owner.handle:
+        raise BadHandleError(ErrorCode.BADHANDLE, "Engine has been destroyed")
+    return owner
+
+
+class NativeAccess:
+    """Per-owner native operation guard and deferred callback exception."""
+
+    def __init__(self) -> None:
+        self.lock = RLock()
+        self.active = 0
+        self.forbid_access = False
+        self.error: BaseException | None = None
+
+    def check(self) -> None:
+        if self.forbid_access:
+            raise LifecycleError(ErrorCode.LIFECYCLE, "Engine access is forbidden inside a staging mapper")
+        if not self.lock.acquire(blocking=False):
+            raise LifecycleError(ErrorCode.LIFECYCLE,
+                                 "Engine is in use by another thread")
+        self.lock.release()
+
+    def require_idle(self) -> None:
+        self.check()
+        if self.active:
+            raise LifecycleError(ErrorCode.LIFECYCLE,
+                                 "Cannot change lifecycle during a native call or callback")
+
+    @contextmanager
+    def operation(self, owner: Any, expected: int = 0) -> Iterator[None]:
+        if not self.lock.acquire(blocking=False):
+            raise LifecycleError(ErrorCode.LIFECYCLE,
+                                 "Engine is in use by another thread")
+        try:
+            address = owner.handle
+            if not address:
+                raise BadHandleError(ErrorCode.BADHANDLE, "Engine has been destroyed")
+            if expected and address != expected:
+                raise StaleObjectError("Engine handle changed")
+            self.active += 1
+            try:
+                yield
+            finally:
+                self.active -= 1
+        finally:
+            self.lock.release()
+
+    def raise_callback_error(self) -> None:
+        error, self.error = self.error, None
+        if error is not None:
+            raise error
+
+
+class Callback:
+    """Capture Python failures without unwinding through a C callback ABI.
+
+The first failure is re-raised after the native operation returns. Further
+callbacks in that operation are suppressed; its current native step may finish.
+"""
+    def __init__(self, access: NativeAccess, callback: Callable[..., Any]) -> None:
+        if not callable(callback):
+            raise TypeError("callback must be callable or None")
+        self.access = access
+        self.callback = callback
+
+    def __call__(self, *args: Any) -> None:
+        if self.access.error is None:
+            try:
+                self.callback(*args)
+            except BaseException as error:
+                self.access.error = error
+
+
+class EngineView:
+    """An owner-backed domain view invalidated by lifecycle/structural changes."""
+
+    def __init__(self, owner: Any) -> None:
+        self._owner = resolve_owner(owner)
+        self._generation = self._owner.generation
+
+    def _address(self) -> int:
+        if self._generation != self._owner.generation:
+            raise StaleObjectError("View was invalidated; reacquire it from the solver")
+        address: int = self._owner.handle
+        if not address:
+            raise BadHandleError(ErrorCode.BADHANDLE, "Engine has been destroyed")
+        return address
+
+
+class StageMapper:
+    """Own callback result storage and defer exceptions across the C ABI."""
+
+    def __init__(self, access: NativeAccess, callback: Callable[..., Any]) -> None:
+        if not callable(callback):
+            raise TypeError("mapper must be callable")
+        self.access = access
+        self.callback = callback
+        self.storage = b""
+        self.error: BaseException | None = None
+
+    def map(self, path: str, kind: int) -> bytes:
+        import os
+        if self.error is not None:
+            return b""
+        self.access.forbid_access = True
+        try:
+            result = self.callback(path, kind)
+            self.storage = os.fsencode(result) if result is not None else b""
+            if b"\0" in self.storage:
+                raise ValueError("Staging path contains a null byte")
+            return self.storage
+        except BaseException as error:
+            self.error = error
+            return b""
+        finally:
+            self.access.forbid_access = False
diff --git a/python/openswmm/engine/_climate.pyi b/python/openswmm/engine/_climate.pyi
index 494f76258..b5e2ac7e0 100644
--- a/python/openswmm/engine/_climate.pyi
+++ b/python/openswmm/engine/_climate.pyi
@@ -28,6 +28,12 @@ class Climate:
     wind_type: int
     wind_monthly: List[float]
 
+    # Humidity ([TEMPERATURE] HUMIDITY)
+    humidity_type: int
+    humidity_variable: int
+    humidity_monthly: List[float]
+    humidity_timeseries: str
+
     # Snowmelt globals
     snow_temp: float
     ati_weight: float
diff --git a/python/openswmm/engine/_climate.pyx b/python/openswmm/engine/_climate.pyx
index f750b14f4..3f79e0f14 100644
--- a/python/openswmm/engine/_climate.pyx
+++ b/python/openswmm/engine/_climate.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Climatology configuration (Pythonic v1 surface)
 ===============================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Climate` view, reached via ``solver.climate``, reads and edits the
 model's climate *configuration* — the data parsed from the ``[TEMPERATURE]``,
@@ -232,6 +248,51 @@ class Climate:
     def wind_monthly(self, values) -> None:
         _write_arr(_ch(self._solver), swmm_climate_set_wind_monthly, values, 12)
 
+    # -- Humidity ---------------------------------------------------
+
+    @property
+    def humidity_type(self) -> int:
+        """Humidity source: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES."""
+        cdef int v = 0
+        _check(swmm_climate_get_humidity_type(_ch(self._solver), &v))
+        return v
+
+    @humidity_type.setter
+    def humidity_type(self, int value) -> None:
+        _check(swmm_climate_set_humidity_type(_ch(self._solver), value))
+
+    @property
+    def humidity_variable(self) -> int:
+        """Humidity quantity: 0=RELATIVE (%), 1=DEWPOINT (project temperature units)."""
+        cdef int v = 0
+        _check(swmm_climate_get_humidity_variable(_ch(self._solver), &v))
+        return v
+
+    @humidity_variable.setter
+    def humidity_variable(self, int value) -> None:
+        _check(swmm_climate_set_humidity_variable(_ch(self._solver), value))
+
+    @property
+    def humidity_monthly(self) -> list:
+        """Twelve monthly humidity values (RH % or dew point per ``humidity_variable``)."""
+        return _read_arr(_ch(self._solver), swmm_climate_get_humidity_monthly, 12)
+
+    @humidity_monthly.setter
+    def humidity_monthly(self, values) -> None:
+        _write_arr(_ch(self._solver), swmm_climate_set_humidity_monthly, values, 12)
+
+    @property
+    def humidity_timeseries(self) -> str:
+        """Humidity time-series id (empty if none). Setting it selects TIMESERIES."""
+        cdef char buf[256]
+        _check(swmm_climate_get_humidity_timeseries(_ch(self._solver), buf, sizeof(buf)))
+        return (buf).decode('utf-8')
+
+    @humidity_timeseries.setter
+    def humidity_timeseries(self, value) -> None:
+        cdef bytes b = value.encode('utf-8')
+        _check(swmm_climate_set_humidity_timeseries(_ch(self._solver), b))
+
     # -- Snowmelt globals -------------------------------------------
 
     @property
diff --git a/python/openswmm/engine/_common.pxd b/python/openswmm/engine/_common.pxd
index 0019d9a98..5e57656a2 100644
--- a/python/openswmm/engine/_common.pxd
+++ b/python/openswmm/engine/_common.pxd
@@ -1,6 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # :author: Caleb Buahin
 # :copyright: Copyright (c) 2026 Caleb Buahin
-# :license: MIT
+# :license: Apache-2.0
 #
 # _common.pxd — Shared C declarations for the OpenSWMM Engine C API.
 #
@@ -188,14 +204,20 @@ cdef extern from "openswmm_nodes.h":
     cdef int swmm_node_set_surcharge_depth(SWMM_Engine e, int idx, double depth)
     cdef int swmm_node_set_pond_area(SWMM_Engine e, int idx, double area)
     cdef int swmm_node_set_initial_depth(SWMM_Engine e, int idx, double depth)
+    cdef int swmm_node_set_rim_depth(SWMM_Engine e, int idx, double depth)
     # Virtual junctions (refactored engine only)
     cdef int swmm_node_is_virtual(SWMM_Engine e, int idx, int* is_virtual)
     cdef int swmm_node_set_virtual(SWMM_Engine e, int idx, int make_virtual)
     cdef int swmm_node_virtual_eligible(SWMM_Engine e, int idx, int* rule_code)
+    cdef int swmm_node_is_inlet(SWMM_Engine e, int idx, int* is_inlet)
+    cdef int swmm_node_inlet_eligible(SWMM_Engine e, int idx, int for_drop_inlet,
+                                       int* rule_code)
+    cdef int swmm_node_set_inlet(SWMM_Engine e, int idx, int make_inlet)
     # Geometry getters
     cdef int swmm_node_get_type(SWMM_Engine e, int idx, int* type)
     cdef int swmm_node_get_invert_elev(SWMM_Engine e, int idx, double* elev)
     cdef int swmm_node_get_max_depth(SWMM_Engine e, int idx, double* depth)
+    cdef int swmm_node_get_rim_depth(SWMM_Engine e, int idx, double* depth)
     cdef int swmm_node_get_surcharge_depth(SWMM_Engine e, int idx, double* depth)
     cdef int swmm_node_get_ponded_area(SWMM_Engine e, int idx, double* area)
     cdef int swmm_node_get_initial_depth(SWMM_Engine e, int idx, double* depth)
@@ -382,6 +404,10 @@ cdef extern from "openswmm_links.h":
     cdef int swmm_link_get_pump_stats_bulk(SWMM_Engine e, int* cycles,
                                             double* on_time, double* volume,
                                             int count) nogil
+    # Preissmann-slot storage (FV routing only; reads 0.0 under dynamic wave)
+    cdef int swmm_link_get_slot_volume(SWMM_Engine e, int idx, double* volume)
+    cdef int swmm_link_get_stat_peak_slot_share(SWMM_Engine e, int idx, double* val)
+    cdef int swmm_link_get_stat_slot_share(SWMM_Engine e, int idx, double* val)
     # Hydraulic power
     cdef int swmm_link_get_hyd_power(SWMM_Engine e, int idx, double* power)
     # Bulk access
@@ -419,6 +445,17 @@ cdef extern from "openswmm_subcatchments.h":
     cdef int         swmm_aquifer_set_param(SWMM_Engine e, int idx, int param, double value)
     cdef int         swmm_aquifer_get_evap_pattern(SWMM_Engine e, int idx, char* buf, int buflen)
     cdef int         swmm_aquifer_set_evap_pattern(SWMM_Engine e, int idx, const char* name)
+    cdef int         swmm_aquifer_rename(SWMM_Engine e, int idx, const char* new_id)
+    # [GWF] custom groundwater flow expressions
+    cdef int         swmm_subcatch_get_gwf_expression(SWMM_Engine e, int idx, int type, char* buf, int buflen)
+    cdef int         swmm_subcatch_set_gwf_expression(SWMM_Engine e, int idx, int type, const char* expr)
+    cdef int         swmm_gwf_validate_expression(SWMM_Engine e, const char* expr,
+                                                  char* errbuf, int buflen, int* col_out)
+    cdef int         swmm_gwf_variable_count(SWMM_Engine e)
+    cdef int         swmm_gwf_variable_name(SWMM_Engine e, int i, char* buf, int buflen)
+    cdef int         swmm_gwf_variable_description(SWMM_Engine e, int i, char* buf, int buflen)
+    cdef int         swmm_gwf_function_count(SWMM_Engine e)
+    cdef int         swmm_gwf_function_name(SWMM_Engine e, int i, char* buf, int buflen)
     cdef int         swmm_snowpack_count(SWMM_Engine e)
     cdef int         swmm_snowpack_index(SWMM_Engine e, const char* id)
     cdef const char* swmm_snowpack_id(SWMM_Engine e, int idx)
@@ -433,6 +470,7 @@ cdef extern from "openswmm_subcatchments.h":
     cdef int         swmm_snowpack_get_removal(SWMM_Engine e, int idx, double* dsnow, double* fout, double* fimp, double* fperv, double* fimelt, double* fsubcatch)
     cdef int         swmm_snowpack_set_removal_subcatch(SWMM_Engine e, int idx, const char* name)
     cdef int         swmm_snowpack_get_removal_subcatch(SWMM_Engine e, int idx, char* buf, int buflen)
+    cdef int         swmm_snowpack_rename(SWMM_Engine e, int idx, const char* new_id)
     # Property setters
     cdef int swmm_subcatch_set_outlet(SWMM_Engine e, int idx, int node_idx)
     cdef int swmm_subcatch_set_area(SWMM_Engine e, int idx, double area)
@@ -550,6 +588,8 @@ cdef extern from "openswmm_gages.h":
     cdef int swmm_gage_set_timeseries(SWMM_Engine e, int idx, const char* ts_id)
     cdef int swmm_gage_set_filename(SWMM_Engine e, int idx, const char* path, const char* station_id)
     cdef int swmm_gage_set_station_id(SWMM_Engine e, int idx, const char* station_id)
+    cdef int swmm_gage_set_file_column(SWMM_Engine e, int idx, const char* column)
+    cdef int swmm_gage_set_file_format(SWMM_Engine e, int idx, int format)
     cdef int swmm_gage_set_snow_factor(SWMM_Engine e, int idx, double factor)
     cdef int swmm_gage_set_rain_units(SWMM_Engine e, int idx, int units)
     cdef int swmm_gage_set_scale_factor(SWMM_Engine e, int idx, double factor)
@@ -561,6 +601,8 @@ cdef extern from "openswmm_gages.h":
     cdef int swmm_gage_get_snow_factor(SWMM_Engine e, int idx, double* factor)
     cdef int swmm_gage_get_timeseries(SWMM_Engine e, int idx, char* buf, int buflen)
     cdef int swmm_gage_get_station_id(SWMM_Engine e, int idx, char* buf, int buflen)
+    cdef int swmm_gage_get_file_column(SWMM_Engine e, int idx, char* buf, int buflen)
+    cdef int swmm_gage_get_file_format(SWMM_Engine e, int idx, int* format)
     cdef int swmm_gage_get_rain_units(SWMM_Engine e, int idx, int* units)
     # State
     cdef int swmm_gage_get_rainfall(SWMM_Engine e, int idx, double* rainfall)
@@ -569,6 +611,12 @@ cdef extern from "openswmm_gages.h":
     cdef int swmm_gage_get_rainfall_bulk(SWMM_Engine e, double* buf, int count) nogil
     # Rename
     cdef int swmm_gage_rename(SWMM_Engine e, int idx, const char* newId)
+    # Resolved rainfall series
+    cdef int swmm_gage_get_rainfall_series_count(SWMM_Engine e, int idx, int* count)
+    cdef int swmm_gage_get_rainfall_series(SWMM_Engine e, int idx,
+                                           double* times, double* values,
+                                           int count)
+    cdef int swmm_gage_reload_rain_files(SWMM_Engine e)
 
 cdef extern from "openswmm_massbalance.h":
     cdef int swmm_get_runoff_continuity_error(SWMM_Engine e, double* error)
@@ -784,6 +832,46 @@ cdef extern from "openswmm_infrastructure.h":
                                     char* grate_type, int grate_buflen, double* open_area, double* splash_veloc)
     cdef int swmm_inlet_get_type(SWMM_Engine e, int idx, char* buf, int buflen)
     cdef int swmm_inlet_count(SWMM_Engine e)
+    # Full inlet-design surface (2026-09-05): every field of the [INLETS]
+    # grammar, including curb height, throat angle, combination inlets and
+    # custom capture curves.
+    cdef struct SWMM_InletDesign:
+        int    type
+        double grate_length
+        double grate_width
+        int    grate_type
+        double open_area
+        double splash_veloc
+        double curb_length
+        double curb_height
+        int    throat
+        double slot_length
+        double slot_width
+        char   curve_id[64]
+        int    curve_kind
+    cdef int swmm_inlet_get_design(SWMM_Engine e, int idx, SWMM_InletDesign* out)
+    cdef int swmm_inlet_set_design(SWMM_Engine e, int idx, const SWMM_InletDesign* design)
+    cdef int swmm_inlet_get_comment(SWMM_Engine e, int idx, char* buf, int buflen)
+    cdef int swmm_inlet_set_comment(SWMM_Engine e, int idx, const char* text)
+    # Inlet usage rows — one per placement, hosted by a conduit
+    # ([INLET_USAGE]) or by an inlet junction ([INLET_JUNCTIONS]).
+    cdef struct SWMM_InletUsage:
+        int    host_kind
+        int    host_idx
+        int    design_idx
+        int    capture_node_idx
+        int    num_inlets
+        double pct_clogged
+        double flow_limit
+        double local_depress
+        double local_width
+        int    placement
+    cdef int swmm_inlet_usage_count(SWMM_Engine e)
+    cdef int swmm_inlet_usage_find_link(SWMM_Engine e, int link_idx)
+    cdef int swmm_inlet_usage_find_node(SWMM_Engine e, int node_idx)
+    cdef int swmm_inlet_usage_get(SWMM_Engine e, int usage_idx, SWMM_InletUsage* out)
+    cdef int swmm_inlet_usage_set(SWMM_Engine e, const SWMM_InletUsage* usage, int* usage_idx)
+    cdef int swmm_inlet_usage_remove(SWMM_Engine e, int usage_idx)
     # LID controls
     cdef int swmm_lid_add(SWMM_Engine e, const char* id, int type)
     cdef int swmm_lid_set_surface(SWMM_Engine e, int idx, double storage, double roughness, double slope)
@@ -817,6 +905,10 @@ cdef extern from "openswmm_infrastructure.h":
     cdef const char* swmm_inlet_id(SWMM_Engine e, int idx)
     cdef int         swmm_lid_index(SWMM_Engine e, const char* id)
     cdef const char* swmm_lid_id(SWMM_Engine e, int idx)
+    # Renames (reference-updating)
+    cdef int         swmm_street_rename(SWMM_Engine e, int idx, const char* new_id)
+    cdef int         swmm_inlet_rename(SWMM_Engine e, int idx, const char* new_id)
+    cdef int         swmm_lid_rename(SWMM_Engine e, int idx, const char* new_id)
     # Transect detail getters / mutation
     cdef int swmm_transect_get_roughness(SWMM_Engine e, int idx, double* n_left, double* n_right, double* n_channel)
     cdef int swmm_transect_set_bank_stations(SWMM_Engine e, int idx, double left, double right)
@@ -940,6 +1032,7 @@ cdef extern from "openswmm_output.h":
     cdef const char* swmm_output_get_subcatch_id(SWMM_Output handle, int index)
     cdef const char* swmm_output_get_node_id(SWMM_Output handle, int index)
     cdef const char* swmm_output_get_link_id(SWMM_Output handle, int index)
+    cdef const char* swmm_output_get_pollut_id(SWMM_Output handle, int index)
     # Per-period results — disk-backed read into caller's float buffer.
     # nogil: pure C I/O, no Python objects touched.
     cdef int swmm_output_get_subcatch_result(SWMM_Output handle, int period, int var, float* values) nogil
@@ -1077,6 +1170,14 @@ cdef extern from "openswmm_edit.h":
                                 int* new_node_idx, int* new_link_idx)
     cdef int swmm_virtual_junction_fuse(SWMM_Engine e, int node_idx,
                                         int* surviving_link_idx)
+    cdef int swmm_conduit_split_inlet(SWMM_Engine e, int link_idx, double t,
+                                      const char* new_node_name,
+                                      const char* new_link_name,
+                                      const char* inlet_id,
+                                      const char* capture_node,
+                                      int* new_node_idx, int* new_link_idx)
+    cdef int swmm_inlet_junction_fuse(SWMM_Engine e, int node_idx,
+                                      int* surviving_link_idx)
 
 
 cdef extern from "openswmm_forcing.h":
@@ -1153,6 +1254,15 @@ cdef extern from "openswmm_climate.h":
     cdef int swmm_climate_set_wind_type(SWMM_Engine e, int type)
     cdef int swmm_climate_get_wind_monthly(SWMM_Engine e, double* buf, int count)
     cdef int swmm_climate_set_wind_monthly(SWMM_Engine e, const double* values, int count)
+    # Humidity
+    cdef int swmm_climate_get_humidity_type(SWMM_Engine e, int* type)
+    cdef int swmm_climate_set_humidity_type(SWMM_Engine e, int type)
+    cdef int swmm_climate_get_humidity_variable(SWMM_Engine e, int* var)
+    cdef int swmm_climate_set_humidity_variable(SWMM_Engine e, int var)
+    cdef int swmm_climate_get_humidity_monthly(SWMM_Engine e, double* buf, int count)
+    cdef int swmm_climate_set_humidity_monthly(SWMM_Engine e, const double* values, int count)
+    cdef int swmm_climate_get_humidity_timeseries(SWMM_Engine e, char* buf, int buflen)
+    cdef int swmm_climate_set_humidity_timeseries(SWMM_Engine e, const char* ts_id)
     # Snowmelt globals
     cdef int swmm_climate_get_snow_temp(SWMM_Engine e, double* divide_temp)
     cdef int swmm_climate_set_snow_temp(SWMM_Engine e, double divide_temp)
@@ -1248,6 +1358,144 @@ cdef extern from "openswmm_xsect.h":
                                              int n, double* out) nogil
 
 
+cdef extern from "openswmm_heat.h":
+
+    # Toggles
+    cdef int swmm_heat_get_enabled(SWMM_Engine e, int* enabled)
+    cdef int swmm_heat_get_module(SWMM_Engine e, int module, int* on)
+    cdef int swmm_heat_set_module(SWMM_Engine e, int module, int on)
+    # [RADIATIVE_FLUXES]
+    cdef int swmm_heat_get_radiative(SWMM_Engine e, int param, double* value)
+    cdef int swmm_heat_set_radiative(SWMM_Engine e, int param, double value)
+    cdef int swmm_heat_get_shortwave_mode(SWMM_Engine e, int* mode)
+    cdef int swmm_heat_set_shortwave_mode(SWMM_Engine e, int mode)
+    cdef int swmm_heat_set_shortwave_timeseries(SWMM_Engine e, const char* name)
+    cdef int swmm_heat_get_current_shortwave(SWMM_Engine e, double* wm2)
+    # [SOLAR_RADIATION]
+    cdef int swmm_heat_get_solar(SWMM_Engine e, int param, double* value)
+    cdef int swmm_heat_set_solar(SWMM_Engine e, int param, double value)
+    cdef int swmm_heat_get_solar_sited(SWMM_Engine e, int* sited)
+    # [CLOUD_COVER]
+    cdef int swmm_heat_get_cloud_configured(SWMM_Engine e, int* configured)
+    cdef int swmm_heat_get_cloud(SWMM_Engine e, int param, double* value)
+    cdef int swmm_heat_set_cloud(SWMM_Engine e, int param, double value)
+    cdef int swmm_heat_set_cloud_timeseries(SWMM_Engine e, const char* name)
+    cdef int swmm_heat_clear_cloud(SWMM_Engine e)
+    cdef int swmm_heat_get_current_cloud(SWMM_Engine e, double* fraction)
+    # [HEAT_SOURCES]
+    cdef int swmm_heat_source_count(SWMM_Engine e, int* count)
+    cdef int swmm_heat_get_source_temp(SWMM_Engine e, int source, double* temp_c)
+    cdef int swmm_heat_set_source_temp(SWMM_Engine e, int source, double temp_c)
+    cdef int swmm_heat_get_source_configured(SWMM_Engine e, int source, int* configured)
+    cdef int swmm_heat_clear_source_temp(SWMM_Engine e, int source)
+    cdef int swmm_heat_node_override_count(SWMM_Engine e, int* count)
+    cdef int swmm_heat_get_node_override(SWMM_Engine e, int index, int* source,
+                                          int* node, double* temp_c)
+    cdef int swmm_heat_set_node_override(SWMM_Engine e, int source, int node,
+                                          double temp_c)
+    cdef int swmm_heat_remove_node_override(SWMM_Engine e, int index)
+    cdef int swmm_heat_get_effective_source_temp(SWMM_Engine e, int source,
+                                                  int node, double* temp_c)
+
+
+cdef extern from "openswmm_water_age.h":
+
+    cdef int swmm_water_age_get_enabled(SWMM_Engine e, int* enabled)
+    cdef int swmm_water_age_get_global_source(SWMM_Engine e, int source, double* hours)
+    cdef int swmm_water_age_set_global_source(SWMM_Engine e, int source, double hours)
+    cdef int swmm_water_age_override_count(SWMM_Engine e, int* count)
+    cdef int swmm_water_age_get_override(SWMM_Engine e, int index, int* source,
+                                          int* node_index, double* hours)
+    cdef int swmm_water_age_set_override(SWMM_Engine e, int source, int node_index,
+                                          double hours)
+    cdef int swmm_water_age_remove_override(SWMM_Engine e, int source, int node_index)
+    cdef int swmm_water_age_save(SWMM_Engine e, const char* path)
+
+
+cdef extern from "openswmm_initial_quality.h":
+
+    cdef int swmm_init_quality_count(SWMM_Engine e)
+    cdef int swmm_init_quality_get(SWMM_Engine e, int entry_idx, int* is_link,
+                                    int* elem_idx, char* constituent_buf,
+                                    int constituent_len, double* value)
+    cdef int swmm_init_quality_set(SWMM_Engine e, int is_link, int elem_idx,
+                                    const char* constituent, double value)
+    cdef int swmm_init_quality_remove(SWMM_Engine e, int entry_idx)
+
+
+cdef extern from "openswmm_process_components.h":
+
+    cdef int swmm_process_component_count(SWMM_Engine e)
+    cdef int swmm_process_component_get(SWMM_Engine e, int idx,
+                                         char* id_buf, int id_len,
+                                         char* config_buf, int config_len,
+                                         char* resolved_buf, int resolved_len)
+    cdef int swmm_process_component_find(SWMM_Engine e, const char* id)
+    cdef int swmm_process_component_register(SWMM_Engine e, const char* id,
+                                              const char* config_path)
+    cdef int swmm_process_component_remove(SWMM_Engine e, int idx)
+
+
+cdef extern from "openswmm_reactions.h":
+
+    # Validation
+    cdef int swmm_reaction_validate_expression(SWMM_Engine e, int scope,
+                                                const char* expr, char* errbuf,
+                                                int buflen, int* col_out)
+    # Discovery
+    cdef int swmm_reaction_species_count(SWMM_Engine e)
+    cdef int swmm_reaction_species_get(SWMM_Engine e, int idx, char* name,
+                                        int name_len, int* is_wall, char* units,
+                                        int units_len, double* atol, double* rtol)
+    cdef int swmm_reaction_coeff_count(SWMM_Engine e)
+    cdef int swmm_reaction_coeff_get(SWMM_Engine e, int idx, char* name,
+                                      int name_len, int* is_param, double* value)
+    cdef int swmm_reaction_term_count(SWMM_Engine e)
+    cdef int swmm_reaction_term_get(SWMM_Engine e, int idx, char* name,
+                                     int name_len, char* expr, int expr_len)
+    cdef int swmm_reaction_expr_get(SWMM_Engine e, int scope, int species_idx,
+                                     int* form, char* expr, int expr_len)
+    cdef int swmm_reaction_option_get(SWMM_Engine e, const char* key, char* value,
+                                       int value_len)
+    # CRUD
+    cdef int swmm_reaction_species_add(SWMM_Engine e, const char* name, int is_wall,
+                                        const char* units, double atol, double rtol)
+    cdef int swmm_reaction_species_remove(SWMM_Engine e, int idx)
+    cdef int swmm_reaction_coeff_add(SWMM_Engine e, const char* name, int is_param,
+                                      double value)
+    cdef int swmm_reaction_coeff_set_value(SWMM_Engine e, int idx, double value)
+    cdef int swmm_reaction_coeff_remove(SWMM_Engine e, int idx)
+    cdef int swmm_reaction_term_add(SWMM_Engine e, const char* name, const char* expr)
+    cdef int swmm_reaction_term_set_expr(SWMM_Engine e, int idx, const char* expr)
+    cdef int swmm_reaction_term_remove(SWMM_Engine e, int idx)
+    cdef int swmm_reaction_expr_set(SWMM_Engine e, int scope, int species_idx,
+                                     int form, const char* expr)
+    cdef int swmm_reaction_option_set(SWMM_Engine e, const char* key, const char* value)
+    # Initial quality
+    cdef int swmm_reaction_init_global_get(SWMM_Engine e, int species_idx, double* value)
+    cdef int swmm_reaction_init_global_set(SWMM_Engine e, int species_idx, double value)
+    cdef int swmm_reaction_init_elem_count(SWMM_Engine e)
+    cdef int swmm_reaction_init_elem_get(SWMM_Engine e, int entry_idx, int* is_link,
+                                          int* elem_idx, int* species_idx, double* value)
+    cdef int swmm_reaction_init_elem_set(SWMM_Engine e, int is_link, int elem_idx,
+                                          int species_idx, double value)
+    cdef int swmm_reaction_init_elem_remove(SWMM_Engine e, int entry_idx)
+    # Whole-file text surface
+    cdef int swmm_reactions_serialize(SWMM_Engine e, char* buf, int buflen,
+                                       int* needed_len)
+    cdef int swmm_reactions_check_text(SWMM_Engine e, const char* text, char* errbuf,
+                                        int buflen)
+    cdef int swmm_reactions_apply_text(SWMM_Engine e, const char* text, char* errbuf,
+                                        int buflen)
+    cdef int swmm_reactions_save(SWMM_Engine e, const char* path_or_null)
+    # Static vocabulary (no engine handle)
+    cdef int swmm_reaction_hydvar_count()
+    cdef int swmm_reaction_hydvar_get(int idx, char* name, int name_len,
+                                       char* description, int desc_len)
+    cdef int swmm_reaction_function_count()
+    cdef int swmm_reaction_function_get(int idx, char* name, int name_len, int* arity)
+
+
 # --- Shared helpers ---
 cdef inline void _check(int code) except *:
     """Raise the right ``EngineError`` subclass for a non-zero ``code``.
diff --git a/python/openswmm/engine/_controls.pyx b/python/openswmm/engine/_controls.pyx
index 7bae44d9f..f2176493c 100644
--- a/python/openswmm/engine/_controls.pyx
+++ b/python/openswmm/engine/_controls.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Control rules (Pythonic v1 surface)
 ===================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Controls` view, reached via ``solver.controls``, behaves as
 a :class:`MutableSequence` of :class:`ControlRule` records over the
diff --git a/python/openswmm/engine/_datetime.pyx b/python/openswmm/engine/_datetime.pyx
index 5666235ac..9500d39b0 100644
--- a/python/openswmm/engine/_datetime.pyx
+++ b/python/openswmm/engine/_datetime.pyx
@@ -1,6 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # :author: Caleb Buahin
 # :copyright: Copyright (c) 2026 Caleb Buahin
-# :license: MIT
+# :license: Apache-2.0
 #
 # _datetime.pyx — Python bindings for the SWMM DateTime conversion C API.
 #
diff --git a/python/openswmm/engine/_edit.pyi b/python/openswmm/engine/_edit.pyi
index 61a7818f3..082c3ba20 100644
--- a/python/openswmm/engine/_edit.pyi
+++ b/python/openswmm/engine/_edit.pyi
@@ -1,15 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Model Editing — Object Deletion and Type Conversion
 ======================================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._edit`.
 """
 
 from __future__ import annotations
+from typing import Iterable
 
 from datetime import datetime
 
@@ -141,6 +158,11 @@ class ModelEditor:
         # Convert C2 conduit -> weir
         result = ed.convert_link("C2", LinkType.WEIR)
     """
+    def delete_nodes(self, keys: Iterable[int | str]) -> list[ImpactEntry]: ...
+    def delete_links(self, keys: Iterable[int | str]) -> list[ImpactEntry]: ...
+    def delete_subcatchments(self, keys: Iterable[int | str]) -> list[ImpactEntry]: ...
+    def delete_gages(self, keys: Iterable[int | str]) -> list[ImpactEntry]: ...
+
 
     def __init__(self, engine: object) -> None: ...
 
@@ -462,6 +484,59 @@ class ModelEditor:
         """
         ...
 
+    # =========================================================================
+    # Inlet junctions — split / fuse / flag (refactored engine only)
+    # =========================================================================
+
+    def set_node_inlet(self, id_or_idx: int | str, make_inlet: bool = True) -> None:
+        """Promote a node to an inlet junction, or demote it back.
+
+        @param id_or_idx: Node name or zero-based index.
+        @type id_or_idx: int or str
+        @param make_inlet: C{True} to promote, C{False} to demote.
+        @type make_inlet: bool
+        @raise KeyError: If C{id_or_idx} is a name and the node is not found.
+        @raise EngineError: On a violated usage rule or C API failure.
+        """
+        ...
+
+    def split_conduit_inlet(self, id_or_idx: int | str, t: float,
+                            new_node_name: str, new_link_name: str,
+                            inlet_id: str, capture_node: str) -> tuple[int, int]:
+        """Split a street conduit, inserting an inlet junction.
+
+        @param id_or_idx: Conduit name or zero-based index.
+        @type id_or_idx: int or str
+        @param t: Normalized split position, exclusive (0, 1).
+        @type t: float
+        @param new_node_name: Unique name for the inserted inlet junction.
+        @type new_node_name: str
+        @param new_link_name: Unique name for the new downstream conduit.
+        @type new_link_name: str
+        @param inlet_id: Name of an existing C{[INLETS]} design.
+        @type inlet_id: str
+        @param capture_node: Name of the receiving (underdrain) node.
+        @type capture_node: str
+        @return: C{(new_node_index, new_link_index)}.
+        @rtype: tuple[int, int]
+        @raise KeyError: If C{id_or_idx} is a name and the link is not found.
+        @raise EngineError: On invalid parameters or a rule failure.
+        """
+        ...
+
+    def fuse_inlet_junction(self, id_or_idx: int | str) -> int:
+        """Re-fuse the two conduits of an inlet junction into one.
+
+        @param id_or_idx: Node name or zero-based index.
+        @type id_or_idx: int or str
+        @return: Index of the surviving conduit AFTER deletions renumber.
+        @rtype: int
+        @raise KeyError: If C{id_or_idx} is a name and the node is not found.
+        @raise EngineError: If the node is not a two-conduit through junction,
+            or on C API failure.
+        """
+        ...
+
     # =========================================================================
     # Convenience counts
     # =========================================================================
diff --git a/python/openswmm/engine/_edit.pyx b/python/openswmm/engine/_edit.pyx
index f056e35cc..6b47bbe84 100644
--- a/python/openswmm/engine/_edit.pyx
+++ b/python/openswmm/engine/_edit.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Model Editing — Object Deletion and Type Conversion
 ======================================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`ModelEditor` class exposes the two editing capabilities added in
 engine 6.0.0:
@@ -248,10 +264,99 @@ cdef class ModelEditor:
         result = ed.convert_link("C2", LinkType.WEIR)
     """
 
-    cdef SWMM_Engine _handle
+    cdef object _owner
+
+    cdef SWMM_Engine _h(self) except NULL:
+        cdef size_t address = self._owner.handle
+        if not address:
+            from ._exceptions import BadHandleError
+            from ._enums import ErrorCode
+            raise BadHandleError(ErrorCode.BADHANDLE, "Engine has been destroyed")
+        return address
 
     def __init__(self, engine):
-        self._handle = engine.handle
+        self._owner = engine
+        self._h()
+
+    def delete_nodes(self, keys):
+        """Delete a batch using pre-edit names/indices; validate all before mutation.
+
+        Duplicates are ignored. Returns the aggregate cascade report and
+        invalidates existing element wrappers after a nonempty batch.
+        """
+        cdef vector[int] indices
+        for key in keys:
+            indices.push_back(self._node_idx(key))
+        cdef SWMM_ImpactReport report
+        report.entries = NULL
+        report.n_entries = 0
+        cdef int rc = swmm_node_delete_many(self._h(), indices.data(), indices.size(), &report)
+        if rc != 0:
+            swmm_impact_report_free(&report)
+            _check(rc)
+        if indices.size():
+            self._owner._bump_generation()
+        return _impact_report_to_list(&report)
+
+    def delete_links(self, keys):
+        """Delete a batch using pre-edit names/indices; validate all before mutation.
+
+        Duplicates are ignored. Returns the aggregate cascade report and
+        invalidates existing element wrappers after a nonempty batch.
+        """
+        cdef vector[int] indices
+        for key in keys:
+            indices.push_back(self._link_idx(key))
+        cdef SWMM_ImpactReport report
+        report.entries = NULL
+        report.n_entries = 0
+        cdef int rc = swmm_link_delete_many(self._h(), indices.data(), indices.size(), &report)
+        if rc != 0:
+            swmm_impact_report_free(&report)
+            _check(rc)
+        if indices.size():
+            self._owner._bump_generation()
+        return _impact_report_to_list(&report)
+
+    def delete_subcatchments(self, keys):
+        """Delete a batch using pre-edit names/indices; validate all before mutation.
+
+        Duplicates are ignored. Returns the aggregate cascade report and
+        invalidates existing element wrappers after a nonempty batch.
+        """
+        cdef vector[int] indices
+        for key in keys:
+            indices.push_back(self._subcatch_idx(key))
+        cdef SWMM_ImpactReport report
+        report.entries = NULL
+        report.n_entries = 0
+        cdef int rc = swmm_subcatch_delete_many(self._h(), indices.data(), indices.size(), &report)
+        if rc != 0:
+            swmm_impact_report_free(&report)
+            _check(rc)
+        if indices.size():
+            self._owner._bump_generation()
+        return _impact_report_to_list(&report)
+
+    def delete_gages(self, keys):
+        """Delete a batch using pre-edit names/indices; validate all before mutation.
+
+        Duplicates are ignored. Returns the aggregate cascade report and
+        invalidates existing element wrappers after a nonempty batch.
+        """
+        cdef vector[int] indices
+        for key in keys:
+            indices.push_back(self._gage_idx(key))
+        cdef SWMM_ImpactReport report
+        report.entries = NULL
+        report.n_entries = 0
+        cdef int rc = swmm_gage_delete_many(self._h(), indices.data(), indices.size(), &report)
+        if rc != 0:
+            swmm_impact_report_free(&report)
+            _check(rc)
+        if indices.size():
+            self._owner._bump_generation()
+        return _impact_report_to_list(&report)
 
     # =========================================================================
     # Internal index resolution helpers
@@ -262,7 +367,7 @@ cdef class ModelEditor:
         cdef int ni
         if isinstance(id_or_idx, str):
             nb = id_or_idx.encode('utf-8')
-            ni = swmm_node_index(self._handle, nb)
+            ni = swmm_node_index(self._h(), nb)
             if ni < 0:
                 raise ElementNotFoundError(id_or_idx)
             return ni
@@ -273,7 +378,7 @@ cdef class ModelEditor:
         cdef int li
         if isinstance(id_or_idx, str):
             lb = id_or_idx.encode('utf-8')
-            li = swmm_link_index(self._handle, lb)
+            li = swmm_link_index(self._h(), lb)
             if li < 0:
                 raise ElementNotFoundError(id_or_idx)
             return li
@@ -284,7 +389,7 @@ cdef class ModelEditor:
         cdef int si
         if isinstance(id_or_idx, str):
             sb = id_or_idx.encode('utf-8')
-            si = swmm_subcatch_index(self._handle, sb)
+            si = swmm_subcatch_index(self._h(), sb)
             if si < 0:
                 raise ElementNotFoundError(id_or_idx)
             return si
@@ -295,7 +400,7 @@ cdef class ModelEditor:
         cdef int gi
         if isinstance(id_or_idx, str):
             gb = id_or_idx.encode('utf-8')
-            gi = swmm_gage_index(self._handle, gb)
+            gi = swmm_gage_index(self._h(), gb)
             if gi < 0:
                 raise ElementNotFoundError(id_or_idx)
             return gi
@@ -306,7 +411,7 @@ cdef class ModelEditor:
         cdef int ti
         if isinstance(id_or_idx, str):
             tb = id_or_idx.encode('utf-8')
-            ti = swmm_table_index(self._handle, tb)
+            ti = swmm_table_index(self._h(), tb)
             if ti < 0:
                 raise ElementNotFoundError(id_or_idx)
             return ti
@@ -317,7 +422,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_pollutant_index(self._handle, b)
+            i = swmm_pollutant_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -328,7 +433,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_pattern_index(self._handle, b)
+            i = swmm_pattern_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -339,7 +444,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_aquifer_index(self._handle, b)
+            i = swmm_aquifer_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -350,7 +455,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_snowpack_index(self._handle, b)
+            i = swmm_snowpack_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -361,7 +466,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_lid_index(self._handle, b)
+            i = swmm_lid_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -372,7 +477,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_street_index(self._handle, b)
+            i = swmm_street_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -383,7 +488,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_inlet_index(self._handle, b)
+            i = swmm_inlet_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -394,7 +499,7 @@ cdef class ModelEditor:
         cdef int i
         if isinstance(id_or_idx, str):
             b = id_or_idx.encode('utf-8')
-            i = swmm_landuse_index(self._handle, b)
+            i = swmm_landuse_index(self._h(), b)
             if i < 0:
                 raise ElementNotFoundError(id_or_idx)
             return i
@@ -419,7 +524,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_node_analyze_impact(self._handle, idx, &report))
+        _check(swmm_node_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_link_impact(self, id_or_idx) -> list:
@@ -437,7 +542,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_link_analyze_impact(self._handle, idx, &report))
+        _check(swmm_link_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_subcatch_impact(self, id_or_idx) -> list:
@@ -457,7 +562,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_subcatch_analyze_impact(self._handle, idx, &report))
+        _check(swmm_subcatch_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_gage_impact(self, id_or_idx) -> list:
@@ -475,7 +580,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_gage_analyze_impact(self._handle, idx, &report))
+        _check(swmm_gage_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_table_impact(self, id_or_idx) -> list:
@@ -493,7 +598,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_table_analyze_impact(self._handle, idx, &report))
+        _check(swmm_table_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_transect_impact(self, int idx) -> list:
@@ -509,7 +614,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_transect_analyze_impact(self._handle, idx, &report))
+        _check(swmm_transect_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_pollutant_impact(self, id_or_idx) -> list:
@@ -527,7 +632,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_pollutant_analyze_impact(self._handle, idx, &report))
+        _check(swmm_pollutant_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_pattern_impact(self, id_or_idx) -> list:
@@ -545,7 +650,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_pattern_analyze_impact(self._handle, idx, &report))
+        _check(swmm_pattern_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_aquifer_impact(self, id_or_idx) -> list:
@@ -562,7 +667,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_aquifer_analyze_impact(self._handle, idx, &report))
+        _check(swmm_aquifer_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_snowpack_impact(self, id_or_idx) -> list:
@@ -579,7 +684,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_snowpack_analyze_impact(self._handle, idx, &report))
+        _check(swmm_snowpack_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_lid_impact(self, id_or_idx) -> list:
@@ -597,7 +702,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_lid_analyze_impact(self._handle, idx, &report))
+        _check(swmm_lid_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_street_impact(self, id_or_idx) -> list:
@@ -614,7 +719,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_street_analyze_impact(self._handle, idx, &report))
+        _check(swmm_street_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_inlet_impact(self, id_or_idx) -> list:
@@ -632,7 +737,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_inlet_analyze_impact(self._handle, idx, &report))
+        _check(swmm_inlet_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_landuse_impact(self, id_or_idx) -> list:
@@ -649,7 +754,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_landuse_analyze_impact(self._handle, idx, &report))
+        _check(swmm_landuse_analyze_impact(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def analyze_hydrograph_impact(self, str uh_name) -> list:
@@ -668,7 +773,7 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_hydrograph_analyze_impact(self._handle, nb, &report))
+        _check(swmm_hydrograph_analyze_impact(self._h(), nb, &report))
         return _impact_report_to_list(&report)
 
     # =========================================================================
@@ -697,7 +802,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_node_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_node_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_link(self, id_or_idx) -> list:
@@ -720,7 +826,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_link_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_link_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_subcatch(self, id_or_idx) -> list:
@@ -745,7 +852,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_subcatch_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_subcatch_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_gage(self, id_or_idx) -> list:
@@ -765,7 +873,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_gage_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_gage_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_table(self, id_or_idx) -> list:
@@ -789,7 +898,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_table_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_table_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_transect(self, int idx) -> list:
@@ -810,7 +920,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_transect_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_transect_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_pollutant(self, id_or_idx) -> list:
@@ -834,7 +945,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_pollutant_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_pollutant_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_pattern(self, id_or_idx) -> list:
@@ -858,7 +970,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_pattern_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_pattern_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_aquifer(self, id_or_idx) -> list:
@@ -880,7 +993,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_aquifer_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_aquifer_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_snowpack(self, id_or_idx) -> list:
@@ -902,7 +1016,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_snowpack_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_snowpack_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_lid(self, id_or_idx) -> list:
@@ -925,7 +1040,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_lid_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_lid_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_street(self, id_or_idx) -> list:
@@ -948,7 +1064,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_street_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_street_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_inlet(self, id_or_idx) -> list:
@@ -971,7 +1088,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_inlet_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_inlet_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_landuse(self, id_or_idx) -> list:
@@ -993,7 +1111,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_landuse_delete(self._handle, idx, &report))
+        self._owner._bump_generation()
+        _check(swmm_landuse_delete(self._h(), idx, &report))
         return _impact_report_to_list(&report)
 
     def delete_hydrograph(self, str uh_name) -> list:
@@ -1014,7 +1133,8 @@ cdef class ModelEditor:
         cdef SWMM_ImpactReport report
         report.entries = NULL
         report.n_entries = 0
-        _check(swmm_hydrograph_delete(self._handle, nb, &report))
+        self._owner._bump_generation()
+        _check(swmm_hydrograph_delete(self._h(), nb, &report))
         return _impact_report_to_list(&report)
 
     # =========================================================================
@@ -1052,7 +1172,8 @@ cdef class ModelEditor:
         res.n_cleared = 0
         res.warnings = NULL
         res.n_warnings = 0
-        _check(swmm_node_convert(self._handle, idx, new_type, &res))
+        self._owner._bump_generation()
+        _check(swmm_node_convert(self._h(), idx, new_type, &res))
         return _conversion_result_to_py(&res)
 
     def convert_link(self, id_or_idx, int new_type) -> ConversionResult:
@@ -1084,7 +1205,8 @@ cdef class ModelEditor:
         res.n_cleared = 0
         res.warnings = NULL
         res.n_warnings = 0
-        _check(swmm_link_convert(self._handle, idx, new_type, &res))
+        self._owner._bump_generation()
+        _check(swmm_link_convert(self._h(), idx, new_type, &res))
         return _conversion_result_to_py(&res)
 
     # =========================================================================
@@ -1109,7 +1231,7 @@ cdef class ModelEditor:
         @raise EngineError: On a violated usage rule or C API failure.
         """
         cdef int idx = self._node_idx(id_or_idx)
-        _check(swmm_node_set_virtual(self._handle, idx, 1 if make_virtual else 0))
+        _check(swmm_node_set_virtual(self._h(), idx, 1 if make_virtual else 0))
 
     def split_conduit(self, id_or_idx, double t, str new_node_name,
                       str new_link_name, bint make_virtual=False) -> tuple:
@@ -1146,7 +1268,8 @@ cdef class ModelEditor:
         cdef bytes link_b = new_link_name.encode('utf-8')
         cdef int new_node = -1
         cdef int new_link = -1
-        _check(swmm_conduit_split(self._handle, idx, t, node_b, link_b,
+        self._owner._bump_generation()
+        _check(swmm_conduit_split(self._h(), idx, t, node_b, link_b,
                                   1 if make_virtual else 0,
                                   &new_node, &new_link))
         return (new_node, new_link)
@@ -1171,7 +1294,98 @@ cdef class ModelEditor:
         """
         cdef int idx = self._node_idx(id_or_idx)
         cdef int surviving = -1
-        _check(swmm_virtual_junction_fuse(self._handle, idx, &surviving))
+        self._owner._bump_generation()
+        _check(swmm_virtual_junction_fuse(self._h(), idx, &surviving))
+        return surviving
+
+    def set_node_inlet(self, id_or_idx, bint make_inlet=True) -> None:
+        """Promote a node to an inlet junction, or demote it back.
+
+        An inlet junction is a virtual junction on a STREET conduit pair that
+        also carries a street inlet (INP C{[INLET_JUNCTIONS]}). Promotion runs
+        the virtual-junction rules plus the street shape rule (623) B{before}
+        changing anything, and makes the node virtual first if it is not
+        already; on a violated rule the node is left exactly as it was.
+        Demotion clears the flag and deletes the node's inlet-usage row,
+        leaving a plain virtual junction.
+
+        Give the node a usage row (C{infrastructure.inlet_usages.set} with
+        C{host_kind=InletHostKind.NODE}) before running the model — an inlet
+        junction without one fails validation.
+
+        @param id_or_idx: Node name (C{str}) or zero-based index (C{int}).
+        @type id_or_idx: int or str
+        @param make_inlet: C{True} to promote, C{False} to demote.
+        @type make_inlet: bool
+        @raise KeyError: If C{id_or_idx} is a name and the node is not found.
+        @raise EngineError: On a violated usage rule or C API failure.
+        """
+        cdef int idx = self._node_idx(id_or_idx)
+        _check(swmm_node_set_inlet(self._h(), idx, 1 if make_inlet else 0))
+
+    def split_conduit_inlet(self, id_or_idx, double t, str new_node_name,
+                            str new_link_name, str inlet_id,
+                            str capture_node) -> tuple:
+        """Split a street conduit, inserting an B{inlet junction}.
+
+        L{split_conduit} with C{make_virtual=True}, followed by the inlet
+        promotion and the usage row in one step: the inserted node captures
+        gutter flow with design C{inlet_id} and delivers it to
+        C{capture_node}. The usage row takes the C{[INLET_USAGE]} defaults
+        (one inlet, no clogging, no flow limit, no local depression,
+        AUTOMATIC placement); edit it afterwards through
+        C{infrastructure.inlet_usages}.
+
+        @param id_or_idx: Conduit name (C{str}) or zero-based index (C{int}).
+        @type id_or_idx: int or str
+        @param t: Normalized split position, exclusive (0, 1).
+        @type t: float
+        @param new_node_name: Unique name for the inserted inlet junction.
+        @type new_node_name: str
+        @param new_link_name: Unique name for the new downstream conduit.
+        @type new_link_name: str
+        @param inlet_id: Name of an existing C{[INLETS]} design.
+        @type inlet_id: str
+        @param capture_node: Name of the receiving (underdrain) node.
+        @type capture_node: str
+        @return: C{(new_node_index, new_link_index)}.
+        @rtype: tuple[int, int]
+        @raise KeyError: If C{id_or_idx} is a name and the link is not found.
+        @raise EngineError: On invalid C{t}, duplicate names, an unknown
+            design or capture node, a non-STREET conduit, or a rule failure.
+        """
+        cdef int idx = self._link_idx(id_or_idx)
+        cdef bytes node_b = new_node_name.encode('utf-8')
+        cdef bytes link_b = new_link_name.encode('utf-8')
+        cdef bytes inlet_b = inlet_id.encode('utf-8')
+        cdef bytes cap_b = capture_node.encode('utf-8')
+        cdef int new_node = -1
+        cdef int new_link = -1
+        self._owner._bump_generation()
+        _check(swmm_conduit_split_inlet(self._h(), idx, t, node_b, link_b,
+                                        inlet_b, cap_b, &new_node, &new_link))
+        return (new_node, new_link)
+
+    def fuse_inlet_junction(self, id_or_idx) -> int:
+        """Re-fuse the two conduits of an inlet junction into one.
+
+        Inverse of L{split_conduit_inlet}: the node's inlet-usage row is
+        removed, then the pair is fused exactly as
+        L{fuse_virtual_junction} does.
+
+        @param id_or_idx: Node name (C{str}) or zero-based index (C{int}) of
+            the inlet junction.
+        @type id_or_idx: int or str
+        @return: Index of the surviving conduit AFTER deletions renumber.
+        @rtype: int
+        @raise KeyError: If C{id_or_idx} is a name and the node is not found.
+        @raise EngineError: If the node is not a two-conduit through
+            junction, or on C API failure.
+        """
+        cdef int idx = self._node_idx(id_or_idx)
+        cdef int surviving = -1
+        self._owner._bump_generation()
+        _check(swmm_inlet_junction_fuse(self._h(), idx, &surviving))
         return surviving
 
     # =========================================================================
@@ -1185,7 +1399,7 @@ cdef class ModelEditor:
         @return: Node count.
         @rtype: int
         """
-        return swmm_node_count(self._handle)
+        return swmm_node_count(self._h())
 
     @property
     def link_count(self) -> int:
@@ -1194,7 +1408,7 @@ cdef class ModelEditor:
         @return: Link count.
         @rtype: int
         """
-        return swmm_link_count(self._handle)
+        return swmm_link_count(self._h())
 
     @property
     def subcatch_count(self) -> int:
@@ -1203,7 +1417,7 @@ cdef class ModelEditor:
         @return: Subcatchment count.
         @rtype: int
         """
-        return swmm_subcatch_count(self._handle)
+        return swmm_subcatch_count(self._h())
 
     @property
     def gage_count(self) -> int:
@@ -1212,7 +1426,7 @@ cdef class ModelEditor:
         @return: Gage count.
         @rtype: int
         """
-        return swmm_gage_count(self._handle)
+        return swmm_gage_count(self._h())
 
     @property
     def table_count(self) -> int:
@@ -1221,7 +1435,7 @@ cdef class ModelEditor:
         @return: Table count.
         @rtype: int
         """
-        return swmm_table_count(self._handle)
+        return swmm_table_count(self._h())
 
     # =========================================================================
     # Typed time-control properties (datetime)
@@ -1235,13 +1449,13 @@ cdef class ModelEditor:
         @raise EngineError: On C API failure.
         """
         cdef double v = 0.0
-        _check(swmm_options_get_start_date(self._handle, &v))
+        _check(swmm_options_get_start_date(self._h(), &v))
         return oadate_to_datetime(v)
 
     @start_datetime.setter
     def start_datetime(self, value: datetime) -> None:
         cdef double v = datetime_to_oadate(value)
-        _check(swmm_options_set_start_date(self._handle, v))
+        _check(swmm_options_set_start_date(self._h(), v))
 
     @property
     def end_datetime(self) -> datetime:
@@ -1251,13 +1465,13 @@ cdef class ModelEditor:
         @raise EngineError: On C API failure.
         """
         cdef double v = 0.0
-        _check(swmm_options_get_end_date(self._handle, &v))
+        _check(swmm_options_get_end_date(self._h(), &v))
         return oadate_to_datetime(v)
 
     @end_datetime.setter
     def end_datetime(self, value: datetime) -> None:
         cdef double v = datetime_to_oadate(value)
-        _check(swmm_options_set_end_date(self._handle, v))
+        _check(swmm_options_set_end_date(self._h(), v))
 
     @property
     def report_start_datetime(self) -> datetime:
@@ -1267,10 +1481,17 @@ cdef class ModelEditor:
         @raise EngineError: On C API failure.
         """
         cdef double v = 0.0
-        _check(swmm_options_get_report_start(self._handle, &v))
+        _check(swmm_options_get_report_start(self._h(), &v))
         return oadate_to_datetime(v)
 
     @report_start_datetime.setter
     def report_start_datetime(self, value: datetime) -> None:
         cdef double v = datetime_to_oadate(value)
-        _check(swmm_options_set_report_start(self._handle, v))
+        _check(swmm_options_set_report_start(self._h(), v))
+
+from libcpp.vector cimport vector
+cdef extern from "openswmm/engine/openswmm_edit.h":
+    int swmm_node_delete_many(SWMM_Engine, const int*, int, SWMM_ImpactReport*)
+    int swmm_link_delete_many(SWMM_Engine, const int*, int, SWMM_ImpactReport*)
+    int swmm_subcatch_delete_many(SWMM_Engine, const int*, int, SWMM_ImpactReport*)
+    int swmm_gage_delete_many(SWMM_Engine, const int*, int, SWMM_ImpactReport*)
diff --git a/python/openswmm/engine/_enums.py b/python/openswmm/engine/_enums.py
index 7616cd054..1ab35d08d 100644
--- a/python/openswmm/engine/_enums.py
+++ b/python/openswmm/engine/_enums.py
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Enumerations
 ============
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Integer-backed enums mirroring the C API enum definitions in
 ``openswmm_engine.h``. These are pure Python (no Cython required)
@@ -552,6 +568,18 @@ class AquiferParam(IntEnum):
     UPPER_MOISTURE = 11
 
 
+class GwfType(IntEnum):
+    """Which of a subcatchment's two C{[GWF]} custom groundwater flow
+    expressions (C{Subcatchments.get_gwf_expression} / C{set_gwf_expression}).
+
+    @cvar LATERAL: Added to the standard A1/A2/A3 lateral groundwater flow.
+    @cvar DEEP: Replaces the standard deep-percolation term.
+    """
+
+    LATERAL = 0
+    DEEP = 1
+
+
 # =============================================================================
 # Output variables
 # =============================================================================
@@ -734,6 +762,8 @@ class RunoffTotal(IntEnum):
     SNOWREMOV = 4
     INITSTORE = 5
     FINALSTORE = 6
+    INITSNOW = 7
+    FINALSNOW = 8
 
 
 class RoutingTotal(IntEnum):
@@ -752,8 +782,8 @@ class RoutingTotal(IntEnum):
     @cvar FINAL_STORAGE: Final network storage.
     @cvar FORCING_INFLOW: Runtime-API forced lateral inflow (e.g.
         flow injected via Nodes.set_lateral_inflow / transient
-        ForcingData). Distinct from EXTERNAL which only counts INP
-        [INFLOWS]-derived inflow.
+        ForcingData). A subset of EXTERNAL, which also includes authored
+        inflows, interface-file inflow, and 2D coupling inflow.
     """
 
     DRY_WEATHER = 0
@@ -768,6 +798,8 @@ class RoutingTotal(IntEnum):
     INIT_STORAGE = 9
     FINAL_STORAGE = 10
     FORCING_INFLOW = 11
+    LINK_GW_INFLOW = 13
+    COUPLING_OUT = 12
 
 
 # =============================================================================
@@ -833,6 +865,11 @@ class ForcingType(IntEnum):
     SUBCATCH_SNOWFALL = 10
     CLIMATE_EVAP = 11
     LINK_QUALITY = 12
+    ELEM_AIR_TEMPERATURE = 13
+    ELEM_HUMIDITY = 14
+    ELEM_WIND_SPEED = 15
+    ELEM_SHORTWAVE = 16
+    LINK_SEEPAGE = 17
 
 
 class ForcingPersist(IntEnum):
@@ -890,6 +927,47 @@ class SurfaceBoundaryType(IntEnum):
     RATING_CURVE = 4
 
 
+class SurfaceInfilMethod(IntEnum):
+    """Per-cell 2D infiltration method (C{[2D_INFILTRATION*]}).
+
+    Mirrors the C{SWMM_INFIL2D_*} codes in C{openswmm_infil2d.h} and
+    C{openswmm::InfilModel}. Distinct from the 1D L{InfilModel} only in that
+    it also carries C{CONSTANT}, which has no legacy C{[INFILTRATION]} token.
+
+    @cvar HORTON: Original Horton model.
+    @cvar MOD_HORTON: Modified Horton model (linear decay).
+    @cvar GREEN_AMPT: Green-Ampt model.
+    @cvar MOD_GREEN_AMPT: Modified Green-Ampt model (M{F} not reset).
+    @cvar CURVE_NUMBER: SCS Curve Number model.
+    @cvar CONSTANT: Constant rate, capacity-bounded. 2D only.
+    """
+
+    HORTON = 0
+    MOD_HORTON = 1
+    GREEN_AMPT = 2
+    MOD_GREEN_AMPT = 3
+    CURVE_NUMBER = 4
+    CONSTANT = 5
+
+
+class SurfaceInfilDest(IntEnum):
+    """Destination of water infiltrated out of a 2D mesh cell.
+
+    Mirrors the C{SWMM_INFIL2D_DEST_*} codes in C{openswmm_infil2d.h} and
+    C{openswmm::twoD::Infil2DDest}. Only L{LOST} is routed in this release
+    (plan decision D-I4); the other two parse so the grammar is stable and
+    are rejected at validation.
+
+    @cvar LOST: Leaves the domain; booked to the C{infil_out} ledger row.
+    @cvar SUBCATCH_AQUIFER: Reserved — legacy subcatchment aquifer.
+    @cvar AQUIFER_2D: Reserved — the two-zone 2D groundwater kernel.
+    """
+
+    LOST = 0
+    SUBCATCH_AQUIFER = 1
+    AQUIFER_2D = 2
+
+
 # =============================================================================
 # Object references (model editing)
 # =============================================================================
@@ -916,6 +994,21 @@ class RefType(IntEnum):
     TABLE = 4
     TRANSECT = 5
     INLET_USAGE = 6
+    EXT_INFLOW = 7
+    DWF_INFLOW = 8
+    RDII_ASSIGN = 9
+    TREATMENT = 10
+    LID_USAGE = 11
+    SNOWPACK = 12
+    HYDROGRAPH = 13
+    POLLUTANT = 14
+    PATTERN = 15
+    AQUIFER = 16
+    LID_CONTROL = 17
+    STREET = 18
+    INLET_DESIGN = 19
+    LANDUSE = 20
+    CONTROL_RULE = 21
 
 
 class TableType(IntEnum):
@@ -982,6 +1075,9 @@ class FilePathRole(IntEnum):
     HOTSTART_SAVE = 8
     RAINGAGE_DATA = 9
     TIMESERIES_DATA = 10
+    MESH_2D = 11
+    OUTPUT_2D = 12
+    LID_REPORT = 13
 
 
 class UserFlagType(IntEnum):
@@ -999,3 +1095,486 @@ class UserFlagType(IntEnum):
     INTEGER = 1
     REAL = 2
     STRING = 3
+
+
+# =============================================================================
+# Transport processes — heat, water age, reactions
+# =============================================================================
+
+class HeatFluxModule(IntEnum):
+    """Independently toggleable heat-flux modules (C{[HEAT_FLUXES]}).
+
+    Mirrors C{SWMM_HeatFluxModule} in C{openswmm_heat.h}.
+
+    @cvar SURFACE_EXCHANGE: Latent + sensible surface exchange.
+    @cvar RADIATIVE_EXCHANGE: Shortwave + longwave radiation.
+    @cvar LAYER_CONDUCTION: LID vertical conduction.
+    """
+
+    SURFACE_EXCHANGE = 0
+    RADIATIVE_EXCHANGE = 1
+    LAYER_CONDUCTION = 2
+
+
+class HeatShortwaveMode(IntEnum):
+    """Where incoming shortwave radiation comes from.
+
+    Mirrors C{SWMM_HeatShortwaveMode}. The three are mutually exclusive in
+    effect — exactly one is read — but switching modes does B{not} erase the
+    other modes' stored settings.
+
+    @cvar CONSTANT: Fixed W/m2, from C{HeatRadiativeParam.SHORTWAVE}.
+    @cvar TIMESERIES: A measured record bound by name.
+    @cvar COMPUTED: Solar position + Bird clear-sky model. Requires both
+        latitude and longitude to have been set explicitly.
+    """
+
+    CONSTANT = 0
+    TIMESERIES = 1
+    COMPUTED = 2
+
+
+class HeatRadiativeParam(IntEnum):
+    """C{[RADIATIVE_FLUXES]} scalar parameters.
+
+    Mirrors C{SWMM_HeatRadiativeParam}.
+
+    @cvar SHORTWAVE: Incoming shortwave, W/m2. Writable only in
+        C{HeatShortwaveMode.CONSTANT}.
+    @cvar ALBEDO: Water reflectance Rs, [0, 1].
+    @cvar SHADE_FACTOR: Shading fraction fs, [0, 1].
+    @cvar SKY_VIEW: Sky-view fraction fsky, [0, 1].
+    @cvar EMISS_WATER: Water emissivity, [0, 1].
+    @cvar EMISS_LANDCOVER: Land-cover emissivity, [0, 1].
+    @cvar ATM_EMISS_COEFF: Brunt atmospheric-emissivity coefficient, [0, 1].
+    @cvar LW_REFLECTION: Longwave reflection RL, [0, 1].
+    """
+
+    SHORTWAVE = 0
+    ALBEDO = 1
+    SHADE_FACTOR = 2
+    SKY_VIEW = 3
+    EMISS_WATER = 4
+    EMISS_LANDCOVER = 5
+    ATM_EMISS_COEFF = 6
+    LW_REFLECTION = 7
+
+
+class HeatSolarParam(IntEnum):
+    """C{[SOLAR_RADIATION]} parameters, consulted under
+    C{HeatShortwaveMode.COMPUTED} only.
+
+    Mirrors C{SWMM_HeatSolarParam}.
+
+    @cvar LATITUDE: Degrees, +N, [-90, 90].
+    @cvar LONGITUDE: Degrees, +E, [-180, 180].
+    @cvar TIMEZONE: Hours from UTC, +E.
+    @cvar ELEVATION: Metres, [-500, 9000]; below sea level is legal.
+    @cvar TURBIDITY_380: Bird aerosol optical depth at 380 nm.
+    @cvar TURBIDITY_500: Bird aerosol optical depth at 500 nm.
+    @cvar PRECIP_WATER: Precipitable water, cm.
+    @cvar OZONE: Ozone column, cm.
+    @cvar GROUND_ALBEDO: B{Land} albedo [0, 1] — not the water's
+        C{HeatRadiativeParam.ALBEDO}.
+    """
+
+    LATITUDE = 0
+    LONGITUDE = 1
+    TIMEZONE = 2
+    ELEVATION = 3
+    TURBIDITY_380 = 4
+    TURBIDITY_500 = 5
+    PRECIP_WATER = 6
+    OZONE = 7
+    GROUND_ALBEDO = 8
+
+
+class HeatCloudParam(IntEnum):
+    """C{[CLOUD_COVER]} parameters.
+
+    Mirrors C{SWMM_HeatCloudParam}.
+
+    @cvar FRACTION: Cloud fraction C, [0, 1] — a fraction, not a percent.
+    @cvar SW_ATTEN_K: Kasten-Czeplak shortwave attenuation k.
+    @cvar SW_ATTEN_N: Kasten-Czeplak shortwave attenuation n.
+    @cvar LW_CLOUD_K: Bolz longwave cloud coefficient k_lw.
+    """
+
+    FRACTION = 0
+    SW_ATTEN_K = 1
+    SW_ATTEN_N = 2
+    LW_CLOUD_K = 3
+
+
+class HeatSourceKind(IntEnum):
+    """C{[HEAT_SOURCES]} water sources.
+
+    Mirrors C{SWMM_HeatSourceKind} (and C{openswmm::HeatSource}). Only
+    C{DWF} and C{EXTERNAL_INFLOW} accept node-scope overrides — the H1 scope
+    rule, refused rather than silently deferred.
+
+    @cvar RAINFALL: Washoff runoff.
+    @cvar DWF: Dry-weather flow.
+    @cvar GW: Groundwater.
+    @cvar RDII: Rainfall-derived infiltration and inflow.
+    @cvar EXTERNAL_INFLOW: C{[INFLOWS]}.
+    @cvar IFACE: Interface file.
+    @cvar INITIAL_STATE: Water present at t = 0.
+    """
+
+    RAINFALL = 0
+    DWF = 1
+    GW = 2
+    RDII = 3
+    EXTERNAL_INFLOW = 4
+    IFACE = 5
+    INITIAL_STATE = 6
+
+
+class WaterAgeSource(IntEnum):
+    """C{[WATER_AGE_SOURCES]} pathways.
+
+    Mirrors C{SWMM_WaterAgeSource}. The C enum's trailing C{COUNT = 7}
+    sentinel is deliberately not reproduced — C{len(WaterAgeSource)} is the
+    count. Only C{DWF} and C{EXTERNAL_INFLOW} accept node-scope overrides
+    (the A1a scope rule).
+
+    @cvar RAINFALL: Rainfall-derived water.
+    @cvar DWF: Dry-weather flow.
+    @cvar GW: Groundwater.
+    @cvar RDII: Rainfall-derived infiltration and inflow.
+    @cvar EXTERNAL_INFLOW: C{[INFLOWS]}.
+    @cvar IFACE: Interface file.
+    @cvar INITIAL_STATE: Water present at t = 0.
+    """
+
+    RAINFALL = 0
+    DWF = 1
+    GW = 2
+    RDII = 3
+    EXTERNAL_INFLOW = 4
+    IFACE = 5
+    INITIAL_STATE = 6
+
+
+class ReactionScope(IntEnum):
+    """Identifier-resolution vocabulary for reaction-expression validation.
+
+    Mirrors the C{SWMM_RXN_SCOPE_*} macros in C{openswmm_reactions.h}.
+
+    @cvar TERM: Intermediate-term scope. References to B{all} terms resolve;
+        the forward-only ordering rule is enforced at file-apply time, where
+        ordinal position exists.
+    @cvar PIPE: Conduit (flowing) reaction scope.
+    @cvar TANK: Storage-unit (mixed) reaction scope.
+    """
+
+    TERM = 0
+    PIPE = 1
+    TANK = 2
+
+
+class ReactionExprForm(IntEnum):
+    """Form of a species' reaction expression.
+
+    Mirrors the C{SWMM_RXN_FORM_*} macros (and C{ReactionExprForm}).
+
+    @cvar NONE: No expression in this scope; also the value that B{clears}
+        one through C{Reactions.set_expression}.
+    @cvar RATE: Rate expression, C{dC/dt = f(...)}.
+    @cvar EQUIL: Equilibrium expression, C{0 = f(...)}.
+    @cvar FORMULA: Explicit formula, C{C = f(...)}.
+    """
+
+    NONE = 0
+    RATE = 1
+    EQUIL = 2
+    FORMULA = 3
+
+
+class InletType(IntEnum):
+    """Street-inlet design type (C{[INLETS]} token 2).
+
+    Mirrors C{SWMM_InletType}. C{COMBO} has no keyword in the .inp grammar:
+    legacy encodes a combination inlet as a C{GRATE} line and a C{CURB} line
+    sharing one name, which the parser merges into a single COMBO design.
+
+    @cvar GRATE: Grate inlet in the gutter.
+    @cvar CURB: Curb-opening inlet.
+    @cvar COMBO: Grate plus curb opening (written back as two lines).
+    @cvar SLOTTED: Slotted drain.
+    @cvar DROP_GRATE: Grate inlet in a drainage channel (RECT_OPEN/TRAPEZOIDAL).
+    @cvar DROP_CURB: Curb opening in a drainage channel; always solved on-sag.
+    @cvar CUSTOM: Capture from a user DIVERSION or RATING curve.
+    """
+
+    GRATE = 0
+    CURB = 1
+    COMBO = 2
+    SLOTTED = 3
+    DROP_GRATE = 4
+    DROP_CURB = 5
+    CUSTOM = 6
+
+
+class GrateType(IntEnum):
+    """Grate bar pattern (HEC-22 Table 4-6). Mirrors C{SWMM_GrateType}.
+
+    @cvar P_BAR_50: Parallel bars at 50 mm spacing.
+    @cvar P_BAR_50x100: Parallel bars at 50 mm with 100 mm cross bars.
+    @cvar P_BAR_30: Parallel bars at 30 mm spacing.
+    @cvar CURVED_VANE: Curved vane grate.
+    @cvar TILT_BAR_45: 45-degree tilt bar grate.
+    @cvar TILT_BAR_30: 30-degree tilt bar grate.
+    @cvar RETICULINE: Reticuline (honeycomb) grate.
+    @cvar GENERIC: User-supplied open-area fraction and splash-over velocity.
+    """
+
+    P_BAR_50 = 0
+    P_BAR_50x100 = 1
+    P_BAR_30 = 2
+    CURVED_VANE = 3
+    TILT_BAR_45 = 4
+    TILT_BAR_30 = 5
+    RETICULINE = 6
+    GENERIC = 7
+
+
+class ThroatType(IntEnum):
+    """Curb-opening throat orientation. Mirrors C{SWMM_ThroatType}.
+
+    Sets the orifice head of a curb-opening inlet operating on sag. The
+    C{[INLETS]} C{DROP_CURB} form has no throat token; VERTICAL is used.
+
+    @cvar HORIZONTAL: Horizontal throat.
+    @cvar INCLINED: Inclined throat.
+    @cvar VERTICAL: Vertical throat (the .inp default).
+    """
+
+    HORIZONTAL = 0
+    INCLINED = 1
+    VERTICAL = 2
+
+
+class InletCurveKind(IntEnum):
+    """Capture-curve kind of a C{CUSTOM} inlet design.
+
+    Mirrors C{SWMM_InletCurveKind}. The C{[INLETS]} grammar carries no kind
+    token — the named curve's own C{[CURVES]} type is the authority, so the
+    engine re-derives this when the model is validated.
+
+    @cvar NONE: Not resolved yet (the curve has not been seen).
+    @cvar DIVERSION: Captured flow as a function of approach flow.
+    @cvar RATING: Captured flow as a function of water depth.
+    """
+
+    NONE = 0
+    DIVERSION = 1
+    RATING = 2
+
+
+class InletPlacement(IntEnum):
+    """Inlet placement mode (C{[INLET_USAGE]} token 9).
+
+    Mirrors C{SWMM_InletPlacement}.
+
+    @cvar AUTOMATIC: On-sag at a network sink, on-grade otherwise. For an
+        inlet junction the test is slope-based (both attached street conduits
+        fall toward the node).
+    @cvar ON_GRADE: Continuous-slope capture (HEC-22 4-16..4-25).
+    @cvar ON_SAG: Sag-point capture: weir/orifice on ponded depth.
+    """
+
+    AUTOMATIC = 0
+    ON_GRADE = 1
+    ON_SAG = 2
+
+
+class InletHostKind(IntEnum):
+    """What an inlet-usage row is attached to. Mirrors C{SWMM_InletHostKind}.
+
+    @cvar LINK: A conduit — the row came from / is written to C{[INLET_USAGE]}.
+    @cvar NODE: An inlet junction — C{[INLET_JUNCTIONS]}.
+    """
+
+    LINK = 0
+    NODE = 1
+
+
+class EvapType(IntEnum):
+    """Codes matching the native ``SWMM_EvapType`` enumeration."""
+
+    CONSTANT = 0
+    MONTHLY = 1
+    TIMESERIES = 2
+    TEMPERATURE = 3
+    FILE = 4
+
+
+class TempSource(IntEnum):
+    """Codes matching the native ``SWMM_TempSource`` enumeration."""
+
+    NONE = 0
+    TIMESERIES = 1
+    FILE = 2
+
+
+class WindType(IntEnum):
+    """Codes matching the native ``SWMM_WindType`` enumeration."""
+
+    MONTHLY = 0
+    FILE = 1
+
+
+class HumidityType(IntEnum):
+    """Codes matching the native ``SWMM_HumidityType`` enumeration."""
+
+    CONSTANT = 0
+    MONTHLY = 1
+    TIMESERIES = 2
+
+
+class HumidityVar(IntEnum):
+    """Codes matching the native ``SWMM_HumidityVar`` enumeration."""
+
+    RELATIVE = 0
+    DEWPOINT = 1
+
+
+class HeatElemKind(IntEnum):
+    """Codes matching the native ``SWMM_HeatElemKind`` enumeration."""
+
+    NODE = 0
+    LINK = 1
+
+
+class InpProfile(IntEnum):
+    """Codes matching the native ``SWMM_InpProfile`` enumeration."""
+
+    FULL = 0
+    SWMM5 = 1
+    SWMM5_STOCK = 2
+
+
+class TransportDispersionMode(IntEnum):
+    """Codes matching the native ``SWMM_TransportDispersionMode`` enumeration."""
+
+    OFF = 0
+    FISCHER = 1
+    VALUE = 2
+
+
+class UnitSystem(IntEnum):
+    """Codes matching the native ``SWMM_UnitSystem`` enumeration."""
+
+    UNITS_US = 0
+    UNITS_SI = 1
+
+
+class TransportDomain(IntEnum):
+    """Domain axis of the engine transport capability matrix."""
+    RUNOFF = 0
+    GROUNDWATER = 1
+    NETWORK_1D = 2
+    SURFACE_2D = 3
+
+
+class TransportClass(IntEnum):
+    """Species class axis of the engine transport capability matrix."""
+    POLLUTANTS = 0
+    MSX = 1
+    AGE = 2
+    TEMPERATURE = 3
+
+
+class TransportState(IntEnum):
+    """Availability of a process, with a diagnostic reason when disabled."""
+    ENABLED = 0
+    DISABLED_BY_USER = 1
+    UNAVAILABLE = 2
+
+
+class CellScope(IntEnum):
+    """Native SWMM_GW2D_SCOPE selectors."""
+    GLOBAL = 0
+    TAG = 1
+    CELL = 2
+
+
+class GroundwaterSoil(IntEnum):
+    """Native SWMM_GW2D_SOIL selectors."""
+    RUSSO = 0
+    GARDNER = 1
+    BROOKS_COREY = 2
+    VAN_GENUCHTEN = 3
+
+
+class GroundwaterClosure(IntEnum):
+    """Native SWMM_GW2D_CLOSURE selectors."""
+    AUTO = -1
+    CLOSED_FORM = 0
+    ENSLAVED = 1
+    SIGMA = 2
+
+
+class GroundwaterVariable(IntEnum):
+    """Native SWMM_GW2D_VAR selectors."""
+    HG = 0
+    HU = 1
+    TABLE_EL = 2
+    Q0 = 3
+    QLAT = 4
+    QNODE = 5
+    QDEEP = 6
+    QET = 7
+    DUNNE = 8
+    QPLUS = 9
+    DT_CELL = 10
+    TIER = 11
+    CLOSURE = 12
+    QLINK = 13
+
+
+class GroundwaterLedger(IntEnum):
+    """Native SWMM_GW2D_LED selectors."""
+    RECHARGE = 0
+    LATERAL = 1
+    DEEP = 2
+    NODE = 3
+    DUNNE = 4
+    CAPRISE = 5
+    ET = 6
+    INFIL_IN = 7
+    INIT_STORAGE = 8
+    STORAGE = 9
+    LINK = 10
+
+
+class GroundwaterZone(IntEnum):
+    """Native SWMM_GW2D_ZONE selectors."""
+    SAT = 0
+    UNSAT = 1
+
+
+class GroundwaterSpeciesLedger(IntEnum):
+    """Native SWMM_GW2D_SPL selectors."""
+    INIT = 0
+    STORAGE = 1
+    INFIL_IN = 2
+    NODE_IN = 3
+    LINK_IN = 4
+    LATERAL_NET = 5
+    DEEP_OUT = 6
+    NODE_OUT = 7
+    LINK_OUT = 8
+    DUNNE_OUT = 9
+    ET_OUT = 10
+    REACTED = 11
+    RESIDUAL = 12
+
+
+class GroundwaterTransportZone(IntEnum):
+    """Authoring zones; LAYER uses an explicit one-based layer index."""
+    SAT = 0
+    UNSAT = 1
+    LAYER = 2
diff --git a/python/openswmm/engine/_enums.pyi b/python/openswmm/engine/_enums.pyi
index c21994276..2376ef52a 100644
--- a/python/openswmm/engine/_enums.pyi
+++ b/python/openswmm/engine/_enums.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Enumerations
 ============
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for L{openswmm.engine._enums}.
 
@@ -66,9 +82,21 @@ class ErrorCode(IntEnum):
 class EngineState(IntEnum):
     """Engine lifecycle states.
 
-    Mirrors ``SWMM_EngineState`` in ``openswmm_engine.h``.
+    Returned by the C{state} property of L{Solver}. Values mirror the
+    C{SWMM_EngineState} enum in C{openswmm_engine.h}.
+
+    @cvar NONE: Uninitialised / fatal-error sentinel.
+    @cvar CREATED: Context allocated, no input loaded.
+    @cvar OPENED: Input file parsed, objects allocated.
+    @cvar INITIALIZED: Initial conditions applied.
+    @cvar STARTED: Simulation prepared to step (post-start, pre-first-step).
+    @cvar RUNNING: Simulation loop in progress.
+    @cvar ENDED: Simulation loop completed.
+    @cvar CLOSED: Resources released.
+    @cvar BUILDING: Programmatic model construction in progress (no .inp).
     """
 
+    NONE = 0
     CREATED = 1
     OPENED = 2
     INITIALIZED = 3
@@ -163,12 +191,17 @@ class RouteModel(IntEnum):
 
     @cvar STEADY: Steady-state routing.
     @cvar KINWAVE: Kinematic wave routing.
-    @cvar DYNWAVE: Dynamic wave (full Saint-Venant) routing.
+    @cvar DYNWAVE: Dynamic wave (full Saint-Venant), implicit. The default.
+    @cvar FV: Explicit conservative finite volume (Godunov). Conserves volume
+        exactly and captures pressurization fronts and transcritical flow, at
+        the cost of needing a resolved mesh — set ``FV_CELL_LENGTH``. See the
+        Hydraulics Reference Manual, Chapter 8.
     """
 
     STEADY = 0
     KINWAVE = 1
     DYNWAVE = 2
+    FV = 3
 
 
 class NodeType(IntEnum):
@@ -473,6 +506,17 @@ class AquiferParam(IntEnum):
     UPPER_MOISTURE = 11
 
 
+class GwfType(IntEnum):
+    """Which of a subcatchment's two [GWF] custom groundwater flow expressions.
+
+    @cvar LATERAL: Added to the standard A1/A2/A3 lateral groundwater flow.
+    @cvar DEEP: Replaces the standard deep-percolation term.
+    """
+
+    LATERAL = 0
+    DEEP = 1
+
+
 # =============================================================================
 # Output variables
 # =============================================================================
@@ -655,6 +699,8 @@ class RunoffTotal(IntEnum):
     SNOWREMOV = 4
     INITSTORE = 5
     FINALSTORE = 6
+    INITSNOW = 7
+    FINALSNOW = 8
 
 
 class RoutingTotal(IntEnum):
@@ -671,6 +717,10 @@ class RoutingTotal(IntEnum):
     @cvar SEEP_LOSS: Seepage loss.
     @cvar INIT_STORAGE: Initial network storage.
     @cvar FINAL_STORAGE: Final network storage.
+    @cvar FORCING_INFLOW: Runtime-API forced lateral inflow (e.g.
+        flow injected via Nodes.set_lateral_inflow / transient
+        ForcingData). A subset of EXTERNAL, which also includes authored
+        inflows, interface-file inflow, and 2D coupling inflow.
     """
 
     DRY_WEATHER = 0
@@ -684,6 +734,9 @@ class RoutingTotal(IntEnum):
     SEEP_LOSS = 8
     INIT_STORAGE = 9
     FINAL_STORAGE = 10
+    FORCING_INFLOW = 11
+    LINK_GW_INFLOW = 13
+    COUPLING_OUT = 12
 
 
 # =============================================================================
@@ -700,7 +753,26 @@ class DividerType(IntEnum):
 
 
 class ForcingType(IntEnum):
-    """Forcing channel for a runtime override. Mirrors ``SWMM_ForcingType``."""
+    """Forcing channel selected when injecting a runtime override.
+
+    Mirrors C{SWMM_ForcingType} in C{openswmm_forcing.h}. Distinct from
+    L{ForcingTarget}, which only names the object *kind* passed to
+    L{Forcing.clear}.
+
+    @cvar NODE_LAT_INFLOW: Lateral inflow at a node.
+    @cvar NODE_HEAD_BOUNDARY: Head boundary condition at a node.
+    @cvar NODE_QUALITY: Pollutant concentration at a node.
+    @cvar LINK_FLOW: Imposed flow on a link.
+    @cvar LINK_SETTING: Control setting on a link.
+    @cvar SUBCATCH_RAINFALL: Rainfall on a subcatchment.
+    @cvar SUBCATCH_EVAP: Evaporation on a subcatchment.
+    @cvar GAGE_RAINFALL: Rainfall at a rain gage.
+    @cvar CLIMATE_TEMPERATURE: System-wide air temperature.
+    @cvar CLIMATE_WIND: System-wide wind speed.
+    @cvar SUBCATCH_SNOWFALL: Snowfall on a subcatchment.
+    @cvar CLIMATE_EVAP: System-wide evaporation rate.
+    @cvar LINK_QUALITY: Pollutant quality on a link.
+    """
 
     NODE_LAT_INFLOW = 0
     NODE_HEAD_BOUNDARY = 1
@@ -715,6 +787,11 @@ class ForcingType(IntEnum):
     SUBCATCH_SNOWFALL = 10
     CLIMATE_EVAP = 11
     LINK_QUALITY = 12
+    ELEM_AIR_TEMPERATURE = 13
+    ELEM_HUMIDITY = 14
+    ELEM_WIND_SPEED = 15
+    ELEM_SHORTWAVE = 16
+    LINK_SEEPAGE = 17
 
 
 class ForcingPersist(IntEnum):
@@ -742,8 +819,38 @@ class SurfaceBoundaryType(IntEnum):
     RATING_CURVE = 4
 
 
+class SurfaceInfilMethod(IntEnum):
+    """Per-cell 2D infiltration method. Mirrors ``SWMM_INFIL2D_*``."""
+
+    HORTON = 0
+    MOD_HORTON = 1
+    GREEN_AMPT = 2
+    MOD_GREEN_AMPT = 3
+    CURVE_NUMBER = 4
+    CONSTANT = 5
+
+
+class SurfaceInfilDest(IntEnum):
+    """Destination of 2D infiltrated water. Mirrors ``SWMM_INFIL2D_DEST_*``."""
+
+    LOST = 0
+    SUBCATCH_AQUIFER = 1
+    AQUIFER_2D = 2
+
+
 class RefType(IntEnum):
-    """Object kind holding a reference (editing API). Mirrors ``SWMM_RefType``."""
+    """Kind of object that holds a reference, used by the editing/impact API.
+
+    Mirrors C{SWMM_RefType} in C{openswmm_edit.h}.
+
+    @cvar NODE: A node holds the reference.
+    @cvar LINK: A link holds the reference.
+    @cvar SUBCATCH: A subcatchment holds the reference.
+    @cvar GAGE: A rain gage holds the reference.
+    @cvar TABLE: A time series or curve holds the reference.
+    @cvar TRANSECT: A transect holds the reference.
+    @cvar INLET_USAGE: An inlet-usage entry holds the reference.
+    """
 
     NODE = 0
     LINK = 1
@@ -752,6 +859,21 @@ class RefType(IntEnum):
     TABLE = 4
     TRANSECT = 5
     INLET_USAGE = 6
+    EXT_INFLOW = 7
+    DWF_INFLOW = 8
+    RDII_ASSIGN = 9
+    TREATMENT = 10
+    LID_USAGE = 11
+    SNOWPACK = 12
+    HYDROGRAPH = 13
+    POLLUTANT = 14
+    PATTERN = 15
+    AQUIFER = 16
+    LID_CONTROL = 17
+    STREET = 18
+    INLET_DESIGN = 19
+    LANDUSE = 20
+    CONTROL_RULE = 21
 
 
 class TableType(IntEnum):
@@ -772,7 +894,24 @@ class TableType(IntEnum):
 
 
 class FilePathRole(IntEnum):
-    """External-file slot selector for ``swmm_file_path_get/set``. Mirrors ``SWMM_FilePathRole``."""
+    """External-file slot selector for C{swmm_file_path_get/set}.
+
+    Mirrors C{SWMM_FilePathRole}. Scalar slots ignore the ``owner``
+    argument; vector slots use ``owner`` to select the entry (a decimal
+    index for hot-start saves, the gage id for rain-gage data, the series
+    id for time-series data).
+
+    @cvar RAINFALL: Rainfall interface file (scalar).
+    @cvar RUNOFF: Runoff interface file (scalar).
+    @cvar RDII: RDII interface file (scalar).
+    @cvar INFLOWS: Routing inflows interface file (scalar).
+    @cvar OUTFLOWS: Routing outflows interface file (scalar).
+    @cvar HOTSTART_USE: Hot-start file to read (scalar).
+    @cvar CLIMATE_TEMP: Climate/temperature file (scalar).
+    @cvar HOTSTART_SAVE: Hot-start save slot (vector; owner = index).
+    @cvar RAINGAGE_DATA: Rain-gage data file (vector; owner = gage id).
+    @cvar TIMESERIES_DATA: Time-series data file (vector; owner = series id).
+    """
 
     RAINFALL = 1
     RUNOFF = 2
@@ -784,6 +923,9 @@ class FilePathRole(IntEnum):
     HOTSTART_SAVE = 8
     RAINGAGE_DATA = 9
     TIMESERIES_DATA = 10
+    MESH_2D = 11
+    OUTPUT_2D = 12
+    LID_REPORT = 13
 
 
 class UserFlagType(IntEnum):
@@ -793,3 +935,331 @@ class UserFlagType(IntEnum):
     INTEGER = 1
     REAL = 2
     STRING = 3
+
+
+class HeatFluxModule(IntEnum):
+    """Independently toggleable heat-flux modules. Mirrors ``SWMM_HeatFluxModule``."""
+
+    SURFACE_EXCHANGE = 0
+    RADIATIVE_EXCHANGE = 1
+    LAYER_CONDUCTION = 2
+
+
+class HeatShortwaveMode(IntEnum):
+    """Source of incoming shortwave radiation. Mirrors ``SWMM_HeatShortwaveMode``."""
+
+    CONSTANT = 0
+    TIMESERIES = 1
+    COMPUTED = 2
+
+
+class HeatRadiativeParam(IntEnum):
+    """``[RADIATIVE_FLUXES]`` scalar parameters. Mirrors ``SWMM_HeatRadiativeParam``."""
+
+    SHORTWAVE = 0
+    ALBEDO = 1
+    SHADE_FACTOR = 2
+    SKY_VIEW = 3
+    EMISS_WATER = 4
+    EMISS_LANDCOVER = 5
+    ATM_EMISS_COEFF = 6
+    LW_REFLECTION = 7
+
+
+class HeatSolarParam(IntEnum):
+    """``[SOLAR_RADIATION]`` parameters. Mirrors ``SWMM_HeatSolarParam``."""
+
+    LATITUDE = 0
+    LONGITUDE = 1
+    TIMEZONE = 2
+    ELEVATION = 3
+    TURBIDITY_380 = 4
+    TURBIDITY_500 = 5
+    PRECIP_WATER = 6
+    OZONE = 7
+    GROUND_ALBEDO = 8
+
+
+class HeatCloudParam(IntEnum):
+    """``[CLOUD_COVER]`` parameters. Mirrors ``SWMM_HeatCloudParam``."""
+
+    FRACTION = 0
+    SW_ATTEN_K = 1
+    SW_ATTEN_N = 2
+    LW_CLOUD_K = 3
+
+
+class HeatSourceKind(IntEnum):
+    """``[HEAT_SOURCES]`` water sources. Mirrors ``SWMM_HeatSourceKind``."""
+
+    RAINFALL = 0
+    DWF = 1
+    GW = 2
+    RDII = 3
+    EXTERNAL_INFLOW = 4
+    IFACE = 5
+    INITIAL_STATE = 6
+
+
+class WaterAgeSource(IntEnum):
+    """``[WATER_AGE_SOURCES]`` pathways. Mirrors ``SWMM_WaterAgeSource`` (without ``COUNT``)."""
+
+    RAINFALL = 0
+    DWF = 1
+    GW = 2
+    RDII = 3
+    EXTERNAL_INFLOW = 4
+    IFACE = 5
+    INITIAL_STATE = 6
+
+
+class ReactionScope(IntEnum):
+    """Reaction-expression validation scope. Mirrors the ``SWMM_RXN_SCOPE_*`` macros."""
+
+    TERM = 0
+    PIPE = 1
+    TANK = 2
+
+
+class ReactionExprForm(IntEnum):
+    """Form of a species' reaction expression. Mirrors the ``SWMM_RXN_FORM_*`` macros."""
+
+    NONE = 0
+    RATE = 1
+    EQUIL = 2
+    FORMULA = 3
+
+
+class InletType(IntEnum):
+    """Street-inlet design type (``[INLETS]`` token 2). Mirrors ``SWMM_InletType``."""
+
+    GRATE = 0
+    CURB = 1
+    COMBO = 2
+    SLOTTED = 3
+    DROP_GRATE = 4
+    DROP_CURB = 5
+    CUSTOM = 6
+
+
+class GrateType(IntEnum):
+    """Grate bar pattern (HEC-22 Table 4-6). Mirrors ``SWMM_GrateType``."""
+
+    P_BAR_50 = 0
+    P_BAR_50x100 = 1
+    P_BAR_30 = 2
+    CURVED_VANE = 3
+    TILT_BAR_45 = 4
+    TILT_BAR_30 = 5
+    RETICULINE = 6
+    GENERIC = 7
+
+
+class ThroatType(IntEnum):
+    """Curb-opening throat orientation. Mirrors ``SWMM_ThroatType``."""
+
+    HORIZONTAL = 0
+    INCLINED = 1
+    VERTICAL = 2
+
+
+class InletCurveKind(IntEnum):
+    """Capture-curve kind of a ``CUSTOM`` inlet. Mirrors ``SWMM_InletCurveKind``."""
+
+    NONE = 0
+    DIVERSION = 1
+    RATING = 2
+
+
+class InletPlacement(IntEnum):
+    """Inlet placement mode (``[INLET_USAGE]`` token 9). Mirrors ``SWMM_InletPlacement``."""
+
+    AUTOMATIC = 0
+    ON_GRADE = 1
+    ON_SAG = 2
+
+
+class InletHostKind(IntEnum):
+    """Inlet-usage host kind. Mirrors ``SWMM_InletHostKind``."""
+
+    LINK = 0
+    NODE = 1
+
+
+class TransportClass(IntEnum):
+    """Species class axis of the engine transport capability matrix."""
+    POLLUTANTS = 0
+    MSX = 1
+    AGE = 2
+    TEMPERATURE = 3
+
+
+class WindType(IntEnum):
+    """Codes matching the native ``SWMM_WindType`` enumeration."""
+
+    MONTHLY = 0
+    FILE = 1
+
+
+class HumidityType(IntEnum):
+    """Codes matching the native ``SWMM_HumidityType`` enumeration."""
+
+    CONSTANT = 0
+    MONTHLY = 1
+    TIMESERIES = 2
+
+
+class TransportDomain(IntEnum):
+    """Domain axis of the engine transport capability matrix."""
+    RUNOFF = 0
+    GROUNDWATER = 1
+    NETWORK_1D = 2
+    SURFACE_2D = 3
+
+
+class TempSource(IntEnum):
+    """Codes matching the native ``SWMM_TempSource`` enumeration."""
+
+    NONE = 0
+    TIMESERIES = 1
+    FILE = 2
+
+
+class HeatElemKind(IntEnum):
+    """Codes matching the native ``SWMM_HeatElemKind`` enumeration."""
+
+    NODE = 0
+    LINK = 1
+
+
+class InpProfile(IntEnum):
+    """Codes matching the native ``SWMM_InpProfile`` enumeration."""
+
+    FULL = 0
+    SWMM5 = 1
+    SWMM5_STOCK = 2
+
+
+class EvapType(IntEnum):
+    """Codes matching the native ``SWMM_EvapType`` enumeration."""
+
+    CONSTANT = 0
+    MONTHLY = 1
+    TIMESERIES = 2
+    TEMPERATURE = 3
+    FILE = 4
+
+
+class UnitSystem(IntEnum):
+    """Codes matching the native ``SWMM_UnitSystem`` enumeration."""
+
+    UNITS_US = 0
+    UNITS_SI = 1
+
+
+class HumidityVar(IntEnum):
+    """Codes matching the native ``SWMM_HumidityVar`` enumeration."""
+
+    RELATIVE = 0
+    DEWPOINT = 1
+
+
+class TransportState(IntEnum):
+    """Availability of a process, with a diagnostic reason when disabled."""
+    ENABLED = 0
+    DISABLED_BY_USER = 1
+    UNAVAILABLE = 2
+
+
+class TransportDispersionMode(IntEnum):
+    """Codes matching the native ``SWMM_TransportDispersionMode`` enumeration."""
+
+    OFF = 0
+    FISCHER = 1
+    VALUE = 2
+
+
+class CellScope(IntEnum):
+    """Native SWMM_GW2D_SCOPE selectors."""
+    GLOBAL = 0
+    TAG = 1
+    CELL = 2
+
+
+class GroundwaterSoil(IntEnum):
+    """Native SWMM_GW2D_SOIL selectors."""
+    RUSSO = 0
+    GARDNER = 1
+    BROOKS_COREY = 2
+    VAN_GENUCHTEN = 3
+
+
+class GroundwaterClosure(IntEnum):
+    """Native SWMM_GW2D_CLOSURE selectors."""
+    AUTO = -1
+    CLOSED_FORM = 0
+    ENSLAVED = 1
+    SIGMA = 2
+
+
+class GroundwaterVariable(IntEnum):
+    """Native SWMM_GW2D_VAR selectors."""
+    HG = 0
+    HU = 1
+    TABLE_EL = 2
+    Q0 = 3
+    QLAT = 4
+    QNODE = 5
+    QDEEP = 6
+    QET = 7
+    DUNNE = 8
+    QPLUS = 9
+    DT_CELL = 10
+    TIER = 11
+    CLOSURE = 12
+    QLINK = 13
+
+
+class GroundwaterLedger(IntEnum):
+    """Native SWMM_GW2D_LED selectors."""
+    RECHARGE = 0
+    LATERAL = 1
+    DEEP = 2
+    NODE = 3
+    DUNNE = 4
+    CAPRISE = 5
+    ET = 6
+    INFIL_IN = 7
+    INIT_STORAGE = 8
+    STORAGE = 9
+    LINK = 10
+
+
+class GroundwaterZone(IntEnum):
+    """Native SWMM_GW2D_ZONE selectors."""
+    SAT = 0
+    UNSAT = 1
+
+
+class GroundwaterSpeciesLedger(IntEnum):
+    """Native SWMM_GW2D_SPL selectors."""
+    INIT = 0
+    STORAGE = 1
+    INFIL_IN = 2
+    NODE_IN = 3
+    LINK_IN = 4
+    LATERAL_NET = 5
+    DEEP_OUT = 6
+    NODE_OUT = 7
+    LINK_OUT = 8
+    DUNNE_OUT = 9
+    ET_OUT = 10
+    REACTED = 11
+    RESIDUAL = 12
+
+
+class GroundwaterTransportZone(IntEnum):
+    """Authoring zones; LAYER uses an explicit one-based layer index."""
+    SAT = 0
+    UNSAT = 1
+    LAYER = 2
diff --git a/python/openswmm/engine/_exceptions.py b/python/openswmm/engine/_exceptions.py
index f18875cbb..1923e27b2 100644
--- a/python/openswmm/engine/_exceptions.py
+++ b/python/openswmm/engine/_exceptions.py
@@ -1,9 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Exception hierarchy for :mod:`openswmm.engine`.
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Every non-zero return from the C API is mapped to an exception subclass
 that **also** inherits from a standard Python exception, so callers can
diff --git a/python/openswmm/engine/_forcing.pyi b/python/openswmm/engine/_forcing.pyi
index c6238de03..428cdaf86 100644
--- a/python/openswmm/engine/_forcing.pyi
+++ b/python/openswmm/engine/_forcing.pyi
@@ -10,6 +10,12 @@ _Key = Union[int, str]
 
 
 class Forcing:
+    def node_temperature(self, node: int | str, value: float, *, mode: ForcingMode = ..., persist: bool = ...) -> None: ...
+    def node_age(self, node: int | str, value: float, *, mode: ForcingMode = ..., persist: bool = ...) -> None: ...
+    def link_seepage(self, link: int | str, value: float, *, mode: ForcingMode = ..., persist: bool = ...) -> None: ...
+    def element_climate(self, kind: int, element: int | str, variable: int, value: float, *, mode: ForcingMode = ..., persist: bool = ...) -> None: ...
+    def element_climate_get(self, kind: int, element: int | str, variable: int) -> tuple[float, ForcingMode | None]: ...
+
     def __init__(self, solver: Solver) -> None: ...
 
     def node_lat_inflow(
diff --git a/python/openswmm/engine/_forcing.pyx b/python/openswmm/engine/_forcing.pyx
index 1cd089b4a..2fc86f9f7 100644
--- a/python/openswmm/engine/_forcing.pyx
+++ b/python/openswmm/engine/_forcing.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Runtime forcing (Pythonic v1 surface)
 =====================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Forcing` view, reached via ``solver.forcing``, applies
 runtime overrides to node/link/subcatchment/gage state.
@@ -82,6 +98,44 @@ class Forcing:
     def __init__(self, solver):
         self._solver = solver
 
+    def node_temperature(self, node, double value, *, mode=ForcingMode.REPLACE, bint persist=False):
+        """Temperature override in degrees C; ADD uses degrees C times ft³/s."""
+        cdef int i = _resolve_node(self._solver, node)
+        _check(swmm_forcing_node_temperature(_h(self._solver), i, value, int(mode), int(persist)))
+
+    def node_age(self, node, double value, *, mode=ForcingMode.REPLACE, bint persist=False):
+        """Age override in hours; ADD uses hours times ft³/s."""
+        cdef int i = _resolve_node(self._solver, node)
+        _check(swmm_forcing_node_age(_h(self._solver), i, value, int(mode), int(persist)))
+
+    def link_seepage(self, link, double value, *, mode=ForcingMode.REPLACE, bint persist=False):
+        """Exchange in ft³/s regardless of project units, positive out of conduit."""
+        cdef int i = _resolve_link(self._solver, link)
+        _check(swmm_forcing_link_seepage(_h(self._solver), i, value, int(mode), int(persist)))
+
+    def element_climate(self, kind, element, variable, double value, *, mode=ForcingMode.REPLACE, bint persist=False):
+        """Force local air temperature, humidity, wind or shortwave climate.
+
+        Use HeatElemKind and the ELEM_* ForcingType selectors. Values use
+        project temperature/wind units, percent humidity, and W/m² shortwave.
+        """
+        cdef int k = int(kind)
+        if k not in (0, 1):
+            raise ValueError("kind must be HeatElemKind.NODE or LINK")
+        cdef int i = _resolve_node(self._solver, element) if k == 0 else _resolve_link(self._solver, element)
+        _check(swmm_forcing_element_climate(_h(self._solver), k, i, int(variable), value, int(mode), int(persist)))
+
+    def element_climate_get(self, kind, element, variable):
+        """Return (value, mode), with mode None when no override is present."""
+        cdef int k = int(kind)
+        if k not in (0, 1):
+            raise ValueError("kind must be HeatElemKind.NODE or LINK")
+        cdef int i = _resolve_node(self._solver, element) if k == 0 else _resolve_link(self._solver, element)
+        cdef double value = 0
+        cdef int mode = 0
+        _check(swmm_forcing_element_climate_get(_h(self._solver), k, i, int(variable), &value, &mode))
+        return value, ForcingMode(mode) if mode else None
+
     # ---- Node forcing ---------------------------------------------
 
     def node_lat_inflow(self, node, double value, *,
@@ -420,3 +474,10 @@ class Forcing:
 
     def __repr__(self) -> str:
         return f""
+
+cdef extern from "openswmm/engine/openswmm_forcing.h":
+    int swmm_forcing_node_temperature(SWMM_Engine, int, double, int, int)
+    int swmm_forcing_node_age(SWMM_Engine, int, double, int, int)
+    int swmm_forcing_link_seepage(SWMM_Engine, int, double, int, int)
+    int swmm_forcing_element_climate(SWMM_Engine, int, int, int, double, int, int)
+    int swmm_forcing_element_climate_get(SWMM_Engine, int, int, int, double*, int*)
diff --git a/python/openswmm/engine/_gages.pyi b/python/openswmm/engine/_gages.pyi
index 390b2e544..1a6606f96 100644
--- a/python/openswmm/engine/_gages.pyi
+++ b/python/openswmm/engine/_gages.pyi
@@ -1,17 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Rain gage access (Pythonic v1 surface)
 ======================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._gages`.
 """
 
 from collections.abc import Iterator
 from datetime import timedelta
-from typing import Any, Union
+from typing import Any, Optional, Union
 
 import numpy as np
 from numpy.typing import NDArray
@@ -35,12 +51,16 @@ class Gage:
     rain_units: int
     timeseries: str
     station_id: str
+    file_column: str
+    file_format: int
     rainfall: float
+    rainfall_series: NDArray[Any]  # dtype = [(time, datetime64[s]), (value, f8)]
 
     def __init__(self, solver: Solver, index: int) -> None: ...
     def set_rain_interval(self, seconds: Union[float, timedelta]) -> None: ...
     def set_timeseries(self, ts_id: str) -> None: ...
-    def set_file(self, path: str, station_id: str) -> None: ...
+    def set_file(self, path: str, station_id: str,
+                 column: Optional[str] = ...) -> None: ...
 
     def __eq__(self, other: object) -> bool: ...
     def __hash__(self) -> int: ...
@@ -59,6 +79,7 @@ class Gages:
     def get_id(self, idx: int) -> str: ...
     def add(self, gage_id: str) -> Gage: ...
     def rename(self, key: _Key, new_id: str) -> None: ...
+    def reload_rain_files(self) -> None: ...
 
     rainfalls: NDArray[Any]
     ids: NDArray[Any]
diff --git a/python/openswmm/engine/_gages.pyx b/python/openswmm/engine/_gages.pyx
index fd3626f5c..234de6a5f 100644
--- a/python/openswmm/engine/_gages.pyx
+++ b/python/openswmm/engine/_gages.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Rain gage access (Pythonic v1 surface)
 ======================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Gages` collection and :class:`Gage` wrapper expose rain
 gages with the same shape as :mod:`openswmm.engine._nodes`.
@@ -28,6 +44,7 @@ import numpy as np
 cimport numpy as np
 
 from ._common cimport *
+from ._dates import oadate_to_datetime
 from ._enums import GageDataSource, GageRainType
 from ._exceptions import ElementNotFoundError, StaleObjectError
 
@@ -198,6 +215,48 @@ cdef class Gage:
         cdef bytes b = value.encode('utf-8')
         _check(swmm_gage_set_station_id(_h(self._solver), self._index, b))
 
+    @property
+    def file_column(self) -> str:
+        """Data column name for a multi-column rain file (empty when unset).
+
+        This is the ``COLUMN`` of the ``FILE "path:COLUMN"`` form (CSV, TSV,
+        or PCSWMM TSF). Assigning a non-empty name switches the gage's file
+        format to USER_CSV; an empty name on a USER_CSV gage selects the
+        file's first data column.
+        """
+        _check_fresh(self)
+        cdef char buf[256]
+        _check(swmm_gage_get_file_column(_h(self._solver), self._index, buf, 256))
+        return buf.decode('utf-8')
+
+    @file_column.setter
+    def file_column(self, str value) -> None:
+        _check_fresh(self)
+        cdef bytes b = value.encode('utf-8')
+        _check(swmm_gage_set_file_column(_h(self._solver), self._index, b))
+
+    @property
+    def file_format(self) -> int:
+        """Rain file format code (meaningful for FILE gages).
+
+        ``5`` = STAN_PRCP standard SWMM rain file, ``6`` = USER_CSV
+        multi-column CSV/TSV/TSF, ``-1`` = unknown/not a file gage.
+
+        Assigning is the way back out of USER_CSV (``file_column`` and
+        ``set_file`` both preserve it). Setting USER_CSV clears
+        ``station_id``; setting a station-based format clears
+        ``file_column``.
+        """
+        _check_fresh(self)
+        cdef int v = -1
+        _check(swmm_gage_get_file_format(_h(self._solver), self._index, &v))
+        return v
+
+    @file_format.setter
+    def file_format(self, int value) -> None:
+        _check_fresh(self)
+        _check(swmm_gage_set_file_format(_h(self._solver), self._index, value))
+
     def set_rain_interval(self, seconds) -> None:
         """Set the rain-interval duration. Accepts a number of seconds
         or a :class:`datetime.timedelta`."""
@@ -216,13 +275,63 @@ cdef class Gage:
         cdef bytes b = ts_id.encode('utf-8')
         _check(swmm_gage_set_timeseries(_h(self._solver), self._index, b))
 
-    def set_file(self, path: str, station_id: str) -> None:
-        """Configure the gage to read from an external file."""
+    def set_file(self, path: str, station_id: str, column: str = None) -> None:
+        """Configure the gage to read from an external file.
+
+        ``column`` selects a data column of a multi-column file (CSV/TSV/TSF,
+        the ``FILE "path:col"`` form) and switches the gage to the USER_CSV
+        format; omit it for a standard SWMM rain file.
+        """
         _check_fresh(self)
         cdef bytes b_path = path.encode('utf-8')
         cdef bytes b_id = station_id.encode('utf-8')
+        cdef bytes b_col
         _check(swmm_gage_set_filename(
             _h(self._solver), self._index, b_path, b_id))
+        if column is not None:
+            b_col = column.encode('utf-8')
+            _check(swmm_gage_set_file_column(
+                _h(self._solver), self._index, b_col))
+
+    # ---- Resolved rainfall series ----------------------------------
+
+    @property
+    def rainfall_series(self):
+        """The rainfall the engine will actually apply, as a structured array.
+
+        Columns are ``time: datetime64[s]`` and ``value: float64``, the same
+        shape as :attr:`openswmm.engine.TimeSeries.points`. Works for both
+        data sources — a TIMESERIES gage reports its table, a FILE gage the
+        series loaded from disk — with the rain-type transform, the rain-file
+        units factor and the scale factor already applied.
+
+        Each value is the intensity (rain units per hour) applying from its
+        own stamp until the recording interval elapses or the next entry
+        begins, whichever comes first; rainfall is zero in between. Pair with
+        :attr:`rain_interval` to reconstruct that.
+
+        A FILE gage's series is windowed to the ``[OPTIONS]`` simulation dates
+        (± one day) and reflects the file as read at open; call
+        :meth:`Gages.reload_rain_files` first if the path, column, station,
+        units or dates have changed. An empty array means that gage
+        contributes no rainfall to the run.
+        """
+        _check_fresh(self)
+        cdef SWMM_Engine h = _h(self._solver)
+        cdef int n = 0
+        _check(swmm_gage_get_rainfall_series_count(h, self._index, &n))
+        cdef np.ndarray[double, ndim=1] times = np.empty(n, dtype=np.float64)
+        cdef np.ndarray[double, ndim=1] values = np.empty(n, dtype=np.float64)
+        if n > 0:
+            _check(swmm_gage_get_rainfall_series(
+                h, self._index, times.data, values.data, n))
+        dtype = np.dtype([("time", "datetime64[s]"), ("value", "float64")])
+        out = np.empty(n, dtype=dtype)
+        for i in range(n):
+            dt = oadate_to_datetime(float(times[i])).replace(microsecond=0)
+            out["time"][i] = np.datetime64(dt)
+        out["value"][:] = values
+        return out
 
     # ---- Runtime state ---------------------------------------------
 
@@ -332,8 +441,9 @@ cdef class Gages:
         cdef int n = swmm_gage_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_gage_get_rainfall_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_gage_get_rainfall_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -342,6 +452,20 @@ cdef class Gages:
         return np.asarray(
             [self.get_id(i) for i in range(len(self))], dtype=object)
 
+    def reload_rain_files(self) -> None:
+        """Re-read every FILE-source gage's rain data from disk.
+
+        Rain files are loaded once, during ``open()``; nothing re-runs that
+        afterwards, so editing a gage's path, column, station id or rain
+        units — or the simulation dates the data is windowed to — has no
+        effect until this is called. Rebuilds the resolved series and the
+        rainfall-file summary for every FILE gage.
+
+        Requires an editable model (BUILDING or OPENED); not valid mid-run.
+        """
+        _check(swmm_gage_reload_rain_files(_h(self._solver)))
+        self._solver._bump_generation()
+
     def __repr__(self) -> str:
         try:
             return f""
diff --git a/python/openswmm/engine/_geometry.py b/python/openswmm/engine/_geometry.py
index 32ea10cff..281284c69 100644
--- a/python/openswmm/engine/_geometry.py
+++ b/python/openswmm/engine/_geometry.py
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Cross-Section Geometry
 ======================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Provides the :class:`CrossSection` dataclass, which wraps the raw
 ``(shape, geom1, geom2, geom3, geom4)`` tuple a link reports with
diff --git a/python/openswmm/engine/_geopackage.pyi b/python/openswmm/engine/_geopackage.pyi
index dd853dbac..7cdb2cef4 100644
--- a/python/openswmm/engine/_geopackage.pyi
+++ b/python/openswmm/engine/_geopackage.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 GeoPackage Access
 =================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._geopackage`.
 
diff --git a/python/openswmm/engine/_geopackage.pyx b/python/openswmm/engine/_geopackage.pyx
index 3dd3e19a5..ee33086e8 100644
--- a/python/openswmm/engine/_geopackage.pyx
+++ b/python/openswmm/engine/_geopackage.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 GeoPackage Access
 =================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`GeoPackage` class provides read/write access to SWMM GeoPackage
 databases for querying multi-run simulation results, importing observed data,
@@ -103,6 +119,7 @@ cdef class GeoPackage:
         underlying GeoPackage library.
     """
 
+    cdef object _lock
     cdef SWMM_Gpkg _handle
 
     def __cinit__(self, str path):
@@ -112,6 +129,8 @@ cdef class GeoPackage:
         @type path: str
         @raise RuntimeError: If the file cannot be opened.
         """
+        from threading import RLock
+        self._lock = RLock()
         cdef bytes b = path.encode('utf-8')
         self._handle = swmm_gpkg_open(b)
         if self._handle is NULL:
@@ -127,11 +146,27 @@ cdef class GeoPackage:
     # File lifecycle (open/close)
     # ====================================================================
 
+    cdef void _check_access(self) except *:
+        if not self._lock.acquire(blocking=False):
+            from ._exceptions import LifecycleError
+            from ._enums import ErrorCode
+            raise LifecycleError(ErrorCode.LIFECYCLE, "GeoPackage is in use by another thread")
+        self._lock.release()
+
+    cdef SWMM_Gpkg _h(self) except NULL:
+        self._check_access()
+        if self._handle == NULL:
+            from ._exceptions import BadHandleError
+            from ._enums import ErrorCode
+            raise BadHandleError(ErrorCode.BADHANDLE, "GeoPackage is closed")
+        return self._handle
+
     def close(self):
         """Close the database connection.
 
         Calling C{close} more than once is harmless.
         """
+        self._check_access()
         if self._handle is not NULL:
             swmm_gpkg_close(self._handle)
             self._handle = NULL
@@ -162,7 +197,7 @@ cdef class GeoPackage:
             reported.
         @rtype: str
         """
-        cdef const char* msg = swmm_gpkg_last_error(self._handle)
+        cdef const char* msg = swmm_gpkg_last_error(self._h())
         return msg.decode('utf-8') if msg else ""
 
     # ====================================================================
@@ -174,7 +209,7 @@ cdef class GeoPackage:
 
         @raise RuntimeError: If the transaction cannot be started.
         """
-        if swmm_gpkg_begin(self._handle) != 0:
+        if swmm_gpkg_begin(self._h()) != 0:
             raise RuntimeError(f"Transaction begin failed: {self.last_error}")
 
     def commit(self):
@@ -182,7 +217,7 @@ cdef class GeoPackage:
 
         @raise RuntimeError: If the commit fails.
         """
-        if swmm_gpkg_commit(self._handle) != 0:
+        if swmm_gpkg_commit(self._h()) != 0:
             raise RuntimeError(f"Transaction commit failed: {self.last_error}")
 
     def rollback(self):
@@ -190,7 +225,7 @@ cdef class GeoPackage:
 
         @raise RuntimeError: If the rollback fails.
         """
-        if swmm_gpkg_rollback(self._handle) != 0:
+        if swmm_gpkg_rollback(self._h()) != 0:
             raise RuntimeError(f"Transaction rollback failed: {self.last_error}")
 
     # ====================================================================
@@ -203,7 +238,7 @@ cdef class GeoPackage:
         @return: Simulation count.
         @rtype: int
         """
-        return swmm_gpkg_simulation_count(self._handle)
+        return swmm_gpkg_simulation_count(self._h())
 
     def simulation_ids(self) -> list:
         """Return all simulation IDs as a list of strings.
@@ -211,11 +246,11 @@ cdef class GeoPackage:
         @return: List of simulation identifier strings.
         @rtype: list
         """
-        cdef int n = swmm_gpkg_simulation_count(self._handle)
+        cdef int n = swmm_gpkg_simulation_count(self._h())
         cdef char buf[256]
         result = []
         for i in range(n):
-            if swmm_gpkg_simulation_id(self._handle, i, buf, 256) == 0:
+            if swmm_gpkg_simulation_id(self._h(), i, buf, 256) == 0:
                 result.append(buf.decode('utf-8'))
         return result
 
@@ -230,10 +265,10 @@ cdef class GeoPackage:
         """
         cdef bytes b = sim_id.encode('utf-8')
         return {
-            "nodes": swmm_gpkg_node_count(self._handle, b),
-            "links": swmm_gpkg_link_count(self._handle, b),
-            "subcatchments": swmm_gpkg_subcatch_count(self._handle, b),
-            "gages": swmm_gpkg_gage_count(self._handle, b),
+            "nodes": swmm_gpkg_node_count(self._h(), b),
+            "links": swmm_gpkg_link_count(self._h(), b),
+            "subcatchments": swmm_gpkg_subcatch_count(self._h(), b),
+            "gages": swmm_gpkg_gage_count(self._h(), b),
         }
 
     def variable_count(self) -> int:
@@ -242,7 +277,7 @@ cdef class GeoPackage:
         @return: Variable count.
         @rtype: int
         """
-        return swmm_gpkg_variable_count(self._handle)
+        return swmm_gpkg_variable_count(self._h())
 
     def topology_edge_count(self, str sim_id) -> int:
         """Return the number of topology edges for a simulation.
@@ -253,7 +288,7 @@ cdef class GeoPackage:
         @rtype: int
         """
         cdef bytes b = sim_id.encode('utf-8')
-        return swmm_gpkg_topology_edge_count(self._handle, b)
+        return swmm_gpkg_topology_edge_count(self._h(), b)
 
     # ====================================================================
     # Read operations - result timeseries (zero-copy numpy)
@@ -276,7 +311,7 @@ cdef class GeoPackage:
         @rtype: int
         """
         return swmm_gpkg_result_ts_count(
-            self._handle, sim_id.encode('utf-8'),
+            self._h(), sim_id.encode('utf-8'),
             obj_type.encode('utf-8'), obj_id.encode('utf-8'),
             variable.encode('utf-8'))
 
@@ -298,7 +333,7 @@ cdef class GeoPackage:
         @see: L{result_ts_count}
         """
         cdef int n = swmm_gpkg_result_ts_count(
-            self._handle, sim_id.encode('utf-8'),
+            self._h(), sim_id.encode('utf-8'),
             obj_type.encode('utf-8'), obj_id.encode('utf-8'),
             variable.encode('utf-8'))
         if n <= 0:
@@ -312,7 +347,7 @@ cdef class GeoPackage:
         cdef bytes b_otype = obj_type.encode('utf-8')
         cdef bytes b_oid = obj_id.encode('utf-8')
         cdef bytes b_var = variable.encode('utf-8')
-        cdef SWMM_Gpkg gpkg = self._handle
+        cdef SWMM_Gpkg gpkg = self._h()
         cdef const char* p_sim = b_sim
         cdef const char* p_otype = b_otype
         cdef const char* p_oid = b_oid
@@ -322,10 +357,11 @@ cdef class GeoPackage:
         cdef int read
         # SQL execution can take many milliseconds for large series — worth
         # releasing the GIL so another thread can do useful work meanwhile.
-        with nogil:
-            read = swmm_gpkg_read_result_ts(
-                gpkg, p_sim, p_otype, p_oid, p_var,
-                p_times, p_values, n)
+        with self._lock:
+            with nogil:
+                read = swmm_gpkg_read_result_ts(
+                    gpkg, p_sim, p_otype, p_oid, p_var,
+                    p_times, p_values, n)
         return times[:read], values[:read]
 
     # ====================================================================
@@ -350,7 +386,7 @@ cdef class GeoPackage:
         """
         cdef double v = 0.0
         cdef int rc = swmm_gpkg_read_summary(
-            self._handle, sim_id.encode('utf-8'),
+            self._h(), sim_id.encode('utf-8'),
             obj_type.encode('utf-8'), obj_id.encode('utf-8'),
             variable.encode('utf-8'), &v)
         if rc != 0:
@@ -398,7 +434,7 @@ cdef class GeoPackage:
         cdef const char* p_src = b_src if source else NULL
         cdef const char* p_units = b_units if units else NULL
         cdef int sid = swmm_gpkg_create_observed_series(
-            self._handle,
+            self._h(),
             b_name, b_var,
             p_otype, p_oid, p_src, p_units)
         if sid < 0:
@@ -427,7 +463,7 @@ cdef class GeoPackage:
         cdef bytes b_flag = flag.encode('utf-8') if flag else b""
         cdef const char* p_flag = b_flag if flag else NULL
         cdef int rc = swmm_gpkg_write_observed_value(
-            self._handle, series_id,
+            self._h(), series_id,
             b_ts, value, p_flag)
         if rc != 0:
             raise RuntimeError(f"Write failed: {self.last_error}")
@@ -456,7 +492,15 @@ cdef class GeoPackage:
             allocated.
         """
         cdef int n = len(timestamps)
-        cdef np.ndarray[double, ndim=1] vals = np.asarray(values, dtype=np.float64)
+        cdef np.ndarray[double, ndim=1] vals = np.ascontiguousarray(values, dtype=np.float64)
+
+        self._h()
+        if len(vals) != n:
+            raise ValueError("timestamps and values must have the same length")
+        if flags is not None and len(flags) not in (0, n):
+            raise ValueError("flags must be empty or match the timestamp count")
+        if n == 0:
+            return
 
         # Build C string arrays
         cdef list ts_bytes = [t.encode('utf-8') for t in timestamps]
@@ -470,7 +514,7 @@ cdef class GeoPackage:
             if c_fl: free(c_fl)
             raise MemoryError()
 
-        cdef SWMM_Gpkg gpkg = self._handle
+        cdef SWMM_Gpkg gpkg = self._h()
         cdef const double* p_vals = vals.data
         cdef const char** c_fl_arg
         cdef int rc_c
@@ -481,9 +525,10 @@ cdef class GeoPackage:
             c_fl_arg = c_fl if flags else NULL
             # Bulk SQL inserts can take a long time for large series;
             # release the GIL so peer threads continue.
-            with nogil:
-                rc_c = swmm_gpkg_write_observed_values(
-                    gpkg, series_id, c_ts, p_vals, c_fl_arg, n)
+            with self._lock:
+                with nogil:
+                    rc_c = swmm_gpkg_write_observed_values(
+                        gpkg, series_id, c_ts, p_vals, c_fl_arg, n)
             if rc_c != 0:
                 raise RuntimeError(f"Bulk write failed: {self.last_error}")
         finally:
@@ -500,7 +545,7 @@ cdef class GeoPackage:
         @return: Observed-series count.
         @rtype: int
         """
-        return swmm_gpkg_observed_series_count(self._handle)
+        return swmm_gpkg_observed_series_count(self._h())
 
     def observed_value_count(self, int series_id) -> int:
         """Return the number of values in an observed series.
@@ -510,7 +555,7 @@ cdef class GeoPackage:
         @return: Value count.
         @rtype: int
         """
-        return swmm_gpkg_observed_value_count(self._handle, series_id)
+        return swmm_gpkg_observed_value_count(self._h(), series_id)
 
     def read_observed_values(self, int series_id):
         """Read observed-timeseries values.
@@ -522,20 +567,21 @@ cdef class GeoPackage:
             C{float64} array.
         @rtype: tuple
         """
-        cdef int n = swmm_gpkg_observed_value_count(self._handle, series_id)
+        cdef int n = swmm_gpkg_observed_value_count(self._h(), series_id)
         if n <= 0:
             return [], np.empty(0, dtype=np.float64)
 
         cdef int ts_len = 32
         cdef bytearray ts_buf = bytearray(n * ts_len)
         cdef np.ndarray[double, ndim=1] values = np.empty(n, dtype=np.float64)
-        cdef SWMM_Gpkg gpkg = self._handle
+        cdef SWMM_Gpkg gpkg = self._h()
         cdef char* p_ts = ts_buf
         cdef double* p_v = values.data
         cdef int read
-        with nogil:
-            read = swmm_gpkg_read_observed_values(
-                gpkg, series_id, p_ts, ts_len, p_v, n)
+        with self._lock:
+            with nogil:
+                read = swmm_gpkg_read_observed_values(
+                    gpkg, series_id, p_ts, ts_len, p_v, n)
 
         timestamps = []
         for i in range(read):
@@ -557,7 +603,7 @@ cdef class GeoPackage:
         @return: Integer result of the query.
         @rtype: int
         """
-        return swmm_gpkg_query_int(self._handle, sql.encode('utf-8'))
+        return swmm_gpkg_query_int(self._h(), sql.encode('utf-8'))
 
     def query_double(self, str sql) -> float:
         """Execute a read-only SQL query and return the first double result.
@@ -569,7 +615,7 @@ cdef class GeoPackage:
         @raise RuntimeError: If the query fails.
         """
         cdef double v = 0.0
-        cdef int rc = swmm_gpkg_query_double(self._handle,
+        cdef int rc = swmm_gpkg_query_double(self._h(),
                                               sql.encode('utf-8'), &v)
         if rc != 0:
             raise RuntimeError(f"Query failed: {self.last_error}")
diff --git a/python/openswmm/engine/_groundwater.pyi b/python/openswmm/engine/_groundwater.pyi
new file mode 100644
index 000000000..319702a1b
--- /dev/null
+++ b/python/openswmm/engine/_groundwater.pyi
@@ -0,0 +1,76 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from collections.abc import Iterator, MutableMapping
+from typing import Any
+import numpy as np
+from numpy.typing import NDArray
+from ._enums import (CellScope, GroundwaterVariable, GroundwaterLedger,
+                     GroundwaterZone, GroundwaterSpeciesLedger)
+
+@dataclass(frozen=True)
+class AquiferRow:
+    scope: CellScope
+    tag: str
+    cell: int
+    ks: float
+    zs: float
+    theta_s: float
+    theta_r: float
+    alpha: float
+
+@dataclass(frozen=True)
+class AquiferNode:
+    node: str
+    cell: int
+    kc: float
+    dc: float
+    area: float
+    locate: bool
+    exchange: bool
+    automatic: bool
+
+from ._gw_transport import GroundwaterTransport
+
+class AquiferOptions(MutableMapping[str, str]):
+    """Text options using the native INP key/value spellings."""
+    def __init__(self, owner: Any) -> None: ...
+    def __getitem__(self, key: str) -> str: ...
+    def __setitem__(self, key: str, value: object) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
+
+
+class Groundwater:
+    @property
+    def transport(self) -> GroundwaterTransport: ...
+    def __init__(self, owner: Any) -> None: ...
+    @property
+    def options(self) -> AquiferOptions: ...
+    @property
+    def rows(self) -> tuple[AquiferRow, ...]: ...
+    def add_row(self, scope: CellScope, ks: float, zs: float, theta_s: float, theta_r: float, alpha: float, *, tag: str = ..., cell: int = ...) -> None: ...
+    def row_property(self, index: int, key: str) -> float: ...
+    def set_row_property(self, index: int, key: str, value: float) -> None: ...
+    def remove_row(self, index: int) -> None: ...
+    @property
+    def nodes(self) -> tuple[AquiferNode, ...]: ...
+    def add_node(self, node: str, cell: int, kc: float, dc: float, area: float = ...) -> None: ...
+    def remove_node(self, index: int) -> None: ...
+    def set_node_exchange(self, index: int, enabled: bool) -> None: ...
+    @property
+    def active(self) -> bool: ...
+    @property
+    def dimensions(self) -> tuple[int, int]: ...
+    def cell(self, cell: int, variable: GroundwaterVariable) -> float: ...
+    def cells(self, variable: GroundwaterVariable) -> NDArray[np.float64]: ...
+    def column(self, cell: int) -> NDArray[np.float64]: ...
+    def ledger(self, term: GroundwaterLedger) -> float: ...
+    @property
+    def continuity_error(self) -> float: ...
+    @property
+    def tier_histogram(self) -> NDArray[Any]: ...
+    @property
+    def species(self) -> tuple[str, ...]: ...
+    def concentrations(self, zone: GroundwaterZone, species: int) -> NDArray[np.float64]: ...
+    def species_ledger(self, species: int, term: GroundwaterSpeciesLedger) -> float: ...
diff --git a/python/openswmm/engine/_groundwater.pyx b/python/openswmm/engine/_groundwater.pyx
new file mode 100644
index 000000000..3eebfaf62
--- /dev/null
+++ b/python/openswmm/engine/_groundwater.pyx
@@ -0,0 +1,274 @@
+"""Two-zone groundwater authoring and runtime snapshots.
+
+Authored aquifer and node-bed values use project units. Runtime hydrology uses
+SI (metres, seconds, cubic metres); species concentrations use mass per cubic
+metre of zone water. Edit before initialize and read active state after start.
+"""
+from dataclasses import dataclass
+from collections.abc import MutableMapping
+import numpy as np
+cimport numpy as np
+from ._common cimport SWMM_Engine, _check
+from ._access import EngineView
+from ._enums import (CellScope, GroundwaterVariable, GroundwaterLedger,
+                     GroundwaterZone, GroundwaterSpeciesLedger)
+
+cdef extern from "openswmm/engine/openswmm_gw2d.h":
+    int swmm_gw2d_species_count(SWMM_Engine engine, int* count) nogil
+    int swmm_gw2d_species_name(SWMM_Engine engine, int species, char* buf, int buflen) nogil
+    int swmm_gw2d_get_cell_conc(SWMM_Engine engine, int zone, int species, double* out, int len, int* written) nogil
+    int swmm_gw2d_get_species_ledger(SWMM_Engine engine, int species, int term, double* value) nogil
+    int swmm_gw2d_option_get(SWMM_Engine engine, const char* key, char* buf, int buflen) nogil
+    int swmm_gw2d_option_set(SWMM_Engine engine, const char* key, const char* value) nogil
+    int swmm_gw2d_row_count(SWMM_Engine engine, int* count) nogil
+    int swmm_gw2d_row_add(SWMM_Engine engine, int scope, const char* tag, int cell, double ks, double zs, double theta_s, double theta_r, double alpha) nogil
+    int swmm_gw2d_row_get(SWMM_Engine engine, int index, int* scope, char* tag, int taglen, int* cell, double* ks, double* zs, double* theta_s, double* theta_r, double* alpha) nogil
+    int swmm_gw2d_row_set_property(SWMM_Engine engine, int index, const char* key, double value) nogil
+    int swmm_gw2d_row_get_property(SWMM_Engine engine, int index, const char* key, double* value) nogil
+    int swmm_gw2d_row_remove(SWMM_Engine engine, int index) nogil
+    int swmm_gw2d_node_count(SWMM_Engine engine, int* count) nogil
+    int swmm_gw2d_node_add(SWMM_Engine engine, const char* node, int cell, double kc, double dc, double area) nogil
+    int swmm_gw2d_node_get(SWMM_Engine engine, int index, char* node, int nodelen, int* cell, double* kc, double* dc, double* area) nogil
+    int swmm_gw2d_node_remove(SWMM_Engine engine, int index) nogil
+    int swmm_gw2d_node_get_flags(SWMM_Engine engine, int index, int* locate, int* exchange, int* automatic) nogil
+    int swmm_gw2d_node_set_exchange(SWMM_Engine engine, int index, int exchange) nogil
+    int swmm_gw2d_is_active(SWMM_Engine engine, int* active) nogil
+    int swmm_gw2d_get_dimensions(SWMM_Engine engine, int* n_cells, int* m_layers) nogil
+    int swmm_gw2d_get_cell(SWMM_Engine engine, int cell, int var, double* value) nogil
+    int swmm_gw2d_get_cell_bulk(SWMM_Engine engine, int var, double* out, int len, int* written) nogil
+    int swmm_gw2d_get_column(SWMM_Engine engine, int cell, double* theta, int len, int* written) nogil
+    int swmm_gw2d_get_ledger(SWMM_Engine engine, int term, double* value) nogil
+    int swmm_gw2d_get_continuity_error(SWMM_Engine engine, double* value) nogil
+    int swmm_gw2d_get_tier_histogram(SWMM_Engine engine, long* out, int len, int* written) nogil
+
+cdef inline SWMM_Engine _h(view):
+    return view._address()
+
+@dataclass(frozen=True)
+class AquiferRow:
+    """Authored aquifer row in project units; cell indices are zero-based."""
+    scope: CellScope
+    tag: str
+    cell: int
+    ks: float
+    zs: float
+    theta_s: float
+    theta_r: float
+    alpha: float
+
+@dataclass(frozen=True)
+class AquiferNode:
+    """Node-bed row and enrollment flags; dimensions use project units."""
+    node: str
+    cell: int
+    kc: float
+    dc: float
+    area: float
+    locate: bool
+    exchange: bool
+    automatic: bool
+
+class AquiferOptions(EngineView, MutableMapping):
+    """Text options using the native INP key/value spellings."""
+    _keys = ('SOIL_CHAR', 'CLOSURE', 'M_LAYERS', 'CAPILLARY_DIFF', 'C_GW', 'C_COL',
+             'FORCE_CLOSED_FORM', 'MODE', 'DUNNE', 'GW_ET', 'NODE_ENROLMENT', 'LINK_SEEPAGE')
+    def __len__(self):
+        return len(self._keys)
+    def __iter__(self):
+        return iter(self._keys)
+    def __getitem__(self, key):
+        cdef bytes name = str(key).encode('utf-8')
+        cdef char value[512]
+        _check(swmm_gw2d_option_get(_h(self), name, value, 512))
+        return value.decode('utf-8')
+    def __setitem__(self, key, value):
+        cdef bytes name = str(key).encode('utf-8')
+        cdef bytes text = str(value).encode('utf-8')
+        _check(swmm_gw2d_option_set(_h(self), name, text))
+    def __delitem__(self, key):
+        raise TypeError('Aquifer options cannot be deleted; assign an explicit value')
+
+class Groundwater(EngineView):
+    """``solver.surface2d.groundwater``; authored rows and live SI results."""
+    @property
+    def transport(self):
+        """Groundwater transport authoring (thermal properties, sorption, sources)."""
+        self._address()
+        from ._gw_transport import GroundwaterTransport
+        return GroundwaterTransport(self._owner)
+
+    @property
+    def options(self):
+        self._address()
+        return AquiferOptions(self._owner)
+
+    @property
+    def rows(self):
+        """Aquifer snapshots in authored order (GLOBAL, TAG or CELL scopes)."""
+        cdef int count=0, index, scope=0, cell=0
+        cdef double ks=0, zs=0, theta_s=0, theta_r=0, alpha=0
+        cdef char tag[512]
+        cdef SWMM_Engine h = _h(self)
+        _check(swmm_gw2d_row_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_gw2d_row_get(h, index, &scope, tag, 512, &cell,
+                                    &ks, &zs, &theta_s, &theta_r, &alpha))
+            rows.append(AquiferRow(CellScope(scope), tag.decode('utf-8'), cell,
+                                   ks, zs, theta_s, theta_r, alpha))
+        return tuple(rows)
+
+    def add_row(self, scope, double ks, double zs, double theta_s,
+                double theta_r, double alpha, *, str tag='', int cell=-1):
+        """Append an aquifer row before initialization.
+
+        ks: in/hr or mm/hr; zs: ft or m; alpha: inverse ft or inverse m.
+        theta_s and theta_r are dimensionless water contents.
+        """
+        cdef bytes name = tag.encode('utf-8')
+        _check(swmm_gw2d_row_add(_h(self), int(CellScope(scope)), name, cell,
+                                ks, zs, theta_s, theta_r, alpha))
+
+    def row_property(self, int index, str key):
+        """Read an optional authored property (HG0, PSI_B, CLOSURE, etc.)."""
+        cdef bytes name = key.encode('utf-8')
+        cdef double value=0
+        _check(swmm_gw2d_row_get_property(_h(self), index, name, &value))
+        return value
+
+    def set_row_property(self, int index, str key, double value):
+        """Set optional numeric properties; soil and closure accept enum codes."""
+        cdef bytes name = key.encode('utf-8')
+        _check(swmm_gw2d_row_set_property(_h(self), index, name, value))
+
+    def remove_row(self, int index):
+        """Remove an authored row; subsequent indices shift."""
+        _check(swmm_gw2d_row_remove(_h(self), index))
+
+    @property
+    def nodes(self):
+        """Node-bed snapshots, including automatically enrolled rows after init."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, index, cell=0, locate=0, exchange=0, automatic=0
+        cdef double kc=0, dc=0, area=0
+        cdef char node[512]
+        _check(swmm_gw2d_node_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_gw2d_node_get(h, index, node, 512, &cell, &kc, &dc, &area))
+            _check(swmm_gw2d_node_get_flags(h, index, &locate, &exchange, &automatic))
+            rows.append(AquiferNode(node.decode('utf-8'), cell, kc, dc, area,
+                                    bool(locate), bool(exchange), bool(automatic)))
+        return tuple(rows)
+
+    def add_node(self, str node, int cell, double kc, double dc, double area=0):
+        """Add a bed: kc in in/hr or mm/hr, dc in ft or m, area in ft² or m².
+
+        cell=-1 locates from node coordinates; kc=0 is direct Darcy exchange;
+        area=0 uses the cell area. Edit before initialization.
+        """
+        cdef bytes name = node.encode('utf-8')
+        _check(swmm_gw2d_node_add(_h(self), name, cell, kc, dc, area))
+
+    def remove_node(self, int index):
+        """Remove a node-bed row; subsequent indices shift."""
+        _check(swmm_gw2d_node_remove(_h(self), index))
+
+    def set_node_exchange(self, int index, bint enabled):
+        """Enable or opt out of groundwater exchange for one authored bed."""
+        _check(swmm_gw2d_node_set_exchange(_h(self), index, int(enabled)))
+
+    @property
+    def active(self):
+        cdef int active=0
+        _check(swmm_gw2d_is_active(_h(self), &active))
+        return bool(active)
+
+    @property
+    def dimensions(self):
+        """(cell count, sigma layer count); cell topology need not be triangular."""
+        cdef int cells=0, layers=0
+        _check(swmm_gw2d_get_dimensions(_h(self), &cells, &layers))
+        return (cells, layers)
+
+    def cell(self, int cell, variable):
+        """One cell's runtime variable in SI; consult GroundwaterVariable."""
+        cdef double value=0
+        _check(swmm_gw2d_get_cell(_h(self), cell, int(GroundwaterVariable(variable)), &value))
+        return value
+
+    def cells(self, variable):
+        """Owned float64 snapshot of a runtime variable over all cells."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int n=0, written=0, rc, selector=int(GroundwaterVariable(variable))
+        _check(swmm_gw2d_get_dimensions(h, &n, NULL))
+        cdef np.ndarray[double, ndim=1] out = np.empty(n, dtype=np.float64)
+        with self._owner._operation(h):
+            with nogil:
+                rc = swmm_gw2d_get_cell_bulk(h, selector, out.data, n, &written)
+        _check(rc)
+        return out[:written].copy()
+
+    def column(self, int cell):
+        """Sigma-column water contents, surface layer first; requires SIGMA closure."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int n=0, written=0
+        _check(swmm_gw2d_get_dimensions(h, NULL, &n))
+        cdef np.ndarray[double, ndim=1] out = np.empty(n, dtype=np.float64)
+        _check(swmm_gw2d_get_column(h, cell, out.data, n, &written))
+        return out[:written].copy()
+
+    def ledger(self, term):
+        """Water ledger term in cubic metres (storage terms are instantaneous)."""
+        cdef double value=0
+        _check(swmm_gw2d_get_ledger(_h(self), int(GroundwaterLedger(term)), &value))
+        return value
+
+    @property
+    def continuity_error(self):
+        """Water continuity residual in cubic metres, not a percentage."""
+        cdef double value=0
+        _check(swmm_gw2d_get_continuity_error(_h(self), &value))
+        return value
+
+    @property
+    def tier_histogram(self):
+        """Owned platform C-long array of cumulative firings per LTS tier."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int capacity=16, written=0
+        cdef np.ndarray out
+        while True:
+            out = np.empty(capacity, dtype=np.dtype('l'))
+            _check(swmm_gw2d_get_tier_histogram(h, out.data, capacity, &written))
+            if written < capacity:
+                return out[:written].copy()
+            capacity *= 2
+
+    @property
+    def species(self):
+        """Transported names in native policy order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, index
+        cdef char name[512]
+        _check(swmm_gw2d_species_count(h, &count))
+        names = []
+        for index in range(count):
+            _check(swmm_gw2d_species_name(h, index, name, 512))
+            names.append(name.decode('utf-8'))
+        return tuple(names)
+
+    def concentrations(self, zone, int species):
+        """Per-cell species mass per m³ of zone water; dry zones report zero."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int n=0, written=0, selected=int(GroundwaterZone(zone))
+        _check(swmm_gw2d_get_dimensions(h, &n, NULL))
+        cdef np.ndarray[double, ndim=1] out = np.empty(n, dtype=np.float64)
+        _check(swmm_gw2d_get_cell_conc(h, selected, species, out.data, n, &written))
+        return out[:written].copy()
+
+    def species_ledger(self, int species, term):
+        """Cumulative transported-species ledger term in the species' mass units."""
+        cdef double value=0
+        _check(swmm_gw2d_get_species_ledger(_h(self), species,
+                                          int(GroundwaterSpeciesLedger(term)), &value))
+        return value
diff --git a/python/openswmm/engine/_gw_transport.pyi b/python/openswmm/engine/_gw_transport.pyi
new file mode 100644
index 000000000..702eef5d9
--- /dev/null
+++ b/python/openswmm/engine/_gw_transport.pyi
@@ -0,0 +1,121 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from collections.abc import Iterator, MutableMapping
+from typing import Any
+from os import PathLike
+from ._enums import CellScope, GroundwaterTransportZone
+
+@dataclass(frozen=True)
+class GroundwaterParameters:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    cell: int = -1
+    rho_s: float = 2650.0
+    c_s: float = 880.0
+    lambda_s: float = 2.0
+    a_s: float = 0.0
+    alpha_L: float = 1.0
+    alpha_T: float = 0.1
+    D_m: float = 1e-9
+    D_v: float = 1e-9
+    geo_flux: float = 0.065
+    tag: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSorption:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    tag: str = ''
+    cell: int = -1
+    species: str = ''
+    kd: float = 0.0
+    decay: float = -1.0
+
+
+@dataclass(frozen=True)
+class GroundwaterInitialQuality:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    tag: str = ''
+    cell: int = -1
+    zone: GroundwaterTransportZone = GroundwaterTransportZone.SAT
+    layer: int = -1
+    species: str = ''
+    value: float = 0.0
+
+
+@dataclass(frozen=True)
+class GroundwaterBoundary:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    cell: int = 0
+    edge: int = 0
+    species: str = ''
+    kind: str = 'CONC'
+    value: float = 0.0
+    timeseries: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSource:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    name: str = ''
+    scope: CellScope = CellScope.CELL
+    tag: str = ''
+    cell: int = 0
+    flow: float = 0.0
+    flow_timeseries: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSourceTerm:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    species: str = ''
+    kind: str = 'CONC'
+    value: float = 0.0
+    timeseries: str = ''
+
+
+class GroundwaterTransportOptions(MutableMapping[str, str]):
+    """Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling."""
+    def __init__(self, owner: Any) -> None: ...
+    def __getitem__(self, key: str) -> str: ...
+    def __setitem__(self, key: str, value: object) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
+
+
+class GroundwaterTransport:
+    def __init__(self, owner: Any) -> None: ...
+    @property
+    def options(self) -> GroundwaterTransportOptions: ...
+    @property
+    def authored(self) -> bool: ...
+    @property
+    def parameters(self) -> tuple[GroundwaterParameters, ...]: ...
+    def set_parameters(self, row: GroundwaterParameters) -> None: ...
+    def remove_parameters(self, index: int) -> None: ...
+    @property
+    def sorption(self) -> tuple[GroundwaterSorption, ...]: ...
+    def set_sorption(self, row: GroundwaterSorption) -> None: ...
+    def remove_sorption(self, index: int) -> None: ...
+    @property
+    def initial_quality(self) -> tuple[GroundwaterInitialQuality, ...]: ...
+    def set_initial_quality(self, row: GroundwaterInitialQuality) -> None: ...
+    def remove_initial_quality(self, index: int) -> None: ...
+    @property
+    def boundaries(self) -> tuple[GroundwaterBoundary, ...]: ...
+    def set_boundary(self, row: GroundwaterBoundary) -> None: ...
+    def remove_boundary(self, index: int) -> None: ...
+    @property
+    def sources(self) -> tuple[GroundwaterSource, ...]: ...
+    def set_source(self, row: GroundwaterSource) -> None: ...
+    def remove_source(self, index: int) -> None: ...
+    def source_species(self, source_index: int) -> tuple[GroundwaterSourceTerm, ...]: ...
+    def set_source_species(self, source_index: int, row: GroundwaterSourceTerm) -> None: ...
+    def remove_source_species(self, source_index: int, index: int) -> None: ...
+    @property
+    def initial_quality_file(self) -> str: ...
+    @initial_quality_file.setter
+    def initial_quality_file(self, path: str | PathLike[str] | None) -> None: ...
diff --git a/python/openswmm/engine/_gw_transport.pyx b/python/openswmm/engine/_gw_transport.pyx
new file mode 100644
index 000000000..f6001cd2a
--- /dev/null
+++ b/python/openswmm/engine/_gw_transport.pyx
@@ -0,0 +1,366 @@
+"""Groundwater transport authoring; runtime results live on Groundwater.
+
+Setters require BUILDING/OPENED. Cells and local edges are zero-based; explicit
+LAYER zones use a one-based layer number. Source flow is m³/s; parameter rows
+use SI thermal/material units, and sorption uses L/kg and 1/day.
+"""
+from dataclasses import dataclass
+from collections.abc import MutableMapping
+from ._access import EngineView
+from ._common cimport SWMM_Engine, _check
+from ._enums import CellScope, GroundwaterTransportZone
+
+cdef extern from "openswmm/engine/openswmm_gw_transport.h":
+    ctypedef struct SWMM_GwParams:
+        int scope
+        int cell
+        double rho_s
+        double c_s
+        double lambda_s
+        double a_s
+        double alpha_L
+        double alpha_T
+        double D_m
+        double D_v
+        double geo_flux
+    int swmm_gw_transport_option_get(SWMM_Engine engine, const char* key, char* buf, int buflen)
+    int swmm_gw_transport_option_set(SWMM_Engine engine, const char* key, const char* value)
+    int swmm_gw_transport_authored(SWMM_Engine engine)
+    int swmm_gw_params_count(SWMM_Engine engine)
+    int swmm_gw_params_get(SWMM_Engine engine, int idx, SWMM_GwParams* row, char* tag_buf, int tag_len)
+    int swmm_gw_params_set(SWMM_Engine engine, const SWMM_GwParams* row, const char* tag)
+    int swmm_gw_params_remove(SWMM_Engine engine, int idx)
+    int swmm_gw_sorption_count(SWMM_Engine engine)
+    int swmm_gw_sorption_get(SWMM_Engine engine, int idx, int* scope, char* tag_buf, int tag_len, int* cell, char* species_buf, int species_len, double* kd, double* decay)
+    int swmm_gw_sorption_set(SWMM_Engine engine, int scope, const char* tag, int cell, const char* species, double kd, double decay)
+    int swmm_gw_sorption_remove(SWMM_Engine engine, int idx)
+    int swmm_gw_init_quality_count(SWMM_Engine engine)
+    int swmm_gw_init_quality_get(SWMM_Engine engine, int idx, int* scope, char* tag_buf, int tag_len, int* cell, int* zone, int* layer, char* species_buf, int species_len, double* value)
+    int swmm_gw_init_quality_set(SWMM_Engine engine, int scope, const char* tag, int cell, int zone, int layer, const char* species, double value)
+    int swmm_gw_init_quality_remove(SWMM_Engine engine, int idx)
+    int swmm_gw_init_quality_file_get(SWMM_Engine engine, char* buf, int buflen)
+    int swmm_gw_init_quality_file_set(SWMM_Engine engine, const char* path)
+    int swmm_gw_boundary_quality_count(SWMM_Engine engine)
+    int swmm_gw_boundary_quality_get(SWMM_Engine engine, int idx, int* cell, int* edge, char* species_buf, int species_len, char* kind_buf, int kind_len, double* value, char* ts_buf, int ts_len)
+    int swmm_gw_boundary_quality_set(SWMM_Engine engine, int cell, int edge, const char* species, const char* kind, double value, const char* ts_name)
+    int swmm_gw_boundary_quality_remove(SWMM_Engine engine, int idx)
+    int swmm_gw_source_count(SWMM_Engine engine)
+    int swmm_gw_source_get(SWMM_Engine engine, int idx, char* name_buf, int name_len, int* scope, char* tag_buf, int tag_len, int* cell, double* flow, char* flow_ts_buf, int flow_ts_len)
+    int swmm_gw_source_set(SWMM_Engine engine, const char* name, int scope, const char* tag, int cell, double flow, const char* flow_ts)
+    int swmm_gw_source_remove(SWMM_Engine engine, int idx)
+    int swmm_gw_source_species_count(SWMM_Engine engine, int src_idx)
+    int swmm_gw_source_species_get(SWMM_Engine engine, int src_idx, int term_idx, char* species_buf, int species_len, char* kind_buf, int kind_len, double* value, char* ts_buf, int ts_len)
+    int swmm_gw_source_species_set(SWMM_Engine engine, int src_idx, const char* species, const char* kind, double value, const char* ts_name)
+    int swmm_gw_source_species_remove(SWMM_Engine engine, int src_idx, int term_idx)
+
+cdef inline SWMM_Engine _h(view):
+    return view._address()
+
+@dataclass(frozen=True)
+class GroundwaterParameters:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    cell: int = -1
+    rho_s: float = 2650.0
+    c_s: float = 880.0
+    lambda_s: float = 2.0
+    a_s: float = 0.0
+    alpha_L: float = 1.0
+    alpha_T: float = 0.1
+    D_m: float = 1e-9
+    D_v: float = 1e-9
+    geo_flux: float = 0.065
+    tag: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSorption:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    tag: str = ''
+    cell: int = -1
+    species: str = ''
+    kd: float = 0.0
+    decay: float = -1.0
+
+
+@dataclass(frozen=True)
+class GroundwaterInitialQuality:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    scope: CellScope = CellScope.GLOBAL
+    tag: str = ''
+    cell: int = -1
+    zone: GroundwaterTransportZone = GroundwaterTransportZone.SAT
+    layer: int = -1
+    species: str = ''
+    value: float = 0.0
+
+
+@dataclass(frozen=True)
+class GroundwaterBoundary:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    cell: int = 0
+    edge: int = 0
+    species: str = ''
+    kind: str = 'CONC'
+    value: float = 0.0
+    timeseries: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSource:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    name: str = ''
+    scope: CellScope = CellScope.CELL
+    tag: str = ''
+    cell: int = 0
+    flow: float = 0.0
+    flow_timeseries: str = ''
+
+
+@dataclass(frozen=True)
+class GroundwaterSourceTerm:
+    """Immutable authored row; replace fields and submit it with the matching setter."""
+    species: str = ''
+    kind: str = 'CONC'
+    value: float = 0.0
+    timeseries: str = ''
+
+
+class GroundwaterTransportOptions(EngineView, MutableMapping):
+    """Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling."""
+    _keys = ('TRANSPORT_POLLUTANTS', 'TRANSPORT_MSX', 'TRANSPORT_AGE',
+             'TRANSPORT_TEMPERATURE', 'DISPERSION', 'CONDUCTION',
+             'SURFACE_THERMAL_BC', 'DEEP_THERMAL_BC', 'THERMAL_MIXING', 'C_DIFF')
+    def __len__(self):
+        return len(self._keys)
+    def __iter__(self):
+        return iter(self._keys)
+    def __getitem__(self, key):
+        cdef bytes name = str(key).encode('utf-8')
+        cdef bytearray buffer = bytearray(256)
+        while True:
+            _check(swmm_gw_transport_option_get(_h(self), name, buffer, len(buffer)))
+            value = bytes(buffer).split(b'\0', 1)[0]
+            if len(value) < len(buffer) - 1:
+                return value.decode('utf-8')
+            buffer = bytearray(len(buffer) * 2)
+    def __setitem__(self, key, value):
+        cdef bytes name = str(key).encode('utf-8')
+        cdef bytes text = str(value).encode('utf-8')
+        _check(swmm_gw_transport_option_set(_h(self), name, text))
+    def __delitem__(self, key):
+        raise TypeError('Transport options cannot be deleted; assign an explicit value')
+
+class GroundwaterTransport(EngineView):
+    """``surface2d.groundwater.transport`` authored row tables.
+
+    Getters return immutable snapshots, setters upsert by native row keys, and
+    removing a row shifts subsequent indices. Check the engine capability
+    matrix for which species and processes are active in a selected backend.
+    """
+    @property
+    def options(self):
+        self._address()
+        return GroundwaterTransportOptions(self._owner)
+
+    @property
+    def authored(self):
+        """Whether any groundwater transport section was authored."""
+        return bool(swmm_gw_transport_authored(_h(self)))
+
+    @property
+    def parameters(self):
+        """Thermal/material/dispersion parameter snapshots, all in native SI units."""
+        cdef SWMM_Engine h = _h(self)
+        cdef SWMM_GwParams row
+        cdef char tag[512]
+        rows = []
+        for index in range(swmm_gw_params_count(h)):
+            _check(swmm_gw_params_get(h, index, &row, tag, 512))
+            rows.append(GroundwaterParameters(CellScope(row.scope), row.cell,
+                row.rho_s, row.c_s, row.lambda_s, row.a_s, row.alpha_L, row.alpha_T, row.D_m, row.D_v, row.geo_flux, tag.decode('utf-8')))
+        return tuple(rows)
+
+    def set_parameters(self, row):
+        """Upsert material parameters by scope/tag/cell; edit before initialization."""
+        cdef SWMM_GwParams value
+        cdef bytes tag = row.tag.encode('utf-8')
+        value.scope = int(CellScope(row.scope))
+        value.cell = row.cell
+        value.rho_s = row.rho_s
+        value.c_s = row.c_s
+        value.lambda_s = row.lambda_s
+        value.a_s = row.a_s
+        value.alpha_L = row.alpha_L
+        value.alpha_T = row.alpha_T
+        value.D_m = row.D_m
+        value.D_v = row.D_v
+        value.geo_flux = row.geo_flux
+        _check(swmm_gw_params_set(_h(self), &value, tag))
+
+    def remove_parameters(self, int index):
+        _check(swmm_gw_params_remove(_h(self), index))
+
+    @property
+    def sorption(self):
+        """Immutable authored row snapshots in native order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int scope=0
+        cdef char tag[512]
+        cdef int cell=0
+        cdef char species[512]
+        cdef double kd=0
+        cdef double decay=0
+        cdef int count = swmm_gw_sorption_count(h)
+        if count < 0:
+            raise IndexError("Invalid native row owner/index")
+        rows = []
+        for index in range(count):
+            _check(swmm_gw_sorption_get(h, index, &scope, tag, 512, &cell, species, 512, &kd, &decay))
+            rows.append(GroundwaterSorption(CellScope(scope), tag.decode('utf-8'), cell, species.decode('utf-8'), kd, decay))
+        return tuple(rows)
+
+    def set_sorption(self, row):
+        """Upsert an authored row; requires BUILDING or OPENED."""
+        cdef bytes tag = row.tag.encode('utf-8')
+        cdef bytes species = row.species.encode('utf-8')
+        _check(swmm_gw_sorption_set(_h(self), int(CellScope(row.scope)), tag, row.cell, species, row.kd, row.decay))
+
+    def remove_sorption(self, int index):
+        """Remove a row; subsequent indices shift."""
+        _check(swmm_gw_sorption_remove(_h(self), index))
+
+    @property
+    def initial_quality(self):
+        """Immutable authored row snapshots in native order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int scope=0
+        cdef char tag[512]
+        cdef int cell=0
+        cdef int zone=0
+        cdef int layer=0
+        cdef char species[512]
+        cdef double value=0
+        cdef int count = swmm_gw_init_quality_count(h)
+        if count < 0:
+            raise IndexError("Invalid native row owner/index")
+        rows = []
+        for index in range(count):
+            _check(swmm_gw_init_quality_get(h, index, &scope, tag, 512, &cell, &zone, &layer, species, 512, &value))
+            rows.append(GroundwaterInitialQuality(CellScope(scope), tag.decode('utf-8'), cell, GroundwaterTransportZone(zone), layer, species.decode('utf-8'), value))
+        return tuple(rows)
+
+    def set_initial_quality(self, row):
+        """Upsert an authored row; requires BUILDING or OPENED."""
+        cdef bytes tag = row.tag.encode('utf-8')
+        cdef bytes species = row.species.encode('utf-8')
+        _check(swmm_gw_init_quality_set(_h(self), int(CellScope(row.scope)), tag, row.cell, int(GroundwaterTransportZone(row.zone)), row.layer, species, row.value))
+
+    def remove_initial_quality(self, int index):
+        """Remove a row; subsequent indices shift."""
+        _check(swmm_gw_init_quality_remove(_h(self), index))
+
+    @property
+    def boundaries(self):
+        """Immutable authored row snapshots in native order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int cell=0
+        cdef int edge=0
+        cdef char species[512]
+        cdef char kind[512]
+        cdef double value=0
+        cdef char timeseries[512]
+        cdef int count = swmm_gw_boundary_quality_count(h)
+        if count < 0:
+            raise IndexError("Invalid native row owner/index")
+        rows = []
+        for index in range(count):
+            _check(swmm_gw_boundary_quality_get(h, index, &cell, &edge, species, 512, kind, 512, &value, timeseries, 512))
+            rows.append(GroundwaterBoundary(cell, edge, species.decode('utf-8'), kind.decode('utf-8'), value, timeseries.decode('utf-8')))
+        return tuple(rows)
+
+    def set_boundary(self, row):
+        """Upsert an authored row; requires BUILDING or OPENED."""
+        cdef bytes species = row.species.encode('utf-8')
+        cdef bytes kind = row.kind.encode('utf-8')
+        cdef bytes timeseries = row.timeseries.encode('utf-8')
+        _check(swmm_gw_boundary_quality_set(_h(self), row.cell, row.edge, species, kind, row.value, timeseries))
+
+    def remove_boundary(self, int index):
+        """Remove a row; subsequent indices shift."""
+        _check(swmm_gw_boundary_quality_remove(_h(self), index))
+
+    @property
+    def sources(self):
+        """Immutable authored row snapshots in native order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef char name[512]
+        cdef int scope=0
+        cdef char tag[512]
+        cdef int cell=0
+        cdef double flow=0
+        cdef char flow_timeseries[512]
+        cdef int count = swmm_gw_source_count(h)
+        if count < 0:
+            raise IndexError("Invalid native row owner/index")
+        rows = []
+        for index in range(count):
+            _check(swmm_gw_source_get(h, index, name, 512, &scope, tag, 512, &cell, &flow, flow_timeseries, 512))
+            rows.append(GroundwaterSource(name.decode('utf-8'), CellScope(scope), tag.decode('utf-8'), cell, flow, flow_timeseries.decode('utf-8')))
+        return tuple(rows)
+
+    def set_source(self, row):
+        """Upsert an authored row; requires BUILDING or OPENED."""
+        cdef bytes name = row.name.encode('utf-8')
+        cdef bytes tag = row.tag.encode('utf-8')
+        cdef bytes flow_timeseries = row.flow_timeseries.encode('utf-8')
+        _check(swmm_gw_source_set(_h(self), name, int(CellScope(row.scope)), tag, row.cell, row.flow, flow_timeseries))
+
+    def remove_source(self, int index):
+        """Remove a row; subsequent indices shift."""
+        _check(swmm_gw_source_remove(_h(self), index))
+
+    def source_species(self, int source_index):
+        """Immutable authored row snapshots in native order."""
+        cdef SWMM_Engine h = _h(self)
+        cdef char species[512]
+        cdef char kind[512]
+        cdef double value=0
+        cdef char timeseries[512]
+        cdef int count = swmm_gw_source_species_count(h, source_index)
+        if count < 0:
+            raise IndexError("Invalid native row owner/index")
+        rows = []
+        for index in range(count):
+            _check(swmm_gw_source_species_get(h, source_index, index, species, 512, kind, 512, &value, timeseries, 512))
+            rows.append(GroundwaterSourceTerm(species.decode('utf-8'), kind.decode('utf-8'), value, timeseries.decode('utf-8')))
+        return tuple(rows)
+
+    def set_source_species(self, int source_index, row):
+        """Upsert an authored row; requires BUILDING or OPENED."""
+        cdef bytes species = row.species.encode('utf-8')
+        cdef bytes kind = row.kind.encode('utf-8')
+        cdef bytes timeseries = row.timeseries.encode('utf-8')
+        _check(swmm_gw_source_species_set(_h(self), source_index, species, kind, row.value, timeseries))
+
+    def remove_source_species(self, int source_index, int index):
+        """Remove a row; subsequent indices shift."""
+        _check(swmm_gw_source_species_remove(_h(self), source_index, index))
+
+    @property
+    def initial_quality_file(self):
+        """Authored sidecar path; changing it records a reference for the next open."""
+        cdef bytearray buffer = bytearray(256)
+        while True:
+            _check(swmm_gw_init_quality_file_get(_h(self), buffer, len(buffer)))
+            value = bytes(buffer).split(b'\0', 1)[0]
+            if len(value) < len(buffer) - 1:
+                return value.decode('utf-8')
+            buffer = bytearray(len(buffer) * 2)
+
+    @initial_quality_file.setter
+    def initial_quality_file(self, path):
+        import os
+        cdef bytes value = os.fsencode(path) if path is not None else b''
+        _check(swmm_gw_init_quality_file_set(_h(self), value))
diff --git a/python/openswmm/engine/_heat.pyi b/python/openswmm/engine/_heat.pyi
new file mode 100644
index 000000000..22dec7bcb
--- /dev/null
+++ b/python/openswmm/engine/_heat.pyi
@@ -0,0 +1,107 @@
+"""Type stubs for :mod:`openswmm.engine._heat`."""
+
+from collections.abc import Iterator
+from typing import NamedTuple, Union
+
+from ._enums import (
+    HeatCloudParam, HeatFluxModule, HeatRadiativeParam, HeatShortwaveMode,
+    HeatSolarParam, HeatSourceKind,
+)
+from ._solver import Solver
+
+
+_Node = Union[int, str]
+_Module = Union[HeatFluxModule, int, str]
+_Radiative = Union[HeatRadiativeParam, int, str]
+_Solar = Union[HeatSolarParam, int, str]
+_Cloud = Union[HeatCloudParam, int, str]
+_Source = Union[HeatSourceKind, int, str]
+
+
+class HeatNodeOverride(NamedTuple):
+    source: HeatSourceKind
+    node_index: int
+    temp_c: float
+
+
+class _HeatModules:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatFluxModule]: ...
+    def __getitem__(self, key: _Module) -> bool: ...
+    def __setitem__(self, key: _Module, value: bool) -> None: ...
+
+
+class _HeatRadiative:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatRadiativeParam]: ...
+    def __getitem__(self, key: _Radiative) -> float: ...
+    def __setitem__(self, key: _Radiative, value: float) -> None: ...
+
+
+class _HeatSolar:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatSolarParam]: ...
+    def __getitem__(self, key: _Solar) -> float: ...
+    def __setitem__(self, key: _Solar, value: float) -> None: ...
+
+
+class _HeatCloud:
+    @property
+    def timeseries(self) -> str: ...
+
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatCloudParam]: ...
+    def __getitem__(self, key: _Cloud) -> float: ...
+    def __setitem__(self, key: _Cloud, value: float) -> None: ...
+
+    configured: bool
+    current: float
+
+    def set_timeseries(self, name: str) -> None: ...
+    def clear(self) -> None: ...
+
+
+class _HeatSources:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatSourceKind]: ...
+    def __getitem__(self, key: _Source) -> float: ...
+    def __setitem__(self, key: _Source, temp_c: float) -> None: ...
+    def __contains__(self, key: object) -> bool: ...
+    def is_configured(self, source: _Source) -> bool: ...
+    def clear(self, source: _Source) -> None: ...
+    def effective(self, source: _Source, node: _Node) -> float: ...
+
+
+class _HeatNodeOverrides:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[HeatNodeOverride]: ...
+    def __getitem__(self, row_index: int) -> HeatNodeOverride: ...
+    def set(self, source: _Source, node: _Node, temp_c: float) -> None: ...
+    def remove(self, row_index: int) -> None: ...
+
+
+class Heat:
+    @property
+    def shortwave_timeseries(self) -> str: ...
+
+    def __init__(self, solver: Solver) -> None: ...
+
+    @property
+    def enabled(self) -> bool: ...
+    modules: _HeatModules
+    radiative: _HeatRadiative
+    shortwave_mode: HeatShortwaveMode
+    current_shortwave: float
+    solar: _HeatSolar
+    solar_sited: bool
+    cloud: _HeatCloud
+    sources: _HeatSources
+    node_overrides: _HeatNodeOverrides
+
+    def set_shortwave_timeseries(self, name: str) -> None: ...
diff --git a/python/openswmm/engine/_heat.pyx b/python/openswmm/engine/_heat.pyx
new file mode 100644
index 000000000..25cf7b1c9
--- /dev/null
+++ b/python/openswmm/engine/_heat.pyx
@@ -0,0 +1,827 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Heat transport (Pythonic v1 surface)
+====================================
+
+:author: Caleb Buahin
+:copyright: Copyright (c) 2026 Caleb Buahin
+:license: Apache-2.0
+
+``solver.heat`` is the editable heat-transport configuration surface: the
+``[HEAT_FLUXES]`` module toggles, the ``[RADIATIVE_FLUXES]``,
+``[SOLAR_RADIATION]`` and ``[CLOUD_COVER]`` parameter blocks, and the
+``[HEAT_SOURCES]`` inlet-temperature table (a global degC per water source
+plus node-scope overrides).
+
+**Edits are live.** Setters mutate engine state and the flux modules re-read
+the configuration every step, so a mid-run edit takes effect on the next
+routing step.
+
+**Values are refused, not clamped.** Every range check mirrors the deck
+parser exactly, so a value the ``.inp`` rejects is a value this API rejects,
+and a refused write does not take effect at all — it raises
+:class:`~openswmm.engine.EngineError` and leaves the previous value in place.
+
+.. code-block:: python
+
+    from openswmm.engine import (
+        Solver, HeatFluxModule, HeatShortwaveMode, HeatSolarParam,
+        HeatRadiativeParam, HeatSourceKind)
+
+    with Solver("model.inp") as s:
+        s.heat.modules[HeatFluxModule.RADIATIVE_EXCHANGE] = True
+        s.heat.radiative[HeatRadiativeParam.ALBEDO] = 0.08
+
+        # COMPUTED shortwave requires an explicit site: latitude AND longitude.
+        s.heat.solar[HeatSolarParam.LATITUDE] = 41.74
+        s.heat.solar[HeatSolarParam.LONGITUDE] = -111.83
+        assert s.heat.solar_sited
+        s.heat.shortwave_mode = HeatShortwaveMode.COMPUTED
+
+        s.heat.sources[HeatSourceKind.DWF] = 18.5
+        s.heat.node_overrides.set(HeatSourceKind.DWF, "J1", 22.0)
+        print(s.heat.sources.effective(HeatSourceKind.DWF, "J1"))
+"""
+
+# cython: language_level=3
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from ._common cimport *
+from ._enums import (
+    HeatCloudParam, HeatFluxModule, HeatRadiativeParam, HeatShortwaveMode,
+    HeatSolarParam, HeatSourceKind)
+
+
+cdef inline SWMM_Engine _h(solver):
+    return solver.handle
+
+
+cdef inline int _resolve_node(solver, key) except -1:
+    return _resolve_index(
+        _h(solver), key, swmm_node_index, swmm_node_count, "Node")
+
+
+def _member(enum_cls, key):
+    """Coerce *key* (member, int code, or member name) to *enum_cls*.
+
+    :param enum_cls: The target ``IntEnum`` class.
+    :param key: An enum member, its integer code, or its member name.
+    :returns: The matching enum member.
+    :raises KeyError: *key* names no member; the message lists the valid ones.
+    """
+    if isinstance(key, enum_cls):
+        return key
+    try:
+        if isinstance(key, str):
+            return enum_cls[key.upper()]
+        return enum_cls(key)
+    except (KeyError, ValueError):
+        pass
+    valid = ", ".join(m.name for m in enum_cls)
+    raise KeyError(
+        f"{key!r} is not a valid {enum_cls.__name__}; valid members: {valid}")
+
+
+class HeatNodeOverride(NamedTuple):
+    """One ``[HEAT_SOURCES]`` NODE-scope override row.
+
+    :ivar source: The :class:`HeatSourceKind` the row overrides. Only
+        ``DWF`` and ``EXTERNAL_INFLOW`` can appear here (the H1 scope rule).
+    :ivar node_index: Zero-based index of the node the override applies to.
+    :ivar temp_c: Inlet temperature for that (source, node) pair, degC.
+    """
+
+    source: HeatSourceKind
+    node_index: int
+    temp_c: float
+
+
+# =============================================================================
+# [HEAT_FLUXES]
+# =============================================================================
+
+class _HeatModules:
+    """``solver.heat.modules`` — mapping keyed by :class:`HeatFluxModule`.
+
+    Each flux module of heat plan section 2 toggles independently::
+
+        s.heat.modules[HeatFluxModule.SURFACE_EXCHANGE] = True
+        if s.heat.modules[HeatFluxModule.RADIATIVE_EXCHANGE]:
+            ...
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return len(HeatFluxModule)
+
+    def __iter__(self) -> Iterator[HeatFluxModule]:
+        return iter(HeatFluxModule)
+
+    def __getitem__(self, key) -> bool:
+        """Is the ``[HEAT_FLUXES]`` module *key* on?
+
+        :param key: A :class:`HeatFluxModule` member, code, or name.
+        :returns: ``True`` when the module is enabled.
+        :raises KeyError: *key* is not a valid :class:`HeatFluxModule`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int on = 0
+        module = _member(HeatFluxModule, key)
+        _check(swmm_heat_get_module(_h(self._solver), int(module), &on))
+        return on != 0
+
+    def __setitem__(self, key, value) -> None:
+        """Turn the ``[HEAT_FLUXES]`` module *key* on or off.
+
+        The edit is live: the module is re-read on the next routing step.
+
+        :param key: A :class:`HeatFluxModule` member, code, or name.
+        :param value: ``True`` to enable the module, ``False`` to disable it.
+        :raises KeyError: *key* is not a valid :class:`HeatFluxModule`.
+        :raises EngineError: The engine refused the write.
+        """
+        module = _member(HeatFluxModule, key)
+        _check(swmm_heat_set_module(
+            _h(self._solver), int(module), 1 if value else 0))
+
+    def __repr__(self) -> str:
+        try:
+            on = [m.name for m in HeatFluxModule if self[m]]
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# [RADIATIVE_FLUXES]
+# =============================================================================
+
+class _HeatRadiative:
+    """``solver.heat.radiative`` — mapping keyed by :class:`HeatRadiativeParam`.
+
+    ``SHORTWAVE`` is W/m2; every other parameter is a dimensionless fraction
+    in ``[0, 1]``.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return len(HeatRadiativeParam)
+
+    def __iter__(self) -> Iterator[HeatRadiativeParam]:
+        return iter(HeatRadiativeParam)
+
+    def __getitem__(self, key) -> float:
+        """Read one ``[RADIATIVE_FLUXES]`` parameter.
+
+        :param key: A :class:`HeatRadiativeParam` member, code, or name.
+        :returns: ``SHORTWAVE`` in W/m2; all others a fraction in ``[0, 1]``.
+        :raises KeyError: *key* is not a valid :class:`HeatRadiativeParam`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double value = 0.0
+        param = _member(HeatRadiativeParam, key)
+        _check(swmm_heat_get_radiative(_h(self._solver), int(param), &value))
+        return value
+
+    def __setitem__(self, key, double value) -> None:
+        """Write one ``[RADIATIVE_FLUXES]`` parameter.
+
+        Values are **refused, not clamped** — the parser's own rule, so the
+        API and the deck agree, and a refused write does not take effect.
+
+        :param key: A :class:`HeatRadiativeParam` member, code, or name.
+        :param value: ``SHORTWAVE`` in W/m2 (must be >= 0); every other
+            parameter a fraction in ``[0, 1]``.
+        :raises KeyError: *key* is not a valid :class:`HeatRadiativeParam`.
+        :raises EngineError: A fraction is outside ``[0, 1]``; ``SHORTWAVE``
+            is negative; or ``SHORTWAVE`` is written while
+            :attr:`Heat.shortwave_mode` is not
+            :attr:`HeatShortwaveMode.CONSTANT` — a constant is not read in the
+            other two modes, and storing one there would look configured while
+            changing nothing. Switch the mode first.
+        """
+        param = _member(HeatRadiativeParam, key)
+        _check(swmm_heat_set_radiative(_h(self._solver), int(param), value))
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# [SOLAR_RADIATION]
+# =============================================================================
+
+class _HeatSolar:
+    """``solver.heat.solar`` — mapping keyed by :class:`HeatSolarParam`.
+
+    These parameters are consulted under
+    :attr:`HeatShortwaveMode.COMPUTED` only.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return len(HeatSolarParam)
+
+    def __iter__(self) -> Iterator[HeatSolarParam]:
+        return iter(HeatSolarParam)
+
+    def __getitem__(self, key) -> float:
+        """Read one ``[SOLAR_RADIATION]`` parameter.
+
+        :param key: A :class:`HeatSolarParam` member, code, or name.
+        :returns: ``LATITUDE`` / ``LONGITUDE`` in degrees (+N / +E),
+            ``TIMEZONE`` in hours from UTC (+E), ``ELEVATION`` in metres,
+            ``PRECIP_WATER`` and ``OZONE`` in cm, the turbidities as Bird
+            aerosol optical depths, ``GROUND_ALBEDO`` as a fraction.
+        :raises KeyError: *key* is not a valid :class:`HeatSolarParam`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double value = 0.0
+        param = _member(HeatSolarParam, key)
+        _check(swmm_heat_get_solar(_h(self._solver), int(param), &value))
+        return value
+
+    def __setitem__(self, key, double value) -> None:
+        """Write one ``[SOLAR_RADIATION]`` parameter.
+
+        Writing ``LATITUDE`` or ``LONGITUDE`` also marks it *explicitly
+        provided*, which is exactly what
+        :attr:`HeatShortwaveMode.COMPUTED` checks for — see
+        :attr:`Heat.solar_sited`.
+
+        :param key: A :class:`HeatSolarParam` member, code, or name.
+        :param value: ``LATITUDE`` degrees ``[-90, 90]``, ``LONGITUDE``
+            degrees ``[-180, 180]``, ``TIMEZONE`` hours from UTC,
+            ``ELEVATION`` metres ``[-500, 9000]`` (below sea level is legal;
+            never written means the climate state's elevation is used),
+            ``GROUND_ALBEDO`` the **land** albedo ``[0, 1]`` — not the water's
+            :attr:`HeatRadiativeParam.ALBEDO`.
+        :raises KeyError: *key* is not a valid :class:`HeatSolarParam`.
+        :raises EngineError: *value* is out of range. Refused, not clamped.
+        """
+        param = _member(HeatSolarParam, key)
+        _check(swmm_heat_set_solar(_h(self._solver), int(param), value))
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# [CLOUD_COVER]
+# =============================================================================
+
+class _HeatCloud:
+    """``solver.heat.cloud`` — mapping keyed by :class:`HeatCloudParam`.
+
+    Writing any parameter marks cloud cover as configured; :meth:`clear`
+    removes the section entirely and restores clear sky.
+    """
+
+    @property
+    def timeseries(self):
+        """Bound timeseries name, or an empty string when none is bound."""
+        cdef bytearray buffer = bytearray(256)
+        while True:
+            _check(swmm_heat_get_cloud_timeseries(_h(self._solver), buffer, len(buffer)))
+            value = bytes(buffer).split(b'\0', 1)[0]
+            if len(value) < len(buffer) - 1:
+                return value.decode('utf-8')
+            buffer = bytearray(len(buffer) * 2)
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return len(HeatCloudParam)
+
+    def __iter__(self) -> Iterator[HeatCloudParam]:
+        return iter(HeatCloudParam)
+
+    def __getitem__(self, key) -> float:
+        """Read one ``[CLOUD_COVER]`` parameter.
+
+        :param key: A :class:`HeatCloudParam` member, code, or name.
+        :returns: ``FRACTION`` as C in ``[0, 1]``; the others as the
+            Kasten-Czeplak ``k`` / ``n`` and Bolz ``k_lw`` coefficients
+            (dimensionless).
+        :raises KeyError: *key* is not a valid :class:`HeatCloudParam`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double value = 0.0
+        param = _member(HeatCloudParam, key)
+        _check(swmm_heat_get_cloud(_h(self._solver), int(param), &value))
+        return value
+
+    def __setitem__(self, key, double value) -> None:
+        """Write one ``[CLOUD_COVER]`` parameter, marking cloud cover configured.
+
+        :param key: A :class:`HeatCloudParam` member, code, or name.
+        :param value: ``FRACTION`` in ``[0, 1]`` — a fraction, **not** a
+            percent; the coefficients must be non-negative.
+        :raises KeyError: *key* is not a valid :class:`HeatCloudParam`.
+        :raises EngineError: ``FRACTION`` is outside ``[0, 1]`` or a
+            coefficient is negative. Refused, not clamped.
+        """
+        param = _member(HeatCloudParam, key)
+        _check(swmm_heat_set_cloud(_h(self._solver), int(param), value))
+
+    # ---- Cloud cover ------------------------------------------------
+
+    @property
+    def configured(self) -> bool:
+        """Is a ``[CLOUD_COVER]`` section in effect?
+
+        :returns: ``True`` when cloud cover is configured.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int configured = 0
+        _check(swmm_heat_get_cloud_configured(_h(self._solver), &configured))
+        return configured != 0
+
+    @property
+    def current(self) -> float:
+        """Cloud fraction in effect at the **current** step, ``[0, 1]``.
+
+        Read-only: this is state, not configuration.
+
+        :returns: The current-step cloud fraction.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double fraction = 0.0
+        _check(swmm_heat_get_current_cloud(_h(self._solver), &fraction))
+        return fraction
+
+    def set_timeseries(self, str name) -> None:
+        """Bind a ``[TIMESERIES]`` by name as the cloud-fraction record.
+
+        :param name: Id of an existing ``[TIMESERIES]``.
+        :raises EngineError: No timeseries of that name exists.
+        """
+        cdef bytes b = name.encode('utf-8')
+        _check(swmm_heat_set_cloud_timeseries(_h(self._solver), b))
+
+    def clear(self) -> None:
+        """Clear ``[CLOUD_COVER]`` entirely — back to clear sky.
+
+        This restores the exact H3 longwave path, not an approximation of it:
+        the cloud factor becomes a literal ``1.0`` that the atmospheric
+        emissivity short-circuits.
+
+        :raises EngineError: The engine refused the edit.
+        """
+        _check(swmm_heat_clear_cloud(_h(self._solver)))
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# [HEAT_SOURCES]
+# =============================================================================
+
+class _HeatSources:
+    """``solver.heat.sources`` — the GLOBAL inlet temperature per water source.
+
+    A mapping keyed by :class:`HeatSourceKind` whose values are degC. The
+    table is a fixed enum extent, not a parsed list, so it is readable even on
+    a model with no heat configured; a source with no row reads the 20 degC
+    default — use :meth:`is_configured` to tell a default from an explicit
+    value.
+
+    Every refusal mirrors the ``[HEAT_SOURCES]`` parser exactly: values are
+    **refused, never clamped**.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of sources the table carries (7).
+
+        :returns: The source count. Never fails on a model with no heat
+            configured.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int count = 0
+        _check(swmm_heat_source_count(_h(self._solver), &count))
+        return count
+
+    def __iter__(self) -> Iterator[HeatSourceKind]:
+        cdef int n = len(self)
+        for i in range(n):
+            yield HeatSourceKind(i)
+
+    def __getitem__(self, key) -> float:
+        """Read one source's GLOBAL inlet temperature.
+
+        :param key: A :class:`HeatSourceKind` member, code, or name.
+        :returns: The global inlet temperature in degC. A source with no row
+            reads the 20 degC default.
+        :raises KeyError: *key* is not a valid :class:`HeatSourceKind`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double temp_c = 0.0
+        source = _member(HeatSourceKind, key)
+        _check(swmm_heat_get_source_temp(
+            _h(self._solver), int(source), &temp_c))
+        return temp_c
+
+    def __setitem__(self, key, double temp_c) -> None:
+        """Write one source's GLOBAL inlet temperature and mark it configured.
+
+        :param key: A :class:`HeatSourceKind` member, code, or name.
+        :param temp_c: Inlet temperature in degC, within ``[-50, 100]`` —
+            the parser's own range.
+        :raises KeyError: *key* is not a valid :class:`HeatSourceKind`.
+        :raises EngineError: *temp_c* is outside ``[-50, 100]``. Refused, not
+            clamped; a refused write does not take effect.
+        """
+        source = _member(HeatSourceKind, key)
+        _check(swmm_heat_set_source_temp(
+            _h(self._solver), int(source), temp_c))
+
+    def __contains__(self, key) -> bool:
+        """Is *key* a source this table carries?"""
+        try:
+            _member(HeatSourceKind, key)
+            return True
+        except (KeyError, TypeError):
+            return False
+
+    def is_configured(self, source) -> bool:
+        """Did the model set *source* explicitly, or is it taking the default?
+
+        An editor needs the distinction to avoid writing rows a user never
+        asked for.
+
+        :param source: A :class:`HeatSourceKind` member, code, or name.
+        :returns: ``True`` when the model set this source explicitly.
+        :raises KeyError: *source* is not a valid :class:`HeatSourceKind`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int configured = 0
+        kind = _member(HeatSourceKind, source)
+        _check(swmm_heat_get_source_configured(
+            _h(self._solver), int(kind), &configured))
+        return configured != 0
+
+    def clear(self, source) -> None:
+        """Return *source* to the 20 degC default and mark it unconfigured.
+
+        The writer then emits no row for it. NODE overrides are **untouched**
+        — they are separate rows, and removing them silently would delete
+        model the caller did not name.
+
+        :param source: A :class:`HeatSourceKind` member, code, or name.
+        :raises KeyError: *source* is not a valid :class:`HeatSourceKind`.
+        :raises EngineError: The engine refused the edit.
+        """
+        kind = _member(HeatSourceKind, source)
+        _check(swmm_heat_clear_source_temp(_h(self._solver), int(kind)))
+
+    def effective(self, source, node) -> float:
+        """The temperature *source* water actually enters *node* at (degC).
+
+        The NODE override when one exists, else the GLOBAL value. Exposed so a
+        caller reads the same resolution the engine uses rather than
+        re-deriving the precedence and drifting from it.
+
+        :param source: A :class:`HeatSourceKind` member, code, or name.
+        :param node: ``int`` node index or ``str`` node id.
+        :returns: The effective inlet temperature in degC.
+        :raises KeyError: *source* is not a valid :class:`HeatSourceKind`, or
+            no node with that id exists.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double temp_c = 0.0
+        kind = _member(HeatSourceKind, source)
+        cdef int ni = _resolve_node(self._solver, node)
+        _check(swmm_heat_get_effective_source_temp(
+            _h(self._solver), int(kind), ni, &temp_c))
+        return temp_c
+
+    def __repr__(self) -> str:
+        try:
+            configured = [s.name for s in self if self.is_configured(s)]
+            return f""
+        except Exception:
+            return ""
+
+
+class _HeatNodeOverrides:
+    """``solver.heat.node_overrides`` — the NODE-scope override rows.
+
+    A sequence of :class:`HeatNodeOverride` rows, indexed by row position.
+    Only :attr:`HeatSourceKind.DWF` and
+    :attr:`HeatSourceKind.EXTERNAL_INFLOW` may be overridden per node — the H1
+    scope rule, refused rather than deferred silently, the same answer the
+    deck gets.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of NODE-scope override rows.
+
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int count = 0
+        _check(swmm_heat_node_override_count(_h(self._solver), &count))
+        return count
+
+    def __iter__(self) -> Iterator[HeatNodeOverride]:
+        cdef int n = len(self)
+        for i in range(n):
+            yield self[i]
+
+    def __getitem__(self, int row_index) -> HeatNodeOverride:
+        """Read one NODE override by row index.
+
+        :param row_index: Zero-based row position; negative indexes from the
+            end, as for a list.
+        :returns: A :class:`HeatNodeOverride` of
+            ``(source, node_index, temp_c)`` with *temp_c* in degC.
+        :raises IndexError: *row_index* is out of range.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int n = len(self)
+        cdef int i = row_index + n if row_index < 0 else row_index
+        if not (0 <= i < n):
+            raise IndexError(row_index)
+        cdef int source = 0
+        cdef int node = -1
+        cdef double temp_c = 0.0
+        _check(swmm_heat_get_node_override(
+            _h(self._solver), i, &source, &node, &temp_c))
+        return HeatNodeOverride(HeatSourceKind(source), node, temp_c)
+
+    def set(self, source, node, double temp_c) -> None:
+        """Add or update the NODE override for ``(source, node)``.
+
+        An existing ``(source, node)`` pair is **updated**, not duplicated:
+        the deck parser refuses a duplicate row because a deck cannot mean two
+        temperatures at once, while through an API setting the same pair twice
+        is an edit. Same invariant — one row per pair — reached the way each
+        caller means it.
+
+        :param source: A :class:`HeatSourceKind` member, code, or name. Only
+            :attr:`HeatSourceKind.DWF` and
+            :attr:`HeatSourceKind.EXTERNAL_INFLOW` are in scope.
+        :param node: ``int`` node index or ``str`` node id.
+        :param temp_c: Inlet temperature in degC, within ``[-50, 100]``.
+        :raises KeyError: *source* is not a valid :class:`HeatSourceKind`, or
+            no node with that id exists.
+        :raises EngineError: *source* is not ``DWF`` or ``EXTERNAL_INFLOW``
+            (the H1 scope rule), *node* is out of range, or *temp_c* is
+            outside ``[-50, 100]``. Refused, not clamped.
+        """
+        kind = _member(HeatSourceKind, source)
+        cdef int ni = _resolve_node(self._solver, node)
+        _check(swmm_heat_set_node_override(
+            _h(self._solver), int(kind), ni, temp_c))
+        self._solver._bump_generation()
+
+    def remove(self, int row_index) -> None:
+        """Remove one NODE override by row index.
+
+        Later rows **shift down**, so a caller iterating by index must re-read
+        the length after removing.
+
+        :param row_index: Zero-based row position.
+        :raises EngineError: The engine refused the removal.
+        """
+        _check(swmm_heat_remove_node_override(_h(self._solver), row_index))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# Heat view
+# =============================================================================
+
+class Heat:
+    """``solver.heat`` — heat-transport configuration.
+
+    Edits are live: setters mutate engine state and the flux modules re-read
+    the configuration every step, so a mid-run edit takes effect on the next
+    routing step. Out-of-range values are refused, never clamped, and a
+    refused write leaves the previous value in place.
+    """
+
+    @property
+    def shortwave_timeseries(self):
+        """Bound timeseries name, or an empty string when none is bound."""
+        cdef bytearray buffer = bytearray(256)
+        while True:
+            _check(swmm_heat_get_shortwave_timeseries(_h(self._solver), buffer, len(buffer)))
+            value = bytes(buffer).split(b'\0', 1)[0]
+            if len(value) < len(buffer) - 1:
+                return value.decode('utf-8')
+            buffer = bytearray(len(buffer) * 2)
+
+    def __init__(self, solver):
+        self._solver = solver
+        self._modules = None
+        self._radiative = None
+        self._solar = None
+        self._cloud = None
+        self._sources = None
+        self._node_overrides = None
+
+    # ---- Toggles ----------------------------------------------------
+
+    @property
+    def enabled(self) -> bool:
+        """Is ``[OPTIONS] HEAT_TRANSPORT`` on? Read-only.
+
+        :returns: ``True`` when heat transport is enabled for the model.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int enabled = 0
+        _check(swmm_heat_get_enabled(_h(self._solver), &enabled))
+        return enabled != 0
+
+    @property
+    def modules(self) -> _HeatModules:
+        """``[HEAT_FLUXES]`` toggles: a mapping keyed by :class:`HeatFluxModule`
+        whose values are ``bool``."""
+        if self._modules is None:
+            self._modules = _HeatModules(self._solver)
+        return self._modules
+
+    # ---- Radiative fluxes -------------------------------------------
+
+    @property
+    def radiative(self) -> _HeatRadiative:
+        """``[RADIATIVE_FLUXES]``: a mapping keyed by
+        :class:`HeatRadiativeParam` (``SHORTWAVE`` in W/m2, the rest
+        fractions in ``[0, 1]``)."""
+        if self._radiative is None:
+            self._radiative = _HeatRadiative(self._solver)
+        return self._radiative
+
+    @property
+    def shortwave_mode(self) -> HeatShortwaveMode:
+        """Where incoming shortwave comes from — a :class:`HeatShortwaveMode`.
+
+        The three modes are mutually exclusive **in effect**: exactly one is
+        read, and there is no precedence ladder behind them. Switching modes
+        does not erase the other modes' settings, so a GUI can offer three
+        radio buttons without destroying what the user typed under the other
+        two.
+
+        :returns: The active :class:`HeatShortwaveMode`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int mode = 0
+        _check(swmm_heat_get_shortwave_mode(_h(self._solver), &mode))
+        return HeatShortwaveMode(mode)
+
+    @shortwave_mode.setter
+    def shortwave_mode(self, value) -> None:
+        """Select the incoming-shortwave mode.
+
+        :param value: A :class:`HeatShortwaveMode` member, code, or name.
+        :raises KeyError: *value* is not a valid :class:`HeatShortwaveMode`.
+        :raises EngineError: :attr:`HeatShortwaveMode.COMPUTED` was requested
+            while latitude or longitude is unset (see :attr:`solar_sited` —
+            the engine will **not** fall back on the ``[TEMPERATURE]``
+            SNOWMELT latitude, which defaults to 0 and would silently model
+            equatorial noon), or :attr:`HeatShortwaveMode.TIMESERIES` was
+            requested with no series bound by
+            :meth:`set_shortwave_timeseries`.
+        """
+        mode = _member(HeatShortwaveMode, value)
+        _check(swmm_heat_set_shortwave_mode(_h(self._solver), int(mode)))
+
+    def set_shortwave_timeseries(self, str name) -> None:
+        """Bind a ``[TIMESERIES]`` by name as the shortwave record.
+
+        This also switches :attr:`shortwave_mode` to
+        :attr:`HeatShortwaveMode.TIMESERIES`.
+
+        :param name: Id of an existing ``[TIMESERIES]`` (W/m2).
+        :raises EngineError: No timeseries of that name exists.
+        """
+        cdef bytes b = name.encode('utf-8')
+        _check(swmm_heat_set_shortwave_timeseries(_h(self._solver), b))
+
+    @property
+    def current_shortwave(self) -> float:
+        """Resolved incoming shortwave at the **current** step, W/m2, cloud
+        already applied.
+
+        Read-only: this is state, not configuration. It is 0 before the first
+        step, and whenever radiative exchange is off.
+
+        :returns: Incoming shortwave in W/m2.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double wm2 = 0.0
+        _check(swmm_heat_get_current_shortwave(_h(self._solver), &wm2))
+        return wm2
+
+    # ---- Solar radiation --------------------------------------------
+
+    @property
+    def solar(self) -> _HeatSolar:
+        """``[SOLAR_RADIATION]``: a mapping keyed by :class:`HeatSolarParam`,
+        consulted under :attr:`HeatShortwaveMode.COMPUTED` only."""
+        if self._solar is None:
+            self._solar = _HeatSolar(self._solver)
+        return self._solar
+
+    @property
+    def solar_sited(self) -> bool:
+        """Have latitude **and** longitude both been explicitly set? Read-only.
+
+        This is the precondition for :attr:`HeatShortwaveMode.COMPUTED`. A GUI
+        should gate the COMPUTED radio button on this rather than discovering
+        the refusal after the fact.
+
+        :returns: ``True`` when both coordinates were written explicitly.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int sited = 0
+        _check(swmm_heat_get_solar_sited(_h(self._solver), &sited))
+        return sited != 0
+
+    # ---- Cloud cover ------------------------------------------------
+
+    @property
+    def cloud(self) -> _HeatCloud:
+        """``[CLOUD_COVER]``: a mapping keyed by :class:`HeatCloudParam`, plus
+        :attr:`~_HeatCloud.configured`, :attr:`~_HeatCloud.current`,
+        :meth:`~_HeatCloud.set_timeseries` and :meth:`~_HeatCloud.clear`."""
+        if self._cloud is None:
+            self._cloud = _HeatCloud(self._solver)
+        return self._cloud
+
+    # ---- Heat sources -----------------------------------------------
+
+    @property
+    def sources(self) -> _HeatSources:
+        """``[HEAT_SOURCES]`` GLOBAL inlet temperatures (degC), keyed by
+        :class:`HeatSourceKind`."""
+        if self._sources is None:
+            self._sources = _HeatSources(self._solver)
+        return self._sources
+
+    @property
+    def node_overrides(self) -> _HeatNodeOverrides:
+        """``[HEAT_SOURCES]`` NODE-scope override rows, indexed by row
+        position. Only ``DWF`` and ``EXTERNAL_INFLOW`` are in scope."""
+        if self._node_overrides is None:
+            self._node_overrides = _HeatNodeOverrides(self._solver)
+        return self._node_overrides
+
+    def __repr__(self) -> str:
+        try:
+            return (f"")
+        except Exception:
+            return ""
+
+
+cdef extern from "openswmm/engine/openswmm_heat.h":
+    int swmm_heat_get_shortwave_timeseries(SWMM_Engine, char*, int)
+    int swmm_heat_get_cloud_timeseries(SWMM_Engine, char*, int)
diff --git a/python/openswmm/engine/_hotstart.pyx b/python/openswmm/engine/_hotstart.pyx
index 6d28fde7f..6cb63da99 100644
--- a/python/openswmm/engine/_hotstart.pyx
+++ b/python/openswmm/engine/_hotstart.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Hot start files (Pythonic v1 surface)
 =====================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Hot start files capture the hydraulic + quality state of a simulation
 at a moment in time and let a follow-up run resume from there.
@@ -61,11 +77,12 @@ cdef class HotStart:
     def save_from(Solver solver, path) -> None:
         """Save ``solver`` state to ``path``. Raises on failure."""
         cdef bytes b = os.fspath(path).encode('utf-8')
-        cdef SWMM_Engine h = solver._handle
+        cdef SWMM_Engine h = solver.handle
         cdef const char* p = b
         cdef int rc
-        with nogil:
-            rc = swmm_hotstart_save(h, p)
+        with solver._operation(h):
+            with nogil:
+                rc = swmm_hotstart_save(h, p)
         _check(rc)
 
     @classmethod
@@ -107,10 +124,10 @@ cdef class HotStart:
     def apply(self, Solver solver) -> None:
         """Apply this hot start to ``solver``. The solver must be
         INITIALIZED (post-:meth:`Solver.initialize`, pre-:meth:`Solver.start`)."""
-        cdef SWMM_Engine h = solver._handle
+        cdef SWMM_Engine h = solver.handle
         cdef SWMM_HotStart hs = self._handle
         cdef int rc
-        with nogil:
+        with solver._operation(h):
             rc = swmm_hotstart_apply(h, hs)
         _check(rc)
 
diff --git a/python/openswmm/engine/_inflows.pyx b/python/openswmm/engine/_inflows.pyx
index 9b52897e3..1de5f2a33 100644
--- a/python/openswmm/engine/_inflows.pyx
+++ b/python/openswmm/engine/_inflows.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Inflows (Pythonic v1 surface)
 =============================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Inflows` view exposes external inflows, dry-weather flows,
 RDII, unit hydrographs, gage assignments, and IA-decay entries on the
diff --git a/python/openswmm/engine/_infrastructure.pyi b/python/openswmm/engine/_infrastructure.pyi
index cfee3cb69..92d93c0c2 100644
--- a/python/openswmm/engine/_infrastructure.pyi
+++ b/python/openswmm/engine/_infrastructure.pyi
@@ -1,9 +1,9 @@
 """Type stubs for :mod:`openswmm.engine._infrastructure`."""
 
 from collections.abc import Iterator
-from typing import List, Tuple, Union
+from typing import Any, List, Tuple, Union
 
-from ._enums import LidType
+from ._enums import InletHostKind, InletPlacement, LidType
 from ._solver import Solver
 
 
@@ -49,6 +49,7 @@ class Streets:
     def get_id(self, idx: int) -> str: ...
     def __iter__(self) -> Iterator[str]: ...
     def __contains__(self, key: object) -> bool: ...
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def set_params(
         self, idx: int, *,
         t_crown: float, h_curb: float, sx: float, n_road: float,
@@ -75,6 +76,7 @@ class Inlets:
     def get_id(self, idx: int) -> str: ...
     def __iter__(self) -> Iterator[str]: ...
     def __contains__(self, key: object) -> bool: ...
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def set_params(
         self, idx: int, *,
         length: float = ..., width: float = ...,
@@ -83,6 +85,29 @@ class Inlets:
     ) -> None: ...
     def get_params(self, idx: int) -> dict[str, float | str]: ...
     def get_type(self, idx: int) -> str: ...
+    def get_design(self, key: _Key) -> dict[str, Any]: ...
+    def set_design(
+        self, key: _Key, design: dict[str, Any] | None = ..., **kwargs: Any,
+    ) -> None: ...
+    def get_comment(self, key: _Key) -> str: ...
+    def set_comment(self, key: _Key, text: str) -> None: ...
+
+
+class InletUsages:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def find_link(self, link_idx: int) -> int: ...
+    def find_node(self, node_idx: int) -> int: ...
+    def get(self, usage_idx: int) -> dict[str, Any]: ...
+    def set(
+        self, host_kind: InletHostKind | int, host_idx: int, design_idx: int,
+        capture_node_idx: int, *,
+        num_inlets: int = ..., pct_clogged: float = ..., flow_limit: float = ...,
+        local_depress: float = ..., local_width: float = ...,
+        placement: InletPlacement | int = ...,
+    ) -> int: ...
+    def remove(self, usage_idx: int) -> None: ...
+    def __iter__(self) -> Iterator[dict[str, Any]]: ...
 
 
 class LIDs:
@@ -93,6 +118,7 @@ class LIDs:
     def get_id(self, idx: int) -> str: ...
     def __iter__(self) -> Iterator[str]: ...
     def __contains__(self, key: object) -> bool: ...
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def set_surface(
         self, idx: int, *, storage: float, roughness: float, slope: float,
     ) -> None: ...
@@ -138,4 +164,5 @@ class Infrastructure:
     transects: Transects
     streets: Streets
     inlets: Inlets
+    inlet_usages: InletUsages
     lids: LIDs
diff --git a/python/openswmm/engine/_infrastructure.pyx b/python/openswmm/engine/_infrastructure.pyx
index 644155cb6..b3da2936e 100644
--- a/python/openswmm/engine/_infrastructure.pyx
+++ b/python/openswmm/engine/_infrastructure.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Infrastructure (Pythonic v1 surface)
 ====================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 ``solver.infrastructure`` exposes the four hydraulic-infrastructure
 families: transects, streets, inlets, and LID controls/usage. The C
@@ -29,7 +45,11 @@ flat (``add_*`` / ``*_count``) rather than dressing it as a collection.
 
 # cython: language_level=3
 
+from libc.string cimport memcpy, memset
+
 from ._exceptions import ElementNotFoundError
+from ._enums import (GrateType, InletCurveKind, InletHostKind, InletPlacement,
+                     InletType, ThroatType)
 from ._common cimport *
 
 
@@ -352,6 +372,18 @@ class Streets:
                 return False
         return 0 <= int(key) < len(self)
 
+    def rename(self, key, str new_id) -> None:
+        """Rename a street cross-section, updating stored references.
+
+        @param key: Integer index or string id.
+        @param new_id: New identifier.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef bytes b = new_id.encode('utf-8')
+        _check(swmm_street_rename(h, idx, b))
+        self._solver._bump_generation()
+
 
 # ---- Inlets ---------------------------------------------------------
 
@@ -458,6 +490,265 @@ class Inlets:
                 return False
         return 0 <= int(key) < len(self)
 
+    def rename(self, key, str new_id) -> None:
+        """Rename an inlet design, updating stored references.
+
+        @param key: Integer index or string id.
+        @param new_id: New identifier.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef bytes b = new_id.encode('utf-8')
+        _check(swmm_inlet_rename(h, idx, b))
+        self._solver._bump_generation()
+
+    # ---- Full design surface (SWMM_InletDesign) ---------------------
+
+    def get_design(self, key) -> dict:
+        """Read every field of an inlet design.
+
+        Superset of :meth:`get_params`, which only covers the grate/slotted
+        dimensions. Only the fields the design's C{type} actually uses carry
+        meaning; the rest read back as zero.
+
+        @param key: Integer index or string id.
+        @return: Mapping with keys ``type`` (L{InletType}), ``grate_length``,
+            ``grate_width``, ``grate_type`` (L{GrateType}), ``open_area``,
+            ``splash_veloc``, ``curb_length``, ``curb_height``, ``throat``
+            (L{ThroatType}), ``slot_length``, ``slot_width``, ``curve_id``,
+            ``curve_kind`` (L{InletCurveKind}).
+        @rtype: dict
+        @raise KeyError: If C{key} is a name and no inlet has it.
+        @raise EngineError: On C API failure.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef SWMM_InletDesign d
+        cdef char curve[64]
+        _check(swmm_inlet_get_design(h, idx, &d))
+        memcpy(curve, d.curve_id, sizeof(curve))
+        curve[sizeof(curve) - 1] = 0
+        return {
+            "type": InletType(d.type),
+            "grate_length": d.grate_length,
+            "grate_width": d.grate_width,
+            "grate_type": GrateType(d.grate_type),
+            "open_area": d.open_area,
+            "splash_veloc": d.splash_veloc,
+            "curb_length": d.curb_length,
+            "curb_height": d.curb_height,
+            "throat": ThroatType(d.throat),
+            "slot_length": d.slot_length,
+            "slot_width": d.slot_width,
+            "curve_id": curve.decode('utf-8'),
+            "curve_kind": InletCurveKind(d.curve_kind),
+        }
+
+    def set_design(self, key, design=None, **kwargs) -> None:
+        """Overwrite every field of an inlet design (the type may change).
+
+        Accepts the mapping :meth:`get_design` returns, keyword arguments, or
+        both (keywords win), so a read-modify-write is a one-liner::
+
+            inlets.set_design("Curb1", throat=ThroatType.INCLINED)
+
+        Only the fields the resulting C{type} uses are validated: the
+        dimensions it needs must be positive, ``open_area`` must lie in
+        (0, 1] for a C{GENERIC} grate, and a C{CUSTOM} design needs a
+        non-empty ``curve_id``. A ``curve_kind`` that contradicts the named
+        curve's own C{[CURVES]} type is rejected; when the curve does not
+        exist yet the kind is stored as given and re-derived on validation.
+
+        @param key: Integer index or string id.
+        @param design: Optional mapping of field values (defaults are read
+            from the existing design, so an omitted field is preserved).
+        @type design: dict or None
+        @raise KeyError: If C{key} is a name and no inlet has it.
+        @raise EngineError: On a violated constraint or C API failure.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef SWMM_InletDesign d
+        _check(swmm_inlet_get_design(h, idx, &d))
+
+        values = dict(design or {})
+        values.update(kwargs)
+        cdef bytes b_curve
+        if "type" in values:         d.type         = int(values["type"])
+        if "grate_length" in values: d.grate_length = float(values["grate_length"])
+        if "grate_width" in values:  d.grate_width  = float(values["grate_width"])
+        if "grate_type" in values:   d.grate_type   = int(values["grate_type"])
+        if "open_area" in values:    d.open_area    = float(values["open_area"])
+        if "splash_veloc" in values: d.splash_veloc = float(values["splash_veloc"])
+        if "curb_length" in values:  d.curb_length  = float(values["curb_length"])
+        if "curb_height" in values:  d.curb_height  = float(values["curb_height"])
+        if "throat" in values:       d.throat       = int(values["throat"])
+        if "slot_length" in values:  d.slot_length  = float(values["slot_length"])
+        if "slot_width" in values:   d.slot_width   = float(values["slot_width"])
+        if "curve_kind" in values:   d.curve_kind   = int(values["curve_kind"])
+        if "curve_id" in values:
+            b_curve = (values["curve_id"] or "").encode('utf-8')
+            if len(b_curve) >= sizeof(d.curve_id):
+                raise ValueError("curve_id is longer than 63 bytes")
+            memset(d.curve_id, 0, sizeof(d.curve_id))
+            memcpy(d.curve_id, b_curve, len(b_curve))
+        _check(swmm_inlet_set_design(h, idx, &d))
+
+    def get_comment(self, key) -> str:
+        """Return the free-text description of an inlet design.
+
+        @param key: Integer index or string id.
+        @rtype: str
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef char buf[1024]
+        _check(swmm_inlet_get_comment(h, idx, buf, sizeof(buf)))
+        return buf.decode('utf-8')
+
+    def set_comment(self, key, str text) -> None:
+        """Set the free-text description of an inlet design.
+
+        @param key: Integer index or string id.
+        @param text: Description; round-tripped as a C{';'} comment line.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef bytes b = (text or "").encode('utf-8')
+        _check(swmm_inlet_set_comment(h, idx, b))
+
+
+# ---- Inlet usage ----------------------------------------------------
+
+class InletUsages:
+    """``solver.infrastructure.inlet_usages`` view — inlet placements.
+
+    One row per placement, of either host kind: a conduit carrying an
+    C{[INLET_USAGE]} row, or an inlet junction (an C{[INLET_JUNCTIONS]}
+    node). Both kinds live in one store, so C{len()} counts them together
+    and :meth:`get` reports which kind a row is through its ``host_kind``.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int n = swmm_inlet_usage_count(h)
+        return n if n > 0 else 0
+
+    def find_link(self, link_idx) -> int:
+        """Row index of the usage hosted by conduit C{link_idx}, or C{-1}.
+
+        @param link_idx: Zero-based link index.
+        @rtype: int
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        return swmm_inlet_usage_find_link(h, int(link_idx))
+
+    def find_node(self, node_idx) -> int:
+        """Row index of the usage hosted by inlet junction C{node_idx}, or C{-1}.
+
+        @param node_idx: Zero-based node index.
+        @rtype: int
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        return swmm_inlet_usage_find_node(h, int(node_idx))
+
+    def get(self, int usage_idx) -> dict:
+        """Read one usage row.
+
+        @param usage_idx: Zero-based usage-row index.
+        @return: Mapping with keys ``host_kind`` (L{InletHostKind}),
+            ``host_idx`` (a link index for C{LINK}, a node index for
+            C{NODE}), ``design_idx``, ``capture_node_idx``, ``num_inlets``,
+            ``pct_clogged``, ``flow_limit``, ``local_depress``,
+            ``local_width``, ``placement`` (L{InletPlacement}).
+        @rtype: dict
+        @raise EngineError: On a bad index or C API failure.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef SWMM_InletUsage u
+        _check(swmm_inlet_usage_get(h, usage_idx, &u))
+        return {
+            "host_kind": InletHostKind(u.host_kind),
+            "host_idx": u.host_idx,
+            "design_idx": u.design_idx,
+            "capture_node_idx": u.capture_node_idx,
+            "num_inlets": u.num_inlets,
+            "pct_clogged": u.pct_clogged,
+            "flow_limit": u.flow_limit,
+            "local_depress": u.local_depress,
+            "local_width": u.local_width,
+            "placement": InletPlacement(u.placement),
+        }
+
+    def set(self, int host_kind, int host_idx, int design_idx,
+            int capture_node_idx, *, int num_inlets=1,
+            double pct_clogged=0.0, double flow_limit=0.0,
+            double local_depress=0.0, double local_width=0.0,
+            int placement=0) -> int:
+        """Create or replace the usage row for a host.
+
+        At most one row exists per host: an existing row for
+        C{(host_kind, host_idx)} is overwritten, otherwise a row is appended.
+        A C{NODE} host must already be an inlet junction (see
+        C{Node.is_inlet}); a C{LINK} host must be a conduit. The capture node
+        must exist, must not be the host node, and must not itself be virtual.
+
+        Flow and length values are in the project's display units, as
+        authored in C{[INLET_USAGE]}.
+
+        @param host_kind: L{InletHostKind} — C{LINK} or C{NODE}.
+        @param host_idx: Zero-based link or node index per C{host_kind}.
+        @param design_idx: Zero-based inlet-design index.
+        @param capture_node_idx: Receiving (underdrain) node index.
+        @param num_inlets: Inlets per side (>= 1).
+        @param pct_clogged: Clogged fraction, 0..99.
+        @param flow_limit: Max capture per inlet; C{0} = unlimited.
+        @param local_depress: Local gutter depression.
+        @param local_width: Local depression width.
+        @param placement: L{InletPlacement}.
+        @return: Index of the created or replaced row.
+        @rtype: int
+        @raise EngineError: On a violated constraint or C API failure.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef SWMM_InletUsage u
+        cdef int row = -1
+        u.host_kind = host_kind
+        u.host_idx = host_idx
+        u.design_idx = design_idx
+        u.capture_node_idx = capture_node_idx
+        u.num_inlets = num_inlets
+        u.pct_clogged = pct_clogged
+        u.flow_limit = flow_limit
+        u.local_depress = local_depress
+        u.local_width = local_width
+        u.placement = placement
+        _check(swmm_inlet_usage_set(h, &u, &row))
+        self._solver._bump_generation()
+        return row
+
+    def remove(self, int usage_idx) -> None:
+        """Delete a usage row.
+
+        Removing an inlet junction's row leaves the node flagged as an inlet
+        with nothing to capture, which the model validator rejects; demote
+        the node instead (C{Node.is_inlet = False}) or give it a new row.
+
+        @param usage_idx: Zero-based usage-row index.
+        @raise EngineError: On a bad index or C API failure.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        _check(swmm_inlet_usage_remove(h, usage_idx))
+        self._solver._bump_generation()
+
+    def __iter__(self):
+        cdef int n = len(self)
+        for i in range(n):
+            yield self.get(i)
+
 
 # ---- LID controls + usage ------------------------------------------
 
@@ -526,6 +817,18 @@ class LIDs:
                 return False
         return 0 <= int(key) < len(self)
 
+    def rename(self, key, str new_id) -> None:
+        """Rename an LID control, updating stored ``[LID_USAGE]`` references.
+
+        @param key: Integer index or string id.
+        @param new_id: New identifier.
+        """
+        cdef SWMM_Engine h = self._solver.handle
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef bytes b = new_id.encode('utf-8')
+        _check(swmm_lid_rename(h, idx, b))
+        self._solver._bump_generation()
+
     def set_surface(self, int idx, *,
                     double storage, double roughness, double slope) -> None:
         """Set the surface-layer parameters for LID *idx*."""
@@ -722,13 +1025,14 @@ class LIDs:
 # ---- Top-level Infrastructure view ----------------------------------
 
 class Infrastructure:
-    """``solver.infrastructure`` — entry point for the four sub-views."""
+    """``solver.infrastructure`` — entry point for the five sub-views."""
 
     def __init__(self, solver):
         self._solver = solver
         self._transects = None
         self._streets = None
         self._inlets = None
+        self._inlet_usages = None
         self._lids = None
 
     @property
@@ -749,6 +1053,12 @@ class Infrastructure:
             self._inlets = Inlets(self._solver)
         return self._inlets
 
+    @property
+    def inlet_usages(self) -> InletUsages:
+        if self._inlet_usages is None:
+            self._inlet_usages = InletUsages(self._solver)
+        return self._inlet_usages
+
     @property
     def lids(self) -> LIDs:
         if self._lids is None:
@@ -759,6 +1069,7 @@ class Infrastructure:
         try:
             return (f"")
         except Exception:
             return ""
diff --git a/python/openswmm/engine/_initial_quality.pyi b/python/openswmm/engine/_initial_quality.pyi
new file mode 100644
index 000000000..c2dd69cd1
--- /dev/null
+++ b/python/openswmm/engine/_initial_quality.pyi
@@ -0,0 +1,39 @@
+"""Type stubs for :mod:`openswmm.engine._initial_quality`."""
+
+from collections.abc import Iterator
+from typing import NamedTuple, Optional, Union
+
+from ._solver import Solver
+from os import PathLike
+
+
+_Key = Union[int, str]
+
+
+class InitialQualityEntry(NamedTuple):
+    is_link: bool
+    elem_index: int
+    constituent: str
+    value: float
+
+
+class InitialQuality:
+    @property
+    def file_path(self) -> str: ...
+    @file_path.setter
+    def file_path(self, path: str | PathLike[str] | None) -> None: ...
+    def is_file(self, row_index: int) -> bool: ...
+
+    def __init__(self, solver: Solver) -> None: ...
+
+    WATER_AGE: str
+    TEMPERATURE: str
+
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[InitialQualityEntry]: ...
+    def __getitem__(self, row_index: int) -> InitialQualityEntry: ...
+    def set(
+        self, constituent: str, value: float, *,
+        node: Optional[_Key] = ..., link: Optional[_Key] = ...,
+    ) -> None: ...
+    def remove(self, row_index: int) -> None: ...
diff --git a/python/openswmm/engine/_initial_quality.pyx b/python/openswmm/engine/_initial_quality.pyx
new file mode 100644
index 000000000..33a79a927
--- /dev/null
+++ b/python/openswmm/engine/_initial_quality.pyx
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Initial quality (Pythonic v1 surface)
+=====================================
+
+:author: Caleb Buahin
+:copyright: Copyright (c) 2026 Caleb Buahin
+:license: Apache-2.0
+
+``solver.initial_quality`` is the ``[INITIAL_QUALITY]`` table: the starting
+concentration a named constituent holds in one node or one link at
+``initialize()``. It is a **sequence of rows** indexed ``0..len-1`` in file
+order. :meth:`InitialQuality.set` is an UPSERT keyed on
+``(is_link, elem_index, constituent)`` — writing the same key twice edits the
+row rather than duplicating it — and :meth:`InitialQuality.remove` deletes by
+row index, after which every later row **shifts down by one**.
+
+A constituent is either a ``[POLLUTANTS]`` pollutant name, or one of the two
+reserved species: :attr:`InitialQuality.WATER_AGE` (``"__WATER_AGE__"``, value
+in HOURS, signed) and :attr:`InitialQuality.TEMPERATURE`
+(``"__TEMPERATURE__"``, value in degC). Pollutant values are concentrations in
+that pollutant's own units and must be **non-negative**; the two reserved
+species accept negative values.
+
+Rows seed state at ``initialize()`` only, so mutation is confined to the
+editable lifecycle states — ``BUILDING`` and ``OPENED``. Editing later raises
+:class:`~openswmm.engine.LifecycleError`.
+
+.. code-block:: python
+
+    from openswmm.engine import Solver, InitialQuality
+
+    s = Solver("model.inp")
+    try:
+        s.open()
+        s.initial_quality.set("TSS", 25.0, node="J1")
+        s.initial_quality.set("TSS", 12.0, link="C1")
+        s.initial_quality.set(InitialQuality.WATER_AGE, -3.0, node="J1")
+        s.initial_quality.set(InitialQuality.TEMPERATURE, 14.5, node="J1")
+        for row in s.initial_quality:
+            print(row.is_link, row.elem_index, row.constituent, row.value)
+        s.initial_quality.remove(0)     # later rows shift down by one
+    finally:
+        s.close()
+        s.destroy()
+"""
+
+# cython: language_level=3
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from ._common cimport *
+from ._enums import ErrorCode
+from ._exceptions import BadHandleError
+
+
+cdef inline SWMM_Engine _h(solver):
+    return solver.handle
+
+
+class InitialQualityEntry(NamedTuple):
+    """One ``[INITIAL_QUALITY]`` row.
+
+    :ivar is_link: ``True`` when ``elem_index`` addresses a link, ``False``
+        when it addresses a node.
+    :ivar elem_index: Zero-based node or link index, or ``-1`` when the row's
+        element could not be resolved.
+    :ivar constituent: A ``[POLLUTANTS]`` pollutant name, or the reserved
+        ``"__WATER_AGE__"`` / ``"__TEMPERATURE__"`` species.
+    :ivar value: Raw value — pollutant concentration in the pollutant's own
+        units (non-negative), HOURS for ``"__WATER_AGE__"`` (signed), or degC
+        for ``"__TEMPERATURE__"``.
+    """
+
+    is_link: bool
+    elem_index: int
+    constituent: str
+    value: float
+
+
+class InitialQuality:
+    """``solver.initial_quality`` — the ``[INITIAL_QUALITY]`` row table.
+
+    A sequence of :class:`InitialQualityEntry` rows in file order. Rows are
+    flat snapshots, not live views: a row carries no identity beyond its
+    ``(is_link, elem_index, constituent)`` key.
+    """
+
+    #: Reserved constituent name for water age. Its value is in HOURS and may
+    #: be negative.
+    WATER_AGE = "__WATER_AGE__"
+
+    #: Reserved constituent name for temperature. Its value is in degC and may
+    #: be negative.
+    TEMPERATURE = "__TEMPERATURE__"
+
+    @property
+    def file_path(self):
+        """Authored sidecar path; empty when unset. Loaded on the next open."""
+        cdef bytearray buffer = bytearray(256)
+        while True:
+            _check(swmm_init_quality_file_get(_h(self._solver), buffer, len(buffer)))
+            value = bytes(buffer).split(b'\0', 1)[0]
+            if len(value) < len(buffer) - 1:
+                return value.decode('utf-8')
+            buffer = bytearray(len(buffer) * 2)
+
+    @file_path.setter
+    def file_path(self, path):
+        import os
+        cdef bytes value = os.fsencode(path) if path is not None else b''
+        _check(swmm_init_quality_file_set(_h(self._solver), value))
+
+    def is_file(self, int row_index):
+        """Whether a row came from the sidecar; accepts negative indices."""
+        cdef int count = len(self)
+        cdef int index = row_index + count if row_index < 0 else row_index
+        if index < 0 or index >= count:
+            raise IndexError(row_index)
+        return bool(swmm_init_quality_is_file(_h(self._solver), index))
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of ``[INITIAL_QUALITY]`` rows.
+
+        :returns: The row count.
+        :raises BadHandleError: The engine handle is invalid.
+        """
+        cdef int n = swmm_init_quality_count(_h(self._solver))
+        if n < 0:
+            raise BadHandleError(
+                int(ErrorCode.BADHANDLE),
+                "Invalid engine handle reading [INITIAL_QUALITY] count")
+        return n
+
+    def __iter__(self) -> Iterator[InitialQualityEntry]:
+        cdef int n = len(self)
+        for i in range(n):
+            yield self[i]
+
+    def __getitem__(self, int row_index) -> InitialQualityEntry:
+        """Read one row by row index.
+
+        :param row_index: Zero-based row position; negative indexes from the
+            end, as for a list.
+        :returns: An :class:`InitialQualityEntry` of
+            ``(is_link, elem_index, constituent, value)``.
+        :raises IndexError: *row_index* is out of range.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int n = len(self)
+        cdef int i = row_index + n if row_index < 0 else row_index
+        if not (0 <= i < n):
+            raise IndexError(row_index)
+        cdef int is_link = 0
+        cdef int elem_idx = -1
+        cdef char buf[128]
+        cdef double value = 0.0
+        buf[0] = 0
+        _check(swmm_init_quality_get(
+            _h(self._solver), i, &is_link, &elem_idx, buf, 128, &value))
+        return InitialQualityEntry(
+            is_link != 0, elem_idx, buf.decode('utf-8'), value)
+
+    def set(self, str constituent, double value, *, node=None,
+            link=None) -> None:
+        """Upsert the initial value of *constituent* in one node or one link.
+
+        The row key is ``(is_link, elem_index, constituent)``: an existing row
+        with that key is updated in place, otherwise a new row is appended.
+        Exactly one of *node* or *link* must be given.
+
+        Rows only seed state at ``initialize()``, so this is a
+        ``BUILDING``/``OPENED``-only edit — the same contract as
+        ``solver.pollutants[...].initial_concentration``.
+
+        :param constituent: A ``[POLLUTANTS]`` pollutant name, or
+            :attr:`WATER_AGE` / :attr:`TEMPERATURE`.
+        :param value: Pollutant concentration in the pollutant's own units
+            (must be **non-negative**); HOURS for :attr:`WATER_AGE` (signed);
+            degC for :attr:`TEMPERATURE` (signed).
+        :param node: ``int`` node index or ``str`` node id. Mutually
+            exclusive with *link*.
+        :param link: ``int`` link index or ``str`` link id. Mutually
+            exclusive with *node*.
+        :raises ValueError: Neither or both of *node* and *link* were given.
+        :raises KeyError: No node/link with that id exists.
+        :raises BadParamError: *constituent* names no pollutant or reserved
+            species, the element index is bad, or a pollutant *value* is
+            negative.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef int is_link
+        cdef int elem
+        cdef bytes b = constituent.encode('utf-8')
+        if (node is None) == (link is None):
+            raise ValueError(
+                "Pass exactly one of node= or link= to identify the element")
+        if node is not None:
+            is_link = 0
+            elem = _resolve_index(
+                _h(self._solver), node, swmm_node_index, swmm_node_count,
+                "Node")
+        else:
+            is_link = 1
+            elem = _resolve_index(
+                _h(self._solver), link, swmm_link_index, swmm_link_count,
+                "Link")
+        _check(swmm_init_quality_set(
+            _h(self._solver), is_link, elem, b, value))
+        self._solver._bump_generation()
+
+    def remove(self, int row_index) -> None:
+        """Remove the row at *row_index*.
+
+        Every later row **shifts down by one**, so a caller holding cached row
+        indices must re-enumerate. ``BUILDING``/``OPENED`` only.
+
+        :param row_index: Zero-based row position.
+        :raises BadIndexError: *row_index* is out of range.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        _check(swmm_init_quality_remove(_h(self._solver), row_index))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+cdef extern from "openswmm/engine/openswmm_initial_quality.h":
+    int swmm_init_quality_file_get(SWMM_Engine, char*, int)
+    int swmm_init_quality_file_set(SWMM_Engine, const char*)
+    int swmm_init_quality_is_file(SWMM_Engine, int)
diff --git a/python/openswmm/engine/_links.pyi b/python/openswmm/engine/_links.pyi
index 75e1e41e6..5e6489138 100644
--- a/python/openswmm/engine/_links.pyi
+++ b/python/openswmm/engine/_links.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Link access (Pythonic v1 surface)
 =================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._links`.
 """
@@ -31,6 +47,8 @@ class LinkStatsView:
     max_filling: float
     vol_flow: float
     surcharge_time: float
+    peak_slot_share: float
+    slot_share: float
     pump_cycles: int
     pump_on_time: float
     pump_volume: float
@@ -107,6 +125,7 @@ class Link:
     velocity: float
     capacity: float
     volume: float
+    slot_volume: float
     hyd_power: float
 
     # Control
@@ -139,6 +158,8 @@ class Link:
 
 class Links:
     """Indexable, iterable collection of :class:`Link` wrappers."""
+    def restore_authored_orientation(self) -> int: ...
+
 
     def __init__(self, solver: Solver) -> None: ...
 
diff --git a/python/openswmm/engine/_links.pyx b/python/openswmm/engine/_links.pyx
index 5307f2f39..f59346a0c 100644
--- a/python/openswmm/engine/_links.pyx
+++ b/python/openswmm/engine/_links.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Link access (Pythonic v1 surface)
 =================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Links` collection and :class:`Link` wrapper expose the
 network's conveyance elements — conduits, pumps, orifices, weirs, and
@@ -128,6 +144,34 @@ cdef class LinkStatsView:
         _check(swmm_link_get_stat_surcharge_time(_h(self._link._solver), self._link._index, &v))
         return v
 
+    @property
+    def peak_slot_share(self) -> float:
+        """Peak instantaneous ``slot_volume / volume`` over the run (0..1).
+
+        Finite-volume routing only: reads ``0.0`` under the dynamic-wave
+        router, which is indistinguishable from "no slot flow occurred".
+        """
+        _check_fresh(self._link)
+        cdef double v = 0.0
+        _check(swmm_link_get_stat_peak_slot_share(
+            _h(self._link._solver), self._link._index, &v))
+        return v
+
+    @property
+    def slot_share(self) -> float:
+        """Run-level slot share ``(∫ slot_volume dt) / (∫ volume dt)`` (0..1).
+
+        A ratio of time integrals — never an average of instantaneous
+        ratios. Finite-volume routing only: reads ``0.0`` under the
+        dynamic-wave router, which is indistinguishable from "no slot flow
+        occurred".
+        """
+        _check_fresh(self._link)
+        cdef double v = 0.0
+        _check(swmm_link_get_stat_slot_share(
+            _h(self._link._solver), self._link._index, &v))
+        return v
+
     @property
     def pump_cycles(self) -> int:
         """Cycles for a pump link. Raises :class:`BadParamError` on non-pumps."""
@@ -685,6 +729,19 @@ cdef class Link:
         _check(swmm_link_get_volume(_h(self._solver), self._index, &v))
         return v
 
+    @property
+    def slot_volume(self) -> float:
+        """Water held in the Preissmann slot, in project volume units.
+
+        The part of :attr:`volume` standing above the pipe crown. Finite-volume
+        routing only: reads ``0.0`` under the dynamic-wave router, which is
+        indistinguishable from "no slot storage".
+        """
+        _check_fresh(self)
+        cdef double v = 0.0
+        _check(swmm_link_get_slot_volume(_h(self._solver), self._index, &v))
+        return v
+
     @property
     def hyd_power(self) -> float:
         _check_fresh(self)
@@ -881,6 +938,18 @@ cdef class Links:
 
     cdef object _solver
 
+    def restore_authored_orientation(self):
+        """Restore reversed conduits after open; return the number restored.
+
+        Intended for editing hosts. The INP writer already restores orientation
+        when writing. Reacquire retained object views after this structural edit.
+        """
+        cdef int count = 0
+        _check(swmm_links_restore_authored_orientation(_h(self._solver), &count))
+        if count:
+            self._solver._bump_generation()
+        return count
+
     def __init__(self, solver):
         self._solver = solver
 
@@ -969,8 +1038,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_flows_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_flows_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -983,8 +1053,9 @@ cdef class Links:
             raise ValueError(f"flows array length {arr.shape[0]} != link count {n}")
         cdef const double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_link_set_flows_bulk(h, p, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_set_flows_bulk(h, p, n)
         _check(err)
 
     @property
@@ -993,8 +1064,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_depths_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_depths_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1004,8 +1076,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_velocities_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_velocities_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1015,8 +1088,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_capacities_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_capacities_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1026,8 +1100,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_volumes_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_volumes_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1037,8 +1112,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_control_settings_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_control_settings_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1048,8 +1124,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_target_settings_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_target_settings_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1059,8 +1136,9 @@ cdef class Links:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_hyd_powers_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_hyd_powers_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1071,8 +1149,9 @@ cdef class Links:
         cdef int p_idx = _resolve_pollutant(self._solver, pollutant)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_quality_bulk(h, p_idx, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_quality_bulk(h, p_idx, buf.data, n)
         _check(err)
         return buf
 
@@ -1085,9 +1164,10 @@ cdef class Links:
         cdef np.ndarray[double, ndim=1] ont = np.zeros(n, dtype=np.float64)
         cdef np.ndarray[double, ndim=1] vol = np.zeros(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_link_get_pump_stats_bulk(
-                h, cyc.data, ont.data, vol.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_pump_stats_bulk(
+                    h, cyc.data, ont.data, vol.data, n)
         _check(err)
         return (cyc, ont, vol)
 
@@ -1101,8 +1181,9 @@ cdef class Links:
         cdef np.ndarray[char, ndim=1, mode="c"] buf = np.zeros(
             n * stride, dtype=np.int8)
         cdef int err
-        with nogil:
-            err = swmm_link_get_ids_bulk(h, buf.data, stride, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_link_get_ids_bulk(h, buf.data, stride, n)
         _check(err)
         raw = bytes(buf)
         out = []
@@ -1119,3 +1200,7 @@ cdef class Links:
             return f""
         except Exception:
             return ""
+
+
+cdef extern from "openswmm/engine/openswmm_links.h":
+    int swmm_links_restore_authored_orientation(SWMM_Engine, int*)
diff --git a/python/openswmm/engine/_massbalance.pyx b/python/openswmm/engine/_massbalance.pyx
index 2dcc158b7..7da5f7b8c 100644
--- a/python/openswmm/engine/_massbalance.pyx
+++ b/python/openswmm/engine/_massbalance.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Mass balance & continuity (Pythonic v1 surface)
 ===============================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`MassBalance` view exposes continuity errors, flux totals,
 and routing diagnostics for a completed simulation. It is reached via
@@ -54,7 +70,7 @@ class MassBalance:
 
     @property
     def runoff_continuity_error(self) -> float:
-        """Runoff continuity error (%)."""
+        """Runoff continuity error as a fraction (0.001 means 0.1%)."""
         cdef SWMM_Engine h = self._solver.handle
         cdef double v = 0.0
         _check(swmm_get_runoff_continuity_error(h, &v))
@@ -62,14 +78,14 @@ class MassBalance:
 
     @property
     def routing_continuity_error(self) -> float:
-        """Flow routing continuity error (%)."""
+        """Flow routing continuity error as a fraction (0.001 means 0.1%)."""
         cdef SWMM_Engine h = self._solver.handle
         cdef double v = 0.0
         _check(swmm_get_routing_continuity_error(h, &v))
         return v
 
     def quality_continuity_error(self, pollutant) -> float:
-        """Quality continuity error (%) for ``pollutant`` (id or index)."""
+        """Quality continuity error as a fraction for ``pollutant`` (id or index)."""
         cdef int p = _resolve_pollutant(self._solver, pollutant)
         cdef SWMM_Engine h = self._solver.handle
         cdef double v = 0.0
diff --git a/python/openswmm/engine/_model.pyi b/python/openswmm/engine/_model.pyi
index ba4fcca76..f683cc1dc 100644
--- a/python/openswmm/engine/_model.pyi
+++ b/python/openswmm/engine/_model.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Programmatic Model Building
 ============================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._model`.
 
@@ -18,6 +34,9 @@ from typing import Optional
 from ._solver import Solver
 
 
+from ._transport import Transport, ThreadInfo, EffectiveThreads, TransportCell
+from ._enums import TransportDomain, TransportClass
+
 class ModelBuilder:
     """Build a SWMM model programmatically (no C{.inp} file).
 
@@ -41,6 +60,9 @@ class ModelBuilder:
         m.finalize()
         solver = m.to_solver()
     """
+    @property
+    def transport(self) -> Transport: ...
+
 
     def __init__(self) -> None: ...
 
@@ -495,10 +517,6 @@ class ModelBuilder:
     # =========================================================================
 
     start_datetime: datetime
-    """Simulation start date/time.
-
-    @raise EngineError: On C API failure.
-    """
 
     end_datetime: datetime
     """Simulation end date/time.
diff --git a/python/openswmm/engine/_model.pyx b/python/openswmm/engine/_model.pyx
index 42ef43b3a..4e751bc7b 100644
--- a/python/openswmm/engine/_model.pyx
+++ b/python/openswmm/engine/_model.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Programmatic Model Building
 ============================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`ModelBuilder` class creates a SWMM model entirely through the API
 without requiring a ``.inp`` file. Objects are added and configured while the
@@ -42,6 +58,9 @@ from datetime import datetime
 
 from ._common cimport *
 from ._solver cimport Solver
+from ._access import NativeAccess, register_owner
+from ._exceptions import BadHandleError
+from ._enums import ErrorCode
 from ._dates import datetime_to_oadate, oadate_to_datetime
 
 
@@ -69,6 +88,8 @@ cdef class ModelBuilder:
         solver = m.to_solver()
     """
 
+    cdef object __weakref__
+    cdef object _access
     cdef SWMM_Engine _handle
     # ``_generation`` mirrors :attr:`Solver._generation`: container-level
     # editors (``builder.tables.add_curve``, ``builder.transects.add``, …)
@@ -78,6 +99,7 @@ cdef class ModelBuilder:
     cdef long long _generation
 
     def __init__(self):
+        self._access = NativeAccess()
         self._handle = swmm_engine_new()
         if self._handle == NULL:
             raise MemoryError("Failed to create engine in BUILDING state")
@@ -421,12 +443,22 @@ cdef class ModelBuilder:
         @return: The underlying C engine pointer cast to an integer.
         @rtype: int
         """
-        return self._handle
+        self._access.check()
+        return register_owner(self, self._handle)
+
+    def _operation(self, expected=0):
+        return self._access.operation(self, expected)
 
     # =========================================================================
     # Conversion to Solver
     # =========================================================================
 
+    @property
+    def transport(self):
+        """ARD transport configuration and authored boundary/source rows."""
+        from ._transport import Transport
+        return Transport(self)
+
     def to_solver(self) -> Solver:
         """Transfer ownership of the engine handle to a L{Solver}.
 
@@ -436,13 +468,17 @@ cdef class ModelBuilder:
         @return: A new L{Solver} wrapping this model's engine.
         @rtype: L{Solver}
         """
-        cdef Solver s = Solver.__new__(Solver)
+        self._access.require_idle()
+        if self._handle == NULL:
+            raise BadHandleError(ErrorCode.BADHANDLE, "Builder ownership has already been transferred")
+        cdef Solver s = Solver()
         s._handle = self._handle
         s._elapsed = 0.0
         s._inp = ""
         s._rpt = ""
         s._out = ""
         self._handle = NULL
+        self._generation += 1
         return s
 
     # =========================================================================
diff --git a/python/openswmm/engine/_nodes.pyi b/python/openswmm/engine/_nodes.pyi
index 5f83ffc60..5d7537881 100644
--- a/python/openswmm/engine/_nodes.pyi
+++ b/python/openswmm/engine/_nodes.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Node access (Pythonic v1 surface)
 =================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._nodes`.
 """
@@ -65,11 +81,14 @@ class Node:
     type: NodeType
     is_virtual: bool
     virtual_rule_violation: int
+    is_inlet: bool
+    def inlet_rule_violation(self, for_drop_inlet: bool = ...) -> int: ...
     solver: Solver
 
     # Geometry
     invert_elev: float
     max_depth: float
+    rim_depth: float
     surcharge_depth: float
     ponded_area: float
     initial_depth: float
diff --git a/python/openswmm/engine/_nodes.pyx b/python/openswmm/engine/_nodes.pyx
index d4e753103..1aeaf78b9 100644
--- a/python/openswmm/engine/_nodes.pyx
+++ b/python/openswmm/engine/_nodes.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Node access (Pythonic v1 surface)
 =================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Nodes` collection and :class:`Node` wrapper are the entry
 point for reading and writing node state in the new bindings. The
@@ -458,11 +474,13 @@ cdef class Node:
         """Dry-run check of the virtual-junction usage rules for this node.
 
         C{0} when the node satisfies every structural rule (exactly two
-        attached conduits of identical cross-section, zero offsets, no
-        lateral inflow sources, dynamic-wave routing) — i.e. setting
-        L{is_virtual} to C{True} would succeed on a JUNCTION-typed node —
-        else the distinct ERR_VJ_* rule code (609-621) identifying the
-        violated rule. Read-only; no state is changed.
+        attached conduits of identical cross-section, zero offsets, not a
+        2D surface-coupling point, dynamic-wave or FV routing) — i.e.
+        setting L{is_virtual} to C{True} would succeed on a JUNCTION-typed
+        node — else the distinct ERR_VJ_* rule code (609-621) identifying
+        the violated rule. Point lateral inflows ([INFLOWS], [DWF], RDII,
+        subcatchment outlets, LID drains) do not disqualify a node.
+        Read-only; no state is changed.
 
         @rtype: int
         """
@@ -471,6 +489,58 @@ cdef class Node:
         _check(swmm_node_virtual_eligible(_h(self._solver), self._index, &code))
         return code
 
+    @property
+    def is_inlet(self) -> bool:
+        """C{True} when this node is an B{inlet junction}.
+
+        An inlet junction is a virtual junction on a STREET conduit pair that
+        also carries a street inlet: it captures gutter flow from the
+        approaching conduit, delivers it to a designated capture (underdrain)
+        node, passes the uncaptured flow on through the downstream conduit,
+        and receives the capture node's overflow back as backflow (INP
+        C{[INLET_JUNCTIONS]}; refactored engine only). C{is_inlet} implies
+        L{is_virtual}.
+
+        Setting to C{True} runs the virtual-junction rules plus the street
+        shape rule (623) and promotes the node to a virtual junction first if
+        it is not one; a violated rule raises and leaves the node unchanged.
+        Setting to C{False} demotes it and deletes its inlet-usage row (the
+        node stays a virtual junction).
+
+        @rtype: bool
+        """
+        _check_fresh(self)
+        cdef int v = 0
+        _check(swmm_node_is_inlet(_h(self._solver), self._index, &v))
+        return v != 0
+
+    @is_inlet.setter
+    def is_inlet(self, value) -> None:
+        _check_fresh(self)
+        _check(swmm_node_set_inlet(_h(self._solver), self._index,
+                                   1 if value else 0))
+
+    def inlet_rule_violation(self, bint for_drop_inlet=False) -> int:
+        """Dry-run check of the inlet-junction usage rules for this node.
+
+        C{0} when setting L{is_inlet} to C{True} would succeed — every
+        virtual-junction rule holds B{and} both attached conduits carry the
+        cross-section the design needs — else the violated rule's code (the
+        ERR_VJ_* codes 609-621, or 623 when the conduits are not STREET).
+        Read-only; no state is changed.
+
+        @param for_drop_inlet: Check against a C{DROP_GRATE}/C{DROP_CURB}
+            design, whose conduits must be C{RECT_OPEN} or C{TRAPEZOIDAL}
+            rather than C{STREET}.
+        @type for_drop_inlet: bool
+        @rtype: int
+        """
+        _check_fresh(self)
+        cdef int code = 0
+        _check(swmm_node_inlet_eligible(_h(self._solver), self._index,
+                                        1 if for_drop_inlet else 0, &code))
+        return code
+
     @property
     def solver(self):
         """The parent :class:`Solver`. Useful for cross-domain access."""
@@ -502,6 +572,28 @@ cdef class Node:
         _check_fresh(self)
         _check(swmm_node_set_max_depth(_h(self._solver), self._index, value))
 
+    @property
+    def rim_depth(self) -> float:
+        """Rendering-only rim (ground) depth above the invert; 0 = unset.
+
+        No hydraulics, routing, reporting or output-file path reads this, so
+        setting it can never change a result. It exists for virtual junctions,
+        whose L{max_depth} is derived (always the shared pipe crown): without
+        it a drawn ground line collapses to the crown at every break point.
+        It is the optional third token of an INP C{[VIRTUAL_JUNCTIONS]} row.
+
+        When 0, a renderer should fall back to L{max_depth}.
+        """
+        _check_fresh(self)
+        cdef double v = 0.0
+        _check(swmm_node_get_rim_depth(_h(self._solver), self._index, &v))
+        return v
+
+    @rim_depth.setter
+    def rim_depth(self, double value) -> None:
+        _check_fresh(self)
+        _check(swmm_node_set_rim_depth(_h(self._solver), self._index, value))
+
     @property
     def surcharge_depth(self) -> float:
         _check_fresh(self)
@@ -817,8 +909,9 @@ cdef class Nodes:
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef double* p = buf.data
         cdef int err
-        with nogil:
-            err = swmm_node_get_depths_bulk(h, p, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_depths_bulk(h, p, n)
         _check(err)
         return buf
 
@@ -832,8 +925,9 @@ cdef class Nodes:
                 f"depths array length {arr.shape[0]} != node count {n}")
         cdef const double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_node_set_depths_bulk(h, p, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_set_depths_bulk(h, p, n)
         _check(err)
 
     @property
@@ -842,8 +936,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_heads_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_heads_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -853,8 +948,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_inflows_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_inflows_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -864,8 +960,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_overflows_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_overflows_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -875,8 +972,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_volumes_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_volumes_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -886,8 +984,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_outflows_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_outflows_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -897,8 +996,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_losses_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_losses_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -908,8 +1008,9 @@ cdef class Nodes:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_lateral_inflows_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_lateral_inflows_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -925,8 +1026,9 @@ cdef class Nodes:
                 f"lateral_inflows array length {arr.shape[0]} != node count {n}")
         cdef const double* p = arr.data
         cdef int err
-        with nogil:
-            err = swmm_node_set_lat_inflows_bulk(h, p, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_set_lat_inflows_bulk(h, p, n)
         _check(err)
 
     def qualities(self, pollutant):
@@ -936,8 +1038,9 @@ cdef class Nodes:
         cdef int p_idx = _resolve_pollutant(self._solver, pollutant)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_node_get_quality_bulk(h, p_idx, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_quality_bulk(h, p_idx, buf.data, n)
         _check(err)
         return buf
 
@@ -952,8 +1055,9 @@ cdef class Nodes:
         cdef np.ndarray[char, ndim=1, mode="c"] buf = np.zeros(
             n * stride, dtype=np.int8)
         cdef int err
-        with nogil:
-            err = swmm_node_get_ids_bulk(h, buf.data, stride, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_node_get_ids_bulk(h, buf.data, stride, n)
         _check(err)
         raw = bytes(buf)
         out = []
diff --git a/python/openswmm/engine/_output_reader.pyi b/python/openswmm/engine/_output_reader.pyi
index f84566333..160f33466 100644
--- a/python/openswmm/engine/_output_reader.pyi
+++ b/python/openswmm/engine/_output_reader.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Binary output file reader (Pythonic v1 surface)
 ===============================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._output_reader`.
 """
@@ -33,6 +49,10 @@ class _OutputNodeStats:
 class OutputReader:
     """Read a SWMM binary ``.out`` file."""
 
+    @property
+    def is_live(self) -> bool: ...
+    def refresh(self) -> int: ...
+
     # Metadata
     version: int
     flow_units: FlowUnits
@@ -49,11 +69,12 @@ class OutputReader:
     node_ids: List[str]
     link_ids: List[str]
     subcatchment_ids: List[str]
+    pollutant_ids: List[str]
 
     # Time axis
     period_times: NDArray[Any]  # dtype = datetime64[s]
 
-    def __init__(self, path: _PathLike) -> None: ...
+    def __init__(self, path: _PathLike, *, live: bool = ...) -> None: ...
     def close(self) -> None: ...
     def __enter__(self) -> "OutputReader": ...
     def __exit__(self, *args: Any) -> bool: ...
diff --git a/python/openswmm/engine/_output_reader.pyx b/python/openswmm/engine/_output_reader.pyx
index 4aaf400b9..271816f5e 100644
--- a/python/openswmm/engine/_output_reader.pyx
+++ b/python/openswmm/engine/_output_reader.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Binary output file reader (Pythonic v1 surface)
 ===============================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`OutputReader` reads a SWMM binary ``.out`` file
 independently of any running engine.
@@ -59,15 +75,19 @@ cdef class OutputReader:
     :raises FileError: If the file cannot be opened.
     """
 
+    cdef object _lock
     cdef SWMM_Output _handle
     cdef object _node_ids       # cached list[str]
     cdef object _link_ids
     cdef object _subcatch_ids
+    cdef object _pollutant_ids
     cdef object _period_times   # cached np.ndarray[datetime64[s]]
 
-    def __init__(self, path):
+    def __init__(self, path, *, bint live=False):
+        from threading import RLock
+        self._lock = RLock()
         cdef bytes b = os.fspath(path).encode('utf-8')
-        self._handle = swmm_output_open(b)
+        self._handle = swmm_output_open_live(b) if live else swmm_output_open(b)
         if self._handle == NULL:
             from ._exceptions import FileError
             from ._enums import ErrorCode
@@ -76,14 +96,49 @@ cdef class OutputReader:
         self._node_ids = None
         self._link_ids = None
         self._subcatch_ids = None
+        self._pollutant_ids = None
         self._period_times = None
 
     # ------------------------------------------------------------------
     # Lifecycle
     # ------------------------------------------------------------------
 
+    cdef void _check_access(self) except *:
+        if not self._lock.acquire(blocking=False):
+            from ._exceptions import LifecycleError
+            from ._enums import ErrorCode
+            raise LifecycleError(ErrorCode.LIFECYCLE, "OutputReader is in use by another thread")
+        self._lock.release()
+
+    cdef SWMM_Output _h(self) except NULL:
+        self._check_access()
+        if self._handle == NULL:
+            from ._exceptions import BadHandleError
+            from ._enums import ErrorCode
+            raise BadHandleError(ErrorCode.BADHANDLE, "OutputReader is closed")
+        return self._handle
+
+    @property
+    def is_live(self):
+        """Whether the reader is waiting for the writer's closing records."""
+        return bool(swmm_output_is_live(self._h()))
+
+    def refresh(self):
+        """Refresh completed periods and invalidate cached timestamps.
+
+        Once closing records appear this becomes an ordinary reader.
+        Returns the available period count. Does not modify the file.
+        """
+        cdef int periods = 0
+        cdef int rc = swmm_output_refresh(self._h(), &periods)
+        if rc:
+            raise RuntimeError("Unable to refresh output file")
+        self._period_times = None
+        return periods
+
     def close(self) -> None:
         """Close the binary output file and release its handle."""
+        self._check_access()
         if self._handle != NULL:
             swmm_output_close(self._handle)
             self._handle = NULL
@@ -106,24 +161,24 @@ cdef class OutputReader:
 
     @property
     def version(self) -> int:
-        return swmm_output_get_version(self._handle)
+        return swmm_output_get_version(self._h())
 
     @property
     def flow_units(self):
-        return FlowUnits(swmm_output_get_flow_units(self._handle))
+        return FlowUnits(swmm_output_get_flow_units(self._h()))
 
     @property
     def period_count(self) -> int:
-        return swmm_output_get_period_count(self._handle)
+        return swmm_output_get_period_count(self._h())
 
     @property
     def report_step(self) -> timedelta:
-        return timedelta(seconds=swmm_output_get_report_step(self._handle))
+        return timedelta(seconds=swmm_output_get_report_step(self._h()))
 
     @property
     def start_datetime(self) -> datetime:
         cdef double v = 0.0
-        cdef int rc = swmm_output_get_start_date(self._handle, &v)
+        cdef int rc = swmm_output_get_start_date(self._h(), &v)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -131,24 +186,24 @@ cdef class OutputReader:
 
     @property
     def pollutant_count(self) -> int:
-        return swmm_output_get_pollut_count(self._handle)
+        return swmm_output_get_pollut_count(self._h())
 
     @property
     def node_count(self) -> int:
-        return swmm_output_get_node_count(self._handle)
+        return swmm_output_get_node_count(self._h())
 
     @property
     def link_count(self) -> int:
-        return swmm_output_get_link_count(self._handle)
+        return swmm_output_get_link_count(self._h())
 
     @property
     def subcatchment_count(self) -> int:
-        return swmm_output_get_subcatch_count(self._handle)
+        return swmm_output_get_subcatch_count(self._h())
 
     @property
     def error_code(self) -> int:
         """SWMM error code stored in the file footer (0 = clean run)."""
-        return swmm_output_get_error_code(self._handle)
+        return swmm_output_get_error_code(self._h())
 
     # ------------------------------------------------------------------
     # Object id arrays
@@ -156,46 +211,72 @@ cdef class OutputReader:
 
     @property
     def node_ids(self) -> List[str]:
+        self._h()
         if self._node_ids is None:
             self._node_ids = self._read_node_ids()
         return list(self._node_ids)
 
     @property
     def link_ids(self) -> List[str]:
+        self._h()
         if self._link_ids is None:
             self._link_ids = self._read_link_ids()
         return list(self._link_ids)
 
     @property
     def subcatchment_ids(self) -> List[str]:
+        self._h()
         if self._subcatch_ids is None:
             self._subcatch_ids = self._read_subcatch_ids()
         return list(self._subcatch_ids)
 
+    @property
+    def pollutant_ids(self) -> List[str]:
+        """Species (pollutant) column names, in column order.
+
+        Reading these names is the only way to identify what a species column
+        holds: the per-column unit field is a three-value concentration enum,
+        so the water-age column (``__WATER_AGE__``, reported in HOURS) reuses
+        a concentration code. Key on the name, not on the unit code.
+        """
+        self._h()
+        if self._pollutant_ids is None:
+            self._pollutant_ids = self._read_pollutant_ids()
+        return list(self._pollutant_ids)
+
     cdef list _read_node_ids(self):
-        cdef int n = swmm_output_get_node_count(self._handle)
+        cdef int n = swmm_output_get_node_count(self._h())
         cdef const char* raw
         out = []
         for i in range(n):
-            raw = swmm_output_get_node_id(self._handle, i)
+            raw = swmm_output_get_node_id(self._h(), i)
             out.append(raw.decode('utf-8') if raw != NULL else "")
         return out
 
     cdef list _read_link_ids(self):
-        cdef int n = swmm_output_get_link_count(self._handle)
+        cdef int n = swmm_output_get_link_count(self._h())
         cdef const char* raw
         out = []
         for i in range(n):
-            raw = swmm_output_get_link_id(self._handle, i)
+            raw = swmm_output_get_link_id(self._h(), i)
             out.append(raw.decode('utf-8') if raw != NULL else "")
         return out
 
     cdef list _read_subcatch_ids(self):
-        cdef int n = swmm_output_get_subcatch_count(self._handle)
+        cdef int n = swmm_output_get_subcatch_count(self._h())
         cdef const char* raw
         out = []
         for i in range(n):
-            raw = swmm_output_get_subcatch_id(self._handle, i)
+            raw = swmm_output_get_subcatch_id(self._h(), i)
+            out.append(raw.decode('utf-8') if raw != NULL else "")
+        return out
+
+    cdef list _read_pollutant_ids(self):
+        cdef int n = swmm_output_get_pollut_count(self._h())
+        cdef const char* raw
+        out = []
+        for i in range(n):
+            raw = swmm_output_get_pollut_id(self._h(), i)
             out.append(raw.decode('utf-8') if raw != NULL else "")
         return out
 
@@ -211,12 +292,12 @@ cdef class OutputReader:
         """
         if self._period_times is not None:
             return self._period_times
-        cdef int n = swmm_output_get_period_count(self._handle)
+        cdef int n = swmm_output_get_period_count(self._h())
         cdef double t = 0.0
         cdef int rc
         py_dts = np.empty(n, dtype='datetime64[s]')
         for i in range(n):
-            rc = swmm_output_get_period_time(self._handle, i, &t)
+            rc = swmm_output_get_period_time(self._h(), i, &t)
             if rc != 0:
                 from ._exceptions import raise_for_code
                 raise_for_code(rc)
@@ -244,11 +325,11 @@ cdef class OutputReader:
             raise TypeError(f"{kind} key must be int or str, got bool")
         if isinstance(key, int):
             if kind == "node":
-                count = swmm_output_get_node_count(self._handle)
+                count = swmm_output_get_node_count(self._h())
             elif kind == "link":
-                count = swmm_output_get_link_count(self._handle)
+                count = swmm_output_get_link_count(self._h())
             else:
-                count = swmm_output_get_subcatch_count(self._handle)
+                count = swmm_output_get_subcatch_count(self._h())
             if not 0 <= key < count:
                 raise IndexError(f"{kind} index {key} out of range [0, {count})")
             return key
@@ -264,10 +345,10 @@ cdef class OutputReader:
     def node_result(self, int period, var) -> np.ndarray:
         """All nodes' value of ``var`` at ``period``."""
         cdef int v = int(var)
-        cdef int n = swmm_output_get_node_count(self._handle)
+        cdef int n = swmm_output_get_node_count(self._h())
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
         cdef int rc = swmm_output_get_node_result(
-            self._handle, period, v, buf.data)
+            self._h(), period, v, buf.data)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -276,10 +357,10 @@ cdef class OutputReader:
     def link_result(self, int period, var) -> np.ndarray:
         """Return an array of *var* values for every link at output *period*."""
         cdef int v = int(var)
-        cdef int n = swmm_output_get_link_count(self._handle)
+        cdef int n = swmm_output_get_link_count(self._h())
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
         cdef int rc = swmm_output_get_link_result(
-            self._handle, period, v, buf.data)
+            self._h(), period, v, buf.data)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -288,10 +369,10 @@ cdef class OutputReader:
     def subcatchment_result(self, int period, var) -> np.ndarray:
         """Return an array of *var* values for every subcatchment at output *period*."""
         cdef int v = int(var)
-        cdef int n = swmm_output_get_subcatch_count(self._handle)
+        cdef int n = swmm_output_get_subcatch_count(self._h())
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
         cdef int rc = swmm_output_get_subcatch_result(
-            self._handle, period, v, buf.data)
+            self._h(), period, v, buf.data)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -302,7 +383,7 @@ cdef class OutputReader:
         cdef int v = int(var)
         cdef float value = 0.0
         cdef int rc = swmm_output_get_system_result(
-            self._handle, period, v, &value)
+            self._h(), period, v, &value)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -326,16 +407,17 @@ cdef class OutputReader:
         """Return the time series of *var* for *node* over the reporting window."""
         cdef int idx = self._resolve(node, "node")
         cdef int v = int(var)
-        cdef int period_count = swmm_output_get_period_count(self._handle)
+        cdef int period_count = swmm_output_get_period_count(self._h())
         cdef int s, e
         s, e = self._series_range(period_count, start, end)
         cdef int n = e - s + 1
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
-        cdef SWMM_Output h = self._handle
+        cdef SWMM_Output h = self._h()
         cdef float* p = buf.data
         cdef int rc
-        with nogil:
-            rc = swmm_output_get_node_series(h, idx, v, s, e, p)
+        with self._lock:
+            with nogil:
+                rc = swmm_output_get_node_series(h, idx, v, s, e, p)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -345,16 +427,17 @@ cdef class OutputReader:
         """Return the time series of *var* for *link* over the reporting window."""
         cdef int idx = self._resolve(link, "link")
         cdef int v = int(var)
-        cdef int period_count = swmm_output_get_period_count(self._handle)
+        cdef int period_count = swmm_output_get_period_count(self._h())
         cdef int s, e
         s, e = self._series_range(period_count, start, end)
         cdef int n = e - s + 1
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
-        cdef SWMM_Output h = self._handle
+        cdef SWMM_Output h = self._h()
         cdef float* p = buf.data
         cdef int rc
-        with nogil:
-            rc = swmm_output_get_link_series(h, idx, v, s, e, p)
+        with self._lock:
+            with nogil:
+                rc = swmm_output_get_link_series(h, idx, v, s, e, p)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -364,16 +447,17 @@ cdef class OutputReader:
         """Return the time series of *var* for *sub* over the reporting window."""
         cdef int idx = self._resolve(sub, "subcatchment")
         cdef int v = int(var)
-        cdef int period_count = swmm_output_get_period_count(self._handle)
+        cdef int period_count = swmm_output_get_period_count(self._h())
         cdef int s, e
         s, e = self._series_range(period_count, start, end)
         cdef int n = e - s + 1
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
-        cdef SWMM_Output h = self._handle
+        cdef SWMM_Output h = self._h()
         cdef float* p = buf.data
         cdef int rc
-        with nogil:
-            rc = swmm_output_get_subcatch_series(h, idx, v, s, e, p)
+        with self._lock:
+            with nogil:
+                rc = swmm_output_get_subcatch_series(h, idx, v, s, e, p)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -382,16 +466,17 @@ cdef class OutputReader:
     def system_series(self, var, *, start=None, end=None) -> np.ndarray:
         """Return the system-wide time series of *var* over the reporting window."""
         cdef int v = int(var)
-        cdef int period_count = swmm_output_get_period_count(self._handle)
+        cdef int period_count = swmm_output_get_period_count(self._h())
         cdef int s, e
         s, e = self._series_range(period_count, start, end)
         cdef int n = e - s + 1
         cdef np.ndarray[float, ndim=1] buf = np.empty(n, dtype=np.float32)
-        cdef SWMM_Output h = self._handle
+        cdef SWMM_Output h = self._h()
         cdef float* p = buf.data
         cdef int rc
-        with nogil:
-            rc = swmm_output_get_system_series(h, v, s, e, p)
+        with self._lock:
+            with nogil:
+                rc = swmm_output_get_system_series(h, v, s, e, p)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -408,7 +493,7 @@ cdef class OutputReader:
         cdef int budget = max(32, int(OutNodeVar.POLLUT_BASE) + self.pollutant_count)
         cdef np.ndarray[float, ndim=1] buf = np.empty(budget, dtype=np.float32)
         cdef int rc = swmm_output_get_node_attribute(
-            self._handle, idx, period, buf.data, &n_attrs)
+            self._h(), idx, period, buf.data, &n_attrs)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -421,7 +506,7 @@ cdef class OutputReader:
         cdef int budget = max(32, int(OutLinkVar.POLLUT_BASE) + self.pollutant_count)
         cdef np.ndarray[float, ndim=1] buf = np.empty(budget, dtype=np.float32)
         cdef int rc = swmm_output_get_link_attribute(
-            self._handle, idx, period, buf.data, &n_attrs)
+            self._h(), idx, period, buf.data, &n_attrs)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -434,7 +519,7 @@ cdef class OutputReader:
         cdef int budget = max(32, int(OutSubcatchVar.POLLUT_BASE) + self.pollutant_count)
         cdef np.ndarray[float, ndim=1] buf = np.empty(budget, dtype=np.float32)
         cdef int rc = swmm_output_get_subcatch_attribute(
-            self._handle, idx, period, buf.data, &n_attrs)
+            self._h(), idx, period, buf.data, &n_attrs)
         if rc != 0:
             from ._exceptions import raise_for_code
             raise_for_code(rc)
@@ -538,3 +623,8 @@ cdef class _OutputNodeStats:
 
     def __repr__(self) -> str:
         return f"<_OutputNodeStats index={self._index}>"
+
+cdef extern from "openswmm/engine/openswmm_output.h":
+    SWMM_Output swmm_output_open_live(const char*)
+    int swmm_output_refresh(SWMM_Output, int*)
+    int swmm_output_is_live(SWMM_Output)
diff --git a/python/openswmm/engine/_pollutants.pyi b/python/openswmm/engine/_pollutants.pyi
index d763fea16..2942743e5 100644
--- a/python/openswmm/engine/_pollutants.pyi
+++ b/python/openswmm/engine/_pollutants.pyi
@@ -33,6 +33,7 @@ class Pollutant:
 
 
 class Pollutants:
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def __init__(self, solver: Solver) -> None: ...
     def __len__(self) -> int: ...
     def __iter__(self) -> Iterator[Pollutant]: ...
diff --git a/python/openswmm/engine/_pollutants.pyx b/python/openswmm/engine/_pollutants.pyx
index 4685982e1..dcbd623d2 100644
--- a/python/openswmm/engine/_pollutants.pyx
+++ b/python/openswmm/engine/_pollutants.pyx
@@ -1,13 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Pollutant access (Pythonic v1 surface)
 ======================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Pollutants` collection and :class:`Pollutant` wrapper
-mirror the shape of :doc:`nodes` / :doc:`links`.
+mirror the shape of :doc:`/guide/nodes` / :doc:`/guide/links`.
 
 .. code-block:: python
 
diff --git a/python/openswmm/engine/_process_components.pyi b/python/openswmm/engine/_process_components.pyi
new file mode 100644
index 000000000..d543991e3
--- /dev/null
+++ b/python/openswmm/engine/_process_components.pyi
@@ -0,0 +1,38 @@
+from __future__ import annotations
+"""Type stubs for :mod:`openswmm.engine._process_components`."""
+
+from collections.abc import Iterator
+from typing import NamedTuple, Union
+
+from ._solver import Solver
+
+
+_Key = Union[int, str]
+
+
+class ProcessComponent(NamedTuple):
+    component_index: int
+    id: str
+    config: str
+    resolved: str
+
+
+class ProcessComponents:
+    @staticmethod
+    def known() -> tuple[KnownProcessComponent, ...]: ...
+
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[ProcessComponent]: ...
+    def __getitem__(self, key: _Key) -> ProcessComponent: ...
+    def __contains__(self, component_id: object) -> bool: ...
+    def get_index(self, component_id: str) -> int: ...
+    def register(
+        self, component_id: str, config_path: str = ...,
+    ) -> ProcessComponent: ...
+    def remove(self, key: _Key) -> None: ...
+
+class KnownProcessComponent(NamedTuple):
+    id: str
+    description: str
+    implemented: bool
diff --git a/python/openswmm/engine/_process_components.pyx b/python/openswmm/engine/_process_components.pyx
new file mode 100644
index 000000000..00452f854
--- /dev/null
+++ b/python/openswmm/engine/_process_components.pyx
@@ -0,0 +1,269 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Process components (Pythonic v1 surface)
+========================================
+
+:author: Caleb Buahin
+:copyright: Copyright (c) 2026 Caleb Buahin
+:license: Apache-2.0
+
+``solver.process_components`` is the ``[PROCESS_COMPONENTS]`` registration
+table — the file-binding surface a component editor uses to locate the config
+file its section is stored in. Each registration carries an id, the
+``config="…"`` argument **as written** (which may be empty), and the effective
+path the config was actually READ from at the last open.
+
+Registering a component whose config file **does not exist yet** is legal and
+deliberate: the "create component + config file" flow registers first and
+writes the file afterwards, and the path is resolved at the next open. Until
+that resolution happens, :attr:`ProcessComponent.resolved` is ``""``.
+Registering an id that is already registered is refused.
+
+Registration and removal are ``BUILDING``/``OPENED`` edits, and removal
+**shifts every later index down**, so cached indexes must be re-read.
+
+.. code-block:: python
+
+    from openswmm.engine import Solver
+
+    with Solver("model.inp") as s:
+        pc = s.process_components.register("reactions", "model.rxn")
+        print(pc.index, pc.id, pc.config, pc.resolved)  # resolved is "" here
+        if "reactions" in s.process_components:
+            print(s.process_components["reactions"].config)
+        for comp in s.process_components:
+            print(comp.id, comp.config or "(none)")
+        s.process_components.remove("reactions")    # later indexes shift
+"""
+
+# cython: language_level=3
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from ._common cimport *
+from ._enums import ErrorCode
+from ._exceptions import BadHandleError, ElementNotFoundError
+
+
+cdef inline SWMM_Engine _h(solver):
+    return solver.handle
+
+
+class ProcessComponent(NamedTuple):
+    """One ``[PROCESS_COMPONENTS]`` registration.
+
+    :ivar component_index: Zero-based registration index. **Not stable across
+        removals** — removing a registration shifts every later index down.
+    :ivar id: The component id.
+    :ivar config: The ``config="…"`` argument exactly as written in the deck.
+        ``""`` when the registration names no config file.
+    :ivar resolved: The effective path the config was READ from at the last
+        open. ``""`` until the component has been resolved — including right
+        after :meth:`ProcessComponents.register`, and for a registration whose
+        config file does not exist yet.
+    """
+
+    component_index: int
+    id: str
+    config: str
+    resolved: str
+
+
+class KnownProcessComponent(NamedTuple):
+    """Registry entry, independent of configured model registrations."""
+    id: str
+    description: str
+    implemented: bool
+
+
+class ProcessComponents:
+    """``solver.process_components`` — the ``[PROCESS_COMPONENTS]`` table.
+
+    A sequence of :class:`ProcessComponent` rows, addressable by index or by
+    id. Rows are flat snapshots, not live views.
+    """
+
+    @staticmethod
+    def known():
+        """Built-in component vocabulary, including unimplemented placeholders."""
+        cdef int index, implemented = 0
+        cdef char identifier[512]
+        cdef char description[4096]
+        rows = []
+        for index in range(swmm_process_component_known_count()):
+            _check(swmm_process_component_known_get(index, identifier, 512,
+                                                    description, 4096, &implemented))
+            rows.append(KnownProcessComponent(identifier.decode('utf-8'),
+                                              description.decode('utf-8'), bool(implemented)))
+        return tuple(rows)
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of ``[PROCESS_COMPONENTS]`` registrations.
+
+        :returns: The registration count.
+        :raises BadHandleError: The engine handle is invalid.
+        """
+        cdef int n = swmm_process_component_count(_h(self._solver))
+        if n < 0:
+            raise BadHandleError(
+                int(ErrorCode.BADHANDLE),
+                "Invalid engine handle reading [PROCESS_COMPONENTS] count")
+        return n
+
+    def __iter__(self) -> Iterator[ProcessComponent]:
+        cdef int n = len(self)
+        for i in range(n):
+            yield self._get(i)
+
+    def __getitem__(self, key) -> ProcessComponent:
+        """Read one registration by index or by id.
+
+        :param key: ``int`` registration index (negatives count from the end)
+            or ``str`` component id.
+        :returns: A :class:`ProcessComponent` of
+            ``(index, id, config, resolved)``.
+        :raises IndexError: An ``int`` *key* is out of range.
+        :raises ElementNotFoundError: A ``str`` *key* names no registration.
+        :raises TypeError: *key* is neither ``int`` nor ``str``.
+        :raises EngineError: The engine refused the read.
+        """
+        return self._get(self._index_of(key))
+
+    def __contains__(self, component_id) -> bool:
+        """Is a component with this id registered?
+
+        :param component_id: The component id to look for.
+        :returns: ``True`` when a registration with that id exists.
+        """
+        if not isinstance(component_id, str):
+            return False
+        cdef bytes b = (component_id).encode('utf-8')
+        return swmm_process_component_find(_h(self._solver), b) >= 0
+
+    def get_index(self, str component_id) -> int:
+        """Return the registration index of *component_id*.
+
+        :param component_id: The component id.
+        :returns: The zero-based registration index. Valid only until the next
+            removal, which shifts later indexes down.
+        :raises ElementNotFoundError: No registration carries that id.
+        """
+        cdef bytes b = component_id.encode('utf-8')
+        cdef int i = swmm_process_component_find(_h(self._solver), b)
+        if i < 0:
+            raise ElementNotFoundError(
+                component_id,
+                f"Process component '{component_id}' not found")
+        return i
+
+    def register(self, str component_id, str config_path="") -> ProcessComponent:
+        """Register a process component and return the new row.
+
+        ``BUILDING``/``OPENED`` only. *config_path* **need not exist yet** —
+        the "create component, then write its config file" flow registers
+        first and writes afterwards; the path is read at the next open, so the
+        returned row's :attr:`~ProcessComponent.resolved` is ``""`` until
+        then. A duplicate id is refused rather than overwritten.
+
+        :param component_id: The component id to register.
+        :param config_path: The ``config="…"`` path to record; ``""`` (the
+            default) registers the component with no config file.
+        :returns: The newly registered :class:`ProcessComponent`.
+        :raises BadParamError: *component_id* is already registered, or is
+            otherwise not a usable id.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b_id = component_id.encode('utf-8')
+        cdef bytes b_path = config_path.encode('utf-8')
+        _check(swmm_process_component_register(
+            _h(self._solver), b_id, b_path))
+        self._solver._bump_generation()
+        return self._get(self.get_index(component_id))
+
+    def remove(self, key) -> None:
+        """Remove one registration, by index or by id.
+
+        ``BUILDING``/``OPENED`` only. Every later registration **shifts down
+        by one**, so a caller holding cached indexes must re-enumerate. The
+        config file itself is untouched — only the registration goes away.
+
+        :param key: ``int`` registration index (negatives count from the end)
+            or ``str`` component id.
+        :raises IndexError: An ``int`` *key* is out of range.
+        :raises ElementNotFoundError: A ``str`` *key* names no registration.
+        :raises TypeError: *key* is neither ``int`` nor ``str``.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef int idx = self._index_of(key)
+        _check(swmm_process_component_remove(_h(self._solver), idx))
+        self._solver._bump_generation()
+
+    # ---- Internals ---------------------------------------------------
+
+    def _index_of(self, key) -> int:
+        """Resolve *key* (index or id) to a validated registration index."""
+        cdef int n
+        cdef int i
+        if isinstance(key, str):
+            return self.get_index(key)
+        # ``bool`` is a subclass of ``int`` — reject it explicitly so
+        # ``components[True]`` doesn't silently mean index 1.
+        if isinstance(key, bool):
+            raise TypeError(
+                "Process component key must be int or str, got bool")
+        if isinstance(key, int) or hasattr(key, "__index__"):
+            n = len(self)
+            i = key.__index__()
+            if i < 0:
+                i += n
+            if not (0 <= i < n):
+                raise IndexError(key)
+            return i
+        raise TypeError(
+            "Process component key must be int or str, got "
+            f"{type(key).__name__}")
+
+    def _get(self, int idx) -> ProcessComponent:
+        """Read registration *idx* into a :class:`ProcessComponent`."""
+        cdef char id_buf[128]
+        cdef char config_buf[512]
+        cdef char resolved_buf[512]
+        id_buf[0] = 0
+        config_buf[0] = 0
+        resolved_buf[0] = 0
+        _check(swmm_process_component_get(
+            _h(self._solver), idx, id_buf, 128, config_buf, 512,
+            resolved_buf, 512))
+        return ProcessComponent(
+            idx, id_buf.decode('utf-8'), config_buf.decode('utf-8'),
+            resolved_buf.decode('utf-8'))
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+cdef extern from "openswmm/engine/openswmm_process_components.h":
+    int swmm_process_component_known_count()
+    int swmm_process_component_known_get(int, char*, int, char*, int, int*)
diff --git a/python/openswmm/engine/_quality.pyi b/python/openswmm/engine/_quality.pyi
index f48a9fe23..ad218fbd2 100644
--- a/python/openswmm/engine/_quality.pyi
+++ b/python/openswmm/engine/_quality.pyi
@@ -11,6 +11,7 @@ _Key = Union[int, str]
 
 
 class Landuse:
+    def rename(self, new_id: str) -> None: ...
     id: str
     index: int
     sweep_interval: float
@@ -31,6 +32,7 @@ class Landuses:
 
 
 class Quality:
+    def validate_treatment_expression(self, expression: str) -> tuple[bool, str, int]: ...
     def __init__(self, solver: Solver) -> None: ...
 
     landuses: Landuses
diff --git a/python/openswmm/engine/_quality.pyx b/python/openswmm/engine/_quality.pyx
index 0f7b4b6bf..397004b4c 100644
--- a/python/openswmm/engine/_quality.pyx
+++ b/python/openswmm/engine/_quality.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Water quality (Pythonic v1 surface)
 ===================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 ``solver.quality`` exposes landuse, buildup, washoff, and treatment
 configuration with enum-typed function selectors and ``int | str``
diff --git a/python/openswmm/engine/_reactions.pyi b/python/openswmm/engine/_reactions.pyi
new file mode 100644
index 000000000..5bb91d0f6
--- /dev/null
+++ b/python/openswmm/engine/_reactions.pyi
@@ -0,0 +1,144 @@
+"""Type stubs for :mod:`openswmm.engine._reactions`."""
+
+from collections.abc import Iterator
+from typing import NamedTuple, Optional, Tuple, Union
+
+from ._enums import ReactionExprForm, ReactionScope
+from ._solver import Solver
+
+
+_Key = Union[int, str]
+
+
+class ReactionHydVar(NamedTuple):
+    name: str
+    description: str
+
+
+class ReactionFunction(NamedTuple):
+    name: str
+    arity: int
+
+
+class ReactionInitialEntry(NamedTuple):
+    is_link: bool
+    elem_index: int
+    species_index: int
+    value: float
+
+
+class ExpressionDiagnostic(NamedTuple):
+    valid: bool
+    message: str
+    column: int
+
+
+class ReactionSpecies:
+    def __init__(self, solver: Solver, index: int) -> None: ...
+
+    index: int
+    name: str
+    is_wall: bool
+    units: str
+    atol: float
+    rtol: float
+    initial: float
+    pipe_expression: Tuple[ReactionExprForm, str]
+    tank_expression: Tuple[ReactionExprForm, str]
+
+    def get_expression(self, scope: ReactionScope) -> Tuple[ReactionExprForm, str]: ...
+    def set_expression(
+        self, scope: ReactionScope, form: ReactionExprForm, expression: str = ...,
+    ) -> None: ...
+
+
+class ReactionCoefficient:
+    def __init__(self, solver: Solver, index: int) -> None: ...
+
+    index: int
+    name: str
+    is_param: bool
+    value: float
+
+
+class ReactionTerm:
+    def __init__(self, solver: Solver, index: int) -> None: ...
+
+    index: int
+    name: str
+    expression: str
+
+
+class _SpeciesCollection:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[ReactionSpecies]: ...
+    def __getitem__(self, key: _Key) -> ReactionSpecies: ...
+    def __contains__(self, key: object) -> bool: ...
+    def get_index(self, key: _Key) -> int: ...
+    def add(
+        self, name: str, *, wall: bool = ..., units: str = ...,
+        atol: float = ..., rtol: float = ...,
+    ) -> ReactionSpecies: ...
+    def remove(self, key: _Key) -> None: ...
+
+
+class _CoefficientCollection:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[ReactionCoefficient]: ...
+    def __getitem__(self, key: _Key) -> ReactionCoefficient: ...
+    def __contains__(self, key: object) -> bool: ...
+    def get_index(self, key: _Key) -> int: ...
+    def add(
+        self, name: str, *, parameter: bool = ..., value: float = ...,
+    ) -> ReactionCoefficient: ...
+    def remove(self, key: _Key) -> None: ...
+
+
+class _TermCollection:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[ReactionTerm]: ...
+    def __getitem__(self, key: _Key) -> ReactionTerm: ...
+    def __contains__(self, key: object) -> bool: ...
+    def get_index(self, key: _Key) -> int: ...
+    def add(self, name: str, expr: str) -> ReactionTerm: ...
+    def remove(self, key: _Key) -> None: ...
+
+
+class _InitialQualityRows:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[ReactionInitialEntry]: ...
+    def __getitem__(self, row: int) -> ReactionInitialEntry: ...
+    def set(
+        self, is_link: bool, elem_index: int, species: _Key, value: float,
+    ) -> None: ...
+    def remove(self, row: int) -> None: ...
+
+
+class Reactions:
+    def __init__(self, solver: Solver) -> None: ...
+
+    species: _SpeciesCollection
+    coefficients: _CoefficientCollection
+    terms: _TermCollection
+    initial: _InitialQualityRows
+
+    def validate(
+        self, expr: str, scope: ReactionScope = ...,
+    ) -> ExpressionDiagnostic: ...
+
+    def get_option(self, key: str) -> str: ...
+    def set_option(self, key: str, value: str) -> None: ...
+
+    def serialize(self) -> str: ...
+    def check_text(self, text: str) -> ExpressionDiagnostic: ...
+    def apply_text(self, text: str) -> None: ...
+    def save(self, path: Optional[str] = ...) -> None: ...
+
+    @staticmethod
+    def hydraulic_variables() -> Tuple[ReactionHydVar, ...]: ...
+    @staticmethod
+    def functions() -> Tuple[ReactionFunction, ...]: ...
diff --git a/python/openswmm/engine/_reactions.pyx b/python/openswmm/engine/_reactions.pyx
new file mode 100644
index 000000000..6c5c46055
--- /dev/null
+++ b/python/openswmm/engine/_reactions.pyx
@@ -0,0 +1,1106 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Reaction system (Pythonic v1 surface)
+=====================================
+
+:author: Caleb Buahin
+:copyright: Copyright (c) 2026 Caleb Buahin
+:license: Apache-2.0
+
+``solver.reactions`` exposes the ``[REACTION_*]`` / ``.rxn`` surface: the
+multi-species reaction vocabulary (species, coefficients, intermediate
+terms), the per-species PIPE/TANK expressions, initial quality, the
+``[REACTION_OPTIONS]`` tokens, and the whole-file text tab contract
+(``serialize`` / ``check_text`` / ``apply_text`` / ``save``).
+
+Two contracts govern everything here and are worth reading once:
+
+**Eager validation with rollback.** Every mutator recompiles the whole
+reaction system before it returns. A mutation that would leave *any*
+expression uncompilable is rolled back and refused with a
+:class:`~openswmm.engine.BadParamError` — the engine can never be left
+holding an uncompilable model. Removal of a species, coefficient, or term
+that is still referenced by a compiled expression is refused for the same
+reason. All of these mutations are ``BUILDING``/``OPENED`` only; reaction
+rows seed at simulation start, so they cannot be edited on a running model.
+
+**Byte-identical text round trip.** ``serialize() -> apply_text() ->
+serialize()`` is byte-identical, which is what makes a GUI text tab safe:
+the user's edits either apply whole or leave the previous system untouched
+(``apply_text`` is staged — on *any* error the previous reaction state and
+registry block are byte-identical to before the call).
+
+The discovery getters are the AUTHORITATIVE completer/highlighter
+vocabulary. A GUI or agent must *enumerate* species, coefficients, terms,
+hydraulic variables, and functions from here rather than hard-coding lists,
+so vocabulary drift is structural rather than disciplinary.
+:meth:`Reactions.hydraulic_variables` and :meth:`Reactions.functions` are
+engine-less statics — they need no open model, and they read the expression
+compiler's own tables, so there is exactly one copy of the truth.
+
+.. code-block:: python
+
+    from openswmm.engine import (
+        Solver, Reactions, ReactionScope, ReactionExprForm)
+
+    # Completer vocabulary — no model, no engine handle required.
+    for hv in Reactions.hydraulic_variables():
+        print(hv.name, "-", hv.description)
+    for fn in Reactions.functions():
+        print(fn.name, "arity", fn.arity)
+
+    s = Solver("model.inp")
+    s.open()                                  # BUILDING/OPENED: edits allowed
+
+    rxn = s.reactions
+    nh3 = rxn.species.add("NH3", units="MG", atol=1e-6, rtol=1e-6)
+    rxn.coefficients.add("Kb", value=0.05)
+    rxn.terms.add("Kf", "1.5826e-4 * RE^0.88 / D")
+
+    nh3.set_expression(ReactionScope.PIPE, ReactionExprForm.RATE, "-Kb * NH3")
+    nh3.initial = 0.5
+
+    diag = rxn.validate("-Kb * NH3", ReactionScope.PIPE)
+    if not diag.valid:
+        print(diag.message, "at column", diag.column)
+
+    text = rxn.serialize()
+    assert rxn.check_text(text).valid
+    rxn.apply_text(text)                      # byte-identical round trip
+    s.close()
+"""
+
+# cython: language_level=3
+
+from ._exceptions import ElementNotFoundError, raise_for_code
+from collections.abc import Iterator
+from typing import NamedTuple, Tuple
+
+from ._common cimport *
+from ._enums import ReactionExprForm, ReactionScope
+
+
+cdef inline SWMM_Engine _h(solver):
+    return solver.handle
+
+
+# =============================================================================
+# Flat snapshots (typing.NamedTuple — cheap, immutable, tuple-compatible)
+# =============================================================================
+
+class ReactionHydVar(NamedTuple):
+    """One built-in hydraulic variable usable inside a reaction expression.
+
+    :ivar name: Variable token as written in an expression (e.g. ``"RE"``).
+    :ivar description: Human-readable meaning, for tooltips/completers.
+    """
+
+    name: str
+    description: str
+
+
+class ReactionFunction(NamedTuple):
+    """One built-in math function usable inside a reaction expression.
+
+    :ivar name: Function token (e.g. ``"EXP"``, ``"POW"``).
+    :ivar arity: Number of arguments the function takes.
+    """
+
+    name: str
+    arity: int
+
+
+class ReactionInitialEntry(NamedTuple):
+    """One NODE/LINK initial-quality row.
+
+    :ivar is_link: ``True`` when ``elem_index`` addresses a link, ``False``
+        when it addresses a node.
+    :ivar elem_index: Zero-based node or link index.
+    :ivar species_index: Zero-based reaction-species index.
+    :ivar value: Initial concentration, in the species' own units.
+    """
+
+    is_link: bool
+    elem_index: int
+    species_index: int
+    value: float
+
+
+class ExpressionDiagnostic(NamedTuple):
+    """Result of a compile-only expression or whole-file check.
+
+    :ivar valid: ``True`` when the text compiles against this model.
+    :ivar message: Engine diagnostic; empty string when ``valid``.
+    :ivar column: 1-based error column, or ``-1`` when the failure is not
+        attributable to a column (and always ``-1`` for whole-file checks,
+        which report no column).
+    """
+
+    valid: bool
+    message: str
+    column: int
+
+
+# =============================================================================
+# Row readers — one fresh C call each, shared by the live views
+# =============================================================================
+
+def _species_row(solver, int idx):
+    """Read species *idx* as ``(name, is_wall, units, atol, rtol)``."""
+    cdef char name[128]
+    cdef char units[128]
+    cdef int is_wall = 0
+    cdef double atol = 0.0
+    cdef double rtol = 0.0
+    name[0] = 0
+    units[0] = 0
+    _check(swmm_reaction_species_get(
+        _h(solver), idx, name, 128, &is_wall, units, 128, &atol, &rtol))
+    return (name.decode('utf-8'), is_wall != 0, units.decode('utf-8'),
+            atol, rtol)
+
+
+def _coeff_row(solver, int idx):
+    """Read coefficient *idx* as ``(name, is_param, value)``."""
+    cdef char name[128]
+    cdef int is_param = 0
+    cdef double value = 0.0
+    name[0] = 0
+    _check(swmm_reaction_coeff_get(_h(solver), idx, name, 128, &is_param, &value))
+    return (name.decode('utf-8'), is_param != 0, value)
+
+
+def _term_row(solver, int idx):
+    """Read term *idx* as ``(name, expression)``."""
+    cdef char name[128]
+    cdef char expr[1024]
+    name[0] = 0
+    expr[0] = 0
+    _check(swmm_reaction_term_get(_h(solver), idx, name, 128, expr, 1024))
+    return (name.decode('utf-8'), expr.decode('utf-8'))
+
+
+def _species_count(solver) -> int:
+    return swmm_reaction_species_count(_h(solver))
+
+
+def _coeff_count(solver) -> int:
+    return swmm_reaction_coeff_count(_h(solver))
+
+
+def _term_count(solver) -> int:
+    return swmm_reaction_term_count(_h(solver))
+
+
+def _resolve_row(solver, key, count_fn, row_fn, str label) -> int:
+    """Resolve ``int | str`` *key* to a validated row index.
+
+    There is no ``swmm_reaction_*_index`` C helper, so a string key is
+    resolved by an **O(n) linear scan** over the collection, comparing the
+    name of each row exactly (case-sensitively). The collections are small
+    (tens of entries at most), so this is cheap in practice — but a caller
+    resolving the same name in a tight loop should hoist the index out.
+
+    :param key: Zero-based index (negatives count from the end) or exact name.
+    :returns: A validated index in ``[0, count)``.
+    :raises ElementNotFoundError: *key* is a string and no row has that name.
+    :raises IndexError: *key* is an out-of-range integer.
+    :raises TypeError: *key* is neither ``int`` nor ``str``.
+    """
+    cdef int n = count_fn(solver)
+    cdef int i
+    if isinstance(key, str):
+        for i in range(n):
+            if row_fn(solver, i)[0] == key:
+                return i
+        raise ElementNotFoundError(key, f"{label} '{key}' not found")
+    if not isinstance(key, int):
+        raise TypeError(
+            f"{label} key must be an int index or a str name, got "
+            f"{type(key).__name__}")
+    i = key
+    if i < 0:
+        i += n
+    if not (0 <= i < n):
+        raise IndexError(f"{label} index out of range: {key}")
+    return i
+
+
+# =============================================================================
+# Live row views — every property access is one fresh C call, no snapshots
+# =============================================================================
+
+class ReactionSpecies:
+    """One declared reaction species. Reach via ``solver.reactions.species[key]``.
+
+    This is a **live view** over ``(solver, index)``: every attribute read
+    issues a fresh C call, so the object never holds stale data. It does hold
+    a positional index, though — a structural mutation (species add/remove,
+    :meth:`Reactions.apply_text`) shifts indices, so re-look-up by name after
+    one rather than reusing an old view.
+    """
+
+    def __init__(self, solver, int index):
+        self._solver = solver
+        self._index = index
+
+    @property
+    def index(self) -> int:
+        """Zero-based position in ``[REACTION_SPECIES]``."""
+        return self._index
+
+    @property
+    def name(self) -> str:
+        """Species name as referenced from expressions."""
+        return _species_row(self._solver, self._index)[0]
+
+    @property
+    def is_wall(self) -> bool:
+        """``True`` for a WALL species, ``False`` for a BULK species."""
+        return _species_row(self._solver, self._index)[1]
+
+    @property
+    def units(self) -> str:
+        """Concentration units token (e.g. ``"MG"``, ``"UG"``, ``"#"``)."""
+        return _species_row(self._solver, self._index)[2]
+
+    @property
+    def atol(self) -> float:
+        """Absolute solver tolerance; ``0.0`` means "use the global ATOL"."""
+        return _species_row(self._solver, self._index)[3]
+
+    @property
+    def rtol(self) -> float:
+        """Relative solver tolerance; ``0.0`` means "use the global RTOL"."""
+        return _species_row(self._solver, self._index)[4]
+
+    # ------------------------------------------------------------------
+    # Expressions
+    # ------------------------------------------------------------------
+
+    def get_expression(self, scope) -> Tuple[object, str]:
+        """Return this species' expression in one scope.
+
+        :param scope: :class:`~openswmm.engine.ReactionScope` ``PIPE`` or
+            ``TANK`` (species expressions exist only in those two scopes).
+        :returns: ``(form, expression)`` where *form* is a
+            :class:`~openswmm.engine.ReactionExprForm`. ``form`` is ``NONE``
+            and ``expression`` is ``""`` when the species has no expression
+            in that scope.
+        :raises BadParamError: *scope* is not a species expression scope.
+        """
+        cdef int form = 0
+        cdef char expr[1024]
+        expr[0] = 0
+        _check(swmm_reaction_expr_get(
+            _h(self._solver), int(scope), self._index, &form, expr, 1024))
+        return (ReactionExprForm(form), expr.decode('utf-8'))
+
+    def set_expression(self, scope, form, str expression="") -> None:
+        """Set — or with ``ReactionExprForm.NONE`` clear — one scope's expression.
+
+        ``BUILDING``/``OPENED`` only. Validated eagerly: the whole reaction
+        system is recompiled before this returns, and if the new expression
+        (or anything it would invalidate) fails to compile the change is
+        rolled back and refused.
+
+        :param scope: :class:`~openswmm.engine.ReactionScope` ``PIPE`` or ``TANK``.
+        :param form: :class:`~openswmm.engine.ReactionExprForm` — ``RATE``
+            (``dC/dt = f(...)``), ``EQUIL`` (``0 = f(...)``), ``FORMULA``
+            (``C = f(...)``), or ``NONE`` to clear the scope.
+        :param expression: Expression text; ignored when *form* is ``NONE``.
+        :raises BadParamError: The expression does not compile (nothing changed).
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b = expression.encode('utf-8')
+        _check(swmm_reaction_expr_set(
+            _h(self._solver), int(scope), self._index, int(form), b))
+
+    @property
+    def pipe_expression(self) -> Tuple[object, str]:
+        """``(form, expression)`` for the conduit (flowing) scope."""
+        return self.get_expression(ReactionScope.PIPE)
+
+    @property
+    def tank_expression(self) -> Tuple[object, str]:
+        """``(form, expression)`` for the storage-unit (mixed) scope."""
+        return self.get_expression(ReactionScope.TANK)
+
+    # ------------------------------------------------------------------
+    # Global initial quality
+    # ------------------------------------------------------------------
+
+    @property
+    def initial(self) -> float:
+        """Model-wide initial concentration, in this species' own units.
+
+        Per-node / per-link overrides live in ``solver.reactions.initial``.
+        """
+        cdef double v = 0.0
+        _check(swmm_reaction_init_global_get(_h(self._solver), self._index, &v))
+        return v
+
+    @initial.setter
+    def initial(self, double value) -> None:
+        """Set the model-wide initial concentration (species units, ``>= 0``).
+
+        ``BUILDING``/``OPENED`` only.
+        """
+        _check(swmm_reaction_init_global_set(_h(self._solver), self._index, value))
+
+    def __repr__(self) -> str:
+        try:
+            name, is_wall, units, atol, rtol = _species_row(
+                self._solver, self._index)
+            kind = "WALL" if is_wall else "BULK"
+            return (f"")
+        except Exception:
+            return f""
+
+
+class ReactionCoefficient:
+    """One ``[REACTION_COEFFICIENTS]`` entry — a CONSTANT or a PARAMETER.
+
+    A **live view** over ``(solver, index)``; every read is a fresh C call.
+    """
+
+    def __init__(self, solver, int index):
+        self._solver = solver
+        self._index = index
+
+    @property
+    def index(self) -> int:
+        """Zero-based position in ``[REACTION_COEFFICIENTS]``."""
+        return self._index
+
+    @property
+    def name(self) -> str:
+        """Coefficient name as referenced from expressions."""
+        return _coeff_row(self._solver, self._index)[0]
+
+    @property
+    def is_param(self) -> bool:
+        """``True`` for a PARAMETER (pipe/tank-overridable), ``False`` for a
+        CONSTANT."""
+        return _coeff_row(self._solver, self._index)[1]
+
+    @property
+    def value(self) -> float:
+        """Current numeric value, in whatever units the expressions imply."""
+        return _coeff_row(self._solver, self._index)[2]
+
+    @value.setter
+    def value(self, double v) -> None:
+        """Change the coefficient's value.
+
+        ``BUILDING``/``OPENED`` only. Validated eagerly and rolled back if the
+        system stops compiling.
+        """
+        _check(swmm_reaction_coeff_set_value(_h(self._solver), self._index, v))
+
+    def __repr__(self) -> str:
+        try:
+            name, is_param, value = _coeff_row(self._solver, self._index)
+            kind = "PARAMETER" if is_param else "CONSTANT"
+            return (f"")
+        except Exception:
+            return f""
+
+
+class ReactionTerm:
+    """One ``[REACTION_TERMS]`` entry — a named intermediate expression.
+
+    A **live view** over ``(solver, index)``; every read is a fresh C call.
+
+    Terms are ordered, and a term may only reference terms declared *before*
+    it. That forward-only rule is enforced when a whole file is applied (where
+    ordinal position exists), not by :meth:`Reactions.validate` in
+    ``ReactionScope.TERM``.
+    """
+
+    def __init__(self, solver, int index):
+        self._solver = solver
+        self._index = index
+
+    @property
+    def index(self) -> int:
+        """Zero-based position in ``[REACTION_TERMS]`` — its ordering rank."""
+        return self._index
+
+    @property
+    def name(self) -> str:
+        """Term name as referenced from later terms and species expressions."""
+        return _term_row(self._solver, self._index)[0]
+
+    @property
+    def expression(self) -> str:
+        """The term's source expression text."""
+        return _term_row(self._solver, self._index)[1]
+
+    @expression.setter
+    def expression(self, str expr) -> None:
+        """Replace this term's expression.
+
+        ``BUILDING``/``OPENED`` only. Validated eagerly: if the replacement
+        breaks this term or anything downstream of it, the whole edit is
+        rolled back and refused.
+        """
+        cdef bytes b = expr.encode('utf-8')
+        _check(swmm_reaction_term_set_expr(_h(self._solver), self._index, b))
+
+    def __repr__(self) -> str:
+        try:
+            name, expr = _term_row(self._solver, self._index)
+            return (f"")
+        except Exception:
+            return f""
+
+
+# =============================================================================
+# Collections
+# =============================================================================
+
+class _SpeciesCollection:
+    """``solver.reactions.species`` — collection of :class:`ReactionSpecies`.
+
+    This is the authoritative species vocabulary for a completer; enumerate it
+    rather than hard-coding names.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return _species_count(self._solver)
+
+    def __iter__(self) -> Iterator[ReactionSpecies]:
+        cdef int n = _species_count(self._solver)
+        cdef int i
+        for i in range(n):
+            yield ReactionSpecies(self._solver, i)
+
+    def __getitem__(self, key) -> ReactionSpecies:
+        """Look a species up by zero-based index or by exact name.
+
+        A string key costs an **O(n) linear scan** (there is no C-side name
+        index for reaction species).
+
+        :raises ElementNotFoundError: No species has that name.
+        :raises IndexError: Integer key out of range.
+        """
+        return ReactionSpecies(self._solver, self.get_index(key))
+
+    def __contains__(self, key) -> bool:
+        try:
+            self.get_index(key)
+            return True
+        except (KeyError, IndexError, TypeError):
+            return False
+
+    def get_index(self, key) -> int:
+        """Resolve ``int | str`` *key* to a zero-based species index.
+
+        String lookup is an O(n) exact-name scan.
+        """
+        return _resolve_row(
+            self._solver, key, _species_count, _species_row, "Reaction species")
+
+    def add(self, str name, *, bint wall=False, str units="",
+            double atol=0.0, double rtol=0.0) -> ReactionSpecies:
+        """Declare a new species and return a live view of it.
+
+        ``BUILDING``/``OPENED`` only. The species registry's MSX block is
+        rebuilt in place and the whole system recompiled before this returns;
+        if anything stops compiling the addition is rolled back and refused.
+
+        :param name: Species name; becomes an expression identifier.
+        :param wall: ``True`` declares a WALL species, ``False`` a BULK species.
+        :param units: Concentration units token (e.g. ``"MG"``, ``"UG"``, ``"#"``).
+        :param atol: Absolute solver tolerance; ``0.0`` uses the global ATOL.
+        :param rtol: Relative solver tolerance; ``0.0`` uses the global RTOL.
+        :returns: A :class:`ReactionSpecies` view of the appended row.
+        :raises BadParamError: The declaration is rejected (nothing changed).
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b_name = name.encode('utf-8')
+        cdef bytes b_units = units.encode('utf-8')
+        _check(swmm_reaction_species_add(
+            _h(self._solver), b_name, 1 if wall else 0, b_units, atol, rtol))
+        self._solver._bump_generation()
+        return ReactionSpecies(self._solver, _species_count(self._solver) - 1)
+
+    def remove(self, key) -> None:
+        """Remove the species named or indexed by *key*.
+
+        ``BUILDING``/``OPENED`` only. **Refused while the species is still
+        referenced** by any compiled expression — remove or rewrite the
+        referring expressions first. All later species shift down by one.
+
+        :raises BadParamError: The species is still referenced (nothing changed).
+        :raises ElementNotFoundError: No species has that name.
+        """
+        cdef int idx = self.get_index(key)
+        _check(swmm_reaction_species_remove(_h(self._solver), idx))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+class _CoefficientCollection:
+    """``solver.reactions.coefficients`` — collection of
+    :class:`ReactionCoefficient`.
+
+    The authoritative coefficient vocabulary for a completer; enumerate it
+    rather than hard-coding names.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return _coeff_count(self._solver)
+
+    def __iter__(self) -> Iterator[ReactionCoefficient]:
+        cdef int n = _coeff_count(self._solver)
+        cdef int i
+        for i in range(n):
+            yield ReactionCoefficient(self._solver, i)
+
+    def __getitem__(self, key) -> ReactionCoefficient:
+        """Look a coefficient up by zero-based index or by exact name
+        (string keys cost an O(n) scan)."""
+        return ReactionCoefficient(self._solver, self.get_index(key))
+
+    def __contains__(self, key) -> bool:
+        try:
+            self.get_index(key)
+            return True
+        except (KeyError, IndexError, TypeError):
+            return False
+
+    def get_index(self, key) -> int:
+        """Resolve ``int | str`` *key* to a zero-based coefficient index
+        (string lookup is an O(n) exact-name scan)."""
+        return _resolve_row(
+            self._solver, key, _coeff_count, _coeff_row, "Reaction coefficient")
+
+    def add(self, str name, *, bint parameter=False,
+            double value=0.0) -> ReactionCoefficient:
+        """Add a coefficient and return a live view of it.
+
+        ``BUILDING``/``OPENED`` only, validated eagerly with rollback on any
+        compile failure.
+
+        :param name: Coefficient name; becomes an expression identifier.
+        :param parameter: ``True`` declares a PARAMETER (overridable per pipe
+            or tank), ``False`` a CONSTANT.
+        :param value: Initial numeric value.
+        :returns: A :class:`ReactionCoefficient` view of the appended row.
+        :raises BadParamError: The declaration is rejected (nothing changed).
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b = name.encode('utf-8')
+        _check(swmm_reaction_coeff_add(
+            _h(self._solver), b, 1 if parameter else 0, value))
+        self._solver._bump_generation()
+        return ReactionCoefficient(self._solver, _coeff_count(self._solver) - 1)
+
+    def remove(self, key) -> None:
+        """Remove the coefficient named or indexed by *key*.
+
+        ``BUILDING``/``OPENED`` only. **Refused while referenced** by any
+        compiled expression. All later coefficients shift down by one.
+
+        :raises BadParamError: The coefficient is still referenced.
+        :raises ElementNotFoundError: No coefficient has that name.
+        """
+        cdef int idx = self.get_index(key)
+        _check(swmm_reaction_coeff_remove(_h(self._solver), idx))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+class _TermCollection:
+    """``solver.reactions.terms`` — collection of :class:`ReactionTerm`.
+
+    Terms are **ordered**: a term may reference only terms declared before it.
+    :meth:`add` appends, so a new term can reference every existing one.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return _term_count(self._solver)
+
+    def __iter__(self) -> Iterator[ReactionTerm]:
+        cdef int n = _term_count(self._solver)
+        cdef int i
+        for i in range(n):
+            yield ReactionTerm(self._solver, i)
+
+    def __getitem__(self, key) -> ReactionTerm:
+        """Look a term up by zero-based index or by exact name (string keys
+        cost an O(n) scan)."""
+        return ReactionTerm(self._solver, self.get_index(key))
+
+    def __contains__(self, key) -> bool:
+        try:
+            self.get_index(key)
+            return True
+        except (KeyError, IndexError, TypeError):
+            return False
+
+    def get_index(self, key) -> int:
+        """Resolve ``int | str`` *key* to a zero-based term index (string
+        lookup is an O(n) exact-name scan)."""
+        return _resolve_row(
+            self._solver, key, _term_count, _term_row, "Reaction term")
+
+    def add(self, str name, str expr) -> ReactionTerm:
+        """Append an intermediate term and return a live view of it.
+
+        ``BUILDING``/``OPENED`` only. Validated eagerly with rollback: an
+        expression that does not compile against the current vocabulary is
+        refused and nothing is added. Because the term is appended last, it
+        may reference every term already declared — but nothing declared
+        after it.
+
+        :param name: Term name; becomes an expression identifier.
+        :param expr: The term's expression text.
+        :returns: A :class:`ReactionTerm` view of the appended row.
+        :raises BadParamError: The expression does not compile.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b_name = name.encode('utf-8')
+        cdef bytes b_expr = expr.encode('utf-8')
+        _check(swmm_reaction_term_add(_h(self._solver), b_name, b_expr))
+        self._solver._bump_generation()
+        return ReactionTerm(self._solver, _term_count(self._solver) - 1)
+
+    def remove(self, key) -> None:
+        """Remove the term named or indexed by *key*.
+
+        ``BUILDING``/``OPENED`` only. **Refused while referenced** by any
+        later term or species expression. All later terms shift down by one.
+
+        :raises BadParamError: The term is still referenced.
+        :raises ElementNotFoundError: No term has that name.
+        """
+        cdef int idx = self.get_index(key)
+        _check(swmm_reaction_term_remove(_h(self._solver), idx))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+class _InitialQualityRows:
+    """``solver.reactions.initial`` — the per-node / per-link initial-quality
+    rows.
+
+    Rows are flat :class:`ReactionInitialEntry` **snapshots**, not live views:
+    a row carries no identity beyond its ``(is_link, elem_index,
+    species_index)`` key, so there is nothing to keep live. Model-wide
+    defaults live on :attr:`ReactionSpecies.initial` instead.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        return swmm_reaction_init_elem_count(_h(self._solver))
+
+    def __iter__(self) -> Iterator[ReactionInitialEntry]:
+        cdef int n = swmm_reaction_init_elem_count(_h(self._solver))
+        cdef int i
+        for i in range(n):
+            yield self[i]
+
+    def __getitem__(self, int row) -> ReactionInitialEntry:
+        """Return row *row* as a :class:`ReactionInitialEntry` snapshot.
+
+        :param row: Zero-based row index (negatives count from the end).
+        :raises IndexError: *row* is out of range.
+        """
+        cdef int n = swmm_reaction_init_elem_count(_h(self._solver))
+        cdef int idx = row
+        cdef int is_link = 0
+        cdef int elem_idx = 0
+        cdef int species_idx = 0
+        cdef double value = 0.0
+        if idx < 0:
+            idx += n
+        if not (0 <= idx < n):
+            raise IndexError(f"Initial-quality row index out of range: {row}")
+        _check(swmm_reaction_init_elem_get(
+            _h(self._solver), idx, &is_link, &elem_idx, &species_idx, &value))
+        return ReactionInitialEntry(
+            is_link != 0, elem_idx, species_idx, value)
+
+    def set(self, bint is_link, int elem_index, species,
+            double value) -> None:
+        """Upsert the initial concentration for one element and species.
+
+        The row key is ``(is_link, elem_index, species_index)``: an existing
+        row with that key is updated in place, otherwise a new row is
+        appended. ``BUILDING``/``OPENED`` only.
+
+        :param is_link: ``True`` when *elem_index* addresses a link, ``False``
+            when it addresses a node.
+        :param elem_index: Zero-based node or link index.
+        :param species: Reaction species as an index or an exact name (a
+            string costs an O(n) scan).
+        :param value: Initial concentration in the species' units; must be
+            ``>= 0``.
+        :raises BadParamError: *value* is negative, or an index is invalid.
+        :raises ElementNotFoundError: No species has that name.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef int sp = _resolve_row(
+            self._solver, species, _species_count, _species_row,
+            "Reaction species")
+        _check(swmm_reaction_init_elem_set(
+            _h(self._solver), 1 if is_link else 0, elem_index, sp, value))
+
+    def remove(self, int row) -> None:
+        """Remove initial-quality row *row*; all later rows shift down by one.
+
+        ``BUILDING``/``OPENED`` only.
+
+        :param row: Zero-based row index (negatives count from the end).
+        :raises IndexError: *row* is out of range.
+        """
+        cdef int n = swmm_reaction_init_elem_count(_h(self._solver))
+        cdef int idx = row
+        if idx < 0:
+            idx += n
+        if not (0 <= idx < n):
+            raise IndexError(f"Initial-quality row index out of range: {row}")
+        _check(swmm_reaction_init_elem_remove(_h(self._solver), idx))
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# Reactions view
+# =============================================================================
+
+class Reactions:
+    """``solver.reactions`` — the ``[REACTION_*]`` / ``.rxn`` surface.
+
+    Groups the discovery/CRUD collections (:attr:`species`,
+    :attr:`coefficients`, :attr:`terms`, :attr:`initial`), the
+    ``[REACTION_OPTIONS]`` accessors, expression validation, and the
+    whole-file text contract. See the module docstring for the two invariants
+    (eager validation with rollback; byte-identical text round trip).
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+        self._species = None
+        self._coefficients = None
+        self._terms = None
+        self._initial = None
+
+    @property
+    def species(self) -> _SpeciesCollection:
+        """The declared species — authoritative completer vocabulary."""
+        if self._species is None:
+            self._species = _SpeciesCollection(self._solver)
+        return self._species
+
+    @property
+    def coefficients(self) -> _CoefficientCollection:
+        """The ``[REACTION_COEFFICIENTS]`` entries."""
+        if self._coefficients is None:
+            self._coefficients = _CoefficientCollection(self._solver)
+        return self._coefficients
+
+    @property
+    def terms(self) -> _TermCollection:
+        """The ordered ``[REACTION_TERMS]`` entries."""
+        if self._terms is None:
+            self._terms = _TermCollection(self._solver)
+        return self._terms
+
+    @property
+    def initial(self) -> _InitialQualityRows:
+        """The per-node / per-link initial-quality rows."""
+        if self._initial is None:
+            self._initial = _InitialQualityRows(self._solver)
+        return self._initial
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def validate(self, str expr, scope=ReactionScope.PIPE) -> ExpressionDiagnostic:
+        """Compile-only check of one expression. **Never changes state.**
+
+        The expression is compiled against this model's live vocabulary —
+        species, coefficients, terms, pollutants, and the built-in hydraulic
+        variables — so a GUI can validate as the user types.
+
+        *scope* selects the identifier-resolution vocabulary. Note the
+        deliberate caveat for ``ReactionScope.TERM``: references to **all**
+        terms are accepted there, including ones declared later. The
+        forward-only term-ordering rule is enforced at file-apply time, where
+        ordinal position exists; ``validate`` answers "is this well-formed
+        against the vocabulary", not "is the file orderable".
+
+        :param expr: Expression text.
+        :param scope: :class:`~openswmm.engine.ReactionScope`; defaults to
+            ``PIPE``.
+        :returns: An :class:`ExpressionDiagnostic` — ``valid`` True with an
+            empty message on success; otherwise the engine diagnostic and a
+            1-based ``column`` (``-1`` when not attributable).
+        """
+        cdef bytes b = expr.encode('utf-8')
+        cdef char errbuf[512]
+        cdef int col = -1
+        cdef int rc
+        errbuf[0] = 0
+        rc = swmm_reaction_validate_expression(
+            _h(self._solver), int(scope), b, errbuf, 512, &col)
+        if rc == 0:
+            return ExpressionDiagnostic(True, "", -1)
+        return ExpressionDiagnostic(False, errbuf.decode('utf-8'), col)
+
+    # ------------------------------------------------------------------
+    # Options
+    # ------------------------------------------------------------------
+
+    def get_option(self, str key) -> str:
+        """Read one ``[REACTION_OPTIONS]`` value as its canonical token.
+
+        Options are exposed as an explicit ``get_option`` / ``set_option``
+        pair rather than a mapping view: the key set is fixed by the engine
+        and every value is a token string, so a dict view would only add
+        indirection.
+
+        :param key: One of ``SOLVER``, ``COUPLING``, ``RATE_UNITS``,
+            ``AREA_UNITS``, ``TIMESTEP``, ``ATOL``, ``RTOL``, ``TEMPERATURE``.
+        :returns: The canonical token (numeric options come back as text —
+            ``TIMESTEP`` in seconds, ``ATOL``/``RTOL`` dimensionless).
+        :raises BadParamError: *key* is not a recognised option.
+        """
+        cdef bytes b = key.encode('utf-8')
+        cdef char buf[128]
+        buf[0] = 0
+        _check(swmm_reaction_option_get(_h(self._solver), b, buf, 128))
+        return buf.decode('utf-8')
+
+    def set_option(self, str key, str value) -> None:
+        """Set one ``[REACTION_OPTIONS]`` value from its canonical token.
+
+        ``BUILDING``/``OPENED`` only, validated eagerly with rollback.
+
+        :param key: One of ``SOLVER``, ``COUPLING``, ``RATE_UNITS``,
+            ``AREA_UNITS``, ``TIMESTEP``, ``ATOL``, ``RTOL``, ``TEMPERATURE``.
+        :param value: The canonical token; numeric options take their value
+            as text (``TIMESTEP`` in seconds, ``ATOL``/``RTOL`` dimensionless).
+        :raises BadParamError: *key* or *value* is not recognised.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b_key = key.encode('utf-8')
+        cdef bytes b_val = value.encode('utf-8')
+        _check(swmm_reaction_option_set(_h(self._solver), b_key, b_val))
+
+    # ------------------------------------------------------------------
+    # Whole-file text surface
+    # ------------------------------------------------------------------
+
+    def serialize(self) -> str:
+        """Return the canonical ``.rxn`` text for the current engine state.
+
+        This is the GUI text tab's read side, and it round-trips exactly:
+        ``serialize() -> apply_text() -> serialize()`` is byte-identical.
+
+        Implemented as the C API's two-pass size query — a first call with a
+        NULL buffer fills in the required length (including the NUL), then a
+        second call fills a buffer of exactly that size.
+
+        :returns: The canonical ``.rxn`` text; ``""`` when no reaction system
+            is configured.
+        """
+        cdef SWMM_Engine h = _h(self._solver)
+        cdef int needed = 0
+        cdef int rc
+        cdef bytearray raw
+        cdef char* buf
+        rc = swmm_reactions_serialize(h, NULL, 0, &needed)
+        if needed <= 0:
+            # Surface a genuine engine failure; otherwise there is simply
+            # nothing to serialize.
+            _check(rc)
+            return ""
+        raw = bytearray(needed)
+        buf = raw
+        _check(swmm_reactions_serialize(h, buf, needed, &needed))
+        return buf.decode('utf-8')
+
+    def check_text(self, str text) -> ExpressionDiagnostic:
+        """Dry-run a whole ``.rxn`` file against this model. **Never mutates.**
+
+        A full parse and compile with zero state change on success *or*
+        failure — the safe "does this text apply?" probe behind a text tab's
+        live error gutter.
+
+        :param text: Complete ``.rxn`` file text.
+        :returns: An :class:`ExpressionDiagnostic`. ``column`` is always
+            ``-1``: the whole-file checker reports the first diagnostic as
+            text, without a column.
+        """
+        cdef bytes b = text.encode('utf-8')
+        cdef char errbuf[512]
+        cdef int rc
+        errbuf[0] = 0
+        rc = swmm_reactions_check_text(_h(self._solver), b, errbuf, 512)
+        if rc == 0:
+            return ExpressionDiagnostic(True, "", -1)
+        return ExpressionDiagnostic(False, errbuf.decode('utf-8'), -1)
+
+    def apply_text(self, str text) -> None:
+        """Transactionally replace the whole reaction system from ``.rxn`` text.
+
+        ``BUILDING``/``OPENED`` only. Staged: on **any** error the previous
+        system — reaction state *and* the registry block — is byte-identical
+        to what it was before the call, so a rejected edit costs nothing.
+        Unlike :meth:`check_text`, this mutates on success, and every wrapper
+        index (species, coefficients, terms, initial rows) is invalidated.
+
+        This is also where the forward-only term-ordering rule is enforced,
+        since ordinal position exists in a file.
+
+        :param text: Complete ``.rxn`` file text — typically an edited
+            :meth:`serialize` result.
+        :raises BadParamError: The text does not parse or compile; the
+            exception message is the engine's own first diagnostic and the
+            previous system is intact.
+        :raises LifecycleError: The engine is past ``OPENED``.
+        """
+        cdef bytes b = text.encode('utf-8')
+        cdef char errbuf[512]
+        cdef int rc
+        errbuf[0] = 0
+        rc = swmm_reactions_apply_text(_h(self._solver), b, errbuf, 512)
+        if rc != 0:
+            raise_for_code(rc, errbuf.decode('utf-8'))
+        self._solver._bump_generation()
+
+    def save(self, path=None) -> None:
+        """Serialize the reaction system to a ``.rxn`` file on disk.
+
+        :param path: Destination path. When ``None`` (the default) the file
+            is written to the path bound to the reaction component's config
+            entry.
+        :raises BadParamError: *path* is ``None`` and no component config
+            path is bound, so there is nowhere to write.
+        """
+        cdef bytes b
+        if path is None:
+            _check(swmm_reactions_save(_h(self._solver), NULL))
+        else:
+            b = str(path).encode('utf-8')
+            _check(swmm_reactions_save(_h(self._solver), b))
+
+    # ------------------------------------------------------------------
+    # Static vocabulary — no engine handle, no open model
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def hydraulic_variables() -> Tuple[ReactionHydVar, ...]:
+        """Return every built-in hydraulic variable usable in an expression.
+
+        **Engine-less static.** This needs no open model and no ``Solver`` —
+        call it on the class (``Reactions.hydraulic_variables()``) at any
+        time, including before a model is loaded, to populate a completer or
+        a syntax highlighter.
+
+        It reads the expression compiler's own tables, so it is the
+        AUTHORITATIVE vocabulary: a GUI or agent must enumerate it rather
+        than hard-coding a list, which is what keeps vocabulary drift
+        structural instead of a matter of discipline.
+
+        :returns: A tuple of :class:`ReactionHydVar` — the variables
+            ``D Q U RE US FF AV HRT DT`` and any the engine adds later.
+        """
+        cdef int n = swmm_reaction_hydvar_count()
+        cdef int i
+        cdef char name[128]
+        cdef char desc[256]
+        out = []
+        for i in range(n):
+            name[0] = 0
+            desc[0] = 0
+            _check(swmm_reaction_hydvar_get(i, name, 128, desc, 256))
+            out.append(ReactionHydVar(
+                name.decode('utf-8'), desc.decode('utf-8')))
+        return tuple(out)
+
+    @staticmethod
+    def functions() -> Tuple[ReactionFunction, ...]:
+        """Return every built-in math function usable in an expression.
+
+        **Engine-less static**, exactly like
+        :meth:`hydraulic_variables`: no open model, no ``Solver``, and it
+        reads the expression compiler's own tables — so it is the
+        AUTHORITATIVE function vocabulary. Enumerate it; do not hard-code.
+
+        :returns: A tuple of :class:`ReactionFunction` — ``EXP`` through
+            ``TAN`` with arity 1, and ``MIN``, ``MAX``, ``POW`` with arity 2.
+        """
+        cdef int n = swmm_reaction_function_count()
+        cdef int i
+        cdef int arity = 0
+        cdef char name[128]
+        out = []
+        for i in range(n):
+            name[0] = 0
+            arity = 0
+            _check(swmm_reaction_function_get(i, name, 128, &arity))
+            out.append(ReactionFunction(name.decode('utf-8'), arity))
+        return tuple(out)
+
+    def __repr__(self) -> str:
+        try:
+            return (f"")
+        except Exception:
+            return ""
diff --git a/python/openswmm/engine/_report.py b/python/openswmm/engine/_report.py
index 39bdf626d..bab1de72f 100644
--- a/python/openswmm/engine/_report.py
+++ b/python/openswmm/engine/_report.py
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Report Snapshot
 ===============
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Provides :func:`get_report_snapshot` — a single call that assembles the
 programmatic equivalent of the SWMM ``.rpt`` file into structured Python
@@ -15,8 +31,7 @@
     from openswmm.engine import Solver, get_report_snapshot
 
     with Solver("model.inp", "model.rpt", "model.out") as s:
-        s.start()
-        while s.step() == 0:
+        for _ in s.steps():
             pass
         s.end()
         report = get_report_snapshot(s)
@@ -98,6 +113,9 @@ class RunoffContinuity:
     initial_storage: float
     final_storage: float
 
+    initial_snow: float = 0.0
+    final_snow: float = 0.0
+
 
 @dataclass
 class RoutingContinuity:
@@ -120,6 +138,10 @@ class RoutingContinuity:
     initial_storage: float
     final_storage: float
 
+    forcing_inflow: float = 0.0
+    coupling_outflow: float = 0.0
+    link_groundwater_inflow: float = 0.0
+
 
 @dataclass
 class QualityContinuity:
@@ -275,7 +297,7 @@ def get_report_snapshot(solver: "Solver") -> ReportSnapshot:
 
         with Solver("model.inp", "model.rpt", "model.out") as s:
             s.start()
-            while s.step() == 0:
+            for _ in s.steps():
                 pass
             s.end()
             snap = get_report_snapshot(s)
@@ -303,39 +325,13 @@ def get_report_snapshot(solver: "Solver") -> ReportSnapshot:
     )
 
     # --- Routing diagnostics (convergence) ------------------------------------
-    raw_rs: Dict[str, Any] = {}
-    if hasattr(mb, "get_routing_stats"):
-        try:
-            raw_rs = mb.get_routing_stats() or {}
-        except Exception:
-            pass
-
-    n_steps = int(raw_rs.get("n_steps", 0))
-    pct_nc  = float(raw_rs.get("pct_non_converged", 0.0))
-
-    max_courant = 0.0
-    if hasattr(mb, "get_max_courant"):
-        try:
-            max_courant = mb.get_max_courant()
-        except Exception:
-            max_courant = float(raw_rs.get("max_courant", 0.0))
-    else:
-        max_courant = float(raw_rs.get("max_courant", 0.0))
-
-    routing_diag = RoutingDiagnostics(
-        avg_time_step=float(raw_rs.get("avg_step", 0.0)),
-        min_time_step=float(raw_rs.get("min_step", 0.0)),
-        max_time_step=float(raw_rs.get("max_step", 0.0)),
-        n_steps=n_steps,
-        pct_not_converged=pct_nc,
-        n_steps_not_converged=round(n_steps * pct_nc / 100.0),
-        avg_iterations=float(raw_rs.get("avg_iterations", 0.0)),
-        max_courant=max_courant,
-    )
+    # Use the current typed API. Probing retired get_* methods silently
+    # produced all-zero diagnostics even after a completed simulation.
+    routing_diag = mb.routing_diagnostics
 
     # --- Runoff continuity ----------------------------------------------------
     runoff_cont = RunoffContinuity(
-        continuity_error_pct=mb.runoff_continuity_error,
+        continuity_error_pct=100.0 * mb.runoff_continuity_error,
         total_rainfall=mb.runoff_total(RunoffTotal.RAINFALL),
         total_evaporation=mb.runoff_total(RunoffTotal.EVAP),
         total_infiltration=mb.runoff_total(RunoffTotal.INFIL),
@@ -343,11 +339,13 @@ def get_report_snapshot(solver: "Solver") -> ReportSnapshot:
         total_snow_removal=mb.runoff_total(RunoffTotal.SNOWREMOV),
         initial_storage=mb.runoff_total(RunoffTotal.INITSTORE),
         final_storage=mb.runoff_total(RunoffTotal.FINALSTORE),
+        initial_snow=mb.runoff_total(RunoffTotal.INITSNOW),
+        final_snow=mb.runoff_total(RunoffTotal.FINALSNOW),
     )
 
     # --- Routing continuity ---------------------------------------------------
     routing_cont = RoutingContinuity(
-        continuity_error_pct=mb.routing_continuity_error,
+        continuity_error_pct=100.0 * mb.routing_continuity_error,
         dry_weather_inflow=mb.routing_total(RoutingTotal.DRY_WEATHER),
         wet_weather_inflow=mb.routing_total(RoutingTotal.WET_WEATHER),
         groundwater_inflow=mb.routing_total(RoutingTotal.GW_INFLOW),
@@ -359,6 +357,9 @@ def get_report_snapshot(solver: "Solver") -> ReportSnapshot:
         seepage_loss=mb.routing_total(RoutingTotal.SEEP_LOSS),
         initial_storage=mb.routing_total(RoutingTotal.INIT_STORAGE),
         final_storage=mb.routing_total(RoutingTotal.FINAL_STORAGE),
+        forcing_inflow=mb.routing_total(RoutingTotal.FORCING_INFLOW),
+        coupling_outflow=mb.routing_total(RoutingTotal.COUPLING_OUT),
+        link_groundwater_inflow=mb.routing_total(RoutingTotal.LINK_GW_INFLOW),
     )
 
     # --- Quality continuity (per pollutant) -----------------------------------
@@ -374,7 +375,7 @@ def get_report_snapshot(solver: "Solver") -> ReportSnapshot:
             evap = 0.0
         quality_cont.append(QualityContinuity(
             pollutant_id=polls.get_id(i),
-            continuity_error_pct=mb.quality_continuity_error(i),
+            continuity_error_pct=100.0 * mb.quality_continuity_error(i),
             seep_loss=seep,
             evap_loss=evap,
         ))
diff --git a/python/openswmm/engine/_solver.pxd b/python/openswmm/engine/_solver.pxd
index c407738f6..adb6e8571 100644
--- a/python/openswmm/engine/_solver.pxd
+++ b/python/openswmm/engine/_solver.pxd
@@ -1,6 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # :author: Caleb Buahin
 # :copyright: Copyright (c) 2026 Caleb Buahin
-# :license: MIT
+# :license: Apache-2.0
 #
 # _solver.pxd -- Expose Solver cdef class for cimport by _model and _hotstart.
 # cython: language_level=3
@@ -8,6 +24,8 @@
 from ._common cimport SWMM_Engine
 
 cdef class Solver:
+    cdef object __weakref__
+    cdef object _access
     cdef SWMM_Engine _handle
     cdef str _inp, _rpt, _out
     cdef object _plugin_lib  # str or None
@@ -39,6 +57,11 @@ cdef class Solver:
     cdef object _infrastructure
     cdef object _spatial
     cdef object _quality
+    cdef object _initial_quality
+    cdef object _reactions
+    cdef object _heat
+    cdef object _water_age
+    cdef object _process_components
     cdef object _statistics
     cdef object _mass_balance
     cdef object _editor
diff --git a/python/openswmm/engine/_solver.pyi b/python/openswmm/engine/_solver.pyi
index 973ef79d3..94b7f61da 100644
--- a/python/openswmm/engine/_solver.pyi
+++ b/python/openswmm/engine/_solver.pyi
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Engine Lifecycle (Pythonic v1 surface)
 ======================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._solver`.
 """
@@ -25,15 +41,20 @@ if TYPE_CHECKING:
     from ._edit import ModelEditor
     from ._forcing import Forcing
     from ._gages import Gages
+    from ._heat import Heat
     from ._hotstart import SaveSchedule
     from ._infrastructure import Infrastructure
     from ._inflows import Inflows
+    from ._initial_quality import InitialQuality
     from ._links import Links
     from ._massbalance import MassBalance
     from ._nodes import Nodes
     from ._pollutants import Pollutants
+    from ._process_components import ProcessComponents
     from ._quality import Quality
+    from ._reactions import Reactions
     from ._spatial import Spatial
+    from ._water_age import WaterAge
     from ._statistics import Statistics
     from ._subcatchments import Aquifers, Snowpacks, Subcatchments
     from ._tables import Patterns, Tables
@@ -201,6 +222,9 @@ def run_with_callback(
 # ---------------------------------------------------------------------------
 
 
+from ._transport import Transport, ThreadInfo, EffectiveThreads, TransportCell
+from ._enums import TransportDomain, TransportClass, InpProfile
+
 class Solver:
     """SWMM engine lifecycle manager.
 
@@ -216,6 +240,17 @@ class Solver:
                 if elapsed >= timedelta(hours=24):
                     break
     """
+    def write_staged(self, final_path: _PathLike, mapper: Callable[[str, int], _PathLike | None]) -> None: ...
+    def write_compat(self, path: _PathLike, profile: InpProfile) -> None: ...
+
+    @property
+    def thread_info(self) -> ThreadInfo: ...
+    def effective_threads(self, requested: int = ...) -> EffectiveThreads: ...
+    @property
+    def transport_matrix(self) -> dict[TransportDomain, dict[TransportClass, TransportCell]]: ...
+    @property
+    def transport(self) -> Transport: ...
+
 
     def __init__(
         self,
@@ -364,6 +399,16 @@ class Solver:
     @property
     def quality(self) -> "Quality": ...
     @property
+    def initial_quality(self) -> "InitialQuality": ...
+    @property
+    def reactions(self) -> "Reactions": ...
+    @property
+    def heat(self) -> "Heat": ...
+    @property
+    def water_age(self) -> "WaterAge": ...
+    @property
+    def process_components(self) -> "ProcessComponents": ...
+    @property
     def statistics(self) -> "Statistics": ...
     @property
     def mass_balance(self) -> "MassBalance": ...
diff --git a/python/openswmm/engine/_solver.pyx b/python/openswmm/engine/_solver.pyx
index 20ddff0a6..a7b1433be 100644
--- a/python/openswmm/engine/_solver.pyx
+++ b/python/openswmm/engine/_solver.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Engine lifecycle (Pythonic v1 surface)
 ======================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Solver` class is the entry point for running, inspecting, and
 editing a SWMM model from Python.
@@ -135,6 +151,8 @@ cdef void _warning_trampoline(SWMM_Engine engine, int code, const char* msg,
 # Solver
 # =============================================================================
 
+from ._access import NativeAccess, Callback, register_owner
+
 cdef class Solver:
     """SWMM engine lifecycle and entry point to every domain accessor.
 
@@ -161,7 +179,7 @@ cdef class Solver:
 
     On entry the solver runs ``open → initialize → start``; on exit it runs
     ``end → report → close → destroy``. Any non-zero return from the C API
-    raises an :class:`EngineError` subclass (see :doc:`error_handling`).
+    raises an :class:`EngineError` subclass (see :doc:`/guide/error_handling`).
     """
 
     def __init__(self,
@@ -170,6 +188,7 @@ cdef class Solver:
                  out=None,
                  *,
                  plugin_lib: Optional[Union[str, "os.PathLike"]] = None):
+        self._access = NativeAccess()
         self._inp = _path_to_str(inp)
         self._rpt = _path_to_str(rpt)
         self._out = _path_to_str(out)
@@ -198,6 +217,11 @@ cdef class Solver:
         self._infrastructure = None
         self._spatial = None
         self._quality = None
+        self._initial_quality = None
+        self._reactions = None
+        self._heat = None
+        self._water_age = None
+        self._process_components = None
         self._statistics = None
         self._mass_balance = None
         self._editor = None
@@ -224,6 +248,7 @@ cdef class Solver:
     def create(self) -> None:
         """Allocate the engine handle. Usually called implicitly by
         :meth:`open` or the context manager."""
+        self._access.require_idle()
         if self._handle != NULL:
             return
         self._handle = swmm_engine_create()
@@ -247,7 +272,7 @@ cdef class Solver:
         """
         if self._handle == NULL:
             self.create()
-        swmm_engine_set_lenient_open(self._handle, 1 if on else 0)
+        swmm_engine_set_lenient_open(self.handle, 1 if on else 0)
 
     def open(self,
              plugin_lib: Optional[Union[str, "os.PathLike"]] = None) -> None:
@@ -257,6 +282,7 @@ cdef class Solver:
             :meth:`__init__`. Pass ``None`` to use the constructor value.
         :raises EngineError: On C API failure (specific subclass per code).
         """
+        self._access.require_idle()
         if self._handle == NULL:
             self.create()
         cdef bytes b_inp = self._inp.encode('utf-8')
@@ -270,11 +296,20 @@ cdef class Solver:
         if resolved_plugin:
             b_plugin = resolved_plugin.encode('utf-8')
             c_plugin = b_plugin
-        _check(swmm_engine_open(self._handle, b_inp, b_rpt, b_out, c_plugin))
+        with self._operation():
+            rc = swmm_engine_open(self.handle, b_inp, b_rpt, b_out, c_plugin)
+        self._generation += 1
+        self._surface2d = None
+        self._access.raise_callback_error()
+        _check(rc)
 
     def initialize(self) -> None:
         """Initialize the simulation; transition to ``INITIALIZED``."""
-        _check(swmm_engine_initialize(self._handle))
+        self._access.require_idle()
+        with self._operation():
+            rc = swmm_engine_initialize(self.handle)
+        self._access.raise_callback_error()
+        _check(rc)
 
     def start(self, bint save_results=True) -> None:
         """Start the simulation; transition to ``STARTED``.
@@ -282,7 +317,11 @@ cdef class Solver:
         :param save_results: If ``True``, write binary output to the
             ``.out`` file. When ``False`` the file is not produced.
         """
-        _check(swmm_engine_start(self._handle, 1 if save_results else 0))
+        self._access.require_idle()
+        with self._operation():
+            rc = swmm_engine_start(self.handle, 1 if save_results else 0)
+        self._access.raise_callback_error()
+        _check(rc)
 
     def step(self) -> timedelta:
         """Advance one routing step.
@@ -292,13 +331,16 @@ cdef class Solver:
             has ended — callers should break out of their loop.
         :raises EngineError: On any non-zero C API return.
         """
+        self._access.require_idle()
         cdef double elapsed = 0.0
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef int rc
-        with nogil:
-            rc = swmm_engine_step(h, &elapsed)
-        _check(rc)
+        with self._operation(h):
+            with nogil:
+                rc = swmm_engine_step(h, &elapsed)
         self._elapsed = elapsed
+        self._access.raise_callback_error()
+        _check(rc)
         return _days_to_td(elapsed)
 
     def stride(self, int n_steps) -> timedelta:
@@ -308,34 +350,54 @@ cdef class Solver:
             :class:`timedelta`. ``timedelta(0)`` once the simulation has
             ended.
         """
+        self._access.require_idle()
         cdef double elapsed = 0.0
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef int rc
-        with nogil:
-            rc = swmm_engine_stride(h, n_steps, &elapsed)
-        _check(rc)
+        with self._operation(h):
+            with nogil:
+                rc = swmm_engine_stride(h, n_steps, &elapsed)
         self._elapsed = elapsed
+        self._access.raise_callback_error()
+        _check(rc)
         return _days_to_td(elapsed)
 
     def end(self) -> None:
         """End the simulation; transition to ``ENDED``."""
-        _check(swmm_engine_end(self._handle))
+        self._access.require_idle()
+        with self._operation():
+            rc = swmm_engine_end(self.handle)
+        self._access.raise_callback_error()
+        _check(rc)
 
     def report(self) -> None:
         """Write the summary report to the ``.rpt`` file."""
-        _check(swmm_engine_report(self._handle))
+        self._access.require_idle()
+        with self._operation():
+            rc = swmm_engine_report(self.handle)
+        self._access.raise_callback_error()
+        _check(rc)
 
     def close(self) -> None:
         """Close all files; transition to ``CLOSED``. Idempotent."""
+        self._access.require_idle()
         if self._handle == NULL:
             return
-        _check(swmm_engine_close(self._handle))
+        with self._operation():
+            rc = swmm_engine_close(self.handle)
+        self._access.raise_callback_error()
+        _check(rc)
+        self._generation += 1
+        self._surface2d = None
 
     def destroy(self) -> None:
         """Destroy the engine handle. Idempotent."""
+        self._access.require_idle()
         if self._handle != NULL:
-            swmm_engine_destroy(self._handle)
+            swmm_engine_destroy(self.handle)
             self._handle = NULL
+            self._generation += 1
+            self._surface2d = None
 
     # ------------------------------------------------------------------
     # Iteration helpers
@@ -358,17 +420,11 @@ cdef class Solver:
 
         :raises EngineError: Propagated from :meth:`step`.
         """
-        cdef double elapsed = 0.0
-        cdef SWMM_Engine h = self._handle
-        cdef int rc
         while True:
-            with nogil:
-                rc = swmm_engine_step(h, &elapsed)
-            _check(rc)
-            self._elapsed = elapsed
-            if elapsed <= 0.0:
+            elapsed = self.step()
+            if not elapsed:
                 return
-            yield _days_to_td(elapsed)
+            yield elapsed
 
     def until(self, target) -> timedelta:
         """Stride forward until the engine reaches ``target``.
@@ -408,19 +464,10 @@ cdef class Solver:
         if target_days <= self._elapsed:
             return _days_to_td(self._elapsed)
 
-        cdef double elapsed = self._elapsed
-        cdef SWMM_Engine h = self._handle
-        cdef int rc
-        while elapsed > 0.0 or self._elapsed == 0.0:
-            with nogil:
-                rc = swmm_engine_step(h, &elapsed)
-            _check(rc)
-            self._elapsed = elapsed
-            if elapsed <= 0.0:                        # simulation ended
-                break
-            if elapsed >= target_days:                # reached the target
-                break
-        return _days_to_td(self._elapsed)
+        while True:
+            elapsed = self.step()
+            if not elapsed or self._elapsed >= target_days:
+                return elapsed
 
     # ------------------------------------------------------------------
     # Convenience: run-to-completion
@@ -470,7 +517,7 @@ cdef class Solver:
     def state(self) -> EngineState:
         """Current lifecycle state as an :class:`EngineState` enum."""
         cdef int s = 0
-        _check(swmm_engine_get_state(self._handle, &s))
+        _check(swmm_engine_get_state(self.handle, &s))
         return EngineState(s)
 
     @property
@@ -480,7 +527,8 @@ cdef class Solver:
         Provided for advanced interop (e.g. passing the handle to other
         Cython modules). The Python-level surface should never need it.
         """
-        return self._handle
+        self._access.check()
+        return register_owner(self, self._handle)
 
     @property
     def open_errors(self) -> list:
@@ -492,12 +540,12 @@ cdef class Solver:
 
         :rtype: list[str]
         """
-        cdef int n = swmm_get_error_count(self._handle)
+        cdef int n = swmm_get_error_count(self.handle)
         cdef int i
         cdef const char* msg
         cdef list out = []
         for i in range(n):
-            msg = swmm_get_error_at(self._handle, i)
+            msg = swmm_get_error_at(self.handle, i)
             out.append(msg.decode('utf-8') if msg != NULL else "")
         return out
 
@@ -509,12 +557,12 @@ cdef class Solver:
 
         :rtype: list[str]
         """
-        cdef int n = swmm_get_warning_count(self._handle)
+        cdef int n = swmm_get_warning_count(self.handle)
         cdef int i
         cdef const char* msg
         cdef list out = []
         for i in range(n):
-            msg = swmm_get_warning_at(self._handle, i)
+            msg = swmm_get_warning_at(self.handle, i)
             out.append(msg.decode('utf-8') if msg != NULL else "")
         return out
 
@@ -525,6 +573,10 @@ cdef class Solver:
         staleness."""
         return int(self._generation)
 
+    def _operation(self, expected=0):
+        """Internal nonblocking guard for native calls that release the GIL."""
+        return self._access.operation(self, expected)
+
     def _bump_generation(self) -> None:
         """Increment the staleness counter. Called by collection-level
         editors (``solver.nodes.add``, ``rename``, ``delete``, …) so
@@ -536,7 +588,7 @@ cdef class Solver:
     def routing_step(self) -> timedelta:
         """Routing timestep as a :class:`timedelta`."""
         cdef double v = 0.0
-        _check(swmm_get_routing_step(self._handle, &v))
+        _check(swmm_get_routing_step(self.handle, &v))
         return timedelta(seconds=v)
 
     # ------------------------------------------------------------------
@@ -547,34 +599,34 @@ cdef class Solver:
     def start_datetime(self) -> datetime:
         """Simulation start :class:`datetime.datetime`."""
         cdef double v = 0.0
-        _check(swmm_options_get_start_date(self._handle, &v))
+        _check(swmm_options_get_start_date(self.handle, &v))
         return oadate_to_datetime(v)
 
     @start_datetime.setter
     def start_datetime(self, value: datetime) -> None:
-        _check(swmm_options_set_start_date(self._handle, datetime_to_oadate(value)))
+        _check(swmm_options_set_start_date(self.handle, datetime_to_oadate(value)))
 
     @property
     def end_datetime(self) -> datetime:
         """Simulation end :class:`datetime.datetime`."""
         cdef double v = 0.0
-        _check(swmm_options_get_end_date(self._handle, &v))
+        _check(swmm_options_get_end_date(self.handle, &v))
         return oadate_to_datetime(v)
 
     @end_datetime.setter
     def end_datetime(self, value: datetime) -> None:
-        _check(swmm_options_set_end_date(self._handle, datetime_to_oadate(value)))
+        _check(swmm_options_set_end_date(self.handle, datetime_to_oadate(value)))
 
     @property
     def report_start_datetime(self) -> datetime:
         """Report start :class:`datetime.datetime`."""
         cdef double v = 0.0
-        _check(swmm_options_get_report_start(self._handle, &v))
+        _check(swmm_options_get_report_start(self.handle, &v))
         return oadate_to_datetime(v)
 
     @report_start_datetime.setter
     def report_start_datetime(self, value: datetime) -> None:
-        _check(swmm_options_set_report_start(self._handle, datetime_to_oadate(value)))
+        _check(swmm_options_set_report_start(self.handle, datetime_to_oadate(value)))
 
     @property
     def current_datetime(self) -> datetime:
@@ -599,7 +651,7 @@ cdef class Solver:
         :attr:`start_datetime` option.
         """
         cdef double v = 0.0
-        _check(swmm_get_start_time(self._handle, &v))
+        _check(swmm_get_start_time(self.handle, &v))
         return oadate_to_datetime(v)
 
     @property
@@ -610,7 +662,7 @@ cdef class Solver:
         ``swmm_get_end_time``).
         """
         cdef double v = 0.0
-        _check(swmm_get_end_time(self._handle, &v))
+        _check(swmm_get_end_time(self.handle, &v))
         return oadate_to_datetime(v)
 
     @property
@@ -620,7 +672,7 @@ cdef class Solver:
         @rtype: int
         """
         cdef int v = 0
-        _check(swmm_get_event_count(self._handle, &v))
+        _check(swmm_get_event_count(self.handle, &v))
         return v
 
     # ------------------------------------------------------------------
@@ -631,7 +683,7 @@ cdef class Solver:
     def crs(self) -> str:
         """Coordinate reference system string from ``[OPTIONS]``."""
         cdef char buf[256]
-        _check(swmm_get_crs(self._handle, buf, 256))
+        _check(swmm_get_crs(self.handle, buf, 256))
         return buf.decode('utf-8')
 
     # ------------------------------------------------------------------
@@ -641,29 +693,69 @@ cdef class Solver:
     @property
     def steady_state_skip(self) -> bool:
         cdef int v = 0
-        _check(swmm_get_steady_state_skip(self._handle, &v))
+        _check(swmm_get_steady_state_skip(self.handle, &v))
         return v != 0
 
     @steady_state_skip.setter
     def steady_state_skip(self, value: bool) -> None:
-        _check(swmm_set_steady_state_skip(self._handle, 1 if value else 0))
+        _check(swmm_set_steady_state_skip(self.handle, 1 if value else 0))
 
     @property
     def is_between_events(self) -> bool:
         """``True`` when the current routing time falls outside any
         ``[EVENTS]`` window (i.e. routing is being skipped)."""
         cdef int v = 0
-        _check(swmm_is_between_events(self._handle, &v))
+        _check(swmm_is_between_events(self.handle, &v))
         return v != 0
 
     # ------------------------------------------------------------------
     # Model write
     # ------------------------------------------------------------------
 
+    def write_staged(self, final_path, mapper):
+        """Serialize each physical output to mapper(final_path, kind).
+
+        kind is 0=model, 1=mesh, 2=component configuration. The mapper returns
+        a distinct staging path or None to refuse. References use final paths.
+        The caller owns validation, publication and cleanup, including failure.
+        Engine access inside the mapper is forbidden; exceptions are re-raised.
+        """
+        from ._access import StageMapper
+        from os import fspath
+        state = StageMapper(self._access, mapper)
+        cdef bytes path = fspath(final_path).encode('utf-8')
+        cdef int rc
+        cdef SWMM_Engine h = self.handle
+        with self._operation():
+            rc = swmm_model_write_staged(h, path, _stage_mapper, state)
+        if state.error is not None:
+            raise state.error
+        self._access.raise_callback_error()
+        _check(rc)
+
+    def write_compat(self, path, profile):
+        """Write FULL, OpenSWMM legacy, or stock EPA SWMM 5 input.
+
+        Conversion warnings appear in ``open_warnings``. The live model is not
+        changed. Compatibility profiles may omit unsupported model features.
+        """
+        from ._enums import InpProfile
+        self._access.require_idle()
+        cdef bytes destination = _path_to_str(path).encode('utf-8')
+        cdef int selected = int(InpProfile(profile))
+        with self._operation():
+            result = swmm_model_write_compat(self._handle, destination, selected)
+        self._access.raise_callback_error()
+        _check(result)
+
     def write(self, path) -> None:
         """Write the current model to a SWMM ``.inp`` file."""
         cdef bytes b = _path_to_str(path).encode('utf-8')
-        _check(swmm_model_write(self._handle, b))
+        self._access.require_idle()
+        with self._operation():
+            result = swmm_model_write(self._handle, b)
+        self._access.raise_callback_error()
+        _check(result)
 
     def write_with_plugin(self, path, str output_plugin_id="") -> None:
         """Write the current model using an output plugin.
@@ -678,7 +770,11 @@ cdef class Solver:
         """
         cdef bytes bp = _path_to_str(path).encode('utf-8')
         cdef bytes bid = output_plugin_id.encode('utf-8')
-        _check(swmm_model_write_with_plugin(self._handle, bp, bid))
+        self._access.require_idle()
+        with self._operation():
+            result = swmm_model_write_with_plugin(self._handle, bp, bid)
+        self._access.raise_callback_error()
+        _check(result)
 
     def write_geopackage(self, path, crs=None) -> None:
         """Write the model to an OGC GeoPackage (``.gpkg``).
@@ -732,7 +828,7 @@ cdef class Solver:
         @raise EngineError: On C API failure.
         """
         cdef int v = 0
-        _check(swmm_get_flow_units(self._handle, &v))
+        _check(swmm_get_flow_units(self.handle, &v))
         return FlowUnits(v)
 
     @property
@@ -749,7 +845,7 @@ cdef class Solver:
         @raise EngineError: On C API failure.
         """
         cdef int v = 0
-        _check(swmm_get_unit_system(self._handle, &v))
+        _check(swmm_get_unit_system(self.handle, &v))
         return "SI" if v == 1 else "US"
 
     @property
@@ -896,6 +992,41 @@ cdef class Solver:
             self._quality = Quality(self)
         return self._quality
 
+    @property
+    def initial_quality(self):
+        if self._initial_quality is None:
+            from ._initial_quality import InitialQuality
+            self._initial_quality = InitialQuality(self)
+        return self._initial_quality
+
+    @property
+    def reactions(self):
+        if self._reactions is None:
+            from ._reactions import Reactions
+            self._reactions = Reactions(self)
+        return self._reactions
+
+    @property
+    def heat(self):
+        if self._heat is None:
+            from ._heat import Heat
+            self._heat = Heat(self)
+        return self._heat
+
+    @property
+    def water_age(self):
+        if self._water_age is None:
+            from ._water_age import WaterAge
+            self._water_age = WaterAge(self)
+        return self._water_age
+
+    @property
+    def process_components(self):
+        if self._process_components is None:
+            from ._process_components import ProcessComponents
+            self._process_components = ProcessComponents(self)
+        return self._process_components
+
     @property
     def statistics(self):
         if self._statistics is None:
@@ -928,6 +1059,29 @@ cdef class Solver:
             self._hotstart = SaveSchedule(self)
         return self._hotstart
 
+    @property
+    def transport(self):
+        """ARD transport configuration and authored boundary/source rows."""
+        from ._transport import Transport
+        return Transport(self)
+
+    @property
+    def thread_info(self):
+        """Process-wide hardware and OpenMP limits."""
+        from ._transport import thread_info
+        return thread_info()
+
+    def effective_threads(self, requested=0):
+        """Thread team sizes for this model; zero requests automatic selection."""
+        from ._transport import effective_threads
+        return effective_threads(self, requested)
+
+    @property
+    def transport_matrix(self):
+        """Capability matrix keyed by domain and species class, with reasons."""
+        from ._transport import transport_matrix
+        return transport_matrix(self)
+
     @property
     def surface2d(self):
         """``solver.surface2d`` — the :class:`Surface2D` overland-flow view.
@@ -942,9 +1096,9 @@ cdef class Solver:
         @raise ImportError: When the extension was built without 2D
             support.
         """
-        if self._surface2d is None:
+        if self._surface2d is None or not self._surface2d._is_current():
             from ._2d import Surface2D
-            self._surface2d = Surface2D(self.handle)
+            self._surface2d = Surface2D(self)
         return self._surface2d
 
     # ------------------------------------------------------------------
@@ -954,21 +1108,23 @@ cdef class Solver:
     def open_runoff_interface_write(self, path) -> None:
         """Open the runoff interface file in SAVE mode."""
         cdef bytes b = _path_to_str(path).encode('utf-8')
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef const char* p = b
         cdef int err
-        with nogil:
-            err = swmm_runoff_iface_open_write(h, p)
+        with self._operation(h):
+            with nogil:
+                err = swmm_runoff_iface_open_write(h, p)
         _check(err)
 
     def open_runoff_interface_read(self, path) -> None:
         """Open the runoff interface file in USE mode."""
         cdef bytes b = _path_to_str(path).encode('utf-8')
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef const char* p = b
         cdef int err
-        with nogil:
-            err = swmm_runoff_iface_open_read(h, p)
+        with self._operation(h):
+            with nogil:
+                err = swmm_runoff_iface_open_read(h, p)
         _check(err)
 
     def save_runoff_step(self, dt) -> None:
@@ -982,10 +1138,11 @@ cdef class Solver:
             dt_s = dt.total_seconds()
         else:
             dt_s = float(dt)
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef int err
-        with nogil:
-            err = swmm_runoff_iface_save_step(h, dt_s)
+        with self._operation(h):
+            with nogil:
+                err = swmm_runoff_iface_save_step(h, dt_s)
         _check(err)
 
     def read_runoff_step(self) -> bool:
@@ -993,20 +1150,22 @@ cdef class Solver:
 
         :returns: ``True`` when a record was read, ``False`` on EOF.
         """
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef int has = 0
         cdef int err
-        with nogil:
-            err = swmm_runoff_iface_read_step(h, &has)
+        with self._operation(h):
+            with nogil:
+                err = swmm_runoff_iface_read_step(h, &has)
         _check(err)
         return bool(has)
 
     def close_runoff_interface(self) -> None:
         """Close the runoff interface file. Idempotent."""
-        cdef SWMM_Engine h = self._handle
+        cdef SWMM_Engine h = self.handle
         cdef int err
-        with nogil:
-            err = swmm_runoff_iface_close(h)
+        with self._operation(h):
+            with nogil:
+                err = swmm_runoff_iface_close(h)
         _check(err)
 
     # ------------------------------------------------------------------
@@ -1020,24 +1179,26 @@ cdef class Solver:
         ``sim_time`` is the current SWMM DateTime double and ``dt`` is
         seconds. Pass ``None`` to unregister.
         """
+        self._access.require_idle()
         if callback is None:
             self._step_begin_cb = None
-            _check(swmm_set_step_begin_callback(self._handle, NULL, NULL))
+            _check(swmm_set_step_begin_callback(self.handle, NULL, NULL))
         else:
-            self._step_begin_cb = callback
+            self._step_begin_cb = Callback(self._access, callback)
             _check(swmm_set_step_begin_callback(
-                self._handle, _step_begin_trampoline,
+                self.handle, _step_begin_trampoline,
                 self._step_begin_cb))
 
     def set_step_end_callback(self, callback) -> None:
         """Register a callback invoked at the end of each timestep."""
+        self._access.require_idle()
         if callback is None:
             self._step_end_cb = None
-            _check(swmm_set_step_end_callback(self._handle, NULL, NULL))
+            _check(swmm_set_step_end_callback(self.handle, NULL, NULL))
         else:
-            self._step_end_cb = callback
+            self._step_end_cb = Callback(self._access, callback)
             _check(swmm_set_step_end_callback(
-                self._handle, _step_end_trampoline,
+                self.handle, _step_end_trampoline,
                 self._step_end_cb))
 
     def set_warning_callback(self, callback) -> None:
@@ -1046,13 +1207,14 @@ cdef class Solver:
         The callable receives ``(code: int, message: str)``. Pass ``None``
         to unregister.
         """
+        self._access.require_idle()
         if callback is None:
             self._warning_cb = None
-            _check(swmm_set_warning_callback(self._handle, NULL, NULL))
+            _check(swmm_set_warning_callback(self.handle, NULL, NULL))
         else:
-            self._warning_cb = callback
+            self._warning_cb = Callback(self._access, callback)
             _check(swmm_set_warning_callback(
-                self._handle, _warning_trampoline,
+                self.handle, _warning_trampoline,
                 self._warning_cb))
 
     def set_progress_callback(self, callback) -> None:
@@ -1065,13 +1227,14 @@ cdef class Solver:
         @param callback: A callable ``(elapsed_frac: float) -> None``, or
             ``None`` to clear.
         """
+        self._access.require_idle()
         if callback is None:
             self._progress_cb = None
-            _check(swmm_set_progress_callback(self._handle, NULL, NULL))
+            _check(swmm_set_progress_callback(self.handle, NULL, NULL))
         else:
-            self._progress_cb = callback
+            self._progress_cb = Callback(self._access, callback)
             _check(swmm_set_progress_callback(
-                self._handle, _progress_trampoline,
+                self.handle, _progress_trampoline,
                 self._progress_cb))
 
     # ------------------------------------------------------------------
@@ -1085,20 +1248,19 @@ cdef class Solver:
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        # Lifecycle teardown swallows per-step errors so destroy always runs.
-        try:
-            self.end()
-        except EngineError:
-            pass
-        try:
-            self.report()
-        except EngineError:
-            pass
-        try:
-            self.close()
-        except EngineError:
-            pass
+        # Finish every teardown stage even if a user callback fails in one.
+        callback_error = None
+        for cleanup in (self.end, self.report, self.close):
+            try:
+                cleanup()
+            except EngineError:
+                pass
+            except BaseException as error:
+                if callback_error is None:
+                    callback_error = error
         self.destroy()
+        if exc_type is None and callback_error is not None:
+            raise callback_error
         return False
 
     def __repr__(self) -> str:
@@ -1175,7 +1337,16 @@ class SimulationOptions(MutableMapping):
         "FV_SLOT_CELERITY", "FV_DISPERSION", "FV_STRUCTURE_COUPLING",
         "FV_COMPACTION", "FV_BACKEND", "FV_MIN_PARALLEL_CELLS",
         "FV_LTS", "FV_LTS_MAX_TIERS", "FV_CFL_CENSUS_INTERVAL",
-        "FV_NODE_COUPLING", "FV_NODE_DT", "FV_NODE_PICARD",
+        # Unsteady friction (issue #156): consumed by the FV (Phase 2) and
+        # dynamic wave (Phase 3) solvers.
+        "UNSTEADY_FRICTION", "UF_K3",
+        # TPA pressure closure (issue #156 Phase 4): FV solver.
+        "FV_PRESSURE_CLOSURE",
+        # Signed piezometric heads in the .out HEAD field (issue #156 O-6).
+        "REPORT_SIGNED_HEADS",
+        # DW surcharge method + TPA celerity (issue #156 Phase 5; adding
+        # SURCHARGE_METHOD also closes the long-standing known-keys gap).
+        "SURCHARGE_METHOD", "TPA_CELERITY",
     )
 
     def __getitem__(self, key: str) -> str:
@@ -1706,3 +1877,22 @@ def run_with_callback(inp, rpt=None, out=None,
         return
     _check(swmm_engine_run_with_callback(
         b_inp, b_rpt, b_out, c_plugin, _progress_trampoline, callback))
+
+
+cdef extern from "openswmm/engine/openswmm_model.h":
+    int swmm_model_write_compat(SWMM_Engine, const char*, int)
+
+
+cdef const char* _stage_mapper(void* data, const char* path, int kind) noexcept with gil:
+    # Storage lives in state until the next callback, as required by the API.
+    try:
+        state = data
+        state.map(path.decode('utf-8'), kind)
+        return state.storage if state.error is None else NULL
+    except BaseException as error:
+        (data).error = error
+        return NULL
+
+cdef extern from "openswmm/engine/openswmm_model.h":
+    ctypedef const char* (*SWMM_StageOutputCallback)(void*, const char*, int) noexcept
+    int swmm_model_write_staged(SWMM_Engine, const char*, SWMM_StageOutputCallback, void*)
diff --git a/python/openswmm/engine/_spatial.pyx b/python/openswmm/engine/_spatial.pyx
index 8753a8df3..f905b1998 100644
--- a/python/openswmm/engine/_spatial.pyx
+++ b/python/openswmm/engine/_spatial.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Spatial / CRS / coordinates (Pythonic v1 surface)
 =================================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Reach via ``solver.spatial``. Provides CRS read/write, per-object
 coordinate access, link vertices, and subcatchment polygons. Every
diff --git a/python/openswmm/engine/_statistics.pyx b/python/openswmm/engine/_statistics.pyx
index 5a3552388..b211a0d60 100644
--- a/python/openswmm/engine/_statistics.pyx
+++ b/python/openswmm/engine/_statistics.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Simulation statistics (Pythonic v1 surface)
 ===========================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 This module exposes the **bulk** views of the per-object cumulative
 statistics. Single-object access lives on the wrapper classes
@@ -55,8 +71,9 @@ class Statistics:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_node_max_depth_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_node_max_depth_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -66,8 +83,9 @@ class Statistics:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_node_max_overflow_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_node_max_overflow_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -77,8 +95,9 @@ class Statistics:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_node_vol_flooded_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_node_vol_flooded_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -89,8 +108,9 @@ class Statistics:
         cdef int n = swmm_node_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_node_time_flooded_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_node_time_flooded_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -104,8 +124,9 @@ class Statistics:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_link_max_flow_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_link_max_flow_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -115,8 +136,9 @@ class Statistics:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_link_max_velocity_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_link_max_velocity_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -126,8 +148,9 @@ class Statistics:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_link_max_filling_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_link_max_filling_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -137,8 +160,9 @@ class Statistics:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_link_vol_flow_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_link_vol_flow_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -148,8 +172,9 @@ class Statistics:
         cdef int n = swmm_link_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_link_surcharge_time_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_link_surcharge_time_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -163,8 +188,9 @@ class Statistics:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_subcatch_runoff_vol_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_subcatch_runoff_vol_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -174,8 +200,9 @@ class Statistics:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_stat_subcatch_max_runoff_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_stat_subcatch_max_runoff_bulk(h, buf.data, n)
         _check(err)
         return buf
 
diff --git a/python/openswmm/engine/_subcatchments.pyi b/python/openswmm/engine/_subcatchments.pyi
index cec546192..4dbcc6742 100644
--- a/python/openswmm/engine/_subcatchments.pyi
+++ b/python/openswmm/engine/_subcatchments.pyi
@@ -1,21 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Subcatchment access (Pythonic v1 surface)
 =========================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Type stubs for :mod:`openswmm.engine._subcatchments`.
 """
 
 from collections.abc import Iterator, MutableMapping
-from typing import Any, NamedTuple, Optional, Tuple, Union
+from typing import Any, List, NamedTuple, Optional, Tuple, Union
 
 import numpy as np
 from numpy.typing import NDArray
 
-from ._enums import AquiferParam, InfilModel
+from ._enums import AquiferParam, GwfType, InfilModel
 from ._gages import Gage
 from ._nodes import Node
 from ._solver import Solver
@@ -62,8 +78,22 @@ class CoverageView(MutableMapping[str, float]):
     def __len__(self) -> int: ...
 
 
+class LoadingsView(MutableMapping[str, float]):
+    """Pollutant or species id -> initial buildup on a subcatchment."""
+    def __init__(self, sub: "Subcatchment") -> None: ...
+    def __getitem__(self, key: _Key) -> float: ...
+    def __setitem__(self, key: _Key, value: float) -> None: ...
+    def __delitem__(self, key: _Key) -> None: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
+
+
 class Subcatchment:
     """Single-subcatchment wrapper. See :class:`Subcatchments`."""
+    rain_scale_factor: float
+    snow_scale_factor: float
+    loadings: LoadingsView
+    def coverages(self) -> list[float]: ...
 
     # Identity
     id: str
@@ -151,10 +181,25 @@ class Subcatchments:
 
     def qualities(self, pollutant: _Key) -> NDArray[Any]: ...
 
+    def get_gwf_expression(self, key: _Key, gwf_type: Union[GwfType, int]) -> str: ...
+    def set_gwf_expression(
+        self, key: _Key, gwf_type: Union[GwfType, int], expression: Optional[str]
+    ) -> None: ...
+    def validate_gwf_expression(self, expression: str) -> Tuple[bool, str, int]: ...
+    def gwf_variables(self) -> List[Tuple[str, str]]: ...
+    def gwf_functions(self) -> List[str]: ...
+
 
 class Aquifers:
     """Name-keyed collection of C{[AQUIFERS]} entries (C{solver.aquifers})."""
 
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __contains__(self, key: object) -> bool: ...
+    def add(self, obj_id: str) -> int: ...
+    def get_index(self, obj_id: str) -> int: ...
+    def get_id(self, idx: int) -> str: ...
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def get_param(self, aquifer: _Key, param: Union[AquiferParam, int]) -> float: ...
     def set_param(
         self, aquifer: _Key, param: Union[AquiferParam, int], value: float
@@ -166,6 +211,13 @@ class Aquifers:
 class Snowpacks:
     """Name-keyed collection of C{[SNOWPACKS]} entries (C{solver.snowpacks})."""
 
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __contains__(self, key: object) -> bool: ...
+    def add(self, obj_id: str) -> int: ...
+    def get_index(self, obj_id: str) -> int: ...
+    def get_id(self, idx: int) -> str: ...
+    def rename(self, key: _Key, new_id: str) -> None: ...
     def set_plowable(
         self, snowpack: _Key, *,
         cmin: float, cmax: float, tbase: float, fwfrac: float,
diff --git a/python/openswmm/engine/_subcatchments.pyx b/python/openswmm/engine/_subcatchments.pyx
index c67fc7c53..f0b6aee50 100644
--- a/python/openswmm/engine/_subcatchments.pyx
+++ b/python/openswmm/engine/_subcatchments.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Subcatchment access (Pythonic v1 surface)
 =========================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`Subcatchments` collection and :class:`Subcatchment` wrapper
 follow the same shape as :mod:`openswmm.engine._nodes`. Each wrapper
@@ -1007,8 +1023,9 @@ cdef class Subcatchments:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_runoff_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_runoff_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1018,8 +1035,9 @@ cdef class Subcatchments:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_rainfall_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_rainfall_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1029,8 +1047,9 @@ cdef class Subcatchments:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_evap_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_evap_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1040,8 +1059,9 @@ cdef class Subcatchments:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_infil_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_infil_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1051,8 +1071,9 @@ cdef class Subcatchments:
         cdef int n = swmm_subcatch_count(h)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_snow_depth_bulk(h, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_snow_depth_bulk(h, buf.data, n)
         _check(err)
         return buf
 
@@ -1063,11 +1084,91 @@ cdef class Subcatchments:
         cdef int p = _resolve_pollutant(self._solver, pollutant)
         cdef np.ndarray[double, ndim=1] buf = np.empty(n, dtype=np.float64)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_quality_bulk(h, p, buf.data, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_quality_bulk(h, p, buf.data, n)
         _check(err)
         return buf
 
+    # ---- [GWF] custom groundwater flow expressions ------------------
+
+    def get_gwf_expression(self, key, gwf_type) -> str:
+        """Return a subcatchment's C{[GWF]} expression (empty if none is set).
+
+        @param key: Subcatchment index or string id.
+        @param gwf_type: L{GwfType} (C{LATERAL} or C{DEEP}) or its int code.
+        @rtype: str
+        """
+        cdef int idx = _resolve_subcatch(self._solver, key)
+        cdef char buf[1024]
+        _check(swmm_subcatch_get_gwf_expression(
+            _h(self._solver), idx, int(gwf_type), buf, sizeof(buf)))
+        return buf.decode('utf-8')
+
+    def set_gwf_expression(self, key, gwf_type, expression) -> None:
+        """Set or clear a subcatchment's C{[GWF]} expression.
+
+        The text is stored as given and is NOT validated here — use
+        :meth:`validate_gwf_expression` first; an invalid expression fails
+        C{initialize()} with ERROR 233. Pre-start-only; a mid-run change
+        raises L{LifecycleError}.
+
+        @param key: Subcatchment index or string id.
+        @param gwf_type: L{GwfType} (C{LATERAL} or C{DEEP}) or its int code.
+        @param expression: Expression text, or C{None}/``""`` to clear.
+        """
+        cdef int idx = _resolve_subcatch(self._solver, key)
+        cdef bytes b = (expression or "").encode('utf-8')
+        _check(swmm_subcatch_set_gwf_expression(
+            _h(self._solver), idx, int(gwf_type), b))
+
+    def validate_gwf_expression(self, str expression):
+        """Validate a C{[GWF]} expression WITHOUT modifying the engine.
+
+        Returns ``(ok, message, col)`` — ``ok`` True when the expression is
+        valid; on failure ``message`` is the diagnostic and ``col`` the
+        0-based character offset of the error (-1 when not attributable).
+        An empty expression is reported invalid; callers treat empty as
+        "clear" themselves.
+        """
+        cdef bytes b = expression.encode('utf-8')
+        cdef char errbuf[512]
+        cdef int col = -1
+        errbuf[0] = 0
+        cdef int rc = swmm_gwf_validate_expression(
+            _h(self._solver), b, errbuf, 512, &col)
+        if rc == 0:
+            return (True, "", -1)
+        return (False, errbuf.decode('utf-8'), col)
+
+    def gwf_variables(self):
+        """Variables a C{[GWF]} expression may reference, as a list of
+        ``(name, description)`` tuples (names upper-case, e.g. ``"HGW"``).
+        """
+        cdef SWMM_Engine h = _h(self._solver)
+        cdef int n = swmm_gwf_variable_count(h)
+        cdef char name[64]
+        cdef char desc[256]
+        out = []
+        for i in range(n):
+            _check(swmm_gwf_variable_name(h, i, name, sizeof(name)))
+            _check(swmm_gwf_variable_description(h, i, desc, sizeof(desc)))
+            out.append((name.decode('utf-8'), desc.decode('utf-8')))
+        return out
+
+    def gwf_functions(self):
+        """Built-in functions a C{[GWF]} expression may call, as a list of
+        lower-case names (``min``/``max`` take two arguments, the rest one).
+        """
+        cdef SWMM_Engine h = _h(self._solver)
+        cdef int n = swmm_gwf_function_count(h)
+        cdef char name[64]
+        out = []
+        for i in range(n):
+            _check(swmm_gwf_function_name(h, i, name, sizeof(name)))
+            out.append(name.decode('utf-8'))
+        return out
+
     @property
     def ids(self):
         return np.asarray(self._ids_list(), dtype=object)
@@ -1078,8 +1179,9 @@ cdef class Subcatchments:
         cdef np.ndarray[char, ndim=1, mode="c"] buf = np.zeros(
             n * stride, dtype=np.int8)
         cdef int err
-        with nogil:
-            err = swmm_subcatch_get_ids_bulk(h, buf.data, stride, n)
+        with self._solver._operation(h):
+            with nogil:
+                err = swmm_subcatch_get_ids_bulk(h, buf.data, stride, n)
         _check(err)
         raw = bytes(buf)
         out = []
@@ -1128,6 +1230,9 @@ cdef class _NamedObjects:
     cdef int _add(self, bytes b) except -1:
         raise NotImplementedError
 
+    cdef int _rename(self, int idx, bytes b) except -1:
+        raise NotImplementedError
+
     def __len__(self) -> int:
         return self._count()
 
@@ -1176,6 +1281,17 @@ cdef class _NamedObjects:
         self._solver._bump_generation()
         return self._count() - 1
 
+    def rename(self, key, str new_id) -> None:
+        """Rename an object, updating stored references to it.
+
+        @param key: Integer index or string id.
+        @param new_id: New identifier.
+        """
+        cdef int idx = key if isinstance(key, int) else self.get_index(key)
+        cdef bytes b = new_id.encode('utf-8')
+        self._rename(idx, b)
+        self._solver._bump_generation()
+
 
 cdef class Aquifers(_NamedObjects):
     """C{solver.aquifers} — name-keyed collection of C{[AQUIFERS]} entries."""
@@ -1193,6 +1309,10 @@ cdef class Aquifers(_NamedObjects):
         _check(swmm_aquifer_add(_h(self._solver), b))
         return 0
 
+    cdef int _rename(self, int idx, bytes b) except -1:
+        _check(swmm_aquifer_rename(_h(self._solver), idx, b))
+        return 0
+
     def get_param(self, aquifer, param) -> float:
         """Get an aquifer parameter (input-file units).
 
@@ -1269,6 +1389,10 @@ cdef class Snowpacks(_NamedObjects):
         _check(swmm_snowpack_add(_h(self._solver), b))
         return 0
 
+    cdef int _rename(self, int idx, bytes b) except -1:
+        _check(swmm_snowpack_rename(_h(self._solver), idx, b))
+        return 0
+
     # ---- Surface parameters (pre-start-only) -----------------------
     # Each of the three snow-melt surfaces takes seven values; ``last`` is the
     # plowable-area fraction for PLOWABLE and the 100%-cover depth for the
diff --git a/python/openswmm/engine/_surface_quality.pyi b/python/openswmm/engine/_surface_quality.pyi
new file mode 100644
index 000000000..bd7bfee83
--- /dev/null
+++ b/python/openswmm/engine/_surface_quality.pyi
@@ -0,0 +1,48 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from collections.abc import Mapping
+from typing import Any
+import numpy as np
+from numpy.typing import NDArray
+from ._enums import CellScope
+
+@dataclass(frozen=True)
+class SurfaceCoverage:
+    """A whole land-use coverage set at one scope; pairs carry percentages."""
+    scope: CellScope
+    tag: str
+    cell: int
+    landuses: tuple[tuple[str, float], ...]
+
+@dataclass(frozen=True)
+class SurfaceLoading:
+    """Initial species buildup in project mass per acre/hectare."""
+    scope: CellScope
+    tag: str
+    cell: int
+    species: str
+    value: float
+
+@dataclass(frozen=True)
+class SurfaceCurbLength:
+    """Authored curb length in project length units."""
+    scope: CellScope
+    tag: str
+    cell: int
+    length: float
+
+class SurfaceQuality:
+    def __init__(self, owner: Any) -> None: ...
+    @property
+    def coverages(self) -> tuple[SurfaceCoverage, ...]: ...
+    def set_coverage(self, scope: CellScope, landuses: Mapping[str, float], *, tag: str = ..., cell: int = ...) -> None: ...
+    def remove_coverage(self, index: int) -> None: ...
+    @property
+    def loadings(self) -> tuple[SurfaceLoading, ...]: ...
+    def set_loading(self, scope: CellScope, species: str, value: float, *, tag: str = ..., cell: int = ...) -> None: ...
+    def remove_loading(self, index: int) -> None: ...
+    @property
+    def curb_lengths(self) -> tuple[SurfaceCurbLength, ...]: ...
+    def set_curb_length(self, scope: CellScope, length: float, *, tag: str = ..., cell: int = ...) -> None: ...
+    def remove_curb_length(self, index: int) -> None: ...
+    def buildup(self, species: str) -> NDArray[np.float64]: ...
diff --git a/python/openswmm/engine/_surface_quality.pyx b/python/openswmm/engine/_surface_quality.pyx
new file mode 100644
index 000000000..8e9af5e28
--- /dev/null
+++ b/python/openswmm/engine/_surface_quality.pyx
@@ -0,0 +1,169 @@
+"""Scoped surface-quality authoring and independent buildup snapshots.
+
+Edit before initialization. GLOBAL < TAG < CELL resolution applies to entire
+coverage sets. All indices address cells, with no triangular-mesh assumption.
+"""
+from dataclasses import dataclass
+import numpy as np
+cimport numpy as np
+from libcpp.vector cimport vector
+from ._common cimport SWMM_Engine, _check
+from ._access import EngineView
+from ._enums import CellScope
+
+cdef extern from "openswmm/engine/openswmm_sq2d.h":
+    int swmm_2d_coverage_count(SWMM_Engine engine, int* count) nogil
+    int swmm_2d_coverage_set(SWMM_Engine engine, int scope, const char* tag, int cell, const char* const* landuses, const double* percents, int n) nogil
+    int swmm_2d_coverage_row_size(SWMM_Engine engine, int index, int* n) nogil
+    int swmm_2d_coverage_get(SWMM_Engine engine, int index, int k, int* scope, char* tag, int taglen, int* cell, char* landuse, int lulen, double* percent) nogil
+    int swmm_2d_coverage_remove(SWMM_Engine engine, int index) nogil
+    int swmm_2d_loading_count(SWMM_Engine engine, int* count) nogil
+    int swmm_2d_loading_set(SWMM_Engine engine, int scope, const char* tag, int cell, const char* species, double value) nogil
+    int swmm_2d_loading_get(SWMM_Engine engine, int index, int* scope, char* tag, int taglen, int* cell, char* species, int splen, double* value) nogil
+    int swmm_2d_loading_remove(SWMM_Engine engine, int index) nogil
+    int swmm_2d_curb_length_count(SWMM_Engine engine, int* count) nogil
+    int swmm_2d_curb_length_set(SWMM_Engine engine, int scope, const char* tag, int cell, double length) nogil
+    int swmm_2d_curb_length_get(SWMM_Engine engine, int index, int* scope, char* tag, int taglen, int* cell, double* length) nogil
+    int swmm_2d_curb_length_remove(SWMM_Engine engine, int index) nogil
+    int swmm_2d_get_buildup_bulk(SWMM_Engine engine, const char* species, double* out, int n) nogil
+
+cdef extern from "openswmm/engine/openswmm_2d.h":
+    int swmm_2d_cell_count(SWMM_Engine, int*)
+
+cdef inline SWMM_Engine _h(view):
+    return view._address()
+
+@dataclass(frozen=True)
+class SurfaceCoverage:
+    """A whole land-use coverage set at one scope; pairs carry percentages."""
+    scope: CellScope
+    tag: str
+    cell: int
+    landuses: tuple[tuple[str, float], ...]
+
+@dataclass(frozen=True)
+class SurfaceLoading:
+    """Initial species buildup in project mass per acre/hectare."""
+    scope: CellScope
+    tag: str
+    cell: int
+    species: str
+    value: float
+
+@dataclass(frozen=True)
+class SurfaceCurbLength:
+    """Authored curb length in project length units."""
+    scope: CellScope
+    tag: str
+    cell: int
+    length: float
+
+class SurfaceQuality(EngineView):
+    """``solver.surface2d.quality``: coverages, loadings and curb lengths."""
+    @property
+    def coverages(self):
+        """Immutable whole-scope coverage snapshots; percentages sum to <=100."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, index, pairs=0, k, scope=0, cell=0
+        cdef double percent=0
+        cdef char tag[512]
+        cdef char landuse[512]
+        _check(swmm_2d_coverage_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_2d_coverage_row_size(h, index, &pairs))
+            uses = []
+            for k in range(pairs):
+                _check(swmm_2d_coverage_get(h, index, k, &scope, tag, 512,
+                                           &cell, landuse, 512, &percent))
+                uses.append((landuse.decode('utf-8'), percent))
+            rows.append(SurfaceCoverage(CellScope(scope), tag.decode('utf-8'), cell, tuple(uses)))
+        return tuple(rows)
+
+    def set_coverage(self, scope, landuses, *, str tag='', int cell=-1):
+        """Replace the complete coverage set at a scope from a name→percent mapping."""
+        items = list(landuses.items())
+        if not items:
+            raise ValueError('Coverage needs at least one land use; remove the row to clear it')
+        encoded = [str(name).encode('utf-8') for name, _ in items]
+        cdef np.ndarray[double, ndim=1] values = np.asarray([v for _, v in items], dtype=np.float64)
+        if not np.isfinite(values).all():
+            raise ValueError('Coverage percentages must be finite')
+        cdef vector[const char*] names
+        cdef bytes encoded_name
+        for encoded_name in encoded:
+            names.push_back(encoded_name)
+        cdef bytes target = tag.encode('utf-8')
+        _check(swmm_2d_coverage_set(_h(self), int(CellScope(scope)), target, cell,
+                                   names.data(), values.data, len(items)))
+
+    def remove_coverage(self, int index):
+        """Remove an authored scope row; subsequent indices shift."""
+        _check(swmm_2d_coverage_remove(_h(self), index))
+
+    @property
+    def loadings(self):
+        """Initial buildup snapshots, in project mass per acre/hectare."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, index, scope=0, cell=0
+        cdef double value=0
+        cdef char tag[512]
+        cdef char species[512]
+        _check(swmm_2d_loading_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_2d_loading_get(h, index, &scope, tag, 512, &cell, species, 512, &value))
+            rows.append(SurfaceLoading(CellScope(scope), tag.decode('utf-8'), cell,
+                                        species.decode('utf-8'), value))
+        return tuple(rows)
+
+    def set_loading(self, scope, str species, double value, *, str tag='', int cell=-1):
+        """Upsert initial species buildup at GLOBAL, TAG or CELL scope."""
+        cdef bytes name = species.encode('utf-8')
+        cdef bytes target = tag.encode('utf-8')
+        _check(swmm_2d_loading_set(_h(self), int(CellScope(scope)), target, cell, name, value))
+
+    def remove_loading(self, int index):
+        """Remove one initial-buildup row."""
+        _check(swmm_2d_loading_remove(_h(self), index))
+
+    @property
+    def curb_lengths(self):
+        """Authored curb-length snapshots in project length units."""
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, index, scope=0, cell=0
+        cdef double value=0
+        cdef char tag[512]
+        _check(swmm_2d_curb_length_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_2d_curb_length_get(h, index, &scope, tag, 512, &cell, &value))
+            rows.append(SurfaceCurbLength(CellScope(scope), tag.decode('utf-8'), cell, value))
+        return tuple(rows)
+
+    def set_curb_length(self, scope, double length, *, str tag='', int cell=-1):
+        """Upsert a positive curb length at one scope, in project length units."""
+        cdef bytes target = tag.encode('utf-8')
+        _check(swmm_2d_curb_length_set(_h(self), int(CellScope(scope)), target, cell, length))
+
+    def remove_curb_length(self, int index):
+        """Remove an authored curb-length row."""
+        _check(swmm_2d_curb_length_remove(_h(self), index))
+
+    def buildup(self, str species):
+        """Owned float64 per-cell buildup in project mass per acre/hectare.
+
+        Requires an active resolved surface-quality store. The native engine
+        reports LifecycleError before start or for unavailable configurations.
+        """
+        cdef SWMM_Engine h = _h(self)
+        cdef int count=0, rc
+        cdef bytes name = species.encode('utf-8')
+        cdef const char* p = name
+        _check(swmm_2d_cell_count(h, &count))
+        cdef np.ndarray[double, ndim=1] values = np.empty(count, dtype=np.float64)
+        with self._owner._operation(h):
+            with nogil:
+                rc = swmm_2d_get_buildup_bulk(h, p, values.data, count)
+        _check(rc)
+        return values
diff --git a/python/openswmm/engine/_tables.pyi b/python/openswmm/engine/_tables.pyi
index 706aa75a8..3a4718884 100644
--- a/python/openswmm/engine/_tables.pyi
+++ b/python/openswmm/engine/_tables.pyi
@@ -27,6 +27,10 @@ class _PointTable:
 
 
 class TimeSeries(_PointTable):
+    @property
+    def relative_info(self) -> tuple[int, float]: ...
+    def set_relative_info(self, count: int, anchor: float) -> None: ...
+
     points: NDArray[Any]  # structured: (time: datetime64[s], value: float64)
 
     def add(self, when: Union[datetime, float], value: float) -> None: ...
diff --git a/python/openswmm/engine/_tables.pyx b/python/openswmm/engine/_tables.pyx
index 95d00adb6..35a6ec72d 100644
--- a/python/openswmm/engine/_tables.pyx
+++ b/python/openswmm/engine/_tables.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Tables, curves, patterns (Pythonic v1 surface)
 ==============================================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Three collections live on the engine — time series, curves, and
 patterns — and the C side stores time series and curves in a single
@@ -152,6 +168,25 @@ cdef class TimeSeries(_PointTable):
     """A SWMM time series — x is a SWMM DateTime double; we surface it as
     ``datetime64[s]``."""
 
+    @property
+    def relative_info(self):
+        """(number of leading relative rows, OADate anchor in days).
+
+        Stored x values are absolute. Subtract the anchor to recover authored
+        elapsed days. This metadata controls time-only INP serialization.
+        """
+        cdef int count = 0
+        cdef double anchor = 0
+        _check(swmm_timeseries_get_relative_info(_h(self._solver), self._index, &count, &anchor))
+        return (count, anchor)
+
+    def set_relative_info(self, int count, double anchor):
+        """Mark leading rows as relative without changing stored x values.
+
+        Call after rebuilding points. Count zero marks all rows explicitly dated.
+        """
+        _check(swmm_timeseries_set_relative_info(_h(self._solver), self._index, count, anchor))
+
     @property
     def points(self):
         """Structured numpy array with columns ``time: datetime64[s]`` and
@@ -501,3 +536,8 @@ cdef class Patterns:
             return f""
         except Exception:
             return ""
+
+
+cdef extern from "openswmm/engine/openswmm_tables.h":
+    int swmm_timeseries_get_relative_info(SWMM_Engine, int, int*, double*)
+    int swmm_timeseries_set_relative_info(SWMM_Engine, int, int, double)
diff --git a/python/openswmm/engine/_transport.pyi b/python/openswmm/engine/_transport.pyi
new file mode 100644
index 000000000..a9c1a296e
--- /dev/null
+++ b/python/openswmm/engine/_transport.pyi
@@ -0,0 +1,51 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import NamedTuple
+from ._enums import TransportDispersionMode, TransportDomain, TransportClass, TransportState
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ._solver import Solver
+    from ._model import ModelBuilder
+
+class ThreadInfo(NamedTuple):
+    logical_cpus: int
+    omp_max_threads: int
+    omp_available: bool
+    perf_cores: int
+    kokkos_omp_threads: int
+class EffectiveThreads(NamedTuple):
+    global_threads: int
+    dynamic_wave: int
+    surface2d: int
+@dataclass(frozen=True)
+class TransportCell:
+    state: TransportState
+    count: int
+    reason: str
+class TransportRow(NamedTuple):
+    element: str
+    species: str
+    is_timeseries: bool
+    value: float
+    timeseries: str
+class ConduitDispersion(NamedTuple):
+    link_index: int
+    value: float
+class Transport:
+    def __init__(self, owner: Solver | ModelBuilder) -> None: ...
+    @property
+    def configured(self) -> bool: ...
+    dispersion_mode: TransportDispersionMode
+    dispersion_value: float
+    target_dx: float
+    @property
+    def conduit_dispersion(self) -> tuple[ConduitDispersion, ...]: ...
+    @property
+    def boundaries(self) -> tuple[TransportRow, ...]: ...
+    @property
+    def sources(self) -> tuple[TransportRow, ...]: ...
+def thread_info() -> ThreadInfo: ...
+def effective_threads(owner: Solver, requested: int = ...) -> EffectiveThreads: ...
+def transport_matrix(owner: Solver) -> dict[TransportDomain, dict[TransportClass, TransportCell]]: ...
+def transport_domain_name(domain: TransportDomain) -> str: ...
+def transport_class_name(species_class: TransportClass) -> str: ...
diff --git a/python/openswmm/engine/_transport.pyx b/python/openswmm/engine/_transport.pyx
new file mode 100644
index 000000000..caff5faea
--- /dev/null
+++ b/python/openswmm/engine/_transport.pyx
@@ -0,0 +1,211 @@
+"""Transport configuration and engine capability snapshots.
+
+Dispersion values use project length squared per second; target spacing uses
+project length. Boundary/source rows are immutable snapshots because the
+native API currently resolves these rows only during model open.
+"""
+from dataclasses import dataclass
+from typing import NamedTuple
+from ._common cimport SWMM_Engine, _check
+from ._enums import TransportDispersionMode, TransportDomain, TransportClass, TransportState
+
+cdef extern from "openswmm/engine/openswmm_transport.h":
+    int swmm_transport_get_configured(SWMM_Engine engine, int* configured)
+    int swmm_transport_get_dispersion_mode(SWMM_Engine engine, int* mode)
+    int swmm_transport_set_dispersion_mode(SWMM_Engine engine, int mode)
+    int swmm_transport_get_dispersion_value(SWMM_Engine engine, double* value)
+    int swmm_transport_set_dispersion_value(SWMM_Engine engine, double value)
+    int swmm_transport_get_target_dx(SWMM_Engine engine, double* dx)
+    int swmm_transport_set_target_dx(SWMM_Engine engine, double dx)
+    int swmm_transport_conduit_disp_count(SWMM_Engine engine, int* count)
+    int swmm_transport_get_conduit_disp(SWMM_Engine engine, int index, int* link_index, double* value)
+    int swmm_transport_boundary_count(SWMM_Engine engine, int* count)
+    int swmm_transport_get_boundary(SWMM_Engine engine, int index, char* element, int elem_len, char* species, int spec_len, int* is_ts, double* value, char* ts_name, int ts_len)
+    int swmm_transport_source_count(SWMM_Engine engine, int* count)
+    int swmm_transport_get_source(SWMM_Engine engine, int index, char* element, int elem_len, char* species, int spec_len, int* is_ts, double* value, char* ts_name, int ts_len)
+
+cdef extern from "openswmm/engine/openswmm_engine.h":
+    ctypedef struct SWMM_ThreadInfo:
+        int logical_cpus
+        int omp_max_threads
+        int omp_available
+        int perf_cores
+        int kokkos_omp_threads
+    ctypedef struct SWMM_TransportCell:
+        int state
+        int count
+        char reason[96]
+    ctypedef struct SWMM_TransportMatrix:
+        SWMM_TransportCell cell[4][4]
+    int swmm_get_thread_info(SWMM_ThreadInfo*)
+    int swmm_get_effective_threads(SWMM_Engine, int, int*, int*, int*)
+    int swmm_get_transport_matrix(SWMM_Engine, SWMM_TransportMatrix*)
+    const char* swmm_transport_domain_name(int)
+    const char* swmm_transport_class_name(int)
+
+cdef inline SWMM_Engine _h(owner):
+    return owner.handle
+
+class ThreadInfo(NamedTuple):
+    logical_cpus: int
+    omp_max_threads: int
+    omp_available: bool
+    perf_cores: int
+    kokkos_omp_threads: int
+
+class EffectiveThreads(NamedTuple):
+    global_threads: int
+    dynamic_wave: int
+    surface2d: int
+
+@dataclass(frozen=True)
+class TransportCell:
+    state: TransportState
+    count: int
+    reason: str
+
+class TransportRow(NamedTuple):
+    element: str
+    species: str
+    is_timeseries: bool
+    value: float
+    timeseries: str
+
+class ConduitDispersion(NamedTuple):
+    link_index: int
+    value: float
+
+def thread_info():
+    """Hardware and OpenMP limits; zero means unknown/not initialized."""
+    cdef SWMM_ThreadInfo info
+    _check(swmm_get_thread_info(&info))
+    return ThreadInfo(info.logical_cpus, info.omp_max_threads,
+                      bool(info.omp_available), info.perf_cores, info.kokkos_omp_threads)
+
+def effective_threads(owner, int requested=0):
+    """Resolve thread teams for this model; requested=0 selects auto."""
+    cdef int general=0, dw=0, surface=0
+    _check(swmm_get_effective_threads(_h(owner), requested, &general, &dw, &surface))
+    return EffectiveThreads(general, dw, surface)
+
+def transport_matrix(owner):
+    """Fresh capability matrix keyed by domain then species class.
+
+    Read after open and after options change. Unavailable entries carry a
+    reason instead of implying the process is implemented by a backend.
+    """
+    cdef SWMM_TransportMatrix matrix
+    cdef int d, c
+    _check(swmm_get_transport_matrix(_h(owner), &matrix))
+    return {TransportDomain(d): {
+        TransportClass(c): TransportCell(TransportState(matrix.cell[d][c].state),
+            matrix.cell[d][c].count, matrix.cell[d][c].reason.decode('utf-8'))
+        for c in range(4)} for d in range(4)}
+
+def transport_domain_name(domain):
+    """Native display label for a validated TransportDomain."""
+    return swmm_transport_domain_name(int(TransportDomain(domain))).decode('utf-8')
+
+def transport_class_name(species_class):
+    """Native display label for a validated TransportClass."""
+    return swmm_transport_class_name(int(TransportClass(species_class))).decode('utf-8')
+
+class Transport:
+    """``solver.transport`` configuration, with read-only authored rows."""
+    def __init__(self, owner):
+        self._owner = owner
+
+    @property
+    def configured(self):
+        """Whether an ARD transport component is configured."""
+        cdef int value = 0
+        _check(swmm_transport_get_configured(_h(self._owner), &value))
+        return bool(value)
+
+    @property
+    def dispersion_mode(self):
+        """Global dispersion closure, including per-conduit overrides."""
+        cdef int value = 0
+        _check(swmm_transport_get_dispersion_mode(_h(self._owner), &value))
+        return TransportDispersionMode(value)
+
+    @dispersion_mode.setter
+    def dispersion_mode(self, value):
+        _check(swmm_transport_set_dispersion_mode(_h(self._owner), int(TransportDispersionMode(value))))
+
+    @property
+    def dispersion_value(self):
+        """Nonnegative coefficient in project length squared per second."""
+        cdef double value = 0
+        _check(swmm_transport_get_dispersion_value(_h(self._owner), &value))
+        return value
+
+    @dispersion_value.setter
+    def dispersion_value(self, double value):
+        _check(swmm_transport_set_dispersion_value(_h(self._owner), value))
+
+    @property
+    def target_dx(self):
+        """Nonnegative target spacing in project length; zero uses the default."""
+        cdef double value = 0
+        _check(swmm_transport_get_target_dx(_h(self._owner), &value))
+        return value
+
+    @target_dx.setter
+    def target_dx(self, double value):
+        _check(swmm_transport_set_target_dx(_h(self._owner), value))
+
+    @property
+    def conduit_dispersion(self):
+        """Immutable per-conduit (link index, coefficient) snapshots."""
+        cdef int count=0, index=0, link=0
+        cdef double value=0
+        cdef SWMM_Engine h = _h(self._owner)
+        _check(swmm_transport_conduit_disp_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_transport_get_conduit_disp(h, index, &link, &value))
+            rows.append(ConduitDispersion(link, value))
+        return tuple(rows)
+
+    @property
+    def boundaries(self):
+        """Authored rows; value is concentration in species units.
+
+        For timeseries rows read ``timeseries`` instead of ``value``.
+        """
+        cdef int count=0, index=0, is_ts=0
+        cdef double value=0
+        cdef char element[256]
+        cdef char species[256]
+        cdef char series[256]
+        cdef SWMM_Engine h = _h(self._owner)
+        _check(swmm_transport_boundary_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_transport_get_boundary(h, index, element, 256, species, 256,
+                                                 &is_ts, &value, series, 256))
+            rows.append(TransportRow(element.decode('utf-8'), species.decode('utf-8'),
+                        bool(is_ts), value, series.decode('utf-8')))
+        return tuple(rows)
+
+    @property
+    def sources(self):
+        """Authored rows; value is mass rate in species mass units per second.
+
+        For timeseries rows read ``timeseries`` instead of ``value``.
+        """
+        cdef int count=0, index=0, is_ts=0
+        cdef double value=0
+        cdef char element[256]
+        cdef char species[256]
+        cdef char series[256]
+        cdef SWMM_Engine h = _h(self._owner)
+        _check(swmm_transport_source_count(h, &count))
+        rows = []
+        for index in range(count):
+            _check(swmm_transport_get_source(h, index, element, 256, species, 256,
+                                                 &is_ts, &value, series, 256))
+            rows.append(TransportRow(element.decode('utf-8'), species.decode('utf-8'),
+                        bool(is_ts), value, series.decode('utf-8')))
+        return tuple(rows)
diff --git a/python/openswmm/engine/_water_age.pyi b/python/openswmm/engine/_water_age.pyi
new file mode 100644
index 000000000..82ebfbbcb
--- /dev/null
+++ b/python/openswmm/engine/_water_age.pyi
@@ -0,0 +1,48 @@
+"""Type stubs for :mod:`openswmm.engine._water_age`."""
+
+from collections.abc import Iterator
+from os import PathLike
+from typing import NamedTuple, Union
+
+from ._enums import WaterAgeSource
+from ._solver import Solver
+
+
+_Node = Union[int, str]
+_Source = Union[WaterAgeSource, int, str]
+_PathLike = Union[str, PathLike[str]]
+
+
+class WaterAgeOverride(NamedTuple):
+    source: WaterAgeSource
+    node_index: int
+    hours: float
+
+
+class _WaterAgeGlobals:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[WaterAgeSource]: ...
+    def __getitem__(self, key: _Source) -> float: ...
+    def __setitem__(self, key: _Source, hours: float) -> None: ...
+    def __contains__(self, key: object) -> bool: ...
+
+
+class _WaterAgeOverrides:
+    def __init__(self, solver: Solver) -> None: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[WaterAgeOverride]: ...
+    def __getitem__(self, row_index: int) -> WaterAgeOverride: ...
+    def set(self, source: _Source, node: _Node, hours: float) -> None: ...
+    def remove(self, source: _Source, node: _Node) -> None: ...
+
+
+class WaterAge:
+    def __init__(self, solver: Solver) -> None: ...
+
+    @property
+    def enabled(self) -> bool: ...
+    globals: _WaterAgeGlobals
+    node_overrides: _WaterAgeOverrides
+
+    def save(self, path: _PathLike) -> None: ...
diff --git a/python/openswmm/engine/_water_age.pyx b/python/openswmm/engine/_water_age.pyx
new file mode 100644
index 000000000..105577f35
--- /dev/null
+++ b/python/openswmm/engine/_water_age.pyx
@@ -0,0 +1,360 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Water age (Pythonic v1 surface)
+===============================
+
+:author: Caleb Buahin
+:copyright: Copyright (c) 2026 Caleb Buahin
+:license: Apache-2.0
+
+``solver.water_age`` is the editable ``[WATER_AGE_SOURCES]`` table: a GLOBAL
+age per source pathway, plus per-NODE overrides for the ``DWF`` and
+``EXTERNAL_INFLOW`` pathways. Every value is in **HOURS**, the config file's
+own unit, and **negative values are legal** — a negative source age *extracts*
+age-volume rather than adding it, clamped so the resulting age never goes
+below zero. Only ``DWF`` and ``EXTERNAL_INFLOW`` accept NODE scope; asking any
+other pathway for a node override is refused with
+:class:`~openswmm.engine.BadParamError`, exactly as the deck parser refuses it
+(the A1a scope rule).
+
+**Edits are live.** Setters mutate engine state and the water-age loaders
+re-read the table every step, so a mid-run edit takes effect on the next
+routing step. :meth:`WaterAge.save` persists the current table as a
+``model.age`` component file.
+
+.. code-block:: python
+
+    from openswmm.engine import Solver, WaterAgeSource
+
+    with Solver("model.inp") as s:
+        if s.water_age.enabled:
+            s.water_age.globals[WaterAgeSource.RAINFALL] = 0.0
+            s.water_age.globals[WaterAgeSource.DWF] = 6.0
+            # Negative is legal: this DWF stream extracts age-volume.
+            s.water_age.node_overrides.set(WaterAgeSource.DWF, "J1", -2.0)
+            for row in s.water_age.node_overrides:
+                print(row.source.name, row.node_index, row.hours)
+            s.water_age.save("model.age")
+"""
+
+# cython: language_level=3
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from ._common cimport *
+from ._enums import WaterAgeSource
+
+
+cdef inline SWMM_Engine _h(solver):
+    return solver.handle
+
+
+cdef inline int _resolve_node(solver, key) except -1:
+    return _resolve_index(
+        _h(solver), key, swmm_node_index, swmm_node_count, "Node")
+
+
+def _source(key):
+    """Coerce *key* (member, int code, or member name) to :class:`WaterAgeSource`.
+
+    :param key: A :class:`WaterAgeSource` member, its integer code, or its
+        member name (case-insensitive).
+    :returns: The matching :class:`WaterAgeSource` member.
+    :raises KeyError: *key* names no member; the message lists the valid ones.
+    """
+    if isinstance(key, WaterAgeSource):
+        return key
+    try:
+        if isinstance(key, str):
+            return WaterAgeSource[key.upper()]
+        return WaterAgeSource(key)
+    except (KeyError, ValueError):
+        pass
+    valid = ", ".join(m.name for m in WaterAgeSource)
+    raise KeyError(
+        f"{key!r} is not a valid WaterAgeSource; valid members: {valid}")
+
+
+class WaterAgeOverride(NamedTuple):
+    """One ``[WATER_AGE_SOURCES]`` NODE-scope override row.
+
+    :ivar source: The :class:`WaterAgeSource` the row overrides. Only
+        ``DWF`` and ``EXTERNAL_INFLOW`` can appear here (the A1a scope rule).
+    :ivar node_index: Zero-based index of the node the override applies to.
+    :ivar hours: Age this source's water enters that node at, in HOURS.
+        Signed — a negative value extracts age-volume, clamped so the
+        resulting age never goes below zero.
+    """
+
+    source: WaterAgeSource
+    node_index: int
+    hours: float
+
+
+# =============================================================================
+# [WATER_AGE_SOURCES] — GLOBAL ages
+# =============================================================================
+
+class _WaterAgeGlobals:
+    """``solver.water_age.globals`` — mapping keyed by :class:`WaterAgeSource`.
+
+    Values are inlet ages in HOURS, one per source pathway. The table is a
+    fixed enum extent, not a parsed list, so every pathway is readable even on
+    a model that configured none of them.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of source pathways the table carries (7).
+
+        :returns: ``len(WaterAgeSource)``.
+        """
+        return len(WaterAgeSource)
+
+    def __iter__(self) -> Iterator[WaterAgeSource]:
+        return iter(WaterAgeSource)
+
+    def __getitem__(self, key) -> float:
+        """Read one pathway's GLOBAL source age.
+
+        :param key: A :class:`WaterAgeSource` member, code, or name.
+        :returns: The global source age in HOURS. Signed — see
+            :meth:`__setitem__`.
+        :raises KeyError: *key* is not a valid :class:`WaterAgeSource`.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef double hours = 0.0
+        source = _source(key)
+        _check(swmm_water_age_get_global_source(
+            _h(self._solver), int(source), &hours))
+        return hours
+
+    def __setitem__(self, key, double hours) -> None:
+        """Write one pathway's GLOBAL source age and mark the table present.
+
+        The edit is live: the water-age loaders re-read the table, so a
+        mid-run write takes effect on the next routing step.
+
+        :param key: A :class:`WaterAgeSource` member, code, or name.
+        :param hours: Inlet age in HOURS. **Negative values are legal** — a
+            negative source age extracts age-volume instead of adding it, and
+            the engine clamps the result so age never goes below zero.
+        :raises KeyError: *key* is not a valid :class:`WaterAgeSource`.
+        :raises EngineError: The engine refused the write.
+        """
+        source = _source(key)
+        _check(swmm_water_age_set_global_source(
+            _h(self._solver), int(source), hours))
+
+    def __contains__(self, key) -> bool:
+        """Is *key* a source pathway this table carries?
+
+        :param key: A :class:`WaterAgeSource` member, code, or name.
+        :returns: ``True`` when *key* names a valid pathway.
+        """
+        try:
+            _source(key)
+            return True
+        except (KeyError, TypeError):
+            return False
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# [WATER_AGE_SOURCES] — NODE-scope overrides
+# =============================================================================
+
+class _WaterAgeOverrides:
+    """``solver.water_age.node_overrides`` — the NODE-scope override rows.
+
+    A sequence of :class:`WaterAgeOverride` rows indexed by row position. Row
+    order is stable across edits within a session.
+
+    Only :attr:`WaterAgeSource.DWF` and
+    :attr:`WaterAgeSource.EXTERNAL_INFLOW` may be overridden per node — the
+    A1a scope rule, refused rather than silently ignored, the same answer the
+    deck gets.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+
+    def __len__(self) -> int:
+        """Number of NODE-scope override rows.
+
+        :returns: The row count.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int count = 0
+        _check(swmm_water_age_override_count(_h(self._solver), &count))
+        return count
+
+    def __iter__(self) -> Iterator[WaterAgeOverride]:
+        cdef int n = len(self)
+        for i in range(n):
+            yield self[i]
+
+    def __getitem__(self, int row_index) -> WaterAgeOverride:
+        """Read one NODE override by row index.
+
+        :param row_index: Zero-based row position; negative indexes from the
+            end, as for a list.
+        :returns: A :class:`WaterAgeOverride` of
+            ``(source, node_index, hours)`` with *hours* in HOURS, signed.
+        :raises IndexError: *row_index* is out of range.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int n = len(self)
+        cdef int i = row_index + n if row_index < 0 else row_index
+        if not (0 <= i < n):
+            raise IndexError(row_index)
+        cdef int source = 0
+        cdef int node_index = -1
+        cdef double hours = 0.0
+        _check(swmm_water_age_get_override(
+            _h(self._solver), i, &source, &node_index, &hours))
+        return WaterAgeOverride(WaterAgeSource(source), node_index, hours)
+
+    def set(self, source, node, double hours) -> None:
+        """Add or update the NODE override for ``(source, node)``.
+
+        An existing ``(source, node)`` pair is **updated**, not duplicated:
+        one row per pair, whether the caller reaches it by writing once or
+        twice. The edit is live — it takes effect on the next routing step.
+
+        :param source: A :class:`WaterAgeSource` member, code, or name. Only
+            :attr:`WaterAgeSource.DWF` and
+            :attr:`WaterAgeSource.EXTERNAL_INFLOW` take NODE scope.
+        :param node: ``int`` node index or ``str`` node id.
+        :param hours: Inlet age in HOURS. **Negative values are legal** — a
+            negative source age extracts age-volume, clamped so the resulting
+            age never goes below zero.
+        :raises KeyError: *source* is not a valid :class:`WaterAgeSource`, or
+            no node with that id exists.
+        :raises BadParamError: *source* is neither ``DWF`` nor
+            ``EXTERNAL_INFLOW`` — the A1a scope rule, the same refusal the
+            parser gives.
+        :raises EngineError: *node* is out of range, or the engine otherwise
+            refused the write.
+        """
+        kind = _source(source)
+        cdef int ni = _resolve_node(self._solver, node)
+        _check(swmm_water_age_set_override(
+            _h(self._solver), int(kind), ni, hours))
+        self._solver._bump_generation()
+
+    def remove(self, source, node) -> None:
+        """Remove the NODE override for ``(source, node)``.
+
+        Keyed on the ``(source, node)`` pair, **not** on a row index — the row
+        table is addressed positionally for reading only. Later rows may shift
+        after a removal, so a caller iterating by index must re-read the
+        length.
+
+        :param source: A :class:`WaterAgeSource` member, code, or name.
+        :param node: ``int`` node index or ``str`` node id.
+        :raises KeyError: *source* is not a valid :class:`WaterAgeSource`, or
+            no node with that id exists.
+        :raises BadIndexError: No override exists for that ``(source, node)``
+            pair.
+        :raises EngineError: The engine otherwise refused the removal.
+        """
+        kind = _source(source)
+        cdef int ni = _resolve_node(self._solver, node)
+        _check(swmm_water_age_remove_override(
+            _h(self._solver), int(kind), ni))
+        self._solver._bump_generation()
+
+    def __repr__(self) -> str:
+        try:
+            return f""
+        except Exception:
+            return ""
+
+
+# =============================================================================
+# Water-age view
+# =============================================================================
+
+class WaterAge:
+    """``solver.water_age`` — the ``[WATER_AGE_SOURCES]`` configuration.
+
+    Every value is in HOURS and signed: a negative source age extracts
+    age-volume, clamped so age never goes below zero. Edits are live — the
+    loaders re-read the table every step, so a mid-run edit takes effect on
+    the next routing step.
+    """
+
+    def __init__(self, solver):
+        self._solver = solver
+        self._globals = None
+        self._node_overrides = None
+
+    @property
+    def enabled(self) -> bool:
+        """Is ``[OPTIONS] WATER_AGE`` on? Read-only.
+
+        :returns: ``True`` when water-age tracking is enabled for the model.
+        :raises EngineError: The engine refused the read.
+        """
+        cdef int enabled = 0
+        _check(swmm_water_age_get_enabled(_h(self._solver), &enabled))
+        return enabled != 0
+
+    @property
+    def globals(self) -> _WaterAgeGlobals:
+        """GLOBAL source ages in HOURS, a mapping keyed by
+        :class:`WaterAgeSource`."""
+        if self._globals is None:
+            self._globals = _WaterAgeGlobals(self._solver)
+        return self._globals
+
+    @property
+    def node_overrides(self) -> _WaterAgeOverrides:
+        """NODE-scope override rows, indexed by row position. Only ``DWF``
+        and ``EXTERNAL_INFLOW`` are in scope."""
+        if self._node_overrides is None:
+            self._node_overrides = _WaterAgeOverrides(self._solver)
+        return self._node_overrides
+
+    def save(self, path) -> None:
+        """Write the current table as a ``[WATER_AGE_SOURCES]`` component file.
+
+        The output is the ``model.age`` format the waterage component parses,
+        so a saved file reloads into the same table.
+
+        :param path: Destination file path (``str`` or ``os.PathLike``).
+        :raises EngineError: The file could not be written.
+        """
+        cdef bytes b = str(path).encode('utf-8')
+        _check(swmm_water_age_save(_h(self._solver), b))
+
+    def __repr__(self) -> str:
+        try:
+            return (f"")
+        except Exception:
+            return ""
diff --git a/python/openswmm/engine/_xsect.pyx b/python/openswmm/engine/_xsect.pyx
index 861d8ae63..ca72f41cb 100644
--- a/python/openswmm/engine/_xsect.pyx
+++ b/python/openswmm/engine/_xsect.pyx
@@ -1,10 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Cross-Section Geometry
 ======================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 The :class:`XSectionGeometry` class exposes the engine's cross-section
 geometry kernels as a standalone reference implementation — the same code the
diff --git a/python/openswmm/engine/catalog.json b/python/openswmm/engine/catalog.json
new file mode 100644
index 000000000..1976321c4
--- /dev/null
+++ b/python/openswmm/engine/catalog.json
@@ -0,0 +1,23433 @@
+{
+ "schema": 1,
+ "note": "Generated by python/scripts/gen_catalog.py -- do not edit by hand.",
+ "c_exports": 1173,
+ "targets": {
+  "aquifers": {
+   "class": "Aquifers",
+   "module": "_subcatchments",
+   "path": "aquifers",
+   "doc": "Name-keyed collection of [AQUIFERS] entries (solver.aquifers).",
+   "parent": "solver"
+  },
+  "builder": {
+   "class": "ModelBuilder",
+   "module": "_model",
+   "path": "",
+   "doc": "Build a SWMM model programmatically (no .inp file).",
+   "construct": {
+    "via": "new",
+    "args": []
+   },
+   "c": [
+    "swmm_engine_new"
+   ]
+  },
+  "climate": {
+   "class": "Climate",
+   "module": "_climate",
+   "path": "climate",
+   "doc": "",
+   "parent": "solver"
+  },
+  "coefficient": {
+   "class": "ReactionCoefficient",
+   "module": "_reactions",
+   "path": "reactions.coefficients[]",
+   "doc": "",
+   "collection": "reactions.coefficients",
+   "key": "Union[int, str]"
+  },
+  "controls": {
+   "class": "Controls",
+   "module": "_controls",
+   "path": "controls",
+   "doc": "",
+   "parent": "solver"
+  },
+  "editor": {
+   "class": "ModelEditor",
+   "module": "_edit",
+   "path": "editor",
+   "doc": "Edit an existing SWMM model -- delete objects and convert types.",
+   "parent": "solver"
+  },
+  "events": {
+   "class": "EventsView",
+   "module": "_solver",
+   "path": "events",
+   "doc": "[EVENTS] block as a MutableSequence. See Solver.events.",
+   "parent": "solver"
+  },
+  "forcing": {
+   "class": "Forcing",
+   "module": "_forcing",
+   "path": "forcing",
+   "doc": "",
+   "parent": "solver"
+  },
+  "gage": {
+   "class": "Gage",
+   "module": "_gages",
+   "path": "gages[]",
+   "doc": "",
+   "collection": "gages",
+   "key": "Union[int, str]"
+  },
+  "gages": {
+   "class": "Gages",
+   "module": "_gages",
+   "path": "gages",
+   "doc": "",
+   "parent": "solver",
+   "element": "gage",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_index"
+   ]
+  },
+  "geopackage": {
+   "class": "GeoPackage",
+   "module": "_geopackage",
+   "path": "",
+   "doc": "GeoPackage database access for SWMM models, results, and observed data.",
+   "construct": {
+    "via": "new",
+    "args": [
+     "path"
+    ]
+   },
+   "c": [
+    "swmm_gpkg_close",
+    "swmm_gpkg_open"
+   ]
+  },
+  "heat": {
+   "class": "Heat",
+   "module": "_heat",
+   "path": "heat",
+   "doc": "",
+   "parent": "solver"
+  },
+  "heat.cloud": {
+   "class": "_HeatCloud",
+   "module": "_heat",
+   "path": "heat.cloud",
+   "doc": "",
+   "parent": "heat"
+  },
+  "heat.modules": {
+   "class": "_HeatModules",
+   "module": "_heat",
+   "path": "heat.modules",
+   "doc": "",
+   "parent": "heat"
+  },
+  "heat.node_overrides": {
+   "class": "_HeatNodeOverrides",
+   "module": "_heat",
+   "path": "heat.node_overrides",
+   "doc": "",
+   "parent": "heat"
+  },
+  "heat.radiative": {
+   "class": "_HeatRadiative",
+   "module": "_heat",
+   "path": "heat.radiative",
+   "doc": "",
+   "parent": "heat"
+  },
+  "heat.solar": {
+   "class": "_HeatSolar",
+   "module": "_heat",
+   "path": "heat.solar",
+   "doc": "",
+   "parent": "heat"
+  },
+  "heat.sources": {
+   "class": "_HeatSources",
+   "module": "_heat",
+   "path": "heat.sources",
+   "doc": "",
+   "parent": "heat"
+  },
+  "hotstart": {
+   "class": "HotStart",
+   "module": "_hotstart",
+   "path": "",
+   "doc": "",
+   "construct": {
+    "via": "open",
+    "args": [
+     "path"
+    ]
+   },
+   "c": [
+    "swmm_hotstart_close"
+   ]
+  },
+  "inflows": {
+   "class": "Inflows",
+   "module": "_inflows",
+   "path": "inflows",
+   "doc": "",
+   "parent": "solver"
+  },
+  "infrastructure": {
+   "class": "Infrastructure",
+   "module": "_infrastructure",
+   "path": "infrastructure",
+   "doc": "",
+   "parent": "solver"
+  },
+  "infrastructure.inlet_usages": {
+   "class": "InletUsages",
+   "module": "_infrastructure",
+   "path": "infrastructure.inlet_usages",
+   "doc": "",
+   "parent": "infrastructure"
+  },
+  "infrastructure.inlets": {
+   "class": "Inlets",
+   "module": "_infrastructure",
+   "path": "infrastructure.inlets",
+   "doc": "",
+   "parent": "infrastructure"
+  },
+  "infrastructure.lids": {
+   "class": "LIDs",
+   "module": "_infrastructure",
+   "path": "infrastructure.lids",
+   "doc": "",
+   "parent": "infrastructure"
+  },
+  "infrastructure.streets": {
+   "class": "Streets",
+   "module": "_infrastructure",
+   "path": "infrastructure.streets",
+   "doc": "",
+   "parent": "infrastructure"
+  },
+  "infrastructure.transects": {
+   "class": "Transects",
+   "module": "_infrastructure",
+   "path": "infrastructure.transects",
+   "doc": "",
+   "parent": "infrastructure"
+  },
+  "initial_quality": {
+   "class": "InitialQuality",
+   "module": "_initial_quality",
+   "path": "initial_quality",
+   "doc": "",
+   "parent": "solver"
+  },
+  "landuse": {
+   "class": "Landuse",
+   "module": "_quality",
+   "path": "quality.landuses[]",
+   "doc": "",
+   "collection": "quality.landuses",
+   "key": "Union[int, str]"
+  },
+  "link": {
+   "class": "Link",
+   "module": "_links",
+   "path": "links[]",
+   "doc": "Single-link wrapper. See Links for the collection.",
+   "collection": "links",
+   "key": "Union[int, str]",
+   "subtype_field": "type"
+  },
+  "link.orifice": {
+   "class": "OrificeView",
+   "module": "_links",
+   "path": "links[].orifice",
+   "doc": "",
+   "parent": "link",
+   "subtypes": [
+    "ORIFICE"
+   ]
+  },
+  "link.outlet": {
+   "class": "OutletView",
+   "module": "_links",
+   "path": "links[].outlet",
+   "doc": "",
+   "parent": "link",
+   "subtypes": [
+    "OUTLET"
+   ]
+  },
+  "link.pump": {
+   "class": "PumpView",
+   "module": "_links",
+   "path": "links[].pump",
+   "doc": "",
+   "parent": "link",
+   "subtypes": [
+    "PUMP"
+   ]
+  },
+  "link.stats": {
+   "class": "LinkStatsView",
+   "module": "_links",
+   "path": "links[].stats",
+   "doc": "",
+   "parent": "link"
+  },
+  "link.weir": {
+   "class": "WeirView",
+   "module": "_links",
+   "path": "links[].weir",
+   "doc": "",
+   "parent": "link",
+   "subtypes": [
+    "WEIR"
+   ]
+  },
+  "link.xsect": {
+   "class": "XSection",
+   "module": "_links",
+   "path": "links[].xsect",
+   "doc": "",
+   "parent": "link"
+  },
+  "links": {
+   "class": "Links",
+   "module": "_links",
+   "path": "links",
+   "doc": "Indexable, iterable collection of Link wrappers.",
+   "parent": "solver",
+   "element": "link",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index"
+   ]
+  },
+  "mass_balance": {
+   "class": "MassBalance",
+   "module": "_massbalance",
+   "path": "mass_balance",
+   "doc": "",
+   "parent": "solver"
+  },
+  "node": {
+   "class": "Node",
+   "module": "_nodes",
+   "path": "nodes[]",
+   "doc": "Single-node wrapper. See Nodes for the collection.",
+   "collection": "nodes",
+   "key": "Union[int, str]",
+   "subtype_field": "type"
+  },
+  "node.divider": {
+   "class": "DividerView",
+   "module": "_nodes",
+   "path": "nodes[].divider",
+   "doc": "",
+   "parent": "node",
+   "subtypes": [
+    "DIVIDER"
+   ]
+  },
+  "node.outfall": {
+   "class": "OutfallView",
+   "module": "_nodes",
+   "path": "nodes[].outfall",
+   "doc": "",
+   "parent": "node",
+   "subtypes": [
+    "OUTFALL"
+   ]
+  },
+  "node.stats": {
+   "class": "NodeStatsView",
+   "module": "_nodes",
+   "path": "nodes[].stats",
+   "doc": "",
+   "parent": "node"
+  },
+  "node.storage": {
+   "class": "StorageView",
+   "module": "_nodes",
+   "path": "nodes[].storage",
+   "doc": "",
+   "parent": "node",
+   "subtypes": [
+    "STORAGE"
+   ]
+  },
+  "nodes": {
+   "class": "Nodes",
+   "module": "_nodes",
+   "path": "nodes",
+   "doc": "Indexable, iterable collection of Node wrappers.",
+   "parent": "solver",
+   "element": "node",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index"
+   ]
+  },
+  "options": {
+   "class": "SimulationOptions",
+   "module": "_solver",
+   "path": "options",
+   "doc": "View over the [OPTIONS] block. See Solver.options.",
+   "parent": "solver"
+  },
+  "options.ext": {
+   "class": "_OptionsExtView",
+   "module": "_solver",
+   "path": "options.ext",
+   "doc": "Sub-mapping for the [OPTIONS_EXT] block.",
+   "parent": "options"
+  },
+  "output": {
+   "class": "OutputReader",
+   "module": "_output_reader",
+   "path": "",
+   "doc": "Read a SWMM binary .out file.",
+   "construct": {
+    "via": "new",
+    "args": [
+     "path"
+    ]
+   },
+   "c": [
+    "swmm_output_close",
+    "swmm_output_open",
+    "swmm_output_open_live"
+   ]
+  },
+  "pattern": {
+   "class": "Pattern",
+   "module": "_tables",
+   "path": "patterns[]",
+   "doc": "",
+   "collection": "patterns",
+   "key": "Union[int, str]"
+  },
+  "patterns": {
+   "class": "Patterns",
+   "module": "_tables",
+   "path": "patterns",
+   "doc": "",
+   "parent": "solver",
+   "element": "pattern",
+   "c": [
+    "swmm_pattern_count"
+   ]
+  },
+  "pollutant": {
+   "class": "Pollutant",
+   "module": "_pollutants",
+   "path": "pollutants[]",
+   "doc": "",
+   "collection": "pollutants",
+   "key": "Union[int, str]"
+  },
+  "pollutants": {
+   "class": "Pollutants",
+   "module": "_pollutants",
+   "path": "pollutants",
+   "doc": "",
+   "parent": "solver",
+   "element": "pollutant",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ]
+  },
+  "process_components": {
+   "class": "ProcessComponents",
+   "module": "_process_components",
+   "path": "process_components",
+   "doc": "",
+   "parent": "solver"
+  },
+  "quality": {
+   "class": "Quality",
+   "module": "_quality",
+   "path": "quality",
+   "doc": "",
+   "parent": "solver"
+  },
+  "quality.landuses": {
+   "class": "Landuses",
+   "module": "_quality",
+   "path": "quality.landuses",
+   "doc": "",
+   "parent": "quality",
+   "element": "landuse",
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_index"
+   ]
+  },
+  "reactions": {
+   "class": "Reactions",
+   "module": "_reactions",
+   "path": "reactions",
+   "doc": "",
+   "parent": "solver"
+  },
+  "reactions.coefficients": {
+   "class": "_CoefficientCollection",
+   "module": "_reactions",
+   "path": "reactions.coefficients",
+   "doc": "",
+   "parent": "reactions",
+   "element": "coefficient",
+   "c": [
+    "swmm_reaction_coeff_count"
+   ]
+  },
+  "reactions.initial": {
+   "class": "_InitialQualityRows",
+   "module": "_reactions",
+   "path": "reactions.initial",
+   "doc": "",
+   "parent": "reactions"
+  },
+  "reactions.species": {
+   "class": "_SpeciesCollection",
+   "module": "_reactions",
+   "path": "reactions.species",
+   "doc": "",
+   "parent": "reactions",
+   "element": "species",
+   "c": [
+    "swmm_reaction_species_count"
+   ]
+  },
+  "reactions.terms": {
+   "class": "_TermCollection",
+   "module": "_reactions",
+   "path": "reactions.terms",
+   "doc": "",
+   "parent": "reactions",
+   "element": "term",
+   "c": [
+    "swmm_reaction_term_count"
+   ]
+  },
+  "save_schedule": {
+   "class": "SaveSchedule",
+   "module": "_hotstart",
+   "path": "save_schedule",
+   "doc": "",
+   "parent": "solver"
+  },
+  "snowpacks": {
+   "class": "Snowpacks",
+   "module": "_subcatchments",
+   "path": "snowpacks",
+   "doc": "Name-keyed collection of [SNOWPACKS] entries (solver.snowpacks).",
+   "parent": "solver"
+  },
+  "solver": {
+   "class": "Solver",
+   "module": "_solver",
+   "path": "",
+   "doc": "SWMM engine lifecycle manager."
+  },
+  "spatial": {
+   "class": "Spatial",
+   "module": "_spatial",
+   "path": "spatial",
+   "doc": "",
+   "parent": "solver"
+  },
+  "species": {
+   "class": "ReactionSpecies",
+   "module": "_reactions",
+   "path": "reactions.species[]",
+   "doc": "",
+   "collection": "reactions.species",
+   "key": "Union[int, str]"
+  },
+  "statistics": {
+   "class": "Statistics",
+   "module": "_statistics",
+   "path": "statistics",
+   "doc": "",
+   "parent": "solver"
+  },
+  "subcatchment": {
+   "class": "Subcatchment",
+   "module": "_subcatchments",
+   "path": "subcatchments[]",
+   "doc": "Single-subcatchment wrapper. See Subcatchments.",
+   "collection": "subcatchments",
+   "key": "Union[int, str]"
+  },
+  "subcatchment.coverage": {
+   "class": "CoverageView",
+   "module": "_subcatchments",
+   "path": "subcatchments[].coverage",
+   "doc": "",
+   "parent": "subcatchment"
+  },
+  "subcatchment.infiltration": {
+   "class": "InfiltrationView",
+   "module": "_subcatchments",
+   "path": "subcatchments[].infiltration",
+   "doc": "",
+   "parent": "subcatchment"
+  },
+  "subcatchment.loadings": {
+   "class": "LoadingsView",
+   "module": "_subcatchments",
+   "path": "subcatchments[].loadings",
+   "doc": "Pollutant or species id -> initial buildup on a subcatchment.",
+   "parent": "subcatchment"
+  },
+  "subcatchment.stats": {
+   "class": "SubcatchmentStatsView",
+   "module": "_subcatchments",
+   "path": "subcatchments[].stats",
+   "doc": "",
+   "parent": "subcatchment"
+  },
+  "subcatchments": {
+   "class": "Subcatchments",
+   "module": "_subcatchments",
+   "path": "subcatchments",
+   "doc": "Indexable, iterable collection of Subcatchment wrappers.",
+   "parent": "solver",
+   "element": "subcatchment",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ]
+  },
+  "surface2d": {
+   "class": "Surface2D",
+   "module": "_2d",
+   "path": "surface2d",
+   "doc": "Read/write interface to the optional 2D surface routing module.",
+   "parent": "solver"
+  },
+  "surface2d.groundwater": {
+   "class": "Groundwater",
+   "module": "_groundwater",
+   "path": "surface2d.groundwater",
+   "doc": "",
+   "parent": "surface2d"
+  },
+  "surface2d.groundwater.options": {
+   "class": "AquiferOptions",
+   "module": "_groundwater",
+   "path": "surface2d.groundwater.options",
+   "doc": "Text options using the native INP key/value spellings.",
+   "parent": "surface2d.groundwater"
+  },
+  "surface2d.groundwater.transport": {
+   "class": "GroundwaterTransport",
+   "module": "_gw_transport",
+   "path": "surface2d.groundwater.transport",
+   "doc": "",
+   "parent": "surface2d.groundwater"
+  },
+  "surface2d.groundwater.transport.options": {
+   "class": "GroundwaterTransportOptions",
+   "module": "_gw_transport",
+   "path": "surface2d.groundwater.transport.options",
+   "doc": "Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.",
+   "parent": "surface2d.groundwater.transport"
+  },
+  "surface2d.infiltration": {
+   "class": "Infiltration2DView",
+   "module": "_2d",
+   "path": "surface2d.infiltration",
+   "doc": "surface2d.infiltration — per-cell infiltration on the 2D mesh.",
+   "parent": "surface2d"
+  },
+  "surface2d.infiltration.defaults": {
+   "class": "Infil2DDefaults",
+   "module": "_2d",
+   "path": "surface2d.infiltration.defaults",
+   "doc": "surface2d.infiltration.defaults — tag → Infil2DRow mapping.",
+   "parent": "surface2d.infiltration"
+  },
+  "surface2d.quality": {
+   "class": "SurfaceQuality",
+   "module": "_surface_quality",
+   "path": "surface2d.quality",
+   "doc": "",
+   "parent": "surface2d"
+  },
+  "table": {
+   "class": "_PointTable",
+   "module": "_tables",
+   "path": "tables[]",
+   "doc": "",
+   "collection": "tables",
+   "key": "Union[int, str]"
+  },
+  "tables": {
+   "class": "Tables",
+   "module": "_tables",
+   "path": "tables",
+   "doc": "",
+   "parent": "solver",
+   "element": "table",
+   "c": [
+    "swmm_table_count",
+    "swmm_table_index"
+   ]
+  },
+  "term": {
+   "class": "ReactionTerm",
+   "module": "_reactions",
+   "path": "reactions.terms[]",
+   "doc": "",
+   "collection": "reactions.terms",
+   "key": "Union[int, str]"
+  },
+  "transport": {
+   "class": "Transport",
+   "module": "_transport",
+   "path": "transport",
+   "doc": "",
+   "parent": "solver"
+  },
+  "userflags": {
+   "class": "UserFlags",
+   "module": "_solver",
+   "path": "userflags",
+   "doc": "Typed user-flag mapping. See Solver.userflags.",
+   "parent": "solver"
+  },
+  "water_age": {
+   "class": "WaterAge",
+   "module": "_water_age",
+   "path": "water_age",
+   "doc": "",
+   "parent": "solver"
+  },
+  "water_age.globals": {
+   "class": "_WaterAgeGlobals",
+   "module": "_water_age",
+   "path": "water_age.globals",
+   "doc": "",
+   "parent": "water_age"
+  },
+  "water_age.node_overrides": {
+   "class": "_WaterAgeOverrides",
+   "module": "_water_age",
+   "path": "water_age.node_overrides",
+   "doc": "",
+   "parent": "water_age"
+  },
+  "xsect": {
+   "class": "XSectionGeometry",
+   "module": "_xsect",
+   "path": "",
+   "doc": "Build a section from a shape code and its geometry parameters.",
+   "construct": {
+    "via": "new",
+    "args": [
+     "shape",
+     "geom1",
+     "geom2",
+     "geom3",
+     "geom4",
+     "units"
+    ]
+   },
+   "c": [
+    "swmm_xsect_create",
+    "swmm_xsect_free",
+    "swmm_xsect_shape_name"
+   ]
+  }
+ },
+ "members": [
+  {
+   "path": "aquifers.add",
+   "target": "aquifers",
+   "name": "add",
+   "form": "method",
+   "python": "Aquifers.add",
+   "doc": "Add a new aquifer definition with default (zero) parameters.",
+   "c": [
+    "swmm_aquifer_add",
+    "swmm_aquifer_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.get_evap_pattern",
+   "target": "aquifers",
+   "name": "get_evap_pattern",
+   "form": "method",
+   "python": "Aquifers.get_evap_pattern",
+   "doc": "Get the aquifer's upper-zone evaporation pattern name (empty if none).",
+   "c": [
+    "swmm_aquifer_get_evap_pattern"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "aquifer",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.get_id",
+   "target": "aquifers",
+   "name": "get_id",
+   "form": "method",
+   "python": "Aquifers.get_id",
+   "doc": "Get the string identifier of an aquifer definition by index.",
+   "c": [
+    "swmm_aquifer_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.get_index",
+   "target": "aquifers",
+   "name": "get_index",
+   "form": "method",
+   "python": "Aquifers.get_index",
+   "doc": "Look up an aquifer's zero-based index by its string identifier.",
+   "c": [
+    "swmm_aquifer_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.get_param",
+   "target": "aquifers",
+   "name": "get_param",
+   "form": "method",
+   "python": "Aquifers.get_param",
+   "doc": "Get an aquifer parameter (input-file units).",
+   "c": [
+    "swmm_aquifer_get_param"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "aquifer",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "param",
+     "type": "Union[AquiferParam, int]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.items",
+   "target": "aquifers",
+   "name": "items",
+   "form": "item",
+   "python": "list(Aquifers)",
+   "doc": "Name-keyed collection of [AQUIFERS] entries (solver.aquifers).",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_aquifer_count"
+   ]
+  },
+  {
+   "path": "aquifers.rename",
+   "target": "aquifers",
+   "name": "rename",
+   "form": "method",
+   "python": "Aquifers.rename",
+   "doc": "Rename an aquifer in place.",
+   "c": [
+    "swmm_aquifer_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.set_evap_pattern",
+   "target": "aquifers",
+   "name": "set_evap_pattern",
+   "form": "method",
+   "python": "Aquifers.set_evap_pattern",
+   "doc": "Set or clear the aquifer's upper-zone evaporation pattern name.",
+   "c": [
+    "swmm_aquifer_set_evap_pattern"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "aquifer",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "name",
+     "type": "Optional[str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "aquifers.set_param",
+   "target": "aquifers",
+   "name": "set_param",
+   "form": "method",
+   "python": "Aquifers.set_param",
+   "doc": "Set an aquifer parameter (input-file units).",
+   "c": [
+    "swmm_aquifer_set_param"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "aquifer",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "param",
+     "type": "Union[AquiferParam, int]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_gage",
+   "target": "builder",
+   "name": "add_gage",
+   "form": "method",
+   "python": "ModelBuilder.add_gage",
+   "doc": "Add a rain gage to the model.",
+   "c": [
+    "swmm_gage_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "gage_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_link",
+   "target": "builder",
+   "name": "add_link",
+   "form": "method",
+   "python": "ModelBuilder.add_link",
+   "doc": "Add a link to the model.",
+   "c": [
+    "swmm_link_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "link_type",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_node",
+   "target": "builder",
+   "name": "add_node",
+   "form": "method",
+   "python": "ModelBuilder.add_node",
+   "doc": "Add a node to the model.",
+   "c": [
+    "swmm_node_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "node_type",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_subcatch",
+   "target": "builder",
+   "name": "add_subcatch",
+   "form": "method",
+   "python": "ModelBuilder.add_subcatch",
+   "doc": "Backward-compatible alias for add_subcatchment.",
+   "c": [],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sc_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_subcatchment",
+   "target": "builder",
+   "name": "add_subcatchment",
+   "form": "method",
+   "python": "ModelBuilder.add_subcatchment",
+   "doc": "Add a subcatchment to the model.",
+   "c": [
+    "swmm_subcatch_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sc_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.add_title_line",
+   "target": "builder",
+   "name": "add_title_line",
+   "form": "method",
+   "python": "ModelBuilder.add_title_line",
+   "doc": "Append a new line to the [TITLE] section.",
+   "c": [
+    "swmm_title_add_line"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "line",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.clear_title",
+   "target": "builder",
+   "name": "clear_title",
+   "form": "method",
+   "python": "ModelBuilder.clear_title",
+   "doc": "Remove all lines from the [TITLE] section.",
+   "c": [
+    "swmm_title_clear"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "builder.clear_userflag_value",
+   "target": "builder",
+   "name": "clear_userflag_value",
+   "form": "method",
+   "python": "ModelBuilder.clear_userflag_value",
+   "doc": "Remove the flag value assigned to a specific object (mark unset).",
+   "c": [
+    "swmm_userflag_value_clear"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.define_userflag",
+   "target": "builder",
+   "name": "define_userflag",
+   "form": "method",
+   "python": "ModelBuilder.define_userflag",
+   "doc": "Define (or redefine) a user-flag schema entry ([USER_FLAGS]).",
+   "c": [
+    "swmm_userflag_define"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "type",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "description",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "builder.end_datetime",
+   "target": "builder",
+   "name": "end_datetime",
+   "form": "property",
+   "python": "ModelBuilder.end_datetime",
+   "doc": "Simulation end date/time.",
+   "c": [
+    "swmm_options_get_end_date",
+    "swmm_options_set_end_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "builder.files_get",
+   "target": "builder",
+   "name": "files_get",
+   "form": "method",
+   "python": "ModelBuilder.files_get",
+   "doc": "Read one [FILES] field by key.",
+   "c": [
+    "swmm_files_get"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.files_set",
+   "target": "builder",
+   "name": "files_set",
+   "form": "method",
+   "python": "ModelBuilder.files_set",
+   "doc": "Write one [FILES] field by key.",
+   "c": [
+    "swmm_files_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.finalize",
+   "target": "builder",
+   "name": "finalize",
+   "form": "method",
+   "python": "ModelBuilder.finalize",
+   "doc": "Finalize the model -- build connectivity and allocate arrays.",
+   "c": [
+    "swmm_finalize_model"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "builder.get_crs",
+   "target": "builder",
+   "name": "get_crs",
+   "form": "method",
+   "python": "ModelBuilder.get_crs",
+   "doc": "Return the coordinate reference system string.",
+   "c": [
+    "swmm_get_crs"
+   ],
+   "returns": "str",
+   "params": []
+  },
+  {
+   "path": "builder.get_file_path",
+   "target": "builder",
+   "name": "get_file_path",
+   "form": "method",
+   "python": "ModelBuilder.get_file_path",
+   "doc": "Read an external-file slot's resolved and original paths.",
+   "c": [
+    "swmm_file_path_get"
+   ],
+   "returns": "tuple[str, str]",
+   "params": [
+    {
+     "name": "role",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "owner",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "builder.get_option",
+   "target": "builder",
+   "name": "get_option",
+   "form": "method",
+   "python": "ModelBuilder.get_option",
+   "doc": "Return the value of a model option.",
+   "c": [
+    "swmm_options_get"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_option_ext",
+   "target": "builder",
+   "name": "get_option_ext",
+   "form": "method",
+   "python": "ModelBuilder.get_option_ext",
+   "doc": "Return the value of an extended model option.",
+   "c": [
+    "swmm_options_get_ext"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_title_count",
+   "target": "builder",
+   "name": "get_title_count",
+   "form": "method",
+   "python": "ModelBuilder.get_title_count",
+   "doc": "Return the number of title lines in the [TITLE] section.",
+   "c": [
+    "swmm_title_get_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "builder.get_title_line",
+   "target": "builder",
+   "name": "get_title_line",
+   "form": "method",
+   "python": "ModelBuilder.get_title_line",
+   "doc": "Return a specific title line by zero-based index.",
+   "c": [
+    "swmm_title_get_line"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_userflag_bool",
+   "target": "builder",
+   "name": "get_userflag_bool",
+   "form": "method",
+   "python": "ModelBuilder.get_userflag_bool",
+   "doc": "Return a boolean user flag value.",
+   "c": [
+    "swmm_userflag_get_bool"
+   ],
+   "returns": "bool",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_userflag_def",
+   "target": "builder",
+   "name": "get_userflag_def",
+   "form": "method",
+   "python": "ModelBuilder.get_userflag_def",
+   "doc": "Return a user-flag schema definition by index (insertion order).",
+   "c": [
+    "swmm_userflag_def_get"
+   ],
+   "returns": "tuple[str, int, str]",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_userflag_int",
+   "target": "builder",
+   "name": "get_userflag_int",
+   "form": "method",
+   "python": "ModelBuilder.get_userflag_int",
+   "doc": "Return an integer user flag value.",
+   "c": [
+    "swmm_userflag_get_int"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_userflag_real",
+   "target": "builder",
+   "name": "get_userflag_real",
+   "form": "method",
+   "python": "ModelBuilder.get_userflag_real",
+   "doc": "Return a real-valued user flag.",
+   "c": [
+    "swmm_userflag_get_real"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.get_userflag_value",
+   "target": "builder",
+   "name": "get_userflag_value",
+   "form": "method",
+   "python": "ModelBuilder.get_userflag_value",
+   "doc": "Return the flag value assigned to a specific object, as a string.",
+   "c": [
+    "swmm_userflag_value_get"
+   ],
+   "returns": "Optional[str]",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.plugin_get",
+   "target": "builder",
+   "name": "plugin_get",
+   "form": "method",
+   "python": "ModelBuilder.plugin_get",
+   "doc": "Read one [PLUGINS] row by index.",
+   "c": [
+    "swmm_plugin_get"
+   ],
+   "returns": "tuple[str, str]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.plugin_remove",
+   "target": "builder",
+   "name": "plugin_remove",
+   "form": "method",
+   "python": "ModelBuilder.plugin_remove",
+   "doc": "Remove the [PLUGINS] row matching path_or_id.",
+   "c": [
+    "swmm_plugin_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path_or_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.plugin_set",
+   "target": "builder",
+   "name": "plugin_set",
+   "form": "method",
+   "python": "ModelBuilder.plugin_set",
+   "doc": "Add or replace a [PLUGINS] row keyed by path/id.",
+   "c": [
+    "swmm_plugin_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path_or_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "args",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "builder.plugins_count",
+   "target": "builder",
+   "name": "plugins_count",
+   "form": "method",
+   "python": "ModelBuilder.plugins_count",
+   "doc": "Return the number of [PLUGINS] entries on the engine.",
+   "c": [
+    "swmm_plugins_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "builder.pop_last_link",
+   "target": "builder",
+   "name": "pop_last_link",
+   "form": "method",
+   "python": "ModelBuilder.pop_last_link",
+   "doc": "Remove the most recently added link (undo-of-add).",
+   "c": [
+    "swmm_link_pop_last"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.pop_last_node",
+   "target": "builder",
+   "name": "pop_last_node",
+   "form": "method",
+   "python": "ModelBuilder.pop_last_node",
+   "doc": "Remove the most recently added node (undo-of-add).",
+   "c": [
+    "swmm_node_pop_last"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.report_start_datetime",
+   "target": "builder",
+   "name": "report_start_datetime",
+   "form": "property",
+   "python": "ModelBuilder.report_start_datetime",
+   "doc": "Report start date/time.",
+   "c": [
+    "swmm_options_get_report_start",
+    "swmm_options_set_report_start"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "builder.set_file_path",
+   "target": "builder",
+   "name": "set_file_path",
+   "form": "method",
+   "python": "ModelBuilder.set_file_path",
+   "doc": "Set the original token for an external-file slot.",
+   "c": [
+    "swmm_file_path_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "role",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "new_path",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "owner",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "builder.set_link_length",
+   "target": "builder",
+   "name": "set_link_length",
+   "form": "method",
+   "python": "ModelBuilder.set_link_length",
+   "doc": "Set the length of a conduit link.",
+   "c": [
+    "swmm_link_set_length"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "length",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_link_nodes",
+   "target": "builder",
+   "name": "set_link_nodes",
+   "form": "method",
+   "python": "ModelBuilder.set_link_nodes",
+   "doc": "Set the upstream and downstream nodes for a link.",
+   "c": [
+    "swmm_link_set_nodes"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "from_node",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "to_node",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_link_roughness",
+   "target": "builder",
+   "name": "set_link_roughness",
+   "form": "method",
+   "python": "ModelBuilder.set_link_roughness",
+   "doc": "Set Manning's roughness coefficient for a conduit.",
+   "c": [
+    "swmm_link_set_roughness"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "n",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_link_xsect",
+   "target": "builder",
+   "name": "set_link_xsect",
+   "form": "method",
+   "python": "ModelBuilder.set_link_xsect",
+   "doc": "Set the cross-section geometry of a conduit.",
+   "c": [
+    "swmm_link_set_xsect"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "shape",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "g1",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "g2",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "g3",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "g4",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "builder.set_node_invert",
+   "target": "builder",
+   "name": "set_node_invert",
+   "form": "method",
+   "python": "ModelBuilder.set_node_invert",
+   "doc": "Set the invert elevation of a node.",
+   "c": [
+    "swmm_node_set_invert_elev"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "elev",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_node_max_depth",
+   "target": "builder",
+   "name": "set_node_max_depth",
+   "form": "method",
+   "python": "ModelBuilder.set_node_max_depth",
+   "doc": "Set the maximum depth of a node.",
+   "c": [
+    "swmm_node_set_max_depth"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "depth",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_option",
+   "target": "builder",
+   "name": "set_option",
+   "form": "method",
+   "python": "ModelBuilder.set_option",
+   "doc": "Set a model option.",
+   "c": [
+    "swmm_options_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_option_ext",
+   "target": "builder",
+   "name": "set_option_ext",
+   "form": "method",
+   "python": "ModelBuilder.set_option_ext",
+   "doc": "Set an extended model option.",
+   "c": [
+    "swmm_options_set_ext"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_title",
+   "target": "builder",
+   "name": "set_title",
+   "form": "method",
+   "python": "ModelBuilder.set_title",
+   "doc": "Replace all title lines with new text.",
+   "c": [
+    "swmm_title_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_userflag_bool",
+   "target": "builder",
+   "name": "set_userflag_bool",
+   "form": "method",
+   "python": "ModelBuilder.set_userflag_bool",
+   "doc": "Set a boolean user flag.",
+   "c": [
+    "swmm_userflag_set_bool"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "bool",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_userflag_int",
+   "target": "builder",
+   "name": "set_userflag_int",
+   "form": "method",
+   "python": "ModelBuilder.set_userflag_int",
+   "doc": "Set an integer user flag.",
+   "c": [
+    "swmm_userflag_set_int"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_userflag_real",
+   "target": "builder",
+   "name": "set_userflag_real",
+   "form": "method",
+   "python": "ModelBuilder.set_userflag_real",
+   "doc": "Set a real-valued user flag.",
+   "c": [
+    "swmm_userflag_set_real"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.set_userflag_value",
+   "target": "builder",
+   "name": "set_userflag_value",
+   "form": "method",
+   "python": "ModelBuilder.set_userflag_value",
+   "doc": "Assign a flag value to a specific object from a string.",
+   "c": [
+    "swmm_userflag_value_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.start_datetime",
+   "target": "builder",
+   "name": "start_datetime",
+   "form": "property",
+   "python": "ModelBuilder.start_datetime",
+   "doc": "Simulation start date/time.",
+   "c": [
+    "swmm_options_get_start_date",
+    "swmm_options_set_start_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "builder.to_solver",
+   "target": "builder",
+   "name": "to_solver",
+   "form": "method",
+   "python": "ModelBuilder.to_solver",
+   "doc": "Transfer ownership of the engine handle to a Solver.",
+   "c": [],
+   "returns": "Solver",
+   "params": []
+  },
+  {
+   "path": "builder.undefine_userflag",
+   "target": "builder",
+   "name": "undefine_userflag",
+   "form": "method",
+   "python": "ModelBuilder.undefine_userflag",
+   "doc": "Remove a user-flag definition and all its per-object values.",
+   "c": [
+    "swmm_userflag_undefine"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.userflag_def_count",
+   "target": "builder",
+   "name": "userflag_def_count",
+   "form": "method",
+   "python": "ModelBuilder.userflag_def_count",
+   "doc": "Return the number of user-flag schema definitions.",
+   "c": [
+    "swmm_userflag_def_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "builder.validate",
+   "target": "builder",
+   "name": "validate",
+   "form": "method",
+   "python": "ModelBuilder.validate",
+   "doc": "Validate model topology.",
+   "c": [
+    "swmm_validate_model"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "builder.write",
+   "target": "builder",
+   "name": "write",
+   "form": "method",
+   "python": "ModelBuilder.write",
+   "doc": "Write the model to a SWMM .inp file.",
+   "c": [
+    "swmm_model_write"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "builder.write_with_plugin",
+   "target": "builder",
+   "name": "write_with_plugin",
+   "form": "method",
+   "python": "ModelBuilder.write_with_plugin",
+   "doc": "Write the current model to disk using an output plugin.",
+   "c": [
+    "swmm_model_write_with_plugin"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "output_plugin_id",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "climate.adc_impervious",
+   "target": "climate",
+   "name": "adc_impervious",
+   "form": "property",
+   "python": "Climate.adc_impervious",
+   "doc": "Impervious areal-depletion curve (10 fractions, 0..1).",
+   "c": [
+    "swmm_climate_get_adc_impervious",
+    "swmm_climate_set_adc_impervious"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.adc_pervious",
+   "target": "climate",
+   "name": "adc_pervious",
+   "form": "property",
+   "python": "Climate.adc_pervious",
+   "doc": "Pervious areal-depletion curve (10 fractions, 0..1).",
+   "c": [
+    "swmm_climate_get_adc_pervious",
+    "swmm_climate_set_adc_pervious"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.adjust_conductivity",
+   "target": "climate",
+   "name": "adjust_conductivity",
+   "form": "property",
+   "python": "Climate.adjust_conductivity",
+   "doc": "Twelve monthly hydraulic-conductivity adjustment multipliers (1.0 = none).",
+   "c": [
+    "swmm_climate_get_adjust_conductivity",
+    "swmm_climate_set_adjust_conductivity"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.adjust_evaporation",
+   "target": "climate",
+   "name": "adjust_evaporation",
+   "form": "property",
+   "python": "Climate.adjust_evaporation",
+   "doc": "Twelve monthly evaporation adjustment multipliers (1.0 = none).",
+   "c": [
+    "swmm_climate_get_adjust_evaporation",
+    "swmm_climate_set_adjust_evaporation"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.adjust_rainfall",
+   "target": "climate",
+   "name": "adjust_rainfall",
+   "form": "property",
+   "python": "Climate.adjust_rainfall",
+   "doc": "Twelve monthly rainfall adjustment multipliers (1.0 = none).",
+   "c": [
+    "swmm_climate_get_adjust_rainfall",
+    "swmm_climate_set_adjust_rainfall"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.adjust_temperature",
+   "target": "climate",
+   "name": "adjust_temperature",
+   "form": "property",
+   "python": "Climate.adjust_temperature",
+   "doc": "Twelve monthly temperature adjustment offsets (project temp units).",
+   "c": [
+    "swmm_climate_get_adjust_temperature",
+    "swmm_climate_set_adjust_temperature"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.ati_weight",
+   "target": "climate",
+   "name": "ati_weight",
+   "form": "property",
+   "python": "Climate.ati_weight",
+   "doc": "Antecedent-temperature-index weight (TIPM, 0..1).",
+   "c": [
+    "swmm_climate_get_ati_weight",
+    "swmm_climate_set_ati_weight"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "fraction"
+  },
+  {
+   "path": "climate.elevation",
+   "target": "climate",
+   "name": "elevation",
+   "form": "property",
+   "python": "Climate.elevation",
+   "doc": "Site elevation (project length units).",
+   "c": [
+    "swmm_climate_get_elevation",
+    "swmm_climate_set_elevation"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "climate.evap_monthly",
+   "target": "climate",
+   "name": "evap_monthly",
+   "form": "property",
+   "python": "Climate.evap_monthly",
+   "doc": "Twelve monthly evaporation rates (project evap-rate units).",
+   "c": [
+    "swmm_climate_get_evap_monthly",
+    "swmm_climate_set_evap_monthly"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.evap_recovery",
+   "target": "climate",
+   "name": "evap_recovery",
+   "form": "property",
+   "python": "Climate.evap_recovery",
+   "doc": "Soil-moisture recovery pattern id (empty if none).",
+   "c": [
+    "swmm_climate_get_evap_recovery",
+    "swmm_climate_set_evap_recovery"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "climate.evap_timeseries",
+   "target": "climate",
+   "name": "evap_timeseries",
+   "form": "property",
+   "python": "Climate.evap_timeseries",
+   "doc": "Evaporation time-series id (empty if none).",
+   "c": [
+    "swmm_climate_get_evap_timeseries",
+    "swmm_climate_set_evap_timeseries"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "climate.evap_type",
+   "target": "climate",
+   "name": "evap_type",
+   "form": "property",
+   "python": "Climate.evap_type",
+   "doc": "Evaporation method: 0=CONSTANT,1=MONTHLY,2=TIMESERIES,3=TEMPERATURE,4=FILE.",
+   "c": [
+    "swmm_climate_get_evap_type",
+    "swmm_climate_set_evap_type"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "climate.humidity_monthly",
+   "target": "climate",
+   "name": "humidity_monthly",
+   "form": "property",
+   "python": "Climate.humidity_monthly",
+   "doc": "Twelve monthly humidity values (RH % or dew point per humidity_variable).",
+   "c": [
+    "swmm_climate_get_humidity_monthly",
+    "swmm_climate_set_humidity_monthly"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.humidity_timeseries",
+   "target": "climate",
+   "name": "humidity_timeseries",
+   "form": "property",
+   "python": "Climate.humidity_timeseries",
+   "doc": "Humidity time-series id (empty if none). Setting it selects TIMESERIES.",
+   "c": [
+    "swmm_climate_get_humidity_timeseries",
+    "swmm_climate_set_humidity_timeseries"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "climate.humidity_type",
+   "target": "climate",
+   "name": "humidity_type",
+   "form": "property",
+   "python": "Climate.humidity_type",
+   "doc": "Humidity source: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES.",
+   "c": [
+    "swmm_climate_get_humidity_type",
+    "swmm_climate_set_humidity_type"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "climate.humidity_variable",
+   "target": "climate",
+   "name": "humidity_variable",
+   "form": "property",
+   "python": "Climate.humidity_variable",
+   "doc": "Humidity quantity: 0=RELATIVE (%), 1=DEWPOINT (project temperature units).",
+   "c": [
+    "swmm_climate_get_humidity_variable",
+    "swmm_climate_set_humidity_variable"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "climate.latitude",
+   "target": "climate",
+   "name": "latitude",
+   "form": "property",
+   "python": "Climate.latitude",
+   "doc": "Site latitude (degrees, -90..90).",
+   "c": [
+    "swmm_climate_get_latitude",
+    "swmm_climate_set_latitude"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "deg"
+  },
+  {
+   "path": "climate.longitude_correction",
+   "target": "climate",
+   "name": "longitude_correction",
+   "form": "property",
+   "python": "Climate.longitude_correction",
+   "doc": "Longitude/solar-time correction (minutes; 0 = true solar time).",
+   "c": [
+    "swmm_climate_get_longitude_correction",
+    "swmm_climate_set_longitude_correction"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "min"
+  },
+  {
+   "path": "climate.neg_melt_ratio",
+   "target": "climate",
+   "name": "neg_melt_ratio",
+   "form": "property",
+   "python": "Climate.neg_melt_ratio",
+   "doc": "Negative-melt-coefficient ratio (RNM, 0..1).",
+   "c": [
+    "swmm_climate_get_neg_melt_ratio",
+    "swmm_climate_set_neg_melt_ratio"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "fraction"
+  },
+  {
+   "path": "climate.pan_coeff",
+   "target": "climate",
+   "name": "pan_coeff",
+   "form": "property",
+   "python": "Climate.pan_coeff",
+   "doc": "Twelve monthly pan coefficients (used with the FILE method).",
+   "c": [
+    "swmm_climate_get_pan_coeff",
+    "swmm_climate_set_pan_coeff"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.snow_temp",
+   "target": "climate",
+   "name": "snow_temp",
+   "form": "property",
+   "python": "Climate.snow_temp",
+   "doc": "Snow/rain dividing temperature (project temperature units).",
+   "c": [
+    "swmm_climate_get_snow_temp",
+    "swmm_climate_set_snow_temp"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "temperature"
+  },
+  {
+   "path": "climate.temp_file_start",
+   "target": "climate",
+   "name": "temp_file_start",
+   "form": "property",
+   "python": "Climate.temp_file_start",
+   "doc": "Climate-file start date (DateTime decimal days; 0 = file start).",
+   "c": [
+    "swmm_climate_get_temp_file_start",
+    "swmm_climate_set_temp_file_start"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "datetime"
+  },
+  {
+   "path": "climate.temp_source",
+   "target": "climate",
+   "name": "temp_source",
+   "form": "property",
+   "python": "Climate.temp_source",
+   "doc": "Air-temperature source: 0=NONE, 1=TIMESERIES, 2=FILE.",
+   "c": [
+    "swmm_climate_get_temp_source",
+    "swmm_climate_set_temp_source"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "climate.temp_timeseries",
+   "target": "climate",
+   "name": "temp_timeseries",
+   "form": "property",
+   "python": "Climate.temp_timeseries",
+   "doc": "Temperature time-series id (empty if none).",
+   "c": [
+    "swmm_climate_get_temp_timeseries",
+    "swmm_climate_set_temp_timeseries"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "climate.temp_units",
+   "target": "climate",
+   "name": "temp_units",
+   "form": "property",
+   "python": "Climate.temp_units",
+   "doc": "Climate-file temperature units: 0=tenths-degC (C10), 1=degC, 2=degF; -1 = unspecified (reader's per-format default).",
+   "c": [
+    "swmm_climate_get_temp_units",
+    "swmm_climate_set_temp_units"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "climate.wind_monthly",
+   "target": "climate",
+   "name": "wind_monthly",
+   "form": "property",
+   "python": "Climate.wind_monthly",
+   "doc": "Twelve monthly average wind speeds (project wind-speed units).",
+   "c": [
+    "swmm_climate_get_wind_monthly",
+    "swmm_climate_set_wind_monthly"
+   ],
+   "type": "List[float]",
+   "access": "rw"
+  },
+  {
+   "path": "climate.wind_type",
+   "target": "climate",
+   "name": "wind_type",
+   "form": "property",
+   "python": "Climate.wind_type",
+   "doc": "Wind-speed source: 0=MONTHLY, 1=FILE.",
+   "c": [
+    "swmm_climate_get_wind_type",
+    "swmm_climate_set_wind_type"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "close",
+   "target": "solver",
+   "name": "close",
+   "form": "method",
+   "python": "Solver.close",
+   "doc": "Close all files; transition to CLOSED. Idempotent.",
+   "c": [
+    "swmm_engine_close"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "close_runoff_interface",
+   "target": "solver",
+   "name": "close_runoff_interface",
+   "form": "method",
+   "python": "Solver.close_runoff_interface",
+   "doc": "Close the runoff interface file. Idempotent.",
+   "c": [
+    "swmm_runoff_iface_close"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "coefficient.index",
+   "target": "coefficient",
+   "name": "index",
+   "form": "property",
+   "python": "ReactionCoefficient.index",
+   "doc": "Zero-based position in [REACTION_COEFFICIENTS].",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "coefficient.is_param",
+   "target": "coefficient",
+   "name": "is_param",
+   "form": "property",
+   "python": "ReactionCoefficient.is_param",
+   "doc": "True for a PARAMETER (pipe/tank-overridable), False for a CONSTANT.",
+   "c": [
+    "swmm_reaction_coeff_get"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "coefficient.name",
+   "target": "coefficient",
+   "name": "name",
+   "form": "property",
+   "python": "ReactionCoefficient.name",
+   "doc": "Coefficient name as referenced from expressions.",
+   "c": [
+    "swmm_reaction_coeff_get"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "coefficient.value",
+   "target": "coefficient",
+   "name": "value",
+   "form": "property",
+   "python": "ReactionCoefficient.value",
+   "doc": "Current numeric value, in whatever units the expressions imply.",
+   "c": [
+    "swmm_reaction_coeff_get",
+    "swmm_reaction_coeff_set_value"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "user_defined"
+  },
+  {
+   "path": "controls.append",
+   "target": "controls",
+   "name": "append",
+   "form": "method",
+   "python": "Controls.append",
+   "doc": "Append a control rule parsed from *value* (an INP RULE block or rule mapping).",
+   "c": [
+    "swmm_control_add_rule"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "controls.clear",
+   "target": "controls",
+   "name": "clear",
+   "form": "method",
+   "python": "Controls.clear",
+   "doc": "Remove all control rules from the model.",
+   "c": [
+    "swmm_control_clear_rules"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "target": "controls",
+   "form": "item",
+   "python": "Controls[]",
+   "doc": "",
+   "path": "controls.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_control_remove_rule"
+   ]
+  },
+  {
+   "path": "controls.find_references",
+   "target": "controls",
+   "name": "find_references",
+   "form": "method",
+   "python": "Controls.find_references",
+   "doc": "Return the indices of control rules that reference *object_name*.",
+   "c": [
+    "swmm_control_find_references"
+   ],
+   "returns": "list[int]",
+   "params": [
+    {
+     "name": "object_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "controls",
+   "form": "item",
+   "python": "Controls[]",
+   "doc": "",
+   "path": "controls.get_item",
+   "name": "get_item",
+   "returns": "ControlRule",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_control_get_id",
+    "swmm_control_get_rule"
+   ]
+  },
+  {
+   "path": "controls.insert",
+   "target": "controls",
+   "name": "insert",
+   "form": "method",
+   "python": "Controls.insert",
+   "doc": "Insert *value* at *idx* (emulated via clear + re-add; the C rule API is append-only).",
+   "c": [],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "controls",
+   "form": "item",
+   "python": "Controls[]",
+   "doc": "",
+   "path": "controls.items",
+   "name": "items",
+   "returns": "list[tuple[int, ControlRule]]",
+   "params": [],
+   "c": [
+    "swmm_control_count",
+    "swmm_control_get_id",
+    "swmm_control_get_rule"
+   ]
+  },
+  {
+   "path": "controls.remove_rule",
+   "target": "controls",
+   "name": "remove_rule",
+   "form": "method",
+   "python": "Controls.remove_rule",
+   "doc": "Remove a single control rule by index.",
+   "c": [
+    "swmm_control_remove_rule"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "controls",
+   "form": "item",
+   "python": "Controls[]",
+   "doc": "",
+   "path": "controls.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "ControlRule",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "path": "controls.set_link_setting",
+   "target": "controls",
+   "name": "set_link_setting",
+   "form": "method",
+   "python": "Controls.set_link_setting",
+   "doc": "Set the control setting for a link by id or index.",
+   "c": [
+    "swmm_control_set_link_setting",
+    "swmm_link_count",
+    "swmm_link_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "setting",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "controls.set_link_status",
+   "target": "controls",
+   "name": "set_link_status",
+   "form": "method",
+   "python": "Controls.set_link_status",
+   "doc": "Set the open/closed status of a link.",
+   "c": [
+    "swmm_control_set_link_status",
+    "swmm_link_count",
+    "swmm_link_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "closed",
+     "type": "bool",
+     "required": true,
+     "keyword_only": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "controls.validate_message",
+   "target": "controls",
+   "name": "validate_message",
+   "form": "method",
+   "python": "Controls.validate_message",
+   "doc": "Validate a control rule without adding it, returning diagnostics.",
+   "c": [
+    "swmm_control_validate_rule"
+   ],
+   "returns": "Tuple[bool, str]",
+   "params": [
+    {
+     "name": "rule_text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "create",
+   "target": "solver",
+   "name": "create",
+   "form": "method",
+   "python": "Solver.create",
+   "doc": "Allocate the engine handle. Usually called implicitly by open or the context manager.",
+   "c": [
+    "swmm_engine_create"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "crs",
+   "target": "solver",
+   "name": "crs",
+   "form": "property",
+   "python": "Solver.crs",
+   "doc": "Coordinate reference system string from [OPTIONS].",
+   "c": [
+    "swmm_get_crs"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "current_datetime",
+   "target": "solver",
+   "name": "current_datetime",
+   "form": "property",
+   "python": "Solver.current_datetime",
+   "doc": "Current simulation datetime.datetime.",
+   "c": [],
+   "type": "datetime",
+   "access": "r"
+  },
+  {
+   "path": "destroy",
+   "target": "solver",
+   "name": "destroy",
+   "form": "method",
+   "python": "Solver.destroy",
+   "doc": "Destroy the engine handle. Idempotent.",
+   "c": [
+    "swmm_engine_destroy"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "editor.analyze_aquifer_impact",
+   "target": "editor",
+   "name": "analyze_aquifer_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_aquifer_impact",
+   "doc": "Preview which subcatchments reference an aquifer.",
+   "c": [
+    "swmm_aquifer_analyze_impact",
+    "swmm_aquifer_index",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_gage_impact",
+   "target": "editor",
+   "name": "analyze_gage_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_gage_impact",
+   "doc": "Preview which objects reference a rain gage.",
+   "c": [
+    "swmm_gage_analyze_impact",
+    "swmm_gage_index",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_hydrograph_impact",
+   "target": "editor",
+   "name": "analyze_hydrograph_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_hydrograph_impact",
+   "doc": "Preview which objects reference a unit-hydrograph group by name.",
+   "c": [
+    "swmm_hydrograph_analyze_impact",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_inlet_impact",
+   "target": "editor",
+   "name": "analyze_inlet_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_inlet_impact",
+   "doc": "Preview which inlet-usage rows reference an inlet design.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_inlet_analyze_impact",
+    "swmm_inlet_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_landuse_impact",
+   "target": "editor",
+   "name": "analyze_landuse_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_landuse_impact",
+   "doc": "Preview which objects reference a land use.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_landuse_analyze_impact",
+    "swmm_landuse_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_lid_impact",
+   "target": "editor",
+   "name": "analyze_lid_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_lid_impact",
+   "doc": "Preview which LID-usage rows reference a LID control.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_lid_analyze_impact",
+    "swmm_lid_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_link_impact",
+   "target": "editor",
+   "name": "analyze_link_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_link_impact",
+   "doc": "Preview which objects reference a link, without deleting it.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_link_analyze_impact",
+    "swmm_link_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_node_impact",
+   "target": "editor",
+   "name": "analyze_node_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_node_impact",
+   "doc": "Preview which objects reference a node, without deleting it.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_node_analyze_impact",
+    "swmm_node_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_pattern_impact",
+   "target": "editor",
+   "name": "analyze_pattern_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_pattern_impact",
+   "doc": "Preview which objects reference a time pattern, without deleting it.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_pattern_analyze_impact",
+    "swmm_pattern_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_pollutant_impact",
+   "target": "editor",
+   "name": "analyze_pollutant_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_pollutant_impact",
+   "doc": "Preview which objects reference a pollutant, without deleting it.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_pollutant_analyze_impact",
+    "swmm_pollutant_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_snowpack_impact",
+   "target": "editor",
+   "name": "analyze_snowpack_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_snowpack_impact",
+   "doc": "Preview which subcatchments reference a snowpack.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_snowpack_analyze_impact",
+    "swmm_snowpack_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_street_impact",
+   "target": "editor",
+   "name": "analyze_street_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_street_impact",
+   "doc": "Preview which inlet-usage rows reference a street.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_street_analyze_impact",
+    "swmm_street_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_subcatch_impact",
+   "target": "editor",
+   "name": "analyze_subcatch_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_subcatch_impact",
+   "doc": "Preview which objects reference a subcatchment.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_subcatch_analyze_impact",
+    "swmm_subcatch_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_table_impact",
+   "target": "editor",
+   "name": "analyze_table_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_table_impact",
+   "doc": "Preview which objects reference a time series or curve.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_table_analyze_impact",
+    "swmm_table_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.analyze_transect_impact",
+   "target": "editor",
+   "name": "analyze_transect_impact",
+   "form": "method",
+   "python": "ModelEditor.analyze_transect_impact",
+   "doc": "Preview which links reference a transect.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_transect_analyze_impact"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.convert_link",
+   "target": "editor",
+   "name": "convert_link",
+   "form": "method",
+   "python": "ModelEditor.convert_link",
+   "doc": "Convert a link to a different type in place.",
+   "c": [
+    "swmm_conversion_result_free",
+    "swmm_link_convert",
+    "swmm_link_index"
+   ],
+   "returns": "ConversionResult",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "new_type",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.convert_node",
+   "target": "editor",
+   "name": "convert_node",
+   "form": "method",
+   "python": "ModelEditor.convert_node",
+   "doc": "Convert a node to a different type in place.",
+   "c": [
+    "swmm_conversion_result_free",
+    "swmm_node_convert",
+    "swmm_node_index"
+   ],
+   "returns": "ConversionResult",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "new_type",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_aquifer",
+   "target": "editor",
+   "name": "delete_aquifer",
+   "form": "method",
+   "python": "ModelEditor.delete_aquifer",
+   "doc": "Delete an aquifer; referencing subcatchments lose their groundwater.",
+   "c": [
+    "swmm_aquifer_delete",
+    "swmm_aquifer_index",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_gage",
+   "target": "editor",
+   "name": "delete_gage",
+   "form": "method",
+   "python": "ModelEditor.delete_gage",
+   "doc": "Delete a rain gage and nullify subcatchment gage references.",
+   "c": [
+    "swmm_gage_delete",
+    "swmm_gage_index",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_gages",
+   "target": "editor",
+   "name": "delete_gages",
+   "form": "method",
+   "python": "ModelEditor.delete_gages",
+   "doc": "Delete a batch using pre-edit names/indices; validate all before mutation.",
+   "c": [
+    "swmm_gage_delete_many",
+    "swmm_gage_index",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "keys",
+     "type": "Iterable[int | str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_hydrograph",
+   "target": "editor",
+   "name": "delete_hydrograph",
+   "form": "method",
+   "python": "ModelEditor.delete_hydrograph",
+   "doc": "Delete a unit-hydrograph group by name.",
+   "c": [
+    "swmm_hydrograph_delete",
+    "swmm_impact_report_free"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_inlet",
+   "target": "editor",
+   "name": "delete_inlet",
+   "form": "method",
+   "python": "ModelEditor.delete_inlet",
+   "doc": "Delete an inlet design; cascade-delete referencing inlet-usage rows.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_inlet_delete",
+    "swmm_inlet_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_landuse",
+   "target": "editor",
+   "name": "delete_landuse",
+   "form": "method",
+   "python": "ModelEditor.delete_landuse",
+   "doc": "Delete a land use; re-pack buildup/washoff and coverage columns.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_landuse_delete",
+    "swmm_landuse_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_lid",
+   "target": "editor",
+   "name": "delete_lid",
+   "form": "method",
+   "python": "ModelEditor.delete_lid",
+   "doc": "Delete a LID control; cascade-delete referencing LID-usage rows.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_lid_delete",
+    "swmm_lid_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_link",
+   "target": "editor",
+   "name": "delete_link",
+   "form": "method",
+   "python": "ModelEditor.delete_link",
+   "doc": "Delete a link and cascade-delete or nullify referencing objects.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_link_delete",
+    "swmm_link_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_links",
+   "target": "editor",
+   "name": "delete_links",
+   "form": "method",
+   "python": "ModelEditor.delete_links",
+   "doc": "Delete a batch using pre-edit names/indices; validate all before mutation.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_link_delete_many",
+    "swmm_link_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "keys",
+     "type": "Iterable[int | str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_node",
+   "target": "editor",
+   "name": "delete_node",
+   "form": "method",
+   "python": "ModelEditor.delete_node",
+   "doc": "Delete a node and cascade-delete or nullify all referencing objects.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_node_delete",
+    "swmm_node_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_nodes",
+   "target": "editor",
+   "name": "delete_nodes",
+   "form": "method",
+   "python": "ModelEditor.delete_nodes",
+   "doc": "Delete a batch using pre-edit names/indices; validate all before mutation.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_node_delete_many",
+    "swmm_node_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "keys",
+     "type": "Iterable[int | str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_pattern",
+   "target": "editor",
+   "name": "delete_pattern",
+   "form": "method",
+   "python": "ModelEditor.delete_pattern",
+   "doc": "Delete a time pattern and clear all name-based references.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_pattern_delete",
+    "swmm_pattern_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_pollutant",
+   "target": "editor",
+   "name": "delete_pollutant",
+   "form": "method",
+   "python": "ModelEditor.delete_pollutant",
+   "doc": "Delete a pollutant and re-pack every per-pollutant matrix.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_pollutant_delete",
+    "swmm_pollutant_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_snowpack",
+   "target": "editor",
+   "name": "delete_snowpack",
+   "form": "method",
+   "python": "ModelEditor.delete_snowpack",
+   "doc": "Delete a snowpack; clear referencing subcatchments and renumber.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_snowpack_delete",
+    "swmm_snowpack_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_street",
+   "target": "editor",
+   "name": "delete_street",
+   "form": "method",
+   "python": "ModelEditor.delete_street",
+   "doc": "Delete a street; cascade-delete referencing inlet-usage rows.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_street_delete",
+    "swmm_street_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_subcatch",
+   "target": "editor",
+   "name": "delete_subcatch",
+   "form": "method",
+   "python": "ModelEditor.delete_subcatch",
+   "doc": "Delete a subcatchment and nullify referencing objects.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_subcatch_delete",
+    "swmm_subcatch_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_subcatchments",
+   "target": "editor",
+   "name": "delete_subcatchments",
+   "form": "method",
+   "python": "ModelEditor.delete_subcatchments",
+   "doc": "Delete a batch using pre-edit names/indices; validate all before mutation.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_subcatch_delete_many",
+    "swmm_subcatch_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "keys",
+     "type": "Iterable[int | str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_table",
+   "target": "editor",
+   "name": "delete_table",
+   "form": "method",
+   "python": "ModelEditor.delete_table",
+   "doc": "Delete a time series or curve and nullify all referencing objects.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_table_delete",
+    "swmm_table_index"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.delete_transect",
+   "target": "editor",
+   "name": "delete_transect",
+   "form": "method",
+   "python": "ModelEditor.delete_transect",
+   "doc": "Delete a transect and reset referencing conduit cross-sections.",
+   "c": [
+    "swmm_impact_report_free",
+    "swmm_transect_delete"
+   ],
+   "returns": "list[ImpactEntry]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.end_datetime",
+   "target": "editor",
+   "name": "end_datetime",
+   "form": "property",
+   "python": "ModelEditor.end_datetime",
+   "doc": "Simulation end date/time.",
+   "c": [
+    "swmm_options_get_end_date",
+    "swmm_options_set_end_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "editor.fuse_inlet_junction",
+   "target": "editor",
+   "name": "fuse_inlet_junction",
+   "form": "method",
+   "python": "ModelEditor.fuse_inlet_junction",
+   "doc": "Re-fuse the two conduits of an inlet junction into one.",
+   "c": [
+    "swmm_inlet_junction_fuse",
+    "swmm_node_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.fuse_virtual_junction",
+   "target": "editor",
+   "name": "fuse_virtual_junction",
+   "form": "method",
+   "python": "ModelEditor.fuse_virtual_junction",
+   "doc": "Re-fuse the two conduits of a virtual junction into one.",
+   "c": [
+    "swmm_node_index",
+    "swmm_virtual_junction_fuse"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.gage_count",
+   "target": "editor",
+   "name": "gage_count",
+   "form": "property",
+   "python": "ModelEditor.gage_count",
+   "doc": "Current number of rain gages in the model.",
+   "c": [
+    "swmm_gage_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "editor.link_count",
+   "target": "editor",
+   "name": "link_count",
+   "form": "property",
+   "python": "ModelEditor.link_count",
+   "doc": "Current number of links in the model.",
+   "c": [
+    "swmm_link_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "editor.node_count",
+   "target": "editor",
+   "name": "node_count",
+   "form": "property",
+   "python": "ModelEditor.node_count",
+   "doc": "Current number of nodes in the model.",
+   "c": [
+    "swmm_node_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "editor.report_start_datetime",
+   "target": "editor",
+   "name": "report_start_datetime",
+   "form": "property",
+   "python": "ModelEditor.report_start_datetime",
+   "doc": "Report start date/time.",
+   "c": [
+    "swmm_options_get_report_start",
+    "swmm_options_set_report_start"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "editor.set_node_inlet",
+   "target": "editor",
+   "name": "set_node_inlet",
+   "form": "method",
+   "python": "ModelEditor.set_node_inlet",
+   "doc": "Promote a node to an inlet junction, or demote it back.",
+   "c": [
+    "swmm_node_index",
+    "swmm_node_set_inlet"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "make_inlet",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "editor.set_node_virtual",
+   "target": "editor",
+   "name": "set_node_virtual",
+   "form": "method",
+   "python": "ModelEditor.set_node_virtual",
+   "doc": "Set or clear a node's virtual-junction flag.",
+   "c": [
+    "swmm_node_index",
+    "swmm_node_set_virtual"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "make_virtual",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "editor.split_conduit",
+   "target": "editor",
+   "name": "split_conduit",
+   "form": "method",
+   "python": "ModelEditor.split_conduit",
+   "doc": "Split a conduit at normalized position t, inserting a new node.",
+   "c": [
+    "swmm_conduit_split",
+    "swmm_link_index"
+   ],
+   "returns": "tuple[int, int]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "t",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "new_node_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "new_link_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "make_virtual",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "editor.split_conduit_inlet",
+   "target": "editor",
+   "name": "split_conduit_inlet",
+   "form": "method",
+   "python": "ModelEditor.split_conduit_inlet",
+   "doc": "Split a street conduit, inserting an inlet junction.",
+   "c": [
+    "swmm_conduit_split_inlet",
+    "swmm_link_index"
+   ],
+   "returns": "tuple[int, int]",
+   "params": [
+    {
+     "name": "id_or_idx",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "t",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "new_node_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "new_link_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "inlet_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "capture_node",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "editor.start_datetime",
+   "target": "editor",
+   "name": "start_datetime",
+   "form": "property",
+   "python": "ModelEditor.start_datetime",
+   "doc": "Simulation start date/time.",
+   "c": [
+    "swmm_options_get_start_date",
+    "swmm_options_set_start_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "editor.subcatch_count",
+   "target": "editor",
+   "name": "subcatch_count",
+   "form": "property",
+   "python": "ModelEditor.subcatch_count",
+   "doc": "Current number of subcatchments in the model.",
+   "c": [
+    "swmm_subcatch_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "editor.table_count",
+   "target": "editor",
+   "name": "table_count",
+   "form": "property",
+   "python": "ModelEditor.table_count",
+   "doc": "Current number of tables (time series + curves) in the model.",
+   "c": [
+    "swmm_table_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "effective_threads",
+   "target": "solver",
+   "name": "effective_threads",
+   "form": "method",
+   "python": "Solver.effective_threads",
+   "doc": "Thread team sizes for this model; zero requests automatic selection.",
+   "c": [
+    "swmm_get_effective_threads"
+   ],
+   "returns": "EffectiveThreads",
+   "params": [
+    {
+     "name": "requested",
+     "type": "int",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "elapsed",
+   "target": "solver",
+   "name": "elapsed",
+   "form": "property",
+   "python": "Solver.elapsed",
+   "doc": "Elapsed simulation time after the last step / stride, as a timedelta.",
+   "c": [],
+   "type": "timedelta",
+   "access": "r"
+  },
+  {
+   "path": "end",
+   "target": "solver",
+   "name": "end",
+   "form": "method",
+   "python": "Solver.end",
+   "doc": "End the simulation; transition to ENDED.",
+   "c": [
+    "swmm_engine_end"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "end_datetime",
+   "target": "solver",
+   "name": "end_datetime",
+   "form": "property",
+   "python": "Solver.end_datetime",
+   "doc": "Simulation end datetime.datetime.",
+   "c": [
+    "swmm_options_get_end_date",
+    "swmm_options_set_end_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "event_count",
+   "target": "solver",
+   "name": "event_count",
+   "form": "property",
+   "python": "Solver.event_count",
+   "doc": "Number of [EVENTS] entries defined on the model.",
+   "c": [
+    "swmm_get_event_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "events.append",
+   "target": "events",
+   "name": "append",
+   "form": "method",
+   "python": "EventsView.append",
+   "doc": "Append a reporting / hot-start event *value*.",
+   "c": [
+    "swmm_events_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "events.clear",
+   "target": "events",
+   "name": "clear",
+   "form": "method",
+   "python": "EventsView.clear",
+   "doc": "Remove all scheduled events.",
+   "c": [
+    "swmm_events_clear"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "target": "events",
+   "form": "item",
+   "python": "EventsView[]",
+   "doc": "[EVENTS] block as a MutableSequence. See Solver.events.",
+   "path": "events.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_events_remove"
+   ]
+  },
+  {
+   "target": "events",
+   "form": "item",
+   "python": "EventsView[]",
+   "doc": "[EVENTS] block as a MutableSequence. See Solver.events.",
+   "path": "events.get_item",
+   "name": "get_item",
+   "returns": "Event",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_events_get"
+   ]
+  },
+  {
+   "path": "events.insert",
+   "target": "events",
+   "name": "insert",
+   "form": "method",
+   "python": "EventsView.insert",
+   "doc": "Insert *value* at *idx* (emulated via clear + re-add; the C event API is append-only).",
+   "c": [],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "events",
+   "form": "item",
+   "python": "EventsView[]",
+   "doc": "[EVENTS] block as a MutableSequence. See Solver.events.",
+   "path": "events.items",
+   "name": "items",
+   "returns": "list[tuple[int, Event]]",
+   "params": [],
+   "c": [
+    "swmm_events_count",
+    "swmm_events_get"
+   ]
+  },
+  {
+   "target": "events",
+   "form": "item",
+   "python": "EventsView[]",
+   "doc": "[EVENTS] block as a MutableSequence. See Solver.events.",
+   "path": "events.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Event",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_events_set"
+   ]
+  },
+  {
+   "path": "flow_units",
+   "target": "solver",
+   "name": "flow_units",
+   "form": "property",
+   "python": "Solver.flow_units",
+   "doc": "solver.flow_units — the model's flow-unit system.",
+   "c": [
+    "swmm_get_flow_units"
+   ],
+   "type": "FlowUnits",
+   "access": "r"
+  },
+  {
+   "path": "forcing.clear",
+   "target": "forcing",
+   "name": "clear",
+   "form": "method",
+   "python": "Forcing.clear",
+   "doc": "Clear all forcing channels on one object.",
+   "c": [
+    "swmm_forcing_clear",
+    "swmm_gage_count",
+    "swmm_gage_index",
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "target",
+     "type": "ForcingTarget",
+     "required": true
+    },
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.clear_all",
+   "target": "forcing",
+   "name": "clear_all",
+   "form": "method",
+   "python": "Forcing.clear_all",
+   "doc": "Clear all active runtime forcing overrides.",
+   "c": [
+    "swmm_forcing_clear_all"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "forcing.climate_dry_only",
+   "target": "forcing",
+   "name": "climate_dry_only",
+   "form": "method",
+   "python": "Forcing.climate_dry_only",
+   "doc": "Set the evaporation DRY_ONLY option at runtime.",
+   "c": [
+    "swmm_climate_set_dry_only"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "flag",
+     "type": "bool",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.climate_evap",
+   "target": "forcing",
+   "name": "climate_evap",
+   "form": "method",
+   "python": "Forcing.climate_evap",
+   "doc": "Prescribe the system-wide evaporation rate.",
+   "c": [
+    "swmm_forcing_climate_evap"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.climate_evap_rate",
+   "target": "forcing",
+   "name": "climate_evap_rate",
+   "form": "method",
+   "python": "Forcing.climate_evap_rate",
+   "doc": "Return the current climate-derived evaporation rate.",
+   "c": [
+    "swmm_climate_get_evap_rate"
+   ],
+   "returns": "float",
+   "params": []
+  },
+  {
+   "path": "forcing.climate_temperature",
+   "target": "forcing",
+   "name": "climate_temperature",
+   "form": "method",
+   "python": "Forcing.climate_temperature",
+   "doc": "Prescribe the air temperature used for snowmelt and temperature-derived evaporation.",
+   "c": [
+    "swmm_forcing_climate_temperature"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.climate_wind",
+   "target": "forcing",
+   "name": "climate_wind",
+   "form": "method",
+   "python": "Forcing.climate_wind",
+   "doc": "Prescribe the wind speed used in rain-on-snow melt.",
+   "c": [
+    "swmm_forcing_climate_wind"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.element_climate",
+   "target": "forcing",
+   "name": "element_climate",
+   "form": "method",
+   "python": "Forcing.element_climate",
+   "doc": "Force local air temperature, humidity, wind or shortwave climate.",
+   "c": [
+    "swmm_forcing_element_climate",
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "kind",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "element",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.element_climate_get",
+   "target": "forcing",
+   "name": "element_climate_get",
+   "form": "method",
+   "python": "Forcing.element_climate_get",
+   "doc": "Return (value, mode), with mode None when no override is present.",
+   "c": [
+    "swmm_forcing_element_climate_get",
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "tuple[float, ForcingMode | None]",
+   "params": [
+    {
+     "name": "kind",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "element",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.gage_rainfall",
+   "target": "forcing",
+   "name": "gage_rainfall",
+   "form": "method",
+   "python": "Forcing.gage_rainfall",
+   "doc": "Force the rainfall rate reported by rain *gage* for the current step (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_gage_rainfall",
+    "swmm_gage_count",
+    "swmm_gage_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "gage",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.get_climate_dry_only",
+   "target": "forcing",
+   "name": "get_climate_dry_only",
+   "form": "method",
+   "python": "Forcing.get_climate_dry_only",
+   "doc": "Return the evaporation DRY_ONLY option.",
+   "c": [
+    "swmm_climate_get_dry_only"
+   ],
+   "returns": "bool",
+   "params": []
+  },
+  {
+   "path": "forcing.get_climate_temperature",
+   "target": "forcing",
+   "name": "get_climate_temperature",
+   "form": "method",
+   "python": "Forcing.get_climate_temperature",
+   "doc": "Return the current air temperature (read-only).",
+   "c": [
+    "swmm_climate_get_temperature"
+   ],
+   "returns": "float",
+   "params": []
+  },
+  {
+   "path": "forcing.get_climate_wind_speed",
+   "target": "forcing",
+   "name": "get_climate_wind_speed",
+   "form": "method",
+   "python": "Forcing.get_climate_wind_speed",
+   "doc": "Return the current wind speed (read-only).",
+   "c": [
+    "swmm_climate_get_wind_speed"
+   ],
+   "returns": "float",
+   "params": []
+  },
+  {
+   "path": "forcing.link_flow",
+   "target": "forcing",
+   "name": "link_flow",
+   "form": "method",
+   "python": "Forcing.link_flow",
+   "doc": "Force the flow through *link* for the current step (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_link_flow",
+    "swmm_link_count",
+    "swmm_link_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.link_quality",
+   "target": "forcing",
+   "name": "link_quality",
+   "form": "method",
+   "python": "Forcing.link_quality",
+   "doc": "Force pollutant quality on a link.",
+   "c": [
+    "swmm_forcing_link_quality",
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.link_seepage",
+   "target": "forcing",
+   "name": "link_seepage",
+   "form": "method",
+   "python": "Forcing.link_seepage",
+   "doc": "Exchange in ft³/s regardless of project units, positive out of conduit.",
+   "c": [
+    "swmm_forcing_link_seepage",
+    "swmm_link_count",
+    "swmm_link_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.link_setting",
+   "target": "forcing",
+   "name": "link_setting",
+   "form": "method",
+   "python": "Forcing.link_setting",
+   "doc": "Force the control setting (0-1) of *link* for the current step (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_link_setting",
+    "swmm_link_count",
+    "swmm_link_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.node_age",
+   "target": "forcing",
+   "name": "node_age",
+   "form": "method",
+   "python": "Forcing.node_age",
+   "doc": "Age override in hours; ADD uses hours times ft³/s.",
+   "c": [
+    "swmm_forcing_node_age",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.node_head_boundary",
+   "target": "forcing",
+   "name": "node_head_boundary",
+   "form": "method",
+   "python": "Forcing.node_head_boundary",
+   "doc": "Force a head/stage boundary at *node* for the current step (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_node_head_boundary",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.node_lat_inflow",
+   "target": "forcing",
+   "name": "node_lat_inflow",
+   "form": "method",
+   "python": "Forcing.node_lat_inflow",
+   "doc": "Force a lateral inflow (flow units) at *node* for the current step; *mode* selects replace/add/scale and *persist* keeps it across steps.",
+   "c": [
+    "swmm_forcing_node_lat_inflow",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.node_quality",
+   "target": "forcing",
+   "name": "node_quality",
+   "form": "method",
+   "python": "Forcing.node_quality",
+   "doc": "Force a pollutant mass-rate inflow of *pollutant* at *node* (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_node_quality",
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "mass_rate",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.node_temperature",
+   "target": "forcing",
+   "name": "node_temperature",
+   "form": "method",
+   "python": "Forcing.node_temperature",
+   "doc": "Temperature override in degrees C; ADD uses degrees C times ft³/s.",
+   "c": [
+    "swmm_forcing_node_temperature",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "int | str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.subcatchment_evap",
+   "target": "forcing",
+   "name": "subcatchment_evap",
+   "form": "method",
+   "python": "Forcing.subcatchment_evap",
+   "doc": "Prescribe a potential evapotranspiration (PET) rate on a subcatchment.",
+   "c": [
+    "swmm_forcing_subcatch_evap",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.subcatchment_rainfall",
+   "target": "forcing",
+   "name": "subcatchment_rainfall",
+   "form": "method",
+   "python": "Forcing.subcatchment_rainfall",
+   "doc": "Force the rainfall rate on subcatchment *sub* for the current step (see *mode* / *persist*).",
+   "c": [
+    "swmm_forcing_subcatch_rainfall",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "forcing.subcatchment_snowfall",
+   "target": "forcing",
+   "name": "subcatchment_snowfall",
+   "form": "method",
+   "python": "Forcing.subcatchment_snowfall",
+   "doc": "Prescribe snowfall on a subcatchment.",
+   "c": [
+    "swmm_forcing_subcatch_snowfall",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "ForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "gage.data_source",
+   "target": "gage",
+   "name": "data_source",
+   "form": "property",
+   "python": "Gage.data_source",
+   "doc": "Get the data source type for a gage.",
+   "c": [
+    "swmm_gage_get_data_source",
+    "swmm_gage_set_data_source"
+   ],
+   "type": "GageDataSource",
+   "access": "rw"
+  },
+  {
+   "path": "gage.file_column",
+   "target": "gage",
+   "name": "file_column",
+   "form": "property",
+   "python": "Gage.file_column",
+   "doc": "Data column name for a multi-column rain file (empty when unset).",
+   "c": [
+    "swmm_gage_get_file_column",
+    "swmm_gage_set_file_column"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "gage.file_format",
+   "target": "gage",
+   "name": "file_format",
+   "form": "property",
+   "python": "Gage.file_format",
+   "doc": "Rain file format code (meaningful for FILE gages).",
+   "c": [
+    "swmm_gage_get_file_format",
+    "swmm_gage_set_file_format"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "gage.id",
+   "target": "gage",
+   "name": "id",
+   "form": "property",
+   "python": "Gage.id",
+   "doc": "Get the string identifier of a rain gage by index.",
+   "c": [
+    "swmm_gage_id"
+   ],
+   "type": "str",
+   "access": "r",
+   "bulk": "gages.ids"
+  },
+  {
+   "path": "gage.index",
+   "target": "gage",
+   "name": "index",
+   "form": "property",
+   "python": "Gage.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "gage.rain_interval",
+   "target": "gage",
+   "name": "rain_interval",
+   "form": "property",
+   "python": "Gage.rain_interval",
+   "doc": "Rain recording interval in seconds.",
+   "c": [
+    "swmm_gage_get_rain_interval"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "s"
+  },
+  {
+   "path": "gage.rain_type",
+   "target": "gage",
+   "name": "rain_type",
+   "form": "property",
+   "python": "Gage.rain_type",
+   "doc": "Get the rainfall data format for a gage.",
+   "c": [
+    "swmm_gage_get_rain_type",
+    "swmm_gage_set_rain_type"
+   ],
+   "type": "GageRainType",
+   "access": "rw"
+  },
+  {
+   "path": "gage.rain_units",
+   "target": "gage",
+   "name": "rain_units",
+   "form": "property",
+   "python": "Gage.rain_units",
+   "doc": "Rain-depth units declared for a file source: 0 = IN, 1 = MM.",
+   "c": [
+    "swmm_gage_get_rain_units",
+    "swmm_gage_set_rain_units"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "gage.rainfall",
+   "target": "gage",
+   "name": "rainfall",
+   "form": "property",
+   "python": "Gage.rainfall",
+   "doc": "Get current rainfall rate at a gage (project rate units).",
+   "c": [
+    "swmm_gage_get_rainfall",
+    "swmm_gage_set_rainfall"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "rain_rate",
+   "bulk": "gages.rainfalls"
+  },
+  {
+   "path": "gage.rainfall_series",
+   "target": "gage",
+   "name": "rainfall_series",
+   "form": "property",
+   "python": "Gage.rainfall_series",
+   "doc": "The rainfall the engine will actually apply, as a structured array.",
+   "c": [
+    "swmm_gage_get_rainfall_series",
+    "swmm_gage_get_rainfall_series_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "gage.scale_factor",
+   "target": "gage",
+   "name": "scale_factor",
+   "form": "property",
+   "python": "Gage.scale_factor",
+   "doc": "Rainfall scaling factor (dimensionless, > 0; 1.0 = no scaling).",
+   "c": [
+    "swmm_gage_get_scale_factor",
+    "swmm_gage_set_scale_factor"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless"
+  },
+  {
+   "path": "gage.set_file",
+   "target": "gage",
+   "name": "set_file",
+   "form": "method",
+   "python": "Gage.set_file",
+   "doc": "Configure the gage to read from an external file.",
+   "c": [
+    "swmm_gage_set_file_column",
+    "swmm_gage_set_filename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "station_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "column",
+     "type": "Optional[str]",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "gage.set_rain_interval",
+   "target": "gage",
+   "name": "set_rain_interval",
+   "form": "method",
+   "python": "Gage.set_rain_interval",
+   "doc": "Set the rain-interval duration. Accepts a number of seconds or a datetime.timedelta.",
+   "c": [
+    "swmm_gage_set_rain_interval"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "seconds",
+     "type": "Union[float, timedelta]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "gage.set_timeseries",
+   "target": "gage",
+   "name": "set_timeseries",
+   "form": "method",
+   "python": "Gage.set_timeseries",
+   "doc": "Configure the gage to read from a named time series.",
+   "c": [
+    "swmm_gage_set_timeseries"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "ts_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "gage.snow_factor",
+   "target": "gage",
+   "name": "snow_factor",
+   "form": "property",
+   "python": "Gage.snow_factor",
+   "doc": "Snow-catch deficiency correction factor (SCF; 1.0 = no correction).",
+   "c": [
+    "swmm_gage_get_snow_factor",
+    "swmm_gage_set_snow_factor"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless"
+  },
+  {
+   "path": "gage.station_id",
+   "target": "gage",
+   "name": "station_id",
+   "form": "property",
+   "python": "Gage.station_id",
+   "doc": "Station id for a file source (empty when unset).",
+   "c": [
+    "swmm_gage_get_station_id",
+    "swmm_gage_set_station_id"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "gage.timeseries",
+   "target": "gage",
+   "name": "timeseries",
+   "form": "property",
+   "python": "Gage.timeseries",
+   "doc": "Assigned time-series id (empty when the source is not a series).",
+   "c": [
+    "swmm_gage_get_timeseries"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "gages.add",
+   "target": "gages",
+   "name": "add",
+   "form": "method",
+   "python": "Gages.add",
+   "doc": "Add a new rain gage *gage_id* and return its Gage handle.",
+   "c": [
+    "swmm_gage_add",
+    "swmm_gage_index"
+   ],
+   "returns": "Gage",
+   "params": [
+    {
+     "name": "gage_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "gages.get_id",
+   "target": "gages",
+   "name": "get_id",
+   "form": "method",
+   "python": "Gages.get_id",
+   "doc": "Return the ID string of the rain gage at *idx*.",
+   "c": [
+    "swmm_gage_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "gages.get_index",
+   "target": "gages",
+   "name": "get_index",
+   "form": "method",
+   "python": "Gages.get_index",
+   "doc": "Return the zero-based index of rain gage *gage_id* (raises if unknown).",
+   "c": [
+    "swmm_gage_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "gage_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "gages.ids",
+   "target": "gages",
+   "name": "ids",
+   "form": "property",
+   "python": "Gages.ids",
+   "doc": "",
+   "c": [],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "gages.rainfalls",
+   "target": "gages",
+   "name": "rainfalls",
+   "form": "property",
+   "python": "Gages.rainfalls",
+   "doc": "All rainfalls as a 1-D float64 array.",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_get_rainfall_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "rain_rate"
+  },
+  {
+   "path": "gages.reload_rain_files",
+   "target": "gages",
+   "name": "reload_rain_files",
+   "form": "method",
+   "python": "Gages.reload_rain_files",
+   "doc": "Re-read every FILE-source gage's rain data from disk.",
+   "c": [
+    "swmm_gage_reload_rain_files"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "gages.rename",
+   "target": "gages",
+   "name": "rename",
+   "form": "method",
+   "python": "Gages.rename",
+   "doc": "Rename the rain gage identified by *key* to *new_id*.",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_index",
+    "swmm_gage_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.begin",
+   "target": "geopackage",
+   "name": "begin",
+   "form": "method",
+   "python": "GeoPackage.begin",
+   "doc": "Begin a transaction for bulk operations.",
+   "c": [
+    "swmm_gpkg_begin"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "geopackage.close",
+   "target": "geopackage",
+   "name": "close",
+   "form": "method",
+   "python": "GeoPackage.close",
+   "doc": "Close the database connection.",
+   "c": [
+    "swmm_gpkg_close"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "geopackage.commit",
+   "target": "geopackage",
+   "name": "commit",
+   "form": "method",
+   "python": "GeoPackage.commit",
+   "doc": "Commit the current transaction.",
+   "c": [
+    "swmm_gpkg_commit"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "geopackage.create_observed_series",
+   "target": "geopackage",
+   "name": "create_observed_series",
+   "form": "method",
+   "python": "GeoPackage.create_observed_series",
+   "doc": "Create an observed-data series.",
+   "c": [
+    "swmm_gpkg_create_observed_series"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": false
+    },
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": false
+    },
+    {
+     "name": "source",
+     "type": "str",
+     "required": false
+    },
+    {
+     "name": "units",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "geopackage.last_error",
+   "target": "geopackage",
+   "name": "last_error",
+   "form": "property",
+   "python": "GeoPackage.last_error",
+   "doc": "The last error message from the GeoPackage library.",
+   "c": [
+    "swmm_gpkg_last_error"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "geopackage.object_counts",
+   "target": "geopackage",
+   "name": "object_counts",
+   "form": "method",
+   "python": "GeoPackage.object_counts",
+   "doc": "Return model object counts for a simulation.",
+   "c": [
+    "swmm_gpkg_gage_count",
+    "swmm_gpkg_link_count",
+    "swmm_gpkg_node_count",
+    "swmm_gpkg_subcatch_count"
+   ],
+   "returns": "Dict[str, int]",
+   "params": [
+    {
+     "name": "sim_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.observed_series_count",
+   "target": "geopackage",
+   "name": "observed_series_count",
+   "form": "method",
+   "python": "GeoPackage.observed_series_count",
+   "doc": "Return the number of observed-data series.",
+   "c": [
+    "swmm_gpkg_observed_series_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "geopackage.observed_value_count",
+   "target": "geopackage",
+   "name": "observed_value_count",
+   "form": "method",
+   "python": "GeoPackage.observed_value_count",
+   "doc": "Return the number of values in an observed series.",
+   "c": [
+    "swmm_gpkg_observed_value_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "series_id",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.query_double",
+   "target": "geopackage",
+   "name": "query_double",
+   "form": "method",
+   "python": "GeoPackage.query_double",
+   "doc": "Execute a read-only SQL query and return the first double result.",
+   "c": [
+    "swmm_gpkg_query_double"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "sql",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.query_int",
+   "target": "geopackage",
+   "name": "query_int",
+   "form": "method",
+   "python": "GeoPackage.query_int",
+   "doc": "Execute a read-only SQL query and return the first integer result.",
+   "c": [
+    "swmm_gpkg_query_int"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sql",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.read_observed_values",
+   "target": "geopackage",
+   "name": "read_observed_values",
+   "form": "method",
+   "python": "GeoPackage.read_observed_values",
+   "doc": "Read observed-timeseries values.",
+   "c": [
+    "swmm_gpkg_observed_value_count",
+    "swmm_gpkg_read_observed_values"
+   ],
+   "returns": "Tuple[List[str], npt.NDArray[np.float64]]",
+   "params": [
+    {
+     "name": "series_id",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.read_result_ts",
+   "target": "geopackage",
+   "name": "read_result_ts",
+   "form": "method",
+   "python": "GeoPackage.read_result_ts",
+   "doc": "Read a result timeseries as NumPy arrays.",
+   "c": [
+    "swmm_gpkg_read_result_ts",
+    "swmm_gpkg_result_ts_count"
+   ],
+   "returns": "Tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]",
+   "params": [
+    {
+     "name": "sim_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.read_summary",
+   "target": "geopackage",
+   "name": "read_summary",
+   "form": "method",
+   "python": "GeoPackage.read_summary",
+   "doc": "Read a single summary statistic value.",
+   "c": [
+    "swmm_gpkg_read_summary"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "sim_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.result_ts_count",
+   "target": "geopackage",
+   "name": "result_ts_count",
+   "form": "method",
+   "python": "GeoPackage.result_ts_count",
+   "doc": "Return the number of result timeseries records for a query.",
+   "c": [
+    "swmm_gpkg_result_ts_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sim_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.rollback",
+   "target": "geopackage",
+   "name": "rollback",
+   "form": "method",
+   "python": "GeoPackage.rollback",
+   "doc": "Roll back the current transaction.",
+   "c": [
+    "swmm_gpkg_rollback"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "geopackage.simulation_count",
+   "target": "geopackage",
+   "name": "simulation_count",
+   "form": "method",
+   "python": "GeoPackage.simulation_count",
+   "doc": "Return the number of simulation runs in the file.",
+   "c": [
+    "swmm_gpkg_simulation_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "geopackage.simulation_ids",
+   "target": "geopackage",
+   "name": "simulation_ids",
+   "form": "method",
+   "python": "GeoPackage.simulation_ids",
+   "doc": "Return all simulation IDs as a list of strings.",
+   "c": [
+    "swmm_gpkg_simulation_count",
+    "swmm_gpkg_simulation_id"
+   ],
+   "returns": "List[str]",
+   "params": []
+  },
+  {
+   "path": "geopackage.topology_edge_count",
+   "target": "geopackage",
+   "name": "topology_edge_count",
+   "form": "method",
+   "python": "GeoPackage.topology_edge_count",
+   "doc": "Return the number of topology edges for a simulation.",
+   "c": [
+    "swmm_gpkg_topology_edge_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sim_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "geopackage.variable_count",
+   "target": "geopackage",
+   "name": "variable_count",
+   "form": "method",
+   "python": "GeoPackage.variable_count",
+   "doc": "Return the number of output variables defined.",
+   "c": [
+    "swmm_gpkg_variable_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "geopackage.write_observed_value",
+   "target": "geopackage",
+   "name": "write_observed_value",
+   "form": "method",
+   "python": "GeoPackage.write_observed_value",
+   "doc": "Write a single observed data point.",
+   "c": [
+    "swmm_gpkg_write_observed_value"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "series_id",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "timestamp",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "flag",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "geopackage.write_observed_values",
+   "target": "geopackage",
+   "name": "write_observed_values",
+   "form": "method",
+   "python": "GeoPackage.write_observed_values",
+   "doc": "Bulk-write observed data points.",
+   "c": [
+    "swmm_gpkg_write_observed_values"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "series_id",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "timestamps",
+     "type": "List[str]",
+     "required": true
+    },
+    {
+     "name": "values",
+     "type": "npt.ArrayLike",
+     "required": true
+    },
+    {
+     "name": "flags",
+     "type": "Optional[List[str]]",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "heat.cloud.clear",
+   "target": "heat.cloud",
+   "name": "clear",
+   "form": "method",
+   "python": "_HeatCloud.clear",
+   "doc": "Clear [CLOUD_COVER] entirely — back to clear sky.",
+   "c": [
+    "swmm_heat_clear_cloud"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "heat.cloud.configured",
+   "target": "heat.cloud",
+   "name": "configured",
+   "form": "property",
+   "python": "_HeatCloud.configured",
+   "doc": "Is a [CLOUD_COVER] section in effect?",
+   "c": [
+    "swmm_heat_get_cloud_configured"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "heat.cloud.current",
+   "target": "heat.cloud",
+   "name": "current",
+   "form": "property",
+   "python": "_HeatCloud.current",
+   "doc": "Cloud fraction in effect at the **current** step, [0, 1].",
+   "c": [
+    "swmm_heat_get_current_cloud"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "target": "heat.cloud",
+   "form": "item",
+   "python": "_HeatCloud[]",
+   "doc": "",
+   "path": "heat.cloud.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatCloudParam, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_cloud"
+   ]
+  },
+  {
+   "target": "heat.cloud",
+   "form": "item",
+   "python": "_HeatCloud[]",
+   "doc": "",
+   "path": "heat.cloud.items",
+   "name": "items",
+   "returns": "list[tuple[Union[HeatCloudParam, int, str], float]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_cloud"
+   ]
+  },
+  {
+   "target": "heat.cloud",
+   "form": "item",
+   "python": "_HeatCloud[]",
+   "doc": "",
+   "path": "heat.cloud.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatCloudParam, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_set_cloud"
+   ]
+  },
+  {
+   "path": "heat.cloud.set_timeseries",
+   "target": "heat.cloud",
+   "name": "set_timeseries",
+   "form": "method",
+   "python": "_HeatCloud.set_timeseries",
+   "doc": "Bind a [TIMESERIES] by name as the cloud-fraction record.",
+   "c": [
+    "swmm_heat_set_cloud_timeseries"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "heat.cloud.timeseries",
+   "target": "heat.cloud",
+   "name": "timeseries",
+   "form": "property",
+   "python": "_HeatCloud.timeseries",
+   "doc": "Bound timeseries name, or an empty string when none is bound.",
+   "c": [
+    "swmm_heat_get_cloud_timeseries"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "heat.current_shortwave",
+   "target": "heat",
+   "name": "current_shortwave",
+   "form": "property",
+   "python": "Heat.current_shortwave",
+   "doc": "Resolved incoming shortwave at the **current** step, W/m2, cloud already applied.",
+   "c": [
+    "swmm_heat_get_current_shortwave"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "W/m2"
+  },
+  {
+   "path": "heat.enabled",
+   "target": "heat",
+   "name": "enabled",
+   "form": "property",
+   "python": "Heat.enabled",
+   "doc": "Is [OPTIONS] HEAT_TRANSPORT on? Read-only.",
+   "c": [
+    "swmm_heat_get_enabled"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "target": "heat.modules",
+   "form": "item",
+   "python": "_HeatModules[]",
+   "doc": "",
+   "path": "heat.modules.get_item",
+   "name": "get_item",
+   "returns": "bool",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatFluxModule, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_module"
+   ]
+  },
+  {
+   "target": "heat.modules",
+   "form": "item",
+   "python": "_HeatModules[]",
+   "doc": "",
+   "path": "heat.modules.items",
+   "name": "items",
+   "returns": "list[tuple[Union[HeatFluxModule, int, str], bool]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_module"
+   ]
+  },
+  {
+   "target": "heat.modules",
+   "form": "item",
+   "python": "_HeatModules[]",
+   "doc": "",
+   "path": "heat.modules.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatFluxModule, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "bool",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_set_module"
+   ]
+  },
+  {
+   "target": "heat.node_overrides",
+   "form": "item",
+   "python": "_HeatNodeOverrides[]",
+   "doc": "",
+   "path": "heat.node_overrides.get_item",
+   "name": "get_item",
+   "returns": "HeatNodeOverride",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_node_override"
+   ]
+  },
+  {
+   "target": "heat.node_overrides",
+   "form": "item",
+   "python": "_HeatNodeOverrides[]",
+   "doc": "",
+   "path": "heat.node_overrides.items",
+   "name": "items",
+   "returns": "list[tuple[int, HeatNodeOverride]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_node_override",
+    "swmm_heat_node_override_count"
+   ]
+  },
+  {
+   "path": "heat.node_overrides.remove",
+   "target": "heat.node_overrides",
+   "name": "remove",
+   "form": "method",
+   "python": "_HeatNodeOverrides.remove",
+   "doc": "Remove one NODE override by row index.",
+   "c": [
+    "swmm_heat_remove_node_override"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row_index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "heat.node_overrides.set",
+   "target": "heat.node_overrides",
+   "name": "set",
+   "form": "method",
+   "python": "_HeatNodeOverrides.set",
+   "doc": "Add or update the NODE override for (source, node).",
+   "c": [
+    "swmm_heat_set_node_override",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "temp_c",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "heat.radiative",
+   "form": "item",
+   "python": "_HeatRadiative[]",
+   "doc": "",
+   "path": "heat.radiative.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatRadiativeParam, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_radiative"
+   ]
+  },
+  {
+   "target": "heat.radiative",
+   "form": "item",
+   "python": "_HeatRadiative[]",
+   "doc": "",
+   "path": "heat.radiative.items",
+   "name": "items",
+   "returns": "list[tuple[Union[HeatRadiativeParam, int, str], float]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_radiative"
+   ]
+  },
+  {
+   "target": "heat.radiative",
+   "form": "item",
+   "python": "_HeatRadiative[]",
+   "doc": "",
+   "path": "heat.radiative.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatRadiativeParam, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_set_radiative"
+   ]
+  },
+  {
+   "path": "heat.set_shortwave_timeseries",
+   "target": "heat",
+   "name": "set_shortwave_timeseries",
+   "form": "method",
+   "python": "Heat.set_shortwave_timeseries",
+   "doc": "Bind a [TIMESERIES] by name as the shortwave record.",
+   "c": [
+    "swmm_heat_set_shortwave_timeseries"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "heat.shortwave_mode",
+   "target": "heat",
+   "name": "shortwave_mode",
+   "form": "property",
+   "python": "Heat.shortwave_mode",
+   "doc": "Where incoming shortwave comes from — a HeatShortwaveMode.",
+   "c": [
+    "swmm_heat_get_shortwave_mode",
+    "swmm_heat_set_shortwave_mode"
+   ],
+   "type": "HeatShortwaveMode",
+   "access": "rw"
+  },
+  {
+   "path": "heat.shortwave_timeseries",
+   "target": "heat",
+   "name": "shortwave_timeseries",
+   "form": "property",
+   "python": "Heat.shortwave_timeseries",
+   "doc": "Bound timeseries name, or an empty string when none is bound.",
+   "c": [
+    "swmm_heat_get_shortwave_timeseries"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "target": "heat.solar",
+   "form": "item",
+   "python": "_HeatSolar[]",
+   "doc": "",
+   "path": "heat.solar.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatSolarParam, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_solar"
+   ]
+  },
+  {
+   "target": "heat.solar",
+   "form": "item",
+   "python": "_HeatSolar[]",
+   "doc": "",
+   "path": "heat.solar.items",
+   "name": "items",
+   "returns": "list[tuple[Union[HeatSolarParam, int, str], float]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_solar"
+   ]
+  },
+  {
+   "target": "heat.solar",
+   "form": "item",
+   "python": "_HeatSolar[]",
+   "doc": "",
+   "path": "heat.solar.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[HeatSolarParam, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_set_solar"
+   ]
+  },
+  {
+   "path": "heat.solar_sited",
+   "target": "heat",
+   "name": "solar_sited",
+   "form": "property",
+   "python": "Heat.solar_sited",
+   "doc": "Have latitude **and** longitude both been explicitly set? Read-only.",
+   "c": [
+    "swmm_heat_get_solar_sited"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "heat.sources.clear",
+   "target": "heat.sources",
+   "name": "clear",
+   "form": "method",
+   "python": "_HeatSources.clear",
+   "doc": "Return *source* to the 20 degC default and mark it unconfigured.",
+   "c": [
+    "swmm_heat_clear_source_temp"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "heat.sources.effective",
+   "target": "heat.sources",
+   "name": "effective",
+   "form": "method",
+   "python": "_HeatSources.effective",
+   "doc": "The temperature *source* water actually enters *node* at (degC).",
+   "c": [
+    "swmm_heat_get_effective_source_temp",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "heat.sources",
+   "form": "item",
+   "python": "_HeatSources[]",
+   "doc": "",
+   "path": "heat.sources.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_get_source_temp"
+   ]
+  },
+  {
+   "path": "heat.sources.is_configured",
+   "target": "heat.sources",
+   "name": "is_configured",
+   "form": "method",
+   "python": "_HeatSources.is_configured",
+   "doc": "Did the model set *source* explicitly, or is it taking the default?",
+   "c": [
+    "swmm_heat_get_source_configured"
+   ],
+   "returns": "bool",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "heat.sources",
+   "form": "item",
+   "python": "_HeatSources[]",
+   "doc": "",
+   "path": "heat.sources.items",
+   "name": "items",
+   "returns": "list[tuple[Union[WaterAgeSource, int, str], float]]",
+   "params": [],
+   "c": [
+    "swmm_heat_get_source_temp",
+    "swmm_heat_source_count"
+   ]
+  },
+  {
+   "target": "heat.sources",
+   "form": "item",
+   "python": "_HeatSources[]",
+   "doc": "",
+   "path": "heat.sources.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_heat_set_source_temp"
+   ]
+  },
+  {
+   "path": "hotstart.apply",
+   "target": "hotstart",
+   "name": "apply",
+   "form": "method",
+   "python": "HotStart.apply",
+   "doc": "Apply this hot start to solver. The solver must be INITIALIZED (post-Solver.initialize, pre-Solver.start).",
+   "c": [
+    "swmm_hotstart_apply"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "solver",
+     "type": "Solver",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.close",
+   "target": "hotstart",
+   "name": "close",
+   "form": "method",
+   "python": "HotStart.close",
+   "doc": "Close the hot-start file and release its handle.",
+   "c": [
+    "swmm_hotstart_close"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "hotstart.crs",
+   "target": "hotstart",
+   "name": "crs",
+   "form": "property",
+   "python": "HotStart.crs",
+   "doc": "CRS string captured in the file, or None if absent.",
+   "c": [
+    "swmm_hotstart_get_crs"
+   ],
+   "type": "Optional[str]",
+   "access": "r"
+  },
+  {
+   "path": "hotstart.link_count",
+   "target": "hotstart",
+   "name": "link_count",
+   "form": "property",
+   "python": "HotStart.link_count",
+   "doc": "Number of links stored in the hot-start blob.",
+   "c": [
+    "swmm_hotstart_link_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "hotstart.node_count",
+   "target": "hotstart",
+   "name": "node_count",
+   "form": "property",
+   "python": "HotStart.node_count",
+   "doc": "Number of nodes stored in the hot-start blob.",
+   "c": [
+    "swmm_hotstart_node_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "hotstart.open",
+   "target": "hotstart",
+   "name": "open",
+   "form": "method",
+   "python": "HotStart.open",
+   "doc": "Open an existing hot start file.",
+   "c": [
+    "swmm_hotstart_open"
+   ],
+   "returns": "HotStart",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "hotstart.save_from",
+   "target": "hotstart",
+   "name": "save_from",
+   "form": "method",
+   "python": "HotStart.save_from",
+   "doc": "Save solver state to path. Raises on failure.",
+   "c": [
+    "swmm_hotstart_save"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "solver",
+     "type": "Solver",
+     "required": true
+    },
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "hotstart.set_link_depth",
+   "target": "hotstart",
+   "name": "set_link_depth",
+   "form": "method",
+   "python": "HotStart.set_link_depth",
+   "doc": "Seed the initial depth at *link_id* in the hot-start state.",
+   "c": [
+    "swmm_hotstart_set_link_depth"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "depth",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.set_link_flow",
+   "target": "hotstart",
+   "name": "set_link_flow",
+   "form": "method",
+   "python": "HotStart.set_link_flow",
+   "doc": "Seed the initial flow at *link_id* in the hot-start state.",
+   "c": [
+    "swmm_hotstart_set_link_flow"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flow",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.set_node_depth",
+   "target": "hotstart",
+   "name": "set_node_depth",
+   "form": "method",
+   "python": "HotStart.set_node_depth",
+   "doc": "Seed the initial water depth at *node_id* in the hot-start state.",
+   "c": [
+    "swmm_hotstart_set_node_depth"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "depth",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.set_node_head",
+   "target": "hotstart",
+   "name": "set_node_head",
+   "form": "method",
+   "python": "HotStart.set_node_head",
+   "doc": "Seed the initial hydraulic head at *node_id* in the hot-start state.",
+   "c": [
+    "swmm_hotstart_set_node_head"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "head",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.set_subcatchment_runoff",
+   "target": "hotstart",
+   "name": "set_subcatchment_runoff",
+   "form": "method",
+   "python": "HotStart.set_subcatchment_runoff",
+   "doc": "Seed the initial runoff at *sub_id* in the hot-start state.",
+   "c": [
+    "swmm_hotstart_set_subcatch_runoff"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "runoff",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "hotstart.sim_datetime",
+   "target": "hotstart",
+   "name": "sim_datetime",
+   "form": "property",
+   "python": "HotStart.sim_datetime",
+   "doc": "Moment at which the saved state was captured.",
+   "c": [
+    "swmm_hotstart_get_sim_time"
+   ],
+   "type": "datetime",
+   "access": "r"
+  },
+  {
+   "path": "hotstart.warnings",
+   "target": "hotstart",
+   "name": "warnings",
+   "form": "property",
+   "python": "HotStart.warnings",
+   "doc": "All warnings emitted during open/apply, in order.",
+   "c": [
+    "swmm_hotstart_warning",
+    "swmm_hotstart_warning_count"
+   ],
+   "type": "List[str]",
+   "access": "r"
+  },
+  {
+   "path": "inflows.add_dwf",
+   "target": "inflows",
+   "name": "add_dwf",
+   "form": "method",
+   "python": "Inflows.add_dwf",
+   "doc": "Add a dry-weather flow.",
+   "c": [
+    "swmm_dwf_add",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "constituent",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "avg_value",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "monthly_pattern",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "daily_pattern",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "hourly_pattern",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "weekend_pattern",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.add_external",
+   "target": "inflows",
+   "name": "add_external",
+   "form": "method",
+   "python": "Inflows.add_external",
+   "doc": "Add an external inflow.",
+   "c": [
+    "swmm_ext_inflow_add",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "constituent",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "ts_name",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "type",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "m_factor",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "s_factor",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "baseline",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "pattern",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.add_hydrograph",
+   "target": "inflows",
+   "name": "add_hydrograph",
+   "form": "method",
+   "python": "Inflows.add_hydrograph",
+   "doc": "Add an RTK unit-hydrograph (response R/T/K) to group *uh_name* for *month*.",
+   "c": [
+    "swmm_hydrograph_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "month",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "r",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "t",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "dmax",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "drecov",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "dinit",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.add_hydrograph_gage",
+   "target": "inflows",
+   "name": "add_hydrograph_gage",
+   "form": "method",
+   "python": "Inflows.add_hydrograph_gage",
+   "doc": "Associate rain *gage_name* with unit-hydrograph group *uh_name*.",
+   "c": [
+    "swmm_hydrograph_add_gage"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "gage_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.add_rdii",
+   "target": "inflows",
+   "name": "add_rdii",
+   "form": "method",
+   "python": "Inflows.add_rdii",
+   "doc": "Add an RDII inflow at *node* driven by unit-hydrograph group *uh_name* over sewered *area*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_rdii_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "area",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.add_rdii_decay",
+   "target": "inflows",
+   "name": "add_rdii_decay",
+   "form": "method",
+   "python": "Inflows.add_rdii_decay",
+   "doc": "Add an exponential-decay RDII entry to unit-hydrograph *uh_name*.",
+   "c": [
+    "swmm_rdii_decay_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "k_dep",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k_0",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k_T",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "T_ref",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "theta_rec",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "T_freeze",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "snow_on",
+     "type": "bool",
+     "required": false
+    },
+    {
+     "name": "snow_T",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "snow_ddf",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "inflows.clear_hydrograph_group_months",
+   "target": "inflows",
+   "name": "clear_hydrograph_group_months",
+   "form": "method",
+   "python": "Inflows.clear_hydrograph_group_months",
+   "doc": "Clear all monthly entries from a unit-hydrograph group.",
+   "c": [
+    "swmm_hydrograph_clear_group_months"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.dwf_count",
+   "target": "inflows",
+   "name": "dwf_count",
+   "form": "property",
+   "python": "Inflows.dwf_count",
+   "doc": "Get the total number of dry weather flow entries defined.",
+   "c": [
+    "swmm_dwf_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.external_count",
+   "target": "inflows",
+   "name": "external_count",
+   "form": "property",
+   "python": "Inflows.external_count",
+   "doc": "Get the total number of external inflows defined.",
+   "c": [
+    "swmm_ext_inflow_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.get_dwf",
+   "target": "inflows",
+   "name": "get_dwf",
+   "form": "method",
+   "python": "Inflows.get_dwf",
+   "doc": "Read one dry-weather-flow row by entry index.",
+   "c": [
+    "swmm_dwf_get"
+   ],
+   "returns": "Tuple[int, str, float, str, str, str, str]",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_external",
+   "target": "inflows",
+   "name": "get_external",
+   "form": "method",
+   "python": "Inflows.get_external",
+   "doc": "Read one external-inflow row by entry index.",
+   "c": [
+    "swmm_ext_inflow_get"
+   ],
+   "returns": "Tuple[int, str, str, str, float, float, float, str]",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_hydrograph",
+   "target": "inflows",
+   "name": "get_hydrograph",
+   "form": "method",
+   "python": "Inflows.get_hydrograph",
+   "doc": "Return the HydrographEntry at *idx*.",
+   "c": [
+    "swmm_hydrograph_get"
+   ],
+   "returns": "HydrographEntry",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_hydrograph_gage",
+   "target": "inflows",
+   "name": "get_hydrograph_gage",
+   "form": "method",
+   "python": "Inflows.get_hydrograph_gage",
+   "doc": "Return the HydrographGageEntry at *idx*.",
+   "c": [
+    "swmm_hydrograph_get_gage"
+   ],
+   "returns": "HydrographGageEntry",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_hydrograph_group_id",
+   "target": "inflows",
+   "name": "get_hydrograph_group_id",
+   "form": "method",
+   "python": "Inflows.get_hydrograph_group_id",
+   "doc": "Return the ID of the unit-hydrograph group at *idx*.",
+   "c": [
+    "swmm_hydrograph_group_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_rdii",
+   "target": "inflows",
+   "name": "get_rdii",
+   "form": "method",
+   "python": "Inflows.get_rdii",
+   "doc": "Return the RDIIEntry at *idx*.",
+   "c": [
+    "swmm_rdii_get"
+   ],
+   "returns": "RDIIEntry",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.get_rdii_decay",
+   "target": "inflows",
+   "name": "get_rdii_decay",
+   "form": "method",
+   "python": "Inflows.get_rdii_decay",
+   "doc": "Return the RDIIDecayEntry at *idx*.",
+   "c": [
+    "swmm_rdii_decay_get"
+   ],
+   "returns": "RDIIDecayEntry",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.hydrograph_count",
+   "target": "inflows",
+   "name": "hydrograph_count",
+   "form": "property",
+   "python": "Inflows.hydrograph_count",
+   "doc": "Count parameter entries in the model.",
+   "c": [
+    "swmm_hydrograph_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.hydrograph_gage_count",
+   "target": "inflows",
+   "name": "hydrograph_gage_count",
+   "form": "property",
+   "python": "Inflows.hydrograph_gage_count",
+   "doc": "Count UH-to-gage assignments.",
+   "c": [
+    "swmm_hydrograph_gage_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.hydrograph_group_count",
+   "target": "inflows",
+   "name": "hydrograph_group_count",
+   "form": "property",
+   "python": "Inflows.hydrograph_group_count",
+   "doc": "Count the unique unit-hydrograph group names defined.",
+   "c": [
+    "swmm_hydrograph_group_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.rdii_count",
+   "target": "inflows",
+   "name": "rdii_count",
+   "form": "property",
+   "python": "Inflows.rdii_count",
+   "doc": "Get the total number of RDII entries defined.",
+   "c": [
+    "swmm_rdii_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.rdii_decay_count",
+   "target": "inflows",
+   "name": "rdii_decay_count",
+   "form": "property",
+   "python": "Inflows.rdii_decay_count",
+   "doc": "Count exponential-decay parameter rows.",
+   "c": [
+    "swmm_rdii_decay_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "inflows.remove_dwf",
+   "target": "inflows",
+   "name": "remove_dwf",
+   "form": "method",
+   "python": "Inflows.remove_dwf",
+   "doc": "Remove the dry-weather-flow row at entry_idx.",
+   "c": [
+    "swmm_dwf_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.remove_external",
+   "target": "inflows",
+   "name": "remove_external",
+   "form": "method",
+   "python": "Inflows.remove_external",
+   "doc": "Remove the external-inflow row at entry_idx.",
+   "c": [
+    "swmm_ext_inflow_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.remove_hydrograph_entry",
+   "target": "inflows",
+   "name": "remove_hydrograph_entry",
+   "form": "method",
+   "python": "Inflows.remove_hydrograph_entry",
+   "doc": "Remove one (group, month, response) entry. Idempotent.",
+   "c": [
+    "swmm_hydrograph_remove_entry"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "month",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.remove_hydrograph_group",
+   "target": "inflows",
+   "name": "remove_hydrograph_group",
+   "form": "method",
+   "python": "Inflows.remove_hydrograph_group",
+   "doc": "Remove an entire unit-hydrograph group.",
+   "c": [
+    "swmm_hydrograph_remove_group"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.remove_rdii",
+   "target": "inflows",
+   "name": "remove_rdii",
+   "form": "method",
+   "python": "Inflows.remove_rdii",
+   "doc": "Remove the RDII assignment row at entry_idx.",
+   "c": [
+    "swmm_rdii_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.remove_rdii_decay",
+   "target": "inflows",
+   "name": "remove_rdii_decay",
+   "form": "method",
+   "python": "Inflows.remove_rdii_decay",
+   "doc": "Remove the IA-decay row for one (group, response). Idempotent.",
+   "c": [
+    "swmm_rdii_decay_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.rename_hydrograph_group",
+   "target": "inflows",
+   "name": "rename_hydrograph_group",
+   "form": "method",
+   "python": "Inflows.rename_hydrograph_group",
+   "doc": "Rename the unit-hydrograph group at idx.",
+   "c": [
+    "swmm_hydrograph_group_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_dwf_baseline",
+   "target": "inflows",
+   "name": "set_dwf_baseline",
+   "form": "method",
+   "python": "Inflows.set_dwf_baseline",
+   "doc": "Set a DWF row's average (baseline) value at runtime.",
+   "c": [
+    "swmm_dwf_set_baseline"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "avg_value",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_external_baseline",
+   "target": "inflows",
+   "name": "set_external_baseline",
+   "form": "method",
+   "python": "Inflows.set_external_baseline",
+   "doc": "Set an external-inflow row's constant baseline at runtime.",
+   "c": [
+    "swmm_ext_inflow_set_baseline"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "baseline",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_external_scale",
+   "target": "inflows",
+   "name": "set_external_scale",
+   "form": "method",
+   "python": "Inflows.set_external_scale",
+   "doc": "Set an external-inflow row's timeseries scale factor at runtime.",
+   "c": [
+    "swmm_ext_inflow_set_scale"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "entry_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "scale",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_hydrograph_gage",
+   "target": "inflows",
+   "name": "set_hydrograph_gage",
+   "form": "method",
+   "python": "Inflows.set_hydrograph_gage",
+   "doc": "Assign the rain gage that drives a unit-hydrograph group.",
+   "c": [
+    "swmm_hydrograph_set_gage"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "gage_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_hydrograph_ia",
+   "target": "inflows",
+   "name": "set_hydrograph_ia",
+   "form": "method",
+   "python": "Inflows.set_hydrograph_ia",
+   "doc": "Upsert linear initial-abstraction params for one (group, month, response).",
+   "c": [
+    "swmm_hydrograph_set_ia"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "month",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "dmax",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "drecov",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "dinit",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_hydrograph_rtk",
+   "target": "inflows",
+   "name": "set_hydrograph_rtk",
+   "form": "method",
+   "python": "Inflows.set_hydrograph_rtk",
+   "doc": "Upsert the (R, T, K) triplet for one (group, month, response).",
+   "c": [
+    "swmm_hydrograph_set_rtk"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "month",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "r",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "t",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "inflows.set_rdii_decay",
+   "target": "inflows",
+   "name": "set_rdii_decay",
+   "form": "method",
+   "python": "Inflows.set_rdii_decay",
+   "doc": "Upsert the IA-decay row for one (group, response).",
+   "c": [
+    "swmm_rdii_decay_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "uh_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "response",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "k_dep",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k_0",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "k_T",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "T_ref",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "theta_rec",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "T_freeze",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "snow_on",
+     "type": "bool",
+     "required": false
+    },
+    {
+     "name": "snow_T",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "snow_ddf",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.find_link",
+   "target": "infrastructure.inlet_usages",
+   "name": "find_link",
+   "form": "method",
+   "python": "InletUsages.find_link",
+   "doc": "Row index of the usage hosted by conduit link_idx, or -1.",
+   "c": [
+    "swmm_inlet_usage_find_link"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "link_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.find_node",
+   "target": "infrastructure.inlet_usages",
+   "name": "find_node",
+   "form": "method",
+   "python": "InletUsages.find_node",
+   "doc": "Row index of the usage hosted by inlet junction node_idx, or -1.",
+   "c": [
+    "swmm_inlet_usage_find_node"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "node_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.get",
+   "target": "infrastructure.inlet_usages",
+   "name": "get",
+   "form": "method",
+   "python": "InletUsages.get",
+   "doc": "Read one usage row.",
+   "c": [
+    "swmm_inlet_usage_get"
+   ],
+   "returns": "dict[str, Any]",
+   "params": [
+    {
+     "name": "usage_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.items",
+   "target": "infrastructure.inlet_usages",
+   "name": "items",
+   "form": "item",
+   "python": "list(InletUsages)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[dict[str, Any]]]]",
+   "params": [],
+   "c": [
+    "swmm_inlet_usage_count"
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.remove",
+   "target": "infrastructure.inlet_usages",
+   "name": "remove",
+   "form": "method",
+   "python": "InletUsages.remove",
+   "doc": "Delete a usage row.",
+   "c": [
+    "swmm_inlet_usage_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "usage_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlet_usages.set",
+   "target": "infrastructure.inlet_usages",
+   "name": "set",
+   "form": "method",
+   "python": "InletUsages.set",
+   "doc": "Create or replace the usage row for a host.",
+   "c": [
+    "swmm_inlet_usage_set"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "host_kind",
+     "type": "InletHostKind | int",
+     "required": true
+    },
+    {
+     "name": "host_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "design_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "capture_node_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "num_inlets",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "pct_clogged",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "flow_limit",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "local_depress",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "local_width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "placement",
+     "type": "InletPlacement | int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.add",
+   "target": "infrastructure.inlets",
+   "name": "add",
+   "form": "method",
+   "python": "Inlets.add",
+   "doc": "Add an inlet *inlet_id* of *inlet_type* and return its index.",
+   "c": [
+    "swmm_inlet_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "inlet_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "inlet_type",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_comment",
+   "target": "infrastructure.inlets",
+   "name": "get_comment",
+   "form": "method",
+   "python": "Inlets.get_comment",
+   "doc": "Return the free-text description of an inlet design.",
+   "c": [
+    "swmm_inlet_get_comment"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_design",
+   "target": "infrastructure.inlets",
+   "name": "get_design",
+   "form": "method",
+   "python": "Inlets.get_design",
+   "doc": "Read every field of an inlet design.",
+   "c": [
+    "swmm_inlet_get_design"
+   ],
+   "returns": "dict[str, Any]",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_id",
+   "target": "infrastructure.inlets",
+   "name": "get_id",
+   "form": "method",
+   "python": "Inlets.get_id",
+   "doc": "Return the string id of the inlet at idx.",
+   "c": [
+    "swmm_inlet_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_index",
+   "target": "infrastructure.inlets",
+   "name": "get_index",
+   "form": "method",
+   "python": "Inlets.get_index",
+   "doc": "Resolve an inlet's zero-based index from its string id.",
+   "c": [
+    "swmm_inlet_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "inlet_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_params",
+   "target": "infrastructure.inlets",
+   "name": "get_params",
+   "form": "method",
+   "python": "Inlets.get_params",
+   "doc": "Read back an inlet's geometric parameters.",
+   "c": [
+    "swmm_inlet_get_params"
+   ],
+   "returns": "dict[str, float | str]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.get_type",
+   "target": "infrastructure.inlets",
+   "name": "get_type",
+   "form": "method",
+   "python": "Inlets.get_type",
+   "doc": "Return the inlet's type string (the value passed to add).",
+   "c": [
+    "swmm_inlet_get_type"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.items",
+   "target": "infrastructure.inlets",
+   "name": "items",
+   "form": "item",
+   "python": "list(Inlets)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_inlet_count"
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.rename",
+   "target": "infrastructure.inlets",
+   "name": "rename",
+   "form": "method",
+   "python": "Inlets.rename",
+   "doc": "Rename an inlet design, updating stored references.",
+   "c": [
+    "swmm_inlet_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.set_comment",
+   "target": "infrastructure.inlets",
+   "name": "set_comment",
+   "form": "method",
+   "python": "Inlets.set_comment",
+   "doc": "Set the free-text description of an inlet design.",
+   "c": [
+    "swmm_inlet_set_comment"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.set_design",
+   "target": "infrastructure.inlets",
+   "name": "set_design",
+   "form": "method",
+   "python": "Inlets.set_design",
+   "doc": "Overwrite every field of an inlet design (the type may change).",
+   "c": [
+    "swmm_inlet_get_design",
+    "swmm_inlet_set_design"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "design",
+     "type": "dict[str, Any] | None",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.inlets.set_params",
+   "target": "infrastructure.inlets",
+   "name": "set_params",
+   "form": "method",
+   "python": "Inlets.set_params",
+   "doc": "Set the geometry parameters for inlet *idx*.",
+   "c": [
+    "swmm_inlet_set_params"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "length",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "grate_type",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "open_area",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "splash_veloc",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.add",
+   "target": "infrastructure.lids",
+   "name": "add",
+   "form": "method",
+   "python": "LIDs.add",
+   "doc": "Add a LID control.",
+   "c": [
+    "swmm_lid_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "lid_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "lid_type",
+     "type": "LidType",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_drain",
+   "target": "infrastructure.lids",
+   "name": "get_drain",
+   "form": "method",
+   "python": "LIDs.get_drain",
+   "doc": "Read the underdrain layer. Inverse of set_drain.",
+   "c": [
+    "swmm_lid_get_drain"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_drainmat",
+   "target": "infrastructure.lids",
+   "name": "get_drainmat",
+   "form": "method",
+   "python": "LIDs.get_drainmat",
+   "doc": "Read the drainage-mat layer. Inverse of set_drainmat.",
+   "c": [
+    "swmm_lid_get_drainmat"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_id",
+   "target": "infrastructure.lids",
+   "name": "get_id",
+   "form": "method",
+   "python": "LIDs.get_id",
+   "doc": "Return the string id of the LID control at idx.",
+   "c": [
+    "swmm_lid_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_index",
+   "target": "infrastructure.lids",
+   "name": "get_index",
+   "form": "method",
+   "python": "LIDs.get_index",
+   "doc": "Resolve a LID control's zero-based index from its string id.",
+   "c": [
+    "swmm_lid_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "lid_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_pavement",
+   "target": "infrastructure.lids",
+   "name": "get_pavement",
+   "form": "method",
+   "python": "LIDs.get_pavement",
+   "doc": "Read the porous-pavement layer. Inverse of set_pavement.",
+   "c": [
+    "swmm_lid_get_pavement"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_soil",
+   "target": "infrastructure.lids",
+   "name": "get_soil",
+   "form": "method",
+   "python": "LIDs.get_soil",
+   "doc": "Read the soil layer. Inverse of set_soil.",
+   "c": [
+    "swmm_lid_get_soil"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_storage",
+   "target": "infrastructure.lids",
+   "name": "get_storage",
+   "form": "method",
+   "python": "LIDs.get_storage",
+   "doc": "Read the storage layer. Inverse of set_storage.",
+   "c": [
+    "swmm_lid_get_storage"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_surface",
+   "target": "infrastructure.lids",
+   "name": "get_surface",
+   "form": "method",
+   "python": "LIDs.get_surface",
+   "doc": "Read the surface layer. Inverse of set_surface.",
+   "c": [
+    "swmm_lid_get_surface"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.get_type",
+   "target": "infrastructure.lids",
+   "name": "get_type",
+   "form": "method",
+   "python": "LIDs.get_type",
+   "doc": "Return the LID control's type code (inverse of the lid_type argument to add).",
+   "c": [
+    "swmm_lid_get_type"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.items",
+   "target": "infrastructure.lids",
+   "name": "items",
+   "form": "item",
+   "python": "list(LIDs)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_lid_count"
+   ]
+  },
+  {
+   "path": "infrastructure.lids.rename",
+   "target": "infrastructure.lids",
+   "name": "rename",
+   "form": "method",
+   "python": "LIDs.rename",
+   "doc": "Rename an LID control, updating stored [LID_USAGE] references.",
+   "c": [
+    "swmm_lid_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_drain",
+   "target": "infrastructure.lids",
+   "name": "set_drain",
+   "form": "method",
+   "python": "LIDs.set_drain",
+   "doc": "Set the underdrain parameters for LID *idx*.",
+   "c": [
+    "swmm_lid_set_drain"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "coeff",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "expon",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "offset",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_drainmat",
+   "target": "infrastructure.lids",
+   "name": "set_drainmat",
+   "form": "method",
+   "python": "LIDs.set_drainmat",
+   "doc": "Set the drainage-mat layer (GREEN_ROOF LIDs).",
+   "c": [
+    "swmm_lid_set_drainmat"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "thick",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "void_frac",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "roughness",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_pavement",
+   "target": "infrastructure.lids",
+   "name": "set_pavement",
+   "form": "method",
+   "python": "LIDs.set_pavement",
+   "doc": "Set the porous-pavement layer (PERM_PAVEMENT LIDs).",
+   "c": [
+    "swmm_lid_set_pavement"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "thick",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "void_ratio",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "frac_imperv",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "ksat",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "clog_factor",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "regen_days",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_soil",
+   "target": "infrastructure.lids",
+   "name": "set_soil",
+   "form": "method",
+   "python": "LIDs.set_soil",
+   "doc": "Set the soil-layer parameters for LID *idx*.",
+   "c": [
+    "swmm_lid_set_soil"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "thick",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "porosity",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fc",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "wp",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "ksat",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "kslope",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_storage",
+   "target": "infrastructure.lids",
+   "name": "set_storage",
+   "form": "method",
+   "python": "LIDs.set_storage",
+   "doc": "Set the storage-layer parameters for LID *idx*.",
+   "c": [
+    "swmm_lid_set_storage"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "thick",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "void_frac",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "ksat",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.set_surface",
+   "target": "infrastructure.lids",
+   "name": "set_surface",
+   "form": "method",
+   "python": "LIDs.set_surface",
+   "doc": "Set the surface-layer parameters for LID *idx*.",
+   "c": [
+    "swmm_lid_set_surface"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "storage",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "roughness",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "slope",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.usage_add",
+   "target": "infrastructure.lids",
+   "name": "usage_add",
+   "form": "method",
+   "python": "LIDs.usage_add",
+   "doc": "Place lid (id or index) on subcatchment (id or index).",
+   "c": [
+    "swmm_lid_usage_add",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "subcatchment",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "lid",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "number",
+     "type": "int",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "area",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "width",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "init_sat",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "from_imperv",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.usage_count",
+   "target": "infrastructure.lids",
+   "name": "usage_count",
+   "form": "method",
+   "python": "LIDs.usage_count",
+   "doc": "Number of [LID_USAGE] placement rows across all subcatchments.",
+   "c": [
+    "swmm_lid_usage_count"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "infrastructure.lids.usage_get",
+   "target": "infrastructure.lids",
+   "name": "usage_get",
+   "form": "method",
+   "python": "LIDs.usage_get",
+   "doc": "Read one [LID_USAGE] placement row by global index.",
+   "c": [
+    "swmm_lid_usage_get"
+   ],
+   "returns": "dict[str, float | int]",
+   "params": [
+    {
+     "name": "usage_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.lids.usage_remove",
+   "target": "infrastructure.lids",
+   "name": "usage_remove",
+   "form": "method",
+   "python": "LIDs.usage_remove",
+   "doc": "Remove one [LID_USAGE] placement row by global index.",
+   "c": [
+    "swmm_lid_usage_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "usage_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.add",
+   "target": "infrastructure.streets",
+   "name": "add",
+   "form": "method",
+   "python": "Streets.add",
+   "doc": "Add a street cross-section *street_id* and return its index.",
+   "c": [
+    "swmm_street_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "street_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.get_id",
+   "target": "infrastructure.streets",
+   "name": "get_id",
+   "form": "method",
+   "python": "Streets.get_id",
+   "doc": "Return the string id of the street at idx.",
+   "c": [
+    "swmm_street_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.get_index",
+   "target": "infrastructure.streets",
+   "name": "get_index",
+   "form": "method",
+   "python": "Streets.get_index",
+   "doc": "Resolve a street's zero-based index from its string id.",
+   "c": [
+    "swmm_street_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "street_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.get_params",
+   "target": "infrastructure.streets",
+   "name": "get_params",
+   "form": "method",
+   "python": "Streets.get_params",
+   "doc": "Read back a street cross-section's geometric parameters.",
+   "c": [
+    "swmm_street_get_params"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.items",
+   "target": "infrastructure.streets",
+   "name": "items",
+   "form": "item",
+   "python": "list(Streets)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_street_count"
+   ]
+  },
+  {
+   "path": "infrastructure.streets.rename",
+   "target": "infrastructure.streets",
+   "name": "rename",
+   "form": "method",
+   "python": "Streets.rename",
+   "doc": "Rename a street cross-section, updating stored references.",
+   "c": [
+    "swmm_street_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.streets.set_params",
+   "target": "infrastructure.streets",
+   "name": "set_params",
+   "form": "method",
+   "python": "Streets.set_params",
+   "doc": "Set the geometry and roughness parameters for street *idx*.",
+   "c": [
+    "swmm_street_set_params"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "t_crown",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "h_curb",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "sx",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "n_road",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "gutter_depres",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "gutter_width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "sides",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_slope",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_n",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.add",
+   "target": "infrastructure.transects",
+   "name": "add",
+   "form": "method",
+   "python": "Transects.add",
+   "doc": "Add a natural-channel transect *transect_id* and return its index.",
+   "c": [
+    "swmm_transect_add"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "transect_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.add_station",
+   "target": "infrastructure.transects",
+   "name": "add_station",
+   "form": "method",
+   "python": "Transects.add_station",
+   "doc": "Append a (station, elevation) point to transect *idx*.",
+   "c": [
+    "swmm_transect_add_station"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "station",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "elevation",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.clear_stations",
+   "target": "infrastructure.transects",
+   "name": "clear_stations",
+   "form": "method",
+   "python": "Transects.clear_stations",
+   "doc": "Remove all station points from the transect at idx.",
+   "c": [
+    "swmm_transect_clear_stations"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_bank_stations",
+   "target": "infrastructure.transects",
+   "name": "get_bank_stations",
+   "form": "method",
+   "python": "Transects.get_bank_stations",
+   "doc": "Return the (left, right) bank stations.",
+   "c": [
+    "swmm_transect_get_bank_stations"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_comments",
+   "target": "infrastructure.transects",
+   "name": "get_comments",
+   "form": "method",
+   "python": "Transects.get_comments",
+   "doc": "Return the descriptive comment string for the transect at idx.",
+   "c": [
+    "swmm_transect_get_comments"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_encroachment_stations",
+   "target": "infrastructure.transects",
+   "name": "get_encroachment_stations",
+   "form": "method",
+   "python": "Transects.get_encroachment_stations",
+   "doc": "Return the (left, right) encroachment stations.",
+   "c": [
+    "swmm_transect_get_encroachment_stations"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_id",
+   "target": "infrastructure.transects",
+   "name": "get_id",
+   "form": "method",
+   "python": "Transects.get_id",
+   "doc": "Return the string id of the transect at idx.",
+   "c": [
+    "swmm_transect_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_index",
+   "target": "infrastructure.transects",
+   "name": "get_index",
+   "form": "method",
+   "python": "Transects.get_index",
+   "doc": "Resolve a transect's zero-based index from its string id.",
+   "c": [
+    "swmm_transect_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "transect_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_modifiers",
+   "target": "infrastructure.transects",
+   "name": "get_modifiers",
+   "form": "method",
+   "python": "Transects.get_modifiers",
+   "doc": "Return the geometry modifiers as (n_factor, x_factor, y_factor).",
+   "c": [
+    "swmm_transect_get_modifiers"
+   ],
+   "returns": "Tuple[float, float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_roughness",
+   "target": "infrastructure.transects",
+   "name": "get_roughness",
+   "form": "method",
+   "python": "Transects.get_roughness",
+   "doc": "Return Manning's n as (n_left, n_right, n_channel).",
+   "c": [
+    "swmm_transect_get_roughness"
+   ],
+   "returns": "Tuple[float, float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.get_station",
+   "target": "infrastructure.transects",
+   "name": "get_station",
+   "form": "method",
+   "python": "Transects.get_station",
+   "doc": "Return the (station, elevation) pair at station_idx.",
+   "c": [
+    "swmm_transect_get_station"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "station_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.items",
+   "target": "infrastructure.transects",
+   "name": "items",
+   "form": "item",
+   "python": "list(Transects)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_transect_count"
+   ]
+  },
+  {
+   "path": "infrastructure.transects.remove",
+   "target": "infrastructure.transects",
+   "name": "remove",
+   "form": "method",
+   "python": "Transects.remove",
+   "doc": "Remove a transect (by index or id), clearing reference sites.",
+   "c": [
+    "swmm_transect_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.rename",
+   "target": "infrastructure.transects",
+   "name": "rename",
+   "form": "method",
+   "python": "Transects.rename",
+   "doc": "Rename a transect, updating stored references.",
+   "c": [
+    "swmm_transect_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.set_bank_stations",
+   "target": "infrastructure.transects",
+   "name": "set_bank_stations",
+   "form": "method",
+   "python": "Transects.set_bank_stations",
+   "doc": "Set the left/right bank stations.",
+   "c": [
+    "swmm_transect_set_bank_stations"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "left",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "right",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.set_comments",
+   "target": "infrastructure.transects",
+   "name": "set_comments",
+   "form": "method",
+   "python": "Transects.set_comments",
+   "doc": "Set the descriptive comment string for the transect at idx.",
+   "c": [
+    "swmm_transect_set_comments"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.set_encroachment_stations",
+   "target": "infrastructure.transects",
+   "name": "set_encroachment_stations",
+   "form": "method",
+   "python": "Transects.set_encroachment_stations",
+   "doc": "Set the left/right encroachment stations.",
+   "c": [
+    "swmm_transect_set_encroachment_stations"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "left",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "right",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.set_modifiers",
+   "target": "infrastructure.transects",
+   "name": "set_modifiers",
+   "form": "method",
+   "python": "Transects.set_modifiers",
+   "doc": "Set the geometry modifiers (Manning, station, elevation factors).",
+   "c": [
+    "swmm_transect_set_modifiers"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "n_factor",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "x_factor",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y_factor",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.set_roughness",
+   "target": "infrastructure.transects",
+   "name": "set_roughness",
+   "form": "method",
+   "python": "Transects.set_roughness",
+   "doc": "Set the left-bank, right-bank and channel Manning's n for transect *idx*.",
+   "c": [
+    "swmm_transect_set_roughness"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "n_left",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "n_right",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "n_channel",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.station_count",
+   "target": "infrastructure.transects",
+   "name": "station_count",
+   "form": "method",
+   "python": "Transects.station_count",
+   "doc": "Number of (station, elevation) points in the transect at idx.",
+   "c": [
+    "swmm_transect_get_station_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "infrastructure.transects.stations",
+   "target": "infrastructure.transects",
+   "name": "stations",
+   "form": "method",
+   "python": "Transects.stations",
+   "doc": "Return all (station, elevation) points as a list of tuples.",
+   "c": [],
+   "returns": "List[Tuple[float, float]]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "initial_quality.TEMPERATURE",
+   "target": "initial_quality",
+   "name": "TEMPERATURE",
+   "form": "property",
+   "python": "InitialQuality.TEMPERATURE",
+   "doc": "",
+   "c": [],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "initial_quality.WATER_AGE",
+   "target": "initial_quality",
+   "name": "WATER_AGE",
+   "form": "property",
+   "python": "InitialQuality.WATER_AGE",
+   "doc": "",
+   "c": [],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "initial_quality.file_path",
+   "target": "initial_quality",
+   "name": "file_path",
+   "form": "property",
+   "python": "InitialQuality.file_path",
+   "doc": "Authored sidecar path; empty when unset. Loaded on the next open.",
+   "c": [
+    "swmm_init_quality_file_get",
+    "swmm_init_quality_file_set"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "target": "initial_quality",
+   "form": "item",
+   "python": "InitialQuality[]",
+   "doc": "",
+   "path": "initial_quality.get_item",
+   "name": "get_item",
+   "returns": "InitialQualityEntry",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_init_quality_get"
+   ]
+  },
+  {
+   "path": "initial_quality.is_file",
+   "target": "initial_quality",
+   "name": "is_file",
+   "form": "method",
+   "python": "InitialQuality.is_file",
+   "doc": "Whether a row came from the sidecar; accepts negative indices.",
+   "c": [
+    "swmm_init_quality_is_file"
+   ],
+   "returns": "bool",
+   "params": [
+    {
+     "name": "row_index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "initial_quality",
+   "form": "item",
+   "python": "InitialQuality[]",
+   "doc": "",
+   "path": "initial_quality.items",
+   "name": "items",
+   "returns": "list[tuple[int, InitialQualityEntry]]",
+   "params": [],
+   "c": [
+    "swmm_init_quality_count",
+    "swmm_init_quality_get"
+   ]
+  },
+  {
+   "path": "initial_quality.remove",
+   "target": "initial_quality",
+   "name": "remove",
+   "form": "method",
+   "python": "InitialQuality.remove",
+   "doc": "Remove the row at *row_index*.",
+   "c": [
+    "swmm_init_quality_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row_index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "initial_quality.set",
+   "target": "initial_quality",
+   "name": "set",
+   "form": "method",
+   "python": "InitialQuality.set",
+   "doc": "Upsert the initial value of *constituent* in one node or one link.",
+   "c": [
+    "swmm_init_quality_set",
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "constituent",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "node",
+     "type": "Optional[Union[int, str]]",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "link",
+     "type": "Optional[Union[int, str]]",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "initialize",
+   "target": "solver",
+   "name": "initialize",
+   "form": "method",
+   "python": "Solver.initialize",
+   "doc": "Initialize the simulation; transition to INITIALIZED.",
+   "c": [
+    "swmm_engine_initialize"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "is_between_events",
+   "target": "solver",
+   "name": "is_between_events",
+   "form": "property",
+   "python": "Solver.is_between_events",
+   "doc": "True when the current routing time falls outside any [EVENTS] window (i.e. routing is being skipped).",
+   "c": [
+    "swmm_is_between_events"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "landuse.id",
+   "target": "landuse",
+   "name": "id",
+   "form": "property",
+   "python": "Landuse.id",
+   "doc": "Return the name of a land use by index. Returns NULL on error.",
+   "c": [
+    "swmm_landuse_id"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "landuse.index",
+   "target": "landuse",
+   "name": "index",
+   "form": "property",
+   "python": "Landuse.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "landuse.rename",
+   "target": "landuse",
+   "name": "rename",
+   "form": "method",
+   "python": "Landuse.rename",
+   "doc": "Rename this land use in place.",
+   "c": [
+    "swmm_landuse_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "landuse.sweep_interval",
+   "target": "landuse",
+   "name": "sweep_interval",
+   "form": "property",
+   "python": "Landuse.sweep_interval",
+   "doc": "Interval between street-sweeping events (days).",
+   "c": [
+    "swmm_landuse_get_sweep_interval",
+    "swmm_landuse_set_sweep_interval"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "d"
+  },
+  {
+   "path": "landuse.sweep_removal",
+   "target": "landuse",
+   "name": "sweep_removal",
+   "form": "property",
+   "python": "Landuse.sweep_removal",
+   "doc": "Sweeper removal fraction (0..1).",
+   "c": [
+    "swmm_landuse_get_sweep_removal",
+    "swmm_landuse_set_sweep_removal"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "fraction"
+  },
+  {
+   "path": "link.barrels",
+   "target": "link",
+   "name": "barrels",
+   "form": "property",
+   "python": "Link.barrels",
+   "doc": "Get the number of parallel barrels in a conduit.",
+   "c": [
+    "swmm_link_get_barrels",
+    "swmm_link_set_barrels"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "link.capacity",
+   "target": "link",
+   "name": "capacity",
+   "form": "property",
+   "python": "Link.capacity",
+   "doc": "Get the current flow capacity utilization (depth / full depth).",
+   "c": [
+    "swmm_link_get_capacity"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction",
+   "bulk": "links.capacities"
+  },
+  {
+   "path": "link.closed",
+   "target": "link",
+   "name": "closed",
+   "form": "property",
+   "python": "Link.closed",
+   "doc": "Get link open/closed status. Returns 1 if closed, 0 if open.",
+   "c": [
+    "swmm_link_get_closed",
+    "swmm_link_set_closed"
+   ],
+   "type": "bool",
+   "access": "rw",
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "link.control_setting",
+   "target": "link",
+   "name": "control_setting",
+   "form": "property",
+   "python": "Link.control_setting",
+   "doc": "Get current control setting.",
+   "c": [
+    "swmm_link_get_control_setting",
+    "swmm_link_set_control_setting"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless",
+   "bulk": "links.control_settings"
+  },
+  {
+   "path": "link.culvert_code",
+   "target": "link",
+   "name": "culvert_code",
+   "form": "property",
+   "python": "Link.culvert_code",
+   "doc": "Get the FHWA culvert inlet geometry code.",
+   "c": [
+    "swmm_link_get_culvert_code",
+    "swmm_link_set_culvert_code"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "link.depth",
+   "target": "link",
+   "name": "depth",
+   "form": "property",
+   "python": "Link.depth",
+   "doc": "Get the current water depth in a link.",
+   "c": [
+    "swmm_link_get_depth"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length",
+   "bulk": "links.depths"
+  },
+  {
+   "path": "link.flap_gate",
+   "target": "link",
+   "name": "flap_gate",
+   "form": "property",
+   "python": "Link.flap_gate",
+   "doc": "Get whether a flap gate exists on a link.",
+   "c": [
+    "swmm_link_get_flap_gate",
+    "swmm_link_set_flap_gate"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "link.flow",
+   "target": "link",
+   "name": "flow",
+   "form": "property",
+   "python": "Link.flow",
+   "doc": "Get the current flow rate in a link.",
+   "c": [
+    "swmm_link_get_flow",
+    "swmm_link_set_flow"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "flow",
+   "phases": [
+    "RUNNING"
+   ],
+   "bulk": "links.flows"
+  },
+  {
+   "path": "link.from_node",
+   "target": "link",
+   "name": "from_node",
+   "form": "property",
+   "python": "Link.from_node",
+   "doc": "Upstream Node wrapper.",
+   "c": [
+    "swmm_link_get_from_node"
+   ],
+   "type": "ref:node",
+   "access": "r"
+  },
+  {
+   "path": "link.hyd_power",
+   "target": "link",
+   "name": "hyd_power",
+   "form": "property",
+   "python": "Link.hyd_power",
+   "doc": "Get hydraulic power dissipated in a link (ft-lb/s). P = gamma * |Q| * |hL|.",
+   "c": [
+    "swmm_link_get_hyd_power"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "ft-lb/s",
+   "bulk": "links.hyd_powers"
+  },
+  {
+   "path": "link.id",
+   "target": "link",
+   "name": "id",
+   "form": "property",
+   "python": "Link.id",
+   "doc": "Get the string identifier of a link by index.",
+   "c": [
+    "swmm_link_id"
+   ],
+   "type": "str",
+   "access": "r",
+   "bulk": "links.ids"
+  },
+  {
+   "path": "link.index",
+   "target": "link",
+   "name": "index",
+   "form": "property",
+   "python": "Link.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "link.initial_flow",
+   "target": "link",
+   "name": "initial_flow",
+   "form": "property",
+   "python": "Link.initial_flow",
+   "doc": "Get the initial flow in a link at simulation start.",
+   "c": [
+    "swmm_link_get_initial_flow",
+    "swmm_link_set_initial_flow"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "flow"
+  },
+  {
+   "path": "link.length",
+   "target": "link",
+   "name": "length",
+   "form": "property",
+   "python": "Link.length",
+   "doc": "Get the conduit length.",
+   "c": [
+    "swmm_link_get_length",
+    "swmm_link_set_length"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.loss_coeff",
+   "target": "link",
+   "name": "loss_coeff",
+   "form": "property",
+   "python": "Link.loss_coeff",
+   "doc": "(inlet, outlet, avg) loss coefficients.",
+   "c": [
+    "swmm_link_get_loss_coeff",
+    "swmm_link_set_loss_coeff"
+   ],
+   "type": "Tuple[float, float, float]",
+   "access": "rw"
+  },
+  {
+   "path": "link.max_flow",
+   "target": "link",
+   "name": "max_flow",
+   "form": "property",
+   "python": "Link.max_flow",
+   "doc": "Get the maximum allowable flow in a link.",
+   "c": [
+    "swmm_link_get_max_flow",
+    "swmm_link_set_max_flow"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "flow"
+  },
+  {
+   "path": "link.offset_dn",
+   "target": "link",
+   "name": "offset_dn",
+   "form": "property",
+   "python": "Link.offset_dn",
+   "doc": "Get the downstream (outlet) offset.",
+   "c": [
+    "swmm_link_get_offset_dn",
+    "swmm_link_set_offset_dn"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.offset_up",
+   "target": "link",
+   "name": "offset_up",
+   "form": "property",
+   "python": "Link.offset_up",
+   "doc": "Get the upstream (inlet) offset.",
+   "c": [
+    "swmm_link_get_offset_up",
+    "swmm_link_set_offset_up"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.orifice.open_close_rate",
+   "target": "link.orifice",
+   "name": "open_close_rate",
+   "form": "property",
+   "python": "OrificeView.open_close_rate",
+   "doc": "Get the orifice open/close rate (fraction per second). @since 6.0.0 (BN-LINK-06)",
+   "c": [
+    "swmm_link_get_orifice_open_close_rate",
+    "swmm_link_set_orifice_open_close_rate"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "1/s"
+  },
+  {
+   "path": "link.orifice.type",
+   "target": "link.orifice",
+   "name": "type",
+   "form": "property",
+   "python": "OrificeView.type",
+   "doc": "Get the orifice flow-attack classification.",
+   "c": [
+    "swmm_link_get_orifice_type",
+    "swmm_link_set_orifice_type"
+   ],
+   "type": "OrificeType",
+   "access": "rw"
+  },
+  {
+   "path": "link.outlet.expon",
+   "target": "link.outlet",
+   "name": "expon",
+   "form": "property",
+   "python": "OutletView.expon",
+   "doc": "Get the outlet functional-form exponent.",
+   "c": [
+    "swmm_link_get_outlet_expon",
+    "swmm_link_set_outlet_expon"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless"
+  },
+  {
+   "path": "link.outlet.rating_type",
+   "target": "link.outlet",
+   "name": "rating_type",
+   "form": "property",
+   "python": "OutletView.rating_type",
+   "doc": "Get the outlet rating-curve classification.",
+   "c": [
+    "swmm_link_get_outlet_rating_type",
+    "swmm_link_set_outlet_rating_type"
+   ],
+   "type": "OutletRatingType",
+   "access": "rw"
+  },
+  {
+   "path": "link.pump.curve",
+   "target": "link.pump",
+   "name": "curve",
+   "form": "property",
+   "python": "PumpView.curve",
+   "doc": "Get the pump curve index assigned to a pump link.",
+   "c": [
+    "swmm_link_get_pump_curve",
+    "swmm_link_set_pump_curve"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "link.pump.init_state",
+   "target": "link.pump",
+   "name": "init_state",
+   "form": "property",
+   "python": "PumpView.init_state",
+   "doc": "Get the initial on/off state of a pump.",
+   "c": [
+    "swmm_link_get_pump_init_state",
+    "swmm_link_set_pump_init_state"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "link.pump.shutoff_depth",
+   "target": "link.pump",
+   "name": "shutoff_depth",
+   "form": "property",
+   "python": "PumpView.shutoff_depth",
+   "doc": "Get the pump shutoff depth. @since 6.0.0 (BN-LINK-05)",
+   "c": [
+    "swmm_link_get_pump_shutoff_depth",
+    "swmm_link_set_pump_shutoff_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.pump.startup_depth",
+   "target": "link.pump",
+   "name": "startup_depth",
+   "form": "property",
+   "python": "PumpView.startup_depth",
+   "doc": "Get the pump startup depth. @since 6.0.0 (BN-LINK-05)",
+   "c": [
+    "swmm_link_get_pump_startup_depth",
+    "swmm_link_set_pump_startup_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.quality",
+   "target": "link",
+   "name": "quality",
+   "form": "method",
+   "python": "Link.quality",
+   "doc": "Return the current concentration of *pollutant* in this link.",
+   "c": [
+    "swmm_link_get_quality",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "link.roughness",
+   "target": "link",
+   "name": "roughness",
+   "form": "property",
+   "python": "Link.roughness",
+   "doc": "Get the Manning's roughness coefficient.",
+   "c": [
+    "swmm_link_get_roughness",
+    "swmm_link_set_roughness"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "manning_n"
+  },
+  {
+   "path": "link.seep_rate",
+   "target": "link",
+   "name": "seep_rate",
+   "form": "property",
+   "python": "Link.seep_rate",
+   "doc": "Get the seepage loss rate for a conduit.",
+   "c": [
+    "swmm_link_get_seep_rate",
+    "swmm_link_set_seep_rate"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "rain_rate"
+  },
+  {
+   "path": "link.set_nodes",
+   "target": "link",
+   "name": "set_nodes",
+   "form": "method",
+   "python": "Link.set_nodes",
+   "doc": "Reconnect this link. Accepts int indices, str ids, or Node wrappers.",
+   "c": [
+    "swmm_link_set_nodes",
+    "swmm_node_count",
+    "swmm_node_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "from_node",
+     "type": "Union[Node, Union[int, str]]",
+     "required": true
+    },
+    {
+     "name": "to_node",
+     "type": "Union[Node, Union[int, str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "link.slope",
+   "target": "link",
+   "name": "slope",
+   "form": "property",
+   "python": "Link.slope",
+   "doc": "Get the computed slope of a conduit.",
+   "c": [
+    "swmm_link_get_slope"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "link.slot_volume",
+   "target": "link",
+   "name": "slot_volume",
+   "form": "property",
+   "python": "Link.slot_volume",
+   "doc": "Water held in the Preissmann slot, in project volume units.",
+   "c": [
+    "swmm_link_get_slot_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "link.stats.max_filling",
+   "target": "link.stats",
+   "name": "max_filling",
+   "form": "property",
+   "python": "LinkStatsView.max_filling",
+   "doc": "Get the maximum depth/full-depth ratio (filling) in a link.",
+   "c": [
+    "swmm_link_get_stat_max_filling"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "link.stats.max_flow",
+   "target": "link.stats",
+   "name": "max_flow",
+   "form": "property",
+   "python": "LinkStatsView.max_flow",
+   "doc": "Get the maximum flow recorded in a link during the simulation.",
+   "c": [
+    "swmm_link_get_stat_max_flow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow",
+   "phases": [
+    "ENDED",
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "link.stats.max_velocity",
+   "target": "link.stats",
+   "name": "max_velocity",
+   "form": "property",
+   "python": "LinkStatsView.max_velocity",
+   "doc": "Get the maximum velocity recorded in a link.",
+   "c": [
+    "swmm_link_get_stat_max_velocity"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "velocity"
+  },
+  {
+   "path": "link.stats.peak_slot_share",
+   "target": "link.stats",
+   "name": "peak_slot_share",
+   "form": "property",
+   "python": "LinkStatsView.peak_slot_share",
+   "doc": "Peak instantaneous slot_volume / volume over the run (0..1).",
+   "c": [
+    "swmm_link_get_stat_peak_slot_share"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "link.stats.pump_cycles",
+   "target": "link.stats",
+   "name": "pump_cycles",
+   "form": "property",
+   "python": "LinkStatsView.pump_cycles",
+   "doc": "Cycles for a pump link. Raises BadParamError on non-pumps.",
+   "c": [
+    "swmm_link_get_stat_pump_cycles"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "link.stats.pump_on_time",
+   "target": "link.stats",
+   "name": "pump_on_time",
+   "form": "property",
+   "python": "LinkStatsView.pump_on_time",
+   "doc": "Get pump total on-time (seconds).",
+   "c": [
+    "swmm_link_get_stat_pump_on_time"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "s"
+  },
+  {
+   "path": "link.stats.pump_volume",
+   "target": "link.stats",
+   "name": "pump_volume",
+   "form": "property",
+   "python": "LinkStatsView.pump_volume",
+   "doc": "Get pump total volume pumped (ft3).",
+   "c": [
+    "swmm_link_get_stat_pump_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "link.stats.slot_share",
+   "target": "link.stats",
+   "name": "slot_share",
+   "form": "property",
+   "python": "LinkStatsView.slot_share",
+   "doc": "Run-level slot share (∫ slot_volume dt) / (∫ volume dt) (0..1).",
+   "c": [
+    "swmm_link_get_stat_slot_share"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "link.stats.surcharge_time",
+   "target": "link.stats",
+   "name": "surcharge_time",
+   "form": "property",
+   "python": "LinkStatsView.surcharge_time",
+   "doc": "Get the total surcharge duration for a link.",
+   "c": [
+    "swmm_link_get_stat_surcharge_time"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "h"
+  },
+  {
+   "path": "link.stats.vol_flow",
+   "target": "link.stats",
+   "name": "vol_flow",
+   "form": "property",
+   "python": "LinkStatsView.vol_flow",
+   "doc": "Get the total volume conveyed through a link.",
+   "c": [
+    "swmm_link_get_stat_vol_flow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "link.tag",
+   "target": "link",
+   "name": "tag",
+   "form": "property",
+   "python": "Link.tag",
+   "doc": "The link's free-form tag string (from the INP [TAGS] section).",
+   "c": [
+    "swmm_link_get_tag",
+    "swmm_link_set_tag"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "link.target_setting",
+   "target": "link",
+   "name": "target_setting",
+   "form": "property",
+   "python": "Link.target_setting",
+   "doc": "Get the current target setting.",
+   "c": [
+    "swmm_link_get_target_setting",
+    "swmm_link_set_target_setting"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless",
+   "bulk": "links.target_settings"
+  },
+  {
+   "path": "link.to_node",
+   "target": "link",
+   "name": "to_node",
+   "form": "property",
+   "python": "Link.to_node",
+   "doc": "Downstream Node wrapper.",
+   "c": [
+    "swmm_link_get_to_node"
+   ],
+   "type": "ref:node",
+   "access": "r"
+  },
+  {
+   "path": "link.type",
+   "target": "link",
+   "name": "type",
+   "form": "property",
+   "python": "Link.type",
+   "doc": "Get the type of a link.",
+   "c": [
+    "swmm_link_get_type"
+   ],
+   "type": "LinkType",
+   "access": "r"
+  },
+  {
+   "path": "link.velocity",
+   "target": "link",
+   "name": "velocity",
+   "form": "property",
+   "python": "Link.velocity",
+   "doc": "Get the current flow velocity in a link.",
+   "c": [
+    "swmm_link_get_velocity"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "velocity",
+   "bulk": "links.velocities"
+  },
+  {
+   "path": "link.volume",
+   "target": "link",
+   "name": "volume",
+   "form": "property",
+   "python": "Link.volume",
+   "doc": "Get the current water volume stored in a link.",
+   "c": [
+    "swmm_link_get_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume",
+   "bulk": "links.volumes"
+  },
+  {
+   "path": "link.weir.crest_height",
+   "target": "link.weir",
+   "name": "crest_height",
+   "form": "property",
+   "python": "WeirView.crest_height",
+   "doc": "Get the crest height for a weir link.",
+   "c": [
+    "swmm_link_get_crest_height",
+    "swmm_link_set_crest_height"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "link.weir.discharge_coeff",
+   "target": "link.weir",
+   "name": "discharge_coeff",
+   "form": "property",
+   "python": "WeirView.discharge_coeff",
+   "doc": "Get the discharge coefficient for a weir link.",
+   "c": [
+    "swmm_link_get_discharge_coeff",
+    "swmm_link_set_discharge_coeff"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "weir_coeff"
+  },
+  {
+   "path": "link.weir.end_contractions",
+   "target": "link.weir",
+   "name": "end_contractions",
+   "form": "property",
+   "python": "WeirView.end_contractions",
+   "doc": "Get the number of end contractions for a weir link.",
+   "c": [
+    "swmm_link_get_end_contractions",
+    "swmm_link_set_end_contractions"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "count"
+  },
+  {
+   "path": "link.weir.type",
+   "target": "link.weir",
+   "name": "type",
+   "form": "property",
+   "python": "WeirView.type",
+   "doc": "Get the weir flow classification.",
+   "c": [
+    "swmm_link_get_weir_type",
+    "swmm_link_set_weir_type"
+   ],
+   "type": "WeirType",
+   "access": "rw"
+  },
+  {
+   "path": "link.xsect.as_tuple",
+   "target": "link.xsect",
+   "name": "as_tuple",
+   "form": "method",
+   "python": "XSection.as_tuple",
+   "doc": "Return the cross-section as a (shape, geom1, geom2, geom3, geom4) tuple.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "returns": "Tuple[XSectShape, float, float, float, float]",
+   "params": []
+  },
+  {
+   "path": "link.xsect.g1",
+   "target": "link.xsect",
+   "name": "g1",
+   "form": "property",
+   "python": "XSection.g1",
+   "doc": "Get the cross-section geometry for a conduit link.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "link.xsect.g2",
+   "target": "link.xsect",
+   "name": "g2",
+   "form": "property",
+   "python": "XSection.g2",
+   "doc": "Get the cross-section geometry for a conduit link.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "shape_dependent"
+  },
+  {
+   "path": "link.xsect.g3",
+   "target": "link.xsect",
+   "name": "g3",
+   "form": "property",
+   "python": "XSection.g3",
+   "doc": "Get the cross-section geometry for a conduit link.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "shape_dependent"
+  },
+  {
+   "path": "link.xsect.g4",
+   "target": "link.xsect",
+   "name": "g4",
+   "form": "property",
+   "python": "XSection.g4",
+   "doc": "Get the cross-section geometry for a conduit link.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "shape_dependent"
+  },
+  {
+   "path": "link.xsect.geometry",
+   "target": "link.xsect",
+   "name": "geometry",
+   "form": "method",
+   "python": "XSection.geometry",
+   "doc": "Return an XSectionGeometry for this link's cross-section.",
+   "c": [],
+   "returns": "XSectionGeometry",
+   "params": []
+  },
+  {
+   "path": "link.xsect.info",
+   "target": "link.xsect",
+   "name": "info",
+   "form": "method",
+   "python": "XSection.info",
+   "doc": "Return this cross-section as a CrossSection.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "returns": "CrossSection",
+   "params": []
+  },
+  {
+   "path": "link.xsect.items",
+   "target": "link.xsect",
+   "name": "items",
+   "form": "item",
+   "python": "list(XSection)",
+   "doc": "",
+   "returns": "list[tuple[int, Iterator[Any]]]",
+   "params": [],
+   "c": []
+  },
+  {
+   "path": "link.xsect.shape",
+   "target": "link.xsect",
+   "name": "shape",
+   "form": "property",
+   "python": "XSection.shape",
+   "doc": "Get the cross-section geometry for a conduit link.",
+   "c": [
+    "swmm_link_get_xsect"
+   ],
+   "type": "XSectShape",
+   "access": "r"
+  },
+  {
+   "path": "links.add",
+   "target": "links",
+   "name": "add",
+   "form": "method",
+   "python": "Links.add",
+   "doc": "Add a new link *link_id* of *link_type* and return its Link handle.",
+   "c": [
+    "swmm_link_add",
+    "swmm_link_index"
+   ],
+   "returns": "Link",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "link_type",
+     "type": "LinkType",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.capacities",
+   "target": "links",
+   "name": "capacities",
+   "form": "property",
+   "python": "Links.capacities",
+   "doc": "Get capacity ratios (q/q_full) for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_capacities_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "links.control_settings",
+   "target": "links",
+   "name": "control_settings",
+   "form": "property",
+   "python": "Links.control_settings",
+   "doc": "Get active control settings (0..1) for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_control_settings_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "links.depths",
+   "target": "links",
+   "name": "depths",
+   "form": "property",
+   "python": "Links.depths",
+   "doc": "Get water depths for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_depths_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "links.flows",
+   "target": "links",
+   "name": "flows",
+   "form": "property",
+   "python": "Links.flows",
+   "doc": "Get flow rates for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_flows_bulk",
+    "swmm_link_set_flows_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "rw",
+   "phases": [
+    "RUNNING"
+   ],
+   "units": "flow"
+  },
+  {
+   "path": "links.get_id",
+   "target": "links",
+   "name": "get_id",
+   "form": "method",
+   "python": "Links.get_id",
+   "doc": "Return the ID string of the link at *idx*.",
+   "c": [
+    "swmm_link_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.get_index",
+   "target": "links",
+   "name": "get_index",
+   "form": "method",
+   "python": "Links.get_index",
+   "doc": "Return the zero-based index of link *link_id* (raises if unknown).",
+   "c": [
+    "swmm_link_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.get_xsect_info",
+   "target": "links",
+   "name": "get_xsect_info",
+   "form": "method",
+   "python": "Links.get_xsect_info",
+   "doc": "Return the cross-section of the link identified by *key*.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_xsect",
+    "swmm_link_index"
+   ],
+   "returns": "CrossSection",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.hyd_powers",
+   "target": "links",
+   "name": "hyd_powers",
+   "form": "property",
+   "python": "Links.hyd_powers",
+   "doc": "Get hydraulic power dissipated in every link in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_hyd_powers_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "ft-lb/s"
+  },
+  {
+   "path": "links.ids",
+   "target": "links",
+   "name": "ids",
+   "form": "property",
+   "python": "Links.ids",
+   "doc": "Get link IDs for all links in a single call (stride-packed UTF-8).",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_ids_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "links.pop_last",
+   "target": "links",
+   "name": "pop_last",
+   "form": "method",
+   "python": "Links.pop_last",
+   "doc": "Remove the most recently added link, which must be *link_id*.",
+   "c": [
+    "swmm_link_pop_last"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.pump_stats",
+   "target": "links",
+   "name": "pump_stats",
+   "form": "method",
+   "python": "Links.pump_stats",
+   "doc": "Per-link pump statistics as a 3-tuple of arrays (cycles, on_time, volume). Non-pump links have zeros.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_pump_stats_bulk"
+   ],
+   "returns": "Tuple[NDArray[Any], NDArray[Any], NDArray[Any]]",
+   "params": []
+  },
+  {
+   "path": "links.qualities",
+   "target": "links",
+   "name": "qualities",
+   "form": "method",
+   "python": "Links.qualities",
+   "doc": "Return an array of *pollutant* concentrations for every link.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_quality_bulk",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.rename",
+   "target": "links",
+   "name": "rename",
+   "form": "method",
+   "python": "Links.rename",
+   "doc": "Rename the link identified by *key* to *new_id*.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_link_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "links.restore_authored_orientation",
+   "target": "links",
+   "name": "restore_authored_orientation",
+   "form": "method",
+   "python": "Links.restore_authored_orientation",
+   "doc": "Restore reversed conduits after open; return the number restored.",
+   "c": [
+    "swmm_links_restore_authored_orientation"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "links.target_settings",
+   "target": "links",
+   "name": "target_settings",
+   "form": "property",
+   "python": "Links.target_settings",
+   "doc": "Get target control settings for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_target_settings_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "dimensionless"
+  },
+  {
+   "path": "links.velocities",
+   "target": "links",
+   "name": "velocities",
+   "form": "property",
+   "python": "Links.velocities",
+   "doc": "Get cross-sectional velocities for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_velocities_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "velocity"
+  },
+  {
+   "path": "links.volumes",
+   "target": "links",
+   "name": "volumes",
+   "form": "property",
+   "python": "Links.volumes",
+   "doc": "Get stored volumes for all links in a single call.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_get_volumes_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "mass_balance.max_courant",
+   "target": "mass_balance",
+   "name": "max_courant",
+   "form": "property",
+   "python": "MassBalance.max_courant",
+   "doc": "Maximum Courant number observed during the simulation.",
+   "c": [
+    "swmm_get_max_courant"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "dimensionless"
+  },
+  {
+   "path": "mass_balance.quality_continuity_error",
+   "target": "mass_balance",
+   "name": "quality_continuity_error",
+   "form": "method",
+   "python": "MassBalance.quality_continuity_error",
+   "doc": "Quality continuity error as a fraction for pollutant (id or index).",
+   "c": [
+    "swmm_get_quality_continuity_error",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "mass_balance.quality_evap_loss",
+   "target": "mass_balance",
+   "name": "quality_evap_loss",
+   "form": "method",
+   "python": "MassBalance.quality_evap_loss",
+   "doc": "Cumulative mass of pollutant lost to evaporation.",
+   "c": [
+    "swmm_get_quality_evap_loss",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "mass_balance.quality_seep_loss",
+   "target": "mass_balance",
+   "name": "quality_seep_loss",
+   "form": "method",
+   "python": "MassBalance.quality_seep_loss",
+   "doc": "Cumulative mass of pollutant lost to seepage.",
+   "c": [
+    "swmm_get_quality_seep_loss",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "mass_balance.routing_continuity_error",
+   "target": "mass_balance",
+   "name": "routing_continuity_error",
+   "form": "property",
+   "python": "MassBalance.routing_continuity_error",
+   "doc": "Flow routing continuity error as a fraction (0.001 means 0.1%).",
+   "c": [
+    "swmm_get_routing_continuity_error"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "mass_balance.routing_diagnostics",
+   "target": "mass_balance",
+   "name": "routing_diagnostics",
+   "form": "property",
+   "python": "MassBalance.routing_diagnostics",
+   "doc": "Routing-solver time-step diagnostics as a RoutingDiagnostics dataclass.",
+   "c": [
+    "swmm_get_routing_stats"
+   ],
+   "type": "RoutingDiagnostics",
+   "access": "r"
+  },
+  {
+   "path": "mass_balance.routing_total",
+   "target": "mass_balance",
+   "name": "routing_total",
+   "form": "method",
+   "python": "MassBalance.routing_total",
+   "doc": "Cumulative routing volume for component (RoutingTotal).",
+   "c": [
+    "swmm_get_routing_total"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "component",
+     "type": "RoutingTotal",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "mass_balance.runoff_continuity_error",
+   "target": "mass_balance",
+   "name": "runoff_continuity_error",
+   "form": "property",
+   "python": "MassBalance.runoff_continuity_error",
+   "doc": "Runoff continuity error as a fraction (0.001 means 0.1%).",
+   "c": [
+    "swmm_get_runoff_continuity_error"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "mass_balance.runoff_total",
+   "target": "mass_balance",
+   "name": "runoff_total",
+   "form": "method",
+   "python": "MassBalance.runoff_total",
+   "doc": "Cumulative runoff volume for component (RunoffTotal).",
+   "c": [
+    "swmm_get_runoff_total"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "component",
+     "type": "RunoffTotal",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.crown_elev",
+   "target": "node",
+   "name": "crown_elev",
+   "form": "property",
+   "python": "Node.crown_elev",
+   "doc": "Get the crown elevation (invert + max depth) at a node.",
+   "c": [
+    "swmm_node_get_crown_elev"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "node.degree",
+   "target": "node",
+   "name": "degree",
+   "form": "property",
+   "python": "Node.degree",
+   "doc": "Get the degree (number of connected links) of a node.",
+   "c": [
+    "swmm_node_get_degree"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "node.depth",
+   "target": "node",
+   "name": "depth",
+   "form": "property",
+   "python": "Node.depth",
+   "doc": "Get the current water depth at a node.",
+   "c": [
+    "swmm_node_get_depth",
+    "swmm_node_set_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length",
+   "phases": [
+    "RUNNING"
+   ],
+   "bulk": "nodes.depths"
+  },
+  {
+   "path": "node.depth_from_volume",
+   "target": "node",
+   "name": "depth_from_volume",
+   "form": "method",
+   "python": "Node.depth_from_volume",
+   "doc": "Storage-curve lookup: depth corresponding to volume.",
+   "c": [
+    "swmm_node_get_depth_from_volume"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "volume",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.divider.type",
+   "target": "node.divider",
+   "name": "type",
+   "form": "property",
+   "python": "DividerView.type",
+   "doc": "Get the divider method for a flow-divider node.",
+   "c": [
+    "swmm_node_get_divider_type",
+    "swmm_node_set_divider_type"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "node.full_volume",
+   "target": "node",
+   "name": "full_volume",
+   "form": "property",
+   "python": "Node.full_volume",
+   "doc": "Get the full (maximum) stored volume at a node.",
+   "c": [
+    "swmm_node_get_full_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "node.head",
+   "target": "node",
+   "name": "head",
+   "form": "property",
+   "python": "Node.head",
+   "doc": "Get the current hydraulic head at a node (invert + depth).",
+   "c": [
+    "swmm_node_get_head"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length",
+   "bulk": "nodes.heads"
+  },
+  {
+   "path": "node.id",
+   "target": "node",
+   "name": "id",
+   "form": "property",
+   "python": "Node.id",
+   "doc": "Get the string identifier of a node by index.",
+   "c": [
+    "swmm_node_id"
+   ],
+   "type": "str",
+   "access": "r",
+   "bulk": "nodes.ids"
+  },
+  {
+   "path": "node.index",
+   "target": "node",
+   "name": "index",
+   "form": "property",
+   "python": "Node.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "node.inflow",
+   "target": "node",
+   "name": "inflow",
+   "form": "property",
+   "python": "Node.inflow",
+   "doc": "Get the total inflow to a node (lateral + upstream links).",
+   "c": [
+    "swmm_node_get_inflow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow",
+   "bulk": "nodes.inflows"
+  },
+  {
+   "path": "node.initial_depth",
+   "target": "node",
+   "name": "initial_depth",
+   "form": "property",
+   "python": "Node.initial_depth",
+   "doc": "Get the initial depth at a node.",
+   "c": [
+    "swmm_node_get_initial_depth",
+    "swmm_node_set_initial_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "node.inlet_rule_violation",
+   "target": "node",
+   "name": "inlet_rule_violation",
+   "form": "method",
+   "python": "Node.inlet_rule_violation",
+   "doc": "Dry-run check of the inlet-junction usage rules for this node.",
+   "c": [
+    "swmm_node_inlet_eligible"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "for_drop_inlet",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "node.invert_elev",
+   "target": "node",
+   "name": "invert_elev",
+   "form": "property",
+   "python": "Node.invert_elev",
+   "doc": "Get a node's invert elevation.",
+   "c": [
+    "swmm_node_get_invert_elev",
+    "swmm_node_set_invert_elev"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "node.is_inlet",
+   "target": "node",
+   "name": "is_inlet",
+   "form": "property",
+   "python": "Node.is_inlet",
+   "doc": "True when this node is an inlet junction.",
+   "c": [
+    "swmm_node_is_inlet",
+    "swmm_node_set_inlet"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "node.is_virtual",
+   "target": "node",
+   "name": "is_virtual",
+   "form": "property",
+   "python": "Node.is_virtual",
+   "doc": "True when this node is a virtual junction.",
+   "c": [
+    "swmm_node_is_virtual",
+    "swmm_node_set_virtual"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "node.lateral_inflow",
+   "target": "node",
+   "name": "lateral_inflow",
+   "form": "property",
+   "python": "Node.lateral_inflow",
+   "doc": "Get the current lateral inflow at a node.",
+   "c": [
+    "swmm_node_get_lateral_inflow",
+    "swmm_node_set_lateral_inflow"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "flow",
+   "phases": [
+    "RUNNING"
+   ],
+   "bulk": "nodes.lateral_inflows"
+  },
+  {
+   "path": "node.losses",
+   "target": "node",
+   "name": "losses",
+   "form": "property",
+   "python": "Node.losses",
+   "doc": "Get the cumulative water losses at a node (evaporation + exfiltration).",
+   "c": [
+    "swmm_node_get_losses"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume",
+   "bulk": "nodes.losses"
+  },
+  {
+   "path": "node.max_depth",
+   "target": "node",
+   "name": "max_depth",
+   "form": "property",
+   "python": "Node.max_depth",
+   "doc": "Get a node's maximum depth.",
+   "c": [
+    "swmm_node_get_max_depth",
+    "swmm_node_set_max_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "node.outfall.flap_gate",
+   "target": "node.outfall",
+   "name": "flap_gate",
+   "form": "property",
+   "python": "OutfallView.flap_gate",
+   "doc": "Get whether a flap gate exists at the outfall.",
+   "c": [
+    "swmm_node_get_outfall_flap_gate",
+    "swmm_node_set_outfall_flap_gate"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "node.outfall.get_tidal_curve",
+   "target": "node.outfall",
+   "name": "get_tidal_curve",
+   "form": "method",
+   "python": "OutfallView.get_tidal_curve",
+   "doc": "Return the tidal-curve index of a TIDAL outfall.",
+   "c": [
+    "swmm_node_get_outfall_tidal"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "node.outfall.get_timeseries",
+   "target": "node.outfall",
+   "name": "get_timeseries",
+   "form": "method",
+   "python": "OutfallView.get_timeseries",
+   "doc": "Return the stage-time-series index of a TIMESERIES outfall.",
+   "c": [
+    "swmm_node_get_outfall_timeseries"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "node.outfall.param",
+   "target": "node.outfall",
+   "name": "param",
+   "form": "property",
+   "python": "OutfallView.param",
+   "doc": "Get the outfall stage parameter (fixed stage, or current computed stage).",
+   "c": [
+    "swmm_node_get_outfall_param"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "node.outfall.route_to",
+   "target": "node.outfall",
+   "name": "route_to",
+   "form": "property",
+   "python": "OutfallView.route_to",
+   "doc": "Index of the subcatchment that receives outfall discharge, or -1 when none configured.",
+   "c": [
+    "swmm_node_get_outfall_route_to",
+    "swmm_node_set_outfall_route_to"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "node.outfall.set_stage",
+   "target": "node.outfall",
+   "name": "set_stage",
+   "form": "method",
+   "python": "OutfallView.set_stage",
+   "doc": "Configure a FIXED outfall with the given stage.",
+   "c": [
+    "swmm_node_set_outfall_stage"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "stage",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.outfall.set_tidal_curve",
+   "target": "node.outfall",
+   "name": "set_tidal_curve",
+   "form": "method",
+   "python": "OutfallView.set_tidal_curve",
+   "doc": "Configure a TIDAL outfall with the given tidal curve.",
+   "c": [
+    "swmm_node_set_outfall_tidal"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "curve_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.outfall.set_timeseries",
+   "target": "node.outfall",
+   "name": "set_timeseries",
+   "form": "method",
+   "python": "OutfallView.set_timeseries",
+   "doc": "Configure a TIMESERIES outfall with the given time series.",
+   "c": [
+    "swmm_node_set_outfall_timeseries"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "ts_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.outfall.type",
+   "target": "node.outfall",
+   "name": "type",
+   "form": "property",
+   "python": "OutfallView.type",
+   "doc": "Get the outfall boundary condition type.",
+   "c": [
+    "swmm_node_get_outfall_type",
+    "swmm_node_set_outfall_type"
+   ],
+   "type": "OutfallType",
+   "access": "rw"
+  },
+  {
+   "path": "node.outflow",
+   "target": "node",
+   "name": "outflow",
+   "form": "property",
+   "python": "Node.outflow",
+   "doc": "Get the total outflow from a node through downstream links.",
+   "c": [
+    "swmm_node_get_outflow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow",
+   "bulk": "nodes.outflows"
+  },
+  {
+   "path": "node.overflow",
+   "target": "node",
+   "name": "overflow",
+   "form": "property",
+   "python": "Node.overflow",
+   "doc": "Get the current overflow (flooding) rate at a node.",
+   "c": [
+    "swmm_node_get_overflow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow",
+   "bulk": "nodes.overflows"
+  },
+  {
+   "path": "node.ponded_area",
+   "target": "node",
+   "name": "ponded_area",
+   "form": "property",
+   "python": "Node.ponded_area",
+   "doc": "Get the ponded area at a node.",
+   "c": [
+    "swmm_node_get_ponded_area",
+    "swmm_node_set_pond_area"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "area"
+  },
+  {
+   "path": "node.quality",
+   "target": "node",
+   "name": "quality",
+   "form": "method",
+   "python": "Node.quality",
+   "doc": "Return the concentration of pollutant (index or id).",
+   "c": [
+    "swmm_node_get_quality",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "node.rim_depth",
+   "target": "node",
+   "name": "rim_depth",
+   "form": "property",
+   "python": "Node.rim_depth",
+   "doc": "Rendering-only rim (ground) depth above the invert; 0 = unset.",
+   "c": [
+    "swmm_node_get_rim_depth",
+    "swmm_node_set_rim_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "node.set_head_boundary",
+   "target": "node",
+   "name": "set_head_boundary",
+   "form": "method",
+   "python": "Node.set_head_boundary",
+   "doc": "Apply a one-shot head boundary value for this step.",
+   "c": [
+    "swmm_node_set_head_boundary"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "head",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "node.set_quality_mass_flux",
+   "target": "node",
+   "name": "set_quality_mass_flux",
+   "form": "method",
+   "python": "Node.set_quality_mass_flux",
+   "doc": "Inject a mass flux (model units / time) for pollutant.",
+   "c": [
+    "swmm_node_set_quality_mass_flux",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "mass_rate",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "node.stats.max_depth",
+   "target": "node.stats",
+   "name": "max_depth",
+   "form": "property",
+   "python": "NodeStatsView.max_depth",
+   "doc": "Get the maximum depth recorded at a node during the simulation.",
+   "c": [
+    "swmm_node_get_stat_max_depth"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length",
+   "phases": [
+    "ENDED",
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "node.stats.max_overflow",
+   "target": "node.stats",
+   "name": "max_overflow",
+   "form": "property",
+   "python": "NodeStatsView.max_overflow",
+   "doc": "Get the maximum overflow rate recorded at a node.",
+   "c": [
+    "swmm_node_get_stat_max_overflow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "node.stats.time_flooded",
+   "target": "node.stats",
+   "name": "time_flooded",
+   "form": "property",
+   "python": "NodeStatsView.time_flooded",
+   "doc": "Cumulative seconds the node has been flooded.",
+   "c": [
+    "swmm_node_get_stat_time_flooded"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "s"
+  },
+  {
+   "path": "node.stats.vol_flooded",
+   "target": "node.stats",
+   "name": "vol_flooded",
+   "form": "property",
+   "python": "NodeStatsView.vol_flooded",
+   "doc": "Get the total flood volume at a node over the simulation.",
+   "c": [
+    "swmm_node_get_stat_vol_flooded"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "node.storage.curve",
+   "target": "node.storage",
+   "name": "curve",
+   "form": "property",
+   "python": "StorageView.curve",
+   "doc": "Index of the storage curve (or -1 if functional).",
+   "c": [
+    "swmm_node_get_storage_curve",
+    "swmm_node_set_storage_curve"
+   ],
+   "type": "int",
+   "access": "rw"
+  },
+  {
+   "path": "node.storage.exfil_params",
+   "target": "node.storage",
+   "name": "exfil_params",
+   "form": "property",
+   "python": "StorageView.exfil_params",
+   "doc": "(suction, ksat, imd) Green-Ampt exfiltration parameters.",
+   "c": [
+    "swmm_node_get_exfil_params",
+    "swmm_node_set_exfil_params"
+   ],
+   "type": "Tuple[float, float, float]",
+   "access": "rw"
+  },
+  {
+   "path": "node.storage.functional",
+   "target": "node.storage",
+   "name": "functional",
+   "form": "property",
+   "python": "StorageView.functional",
+   "doc": "(a, b, c) coefficients of the functional storage relation.",
+   "c": [
+    "swmm_node_get_storage_functional",
+    "swmm_node_set_storage_functional"
+   ],
+   "type": "Tuple[float, float, float]",
+   "access": "rw"
+  },
+  {
+   "path": "node.storage.geometry",
+   "target": "node.storage",
+   "name": "geometry",
+   "form": "property",
+   "python": "StorageView.geometry",
+   "doc": "(p1, p2, p3) raw dimensions of a geometric storage shape.",
+   "c": [
+    "swmm_node_get_storage_geometry",
+    "swmm_node_set_storage_geometry"
+   ],
+   "type": "Tuple[float, float, float]",
+   "access": "rw"
+  },
+  {
+   "path": "node.storage.seep_rate",
+   "target": "node.storage",
+   "name": "seep_rate",
+   "form": "property",
+   "python": "StorageView.seep_rate",
+   "doc": "Get the seepage rate for a storage node.",
+   "c": [
+    "swmm_node_get_storage_seep_rate",
+    "swmm_node_set_storage_seep_rate"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "unverified"
+  },
+  {
+   "path": "node.storage.shape",
+   "target": "node.storage",
+   "name": "shape",
+   "form": "property",
+   "python": "StorageView.shape",
+   "doc": "The surface-area relation as a StorageShape.",
+   "c": [
+    "swmm_node_get_storage_shape",
+    "swmm_node_set_storage_shape"
+   ],
+   "type": "StorageShape",
+   "access": "rw"
+  },
+  {
+   "path": "node.surcharge_depth",
+   "target": "node",
+   "name": "surcharge_depth",
+   "form": "property",
+   "python": "Node.surcharge_depth",
+   "doc": "Get the surcharge depth above the node's crown.",
+   "c": [
+    "swmm_node_get_surcharge_depth",
+    "swmm_node_set_surcharge_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "node.tag",
+   "target": "node",
+   "name": "tag",
+   "form": "property",
+   "python": "Node.tag",
+   "doc": "The node's free-form tag string (from the INP [TAGS] section).",
+   "c": [
+    "swmm_node_get_tag",
+    "swmm_node_set_tag"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "node.type",
+   "target": "node",
+   "name": "type",
+   "form": "property",
+   "python": "Node.type",
+   "doc": "Get the type of a node.",
+   "c": [
+    "swmm_node_get_type"
+   ],
+   "type": "NodeType",
+   "access": "r"
+  },
+  {
+   "path": "node.virtual_rule_violation",
+   "target": "node",
+   "name": "virtual_rule_violation",
+   "form": "property",
+   "python": "Node.virtual_rule_violation",
+   "doc": "Dry-run check of the virtual-junction usage rules for this node.",
+   "c": [
+    "swmm_node_virtual_eligible"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "node.volume",
+   "target": "node",
+   "name": "volume",
+   "form": "property",
+   "python": "Node.volume",
+   "doc": "Get the current stored water volume at a node.",
+   "c": [
+    "swmm_node_get_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume",
+   "bulk": "nodes.volumes"
+  },
+  {
+   "path": "nodes.add",
+   "target": "nodes",
+   "name": "add",
+   "form": "method",
+   "python": "Nodes.add",
+   "doc": "Append a new node and return a wrapper for it.",
+   "c": [
+    "swmm_node_add",
+    "swmm_node_index"
+   ],
+   "returns": "Node",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "node_type",
+     "type": "NodeType",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.depths",
+   "target": "nodes",
+   "name": "depths",
+   "form": "property",
+   "python": "Nodes.depths",
+   "doc": "All node depths as a 1-D float64 array, length len(self).",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_depths_bulk",
+    "swmm_node_set_depths_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "rw",
+   "phases": [
+    "RUNNING"
+   ],
+   "units": "length"
+  },
+  {
+   "path": "nodes.get_id",
+   "target": "nodes",
+   "name": "get_id",
+   "form": "method",
+   "python": "Nodes.get_id",
+   "doc": "Return the string id of the node at integer index idx.",
+   "c": [
+    "swmm_node_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.get_index",
+   "target": "nodes",
+   "name": "get_index",
+   "form": "method",
+   "python": "Nodes.get_index",
+   "doc": "Return the integer index of a node by id, or raise :exc:`KeyError`.",
+   "c": [
+    "swmm_node_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.heads",
+   "target": "nodes",
+   "name": "heads",
+   "form": "property",
+   "python": "Nodes.heads",
+   "doc": "Get hydraulic heads for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_heads_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "nodes.ids",
+   "target": "nodes",
+   "name": "ids",
+   "form": "property",
+   "python": "Nodes.ids",
+   "doc": "All node ids as a numpy.ndarray of dtype object.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_ids_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "nodes.inflows",
+   "target": "nodes",
+   "name": "inflows",
+   "form": "property",
+   "python": "Nodes.inflows",
+   "doc": "Get total inflows for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_inflows_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "nodes.lateral_inflows",
+   "target": "nodes",
+   "name": "lateral_inflows",
+   "form": "property",
+   "python": "Nodes.lateral_inflows",
+   "doc": "Get current lateral inflows for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_lateral_inflows_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "nodes.losses",
+   "target": "nodes",
+   "name": "losses",
+   "form": "property",
+   "python": "Nodes.losses",
+   "doc": "Get accumulated node losses (exfil + evap) for all nodes in one call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_losses_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "nodes.outflows",
+   "target": "nodes",
+   "name": "outflows",
+   "form": "property",
+   "python": "Nodes.outflows",
+   "doc": "Get current outflows for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_outflows_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "nodes.overflows",
+   "target": "nodes",
+   "name": "overflows",
+   "form": "property",
+   "python": "Nodes.overflows",
+   "doc": "Get overflow rates for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_overflows_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "nodes.pop_last",
+   "target": "nodes",
+   "name": "pop_last",
+   "form": "method",
+   "python": "Nodes.pop_last",
+   "doc": "Remove the most recently added node (must match node_id).",
+   "c": [
+    "swmm_node_pop_last"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.qualities",
+   "target": "nodes",
+   "name": "qualities",
+   "form": "method",
+   "python": "Nodes.qualities",
+   "doc": "Per-node concentration of pollutant as a numpy array.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_quality_bulk",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.rename",
+   "target": "nodes",
+   "name": "rename",
+   "form": "method",
+   "python": "Nodes.rename",
+   "doc": "Rename the node addressed by key.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_node_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "nodes.set_lateral_inflows",
+   "target": "nodes",
+   "name": "set_lateral_inflows",
+   "form": "method",
+   "python": "Nodes.set_lateral_inflows",
+   "doc": "Vectorised setter for lateral inflows (write-only; no symmetric read property because the engine *also* updates this field internally, so a property would be misleading).",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_set_lat_inflows_bulk"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "values",
+     "type": "NDArray[Any]",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "nodes.volumes",
+   "target": "nodes",
+   "name": "volumes",
+   "form": "property",
+   "python": "Nodes.volumes",
+   "doc": "Get current stored volumes for all nodes in a single call.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_get_volumes_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "open",
+   "target": "solver",
+   "name": "open",
+   "form": "method",
+   "python": "Solver.open",
+   "doc": "Open the input file; transition to OPENED.",
+   "c": [
+    "swmm_engine_open"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "plugin_lib",
+     "type": "Optional[Union[str, PathLike[str]]]",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "open_errors",
+   "target": "solver",
+   "name": "open_errors",
+   "form": "property",
+   "python": "Solver.open_errors",
+   "doc": "Validation errors accumulated on the engine during open.",
+   "c": [
+    "swmm_get_error_at",
+    "swmm_get_error_count"
+   ],
+   "type": "list[str]",
+   "access": "r"
+  },
+  {
+   "path": "open_runoff_interface_read",
+   "target": "solver",
+   "name": "open_runoff_interface_read",
+   "form": "method",
+   "python": "Solver.open_runoff_interface_read",
+   "doc": "Open the runoff interface file in USE mode.",
+   "c": [
+    "swmm_runoff_iface_open_read"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "open_runoff_interface_write",
+   "target": "solver",
+   "name": "open_runoff_interface_write",
+   "form": "method",
+   "python": "Solver.open_runoff_interface_write",
+   "doc": "Open the runoff interface file in SAVE mode.",
+   "c": [
+    "swmm_runoff_iface_open_write"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "open_warnings",
+   "target": "solver",
+   "name": "open_warnings",
+   "form": "property",
+   "python": "Solver.open_warnings",
+   "doc": "Warnings accumulated on the engine during open.",
+   "c": [
+    "swmm_get_warning_at",
+    "swmm_get_warning_count"
+   ],
+   "type": "list[str]",
+   "access": "r"
+  },
+  {
+   "path": "options.crs",
+   "target": "options",
+   "name": "crs",
+   "form": "property",
+   "python": "SimulationOptions.crs",
+   "doc": "",
+   "c": [],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "target": "options",
+   "form": "item",
+   "python": "SimulationOptions[]",
+   "doc": "View over the [OPTIONS] block. See Solver.options.",
+   "path": "options.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "path": "options.end_datetime",
+   "target": "options",
+   "name": "end_datetime",
+   "form": "property",
+   "python": "SimulationOptions.end_datetime",
+   "doc": "",
+   "c": [],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "target": "options.ext",
+   "form": "item",
+   "python": "_OptionsExtView[]",
+   "doc": "Sub-mapping for the [OPTIONS_EXT] block.",
+   "path": "options.ext.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "target": "options.ext",
+   "form": "item",
+   "python": "_OptionsExtView[]",
+   "doc": "Sub-mapping for the [OPTIONS_EXT] block.",
+   "path": "options.ext.get_item",
+   "name": "get_item",
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_options_get_ext"
+   ]
+  },
+  {
+   "target": "options.ext",
+   "form": "item",
+   "python": "_OptionsExtView[]",
+   "doc": "Sub-mapping for the [OPTIONS_EXT] block.",
+   "path": "options.ext.items",
+   "name": "items",
+   "returns": "list[tuple[str, str]]",
+   "params": [],
+   "c": [
+    "swmm_options_get_ext"
+   ]
+  },
+  {
+   "target": "options.ext",
+   "form": "item",
+   "python": "_OptionsExtView[]",
+   "doc": "Sub-mapping for the [OPTIONS_EXT] block.",
+   "path": "options.ext.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_options_set_ext"
+   ]
+  },
+  {
+   "target": "options",
+   "form": "item",
+   "python": "SimulationOptions[]",
+   "doc": "View over the [OPTIONS] block. See Solver.options.",
+   "path": "options.get_item",
+   "name": "get_item",
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_options_get"
+   ]
+  },
+  {
+   "target": "options",
+   "form": "item",
+   "python": "SimulationOptions[]",
+   "doc": "View over the [OPTIONS] block. See Solver.options.",
+   "path": "options.items",
+   "name": "items",
+   "returns": "list[tuple[str, str]]",
+   "params": [],
+   "c": [
+    "swmm_options_get"
+   ]
+  },
+  {
+   "path": "options.report_start_datetime",
+   "target": "options",
+   "name": "report_start_datetime",
+   "form": "property",
+   "python": "SimulationOptions.report_start_datetime",
+   "doc": "",
+   "c": [],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "options.routing_step",
+   "target": "options",
+   "name": "routing_step",
+   "form": "property",
+   "python": "SimulationOptions.routing_step",
+   "doc": "",
+   "c": [],
+   "type": "timedelta",
+   "access": "r"
+  },
+  {
+   "target": "options",
+   "form": "item",
+   "python": "SimulationOptions[]",
+   "doc": "View over the [OPTIONS] block. See Solver.options.",
+   "path": "options.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_options_set"
+   ]
+  },
+  {
+   "path": "options.start_datetime",
+   "target": "options",
+   "name": "start_datetime",
+   "form": "property",
+   "python": "SimulationOptions.start_datetime",
+   "doc": "",
+   "c": [],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "output.close",
+   "target": "output",
+   "name": "close",
+   "form": "method",
+   "python": "OutputReader.close",
+   "doc": "Close the binary output file and release its handle.",
+   "c": [
+    "swmm_output_close"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "output.error_code",
+   "target": "output",
+   "name": "error_code",
+   "form": "property",
+   "python": "OutputReader.error_code",
+   "doc": "SWMM error code stored in the file footer (0 = clean run).",
+   "c": [
+    "swmm_output_get_error_code"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.flow_units",
+   "target": "output",
+   "name": "flow_units",
+   "form": "property",
+   "python": "OutputReader.flow_units",
+   "doc": "Get the flow units code.",
+   "c": [
+    "swmm_output_get_flow_units"
+   ],
+   "type": "FlowUnits",
+   "access": "r"
+  },
+  {
+   "path": "output.is_live",
+   "target": "output",
+   "name": "is_live",
+   "form": "property",
+   "python": "OutputReader.is_live",
+   "doc": "Whether the reader is waiting for the writer's closing records.",
+   "c": [
+    "swmm_output_is_live"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "output.link_attributes",
+   "target": "output",
+   "name": "link_attributes",
+   "form": "method",
+   "python": "OutputReader.link_attributes",
+   "doc": "Return all output variables for *link* at output *period* as a dict.",
+   "c": [
+    "swmm_output_get_link_attribute",
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_count",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "Dict[Union[OutLinkVar, int], float]",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.link_count",
+   "target": "output",
+   "name": "link_count",
+   "form": "property",
+   "python": "OutputReader.link_count",
+   "doc": "Get the number of links in the output file.",
+   "c": [
+    "swmm_output_get_link_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.link_ids",
+   "target": "output",
+   "name": "link_ids",
+   "form": "property",
+   "python": "OutputReader.link_ids",
+   "doc": "Get the string ID of a link by index.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_link_id"
+   ],
+   "type": "List[str]",
+   "access": "r"
+  },
+  {
+   "path": "output.link_result",
+   "target": "output",
+   "name": "link_result",
+   "form": "method",
+   "python": "OutputReader.link_result",
+   "doc": "Return an array of *var* values for every link at output *period*.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_link_result"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutLinkVar",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.link_series",
+   "target": "output",
+   "name": "link_series",
+   "form": "method",
+   "python": "OutputReader.link_series",
+   "doc": "Return the time series of *var* for *link* over the reporting window.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_link_series",
+    "swmm_output_get_node_count",
+    "swmm_output_get_period_count",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutLinkVar",
+     "required": true
+    },
+    {
+     "name": "start",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "end",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "output.node_attributes",
+   "target": "output",
+   "name": "node_attributes",
+   "form": "method",
+   "python": "OutputReader.node_attributes",
+   "doc": "Return all output variables for *node* at output *period* as a dict.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_attribute",
+    "swmm_output_get_node_count",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "Dict[Union[OutNodeVar, int], float]",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.node_count",
+   "target": "output",
+   "name": "node_count",
+   "form": "property",
+   "python": "OutputReader.node_count",
+   "doc": "Get the number of nodes in the output file.",
+   "c": [
+    "swmm_output_get_node_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.node_ids",
+   "target": "output",
+   "name": "node_ids",
+   "form": "property",
+   "python": "OutputReader.node_ids",
+   "doc": "Get the string ID of a node by index.",
+   "c": [
+    "swmm_output_get_node_count",
+    "swmm_output_get_node_id"
+   ],
+   "type": "List[str]",
+   "access": "r"
+  },
+  {
+   "path": "output.node_result",
+   "target": "output",
+   "name": "node_result",
+   "form": "method",
+   "python": "OutputReader.node_result",
+   "doc": "All nodes' value of var at period.",
+   "c": [
+    "swmm_output_get_node_count",
+    "swmm_output_get_node_result"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutNodeVar",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.node_series",
+   "target": "output",
+   "name": "node_series",
+   "form": "method",
+   "python": "OutputReader.node_series",
+   "doc": "Return the time series of *var* for *node* over the reporting window.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_count",
+    "swmm_output_get_node_series",
+    "swmm_output_get_period_count",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutNodeVar",
+     "required": true
+    },
+    {
+     "name": "start",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "end",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "output.node_stats",
+   "target": "output",
+   "name": "node_stats",
+   "form": "method",
+   "python": "OutputReader.node_stats",
+   "doc": "Cumulative flooding/overflow stats for node.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_count",
+    "swmm_output_get_node_stat_max_depth",
+    "swmm_output_get_node_stat_max_overflow",
+    "swmm_output_get_node_stat_time_flooded",
+    "swmm_output_get_node_stat_vol_flooded",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "_OutputNodeStats",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.period_count",
+   "target": "output",
+   "name": "period_count",
+   "form": "property",
+   "python": "OutputReader.period_count",
+   "doc": "Get the number of reporting periods (timesteps) in the output file.",
+   "c": [
+    "swmm_output_get_period_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.period_times",
+   "target": "output",
+   "name": "period_times",
+   "form": "property",
+   "python": "OutputReader.period_times",
+   "doc": "All reporting-period times as a datetime64[s] numpy array.",
+   "c": [
+    "swmm_output_get_period_count",
+    "swmm_output_get_period_time"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "output.pollutant_count",
+   "target": "output",
+   "name": "pollutant_count",
+   "form": "property",
+   "python": "OutputReader.pollutant_count",
+   "doc": "Get the number of pollutants in the output file.",
+   "c": [
+    "swmm_output_get_pollut_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.pollutant_ids",
+   "target": "output",
+   "name": "pollutant_ids",
+   "form": "property",
+   "python": "OutputReader.pollutant_ids",
+   "doc": "Species (pollutant) column names, in column order.",
+   "c": [
+    "swmm_output_get_pollut_count",
+    "swmm_output_get_pollut_id"
+   ],
+   "type": "List[str]",
+   "access": "r"
+  },
+  {
+   "path": "output.refresh",
+   "target": "output",
+   "name": "refresh",
+   "form": "method",
+   "python": "OutputReader.refresh",
+   "doc": "Refresh completed periods and invalidate cached timestamps.",
+   "c": [
+    "swmm_output_refresh"
+   ],
+   "returns": "int",
+   "params": []
+  },
+  {
+   "path": "output.report_step",
+   "target": "output",
+   "name": "report_step",
+   "form": "property",
+   "python": "OutputReader.report_step",
+   "doc": "Get the report step in seconds.",
+   "c": [
+    "swmm_output_get_report_step"
+   ],
+   "type": "timedelta",
+   "access": "r"
+  },
+  {
+   "path": "output.start_datetime",
+   "target": "output",
+   "name": "start_datetime",
+   "form": "property",
+   "python": "OutputReader.start_datetime",
+   "doc": "Get the simulation start date as a SWMM DateTime double.",
+   "c": [
+    "swmm_output_get_start_date"
+   ],
+   "type": "datetime",
+   "access": "r"
+  },
+  {
+   "path": "output.subcatchment_attributes",
+   "target": "output",
+   "name": "subcatchment_attributes",
+   "form": "method",
+   "python": "OutputReader.subcatchment_attributes",
+   "doc": "Return all output variables for *sub* at output *period* as a dict.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_count",
+    "swmm_output_get_subcatch_attribute",
+    "swmm_output_get_subcatch_count"
+   ],
+   "returns": "Dict[Union[OutSubcatchVar, int], float]",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.subcatchment_count",
+   "target": "output",
+   "name": "subcatchment_count",
+   "form": "property",
+   "python": "OutputReader.subcatchment_count",
+   "doc": "Get the number of subcatchments in the output file.",
+   "c": [
+    "swmm_output_get_subcatch_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "output.subcatchment_ids",
+   "target": "output",
+   "name": "subcatchment_ids",
+   "form": "property",
+   "python": "OutputReader.subcatchment_ids",
+   "doc": "Get the string ID of a subcatchment by index.",
+   "c": [
+    "swmm_output_get_subcatch_count",
+    "swmm_output_get_subcatch_id"
+   ],
+   "type": "List[str]",
+   "access": "r"
+  },
+  {
+   "path": "output.subcatchment_result",
+   "target": "output",
+   "name": "subcatchment_result",
+   "form": "method",
+   "python": "OutputReader.subcatchment_result",
+   "doc": "Return an array of *var* values for every subcatchment at output *period*.",
+   "c": [
+    "swmm_output_get_subcatch_count",
+    "swmm_output_get_subcatch_result"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutSubcatchVar",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.subcatchment_series",
+   "target": "output",
+   "name": "subcatchment_series",
+   "form": "method",
+   "python": "OutputReader.subcatchment_series",
+   "doc": "Return the time series of *var* for *sub* over the reporting window.",
+   "c": [
+    "swmm_output_get_link_count",
+    "swmm_output_get_node_count",
+    "swmm_output_get_period_count",
+    "swmm_output_get_subcatch_count",
+    "swmm_output_get_subcatch_series"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutSubcatchVar",
+     "required": true
+    },
+    {
+     "name": "start",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "end",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "output.system_result",
+   "target": "output",
+   "name": "system_result",
+   "form": "method",
+   "python": "OutputReader.system_result",
+   "doc": "Return the system-wide *var* value at output *period*.",
+   "c": [
+    "swmm_output_get_system_result"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "period",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "var",
+     "type": "OutSystemVar",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "output.system_series",
+   "target": "output",
+   "name": "system_series",
+   "form": "method",
+   "python": "OutputReader.system_series",
+   "doc": "Return the system-wide time series of *var* over the reporting window.",
+   "c": [
+    "swmm_output_get_period_count",
+    "swmm_output_get_system_series"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "var",
+     "type": "OutSystemVar",
+     "required": true
+    },
+    {
+     "name": "start",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "end",
+     "type": "Optional[int]",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "output.version",
+   "target": "output",
+   "name": "version",
+   "form": "property",
+   "python": "OutputReader.version",
+   "doc": "Get the SWMM version stored in the output file.",
+   "c": [
+    "swmm_output_get_version"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "pattern.factors",
+   "target": "pattern",
+   "name": "factors",
+   "form": "property",
+   "python": "Pattern.factors",
+   "doc": "The pattern's multiplier factors as a list of floats.",
+   "c": [
+    "swmm_pattern_get_factor",
+    "swmm_pattern_get_factor_count"
+   ],
+   "type": "list[float]",
+   "access": "r"
+  },
+  {
+   "path": "pattern.id",
+   "target": "pattern",
+   "name": "id",
+   "form": "property",
+   "python": "Pattern.id",
+   "doc": "The pattern's string identifier (from the INP [PATTERNS] section).",
+   "c": [
+    "swmm_pattern_id"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "pattern.index",
+   "target": "pattern",
+   "name": "index",
+   "form": "property",
+   "python": "Pattern.index",
+   "doc": "The pattern's zero-based index within Patterns.",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "pattern.set_factors",
+   "target": "pattern",
+   "name": "set_factors",
+   "form": "method",
+   "python": "Pattern.set_factors",
+   "doc": "Replace the pattern factors.",
+   "c": [
+    "swmm_pattern_set_factors"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "values",
+     "type": "Iterable[float]",
+     "required": true
+    },
+    {
+     "name": "type",
+     "type": "PatternType",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "pattern.type",
+   "target": "pattern",
+   "name": "type",
+   "form": "property",
+   "python": "Pattern.type",
+   "doc": "The pattern's type as a PatternType (MONTHLY/DAILY/HOURLY/WEEKEND).",
+   "c": [
+    "swmm_pattern_get_type"
+   ],
+   "type": "PatternType",
+   "access": "r"
+  },
+  {
+   "path": "patterns.add",
+   "target": "patterns",
+   "name": "add",
+   "form": "method",
+   "python": "Patterns.add",
+   "doc": "Append a new time pattern and return its wrapper.",
+   "c": [
+    "swmm_pattern_add",
+    "swmm_pattern_count"
+   ],
+   "returns": "Pattern",
+   "params": [
+    {
+     "name": "pattern_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "type",
+     "type": "PatternType",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "patterns.get_index",
+   "target": "patterns",
+   "name": "get_index",
+   "form": "method",
+   "python": "Patterns.get_index",
+   "doc": "Resolve a pattern's zero-based index from its string id.",
+   "c": [
+    "swmm_pattern_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "pattern_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "patterns.remove",
+   "target": "patterns",
+   "name": "remove",
+   "form": "method",
+   "python": "Patterns.remove",
+   "doc": "Remove a pattern (by index or id), clearing any reference sites.",
+   "c": [
+    "swmm_pattern_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "patterns.rename",
+   "target": "patterns",
+   "name": "rename",
+   "form": "method",
+   "python": "Patterns.rename",
+   "doc": "Rename a pattern, updating every stored reference to it.",
+   "c": [
+    "swmm_pattern_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "pollutant.co_pollutant",
+   "target": "pollutant",
+   "name": "co_pollutant",
+   "form": "property",
+   "python": "Pollutant.co_pollutant",
+   "doc": "(Pollutant, fraction) or None if no co-pollutant.",
+   "c": [
+    "swmm_pollutant_get_co_pollutant"
+   ],
+   "type": "Optional[Tuple['Pollutant', float]]",
+   "access": "r"
+  },
+  {
+   "path": "pollutant.dwf_conc",
+   "target": "pollutant",
+   "name": "dwf_conc",
+   "form": "property",
+   "python": "Pollutant.dwf_conc",
+   "doc": "Dry-weather-flow concentration of this pollutant (pollutant units).",
+   "c": [
+    "swmm_pollutant_get_dwf_conc",
+    "swmm_pollutant_set_dwf_conc"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "pollutant.gw_conc",
+   "target": "pollutant",
+   "name": "gw_conc",
+   "form": "property",
+   "python": "Pollutant.gw_conc",
+   "doc": "Get the pollutant concentration in groundwater.",
+   "c": [
+    "swmm_pollutant_get_gw_conc",
+    "swmm_pollutant_set_gw_conc"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "pollutant.id",
+   "target": "pollutant",
+   "name": "id",
+   "form": "property",
+   "python": "Pollutant.id",
+   "doc": "Get the string identifier of a pollutant by index.",
+   "c": [
+    "swmm_pollutant_id"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "pollutant.index",
+   "target": "pollutant",
+   "name": "index",
+   "form": "property",
+   "python": "Pollutant.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "pollutant.init_conc",
+   "target": "pollutant",
+   "name": "init_conc",
+   "form": "property",
+   "python": "Pollutant.init_conc",
+   "doc": "Get the initial concentration throughout the conveyance system.",
+   "c": [
+    "swmm_pollutant_get_init_conc",
+    "swmm_pollutant_set_init_conc"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "pollutant.kdecay",
+   "target": "pollutant",
+   "name": "kdecay",
+   "form": "property",
+   "python": "Pollutant.kdecay",
+   "doc": "Get the first-order decay coefficient.",
+   "c": [
+    "swmm_pollutant_get_kdecay",
+    "swmm_pollutant_set_kdecay"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "1/day"
+  },
+  {
+   "path": "pollutant.mwt",
+   "target": "pollutant",
+   "name": "mwt",
+   "form": "property",
+   "python": "Pollutant.mwt",
+   "doc": "Get the molecular weight of a pollutant.",
+   "c": [
+    "swmm_pollutant_get_mwt",
+    "swmm_pollutant_set_mwt"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "g/mol"
+  },
+  {
+   "path": "pollutant.rain_conc",
+   "target": "pollutant",
+   "name": "rain_conc",
+   "form": "property",
+   "python": "Pollutant.rain_conc",
+   "doc": "Get the pollutant concentration in rainfall.",
+   "c": [
+    "swmm_pollutant_get_rain_conc",
+    "swmm_pollutant_set_rain_conc"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "pollutant.rdii_conc",
+   "target": "pollutant",
+   "name": "rdii_conc",
+   "form": "property",
+   "python": "Pollutant.rdii_conc",
+   "doc": "Get the RDII concentration.",
+   "c": [
+    "swmm_pollutant_get_rdii_conc",
+    "swmm_pollutant_set_rdii_conc"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "pollutant.set_co_pollutant",
+   "target": "pollutant",
+   "name": "set_co_pollutant",
+   "form": "method",
+   "python": "Pollutant.set_co_pollutant",
+   "doc": "Link this pollutant to co (id, index, or Pollutant) with the given fraction.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_pollutant_set_co_pollutant"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "co",
+     "type": "Union['Pollutant', Union[int, str]]",
+     "required": true
+    },
+    {
+     "name": "fraction",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "pollutant.snow_only",
+   "target": "pollutant",
+   "name": "snow_only",
+   "form": "property",
+   "python": "Pollutant.snow_only",
+   "doc": "Get whether a pollutant only builds up during snowfall events.",
+   "c": [
+    "swmm_pollutant_get_snow_only",
+    "swmm_pollutant_set_snow_only"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "pollutant.units",
+   "target": "pollutant",
+   "name": "units",
+   "form": "property",
+   "python": "Pollutant.units",
+   "doc": "Change the concentration units (a ConcentrationUnits value or its integer code: 0=MG/L, 1=UG/L, 2=#/L).",
+   "c": [
+    "swmm_pollutant_get_units",
+    "swmm_pollutant_set_units"
+   ],
+   "type": "ConcentrationUnits",
+   "access": "rw"
+  },
+  {
+   "path": "pollutants.add",
+   "target": "pollutants",
+   "name": "add",
+   "form": "method",
+   "python": "Pollutants.add",
+   "doc": "Add a new pollutant *pollut_id* measured in *units* and return its Pollutant.",
+   "c": [
+    "swmm_pollutant_add",
+    "swmm_pollutant_index"
+   ],
+   "returns": "Pollutant",
+   "params": [
+    {
+     "name": "pollut_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "units",
+     "type": "ConcentrationUnits",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "pollutants.get_id",
+   "target": "pollutants",
+   "name": "get_id",
+   "form": "method",
+   "python": "Pollutants.get_id",
+   "doc": "Return the ID string of the pollutant at *idx*.",
+   "c": [
+    "swmm_pollutant_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "pollutants.get_index",
+   "target": "pollutants",
+   "name": "get_index",
+   "form": "method",
+   "python": "Pollutants.get_index",
+   "doc": "Return the zero-based index of pollutant *pollut_id* (raises if unknown).",
+   "c": [
+    "swmm_pollutant_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "pollut_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "pollutants.rename",
+   "target": "pollutants",
+   "name": "rename",
+   "form": "method",
+   "python": "Pollutants.rename",
+   "doc": "Rename the pollutant identified by *key* to *new_id*.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_pollutant_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "pollutants.set_link_quality",
+   "target": "pollutants",
+   "name": "set_link_quality",
+   "form": "method",
+   "python": "Pollutants.set_link_quality",
+   "doc": "Set runtime concentration at link for pollutant.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_link_set_quality",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "conc",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "pollutants.set_node_quality",
+   "target": "pollutants",
+   "name": "set_node_quality",
+   "form": "method",
+   "python": "Pollutants.set_node_quality",
+   "doc": "Set runtime concentration at node for pollutant.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_node_set_quality",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "conc",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "phases": [
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "process_components.get_index",
+   "target": "process_components",
+   "name": "get_index",
+   "form": "method",
+   "python": "ProcessComponents.get_index",
+   "doc": "Return the registration index of *component_id*.",
+   "c": [
+    "swmm_process_component_find"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "component_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "process_components",
+   "form": "item",
+   "python": "ProcessComponents[]",
+   "doc": "",
+   "path": "process_components.get_item",
+   "name": "get_item",
+   "returns": "ProcessComponent",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_process_component_get"
+   ]
+  },
+  {
+   "target": "process_components",
+   "form": "item",
+   "python": "ProcessComponents[]",
+   "doc": "",
+   "path": "process_components.items",
+   "name": "items",
+   "returns": "list[tuple[Union[int, str], ProcessComponent]]",
+   "params": [],
+   "c": [
+    "swmm_process_component_count",
+    "swmm_process_component_get"
+   ]
+  },
+  {
+   "path": "process_components.known",
+   "target": "process_components",
+   "name": "known",
+   "form": "method",
+   "python": "ProcessComponents.known",
+   "doc": "Built-in component vocabulary, including unimplemented placeholders.",
+   "c": [
+    "swmm_process_component_known_count",
+    "swmm_process_component_known_get"
+   ],
+   "returns": "tuple[KnownProcessComponent, ...]",
+   "params": [],
+   "static": true
+  },
+  {
+   "path": "process_components.register",
+   "target": "process_components",
+   "name": "register",
+   "form": "method",
+   "python": "ProcessComponents.register",
+   "doc": "Register a process component and return the new row.",
+   "c": [
+    "swmm_process_component_get",
+    "swmm_process_component_register"
+   ],
+   "returns": "ProcessComponent",
+   "params": [
+    {
+     "name": "component_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "config_path",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "process_components.remove",
+   "target": "process_components",
+   "name": "remove",
+   "form": "method",
+   "python": "ProcessComponents.remove",
+   "doc": "Remove one registration, by index or by id.",
+   "c": [
+    "swmm_process_component_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.clear_treatment",
+   "target": "quality",
+   "name": "clear_treatment",
+   "form": "method",
+   "python": "Quality.clear_treatment",
+   "doc": "Remove any treatment for *pollutant* at *node*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_treatment_clear"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.get_buildup",
+   "target": "quality",
+   "name": "get_buildup",
+   "form": "method",
+   "python": "Quality.get_buildup",
+   "doc": "Return {\"func\": BuildupFunc, \"c1\": ..., \"c2\": ..., \"c3\": ..., \"normalizer\": int}.",
+   "c": [
+    "swmm_buildup_get",
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "Dict[str, object]",
+   "params": [
+    {
+     "name": "landuse",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.get_treatment",
+   "target": "quality",
+   "name": "get_treatment",
+   "form": "method",
+   "python": "Quality.get_treatment",
+   "doc": "Return the treatment expression for *pollutant* at *node*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_treatment_get"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.get_washoff",
+   "target": "quality",
+   "name": "get_washoff",
+   "form": "method",
+   "python": "Quality.get_washoff",
+   "doc": "Return the washoff parameters for *landuse* / *pollutant* as a dict.",
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_washoff_get"
+   ],
+   "returns": "Dict[str, object]",
+   "params": [
+    {
+     "name": "landuse",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.landuses.add",
+   "target": "quality.landuses",
+   "name": "add",
+   "form": "method",
+   "python": "Landuses.add",
+   "doc": "Add a new land use *landuse_id* and return its Landuse handle.",
+   "c": [
+    "swmm_landuse_add",
+    "swmm_landuse_index"
+   ],
+   "returns": "Landuse",
+   "params": [
+    {
+     "name": "landuse_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.landuses.get_id",
+   "target": "quality.landuses",
+   "name": "get_id",
+   "form": "method",
+   "python": "Landuses.get_id",
+   "doc": "Return the ID string of the land use at *idx*.",
+   "c": [
+    "swmm_landuse_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.landuses.get_index",
+   "target": "quality.landuses",
+   "name": "get_index",
+   "form": "method",
+   "python": "Landuses.get_index",
+   "doc": "Return the zero-based index of land use *landuse_id* (raises if unknown).",
+   "c": [
+    "swmm_landuse_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "landuse_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.set_buildup",
+   "target": "quality",
+   "name": "set_buildup",
+   "form": "method",
+   "python": "Quality.set_buildup",
+   "doc": "Configure buildup for (landuse, pollutant).",
+   "c": [
+    "swmm_buildup_set",
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "landuse",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "func",
+     "type": "BuildupFunc",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "c1",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "c2",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "c3",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "normalizer",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "quality.set_treatment",
+   "target": "quality",
+   "name": "set_treatment",
+   "form": "method",
+   "python": "Quality.set_treatment",
+   "doc": "Set the treatment *expression* for *pollutant* at *node*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_treatment_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "expression",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "quality.set_washoff",
+   "target": "quality",
+   "name": "set_washoff",
+   "form": "method",
+   "python": "Quality.set_washoff",
+   "doc": "Set the washoff function and coefficients for *landuse* / *pollutant*.",
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_washoff_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "landuse",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "func",
+     "type": "WashoffFunc",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "coeff",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "expon",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "sweep_effic",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "bmp_effic",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "quality.validate_treatment_expression",
+   "target": "quality",
+   "name": "validate_treatment_expression",
+   "form": "method",
+   "python": "Quality.validate_treatment_expression",
+   "doc": "Validate a treatment expression WITHOUT modifying the engine.",
+   "c": [
+    "swmm_treatment_validate_expression"
+   ],
+   "returns": "tuple[bool, str, int]",
+   "params": [
+    {
+     "name": "expression",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.apply_text",
+   "target": "reactions",
+   "name": "apply_text",
+   "form": "method",
+   "python": "Reactions.apply_text",
+   "doc": "Transactionally replace the whole reaction system from .rxn text.",
+   "c": [
+    "swmm_reactions_apply_text"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.check_text",
+   "target": "reactions",
+   "name": "check_text",
+   "form": "method",
+   "python": "Reactions.check_text",
+   "doc": "Dry-run a whole .rxn file against this model. **Never mutates.**",
+   "c": [
+    "swmm_reactions_check_text"
+   ],
+   "returns": "ExpressionDiagnostic",
+   "params": [
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.coefficients.add",
+   "target": "reactions.coefficients",
+   "name": "add",
+   "form": "method",
+   "python": "_CoefficientCollection.add",
+   "doc": "Add a coefficient and return a live view of it.",
+   "c": [
+    "swmm_reaction_coeff_add",
+    "swmm_reaction_coeff_count"
+   ],
+   "returns": "ReactionCoefficient",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "parameter",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.coefficients.get_index",
+   "target": "reactions.coefficients",
+   "name": "get_index",
+   "form": "method",
+   "python": "_CoefficientCollection.get_index",
+   "doc": "Resolve int | str *key* to a zero-based coefficient index (string lookup is an O(n) exact-name scan).",
+   "c": [],
+   "returns": "int",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.coefficients.remove",
+   "target": "reactions.coefficients",
+   "name": "remove",
+   "form": "method",
+   "python": "_CoefficientCollection.remove",
+   "doc": "Remove the coefficient named or indexed by *key*.",
+   "c": [
+    "swmm_reaction_coeff_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.functions",
+   "target": "reactions",
+   "name": "functions",
+   "form": "method",
+   "python": "Reactions.functions",
+   "doc": "Return every built-in math function usable in an expression.",
+   "c": [
+    "swmm_reaction_function_count",
+    "swmm_reaction_function_get"
+   ],
+   "returns": "Tuple[ReactionFunction, ...]",
+   "params": [],
+   "static": true
+  },
+  {
+   "path": "reactions.get_option",
+   "target": "reactions",
+   "name": "get_option",
+   "form": "method",
+   "python": "Reactions.get_option",
+   "doc": "Read one [REACTION_OPTIONS] value as its canonical token.",
+   "c": [
+    "swmm_reaction_option_get"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.hydraulic_variables",
+   "target": "reactions",
+   "name": "hydraulic_variables",
+   "form": "method",
+   "python": "Reactions.hydraulic_variables",
+   "doc": "Return every built-in hydraulic variable usable in an expression.",
+   "c": [
+    "swmm_reaction_hydvar_count",
+    "swmm_reaction_hydvar_get"
+   ],
+   "returns": "Tuple[ReactionHydVar, ...]",
+   "params": [],
+   "static": true
+  },
+  {
+   "target": "reactions.initial",
+   "form": "item",
+   "python": "_InitialQualityRows[]",
+   "doc": "",
+   "path": "reactions.initial.get_item",
+   "name": "get_item",
+   "returns": "ReactionInitialEntry",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_reaction_init_elem_count",
+    "swmm_reaction_init_elem_get"
+   ]
+  },
+  {
+   "target": "reactions.initial",
+   "form": "item",
+   "python": "_InitialQualityRows[]",
+   "doc": "",
+   "path": "reactions.initial.items",
+   "name": "items",
+   "returns": "list[tuple[int, ReactionInitialEntry]]",
+   "params": [],
+   "c": [
+    "swmm_reaction_init_elem_count",
+    "swmm_reaction_init_elem_get"
+   ]
+  },
+  {
+   "path": "reactions.initial.remove",
+   "target": "reactions.initial",
+   "name": "remove",
+   "form": "method",
+   "python": "_InitialQualityRows.remove",
+   "doc": "Remove initial-quality row *row*; all later rows shift down by one.",
+   "c": [
+    "swmm_reaction_init_elem_count",
+    "swmm_reaction_init_elem_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.initial.set",
+   "target": "reactions.initial",
+   "name": "set",
+   "form": "method",
+   "python": "_InitialQualityRows.set",
+   "doc": "Upsert the initial concentration for one element and species.",
+   "c": [
+    "swmm_reaction_init_elem_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "is_link",
+     "type": "bool",
+     "required": true
+    },
+    {
+     "name": "elem_index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "species",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.save",
+   "target": "reactions",
+   "name": "save",
+   "form": "method",
+   "python": "Reactions.save",
+   "doc": "Serialize the reaction system to a .rxn file on disk.",
+   "c": [
+    "swmm_reactions_save"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Optional[str]",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "reactions.serialize",
+   "target": "reactions",
+   "name": "serialize",
+   "form": "method",
+   "python": "Reactions.serialize",
+   "doc": "Return the canonical .rxn text for the current engine state.",
+   "c": [
+    "swmm_reactions_serialize"
+   ],
+   "returns": "str",
+   "params": []
+  },
+  {
+   "path": "reactions.set_option",
+   "target": "reactions",
+   "name": "set_option",
+   "form": "method",
+   "python": "Reactions.set_option",
+   "doc": "Set one [REACTION_OPTIONS] value from its canonical token.",
+   "c": [
+    "swmm_reaction_option_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.species.add",
+   "target": "reactions.species",
+   "name": "add",
+   "form": "method",
+   "python": "_SpeciesCollection.add",
+   "doc": "Declare a new species and return a live view of it.",
+   "c": [
+    "swmm_reaction_species_add",
+    "swmm_reaction_species_count"
+   ],
+   "returns": "ReactionSpecies",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "wall",
+     "type": "bool",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "units",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "atol",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "rtol",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.species.get_index",
+   "target": "reactions.species",
+   "name": "get_index",
+   "form": "method",
+   "python": "_SpeciesCollection.get_index",
+   "doc": "Resolve int | str *key* to a zero-based species index.",
+   "c": [],
+   "returns": "int",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.species.remove",
+   "target": "reactions.species",
+   "name": "remove",
+   "form": "method",
+   "python": "_SpeciesCollection.remove",
+   "doc": "Remove the species named or indexed by *key*.",
+   "c": [
+    "swmm_reaction_species_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.terms.add",
+   "target": "reactions.terms",
+   "name": "add",
+   "form": "method",
+   "python": "_TermCollection.add",
+   "doc": "Append an intermediate term and return a live view of it.",
+   "c": [
+    "swmm_reaction_term_add",
+    "swmm_reaction_term_count"
+   ],
+   "returns": "ReactionTerm",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "expr",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.terms.get_index",
+   "target": "reactions.terms",
+   "name": "get_index",
+   "form": "method",
+   "python": "_TermCollection.get_index",
+   "doc": "Resolve int | str *key* to a zero-based term index (string lookup is an O(n) exact-name scan).",
+   "c": [],
+   "returns": "int",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.terms.remove",
+   "target": "reactions.terms",
+   "name": "remove",
+   "form": "method",
+   "python": "_TermCollection.remove",
+   "doc": "Remove the term named or indexed by *key*.",
+   "c": [
+    "swmm_reaction_term_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "reactions.validate",
+   "target": "reactions",
+   "name": "validate",
+   "form": "method",
+   "python": "Reactions.validate",
+   "doc": "Compile-only check of one expression. **Never changes state.**",
+   "c": [
+    "swmm_reaction_validate_expression"
+   ],
+   "returns": "ExpressionDiagnostic",
+   "params": [
+    {
+     "name": "expr",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "scope",
+     "type": "ReactionScope",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "read_runoff_step",
+   "target": "solver",
+   "name": "read_runoff_step",
+   "form": "method",
+   "python": "Solver.read_runoff_step",
+   "doc": "Read one substep from the USE-mode runoff interface file.",
+   "c": [
+    "swmm_runoff_iface_read_step"
+   ],
+   "returns": "bool",
+   "params": []
+  },
+  {
+   "path": "report",
+   "target": "solver",
+   "name": "report",
+   "form": "method",
+   "python": "Solver.report",
+   "doc": "Write the summary report to the .rpt file.",
+   "c": [
+    "swmm_engine_report"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "report_start_datetime",
+   "target": "solver",
+   "name": "report_start_datetime",
+   "form": "property",
+   "python": "Solver.report_start_datetime",
+   "doc": "Report start datetime.datetime.",
+   "c": [
+    "swmm_options_get_report_start",
+    "swmm_options_set_report_start"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "routing_step",
+   "target": "solver",
+   "name": "routing_step",
+   "form": "property",
+   "python": "Solver.routing_step",
+   "doc": "Routing timestep as a timedelta.",
+   "c": [
+    "swmm_get_routing_step"
+   ],
+   "type": "timedelta",
+   "access": "r"
+  },
+  {
+   "path": "run",
+   "target": "solver",
+   "name": "run",
+   "form": "method",
+   "python": "Solver.run",
+   "doc": "Run the full simulation lifecycle in one call.",
+   "c": [],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "save_runoff_step",
+   "target": "solver",
+   "name": "save_runoff_step",
+   "form": "method",
+   "python": "Solver.save_runoff_step",
+   "doc": "Force one runoff substep snapshot to the open SAVE file.",
+   "c": [
+    "swmm_runoff_iface_save_step"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "dt",
+     "type": "Union[timedelta, float]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "save_schedule.append",
+   "target": "save_schedule",
+   "name": "append",
+   "form": "method",
+   "python": "SaveSchedule.append",
+   "doc": "Append a hot-start save-schedule entry *value*.",
+   "c": [
+    "swmm_hotstart_saves_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "save_schedule.clear",
+   "target": "save_schedule",
+   "name": "clear",
+   "form": "method",
+   "python": "SaveSchedule.clear",
+   "doc": "Remove all entries from the hot-start save schedule.",
+   "c": [
+    "swmm_hotstart_saves_clear"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "target": "save_schedule",
+   "form": "item",
+   "python": "SaveSchedule[]",
+   "doc": "",
+   "path": "save_schedule.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_hotstart_saves_remove"
+   ]
+  },
+  {
+   "target": "save_schedule",
+   "form": "item",
+   "python": "SaveSchedule[]",
+   "doc": "",
+   "path": "save_schedule.get_item",
+   "name": "get_item",
+   "returns": "SaveScheduleEntry",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_hotstart_saves_get_datetime",
+    "swmm_hotstart_saves_get_path"
+   ]
+  },
+  {
+   "path": "save_schedule.insert",
+   "target": "save_schedule",
+   "name": "insert",
+   "form": "method",
+   "python": "SaveSchedule.insert",
+   "doc": "Insert *value* at *idx* (emulated via clear + re-add; the C save API is append-only).",
+   "c": [],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Any",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "save_schedule",
+   "form": "item",
+   "python": "SaveSchedule[]",
+   "doc": "",
+   "path": "save_schedule.items",
+   "name": "items",
+   "returns": "list[tuple[int, SaveScheduleEntry]]",
+   "params": [],
+   "c": [
+    "swmm_hotstart_saves_count",
+    "swmm_hotstart_saves_get_datetime",
+    "swmm_hotstart_saves_get_path"
+   ]
+  },
+  {
+   "target": "save_schedule",
+   "form": "item",
+   "python": "SaveSchedule[]",
+   "doc": "",
+   "path": "save_schedule.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "SaveScheduleEntry",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_hotstart_saves_set_datetime",
+    "swmm_hotstart_saves_set_path"
+   ]
+  },
+  {
+   "path": "set_lenient_open",
+   "target": "solver",
+   "name": "set_lenient_open",
+   "form": "method",
+   "python": "Solver.set_lenient_open",
+   "doc": "Enable or disable permissive (\"lenient\") open on this engine.",
+   "c": [
+    "swmm_engine_set_lenient_open"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "on",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "set_progress_callback",
+   "target": "solver",
+   "name": "set_progress_callback",
+   "form": "method",
+   "python": "Solver.set_progress_callback",
+   "doc": "Register a callback invoked as the simulation advances.",
+   "c": [
+    "swmm_set_progress_callback"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "callback",
+     "type": "Optional[Callable[[float], None]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "set_step_begin_callback",
+   "target": "solver",
+   "name": "set_step_begin_callback",
+   "form": "method",
+   "python": "Solver.set_step_begin_callback",
+   "doc": "Register a callback invoked at the start of each timestep.",
+   "c": [
+    "swmm_set_step_begin_callback"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "callback",
+     "type": "Optional[Callable[[float, float], None]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "set_step_end_callback",
+   "target": "solver",
+   "name": "set_step_end_callback",
+   "form": "method",
+   "python": "Solver.set_step_end_callback",
+   "doc": "Register a callback invoked at the end of each timestep.",
+   "c": [
+    "swmm_set_step_end_callback"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "callback",
+     "type": "Optional[Callable[[float, float], None]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "set_warning_callback",
+   "target": "solver",
+   "name": "set_warning_callback",
+   "form": "method",
+   "python": "Solver.set_warning_callback",
+   "doc": "Register a callback invoked on each non-fatal engine warning.",
+   "c": [
+    "swmm_set_warning_callback"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "callback",
+     "type": "Optional[Callable[[int, str], None]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "sim_end_time",
+   "target": "solver",
+   "name": "sim_end_time",
+   "form": "property",
+   "python": "Solver.sim_end_time",
+   "doc": "Resolved simulation end as a datetime.datetime.",
+   "c": [
+    "swmm_get_end_time"
+   ],
+   "type": "datetime",
+   "access": "r"
+  },
+  {
+   "path": "sim_start_time",
+   "target": "solver",
+   "name": "sim_start_time",
+   "form": "property",
+   "python": "Solver.sim_start_time",
+   "doc": "Resolved simulation start as a datetime.datetime.",
+   "c": [
+    "swmm_get_start_time"
+   ],
+   "type": "datetime",
+   "access": "r"
+  },
+  {
+   "path": "snowpacks.add",
+   "target": "snowpacks",
+   "name": "add",
+   "form": "method",
+   "python": "Snowpacks.add",
+   "doc": "Add a new snowpack definition with default (zero) parameters.",
+   "c": [
+    "swmm_snowpack_add",
+    "swmm_snowpack_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_id",
+   "target": "snowpacks",
+   "name": "get_id",
+   "form": "method",
+   "python": "Snowpacks.get_id",
+   "doc": "Get the string identifier of a snowpack definition by index.",
+   "c": [
+    "swmm_snowpack_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_impervious",
+   "target": "snowpacks",
+   "name": "get_impervious",
+   "form": "method",
+   "python": "Snowpacks.get_impervious",
+   "doc": "Read the IMPERVIOUS surface. Inverse of set_impervious.",
+   "c": [
+    "swmm_snowpack_get_impervious"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_index",
+   "target": "snowpacks",
+   "name": "get_index",
+   "form": "method",
+   "python": "Snowpacks.get_index",
+   "doc": "Look up a snowpack's zero-based index by its string identifier.",
+   "c": [
+    "swmm_snowpack_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "obj_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_pervious",
+   "target": "snowpacks",
+   "name": "get_pervious",
+   "form": "method",
+   "python": "Snowpacks.get_pervious",
+   "doc": "Read the PERVIOUS surface. Inverse of set_pervious.",
+   "c": [
+    "swmm_snowpack_get_pervious"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_plowable",
+   "target": "snowpacks",
+   "name": "get_plowable",
+   "form": "method",
+   "python": "Snowpacks.get_plowable",
+   "doc": "Read the PLOWABLE surface. Inverse of set_plowable.",
+   "c": [
+    "swmm_snowpack_get_plowable"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_removal",
+   "target": "snowpacks",
+   "name": "get_removal",
+   "form": "method",
+   "python": "Snowpacks.get_removal",
+   "doc": "Read the REMOVAL fractions. Inverse of set_removal.",
+   "c": [
+    "swmm_snowpack_get_removal"
+   ],
+   "returns": "dict[str, float]",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.get_removal_subcatch",
+   "target": "snowpacks",
+   "name": "get_removal_subcatch",
+   "form": "method",
+   "python": "Snowpacks.get_removal_subcatch",
+   "doc": "Read the REMOVAL destination subcatchment name (empty if none).",
+   "c": [
+    "swmm_snowpack_get_removal_subcatch"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.items",
+   "target": "snowpacks",
+   "name": "items",
+   "form": "item",
+   "python": "list(Snowpacks)",
+   "doc": "Name-keyed collection of [SNOWPACKS] entries (solver.snowpacks).",
+   "returns": "list[tuple[int, Iterator[str]]]",
+   "params": [],
+   "c": [
+    "swmm_snowpack_count"
+   ]
+  },
+  {
+   "path": "snowpacks.rename",
+   "target": "snowpacks",
+   "name": "rename",
+   "form": "method",
+   "python": "Snowpacks.rename",
+   "doc": "Rename a snow pack in place.",
+   "c": [
+    "swmm_snowpack_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.set_impervious",
+   "target": "snowpacks",
+   "name": "set_impervious",
+   "form": "method",
+   "python": "Snowpacks.set_impervious",
+   "doc": "Set the IMPERVIOUS surface (last = 100%-cover depth).",
+   "c": [
+    "swmm_snowpack_set_impervious"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "cmin",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "cmax",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "tbase",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fwfrac",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "sd0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fw0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "last",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.set_pervious",
+   "target": "snowpacks",
+   "name": "set_pervious",
+   "form": "method",
+   "python": "Snowpacks.set_pervious",
+   "doc": "Set the PERVIOUS surface (last = 100%-cover depth).",
+   "c": [
+    "swmm_snowpack_set_pervious"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "cmin",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "cmax",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "tbase",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fwfrac",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "sd0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fw0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "last",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.set_plowable",
+   "target": "snowpacks",
+   "name": "set_plowable",
+   "form": "method",
+   "python": "Snowpacks.set_plowable",
+   "doc": "Set the PLOWABLE surface (last = plowable-area fraction).",
+   "c": [
+    "swmm_snowpack_set_plowable"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "cmin",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "cmax",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "tbase",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fwfrac",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "sd0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fw0",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "last",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.set_removal",
+   "target": "snowpacks",
+   "name": "set_removal",
+   "form": "method",
+   "python": "Snowpacks.set_removal",
+   "doc": "Set the REMOVAL fractions (snow redistribution at depth dsnow).",
+   "c": [
+    "swmm_snowpack_set_removal"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "dsnow",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fout",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fimp",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fperv",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fimelt",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "fsubcatch",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "snowpacks.set_removal_subcatch",
+   "target": "snowpacks",
+   "name": "set_removal_subcatch",
+   "form": "method",
+   "python": "Snowpacks.set_removal_subcatch",
+   "doc": "Set/clear the destination subcatchment for the REMOVAL fsubcatch fraction (None/\"\" clears).",
+   "c": [
+    "swmm_snowpack_set_removal_subcatch"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "snowpack",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "name",
+     "type": "Optional[str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.crs",
+   "target": "spatial",
+   "name": "crs",
+   "form": "property",
+   "python": "Spatial.crs",
+   "doc": "Coordinate reference system (EPSG token, WKT, or proj string). Reading a model with no CRS raises CRSError; assigning sets it.",
+   "c": [
+    "swmm_spatial_get_crs",
+    "swmm_spatial_set_crs"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "spatial.gage_coord",
+   "target": "spatial",
+   "name": "gage_coord",
+   "form": "method",
+   "python": "Spatial.gage_coord",
+   "doc": "Return the (x, y) coordinate of rain *gage*.",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_index",
+    "swmm_spatial_get_gage_coord"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "gage",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.link_coord",
+   "target": "spatial",
+   "name": "link_coord",
+   "form": "method",
+   "python": "Spatial.link_coord",
+   "doc": "Return the (x, y) mid-point coordinate of *link*.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_spatial_get_link_coord"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.link_vertices",
+   "target": "spatial",
+   "name": "link_vertices",
+   "form": "method",
+   "python": "Spatial.link_vertices",
+   "doc": "(n, 2) float64 numpy array of polyline vertices.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_spatial_get_link_vertex_count",
+    "swmm_spatial_get_link_vertices"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.node_coord",
+   "target": "spatial",
+   "name": "node_coord",
+   "form": "method",
+   "python": "Spatial.node_coord",
+   "doc": "Return the (x, y) coordinate of *node*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_spatial_get_node_coord"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.node_coords",
+   "target": "spatial",
+   "name": "node_coords",
+   "form": "method",
+   "python": "Spatial.node_coords",
+   "doc": "All node coordinates as a (n_nodes, 2) float64 array.",
+   "c": [
+    "swmm_node_count",
+    "swmm_spatial_get_node_coords_bulk"
+   ],
+   "returns": "NDArray[Any]",
+   "params": []
+  },
+  {
+   "path": "spatial.set_gage_coord",
+   "target": "spatial",
+   "name": "set_gage_coord",
+   "form": "method",
+   "python": "Spatial.set_gage_coord",
+   "doc": "Set the (x, y) coordinate of rain *gage*.",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_index",
+    "swmm_spatial_set_gage_coord"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "gage",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_link_coord",
+   "target": "spatial",
+   "name": "set_link_coord",
+   "form": "method",
+   "python": "Spatial.set_link_coord",
+   "doc": "Set the (x, y) mid-point coordinate of *link*.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_spatial_set_link_coord"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_link_vertices",
+   "target": "spatial",
+   "name": "set_link_vertices",
+   "form": "method",
+   "python": "Spatial.set_link_vertices",
+   "doc": "Set the polyline vertices of *link* from an (N, 2) array.",
+   "c": [
+    "swmm_link_count",
+    "swmm_link_index",
+    "swmm_spatial_set_link_vertices"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "link",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "vertices",
+     "type": "NDArray[Any]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_node_coord",
+   "target": "spatial",
+   "name": "set_node_coord",
+   "form": "method",
+   "python": "Spatial.set_node_coord",
+   "doc": "Set the (x, y) coordinate of *node*.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_spatial_set_node_coord"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_node_coords",
+   "target": "spatial",
+   "name": "set_node_coords",
+   "form": "method",
+   "python": "Spatial.set_node_coords",
+   "doc": "coords is shape (n_nodes, 2) float64.",
+   "c": [
+    "swmm_node_count",
+    "swmm_spatial_set_node_coords_bulk"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "coords",
+     "type": "NDArray[Any]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_subcatchment_coord",
+   "target": "spatial",
+   "name": "set_subcatchment_coord",
+   "form": "method",
+   "python": "Spatial.set_subcatchment_coord",
+   "doc": "Set the (x, y) centroid coordinate of *sub*.",
+   "c": [
+    "swmm_spatial_set_subcatch_coord",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.set_subcatchment_polygon",
+   "target": "spatial",
+   "name": "set_subcatchment_polygon",
+   "form": "method",
+   "python": "Spatial.set_subcatchment_polygon",
+   "doc": "Set the boundary polygon of *sub* from an (N, 2) array.",
+   "c": [
+    "swmm_spatial_set_subcatch_polygon",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "polygon",
+     "type": "NDArray[Any]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.subcatchment_coord",
+   "target": "spatial",
+   "name": "subcatchment_coord",
+   "form": "method",
+   "python": "Spatial.subcatchment_coord",
+   "doc": "Return the (x, y) centroid coordinate of *sub*.",
+   "c": [
+    "swmm_spatial_get_subcatch_coord",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "Tuple[float, float]",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "spatial.subcatchment_polygon",
+   "target": "spatial",
+   "name": "subcatchment_polygon",
+   "form": "method",
+   "python": "Spatial.subcatchment_polygon",
+   "doc": "Return the boundary polygon of *sub* as an (N, 2) array.",
+   "c": [
+    "swmm_spatial_get_subcatch_polygon",
+    "swmm_spatial_get_subcatch_polygon_count",
+    "swmm_subcatch_count",
+    "swmm_subcatch_index"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "species.atol",
+   "target": "species",
+   "name": "atol",
+   "form": "property",
+   "python": "ReactionSpecies.atol",
+   "doc": "Absolute solver tolerance; 0.0 means \"use the global ATOL\".",
+   "c": [
+    "swmm_reaction_species_get"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "concentration"
+  },
+  {
+   "path": "species.get_expression",
+   "target": "species",
+   "name": "get_expression",
+   "form": "method",
+   "python": "ReactionSpecies.get_expression",
+   "doc": "Return this species' expression in one scope.",
+   "c": [
+    "swmm_reaction_expr_get"
+   ],
+   "returns": "Tuple[ReactionExprForm, str]",
+   "params": [
+    {
+     "name": "scope",
+     "type": "ReactionScope",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "species.index",
+   "target": "species",
+   "name": "index",
+   "form": "property",
+   "python": "ReactionSpecies.index",
+   "doc": "Zero-based position in [REACTION_SPECIES].",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "species.initial",
+   "target": "species",
+   "name": "initial",
+   "form": "property",
+   "python": "ReactionSpecies.initial",
+   "doc": "Model-wide initial concentration, in this species' own units.",
+   "c": [
+    "swmm_reaction_init_global_get",
+    "swmm_reaction_init_global_set"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "concentration"
+  },
+  {
+   "path": "species.is_wall",
+   "target": "species",
+   "name": "is_wall",
+   "form": "property",
+   "python": "ReactionSpecies.is_wall",
+   "doc": "True for a WALL species, False for a BULK species.",
+   "c": [
+    "swmm_reaction_species_get"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "species.name",
+   "target": "species",
+   "name": "name",
+   "form": "property",
+   "python": "ReactionSpecies.name",
+   "doc": "Species name as referenced from expressions.",
+   "c": [
+    "swmm_reaction_species_get"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "species.pipe_expression",
+   "target": "species",
+   "name": "pipe_expression",
+   "form": "property",
+   "python": "ReactionSpecies.pipe_expression",
+   "doc": "(form, expression) for the conduit (flowing) scope.",
+   "c": [],
+   "type": "Tuple[ReactionExprForm, str]",
+   "access": "r"
+  },
+  {
+   "path": "species.rtol",
+   "target": "species",
+   "name": "rtol",
+   "form": "property",
+   "python": "ReactionSpecies.rtol",
+   "doc": "Relative solver tolerance; 0.0 means \"use the global RTOL\".",
+   "c": [
+    "swmm_reaction_species_get"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "dimensionless"
+  },
+  {
+   "path": "species.set_expression",
+   "target": "species",
+   "name": "set_expression",
+   "form": "method",
+   "python": "ReactionSpecies.set_expression",
+   "doc": "Set — or with ReactionExprForm.NONE clear — one scope's expression.",
+   "c": [
+    "swmm_reaction_expr_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "scope",
+     "type": "ReactionScope",
+     "required": true
+    },
+    {
+     "name": "form",
+     "type": "ReactionExprForm",
+     "required": true
+    },
+    {
+     "name": "expression",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "species.tank_expression",
+   "target": "species",
+   "name": "tank_expression",
+   "form": "property",
+   "python": "ReactionSpecies.tank_expression",
+   "doc": "(form, expression) for the storage-unit (mixed) scope.",
+   "c": [],
+   "type": "Tuple[ReactionExprForm, str]",
+   "access": "r"
+  },
+  {
+   "path": "species.units",
+   "target": "species",
+   "name": "units",
+   "form": "property",
+   "python": "ReactionSpecies.units",
+   "doc": "Concentration units token (e.g. \"MG\", \"UG\", \"#\").",
+   "c": [
+    "swmm_reaction_species_get"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "start",
+   "target": "solver",
+   "name": "start",
+   "form": "method",
+   "python": "Solver.start",
+   "doc": "Start the simulation; transition to STARTED.",
+   "c": [
+    "swmm_engine_start"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "save_results",
+     "type": "bool",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "start_datetime",
+   "target": "solver",
+   "name": "start_datetime",
+   "form": "property",
+   "python": "Solver.start_datetime",
+   "doc": "Simulation start datetime.datetime.",
+   "c": [
+    "swmm_options_get_start_date",
+    "swmm_options_set_start_date"
+   ],
+   "type": "datetime",
+   "access": "rw"
+  },
+  {
+   "path": "state",
+   "target": "solver",
+   "name": "state",
+   "form": "property",
+   "python": "Solver.state",
+   "doc": "Current lifecycle state as an EngineState enum.",
+   "c": [
+    "swmm_engine_get_state"
+   ],
+   "type": "EngineState",
+   "access": "r"
+  },
+  {
+   "path": "statistics.link_max_filling",
+   "target": "statistics",
+   "name": "link_max_filling",
+   "form": "property",
+   "python": "Statistics.link_max_filling",
+   "doc": "Maximum filling ratio (depth / full depth) in each link.",
+   "c": [
+    "swmm_link_count",
+    "swmm_stat_link_max_filling_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "statistics.link_max_filling_at",
+   "target": "statistics",
+   "name": "link_max_filling_at",
+   "form": "method",
+   "python": "Statistics.link_max_filling_at",
+   "doc": "Peak fractional filling [0, 1] of one link.",
+   "c": [
+    "swmm_stat_link_max_filling"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.link_max_flow",
+   "target": "statistics",
+   "name": "link_max_flow",
+   "form": "property",
+   "python": "Statistics.link_max_flow",
+   "doc": "Maximum flow rate in each link, in project units.",
+   "c": [
+    "swmm_link_count",
+    "swmm_stat_link_max_flow_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.link_max_flow_at",
+   "target": "statistics",
+   "name": "link_max_flow_at",
+   "form": "method",
+   "python": "Statistics.link_max_flow_at",
+   "doc": "Peak flow in one link (project flow units).",
+   "c": [
+    "swmm_stat_link_max_flow"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.link_max_velocity",
+   "target": "statistics",
+   "name": "link_max_velocity",
+   "form": "property",
+   "python": "Statistics.link_max_velocity",
+   "doc": "Maximum flow velocity in each link, in project units.",
+   "c": [
+    "swmm_link_count",
+    "swmm_stat_link_max_velocity_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.link_max_velocity_at",
+   "target": "statistics",
+   "name": "link_max_velocity_at",
+   "form": "method",
+   "python": "Statistics.link_max_velocity_at",
+   "doc": "Peak velocity in one link (project length/time units).",
+   "c": [
+    "swmm_stat_link_max_velocity"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.link_surcharge_time",
+   "target": "statistics",
+   "name": "link_surcharge_time",
+   "form": "property",
+   "python": "Statistics.link_surcharge_time",
+   "doc": "Cumulative surcharge duration in each link, in seconds.",
+   "c": [
+    "swmm_link_count",
+    "swmm_stat_link_surcharge_time_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.link_surcharge_time_at",
+   "target": "statistics",
+   "name": "link_surcharge_time_at",
+   "form": "method",
+   "python": "Statistics.link_surcharge_time_at",
+   "doc": "Total surcharge time of one link (hours).",
+   "c": [
+    "swmm_stat_link_surcharge_time"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.link_vol_flow",
+   "target": "statistics",
+   "name": "link_vol_flow",
+   "form": "property",
+   "python": "Statistics.link_vol_flow",
+   "doc": "Cumulative flow volume through each link, in project units.",
+   "c": [
+    "swmm_link_count",
+    "swmm_stat_link_vol_flow_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.link_vol_flow_at",
+   "target": "statistics",
+   "name": "link_vol_flow_at",
+   "form": "method",
+   "python": "Statistics.link_vol_flow_at",
+   "doc": "Total flow volume through one link (project volume units).",
+   "c": [
+    "swmm_stat_link_vol_flow"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.node_max_depth",
+   "target": "statistics",
+   "name": "node_max_depth",
+   "form": "property",
+   "python": "Statistics.node_max_depth",
+   "doc": "Maximum depth reached at each node, in project units.",
+   "c": [
+    "swmm_node_count",
+    "swmm_stat_node_max_depth_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.node_max_depth_at",
+   "target": "statistics",
+   "name": "node_max_depth_at",
+   "form": "method",
+   "python": "Statistics.node_max_depth_at",
+   "doc": "Peak depth at one node (project length units).",
+   "c": [
+    "swmm_stat_node_max_depth"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.node_max_overflow",
+   "target": "statistics",
+   "name": "node_max_overflow",
+   "form": "property",
+   "python": "Statistics.node_max_overflow",
+   "doc": "Maximum overflow (flooding) rate at each node, in project units.",
+   "c": [
+    "swmm_node_count",
+    "swmm_stat_node_max_overflow_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.node_max_overflow_at",
+   "target": "statistics",
+   "name": "node_max_overflow_at",
+   "form": "method",
+   "python": "Statistics.node_max_overflow_at",
+   "doc": "Peak overflow (flooding) rate at one node (project flow units).",
+   "c": [
+    "swmm_stat_node_max_overflow"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.node_time_flooded",
+   "target": "statistics",
+   "name": "node_time_flooded",
+   "form": "property",
+   "python": "Statistics.node_time_flooded",
+   "doc": "Cumulative flooded duration per node (seconds).",
+   "c": [
+    "swmm_node_count",
+    "swmm_stat_node_time_flooded_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "s"
+  },
+  {
+   "path": "statistics.node_time_flooded_at",
+   "target": "statistics",
+   "name": "node_time_flooded_at",
+   "form": "method",
+   "python": "Statistics.node_time_flooded_at",
+   "doc": "Total time flooded at one node (hours).",
+   "c": [
+    "swmm_stat_node_time_flooded"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.node_vol_flooded",
+   "target": "statistics",
+   "name": "node_vol_flooded",
+   "form": "property",
+   "python": "Statistics.node_vol_flooded",
+   "doc": "Cumulative flooded volume at each node, in project units.",
+   "c": [
+    "swmm_node_count",
+    "swmm_stat_node_vol_flooded_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.node_vol_flooded_at",
+   "target": "statistics",
+   "name": "node_vol_flooded_at",
+   "form": "method",
+   "python": "Statistics.node_vol_flooded_at",
+   "doc": "Total flooded volume at one node (project volume units).",
+   "c": [
+    "swmm_stat_node_vol_flooded"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.subcatchment_max_runoff",
+   "target": "statistics",
+   "name": "subcatchment_max_runoff",
+   "form": "property",
+   "python": "Statistics.subcatchment_max_runoff",
+   "doc": "Peak runoff rate from each subcatchment, in project units.",
+   "c": [
+    "swmm_stat_subcatch_max_runoff_bulk",
+    "swmm_subcatch_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.subcatchment_max_runoff_at",
+   "target": "statistics",
+   "name": "subcatchment_max_runoff_at",
+   "form": "method",
+   "python": "Statistics.subcatchment_max_runoff_at",
+   "doc": "Peak runoff rate from one subcatchment (project flow units).",
+   "c": [
+    "swmm_stat_subcatch_max_runoff"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "statistics.subcatchment_precip",
+   "target": "statistics",
+   "name": "subcatchment_precip",
+   "form": "property",
+   "python": "Statistics.subcatchment_precip",
+   "doc": "Cumulative precipitation depth at each subcatchment.",
+   "c": [
+    "swmm_stat_subcatch_precip",
+    "swmm_subcatch_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "statistics.subcatchment_runoff_vol",
+   "target": "statistics",
+   "name": "subcatchment_runoff_vol",
+   "form": "property",
+   "python": "Statistics.subcatchment_runoff_vol",
+   "doc": "Cumulative runoff volume from each subcatchment, in project units.",
+   "c": [
+    "swmm_stat_subcatch_runoff_vol_bulk",
+    "swmm_subcatch_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "statistics.subcatchment_runoff_vol_at",
+   "target": "statistics",
+   "name": "subcatchment_runoff_vol_at",
+   "form": "method",
+   "python": "Statistics.subcatchment_runoff_vol_at",
+   "doc": "Total runoff volume from one subcatchment (project volume units).",
+   "c": [
+    "swmm_stat_subcatch_runoff_vol"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "steady_state_skip",
+   "target": "solver",
+   "name": "steady_state_skip",
+   "form": "property",
+   "python": "Solver.steady_state_skip",
+   "doc": "Get/set steady-state skip flag.",
+   "c": [
+    "swmm_get_steady_state_skip",
+    "swmm_set_steady_state_skip"
+   ],
+   "type": "bool",
+   "access": "rw"
+  },
+  {
+   "path": "step",
+   "target": "solver",
+   "name": "step",
+   "form": "method",
+   "python": "Solver.step",
+   "doc": "Advance one routing step.",
+   "c": [
+    "swmm_engine_step"
+   ],
+   "returns": "timedelta",
+   "params": []
+  },
+  {
+   "path": "steps",
+   "target": "solver",
+   "name": "steps",
+   "form": "method",
+   "python": "Solver.steps",
+   "doc": "Iterate routing steps until the simulation ends.",
+   "c": [],
+   "returns": "Iterator[timedelta]",
+   "params": []
+  },
+  {
+   "path": "stride",
+   "target": "solver",
+   "name": "stride",
+   "form": "method",
+   "python": "Solver.stride",
+   "doc": "Advance n_steps routing steps in one call.",
+   "c": [
+    "swmm_engine_stride"
+   ],
+   "returns": "timedelta",
+   "params": [
+    {
+     "name": "n_steps",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.aquifer",
+   "target": "subcatchment",
+   "name": "aquifer",
+   "form": "property",
+   "python": "Subcatchment.aquifer",
+   "doc": "The aquifer index assigned to this subcatchment, or None when it has no groundwater.",
+   "c": [
+    "swmm_aquifer_count",
+    "swmm_aquifer_index",
+    "swmm_subcatch_get_aquifer",
+    "swmm_subcatch_set_aquifer"
+   ],
+   "type": "Optional[int]",
+   "access": "rw"
+  },
+  {
+   "path": "subcatchment.area",
+   "target": "subcatchment",
+   "name": "area",
+   "form": "property",
+   "python": "Subcatchment.area",
+   "doc": "Get the subcatchment area.",
+   "c": [
+    "swmm_subcatch_get_area",
+    "swmm_subcatch_set_area"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "land_area"
+  },
+  {
+   "target": "subcatchment.coverage",
+   "form": "item",
+   "python": "CoverageView[]",
+   "doc": "",
+   "path": "subcatchment.coverage.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "target": "subcatchment.coverage",
+   "form": "item",
+   "python": "CoverageView[]",
+   "doc": "",
+   "path": "subcatchment.coverage.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_subcatch_get_coverage"
+   ]
+  },
+  {
+   "target": "subcatchment.coverage",
+   "form": "item",
+   "python": "CoverageView[]",
+   "doc": "",
+   "path": "subcatchment.coverage.items",
+   "name": "items",
+   "returns": "list[tuple[str, float]]",
+   "params": [],
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_id",
+    "swmm_landuse_index",
+    "swmm_subcatch_get_coverage"
+   ]
+  },
+  {
+   "target": "subcatchment.coverage",
+   "form": "item",
+   "python": "CoverageView[]",
+   "doc": "",
+   "path": "subcatchment.coverage.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_landuse_count",
+    "swmm_landuse_index",
+    "swmm_subcatch_set_coverage"
+   ]
+  },
+  {
+   "path": "subcatchment.coverages",
+   "target": "subcatchment",
+   "name": "coverages",
+   "form": "method",
+   "python": "Subcatchment.coverages",
+   "doc": "All land-use coverage percents in land-use index order (bulk peer of coverage[...] — one C call instead of one per pair).",
+   "c": [
+    "swmm_landuse_count",
+    "swmm_subcatch_get_coverages"
+   ],
+   "returns": "list[float]",
+   "params": []
+  },
+  {
+   "path": "subcatchment.ds_imperv",
+   "target": "subcatchment",
+   "name": "ds_imperv",
+   "form": "property",
+   "python": "Subcatchment.ds_imperv",
+   "doc": "Get the depression storage depth for the impervious area.",
+   "c": [
+    "swmm_subcatch_get_ds_imperv",
+    "swmm_subcatch_set_ds_imperv"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "rain_depth"
+  },
+  {
+   "path": "subcatchment.ds_perv",
+   "target": "subcatchment",
+   "name": "ds_perv",
+   "form": "property",
+   "python": "Subcatchment.ds_perv",
+   "doc": "Get the depression storage depth for the pervious area.",
+   "c": [
+    "swmm_subcatch_get_ds_perv",
+    "swmm_subcatch_set_ds_perv"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "rain_depth"
+  },
+  {
+   "path": "subcatchment.evap",
+   "target": "subcatchment",
+   "name": "evap",
+   "form": "property",
+   "python": "Subcatchment.evap",
+   "doc": "Get the current evaporation rate at a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_evap"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "evap_rate",
+   "bulk": "subcatchments.evaps"
+  },
+  {
+   "path": "subcatchment.gage",
+   "target": "subcatchment",
+   "name": "gage",
+   "form": "property",
+   "python": "Subcatchment.gage",
+   "doc": "The Gage wrapper assigned to this subcatchment.",
+   "c": [
+    "swmm_gage_count",
+    "swmm_gage_index",
+    "swmm_subcatch_get_gage",
+    "swmm_subcatch_set_gage"
+   ],
+   "type": "ref:gage",
+   "access": "rw"
+  },
+  {
+   "path": "subcatchment.get_gw_state",
+   "target": "subcatchment",
+   "name": "get_gw_state",
+   "form": "method",
+   "python": "Subcatchment.get_gw_state",
+   "doc": "Read the groundwater state on this subcatchment.",
+   "c": [
+    "swmm_subcatch_get_gw_state"
+   ],
+   "returns": "tuple[float, float]",
+   "params": []
+  },
+  {
+   "path": "subcatchment.get_snow_state",
+   "target": "subcatchment",
+   "name": "get_snow_state",
+   "form": "method",
+   "python": "Subcatchment.get_snow_state",
+   "doc": "Read the snow-pack state on one snow surface.",
+   "c": [
+    "swmm_subcatch_get_snow_state"
+   ],
+   "returns": "tuple[float, float, float, float]",
+   "params": [
+    {
+     "name": "surface",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.groundwater",
+   "target": "subcatchment",
+   "name": "groundwater",
+   "form": "property",
+   "python": "Subcatchment.groundwater",
+   "doc": "Get the current groundwater flow from a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_groundwater"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "subcatchment.gw_node",
+   "target": "subcatchment",
+   "name": "gw_node",
+   "form": "property",
+   "python": "Subcatchment.gw_node",
+   "doc": "The node index receiving this subcatchment's groundwater flow, or None when none is assigned.",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_subcatch_get_gw_node",
+    "swmm_subcatch_set_gw_node"
+   ],
+   "type": "Optional[int]",
+   "access": "rw"
+  },
+  {
+   "path": "subcatchment.gw_params",
+   "target": "subcatchment",
+   "name": "gw_params",
+   "form": "property",
+   "python": "Subcatchment.gw_params",
+   "doc": "Groundwater flow parameters as a GroundwaterParams named tuple (surf_elev, a1, b1, a2, b2, a3, tw, hstar) — the [GROUNDWATER] token order.",
+   "c": [
+    "swmm_subcatch_get_gw_params"
+   ],
+   "type": "GroundwaterParams",
+   "access": "r"
+  },
+  {
+   "path": "subcatchment.id",
+   "target": "subcatchment",
+   "name": "id",
+   "form": "property",
+   "python": "Subcatchment.id",
+   "doc": "Get the string identifier of a subcatchment by index.",
+   "c": [
+    "swmm_subcatch_id"
+   ],
+   "type": "str",
+   "access": "r",
+   "bulk": "subcatchments.ids"
+  },
+  {
+   "path": "subcatchment.imperv_pct",
+   "target": "subcatchment",
+   "name": "imperv_pct",
+   "form": "property",
+   "python": "Subcatchment.imperv_pct",
+   "doc": "Get the percentage of impervious area.",
+   "c": [
+    "swmm_subcatch_get_imperv_pct",
+    "swmm_subcatch_set_imperv_pct"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "percent"
+  },
+  {
+   "path": "subcatchment.index",
+   "target": "subcatchment",
+   "name": "index",
+   "form": "property",
+   "python": "Subcatchment.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "subcatchment.infil",
+   "target": "subcatchment",
+   "name": "infil",
+   "form": "property",
+   "python": "Subcatchment.infil",
+   "doc": "Get the current infiltration rate at a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_infil"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "rain_rate",
+   "bulk": "subcatchments.infils"
+  },
+  {
+   "path": "subcatchment.infiltration.curve_number",
+   "target": "subcatchment.infiltration",
+   "name": "curve_number",
+   "form": "property",
+   "python": "InfiltrationView.curve_number",
+   "doc": "Get the Curve Number infiltration parameters for a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_infil_curve_number"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "dimensionless"
+  },
+  {
+   "path": "subcatchment.infiltration.curve_number_drying_time",
+   "target": "subcatchment.infiltration",
+   "name": "curve_number_drying_time",
+   "form": "property",
+   "python": "InfiltrationView.curve_number_drying_time",
+   "doc": "Days for a fully saturated soil to dry (third [INFILTRATION] column).",
+   "c": [
+    "swmm_subcatch_get_infil_curve_number"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "d"
+  },
+  {
+   "path": "subcatchment.infiltration.green_ampt",
+   "target": "subcatchment.infiltration",
+   "name": "green_ampt",
+   "form": "property",
+   "python": "InfiltrationView.green_ampt",
+   "doc": "(suction, conductivity, initial_deficit) Green-Ampt parameters.",
+   "c": [
+    "swmm_subcatch_get_infil_green_ampt"
+   ],
+   "type": "Tuple[float, float, float]",
+   "access": "r"
+  },
+  {
+   "path": "subcatchment.infiltration.horton",
+   "target": "subcatchment.infiltration",
+   "name": "horton",
+   "form": "property",
+   "python": "InfiltrationView.horton",
+   "doc": "(f0, fmin, decay, dry_time) — Horton parameters.",
+   "c": [
+    "swmm_subcatch_get_infil_horton"
+   ],
+   "type": "Tuple[float, float, float, float]",
+   "access": "r"
+  },
+  {
+   "path": "subcatchment.infiltration.model",
+   "target": "subcatchment.infiltration",
+   "name": "model",
+   "form": "property",
+   "python": "InfiltrationView.model",
+   "doc": "Switch the active infiltration model.",
+   "c": [
+    "swmm_subcatch_get_infil_model",
+    "swmm_subcatch_set_infil_model"
+   ],
+   "type": "InfilModel",
+   "access": "rw"
+  },
+  {
+   "path": "subcatchment.infiltration.set_curve_number",
+   "target": "subcatchment.infiltration",
+   "name": "set_curve_number",
+   "form": "method",
+   "python": "InfiltrationView.set_curve_number",
+   "doc": "Set the SCS curve-number infiltration parameters (CN, drying time in days).",
+   "c": [
+    "swmm_subcatch_set_infil_curve_number"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "cn",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "drying_time",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.infiltration.set_green_ampt",
+   "target": "subcatchment.infiltration",
+   "name": "set_green_ampt",
+   "form": "method",
+   "python": "InfiltrationView.set_green_ampt",
+   "doc": "Set Green-Ampt infiltration parameters (suction, conductivity, initial deficit).",
+   "c": [
+    "swmm_subcatch_set_infil_green_ampt"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "suction",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "conductivity",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "initial_deficit",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.infiltration.set_horton",
+   "target": "subcatchment.infiltration",
+   "name": "set_horton",
+   "form": "method",
+   "python": "InfiltrationView.set_horton",
+   "doc": "Set Horton infiltration parameters (f0, fmin, decay, dry-time) for this subcatchment.",
+   "c": [
+    "swmm_subcatch_set_infil_horton"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "f0",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "fmin",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "decay",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "dry_time",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "subcatchment.loadings",
+   "form": "item",
+   "python": "LoadingsView[]",
+   "doc": "Pollutant or species id -> initial buildup on a subcatchment.",
+   "path": "subcatchment.loadings.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "target": "subcatchment.loadings",
+   "form": "item",
+   "python": "LoadingsView[]",
+   "doc": "Pollutant or species id -> initial buildup on a subcatchment.",
+   "path": "subcatchment.loadings.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_get_initial_loading"
+   ]
+  },
+  {
+   "target": "subcatchment.loadings",
+   "form": "item",
+   "python": "LoadingsView[]",
+   "doc": "Pollutant or species id -> initial buildup on a subcatchment.",
+   "path": "subcatchment.loadings.items",
+   "name": "items",
+   "returns": "list[tuple[str, float]]",
+   "params": [],
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_id",
+    "swmm_pollutant_index",
+    "swmm_subcatch_get_initial_loading"
+   ]
+  },
+  {
+   "target": "subcatchment.loadings",
+   "form": "item",
+   "python": "LoadingsView[]",
+   "doc": "Pollutant or species id -> initial buildup on a subcatchment.",
+   "path": "subcatchment.loadings.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_set_initial_loading"
+   ]
+  },
+  {
+   "path": "subcatchment.n_imperv",
+   "target": "subcatchment",
+   "name": "n_imperv",
+   "form": "property",
+   "python": "Subcatchment.n_imperv",
+   "doc": "Get Manning's n for the impervious area.",
+   "c": [
+    "swmm_subcatch_get_n_imperv",
+    "swmm_subcatch_set_n_imperv"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "manning_n"
+  },
+  {
+   "path": "subcatchment.n_perv",
+   "target": "subcatchment",
+   "name": "n_perv",
+   "form": "property",
+   "python": "Subcatchment.n_perv",
+   "doc": "Get Manning's n for the pervious area.",
+   "c": [
+    "swmm_subcatch_get_n_perv",
+    "swmm_subcatch_set_n_perv"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "manning_n"
+  },
+  {
+   "path": "subcatchment.outlet",
+   "target": "subcatchment",
+   "name": "outlet",
+   "form": "property",
+   "python": "Subcatchment.outlet",
+   "doc": "The downstream Node (or Subcatchment if the outlet is another subcatchment).",
+   "c": [
+    "swmm_subcatch_get_outlet",
+    "swmm_subcatch_get_outlet_subcatch"
+   ],
+   "type": "Union[Node, 'Subcatchment', None]",
+   "access": "r"
+  },
+  {
+   "path": "subcatchment.ponded_quality",
+   "target": "subcatchment",
+   "name": "ponded_quality",
+   "form": "method",
+   "python": "Subcatchment.ponded_quality",
+   "doc": "Return the ponded-water concentration of *pollutant* for this subcatchment.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_get_ponded_quality"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.quality",
+   "target": "subcatchment",
+   "name": "quality",
+   "form": "method",
+   "python": "Subcatchment.quality",
+   "doc": "Return the current runoff concentration of *pollutant* for this subcatchment.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_get_quality"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.rain_scale_factor",
+   "target": "subcatchment",
+   "name": "rain_scale_factor",
+   "form": "property",
+   "python": "Subcatchment.rain_scale_factor",
+   "doc": "Per-subcatchment rainfall scale factor (dimensionless, > 0; 1.0 = no scaling).",
+   "c": [
+    "swmm_subcatch_get_rain_scale_factor",
+    "swmm_subcatch_set_rain_scale_factor"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless"
+  },
+  {
+   "path": "subcatchment.rainfall",
+   "target": "subcatchment",
+   "name": "rainfall",
+   "form": "property",
+   "python": "Subcatchment.rainfall",
+   "doc": "Get the current rainfall intensity at a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_rainfall",
+    "swmm_subcatch_set_rainfall"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "rain_rate",
+   "bulk": "subcatchments.rainfalls"
+  },
+  {
+   "path": "subcatchment.runoff",
+   "target": "subcatchment",
+   "name": "runoff",
+   "form": "property",
+   "python": "Subcatchment.runoff",
+   "doc": "Get the current runoff rate from a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_runoff"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow",
+   "bulk": "subcatchments.runoffs"
+  },
+  {
+   "path": "subcatchment.set_gw_params",
+   "target": "subcatchment",
+   "name": "set_gw_params",
+   "form": "method",
+   "python": "Subcatchment.set_gw_params",
+   "doc": "Set the groundwater flow parameters ([GROUNDWATER] token order).",
+   "c": [
+    "swmm_subcatch_set_gw_params"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "surf_elev",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "a1",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "b1",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "a2",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "b2",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "a3",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "tw",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "hstar",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.set_gw_state",
+   "target": "subcatchment",
+   "name": "set_gw_state",
+   "form": "method",
+   "python": "Subcatchment.set_gw_state",
+   "doc": "Inject the groundwater state on this subcatchment (RUNNING only).",
+   "c": [
+    "swmm_subcatch_set_gw_state"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "theta",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "lower_depth",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.set_outlet_node",
+   "target": "subcatchment",
+   "name": "set_outlet_node",
+   "form": "method",
+   "python": "Subcatchment.set_outlet_node",
+   "doc": "Route runoff to node (a Node wrapper, index, or id).",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_subcatch_set_outlet"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "Union[Node, Union[int, str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.set_outlet_subcatchment",
+   "target": "subcatchment",
+   "name": "set_outlet_subcatchment",
+   "form": "method",
+   "python": "Subcatchment.set_outlet_subcatchment",
+   "doc": "Route runoff to another Subcatchment.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_index",
+    "swmm_subcatch_set_outlet_subcatch"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "sub",
+     "type": "Union['Subcatchment', Union[int, str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.set_ponded_quality",
+   "target": "subcatchment",
+   "name": "set_ponded_quality",
+   "form": "method",
+   "python": "Subcatchment.set_ponded_quality",
+   "doc": "Set the ponded-water *mass* of *pollutant* for this subcatchment.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_set_ponded_quality"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "mass",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.set_snow_state",
+   "target": "subcatchment",
+   "name": "set_snow_state",
+   "form": "method",
+   "python": "Subcatchment.set_snow_state",
+   "doc": "Inject the snow-pack state on one snow surface (RUNNING only).",
+   "c": [
+    "swmm_subcatch_set_snow_state"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "surface",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "swe",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "fw",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "ati",
+     "type": "float",
+     "required": false
+    },
+    {
+     "name": "coldc",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "subcatchment.slope",
+   "target": "subcatchment",
+   "name": "slope",
+   "form": "property",
+   "python": "Subcatchment.slope",
+   "doc": "Get the average surface slope.",
+   "c": [
+    "swmm_subcatch_get_slope",
+    "swmm_subcatch_set_slope"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "percent"
+  },
+  {
+   "path": "subcatchment.snow_depth",
+   "target": "subcatchment",
+   "name": "snow_depth",
+   "form": "property",
+   "python": "Subcatchment.snow_depth",
+   "doc": "Get the current snow depth on a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_snow_depth"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length",
+   "bulk": "subcatchments.snow_depths"
+  },
+  {
+   "path": "subcatchment.snow_scale_factor",
+   "target": "subcatchment",
+   "name": "snow_scale_factor",
+   "form": "property",
+   "python": "Subcatchment.snow_scale_factor",
+   "doc": "Per-subcatchment snowfall scale factor (dimensionless, > 0; 1.0 = no scaling).",
+   "c": [
+    "swmm_subcatch_get_snow_scale_factor",
+    "swmm_subcatch_set_snow_scale_factor"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "dimensionless"
+  },
+  {
+   "path": "subcatchment.stats.max_runoff",
+   "target": "subcatchment.stats",
+   "name": "max_runoff",
+   "form": "property",
+   "python": "SubcatchmentStatsView.max_runoff",
+   "doc": "Get the maximum runoff rate from a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_stat_max_runoff"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "subcatchment.stats.precip",
+   "target": "subcatchment.stats",
+   "name": "precip",
+   "form": "property",
+   "python": "SubcatchmentStatsView.precip",
+   "doc": "Get the total precipitation volume at a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_stat_precip"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume",
+   "phases": [
+    "ENDED",
+    "RUNNING"
+   ]
+  },
+  {
+   "path": "subcatchment.stats.runoff_vol",
+   "target": "subcatchment.stats",
+   "name": "runoff_vol",
+   "form": "property",
+   "python": "SubcatchmentStatsView.runoff_vol",
+   "doc": "Get the total runoff volume from a subcatchment.",
+   "c": [
+    "swmm_subcatch_get_stat_runoff_vol"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "volume"
+  },
+  {
+   "path": "subcatchment.tag",
+   "target": "subcatchment",
+   "name": "tag",
+   "form": "property",
+   "python": "Subcatchment.tag",
+   "doc": "The subcatchment's free-form tag string (INP [TAGS] section).",
+   "c": [
+    "swmm_subcatch_get_tag",
+    "swmm_subcatch_set_tag"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "subcatchment.width",
+   "target": "subcatchment",
+   "name": "width",
+   "form": "property",
+   "python": "Subcatchment.width",
+   "doc": "Get the characteristic overland flow width.",
+   "c": [
+    "swmm_subcatch_get_width",
+    "swmm_subcatch_set_width"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "subcatchment.zero_imperv_pct",
+   "target": "subcatchment",
+   "name": "zero_imperv_pct",
+   "form": "property",
+   "python": "Subcatchment.zero_imperv_pct",
+   "doc": "Percent of the impervious area with no depression storage.",
+   "c": [
+    "swmm_subcatch_get_zero_imperv_pct",
+    "swmm_subcatch_set_zero_imperv_pct"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "percent"
+  },
+  {
+   "path": "subcatchments.add",
+   "target": "subcatchments",
+   "name": "add",
+   "form": "method",
+   "python": "Subcatchments.add",
+   "doc": "Add a new subcatchment *sub_id* and return its Subcatchment handle.",
+   "c": [
+    "swmm_subcatch_add",
+    "swmm_subcatch_index"
+   ],
+   "returns": "Subcatchment",
+   "params": [
+    {
+     "name": "sub_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.evaps",
+   "target": "subcatchments",
+   "name": "evaps",
+   "form": "property",
+   "python": "Subcatchments.evaps",
+   "doc": "Get evaporation losses for all subcatchments in a single call.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_evap_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "evap_rate"
+  },
+  {
+   "path": "subcatchments.get_gwf_expression",
+   "target": "subcatchments",
+   "name": "get_gwf_expression",
+   "form": "method",
+   "python": "Subcatchments.get_gwf_expression",
+   "doc": "Return a subcatchment's [GWF] expression (empty if none is set).",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_gwf_expression",
+    "swmm_subcatch_index"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "gwf_type",
+     "type": "Union[GwfType, int]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.get_id",
+   "target": "subcatchments",
+   "name": "get_id",
+   "form": "method",
+   "python": "Subcatchments.get_id",
+   "doc": "Return the ID string of the subcatchment at *idx*.",
+   "c": [
+    "swmm_subcatch_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.get_index",
+   "target": "subcatchments",
+   "name": "get_index",
+   "form": "method",
+   "python": "Subcatchments.get_index",
+   "doc": "Return the zero-based index of subcatchment *sub_id* (raises if unknown).",
+   "c": [
+    "swmm_subcatch_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "sub_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.gwf_functions",
+   "target": "subcatchments",
+   "name": "gwf_functions",
+   "form": "method",
+   "python": "Subcatchments.gwf_functions",
+   "doc": "Built-in functions a [GWF] expression may call, as a list of lower-case names (min/max take two arguments, the rest one).",
+   "c": [
+    "swmm_gwf_function_count",
+    "swmm_gwf_function_name"
+   ],
+   "returns": "List[str]",
+   "params": []
+  },
+  {
+   "path": "subcatchments.gwf_variables",
+   "target": "subcatchments",
+   "name": "gwf_variables",
+   "form": "method",
+   "python": "Subcatchments.gwf_variables",
+   "doc": "Variables a [GWF] expression may reference, as a list of (name, description) tuples (names upper-case, e.g. \"HGW\").",
+   "c": [
+    "swmm_gwf_variable_count",
+    "swmm_gwf_variable_description",
+    "swmm_gwf_variable_name"
+   ],
+   "returns": "List[Tuple[str, str]]",
+   "params": []
+  },
+  {
+   "path": "subcatchments.ids",
+   "target": "subcatchments",
+   "name": "ids",
+   "form": "property",
+   "python": "Subcatchments.ids",
+   "doc": "Get subcatchment IDs for all subcatchments in a single call (stride-packed UTF-8).",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_ids_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "subcatchments.infils",
+   "target": "subcatchments",
+   "name": "infils",
+   "form": "property",
+   "python": "Subcatchments.infils",
+   "doc": "Get infiltration losses for all subcatchments in a single call.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_infil_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "rain_rate"
+  },
+  {
+   "path": "subcatchments.qualities",
+   "target": "subcatchments",
+   "name": "qualities",
+   "form": "method",
+   "python": "Subcatchments.qualities",
+   "doc": "Return an array of *pollutant* runoff concentrations for every subcatchment.",
+   "c": [
+    "swmm_pollutant_count",
+    "swmm_pollutant_index",
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_quality_bulk"
+   ],
+   "returns": "NDArray[Any]",
+   "params": [
+    {
+     "name": "pollutant",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.rainfalls",
+   "target": "subcatchments",
+   "name": "rainfalls",
+   "form": "property",
+   "python": "Subcatchments.rainfalls",
+   "doc": "Get rainfall rates for all subcatchments in a single call.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_rainfall_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "rain_rate"
+  },
+  {
+   "path": "subcatchments.rename",
+   "target": "subcatchments",
+   "name": "rename",
+   "form": "method",
+   "python": "Subcatchments.rename",
+   "doc": "Rename the subcatchment identified by *key* to *new_id*.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_index",
+    "swmm_subcatch_rename"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "new_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.runoffs",
+   "target": "subcatchments",
+   "name": "runoffs",
+   "form": "property",
+   "python": "Subcatchments.runoffs",
+   "doc": "Get runoff rates for all subcatchments in a single call.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_runoff_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "flow"
+  },
+  {
+   "path": "subcatchments.set_gwf_expression",
+   "target": "subcatchments",
+   "name": "set_gwf_expression",
+   "form": "method",
+   "python": "Subcatchments.set_gwf_expression",
+   "doc": "Set or clear a subcatchment's [GWF] expression.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_index",
+    "swmm_subcatch_set_gwf_expression"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "gwf_type",
+     "type": "Union[GwfType, int]",
+     "required": true
+    },
+    {
+     "name": "expression",
+     "type": "Optional[str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "subcatchments.snow_depths",
+   "target": "subcatchments",
+   "name": "snow_depths",
+   "form": "property",
+   "python": "Subcatchments.snow_depths",
+   "doc": "Get snow depths for all subcatchments in a single call.",
+   "c": [
+    "swmm_subcatch_count",
+    "swmm_subcatch_get_snow_depth_bulk"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "subcatchments.validate_gwf_expression",
+   "target": "subcatchments",
+   "name": "validate_gwf_expression",
+   "form": "method",
+   "python": "Subcatchments.validate_gwf_expression",
+   "doc": "Validate a [GWF] expression WITHOUT modifying the engine.",
+   "c": [
+    "swmm_gwf_validate_expression"
+   ],
+   "returns": "Tuple[bool, str, int]",
+   "params": [
+    {
+     "name": "expression",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.add_triangle_coupling",
+   "target": "surface2d",
+   "name": "add_triangle_coupling",
+   "form": "method",
+   "python": "Surface2D.add_triangle_coupling",
+   "doc": "Append one node->cell coupling row for a triangle.",
+   "c": [
+    "swmm_2d_add_triangle_coupling"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "node_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "cd",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "area",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.boundary_edge_count",
+   "target": "surface2d",
+   "name": "boundary_edge_count",
+   "form": "property",
+   "python": "Surface2D.boundary_edge_count",
+   "doc": "Number of boundary edges in the 2D mesh.",
+   "c": [
+    "swmm_2d_boundary_edge_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.clear_triangle_couplings",
+   "target": "surface2d",
+   "name": "clear_triangle_couplings",
+   "form": "method",
+   "python": "Surface2D.clear_triangle_couplings",
+   "doc": "Remove every authored node->cell coupling row (all triangles).",
+   "c": [
+    "swmm_2d_clear_triangle_couplings"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "surface2d.continuity_error",
+   "target": "surface2d",
+   "name": "continuity_error",
+   "form": "property",
+   "python": "Surface2D.continuity_error",
+   "doc": "Global 2D surface continuity error.",
+   "c": [
+    "swmm_2d_get_continuity_error"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "fraction"
+  },
+  {
+   "path": "surface2d.dry_depth",
+   "target": "surface2d",
+   "name": "dry_depth",
+   "form": "property",
+   "python": "Surface2D.dry_depth",
+   "doc": "Dry-depth threshold (m); triangles below this are treated as dry.",
+   "c": [
+    "swmm_2d_get_dry_depth",
+    "swmm_2d_set_dry_depth"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "m"
+  },
+  {
+   "path": "surface2d.edge_stride",
+   "target": "surface2d",
+   "name": "edge_stride",
+   "form": "property",
+   "python": "Surface2D.edge_stride",
+   "doc": "Edge slots per cell row in the bulk edge arrays: 3 for an all-triangle mesh (historical [tri*3 + localEdge] layout), 4 once the mesh holds any quad ([cell*4 + localEdge]).",
+   "c": [
+    "swmm_2d_edge_stride"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.force_clear_all",
+   "target": "surface2d",
+   "name": "force_clear_all",
+   "form": "method",
+   "python": "Surface2D.force_clear_all",
+   "doc": "Clear all 2D forcings.",
+   "c": [
+    "swmm_2d_force_clear_all"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "surface2d.force_coupling_flux",
+   "target": "surface2d",
+   "name": "force_coupling_flux",
+   "form": "method",
+   "python": "Surface2D.force_coupling_flux",
+   "doc": "Force a coupling flux on a specific triangle.",
+   "c": [
+    "swmm_2d_force_coupling_flux"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "SurfaceForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "ForcingPersist",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.force_evap",
+   "target": "surface2d",
+   "name": "force_evap",
+   "form": "method",
+   "python": "Surface2D.force_evap",
+   "doc": "Force evaporation on a specific triangle.",
+   "c": [
+    "swmm_2d_force_evap"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "SurfaceForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "ForcingPersist",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.force_evap_uniform",
+   "target": "surface2d",
+   "name": "force_evap_uniform",
+   "form": "method",
+   "python": "Surface2D.force_evap_uniform",
+   "doc": "Force uniform evaporation on all triangles.",
+   "c": [
+    "swmm_2d_force_evap_uniform"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "SurfaceForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "ForcingPersist",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.force_rainfall",
+   "target": "surface2d",
+   "name": "force_rainfall",
+   "form": "method",
+   "python": "Surface2D.force_rainfall",
+   "doc": "Force rainfall on a specific triangle.",
+   "c": [
+    "swmm_2d_force_rainfall"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "SurfaceForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "ForcingPersist",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.force_rainfall_uniform",
+   "target": "surface2d",
+   "name": "force_rainfall_uniform",
+   "form": "method",
+   "python": "Surface2D.force_rainfall_uniform",
+   "doc": "Force uniform rainfall on all triangles.",
+   "c": [
+    "swmm_2d_force_rainfall_uniform"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "mode",
+     "type": "SurfaceForcingMode",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "persist",
+     "type": "ForcingPersist",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_cell_neighbours",
+   "target": "surface2d",
+   "name": "get_cell_neighbours",
+   "form": "method",
+   "python": "Surface2D.get_cell_neighbours",
+   "doc": "Neighbour cell across each local edge (-1 = boundary), length 3 or 4.",
+   "c": [
+    "swmm_2d_cell_get_neighbours"
+   ],
+   "returns": "tuple[int, ...]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_cell_vertex_count",
+   "target": "surface2d",
+   "name": "get_cell_vertex_count",
+   "form": "method",
+   "python": "Surface2D.get_cell_vertex_count",
+   "doc": "Vertices (== edges) of a cell: 3 or 4.",
+   "c": [
+    "swmm_2d_cell_vertex_count"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_cell_vertices",
+   "target": "surface2d",
+   "name": "get_cell_vertices",
+   "form": "method",
+   "python": "Surface2D.get_cell_vertices",
+   "doc": "Vertex indices of any cell as a tuple of length 3 or 4. Local edge k has endpoints v[(k+1)%nv], v[(k+2)%nv].",
+   "c": [
+    "swmm_2d_cell_get_vertices"
+   ],
+   "returns": "tuple[int, ...]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_coupling_flux",
+   "target": "surface2d",
+   "name": "get_coupling_flux",
+   "form": "method",
+   "python": "Surface2D.get_coupling_flux",
+   "doc": "Return the coupling flux at a specific triangle.",
+   "c": [
+    "swmm_2d_get_coupling_flux"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_coupling_fluxes",
+   "target": "surface2d",
+   "name": "get_coupling_fluxes",
+   "form": "method",
+   "python": "Surface2D.get_coupling_fluxes",
+   "doc": "Return coupling fluxes for all triangles as a NumPy array. The GIL is released during the C call.",
+   "c": [
+    "swmm_2d_get_coupling_fluxes_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_coupling_volume_bulk",
+   "target": "surface2d",
+   "name": "get_coupling_volume_bulk",
+   "form": "method",
+   "python": "Surface2D.get_coupling_volume_bulk",
+   "doc": "Cumulative signed coupling volume, m³; positive from 1D to 2D. Returns an owned float64 array.",
+   "c": [
+    "swmm_2d_cell_count",
+    "swmm_2d_get_coupling_volume_bulk"
+   ],
+   "returns": "np.ndarray",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_depth",
+   "target": "surface2d",
+   "name": "get_depth",
+   "form": "method",
+   "python": "Surface2D.get_depth",
+   "doc": "Return the water depth at a specific triangle.",
+   "c": [
+    "swmm_2d_get_depth"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_depths",
+   "target": "surface2d",
+   "name": "get_depths",
+   "form": "method",
+   "python": "Surface2D.get_depths",
+   "doc": "Return depths for all triangles as a NumPy array.",
+   "c": [
+    "swmm_2d_get_depths_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_edge_bc_cum_flux",
+   "target": "surface2d",
+   "name": "get_edge_bc_cum_flux",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_cum_flux",
+   "doc": "Return the cumulative boundary flux for a triangle edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_cum_flux"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_flow",
+   "target": "surface2d",
+   "name": "get_edge_bc_flow",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_flow",
+   "doc": "Return the prescribed flow per metre for a SPECIFIED_FLOW edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_flow"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_flow_tseries_name",
+   "target": "surface2d",
+   "name": "get_edge_bc_flow_tseries_name",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_flow_tseries_name",
+   "doc": "Return the timeseries name driving a SPECIFIED_FLOW edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_flow_tseries_name"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_head",
+   "target": "surface2d",
+   "name": "get_edge_bc_head",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_head",
+   "doc": "Return the boundary head for a triangle edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_head"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_rating_curve_name",
+   "target": "surface2d",
+   "name": "get_edge_bc_rating_curve_name",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_rating_curve_name",
+   "doc": "Return the rating-curve name driving a RATING_CURVE edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_rating_curve_name"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_slope",
+   "target": "surface2d",
+   "name": "get_edge_bc_slope",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_slope",
+   "doc": "Return the boundary slope for a triangle edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_slope"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_tseries_name",
+   "target": "surface2d",
+   "name": "get_edge_bc_tseries_name",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_tseries_name",
+   "doc": "Return the timeseries name driving a SPECIFIED_STAGE edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_tseries_name"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_bc_type",
+   "target": "surface2d",
+   "name": "get_edge_bc_type",
+   "form": "method",
+   "python": "Surface2D.get_edge_bc_type",
+   "doc": "Return the boundary condition type for a triangle edge.",
+   "c": [
+    "swmm_2d_get_edge_bc_type"
+   ],
+   "returns": "SurfaceBoundaryType",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_conveyance",
+   "target": "surface2d",
+   "name": "get_edge_conveyance",
+   "form": "method",
+   "python": "Surface2D.get_edge_conveyance",
+   "doc": "Return the per-edge conveyance factor in [0, 1].",
+   "c": [
+    "swmm_2d_get_edge_conveyance"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "tri",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_edge_conveyance_bulk",
+   "target": "surface2d",
+   "name": "get_edge_conveyance_bulk",
+   "form": "method",
+   "python": "Surface2D.get_edge_conveyance_bulk",
+   "doc": "Return a NumPy array of all per-edge conveyance factors.",
+   "c": [
+    "swmm_2d_edge_stride",
+    "swmm_2d_get_edge_conveyance_bulk",
+    "swmm_2d_triangle_count"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_edge_flux_bulk",
+   "target": "surface2d",
+   "name": "get_edge_flux_bulk",
+   "form": "method",
+   "python": "Surface2D.get_edge_flux_bulk",
+   "doc": "Return normal edge fluxes for all triangle edges as a NumPy array. The GIL is released during the C call.",
+   "c": [
+    "swmm_2d_get_edge_flux_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_edge_geometry_bulk",
+   "target": "surface2d",
+   "name": "get_edge_geometry_bulk",
+   "form": "method",
+   "python": "Surface2D.get_edge_geometry_bulk",
+   "doc": "Return time-invariant edge lengths and outward unit normal components. The GIL is released during the C call.",
+   "c": [
+    "swmm_2d_edge_get_geometry_bulk"
+   ],
+   "returns": "tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64]]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_head",
+   "target": "surface2d",
+   "name": "get_head",
+   "form": "method",
+   "python": "Surface2D.get_head",
+   "doc": "Return the total head at a specific triangle.",
+   "c": [
+    "swmm_2d_get_head"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_heads",
+   "target": "surface2d",
+   "name": "get_heads",
+   "form": "method",
+   "python": "Surface2D.get_heads",
+   "doc": "Return total heads for all triangles as a NumPy array. The GIL is released during the C call.",
+   "c": [
+    "swmm_2d_get_heads_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_mass_balance",
+   "target": "surface2d",
+   "name": "get_mass_balance",
+   "form": "method",
+   "python": "Surface2D.get_mass_balance",
+   "doc": "Return the global 2D mass-balance terms.",
+   "c": [
+    "swmm_2d_get_continuity_error",
+    "swmm_2d_get_mass_balance"
+   ],
+   "returns": "dict[str, float]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_net_source",
+   "target": "surface2d",
+   "name": "get_net_source",
+   "form": "method",
+   "python": "Surface2D.get_net_source",
+   "doc": "Return the net source term at a specific triangle.",
+   "c": [
+    "swmm_2d_get_net_source"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_rain_volume_bulk",
+   "target": "surface2d",
+   "name": "get_rain_volume_bulk",
+   "form": "method",
+   "python": "Surface2D.get_rain_volume_bulk",
+   "doc": "Cumulative rain volume per cell, m³. Returns an owned float64 array.",
+   "c": [
+    "swmm_2d_cell_count",
+    "swmm_2d_get_rain_volume_bulk"
+   ],
+   "returns": "np.ndarray",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_rainfall",
+   "target": "surface2d",
+   "name": "get_rainfall",
+   "form": "method",
+   "python": "Surface2D.get_rainfall",
+   "doc": "Return the current rainfall at a specific triangle.",
+   "c": [
+    "swmm_2d_get_rainfall"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "units": "m/s"
+  },
+  {
+   "path": "surface2d.get_rainfall_bulk",
+   "target": "surface2d",
+   "name": "get_rainfall_bulk",
+   "form": "method",
+   "python": "Surface2D.get_rainfall_bulk",
+   "doc": "Current rainfall rate per cell, m/s. Returns an owned float64 array.",
+   "c": [
+    "swmm_2d_cell_count",
+    "swmm_2d_get_rainfall_bulk"
+   ],
+   "returns": "np.ndarray",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_stat_max_continuity_err",
+   "target": "surface2d",
+   "name": "get_stat_max_continuity_err",
+   "form": "method",
+   "python": "Surface2D.get_stat_max_continuity_err",
+   "doc": "Return cumulative maximum abs(continuity residual) envelope per triangle.",
+   "c": [
+    "swmm_2d_get_stat_max_continuity_err"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_stat_max_depths",
+   "target": "surface2d",
+   "name": "get_stat_max_depths",
+   "form": "method",
+   "python": "Surface2D.get_stat_max_depths",
+   "doc": "Return cumulative maximum-depth envelope for all triangles.",
+   "c": [
+    "swmm_2d_get_stat_max_depths"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_stat_max_velocities",
+   "target": "surface2d",
+   "name": "get_stat_max_velocities",
+   "form": "method",
+   "python": "Surface2D.get_stat_max_velocities",
+   "doc": "Return cumulative maximum velocity-magnitude envelope for all triangles.",
+   "c": [
+    "swmm_2d_get_stat_max_velocities"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_triangle_area",
+   "target": "surface2d",
+   "name": "get_triangle_area",
+   "form": "method",
+   "python": "Surface2D.get_triangle_area",
+   "doc": "Return the area of a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_area"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_centroid",
+   "target": "surface2d",
+   "name": "get_triangle_centroid",
+   "form": "method",
+   "python": "Surface2D.get_triangle_centroid",
+   "doc": "Return the (cx, cy, cz) centroid coordinates for a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_centroid"
+   ],
+   "returns": "tuple[float, float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_coupled_node",
+   "target": "surface2d",
+   "name": "get_triangle_coupled_node",
+   "form": "method",
+   "python": "Surface2D.get_triangle_coupled_node",
+   "doc": "Return the SWMM node index coupled to a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_coupled_node"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_coupling_row",
+   "target": "surface2d",
+   "name": "get_triangle_coupling_row",
+   "form": "method",
+   "python": "Surface2D.get_triangle_coupling_row",
+   "doc": "Read one authored node->cell coupling row by row index.",
+   "c": [
+    "swmm_2d_get_triangle_coupling_row"
+   ],
+   "returns": "tuple[int, int, float, float]",
+   "params": [
+    {
+     "name": "row_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_init_depth",
+   "target": "surface2d",
+   "name": "get_triangle_init_depth",
+   "form": "method",
+   "python": "Surface2D.get_triangle_init_depth",
+   "doc": "Return the initial water depth of a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_init_depth"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_init_velocity",
+   "target": "surface2d",
+   "name": "get_triangle_init_velocity",
+   "form": "method",
+   "python": "Surface2D.get_triangle_init_velocity",
+   "doc": "Return the (u, v) initial velocity of a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_init_velocity"
+   ],
+   "returns": "tuple[float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_mannings",
+   "target": "surface2d",
+   "name": "get_triangle_mannings",
+   "form": "method",
+   "python": "Surface2D.get_triangle_mannings",
+   "doc": "Return Manning's n for a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_mannings"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_neighbours",
+   "target": "surface2d",
+   "name": "get_triangle_neighbours",
+   "form": "method",
+   "python": "Surface2D.get_triangle_neighbours",
+   "doc": "Return the (n0, n1, n2) neighbour triangle indices.",
+   "c": [
+    "swmm_2d_triangle_get_neighbours"
+   ],
+   "returns": "tuple[int, int, int]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_tag",
+   "target": "surface2d",
+   "name": "get_triangle_tag",
+   "form": "method",
+   "python": "Surface2D.get_triangle_tag",
+   "doc": "Return the descriptive tag of a triangle ([2D_TRIANGLES] TAG).",
+   "c": [
+    "swmm_2d_get_triangle_tag"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_triangle_vertices",
+   "target": "surface2d",
+   "name": "get_triangle_vertices",
+   "form": "method",
+   "python": "Surface2D.get_triangle_vertices",
+   "doc": "Return the (v0, v1, v2) vertex indices for a triangle.",
+   "c": [
+    "swmm_2d_triangle_get_vertices"
+   ],
+   "returns": "tuple[int, int, int]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_coords",
+   "target": "surface2d",
+   "name": "get_vertex_coords",
+   "form": "method",
+   "python": "Surface2D.get_vertex_coords",
+   "doc": "Return (x, y, z) NumPy arrays for all vertices.",
+   "c": [
+    "swmm_2d_vertex_get_xyz_bulk"
+   ],
+   "returns": "tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64]]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_vertex_coupled_node",
+   "target": "surface2d",
+   "name": "get_vertex_coupled_node",
+   "form": "method",
+   "python": "Surface2D.get_vertex_coupled_node",
+   "doc": "Return the SWMM node index coupled to a vertex.",
+   "c": [
+    "swmm_2d_vertex_get_coupled_node"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_coupling_area",
+   "target": "surface2d",
+   "name": "get_vertex_coupling_area",
+   "form": "method",
+   "python": "Surface2D.get_vertex_coupling_area",
+   "doc": "Return the coupling exchange area of a vertex.",
+   "c": [
+    "swmm_2d_get_vertex_coupling_area"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_coupling_cd",
+   "target": "surface2d",
+   "name": "get_vertex_coupling_cd",
+   "form": "method",
+   "python": "Surface2D.get_vertex_coupling_cd",
+   "doc": "Return the coupling discharge coefficient of a vertex.",
+   "c": [
+    "swmm_2d_get_vertex_coupling_cd"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_head",
+   "target": "surface2d",
+   "name": "get_vertex_head",
+   "form": "method",
+   "python": "Surface2D.get_vertex_head",
+   "doc": "Return the water-surface head at one mesh vertex.",
+   "c": [
+    "swmm_2d_vertex_get_head"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_heads",
+   "target": "surface2d",
+   "name": "get_vertex_heads",
+   "form": "method",
+   "python": "Surface2D.get_vertex_heads",
+   "doc": "Return reconstructed heads at all vertices as a NumPy array.",
+   "c": [
+    "swmm_2d_vertex_get_heads_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_vertex_render_depths",
+   "target": "surface2d",
+   "name": "get_vertex_render_depths",
+   "form": "method",
+   "python": "Surface2D.get_vertex_render_depths",
+   "doc": "Return render-oriented signed water depths at all vertices.",
+   "c": [
+    "swmm_2d_vertex_get_render_depths_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.get_vertex_tag",
+   "target": "surface2d",
+   "name": "get_vertex_tag",
+   "form": "method",
+   "python": "Surface2D.get_vertex_tag",
+   "doc": "Return the descriptive tag of a vertex ([2D_VERTICES] TAG).",
+   "c": [
+    "swmm_2d_get_vertex_tag"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.get_vertex_xyz",
+   "target": "surface2d",
+   "name": "get_vertex_xyz",
+   "form": "method",
+   "python": "Surface2D.get_vertex_xyz",
+   "doc": "Return the (x, y, z) coordinates of one mesh vertex.",
+   "c": [
+    "swmm_2d_vertex_get_xyz"
+   ],
+   "returns": "tuple[float, float, float]",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.active",
+   "target": "surface2d.groundwater",
+   "name": "active",
+   "form": "property",
+   "python": "Groundwater.active",
+   "doc": "",
+   "c": [
+    "swmm_gw2d_is_active"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.add_node",
+   "target": "surface2d.groundwater",
+   "name": "add_node",
+   "form": "method",
+   "python": "Groundwater.add_node",
+   "doc": "Add a bed: kc in in/hr or mm/hr, dc in ft or m, area in ft² or m².",
+   "c": [
+    "swmm_gw2d_node_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "node",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "cell",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "kc",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "dc",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "area",
+     "type": "float",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.add_row",
+   "target": "surface2d.groundwater",
+   "name": "add_row",
+   "form": "method",
+   "python": "Groundwater.add_row",
+   "doc": "Append an aquifer row before initialization.",
+   "c": [
+    "swmm_gw2d_row_add"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "scope",
+     "type": "CellScope",
+     "required": true
+    },
+    {
+     "name": "ks",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "zs",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "theta_s",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "theta_r",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "alpha",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "cell",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.cell",
+   "target": "surface2d.groundwater",
+   "name": "cell",
+   "form": "method",
+   "python": "Groundwater.cell",
+   "doc": "One cell's runtime variable in SI; consult GroundwaterVariable.",
+   "c": [
+    "swmm_gw2d_get_cell"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "cell",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "variable",
+     "type": "GroundwaterVariable",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.cells",
+   "target": "surface2d.groundwater",
+   "name": "cells",
+   "form": "method",
+   "python": "Groundwater.cells",
+   "doc": "Owned float64 snapshot of a runtime variable over all cells.",
+   "c": [
+    "swmm_gw2d_get_cell_bulk",
+    "swmm_gw2d_get_dimensions"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "variable",
+     "type": "GroundwaterVariable",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.column",
+   "target": "surface2d.groundwater",
+   "name": "column",
+   "form": "method",
+   "python": "Groundwater.column",
+   "doc": "Sigma-column water contents, surface layer first; requires SIGMA closure.",
+   "c": [
+    "swmm_gw2d_get_column",
+    "swmm_gw2d_get_dimensions"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "cell",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.concentrations",
+   "target": "surface2d.groundwater",
+   "name": "concentrations",
+   "form": "method",
+   "python": "Groundwater.concentrations",
+   "doc": "Per-cell species mass per m³ of zone water; dry zones report zero.",
+   "c": [
+    "swmm_gw2d_get_cell_conc",
+    "swmm_gw2d_get_dimensions"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "zone",
+     "type": "GroundwaterZone",
+     "required": true
+    },
+    {
+     "name": "species",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.continuity_error",
+   "target": "surface2d.groundwater",
+   "name": "continuity_error",
+   "form": "property",
+   "python": "Groundwater.continuity_error",
+   "doc": "Water continuity residual in cubic metres, not a percentage.",
+   "c": [
+    "swmm_gw2d_get_continuity_error"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "m3"
+  },
+  {
+   "path": "surface2d.groundwater.dimensions",
+   "target": "surface2d.groundwater",
+   "name": "dimensions",
+   "form": "property",
+   "python": "Groundwater.dimensions",
+   "doc": "(cell count, sigma layer count); cell topology need not be triangular.",
+   "c": [
+    "swmm_gw2d_get_dimensions"
+   ],
+   "type": "tuple[int, int]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.ledger",
+   "target": "surface2d.groundwater",
+   "name": "ledger",
+   "form": "method",
+   "python": "Groundwater.ledger",
+   "doc": "Water ledger term in cubic metres (storage terms are instantaneous).",
+   "c": [
+    "swmm_gw2d_get_ledger"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "term",
+     "type": "GroundwaterLedger",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.nodes",
+   "target": "surface2d.groundwater",
+   "name": "nodes",
+   "form": "property",
+   "python": "Groundwater.nodes",
+   "doc": "Node-bed snapshots, including automatically enrolled rows after init.",
+   "c": [
+    "swmm_gw2d_node_count",
+    "swmm_gw2d_node_get",
+    "swmm_gw2d_node_get_flags"
+   ],
+   "type": "tuple[AquiferNode, ...]",
+   "access": "r"
+  },
+  {
+   "target": "surface2d.groundwater.options",
+   "form": "item",
+   "python": "AquiferOptions[]",
+   "doc": "Text options using the native INP key/value spellings.",
+   "path": "surface2d.groundwater.options.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "target": "surface2d.groundwater.options",
+   "form": "item",
+   "python": "AquiferOptions[]",
+   "doc": "Text options using the native INP key/value spellings.",
+   "path": "surface2d.groundwater.options.get_item",
+   "name": "get_item",
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_gw2d_option_get"
+   ]
+  },
+  {
+   "target": "surface2d.groundwater.options",
+   "form": "item",
+   "python": "AquiferOptions[]",
+   "doc": "Text options using the native INP key/value spellings.",
+   "path": "surface2d.groundwater.options.items",
+   "name": "items",
+   "returns": "list[tuple[str, str]]",
+   "params": [],
+   "c": [
+    "swmm_gw2d_option_get"
+   ]
+  },
+  {
+   "target": "surface2d.groundwater.options",
+   "form": "item",
+   "python": "AquiferOptions[]",
+   "doc": "Text options using the native INP key/value spellings.",
+   "path": "surface2d.groundwater.options.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_gw2d_option_set"
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.remove_node",
+   "target": "surface2d.groundwater",
+   "name": "remove_node",
+   "form": "method",
+   "python": "Groundwater.remove_node",
+   "doc": "Remove a node-bed row; subsequent indices shift.",
+   "c": [
+    "swmm_gw2d_node_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.remove_row",
+   "target": "surface2d.groundwater",
+   "name": "remove_row",
+   "form": "method",
+   "python": "Groundwater.remove_row",
+   "doc": "Remove an authored row; subsequent indices shift.",
+   "c": [
+    "swmm_gw2d_row_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.row_property",
+   "target": "surface2d.groundwater",
+   "name": "row_property",
+   "form": "method",
+   "python": "Groundwater.row_property",
+   "doc": "Read an optional authored property (HG0, PSI_B, CLOSURE, etc.).",
+   "c": [
+    "swmm_gw2d_row_get_property"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.rows",
+   "target": "surface2d.groundwater",
+   "name": "rows",
+   "form": "property",
+   "python": "Groundwater.rows",
+   "doc": "Aquifer snapshots in authored order (GLOBAL, TAG or CELL scopes).",
+   "c": [
+    "swmm_gw2d_row_count",
+    "swmm_gw2d_row_get"
+   ],
+   "type": "tuple[AquiferRow, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.set_node_exchange",
+   "target": "surface2d.groundwater",
+   "name": "set_node_exchange",
+   "form": "method",
+   "python": "Groundwater.set_node_exchange",
+   "doc": "Enable or opt out of groundwater exchange for one authored bed.",
+   "c": [
+    "swmm_gw2d_node_set_exchange"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "enabled",
+     "type": "bool",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.set_row_property",
+   "target": "surface2d.groundwater",
+   "name": "set_row_property",
+   "form": "method",
+   "python": "Groundwater.set_row_property",
+   "doc": "Set optional numeric properties; soil and closure accept enum codes.",
+   "c": [
+    "swmm_gw2d_row_set_property"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.species",
+   "target": "surface2d.groundwater",
+   "name": "species",
+   "form": "property",
+   "python": "Groundwater.species",
+   "doc": "Transported names in native policy order.",
+   "c": [
+    "swmm_gw2d_species_count",
+    "swmm_gw2d_species_name"
+   ],
+   "type": "tuple[str, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.species_ledger",
+   "target": "surface2d.groundwater",
+   "name": "species_ledger",
+   "form": "method",
+   "python": "Groundwater.species_ledger",
+   "doc": "Cumulative transported-species ledger term in the species' mass units.",
+   "c": [
+    "swmm_gw2d_get_species_ledger"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "species",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "term",
+     "type": "GroundwaterSpeciesLedger",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.tier_histogram",
+   "target": "surface2d.groundwater",
+   "name": "tier_histogram",
+   "form": "property",
+   "python": "Groundwater.tier_histogram",
+   "doc": "Owned platform C-long array of cumulative firings per LTS tier.",
+   "c": [
+    "swmm_gw2d_get_tier_histogram"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.authored",
+   "target": "surface2d.groundwater.transport",
+   "name": "authored",
+   "form": "property",
+   "python": "GroundwaterTransport.authored",
+   "doc": "Whether any groundwater transport section was authored.",
+   "c": [
+    "swmm_gw_transport_authored"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.boundaries",
+   "target": "surface2d.groundwater.transport",
+   "name": "boundaries",
+   "form": "property",
+   "python": "GroundwaterTransport.boundaries",
+   "doc": "Immutable authored row snapshots in native order.",
+   "c": [
+    "swmm_gw_boundary_quality_count",
+    "swmm_gw_boundary_quality_get"
+   ],
+   "type": "tuple[GroundwaterBoundary, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.initial_quality",
+   "target": "surface2d.groundwater.transport",
+   "name": "initial_quality",
+   "form": "property",
+   "python": "GroundwaterTransport.initial_quality",
+   "doc": "Immutable authored row snapshots in native order.",
+   "c": [
+    "swmm_gw_init_quality_count",
+    "swmm_gw_init_quality_get"
+   ],
+   "type": "tuple[GroundwaterInitialQuality, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.initial_quality_file",
+   "target": "surface2d.groundwater.transport",
+   "name": "initial_quality_file",
+   "form": "property",
+   "python": "GroundwaterTransport.initial_quality_file",
+   "doc": "Authored sidecar path; changing it records a reference for the next open.",
+   "c": [
+    "swmm_gw_init_quality_file_get",
+    "swmm_gw_init_quality_file_set"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "target": "surface2d.groundwater.transport.options",
+   "form": "item",
+   "python": "GroundwaterTransportOptions[]",
+   "doc": "Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.",
+   "path": "surface2d.groundwater.transport.options.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": []
+  },
+  {
+   "target": "surface2d.groundwater.transport.options",
+   "form": "item",
+   "python": "GroundwaterTransportOptions[]",
+   "doc": "Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.",
+   "path": "surface2d.groundwater.transport.options.get_item",
+   "name": "get_item",
+   "returns": "str",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_gw_transport_option_get"
+   ]
+  },
+  {
+   "target": "surface2d.groundwater.transport.options",
+   "form": "item",
+   "python": "GroundwaterTransportOptions[]",
+   "doc": "Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.",
+   "path": "surface2d.groundwater.transport.options.items",
+   "name": "items",
+   "returns": "list[tuple[str, str]]",
+   "params": [],
+   "c": [
+    "swmm_gw_transport_option_get"
+   ]
+  },
+  {
+   "target": "surface2d.groundwater.transport.options",
+   "form": "item",
+   "python": "GroundwaterTransportOptions[]",
+   "doc": "Native GW_TRANSPORT_OPTIONS text keys; values preserve INP spelling.",
+   "path": "surface2d.groundwater.transport.options.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_gw_transport_option_set"
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.parameters",
+   "target": "surface2d.groundwater.transport",
+   "name": "parameters",
+   "form": "property",
+   "python": "GroundwaterTransport.parameters",
+   "doc": "Thermal/material/dispersion parameter snapshots, all in native SI units.",
+   "c": [
+    "swmm_gw_params_count",
+    "swmm_gw_params_get"
+   ],
+   "type": "tuple[GroundwaterParameters, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_boundary",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_boundary",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_boundary",
+   "doc": "Remove a row; subsequent indices shift.",
+   "c": [
+    "swmm_gw_boundary_quality_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_initial_quality",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_initial_quality",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_initial_quality",
+   "doc": "Remove a row; subsequent indices shift.",
+   "c": [
+    "swmm_gw_init_quality_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_parameters",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_parameters",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_parameters",
+   "doc": "",
+   "c": [
+    "swmm_gw_params_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_sorption",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_sorption",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_sorption",
+   "doc": "Remove a row; subsequent indices shift.",
+   "c": [
+    "swmm_gw_sorption_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_source",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_source",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_source",
+   "doc": "Remove a row; subsequent indices shift.",
+   "c": [
+    "swmm_gw_source_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.remove_source_species",
+   "target": "surface2d.groundwater.transport",
+   "name": "remove_source_species",
+   "form": "method",
+   "python": "GroundwaterTransport.remove_source_species",
+   "doc": "Remove a row; subsequent indices shift.",
+   "c": [
+    "swmm_gw_source_species_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source_index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_boundary",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_boundary",
+   "form": "method",
+   "python": "GroundwaterTransport.set_boundary",
+   "doc": "Upsert an authored row; requires BUILDING or OPENED.",
+   "c": [
+    "swmm_gw_boundary_quality_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "GroundwaterBoundary",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_initial_quality",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_initial_quality",
+   "form": "method",
+   "python": "GroundwaterTransport.set_initial_quality",
+   "doc": "Upsert an authored row; requires BUILDING or OPENED.",
+   "c": [
+    "swmm_gw_init_quality_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "GroundwaterInitialQuality",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_parameters",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_parameters",
+   "form": "method",
+   "python": "GroundwaterTransport.set_parameters",
+   "doc": "Upsert material parameters by scope/tag/cell; edit before initialization.",
+   "c": [
+    "swmm_gw_params_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "GroundwaterParameters",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_sorption",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_sorption",
+   "form": "method",
+   "python": "GroundwaterTransport.set_sorption",
+   "doc": "Upsert an authored row; requires BUILDING or OPENED.",
+   "c": [
+    "swmm_gw_sorption_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "GroundwaterSorption",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_source",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_source",
+   "form": "method",
+   "python": "GroundwaterTransport.set_source",
+   "doc": "Upsert an authored row; requires BUILDING or OPENED.",
+   "c": [
+    "swmm_gw_source_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "row",
+     "type": "GroundwaterSource",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.set_source_species",
+   "target": "surface2d.groundwater.transport",
+   "name": "set_source_species",
+   "form": "method",
+   "python": "GroundwaterTransport.set_source_species",
+   "doc": "Upsert an authored row; requires BUILDING or OPENED.",
+   "c": [
+    "swmm_gw_source_species_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source_index",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "row",
+     "type": "GroundwaterSourceTerm",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.sorption",
+   "target": "surface2d.groundwater.transport",
+   "name": "sorption",
+   "form": "property",
+   "python": "GroundwaterTransport.sorption",
+   "doc": "Immutable authored row snapshots in native order.",
+   "c": [
+    "swmm_gw_sorption_count",
+    "swmm_gw_sorption_get"
+   ],
+   "type": "tuple[GroundwaterSorption, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.groundwater.transport.source_species",
+   "target": "surface2d.groundwater.transport",
+   "name": "source_species",
+   "form": "method",
+   "python": "GroundwaterTransport.source_species",
+   "doc": "Immutable authored row snapshots in native order.",
+   "c": [
+    "swmm_gw_source_species_count",
+    "swmm_gw_source_species_get"
+   ],
+   "returns": "tuple[GroundwaterSourceTerm, ...]",
+   "params": [
+    {
+     "name": "source_index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.groundwater.transport.sources",
+   "target": "surface2d.groundwater.transport",
+   "name": "sources",
+   "form": "property",
+   "python": "GroundwaterTransport.sources",
+   "doc": "Immutable authored row snapshots in native order.",
+   "c": [
+    "swmm_gw_source_count",
+    "swmm_gw_source_get"
+   ],
+   "type": "tuple[GroundwaterSource, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.infiltration.cell",
+   "target": "surface2d.infiltration",
+   "name": "cell",
+   "form": "method",
+   "python": "Infiltration2DView.cell",
+   "doc": "Return the infiltration specification in force at one triangle.",
+   "c": [
+    "swmm_infil2d_get_cell"
+   ],
+   "returns": "Infil2DCell",
+   "params": [
+    {
+     "name": "tri",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.infiltration.cumulative",
+   "target": "surface2d.infiltration",
+   "name": "cumulative",
+   "form": "method",
+   "python": "Infiltration2DView.cumulative",
+   "doc": "Return the cumulative infiltrated depth per cell as a NumPy array.",
+   "c": [
+    "swmm_2d_triangle_count",
+    "swmm_infil2d_get_cum_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "target": "surface2d.infiltration.defaults",
+   "form": "item",
+   "python": "Infil2DDefaults[]",
+   "doc": "surface2d.infiltration.defaults — tag → Infil2DRow mapping.",
+   "path": "surface2d.infiltration.defaults.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_infil2d_remove_default"
+   ]
+  },
+  {
+   "target": "surface2d.infiltration.defaults",
+   "form": "item",
+   "python": "Infil2DDefaults[]",
+   "doc": "surface2d.infiltration.defaults — tag → Infil2DRow mapping.",
+   "path": "surface2d.infiltration.defaults.get_item",
+   "name": "get_item",
+   "returns": "Infil2DRow",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_infil2d_defaults_count",
+    "swmm_infil2d_get_default",
+    "swmm_infil2d_get_default_tag"
+   ]
+  },
+  {
+   "target": "surface2d.infiltration.defaults",
+   "form": "item",
+   "python": "Infil2DDefaults[]",
+   "doc": "surface2d.infiltration.defaults — tag → Infil2DRow mapping.",
+   "path": "surface2d.infiltration.defaults.items",
+   "name": "items",
+   "returns": "list[tuple[str, Infil2DRow]]",
+   "params": [],
+   "c": [
+    "swmm_infil2d_defaults_count",
+    "swmm_infil2d_get_default",
+    "swmm_infil2d_get_default_tag"
+   ]
+  },
+  {
+   "target": "surface2d.infiltration.defaults",
+   "form": "item",
+   "python": "Infil2DDefaults[]",
+   "doc": "surface2d.infiltration.defaults — tag → Infil2DRow mapping.",
+   "path": "surface2d.infiltration.defaults.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Infil2DRow",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_infil2d_set_default"
+   ]
+  },
+  {
+   "path": "surface2d.infiltration.infil_step",
+   "target": "surface2d.infiltration",
+   "name": "infil_step",
+   "form": "property",
+   "python": "Infiltration2DView.infil_step",
+   "doc": "Evaluation cadence in seconds ([2D_INFILTRATION_OPTIONS]).",
+   "c": [
+    "swmm_infil2d_get_options",
+    "swmm_infil2d_set_options"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "s"
+  },
+  {
+   "path": "surface2d.infiltration.rate",
+   "target": "surface2d.infiltration",
+   "name": "rate",
+   "form": "method",
+   "python": "Infiltration2DView.rate",
+   "doc": "Return the held per-cell infiltration rate as a NumPy array.",
+   "c": [
+    "swmm_2d_triangle_count",
+    "swmm_infil2d_get_rate_bulk"
+   ],
+   "returns": "npt.NDArray[np.float64]",
+   "params": []
+  },
+  {
+   "path": "surface2d.infiltration.set_cell",
+   "target": "surface2d.infiltration",
+   "name": "set_cell",
+   "form": "method",
+   "python": "Infiltration2DView.set_cell",
+   "doc": "Set (or clear) the per-cell override of one triangle.",
+   "c": [
+    "swmm_infil2d_set_cell"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "row",
+     "type": "Infil2DRow | None",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.infiltration.set_cells",
+   "target": "surface2d.infiltration",
+   "name": "set_cells",
+   "form": "method",
+   "python": "Infiltration2DView.set_cells",
+   "doc": "Assign one specification to many triangles in a single call.",
+   "c": [
+    "swmm_infil2d_set_cells"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tris",
+     "type": "Sequence[int]",
+     "required": true
+    },
+    {
+     "name": "row",
+     "type": "Infil2DRow | None",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.infiltration.total_volume",
+   "target": "surface2d.infiltration",
+   "name": "total_volume",
+   "form": "property",
+   "python": "Infiltration2DView.total_volume",
+   "doc": "Cumulative 2D infiltration loss in m³ (the infil_out row).",
+   "c": [
+    "swmm_infil2d_get_total_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "m3"
+  },
+  {
+   "path": "surface2d.is_active",
+   "target": "surface2d",
+   "name": "is_active",
+   "form": "property",
+   "python": "Surface2D.is_active",
+   "doc": "True if the 2D module is active for this simulation.",
+   "c": [
+    "swmm_2d_is_active"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.max_depth",
+   "target": "surface2d",
+   "name": "max_depth",
+   "form": "property",
+   "python": "Surface2D.max_depth",
+   "doc": "Maximum depth across all triangles.",
+   "c": [
+    "swmm_2d_get_max_depth"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "m"
+  },
+  {
+   "path": "surface2d.n_cells",
+   "target": "surface2d",
+   "name": "n_cells",
+   "form": "property",
+   "python": "Surface2D.n_cells",
+   "doc": "Number of mesh cells (triangles + quads).",
+   "c": [
+    "swmm_2d_cell_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.n_quads",
+   "target": "surface2d",
+   "name": "n_quads",
+   "form": "property",
+   "python": "Surface2D.n_quads",
+   "doc": "Number of quadrilateral cells (0 for an all-triangle mesh).",
+   "c": [
+    "swmm_2d_quad_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.n_triangles",
+   "target": "surface2d",
+   "name": "n_triangles",
+   "form": "property",
+   "python": "Surface2D.n_triangles",
+   "doc": "Number of mesh cells (triangles + quads; historical name).",
+   "c": [
+    "swmm_2d_triangle_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.n_vertices",
+   "target": "surface2d",
+   "name": "n_vertices",
+   "form": "property",
+   "python": "Surface2D.n_vertices",
+   "doc": "Number of mesh vertices.",
+   "c": [
+    "swmm_2d_vertex_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.output_variable_mask",
+   "target": "surface2d",
+   "name": "output_variable_mask",
+   "form": "method",
+   "python": "Surface2D.output_variable_mask",
+   "doc": "Parse DEFAULT/MINIMAL/ALL or a native variable list into a mask.",
+   "c": [
+    "swmm_2d_output_variable_mask"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "text",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "surface2d.output_variable_text",
+   "target": "surface2d",
+   "name": "output_variable_text",
+   "form": "method",
+   "python": "Surface2D.output_variable_text",
+   "doc": "Return canonical variable text for a mask.",
+   "c": [
+    "swmm_2d_output_variable_text"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "mask",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "surface2d.output_variables",
+   "target": "surface2d",
+   "name": "output_variables",
+   "form": "method",
+   "python": "Surface2D.output_variables",
+   "doc": "Supported 2D output variable names in native order.",
+   "c": [
+    "swmm_2d_output_variable_count",
+    "swmm_2d_output_variable_name"
+   ],
+   "returns": "tuple[str, ...]",
+   "params": [],
+   "static": true
+  },
+  {
+   "path": "surface2d.prepare_for_edit",
+   "target": "surface2d",
+   "name": "prepare_for_edit",
+   "form": "method",
+   "python": "Surface2D.prepare_for_edit",
+   "doc": "Make the parsed 2D mesh editable without a full initialize().",
+   "c": [
+    "swmm_2d_prepare_for_edit"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "surface2d.quality.buildup",
+   "target": "surface2d.quality",
+   "name": "buildup",
+   "form": "method",
+   "python": "SurfaceQuality.buildup",
+   "doc": "Owned float64 per-cell buildup in project mass per acre/hectare.",
+   "c": [
+    "swmm_2d_cell_count",
+    "swmm_2d_get_buildup_bulk"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "species",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.coverages",
+   "target": "surface2d.quality",
+   "name": "coverages",
+   "form": "property",
+   "python": "SurfaceQuality.coverages",
+   "doc": "Immutable whole-scope coverage snapshots; percentages sum to <=100.",
+   "c": [
+    "swmm_2d_coverage_count",
+    "swmm_2d_coverage_get",
+    "swmm_2d_coverage_row_size"
+   ],
+   "type": "tuple[SurfaceCoverage, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.quality.curb_lengths",
+   "target": "surface2d.quality",
+   "name": "curb_lengths",
+   "form": "property",
+   "python": "SurfaceQuality.curb_lengths",
+   "doc": "Authored curb-length snapshots in project length units.",
+   "c": [
+    "swmm_2d_curb_length_count",
+    "swmm_2d_curb_length_get"
+   ],
+   "type": "tuple[SurfaceCurbLength, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.quality.loadings",
+   "target": "surface2d.quality",
+   "name": "loadings",
+   "form": "property",
+   "python": "SurfaceQuality.loadings",
+   "doc": "Initial buildup snapshots, in project mass per acre/hectare.",
+   "c": [
+    "swmm_2d_loading_count",
+    "swmm_2d_loading_get"
+   ],
+   "type": "tuple[SurfaceLoading, ...]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.quality.remove_coverage",
+   "target": "surface2d.quality",
+   "name": "remove_coverage",
+   "form": "method",
+   "python": "SurfaceQuality.remove_coverage",
+   "doc": "Remove an authored scope row; subsequent indices shift.",
+   "c": [
+    "swmm_2d_coverage_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.remove_curb_length",
+   "target": "surface2d.quality",
+   "name": "remove_curb_length",
+   "form": "method",
+   "python": "SurfaceQuality.remove_curb_length",
+   "doc": "Remove an authored curb-length row.",
+   "c": [
+    "swmm_2d_curb_length_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.remove_loading",
+   "target": "surface2d.quality",
+   "name": "remove_loading",
+   "form": "method",
+   "python": "SurfaceQuality.remove_loading",
+   "doc": "Remove one initial-buildup row.",
+   "c": [
+    "swmm_2d_loading_remove"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "index",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.set_coverage",
+   "target": "surface2d.quality",
+   "name": "set_coverage",
+   "form": "method",
+   "python": "SurfaceQuality.set_coverage",
+   "doc": "Replace the complete coverage set at a scope from a name→percent mapping.",
+   "c": [
+    "swmm_2d_coverage_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "scope",
+     "type": "CellScope",
+     "required": true
+    },
+    {
+     "name": "landuses",
+     "type": "Mapping[str, float]",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "cell",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.set_curb_length",
+   "target": "surface2d.quality",
+   "name": "set_curb_length",
+   "form": "method",
+   "python": "SurfaceQuality.set_curb_length",
+   "doc": "Upsert a positive curb length at one scope, in project length units.",
+   "c": [
+    "swmm_2d_curb_length_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "scope",
+     "type": "CellScope",
+     "required": true
+    },
+    {
+     "name": "length",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "cell",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.quality.set_loading",
+   "target": "surface2d.quality",
+   "name": "set_loading",
+   "form": "method",
+   "python": "SurfaceQuality.set_loading",
+   "doc": "Upsert initial species buildup at GLOBAL, TAG or CELL scope.",
+   "c": [
+    "swmm_2d_loading_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "scope",
+     "type": "CellScope",
+     "required": true
+    },
+    {
+     "name": "species",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "cell",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.rainfall_weights",
+   "target": "surface2d",
+   "name": "rainfall_weights",
+   "form": "method",
+   "python": "Surface2D.rainfall_weights",
+   "doc": "Return (method, gage indices, weights) as owned snapshots.",
+   "c": [
+    "swmm_2d_get_rainfall_weights"
+   ],
+   "returns": "tuple[int, np.ndarray, np.ndarray]",
+   "params": [
+    {
+     "name": "cell",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.reset_edge_conveyance",
+   "target": "surface2d",
+   "name": "reset_edge_conveyance",
+   "form": "method",
+   "python": "Surface2D.reset_edge_conveyance",
+   "doc": "Reset every edge's conveyance factor to 1.0 (unrestricted).",
+   "c": [
+    "swmm_2d_reset_edge_conveyance"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "surface2d.run_stats",
+   "target": "surface2d",
+   "name": "run_stats",
+   "form": "property",
+   "python": "Surface2D.run_stats",
+   "doc": "Cumulative marcher statistics and the backend of this 2D run.",
+   "c": [
+    "swmm_2d_get_run_stats"
+   ],
+   "type": "dict[str, Any]",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.set_edge_bc_flow",
+   "target": "surface2d",
+   "name": "set_edge_bc_flow",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_flow",
+   "doc": "Set the prescribed flow per metre for a SPECIFIED_FLOW edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_flow"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "flow",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_flow_tseries_name",
+   "target": "surface2d",
+   "name": "set_edge_bc_flow_tseries_name",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_flow_tseries_name",
+   "doc": "Set the timeseries name driving a SPECIFIED_FLOW edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_flow_tseries_name"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_head",
+   "target": "surface2d",
+   "name": "set_edge_bc_head",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_head",
+   "doc": "Set the boundary head for a triangle edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_head"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "head",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_rating_curve_name",
+   "target": "surface2d",
+   "name": "set_edge_bc_rating_curve_name",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_rating_curve_name",
+   "doc": "Set the rating-curve name driving a RATING_CURVE edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_rating_curve_name"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_slope",
+   "target": "surface2d",
+   "name": "set_edge_bc_slope",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_slope",
+   "doc": "Set the boundary slope for a triangle edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_slope"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "slope",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_tseries_name",
+   "target": "surface2d",
+   "name": "set_edge_bc_tseries_name",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_tseries_name",
+   "doc": "Set the timeseries name driving a SPECIFIED_STAGE edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_tseries_name"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_bc_type",
+   "target": "surface2d",
+   "name": "set_edge_bc_type",
+   "form": "method",
+   "python": "Surface2D.set_edge_bc_type",
+   "doc": "Set the boundary condition type for a triangle edge.",
+   "c": [
+    "swmm_2d_set_edge_bc_type"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "bc_type",
+     "type": "SurfaceBoundaryType",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_edge_conveyance",
+   "target": "surface2d",
+   "name": "set_edge_conveyance",
+   "form": "method",
+   "python": "Surface2D.set_edge_conveyance",
+   "doc": "Set the per-edge conveyance factor in [0, 1].",
+   "c": [
+    "swmm_2d_set_edge_conveyance"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "tri",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "edge",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "conveyance",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_triangle_init_depth",
+   "target": "surface2d",
+   "name": "set_triangle_init_depth",
+   "form": "method",
+   "python": "Surface2D.set_triangle_init_depth",
+   "doc": "Set the initial water depth of a triangle.",
+   "c": [
+    "swmm_2d_set_triangle_init_depth"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "depth",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_triangle_init_velocity",
+   "target": "surface2d",
+   "name": "set_triangle_init_velocity",
+   "form": "method",
+   "python": "Surface2D.set_triangle_init_velocity",
+   "doc": "Set the (u, v) initial velocity of a triangle.",
+   "c": [
+    "swmm_2d_set_triangle_init_velocity"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "u",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "v",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_triangle_mannings",
+   "target": "surface2d",
+   "name": "set_triangle_mannings",
+   "form": "method",
+   "python": "Surface2D.set_triangle_mannings",
+   "doc": "Set Manning's n for a triangle.",
+   "c": [
+    "swmm_2d_set_triangle_mannings"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "n",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_triangle_tag",
+   "target": "surface2d",
+   "name": "set_triangle_tag",
+   "form": "method",
+   "python": "Surface2D.set_triangle_tag",
+   "doc": "Set the descriptive tag of a triangle ([2D_TRIANGLES] TAG).",
+   "c": [
+    "swmm_2d_set_triangle_tag"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_coupled_node",
+   "target": "surface2d",
+   "name": "set_vertex_coupled_node",
+   "form": "method",
+   "python": "Surface2D.set_vertex_coupled_node",
+   "doc": "Couple a mesh vertex to a 1D SWMM node by name.",
+   "c": [
+    "swmm_2d_set_vertex_coupled_node"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "node_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_coupling_area",
+   "target": "surface2d",
+   "name": "set_vertex_coupling_area",
+   "form": "method",
+   "python": "Surface2D.set_vertex_coupling_area",
+   "doc": "Set the coupling exchange area of a vertex.",
+   "c": [
+    "swmm_2d_set_vertex_coupling_area"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "area",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_coupling_cd",
+   "target": "surface2d",
+   "name": "set_vertex_coupling_cd",
+   "form": "method",
+   "python": "Surface2D.set_vertex_coupling_cd",
+   "doc": "Set the coupling discharge coefficient of a vertex.",
+   "c": [
+    "swmm_2d_set_vertex_coupling_cd"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "vertex_idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "cd",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_tag",
+   "target": "surface2d",
+   "name": "set_vertex_tag",
+   "form": "method",
+   "python": "Surface2D.set_vertex_tag",
+   "doc": "Set the descriptive tag of a vertex ([2D_VERTICES] TAG).",
+   "c": [
+    "swmm_2d_set_vertex_tag"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "tag",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_z",
+   "target": "surface2d",
+   "name": "set_vertex_z",
+   "form": "method",
+   "python": "Surface2D.set_vertex_z",
+   "doc": "Set the ground elevation of a mesh vertex.",
+   "c": [
+    "swmm_2d_set_vertex_z"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "z",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.set_vertex_z_bulk",
+   "target": "surface2d",
+   "name": "set_vertex_z_bulk",
+   "form": "method",
+   "python": "Surface2D.set_vertex_z_bulk",
+   "doc": "Set EVERY vertex ground elevation in one call.",
+   "c": [
+    "swmm_2d_set_vertex_z_bulk"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "z",
+     "type": "Sequence[float] | npt.NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "surface2d.solver_last_step",
+   "target": "surface2d",
+   "name": "solver_last_step",
+   "form": "property",
+   "python": "Surface2D.solver_last_step",
+   "doc": "The explicit marcher's last sub-step size in seconds.",
+   "c": [
+    "swmm_2d_get_solver_last_step"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "s"
+  },
+  {
+   "path": "surface2d.solver_steps",
+   "target": "surface2d",
+   "name": "solver_steps",
+   "form": "property",
+   "python": "Surface2D.solver_steps",
+   "doc": "Number of explicit-marcher sub-steps in the last advance.",
+   "c": [
+    "swmm_2d_get_solver_steps"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.total_exchange_flow",
+   "target": "surface2d",
+   "name": "total_exchange_flow",
+   "form": "property",
+   "python": "Surface2D.total_exchange_flow",
+   "doc": "Total exchange flow rate.",
+   "c": [
+    "swmm_2d_get_total_exchange_flow"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "m3/s"
+  },
+  {
+   "path": "surface2d.total_volume",
+   "target": "surface2d",
+   "name": "total_volume",
+   "form": "property",
+   "python": "Surface2D.total_volume",
+   "doc": "Total 2D surface volume (sum of depth x area).",
+   "c": [
+    "swmm_2d_get_total_volume"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "m3"
+  },
+  {
+   "path": "surface2d.triangle_coupling_count",
+   "target": "surface2d",
+   "name": "triangle_coupling_count",
+   "form": "property",
+   "python": "Surface2D.triangle_coupling_count",
+   "doc": "Number of triangle-to-node coupling points.",
+   "c": [
+    "swmm_2d_triangle_coupling_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.triangle_coupling_rows",
+   "target": "surface2d",
+   "name": "triangle_coupling_rows",
+   "form": "property",
+   "python": "Surface2D.triangle_coupling_rows",
+   "doc": "Number of authored node->cell coupling rows.",
+   "c": [
+    "swmm_2d_triangle_coupling_rows"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "surface2d.vertex_coupling_count",
+   "target": "surface2d",
+   "name": "vertex_coupling_count",
+   "form": "property",
+   "python": "Surface2D.vertex_coupling_count",
+   "doc": "Number of vertex-to-node coupling points.",
+   "c": [
+    "swmm_2d_vertex_coupling_count"
+   ],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "table.add",
+   "target": "table",
+   "name": "add",
+   "form": "method",
+   "python": "TimeSeries.add",
+   "doc": "Append a (when, value) point. when is datetime or a SWMM DateTime float.",
+   "c": [],
+   "returns": "None",
+   "params": [
+    {
+     "name": "when",
+     "type": "Union[datetime, float]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "variant": "TimeSeries"
+  },
+  {
+   "path": "table.add_point",
+   "target": "table",
+   "name": "add_point",
+   "form": "method",
+   "python": "_PointTable.add_point",
+   "doc": "Append an (x, y) point to the table.",
+   "c": [
+    "swmm_table_add_point"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "y",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "table.clear",
+   "target": "table",
+   "name": "clear",
+   "form": "method",
+   "python": "_PointTable.clear",
+   "doc": "Remove all points.",
+   "c": [
+    "swmm_table_clear"
+   ],
+   "returns": "None",
+   "params": []
+  },
+  {
+   "path": "table.id",
+   "target": "table",
+   "name": "id",
+   "form": "property",
+   "python": "_PointTable.id",
+   "doc": "Get the string identifier of a table by index.",
+   "c": [
+    "swmm_table_id"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "table.index",
+   "target": "table",
+   "name": "index",
+   "form": "property",
+   "python": "_PointTable.index",
+   "doc": "",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "table.lookup",
+   "target": "table",
+   "name": "lookup",
+   "form": "method",
+   "python": "_PointTable.lookup",
+   "doc": "Interpolate y at x using the underlying SWMM lookup.",
+   "c": [
+    "swmm_table_lookup"
+   ],
+   "returns": "float",
+   "params": [
+    {
+     "name": "x",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "table.points",
+   "target": "table",
+   "name": "points",
+   "form": "property",
+   "python": "TimeSeries.points",
+   "doc": "Structured numpy array with columns time: datetime64[s] and value: float64.",
+   "c": [
+    "swmm_table_get_point",
+    "swmm_table_get_point_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "variant": "TimeSeries"
+  },
+  {
+   "path": "table.points",
+   "target": "table",
+   "name": "points",
+   "form": "property",
+   "python": "Curve.points",
+   "doc": "float64 (n_points, 2) numpy array.",
+   "c": [
+    "swmm_table_get_point",
+    "swmm_table_get_point_count"
+   ],
+   "type": "NDArray[Any]",
+   "access": "r",
+   "variant": "Curve"
+  },
+  {
+   "path": "table.relative_info",
+   "target": "table",
+   "name": "relative_info",
+   "form": "property",
+   "python": "TimeSeries.relative_info",
+   "doc": "(number of leading relative rows, OADate anchor in days).",
+   "c": [
+    "swmm_timeseries_get_relative_info"
+   ],
+   "type": "tuple[int, float]",
+   "access": "r",
+   "variant": "TimeSeries"
+  },
+  {
+   "path": "table.set_relative_info",
+   "target": "table",
+   "name": "set_relative_info",
+   "form": "method",
+   "python": "TimeSeries.set_relative_info",
+   "doc": "Mark leading rows as relative without changing stored x values.",
+   "c": [
+    "swmm_timeseries_set_relative_info"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "count",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "anchor",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "variant": "TimeSeries"
+  },
+  {
+   "path": "tables.add_curve",
+   "target": "tables",
+   "name": "add_curve",
+   "form": "method",
+   "python": "Tables.add_curve",
+   "doc": "curve_type is the legacy CurveType integer code; the C API accepts 0 for the default.",
+   "c": [
+    "swmm_curve_add",
+    "swmm_table_get_point",
+    "swmm_table_get_point_count",
+    "swmm_table_index"
+   ],
+   "returns": "Curve",
+   "params": [
+    {
+     "name": "curve_id",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "curve_type",
+     "type": "int",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "tables.add_timeseries",
+   "target": "tables",
+   "name": "add_timeseries",
+   "form": "method",
+   "python": "Tables.add_timeseries",
+   "doc": "Add a new time series *ts_id* and return its TimeSeries handle.",
+   "c": [
+    "swmm_table_get_point",
+    "swmm_table_get_point_count",
+    "swmm_table_index",
+    "swmm_timeseries_add",
+    "swmm_timeseries_get_relative_info"
+   ],
+   "returns": "TimeSeries",
+   "params": [
+    {
+     "name": "ts_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "tables.as_curve",
+   "target": "tables",
+   "name": "as_curve",
+   "form": "method",
+   "python": "Tables.as_curve",
+   "doc": "Return a Curve view of the table identified by *key*.",
+   "c": [
+    "swmm_table_count",
+    "swmm_table_get_point",
+    "swmm_table_get_point_count",
+    "swmm_table_index"
+   ],
+   "returns": "Curve",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "tables.as_timeseries",
+   "target": "tables",
+   "name": "as_timeseries",
+   "form": "method",
+   "python": "Tables.as_timeseries",
+   "doc": "Return a TimeSeries view of the table identified by *key*.",
+   "c": [
+    "swmm_table_count",
+    "swmm_table_get_point",
+    "swmm_table_get_point_count",
+    "swmm_table_index",
+    "swmm_timeseries_get_relative_info"
+   ],
+   "returns": "TimeSeries",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "tables.get_id",
+   "target": "tables",
+   "name": "get_id",
+   "form": "method",
+   "python": "Tables.get_id",
+   "doc": "Return the ID string of the table at *idx*.",
+   "c": [
+    "swmm_table_id"
+   ],
+   "returns": "str",
+   "params": [
+    {
+     "name": "idx",
+     "type": "int",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "tables.get_index",
+   "target": "tables",
+   "name": "get_index",
+   "form": "method",
+   "python": "Tables.get_index",
+   "doc": "Return the zero-based index of table *table_id* (raises if unknown).",
+   "c": [
+    "swmm_table_index"
+   ],
+   "returns": "int",
+   "params": [
+    {
+     "name": "table_id",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "tables.get_type",
+   "target": "tables",
+   "name": "get_type",
+   "form": "method",
+   "python": "Tables.get_type",
+   "doc": "The type of a table, as a TableType.",
+   "c": [
+    "swmm_table_count",
+    "swmm_table_get_type",
+    "swmm_table_index"
+   ],
+   "returns": "TableType",
+   "params": [
+    {
+     "name": "key",
+     "type": "int | str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "term.expression",
+   "target": "term",
+   "name": "expression",
+   "form": "property",
+   "python": "ReactionTerm.expression",
+   "doc": "The term's source expression text.",
+   "c": [
+    "swmm_reaction_term_get",
+    "swmm_reaction_term_set_expr"
+   ],
+   "type": "str",
+   "access": "rw"
+  },
+  {
+   "path": "term.index",
+   "target": "term",
+   "name": "index",
+   "form": "property",
+   "python": "ReactionTerm.index",
+   "doc": "Zero-based position in [REACTION_TERMS] — its ordering rank.",
+   "c": [],
+   "type": "int",
+   "access": "r"
+  },
+  {
+   "path": "term.name",
+   "target": "term",
+   "name": "name",
+   "form": "property",
+   "python": "ReactionTerm.name",
+   "doc": "Term name as referenced from later terms and species expressions.",
+   "c": [
+    "swmm_reaction_term_get"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "thread_info",
+   "target": "solver",
+   "name": "thread_info",
+   "form": "property",
+   "python": "Solver.thread_info",
+   "doc": "Process-wide hardware and OpenMP limits.",
+   "c": [
+    "swmm_get_thread_info"
+   ],
+   "type": "ThreadInfo",
+   "access": "r"
+  },
+  {
+   "path": "transport.boundaries",
+   "target": "transport",
+   "name": "boundaries",
+   "form": "property",
+   "python": "Transport.boundaries",
+   "doc": "Authored rows; value is concentration in species units.",
+   "c": [
+    "swmm_transport_boundary_count",
+    "swmm_transport_get_boundary"
+   ],
+   "type": "tuple[TransportRow, ...]",
+   "access": "r"
+  },
+  {
+   "path": "transport.conduit_dispersion",
+   "target": "transport",
+   "name": "conduit_dispersion",
+   "form": "property",
+   "python": "Transport.conduit_dispersion",
+   "doc": "Immutable per-conduit (link index, coefficient) snapshots.",
+   "c": [
+    "swmm_transport_conduit_disp_count",
+    "swmm_transport_get_conduit_disp"
+   ],
+   "type": "tuple[ConduitDispersion, ...]",
+   "access": "r"
+  },
+  {
+   "path": "transport.configured",
+   "target": "transport",
+   "name": "configured",
+   "form": "property",
+   "python": "Transport.configured",
+   "doc": "Whether an ARD transport component is configured.",
+   "c": [
+    "swmm_transport_get_configured"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "transport.dispersion_mode",
+   "target": "transport",
+   "name": "dispersion_mode",
+   "form": "property",
+   "python": "Transport.dispersion_mode",
+   "doc": "Global dispersion closure, including per-conduit overrides.",
+   "c": [
+    "swmm_transport_get_dispersion_mode",
+    "swmm_transport_set_dispersion_mode"
+   ],
+   "type": "TransportDispersionMode",
+   "access": "rw"
+  },
+  {
+   "path": "transport.dispersion_value",
+   "target": "transport",
+   "name": "dispersion_value",
+   "form": "property",
+   "python": "Transport.dispersion_value",
+   "doc": "Nonnegative coefficient in project length squared per second.",
+   "c": [
+    "swmm_transport_get_dispersion_value",
+    "swmm_transport_set_dispersion_value"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length2/s"
+  },
+  {
+   "path": "transport.sources",
+   "target": "transport",
+   "name": "sources",
+   "form": "property",
+   "python": "Transport.sources",
+   "doc": "Authored rows; value is mass rate in species mass units per second.",
+   "c": [
+    "swmm_transport_get_source",
+    "swmm_transport_source_count"
+   ],
+   "type": "tuple[TransportRow, ...]",
+   "access": "r"
+  },
+  {
+   "path": "transport.target_dx",
+   "target": "transport",
+   "name": "target_dx",
+   "form": "property",
+   "python": "Transport.target_dx",
+   "doc": "Nonnegative target spacing in project length; zero uses the default.",
+   "c": [
+    "swmm_transport_get_target_dx",
+    "swmm_transport_set_target_dx"
+   ],
+   "type": "float",
+   "access": "rw",
+   "units": "length"
+  },
+  {
+   "path": "transport_matrix",
+   "target": "solver",
+   "name": "transport_matrix",
+   "form": "property",
+   "python": "Solver.transport_matrix",
+   "doc": "Capability matrix keyed by domain and species class, with reasons.",
+   "c": [
+    "swmm_get_transport_matrix"
+   ],
+   "type": "dict[TransportDomain, dict[TransportClass, TransportCell]]",
+   "access": "r"
+  },
+  {
+   "path": "unit_system",
+   "target": "solver",
+   "name": "unit_system",
+   "form": "property",
+   "python": "Solver.unit_system",
+   "doc": "solver.unit_system — 'US' or 'SI'.",
+   "c": [
+    "swmm_get_unit_system"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "until",
+   "target": "solver",
+   "name": "until",
+   "form": "method",
+   "python": "Solver.until",
+   "doc": "Stride forward until the engine reaches target.",
+   "c": [],
+   "returns": "timedelta",
+   "params": [
+    {
+     "name": "target",
+     "type": "Union[datetime, timedelta]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "userflags.clear_value",
+   "target": "userflags",
+   "name": "clear_value",
+   "form": "method",
+   "python": "UserFlags.clear_value",
+   "doc": "Remove the flag value assigned to a specific object (mark unset).",
+   "c": [
+    "swmm_userflag_value_clear"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "userflags.define",
+   "target": "userflags",
+   "name": "define",
+   "form": "method",
+   "python": "UserFlags.define",
+   "doc": "Define (or redefine) a user flag ([USER_FLAGS] schema).",
+   "c": [
+    "swmm_userflag_define"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "type",
+     "type": "int",
+     "required": true
+    },
+    {
+     "name": "description",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "userflags.definitions",
+   "target": "userflags",
+   "name": "definitions",
+   "form": "method",
+   "python": "UserFlags.definitions",
+   "doc": "Return every user-flag schema definition, in insertion order.",
+   "c": [
+    "swmm_userflag_def_count",
+    "swmm_userflag_def_get"
+   ],
+   "returns": "list[UserFlagDef]",
+   "params": []
+  },
+  {
+   "target": "userflags",
+   "form": "item",
+   "python": "UserFlags[]",
+   "doc": "Typed user-flag mapping. See Solver.userflags.",
+   "path": "userflags.delete_item",
+   "name": "delete_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_userflag_undefine"
+   ]
+  },
+  {
+   "target": "userflags",
+   "form": "item",
+   "python": "UserFlags[]",
+   "doc": "Typed user-flag mapping. See Solver.userflags.",
+   "path": "userflags.get_item",
+   "name": "get_item",
+   "returns": "Union[bool, int, float, str]",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_userflag_get_bool",
+    "swmm_userflag_get_int",
+    "swmm_userflag_get_real",
+    "swmm_userflag_value_get"
+   ]
+  },
+  {
+   "path": "userflags.get_value",
+   "target": "userflags",
+   "name": "get_value",
+   "form": "method",
+   "python": "UserFlags.get_value",
+   "doc": "Return the flag value assigned to a specific object, as a string.",
+   "c": [
+    "swmm_userflag_value_get"
+   ],
+   "returns": "Optional[str]",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "target": "userflags",
+   "form": "item",
+   "python": "UserFlags[]",
+   "doc": "Typed user-flag mapping. See Solver.userflags.",
+   "path": "userflags.items",
+   "name": "items",
+   "returns": "list[tuple[str, Union[bool, int, float, str]]]",
+   "params": [],
+   "c": [
+    "swmm_userflag_def_count",
+    "swmm_userflag_get_bool",
+    "swmm_userflag_get_int",
+    "swmm_userflag_get_real",
+    "swmm_userflag_value_get"
+   ]
+  },
+  {
+   "target": "userflags",
+   "form": "item",
+   "python": "UserFlags[]",
+   "doc": "Typed user-flag mapping. See Solver.userflags.",
+   "path": "userflags.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "Union[bool, int, float, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_userflag_define",
+    "swmm_userflag_set_bool",
+    "swmm_userflag_set_int",
+    "swmm_userflag_set_real",
+    "swmm_userflag_value_set"
+   ]
+  },
+  {
+   "path": "userflags.set_value",
+   "target": "userflags",
+   "name": "set_value",
+   "form": "method",
+   "python": "UserFlags.set_value",
+   "doc": "Assign a flag value to a specific object from a string.",
+   "c": [
+    "swmm_userflag_value_set"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "obj_type",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "obj_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "flag_name",
+     "type": "str",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "userflags.undefine",
+   "target": "userflags",
+   "name": "undefine",
+   "form": "method",
+   "python": "UserFlags.undefine",
+   "doc": "Remove a flag definition and all its per-object values.",
+   "c": [
+    "swmm_userflag_undefine"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "name",
+     "type": "str",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "water_age.enabled",
+   "target": "water_age",
+   "name": "enabled",
+   "form": "property",
+   "python": "WaterAge.enabled",
+   "doc": "Is [OPTIONS] WATER_AGE on? Read-only.",
+   "c": [
+    "swmm_water_age_get_enabled"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "target": "water_age.globals",
+   "form": "item",
+   "python": "_WaterAgeGlobals[]",
+   "doc": "",
+   "path": "water_age.globals.get_item",
+   "name": "get_item",
+   "returns": "float",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_water_age_get_global_source"
+   ]
+  },
+  {
+   "target": "water_age.globals",
+   "form": "item",
+   "python": "_WaterAgeGlobals[]",
+   "doc": "",
+   "path": "water_age.globals.items",
+   "name": "items",
+   "returns": "list[tuple[Union[WaterAgeSource, int, str], float]]",
+   "params": [],
+   "c": [
+    "swmm_water_age_get_global_source"
+   ]
+  },
+  {
+   "target": "water_age.globals",
+   "form": "item",
+   "python": "_WaterAgeGlobals[]",
+   "doc": "",
+   "path": "water_age.globals.set_item",
+   "name": "set_item",
+   "returns": "None",
+   "params": [
+    {
+     "name": "key",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "value",
+     "type": "float",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_water_age_set_global_source"
+   ]
+  },
+  {
+   "target": "water_age.node_overrides",
+   "form": "item",
+   "python": "_WaterAgeOverrides[]",
+   "doc": "",
+   "path": "water_age.node_overrides.get_item",
+   "name": "get_item",
+   "returns": "WaterAgeOverride",
+   "params": [
+    {
+     "name": "key",
+     "type": "int",
+     "required": true
+    }
+   ],
+   "c": [
+    "swmm_water_age_get_override"
+   ]
+  },
+  {
+   "target": "water_age.node_overrides",
+   "form": "item",
+   "python": "_WaterAgeOverrides[]",
+   "doc": "",
+   "path": "water_age.node_overrides.items",
+   "name": "items",
+   "returns": "list[tuple[int, WaterAgeOverride]]",
+   "params": [],
+   "c": [
+    "swmm_water_age_get_override",
+    "swmm_water_age_override_count"
+   ]
+  },
+  {
+   "path": "water_age.node_overrides.remove",
+   "target": "water_age.node_overrides",
+   "name": "remove",
+   "form": "method",
+   "python": "_WaterAgeOverrides.remove",
+   "doc": "Remove the NODE override for (source, node).",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_water_age_remove_override"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "water_age.node_overrides.set",
+   "target": "water_age.node_overrides",
+   "name": "set",
+   "form": "method",
+   "python": "_WaterAgeOverrides.set",
+   "doc": "Add or update the NODE override for (source, node).",
+   "c": [
+    "swmm_node_count",
+    "swmm_node_index",
+    "swmm_water_age_set_override"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "source",
+     "type": "Union[WaterAgeSource, int, str]",
+     "required": true
+    },
+    {
+     "name": "node",
+     "type": "Union[int, str]",
+     "required": true
+    },
+    {
+     "name": "hours",
+     "type": "float",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "water_age.save",
+   "target": "water_age",
+   "name": "save",
+   "form": "method",
+   "python": "WaterAge.save",
+   "doc": "Write the current table as a [WATER_AGE_SOURCES] component file.",
+   "c": [
+    "swmm_water_age_save"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "write",
+   "target": "solver",
+   "name": "write",
+   "form": "method",
+   "python": "Solver.write",
+   "doc": "Write the current model to a SWMM .inp file.",
+   "c": [
+    "swmm_model_write"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "write_compat",
+   "target": "solver",
+   "name": "write_compat",
+   "form": "method",
+   "python": "Solver.write_compat",
+   "doc": "Write FULL, OpenSWMM legacy, or stock EPA SWMM 5 input.",
+   "c": [
+    "swmm_model_write_compat"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    },
+    {
+     "name": "profile",
+     "type": "InpProfile",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "write_geopackage",
+   "target": "solver",
+   "name": "write_geopackage",
+   "form": "method",
+   "python": "Solver.write_geopackage",
+   "doc": "Write the model to an OGC GeoPackage (.gpkg).",
+   "c": [],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    },
+    {
+     "name": "crs",
+     "type": "Optional[str]",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "write_staged",
+   "target": "solver",
+   "name": "write_staged",
+   "form": "method",
+   "python": "Solver.write_staged",
+   "doc": "Serialize each physical output to mapper(final_path, kind).",
+   "c": [
+    "swmm_model_write_staged"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "final_path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    },
+    {
+     "name": "mapper",
+     "type": "Callable[[str, int], Union[str, PathLike[str]] | None]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "write_with_plugin",
+   "target": "solver",
+   "name": "write_with_plugin",
+   "form": "method",
+   "python": "Solver.write_with_plugin",
+   "doc": "Write the current model using an output plugin.",
+   "c": [
+    "swmm_model_write_with_plugin"
+   ],
+   "returns": "None",
+   "params": [
+    {
+     "name": "path",
+     "type": "Union[str, PathLike[str]]",
+     "required": true
+    },
+    {
+     "name": "output_plugin_id",
+     "type": "str",
+     "required": false
+    }
+   ]
+  },
+  {
+   "path": "xsect.area",
+   "target": "xsect",
+   "name": "area",
+   "form": "method",
+   "python": "XSectionGeometry.area",
+   "doc": "Flow area at *depth*. @param depth: float or ndarray.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "depth",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.area_from_section_factor",
+   "target": "xsect",
+   "name": "area_from_section_factor",
+   "form": "method",
+   "python": "XSectionGeometry.area_from_section_factor",
+   "doc": "Flow area for section factor *sf* — used to solve for normal depth.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "sf",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.critical_depth",
+   "target": "xsect",
+   "name": "critical_depth",
+   "form": "method",
+   "python": "XSectionGeometry.critical_depth",
+   "doc": "Critical depth for *flow*, in flow_units.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "flow",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.depth_from_area",
+   "target": "xsect",
+   "name": "depth_from_area",
+   "form": "method",
+   "python": "XSectionGeometry.depth_from_area",
+   "doc": "Depth of flow for *area* — the inverse of area.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "area",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.dsda",
+   "target": "xsect",
+   "name": "dsda",
+   "form": "method",
+   "python": "XSectionGeometry.dsda",
+   "doc": "Derivative of the section factor with respect to area, dS/dA.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "area",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.flow_units",
+   "target": "xsect",
+   "name": "flow_units",
+   "form": "property",
+   "python": "XSectionGeometry.flow_units",
+   "doc": "Flow units for critical_depth ('CFS', 'CMS', …).",
+   "c": [
+    "swmm_xsect_get_units"
+   ],
+   "type": "str",
+   "access": "r"
+  },
+  {
+   "path": "xsect.from_curve",
+   "target": "xsect",
+   "name": "from_curve",
+   "form": "method",
+   "python": "XSectionGeometry.from_curve",
+   "doc": "Build a custom section from a normalized shape curve.",
+   "c": [
+    "swmm_xsect_create_custom",
+    "swmm_xsect_get_shape"
+   ],
+   "returns": "XSectionGeometry",
+   "params": [
+    {
+     "name": "full_depth",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "curve_depths",
+     "type": "Union[float, Sequence[float], _Array]",
+     "required": true
+    },
+    {
+     "name": "curve_widths",
+     "type": "Union[float, Sequence[float], _Array]",
+     "required": true
+    },
+    {
+     "name": "units",
+     "type": "Literal['US', 'SI']",
+     "required": true,
+     "keyword_only": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "xsect.from_link",
+   "target": "xsect",
+   "name": "from_link",
+   "form": "method",
+   "python": "XSectionGeometry.from_link",
+   "doc": "Build a section from a Link of an open model.",
+   "c": [
+    "swmm_link_create_xsect",
+    "swmm_xsect_get_shape"
+   ],
+   "returns": "XSectionGeometry",
+   "params": [
+    {
+     "name": "link",
+     "type": "Any",
+     "required": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "xsect.from_street",
+   "target": "xsect",
+   "name": "from_street",
+   "form": "method",
+   "python": "XSectionGeometry.from_street",
+   "doc": "Build a street section. Mirrors a [STREETS] entry.",
+   "c": [
+    "swmm_xsect_create_street",
+    "swmm_xsect_get_shape"
+   ],
+   "returns": "XSectionGeometry",
+   "params": [
+    {
+     "name": "width",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "curb_height",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "slope",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "roughness",
+     "type": "float",
+     "required": true
+    },
+    {
+     "name": "gutter_depression",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "gutter_width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "sides",
+     "type": "int",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_width",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_slope",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "back_roughness",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "units",
+     "type": "Literal['US', 'SI']",
+     "required": true,
+     "keyword_only": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "xsect.from_transect",
+   "target": "xsect",
+   "name": "from_transect",
+   "form": "method",
+   "python": "XSectionGeometry.from_transect",
+   "doc": "Build an irregular (natural channel) section from transect data.",
+   "c": [
+    "swmm_xsect_create_irregular",
+    "swmm_xsect_get_shape"
+   ],
+   "returns": "XSectionGeometry",
+   "params": [
+    {
+     "name": "stations",
+     "type": "Union[float, Sequence[float], _Array]",
+     "required": true
+    },
+    {
+     "name": "elevations",
+     "type": "Union[float, Sequence[float], _Array]",
+     "required": true
+    },
+    {
+     "name": "left_bank",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "right_bank",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "n_channel",
+     "type": "float",
+     "required": true,
+     "keyword_only": true
+    },
+    {
+     "name": "n_left",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "n_right",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "length_factor",
+     "type": "float",
+     "required": false,
+     "keyword_only": true
+    },
+    {
+     "name": "units",
+     "type": "Literal['US', 'SI']",
+     "required": true,
+     "keyword_only": true
+    }
+   ],
+   "static": true
+  },
+  {
+   "path": "xsect.full_area",
+   "target": "xsect",
+   "name": "full_area",
+   "form": "property",
+   "python": "XSectionGeometry.full_area",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "area"
+  },
+  {
+   "path": "xsect.full_depth",
+   "target": "xsect",
+   "name": "full_depth",
+   "form": "property",
+   "python": "XSectionGeometry.full_depth",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "xsect.full_hyd_radius",
+   "target": "xsect",
+   "name": "full_hyd_radius",
+   "form": "property",
+   "python": "XSectionGeometry.full_hyd_radius",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "xsect.full_section_factor",
+   "target": "xsect",
+   "name": "full_section_factor",
+   "form": "property",
+   "python": "XSectionGeometry.full_section_factor",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "section_factor"
+  },
+  {
+   "path": "xsect.hyd_radius",
+   "target": "xsect",
+   "name": "hyd_radius",
+   "form": "method",
+   "python": "XSectionGeometry.hyd_radius",
+   "doc": "Hydraulic radius (area / wetted perimeter) at *depth*.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "depth",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.hyd_radius_from_area",
+   "target": "xsect",
+   "name": "hyd_radius_from_area",
+   "form": "method",
+   "python": "XSectionGeometry.hyd_radius_from_area",
+   "doc": "Hydraulic radius for *area*.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "area",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.is_open",
+   "target": "xsect",
+   "name": "is_open",
+   "form": "property",
+   "python": "XSectionGeometry.is_open",
+   "doc": "Whether the cross-section is open to the atmosphere at its top.",
+   "c": [
+    "swmm_xsect_is_open"
+   ],
+   "type": "bool",
+   "access": "r"
+  },
+  {
+   "path": "xsect.max_area",
+   "target": "xsect",
+   "name": "max_area",
+   "form": "property",
+   "python": "XSectionGeometry.max_area",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "area"
+  },
+  {
+   "path": "xsect.max_width",
+   "target": "xsect",
+   "name": "max_width",
+   "form": "property",
+   "python": "XSectionGeometry.max_width",
+   "doc": "Full-depth (bank-full) properties of the cross-section.",
+   "c": [
+    "swmm_xsect_full_properties"
+   ],
+   "type": "float",
+   "access": "r",
+   "units": "length"
+  },
+  {
+   "path": "xsect.section_factor",
+   "target": "xsect",
+   "name": "section_factor",
+   "form": "method",
+   "python": "XSectionGeometry.section_factor",
+   "doc": "Section factor (A·R^(2/3)) for *area*.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "area",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  },
+  {
+   "path": "xsect.shape",
+   "target": "xsect",
+   "name": "shape",
+   "form": "property",
+   "python": "XSectionGeometry.shape",
+   "doc": "",
+   "c": [],
+   "type": "XSectShape",
+   "access": "r"
+  },
+  {
+   "path": "xsect.units",
+   "target": "xsect",
+   "name": "units",
+   "form": "property",
+   "python": "XSectionGeometry.units",
+   "doc": "'US' or 'SI' — the unit system of every value here.",
+   "c": [
+    "swmm_xsect_get_units"
+   ],
+   "type": "Literal['US', 'SI']",
+   "access": "r"
+  },
+  {
+   "path": "xsect.width",
+   "target": "xsect",
+   "name": "width",
+   "form": "method",
+   "python": "XSectionGeometry.width",
+   "doc": "Top width of the water surface at *depth*.",
+   "c": [
+    "swmm_xsect_area_of_depth",
+    "swmm_xsect_area_of_depth_array",
+    "swmm_xsect_area_of_sectfactor",
+    "swmm_xsect_area_of_sectfactor_array",
+    "swmm_xsect_critical_depth",
+    "swmm_xsect_critical_depth_array",
+    "swmm_xsect_depth_of_area",
+    "swmm_xsect_depth_of_area_array",
+    "swmm_xsect_dsda",
+    "swmm_xsect_dsda_array",
+    "swmm_xsect_hydrad_of_area",
+    "swmm_xsect_hydrad_of_area_array",
+    "swmm_xsect_hydrad_of_depth",
+    "swmm_xsect_hydrad_of_depth_array",
+    "swmm_xsect_sectfactor_of_area",
+    "swmm_xsect_sectfactor_of_area_array",
+    "swmm_xsect_width_of_depth",
+    "swmm_xsect_width_of_depth_array"
+   ],
+   "returns": "NDArray[np.float64]",
+   "params": [
+    {
+     "name": "depth",
+     "type": "Sequence[float] | NDArray[np.float64]",
+     "required": true
+    }
+   ]
+  }
+ ],
+ "functions": {
+  "_dates": {
+   "datetime_to_oadate": {
+    "name": "datetime_to_oadate",
+    "form": "method",
+    "type": "float",
+    "params": [
+     {
+      "name": "dt",
+      "type": "datetime",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": []
+   },
+   "oadate_to_datetime": {
+    "name": "oadate_to_datetime",
+    "form": "method",
+    "type": "datetime",
+    "params": [
+     {
+      "name": "value",
+      "type": "float",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": []
+   }
+  },
+  "_datetime": {
+   "add_seconds": {
+    "name": "add_seconds",
+    "form": "method",
+    "type": "float",
+    "params": [
+     {
+      "name": "value",
+      "type": "float",
+      "required": true
+     },
+     {
+      "name": "seconds",
+      "type": "float",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_add_seconds"
+    ]
+   },
+   "decode_date": {
+    "name": "decode_date",
+    "form": "method",
+    "type": "tuple[int, int, int]",
+    "params": [
+     {
+      "name": "value",
+      "type": "float",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_decode_date"
+    ]
+   },
+   "decode_time": {
+    "name": "decode_time",
+    "form": "method",
+    "type": "tuple[int, int, int]",
+    "params": [
+     {
+      "name": "value",
+      "type": "float",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_decode_time"
+    ]
+   },
+   "encode_date": {
+    "name": "encode_date",
+    "form": "method",
+    "type": "float",
+    "params": [
+     {
+      "name": "year",
+      "type": "int",
+      "required": true
+     },
+     {
+      "name": "month",
+      "type": "int",
+      "required": true
+     },
+     {
+      "name": "day",
+      "type": "int",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_encode_date"
+    ]
+   },
+   "encode_time": {
+    "name": "encode_time",
+    "form": "method",
+    "type": "float",
+    "params": [
+     {
+      "name": "hour",
+      "type": "int",
+      "required": true
+     },
+     {
+      "name": "minute",
+      "type": "int",
+      "required": true
+     },
+     {
+      "name": "second",
+      "type": "int",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_encode_time"
+    ]
+   },
+   "time_diff": {
+    "name": "time_diff",
+    "form": "method",
+    "type": "int",
+    "params": [
+     {
+      "name": "value1",
+      "type": "float",
+      "required": true
+     },
+     {
+      "name": "value2",
+      "type": "float",
+      "required": true
+     }
+    ],
+    "doc": "",
+    "stub_setter": false,
+    "static": false,
+    "c": [
+     "swmm_datetime_time_diff"
+    ]
+   }
+  }
+ },
+ "records": {
+  "AquiferNode": {
+   "fields": {
+    "node": "str",
+    "cell": "int",
+    "kc": "float",
+    "dc": "float",
+    "area": "float",
+    "locate": "bool",
+    "exchange": "bool",
+    "automatic": "bool"
+   },
+   "doc": ""
+  },
+  "AquiferRow": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "ks": "float",
+    "zs": "float",
+    "theta_s": "float",
+    "theta_r": "float",
+    "alpha": "float"
+   },
+   "doc": ""
+  },
+  "ConduitDispersion": {
+   "fields": {
+    "link_index": "int",
+    "value": "float"
+   },
+   "doc": ""
+  },
+  "ControlRule": {
+   "fields": {
+    "id": "str",
+    "text": "str"
+   },
+   "doc": ""
+  },
+  "ConversionResult": {
+   "fields": {
+    "new_type": "int",
+    "cleared_fields": "list[str]",
+    "warnings": "list[str]"
+   },
+   "doc": "Result of an in-place node or link type conversion."
+  },
+  "EffectiveThreads": {
+   "fields": {
+    "global_threads": "int",
+    "dynamic_wave": "int",
+    "surface2d": "int"
+   },
+   "doc": ""
+  },
+  "Event": {
+   "fields": {
+    "start": "datetime",
+    "end": "datetime"
+   },
+   "doc": ""
+  },
+  "ExpressionDiagnostic": {
+   "fields": {
+    "valid": "bool",
+    "message": "str",
+    "column": "int"
+   },
+   "doc": ""
+  },
+  "GroundwaterBoundary": {
+   "fields": {
+    "cell": "int",
+    "edge": "int",
+    "species": "str",
+    "kind": "str",
+    "value": "float",
+    "timeseries": "str"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "GroundwaterInitialQuality": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "zone": "GroundwaterTransportZone",
+    "layer": "int",
+    "species": "str",
+    "value": "float"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "GroundwaterParameters": {
+   "fields": {
+    "scope": "CellScope",
+    "cell": "int",
+    "rho_s": "float",
+    "c_s": "float",
+    "lambda_s": "float",
+    "a_s": "float",
+    "alpha_L": "float",
+    "alpha_T": "float",
+    "D_m": "float",
+    "D_v": "float",
+    "geo_flux": "float",
+    "tag": "str"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "GroundwaterParams": {
+   "fields": {
+    "surf_elev": "float",
+    "a1": "float",
+    "b1": "float",
+    "a2": "float",
+    "b2": "float",
+    "a3": "float",
+    "tw": "float",
+    "hstar": "float"
+   },
+   "doc": ""
+  },
+  "GroundwaterSorption": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "species": "str",
+    "kd": "float",
+    "decay": "float"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "GroundwaterSource": {
+   "fields": {
+    "name": "str",
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "flow": "float",
+    "flow_timeseries": "str"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "GroundwaterSourceTerm": {
+   "fields": {
+    "species": "str",
+    "kind": "str",
+    "value": "float",
+    "timeseries": "str"
+   },
+   "doc": "Immutable authored row; replace fields and submit it with the matching setter."
+  },
+  "HeatNodeOverride": {
+   "fields": {
+    "source": "HeatSourceKind",
+    "node_index": "int",
+    "temp_c": "float"
+   },
+   "doc": ""
+  },
+  "HydrographEntry": {
+   "fields": {
+    "uh_name": "str",
+    "month": "int",
+    "response": "int",
+    "r": "float",
+    "t": "float",
+    "k": "float",
+    "dmax": "float",
+    "drecov": "float",
+    "dinit": "float"
+   },
+   "doc": ""
+  },
+  "HydrographGageEntry": {
+   "fields": {
+    "uh_name": "str",
+    "gage_name": "str"
+   },
+   "doc": ""
+  },
+  "ImpactEntry": {
+   "fields": {
+    "obj_type": "int",
+    "obj_type_name": "str",
+    "obj_idx": "int",
+    "field": "str",
+    "cascaded": "bool"
+   },
+   "doc": "One cross-reference that would be affected by a deletion."
+  },
+  "Infil2DCell": {
+   "fields": {
+    "row": "Infil2DRow",
+    "is_override": "bool"
+   },
+   "doc": "The infiltration specification in force at one cell."
+  },
+  "Infil2DRow": {
+   "fields": {
+    "method": "SurfaceInfilMethod | None",
+    "params": "tuple[float, ...]",
+    "dest": "SurfaceInfilDest"
+   },
+   "doc": "One infiltration specification."
+  },
+  "InitialQualityEntry": {
+   "fields": {
+    "is_link": "bool",
+    "elem_index": "int",
+    "constituent": "str",
+    "value": "float"
+   },
+   "doc": ""
+  },
+  "KnownProcessComponent": {
+   "fields": {
+    "id": "str",
+    "description": "str",
+    "implemented": "bool"
+   },
+   "doc": ""
+  },
+  "ProcessComponent": {
+   "fields": {
+    "component_index": "int",
+    "id": "str",
+    "config": "str",
+    "resolved": "str"
+   },
+   "doc": ""
+  },
+  "RDIIDecayEntry": {
+   "fields": {
+    "uh_name": "str",
+    "response": "int",
+    "k_dep": "float",
+    "k_0": "float",
+    "k_T": "float",
+    "T_ref": "float",
+    "theta_rec": "float",
+    "T_freeze": "float",
+    "snow_on": "bool",
+    "snow_T": "float",
+    "snow_ddf": "float"
+   },
+   "doc": ""
+  },
+  "RDIIEntry": {
+   "fields": {
+    "node_index": "int",
+    "uh_name": "str",
+    "area": "float"
+   },
+   "doc": ""
+  },
+  "ReactionFunction": {
+   "fields": {
+    "name": "str",
+    "arity": "int"
+   },
+   "doc": ""
+  },
+  "ReactionHydVar": {
+   "fields": {
+    "name": "str",
+    "description": "str"
+   },
+   "doc": ""
+  },
+  "ReactionInitialEntry": {
+   "fields": {
+    "is_link": "bool",
+    "elem_index": "int",
+    "species_index": "int",
+    "value": "float"
+   },
+   "doc": ""
+  },
+  "SaveScheduleEntry": {
+   "fields": {
+    "when": "datetime",
+    "path": "str"
+   },
+   "doc": ""
+  },
+  "SurfaceCoverage": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "landuses": "tuple[tuple[str, float], ...]"
+   },
+   "doc": "A whole land-use coverage set at one scope; pairs carry percentages."
+  },
+  "SurfaceCurbLength": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "length": "float"
+   },
+   "doc": "Authored curb length in project length units."
+  },
+  "SurfaceLoading": {
+   "fields": {
+    "scope": "CellScope",
+    "tag": "str",
+    "cell": "int",
+    "species": "str",
+    "value": "float"
+   },
+   "doc": "Initial species buildup in project mass per acre/hectare."
+  },
+  "ThreadInfo": {
+   "fields": {
+    "logical_cpus": "int",
+    "omp_max_threads": "int",
+    "omp_available": "bool",
+    "perf_cores": "int",
+    "kokkos_omp_threads": "int"
+   },
+   "doc": ""
+  },
+  "TransportCell": {
+   "fields": {
+    "state": "TransportState",
+    "count": "int",
+    "reason": "str"
+   },
+   "doc": ""
+  },
+  "TransportRow": {
+   "fields": {
+    "element": "str",
+    "species": "str",
+    "is_timeseries": "bool",
+    "value": "float",
+    "timeseries": "str"
+   },
+   "doc": ""
+  },
+  "UserFlagDef": {
+   "fields": {
+    "name": "str",
+    "type": "int",
+    "description": "str"
+   },
+   "doc": "A [USER_FLAGS] schema definition: (name, type, description)."
+  },
+  "WaterAgeOverride": {
+   "fields": {
+    "source": "WaterAgeSource",
+    "node_index": "int",
+    "hours": "float"
+   },
+   "doc": ""
+  }
+ },
+ "enums": {
+  "AquiferParam": {
+   "POROSITY": 0,
+   "WILTING_POINT": 1,
+   "FIELD_CAPACITY": 2,
+   "CONDUCTIVITY": 3,
+   "CONDUCT_SLOPE": 4,
+   "TENSION_SLOPE": 5,
+   "UPPER_EVAP_FRAC": 6,
+   "LOWER_EVAP_DEPTH": 7,
+   "LOWER_LOSS_COEFF": 8,
+   "BOTTOM_ELEV": 9,
+   "WATER_TABLE_ELEV": 10,
+   "UPPER_MOISTURE": 11
+  },
+  "BuildupFunc": {
+   "NONE": 0,
+   "POW": 1,
+   "EXP": 2,
+   "SAT": 3,
+   "EXT": 4
+  },
+  "CellScope": {
+   "GLOBAL": 0,
+   "TAG": 1,
+   "CELL": 2
+  },
+  "ConcentrationUnits": {
+   "MG_PER_L": 0,
+   "UG_PER_L": 1,
+   "COUNT_PER_L": 2
+  },
+  "DividerType": {
+   "CUTOFF": 0,
+   "OVERFLOW": 1,
+   "TABULAR": 2,
+   "WEIR": 3
+  },
+  "EngineState": {
+   "NONE": 0,
+   "CREATED": 1,
+   "OPENED": 2,
+   "INITIALIZED": 3,
+   "STARTED": 4,
+   "RUNNING": 5,
+   "ENDED": 6,
+   "CLOSED": 7,
+   "BUILDING": 8
+  },
+  "ErrorCode": {
+   "OK": 0,
+   "NOMEM": 1,
+   "INPFILE": 2,
+   "RPTFILE": 3,
+   "OUTFILE": 4,
+   "PARSE": 5,
+   "LIFECYCLE": 6,
+   "BADHANDLE": 7,
+   "BADINDEX": 8,
+   "BADPARAM": 9,
+   "PLUGIN": 10,
+   "IO": 11,
+   "HOTSTART": 12,
+   "CRS": 13,
+   "NUMERICAL": 14,
+   "DEPENDENCY": 15,
+   "INTERNAL": 99
+  },
+  "EvapType": {
+   "CONSTANT": 0,
+   "MONTHLY": 1,
+   "TIMESERIES": 2,
+   "TEMPERATURE": 3,
+   "FILE": 4
+  },
+  "FilePathRole": {
+   "RAINFALL": 1,
+   "RUNOFF": 2,
+   "RDII": 3,
+   "INFLOWS": 4,
+   "OUTFLOWS": 5,
+   "HOTSTART_USE": 6,
+   "CLIMATE_TEMP": 7,
+   "HOTSTART_SAVE": 8,
+   "RAINGAGE_DATA": 9,
+   "TIMESERIES_DATA": 10,
+   "MESH_2D": 11,
+   "OUTPUT_2D": 12,
+   "LID_REPORT": 13
+  },
+  "FlowUnits": {
+   "CFS": 0,
+   "GPM": 1,
+   "MGD": 2,
+   "CMS": 3,
+   "LPS": 4,
+   "MLD": 5
+  },
+  "ForcingMode": {
+   "REPLACE": 1,
+   "ADD": 2
+  },
+  "ForcingPersist": {
+   "RESET": 0,
+   "PERSIST": 1
+  },
+  "ForcingTarget": {
+   "NODE": 0,
+   "LINK": 1,
+   "SUBCATCH": 2,
+   "GAGE": 3,
+   "CLIMATE": 4
+  },
+  "ForcingType": {
+   "NODE_LAT_INFLOW": 0,
+   "NODE_HEAD_BOUNDARY": 1,
+   "NODE_QUALITY": 2,
+   "LINK_FLOW": 3,
+   "LINK_SETTING": 4,
+   "SUBCATCH_RAINFALL": 5,
+   "SUBCATCH_EVAP": 6,
+   "GAGE_RAINFALL": 7,
+   "CLIMATE_TEMPERATURE": 8,
+   "CLIMATE_WIND": 9,
+   "SUBCATCH_SNOWFALL": 10,
+   "CLIMATE_EVAP": 11,
+   "LINK_QUALITY": 12,
+   "ELEM_AIR_TEMPERATURE": 13,
+   "ELEM_HUMIDITY": 14,
+   "ELEM_WIND_SPEED": 15,
+   "ELEM_SHORTWAVE": 16,
+   "LINK_SEEPAGE": 17
+  },
+  "GageDataSource": {
+   "TIMESERIES": 0,
+   "FILE": 1
+  },
+  "GageRainType": {
+   "INTENSITY": 0,
+   "VOLUME": 1,
+   "CUMULATIVE": 2
+  },
+  "GrateType": {
+   "P_BAR_50": 0,
+   "P_BAR_50x100": 1,
+   "P_BAR_30": 2,
+   "CURVED_VANE": 3,
+   "TILT_BAR_45": 4,
+   "TILT_BAR_30": 5,
+   "RETICULINE": 6,
+   "GENERIC": 7
+  },
+  "GroundwaterClosure": {
+   "AUTO": -1,
+   "CLOSED_FORM": 0,
+   "ENSLAVED": 1,
+   "SIGMA": 2
+  },
+  "GroundwaterLedger": {
+   "RECHARGE": 0,
+   "LATERAL": 1,
+   "DEEP": 2,
+   "NODE": 3,
+   "DUNNE": 4,
+   "CAPRISE": 5,
+   "ET": 6,
+   "INFIL_IN": 7,
+   "INIT_STORAGE": 8,
+   "STORAGE": 9,
+   "LINK": 10
+  },
+  "GroundwaterSoil": {
+   "RUSSO": 0,
+   "GARDNER": 1,
+   "BROOKS_COREY": 2,
+   "VAN_GENUCHTEN": 3
+  },
+  "GroundwaterSpeciesLedger": {
+   "INIT": 0,
+   "STORAGE": 1,
+   "INFIL_IN": 2,
+   "NODE_IN": 3,
+   "LINK_IN": 4,
+   "LATERAL_NET": 5,
+   "DEEP_OUT": 6,
+   "NODE_OUT": 7,
+   "LINK_OUT": 8,
+   "DUNNE_OUT": 9,
+   "ET_OUT": 10,
+   "REACTED": 11,
+   "RESIDUAL": 12
+  },
+  "GroundwaterTransportZone": {
+   "SAT": 0,
+   "UNSAT": 1,
+   "LAYER": 2
+  },
+  "GroundwaterVariable": {
+   "HG": 0,
+   "HU": 1,
+   "TABLE_EL": 2,
+   "Q0": 3,
+   "QLAT": 4,
+   "QNODE": 5,
+   "QDEEP": 6,
+   "QET": 7,
+   "DUNNE": 8,
+   "QPLUS": 9,
+   "DT_CELL": 10,
+   "TIER": 11,
+   "CLOSURE": 12,
+   "QLINK": 13
+  },
+  "GroundwaterZone": {
+   "SAT": 0,
+   "UNSAT": 1
+  },
+  "GwfType": {
+   "LATERAL": 0,
+   "DEEP": 1
+  },
+  "HeatCloudParam": {
+   "FRACTION": 0,
+   "SW_ATTEN_K": 1,
+   "SW_ATTEN_N": 2,
+   "LW_CLOUD_K": 3
+  },
+  "HeatElemKind": {
+   "NODE": 0,
+   "LINK": 1
+  },
+  "HeatFluxModule": {
+   "SURFACE_EXCHANGE": 0,
+   "RADIATIVE_EXCHANGE": 1,
+   "LAYER_CONDUCTION": 2
+  },
+  "HeatRadiativeParam": {
+   "SHORTWAVE": 0,
+   "ALBEDO": 1,
+   "SHADE_FACTOR": 2,
+   "SKY_VIEW": 3,
+   "EMISS_WATER": 4,
+   "EMISS_LANDCOVER": 5,
+   "ATM_EMISS_COEFF": 6,
+   "LW_REFLECTION": 7
+  },
+  "HeatShortwaveMode": {
+   "CONSTANT": 0,
+   "TIMESERIES": 1,
+   "COMPUTED": 2
+  },
+  "HeatSolarParam": {
+   "LATITUDE": 0,
+   "LONGITUDE": 1,
+   "TIMEZONE": 2,
+   "ELEVATION": 3,
+   "TURBIDITY_380": 4,
+   "TURBIDITY_500": 5,
+   "PRECIP_WATER": 6,
+   "OZONE": 7,
+   "GROUND_ALBEDO": 8
+  },
+  "HeatSourceKind": {
+   "RAINFALL": 0,
+   "DWF": 1,
+   "GW": 2,
+   "RDII": 3,
+   "EXTERNAL_INFLOW": 4,
+   "IFACE": 5,
+   "INITIAL_STATE": 6
+  },
+  "HumidityType": {
+   "CONSTANT": 0,
+   "MONTHLY": 1,
+   "TIMESERIES": 2
+  },
+  "HumidityVar": {
+   "RELATIVE": 0,
+   "DEWPOINT": 1
+  },
+  "InfilModel": {
+   "HORTON": 0,
+   "MOD_HORTON": 1,
+   "GREEN_AMPT": 2,
+   "MOD_GREEN_AMPT": 3,
+   "CURVE_NUMBER": 4
+  },
+  "InletCurveKind": {
+   "NONE": 0,
+   "DIVERSION": 1,
+   "RATING": 2
+  },
+  "InletHostKind": {
+   "LINK": 0,
+   "NODE": 1
+  },
+  "InletPlacement": {
+   "AUTOMATIC": 0,
+   "ON_GRADE": 1,
+   "ON_SAG": 2
+  },
+  "InletType": {
+   "GRATE": 0,
+   "CURB": 1,
+   "COMBO": 2,
+   "SLOTTED": 3,
+   "DROP_GRATE": 4,
+   "DROP_CURB": 5,
+   "CUSTOM": 6
+  },
+  "InpProfile": {
+   "FULL": 0,
+   "SWMM5": 1,
+   "SWMM5_STOCK": 2
+  },
+  "LidType": {
+   "BIO_CELL": 0,
+   "RAIN_GARDEN": 1,
+   "GREEN_ROOF": 2,
+   "INFIL_TRENCH": 3,
+   "PERM_PAVEMENT": 4,
+   "RAIN_BARREL": 5,
+   "ROOFTOP_DISCONN": 6,
+   "VEGETATIVE_SWALE": 7
+  },
+  "LinkType": {
+   "CONDUIT": 0,
+   "PUMP": 1,
+   "ORIFICE": 2,
+   "WEIR": 3,
+   "OUTLET": 4
+  },
+  "NodeType": {
+   "JUNCTION": 0,
+   "OUTFALL": 1,
+   "STORAGE": 2,
+   "DIVIDER": 3
+  },
+  "ObjectType": {
+   "GAGE": 0,
+   "SUBCATCH": 1,
+   "NODE": 2,
+   "LINK": 3,
+   "POLLUT": 4,
+   "LANDUSE": 5,
+   "TIMESER": 6,
+   "TABLE": 7,
+   "RDII": 8,
+   "UNITHYD": 9,
+   "SNOWMELT": 10,
+   "SHAPE": 11,
+   "LID": 12
+  },
+  "OrificeType": {
+   "SIDE": 0,
+   "BOTTOM": 1
+  },
+  "OutLinkVar": {
+   "FLOW": 0,
+   "DEPTH": 1,
+   "VELOCITY": 2,
+   "VOLUME": 3,
+   "CAPACITY": 4,
+   "POLLUT_BASE": 5
+  },
+  "OutNodeVar": {
+   "DEPTH": 0,
+   "HEAD": 1,
+   "VOLUME": 2,
+   "LATERAL_INFLOW": 3,
+   "TOTAL_INFLOW": 4,
+   "OVERFLOW": 5,
+   "POLLUT_BASE": 6
+  },
+  "OutSubcatchVar": {
+   "RAINFALL": 0,
+   "SNOW_DEPTH": 1,
+   "EVAP": 2,
+   "INFIL": 3,
+   "RUNOFF": 4,
+   "GW_FLOW": 5,
+   "GW_ELEV": 6,
+   "SOIL_MOIST": 7,
+   "POLLUT_BASE": 8
+  },
+  "OutSystemVar": {
+   "TEMPERATURE": 0,
+   "RAINFALL": 1,
+   "SNOW_DEPTH": 2,
+   "EVAP": 3,
+   "INFIL": 4,
+   "RUNOFF": 5,
+   "DW_INFLOW": 6,
+   "GW_INFLOW": 7,
+   "LAT_INFLOW": 8,
+   "FLOODING": 9,
+   "OUTFLOW": 10,
+   "STORAGE": 11,
+   "EVAP_TOTAL": 12,
+   "PET": 13
+  },
+  "OutfallType": {
+   "FREE": 0,
+   "NORMAL": 1,
+   "FIXED": 2,
+   "TIDAL": 3,
+   "TIMESERIES": 4
+  },
+  "OutletRatingType": {
+   "FUNCTIONAL_HEAD": 0,
+   "FUNCTIONAL_DEPTH": 1,
+   "TABULAR_HEAD": 2,
+   "TABULAR_DEPTH": 3
+  },
+  "PatternType": {
+   "MONTHLY": 0,
+   "DAILY": 1,
+   "HOURLY": 2,
+   "WEEKEND": 3
+  },
+  "ReactionExprForm": {
+   "NONE": 0,
+   "RATE": 1,
+   "EQUIL": 2,
+   "FORMULA": 3
+  },
+  "ReactionScope": {
+   "TERM": 0,
+   "PIPE": 1,
+   "TANK": 2
+  },
+  "RefType": {
+   "NODE": 0,
+   "LINK": 1,
+   "SUBCATCH": 2,
+   "GAGE": 3,
+   "TABLE": 4,
+   "TRANSECT": 5,
+   "INLET_USAGE": 6,
+   "EXT_INFLOW": 7,
+   "DWF_INFLOW": 8,
+   "RDII_ASSIGN": 9,
+   "TREATMENT": 10,
+   "LID_USAGE": 11,
+   "SNOWPACK": 12,
+   "HYDROGRAPH": 13,
+   "POLLUTANT": 14,
+   "PATTERN": 15,
+   "AQUIFER": 16,
+   "LID_CONTROL": 17,
+   "STREET": 18,
+   "INLET_DESIGN": 19,
+   "LANDUSE": 20,
+   "CONTROL_RULE": 21
+  },
+  "RouteModel": {
+   "STEADY": 0,
+   "KINWAVE": 1,
+   "DYNWAVE": 2,
+   "FV": 3
+  },
+  "RoutingTotal": {
+   "DRY_WEATHER": 0,
+   "WET_WEATHER": 1,
+   "GW_INFLOW": 2,
+   "RDII": 3,
+   "EXTERNAL": 4,
+   "FLOODING": 5,
+   "OUTFLOW": 6,
+   "EVAP_LOSS": 7,
+   "SEEP_LOSS": 8,
+   "INIT_STORAGE": 9,
+   "FINAL_STORAGE": 10,
+   "FORCING_INFLOW": 11,
+   "LINK_GW_INFLOW": 13,
+   "COUPLING_OUT": 12
+  },
+  "RunoffTotal": {
+   "RAINFALL": 0,
+   "EVAP": 1,
+   "INFIL": 2,
+   "RUNOFF": 3,
+   "SNOWREMOV": 4,
+   "INITSTORE": 5,
+   "FINALSTORE": 6,
+   "INITSNOW": 7,
+   "FINALSNOW": 8
+  },
+  "StorageShape": {
+   "TABULAR": 0,
+   "FUNCTIONAL": 1,
+   "CYLINDRICAL": 2,
+   "CONICAL": 3,
+   "PARABOLOID": 4,
+   "PYRAMIDAL": 5
+  },
+  "SurfaceBoundaryType": {
+   "WALL": 0,
+   "NORMAL_FLOW": 1,
+   "SPECIFIED_STAGE": 2,
+   "SPECIFIED_FLOW": 3,
+   "RATING_CURVE": 4
+  },
+  "SurfaceForcingMode": {
+   "NONE": 0,
+   "OVERRIDE": 1,
+   "ADD": 2
+  },
+  "SurfaceInfilDest": {
+   "LOST": 0,
+   "SUBCATCH_AQUIFER": 1,
+   "AQUIFER_2D": 2
+  },
+  "SurfaceInfilMethod": {
+   "HORTON": 0,
+   "MOD_HORTON": 1,
+   "GREEN_AMPT": 2,
+   "MOD_GREEN_AMPT": 3,
+   "CURVE_NUMBER": 4,
+   "CONSTANT": 5
+  },
+  "TableType": {
+   "TIMESERIES": 0,
+   "CURVE_STORAGE": 1,
+   "CURVE_DIVERSION": 2,
+   "CURVE_RATING": 3,
+   "CURVE_SHAPE": 4,
+   "CURVE_CONTROL": 5,
+   "CURVE_TIDAL": 6,
+   "CURVE_PUMP1": 7,
+   "CURVE_PUMP2": 8,
+   "CURVE_PUMP3": 9,
+   "CURVE_PUMP4": 10,
+   "CURVE_PUMP5": 11
+  },
+  "TempSource": {
+   "NONE": 0,
+   "TIMESERIES": 1,
+   "FILE": 2
+  },
+  "ThroatType": {
+   "HORIZONTAL": 0,
+   "INCLINED": 1,
+   "VERTICAL": 2
+  },
+  "TransportClass": {
+   "POLLUTANTS": 0,
+   "MSX": 1,
+   "AGE": 2,
+   "TEMPERATURE": 3
+  },
+  "TransportDispersionMode": {
+   "OFF": 0,
+   "FISCHER": 1,
+   "VALUE": 2
+  },
+  "TransportDomain": {
+   "RUNOFF": 0,
+   "GROUNDWATER": 1,
+   "NETWORK_1D": 2,
+   "SURFACE_2D": 3
+  },
+  "TransportState": {
+   "ENABLED": 0,
+   "DISABLED_BY_USER": 1,
+   "UNAVAILABLE": 2
+  },
+  "UnitSystem": {
+   "UNITS_US": 0,
+   "UNITS_SI": 1
+  },
+  "UserFlagType": {
+   "BOOLEAN": 0,
+   "INTEGER": 1,
+   "REAL": 2,
+   "STRING": 3
+  },
+  "WarnCode": {
+   "NONE": 0,
+   "HOTSTART_MISSING": 1,
+   "UNKNOWN_SECTION": 2,
+   "UNKNOWN_OPTION": 3,
+   "DEPRECATED_KW": 4,
+   "PLUGIN_INIT": 5,
+   "NUMERICAL": 6,
+   "STABILITY_LIMIT": 7
+  },
+  "WashoffFunc": {
+   "NONE": 0,
+   "EXP": 1,
+   "RC": 2,
+   "EMC": 3
+  },
+  "WaterAgeSource": {
+   "RAINFALL": 0,
+   "DWF": 1,
+   "GW": 2,
+   "RDII": 3,
+   "EXTERNAL_INFLOW": 4,
+   "IFACE": 5,
+   "INITIAL_STATE": 6
+  },
+  "WeirType": {
+   "TRANSVERSE": 0,
+   "SIDEFLOW": 1,
+   "VNOTCH": 2,
+   "TRAPEZOIDAL": 3,
+   "ROADWAY": 4
+  },
+  "WindType": {
+   "MONTHLY": 0,
+   "FILE": 1
+  },
+  "XSectShape": {
+   "CIRCULAR": 0,
+   "FILLED_CIRCULAR": 1,
+   "RECT_CLOSED": 2,
+   "RECT_OPEN": 3,
+   "TRAPEZOIDAL": 4,
+   "TRIANGULAR": 5,
+   "PARABOLIC": 6,
+   "POWER": 7,
+   "MODBASKETHANDLE": 8,
+   "EGGSHAPED": 9,
+   "HORSESHOE": 10,
+   "GOTHIC": 11,
+   "CATENARY": 12,
+   "SEMIELLIPTICAL": 13,
+   "BASKETHANDLE": 14,
+   "SEMICIRCULAR": 15,
+   "RECT_TRIANG": 16,
+   "RECT_ROUND": 17,
+   "HORIZ_ELLIPSE": 18,
+   "VERT_ELLIPSE": 19,
+   "ARCH": 20,
+   "IRREGULAR": 21,
+   "CUSTOM": 22,
+   "FORCE_MAIN": 23,
+   "STREET_XSECT": 24,
+   "DUMMY": 25
+  }
+ }
+}
diff --git a/python/openswmm/engine/catalog.py b/python/openswmm/engine/catalog.py
new file mode 100644
index 000000000..3f0502bdb
--- /dev/null
+++ b/python/openswmm/engine/catalog.py
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Machine-readable map of the Python engine API.
+
+``catalog.json`` is generated from the stubs, Cython sources and C headers by
+``python/scripts/gen_catalog.py``; CI fails when it is stale. It lists every
+*target* reachable from a :class:`Solver` -- services such as ``forcing`` and
+``surface2d.groundwater``, element kinds such as ``node`` and ``link`` and
+their sub-views such as ``node.stats`` -- and every property and method on
+them, with type, access, units, lifecycle phases and wrapped C symbols.
+
+.. code-block:: python
+
+    from openswmm.engine import catalog
+
+    catalog.lookup("node.stats.max_depth")["units"]      # 'length'
+    obj = catalog.resolve(solver, "node.stats", "J1")    # the live NodeStatsView
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+__all__ = ["load", "targets", "members", "lookup", "resolve", "unit_label", "UNIT_KINDS"]
+
+_PATH = Path(__file__).with_name("catalog.json")
+
+
+@lru_cache(maxsize=1)
+def load() -> dict[str, Any]:
+    """Return the whole catalog (cached)."""
+    data: dict[str, Any] = json.loads(_PATH.read_text(encoding="utf-8"))
+    return data
+
+
+@lru_cache(maxsize=1)
+def _by_path() -> dict[str, dict[str, Any]]:
+    return {m["path"]: m for m in load()["members"]}
+
+
+def targets() -> dict[str, dict[str, Any]]:
+    """``{target name: entry}``; element targets carry ``collection`` and ``key``."""
+    entries: dict[str, dict[str, Any]] = load()["targets"]
+    return entries
+
+
+def members(target: str | None = None) -> list[dict[str, Any]]:
+    """Members of one target, or of all targets."""
+    return [m for m in load()["members"] if target is None or m["target"] == target]
+
+
+def lookup(path: str) -> dict[str, Any]:
+    """Return the member entry for a dotted *path* such as ``"node.depth"``."""
+    try:
+        return _by_path()[path]
+    except KeyError:
+        raise KeyError(f"{path!r} is not in the engine catalog") from None
+
+
+def resolve(solver: Any, target: str, key: int | str | None = None) -> Any:
+    """Return the live object behind *target* on *solver*.
+
+    Element targets (``node``, ``link.pump``, ``species`` ...) need the element
+    *key* (id or index). Standalone roots (``builder``, ``output``, ...) are not
+    reachable from a solver and raise ``KeyError``.
+    """
+    entry = targets()[target]
+    if "construct" in entry:
+        raise KeyError(f"{target!r} is a standalone root; construct it directly")
+    obj = solver
+    for part in filter(None, entry["path"].split(".")):
+        if part.endswith("[]"):
+            if key is None:
+                raise ValueError(f"{target!r} is an element target; pass its id or index")
+            obj = getattr(obj, part[:-2])[key]
+        else:
+            obj = getattr(obj, part)
+    return obj
+
+
+# Unit kinds (a member's ``units``) that are not literal units, and their labels.
+_FIXED = {
+    "dimensionless": "dimensionless",
+    "fraction": "fraction",
+    "percent": "%",
+    "count": "count",
+    "manning_n": "Manning's n",
+    "concentration": "pollutant concentration units",
+    "user_defined": "units implied by the model's expressions",
+    "shape_dependent": "depends on the cross-section shape (see xsect.shape)",
+    "unverified": "stored as given; the engine applies no unit conversion",
+    "datetime": "DateTime (decimal days)",
+}
+_BY_SYSTEM = {  # kind: (US label, SI label)
+    "length": ("ft", "m"),
+    "area": ("ft2", "m2"),
+    "land_area": ("ac", "ha"),
+    "volume": ("ft3", "m3"),
+    "velocity": ("ft/s", "m/s"),
+    "rain_rate": ("in/hr", "mm/hr"),
+    "rain_depth": ("in", "mm"),
+    "evap_rate": ("in/day", "mm/day"),
+    "temperature": ("degF", "degC"),
+    "user_temperature": ("degF", "degC"),
+    "wind_speed": ("mph", "km/hr"),
+    "length2/s": ("ft2/s", "m2/s"),
+    "weir_coeff": ("ft^0.5/s", "m^0.5/s"),
+    "section_factor": ("ft^8/3", "m^8/3"),
+}
+#: Every symbolic unit kind; any other ``units`` value is a literal unit ("m3/s", "s").
+UNIT_KINDS = frozenset(_FIXED) | frozenset(_BY_SYSTEM) | {"flow"}
+
+
+def unit_label(
+    kind: str | None, unit_system: str | None = None, flow_units: Any = None
+) -> str | None:
+    """Human-readable units for a catalog unit kind in a model's unit system.
+
+    ``flow`` takes the model's flow units, as a token (``"CFS"``, ``"CMS"``
+    ...) or as ``Solver.flow_units`` itself; other system-dependent kinds take
+    ``"US"`` or ``"SI"`` and come back unchanged without one; literal units
+    pass through.
+
+    .. code-block:: python
+
+        catalog.unit_label(catalog.lookup("link.length")["units"], "SI")   # 'm'
+    """
+    if kind is None or kind in _FIXED:
+        return _FIXED.get(kind) if kind else None
+    if kind == "flow":
+        if flow_units is None or flow_units == "":
+            return kind
+        # A FlowUnits member (CFS is 0, so falsy) labels by its name.
+        return str(getattr(flow_units, "name", flow_units))
+    if kind in _BY_SYSTEM and unit_system in ("US", "SI"):
+        return _BY_SYSTEM[kind][unit_system == "SI"]
+    return kind
diff --git a/python/openswmm/legacy/engine/_solver.pyx b/python/openswmm/legacy/engine/_solver.pyx
index 62c53fb47..ce6515b14 100644
--- a/python/openswmm/legacy/engine/_solver.pyx
+++ b/python/openswmm/legacy/engine/_solver.pyx
@@ -1,11 +1,27 @@
 # cython: language_level=3str
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 openswmm.solver._solver
 ========================
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 
 Cython module for the legacy SWMM 5.x solver bindings. Provides
 enumerations identifying SWMM objects, an exception class, free helper
diff --git a/python/openswmm/output/__init__.py b/python/openswmm/output/__init__.py
index bd0f13a1b..84dd04bb7 100644
--- a/python/openswmm/output/__init__.py
+++ b/python/openswmm/output/__init__.py
@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Backward-compatibility shim that re-exports the full public API of
 ``openswmm.legacy.output`` under the shorter ``openswmm.output`` namespace.
@@ -13,7 +29,7 @@
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 # Backward-compatibility shim: openswmm.output -> openswmm.legacy.output
 # Deprecated: use ``from openswmm.legacy.output import ...`` instead.
diff --git a/python/openswmm/output/_output.pyi b/python/openswmm/output/_output.pyi
index 33414c12c..f1156ccde 100644
--- a/python/openswmm/output/_output.pyi
+++ b/python/openswmm/output/_output.pyi
@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Type stub for the ``openswmm.output._output`` Cython extension module.
 
@@ -6,7 +22,7 @@ carry complete epytext documentation for every public symbol.
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 
 from enum import Enum
diff --git a/python/openswmm/py.typed b/python/openswmm/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/python/openswmm/solver/__init__.py b/python/openswmm/solver/__init__.py
index 92e26f1b4..91ecaf638 100644
--- a/python/openswmm/solver/__init__.py
+++ b/python/openswmm/solver/__init__.py
@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Backward-compatibility shim that re-exports the full public API of
 ``openswmm.legacy.engine`` under the shorter ``openswmm.solver`` namespace.
@@ -13,7 +29,7 @@
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 # Backward-compatibility shim: openswmm.solver -> openswmm.legacy.engine
 # Deprecated: use ``from openswmm.legacy.engine import ...`` instead.
diff --git a/python/openswmm/solver/_solver.pyi b/python/openswmm/solver/_solver.pyi
index 1dbff9fd4..e2b69b923 100644
--- a/python/openswmm/solver/_solver.pyi
+++ b/python/openswmm/solver/_solver.pyi
@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """
 Type stub for the ``openswmm.solver._solver`` Cython extension module.
 
@@ -6,7 +22,7 @@ carry complete epytext documentation for every public symbol.
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 
 from enum import Enum
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 910911c8d..31ff71050 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -33,7 +33,7 @@
 # extensions compile against numpy 2.x and the produced wheels run on any
 # numpy >= 1.21 (since we use only the numpy 1.7+ stable ABI surface).
 requires = [
-    "scikit-build-core >= 0.10",
+    "scikit-build-core >= 0.11",
     "cython >= 3.0.12",
     "numpy >= 1.21",
 ]
@@ -44,11 +44,12 @@ build-backend = "scikit_build_core.build"
 # ============================================================================
 [project]
 name = "openswmm"
-version = "6.0.0a3"
+version = "6.0.0a4.dev1"
 description = "Python bindings for the OpenSWMM stormwater modelling engine."
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
-license = { file = "LICENSE" }
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
 authors     = [{ name = "Caleb Buahin", email = "caleb.buahin@gmail.com" }]
 maintainers = [{ name = "Caleb Buahin", email = "caleb.buahin@gmail.com" }]
 keywords = [
@@ -100,7 +101,16 @@ Changelog     = "https://github.com/hydrocouple/openswmm.engine/blob/main/CHANGE
 # ============================================================================
 [tool.scikit-build]
 minimum-version  = "build-system.requires"
-cmake.version    = ">=3.24"
+# >=4.3, not >=3.24: configuring this project runs the vcpkg toolchain, and
+# vcpkg 2026.07.29's SPDX manifest generation calls
+# `string(JSON ... STRING_ENCODE ...)`, which arrived in CMake 4.3. The floor
+# is what scikit-build-core resolves its build-env CMake against — with
+# >=3.24 it picked 4.1.0 and every Linux wheel died on the first port
+# (`building sqlite3:x64-linux failed with: BUILD_FAILED`) during
+# `python -m build`, even though the cibuildwheel `before-all` vcpkg install
+# had already succeeded on its own pinned CMake. Both CMakes have to clear the
+# bar, because both invoke vcpkg.
+cmake.version    = ">=4.3"
 cmake.build-type = "Release"
 ninja.make-fallback = true
 
@@ -148,6 +158,7 @@ editable.verbose = false
 # sdist: include everything needed to build from scratch on a clean
 # machine, but exclude all build artefacts.
 sdist.include = [
+    "NOTICE",
     "openswmm/**/*.pyi",
     "openswmm/**/*.pxd",
     "openswmm/legacy/**/*.c",
@@ -215,7 +226,7 @@ musllinux-x86_64-image  = "musllinux_1_2"
 musllinux-aarch64-image = "musllinux_1_2"
 
 test-requires = ["pytest", "numpy"]
-test-command  = "pytest {package}/tests/engine -v --import-mode=importlib --ignore={package}/tests/engine/test_integration.py"
+test-command  = "pytest {package}/tests -v --import-mode=importlib --ignore={package}/tests/typing"
 
 [tool.cibuildwheel.linux]
 # Bootstrap vcpkg inside the manylinux container. The host's $VCPKG_ROOT is
@@ -236,18 +247,27 @@ else
   apt-get update && apt-get install -y curl zip unzip tar git ninja-build libgomp1
 fi
 
-# Pin CMake < 4 inside the container, ahead of the system cmake.
-# Why: manylinux_2_28_aarch64:2025.08.15-1 ships CMake 4.x. vcpkg-tool's
-# bundled cmakerc dep has cmake_minimum_required(VERSION 3.3), which CMake
-# 4.x rejects with "Compatibility with CMake < 3.5 has been removed". On
-# x86_64, bootstrap-vcpkg.sh downloads a pre-built binary and skips this
-# CMake compile entirely — the bug only fires on arm64. We apply the pin
-# unconditionally so the same fix protects any vcpkg port (SUNDIALS, HDF5,
-# ...) that might hit the same compatibility removal on either arch.
-# Belt-and-suspenders: CMAKE_POLICY_VERSION_MINIMUM=3.5 (set in `environment`
-# below, so it persists into the build phase) makes any CMake 4.x that still
-# gets invoked accept the < 3.5 minimum instead of failing.
-/opt/python/cp312-cp312/bin/pip install --quiet 'cmake<4'
+# Pin CMake >= 4.3 inside the container, ahead of the system cmake.
+#
+# LOWER bound: vcpkg 2026.07.29's SPDX manifest generation calls
+# `string(JSON ... STRING_ENCODE ...)` from z_vcpkg_add_spdx_resource
+# (scripts/cmake/vcpkg_download_distfile.cmake:160). STRING_ENCODE arrived in
+# CMake 4.3; anything older dies with "string sub-command JSON got an invalid
+# mode 'STRING_ENCODE'" on the FIRST port it downloads (sqlite3), before any
+# compilation. This is what the previous `cmake<4` pin caused once VCPKG_REF
+# moved to 2026.07.29.
+#
+# The `cmake<4` pin it replaces existed because manylinux_2_28_aarch64 ships
+# CMake 4.x and vcpkg-tool's bundled cmakerc dep has
+# cmake_minimum_required(VERSION 3.3), which CMake 4.x rejects with
+# "Compatibility with CMake < 3.5 has been removed" (arm64 only: on x86_64
+# bootstrap-vcpkg.sh downloads a prebuilt binary and never compiles cmakerc).
+# That is now handled solely by CMAKE_POLICY_VERSION_MINIMUM=3.5, set in
+# `environment` below so it persists into the build phase — it makes CMake 4.x
+# accept the < 3.5 minimum instead of failing. The pin was belt to that
+# suspenders; the two requirements are now in direct conflict, and the env var
+# is the one that can satisfy both.
+/opt/python/cp312-cp312/bin/pip install --quiet 'cmake>=4.3'
 export PATH="/opt/python/cp312-cp312/bin:$PATH"
 
 case "$(uname -m)" in
@@ -261,7 +281,7 @@ esac
 # it invokes the downloaded ninja ("vcpkg was unable to detect the active
 # compiler's information", CMAKE_MAKE_PROGRAM=.../downloads/tools/ninja/...).
 # The system tools are installed above (apk ninja/samurai, yum/apt ninja-build)
-# with the pinned cmake<4 on PATH. This is what unbreaks the musllinux wheels;
+# with the pinned cmake>=4.3 on PATH. This is what unbreaks the musllinux wheels;
 # it is a no-op on manylinux (glibc), where the same system tools are valid too.
 export VCPKG_FORCE_SYSTEM_BINARIES=1
 # /host persists across the manylinux and musllinux container runs within a
@@ -284,19 +304,23 @@ if [ -d /tmp/vcpkg-downloads ]; then
   mv /tmp/vcpkg-downloads /host/vcpkg/downloads
 fi
 /host/vcpkg/bootstrap-vcpkg.sh -disableMetrics
-# CPU-only base wheel: opt out of vcpkg default-features so the now-default `gpu`
-# feature (Kokkos) is NOT built/linked here. Mirrors the
-# CMake-side opt-out in python/CMakeLists.txt; keeps this wheel Kokkos-free and
-# portable. OpenMP acceleration ships via the openswmm-gpu-omp companion wheel.
-# `hypre` IS pulled here so PRECONDITIONER=AMG (the 2D solver default) works in
-# the wheel via the serial BoomerAMG preconditioner — must mirror the `2d;hypre`
-# feature list in python/CMakeLists.txt (OPENSWMM_WITH_HYPRE defaults ON).
+# Features are listed explicitly rather than taken from default-features, so
+# this wheel's dependency set is stated here and does not silently follow a
+# future edit of vcpkg.json. Keep in step with VCPKG_MANIFEST_FEATURES in
+# python/CMakeLists.txt, which the BUILD phase reads when it re-runs the vcpkg
+# toolchain in manifest mode.
+# `gpu` pulls Kokkos for the OpenMP surface-solver plugin, which the base wheel
+# now builds and ships in openswmm/engine/ (the companion wheel still builds
+# the same plugin; the discovery shim prefers the in-wheel copy).
+# `hypre` IS pulled so PRECONDITIONER=AMG (the 2D solver default) works in the
+# wheel via the serial BoomerAMG preconditioner (OPENSWMM_WITH_HYPRE defaults ON).
 /host/vcpkg/vcpkg install \
   --triplet "$VCPKG_TRIPLET" \
   --x-manifest-root /project \
   --x-install-root /host/vcpkg/installed \
   --x-no-default-features \
   --x-feature 2d \
+  --x-feature gpu \
   --x-feature hypre
 """
 before-build = "pip install ninja"
diff --git a/python/scripts/api_drift_audit.py b/python/scripts/api_drift_audit.py
index 860e17004..08af3927b 100644
--- a/python/scripts/api_drift_audit.py
+++ b/python/scripts/api_drift_audit.py
@@ -24,6 +24,8 @@
 from __future__ import annotations
 
 import argparse
+import io
+import tokenize
 import json
 import re
 import sys
@@ -63,7 +65,7 @@ def collect_c_functions() -> dict[str, str]:
     for h in sorted(HEADERS.glob("openswmm_*.h")):
         if h.name in HEADER_EXCLUDE:
             continue
-        text = _read(h)
+        text = re.sub(r"/\*.*?\*/|//[^\n]*", "", _read(h), flags=re.S)
         for m in _FUNC_RE.finditer(text):
             funcs.setdefault(m.group(1), h.name)
     return funcs
@@ -79,25 +81,57 @@ def collect_c_enums() -> dict[str, str]:
     return enums
 
 
-def collect_pxd_functions() -> set[str]:
-    """Functions declared in a .pxd OR via a `cdef extern` block inside a .pyx.
+# These have Python-native replacements rather than missing wrappers.
+KNOWN_UNBOUND = frozenset({
+    "swmm_get_last_error",      # typed EngineError exceptions
+    "swmm_get_last_error_msg",  # typed EngineError exceptions
+    "swmm_get_current_time",    # Solver.current_datetime
+})
+
+
+def executable_cython(text: str, *, declarations: bool = False) -> str:
+    """Keep code or extern declarations, excluding comments/string literals.
 
-    Cython lets you put `cdef extern from "header.h"` declarations directly in a
-    .pyx (the geopackage and 2D modules do this), so a function declared there
-    is wrapped even though it never appears in a .pxd.
+    Shared .pxd helpers contain executable code and must count as uses.
+    Tokenization preserves indentation, including multiline docstrings.
     """
-    names: set[str] = set()
-    for src in list(ENGINE.glob("*.pxd")) + list(ENGINE.glob("*.pyx")):
-        for m in _PXD_FUNC_RE.finditer(_read(src)):
-            names.add(m.group(1))
+    lines = text.splitlines(keepends=True)
+    for token in tokenize.generate_tokens(io.StringIO(text).readline):
+        if token.type not in (tokenize.COMMENT, tokenize.STRING):
+            continue
+        (first, left), (last, right) = token.start, token.end
+        for row in range(first - 1, last):
+            lo = left if row == first - 1 else 0
+            hi = right if row == last - 1 else len(lines[row].rstrip("\r\n"))
+            lines[row] = lines[row][:lo] + " " * (hi - lo) + lines[row][hi:]
+    out, in_extern, level = [], False, 0
+    for line in lines:
+        stripped = line.strip()
+        indent = len(line) - len(line.lstrip())
+        if re.match(r"cdef\s+extern\b", stripped):
+            in_extern, level = True, indent
+            continue
+        if in_extern and stripped and indent <= level:
+            in_extern = False
+        if in_extern == declarations:
+            out.append(line)
+    return "".join(out)
+
+
+def collect_pxd_functions() -> set[str]:
+    """Declarations in .pxd files and inline .pyx extern blocks."""
+    names = set()
+    for src in [*ENGINE.glob("*.pxd"), *ENGINE.glob("*.pyx")]:
+        names.update(_PXD_FUNC_RE.findall(executable_cython(_read(src), declarations=True)))
     return names
 
 
 def collect_pyx_tokens() -> set[str]:
-    blob = "\n".join(_read(p) for p in ENGINE.glob("*.pyx"))
-    return set(_PXD_FUNC_RE.findall(blob)) | set(
-        re.findall(r"\b(swmm_[A-Za-z0-9_]+)\b", blob)
-    )
+    """Executable references, including helper functions in shared .pxd files."""
+    names = set()
+    for src in [*ENGINE.glob("*.pyx"), *ENGINE.glob("*.pxd")]:
+        names.update(re.findall(r"\b(swmm_[A-Za-z0-9_]+)\b", executable_cython(_read(src))))
+    return names
 
 
 def collect_py_enums() -> set[str]:
@@ -132,6 +166,7 @@ def main() -> int:
         if tail not in py_enums
     }
 
+    unbound = sorted(set(c_funcs) - pyx - KNOWN_UNBOUND)
     report = {
         "totals": {
             "c_functions": len(c_funcs),
@@ -139,6 +174,8 @@ def main() -> int:
             "c_enums": len(c_enums),
             "py_enums": len(py_enums),
         },
+        "unbound_without_exemption": unbound,
+        "intentional_exclusions": sorted(KNOWN_UNBOUND),
         "functions_missing_from_pxd": dict(sorted(missing_decl.items())),
         "declared_but_unsurfaced_in_pyx": declared_unsurfaced,
         "enums_missing_from_python": dict(sorted(missing_enums.items())),
@@ -190,11 +227,11 @@ def main() -> int:
             print(f"  {name}   ({hdr})")
         print()
         print(f"== Declared in .pxd but NOT referenced in any .pyx ({len(declared_unsurfaced)}) ==")
-        print("   (weak signal -- may be reached via bulk/helper paths)")
+        print("   (excludes comments, strings and extern declarations; includes .pxd helpers)")
         for fn in declared_unsurfaced:
             print(f"      {fn}")
 
-    gaps = bool(missing_decl or missing_enums)
+    gaps = bool(unbound or missing_enums)
     if args.strict and gaps:
         return 1
     return 0
diff --git a/python/scripts/catalog_overrides.json b/python/scripts/catalog_overrides.json
new file mode 100644
index 000000000..33344a88f
--- /dev/null
+++ b/python/scripts/catalog_overrides.json
@@ -0,0 +1,182 @@
+{
+ "element_names": {
+  "nodes": "node",
+  "links": "link",
+  "subcatchments": "subcatchment",
+  "gages": "gage",
+  "pollutants": "pollutant",
+  "quality.landuses": "landuse",
+  "patterns": "pattern",
+  "tables": "table",
+  "process_components": "process_component",
+  "reactions.species": "species",
+  "reactions.coefficients": "coefficient",
+  "reactions.terms": "term"
+ },
+ "subtype_fields": {
+  "Node": "type",
+  "Link": "type"
+ },
+ "subtypes": {
+  "node.storage": [
+   "STORAGE"
+  ],
+  "node.outfall": [
+   "OUTFALL"
+  ],
+  "node.divider": [
+   "DIVIDER"
+  ],
+  "link.pump": [
+   "PUMP"
+  ],
+  "link.weir": [
+   "WEIR"
+  ],
+  "link.orifice": [
+   "ORIFICE"
+  ],
+  "link.outlet": [
+   "OUTLET"
+  ]
+ },
+ "variants": {
+  "table": [
+   "TimeSeries",
+   "Curve"
+  ]
+ },
+ "roots": {
+  "builder": {
+   "class": "ModelBuilder",
+   "construct": {
+    "via": "new",
+    "args": []
+   }
+  },
+  "output": {
+   "class": "OutputReader",
+   "construct": {
+    "via": "new",
+    "args": [
+     "path"
+    ]
+   }
+  },
+  "geopackage": {
+   "class": "GeoPackage",
+   "construct": {
+    "via": "new",
+    "args": [
+     "path"
+    ]
+   }
+  },
+  "hotstart": {
+   "class": "HotStart",
+   "construct": {
+    "via": "open",
+    "args": [
+     "path"
+    ]
+   }
+  },
+  "xsect": {
+   "class": "XSectionGeometry",
+   "construct": {
+    "via": "new",
+    "args": [
+     "shape",
+     "geom1",
+     "geom2",
+     "geom3",
+     "geom4",
+     "units"
+    ]
+   }
+  }
+ },
+ "function_modules": [
+  "datetime",
+  "dates"
+ ],
+ "record_classes": [
+  "ImpactEntry",
+  "ConversionResult"
+ ],
+ "exclude_members": [
+  "Solver.handle",
+  "Solver.generation",
+  "ModelBuilder.transport",
+  "ModelBuilder.handle",
+  "ModelBuilder.generation"
+ ],
+ "exclude_classes": [
+  "EngineError",
+  "BadHandleError",
+  "BadIndexError",
+  "BadParamError",
+  "CRSError",
+  "DependencyError",
+  "FileError",
+  "HotStartError",
+  "LifecycleError",
+  "NumericalError",
+  "ParseError",
+  "PluginError",
+  "StaleObjectError"
+ ],
+ "units": {
+  "climate.ati_weight": "fraction",
+  "climate.temp_file_start": "datetime",
+  "coefficient.value": "user_defined",
+  "gage.snow_factor": "dimensionless",
+  "link.control_setting": "dimensionless",
+  "link.outlet.expon": "dimensionless",
+  "link.pump.shutoff_depth": "length",
+  "link.pump.startup_depth": "length",
+  "link.roughness": "manning_n",
+  "link.seep_rate": "rain_rate",
+  "link.slope": "fraction",
+  "link.target_setting": "dimensionless",
+  "link.weir.crest_height": "length",
+  "link.weir.discharge_coeff": "weir_coeff",
+  "link.weir.end_contractions": "count",
+  "link.xsect.g1": "length",
+  "link.xsect.g2": "shape_dependent",
+  "link.xsect.g3": "shape_dependent",
+  "link.xsect.g4": "shape_dependent",
+  "mass_balance.max_courant": "dimensionless",
+  "node.outfall.param": "length",
+  "node.stats.time_flooded": "s",
+  "node.storage.seep_rate": "unverified",
+  "pollutant.gw_conc": "concentration",
+  "pollutant.init_conc": "concentration",
+  "pollutant.mwt": "g/mol",
+  "pollutant.rain_conc": "concentration",
+  "pollutant.rdii_conc": "concentration",
+  "species.atol": "concentration",
+  "species.initial": "concentration",
+  "species.rtol": "dimensionless",
+  "statistics.node_time_flooded": "s",
+  "subcatchment.area": "land_area",
+  "subcatchment.ds_imperv": "rain_depth",
+  "subcatchment.ds_perv": "rain_depth",
+  "subcatchment.evap": "evap_rate",
+  "subcatchment.infil": "rain_rate",
+  "subcatchment.infiltration.curve_number": "dimensionless",
+  "subcatchment.infiltration.curve_number_drying_time": "d",
+  "subcatchment.n_imperv": "manning_n",
+  "subcatchment.n_perv": "manning_n",
+  "surface2d.get_rainfall": "m/s",
+  "surface2d.max_depth": "m",
+  "surface2d.total_exchange_flow": "m3/s",
+  "surface2d.total_volume": "m3",
+  "xsect.full_area": "area",
+  "xsect.full_depth": "length",
+  "xsect.full_hyd_radius": "length",
+  "xsect.full_section_factor": "section_factor",
+  "xsect.max_area": "area",
+  "xsect.max_width": "length"
+ }
+}
diff --git a/python/scripts/gen_catalog.py b/python/scripts/gen_catalog.py
new file mode 100644
index 000000000..d417f7a37
--- /dev/null
+++ b/python/scripts/gen_catalog.py
@@ -0,0 +1,767 @@
+#!/usr/bin/env python3
+"""Generate ``openswmm/engine/catalog.json``, a machine-readable map of the
+Python engine API.
+
+The catalog lists every target reachable from a :class:`Solver` (and a few
+standalone roots) with its properties and methods. Each entry carries its type,
+access, units, lifecycle states, applicable subtypes, the C symbols it wraps,
+and a one-paragraph description. Downstream consumers use it to reach the whole
+API without per-function code: the MCP server's generic ``get``/``set``/``call``
+tools and gymnasium's field-path observations.
+
+It is generated from source text, so no compiled engine is needed:
+
+* ``.pyi`` stubs give the typed class graph, signatures and return types.
+* ``.pyx`` sources say which properties have setters and hold runtime docstrings.
+* The ``.pyx`` call graph (shared with ``plans/parity``) gives C symbols per member.
+* Public headers give ``@brief`` text, units and lifecycle states per C symbol.
+* ``python/scripts/catalog_overrides.json`` names element kinds, subtypes and
+  roots, and lists deliberate exclusions.
+
+Usage::
+
+    python python/scripts/gen_catalog.py          # rewrite catalog.json
+    python python/scripts/gen_catalog.py --check  # exit 1 if stale or incomplete
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import importlib.util
+import json
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+ENGINE_DIR = REPO / "python" / "openswmm" / "engine"
+HEADER_DIR = REPO / "include" / "openswmm" / "engine"
+OUT_JSON = ENGINE_DIR / "catalog.json"
+OVERRIDES = Path(__file__).with_name("catalog_overrides.json")
+SCHEMA = 1
+
+
+def _load(name: str, path: Path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_provenance = _load("_provenance", REPO / "plans/parity/tools/build_matrix_provenance.py")
+
+# ---------------------------------------------------------------------------
+# Stubs
+# ---------------------------------------------------------------------------
+RECORD_BASES = {"NamedTuple"}
+MAPPING_BASES = ("MutableMapping", "Mapping")
+SEQUENCE_BASES = ("MutableSequence", "Sequence")
+
+
+@dataclass
+class Member:
+    name: str
+    form: str                      # "property" | "method"
+    type: str = ""                 # property type / method return type
+    params: list[dict] = field(default_factory=list)
+    doc: str = ""
+    stub_setter: bool = False
+    static: bool = False
+
+
+@dataclass
+class Cls:
+    name: str
+    module: str
+    bases: list[str]
+    doc: str = ""
+    record: bool = False
+    members: dict[str, Member] = field(default_factory=dict)
+    getitem: tuple[str, str] | None = None     # (key type, value type)
+    setitem: bool = False
+    delitem: bool = False
+    iter_type: str = ""
+
+
+def _first_paragraph(doc: str | None) -> str:
+    if not doc:
+        return ""
+    text = doc.strip().split("\n\n", 1)[0]
+    text = re.sub(r"\s+", " ", text)
+    # Epytext / reST markup to plain text.
+    text = re.sub(r"[LCIBM]\{([^}]*)\}", r"\1", text)
+    text = re.sub(r":(?:class|meth|func|attr|data|mod):`~?([^`]*)`", r"\1", text)
+    return text.replace("``", "").strip()
+
+
+def _unparse(node: ast.AST | None) -> str:
+    return "" if node is None else ast.unparse(node).strip("'\"")
+
+
+def parse_stubs() -> tuple[dict[str, Cls], dict[str, dict], dict[str, str]]:
+    """Return (classes, module functions, type aliases) from every ``_*.pyi``."""
+    classes: dict[str, Cls] = {}
+    functions: dict[str, dict] = {}
+    aliases: dict[str, str] = {}
+    for pyi in sorted(ENGINE_DIR.glob("_*.pyi")):
+        module = pyi.stem
+        tree = ast.parse(pyi.read_text(encoding="utf-8"))
+        for node in tree.body:
+            if isinstance(node, ast.Assign) and len(node.targets) == 1 \
+                    and isinstance(node.targets[0], ast.Name) and node.targets[0].id.startswith("_"):
+                aliases[node.targets[0].id] = _unparse(node.value)
+            elif isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
+                functions.setdefault(module, {})[node.name] = _method(node).__dict__
+            elif isinstance(node, ast.ClassDef):
+                classes[node.name] = _parse_class(node, module)
+    return classes, functions, aliases
+
+
+def _method(node: ast.FunctionDef) -> Member:
+    params = []
+    args = node.args
+    positional = args.posonlyargs + args.args
+    defaults = [None] * (len(positional) - len(args.defaults)) + list(args.defaults)
+    for a, d in zip(positional, defaults):
+        if a.arg in ("self", "cls"):
+            continue
+        params.append({"name": a.arg, "type": _unparse(a.annotation), "required": d is None})
+    for a, d in zip(args.kwonlyargs, args.kw_defaults):
+        params.append({"name": a.arg, "type": _unparse(a.annotation), "required": d is None,
+                       "keyword_only": True})
+    static = any(_unparse(d) in ("staticmethod", "classmethod") for d in node.decorator_list)
+    return Member(node.name, "method", _unparse(node.returns), params,
+                  _first_paragraph(ast.get_docstring(node)), static=static)
+
+
+def _parse_class(node: ast.ClassDef, module: str) -> Cls:
+    bases = [_unparse(b) for b in node.bases]
+    decorators = [_unparse(d) for d in node.decorator_list]
+    record = any(b.split("[")[0] in RECORD_BASES for b in bases) or \
+        any(d.startswith("dataclass") for d in decorators)
+    cls = Cls(node.name, module, bases, _first_paragraph(ast.get_docstring(node)), record)
+    for item in node.body:
+        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+            name = item.target.id
+            if not name.startswith("_"):
+                cls.members[name] = Member(name, "property", _unparse(item.annotation))
+        elif isinstance(item, ast.FunctionDef):
+            decos = [_unparse(d) for d in item.decorator_list]
+            if item.name == "__getitem__":
+                key = item.args.args[1].annotation if len(item.args.args) > 1 else None
+                cls.getitem = (_unparse(key), _unparse(item.returns))
+            elif item.name == "__setitem__":
+                cls.setitem = True
+            elif item.name == "__delitem__":
+                cls.delitem = True
+            elif item.name == "__iter__":
+                cls.iter_type = _unparse(item.returns)
+            elif item.name.startswith("_"):
+                continue
+            elif "property" in decos:
+                m = _method(item)
+                cls.members[item.name] = Member(item.name, "property", m.type, doc=m.doc)
+            elif any(d.endswith(".setter") for d in decos):
+                if item.name in cls.members:
+                    cls.members[item.name].stub_setter = True
+            else:
+                cls.members[item.name] = _method(item)
+    return cls
+
+
+def parse_enums() -> dict[str, dict[str, int]]:
+    """``{EnumName: {MEMBER: value}}`` from the runtime ``_enums.py``."""
+    tree = ast.parse((ENGINE_DIR / "_enums.py").read_text(encoding="utf-8"))
+    enums: dict[str, dict[str, int]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        if not any(_unparse(b) in ("IntEnum", "IntFlag", "Enum") for b in node.bases):
+            continue
+        values: dict[str, int] = {}
+        for item in node.body:
+            if isinstance(item, ast.Assign) and isinstance(item.targets[0], ast.Name):
+                name = item.targets[0].id
+                if name.startswith("_"):
+                    continue
+                try:
+                    values[name] = ast.literal_eval(item.value)
+                except ValueError:
+                    ref = _unparse(item.value)
+                    if ref in values:
+                        values[name] = values[ref]
+        enums[node.name] = values
+    return enums
+
+
+# ---------------------------------------------------------------------------
+# .pyx: setters and runtime docstrings
+# ---------------------------------------------------------------------------
+_CLASS = re.compile(r"^(?:cdef\s+)?class\s+(\w+)")
+_DEF = re.compile(r"^    (?:cp?def\s+(?:[\w\[\], ]+\s+)?|def\s+)(\w+)\s*\(")
+_SETTER = re.compile(r"^    @(\w+)\.setter")
+
+
+def parse_pyx() -> tuple[set[tuple[str, str]], dict[tuple[str, str], str]]:
+    setters: set[tuple[str, str]] = set()
+    docs: dict[tuple[str, str], str] = {}
+    for pyx in sorted(ENGINE_DIR.glob("_*.pyx")):
+        lines = pyx.read_text(encoding="utf-8").splitlines()
+        cls = ""
+        for i, line in enumerate(lines):
+            m = _CLASS.match(line)
+            if m:
+                cls = m.group(1)
+                continue
+            if line and not line[0].isspace():
+                cls = ""
+            if not cls:
+                continue
+            m = _SETTER.match(line)
+            if m:
+                setters.add((cls, m.group(1)))
+                continue
+            m = _DEF.match(line)
+            if m and (cls, m.group(1)) not in docs:
+                doc = _docstring_after(lines, i)
+                if doc:
+                    docs[(cls, m.group(1))] = doc
+    return setters, docs
+
+
+def _docstring_after(lines: list[str], i: int) -> str:
+    j = i
+    while j < len(lines) and not lines[j].rstrip().endswith(":"):
+        j += 1
+    j += 1
+    if j >= len(lines):
+        return ""
+    first = lines[j].strip()
+    m = re.match(r'^[rRuU]?("""|\'\'\')', first)
+    if not m:
+        return ""
+    quote = m.group(1)
+    body = first[m.end():]
+    if quote in body:
+        return _first_paragraph(body.split(quote)[0])
+    chunk = [body]
+    for k in range(j + 1, min(j + 200, len(lines))):
+        if quote in lines[k]:
+            chunk.append(lines[k].split(quote)[0])
+            break
+        chunk.append(lines[k])
+    return _first_paragraph("\n".join(chunk))
+
+
+# ---------------------------------------------------------------------------
+# Headers: brief, units, lifecycle states per C symbol
+# ---------------------------------------------------------------------------
+_DOC_DECL = re.compile(r"/\*\*((?:(?!\*/).)*)\*/\s*SWMM_ENGINE_API[^;{]*?\b(swmm_\w+)\s*\(", re.S)
+
+# First match wins; applied to the documentation of the value a getter returns.
+UNIT_PATTERNS: list[tuple[str, str]] = [
+    (r"in/hr for us, mm/hr for si|in/hr or mm/hr|rainfall intensity", "rain_rate"),
+    (r"in/day (?:for )?us, mm/day (?:for )?si", "evap_rate"),
+    (r"mph us, km/hr si", "wind_speed"),
+    (r"deg f us, deg c si", "user_temperature"),
+    (r"cfs for us, cms for si|project flow units|\bflow units\b", "flow"),
+    (r"project length/time units|project velocity units|velocity units|ft/s or m/s", "velocity"),
+    (r"project volume units|volume units|ft3 or m3|ft³ or m³", "volume"),
+    (r"project area units|\barea units\b|ft2 or m2", "area"),
+    (r"project length units|\blength units\b|\bft or m\b|feet or meters|user depth units", "length"),
+    (r"project rate units", "rain_rate"),
+    (r"pollutant units|concentration units|pollutant's concentration", "concentration"),
+    (r"\bcrs units\b", "crs"),
+    (r"\(m3/s\)|\(m³/s\)", "m3/s"),
+    (r"\(m2/s\)", "m2/s"),
+    (r"\(m/s", "m/s"),
+    (r"\(m³\)|\(m3\)", "m3"),
+    (r"\(m2\)|\(m²\)", "m2"),
+    (r"\(m\)", "m"),
+    (r"\(mm\)|millimetres|millimeters", "mm"),
+    (r"\(in or mm\)|inches or mm", "rain_depth"),
+    (r"\(°c\)|\(deg ?c\)|\bdegc\b|degrees c(?:elsius)?\b|°c", "degC"),
+    (r"\bin seconds\b|\(seconds\)|\bseconds\b", "s"),
+    (r"\bin hours\b|\(hours\)", "h"),
+    (r"\bin days\b|\(days\b", "d"),
+    (r"\bin percent\b|\bpercentage\b", "percent"),
+    (r"fraction per second", "1/s"),
+    (r"\bfraction\b|\(0\.\.1\)|\bratio\b", "fraction"),
+    (r"\bdimensionless\b", "dimensionless"),
+    (r"\(1/day\)", "1/day"),
+    (r"\bw/m2\b|w/m²", "W/m2"),
+    (r"project temperature units", "temperature"),
+    (r"project length squared per second", "length2/s"),
+    (r"ft-lb/s", "ft-lb/s"),
+    (r"\(ft3\)", "volume"),
+    (r"\(degrees\b", "deg"),
+    (r"\(minutes\b", "min"),
+]
+_STATE_RE = re.compile(r"@param\s+engine\b[^\n]*?\(([A-Z_]+(?:\s*(?:,|or|/)\s*[A-Z_]+)*)\s+state", re.S)
+
+
+_CALL = re.compile(r"(?:\b(self|cls)\s*\.\s*)?\b([A-Za-z_]\w*)\s*\(")
+# Error reporting runs on every failing call; it is not functionality.
+_NOT_HELPERS = {"_check"}
+
+
+_CLASS_BASES = re.compile(r"^\s*(?:cdef\s+)?class\s+(\w+)\s*(?:\(([^)]*)\))?")
+
+
+def c_symbols_by_def() -> dict[tuple[str, str], set[str]]:
+    """``{(class, def): C symbols}``, following calls into helpers.
+
+    A public method often reaches the C API through a private helper
+    (``self._add``, ``_call_scalar``) or a module-level function, possibly in
+    another module (``Solver.thread_info`` -> ``_transport.thread_info``).
+    Those symbols belong to the public member too. ``self._helper`` calls
+    dispatch on the concrete class, so a method inherited from a Cython base
+    (``Aquifers.rename`` from ``_NamedObjects``) gets the subclass's symbols.
+    Module-level defs use the class ``""``.
+    """
+    direct: dict[tuple[str, str], set[str]] = defaultdict(set)
+    for sym, sites in _provenance.pyx_callgraph().items():
+        for _module, cls, name in sites:
+            direct[(cls, name)].add(sym)
+    calls: dict[tuple[str, str], set[tuple[str, str]]] = defaultdict(set)
+    defined: set[tuple[str, str]] = set()
+    module_defs: dict[str, int] = defaultdict(int)          # name -> modules defining it
+    bases: dict[str, list[str]] = {}
+    for pyx in sorted(ENGINE_DIR.glob("*.pyx")):
+        scopes: list[tuple[int, str, str]] = []
+        in_extern, extern_indent = False, 0
+        for raw in _provenance._audit.executable_cython(pyx.read_text(encoding="utf-8")).splitlines():
+            code = raw.split("#", 1)[0]
+            if not code.strip():
+                continue
+            indent = len(code) - len(code.lstrip())
+            if _provenance._CDEF_EXTERN.match(code.strip()):
+                in_extern, extern_indent = True, indent
+                continue
+            if in_extern:
+                if indent <= extern_indent:
+                    in_extern = False
+                else:
+                    continue
+            if (cm := _provenance._CLASS_RE.match(code)):
+                while scopes and scopes[-1][0] >= len(cm.group("i")):
+                    scopes.pop()
+                scopes.append((len(cm.group("i")), "class", cm.group("name")))
+                bm = _CLASS_BASES.match(code)
+                bases.setdefault(cm.group("name"), [b.strip() for b in (bm.group(2) or "").split(",")
+                                                     if b.strip()])
+                continue
+            if (dm := _provenance._DEF_RE.match(code)):
+                while scopes and scopes[-1][0] >= len(dm.group("i")):
+                    scopes.pop()
+                if not any(s[1] == "def" for s in scopes):
+                    cls = next((s[2] for s in reversed(scopes) if s[1] == "class"), "")
+                    defined.add((cls, dm.group("name")))
+                    if not cls:
+                        module_defs[dm.group("name")] += 1
+                scopes.append((len(dm.group("i")), "def", dm.group("name")))
+                continue
+            cur_def = next((s for s in reversed(scopes) if s[1] == "def"), None)
+            if cur_def is None:
+                continue
+            cls = next((s[2] for s in reversed(scopes) if s[1] == "class"), "")
+            for qual, name in _CALL.findall(code):
+                calls[(cls, cur_def[2])].add((qual, name))
+
+    def mro(cls: str) -> list[str]:
+        out, todo = [], [cls]
+        while todo:
+            c = todo.pop(0)
+            if c not in out:
+                out.append(c)
+                todo.extend(bases.get(c, []))
+        return out
+
+    def owner(cls: str, name: str) -> str | None:
+        return next((c for c in mro(cls) if (c, name) in defined), None)
+
+    memo: dict[tuple[str, str], set[str]] = {}
+
+    def symbols(cls: str, name: str, seen: frozenset) -> set[str]:
+        """Symbols reached by ``cls.name`` (``cls`` is the concrete class)."""
+        key = (cls, name)
+        if key in memo:
+            return memo[key]
+        home = owner(cls, name) if cls else ("" if ("", name) in defined else None)
+        if home is None:
+            return set()
+        out = set(direct.get((home, name), ()))
+        for qual, callee in calls.get((home, name), ()):
+            if callee in _NOT_HELPERS:
+                continue
+            if qual and cls:
+                target = (cls, callee) if callee.startswith("_") and not callee.startswith("__") \
+                    else None
+            else:
+                target = ("", callee) if module_defs.get(callee) == 1 or ("", callee) in defined \
+                    else None
+            if target and target not in seen and target != key:
+                out |= symbols(target[0], target[1], seen | {key})
+        memo[key] = out
+        return out
+
+    result: dict[tuple[str, str], set[str]] = {}
+    for cls in {c for c, _ in defined} | set(bases):
+        for c in mro(cls):
+            for d_cls, name in defined:
+                if d_cls == c and (cls, name) not in result:
+                    result[(cls, name)] = symbols(cls, name, frozenset())
+    return result
+
+
+def parse_headers() -> dict[str, dict]:
+    info: dict[str, dict] = {}
+    for header in sorted(HEADER_DIR.glob("openswmm_*.h")):
+        text = header.read_text(encoding="utf-8")
+        for m in _DOC_DECL.finditer(text):
+            doc = re.sub(r"^\s*\*", "", m.group(1), flags=re.M)
+            info[m.group(2)] = _header_entry(doc)
+    return info
+
+
+def _header_entry(doc: str) -> dict:
+    brief = re.search(r"@brief\s+(.*?)(?:\n\s*\n|\n\s*@|$)", doc, re.S)
+    outs = re.findall(r"@param\[out\][^\n]*(?:\n(?!\s*@)[^\n]*)*", doc)
+    # With several out-parameters a unit phrase cannot be tied to one of them.
+    out_lines = outs[0] if len(outs) == 1 else ""
+    returns = " ".join(re.findall(r"@returns?\b[^\n]*", doc))
+    states = _STATE_RE.search(doc)
+    entry = {
+        "brief": re.sub(r"\s+", " ", brief.group(1)).strip() if brief else "",
+        "units": _units(out_lines) or _units(brief.group(1) if brief else "")
+                 or _units(returns),
+        "phases": sorted(set(re.findall(r"[A-Z_]{4,}", states.group(1)))) if states else [],
+    }
+    return entry
+
+
+def _rank_symbols(member: str, symbols: list[str]) -> list[str]:
+    """Order a member's C symbols so the one documenting it comes first.
+
+    Getters whose name contains the member name win; counts and setters
+    (called only for sizing or writing) come last.
+    """
+    stem = member.rstrip("s")
+
+    def key(sym: str) -> tuple[int, int, str]:
+        return (0 if stem and stem in sym else 1,
+                1 if sym.endswith("_count") or "_set_" in sym else 0, sym)
+
+    return sorted(symbols, key=key)
+
+
+def _units(text: str) -> str | None:
+    low = text.lower()
+    for pattern, unit in UNIT_PATTERNS:
+        if re.search(pattern, low):
+            return unit
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Catalog assembly
+# ---------------------------------------------------------------------------
+def _type_name(t: str) -> str:
+    """Strip quotes/Optional from a stub annotation to find a class name."""
+    t = t.strip().strip("'\"")
+    m = re.fullmatch(r"(?:Optional\[)?\s*['\"]?(\w+)['\"]?\s*\]?", t)
+    return m.group(1) if m else ""
+
+
+def _expand(t: str, aliases: dict[str, str]) -> str:
+    return re.sub(r"\b(_[A-Z]\w*)\b", lambda m: aliases.get(m.group(1), m.group(1)), t)
+
+
+class Builder:
+    def __init__(self) -> None:
+        self.classes, self.functions, self.aliases = parse_stubs()
+        self.enums = parse_enums()
+        self.setters, self.pyx_docs = parse_pyx()
+        self.headers = parse_headers()
+        self.overrides = json.loads(OVERRIDES.read_text(encoding="utf-8"))
+        self.c_by_member = c_symbols_by_def()
+        self.targets: dict[str, dict] = {}
+        self.members: list[dict] = []
+        self.class_target: dict[str, str] = {}
+
+    # -- walk ---------------------------------------------------------------
+    def is_target_class(self, name: str) -> bool:
+        cls = self.classes.get(name)
+        return bool(cls) and not cls.record and name not in self.enums \
+            and name not in self.overrides["record_classes"]
+
+    def walk(self, target: str, cls_name: str, path: str, **extra) -> None:
+        """Breadth-first walk of the typed property/element graph from one root.
+
+        Breadth-first so a class is named by its shortest path: ``gages[]`` is
+        the ``gage`` element before ``subcatchments[].gage`` can claim it.
+        """
+        ov = self.overrides
+        queue = [(target, cls_name, path, extra)]
+        while queue:
+            target, cls_name, path, extra = queue.pop(0)
+            if target in self.targets or cls_name in self.class_target:
+                continue
+            cls = self.classes[cls_name]
+            entry = {"class": cls_name, "module": cls.module, "path": path,
+                     "doc": cls.doc or self.pyx_docs.get((cls_name, "__init__"), "")}
+            entry.update({k: v for k, v in extra.items() if v is not None})
+            if target in ov["subtypes"]:
+                entry["subtypes"] = ov["subtypes"][target]
+            self.targets[target] = entry
+            self.class_target[cls_name] = target
+            prefix = "" if target == "solver" else target + "."
+            for name, m in cls.members.items():
+                if f"{cls_name}.{name}" in ov["exclude_members"]:
+                    continue
+                child = _type_name(m.type) if m.form == "property" else ""
+                if child and self.is_target_class(child):
+                    queue.append((prefix + name, child, f"{path}.{name}".lstrip("."),
+                                  {"parent": target}))
+            if cls.getitem:
+                value = _type_name(cls.getitem[1])
+                if value and self.is_target_class(value) and value not in self.class_target:
+                    elem = ov["element_names"].get(target, f"{target}[]")
+                    entry["element"] = elem
+                    queue.append((elem, value, f"{path}[]",
+                                  {"collection": target, "key": _expand(cls.getitem[0], self.aliases),
+                                   "subtype_field": ov["subtype_fields"].get(value)}))
+
+    def build(self) -> dict:
+        self.walk("solver", "Solver", "")
+        for root, spec in self.overrides["roots"].items():
+            self.walk(root, spec["class"], "", construct=spec["construct"])
+            ctor = set().union(*(self.c_by_member.get((spec["class"], d), set())
+                                 for d in ("__cinit__", "__init__", "__dealloc__")))
+            if ctor:
+                self.targets[root]["c"] = sorted(ctor)
+        for target, entry in self.targets.items():
+            self.add_members(target, entry)
+        for target, variants in self.overrides["variants"].items():
+            for cls_name in variants:
+                self.class_target.setdefault(cls_name, target)
+                for m in self.classes[cls_name].members.values():
+                    self.members.append(dict(self.member_entry(target, cls_name, m), variant=cls_name))
+        bulk = self.bulk_links()
+        by_path = {m["path"]: m for m in self.members}
+        for m in self.members:
+            if m["form"] == "property" and m["path"] in bulk:
+                m["bulk"] = bulk[m["path"]]
+                array = by_path[bulk[m["path"]]]
+                if "units" in m and "units" not in array:
+                    array["units"] = m["units"]
+        records = {name: {"fields": {k: _expand(v.type, self.aliases)
+                                     for k, v in c.members.items() if v.form == "property"},
+                          "doc": c.doc}
+                   for name, c in sorted(self.classes.items())
+                   if c.record or name in self.overrides["record_classes"]}
+        return {
+            "schema": SCHEMA,
+            "note": "Generated by python/scripts/gen_catalog.py -- do not edit by hand.",
+            "c_exports": len(_provenance.c_symbols()),
+            "targets": dict(sorted(self.targets.items())),
+            "members": sorted(self.members, key=lambda m: m["path"]),
+            "functions": {mod: {name: dict(fn, c=sorted(self.c_by_member.get(("", name), ())))
+                                for name, fn in sorted(f.items())}
+                          for mod, f in sorted(self.functions.items())
+                          if mod.lstrip("_") in self.overrides["function_modules"]},
+            "records": records,
+            "enums": dict(sorted(self.enums.items())),
+        }
+
+    def add_members(self, target: str, entry: dict) -> None:
+        cls_name = entry["class"]
+        cls = self.classes[cls_name]
+        ov = self.overrides
+        for name, m in cls.members.items():
+            if f"{cls_name}.{name}" in ov["exclude_members"]:
+                continue
+            child = _type_name(m.type) if m.form == "property" else ""
+            if child and self.is_target_class(child):
+                ref = self.class_target.get(child, "")
+                if ref and self.targets[ref].get("collection") and ref != target:
+                    # A reference to another element (e.g. a subcatchment's gage):
+                    # expose it as a value -- the referenced element's id.
+                    self.members.append(dict(self.member_entry(target, cls_name, m),
+                                             type=f"ref:{ref}"))
+                continue            # otherwise a navigable sub-target, not a value
+            self.members.append(self.member_entry(target, cls_name, m))
+        if cls.getitem and not entry.get("element"):
+            self.members.extend(self.item_members(target, cls))
+        elif any(b.startswith(MAPPING_BASES + SEQUENCE_BASES) for b in cls.bases):
+            self.members.extend(self.item_members(target, cls))
+        elif cls.iter_type and not entry.get("element"):
+            # Iterable but not indexable (Inlets, Aquifers): list it.
+            syms = set().union(*(self.c_by_member.get((cls_name, d), set())
+                                 for d in ("__iter__", "__len__", "__contains__")))
+            self.members.append({"path": f"{target}.items", "target": target, "name": "items",
+                                 "form": "item", "python": f"list({cls_name})", "doc": cls.doc,
+                                 "returns": f"list[tuple[int, {_expand(cls.iter_type, self.aliases)}]]",
+                                 "params": [], "c": sorted(syms)})
+        if entry.get("element"):
+            # Element collections are enumerated through len()/iteration by every tool.
+            syms = set().union(*(self.c_by_member.get((cls_name, d), set())
+                                 for d in ("__len__", "__iter__", "__getitem__", "__contains__")))
+            if syms:
+                entry["c"] = sorted(set(entry.get("c", [])) | syms)
+
+    def member_entry(self, target: str, cls_name: str, m: Member) -> dict:
+        prefix = "" if target == "solver" else target + "."
+        c_syms = sorted(self.c_by_member.get((cls_name, m.name), ()))
+        header = next((self.headers[s] for s in _rank_symbols(m.name, c_syms)
+                       if s in self.headers), {})
+        doc = self.pyx_docs.get((cls_name, m.name)) or m.doc or header.get("brief", "")
+        out = {"path": prefix + m.name, "target": target, "name": m.name, "form": m.form,
+               "python": f"{cls_name}.{m.name}", "doc": doc, "c": c_syms}
+        if m.form == "property":
+            out["type"] = _expand(m.type, self.aliases)
+            out["access"] = "rw" if (cls_name, m.name) in self.setters or m.stub_setter else "r"
+        else:
+            out["returns"] = _expand(m.type, self.aliases)
+            out["params"] = [dict(p, type=_expand(p["type"], self.aliases)) for p in m.params]
+            if m.static:
+                out["static"] = True
+        out["c"] = sorted(set(out["c"]) | self.returned_symbols(m.type))
+        units = ov_units = self.overrides["units"].get(prefix + m.name)
+        # Tuples mix quantities and ints are usually codes, so only plain
+        # floats and float arrays carry a single unit.
+        numeric = m.type == "float" or m.type.startswith("NDArray")
+        if ov_units is None and m.form == "property" and numeric:
+            units = header.get("units") or (_units(doc) if m.type == "float" else None)
+        if units:
+            out["units"] = units
+        phases = sorted({p for s in c_syms if s in self.headers for p in self.headers[s]["phases"]})
+        if phases:
+            out["phases"] = phases
+        return out
+
+    def returned_symbols(self, type_str: str) -> set[str]:
+        """C symbols of an uncatalogued object a member hands back.
+
+        ``OutputReader.node_stats`` returns an ``_OutputNodeStats`` whose
+        properties call the C API; serializing the result reaches them.
+        """
+        out: set[str] = set()
+        for name in re.findall(r"\b(_?[A-Z]\w*)\b", type_str or ""):
+            obj = self.classes.get(name)
+            if obj is None or name in self.class_target or name in self.enums:
+                continue
+            for d in [p for p, pm in obj.members.items() if pm.form == "property"] + \
+                    ["__len__", "__iter__", "__getitem__"]:
+                out |= self.c_by_member.get((name, d), set())
+        return out
+
+    def item_members(self, target: str, cls: Cls) -> list[dict]:
+        """Synthesize ``items``/``get_item``/``set_item``/``delete_item`` for mapping-like targets."""
+        key_t, val_t = cls.getitem or ("", "")
+        for b in cls.bases:
+            m = re.match(r"Mutable(?:Mapping|Sequence)\[(.*)\]", b)
+            if m:
+                parts = [p.strip() for p in m.group(1).split(",", 1)]
+                key_t, val_t = (parts[0], parts[1]) if len(parts) == 2 else ("int", parts[0])
+        mutable = cls.setitem or any(b.startswith("Mutable") for b in cls.bases)
+        key_t, val_t = _expand(key_t, self.aliases), _expand(val_t, self.aliases)
+        def syms(*defs: str) -> list[str]:
+            return sorted(set().union(*(self.c_by_member.get((cls.name, d), set()) for d in defs)))
+
+        base = {"target": target, "form": "item", "python": f"{cls.name}[]", "doc": cls.doc}
+        values = sorted(self.returned_symbols(val_t))
+        out = [dict(base, path=f"{target}.items", name="items", returns=f"list[tuple[{key_t}, {val_t}]]",
+                    params=[], c=sorted(set(syms("__iter__", "__len__", "__getitem__", "keys",
+                                                 "items", "values")) | set(values))),
+               dict(base, path=f"{target}.get_item", name="get_item", returns=val_t,
+                    params=[{"name": "key", "type": key_t, "required": True}],
+                    c=sorted(set(syms("__getitem__")) | set(values)))]
+        if mutable:
+            out.append(dict(base, path=f"{target}.set_item", name="set_item", returns="None",
+                            params=[{"name": "key", "type": key_t, "required": True},
+                                    {"name": "value", "type": val_t, "required": True}],
+                            c=syms("__setitem__")))
+        if cls.delitem or any(b.startswith("Mutable") for b in cls.bases):
+            out.append(dict(base, path=f"{target}.delete_item", name="delete_item", returns="None",
+                            params=[{"name": "key", "type": key_t, "required": True}],
+                            c=syms("__delitem__")))
+        return out
+
+    def bulk_links(self) -> dict[str, str]:
+        """Map an element property path to the collection array that holds it for every element."""
+        links: dict[str, str] = {}
+        for target, entry in self.targets.items():
+            elem = entry.get("element")
+            if not elem:
+                continue
+            coll = self.classes[entry["class"]]
+            elem_props = {m["name"] for m in self.members
+                          if m["target"] == elem and m["form"] == "property"}
+            for name, m in coll.members.items():
+                if m.form != "property" or "NDArray" not in m.type:
+                    continue
+                singular = name[:-3] + "y" if name.endswith("ies") else name
+                for cand in (name, singular, name[:-1], name[:-2]):
+                    if cand in elem_props and cand != "ids":
+                        links[f"{elem}.{cand}"] = f"{target}.{name}"
+                        break
+        return links
+
+    # -- completeness -------------------------------------------------------
+    def uncovered(self) -> list[str]:
+        """Public classes/members neither in the catalog nor excluded."""
+        covered_cls = {e["class"] for e in self.targets.values()}
+        missing = []
+        for name, cls in sorted(self.classes.items()):
+            if name.startswith("_") and name not in covered_cls:
+                continue
+            if cls.record or name in self.enums or name in self.overrides["exclude_classes"] \
+                    or name in self.overrides["record_classes"] or name in self.class_target:
+                continue
+            if name not in covered_cls:
+                missing.append(name)
+        return missing
+
+
+def unitless_floats(catalog: dict) -> list[str]:
+    """Float properties without a unit kind (``dimensionless`` counts as one)."""
+    return [m["path"] for m in catalog["members"]
+            if m["form"] == "property" and m.get("type") == "float" and "units" not in m]
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("--check", action="store_true",
+                    help="fail if catalog.json is stale, a class is uncovered, or a float field has no unit kind")
+    args = ap.parse_args(argv)
+    b = Builder()
+    catalog = b.build()
+    text = json.dumps(catalog, indent=1, ensure_ascii=False) + "\n"
+    missing = b.uncovered()
+    unitless = unitless_floats(catalog)
+    print(f"targets={len(catalog['targets'])} members={len(catalog['members'])} "
+          f"float fields without a unit kind={len(unitless)}")
+    problems = []
+    if missing:
+        problems.append("classes neither reachable nor excluded: " + ", ".join(missing))
+    if unitless:
+        problems.append("float fields without a unit kind (add one, or 'dimensionless', to "
+                        "catalog_overrides.json): " + ", ".join(unitless))
+    if args.check:
+        current = OUT_JSON.read_text(encoding="utf-8") if OUT_JSON.exists() else ""
+        if current != text:
+            problems.append(f"{OUT_JSON.relative_to(REPO)} is stale; run python/scripts/gen_catalog.py")
+    else:
+        OUT_JSON.write_text(text, encoding="utf-8")
+        print(f"wrote {OUT_JSON.relative_to(REPO)} ({len(text) // 1024} KiB)")
+    for p in problems:
+        print("ERROR:", p, file=sys.stderr)
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/python/scripts/stage_python_sources.py b/python/scripts/stage_python_sources.py
new file mode 100644
index 000000000..edaa4cd07
--- /dev/null
+++ b/python/scripts/stage_python_sources.py
@@ -0,0 +1,22 @@
+"""Copy Python modules/stubs into a CMake install prefix for package testing.
+
+CMake installs native modules; scikit-build normally adds these source files
+when producing a wheel. This helper supplies the same files for feature builds.
+"""
+from pathlib import Path
+import shutil
+import sys
+
+
+def main():
+    source = Path(__file__).resolve().parents[1] / 'openswmm'
+    destination = Path(sys.argv[1]).resolve() / 'openswmm'
+    for path in source.rglob('*'):
+        if path.is_file() and (path.suffix in ('.py', '.pyi') or path.name in ('py.typed', 'catalog.json')):
+            target = destination / path.relative_to(source)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(path, target)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/python/scripts/test_staged_package.py b/python/scripts/test_staged_package.py
new file mode 100644
index 000000000..9abf12e77
--- /dev/null
+++ b/python/scripts/test_staged_package.py
@@ -0,0 +1,30 @@
+"""Run pytest against a staged package using the active Python environment.
+
+Usage: conda run -n openswmm python python/scripts/test_staged_package.py STAGE [pytest args]
+
+Scikit-build editable imports override PYTHONPATH. Remove only OpenSWMM's
+redirector for this process, and assert the loaded native modules belong to
+STAGE. This does not modify the installed package or environment.
+"""
+from pathlib import Path
+import sys
+
+
+def main():
+    stage = Path(sys.argv[1]).resolve()
+    source = Path(__file__).resolve().parents[1]
+    sys.meta_path[:] = [finder for finder in sys.meta_path
+                       if type(finder).__module__ != "_openswmm_editable"]
+    sys.path[:0] = [str(stage), str(source)]
+    import openswmm.engine._solver as solver
+    assert Path(solver.__file__).is_relative_to(stage), solver.__file__
+    for name, module in tuple(sys.modules.items()):
+        if name.startswith("openswmm.") and getattr(module, "__file__", None):
+            assert Path(module.__file__).is_relative_to(stage), (name, module.__file__)
+    print(f"Python: {sys.executable}\nBindings: {solver.__file__}", flush=True)
+    import pytest
+    return pytest.main(["--import-mode=importlib", *sys.argv[2:]])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/python/tests/data/solver/non_existent_input_file.rpt b/python/tests/data/solver/non_existent_input_file.rpt
index 9c7828612..0011aa2fa 100644
--- a/python/tests/data/solver/non_existent_input_file.rpt
+++ b/python/tests/data/solver/non_existent_input_file.rpt
@@ -122,7 +122,6 @@
   *********************************
   Most Frequent Nonconverging Nodes
   *********************************
-  Node O1 (29.21%)
   Node J8 (28.48%)
   Node J5 (1.87%)
   Node J6 (0.73%)
@@ -2382,6 +2381,6 @@
    01/01/1998 01:00:00     56.517     9.549     1.748     0.334     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:37 2026
-  Analysis ended on:  Thu Jul  2 12:09:37 2026
+  Analysis begun on:  Mon Aug 17 08:41:06 2026
+  Analysis ended on:  Mon Aug 17 08:41:06 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example.rpt b/python/tests/data/solver/site_drainage_example.rpt
index 57f8678d0..26e781354 100644
--- a/python/tests/data/solver/site_drainage_example.rpt
+++ b/python/tests/data/solver/site_drainage_example.rpt
@@ -2381,6 +2381,6 @@
    01/01/1998 01:00:00    131.487    11.835     2.852     0.627     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:37 2026
-  Analysis ended on:  Thu Jul  2 12:09:37 2026
+  Analysis begun on:  Mon Aug 17 08:41:06 2026
+  Analysis ended on:  Mon Aug 17 08:41:06 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_link.rpt b/python/tests/data/solver/site_drainage_example_link.rpt
index 8a908c48a..443568624 100644
--- a/python/tests/data/solver/site_drainage_example_link.rpt
+++ b/python/tests/data/solver/site_drainage_example_link.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:34 2026
-  Analysis ended on:  Thu Jul  2 12:09:35 2026
-  Total elapsed time: 00:00:01
\ No newline at end of file
+  Analysis begun on:  Mon Aug 17 08:41:02 2026
+  Analysis ended on:  Mon Aug 17 08:41:02 2026
+  Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_node.rpt b/python/tests/data/solver/site_drainage_example_node.rpt
index 167c1526a..443568624 100644
--- a/python/tests/data/solver/site_drainage_example_node.rpt
+++ b/python/tests/data/solver/site_drainage_example_node.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:34 2026
-  Analysis ended on:  Thu Jul  2 12:09:34 2026
+  Analysis begun on:  Mon Aug 17 08:41:02 2026
+  Analysis ended on:  Mon Aug 17 08:41:02 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_outfall.rpt b/python/tests/data/solver/site_drainage_example_outfall.rpt
index 02cf556e2..4f5cdbe2d 100644
--- a/python/tests/data/solver/site_drainage_example_outfall.rpt
+++ b/python/tests/data/solver/site_drainage_example_outfall.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:35 2026
-  Analysis ended on:  Thu Jul  2 12:09:35 2026
+  Analysis begun on:  Mon Aug 17 08:41:03 2026
+  Analysis ended on:  Mon Aug 17 08:41:03 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_routing.rpt b/python/tests/data/solver/site_drainage_example_routing.rpt
index 02cf556e2..4f5cdbe2d 100644
--- a/python/tests/data/solver/site_drainage_example_routing.rpt
+++ b/python/tests/data/solver/site_drainage_example_routing.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:35 2026
-  Analysis ended on:  Thu Jul  2 12:09:35 2026
+  Analysis begun on:  Mon Aug 17 08:41:03 2026
+  Analysis ended on:  Mon Aug 17 08:41:03 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_runoff.rpt b/python/tests/data/solver/site_drainage_example_runoff.rpt
index b11106d47..bca7ab221 100644
--- a/python/tests/data/solver/site_drainage_example_runoff.rpt
+++ b/python/tests/data/solver/site_drainage_example_runoff.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:35 2026
-  Analysis ended on:  Thu Jul  2 12:09:36 2026
+  Analysis begun on:  Mon Aug 17 08:41:03 2026
+  Analysis ended on:  Mon Aug 17 08:41:04 2026
   Total elapsed time: 00:00:01
\ No newline at end of file
diff --git a/python/tests/data/solver/site_drainage_example_subcatch.rpt b/python/tests/data/solver/site_drainage_example_subcatch.rpt
index 167c1526a..443568624 100644
--- a/python/tests/data/solver/site_drainage_example_subcatch.rpt
+++ b/python/tests/data/solver/site_drainage_example_subcatch.rpt
@@ -11371,6 +11371,6 @@
    01/01/1998 06:00:00      0.006     1.038     0.011     0.000     0.000
   
 
-  Analysis begun on:  Thu Jul  2 12:09:34 2026
-  Analysis ended on:  Thu Jul  2 12:09:34 2026
+  Analysis begun on:  Mon Aug 17 08:41:02 2026
+  Analysis ended on:  Mon Aug 17 08:41:02 2026
   Total elapsed time: < 1 sec
\ No newline at end of file
diff --git a/python/tests/engine/_groundwater_cases.py b/python/tests/engine/_groundwater_cases.py
new file mode 100644
index 000000000..5b0f8e330
--- /dev/null
+++ b/python/tests/engine/_groundwater_cases.py
@@ -0,0 +1,63 @@
+"""Small mixed-cell model shared by groundwater and surface-quality tests."""
+from pathlib import Path
+
+from openswmm.engine import Solver
+
+MODEL = '''[OPTIONS]
+FLOW_UNITS CMS
+FLOW_ROUTING DYNWAVE
+START_DATE 01/01/2026
+START_TIME 00:00:00
+END_DATE 01/01/2026
+END_TIME 00:10:00
+REPORT_STEP 00:01:00
+WET_STEP 00:01:00
+ROUTING_STEP 5
+[POLLUTANTS]
+TSS MG/L 0 0 0 0
+[JUNCTIONS]
+J1 -2 4 0 0 0
+[OUTFALLS]
+O1 -2.5 FREE NO
+[CONDUITS]
+C1 J1 O1 30 0.013 0 0 0
+[XSECTIONS]
+C1 CIRCULAR 0.5 0 0 0 1
+[TIMESERIES]
+INPUT 0:00 0.5
+INPUT 1:00 0.5
+[2D_OPTIONS]
+INTEGRATOR EXPLICIT
+LTS_TIERS 2
+MAX_TIMESTEP 5
+DRY_DEPTH 0.001
+REPORT_2D NO
+RAINFALL_MODE SYSTEM
+[2D_VERTICES]
+0 0 0
+10 0 0
+10 10 0
+0 10 0
+20 0 0
+[2D_TRIANGLES]
+1 4 2 0.03 0.1 FAR
+[2D_QUADS]
+0 1 2 3 0.03 0.1 PAN
+[REPORT]
+INPUT NO
+'''
+
+
+def open_model(directory, extra=''):
+    path = Path(directory) / 'model.inp'
+    path.write_text(MODEL + '\n' + extra)
+    solver = Solver(path, path.with_suffix('.rpt'), path.with_suffix('.out'))
+    solver.open()
+    return solver
+
+
+def cleanup(solver):
+    try:
+        solver.close()
+    finally:
+        solver.destroy()
diff --git a/python/tests/engine/test_binding_completion.py b/python/tests/engine/test_binding_completion.py
new file mode 100644
index 000000000..a0c8bc4c2
--- /dev/null
+++ b/python/tests/engine/test_binding_completion.py
@@ -0,0 +1,212 @@
+"""Regression coverage for bulk editing, live output, staged writes and diagnostics."""
+from pathlib import Path
+import struct
+import numpy as np
+import pytest
+from openswmm.engine import (
+    ModelEditor, BadIndexError, BadHandleError, StaleObjectError,
+    LifecycleError, OutputReader, OutNodeVar, Surface2D, HeatElemKind,
+    ForcingType, ForcingMode,
+)
+from tests.engine._groundwater_cases import open_model, cleanup
+from tests.engine._solver_cases import EngineSolverCase
+
+
+class TestBulkEditAndLiveOutput(EngineSolverCase):
+    def test_batch_invalid_atomic_and_duplicates(self):
+        s = self.opened_solver()
+        editor = ModelEditor(s)
+        names = [n.id for n in s.nodes]
+        old = s.nodes[0]
+        with pytest.raises(BadIndexError):
+            editor.delete_nodes([0, 999999])
+        assert [n.id for n in s.nodes] == names
+        assert old.id == names[0]
+        impacts = editor.delete_nodes([names[0], 0])
+        assert isinstance(impacts, list)
+        assert editor.node_count == len(names) - 1
+        with pytest.raises(StaleObjectError):
+            _ = old.id
+        for method in (editor.delete_nodes, editor.delete_links, editor.delete_subcatchments, editor.delete_gages):
+            assert method([]) == []
+        s.destroy()
+        with pytest.raises(BadHandleError):
+            _ = editor.node_count
+
+    def test_report_snapshot_uses_live_diagnostics_and_percentages(self):
+        from openswmm.engine import get_report_snapshot, RunoffTotal, RoutingTotal
+        s = self.completed_solver()
+        report = get_report_snapshot(s)
+        mb = s.mass_balance
+        assert report.routing_diagnostics == mb.routing_diagnostics
+        assert report.routing_diagnostics.n_steps > 0
+        assert report.runoff_continuity.continuity_error_pct == pytest.approx(100 * mb.runoff_continuity_error)
+        assert report.routing_continuity.continuity_error_pct == pytest.approx(100 * mb.routing_continuity_error)
+        assert report.runoff_continuity.initial_snow == mb.runoff_total(RunoffTotal.INITSNOW)
+        assert report.runoff_continuity.final_snow == mb.runoff_total(RunoffTotal.FINALSNOW)
+        assert report.routing_continuity.forcing_inflow == mb.routing_total(RoutingTotal.FORCING_INFLOW)
+        assert report.routing_continuity.coupling_outflow == mb.routing_total(RoutingTotal.COUPLING_OUT)
+        assert report.routing_continuity.link_groundwater_inflow == mb.routing_total(RoutingTotal.LINK_GW_INFLOW)
+        for i, quality in enumerate(report.quality_continuity):
+            assert quality.continuity_error_pct == pytest.approx(100 * mb.quality_continuity_error(i))
+
+    def test_other_batch_deletions_validate_and_deduplicate(self):
+        for collection, method in [('links', 'delete_links'), ('subcatchments', 'delete_subcatchments'), ('gages', 'delete_gages')]:
+            s = self.opened_solver()
+            editor = ModelEditor(s)
+            objects = getattr(s, collection)
+            count = len(objects)
+            assert count > 0
+            name = objects[0].id
+            delete = getattr(editor, method)
+            with pytest.raises(BadIndexError):
+                delete([name, count + 10])
+            assert len(objects) == count
+            delete([name, 0])
+            assert len(getattr(s, collection)) == count - 1
+
+    def test_live_partial_period_refresh_and_footer(self):
+        self.completed_solver()
+        source = Path(self.solver_files()[2])
+        data = source.read_bytes()
+        _, _, start, periods, _, _ = struct.unpack('<6i', data[-24:])
+        size = (len(data) - 24 - start) // periods
+        live_path = source.with_name('binding_live.out')
+        live_path.write_bytes(data[:start])
+        with OutputReader(live_path, live=True) as live:
+            assert live.is_live and live.period_count == 0
+            assert len(live.period_times) == 0
+            with live_path.open('ab') as stream:
+                stream.write(data[start:start + size + size // 2])
+            assert live.refresh() == 1
+            assert len(live.period_times) == 1
+            with live_path.open('ab') as stream:
+                stream.write(data[start + size + size // 2:])
+            assert live.refresh() == periods
+            assert not live.is_live
+            assert len(live.period_times) == periods
+            with OutputReader(source) as finished:
+                np.testing.assert_array_equal(live.node_result(0, OutNodeVar.DEPTH), finished.node_result(0, OutNodeVar.DEPTH))
+        for read in (live.refresh, lambda: live.period_count, lambda: live.is_live):
+            with pytest.raises(BadHandleError):
+                read()
+
+
+def test_staged_writer_callback_contract(tmp_path):
+    solver = open_model(tmp_path)
+    try:
+        final = tmp_path / 'final.inp'
+        stage = tmp_path / 'stage.inp'
+        calls = []
+        def mapper(path, kind):
+            calls.append((path, kind))
+            return stage if kind == 0 else tmp_path / ('stage-' + Path(path).name)
+        solver.write_staged(final, mapper)
+        assert stage.exists() and not final.exists()
+        assert calls[0] == (str(final), 0)
+        sentinel = ValueError('mapper failed')
+        def fail(path, kind):
+            raise sentinel
+        with pytest.raises(ValueError) as error:
+            solver.write_staged(final, fail)
+        assert error.value is sentinel
+        with pytest.raises(LifecycleError):
+            solver.write_staged(final, lambda path, kind: solver.destroy())
+        assert solver.handle
+    finally:
+        cleanup(solver)
+
+
+def test_2d_diagnostics_and_forcing(tmp_path):
+    solver = open_model(tmp_path, "[OPTIONS]\nHEAT_TRANSPORT ON\nWATER_AGE ON\n")
+    try:
+        surface = solver.surface2d
+        assert Surface2D.output_variables()
+        for preset in ('ALL', 'DEFAULT', 'MINIMAL'):
+            mask = Surface2D.output_variable_mask(preset)
+            assert Surface2D.output_variable_mask(Surface2D.output_variable_text(mask)) == mask
+        with pytest.raises(ValueError):
+            Surface2D.output_variable_mask('NO_SUCH_VARIABLE')
+        solver.initialize()
+        solver.start(False)
+        forcing = solver.forcing
+        forcing.node_temperature('J1', 20)
+        forcing.node_age('J1', 1)
+        forcing.link_seepage('C1', 0)
+        forcing.element_climate(HeatElemKind.NODE, 'J1', ForcingType.ELEM_AIR_TEMPERATURE, 21, persist=True)
+        value, mode = forcing.element_climate_get(HeatElemKind.NODE, 'J1', ForcingType.ELEM_AIR_TEMPERATURE)
+        # SI input is stored as °F internally; (21*1.8+32-32)*5/9 is
+        # 21.000000000000007 unless the compiler fuses it into an FMA.
+        assert value == pytest.approx(21) and mode == ForcingMode.REPLACE
+        solver.step()
+        for read in (surface.get_rainfall_bulk, surface.get_rain_volume_bulk, surface.get_coupling_volume_bulk):
+            result = read()
+            assert result.shape == (2,) and np.isfinite(result).all()
+        method, indices, weights = surface.rainfall_weights(1)
+        assert method == -1 and indices.size == weights.size == 0
+        solver.end()
+    finally:
+        cleanup(solver)
+
+
+@pytest.mark.parametrize('units,rain', [('CMS', 36.0), ('CFS', 36.0 / 25.4)])
+def test_nonzero_rainfall_weights_and_volume_in_si(tmp_path, units, rain):
+    from openswmm.engine import Solver
+    from tests.engine._groundwater_cases import MODEL
+    path = tmp_path / 'rain.inp'
+    model = MODEL.replace('FLOW_UNITS CMS', 'FLOW_UNITS ' + units)
+    model = model.replace('WET_STEP 00:01:00', 'WET_STEP 00:00:01\nDRY_STEP 00:00:01').replace('ROUTING_STEP 5', 'ROUTING_STEP 1')
+    model = model.replace('RAINFALL_MODE SYSTEM', 'RAINFALL_MODE NEAREST_NEIGHBOUR')
+    path.write_text(model + f'''\n[RAINGAGES]
+RG INTENSITY 1:00 1 TIMESERIES RAIN
+[TIMESERIES]
+RAIN 01/01/2026 00:00 {rain}
+RAIN 01/01/2026 01:00 {rain}
+[SYMBOLS]
+RG 5 5
+''')
+    solver = Solver(path, tmp_path / 'rain.rpt')
+    try:
+        solver.open()
+        surface = solver.surface2d
+        solver.initialize()
+        solver.start(False)
+        for _ in range(10):
+            solver.step()
+        initial_volume = surface.get_rain_volume_bulk()
+        initial_time = solver.elapsed.total_seconds()
+        elapsed = solver.step().total_seconds() - initial_time
+        np.testing.assert_allclose(surface.get_rainfall_bulk(), [1e-5, 1e-5], rtol=1e-6)
+        for cell in range(2):
+            method, indices, weights = surface.rainfall_weights(cell)
+            assert method == 2
+            np.testing.assert_array_equal(indices, [0])
+            np.testing.assert_allclose(weights, [1])
+            assert surface.get_rainfall_bulk()[cell] == pytest.approx(surface.get_rainfall(cell))
+        area_scale = 0.3048 ** 2 if units == 'CFS' else 1
+        np.testing.assert_allclose(surface.get_rain_volume_bulk() - initial_volume,
+                                   np.array([50, 100]) * area_scale * 1e-5 * elapsed,
+                                   rtol=1e-5)
+        assert surface.get_coupling_volume_bulk().shape == (2,)
+        solver.end()
+    finally:
+        cleanup(solver)
+
+
+def test_geopackage_bulk_shapes_and_closed_handle(tmp_path):
+    from openswmm.engine import GeoPackage
+    with GeoPackage(str(tmp_path / 'observed.gpkg')) as database:
+        series = database.create_observed_series('rain', 'rainfall')
+        times = ['2026-01-01T00:00:00Z', '2026-01-01T00:01:00Z', '2026-01-01T00:02:00Z']
+        with pytest.raises(ValueError):
+            database.write_observed_values(series, times, [1])
+        with pytest.raises(ValueError):
+            database.write_observed_values(series, times, [1, 2, 3], ['A'])
+        database.write_observed_values(series, [], [])
+        values = np.arange(6, dtype=float)[::2]  # noncontiguous input must be copied
+        database.write_observed_values(series, times, values)
+        actual_times, actual = database.read_observed_values(series)
+        assert actual_times == times
+        np.testing.assert_array_equal(actual, values)
+    with pytest.raises(BadHandleError):
+        database.read_observed_values(series)
diff --git a/python/tests/engine/test_climate_pythonic.py b/python/tests/engine/test_climate_pythonic.py
index cfbcd776c..2fc909dd4 100644
--- a/python/tests/engine/test_climate_pythonic.py
+++ b/python/tests/engine/test_climate_pythonic.py
@@ -79,6 +79,7 @@ def test_array_roundtrip(self):
             ("evap_monthly", 12),
             ("pan_coeff", 12),
             ("wind_monthly", 12),
+            ("humidity_monthly", 12),
             ("adjust_temperature", 12),
             ("adjust_evaporation", 12),
             ("adjust_rainfall", 12),
diff --git a/python/tests/engine/test_concurrent_simulation.py b/python/tests/engine/test_concurrent_simulation.py
index 60eecc8fc..b7b33c260 100644
--- a/python/tests/engine/test_concurrent_simulation.py
+++ b/python/tests/engine/test_concurrent_simulation.py
@@ -12,9 +12,10 @@
      complete in less wall-clock time than the sum of their single-threaded
      runtimes — proving the GIL is genuinely released during ``step``.
   2. Bulk getters called concurrently from many threads against the same
-     solver must complete without deadlock, exception, or corruption (each
-     call writes into its own caller-allocated NumPy array; the C engine's
-     read of the state vectors is intrinsically thread-safe for reads).
+     solver must never deadlock or return corrupt data. One engine admits
+     one thread into its native layer at a time (``NativeAccess`` in
+     ``openswmm/engine/_access.py``); a second thread is refused promptly
+     with ``LifecycleError`` rather than blocking, and may retry.
   3. The wall-clock benefit of (1) is enough to be statistically detectable
      above noise. We require strictly *better* than serial, not a hard
      speedup ratio — busy CI machines and small fixtures suppress the
@@ -37,7 +38,7 @@
 import numpy as np
 import pytest
 
-from openswmm.engine import EngineState, Solver
+from openswmm.engine import EngineState, ErrorCode, LifecycleError, Solver
 
 from tests._paths import SITE_DRAINAGE_INP, artifact_dir
 from tests.engine._solver_cases import EngineSolverCase
@@ -251,14 +252,15 @@ def worker(side: str) -> None:
     @pytest.mark.slow
     def test_bulk_getters_concurrent_reads(self):
         """Many threads calling node/link/subcatch bulk getters on one ENDED
-        solver should not deadlock, raise, or return corrupt arrays.
-
-        Reading from an ENDED solver is safe because state vectors are
-        no longer being mutated. We check that *parallel* reads still
-        agree bit-for-bit with a *serial* baseline. (Concurrent reads
-        while the engine is mid-step are a separate question, not asserted
-        here — the bindings document the engine handle as not thread-safe
-        for concurrent mutation.)
+        solver must not deadlock, return corrupt arrays, or fail with
+        anything other than the documented busy refusal.
+
+        ``NativeAccess`` refuses a thread that arrives while another is
+        inside the native layer (``LifecycleError``, "in use by another
+        thread") instead of blocking — see
+        ``test_native_safety.test_foreign_thread_access_fails_without_deadlock``.
+        Readers therefore retry on that refusal, and every read that does
+        get through must agree bit-for-bit with a serial baseline.
         """
         inp, rpt, out = self.solver_files()
         s = Solver(inp, rpt, out)
@@ -277,16 +279,32 @@ def test_bulk_getters_concurrent_reads(self):
 
             N_THREADS = 8
             N_ITERS = 16
+            TIMEOUT_S = 60.0
+            deadline = time.monotonic() + TIMEOUT_S
             errors: list[BaseException] = []
 
+            def read(getter):
+                # A refusal means another reader holds the engine, so the
+                # pool as a whole always makes progress; the deadline only
+                # guards against a regression that never releases it.
+                while True:
+                    try:
+                        return getter()
+                    except LifecycleError as e:
+                        busy = (e.code == ErrorCode.LIFECYCLE
+                                and "in use by another thread" in e.message)
+                        if not busy or time.monotonic() > deadline:
+                            raise
+                        time.sleep(0.001)
+
             def reader() -> None:
                 try:
                     for _ in range(N_ITERS):
-                        nd = s.nodes.depths
-                        nh = s.nodes.heads
-                        lf = s.links.flows
-                        ld = s.links.depths
-                        sr = s.subcatchments.runoffs
+                        nd = read(lambda: s.nodes.depths)
+                        nh = read(lambda: s.nodes.heads)
+                        lf = read(lambda: s.links.flows)
+                        ld = read(lambda: s.links.depths)
+                        sr = read(lambda: s.subcatchments.runoffs)
                         np.testing.assert_array_equal(nd, baseline_node_depths)
                         np.testing.assert_array_equal(lf, baseline_link_flows)
                         np.testing.assert_array_equal(sr, baseline_runoff)
@@ -299,8 +317,10 @@ def reader() -> None:
             for t in threads:
                 t.start()
             for t in threads:
-                t.join()
+                t.join(timeout=max(0.0, deadline - time.monotonic()) + 5.0)
 
+            self.assertFalse([t for t in threads if t.is_alive()],
+                             "concurrent readers deadlocked")
             self.assertFalse(errors, f"concurrent reads raised: {errors[:3]}")
         finally:
             try:
diff --git a/python/tests/engine/test_enums.py b/python/tests/engine/test_enums.py
index 5785fe64e..d100e5344 100644
--- a/python/tests/engine/test_enums.py
+++ b/python/tests/engine/test_enums.py
@@ -5,6 +5,9 @@
 from openswmm.engine import (
     ErrorCode, EngineState, NodeType, LinkType,
     XSectShape, FlowUnits, RouteModel, WarnCode, ObjectType,
+    HeatFluxModule, HeatShortwaveMode, HeatRadiativeParam, HeatSolarParam,
+    HeatCloudParam, HeatSourceKind, WaterAgeSource,
+    ReactionScope, ReactionExprForm,
 )
 
 
@@ -199,26 +202,191 @@ def test_member_count(self):
         self.assertEqual(len(ObjectType), 13)
 
 
+# ---------------------------------------------------------------------------
+# HeatFluxModule
+# ---------------------------------------------------------------------------
+class TestHeatFluxModule(unittest.TestCase):
+    """Verify HeatFluxModule values (mirrors ``SWMM_HeatFluxModule``)."""
+
+    def test_known_values(self):
+        expected = {
+            "SURFACE_EXCHANGE": 0, "RADIATIVE_EXCHANGE": 1,
+            "LAYER_CONDUCTION": 2,
+        }
+        for name, val in expected.items():
+            self.assertEqual(HeatFluxModule[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatFluxModule), 3)
+
+
+# ---------------------------------------------------------------------------
+# HeatShortwaveMode
+# ---------------------------------------------------------------------------
+class TestHeatShortwaveMode(unittest.TestCase):
+    """Verify HeatShortwaveMode values (mirrors ``SWMM_HeatShortwaveMode``)."""
+
+    def test_known_values(self):
+        expected = {"CONSTANT": 0, "TIMESERIES": 1, "COMPUTED": 2}
+        for name, val in expected.items():
+            self.assertEqual(HeatShortwaveMode[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatShortwaveMode), 3)
+
+
+# ---------------------------------------------------------------------------
+# HeatRadiativeParam
+# ---------------------------------------------------------------------------
+class TestHeatRadiativeParam(unittest.TestCase):
+    """Verify HeatRadiativeParam values (mirrors ``SWMM_HeatRadiativeParam``)."""
+
+    def test_known_values(self):
+        expected = {
+            "SHORTWAVE": 0, "ALBEDO": 1, "SHADE_FACTOR": 2, "SKY_VIEW": 3,
+            "EMISS_WATER": 4, "EMISS_LANDCOVER": 5, "ATM_EMISS_COEFF": 6,
+            "LW_REFLECTION": 7,
+        }
+        for name, val in expected.items():
+            self.assertEqual(HeatRadiativeParam[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatRadiativeParam), 8)
+
+
+# ---------------------------------------------------------------------------
+# HeatSolarParam
+# ---------------------------------------------------------------------------
+class TestHeatSolarParam(unittest.TestCase):
+    """Verify HeatSolarParam values (mirrors ``SWMM_HeatSolarParam``)."""
+
+    def test_known_values(self):
+        expected = {
+            "LATITUDE": 0, "LONGITUDE": 1, "TIMEZONE": 2, "ELEVATION": 3,
+            "TURBIDITY_380": 4, "TURBIDITY_500": 5, "PRECIP_WATER": 6,
+            "OZONE": 7, "GROUND_ALBEDO": 8,
+        }
+        for name, val in expected.items():
+            self.assertEqual(HeatSolarParam[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatSolarParam), 9)
+
+
+# ---------------------------------------------------------------------------
+# HeatCloudParam
+# ---------------------------------------------------------------------------
+class TestHeatCloudParam(unittest.TestCase):
+    """Verify HeatCloudParam values (mirrors ``SWMM_HeatCloudParam``)."""
+
+    def test_known_values(self):
+        expected = {
+            "FRACTION": 0, "SW_ATTEN_K": 1, "SW_ATTEN_N": 2,
+            "LW_CLOUD_K": 3,
+        }
+        for name, val in expected.items():
+            self.assertEqual(HeatCloudParam[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatCloudParam), 4)
+
+
+# ---------------------------------------------------------------------------
+# HeatSourceKind
+# ---------------------------------------------------------------------------
+class TestHeatSourceKind(unittest.TestCase):
+    """Verify HeatSourceKind values (mirrors ``SWMM_HeatSourceKind``)."""
+
+    def test_known_values(self):
+        expected = {
+            "RAINFALL": 0, "DWF": 1, "GW": 2, "RDII": 3,
+            "EXTERNAL_INFLOW": 4, "IFACE": 5, "INITIAL_STATE": 6,
+        }
+        for name, val in expected.items():
+            self.assertEqual(HeatSourceKind[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(HeatSourceKind), 7)
+
+
+# ---------------------------------------------------------------------------
+# WaterAgeSource
+# ---------------------------------------------------------------------------
+class TestWaterAgeSource(unittest.TestCase):
+    """Verify WaterAgeSource values (mirrors ``SWMM_WaterAgeSource``)."""
+
+    def test_known_values(self):
+        expected = {
+            "RAINFALL": 0, "DWF": 1, "GW": 2, "RDII": 3,
+            "EXTERNAL_INFLOW": 4, "IFACE": 5, "INITIAL_STATE": 6,
+        }
+        for name, val in expected.items():
+            self.assertEqual(WaterAgeSource[name].value, val)
+
+    def test_member_count(self):
+        # SEVEN, not eight: the C enum's trailing ``SWMM_AGE_SRC_COUNT = 7``
+        # sentinel is deliberately NOT reproduced as a Python member —
+        # ``len(WaterAgeSource)`` is the count, so a sentinel member would
+        # both double-count and show up in iteration as a fake pathway.
+        self.assertEqual(len(WaterAgeSource), 7)
+
+    def test_count_sentinel_is_not_a_member(self):
+        self.assertNotIn("COUNT", WaterAgeSource.__members__)
+
+
+# ---------------------------------------------------------------------------
+# ReactionScope
+# ---------------------------------------------------------------------------
+class TestReactionScope(unittest.TestCase):
+    """Verify ReactionScope values (mirrors the ``SWMM_RXN_SCOPE_*`` macros)."""
+
+    def test_known_values(self):
+        expected = {"TERM": 0, "PIPE": 1, "TANK": 2}
+        for name, val in expected.items():
+            self.assertEqual(ReactionScope[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(ReactionScope), 3)
+
+
+# ---------------------------------------------------------------------------
+# ReactionExprForm
+# ---------------------------------------------------------------------------
+class TestReactionExprForm(unittest.TestCase):
+    """Verify ReactionExprForm values (mirrors the ``SWMM_RXN_FORM_*`` macros)."""
+
+    def test_known_values(self):
+        expected = {"NONE": 0, "RATE": 1, "EQUIL": 2, "FORMULA": 3}
+        for name, val in expected.items():
+            self.assertEqual(ReactionExprForm[name].value, val)
+
+    def test_member_count(self):
+        self.assertEqual(len(ReactionExprForm), 4)
+
+
 # ---------------------------------------------------------------------------
 # Cross-cutting
 # ---------------------------------------------------------------------------
+_ALL_ENUMS = (
+    ErrorCode, EngineState, NodeType, LinkType,
+    XSectShape, FlowUnits, RouteModel, WarnCode, ObjectType,
+    HeatFluxModule, HeatShortwaveMode, HeatRadiativeParam, HeatSolarParam,
+    HeatCloudParam, HeatSourceKind, WaterAgeSource,
+    ReactionScope, ReactionExprForm,
+)
+
+
 class TestEnumsCrossCutting(unittest.TestCase):
     """General properties all enums should satisfy."""
 
     def test_all_members_are_int(self):
-        for enum_cls in (
-            ErrorCode, EngineState, NodeType, LinkType,
-            XSectShape, FlowUnits, RouteModel, WarnCode, ObjectType,
-        ):
+        for enum_cls in _ALL_ENUMS:
             with self.subTest(enum_cls=enum_cls):
                 for member in enum_cls:
                     self.assertIsInstance(member.value, int)
 
     def test_values_are_unique(self):
-        for enum_cls in (
-            ErrorCode, EngineState, NodeType, LinkType,
-            XSectShape, FlowUnits, RouteModel, WarnCode, ObjectType,
-        ):
+        for enum_cls in _ALL_ENUMS:
             with self.subTest(enum_cls=enum_cls):
                 vals = [e.value for e in enum_cls]
                 self.assertEqual(len(vals), len(set(vals)),
diff --git a/python/tests/engine/test_forcing_climate.py b/python/tests/engine/test_forcing_climate.py
index 5c47e710a..7ed9a9dd6 100644
--- a/python/tests/engine/test_forcing_climate.py
+++ b/python/tests/engine/test_forcing_climate.py
@@ -19,6 +19,17 @@
 observed is attributable to the forcing alone. Snowmelt-response tests
 require a snowpack fixture and are tracked as follow-up work in the plan.
 
+The temperature baseline is the 70 deg F the ClimateState NSDMI carries.
+672d99ef ("fix(climate): report sys.TEMPERATURE as legacy does") once zeroed
+it at init, but 39370ef8 restored the legacy default: project.c:941 leaves
+Temp.ta = 70.0 and climate.c's setTemp reassigns it only for
+FILE_TEMP/TSERIES_TEMP, so a deck with no [TEMPERATURE] section both computes
+and reports with 70. The raw 0 legacy reports is narrower than 672d99ef
+assumed: it comes from SYS_TEMPERATURE being assigned only inside
+output_saveSubcatchResults, which is the has_subcatchments guard at the
+snapshot, not the state default. This model has subcatchments, so these
+assertions see 70.
+
 @author: Caleb Buahin
 """
 
@@ -36,7 +47,9 @@
 _INP = os.path.join(_DATA_DIR, "site_drainage_example.inp")
 _OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
 
-_DEFAULT_TEMP_F = 70.0   # ClimateState default when no source is present
+# Legacy parity: 70, the value project_setDefaults leaves in Temp.ta — see the
+# module docstring and SWMMEngine.cpp's temp_source == 0 branch.
+_DEFAULT_TEMP_F = 70.0   # effective default when no source is present
 _DEFAULT_WIND = 0.0
 
 # Climate state (temperature/wind/evap) is refreshed on the runoff clock, not
diff --git a/python/tests/engine/test_forcing_quality.py b/python/tests/engine/test_forcing_quality.py
index c45d35eb6..87bd6f4e2 100644
--- a/python/tests/engine/test_forcing_quality.py
+++ b/python/tests/engine/test_forcing_quality.py
@@ -49,6 +49,13 @@ def _quality_model(cgw=50.0, cdwf=100.0, tag="dwf"):
     text = re.sub(r'^IGNORE_QUALITY\s+\S+', 'IGNORE_QUALITY       NO',
                   text, count=1, flags=re.MULTILINE)
     text = text + _pollutants(cgw, cdwf)
+    # The derived copy is written to _OUT_DIR, so the base model's *relative*
+    # FILE tokens (e.g. [TIMESERIES] ... FILE "dir/series.dat") would resolve
+    # against _OUT_DIR instead of the model folder. Anchor them to the original
+    # model's directory so the derived copy references the same files.
+    _base_dir = os.path.dirname(_DWF_INP).replace("\\", "/")
+    text = re.sub(r'(FILE\s+")(?![/\\]|[A-Za-z]:)',
+                  lambda m: m.group(1) + _base_dir + "/", text)
     path = os.path.join(_OUT_DIR, f"quality_{tag}.inp")
     with open(path, "w") as f:
         f.write(text)
diff --git a/python/tests/engine/test_geopackage_export.py b/python/tests/engine/test_geopackage_export.py
index c1e402c23..476d31728 100644
--- a/python/tests/engine/test_geopackage_export.py
+++ b/python/tests/engine/test_geopackage_export.py
@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 import os
+from pathlib import Path
 import sqlite3
 import struct
 import unittest
@@ -47,6 +48,7 @@ def test_write_geopackage_with_crs(self):
         gpkg = os.path.join(artifact_dir(self), "model.gpkg")
         n_nodes = len(solver.nodes)
 
+        Path(gpkg).unlink(missing_ok=True)  # each run creates a fresh fixture
         solver.write_geopackage(gpkg, crs="EPSG:2284")
 
         # CRS landed on the spatial frame (the field the writer reads).
@@ -84,6 +86,7 @@ def test_write_with_plugin_explicit_id(self):
         solver = self.opened_solver()
         gpkg = os.path.join(artifact_dir(self), "model2.gpkg")
         solver.spatial.crs = "EPSG:4326"
+        Path(gpkg).unlink(missing_ok=True)
         solver.write_with_plugin(gpkg, GEOPACKAGE_PLUGIN_ID)
         con = sqlite3.connect(gpkg)
         try:
diff --git a/python/tests/engine/test_groundwater.py b/python/tests/engine/test_groundwater.py
new file mode 100644
index 000000000..b342b3898
--- /dev/null
+++ b/python/tests/engine/test_groundwater.py
@@ -0,0 +1,92 @@
+"""Mixed-cell aquifer authoring, lifecycle, units and snapshot regressions."""
+import numpy as np
+import pytest
+from openswmm.engine import (
+    CellScope, GroundwaterClosure, GroundwaterVariable, GroundwaterLedger,
+    BadParamError, LifecycleError, StaleObjectError,
+)
+from tests.engine._groundwater_cases import open_model, cleanup
+
+
+def test_groundwater_authoring_and_roundtrip(tmp_path):
+    solver = open_model(tmp_path)
+    try:
+        gw = solver.surface2d.groundwater
+        assert not gw.active
+        assert gw.rows == ()
+        gw.options['NODE_ENROLMENT'] = 'ROWS'
+        assert gw.options['NODE_ENROLMENT'] == 'ROWS'
+        gw.add_row(CellScope.GLOBAL, 36, 0.5, 0.45, 0.1, 2)
+        gw.set_row_property(0, 'HG0', 0.2)
+        gw.add_row(CellScope.TAG, 18, 0.6, 0.4, 0.1, 1, tag='PAN')
+        assert gw.rows[1].tag == 'PAN'
+        gw.remove_row(1)
+        assert gw.rows[0].ks == 36  # authored mm/hr, not converted to m/s
+        assert gw.row_property(0, 'HG0') == 0.2
+        gw.add_node('J1', -1, 36, 0.1, 0.5)
+        assert gw.nodes[0].locate
+        assert not gw.nodes[0].automatic
+        gw.set_node_exchange(0, False)
+        assert not gw.nodes[0].exchange
+        gw.remove_node(0)
+        assert gw.nodes == ()
+        with pytest.raises(BadParamError):
+            gw.set_row_property(0, 'NO_SUCH_PROPERTY', 1)
+        saved = tmp_path / 'saved.inp'
+        solver.write(saved)
+        from openswmm.engine import Solver
+        reopened = Solver(saved, tmp_path / 'saved.rpt')
+        try:
+            reopened.open()
+            assert reopened.surface2d.groundwater.rows == gw.rows
+            assert reopened.surface2d.groundwater.row_property(0, 'HG0') == 0.2
+        finally:
+            cleanup(reopened)
+        solver.close()
+        with pytest.raises(StaleObjectError):
+            _ = gw.rows
+    finally:
+        cleanup(solver)
+
+
+@pytest.mark.parametrize('sigma', [False, True])
+def test_groundwater_runtime_mixed_cells(tmp_path, sigma):
+    solver = open_model(tmp_path)
+    try:
+        gw = solver.surface2d.groundwater
+        gw.options['NODE_ENROLMENT'] = 'ROWS'
+        gw.add_row(CellScope.GLOBAL, 36, 0.5, 0.45, 0.1, 2)
+        gw.set_row_property(0, 'HG0', 0.2)
+        if sigma:
+            gw.options['M_LAYERS'] = '4'
+            gw.set_row_property(0, 'CLOSURE', GroundwaterClosure.SIGMA)
+            gw.set_row_property(0, 'M_LAYERS', 4)
+        with pytest.raises(LifecycleError):
+            gw.cells(GroundwaterVariable.HG)
+        solver.initialize()
+        solver.start(False)
+        solver.step()
+        assert gw.active
+        assert gw.dimensions[0] == 2  # one triangle plus one quad
+        values = gw.cells(GroundwaterVariable.HG)
+        assert values.shape == (2,)
+        assert values.dtype == np.float64
+        assert np.isfinite(values).all()
+        assert values[0] == pytest.approx(gw.cell(0, GroundwaterVariable.HG))
+        values[:] = -999
+        assert gw.cell(0, GroundwaterVariable.HG) >= 0  # independent snapshot
+        assert gw.ledger(GroundwaterLedger.STORAGE) >= 0
+        assert abs(gw.continuity_error) < 1e-7
+        assert gw.tier_histogram.dtype == np.dtype('l')
+        assert gw.tier_histogram.ndim == 1
+        assert isinstance(gw.species, tuple)
+        if sigma:
+            assert gw.column(0).shape == (4,)
+        else:
+            with pytest.raises(BadParamError):
+                gw.column(0)
+        with pytest.raises(LifecycleError):
+            gw.add_row(CellScope.GLOBAL, 1, 1, 0.4, 0.1, 1)
+        solver.end()
+    finally:
+        cleanup(solver)
diff --git a/python/tests/engine/test_heat.py b/python/tests/engine/test_heat.py
new file mode 100644
index 000000000..8f8c4dc69
--- /dev/null
+++ b/python/tests/engine/test_heat.py
@@ -0,0 +1,587 @@
+"""Round-trips and documented refusals for ``solver.heat`` (``_heat.pyx``).
+
+Covers:
+  * ``heat.enabled`` — the ``[OPTIONS] HEAT_TRANSPORT`` toggle.
+  * ``heat.modules`` — the ``[HEAT_FLUXES]`` module toggles as a mapping.
+  * ``heat.radiative`` — the ``[RADIATIVE_FLUXES]`` scalar parameters.
+  * ``heat.shortwave_mode`` / ``set_shortwave_timeseries`` /
+    ``current_shortwave`` — the three mutually exclusive shortwave sources.
+  * ``heat.solar`` / ``heat.solar_sited`` — ``[SOLAR_RADIATION]``.
+  * ``heat.cloud`` — ``[CLOUD_COVER]`` plus ``configured`` / ``current`` /
+    ``set_timeseries`` / ``clear``.
+  * ``heat.sources`` — the ``[HEAT_SOURCES]`` GLOBAL inlet temperatures,
+    ``is_configured``, ``clear`` and ``effective``.
+  * ``heat.node_overrides`` — the NODE-scope override rows.
+  * The documented refusals, each asserting *refused, not clamped*: the
+    value is read back after the refusal and must be unchanged.
+
+The model is authored inline because ``site_drainage_model.inp`` carries no
+``[HEAT_*]`` sections at all. Both the ``.inp`` and its ``.heat`` component
+config, and every report/output file, land in ``tests/engine/output`` so a
+user can review them after a run.
+
+@author: Caleb Buahin
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from openswmm.engine import (
+    BadParamError,
+    HeatCloudParam,
+    HeatFluxModule,
+    HeatNodeOverride,
+    HeatRadiativeParam,
+    HeatShortwaveMode,
+    HeatSolarParam,
+    HeatSourceKind,
+)
+
+from tests.engine._solver_cases import EngineSolverCase
+
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
+
+#: Component id the engine registers the heat coordinator under
+#: (``kHeatId`` in ``src/engine/transport/components/HeatModule/
+#: HeatComponent.cpp``).
+_HEAT_COMPONENT = "org.hydrocouple.openswmm.heat"
+
+
+def _heat_model(tag):
+    """Write a heat-enabled ``.inp`` plus its ``.heat`` config; return the .inp.
+
+    Section spellings are the engine's own: ``[HEAT_SOURCES]``,
+    ``[HEAT_FLUXES]``, ``[RADIATIVE_FLUXES]``, ``[SOLAR_RADIATION]`` and
+    ``[CLOUD_COVER]`` are parsed by ``HeatComponent.cpp``; the component is
+    bound to the deck through ``[PROCESS_COMPONENTS]  config="…"``.
+
+    ``[SOLAR_RADIATION]`` is deliberately **absent** so ``solar_sited`` is
+    False on a freshly opened model — that is the precondition the
+    ``HeatShortwaveMode.COMPUTED`` refusal test needs.
+    """
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    heat_name = f"heat_{tag}.heat"
+
+    heat_cfg = (
+        "[HEAT_SOURCES]\n"
+        "DWF             GLOBAL  15.0\n"
+        "INITIAL_STATE   GLOBAL  20.0\n"
+        "DWF             NODE    J1  22.0\n"
+        "\n[HEAT_FLUXES]\n"
+        "RADIATIVE_EXCHANGE  ON\n"
+        "\n[RADIATIVE_FLUXES]\n"
+        "SHORTWAVE  GLOBAL  250.0\n"
+        "\n[CLOUD_COVER]\n"
+        "FRACTION  GLOBAL  0.25\n"
+    )
+    with open(os.path.join(_OUT_DIR, heat_name), "w") as f:
+        f.write(heat_cfg)
+
+    text = (
+        "[TITLE]\n"
+        "Python heat-binding round-trip deck\n"
+        "\n[OPTIONS]\n"
+        "FLOW_UNITS           CFS\n"
+        "FLOW_ROUTING         DYNWAVE\n"
+        "HEAT_TRANSPORT       ON\n"
+        "START_DATE           06/21/2026\n"
+        "START_TIME           12:00:00\n"
+        "END_DATE             06/21/2026\n"
+        "END_TIME             12:10:00\n"
+        "ROUTING_STEP         10\n"
+        "REPORT_STEP          00:05:00\n"
+        "\n[TEMPERATURE]\n"
+        "TIMESERIES  air_ts\n"
+        "HUMIDITY    50.0\n"
+        "\n[TIMESERIES]\n"
+        "air_ts    06/21/2026 00:00 50.0\n"
+        "air_ts    06/22/2026 00:00 50.0\n"
+        "sw_ts     06/21/2026 00:00 700.0\n"
+        "sw_ts     06/22/2026 00:00 700.0\n"
+        "cloud_ts  06/21/2026 00:00 0.5\n"
+        "cloud_ts  06/22/2026 00:00 0.5\n"
+        "\n[JUNCTIONS]\n"
+        ";;Name Elev MaxDepth InitDepth SurDepth Aponded\n"
+        "J1  9.0  10  1.0  0  0\n"
+        "J2  8.5  10  1.0  0  0\n"
+        "\n[OUTFALLS]\n"
+        "OUT  8.0  FREE  NO\n"
+        "\n[CONDUITS]\n"
+        "C1  J1  J2   500  0.013  0  0  0\n"
+        "C2  J2  OUT  500  0.013  0  0  0\n"
+        "\n[XSECTIONS]\n"
+        "C1  CIRCULAR  3.0  0  0  0\n"
+        "C2  CIRCULAR  3.0  0  0  0\n"
+        "\n[PROCESS_COMPONENTS]\n"
+        f'{_HEAT_COMPONENT} config="{heat_name}"\n'
+        "\n[REPORT]\n"
+        "INPUT NO\n"
+    )
+    path = os.path.join(_OUT_DIR, f"heat_{tag}.inp")
+    with open(path, "w") as f:
+        f.write(text)
+    return path
+
+
+class _HeatCase(EngineSolverCase):
+    """``EngineSolverCase`` bound to the inline heat deck.
+
+    Overriding :meth:`solver_files` is all it takes: every lifecycle factory
+    (``opened_solver`` / ``initialized_solver`` / ``running_solver``) then
+    builds a per-test deck and registers its own ``addCleanup``.
+    """
+
+    def solver_files(self):
+        # Class AND method: several classes share a method name (e.g.
+        # ``test_container_protocol``), and the method name alone would put
+        # two tests on the same deck file.
+        tag = "_".join(self.id().split(".")[-2:])
+        inp = _heat_model(tag)
+        base = os.path.splitext(inp)[0]
+        return inp, base + ".rpt", base + ".out"
+
+
+# ---------------------------------------------------------------------------
+# Toggles and module mapping
+# ---------------------------------------------------------------------------
+class TestHeatToggles(_HeatCase):
+
+    def test_enabled_reflects_option(self):
+        s = self.opened_solver()
+        self.assertTrue(s.heat.enabled)
+
+    def test_modules_container_protocol(self):
+        s = self.opened_solver()
+        mods = s.heat.modules
+        self.assertEqual(len(mods), len(HeatFluxModule))
+        self.assertEqual(list(mods), list(HeatFluxModule))
+        # The deck turned radiative exchange on and left the others off.
+        self.assertTrue(mods[HeatFluxModule.RADIATIVE_EXCHANGE])
+        self.assertFalse(mods[HeatFluxModule.SURFACE_EXCHANGE])
+        self.assertIsInstance(repr(mods), str)
+
+    def test_module_roundtrip_by_member_code_and_name(self):
+        s = self.opened_solver()
+        mods = s.heat.modules
+        for key in (HeatFluxModule.SURFACE_EXCHANGE,
+                    int(HeatFluxModule.LAYER_CONDUCTION),
+                    "RADIATIVE_EXCHANGE"):
+            with self.subTest(key=key):
+                mods[key] = True
+                self.assertTrue(mods[key])
+                mods[key] = False
+                self.assertFalse(mods[key])
+
+    def test_unknown_module_key_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.heat.modules["NOT_A_MODULE"]
+        with self.assertRaises(KeyError):
+            s.heat.modules[99] = True
+
+
+# ---------------------------------------------------------------------------
+# [RADIATIVE_FLUXES]
+# ---------------------------------------------------------------------------
+class TestHeatRadiative(_HeatCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        rad = s.heat.radiative
+        self.assertEqual(len(rad), len(HeatRadiativeParam))
+        self.assertEqual(list(rad), list(HeatRadiativeParam))
+        self.assertIsInstance(repr(rad), str)
+
+    def test_shortwave_roundtrip_in_constant_mode(self):
+        s = self.opened_solver()
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+        self.assertAlmostEqual(s.heat.radiative[HeatRadiativeParam.SHORTWAVE],
+                               250.0)
+        s.heat.radiative[HeatRadiativeParam.SHORTWAVE] = 312.5
+        self.assertAlmostEqual(s.heat.radiative[HeatRadiativeParam.SHORTWAVE],
+                               312.5)
+
+    def test_fraction_params_roundtrip(self):
+        s = self.opened_solver()
+        rad = s.heat.radiative
+        fractions = [p for p in HeatRadiativeParam
+                     if p is not HeatRadiativeParam.SHORTWAVE]
+        for i, param in enumerate(fractions):
+            value = 0.10 + 0.05 * i
+            with self.subTest(param=param):
+                rad[param] = value
+                self.assertAlmostEqual(rad[param], value)
+                # The same key spelled as a name and as a code agree.
+                self.assertAlmostEqual(rad[param.name], value)
+                self.assertAlmostEqual(rad[int(param)], value)
+
+    def test_fraction_out_of_range_is_refused_not_clamped(self):
+        s = self.opened_solver()
+        rad = s.heat.radiative
+        rad[HeatRadiativeParam.ALBEDO] = 0.08
+        for bad in (1.5, -0.01):
+            with self.subTest(bad=bad):
+                with self.assertRaises(BadParamError):
+                    rad[HeatRadiativeParam.ALBEDO] = bad
+                # Refused, not clamped: the previous value survives.
+                self.assertAlmostEqual(rad[HeatRadiativeParam.ALBEDO], 0.08)
+
+    def test_negative_shortwave_is_refused_not_clamped(self):
+        s = self.opened_solver()
+        rad = s.heat.radiative
+        with self.assertRaises(BadParamError):
+            rad[HeatRadiativeParam.SHORTWAVE] = -1.0
+        self.assertAlmostEqual(rad[HeatRadiativeParam.SHORTWAVE], 250.0)
+
+    def test_shortwave_write_refused_outside_constant_mode(self):
+        """A constant is not read under TIMESERIES, so storing one is refused."""
+        s = self.opened_solver()
+        rad = s.heat.radiative
+        before = rad[HeatRadiativeParam.SHORTWAVE]
+        s.heat.set_shortwave_timeseries("sw_ts")
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.TIMESERIES)
+        with self.assertRaises(BadParamError):
+            rad[HeatRadiativeParam.SHORTWAVE] = 999.0
+        # Refused, not clamped, and not half-applied either.
+        self.assertAlmostEqual(rad[HeatRadiativeParam.SHORTWAVE], before)
+        # Switching the mode back makes the same write legal.
+        s.heat.shortwave_mode = HeatShortwaveMode.CONSTANT
+        rad[HeatRadiativeParam.SHORTWAVE] = 999.0
+        self.assertAlmostEqual(rad[HeatRadiativeParam.SHORTWAVE], 999.0)
+
+
+# ---------------------------------------------------------------------------
+# Shortwave mode
+# ---------------------------------------------------------------------------
+class TestHeatShortwaveMode(_HeatCase):
+
+    def test_timeseries_binding_switches_mode(self):
+        s = self.opened_solver()
+        s.heat.set_shortwave_timeseries("sw_ts")
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.TIMESERIES)
+        s.heat.shortwave_mode = HeatShortwaveMode.CONSTANT
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+        # Round-trip through the name and the code spellings too.
+        s.heat.shortwave_mode = "TIMESERIES"
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.TIMESERIES)
+        s.heat.shortwave_mode = int(HeatShortwaveMode.CONSTANT)
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+
+    def test_unknown_timeseries_refused(self):
+        s = self.opened_solver()
+        with self.assertRaises(BadParamError):
+            s.heat.set_shortwave_timeseries("no_such_series")
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+
+    def test_computed_requires_latitude_and_longitude(self):
+        """COMPUTED before the site is set is refused, and refused cleanly."""
+        s = self.opened_solver()
+        self.assertFalse(s.heat.solar_sited)
+        with self.assertRaises(BadParamError):
+            s.heat.shortwave_mode = HeatShortwaveMode.COMPUTED
+        # Refused, not applied: the previous mode is still in effect.
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+
+        # Latitude alone is still not a site.
+        s.heat.solar[HeatSolarParam.LATITUDE] = 41.74
+        self.assertFalse(s.heat.solar_sited)
+        with self.assertRaises(BadParamError):
+            s.heat.shortwave_mode = HeatShortwaveMode.COMPUTED
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.CONSTANT)
+
+        # Both coordinates: now the mode is reachable.
+        s.heat.solar[HeatSolarParam.LONGITUDE] = -111.83
+        self.assertTrue(s.heat.solar_sited)
+        s.heat.shortwave_mode = HeatShortwaveMode.COMPUTED
+        self.assertEqual(s.heat.shortwave_mode, HeatShortwaveMode.COMPUTED)
+
+    def test_current_shortwave_is_readable_state(self):
+        s = self.opened_solver()
+        self.assertIsInstance(s.heat.current_shortwave, float)
+
+
+# ---------------------------------------------------------------------------
+# [SOLAR_RADIATION]
+# ---------------------------------------------------------------------------
+class TestHeatSolar(_HeatCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        solar = s.heat.solar
+        self.assertEqual(len(solar), len(HeatSolarParam))
+        self.assertEqual(list(solar), list(HeatSolarParam))
+        self.assertIsInstance(repr(solar), str)
+
+    def test_roundtrip(self):
+        s = self.opened_solver()
+        solar = s.heat.solar
+        expected = {
+            HeatSolarParam.LATITUDE: 41.74,
+            HeatSolarParam.LONGITUDE: -111.83,
+            HeatSolarParam.TIMEZONE: -7.0,
+            HeatSolarParam.ELEVATION: -430.0,   # below sea level is legal
+            HeatSolarParam.TURBIDITY_380: 0.15,
+            HeatSolarParam.TURBIDITY_500: 0.10,
+            HeatSolarParam.PRECIP_WATER: 1.4,
+            HeatSolarParam.OZONE: 0.3,
+            HeatSolarParam.GROUND_ALBEDO: 0.2,
+        }
+        for param, value in expected.items():
+            with self.subTest(param=param):
+                solar[param] = value
+                self.assertAlmostEqual(solar[param], value)
+
+    def test_out_of_range_is_refused_not_clamped(self):
+        s = self.opened_solver()
+        solar = s.heat.solar
+        solar[HeatSolarParam.LATITUDE] = 41.74
+        with self.assertRaises(BadParamError):
+            solar[HeatSolarParam.LATITUDE] = 120.0
+        self.assertAlmostEqual(solar[HeatSolarParam.LATITUDE], 41.74)
+
+    def test_ground_albedo_fraction_refused_not_clamped(self):
+        s = self.opened_solver()
+        solar = s.heat.solar
+        solar[HeatSolarParam.GROUND_ALBEDO] = 0.2
+        with self.assertRaises(BadParamError):
+            solar[HeatSolarParam.GROUND_ALBEDO] = 1.4
+        self.assertAlmostEqual(solar[HeatSolarParam.GROUND_ALBEDO], 0.2)
+
+
+# ---------------------------------------------------------------------------
+# [CLOUD_COVER]
+# ---------------------------------------------------------------------------
+class TestHeatCloud(_HeatCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        cloud = s.heat.cloud
+        self.assertEqual(len(cloud), len(HeatCloudParam))
+        self.assertEqual(list(cloud), list(HeatCloudParam))
+        self.assertIsInstance(repr(cloud), str)
+
+    def test_roundtrip_and_configured(self):
+        s = self.opened_solver()
+        cloud = s.heat.cloud
+        self.assertTrue(cloud.configured)
+        self.assertAlmostEqual(cloud[HeatCloudParam.FRACTION], 0.25)
+        for param, value in ((HeatCloudParam.FRACTION, 0.6),
+                             (HeatCloudParam.SW_ATTEN_K, 0.75),
+                             (HeatCloudParam.SW_ATTEN_N, 3.4),
+                             (HeatCloudParam.LW_CLOUD_K, 0.30)):
+            with self.subTest(param=param):
+                cloud[param] = value
+                self.assertAlmostEqual(cloud[param], value)
+        self.assertTrue(cloud.configured)
+
+    def test_current_is_readable_state(self):
+        s = self.opened_solver()
+        self.assertIsInstance(s.heat.cloud.current, float)
+
+    def test_set_timeseries_marks_configured(self):
+        s = self.opened_solver()
+        s.heat.cloud.set_timeseries("cloud_ts")
+        self.assertTrue(s.heat.cloud.configured)
+
+    def test_unknown_timeseries_refused(self):
+        s = self.opened_solver()
+        with self.assertRaises(BadParamError):
+            s.heat.cloud.set_timeseries("no_such_series")
+
+    def test_clear_restores_clear_sky(self):
+        s = self.opened_solver()
+        self.assertTrue(s.heat.cloud.configured)
+        s.heat.cloud.clear()
+        self.assertFalse(s.heat.cloud.configured)
+
+    def test_fraction_out_of_range_is_refused_not_clamped(self):
+        """FRACTION is a fraction, not a percent — a 75 must not become 1.0."""
+        s = self.opened_solver()
+        cloud = s.heat.cloud
+        with self.assertRaises(BadParamError):
+            cloud[HeatCloudParam.FRACTION] = 75.0
+        self.assertAlmostEqual(cloud[HeatCloudParam.FRACTION], 0.25)
+        with self.assertRaises(BadParamError):
+            cloud[HeatCloudParam.FRACTION] = -0.5
+        self.assertAlmostEqual(cloud[HeatCloudParam.FRACTION], 0.25)
+
+    def test_negative_coefficient_is_refused_not_clamped(self):
+        s = self.opened_solver()
+        cloud = s.heat.cloud
+        cloud[HeatCloudParam.LW_CLOUD_K] = 0.30
+        with self.assertRaises(BadParamError):
+            cloud[HeatCloudParam.LW_CLOUD_K] = -0.1
+        self.assertAlmostEqual(cloud[HeatCloudParam.LW_CLOUD_K], 0.30)
+
+
+# ---------------------------------------------------------------------------
+# [HEAT_SOURCES] — GLOBAL temperatures
+# ---------------------------------------------------------------------------
+class TestHeatSources(_HeatCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        self.assertEqual(len(src), len(HeatSourceKind))
+        self.assertEqual(list(src), list(HeatSourceKind))
+        self.assertIn(HeatSourceKind.DWF, src)
+        self.assertIn("EXTERNAL_INFLOW", src)
+        self.assertIn(0, src)
+        self.assertNotIn("NOT_A_SOURCE", src)
+        self.assertIsInstance(repr(src), str)
+
+    def test_parsed_values_and_configured_flags(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        self.assertAlmostEqual(src[HeatSourceKind.DWF], 15.0)
+        self.assertAlmostEqual(src[HeatSourceKind.INITIAL_STATE], 20.0)
+        self.assertTrue(src.is_configured(HeatSourceKind.DWF))
+        # An unset source reads the 20 degC default but is NOT configured.
+        self.assertFalse(src.is_configured(HeatSourceKind.RAINFALL))
+        self.assertAlmostEqual(src[HeatSourceKind.RAINFALL], 20.0)
+
+    def test_roundtrip_every_source(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        for i, kind in enumerate(HeatSourceKind):
+            value = -10.0 + 3.5 * i
+            with self.subTest(kind=kind):
+                src[kind] = value
+                self.assertAlmostEqual(src[kind], value)
+                self.assertAlmostEqual(src[kind.name], value)
+                self.assertAlmostEqual(src[int(kind)], value)
+                self.assertTrue(src.is_configured(kind))
+
+    def test_clear_restores_default_and_keeps_node_overrides(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        self.assertEqual(len(s.heat.node_overrides), 1)
+        src.clear(HeatSourceKind.DWF)
+        self.assertFalse(src.is_configured(HeatSourceKind.DWF))
+        self.assertAlmostEqual(src[HeatSourceKind.DWF], 20.0)
+        # NODE overrides are separate rows; clear() must not delete them.
+        self.assertEqual(len(s.heat.node_overrides), 1)
+        self.assertAlmostEqual(src.effective(HeatSourceKind.DWF, "J1"), 22.0)
+
+    def test_effective_resolves_override_then_global(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        self.assertAlmostEqual(src.effective(HeatSourceKind.DWF, "J1"), 22.0)
+        self.assertAlmostEqual(src.effective(HeatSourceKind.DWF, "J2"), 15.0)
+        # Node index and node id address the same node.
+        j1 = s.nodes["J1"].index
+        self.assertAlmostEqual(src.effective(HeatSourceKind.DWF, j1), 22.0)
+
+    def test_out_of_range_temperature_is_refused_not_clamped(self):
+        """The parser's [-50, 100] degC range, enforced identically here."""
+        s = self.opened_solver()
+        src = s.heat.sources
+        for bad in (100.5, -50.5):
+            with self.subTest(bad=bad):
+                with self.assertRaises(BadParamError):
+                    src[HeatSourceKind.DWF] = bad
+                # Refused, not clamped: still the deck's 15 degC.
+                self.assertAlmostEqual(src[HeatSourceKind.DWF], 15.0)
+
+    def test_range_endpoints_are_accepted(self):
+        s = self.opened_solver()
+        src = s.heat.sources
+        for good in (-50.0, 100.0):
+            with self.subTest(good=good):
+                src[HeatSourceKind.GW] = good
+                self.assertAlmostEqual(src[HeatSourceKind.GW], good)
+
+    def test_unknown_source_key_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.heat.sources["NOT_A_SOURCE"]
+
+
+# ---------------------------------------------------------------------------
+# [HEAT_SOURCES] — NODE overrides
+# ---------------------------------------------------------------------------
+class TestHeatNodeOverrides(_HeatCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        rows = s.heat.node_overrides
+        self.assertEqual(len(rows), 1)
+        row = rows[0]
+        self.assertIsInstance(row, HeatNodeOverride)
+        self.assertEqual(row.source, HeatSourceKind.DWF)
+        self.assertEqual(row.node_index, s.nodes["J1"].index)
+        self.assertAlmostEqual(row.temp_c, 22.0)
+        self.assertEqual(rows[-1], row)
+        self.assertEqual(list(rows), [row])
+        self.assertIsInstance(repr(rows), str)
+
+    def test_index_out_of_range(self):
+        s = self.opened_solver()
+        with self.assertRaises(IndexError):
+            s.heat.node_overrides[5]
+
+    def test_set_updates_rather_than_duplicates(self):
+        s = self.opened_solver()
+        rows = s.heat.node_overrides
+        rows.set(HeatSourceKind.DWF, "J1", 25.5)
+        self.assertEqual(len(rows), 1)
+        self.assertAlmostEqual(rows[0].temp_c, 25.5)
+
+    def test_set_appends_a_new_pair_and_remove_shifts(self):
+        s = self.opened_solver()
+        rows = s.heat.node_overrides
+        rows.set(HeatSourceKind.EXTERNAL_INFLOW, "J2", 12.0)
+        self.assertEqual(len(rows), 2)
+        added = rows[1]
+        self.assertEqual(added.source, HeatSourceKind.EXTERNAL_INFLOW)
+        self.assertEqual(added.node_index, s.nodes["J2"].index)
+        self.assertAlmostEqual(added.temp_c, 12.0)
+        rows.remove(0)
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0], added)   # later rows shifted down
+
+    def test_scope_rule_refuses_non_dwf_non_external(self):
+        """Only DWF and EXTERNAL_INFLOW take NODE scope (the H1 rule)."""
+        s = self.opened_solver()
+        rows = s.heat.node_overrides
+        before = len(rows)
+        for kind in (HeatSourceKind.RAINFALL, HeatSourceKind.GW,
+                     HeatSourceKind.RDII, HeatSourceKind.IFACE,
+                     HeatSourceKind.INITIAL_STATE):
+            with self.subTest(kind=kind):
+                with self.assertRaises(BadParamError):
+                    rows.set(kind, "J2", 18.0)
+                # Refused, not deferred: no row was written.
+                self.assertEqual(len(rows), before)
+
+    def test_override_temperature_range_is_refused_not_clamped(self):
+        s = self.opened_solver()
+        rows = s.heat.node_overrides
+        with self.assertRaises(BadParamError):
+            rows.set(HeatSourceKind.DWF, "J1", 250.0)
+        self.assertEqual(len(rows), 1)
+        self.assertAlmostEqual(rows[0].temp_c, 22.0)
+
+    def test_unknown_node_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.heat.node_overrides.set(HeatSourceKind.DWF, "NOPE", 20.0)
+
+
+# ---------------------------------------------------------------------------
+# Repr
+# ---------------------------------------------------------------------------
+class TestHeatRepr(_HeatCase):
+
+    def test_repr_does_not_raise(self):
+        s = self.opened_solver()
+        for view in (s.heat, s.heat.modules, s.heat.radiative, s.heat.solar,
+                     s.heat.cloud, s.heat.sources, s.heat.node_overrides):
+            with self.subTest(view=type(view).__name__):
+                self.assertIsInstance(repr(view), str)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_initial_quality.py b/python/tests/engine/test_initial_quality.py
new file mode 100644
index 000000000..02e1a6ecc
--- /dev/null
+++ b/python/tests/engine/test_initial_quality.py
@@ -0,0 +1,295 @@
+"""Round-trips and documented refusals for ``solver.initial_quality``.
+
+Covers:
+  * The ``[INITIAL_QUALITY]`` row table as a sequence — ``len``, iteration,
+    positional and negative indexing, ``repr``.
+  * ``set`` upsert semantics keyed on ``(is_link, elem_index, constituent)``:
+    setting the same key twice updates in place, it does not append.
+  * The reserved constituents ``InitialQuality.WATER_AGE`` and
+    ``InitialQuality.TEMPERATURE``, whose values are signed.
+  * The documented refusals: a **negative pollutant** value, an unknown
+    constituent, an unknown element, and passing neither/both of
+    ``node=`` / ``link=``.
+  * ``remove`` shifting every later row down by one.
+
+The model is authored inline because ``site_drainage_model.inp`` carries no
+``[INITIAL_QUALITY]`` section. The ``.inp`` and every report/output file
+land in ``tests/engine/output`` so a user can review them after a run.
+
+@author: Caleb Buahin
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from openswmm.engine import (
+    BadIndexError,
+    BadParamError,
+    InitialQuality,
+    InitialQualityEntry,
+)
+
+from tests.engine._solver_cases import EngineSolverCase
+
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
+
+
+def _initial_quality_model(tag):
+    """Write an ``.inp`` carrying ``[INITIAL_QUALITY]`` rows; return its path.
+
+    The row spelling is ``NODE|LINK   `` — the
+    form ``InpWriter.cpp`` emits and ``PostParseResolver.cpp`` resolves.
+    ``HEAT_TRANSPORT`` is deliberately left OFF, so the ``__TEMPERATURE__``
+    row exercises the engine's warn-and-keep path (stored, classified,
+    warned, inert) exactly as the C++ gate deck does.
+    """
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    text = (
+        "[TITLE]\n"
+        "Python initial-quality binding round-trip deck\n"
+        "\n[OPTIONS]\n"
+        "FLOW_UNITS           CFS\n"
+        "FLOW_ROUTING         DYNWAVE\n"
+        "WATER_AGE            YES\n"
+        "START_DATE           01/01/2026\n"
+        "START_TIME           00:00:00\n"
+        "END_DATE             01/01/2026\n"
+        "END_TIME             00:30:00\n"
+        "ROUTING_STEP         5\n"
+        "REPORT_STEP          00:05:00\n"
+        "\n[JUNCTIONS]\n"
+        ";;Name Elev MaxDepth InitDepth SurDepth Aponded\n"
+        "J0  10.0  10  0.5  0  0\n"
+        "J1   9.0  10  0.5  0  0\n"
+        "J2   9.5  10  0.5  0  0\n"
+        "\n[OUTFALLS]\n"
+        "OUT  7.0  FREE  NO\n"
+        "\n[CONDUITS]\n"
+        "C1  J0  J1   400  0.013  0  0  0\n"
+        "C2  J1  OUT  400  0.013  0  0  0\n"
+        "C3  J2  J1   400  0.013  0  0  0\n"
+        "\n[XSECTIONS]\n"
+        "C1  CIRCULAR  1.5  0  0  0\n"
+        "C2  CIRCULAR  1.5  0  0  0\n"
+        "C3  CIRCULAR  1.5  0  0  0\n"
+        "\n[POLLUTANTS]\n"
+        ";;Name Units Crain Cgw Crdii Kdecay SnowOnly CoPollut CoFrac Cdwf Cinit\n"
+        "TSS   MG/L  0.0  0.0  0.0  0.0  NO  *  0.0  0.0  5.0\n"
+        "\n[INITIAL_QUALITY]\n"
+        ";;Scope Element Constituent Value\n"
+        "NODE  J1  TSS              12.5\n"
+        "NODE  J0  __WATER_AGE__     6.0\n"
+        "LINK  C2  __TEMPERATURE__  18.5\n"
+        "\n[REPORT]\n"
+        "INPUT NO\n"
+    )
+    path = os.path.join(_OUT_DIR, f"initial_quality_{tag}.inp")
+    with open(path, "w") as f:
+        f.write(text)
+    return path
+
+
+class _InitialQualityCase(EngineSolverCase):
+    """``EngineSolverCase`` bound to the inline [INITIAL_QUALITY] deck."""
+
+    def solver_files(self):
+        # Class AND method, so a method name reused by another class can
+        # never put two tests on the same deck file.
+        tag = "_".join(self.id().split(".")[-2:])
+        inp = _initial_quality_model(tag)
+        base = os.path.splitext(inp)[0]
+        return inp, base + ".rpt", base + ".out"
+
+
+# ---------------------------------------------------------------------------
+# Container protocol
+# ---------------------------------------------------------------------------
+class TestInitialQualityContainer(_InitialQualityCase):
+
+    def test_reserved_constituent_names(self):
+        self.assertEqual(InitialQuality.WATER_AGE, "__WATER_AGE__")
+        self.assertEqual(InitialQuality.TEMPERATURE, "__TEMPERATURE__")
+
+    def test_parsed_rows(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        self.assertEqual(len(iq), 3)
+        rows = list(iq)
+        self.assertEqual(len(rows), 3)
+        for row in rows:
+            self.assertIsInstance(row, InitialQualityEntry)
+
+        first = iq[0]
+        self.assertFalse(first.is_link)
+        self.assertEqual(first.elem_index, s.nodes["J1"].index)
+        self.assertEqual(first.constituent, "TSS")
+        self.assertAlmostEqual(first.value, 12.5)
+
+        second = iq[1]
+        self.assertEqual(second.constituent, InitialQuality.WATER_AGE)
+        self.assertEqual(second.elem_index, s.nodes["J0"].index)
+        self.assertAlmostEqual(second.value, 6.0)
+
+        third = iq[2]
+        self.assertTrue(third.is_link)
+        self.assertEqual(third.elem_index, s.links["C2"].index)
+        self.assertEqual(third.constituent, InitialQuality.TEMPERATURE)
+        self.assertAlmostEqual(third.value, 18.5)
+
+    def test_negative_index_and_range(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        self.assertEqual(iq[-1], iq[2])
+        with self.assertRaises(IndexError):
+            iq[3]
+        with self.assertRaises(IndexError):
+            iq[-4]
+
+    def test_repr_does_not_raise(self):
+        s = self.opened_solver()
+        self.assertIsInstance(repr(s.initial_quality), str)
+
+
+# ---------------------------------------------------------------------------
+# set() round-trips and upsert semantics
+# ---------------------------------------------------------------------------
+class TestInitialQualitySet(_InitialQualityCase):
+
+    def test_node_pollutant_roundtrip(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        iq.set("TSS", 20.0, node="J2")
+        self.assertEqual(len(iq), 4)
+        added = iq[-1]
+        self.assertFalse(added.is_link)
+        self.assertEqual(added.elem_index, s.nodes["J2"].index)
+        self.assertEqual(added.constituent, "TSS")
+        self.assertAlmostEqual(added.value, 20.0)
+
+    def test_link_pollutant_roundtrip(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        iq.set("TSS", 0.25, link="C1")
+        added = iq[-1]
+        self.assertTrue(added.is_link)
+        self.assertEqual(added.elem_index, s.links["C1"].index)
+        self.assertAlmostEqual(added.value, 0.25)
+
+    def test_element_may_be_named_or_indexed(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        iq.set("TSS", 7.0, node=s.nodes["J2"].index)
+        self.assertAlmostEqual(iq[-1].value, 7.0)
+        self.assertEqual(iq[-1].elem_index, s.nodes["J2"].index)
+
+    def test_upsert_updates_in_place(self):
+        """The same (scope, element, constituent) key is an EDIT, not a row."""
+        s = self.opened_solver()
+        iq = s.initial_quality
+        before = len(iq)
+        iq.set("TSS", 33.0, node="J1")
+        self.assertEqual(len(iq), before)
+        self.assertAlmostEqual(iq[0].value, 33.0)
+        # And again, to prove it is not a one-shot.
+        iq.set("TSS", 34.0, node="J1")
+        self.assertEqual(len(iq), before)
+        self.assertAlmostEqual(iq[0].value, 34.0)
+
+    def test_negative_water_age_is_accepted(self):
+        """__WATER_AGE__ is signed (hours) — a negative must NOT be refused."""
+        s = self.opened_solver()
+        iq = s.initial_quality
+        iq.set(InitialQuality.WATER_AGE, -4.0, node="J0")
+        self.assertAlmostEqual(iq[1].value, -4.0)
+        iq.set(InitialQuality.WATER_AGE, -0.5, link="C1")
+        self.assertAlmostEqual(iq[-1].value, -0.5)
+
+    def test_negative_temperature_is_accepted(self):
+        """__TEMPERATURE__ is degC — sub-zero is a real temperature."""
+        s = self.opened_solver()
+        iq = s.initial_quality
+        iq.set(InitialQuality.TEMPERATURE, -3.5, link="C2")
+        self.assertAlmostEqual(iq[2].value, -3.5)
+        iq.set(InitialQuality.TEMPERATURE, -12.0, node="J2")
+        self.assertAlmostEqual(iq[-1].value, -12.0)
+
+
+# ---------------------------------------------------------------------------
+# Refusals
+# ---------------------------------------------------------------------------
+class TestInitialQualityRefusals(_InitialQualityCase):
+
+    def test_negative_pollutant_value_refused(self):
+        """A concentration may not be negative — refused, and nothing stored."""
+        s = self.opened_solver()
+        iq = s.initial_quality
+        before = len(iq)
+        with self.assertRaises(BadParamError):
+            iq.set("TSS", -1.0, node="J2")
+        self.assertEqual(len(iq), before)
+
+    def test_negative_pollutant_upsert_leaves_value_unchanged(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        with self.assertRaises(BadParamError):
+            iq.set("TSS", -0.1, node="J1")
+        # Refused, not clamped: the existing row keeps the deck's value.
+        self.assertAlmostEqual(iq[0].value, 12.5)
+
+    def test_unknown_constituent_refused(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        before = len(iq)
+        with self.assertRaises(BadParamError):
+            iq.set("NOT_A_POLLUTANT", 1.0, node="J1")
+        self.assertEqual(len(iq), before)
+
+    def test_unknown_element_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.initial_quality.set("TSS", 1.0, node="NOPE")
+        with self.assertRaises(KeyError):
+            s.initial_quality.set("TSS", 1.0, link="NOPE")
+
+    def test_neither_or_both_scopes_is_a_value_error(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        with self.assertRaises(ValueError):
+            iq.set("TSS", 1.0)
+        with self.assertRaises(ValueError):
+            iq.set("TSS", 1.0, node="J1", link="C1")
+
+    def test_remove_out_of_range_refused(self):
+        s = self.opened_solver()
+        with self.assertRaises(BadIndexError):
+            s.initial_quality.remove(99)
+
+
+# ---------------------------------------------------------------------------
+# remove()
+# ---------------------------------------------------------------------------
+class TestInitialQualityRemove(_InitialQualityCase):
+
+    def test_remove_shifts_later_rows_down(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        before = list(iq)
+        self.assertEqual(len(before), 3)
+        iq.remove(0)
+        after = list(iq)
+        self.assertEqual(len(after), 2)
+        self.assertEqual(after, before[1:])
+
+    def test_remove_all_rows(self):
+        s = self.opened_solver()
+        iq = s.initial_quality
+        while len(iq):
+            iq.remove(0)
+        self.assertEqual(len(iq), 0)
+        self.assertEqual(list(iq), [])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_inlet_api.py b/python/tests/engine/test_inlet_api.py
new file mode 100644
index 000000000..ee14edb08
--- /dev/null
+++ b/python/tests/engine/test_inlet_api.py
@@ -0,0 +1,119 @@
+"""Street-inlet Python API smoke tests against ``examples/inlets/street_inlet_junction.inp``.
+
+Covers the bindings added with the inlet-junction work: ``Inlets.get_design``
+(including the fixed-buffer ``curve_id`` -> ``str`` conversion), the
+``InletUsages`` view, ``Node.is_inlet`` and ``ModelEditor.fuse_inlet_junction``,
+plus a write/reopen round trip.  Written decks land in ``output/inlet_api/``
+next to this file so a failure can be inspected.
+"""
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from openswmm.engine import (
+    Infrastructure, InletHostKind, InletType, ModelEditor, Nodes, Solver,
+)
+
+_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+_INP = os.path.join(_REPO_ROOT, "examples", "inlets", "street_inlet_junction.inp")
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output", "inlet_api")
+
+pytestmark = pytest.mark.skipif(not os.path.exists(_INP), reason="example deck not present")
+
+
+def _open(inp: str, tag: str) -> Solver:
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    s = Solver(inp, os.path.join(_OUT_DIR, tag + ".rpt"), os.path.join(_OUT_DIR, tag + ".out"))
+    s.open()
+    return s
+
+
+def _section(text: str, name: str) -> list[str]:
+    rows, on = [], False
+    for ln in text.splitlines():
+        st = ln.strip()
+        if st.startswith("["):
+            on = st.upper() == f"[{name}]"
+            continue
+        if on and st and not st.startswith(";"):
+            rows.append(st.split())
+    return rows
+
+
+def test_combo_design_carries_both_grate_and_curb() -> None:
+    s = _open(_INP, "design")
+    try:
+        inlets = Infrastructure(s).inlets
+        assert set(inlets) >= {"Grate1", "Curb1", "Combo1", "Custom1"}
+        d = inlets.get_design("Combo1")
+        assert d["type"] == InletType.COMBO
+        assert (d["grate_length"], d["grate_width"]) == pytest.approx((2.0, 2.0))
+        assert (d["curb_length"], d["curb_height"]) == pytest.approx((3.0, 0.5))
+        custom = inlets.get_design("Custom1")
+        assert custom["type"] == InletType.CUSTOM
+        assert custom["curve_id"] == "DIV_CAP"          # char[64] -> str, no padding
+        assert isinstance(custom["curve_id"], str)
+    finally:
+        s.close()
+
+
+def test_usage_view_and_inlet_junction_flag() -> None:
+    s = _open(_INP, "usage")
+    try:
+        infra, nodes = Infrastructure(s), Nodes(s)
+        usages = list(infra.inlet_usages)
+        assert len(usages) == 2
+        kinds = {u["host_kind"] for u in usages}
+        assert kinds == {InletHostKind.LINK, InletHostKind.NODE}
+        ij1 = nodes["IJ1"]
+        assert ij1.is_inlet is True
+        assert ij1.is_virtual is True
+        assert nodes["MH2"].is_inlet is False
+        node_row = next(u for u in usages if u["host_kind"] == InletHostKind.NODE)
+        assert node_row["host_idx"] == ij1.index
+        assert nodes[node_row["capture_node_idx"]].id == "MH2"
+        assert infra.inlet_usages.find_node(ij1.index) >= 0
+    finally:
+        s.close()
+
+
+def test_write_reopen_keeps_inlet_junction() -> None:
+    s = _open(_INP, "rt1")
+    try:
+        path = os.path.join(_OUT_DIR, "roundtrip.inp")
+        s.write(path)
+    finally:
+        s.close()
+    text = open(path, encoding="utf-8").read()
+    assert [r[0] for r in _section(text, "INLET_JUNCTIONS")] == ["IJ1"]
+    assert "IJ1" not in {r[0] for r in _section(text, "JUNCTIONS")}
+    assert "IJ1" not in {r[0] for r in _section(text, "VIRTUAL_JUNCTIONS")}
+    assert [r[:3] for r in _section(text, "INLET_USAGE")] == [["ST_A", "Combo1", "MH1"]]
+    s2 = _open(path, "rt2")
+    try:
+        assert Nodes(s2)["IJ1"].is_inlet is True
+        assert len(Infrastructure(s2).inlet_usages) == 2
+    finally:
+        s2.close()
+
+
+def test_fuse_inlet_junction_merges_the_street() -> None:
+    s = _open(_INP, "fuse")
+    try:
+        ModelEditor(s).fuse_inlet_junction("IJ1")
+        assert "IJ1" not in Nodes(s)
+        assert len(Infrastructure(s).inlet_usages) == 1     # ST_A's conduit inlet survives
+        path = os.path.join(_OUT_DIR, "fused.inp")
+        s.write(path)
+    finally:
+        s.close()
+    text = open(path, encoding="utf-8").read()
+    assert _section(text, "INLET_JUNCTIONS") == []
+    conduits = {r[0]: r for r in _section(text, "CONDUITS")}
+    assert "ST_A" in conduits
+    survivors = {"ST_B", "ST_C"} & set(conduits)          # ST_B + ST_C fused into one
+    assert len(survivors) == 1
+    assert conduits[survivors.pop()][1:3] == ["J_MID", "OUT_ST"]
+    assert [r[:3] for r in _section(text, "INLET_USAGE")] == [["ST_A", "Combo1", "MH1"]]
diff --git a/python/tests/engine/test_metadata_bindings.py b/python/tests/engine/test_metadata_bindings.py
new file mode 100644
index 000000000..f031c9567
--- /dev/null
+++ b/python/tests/engine/test_metadata_bindings.py
@@ -0,0 +1,106 @@
+"""Round trips for model metadata added to the public native API."""
+from pathlib import Path
+import tempfile
+
+import pytest
+from openswmm.engine import Solver, InpProfile
+from openswmm.legacy.engine import _solver as legacy
+from tests.engine._solver_cases import EngineSolverCase
+
+
+class TestMetadataBindings(EngineSolverCase):
+    def test_initial_quality_sidecar_provenance(self):
+        solver = self.opened_solver()
+        quality = solver.initial_quality
+        node = solver.nodes.get_id(0)
+        pollutant = solver.pollutants.get_id(0)
+        quality.set(pollutant, 2.0, node=node)
+        assert not quality.is_file(-1)
+        with pytest.raises(IndexError):
+            quality.is_file(100000)
+        with tempfile.TemporaryDirectory() as directory:
+            sidecar = Path(directory) / 'quality.csv'
+            sidecar_node = solver.nodes.get_id(1)
+            sidecar.write_text(f'NODE,{sidecar_node},{pollutant},7.0\n')
+            quality.file_path = str(sidecar)
+            assert quality.file_path == str(sidecar)
+            assert quality[-1].value == 2.0  # setting the reference does not reload it
+            model = Path(directory) / 'model.inp'
+            solver.write(model)
+            loaded = Solver(model, Path(directory) / 'model.rpt')
+            try:
+                loaded.open()
+                rows = loaded.initial_quality
+                assert any(rows.is_file(i) and rows[i].value == 7.0 for i in range(len(rows)))
+            finally:
+                loaded.close()
+                loaded.destroy()
+        quality.file_path = None
+        assert quality.file_path == ''
+
+    def test_heat_timeseries_readback(self):
+        solver = self.opened_solver()
+        series = solver.tables.add_timeseries('PY_CLIMATE_SERIES')
+        series.add(solver.start_datetime, 0.5)
+        heat = solver.heat
+        assert heat.shortwave_timeseries == ''
+        assert heat.cloud.timeseries == ''
+        heat.set_shortwave_timeseries(series.id)
+        heat.cloud.set_timeseries(series.id)
+        assert heat.shortwave_timeseries == series.id
+        assert heat.cloud.timeseries == series.id
+        heat.cloud.clear()
+        assert heat.cloud.timeseries == ''
+
+    def test_registry_is_distinct_from_model_membership(self):
+        solver = self.opened_solver()
+        registry = solver.process_components.known()
+        assert registry
+        assert len({row.id for row in registry}) == len(registry)
+        assert all(row.id and row.description and isinstance(row.implemented, bool) for row in registry)
+        assert len(solver.process_components) == 0
+
+    def test_timeseries_relative_metadata(self):
+        solver = self.opened_solver()
+        series = solver.tables.add_timeseries('PY_RELATIVE')
+        series.add(45000.0, 1.0)
+        series.add(45000.5, 2.0)
+        before = series.points.copy()
+        series.set_relative_info(2, 45000.0)
+        assert series.relative_info == (2, 45000.0)
+        assert (series.points == before).all()
+        series.set_relative_info(0, 0.0)
+        assert series.relative_info[0] == 0
+
+    def test_restore_orientation_is_idempotent(self):
+        links = self.opened_solver().links
+        assert links.restore_authored_orientation() >= 0
+        assert links.restore_authored_orientation() == 0
+
+    def test_compatibility_profiles_can_be_loaded(self):
+        solver = self.opened_solver()
+        counts = (len(solver.nodes), len(solver.links))
+        with tempfile.TemporaryDirectory() as directory:
+            for profile in InpProfile:
+                target = Path(directory) / (profile.name + '.inp')
+                solver.write_compat(target, profile)
+                assert target.stat().st_size > 0
+                assert (len(solver.nodes), len(solver.links)) == counts
+                if profile is InpProfile.FULL:
+                    loaded = Solver(target, target.with_suffix('.rpt'))
+                    try:
+                        loaded.open()
+                        assert (len(loaded.nodes), len(loaded.links)) == counts
+                    finally:
+                        loaded.close()
+                        loaded.destroy()
+                else:
+                    loaded = legacy.Solver(inp_file=str(target), rpt_file=str(target.with_suffix('.rpt')),
+                                           out_file=str(target.with_suffix('.out')))
+                    try:
+                        loaded.initialize()
+                    finally:
+                        loaded.end()
+                        loaded.finalize()
+        with pytest.raises(ValueError):
+            solver.write_compat('unused.inp', 999)
diff --git a/python/tests/engine/test_native_safety.py b/python/tests/engine/test_native_safety.py
new file mode 100644
index 000000000..7dde005be
--- /dev/null
+++ b/python/tests/engine/test_native_safety.py
@@ -0,0 +1,154 @@
+"""Regression tests for ownership and Python/native call boundaries."""
+from concurrent.futures import ThreadPoolExecutor
+from datetime import timedelta
+import gc
+from threading import Event
+import weakref
+
+import pytest
+
+from openswmm.engine import Solver, ModelBuilder
+from openswmm.engine._2d import Surface2D
+from openswmm.engine._exceptions import BadHandleError, LifecycleError, StaleObjectError
+from tests.engine._solver_cases import EngineSolverCase
+
+
+class TestNativeSafety(EngineSolverCase):
+    def test_2d_views_are_invalid_after_close(self):
+        solver = self.opened_solver()
+        surface = solver.surface2d
+        infiltration = surface.infiltration
+        defaults = infiltration.defaults
+        solver.close()
+        with pytest.raises(StaleObjectError):
+            _ = surface.is_active
+        with pytest.raises(StaleObjectError):
+            _ = infiltration.infil_step
+        with pytest.raises(StaleObjectError):
+            _ = len(defaults)
+
+    def test_2d_view_pins_its_owner(self):
+        solver = Solver()
+        solver.create()
+        owner = weakref.ref(solver)
+        surface = Surface2D(solver)
+        del solver
+        gc.collect()
+        assert owner() is not None
+        assert surface.is_active is False
+        owner().destroy()
+        with pytest.raises(StaleObjectError):
+            _ = surface.is_active
+
+    def test_raw_pointer_requires_live_registered_owner(self):
+        with pytest.warns(DeprecationWarning), pytest.raises(BadHandleError):
+            Surface2D(123)
+        solver = self.opened_solver()
+        address = solver.handle
+        with pytest.warns(DeprecationWarning):
+            surface = Surface2D(address)
+        assert surface.is_active is False
+        solver.destroy()
+        with pytest.warns(DeprecationWarning), pytest.raises(BadHandleError):
+            Surface2D(address)
+
+    def test_builder_transfer_initializes_solver_and_invalidates_views(self):
+        builder = ModelBuilder()
+        view = Surface2D(builder)
+        solver = builder.to_solver()
+        try:
+            assert solver.handle != 0
+            assert solver.surface2d.is_active is False
+            with pytest.raises(StaleObjectError):
+                _ = view.is_active
+            with pytest.raises(BadHandleError):
+                builder.to_solver()
+        finally:
+            solver.destroy()
+
+    def test_callback_failure_is_raised_at_each_advance_entrypoint(self):
+        solver = self.running_solver()
+        error = ValueError("callback failed")
+        def fail(*args):
+            raise error
+        for advance in (solver.step, lambda: solver.stride(1),
+                        lambda: next(solver.steps()),
+                        lambda: solver.until(timedelta(days=1))):
+            solver.set_step_begin_callback(fail)
+            with pytest.raises(ValueError) as caught:
+                advance()
+            assert caught.value is error
+        solver.set_step_begin_callback(None)
+        assert solver.step() > timedelta(0)
+
+    def test_callback_can_read_but_cannot_destroy_owner(self):
+        solver = self.running_solver()
+        seen = []
+        def callback(*args):
+            seen.append(solver.nodes.depths.copy())
+            solver.destroy()
+        solver.set_step_begin_callback(callback)
+        with pytest.raises(LifecycleError):
+            solver.step()
+        assert len(seen) == 1
+        assert solver.handle != 0
+        solver.set_step_begin_callback(None)
+        solver.step()
+
+    def test_foreign_thread_access_fails_without_deadlock(self):
+        solver = self.running_solver()
+        entered, release = Event(), Event()
+        def hold(*args):
+            entered.set()
+            assert release.wait(10), "test did not release callback"
+        solver.set_step_begin_callback(hold)
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(solver.step)
+            try:
+                assert entered.wait(10), "step did not enter callback"
+                for access in (solver.destroy, lambda: solver.nodes.depths,
+                               lambda: solver.state):
+                    with pytest.raises(LifecycleError):
+                        access()
+            finally:
+                release.set()
+            future.result(timeout=10)
+        solver.set_step_begin_callback(None)
+        solver.step()
+
+    def test_iterator_rechecks_handle_after_yield(self):
+        solver = self.running_solver()
+        steps = solver.steps()
+        next(steps)
+        solver.destroy()
+        with pytest.raises(BadHandleError):
+            next(steps)
+
+
+def test_destroyed_view_regression_in_subprocess():
+    # A regression must fail this subprocess rather than taking down pytest.
+    import subprocess
+    import sys
+    from pathlib import Path
+    import openswmm
+    stage = str(Path(openswmm.__file__).parents[1])
+    script = f"""
+import sys
+sys.meta_path[:] = [f for f in sys.meta_path if type(f).__module__ != '_openswmm_editable']
+sys.path.insert(0, {stage!r})
+from openswmm.engine import Solver, ModelEditor, StaleObjectError, BadHandleError
+s = Solver()
+s.create()
+v = s.surface2d
+editor = ModelEditor(s)
+s.destroy()
+for operation, error in [(lambda: v.is_active, StaleObjectError), (lambda: editor.node_count, BadHandleError)]:
+    try:
+        operation()
+    except error:
+        pass
+    else:
+        raise AssertionError('destroyed native handle was accepted')
+"""
+    result = subprocess.run([sys.executable, '-c', script], capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
diff --git a/python/tests/engine/test_new_binding_stubs.py b/python/tests/engine/test_new_binding_stubs.py
new file mode 100644
index 000000000..c09f98d8f
--- /dev/null
+++ b/python/tests/engine/test_new_binding_stubs.py
@@ -0,0 +1,29 @@
+"""Ensure new documented view signatures match the installed extension surface."""
+import ast
+import importlib
+import inspect
+from pathlib import Path
+import pytest
+import openswmm.engine
+
+
+@pytest.mark.parametrize('module', ['_transport', '_groundwater', '_gw_transport', '_surface_quality'])
+def test_new_view_stub_signatures(module):
+    runtime = importlib.import_module('openswmm.engine.' + module)
+    stub = Path(openswmm.engine.__file__).with_name(module + '.pyi')
+    for cls in ast.parse(stub.read_text()).body:
+        if not isinstance(cls, ast.ClassDef):
+            continue
+        actual = getattr(runtime, cls.name)
+        for method in cls.body:
+            if not isinstance(method, ast.FunctionDef):
+                continue
+            value = inspect.getattr_static(actual, method.name)
+            if isinstance(value, property):
+                assert any(isinstance(d, ast.Name) and d.id == 'property' or
+                           isinstance(d, ast.Attribute) and d.attr == 'setter'
+                           for d in method.decorator_list), (cls.name, method.name)
+                continue
+            signature = inspect.signature(getattr(actual, method.name))
+            expected = [arg.arg for arg in method.args.posonlyargs + method.args.args + method.args.kwonlyargs]
+            assert list(signature.parameters) == expected, (cls.name, method.name)
diff --git a/python/tests/engine/test_new_domain_tables.py b/python/tests/engine/test_new_domain_tables.py
new file mode 100644
index 000000000..5ebcc977b
--- /dev/null
+++ b/python/tests/engine/test_new_domain_tables.py
@@ -0,0 +1,132 @@
+"""Round-trip all new groundwater and surface-quality authoring tables."""
+from dataclasses import replace
+import numpy as np
+import pytest
+from openswmm.engine import (
+    Solver, CellScope, GroundwaterParameters, GroundwaterSorption,
+    GroundwaterInitialQuality, GroundwaterBoundary, GroundwaterSource,
+    GroundwaterSourceTerm, GroundwaterZone, GroundwaterSpeciesLedger,
+    BadIndexError, BadParamError, LifecycleError, StaleObjectError,
+)
+from tests.engine._groundwater_cases import open_model, cleanup
+
+
+def test_groundwater_transport_tables(tmp_path):
+    solver = open_model(tmp_path)
+    try:
+        t = solver.surface2d.groundwater.transport
+        t.options['TRANSPORT_POLLUTANTS'] = 'YES'
+        assert t.options['TRANSPORT_POLLUTANTS'] == 'YES'
+        t.set_parameters(GroundwaterParameters())
+        t.set_parameters(replace(t.parameters[0], rho_s=2700))
+        assert len(t.parameters) == 1 and t.parameters[0].rho_s == 2700
+        t.set_sorption(GroundwaterSorption(species='TSS', kd=0.25))
+        t.set_initial_quality(GroundwaterInitialQuality(species='TSS', value=5))
+        t.set_boundary(GroundwaterBoundary(cell=1, edge=3, species='TSS', value=2))
+        t.set_source(GroundwaterSource(name='well', cell=1, flow=1e-5))
+        t.set_source_species(0, GroundwaterSourceTerm(species='TSS', value=3))
+        assert t.source_species(0)[0].value == 3
+        assert t.authored
+        saved = tmp_path / 'transport.inp'
+        solver.write(saved)
+        reopened = Solver(saved, tmp_path / 'transport.rpt')
+        try:
+            reopened.open()
+            actual = reopened.surface2d.groundwater.transport
+            for field in ('parameters', 'sorption', 'initial_quality', 'boundaries', 'sources'):
+                assert getattr(actual, field) == getattr(t, field)
+            assert actual.source_species(0) == t.source_species(0)
+        finally:
+            cleanup(reopened)
+        t.initial_quality_file = tmp_path / ('quality-' + 'x' * 180 + '.csv')
+        assert t.initial_quality_file.endswith('.csv')
+        t.initial_quality_file = None
+        assert t.initial_quality_file == ''
+        with pytest.raises(BadIndexError):
+            t.remove_source(999)
+        t.remove_source_species(0, 0)
+        assert t.source_species(0) == ()
+        for field, remove in [('parameters', t.remove_parameters), ('sorption', t.remove_sorption),
+                              ('initial_quality', t.remove_initial_quality), ('boundaries', t.remove_boundary),
+                              ('sources', t.remove_source)]:
+            remove(0)
+            assert getattr(t, field) == ()
+        solver.close()
+        with pytest.raises(StaleObjectError):
+            _ = t.parameters
+    finally:
+        cleanup(solver)
+
+
+def test_groundwater_species_snapshots(tmp_path):
+    solver = open_model(tmp_path)
+    try:
+        gw = solver.surface2d.groundwater
+        gw.options['NODE_ENROLMENT'] = 'ROWS'
+        gw.add_row(CellScope.GLOBAL, 36, 0.5, 0.45, 0.1, 2)
+        gw.set_row_property(0, 'HG0', 0.2)
+        gw.transport.options['TRANSPORT_POLLUTANTS'] = 'YES'
+        gw.transport.set_initial_quality(GroundwaterInitialQuality(species='TSS', value=5))
+        solver.initialize()
+        solver.start(False)
+        solver.step()
+        index = gw.species.index('TSS')
+        for zone in GroundwaterZone:
+            values = gw.concentrations(zone, index)
+            assert values.shape == (2,) and np.isfinite(values).all()
+            values[:] = -999
+            assert (gw.concentrations(zone, index) >= 0).all()
+        for term in GroundwaterSpeciesLedger:
+            assert np.isfinite(gw.species_ledger(index, term))
+        solver.end()
+    finally:
+        cleanup(solver)
+
+
+def test_surface_quality_tables_and_buildup(tmp_path):
+    solver = open_model(tmp_path, '''[LANDUSES]
+URBAN 0 0 0
+[BUILDUP]
+URBAN TSS POW 100 0 1 AREA
+''')
+    try:
+        q = solver.surface2d.quality
+        q.set_coverage(CellScope.GLOBAL, {'URBAN': 100})
+        q.set_loading(CellScope.GLOBAL, 'TSS', 10)
+        q.set_loading(CellScope.TAG, 'TSS', 20, tag='PAN')
+        q.set_loading(CellScope.CELL, 'TSS', 30, cell=0)
+        q.set_curb_length(CellScope.GLOBAL, 25)
+        assert q.coverages[0].landuses == (('URBAN', 100),)
+        assert len(q.loadings) == 3
+        assert q.curb_lengths[0].length == 25
+        with pytest.raises(ValueError):
+            q.set_coverage(CellScope.GLOBAL, {})
+        with pytest.raises(BadParamError):
+            q.set_coverage(CellScope.GLOBAL, {'URBAN': 101})
+        saved = tmp_path / 'quality.inp'
+        solver.write(saved)
+        reopened = Solver(saved, tmp_path / 'quality.rpt')
+        try:
+            reopened.open()
+            actual = reopened.surface2d.quality
+            assert actual.coverages == q.coverages
+            assert actual.loadings == q.loadings
+            assert actual.curb_lengths == q.curb_lengths
+            actual.remove_coverage(0)
+            actual.remove_loading(2)
+            actual.remove_curb_length(0)
+            assert actual.coverages == () and actual.curb_lengths == ()
+            assert len(actual.loadings) == 2
+        finally:
+            cleanup(reopened)
+        solver.initialize()
+        solver.start(False)
+        values = q.buildup('TSS')
+        np.testing.assert_allclose(values, [30, 20])
+        values[:] = -1
+        assert (q.buildup('TSS') >= 0).all()
+        with pytest.raises(LifecycleError):
+            q.remove_loading(0)
+        solver.end()
+    finally:
+        cleanup(solver)
diff --git a/python/tests/engine/test_optional_imports.py b/python/tests/engine/test_optional_imports.py
new file mode 100644
index 000000000..1f1e8882c
--- /dev/null
+++ b/python/tests/engine/test_optional_imports.py
@@ -0,0 +1,39 @@
+"""Distinguish missing build features from broken binary dependencies."""
+from pathlib import Path
+import subprocess
+import sys
+
+import pytest
+import openswmm
+
+
+@pytest.mark.parametrize('module', ['_2d', '_geopackage'])
+@pytest.mark.parametrize('missing', [True, False])
+def test_optional_module_import_contract(module, missing):
+    stage = str(Path(openswmm.__file__).parents[1])
+    script = f'''
+import sys, importlib.abc
+sys.meta_path[:] = [f for f in sys.meta_path if type(f).__module__ != '_openswmm_editable']
+sys.path.insert(0, {stage!r})
+class Block(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname == 'openswmm.engine.{module}':
+            if {missing!r}:
+                raise ModuleNotFoundError('omitted build feature', name=fullname)
+            raise ImportError('broken native dependency')
+sys.meta_path.insert(0, Block())
+import openswmm.engine as engine
+assert not engine.{'HAS_2D' if module=='_2d' else 'HAS_GEOPACKAGE'}
+namespace = {{}}
+exec('from openswmm.engine import *', namespace)
+'''
+    result = subprocess.run([sys.executable, '-c', script], capture_output=True, text=True)
+    if missing:
+        assert result.returncode == 0, result.stderr
+    else:
+        assert result.returncode != 0
+        assert 'broken native dependency' in result.stderr
+
+
+def test_installed_typing_marker():
+    assert Path(openswmm.__file__).with_name('py.typed').is_file()
diff --git a/python/tests/engine/test_output_species_ids.py b/python/tests/engine/test_output_species_ids.py
new file mode 100644
index 000000000..e1f7958ad
--- /dev/null
+++ b/python/tests/engine/test_output_species_ids.py
@@ -0,0 +1,157 @@
+"""``OutputReader.pollutant_ids`` — the Python binding for
+``swmm_output_get_pollut_id``.
+
+Why the names matter, and why reading them by index is not enough: the
+``.out`` per-column unit field is a three-value concentration enum with no
+HOURS slot, so the water-age column (``__WATER_AGE__``, reported in hours)
+necessarily reuses a concentration code. A consumer that keys on the unit
+code sees two MG/L columns, one of which is hours. The NAME is the only
+discriminator, and until ``swmm_output_get_pollut_id`` landed (``06580dd6``)
+nothing in the modern stack could read it — Python exposed
+``pollutant_count`` and nothing else.
+
+Gates here:
+
+* ``test_water_age_deck_names_both_species`` — the ordered-equality
+  assertion ``["TSS", "__WATER_AGE__"]``. Order is asserted, not just
+  membership: a header whose name list disagrees with the data column order
+  passes every value-by-index check while telling a consumer the wrong
+  thing.
+* ``test_reference_deck_names_its_pollutant`` — the no-water-age path on the
+  shared reference model, so the binding is not shown to work only on a deck
+  written by this file.
+* ``test_pollutant_ids_returns_a_copy`` — the property caches; it must hand
+  back a copy, or one caller's mutation silently rewrites every later read.
+
+Fixtures are written to the reviewable per-test artifact directory
+(CLAUDE.md 4.1).
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+try:
+    import openswmm.engine._output_reader  # noqa: F401
+except ImportError as _exc:  # pragma: no cover - environment dependent
+    raise unittest.SkipTest(f"requires compiled engine: {_exc}")
+
+from openswmm.engine import OutputReader, Solver
+
+from tests._paths import SITE_DRAINAGE_INP, artifact_dir
+
+
+#: Level pool: wet junctions, a FIXED outfall at the water surface, so there
+#: is no flow and no transport physics enters any assertion here. The deck
+#: mirrors ``tests/unit/engine/test_output_quality.cpp``'s, which is where
+#: the C-level gates for the same reader live.
+_DECK = """[TITLE]
+python species-id gate deck
+
+[OPTIONS]
+FLOW_UNITS CFS
+FLOW_ROUTING DYNWAVE
+START_DATE 01/01/2026
+START_TIME 00:00:00
+END_DATE 01/01/2026
+END_TIME 00:10:00
+ROUTING_STEP 5
+REPORT_STEP 00:01:00
+WATER_AGE ON
+QUALITY_SOLVER EULERIAN_ARD
+
+[JUNCTIONS]
+J0 10.0 10 1.5 0 0
+J1 10.0 10 1.5 0 0
+J2 10.0 10 1.5 0 0
+
+[OUTFALLS]
+OUT 10.0 FIXED 11.5 NO
+
+[CONDUITS]
+C1 J0 J1 500 0.013 0 0 0
+C2 J1 J2 500 0.013 0 0 0
+C3 J2 OUT 500 0.013 0 0 0
+
+[XSECTIONS]
+C1 CIRCULAR 2.0 0 0 0
+C2 CIRCULAR 2.0 0 0 0
+C3 CIRCULAR 2.0 0 0 0
+
+[POLLUTANTS]
+;;Name Units Crain Cgw Crdii Kdecay SnowOnly CoPollut CoFrac Cdwf Cinit
+TSS    MG/L  0     0   0     0      NO       *        0      0    42
+
+[PROCESS_COMPONENTS]
+org.hydrocouple.openswmm.waterage config="age.cfg"
+
+[REPORT]
+INPUT NO
+"""
+
+_AGE_CFG = "[WATER_AGE_SOURCES]\nINITIAL_STATE GLOBAL 2.0\n"
+
+
+class SpeciesIdCase(unittest.TestCase):
+    """Runs a deck to completion and re-opens the ``.out`` it wrote."""
+
+    def _run(self, inp: str) -> str:
+        d = artifact_dir(self)
+        rpt = os.path.join(d, "model.rpt")
+        out = os.path.join(d, "model.out")
+        s = Solver(inp, rpt, out)
+        s.open()
+        s.initialize()
+        s.start()
+        for _ in s.steps():
+            pass
+        s.end()
+        s.report()
+        s.close()
+        s.destroy()
+        self.assertTrue(os.path.exists(out), f"no .out written to {out}")
+        return out
+
+    def _reader(self, out_path: str) -> OutputReader:
+        o = OutputReader(out_path)
+        self.addCleanup(o.close)
+        return o
+
+
+class TestSpeciesIds(SpeciesIdCase):
+    def test_water_age_deck_names_both_species(self):
+        d = artifact_dir(self)
+        inp = os.path.join(d, "age.inp")
+        with open(os.path.join(d, "age.cfg"), "w", encoding="utf-8") as fh:
+            fh.write(_AGE_CFG)
+        with open(inp, "w", encoding="utf-8") as fh:
+            fh.write(_DECK)
+
+        out = self._reader(self._run(inp))
+
+        # Setup assertion before the result one: if the deck did not actually
+        # enable water age, the equality below would fail for a reason that
+        # has nothing to do with the binding under test.
+        self.assertEqual(
+            out.pollutant_count,
+            2,
+            "the deck did not produce two species columns — WATER_AGE never "
+            "reached the writer, so this gate is not testing the binding",
+        )
+        self.assertEqual(out.pollutant_ids, ["TSS", "__WATER_AGE__"])
+
+    def test_reference_deck_names_its_pollutant(self):
+        out = self._reader(self._run(SITE_DRAINAGE_INP))
+        self.assertEqual(out.pollutant_ids, ["TSS"])
+        self.assertEqual(len(out.pollutant_ids), out.pollutant_count)
+
+    def test_pollutant_ids_returns_a_copy(self):
+        out = self._reader(self._run(SITE_DRAINAGE_INP))
+        first = out.pollutant_ids
+        first.append("MUTATED")
+        self.assertEqual(out.pollutant_ids, ["TSS"])
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()
diff --git a/python/tests/engine/test_process_components.py b/python/tests/engine/test_process_components.py
new file mode 100644
index 000000000..462e896c2
--- /dev/null
+++ b/python/tests/engine/test_process_components.py
@@ -0,0 +1,295 @@
+"""Round-trips and documented refusals for ``solver.process_components``.
+
+Covers:
+  * The ``[PROCESS_COMPONENTS]`` registration table as a sequence — ``len``,
+    iteration, ``__getitem__`` by index *and* by id, ``__contains__``,
+    ``get_index``, ``repr``.
+  * ``register`` — including the documented flow where the ``config=`` path
+    **does not exist yet** (registration is legal; the path is read at the
+    next open), so the new row's ``resolved`` is ``""``.
+  * A deck-declared registration whose ``resolved`` IS filled in, because
+    opening the model resolved it — the contrast that gives ``resolved``
+    its meaning.
+  * The documented refusals: a duplicate id, an out-of-range index, an
+    unknown id, and a key that is neither ``int`` nor ``str`` (``bool``
+    included, so ``components[True]`` cannot silently mean index 1).
+  * ``remove`` shifting later registrations down.
+
+The model is authored inline: ``site_drainage_model.inp`` has no
+``[PROCESS_COMPONENTS]`` section at all. The ``.inp``, its ``.age`` sidecar
+and every report/output file land in ``tests/engine/output`` so a user can
+review them after a run.
+
+@author: Caleb Buahin
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from openswmm.engine import BadParamError, ProcessComponent
+
+from tests.engine._solver_cases import EngineSolverCase
+
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
+
+#: ``kAgeId`` in ``src/engine/transport/components/WaterAgeModule/
+#: WaterAgeComponent.cpp`` — a real, resolvable component so the deck row
+#: has a non-empty ``resolved`` after open.
+_AGE_COMPONENT = "org.hydrocouple.openswmm.waterage"
+
+
+def _process_components_model(tag):
+    """Write an ``.inp`` with one ``[PROCESS_COMPONENTS]`` row plus its config.
+
+    The row spelling is `` config=""`` — the form
+    ``InpWriter.cpp`` emits and ``SWMMEngine.cpp`` resolves at open. The
+    ``config=`` path is relative, so it resolves against the ``.inp``'s own
+    directory.
+    """
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    age_name = f"process_components_{tag}.age"
+    with open(os.path.join(_OUT_DIR, age_name), "w") as f:
+        f.write("[WATER_AGE_SOURCES]\nDWF GLOBAL 2.0\n")
+
+    text = (
+        "[TITLE]\n"
+        "Python process-components binding deck\n"
+        "\n[OPTIONS]\n"
+        "FLOW_UNITS           CFS\n"
+        "FLOW_ROUTING         DYNWAVE\n"
+        "QUALITY_SOLVER       EULERIAN_ARD\n"
+        "WATER_AGE            ON\n"
+        "START_DATE           01/01/2026\n"
+        "START_TIME           00:00:00\n"
+        "END_DATE             01/01/2026\n"
+        "END_TIME             00:30:00\n"
+        "ROUTING_STEP         5\n"
+        "REPORT_STEP          00:05:00\n"
+        "\n[JUNCTIONS]\n"
+        ";;Name Elev MaxDepth InitDepth SurDepth Aponded\n"
+        "J0  10.0  10  1.0  0  0\n"
+        "J1   9.0  10  1.0  0  0\n"
+        "\n[OUTFALLS]\n"
+        "OUT  8.0  FREE  NO\n"
+        "\n[CONDUITS]\n"
+        "C1  J0  J1   400  0.013  0  0  0\n"
+        "C2  J1  OUT  400  0.013  0  0  0\n"
+        "\n[XSECTIONS]\n"
+        "C1  CIRCULAR  1.5  0  0  0\n"
+        "C2  CIRCULAR  1.5  0  0  0\n"
+        "\n[PROCESS_COMPONENTS]\n"
+        f'{_AGE_COMPONENT} config="{age_name}"\n'
+        "\n[REPORT]\n"
+        "INPUT NO\n"
+    )
+    path = os.path.join(_OUT_DIR, f"process_components_{tag}.inp")
+    with open(path, "w") as f:
+        f.write(text)
+    return path
+
+
+class _ProcessComponentsCase(EngineSolverCase):
+    """``EngineSolverCase`` bound to the inline [PROCESS_COMPONENTS] deck."""
+
+    def solver_files(self):
+        inp = _process_components_model(self.tag())
+        base = os.path.splitext(inp)[0]
+        return inp, base + ".rpt", base + ".out"
+
+    def tag(self):
+        # Class AND method, so a method name reused by another class can
+        # never put two tests on the same deck file.
+        return "_".join(self.id().split(".")[-2:])
+
+    def config_name(self):
+        return f"process_components_{self.tag()}.age"
+
+
+# ---------------------------------------------------------------------------
+# Container protocol
+# ---------------------------------------------------------------------------
+class TestProcessComponentsContainer(_ProcessComponentsCase):
+
+    def test_parsed_registration(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        self.assertEqual(len(pcs), 1)
+        row = pcs[0]
+        self.assertIsInstance(row, ProcessComponent)
+        self.assertEqual(row.component_index, 0)
+        self.assertEqual(row.id, _AGE_COMPONENT)
+        self.assertEqual(row.config, self.config_name())
+
+    def test_lookup_by_id_matches_lookup_by_index(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        self.assertEqual(pcs[_AGE_COMPONENT], pcs[0])
+        self.assertEqual(pcs.get_index(_AGE_COMPONENT), 0)
+        self.assertEqual(pcs[-1], pcs[0])
+
+    def test_contains(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        self.assertIn(_AGE_COMPONENT, pcs)
+        self.assertNotIn("not.a.component", pcs)
+        # A non-string is never a component id.
+        self.assertNotIn(0, pcs)
+
+    def test_iteration(self):
+        s = self.opened_solver()
+        rows = list(s.process_components)
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0].id, _AGE_COMPONENT)
+
+    def test_repr_does_not_raise(self):
+        s = self.opened_solver()
+        self.assertIsInstance(repr(s.process_components), str)
+
+
+# ---------------------------------------------------------------------------
+# resolved
+# ---------------------------------------------------------------------------
+class TestProcessComponentsResolved(_ProcessComponentsCase):
+
+    def test_deck_registration_is_resolved_by_the_open(self):
+        s = self.opened_solver()
+        row = s.process_components[_AGE_COMPONENT]
+        self.assertTrue(
+            row.resolved,
+            "opening the model should record the path the config was read "
+            "from")
+        self.assertTrue(row.resolved.endswith(self.config_name()))
+
+    def test_new_registration_has_no_resolved_path_yet(self):
+        """`resolved` is empty until an open resolves it — including for a
+        row registered after the open."""
+        s = self.opened_solver()
+        pcs = s.process_components
+        row = pcs.register("test.component.fresh", "fresh_config.rxn")
+        self.assertEqual(row.resolved, "")
+        # And re-reading the row through the collection agrees.
+        self.assertEqual(pcs["test.component.fresh"].resolved, "")
+
+
+# ---------------------------------------------------------------------------
+# register()
+# ---------------------------------------------------------------------------
+class TestProcessComponentsRegister(_ProcessComponentsCase):
+
+    def test_register_appends_and_round_trips(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        row = pcs.register("test.component.a", "component_a.cfg")
+        self.assertEqual(len(pcs), 2)
+        self.assertEqual(row.component_index, 1)
+        self.assertEqual(row.id, "test.component.a")
+        self.assertEqual(row.config, "component_a.cfg")
+        self.assertIn("test.component.a", pcs)
+
+    def test_register_against_a_nonexistent_config_path_is_accepted(self):
+        """The "create component, then write its config" flow: registration
+        first, file afterwards."""
+        s = self.opened_solver()
+        missing = os.path.join(_OUT_DIR, "definitely_not_written_yet.rxn")
+        self.assertFalse(os.path.exists(missing))
+        row = s.process_components.register("test.component.later", missing)
+        self.assertEqual(row.config, missing)
+        self.assertEqual(row.resolved, "")
+
+    def test_register_without_a_config_path(self):
+        s = self.opened_solver()
+        row = s.process_components.register("test.component.bare")
+        self.assertEqual(row.config, "")
+
+    def test_duplicate_id_is_refused(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        pcs.register("test.component.dup", "one.cfg")
+        before = len(pcs)
+        with self.assertRaises(BadParamError):
+            pcs.register("test.component.dup", "two.cfg")
+        # Refused, not overwritten: the count and the first config survive.
+        self.assertEqual(len(pcs), before)
+        self.assertEqual(pcs["test.component.dup"].config, "one.cfg")
+
+    def test_duplicate_of_the_deck_registration_is_refused(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        with self.assertRaises(BadParamError):
+            pcs.register(_AGE_COMPONENT, "other.age")
+        self.assertEqual(len(pcs), 1)
+
+
+# ---------------------------------------------------------------------------
+# remove()
+# ---------------------------------------------------------------------------
+class TestProcessComponentsRemove(_ProcessComponentsCase):
+
+    def test_remove_by_id(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        pcs.register("test.component.x", "x.cfg")
+        self.assertEqual(len(pcs), 2)
+        pcs.remove("test.component.x")
+        self.assertEqual(len(pcs), 1)
+        self.assertNotIn("test.component.x", pcs)
+
+    def test_remove_by_index_shifts_later_rows_down(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        pcs.register("test.component.x", "x.cfg")
+        pcs.register("test.component.y", "y.cfg")
+        self.assertEqual(len(pcs), 3)
+        pcs.remove(0)
+        self.assertEqual(len(pcs), 2)
+        self.assertEqual([r.id for r in pcs],
+                         ["test.component.x", "test.component.y"])
+        # Indexes are re-derived, never stale.
+        self.assertEqual(pcs["test.component.y"].component_index, 1)
+
+    def test_remove_does_not_delete_the_config_file(self):
+        s = self.opened_solver()
+        cfg = os.path.join(_OUT_DIR, self.config_name())
+        self.assertTrue(os.path.exists(cfg))
+        s.process_components.remove(_AGE_COMPONENT)
+        self.assertTrue(os.path.exists(cfg))
+
+
+# ---------------------------------------------------------------------------
+# Key handling
+# ---------------------------------------------------------------------------
+class TestProcessComponentsKeys(_ProcessComponentsCase):
+
+    def test_unknown_id_raises_keyerror(self):
+        s = self.opened_solver()
+        pcs = s.process_components
+        with self.assertRaises(KeyError):
+            pcs["not.a.component"]
+        with self.assertRaises(KeyError):
+            pcs.get_index("not.a.component")
+        with self.assertRaises(KeyError):
+            pcs.remove("not.a.component")
+
+    def test_out_of_range_index_raises_indexerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(IndexError):
+            s.process_components[99]
+        with self.assertRaises(IndexError):
+            s.process_components[-99]
+
+    def test_bool_key_is_rejected(self):
+        """``components[True]`` must not silently mean index 1."""
+        s = self.opened_solver()
+        with self.assertRaises(TypeError):
+            s.process_components[True]
+
+    def test_non_int_non_str_key_is_rejected(self):
+        s = self.opened_solver()
+        with self.assertRaises(TypeError):
+            s.process_components[1.5]
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_quality_editing.py b/python/tests/engine/test_quality_editing.py
index a4b819018..22367e5cf 100644
--- a/python/tests/engine/test_quality_editing.py
+++ b/python/tests/engine/test_quality_editing.py
@@ -166,10 +166,12 @@ def test_validate_treatment_expression(self):
             self.assertTrue(ok)
             self.assertEqual(msg, "")
 
+            ok, msg, col = s.quality.validate_treatment_expression("C = FLOW * 2")
+            self.assertTrue(ok)  # FLOW is now a supported hydraulic variable.
             ok, msg, col = s.quality.validate_treatment_expression(
-                "C = FLOW * 2")
+                "C = NOT_A_HYDRAULIC_VARIABLE * 2")
             self.assertFalse(ok)
-            self.assertIn("FLOW", msg)
+            self.assertIn("NOT_A_HYDRAULIC_VARIABLE", msg)
             self.assertEqual(col, 4)
 
             ok, msg, col = s.quality.validate_treatment_expression("X = 1")
diff --git a/python/tests/engine/test_reactions.py b/python/tests/engine/test_reactions.py
new file mode 100644
index 000000000..6ebe50e1e
--- /dev/null
+++ b/python/tests/engine/test_reactions.py
@@ -0,0 +1,697 @@
+"""Round-trips, refusals and text-tab contracts for ``solver.reactions``.
+
+Covers:
+  * ``Reactions.hydraulic_variables()`` / ``Reactions.functions()`` — the
+    **engine-less statics**: exercised with no ``Solver`` constructed at all,
+    and asserted against the documented vocabulary (``D Q U RE US FF AV HRT
+    DT``; ``EXP``..``TAN`` arity 1, ``MIN`` ``MAX`` ``POW`` arity 2).
+  * ``reactions.species`` / ``.coefficients`` / ``.terms`` — the container
+    protocol (``len``, iteration, index and name lookup, ``__contains__``,
+    ``get_index``, ``repr``) and every setter round-tripped against its
+    getter.
+  * ``reactions.initial`` — the per-node/per-link initial-quality rows.
+  * ``reactions.get_option`` / ``set_option`` — the ``[REACTION_OPTIONS]``
+    tokens.
+  * ``reactions.validate`` — compile-only, never mutating.
+  * The documented refusals: removing a still-referenced species,
+    coefficient or term; a malformed expression reported by ``validate``;
+    ``check_text`` on bad text leaving state byte-identical; and a failed
+    ``apply_text`` leaving state byte-identical.
+  * The D-RC6 invariant: ``serialize() -> apply_text() -> serialize()`` is
+    byte-identical.
+
+The model is authored inline because ``site_drainage_model.inp`` carries no
+``[REACTION_*]`` sections. The ``.inp``, its ``.rxn`` component config and
+every report/output file land in ``tests/engine/output`` so a user can
+review them after a run.
+
+@author: Caleb Buahin
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from openswmm.engine import (
+    BadParamError,
+    ReactionCoefficient,
+    ReactionExprForm,
+    ReactionFunction,
+    ReactionHydVar,
+    ReactionInitialEntry,
+    ReactionScope,
+    ReactionSpecies,
+    ReactionTerm,
+    Reactions,
+)
+
+from tests.engine._solver_cases import EngineSolverCase
+
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
+
+#: ``kComponentId`` in ``src/engine/transport/components/ReactionModule/
+#: ReactionsComponent.cpp``.
+_RXN_COMPONENT = "org.hydrocouple.openswmm.reactions"
+
+#: Text that parses as ``.rxn`` sections but cannot COMPILE — the reference
+#: to ``NO_SUCH_COEF`` resolves against nothing.
+_UNCOMPILABLE_RXN = (
+    "[REACTION_OPTIONS]\n"
+    "RATE_UNITS SEC\n"
+    "[REACTION_SPECIES]\n"
+    "BULK Z MG\n"
+    "[REACTION_PIPES]\n"
+    "RATE Z -NO_SUCH_COEF * Z\n"
+)
+
+
+def _reactions_model(tag):
+    """Write a reaction-enabled ``.inp`` plus its ``.rxn`` config.
+
+    Section spellings are the engine's own — ``[REACTION_OPTIONS]``,
+    ``[REACTION_SPECIES]``, ``[REACTION_COEFFICIENTS]``,
+    ``[REACTION_TERMS]``, ``[REACTION_PIPES]``, ``[REACTION_TANKS]`` and
+    ``[REACTION_QUALITY]`` (``ReactionsComponent.cpp`` parses them,
+    ``ReactionsWriter.cpp`` emits them) — and the component is bound through
+    ``[PROCESS_COMPONENTS]  config="…"``.
+
+    The system is wired so that every "remove while referenced" refusal has
+    a referent: ``X`` is referenced by ``Y``'s pipe expression, ``Kb`` by
+    both, and the term ``Kf`` by ``X``'s pipe expression.
+    """
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    rxn_name = f"reactions_{tag}.rxn"
+
+    with open(os.path.join(_OUT_DIR, rxn_name), "w") as f:
+        f.write(
+            "[REACTION_OPTIONS]\n"
+            "RATE_UNITS SEC\n"
+            "[REACTION_SPECIES]\n"
+            "BULK X MG\n"
+            "BULK Y MG\n"
+            "[REACTION_COEFFICIENTS]\n"
+            "CONSTANT Kb 0.05\n"
+            "[REACTION_TERMS]\n"
+            "Kf 0.5 * RE / D\n"
+            "[REACTION_PIPES]\n"
+            "RATE X -Kb * Kf * X\n"
+            "RATE Y -Kb * X\n"
+            "[REACTION_TANKS]\n"
+            "RATE X -Kb * X\n"
+            "RATE Y 0\n"
+            "[REACTION_QUALITY]\n"
+            "GLOBAL X 8\n"
+        )
+
+    text = (
+        "[TITLE]\n"
+        "Python reactions-binding round-trip deck\n"
+        "\n[OPTIONS]\n"
+        "FLOW_UNITS           CFS\n"
+        "FLOW_ROUTING         DYNWAVE\n"
+        "QUALITY_SOLVER       EULERIAN_ARD\n"
+        "START_DATE           01/01/2026\n"
+        "START_TIME           00:00:00\n"
+        "END_DATE             01/01/2026\n"
+        "END_TIME             01:00:00\n"
+        "ROUTING_STEP         5\n"
+        "REPORT_STEP          00:05:00\n"
+        "\n[JUNCTIONS]\n"
+        ";;Name Elev MaxDepth InitDepth SurDepth Aponded\n"
+        "J0  10.0  10  1.5  0  0\n"
+        "J1   9.4  10  1.5  0  0\n"
+        "\n[OUTFALLS]\n"
+        "OUT  7.0  FREE  NO\n"
+        "\n[CONDUITS]\n"
+        "C1  J0  J1   500  0.013  0  0  0\n"
+        "C2  J1  OUT  500  0.013  0  0  0\n"
+        "\n[XSECTIONS]\n"
+        "C1  CIRCULAR  2.0  0  0  0\n"
+        "C2  CIRCULAR  2.0  0  0  0\n"
+        "\n[INFLOWS]\n"
+        'J0  FLOW  ""  FLOW  1.0  1.0  5\n'
+        "\n[POLLUTANTS]\n"
+        ";;Name Units Crain Cgw Crdii Kdecay SnowOnly CoPollut CoFrac Cdwf Cinit\n"
+        "TSS   MG/L  0  0  0  0  NO  *  0  0  10\n"
+        "\n[PROCESS_COMPONENTS]\n"
+        f'{_RXN_COMPONENT} config="{rxn_name}"\n'
+        "\n[REPORT]\n"
+        "INPUT NO\n"
+    )
+    path = os.path.join(_OUT_DIR, f"reactions_{tag}.inp")
+    with open(path, "w") as f:
+        f.write(text)
+    return path
+
+
+class _ReactionsCase(EngineSolverCase):
+    """``EngineSolverCase`` bound to the inline reaction deck."""
+
+    def solver_files(self):
+        # Class AND method: several classes share a method name (e.g.
+        # ``test_container_protocol``), and the method name alone would put
+        # two tests on the same deck file.
+        tag = "_".join(self.id().split(".")[-2:])
+        inp = _reactions_model(tag)
+        base = os.path.splitext(inp)[0]
+        return inp, base + ".rpt", base + ".out"
+
+
+# ---------------------------------------------------------------------------
+# Engine-less statics — no Solver is constructed anywhere in this class
+# ---------------------------------------------------------------------------
+class TestReactionStatics(unittest.TestCase):
+    """The discovery statics must work with **no engine at all**.
+
+    These are the authoritative completer/highlighter vocabulary, and a GUI
+    populates them before any model is loaded — so the contract under test is
+    precisely that no ``Solver`` is needed. Nothing in this class builds one.
+    """
+
+    def test_hydraulic_variables_need_no_solver(self):
+        hydvars = Reactions.hydraulic_variables()
+        self.assertIsInstance(hydvars, tuple)
+        self.assertTrue(hydvars)
+        for hv in hydvars:
+            self.assertIsInstance(hv, ReactionHydVar)
+            self.assertTrue(hv.name)
+            self.assertTrue(hv.description)
+
+    def test_documented_hydraulic_variable_vocabulary(self):
+        names = [hv.name for hv in Reactions.hydraulic_variables()]
+        self.assertEqual(
+            names,
+            ["D", "Q", "U", "RE", "US", "FF", "AV", "HRT", "DT", "TEMP"])
+
+    def test_functions_need_no_solver(self):
+        functions = Reactions.functions()
+        self.assertIsInstance(functions, tuple)
+        self.assertTrue(functions)
+        for fn in functions:
+            self.assertIsInstance(fn, ReactionFunction)
+            self.assertTrue(fn.name)
+            self.assertIn(fn.arity, (1, 2))
+
+    def test_documented_function_arities(self):
+        arity = {fn.name: fn.arity for fn in Reactions.functions()}
+        # EXP .. TAN take one argument.
+        for name in ("EXP", "LOG", "LOG10", "SQRT", "ABS", "SGN", "STEP",
+                     "SIN", "COS", "TAN"):
+            with self.subTest(function=name):
+                self.assertEqual(arity.get(name), 1)
+        # MIN, MAX and POW take two.
+        for name in ("MIN", "MAX", "POW"):
+            with self.subTest(function=name):
+                self.assertEqual(arity.get(name), 2)
+
+    def test_statics_are_callable_on_the_class(self):
+        # Not just on an instance: a GUI reaches them as `Reactions.foo()`.
+        self.assertIs(type(Reactions.functions()), tuple)
+        self.assertIs(type(Reactions.hydraulic_variables()), tuple)
+
+
+# ---------------------------------------------------------------------------
+# Species
+# ---------------------------------------------------------------------------
+class TestReactionSpecies(_ReactionsCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        species = s.reactions.species
+        self.assertEqual(len(species), 2)
+        self.assertEqual([sp.name for sp in species], ["X", "Y"])
+        self.assertIsInstance(species[0], ReactionSpecies)
+        self.assertEqual(species["X"].index, 0)
+        self.assertEqual(species["Y"].index, 1)
+        self.assertEqual(species[-1].name, "Y")
+        self.assertIn("X", species)
+        self.assertNotIn("NOPE", species)
+        self.assertEqual(species.get_index("Y"), 1)
+        self.assertIsInstance(repr(species), str)
+        self.assertIsInstance(repr(species[0]), str)
+
+    def test_unknown_name_and_bad_index(self):
+        s = self.opened_solver()
+        species = s.reactions.species
+        with self.assertRaises(KeyError):
+            species["NOPE"]
+        with self.assertRaises(IndexError):
+            species[9]
+        with self.assertRaises(TypeError):
+            species.get_index(1.5)
+
+    def test_attribute_reads(self):
+        s = self.opened_solver()
+        x = s.reactions.species["X"]
+        self.assertEqual(x.name, "X")
+        self.assertFalse(x.is_wall)
+        self.assertEqual(x.units, "MG")
+        self.assertIsInstance(x.atol, float)
+        self.assertIsInstance(x.rtol, float)
+
+    def test_global_initial_roundtrip(self):
+        s = self.opened_solver()
+        x = s.reactions.species["X"]
+        self.assertAlmostEqual(x.initial, 8.0)
+        x.initial = 2.5
+        self.assertAlmostEqual(x.initial, 2.5)
+        self.assertAlmostEqual(s.reactions.species["X"].initial, 2.5)
+
+    def test_expression_roundtrip(self):
+        s = self.opened_solver()
+        x = s.reactions.species["X"]
+        form, expr = x.get_expression(ReactionScope.PIPE)
+        self.assertEqual(form, ReactionExprForm.RATE)
+        self.assertTrue(expr)
+        self.assertEqual(x.pipe_expression, (form, expr))
+
+        x.set_expression(ReactionScope.PIPE, ReactionExprForm.RATE, "-Kb * X")
+        self.assertEqual(x.get_expression(ReactionScope.PIPE),
+                         (ReactionExprForm.RATE, "-Kb * X"))
+
+        x.set_expression(ReactionScope.TANK, ReactionExprForm.FORMULA,
+                         "Kb * 2")
+        self.assertEqual(x.tank_expression,
+                         (ReactionExprForm.FORMULA, "Kb * 2"))
+
+    def test_expression_can_be_cleared(self):
+        s = self.opened_solver()
+        x = s.reactions.species["X"]
+        x.set_expression(ReactionScope.TANK, ReactionExprForm.NONE)
+        self.assertEqual(x.get_expression(ReactionScope.TANK),
+                         (ReactionExprForm.NONE, ""))
+
+    def test_uncompilable_expression_is_refused_and_rolled_back(self):
+        s = self.opened_solver()
+        x = s.reactions.species["X"]
+        before = x.pipe_expression
+        with self.assertRaises(BadParamError):
+            x.set_expression(ReactionScope.PIPE, ReactionExprForm.RATE,
+                             "-NO_SUCH_COEF * X")
+        self.assertEqual(x.pipe_expression, before)
+
+    def test_add_species(self):
+        s = self.opened_solver()
+        species = s.reactions.species
+        z = species.add("Z", units="UG", atol=1e-6, rtol=1e-5)
+        self.assertEqual(len(species), 3)
+        self.assertEqual(z.name, "Z")
+        self.assertEqual(z.index, 2)
+        self.assertFalse(z.is_wall)
+        self.assertEqual(z.units, "UG")
+        self.assertAlmostEqual(z.atol, 1e-6)
+        self.assertAlmostEqual(z.rtol, 1e-5)
+        self.assertIn("Z", species)
+
+    def test_add_wall_species(self):
+        s = self.opened_solver()
+        w = s.reactions.species.add("W", wall=True, units="MG")
+        self.assertTrue(w.is_wall)
+
+    def test_remove_unreferenced_species(self):
+        s = self.opened_solver()
+        species = s.reactions.species
+        species.add("Z", units="MG")
+        self.assertEqual(len(species), 3)
+        species.remove("Z")
+        self.assertEqual(len(species), 2)
+        self.assertNotIn("Z", species)
+
+    def test_remove_referenced_species_is_refused(self):
+        """``X`` appears in ``Y``'s pipe expression — removal must be refused."""
+        s = self.opened_solver()
+        species = s.reactions.species
+        before = len(species)
+        with self.assertRaises(BadParamError):
+            species.remove("X")
+        # Refused, not partially applied.
+        self.assertEqual(len(species), before)
+        self.assertEqual([sp.name for sp in species], ["X", "Y"])
+
+
+# ---------------------------------------------------------------------------
+# Coefficients
+# ---------------------------------------------------------------------------
+class TestReactionCoefficients(_ReactionsCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        coeffs = s.reactions.coefficients
+        self.assertEqual(len(coeffs), 1)
+        self.assertIsInstance(coeffs[0], ReactionCoefficient)
+        self.assertEqual(coeffs["Kb"].index, 0)
+        self.assertIn("Kb", coeffs)
+        self.assertNotIn("NOPE", coeffs)
+        self.assertEqual(coeffs.get_index("Kb"), 0)
+        self.assertIsInstance(repr(coeffs), str)
+        self.assertIsInstance(repr(coeffs[0]), str)
+
+    def test_attribute_reads_and_value_roundtrip(self):
+        s = self.opened_solver()
+        kb = s.reactions.coefficients["Kb"]
+        self.assertEqual(kb.name, "Kb")
+        self.assertFalse(kb.is_param)
+        self.assertAlmostEqual(kb.value, 0.05)
+        kb.value = 0.125
+        self.assertAlmostEqual(kb.value, 0.125)
+        self.assertAlmostEqual(s.reactions.coefficients["Kb"].value, 0.125)
+
+    def test_add_constant_and_parameter(self):
+        s = self.opened_solver()
+        coeffs = s.reactions.coefficients
+        kc = coeffs.add("Kc", value=1.75)
+        self.assertEqual(kc.name, "Kc")
+        self.assertFalse(kc.is_param)
+        self.assertAlmostEqual(kc.value, 1.75)
+        kp = coeffs.add("Kp", parameter=True, value=0.5)
+        self.assertTrue(kp.is_param)
+        self.assertAlmostEqual(kp.value, 0.5)
+        self.assertEqual(len(coeffs), 3)
+
+    def test_remove_unreferenced_coefficient(self):
+        s = self.opened_solver()
+        coeffs = s.reactions.coefficients
+        coeffs.add("Kc", value=1.0)
+        coeffs.remove("Kc")
+        self.assertEqual(len(coeffs), 1)
+        self.assertNotIn("Kc", coeffs)
+
+    def test_remove_referenced_coefficient_is_refused(self):
+        """``Kb`` is referenced by both species' expressions."""
+        s = self.opened_solver()
+        coeffs = s.reactions.coefficients
+        with self.assertRaises(BadParamError):
+            coeffs.remove("Kb")
+        self.assertEqual(len(coeffs), 1)
+        self.assertAlmostEqual(coeffs["Kb"].value, 0.05)
+
+
+# ---------------------------------------------------------------------------
+# Terms
+# ---------------------------------------------------------------------------
+class TestReactionTerms(_ReactionsCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        terms = s.reactions.terms
+        self.assertEqual(len(terms), 1)
+        self.assertIsInstance(terms[0], ReactionTerm)
+        self.assertEqual(terms["Kf"].index, 0)
+        self.assertIn("Kf", terms)
+        self.assertNotIn("NOPE", terms)
+        self.assertEqual(terms.get_index("Kf"), 0)
+        self.assertIsInstance(repr(terms), str)
+        self.assertIsInstance(repr(terms[0]), str)
+
+    def test_expression_roundtrip(self):
+        s = self.opened_solver()
+        kf = s.reactions.terms["Kf"]
+        self.assertEqual(kf.name, "Kf")
+        self.assertTrue(kf.expression)
+        kf.expression = "0.25 * RE"
+        self.assertEqual(kf.expression, "0.25 * RE")
+        self.assertEqual(s.reactions.terms["Kf"].expression, "0.25 * RE")
+
+    def test_add_term(self):
+        s = self.opened_solver()
+        terms = s.reactions.terms
+        kg = terms.add("Kg", "2.0 * D")
+        self.assertEqual(len(terms), 2)
+        self.assertEqual(kg.name, "Kg")
+        self.assertEqual(kg.index, 1)
+        self.assertEqual(kg.expression, "2.0 * D")
+
+    def test_uncompilable_term_is_refused(self):
+        s = self.opened_solver()
+        terms = s.reactions.terms
+        with self.assertRaises(BadParamError):
+            terms.add("Kbad", "NO_SUCH_NAME * 2")
+        self.assertEqual(len(terms), 1)
+
+    def test_remove_unreferenced_term(self):
+        s = self.opened_solver()
+        terms = s.reactions.terms
+        terms.add("Kg", "2.0 * D")
+        terms.remove("Kg")
+        self.assertEqual(len(terms), 1)
+        self.assertNotIn("Kg", terms)
+
+    def test_remove_referenced_term_is_refused(self):
+        """``Kf`` is referenced by ``X``'s pipe expression."""
+        s = self.opened_solver()
+        terms = s.reactions.terms
+        with self.assertRaises(BadParamError):
+            terms.remove("Kf")
+        self.assertEqual(len(terms), 1)
+        self.assertEqual(terms[0].name, "Kf")
+
+
+# ---------------------------------------------------------------------------
+# Per-element initial quality rows
+# ---------------------------------------------------------------------------
+class TestReactionInitialRows(_ReactionsCase):
+
+    def test_empty_before_any_row_is_set(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        self.assertEqual(len(rows), 0)
+        self.assertEqual(list(rows), [])
+        self.assertIsInstance(repr(rows), str)
+
+    def test_set_and_read_back(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        node = s.nodes["J1"].index
+        rows.set(False, node, "X", 3.0)
+        self.assertEqual(len(rows), 1)
+        row = rows[0]
+        self.assertIsInstance(row, ReactionInitialEntry)
+        self.assertFalse(row.is_link)
+        self.assertEqual(row.elem_index, node)
+        self.assertEqual(row.species_index, s.reactions.species.get_index("X"))
+        self.assertAlmostEqual(row.value, 3.0)
+        self.assertEqual(rows[-1], row)
+
+    def test_upsert_on_the_same_key(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        node = s.nodes["J1"].index
+        rows.set(False, node, "X", 3.0)
+        rows.set(False, node, "X", 4.5)
+        self.assertEqual(len(rows), 1)
+        self.assertAlmostEqual(rows[0].value, 4.5)
+
+    def test_link_rows(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        link = s.links["C1"].index
+        rows.set(True, link, "Y", 1.25)
+        row = rows[-1]
+        self.assertTrue(row.is_link)
+        self.assertEqual(row.elem_index, link)
+        self.assertAlmostEqual(row.value, 1.25)
+
+    def test_negative_value_refused(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        with self.assertRaises(BadParamError):
+            rows.set(False, s.nodes["J1"].index, "X", -1.0)
+        self.assertEqual(len(rows), 0)
+
+    def test_unknown_species_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.reactions.initial.set(False, 0, "NOPE", 1.0)
+
+    def test_remove_and_index_bounds(self):
+        s = self.opened_solver()
+        rows = s.reactions.initial
+        rows.set(False, s.nodes["J0"].index, "X", 1.0)
+        rows.set(False, s.nodes["J1"].index, "X", 2.0)
+        self.assertEqual(len(rows), 2)
+        second = rows[1]
+        rows.remove(0)
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0], second)
+        with self.assertRaises(IndexError):
+            rows[1]
+        with self.assertRaises(IndexError):
+            rows.remove(5)
+
+
+# ---------------------------------------------------------------------------
+# [REACTION_OPTIONS]
+# ---------------------------------------------------------------------------
+class TestReactionOptions(_ReactionsCase):
+
+    def test_parsed_option(self):
+        s = self.opened_solver()
+        self.assertEqual(s.reactions.get_option("RATE_UNITS"), "SEC")
+
+    def test_token_option_roundtrips(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        for key, value in (("SOLVER", "RK5"), ("SOLVER", "ROS2"),
+                           ("COUPLING", "FULL"), ("COUPLING", "NONE"),
+                           ("RATE_UNITS", "HR"), ("RATE_UNITS", "DAY"),
+                           ("AREA_UNITS", "M2"), ("AREA_UNITS", "CM2")):
+            with self.subTest(key=key, value=value):
+                rxn.set_option(key, value)
+                self.assertEqual(rxn.get_option(key), value)
+
+    def test_numeric_option_roundtrips(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        for key, value in (("TIMESTEP", 30.0), ("ATOL", 0.001),
+                           ("RTOL", 0.002), ("TEMPERATURE", 12.5)):
+            with self.subTest(key=key):
+                rxn.set_option(key, str(value))
+                # Numeric options come back as text; compare numerically.
+                self.assertAlmostEqual(float(rxn.get_option(key)), value)
+
+    def test_unknown_key_refused(self):
+        s = self.opened_solver()
+        with self.assertRaises(BadParamError):
+            s.reactions.get_option("NOT_AN_OPTION")
+        with self.assertRaises(BadParamError):
+            s.reactions.set_option("NOT_AN_OPTION", "1")
+
+    def test_unknown_value_refused(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        with self.assertRaises(BadParamError):
+            rxn.set_option("SOLVER", "NOT_A_SOLVER")
+        # Refused, not applied.
+        self.assertNotEqual(rxn.get_option("SOLVER"), "NOT_A_SOLVER")
+
+
+# ---------------------------------------------------------------------------
+# validate()
+# ---------------------------------------------------------------------------
+class TestReactionValidate(_ReactionsCase):
+
+    def test_valid_expression(self):
+        s = self.opened_solver()
+        diag = s.reactions.validate("-Kb * X", ReactionScope.PIPE)
+        self.assertTrue(diag.valid)
+        self.assertEqual(diag.message, "")
+
+    def test_malformed_expression_is_invalid_with_a_message(self):
+        s = self.opened_solver()
+        for expr in ("-NOT_A_NAME * 2", "-Kb *", "* X", "( X"):
+            with self.subTest(expr=expr):
+                diag = s.reactions.validate(expr, ReactionScope.PIPE)
+                self.assertFalse(diag.valid)
+                self.assertTrue(diag.message,
+                                "a refusal must carry a diagnostic")
+                self.assertIsInstance(diag.column, int)
+
+    def test_validate_never_mutates(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        before = rxn.serialize()
+        rxn.validate("-NOT_A_NAME * 2", ReactionScope.PIPE)
+        rxn.validate("-Kb * X", ReactionScope.TANK)
+        self.assertEqual(rxn.serialize(), before)
+
+    def test_default_scope_is_pipe(self):
+        s = self.opened_solver()
+        self.assertTrue(s.reactions.validate("-Kb * X").valid)
+
+
+# ---------------------------------------------------------------------------
+# The whole-file text surface
+# ---------------------------------------------------------------------------
+class TestReactionText(_ReactionsCase):
+
+    def test_serialize_is_non_empty(self):
+        s = self.opened_solver()
+        text = s.reactions.serialize()
+        self.assertTrue(text)
+        self.assertIn("[REACTION_SPECIES]", text)
+
+    def test_serialize_apply_text_serialize_is_byte_identical(self):
+        """D-RC6 — the invariant that makes a GUI text tab safe."""
+        s = self.opened_solver()
+        rxn = s.reactions
+        first = rxn.serialize()
+        self.assertTrue(rxn.check_text(first).valid)
+        rxn.apply_text(first)
+        self.assertEqual(rxn.serialize(), first)
+        # And once more, to show it is a fixed point rather than luck.
+        rxn.apply_text(first)
+        self.assertEqual(rxn.serialize(), first)
+
+    def test_check_text_accepts_good_text(self):
+        s = self.opened_solver()
+        diag = s.reactions.check_text(s.reactions.serialize())
+        self.assertTrue(diag.valid)
+        self.assertEqual(diag.message, "")
+
+    def test_check_text_on_bad_text_does_not_mutate(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        before = rxn.serialize()
+        diag = rxn.check_text(_UNCOMPILABLE_RXN)
+        self.assertFalse(diag.valid)
+        self.assertTrue(diag.message)
+        # Whole-file checks report no column.
+        self.assertEqual(diag.column, -1)
+        # Zero state change on failure.
+        self.assertEqual(rxn.serialize(), before)
+
+    def test_check_text_on_good_text_does_not_mutate_either(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        before = rxn.serialize()
+        rxn.check_text(_UNCOMPILABLE_RXN.replace("NO_SUCH_COEF * Z", "0"))
+        self.assertEqual(rxn.serialize(), before)
+
+    def test_failed_apply_text_leaves_state_byte_identical(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        before = rxn.serialize()
+        with self.assertRaises(BadParamError):
+            rxn.apply_text(_UNCOMPILABLE_RXN)
+        # Staged: on ANY error the previous system is byte-identical.
+        self.assertEqual(rxn.serialize(), before)
+        # The vocabulary survived too.
+        self.assertEqual([sp.name for sp in rxn.species], ["X", "Y"])
+        self.assertEqual([c.name for c in rxn.coefficients], ["Kb"])
+        self.assertEqual([t.name for t in rxn.terms], ["Kf"])
+
+    def test_apply_text_replaces_the_system(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        rxn.apply_text(
+            "[REACTION_OPTIONS]\n"
+            "RATE_UNITS HR\n"
+            "[REACTION_SPECIES]\n"
+            "BULK P MG\n"
+            "[REACTION_PIPES]\n"
+            "RATE P 0\n"
+        )
+        self.assertEqual([sp.name for sp in rxn.species], ["P"])
+        self.assertEqual(rxn.get_option("RATE_UNITS"), "HR")
+
+    def test_save_writes_the_serialized_text(self):
+        s = self.opened_solver()
+        rxn = s.reactions
+        out = os.path.join(_OUT_DIR, "reactions_saved.rxn")
+        rxn.save(out)
+        self.assertTrue(os.path.exists(out))
+        with open(out) as f:
+            self.assertIn("[REACTION_SPECIES]", f.read())
+
+    def test_repr_does_not_raise(self):
+        s = self.opened_solver()
+        for view in (s.reactions, s.reactions.species,
+                     s.reactions.coefficients, s.reactions.terms,
+                     s.reactions.initial):
+            with self.subTest(view=type(view).__name__):
+                self.assertIsInstance(repr(view), str)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_surface2d_run_stats.py b/python/tests/engine/test_surface2d_run_stats.py
new file mode 100644
index 000000000..540ebb81c
--- /dev/null
+++ b/python/tests/engine/test_surface2d_run_stats.py
@@ -0,0 +1,82 @@
+"""``Surface2D.run_stats`` — the backend label, momentum closure, configured
+LTS_TIERS and the cumulative marcher counters (``swmm_2d_get_run_stats``)
+read during a run of ``examples/2d_complete_example.inp``.
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+try:  # pragma: no cover - import guard mirrors test_surface2d_view.py
+    import openswmm.engine._2d  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise unittest.SkipTest(f"2D bindings not built: {exc}")
+
+from openswmm.engine import Solver  # noqa: E402
+
+from tests._paths import artifact_dir  # noqa: E402
+
+_TESTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_REPO_ROOT = os.path.dirname(os.path.dirname(_TESTS_DIR))
+TWOD_EXAMPLE_INP = os.path.join(_REPO_ROOT, "examples", "2d_complete_example.inp")
+
+
+class TestSurface2dRunStats(unittest.TestCase):
+    def setUp(self):
+        # The AUTO backend is size-gated to the CPU marcher on the example's
+        # 8 cells; an inherited OPENSWMM_2D_BACKEND would override that.
+        self._old_backend = os.environ.get("OPENSWMM_2D_BACKEND")
+        os.environ["OPENSWMM_2D_BACKEND"] = "cpu"
+
+    def tearDown(self):
+        if self._old_backend is None:
+            os.environ.pop("OPENSWMM_2D_BACKEND", None)
+        else:
+            os.environ["OPENSWMM_2D_BACKEND"] = self._old_backend
+
+    def test_stats_populate_during_the_run(self):
+        d = artifact_dir(self)
+        s = Solver(
+            TWOD_EXAMPLE_INP,
+            os.path.join(d, "twod.rpt"),
+            os.path.join(d, "twod.out"),
+        )
+        s.open()
+        s.initialize()
+        try:
+            s.start()
+            surface = s.surface2d
+            self.assertIsNotNone(surface)
+
+            st0 = surface.run_stats
+            self.assertTrue(st0["backend"].startswith("cpu"), st0["backend"])
+            self.assertEqual(st0["momentum"], "LOCAL_INERTIAL")
+            self.assertGreaterEqual(st0["lts_tiers"], 1)
+            self.assertEqual(st0["steps"], 0)
+
+            for _ in range(10):
+                # step() returns the elapsed time as a timedelta; zero = done.
+                if s.step().total_seconds() <= 0.0:
+                    break
+
+            st1 = surface.run_stats
+            self.assertGreater(st1["steps"], 0)
+            self.assertGreater(st1["face_evals"], 0)
+            self.assertGreater(st1["last_step"], 0.0)
+            self.assertEqual(len(st1["tier_cells"]), st1["lts_tiers"])
+            self.assertGreater(sum(st1["tier_cells"]), 0)
+            lo, mean, hi = st1["active_frac"]
+            self.assertLessEqual(lo, hi)
+            self.assertLessEqual(hi, 1.0 + 1e-12)
+            self.assertGreaterEqual(mean, 0.0)
+        finally:
+            try:
+                s.close()
+            except Exception:
+                pass
+            s.destroy()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_surface2d_view.py b/python/tests/engine/test_surface2d_view.py
index ac0d00a76..5f10be541 100644
--- a/python/tests/engine/test_surface2d_view.py
+++ b/python/tests/engine/test_surface2d_view.py
@@ -18,7 +18,7 @@
 except ImportError as _exc:  # pragma: no cover - environment dependent
     raise unittest.SkipTest(f"requires compiled engine: {_exc}")
 
-from openswmm.engine import Solver, Surface2D  # noqa: E402
+from openswmm.engine import Solver, Surface2D, BadParamError, BadIndexError  # noqa: E402
 
 from tests._paths import artifact_dir  # noqa: E402
 
@@ -127,12 +127,12 @@ def test_set_round_trip(self):
 
     def test_non_positive_values_rejected(self):
         surface = self.twod_solver().surface2d
-        with self.assertRaises(RuntimeError):
+        with self.assertRaises(BadParamError):
             surface.set_vertex_coupling_cd(4, 0.0)
-        with self.assertRaises(RuntimeError):
+        with self.assertRaises(BadParamError):
             surface.set_vertex_coupling_area(4, -1.0)
 
     def test_bad_vertex_index_rejected(self):
         surface = self.twod_solver().surface2d
-        with self.assertRaises(RuntimeError):
+        with self.assertRaises(BadIndexError):
             surface.get_vertex_coupling_cd(surface.n_vertices)
diff --git a/python/tests/engine/test_transport.py b/python/tests/engine/test_transport.py
new file mode 100644
index 000000000..3ab3bfc8d
--- /dev/null
+++ b/python/tests/engine/test_transport.py
@@ -0,0 +1,90 @@
+"""Transport configuration, capability diagnostics and thread introspection."""
+import math
+import pytest
+from openswmm.engine import (
+    Solver, TransportDispersionMode, TransportDomain, TransportClass,
+    TransportState, BadParamError, BadHandleError,
+    transport_domain_name, transport_class_name,
+)
+from tests.engine._solver_cases import EngineSolverCase
+
+
+class TestTransport(EngineSolverCase):
+    def test_configuration_and_validation(self):
+        s = self.opened_solver()
+        t = s.transport
+        t.dispersion_mode = TransportDispersionMode.VALUE
+        t.dispersion_value = 1.25
+        t.target_dx = 12.5
+        assert t.configured
+        assert t.dispersion_mode is TransportDispersionMode.VALUE
+        assert t.dispersion_value == 1.25
+        assert t.target_dx == 12.5
+        assert isinstance(t.boundaries, tuple)
+        assert isinstance(t.sources, tuple)
+        assert isinstance(t.conduit_dispersion, tuple)
+        for invalid in (-1.0, math.nan, math.inf):
+            with pytest.raises(BadParamError):
+                t.dispersion_value = invalid
+            with pytest.raises(BadParamError):
+                t.target_dx = invalid
+        with pytest.raises(ValueError):
+            t.dispersion_mode = 99
+        s.destroy()
+        with pytest.raises(BadHandleError):
+            _ = t.target_dx
+
+    def test_matrix_axes_and_diagnostics(self):
+        s = self.opened_solver()
+        matrix = s.transport_matrix
+        assert set(matrix) == set(TransportDomain)
+        for domain, cells in matrix.items():
+            assert transport_domain_name(domain)
+            assert set(cells) == set(TransportClass)
+            for species, cell in cells.items():
+                assert transport_class_name(species)
+                assert isinstance(cell.state, TransportState)
+                assert cell.count >= 0
+                if cell.state is not TransportState.ENABLED:
+                    assert cell.reason
+        with pytest.raises(ValueError):
+            transport_domain_name(100)
+
+    def test_thread_limits(self):
+        s = self.opened_solver()
+        info = s.thread_info
+        assert info.logical_cpus >= 0
+        assert info.omp_max_threads >= 1
+        assert isinstance(info.omp_available, bool)
+        explicit = s.effective_threads(1)
+        assert explicit.global_threads == 1
+        assert explicit.dynamic_wave in (0, 1)
+        assert explicit.surface2d == 0
+        assert s.effective_threads().global_threads >= 1
+
+
+@pytest.mark.parametrize('units', ['CMS', 'CFS'])
+def test_authored_transport_units_and_roundtrip(tmp_path, units):
+    from tests.engine._groundwater_cases import MODEL, cleanup
+    path = tmp_path / 'transport.inp'
+    path.write_text(MODEL.split('[2D_OPTIONS]')[0].replace('FLOW_UNITS CMS', 'FLOW_UNITS ' + units) + '[REPORT]\nINPUT NO\n')
+    solver = Solver(path, tmp_path / 'transport.rpt')
+    try:
+        solver.open()
+        solver.process_components.register("org.hydrocouple.openswmm.transport.ard", "transport.ard")
+        solver.options["QUALITY_SOLVER"] = "EULERIAN_ARD"
+        solver.transport.dispersion_mode = TransportDispersionMode.VALUE
+        solver.transport.dispersion_value = 1.25
+        solver.transport.target_dx = 12.5
+        saved = tmp_path / 'saved.inp'
+        solver.write(saved)
+        reopened = Solver(saved, tmp_path / 'saved.rpt')
+        try:
+            reopened.open()
+            assert reopened.transport.dispersion_value == 1.25
+            assert reopened.transport.target_dx == 12.5
+            assert reopened.transport.dispersion_mode == TransportDispersionMode.VALUE
+        finally:
+            cleanup(reopened)
+    finally:
+        cleanup(solver)
diff --git a/python/tests/engine/test_water_age.py b/python/tests/engine/test_water_age.py
new file mode 100644
index 000000000..46ae345fd
--- /dev/null
+++ b/python/tests/engine/test_water_age.py
@@ -0,0 +1,290 @@
+"""Round-trips and documented refusals for ``solver.water_age``.
+
+Covers:
+  * ``water_age.enabled`` — the ``[OPTIONS] WATER_AGE`` toggle.
+  * ``water_age.globals`` — the ``[WATER_AGE_SOURCES]`` GLOBAL ages (HOURS)
+    as a mapping keyed by :class:`WaterAgeSource`.
+  * ``water_age.node_overrides`` — the NODE-scope override rows, the A1a
+    scope rule, and pair-keyed ``set`` / ``remove``.
+  * ``water_age.save`` — the component-file write path.
+  * The **signed** contract: a negative age is legal here (it extracts
+    age-volume, D-NS1), so the positive test that it is *accepted* matters
+    as much as the negative tests elsewhere.
+
+The model is authored inline because ``site_drainage_model.inp`` carries no
+``[WATER_AGE_SOURCES]`` section. Both the ``.inp`` and its ``.age``
+component config, and every report/output file, land in
+``tests/engine/output`` so a user can review them after a run.
+
+@author: Caleb Buahin
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+from openswmm.engine import (
+    BadIndexError,
+    BadParamError,
+    WaterAgeOverride,
+    WaterAgeSource,
+)
+
+from tests.engine._solver_cases import EngineSolverCase
+
+_OUT_DIR = os.path.join(os.path.dirname(__file__), "output")
+
+#: Component id the engine registers the water-age coordinator under
+#: (``kAgeId`` in ``src/engine/transport/components/WaterAgeModule/
+#: WaterAgeComponent.cpp``).
+_AGE_COMPONENT = "org.hydrocouple.openswmm.waterage"
+
+
+def _water_age_model(tag):
+    """Write a water-age-enabled ``.inp`` plus its ``.age`` config.
+
+    ``[WATER_AGE_SOURCES]`` rows are `` GLOBAL `` and
+    `` NODE  `` — the spelling ``WaterAgeComponent.cpp``
+    parses. The component is bound through ``[PROCESS_COMPONENTS]``.
+    """
+    os.makedirs(_OUT_DIR, exist_ok=True)
+    age_name = f"water_age_{tag}.age"
+
+    with open(os.path.join(_OUT_DIR, age_name), "w") as f:
+        f.write(
+            "[WATER_AGE_SOURCES]\n"
+            "DWF              GLOBAL  4.0\n"
+            "EXTERNAL_INFLOW  NODE    J0  6.0\n"
+        )
+
+    text = (
+        "[TITLE]\n"
+        "Python water-age-binding round-trip deck\n"
+        "\n[OPTIONS]\n"
+        "FLOW_UNITS           CFS\n"
+        "FLOW_ROUTING         DYNWAVE\n"
+        "QUALITY_SOLVER       EULERIAN_ARD\n"
+        "WATER_AGE            ON\n"
+        "START_DATE           01/01/2026\n"
+        "START_TIME           00:00:00\n"
+        "END_DATE             01/01/2026\n"
+        "END_TIME             01:00:00\n"
+        "ROUTING_STEP         5\n"
+        "REPORT_STEP          00:05:00\n"
+        "\n[JUNCTIONS]\n"
+        ";;Name Elev MaxDepth InitDepth SurDepth Aponded\n"
+        "J0  10.0  10  1.5  0  0\n"
+        "J1   9.4  10  1.5  0  0\n"
+        "J2   8.8  10  1.5  0  0\n"
+        "\n[OUTFALLS]\n"
+        "OUT  7.0  FREE  NO\n"
+        "\n[CONDUITS]\n"
+        "C1  J0  J1   500  0.013  0  0  0\n"
+        "C2  J1  J2   500  0.013  0  0  0\n"
+        "C3  J2  OUT  500  0.013  0  0  0\n"
+        "\n[XSECTIONS]\n"
+        "C1  CIRCULAR  2.0  0  0  0\n"
+        "C2  CIRCULAR  2.0  0  0  0\n"
+        "C3  CIRCULAR  2.0  0  0  0\n"
+        "\n[INFLOWS]\n"
+        'J0  FLOW  ""  FLOW  1.0  1.0  5\n'
+        "\n[PROCESS_COMPONENTS]\n"
+        f'{_AGE_COMPONENT} config="{age_name}"\n'
+        "\n[REPORT]\n"
+        "INPUT NO\n"
+    )
+    path = os.path.join(_OUT_DIR, f"water_age_{tag}.inp")
+    with open(path, "w") as f:
+        f.write(text)
+    return path
+
+
+class _WaterAgeCase(EngineSolverCase):
+    """``EngineSolverCase`` bound to the inline water-age deck."""
+
+    def solver_files(self):
+        # Class AND method: two classes share ``test_container_protocol``,
+        # and the method name alone would put both on the same deck file.
+        tag = "_".join(self.id().split(".")[-2:])
+        inp = _water_age_model(tag)
+        base = os.path.splitext(inp)[0]
+        return inp, base + ".rpt", base + ".out"
+
+
+# ---------------------------------------------------------------------------
+# Toggle
+# ---------------------------------------------------------------------------
+class TestWaterAgeEnabled(_WaterAgeCase):
+
+    def test_enabled_reflects_option(self):
+        s = self.opened_solver()
+        self.assertTrue(s.water_age.enabled)
+
+    def test_repr_does_not_raise(self):
+        s = self.opened_solver()
+        for view in (s.water_age, s.water_age.globals,
+                     s.water_age.node_overrides):
+            with self.subTest(view=type(view).__name__):
+                self.assertIsInstance(repr(view), str)
+
+
+# ---------------------------------------------------------------------------
+# GLOBAL source ages
+# ---------------------------------------------------------------------------
+class TestWaterAgeGlobals(_WaterAgeCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        g = s.water_age.globals
+        # The C enum's trailing COUNT sentinel is deliberately not mirrored
+        # into WaterAgeSource, so len() is the pathway count.
+        self.assertEqual(len(g), len(WaterAgeSource))
+        self.assertEqual(len(g), 7)
+        self.assertEqual(list(g), list(WaterAgeSource))
+        self.assertIn(WaterAgeSource.DWF, g)
+        self.assertIn("EXTERNAL_INFLOW", g)
+        self.assertIn(0, g)
+        self.assertNotIn("NOT_A_SOURCE", g)
+        self.assertIsInstance(repr(g), str)
+
+    def test_parsed_global_is_visible(self):
+        s = self.opened_solver()
+        self.assertAlmostEqual(s.water_age.globals[WaterAgeSource.DWF], 4.0)
+
+    def test_roundtrip_every_pathway(self):
+        s = self.opened_solver()
+        g = s.water_age.globals
+        for i, source in enumerate(WaterAgeSource):
+            hours = 1.5 * (i + 1)
+            with self.subTest(source=source):
+                g[source] = hours
+                self.assertAlmostEqual(g[source], hours)
+                self.assertAlmostEqual(g[source.name], hours)
+                self.assertAlmostEqual(g[int(source)], hours)
+
+    def test_negative_global_age_is_accepted(self):
+        """Negative is LEGAL here (D-NS1 age-volume extraction), not refused."""
+        s = self.opened_solver()
+        g = s.water_age.globals
+        g[WaterAgeSource.GW] = -2.5
+        self.assertAlmostEqual(g[WaterAgeSource.GW], -2.5)
+        g[WaterAgeSource.RAINFALL] = -0.001
+        self.assertAlmostEqual(g[WaterAgeSource.RAINFALL], -0.001)
+
+    def test_zero_is_accepted(self):
+        s = self.opened_solver()
+        g = s.water_age.globals
+        g[WaterAgeSource.IFACE] = 0.0
+        self.assertAlmostEqual(g[WaterAgeSource.IFACE], 0.0)
+
+    def test_unknown_source_key_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.water_age.globals["NOT_A_SOURCE"]
+        with self.assertRaises(KeyError):
+            s.water_age.globals[42] = 1.0
+
+
+# ---------------------------------------------------------------------------
+# NODE-scope overrides
+# ---------------------------------------------------------------------------
+class TestWaterAgeNodeOverrides(_WaterAgeCase):
+
+    def test_container_protocol(self):
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        self.assertEqual(len(rows), 1)
+        row = rows[0]
+        self.assertIsInstance(row, WaterAgeOverride)
+        self.assertEqual(row.source, WaterAgeSource.EXTERNAL_INFLOW)
+        self.assertEqual(row.node_index, s.nodes["J0"].index)
+        self.assertAlmostEqual(row.hours, 6.0)
+        self.assertEqual(rows[-1], row)
+        self.assertEqual(list(rows), [row])
+        self.assertIsInstance(repr(rows), str)
+
+    def test_index_out_of_range(self):
+        s = self.opened_solver()
+        with self.assertRaises(IndexError):
+            s.water_age.node_overrides[7]
+
+    def test_set_updates_rather_than_duplicates(self):
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        rows.set(WaterAgeSource.EXTERNAL_INFLOW, "J0", 9.25)
+        self.assertEqual(len(rows), 1)
+        self.assertAlmostEqual(rows[0].hours, 9.25)
+
+    def test_set_appends_a_new_pair(self):
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        rows.set(WaterAgeSource.DWF, "J1", 3.0)
+        self.assertEqual(len(rows), 2)
+        added = rows[1]
+        self.assertEqual(added.source, WaterAgeSource.DWF)
+        self.assertEqual(added.node_index, s.nodes["J1"].index)
+        self.assertAlmostEqual(added.hours, 3.0)
+
+    def test_negative_override_age_is_accepted(self):
+        """Negative is LEGAL for an override too — a naive guard would refuse."""
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        rows.set(WaterAgeSource.DWF, "J1", -1.5)
+        by_node = {(r.source, r.node_index): r.hours for r in rows}
+        self.assertAlmostEqual(
+            by_node[(WaterAgeSource.DWF, s.nodes["J1"].index)], -1.5)
+
+    def test_remove_is_keyed_on_the_pair(self):
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        rows.set(WaterAgeSource.DWF, "J1", 3.0)
+        self.assertEqual(len(rows), 2)
+        rows.remove(WaterAgeSource.DWF, "J1")
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0].source, WaterAgeSource.EXTERNAL_INFLOW)
+
+    def test_remove_unknown_pair_raises(self):
+        s = self.opened_solver()
+        with self.assertRaises(BadIndexError):
+            s.water_age.node_overrides.remove(WaterAgeSource.DWF, "J2")
+
+    def test_scope_rule_refuses_non_dwf_non_external(self):
+        """Only DWF and EXTERNAL_INFLOW take NODE scope (the A1a rule)."""
+        s = self.opened_solver()
+        rows = s.water_age.node_overrides
+        before = len(rows)
+        for source in (WaterAgeSource.RAINFALL, WaterAgeSource.GW,
+                       WaterAgeSource.RDII, WaterAgeSource.IFACE,
+                       WaterAgeSource.INITIAL_STATE):
+            with self.subTest(source=source):
+                with self.assertRaises(BadParamError):
+                    rows.set(source, "J1", 5.0)
+                # Refused, not silently ignored: no row was written.
+                self.assertEqual(len(rows), before)
+
+    def test_unknown_node_raises_keyerror(self):
+        s = self.opened_solver()
+        with self.assertRaises(KeyError):
+            s.water_age.node_overrides.set(
+                WaterAgeSource.DWF, "NOPE", 1.0)
+
+
+# ---------------------------------------------------------------------------
+# save()
+# ---------------------------------------------------------------------------
+class TestWaterAgeSave(_WaterAgeCase):
+
+    def test_save_writes_a_component_file(self):
+        s = self.opened_solver()
+        s.water_age.globals[WaterAgeSource.RDII] = 7.5
+        out = os.path.join(_OUT_DIR, "water_age_saved.age")
+        s.water_age.save(out)
+        self.assertTrue(os.path.exists(out))
+        with open(out) as f:
+            text = f.read()
+        self.assertIn("[WATER_AGE_SOURCES]", text)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/engine/test_xsect_geometry.py b/python/tests/engine/test_xsect_geometry.py
index 95a523fc4..8b66f7941 100644
--- a/python/tests/engine/test_xsect_geometry.py
+++ b/python/tests/engine/test_xsect_geometry.py
@@ -1,8 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """Tests for XSectionGeometry, Links.get_xsect_info and the XSectShape enum.
 
 :author: Caleb Buahin
 :copyright: Copyright (c) 2026 Caleb Buahin
-:license: MIT
+:license: Apache-2.0
 """
 
 import math
diff --git a/python/tests/legacy/test_phase1_enum_coverage.py b/python/tests/legacy/test_phase1_enum_coverage.py
index ea3763db9..0d48b99f8 100644
--- a/python/tests/legacy/test_phase1_enum_coverage.py
+++ b/python/tests/legacy/test_phase1_enum_coverage.py
@@ -15,7 +15,7 @@
 
 
 class TestSubcatchmentEnumCoverage(unittest.TestCase):
-    """Verify all 48 subcatchment enum members exist and map to expected C values.
+    """Verify all 57 subcatchment enum members exist and map to expected C values.
 
     The C header (openswmm_solver.h) defines swmm_SubcatchProperty starting
     at 200 for AREA.  Each subsequent member increments by 1.
@@ -90,9 +90,14 @@ def test_trailing_properties(self):
         self.assertEqual(solver.SWMMSubcatchmentProperties.GW_MOISTURE.value, 249)
         self.assertEqual(solver.SWMMSubcatchmentProperties.SNOW_COLDC.value, 254)
 
+    def test_scale_factor_properties(self):
+        """Per-subcatchment rain/snow scale factors (255-256)."""
+        self.assertEqual(solver.SWMMSubcatchmentProperties.RAIN_SCALE_FACTOR.value, 255)
+        self.assertEqual(solver.SWMMSubcatchmentProperties.SNOW_SCALE_FACTOR.value, 256)
+
     def test_total_enum_member_count(self):
-        """All 55 subcatchment properties should be present."""
-        self.assertEqual(len(solver.SWMMSubcatchmentProperties), 55)
+        """All 57 subcatchment properties should be present."""
+        self.assertEqual(len(solver.SWMMSubcatchmentProperties), 57)
 
 
 class TestSystemEnumCoverage(unittest.TestCase):
diff --git a/python/tests/legacy/test_quality_sources.py b/python/tests/legacy/test_quality_sources.py
index 558cfce31..4c95bc92f 100644
--- a/python/tests/legacy/test_quality_sources.py
+++ b/python/tests/legacy/test_quality_sources.py
@@ -115,7 +115,16 @@ def _max_node_quality(s, max_steps):
 # --------------------------------------------------------------------------- #
 class TestRainConcentration(unittest.TestCase):
     def _peak_runoff_tss(self, rain_conc, name):
-        s = _open(_SITE_DRAINAGE, name)
+        # Isolate wet deposition: the shared model also contains initial
+        # buildup and land-use washoff, which otherwise produce TSS at zero rain concentration.
+        with open(_SITE_DRAINAGE) as source:
+            text = source.read()
+        text = re.sub(r"^\[(?:LOADINGS|BUILDUP|WASHOFF)\][^\[]*", "", text, flags=re.MULTILINE)
+        os.makedirs(_OUT_DIR, exist_ok=True)
+        path = os.path.join(_OUT_DIR, name + ".inp")
+        with open(path, "w") as destination:
+            destination.write(text)
+        s = _open(path, name)
         s.set_value(_PObj, _PProp.RAIN_CONCENTRATION, 0, rain_conc)
         subs = LegacySubcatchments(s)
         peak = 0.0
diff --git a/python/tests/minimal_features.py b/python/tests/minimal_features.py
new file mode 100644
index 000000000..10f6375b7
--- /dev/null
+++ b/python/tests/minimal_features.py
@@ -0,0 +1,23 @@
+"""Explicitly selected tests for a build with native optional features off."""
+import pytest
+import openswmm.engine as engine
+
+
+def test_minimal_package_exports():
+    assert not engine.HAS_2D
+    assert not engine.HAS_GEOPACKAGE
+    namespace = {}
+    exec('from openswmm.engine import *', namespace)
+    assert 'Surface2D' not in namespace
+    assert 'Groundwater' not in namespace
+    assert 'SurfaceQuality' not in namespace
+    assert 'GeoPackage' not in namespace
+    solver = engine.Solver()
+    try:
+        solver.create()
+        assert solver.handle
+        with pytest.raises(ImportError):
+            _ = solver.surface2d
+        assert solver.thread_info.logical_cpus >= 1
+    finally:
+        solver.destroy()
diff --git a/python/tests/test_2d_triangle_coupling.py b/python/tests/test_2d_triangle_coupling.py
index 6b49ad46e..d07422ca8 100644
--- a/python/tests/test_2d_triangle_coupling.py
+++ b/python/tests/test_2d_triangle_coupling.py
@@ -17,7 +17,7 @@
 import os
 import unittest
 
-from openswmm.engine import Solver
+from openswmm.engine import BadParamError, BadIndexError, Solver
 
 from ._paths import artifact_dir
 
@@ -129,13 +129,13 @@ def test_clear_removes_all_rows(self):
     def test_invalid_rows_raise(self):
         s = self._open_model("invalid")
         surf = s.surface2d
-        with self.assertRaises(RuntimeError):  # bad triangle index
+        with self.assertRaises(BadIndexError):  # bad triangle index
             surf.add_triangle_coupling(99, "J1", 0.65, 1.0)
-        with self.assertRaises(RuntimeError):  # empty node name
+        with self.assertRaises(BadParamError):  # empty node name
             surf.add_triangle_coupling(0, "", 0.65, 1.0)
-        with self.assertRaises(RuntimeError):  # non-positive cd
+        with self.assertRaises(BadParamError):  # non-positive cd
             surf.add_triangle_coupling(0, "J1", 0.0, 1.0)
-        with self.assertRaises(RuntimeError):  # non-positive area
+        with self.assertRaises(BadParamError):  # non-positive area
             surf.add_triangle_coupling(0, "J1", 0.65, -1.0)
         self.assertEqual(surf.triangle_coupling_rows, 0)
 
diff --git a/python/tests/test_2d_triangle_initial_state.py b/python/tests/test_2d_triangle_initial_state.py
index 62fd17a99..62f6d3de1 100644
--- a/python/tests/test_2d_triangle_initial_state.py
+++ b/python/tests/test_2d_triangle_initial_state.py
@@ -17,7 +17,7 @@
 import os
 import unittest
 
-from openswmm.engine import Solver
+from openswmm.engine import BadParamError, BadIndexError, Solver
 
 from ._paths import artifact_dir
 
@@ -111,9 +111,9 @@ def test_depth_round_trips(self):
 
     def test_invalid_depth_raises(self):
         surf = self._open_model("depth_invalid").surface2d
-        with self.assertRaises(RuntimeError):  # negative depth
+        with self.assertRaises(BadParamError):  # negative depth
             surf.set_triangle_init_depth(0, -0.1)
-        with self.assertRaises(RuntimeError):  # bad triangle index
+        with self.assertRaises(BadIndexError):  # bad triangle index
             surf.set_triangle_init_depth(99, 0.1)
         self.assertAlmostEqual(surf.get_triangle_init_depth(0), 0.0)
 
@@ -134,11 +134,11 @@ def test_velocity_round_trips(self):
 
     def test_invalid_velocity_raises(self):
         surf = self._open_model("vel_invalid").surface2d
-        with self.assertRaises(RuntimeError):  # non-finite u
+        with self.assertRaises(BadParamError):  # non-finite u
             surf.set_triangle_init_velocity(0, math.inf, 0.0)
-        with self.assertRaises(RuntimeError):  # non-finite v
+        with self.assertRaises(BadParamError):  # non-finite v
             surf.set_triangle_init_velocity(0, 0.0, math.nan)
-        with self.assertRaises(RuntimeError):  # bad triangle index
+        with self.assertRaises(BadIndexError):  # bad triangle index
             surf.set_triangle_init_velocity(99, 1.0, 1.0)
         self.assertEqual(surf.get_triangle_init_velocity(0), (0.0, 0.0))
 
diff --git a/python/tests/test_api_coverage.py b/python/tests/test_api_coverage.py
index 7b5a629e0..b9944030d 100644
--- a/python/tests/test_api_coverage.py
+++ b/python/tests/test_api_coverage.py
@@ -63,21 +63,16 @@
 # Keep this in sync with the ``intentional`` rows in
 # ``plans/parity/overrides.tsv``.
 # ---------------------------------------------------------------------------
-KNOWN_UNBOUND: frozenset[str] = frozenset({
-    # Error introspection — Python raises a typed ``EngineError`` instead of
-    # polling C-level last-error state, so these are never called directly.
-    # (The lenient-open accumulator API — swmm_get_error_count/at and
-    # swmm_get_warning_count/at — *is* bound, via ``Solver.open_errors`` /
-    # ``Solver.open_warnings``; only the single-shot last-error accessors and
-    # the static code→string lookup remain served by the exception layer.)
-    "swmm_error_message",
-    "swmm_get_last_error",
-    "swmm_get_last_error_msg",
-    # Current simulation time — declared in _common.pxd but intentionally not
-    # called; ``Solver.current_datetime`` derives it as start_datetime +
-    # elapsed (the C func returns elapsed seconds, not an OADate).
-    "swmm_get_current_time",
-})
+import importlib.util
+_spec = importlib.util.spec_from_file_location(
+    "_api_drift_audit", _PYTHON_DIR / "scripts/api_drift_audit.py")
+_audit = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_audit)
+KNOWN_UNBOUND = _audit.KNOWN_UNBOUND
+collect_c_functions = _audit.collect_c_functions
+collect_pyx_tokens = _audit.collect_pyx_tokens
+collect_pxd_functions = _audit.collect_pxd_functions
+executable_cython = _audit.executable_cython
 
 
 # Regex to extract C API symbol names from header declarations.  A declaration
@@ -98,69 +93,33 @@
 
 
 def _collect_c_symbols() -> set[str]:
-    """Return every C API symbol declared with ``SWMM_ENGINE_API``."""
-    assert _HEADER_GLOB.is_dir(), (
-        f"Header directory not found: {_HEADER_GLOB}.  Has the project "
-        f"layout changed?")
-    symbols: set[str] = set()
-    for header in sorted(_HEADER_GLOB.glob("*.h")):
-        if header.name.endswith("_export.h"):
-            continue
-        lines = header.read_text(encoding="utf-8").splitlines()
-        i = 0
-        while i < len(lines):
-            if lines[i].lstrip().startswith(_EXPORT_PREFIX):
-                buf = [lines[i]]
-                while ";" not in lines[i] and i + 1 < len(lines):
-                    i += 1
-                    buf.append(lines[i])
-                joined = re.sub(r"\s+", " ", " ".join(buf))
-                m = _C_FUNC_TOKEN.search(joined)
-                if m:
-                    symbols.add(m.group(1))
-            i += 1
-    return symbols
+    return set(collect_c_functions())
 
 
 def _collect_pyx_uses() -> set[str]:
-    """Return every ``swmm_*`` symbol *used* from ``.pyx`` sources.
-
-    "Used" = referenced outside of ``cdef extern`` declaration blocks and
-    outside of ``#`` comments — i.e. an actual call site or function-pointer
-    reference in the Python-facing layer.
-    """
-    assert _CYTHON_DIR.is_dir(), (
-        f"Cython source directory not found: {_CYTHON_DIR}.")
-    uses: set[str] = set()
-    for path in sorted(_CYTHON_DIR.glob("*.pyx")):
-        in_extern = False
-        extern_indent = 0
-        for raw in path.read_text(encoding="utf-8").splitlines():
-            code = raw.split("#", 1)[0]           # drop line comments
-            stripped = code.strip()
-            if _CDEF_EXTERN.match(stripped):
-                in_extern = True
-                extern_indent = len(code) - len(code.lstrip())
-                continue
-            if in_extern:
-                # extern block ends at the next non-blank line whose indent
-                # returns to <= the block-header indent.
-                if stripped and (len(code) - len(code.lstrip())) <= extern_indent:
-                    in_extern = False
-                else:
-                    continue
-            for m in _SWMM_TOKEN.finditer(code):
-                uses.add(m.group(1))
-    return uses
+    return collect_pyx_tokens()
 
 
 def _collect_pxd_decls() -> set[str]:
-    """Return every ``swmm_*`` symbol declared in ``.pxd`` extern blocks."""
-    decls: set[str] = set()
-    for path in sorted(_CYTHON_DIR.glob("*.pxd")):
-        for m in _SWMM_TOKEN.finditer(path.read_text(encoding="utf-8")):
-            decls.add(m.group(1))
-    return decls
+    return collect_pxd_functions()
+
+
+def test_collector_distinguishes_declarations_comments_and_helpers():
+    source = '\n'.join([
+        '"""swmm_doc_only()"""',
+        '# swmm_comment_only()',
+        'cdef extern from "swmm_header.h":',
+        '    int swmm_decl_only(int x)',
+        '',
+        'cdef inline int helper():',
+        '    return swmm_real_call(1)',
+        'callback = swmm_function_pointer',
+        'text = "swmm_string_only()"',
+    ])
+    uses = set(_SWMM_TOKEN.findall(executable_cython(source)))
+    assert uses == {"swmm_real_call", "swmm_function_pointer"}
+    decls = set(_SWMM_TOKEN.findall(executable_cython(source, declarations=True)))
+    assert decls == {"swmm_decl_only"}
 
 
 # ---------------------------------------------------------------------------
diff --git a/python/tests/test_catalog.py b/python/tests/test_catalog.py
new file mode 100644
index 000000000..821f174d6
--- /dev/null
+++ b/python/tests/test_catalog.py
@@ -0,0 +1,165 @@
+"""Engine catalog contract.
+
+``openswmm/engine/catalog.json`` is the machine-readable map of the Python API
+that the MCP server and gymnasium consume. Two guarantees are checked here:
+
+* **Source contract** (no compiled engine needed): the committed catalog equals
+  what ``python/scripts/gen_catalog.py`` generates from the current stubs,
+  Cython sources and headers; every public class is reachable or deliberately
+  excluded; every float field has a unit kind.
+* **Runtime contract** (compiled engine): every catalogued property and method
+  exists on its runtime class, every public runtime attribute is catalogued or
+  excluded, and every Solver-rooted target resolves on an opened model.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+import os
+import re
+import sys
+import unittest
+from pathlib import Path
+
+_PYTHON_DIR = Path(__file__).resolve().parents[1]
+_GENERATOR = _PYTHON_DIR / "scripts" / "gen_catalog.py"
+_CATALOG = _PYTHON_DIR / "openswmm" / "engine" / "catalog.json"
+
+try:
+    import openswmm.engine as _engine
+    from openswmm.engine import catalog as _catalog
+except ImportError:  # pragma: no cover - source-only environments
+    _engine = None
+    _catalog = None
+
+
+class CatalogSourceContract(unittest.TestCase):
+    def test_catalog_is_fresh_and_complete(self):
+        spec = importlib.util.spec_from_file_location("gen_catalog", _GENERATOR)
+        gen = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = gen
+        spec.loader.exec_module(gen)
+        self.assertEqual(gen.main(["--check"]), 0,
+                         "catalog.json is stale or incomplete; run python/scripts/gen_catalog.py")
+
+    def test_every_element_target_names_its_collection(self):
+        targets = json.loads(_CATALOG.read_text(encoding="utf-8"))["targets"]
+        for name, entry in targets.items():
+            if entry["path"].endswith("[]"):
+                self.assertIn("collection", entry, name)
+                self.assertIn(entry["collection"], targets, name)
+
+    def test_every_unit_kind_has_a_label(self):
+        """A new symbolic unit kind must get a label in catalog.py, in both systems."""
+        spec = importlib.util.spec_from_file_location("_catalog_src", _CATALOG.with_suffix(".py"))
+        src = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(src)
+        kinds = {m["units"] for m in json.loads(_CATALOG.read_text(encoding="utf-8"))["members"]
+                 if "units" in m}
+        # Anything else must look like a literal unit ("m3/s", "s", "1/day"), not a word.
+        unknown = sorted(k for k in kinds - src.UNIT_KINDS if re.fullmatch(r"[a-z_]{4,}", k))
+        self.assertEqual(unknown, [], "unit kinds without a label in catalog.py")
+        for kind in kinds & set(src._BY_SYSTEM):
+            for system in ("US", "SI"):
+                self.assertNotEqual(src.unit_label(kind, system), kind, f"{kind} ({system})")
+
+    def test_flow_label_takes_a_token_or_the_solver_enum(self):
+        import enum
+
+        spec = importlib.util.spec_from_file_location("_catalog_src", _CATALOG.with_suffix(".py"))
+        src = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(src)
+        flow_units = enum.IntEnum("FlowUnits", {"CFS": 0, "CMS": 3})
+        self.assertEqual(src.unit_label("flow", "US", "CFS"), "CFS")
+        self.assertEqual(src.unit_label("flow", "US", flow_units.CFS), "CFS")  # value 0
+        self.assertEqual(src.unit_label("flow", "SI", flow_units.CMS), "CMS")
+        self.assertEqual(src.unit_label("flow", "US"), "flow")
+
+
+@unittest.skipIf(_engine is None, "compiled openswmm.engine not installed")
+class CatalogRuntimeContract(unittest.TestCase):
+    def test_members_exist_on_runtime_classes(self):
+        missing = []
+        for name, entry in _catalog.targets().items():
+            module = importlib.import_module(f"openswmm.engine.{entry['module']}")
+            cls = getattr(module, entry["class"])
+            for m in _catalog.members(name):
+                if m["form"] == "item" or "variant" in m:
+                    continue
+                if not hasattr(cls, m["name"]):
+                    missing.append(m["path"])
+        self.assertEqual(missing, [], "catalog members absent at runtime")
+
+    # Collection mixins reach the engine through the synthesized items /
+    # get_item / set_item / delete_item members; ``solver`` is a back-reference.
+    _MIXINS = {"append", "clear", "count", "extend", "get", "index", "insert", "keys",
+               "pop", "popitem", "remove", "reverse", "setdefault", "solver", "update",
+               "values"}
+
+    def test_runtime_attributes_are_catalogued(self):
+        """The reverse of the check above: stubs cannot silently omit a public member."""
+        overrides = json.loads(
+            (_PYTHON_DIR / "scripts" / "catalog_overrides.json").read_text(encoding="utf-8")
+        )
+        excluded = set(overrides["exclude_members"])
+        targets = _catalog.targets()
+        unlisted = []
+        for name, entry in targets.items():
+            module = importlib.import_module(f"openswmm.engine.{entry['module']}")
+            cls = getattr(module, entry["class"])
+            prefix = "" if name == "solver" else name + "."
+            listed = {m["name"] for m in _catalog.members(name)} | {
+                t[len(prefix):] for t in targets
+                if t.startswith(prefix) and "." not in t[len(prefix):]
+            }
+            for attr in dir(cls):
+                if attr.startswith("_") or attr in listed or attr in self._MIXINS:
+                    continue
+                if f"{entry['class']}.{attr}" not in excluded:
+                    unlisted.append(f"{name}.{attr}")
+        self.assertEqual(unlisted, [], "public runtime attributes missing from the catalog")
+
+    def test_solver_targets_resolve_on_an_opened_model(self):
+        from tests._paths import SITE_DRAINAGE_INP, artifact_dir
+
+        out_dir = artifact_dir(self)
+        solver = _engine.Solver(SITE_DRAINAGE_INP, os.path.join(out_dir, "catalog.rpt"),
+                                os.path.join(out_dir, "catalog.out"))
+        solver.open()
+        try:
+            for name, entry in _catalog.targets().items():
+                if "construct" in entry or entry.get("subtypes"):
+                    continue
+                if name.startswith("surface2d") and not solver.surface2d.is_active:
+                    continue
+                key = None
+                if entry["path"].endswith("[]") or "[]." in entry["path"]:
+                    collection = _catalog.resolve(solver, _collection_of(entry))
+                    if len(collection) == 0:
+                        continue
+                    key = 0
+                with self.subTest(target=name):
+                    self.assertIsNotNone(_catalog.resolve(solver, name, key))
+        finally:
+            solver.close()
+
+    def test_lookup_reports_units_and_bulk_path(self):
+        entry = _catalog.lookup("node.depth")
+        self.assertEqual(entry["units"], "length")
+        self.assertEqual(entry["bulk"], "nodes.depths")
+        with self.assertRaises(KeyError):
+            _catalog.lookup("node.not_a_field")
+
+
+def _collection_of(entry: dict) -> str:
+    """Name of the collection target that owns an element (or sub-view) target."""
+    targets = _catalog.targets()
+    while "collection" not in entry:
+        entry = targets[entry["parent"]]
+    return entry["collection"]
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/python/tests/test_enum_drift.py b/python/tests/test_enum_drift.py
new file mode 100644
index 000000000..c929514c3
--- /dev/null
+++ b/python/tests/test_enum_drift.py
@@ -0,0 +1,67 @@
+"""Native numeric selectors must remain lossless in the Python API."""
+from pathlib import Path
+import re
+import pytest
+# Load the enum module without importing optional compiled extensions.
+import importlib.util
+_spec = importlib.util.spec_from_file_location("_binding_enums", Path(__file__).resolve().parents[1] / "openswmm/engine/_enums.py")
+_enums = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_enums)
+
+MAPPING = {'RunoffTotal': 'SWMM_RUNOFF_', 'RoutingTotal': 'SWMM_ROUTING_', 'RefType': 'SWMM_REF_', 'FilePathRole': 'SWMM_FILE_', 'ForcingType': 'SWMM_FORCE_', 'EvapType': 'SWMM_EVAP_', 'TempSource': 'SWMM_TEMP_', 'WindType': 'SWMM_WIND_', 'HumidityType': 'SWMM_HUMIDITY_', 'HumidityVar': 'SWMM_HUMIDITY_', 'HeatElemKind': 'SWMM_HEAT_ELEM_', 'InpProfile': 'SWMM_INP_PROFILE_', 'TransportDispersionMode': 'SWMM_DISPERSION_', 'UnitSystem': 'SWMM_'}
+
+@pytest.mark.parametrize("name,prefix", MAPPING.items())
+def test_native_enum_members(name, prefix):
+    headers = Path(__file__).resolve().parents[2] / "include/openswmm/engine"
+    text = "\n".join(p.read_text() for p in headers.glob("*.h"))
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+    match = re.search(r"typedef enum SWMM_" + name + r"\s*\{(.*?)\}", text, re.S)
+    assert match, name
+    values = re.findall(r"\b(" + prefix + r"\w+)\s*=\s*(-?\d+)", match[1])
+    assert values, name
+    enum = getattr(_enums, name)
+    for symbol, value in values:
+        member = symbol[len(prefix):]
+        assert enum.__members__[member].value == int(value), symbol
+
+
+def test_enum_stubs_match_runtime():
+    import ast
+    stub = Path(__file__).resolve().parents[1] / 'openswmm/engine/_enums.pyi'
+    for node in ast.parse(stub.read_text()).body:
+        if not isinstance(node, ast.ClassDef) or not hasattr(_enums, node.name):
+            continue
+        enum = getattr(_enums, node.name)
+        members = {stmt.targets[0].id: ast.literal_eval(stmt.value)
+                   for stmt in node.body if isinstance(stmt, ast.Assign)
+                   and isinstance(stmt.targets[0], ast.Name)}
+        assert members == {key: item.value for key, item in enum.__members__.items()}, node.name
+
+
+MACROS = {
+    'CellScope': ('SWMM_GW_SCOPE_', 'SWMM_GW2D_SCOPE_', 'SWMM_SQ2D_SCOPE_'),
+    'GroundwaterSoil': ('SWMM_GW2D_SOIL_',),
+    'GroundwaterClosure': ('SWMM_GW2D_CLOSURE_',),
+    'GroundwaterVariable': ('SWMM_GW2D_VAR_',),
+    'GroundwaterLedger': ('SWMM_GW2D_LED_',),
+    'GroundwaterZone': ('SWMM_GW2D_ZONE_',),
+    'GroundwaterSpeciesLedger': ('SWMM_GW2D_SPL_',),
+    'GroundwaterTransportZone': ('SWMM_GW_ZONE_',),
+    'TransportDomain': ('SWMM_TRANSPORT_DOMAIN_',),
+    'TransportClass': ('SWMM_TRANSPORT_CLASS_',),
+    'TransportState': ('SWMM_TRANSPORT_',),
+}
+
+@pytest.mark.parametrize('name,prefixes', MACROS.items())
+def test_native_macro_selectors(name, prefixes):
+    headers = Path(__file__).resolve().parents[2] / 'include/openswmm/engine'
+    text = '\n'.join(p.read_text() for p in headers.glob('*.h'))
+    enum = getattr(_enums, name)
+    for prefix in prefixes:
+        values = dict((symbol[len(prefix):], int(value)) for symbol, value in
+                      re.findall(r'^#define\s+(' + prefix + r'\w+)\s+\(?(-?\d+)\)?', text, re.M))
+        values.pop('COUNT', None)
+        if name == 'TransportState':
+            values = {key: value for key, value in values.items() if not key.startswith(('DOMAIN_', 'CLASS_'))}
+        assert values, prefix
+        assert values == {key: item.value for key, item in enum.__members__.items()}
diff --git a/python/tests/test_fv_routing_options.py b/python/tests/test_fv_routing_options.py
index 21cbbc15f..8d2159b6c 100644
--- a/python/tests/test_fv_routing_options.py
+++ b/python/tests/test_fv_routing_options.py
@@ -118,9 +118,6 @@ def test_every_key_round_trips(self):
                 "FV_COMPACTION": "NO",
                 "FV_BACKEND": "CPU",
                 "FV_MIN_PARALLEL_CELLS": "12345",
-                "FV_NODE_COUPLING": "EXPLICIT",
-                "FV_NODE_DT": "NONE",
-                "FV_NODE_PICARD": "3",
                 "FV_LTS": "NO",
                 "FV_LTS_MAX_TIERS": "5",
                 "FV_CFL_CENSUS_INTERVAL": "10",
@@ -152,12 +149,31 @@ def test_all_fv_keys_are_iterable(self):
                 "FV_ORDER", "FV_LIMITER", "FV_SCALAR_SCHEME",
                 "FV_TIME_INTEGRATION", "FV_SLOT_CELERITY", "FV_DISPERSION",
                 "FV_STRUCTURE_COUPLING", "FV_COMPACTION", "FV_BACKEND",
-                "FV_MIN_PARALLEL_CELLS",
+                "FV_MIN_PARALLEL_CELLS", "FV_PRESSURE_CLOSURE",
                 "FV_LTS", "FV_LTS_MAX_TIERS", "FV_CFL_CENSUS_INTERVAL",
-                "FV_NODE_COUPLING", "FV_NODE_DT", "FV_NODE_PICARD",
             },
         )
 
+    def test_retired_node_keys_read_frozen_and_accept_writes(self):
+        # FV_NODE_COUPLING / FV_NODE_DT / FV_NODE_PICARD were retired
+        # 2026-08-29: the getter reports the behaviour that is now built in,
+        # and a write is accepted and ignored so older scripts keep running.
+        inp, rpt, out = _write_model(self)
+        s = Solver(inp, rpt, out)
+        s.open()
+        try:
+            frozen = {
+                "FV_NODE_COUPLING": ("SEMI_IMPLICIT", "EXPLICIT"),
+                "FV_NODE_DT": ("STABILITY", "NONE"),
+                "FV_NODE_PICARD": ("1", "3"),
+            }
+            for key, (value, attempt) in frozen.items():
+                self.assertEqual(s.options[key], value, msg=key)
+                s.options[key] = attempt          # must not raise
+                self.assertEqual(s.options[key], value, msg=key)
+        finally:
+            s.close()
+
     def test_invalid_enum_value_is_rejected(self):
         # A silent no-op here would leave a user believing they had selected a
         # scheme they had not.
diff --git a/python/tests/typing/test_surface.py b/python/tests/typing/test_surface.py
index ccddec174..89e1fa1a3 100644
--- a/python/tests/typing/test_surface.py
+++ b/python/tests/typing/test_surface.py
@@ -36,8 +36,18 @@
     ForcingTarget,
     GageDataSource,
     GageRainType,
+    Heat,
+    HeatCloudParam,
+    HeatFluxModule,
+    HeatNodeOverride,
+    HeatRadiativeParam,
+    HeatShortwaveMode,
+    HeatSolarParam,
+    HeatSourceKind,
     HotStart,
     InfilModel,
+    InitialQuality,
+    InitialQualityEntry,
     LidType,
     LifecycleError,
     LinkType,
@@ -51,6 +61,18 @@
     OutSystemVar,
     OutputReader,
     PatternType,
+    ProcessComponent,
+    ProcessComponents,
+    ExpressionDiagnostic,
+    ReactionCoefficient,
+    ReactionExprForm,
+    ReactionFunction,
+    ReactionHydVar,
+    ReactionInitialEntry,
+    ReactionScope,
+    ReactionSpecies,
+    ReactionTerm,
+    Reactions,
     RouteModel,
     RoutingTotal,
     RunoffTotal,
@@ -59,6 +81,9 @@
     SurfaceBoundaryType,
     SurfaceForcingMode,
     WashoffFunc,
+    WaterAge,
+    WaterAgeOverride,
+    WaterAgeSource,
     WeirType,
     XSectShape,
     datetime_to_oadate,
@@ -173,12 +198,13 @@ def check_output_reader() -> None:
         fu: FlowUnits = out.flow_units
         nc: int = out.node_count
         ni: List[str] = out.node_ids
+        pi: List[str] = out.pollutant_ids
         pt: np.ndarray = out.period_times
         depths: np.ndarray = out.node_series("J1", OutNodeVar.DEPTH)
         attrs: Dict[OutNodeVar | int, float] = out.node_attributes("J1", 0)
         stats = out.node_stats("J1")
         md: float = stats.max_depth
-        _ = (sd, rs, fu, nc, ni, pt, depths, attrs, md)
+        _ = (sd, rs, fu, nc, ni, pi, pt, depths, attrs, md)
 
 
 def check_exceptions(s: Solver) -> None:
@@ -265,6 +291,278 @@ def check_enums() -> None:
     assert int(EngineState.CREATED) == 1
 
 
+def check_heat(s: Solver) -> None:
+    """``solver.heat`` — mappings return floats/bools, rows return NamedTuples."""
+    heat: Heat = s.heat
+    enabled: bool = heat.enabled
+
+    # [HEAT_FLUXES] toggles: bool in, bool out.
+    module_on: bool = heat.modules[HeatFluxModule.RADIATIVE_EXCHANGE]
+    heat.modules[HeatFluxModule.SURFACE_EXCHANGE] = True
+    heat.modules["LAYER_CONDUCTION"] = False
+    heat.modules[0] = True
+    n_modules: int = len(heat.modules)
+    for module in heat.modules:
+        module_member: HeatFluxModule = module
+        _ = module_member
+
+    # [RADIATIVE_FLUXES] / [SOLAR_RADIATION] / [CLOUD_COVER]: float mappings.
+    albedo: float = heat.radiative[HeatRadiativeParam.ALBEDO]
+    heat.radiative[HeatRadiativeParam.SHORTWAVE] = 250.0
+    latitude: float = heat.solar[HeatSolarParam.LATITUDE]
+    heat.solar[HeatSolarParam.LONGITUDE] = -111.83
+    sited: bool = heat.solar_sited
+    fraction: float = heat.cloud[HeatCloudParam.FRACTION]
+    heat.cloud[HeatCloudParam.LW_CLOUD_K] = 0.3
+    cloud_configured: bool = heat.cloud.configured
+    cloud_now: float = heat.cloud.current
+    heat.cloud.set_timeseries("cloud_ts")
+    heat.cloud.clear()
+
+    # Shortwave mode.
+    mode: HeatShortwaveMode = heat.shortwave_mode
+    heat.shortwave_mode = HeatShortwaveMode.CONSTANT
+    heat.set_shortwave_timeseries("sw_ts")
+    wm2: float = heat.current_shortwave
+
+    # [HEAT_SOURCES].
+    n_sources: int = len(heat.sources)
+    temp: float = heat.sources[HeatSourceKind.DWF]
+    heat.sources[HeatSourceKind.DWF] = 18.5
+    configured: bool = heat.sources.is_configured(HeatSourceKind.DWF)
+    heat.sources.clear(HeatSourceKind.DWF)
+    effective: float = heat.sources.effective(HeatSourceKind.DWF, "J1")
+    effective_by_index: float = heat.sources.effective(HeatSourceKind.DWF, 0)
+    in_table: bool = HeatSourceKind.DWF in heat.sources
+    for source in heat.sources:
+        source_member: HeatSourceKind = source
+        _ = source_member
+
+    # NODE overrides.
+    n_rows: int = len(heat.node_overrides)
+    row: HeatNodeOverride = heat.node_overrides[0]
+    row_source: HeatSourceKind = row.source
+    row_node: int = row.node_index
+    row_temp: float = row.temp_c
+    heat.node_overrides.set(HeatSourceKind.DWF, "J1", 22.0)
+    heat.node_overrides.remove(0)
+    for override in heat.node_overrides:
+        override_row: HeatNodeOverride = override
+        _ = override_row
+
+    _ = (enabled, module_on, n_modules, albedo, latitude, sited, fraction,
+         cloud_configured, cloud_now, mode, wm2, n_sources, temp, configured,
+         effective, effective_by_index, in_table, n_rows, row_source,
+         row_node, row_temp)
+
+
+def check_water_age(s: Solver) -> None:
+    """``solver.water_age`` — HOURS everywhere, signed."""
+    age: WaterAge = s.water_age
+    enabled: bool = age.enabled
+
+    n_sources: int = len(age.globals)
+    hours: float = age.globals[WaterAgeSource.DWF]
+    age.globals[WaterAgeSource.DWF] = 4.0
+    age.globals["GW"] = -2.5           # negative is legal (D-NS1)
+    age.globals[0] = 1.0
+    present: bool = WaterAgeSource.DWF in age.globals
+    for source in age.globals:
+        source_member: WaterAgeSource = source
+        _ = source_member
+
+    n_rows: int = len(age.node_overrides)
+    row: WaterAgeOverride = age.node_overrides[0]
+    row_source: WaterAgeSource = row.source
+    row_node: int = row.node_index
+    row_hours: float = row.hours
+    age.node_overrides.set(WaterAgeSource.EXTERNAL_INFLOW, "J0", 6.0)
+    age.node_overrides.set(WaterAgeSource.DWF, 0, -1.5)
+    age.node_overrides.remove(WaterAgeSource.DWF, "J0")
+    for override in age.node_overrides:
+        override_row: WaterAgeOverride = override
+        _ = override_row
+
+    age.save("saved.age")
+    age.save(Path("saved.age"))
+
+    _ = (enabled, n_sources, hours, present, n_rows, row_source, row_node,
+         row_hours)
+
+
+def check_initial_quality(s: Solver) -> None:
+    """``solver.initial_quality`` — the [INITIAL_QUALITY] row table."""
+    iq: InitialQuality = s.initial_quality
+    n: int = len(iq)
+    row: InitialQualityEntry = iq[0]
+    is_link: bool = row.is_link
+    elem: int = row.elem_index
+    constituent: str = row.constituent
+    value: float = row.value
+
+    water_age_name: str = InitialQuality.WATER_AGE
+    temperature_name: str = InitialQuality.TEMPERATURE
+
+    iq.set("TSS", 12.5, node="J1")
+    iq.set("TSS", 12.5, link="C1")
+    iq.set(water_age_name, -6.0, node=0)
+    iq.set(temperature_name, 18.5, link=0)
+    iq.remove(0)
+    for entry in iq:
+        entry_row: InitialQualityEntry = entry
+        _ = entry_row
+
+    _ = (n, is_link, elem, constituent, value, water_age_name,
+         temperature_name)
+
+
+def check_process_components(s: Solver) -> None:
+    """``solver.process_components`` — the [PROCESS_COMPONENTS] table."""
+    pcs: ProcessComponents = s.process_components
+    n: int = len(pcs)
+    by_index: ProcessComponent = pcs[0]
+    by_id: ProcessComponent = pcs["org.hydrocouple.openswmm.reactions"]
+    idx: int = by_index.component_index
+    cid: str = by_index.id
+    config: str = by_index.config
+    resolved: str = by_index.resolved
+    present: bool = "org.hydrocouple.openswmm.reactions" in pcs
+    found: int = pcs.get_index("org.hydrocouple.openswmm.reactions")
+    registered: ProcessComponent = pcs.register("my.component", "my.rxn")
+    bare: ProcessComponent = pcs.register("my.other.component")
+    pcs.remove(0)
+    pcs.remove("my.component")
+    for comp in pcs:
+        comp_row: ProcessComponent = comp
+        _ = comp_row
+
+    _ = (n, by_id, idx, cid, config, resolved, present, found, registered,
+         bare)
+
+
+def check_reactions(s: Solver) -> None:
+    """``solver.reactions`` — collections, expressions, and the text tab."""
+    rxn: Reactions = s.reactions
+
+    # Species.
+    n_species: int = len(rxn.species)
+    species: ReactionSpecies = rxn.species["X"]
+    by_index: ReactionSpecies = rxn.species[0]
+    sp_index: int = species.index
+    sp_name: str = species.name
+    sp_wall: bool = species.is_wall
+    sp_units: str = species.units
+    sp_atol: float = species.atol
+    sp_rtol: float = species.rtol
+    sp_initial: float = species.initial
+    species.initial = 0.5
+    pipe: Tuple[ReactionExprForm, str] = species.pipe_expression
+    tank: Tuple[ReactionExprForm, str] = species.tank_expression
+    got: Tuple[ReactionExprForm, str] = species.get_expression(
+        ReactionScope.PIPE)
+    species.set_expression(ReactionScope.PIPE, ReactionExprForm.RATE,
+                           "-Kb * X")
+    species.set_expression(ReactionScope.TANK, ReactionExprForm.NONE)
+    added_species: ReactionSpecies = rxn.species.add(
+        "Z", wall=True, units="MG", atol=1e-6, rtol=1e-6)
+    has_species: bool = "X" in rxn.species
+    species_index: int = rxn.species.get_index("X")
+    rxn.species.remove("Z")
+    for sp in rxn.species:
+        sp_row: ReactionSpecies = sp
+        _ = sp_row
+
+    # Coefficients.
+    n_coeffs: int = len(rxn.coefficients)
+    coeff: ReactionCoefficient = rxn.coefficients["Kb"]
+    coeff_index: int = coeff.index
+    coeff_name: str = coeff.name
+    coeff_is_param: bool = coeff.is_param
+    coeff_value: float = coeff.value
+    coeff.value = 0.05
+    added_coeff: ReactionCoefficient = rxn.coefficients.add(
+        "Kc", parameter=True, value=1.0)
+    has_coeff: bool = "Kb" in rxn.coefficients
+    coeff_idx: int = rxn.coefficients.get_index("Kb")
+    rxn.coefficients.remove("Kc")
+    for c in rxn.coefficients:
+        coeff_row: ReactionCoefficient = c
+        _ = coeff_row
+
+    # Terms.
+    n_terms: int = len(rxn.terms)
+    term: ReactionTerm = rxn.terms["Kf"]
+    term_index: int = term.index
+    term_name: str = term.name
+    term_expr: str = term.expression
+    term.expression = "0.5 * RE"
+    added_term: ReactionTerm = rxn.terms.add("Kg", "2.0 * D")
+    has_term: bool = "Kf" in rxn.terms
+    term_idx: int = rxn.terms.get_index("Kf")
+    rxn.terms.remove("Kg")
+    for t in rxn.terms:
+        term_row: ReactionTerm = t
+        _ = term_row
+
+    # Per-element initial quality.
+    n_initial: int = len(rxn.initial)
+    initial_row: ReactionInitialEntry = rxn.initial[0]
+    init_is_link: bool = initial_row.is_link
+    init_elem: int = initial_row.elem_index
+    init_species: int = initial_row.species_index
+    init_value: float = initial_row.value
+    rxn.initial.set(False, 0, "X", 3.0)
+    rxn.initial.set(True, 0, 0, 3.0)
+    rxn.initial.remove(0)
+    for entry in rxn.initial:
+        init_entry: ReactionInitialEntry = entry
+        _ = init_entry
+
+    # Validation, options, text tab.
+    diag: ExpressionDiagnostic = rxn.validate("-Kb * X", ReactionScope.PIPE)
+    default_scope: ExpressionDiagnostic = rxn.validate("-Kb * X")
+    diag_valid: bool = diag.valid
+    diag_message: str = diag.message
+    diag_column: int = diag.column
+    option: str = rxn.get_option("RATE_UNITS")
+    rxn.set_option("RATE_UNITS", "SEC")
+    text: str = rxn.serialize()
+    check: ExpressionDiagnostic = rxn.check_text(text)
+    rxn.apply_text(text)
+    rxn.save()
+    rxn.save("model.rxn")
+
+    # Engine-less statics: reachable on the CLASS, with no Solver at all.
+    hydvars: Tuple[ReactionHydVar, ...] = Reactions.hydraulic_variables()
+    functions: Tuple[ReactionFunction, ...] = Reactions.functions()
+    hv_name: str = hydvars[0].name
+    hv_desc: str = hydvars[0].description
+    fn_name: str = functions[0].name
+    fn_arity: int = functions[0].arity
+
+    _ = (n_species, by_index, sp_index, sp_name, sp_wall, sp_units, sp_atol,
+         sp_rtol, sp_initial, pipe, tank, got, added_species, has_species,
+         species_index, n_coeffs, coeff_index, coeff_name, coeff_is_param,
+         coeff_value, added_coeff, has_coeff, coeff_idx, n_terms, term_index,
+         term_name, term_expr, added_term, has_term, term_idx, n_initial,
+         init_is_link, init_elem, init_species, init_value, default_scope,
+         diag_valid, diag_message, diag_column, option, text, check,
+         hv_name, hv_desc, fn_name, fn_arity)
+
+
+def check_transport_enums() -> None:
+    # The nine transport enums are IntEnums with the C storage codes.
+    assert int(HeatFluxModule.SURFACE_EXCHANGE) == 0
+    assert int(HeatShortwaveMode.CONSTANT) == 0
+    assert int(HeatRadiativeParam.SHORTWAVE) == 0
+    assert int(HeatSolarParam.LATITUDE) == 0
+    assert int(HeatCloudParam.FRACTION) == 0
+    assert int(HeatSourceKind.RAINFALL) == 0
+    assert int(WaterAgeSource.RAINFALL) == 0
+    assert int(ReactionScope.TERM) == 0
+    assert int(ReactionExprForm.NONE) == 0
+
+
 def check_exception_subclasses() -> None:
     # Each subclass also inherits from a stdlib exception.
     assert issubclass(BadIndexError, IndexError)
@@ -274,3 +572,30 @@ def check_exception_subclasses() -> None:
     assert issubclass(CRSError, ValueError)
     assert issubclass(DependencyError, RuntimeError)
     assert issubclass(StaleObjectError, LifecycleError)
+
+
+def check_new_domain_contracts(solver: Solver) -> None:
+    from dataclasses import replace
+    from openswmm.engine import (
+        CellScope, GroundwaterParameters, GroundwaterInitialQuality,
+        GroundwaterVariable, GroundwaterZone, GroundwaterSpeciesLedger,
+        GroundwaterSource, GroundwaterSourceTerm, TransportDomain,
+        TransportClass, TransportState, InpProfile, HeatElemKind, ForcingType,
+    )
+    gw = solver.surface2d.groundwater
+    gw.transport.set_parameters(replace(GroundwaterParameters(), rho_s=2700))
+    gw.transport.set_initial_quality(GroundwaterInitialQuality(species='TSS', value=5))
+    gw.transport.set_source(GroundwaterSource(name='well', flow=1e-5))
+    gw.transport.set_source_species(0, GroundwaterSourceTerm(species='TSS', value=3))
+    row_name: str = gw.transport.sources[0].name
+    row_density: float = gw.transport.parameters[0].rho_s
+    level: float = gw.cell(0, GroundwaterVariable.HG)
+    concentration = gw.concentrations(GroundwaterZone.SAT, 0)
+    residual: float = gw.species_ledger(0, GroundwaterSpeciesLedger.RESIDUAL)
+    solver.surface2d.quality.set_coverage(CellScope.GLOBAL, {'URBAN': 100})
+    solver.surface2d.quality.set_loading(CellScope.CELL, 'TSS', 10, cell=0)
+    state: TransportState = solver.transport_matrix[TransportDomain.GROUNDWATER][TransportClass.POLLUTANTS].state
+    solver.forcing.element_climate(HeatElemKind.NODE, 'J1', ForcingType.ELEM_AIR_TEMPERATURE, 21)
+    solver.write_compat('compatible.inp', InpProfile.FULL)
+    solver.write_staged('final.inp', lambda path, kind: 'stage.inp')
+    _ = row_name, row_density, level, concentration, residual, state
diff --git a/scripts/build_macos_libomp.sh b/scripts/build_macos_libomp.sh
index 068cdf007..55ef9ecbd 100755
--- a/scripts/build_macos_libomp.sh
+++ b/scripts/build_macos_libomp.sh
@@ -13,7 +13,15 @@
 #
 # Env:
 #   MACOSX_DEPLOYMENT_TARGET  minimum macOS version (default 11.0)
-#   LLVM_OPENMP_VERSION       LLVM release to build (default 18.1.8)
+#   LLVM_OPENMP_VERSION       LLVM release to build (default 20.1.8)
+#
+# The default must stay >= 20.x: AppleClang 17 (on the macos-15 runners since
+# 2026-08) emits __kmpc_dispatch_deinit at the end of schedule(dynamic/guided)
+# loops (e.g. ExplicitFvSolver::updateCells), and that runtime entry point
+# first appeared in the LLVM 20 OpenMP runtime (present in 20.1.0's dllexports,
+# absent through 19.1.7) — linking an older libomp fails with
+# "Undefined symbols: ___kmpc_dispatch_deinit". The post-install check below
+# asserts the built dylib actually exports it.
 #
 # NOTE: this runs in CI on macOS runners; it needs cmake + ninja on PATH
 # (the caller's `brew install ninja` covers ninja; runners ship cmake).
@@ -25,7 +33,7 @@
 set -euo pipefail
 
 TARGET="${MACOSX_DEPLOYMENT_TARGET:-11.0}"
-LLVM_VER="${LLVM_OPENMP_VERSION:-18.1.8}"
+LLVM_VER="${LLVM_OPENMP_VERSION:-20.1.8}"
 
 case "$(uname -m)" in
   arm64)  ARCH=arm64;  PREFIX=/opt/homebrew/opt/libomp ;;
@@ -58,9 +66,28 @@ cmake -S "openmp-${LLVM_VER}.src" -B build-omp -G Ninja \
 
 cmake --build build-omp
 mkdir -p "${PREFIX}"
+# Drop stale artifacts from earlier installs (e.g. an old libomp.a — this
+# script only ships the dylib) so nothing outdated can be picked up.
+rm -f "${PREFIX}/lib/libomp.a"
 cmake --install build-omp
 
 echo ">>> installed:"
 ls -la "${PREFIX}/lib"
 # Confirm the produced dylib's minimum matches the requested target.
 otool -l "${PREFIX}/lib/libomp.dylib" | grep -A3 LC_BUILD_VERSION || true
+# Fail fast if the runtime predates the compiler's dispatch-loop codegen
+# (see the LLVM_OPENMP_VERSION note above) — a missing symbol here otherwise
+# surfaces much later as a cryptic engine link error.
+#
+# The symbol table is captured first and matched in-shell rather than piped
+# into `grep -q`. Under `set -o pipefail` that pipeline reports the producer's
+# status, and `grep -q` exits the moment it matches — which kills `nm` with
+# SIGPIPE (LLVM's nm prints "IO failure on output stream: Broken pipe") and
+# makes the pipeline fail EXACTLY WHEN THE SYMBOL IS PRESENT. The check
+# inverted itself: every macOS job failed here with the symbol in place.
+omp_syms="$(nm -g "${PREFIX}/lib/libomp.dylib")"
+if [[ "${omp_syms}" != *"___kmpc_dispatch_deinit"* ]]; then
+  echo "ERROR: libomp ${LLVM_VER} lacks ___kmpc_dispatch_deinit (need LLVM >= 20)" >&2
+  exit 1
+fi
+echo ">>> ___kmpc_dispatch_deinit present"
diff --git a/scripts/build_manual_figures.py b/scripts/build_manual_figures.py
new file mode 100644
index 000000000..4675d8f06
--- /dev/null
+++ b/scripts/build_manual_figures.py
@@ -0,0 +1,898 @@
+#!/usr/bin/env python3
+"""Manual figure pipeline: one manifest, reproducible generators, a stdlib audit.
+
+    docs/figures/MANIFEST.tsv   every image any manual embeds, one row each
+    docs/figures/src//  one generator module per figure family
+    docs/figures/png|svg/       committed outputs of the generators
+    docs/figures/decks/         small in-tree models the simulated tier runs
+    docs/figures/cache/         git-ignored engine runs
+
+Subcommands
+  list        tabulate manifest rows            [--tier T] [--manual M] [--page P]
+  check       audit the manifest (stdlib only; scripts/lint_manual_docs.py calls it)
+  build       run generators                    [--tier synthetic|simulated|all]
+                                                [--only GLOB] [--out DIR]
+                                                [--skip-missing-deps] [--cli PATH]
+  run-decks   run every simulated-tier deck through the engine CLI and record
+              exit / seconds / continuity       [--cli PATH] [--out DIR]
+                                                [--max-seconds N] [--deck PATH]
+  clean-cache remove docs/figures/cache
+
+Manifest columns (tab-separated, `#` comments allowed):
+  fig_id      ^(eng|hydrology|hydraulics|quality|workflow)_[a-z0-9_]+$ ; unique
+  tier        synthetic  numpy/matplotlib only (may REQUIRE the openswmm package)
+              simulated  runs an in-tree deck through the engine first
+              external   committed image whose generator or data cannot live in-tree
+              legacy     EPA / hand-drawn figure, no generator
+  generator   path under docs/figures/ of a module defining build(sink), or -
+  inputs      ;-joined paths under docs/figures/ (decks, data), or -
+  file        path under docs/ of the embedded image; generated rows must use
+              figures/png/.png (an SVG twin is required beside it)
+  page_id     ;-joined @page ids that embed the file, or - (Doxyfile-only assets)
+  figure_no   n-m as printed in the caption, or -
+  caption     free text
+  provenance  where a legacy/external image came from; - for generated rows
+
+What `check` asserts (every one has a recorded negative test):
+  C1  every image a page embeds resolves to a row that lists that page
+  C2  every row's file exists; generated rows also have their SVG twin
+  C3  every row is embedded by every page it lists
+  C4  no image on disk lacks a row; no emf/wmf/bmp anywhere (browsers cannot render them)
+  C5  generated rows name a generator that exists and defines build(
+  C6  PNG width <= 1600 px and every image <= 400 KB (Doxygen embeds at 100 %)
+  C7  fig_id/tier/page_id/figure_no are well formed and unique
+  C8  simulated rows' inputs exist
+  C9  when a row carries a figure number, "Figure n-m" follows the embed within 5 lines
+  C11 docs/figures/status.py is self-consistent
+  C12 no two image directories hold the same basename — Doxygen copies images by
+      basename into one output directory, so a collision silently serves one
+      manual's figure on another manual's page
+  C13 every `
` block names a figure the
+      page embeds, is closed, and holds only well-formed
+      `@ref target "label"` lines
+      (fractions of the image, top-left origin, x0 < x1, y0 < y1)
+  C14 the interactive-diagram assets are wired: docs/custom/js/manual-interactive.js
+      exists, the Doxyfile ships it (HTML_EXTRA_FILES) and header.html loads it
+
+Hotspots: a generator calls sink.hotspot(fig_id, ax, x0, y0, x1, y1, ref, label)
+in data coordinates; save() converts the boxes to fractions of the saved PNG and
+`build` rewrites the page's fig-hotspots block (inserted after the caption) so
+the clickable regions never drift from the drawing. Under --out the blocks are
+reported but no page is touched.
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import importlib
+import importlib.util
+import os
+import re
+import shutil
+import struct
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS = ROOT / "docs"
+
+COLUMNS = ["fig_id", "tier", "generator", "inputs", "file", "page_id",
+           "figure_no", "caption", "provenance"]
+TIERS = {"synthetic", "simulated", "external", "legacy"}
+GENERATED = {"synthetic", "simulated"}
+FIG_ID_RE = re.compile(r"^(eng|hydrology|hydraulics|quality|workflow)_[a-z0-9_]+$")
+FIGURE_NO_RE = re.compile(r"^[0-9A-Z]+-[0-9]+$")
+IMAGE_EXT = {".png", ".jpg", ".jpeg", ".gif"}
+UNRENDERABLE = {".emf", ".wmf", ".bmp", ".tif", ".tiff"}
+MAX_WIDTH = 1600
+MAX_BYTES = 400 * 1024
+EXCLUDE_RE = re.compile(r"/SWMM[^/]*\.md$|/media/")
+EMBED_RE = re.compile(r"!\[[^\]]*\]\(([^) ]+)|]+src=\"([^\"]+)\"")
+DPI = 160
+HOTSPOT_DIV_RE = re.compile(r'^
\s*$')
+HOTSPOT_SPAN_RE = re.compile(
+    r'^'
+    r'@ref [A-Za-z0-9_]+ "[^"]+"\s*$')
+CAPTION_RE = re.compile(r"^(\*||)?Figure\s+[0-9A-Z]+-[0-9]+")
+
+
+# ── manifest ────────────────────────────────────────────────────────────────
+
+class Row(dict):
+    __getattr__ = dict.__getitem__
+
+    @property
+    def pages(self):
+        return [] if self["page_id"] == "-" else self["page_id"].split(";")
+
+    @property
+    def input_list(self):
+        return [] if self["inputs"] == "-" else self["inputs"].split(";")
+
+
+def load_manifest(path: Path):
+    rows, errors = [], []
+    for n, ln in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not ln.strip() or ln.startswith("#"):
+            continue
+        f = ln.split("\t")
+        if len(f) != len(COLUMNS):
+            errors.append(f"MANIFEST.tsv:{n}: {len(f)} columns, expected {len(COLUMNS)}")
+            continue
+        rows.append(Row(zip(COLUMNS, (x.strip() for x in f))))
+    return rows, errors
+
+
+def write_manifest(path: Path, rows):
+    lines = ["# " + "\t".join(COLUMNS),
+             "# One row per image any manual embeds. Audited by scripts/build_manual_figures.py check;",
+             "# the column contract is in that script's docstring. Keep rows sorted by fig_id."]
+    for r in sorted(rows, key=lambda r: r["fig_id"]):
+        lines.append("\t".join(r[c] for c in COLUMNS))
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+# ── docs tree helpers (stdlib) ──────────────────────────────────────────────
+
+def doxyfile_image_paths(docs: Path):
+    """IMAGE_PATH entries from docs/Doxyfile, resolved against docs/."""
+    text = (docs / "Doxyfile").read_text(errors="replace")
+    m = re.search(r"^IMAGE_PATH\s*=\s*(.*?)(?=^\S|\Z)", text, re.M | re.S)
+    if not m:
+        return []
+    value = m.group(1).replace("\\\n", " ")
+    return [(docs / p).resolve() for p in value.split() if p]
+
+
+def manual_md_files(docs: Path):
+    out = [p for p in (docs / "manuals").rglob("*.md") if not EXCLUDE_RE.search(str(p))]
+    if (docs / "authors.md").exists():
+        out.append(docs / "authors.md")
+    return sorted(out)
+
+
+def page_id_of(md: Path):
+    m = re.search(r"^@page +(\S+)", md.read_text(errors="replace"), re.M)
+    return m.group(1) if m else md.stem
+
+
+def page_index(docs: Path):
+    return {page_id_of(md): md for md in manual_md_files(docs)}
+
+
+def embeds(md: Path):
+    """(lineno, raw path) for every markdown image or  in the page."""
+    out = []
+    for n, ln in enumerate(md.read_text(errors="replace").splitlines(), 1):
+        for m in EMBED_RE.finditer(ln):
+            out.append((n, m.group(1) or m.group(2)))
+    return out
+
+
+def resolve_embed(docs: Path, md: Path, raw: str, image_dirs):
+    """The on-disk file an embed refers to, relative to docs/ — or an error.
+
+    Doxygen resolves by basename over IMAGE_PATH; the manuals write paths
+    relative to their own root (reference: `hydraulics/media/media/x.png`,
+    engine: `figures/x.png`). Try the citing manual's root, then docs/, then
+    the basename across the image directories (which must be unambiguous).
+    """
+    try:
+        parts = md.relative_to(docs / "manuals").parts
+        manual_root = docs / "manuals" / parts[0]
+    except ValueError:
+        manual_root = docs
+    for base in (manual_root, docs):
+        cand = base / raw
+        if cand.is_file():
+            return cand.resolve().relative_to(docs.resolve()).as_posix(), None
+    name = Path(raw).name
+    hits = [d / name for d in image_dirs if (d / name).is_file()]
+    if len(hits) == 1:
+        return hits[0].resolve().relative_to(docs.resolve()).as_posix(), None
+    if not hits:
+        return None, f"image {raw} not found under the manual root, docs/, or any IMAGE_PATH"
+    return None, f"image {raw} is ambiguous: {', '.join(h.relative_to(docs).as_posix() for h in hits)}"
+
+
+def png_size(path: Path):
+    with path.open("rb") as fh:
+        head = fh.read(24)
+    if len(head) < 24 or head[:8] != b"\x89PNG\r\n\x1a\n":
+        return None
+    return struct.unpack(">II", head[16:24])
+
+
+def normalise_dashes(s: str) -> str:
+    return s.replace("‑", "-").replace("–", "-").replace("‐", "-")
+
+
+def load_status(docs: Path):
+    path = docs / "figures" / "status.py"
+    if not path.exists():
+        return None
+    spec = importlib.util.spec_from_file_location("manual_status", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# ── check ───────────────────────────────────────────────────────────────────
+
+def check_manifest(docs=DOCS, verbose=False) -> int:
+    """Audit MANIFEST.tsv against the manuals and the image directories.
+
+    Prints one `ERROR figures: ...` line per problem and returns the count.
+    """
+    docs = Path(docs).resolve()
+    fig = docs / "figures"
+    manifest = fig / "MANIFEST.tsv"
+    errors = []
+
+    def err(msg):
+        errors.append(msg)
+        print(f"ERROR figures: {msg}")
+
+    if not manifest.exists():
+        err("docs/figures/MANIFEST.tsv is missing")
+        return 1
+    rows, load_errs = load_manifest(manifest)
+    for e in load_errs:
+        err(e)
+    image_dirs = doxyfile_image_paths(docs)
+    if not image_dirs:
+        err("docs/Doxyfile has no IMAGE_PATH")
+    pages = page_index(docs)
+
+    # C7 / C2 / C5 / C8 — row validity
+    by_file, seen_ids = {}, set()
+    for r in rows:
+        if not FIG_ID_RE.match(r.fig_id):
+            err(f"{r.fig_id}: fig_id must match {FIG_ID_RE.pattern}")
+        if r.fig_id in seen_ids:
+            err(f"{r.fig_id}: duplicate fig_id")
+        seen_ids.add(r.fig_id)
+        if r.tier not in TIERS:
+            err(f"{r.fig_id}: tier {r.tier!r} is not one of {sorted(TIERS)}")
+        if r.figure_no != "-" and not FIGURE_NO_RE.match(r.figure_no):
+            err(f"{r.fig_id}: figure_no {r.figure_no!r} must look like 3-8 or C-1, or -")
+        for p in r.pages:
+            if p not in pages:
+                err(f"{r.fig_id}: page_id {p} is not a known @page")
+        if r.file in by_file:
+            err(f"{r.fig_id}: file {r.file} already listed by {by_file[r.file].fig_id}")
+        by_file[r.file] = r
+        path = docs / r.file
+        if not path.is_file():
+            err(f"{r.fig_id}: file {r.file} does not exist")
+        if r.tier in GENERATED:
+            want = f"figures/png/{r.fig_id}"
+            if not (r.file == want + ".png" or r.file == want + ".gif"):
+                err(f"{r.fig_id}: generated rows must embed {want}.png (got {r.file})")
+            if not (fig / "svg" / f"{r.fig_id}.svg").is_file():
+                err(f"{r.fig_id}: SVG twin figures/svg/{r.fig_id}.svg is missing")
+            gen = fig / r.generator
+            if r.generator == "-" or not gen.is_file():
+                err(f"{r.fig_id}: generator {r.generator} does not exist under docs/figures/")
+            elif not re.search(r"^def build\(", gen.read_text(errors="replace"), re.M):
+                err(f"{r.fig_id}: generator {r.generator} defines no build(sink)")
+            if r.provenance != "-":
+                err(f"{r.fig_id}: generated rows carry no provenance (got {r.provenance!r})")
+        else:
+            if r.generator != "-":
+                err(f"{r.fig_id}: {r.tier} rows must have generator -, got {r.generator}")
+            if r.tier == "external" and r.provenance == "-":
+                err(f"{r.fig_id}: external rows must state their provenance")
+        for inp in r.input_list:
+            if not (fig / inp).exists():
+                err(f"{r.fig_id}: input {inp} does not exist under docs/figures/")
+        if r.tier == "simulated" and not r.input_list:
+            err(f"{r.fig_id}: simulated rows must name the deck they run in inputs")
+
+    # C1 / C3 / C9 — embeds vs rows
+    cited = defaultdict(set)
+    embed_lines = defaultdict(list)
+    embedded_ids = defaultdict(set)
+    for md in manual_md_files(docs):
+        pid = page_id_of(md)
+        rel = md.relative_to(docs).as_posix()
+        lines = md.read_text(errors="replace").splitlines()
+        for n, raw in embeds(md):
+            resolved, e = resolve_embed(docs, md, raw, image_dirs)
+            if e:
+                err(f"{rel}:{n}: {e}")
+                continue
+            row = by_file.get(resolved)
+            if row is None:
+                err(f"{rel}:{n}: {resolved} is embedded but has no MANIFEST.tsv row")
+                continue
+            if pid not in row.pages:
+                err(f"{rel}:{n}: {row.fig_id} is embedded by {pid}, which is not in its page_id")
+            cited[resolved].add(pid)
+            embed_lines[(resolved, pid)].append((rel, n, lines[n:n + 5]))
+            embedded_ids[rel].add(row.fig_id)
+        # C13 — hotspot blocks
+        i = 0
+        while i < len(lines):
+            m = HOTSPOT_DIV_RE.match(lines[i])
+            if lines[i].startswith('
= len(lines):
+                err(f"{rel}:{i + 1}: fig-hotspots block for {fid} is not closed by 
")
+            elif n_spans == 0:
+                err(f"{rel}:{i + 1}: fig-hotspots block for {fid} holds no hotspot")
+            i = j + 1
+    for r in rows:
+        for p in r.pages:
+            if p not in cited.get(r.file, ()):
+                err(f"{r.fig_id}: never embedded by {p}")
+    # C9: a row that claims a figure number must be captioned with it at least
+    # once. "At least once", not at every embed: the EPA manuals reuse a
+    # figure inline (an icon in a table, a sketch repeated in a later chapter)
+    # without repeating its caption, and that is not drift.
+    locs_by_file = defaultdict(list)
+    for (file, pid), locs in embed_lines.items():
+        locs_by_file[file] += locs
+    for file, locs in locs_by_file.items():
+        r = by_file[file]
+        if r.figure_no == "-":
+            continue
+        pat = re.compile(r"Figure\s+" + re.escape(r.figure_no) + r"(?![0-9])")
+        # embed lines are excluded from the window: a following image's
+        # `![](x.png "Figure 3-2")` title attribute is not this figure's caption
+        if not any(pat.search(normalise_dashes(" ".join(
+                ln for ln in window if not EMBED_RE.search(ln)))) for _, _, window in locs):
+            rel, n, _ = locs[0]
+            err(f"{rel}:{n}: no 'Figure {r.figure_no}' caption within 5 lines of any embed of {r.fig_id}")
+
+    # C4 / C12 — the image directories
+    basenames = defaultdict(list)
+    for d in image_dirs:
+        if not d.is_dir():
+            err(f"IMAGE_PATH directory {d.relative_to(docs) if d.is_relative_to(docs) else d} does not exist")
+            continue
+        for q in sorted(d.iterdir()):
+            if not q.is_file() or q.name.startswith("."):
+                continue
+            ext = q.suffix.lower()
+            rel = q.resolve().relative_to(docs).as_posix()
+            if ext in UNRENDERABLE:
+                err(f"{rel}: {ext} is not renderable by browsers — convert or delete")
+            if ext not in IMAGE_EXT:
+                continue
+            basenames[q.name].append(rel)
+            if rel not in by_file:
+                err(f"{rel} is on disk but has no MANIFEST.tsv row (orphan)")
+    for name, paths in sorted(basenames.items()):
+        if len(paths) > 1:
+            err(f"basename {name} exists in {len(paths)} IMAGE_PATH dirs ({'; '.join(paths)}) — "
+                f"Doxygen serves one of them on every page")
+
+    # C6 — bounds
+    for r in rows:
+        path = docs / r.file
+        if not path.is_file():
+            continue
+        size = path.stat().st_size
+        if size > MAX_BYTES:
+            err(f"{r.fig_id}: {r.file} is {size // 1024} KB (max {MAX_BYTES // 1024} KB)")
+        if path.suffix.lower() == ".png":
+            dims = png_size(path)
+            if dims is None:
+                err(f"{r.fig_id}: {r.file} is not a PNG")
+            elif dims[0] > MAX_WIDTH:
+                err(f"{r.fig_id}: {r.file} is {dims[0]} px wide (max {MAX_WIDTH})")
+
+    # C11 — status vocabulary
+    st = load_status(docs)
+    if st is None:
+        err("docs/figures/status.py is missing")
+    else:
+        for e in st.self_check():
+            err(e)
+
+    # C14 — the interactive-diagram assets are wired
+    js = docs / "custom" / "js" / "manual-interactive.js"
+    if not js.is_file():
+        err("docs/custom/js/manual-interactive.js is missing")
+    doxy = (docs / "Doxyfile").read_text(errors="replace") if (docs / "Doxyfile").exists() else ""
+    if "custom/js/manual-interactive.js" not in doxy:
+        err("docs/Doxyfile HTML_EXTRA_FILES does not ship custom/js/manual-interactive.js")
+    header = docs / "custom" / "html" / "header.html"
+    if not (header.is_file() and "manual-interactive.js" in header.read_text(errors="replace")):
+        err("docs/custom/html/header.html does not load manual-interactive.js")
+    css = docs / "custom" / "css" / "manual.css"
+    if not (css.is_file() and "fig-hotspots" in css.read_text(errors="replace")):
+        err("docs/custom/css/manual.css lacks the fig-hotspots rules")
+
+    if verbose or not errors:
+        n_gen = sum(1 for r in rows if r.tier in GENERATED)
+        print(f"figures: {len(rows)} rows ({n_gen} generated, "
+              f"{sum(1 for r in rows if r.tier == 'legacy')} legacy, "
+              f"{sum(1 for r in rows if r.tier == 'external')} external), "
+              f"{len(cited)} embedded files, {len(errors)} errors")
+    return len(errors)
+
+
+# ── build ───────────────────────────────────────────────────────────────────
+
+def find_cli(explicit=None):
+    """The openswmm CLI: --cli, $OPENSWMM_BIN, $OPENSWMM_BUILD_DIR, or a build/install tree."""
+    cands = []
+    if explicit:
+        cands.append(Path(explicit))
+    if os.environ.get("OPENSWMM_BIN"):
+        cands.append(Path(os.environ["OPENSWMM_BIN"]))
+    bd = os.environ.get("OPENSWMM_BUILD_DIR")
+    if bd:
+        for sub in ("bin/Release", "bin/Debug", "bin", "."):
+            cands.append(Path(bd) / sub / "openswmm")
+    cands += sorted(ROOT.glob("build*/bin/*/openswmm")) + sorted(ROOT.glob("build*/bin/openswmm"))
+    cands += sorted(ROOT.glob("install/*/bin/openswmm"))
+    for c in cands:
+        if c.is_file() and os.access(c, os.X_OK):
+            return c
+    return None
+
+
+def upsert_options(text: str, options: dict) -> str:
+    """Rewrite [OPTIONS] keys in an .inp (add the key if absent)."""
+    lines = text.splitlines()
+    out, in_opts, done = [], False, set()
+    for ln in lines:
+        s = ln.strip()
+        if s.startswith("["):
+            if in_opts:
+                for k, v in options.items():
+                    if k not in done:
+                        out.append(f"{k:<24}{v}")
+                out.append("")
+            in_opts = s.upper().startswith("[OPTIONS]")
+        elif in_opts and s and not s.startswith(";"):
+            key = s.split()[0].upper()
+            if key in options:
+                out.append(f"{key:<24}{options[key]}")
+                done.add(key)
+                continue
+        out.append(ln)
+    if in_opts:
+        for k, v in options.items():
+            if k not in done:
+                out.append(f"{k:<24}{v}")
+    return "\n".join(out) + "\n"
+
+
+class RunResult:
+    def __init__(self, inp, rpt, out, h5, seconds):
+        self.inp, self.rpt, self.out, self.h5, self.seconds = inp, rpt, out, h5, seconds
+
+
+class FigureSink:
+    """What a generator's build(sink) receives."""
+
+    def __init__(self, fig_dir: Path, expected_ids, out_dir: Path | None, cli):
+        self.fig_dir = fig_dir
+        self.expected = set(expected_ids)
+        self.png_dir = (out_dir or fig_dir) / "png" if out_dir else fig_dir / "png"
+        self.svg_dir = (out_dir or fig_dir) / "svg" if out_dir else fig_dir / "svg"
+        self.cli = cli
+        self.produced = set()
+        self.status = load_status(fig_dir.parent)
+        self._pending_hotspots = defaultdict(list)
+        self.hotspots = {}
+
+    def hotspot(self, fig_id: str, ax, x0, y0, x1, y1, ref: str, label: str):
+        """Register a clickable region of `fig_id`, in `ax` data coordinates.
+
+        `ref` is a Doxygen page id or anchor; `label` the link text. The
+        region is converted to fractions of the saved PNG by save().
+        """
+        if not ref or not label:
+            return
+        self._pending_hotspots[fig_id].append((ax, float(x0), float(y0), float(x1), float(y1), ref, label))
+
+    def _resolve_hotspots(self, fig, fig_id):
+        pending = self._pending_hotspots.pop(fig_id, [])
+        if not pending:
+            return
+        fig.canvas.draw()
+        renderer = fig.canvas.get_renderer()
+        tb = fig.get_tightbbox(renderer)            # inches, the same box bbox_inches="tight" saves
+        dpi = fig.dpi
+        boxes = []
+        for ax, x0, y0, x1, y1, ref, label in pending:
+            (px0, py0), (px1, py1) = ax.transData.transform([(x0, y0), (x1, y1)])
+            fx0 = (min(px0, px1) / dpi - tb.x0) / tb.width
+            fx1 = (max(px0, px1) / dpi - tb.x0) / tb.width
+            fy0 = (tb.y1 - max(py0, py1) / dpi) / tb.height
+            fy1 = (tb.y1 - min(py0, py1) / dpi) / tb.height
+            clip = lambda v: min(1.0, max(0.0, v))  # noqa: E731
+            fx0, fx1, fy0, fy1 = clip(fx0), clip(fx1), clip(fy0), clip(fy1)
+            if fx1 - fx0 < 1e-3 or fy1 - fy0 < 1e-3:
+                continue
+            boxes.append((round(fx0, 4), round(fy0, 4), round(fx1, 4), round(fy1, 4), ref, label))
+        self.hotspots[fig_id] = boxes
+
+    def save(self, fig, fig_id: str):
+        if fig_id not in self.expected:
+            raise RuntimeError(f"generator produced {fig_id}, which its manifest rows do not list")
+        import matplotlib.pyplot as plt
+        self.png_dir.mkdir(parents=True, exist_ok=True)
+        self.svg_dir.mkdir(parents=True, exist_ok=True)
+        png, svg = self.png_dir / f"{fig_id}.png", self.svg_dir / f"{fig_id}.svg"
+        self._resolve_hotspots(fig, fig_id)
+        # pad_inches=0: the canvases carry their own margins, and the default
+        # 0.1 in pad would push a 10 in figure past the 1600 px bound
+        fig.savefig(png, dpi=DPI, bbox_inches="tight", pad_inches=0, metadata={"Software": None})
+        self._shrink_png(png)
+        with_salt = {"svg.hashsalt": fig_id}
+        import matplotlib
+        with matplotlib.rc_context(with_salt):
+            fig.savefig(svg, format="svg", bbox_inches="tight", pad_inches=0,
+                        metadata={"Date": None, "Creator": None})
+        plt.close(fig)
+        self.produced.add(fig_id)
+        print(f"  wrote {png.name} ({png.stat().st_size // 1024} KB) + {svg.name}")
+
+    @staticmethod
+    def _shrink_png(png: Path):
+        """Lossless re-encode; if still over the byte bound, quantise to a 256-colour palette.
+
+        Diagrams are flat colour and text, so a palette costs nothing visible
+        and halves the file. A figure that stays over the bound after that is
+        drawn too large: the build's bounds check reports it.
+        """
+        from PIL import Image
+        with Image.open(png) as im:
+            im.load()
+            im.save(png, optimize=True)
+            if png.stat().st_size > MAX_BYTES:
+                im.convert("RGB").quantize(colors=256, method=Image.Quantize.MEDIANCUT).save(png, optimize=True)
+                print(f"  note: {png.name} quantised to 256 colours to stay under {MAX_BYTES // 1024} KB")
+
+    def run(self, deck: str, options: dict | None = None, key: str | None = None,
+            sidecars: dict | None = None, text: str | None = None) -> RunResult:
+        """Run docs/figures/decks/ through the engine, cached under docs/figures/cache.
+
+        `options` upserts `[OPTIONS]` keys. `sidecars` maps a file name beside the
+        deck to replacement text, for the keys that live in a process component's
+        own configuration file rather than in the deck — a variant over
+        `[TRANSPORT_OPTIONS] TARGET_DX`, say. `text` replaces the deck text
+        outright, for a key in some other section of the deck itself, such as
+        `[2D_OPTIONS] MOMENTUM_EQUATION`; the generator is then responsible for
+        deriving it from the committed deck rather than inventing a model. All
+        three take part in the cache check.
+        """
+        src = self.fig_dir / "decks" / deck
+        if not src.is_file():
+            raise FileNotFoundError(f"deck {deck} is not under docs/figures/decks/")
+        key = key or (re.sub(r"[^A-Za-z0-9]+", "_", "_".join(f"{k}{v}" for k, v in sorted((options or {}).items()))) or "base")
+        work = self.fig_dir / "cache" / Path(deck).stem / key
+        work.mkdir(parents=True, exist_ok=True)
+        inp, rpt, out = work / "model.inp", work / "model.rpt", work / "model.out"
+        text = src.read_text(errors="replace") if text is None else text
+        if options:
+            text = upsert_options(text, {k.upper(): v for k, v in options.items()})
+        for sidecar in src.parent.iterdir():
+            if sidecar.is_file() and sidecar != src and not (work / sidecar.name).exists():
+                shutil.copy2(sidecar, work / sidecar.name)
+        stale = False
+        for name, body in (sidecars or {}).items():
+            target = work / name
+            if not target.exists() or target.read_text(errors="replace") != body:
+                target.write_text(body)
+                stale = True
+        if (not stale and inp.exists() and inp.read_text(errors="replace") == text
+                and rpt.exists() and out.exists()):
+            return RunResult(inp, rpt, out, next(work.glob("*.h5"), None), 0.0)
+        inp.write_text(text)
+        cli = find_cli(self.cli)
+        if cli is None:
+            raise RuntimeError("no openswmm CLI: pass --cli, set OPENSWMM_BIN or OPENSWMM_BUILD_DIR")
+        t0 = time.time()
+        p = subprocess.run([str(cli), inp.name, rpt.name, out.name], cwd=work,
+                           capture_output=True, text=True)
+        secs = time.time() - t0
+        if p.returncode != 0:
+            raise RuntimeError(f"{cli.name} failed on {deck} [{key}] (exit {p.returncode}):\n{p.stdout[-800:]}{p.stderr[-800:]}")
+        return RunResult(inp, rpt, out, next(work.glob("*.h5"), None), secs)
+
+
+def load_generator(path: Path):
+    spec = importlib.util.spec_from_file_location(f"manual_fig_{path.stem}", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def hotspot_block(fig_id: str, boxes) -> list:
+    lines = [f'
']
+    for x0, y0, x1, y1, ref, label in boxes:
+        label = label.replace('"', "'")
+        lines.append(f'@ref {ref} "{label}"')
+    lines.append("
")
+    return lines
+
+
+def upsert_hotspot_blocks(docs: Path, row, boxes) -> list:
+    """Write (or rewrite) the fig-hotspots block after the figure's caption on every page the row lists.
+
+    Returns the pages changed. A page that embeds the figure without a caption
+    line within five lines gets the block right after the embed.
+    """
+    pages = page_index(docs)
+    changed = []
+    block = hotspot_block(row.fig_id, boxes)
+    for pid in row.pages:
+        md = pages.get(pid)
+        if md is None:
+            continue
+        text = md.read_text(errors="replace")
+        lines = text.split("\n")
+        out, i, done = [], 0, False
+        while i < len(lines):
+            ln = lines[i]
+            out.append(ln)
+            m = EMBED_RE.search(ln)
+            if not done and m and Path(m.group(1) or m.group(2)).name == f"{row.fig_id}.png":
+                # find the caption line within the next five lines
+                j = i + 1
+                cap = None
+                for k in range(i + 1, min(i + 6, len(lines))):
+                    if CAPTION_RE.match(lines[k].strip()):
+                        cap = k
+                        break
+                end = cap if cap is not None else i
+                out.extend(lines[i + 1:end + 1])
+                j = end + 1
+                # an existing block (after optional blank lines) is replaced
+                k = j
+                while k < len(lines) and not lines[k].strip():
+                    k += 1
+                if k < len(lines) and HOTSPOT_DIV_RE.match(lines[k]) and HOTSPOT_DIV_RE.match(lines[k]).group(1) == row.fig_id:
+                    e = k
+                    while e < len(lines) and lines[e].strip() != "
":
+                        e += 1
+                    out.extend(lines[j:k])
+                    out.extend(block)
+                    i = e + 1
+                else:
+                    out.append("")
+                    out.extend(block)
+                    i = j
+                done = True
+                continue
+            i += 1
+        new = "\n".join(out)
+        if done and new != text:
+            md.write_text(new)
+            changed.append(md.relative_to(docs).as_posix())
+    return changed
+
+
+def cmd_build(args) -> int:
+    docs = DOCS
+    fig = docs / "figures"
+    rows, errs = load_manifest(fig / "MANIFEST.tsv")
+    if errs:
+        for e in errs:
+            print("ERROR", e)
+        return 1
+    tiers = GENERATED if args.tier == "all" else {args.tier}
+    by_gen = defaultdict(list)
+    for r in rows:
+        if r.tier in tiers and (not args.only or fnmatch.fnmatch(r.fig_id, args.only)):
+            by_gen[r.generator].append(r)
+    if not by_gen:
+        print(f"no {args.tier} rows match" + (f" {args.only}" if args.only else ""))
+        return 0
+    sys.path.insert(0, str(fig))
+    try:
+        import style  # noqa: F401  (vendored house style; sets the Agg backend)
+        style.apply_rc()
+    except ImportError as exc:
+        print(f"ERROR figures: cannot import docs/figures/style.py ({exc}); install matplotlib")
+        return 1
+    out_dir = Path(args.out).resolve() if args.out else None
+    ran, skipped, failures = 0, [], 0
+    for gen, grp in sorted(by_gen.items()):
+        path = fig / gen
+        print(f"== {gen}  ({', '.join(r.fig_id for r in grp)})")
+        try:
+            mod = load_generator(path)
+        except ImportError as exc:
+            if args.skip_missing_deps:
+                skipped.append(f"{gen}: {exc}")
+                continue
+            print(f"ERROR figures: {gen}: {exc}")
+            failures += 1
+            continue
+        missing = [m for m in getattr(mod, "REQUIRES", ()) if importlib.util.find_spec(m) is None]
+        if missing:
+            if args.skip_missing_deps:
+                skipped.append(f"{gen}: requires {', '.join(missing)}")
+                continue
+            print(f"ERROR figures: {gen} requires {', '.join(missing)}")
+            failures += 1
+            continue
+        sink = FigureSink(fig, [r.fig_id for r in grp], out_dir, args.cli)
+        try:
+            mod.build(sink)
+        except Exception as exc:  # a generator that throws is a failed gate, not a crash
+            print(f"ERROR figures: {gen} raised {type(exc).__name__}: {exc}")
+            failures += 1
+            continue
+        want = {r.fig_id for r in grp}
+        if sink.produced != want:
+            print(f"ERROR figures: {gen} produced {sorted(sink.produced)} but the manifest lists {sorted(want)}")
+            failures += 1
+        for fid, boxes in sorted(sink.hotspots.items()):
+            row = next(r for r in grp if r.fig_id == fid)
+            if out_dir is not None:
+                print(f"  {fid}: {len(boxes)} hotspots (not written under --out)")
+                continue
+            changed = upsert_hotspot_blocks(docs, row, boxes)
+            print(f"  {fid}: {len(boxes)} hotspots" + (f" -> {', '.join(changed)}" if changed else " (pages unchanged)"))
+        for fid in sink.produced:
+            png = sink.png_dir / f"{fid}.png"
+            dims = png_size(png)
+            if dims and dims[0] > MAX_WIDTH:
+                print(f"ERROR figures: {fid}.png is {dims[0]} px wide (max {MAX_WIDTH})")
+                failures += 1
+            if png.stat().st_size > MAX_BYTES:
+                print(f"ERROR figures: {fid}.png is {png.stat().st_size // 1024} KB (max {MAX_BYTES // 1024})")
+                failures += 1
+        ran += 1
+    for s in skipped:
+        print(f"skipped {s}")
+    if ran == 0 and not failures:
+        print("ERROR figures: no generator ran (all skipped)")
+        return 1
+    print(f"\n{ran} generators ran, {len(skipped)} skipped, {failures} failures")
+    return 1 if failures else 0
+
+
+# ── run-decks ───────────────────────────────────────────────────────────────
+
+CONTINUITY_RE = re.compile(r"Continuity Error \(%\)\s*\.+\s*([-+0-9.]+)")
+
+
+def run_one_deck(cli: Path, deck: Path, work: Path, max_seconds: float):
+    work.mkdir(parents=True, exist_ok=True)
+    for sidecar in deck.parent.iterdir():
+        if sidecar.is_file():
+            shutil.copy2(sidecar, work / sidecar.name)
+    inp = work / deck.name
+    rpt, out = work / "model.rpt", work / "model.out"
+    t0 = time.time()
+    try:
+        p = subprocess.run([str(cli), inp.name, rpt.name, out.name], cwd=work,
+                           capture_output=True, text=True, timeout=max_seconds)
+        code, timed_out = p.returncode, False
+        (work / "stdout.txt").write_text(p.stdout + p.stderr)
+    except subprocess.TimeoutExpired:
+        code, timed_out = 124, True
+    secs = time.time() - t0
+    rpt_text = rpt.read_text(errors="replace") if rpt.exists() else ""
+    rpt_errors = [ln.strip() for ln in rpt_text.splitlines() if ln.strip().startswith("ERROR")]
+    cont = CONTINUITY_RE.findall(rpt_text)
+    ok = code == 0 and not rpt_errors and not timed_out
+    return ok, code, secs, rpt_errors, cont, timed_out
+
+
+def cmd_run_decks(args) -> int:
+    fig = DOCS / "figures"
+    cli = find_cli(args.cli)
+    if cli is None:
+        print("ERROR decks: no openswmm CLI: pass --cli, set OPENSWMM_BIN or OPENSWMM_BUILD_DIR")
+        return 1
+    if args.deck:
+        decks = [Path(args.deck).resolve()]
+    else:
+        rows, errs = load_manifest(fig / "MANIFEST.tsv")
+        decks = sorted({(fig / i).resolve() for r in rows if r.tier == "simulated"
+                        for i in r.input_list if i.endswith(".inp")})
+    out = Path(args.out).resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    if not decks:
+        print("run-decks: no simulated-tier decks in the manifest — nothing to run")
+        (out / "summary.tsv").write_text("deck\texit\tseconds\tcontinuity\tnote\n")
+        return 0
+    lines = ["deck\texit\tseconds\tcontinuity\tnote"]
+    failures = 0
+    for deck in decks:
+        work = out / deck.parent.name / deck.stem
+        ok, code, secs, rpt_errors, cont, timed_out = run_one_deck(cli, deck, work, args.max_seconds)
+        note = "timeout" if timed_out else ("; ".join(rpt_errors)[:120] if rpt_errors else "ok")
+        lines.append(f"{deck.relative_to(fig) if deck.is_relative_to(fig) else deck}\t{code}\t{secs:.1f}\t{','.join(cont)}\t{note}")
+        print(f"{'PASS' if ok else 'FAIL'}  {deck.name}  exit={code}  {secs:.1f}s  {note}")
+        failures += 0 if ok else 1
+    (out / "summary.tsv").write_text("\n".join(lines) + "\n")
+    print(f"\n{len(decks)} decks, {failures} failures — {out / 'summary.tsv'}")
+    return 1 if failures else 0
+
+
+# ── list / clean ────────────────────────────────────────────────────────────
+
+def cmd_list(args) -> int:
+    rows, errs = load_manifest(DOCS / "figures" / "MANIFEST.tsv")
+    for e in errs:
+        print("ERROR", e)
+    for r in sorted(rows, key=lambda r: r["fig_id"]):
+        if args.tier and r.tier != args.tier:
+            continue
+        if args.manual and not r.fig_id.startswith(args.manual + "_"):
+            continue
+        if args.page and args.page not in r.pages:
+            continue
+        print(f"{r.fig_id:48} {r.tier:10} {r.figure_no:6} {r.file}")
+    return 1 if errs else 0
+
+
+def cmd_clean_cache(args) -> int:
+    cache = DOCS / "figures" / "cache"
+    if cache.exists():
+        shutil.rmtree(cache)
+        print(f"removed {cache}")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Manual figure pipeline",
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("list")
+    p.add_argument("--tier")
+    p.add_argument("--manual")
+    p.add_argument("--page")
+    p = sub.add_parser("check")
+    p.add_argument("--docs-root", default=str(DOCS))
+    p.add_argument("-v", "--verbose", action="store_true")
+    p = sub.add_parser("build")
+    p.add_argument("--tier", default="synthetic", choices=["synthetic", "simulated", "all"])
+    p.add_argument("--only", help="glob on fig_id")
+    p.add_argument("--out", help="write png/ and svg/ under this directory instead of docs/figures/")
+    p.add_argument("--skip-missing-deps", action="store_true")
+    p.add_argument("--cli", help="openswmm executable for the simulated tier")
+    p = sub.add_parser("run-decks")
+    p.add_argument("--cli")
+    p.add_argument("--out", default=str(ROOT / "tests" / "output" / "manual_decks"))
+    p.add_argument("--max-seconds", type=float, default=600)
+    p.add_argument("--deck", help="run this one deck instead of the manifest's simulated decks")
+    sub.add_parser("clean-cache")
+    args = ap.parse_args(argv)
+    if args.cmd == "list":
+        return cmd_list(args)
+    if args.cmd == "check":
+        return 1 if check_manifest(Path(args.docs_root), verbose=args.verbose) else 0
+    if args.cmd == "build":
+        return cmd_build(args)
+    if args.cmd == "run-decks":
+        return cmd_run_decks(args)
+    if args.cmd == "clean-cache":
+        return cmd_clean_cache(args)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/check_version_sync.py b/scripts/check_version_sync.py
index 48ef01b35..554f7dc12 100755
--- a/scripts/check_version_sync.py
+++ b/scripts/check_version_sync.py
@@ -5,11 +5,13 @@
 all three from one file (which would mean a fragile dynamic-version refactor of
 the CMake + scikit-build-core build), we keep the three declarations and gate
 them with this check in CI. They must normalize to the same (base, phase, num).
+Python wheels may add a .devN suffix before that native release; both Python
+packages and the companion dependency pin must share the exact full version.
 
 Sources:
   - CMakeLists.txt          project(... VERSION X.Y.Z) + OPENSWMM_PRERELEASE
   - vcpkg.json              "version-semver": "X.Y.Z-."
-  - python/pyproject.toml   [project] version = "X.Y.Z"  (PEP 440)
+  - python/pyproject.toml   [project] version = "X.Y.Z[.devN]"  (PEP 440)
 
 Run: python scripts/check_version_sync.py   (exit 0 = in sync, 1 = mismatch)
 """
@@ -51,9 +53,17 @@ def from_vcpkg(p: Path) -> tuple[str, str, int]:
     return _norm(base, phase, num)
 
 
+def python_version(p: Path) -> str:
+    """Read the complete Python release, including its development suffix."""
+    return re.search(r'^version\s*=\s*"([^"]+)"', p.read_text(), re.MULTILINE).group(1)
+
+
 def from_pyproject(p: Path) -> tuple[str, str, int]:
-    ver = re.search(r'^version\s*=\s*"([^"]+)"', p.read_text(), re.MULTILINE).group(1)
-    m = re.match(r"([0-9]+\.[0-9]+\.[0-9]+)(?:(a|b|rc)([0-9]+))?$", ver)
+    """Match the native release while allowing a Python-only .devN suffix."""
+    ver = python_version(p)
+    m = re.fullmatch(r"([0-9]+\.[0-9]+\.[0-9]+)(?:(a|b|rc)([0-9]+))?(?:\.dev[0-9]+)?", ver)
+    if m is None:
+        raise ValueError(f"Unsupported Python package version in {p}: {ver}")
     base, phase, num = m.groups()
     return _norm(base, phase, num)
 
@@ -77,11 +87,16 @@ def main() -> int:
     # its `openswmm == ` dependency pin; that pin must track the shared
     # version too (the pyproject `version =` check above only covers the
     # companion's OWN version).
-    companion = (ROOT / "packages" / "gpu-omp" / "pyproject.toml").read_text()
-    pin = re.search(r'openswmm\s*==\s*([^"\'\s]+)', companion)
-    base_ver = re.search(r'^version\s*=\s*"([^"]+)"',
-                         (ROOT / "python" / "pyproject.toml").read_text(),
-                         re.MULTILINE).group(1)
+    companion_path = ROOT / "packages" / "gpu-omp" / "pyproject.toml"
+    base_ver = python_version(ROOT / "python" / "pyproject.toml")
+    companion_ver = python_version(companion_path)
+    if companion_ver != base_ver:
+        print(f"\nERROR: gpu-omp version {companion_ver} differs from base {base_ver}.",
+              file=sys.stderr)
+        return 1
+    print(f"  Python packages                  -> {base_ver} (exact match)")
+    companion = companion_path.read_text()
+    pin = re.search(r"openswmm\s*==\s*([^\"'\s]+)", companion)
     if not pin or pin.group(1) != base_ver:
         print(f"\nERROR: gpu-omp companion pins 'openswmm == "
               f"{pin.group(1) if pin else '?'}' but base is {base_ver}.",
diff --git a/scripts/gen_manual_frontmatter.py b/scripts/gen_manual_frontmatter.py
new file mode 100644
index 000000000..7b104b85d
--- /dev/null
+++ b/scripts/gen_manual_frontmatter.py
@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Generate the reference manuals' List of Figures and List of Tables from
+the captions in their chapters.
+
+    scripts/gen_manual_frontmatter.py --write    rewrite the generated blocks
+    scripts/gen_manual_frontmatter.py --check    fail (exit 1) if they are stale
+
+The source of truth is the caption line under each figure or table, written
+either as `*Figure 8-1 …*` or `Figure 8-1 …`. Chapters are
+visited in the order the manual's `@subpage` list names them, so the lists
+follow the book. The manifest is deliberately NOT the source: legacy figures
+carry captions and no manifest figure number, and a table has no manifest row
+at all.
+
+Each list lives between markers, which the first `--write` inserts around the
+existing list:
+
+    ## List of Figures
+    
+    ...
+    
+
+Each manual keeps the entry style it already uses — `- **Figure 1-1** text`,
+`Figure 1-1. text` or `Figure 1-1 text` — detected from the entries found
+before the first rewrite and then pinned by the marker comment.
+
+Numbers must be unique within a chapter. Gaps are reported but allowed: a
+chapter may cite a figure numbered to match its sibling manuals.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS = ROOT / "docs"
+MANUALS = ["hydraulics", "hydrology", "quality"]
+
+# A caption is a line of its own, either marked up (**…**, *…*, …)
+# or — for the legacy chapters that never marked theirs — a bare line directly
+# under the image it captions.
+CAPTION_RE = re.compile(r"^(?:\*\*|\*|)(Figure|Table)\s+([0-9A-Z]+[-‑][0-9]+)\s+(.+?)"
+                        r"(?:\*\*|\*|)\s*$")
+# the pandoc-converted legacy captions: … wrapped over several lines,
+# sometimes with a non-breaking hyphen in the number
+STRONG_RE = re.compile(r"\s*(Figure|Table)\s+([0-9A-Z]+[-‑][0-9]+)\s+(.+?)", re.S)
+# *…* and **…** captions, which may wrap over lines but never across a blank one
+_BODY = r"((?:[^*\n]|\n(?!\n))+?)"
+BOLD_RE = re.compile(r"(?m)^\*\*(Figure|Table)\s+([0-9A-Z]+[-‑][0-9]+)\s+" + _BODY + r"\*\*\s*$")
+ITALIC_RE = re.compile(r"(?m)^\*(Figure|Table)\s+([0-9A-Z]+[-‑][0-9]+)\s+" + _BODY + r"\*\s*$")
+BARE_CAPTION_RE = re.compile(r"^(Figure|Table)\s+([0-9A-Z]+-[0-9]+)[.:]?\s+(.+?)\.?\s*$")
+EMBED_RE = re.compile(r"!\[[^\]]*\]\([^)]+\)|]+src=")
+# prose that happens to open with a figure number, not a caption
+PROSE_RE = re.compile(r"\b(shows|depicts|illustrates|gives|plots|summari[sz]es|lists|is |are |presents|compares)\b")
+SUBPAGE_RE = re.compile(r"^-\s*@subpage\s+(\S+)")
+PAGE_RE = re.compile(r"^@page\s+(\S+)", re.M)
+BEGIN = ""
+BEGIN_ANY = re.compile(r"^$")
+END = ""
+STYLES = {
+    "bullet": lambda k, n, c: f"- **{k} {n}** {c}",
+    "period": lambda k, n, c: f"{k} {n}. {c}",
+    "plain": lambda k, n, c: f"{k} {n} {c}",
+}
+
+
+def chapters_in_order(manual: str):
+    """The manual's section files, in @subpage order, then any not listed."""
+    front = DOCS / "manuals" / "reference" / f"{manual}.md"
+    sections = sorted((DOCS / "manuals" / "reference" / manual / "sections").glob("*.md"))
+    by_page = {}
+    for p in sections:
+        m = PAGE_RE.search(p.read_text(errors="replace"))
+        if m:
+            by_page[m.group(1)] = p
+    order, seen = [], set()
+    for ln in front.read_text(errors="replace").split("\n"):
+        m = SUBPAGE_RE.match(ln.strip())
+        if m and m.group(1) in by_page:
+            order.append(by_page[m.group(1)])
+            seen.add(by_page[m.group(1)])
+    order += [p for p in sections if p not in seen]
+    return front, order
+
+
+def captions(manual: str):
+    """{'Figure': [(no, caption, file)], 'Table': [...]} in document order, plus problems."""
+    _, chapters = chapters_in_order(manual)
+    out = {"Figure": [], "Table": []}
+    problems = []
+    for p in chapters:
+        rel = p.relative_to(DOCS).as_posix()
+        text = p.read_text(errors="replace")
+        body = text.split("\n")
+        found = []                                  # (offset, kind, no, caption, line)
+        for rx in (STRONG_RE, BOLD_RE, ITALIC_RE):
+            for m in rx.finditer(text):
+                found.append((m.start(), m.group(1), m.group(2), m.group(3),
+                              text.count("\n", 0, m.start()) + 1))
+        off = 0
+        for n, ln in enumerate(body, 1):
+            m = CAPTION_RE.match(ln.strip())
+            if not m:
+                m = BARE_CAPTION_RE.match(ln.strip())
+                if not m or PROSE_RE.search(m.group(3)):
+                    off += len(ln) + 1
+                    continue
+                # only a bare line sitting directly under its image is a caption
+                prev = [q for q in body[max(0, n - 4):n - 1] if q.strip()]
+                if not (prev and EMBED_RE.search(prev[-1])):
+                    off += len(ln) + 1
+                    continue
+            found.append((off, m.group(1), m.group(2), m.group(3), n))
+            off += len(ln) + 1
+        seen = {"Figure": {}, "Table": {}}
+        for _, kind, no, cap, n in sorted(found):
+            no = no.replace("‑", "-")
+            cap = " ".join(re.sub(r"<[^>]+>", "", cap).split())
+            if cap.endswith("(continued)"):
+                continue            # a table split across pages, not a second table
+            if no in seen[kind]:
+                if seen[kind][no] != n:
+                    problems.append(f"{rel}:{n}: {kind} {no} is captioned twice "
+                                    f"(first at line {seen[kind][no]})")
+                continue
+            seen[kind][no] = n
+            out[kind].append((no, cap, rel))
+    return out, problems
+
+
+ENTRY_RE = re.compile(r"^(?:-\s*\*\*)?(Figure|Table)\s+([0-9A-Z]+-[0-9]+)(?:\*\*)?[.:]?\s+(.+?)\.?\s*$")
+
+
+def parse_entries(lines, kind):
+    """{number: text} for the entries already in a list block, in order."""
+    out = {}
+    for ln in lines:
+        m = ENTRY_RE.match(ln.strip())
+        if m and m.group(1) == kind:
+            out.setdefault(m.group(2), " ".join(m.group(3).split()))
+    return out
+
+
+def sort_key(no):
+    ch, _, num = no.partition("-")
+    return (0, int(ch)) if ch.isdigit() else (1, 0), ch, int(num)
+
+
+def merge(existing, sourced):
+    """(ordered [(no, text)], unsourced numbers) — captions win, old entries are never dropped."""
+    nums = sorted(set(existing) | set(sourced), key=sort_key)
+    return ([(n, sourced[n] if n in sourced else existing[n]) for n in nums],
+            [n for n in nums if n not in sourced])
+
+
+def detect_style(block_lines, marker_style):
+    if marker_style in STYLES:
+        return marker_style
+    for ln in block_lines:
+        s = ln.strip()
+        if s.startswith("- **"):
+            return "bullet"
+        if re.match(r"^(Figure|Table)\s+[0-9A-Z]+-[0-9]+\.\s", s):
+            return "period"
+        if re.match(r"^(Figure|Table)\s+[0-9A-Z]+-[0-9]+\s", s):
+            return "plain"
+    return "plain"
+
+
+def section_bounds(lines, heading):
+    """(start, end) of the list body under `heading`, exclusive of the heading itself."""
+    try:
+        i = next(k for k, ln in enumerate(lines) if ln.strip() == heading)
+    except StopIteration:
+        return None
+    j = i + 1
+    while j < len(lines) and not (lines[j].startswith("## ") or lines[j].strip() == "---"):
+        j += 1
+    return i + 1, j
+
+
+def render(entries, style, kind):
+    """One line per entry for the bullet style, which markdown renders as a list;
+    a blank line between entries otherwise, or the reader's markdown joins them
+    into a single paragraph."""
+    fn = STYLES[style]
+    out, last_chapter = [], None
+    for no, cap in entries:
+        chapter = no.split("-")[0]
+        if last_chapter is not None and (style != "bullet" or chapter != last_chapter):
+            out.append("")
+        out.append(fn(kind, no, cap))
+        last_chapter = chapter
+    return out
+
+
+def rewrite(manual: str, write: bool, verbose: bool):
+    front, _ = chapters_in_order(manual)
+    caps, problems = captions(manual)
+    text = front.read_text()
+    lines = text.split("\n")
+    changed = []
+    for kind, heading in (("Figure", "## List of Figures"), ("Table", "## List of Tables")):
+        key = "figures" if kind == "Figure" else "tables"
+        bounds = section_bounds(lines, heading)
+        if bounds is None:
+            problems.append(f"{front.relative_to(DOCS).as_posix()}: no '{heading}' heading")
+            continue
+        s, e = bounds
+        body = lines[s:e]
+        marker_style = None
+        inner = body
+        for k, ln in enumerate(body):
+            m = BEGIN_ANY.match(ln.strip())
+            if m:
+                marker_style = m.group(2)
+                try:
+                    stop = next(q for q in range(k + 1, len(body)) if body[q].strip() == END)
+                except StopIteration:
+                    problems.append(f"{front.relative_to(DOCS).as_posix()}: unterminated {key} block")
+                    stop = len(body) - 1
+                inner = body[k + 1:stop]
+                break
+        style = detect_style(inner, marker_style)
+        entries, unsourced = merge(parse_entries(inner, kind),
+                                   {no: cap for no, cap, _ in caps[kind]})
+        want = ([""] + [BEGIN.format(kind=key, style=f" style={style}")] + [""]
+                + render(entries, style, kind) + ["", END, ""])
+        if body != want:
+            changed.append(f"{manual}: {heading[3:]} ({len(entries)} entries, {style} style)")
+            if write:
+                lines[s:e] = want
+        if unsourced and verbose:
+            print(f"  {manual}: {len(unsourced)} {kind.lower()} entries kept from the old list with no "
+                  f"caption found in a chapter: {', '.join(unsourced[:8])}"
+                  + (" …" if len(unsourced) > 8 else ""))
+    if write and changed:
+        front.write_text("\n".join(lines))
+    if verbose:
+        for kind in ("Figure", "Table"):
+            nums = [no for no, _, _ in caps[kind]]
+            print(f"  {manual}: {len(nums)} {kind.lower()} captions")
+    return changed, problems
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--write", action="store_true", help="rewrite the generated blocks")
+    g.add_argument("--check", action="store_true", help="exit 1 if any block is stale")
+    ap.add_argument("--manual", choices=MANUALS, help="only this manual")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    args = ap.parse_args(argv)
+    manuals = [args.manual] if args.manual else MANUALS
+    stale, problems = [], []
+    for m in manuals:
+        c, p = rewrite(m, args.write, args.verbose)
+        stale += c
+        problems += p
+    for p in problems:
+        print(f"ERROR front matter: {p}")
+    for c in stale:
+        print(("rewrote " if args.write else "ERROR front matter: stale — ") + c)
+    if problems:
+        return 1
+    if args.check and stale:
+        print("front matter: run scripts/gen_manual_frontmatter.py --write")
+        return 1
+    print(f"front matter: {len(manuals)} manuals, "
+          f"{'rewrote ' + str(len(stale)) if args.write else str(len(stale)) + ' stale'}, "
+          f"{len(problems)} errors")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/lint_manual_docs.py b/scripts/lint_manual_docs.py
index fc978e743..accc37d9f 100644
--- a/scripts/lint_manual_docs.py
+++ b/scripts/lint_manual_docs.py
@@ -9,30 +9,60 @@
     \\anchor in the manual tree (code-entity refs are skipped: they contain
     '::' or match a known source symbol pattern)
   * markdown tables whose rows have inconsistent column counts
-  * unbalanced $$ display-math delimiters
+  * raw $ math, unbalanced \\f[ \\f] and odd \\f$ counts
+  * 
/
, unknown HTML tags, indented dash rules
   * image references whose basename exists in no IMAGE_PATH directory
+  * [SECTION] coverage of Chapter 2 against the parser's registrations
+  * the error/warning catalogue against ErrorCodes.hpp
+  * the engine figure manifest (listed, present, cited)
+  * retired-interface prose in the engine manual
+  * \\status{...} badges: alias present, vocabulary from docs/figures/status.py,
+    every Status-column table cell is exactly one badge, CSS colours in sync
+  * Mermaid blocks: labelled ``, closed, unique ids, no
+    piped node labels and no Doxygen command characters
+  * Application Manual deck citations and \\snippet markers resolve
 
-Exit code 1 if any errors. Run from anywhere.
+Exit code 1 if any errors. Run from anywhere. `--docs-root` points the lint
+at a copy of docs/ (the negative-test runner mutates copies, never the tree);
+`--src-root` stays on the real source tree unless overridden.
 """
+import argparse
+import importlib.util
 import re
 import sys
+import xml.etree.ElementTree as ET
 from collections import defaultdict
 from pathlib import Path
 
-DOCS = Path(__file__).resolve().parent.parent / "docs"
-MANUAL_DIRS = [DOCS / "manuals", DOCS / "authors.md", DOCS / "Updates.md"]
-IMAGE_PATHS = [
-    DOCS / "images",
-    DOCS / "manuals" / "user" / "figures",
-    DOCS / "manuals" / "reference" / "hydrology" / "media" / "media",
-    DOCS / "manuals" / "reference" / "hydraulics" / "media" / "media",
-    DOCS / "manuals" / "reference" / "quality" / "media" / "media",
-]
+ROOT = Path(__file__).resolve().parent.parent
+DOCS = ROOT / "docs"
+SRC = ROOT / "src"
+MANUAL_DIRS = []
+IMAGE_PATHS = []
 EXCLUDE_RE = re.compile(r"/SWMM[^/]*\.md$|/media/")
 
 CODE_REF = re.compile(r"::|\.h$|^[a-z]+_[a-zA-Z]+$")  # C API / namespaced / header files
 
 
+def configure(docs_root, src_root):
+    """Bind the module paths. Called once from main(); tests call it directly."""
+    global DOCS, SRC, MANUAL_DIRS, IMAGE_PATHS
+    DOCS = Path(docs_root).resolve()
+    SRC = Path(src_root).resolve()
+    MANUAL_DIRS = [DOCS / "manuals", DOCS / "authors.md"]
+    IMAGE_PATHS = [
+        DOCS / "images",
+        DOCS / "figures" / "png",
+        DOCS / "manuals" / "engine" / "figures",
+        DOCS / "manuals" / "reference" / "hydrology" / "media" / "media",
+        DOCS / "manuals" / "reference" / "hydraulics" / "media" / "media",
+        DOCS / "manuals" / "reference" / "quality" / "media" / "media",
+    ]
+
+
+configure(DOCS, SRC)
+
+
 def md_files():
     out = []
     for root in MANUAL_DIRS:
@@ -43,7 +73,585 @@ def md_files():
     return sorted(out)
 
 
-def main():
+def external_pages():
+    """Page ids imported from the Doxyfile's TAGFILES.
+
+    `@ref manual_*` into the SWMMVis manual resolves through
+    docs/tags/swmmvis-manual.tag at build time, so those targets are valid even
+    though no local file declares them. Without this the lint reports every
+    cross-repo reference as unresolved.
+    """
+    ids = set()
+    for tag in sorted((DOCS / "tags").glob("*.tag")):
+        try:
+            root = ET.parse(tag).getroot()
+        except ET.ParseError as exc:
+            print(f"ERROR {tag.name}: not parseable as a Doxygen tagfile ({exc})")
+            continue
+        ids.update(c.findtext("name") for c in root if c.get("kind") == "page")
+    return {i for i in ids if i}
+
+
+# Delphi-interface vocabulary. The engine manual documents an engine; prose
+# that tells the reader to click something is a sign that text was carried over
+# from the retired user manual without being rewritten. Case-sensitive on
+# purpose: "Study Area Map" is the old UI's proper noun, "study area map" in a
+# figure caption is just English.
+GUI_PROSE = re.compile(
+    r"Main Menu|Main Toolbar|Project Browser|Property Editor|Map Browser"
+    r"|Windows Clipboard|Study Area Map|epaswmm5\.exe"
+    r"|click the .*button|right-click")
+
+
+def check_gui_prose():
+    engine_dir = DOCS / "manuals" / "engine"
+    if not engine_dir.is_dir():
+        return 0
+    errors = 0
+    for f in sorted(engine_dir.rglob("*.md")):
+        for n, line in enumerate(f.read_text(errors="replace").splitlines(), 1):
+            # A table row that names a retired chapter and points at what
+            # replaced it is a record of the migration, not prose left behind.
+            if line.lstrip().startswith("|") and ("@ref manual_" in line
+                                                  or "@ref tutorial_" in line
+                                                  or "SWMMVis manual" in line):
+                continue
+            if GUI_PROSE.search(line):
+                print(f"ERROR {f.relative_to(DOCS)}:{n}: retired-interface prose "
+                      f"in the engine manual")
+                errors += 1
+    return errors
+
+
+def check_message_catalogue():
+    """Appendix A must document every code the engine can emit.
+
+    Source of truth is src/engine/core/ErrorCodes.hpp. The appendix splits
+    WARNING 10 into 10a/10b (two distinct conditions share one code), so the
+    warning numbers are matched on their leading digits.
+    """
+    hdr = SRC / "engine" / "core" / "ErrorCodes.hpp"
+    apx = DOCS / "manuals" / "engine" / "sections" / "AppendixA-Messages.md"
+    if not hdr.exists() or not apx.exists():
+        return 0
+    src, text = hdr.read_text(errors="replace"), apx.read_text(errors="replace")
+
+    def enum(name):
+        m = re.search(rf"enum\s+{name}\s*:\s*int\s*\{{(.*?)^\}};", src, re.S | re.M)
+        if not m:
+            return None
+        return {int(v) for v in re.findall(r"^\s*[A-Z][A-Z0-9_]*\s*=\s*(\d+)", m.group(1), re.M)} - {0}
+
+    errors = 0
+    for enum_name, prefix in (("ErrorCode", "ERROR"), ("WarnCode", "WARNING")):
+        want = enum(enum_name)
+        if want is None:
+            print(f"ERROR messages: could not find enum {enum_name}")
+            return 1
+        have = {int(x) for x in re.findall(rf"^{prefix} 0*(\d+)[a-z]?:", text, re.M)}
+        for c in sorted(want - have):
+            print(f"ERROR messages: {prefix} {c} is in ErrorCodes.hpp but not in Appendix A")
+            errors += 1
+        for c in sorted(have - want):
+            print(f"ERROR messages: Appendix A documents {prefix} {c}, "
+                  f"which ErrorCodes.hpp does not define")
+            errors += 1
+    return errors
+
+
+def check_figure_manifest():
+    """Every image any manual embeds has a manifest row, and vice versa.
+
+    The audit itself lives in scripts/build_manual_figures.py (one
+    implementation for the lint and for the figure pipeline's `check`); it
+    covers the retired manual's failure mode — 307 images no page referenced —
+    and the reference manuals' basename collisions that let Doxygen serve one
+    manual's figure on another manual's page.
+    """
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from build_manual_figures import check_manifest
+    return check_manifest(DOCS)
+
+
+def check_front_matter():
+    """Each reference manual's List of Figures and List of Tables matches its captions.
+
+    The lists are generated from the caption lines by
+    scripts/gen_manual_frontmatter.py; this runs its --check. The manuals'
+    invented entries (the quality manual listed "SWMM's Object Model" for a
+    figure captioned "Elements of a typical urban drainage system") are what
+    the generator exists to prevent.
+    """
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    import io
+    import contextlib
+    import gen_manual_frontmatter as gm
+    if gm.DOCS != DOCS:                      # --docs-root: point the generator at the copy
+        gm.DOCS = DOCS
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        rc = gm.main(["--check"])
+    out = buf.getvalue().strip().split("\n")
+    if rc == 0:
+        print(out[-1])
+        return 0
+    for ln in out:
+        if ln.startswith("ERROR") or ln.startswith("front matter:"):
+            print(ln)
+    return sum(1 for ln in out if ln.startswith("ERROR"))
+
+
+def check_section_coverage():
+    """Chapter 2 must document every [SECTION] the parser registers.
+
+    The allowlist (KNOWN_SECTION_GAPS.txt) holds the 2D_*/GW_* backlog, so this
+    fails when someone registers a NEW section without documenting it — the
+    regression worth catching — rather than demanding the backlog be written
+    before anything else can land. Shrink the allowlist, never grow it.
+    """
+    src = SRC / "engine"
+    chapter = DOCS / "manuals" / "engine" / "sections" / "Chapter2-InputFileReference.md"
+    gaps_file = chapter.parent / "KNOWN_SECTION_GAPS.txt"
+    if not src.is_dir() or not chapter.exists():
+        return 0
+
+    registered = set()
+    for f in src.rglob("*.cpp"):
+        text = f.read_text(errors="replace")
+        registered |= set(re.findall(r'register_builtin\(\s*"([A-Z0-9_]+)"', text))
+        registered |= set(re.findall(r'register_custom\(\s*"([A-Z0-9_]+)"', text))
+    if not registered:
+        print("ERROR section coverage: parsed no registered sections — "
+              "the registration call's shape changed")
+        return 1
+
+    documented = set(re.findall(r"^### Section: \[([A-Z0-9_]+)\]",
+                                chapter.read_text(errors="replace"), re.M))
+    allowed = set()
+    if gaps_file.exists():
+        allowed = {ln.strip() for ln in gaps_file.read_text().splitlines()
+                   if ln.strip() and not ln.startswith("#")}
+
+    errors = 0
+    for s in sorted(documented - registered):
+        print(f"ERROR section coverage: Chapter 2 documents [{s}], "
+              f"which no handler registers")
+        errors += 1
+    for s in sorted(registered - documented - allowed):
+        print(f"ERROR section coverage: [{s}] is registered but undocumented "
+              f"and not in KNOWN_SECTION_GAPS.txt")
+        errors += 1
+    for s in sorted(allowed & documented):
+        print(f"ERROR section coverage: [{s}] is documented — remove it from "
+              f"KNOWN_SECTION_GAPS.txt")
+        errors += 1
+    return errors
+
+
+def _function_body(text, start_re):
+    """Source text from the first match of start_re to the next lone `}` at column 0."""
+    m = re.search(start_re, text, re.M)
+    if not m:
+        return None
+    end = re.search(r"^}\s*$", text[m.end():], re.M)
+    return text[m.start(): m.end() + (end.end() if end else 0)]
+
+
+def _documented_keys(chapter_text, section):
+    """Keywords a `### Section: [X]` entry documents: first-column backticked
+    keys of its tables plus the leading token of each line in its fenced
+    Format blocks."""
+    m = re.search(r"^### Section: \[" + re.escape(section.strip("[]")) + r"\].*?(?=^### Section: |\Z)",
+                  chapter_text, re.M | re.S)
+    if not m:
+        return None
+    region = m.group(0)
+    keys = set(re.findall(r"^\|\s*`?([A-Z][A-Z0-9_]*)`?\s*\|", region, re.M))
+    # Format blocks: fenced, or the legacy plain column-0 `KEYWORD   value` layout
+    for block in re.findall(r"```.*?```", region, re.S):
+        keys |= set(re.findall(r"^([A-Z][A-Z0-9_]{2,})\s", block, re.M))
+    keys |= set(re.findall(r"^([A-Z][A-Z0-9_]{2,})\s{2,}\S", region, re.M))
+    return keys
+
+
+# (source under src/, regex locating the function, regex for the key literal inside it, section)
+OPTIONS_COVERAGE = [
+    ("engine/input/handlers/OptionsHandler.cpp", r"^void handle_options\(",
+     r'key\s*==\s*"([A-Z][A-Z0-9_]*)"', "[OPTIONS]"),
+    ("engine/2d/input/SectionHandlers2D.cpp", r"^bool is2DOptionKey\(",
+     r'"([A-Z][A-Z0-9_]*)"', "[2D_OPTIONS]"),
+    ("engine/2d/input/SectionHandlers2D.cpp", r"^bool is2DRetiredOptionKey\(",
+     r'"([A-Z][A-Z0-9_]*)"', "[2D_OPTIONS]"),
+    # the file parser itself: it accepts DISPERSION, which the API allow-list omits
+    ("engine/2d/input/SectionHandlers2D.cpp", r"parse2DOptionsLine\(",
+     r'iequals\(key,\s*"([A-Z][A-Z0-9_]*)"\)', "[2D_OPTIONS]"),
+]
+
+
+def check_options_coverage():
+    """The [OPTIONS] and [2D_OPTIONS] entries document every keyword the parser accepts.
+
+    Parsed keys are the string literals compared inside handle_options() and
+    the two 2D allow-lists; documented keys are the backticked first column
+    of the entry's tables and the leading token of its Format block. Fails in
+    both directions, so an invented keyword and a forgotten one are the same
+    error. Retired keys are parsed too and belong in the entry's Retired table.
+    """
+    chapter = DOCS / "manuals" / "engine" / "sections" / "Chapter2-InputFileReference.md"
+    if not chapter.exists() or not SRC.is_dir():
+        return 0
+    text = chapter.read_text(errors="replace")
+    parsed = defaultdict(set)
+    for rel, start_re, key_re, section in OPTIONS_COVERAGE:
+        src = SRC / rel
+        if not src.exists():
+            print(f"ERROR options coverage: {rel} not found")
+            return 1
+        body = _function_body(src.read_text(errors="replace"), start_re)
+        if body is None:
+            print(f"ERROR options coverage: {start_re!r} not found in {rel}")
+            return 1
+        parsed[section] |= set(re.findall(key_re, body))
+    errors = 0
+    for section, keys in parsed.items():
+        if not keys:
+            print(f"ERROR options coverage: parsed no keys for {section} — the parser's shape changed")
+            errors += 1
+            continue
+        documented = _documented_keys(text, section)
+        if documented is None:
+            print(f"ERROR options coverage: Chapter 2 has no `### Section: {section}` entry")
+            errors += 1
+            continue
+        for k in sorted(keys - documented):
+            print(f"ERROR options coverage: {section} keyword {k} is parsed but not documented")
+            errors += 1
+        for k in sorted(documented - keys):
+            print(f"ERROR options coverage: {section} documents {k}, which the parser does not accept")
+            errors += 1
+    return errors
+
+
+# (source under src/, regex locating the function or None for whole file, regex for the section literal)
+COMPONENT_SOURCES = [
+    ("engine/transport/components/ReactionModule/ReactionsComponent.cpp",
+     r"reactionSectionTags\(\)\s*\{", r'"(REACTION_[A-Z_]+)"'),
+    ("engine/transport/components/HeatModule/HeatComponent.cpp", None, r'sec\.first\s*[!=]=\s*"([A-Z_]+)"'),
+    ("engine/transport/components/WaterAgeModule/WaterAgeComponent.cpp", None, r'sec\.first\s*[!=]=\s*"([A-Z_]+)"'),
+    ("engine/transport/components/EulerianArdComponent/ArdConfig.cpp", None, r'tag\s*==\s*"([A-Z_]+)"'),
+]
+COMPONENT_MENTION = re.compile(r"\[((?:REACTION|HEAT|TRANSPORT|WATER_AGE)_[A-Z_]+"
+                               r"|RADIATIVE_FLUXES|SOLAR_RADIATION|CLOUD_COVER|SEDIMENT_EXCHANGE)\]")
+
+
+def check_component_sections():
+    """Chapter 2 §2.5 documents every configuration section a process component parses.
+
+    These sections never pass through the SectionRegistry (they come from
+    the file named in [PROCESS_COMPONENTS]), so check_section_coverage()
+    cannot see them. Parsed names are the literals each component compares
+    against; documented names use the distinct heading
+    `### Component section: [X]`. A second assertion: any bracketed
+    component-section name mentioned anywhere in the manuals must exist —
+    which is how a stale `[REACTION_INITIAL]` gets caught.
+    """
+    chapter = DOCS / "manuals" / "engine" / "sections" / "Chapter2-InputFileReference.md"
+    if not chapter.exists() or not SRC.is_dir():
+        return 0
+    parsed = set()
+    for rel, start_re, lit_re in COMPONENT_SOURCES:
+        src = SRC / rel
+        if not src.exists():
+            print(f"ERROR component sections: {rel} not found")
+            return 1
+        text = src.read_text(errors="replace")
+        body = _function_body(text, start_re) if start_re else text
+        if body is None:
+            print(f"ERROR component sections: {start_re!r} not found in {rel}")
+            return 1
+        parsed |= set(re.findall(lit_re, body))
+    if not parsed:
+        print("ERROR component sections: parsed no section literals — the components' shape changed")
+        return 1
+    documented = set(re.findall(r"^### Component section: \[([A-Z0-9_]+)\]",
+                                chapter.read_text(errors="replace"), re.M))
+    errors = 0
+    for s in sorted(parsed - documented):
+        print(f"ERROR component sections: [{s}] is parsed by a component but has no "
+              f"`### Component section:` entry in Chapter 2")
+        errors += 1
+    for s in sorted(documented - parsed):
+        print(f"ERROR component sections: Chapter 2 documents [{s}], which no component parses")
+        errors += 1
+    for f in md_files():
+        for n, ln in enumerate(f.read_text(errors="replace").split("\n"), 1):
+            for m in COMPONENT_MENTION.finditer(ln):
+                if m.group(1) not in parsed:
+                    print(f"ERROR {f.relative_to(DOCS)}:{n}: [{m.group(1)}] is not a section any "
+                          f"component parses")
+                    errors += 1
+    return errors
+
+
+def load_status_module():
+    """docs/figures/status.py — the badge vocabulary and colours. None if absent."""
+    path = DOCS / "figures" / "status.py"
+    if not path.exists():
+        return None
+    spec = importlib.util.spec_from_file_location("manual_status", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+BADGE_RE = re.compile(r"[\\@]status\{([^}]*)\}")
+
+
+def table_rows(lines, i):
+    """If lines[i] starts a markdown table, return (header_cells, [(lineno, cells)...])."""
+    if not (re.match(r"^\s*\|.*\|\s*$", lines[i]) and i + 1 < len(lines)
+            and re.match(r"^\s*\|[\s:|-]+\|\s*$", lines[i + 1])):
+        return None
+    header = [c.strip() for c in lines[i].strip().strip("|").split("|")]
+    body = []
+    j = i + 2
+    while j < len(lines) and re.match(r"^\s*\|.*\|\s*$", lines[j]):
+        body.append((j + 1, [c.strip() for c in lines[j].strip().strip("|").split("|")]))
+        j += 1
+    return header, body
+
+
+def check_status_badges(status_report=False):
+    """\\status{...} is the one way a manual states a formulation's status.
+
+    Three things must agree: the Doxyfile alias (else the badge renders as
+    literal text), the vocabulary in docs/figures/status.py (the same dict the
+    figure generators colour their chips from), and the CSS colours. Any table
+    whose header has a cell reading exactly `Status` is an alternatives table:
+    every body row must carry exactly one badge in that column.
+    """
+    errors = 0
+    doxyfile = DOCS / "Doxyfile"
+    if not doxyfile.exists() or '"status{1}=' not in doxyfile.read_text(errors="replace"):
+        print("ERROR status: docs/Doxyfile has no status{1} alias — badges would render as text")
+        errors += 1
+    mod = load_status_module()
+    if mod is None:
+        print("ERROR status: docs/figures/status.py is missing")
+        return errors + 1
+    for e in mod.self_check():
+        print(f"ERROR {e}")
+        errors += 1
+    vocab = mod.labels()
+    css = DOCS / "custom" / "css" / "manual.css"
+    css_text = css.read_text(errors="replace") if css.exists() else ""
+    for lab, hexval in mod.STATUS.values():
+        if hexval not in css_text:
+            print(f"ERROR status: {css.name} lacks the {lab} colour {hexval} from status.py")
+            errors += 1
+
+    badge_cell = re.compile(r"^[\\@]status\{(" + "|".join(sorted(vocab)) + r")\}$")
+    report = []
+    for f in md_files():
+        rel = f.relative_to(DOCS)
+        lines = f.read_text(errors="replace").split("\n")
+        for n, ln in enumerate(lines, 1):
+            for m in BADGE_RE.finditer(ln):
+                if m.group(1) not in vocab:
+                    print(f"ERROR {rel}:{n}: \\status{{{m.group(1)}}} is not one of "
+                          f"{', '.join(sorted(vocab))}")
+                    errors += 1
+                else:
+                    report.append((str(rel), n, m.group(1)))
+        i = 0
+        while i < len(lines):
+            t = table_rows(lines, i)
+            if t is None:
+                i += 1
+                continue
+            header, body = t
+            if "Status" in header:
+                col = header.index("Status")
+                for n, cells in body:
+                    cell = cells[col] if col < len(cells) else ""
+                    if not badge_cell.match(cell):
+                        print(f"ERROR {rel}:{n}: Status column must hold exactly one "
+                              f"\\status{{...}} badge, found {cell[:40]!r}")
+                        errors += 1
+            i += 2 + len(body)
+    if status_report:
+        print("\nSTATUS REPORT (file:line badge)")
+        for rel, n, lab in report:
+            print(f"  {rel}:{n} {lab}")
+        print(f"  {len(report)} badges")
+    return errors
+
+
+MERMAID_ID_RE = re.compile(r"^$")
+MERMAID_LABEL_RE = re.compile(r"\[([^\]]*)\]|\{([^}]*)\}")
+WORKFLOW_LINKS_RE = re.compile(r'^
\s*$')
+WORKFLOW_NODE_RE = re.compile(r'^@ref [A-Za-z0-9_]+ "[^"]+"\s*$')
+
+
+def _check_workflow_links(rel, lines, k, wid, body, consumed):
+    """A `
` block right after a mermaid block: well formed, same id,
+    every node a node of that flowchart. Returns the error count."""
+    errors = 0
+    consumed.add((rel, k))
+    m = WORKFLOW_LINKS_RE.match(lines[k])
+    if not m:
+        print(f"ERROR {rel}:{k+1}: malformed workflow-links opener (expected "
+              f'
)')
+        return 1
+    if wid and m.group(1) != wid:
+        print(f"ERROR {rel}:{k+1}: workflow-links names workflow {m.group(1)!r} but follows the block {wid!r}")
+        errors += 1
+    first = next((ln.strip() for ln in body.split("\n") if ln.strip()), "")
+    if not (first.startswith("graph") or first.startswith("flowchart")):
+        print(f"ERROR {rel}:{k+1}: workflow-links on a non-flowchart diagram ({first[:20]!r}); "
+              f"Mermaid supports click on flowcharts only")
+        errors += 1
+    e, n_nodes = k + 1, 0
+    while e < len(lines) and lines[e].strip() != "
":
+        nm = WORKFLOW_NODE_RE.match(lines[e])
+        if not nm:
+            print(f"ERROR {rel}:{e+1}: workflow-links line is not "
+                  f'@ref target "label"')
+            errors += 1
+        else:
+            node = nm.group(1)
+            if not re.search(rf"(?= len(lines):
+        print(f"ERROR {rel}:{k+1}: workflow-links block is not closed by 
")
+        errors += 1
+    elif n_nodes == 0:
+        print(f"ERROR {rel}:{k+1}: workflow-links block holds no link")
+        errors += 1
+    return errors
+
+
+def check_mermaid_workflows():
+    """Every `
` block is labelled, closed and safe.
+
+    Doxygen expands `@` and `\\` commands inside the block; a pipe inside a
+    node label is Mermaid's edge-label syntax and breaks the diagram. The
+    `` line before the block names the diagram so a
+    figure manifest and the prose can refer to it.
+    """
+    errors = 0
+    seen = {}
+    consumed = set()
+    link_divs = []
+    for f in md_files():
+        rel = f.relative_to(DOCS)
+        lines = f.read_text(errors="replace").split("\n")
+        for i, ln in enumerate(lines):
+            if ln.startswith('
= 0 and not lines[k].strip():
+                k -= 1
+            m = MERMAID_ID_RE.match(lines[k].strip()) if k >= 0 else None
+            if not m:
+                print(f"ERROR {rel}:{i+1}: mermaid block lacks a `` "
+                      f"line immediately above it")
+                errors += 1
+            else:
+                wid = m.group(1)
+                if wid in seen:
+                    print(f"ERROR {rel}:{i+1}: workflow id {wid!r} already used in {seen[wid]}")
+                    errors += 1
+                seen[wid] = f"{rel}:{i+1}"
+            j = i + 1
+            while j < len(lines) and lines[j].strip() != "
":
+                if lines[j].strip().startswith("= len(lines) or lines[j].strip() != "":
+                print(f"ERROR {rel}:{i+1}: mermaid block is not closed by ")
+                errors += 1
+                continue
+            for n in range(i + 1, j):
+                body = lines[n]
+                if "@" in body or "\\" in body:
+                    print(f"ERROR {rel}:{n+1}: mermaid line contains @ or \\ "
+                          f"(Doxygen command characters)")
+                    errors += 1
+                for lm in MERMAID_LABEL_RE.finditer(body):
+                    label = lm.group(1) if lm.group(1) is not None else lm.group(2)
+                    if "|" in label:
+                        print(f"ERROR {rel}:{n+1}: mermaid node label contains '|' "
+                              f"(edge-label syntax): {label[:40]!r}")
+                        errors += 1
+            # an optional click-target block must follow the diagram directly
+            k = j + 1
+            while k < len(lines) and not lines[k].strip():
+                k += 1
+            if k < len(lines) and lines[k].startswith('
 not found in IMAGE_PATH: {m.group(1)}")
                 errors += 1
 
+    errors += check_section_coverage()
+    errors += check_options_coverage()
+    errors += check_component_sections()
+    errors += check_gui_prose()
+    errors += check_figure_manifest()
+    errors += check_front_matter()
+    errors += check_message_catalogue()
+    errors += check_status_badges(status_report=args.status_report)
+    errors += check_mermaid_workflows()
+    errors += check_application_decks()
+
     print(f"\n{len(files)} files, {len(pages)} pages, {len(anchors)} anchors, {errors} errors")
     return 1 if errors else 0
 
diff --git a/scripts/lint_manual_docs_negative.py b/scripts/lint_manual_docs_negative.py
new file mode 100644
index 000000000..8b028da8a
--- /dev/null
+++ b/scripts/lint_manual_docs_negative.py
@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Prove that every lint check can fail.
+
+A gate is not a gate until it has been seen to fail. For each case below the
+runner copies docs/ (text files copied, images hard-linked, generated html/
+skipped), applies one mutation, runs scripts/lint_manual_docs.py --docs-root on
+the copy and asserts that it exits 1 with the expected message. An unmodified
+copy is run first as the positive control. Everything lands in a reviewable
+directory, never a temp dir:
+
+    tests/output/docs_lint_negative_//docs   (the mutated copy)
+    tests/output/docs_lint_negative_/.log    (the lint output)
+    tests/output/docs_lint_negative_/SUMMARY.txt
+
+Exit 1 if the control fails, or any case does not fail the way it should.
+"""
+import datetime as dt
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS = ROOT / "docs"
+LINT = ROOT / "scripts" / "lint_manual_docs.py"
+IMAGE_EXT = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".emf", ".wmf"}
+
+# (case, file relative to docs/, old text, new text, expected substring in the lint output)
+CASES = [
+    ("duplicate_page",
+     "manuals/engine/sections/Chapter3-Files.md",
+     "@page engine_manual_ch3_files", "@page engine_manual_ch4_reports",
+     "duplicate @page engine_manual_ch4_reports"),
+    ("unresolved_ref",
+     "manuals/engine/engine_manual.md",
+     "@subpage engine_manual_ch1_conceptual_model", "@subpage engine_manual_ch1_nonexistent",
+     "unresolved @ref/@subpage 'engine_manual_ch1_nonexistent'"),
+    ("ragged_table",
+     "manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md",
+     "| Closure | Prognostic state | Face law | Valid regime | Cost | Status |",
+     "| Closure | Prognostic state | Face law | Valid regime | Cost | Status | Extra |",
+     "table row has"),
+    ("raw_dollar_math",
+     "manuals/engine/sections/Chapter1-ConceptualModel.md",
+     "This chapter discusses how SWMM models",
+     "This chapter discusses how $x$ SWMM models",
+     "raw $ math"),
+    ("image_missing",
+     "manuals/engine/engine_manual.md",
+     "figures/figure1_1_urban_sewershed.jpg", "figures/nope.png",
+     "image not found"),
+    ("section_undocumented",
+     "manuals/engine/sections/Chapter2-InputFileReference.md",
+     "### Section: [TAGS]", "### Section-gone: [TAGS]",
+     "[TAGS] is registered but undocumented"),
+    ("options_missing_key",
+     "manuals/engine/sections/Chapter2-InputFileReference.md",
+     "| FV_CFL | number | 0.5 |", "| FV_CFLX | number | 0.5 |",
+     "[OPTIONS] keyword FV_CFL is parsed but not documented"),
+    ("options_bogus_key",
+     "manuals/engine/sections/Chapter2-InputFileReference.md",
+     "| FV_CFL | number | 0.5 |", "| FOO_BAR | number | 1 | Invented. |\n| FV_CFL | number | 0.5 |",
+     "[OPTIONS] documents FOO_BAR, which the parser does not accept"),
+    ("options_2d_missing_key",
+     "manuals/engine/sections/Chapter2-InputFileReference.md",
+     "| CELL_CLOSURE |", "| CELL_CLOSUREX |",
+     "[2D_OPTIONS] keyword CELL_CLOSURE is parsed but not documented"),
+    ("component_missing_section",
+     "manuals/engine/sections/Chapter2-InputFileReference.md",
+     "### Component section: [HEAT_FLUXES]", "### Component section-gone: [HEAT_FLUXES]",
+     "[HEAT_FLUXES] is parsed by a component but has no"),
+    ("component_stray_bracket",
+     "manuals/reference/quality/sections/Chapter8-MultiSpeciesReactions.md",
+     "## 8.1 Introduction", "## 8.1 Introduction\n\nSee also [HEAT_BOGUS].\n",
+     "[HEAT_BOGUS] is not a section any component parses"),
+    ("message_missing",
+     "manuals/engine/sections/AppendixA-Messages.md",
+     "ERROR 101:", "ERROR 1010:",
+     "ERROR 101 is in ErrorCodes.hpp but not in Appendix A"),
+    ("figure_uncited",
+     "manuals/engine/sections/Chapter1-ConceptualModel.md",
+     "figures/fig3-03-storm-drain-inlet.png", "figures/fig3-03-storm-drain-inlet-renamed.png",
+     "never embedded by engine_manual_ch1_conceptual_model"),
+    ("manifest_row_deleted",
+     "figures/MANIFEST.tsv",
+     "eng_fig3_03_storm_drain_inlet\t", "# eng_fig3_03_storm_drain_inlet\t",
+     "has no MANIFEST.tsv row"),
+    ("manifest_wrong_page",
+     "figures/MANIFEST.tsv",
+     "\tengine_manual_ch1_conceptual_model\t1-5\t", "\tengine_manual_ch4_reports\t1-5\t",
+     "which is not in its page_id"),
+    ("manifest_figure_no_drift",
+     "figures/MANIFEST.tsv",
+     "\tengine_manual_ch1_conceptual_model\t1-5\t", "\tengine_manual_ch1_conceptual_model\t1-99\t",
+     "no 'Figure 1-99' caption within 5 lines"),
+    ("manifest_bad_tier",
+     "figures/MANIFEST.tsv",
+     "eng_fig3_03_storm_drain_inlet\tlegacy\t", "eng_fig3_03_storm_drain_inlet\tantique\t",
+     "tier 'antique' is not one of"),
+    ("manifest_generated_without_generator",
+     "figures/MANIFEST.tsv",
+     "eng_fig3_03_storm_drain_inlet\tlegacy\t", "eng_fig3_03_storm_drain_inlet\tsynthetic\t",
+     "generated rows must embed figures/png/eng_fig3_03_storm_drain_inlet.png"),
+    ("manifest_orphan",
+     "COPY", "manuals/engine/figures/fig3-03-storm-drain-inlet.png", "images/stray.png",
+     "images/stray.png is on disk but has no MANIFEST.tsv row (orphan)"),
+    ("manifest_ambiguous_basename",
+     "COPY", "manuals/engine/figures/fig3-03-storm-drain-inlet.png",
+     "images/fig3-03-storm-drain-inlet.png",
+     "basename fig3-03-storm-drain-inlet.png exists in 2 IMAGE_PATH dirs"),
+    ("manifest_unrenderable",
+     "COPY", "manuals/engine/figures/fig3-03-storm-drain-inlet.png", "images/legacy.emf",
+     ".emf is not renderable by browsers"),
+    ("bad_status_word",
+     "manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md",
+     "\\status{Implemented} |", "\\status{Shipped} |",
+     "\\status{Shipped} is not one of"),
+    ("status_table_plain_text",
+     "manuals/reference/hydraulics/sections/Chapter9-TwoDimensional.md",
+     "| \\status{Implemented} |", "| Implemented |",
+     "Status column must hold exactly one"),
+    ("doxyfile_missing_alias",
+     "Doxyfile",
+     '"status{1}=', '"statusx{1}=',
+     "has no status{1} alias"),
+    ("css_colour_drift",
+     "custom/css/manual.css",
+     "#1baf7a", "#1baf7b",
+     "lacks the Implemented colour #1baf7a"),
+    ("mermaid_id_missing",
+     "manuals/engine/sections/Chapter5-ProgrammaticApi.md",
+     "\n", "",
+     "lacks a `` line"),
+    ("mermaid_id_duplicate",
+     "manuals/engine/sections/Chapter5-ProgrammaticApi.md",
+     "", "",
+     "workflow id 'engine_lifecycle' already used"),
+    ("mermaid_piped_label",
+     "manuals/engine/sections/Chapter5-ProgrammaticApi.md",
+     "G[Load library directly]", "G[Load library|directly]",
+     "mermaid node label contains '|'"),
+    ("mermaid_unclosed",
+     "manuals/engine/sections/Chapter5-ProgrammaticApi.md",
+     "    K --> L[Plugin receives host callbacks during the run]\n",
+     "    K --> L[Plugin receives host callbacks during the run]\n",
+     "mermaid block is not closed"),
+    ("mermaid_command_char",
+     "manuals/engine/sections/Chapter5-ProgrammaticApi.md",
+     "G[Load library directly]", "G[Load @ref library directly]",
+     "mermaid line contains @ or"),
+    ("app_deck_missing",
+     "manuals/application/application.md",
+     "## Introduction", "## Introduction\n\nDeck: `docs/figures/decks/nope/nope.inp`\n",
+     "cites docs/figures/decks/nope/nope.inp, which does not exist"),
+    ("workflow_link_unknown_node",
+     "manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md",
+     '@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping"',
+     '@ref hydraulics_ref_ch8_lts "8.5.6 Local time stepping"',
+     "workflow-links node 'ZZ' is not a node of workflow fv_substep"),
+    ("workflow_link_wrong_id",
+     "manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md",
+     'data-workflow="fv_substep"', 'data-workflow="fv_substep_x"',
+     "workflow-links names workflow 'fv_substep_x' but follows the block 'fv_substep'"),
+    ("workflow_link_detached",
+     "manuals/reference/hydraulics/sections/Chapter8-FiniteVolume.md",
+     "*Figure 8-5 Substep workflow",
+     '
\n
\n\n*Figure 8-5 Substep workflow',
+     "workflow-links block does not directly follow a mermaid block"),
+    ("hotspot_wrong_fig",
+     "manuals/engine/sections/Chapter1-ConceptualModel.md",
+     '
',
+     '
',
+     "fig-hotspots block for quality_ch9_heat_budget, but the page embeds no such figure"),
+    ("front_matter_stale",
+     "manuals/reference/quality.md",
+     "Figure 10-1. The transport policy matrix", "Figure 10-1. A stale caption nobody wrote",
+     "stale — quality: List of Figures"),
+    ("front_matter_missing_entry",
+     "manuals/reference/hydraulics.md",
+     "Figure 9-6 Where a node spill is booked", "Figure 9-9 Where a node spill is booked",
+     "stale — hydraulics: List of Figures"),
+    ("hotspot_bad_box",
+     "manuals/engine/sections/Chapter1-ConceptualModel.md",
+     'data-box="0.0900,0.0768,0.2400,0.1375"', 'data-box="0.2400,0.0768,0.0900,0.1375"',
+     "is not inside the image"),
+]
+
+
+def copy_docs(dst):
+    """Copy docs/ without the generated site; images are hard-linked (never mutated)."""
+
+    def copy_fn(src, dest):
+        if Path(src).suffix.lower() in IMAGE_EXT:
+            try:
+                os.link(src, dest)
+                return dest
+            except OSError:
+                pass
+        return shutil.copy2(src, dest)
+
+    def ignore(src, names):
+        # only the generated site at docs/html is skipped; docs/custom/html holds the header template
+        skip = {".DS_Store", "__pycache__"} | ({"html"} if Path(src) == DOCS else set())
+        return [n for n in names if n in skip]
+
+    shutil.copytree(DOCS, dst, copy_function=copy_fn, ignore=ignore)
+
+
+SRC_ROOT = ROOT / "src"
+
+
+def run_lint(docs_root):
+    p = subprocess.run([sys.executable, str(LINT), "--docs-root", str(docs_root),
+                        "--src-root", str(SRC_ROOT)],
+                       capture_output=True, text=True)
+    return p.returncode, p.stdout + p.stderr
+
+
+def main():
+    # --src-root pins the sources the coverage checks read. The default is this
+    # working tree; pass a checkout of HEAD (git archive HEAD src | tar -x) when a
+    # peer session has uncommitted parser edits, so the control run is not red for
+    # a section that is not yet in the branch.
+    global SRC_ROOT
+    argv = sys.argv[1:]
+    if argv[:1] == ["--src-root"] and len(argv) > 1:
+        SRC_ROOT = Path(argv[1]).resolve()
+    out = ROOT / "tests" / "output" / f"docs_lint_negative_{dt.date.today().isoformat()}"
+    if out.exists():
+        shutil.rmtree(out)
+    out.mkdir(parents=True)
+    summary = []
+    failures = 0
+
+    control = out / "control" / "docs"
+    copy_docs(control)
+    rc, log = run_lint(control)
+    (out / "control.log").write_text(log)
+    ok = rc == 0
+    summary.append(f"{'PASS' if ok else 'FAIL'}  control  (exit {rc}, expected 0)")
+    failures += 0 if ok else 1
+
+    for name, rel, old, new, expect in CASES:
+        dst = out / name / "docs"
+        copy_docs(dst)
+        if rel == "COPY":
+            # (name, "COPY", source, destination, expect): plant a second copy of
+            # an image — the mutation for orphan / collision / format checks.
+            src, dest = dst / old, dst / new
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(src, dest)
+            what = f"copy {old} -> {new}"
+        else:
+            target = dst / rel
+            text = target.read_text(errors="replace")
+            if old not in text:
+                summary.append(f"FAIL  {name}  mutation anchor not found in {rel}: {old[:50]!r}")
+                failures += 1
+                continue
+            target.write_text(text.replace(old, new, 1))
+            what = f"mutate {rel}: {old[:60]!r} -> {new[:60]!r}"
+        rc, log = run_lint(dst)
+        (out / f"{name}.log").write_text(f"$ lint --docs-root {dst}\n# {what}\n"
+                                         f"# expect: {expect}\n\n{log}")
+        ok = rc == 1 and expect in log
+        summary.append(f"{'PASS' if ok else 'FAIL'}  {name}  (exit {rc}, "
+                       f"{'found' if expect in log else 'MISSING'}: {expect})")
+        failures += 0 if ok else 1
+
+    text = "\n".join(summary) + f"\n\n{len(CASES)} cases, {failures} failures\n"
+    (out / "SUMMARY.txt").write_text(text)
+    print(text)
+    print(f"artifacts: {out}")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/refresh_gui_tagfile.py b/scripts/refresh_gui_tagfile.py
new file mode 100755
index 000000000..0d4098cf8
--- /dev/null
+++ b/scripts/refresh_gui_tagfile.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Refresh the committed Doxygen tagfile for the SWMMVis (GUI) manual.
+
+The engine manual links into the GUI manual with `\\ref manual_*` /
+`\\ref tutorial_*`. Doxygen resolves those through a tagfile that must exist on
+local disk when `doxygen Doxyfile` runs, so the tagfile is **committed** rather
+than fetched at build time: a build-time `curl` fails on fork PRs and whenever
+the GUI Pages site is briefly unavailable, and the hard requirement is that the
+engine docs build never breaks because of the other repo.
+
+Only `` entries are kept. The GUI Doxyfile's INPUT covers
+its whole `include/` and `src/` tree, so its published tag is ~6 MB of C++ API
+entries the engine has no use for; filtered to pages it is ~10 KB and stops the
+engine repo churning multi-megabyte diffs on every refresh.
+
+The page URLs in the filtered file are the ones Doxygen itself emitted from the
+real HTML run, so they are correct under `CREATE_SUBDIRS = YES` (which hashes
+page paths). That is why this filters a published tag rather than generating a
+second pages-only tag whose hashes would have to be assumed to match.
+
+    refresh_gui_tagfile.py            fetch and rewrite the committed tagfile
+    refresh_gui_tagfile.py --check    exit non-zero if the committed one is stale
+    refresh_gui_tagfile.py --from F   read a local tagfile instead of fetching
+
+Run it by hand when the GUI manual gains, loses or renames a page.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+import urllib.error
+import urllib.request
+import xml.etree.ElementTree as ET
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+TAGFILE = ROOT / "docs" / "tags" / "swmmvis-manual.tag"
+SOURCE_URL = "https://www.hydrocouple.org/openswmm.gui/openswmm.gui.tag"
+
+
+# Only the GUI manual's own namespace is imported. Both repos declare a page
+# called `authors`, and Doxygen resolves an imported page id ahead of the local
+# one — so importing it would make every engine `@ref authors` point at the GUI
+# site and drop the engine's own authors page from the nav, with the build still
+# green. Restricting to these prefixes keeps the two namespaces disjoint.
+KEEP_PREFIXES = ("manual_", "tutorial_")
+
+
+def filtered(raw: bytes) -> bytes:
+    root = ET.fromstring(raw)
+    kept = [c for c in list(root)
+            if c.get("kind") == "page"
+            and (c.findtext("name") or "").startswith(KEEP_PREFIXES)]
+    if not kept:
+        raise SystemExit("FAIL: the source tagfile contains no GUI manual pages "
+                         f"(expected ids starting with {' or '.join(KEEP_PREFIXES)})")
+    for c in list(root):
+        root.remove(c)
+    for c in kept:
+        root.append(c)
+    return ET.tostring(root, encoding="utf-8", xml_declaration=True) + b"\n"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--check", action="store_true",
+                   help="exit non-zero if the committed tagfile differs")
+    p.add_argument("--from", dest="src", help="read this local tagfile instead of fetching")
+    p.add_argument("--url", default=SOURCE_URL, help=f"source URL (default {SOURCE_URL})")
+    args = p.parse_args()
+
+    if args.src:
+        raw = pathlib.Path(args.src).read_bytes()
+    else:
+        try:
+            with urllib.request.urlopen(args.url, timeout=30) as r:
+                raw = r.read()
+        except (urllib.error.URLError, TimeoutError) as exc:
+            # Never fail a build because the other site is unreachable.
+            print(f"could not fetch {args.url} ({exc}) — skipped")
+            return 0
+
+    fresh = filtered(raw)
+    pages = len(list(ET.fromstring(fresh)))
+
+    if args.check:
+        if not TAGFILE.exists():
+            print(f"FAIL: {TAGFILE.relative_to(ROOT)} does not exist", file=sys.stderr)
+            return 1
+        if TAGFILE.read_bytes() == fresh:
+            print(f"{TAGFILE.relative_to(ROOT)} is current ({pages} pages)")
+            return 0
+        print(f"FAIL: {TAGFILE.relative_to(ROOT)} is stale; "
+              f"run scripts/refresh_gui_tagfile.py", file=sys.stderr)
+        return 1
+
+    TAGFILE.parent.mkdir(parents=True, exist_ok=True)
+    TAGFILE.write_bytes(fresh)
+    print(f"wrote {TAGFILE.relative_to(ROOT)} ({pages} pages, {len(fresh)} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/split_user_manual.py b/scripts/split_user_manual.py
deleted file mode 100644
index e459b722c..000000000
--- a/scripts/split_user_manual.py
+++ /dev/null
@@ -1,86 +0,0 @@
-#!/usr/bin/env python3
-"""One-time migration: split docs/manuals/user/user_manual.md into per-chapter
-@page sources under docs/manuals/user/manual/, mirroring the reference-manual
-restructure. See plans/DOCUMENTATION_OVERHAUL_PLAN_2026-08-11.md.
-
-Existing {#user_manual_*} heading anchors become the page ids, so any @ref
-to them keeps resolving. Deeper headings keep their explicit anchors.
-"""
-import re
-import sys
-from pathlib import Path
-
-USER = Path(__file__).resolve().parent.parent / "docs" / "manuals" / "user"
-
-# heading-text prefix -> output filename
-FILE_MAP = [
-    ("CHAPTER 1", "Chapter1.md"),
-    ("CHAPTER 2", "Chapter2.md"),
-    ("CHAPTER 3", "Chapter3.md"),
-    ("CHAPTER 4", "Chapter4.md"),
-    ("CHAPTER 5", "Chapter5.md"),
-    ("CHAPTER 6", "Chapter6.md"),
-    ("CHAPTER 7", "Chapter7.md"),
-    ("CHAPTER 8", "Chapter8.md"),
-    ("CHAPTER 9", "Chapter9.md"),
-    ("CHAPTER 10", "Chapter10.md"),
-    ("CHAPTER 11", "Chapter11.md"),
-    ("CHAPTER 12", "Chapter12.md"),
-    ("CHAPTER 13", "Chapter13.md"),
-    ("APPENDIX A", "AppendixA.md"),
-    ("APPENDIX B", "AppendixB.md"),
-    ("APPENDIX C", "AppendixC.md"),
-    ("APPENDIX D", "AppendixD.md"),
-    ("APPENDIX E", "AppendixE.md"),
-]
-
-HEAD = re.compile(r"^## +(?!#)(.+?)(?: *\{#([a-z_0-9]+)\})? *$", re.M)
-
-
-def promote(body):
-    out = []
-    for ln in body.split("\n")[1:]:
-        m = re.match(r"^(#{3,6}) ", ln)
-        out.append("#" * (len(m.group(1)) - 1) + ln[len(m.group(1)) :] if m else ln)
-    return "\n".join(out).lstrip("\n")
-
-
-def main():
-    mono_path = USER / "user_manual.md"
-    text = mono_path.read_text()
-    matches = list(HEAD.finditer(text))
-    front = text[: matches[0].start()]
-    blocks = []
-    for i, m in enumerate(matches):
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
-        blocks.append((m.group(1).strip(), m.group(2), text[m.start() : end]))
-
-    used, pages = set(), []
-    for prefix, fname in FILE_MAP:
-        hit = next(
-            (b for b in blocks if b[0].upper().startswith(prefix) and b[0] not in used),
-            None,
-        )
-        if hit is None:
-            print(f"MISSING: {prefix}")
-            continue
-        used.add(hit[0])
-        heading, anchor, body = hit
-        page_id = anchor or "user_manual_" + re.sub(r"\W+", "_", prefix.lower())
-        content = f"@page {page_id} {heading}\n\n@tableofcontents\n\n{promote(body)}"
-        (USER / "manual" / fname).write_text(content + "\n")
-        pages.append((page_id, heading))
-        print(f"wrote manual/{fname:14s} @page {page_id}")
-
-    leftover = [b[0] for b in blocks if b[0] not in used]
-    print(f"front-matter blocks kept in parent: {leftover}")
-    kept = "\n".join(b[2].rstrip() + "\n" for b in blocks if b[0] not in used)
-    sub = "\n".join(f"- @subpage {pid} — {h}" for pid, h in pages)
-    mono_path.write_text(
-        front.rstrip() + "\n\n" + kept.rstrip() + "\n\n## Manual Contents\n\n" + sub + "\n"
-    )
-    print("parent rewritten: user_manual.md")
-
-
-if __name__ == "__main__":
-    sys.exit(main())
diff --git a/scripts/test_version_sync.py b/scripts/test_version_sync.py
new file mode 100644
index 000000000..8d041851e
--- /dev/null
+++ b/scripts/test_version_sync.py
@@ -0,0 +1,59 @@
+"""Regression checks for native release and Python development-wheel alignment."""
+from contextlib import redirect_stderr, redirect_stdout
+from io import StringIO
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+from unittest.mock import patch
+
+import check_version_sync as sync
+
+
+class VersionSyncTests(unittest.TestCase):
+    def check_versions(self, base, companion=None, pin=None, native="alpha.4"):
+        companion = base if companion is None else companion
+        pin = base if pin is None else pin
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "python").mkdir()
+            (root / "packages/gpu-omp").mkdir(parents=True)
+            (root / "CMakeLists.txt").write_text(
+                f'project(openswmm VERSION 6.0.0)\nset(OPENSWMM_PRERELEASE "{native}")\n')
+            suffix = f"-{native}" if native else ""
+            (root / "vcpkg.json").write_text(
+                '{"version-semver": "6.0.0' + suffix + '"}')
+            (root / "python/pyproject.toml").write_text(f'version = "{base}"\n')
+            (root / "packages/gpu-omp/pyproject.toml").write_text(
+                f'version = "{companion}"\ndependencies = ["openswmm == {pin}"]\n')
+            with patch.object(sync, "ROOT", root), redirect_stdout(StringIO()), redirect_stderr(StringIO()):
+                return sync.main()
+
+    def test_matching_development_builds(self):
+        for version in ("6.0.0a4.dev1", "6.0.0a4.dev12"):
+            with self.subTest(version=version):
+                self.assertEqual(self.check_versions(version), 0)
+
+    def test_completed_alpha_and_stable_releases(self):
+        self.assertEqual(self.check_versions("6.0.0a4"), 0)
+        self.assertEqual(self.check_versions("6.0.0", native=""), 0)
+
+    def test_companion_must_match_development_number(self):
+        self.assertEqual(self.check_versions("6.0.0a4.dev1", "6.0.0a4.dev2"), 1)
+
+    def test_companion_cannot_drop_development_suffix(self):
+        self.assertEqual(self.check_versions("6.0.0a4.dev1", "6.0.0a4"), 1)
+
+    def test_dependency_pin_must_include_development_suffix(self):
+        self.assertEqual(self.check_versions("6.0.0a4.dev1", pin="6.0.0a4"), 1)
+
+    def test_python_still_must_match_native_release(self):
+        self.assertEqual(self.check_versions("6.0.0a3.dev1"), 1)
+        self.assertEqual(self.check_versions("6.0.0.dev1"), 1)
+
+    def test_invalid_suffix_is_rejected(self):
+        with self.assertRaises(ValueError):
+            self.check_versions("6.0.0a4.devbanana")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 733b37b6d..2bd935631 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -27,6 +27,14 @@ add_subdirectory(engine)   # → openswmm_engine (output name: openswmm.engine)
 # ---- CLI ----
 add_subdirectory(cli)
 
+# O4 diagnostic driver — off by default. It is a debugging instrument, not a
+# shipped artefact, and it should not lengthen an ordinary build.
+option(OPENSWMM_BUILD_O4_DIFFERENTIAL
+       "Build the O4 API/CLI differential driver" OFF)
+if(OPENSWMM_BUILD_O4_DIFFERENTIAL)
+    add_subdirectory(tools/o4_differential)
+endif()
+
 # ---- openswmm2d (2D FVHM solver — future coupling target; disabled for now) ----
 # add_subdirectory(openswmm2d)
 
diff --git a/src/engine/2d/SurfaceRouter2D.cpp b/src/engine/2d/SurfaceRouter2D.cpp
index e6b5cb066..951348806 100644
--- a/src/engine/2d/SurfaceRouter2D.cpp
+++ b/src/engine/2d/SurfaceRouter2D.cpp
@@ -10,6 +10,7 @@
 #include "mesh/MeshBuilder.hpp"
 #include "mesh/VertexReconstruction.hpp"
 #include "mesh/VfrClosure.hpp"
+#include "mesh/QuadVfr.hpp"
 #include "solver/SurfaceFluxCalculator.hpp"
 #include "solver/ExplicitInertialSolver.hpp"
 #ifdef OPENSWMM_HAS_2D
@@ -19,6 +20,11 @@
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
 #include "../core/PerfTimers.hpp"
+#include "../core/ThreadInfo.hpp"
+#include "../hydrology/Gage.hpp"
+#include "../transport/components/ReactionModule/ReactionArdBinding.hpp"   // S4
+#include "../transport/TransportPolicy.hpp"                                  // E2
+#include "subsurface/SubsurfaceSections.hpp"                                 // G1
 
 #include 
 #include 
@@ -56,9 +62,16 @@ void refreshOutputGradients(const MeshData& mesh, SurfaceStateData& state,
 double headFromMeanDepth(const MeshData& mesh, const SolverOptions2D& opts,
                          int i, double d) {
     if (opts.cell_closure == CellClosure2D::VFR) {
-        double z1 = mesh.vz[mesh.tri_v0[i]];
-        double z2 = mesh.vz[mesh.tri_v1[i]];
-        double z3 = mesh.vz[mesh.tri_v2[i]];
+        if (mesh.cell_vertex_count(i) == 4) {
+            const auto u = static_cast(i);
+            return quadEtaFromMeanDepth(&mesh.quad_vfr_z[u * kQuadVfrZ],
+                                        mesh.quad_vfr_a[u * 2],
+                                        mesh.quad_vfr_a[u * 2 + 1], d,
+                                        opts.vfr_min_wet_frac);
+        }
+        double z1 = mesh.vz[mesh.cell_vertex(i, 0)];
+        double z2 = mesh.vz[mesh.cell_vertex(i, 1)];
+        double z3 = mesh.vz[mesh.cell_vertex(i, 2)];
         vfrSort3(z1, z2, z3);
         return vfrEtaFromMeanDepth(z1, z2, z3, d, opts.vfr_min_wet_frac);
     }
@@ -70,9 +83,9 @@ double headFromMeanDepth(const MeshData& mesh, const SolverOptions2D& opts,
 void SurfaceRouter2D::drainPendingRows() {
     if (mesh_.n_triangles() < 1) return;             // nothing to drain into
 
-    // Initialize per-edge boundary condition storage (n_triangles * 3 slots,
-    // all initialized to WALL with zero head/slope/cum_flux).
-    boundary_.resize(mesh_.n_triangles() * 3);
+    // Initialize per-edge boundary condition storage (n_cells * kMaxCellVerts
+    // slots, all initialized to WALL with zero head/slope/cum_flux).
+    boundary_.resize(mesh_.n_edge_slots());
 
     // V-E3 — drain any [2D_BOUNDARY_CONDITIONS] rows the parser accumulated
     // into boundary_. Out-of-range rows are silently skipped — defensive
@@ -81,8 +94,8 @@ void SurfaceRouter2D::drainPendingRows() {
         const int n_edges = boundary_.size();
         for (const auto& r : pending_bc_rows_) {
             if (r.tri < 0 || r.tri >= mesh_.n_triangles()) continue;
-            if (r.edge < 0 || r.edge > 2) continue;
-            const int idx = r.tri * 3 + r.edge;
+            if (r.edge < 0 || r.edge >= mesh_.cell_vertex_count(r.tri)) continue;
+            const int idx = MeshData::slot(r.tri, r.edge);
             if (idx < 0 || idx >= n_edges) continue;
             boundary_.edge_bc_type[idx] = static_cast(r.bc_type);
             switch (static_cast(r.bc_type)) {
@@ -139,15 +152,15 @@ void SurfaceRouter2D::drainPendingRows() {
         };
 
         std::unordered_map, EdgeKeyHash> edge_key_to_slots;
-        edge_key_to_slots.reserve(static_cast(mesh_.n_triangles()) * 3);
+        edge_key_to_slots.reserve(static_cast(mesh_.n_edge_slots()));
 
         const int nt = mesh_.n_triangles();
         for (int t = 0; t < nt; ++t) {
-            const int v[3] = { mesh_.tri_v0[t], mesh_.tri_v1[t], mesh_.tri_v2[t] };
-            for (int e = 0; e < 3; ++e) {
-                const int va = v[(e + 1) % 3];
-                const int vb = v[(e + 2) % 3];
-                edge_key_to_slots[makeKey(va, vb)].push_back(t * 3 + e);
+            const int nvc = mesh_.cell_vertex_count(t);
+            for (int e = 0; e < nvc; ++e) {
+                int va, vb;
+                mesh_.cell_edge_vertices(t, e, va, vb);
+                edge_key_to_slots[makeKey(va, vb)].push_back(MeshData::slot(t, e));
             }
         }
 
@@ -226,16 +239,24 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
     const double mesh_to_si = (us == 0) ? ft_to_m : 1.0;
 
-    // SPECIFIED_STAGE boundary heads share the mesh's vertical datum, so they
-    // convert with the same factor and under the same condition as vz: rows
-    // authored in the project's display units (feet for US) scale to the SI
-    // metres the solver compares against bed elevations; an SI-tagged mesh
-    // file's rows are already metres. Constant heads are scaled once after
-    // drainPendingRows() below; timeseries-driven heads are scaled at every
-    // lookup in resolveBoundaryValues() (the table carries display units).
+    // CONSTANT SPECIFIED_STAGE heads live in the mesh sections and share the
+    // mesh's vertical datum, so they convert with the same factor and under
+    // the same condition as vz: rows authored in the project's display units
+    // (feet for US) scale to the SI metres the solver compares against bed
+    // elevations; an SI-tagged mesh file's rows are already metres. Scaled
+    // once after drainPendingRows() below.
     bc_stage_scale_ =
         (!options_.mesh_units_si && mesh_to_si != 1.0) ? mesh_to_si : 1.0;
 
+    // TS_STAGE / rating-curve STAGE values come from the 1D [TIMESERIES] /
+    // [CURVES] tables, which are authored in the project's display units
+    // whatever the mesh file is tagged — an SI-tagged mesh in a feet project
+    // still references a feet stage series. So this factor is FLOW_UNITS-
+    // driven only (like bc_flow_scale_), applied at every lookup in
+    // resolveBoundaryValues(). Previously tied to the mesh header, which
+    // read feet series as metres after any post-run save wrote the header.
+    bc_stage_ts_scale_ = mesh_to_si;
+
     // SPECIFIED_FLOW / TS_FLOW / RATING_CURVE discharges are authored in the
     // project's display flow units PER METRE of edge (the GUI's contract —
     // "Flow/m" in display units); the solver works in m³/s/m. Indexed by the
@@ -255,6 +276,14 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
         bc_flow_scale_ = (fu >= 0 && fu < 6) ? kFlowToCms[fu] : 1.0;
     }
 
+    // Record the factor that applies to this mesh — metres per model-CRS
+    // linear unit — outside the guard below, so a repeated initialize() that
+    // short-circuits the in-place scaling still reports the factor the stored
+    // coordinates carry. Consumed by Default2DOutputPlugin's `/crs` variable
+    // (issue #155).
+    options_.mesh_to_si_factor =
+        (!options_.mesh_units_si && mesh_to_si != 1.0) ? mesh_to_si : 1.0;
+
     // Convert mesh geometry from project length units (feet for US) to the SI
     // internal units the 2D solver expects. MUST run BEFORE buildMeshTopology
     // so all derived geometry (areas, edge lengths, centroids, midpoint Z) is
@@ -303,6 +332,8 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
             options_.rainfall_mode = RainfallMode::SYSTEM;
         else if (std::strcmp(rm, "natural") == 0)
             options_.rainfall_mode = RainfallMode::NATURAL_NEIGHBOUR;
+        else if (std::strcmp(rm, "nearest") == 0)
+            options_.rainfall_mode = RainfallMode::NEAREST_NEIGHBOUR;
         else if (std::strcmp(rm, "none") == 0)
             options_.rainfall_mode = RainfallMode::NONE;
     }
@@ -322,7 +353,24 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     // the SI mesh frame the centroids now live in. Rebuilds cleanly, so a
     // repeated initialize() is idempotent.
     interp_.build(mesh_.tri_cx, mesh_.tri_cy, ctx.spatial.gage_x, ctx.spatial.gage_y,
-                  ctx.n_gages(), mesh_to_si);
+                  ctx.n_gages(), mesh_to_si,
+                  options_.rainfall_mode == RainfallMode::NEAREST_NEIGHBOUR
+                      ? RainfallInterpolator::Method::NearestNeighbour
+                      : RainfallInterpolator::Method::NaturalNeighbour);
+    if (options_.rainfall_mode == RainfallMode::NATURAL_NEIGHBOUR ||
+        options_.rainfall_mode == RainfallMode::NEAREST_NEIGHBOUR) {
+        const auto& d = interp_.diagnostics();
+        if (d.unlocated || d.invalid || d.duplicates)
+            ctx.warnings.push_back("2D rainfall gages: " + std::to_string(d.unlocated) +
+                " without a location (0,0), " + std::to_string(d.invalid) +
+                " invalid coordinates, " + std::to_string(d.duplicates) +
+                " duplicate locations (first gage retained).");
+        if (!interp_.ready())
+            ctx.warnings.push_back("2D rainfall: no located gages; using the uniform system mean.");
+        if (d.idwCells)
+            ctx.warnings.push_back("2D rainfall: inverse-distance fallback used for " +
+                std::to_string(d.idwCells) + " cells outside the gage hull or with degenerate weights.");
+    }
 
     // Resolve deferred coupling node names → indices
     for (int v = 0; v < mesh_.n_vertices(); ++v) {
@@ -389,18 +437,24 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     // TS-driven entries (tseries slot == -2, name pending) are excluded:
     // their value is overwritten from the table each step and scaled at
     // lookup time; rating-curve discharges are likewise resolved per step.
-    if (bc_stage_scale_ != 1.0 || bc_flow_scale_ != 1.0) {
-        for (int idx = 0; idx < boundary_.size(); ++idx) {
-            const auto bt =
-                static_cast(boundary_.edge_bc_type[idx]);
-            if (bt == BoundaryType::SPECIFIED_STAGE
-                && boundary_.edge_bc_tseries[idx] == -1)
-                boundary_.edge_bc_head[idx] *= bc_stage_scale_;
-            else if (bt == BoundaryType::SPECIFIED_FLOW
-                     && boundary_.edge_bc_flow_tseries[idx] == -1)
-                boundary_.edge_bc_flow[idx] *= bc_flow_scale_;
-        }
+    // NOT guarded across initializes: drainPendingRows() above re-defaults
+    // boundary_ and re-applies the AUTHORED (display-unit) rows every time,
+    // so scaling once per drain IS exactly-once per value — a scaled-once
+    // flag here made a repeated initialize() revert the constants to their
+    // raw authored numbers (drain re-applied them, the guard skipped the
+    // rescale) and the writer then divided the raw flow a second time.
+    for (int idx = 0; idx < boundary_.size(); ++idx) {
+        const auto bt =
+            static_cast(boundary_.edge_bc_type[idx]);
+        if (bt == BoundaryType::SPECIFIED_STAGE
+            && boundary_.edge_bc_tseries[idx] == -1)
+            boundary_.edge_bc_head[idx] *= bc_stage_scale_;
+        else if (bt == BoundaryType::SPECIFIED_FLOW
+                 && boundary_.edge_bc_flow_tseries[idx] == -1)
+            boundary_.edge_bc_flow[idx] *= bc_flow_scale_;
     }
+    // Tells the writers to divide edge_bc_flow back to display units.
+    options_.bc_flow_to_si_applied = bc_flow_scale_;
 
     // A NORMAL_FLOW edge with zero bed slope produces zero Manning flux —
     // it silently behaves as a Wall (no auto-compute from bed geometry
@@ -576,9 +630,16 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
         if (cp.vertex_idx >= 0) {
             const int s = mesh_.vert_stencil_ptr[cp.vertex_idx];
             const int e = mesh_.vert_stencil_ptr[cp.vertex_idx + 1];
-            for (int k = s; k < e; ++k)
-                foot_m2 += mesh_.tri_area[mesh_.vert_stencil_idx[k]];
-            foot_m2 /= 3.0;  // each triangle contributes ~1/3 of its area per vertex
+            // Each cell contributes ~1/nv of its area per vertex (1/3 for a
+            // triangle, 1/4 for a quad). Triangle-only meshes keep the
+            // historical Σ/3 arithmetic exactly.
+            double foot_tri = 0.0, foot_quad = 0.0;
+            for (int k = s; k < e; ++k) {
+                const int c = mesh_.vert_stencil_idx[k];
+                if (mesh_.cell_vertex_count(c) == 4) foot_quad += mesh_.tri_area[c];
+                else                                 foot_tri  += mesh_.tri_area[c];
+            }
+            foot_m2 = foot_tri / 3.0 + foot_quad / 4.0;
         } else {
             foot_m2 = mesh_.tri_area[cp.cell_idx];
         }
@@ -642,13 +703,12 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     // loops (computeCellContinuity / computeFaceVelocity / update_statistics)
     // read options_.num_threads outside the OPENSWMM_HAS_2D block below.
 #if defined(SWMM_USE_OPENMP)
-    {
-        int max_t = omp_get_max_threads();
-        int req   = ctx.options.num_threads;
-        int n_thr = (req == 0) ? max_t : std::min(req, max_t);
-        if (mesh_.n_triangles() < 4 * n_thr) n_thr = 1;
-        options_.num_threads = n_thr;
-    }
+    // Same resolution rules as the 1D solvers (threadinfo::twoDThreads): 0 =
+    // auto, N honoured exactly with warnings; the triangle gate still applies.
+    thread_warnings_.clear();
+    options_.requested_threads = ctx.options.num_threads;
+    options_.num_threads = threadinfo::twoDThreads(
+        ctx.options.num_threads, mesh_.n_triangles(), &thread_warnings_);
 #else
     options_.num_threads = 1;
 #endif
@@ -674,15 +734,585 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     // Construct the time integrator: the Kokkos marcher plugin when installed
     // and eligible (OPENSWMM_2D_BACKEND policy + small-mesh gate), else the
     // serial ExplicitInertialSolver.
+    // S1 (overland transport): size the species state BEFORE the solver
+    // initialises, since the marcher sizes its face accumulators from it.
+    // Rows are the [POLLUTANTS] species only in S1; age, temperature and MSX
+    // rows arrive with S4 in the 1D engines' row order. Initial mass is zero
+    // — a `[2D_INITIAL_QUALITY]` surface is S2's — so a deck with pollutants
+    // and no 2D initial quality starts clean and stays clean until S2/S3
+    // give rainfall, boundaries and the coupling their concentrations.
+    // Sized to zero (transport off) when the model carries no pollutants or
+    // quality is ignored, so hydrodynamics-only models allocate nothing.
+    {
+        // S4: the 1D engines' row layout, verbatim (ArdEngine::initialize is
+        // the reference): pollutants, MSX species (when a reactions component
+        // is active and declares no WALL species — the same fallback the ARD
+        // engine takes, with the same warning), the reserved age row, the
+        // reserved temperature row LAST. IGNORE_QUALITY turns off the
+        // pollutant and MSX rows only: age and temperature are their own
+        // options, exactly as on the 1D side.
+        // E2: the class enables come from the one policy (TransportPolicy:
+        // the 1D rule plus the [2D_OPTIONS] TRANSPORT_* keys); the row order
+        // is the canonical SpeciesRegistry order (pollutants, MSX, age,
+        // temperature) that ArdEngine also uses. Same values as the pre-E2
+        // inline derivation whenever no TRANSPORT_* key is set.
+        const transport::ClassEnables en = transport::surface2DEnables(ctx);
+        if (!ctx.options.ignore_quality && options_.transport_msx &&
+            transport::ardReactionsActive(ctx) && en.msx_has_wall) {
+            ctx.warnings.push_back(
+                "2D transport: WALL species have no transport semantics on "
+                "the surface yet — MSX rows are not carried on the mesh "
+                "(the LEGACY element-local binding still runs them in 1D).");
+        }
+        const transport::RowLayout L = transport::canonicalRows(ctx, en);
+        const int np = L.n_pollut;
+        const int nm = L.n_msx;
+        const int na = en.age         ? 1 : 0;
+        const int nt = en.temperature ? 1 : 0;
+        const int ns = L.ns;
+        state_.transport.resize(ns, mesh_.n_triangles(),
+                                static_cast(node_coupling_points_.size()));
+        auto& tr = state_.transport;
+        tr.n_pollut = np;
+        tr.n_msx    = nm;
+        tr.age_row  = L.age_row;
+        tr.temp_row = L.temp_row;
+        tr.row_names = L.names;
+        (void)na; (void)nt;
+        ctx.nodes.coupling_tuple_age  = (tr.age_row  >= 0);
+        ctx.nodes.coupling_tuple_temp = (tr.temp_row >= 0);
+        if (tr.active()) {
+            // S4: the temperature row starts at the INITIAL_STATE source
+            // temperature (H1's convention for water in the network at t=0),
+            // as temperature-volume; age starts at 0. [2D_INITIAL_QUALITY]
+            // below may override either by name.
+            if (tr.temp_row >= 0) {
+                const double t0 = ctx.heat_config.source_temp(
+                    HeatSource::INITIAL_STATE, -1);
+                for (int c = 0; c < tr.n_cells; ++c)
+                    tr.cell_mass[tr.idx(tr.temp_row, c)] = t0 * state_.volume[c];
+            }
+            // S3: outfall discharge onto the mesh carries the outfall's
+            // concentration through a per-cell mass-rate density that
+            // scatters exactly as coupling_flux does. Sized only when an
+            // outfall point exists; junction spill is booked live instead.
+            if (std::any_of(coupling_points_.begin(), coupling_points_.end(),
+                            [](const CouplingPoint& c) { return c.is_outfall; }))
+                tr.coupling_src.assign(static_cast(ns) *
+                                       static_cast(mesh_.n_triangles()),
+                                       0.0);
+            // S2: rainfall carries the [POLLUTANTS] rain concentration —
+            // the same column the 1D runoff path uses, so a species that rains
+            // in at 10 mg/L on a subcatchment rains in at 10 mg/L on the mesh.
+            // S4: MSX rows rain in clean, age rains in at 0 (new water), the
+            // temperature row at the RAINFALL source temperature.
+            tr.rain_conc.assign(static_cast(ns), 0.0);
+            for (int p = 0; p < np; ++p) tr.rain_conc[static_cast(p)] =
+                ctx.pollutants.c_rain[static_cast(p)];
+            if (tr.temp_row >= 0)
+                tr.rain_conc[static_cast(tr.temp_row)] =
+                    ctx.heat_config.source_temp(HeatSource::RAINFALL, -1);
+            // S2: [2D_BOUNDARY_QUALITY] rows, species resolved by name here;
+            // the edge slot is resolved by the solver against its own
+            // boundary-edge list at initialize (it owns that list).
+            for (const auto& r : pending_bq_rows_) {
+                if (r.tri < 0 || r.tri >= mesh_.n_triangles())
+                    throw std::runtime_error(
+                        "[2D_BOUNDARY_QUALITY] TRI " + std::to_string(r.tri) +
+                        " is off the mesh (" +
+                        std::to_string(mesh_.n_triangles()) + " triangles).");
+                const int sp = tr.rowIndex(r.species);   // S4: any carried row
+                if (sp < 0)
+                    throw std::runtime_error(
+                        "[2D_BOUNDARY_QUALITY] unknown species '" + r.species +
+                        "' — declare it in [POLLUTANTS] / the reactions "
+                        "component, or name __WATER_AGE__ / __TEMPERATURE__ "
+                        "with that option on.");
+                // S4b: the age row is authored in HOURS like the 1D
+                // [INITIAL_QUALITY] / water-age sources and carried in
+                // seconds internally (D-A21).
+                const double conc = (sp == tr.age_row) ? r.conc * 3600.0 : r.conc;
+                tr.bc_quality_rows.push_back({MeshData::slot(r.tri, r.edge), sp, conc});
+            }
+        } else if (!pending_bq_rows_.empty()) {
+            throw std::runtime_error(
+                "[2D_BOUNDARY_QUALITY] rows are present but the model carries "
+                "no transported species ([POLLUTANTS] empty or IGNORE_QUALITY "
+                "set), so they could carry nothing.");
+        }
+        // S4: the node row-value publisher the marcher and the outfall
+        // injector read (spill / discharge arrive at the NODE's values).
+        node_row_conc_.assign(static_cast(ns) *
+                              static_cast(ctx.n_nodes()), 0.0);
+        state_.node_row_conc = &node_row_conc_;
+    }
+
+    // S7: cell coverages → buildup / washoff / sweeping. Resolved here, once
+    // the rows (species layout) and the mesh (tags, areas) are final; an
+    // "ERROR" diagnostic is fatal exactly like a bad [2D_INITIAL_QUALITY]
+    // row, the rest are warnings (inert under RAINFALL_MODE NONE, the
+    // double-counting notice). The marcher accumulates each cell's outflow
+    // only while `cell_runoff_vol` is sized.
+    if (surface_quality_.authored()) {
+        auto diags = surface_quality_.resolve(ctx, mesh_, state_.transport, options_);
+        for (auto& d : diags) {
+            if (d.rfind("ERROR", 0) == 0) throw std::runtime_error(d.substr(6));
+            ctx.warnings.push_back(std::move(d));
+        }
+        if (surface_quality_.active()) {
+            state_.transport.cell_runoff_vol.assign(
+                static_cast(mesh_.n_triangles()), 0.0);
+            state_.transport.gained_washoff.assign(
+                static_cast(state_.transport.n_species), 0.0);
+        }
+    }
+
     if (!solver_) {
-        solver_ = makeSurfaceSolver(options_, nullptr, mesh_.n_triangles());
+        // The Kokkos plugin covers all-triangle LOCAL_INERTIAL models only
+        // (SurfaceSolverFactory R6 gate); everything else runs on the CPU.
+        // S4b: the plugin also carries no transport rows (species, age,
+        // temperature) — a deck with TRANSPORT_* on runs the CPU marcher,
+        // loudly, rather than silently losing every row.
+        const bool plugin_ok =
+            mesh_.n_quads() == 0 &&
+            options_.momentum == Momentum2D::LOCAL_INERTIAL &&
+            !state_.transport.active();
+        solver_ = makeSurfaceSolver(options_, &backend_name_,
+                                    mesh_.n_triangles(), plugin_ok);
+        // Say which solver this run is on. Rides the advisory-warning path
+        // (code 0) with the thread notices, so it reaches the .rpt and the
+        // GUI's warning callback — the backend choice used to be visible on
+        // stderr only, and not at all when AUTO refused the plugin.
+        const char* closure =
+            options_.momentum == Momentum2D::FULL_SWE       ? "FULL_SWE" :
+            options_.momentum == Momentum2D::DIFFUSIVE_WAVE ? "DIFFUSIVE_WAVE" :
+                                                              "LOCAL_INERTIAL";
+        char buf[320];
+        std::snprintf(buf, sizeof buf,
+            "2D solver: %s; MOMENTUM_EQUATION %s; LTS_TIERS %d; %d cells "
+            "(%d quads)%s",
+            backend_name_.c_str(), closure, options_.lts_tiers,
+            mesh_.n_triangles(), mesh_.n_quads(),
+            plugin_ok ? "" :
+            state_.transport.active()
+                ? " — the GPU/Kokkos plugin carries no transport rows "
+                  "(species / age / temperature); CPU marcher used"
+                : " — the GPU/Kokkos plugin serves all-triangle "
+                  "LOCAL_INERTIAL models only");
+        thread_warnings_.emplace_back(buf);
     }
     solver_->initialize(mesh_, state_, options_);
+
+    // G1: the two-zone groundwater kernel, if [2D_AQUIFER] was authored. It
+    // shares the marcher's unique-edge topology (one graph, one orientation
+    // convention) and its LTS ladder, so it needs the concrete CPU marcher.
+    // The GPU/Kokkos backend has no subsurface hooks — say so plainly rather
+    // than running the surface with a silently inert aquifer.
+    // [2D_OPTIONS] GROUNDWATER is the process enable over the top of that:
+    // AUTO (the default, and what every deck written before the key means)
+    // runs iff rows were authored; NO keeps the rows — they still save — and
+    // runs without the subsurface, exactly as INFILTRATION NO does.
+    const bool gw_wanted = options_.groundwater < 0 ? !aquifer_cfg_.empty()
+                                                    : options_.groundwater > 0;
+    if (options_.groundwater == 0 && !aquifer_cfg_.empty())
+        ctx.warnings.push_back(
+            "[2D_OPTIONS] GROUNDWATER NO — the [2D_AQUIFER*] rows are kept "
+            "but no subsurface runs this simulation.");
+    if (gw_wanted && !aquifer_cfg_.empty()) {
+        auto* marcher = dynamic_cast(solver_.get());
+        if (marcher == nullptr)
+            throw std::runtime_error(
+                "[2D_AQUIFER] the two-zone groundwater kernel runs on the CPU "
+                "explicit marcher only; this run selected the '" +
+                backend_name_ + "' backend.");
+        // G-X2: node [COORDINATES] are project map units (feet on a US
+        // project); the mesh is SI here, so the locator takes the same
+        // factor the vertices were scaled by.
+        const auto aq_errs = resolveSubsurface(ctx, mesh_, aquifer_cfg_,
+                                               aquifer_node_names_, mesh_to_si);
+        if (!aq_errs.empty()) throw std::runtime_error(aq_errs.front());
+        const std::string aq_err = subsurface_.initialize(
+            mesh_, marcher->inertialEdges(), options_, gwUnitFactors(ctx),
+            static_cast(ctx.nodes.invert_elev.size()), aquifer_cfg_,
+            ctx.warnings);
+        if (!aq_err.empty()) throw std::runtime_error(aq_err);
+        marcher->setSubsurface(&subsurface_);
+        // G-X1 (2026-09-19): the aquifer's node beds sample the 1D heads
+        // through `state_.nodes_1d`, which only the orifice coupling used to
+        // publish — a bed under a node with no [2D_VERTEX_NODE_MAP] entry
+        // never exchanged at all. The volumes still travel through
+        // `nodes.coupling_volume`, which assembleLateralInflows drains for
+        // every node, so nothing else is needed for an un-coupled node.
+        if (subsurface_.active() && !subsurface_.nodeBeds().empty())
+            state_.nodes_1d = &ctx.nodes;
+        // G-X2 one-owner rule: a storage node with a bed exchanges through
+        // the conductance channel, so its own Green-Ampt exfiltration is
+        // switched off (ExfilSolver reads the flag); running both would
+        // lose the same water twice. Named once so the modeller sees it.
+        if (subsurface_.active()) {
+            ctx.nodes.aquifer2d_bed.assign(ctx.nodes.invert_elev.size(), 0);
+            std::string superseded;
+            for (const auto& b : subsurface_.nodeBeds()) {
+                if (b.cell < 0 || b.node < 0 ||
+                    static_cast(b.node) >= ctx.nodes.aquifer2d_bed.size())
+                    continue;
+                ctx.nodes.aquifer2d_bed[static_cast(b.node)] = 1;
+                const int sr = ctx.node_subtypes.storage_row(b.node);
+                if (sr >= 0 &&
+                    static_cast(sr) < ctx.node_subtypes.storages.exfil_ksat.size() &&
+                    ctx.node_subtypes.storages.exfil_ksat[static_cast(sr)] > 0.0) {
+                    if (!superseded.empty()) superseded += ", ";
+                    superseded += ctx.node_names.name_of(b.node);
+                }
+            }
+            if (!superseded.empty())
+                ctx.warnings.push_back(
+                    "2D aquifer: storage node(s) " + superseded +
+                    " have a bed on the mesh; their [STORAGE] exfiltration is "
+                    "replaced by the node <-> aquifer exchange (one owner).");
+        }
+        // T7.1 (2026-09-20): the aquifer's own transported tuple. Rows come
+        // from TransportPolicy — the same authority the surface used above,
+        // so a species is the same row index in both domains and the seam
+        // between them is one concentration, not a mapping. Sized after the
+        // kernel initialized, because its enables ask whether the kernel is
+        // live at all.
+        if (subsurface_.active()) {
+            const transport::ClassEnables gen = transport::groundwaterEnables(ctx);
+            const transport::RowLayout GL = transport::canonicalRows(ctx, gen);
+            RowLayoutLite rows;
+            rows.n_species = GL.ns;
+            rows.n_pollut  = GL.n_pollut;
+            rows.n_msx     = GL.n_msx;
+            rows.age_row   = GL.age_row;
+            rows.temp_row  = GL.temp_row;
+            rows.names     = GL.names;
+            // T7.2: the `[POLLUTANTS]` decay column, row-aligned with the
+            // layout above — a `[GW_SORPTION]` row with no DECAY of its own
+            // falls back to it, so a species decays at the same rate in the
+            // aquifer as it does in the pipes unless the modeller says
+            // otherwise.
+            std::vector pollut_decay(
+                static_cast(std::max(0, GL.ns)), 0.0);
+            for (int p = 0; p < GL.n_pollut &&
+                            static_cast(p) < ctx.pollutants.k_decay.size(); ++p)
+                pollut_decay[static_cast(p)] =
+                    ctx.pollutants.k_decay[static_cast(p)];
+            subsurface_.initTransport(rows, &gw_, pollut_decay, ctx.warnings);
+        }
+
+        // G-X3 (2026-09-19): conduit seepage → the cells the conduit crosses.
+        // Resolved once; booked every routing step (advancePostRouting).
+        aquifer_link_shares_.clear();
+        aquifer_link_ids_.clear();
+        const auto link_mode = subsurface_.options().link_seepage;
+        if (subsurface_.active() && link_mode != GwLinkMode::NONE) {
+            int n_conduits = 0;
+            aquifer_link_shares_ = resolveLinkSeepage(ctx, mesh_, aquifer_cfg_,
+                                                      aquifer_link_names_,
+                                                      mesh_to_si, n_conduits);
+            for (const auto& sh : aquifer_link_shares_)
+                if (aquifer_link_ids_.empty() || aquifer_link_ids_.back() != sh.link)
+                    aquifer_link_ids_.push_back(sh.link);
+            if (n_conduits > 0)
+                ctx.warnings.push_back(
+                    link_mode == GwLinkMode::TWO_WAY
+                        // G-X4: new physics, named as such.
+                        ? "2D aquifer: " + std::to_string(n_conduits) +
+                          " conduit(s) exchange with the aquifer along their length "
+                          "through the signed conductance law; a reach under the water "
+                          "table GAINS (LINK_SEEPAGE TWO_WAY; AUTO keeps the exchange "
+                          "one-way, NONE keeps seepage a system loss)."
+                        : "2D aquifer: " + std::to_string(n_conduits) +
+                          " conduit(s) with a [LOSSES] seepage rate cross the mesh; their "
+                          "seepage is delivered into the aquifer cells they cross, by length "
+                          "(LINK_SEEPAGE AUTO; LINK_SEEPAGE NONE keeps it a system loss).");
+            // G-X4: seed the frozen coupling so the very first routing step
+            // — which runs before any publish — already sees the law.
+            if (link_mode == GwLinkMode::TWO_WAY) publishLinkCoupling(ctx);
+        }
+    }
 #endif
 
+    // §5.5 track I — resolve the [2D_INFILTRATION*] rows against the mesh
+    // (D-I3: per-cell override > tag > '*' > none) now that tri_tag and the
+    // triangle count are final, and the solver has reconstructed the initial
+    // depths the kernels read. Validation failures (unsupported destination,
+    // out-of-range cell, bad parameters) are reported like the mesh ones.
+    // Cheap no-op with no sections present: resolve() drops straight back to
+    // the unconfigured fast path.
+    {
+        // E2 — the [2D_OPTIONS] infiltration keys act on the rows here, once,
+        // before resolution: INFIL_DESTINATION fills every row that did not
+        // spell its own DEST; INFIL_DEFAULT_METHOD NONE drops the '*' row for
+        // the run, a method must agree with the '*' row (its parameters live
+        // there). INFIL_STEP was folded into infil_.options() at open.
+        if (!options_.infil_destination.empty() &&
+            options_.infil_destination != "LOST") {
+            Infil2DDest dest = Infil2DDest::LOST;
+            if (parseInfil2DDest(options_.infil_destination, dest)) {
+                for (auto& d : infil_.defaults())  if (!d.row.dest_explicit) d.row.dest = dest;
+                for (auto& o : infil_.overrides()) if (!o.row.dest_explicit) o.row.dest = dest;
+            }
+        }
+        if (!options_.infil_default_method.empty()) {
+            auto& defs = infil_.defaults();
+            auto star = std::find_if(defs.begin(), defs.end(),
+                                     [](const Infil2DDefault& d) { return d.tag == "*"; });
+            if (options_.infil_default_method == "NONE") {
+                if (star != defs.end()) {
+                    ctx.warnings.push_back(
+                        "[2D_OPTIONS] INFIL_DEFAULT_METHOD NONE — the '*' row of "
+                        "[2D_INFILTRATION_DEFAULTS] is not applied this run "
+                        "(tag and per-cell rows still are).");
+                    defs.erase(star);
+                }
+            } else if (star == defs.end()) {
+                ctx.warnings.push_back(
+                    "[2D_OPTIONS] INFIL_DEFAULT_METHOD " + options_.infil_default_method +
+                    " names no '*' row in [2D_INFILTRATION_DEFAULTS] — the method "
+                    "needs that row's parameters; nothing infiltrates by default.");
+            } else if (options_.infil_default_method !=
+                       std::string(infil2DMethodToken(star->row))) {
+                throw std::runtime_error(
+                    "[2D_OPTIONS] INFIL_DEFAULT_METHOD " + options_.infil_default_method +
+                    " conflicts with the '*' row of [2D_INFILTRATION_DEFAULTS] (" +
+                    infil2DMethodToken(star->row) + ") — edit the row, whose "
+                    "parameters belong to its method.");
+            }
+        }
+        // G1: AQUIFER_2D is legal exactly when a [2D_AQUIFER] resolved above.
+        // Told before resolve() because that is where the destinations are
+        // validated.
+        infil_.setAquifer2DAvailable(subsurface_.active());
+        std::string infil_err;
+        if (!infil_.resolve(mesh_, ctx.options, infil_err))
+            throw std::runtime_error(infil_err);
+        // U3 (track I-b): resolve cell → containing subcatchment for every
+        // cell whose row routes to SUBCATCH_AQUIFER. Cell-generic: the
+        // centroid is MeshData's true-area centroid, valid for triangles and
+        // quads alike. Point-in-polygon (ray crossing) against the authored
+        // [Polygons]; the FIRST containing subcatchment wins and an overlap
+        // is reported once so a user does not silently lose recharge.
+        cell_subcatch_.clear();
+        subcatch_recharge_.clear();
+        {
+            bool any_aq = false;
+            for (const auto& r : infil_.resolvedRows())
+                if (r.has_method && r.dest == Infil2DDest::SUBCATCH_AQUIFER) {
+                    any_aq = true;
+                    break;
+                }
+            if (any_aq) {
+                const int nsub = ctx.n_subcatches();
+                if (nsub <= 0)
+                    throw std::runtime_error(
+                        "[2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER needs "
+                        "subcatchments with aquifers to receive the recharge; "
+                        "this model has none.");
+                // PROG §B.4 one-owner check: a subcatchment already owned by
+                // the integrated 2D groundwater component cannot also receive
+                // legacy recharge from the surface.
+                for (const auto& spec : ctx.process_component_specs)
+                    if (spec.id == "org.hydrocouple.openswmm.integrated2d")
+                        throw std::runtime_error(
+                            "[2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER "
+                            "conflicts with the registered "
+                            "org.hydrocouple.openswmm.integrated2d component: a "
+                            "subcatchment's aquifer has one owner. Use "
+                            "AQUIFER_2D with that component, or remove it.");
+
+                // G1, the same rule for the in-tree kernel. A [2D_AQUIFER]
+                // owns every infiltrating cell's water, so a cell routed to
+                // SUBCATCH_AQUIFER would be delivered TWICE — once into the
+                // subcatchment's legacy aquifer here, and once into the
+                // two-zone column by the marcher. Refused rather than
+                // silently arbitrated: which aquifer the recharge belongs to
+                // is the author's call, not ours.
+                if (subsurface_.active())
+                    throw std::runtime_error(
+                        "[2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER "
+                        "conflicts with the [2D_AQUIFER] section: infiltration "
+                        "has one owner, and a [2D_AQUIFER] already receives it. "
+                        "Use AQUIFER_2D (or LOST, which reads the same way "
+                        "under an aquifer), or remove the [2D_AQUIFER].");
+
+                const auto& px = ctx.spatial.subcatch_polygon_x;
+                const auto& py = ctx.spatial.subcatch_polygon_y;
+                auto contains = [&](std::size_t sub, double x, double y) {
+                    if (sub >= px.size() || px[sub].size() < 3) return false;
+                    const auto& xs = px[sub];
+                    const auto& ys = py[sub];
+                    bool in = false;
+                    for (std::size_t i = 0, j = xs.size() - 1; i < xs.size(); j = i++) {
+                        if (((ys[i] > y) != (ys[j] > y)) &&
+                            (x < (xs[j] - xs[i]) * (y - ys[i]) / (ys[j] - ys[i]) + xs[i]))
+                            in = !in;
+                    }
+                    return in;
+                };
+                // The mesh is SI metres here; the polygons are in the project's
+                // authored map units, which for a US-units project are feet
+                // (the same scaling initialize() applied to vx/vy).
+                const double inv = (options_.mesh_to_si_factor > 0.0)
+                                       ? 1.0 / options_.mesh_to_si_factor : 1.0;
+                cell_subcatch_.assign(static_cast(mesh_.n_triangles()), -1);
+                subcatch_recharge_.assign(static_cast(nsub), 0.0);
+                int unowned = 0, overlapped = 0;
+                for (int c = 0; c < mesh_.n_triangles(); ++c) {
+                    const auto uc = static_cast(c);
+                    const auto& row = infil_.resolvedRows()[uc];
+                    if (!row.has_method || row.dest != Infil2DDest::SUBCATCH_AQUIFER)
+                        continue;
+                    const double x = mesh_.tri_cx[uc] * inv;
+                    const double y = mesh_.tri_cy[uc] * inv;
+                    int owner = -1, hits = 0;
+                    for (int sidx = 0; sidx < nsub; ++sidx)
+                        if (contains(static_cast(sidx), x, y)) {
+                            if (owner < 0) owner = sidx;
+                            ++hits;
+                        }
+                    cell_subcatch_[uc] = owner;
+                    if (owner < 0) ++unowned;
+                    else if (hits > 1) ++overlapped;
+                }
+                if (unowned > 0)
+                    ctx.warnings.push_back(
+                        "[2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER: " +
+                        std::to_string(unowned) +
+                        " cell(s) lie outside every subcatchment polygon — "
+                        "their infiltration is LOST, as before.");
+                if (overlapped > 0)
+                    ctx.warnings.push_back(
+                        "[2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER: " +
+                        std::to_string(overlapped) +
+                        " cell(s) fall inside more than one subcatchment "
+                        "polygon — the first by index receives the recharge.");
+            }
+        }
+
+        // INFILTRATION NO keeps the rows (they still save) but runs dry;
+        // YES with nothing resolved is a deck that expects infiltration and
+        // gets none — say so.
+        if (options_.infiltration == 0 && infil_.active()) {
+            ctx.warnings.push_back(
+                "[2D_OPTIONS] INFILTRATION NO — the [2D_INFILTRATION*] rows are "
+                "kept but no cell infiltrates this run.");
+            infil_.deactivate();
+        } else if (options_.infiltration == 1 && !infil_.active()) {
+            ctx.warnings.push_back(
+                "[2D_OPTIONS] INFILTRATION YES but no [2D_INFILTRATION_DEFAULTS] "
+                "/ [2D_INFILTRATION] row resolved to a method — no cell "
+                "infiltrates this run.");
+        }
+    }
+
+    // S1/S2 — [2D_INITIAL_QUALITY]: seed species MASS = conc x cell volume,
+    // now that the solver has reconstructed the initial volumes. Resolution
+    // order is `* < TAG < CELL` (the D-I3 order the infiltration rows use),
+    // applied by ORDER — later writes win — rather than by comparison, the
+    // same argument the PE resolver made. Every failure is fatal: an unknown
+    // species or tag, or a cell off the mesh, is a row that would silently
+    // seed nothing (lessons 10/20).
+    if (!pending_iq_rows_.empty()) {
+        auto& tr = state_.transport;
+        if (!tr.active())
+            throw std::runtime_error(
+                "[2D_INITIAL_QUALITY] rows are present but the model carries "
+                "no transported species ([POLLUTANTS] empty or IGNORE_QUALITY "
+                "set), so they could seed nothing.");
+        const int nt = mesh_.n_triangles();
+        auto species_index = [&](const std::string& name) {
+            return tr.rowIndex(name);   // S4: any carried row; -1 if absent
+        };
+        auto seed = [&](int sp, int c, double conc) {
+            // S4b: `__WATER_AGE__` is authored in hours (the 1D convention,
+            // InitialQualitySeeds::initialAgeSecondsFor) and stored in seconds.
+            if (sp == tr.age_row) conc *= 3600.0;
+            tr.cell_mass[tr.idx(sp, c)] = conc * state_.volume[c];
+        };
+        for (int pass = 0; pass < 3; ++pass) {   // 0:'*', 1:TAG, 2:CELL
+            for (const auto& r : pending_iq_rows_) {
+                const int kind = r.all ? 0 : (r.tri < 0 ? 1 : 2);
+                if (kind != pass) continue;
+                const int sp = species_index(r.species);
+                if (sp < 0 || sp >= tr.n_species)
+                    throw std::runtime_error(
+                        "[2D_INITIAL_QUALITY] unknown species '" + r.species +
+                        "' — declare it in [POLLUTANTS] / the reactions "
+                        "component, or name __WATER_AGE__ / __TEMPERATURE__ "
+                        "with that option on.");
+                if (r.all) {
+                    for (int c = 0; c < nt; ++c) seed(sp, c, r.conc);
+                } else if (r.tri < 0) {
+                    bool hit = false;
+                    for (int c = 0; c < nt; ++c) {
+                        if (static_cast(c) < mesh_.tri_tag.size() &&
+                            mesh_.tri_tag[static_cast(c)] == r.tag) {
+                            seed(sp, c, r.conc);
+                            hit = true;
+                        }
+                    }
+                    if (!hit)
+                        throw std::runtime_error(
+                            "[2D_INITIAL_QUALITY] TAG '" + r.tag +
+                            "' matches no triangle, so this row would seed "
+                            "nothing.");
+                } else {
+                    if (r.tri >= nt)
+                        throw std::runtime_error(
+                            "[2D_INITIAL_QUALITY] CELL " +
+                            std::to_string(r.tri + 1) + " is beyond the mesh (" +
+                            std::to_string(nt) + " triangles).");
+                    seed(sp, r.tri, r.conc);
+                }
+            }
+        }
+    }
+    // S7: initial buildup on the cells ([2D_LOADINGS] or DRY_DAYS), after
+    // the coverages resolved above and before the first runoff step.
+    if (surface_quality_.active() && !ctx.options.ignore_quality)
+        surface_quality_.initState(ctx, mesh_);
+    infil_elapsed_ = 0.0;
+    if (infil_.active()) {
+        // Publish an initial held rate so the very first substep infiltrates
+        // instead of running a whole INFIL_STEP dry. The kernels are advanced
+        // by one cadence step here, matching how the runoff module evaluates
+        // at the start of a wet step.
+        infil_.updateRates(mesh_, state_, infil_.stepSeconds());
+        infil_cum_applied_.assign(
+            static_cast(mesh_.n_triangles()), 0.0);
+    } else {
+        // Left EMPTY (not zero-filled) so consumers can distinguish "no model"
+        // exactly as they do for Infil2D::cumulative().
+        infil_cum_applied_.clear();
+    }
+    rain_cum_.assign(static_cast(mesh_.n_triangles()), 0.0);
+    // C1: always sized (unlike infil_cum_applied_, which is empty when no
+    // model resolved). Coupling has no "not configured" state — a mesh with
+    // no coupling points simply reports zeros, which is the true answer.
+    coupling_cum_applied_.assign(
+        static_cast(mesh_.n_triangles()), 0.0);
+
     active_ = true;
     sim_time_ = 0.0;
+    gage_rate_.clear();
+    gage_cum_.clear();
+    gage_window_depth_.clear();
+    gage_window_rate_.clear();
+    rain_gage_last_.clear();
+    gage_since_ = 0.0;
+    gage_report_depth_.clear();
+    report_rain_cum_.clear();
+    report_rain_ms_ = -1.0;
     pending_dt_ = 0.0;
+    report_old_depth_.assign(
+        static_cast(mesh_.n_triangles()), 0.0);
+    report_old_head_.assign(
+        static_cast(mesh_.n_triangles()), 0.0);
+    report_window_old_ms_ = 0.0;
+    report_window_new_ms_ = 0.0;
+    report_old_valid_ = false;
 
     resetWindowAccumulators();
 
@@ -697,7 +1327,8 @@ void SurfaceRouter2D::initialize(SimulationContext& ctx) {
     // any sync batch fires — e.g. a hotstart-restored wet state) already
     // carries a physically consistent field instead of the resize() zeros.
     reconstructVertexRenderDepths(mesh_, state_, options_.dry_depth,
-                                  options_.num_threads);
+                                  options_.num_threads, render_eta_);
+    render_dirty_ = false;
 }
 
 
@@ -720,11 +1351,56 @@ void SurfaceRouter2D::updateOutfallsPreRouting(SimulationContext& ctx) {
 }
 
 
+bool SurfaceRouter2D::refreshDue(const SimulationContext& ctx,
+                                 double dt) const {
+    // Sampling cadence for the per-cell continuity residual, the face
+    // velocity and the cumulative envelopes update_statistics builds from
+    // them. Capped at 30 s because the envelopes are PEAK trackers: sampling
+    // them only at REPORT_STEP would quietly lower every reported maximum.
+    (void)ctx;
+    const double refresh_dt = std::max(dt, 30.0);
+    return co_refresh_elapsed_ + dt >= refresh_dt;
+}
+
+
+void SurfaceRouter2D::refreshRenderFields() {
+    reconstructVertexHeads(mesh_, state_, options_.num_threads);
+    refreshOutputGradients(mesh_, state_, options_);
+    reconstructVertexRenderDepths(mesh_, state_, options_.dry_depth,
+                                  options_.num_threads, render_eta_);
+    co_render_elapsed_ = 0.0;
+    render_dirty_      = false;
+}
+
+
 void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
                                     double t) {
     if (dt <= 0.0) return;
     perf::ScopedTimer tm_window(perf::sec_2d_window);
-    state_.save_state();
+    // Report-time blend: when this batch reaches/crosses the next report
+    // instant, capture the batch-start depth/head as the blend's old side
+    // (~two full-mesh copies once per REPORT step, not per routing step).
+    // The ms window mirrors ctx.elapsed_ms's `+= 1000*dt` recurrence —
+    // under default per-routing-step coupling the sequences are identical.
+    {
+        const double window_end_ms = report_window_new_ms_ + 1000.0 * dt;
+        if (window_end_ms >= ctx.next_report_ms) {
+            std::copy(state_.depth.begin(), state_.depth.end(),
+                      report_old_depth_.begin());
+            std::copy(state_.head.begin(), state_.head.end(),
+                      report_old_head_.begin());
+            report_window_old_ms_ = report_window_new_ms_;
+            report_old_valid_ = true;
+        }
+        report_window_new_ms_ = window_end_ms;
+    }
+    // Snapshot for computeCellContinuity, taken only on the batch whose
+    // output refresh will consume it. The diagnostic is
+    // (volume - old_volume)/dt against the END-OF-BATCH flux and source
+    // rates, so its snapshot must be one batch old — not one refresh window
+    // old — and every other batch's two full-mesh memcpys were pure cost.
+    const bool refresh_due = refreshDue(ctx, dt);
+    if (refresh_due) state_.save_state();
 
     // Outfall discharge → 2D: accumulate this step's 1D outfall discharge and
     // inject it as a constant-rate source over the subcycle (same ledger as
@@ -736,19 +1412,41 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
                                        window_avail_budget_,
                                        /*sample_row*/ nullptr) > 0)
         ++outfall_clamp_windows_;
-    for (const auto& cp : coupling_points_) {
-        if (!cp.is_outfall) continue;
-        if (cp.vertex_idx >= 0) {
-            const int s = mesh_.vert_stencil_ptr[cp.vertex_idx];
-            const int e = mesh_.vert_stencil_ptr[cp.vertex_idx + 1];
-            for (int k = s; k < e; ++k)
-                state_.coupling_flux[mesh_.vert_stencil_idx[k]] = 0.0;
-        } else if (cp.cell_idx >= 0) {
-            state_.coupling_flux[cp.cell_idx] = 0.0;
+    {
+        auto& tr = state_.transport;
+        auto clear_cell = [&](int c) {
+            state_.coupling_flux[c] = 0.0;
+            if (!tr.coupling_src.empty())            // S3: same targeted clear
+                for (int sp = 0; sp < tr.n_species; ++sp)
+                    tr.coupling_src[tr.idx(sp, c)] = 0.0;
+        };
+        for (const auto& cp : coupling_points_) {
+            if (!cp.is_outfall) continue;
+            if (cp.vertex_idx >= 0) {
+                const int s = mesh_.vert_stencil_ptr[cp.vertex_idx];
+                const int e = mesh_.vert_stencil_ptr[cp.vertex_idx + 1];
+                for (int k = s; k < e; ++k)
+                    clear_cell(mesh_.vert_stencil_idx[k]);
+            } else if (cp.cell_idx >= 0) {
+                clear_cell(cp.cell_idx);
+            }
         }
     }
+    // S3/S4: the outfall's published row values ride its discharge; the
+    // junction spill inside the marcher reads the same array. Refreshed once
+    // per batch here — the 1D side does not move during the advance.
+    publishNodeRows(ctx);
+    // T7.4: the aquifer samples a RECHARGING node's quality from the same
+    // published row the surface spill uses — one authority, so the two 2D
+    // seams can never disagree about what a node is carrying.
+    if (subsurface_.active() && subsurface_.transport().active())
+        subsurface_.setNodeRowConc(node_row_conc_.empty() ? nullptr
+                                                          : node_row_conc_.data(),
+                                   state_.transport.n_species);
     injectAccumulatedExchange(coupling_points_, mesh_, state_,
-                              window_outfall_accum_, dt, +1.0);
+                              window_outfall_accum_, dt, +1.0,
+                              state_.transport.coupling_src.empty()
+                                  ? nullptr : &node_row_conc_);
 
     // Rainfall / forcings on a coarse cadence: gage values change at the gage
     // timestep (minutes), and the per-cell interpolation apply is O(nt) — per
@@ -757,18 +1455,66 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
     // cadence: the forcing API just changed a prescription (or a one-shot
     // expired in clear_reset_forcings), so apply immediately — that keeps the
     // documented per-step RESET semantics under the batched co-advance.
+    // Rain is applied as the 1D applies it: each gage's piecewise-constant
+    // runoff-step rate (bookGageRates) integrated over this window, so a
+    // window that straddles a record boundary gets the exact mean rather than
+    // the end-of-window rate. A window with no rate change takes the rate
+    // itself, not a rounded integral, so the field is only rebuilt when a
+    // rate actually changes. A changed rate bypasses the cadence: holding
+    // the old field for up to 30 s shifted and dropped whole 1-min records
+    // (−12 % on a 1-min on/off storm at a 7 s routing step).
     co_forcing_elapsed_ += dt;
+    const std::size_t n_gages = static_cast(std::max(ctx.n_gages(), 0));
+    const double report_s = ctx.next_report_ms / 1000.0;
+    const bool rain_report_due = report_window_new_ms_ >= ctx.next_report_ms &&
+                                 report_s >= sim_time_ - 1e-8;
+    std::vector report_gage_depth;
+    if (rain_report_due) report_gage_depth.assign(n_gages, 0.0);
+    if (gage_rate_.size() == n_gages && n_gages > 0) {
+        const double t0 = sim_time_, t1 = sim_time_ + dt;
+        gage_window_rate_.resize(n_gages);
+        for (std::size_t g = 0; g < n_gages; ++g) {
+            const double d1 = gage_cum_[g] + gage_rate_[g] * std::max(0.0, t1 - gage_since_);
+            gage_window_rate_[g] = (gage_since_ <= t0) ? gage_rate_[g]
+                                                       : (d1 - gage_window_depth_[g]) / dt;
+            if (rain_report_due) {
+                // Unlike a linear blend of the whole 2D window, this keeps
+                // a short pulse entirely on its correct side of the report.
+                const double d_report = gage_since_ <= report_s
+                    ? gage_cum_[g] + gage_rate_[g] * (report_s - gage_since_)
+                    : gage_report_depth_[g];
+                report_gage_depth[g] = d_report - gage_window_depth_[g];
+            }
+            gage_window_depth_[g] = d1;
+        }
+    }
+    const std::vector& rates =
+        gage_window_rate_.size() == n_gages ? gage_window_rate_ : ctx.gages.rainfall;
+    bool gage_changed = rain_gage_last_.size() != n_gages;
+    for (std::size_t g = 0; !gage_changed && g < n_gages; ++g)
+        gage_changed = rates[g] != rain_gage_last_[g];
     if (co_forcing_elapsed_ >= 30.0 || co_forcing_first_ ||
-        state_.forcing_dirty) {
+        state_.forcing_dirty || gage_changed) {
         state_.forcing_dirty = false;
         updateRainfall(ctx);
-        std::fill(state_.evap_rate.begin(), state_.evap_rate.end(), 0.0);
+        // E2 [2D_OPTIONS] EVAPORATION: YES (default) = forcing only, the
+        // pre-E2 sink; CLIMATE = unforced cells take the project
+        // [EVAPORATION] rate (climate_state.evap_rate is internal ft/s);
+        // NO = the sink stays zero and forcing is ignored.
+        const double evap_base =
+            (options_.evaporation == 2)
+                ? std::max(0.0, ctx.climate_state.evap_rate) * 0.3048
+                : 0.0;
+        std::fill(state_.evap_rate.begin(), state_.evap_rate.end(), evap_base);
+        const bool evap_on = options_.evaporation != 0;
         for (std::size_t i = 0; i < state_.depth.size(); ++i) {
             if (state_.rainfall_forced[i] == 1)
                 state_.rainfall[i] = state_.rainfall_force_val[i];
             else if (state_.rainfall_forced[i] == 2)
                 state_.rainfall[i] += state_.rainfall_force_val[i];
-            if (state_.evap_forced[i] == 1)
+            if (!evap_on)
+                state_.evap_rate[i] = 0.0;
+            else if (state_.evap_forced[i] == 1)
                 state_.evap_rate[i] = state_.evap_force_val[i];
             else if (state_.evap_forced[i] == 2)
                 state_.evap_rate[i] += state_.evap_force_val[i];
@@ -780,6 +1526,39 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
         co_forcing_elapsed_ = 0.0;
         co_forcing_first_ = false;
     }
+
+    if (rain_report_due) {
+        // The spatial mapping is linear: rate×seconds maps to depth (m).
+        // Capture forcings before clear_reset_forcings expires one-shot API
+        // prescriptions. They apply uniformly over this executed window.
+        gageRatesToCells(ctx, report_gage_depth, report_rain_cum_);
+        const double span = std::clamp(report_s - sim_time_, 0.0, dt);
+        for (std::size_t i = 0; i < report_rain_cum_.size(); ++i) {
+            if (state_.rainfall_forced[i] == 1)
+                report_rain_cum_[i] = state_.rainfall_force_val[i] * span;
+            else if (state_.rainfall_forced[i] == 2)
+                report_rain_cum_[i] += state_.rainfall_force_val[i] * span;
+            report_rain_cum_[i] = rain_cum_[i] + report_rain_cum_[i] * mesh_.tri_area[i];
+        }
+        report_rain_ms_ = ctx.next_report_ms;
+    }
+
+    // §5.5.2 (D-I1) — infiltration is a HELD rate on its own INFIL_STEP
+    // cadence: recompute here (co-advance/routing cadence, after the rainfall
+    // the kernels read has been refreshed) and hold it constant in between.
+    // NEVER per marcher substep — that would be a different model and would
+    // drag infiltration into the LTS tiering. updateRates advances the kernel
+    // state of every model-carrying cell, active or not, so an inactive cell
+    // does not present full initial capacity when rain finally arrives.
+    // Entirely skipped (no loop, no allocation) when nothing resolved.
+    if (infil_.active()) {
+        infil_elapsed_ += dt;
+        if (infil_elapsed_ >= infil_.stepSeconds()) {
+            infil_.updateRates(mesh_, state_, infil_elapsed_);
+            infil_elapsed_ = 0.0;
+        }
+    }
+
     resolveBoundaryValues(ctx, t);
 
     // OPENSWMM_2D_HEAD_RAMP=1 (experimental, decoupling-viability study):
@@ -822,6 +1601,7 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
         solver_->advance(sim_time_, sim_time_ + dt);  // always reaches target
     }
     sim_time_ += dt;
+    applyAgingAndReactions(ctx, dt);   // S4: Lie-split after the advance
 
     // Junction ledger: the marcher integrated ∫Q_k dt (m³, + = 2D→1D drain)
     // per live point at substep cadence. Book the batch volume (1D ft³)
@@ -840,23 +1620,127 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
                 static_cast(node_coupling_points_[k].node_idx);
             ctx.nodes.coupling_volume[ni] += exch[k] * options_.flow_2d_to_1d;
         }
+        // S3 (D-2DT4, 2D→1D half): the drain's species mass, booked per point
+        // by the marcher at the CELL's concentration (conc·m³), goes straight
+        // to the node's mass QUEUE in 1D mass units (conc·ft³) — the same
+        // m³→ft³ factor the volume takes, so mass/volume stays the cell's
+        // concentration exactly. assembleLateralInflows drains both queues by
+        // one rule. exch_mass is drain-only (≥ 0); the spill side is booked on
+        // the 2D cell from nodes.conc and needs no queue (see the marcher).
+        {
+            const auto& tr = state_.transport;
+            const auto  ns = static_cast(tr.n_species);
+            auto& q = ctx.nodes.coupling_qual_queue;
+            if (ns > 0 && !tr.exch_mass.empty()) {
+                for (std::size_t k = 0; k < n; ++k) {
+                    const auto ni = static_cast(
+                        node_coupling_points_[k].node_idx);
+                    if ((ni + 1) * ns > q.size() || (k + 1) * ns > tr.exch_mass.size())
+                        continue;
+                    // The exchange flip-flops across the rim within one
+                    // window, and the VOLUME side nets (exch_ = ∫Q dt,
+                    // signed) while exch_mass holds the drain GROSS. Handing
+                    // the node gross mass with net water made a junction fed
+                    // at c0 read ABOVE c0 (the check measured 4.31). The
+                    // spill pairs against this window's own drain first —
+                    // min(spill, drain) of it, at the node's published
+                    // concentration, comes back out of the queued mass — and
+                    // only the net-negative remainder is the part §2.1's
+                    // implicit-CSTR argument covers (the node's volume drop
+                    // removes it at the mixed concentration).
+                    const double S = (k < tr.exch_spill.size())
+                                         ? tr.exch_spill[k] : 0.0;
+                    const double D = exch[k] + S;   // gross drain volume
+                    const double paired = std::min(S, (D > 0.0 ? D : 0.0));
+                    // S4: rows route by kind — pollutant rows to the
+                    // np-strided species queue, the age and temperature rows
+                    // to their scalar queues, MSX rows nowhere (the 1D node
+                    // has no MSX inflow accumulator for ANY loader yet — a 1D
+                    // seam, recorded; the mass stays in lost_coupling). The
+                    // pairing reads the published node ROW value, so the
+                    // temperature row pairs against the node temperature.
+                    const auto npol = static_cast(tr.n_pollut);
+                    for (std::size_t sp = 0; sp < ns; ++sp) {
+                        double inc = tr.exch_mass[k * ns + sp];
+                        if (paired > 0.0 &&
+                            (ni + 1) * ns <= node_row_conc_.size())
+                            inc -= paired * node_row_conc_[ni * ns + sp];
+                        double* row = nullptr;
+                        if (sp < npol) {
+                            if ((ni + 1) * npol <= q.size()) row = &q[ni * npol + sp];
+                        } else if (static_cast(sp) == tr.age_row) {
+                            if (ni < ctx.nodes.coupling_age_vol_queue.size())
+                                row = &ctx.nodes.coupling_age_vol_queue[ni];
+                        } else if (static_cast(sp) == tr.temp_row) {
+                            if (ni < ctx.nodes.coupling_temp_vol_queue.size())
+                                row = &ctx.nodes.coupling_temp_vol_queue[ni];
+                        }
+                        if (!row) continue;
+                        *row += inc * options_.flow_2d_to_1d;
+                        // Mass cannot be owed: a spill richer than the drain
+                        // (node above the cell) can push the pairing past
+                        // the queued mass by round-off; the floor keeps the
+                        // queue a mass. Not for the SIGNED temperature row.
+                        if (*row < 0.0 && !tr.signedRow(static_cast(sp)))
+                            *row = 0.0;
+                    }
+                }
+            }
+        }
     }
 
     // Boundary ledger: the marcher published the WINDOW-MEAN applied flux in
     // the boundary slots, so −flux·dt recovers the exact ∫F_applied dt.
-    {
-        const int ne = boundary_.size();
-        for (int idx = 0; idx < ne; ++idx)
-            if (static_cast(boundary_.edge_bc_type[idx]) !=
-                BoundaryType::WALL)
-                boundary_.edge_bc_cum_flux[idx] +=
-                    -state_.edge_flux[idx] * dt;
-    }
+    for (const int idx : bc_nonwall_slots_)
+        boundary_.edge_bc_cum_flux[idx] += -state_.edge_flux[idx] * dt;
 
     // Ledgers every batch (accumulateMassBalance reads coupling_volume as
     // "this batch's exchange", so it MUST run before the queue move below) …
     accumulateMassBalance(ctx, dt);
 
+    // G1: the aquifer's node exchange rides the same 1D delivery channel as
+    // the surface's — to the node they are the same thing, water arriving
+    // over the batch span — but it is booked HERE, and the position is the
+    // whole point.
+    //
+    // Two things above would eat it otherwise, and both did:
+    //
+    //  1. The surface pass a few lines up CLEARS `coupling_volume` for every
+    //     surface coupling point before accumulating `exch`. Booked before
+    //     that, an aquifer exchange on a node that ALSO has a surface
+    //     coupling point is silently zeroed — the water leaves the aquifer
+    //     ledger and never reaches the pipe. (The original comment here said
+    //     exactly that and the code then did it anyway.)
+    //  2. `accumulateMassBalance` reads `coupling_volume` back and books it
+    //     as `coupling_2d_to_1d_out` — a SURFACE term. Booked before that,
+    //     aquifer→pipe water is reported as surface exchange the surface
+    //     never lost, and the 2D surface continuity error grows by exactly
+    //     that volume.
+    //
+    // After both, the node still receives everything: `coupling_volume` is
+    // consumed by assembleLateralInflows at the start of the next routing
+    // step, not here. The aquifer's own ledger term is `led_node` (see
+    // swmm_gw2d_get_ledger), which is where this volume is accounted — it
+    // must not appear in the surface ledger as well.
+    if (subsurface_.active()) {
+        const auto& nv = subsurface_.nodeExchangeVolumes();
+        for (std::size_t ni = 0; ni < nv.size(); ++ni) {
+            if (nv[ni] == 0.0) continue;
+            if (ni < ctx.nodes.coupling_volume.size())
+                ctx.nodes.coupling_volume[ni] += nv[ni] * options_.flow_2d_to_1d;
+        }
+        // T7.4: the tuple rides the same channel as the volume. Aquifer →
+        // node mass goes into the node's coupling QUEUES, which
+        // assembleLateralInflows drains to the quality solver's inlets over
+        // the batch span — the surface's own path, so a node cannot tell
+        // (or need to tell) which 2D domain a parcel came from. The
+        // reverse direction, a node recharging the aquifer, is a LOSS the
+        // 1D quality continuity never had a row for; it is booked here so
+        // the balance closes.
+        flushAquiferNodeSpecies(ctx);
+        subsurface_.resetNodeExchangeVolumes();
+    }
+
     // … then hand the batch's junction volumes to the delivery QUEUE so
     // assembleLateralInflows drains them at a uniform rate over the batch
     // span instead of a single-step pulse.
@@ -884,22 +1768,30 @@ void SurfaceRouter2D::coAdvanceStep(SimulationContext& ctx, double dt,
     // at REPORT_STEP granularity; exchange/outfall heads use solver-fresh
     // state.head directly, not these derived fields.
     co_refresh_elapsed_ += dt;
-    const double refresh_dt =
-        std::max(dt, std::min(ctx.options.report_step > 0.0
-                                  ? ctx.options.report_step
-                                  : 30.0,
-                              30.0));
-    if (co_refresh_elapsed_ >= refresh_dt) {
-        reconstructVertexHeads(mesh_, state_, options_.num_threads);
-        refreshOutputGradients(mesh_, state_, options_);
-        computeCellContinuity(mesh_, state_, options_, co_refresh_elapsed_);
+    if (refresh_due) {
+        // dt, not the refresh span: old_volume was snapshotted at the top of
+        // THIS batch, and the flux/source rates the residual is measured
+        // against are this batch's end-of-step values.
+        computeCellContinuity(mesh_, state_, options_, dt);
         computeFaceVelocity(mesh_, state_, options_);
-        reconstructVertexRenderDepths(mesh_, state_, options_.dry_depth,
-                                      options_.num_threads);
+        // The cumulative envelopes DO integrate over the refresh span: this
+        // sample stands for the whole window in stat_cum_volume.
         state_.update_statistics(mesh_.tri_area, co_refresh_elapsed_,
                                  options_.num_threads);
         co_refresh_elapsed_ = 0.0;
     }
+
+    // Render fields on the REPORT_STEP grid. They feed the output snapshot and
+    // the bulk API getters and nothing else — no solver term, no coupling head
+    // reads them — so running them on the 30 s statistics cadence did six
+    // full-mesh passes for every one a consumer could see. A reader arriving
+    // off-grid gets them refreshed on demand (refreshRenderFieldsIfStale).
+    render_dirty_ = true;
+    co_render_elapsed_ += dt;
+    const double render_dt = std::max(dt, ctx.options.report_step > 0.0
+                                              ? ctx.options.report_step
+                                              : 30.0);
+    if (co_render_elapsed_ >= render_dt) refreshRenderFields();
 }
 
 
@@ -919,6 +1811,208 @@ void SurfaceRouter2D::computeCouplingConductances(
 }
 
 
+// G-X4 (2026-09-20): freeze the aquifer's side of the conduit exchange for
+// the routing step about to run. The two loss laws then need nothing but the
+// conduit row: a table elevation relative to the conduit's own mid invert, a
+// conductivity, a path length and a gain budget. Everything unit- and
+// datum-dependent is settled here, once per step per conduit, instead of in
+// the Picard loop.
+namespace {
+/// G-X4: the share of a cell's drainable water a conduit may take in one
+/// routing step — the node exchange's `kFaceShare` (G-X1), for the same
+/// reason: a sink allowed the whole cell in one step oscillates.
+constexpr double kLinkFaceShare = 0.5;
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// T7.4 — the 1D ⇄ aquifer quality seam
+// ---------------------------------------------------------------------------
+
+double SurfaceRouter2D::linkRowConc(const SimulationContext& ctx, int link,
+                                    int s,
+                                    const SubsurfaceTransportState& tr) const {
+    const auto ul = static_cast(link);
+    if (s == tr.age_row) {
+        return (ul < ctx.water_age_state.link_age.size())
+                   ? ctx.water_age_state.link_age[ul] : 0.0;
+    }
+    if (s == tr.temp_row) {
+        return (ul < ctx.heat_state.link_temp.size())
+                   ? ctx.heat_state.link_temp[ul] : 0.0;
+    }
+    // Pollutants only. MSX rows have no 1D link concentration the seam can
+    // read — the same gap the surface's own node seam records, and the
+    // reason an MSX row's mass stays where it is rather than crossing.
+    if (s < tr.n_pollut) {
+        const int np = ctx.n_pollutants();
+        const auto k = ul * static_cast(np) +
+                       static_cast(s);
+        if (np > 0 && k < ctx.links.conc.size()) return ctx.links.conc[k];
+    }
+    return 0.0;
+}
+
+void SurfaceRouter2D::flushAquiferNodeSpecies(SimulationContext& ctx) {
+    auto& gtr = subsurface_.transport();
+    if (!gtr.active() || gtr.node_out_mass.empty()) return;
+    const auto& nv = subsurface_.nodeExchangeVolumes();
+    const int   np = ctx.n_pollutants();
+    const auto  nn = gtr.node_out_mass.size() /
+                     static_cast(gtr.n_species);
+
+    for (std::size_t ni = 0; ni < nn; ++ni) {
+        for (int sp = 0; sp < gtr.n_species; ++sp) {
+            const double m2d = gtr.node_out_mass[static_cast(sp) * nn + ni];
+            if (m2d == 0.0) continue;
+            // Same unit factor the volume takes, so mass/volume stays the
+            // cell's concentration through the conversion.
+            const double m = m2d * options_.flow_2d_to_1d;
+            if (sp < gtr.n_pollut && np > 0) {
+                const auto k = ni * static_cast(np) +
+                               static_cast(sp);
+                // T7.4b (2026-09-21): the QUEUE is the only booking. Adding
+                // `qual_routing_gw_in` here as well counted one transfer in
+                // two inflow rows: the queue is drained into
+                // `coupling_qual_inflow`, which `addCouplingLoads` already
+                // books as `qual_routing_ex_in`. Measured on a deck whose
+                // whole quality budget is aquifer → J1 → outfall, the
+                // duplicate was a 49.7 % continuity error; removing it takes
+                // that deck to ≈ −0.5 %.
+                //
+                // The attribution cost is real and recorded: aquifer→node
+                // mass now reports under the 2D coupling inflow row rather
+                // than "Groundwater Inflow". Giving it its own row means
+                // tagging the queued mass by origin — the queue is shared
+                // with the 2D surface's drain — which is a NodeData and
+                // QualityRouting change, not a router one.
+                if (k < ctx.nodes.coupling_qual_queue.size())
+                    ctx.nodes.coupling_qual_queue[k] += m;
+            } else if (sp == gtr.age_row) {
+                if (ni < ctx.nodes.coupling_age_vol_queue.size())
+                    ctx.nodes.coupling_age_vol_queue[ni] += m;
+            } else if (sp == gtr.temp_row) {
+                if (ni < ctx.nodes.coupling_temp_vol_queue.size())
+                    ctx.nodes.coupling_temp_vol_queue[ni] += m;
+            }
+            // An MSX row has no 1D node inlet for any loader yet — the same
+            // recorded gap the surface seam has. Its mass stays booked out
+            // of the aquifer (`lost_node`) rather than vanishing silently.
+        }
+    }
+
+    // The other direction: a node that RECHARGED the aquifer gave up mass
+    // the 1D quality balance had no row for. The water left through
+    // `coupling_volume` and the node's concentration is unchanged, so the
+    // mass left implicitly with the volume — book it as the exfiltration
+    // loss it is, or the 1D continuity error grows by exactly this.
+    if (np > 0 && gtr.n_pollut > 0) {
+        for (std::size_t ni = 0; ni < nv.size() && ni < nn; ++ni) {
+            if (nv[ni] >= 0.0) continue;                   // + is out of the aquifer
+            const double v_1d = -nv[ni] * options_.flow_2d_to_1d;
+            for (int sp = 0; sp < gtr.n_pollut; ++sp) {
+                const auto k = ni * static_cast(np) +
+                               static_cast(sp);
+                if (k >= ctx.nodes.conc.size()) continue;
+                const double m = v_1d * ctx.nodes.conc[k];
+                if (m != 0.0 &&
+                    static_cast(sp) < ctx.mass_balance.qual_routing_seep.size())
+                    ctx.mass_balance.qual_routing_seep[static_cast(sp)] += m;
+            }
+        }
+    }
+
+    std::fill(gtr.node_out_mass.begin(), gtr.node_out_mass.end(), 0.0);
+}
+
+void SurfaceRouter2D::publishLinkCoupling(SimulationContext& ctx) {
+    if (aquifer_link_shares_.empty() || !subsurface_.active()) return;
+    auto& CD = ctx.link_subtypes.conduits;
+    if (CD.gw_coupled.empty()) return;
+    const auto& gw = subsurface_.state();
+    // [LOSSES] seepage is authored in in/hr (US) or mm/hr (SI) and carried
+    // internally in ft/s — `internal = project / Ucf[RAINFALL]`
+    // (UnitConversion.hpp); `[2D_AQUIFER_LINKS] KC` is authored in the same
+    // column's units, so it takes the same factor. NOTE the whole 1D side is
+    // internally US (ft, ft/s, ft³/s) whatever FLOW_UNITS says, which is why
+    // `len_1d_to_2d` and `vol_1d_to_2d` appear on every quantity crossing
+    // into the metric 2D module.
+    const int usz = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    const double k_ucf = ucf::Ucf[ucf::RAINFALL][usz];
+    const double l12 = options_.len_1d_to_2d;        // project length → m
+    if (!(l12 > 0.0)) return;
+
+    for (const int j : aquifer_link_ids_) {
+        const auto uj = static_cast(j);
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        if (cr < 0) continue;
+        const auto ucr = static_cast(cr);
+
+        // The conduit's mid invert, the datum the signed law measures from
+        // (project length): the mean of its two offset ends, exactly the
+        // elevation `h_link = z_inv + depth` is built on.
+        const auto n1 = static_cast(ctx.links.node1[uj]);
+        const auto n2 = static_cast(ctx.links.node2[uj]);
+        if (n1 >= ctx.nodes.invert_elev.size() || n2 >= ctx.nodes.invert_elev.size())
+            continue;
+        const double z_inv = 0.5 * ((ctx.nodes.invert_elev[n1] + ctx.links.offset1[uj]) +
+                                    (ctx.nodes.invert_elev[n2] + ctx.links.offset2[uj]));
+
+        // Length-weighted table elevation over the cells it crosses, and the
+        // gain budget: the share of each cell's drainable water this step
+        // that the conduit may take, converted to the smallest whole-conduit
+        // rate no cell can over-draw. `kLinkFaceShare` is the node
+        // exchange's `kFaceShare` — half a cell's water in one step, the
+        // same anti-oscillation rule (G-X1).
+        double h_gw_m = 0.0, w_sum = 0.0, gain_max_2d = 1.0e30;
+        for (const auto& sh : aquifer_link_shares_) {
+            if (sh.link != j) continue;
+            const auto c = static_cast(sh.cell);
+            h_gw_m += sh.weight * (gw.z_bed[c] + gw.hg[c]);
+            w_sum  += sh.weight;
+            const double Sy = std::max(gw.theta_s[c] - gw.theta_r[c], 1.0e-3);
+            const double avail = gw.hg[c] * Sy * gw.area[c];       // m³
+            // What is LEFT of this cell's share: `lacc` holds every volume
+            // booked since its last firing (negative while the conduit
+            // draws), and the cell may fire many routing steps from now.
+            // Sizing each step against the frozen `hg` alone let a conduit
+            // take half the cell EVERY step and drive it past empty (the
+            // aquifer then had no channel to refund through, and created
+            // the water instead) — the node exchange's per-batch budget,
+            // here expressed with the accumulator itself (G-X1 rule 2).
+            const double left = kLinkFaceShare * avail + gw.lacc[c];
+            if (sh.weight > 0.0)
+                gain_max_2d = std::min(gain_max_2d,
+                                       std::max(left, 0.0) / sh.weight);
+        }
+        if (w_sum <= 0.0) continue;
+        h_gw_m /= w_sum;                       // the covered length's mean
+
+        const double dt_step = std::max(ctx.options.routing_step, 1.0e-6);
+        const auto* row = [&]() -> const GwLinkRow* {
+            for (const auto& r : aquifer_cfg_.link_rows)
+                if (r.link == j) return &r;
+            return nullptr;
+        }();
+
+        CD.gw_coupled[ucr]  = 1;
+        CD.gw_head_rel[ucr] = h_gw_m / l12 - z_inv;
+        CD.gw_kc[ucr] = (row != nullptr && row->Kc > 0.0) ? row->Kc / k_ucf
+                                                          : CD.seep_rate[ucr];
+        // The characteristic path: the authored bed thickness, or the
+        // conduit's own full depth — which is what makes a FULL pipe over a
+        // table at its invert seep exactly the legacy rate.
+        double d_c = (row != nullptr && row->dC > 0.0) ? row->dC
+                                                       : ctx.links.xsect_y_full[uj];
+        if (!(d_c > 0.0)) d_c = 1.0;
+        CD.gw_dc[ucr] = d_c;
+        // …per barrel, in the 1D's own volume units.
+        const int barrels = std::max(CD.barrels[ucr], 1);
+        CD.gw_gain_max[ucr] =
+            gain_max_2d / (dt_step * options_.vol_1d_to_2d * barrels);
+    }
+}
+
+
 void SurfaceRouter2D::advancePostRouting(SimulationContext& ctx, double routing_dt,
                                           double t) {
     if (!active_) return;
@@ -933,6 +2027,50 @@ void SurfaceRouter2D::advancePostRouting(SimulationContext& ctx, double routing_
     // queue spread (uniform rate over the batch span).
     pending_dt_ += routing_dt;
     last_t_ = t;
+    // G-X3 (2026-09-19): this routing step's conduit seepage, exactly as
+    // updateRoutingMassBalance books it into `routing_seep_loss` (the same
+    // rate × barrels × dt, read after the same DW step), delivered to the
+    // aquifer cells the conduit crosses by its length shares. One-way: the
+    // 1D keeps booking the loss; the aquifer's `led_link` is where it lands.
+    if (!aquifer_link_shares_.empty() && subsurface_.active()) {
+        const auto& CD = ctx.link_subtypes.conduits;
+        // G-X4: TWO_WAY makes the rate SIGNED, so a gaining reach books a
+        // withdrawal (a negative volume) into the same accumulator. The
+        // aquifer can afford it: `gw_gain_max`, frozen before the step, is
+        // what the 1D was allowed to ask for.
+        const bool two_way =
+            subsurface_.options().link_seepage == GwLinkMode::TWO_WAY;
+        for (const auto& sh : aquifer_link_shares_) {
+            const int cr = ctx.link_subtypes.conduit_row(sh.link);
+            if (cr < 0) continue;
+            const auto ucr = static_cast(cr);
+            const double rate = CD.seep_loss_rate[ucr];
+            if (rate == 0.0 || (!two_way && rate < 0.0)) continue;
+            const int barrels = std::max(CD.barrels[ucr], 1);
+            const double vol_2d =
+                rate * barrels * routing_dt * options_.vol_1d_to_2d * sh.weight;
+            subsurface_.bookLinkSeepage(sh.cell, vol_2d);
+            // T7.4: …and its quality, for a LEAKING conduit only. The 1D
+            // quality solver already debits this mass as the conduit's
+            // exfiltration loss (`qual_routing_seep`), so handing it over
+            // here completes a transfer that was previously a
+            // disappearance. A GAINING conduit is the other direction and
+            // has no 1D receiver yet (see the T7.4 handoff): its water
+            // arrives in the pipe without the aquifer's quality.
+            if (rate > 0.0 && subsurface_.transport().active()) {
+                const auto& gtr = subsurface_.transport();
+                const double v_1d = rate * barrels * routing_dt * sh.weight;
+                for (int sp = 0; sp < gtr.n_species; ++sp) {
+                    const double c = linkRowConc(ctx, sh.link, sp, gtr);
+                    if (c != 0.0)
+                        subsurface_.bookLinkSeepageMass(sh.cell, sp, v_1d * c);
+                }
+            }
+        }
+        // …and freeze the aquifer's side for the NEXT routing step, now that
+        // this step's exchange has been handed over.
+        if (two_way) publishLinkCoupling(ctx);
+    }
     // OPENSWMM_2D_SYNC_SPAN (seconds): experimental override of the sync-batch
     // span for the decoupling-viability study — bypasses the [2D_OPTIONS]
     // COUPLING_SYNC policy and the 60 s ceiling. Unset/0 = normal policy.
@@ -963,11 +2101,8 @@ void SurfaceRouter2D::advancePostRouting(SimulationContext& ctx, double routing_
 }
 
 
-void SurfaceRouter2D::prepareOneShotForcing(SimulationContext& ctx) {
+void SurfaceRouter2D::flushPendingBatch(SimulationContext& ctx) {
     if (!active_) return;
-
-    // Flush the partial sync batch so the one-shot forcing applies to future
-    // time only; the next batch picks up the new prescription.
     if (pending_dt_ > 0.0) {
         const double span = pending_dt_;
         pending_dt_ = 0.0;
@@ -976,6 +2111,107 @@ void SurfaceRouter2D::prepareOneShotForcing(SimulationContext& ctx) {
 }
 
 
+double SurfaceRouter2D::reportWeight(double report_ms) const noexcept {
+    if (!report_old_valid_) return 1.0;
+    const double span = report_window_new_ms_ - report_window_old_ms_;
+    if (span <= 0.0) return 1.0;
+    double f = (report_ms - report_window_old_ms_) / span;
+    if (f < 0.0) f = 0.0;
+    if (f > 1.0) f = 1.0;
+    return f;
+}
+
+
+void SurfaceRouter2D::prepareOneShotForcing(SimulationContext& ctx) {
+    if (!active_) return;
+
+    // Flush the partial sync batch so the one-shot forcing applies to future
+    // time only; the next batch picks up the new prescription.
+    flushPendingBatch(ctx);
+}
+
+
+void SurfaceRouter2D::publishNodeRows(const SimulationContext& ctx) {
+    auto& tr = state_.transport;
+    const auto ns = static_cast(tr.n_species);
+    if (!tr.active() || node_row_conc_.size() != ns * static_cast(ctx.n_nodes()))
+        return;
+    const auto np = static_cast(tr.n_pollut);
+    const auto nm = static_cast(tr.n_msx);
+    const auto& conc = ctx.nodes.conc;              // [node * np + p]
+    const auto& msx  = ctx.reactions.msx_node_conc;  // [node * nm_all + m] (LEGACY R4b)
+    const auto nm_all = static_cast(ctx.reactions.n_species());
+    for (int n = 0; n < ctx.n_nodes(); ++n) {
+        const auto un = static_cast(n);
+        double* row = &node_row_conc_[un * ns];
+        for (std::size_t p = 0; p < np; ++p)
+            row[p] = ((un + 1) * np <= conc.size()) ? conc[un * np + p] : 0.0;
+        for (std::size_t m = 0; m < nm; ++m)
+            row[np + m] = ((un + 1) * nm_all <= msx.size()) ? msx[un * nm_all + m] : 0.0;
+        if (tr.age_row >= 0)
+            row[static_cast(tr.age_row)] =
+                (un < ctx.water_age_state.node_age.size())
+                    ? ctx.water_age_state.node_age[un] : 0.0;
+        if (tr.temp_row >= 0)
+            row[static_cast(tr.temp_row)] =
+                (un < ctx.heat_state.node_temp.size())
+                    ? ctx.heat_state.node_temp[un] : 0.0;
+    }
+}
+
+void SurfaceRouter2D::applyAgingAndReactions(SimulationContext& ctx, double dt) {
+    auto& tr = state_.transport;
+    if (!tr.active() || !(dt > 0.0)) return;
+    const auto nt = static_cast(tr.n_cells);
+
+    // A1a on the surface: d(age)/dt = 1, exactly — the age row is an
+    // age-VOLUME, so += dt·V advances the mean age of every cell's water by
+    // dt at constant volume. Dry cells hold ~0 volume and stay put. Lie-split
+    // after the advance like the ARD engine's aging stage.
+    if (tr.age_row >= 0) {
+        const auto ar = static_cast(tr.age_row);
+        for (std::size_t c = 0; c < nt; ++c)
+            tr.cell_mass[ar * nt + c] += dt * state_.volume[c];
+    }
+
+    // E4/S4 reaction stage, reusing reactArdStage on a per-cell CONCENTRATION
+    // view (mass / volume) of the WET cells: pollutant kdecay (exact
+    // exponential, booked to qual_routing_reacted in 1D mass units through
+    // cell_a = V·f, cell_dx = 1) and MSX pipe-scope integration with the
+    // cell's own temperature row. No node stores here (n_nodes = 0). Dry
+    // cells are skipped: no meaningful concentration, negligible mass.
+    const bool any_decay = [&] {
+        for (int p = 0; p < tr.n_pollut; ++p)
+            if (ctx.pollutants.k_decay[static_cast(p)] != 0.0) return true;
+        return false;
+    }();
+    if (!any_decay && tr.n_msx == 0) return;
+    const auto ns = static_cast(tr.n_species);
+    const double dry_h = options_.dry_depth;
+    react_phi_.assign(ns * nt, 0.0);
+    react_a_.assign(nt, 0.0);
+    react_dx_.assign(nt, 1.0);
+    for (std::size_t c = 0; c < nt; ++c) {
+        const double v = state_.volume[c];
+        if (!(v > dry_h * mesh_.tri_area[c])) continue;
+        react_a_[c] = v * options_.flow_2d_to_1d;   // 1D volume units
+        for (std::size_t s = 0; s < ns; ++s)
+            react_phi_[s * nt + c] = tr.cell_mass[s * nt + c] / v;
+    }
+    transport::reactArdStage(ctx, dt, react_phi_.data(), react_a_.data(),
+                             react_dx_.data(), static_cast(nt),
+                             /*node_mass*/ nullptr, /*node_vol*/ nullptr,
+                             /*n_nodes*/ 0, tr.n_pollut,
+                             static_cast(ns), 0.0, tr.temp_row);
+    for (std::size_t c = 0; c < nt; ++c) {
+        if (react_a_[c] == 0.0) continue;   // dry: untouched
+        const double v = state_.volume[c];
+        const auto n_react = static_cast(tr.n_pollut + tr.n_msx);
+        for (std::size_t s = 0; s < n_react; ++s)   // age/temp rows do not react
+            tr.cell_mass[s * nt + c] = react_phi_[s * nt + c] * v;
+    }
+}
+
 void SurfaceRouter2D::resetWindowAccumulators() {
     std::fill(window_outfall_accum_.begin(), window_outfall_accum_.end(), 0.0);
     // Withdrawal budget = the water each cell actually holds right now (the
@@ -1026,6 +2262,20 @@ void SurfaceRouter2D::finalize(SimulationContext& ctx) {
             "coupling and the 2D continuity block.", outfall_clamp_windows_);
         ctx.warnings.push_back(buf);
     }
+    // S2 telemetry: a face whose dispersive exchange was capped is a face
+    // where D·dt/d² exceeded the explicit limit — the physics stayed bounded
+    // but the dispersion RATE was degraded there. Surfaced as a warning so a
+    // modeller sees it without instrumenting the state.
+    if (state_.transport.dispersion_limiter_binds > 0) {
+        char buf[256];
+        std::snprintf(buf, sizeof(buf),
+            "WARNING: 2D dispersion exchange was limited on %ld face-firing(s) "
+            "(D·dt/dx² above the explicit limit); the dispersion rate is "
+            "under-resolved at the marcher's time step there. Reduce "
+            "DISPERSION or MAX_TIMESTEP, or refine the mesh.",
+            state_.transport.dispersion_limiter_binds);
+        ctx.warnings.push_back(buf);
+    }
     active_ = false;
 }
 
@@ -1053,34 +2303,79 @@ double SurfaceRouter2D::totalExchangeFlow() const {
 
 
 void SurfaceRouter2D::updateRainfall(SimulationContext& ctx) {
+    const auto n_gages = static_cast(std::max(ctx.n_gages(), 0));
+    const std::vector& rates =
+        gage_window_rate_.size() == n_gages ? gage_window_rate_ : ctx.gages.rainfall;
+    rain_gage_last_.assign(rates.begin(), rates.begin() + static_cast(n_gages));
+    gageRatesToCells(ctx, rain_gage_last_, state_.rainfall);
+}
+
+void SurfaceRouter2D::gageRatesToCells(const SimulationContext& ctx,
+                                       const std::vector& rates,
+                                       std::vector& out) const {
     const int n_gages = ctx.n_gages();
+    out.resize(static_cast(mesh_.n_triangles()));
 
     if (n_gages <= 0 || options_.rainfall_mode == RainfallMode::NONE) {
-        std::fill(state_.rainfall.begin(), state_.rainfall.end(), 0.0);
+        std::fill(out.begin(), out.end(), 0.0);
         return;
     }
 
-    // Convert every gage's current rainfall (user units, in/hr or mm/hr) to the
+    // Convert every gage's rainfall (user units, in/hr or mm/hr) to the
     // solver's SI m/s. The conversion is linear, so interpolating the converted
     // values is identical to interpolating then converting.
     const double to_ms =
         (ucf::getUnitSystem(static_cast(ctx.options.flow_units)) == 0)
             ? (0.0254 / 3600.0)   // US: in/hr → m/s
             : (0.001  / 3600.0);  // SI: mm/hr → m/s
-    rain_si_.assign(static_cast(n_gages), 0.0);
+    std::vector rain_si(static_cast(n_gages), 0.0);
     for (int g = 0; g < n_gages; ++g)
-        rain_si_[static_cast(g)] = ctx.gages.rainfall[g] * to_ms;
+        rain_si[static_cast(g)] = rates[static_cast(g)] * to_ms;
 
-    if (options_.rainfall_mode == RainfallMode::NATURAL_NEIGHBOUR && interp_.ready()) {
+    if ((options_.rainfall_mode == RainfallMode::NATURAL_NEIGHBOUR ||
+         options_.rainfall_mode == RainfallMode::NEAREST_NEIGHBOUR) && interp_.ready()) {
         // Natural-neighbour (Laplace) interpolation inside the gage hull, IDW
         // outside — applied as the precomputed per-cell sparse weighted sum.
-        interp_.apply(rain_si_, state_.rainfall);
+        interp_.apply(rain_si, out);
     } else {
         // SYSTEM mode (or no located gages): uniform = mean of all gages.
         double mean = 0.0;
-        for (double r : rain_si_) mean += r;
+        for (double r : rain_si) mean += r;
         mean /= static_cast(n_gages);
-        std::fill(state_.rainfall.begin(), state_.rainfall.end(), mean);
+        std::fill(out.begin(), out.end(), mean);
+    }
+}
+
+void SurfaceRouter2D::bookGageRates(const SimulationContext& ctx, double runoff_start_s) {
+    const auto n_gages = static_cast(std::max(ctx.n_gages(), 0));
+    if (gage_rate_.size() != n_gages) {
+        gage_rate_.assign(n_gages, 0.0);
+        gage_cum_.assign(n_gages, 0.0);
+        gage_window_depth_.assign(n_gages, 0.0);
+        gage_report_depth_.assign(n_gages, 0.0);
+        gage_since_ = 0.0;
+    }
+    const double report_s = ctx.next_report_ms / 1000.0;
+    if (gage_since_ <= report_s && runoff_start_s > report_s)
+        for (std::size_t g = 0; g < n_gages; ++g)
+            gage_report_depth_[g] = gage_cum_[g] + gage_rate_[g] * (report_s - gage_since_);
+    for (std::size_t g = 0; g < n_gages; ++g) {
+        gage_cum_[g] += gage_rate_[g] * std::max(0.0, runoff_start_s - gage_since_);
+        gage_rate_[g] = ctx.gages.rainfall[g];
+    }
+    gage_since_ = runoff_start_s;
+}
+
+void SurfaceRouter2D::reportRainfall(const SimulationContext& ctx, double report_date,
+                                     std::vector& out) const {
+    const int n_gages = ctx.n_gages();
+    std::vector rates(static_cast(std::max(n_gages, 0)), 0.0);
+    for (int g = 0; g < n_gages; ++g)
+        rates[static_cast(g)] = gage::getReportRainfallFromSeries(ctx, g, report_date);
+    gageRatesToCells(ctx, rates, out);
+    for (std::size_t i = 0; i < out.size() && i < state_.rainfall_forced.size(); ++i) {
+        if (state_.rainfall_forced[i] == 1)      out[i] = state_.rainfall_force_val[i];
+        else if (state_.rainfall_forced[i] == 2) out[i] += state_.rainfall_force_val[i];
     }
 }
 
@@ -1089,6 +2384,19 @@ void SurfaceRouter2D::resolveBoundaryValues(SimulationContext& ctx, double t) {
     const int ne = boundary_.size();
     if (ne == 0) return;
 
+    // Compact the non-WALL slots once. A WALL slot resolves to nothing and is
+    // ledgered as nothing, but both passes used to switch over all 3*n_tri
+    // slots every routing step to find the perimeter-sized handful that are
+    // not WALL.
+    if (bc_nonwall_dirty_) {
+        bc_nonwall_dirty_ = false;
+        bc_nonwall_slots_.clear();
+        for (int idx = 0; idx < ne; ++idx)
+            if (static_cast(boundary_.edge_bc_type[idx])
+                    != BoundaryType::WALL)
+                bc_nonwall_slots_.push_back(idx);
+    }
+
     // One-shot: resolve deferred timeseries / curve names to table indices.
     // ctx.tables is only populated post-parse, so this can't happen at parse
     // time; -2 = "name pending", -1 = not found (then treated as constant).
@@ -1117,14 +2425,14 @@ void SurfaceRouter2D::resolveBoundaryValues(SimulationContext& ctx, double t) {
     const double abs_t = datetime::addSeconds(ctx.options.start_date, t);
 
     const int n_tables = static_cast(ctx.tables.tables.size());
-    for (int idx = 0; idx < ne; ++idx) {
+    for (const int idx : bc_nonwall_slots_) {
         switch (static_cast(boundary_.edge_bc_type[idx])) {
             case BoundaryType::SPECIFIED_STAGE: {
                 const int ts = boundary_.edge_bc_tseries[idx];
                 if (ts >= 0 && ts < n_tables)
-                    // Stage values are authored in project display units
-                    // (like the constant form); scale onto the SI datum.
-                    boundary_.edge_bc_head[idx] = bc_stage_scale_ *
+                    // Series values are authored in project display units
+                    // ([TIMESERIES] is 1D data); scale onto the SI datum.
+                    boundary_.edge_bc_head[idx] = bc_stage_ts_scale_ *
                         table_lookup_cursor(ctx.tables.tables[ts], abs_t);
                 break;  // else constant: edge_bc_head already holds the value
             }
@@ -1147,10 +2455,10 @@ void SurfaceRouter2D::resolveBoundaryValues(SimulationContext& ctx, double t) {
                     // metre of edge — so the SI head converts back to display
                     // for the query and the result scales to m³/s/m,
                     // consistent with SPECIFIED_FLOW.
-                    const int i = idx / 3;
+                    const int i = MeshData::slot_cell(idx);
                     boundary_.edge_bc_flow[idx] = bc_flow_scale_ *
                         table_lookupEx(ctx.tables.tables[cv],
-                                       state_.head[i] / bc_stage_scale_);
+                                       state_.head[i] / bc_stage_ts_scale_);
                 }
                 break;
             }
@@ -1164,11 +2472,58 @@ void SurfaceRouter2D::accumulateMassBalance(SimulationContext& ctx, double dt) {
     auto& mb = ctx.mass_balance_2d;
     int nt = mesh_.n_triangles();
 
-    // Rainfall inflow (m³): rainfall is m/s after forcings are applied.
-    double rain_vol = 0.0;
+    // Rain / evaporation / infiltration / storage in ONE pass over the cells.
+    // Each accumulator still sums its own term over ascending i, so every
+    // total is bit-identical to the four separate passes this replaces; only
+    // the memory traffic (four full sweeps of the same arrays per routing
+    // step) is gone.
+    const bool do_infil = infil_.active();
+    const bool track_cum =
+        do_infil && infil_cum_applied_.size() == static_cast(nt);
+    double rain_vol = 0.0, evap_vol = 0.0, infil_vol = 0.0, storage = 0.0;
+    const bool route_aq =
+        do_infil && cell_subcatch_.size() == static_cast(nt) &&
+        !subcatch_recharge_.empty();
     for (int i = 0; i < nt; ++i) {
-        rain_vol += state_.rainfall[i] * mesh_.tri_area[i];
+        const auto ui = static_cast(i);
+        const double area = mesh_.tri_area[ui];
+        rain_vol += state_.rainfall[ui] * area;
+        rain_cum_[ui] += state_.rainfall[ui] * area * dt;
+        evap_vol += evapSink(state_.evap_rate[ui], state_.depth[ui],
+                             options_.dry_depth) * area;
+        if (do_infil) {
+            // APPLIED depth (m) the marcher actually removed since the last
+            // read — not a re-derivation at the accepted end-of-step depth.
+            // Consumed and zeroed here, so this must run exactly once per
+            // routing step.
+            const double applied = state_.infil_applied[ui];
+            state_.infil_applied[ui] = 0.0;
+            infil_vol += applied * area;
+            if (track_cum) infil_cum_applied_[ui] += applied;
+            // U3: the SUBCATCH_AQUIFER share is booked to its subcatchment
+            // here, from the same applied depth, so the recharge and the
+            // 2D ledger can never disagree.
+            if (route_aq && cell_subcatch_[ui] >= 0) {
+                const auto us = static_cast(cell_subcatch_[ui]);
+                if (us < subcatch_recharge_.size()) {
+                    subcatch_recharge_[us] += applied * area;
+                }
+            }
+        }
+        // C1: signed per-cell coupling volume (m³), drained on the SAME
+        // once-per-routing-step pass as infil_applied so the two series share
+        // a cadence and can be compared. Positive = the cell received from
+        // the node; negative = the node abstracted from the cell. Kept
+        // per-cell and signed because the domain totals are two unsigned
+        // accumulators that cancel a flip-flopping point to nothing.
+        if (coupling_cum_applied_.size() == static_cast(nt)) {
+            coupling_cum_applied_[ui] += state_.coupling_applied[ui];
+            state_.coupling_applied[ui] = 0.0;
+        }
+        storage += state_.volume[ui];
     }
+
+    // Rainfall inflow (m³): rainfall is m/s after forcings are applied.
     mb.rainfall_in += rain_vol * dt;
 
     // Evaporation loss (m³): the depth-limited sink assembleRHS integrates,
@@ -1177,21 +2532,69 @@ void SurfaceRouter2D::accumulateMassBalance(SimulationContext& ctx, double dt) {
     // rainfall term's treatment). Accumulated into the 2D mass-balance struct
     // so the continuity error and reported totals close natively; the 2D
     // state mirror (evap_loss_total) is retained for back-compatibility.
-    double evap_vol = 0.0;
-    for (int i = 0; i < nt; ++i) {
-        evap_vol += evapSink(state_.evap_rate[i], state_.depth[i],
-                             options_.dry_depth) * mesh_.tri_area[i];
-    }
     mb.evap_out += evap_vol * dt;
     state_.evap_loss_total += evap_vol * dt;
 
+    // Infiltration loss (m³) — plan §5.5.2 site 5 / §5.5.4. Destination is
+    // LOST in this release (D-I4), so it is a true exit from the modelled
+    // system. Skipped entirely when no [2D_INFILTRATION*] rows resolved.
+    //
+    // Unlike the rainfall and evaporation terms above, this is NOT re-derived
+    // from the accepted end-of-step state: it is the volume the marcher
+    // actually removed, summed as it was removed (state_.infil_applied, above).
+    // Re-deriving infilSink() at the end-of-step depth and scaling by the full
+    // routing dt is only first-order, and it under-books on exactly the cells
+    // that matter — a cell that dries mid-step is sunk at the higher
+    // early-step rate but re-derived at the ramped end-of-step rate, and the
+    // lazy tier integrates a stale depth across an entire sync interval. On the
+    // G3 rain-on-grid gate that left 0.0117 m³ of the 3.775 m³ budget
+    // unaccounted: storage fell by more than the ledger booked.
+    //
+    // The per-cell APPLIED cumulative depth (m) comes from the SAME array in
+    // the same pass, which is what keeps
+    // sum(infil_cum_applied_[i] * tri_area[i]) == mb.infil_out true by
+    // construction. Infil2D::cumulative() cannot serve here: it integrates the
+    // unramped capacity the kernel offered, which exceeds the applied loss
+    // whenever a cell is drying.
+    if (do_infil) mb.infil_out += infil_vol;
+    // U3 (track I-b) / G1-c item 1 (2026-09-19): the aquifer-bound share is a
+    // transfer to the 1D groundwater. It is booked to `infil_to_aquifer` when
+    // the runoff step DELIVERS it (SWMMEngine, beside gw_infil_2d_recharge),
+    // not here when the marcher applied it: the two ledgers then sum the same
+    // volumes and cannot disagree by the routing steps that sit between one
+    // runoff drain and the next — the one-step lag the U3 gate measured as a
+    // 3.6 % shortfall on a 30-minute run. What is booked here is the volume
+    // still in flight (applied, not yet delivered), an assignment.
+    if (route_aq) {
+        double pending = 0.0;
+        for (const double v : subcatch_recharge_) pending += v;
+        mb.infil_aquifer_pending = pending;
+    }
+
+    // G1: and the reverse direction. The two-zone kernel books saturation
+    // excess into xacc_to_surface and the marcher's cell loop drains it into
+    // the surface as a source, so the volume the SURFACE has actually taken
+    // is everything the kernel ever handed over, less whatever is still
+    // waiting to be picked up. Cumulative, not incremental — led_dunne is
+    // itself cumulative — so this is an assignment.
+    //
+    // Deriving it here rather than accumulating inside fireCellsImpl is what
+    // keeps the hot parallel cell loop free of a shared reduction; the sum is
+    // one pass over a vector that only exists when an aquifer resolved.
+    if (subsurface_.active()) {
+        const auto& gws = subsurface_.state();
+        double pending = 0.0;
+        for (const double v : gws.xacc_to_surface) pending += v;
+        mb.aquifer_in = gws.led_dunne - pending;
+    }
+
     // Coupling and outfall exchange (m³, SI-native, already capped/clamped —
     // exactly what the 2D domain was asked to move). Outfall sign: + = pipe
     // discharge into 2D (source), − = withdrawal, from the per-batch
     // accumulator. Junction exchange: the marcher booked the batch's per-node
     // total into nodes.coupling_volume (before the queue move) — read it with
     // a per-node dedupe. Sign: + = 2D→1D drain (out of 2D), − = 1D→2D spill.
-    std::unordered_set seen;
+    mb_seen_nodes_.clear();
     for (std::size_t k = 0; k < coupling_points_.size(); ++k) {
         const auto& cp = coupling_points_[k];
         if (cp.is_outfall) {
@@ -1199,7 +2602,7 @@ void SurfaceRouter2D::accumulateMassBalance(SimulationContext& ctx, double dt) {
             if (v > 0.0) mb.outfall_in  += v;
             else         mb.outfall_out += -v;
         } else {
-            if (!seen.insert(cp.node_idx).second) continue;
+            if (!mb_seen_nodes_.insert(cp.node_idx).second) continue;
             const double vol = ctx.nodes.coupling_volume[
                 static_cast(cp.node_idx)] * options_.vol_1d_to_2d;
             if (vol > 0.0) mb.coupling_2d_to_1d_out += vol;
@@ -1210,14 +2613,16 @@ void SurfaceRouter2D::accumulateMassBalance(SimulationContext& ctx, double dt) {
     // Boundary exchange (outward-positive cumulative, m³). Reads 0 until the
     // non-Wall BC flux integration lands, but the term is wired now.
     double cur_bnd = 0.0;
-    for (double f : boundary_.edge_bc_cum_flux) cur_bnd += f;
+    for (const int idx : bc_nonwall_slots_)
+        cur_bnd += boundary_.edge_bc_cum_flux[idx];
     double dbnd = cur_bnd - prev_boundary_cum_;
     prev_boundary_cum_ = cur_bnd;
     if (dbnd > 0.0) mb.boundary_out += dbnd;
     else            mb.boundary_in  += -dbnd;
 
-    // Latest storage (m³) — overwrite so the value at simulation end is final.
-    mb.final_storage = totalVolume();
+    // Latest storage (m³) — overwrite so the value at simulation end is final
+    // (summed in the fused pass above, same ascending order as totalVolume()).
+    mb.final_storage = storage;
 }
 
 
diff --git a/src/engine/2d/SurfaceRouter2D.hpp b/src/engine/2d/SurfaceRouter2D.hpp
index f88349e6d..b5c62d057 100644
--- a/src/engine/2d/SurfaceRouter2D.hpp
+++ b/src/engine/2d/SurfaceRouter2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SurfaceRouter2D.hpp
  * @brief Top-level orchestrator for the optional 2D surface routing module.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SURFACE_ROUTER_HPP
@@ -28,10 +44,16 @@
 #include "data/BoundaryData.hpp"
 #include "data/PendingRows2D.hpp"
 #include "coupling/NodeCoupling.hpp"
+#include "gw/GwTransportData.hpp"
+#include "quality/SurfaceQuality2D.hpp"   // S7
+#include "subsurface/SubsurfaceSolver.hpp"   // G1: the two-zone GW kernel
+#include "infil/Infil2D.hpp"
 #include "mesh/RainfallInterpolator.hpp"
 
 #include 
 #include 
+#include 
+#include 
 #include 
 #ifdef OPENSWMM_HAS_2D
 #include "solver/ISurfaceSolver.hpp"
@@ -113,6 +135,55 @@ class SurfaceRouter2D {
      */
     void prepareOneShotForcing(SimulationContext& ctx);
 
+    /**
+     * @brief Flush the pending (partial) sync batch, if any.
+     *
+     * Closes the accumulated routing span with one co-advance so the 2D
+     * clock reaches the current routing time. A no-op under default
+     * per-routing-step coupling (the batch closes every step). Used before
+     * a report snapshot — so the report-time blend brackets the report
+     * instant — and before a one-shot forcing.
+     */
+    void flushPendingBatch(SimulationContext& ctx);
+
+    /// Report-time interpolation weight for the 2D snapshot blend:
+    /// f = (report_ms − window_old_ms)/(window_new_ms − window_old_ms),
+    /// clamped to [0,1]; returns 1.0 (pure current state) when no batch has
+    /// crossed a report instant yet. Unlike the 1D weight there is no legacy
+    /// bit pattern to reproduce, so the clamp simply absorbs ulp-level clock
+    /// skew between the router's and the engine's ms accumulators.
+    double reportWeight(double report_ms) const noexcept;
+
+    /// Book the gage rates a runoff step starting at @p runoff_start_s
+    /// (seconds since the run start) takes, after the monthly adjustment.
+    /// The 2D integrates these piecewise-constant rates over each of its own
+    /// windows, so a cell receives exactly the gage depth the subcatchments
+    /// do over the same interval.
+    void bookGageRates(const SimulationContext& ctx, double runoff_start_s);
+
+    /// Per-cell rainfall (m/s) as the .out reports subcatchment rainfall: the
+    /// source gage rate at @p report_date, independent of runoff cursor, mapped
+    /// through RAINFALL_MODE, with the per-cell rainfall forcings applied.
+    void reportRainfall(const SimulationContext& ctx, double report_date,
+                        std::vector& out) const;
+
+    /// Rainfall volume (m³) integrated to the report boundary, excluding the
+    /// part of a routing/sync window after that boundary. Runtime totals
+    /// remain available through rainCumulative().
+    const std::vector& reportRainCumulative(double report_ms) const noexcept {
+        return report_rain_ms_ == report_ms ? report_rain_cum_ : rain_cum_;
+    }
+
+    /// Cell depth (m) at the start of the sync batch that crossed the
+    /// current report instant (meaningful when reportWeight() < 1).
+    const std::vector& reportOldDepth() const noexcept {
+        return report_old_depth_;
+    }
+    /// Cell head (m) at the start of that batch.
+    const std::vector& reportOldHead() const noexcept {
+        return report_old_head_;
+    }
+
     /**
      * @brief Finalize the 2D module at simulation end.
      *
@@ -127,6 +198,11 @@ class SurfaceRouter2D {
     /// Check if the 2D module is active.
     bool isActive() const noexcept { return active_; }
 
+    /// Thread-count advisories produced by initialize() (THREADS above the
+    /// machine limits, triangle gate reducing an explicit request). The engine
+    /// forwards them to the report warnings and the host warning callback.
+    const std::vector& threadWarnings() const noexcept { return thread_warnings_; }
+
     /// Windowless-coupling stabilizer: per coupled node, the exchange head
     /// sensitivity G = Σ_points −∂Q/∂h_1d ≥ 0 converted to 1D units (ft³/s per
     /// ft), for the caller to add into the dynamic-wave `sumdqdh` each Picard
@@ -172,6 +248,135 @@ class SurfaceRouter2D {
     /// Access per-edge boundary-condition data (mutable, for forcing/parsing).
     BoundaryData& boundary() noexcept { return boundary_; }
 
+    /// Announce that a boundary slot's TYPE changed (the API BC-type setter),
+    /// so the compact non-WALL slot list the per-step boundary passes walk is
+    /// rebuilt before it is next used.
+    void invalidateBoundaryIndex() noexcept { bc_nonwall_dirty_ = true; }
+
+    /// Bring the render fields (vertex heads, output gradients, vertex render
+    /// depths) up to date with the current solver state if a batch has run
+    /// since they were last computed. The API getters that expose those fields
+    /// call this so a reader arriving between reports is never served a stale
+    /// field; it is a no-op at a report instant, where the refresh already ran.
+    void refreshRenderFieldsIfStale() {
+        if (render_dirty_) refreshRenderFields();
+    }
+
+    /**
+     * @brief Access the per-cell infiltration model (plan §5.5, track I).
+     *
+     * Mutable so SWMMEngine can publish it on `ctx.twod_io.infil` — the
+     * [2D_INFILTRATION*] section handlers and the InpWriter reach it there.
+     * The router owns the object, resolves it against the mesh in
+     * initialize(), and drives its INFIL_STEP cadence in coAdvanceStep().
+     */
+    Infil2D& infil() noexcept { return infil_; }
+    const Infil2D& infil() const noexcept { return infil_; }
+
+    /// U4 (2026-09-07): the `[GW_*]` subsurface-transport authoring rows.
+    /// Reached by the parser, the writer and the C API through
+    /// SimulationContext::twod_io.gw. Authoring-only in this release.
+    GwTransportData&       gwTransport()       noexcept { return gw_; }
+    const GwTransportData& gwTransport() const noexcept { return gw_; }
+    /// S7: cell coverages / buildup / washoff / sweeping (authoring + state).
+    SurfaceQuality2D&       surfaceQuality()       noexcept { return surface_quality_; }
+    const SurfaceQuality2D& surfaceQuality() const noexcept { return surface_quality_; }
+
+    /// G1: the authored `[2D_AQUIFER*]` rows, in the user's own units.
+    /// Reached by the section handlers and the InpWriter through
+    /// `SimulationContext::twod_io.aquifer`.
+    SubsurfaceConfig&       aquiferConfig()       noexcept { return aquifer_cfg_; }
+    const SubsurfaceConfig& aquiferConfig() const noexcept { return aquifer_cfg_; }
+    std::vector& aquiferNodeNames() noexcept {
+        return aquifer_node_names_;
+    }
+    const std::vector& aquiferNodeNames() const noexcept {
+        return aquifer_node_names_;
+    }
+    /// G-X4: the `[2D_AQUIFER_LINKS]` row names, parallel to
+    /// `aquiferConfig().link_rows` — the writer's round-trip key.
+    std::vector& aquiferLinkNames() noexcept {
+        return aquifer_link_names_;
+    }
+    const std::vector& aquiferLinkNames() const noexcept {
+        return aquifer_link_names_;
+    }
+    /// The running kernel. `active()` is false until `[2D_AQUIFER]` resolves.
+    SubsurfaceSolver&       subsurface()       noexcept { return subsurface_; }
+    const SubsurfaceSolver& subsurface() const noexcept { return subsurface_; }
+
+    /**
+     * @brief Ledger-consistent cumulative infiltrated depth per cell (m).
+     *
+     * @details Drains the SAME `SurfaceStateData::infil_applied` accumulator
+     *          that `MassBalance2D::infil_out` books — the depth the marcher
+     *          actually removed, summed as it was removed — so
+     *          `sum(infilCumulative()[i] * tri_area[i]) == infil_out` holds by
+     *          construction. Prefer this over `Infil2D::cumulative()`, which is
+     *          the unramped capacity the kernels offered and therefore exceeds
+     *          the applied loss on drying cells. Empty when no
+     *          `[2D_INFILTRATION*]` model resolved.
+     */
+    /**
+     * @brief U3 (track I-b) — per-subcatchment 2D infiltration recharge
+     *        pending delivery to the legacy aquifer, in m³.
+     *
+     * @details Filled in accumulateMassBalance() for every cell whose
+     *          resolved row says SUBCATCH_AQUIFER and that a subcatchment
+     *          contains. `drainSubcatchRecharge()` hands it to the runoff
+     *          step (which adds it to that subcatchment's infiltration rate
+     *          for GWSolver::execute) and zeroes it, so the accumulator is
+     *          drained exactly once per runoff step. Empty when the
+     *          destination is not in use.
+     */
+    const std::vector& subcatchRecharge() const noexcept {
+        return subcatch_recharge_;
+    }
+    /// Move the pending recharge into @p out (m³ per subcatchment) and zero
+    /// the accumulator. @p out is sized to the accumulator (empty when the
+    /// destination is not in use).
+    void drainSubcatchRecharge(std::vector& out) {
+        out = subcatch_recharge_;
+        std::fill(subcatch_recharge_.begin(), subcatch_recharge_.end(), 0.0);
+    }
+    /// Cell → containing subcatchment index (-1 = none). Empty unless the
+    /// SUBCATCH_AQUIFER destination resolved.
+    const std::vector& cellSubcatchment() const noexcept {
+        return cell_subcatch_;
+    }
+
+    const std::vector& infilCumulative() const noexcept {
+        return infil_cum_applied_;
+    }
+
+    /*!
+     * \brief Signed cumulative coupling exchange per cell (m³).
+     *
+     * \details Positive = water the 1D node delivered INTO this cell (spill,
+     *          submerged-outfall discharge); negative = water the node
+     *          abstracted FROM it (drain). Summing the vector gives
+     *          `coupling_1d_to_2d_in − coupling_2d_to_1d_out`, which is the
+     *          check that ties this series to the domain totals.
+     */
+    const std::vector& couplingCumulative() const noexcept {
+        return coupling_cum_applied_;
+    }
+
+    /**
+     * @brief Ledger-consistent cumulative rainfall volume per cell (m³).
+     *
+     * @details Booked in accumulateMassBalance() from the SAME per-cell
+     *          rainfall term that feeds `MassBalance2D::rainfall_in`, so
+     *          `sum(rainCumulative()[i]) == rainfall_in` holds by construction.
+     *          Sized [n_triangles] from initialize(); zero-filled when no rain.
+     */
+    const std::vector& rainCumulative() const noexcept {
+        return rain_cum_;
+    }
+
+    /// Static rainfall weights built at initialize() (diagnostic inspection).
+    const RainfallInterpolator& rainfallInterpolator() const noexcept { return interp_; }
+
     /**
      * @brief Per-row buffer for `[2D_BOUNDARY_CONDITIONS]` parse output.
      *
@@ -183,6 +388,15 @@ class SurfaceRouter2D {
      * Hoisted to data/PendingRows2D.hpp; alias kept for call sites.
      */
     using PendingBoundaryRow = twoD::PendingBoundaryRow;
+    using PendingInitialQualityRow = twoD::PendingInitialQualityRow;
+    using PendingBoundaryQualityRow = twoD::PendingBoundaryQualityRow;
+    /// S1/S2: raw [2D_INITIAL_QUALITY] rows, resolved at initialize().
+    std::vector& pendingInitialQualityRows() noexcept {
+        return pending_iq_rows_;
+    }
+    std::vector& pendingBoundaryQualityRows() noexcept {
+        return pending_bq_rows_;
+    }
     std::vector& pendingBCRows() noexcept { return pending_bc_rows_; }
     const std::vector& pendingBCRows() const noexcept { return pending_bc_rows_; }
 
@@ -217,10 +431,19 @@ class SurfaceRouter2D {
     double lastSolverStepSize() const {
         return solver_ ? solver_->last_step_size() : 0.0;
     }
+    /// Cumulative marcher statistics (ISurfaceSolver::RunStats): substeps,
+    /// face-kernel evaluations, active-cell fractions and LTS tier occupancy.
+    /// Zeros once the solver has been finalised.
+    ISurfaceSolver::RunStats runStats() const {
+        return solver_ ? solver_->run_stats() : ISurfaceSolver::RunStats{};
+    }
 #else
     long lastSolverSteps() const { return 0; }
     double lastSolverStepSize() const { return 0.0; }
 #endif
+    /// Backend label chosen by SurfaceSolverFactory at initialize()
+    /// ("cpu (explicit marcher)", "omp (…)", …); empty before that.
+    const std::string& backendName() const noexcept { return backend_name_; }
 
 private:
     /// Drain pending [2D_BOUNDARY_CONDITIONS] / [2D_EDGE_CONVEYANCE] rows into
@@ -232,9 +455,65 @@ class SurfaceRouter2D {
     SurfaceStateData state_;
     SolverOptions2D  options_;
     BoundaryData     boundary_;
+    std::vector thread_warnings_;   ///< See threadWarnings().
+    std::string              backend_name_;      ///< See backendName().
+
+    /// §5.5 track I — per-cell infiltration parameters, kernel state and the
+    /// held rates published into state_.infil_rate. Inert (no allocation, no
+    /// per-step work) until a [2D_INFILTRATION*] section resolves a model.
+    Infil2D infil_;
+
+    /// Sim time since the last Infil2D::updateRates call (D-I1 INFIL_STEP
+    /// cadence). Advanced on the routing/co-advance cadence, NEVER per
+    /// marcher substep.
+    double infil_elapsed_ = 0.0;
+
+    /// Per-cell APPLIED cumulative infiltrated depth (m) — see
+    /// infilCumulative(). Filled in accumulateMassBalance() by draining the
+    /// same SurfaceStateData::infil_applied accumulator that feeds
+    /// MassBalance2D::infil_out; empty when no [2D_INFILTRATION*] model
+    /// resolved.
+    std::vector infil_cum_applied_;
+
+    /// C1: SIGNED cumulative coupling exchange volume per cell (m³).
+    /// + = received from the 1D node, − = abstracted by it. Drained from
+    /// SurfaceStateData::coupling_applied on the same once-per-routing-step
+    /// pass as infil_cum_applied_. Always sized once the mesh resolves.
+    std::vector coupling_cum_applied_;
+
+    /// U3 (track I-b): cell → containing subcatchment (-1 = none), resolved
+    /// once at initialize() from the cell centroid and the [Polygons]; and
+    /// the per-subcatchment recharge volume (m³) awaiting delivery.
+    std::vector    cell_subcatch_;
+    std::vector subcatch_recharge_;
+
+    /// U4: subsurface-transport authoring rows (inert until the kernel).
+    GwTransportData gw_;
+    SurfaceQuality2D surface_quality_;   ///< S7
+
+    /// G1: the `[2D_AQUIFER*]` authoring rows (project units, never
+    /// converted in place) and the two-zone kernel that reads them into SI
+    /// state. Both are inert — no allocation, no per-step work — until a
+    /// `[2D_AQUIFER]` row resolves.
+    SubsurfaceConfig         aquifer_cfg_;
+    std::vector aquifer_node_names_;
+    std::vector aquifer_link_names_;   ///< G-X4
+    SubsurfaceSolver         subsurface_;
+    /// G-X3: the (conduit, cell, length share) table `LINK_SEEPAGE AUTO`
+    /// resolved at initialize; empty when nothing seeps over the mesh.
+    std::vector aquifer_link_shares_;
+    /// G-X4: the conduits in `aquifer_link_shares_`, each once, ascending —
+    /// the publisher's loop, so it does not re-scan the share table.
+    std::vector         aquifer_link_ids_;
+
+    /// Per-cell cumulative rainfall volume (m³) — see rainCumulative().
+    /// Filled in accumulateMassBalance() alongside MassBalance2D::rainfall_in.
+    std::vector rain_cum_;
 
     /// V-E3 — parse-time scratch for [2D_BOUNDARY_CONDITIONS] rows.
     std::vector pending_bc_rows_;
+    std::vector pending_iq_rows_;   ///< S1/S2
+    std::vector pending_bq_rows_;  ///< S2
 
     /// §11A — parse-time scratch for [2D_EDGE_CONVEYANCE] rows.
     /// Drained in initialize() into mesh_.edge_conveyance after
@@ -246,9 +525,39 @@ class SurfaceRouter2D {
     /// Stable storage that state_.node_coupling points at; built once in
     /// initialize().
     std::vector node_coupling_points_;
-
-    /// Sim time since the last co-advance output refresh (report-scale cadence).
+    /// S4: published 1D node row values `[node * n_species + s]` (pollutant
+    /// conc, MSX conc, age, temperature), refreshed once per batch by
+    /// publishNodeRows(); state_.node_row_conc points here.
+    std::vector node_row_conc_;
+    void publishNodeRows(const SimulationContext& ctx);
+    /// S4: aging of the age row and the per-cell reaction stage (pollutant
+    /// kdecay + MSX via reactArdStage), Lie-split after each advance.
+    void applyAgingAndReactions(SimulationContext& ctx, double dt);
+    std::vector react_phi_, react_a_, react_dx_;   ///< scratch
+
+    /// Sim time since the last statistics/continuity sample (30 s cadence).
     double co_refresh_elapsed_ = 0.0;
+    /// Sim time since the last RENDER-field refresh (vertex heads, gradients,
+    /// render depths). Those fields have exactly two consumers — the output
+    /// snapshot and the bulk API getters — so they are refreshed on the
+    /// REPORT_STEP grid, and on demand for an API reader that arrives between
+    /// reports (render_dirty_).
+    double co_render_elapsed_ = 0.0;
+    bool   render_dirty_      = false;
+    /// Per-cell free-surface scratch for the render-depth reconstruction,
+    /// held across refreshes so the pass allocates nothing.
+    std::vector render_eta_;
+    /// Flat mesh edge slots (3*i+e) carrying a non-WALL boundary condition.
+    /// The BC TYPE of a slot is fixed once the model is resolved, so the list
+    /// is built once in initialize(); the per-step boundary ledger and the
+    /// per-step TS/rating resolve walk it instead of all 3*n_triangles slots.
+    std::vector bc_nonwall_slots_;
+    /// Set whenever a slot's BC TYPE changes (parse-time drain, API setter);
+    /// bc_nonwall_slots_ is rebuilt on the next resolve.
+    bool bc_nonwall_dirty_ = true;
+    /// Per-node dedupe for the coupling term of the per-batch mass balance;
+    /// a member so the batch does not build and destroy a hash set each time.
+    std::unordered_set mb_seen_nodes_;
     /// Sim time since the last rainfall/forcing refresh (gage-scale cadence).
     double co_forcing_elapsed_ = 0.0;
     bool   co_forcing_first_   = true;
@@ -257,12 +566,43 @@ class SurfaceRouter2D {
     /// mass balance + output refresh. Replaces the whole window state machine
     /// on the marcher path.
     void coAdvanceStep(SimulationContext& ctx, double dt, double t);
+    /// G-X4: freeze the aquifer's side of the conduit exchange (table
+    /// elevation relative to the conduit invert, conductivity, path length
+    /// and the gain budget) into the conduit rows the two loss laws read.
+    void publishLinkCoupling(SimulationContext& ctx);
+    /// T7.4: one species' concentration in a conduit, in 1D units — what a
+    /// leaking pipe's water carries into the aquifer.
+    double linkRowConc(const SimulationContext& ctx, int link, int s,
+                       const SubsurfaceTransportState& tr) const;
+    /// T7.4: hand the aquifer's node-seam mass to the 1D in both
+    /// directions — out through the node's coupling queues, in as the
+    /// exfiltration loss the 1D quality balance never booked.
+    void flushAquiferNodeSpecies(SimulationContext& ctx);
+    /// True when the batch about to run (span @p dt) is the one that closes
+    /// the current output-refresh window — decided BEFORE the advance so the
+    /// continuity snapshot is only taken on batches that will use it.
+    bool refreshDue(const SimulationContext& ctx, double dt) const;
+    /// Recompute the render fields from the current state.
+    void refreshRenderFields();
 
     bool   active_           = false;
     double sim_time_         = 0.0;
     /// Routing time accumulated since the last co-advance sync batch.
     double pending_dt_       = 0.0;
 
+    /// Report-time blend support (the 2D analogue of the 1D old/new report
+    /// interpolation): cell depth/head captured at the START of the sync
+    /// batch that crosses the next report instant, plus that batch's ms
+    /// window [old, new] kept on the same `+= 1000*dt` recurrence as
+    /// ctx.elapsed_ms. fillSurfaceSnapshot blends old→current with
+    /// reportWeight() so the snapshot's depth/head are truthful at the
+    /// report datestamp instead of lagging at the window end.
+    std::vector report_old_depth_;
+    std::vector report_old_head_;
+    double report_window_old_ms_ = 0.0;
+    double report_window_new_ms_ = 0.0;
+    bool   report_old_valid_     = false;
+
     /// OPENSWMM_2D_HEAD_RAMP experiment: per-coupling-point 1D head at the
     /// previous batch (2D metre frame) + that batch's span, for the
     /// batch-over-batch trend slope handed to the marcher.
@@ -298,14 +638,22 @@ class SurfaceRouter2D {
     /// then), not at parse time.
     bool boundary_names_resolved_ = false;
 
-    /// Project-display-units → SI factor for SPECIFIED_STAGE boundary heads
-    /// (0.3048 for US FLOW_UNITS with a non-SI mesh file, else 1.0). Set in
-    /// initialize() alongside the mesh scaling; applied once to constant
-    /// heads after drainPendingRows() and at every TS lookup in
-    /// resolveBoundaryValues(). Also converts the SI head back to display
-    /// units for rating-curve stage-axis queries.
+    /// Mesh-file-units → SI factor for CONSTANT SPECIFIED_STAGE heads
+    /// (0.3048 for US FLOW_UNITS with a non-SI mesh file, else 1.0). Constant
+    /// heads live in the mesh sections and share the mesh's vertical datum
+    /// and units, so they follow the mesh scaling exactly (including the
+    /// `;; UNITS: SI (m)` header). Applied once after drainPendingRows().
     double bc_stage_scale_ = 1.0;
 
+    /// Project-display-units → SI factor for TIME-SERIES / rating-curve
+    /// stage values (0.3048 for US FLOW_UNITS, else 1.0). [TIMESERIES] and
+    /// [CURVES] tables are 1D project data authored in display units
+    /// regardless of how the mesh file is tagged, so this is driven by
+    /// FLOW_UNITS alone (like bc_flow_scale_) — NOT by the mesh header.
+    /// Applied at every lookup in resolveBoundaryValues(); also converts the
+    /// SI head back to display units for rating-curve stage-axis queries.
+    double bc_stage_ts_scale_ = 1.0;
+
     /// Display flow units → m³/s factor for SPECIFIED_FLOW / TS_FLOW /
     /// RATING_CURVE per-metre discharges (from FLOW_UNITS; 1.0 for CMS).
     /// Applied once to constant flows after drainPendingRows() and at every
@@ -322,14 +670,31 @@ class SurfaceRouter2D {
     /// the uniform SYSTEM mean, per options_.rainfall_mode).
     void updateRainfall(SimulationContext& ctx);
 
+    /// Map per-gage rates (user units, in/hr or mm/hr) onto the cells (m/s)
+    /// per options_.rainfall_mode.
+    void gageRatesToCells(const SimulationContext& ctx, const std::vector& rates,
+                          std::vector& out) const;
+
     /// Static per-cell rainfall-interpolation weights. Built once in
     /// initialize() (gage positions are fixed for a run); applied each step in
     /// updateRainfall() for RainfallMode::NATURAL_NEIGHBOUR.
     RainfallInterpolator interp_;
 
-    /// Per-step scratch: each gage's current rainfall converted to m/s, indexed
-    /// by global gage index. Reused across steps to avoid per-step allocation.
-    std::vector rain_si_;
+    /// Gage rainfall (user units) the current cell field was built from. A
+    /// change forces a refresh ahead of the 30 s cadence, so the field never
+    /// lags a gage record by more than the step that crosses it.
+    std::vector rain_gage_last_;
+
+    /// Gage rates booked by bookGageRates (user units), the time they took
+    /// effect (s), the depth each gage delivered before then (rate x s), the
+    /// same depth at the end of the last 2D window, and that window's mean
+    /// rate — what updateRainfall maps onto the cells.
+    std::vector gage_rate_, gage_cum_, gage_window_depth_, gage_window_rate_;
+    double gage_since_ = 0.0;
+    // Preserve the integral at the next report boundary before the runoff
+    // clock moves beyond it. Only one gage row and one cell row are retained.
+    std::vector gage_report_depth_, report_rain_cum_;
+    double report_rain_ms_ = -1.0;
 
     /// Resolve per-step boundary driving values: evaluate SPECIFIED_STAGE /
     /// SPECIFIED_FLOW timeseries at time @p t and RATING_CURVE from the boundary
@@ -340,7 +705,8 @@ class SurfaceRouter2D {
 
     /// Accumulate the global 2D mass-balance terms for one executed step
     /// into ctx.mass_balance_2d (rainfall, coupling, outfall, boundary,
-    /// latest storage) and the evaporation loss into state_.evap_loss_total.
+    /// infiltration, latest storage) and the evaporation loss into
+    /// state_.evap_loss_total.
     /// All terms in the 2D solver's SI internal units (m³).
     void accumulateMassBalance(SimulationContext& ctx, double dt);
 };
diff --git a/src/engine/2d/api/Api2D.cpp b/src/engine/2d/api/Api2D.cpp
index ec2310161..cdbde137e 100644
--- a/src/engine/2d/api/Api2D.cpp
+++ b/src/engine/2d/api/Api2D.cpp
@@ -14,6 +14,7 @@
 #include 
 #include "../../core/SWMMEngine.hpp"
 #include "../mesh/MeshBuilder.hpp"
+#include "../data/Report2DVars.hpp"
 
 #include 
 #include 
@@ -40,10 +41,36 @@
     if ((idx) < 0 || (idx) >= router2d.mesh().n_triangles()) \
         return SWMM_ERR_BADINDEX
 
+/// Local edge index must be < the cell's vertex count (3 or 4).
+#define CHECK_EDGE_IDX(cell, edge, router2d) \
+    do { \
+        if ((edge) < 0 || (edge) >= (router2d).mesh().cell_vertex_count(cell)) \
+            return SWMM_ERR_BADINDEX; \
+    } while (0)
+
 #define CHECK_VERT_IDX(idx, router2d) \
     if ((idx) < 0 || (idx) >= router2d.mesh().n_vertices()) \
         return SWMM_ERR_BADINDEX
 
+namespace {
+
+/// Report a coupling's node index the same way whether the coupling was
+/// authored or set through the API.
+///
+/// The API setters resolve the node name eagerly, but a coupling parsed from
+/// `[2D_VERTEX_NODE_MAP]` / `[2D_TRIANGLE_NODE_MAP]` carries only the NAME
+/// until SurfaceRouter2D::initialize() resolves it — section order means the
+/// node table may not exist yet at parse time. Readers therefore fall back to
+/// a name lookup so both paths agree in the OPENED state; the stored index is
+/// left untouched, and -1 still means genuinely unresolvable.
+int coupledNodeIndex(openswmm::SWMMEngine* eng, int stored,
+                     const std::string& node_name) {
+    if (stored >= 0 || node_name.empty()) return stored;
+    return eng->context().node_names.find(node_name);
+}
+
+}  // namespace
+
 extern "C" {
 
 // ============================================================================
@@ -121,6 +148,20 @@ int swmm_2d_set_vertex_z(SWMM_Engine engine, int idx, double z) {
     return SWMM_OK;
 }
 
+int swmm_2d_set_vertex_z_bulk(SWMM_Engine engine, const double* z, int count) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!z) return SWMM_ERR_BADPARAM;
+
+    auto& m = router2d.mesh();
+    if (count != m.n_vertices()) return SWMM_ERR_BADPARAM;
+
+    std::memcpy(m.vz.data(), z, static_cast(count) * sizeof(double));
+    // One pass over the triangles instead of one pass PER VERTEX.
+    openswmm::twoD::recomputeAllZDependents(m);
+    return SWMM_OK;
+}
+
 int swmm_2d_triangle_get_vertices(SWMM_Engine engine, int idx,
                                     int* v0, int* v1, int* v2) {
     GET_ENGINE(engine);
@@ -129,7 +170,67 @@ int swmm_2d_triangle_get_vertices(SWMM_Engine engine, int idx,
     if (!v0 || !v1 || !v2) return SWMM_ERR_BADPARAM;
 
     auto& m = router2d.mesh();
-    *v0 = m.tri_v0[idx]; *v1 = m.tri_v1[idx]; *v2 = m.tri_v2[idx];
+    // A quad has four vertices — refuse rather than truncate; callers use
+    // swmm_2d_cell_get_vertices for mixed meshes.
+    if (m.cell_vertex_count(idx) != 3) return SWMM_ERR_BADPARAM;
+    *v0 = m.cell_vertex(idx, 0); *v1 = m.cell_vertex(idx, 1); *v2 = m.cell_vertex(idx, 2);
+    return SWMM_OK;
+}
+
+int swmm_2d_cell_count(SWMM_Engine engine, int* count) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = router2d.mesh().n_triangles();
+    return SWMM_OK;
+}
+
+int swmm_2d_quad_count(SWMM_Engine engine, int* count) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = router2d.mesh().n_quads();
+    return SWMM_OK;
+}
+
+int swmm_2d_edge_stride(SWMM_Engine engine, int* stride) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!stride) return SWMM_ERR_BADPARAM;
+    *stride = router2d.mesh().edge_stride();
+    return SWMM_OK;
+}
+
+int swmm_2d_cell_vertex_count(SWMM_Engine engine, int idx, int* nv) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(idx, router2d);
+    if (!nv) return SWMM_ERR_BADPARAM;
+    *nv = router2d.mesh().cell_vertex_count(idx);
+    return SWMM_OK;
+}
+
+int swmm_2d_cell_get_vertices(SWMM_Engine engine, int idx, int* v, int* nv) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(idx, router2d);
+    if (!v || !nv) return SWMM_ERR_BADPARAM;
+    auto& m = router2d.mesh();
+    *nv = m.cell_vertex_count(idx);
+    for (int k = 0; k < openswmm::twoD::kMaxCellVerts; ++k)
+        v[k] = (k < *nv) ? m.cell_vertex(idx, k) : -1;
+    return SWMM_OK;
+}
+
+int swmm_2d_cell_get_neighbours(SWMM_Engine engine, int idx, int* n, int* nv) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(idx, router2d);
+    if (!n || !nv) return SWMM_ERR_BADPARAM;
+    auto& m = router2d.mesh();
+    *nv = m.cell_vertex_count(idx);
+    for (int k = 0; k < openswmm::twoD::kMaxCellVerts; ++k)
+        n[k] = (k < *nv) ? m.cell_neighbour(idx, k) : -2;
     return SWMM_OK;
 }
 
@@ -277,7 +378,8 @@ int swmm_2d_triangle_get_neighbours(SWMM_Engine engine, int idx,
     if (!n0 || !n1 || !n2) return SWMM_ERR_BADPARAM;
 
     auto& m = router2d.mesh();
-    *n0 = m.tri_nbr0[idx]; *n1 = m.tri_nbr1[idx]; *n2 = m.tri_nbr2[idx];
+    if (m.cell_vertex_count(idx) != 3) return SWMM_ERR_BADPARAM;
+    *n0 = m.cell_neighbour(idx, 0); *n1 = m.cell_neighbour(idx, 1); *n2 = m.cell_neighbour(idx, 2);
     return SWMM_OK;
 }
 
@@ -287,13 +389,14 @@ int swmm_2d_triangle_get_neighbours(SWMM_Engine engine, int idx,
 
 int swmm_2d_vertex_coupling_count(SWMM_Engine engine, int* count) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     if (!count) return SWMM_ERR_BADPARAM;
 
     int n = 0;
     auto& m = router2d.mesh();
     for (int i = 0; i < m.n_vertices(); ++i) {
-        if (m.vert_coupled_node[i] >= 0) ++n;
+        if (coupledNodeIndex(eng, m.vert_coupled_node[i],
+                             m.vert_coupled_node_name[i]) >= 0) ++n;
     }
     *count = n;
     return SWMM_OK;
@@ -301,13 +404,14 @@ int swmm_2d_vertex_coupling_count(SWMM_Engine engine, int* count) {
 
 int swmm_2d_triangle_coupling_count(SWMM_Engine engine, int* count) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     if (!count) return SWMM_ERR_BADPARAM;
 
     int n = 0;
     auto& m = router2d.mesh();
     for (int i = 0; i < m.n_triangles(); ++i) {
-        if (m.tri_coupled_node[i] >= 0) ++n;
+        if (coupledNodeIndex(eng, m.tri_coupled_node[i],
+                             m.tri_coupled_node_name[i]) >= 0) ++n;
     }
     *count = n;
     return SWMM_OK;
@@ -316,22 +420,26 @@ int swmm_2d_triangle_coupling_count(SWMM_Engine engine, int* count) {
 int swmm_2d_vertex_get_coupled_node(SWMM_Engine engine, int vertex_idx,
                                       int* node_idx) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_VERT_IDX(vertex_idx, router2d);
     if (!node_idx) return SWMM_ERR_BADPARAM;
 
-    *node_idx = router2d.mesh().vert_coupled_node[vertex_idx];
+    const auto& m = router2d.mesh();
+    *node_idx = coupledNodeIndex(eng, m.vert_coupled_node[vertex_idx],
+                                 m.vert_coupled_node_name[vertex_idx]);
     return SWMM_OK;
 }
 
 int swmm_2d_triangle_get_coupled_node(SWMM_Engine engine, int tri_idx,
                                         int* node_idx) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
     if (!node_idx) return SWMM_ERR_BADPARAM;
 
-    *node_idx = router2d.mesh().tri_coupled_node[tri_idx];
+    const auto& m = router2d.mesh();
+    *node_idx = coupledNodeIndex(eng, m.tri_coupled_node[tri_idx],
+                                 m.tri_coupled_node_name[tri_idx]);
     return SWMM_OK;
 }
 
@@ -420,7 +528,7 @@ int swmm_2d_get_triangle_coupling_row(SWMM_Engine engine, int row_idx,
 
     const auto& r = rows[static_cast(row_idx)];
     *tri_idx  = r.tri;
-    *node_idx = r.node;
+    *node_idx = coupledNodeIndex(eng, r.node, r.node_name);
     *cd       = r.cd;
     *area     = r.area;
     return SWMM_OK;
@@ -514,6 +622,36 @@ int swmm_2d_get_rainfall(SWMM_Engine engine, int idx, double* rainfall) {
     return SWMM_OK;
 }
 
+int swmm_2d_get_rainfall_weights(SWMM_Engine engine, int idx, int* method,
+                                 int* gage_indices, double* weights, int capacity,
+                                 int* count) {
+    GET_ENGINE(engine);
+    CHECK_2D_ACTIVE(eng);
+    CHECK_TRI_IDX(idx, router2d);
+    if (!method || !count || capacity < 0 ||
+        (capacity > 0 && (!gage_indices || !weights)))
+        return SWMM_ERR_BADPARAM;
+
+    const auto mode = router2d.options().rainfall_mode;
+    const auto& interp = router2d.rainfallInterpolator();
+    if ((mode != openswmm::twoD::RainfallMode::NATURAL_NEIGHBOUR &&
+         mode != openswmm::twoD::RainfallMode::NEAREST_NEIGHBOUR) || !interp.ready()) {
+        *method = -1;
+        *count  = 0;
+        return SWMM_OK;
+    }
+    std::vector g;
+    std::vector w;
+    interp.cellWeights(idx, g, w);
+    *method = static_cast(interp.cellMethod(idx));
+    *count  = static_cast(g.size());
+    for (int k = 0; k < std::min(capacity, *count); ++k) {
+        gage_indices[k] = g[static_cast(k)];
+        weights[k]      = w[static_cast(k)];
+    }
+    return SWMM_OK;
+}
+
 int swmm_2d_get_net_source(SWMM_Engine engine, int idx, double* net_source) {
     GET_ENGINE(engine);
     CHECK_2D_ACTIVE(eng);
@@ -534,6 +672,36 @@ int swmm_2d_get_depths_bulk(SWMM_Engine engine, double* depths) {
     return SWMM_OK;
 }
 
+int swmm_2d_get_rainfall_bulk(SWMM_Engine engine, double* rainfall) {
+    GET_ENGINE(engine);
+    CHECK_2D_ACTIVE(eng);
+    if (!rainfall) return SWMM_ERR_BADPARAM;
+
+    auto& s = router2d.state();
+    std::memcpy(rainfall, s.rainfall.data(), s.rainfall.size() * sizeof(double));
+    return SWMM_OK;
+}
+
+int swmm_2d_get_rain_volume_bulk(SWMM_Engine engine, double* volumes) {
+    GET_ENGINE(engine);
+    CHECK_2D_ACTIVE(eng);
+    if (!volumes) return SWMM_ERR_BADPARAM;
+
+    const auto& rc = router2d.rainCumulative();
+    std::memcpy(volumes, rc.data(), rc.size() * sizeof(double));
+    return SWMM_OK;
+}
+
+int swmm_2d_get_coupling_volume_bulk(SWMM_Engine engine, double* volumes) {
+    GET_ENGINE(engine);
+    CHECK_2D_ACTIVE(eng);
+    if (!volumes) return SWMM_ERR_BADPARAM;
+
+    const auto& cc = router2d.couplingCumulative();
+    std::memcpy(volumes, cc.data(), cc.size() * sizeof(double));
+    return SWMM_OK;
+}
+
 int swmm_2d_get_heads_bulk(SWMM_Engine engine, double* heads) {
     GET_ENGINE(engine);
     CHECK_2D_ACTIVE(eng);
@@ -567,19 +735,17 @@ bool partnerSlot(const openswmm::twoD::MeshData& mesh,
                  int tri, int edge,
                  int& nbr_tri, int& nbr_edge)
 {
-    const int nbr =
-        (edge == 0) ? mesh.tri_nbr0[tri] :
-        (edge == 1) ? mesh.tri_nbr1[tri] :
-                      mesh.tri_nbr2[tri];
+    const int nbr = mesh.cell_neighbour(tri, edge);
     if (nbr < 0) return false;
 
     // Find which of nbr's local edges points back at `tri` — that's the
     // partner slot.  At most one match by construction of the neighbour
     // table.
-    if      (mesh.tri_nbr0[nbr] == tri) nbr_edge = 0;
-    else if (mesh.tri_nbr1[nbr] == tri) nbr_edge = 1;
-    else if (mesh.tri_nbr2[nbr] == tri) nbr_edge = 2;
-    else return false;  // neighbour table inconsistent — shouldn't happen
+    const int nvn = mesh.cell_vertex_count(nbr);
+    nbr_edge = -1;
+    for (int k = 0; k < nvn; ++k)
+        if (mesh.cell_neighbour(nbr, k) == tri) { nbr_edge = k; break; }
+    if (nbr_edge < 0) return false;  // neighbour table inconsistent — shouldn't happen
     nbr_tri = nbr;
     return true;
 }
@@ -591,10 +757,10 @@ int swmm_2d_get_edge_conveyance(SWMM_Engine engine, int tri, int edge,
     GET_ENGINE(engine);
     CHECK_2D_ACTIVE(eng);
     CHECK_TRI_IDX(tri, router2d);
-    if (edge < 0 || edge > 2)   return SWMM_ERR_BADINDEX;
+    CHECK_EDGE_IDX(tri, edge, router2d);
     if (!conveyance)            return SWMM_ERR_BADPARAM;
 
-    *conveyance = router2d.mesh().edge_conveyance[tri * 3 + edge];
+    *conveyance = router2d.mesh().edge_conveyance[openswmm::twoD::MeshData::slot(tri, edge)];
     return SWMM_OK;
 }
 
@@ -604,16 +770,16 @@ int swmm_2d_set_edge_conveyance(SWMM_Engine engine, int tri, int edge,
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri, router2d);
-    if (edge < 0 || edge > 2)                          return SWMM_ERR_BADINDEX;
+    CHECK_EDGE_IDX(tri, edge, router2d);
     if (!(conveyance >= 0.0 && conveyance <= 1.0))     return SWMM_ERR_BADPARAM;
 
     auto& mesh = router2d.mesh();
-    mesh.edge_conveyance[tri * 3 + edge] = conveyance;
+    mesh.edge_conveyance[openswmm::twoD::MeshData::slot(tri, edge)] = conveyance;
 
     // Q3 silent partner mirroring — interior edges only.
     int nbr_tri = -1, nbr_edge = -1;
     if (partnerSlot(mesh, tri, edge, nbr_tri, nbr_edge)) {
-        mesh.edge_conveyance[nbr_tri * 3 + nbr_edge] = conveyance;
+        mesh.edge_conveyance[openswmm::twoD::MeshData::slot(nbr_tri, nbr_edge)] = conveyance;
     }
     return SWMM_OK;
 }
@@ -625,8 +791,14 @@ int swmm_2d_get_edge_conveyance_bulk(SWMM_Engine engine, double* conveyance)
     if (!conveyance) return SWMM_ERR_BADPARAM;
 
     auto& m = router2d.mesh();
-    std::memcpy(conveyance, m.edge_conveyance.data(),
-                m.edge_conveyance.size() * sizeof(double));
+    // Public layout is [cell * edge_stride + edge] (stride 3 for all-triangle
+    // meshes, 4 once a quad exists); pack from the internal padded slots.
+    const int stride = m.edge_stride();
+    for (int c = 0; c < m.n_triangles(); ++c)
+        for (int k = 0; k < stride; ++k)
+            conveyance[static_cast(c) * stride + k] =
+                m.edge_conveyance[static_cast(
+                    openswmm::twoD::MeshData::slot(c, k))];
     return SWMM_OK;
 }
 
@@ -650,8 +822,12 @@ int swmm_2d_get_edge_flux_bulk(SWMM_Engine engine, double* flux) {
     // edge_flux INFLOW-positive, so flip the sign on the way out. The internal
     // state is untouched (the volume update relies on the inflow-positive array).
     const auto& ef = s.edge_flux;
-    for (std::size_t i = 0; i < ef.size(); ++i)
-        flux[i] = -ef[i];
+    const auto& m  = router2d.mesh();
+    const int stride = m.edge_stride();
+    for (int c = 0; c < m.n_triangles(); ++c)
+        for (int k = 0; k < stride; ++k)
+            flux[static_cast(c) * stride + k] =
+                -ef[static_cast(openswmm::twoD::MeshData::slot(c, k))];
     return SWMM_OK;
 }
 
@@ -662,10 +838,15 @@ int swmm_2d_edge_get_geometry_bulk(SWMM_Engine engine,
     if (!length || !nx || !ny) return SWMM_ERR_BADPARAM;
 
     auto& m = router2d.mesh();
-    const size_t n3 = m.edge_length.size();
-    std::memcpy(length, m.edge_length.data(), n3 * sizeof(double));
-    std::memcpy(nx,     m.edge_nx.data(),     n3 * sizeof(double));
-    std::memcpy(ny,     m.edge_ny.data(),     n3 * sizeof(double));
+    const int stride = m.edge_stride();
+    for (int c = 0; c < m.n_triangles(); ++c)
+        for (int k = 0; k < stride; ++k) {
+            const auto dst = static_cast(c) * stride + k;
+            const auto src = static_cast(openswmm::twoD::MeshData::slot(c, k));
+            length[dst] = m.edge_length[src];
+            nx[dst]     = m.edge_nx[src];
+            ny[dst]     = m.edge_ny[src];
+        }
     return SWMM_OK;
 }
 
@@ -679,6 +860,7 @@ int swmm_2d_vertex_get_head(SWMM_Engine engine, int idx, double* head) {
     CHECK_VERT_IDX(idx, router2d);
     if (!head) return SWMM_ERR_BADPARAM;
 
+    router2d.refreshRenderFieldsIfStale();
     *head = router2d.state().vert_head[idx];
     return SWMM_OK;
 }
@@ -688,6 +870,7 @@ int swmm_2d_vertex_get_heads_bulk(SWMM_Engine engine, double* heads) {
     CHECK_2D_ACTIVE(eng);
     if (!heads) return SWMM_ERR_BADPARAM;
 
+    router2d.refreshRenderFieldsIfStale();
     auto& s = router2d.state();
     std::memcpy(heads, s.vert_head.data(), s.vert_head.size() * sizeof(double));
     return SWMM_OK;
@@ -698,6 +881,7 @@ int swmm_2d_vertex_get_render_depths_bulk(SWMM_Engine engine, double* depths) {
     CHECK_2D_ACTIVE(eng);
     if (!depths) return SWMM_ERR_BADPARAM;
 
+    router2d.refreshRenderFieldsIfStale();
     auto& s = router2d.state();
     std::memcpy(depths, s.vert_depth_signed.data(),
                 s.vert_depth_signed.size() * sizeof(double));
@@ -754,6 +938,31 @@ int swmm_2d_get_solver_last_step(SWMM_Engine engine, double* h_last) {
     return SWMM_OK;
 }
 
+int swmm_2d_get_run_stats(SWMM_Engine engine, SWMM_2DRunStats* stats) {
+    GET_ENGINE(engine);
+    CHECK_2D_ACTIVE(eng);
+    if (!stats) return SWMM_ERR_BADPARAM;
+
+    *stats = SWMM_2DRunStats{};
+    std::snprintf(stats->backend, sizeof stats->backend, "%s",
+                  router2d.backendName().c_str());
+    const auto& o = router2d.options();
+    using openswmm::twoD::Momentum2D;
+    stats->momentum  = (o.momentum == Momentum2D::FULL_SWE)       ? 1
+                     : (o.momentum == Momentum2D::DIFFUSIVE_WAVE) ? 2 : 0;
+    stats->lts_tiers = o.lts_tiers;
+    const auto s = router2d.runStats();
+    stats->steps            = s.nsteps;
+    stats->face_evals       = s.nrhs;
+    stats->last_step        = s.last_h;
+    stats->active_frac_min  = s.active_frac_min;
+    stats->active_frac_mean = s.active_frac_mean;
+    stats->active_frac_max  = s.active_frac_max;
+    stats->n_tiers          = s.n_tiers;
+    for (int k = 0; k < 8; ++k) stats->tier_cells[k] = s.tier_cells[k];
+    return SWMM_OK;
+}
+
 int swmm_2d_get_stat_max_depths(SWMM_Engine engine, double* max_depths) {
     GET_ENGINE(engine);
     CHECK_2D_ACTIVE(eng);
@@ -843,6 +1052,7 @@ int swmm_2d_force_rainfall(SWMM_Engine engine, int idx,
     s.rainfall_force_val[idx] = value;
     s.rainfall_persist[idx]   = static_cast(persist);
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -861,6 +1071,7 @@ int swmm_2d_force_rainfall_uniform(SWMM_Engine engine,
         s.rainfall_persist[i]   = static_cast(persist);
     }
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -877,6 +1088,7 @@ int swmm_2d_force_evap(SWMM_Engine engine, int idx,
     s.evap_force_val[idx] = value;
     s.evap_persist[idx]   = static_cast(persist);
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -895,6 +1107,7 @@ int swmm_2d_force_evap_uniform(SWMM_Engine engine,
         s.evap_persist[i]   = static_cast(persist);
     }
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -911,6 +1124,7 @@ int swmm_2d_force_coupling_flux(SWMM_Engine engine, int idx,
     s.coupling_force_val[idx] = value;
     s.coupling_persist[idx]   = static_cast(persist);
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -932,6 +1146,7 @@ int swmm_2d_force_clear_all(SWMM_Engine engine) {
         s.coupling_persist[i] = 0;
     }
     s.forcing_dirty = true;
+    s.forcing_ever_set = true;
     return SWMM_OK;
 }
 
@@ -969,11 +1184,7 @@ int swmm_2d_set_dry_depth(SWMM_Engine engine, double dry_depth) {
 namespace {
 
 inline int tri_nbr(const openswmm::twoD::MeshData& mesh, int t, int e) {
-    switch (e) {
-        case 0:  return mesh.tri_nbr0[t];
-        case 1:  return mesh.tri_nbr1[t];
-        default: return mesh.tri_nbr2[t];
-    }
+    return (e >= 0 && e < mesh.cell_vertex_count(t)) ? mesh.cell_neighbour(t, e) : -2;
 }
 
 } // namespace
@@ -986,22 +1197,37 @@ int swmm_2d_boundary_edge_count(SWMM_Engine engine, int* count) {
     const auto& mesh = router2d.mesh();
     int n = 0;
     for (int t = 0; t < mesh.n_triangles(); ++t) {
-        if (mesh.tri_nbr0[t] < 0) ++n;
-        if (mesh.tri_nbr1[t] < 0) ++n;
-        if (mesh.tri_nbr2[t] < 0) ++n;
+        const int nvc = mesh.cell_vertex_count(t);
+        for (int k = 0; k < nvc; ++k)
+            if (mesh.cell_neighbour(t, k) < 0) ++n;
     }
     *count = n;
     return SWMM_OK;
 }
 
+// The four BC-value getters below read parsed MESH data, not solver state,
+// so they use CHECK_2D_MESH and work in the OPENED state the GUI holds —
+// the setters' mirror image (SVBC round A8). Only the cum_flux getter reads
+// a runtime accumulator and keeps CHECK_2D_ACTIVE.
+// BoundaryData's live arrays are sized by drainPendingRows() (via
+// swmm_2d_prepare_for_edit or initialize) — before that, in the freshly
+// OPENED state, they are EMPTY even for a deck with authored BC rows, and
+// unchecked indexing segfaulted (found by this round's pre-push gate). The
+// getters refuse cleanly until the drain instead.
+#define CHECK_BC_SIZED(vec, idx) \
+    if ((idx) < 0 || static_cast(idx) >= (vec).size()) \
+        return SWMM_ERR_BADPARAM
+
 int swmm_2d_get_edge_bc_type(SWMM_Engine engine, int tri_idx, int edge,
                               int* bc_type) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2 || !bc_type) return SWMM_ERR_BADPARAM;
+    if (!bc_type) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_type, openswmm::twoD::MeshData::slot(tri_idx, edge));
 
-    *bc_type = router2d.boundary().edge_bc_type[tri_idx * 3 + edge];
+    *bc_type = router2d.boundary().edge_bc_type[openswmm::twoD::MeshData::slot(tri_idx, edge)];
     return SWMM_OK;
 }
 
@@ -1010,7 +1236,7 @@ int swmm_2d_set_edge_bc_type(SWMM_Engine engine, int tri_idx, int edge,
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
     if (bc_type != SWMM_2D_BC_WALL &&
         bc_type != SWMM_2D_BC_NORMAL_FLOW &&
         bc_type != SWMM_2D_BC_SPECIFIED_STAGE &&
@@ -1019,19 +1245,22 @@ int swmm_2d_set_edge_bc_type(SWMM_Engine engine, int tri_idx, int edge,
         return SWMM_ERR_BADPARAM;
     }
 
-    router2d.boundary().edge_bc_type[tri_idx * 3 + edge] =
+    router2d.boundary().edge_bc_type[openswmm::twoD::MeshData::slot(tri_idx, edge)] =
         static_cast(bc_type);
+    router2d.invalidateBoundaryIndex();
     return SWMM_OK;
 }
 
 int swmm_2d_get_edge_bc_head(SWMM_Engine engine, int tri_idx, int edge,
                               double* head) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2 || !head) return SWMM_ERR_BADPARAM;
+    if (!head) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_head, openswmm::twoD::MeshData::slot(tri_idx, edge));
 
-    *head = router2d.boundary().edge_bc_head[tri_idx * 3 + edge];
+    *head = router2d.boundary().edge_bc_head[openswmm::twoD::MeshData::slot(tri_idx, edge)];
     return SWMM_OK;
 }
 
@@ -1040,20 +1269,22 @@ int swmm_2d_set_edge_bc_head(SWMM_Engine engine, int tri_idx, int edge,
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    router2d.boundary().edge_bc_head[tri_idx * 3 + edge] = head;
+    router2d.boundary().edge_bc_head[openswmm::twoD::MeshData::slot(tri_idx, edge)] = head;
     return SWMM_OK;
 }
 
 int swmm_2d_get_edge_bc_slope(SWMM_Engine engine, int tri_idx, int edge,
                                double* slope) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2 || !slope) return SWMM_ERR_BADPARAM;
+    if (!slope) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bed_slope, openswmm::twoD::MeshData::slot(tri_idx, edge));
 
-    *slope = router2d.boundary().edge_bed_slope[tri_idx * 3 + edge];
+    *slope = router2d.boundary().edge_bed_slope[openswmm::twoD::MeshData::slot(tri_idx, edge)];
     return SWMM_OK;
 }
 
@@ -1062,10 +1293,10 @@ int swmm_2d_set_edge_bc_slope(SWMM_Engine engine, int tri_idx, int edge,
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
     if (slope < 0.0) return SWMM_ERR_BADPARAM;
 
-    router2d.boundary().edge_bed_slope[tri_idx * 3 + edge] = slope;
+    router2d.boundary().edge_bed_slope[openswmm::twoD::MeshData::slot(tri_idx, edge)] = slope;
     return SWMM_OK;
 }
 
@@ -1074,9 +1305,10 @@ int swmm_2d_get_edge_bc_cum_flux(SWMM_Engine engine, int tri_idx, int edge,
     GET_ENGINE(engine);
     CHECK_2D_ACTIVE(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2 || !cum_flux) return SWMM_ERR_BADPARAM;
+    if (!cum_flux) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    *cum_flux = router2d.boundary().edge_bc_cum_flux[tri_idx * 3 + edge];
+    *cum_flux = router2d.boundary().edge_bc_cum_flux[openswmm::twoD::MeshData::slot(tri_idx, edge)];
     return SWMM_OK;
 }
 
@@ -1092,9 +1324,9 @@ int swmm_2d_set_edge_bc_tseries_name(SWMM_Engine engine, int tri_idx, int edge,
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    const int idx = tri_idx * 3 + edge;
+    const int idx = openswmm::twoD::MeshData::slot(tri_idx, edge);
     auto& b = router2d.boundary();
     if (!name || name[0] == '\0') {
         b.edge_bc_tseries_name[idx].clear();
@@ -1109,22 +1341,76 @@ int swmm_2d_set_edge_bc_tseries_name(SWMM_Engine engine, int tri_idx, int edge,
 int swmm_2d_get_edge_bc_flow(SWMM_Engine engine, int tri_idx, int edge,
                                double* flow) {
     GET_ENGINE(engine);
-    CHECK_2D_ACTIVE(eng);
+    CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2 || !flow) return SWMM_ERR_BADPARAM;
+    if (!flow) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_flow, openswmm::twoD::MeshData::slot(tri_idx, edge));
 
-    *flow = router2d.boundary().edge_bc_flow[tri_idx * 3 + edge];
+    *flow = router2d.boundary().edge_bc_flow[openswmm::twoD::MeshData::slot(tri_idx, edge)];
     return SWMM_OK;
 }
 
+// SVBC A8 — name getters, the setter trio's mirror image, so a caller can
+// VERIFY what the engine holds after an edit push (the GUI previously had
+// write-only access to BC names). Same buf/buflen truncating-copy
+// convention as swmm_2d_get_vertex_tag.
+static int copyBcName(const std::string& s, char* buf, int buflen) {
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const int copy_len = std::min(static_cast(s.size()), buflen - 1);
+    if (copy_len > 0)
+        std::memcpy(buf, s.c_str(), static_cast(copy_len));
+    buf[copy_len] = '\0';
+    return SWMM_OK;
+}
+
+int swmm_2d_get_edge_bc_tseries_name(SWMM_Engine engine, int tri_idx, int edge,
+                                       char* buf, int buflen) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(tri_idx, router2d);
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_tseries_name,
+                   openswmm::twoD::MeshData::slot(tri_idx, edge));
+    return copyBcName(
+        router2d.boundary().edge_bc_tseries_name[openswmm::twoD::MeshData::slot(tri_idx, edge)],
+        buf, buflen);
+}
+
+int swmm_2d_get_edge_bc_flow_tseries_name(SWMM_Engine engine, int tri_idx,
+                                            int edge, char* buf, int buflen) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(tri_idx, router2d);
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_flow_tseries_name,
+                   openswmm::twoD::MeshData::slot(tri_idx, edge));
+    return copyBcName(
+        router2d.boundary().edge_bc_flow_tseries_name[openswmm::twoD::MeshData::slot(tri_idx, edge)],
+        buf, buflen);
+}
+
+int swmm_2d_get_edge_bc_rating_curve_name(SWMM_Engine engine, int tri_idx,
+                                            int edge, char* buf, int buflen) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(tri_idx, router2d);
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
+    CHECK_BC_SIZED(router2d.boundary().edge_bc_rating_curve_name,
+                   openswmm::twoD::MeshData::slot(tri_idx, edge));
+    return copyBcName(
+        router2d.boundary().edge_bc_rating_curve_name[openswmm::twoD::MeshData::slot(tri_idx, edge)],
+        buf, buflen);
+}
+
 int swmm_2d_set_edge_bc_flow(SWMM_Engine engine, int tri_idx, int edge,
                                double flow) {
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    router2d.boundary().edge_bc_flow[tri_idx * 3 + edge] = flow;
+    router2d.boundary().edge_bc_flow[openswmm::twoD::MeshData::slot(tri_idx, edge)] = flow;
     return SWMM_OK;
 }
 
@@ -1133,9 +1419,9 @@ int swmm_2d_set_edge_bc_flow_tseries_name(SWMM_Engine engine, int tri_idx, int e
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    const int idx = tri_idx * 3 + edge;
+    const int idx = openswmm::twoD::MeshData::slot(tri_idx, edge);
     auto& b = router2d.boundary();
     if (!name || name[0] == '\0') {
         b.edge_bc_flow_tseries_name[idx].clear();
@@ -1152,9 +1438,9 @@ int swmm_2d_set_edge_bc_rating_curve_name(SWMM_Engine engine, int tri_idx, int e
     GET_ENGINE(engine);
     CHECK_2D_MESH(eng);
     CHECK_TRI_IDX(tri_idx, router2d);
-    if (edge < 0 || edge > 2) return SWMM_ERR_BADPARAM;
+    CHECK_EDGE_IDX(tri_idx, edge, router2d);
 
-    const int idx = tri_idx * 3 + edge;
+    const int idx = openswmm::twoD::MeshData::slot(tri_idx, edge);
     auto& b = router2d.boundary();
     if (!name || name[0] == '\0') {
         b.edge_bc_rating_curve_name[idx].clear();
@@ -1166,4 +1452,31 @@ int swmm_2d_set_edge_bc_rating_curve_name(SWMM_Engine engine, int tri_idx, int e
     return SWMM_OK;
 }
 
+// ============================================================================
+// Results-file variable selection helpers (engine-independent)
+// ============================================================================
+
+int swmm_2d_output_variable_count(void) {
+    return static_cast(openswmm::twoD::report2d::tokens().size());
+}
+
+const char* swmm_2d_output_variable_name(int i) {
+    const auto& t = openswmm::twoD::report2d::tokens();
+    if (i < 0 || i >= static_cast(t.size())) return "";
+    return t[static_cast(i)].c_str();
+}
+
+unsigned swmm_2d_output_variable_mask(const char* text) {
+    if (!text) return 0u;
+    unsigned mask = 0u;
+    if (!openswmm::twoD::report2d::parseMask(text, mask).empty()) return 0u;
+    return mask;
+}
+
+const char* swmm_2d_output_variable_text(unsigned mask) {
+    static thread_local std::string buf;
+    buf = openswmm::twoD::report2d::formatMask(mask);
+    return buf.c_str();
+}
+
 } // extern "C"
diff --git a/src/engine/2d/api/Api2D.hpp b/src/engine/2d/api/Api2D.hpp
index bdb049c6d..57d1c3295 100644
--- a/src/engine/2d/api/Api2D.hpp
+++ b/src/engine/2d/api/Api2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Api2D.hpp
  * @brief C API implementation bridge for the 2D surface routing module.
@@ -9,7 +25,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_API_HPP
diff --git a/src/engine/2d/api/ApiGw2D.cpp b/src/engine/2d/api/ApiGw2D.cpp
new file mode 100644
index 000000000..34afb7e8d
--- /dev/null
+++ b/src/engine/2d/api/ApiGw2D.cpp
@@ -0,0 +1,601 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ApiGw2D.cpp
+ * @brief G-step 19 — implementation of `openswmm_gw2d.h`.
+ *
+ * @details The authoring half edits `SubsurfaceConfig` (project units, never
+ *          converted); the state half reads `SubsurfaceState` (SI). Keeping
+ *          the two apart in the header is what keeps them apart here: there
+ *          is no place in this file where a project-unit number and an SI one
+ *          could be added together.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+
+#include "../../core/SWMMEngine.hpp"
+#include "../subsurface/SubsurfaceSections.hpp"
+#include "../subsurface/SubsurfaceSolver.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace {
+
+using openswmm::twoD::GwAquiferRow;
+using openswmm::twoD::GwClosure;
+using openswmm::twoD::GwLinkMode;   // G-X4
+using openswmm::twoD::GwNodeBed;
+using openswmm::twoD::SoilChar;
+using openswmm::twoD::SubsurfaceConfig;
+using openswmm::twoD::SubsurfaceSolver;
+
+void copy_to(const std::string& src, char* buf, int len) {
+    if (!buf || len <= 0) return;
+    const int n = std::min(static_cast(src.size()), len - 1);
+    std::memcpy(buf, src.c_str(), static_cast(n));
+    buf[n] = '\0';
+}
+
+bool ieq(const char* a, const char* b) {
+    if (!a || !b) return false;
+    for (; *a && *b; ++a, ++b)
+        if (std::toupper(static_cast(*a)) !=
+            std::toupper(static_cast(*b))) return false;
+    return *a == '\0' && *b == '\0';
+}
+
+}  // namespace
+
+// Authoring edits the rows the kernel is BUILT from, so the guard is the
+// editable-state one — the same contract as the 2D boundary, infiltration and
+// [GW_*] APIs. A mid-run set would be silently dropped at the next
+// initialize, and silence is the worst of the three options.
+#define AQ_CFG(engine) \
+    auto* eng = reinterpret_cast(engine); \
+    if (!eng) return SWMM_ERR_BADHANDLE; \
+    SubsurfaceConfig& cfg = eng->surfaceRouter2D().aquiferConfig()
+
+#define AQ_EDITABLE(eng) \
+    if (eng->context().state != openswmm::EngineState::OPENED && \
+        eng->context().state != openswmm::EngineState::BUILDING) \
+        return SWMM_ERR_LIFECYCLE
+
+#define AQ_SOLVER(engine) \
+    auto* eng = reinterpret_cast(engine); \
+    if (!eng) return SWMM_ERR_BADHANDLE; \
+    const SubsurfaceSolver& gw = eng->surfaceRouter2D().subsurface(); \
+    if (!gw.active()) return SWMM_ERR_LIFECYCLE
+
+extern "C" {
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER_OPTIONS]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw2d_option_get(SWMM_Engine engine, const char* key,
+                                         char* buf, int buflen) {
+    AQ_CFG(engine);
+    if (!key || !buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& o = cfg.options;
+    auto yn = [](bool b) { return std::string(b ? "YES" : "NO"); };
+    auto num = [](double v) {
+        char t[32];
+        std::snprintf(t, sizeof t, "%.6g", v);
+        return std::string(t);
+    };
+    std::string v;
+    if      (ieq(key, "SOIL_CHAR"))       v = soilCharToken(o.soil_char);
+    else if (ieq(key, "CLOSURE"))         v = gwClosureToken(o.closure);
+    else if (ieq(key, "M_LAYERS"))        v = std::to_string(o.m_layers);
+    else if (ieq(key, "CAPILLARY_DIFF"))  v = yn(o.capillary_diff);
+    else if (ieq(key, "C_GW"))            v = num(o.c_gw);
+    else if (ieq(key, "C_COL"))           v = num(o.c_col);
+    else if (ieq(key, "FORCE_CLOSED_FORM")) v = yn(o.force_closed_form);
+    else if (ieq(key, "MODE"))            v = o.per_subcatch ? "PER_SUBCATCH" : "MESH";
+    else if (ieq(key, "DUNNE"))           v = yn(o.dunne);
+    else if (ieq(key, "GW_ET"))           v = o.gw_et;
+    else if (ieq(key, "NODE_ENROLMENT"))  v = o.node_auto ? "AUTO" : "ROWS";   // G-X2
+    else if (ieq(key, "LINK_SEEPAGE"))                                          // G-X3/G-X4
+        v = (o.link_seepage == GwLinkMode::NONE)    ? "NONE"
+          : (o.link_seepage == GwLinkMode::TWO_WAY) ? "TWO_WAY" : "AUTO";
+    else return SWMM_ERR_BADPARAM;
+    copy_to(v, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_option_set(SWMM_Engine engine, const char* key,
+                                         const char* value) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (!key || !value) return SWMM_ERR_BADPARAM;
+    // One parser for the file and the API. A second spelling table here is
+    // how a host ends up able to set something the .inp cannot express, and
+    // then the model does not round-trip.
+    const std::vector tokens{key, value};
+    const std::string err =
+        openswmm::twoD::parseAquiferOptionsLine(tokens, cfg.options);
+    if (!err.empty()) return SWMM_ERR_BADPARAM;
+    cfg.options.authored = true;
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER] rows
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw2d_row_count(SWMM_Engine engine, int* count) {
+    AQ_CFG(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = static_cast(cfg.rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_row_add(SWMM_Engine engine, int scope,
+                                      const char* tag, int cell,
+                                      double ks, double zs,
+                                      double theta_s, double theta_r,
+                                      double alpha) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (scope < 0 || scope > 2) return SWMM_ERR_BADPARAM;
+    if (scope == SWMM_GW2D_SCOPE_TAG && (!tag || tag[0] == '\0'))
+        return SWMM_ERR_BADPARAM;
+    if (scope == SWMM_GW2D_SCOPE_CELL && cell < 0) return SWMM_ERR_BADPARAM;
+    // The same validity rules the parser enforces, so a host cannot build a
+    // model the file would refuse.
+    if (!(ks > 0.0) || !(zs > 0.0) || !(alpha > 0.0)) return SWMM_ERR_BADPARAM;
+    if (!(theta_s > 0.0) || theta_s > 1.0) return SWMM_ERR_BADPARAM;
+    if (theta_r < 0.0 || theta_r >= theta_s) return SWMM_ERR_BADPARAM;
+
+    GwAquiferRow r;
+    r.scope   = scope;
+    r.tag     = (scope == SWMM_GW2D_SCOPE_TAG) ? tag : "";
+    r.cell    = (scope == SWMM_GW2D_SCOPE_CELL) ? cell : -1;
+    r.Ks      = ks;
+    r.zs      = zs;
+    r.theta_s = theta_s;
+    r.theta_r = theta_r;
+    r.alpha   = alpha;
+    cfg.rows.push_back(r);
+    cfg.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_row_get(SWMM_Engine engine, int index,
+                                      int* scope, char* tag, int taglen,
+                                      int* cell, double* ks, double* zs,
+                                      double* theta_s, double* theta_r,
+                                      double* alpha) {
+    AQ_CFG(engine);
+    if (index < 0 || index >= static_cast(cfg.rows.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& r = cfg.rows[static_cast(index)];
+    if (scope)   *scope   = r.scope;
+    if (cell)    *cell    = r.cell;
+    if (ks)      *ks      = r.Ks;
+    if (zs)      *zs      = r.zs;
+    if (theta_s) *theta_s = r.theta_s;
+    if (theta_r) *theta_r = r.theta_r;
+    if (alpha)   *alpha   = r.alpha;
+    if (tag)     copy_to(r.tag, tag, taglen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_row_set_property(SWMM_Engine engine, int index,
+                                               const char* key, double value) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (!key || index < 0 || index >= static_cast(cfg.rows.size()))
+        return SWMM_ERR_BADPARAM;
+    auto& r = cfg.rows[static_cast(index)];
+    if      (ieq(key, "PSI_B"))  { if (value < 0.0)  return SWMM_ERR_BADPARAM; r.psi_b = value; }
+    else if (ieq(key, "LAMBDA")) { if (value <= 0.0) return SWMM_ERR_BADPARAM; r.lambda = value; }
+    else if (ieq(key, "N"))      { if (value <= 1.0) return SWMM_ERR_BADPARAM; r.vg_n = value; }
+    else if (ieq(key, "L"))      { r.vg_L = value; }
+    else if (ieq(key, "C_LOSS")) { if (value < 0.0)  return SWMM_ERR_BADPARAM; r.c_loss = value; }
+    else if (ieq(key, "HG0"))    { r.hg0 = value; }
+    else if (ieq(key, "SOIL_CHAR")) {
+        const int c = static_cast(std::lround(value));
+        if (c < 0 || c > 3) return SWMM_ERR_BADPARAM;
+        r.soil_char = static_cast(c);
+        r.soil_char_set = true;
+    } else if (ieq(key, "CLOSURE")) {
+        const int c = static_cast(std::lround(value));
+        if (c < -1 || c > 2) return SWMM_ERR_BADPARAM;
+        r.closure = static_cast(c);
+        r.closure_set = true;
+    } else if (ieq(key, "M_LAYERS")) {
+        const int mlayers = static_cast(std::lround(value));
+        if (mlayers < 2 || mlayers > 128) return SWMM_ERR_BADPARAM;
+        r.m_layers = mlayers;
+    } else {
+        return SWMM_ERR_BADPARAM;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_row_get_property(SWMM_Engine engine, int index,
+                                               const char* key, double* value) {
+    AQ_CFG(engine);
+    if (!key || !value || index < 0 ||
+        index >= static_cast(cfg.rows.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& r = cfg.rows[static_cast(index)];
+    if      (ieq(key, "PSI_B"))     *value = r.psi_b;
+    else if (ieq(key, "LAMBDA"))    *value = r.lambda;
+    else if (ieq(key, "N"))         *value = r.vg_n;
+    else if (ieq(key, "L"))         *value = r.vg_L;
+    else if (ieq(key, "C_LOSS"))    *value = r.c_loss;
+    else if (ieq(key, "HG0"))       *value = r.hg0;
+    else if (ieq(key, "SOIL_CHAR")) *value = static_cast(r.soil_char);
+    else if (ieq(key, "CLOSURE"))   *value = static_cast(r.closure);
+    else if (ieq(key, "M_LAYERS"))  *value = r.m_layers;
+    else return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_row_remove(SWMM_Engine engine, int index) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(cfg.rows.size()))
+        return SWMM_ERR_BADPARAM;
+    cfg.rows.erase(cfg.rows.begin() + index);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER_NODE]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw2d_node_count(SWMM_Engine engine, int* count) {
+    AQ_CFG(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = static_cast(cfg.node_beds.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_node_add(SWMM_Engine engine, const char* node,
+                                       int cell, double kc, double dc,
+                                       double area) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (!node || node[0] == '\0' || cell < -1) return SWMM_ERR_BADPARAM;
+    if (kc < 0.0 || dc < 0.0 || area < 0.0) return SWMM_ERR_BADPARAM;
+    if (kc > 0.0 && dc <= 0.0) return SWMM_ERR_BADPARAM;   // a bed needs a thickness
+    GwNodeBed b;
+    b.cell   = cell;
+    b.locate = (cell < 0);      // G-X2: −1 = CELL AUTO, located at initialize
+    b.Kc   = kc;
+    b.dC   = dc;
+    b.area = area;
+    cfg.node_beds.push_back(b);
+    eng->surfaceRouter2D().aquiferNodeNames().emplace_back(node);
+    cfg.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_node_get(SWMM_Engine engine, int index,
+                                       char* node, int nodelen, int* cell,
+                                       double* kc, double* dc, double* area) {
+    AQ_CFG(engine);
+    if (index < 0 || index >= static_cast(cfg.node_beds.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& b = cfg.node_beds[static_cast(index)];
+    if (cell) *cell = b.cell;
+    if (kc)   *kc   = b.Kc;
+    if (dc)   *dc   = b.dC;
+    if (area) *area = b.area;
+    if (node) {
+        const auto& names = eng->surfaceRouter2D().aquiferNodeNames();
+        copy_to(index < static_cast(names.size())
+                    ? names[static_cast(index)] : std::string{},
+                node, nodelen);
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_node_get_flags(SWMM_Engine engine, int index,
+                                             int* locate, int* exchange,
+                                             int* automatic) {
+    AQ_CFG(engine);   // G-X2
+    if (index < 0 || index >= static_cast(cfg.node_beds.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& b = cfg.node_beds[static_cast(index)];
+    if (locate)    *locate    = b.locate ? 1 : 0;
+    if (exchange)  *exchange  = b.exchange ? 1 : 0;
+    if (automatic) *automatic = b.automatic ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_node_set_exchange(SWMM_Engine engine, int index,
+                                                int exchange) {
+    AQ_CFG(engine);   // G-X2
+    AQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(cfg.node_beds.size()))
+        return SWMM_ERR_BADPARAM;
+    cfg.node_beds[static_cast(index)].exchange = (exchange != 0);
+    cfg.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_node_remove(SWMM_Engine engine, int index) {
+    AQ_CFG(engine);
+    AQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(cfg.node_beds.size()))
+        return SWMM_ERR_BADPARAM;
+    cfg.node_beds.erase(cfg.node_beds.begin() + index);
+    auto& names = eng->surfaceRouter2D().aquiferNodeNames();
+    if (index < static_cast(names.size()))
+        names.erase(names.begin() + index);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// Running state
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw2d_is_active(SWMM_Engine engine, int* active) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return SWMM_ERR_BADHANDLE;
+    if (!active) return SWMM_ERR_BADPARAM;
+    *active = eng->surfaceRouter2D().subsurface().active() ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_dimensions(SWMM_Engine engine,
+                                             int* n_cells, int* m_layers) {
+    AQ_SOLVER(engine);
+    if (n_cells)  *n_cells  = gw.state().n_cells;
+    if (m_layers) *m_layers = gw.state().m_layers;
+    return SWMM_OK;
+}
+
+namespace {
+
+double cellVar(const openswmm::twoD::SubsurfaceState& st, std::size_t u,
+               int var, bool& ok) {
+    ok = true;
+    switch (var) {
+        case SWMM_GW2D_VAR_HG:       return st.hg[u];
+        case SWMM_GW2D_VAR_HU:       return st.hu[u];
+        case SWMM_GW2D_VAR_TABLE_EL: return st.z_bed[u] + st.hg[u];
+        case SWMM_GW2D_VAR_Q0:       return st.q0_last[u];
+        case SWMM_GW2D_VAR_QLAT:     return st.qlat_last[u];
+        case SWMM_GW2D_VAR_QNODE:    return st.qnode_last[u];
+        case SWMM_GW2D_VAR_QDEEP:    return st.qdeep_last[u];
+        case SWMM_GW2D_VAR_QET:      return st.qet_last[u];
+        case SWMM_GW2D_VAR_DUNNE:    return st.dunne_last[u];
+        case SWMM_GW2D_VAR_QPLUS:    return st.qplus_last[u];
+        case SWMM_GW2D_VAR_DT_CELL:  return st.dt_cell[u];
+        case SWMM_GW2D_VAR_TIER:     return static_cast(st.tier[u]);
+        case SWMM_GW2D_VAR_CLOSURE:  return static_cast(st.closure[u]);
+        case SWMM_GW2D_VAR_QLINK:    return st.qlink_last[u];   // G-X3
+        default: ok = false; return 0.0;
+    }
+}
+
+}  // namespace
+
+SWMM_ENGINE_API int swmm_gw2d_get_cell(SWMM_Engine engine, int cell, int var,
+                                       double* value) {
+    AQ_SOLVER(engine);
+    const auto& st = gw.state();
+    if (!value || cell < 0 || cell >= st.n_cells) return SWMM_ERR_BADPARAM;
+    bool ok = false;
+    const double v = cellVar(st, static_cast(cell), var, ok);
+    if (!ok) return SWMM_ERR_BADPARAM;
+    *value = v;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_cell_bulk(SWMM_Engine engine, int var,
+                                            double* out, int len,
+                                            int* written) {
+    AQ_SOLVER(engine);
+    const auto& st = gw.state();
+    if (!out || len < st.n_cells) return SWMM_ERR_BADPARAM;
+    bool ok = true;
+    for (int i = 0; i < st.n_cells && ok; ++i)
+        out[i] = cellVar(st, static_cast(i), var, ok);
+    if (!ok) return SWMM_ERR_BADPARAM;
+    if (written) *written = st.n_cells;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_column(SWMM_Engine engine, int cell,
+                                         double* theta, int len,
+                                         int* written) {
+    AQ_SOLVER(engine);
+    const auto& st = gw.state();
+    if (!theta || cell < 0 || cell >= st.n_cells) return SWMM_ERR_BADPARAM;
+    if (len < st.m_layers) return SWMM_ERR_BADPARAM;
+    // Refuse rather than return zeros: a caller that reads a closure-A cell's
+    // "column" would see a bone-dry profile and have no way to tell it apart
+    // from a real one.
+    if (st.closure[static_cast(cell)] !=
+        static_cast(GwClosure::SIGMA))
+        return SWMM_ERR_BADPARAM;
+    for (int j = 0; j < st.m_layers; ++j)
+        theta[j] = st.theta_sigma[static_cast(j) *
+                                      static_cast(st.n_cells) +
+                                  static_cast(cell)];
+    if (written) *written = st.m_layers;
+    return SWMM_OK;
+}
+
+namespace {
+
+// G-O: the storage views live on SubsurfaceState (the results file and the
+// report read the same numbers); the reasoning is on the methods there and
+// on swmm_gw2d_get_continuity_error below.
+double liveStorage(const SubsurfaceSolver& gw)     { return gw.state().liveStorage(); }
+double ledgeredStorage(const SubsurfaceSolver& gw) { return gw.state().ledgeredStorage(); }
+
+}  // namespace
+
+SWMM_ENGINE_API int swmm_gw2d_get_ledger(SWMM_Engine engine, int term,
+                                         double* value) {
+    AQ_SOLVER(engine);
+    if (!value) return SWMM_ERR_BADPARAM;
+    const auto& st = gw.state();
+    switch (term) {
+        case SWMM_GW2D_LED_RECHARGE:     *value = st.led_recharge; break;
+        case SWMM_GW2D_LED_LATERAL:      *value = st.led_lateral; break;
+        case SWMM_GW2D_LED_DEEP:         *value = st.led_deep; break;
+        case SWMM_GW2D_LED_NODE:         *value = st.led_node; break;
+        case SWMM_GW2D_LED_DUNNE:        *value = st.led_dunne; break;
+        case SWMM_GW2D_LED_CAPRISE:      *value = st.led_caprise; break;
+        case SWMM_GW2D_LED_ET:           *value = st.led_et; break;
+        case SWMM_GW2D_LED_INFIL_IN:     *value = st.led_infil_in; break;
+        case SWMM_GW2D_LED_INIT_STORAGE: *value = st.led_init_storage; break;
+        case SWMM_GW2D_LED_STORAGE:      *value = liveStorage(gw); break;
+        case SWMM_GW2D_LED_LINK:         *value = st.led_link; break;   // G-X3
+        default: return SWMM_ERR_BADPARAM;
+    }
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// T7.5 — the transported tuple, read-only
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw2d_species_count(SWMM_Engine engine, int* count) {
+    AQ_SOLVER(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    const auto& tr = gw.transport();
+    *count = tr.active() ? tr.n_species : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_species_name(SWMM_Engine engine, int species,
+                                           char* buf, int buflen) {
+    AQ_SOLVER(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& tr = gw.transport();
+    if (species < 0 || species >= tr.n_species) return SWMM_ERR_BADINDEX;
+    copy_to(tr.row_names[static_cast(species)], buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_cell_conc(SWMM_Engine engine, int zone,
+                                            int species, double* out, int len,
+                                            int* written) {
+    AQ_SOLVER(engine);
+    if (!out || len <= 0) return SWMM_ERR_BADPARAM;
+    if (zone != SWMM_GW2D_ZONE_SAT && zone != SWMM_GW2D_ZONE_UNSAT)
+        return SWMM_ERR_BADPARAM;
+    const auto& tr = gw.transport();
+    if (!tr.active() || species < 0 || species >= tr.n_species)
+        return SWMM_ERR_BADINDEX;
+    const int n = std::min(len, tr.n_cells);
+    for (int c = 0; c < n; ++c) {
+        const double v = (zone == SWMM_GW2D_ZONE_SAT) ? gw.satVolume(c)
+                                                      : gw.unsatVolume(c);
+        const auto k = tr.idx(species, c);
+        const double m = (zone == SWMM_GW2D_ZONE_SAT) ? tr.sat_mass[k]
+                                                      : tr.unsat_mass[k];
+        out[c] = (v > 0.0) ? m / v : 0.0;
+    }
+    if (written) *written = n;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_species_ledger(SWMM_Engine engine,
+                                                 int species, int term,
+                                                 double* value) {
+    AQ_SOLVER(engine);
+    if (!value) return SWMM_ERR_BADPARAM;
+    const auto& tr = gw.transport();
+    if (!tr.active() || species < 0 || species >= tr.n_species)
+        return SWMM_ERR_BADINDEX;
+    const auto u = static_cast(species);
+    switch (term) {
+        case SWMM_GW2D_SPL_INIT:        *value = tr.init_mass[u]; break;
+        case SWMM_GW2D_SPL_STORAGE:     *value = tr.ledgeredStorage(species); break;
+        case SWMM_GW2D_SPL_INFIL_IN:    *value = tr.gained_infil[u]; break;
+        case SWMM_GW2D_SPL_NODE_IN:     *value = tr.gained_node[u]; break;
+        case SWMM_GW2D_SPL_LINK_IN:     *value = tr.gained_link[u]; break;
+        case SWMM_GW2D_SPL_LATERAL_NET: *value = tr.net_lateral[u]; break;
+        case SWMM_GW2D_SPL_DEEP_OUT:    *value = tr.lost_deep[u]; break;
+        case SWMM_GW2D_SPL_NODE_OUT:    *value = tr.lost_node[u]; break;
+        case SWMM_GW2D_SPL_LINK_OUT:    *value = tr.lost_link[u]; break;
+        case SWMM_GW2D_SPL_DUNNE_OUT:   *value = tr.lost_dunne[u]; break;
+        case SWMM_GW2D_SPL_ET_OUT:      *value = tr.lost_et[u]; break;
+        case SWMM_GW2D_SPL_REACTED:     *value = tr.lost_reaction[u]; break;
+        case SWMM_GW2D_SPL_RESIDUAL:    *value = tr.residual(species); break;
+        default: return SWMM_ERR_BADPARAM;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_continuity_error(SWMM_Engine engine,
+                                                   double* value) {
+    AQ_SOLVER(engine);
+    if (!value) return SWMM_ERR_BADPARAM;
+    const auto& st = gw.state();
+    // In: infiltration from the surface, and lateral inflow across the domain
+    // boundary (net, already signed). Out: deep loss, node exchange, ET and
+    // saturation excess handed back to the surface. Recharge and capillary
+    // rise are INTERNAL — they move water between the two zones of the same
+    // cell — so they do not appear here, and a residual that scales with them
+    // means the handover is wrong, not the boundary.
+    //
+    // The storage term is `ledgeredStorage`, NOT `liveStorage`, and the
+    // difference is the whole correctness of this number. Every ledger term is
+    // written at the cell's own firing, so the two surface accumulators are
+    // always a step out of phase with it:
+    //
+    //   xacc_from_surface  water the surface has handed over, which
+    //                      `led_infil_in` does not count until the cell
+    //                      gathers it;
+    //   xacc_to_surface    water `led_dunne` counted as OUT the moment it was
+    //                      pushed, which the surface has not drained yet.
+    //
+    // Write out storage_now = state + eacc + P_in + P_out and the true
+    // inflow = led_infil_in + P_in, true outflow = led_dunne − P_out, and both
+    // pending terms cancel exactly — leaving state + eacc against the ledger
+    // as written. Using holdings here instead reports a leak of P_in + P_out,
+    // which on a steadily infiltrating deck is a permanent non-zero residual
+    // for a kernel that is conserving to machine precision.
+    (void)st;
+    *value = gw.state().continuityResidual();   // G-O: one definition, shared
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw2d_get_tier_histogram(SWMM_Engine engine, long* out,
+                                                 int len, int* written) {
+    AQ_SOLVER(engine);
+    if (!out || len <= 0) return SWMM_ERR_BADPARAM;
+    const auto& f = gw.tierFirings();
+    const int n = std::min(len, static_cast(f.size()));
+    for (int i = 0; i < n; ++i) out[i] = f[static_cast(i)];
+    if (written) *written = n;
+    return SWMM_OK;
+}
+
+}  // extern "C"
diff --git a/src/engine/2d/api/ApiGwTransport.cpp b/src/engine/2d/api/ApiGwTransport.cpp
new file mode 100644
index 000000000..df1355f52
--- /dev/null
+++ b/src/engine/2d/api/ApiGwTransport.cpp
@@ -0,0 +1,585 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ApiGwTransport.cpp
+ * @brief U4 — implementation of openswmm_gw_transport.h.
+ *
+ * @details Every setter parses through the SAME line parsers the `.inp`
+ *          sections use, so the API and the file can never drift: an option
+ *          the file refuses the API refuses, with the same message shape.
+ *          The rows live on SurfaceRouter2D (via `ctx.twod_io.gw`), so a
+ *          save re-emits exactly what the API wrote.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+
+#include "../../core/SWMMEngine.hpp"
+#include "../gw/GwTransportSections.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace {
+
+using openswmm::twoD::GwBoundaryQualityRow;
+using openswmm::twoD::GwInitialQualityRow;
+using openswmm::twoD::GwParamsRow;
+using openswmm::twoD::GwScope;
+using openswmm::twoD::GwSorptionRow;
+using openswmm::twoD::GwSourceRow;
+using openswmm::twoD::GwSourceSpeciesTerm;
+using openswmm::twoD::GwTransportData;
+using openswmm::twoD::GwZone;
+
+void copy_to(const std::string& src, char* buf, int len) {
+    if (!buf || len <= 0) return;
+    const int n = std::min(static_cast(src.size()), len - 1);
+    std::memcpy(buf, src.c_str(), static_cast(n));
+    buf[n] = '\0';
+}
+
+GwScope toScope(int s) {
+    switch (s) {
+        case SWMM_GW_SCOPE_TAG:  return GwScope::TAG;
+        case SWMM_GW_SCOPE_CELL: return GwScope::CELL;
+        default:                 return GwScope::GLOBAL;
+    }
+}
+int fromScope(GwScope s) { return static_cast(s); }
+
+GwZone toZone(int z) {
+    switch (z) {
+        case SWMM_GW_ZONE_UNSAT: return GwZone::UNSAT;
+        case SWMM_GW_ZONE_LAYER: return GwZone::LAYER;
+        default:                 return GwZone::SAT;
+    }
+}
+
+}  // namespace
+
+// GW rows are authoring state on the parsed model, so the guard is the
+// editable-state one (BUILDING/OPENED), matching the 2D BC and infiltration
+// APIs. No mesh is required: a host may author options before meshing.
+#define GW_GET(engine) \
+    auto* eng = reinterpret_cast(engine); \
+    if (!eng) return SWMM_ERR_BADHANDLE; \
+    GwTransportData& gw = eng->surfaceRouter2D().gwTransport()
+
+#define GW_EDITABLE(eng) \
+    if (eng->context().state != openswmm::EngineState::OPENED && \
+        eng->context().state != openswmm::EngineState::BUILDING) \
+        return SWMM_ERR_LIFECYCLE
+
+extern "C" {
+
+// ---------------------------------------------------------------------------
+// [GW_TRANSPORT_OPTIONS]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_transport_option_get(SWMM_Engine engine,
+        const char* key, char* buf, int buflen) {
+    GW_GET(engine);
+    if (!key || !buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& o = gw.options;
+    const std::string k(key);
+    auto yn = [](bool b) { return std::string(b ? "YES" : "NO"); };
+    std::string v;
+    if      (k == "TRANSPORT_POLLUTANTS")  v = yn(o.transport_pollutants);
+    else if (k == "TRANSPORT_MSX")         v = yn(o.transport_msx);
+    else if (k == "TRANSPORT_AGE")         v = yn(o.transport_age);
+    else if (k == "TRANSPORT_TEMPERATURE") v = yn(o.transport_temperature);
+    else if (k == "DISPERSION")            v = yn(o.dispersion);
+    else if (k == "CONDUCTION")            v = yn(o.conduction);
+    else if (k == "THERMAL_MIXING")        v = o.thermal_mixing;
+    else if (k == "SURFACE_THERMAL_BC")
+        v = o.surface_thermal_arg.empty()
+                ? o.surface_thermal_bc
+                : o.surface_thermal_bc + " " + o.surface_thermal_arg;
+    else if (k == "DEEP_THERMAL_BC") {
+        v = o.deep_thermal_bc;
+        if (!o.deep_thermal_arg.empty()) v += " " + o.deep_thermal_arg;
+        if (o.deep_depth > 0.0) {
+            char d[64];
+            std::snprintf(d, sizeof d, " DEPTH %.12g", o.deep_depth);
+            v += d;
+        }
+    } else if (k == "C_DIFF") {
+        char d[64];
+        std::snprintf(d, sizeof d, "%.12g", o.c_diff);
+        v = d;
+    } else {
+        return SWMM_ERR_BADPARAM;
+    }
+    copy_to(v, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_transport_option_set(SWMM_Engine engine,
+        const char* key, const char* value) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!key || !value) return SWMM_ERR_BADPARAM;
+    // Route through the file parser so the API and the section agree on
+    // every accepted spelling — including the multi-token thermal BCs.
+    std::vector tokens{key};
+    std::string cur;
+    for (const char* p = value; *p; ++p) {
+        if (std::isspace(static_cast(*p))) {
+            if (!cur.empty()) { tokens.push_back(cur); cur.clear(); }
+        } else {
+            cur += *p;
+        }
+    }
+    if (!cur.empty()) tokens.push_back(cur);
+    // Commit only on success: the parser assigns before validating the
+    // trailing arguments, so a rejected set must not leave a half-edit.
+    auto tmp = gw.options;
+    if (!openswmm::twoD::parseGwTransportOptionsLine(tokens, tmp).empty())
+        return SWMM_ERR_BADPARAM;
+    tmp.authored = true;
+    gw.options = tmp;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_transport_authored(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return 0;
+    return eng->surfaceRouter2D().gwTransport().empty() ? 0 : 1;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_TRANSPORT_PARAMS]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_params_count(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    return static_cast(eng->surfaceRouter2D().gwTransport().params.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_params_get(SWMM_Engine engine, int idx,
+        SWMM_GwParams* row, char* tag_buf, int tag_len) {
+    GW_GET(engine);
+    if (!row) return SWMM_ERR_BADPARAM;
+    if (idx < 0 || idx >= static_cast(gw.params.size())) return SWMM_ERR_BADINDEX;
+    const auto& r = gw.params[static_cast(idx)];
+    row->scope    = fromScope(r.scope);
+    row->cell     = r.cell;
+    row->rho_s    = r.rho_s;
+    row->c_s      = r.c_s;
+    row->lambda_s = r.lambda_s;
+    row->a_s      = r.a_s;
+    row->alpha_L  = r.alpha_L;
+    row->alpha_T  = r.alpha_T;
+    row->D_m      = r.D_m;
+    row->D_v      = r.D_v;
+    row->geo_flux = r.geo_flux;
+    copy_to(r.tag, tag_buf, tag_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_params_set(SWMM_Engine engine,
+        const SWMM_GwParams* row, const char* tag) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!row) return SWMM_ERR_BADPARAM;
+    GwParamsRow r;
+    r.scope = toScope(row->scope);
+    r.tag   = (r.scope == GwScope::TAG && tag) ? tag : "";
+    r.cell  = (r.scope == GwScope::CELL) ? row->cell : -1;
+    if (r.scope == GwScope::TAG && r.tag.empty()) return SWMM_ERR_BADPARAM;
+    if (r.scope == GwScope::CELL && r.cell < 0)   return SWMM_ERR_BADINDEX;
+    r.rho_s = row->rho_s; r.c_s = row->c_s; r.lambda_s = row->lambda_s;
+    r.a_s = row->a_s; r.alpha_L = row->alpha_L; r.alpha_T = row->alpha_T;
+    r.D_m = row->D_m; r.D_v = row->D_v; r.geo_flux = row->geo_flux;
+    for (auto& e : gw.params)
+        if (e.scope == r.scope && e.tag == r.tag && e.cell == r.cell) {
+            e = r;
+            gw.options.authored = true;
+            return SWMM_OK;
+        }
+    gw.params.push_back(std::move(r));
+    gw.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_params_remove(SWMM_Engine engine, int idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (idx < 0 || idx >= static_cast(gw.params.size())) return SWMM_ERR_BADINDEX;
+    gw.params.erase(gw.params.begin() + idx);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_SORPTION]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_sorption_count(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    return static_cast(eng->surfaceRouter2D().gwTransport().sorption.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_sorption_get(SWMM_Engine engine, int idx,
+        int* scope, char* tag_buf, int tag_len, int* cell,
+        char* species_buf, int species_len, double* kd, double* decay) {
+    GW_GET(engine);
+    if (idx < 0 || idx >= static_cast(gw.sorption.size())) return SWMM_ERR_BADINDEX;
+    const auto& r = gw.sorption[static_cast(idx)];
+    if (scope) *scope = fromScope(r.scope);
+    if (cell)  *cell  = r.cell;
+    if (kd)    *kd    = r.kd;
+    if (decay) *decay = r.decay;
+    copy_to(r.tag, tag_buf, tag_len);
+    copy_to(r.species, species_buf, species_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_sorption_set(SWMM_Engine engine, int scope,
+        const char* tag, int cell, const char* species, double kd, double decay) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!species || !*species || kd < 0.0) return SWMM_ERR_BADPARAM;
+    GwSorptionRow r;
+    r.scope   = toScope(scope);
+    r.tag     = (r.scope == GwScope::TAG && tag) ? tag : "";
+    r.cell    = (r.scope == GwScope::CELL) ? cell : -1;
+    r.species = species;
+    r.kd      = kd;
+    r.decay   = decay;
+    if (r.scope == GwScope::TAG && r.tag.empty()) return SWMM_ERR_BADPARAM;
+    if (r.scope == GwScope::CELL && r.cell < 0)   return SWMM_ERR_BADINDEX;
+    for (auto& e : gw.sorption)
+        if (e.scope == r.scope && e.tag == r.tag && e.cell == r.cell &&
+            e.species == r.species) {
+            e = r;
+            gw.options.authored = true;
+            return SWMM_OK;
+        }
+    gw.sorption.push_back(std::move(r));
+    gw.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_sorption_remove(SWMM_Engine engine, int idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (idx < 0 || idx >= static_cast(gw.sorption.size())) return SWMM_ERR_BADINDEX;
+    gw.sorption.erase(gw.sorption.begin() + idx);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_INITIAL_QUALITY]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_init_quality_count(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    return static_cast(
+        eng->surfaceRouter2D().gwTransport().initial_quality.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_init_quality_get(SWMM_Engine engine, int idx,
+        int* scope, char* tag_buf, int tag_len, int* cell,
+        int* zone, int* layer, char* species_buf, int species_len, double* value) {
+    GW_GET(engine);
+    if (idx < 0 || idx >= static_cast(gw.initial_quality.size()))
+        return SWMM_ERR_BADINDEX;
+    const auto& r = gw.initial_quality[static_cast(idx)];
+    if (scope) *scope = fromScope(r.scope);
+    if (cell)  *cell  = r.cell;
+    if (zone)  *zone  = static_cast(r.zone);
+    if (layer) *layer = r.layer;
+    if (value) *value = r.value;
+    copy_to(r.tag, tag_buf, tag_len);
+    copy_to(r.species, species_buf, species_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_init_quality_set(SWMM_Engine engine, int scope,
+        const char* tag, int cell, int zone, int layer,
+        const char* species, double value) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!species || !*species) return SWMM_ERR_BADPARAM;
+    GwInitialQualityRow r;
+    r.scope   = toScope(scope);
+    r.tag     = (r.scope == GwScope::TAG && tag) ? tag : "";
+    r.cell    = (r.scope == GwScope::CELL) ? cell : -1;
+    r.zone    = toZone(zone);
+    r.layer   = (r.zone == GwZone::LAYER) ? layer : -1;
+    r.species = species;
+    r.value   = value;
+    if (r.scope == GwScope::TAG && r.tag.empty()) return SWMM_ERR_BADPARAM;
+    if (r.scope == GwScope::CELL && r.cell < 0)   return SWMM_ERR_BADINDEX;
+    if (r.zone == GwZone::LAYER && r.layer < 1)   return SWMM_ERR_BADPARAM;
+    // A concentration may not be negative; the reserved species may.
+    if (value < 0.0 && r.species != "__TEMPERATURE__" &&
+        r.species != "__WATER_AGE__")
+        return SWMM_ERR_BADPARAM;
+    for (auto& e : gw.initial_quality)
+        if (e.scope == r.scope && e.tag == r.tag && e.cell == r.cell &&
+            e.zone == r.zone && e.layer == r.layer && e.species == r.species) {
+            e.value = r.value;
+            gw.options.authored = true;
+            return SWMM_OK;
+        }
+    gw.initial_quality.push_back(std::move(r));
+    gw.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_init_quality_remove(SWMM_Engine engine, int idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (idx < 0 || idx >= static_cast(gw.initial_quality.size()))
+        return SWMM_ERR_BADINDEX;
+    gw.initial_quality.erase(gw.initial_quality.begin() + idx);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_init_quality_file_get(SWMM_Engine engine,
+        char* buf, int buflen) {
+    GW_GET(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    copy_to(gw.initial_quality_file, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_init_quality_file_set(SWMM_Engine engine,
+        const char* path) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    gw.initial_quality_file = path ? path : "";
+    if (!gw.initial_quality_file.empty()) gw.options.authored = true;
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_BOUNDARY_QUALITY]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_boundary_quality_count(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    return static_cast(
+        eng->surfaceRouter2D().gwTransport().boundary_quality.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_boundary_quality_get(SWMM_Engine engine, int idx,
+        int* cell, int* edge, char* species_buf, int species_len,
+        char* kind_buf, int kind_len, double* value, char* ts_buf, int ts_len) {
+    GW_GET(engine);
+    if (idx < 0 || idx >= static_cast(gw.boundary_quality.size()))
+        return SWMM_ERR_BADINDEX;
+    const auto& r = gw.boundary_quality[static_cast(idx)];
+    if (cell)  *cell  = r.cell;
+    if (edge)  *edge  = r.edge;
+    if (value) *value = r.value;
+    copy_to(r.species, species_buf, species_len);
+    copy_to(r.kind, kind_buf, kind_len);
+    copy_to(r.ts_name, ts_buf, ts_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_boundary_quality_set(SWMM_Engine engine,
+        int cell, int edge, const char* species, const char* kind,
+        double value, const char* ts_name) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!species || !*species || !kind || cell < 0 || edge < 0)
+        return SWMM_ERR_BADPARAM;
+    const std::string k(kind);
+    if (k != "CONC" && k != "TS" && k != "MASSFLUX" && k != "HEATFLUX")
+        return SWMM_ERR_BADPARAM;
+    // EDGE is the LOCAL edge of ITS cell — cell-generic: 3 for a triangle,
+    // 4 for a quad. Checked here when the mesh is already in hand; the
+    // resolve pass checks it again for file-authored rows.
+    const auto& mesh = eng->surfaceRouter2D().mesh();
+    if (mesh.n_cells() > 0) {
+        if (cell >= mesh.n_cells()) return SWMM_ERR_BADINDEX;
+        if (edge >= static_cast(mesh.cell_nv[static_cast(cell)]))
+            return SWMM_ERR_BADINDEX;
+    }
+    GwBoundaryQualityRow r;
+    r.cell    = cell;
+    r.edge    = edge;
+    r.species = species;
+    r.kind    = k;
+    r.value   = value;
+    r.ts_name = ts_name ? ts_name : "";
+    if (k == "TS" && r.ts_name.empty()) return SWMM_ERR_BADPARAM;
+    for (auto& e : gw.boundary_quality)
+        if (e.cell == r.cell && e.edge == r.edge && e.species == r.species) {
+            e = r;
+            gw.options.authored = true;
+            return SWMM_OK;
+        }
+    gw.boundary_quality.push_back(std::move(r));
+    gw.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_boundary_quality_remove(SWMM_Engine engine, int idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (idx < 0 || idx >= static_cast(gw.boundary_quality.size()))
+        return SWMM_ERR_BADINDEX;
+    gw.boundary_quality.erase(gw.boundary_quality.begin() + idx);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_SOURCES]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_gw_source_count(SWMM_Engine engine) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    return static_cast(eng->surfaceRouter2D().gwTransport().sources.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_source_get(SWMM_Engine engine, int idx,
+        char* name_buf, int name_len, int* scope, char* tag_buf, int tag_len,
+        int* cell, double* flow, char* flow_ts_buf, int flow_ts_len) {
+    GW_GET(engine);
+    if (idx < 0 || idx >= static_cast(gw.sources.size())) return SWMM_ERR_BADINDEX;
+    const auto& r = gw.sources[static_cast(idx)];
+    if (scope) *scope = fromScope(r.scope);
+    if (cell)  *cell  = r.cell;
+    if (flow)  *flow  = r.flow;
+    copy_to(r.name, name_buf, name_len);
+    copy_to(r.tag, tag_buf, tag_len);
+    copy_to(r.flow_ts, flow_ts_buf, flow_ts_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_source_set(SWMM_Engine engine, const char* name,
+        int scope, const char* tag, int cell, double flow, const char* flow_ts) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (!name || !*name) return SWMM_ERR_BADPARAM;
+    const GwScope sc = toScope(scope);
+    if (sc == GwScope::TAG && (!tag || !*tag)) return SWMM_ERR_BADPARAM;
+    if (sc == GwScope::CELL && cell < 0)       return SWMM_ERR_BADINDEX;
+    for (auto& e : gw.sources)
+        if (e.name == name) {
+            e.scope   = sc;
+            e.tag     = (sc == GwScope::TAG && tag) ? tag : "";
+            e.cell    = (sc == GwScope::CELL) ? cell : -1;
+            e.by_xy   = false;
+            e.flow    = flow;
+            e.flow_ts = flow_ts ? flow_ts : "";
+            gw.options.authored = true;
+            return SWMM_OK;
+        }
+    GwSourceRow r;
+    r.name    = name;
+    r.scope   = sc;
+    r.tag     = (sc == GwScope::TAG && tag) ? tag : "";
+    r.cell    = (sc == GwScope::CELL) ? cell : -1;
+    r.flow    = flow;
+    r.flow_ts = flow_ts ? flow_ts : "";
+    gw.sources.push_back(std::move(r));
+    gw.options.authored = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_source_remove(SWMM_Engine engine, int idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (idx < 0 || idx >= static_cast(gw.sources.size())) return SWMM_ERR_BADINDEX;
+    gw.sources.erase(gw.sources.begin() + idx);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_source_species_count(SWMM_Engine engine, int src_idx) {
+    auto* eng = reinterpret_cast(engine);
+    if (!eng) return -1;
+    const auto& src = eng->surfaceRouter2D().gwTransport().sources;
+    if (src_idx < 0 || src_idx >= static_cast(src.size())) return -1;
+    return static_cast(src[static_cast(src_idx)].species.size());
+}
+
+SWMM_ENGINE_API int swmm_gw_source_species_get(SWMM_Engine engine, int src_idx,
+        int term_idx, char* species_buf, int species_len,
+        char* kind_buf, int kind_len, double* value, char* ts_buf, int ts_len) {
+    GW_GET(engine);
+    if (src_idx < 0 || src_idx >= static_cast(gw.sources.size()))
+        return SWMM_ERR_BADINDEX;
+    const auto& terms = gw.sources[static_cast(src_idx)].species;
+    if (term_idx < 0 || term_idx >= static_cast(terms.size()))
+        return SWMM_ERR_BADINDEX;
+    const auto& t = terms[static_cast(term_idx)];
+    if (value) *value = t.value;
+    copy_to(t.species, species_buf, species_len);
+    copy_to(t.kind, kind_buf, kind_len);
+    copy_to(t.ts_name, ts_buf, ts_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_source_species_set(SWMM_Engine engine, int src_idx,
+        const char* species, const char* kind, double value, const char* ts_name) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (src_idx < 0 || src_idx >= static_cast(gw.sources.size()))
+        return SWMM_ERR_BADINDEX;
+    if (!species || !*species || !kind) return SWMM_ERR_BADPARAM;
+    const std::string k(kind);
+    if (k != "CONC" && k != "MASS") return SWMM_ERR_BADPARAM;
+    auto& terms = gw.sources[static_cast(src_idx)].species;
+    for (auto& t : terms)
+        if (t.species == species) {
+            t.kind    = k;
+            t.value   = value;
+            t.ts_name = ts_name ? ts_name : "";
+            return SWMM_OK;
+        }
+    GwSourceSpeciesTerm t;
+    t.species = species;
+    t.kind    = k;
+    t.value   = value;
+    t.ts_name = ts_name ? ts_name : "";
+    terms.push_back(std::move(t));
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gw_source_species_remove(SWMM_Engine engine,
+        int src_idx, int term_idx) {
+    GW_GET(engine);
+    GW_EDITABLE(eng);
+    if (src_idx < 0 || src_idx >= static_cast(gw.sources.size()))
+        return SWMM_ERR_BADINDEX;
+    auto& terms = gw.sources[static_cast(src_idx)].species;
+    if (term_idx < 0 || term_idx >= static_cast(terms.size()))
+        return SWMM_ERR_BADINDEX;
+    terms.erase(terms.begin() + term_idx);
+    return SWMM_OK;
+}
+
+}  // extern "C"
diff --git a/src/engine/2d/api/ApiInfil2D.cpp b/src/engine/2d/api/ApiInfil2D.cpp
new file mode 100644
index 000000000..7b644aef4
--- /dev/null
+++ b/src/engine/2d/api/ApiInfil2D.cpp
@@ -0,0 +1,440 @@
+/**
+ * @file ApiInfil2D.cpp
+ * @brief C API implementation for 2D per-cell infiltration (plan §5.5.6, I6).
+ *
+ * @details Implements all functions declared in openswmm_infil2d.h. Follows
+ *          Api2D.cpp exactly: the SWMMEngine is extracted from the opaque
+ *          handle, the SurfaceRouter2D is reached through it, and the call is
+ *          delegated — here to the `twoD::Infil2D` the router owns.
+ *
+ *          Two conventions are worth stating once, because both are load-
+ *          bearing and neither is obvious from the signatures:
+ *
+ *          1. **Staleness.** `Infil2D::resolve()` is the only re-entry point
+ *             that rebuilds kernel state, and it rebuilds it for the WHOLE
+ *             mesh while zeroing `cumulative()`. Calling it mid-run would
+ *             discard the Horton/Green-Ampt integration history of every cell
+ *             the caller never touched and desynchronize `cum_depth_` from
+ *             `MassBalance2D::infil_out`. There is no per-cell re-init entry
+ *             point and Infil2D.hpp is a frozen contract, so every parameter
+ *             setter here is *rejected* once the engine has left OPENED —
+ *             `SWMM_ERR_LIFECYCLE`, mirroring the guard the LID/inflow C API
+ *             uses (openswmm_infrastructure_impl.cpp:581).
+ *
+ *          2. **Empty-when-inactive.** `resolvedRows()`, `provenance()` and
+ *             `cumulative()` are EMPTY — not sized `n_triangles` — both before
+ *             resolve() runs and after a resolve() that found no model
+ *             (Infil2D.cpp:312-316, the I7 fast path). Every reader here
+ *             therefore checks the container's own size before indexing and
+ *             degrades to "no infiltration" / zero-fill rather than reading
+ *             out of bounds.
+ *
+ * @ingroup engine_infil2d
+ */
+
+#include 
+#include 
+#include "../../core/SWMMEngine.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+// Helper macros — same shape as Api2D.cpp.
+#define GET_ENGINE(engine) \
+    auto* eng = reinterpret_cast(engine); \
+    if (!eng) return SWMM_ERR_BADHANDLE
+
+// Configuration lives on the parsed mesh, not on an initialized solver, so the
+// infiltration API uses the mesh guard (the state the GUI edits in), not
+// CHECK_2D_ACTIVE.
+#define CHECK_2D_MESH(eng) \
+    auto& router2d = eng->surfaceRouter2D(); \
+    if (router2d.mesh().n_vertices() <= 0) return SWMM_ERR_BADPARAM
+
+#define CHECK_TRI_IDX(idx, router2d) \
+    if ((idx) < 0 || (idx) >= router2d.mesh().n_triangles()) \
+        return SWMM_ERR_BADINDEX
+
+// See note 1 in the file header.
+#define CHECK_EDITABLE(eng) \
+    if (eng->context().state != openswmm::EngineState::OPENED && \
+        eng->context().state != openswmm::EngineState::BUILDING) \
+        return SWMM_ERR_LIFECYCLE
+
+namespace {
+
+using openswmm::InfilModel;
+using openswmm::twoD::Infil2D;
+using openswmm::twoD::Infil2DDest;
+using openswmm::twoD::Infil2DProvenance;
+using openswmm::twoD::Infil2DRow;
+using openswmm::twoD::kInfil2DMaxParams;
+
+/// Map a `SWMM_INFIL2D_*` method code onto `InfilModel`.
+/// @returns False when the code names no method.
+bool toMethod(int code, InfilModel& out) {
+    switch (code) {
+        case SWMM_INFIL2D_HORTON:         out = InfilModel::HORTON;         return true;
+        case SWMM_INFIL2D_MOD_HORTON:     out = InfilModel::MOD_HORTON;     return true;
+        case SWMM_INFIL2D_GREEN_AMPT:     out = InfilModel::GREEN_AMPT;     return true;
+        case SWMM_INFIL2D_MOD_GREEN_AMPT: out = InfilModel::MOD_GREEN_AMPT; return true;
+        case SWMM_INFIL2D_CURVE_NUMBER:   out = InfilModel::CURVE_NUM;      return true;
+        case SWMM_INFIL2D_CONSTANT:       out = InfilModel::CONSTANT;       return true;
+        default:                                                            return false;
+    }
+}
+
+/// Inverse of toMethod.
+int fromMethod(InfilModel m) {
+    switch (m) {
+        case InfilModel::HORTON:         return SWMM_INFIL2D_HORTON;
+        case InfilModel::MOD_HORTON:     return SWMM_INFIL2D_MOD_HORTON;
+        case InfilModel::GREEN_AMPT:     return SWMM_INFIL2D_GREEN_AMPT;
+        case InfilModel::MOD_GREEN_AMPT: return SWMM_INFIL2D_MOD_GREEN_AMPT;
+        case InfilModel::CURVE_NUM:      return SWMM_INFIL2D_CURVE_NUMBER;
+        case InfilModel::CONSTANT:       return SWMM_INFIL2D_CONSTANT;
+    }
+    return SWMM_INFIL2D_HORTON;
+}
+
+/// Convert a caller row into the engine type, validating as we go.
+///
+/// The parameter bounds mirror `validateRow` in Infil2D.cpp (which is file-
+/// local, so it cannot be shared) — rejecting here means the caller learns
+/// immediately instead of at initialize() with a parse-style message. D-I4:
+/// LOST is the only destination this release routes.
+///
+/// @returns SWMM_OK, or SWMM_ERR_BADPARAM naming nothing (the C API has no
+///          message channel; the same row is re-validated by resolve()).
+int toRow(const SWMM_Infil2DRow& in, Infil2DRow& out) {
+    out = Infil2DRow{};
+    if (in.has_method == 0) return SWMM_OK;   // NONE: every other field is moot
+
+    if (!toMethod(in.method, out.method)) return SWMM_ERR_BADPARAM;
+    out.has_method = true;
+
+    for (int k = 0; k < kInfil2DMaxParams; ++k) {
+        if (!std::isfinite(in.p[k])) return SWMM_ERR_BADPARAM;
+        out.p[k] = in.p[k];
+    }
+
+    // D-I4: parse the other destinations, accept only LOST.
+    switch (in.dest) {
+        case SWMM_INFIL2D_DEST_LOST: out.dest = Infil2DDest::LOST; break;
+        case SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER:
+        case SWMM_INFIL2D_DEST_AQUIFER_2D:
+        default:
+            return SWMM_ERR_BADPARAM;
+    }
+
+    switch (out.method) {
+        case InfilModel::HORTON:
+        case InfilModel::MOD_HORTON:
+            if (out.p[0] < 0.0 || out.p[1] < 0.0) return SWMM_ERR_BADPARAM;
+            break;
+        case InfilModel::GREEN_AMPT:
+        case InfilModel::MOD_GREEN_AMPT:
+            if (out.p[1] < 0.0) return SWMM_ERR_BADPARAM;
+            if (out.p[2] < 0.0 || out.p[2] > 1.0) return SWMM_ERR_BADPARAM;
+            break;
+        case InfilModel::CURVE_NUM:
+            if (out.p[0] < 1.0 || out.p[0] > 100.0) return SWMM_ERR_BADPARAM;
+            break;
+        case InfilModel::CONSTANT:
+            if (out.p[0] < 0.0) return SWMM_ERR_BADPARAM;
+            break;
+    }
+    return SWMM_OK;
+}
+
+/// Convert an engine row into the caller's POD.
+void fromRow(const Infil2DRow& in, SWMM_Infil2DRow& out) {
+    out.has_method = in.has_method ? 1 : 0;
+    out.method     = fromMethod(in.method);
+    for (int k = 0; k < kInfil2DMaxParams; ++k) out.p[k] = in.p[k];
+    switch (in.dest) {
+        case Infil2DDest::SUBCATCH_AQUIFER: out.dest = SWMM_INFIL2D_DEST_SUBCATCH_AQUIFER; break;
+        case Infil2DDest::AQUIFER_2D:       out.dest = SWMM_INFIL2D_DEST_AQUIFER_2D;       break;
+        case Infil2DDest::LOST:
+        default:                            out.dest = SWMM_INFIL2D_DEST_LOST;             break;
+    }
+}
+
+/// Drop every per-cell override row for @p tri. Used by both the clear path
+/// and the upsert path so a cell never accumulates two override rows.
+void eraseOverrides(Infil2D& infil, int tri) {
+    auto& v = infil.overrides();
+    std::size_t w = 0;
+    for (std::size_t r = 0; r < v.size(); ++r) {
+        if (v[r].tri == tri) continue;
+        if (w != r) v[w] = v[r];
+        ++w;
+    }
+    v.resize(w);
+}
+
+/// Copy `min(n, count)` doubles out of @p src, zero-filling when @p src is the
+/// empty "no model resolved" container (see note 2 in the file header).
+void fillBulk(double* dst, int n, int count, const std::vector& src) {
+    const int m = (n < count) ? n : count;
+    for (int i = 0; i < m; ++i)
+        dst[i] = (static_cast(i) < src.size())
+               ? src[static_cast(i)]
+               : 0.0;
+}
+
+}  // namespace
+
+extern "C" {
+
+// ============================================================================
+// Options — [2D_INFILTRATION_OPTIONS]
+// ============================================================================
+
+int swmm_infil2d_get_options(SWMM_Engine engine, SWMM_Infil2DOptions* options) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!options) return SWMM_ERR_BADPARAM;
+
+    options->infil_step = router2d.infil().options().infil_step;
+    return SWMM_OK;
+}
+
+int swmm_infil2d_set_options(SWMM_Engine engine,
+                             const SWMM_Infil2DOptions* options) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!options) return SWMM_ERR_BADPARAM;
+    if (!std::isfinite(options->infil_step)) return SWMM_ERR_BADPARAM;
+    CHECK_EDITABLE(eng);
+
+    // <= 0 is the documented "use the project WET_STEP" sentinel, so it is
+    // stored verbatim rather than clamped.
+    router2d.infil().options().infil_step = options->infil_step;
+    return SWMM_OK;
+}
+
+// ============================================================================
+// Tag defaults — [2D_INFILTRATION_DEFAULTS]
+// ============================================================================
+
+int swmm_infil2d_defaults_count(SWMM_Engine engine, int* count) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!count) return SWMM_ERR_BADPARAM;
+
+    *count = static_cast(router2d.infil().defaults().size());
+    return SWMM_OK;
+}
+
+int swmm_infil2d_get_default(SWMM_Engine engine, int idx,
+                             SWMM_Infil2DRow* row) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!row) return SWMM_ERR_BADPARAM;
+
+    const auto& defs = router2d.infil().defaults();
+    if (idx < 0 || idx >= static_cast(defs.size())) return SWMM_ERR_BADINDEX;
+
+    fromRow(defs[static_cast(idx)].row, *row);
+    return SWMM_OK;
+}
+
+int swmm_infil2d_get_default_tag(SWMM_Engine engine, int idx,
+                                 char* buf, int buflen) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+
+    const auto& defs = router2d.infil().defaults();
+    if (idx < 0 || idx >= static_cast(defs.size())) return SWMM_ERR_BADINDEX;
+
+    const std::string& s = defs[static_cast(idx)].tag;
+    const std::size_t n  = (s.size() < static_cast(buflen) - 1)
+                         ? s.size()
+                         : static_cast(buflen) - 1;
+    std::memcpy(buf, s.data(), n);
+    buf[n] = '\0';
+    return SWMM_OK;
+}
+
+int swmm_infil2d_set_default(SWMM_Engine engine, const char* tag,
+                             const SWMM_Infil2DRow* row) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!tag || tag[0] == '\0' || !row) return SWMM_ERR_BADPARAM;
+    CHECK_EDITABLE(eng);
+
+    openswmm::twoD::Infil2DDefault entry;
+    entry.tag = tag;
+    const int rc = toRow(*row, entry.row);
+    if (rc != SWMM_OK) return rc;
+
+    // Upsert: a tag never carries two definitions.
+    auto& defs = router2d.infil().defaults();
+    std::size_t w = 0;
+    for (std::size_t r = 0; r < defs.size(); ++r) {
+        if (defs[r].tag == entry.tag) continue;
+        if (w != r) defs[w] = std::move(defs[r]);
+        ++w;
+    }
+    defs.resize(w);
+    defs.push_back(std::move(entry));
+    return SWMM_OK;
+}
+
+int swmm_infil2d_remove_default(SWMM_Engine engine, const char* tag) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!tag || tag[0] == '\0') return SWMM_ERR_BADPARAM;
+    CHECK_EDITABLE(eng);
+
+    const std::string want(tag);
+    auto& defs = router2d.infil().defaults();
+    std::size_t w = 0;
+    for (std::size_t r = 0; r < defs.size(); ++r) {
+        if (defs[r].tag == want) continue;
+        if (w != r) defs[w] = std::move(defs[r]);
+        ++w;
+    }
+    defs.resize(w);
+    return SWMM_OK;
+}
+
+// ============================================================================
+// Per-cell overrides — [2D_INFILTRATION]
+// ============================================================================
+
+int swmm_infil2d_get_cell(SWMM_Engine engine, int tri,
+                          SWMM_Infil2DRow* row, int* is_override) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(tri, router2d);
+    if (!row) return SWMM_ERR_BADPARAM;
+
+    const Infil2D& infil = router2d.infil();
+    const auto  ui       = static_cast(tri);
+    const auto& resolved = infil.resolvedRows();
+    const auto& prov     = infil.provenance();
+
+    // Resolved path — resolvedRows()/provenance() are sized n_triangles only
+    // once resolve() found at least one model.
+    if (ui < resolved.size() && ui < prov.size()) {
+        fromRow(resolved[ui], *row);
+        if (is_override)
+            *is_override = (prov[ui] == Infil2DProvenance::OVERRIDE) ? 1 : 0;
+        return SWMM_OK;
+    }
+
+    // Unresolved path — only the authored per-cell layer is visible. Last row
+    // wins, matching the order resolve() applies overrides in.
+    fromRow(Infil2DRow{}, *row);
+    if (is_override) *is_override = 0;
+    for (const auto& o : infil.overrides()) {
+        if (o.tri != tri) continue;
+        fromRow(o.row, *row);
+        if (is_override) *is_override = 1;
+    }
+    return SWMM_OK;
+}
+
+int swmm_infil2d_set_cell(SWMM_Engine engine, int tri,
+                          const SWMM_Infil2DRow* row) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    CHECK_TRI_IDX(tri, router2d);
+    CHECK_EDITABLE(eng);
+
+    Infil2D& infil = router2d.infil();
+
+    if (!row) {                       // NULL = clear the override entirely
+        eraseOverrides(infil, tri);
+        return SWMM_OK;
+    }
+
+    openswmm::twoD::Infil2DOverride entry;
+    entry.tri    = tri;
+    const int rc = toRow(*row, entry.row);
+    if (rc != SWMM_OK) return rc;     // validated BEFORE anything is erased
+
+    eraseOverrides(infil, tri);
+    infil.overrides().push_back(std::move(entry));
+    return SWMM_OK;
+}
+
+int swmm_infil2d_set_cells(SWMM_Engine engine, const int* tris, int n,
+                           const SWMM_Infil2DRow* row) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!tris || n <= 0) return SWMM_ERR_BADPARAM;
+    CHECK_EDITABLE(eng);
+
+    // --- one validation pass; nothing is written until it passes ------------
+    Infil2DRow parsed;
+    if (row) {
+        const int rc = toRow(*row, parsed);
+        if (rc != SWMM_OK) return rc;
+    }
+
+    const int nt = router2d.mesh().n_triangles();
+    for (int i = 0; i < n; ++i)
+        if (tris[i] < 0 || tris[i] >= nt) return SWMM_ERR_BADINDEX;
+
+    // --- apply --------------------------------------------------------------
+    Infil2D& infil = router2d.infil();
+    for (int i = 0; i < n; ++i) {
+        eraseOverrides(infil, tris[i]);
+        if (!row) continue;           // NULL row = clear on every listed cell
+        openswmm::twoD::Infil2DOverride entry;
+        entry.tri = tris[i];
+        entry.row = parsed;
+        infil.overrides().push_back(entry);
+    }
+    return SWMM_OK;
+}
+
+// ============================================================================
+// State readback (SI)
+// ============================================================================
+
+int swmm_infil2d_get_rate_bulk(SWMM_Engine engine, double* f, int n) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!f || n <= 0) return SWMM_ERR_BADPARAM;
+
+    // state().infil_rate is allocated with the rest of the surface state, but
+    // is all-zero (and may be empty before initialize()) when no model
+    // resolved — fillBulk covers both.
+    fillBulk(f, n, router2d.mesh().n_triangles(), router2d.state().infil_rate);
+    return SWMM_OK;
+}
+
+int swmm_infil2d_get_cum_bulk(SWMM_Engine engine, double* F, int n) {
+    GET_ENGINE(engine);
+    CHECK_2D_MESH(eng);
+    if (!F || n <= 0) return SWMM_ERR_BADPARAM;
+
+    // The ROUTER's cumulative, not Infil2D::cumulative(): it accumulates the
+    // depth-ramped infilSink() value the solver actually removed, so this
+    // reader agrees with swmm_infil2d_get_total_volume / the ledger. It is
+    // EMPTY, not zero-sized-per-triangle, when no model resolved — fillBulk
+    // zero-fills rather than index it.
+    fillBulk(F, n, router2d.mesh().n_triangles(), router2d.infilCumulative());
+    return SWMM_OK;
+}
+
+int swmm_infil2d_get_total_volume(SWMM_Engine engine, double* volume) {
+    GET_ENGINE(engine);
+    if (!volume) return SWMM_ERR_BADPARAM;
+
+    // Same guard as swmm_2d_get_mass_balance — this reads the same ledger.
+    const auto& mb = eng->context().mass_balance_2d;
+    if (!mb.active) return SWMM_ERR_BADPARAM;
+
+    *volume = mb.infil_out;
+    return SWMM_OK;
+}
+
+}  // extern "C"
diff --git a/src/engine/2d/api/ApiSq2D.cpp b/src/engine/2d/api/ApiSq2D.cpp
new file mode 100644
index 000000000..e1d805cd7
--- /dev/null
+++ b/src/engine/2d/api/ApiSq2D.cpp
@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ApiSq2D.cpp
+ * @brief S7 (2026-09-19) — C API over the 2D surface-quality rows and the
+ *        cell buildup store (openswmm_sq2d.h).
+ *
+ * @details Row edits go through the SAME line parsers the `.inp` sections
+ *          use (`parse2DCoveragesLine` & co.), so the API and the file share
+ *          one grammar, one replace-by-scope rule and one percent check. The
+ *          names a row refers to are validated here against the model's
+ *          land uses and species, which the parsers defer to initialize —
+ *          a host must not be able to build a model the file would refuse.
+ */
+
+#include 
+#include 
+
+#include "../../core/SWMMEngine.hpp"
+#include "../quality/SurfaceQuality2D.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+namespace {
+
+using openswmm::twoD::SqScope;
+using openswmm::twoD::SqScopeKey;
+using openswmm::twoD::SurfaceQuality2D;
+
+void copy_to(const std::string& src, char* buf, int len) {
+    if (!buf || len <= 0) return;
+    const int n = std::min(static_cast(src.size()), len - 1);
+    std::memcpy(buf, src.c_str(), static_cast(n));
+    buf[n] = '\0';
+}
+
+bool scopeTokens(int scope, const char* tag, int cell, std::vector& t) {
+    if (scope == SWMM_SQ2D_SCOPE_GLOBAL) { t.push_back("*"); return true; }
+    if (scope == SWMM_SQ2D_SCOPE_TAG) {
+        if (!tag || tag[0] == '\0') return false;
+        t.push_back("TAG"); t.push_back(tag); return true;
+    }
+    if (scope == SWMM_SQ2D_SCOPE_CELL) {
+        if (cell < 0) return false;
+        t.push_back("CELL"); t.push_back(std::to_string(cell + 1)); return true;
+    }
+    return false;
+}
+
+bool sameKey(const SqScopeKey& a, const SqScopeKey& b) {
+    return a.scope == b.scope && a.tag == b.tag && a.cell == b.cell;
+}
+
+bool isSurfaceSpecies(const openswmm::SimulationContext& ctx, const std::string& name) {
+    if (ctx.pollutant_names.find(name) >= 0) return true;
+    for (const auto& s : ctx.reactions.species_name)
+        if (s == name) return true;
+    return false;
+}
+
+}  // namespace
+
+#define SQ_STORE(engine) \
+    auto* eng = reinterpret_cast(engine); \
+    if (!eng) return SWMM_ERR_BADHANDLE; \
+    SurfaceQuality2D& sq = eng->surfaceRouter2D().surfaceQuality()
+
+#define SQ_EDITABLE(eng) \
+    if (eng->context().state != openswmm::EngineState::OPENED && \
+        eng->context().state != openswmm::EngineState::BUILDING) \
+        return SWMM_ERR_LIFECYCLE
+
+// ---------------------------------------------------------------------------
+// [2D_COVERAGES]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_2d_coverage_count(SWMM_Engine engine, int* count) {
+    SQ_STORE(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = static_cast(sq.coverage_rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_coverage_set(SWMM_Engine engine, int scope,
+                                         const char* tag, int cell,
+                                         const char* const* landuses,
+                                         const double* percents, int n) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    if (n <= 0 || !landuses || !percents) return SWMM_ERR_BADPARAM;
+    std::vector t;
+    if (!scopeTokens(scope, tag, cell, t)) return SWMM_ERR_BADPARAM;
+    for (int i = 0; i < n; ++i) {
+        if (!landuses[i] || eng->context().landuse_names.find(landuses[i]) < 0)
+            return SWMM_ERR_BADPARAM;
+        t.emplace_back(landuses[i]);
+        t.push_back(std::to_string(percents[i]));
+    }
+    return openswmm::twoD::parse2DCoveragesLine(t, sq.coverage_rows).empty()
+               ? SWMM_OK : SWMM_ERR_BADPARAM;
+}
+
+SWMM_ENGINE_API int swmm_2d_coverage_row_size(SWMM_Engine engine, int index, int* n) {
+    SQ_STORE(engine);
+    if (!n || index < 0 || index >= static_cast(sq.coverage_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    *n = static_cast(sq.coverage_rows[static_cast(index)].uses.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_coverage_get(SWMM_Engine engine, int index, int k,
+                                         int* scope, char* tag, int taglen,
+                                         int* cell, char* landuse, int lulen,
+                                         double* percent) {
+    SQ_STORE(engine);
+    if (index < 0 || index >= static_cast(sq.coverage_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& r = sq.coverage_rows[static_cast(index)];
+    if (k < 0 || k >= static_cast(r.uses.size())) return SWMM_ERR_BADPARAM;
+    if (scope)   *scope   = static_cast(r.key.scope);
+    if (cell)    *cell    = r.key.cell;
+    if (tag)     copy_to(r.key.tag, tag, taglen);
+    if (landuse) copy_to(r.uses[static_cast(k)].first, landuse, lulen);
+    if (percent) *percent = r.uses[static_cast(k)].second;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_coverage_remove(SWMM_Engine engine, int index) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(sq.coverage_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    sq.coverage_rows.erase(sq.coverage_rows.begin() + index);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [2D_LOADINGS]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_2d_loading_count(SWMM_Engine engine, int* count) {
+    SQ_STORE(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = static_cast(sq.loading_rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_loading_set(SWMM_Engine engine, int scope,
+                                        const char* tag, int cell,
+                                        const char* species, double value) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    if (!species || !isSurfaceSpecies(eng->context(), species)) return SWMM_ERR_BADPARAM;
+    std::vector t;
+    if (!scopeTokens(scope, tag, cell, t)) return SWMM_ERR_BADPARAM;
+    t.emplace_back(species);
+    t.push_back(std::to_string(value));
+    std::vector one;
+    if (!openswmm::twoD::parse2DLoadingsLine(t, one).empty()) return SWMM_ERR_BADPARAM;
+    one.front().value = value;   // the exact double, not its text
+    auto& rows = sq.loading_rows;
+    rows.erase(std::remove_if(rows.begin(), rows.end(), [&](const openswmm::twoD::LoadingRow2D& o) {
+        return sameKey(o.key, one.front().key) && o.species == one.front().species;
+    }), rows.end());
+    rows.push_back(std::move(one.front()));
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_loading_get(SWMM_Engine engine, int index,
+                                        int* scope, char* tag, int taglen,
+                                        int* cell, char* species, int splen,
+                                        double* value) {
+    SQ_STORE(engine);
+    if (index < 0 || index >= static_cast(sq.loading_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& r = sq.loading_rows[static_cast(index)];
+    if (scope)   *scope = static_cast(r.key.scope);
+    if (cell)    *cell  = r.key.cell;
+    if (tag)     copy_to(r.key.tag, tag, taglen);
+    if (species) copy_to(r.species, species, splen);
+    if (value)   *value = r.value;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_loading_remove(SWMM_Engine engine, int index) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(sq.loading_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    sq.loading_rows.erase(sq.loading_rows.begin() + index);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// [2D_CURB_LENGTH]
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_2d_curb_length_count(SWMM_Engine engine, int* count) {
+    SQ_STORE(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    *count = static_cast(sq.curb_rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_curb_length_set(SWMM_Engine engine, int scope,
+                                            const char* tag, int cell,
+                                            double length) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    std::vector t;
+    if (!scopeTokens(scope, tag, cell, t)) return SWMM_ERR_BADPARAM;
+    t.push_back(std::to_string(length));
+    std::vector one;
+    if (!openswmm::twoD::parse2DCurbLengthLine(t, one).empty()) return SWMM_ERR_BADPARAM;
+    one.front().length = length;
+    auto& rows = sq.curb_rows;
+    rows.erase(std::remove_if(rows.begin(), rows.end(), [&](const openswmm::twoD::CurbRow2D& o) {
+        return sameKey(o.key, one.front().key);
+    }), rows.end());
+    rows.push_back(std::move(one.front()));
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_curb_length_get(SWMM_Engine engine, int index,
+                                            int* scope, char* tag, int taglen,
+                                            int* cell, double* length) {
+    SQ_STORE(engine);
+    if (index < 0 || index >= static_cast(sq.curb_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    const auto& r = sq.curb_rows[static_cast(index)];
+    if (scope)  *scope  = static_cast(r.key.scope);
+    if (cell)   *cell   = r.key.cell;
+    if (tag)    copy_to(r.key.tag, tag, taglen);
+    if (length) *length = r.length;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_2d_curb_length_remove(SWMM_Engine engine, int index) {
+    SQ_STORE(engine);
+    SQ_EDITABLE(eng);
+    if (index < 0 || index >= static_cast(sq.curb_rows.size()))
+        return SWMM_ERR_BADPARAM;
+    sq.curb_rows.erase(sq.curb_rows.begin() + index);
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// Buildup store
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_2d_get_buildup_bulk(SWMM_Engine engine,
+                                             const char* species,
+                                             double* out, int n) {
+    SQ_STORE(engine);
+    if (!species || !out) return SWMM_ERR_BADPARAM;
+    if (!sq.active()) return SWMM_ERR_LIFECYCLE;
+    if (n < sq.nCells()) return SWMM_ERR_BADPARAM;
+    int s = -1;
+    for (int i = 0; i < sq.nSpecies(); ++i)
+        if (sq.speciesName(i) == species) { s = i; break; }
+    if (s < 0) return SWMM_ERR_BADPARAM;
+    for (int c = 0; c < sq.nCells(); ++c) out[c] = sq.buildupPerArea(c, s);
+    return SWMM_OK;
+}
diff --git a/src/engine/2d/coupling/NodeCoupling.cpp b/src/engine/2d/coupling/NodeCoupling.cpp
index f23adc12e..bb465a46a 100644
--- a/src/engine/2d/coupling/NodeCoupling.cpp
+++ b/src/engine/2d/coupling/NodeCoupling.cpp
@@ -66,13 +66,29 @@ inline double effectiveArea(double h_max, double z_ground, double full_depth,
 /// (conservative; totalExchangeFlow() unchanged). On a flat surface (Σw ≈ 0) —
 /// or when no cell lies in the upwind direction — fall back to the geometric
 /// partition-of-unity weights the head reconstruction uses (vert_stencil_wt).
+///
+/// S3: when `conc` (length = transport.n_species) is given and Q > 0, the
+/// same share q/area that goes into coupling_flux also goes into
+/// transport.coupling_src[s][cell] × conc[s] — the species mass-rate density
+/// riding this source, so the marcher adds mass beside volume with one rule.
 inline void scatterCouplingFlux(const MeshData& mesh, SurfaceStateData& state,
-                                const CouplingPoint& cp, double Q) noexcept {
+                                const CouplingPoint& cp, double Q,
+                                const double* conc = nullptr) noexcept {
+    auto& tr = state.transport;
+    const bool with_species =
+        conc && Q > 0.0 && tr.active() && !tr.coupling_src.empty();
+    auto add = [&](int cell, double q_share) {
+        const double area = mesh.tri_area[cell];
+        if (!(area > 1.0e-30)) return;
+        const double dens = q_share / area;
+        state.coupling_flux[cell] += dens;
+        if (with_species)
+            for (int s = 0; s < tr.n_species; ++s)
+                tr.coupling_src[tr.idx(s, cell)] += dens * conc[s];
+    };
     // Triangle coupling: single cell, head and flux already co-located.
     if (cp.vertex_idx < 0) {
-        int ci = cp.cell_idx;
-        double area = mesh.tri_area[ci];
-        if (area > 1.0e-30) state.coupling_flux[ci] += Q / area;
+        add(cp.cell_idx, Q);
         return;
     }
 
@@ -107,16 +123,12 @@ inline void scatterCouplingFlux(const MeshData& mesh, SurfaceStateData& state,
             if (d < 1.0e-9) continue;
             double slope = sign * (hv - state.head[kc]) / d;
             if (slope <= 0.0) continue;
-            double area = mesh.tri_area[kc];
-            if (area > 1.0e-30)
-                state.coupling_flux[kc] += (Q * (slope / wsum)) / area;
+            add(kc, Q * (slope / wsum));
         }
     } else {
         for (int k = start; k < end; ++k) {
             int kc = mesh.vert_stencil_idx[k];
-            double area = mesh.tri_area[kc];
-            if (area > 1.0e-30)
-                state.coupling_flux[kc] += (Q * mesh.vert_stencil_wt[k]) / area;
+            add(kc, Q * mesh.vert_stencil_wt[k]);
         }
     }
 }
@@ -363,6 +375,23 @@ std::vector buildCouplingPoints(const MeshData& mesh,
 
     // Vertex-to-node couplings
     int nv = mesh.n_vertices();
+    // First cell (lowest index) touching each vertex, built once in
+    // O(n_cells·nv). The per-coupling scan of every cell this replaces was
+    // O(n_couplings × n_cells): 0.05 → 0.36 s of the Bellinge start-up after
+    // the nv-generic rewrite (2D_PERF_REGRESSION_DIAGNOSIS). Same answer:
+    // the lowest cell index containing the vertex.
+    std::vector first_cell_of_vertex(static_cast(nv), -1);
+    {
+        const int nt_all = mesh.n_triangles();
+        for (int t = 0; t < nt_all; ++t) {
+            const int nvc = mesh.cell_vertex_count(t);
+            for (int k = 0; k < nvc; ++k) {
+                const int vv = mesh.cell_vertex(t, k);
+                if (vv >= 0 && vv < nv && first_cell_of_vertex[static_cast(vv)] < 0)
+                    first_cell_of_vertex[static_cast(vv)] = t;
+            }
+        }
+    }
     for (int v = 0; v < nv; ++v) {
         int node_idx = mesh.vert_coupled_node[v];
         if (node_idx < 0) continue;
@@ -378,14 +407,7 @@ std::vector buildCouplingPoints(const MeshData& mesh,
 
         // Find the triangle that contains this vertex (use first one)
         // The coupling flux is distributed to triangles sharing this vertex
-        cp.cell_idx = -1;
-        int nt = mesh.n_triangles();
-        for (int t = 0; t < nt; ++t) {
-            if (mesh.tri_v0[t] == v || mesh.tri_v1[t] == v || mesh.tri_v2[t] == v) {
-                cp.cell_idx = t;
-                break;
-            }
-        }
+        cp.cell_idx = first_cell_of_vertex[static_cast(v)];
         if (cp.cell_idx < 0) continue;
 
         auto ui = static_cast(node_idx);
@@ -650,12 +672,22 @@ void injectAccumulatedExchange(const std::vector& cps,
                                SurfaceStateData& state,
                                const std::vector& accum_m3,
                                double window_dt,
-                               double sign) {
+                               double sign,
+                               const std::vector* node_conc) {
     if (window_dt <= 0.0) return;
+    const auto ns = static_cast(state.transport.n_species);
     for (std::size_t k = 0; k < cps.size(); ++k) {
         const double vol = accum_m3[k];
         if (vol == 0.0) continue;
-        scatterCouplingFlux(mesh, state, cps[k], sign * vol / window_dt);
+        // S3: a 2D-source (positive after sign) carries the NODE's published
+        // concentration — for an outfall, the concentration of what the 1D
+        // network discharged. Only when the row exists at this stride.
+        const double* conc = nullptr;
+        if (node_conc && ns > 0 && cps[k].node_idx >= 0) {
+            const auto ni = static_cast(cps[k].node_idx);
+            if ((ni + 1) * ns <= node_conc->size()) conc = &(*node_conc)[ni * ns];
+        }
+        scatterCouplingFlux(mesh, state, cps[k], sign * vol / window_dt, conc);
     }
 }
 
diff --git a/src/engine/2d/coupling/NodeCoupling.hpp b/src/engine/2d/coupling/NodeCoupling.hpp
index be5c63a0d..2c03801e2 100644
--- a/src/engine/2d/coupling/NodeCoupling.hpp
+++ b/src/engine/2d/coupling/NodeCoupling.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NodeCoupling.hpp
  * @brief Orifice-equation exchange between 2D surface and SWMM nodes.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_NODE_COUPLING_HPP
@@ -122,13 +138,20 @@ int accumulateOutfallDischargeStep(const std::vector& cps,
  *          −1: accum is 2D→1D-drain-positive, e.g. junction exchange, so the
  *          2D-side source is its negation). coupling_flux is NOT cleared here —
  *          callers zero it once before injecting both accumulators.
+ *
+ * @param node_conc S3 (nullable): the 1D nodes' published concentrations,
+ *                  flat `[node * n_species + s]` with the 2D transport
+ *                  stride. When given, each 2D-source volume also scatters
+ *                  `transport.coupling_src` at the point's node concentration
+ *                  (callers clear coupling_src alongside coupling_flux).
  */
 void injectAccumulatedExchange(const std::vector& cps,
                                const MeshData& mesh,
                                SurfaceStateData& state,
                                const std::vector& accum_m3,
                                double window_dt,
-                               double sign);
+                               double sign,
+                               const std::vector* node_conc = nullptr);
 
 /**
  * @brief Live node-coupling orifice flux for ONE non-outfall coupling point.
diff --git a/src/engine/2d/data/BoundaryData.hpp b/src/engine/2d/data/BoundaryData.hpp
index 1a35faa38..f805b73c8 100644
--- a/src/engine/2d/data/BoundaryData.hpp
+++ b/src/engine/2d/data/BoundaryData.hpp
@@ -1,10 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file BoundaryData.hpp
  * @brief Structure-of-Arrays (SoA) storage for 2D mesh boundary conditions.
  *
  * @details Stores per-edge boundary condition type, parameters, and cumulative
- *          flux tracking. Arrays are flat 2D [tri * 3 + edge_local], sized to
- *          n_triangles * 3 (matching edge_flux, edge_length, etc.).
+ *          flux tracking. Arrays are flat 2D [cell * kMaxCellVerts + edge_local],
+ *          sized to n_cells * kMaxCellVerts (matching edge_flux, edge_length, etc.).
  *
  *          Boundary types:
  *          - WALL: Zero-flux (default). No water crosses the boundary.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_BOUNDARY_DATA_HPP
@@ -48,7 +64,7 @@ enum class BoundaryType : int8_t {
 /**
  * @brief SoA storage for per-edge boundary conditions.
  *
- * All arrays are flat 2D: indexed as [tri * 3 + edge_local] where
+ * All arrays are flat 2D: indexed as [cell * kMaxCellVerts + edge_local] where
  * edge_local ∈ {0,1,2}. Only meaningful for boundary edges (tri_nbr == -1),
  * but allocated for all edges to avoid indirection in the flux loop.
  */
@@ -112,7 +128,7 @@ struct BoundaryData {
 
     /**
      * @brief Resize all arrays to n_edges and initialize to WALL defaults.
-     * @param n_edges Total number of edge slots (n_triangles * 3).
+     * @param n_edges Total number of edge slots (n_cells * kMaxCellVerts).
      */
     void resize(int n_edges) {
         auto n = static_cast(n_edges);
diff --git a/src/engine/2d/data/MeshData.hpp b/src/engine/2d/data/MeshData.hpp
index 626b5639e..2a2565247 100644
--- a/src/engine/2d/data/MeshData.hpp
+++ b/src/engine/2d/data/MeshData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file MeshData.hpp
  * @brief Structure-of-Arrays (SoA) storage for 2D triangular mesh geometry.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_MESH_DATA_HPP
@@ -24,12 +40,29 @@
 
 namespace openswmm::twoD {
 
+/// Maximum vertices (and therefore edge slots) per cell. The mesh is a mixed
+/// triangle / convex-quadrilateral mesh (2D_TRI_QUAD_MESH_PLAN_2026-09-06):
+/// every per-cell connectivity and edge SoA is padded to this fixed stride so
+/// the flat `[cell * kMaxCellVerts + k]` addressing the solvers, the C API,
+/// the HDF5 layout and the GUI all share stays a plain stride, never a CSR.
+/// Slots k ≥ cell_nv[c] are padding (vertex −1, neighbour −2, zero geometry).
+inline constexpr int kMaxCellVerts = 4;
+
 /**
- * @brief SoA storage for 2D triangular mesh geometry and topology.
+ * @brief SoA storage for 2D mixed triangle/quad mesh geometry and topology.
  *
  * All vertex arrays are indexed by vertex index [0, n_vertices).
- * All triangle arrays are indexed by triangle index [0, n_triangles).
- * Edge arrays are flat 2D: [tri * 3 + edge_local] for edge_local in {0,1,2}.
+ * All cell arrays are indexed by cell index [0, n_triangles()) — the
+ * historical `tri_*` names are kept for the per-cell scalar arrays; a "tri"
+ * is any cell (triangle or quad). Cells are ordered triangles first, then
+ * quads (the `[2D_TRIANGLES]` rows, then the `[2D_QUADS]` rows).
+ * Edge / connectivity arrays are flat 2D: [cell * kMaxCellVerts + k] for
+ * k in [0, cell_nv[cell]).
+ *
+ * Local-edge convention (unified for both shapes): edge k has endpoints
+ * `v[(k+1) % nv], v[(k+2) % nv]`. For a triangle this is the historical
+ * "edge k is opposite vertex k" rule, so every existing `TRI EDGE` row keeps
+ * its meaning; for a quad it is a fixed rotation of the natural numbering.
  */
 struct MeshData {
 
@@ -43,34 +76,48 @@ struct MeshData {
     std::vector vtag;      ///< Optional vertex tag
 
     // -----------------------------------------------------------------------
-    // Triangle static properties — indexed by triangle index [0, n_triangles)
+    // Cell static properties — indexed by cell index [0, n_triangles())
     // -----------------------------------------------------------------------
 
-    // Connectivity (3 vertex indices per triangle)
-    std::vector tri_v0;            ///< Vertex 0 index
-    std::vector tri_v1;            ///< Vertex 1 index
-    std::vector tri_v2;            ///< Vertex 2 index
-
-    // Neighbour connectivity (3 adjacent triangle indices, -1 = boundary)
-    std::vector tri_nbr0;          ///< Neighbour across edge opposite v0
-    std::vector tri_nbr1;          ///< Neighbour across edge opposite v1
-    std::vector tri_nbr2;          ///< Neighbour across edge opposite v2
+    /// Vertices per cell: 3 (triangle) or 4 (quadrilateral).
+    std::vector cell_nv;
+    /// Connectivity, padded: [cell * kMaxCellVerts + k]; −1 in padding slots.
+    /// Counter-clockwise order (MeshBuilder orients the outward normals from
+    /// the centroid, so a clockwise triangle still works; quads are validated
+    /// CCW + convex at parse time).
+    std::vector cell_v;
+    /// Neighbour across local edge k, padded: [cell * kMaxCellVerts + k].
+    /// −1 = boundary edge, −2 = padding slot (k ≥ cell_nv).
+    std::vector cell_nbr;
 
-    // Precomputed geometry
+    // Precomputed geometry (per cell)
     std::vector tri_area;       ///< Planimetric area (m²)
-    std::vector tri_cx;         ///< Centroid X
-    std::vector tri_cy;         ///< Centroid Y
-    std::vector tri_cz;         ///< Centroid Z (avg of vertex elevations)
+    std::vector tri_cx;         ///< Centroid X (area centroid)
+    std::vector tri_cy;         ///< Centroid Y (area centroid)
+    std::vector tri_cz;         ///< Mean of the cell's vertex elevations
 
-    // Edge geometry — flat 2D: [tri * 3 + edge]
+    // Edge geometry — flat 2D: [cell * kMaxCellVerts + k]
     std::vector edge_length;    ///< Length of each edge
     std::vector edge_nx;        ///< Outward normal X component
     std::vector edge_ny;        ///< Outward normal Y component
     std::vector edge_mx;        ///< Edge midpoint X
     std::vector edge_my;        ///< Edge midpoint Y
     std::vector edge_mz;        ///< Edge midpoint Z (interpolated)
+    /// Centroid → edge-midpoint distance along the outward normal,
+    /// (m⃗_e − c⃗)·n̂_e (m). For a triangle this equals the classic 2A/(3ξ)
+    /// (the centroid sits one third of the altitude up); for a quad it is the
+    /// exact normal distance. The ghost-cell arm every boundary-edge law uses.
+    std::vector edge_dist_c;
 
-    /// Per-edge conveyance factor in [0, 1], flat 2D [tri * 3 + edge].
+    /// Quad VFR precomputed data (B&S 2007 two-plane storage model, see
+    /// mesh/QuadVfr.hpp): per CELL, six sorted sub-triangle elevations
+    /// [cell*6 + k] and two sub-triangle areas [cell*2 + k]. Allocated only
+    /// when the mesh holds at least one quad (empty otherwise); triangle rows
+    /// are zero and never read. Rebuilt by MeshBuilder with the z-dependents.
+    std::vector quad_vfr_z;
+    std::vector quad_vfr_a;
+
+    /// Per-edge conveyance factor in [0, 1], flat 2D [cell * kMaxCellVerts + k].
     /// Default 1.0 (unrestricted) for every edge.  Multiplies the
     /// diffusion-wave flux in SurfaceFluxCalculator::computeEdgeFluxes
     /// (the last factor before edge_flux is stored).  Symmetric: for
@@ -146,7 +193,60 @@ struct MeshData {
     // -----------------------------------------------------------------------
 
     int n_vertices()  const noexcept { return static_cast(vx.size()); }
-    int n_triangles() const noexcept { return static_cast(tri_v0.size()); }
+    /// Number of CELLS (triangles + quads). The historical name is kept for
+    /// the ~200 call sites; `n_cells()` is the same value.
+    int n_triangles() const noexcept { return static_cast(cell_nv.size()); }
+    int n_cells()     const noexcept { return static_cast(cell_nv.size()); }
+    /// Number of quadrilateral cells (O(n) scan; not a hot path).
+    int n_quads() const noexcept {
+        int q = 0;
+        for (uint8_t nv : cell_nv) q += (nv == 4);
+        return q;
+    }
+    /// Edge-slot stride of the PUBLIC (API / HDF5) layout: 3 for an
+    /// all-triangle mesh (byte-compatible with every existing consumer),
+    /// kMaxCellVerts once a quad exists. Internal SoAs always use
+    /// kMaxCellVerts.
+    int edge_stride() const noexcept { return n_quads() > 0 ? kMaxCellVerts : 3; }
+    /// Number of internal edge slots (n_cells * kMaxCellVerts).
+    int n_edge_slots() const noexcept { return n_cells() * kMaxCellVerts; }
+
+    // -----------------------------------------------------------------------
+    // Cell / edge-slot accessors
+    // -----------------------------------------------------------------------
+
+    /// Flat edge/vertex slot of local index k in cell c.
+    static constexpr int slot(int c, int k) noexcept { return c * kMaxCellVerts + k; }
+    /// Local index k of a flat slot; cell of a flat slot.
+    static constexpr int slot_local(int s) noexcept { return s % kMaxCellVerts; }
+    static constexpr int slot_cell(int s)  noexcept { return s / kMaxCellVerts; }
+
+    int cell_vertex_count(int c) const noexcept { return cell_nv[static_cast(c)]; }
+    int cell_vertex(int c, int k) const noexcept { return cell_v[static_cast(slot(c, k))]; }
+    int cell_neighbour(int c, int k) const noexcept { return cell_nbr[static_cast(slot(c, k))]; }
+    bool is_quad(int c) const noexcept { return cell_nv[static_cast(c)] == 4; }
+
+    /// Endpoint vertices of local edge k of cell c: v[(k+1)%nv], v[(k+2)%nv].
+    void cell_edge_vertices(int c, int k, int& a, int& b) const noexcept {
+        const int nv = cell_nv[static_cast(c)];
+        a = cell_v[static_cast(slot(c, (k + 1) % nv))];
+        b = cell_v[static_cast(slot(c, (k + 2) % nv))];
+    }
+
+    void set_triangle(int c, int v0, int v1, int v2) noexcept {
+        cell_nv[static_cast(c)] = 3;
+        cell_v[static_cast(slot(c, 0))] = v0;
+        cell_v[static_cast(slot(c, 1))] = v1;
+        cell_v[static_cast(slot(c, 2))] = v2;
+        cell_v[static_cast(slot(c, 3))] = -1;
+    }
+    void set_quad(int c, int v0, int v1, int v2, int v3) noexcept {
+        cell_nv[static_cast(c)] = 4;
+        cell_v[static_cast(slot(c, 0))] = v0;
+        cell_v[static_cast(slot(c, 1))] = v1;
+        cell_v[static_cast(slot(c, 2))] = v2;
+        cell_v[static_cast(slot(c, 3))] = v3;
+    }
 
     // -----------------------------------------------------------------------
     // Resize / allocation
@@ -165,27 +265,33 @@ struct MeshData {
         vert_coupling_area_set.resize(n, 0);
     }
 
+    /// Resize the per-cell arrays to nt cells. New cells are TRIANGLES
+    /// (cell_nv = 3, vertex slots 0 / padding −1) until set_quad() is called.
     void resize_triangles(int nt) {
         auto n = static_cast(nt);
-        tri_v0.resize(n, 0);
-        tri_v1.resize(n, 0);
-        tri_v2.resize(n, 0);
-        tri_nbr0.resize(n, -1);
-        tri_nbr1.resize(n, -1);
-        tri_nbr2.resize(n, -1);
+        const auto old_n = cell_nv.size();
+        cell_nv.resize(n, 3);
+        const auto n4 = n * static_cast(kMaxCellVerts);
+        cell_v.resize(n4, 0);
+        cell_nbr.resize(n4, -1);
+        // Padding slot of every NEW triangle: vertex −1, neighbour −2.
+        for (std::size_t c = old_n; c < n; ++c) {
+            cell_v[c * kMaxCellVerts + 3]   = -1;
+            cell_nbr[c * kMaxCellVerts + 3] = -2;
+        }
         tri_area.resize(n, 0.0);
         tri_cx.resize(n, 0.0);
         tri_cy.resize(n, 0.0);
         tri_cz.resize(n, 0.0);
 
-        auto n3 = static_cast(nt) * 3;
-        edge_length.resize(n3, 0.0);
-        edge_nx.resize(n3, 0.0);
-        edge_ny.resize(n3, 0.0);
-        edge_mx.resize(n3, 0.0);
-        edge_my.resize(n3, 0.0);
-        edge_mz.resize(n3, 0.0);
-        edge_conveyance.resize(n3, 1.0);  // §11A — default unrestricted
+        edge_length.resize(n4, 0.0);
+        edge_nx.resize(n4, 0.0);
+        edge_ny.resize(n4, 0.0);
+        edge_mx.resize(n4, 0.0);
+        edge_my.resize(n4, 0.0);
+        edge_mz.resize(n4, 0.0);
+        edge_dist_c.resize(n4, 0.0);
+        edge_conveyance.resize(n4, 1.0);  // §11A — default unrestricted
 
         mannings_n.resize(n, 0.035);
         tri_init_depth.resize(n, 0.0);
diff --git a/src/engine/2d/data/PendingRows2D.hpp b/src/engine/2d/data/PendingRows2D.hpp
index 459c3fdee..4252d119b 100644
--- a/src/engine/2d/data/PendingRows2D.hpp
+++ b/src/engine/2d/data/PendingRows2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PendingRows2D.hpp
  * @brief Parse-time scratch rows for [2D_BOUNDARY_CONDITIONS] and
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_PENDING_ROWS_HPP
@@ -59,6 +75,36 @@ struct PendingEdgeConveyanceRow {
     double conveyance = 1.0; ///< Validated to [0, 1] at parse time
 };
 
+/**
+ * @brief One `[2D_INITIAL_QUALITY]` row (overland transport S1/S2).
+ *
+ * @details `CELL   `, `TAG   ` or
+ *          `*  `. Stored raw at parse: the mesh, its tags and
+ *          the species table are all finalised AFTER the .inp is read, so
+ *          resolution (and every fatal diagnostic — unknown species, unknown
+ *          tag, cell out of range) happens in `SurfaceRouter2D::initialize`
+ *          once the volumes exist to multiply against. Precedence at resolve
+ *          is `* < TAG < CELL`, the D-I3 order the infiltration rows use.
+ */
+struct PendingInitialQualityRow {
+    int         tri = -1;     ///< 0-based cell, or -1 for TAG / '*' scope
+    std::string tag;          ///< tag name; empty with tri >= 0 or for '*'
+    bool        all = false;  ///< the '*' spelling
+    std::string species;      ///< name in [POLLUTANTS]
+    double      conc = 0.0;   ///< species units (mass = conc x cell volume)
+};
+
+/// S2 — one `[2D_BOUNDARY_QUALITY]` row: `TRI EDGE SPECIES CONC`, the same
+/// 0-based TRI / 0..2 EDGE spelling as `[2D_BOUNDARY_CONDITIONS]`. Gives the
+/// concentration INFLOW through that boundary edge carries; outflow always
+/// leaves at the cell's concentration, so no row is needed for it.
+struct PendingBoundaryQualityRow {
+    int         tri  = 0;
+    int         edge = 0;     ///< 0..2
+    std::string species;      ///< name in [POLLUTANTS]
+    double      conc = 0.0;   ///< species units
+};
+
 } // namespace openswmm::twoD
 
 #endif // OPENSWMM_ENGINE_2D_PENDING_ROWS_HPP
diff --git a/src/engine/2d/data/Report2DVars.hpp b/src/engine/2d/data/Report2DVars.hpp
new file mode 100644
index 000000000..4ce238a7e
--- /dev/null
+++ b/src/engine/2d/data/Report2DVars.hpp
@@ -0,0 +1,138 @@
+/**
+ * @file Report2DVars.hpp
+ * @brief Header-only token ↔ bitmask helpers for
+ *        [2D_OPTIONS] REPORT_2D_VARIABLES / REPORT_2D_SPECIES / REPORT_2D_STEP.
+ *
+ * @details Shared by the [2D_OPTIONS] parser (SectionHandlers2D, 2D builds
+ *          only), the .inp writer and the GeoPackage writer/reader (compiled
+ *          in every build), so the vocabulary lives in one place and no
+ *          non-2D build gains a link dependency on the 2D TU.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+#ifndef OPENSWMM_ENGINE_2D_REPORT2D_VARS_HPP
+#define OPENSWMM_ENGINE_2D_REPORT2D_VARS_HPP
+
+#include "SolverOptions2D.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD::report2d {
+
+/// Group tokens in bit order (index i ↔ bit 1u << i).
+inline const std::vector& tokens() {
+    static const std::vector kTokens = {
+        "DEPTH", "VELOCITY", "EDGE_FLUX", "NODE_HEAD", "SPECIES", "RAINFALL",
+        "INFILTRATION", "COUPLING", "GRADIENTS", "CONTINUITY", "ENVELOPES",
+        "BUILDUP",   // S7
+        "GROUNDWATER", "GW_DETAILED",   // G-O
+    };
+    return kTokens;
+}
+
+inline bool iequalsTok(const std::string& a, const char* b) {
+    std::size_t i = 0;
+    for (; i < a.size() && b[i]; ++i)
+        if (std::toupper(static_cast(a[i])) !=
+            std::toupper(static_cast(b[i]))) return false;
+    return i == a.size() && b[i] == '\0';
+}
+
+/// Split on whitespace / commas.
+inline std::vector splitList(const std::string& text) {
+    std::vector toks;
+    std::string cur;
+    for (char c : text) {
+        if (c == ',' || c == ' ' || c == '\t' || c == '\r' || c == '\n') {
+            if (!cur.empty()) { toks.push_back(cur); cur.clear(); }
+        } else {
+            cur += c;
+        }
+    }
+    if (!cur.empty()) toks.push_back(cur);
+    return toks;
+}
+
+/**
+ * @brief Parse a token list or a preset (DEFAULT | MINIMAL | ALL | NONE) into
+ *        a bitmask. DEPTH is always included — every reader keys the time
+ *        axis on it. Returns an error string, empty on success.
+ */
+inline std::string parseMask(const std::string& text, unsigned& mask) {
+    mask = 0;
+    const auto toks = splitList(text);
+    if (toks.empty())
+        return "REPORT_2D_VARIABLES needs DEFAULT|MINIMAL|ALL or a token list";
+    const auto& names = tokens();
+    for (const auto& t : toks) {
+        if (iequalsTok(t, "DEFAULT")) { mask |= DEFAULT_MASK; continue; }
+        if (iequalsTok(t, "MINIMAL")) { mask |= MINIMAL_MASK; continue; }
+        if (iequalsTok(t, "ALL"))     { mask |= ALL_MASK;     continue; }
+        if (iequalsTok(t, "NONE"))    { continue; }
+        bool found = false;
+        for (std::size_t i = 0; i < names.size(); ++i) {
+            if (iequalsTok(t, names[i].c_str())) { mask |= (1u << i); found = true; break; }
+        }
+        if (!found) {
+            std::string all;
+            for (const auto& n : names) { if (!all.empty()) all += "|"; all += n; }
+            return "Unknown REPORT_2D_VARIABLES token '" + t +
+                   "' (expected DEFAULT|MINIMAL|ALL|NONE or " + all + ")";
+        }
+    }
+    mask |= DEPTH;
+    return {};
+}
+
+/// Preset name when the mask equals one, else the space-separated token list.
+inline std::string formatMask(unsigned mask) {
+    mask &= ALL_MASK;
+    if (mask == DEFAULT_MASK) return "DEFAULT";
+    if (mask == MINIMAL_MASK) return "MINIMAL";
+    if (mask == ALL_MASK)     return "ALL";
+    const auto& names = tokens();
+    std::string out;
+    for (std::size_t i = 0; i < names.size(); ++i) {
+        if (mask & (1u << i)) {
+            if (!out.empty()) out += ' ';
+            out += names[i];
+        }
+    }
+    return out.empty() ? std::string("DEPTH") : out;
+}
+
+/// "ALL" for an empty (unfiltered) list, else the space-separated names.
+inline std::string formatSpecies(const std::vector& species) {
+    if (species.empty()) return "ALL";
+    std::string out;
+    for (const auto& n : species) {
+        if (!out.empty()) out += ' ';
+        out += n;
+    }
+    return out;
+}
+
+/// Species list from text; "ALL" (alone) → empty list.
+inline std::vector parseSpecies(const std::string& text) {
+    auto v = splitList(text);
+    if (v.size() == 1 && iequalsTok(v[0], "ALL")) v.clear();
+    return v;
+}
+
+/// HH:MM:SS (REPORT_STEP spelling).
+inline std::string formatStep(double seconds) {
+    const long total = seconds > 0.0 ? static_cast(seconds + 0.5) : 0L;
+    char buf[32];
+    std::snprintf(buf, sizeof(buf), "%02ld:%02ld:%02ld",
+                  total / 3600, (total % 3600) / 60, total % 60);
+    return buf;
+}
+
+} // namespace openswmm::twoD::report2d
+
+#endif // OPENSWMM_ENGINE_2D_REPORT2D_VARS_HPP
diff --git a/src/engine/2d/data/Serialize2D.hpp b/src/engine/2d/data/Serialize2D.hpp
index 47738ed90..a4f3cb1b7 100644
--- a/src/engine/2d/data/Serialize2D.hpp
+++ b/src/engine/2d/data/Serialize2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Serialize2D.hpp
  * @brief Header-only helpers shared by 2D model serialization consumers
@@ -20,7 +36,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SERIALIZE_2D_HPP
@@ -46,6 +62,13 @@ namespace openswmm::twoD {
  * @param boundary Drained per-edge BC storage (may be null/unsized).
  * @param drained  SolverOptions2D::pending_rows_drained — true once
  *                 initialize() moved the pending rows into @p boundary.
+ * @param flow_to_si_applied  SolverOptions2D::bc_flow_to_si_applied — the
+ *                 display-flow → m³/s factor initialize() scaled the constant
+ *                 SPECIFIED_FLOW values by (1.0 when it has not run). The file
+ *                 contract is display flow units per metre, so constant flows
+ *                 read from @p boundary are divided by it. Constant STAGE heads
+ *                 need no such treatment: they follow the mesh scaling, and the
+ *                 `;; UNITS: SI (m)` header the writer emits covers them.
  * @return Authored rows; empty when every edge is a default WALL.
  *
  * @note Source selection: BEFORE the drain the pending rows are the only
@@ -59,7 +82,11 @@ namespace openswmm::twoD {
 inline std::vector collectBCRows(
     const std::vector* pending,
     const BoundaryData* boundary,
-    bool drained) {
+    bool drained,
+    double flow_to_si_applied = 1.0) {
+
+    const double flow_to_display =
+        (flow_to_si_applied > 0.0) ? 1.0 / flow_to_si_applied : 1.0;
 
     if (!drained) {
         if (pending && !pending->empty()) return *pending;
@@ -77,8 +104,8 @@ inline std::vector collectBCRows(
         if (type == BoundaryType::WALL) continue;
 
         PendingBoundaryRow r;
-        r.tri     = idx / 3;
-        r.edge    = idx % 3;
+        r.tri     = MeshData::slot_cell(idx);
+        r.edge    = MeshData::slot_local(idx);
         r.bc_type = static_cast(type);
 
         switch (type) {
@@ -95,7 +122,7 @@ inline std::vector collectBCRows(
             if (!boundary->edge_bc_flow_tseries_name[idx].empty())
                 r.name = boundary->edge_bc_flow_tseries_name[idx];
             else
-                r.param1 = boundary->edge_bc_flow[idx];
+                r.param1 = boundary->edge_bc_flow[idx] * flow_to_display;
             break;
         case BoundaryType::RATING_CURVE:
             r.name = boundary->edge_bc_rating_curve_name[idx];
@@ -112,11 +139,11 @@ inline std::vector collectBCRows(
         std::unordered_map groups;
         groups.reserve(pending->size());
         for (const auto& p : *pending) {
-            if (!p.group.empty()) groups[p.tri * 3 + p.edge] = &p.group;
+            if (!p.group.empty()) groups[MeshData::slot(p.tri, p.edge)] = &p.group;
         }
         if (!groups.empty()) {
             for (auto& r : rows) {
-                auto it = groups.find(r.tri * 3 + r.edge);
+                auto it = groups.find(MeshData::slot(r.tri, r.edge));
                 if (it != groups.end()) r.group = *it->second;
             }
         }
@@ -155,17 +182,19 @@ inline std::vector collectConveyanceRows(
 
     const int nt = mesh->n_triangles();
     if (nt < 1 ||
-        mesh->edge_conveyance.size() < static_cast(nt) * 3)
+        mesh->edge_conveyance.size() < static_cast(mesh->n_edge_slots()))
         return rows;
 
     std::unordered_set seen;
     for (int t = 0; t < nt; ++t) {
-        const int v[3] = { mesh->tri_v0[t], mesh->tri_v1[t], mesh->tri_v2[t] };
-        for (int e = 0; e < 3; ++e) {
-            const double k = mesh->edge_conveyance[t * 3 + e];
+        const int nvc = mesh->cell_vertex_count(t);
+        for (int e = 0; e < nvc; ++e) {
+            const double k = mesh->edge_conveyance[MeshData::slot(t, e)];
             if (k == 1.0) continue;
-            const int va = std::min(v[(e + 1) % 3], v[(e + 2) % 3]);
-            const int vb = std::max(v[(e + 1) % 3], v[(e + 2) % 3]);
+            int ea, eb;
+            mesh->cell_edge_vertices(t, e, ea, eb);
+            const int va = std::min(ea, eb);
+            const int vb = std::max(ea, eb);
             const std::int64_t key =
                 (static_cast(va) << 32)
                 | (static_cast(vb) & 0xFFFFFFFFLL);
diff --git a/src/engine/2d/data/SolverOptions2D.hpp b/src/engine/2d/data/SolverOptions2D.hpp
index beec0428b..55d44cdd3 100644
--- a/src/engine/2d/data/SolverOptions2D.hpp
+++ b/src/engine/2d/data/SolverOptions2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SolverOptions2D.hpp
  * @brief Configuration options for the 2D surface routing solver.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SOLVER_OPTIONS_HPP
@@ -15,6 +31,9 @@
 
 #include 
 #include 
+#include 
+
+#include "../../core/FilePathPair.hpp"
 
 namespace openswmm::twoD {
 
@@ -88,16 +107,102 @@ enum class FaceDepth2D : int8_t {
  * map location (no [SYMBOLS] coordinate), since interpolation is then undefined.
  *
  * Parsed from [2D_OPTIONS] RAINFALL_MODE; env OPENSWMM_2D_RAINFALL_MODE
- * (natural|system) overrides at initialize().
+ * (natural|nearest|system|none) overrides at initialize().
  */
 enum class RainfallMode : int8_t {
     NATURAL_NEIGHBOUR = 0,  ///< Default: spatial interpolation across all gages.
     SYSTEM            = 1,  ///< Uniform = mean of all gages.
-    NONE              = 2   ///< No rain on the mesh. Use when subcatchments
+    NONE              = 2,  ///< No rain on the mesh. Use when subcatchments
                             ///< already capture the rainfall (runoff → nodes) —
                             ///< rain-on-mesh would double-count the same storm.
+    NEAREST_NEIGHBOUR = 3   ///< Closest located gage; ties use first gage order.
+};
+
+/**
+ * @brief Compute backend for the 2D marcher (mirrors fv::Backend).
+ *
+ * AUTO (default) lets SurfaceSolverFactory pick: a device plugin (cuda, hip,
+ * sycl) above the device mesh-size floor, the OpenMP plugin above its own
+ * (higher) floor, else the built-in CPU marcher. The named values request one
+ * backend outright and bypass the size floors; a plugin that is absent or has
+ * no usable device falls back to CPU with a stderr notice, never a hard fail.
+ * The OPENSWMM_2D_BACKEND environment variable, when set, overrides this
+ * option (same precedence as OPENSWMM_FV_BACKEND over FV_BACKEND).
+ *
+ * Parsed from [2D_OPTIONS] BACKEND (AUTO|CPU|OMP|CUDA|HIP|SYCL).
+ */
+enum class Backend2D : int8_t {
+    CPU  = 0,   ///< Built-in marcher (OpenMP-threaded on the host), no plugin.
+    AUTO = 1,   ///< Default: plugins above their size floors, else CPU.
+    OMP  = 2,   ///< Kokkos OpenMP host plugin.
+    CUDA = 3,   ///< Kokkos CUDA device plugin (NVIDIA).
+    HIP  = 4,   ///< Kokkos HIP device plugin (AMD).
+    SYCL = 5    ///< Kokkos SYCL device plugin (Intel).
+};
+
+/**
+ * @brief Momentum closure of the explicit 2D marcher
+ *        (2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05 §2).
+ *
+ * Parsed from [2D_OPTIONS] MOMENTUM_EQUATION. One marcher (tiered LTS,
+ * active sets, positivity, coupling, transport) with three face laws:
+ *  - LOCAL_INERTIAL  de Almeida & Bates face-q update (default; bit-identical
+ *                    to the pre-2026-09 marcher).
+ *  - FULL_SWE        conservative shallow-water equations with the convective
+ *                    term: cell (h, hu, hv), hydrostatic reconstruction,
+ *                    rotated HLLC Riemann flux, shock capturing.
+ *  - DIFFUSIVE_WAVE  Manning quasi-steady face flux, no inertia (Hunter et al.
+ *                    2005 explicit diffusive wave; Δt ∝ Δx² per cell, absorbed
+ *                    by the LTS tiers).
+ */
+enum class Momentum2D : int8_t {
+    LOCAL_INERTIAL = 0,
+    FULL_SWE       = 1,
+    DIFFUSIVE_WAVE = 2
+};
+
+/**
+ * @brief Storage precision of the 2D results file's time-varying datasets
+ *        ([2D_OPTIONS] OUTPUT_PRECISION). Mesh geometry always stays float64:
+ *        projected coordinates are O(1e6) m and float32 would lose
+ *        centimetres there; depth/velocity fields have no such offset.
+ */
+enum class OutputPrecision2D : int8_t {
+    FLOAT32 = 0,   ///< default — halves the file, ~7 significant digits
+    FLOAT64 = 1    ///< bit-for-bit parity tooling
 };
 
+/**
+ * @brief Dataset groups the 2D results writer can emit
+ *        ([2D_OPTIONS] REPORT_2D_VARIABLES). One bit per group; the tokens
+ *        are the names below. Unselected groups are NOT created in the
+ *        file, so readers treat every time-varying dataset as optional.
+ */
+namespace report2d {
+enum Var : unsigned {
+    DEPTH        = 1u << 0,  ///< Mesh2_face_depth, Mesh2_face_head
+    VELOCITY     = 1u << 1,  ///< Mesh2_face_vx, Mesh2_face_vy
+    EDGE_FLUX    = 1u << 2,  ///< Mesh2_edge_flux (GUI velocity reconstruction, profile flux)
+    NODE_HEAD    = 1u << 3,  ///< Mesh2_node_head, Mesh2_node_depth (render reconstruction)
+    SPECIES      = 1u << 4,  ///< Mesh2_face_species_conc (when transport rows exist)
+    RAINFALL     = 1u << 5,  ///< Mesh2_face_rainfall, Mesh2_face_rain_cum
+    INFILTRATION = 1u << 6,  ///< Mesh2_face_infil_rate, Mesh2_face_infil_cum
+    COUPLING     = 1u << 7,  ///< Mesh2_face_coupling_flux, Mesh2_face_net_source
+    GRADIENTS    = 1u << 8,  ///< Mesh2_face_grad_hx/hy and the _lim pair (solver diagnostics)
+    CONTINUITY   = 1u << 9,  ///< Mesh2_face_continuity_err (solver diagnostic)
+    ENVELOPES    = 1u << 10, ///< Mesh2_face_max_depth / _max_velocity / _max_continuity_err
+    BUILDUP      = 1u << 11, ///< S7: Mesh2_face_buildup (when [2D_COVERAGES] rows resolved)
+    GROUNDWATER  = 1u << 12, ///< G-O: Mesh2_face_gw_* per-cell fields, groundwater_ledger, groundwater_node_exchange_cum (when a [2D_AQUIFER] resolved)
+    GW_DETAILED  = 1u << 13, ///< G-O: Mesh2_face_gw_theta_sigma [time, layer, face] — m × nFace per step
+    ALL_MASK     = (1u << 14) - 1u,
+    /// DEFAULT: everything a user renders or plots; solver diagnostics off.
+    DEFAULT_MASK = DEPTH | VELOCITY | EDGE_FLUX | NODE_HEAD | SPECIES |
+                   RAINFALL | INFILTRATION | ENVELOPES | BUILDUP | GROUNDWATER,
+    /// MINIMAL: depth map + render reconstruction + envelopes only.
+    MINIMAL_MASK = DEPTH | NODE_HEAD | ENVELOPES,
+};
+} // namespace report2d
+
 /**
  * @brief Configuration for the 2D surface routing solver.
  *
@@ -105,6 +210,21 @@ enum class RainfallMode : int8_t {
  * typical urban drainage surface routing problems.
  */
 struct SolverOptions2D {
+    /// [2D_OPTIONS] MOMENTUM_EQUATION — momentum closure (see Momentum2D).
+    Momentum2D momentum = Momentum2D::LOCAL_INERTIAL;
+    /// [2D_OPTIONS] FRONT_REBUILD AUTO|YES|NO — rebuild the flux-active set
+    /// as soon as a wetting front reaches the edge of the active halo instead
+    /// of waiting for the fixed rebuild cadence (kRebuildEveryCycles macro
+    /// cycles). Without it a dry-bed front can advance at most one cell ring
+    /// per cadence — the stall that pins the SWASHES Ritter/Thacker results.
+    /// AUTO (default): YES for FULL_SWE / DIFFUSIVE_WAVE, NO for
+    /// LOCAL_INERTIAL (which stays bit-identical to its pre-2026-09 results).
+    int front_rebuild = -1;   ///< -1 AUTO, 0 NO, 1 YES
+    /// [2D_OPTIONS] RECONSTRUCTION_ORDER 1|2 — FULL_SWE only: 1 = piecewise
+    /// constant (first-order Godunov, forward Euler); 2 = MUSCL on (η, u, v)
+    /// with the Barth–Jespersen-limited Green-Gauss gradient + SSP-RK2
+    /// (global-dt mode; LTS_TIERS > 1 is reduced to 1 with a warning).
+    int reconstruction_order = 1;
     /// Max marcher step (s): caps film-cell CFL steps (and thus the LTS tier
     /// spread) and the co-advance sync-batch span.
     double max_timestep      = 10.0;
@@ -132,10 +252,94 @@ struct SolverOptions2D {
     double coupling_cd       = 0.65;    ///< Default discharge coefficient
     bool   report_2d         = true;    ///< Write 2D results to output
 
+    // ---- Results-file size controls (plans/2D_OUTPUT_FLOAT32_AND_VARIABLE_SELECTION_PLAN) ----
+    /// [2D_OPTIONS] OUTPUT_PRECISION FLOAT32|FLOAT64 — storage type of the
+    /// time-varying datasets and envelopes (geometry stays float64).
+    OutputPrecision2D output_precision = OutputPrecision2D::FLOAT32;
+    /// [2D_OPTIONS] OUTPUT_COMPRESSION 0..9 — zlib level on chunked datasets;
+    /// the byte-shuffle filter precedes it whenever level > 0. 0 = none.
+    int output_compression = 4;
+    /// [2D_OPTIONS] REPORT_2D_VARIABLES — bitmask of report2d::Var groups
+    /// (tokens, or presets DEFAULT | MINIMAL | ALL).
+    unsigned report_2d_vars = report2d::DEFAULT_MASK;
+    /// [2D_OPTIONS] REPORT_2D_SPECIES — species row names to write; empty =
+    /// every row the transport layout carries.
+    std::vector report_2d_species;
+    /// [2D_OPTIONS] REPORT_2D_STEP — 2D-only report interval (seconds);
+    /// 0 = follow [OPTIONS] REPORT_STEP. Validated at start to be a positive
+    /// multiple of REPORT_STEP.
+    double report_2d_step = 0.0;
+
+    // -----------------------------------------------------------------------
+    // E2 (2026-09-07) — process enables. Every default reproduces the
+    // behaviour before the keys existed, so a deck without them is
+    // bit-identical. Consumed in SurfaceRouter2D::initialize() (infiltration
+    // rows, transport row layout via transport::surface2DEnables) and the
+    // per-step forcing refresh (evaporation).
+    // -----------------------------------------------------------------------
+    /// [2D_OPTIONS] INFILTRATION YES|NO. -1 = AUTO (unset): infiltration is
+    /// on iff any [2D_INFILTRATION*] row resolved (the pre-E2 rule). 0 = NO:
+    /// rows are kept in the model but Infil2D is deactivated for the run.
+    /// 1 = YES: explicit; warns when no row resolves.
+    int8_t infiltration = -1;
+    /// [2D_OPTIONS] INFIL_STEP (seconds). The canonical home of the
+    /// [2D_INFILTRATION_OPTIONS] INFIL_STEP value; the old section is still
+    /// read. 0 = unset (the section value, else the project WET_STEP).
+    /// When both are present this one wins.
+    double infil_step = 0.0;
+    /// [2D_OPTIONS] INFIL_DEFAULT_METHOD token (NONE | HORTON | MOD_HORTON |
+    /// GREEN_AMPT | MOD_GREEN_AMPT | CURVE_NUMBER | CONSTANT). Empty = unset:
+    /// the '*' row of [2D_INFILTRATION_DEFAULTS] governs. NONE drops the '*'
+    /// row for the run; a method must match the '*' row (its parameters live
+    /// there) — a mismatch is an initialize error, a missing row a warning.
+    std::string infil_default_method;
+    /// [2D_OPTIONS] INFIL_DESTINATION token (LOST | SUBCATCH_AQUIFER |
+    /// AQUIFER_2D). Empty = LOST. Applied at initialize to every
+    /// [2D_INFILTRATION*] row that did not spell its own DEST column.
+    /// SUBCATCH_AQUIFER routes to the containing subcatchment's legacy
+    /// aquifer (U3); AQUIFER_2D is authoring-only until the G1 kernel.
+    std::string infil_destination;
+    /// [2D_OPTIONS] EVAPORATION NO | YES | CLIMATE. 1 = YES (default, the
+    /// pre-E2 sink: per-cell forcing only — swmm_2d_force_evap*). 0 = NO:
+    /// the evaporation sink is zero for the run (forcing ignored). 2 =
+    /// CLIMATE: unforced cells evaporate at the project [EVAPORATION] rate
+    /// (climate_state.evap_rate, ft/s → m/s); forcing still overrides/adds.
+    int8_t evaporation = 1;
+    /// [2D_OPTIONS] TRANSPORT_POLLUTANTS | TRANSPORT_MSX | TRANSPORT_AGE |
+    /// TRANSPORT_TEMPERATURE YES|NO — the 2D column of the Domain × Species
+    /// matrix (transport::resolve). NO drops that class's rows from the
+    /// surface transport state; the 1D side is unaffected.
+    bool transport_pollutants  = true;
+    bool transport_msx         = true;
+    bool transport_age         = true;
+    bool transport_temperature = true;
+
+    // -----------------------------------------------------------------------
+    // U5 (2026-09-07), rewired 2026-09-07 once the G1 two-zone kernel landed.
+    // These are the PROCESS ENABLES for the integrated 2D subsurface; the
+    // parameters themselves live in [2D_AQUIFER_OPTIONS] / [2D_AQUIFER] /
+    // [2D_AQUIFER_NODE]. Same shape as INFILTRATION / INFIL_STEP above: a
+    // tri-state enable whose AUTO reproduces the pre-existing behaviour, and
+    // an alias that folds into the authoritative struct at open.
+    // -----------------------------------------------------------------------
+    /// [2D_OPTIONS] GROUNDWATER YES|NO. -1 = AUTO (unset): the kernel runs iff
+    /// any [2D_AQUIFER*] row was authored — exactly what it did before this
+    /// key existed, so a deck without it is unchanged. NO keeps the rows (they
+    /// still save) and runs without the subsurface; YES with no rows is a deck
+    /// that expects groundwater and has none, and says so.
+    int8_t groundwater = -1;
+    /// [2D_OPTIONS] GW_ET NONE | CAPILLARY_RISE | BOUNDARY_ET | BOTH — an
+    /// ALIAS of the [2D_AQUIFER_OPTIONS] key of the same name, which is the
+    /// single source of truth (GwOptions::gw_et is what the kernel reads and
+    /// what the writer emits). Empty = not spelled here; SWMMEngine::open
+    /// folds a spelled value into GwOptions and clears this, so the value is
+    /// never stored — or written — in two places.
+    std::string gw_et;
+
     // Rainfall→mesh mapping. Default NATURAL_NEIGHBOUR (spatial interpolation
     // across all located gages); SYSTEM applies the uniform all-gage mean.
     // Parsed from [2D_OPTIONS] RAINFALL_MODE; env OPENSWMM_2D_RAINFALL_MODE
-    // (natural|system) overrides.
+    // (natural|nearest|system|none) overrides.
     RainfallMode       rainfall_mode   = RainfallMode::NATURAL_NEIGHBOUR;
 
     // Volume → free-surface cell closure. Default FLAT (legacy η = tri_cz + V/A):
@@ -199,6 +403,14 @@ struct SolverOptions2D {
     /// Positivity/exchange availability fraction β: max share of a cell's
     /// volume that outgoing fluxes (or a coupling drain) may take per own-step.
     double exchange_beta  = 0.8;
+
+    /// Overland transport S2 — `[2D_OPTIONS] DISPERSION `: isotropic
+    /// species dispersion coefficient (D-2DT7). 0 (default) means the
+    /// dispersive face term is never entered, so pre-S2 answers are
+    /// bit-identical by construction rather than by a zero coefficient
+    /// multiplying through. Refused negative at parse: anti-diffusion is not
+    /// a modelling case.
+    double dispersion     = 0.0;
     /// Optional EMA sub-relaxation of per-substep coupling exchange (1 = off).
     double exchange_relax = 1.0;
     /// [2D_OPTIONS] COUPLING_AREA AUTO: derive exchange area at coupling-point
@@ -206,13 +418,34 @@ struct SolverOptions2D {
     /// 0.05, 2.0) m²) for rows that did not author an explicit area.
     bool   coupling_area_auto = false;
 
+    /// [2D_OPTIONS] COUPLING_IN_FLOODING: book the 1D→2D spill into the 1D
+    /// report's "Flooding Loss" row instead of its own "2D Coupling Outflow"
+    /// row. Default NO — the split row is the accurate reporting, since a
+    /// coupling transfer is not flooding.
+    ///
+    /// YES exists for one reason: comparing a run against a build from before
+    /// the split, where the spill was inside Flooding Loss. It changes the
+    /// report only; the continuity error and every routed volume are
+    /// identical either way.
+    bool   coupling_in_flooding = false;
+
+    /// [2D_OPTIONS] BACKEND: which marcher implementation runs the mesh. See
+    /// Backend2D. Read once, at SurfaceRouter2D::initialize() (the solver is
+    /// constructed there), so a mid-run edit takes effect on the next open.
+    Backend2D backend = Backend2D::AUTO;
+
     /// Path from [2D_MESH_FILE] FILE token. Empty = mesh is inline in main .inp.
-    std::string mesh_file;
+    /// `.absolute` is filled by resolve_external_file_slots() against the source
+    /// .inp directory, which is what lets the writer re-anchor a RELATIVE token
+    /// when saving to a different folder (without it, a Save-As left the .2dm
+    /// reference pointing at the old directory).
+    openswmm::FilePathPair mesh_file;
 
     /// HDF5 output file path from [2D_OPTIONS] OUTPUT_FILE token. Empty =
     /// no 2D output is written. Resolved relative to the parent .inp directory
-    /// by the section handler.
-    std::string output_file;
+    /// at the point of use (SWMMEngine::open) and re-anchored on save from
+    /// `.absolute`, same as mesh_file.
+    openswmm::FilePathPair output_file;
 
     // -----------------------------------------------------------------------
     // Unit-system coupling factors — NOT parsed from input. Computed once in
@@ -244,6 +477,12 @@ struct SolverOptions2D {
      *  thread count is bit-identical to serial. Never parsed/persisted. */
     int num_threads = 1;
 
+    /*! Runtime-only: the RAW [OPTIONS] THREADS value (0 = auto) copied in
+     *  SurfaceRouter2D::initialize(), handed to the Kokkos OpenMP plugin as
+     *  OpenSwmmGpuProbe::requested_threads (ABI v4) so the 2D host backend
+     *  follows THREADS like the 1D solvers. Never parsed/persisted. */
+    int requested_threads = 0;
+
     /*! When true, the inline `.inp` or referenced `.2dm` declared
      *  `;; UNITS: SI (m)` (or an equivalent metric keyword). The mesh on
      *  disk is already in SI metres, so SurfaceRouter2D::initialize
@@ -261,6 +500,15 @@ struct SolverOptions2D {
      *  against double-scaling. Never parsed from input, never persisted. */
     bool mesh_scaled_to_si = false;
 
+    /*! Runtime-only: the linear factor SurfaceRouter2D::initialize() applied
+     *  to the authored mesh coordinates to reach the solver's SI metres —
+     *  0.3048 for US FLOW_UNITS, 1.0 for SI projects and for meshes that
+     *  declared `;; UNITS: SI (m)`. Equivalently: metres per model-CRS linear
+     *  unit. Georeferenced output (Default2DOutputPlugin) writes this into the
+     *  `/crs` variable so a consumer can return the stored metric coordinates
+     *  to the model CRS's own unit exactly. Never parsed/persisted. */
+    double mesh_to_si_factor = 1.0;
+
     /*! Runtime-only: true after SurfaceRouter2D::initialize() drained the
      *  pending [2D_BOUNDARY_CONDITIONS] / [2D_EDGE_CONVEYANCE] rows into
      *  BoundaryData / MeshData::edge_conveyance. Serialization collectors
@@ -268,6 +516,14 @@ struct SolverOptions2D {
      *  they are the live state that post-initialize API mutations edit;
      *  the retained pending rows would be stale. Never parsed/persisted. */
     bool pending_rows_drained = false;
+
+    /*! Runtime-only: the display-flow-units → m³/s factor initialize() has
+     *  applied IN PLACE to the constant SPECIFIED_FLOW values in BoundaryData
+     *  (1.0 until it runs, and for CMS projects). The [2D_BOUNDARY_CONDITIONS]
+     *  file contract is display flow units per metre — there is no SI header
+     *  for flows, unlike lengths — so the writers divide edge_bc_flow by this
+     *  before emitting. Never parsed/persisted. */
+    double bc_flow_to_si_applied = 1.0;
 };
 
 } // namespace openswmm::twoD
diff --git a/src/engine/2d/data/SurfaceStateData.hpp b/src/engine/2d/data/SurfaceStateData.hpp
index 04d138fe4..1fd5e5de9 100644
--- a/src/engine/2d/data/SurfaceStateData.hpp
+++ b/src/engine/2d/data/SurfaceStateData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SurfaceStateData.hpp
  * @brief Structure-of-Arrays (SoA) storage for 2D surface routing state.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SURFACE_STATE_DATA_HPP
@@ -22,6 +38,9 @@
 #include 
 #include 
 
+#include "SurfaceTransportState.hpp"   // S1 — species mass per cell
+#include "MeshData.hpp"                 // kMaxCellVerts edge-slot stride
+
 namespace openswmm { struct NodeData; }  // 1D node data (held during a 2D advance)
 
 namespace openswmm::twoD {
@@ -32,7 +51,7 @@ struct CouplingPoint;  // fwd decl — 1D↔2D coupling descriptor (NodeCoupling
  * @brief SoA storage for 2D surface routing state variables.
  *
  * Per-triangle arrays are indexed [0, n_triangles).
- * Edge arrays are flat 2D: [tri * 3 + edge].
+ * Edge arrays are flat 2D: [cell * kMaxCellVerts + edge] (padded stride).
  * Vertex arrays are indexed [0, n_vertices).
  */
 struct BoundaryData;  // fwd decl — per-edge boundary conditions (BoundaryData.hpp)
@@ -57,8 +76,20 @@ struct SurfaceStateData {
     /// it self-limits) and accumulates the exact ∫Q dt per point.
     /// `nodes_1d` is the 1D node data, frozen for the duration of the batch.
     const NodeData*                   nodes_1d        = nullptr;
+    /// S4: the 1D nodes' PUBLISHED row values, `[node * n_species + s]` in the
+    /// 2D transport row order (pollutant conc, MSX conc, age, temperature),
+    /// assembled by the router before each advance and frozen for the batch.
+    /// What a 1D→2D spill or outfall discharge arrives at.
+    const std::vector*        node_row_conc   = nullptr;
     const std::vector* node_coupling   = nullptr;  ///< non-outfall points
 
+    /// S1 — overland species transport. `transport.active()` is false (and
+    /// every marcher species branch is skipped) unless the router sized it,
+    /// so a hydrodynamics-only model pays one predicate per firing and is
+    /// otherwise untouched. Embedded rather than pointed-to: it is per-cell
+    /// STATE, sized with `volume`, and it is copied when the state is.
+    SurfaceTransportState transport;
+
     std::vector depth;          ///< Mean wetted depth h̄ = V/A_wet (m) [reconstructed]
     std::vector head;           ///< Free-surface elevation η (m) [reconstructed]
     std::vector volume;         ///< Cell water volume V (m³) — the integrated state
@@ -89,13 +120,53 @@ struct SurfaceStateData {
     // Per-cell continuity residual — per triangle (m³/s, ≈0 when conservative)
     std::vector cell_continuity_err;
 
-    // Fluxes — flat 2D: [tri * 3 + edge]
+    // Fluxes — flat 2D: [cell * kMaxCellVerts + edge]
     std::vector edge_flux;      ///< Normal flux through each edge
 
     // Source/sink terms — per triangle
     std::vector rainfall;       ///< Rainfall intensity (m/s)
     std::vector evap_rate;      ///< Evaporation demand rate (m/s, >= 0)
+
+    /// Infiltration loss rate (m/s, >= 0) — a HELD rate (plan §5.5.2, D-I1):
+    /// Infil2D::updateRates republishes it on the INFIL_STEP cadence and it is
+    /// held constant in between, exactly as `rainfall` is. The marcher NEVER
+    /// evaluates an infiltration kernel per substep; it only consumes this
+    /// array through infilSink(), so infiltration has no interaction with the
+    /// LTS tiering or active set. All-zero when no [2D_INFILTRATION*] rows
+    /// resolved — the bitwise-regression fast path (gate I7).
+    std::vector infil_rate;
+
+    /// Infiltration APPLIED depth (m) accumulated since the last mass-balance
+    /// read, then zeroed by it. Every site that integrates the infiltration
+    /// sink into `volume` adds `infilSink(...) * dt` here with the SAME depth
+    /// and the SAME dt it used, so the ledger books what the marcher actually
+    /// removed. Re-deriving the loss from the accepted end-of-step depth is
+    /// only first-order: a cell that dries mid-step is sunk at the higher
+    /// early-step rate but re-derived at the ramped end-of-step rate, and the
+    /// lazy tier integrates a stale depth across a whole sync interval. Both
+    /// leave storage falling by more than the ledger books.
+    std::vector infil_applied;
+
     std::vector coupling_flux;  ///< Exchange with SWMM node (m/s, + = into 2D)
+
+    /// SIGNED per-cell coupling exchange VOLUME (m³) accumulated since the
+    /// last mass-balance read, then zeroed by it. Positive = water arrived in
+    /// this cell from the 1D node (spill / outfall discharge); negative =
+    /// water was abstracted from this cell into the node (drain).
+    ///
+    /// Signed on purpose, and per cell on purpose. The domain totals
+    /// (`MassBalance2D::coupling_1d_to_2d_in` / `coupling_2d_to_1d_out`) are
+    /// two unsigned accumulators and cannot answer "what did THIS cell give
+    /// or take", which is the question asked of a coupling point that
+    /// flip-flops within a batch: the two directions cancel in the net and
+    /// both are invisible in the totals. `coupling_flux` is a rate that is
+    /// overwritten every step, so it cannot answer it either.
+    ///
+    /// Booked at the SAME dt and the same share the marcher applied, exactly
+    /// like `infil_applied` above and for the same reason — re-deriving it
+    /// from end-of-step state is first-order and under-books the cells that
+    /// dried mid-step.
+    std::vector coupling_applied;
     std::vector net_source;     ///< Net source/sink per cell (m/s)
 
     // -----------------------------------------------------------------------
@@ -119,6 +190,13 @@ struct SurfaceStateData {
     /// semantics the swmm_2d_force_* API documents.
     bool forcing_dirty = false;
 
+    /// Sticky companion to forcing_dirty: set by the forcing API the first
+    /// time any prescription is written, never cleared. clear_reset_forcings()
+    /// is called once per routing step and is O(n_cells); on a model that
+    /// never uses the forcing API (every deck without an external controller)
+    /// the whole sweep is dead work, and this flag skips it.
+    bool forcing_ever_set = false;
+
     // -----------------------------------------------------------------------
     // Previous step state
     // -----------------------------------------------------------------------
@@ -147,7 +225,7 @@ struct SurfaceStateData {
     void resize(int n_triangles, int n_vertices) {
         auto nt = static_cast(n_triangles);
         auto nv = static_cast(n_vertices);
-        auto n3 = nt * 3;
+        auto n3 = nt * static_cast(kMaxCellVerts);
 
         depth.assign(nt, 0.0);
         head.assign(nt, 0.0);
@@ -164,6 +242,9 @@ struct SurfaceStateData {
         edge_flux.assign(n3, 0.0);
         rainfall.assign(nt, 0.0);
         evap_rate.assign(nt, 0.0);
+        infil_rate.assign(nt, 0.0);
+        infil_applied.assign(nt, 0.0);
+        coupling_applied.assign(nt, 0.0);
         coupling_flux.assign(nt, 0.0);
         net_source.assign(nt, 0.0);
 
@@ -202,6 +283,7 @@ struct SurfaceStateData {
 
     /// Clear RESET forcings after each step
     void clear_reset_forcings() noexcept {
+        if (!forcing_ever_set) return;
         for (std::size_t i = 0; i < rainfall_forced.size(); ++i) {
             if (rainfall_persist[i] == 0 && rainfall_forced[i] != 0) {
                 rainfall_forced[i] = 0;
diff --git a/src/engine/2d/data/SurfaceTransportState.hpp b/src/engine/2d/data/SurfaceTransportState.hpp
new file mode 100644
index 000000000..e37279268
--- /dev/null
+++ b/src/engine/2d/data/SurfaceTransportState.hpp
@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SurfaceTransportState.hpp
+ * @brief Overland transport S1 — per-cell species MASS on the 2D surface.
+ *
+ * @details Species are carried as **mass**, not concentration (D-2DT1). The
+ *          2D solver's integrated state is `SurfaceStateData::volume`, with
+ *          depth and head *reconstructed* from it each step; a concentration
+ *          state would have to be reconstructed against a volume that itself
+ *          moves, and the two would disagree at every wet/dry transition.
+ *          Mass is what the flux form conserves, and it makes drying
+ *          trivial: a cell that empties keeps what it held.
+ *
+ *          Layout is SPECIES-MAJOR, `[s * n_cells + c]`, matching
+ *          `ArdEngine`'s `cell_phi` so the two engines' kernels read alike.
+ *
+ * @par What S1 carries, and what it does not
+ *      S1 rows are the `[POLLUTANTS]` species only, `[0, np)`. Water age,
+ *      temperature and MSX rows arrive with S4 and take the same row
+ *      convention the 1D engines use (pollutants, MSX, age, temperature).
+ *      `n_species` is therefore whatever the router sizes it to, and no code
+ *      in the marcher knows what a row MEANS — it moves mass.
+ *
+ * @par Sources in S1
+ *      Water arriving through rainfall, a boundary inflow, or the 1D→2D
+ *      coupling arrives at **zero concentration** in S1. Water LEAVING
+ *      through infiltration, a boundary outflow, or the 2D→1D drain leaves
+ *      **at the cell's concentration** and its mass is booked to a ledger,
+ *      so nothing is destroyed silently. Evaporation removes volume and no
+ *      mass — the concentration rises — which is the up-concentration the
+ *      1D path gets wrong (KD1's open residual) and the 2D path gets right
+ *      from the start. Source concentrations (rain concentration, boundary
+ *      species, the coupling tuple) are S2/S3; the ledger rows below are
+ *      what those phases will consume.
+ *
+ * @see plans/transport/OVERLAND_TRANSPORT_HEAT_MSX_PLAN_2026-09-01.md
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SURFACE_TRANSPORT_STATE_HPP
+#define OPENSWMM_ENGINE_2D_SURFACE_TRANSPORT_STATE_HPP
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+struct SurfaceTransportState {
+    int n_species = 0;   ///< rows carried; 0 ⇒ transport is off everywhere
+    int n_cells   = 0;
+
+    // ---- S4 row layout — the 1D engines' convention, verbatim -------------
+    // rows [0, n_pollut) pollutants; [n_pollut, n_pollut + n_msx) MSX species
+    // in ReactionData order; then the reserved __WATER_AGE__ row; then the
+    // reserved __TEMPERATURE__ row LAST (H1 fixed the reported column order
+    // so adding heat to an age model never moves the age column). Set by the
+    // router after resize(); -1 ⇒ the row is not carried.
+    int n_pollut = 0;
+    int n_msx    = 0;
+    int age_row  = -1;
+    int temp_row = -1;
+    /// Row names in row order (pollutant ids, MSX ids, `__WATER_AGE__`,
+    /// `__TEMPERATURE__`) — what the HDF5 species attribute and the
+    /// [2D_INITIAL_QUALITY]/[2D_BOUNDARY_QUALITY] resolvers key on.
+    std::vector row_names;
+    /// The temperature row is SIGNED (°C below zero is a state, not an
+    /// error): every "mass ≥ 0" guard in the marcher and the queue must skip
+    /// it. Age and every concentration row are non-negative.
+    bool signedRow(int s) const noexcept { return s == temp_row; }
+    int rowIndex(std::string_view name) const noexcept {
+        for (std::size_t i = 0; i < row_names.size(); ++i)
+            if (row_names[i] == name) return static_cast(i);
+        return -1;
+    }
+
+    /// [s * n_cells + c] species mass in the cell's water, in the species'
+    /// own mass units (concentration units × m³, so a report divides by the
+    /// SI cell volume and needs no further conversion).
+    std::vector cell_mass;
+
+    // ---- Ledgers (per species), m³·conc, cumulative over the run. ----------
+    // These are what S3's coupling tuple and the continuity table will read;
+    // in S1 they are the record that mass left the surface and where.
+    std::vector lost_infiltration;   ///< left through the bed
+    std::vector lost_boundary;       ///< left through an open edge
+    std::vector lost_coupling;       ///< left through the 1D↔2D exchange
+    /// [k * n_species + s] species mass drained through coupling point k this
+    /// advance (m³·conc, + = 2D→1D). Reset with `exch_` per advance; S3's
+    /// tuple reads it into the node's `qual_mass_in`.
+    std::vector exch_mass;
+    /// [k] spill VOLUME (m³, 1D→2D side only) through coupling point k this
+    /// advance. Volume, not mass — it exists for the mass bookkeeping: the
+    /// volume queue NETS a window's flip-flop while `exch_mass` holds the
+    /// drain GROSS, and the router pairs `min(spill, drain)` of the spill
+    /// against the queued mass at the node's concentration so a mixed-sign
+    /// window hands the node mass and water in the same ratio. The
+    /// net-negative remainder is the part the node's own volume drop removes
+    /// at the mixed concentration (the plan's §2.1 argument, now scoped to
+    /// exactly that remainder). Reset with `exch_mass`.
+    std::vector exch_spill;
+
+    // ---- S2 source concentrations (species units) -------------------------
+    /// [s] concentration carried by rainfall — `[POLLUTANTS]` rain
+    /// concentration, set by the router. Empty ⇒ rain arrives clean (S1).
+    std::vector rain_conc;
+    /// [bc_slot * n_species + s] concentration carried by INFLOW through a
+    /// non-WALL boundary edge, from `[2D_BOUNDARY_QUALITY]`. Sized by the
+    /// solver to its own `bc_cell_` list at initialize; empty ⇒ inflow
+    /// arrives clean. Outflow always leaves at the cell's concentration.
+    std::vector bc_conc;
+    /// Raw `[2D_BOUNDARY_QUALITY]` rows, resolved by the solver against its
+    /// boundary-edge list: (flat mesh edge slot tri*3+e, species, conc).
+    struct BoundaryQualityRow { int slot = -1; int species = -1; double conc = 0.0; };
+    std::vector bc_quality_rows;
+
+    // ---- S2 dispersion limiter telemetry ----------------------------------
+    /// Times the explicit dispersive exchange on a face was capped to keep the
+    /// pair from crossing (the max-principle limiter). Nonzero means the
+    /// dispersion is under-resolved at the marcher's dt on that face — a
+    /// modelling signal, not an error, and the reason it is counted rather
+    /// than hidden.
+    long dispersion_limiter_binds = 0;
+
+    /// Source ledgers (per species, m³·conc, cumulative) so the continuity
+    /// statement can close: what came in through rain and boundaries.
+    std::vector gained_rainfall;
+    std::vector gained_boundary;
+    /// S3: what came in through the 1D→2D coupling (junction spill at the
+    /// node's published concentration, outfall discharge at the outfall's).
+    std::vector gained_coupling;
+    /// T7.1: mass the two-zone aquifer handed back up with its saturation
+    /// excess. The twin of `lost_infiltration`, which is what went down.
+    std::vector gained_exfiltration;
+    /// S7: [s] species mass washed off the cells' land-use surfaces into the
+    /// rows (cell buildup → water), m³·conc. Sized by the router when
+    /// `[2D_COVERAGES]` resolves; empty otherwise.
+    std::vector gained_washoff;
+    /// S7: [c] the cell's NET runoff volume (m³, signed) since the last
+    /// runoff step: + what left across its faces, open boundary edges and
+    /// drains to nodes, − what arrived across faces, from node spills,
+    /// outfall discharge, prescribed inflow and inflow boundaries. Rainfall
+    /// and groundwater return are generation, not inflow, so they are not
+    /// subtracted: the positive part is the runoff the cell itself produced
+    /// (rain excess plus storage release, the subcatchment step's `q·A`) —
+    /// D-A22 as revised 2026-09-19. Accumulated by the marcher only while
+    /// non-empty (sized by the router with the coverages); read, clamped at
+    /// zero and zeroed by SurfaceQuality2D::step.
+    std::vector cell_runoff_vol;
+
+    // ---- S3 outfall-discharge species source ------------------------------
+    /// [s * n_cells + c] species mass-rate DENSITY (conc · m/s) riding the
+    /// positive `coupling_flux` an outfall scatters onto its cells, so a cell
+    /// gains `coupling_src · area · dt` beside the volume `coupling_flux ·
+    /// area · dt`. Sized by the router when transport is active and outfall
+    /// points exist; empty ⇒ outfall discharge arrives clean. The junction
+    /// spill does NOT use this — it is booked live in the marcher from the
+    /// node's concentration.
+    std::vector coupling_src;
+
+    bool active() const noexcept { return n_species > 0 && n_cells > 0; }
+
+    void resize(int n_spec, int n_tri, int n_coupling_points) {
+        n_species = (n_spec > 0) ? n_spec : 0;
+        n_cells   = (n_tri  > 0) ? n_tri  : 0;
+        n_pollut = n_species; n_msx = 0; age_row = -1; temp_row = -1;   // S4: router refines
+        row_names.clear();
+        const auto ns = static_cast(n_species);
+        cell_mass.assign(ns * static_cast(n_cells), 0.0);
+        lost_infiltration.assign(ns, 0.0);
+        lost_boundary.assign(ns, 0.0);
+        lost_coupling.assign(ns, 0.0);
+        exch_mass.assign(ns * static_cast(
+                                  n_coupling_points > 0 ? n_coupling_points
+                                                        : 0),
+                         0.0);
+        exch_spill.assign(static_cast(
+                              n_coupling_points > 0 ? n_coupling_points : 0),
+                          0.0);
+        rain_conc.clear();          // S2: router fills when pollutants carry one
+        bc_conc.clear();            // S2: solver sizes at initialize
+        bc_quality_rows.clear();
+        dispersion_limiter_binds = 0;
+        gained_rainfall.assign(ns, 0.0);
+        gained_boundary.assign(ns, 0.0);
+        gained_coupling.assign(ns, 0.0);
+        gained_exfiltration.assign(ns, 0.0);   // T7.1
+        coupling_src.clear();       // S3: router sizes when outfalls exist
+    }
+
+    void clear() { *this = SurfaceTransportState{}; }
+
+    std::size_t idx(int s, int c) const noexcept {
+        return static_cast(s) * static_cast(n_cells) +
+               static_cast(c);
+    }
+
+    /// Reported concentration — derived, never stored. `dry_volume_m3` is the
+    /// hydraulics' own dry threshold expressed as a volume; below it the
+    /// cell holds its mass and reports 0 rather than dividing by a vanishing
+    /// volume (the 2D analogue of the 1D dryness guard).
+    double concentration(int s, int c, double volume_m3,
+                         double dry_volume_m3) const noexcept {
+        if (!(volume_m3 > dry_volume_m3)) return 0.0;
+        return cell_mass[idx(s, c)] / volume_m3;
+    }
+
+    /// Total mass of one species over the surface + every ledger — the
+    /// quantity the S1 conservation gate asserts is invariant.
+    double totalIncludingLedgers(int s) const noexcept {
+        double m = 0.0;
+        const auto base = static_cast(s) *
+                          static_cast(n_cells);
+        for (int c = 0; c < n_cells; ++c)
+            m += cell_mass[base + static_cast(c)];
+        const auto us = static_cast(s);
+        // Sources are SUBTRACTED so the quantity is "what was there at t=0":
+        // surface + everything that left − everything that arrived.
+        return m + lost_infiltration[us] + lost_boundary[us] +
+               lost_coupling[us] -
+               (us < gained_rainfall.size() ? gained_rainfall[us] : 0.0) -
+               (us < gained_boundary.size() ? gained_boundary[us] : 0.0) -
+               (us < gained_coupling.size() ? gained_coupling[us] : 0.0) -
+               (us < gained_washoff.size()  ? gained_washoff[us]  : 0.0) -
+               (us < gained_exfiltration.size() ? gained_exfiltration[us] : 0.0);
+    }
+};
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_SURFACE_TRANSPORT_STATE_HPP
diff --git a/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.cpp b/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.cpp
index 1f3b3518d..5497ae6cb 100644
--- a/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.cpp
+++ b/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.cpp
@@ -18,12 +18,18 @@
 #define OPENSWMM_KERNEL_FN KOKKOS_INLINE_FUNCTION
 
 #include "ExplicitKokkosSurfaceSolver.hpp"
+// Relative, not "core/FileIO.hpp": this TU is also compiled into the STANDALONE
+// GPU plugin targets (openswmm_gpu_omp / _cuda), whose include path is only
+// ../solver and ../data — src/engine is not on it. Matches how every other
+// engine header is reached from this file (../data/MeshData.hpp, etc.).
+#include "../../core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include 
 #include 
 #include 
 #include 
 
+#include "KokkosPerfCounters.hpp"
 #include "../data/MeshData.hpp"
 #include "../data/SolverOptions2D.hpp"
 #include "../data/SurfaceStateData.hpp"
@@ -88,6 +94,18 @@ KOKKOS_INLINE_FUNCTION double devEvapSink(double rate, double depth,
     return rate * t * t * (3.0 - 2.0 * t);
 }
 
+/// Device twin of SurfaceFluxCalculator.hpp infilSink (plan §5.5, D-I1) —
+/// same body as devEvapSink above, kept as its own function so the two sinks
+/// stay independently greppable and D-I2's ordering reads explicitly at the
+/// call sites.
+KOKKOS_INLINE_FUNCTION double devInfilSink(double rate, double depth,
+                                           double dry_depth) {
+    if (rate <= 0.0 || depth <= 0.0) return 0.0;
+    if (depth >= dry_depth) return rate;
+    const double t = depth / dry_depth;
+    return rate * t * t * (3.0 - 2.0 * t);
+}
+
 constexpr double kOrificeHEps = 0.02;   // == NodeCoupling.cpp ORIFICE_H_EPS
 
 KOKKOS_INLINE_FUNCTION double devOrificePhi(double a) {
@@ -136,6 +154,12 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     state_ = &state;
     opts_  = &opts;
 
+    // Perf review Phase A2: launch/fence/deep_copy counters (OPENSWMM_PERF).
+    // Installed after Kokkos::initialize (plugin construction), before the
+    // devCopy mirroring below so initialize's uploads are counted too.
+    kperf::install();
+    kperf::reset();
+
     const int nt = mesh.n_triangles();
     if (nt <= 0) return;
 
@@ -150,9 +174,10 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     d_vz_       = devCopy("vz", mesh.vz);
     d_vx_       = devCopy("vx", mesh.vx);
     d_vy_       = devCopy("vy", mesh.vy);
-    d_tri_v0_   = devCopy("tri_v0", mesh.tri_v0);
-    d_tri_v1_   = devCopy("tri_v1", mesh.tri_v1);
-    d_tri_v2_   = devCopy("tri_v2", mesh.tri_v2);
+    // Padded [cell*kMaxCellVerts + k] connectivity (MeshData). This plugin
+    // is gated to ALL-TRIANGLE meshes by SurfaceSolverFactory (R6), so the
+    // kernels below read slots 0..2 only.
+    d_cell_v_   = devCopy("cell_v", mesh.cell_v);
     d_vs_ptr_   = devCopy("vs_ptr", mesh.vert_stencil_ptr);
     d_vs_idx_   = devCopy("vs_idx", mesh.vert_stencil_idx);
     d_vs_wt_    = devCopy("vs_wt", mesh.vert_stencil_wt);
@@ -176,7 +201,13 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     d_lchar_ = devCopy("cell_lchar", edges_.cell_lchar);
     d_cell_ptr_  = devCopy("cell_ptr", edges_.cell_ptr);
     d_cell_edge_ = devCopy("cell_edge", edges_.cell_edge);
-    d_sign_      = devCopy("cell_sign", edges_.cell_sign);
+    {
+        // edges_.cell_sign is int8 on the host (gather-traffic diet in the CPU
+        // marcher); the device kernels keep it as doubles they multiply by.
+        std::vector sgn(edges_.cell_sign.begin(),
+                                edges_.cell_sign.end());
+        d_sign_ = devCopy("cell_sign", sgn);
+    }
 
     // State + marching arrays.
     d_volume_ = devCopy("volume", state.volume);
@@ -192,6 +223,11 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     d_rain_ = DView("rain", nt);
     d_coup_ = DView("coup", nt);
     d_evap_ = DView("evap", nt);
+    d_infil_ = DView("infil", nt);
+    d_infil_applied_ = DView("infil_applied", nt);
+    infil_applied_host_.assign(static_cast(nt), 0.0);
+    d_coupling_applied_ = DView("coupling_applied", nt);
+    coupling_applied_host_.assign(static_cast(nt), 0.0);
     d_edge_flux_ = DView("edge_flux", state.edge_flux.size());
     d_active_ = IView("active", nt);
     d_pin_t0_ = IView("pin_t0", nt);
@@ -215,13 +251,12 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     bc_slot_host_.clear();
     if (state.boundary) {
         for (int i = 0; i < nt; ++i) {
-            for (int e = 0; e < 3; ++e) {
-                const int idx = i * 3 + e;
+            const int nvc = mesh.cell_vertex_count(i);
+            for (int e = 0; e < nvc; ++e) {
+                const int idx = MeshData::slot(i, e);
                 const auto ty =
                     static_cast(state.boundary->edge_bc_type[idx]);
-                const bool interior = (e == 0   ? mesh.tri_nbr0[i]
-                                       : e == 1 ? mesh.tri_nbr1[i]
-                                                : mesh.tri_nbr2[i]) >= 0;
+                const bool interior = mesh.cell_neighbour(i, e) >= 0;
                 if (!interior && ty != BoundaryType::WALL) {
                     bc_cell_host_.push_back(i);
                     bc_slot_host_.push_back(idx);
@@ -267,11 +302,13 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
     d_node_head_      = DView("node_head", nn);
     d_node_depth_     = DView("node_depth", nn);
     d_node_volume_    = DView("node_volume", nn);
+    d_node_fullvol_   = DView("node_fullvol", nn);
     d_node_invert_    = DView("node_invert", nn);
     d_node_fulldepth_ = DView("node_fulldepth", nn);
     if (nn > 0) {
         devRefresh(d_node_invert_, state.nodes_1d->invert_elev);
         devRefresh(d_node_fulldepth_, state.nodes_1d->full_depth);
+        devRefresh(d_node_fullvol_, state.nodes_1d->full_volume);
     }
 
     // Tier-0 pins: BC cells + coupling cells (fastest-changing forcing).
@@ -326,7 +363,7 @@ void ExplicitKokkosSurfaceSolver::initialize(MeshData& mesh,
                     double sx = 0.0, sy = 0.0;
                     for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
                         const int    e = ed.cell_edge[p];
-                        const double fq = ed.cell_sign[p] * qh[e] * ed.xi[e];
+                        const double fq = static_cast(ed.cell_sign[p]) * qh[e] * ed.xi[e];
                         sx += fq * (ed.mx[e] - mesh.tri_cx[i]);
                         sy += fq * (ed.my[e] - mesh.tri_cy[i]);
                     }
@@ -358,15 +395,15 @@ void ExplicitKokkosSurfaceSolver::reconstructAllDev() {
     const int nt = mesh_->n_triangles();
     auto vol = d_volume_, head = d_head_, depth = d_depth_;
     auto area = d_tri_area_, cz = d_tri_cz_, vz = d_vz_;
-    auto v0 = d_tri_v0_, v1 = d_tri_v1_, v2 = d_tri_v2_;
+    auto cvv = d_cell_v_;
     const bool vfr = (opts_->cell_closure == CellClosure2D::VFR);
     const double mwf = opts_->vfr_min_wet_frac;
     Kokkos::parallel_for(
         "reconstructAll", Kokkos::RangePolicy(0, nt),
         KOKKOS_LAMBDA(int i) {
             double e, d;
-            inertial::etaDepthScalar(area(i), cz(i), vz(v0(i)), vz(v1(i)),
-                                     vz(v2(i)), vfr, mwf, vol(i), e, d);
+            inertial::etaDepthScalar(area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)), vz(cvv(i * kMaxCellVerts + 1)),
+                                     vz(cvv(i * kMaxCellVerts + 2)), vfr, mwf, vol(i), e, d);
             head(i) = e;
             depth(i) = d;
         });
@@ -379,7 +416,7 @@ void ExplicitKokkosSurfaceSolver::settleAccumulatorsDev() {
     auto ptr = d_cell_ptr_, edge = d_cell_edge_;
     auto sign = d_sign_;
     auto area = d_tri_area_, cz = d_tri_cz_, vz = d_vz_;
-    auto v0 = d_tri_v0_, v1 = d_tri_v1_, v2 = d_tri_v2_;
+    auto cvv = d_cell_v_;
     const bool vfr = (opts_->cell_closure == CellClosure2D::VFR);
     const double mwf = opts_->vfr_min_wet_frac;
     Kokkos::parallel_for(
@@ -400,8 +437,8 @@ void ExplicitKokkosSurfaceSolver::settleAccumulatorsDev() {
             double v = vol(i) + pending;
             vol(i) = (v > 0.0) ? v : 0.0;
             double e2, d2;
-            inertial::etaDepthScalar(area(i), cz(i), vz(v0(i)), vz(v1(i)),
-                                     vz(v2(i)), vfr, mwf, vol(i), e2, d2);
+            inertial::etaDepthScalar(area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)), vz(cvv(i * kMaxCellVerts + 1)),
+                                     vz(cvv(i * kMaxCellVerts + 2)), vfr, mwf, vol(i), e2, d2);
             head(i) = e2;
             depth(i) = d2;
         });
@@ -412,10 +449,12 @@ void ExplicitKokkosSurfaceSolver::lazySourcesDev(double t) {
     if (dt_lazy <= 0.0) return;
     const int nt = mesh_->n_triangles();
     auto vol = d_volume_, head = d_head_, depth = d_depth_;
-    auto rain = d_rain_, coup = d_coup_, evap = d_evap_;
+    auto rain = d_rain_, coup = d_coup_, evap = d_evap_, infil = d_infil_;
+    auto infil_app = d_infil_applied_;
+    auto coup_app = d_coupling_applied_;
     auto active = d_active_;
     auto area = d_tri_area_, cz = d_tri_cz_, vz = d_vz_;
-    auto v0 = d_tri_v0_, v1 = d_tri_v1_, v2 = d_tri_v2_;
+    auto cvv = d_cell_v_;
     const bool vfr = (opts_->cell_closure == CellClosure2D::VFR);
     const double mwf = opts_->vfr_min_wet_frac;
     const double dry = opts_->dry_depth;
@@ -423,14 +462,21 @@ void ExplicitKokkosSurfaceSolver::lazySourcesDev(double t) {
         "lazySources", Kokkos::RangePolicy(0, nt),
         KOKKOS_LAMBDA(int i) {
             if (active(i)) return;
+            // D-I2 ordering: rainfall source → evaporation → infiltration
+            // against the remaining depth (== ExplicitInertialSolver).
+            const double inf = devInfilSink(infil(i), depth(i), dry);
+            // Book before the early-out, as the serial marcher does.
+            infil_app(i) += inf * dt_lazy;
+            if (coup(i) != 0.0) coup_app(i) += coup(i) * dt_lazy * area(i);
             const double src = rain(i) + coup(i)
-                               - devEvapSink(evap(i), depth(i), dry);
+                               - devEvapSink(evap(i), depth(i), dry)
+                               - inf;
             if (src == 0.0) return;
             double v = vol(i) + dt_lazy * src * area(i);
             vol(i) = (v > 0.0) ? v : 0.0;
             double e2, d2;
-            inertial::etaDepthScalar(area(i), cz(i), vz(v0(i)), vz(v1(i)),
-                                     vz(v2(i)), vfr, mwf, vol(i), e2, d2);
+            inertial::etaDepthScalar(area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)), vz(cvv(i * kMaxCellVerts + 1)),
+                                     vz(cvv(i * kMaxCellVerts + 2)), vfr, mwf, vol(i), e2, d2);
             head(i) = e2;
             depth(i) = d2;
         });
@@ -489,7 +535,7 @@ void ExplicitKokkosSurfaceSolver::syncAndRebuild(double t) {
             const double h = depth(i);
             double speed = 0.0;
             if (perot && h > 1.0e-6)
-                speed = std::hypot(qcx(i), qcy(i)) / h;
+                speed = inertial::qMagnitude(qcx(i), qcy(i)) / h;
             double dt = (h > dry)
                             ? inertial::cellCflDt(alpha, lchar(i), h, speed)
                             : 1.0e30;
@@ -602,7 +648,7 @@ void ExplicitKokkosSurfaceSolver::refreshDt0() {
             if (h <= dry) return;
             double speed = 0.0;
             if (perot && h > 1.0e-6)
-                speed = std::hypot(qcx(i), qcy(i)) / h;
+                speed = inertial::qMagnitude(qcx(i), qcy(i)) / h;
             const double dt = inertial::cellCflDt(alpha, lchar(i), h, speed);
             if (dt < mn) mn = dt;
         },
@@ -708,7 +754,7 @@ void ExplicitKokkosSurfaceSolver::fireFaces(int k, double dt_f) {
                 const double qn  = qfx * nxv(e) + qfy * nyv(e);
                 qhat  = theta * qv(e) + (1.0 - theta) * qn;
                 // Vector friction magnitude, floored at |q_n| (== serial).
-                const double qm = std::sqrt(qfx * qfx + qfy * qfy);
+                const double qm = inertial::qMagnitude(qfx, qfy);
                 if (qm > q_mag) q_mag = qm;
             }
             double deta = head(b) - head(a);
@@ -752,12 +798,14 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
     auto faccL = d_faccL_, faccR = d_faccR_;
     auto ptr = d_cell_ptr_, edge = d_cell_edge_;
     auto sign = d_sign_;
-    auto rain = d_rain_, coup = d_coup_, evap = d_evap_;
+    auto rain = d_rain_, coup = d_coup_, evap = d_evap_, infil = d_infil_;
+    auto infil_app = d_infil_applied_;
+    auto coup_app = d_coupling_applied_;
     auto qv = d_q_, xi = d_xi_, mx = d_mx_, my = d_my_;
     auto qcx = d_qcx_, qcy = d_qcy_;
     auto area = d_tri_area_, cz = d_tri_cz_, cx = d_tri_cx_, cy = d_tri_cy_;
     auto vz = d_vz_;
-    auto v0 = d_tri_v0_, v1 = d_tri_v1_, v2 = d_tri_v2_;
+    auto cvv = d_cell_v_;
     const bool vfr = (opts_->cell_closure == CellClosure2D::VFR);
     const double mwf = opts_->vfr_min_wet_frac;
     const bool perot = have_perot_;
@@ -778,13 +826,19 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         faccR(e) = 0.0;
                     }
                 }
+                // D-I2 ordering: rainfall source → evaporation → infiltration
+                // against the remaining depth (== ExplicitInertialSolver).
+                const double inf = devInfilSink(infil(i), depth(i), dry);
+                infil_app(i) += inf * dt_c;
+                if (coup(i) != 0.0) coup_app(i) += coup(i) * dt_c * area(i);
                 const double src = rain(i) + coup(i)
-                                   - devEvapSink(evap(i), depth(i), dry);
+                                   - devEvapSink(evap(i), depth(i), dry)
+                                   - inf;
                 double v = vol(i) + flux_m3 + dt_c * src * area(i);
                 vol(i) = (v > 0.0) ? v : 0.0;
                 double e2, d2;
-                inertial::etaDepthScalar(area(i), cz(i), vz(v0(i)), vz(v1(i)),
-                                         vz(v2(i)), vfr, mwf, vol(i), e2, d2);
+                inertial::etaDepthScalar(area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)), vz(cvv(i * kMaxCellVerts + 1)),
+                                         vz(cvv(i * kMaxCellVerts + 2)), vfr, mwf, vol(i), e2, d2);
                 head(i) = e2;
                 depth(i) = d2;
                 if (perot) {
@@ -842,18 +896,23 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         const double S = bc_slope(kk);
                         double h_out = depth(i);
                         if (vfr_face) {
-                            const int e = idx % 3;
-                            const int vv[3] = {v0(i), v1(i), v2(i)};
+                            const int e = idx % kMaxCellVerts;
+                            const int vv[3] = {cvv(i * kMaxCellVerts + 0),
+                                               cvv(i * kMaxCellVerts + 1),
+                                               cvv(i * kMaxCellVerts + 2)};
                             const double za = vz(vv[(e + 1) % 3]);
                             const double zb = vz(vv[(e + 2) % 3]);
                             h_out = inertial::faceDepthFromEta(
                                 head(i), (za < zb) ? za : zb,
                                 (za < zb) ? zb : za);
                         }
-                        if (S > 0.0 && h_out > 0.0 && n > 0.0) {
+                        // Signed slope, as the two CPU marchers: positive
+                        // drains the domain, negative feeds it.
+                        if (S != 0.0 && h_out > 0.0 && n > 0.0) {
+                            const double sgnS = (S > 0.0) ? 1.0 : -1.0;
                             const double h53 =
                                 h_out * std::cbrt(h_out * h_out);
-                            f = -(h53 * std::sqrt(S) / n) * L;
+                            f = -sgnS * (h53 * std::sqrt(S < 0.0 ? -S : S) / n) * L;
                         }
                     } else if (ty == bt_flow || ty == bt_rating) {
                         f = -bc_flow(kk) * L;
@@ -864,8 +923,10 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         const double eta_bc = bc_head(kk);
                         double hf;
                         if (vfr_face) {
-                            const int e = idx % 3;
-                            const int vv[3] = {v0(i), v1(i), v2(i)};
+                            const int e = idx % kMaxCellVerts;
+                            const int vv[3] = {cvv(i * kMaxCellVerts + 0),
+                                               cvv(i * kMaxCellVerts + 1),
+                                               cvv(i * kMaxCellVerts + 2)};
                             const double za = vz(vv[(e + 1) % 3]);
                             const double zb = vz(vv[(e + 2) % 3]);
                             const double eta_hi =
@@ -907,7 +968,7 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         // overshoot backstop: one substep moves the cell AT
                         // MOST to the prescribed stage.
                         const double v_eq = inertial::volumeFromEtaScalar(
-                            area(i), cz(i), vz(v0(i)), vz(v1(i)), vz(v2(i)),
+                            area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)), vz(cvv(i * kMaxCellVerts + 1)), vz(cvv(i * kMaxCellVerts + 2)),
                             vfr, mwf, bc_head(kk));
                         if (f < 0.0) {
                             const double lo =
@@ -927,8 +988,8 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         vol(i) = v_new;
                         bc_accum(kk) += dt_c * f;
                         double e2, d2;
-                        inertial::etaDepthScalar(area(i), cz(i), vz(v0(i)),
-                                                 vz(v1(i)), vz(v2(i)), vfr,
+                        inertial::etaDepthScalar(area(i), cz(i), vz(cvv(i * kMaxCellVerts + 0)),
+                                                 vz(cvv(i * kMaxCellVerts + 1)), vz(cvv(i * kMaxCellVerts + 2)), vfr,
                                                  mwf, vol(i), e2, d2);
                         head(i) = e2;
                         depth(i) = d2;
@@ -936,8 +997,10 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                     // Perot completion: add the boundary edge's contribution
                     // the interior-only rebuild missed (== serial marcher).
                     if (perot && bc_q(kk) != 0.0) {
-                        const int e = idx % 3;
-                        const int vv[3] = {v0(i), v1(i), v2(i)};
+                        const int e = idx % kMaxCellVerts;
+                        const int vv[3] = {cvv(i * kMaxCellVerts + 0),
+                                           cvv(i * kMaxCellVerts + 1),
+                                           cvv(i * kMaxCellVerts + 2)};
                         const int va = vv[(e + 1) % 3];
                         const int vb = vv[(e + 2) % 3];
                         const double mxb = 0.5 * (vxv(va) + vxv(vb));
@@ -960,7 +1023,9 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
              cp_node = d_cp_node_;
         auto cp_cd = d_cp_cd_, cp_area = d_cp_area_;
         auto exch = d_exch_, node_drawn = d_node_drawn_;
+        auto coup_app = d_coupling_applied_;
         auto nh = d_node_head_, nd = d_node_depth_, nv = d_node_volume_;
+        auto nfv = d_node_fullvol_;
         auto ninv = d_node_invert_, nfd = d_node_fulldepth_;
         auto active = d_active_;
         auto vs_ptr = d_vs_ptr_, vs_idx = d_vs_idx_;
@@ -1034,8 +1099,14 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         const double vmax = vol(ci) > 0.0 ? vol(ci) : 0.0;
                         const double cap = beta * vmax / dt_c;
                         if (Q > cap) Q = cap;
-                    } else {         // 1D → 2D spill: node stored budget
-                        const double avail0 = nv(ni) * vol12 - node_drawn(ni);
+                    } else {
+                        // 1D → 2D spill: PONDED budget only (C3). See the CPU
+                        // marcher for why total node storage is wrong — the
+                        // spill exits at the rim and cannot reach below-crown
+                        // conveyance storage. The two backends must agree.
+                        const double ponded =
+                            (nv(ni) > nfv(ni)) ? (nv(ni) - nfv(ni)) : 0.0;
+                        const double avail0 = ponded * vol12 - node_drawn(ni);
                         const double avail = (avail0 > 0.0) ? avail0 : 0.0;
                         if (avail <= 0.0) continue;
                         const double want = -Q * dt_c;
@@ -1043,12 +1114,17 @@ void ExplicitKokkosSurfaceSolver::fireCells(int k, double dt_c) {
                         node_drawn(ni) += take;
                         Q = -take / dt_c;
                     }
+                    // C1: mirror of the CPU marcher — book the signed
+                    // per-cell abstraction where the node exchange actually
+                    // moves water. The two sites above book `coup`, which
+                    // only carries the FORCING API's prescribed rate.
+                    coup_app(ci) += -Q * dt_c;
                     vol(ci) -= Q * dt_c;
                     if (vol(ci) < 0.0) vol(ci) = 0.0;
                     exch(kk) += Q * dt_c;
                     double e2, d2;
-                    inertial::etaDepthScalar(area(ci), cz(ci), vz(v0(ci)),
-                                             vz(v1(ci)), vz(v2(ci)), vfr, mwf,
+                    inertial::etaDepthScalar(area(ci), cz(ci), vz(cvv(ci * kMaxCellVerts + 0)),
+                                             vz(cvv(ci * kMaxCellVerts + 1)), vz(cvv(ci * kMaxCellVerts + 2)), vfr, mwf,
                                              vol(ci), e2, d2);
                     head(ci) = e2;
                     depth(ci) = d2;
@@ -1081,6 +1157,9 @@ void ExplicitKokkosSurfaceSolver::pushForcings() {
     devRefresh(d_rain_, state_->rainfall);
     devRefresh(d_coup_, state_->coupling_flux);
     devRefresh(d_evap_, state_->evap_rate);
+    // Held INFIL_STEP rate (plan §5.5, D-I1) — republished host-side by
+    // Infil2D::updateRates, so it uploads with the other held forcings.
+    devRefresh(d_infil_, state_->infil_rate);
 
     // Boundary values were resolved host-side for this batch.
     const int nbc = static_cast(bc_cell_host_.size());
@@ -1157,14 +1236,33 @@ void ExplicitKokkosSurfaceSolver::publishAndCopyBack(double t_current,
     hostRefresh(state_->depth, d_depth_);
     hostRefresh(state_->edge_flux, d_edge_flux_);
     if (!exch_host_.empty()) hostRefresh(exch_host_, d_exch_);
+
+    // Drain the applied-infiltration accumulator ADDITIVELY: the host array is
+    // consumed and zeroed by the mass balance on the routing-step cadence,
+    // which need not line up with this publish.
+    if (state_->infil_applied.size() == infil_applied_host_.size()) {
+        hostRefresh(infil_applied_host_, d_infil_applied_);
+        for (std::size_t i = 0; i < infil_applied_host_.size(); ++i)
+            state_->infil_applied[i] += infil_applied_host_[i];
+        Kokkos::deep_copy(d_infil_applied_, 0.0);
+        hostRefresh(coupling_applied_host_, d_coupling_applied_);
+        for (std::size_t i = 0; i < coupling_applied_host_.size(); ++i)
+            state_->coupling_applied[i] += coupling_applied_host_[i];
+        Kokkos::deep_copy(d_coupling_applied_, 0.0);
+    }
 }
 
 double ExplicitKokkosSurfaceSolver::advance(double t_current,
                                             double t_target) {
     if (!initialized_ || t_target <= t_current) return t_target;
+    kperf::count_advance();
 
     double t = t_current;
     if (t_last_sync_ > t_current) t_last_sync_ = t_current;
+    // Tools regions (perf review Phase A3): group the advance for external
+    // profilers (nsys via the nvtx connector, kernel-logger). No-ops when no
+    // tool is loaded.
+    Kokkos::Profiling::pushRegion("openswmm_2d_advance_push");
     pushForcings();
     pushNodeState();
     Kokkos::deep_copy(d_bc_accum_, 0.0);
@@ -1172,7 +1270,9 @@ double ExplicitKokkosSurfaceSolver::advance(double t_current,
     Kokkos::deep_copy(d_node_drawn_, 0.0);
     last_steps_ = 0;
     int cycles_since_rebuild = cycles_since_rebuild_;
+    Kokkos::Profiling::popRegion();
 
+    Kokkos::Profiling::pushRegion("openswmm_2d_advance_march");
     while (t < t_target) {
         if (cycles_since_rebuild >= kRebuildEveryCycles) {
             syncAndRebuild(t);
@@ -1189,18 +1289,34 @@ double ExplicitKokkosSurfaceSolver::advance(double t_current,
             break;
         }
 
-        double dt0 = std::min(dt0_, remaining);
-        int nsub = nsub_full;
-        if (nsub_full * dt0_ > remaining) {
-            collapseToGlobalDt();
-            nsub = 1;
-            cycles_since_rebuild = kRebuildEveryCycles;   // rebuild after tail
+        if (nsub_full * dt0_ <= remaining) {
+            runMacroCycle(dt0_, nsub_full);
+            t += nsub_full * dt0_;
+            last_dt_ = dt0_;
+            ++cycles_since_rebuild;
+            continue;
         }
 
-        runMacroCycle(dt0, nsub);
-        t += nsub * dt0;
-        last_dt_ = dt0;
-        ++cycles_since_rebuild;
+        // Tail: split the WHOLE remaining span into nt EQUAL global
+        // substeps (each in (dt0_/2, dt0_] for nt >= 2 — CFL-safe, never
+        // degenerate) and land exactly. collapseToGlobalDt() drops every
+        // active cell/face to tier 0, so runMacroCycle fires nt global
+        // substeps at dt_tail (higher-tier lists are empty). Mirrors the
+        // CPU marcher's tail (ExplicitInertialSolver::advance).
+        if (remaining <= dt0_ * 1.0e-9) {
+            // Sub-ulp residue of the macro landing: no physics.
+            t = t_target;
+            break;
+        }
+        collapseToGlobalDt();
+        const int nt = std::max(
+            1, static_cast(std::ceil(remaining / dt0_)));
+        const double dt_tail = remaining / nt;
+        runMacroCycle(dt_tail, nt);
+        last_dt_ = dt_tail;
+        cycles_since_rebuild = kRebuildEveryCycles;   // rebuild after tail
+        t = t_target;   // exact landing — no 1-ulp re-entry
+        break;
     }
 
     cycles_since_rebuild_ = cycles_since_rebuild;
@@ -1212,8 +1328,11 @@ double ExplicitKokkosSurfaceSolver::advance(double t_current,
             lazySourcesDev(t_target);
         }
     }
+    Kokkos::Profiling::popRegion();
 
+    Kokkos::Profiling::pushRegion("openswmm_2d_advance_publish");
     publishAndCopyBack(t_current, t_target);
+    Kokkos::Profiling::popRegion();
     return t_target;
 }
 
@@ -1241,8 +1360,9 @@ void ExplicitKokkosSurfaceSolver::resyncFromVolumes(double /*t0*/) {
 
 void ExplicitKokkosSurfaceSolver::finalize() {
     if (!initialized_) return;
+    kperf::dump();
     if (!telemetry_path_.empty() && !telemetry_.empty()) {
-        if (std::FILE* f = std::fopen(telemetry_path_.c_str(), "w")) {
+        if (std::FILE* f = openswmm::io::fopen_utf8(telemetry_path_, "w")) {
             std::fprintf(f, "t_s,active_cells,active_frac\n");
             const double nt = std::max(1, mesh_ ? mesh_->n_triangles() : 1);
             for (const auto& [t, n] : telemetry_)
diff --git a/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.hpp b/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.hpp
index a7e186911..608201e09 100644
--- a/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.hpp
+++ b/src/engine/2d/gpu/ExplicitKokkosSurfaceSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExplicitKokkosSurfaceSolver.hpp
  * @brief Kokkos (OpenMP/CUDA/HIP/SYCL) port of the explicit local-inertial
@@ -30,7 +46,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_GPU_EXPLICIT_KOKKOS_SURFACE_SOLVER_HPP
@@ -75,7 +91,7 @@ class ExplicitKokkosSurfaceSolver final : public ISurfaceSolver {
 
     // ---- device geometry (const after initialize) -------------------------
     DView d_tri_area_, d_tri_cz_, d_tri_cx_, d_tri_cy_, d_vz_, d_vx_, d_vy_;
-    IView d_tri_v0_, d_tri_v1_, d_tri_v2_;
+    IView d_cell_v_;                   ///< padded [cell*kMaxCellVerts + k] connectivity
     DView d_vs_wt_;                    ///< vertex-stencil weights
     IView d_vs_ptr_, d_vs_idx_;        ///< vertex-stencil CSR
     DView d_edge_length_, d_mannings_n_;
@@ -87,8 +103,27 @@ class ExplicitKokkosSurfaceSolver final : public ISurfaceSolver {
     // ---- device state -----------------------------------------------------
     DView d_volume_, d_head_, d_depth_;
     DView d_q_, d_faccL_, d_faccR_, d_qcx_, d_qcy_;
-    DView d_rain_, d_coup_, d_evap_;
-    DView d_edge_flux_;                ///< 3·nt flat slots (published)
+    DView d_rain_, d_coup_, d_evap_, d_infil_;
+
+    /// Infiltration APPLIED depth (m) accumulated on device since the last
+    /// publish, then drained ADDITIVELY into state_->infil_applied and zeroed.
+    /// Additive because the host array is consumed on the routing-step cadence
+    /// while this one drains on the publish cadence — a plain overwrite would
+    /// lose or double-count whatever fell between the two.
+    DView d_infil_applied_;
+    /// Signed per-cell coupling exchange volume (m³), mirroring
+    /// SurfaceStateData::coupling_applied. Kept on device beside
+    /// d_infil_applied_ and drained by the same host pass — a GPU run that
+    /// left it zero would report "no coupling" on exactly the decks the
+    /// plugin is chosen for.
+    DView d_coupling_applied_;
+    /// C3: node full_volume (1D ft³) on device, so the spill cap can use the
+    /// PONDED share (volume − full_volume) rather than total node storage.
+    /// Static for the run, uploaded once beside d_node_invert_.
+    DView d_node_fullvol_;
+    std::vector infil_applied_host_;  ///< drain scratch (nt)
+    std::vector coupling_applied_host_;  ///< drain scratch (nt)
+    DView d_edge_flux_;                ///< kMaxCellVerts·nt flat slots (published)
     IView d_active_, d_pin_t0_, d_tier_, d_face_tier_;
     IView d_cells_compact_, d_edges_compact_;  ///< per-tier segments
     IView d_scratch_;                  ///< seed flags scratch (nt)
diff --git a/src/engine/2d/gpu/GpuPluginCuda.cpp b/src/engine/2d/gpu/GpuPluginCuda.cpp
index 536f6015f..301fb8009 100644
--- a/src/engine/2d/gpu/GpuPluginCuda.cpp
+++ b/src/engine/2d/gpu/GpuPluginCuda.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginCuda.cpp
  * @brief Plugin entry points for the Phase 2 Kokkos/CUDA surface solver.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../solver/GpuPluginAbi.h"
diff --git a/src/engine/2d/gpu/GpuPluginHip.cpp b/src/engine/2d/gpu/GpuPluginHip.cpp
index da306b024..e86f1cc23 100644
--- a/src/engine/2d/gpu/GpuPluginHip.cpp
+++ b/src/engine/2d/gpu/GpuPluginHip.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginHip.cpp
  * @brief Plugin entry points for the Phase 5 Kokkos/HIP surface solver (AMD).
@@ -25,7 +41,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../solver/GpuPluginAbi.h"
diff --git a/src/engine/2d/gpu/GpuPluginOmp.cpp b/src/engine/2d/gpu/GpuPluginOmp.cpp
index b2978c8e6..1c14474bb 100644
--- a/src/engine/2d/gpu/GpuPluginOmp.cpp
+++ b/src/engine/2d/gpu/GpuPluginOmp.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginOmp.cpp
  * @brief Plugin entry points for the Phase 1 Kokkos/OpenMP surface solver.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../solver/GpuPluginAbi.h"
@@ -30,23 +46,33 @@
 #include 
 
 namespace {
-void ensureKokkosInitialized() {
+int g_host_threads = 0;   // threads Kokkos was initialised with (0 = not yet)
+
+// Thread-count precedence (THREAD_LIMITS_AND_OVERSUBSCRIPTION_PLAN §5.2):
+//   1. OPENSWMM_2D_THREADS env         — operator A/B override, always wins
+//   2. requested_threads (ABI v4)      — [OPTIONS] THREADS handed over by the core
+//   3. Kokkos default                  — OMP_NUM_THREADS, else omp_get_max_threads()
+// Kokkos initialises once per process: the first solver built in a process
+// fixes the count for every later one (the core warns when a later request
+// differs — see SurfaceSolverFactory).
+void ensureKokkosInitialized(int requested_threads) {
     if (!Kokkos::is_initialized() && !Kokkos::is_finalized()) {
-        // Thread count: OPENSWMM_2D_THREADS wins, else Kokkos' own defaults
-        // apply (OMP_NUM_THREADS, else all hardware threads — including
-        // efficiency cores on Apple Silicon, which drag the fenced kernel
-        // loops; set OPENSWMM_2D_THREADS to the performance-core count there).
-        // [OPTIONS] THREADS deliberately does NOT govern the plugin: it caps
-        // the host/serial-path loops only.
         Kokkos::InitializationSettings settings;
+        int chosen = 0;
         if (const char* env = std::getenv("OPENSWMM_2D_THREADS")) {
             char* endp = nullptr;
             const long n = std::strtol(env, &endp, 10);
-            if (endp != env && n > 0)
-                settings.set_num_threads(static_cast(n));
+            if (endp != env && n > 0) chosen = static_cast(n);
         }
+        if (chosen <= 0 && requested_threads > 0) chosen = requested_threads;
+        if (chosen > 0) settings.set_num_threads(chosen);
         Kokkos::initialize(settings);
     }
+#if defined(KOKKOS_ENABLE_OPENMP)
+    g_host_threads = Kokkos::OpenMP().concurrency();
+#else
+    g_host_threads = Kokkos::DefaultHostExecutionSpace().concurrency();
+#endif
 }
 } // namespace
 
@@ -62,9 +88,14 @@ openswmm_gpu_probe(OpenSwmmGpuProbe* out) {
     return 0;  // usable backend present
 }
 
+extern "C" OPENSWMM_GPU_ABI int
+openswmm_gpu_host_threads(void) {
+    return g_host_threads;
+}
+
 extern "C" OPENSWMM_GPU_ABI void*
-openswmm_make_gpu_explicit_solver(const OpenSwmmGpuProbe* /*probe*/) {
-    ensureKokkosInitialized();
+openswmm_make_gpu_explicit_solver(const OpenSwmmGpuProbe* probe) {
+    ensureKokkosInitialized(probe ? probe->requested_threads : 0);
     openswmm::twoD::ISurfaceSolver* solver =
         new openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver();
     return static_cast(solver);
diff --git a/src/engine/2d/gpu/GpuPluginStub.cpp b/src/engine/2d/gpu/GpuPluginStub.cpp
index ff89ea603..848227138 100644
--- a/src/engine/2d/gpu/GpuPluginStub.cpp
+++ b/src/engine/2d/gpu/GpuPluginStub.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginStub.cpp
  * @brief Placeholder GPU surface-solver plugin (Phase 0 scaffold).
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../solver/GpuPluginAbi.h"
diff --git a/src/engine/2d/gpu/GpuPluginSycl.cpp b/src/engine/2d/gpu/GpuPluginSycl.cpp
index 0ca11a86d..4714f7609 100644
--- a/src/engine/2d/gpu/GpuPluginSycl.cpp
+++ b/src/engine/2d/gpu/GpuPluginSycl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginSycl.cpp
  * @brief Plugin entry points for the Phase 5 Kokkos/SYCL surface solver (Intel).
@@ -31,7 +47,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../solver/GpuPluginAbi.h"
diff --git a/src/engine/2d/gpu/KokkosPerfCounters.hpp b/src/engine/2d/gpu/KokkosPerfCounters.hpp
new file mode 100644
index 000000000..9ab63e09b
--- /dev/null
+++ b/src/engine/2d/gpu/KokkosPerfCounters.hpp
@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file KokkosPerfCounters.hpp
+ * @brief OPENSWMM_PERF=1 launch/fence/deep_copy counters for the Kokkos
+ *        surface solver, riding the in-process Kokkos::Tools callbacks.
+ *
+ * @details Phase A2 of plans/CPU_GPU_PERF_REVIEW_PLAN_2026-09-02.md. The
+ *          counters answer three questions the wall clock cannot: how many
+ *          kernel launches an advance() costs, how long the host blocks in
+ *          fences, and how many bytes cross host<->device per advance. They
+ *          hook Kokkos::Tools::Experimental::set_*_callback rather than the
+ *          ~25 dispatch sites so every launch — including implicit fences and
+ *          the deep_copies inside devCopy/devRefresh — is counted without a
+ *          line of code in the hot path.
+ *
+ *          Registration is skipped when an external tool is loaded
+ *          (KOKKOS_TOOLS_LIBS / KOKKOS_PROFILE_LIBRARY): Kokkos holds ONE
+ *          callback set, and stealing it would blind nsys/kernel-logger,
+ *          which attribute by the same kernel labels (plan Phase A3). Use one
+ *          or the other per run.
+ *
+ *          Per-kernel `s=` is HOST-SIDE wall between the begin/end dispatch
+ *          callbacks: on the OpenMP backend that is the kernel's execution
+ *          time (dispatch blocks); on CUDA/HIP it is launch overhead only —
+ *          device time lives in the fence/nsys numbers.
+ *
+ *          Counters are plain (non-atomic) longs: the engine drives the
+ *          solver from one thread, and Kokkos dispatch callbacks fire on the
+ *          calling thread. Zero cost when OPENSWMM_PERF is unset (nothing is
+ *          registered at all).
+ *
+ * @ingroup engine_2d_gpu
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_GPU_KOKKOS_PERF_COUNTERS_HPP
+#define OPENSWMM_ENGINE_2D_GPU_KOKKOS_PERF_COUNTERS_HPP
+
+#include 
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../core/PerfTimers.hpp"
+
+namespace openswmm::twoD::gpu::kperf {
+
+struct KernelEntry {
+    std::string label;
+    long   n   = 0;    ///< launches
+    double sec = 0.0;  ///< host-side dispatch wall (== execution on OMP)
+};
+
+struct Counters {
+    long n_advance = 0;
+    long n_launch  = 0;   ///< parallel_for + reduce + scan
+    long n_fence   = 0;
+    double sec_fence = 0.0;
+    long n_deep_copy = 0;
+    unsigned long long bytes_h2d = 0, bytes_d2h = 0, bytes_same = 0;
+    std::vector kernels;             ///< indexed by kernel id
+    std::map label_id;
+};
+
+inline Counters g;
+
+namespace detail {
+
+using clock = std::chrono::steady_clock;
+
+/// Dispatch begin/end pairs nest strictly on the calling thread, so a stack
+/// of start times pairs them; the uint64_t Kokkos hands back carries the
+/// kernel id assigned at begin.
+inline std::vector dispatch_t0;
+inline std::vector fence_t0;
+
+inline void begin_dispatch(const char* name, std::uint32_t /*devid*/,
+                           std::uint64_t* kID) {
+    const auto it = g.label_id.find(name);
+    std::uint64_t id;
+    if (it == g.label_id.end()) {
+        id = g.kernels.size();
+        g.label_id.emplace(name, id);
+        g.kernels.push_back({name, 0, 0.0});
+    } else {
+        id = it->second;
+    }
+    *kID = id;
+    ++g.n_launch;
+    dispatch_t0.push_back(clock::now());
+}
+
+inline void end_dispatch(std::uint64_t kID) {
+    if (dispatch_t0.empty()) return;
+    const double dt = std::chrono::duration(
+        clock::now() - dispatch_t0.back()).count();
+    dispatch_t0.pop_back();
+    if (kID < g.kernels.size()) {
+        ++g.kernels[kID].n;
+        g.kernels[kID].sec += dt;
+    }
+}
+
+inline void begin_fence(const char* /*name*/, std::uint32_t /*devid*/,
+                        std::uint64_t* handle) {
+    *handle = 0;
+    fence_t0.push_back(clock::now());
+}
+
+inline void end_fence(std::uint64_t /*handle*/) {
+    if (fence_t0.empty()) return;
+    g.sec_fence += std::chrono::duration(
+        clock::now() - fence_t0.back()).count();
+    fence_t0.pop_back();
+    ++g.n_fence;
+}
+
+inline void begin_deep_copy(Kokkos_Profiling_SpaceHandle dst, const char*,
+                            const void*,
+                            Kokkos_Profiling_SpaceHandle src, const char*,
+                            const void*, std::uint64_t size) {
+    ++g.n_deep_copy;
+    const bool dst_host = std::strncmp(dst.name, "Host", 4) == 0;
+    const bool src_host = std::strncmp(src.name, "Host", 4) == 0;
+    if (src_host && !dst_host)      g.bytes_h2d  += size;
+    else if (dst_host && !src_host) g.bytes_d2h  += size;
+    else                            g.bytes_same += size;  // OMP backend: all
+}
+
+} // namespace detail
+
+/// Registers the counting callbacks once per process. No-op unless
+/// OPENSWMM_PERF is set; defers to an external Kokkos tool if one is loaded.
+inline void install() {
+    static const bool done = [] {
+        if (!perf::enabled()) return false;
+        if (std::getenv("KOKKOS_TOOLS_LIBS") ||
+            std::getenv("KOKKOS_PROFILE_LIBRARY")) {
+            std::fprintf(stderr,
+                "[PERF-2D-KOKKOS] external Kokkos tool loaded; in-process "
+                "counters disabled for this run.\n");
+            return false;
+        }
+        namespace KTE = Kokkos::Tools::Experimental;
+        KTE::set_begin_parallel_for_callback(detail::begin_dispatch);
+        KTE::set_end_parallel_for_callback(detail::end_dispatch);
+        KTE::set_begin_parallel_reduce_callback(detail::begin_dispatch);
+        KTE::set_end_parallel_reduce_callback(detail::end_dispatch);
+        KTE::set_begin_parallel_scan_callback(detail::begin_dispatch);
+        KTE::set_end_parallel_scan_callback(detail::end_dispatch);
+        KTE::set_begin_fence_callback(detail::begin_fence);
+        KTE::set_end_fence_callback(detail::end_fence);
+        KTE::set_begin_deep_copy_callback(detail::begin_deep_copy);
+        return true;
+    }();
+    (void)done;
+}
+
+inline void reset() {
+    g = Counters{};
+}
+
+inline void count_advance() {
+    if (perf::enabled()) ++g.n_advance;
+}
+
+/// One [PERF-2D-KOKKOS] summary line plus one line per kernel label, sorted
+/// by host-side dispatch wall descending. Same key=value contract as
+/// [PERF-FV] / [PERF-LOAD]; tests/benchmarks scripts can scrape it.
+inline void dump() {
+    if (!perf::enabled() || g.n_advance == 0) return;
+    const double adv = static_cast(g.n_advance);
+    std::fprintf(stderr,
+        "[PERF-2D-KOKKOS] advances=%ld launches=%ld launches_per_advance=%.1f "
+        "fences=%ld fence_s=%.4f deep_copies=%ld "
+        "h2d_bytes=%llu d2h_bytes=%llu samespace_bytes=%llu "
+        "h2d_bytes_per_advance=%.0f d2h_bytes_per_advance=%.0f\n",
+        g.n_advance, g.n_launch, g.n_launch / adv,
+        g.n_fence, g.sec_fence, g.n_deep_copy,
+        g.bytes_h2d, g.bytes_d2h, g.bytes_same,
+        g.bytes_h2d / adv, g.bytes_d2h / adv);
+    std::vector order;
+    order.reserve(g.kernels.size());
+    for (const auto& k : g.kernels) order.push_back(&k);
+    std::sort(order.begin(), order.end(),
+              [](const KernelEntry* a, const KernelEntry* b) {
+                  return a->sec > b->sec;
+              });
+    for (const KernelEntry* k : order)
+        std::fprintf(stderr,
+            "[PERF-2D-KOKKOS-KERNEL] name=%s n=%ld s=%.4f per_advance=%.1f\n",
+            k->label.c_str(), k->n, k->sec, k->n / adv);
+}
+
+} // namespace openswmm::twoD::gpu::kperf
+
+#endif // OPENSWMM_ENGINE_2D_GPU_KOKKOS_PERF_COUNTERS_HPP
diff --git a/src/engine/2d/gpu/KokkosTypes.hpp b/src/engine/2d/gpu/KokkosTypes.hpp
index 5e4024c49..31ae70d25 100644
--- a/src/engine/2d/gpu/KokkosTypes.hpp
+++ b/src/engine/2d/gpu/KokkosTypes.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file KokkosTypes.hpp
  * @brief Execution-space selection + view aliases for the Kokkos marcher plugin.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_GPU_KOKKOS_TYPES_HPP
diff --git a/src/engine/2d/gw/GwTransportData.hpp b/src/engine/2d/gw/GwTransportData.hpp
new file mode 100644
index 000000000..109ac1343
--- /dev/null
+++ b/src/engine/2d/gw/GwTransportData.hpp
@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file GwTransportData.hpp
+ * @brief U4 (2026-09-07) — authoring state for subsurface (groundwater)
+ *        transport: `[GW_TRANSPORT_OPTIONS]`, `[GW_TRANSPORT_PARAMS]`,
+ *        `[GW_SORPTION]`, `[GW_INITIAL_QUALITY]`, `[GW_BOUNDARY_QUALITY]`
+ *        and `[GW_SOURCES]`.
+ *
+ * @details **Authoring only in this release.** The two-zone integrated
+ *          groundwater kernel (G1 of the two-zone plan) does not exist yet,
+ *          so these rows are parsed, validated against the mesh and the
+ *          species registry, held here, round-tripped by the writer and
+ *          exposed through `openswmm_gw_transport.h` — and a run emits ONE
+ *          warning saying the kernel is not available. That is the
+ *          deliberate shape: a user can author, save, reopen and share a
+ *          complete subsurface-transport model before the solver lands, and
+ *          nothing about the file changes when it does.
+ *
+ *          **Cell-generic** (the tri/quad amendment): every scope is a CELL
+ *          index or a TAG, never a "triangle"; an edge is `EDGE 0..nv-1` of
+ *          its cell, validated against `MeshData::cell_nv`. No `/3`, no
+ *          `* 3`, no `tri_` naming.
+ *
+ *          Resolution ladder, the same one `[2D_INFILTRATION]` and
+ *          `[2D_INITIAL_QUALITY]` use: `*` < `TAG` < `CELL`, applied by
+ *          ORDER (later rows win) rather than by comparison.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_GW_TRANSPORT_DATA_HPP
+#define OPENSWMM_ENGINE_2D_GW_TRANSPORT_DATA_HPP
+
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+/// Which zone of the two-zone column a row addresses.
+enum class GwZone : int8_t {
+    SAT   = 0,   ///< saturated (lower) zone
+    UNSAT = 1,   ///< unsaturated (upper) zone
+    LAYER = 2    ///< an explicit layer index (`layer` field)
+};
+
+/// Scope of a per-cell row.
+enum class GwScope : int8_t {
+    GLOBAL = 0,  ///< the `*` row
+    TAG    = 1,  ///< every cell carrying `tag`
+    CELL   = 2   ///< one cell, by 0-based index (1-based in the file)
+};
+
+/// `[GW_TRANSPORT_OPTIONS]` — the subsurface column of the Domain × Species
+/// matrix plus the process switches. Defaults reproduce "everything the
+/// kernel would carry", so a deck that only names the section gets the
+/// full model when the kernel arrives.
+struct GwTransportOptions {
+    bool transport_pollutants  = true;
+    bool transport_msx         = true;
+    bool transport_age         = true;
+    bool transport_temperature = true;
+    bool dispersion            = true;   ///< α_L / α_T / D_m active
+    bool conduction            = true;   ///< vertical + lateral heat conduction
+    /// SURFACE_THERMAL_BC kind and its argument: AIR | SURFACE_WATER |
+    /// FIXED  | TIMESERIES .
+    std::string surface_thermal_bc = "AIR";
+    std::string surface_thermal_arg;
+    /// DEEP_THERMAL_BC: GEOTHERMAL_FLUX  | FIXED_TEMP  |
+    /// TIMESERIES , with DEPTH  in the `deep_depth` field.
+    std::string deep_thermal_bc = "GEOTHERMAL_FLUX";
+    std::string deep_thermal_arg;
+    double      deep_depth = 0.0;
+    /// THERMAL_MIXING ARITHMETIC | GEOMETRIC.
+    std::string thermal_mixing = "ARITHMETIC";
+    /// Explicit diffusion Courant number for the kernel's tier bound.
+    double c_diff = 0.4;
+    /// True once any [GW_*] section was seen — the run-time warning and the
+    /// writer both key on it, so a deck with no subsurface authoring is
+    /// byte-identical.
+    bool authored = false;
+};
+
+/// One `[GW_TRANSPORT_PARAMS]` row: solute + thermal matrix properties.
+struct GwParamsRow {
+    GwScope     scope = GwScope::GLOBAL;
+    std::string tag;              ///< TAG scope
+    int         cell = -1;        ///< CELL scope (0-based)
+    double rho_s    = 2650.0;     ///< grain density (kg/m3)
+    double c_s      = 880.0;      ///< grain specific heat (J/kg/K)
+    double lambda_s = 2.0;        ///< grain thermal conductivity (W/m/K)
+    double a_s      = 0.0;        ///< specific surface area (m2/kg)
+    double alpha_L  = 1.0;        ///< longitudinal dispersivity (m)
+    double alpha_T  = 0.1;        ///< transverse dispersivity (m)
+    double D_m      = 1.0e-9;     ///< molecular diffusivity (m2/s)
+    double D_v      = 1.0e-9;     ///< vapour diffusivity (m2/s)
+    double geo_flux = 0.065;      ///< geothermal flux (W/m2) or deep temp (degC)
+};
+
+/// One `[GW_SORPTION]` row: retardation input for one species in one scope.
+struct GwSorptionRow {
+    GwScope     scope = GwScope::GLOBAL;
+    std::string tag;
+    int         cell = -1;
+    std::string species;
+    double      kd    = 0.0;      ///< partition coefficient (L/kg)
+    double      decay = -1.0;     ///< 1/day; < 0 = "use [POLLUTANTS] kdecay"
+};
+
+/// One `[GW_INITIAL_QUALITY]` row.
+struct GwInitialQualityRow {
+    GwScope     scope = GwScope::GLOBAL;
+    std::string tag;
+    int         cell  = -1;
+    GwZone      zone  = GwZone::SAT;
+    int         layer = -1;       ///< LAYER zone only
+    std::string species;
+    double      value = 0.0;
+};
+
+/// One `[GW_BOUNDARY_QUALITY]` row — a lateral edge BC.
+struct GwBoundaryQualityRow {
+    int         cell    = -1;     ///< 0-based cell index
+    int         edge    = -1;     ///< local edge 0..nv-1 of that cell
+    std::string species;
+    /// CONC | TS | MASSFLUX | HEATFLUX.
+    std::string kind    = "CONC";
+    double      value   = 0.0;    ///< constant form
+    std::string ts_name;          ///< TS form (kind == "TS", or a TS argument)
+};
+
+/// One `[GW_SOURCES]` species term.
+struct GwSourceSpeciesTerm {
+    std::string species;
+    std::string kind = "CONC";    ///< CONC | MASS
+    double      value = 0.0;
+    std::string ts_name;
+};
+
+/// One `[GW_SOURCES]` row — a well / point source or sink.
+struct GwSourceRow {
+    std::string name;
+    GwScope     scope = GwScope::CELL;   ///< CELL | TAG | (XY resolves to CELL)
+    std::string tag;
+    int         cell = -1;
+    double      x = 0.0, y = 0.0;        ///< XY form (retained for the writer)
+    bool        by_xy = false;
+    double      flow = 0.0;              ///< m3/s, + inject / − extract
+    std::string flow_ts;                 ///< when the FLOW argument is a series
+    std::vector species;
+};
+
+/**
+ * @brief Every `[GW_*]` authoring row of one model.
+ *
+ * @details Owned by SurfaceRouter2D (the 2D module's data home) and reached
+ *          through `SimulationContext::twod_io.gw` so the writer, the C API
+ *          and the GeoPackage path can read it without depending on the
+ *          router.
+ */
+struct GwTransportData {
+    GwTransportOptions               options;
+    std::vector         params;
+    std::vector       sorption;
+    std::vector initial_quality;
+    /// `[GW_INITIAL_QUALITY] FILE ` (element,zone,species,value).
+    std::string                      initial_quality_file;
+    std::vector boundary_quality;
+    std::vector         sources;
+
+    bool empty() const noexcept {
+        return !options.authored && params.empty() && sorption.empty() &&
+               initial_quality.empty() && initial_quality_file.empty() &&
+               boundary_quality.empty() && sources.empty();
+    }
+
+    void clear() { *this = GwTransportData{}; }
+};
+
+const char* gwZoneToken(GwZone z) noexcept;
+bool        parseGwZone(const std::string& token, GwZone& z) noexcept;
+const char* gwScopeToken(GwScope s) noexcept;
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_GW_TRANSPORT_DATA_HPP
diff --git a/src/engine/2d/gw/GwTransportSections.cpp b/src/engine/2d/gw/GwTransportSections.cpp
new file mode 100644
index 000000000..da4ad0042
--- /dev/null
+++ b/src/engine/2d/gw/GwTransportSections.cpp
@@ -0,0 +1,644 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file GwTransportSections.cpp
+ * @brief U4 — `[GW_*]` parsers, registration and resolution (see header).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "GwTransportSections.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+
+#include "../data/MeshData.hpp"
+#include "../../core/PathResolver.hpp"
+#include "../../core/SimulationContext.hpp"
+#include "../../input/InputParseUtils.hpp"
+#include "../../input/Tokenizer.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+namespace {
+
+bool iequals(const std::string& a, const char* b) {
+    std::size_t i = 0;
+    for (; i < a.size() && b[i]; ++i)
+        if (std::toupper(static_cast(a[i])) !=
+            std::toupper(static_cast(b[i]))) return false;
+    return i == a.size() && b[i] == '\0';
+}
+
+bool num(const std::string& s, double& v) {
+    auto [p, ec] = openswmm::from_chars_double(s.data(), s.data() + s.size(), v);
+    return ec == std::errc{} && p == s.data() + s.size() && std::isfinite(v);
+}
+
+bool inum(const std::string& s, int& v) {
+    double d = 0.0;
+    if (!num(s, d)) return false;
+    v = static_cast(d);
+    return static_cast(v) == d;
+}
+
+/// `* | TAG  | CELL ` starting at tokens[0]; advances @p at past it.
+/// CELL is 1-BASED in the file (the upper bound is resolveGwTransport's).
+std::string parseScope(const std::vector& tokens, const char* sec,
+                       GwScope& scope, std::string& tag, int& cell,
+                       std::size_t& at) {
+    if (tokens.empty()) return std::string(sec) + " empty row";
+    if (tokens[0] == "*") { scope = GwScope::GLOBAL; at = 1; return {}; }
+    if (iequals(tokens[0], "TAG")) {
+        if (tokens.size() < 2) return std::string(sec) + " TAG needs a name";
+        scope = GwScope::TAG;
+        tag   = tokens[1];
+        at    = 2;
+        return {};
+    }
+    if (iequals(tokens[0], "CELL")) {
+        if (tokens.size() < 2) return std::string(sec) + " CELL needs an index";
+        int n = 0;
+        if (!inum(tokens[1], n) || n < 1)
+            return std::string(sec) + " invalid CELL index (1-based): " + tokens[1];
+        scope = GwScope::CELL;
+        cell  = n - 1;
+        at    = 2;
+        return {};
+    }
+    return std::string(sec) + " row must start with CELL, TAG or '*': " + tokens[0];
+}
+
+/// A `VALUE | TS-NAME` argument: numeric fills @p v, otherwise @p ts.
+void valueOrSeries(const std::string& token, double& v, std::string& ts) {
+    if (num(token, v)) { ts.clear(); return; }
+    v = 0.0;
+    ts = token;
+}
+
+input::SectionHandler makeGwHandler(
+    std::function&)> lp,
+    GwTransportOptions& opts) {
+    return [lp = std::move(lp), &opts](openswmm::SimulationContext& ctx,
+                                       const std::vector& lines) {
+        opts.authored = true;
+        for (const auto& raw : lines) {
+            auto tokens = openswmm::input::Tokenizer::tokenize(raw);
+            if (tokens.empty()) continue;
+            const std::string err = lp(tokens);
+            if (!err.empty()) {
+                ctx.error_code    = 5;  // SWMM_ERR_PARSE
+                ctx.error_message = "[GW] " + err + " — line: " + raw;
+                return;
+            }
+        }
+    };
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// Tokens
+// ---------------------------------------------------------------------------
+
+const char* gwZoneToken(GwZone z) noexcept {
+    switch (z) {
+        case GwZone::SAT:   return "SAT";
+        case GwZone::UNSAT: return "UNSAT";
+        case GwZone::LAYER: return "LAYER";
+    }
+    return "SAT";
+}
+
+bool parseGwZone(const std::string& token, GwZone& z) noexcept {
+    if (iequals(token, "SAT"))   { z = GwZone::SAT;   return true; }
+    if (iequals(token, "UNSAT")) { z = GwZone::UNSAT; return true; }
+    if (iequals(token, "LAYER")) { z = GwZone::LAYER; return true; }
+    return false;
+}
+
+const char* gwScopeToken(GwScope s) noexcept {
+    switch (s) {
+        case GwScope::GLOBAL: return "*";
+        case GwScope::TAG:    return "TAG";
+        case GwScope::CELL:   return "CELL";
+    }
+    return "*";
+}
+
+// ---------------------------------------------------------------------------
+// [GW_TRANSPORT_OPTIONS]
+// ---------------------------------------------------------------------------
+
+std::string parseGwTransportOptionsLine(const std::vector& tokens,
+                                        GwTransportOptions& o) {
+    if (tokens.empty()) return {};
+    if (tokens.size() < 2)
+        return "[GW_TRANSPORT_OPTIONS] needs PARAMETER VALUE";
+    const std::string& k = tokens[0];
+    const std::string& v = tokens[1];
+
+    auto yesno = [&](bool& field) -> std::string {
+        if      (iequals(v, "YES") || iequals(v, "ON"))  field = true;
+        else if (iequals(v, "NO")  || iequals(v, "OFF")) field = false;
+        else return "[GW_TRANSPORT_OPTIONS] " + k + ": expected YES|NO, got " + v;
+        return {};
+    };
+
+    if (iequals(k, "TRANSPORT_POLLUTANTS"))  return yesno(o.transport_pollutants);
+    if (iequals(k, "TRANSPORT_MSX"))         return yesno(o.transport_msx);
+    if (iequals(k, "TRANSPORT_AGE"))         return yesno(o.transport_age);
+    if (iequals(k, "TRANSPORT_TEMPERATURE")) return yesno(o.transport_temperature);
+    if (iequals(k, "DISPERSION"))            return yesno(o.dispersion);
+    if (iequals(k, "CONDUCTION"))            return yesno(o.conduction);
+
+    if (iequals(k, "SURFACE_THERMAL_BC")) {
+        if (iequals(v, "AIR") || iequals(v, "SURFACE_WATER")) {
+            o.surface_thermal_bc = iequals(v, "AIR") ? "AIR" : "SURFACE_WATER";
+            o.surface_thermal_arg.clear();
+        } else if (iequals(v, "FIXED") || iequals(v, "TIMESERIES")) {
+            if (tokens.size() < 3)
+                return "[GW_TRANSPORT_OPTIONS] SURFACE_THERMAL_BC " + v +
+                       " needs a value or series name";
+            o.surface_thermal_bc  = iequals(v, "FIXED") ? "FIXED" : "TIMESERIES";
+            o.surface_thermal_arg = tokens[2];
+            if (o.surface_thermal_bc == "FIXED") {
+                double t = 0.0;
+                if (!num(tokens[2], t))
+                    return "[GW_TRANSPORT_OPTIONS] SURFACE_THERMAL_BC FIXED "
+                           "needs a temperature, got " + tokens[2];
+            }
+        } else {
+            return "[GW_TRANSPORT_OPTIONS] SURFACE_THERMAL_BC: expected "
+                   "AIR|SURFACE_WATER|FIXED |TIMESERIES , got " + v;
+        }
+        return {};
+    }
+
+    if (iequals(k, "DEEP_THERMAL_BC")) {
+        if (!(iequals(v, "GEOTHERMAL_FLUX") || iequals(v, "FIXED_TEMP") ||
+              iequals(v, "TIMESERIES")))
+            return "[GW_TRANSPORT_OPTIONS] DEEP_THERMAL_BC: expected "
+                   "GEOTHERMAL_FLUX|FIXED_TEMP|TIMESERIES, got " + v;
+        if (tokens.size() < 3)
+            return "[GW_TRANSPORT_OPTIONS] DEEP_THERMAL_BC needs a value or "
+                   "series name";
+        o.deep_thermal_bc  = iequals(v, "GEOTHERMAL_FLUX") ? "GEOTHERMAL_FLUX"
+                           : iequals(v, "FIXED_TEMP")      ? "FIXED_TEMP"
+                                                           : "TIMESERIES";
+        o.deep_thermal_arg = tokens[2];
+        if (o.deep_thermal_bc != "TIMESERIES") {
+            double d = 0.0;
+            if (!num(tokens[2], d))
+                return "[GW_TRANSPORT_OPTIONS] DEEP_THERMAL_BC " +
+                       o.deep_thermal_bc + " needs a number, got " + tokens[2];
+        }
+        // Optional trailing `DEPTH `.
+        if (tokens.size() >= 5 && iequals(tokens[3], "DEPTH")) {
+            double z = 0.0;
+            if (!num(tokens[4], z) || z < 0.0)
+                return "[GW_TRANSPORT_OPTIONS] DEEP_THERMAL_BC DEPTH must be "
+                       ">= 0, got " + tokens[4];
+            o.deep_depth = z;
+        }
+        return {};
+    }
+
+    if (iequals(k, "THERMAL_MIXING")) {
+        if      (iequals(v, "ARITHMETIC")) o.thermal_mixing = "ARITHMETIC";
+        else if (iequals(v, "GEOMETRIC"))  o.thermal_mixing = "GEOMETRIC";
+        else return "[GW_TRANSPORT_OPTIONS] THERMAL_MIXING: expected "
+                    "ARITHMETIC|GEOMETRIC, got " + v;
+        return {};
+    }
+
+    if (iequals(k, "C_DIFF")) {
+        double c = 0.0;
+        if (!num(v, c) || c <= 0.0 || c > 1.0)
+            return "[GW_TRANSPORT_OPTIONS] C_DIFF must be in (0, 1], got " + v;
+        o.c_diff = c;
+        return {};
+    }
+
+    return "Unknown GW_TRANSPORT_OPTIONS parameter: " + k;
+}
+
+// ---------------------------------------------------------------------------
+// [GW_TRANSPORT_PARAMS]
+// ---------------------------------------------------------------------------
+
+std::string parseGwParamsLine(const std::vector& tokens,
+                              std::vector& rows) {
+    if (tokens.empty()) return {};
+    GwParamsRow r;
+    std::size_t at = 0;
+    const std::string e =
+        parseScope(tokens, "[GW_TRANSPORT_PARAMS]", r.scope, r.tag, r.cell, at);
+    if (!e.empty()) return e;
+
+    // Positional, all optional after the scope — an omitted column keeps the
+    // struct default (which is the plan's example row).
+    double* slots[] = {&r.rho_s, &r.c_s, &r.lambda_s, &r.a_s, &r.alpha_L,
+                       &r.alpha_T, &r.D_m, &r.D_v, &r.geo_flux};
+    const char* names[] = {"rho_s", "c_s", "lambda_s", "a_s", "alpha_L",
+                           "alpha_T", "D_m", "D_v", "geo_flux"};
+    constexpr int kSlots = 9;
+    for (std::size_t k = at; k < tokens.size(); ++k) {
+        const std::size_t i = k - at;
+        if (i >= static_cast(kSlots))
+            return "[GW_TRANSPORT_PARAMS] too many columns (max 9 after the scope)";
+        if (tokens[k] == "-") continue;   // unset — keep the default
+        double v = 0.0;
+        if (!num(tokens[k], v))
+            return std::string("[GW_TRANSPORT_PARAMS] invalid ") + names[i] +
+                   ": " + tokens[k];
+        // Only geo_flux (which may also be a deep temperature) is signed.
+        if (v < 0.0 && i != 8)
+            return std::string("[GW_TRANSPORT_PARAMS] ") + names[i] +
+                   " must be >= 0, got " + tokens[k];
+        *slots[i] = v;
+    }
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// [GW_SORPTION]
+// ---------------------------------------------------------------------------
+
+std::string parseGwSorptionLine(const std::vector& tokens,
+                                std::vector& rows) {
+    if (tokens.empty()) return {};
+    GwSorptionRow r;
+    std::size_t at = 0;
+    const std::string e =
+        parseScope(tokens, "[GW_SORPTION]", r.scope, r.tag, r.cell, at);
+    if (!e.empty()) return e;
+    if (tokens.size() < at + 2)
+        return "[GW_SORPTION] needs SCOPE SPECIES Kd [decay]";
+    r.species = tokens[at];
+    if (!num(tokens[at + 1], r.kd) || r.kd < 0.0)
+        return "[GW_SORPTION] Kd must be a finite value >= 0, got " +
+               tokens[at + 1];
+    if (tokens.size() > at + 2 && tokens[at + 2] != "-") {
+        if (!num(tokens[at + 2], r.decay) || r.decay < 0.0)
+            return "[GW_SORPTION] decay must be a finite value >= 0, got " +
+                   tokens[at + 2];
+    }
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// [GW_INITIAL_QUALITY]
+// ---------------------------------------------------------------------------
+
+std::string parseGwInitialQualityLine(const std::vector& tokens,
+                                      std::vector& rows,
+                                      std::string& file) {
+    if (tokens.empty()) return {};
+    if (iequals(tokens[0], "FILE")) {
+        if (tokens.size() < 2) return "[GW_INITIAL_QUALITY] FILE needs a path";
+        file = tokens[1];
+        return {};
+    }
+    GwInitialQualityRow r;
+    std::size_t at = 0;
+    const std::string e =
+        parseScope(tokens, "[GW_INITIAL_QUALITY]", r.scope, r.tag, r.cell, at);
+    if (!e.empty()) return e;
+    if (tokens.size() < at + 3)
+        return "[GW_INITIAL_QUALITY] needs SCOPE ZONE SPECIES VALUE";
+    if (!parseGwZone(tokens[at], r.zone))
+        return "[GW_INITIAL_QUALITY] ZONE must be SAT, UNSAT or LAYER , got " +
+               tokens[at];
+    ++at;
+    if (r.zone == GwZone::LAYER) {
+        if (tokens.size() < at + 3)
+            return "[GW_INITIAL_QUALITY] LAYER needs  SPECIES VALUE";
+        if (!inum(tokens[at], r.layer) || r.layer < 1)
+            return "[GW_INITIAL_QUALITY] LAYER index must be >= 1, got " +
+                   tokens[at];
+        ++at;
+    }
+    r.species = tokens[at];
+    if (!num(tokens[at + 1], r.value))
+        return "[GW_INITIAL_QUALITY] VALUE must be a finite number, got " +
+               tokens[at + 1];
+    // Temperature (degC) and age (signed, D-NS1) may be negative; a
+    // concentration may not. The species kind is only known at resolve, so
+    // the sign check lives there.
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// [GW_BOUNDARY_QUALITY]
+// ---------------------------------------------------------------------------
+
+std::string parseGwBoundaryQualityLine(const std::vector& tokens,
+                                       std::vector& rows) {
+    if (tokens.empty()) return {};
+    if (tokens.size() < 5)
+        return "[GW_BOUNDARY_QUALITY] needs CELL EDGE SPECIES KIND VALUE";
+    GwBoundaryQualityRow r;
+    int cell = 0;
+    if (!inum(tokens[0], cell) || cell < 1)
+        return "[GW_BOUNDARY_QUALITY] invalid CELL index (1-based): " + tokens[0];
+    r.cell = cell - 1;
+    // EDGE is the LOCAL edge of that cell, 0..nv-1 — cell-generic, so the
+    // upper bound is the cell's own vertex count, checked at resolve.
+    if (!inum(tokens[1], r.edge) || r.edge < 0)
+        return "[GW_BOUNDARY_QUALITY] invalid EDGE (0-based, 0..nv-1): " + tokens[1];
+    r.species = tokens[2];
+    const std::string& kind = tokens[3];
+    if      (iequals(kind, "CONC"))     r.kind = "CONC";
+    else if (iequals(kind, "TS"))       r.kind = "TS";
+    else if (iequals(kind, "MASSFLUX")) r.kind = "MASSFLUX";
+    else if (iequals(kind, "HEATFLUX")) r.kind = "HEATFLUX";
+    else return "[GW_BOUNDARY_QUALITY] KIND must be CONC|TS|MASSFLUX|HEATFLUX, "
+                "got " + kind;
+    if (r.kind == "TS") r.ts_name = tokens[4];
+    else                valueOrSeries(tokens[4], r.value, r.ts_name);
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// [GW_SOURCES]
+// ---------------------------------------------------------------------------
+
+std::string parseGwSourcesLine(const std::vector& tokens,
+                               std::vector& rows) {
+    if (tokens.empty()) return {};
+    if (tokens.size() < 4)
+        return "[GW_SOURCES] needs NAME (CELL n | TAG t | XY x y) FLOW value";
+    GwSourceRow r;
+    r.name = tokens[0];
+    std::size_t at = 1;
+    if (iequals(tokens[at], "CELL")) {
+        int n = 0;
+        if (!inum(tokens[at + 1], n) || n < 1)
+            return "[GW_SOURCES] invalid CELL index (1-based): " + tokens[at + 1];
+        r.scope = GwScope::CELL;
+        r.cell  = n - 1;
+        at += 2;
+    } else if (iequals(tokens[at], "TAG")) {
+        r.scope = GwScope::TAG;
+        r.tag   = tokens[at + 1];
+        at += 2;
+    } else if (iequals(tokens[at], "XY")) {
+        if (tokens.size() < at + 3) return "[GW_SOURCES] XY needs x y";
+        if (!num(tokens[at + 1], r.x) || !num(tokens[at + 2], r.y))
+            return "[GW_SOURCES] XY needs two numbers";
+        r.scope = GwScope::CELL;   // resolved to a cell at resolve
+        r.by_xy = true;
+        at += 3;
+    } else {
+        return "[GW_SOURCES] location must be CELL, TAG or XY, got " + tokens[at];
+    }
+
+    if (at >= tokens.size() || !iequals(tokens[at], "FLOW"))
+        return "[GW_SOURCES] '" + r.name + "' needs a FLOW value or series";
+    if (at + 1 >= tokens.size())
+        return "[GW_SOURCES] FLOW needs a value or series name";
+    valueOrSeries(tokens[at + 1], r.flow, r.flow_ts);
+    at += 2;
+
+    // Trailing species terms: SPECIES (CONC|MASS) value|ts, repeated.
+    while (at < tokens.size()) {
+        if (at + 2 >= tokens.size())
+            return "[GW_SOURCES] '" + r.name +
+                   "' trailing species term needs SPECIES (CONC|MASS) value";
+        GwSourceSpeciesTerm t;
+        t.species = tokens[at];
+        if      (iequals(tokens[at + 1], "CONC")) t.kind = "CONC";
+        else if (iequals(tokens[at + 1], "MASS")) t.kind = "MASS";
+        else return "[GW_SOURCES] species term kind must be CONC or MASS, got " +
+                    tokens[at + 1];
+        valueOrSeries(tokens[at + 2], t.value, t.ts_name);
+        r.species.push_back(std::move(t));
+        at += 3;
+    }
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+void registerGwTransportSections(GwTransportData& gw,
+                                 input::SectionRegistry& registry) {
+    registry.register_custom("GW_TRANSPORT_OPTIONS",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwTransportOptionsLine(t, gw.options);
+        }, gw.options));
+    registry.register_custom("GW_TRANSPORT_PARAMS",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwParamsLine(t, gw.params);
+        }, gw.options));
+    registry.register_custom("GW_SORPTION",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwSorptionLine(t, gw.sorption);
+        }, gw.options));
+    registry.register_custom("GW_INITIAL_QUALITY",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwInitialQualityLine(t, gw.initial_quality,
+                                             gw.initial_quality_file);
+        }, gw.options));
+    registry.register_custom("GW_BOUNDARY_QUALITY",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwBoundaryQualityLine(t, gw.boundary_quality);
+        }, gw.options));
+    registry.register_custom("GW_SOURCES",
+        makeGwHandler([&gw](const std::vector& t) {
+            return parseGwSourcesLine(t, gw.sources);
+        }, gw.options));
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+std::vector resolveGwTransport(SimulationContext& ctx,
+                                            const MeshData& mesh,
+                                            GwTransportData& gw) {
+    std::vector errs;
+    if (gw.empty()) return errs;
+
+    const int n_cells = mesh.n_cells();
+
+    // `[GW_INITIAL_QUALITY] FILE `: element,zone,species,value.
+    if (!gw.initial_quality_file.empty()) {
+        // Drop what a previous resolve loaded (re-resolve is idempotent).
+        for (int i = static_cast(gw.initial_quality.size()) - 1; i >= 0; --i)
+            if (gw.initial_quality[static_cast(i)].layer == -2)
+                gw.initial_quality.erase(gw.initial_quality.begin() + i);
+        const std::string dir  = openswmm::io::parentDir(ctx.inp_file_path);
+        const std::string path =
+            openswmm::io::resolveRelative(gw.initial_quality_file, dir);
+        std::ifstream in(openswmm::io::utf8_path(path));
+        if (!in.is_open()) {
+            errs.push_back("[GW_INITIAL_QUALITY] FILE '" + gw.initial_quality_file +
+                           "' not found or unreadable (" + path + ").");
+        } else {
+            std::string line;
+            int lineno = 0;
+            while (std::getline(in, line)) {
+                ++lineno;
+                for (char& ch : line)
+                    if (ch == ',' || ch == ';' || ch == '\t') ch = ' ';
+                auto tok = openswmm::input::Tokenizer::tokenize(line);
+                if (tok.empty()) continue;
+                std::vector one;
+                std::string ignored;
+                const std::string e = parseGwInitialQualityLine(tok, one, ignored);
+                if (!e.empty()) {
+                    if (lineno == 1) continue;   // header
+                    errs.push_back("[GW_INITIAL_QUALITY] FILE '" +
+                                   gw.initial_quality_file + "' line " +
+                                   std::to_string(lineno) + ": " + e);
+                    continue;
+                }
+                for (auto& r : one) {
+                    if (r.zone != GwZone::LAYER) r.layer = -2;   // "from the file"
+                    gw.initial_quality.push_back(std::move(r));
+                }
+            }
+        }
+    }
+
+    auto checkCell = [&](int cell, const char* sec) {
+        if (cell < 0) return;   // GLOBAL / TAG rows carry -1
+        if (cell >= n_cells)
+            errs.push_back(std::string(sec) + " CELL " + std::to_string(cell + 1) +
+                           " is off the mesh (" + std::to_string(n_cells) +
+                           " cells).");
+    };
+    auto checkTag = [&](const std::string& tag, const char* sec) {
+        if (tag.empty()) return;
+        for (const auto& t : mesh.tri_tag)
+            if (t == tag) return;
+        errs.push_back(std::string(sec) + " TAG '" + tag +
+                       "' matches no cell tag on the mesh.");
+    };
+    auto checkSpecies = [&](const std::string& name, const char* sec) {
+        if (name == "__WATER_AGE__" || name == "__TEMPERATURE__") return true;
+        if (ctx.species_registry.find(name) >= 0) return true;
+        errs.push_back(std::string(sec) + " unknown species '" + name +
+                       "' — declare it in [POLLUTANTS] or the reactions "
+                       "component, or name __WATER_AGE__ / __TEMPERATURE__.");
+        return false;
+    };
+    auto checkSeries = [&](const std::string& name, const char* sec) {
+        if (name.empty()) return;
+        if (ctx.find_timeseries(name) < 0)
+            errs.push_back(std::string(sec) + " unknown time series '" + name + "'.");
+    };
+
+    for (const auto& r : gw.params) {
+        checkCell(r.cell, "[GW_TRANSPORT_PARAMS]");
+        checkTag(r.tag, "[GW_TRANSPORT_PARAMS]");
+    }
+    for (const auto& r : gw.sorption) {
+        checkCell(r.cell, "[GW_SORPTION]");
+        checkTag(r.tag, "[GW_SORPTION]");
+        checkSpecies(r.species, "[GW_SORPTION]");
+    }
+    for (const auto& r : gw.initial_quality) {
+        checkCell(r.cell, "[GW_INITIAL_QUALITY]");
+        checkTag(r.tag, "[GW_INITIAL_QUALITY]");
+        if (!checkSpecies(r.species, "[GW_INITIAL_QUALITY]")) continue;
+        const bool signed_row = r.species == "__TEMPERATURE__" ||
+                                r.species == "__WATER_AGE__";
+        if (!signed_row && r.value < 0.0)
+            errs.push_back("[GW_INITIAL_QUALITY] negative value for '" +
+                           r.species + "'.");
+    }
+    for (const auto& r : gw.boundary_quality) {
+        checkCell(r.cell, "[GW_BOUNDARY_QUALITY]");
+        // EDGE 0..nv-1 of ITS cell: a triangle has 3 local edges, a quad 4.
+        if (r.cell >= 0 && r.cell < n_cells) {
+            const int nv = static_cast(
+                mesh.cell_nv[static_cast(r.cell)]);
+            if (r.edge >= nv)
+                errs.push_back("[GW_BOUNDARY_QUALITY] EDGE " +
+                               std::to_string(r.edge) + " on CELL " +
+                               std::to_string(r.cell + 1) + " (" +
+                               std::to_string(nv) + " vertices) — EDGE is "
+                               "0.." + std::to_string(nv - 1) + ".");
+        }
+        checkSpecies(r.species, "[GW_BOUNDARY_QUALITY]");
+        checkSeries(r.ts_name, "[GW_BOUNDARY_QUALITY]");
+    }
+    for (auto& r : gw.sources) {
+        if (r.by_xy) {
+            // Nearest cell centroid — the same rule the mesh editor uses to
+            // place a picked point, and cell-generic (centroids are true-area).
+            int best = -1;
+            double best_d2 = 0.0;
+            for (int c = 0; c < n_cells; ++c) {
+                const auto uc = static_cast(c);
+                const double dx = mesh.tri_cx[uc] - r.x;
+                const double dy = mesh.tri_cy[uc] - r.y;
+                const double d2 = dx * dx + dy * dy;
+                if (best < 0 || d2 < best_d2) { best = c; best_d2 = d2; }
+            }
+            if (best < 0)
+                errs.push_back("[GW_SOURCES] '" + r.name +
+                               "' XY cannot be placed: the mesh has no cells.");
+            r.cell = best;
+        }
+        checkCell(r.cell, "[GW_SOURCES]");
+        checkTag(r.tag, "[GW_SOURCES]");
+        checkSeries(r.flow_ts, "[GW_SOURCES]");
+        for (const auto& t : r.species) {
+            checkSpecies(t.species, "[GW_SOURCES]");
+            checkSeries(t.ts_name, "[GW_SOURCES]");
+        }
+    }
+
+    // Duplicate names are an error, not last-wins — the same reasoning
+    // [INITIAL_QUALITY] applies to its own duplicates.
+    for (std::size_t i = 0; i < gw.sources.size(); ++i)
+        for (std::size_t j = 0; j < i; ++j)
+            if (gw.sources[i].name == gw.sources[j].name)
+                errs.push_back("[GW_SOURCES] duplicate source name '" +
+                               gw.sources[i].name + "'.");
+
+    return errs;
+}
+
+std::string gwTransportInertWarning(const GwTransportData& gw) {
+    if (gw.empty()) return {};
+    // T7.1 (2026-09-20): the two-zone kernel now transports, so this warning
+    // is no longer about the release — it is about THIS deck. It fires only
+    // when the [GW_*] rows have no kernel to configure, which the caller
+    // decides (it knows whether a [2D_AQUIFER] resolved).
+    return "[GW_*] subsurface transport is AUTHORED but INERT this run: the "
+           "rows configure the two-zone [2D_AQUIFER] kernel, and no "
+           "[2D_AQUIFER] resolved on this model. The rows are validated, "
+           "kept and written back unchanged.";
+}
+
+}  // namespace openswmm::twoD
diff --git a/src/engine/2d/gw/GwTransportSections.hpp b/src/engine/2d/gw/GwTransportSections.hpp
new file mode 100644
index 000000000..a1aff2132
--- /dev/null
+++ b/src/engine/2d/gw/GwTransportSections.hpp
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file GwTransportSections.hpp
+ * @brief U4 (2026-09-07) — parsers and registration for the `[GW_*]`
+ *        subsurface-transport authoring sections. See GwTransportData.hpp
+ *        for the shape and the authoring-only contract.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_GW_TRANSPORT_SECTIONS_HPP
+#define OPENSWMM_ENGINE_2D_GW_TRANSPORT_SECTIONS_HPP
+
+#include "GwTransportData.hpp"
+#include "../../input/SectionRegistry.hpp"
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::twoD {
+
+struct MeshData;
+
+/// One `[GW_TRANSPORT_OPTIONS]` line (`KEY VALUE [ARG…]`). Empty = OK.
+std::string parseGwTransportOptionsLine(const std::vector& tokens,
+                                        GwTransportOptions& opts);
+
+/// One `[GW_TRANSPORT_PARAMS]` line: `* | TAG  | CELL ` then the
+/// positional matrix properties (see GwParamsRow). Empty = OK.
+std::string parseGwParamsLine(const std::vector& tokens,
+                              std::vector& rows);
+
+/// One `[GW_SORPTION]` line: scope, SPECIES, Kd [decay]. Empty = OK.
+std::string parseGwSorptionLine(const std::vector& tokens,
+                                std::vector& rows);
+
+/// One `[GW_INITIAL_QUALITY]` line: scope, `SAT|UNSAT|LAYER `, SPECIES,
+/// VALUE — or `FILE `. Empty = OK.
+std::string parseGwInitialQualityLine(const std::vector& tokens,
+                                      std::vector& rows,
+                                      std::string& file);
+
+/// One `[GW_BOUNDARY_QUALITY]` line: `CELL EDGE SPECIES CONC v | TS n |
+/// MASSFLUX v|n | HEATFLUX v|n`. CELL is 1-based in the file, EDGE is
+/// 0-based (`EDGE 0..nv-1` of that cell). Empty = OK.
+std::string parseGwBoundaryQualityLine(const std::vector& tokens,
+                                       std::vector& rows);
+
+/// One `[GW_SOURCES]` line: `NAME (CELL n | TAG t | XY x y) FLOW v|ts
+/// [SPECIES (CONC|MASS) v|ts]…`. Empty = OK.
+std::string parseGwSourcesLine(const std::vector& tokens,
+                               std::vector& rows);
+
+/// Register every `[GW_*]` handler against @p registry, writing into @p gw.
+void registerGwTransportSections(GwTransportData& gw,
+                                 input::SectionRegistry& registry);
+
+/**
+ * @brief Validate the authored rows against the model and the species
+ *        registry, once the mesh and the species are final.
+ *
+ * @details Cell indices must be on the mesh, `EDGE` must be `0..nv-1` of ITS
+ *          cell (cell-generic — a triangle has 3, a quad 4), species must
+ *          resolve through the one registry (pollutants, reactions species,
+ *          `__WATER_AGE__`, `__TEMPERATURE__`), timeseries names must exist.
+ *          Returns the diagnostics; empty on success. Also loads the
+ *          `[GW_INITIAL_QUALITY] FILE` sidecar (relative to the .inp).
+ */
+std::vector resolveGwTransport(SimulationContext& ctx,
+                                            const MeshData& mesh,
+                                            GwTransportData& gw);
+
+/// The single "authored but no kernel" run-time warning (U4's contract).
+/// Empty when nothing was authored.
+std::string gwTransportInertWarning(const GwTransportData& gw);
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_GW_TRANSPORT_SECTIONS_HPP
diff --git a/src/engine/2d/infil/Infil2D.cpp b/src/engine/2d/infil/Infil2D.cpp
new file mode 100644
index 000000000..2f9f85a7b
--- /dev/null
+++ b/src/engine/2d/infil/Infil2D.cpp
@@ -0,0 +1,396 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Infil2D.cpp
+ * @brief Per-cell infiltration for the 2D overland-flow mesh (track I).
+ *
+ * @see Infil2D.hpp — the contract, and plan §5.5 (D-I1…D-I6).
+ * @ingroup twoD
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "Infil2D.hpp"
+
+#include "../data/MeshData.hpp"
+#include "../data/SurfaceStateData.hpp"
+#include "../../core/SimulationOptions.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+namespace {
+
+// ---------------------------------------------------------------------------
+// SI ⇄ legacy-kernel units
+// ---------------------------------------------------------------------------
+// The 2D solver is SI (m, m/s); infil::*_getInfil is ft, ft/s for every
+// project (US or SI) — see §5.5.1. Conversion happens only here, at the call
+// boundary, so the kernels keep bit-parity with legacy infil.c.
+
+constexpr double kFeetPerMeter  = 3.280839895013123;  ///< m → ft
+constexpr double kMetersPerFoot = 0.3048;             ///< ft → m (exact)
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+
+/// Case-insensitive comparison (file tokens are case-insensitive on input).
+bool iequals(std::string_view a, std::string_view b) {
+    if (a.size() != b.size()) return false;
+    for (std::size_t i = 0; i < a.size(); ++i) {
+        if (std::toupper(static_cast(a[i]))
+            != std::toupper(static_cast(b[i])))
+            return false;
+    }
+    return true;
+}
+
+/// Validate one row. @p who names the offending cell or tag in every message.
+/// @p aquifer_2d is true once a `[2D_AQUIFER]` has resolved, which is what
+/// gives the AQUIFER_2D destination a receiver.
+bool validateRow(const Infil2DRow& row, const std::string& who,
+                 bool aquifer_2d, std::string& err) {
+    if (!row.has_method) return true;
+
+    // D-I4 as amended by U3 (2026-09-07) and G1: LOST and SUBCATCH_AQUIFER are
+    // routed. SUBCATCH_AQUIFER recharges the legacy aquifer of the
+    // subcatchment containing the cell (track I-b); AQUIFER_2D recharges the
+    // two-zone kernel and is legal exactly when there is a kernel to receive
+    // it. Refusing it when there is none is deliberate: quietly reading it as
+    // LOST would drain a model the author believed was recharging.
+    if (row.dest == Infil2DDest::AQUIFER_2D && !aquifer_2d) {
+        err = "2D infiltration " + who + ": destination AQUIFER_2D needs a "
+              "[2D_AQUIFER] section to receive the recharge; this model has "
+              "none — add one, or use LOST or SUBCATCH_AQUIFER";
+        return false;
+    }
+
+    switch (row.method) {
+        case InfilModel::HORTON:
+        case InfilModel::MOD_HORTON:
+            if (row.p[0] < 0.0 || row.p[1] < 0.0) {
+                err = "2D infiltration " + who
+                    + ": Horton rates f0 and fmin must be >= 0";
+                return false;
+            }
+            break;
+
+        case InfilModel::GREEN_AMPT:
+        case InfilModel::MOD_GREEN_AMPT:
+            if (row.p[1] < 0.0) {
+                err = "2D infiltration " + who
+                    + ": Green-Ampt conductivity Ks must be >= 0";
+                return false;
+            }
+            if (row.p[2] < 0.0 || row.p[2] > 1.0) {
+                err = "2D infiltration " + who
+                    + ": Green-Ampt initial moisture deficit IMD must be in 0..1";
+                return false;
+            }
+            break;
+
+        case InfilModel::CURVE_NUM:
+            if (row.p[0] < 1.0 || row.p[0] > 100.0) {
+                err = "2D infiltration " + who
+                    + ": curve number must be in 1..100";
+                return false;
+            }
+            break;
+
+        case InfilModel::CONSTANT:
+            if (row.p[0] < 0.0) {
+                err = "2D infiltration " + who + ": constant rate must be >= 0";
+                return false;
+            }
+            break;
+
+        default:
+            err = "2D infiltration " + who + ": unknown infiltration method";
+            return false;
+    }
+    return true;
+}
+
+} // namespace
+
+// ============================================================================
+// Free helpers
+// ============================================================================
+
+bool parseInfil2DMethod(const std::string& token, InfilModel& method,
+                        bool& has_method) {
+    if (iequals(token, "NONE")) {
+        method     = InfilModel::HORTON;   // meaningless when has_method is false
+        has_method = false;
+        return true;
+    }
+
+    has_method = true;
+    if (iequals(token, "HORTON"))              { method = InfilModel::HORTON;         return true; }
+    if (iequals(token, "MODIFIED_HORTON"))     { method = InfilModel::MOD_HORTON;     return true; }
+    if (iequals(token, "GREEN_AMPT"))          { method = InfilModel::GREEN_AMPT;     return true; }
+    if (iequals(token, "MODIFIED_GREEN_AMPT")) { method = InfilModel::MOD_GREEN_AMPT; return true; }
+    if (iequals(token, "CURVE_NUMBER"))        { method = InfilModel::CURVE_NUM;      return true; }
+    if (iequals(token, "CONSTANT"))            { method = InfilModel::CONSTANT;       return true; }
+
+    has_method = false;
+    return false;
+}
+
+const char* infil2DMethodToken(const Infil2DRow& row) {
+    if (!row.has_method) return "NONE";
+    switch (row.method) {
+        case InfilModel::HORTON:         return "HORTON";
+        case InfilModel::MOD_HORTON:     return "MODIFIED_HORTON";
+        case InfilModel::GREEN_AMPT:     return "GREEN_AMPT";
+        case InfilModel::MOD_GREEN_AMPT: return "MODIFIED_GREEN_AMPT";
+        case InfilModel::CURVE_NUM:      return "CURVE_NUMBER";
+        case InfilModel::CONSTANT:       return "CONSTANT";
+    }
+    return "NONE";
+}
+
+bool parseInfil2DDest(const std::string& token, Infil2DDest& dest) {
+    if (iequals(token, "LOST"))             { dest = Infil2DDest::LOST;             return true; }
+    if (iequals(token, "SUBCATCH_AQUIFER")) { dest = Infil2DDest::SUBCATCH_AQUIFER; return true; }
+    if (iequals(token, "AQUIFER_2D"))       { dest = Infil2DDest::AQUIFER_2D;       return true; }
+    return false;
+}
+
+const char* infil2DDestToken(Infil2DDest dest) {
+    switch (dest) {
+        case Infil2DDest::LOST:             return "LOST";
+        case Infil2DDest::SUBCATCH_AQUIFER: return "SUBCATCH_AQUIFER";
+        case Infil2DDest::AQUIFER_2D:       return "AQUIFER_2D";
+    }
+    return "LOST";
+}
+
+int infil2DParamCount(InfilModel method) {
+    switch (method) {
+        case InfilModel::HORTON:
+        case InfilModel::MOD_HORTON:     return 5;  // f0 fmin decay dry_time Fmax
+        case InfilModel::GREEN_AMPT:
+        case InfilModel::MOD_GREEN_AMPT: return 3;  // S Ks IMD
+        case InfilModel::CURVE_NUM:      return 3;  // CN (unused) dry_time
+        case InfilModel::CONSTANT:       return 1;  // rate
+    }
+    return 0;
+}
+
+// ============================================================================
+// Infil2D
+// ============================================================================
+
+bool Infil2D::resolve(const MeshData& mesh, const SimulationOptions& opts,
+                      std::string& err) {
+    const int  nt   = mesh.n_triangles();
+    const auto nt_u = static_cast(nt);
+
+    resolved_.assign(nt_u, Infil2DRow{});
+    prov_.assign(nt_u, Infil2DProvenance::NONE);
+    cum_depth_.assign(nt_u, 0.0);
+    horton_.clear();
+    grnampt_.clear();
+    curvenum_.clear();
+    active_ = false;
+
+    // D-I1: the cadence is INFIL_STEP, falling back to the project WET_STEP
+    // (SimulationOptions::wet_step is already in seconds).
+    step_seconds_ = (options_.infil_step > 0.0) ? options_.infil_step : opts.wet_step;
+
+    // --- D-I3 precedence, least specific first: '*' → tag → override -------
+
+    const Infil2DDefault* star = nullptr;
+    for (const auto& d : defaults_) {
+        if (!validateRow(d.row, "tag '" + d.tag + "'",
+                         aquifer_2d_available_, err)) return false;
+        if (d.tag == "*") star = &d;
+    }
+
+    if (star != nullptr && star->row.has_method) {
+        for (std::size_t i = 0; i < nt_u; ++i) {
+            resolved_[i] = star->row;
+            prov_[i]     = Infil2DProvenance::STAR;
+        }
+    }
+
+    // A tag row spelled NONE deliberately clears the '*' default for its cells.
+    const std::size_t n_tagged = std::min(nt_u, mesh.tri_tag.size());
+    for (const auto& d : defaults_) {
+        if (d.tag == "*") continue;
+        for (std::size_t i = 0; i < n_tagged; ++i) {
+            if (mesh.tri_tag[i] != d.tag) continue;
+            if (d.row.has_method) {
+                resolved_[i] = d.row;
+                prov_[i]     = Infil2DProvenance::TAG;
+            } else {
+                resolved_[i] = Infil2DRow{};
+                prov_[i]     = Infil2DProvenance::NONE;
+            }
+        }
+    }
+
+    for (const auto& o : overrides_) {
+        if (o.tri < 0 || o.tri >= nt) {
+            err = "2D infiltration cell " + std::to_string(o.tri + 1)
+                + ": triangle index out of range (mesh has "
+                + std::to_string(nt) + " triangles)";
+            return false;
+        }
+        if (!validateRow(o.row, "cell " + std::to_string(o.tri + 1),
+                         aquifer_2d_available_, err)) return false;
+
+        const auto ui = static_cast(o.tri);
+        if (o.row.has_method) {
+            resolved_[ui] = o.row;
+            prov_[ui]     = Infil2DProvenance::OVERRIDE;
+        } else {
+            resolved_[ui] = Infil2DRow{};
+            prov_[ui]     = Infil2DProvenance::NONE;
+        }
+    }
+
+    // --- kernel state, from the PROJECT-UNIT parameters (§5.5.1) -----------
+
+    for (std::size_t i = 0; i < nt_u; ++i) {
+        const Infil2DRow& r = resolved_[i];
+        if (!r.has_method) continue;
+        active_ = true;
+
+        switch (r.method) {
+            case InfilModel::HORTON:
+            case InfilModel::MOD_HORTON:
+                if (horton_.empty()) horton_.assign(nt_u, infil::HortonState{});
+                infil::horton_init(horton_[i], r.p[0], r.p[1], r.p[2], r.p[3],
+                                   r.p[4], opts);
+                break;
+
+            case InfilModel::CONSTANT:
+                // A constant rate is a degenerate Horton (f0 == fmin, no decay,
+                // no regeneration), so horton_init performs exactly the
+                // in/hr|mm/hr → ft/s conversion this method needs and
+                // horton_[i].fmin carries the rate. No extra storage, and the
+                // slot reads sanely if anyone inspects it.
+                if (horton_.empty()) horton_.assign(nt_u, infil::HortonState{});
+                infil::horton_init(horton_[i], r.p[0], r.p[0], 0.0, 0.0, 0.0, opts);
+                break;
+
+            case InfilModel::GREEN_AMPT:
+            case InfilModel::MOD_GREEN_AMPT:
+                if (grnampt_.empty()) grnampt_.assign(nt_u, infil::GreenAmptState{});
+                infil::grnampt_init(grnampt_[i], r.p[0], r.p[1], r.p[2], opts);
+                break;
+
+            case InfilModel::CURVE_NUM:
+                // Drying time is p[2] — the third positional column, matching
+                // legacy curvenum_setParams() and Runoff.cpp:252-253.
+                if (curvenum_.empty()) curvenum_.assign(nt_u, infil::CurveNumState{});
+                infil::curvenum_init(curvenum_[i], r.p[0], r.p[2]);
+                break;
+
+            default:
+                err = "2D infiltration cell " + std::to_string(i + 1)
+                    + ": unknown infiltration method";
+                return false;
+        }
+    }
+
+    // Nothing resolved: drop back to the unconfigured fast path so the
+    // bitwise-regression gate (I7) holds with no arrays allocated.
+    if (!active_) {
+        resolved_.clear();
+        prov_.clear();
+        cum_depth_.clear();
+    }
+
+    return true;
+}
+
+void Infil2D::updateRates(const MeshData& mesh, SurfaceStateData& state, double dt) {
+    (void)mesh;
+    if (!active_ || dt <= 0.0) return;
+
+    // §5.5.2: advance EVERY model-carrying cell, active or not — a cell that
+    // sat inactive must not present full initial capacity when rain arrives.
+    const std::size_t n = std::min(resolved_.size(), state.infil_rate.size());
+    for (std::size_t i = 0; i < n; ++i) {
+        const Infil2DRow& r = resolved_[i];
+        if (!r.has_method) continue;
+
+        const double precip_ft = state.rainfall[i] * kFeetPerMeter;
+        const double depth_ft  = state.depth[i]    * kFeetPerMeter;
+
+        double f_ftsec = 0.0;
+        switch (r.method) {
+            case InfilModel::HORTON:
+                f_ftsec = infil::horton_getInfil(horton_[i], precip_ft, depth_ft, dt);
+                break;
+            case InfilModel::MOD_HORTON:
+                f_ftsec = infil::modHorton_getInfil(horton_[i], precip_ft, depth_ft, dt);
+                break;
+            case InfilModel::GREEN_AMPT:
+            case InfilModel::MOD_GREEN_AMPT:
+                // The modified variant is selected by the enum, not a bool.
+                f_ftsec = infil::grnampt_getInfil(grnampt_[i], precip_ft, depth_ft,
+                                                  dt, r.method);
+                break;
+            case InfilModel::CURVE_NUM:
+                // Runoff.cpp:428 folds inter-subarea runon into the depth
+                // argument (and passes rainfall alone as the rate); a mesh cell
+                // has no runon, so the ponded depth passes through unchanged.
+                f_ftsec = infil::curvenum_getInfil(curvenum_[i], precip_ft, depth_ft, dt);
+                break;
+            case InfilModel::CONSTANT:
+                f_ftsec = infil::constant_getInfil(horton_[i].fmin, precip_ft,
+                                                   depth_ft, dt);
+                break;
+            default:
+                break;
+        }
+
+        const double rate_si = std::max(0.0, f_ftsec * kMetersPerFoot);
+        state.infil_rate[i] = rate_si;
+        cum_depth_[i] += rate_si * dt;
+    }
+}
+
+void Infil2D::reset() {
+    defaults_.clear();
+    overrides_.clear();
+    options_ = Infil2DOptions{};
+
+    active_       = false;
+    step_seconds_ = 0.0;
+    aquifer_2d_available_ = false;
+
+    resolved_.clear();
+    prov_.clear();
+    cum_depth_.clear();
+    horton_.clear();
+    grnampt_.clear();
+    curvenum_.clear();
+}
+
+} // namespace openswmm::twoD
diff --git a/src/engine/2d/infil/Infil2D.hpp b/src/engine/2d/infil/Infil2D.hpp
new file mode 100644
index 000000000..73c68f9fd
--- /dev/null
+++ b/src/engine/2d/infil/Infil2D.hpp
@@ -0,0 +1,315 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Infil2D.hpp
+ * @brief Per-cell infiltration for the 2D overland-flow mesh (track I).
+ *
+ * @details Implements `plans/TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN_2026-08-15.md`
+ *          §5.5 (steps I1–I8, decisions D-I1…D-I6). This is the
+ *          `GROUNDWATER OFF` infiltration path: a per-cell loss model so
+ *          surface-only runs do not overestimate pervious runoff.
+ *
+ *          Design invariants — do not violate these without amending §5.5:
+ *
+ *          - **D-I1.** Infiltration is a *held rate*, recomputed on the
+ *            `INFIL_STEP` cadence and published into
+ *            `SurfaceStateData::infil_rate` (m/s). It is NOT evaluated inside
+ *            the marcher's `fireCells`. The marcher only consumes the held
+ *            rate through `infilSink()`.
+ *          - **D-I2.** Sink order within a substep: rainfall source →
+ *            evaporation (unchanged `evapSink` semantics) → infiltration
+ *            against the remaining depth.
+ *          - **D-I3.** Parameters resolve
+ *            `per-cell override > tag row > '*' row > none`, once, at
+ *            configure time. The solver never consults tags. Provenance is
+ *            retained so the writer re-emits a compact file.
+ *          - **D-I4.** `LOST` is the only destination accepted in this
+ *            release; the others parse and are rejected with a clear message.
+ *          - **D-I6.** Six methods: HORTON, MOD_HORTON, GREEN_AMPT,
+ *            MOD_GREEN_AMPT, CURVE_NUM, CONSTANT.
+ *
+ *          **Units.** Row parameters are in *project units* (the same numbers
+ *          a user types into `[INFILTRATION]`) — user decision 2026-08-20.
+ *          The `infil::*_init` functions consume those directly via
+ *          `ucf::UCF(...)`. The `infil::*_getInfil` kernels work in ft and
+ *          ft/s; the 2D solver is SI. All conversion happens in
+ *          Infil2D::updateRates() at the call boundary, so the hydrology
+ *          kernels keep bit-parity with legacy `infil.c`.
+ *
+ * @ingroup twoD
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_2D_INFIL2D_HPP
+#define OPENSWMM_2D_INFIL2D_HPP
+
+#include 
+#include 
+#include 
+
+#include "../../hydrology/Infiltration.hpp"
+
+namespace openswmm { struct SimulationOptions; }
+
+namespace openswmm::twoD {
+
+struct MeshData;
+struct SurfaceStateData;
+
+// ============================================================================
+// Value types
+// ============================================================================
+
+/// Destination of infiltrated water. D-I4 as amended by U3 and G1: LOST and
+/// SUBCATCH_AQUIFER are routed, and AQUIFER_2D is accepted once a
+/// `[2D_AQUIFER]` section resolves — without one it is still refused, with a
+/// message naming the section to add.
+///
+/// @note With a `[2D_AQUIFER]` present the aquifer OWNS infiltration: every
+///       infiltrating cell recharges it and LOST reads as AQUIFER_2D. That is
+///       what a user means by putting an aquifer under the mesh, and it keeps
+///       the water to one owner. SUBCATCH_AQUIFER is the one destination that
+///       cannot coexist with it, for the same one-owner reason the integrated
+///       component conflict already states — see `SurfaceRouter2D::initialize`.
+enum class Infil2DDest : int {
+    LOST             = 0,  ///< Leaves the domain; booked to MassBalance2D::infil_out
+    SUBCATCH_AQUIFER = 1,  ///< Legacy subcatchment aquifer (U3 track I-b)
+    AQUIFER_2D       = 2   ///< The two-zone 2D kernel (G1 step 11b)
+};
+
+/// Number of positional parameter columns carried per row. Matches the widest
+/// legacy `[INFILTRATION]` method (Horton: f0 fmin decay dry_time Fmax).
+inline constexpr int kInfil2DMaxParams = 5;
+
+/**
+ * @brief One infiltration specification: method + positional parameters + destination.
+ *
+ * @details Parameters are POSITIONAL and in PROJECT UNITS, matching legacy
+ *          `[INFILTRATION]` exactly:
+ *
+ *          | method          | p0        | p1        | p2          | p3         | p4   |
+ *          |-----------------|-----------|-----------|-------------|------------|------|
+ *          | HORTON          | f0        | fmin      | decay (1/hr)| dry_time(d)| Fmax |
+ *          | MOD_HORTON      | f0        | fmin      | decay (1/hr)| dry_time(d)| Fmax |
+ *          | GREEN_AMPT      | S (suction)| Ks       | IMD         | —          | —    |
+ *          | MOD_GREEN_AMPT  | S (suction)| Ks       | IMD         | —          | —    |
+ *          | CURVE_NUM       | CN        | —         | dry_time(d) | —          | —    |
+ *          | CONSTANT        | rate      | —         | —           | —          | —    |
+ *
+ *          f0/fmin/Ks/rate are in/hr (US) or mm/hr (SI); S and Fmax are in
+ *          (US) or mm (SI). CURVE_NUM's p1 is unused and ignored, matching the
+ *          legacy column layout where the middle value is a no-op.
+ */
+struct Infil2DRow {
+    /// False = NONE: the cell has no infiltration model. When false, every
+    /// other field is meaningless.
+    bool        has_method = false;
+    InfilModel  method     = InfilModel::HORTON;
+    double      p[kInfil2DMaxParams] = {0.0, 0.0, 0.0, 0.0, 0.0};
+    Infil2DDest dest       = Infil2DDest::LOST;
+    /// E2: true when the row spelled its own DEST column. Rows that did not
+    /// take the project default ([2D_OPTIONS] INFIL_DESTINATION) at
+    /// initialize; the writer emits DEST only for explicit rows so a deck
+    /// round-trips unchanged.
+    bool        dest_explicit = false;
+};
+
+/// One `[2D_INFILTRATION_DEFAULTS]` row. `tag == "*"` is the mesh-wide
+/// fallback and may appear anywhere in the section.
+struct Infil2DDefault {
+    std::string tag;
+    Infil2DRow  row;
+};
+
+/// One `[2D_INFILTRATION]` per-cell override row.
+struct Infil2DOverride {
+    int        tri = -1;   ///< Triangle index (0-based internally; 1-based in file)
+    Infil2DRow row;
+};
+
+/// `[2D_INFILTRATION_OPTIONS]`.
+struct Infil2DOptions {
+    /// Evaluation cadence (s). D-I1. <= 0 means "use the project WET_STEP",
+    /// which SurfaceRouter2D resolves at initialize().
+    double infil_step = 0.0;
+};
+
+/// Where a resolved cell's parameters came from. Retained so the writer emits
+/// a compact file (D-I3) instead of N per-cell rows.
+enum class Infil2DProvenance : std::uint8_t {
+    NONE     = 0,  ///< No model resolved
+    STAR     = 1,  ///< From the '*' default row
+    TAG      = 2,  ///< From a tag default row
+    OVERRIDE = 3   ///< From a per-cell [2D_INFILTRATION] row
+};
+
+// ============================================================================
+// Infil2D — per-cell infiltration state and driver
+// ============================================================================
+
+/**
+ * @brief Owns per-cell infiltration parameters, kernel state and held rates.
+ *
+ * @details Lifecycle:
+ *          1. Parsers fill `defaults()`, `overrides()`, `options()`.
+ *          2. `SurfaceRouter2D::initialize()` calls resolve() once the mesh
+ *             (and therefore `MeshData::tri_tag`) is available.
+ *          3. `SurfaceRouter2D` calls updateRates() every `INFIL_STEP`.
+ *          4. The marcher consumes `SurfaceStateData::infil_rate` only.
+ *
+ *          Empty/unconfigured is the fast path: `active()` is false and no
+ *          array is allocated, so a project with no `[2D_INFILTRATION*]`
+ *          sections is bitwise identical to the pre-track-I engine (gate I7).
+ */
+class Infil2D {
+public:
+    // --- configuration (populated by the section handlers) -----------------
+    std::vector&        defaults()        noexcept { return defaults_; }
+    const std::vector&  defaults()  const noexcept { return defaults_; }
+    std::vector&       overrides()       noexcept { return overrides_; }
+    const std::vector& overrides() const noexcept { return overrides_; }
+    Infil2DOptions&                     options()         noexcept { return options_; }
+    const Infil2DOptions&               options()   const noexcept { return options_; }
+
+    /**
+     * @brief Resolve tag/override precedence into flat per-cell state.
+     *
+     * @details D-I3 precedence: override > tag > '*' > none. Initializes the
+     *          hydrology kernel state for every cell that resolved to a model,
+     *          converting project-unit parameters through `infil::*_init`.
+     *
+     * @param mesh  Mesh (uses `tri_tag` and `n_triangles()`).
+     * @param opts  Simulation options (unit system for the *_init conversions).
+     * @param err   [out] Human-readable message when the return is false.
+     * @returns False on a validation failure (unsupported destination,
+     *          out-of-range triangle index, unknown method, bad parameters).
+     */
+    bool resolve(const MeshData& mesh, const SimulationOptions& opts,
+                 std::string& err);
+
+    /**
+     * @brief G1 — tell validation that a `[2D_AQUIFER]` resolved, so the
+     *        `AQUIFER_2D` destination has somewhere to send its water.
+     *
+     * @details Must be called before `resolve()`. Without it `AQUIFER_2D` is
+     *          refused, which is the right answer when there is no aquifer:
+     *          silently treating it as LOST would drain a model the user
+     *          believed was recharging.
+     */
+    void setAquifer2DAvailable(bool on) noexcept { aquifer_2d_available_ = on; }
+    bool aquifer2DAvailable() const noexcept { return aquifer_2d_available_; }
+
+    /**
+     * @brief Recompute and publish per-cell infiltration rates (D-I1).
+     *
+     * @details Called on the `INFIL_STEP` cadence. Advances kernel state for
+     *          EVERY model-carrying cell, including cells the marcher has
+     *          deactivated — otherwise a dry cell presents full initial
+     *          capacity when rain finally arrives (§5.5.2).
+     *
+     *          Writes `state.infil_rate[i]` in m/s, >= 0. Conversion:
+     *          precip/depth SI→ft on the way in, rate ft/s→SI on the way out.
+     *
+     * @param mesh   Mesh (unused today; kept for symmetry and future area use).
+     * @param state  Surface state — reads `rainfall`/`depth`, writes `infil_rate`.
+     * @param dt     Elapsed seconds since the previous call (the INFIL_STEP).
+     */
+    void updateRates(const MeshData& mesh, SurfaceStateData& state, double dt);
+
+    /// True when at least one cell resolved to a model.
+    bool active() const noexcept { return active_; }
+
+    /// E2: [2D_OPTIONS] INFILTRATION NO — keep the rows (they still save)
+    /// but run without infiltration. Called after resolve().
+    void deactivate() noexcept { active_ = false; }
+
+    /// Resolved method per triangle; `has_method == false` entries are NONE.
+    const std::vector& resolvedRows() const noexcept { return resolved_; }
+
+    /// Provenance per triangle (D-I3, for the writer).
+    const std::vector& provenance() const noexcept { return prov_; }
+
+    /// Cumulative infiltration CAPACITY per triangle (m): the integral of the
+    /// published rate, without the solver's depth ramp. On a drying cell this
+    /// exceeds the water actually removed, so it is NOT ledger-consistent with
+    /// `MassBalance2D::infil_out`. `SurfaceRouter2D::infilCumulative()` is the
+    /// ledger-consistent series and is what the sidecar's `infil_cum` and the
+    /// C API's `*_get_cum_bulk` report; this one is retained as the kernel-side
+    /// diagnostic.
+    const std::vector& cumulative() const noexcept { return cum_depth_; }
+
+    /// Resolved cadence in seconds (options_.infil_step, or the project
+    /// WET_STEP when that was <= 0). Set by resolve().
+    double stepSeconds() const noexcept { return step_seconds_; }
+
+    /// Clear everything back to the unconfigured fast path.
+    void reset();
+
+private:
+    std::vector  defaults_;
+    std::vector overrides_;
+    Infil2DOptions               options_;
+
+    bool   active_        = false;
+    double step_seconds_  = 0.0;
+    /// G1: a `[2D_AQUIFER]` resolved, so AQUIFER_2D has a receiver. Set by
+    /// SurfaceRouter2D before resolve(), and cleared by reset() with the rest
+    /// of the authored state.
+    bool   aquifer_2d_available_ = false;
+
+    // Per-triangle resolved state (empty when !active_).
+    std::vector        resolved_;
+    std::vector prov_;
+    std::vector            cum_depth_;   ///< m
+
+    // Kernel state, one entry per triangle (allocated only for the methods in
+    // use; indexed by triangle so lookups stay branch-free).
+    std::vector    horton_;
+    std::vector grnampt_;
+    std::vector  curvenum_;
+};
+
+// ============================================================================
+// Free helpers
+// ============================================================================
+
+/// Parse a method token (`HORTON`, `MODIFIED_HORTON`, `GREEN_AMPT`,
+/// `MODIFIED_GREEN_AMPT`, `CURVE_NUMBER`, `CONSTANT`, `NONE`), case-insensitive.
+/// @returns False if the token is unrecognised. `NONE` returns true with
+///          @p has_method set false.
+bool parseInfil2DMethod(const std::string& token, InfilModel& method,
+                        bool& has_method);
+
+/// Inverse of parseInfil2DMethod — the canonical file token.
+const char* infil2DMethodToken(const Infil2DRow& row);
+
+/// Parse a destination token. @returns false if unrecognised.
+bool parseInfil2DDest(const std::string& token, Infil2DDest& dest);
+
+/// Inverse of parseInfil2DDest.
+const char* infil2DDestToken(Infil2DDest dest);
+
+/// Number of meaningful positional parameters for @p method (used by the
+/// writer to trim trailing placeholders and by validation).
+int infil2DParamCount(InfilModel method);
+
+} // namespace openswmm::twoD
+
+#endif // OPENSWMM_2D_INFIL2D_HPP
diff --git a/src/engine/2d/input/SectionHandlers2D.cpp b/src/engine/2d/input/SectionHandlers2D.cpp
index 9723c072e..629dcb188 100644
--- a/src/engine/2d/input/SectionHandlers2D.cpp
+++ b/src/engine/2d/input/SectionHandlers2D.cpp
@@ -7,8 +7,11 @@
  */
 
 #include "SectionHandlers2D.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../data/BoundaryData.hpp"
+#include "../data/Report2DVars.hpp"
+#include "../../input/InputParseUtils.hpp"
 #include "../../input/InputReader.hpp"
 #include "../../input/Tokenizer.hpp"
 #include "../../core/ErrorCodes.hpp"
@@ -16,6 +19,7 @@
 
 #include 
 #include 
+#include 
 #include 
 #include 
 #include 
@@ -27,8 +31,10 @@ namespace openswmm::twoD {
 
 namespace {
 
-// Case-insensitive string comparison
-bool iequals(const std::string& a, const std::string& b) {
+// Case-insensitive string comparison. Takes views so callers on the
+// allocation-free scan paths (prescan2DUnitsHeader) need no temporaries;
+// std::string arguments still convert implicitly.
+bool iequals(std::string_view a, std::string_view b) {
     if (a.size() != b.size()) return false;
     for (std::size_t i = 0; i < a.size(); ++i) {
         if (std::toupper(static_cast(a[i]))
@@ -74,8 +80,8 @@ int findTriangleByTag(const MeshData& mesh, const std::string& tag) {
 const std::string RETIRED_SUFFIX =
     " was retired with the CVODE/ARKODE 2D solvers: the explicit "
     "local-inertial marcher is the only 2D integrator. Remove the line; "
-    "marcher settings are THETA, CFL_NUMBER, LTS_TIERS, H_MOVE, FROUDE_MAX, "
-    "ADVECTION, MAX_TIMESTEP, COUPLING_AREA.";
+    "marcher settings are MOMENTUM_EQUATION, THETA, CFL_NUMBER, LTS_TIERS, "
+    "H_MOVE, FROUDE_MAX, RECONSTRUCTION_ORDER, MAX_TIMESTEP, COUPLING_AREA.";
 
 /// Retired [2D_OPTIONS] material: warn-and-ignore when a warnings sink is
 /// available (the file-load path — legacy models must still open), hard
@@ -111,6 +117,12 @@ std::string parse2DOptionsLine(const std::vector& tokens,
     } else if (iequals(key, "COUPLING_CD")) {
         opts.coupling_cd = tryParseDouble(val, ok);
         if (!ok) return "Invalid COUPLING_CD value";
+    } else if (iequals(key, "DISPERSION")) {
+        // S2: isotropic species dispersion, m2/s. Refused negative, not
+        // clamped (the 1D [TRANSPORT_OPTIONS] DISPERSION convention).
+        opts.dispersion = tryParseDouble(val, ok);
+        if (!ok || !std::isfinite(opts.dispersion) || opts.dispersion < 0.0)
+            return "Invalid DISPERSION value (m2/s, must be finite and >= 0)";
     } else if (iequals(key, "COUPLING_SYNC")) {
         opts.coupling_sync = tryParseDouble(val, ok);
         if (!ok || opts.coupling_sync < 0.0)
@@ -143,6 +155,8 @@ std::string parse2DOptionsLine(const std::vector& tokens,
     } else if (iequals(key, "RAINFALL_MODE")) {
         if (iequals(val, "NATURAL_NEIGHBOUR") || iequals(val, "NATURAL_NEIGHBOR"))
             opts.rainfall_mode = RainfallMode::NATURAL_NEIGHBOUR;
+        else if (iequals(val, "NEAREST_NEIGHBOUR") || iequals(val, "NEAREST_NEIGHBOR"))
+            opts.rainfall_mode = RainfallMode::NEAREST_NEIGHBOUR;
         else if (iequals(val, "SYSTEM"))
             opts.rainfall_mode = RainfallMode::SYSTEM;
         else if (iequals(val, "NONE"))
@@ -168,6 +182,28 @@ std::string parse2DOptionsLine(const std::vector& tokens,
         // and hard-error on the programmatic set path.
         if (!iequals(val, "EXPLICIT"))
             return retiredOption("INTEGRATOR " + val, warnings);
+    } else if (iequals(key, "MOMENTUM_EQUATION")) {
+        if      (iequals(val, "LOCAL_INERTIAL") || iequals(val, "LI"))
+            opts.momentum = Momentum2D::LOCAL_INERTIAL;
+        else if (iequals(val, "FULL_SWE") || iequals(val, "SWE") ||
+                 iequals(val, "FULL"))
+            opts.momentum = Momentum2D::FULL_SWE;
+        else if (iequals(val, "DIFFUSIVE_WAVE") || iequals(val, "DW") ||
+                 iequals(val, "DIFFUSIVE"))
+            opts.momentum = Momentum2D::DIFFUSIVE_WAVE;
+        else
+            return "Unknown MOMENTUM_EQUATION: " + val +
+                   " (expected LOCAL_INERTIAL|FULL_SWE|DIFFUSIVE_WAVE)";
+    } else if (iequals(key, "FRONT_REBUILD")) {
+        if      (iequals(val, "AUTO")) opts.front_rebuild = -1;
+        else if (iequals(val, "YES") || iequals(val, "ON"))  opts.front_rebuild = 1;
+        else if (iequals(val, "NO")  || iequals(val, "OFF")) opts.front_rebuild = 0;
+        else return "Unknown FRONT_REBUILD: " + val + " (expected AUTO|YES|NO)";
+    } else if (iequals(key, "RECONSTRUCTION_ORDER")) {
+        const int k = tryParseInt(val, ok);
+        if (!ok || (k != 1 && k != 2))
+            return "Invalid RECONSTRUCTION_ORDER value (expected 1|2)";
+        opts.reconstruction_order = k;
     } else if (iequals(key, "THETA")) {
         const double th = tryParseDouble(val, ok);
         if (!ok || th <= 0.0 || th > 1.0)
@@ -194,6 +230,15 @@ std::string parse2DOptionsLine(const std::vector& tokens,
             return "Invalid FROUDE_MAX value (expected > 0)";
         opts.froude_max = f;
     } else if (iequals(key, "ADVECTION")) {
+        // DEPRECATED (2026-09-06): the LI + staggered-advection experiment is
+        // superseded by MOMENTUM_EQUATION FULL_SWE. Still honoured so an old
+        // deck keeps its physics, but a file load names the replacement.
+        if (warnings && (iequals(val, "YES") || iequals(val, "ON") ||
+                         iequals(val, "TRUE")))
+            warnings->push_back(
+                "[2D_OPTIONS] ADVECTION YES is deprecated — use "
+                "MOMENTUM_EQUATION FULL_SWE for a conservative convective "
+                "term with shock capturing.");
         if (iequals(val, "YES") || iequals(val, "ON") || iequals(val, "TRUE"))
             opts.advection = true;
         else if (iequals(val, "NO") || iequals(val, "OFF") ||
@@ -201,6 +246,13 @@ std::string parse2DOptionsLine(const std::vector& tokens,
             opts.advection = false;
         else
             return "Unknown ADVECTION: " + val + " (expected YES|NO)";
+    } else if (iequals(key, "COUPLING_IN_FLOODING")) {
+        if (iequals(val, "YES") || iequals(val, "TRUE"))
+            opts.coupling_in_flooding = true;
+        else if (iequals(val, "NO") || iequals(val, "FALSE"))
+            opts.coupling_in_flooding = false;
+        else
+            return "Unknown COUPLING_IN_FLOODING: " + val + " (expected YES|NO)";
     } else if (iequals(key, "COUPLING_AREA")) {
         if (iequals(val, "AUTO"))
             opts.coupling_area_auto = true;
@@ -208,6 +260,125 @@ std::string parse2DOptionsLine(const std::vector& tokens,
             opts.coupling_area_auto = false;
         else
             return "Unknown COUPLING_AREA: " + val + " (expected AUTO|DEFAULT)";
+    } else if (iequals(key, "BACKEND")) {
+        // Same token set as [OPTIONS] FV_BACKEND; unknown tokens are rejected
+        // so a typo surfaces as a failed set instead of a silent AUTO.
+        if      (iequals(val, "AUTO")) opts.backend = Backend2D::AUTO;
+        else if (iequals(val, "CPU"))  opts.backend = Backend2D::CPU;
+        else if (iequals(val, "OMP"))  opts.backend = Backend2D::OMP;
+        else if (iequals(val, "CUDA")) opts.backend = Backend2D::CUDA;
+        else if (iequals(val, "HIP"))  opts.backend = Backend2D::HIP;
+        else if (iequals(val, "SYCL")) opts.backend = Backend2D::SYCL;
+        else
+            return "Unknown BACKEND: " + val +
+                   " (expected AUTO|CPU|OMP|CUDA|HIP|SYCL)";
+    } else if (iequals(key, "OUTPUT_PRECISION")) {
+        if      (iequals(val, "FLOAT32") || iequals(val, "F32") || iequals(val, "SINGLE"))
+            opts.output_precision = OutputPrecision2D::FLOAT32;
+        else if (iequals(val, "FLOAT64") || iequals(val, "F64") || iequals(val, "DOUBLE"))
+            opts.output_precision = OutputPrecision2D::FLOAT64;
+        else
+            return "Unknown OUTPUT_PRECISION: " + val + " (expected FLOAT32|FLOAT64)";
+    } else if (iequals(key, "OUTPUT_COMPRESSION")) {
+        const int lvl = tryParseInt(val, ok);
+        if (!ok || lvl < 0 || lvl > 9)
+            return "Invalid OUTPUT_COMPRESSION value (expected 0..9)";
+        opts.output_compression = lvl;
+    } else if (iequals(key, "REPORT_2D_VARIABLES")) {
+        // The value may span several tokens on a file line
+        // ("REPORT_2D_VARIABLES DEPTH VELOCITY") or arrive as one
+        // space/comma-separated string from the C API; join then split.
+        std::string joined;
+        for (std::size_t i = 1; i < tokens.size(); ++i) {
+            if (i > 1) joined += ' ';
+            joined += tokens[i];
+        }
+        unsigned mask = 0;
+        const std::string err = parseReport2DVars(joined, mask);
+        if (!err.empty()) return err;
+        opts.report_2d_vars = mask;
+    } else if (iequals(key, "REPORT_2D_SPECIES")) {
+        std::string joined;
+        for (std::size_t i = 1; i < tokens.size(); ++i) {
+            if (i > 1) joined += ' ';
+            joined += tokens[i];
+        }
+        opts.report_2d_species = report2d::parseSpecies(joined);   // ALL → empty
+    } else if (iequals(key, "REPORT_2D_STEP")) {
+        // HH:MM:SS, HH:MM or plain seconds — the [OPTIONS] *_STEP spelling.
+        const double sec = openswmm::input::parse_time_seconds(val);
+        if (!(sec >= 0.0) || !std::isfinite(sec))
+            return "Invalid REPORT_2D_STEP value (expected HH:MM:SS or seconds >= 0)";
+        opts.report_2d_step = sec;
+    } else if (iequals(key, "INFILTRATION")) {
+        // E2 process enable. AUTO restores the pre-E2 rule (on iff rows).
+        if      (iequals(val, "YES") || iequals(val, "ON"))  opts.infiltration = 1;
+        else if (iequals(val, "NO")  || iequals(val, "OFF")) opts.infiltration = 0;
+        else if (iequals(val, "AUTO"))                       opts.infiltration = -1;
+        else return "Unknown INFILTRATION: " + val + " (expected YES|NO|AUTO)";
+    } else if (iequals(key, "INFIL_STEP")) {
+        // Alias of [2D_INFILTRATION_OPTIONS] INFIL_STEP; same duration grammar
+        // as WET_STEP / DRY_STEP. 0 = unset.
+        const double secs = openswmm::input::parse_time_seconds(val);
+        if (!(secs >= 0.0) || !std::isfinite(secs))
+            return "Invalid INFIL_STEP value (expected hh:mm:ss or seconds >= 0)";
+        opts.infil_step = secs;
+    } else if (iequals(key, "INFIL_DEFAULT_METHOD")) {
+        static const char* kMethods[] = {
+            "NONE", "HORTON", "MOD_HORTON", "GREEN_AMPT", "MOD_GREEN_AMPT",
+            "CURVE_NUMBER", "CONSTANT",
+        };
+        bool known = false;
+        for (const char* m : kMethods) {
+            if (iequals(val, m)) { opts.infil_default_method = m; known = true; break; }
+        }
+        // Legacy [INFILTRATION] spellings of the same methods.
+        if (!known && iequals(val, "MODIFIED_HORTON"))     { opts.infil_default_method = "MOD_HORTON";     known = true; }
+        if (!known && iequals(val, "MODIFIED_GREEN_AMPT")) { opts.infil_default_method = "MOD_GREEN_AMPT"; known = true; }
+        if (!known && iequals(val, "CURVE_NUM"))           { opts.infil_default_method = "CURVE_NUMBER";   known = true; }
+        if (!known)
+            return "Unknown INFIL_DEFAULT_METHOD: " + val +
+                   " (expected NONE|HORTON|MOD_HORTON|GREEN_AMPT|MOD_GREEN_AMPT|"
+                   "CURVE_NUMBER|CONSTANT)";
+    } else if (iequals(key, "INFIL_DESTINATION")) {
+        if      (iequals(val, "LOST"))             opts.infil_destination = "LOST";
+        else if (iequals(val, "SUBCATCH_AQUIFER")) opts.infil_destination = "SUBCATCH_AQUIFER";
+        else if (iequals(val, "AQUIFER_2D"))       opts.infil_destination = "AQUIFER_2D";
+        else return "Unknown INFIL_DESTINATION: " + val +
+                    " (expected LOST|SUBCATCH_AQUIFER|AQUIFER_2D)";
+    } else if (iequals(key, "EVAPORATION")) {
+        if      (iequals(val, "YES") || iequals(val, "ON") || iequals(val, "FORCING"))
+            opts.evaporation = 1;
+        else if (iequals(val, "NO")  || iequals(val, "OFF"))
+            opts.evaporation = 0;
+        else if (iequals(val, "CLIMATE"))
+            opts.evaporation = 2;
+        else return "Unknown EVAPORATION: " + val + " (expected NO|YES|CLIMATE)";
+    } else if (iequals(key, "TRANSPORT_POLLUTANTS") || iequals(key, "TRANSPORT_MSX") ||
+               iequals(key, "TRANSPORT_AGE") || iequals(key, "TRANSPORT_TEMPERATURE")) {
+        bool on = false;
+        if      (iequals(val, "YES") || iequals(val, "ON"))  on = true;
+        else if (iequals(val, "NO")  || iequals(val, "OFF")) on = false;
+        else return "Unknown " + key + ": " + val + " (expected YES|NO)";
+        if      (iequals(key, "TRANSPORT_POLLUTANTS"))  opts.transport_pollutants  = on;
+        else if (iequals(key, "TRANSPORT_MSX"))         opts.transport_msx         = on;
+        else if (iequals(key, "TRANSPORT_AGE"))         opts.transport_age         = on;
+        else                                            opts.transport_temperature = on;
+    } else if (iequals(key, "GROUNDWATER")) {
+        // Process enable for the integrated 2D subsurface (G1 kernel).
+        // AUTO restores the pre-key rule (on iff [2D_AQUIFER*] rows).
+        if      (iequals(val, "ON")  || iequals(val, "YES")) opts.groundwater = 1;
+        else if (iequals(val, "OFF") || iequals(val, "NO"))  opts.groundwater = 0;
+        else if (iequals(val, "AUTO"))                       opts.groundwater = -1;
+        else return "Unknown GROUNDWATER: " + val + " (expected YES|NO|AUTO)";
+    } else if (iequals(key, "GW_ET")) {
+        static const char* kEt[] = {"NONE", "CAPILLARY_RISE", "BOUNDARY_ET", "BOTH"};
+        bool known = false;
+        for (const char* e : kEt)
+            if (iequals(val, e)) { opts.gw_et = e; known = true; break; }
+        if (!known)
+            return "Unknown GW_ET: " + val +
+                   " (expected NONE|CAPILLARY_RISE|BOUNDARY_ET|BOTH)";
     } else if (is2DRetiredOptionKey(key)) {
         // These keys configured the deleted CVODE/ARKODE stack. On file load
         // they are ignored with a WARNING 104 (legacy models must still
@@ -241,8 +412,17 @@ bool is2DOptionKey(const std::string& key) {
         "LIMITER_EPSILON", "FLUX_DH_EPS", "RAINFALL_MODE", "REPORT_2D",
         "CELL_CLOSURE", "FACE_RECONSTRUCTION", "VFR_MIN_WET_FRAC",
         "OUTPUT_FILE",
-        "INTEGRATOR", "THETA", "CFL_NUMBER", "H_MOVE",
+        "INTEGRATOR", "MOMENTUM_EQUATION", "RECONSTRUCTION_ORDER", "FRONT_REBUILD",
+        "THETA", "CFL_NUMBER", "H_MOVE",
         "LTS_TIERS", "FROUDE_MAX", "ADVECTION", "COUPLING_AREA",
+        "COUPLING_IN_FLOODING",
+        "BACKEND",
+        "OUTPUT_PRECISION", "OUTPUT_COMPRESSION", "REPORT_2D_VARIABLES",
+        "REPORT_2D_SPECIES", "REPORT_2D_STEP",
+        "INFILTRATION", "INFIL_STEP", "INFIL_DEFAULT_METHOD", "INFIL_DESTINATION",
+        "EVAPORATION", "TRANSPORT_POLLUTANTS", "TRANSPORT_MSX", "TRANSPORT_AGE",
+        "TRANSPORT_TEMPERATURE",
+        "GROUNDWATER", "GW_ET",
     };
     for (const char* k : kKeys) {
         if (iequals(key, k)) return true;
@@ -251,6 +431,15 @@ bool is2DOptionKey(const std::string& key) {
 }
 
 
+const std::vector& report2DVarTokens() { return report2d::tokens(); }
+
+std::string parseReport2DVars(const std::string& text, unsigned& mask) {
+    return report2d::parseMask(text, mask);
+}
+
+std::string formatReport2DVars(unsigned mask) { return report2d::formatMask(mask); }
+
+
 std::string format2DOptionValue(const SolverOptions2D& opts,
                                 const std::string& key) {
     auto fmt_g = [](double v) {
@@ -276,12 +465,25 @@ std::string format2DOptionValue(const SolverOptions2D& opts,
     if (iequals(key, "RAINFALL_MODE")) {
         switch (opts.rainfall_mode) {
             case RainfallMode::NATURAL_NEIGHBOUR: return "NATURAL_NEIGHBOUR";
+            case RainfallMode::NEAREST_NEIGHBOUR: return "NEAREST_NEIGHBOUR";
             case RainfallMode::SYSTEM:            return "SYSTEM";
             case RainfallMode::NONE:              return "NONE";
         }
         return "NATURAL_NEIGHBOUR";
     }
     if (iequals(key, "INTEGRATOR"))    return "EXPLICIT";
+    if (iequals(key, "MOMENTUM_EQUATION")) {
+        switch (opts.momentum) {
+            case Momentum2D::FULL_SWE:       return "FULL_SWE";
+            case Momentum2D::DIFFUSIVE_WAVE: return "DIFFUSIVE_WAVE";
+            case Momentum2D::LOCAL_INERTIAL: break;
+        }
+        return "LOCAL_INERTIAL";
+    }
+    if (iequals(key, "RECONSTRUCTION_ORDER"))
+        return std::to_string(opts.reconstruction_order);
+    if (iequals(key, "FRONT_REBUILD"))
+        return opts.front_rebuild < 0 ? "AUTO" : (opts.front_rebuild ? "YES" : "NO");
     if (iequals(key, "THETA"))         return fmt_g(opts.theta);
     if (iequals(key, "CFL_NUMBER"))    return fmt_g(opts.cfl_number);
     if (iequals(key, "H_MOVE"))        return fmt_g(opts.h_move);
@@ -289,10 +491,89 @@ std::string format2DOptionValue(const SolverOptions2D& opts,
     if (iequals(key, "FROUDE_MAX"))    return fmt_g(opts.froude_max);
     if (iequals(key, "ADVECTION"))     return opts.advection ? "YES" : "NO";
     if (iequals(key, "COUPLING_AREA")) return opts.coupling_area_auto ? "AUTO" : "DEFAULT";
+    if (iequals(key, "COUPLING_IN_FLOODING"))
+        return opts.coupling_in_flooding ? "YES" : "NO";
+    if (iequals(key, "BACKEND")) {
+        switch (opts.backend) {
+            case Backend2D::CPU:  return "CPU";
+            case Backend2D::OMP:  return "OMP";
+            case Backend2D::CUDA: return "CUDA";
+            case Backend2D::HIP:  return "HIP";
+            case Backend2D::SYCL: return "SYCL";
+            case Backend2D::AUTO: break;
+        }
+        return "AUTO";
+    }
+    if (iequals(key, "OUTPUT_PRECISION"))
+        return opts.output_precision == OutputPrecision2D::FLOAT64 ? "FLOAT64" : "FLOAT32";
+    if (iequals(key, "OUTPUT_COMPRESSION")) return std::to_string(opts.output_compression);
+    if (iequals(key, "REPORT_2D_VARIABLES")) return formatReport2DVars(opts.report_2d_vars);
+    if (iequals(key, "REPORT_2D_SPECIES")) return report2d::formatSpecies(opts.report_2d_species);
+    if (iequals(key, "REPORT_2D_STEP"))    return report2d::formatStep(opts.report_2d_step);
+    // E2 process enables. INFILTRATION AUTO is reported as AUTO (a host
+    // derives the effective state from swmm_infil2d_defaults_count and the
+    // per-cell rows); INFIL_STEP / INFIL_DEFAULT_METHOD report the stored
+    // key only — format2DOptionValueEx resolves the unset cases against the
+    // Infil2D rows when a caller has them.
+    if (iequals(key, "INFILTRATION"))
+        return opts.infiltration < 0 ? "AUTO" : (opts.infiltration ? "YES" : "NO");
+    if (iequals(key, "INFIL_STEP"))           return report2d::formatStep(opts.infil_step);
+    if (iequals(key, "INFIL_DEFAULT_METHOD"))
+        return opts.infil_default_method.empty() ? "NONE" : opts.infil_default_method;
+    if (iequals(key, "INFIL_DESTINATION"))
+        return opts.infil_destination.empty() ? "LOST" : opts.infil_destination;
+    if (iequals(key, "EVAPORATION"))
+        return opts.evaporation == 0 ? "NO" : (opts.evaporation == 2 ? "CLIMATE" : "YES");
+    if (iequals(key, "TRANSPORT_POLLUTANTS"))  return opts.transport_pollutants  ? "YES" : "NO";
+    if (iequals(key, "TRANSPORT_MSX"))         return opts.transport_msx         ? "YES" : "NO";
+    if (iequals(key, "TRANSPORT_AGE"))         return opts.transport_age         ? "YES" : "NO";
+    if (iequals(key, "TRANSPORT_TEMPERATURE")) return opts.transport_temperature ? "YES" : "NO";
+    // Like INFILTRATION, GROUNDWATER reports what was STORED; the Ex form
+    // resolves AUTO against the [2D_AQUIFER*] rows, and reads GW_ET from the
+    // [2D_AQUIFER_OPTIONS] struct that owns it.
+    if (iequals(key, "GROUNDWATER"))
+        return opts.groundwater < 0 ? "AUTO" : (opts.groundwater ? "YES" : "NO");
+    if (iequals(key, "GW_ET"))       return opts.gw_et.empty() ? "NONE" : opts.gw_et;
     return {};
 }
 
 
+std::string format2DOptionValueEx(const SolverOptions2D& opts,
+                                  const Infil2D* infil,
+                                  const std::string& key) {
+    return format2DOptionValueEx(opts, infil, nullptr, key);
+}
+
+std::string format2DOptionValueEx(const SolverOptions2D& opts,
+                                  const Infil2D* infil,
+                                  const SubsurfaceConfig* aquifer,
+                                  const std::string& key) {
+    if (infil) {
+        if (iequals(key, "INFIL_STEP") && opts.infil_step <= 0.0)
+            return report2d::formatStep(infil->options().infil_step);
+        if (iequals(key, "INFIL_DEFAULT_METHOD") && opts.infil_default_method.empty()) {
+            for (const auto& d : infil->defaults())
+                if (d.tag == "*") return infil2DMethodToken(d.row);
+            return "NONE";
+        }
+    }
+    if (aquifer) {
+        // GW_ET lives in [2D_AQUIFER_OPTIONS]; the [2D_OPTIONS] spelling is an
+        // alias that open() folds away, so the staging field is normally empty
+        // and the authoritative value is the only one to report.
+        if (iequals(key, "GW_ET") && opts.gw_et.empty())
+            return aquifer->options.gw_et.empty() ? "NONE"
+                                                  : aquifer->options.gw_et;
+        // GROUNDWATER is deliberately NOT resolved here: like INFILTRATION it
+        // reports AUTO | YES | NO exactly AS STORED, so a host round-trips
+        // what the deck said rather than writing back a resolved YES/NO over
+        // a deck that never spelled the key. Hosts derive the effective state
+        // from the row count.
+    }
+    return format2DOptionValue(opts, key);
+}
+
+
 std::string parse2DVertexLine(const std::vector& tokens,
                                MeshData& mesh) {
     if (tokens.size() < 3) return "Expected X Y Z [TAG]";
@@ -358,11 +639,61 @@ std::string parse2DTriangleLine(const std::vector& tokens,
         }
     }
 
+    int idx = mesh.n_triangles();
+    // Cell index contract: triangles first, then quads (2D_TRI_QUAD_MESH_PLAN
+    // §2.4). A triangle row arriving after a quad row would renumber every
+    // cell-addressed section behind it.
+    if (idx > 0 && mesh.cell_vertex_count(idx - 1) == 4)
+        return "[2D_TRIANGLES] rows must precede all [2D_QUADS] rows "
+               "(cells are numbered triangles first, then quads)";
+    mesh.resize_triangles(idx + 1);
+    mesh.set_triangle(idx, v0, v1, v2);
+    mesh.mannings_n[idx] = n;
+    mesh.tri_init_depth[idx] = init_depth;
+    mesh.tri_tag[idx] = tag;
+
+    return {};
+}
+
+
+// [2D_QUADS] — convex quadrilateral cells, appended AFTER every triangle:
+//   V1 V2 V3 V4 MANNINGS_N [INIT_DEPTH] [TAG]
+// The four vertices are listed in cyclic order (either orientation; the
+// builder orients edge normals outward from the centroid). Cell index of the
+// j-th quad row is n_triangles + j — the unified index every cell-addressed
+// section (`TRI` columns) uses. Local edge k = (V[(k+1)%4], V[(k+2)%4]).
+std::string parse2DQuadLine(const std::vector& tokens,
+                            MeshData& mesh) {
+    if (tokens.size() < 5)
+        return "Expected V1 V2 V3 V4 MANNINGS_N [INIT_DEPTH] [TAG]";
+
+    bool ok = false;
+    int v[4];
+    for (int k = 0; k < 4; ++k) {
+        v[k] = tryParseInt(tokens[static_cast(k)], ok);
+        if (!ok) return "Invalid V" + std::to_string(k + 1) + " index";
+    }
+
+    double n = tryParseDouble(tokens[4], ok);
+    if (!ok) return "Invalid MANNINGS_N value";
+
+    double init_depth = 0.0;
+    std::string tag;
+    if (tokens.size() >= 6) {
+        bool num = false;
+        double d = tryParseDouble(tokens[5], num);
+        if (num) {
+            if (d < 0.0) return "Invalid INIT_DEPTH (must be >= 0)";
+            init_depth = d;
+            if (tokens.size() >= 7) tag = tokens[6];
+        } else {
+            tag = tokens[5];
+        }
+    }
+
     int idx = mesh.n_triangles();
     mesh.resize_triangles(idx + 1);
-    mesh.tri_v0[idx] = v0;
-    mesh.tri_v1[idx] = v1;
-    mesh.tri_v2[idx] = v2;
+    mesh.set_quad(idx, v[0], v[1], v[2], v[3]);
     mesh.mannings_n[idx] = n;
     mesh.tri_init_depth[idx] = init_depth;
     mesh.tri_tag[idx] = tag;
@@ -545,8 +876,9 @@ std::string parse2DBoundaryConditionsLine(
     if (!ok || row.tri < 0)
         return "[2D_BOUNDARY_CONDITIONS] invalid TRI index";
     row.edge = tryParseInt(tokens[1], ok);
-    if (!ok || row.edge < 0 || row.edge > 2)
-        return "[2D_BOUNDARY_CONDITIONS] invalid EDGE (must be 0..2)";
+    if (!ok || row.edge < 0 || row.edge >= kMaxCellVerts)
+        return "[2D_BOUNDARY_CONDITIONS] invalid EDGE (must be 0..2 for a "
+               "triangle, 0..3 for a quad)";
 
     const std::string &type_tok = tokens[2];
     if      (iequals(type_tok, "WALL"))            row.bc_type = static_cast(BoundaryType::WALL);
@@ -632,6 +964,241 @@ std::string parse2DEdgeConveyanceLine(
 }
 
 
+// ============================================================================
+// §5.5 track I — [2D_INFILTRATION_OPTIONS] / [2D_INFILTRATION_DEFAULTS] /
+// [2D_INFILTRATION] line parsers
+// ============================================================================
+
+namespace {
+
+// Shared tail of a [2D_INFILTRATION_DEFAULTS] / [2D_INFILTRATION] row:
+//
+//     METHOD  [P1 .. P5]  [DEST]
+//
+// starting at tokens[first]. Parameter columns are POSITIONAL and carry
+// PROJECT UNITS — they are stored verbatim; Infil2D::resolve() does the
+// conversion. "-" means "unset" and leaves the slot at its default 0.
+// Trailing columns a method does not use may be omitted (the writer trims
+// them with infil2DParamCount), so a row's length varies by method. DEST is
+// recognised as the final token when it is neither numeric nor "-"; absent,
+// the Infil2DRow default (LOST) stands.
+std::string parseInfil2DRowTail(const std::vector& tokens,
+                                std::size_t first,
+                                const char* section,
+                                Infil2DRow& row)
+{
+    if (tokens.size() <= first)
+        return std::string(section) + " missing METHOD";
+
+    if (!parseInfil2DMethod(tokens[first], row.method, row.has_method))
+        return std::string(section) + " unknown METHOD: " + tokens[first];
+
+    std::size_t end = tokens.size();
+    if (end > first + 1) {
+        const std::string& last = tokens[end - 1];
+        bool numeric = false;
+        (void)tryParseDouble(last, numeric);
+        if (!numeric && last != "-") {
+            if (!parseInfil2DDest(last, row.dest))
+                return std::string(section) + " unknown DEST: " + last;
+            row.dest_explicit = true;   // E2: keeps its own DEST over INFIL_DESTINATION
+            --end;
+        }
+    }
+
+    for (std::size_t k = first + 1; k < end; ++k) {
+        const std::size_t idx = k - (first + 1);
+        if (idx >= static_cast(kInfil2DMaxParams))
+            return std::string(section) + " too many parameter columns (max "
+                   + std::to_string(kInfil2DMaxParams) + ")";
+        if (tokens[k] == "-") continue;  // unset
+        bool ok = false;
+        row.p[idx] = tryParseDouble(tokens[k], ok);
+        if (!ok)
+            return std::string(section) + " invalid parameter: " + tokens[k];
+    }
+
+    return {};
+}
+
+// makeSectionHandler's sibling for the [2D_INFILTRATION*] family. Those
+// sections write into the Infil2D owned by SurfaceRouter2D, which — unlike the
+// mesh, options and pending-row buffers — is reached through
+// ctx.twod_io.infil rather than a captured reference. Null (engine built
+// without 2D, or a detached context) means the section is skipped, matching
+// how every other twod_io consumer runtime-guards.
+using InfilLineParser =
+    std::function&, Infil2D&)>;
+
+input::SectionHandler makeInfilSectionHandler(InfilLineParser line_parser) {
+    return [lp = std::move(line_parser)](
+        openswmm::SimulationContext& ctx,
+        const std::vector& lines)
+    {
+        Infil2D* infil = ctx.twod_io.infil;
+        if (!infil) return;
+        for (const auto& raw : lines) {
+            auto tokens = openswmm::input::Tokenizer::tokenize(raw);
+            if (tokens.empty()) continue;
+            std::string err = lp(tokens, *infil);
+            if (!err.empty()) {
+                ctx.error_code    = 5;  // SWMM_ERR_PARSE (see makeSectionHandler)
+                ctx.error_message = "[2D] " + err + " — line: " + raw;
+                return;
+            }
+        }
+    };
+}
+
+} // anonymous namespace
+
+
+std::string parse2DInfiltrationOptionsLine(
+    const std::vector& tokens, Infil2D& infil)
+{
+    if (tokens.empty()) return {};
+    if (tokens.size() < 2)
+        return "[2D_INFILTRATION_OPTIONS] needs PARAMETER VALUE";
+
+    if (!iequals(tokens[0], "INFIL_STEP"))
+        return "Unknown 2D_INFILTRATION_OPTIONS parameter: " + tokens[0];
+
+    // Same duration grammar as WET_STEP / DRY_STEP in [OPTIONS].
+    const double secs = openswmm::input::parse_time_seconds(tokens[1]);
+    if (secs < 0.0)
+        return "[2D_INFILTRATION_OPTIONS] invalid INFIL_STEP (expected "
+               "hh:mm:ss >= 0): " + tokens[1];
+
+    infil.options().infil_step = secs;
+    return {};
+}
+
+
+std::string parse2DInfiltrationDefaultsLine(
+    const std::vector& tokens, Infil2D& infil)
+{
+    if (tokens.empty()) return {};
+    if (tokens.size() < 2)
+        return "[2D_INFILTRATION_DEFAULTS] needs TAG METHOD [P1..P5] [DEST]";
+
+    Infil2DDefault entry;
+    entry.tag = tokens[0];
+
+    const std::string err = parseInfil2DRowTail(
+        tokens, 1, "[2D_INFILTRATION_DEFAULTS]", entry.row);
+    if (!err.empty()) return err;
+
+    infil.defaults().push_back(std::move(entry));
+    return {};
+}
+
+
+std::string parse2DInfiltrationLine(
+    const std::vector& tokens, Infil2D& infil)
+{
+    if (tokens.empty()) return {};
+    if (tokens.size() < 2)
+        return "[2D_INFILTRATION] needs CELL METHOD [P1..P5] [DEST]";
+
+    // CELL is 1-BASED in the file, 0-based in Infil2DOverride::tri. Only the
+    // lower bound is checked here — the mesh may not be loaded yet, so the
+    // upper bound is Infil2D::resolve()'s job.
+    bool ok = false;
+    const int cell = tryParseInt(tokens[0], ok);
+    if (!ok || cell < 1)
+        return "[2D_INFILTRATION] invalid CELL index (1-based): " + tokens[0];
+
+    Infil2DOverride entry;
+    entry.tri = cell - 1;
+
+    const std::string err = parseInfil2DRowTail(
+        tokens, 1, "[2D_INFILTRATION]", entry.row);
+    if (!err.empty()) return err;
+
+    infil.overrides().push_back(std::move(entry));
+    return {};
+}
+
+
+// ============================================================================
+// [2D_INITIAL_QUALITY] — overland transport S1/S2
+// ============================================================================
+
+std::string parse2DInitialQualityLine(
+    const std::vector& tokens,
+    std::vector& rows)
+{
+    if (tokens.empty()) return {};
+    // CELL     |  TAG     |  *  
+    SurfaceRouter2D::PendingInitialQualityRow r;
+    std::size_t at = 0;
+    if (tokens[0] == "*") {
+        if (tokens.size() != 3)
+            return "[2D_INITIAL_QUALITY] '*' row needs SPECIES CONC";
+        r.all = true;
+        at = 1;
+    } else if (iequals(tokens[0], "CELL")) {
+        if (tokens.size() != 4)
+            return "[2D_INITIAL_QUALITY] CELL row needs CELL  SPECIES CONC";
+        bool ok = false;
+        const int cell = tryParseInt(tokens[1], ok);
+        if (!ok || cell < 1)
+            return "[2D_INITIAL_QUALITY] invalid CELL index (1-based): " +
+                   tokens[1];
+        r.tri = cell - 1;   // upper bound is the router's, once the mesh exists
+        at = 2;
+    } else if (iequals(tokens[0], "TAG")) {
+        if (tokens.size() != 4)
+            return "[2D_INITIAL_QUALITY] TAG row needs TAG  SPECIES CONC";
+        r.tag = tokens[1];
+        at = 2;
+    } else {
+        return "[2D_INITIAL_QUALITY] row must start with CELL, TAG or '*': " +
+               tokens[0];
+    }
+    r.species = tokens[at];
+    bool okc = false;
+    r.conc = tryParseDouble(tokens[at + 1], okc);
+    // Refused, not clamped: a negative initial concentration is not a
+    // modelling case, and a non-finite one is a typo that would otherwise
+    // become NaN mass across the mesh.
+    if (!okc || !std::isfinite(r.conc) || r.conc < 0.0)
+        return "[2D_INITIAL_QUALITY] CONC must be a finite non-negative "
+               "number, got '" + tokens[at + 1] + "'";
+    rows.push_back(std::move(r));
+    return {};
+}
+
+// ============================================================================
+// [2D_BOUNDARY_QUALITY] — overland transport S2
+// ============================================================================
+
+std::string parse2DBoundaryQualityLine(
+    const std::vector& tokens,
+    std::vector& rows)
+{
+    if (tokens.empty()) return {};
+    if (tokens.size() != 4)
+        return "[2D_BOUNDARY_QUALITY] needs TRI EDGE SPECIES CONC";
+    bool ok = false;
+    SurfaceRouter2D::PendingBoundaryQualityRow r;
+    r.tri = tryParseInt(tokens[0], ok);
+    if (!ok || r.tri < 0)
+        return "[2D_BOUNDARY_QUALITY] invalid TRI index: " + tokens[0];
+    r.edge = tryParseInt(tokens[1], ok);
+    if (!ok || r.edge < 0 || r.edge >= kMaxCellVerts)
+        return "[2D_BOUNDARY_QUALITY] invalid EDGE (must be 0..2 for a "
+               "triangle, 0..3 for a quad): " + tokens[1];
+    r.species = tokens[2];
+    bool okc = false;
+    r.conc = tryParseDouble(tokens[3], okc);
+    if (!okc || !std::isfinite(r.conc) || r.conc < 0.0)
+        return "[2D_BOUNDARY_QUALITY] CONC must be a finite non-negative "
+               "number, got '" + tokens[3] + "'";
+    rows.push_back(std::move(r));
+    return {};
+}
+
 // ============================================================================
 // register2DSections
 // ============================================================================
@@ -640,8 +1207,22 @@ void register2DSections(MeshData& mesh,
                         SolverOptions2D& options,
                         std::vector& pending_bc_rows,
                         std::vector& pending_ec_rows,
+                        std::vector& pending_iq_rows,
+                        std::vector& pending_bq_rows,
                         input::SectionRegistry& registry)
 {
+    // S1/S2: initial surface species concentration. Main .inp only in this
+    // round — the .2dm sidecar's mini-registry does not carry it (recorded).
+    registry.register_custom("2D_INITIAL_QUALITY",
+        makeSectionHandler([&pending_iq_rows](const std::vector& tokens) {
+            return parse2DInitialQualityLine(tokens, pending_iq_rows);
+        }));
+    // S2: inflow concentration on a non-WALL boundary edge. Main .inp only.
+    registry.register_custom("2D_BOUNDARY_QUALITY",
+        makeSectionHandler([&pending_bq_rows](const std::vector& tokens) {
+            return parse2DBoundaryQualityLine(tokens, pending_bq_rows);
+        }));
+
     // Full-form handler (not makeSectionHandler): parse2DOptionsLine needs
     // ctx.warnings so retired CVODE-era keys warn-and-ignore on file load.
     registry.register_custom("2D_OPTIONS",
@@ -671,6 +1252,11 @@ void register2DSections(MeshData& mesh,
             return parse2DTriangleLine(tokens, mesh);
         }));
 
+    registry.register_custom("2D_QUADS",
+        makeSectionHandler([&mesh](const std::vector& tokens) {
+            return parse2DQuadLine(tokens, mesh);
+        }));
+
     registry.register_custom("2D_INITIAL_VELOCITY",
         makeSectionHandler([&mesh](const std::vector& tokens) {
             return parse2DInitialVelocityLine(tokens, mesh);
@@ -701,6 +1287,18 @@ void register2DSections(MeshData& mesh,
             return parse2DEdgeConveyanceLine(tokens, pending_ec_rows);
         }));
 
+    // §5.5 track I — per-cell infiltration. Rows land in the Infil2D reached
+    // through ctx.twod_io.infil and are resolved against the mesh (tag/cell
+    // precedence) in SurfaceRouter2D::initialize().
+    registry.register_custom("2D_INFILTRATION_OPTIONS",
+        makeInfilSectionHandler(parse2DInfiltrationOptionsLine));
+
+    registry.register_custom("2D_INFILTRATION_DEFAULTS",
+        makeInfilSectionHandler(parse2DInfiltrationDefaultsLine));
+
+    registry.register_custom("2D_INFILTRATION",
+        makeInfilSectionHandler(parse2DInfiltrationLine));
+
     // [2D_MESH_FILE] — capture only the first FILE token; mesh is loaded
     // after the main .inp is fully parsed (see SWMMEngine::open).
     registry.register_custom("2D_MESH_FILE",
@@ -710,7 +1308,14 @@ void register2DSections(MeshData& mesh,
             for (const auto& raw : lines) {
                 auto tokens = openswmm::input::Tokenizer::tokenize(raw);
                 if (tokens.size() >= 2 && iequals(tokens[0], "FILE")) {
-                    options.mesh_file = tokens[1];
+                    // Path may contain spaces; the tokenizer split an unquoted
+                    // path, so rejoin the tokens after FILE (a quoted path is a
+                    // single token already). Fixes meshes like "My Model.2dm".
+                    std::string path = tokens[1];
+                    for (std::size_t k = 2; k < tokens.size(); ++k) { path += ' '; path += tokens[k]; }
+                    if (path.size() >= 2 && path.front() == '"' && path.back() == '"')
+                        path = path.substr(1, path.size() - 2);
+                    options.mesh_file = path;
                     return; // only first FILE line
                 }
             }
@@ -726,16 +1331,21 @@ std::string load2DMeshExternalFile(MeshData& mesh,
                                    SolverOptions2D& opts,
                                    std::vector& pending_bc_rows,
                                    std::vector& pending_ec_rows,
+                                   Infil2D* infil,
                                    const std::string& mesh_file,
                                    const std::string& inp_base_dir,
-                                   std::vector* warnings)
+                                   std::vector* warnings,
+                                   std::vector* pending_iq_rows,
+                                   std::vector* pending_bq_rows)
 {
     namespace fs = std::filesystem;
 
     // Resolve path
-    fs::path p(mesh_file);
+    // utf8_path, not fs::path(std::string): both of these come from the model
+    // as UTF-8 and the latter decodes in the ANSI code page (issue #7).
+    fs::path p = openswmm::io::utf8_path(mesh_file);
     if (p.is_relative() && !inp_base_dir.empty())
-        p = fs::path(inp_base_dir) / p;
+        p = openswmm::io::utf8_path(inp_base_dir) / p;
 
     // Build a minimal registry (no 2D_MESH_FILE — prevents recursion)
     openswmm::input::SectionRegistry mini;
@@ -751,6 +1361,10 @@ std::string load2DMeshExternalFile(MeshData& mesh,
         makeSectionHandler([&mesh](const std::vector& tokens) {
             return parse2DTriangleLine(tokens, mesh);
         }));
+    mini.register_custom("2D_QUADS",
+        makeSectionHandler([&mesh](const std::vector& tokens) {
+            return parse2DQuadLine(tokens, mesh);
+        }));
     mini.register_custom("2D_INITIAL_VELOCITY",
         makeSectionHandler([&mesh](const std::vector& tokens) {
             return parse2DInitialVelocityLine(tokens, mesh);
@@ -770,20 +1384,69 @@ std::string load2DMeshExternalFile(MeshData& mesh,
             return parse2DBoundaryConditionsLine(tokens, pending_bc_rows);
         }));
 
+    // S2/S3 — external .2dm may carry the surface quality sections too (they
+    // travel with the mesh they address). Registered only when the caller
+    // passes the pending stores, so older callers are unchanged.
+    if (pending_iq_rows)
+        mini.register_custom("2D_INITIAL_QUALITY",
+            makeSectionHandler([pending_iq_rows](const std::vector& tokens) {
+                return parse2DInitialQualityLine(tokens, *pending_iq_rows);
+            }));
+    if (pending_bq_rows)
+        mini.register_custom("2D_BOUNDARY_QUALITY",
+            makeSectionHandler([pending_bq_rows](const std::vector& tokens) {
+                return parse2DBoundaryQualityLine(tokens, *pending_bq_rows);
+            }));
+
     // §11A — external .2dm may carry its own [2D_EDGE_CONVEYANCE].
     mini.register_custom("2D_EDGE_CONVEYANCE",
         makeSectionHandler([&pending_ec_rows](const std::vector& tokens) {
             return parse2DEdgeConveyanceLine(tokens, pending_ec_rows);
         }));
 
+    // §5.5.5 — [2D_INFILTRATION*] are per-cell mesh attributes, so they follow
+    // the mesh into the .2dm. The registry the main .inp uses reaches its
+    // target through ctx.twod_io.infil, which the detached context below does
+    // not carry, so the sidecar rows are parsed into a scratch object bound
+    // here by reference and transplanted after the read. Per SECTION
+    // precedence: a section the sidecar carries REPLACES the inline one
+    // (external overrides inline, the [2D_MESH_FILE] rule) rather than
+    // appending to it, so no row can be counted twice; sections the sidecar
+    // omits keep whatever the .inp supplied.
+    Infil2D sidecar_infil;
+    mini.register_custom("2D_INFILTRATION_OPTIONS",
+        makeSectionHandler([&sidecar_infil](const std::vector& tokens) {
+            return parse2DInfiltrationOptionsLine(tokens, sidecar_infil);
+        }));
+    mini.register_custom("2D_INFILTRATION_DEFAULTS",
+        makeSectionHandler([&sidecar_infil](const std::vector& tokens) {
+            return parse2DInfiltrationDefaultsLine(tokens, sidecar_infil);
+        }));
+    mini.register_custom("2D_INFILTRATION",
+        makeSectionHandler([&sidecar_infil](const std::vector& tokens) {
+            return parse2DInfiltrationLine(tokens, sidecar_infil);
+        }));
+
     // The external .2dm may carry its own `;; UNITS:` header. Scan first
     // so SurfaceRouter2D::initialize sees the right flag before it runs.
-    prescan2DUnitsHeader(p.string(), opts);
+    // path_utf8, not p.string(): both callees take a UTF-8 std::string and
+    // re-apply utf8_path themselves, and string() would re-encode to ANSI.
+    const std::string p_utf8 = openswmm::io::path_utf8(p);
+    prescan2DUnitsHeader(p_utf8, opts);
 
     openswmm::input::InputReader reader(mini);
     openswmm::SimulationContext  dummy;
-    if (!reader.read(p.string(), dummy)) {
-        return "2D_MESH_FILE: error reading '" + p.string() + "': " + dummy.error_message;
+    if (!reader.read(p_utf8, dummy)) {
+        return "2D_MESH_FILE: error reading '" + p_utf8 + "': " + dummy.error_message;
+    }
+
+    if (infil != nullptr) {
+        if (!sidecar_infil.defaults().empty())
+            infil->defaults() = std::move(sidecar_infil.defaults());
+        if (!sidecar_infil.overrides().empty())
+            infil->overrides() = std::move(sidecar_infil.overrides());
+        if (sidecar_infil.options().infil_step > 0.0)
+            infil->options() = sidecar_infil.options();
     }
     return {};
 }
@@ -794,22 +1457,34 @@ std::string load2DMeshExternalFile(MeshData& mesh,
 
 void prescan2DUnitsHeader(const std::string& inp_path, SolverOptions2D& opts)
 {
-    std::ifstream in(inp_path);
+    std::ifstream in(openswmm::io::utf8_path(inp_path));
     if (!in) return;  // file missing — caller will surface the error
 
-    auto trim = [](std::string s) {
+    // Views, not strings. This pass reads the ENTIRE .inp — see the note below
+    // on why it cannot stop early — so on a large model it visits millions of
+    // lines. The previous by-value `trim(std::string)` allocated twice per
+    // line (the parameter copy and the substr result) for a scan that almost
+    // always finds nothing.
+    const auto trim = [](std::string_view s) noexcept {
         const auto issp = [](unsigned char c) { return std::isspace(c) != 0; };
-        while (!s.empty() && issp(static_cast(s.back())))   s.pop_back();
-        std::size_t i = 0;
-        while (i < s.size() && issp(static_cast(s[i]))) ++i;
-        return s.substr(i);
+        while (!s.empty() && issp(static_cast(s.back())))
+            s.remove_suffix(1);
+        while (!s.empty() && issp(static_cast(s.front())))
+            s.remove_prefix(1);
+        return s;
     };
 
+    // NB: this deliberately scans to EOF rather than stopping at the first
+    // "[SECTION]" header. The header is not always in the pre-section prefix —
+    // InpWriter emits `;; UNITS: SI (m)` underneath [2D_VERTICES] (InpWriter.cpp
+    // writeMesh2D), so every .inp the engine itself writes carries it mid-file.
+    // Stopping early would silently drop SI mesh scaling on round-trip.
+    // Last match wins, matching the previous behaviour.
     std::string line;
     while (std::getline(in, line)) {
-        const std::string t = trim(line);
+        const std::string_view t = trim(line);
         if (t.size() < 2 || t[0] != ';' || t[1] != ';') continue;
-        std::string rest = trim(t.substr(2));
+        std::string_view rest = trim(t.substr(2));
         // Match "UNITS:" prefix case-insensitively.
         constexpr std::string_view kKey = "UNITS:";
         if (rest.size() < kKey.size()) continue;
@@ -820,7 +1495,7 @@ void prescan2DUnitsHeader(const std::string& inp_path, SolverOptions2D& opts)
             }
         }
         if (!match) continue;
-        const std::string value = trim(rest.substr(kKey.size()));
+        const std::string_view value = trim(rest.substr(kKey.size()));
         // Recognised metric markers.  Anything else (including absent /
         // unknown / explicit "ft") leaves the flag at its current value.
         const bool si =
diff --git a/src/engine/2d/input/SectionHandlers2D.hpp b/src/engine/2d/input/SectionHandlers2D.hpp
index 2b0875263..84f483d74 100644
--- a/src/engine/2d/input/SectionHandlers2D.hpp
+++ b/src/engine/2d/input/SectionHandlers2D.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SectionHandlers2D.hpp
  * @brief Input section parsers for the 2D surface routing module.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SECTION_HANDLERS_HPP
@@ -25,6 +41,7 @@
 
 #include "../data/MeshData.hpp"
 #include "../data/SolverOptions2D.hpp"
+#include "../infil/Infil2D.hpp"
 #include "../SurfaceRouter2D.hpp"
 #include "../../input/SectionRegistry.hpp"
 
@@ -73,6 +90,15 @@ std::string parse2DVertexLine(const std::vector& tokens,
 std::string parse2DTriangleLine(const std::vector& tokens,
                                  MeshData& mesh);
 
+/**
+ * @brief Parse a single line from the [2D_QUADS] section.
+ *
+ * Format: V1 V2 V3 V4 MANNINGS_N [INIT_DEPTH] [TAG]
+ * Quads are appended after every triangle (cell index = n_triangles + j).
+ */
+std::string parse2DQuadLine(const std::vector& tokens,
+                            MeshData& mesh);
+
 /**
  * @brief Parse a single line from the [2D_INITIAL_VELOCITY] section.
  *
@@ -145,6 +171,52 @@ std::string parse2DEdgeConveyanceLine(
     const std::vector& tokens,
     std::vector& pending_rows);
 
+/**
+ * @brief §5.5 track I — parse a single `[2D_INFILTRATION_OPTIONS]` line.
+ *
+ * Format: `INFIL_STEP `
+ *   The only key. Accepts the same duration grammar as WET_STEP/DRY_STEP in
+ *   [OPTIONS] (`hh:mm:ss`, `hh:mm`, or plain seconds) and stores seconds in
+ *   Infil2DOptions::infil_step. 0 means "use the project WET_STEP" (D-I1).
+ */
+std::string parse2DInfiltrationOptionsLine(
+    const std::vector& tokens, Infil2D& infil);
+
+/**
+ * @brief §5.5 track I — parse a single `[2D_INFILTRATION_DEFAULTS]` line.
+ *
+ * Format: `TAG|*  METHOD  [P1 .. P5]  [DEST]`
+ *   TAG      : `[2D_TRIANGLES]` TAG to match, or `*` for the mesh-wide default.
+ *   METHOD   : HORTON / MODIFIED_HORTON / GREEN_AMPT / MODIFIED_GREEN_AMPT /
+ *              CURVE_NUMBER / CONSTANT / NONE (parseInfil2DMethod).
+ *   P1..P5   : POSITIONAL parameters in PROJECT UNITS, laid out per method
+ *              exactly like legacy [INFILTRATION] (see the table on
+ *              Infil2DRow). `-` means "unset"; trailing columns a method does
+ *              not use may be omitted.
+ *   DEST     : LOST / SUBCATCH_AQUIFER / AQUIFER_2D (default LOST). Only LOST
+ *              is accepted at validation in this release (D-I4).
+ *
+ * Rows are appended to `infil.defaults()` in file order and resolved against
+ * the mesh in Infil2D::resolve() (D-I3: override > tag > `*` > none).
+ */
+std::string parse2DInfiltrationDefaultsLine(
+    const std::vector& tokens, Infil2D& infil);
+
+/**
+ * @brief §5.5 track I — parse a single `[2D_INFILTRATION]` line.
+ *
+ * Format: `CELL  METHOD  [P1 .. P5]  [DEST]`
+ *   CELL is the triangle index, **1-BASED in the file** and stored 0-based in
+ *   Infil2DOverride::tri. The upper bound is checked in Infil2D::resolve() —
+ *   the mesh is not necessarily loaded when this section is read.
+ *   The remaining columns are identical to [2D_INFILTRATION_DEFAULTS].
+ *
+ * Rows are appended to `infil.overrides()` and take precedence over every
+ * default row for that cell.
+ */
+std::string parse2DInfiltrationLine(
+    const std::vector& tokens, Infil2D& infil);
+
 /**
  * @brief True when @p key (case-insensitive) is a [2D_OPTIONS] parameter
  *        accepted by parse2DOptionsLine.
@@ -178,9 +250,46 @@ bool is2DRetiredOptionKey(const std::string& key);
  * @return The value token, or an empty string for unknown keys
  *         (and for an unset OUTPUT_FILE, whose value token is optional).
  */
+/**
+ * @brief Token ↔ bitmask helpers for [2D_OPTIONS] REPORT_2D_VARIABLES.
+ *
+ * report2DVarTokens() lists the group tokens in bit order (DEPTH, VELOCITY,
+ * EDGE_FLUX, NODE_HEAD, SPECIES, RAINFALL, INFILTRATION, COUPLING,
+ * GRADIENTS, CONTINUITY, ENVELOPES, BUILDUP (S7), GROUNDWATER, GW_DETAILED
+ * (G-O)). parseReport2DVars() accepts a
+ * whitespace/comma-separated list of those tokens or one of the presets
+ * DEFAULT | MINIMAL | ALL (case-insensitive); it returns an empty error
+ * string on success. formatReport2DVars() writes a preset name when the mask
+ * equals one, else the token list.
+ */
+const std::vector& report2DVarTokens();
+std::string parseReport2DVars(const std::string& text, unsigned& mask);
+std::string formatReport2DVars(unsigned mask);
+
 std::string format2DOptionValue(const SolverOptions2D& opts,
                                 const std::string& key);
 
+/**
+ * @brief format2DOptionValue with the E2 infiltration keys resolved against
+ *        the model's [2D_INFILTRATION*] rows: INFIL_STEP falls back to the
+ *        section value, INFIL_DEFAULT_METHOD to the '*' row's method.
+ *        INFILTRATION stays AUTO | YES | NO as stored. @p infil may be null.
+ */
+std::string format2DOptionValueEx(const SolverOptions2D& opts,
+                                  const Infil2D* infil,
+                                  const std::string& key);
+
+/**
+ * @brief As above, and additionally resolves the groundwater enables against
+ *        the `[2D_AQUIFER*]` authoring: GROUNDWATER AUTO reports the YES|NO
+ *        the kernel will actually take, and GW_ET reads the
+ *        `[2D_AQUIFER_OPTIONS]` field that owns it. @p aquifer may be null.
+ */
+std::string format2DOptionValueEx(const SolverOptions2D& opts,
+                                  const Infil2D* infil,
+                                  const SubsurfaceConfig* aquifer,
+                                  const std::string& key);
+
 /**
  * @brief Register all 2D input section handlers with the section registry.
  *
@@ -195,20 +304,43 @@ void register2DSections(MeshData& mesh,
                         SolverOptions2D& options,
                         std::vector& pending_bc_rows,
                         std::vector& pending_ec_rows,
+                        std::vector& pending_iq_rows,
+                        std::vector& pending_bq_rows,
                         input::SectionRegistry& registry);
 
+/// S1/S2 — one `[2D_INITIAL_QUALITY]` line. Empty string = OK.
+std::string parse2DInitialQualityLine(
+    const std::vector& tokens,
+    std::vector& rows);
+
+/// S2 — one `[2D_BOUNDARY_QUALITY]` line (`TRI EDGE SPECIES CONC`). Empty = OK.
+std::string parse2DBoundaryQualityLine(
+    const std::vector& tokens,
+    std::vector& rows);
+
 /**
  * @brief Load 2D mesh sections from an external file.
  *
  * Opens the file referenced by @p mesh_file (resolved relative to
  * @p inp_base_dir if it is a relative path) and parses any
  * [2D_OPTIONS], [2D_VERTICES], [2D_TRIANGLES], [2D_VERTEX_NODE_MAP],
- * and [2D_TRIANGLE_NODE_MAP] sections found in it.
+ * [2D_TRIANGLE_NODE_MAP] and [2D_INFILTRATION*] sections found in it.
  *
  * @param mesh         Mesh data to populate.
  * @param opts         Solver options to populate.
  * @param mesh_file    Path from the [2D_MESH_FILE] FILE token.
  * @param inp_base_dir Directory of the parent .inp file (may be empty).
+ * @param infil        Per-cell infiltration to populate from the sidecar's
+ *                     [2D_INFILTRATION*] sections (plan §5.5.5 — these are
+ *                     per-cell mesh attributes, so they travel with the mesh
+ *                     exactly like [2D_VERTICES]/[2D_TRIANGLES]). The .2dm is
+ *                     parsed against a detached context, so the handlers
+ *                     cannot reach it through ctx.twod_io.infil and it must be
+ *                     passed explicitly. May be null (rows are then dropped).
+ *                     A section present in BOTH files resolves in favour of
+ *                     the sidecar, matching the [2D_MESH_FILE] rule that the
+ *                     external file overrides the inline one; rows are never
+ *                     merged, so nothing is double-counted.
  * @param warnings     Optional sink for retired-key warnings (see
  *                     parse2DOptionsLine); pass &ctx.warnings so a legacy
  *                     external mesh file still loads.
@@ -218,9 +350,12 @@ std::string load2DMeshExternalFile(MeshData& mesh,
                                    SolverOptions2D& opts,
                                    std::vector& pending_bc_rows,
                                    std::vector& pending_ec_rows,
+                                   Infil2D* infil,
                                    const std::string& mesh_file,
                                    const std::string& inp_base_dir,
-                                   std::vector* warnings = nullptr);
+                                   std::vector* warnings = nullptr,
+                                   std::vector* pending_iq_rows = nullptr,
+                                   std::vector* pending_bq_rows = nullptr);
 
 /**
  * @brief Scan @p inp_path for a `;; UNITS: ` comment header and set
diff --git a/src/engine/2d/mesh/MeshBuilder.cpp b/src/engine/2d/mesh/MeshBuilder.cpp
index 2444e7ade..d173056ec 100644
--- a/src/engine/2d/mesh/MeshBuilder.cpp
+++ b/src/engine/2d/mesh/MeshBuilder.cpp
@@ -1,12 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file MeshBuilder.cpp
  * @brief Implementation of mesh topology construction and geometry computation.
  *
+ * @details Mixed triangle / quadrilateral cells (kMaxCellVerts = 4 padded
+ *          layout, see MeshData.hpp). Triangle arithmetic is kept
+ *          expression-for-expression identical to the triangle-only builder
+ *          so an all-triangle mesh reproduces its geometry bit-for-bit; quads
+ *          use the shoelace area and the area-weighted centroid of their two
+ *          sub-triangles (the vertex mean is NOT the centroid of a skewed
+ *          quad, and the Perot arms / ghost distances need the real one).
+ *
  * @see MeshBuilder.hpp
  * @ingroup engine_2d
  */
 
 #include "MeshBuilder.hpp"
+#include "QuadVfr.hpp"
 
 #include 
 #include 
@@ -36,67 +61,56 @@ struct EdgeKeyHash {
     }
 };
 
-// Edge record: first triangle and local edge that claimed this edge
+// Edge record: first cell and local edge that claimed this edge
 struct EdgeRecord {
-    int tri_idx;
-    int local_edge;  // 0, 1, 2
+    int cell_idx;
+    int local_edge;  // 0 .. nv-1
 };
 
-// Get the two vertex indices for local edge e of triangle t
-// Edge 0 = opposite v0 → between v1 and v2
-// Edge 1 = opposite v1 → between v2 and v0
-// Edge 2 = opposite v2 → between v0 and v1
-inline std::pair edgeVertices(const MeshData& mesh, int t, int e) {
-    int v[3] = {mesh.tri_v0[t], mesh.tri_v1[t], mesh.tri_v2[t]};
-    int a = v[(e + 1) % 3];
-    int b = v[(e + 2) % 3];
-    return {a, b};
-}
-
 inline EdgeKey makeEdgeKey(int va, int vb) {
     return {std::min(va, vb), std::max(va, vb)};
 }
 
+inline void computeQuadVfr(MeshData& mesh, int t);
+
 } // anonymous namespace
 
 
 void buildMeshTopology(MeshData& mesh) {
-    int nt = mesh.n_triangles();
-    int nv = mesh.n_vertices();
+    const int nt = mesh.n_triangles();
 
     // --- 1. Build edge-neighbour adjacency ---
 
-    // Map: sorted vertex pair → first triangle that claimed this edge
+    // Map: sorted vertex pair → first cell that claimed this edge
     std::unordered_map edge_map;
-    edge_map.reserve(nt * 3);
-
-    // Initialize neighbours to -1 (boundary)
-    std::fill(mesh.tri_nbr0.begin(), mesh.tri_nbr0.end(), -1);
-    std::fill(mesh.tri_nbr1.begin(), mesh.tri_nbr1.end(), -1);
-    std::fill(mesh.tri_nbr2.begin(), mesh.tri_nbr2.end(), -1);
-
-    auto set_nbr = [&](int tri, int local_edge, int nbr_tri) {
-        switch (local_edge) {
-            case 0: mesh.tri_nbr0[tri] = nbr_tri; break;
-            case 1: mesh.tri_nbr1[tri] = nbr_tri; break;
-            case 2: mesh.tri_nbr2[tri] = nbr_tri; break;
-        }
-    };
+    edge_map.reserve(static_cast(nt) * kMaxCellVerts);
+
+    // Initialize neighbours to -1 (boundary) on real slots, -2 on padding.
+    for (int t = 0; t < nt; ++t) {
+        const int nv = mesh.cell_vertex_count(t);
+        for (int k = 0; k < kMaxCellVerts; ++k)
+            mesh.cell_nbr[static_cast(MeshData::slot(t, k))] =
+                (k < nv) ? -1 : -2;
+    }
 
     for (int t = 0; t < nt; ++t) {
-        for (int e = 0; e < 3; ++e) {
-            auto [va, vb] = edgeVertices(mesh, t, e);
+        const int nv = mesh.cell_vertex_count(t);
+        for (int e = 0; e < nv; ++e) {
+            int va, vb;
+            mesh.cell_edge_vertices(t, e, va, vb);
             auto key = makeEdgeKey(va, vb);
 
             auto it = edge_map.find(key);
             if (it == edge_map.end()) {
-                // First triangle to claim this edge
+                // First cell to claim this edge
                 edge_map[key] = {t, e};
             } else {
-                // Second triangle — complete the pair
+                // Second cell — complete the pair
                 auto& first = it->second;
-                set_nbr(t, e, first.tri_idx);
-                set_nbr(first.tri_idx, first.local_edge, t);
+                mesh.cell_nbr[static_cast(MeshData::slot(t, e))] =
+                    first.cell_idx;
+                mesh.cell_nbr[static_cast(
+                    MeshData::slot(first.cell_idx, first.local_edge))] = t;
             }
         }
     }
@@ -104,34 +118,81 @@ void buildMeshTopology(MeshData& mesh) {
     // --- 2. Compute cell geometry ---
 
     for (int t = 0; t < nt; ++t) {
-        int v0 = mesh.tri_v0[t];
-        int v1 = mesh.tri_v1[t];
-        int v2 = mesh.tri_v2[t];
-
-        double x0 = mesh.vx[v0], y0 = mesh.vy[v0], z0 = mesh.vz[v0];
-        double x1 = mesh.vx[v1], y1 = mesh.vy[v1], z1 = mesh.vz[v1];
-        double x2 = mesh.vx[v2], y2 = mesh.vy[v2], z2 = mesh.vz[v2];
-
-        // Centroid
-        mesh.tri_cx[t] = (x0 + x1 + x2) / 3.0;
-        mesh.tri_cy[t] = (y0 + y1 + y2) / 3.0;
-        mesh.tri_cz[t] = (z0 + z1 + z2) / 3.0;
-
-        // Area via cross product: 0.5 * ||(v1-v0) × (v2-v0)||
-        double dx1 = x1 - x0, dy1 = y1 - y0;
-        double dx2 = x2 - x0, dy2 = y2 - y0;
-        mesh.tri_area[t] = 0.5 * std::abs(dx1 * dy2 - dx2 * dy1);
+        const int nv = mesh.cell_vertex_count(t);
+        if (nv == 3) {
+            // Triangle: identical expressions to the triangle-only builder.
+            int v0 = mesh.cell_vertex(t, 0);
+            int v1 = mesh.cell_vertex(t, 1);
+            int v2 = mesh.cell_vertex(t, 2);
+
+            double x0 = mesh.vx[v0], y0 = mesh.vy[v0], z0 = mesh.vz[v0];
+            double x1 = mesh.vx[v1], y1 = mesh.vy[v1], z1 = mesh.vz[v1];
+            double x2 = mesh.vx[v2], y2 = mesh.vy[v2], z2 = mesh.vz[v2];
+
+            // Centroid
+            mesh.tri_cx[t] = (x0 + x1 + x2) / 3.0;
+            mesh.tri_cy[t] = (y0 + y1 + y2) / 3.0;
+            mesh.tri_cz[t] = (z0 + z1 + z2) / 3.0;
+
+            // Area via cross product: 0.5 * ||(v1-v0) × (v2-v0)||
+            double dx1 = x1 - x0, dy1 = y1 - y0;
+            double dx2 = x2 - x0, dy2 = y2 - y0;
+            mesh.tri_area[t] = 0.5 * std::abs(dx1 * dy2 - dx2 * dy1);
+        } else {
+            // Quadrilateral (v0 v1 v2 v3): shoelace area; centroid as the
+            // area-weighted centroid of the two sub-triangles (v0,v1,v2) and
+            // (v0,v2,v3) — a property of the polygon, independent of which
+            // diagonal is used. Mean bed elevation over the four vertices.
+            double x[4], y[4], z[4];
+            for (int k = 0; k < 4; ++k) {
+                const int v = mesh.cell_vertex(t, k);
+                x[k] = mesh.vx[v]; y[k] = mesh.vy[v]; z[k] = mesh.vz[v];
+            }
+            const double a1s = 0.5 * ((x[1] - x[0]) * (y[2] - y[0]) -
+                                      (x[2] - x[0]) * (y[1] - y[0]));
+            const double a2s = 0.5 * ((x[2] - x[0]) * (y[3] - y[0]) -
+                                      (x[3] - x[0]) * (y[2] - y[0]));
+            const double a1 = std::abs(a1s), a2 = std::abs(a2s);
+            const double area = a1 + a2;
+            const double c1x = (x[0] + x[1] + x[2]) / 3.0;
+            const double c1y = (y[0] + y[1] + y[2]) / 3.0;
+            const double c2x = (x[0] + x[2] + x[3]) / 3.0;
+            const double c2y = (y[0] + y[2] + y[3]) / 3.0;
+            if (area > 0.0) {
+                mesh.tri_cx[t] = (a1 * c1x + a2 * c2x) / area;
+                mesh.tri_cy[t] = (a1 * c1y + a2 * c2y) / area;
+            } else {
+                mesh.tri_cx[t] = 0.25 * (x[0] + x[1] + x[2] + x[3]);
+                mesh.tri_cy[t] = 0.25 * (y[0] + y[1] + y[2] + y[3]);
+            }
+            mesh.tri_cz[t] = 0.25 * (z[0] + z[1] + z[2] + z[3]);
+            mesh.tri_area[t] = area;
+        }
     }
+    // Quad VFR side data (needs the connectivity + z only; sized on first quad).
+    mesh.quad_vfr_z.clear();
+    mesh.quad_vfr_a.clear();
+    for (int t = 0; t < nt; ++t) computeQuadVfr(mesh, t);
 
     // --- 3. Compute edge geometry ---
 
     for (int t = 0; t < nt; ++t) {
         double cx = mesh.tri_cx[t];
         double cy = mesh.tri_cy[t];
-
-        for (int e = 0; e < 3; ++e) {
-            auto [va, vb] = edgeVertices(mesh, t, e);
-            int idx = t * 3 + e;
+        const int nv = mesh.cell_vertex_count(t);
+
+        for (int e = 0; e < kMaxCellVerts; ++e) {
+            int idx = MeshData::slot(t, e);
+            if (e >= nv) {
+                // Padding slot: zero geometry, so a stray read is inert.
+                mesh.edge_mx[idx] = mesh.edge_my[idx] = mesh.edge_mz[idx] = 0.0;
+                mesh.edge_length[idx] = 0.0;
+                mesh.edge_nx[idx] = mesh.edge_ny[idx] = 0.0;
+                mesh.edge_dist_c[idx] = 0.0;
+                continue;
+            }
+            int va, vb;
+            mesh.cell_edge_vertices(t, e, va, vb);
 
             double ax = mesh.vx[va], ay = mesh.vy[va], az = mesh.vz[va];
             double bx = mesh.vx[vb], by = mesh.vy[vb], bz = mesh.vz[vb];
@@ -168,42 +229,76 @@ void buildMeshTopology(MeshData& mesh) {
                 mesh.edge_nx[idx] = 0.0;
                 mesh.edge_ny[idx] = 0.0;
             }
+            // Centroid → edge normal distance (the ghost-cell arm).
+            mesh.edge_dist_c[idx] =
+                to_mid_x * mesh.edge_nx[idx] + to_mid_y * mesh.edge_ny[idx];
         }
     }
 }
 
 
 std::string validateMesh(const MeshData& mesh) {
-    int nv = mesh.n_vertices();
+    int nv_total = mesh.n_vertices();
     int nt = mesh.n_triangles();
 
-    if (nv < 3) return "Mesh must have at least 3 vertices";
-    if (nt < 1) return "Mesh must have at least 1 triangle";
+    if (nv_total < 3) return "Mesh must have at least 3 vertices";
+    if (nt < 1) return "Mesh must have at least 1 cell";
 
     for (int t = 0; t < nt; ++t) {
-        int v0 = mesh.tri_v0[t], v1 = mesh.tri_v1[t], v2 = mesh.tri_v2[t];
-
-        if (v0 < 0 || v0 >= nv || v1 < 0 || v1 >= nv || v2 < 0 || v2 >= nv) {
+        const int nv = mesh.cell_vertex_count(t);
+        const char* kind = (nv == 4) ? "Quad " : "Triangle ";
+        if (nv != 3 && nv != 4) {
             std::ostringstream oss;
-            oss << "Triangle " << t << " has out-of-range vertex index";
+            oss << "Cell " << t << " has unsupported vertex count " << nv;
             return oss.str();
         }
-
-        if (v0 == v1 || v1 == v2 || v0 == v2) {
-            std::ostringstream oss;
-            oss << "Triangle " << t << " has duplicate vertex indices";
-            return oss.str();
+        int v[4] = {-1, -1, -1, -1};
+        for (int k = 0; k < nv; ++k) {
+            v[k] = mesh.cell_vertex(t, k);
+            if (v[k] < 0 || v[k] >= nv_total) {
+                std::ostringstream oss;
+                oss << kind << t << " has out-of-range vertex index";
+                return oss.str();
+            }
         }
+        for (int a = 0; a < nv; ++a)
+            for (int b = a + 1; b < nv; ++b)
+                if (v[a] == v[b]) {
+                    std::ostringstream oss;
+                    oss << kind << t << " has duplicate vertex indices";
+                    return oss.str();
+                }
 
         if (mesh.tri_area[t] <= 0.0) {
             std::ostringstream oss;
-            oss << "Triangle " << t << " has zero or negative area";
+            oss << kind << t << " has zero or negative area";
             return oss.str();
         }
 
+        if (nv == 4) {
+            // Convex and simple: every consecutive edge-pair cross product
+            // has the same sign (either orientation is accepted — the edge
+            // normals are oriented outward from the centroid regardless).
+            int sign = 0;
+            for (int k = 0; k < 4; ++k) {
+                const int p = v[k], q = v[(k + 1) % 4], r = v[(k + 2) % 4];
+                const double cr = (mesh.vx[q] - mesh.vx[p]) * (mesh.vy[r] - mesh.vy[q]) -
+                                  (mesh.vy[q] - mesh.vy[p]) * (mesh.vx[r] - mesh.vx[q]);
+                const int s = (cr > 0.0) ? 1 : (cr < 0.0) ? -1 : 0;
+                if (s == 0 || (sign != 0 && s != sign)) {
+                    std::ostringstream oss;
+                    oss << "Quad " << t << " (vertices " << v[0] << " " << v[1]
+                        << " " << v[2] << " " << v[3]
+                        << ") is not a convex quadrilateral";
+                    return oss.str();
+                }
+                sign = s;
+            }
+        }
+
         if (mesh.mannings_n[t] <= 0.0) {
             std::ostringstream oss;
-            oss << "Triangle " << t << " has non-positive Manning's n";
+            oss << kind << t << " has non-positive Manning's n";
             return oss.str();
         }
     }
@@ -211,13 +306,33 @@ std::string validateMesh(const MeshData& mesh) {
     return {};
 }
 
-void recomputeVertexZDependents(MeshData& mesh, int vidx) {
-    const int nt = mesh.n_triangles();
-    for (int t = 0; t < nt; ++t) {
-        const int v0 = mesh.tri_v0[t];
-        const int v1 = mesh.tri_v1[t];
-        const int v2 = mesh.tri_v2[t];
-        if (v0 != vidx && v1 != vidx && v2 != vidx) continue;
+namespace {
+// Quad VFR side data for cell t (no-op for triangles). Allocates the SoA on
+// first use so all-triangle meshes carry nothing.
+inline void computeQuadVfr(MeshData& mesh, int t) {
+    if (mesh.cell_vertex_count(t) != 4) return;
+    const auto nt = static_cast(mesh.n_triangles());
+    if (mesh.quad_vfr_z.size() != nt * kQuadVfrZ) mesh.quad_vfr_z.assign(nt * kQuadVfrZ, 0.0);
+    if (mesh.quad_vfr_a.size() != nt * 2)         mesh.quad_vfr_a.assign(nt * 2, 0.0);
+    double x[4], y[4], z[4];
+    for (int k = 0; k < 4; ++k) {
+        const int v = mesh.cell_vertex(t, k);
+        x[k] = mesh.vx[v]; y[k] = mesh.vy[v]; z[k] = mesh.vz[v];
+    }
+    double A1 = 0.0, A2 = 0.0;
+    quadVfrPrecompute(x, y, z, &mesh.quad_vfr_z[static_cast(t) * kQuadVfrZ], A1, A2);
+    mesh.quad_vfr_a[static_cast(t) * 2 + 0] = A1;
+    mesh.quad_vfr_a[static_cast(t) * 2 + 1] = A2;
+}
+
+// Z-dependent geometry of one cell: mean bed and edge-midpoint beds. Triangle
+// expressions kept identical to the triangle-only builder (bit-identity).
+inline void recomputeCellZ(MeshData& mesh, int t) {
+    const int nv = mesh.cell_vertex_count(t);
+    if (nv == 3) {
+        const int v0 = mesh.cell_vertex(t, 0);
+        const int v1 = mesh.cell_vertex(t, 1);
+        const int v2 = mesh.cell_vertex(t, 2);
 
         const double z0 = mesh.vz[v0];
         const double z1 = mesh.vz[v1];
@@ -226,10 +341,42 @@ void recomputeVertexZDependents(MeshData& mesh, int vidx) {
         mesh.tri_cz[t] = (z0 + z1 + z2) / 3.0;
 
         // Edge e (0..2) is opposite vertex e; its endpoints are the other two
-        // vertices of the triangle (same convention as MeshBuilder::edgeVertices).
-        mesh.edge_mz[t * 3 + 0] = 0.5 * (z1 + z2);
-        mesh.edge_mz[t * 3 + 1] = 0.5 * (z2 + z0);
-        mesh.edge_mz[t * 3 + 2] = 0.5 * (z0 + z1);
+        // vertices of the triangle (same convention as cell_edge_vertices).
+        mesh.edge_mz[MeshData::slot(t, 0)] = 0.5 * (z1 + z2);
+        mesh.edge_mz[MeshData::slot(t, 1)] = 0.5 * (z2 + z0);
+        mesh.edge_mz[MeshData::slot(t, 2)] = 0.5 * (z0 + z1);
+        return;
+    }
+    double zsum = 0.0;
+    for (int k = 0; k < nv; ++k) zsum += mesh.vz[mesh.cell_vertex(t, k)];
+    mesh.tri_cz[t] = zsum / static_cast(nv);
+    for (int e = 0; e < nv; ++e) {
+        int va, vb;
+        mesh.cell_edge_vertices(t, e, va, vb);
+        mesh.edge_mz[MeshData::slot(t, e)] = 0.5 * (mesh.vz[va] + mesh.vz[vb]);
+    }
+    computeQuadVfr(mesh, t);
+}
+} // namespace
+
+void recomputeVertexZDependents(MeshData& mesh, int vidx) {
+    const int nt = mesh.n_triangles();
+    for (int t = 0; t < nt; ++t) {
+        const int nv = mesh.cell_vertex_count(t);
+        bool hit = false;
+        for (int k = 0; k < nv && !hit; ++k) hit = (mesh.cell_vertex(t, k) == vidx);
+        if (!hit) continue;
+        recomputeCellZ(mesh, t);
+    }
+}
+
+void recomputeAllZDependents(MeshData& mesh) {
+    const int nt = mesh.n_triangles();
+    for (int t = 0; t < nt; ++t) {
+        // Identical body to recomputeVertexZDependents above, minus the
+        // incidence filter — same operands in the same order, so the results
+        // are bitwise equal to recomputing vertex by vertex.
+        recomputeCellZ(mesh, t);
     }
 }
 
diff --git a/src/engine/2d/mesh/MeshBuilder.hpp b/src/engine/2d/mesh/MeshBuilder.hpp
index a98acdbb5..364bd248b 100644
--- a/src/engine/2d/mesh/MeshBuilder.hpp
+++ b/src/engine/2d/mesh/MeshBuilder.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file MeshBuilder.hpp
  * @brief Topology construction and geometry precomputation for the 2D mesh.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_MESH_BUILDER_HPP
@@ -60,6 +76,22 @@ std::string validateMesh(const MeshData& mesh);
  */
 void recomputeVertexZDependents(MeshData& mesh, int vidx);
 
+/**
+ * @brief Whole-mesh form of `recomputeVertexZDependents`.
+ *
+ * Recomputes `tri_cz` and `edge_mz` for EVERY triangle in one pass, and
+ * produces bitwise-identical values to calling the per-vertex form for every
+ * vertex in turn (same operands, same operand order, same arithmetic).
+ *
+ * This exists because the per-vertex form scans all triangles per call: doing
+ * that once per vertex is O(nVertices x nTriangles), which is minutes on a
+ * million-cell mesh. `swmm_2d_set_vertex_z_bulk` writes every Z and then calls
+ * this once, making the same work O(nVertices + nTriangles).
+ *
+ * @param mesh The mesh; `mesh.vz` is assumed to already hold the new Zs.
+ */
+void recomputeAllZDependents(MeshData& mesh);
+
 } // namespace openswmm::twoD
 
 #endif // OPENSWMM_ENGINE_2D_MESH_BUILDER_HPP
diff --git a/src/engine/2d/mesh/QuadVfr.hpp b/src/engine/2d/mesh/QuadVfr.hpp
new file mode 100644
index 000000000..742c252f3
--- /dev/null
+++ b/src/engine/2d/mesh/QuadVfr.hpp
@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file QuadVfr.hpp
+ * @brief Volume–free-surface relationship (VFR) for a quadrilateral cell.
+ *
+ * @details Begnudelli & Sanders (2007), "Conservative Wetting and Drying
+ *          Methodology for Quadrilateral Grid Finite-Volume Models", JHE
+ *          133(3):312–322. Four vertices do not in general lie on a plane, so
+ *          the cell is split along a diagonal into two planar sub-triangles
+ *          for the purpose of budgeting storage; the diagonal is chosen from
+ *          the elevation ordering n1 ≤ n2 ≤ n3 ≤ n4 (their Cases 1–3):
+ *
+ *            Case 1  n1, n4 diagonally opposite     → diagonal n1–n4,
+ *                    sub-triangles (n1,n2,n4), (n1,n3,n4)
+ *            Case 2  n1, n4 adjacent, n2 adjacent to n1 → diagonal n2–n4,
+ *                    sub-triangles (n1,n2,n4), (n2,n3,n4)
+ *            Case 3  n1, n4 adjacent, n2 adjacent to n4 → diagonal n3–n4,
+ *                    sub-triangles (n1,n3,n4), (n2,n3,n4)
+ *
+ *          The paper's Eqs. 8–13 (piecewise cubic / quadratic / linear
+ *          h(η) with the Appendix coefficient tables) are exactly the SUM of
+ *          the two planar-triangle VFRs (B&S 2006, VfrClosure.hpp) weighted
+ *          by the sub-triangle areas:
+ *
+ *            h̄(η) = [ A₁·d̄(η; z_a,z_b,z_d) + A₂·d̄(η; z_a,z_c,z_d) ] / (A₁+A₂)
+ *
+ *          This header implements that sum directly (the plan's "Q-A"
+ *          generic form), reusing the tested, ε-regularised triangle closure
+ *          so quads and triangles share one regularisation and one
+ *          round-trip contract. The inverse η(h̄) is a safeguarded Newton on
+ *          the monotone sum (closed form when fully wet). The closed-form
+ *          Appendix coefficients are an optional optimisation ("Q-B") and
+ *          would be unit-tested against these functions.
+ *
+ *          Per-quad data is precomputed once (quadVfrPrecompute): the six
+ *          sub-triangle vertex elevations, each triple sorted, and the two
+ *          planimetric sub-triangle areas. Everything here is device-callable
+ *          scalar arithmetic like the rest of the 2D kernels.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_QUAD_VFR_HPP
+#define OPENSWMM_ENGINE_2D_QUAD_VFR_HPP
+
+#include 
+
+#include "VfrClosure.hpp"
+
+namespace openswmm::twoD {
+
+/// Number of doubles of precomputed elevation data per quad cell: two sorted
+/// sub-triangle triples.
+inline constexpr int kQuadVfrZ = 6;
+
+/// Wetted-area fraction of the quad at stage η (dh̄/dη away from the ε-tail).
+/// @p zs: six sorted elevations (z1,z2,z3 of sub-triangle 1, then of 2).
+OPENSWMM_KERNEL_FN double quadWetFraction(const double* zs, double A1, double A2,
+                                          double eta) noexcept {
+    const double w1 = vfrWetFraction(zs[0], zs[1], zs[2], eta);
+    const double w2 = vfrWetFraction(zs[3], zs[4], zs[5], eta);
+    return (A1 * w1 + A2 * w2) / (A1 + A2);
+}
+
+/// Regularised cell-mean depth h̄(η) of the quad — the area-weighted sum of the
+/// two sub-triangle closures (exact for eps == 0).
+OPENSWMM_KERNEL_FN double quadMeanDepthFromEta(const double* zs, double A1, double A2,
+                                               double eta, double eps) noexcept {
+    const double d1 = vfrMeanDepthFromEta(zs[0], zs[1], zs[2], eta, eps);
+    const double d2 = vfrMeanDepthFromEta(zs[3], zs[4], zs[5], eta, eps);
+    return (A1 * d1 + A2 * d2) / (A1 + A2);
+}
+
+/// Slope dh̄/dη of the REGULARISED sum at η: each sub-triangle contributes its
+/// wet fraction above its switch stage, eps inside its linear tail, and 0
+/// once its tail has reached zero depth. Used by the Newton inverse.
+OPENSWMM_KERNEL_FN double quadMeanDepthSlope(const double* zs, double A1, double A2,
+                                             double eta, double eps) noexcept {
+    double s = 0.0;
+    for (int k = 0; k < 2; ++k) {
+        const double z1 = zs[3 * k], z2 = zs[3 * k + 1], z3 = zs[3 * k + 2];
+        const double A  = (k == 0) ? A1 : A2;
+        const double relief = z3 - z1;
+        double w;
+        if (eps <= 0.0 || relief < kVfrFlatRelief) {
+            w = vfrWetFraction(z1, z2, z3, eta);
+        } else {
+            const double eta_s = vfrStageAtWetFraction(z1, z2, z3, eps);
+            if (eta >= eta_s) {
+                w = vfrWetFraction(z1, z2, z3, eta);
+            } else {
+                const double d = vfrMeanDepthFromEta(z1, z2, z3, eta, eps);
+                w = (d > 0.0) ? eps : 0.0;
+            }
+        }
+        s += A * w;
+    }
+    return s / (A1 + A2);
+}
+
+/// Regularised free-surface elevation η(h̄) of the quad — the solver closure.
+/// Monotone inverse of quadMeanDepthFromEta for the same eps; fully wet
+/// reduces to the flat closure η = z̄_w + h̄ exactly, where z̄_w is the
+/// area-weighted mean of the two sub-triangle mean beds (== the quad's mean
+/// bed over its two-plane model).
+OPENSWMM_KERNEL_FN double quadEtaFromMeanDepth(const double* zs, double A1, double A2,
+                                               double mean_depth, double eps) noexcept {
+    const double A     = A1 + A2;
+    const double zbar1 = (zs[0] + zs[1] + zs[2]) / 3.0;
+    const double zbar2 = (zs[3] + zs[4] + zs[5]) / 3.0;
+    const double zw    = (A1 * zbar1 + A2 * zbar2) / A;
+    const double ztop  = (zs[2] > zs[5]) ? zs[2] : zs[5];
+    const double zlow  = (zs[0] < zs[3]) ? zs[0] : zs[3];
+    const double relief = ztop - zlow;
+
+    // Flat (or degenerate) cell: the flat closure is exact.
+    if (relief < kVfrFlatRelief)
+        return zw + ((mean_depth > 0.0) ? mean_depth : 0.0);
+
+    // Fully wet: both sub-triangles submerged — flat closure exact.
+    if (mean_depth >= ztop - zw) return zw + mean_depth;
+
+    // Dry limit: the stage at which the regularised sum reaches zero — the
+    // lower of the two sub-triangle dry stages (each tail ends at η_s − h_s/ε).
+    const double dry1 = vfrDryEta(zs[0], zs[1], zs[2], eps);
+    const double dry2 = vfrDryEta(zs[3], zs[4], zs[5], eps);
+    const double lo0  = (dry1 < dry2) ? dry1 : dry2;
+    if (!(mean_depth > 0.0)) return lo0;
+
+    // Safeguarded Newton on the monotone sum over [lo0, ztop].
+    double lo = lo0, hi = ztop;
+    double eta = zw + mean_depth;                     // flat-closure guess
+    if (eta <= lo || eta >= hi) eta = 0.5 * (lo + hi);
+    for (int it = 0; it < 80; ++it) {
+        const double f = quadMeanDepthFromEta(zs, A1, A2, eta, eps) - mean_depth;
+        if (f > 0.0) hi = eta; else lo = eta;
+        const double df = quadMeanDepthSlope(zs, A1, A2, eta, eps);
+        double next = (df > 1.0e-12) ? eta - f / df : 0.5 * (lo + hi);
+        if (next <= lo || next >= hi) next = 0.5 * (lo + hi);   // safeguard
+        if (std::abs(next - eta) < 1.0e-13 * (1.0 + relief)) return next;
+        eta = next;
+    }
+    return eta;
+}
+
+/// dη/dh̄ of the regularised quad closure at stage η: 1/max(slope, eps).
+OPENSWMM_KERNEL_FN double quadDEtaDMeanDepth(const double* zs, double A1, double A2,
+                                             double eta, double eps) noexcept {
+    double w = quadMeanDepthSlope(zs, A1, A2, eta, eps);
+    if (w < eps) w = eps;
+    if (w < 1.0e-12) w = 1.0e-12;
+    return 1.0 / w;
+}
+
+/**
+ * @brief Choose the B&S 2007 diagonal for a quad and emit its precomputed
+ *        VFR data.
+ *
+ * @param x,y,z   the four vertices in CYCLIC order (either orientation)
+ * @param zs      out: six elevations — sorted triple of sub-triangle 1, then
+ *                sorted triple of sub-triangle 2
+ * @param A1,A2   out: planimetric areas of the two sub-triangles
+ * @return the case number (1, 2 or 3) — for tests / diagnostics
+ */
+inline int quadVfrPrecompute(const double* x, const double* y, const double* z,
+                             double* zs, double& A1, double& A2) noexcept {
+    // Sort the four cyclic positions by elevation (stable insertion sort so
+    // ties keep cyclic order — any consistent choice is a valid split).
+    int p[4] = {0, 1, 2, 3};
+    for (int i = 1; i < 4; ++i) {
+        const int key = p[i];
+        int j = i - 1;
+        while (j >= 0 && z[p[j]] > z[key]) { p[j + 1] = p[j]; --j; }
+        p[j + 1] = key;
+    }
+    const int n1 = p[0], n2 = p[1], n3 = p[2], n4 = p[3];
+    auto adjacent = [](int a, int b) { const int d = (a - b + 4) % 4; return d == 1 || d == 3; };
+
+    int t1[3], t2[3], kase;
+    if (!adjacent(n1, n4)) {           // Case 1: n1–n4 is a diagonal
+        kase = 1;
+        t1[0] = n1; t1[1] = n2; t1[2] = n4;
+        t2[0] = n1; t2[1] = n3; t2[2] = n4;
+    } else if (adjacent(n2, n1)) {     // Case 2: diagonal n2–n4
+        kase = 2;
+        t1[0] = n1; t1[1] = n2; t1[2] = n4;
+        t2[0] = n2; t2[1] = n3; t2[2] = n4;
+    } else {                           // Case 3: diagonal n3–n4
+        kase = 3;
+        t1[0] = n1; t1[1] = n3; t1[2] = n4;
+        t2[0] = n2; t2[1] = n3; t2[2] = n4;
+    }
+    auto tri_area = [&](const int* t) {
+        const double dx1 = x[t[1]] - x[t[0]], dy1 = y[t[1]] - y[t[0]];
+        const double dx2 = x[t[2]] - x[t[0]], dy2 = y[t[2]] - y[t[0]];
+        return 0.5 * std::abs(dx1 * dy2 - dx2 * dy1);
+    };
+    A1 = tri_area(t1);
+    A2 = tri_area(t2);
+    zs[0] = z[t1[0]]; zs[1] = z[t1[1]]; zs[2] = z[t1[2]];
+    zs[3] = z[t2[0]]; zs[4] = z[t2[1]]; zs[5] = z[t2[2]];
+    vfrSort3(zs[0], zs[1], zs[2]);
+    vfrSort3(zs[3], zs[4], zs[5]);
+    // Degenerate sub-triangle (collinear): fold everything into the other so
+    // the closure stays well-defined (A1 + A2 > 0 was validated upstream).
+    if (!(A1 > 0.0)) { A1 = 0.0; }
+    if (!(A2 > 0.0)) { A2 = 0.0; }
+    return kase;
+}
+
+} // namespace openswmm::twoD
+
+#endif // OPENSWMM_ENGINE_2D_QUAD_VFR_HPP
diff --git a/src/engine/2d/mesh/RainfallInterpolator.cpp b/src/engine/2d/mesh/RainfallInterpolator.cpp
index 692790d0a..01bb95f26 100644
--- a/src/engine/2d/mesh/RainfallInterpolator.cpp
+++ b/src/engine/2d/mesh/RainfallInterpolator.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RainfallInterpolator.cpp
  * @brief Implementation of natural-neighbour / IDW rainfall interpolation.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RainfallInterpolator.hpp"
@@ -17,6 +33,9 @@
 #include 
 #include 
 #include 
+#include 
+#include 
+#include 
 
 namespace openswmm::twoD {
 namespace {
@@ -36,14 +55,14 @@ inline double dist2(const Pt& p, const Pt& q) {
 /// Circumcenter of triangle (a,b,c). Caller must guard against collinear input
 /// (orient2d ≈ 0), where the denominator d vanishes.
 inline Pt circumcenter(const Pt& a, const Pt& b, const Pt& c) {
-    const double d  = 2.0 * (a.x * (b.y - c.y) + b.x * (c.y - a.y) + c.x * (a.y - b.y));
-    const double a2 = a.x * a.x + a.y * a.y;
-    const double b2 = b.x * b.x + b.y * b.y;
-    const double c2 = c.x * c.x + c.y * c.y;
-    Pt o;
-    o.x = (a2 * (b.y - c.y) + b2 * (c.y - a.y) + c2 * (a.y - b.y)) / d;
-    o.y = (a2 * (c.x - b.x) + b2 * (a.x - c.x) + c2 * (b.x - a.x)) / d;
-    return o;
+    // Translate before squaring: large projected coordinates must not
+    // cancel in the circumcenter numerator.
+    const double bx = b.x - a.x, by = b.y - a.y;
+    const double cx = c.x - a.x, cy = c.y - a.y;
+    const double d = 2.0 * (bx * cy - by * cx);
+    const double b2 = bx * bx + by * by, c2 = cx * cx + cy * cy;
+    return {a.x + (b2 * cy - c2 * by) / d,
+            a.y + (bx * c2 - cx * b2) / d};
 }
 
 /// True if p lies strictly inside the circumcircle of CCW triangle (a,b,c).
@@ -140,11 +159,13 @@ Weights idwAll(const Pt& p, const std::vector& site, const std::vector&
     const int m = static_cast(site.size());
     for (int j = 0; j < m; ++j)
         if (dist2(p, site[j]) < 1.0e-18) return {{gid[j], 1.0}};
+    double minD2 = std::numeric_limits::infinity();
+    for (const auto& s : site) minD2 = std::min(minD2, dist2(p, s));
     Weights w;
     w.reserve(m);
     double sum = 0.0;
     for (int j = 0; j < m; ++j) {
-        const double wj = 1.0 / dist2(p, site[j]);   // 1/d² = power-2 IDW
+        const double wj = minD2 / dist2(p, site[j]); // rescaled 1/d²; avoids overflow
         w.push_back({gid[j], wj});
         sum += wj;
     }
@@ -214,7 +235,7 @@ Weights laplaceWeights(const Pt& p, const std::vector& site,
         w.push_back({gid[s], wj});
         sum += wj;
     }
-    if (sum <= 0.0) return {};
+    if (!(sum > 0.0) || !std::isfinite(sum)) return {};
     for (auto& e : w) e.second /= sum;
     return w;
 }
@@ -225,12 +246,19 @@ void RainfallInterpolator::build(const std::vector& cx,
                                  const std::vector& cy,
                                  const std::vector& gage_x,
                                  const std::vector& gage_y,
-                                 int n_gages, double gage_scale) {
+                                 int n_gages, double gage_scale, Method method) {
     ready_ = false;
+    diagnostics_ = {};
+    if (cx.size() != cy.size() || !std::isfinite(gage_scale) || gage_scale <= 0.0)
+        throw std::invalid_argument("2D rainfall: invalid coordinate dimensions or scale");
+    for (std::size_t i = 0; i < cx.size(); ++i)
+        if (!std::isfinite(cx[i]) || !std::isfinite(cy[i]))
+            throw std::invalid_argument("2D rainfall: nonfinite cell centroid " + std::to_string(i));
     nt_ = static_cast(cx.size());
     w_ptr_.assign(static_cast(nt_) + 1, 0);
     w_gage_.clear();
     w_val_.clear();
+    cell_method_.assign(static_cast(nt_), CellMethod::Nearest);
 
     // Collect located gages (skip the un-located (0,0) sentinel and any gage
     // that duplicates an already-collected position — a duplicate would make
@@ -243,12 +271,13 @@ void RainfallInterpolator::build(const std::vector& cx,
     for (int g = 0; g < n_gages; ++g) {
         const double gx = (g < gx_n) ? gage_x[g] : 0.0;
         const double gy = (g < gy_n) ? gage_y[g] : 0.0;
-        if (gx == 0.0 && gy == 0.0) continue;   // un-located
+        if (gx == 0.0 && gy == 0.0) { ++diagnostics_.unlocated; continue; }
         const Pt s{gx * gage_scale, gy * gage_scale};
+        if (!std::isfinite(s.x) || !std::isfinite(s.y)) { ++diagnostics_.invalid; continue; }
         bool dup = false;
         for (const auto& e : site)
             if (dist2(e, s) < 1.0e-12) { dup = true; break; }
-        if (dup) continue;
+        if (dup) { ++diagnostics_.duplicates; continue; }
         site.push_back(s);
         gid.push_back(g);
     }
@@ -256,25 +285,48 @@ void RainfallInterpolator::build(const std::vector& cx,
     const int m = static_cast(site.size());
     if (m == 0 || nt_ == 0) return;   // ready_ stays false → caller uses SYSTEM mean
 
-    // Per-cell weight lists, then flatten to CSR.
-    std::vector rows(static_cast(nt_));
+    // Work in one dimensionless local frame for both sites and cells.
+    // Rainfall weights should be independent of CRS origin and length scale.
+    const Pt origin = site.front();
+    double scale = 0.0;
+    for (const auto& s : site)
+        scale = std::max(scale, std::max(std::fabs(s.x - origin.x), std::fabs(s.y - origin.y)));
+    if (!(scale > 0.0)) scale = 1.0;
+    for (auto& s : site) { s.x = (s.x - origin.x) / scale; s.y = (s.y - origin.y) / scale; }
 
-    if (m == 1) {
-        for (int i = 0; i < nt_; ++i) rows[i] = {{gid[0], 1.0}};
-    } else if (m == 2) {
-        for (int i = 0; i < nt_; ++i) rows[i] = idwAll(Pt{cx[i], cy[i]}, site, gid);
-    } else {
-        const std::vector tris = delaunay(site);
-        if (tris.empty()) {
-            for (int i = 0; i < nt_; ++i) rows[i] = idwAll(Pt{cx[i], cy[i]}, site, gid);
+    std::vector rows(static_cast(nt_));
+    const auto tris = method == Method::NaturalNeighbour ? delaunay(site) : std::vector{};
+    for (int i = 0; i < nt_; ++i) {
+        const Pt p{(cx[i] - origin.x) / scale, (cy[i] - origin.y) / scale};
+        Weights w;
+        if (m == 1) w = {{gid[0], 1.0}};
+        else if (method == Method::NearestNeighbour) {
+            int nearest = 0;
+            double best = dist2(p, site[0]);
+            for (int g = 1; g < m; ++g) {
+                const double d = dist2(p, site[g]);
+                if (d < best) { best = d; nearest = g; }
+            }
+            w = {{gid[nearest], 1.0}};
         } else {
-            for (int i = 0; i < nt_; ++i) {
-                const Pt p{cx[i], cy[i]};
-                Weights w = laplaceWeights(p, site, gid, tris);
-                if (w.empty()) w = idwAll(p, site, gid);   // outside hull / degenerate
-                rows[i] = std::move(w);
+            cell_method_[static_cast(i)] = CellMethod::NaturalNeighbour;
+            if (!tris.empty()) w = laplaceWeights(p, site, gid, tris);
+            if (w.empty()) {
+                w = idwAll(p, site, gid);
+                ++diagnostics_.idwCells;
+                cell_method_[static_cast(i)] = CellMethod::InverseDistance;
             }
         }
+        double sum = 0.0;
+        for (const auto& e : w) {
+            if (!std::isfinite(e.second) || e.second < 0.0)
+                throw std::runtime_error("2D rainfall: invalid weight at cell " + std::to_string(i));
+            sum += e.second;
+        }
+        if (!(sum > 0.0) || !std::isfinite(sum))
+            throw std::runtime_error("2D rainfall: no valid weights at cell " + std::to_string(i));
+        for (auto& e : w) e.second /= sum;
+        rows[i] = std::move(w);
     }
 
     int total = 0;
@@ -306,4 +358,12 @@ void RainfallInterpolator::apply(const std::vector& rain,
     }
 }
 
+void RainfallInterpolator::cellWeights(int i, std::vector& gages,
+                                       std::vector& weights) const {
+    const int beg = w_ptr_[static_cast(i)];
+    const int end = w_ptr_[static_cast(i) + 1];
+    gages.assign(w_gage_.begin() + beg, w_gage_.begin() + end);
+    weights.assign(w_val_.begin() + beg, w_val_.begin() + end);
+}
+
 } // namespace openswmm::twoD
diff --git a/src/engine/2d/mesh/RainfallInterpolator.hpp b/src/engine/2d/mesh/RainfallInterpolator.hpp
index c97e1dfea..4b0dec658 100644
--- a/src/engine/2d/mesh/RainfallInterpolator.hpp
+++ b/src/engine/2d/mesh/RainfallInterpolator.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RainfallInterpolator.hpp
  * @brief Static per-cell weights mapping raingage rainfall onto the 2D mesh.
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_RAINFALL_INTERPOLATOR_HPP
@@ -43,6 +59,20 @@ namespace openswmm::twoD {
  */
 class RainfallInterpolator {
 public:
+    enum class Method { NaturalNeighbour, NearestNeighbour };
+    /// How build() weighted one cell (values match swmm_2d_get_rainfall_weights).
+    enum class CellMethod : signed char {
+        NaturalNeighbour = 0,  ///< Laplace weights inside the gage hull.
+        InverseDistance  = 1,  ///< IDW: outside the hull, 2 sites, or degenerate.
+        Nearest          = 2   ///< One gage, weight 1 (nearest mode or 1 site).
+    };
+    struct Diagnostics {
+        int unlocated = 0;
+        int invalid = 0;
+        int duplicates = 0;
+        int idwCells = 0;
+    };
+    const Diagnostics& diagnostics() const noexcept { return diagnostics_; }
     /**
      * @brief Precompute per-cell interpolation weights.
      *
@@ -58,7 +88,8 @@ class RainfallInterpolator {
      */
     void build(const std::vector& cx, const std::vector& cy,
                const std::vector& gage_x, const std::vector& gage_y,
-               int n_gages, double gage_scale);
+               int n_gages, double gage_scale,
+               Method method = Method::NaturalNeighbour);
 
     /// True once build() produced usable weights (≥ 1 located gage).
     bool ready() const noexcept { return ready_; }
@@ -73,7 +104,14 @@ class RainfallInterpolator {
      */
     void apply(const std::vector& rain, std::vector& out) const;
 
+    /// Per-cell diagnostic: the method used and the contributing (global gage
+    /// index, weight) pairs of cell @p i. Requires ready() and 0 ≤ i < cells.
+    CellMethod cellMethod(int i) const { return cell_method_[static_cast(i)]; }
+    void cellWeights(int i, std::vector& gages, std::vector& weights) const;
+
 private:
+    Diagnostics diagnostics_;
+    std::vector cell_method_;
     bool ready_ = false;
     int  nt_    = 0;
 
diff --git a/src/engine/2d/mesh/VertexReconstruction.cpp b/src/engine/2d/mesh/VertexReconstruction.cpp
index 744eaf9ba..1c5e33f3a 100644
--- a/src/engine/2d/mesh/VertexReconstruction.cpp
+++ b/src/engine/2d/mesh/VertexReconstruction.cpp
@@ -9,6 +9,7 @@
 
 #include "VertexReconstruction.hpp"
 #include "VfrClosure.hpp"
+#include "QuadVfr.hpp"
 
 #include 
 #include 
@@ -29,9 +30,9 @@ void buildVertexStencils(MeshData& mesh) {
     // Step 1: For each vertex, collect all triangles that share it
     std::vector> vert_triangles(nv);
     for (int t = 0; t < nt; ++t) {
-        vert_triangles[mesh.tri_v0[t]].push_back(t);
-        vert_triangles[mesh.tri_v1[t]].push_back(t);
-        vert_triangles[mesh.tri_v2[t]].push_back(t);
+        const int nvc = mesh.cell_vertex_count(t);
+        for (int k = 0; k < nvc; ++k)
+            vert_triangles[mesh.cell_vertex(t, k)].push_back(t);
     }
 
     // Step 2: Build CSR stencil
@@ -164,6 +165,21 @@ void reconstructVertexHeads(const MeshData& mesh, SurfaceStateData& state,
 }
 
 
+double cellFreeSurfaceElevationOf(const MeshData& mesh, int t, double mean_depth) {
+    if (mesh.cell_vertex_count(t) == 4) {
+        // Quad: exact (eps = 0) B&S 2007 two-plane relation over the
+        // precomputed sub-triangle data (mesh/QuadVfr.hpp).
+        const auto u = static_cast(t);
+        const double* zs = &mesh.quad_vfr_z[u * kQuadVfrZ];
+        if (!(mean_depth > 0.0)) return (zs[0] < zs[3]) ? zs[0] : zs[3];
+        return quadEtaFromMeanDepth(zs, mesh.quad_vfr_a[u * 2],
+                                    mesh.quad_vfr_a[u * 2 + 1], mean_depth, 0.0);
+    }
+    return cellFreeSurfaceElevation(mean_depth, mesh.vz[mesh.cell_vertex(t, 0)],
+                                    mesh.vz[mesh.cell_vertex(t, 1)],
+                                    mesh.vz[mesh.cell_vertex(t, 2)]);
+}
+
 double cellFreeSurfaceElevation(double mean_depth, double za, double zb,
                                 double zc) {
     // Delegates to the shared VFR closure (VfrClosure.hpp) with eps = 0 — the
@@ -179,8 +195,27 @@ double cellFreeSurfaceElevation(double mean_depth, double za, double zb,
 
 void reconstructVertexRenderDepths(const MeshData& mesh, SurfaceStateData& state,
                                    double dry_depth,
-                                   [[maybe_unused]] int nthreads) {
+                                   [[maybe_unused]] int nthreads,
+                                   std::vector& eta_scratch) {
     const int nv = mesh.n_vertices();
+    const int nt = mesh.n_triangles();
+
+    // Each cell's free surface is a property of the CELL, not of the (vertex,
+    // cell) incidence: the per-incidence form re-ran the exact planar-bed
+    // closure (sort3 + cube root / Newton) about once per incident vertex,
+    // i.e. ~3x per cell per pass, and it was the single largest consumer in
+    // the profile. Evaluate it once per wet cell here, then gather. Dry cells
+    // are left untouched (the gather re-tests the same predicate) so the
+    // closure is never evaluated where the old code would not have evaluated
+    // it either.
+    eta_scratch.resize(static_cast(nt));
+#pragma omp parallel for schedule(static) num_threads(nthreads)
+    for (int t = 0; t < nt; ++t) {
+        const double h = state.depth[t];
+        if (!(h >= dry_depth)) continue;
+        eta_scratch[static_cast(t)] =
+            cellFreeSurfaceElevationOf(mesh, t, h);
+    }
 
     // Per-vertex CSR gather over the stencil's cell LIST (topology only — the
     // pseudo-Laplacian weights are a solver concern). Each iteration writes
@@ -196,9 +231,7 @@ void reconstructVertexRenderDepths(const MeshData& mesh, SurfaceStateData& state
             const int    t = mesh.vert_stencil_idx[k];
             const double h = state.depth[t];
             if (!(h >= dry_depth)) continue;        // dry skip (NaN-robust)
-            const double eta = cellFreeSurfaceElevation(
-                h, mesh.vz[mesh.tri_v0[t]], mesh.vz[mesh.tri_v1[t]],
-                mesh.vz[mesh.tri_v2[t]]);
+            const double eta = eta_scratch[static_cast(t)];
             if (!std::isfinite(eta)) continue;      // nodata z must not spread
             // Wetted-contact gate: a cell votes at this vertex only if its
             // water surface actually reaches the vertex's corner (η above the
diff --git a/src/engine/2d/mesh/VertexReconstruction.hpp b/src/engine/2d/mesh/VertexReconstruction.hpp
index 58192587c..03fd4db7a 100644
--- a/src/engine/2d/mesh/VertexReconstruction.hpp
+++ b/src/engine/2d/mesh/VertexReconstruction.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file VertexReconstruction.hpp
  * @brief Pseudo-Laplacian vertex reconstruction stencil computation.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_VERTEX_RECONSTRUCTION_HPP
@@ -91,6 +107,10 @@ inline double vertexHeadAt(const MeshData& mesh, const SurfaceStateData& state,
 double cellFreeSurfaceElevation(double mean_depth, double za, double zb,
                                 double zc);
 
+/// Cell-shape-aware form: triangle → cellFreeSurfaceElevation over the three
+/// vertex beds; quad → the B&S 2007 two-plane closure (mesh/QuadVfr.hpp).
+double cellFreeSurfaceElevationOf(const MeshData& mesh, int t, double mean_depth);
+
 /**
  * @brief Wet-masked, depth-weighted free-surface reconstruction at vertices
  *        for RENDERING/OUTPUT only (writes state.vert_depth_signed).
@@ -118,9 +138,27 @@ double cellFreeSurfaceElevation(double mean_depth, double za, double zb,
  * @param state     Surface state (reads depth[], writes vert_depth_signed[]).
  * @param dry_depth Wet/dry threshold (m) — cells below it are excluded.
  * @param nthreads  OpenMP thread count for the per-vertex loop (1 = serial).
+ * @param eta_scratch Caller-owned scratch resized to n_triangles(); the
+ *                  per-cell free-surface elevations are evaluated ONCE here
+ *                  and gathered per vertex. Passing a persistent buffer keeps
+ *                  the closure evaluations at O(nt) instead of O(nt x
+ *                  incidence) and avoids a per-call allocation. Bit-identical
+ *                  to the per-incidence evaluation it replaces (same value,
+ *                  same gather order).
  */
 void reconstructVertexRenderDepths(const MeshData& mesh, SurfaceStateData& state,
-                                   double dry_depth, int nthreads = 1);
+                                   double dry_depth, int nthreads,
+                                   std::vector& eta_scratch);
+
+/// Convenience overload for callers with no persistent scratch (tests, one-shot
+/// seeding): allocates the per-cell buffer for the duration of the call.
+inline void reconstructVertexRenderDepths(const MeshData& mesh,
+                                          SurfaceStateData& state,
+                                          double dry_depth, int nthreads = 1) {
+    std::vector eta_scratch;
+    reconstructVertexRenderDepths(mesh, state, dry_depth, nthreads,
+                                  eta_scratch);
+}
 
 } // namespace openswmm::twoD
 
diff --git a/src/engine/2d/mesh/VfrClosure.hpp b/src/engine/2d/mesh/VfrClosure.hpp
index 70eec07e7..00f2a587d 100644
--- a/src/engine/2d/mesh/VfrClosure.hpp
+++ b/src/engine/2d/mesh/VfrClosure.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file VfrClosure.hpp
  * @brief Volume–free-surface (VFR) closure for a planar-bed triangular cell.
@@ -36,7 +52,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_VFR_CLOSURE_HPP
diff --git a/src/engine/2d/output/Default2DOutputPlugin.cpp b/src/engine/2d/output/Default2DOutputPlugin.cpp
index 46466ebb1..300345c2d 100644
--- a/src/engine/2d/output/Default2DOutputPlugin.cpp
+++ b/src/engine/2d/output/Default2DOutputPlugin.cpp
@@ -9,9 +9,15 @@
 #ifdef OPENSWMM_HAS_2D
 
 #include "Default2DOutputPlugin.hpp"
+#include "../subsurface/SubsurfaceData.hpp"   // G-O: the aquifer ledger at finalize
 #include "../../core/SimulationContext.hpp"
 #include "../../2d/SurfaceRouter2D.hpp"
+#include "../data/SolverOptions2D.hpp"
+#include "../data/Report2DVars.hpp"
 
+#include 
+#include 
+#include 
 #include 
 #include 
 
@@ -23,8 +29,13 @@ namespace openswmm::twoD {
 
 void Default2DOutputPlugin::writeStringAttr(hid_t loc, const char* name,
                                              const char* value) {
+    // H5Tset_size rejects 0, and nothing here checks return codes — an empty
+    // value would silently write no attribute at all. Store a single NUL
+    // instead, which reads back as the empty string.
+    const size_t len = (value && *value) ? std::strlen(value) : 1;
+
     hid_t atype = H5Tcopy(H5T_C_S1);
-    H5Tset_size(atype, std::strlen(value));
+    H5Tset_size(atype, len);
     H5Tset_strpad(atype, H5T_STR_NULLTERM);
 
     hid_t aspace = H5Screate(H5S_SCALAR);
@@ -37,19 +48,28 @@ void Default2DOutputPlugin::writeStringAttr(hid_t loc, const char* name,
 
 hid_t Default2DOutputPlugin::createUnlimitedDataset(const char* name, int rank,
                                                       const hsize_t* dims,
-                                                      const hsize_t* chunk_dims) {
+                                                      const hsize_t* chunk_dims,
+                                                      hid_t type) {
     // Create dataspace with unlimited first dimension
     std::vector maxdims(dims, dims + rank);
     maxdims[0] = H5S_UNLIMITED;
     hid_t space = H5Screate_simple(rank, dims, maxdims.data());
 
-    // Enable chunking (required for unlimited dimensions)
+    // Enable chunking (required for unlimited dimensions). The byte-shuffle
+    // filter precedes deflate: on smooth float fields it typically improves
+    // the zlib ratio 20-40% at negligible CPU. Level 0 = no filters.
     hid_t plist = H5Pcreate(H5P_DATASET_CREATE);
     H5Pset_chunk(plist, rank, chunk_dims);
-    H5Pset_deflate(plist, 4);  // zlib compression level 4
+    if (compression_ > 0) {
+        H5Pset_shuffle(plist);
+        H5Pset_deflate(plist, static_cast(compression_));
+    }
 
-    hid_t ds = H5Dcreate2(file_id_, name, H5T_NATIVE_DOUBLE, space,
-                           H5P_DEFAULT, plist, H5P_DEFAULT);
+    // Storage type follows OUTPUT_PRECISION unless the caller forces one; the
+    // memory type on every write stays H5T_NATIVE_DOUBLE and HDF5 converts, so
+    // no buffer copies.
+    hid_t ds = H5Dcreate2(file_id_, name, type >= 0 ? type : storage_type_,
+                           space, H5P_DEFAULT, plist, H5P_DEFAULT);
     H5Pclose(plist);
     H5Sclose(space);
     return ds;
@@ -106,7 +126,7 @@ hid_t Default2DOutputPlugin::createFaceEnvelopeDataset(const char* name,
     // Fixed [nFace] dataset — no time dimension, no chunking. Overwritten in
     // place each update(); since envelopes are monotone the last write is final.
     hid_t space = H5Screate_simple(1, &n_faces_, nullptr);
-    hid_t ds = H5Dcreate2(file_id_, name, H5T_NATIVE_DOUBLE, space,
+    hid_t ds = H5Dcreate2(file_id_, name, storage_type_, space,
                            H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
     writeStringAttr(ds, "long_name", long_name);
     writeStringAttr(ds, "units", units);
@@ -191,19 +211,101 @@ int Default2DOutputPlugin::prepare(const SimulationContext& ctx) {
     writeStringAttr(file_id_, "institution", "OpenSWMM / HydroCouple");
     writeStringAttr(file_id_, "source", "OpenSWMM Engine 6.0");
 
+    // Model CRS for the `/crs` variable written in prepareMeshAndDatasets().
+    // ctx.spatial.crs and ctx.options.crs are both set by OptionsHandler from
+    // `[OPTIONS] CRS`; prefer the spatial frame, which is what the spatial API
+    // mutates at runtime. Empty is legitimate — models need not declare a CRS.
+    model_crs_ = !ctx.spatial.crs.empty() ? ctx.spatial.crs : ctx.options.crs;
+
     state_ = PluginState::PREPARED;
     return 0;
 }
 
+void Default2DOutputPlugin::setMeshCoordinateScale(double metres_per_model_unit) {
+    if (metres_per_model_unit > 0.0)
+        metres_per_model_unit_ = metres_per_model_unit;
+}
+
+std::string Default2DOutputPlugin::configureOutput(const SolverOptions2D& opts,
+                                                   double report_step_sec) {
+    storage_type_ = (opts.output_precision == OutputPrecision2D::FLOAT64)
+                        ? H5T_NATIVE_DOUBLE : H5T_IEEE_F32LE;
+    compression_  = std::max(0, std::min(9, opts.output_compression));
+    report_vars_  = (opts.report_2d_vars & report2d::ALL_MASK) | report2d::DEPTH;
+    species_filter_ = opts.report_2d_species;
+    species_rows_.clear();
+
+    report_2d_step_days_ = 0.0;
+    next_due_days_       = -1.0;
+    if (opts.report_2d_step > 0.0) {
+        if (report_step_sec > 0.0) {
+            const double ratio = opts.report_2d_step / report_step_sec;
+            const double rounded = std::round(ratio);
+            if (rounded < 1.0 || std::fabs(ratio - rounded) > 1e-6) {
+                char buf[192];
+                std::snprintf(buf, sizeof buf,
+                    "[2D_OPTIONS] REPORT_2D_STEP (%.0f s) must be a positive "
+                    "multiple of REPORT_STEP (%.0f s).",
+                    opts.report_2d_step, report_step_sec);
+                return buf;
+            }
+        }
+        report_2d_step_days_ = opts.report_2d_step / 86400.0;
+    }
+    return {};
+}
+
+void Default2DOutputPlugin::writeCrsVariable() {
+    if (file_id_ == H5I_INVALID_HID) return;
+
+    hid_t space = H5Screate(H5S_SCALAR);
+    hid_t ds = H5Dcreate2(file_id_, "crs", H5T_NATIVE_INT, space,
+                           H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+    if (ds < 0) {
+        H5Sclose(space);
+        return;
+    }
+
+    writeStringAttr(ds, "long_name",
+                    "coordinate reference of the MODEL, plus the factor "
+                    "relating it to the metric Mesh2 coordinates stored here");
+    // Unit of the coordinates AS STORED here. The 2D solver runs in SI, so
+    // node/face x/y are metres whatever the model's own unit is.
+    writeStringAttr(ds, "units", "m");
+    // stored = model x factor; model = stored / factor.
+    writeDoubleAttr(ds, "metres_per_model_unit", metres_per_model_unit_);
+    writeStringAttr(ds, "comment",
+                    "Mesh2 x/y are stored in SI metres. Divide by "
+                    "metres_per_model_unit to obtain coordinates in the linear "
+                    "unit of model_crs; only then reproject from model_crs.");
+
+    if (!model_crs_.empty()) {
+        // CRS of the MODEL coordinates, not of the metric values stored here.
+        // Named model_crs rather than spatial_ref/crs_wkt on purpose: a
+        // generic reader honouring those would place metres in a foot-based
+        // CRS and reproduce the offset this variable exists to describe (#155).
+        writeStringAttr(ds, "model_crs", model_crs_.c_str());
+    }
+
+    int dummy = 0;
+    H5Dwrite(ds, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, &dummy);
+    H5Dclose(ds);
+    H5Sclose(space);
+}
+
 // ============================================================================
 // prepareMesh() — called by SWMMEngine after 2D initialization
 // ============================================================================
 
 void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
-                      hsize_t& n_faces, hsize_t& n_nodes,
+                      hsize_t& n_faces, hsize_t& n_nodes, hsize_t& edge_stride,
                       auto& writeStringAttrFn) {
     n_faces = static_cast(mesh.n_triangles());
     n_nodes = static_cast(mesh.n_vertices());
+    // UGRID mixed topology: [nFace, max_nv] with _FillValue in the padding.
+    // All-triangle meshes keep the historical {n, 3} layout byte-for-byte.
+    edge_stride = static_cast(mesh.edge_stride());
+    const int stride = static_cast(edge_stride);
 
     // --- Mesh2 topology variable (UGRID convention) ---
     {
@@ -216,6 +318,7 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         writeStringAttrFn(ds, "node_coordinates", "Mesh2_node_x Mesh2_node_y");
         writeStringAttrFn(ds, "face_node_connectivity", "Mesh2_face_nodes");
         writeStringAttrFn(ds, "face_coordinates", "Mesh2_face_x Mesh2_face_y");
+        writeStringAttrFn(ds, "openswmm_crs", "crs");
 
         // Write a dummy value
         int dummy = 0;
@@ -235,6 +338,7 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         H5Dwrite(ds_x, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, mesh.vx.data());
         writeStringAttrFn(ds_x, "standard_name", "projection_x_coordinate");
         writeStringAttrFn(ds_x, "units", "m");
+        writeStringAttrFn(ds_x, "openswmm_crs", "crs");
         H5Dclose(ds_x);
 
         // Mesh2_node_y
@@ -243,6 +347,7 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         H5Dwrite(ds_y, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, mesh.vy.data());
         writeStringAttrFn(ds_y, "standard_name", "projection_y_coordinate");
         writeStringAttrFn(ds_y, "units", "m");
+        writeStringAttrFn(ds_y, "openswmm_crs", "crs");
         H5Dclose(ds_y);
 
         // Mesh2_node_z (elevation)
@@ -257,24 +362,60 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         H5Sclose(space);
     }
 
-    // --- Face-node connectivity [nFace, 3] ---
+    // --- Face-node connectivity [nFace, 3 | 4] ---
     {
-        hsize_t dims[2] = { n_faces, 3 };
+        hsize_t dims[2] = { n_faces, edge_stride };
         hid_t space = H5Screate_simple(2, dims, nullptr);
+        const int fill = -1;
+        hid_t dcpl = H5P_DEFAULT;
+        if (stride > 3) {
+            dcpl = H5Pcreate(H5P_DATASET_CREATE);
+            H5Pset_fill_value(dcpl, H5T_NATIVE_INT, &fill);
+        }
         hid_t ds = H5Dcreate2(file_id, "Mesh2_face_nodes", H5T_NATIVE_INT,
-                                space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+                                space, H5P_DEFAULT, dcpl, H5P_DEFAULT);
+        if (dcpl != H5P_DEFAULT) H5Pclose(dcpl);
 
-        // Interleave v0, v1, v2 into [nFace, 3] row-major
-        std::vector conn(n_faces * 3);
+        // Interleave the cell vertices into [nFace, stride] row-major;
+        // padding slots of a triangle row carry −1 (the UGRID fill value).
+        std::vector conn(n_faces * edge_stride);
         for (hsize_t i = 0; i < n_faces; ++i) {
-            conn[i * 3 + 0] = mesh.tri_v0[i];
-            conn[i * 3 + 1] = mesh.tri_v1[i];
-            conn[i * 3 + 2] = mesh.tri_v2[i];
+            const int c  = static_cast(i);
+            const int nv = mesh.cell_vertex_count(c);
+            for (int k = 0; k < stride; ++k)
+                conn[i * edge_stride + static_cast(k)] =
+                    (k < nv) ? mesh.cell_vertex(c, k) : -1;
         }
         H5Dwrite(ds, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, conn.data());
 
         writeStringAttrFn(ds, "cf_role", "face_node_connectivity");
         writeStringAttrFn(ds, "start_index", "0");
+        if (stride > 3) {
+            // UGRID: the fill value is what marks a mixed-shape row's padding.
+            hid_t aspace = H5Screate(H5S_SCALAR);
+            hid_t attr   = H5Acreate2(ds, "_FillValue", H5T_NATIVE_INT, aspace,
+                                      H5P_DEFAULT, H5P_DEFAULT);
+            H5Awrite(attr, H5T_NATIVE_INT, &fill);
+            H5Aclose(attr);
+            H5Sclose(aspace);
+        }
+        H5Dclose(ds);
+        H5Sclose(space);
+    }
+
+    // --- Vertices per face [nFace] — only for mixed meshes (int8) ---
+    if (stride > 3) {
+        hsize_t dim = n_faces;
+        hid_t space = H5Screate_simple(1, &dim, nullptr);
+        hid_t ds = H5Dcreate2(file_id, "Mesh2_face_nv", H5T_NATIVE_INT8,
+                                space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+        std::vector nv(n_faces);
+        for (hsize_t i = 0; i < n_faces; ++i)
+            nv[i] = static_cast(mesh.cell_vertex_count(static_cast(i)));
+        H5Dwrite(ds, H5T_NATIVE_INT8, H5S_ALL, H5S_ALL, H5P_DEFAULT, nv.data());
+        writeStringAttrFn(ds, "long_name", "vertices per face (3 = triangle, 4 = quadrilateral)");
+        writeStringAttrFn(ds, "mesh", "Mesh2");
+        writeStringAttrFn(ds, "location", "face");
         H5Dclose(ds);
         H5Sclose(space);
     }
@@ -288,12 +429,14 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
                                    space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
         H5Dwrite(ds_cx, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, mesh.tri_cx.data());
         writeStringAttrFn(ds_cx, "units", "m");
+        writeStringAttrFn(ds_cx, "openswmm_crs", "crs");
         H5Dclose(ds_cx);
 
         hid_t ds_cy = H5Dcreate2(file_id, "Mesh2_face_y", H5T_NATIVE_DOUBLE,
                                    space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
         H5Dwrite(ds_cy, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, mesh.tri_cy.data());
         writeStringAttrFn(ds_cy, "units", "m");
+        writeStringAttrFn(ds_cy, "openswmm_crs", "crs");
         H5Dclose(ds_cy);
 
         hid_t ds_cz = H5Dcreate2(file_id, "Mesh2_face_z", H5T_NATIVE_DOUBLE,
@@ -330,13 +473,27 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
     // can reconstruct cell-centred velocity via RT0 without re-deriving edge
     // length / outward normals from the vertex coordinates.
     {
-        hsize_t dims[2] = { n_faces, 3 };
+        hsize_t dims[2] = { n_faces, edge_stride };
         hid_t space = H5Screate_simple(2, dims, nullptr);
 
+        // Pack the internal kMaxCellVerts-stride slots to the public stride.
+        auto packed = [&](const std::vector& src) {
+            std::vector out(n_faces * edge_stride, 0.0);
+            for (hsize_t i = 0; i < n_faces; ++i)
+                for (int k = 0; k < stride; ++k)
+                    out[i * edge_stride + static_cast(k)] =
+                        src[static_cast(
+                            MeshData::slot(static_cast(i), k))];
+            return out;
+        };
+        const std::vector len_p = packed(mesh.edge_length);
+        const std::vector nx_p  = packed(mesh.edge_nx);
+        const std::vector ny_p  = packed(mesh.edge_ny);
+
         hid_t ds_len = H5Dcreate2(file_id, "Mesh2_edge_length", H5T_NATIVE_DOUBLE,
                                     space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
         H5Dwrite(ds_len, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT,
-                 mesh.edge_length.data());
+                 len_p.data());
         writeStringAttrFn(ds_len, "long_name", "edge length");
         writeStringAttrFn(ds_len, "units", "m");
         writeStringAttrFn(ds_len, "mesh", "Mesh2");
@@ -346,7 +503,7 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         hid_t ds_nx = H5Dcreate2(file_id, "Mesh2_edge_nx", H5T_NATIVE_DOUBLE,
                                    space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
         H5Dwrite(ds_nx, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT,
-                 mesh.edge_nx.data());
+                 nx_p.data());
         writeStringAttrFn(ds_nx, "long_name", "edge outward unit normal x component");
         writeStringAttrFn(ds_nx, "units", "1");
         writeStringAttrFn(ds_nx, "mesh", "Mesh2");
@@ -356,7 +513,7 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
         hid_t ds_ny = H5Dcreate2(file_id, "Mesh2_edge_ny", H5T_NATIVE_DOUBLE,
                                    space, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
         H5Dwrite(ds_ny, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT,
-                 mesh.edge_ny.data());
+                 ny_p.data());
         writeStringAttrFn(ds_ny, "long_name", "edge outward unit normal y component");
         writeStringAttrFn(ds_ny, "units", "1");
         writeStringAttrFn(ds_ny, "mesh", "Mesh2");
@@ -368,27 +525,45 @@ void writeMeshToHDF5(hid_t file_id, const MeshData& mesh,
 }
 
 void Default2DOutputPlugin::prepareMeshAndDatasets(const MeshData& mesh) {
+    // Written first so the `openswmm_crs = "crs"` attributes the mesh
+    // variables carry resolve against a variable that already exists.
+    writeCrsVariable();
+
+    // Results-file size controls, recorded so readers and the parity tooling
+    // can tell how the time-varying datasets were stored.
+    writeStringAttr(file_id_, "precision",
+                    storage_type_ == H5T_NATIVE_DOUBLE ? "float64" : "float32");
+    {
+        char cbuf[16];
+        std::snprintf(cbuf, sizeof cbuf, "%d", compression_);
+        writeStringAttr(file_id_, "compression", cbuf);
+        writeStringAttr(file_id_, "report_2d_variables",
+                        report2d::formatMask(report_vars_).c_str());
+    }
+
     auto writeAttr = [this](hid_t loc, const char* name, const char* val) {
         writeStringAttr(loc, name, val);
     };
-    writeMeshToHDF5(file_id_, mesh, n_faces_, n_nodes_, writeAttr);
+    writeMeshToHDF5(file_id_, mesh, n_faces_, n_nodes_, edge_stride_, writeAttr);
 
     // --- Create time-varying datasets with unlimited time dimension ---
     // Chunk size: 1 time step x all faces (or nodes)
     hsize_t face_chunk[2] = { 1, n_faces_ };
     hsize_t node_chunk[2] = { 1, n_nodes_ };
-    hsize_t edge_chunk[3] = { 1, n_faces_, 3 };
+    hsize_t edge_chunk[3] = { 1, n_faces_, edge_stride_ };
     hsize_t time_chunk[1] = { 64 };
 
     hsize_t zero2[2] = { 0, n_faces_ };
     hsize_t zero2n[2] = { 0, n_nodes_ };
-    hsize_t zero3[3] = { 0, n_faces_, 3 };
+    hsize_t zero3[3] = { 0, n_faces_, edge_stride_ };
     hsize_t zero1[1] = { 0 };
 
-    // Time coordinate
-    ds_time_ = createUnlimitedDataset("time", 1, zero1, time_chunk);
+    // Time coordinate — always float64: OUTPUT_PRECISION thins the state
+    // fields, not the axis every reader keys its lookup on.
+    ds_time_ = createUnlimitedDataset("time", 1, zero1, time_chunk,
+                                      H5T_NATIVE_DOUBLE);
     writeStringAttr(ds_time_, "standard_name", "time");
-    writeStringAttr(ds_time_, "units", "days since simulation start");
+    writeStringAttr(ds_time_, "units", "days since 1899-12-30 00:00:00");
     writeStringAttr(ds_time_, "calendar", "standard");
 
     // Helper lambda for face datasets
@@ -404,68 +579,103 @@ void Default2DOutputPlugin::prepareMeshAndDatasets(const MeshData& mesh) {
         return ds;
     };
 
+    // Every dataset below is created ONLY when its REPORT_2D_VARIABLES group is
+    // selected (default: everything a user renders or plots; solver
+    // diagnostics off). Handles stay H5I_INVALID_HID otherwise and update()
+    // skips them. DEPTH is always on (the time axis every reader keys on).
     ds_face_depth_         = createFaceDS("Mesh2_face_depth",
                                            "overland flow depth", "m", "water_surface_height_above_reference_datum");
     ds_face_head_          = createFaceDS("Mesh2_face_head",
                                            "total hydraulic head", "m", "hydraulic_head");
-    ds_face_grad_hx_       = createFaceDS("Mesh2_face_grad_hx",
-                                           "head gradient dh/dx (unlimited)", "1");
-    ds_face_grad_hy_       = createFaceDS("Mesh2_face_grad_hy",
-                                           "head gradient dh/dy (unlimited)", "1");
-    ds_face_grad_hx_lim_   = createFaceDS("Mesh2_face_grad_hx_lim",
-                                           "head gradient dh/dx (slope limited)", "1");
-    ds_face_grad_hy_lim_   = createFaceDS("Mesh2_face_grad_hy_lim",
-                                           "head gradient dh/dy (slope limited)", "1");
-    ds_face_rainfall_      = createFaceDS("Mesh2_face_rainfall",
-                                           "rainfall intensity", "m s-1", "rainfall_rate");
-    ds_face_coupling_flux_ = createFaceDS("Mesh2_face_coupling_flux",
-                                           "coupling flux with SWMM node", "m s-1");
-    ds_face_net_source_    = createFaceDS("Mesh2_face_net_source",
-                                           "net volumetric source/sink", "m s-1");
-    ds_face_vx_            = createFaceDS("Mesh2_face_vx",
-                                          "cell-centred velocity X (RT0)", "m s-1");
-    ds_face_vy_            = createFaceDS("Mesh2_face_vy",
-                                          "cell-centred velocity Y (RT0)", "m s-1");
-    ds_face_continuity_err_ = createFaceDS("Mesh2_face_continuity_err",
-                                            "per-cell continuity residual", "m3 s-1");
-
-    // Edge flux [nTime, nFace, 3]
-    ds_edge_flux_ = createUnlimitedDataset("Mesh2_edge_flux", 3, zero3, edge_chunk);
-    writeStringAttr(ds_edge_flux_, "long_name", "normal flux through cell edges");
-    // Volumetric edge flux F_e = -q·n_e·L_e (see SurfaceFluxCalculator
-    // computeEdgeFluxes, which derives the m3/s dimensioning). Matches the
-    // m3 s-1 units of the continuity-residual datasets that sum these fluxes.
-    writeStringAttr(ds_edge_flux_, "units", "m3 s-1");
-    writeStringAttr(ds_edge_flux_, "mesh", "Mesh2");
-    writeStringAttr(ds_edge_flux_, "location", "edge");
-
-    // Node head [nTime, nNode]
-    ds_node_head_ = createUnlimitedDataset("Mesh2_node_head", 2, zero2n, node_chunk);
-    writeStringAttr(ds_node_head_, "long_name", "reconstructed vertex head");
-    writeStringAttr(ds_node_head_, "units", "m");
-    writeStringAttr(ds_node_head_, "mesh", "Mesh2");
-    writeStringAttr(ds_node_head_, "location", "node");
-
-    // Node SIGNED depth [nTime, nNode] — wet-masked render reconstruction
-    // (eta_v - z_v; wetted-contact gated, so current engines emit > 0 or the
-    // 0 no-data sentinel; files from older engines may carry negatives). This
-    // is the field renderers/profilers should interpolate; Mesh2_node_head is
-    // the solver field (dry-cell head = bed elevation) kept for back-compat.
-    ds_node_depth_ = createUnlimitedDataset("Mesh2_node_depth", 2, zero2n, node_chunk);
-    writeStringAttr(ds_node_depth_, "long_name",
-                    "signed vertex water depth (wet-masked render reconstruction)");
-    writeStringAttr(ds_node_depth_, "units", "m");
-    writeStringAttr(ds_node_depth_, "mesh", "Mesh2");
-    writeStringAttr(ds_node_depth_, "location", "node");
+    if (want(report2d::GRADIENTS)) {
+        ds_face_grad_hx_       = createFaceDS("Mesh2_face_grad_hx",
+                                               "head gradient dh/dx (unlimited)", "1");
+        ds_face_grad_hy_       = createFaceDS("Mesh2_face_grad_hy",
+                                               "head gradient dh/dy (unlimited)", "1");
+        ds_face_grad_hx_lim_   = createFaceDS("Mesh2_face_grad_hx_lim",
+                                               "head gradient dh/dx (slope limited)", "1");
+        ds_face_grad_hy_lim_   = createFaceDS("Mesh2_face_grad_hy_lim",
+                                               "head gradient dh/dy (slope limited)", "1");
+    }
+    if (want(report2d::RAINFALL)) {
+        ds_face_rainfall_      = createFaceDS("Mesh2_face_rainfall",
+                                               "rainfall intensity", "m s-1", "rainfall_rate");
+        // Cumulative rainfall VOLUME per cell (m³) at this report time.
+        // The final mass_balance_2d/rainfall_in can include a trailing
+        // interval after the last scheduled report.
+        ds_face_rain_cum_      = createFaceDS("Mesh2_face_rain_cum",
+                                               "cumulative rainfall volume", "m3");
+    }
+    if (want(report2d::COUPLING)) {
+        ds_face_coupling_flux_ = createFaceDS("Mesh2_face_coupling_flux",
+                                               "coupling flux with SWMM node", "m s-1");
+        ds_face_net_source_    = createFaceDS("Mesh2_face_net_source",
+                                               "net volumetric source/sink", "m s-1");
+    }
+    if (want(report2d::INFILTRATION)) {
+        // Per-cell infiltration (plan §5.5.6): the held INFIL_STEP rate and
+        // the cumulative infiltrated depth (all-zero when no
+        // [2D_INFILTRATION*] rows resolved).
+        ds_face_infil_rate_    = createFaceDS("Mesh2_face_infil_rate",
+                                               "infiltration loss rate", "m s-1");
+        ds_face_infil_cum_     = createFaceDS("Mesh2_face_infil_cum",
+                                               "cumulative infiltrated depth", "m");
+    }
+    if (want(report2d::VELOCITY)) {
+        ds_face_vx_            = createFaceDS("Mesh2_face_vx",
+                                              "cell-centred velocity X (RT0)", "m s-1");
+        ds_face_vy_            = createFaceDS("Mesh2_face_vy",
+                                              "cell-centred velocity Y (RT0)", "m s-1");
+    }
+    if (want(report2d::CONTINUITY))
+        ds_face_continuity_err_ = createFaceDS("Mesh2_face_continuity_err",
+                                                "per-cell continuity residual", "m3 s-1");
+
+    if (want(report2d::EDGE_FLUX)) {
+        // Edge flux [nTime, nFace, stride]
+        ds_edge_flux_ = createUnlimitedDataset("Mesh2_edge_flux", 3, zero3, edge_chunk);
+        writeStringAttr(ds_edge_flux_, "long_name", "normal flux through cell edges");
+        // Volumetric edge flux F_e = -q·n_e·L_e (see SurfaceFluxCalculator
+        // computeEdgeFluxes, which derives the m3/s dimensioning). Matches the
+        // m3 s-1 units of the continuity-residual datasets that sum these fluxes.
+        writeStringAttr(ds_edge_flux_, "units", "m3 s-1");
+        writeStringAttr(ds_edge_flux_, "mesh", "Mesh2");
+        writeStringAttr(ds_edge_flux_, "location", "edge");
+    }
+
+    if (want(report2d::NODE_HEAD)) {
+        // Node head [nTime, nNode]
+        ds_node_head_ = createUnlimitedDataset("Mesh2_node_head", 2, zero2n, node_chunk);
+        writeStringAttr(ds_node_head_, "long_name", "reconstructed vertex head");
+        writeStringAttr(ds_node_head_, "units", "m");
+        writeStringAttr(ds_node_head_, "mesh", "Mesh2");
+        writeStringAttr(ds_node_head_, "location", "node");
+
+        // Node SIGNED depth [nTime, nNode] — wet-masked render reconstruction
+        // (eta_v - z_v; wetted-contact gated, so current engines emit > 0 or
+        // the 0 no-data sentinel; files from older engines may carry
+        // negatives). This is the field renderers/profilers should
+        // interpolate; Mesh2_node_head is the solver field (dry-cell head =
+        // bed elevation) kept for back-compat.
+        ds_node_depth_ = createUnlimitedDataset("Mesh2_node_depth", 2, zero2n, node_chunk);
+        writeStringAttr(ds_node_depth_, "long_name",
+                        "signed vertex water depth (wet-masked render reconstruction)");
+        writeStringAttr(ds_node_depth_, "units", "m");
+        writeStringAttr(ds_node_depth_, "mesh", "Mesh2");
+        writeStringAttr(ds_node_depth_, "location", "node");
+    }
 
     // --- Cumulative rendering envelopes (fixed [nFace], overwritten in place) ---
-    ds_face_max_depth_ = createFaceEnvelopeDataset(
-        "Mesh2_face_max_depth", "maximum overland flow depth", "m");
-    ds_face_max_velocity_ = createFaceEnvelopeDataset(
-        "Mesh2_face_max_velocity", "maximum cell velocity magnitude", "m s-1");
-    ds_face_max_continuity_err_ = createFaceEnvelopeDataset(
-        "Mesh2_face_max_continuity_err",
-        "maximum absolute per-cell continuity residual", "m3 s-1");
+    if (want(report2d::ENVELOPES)) {
+        ds_face_max_depth_ = createFaceEnvelopeDataset(
+            "Mesh2_face_max_depth", "maximum overland flow depth", "m");
+        ds_face_max_velocity_ = createFaceEnvelopeDataset(
+            "Mesh2_face_max_velocity", "maximum cell velocity magnitude", "m s-1");
+        if (want(report2d::CONTINUITY))
+            ds_face_max_continuity_err_ = createFaceEnvelopeDataset(
+                "Mesh2_face_max_continuity_err",
+                "maximum absolute per-cell continuity residual", "m3 s-1");
+    }
 }
 
 // ============================================================================
@@ -475,6 +685,16 @@ void Default2DOutputPlugin::prepareMeshAndDatasets(const MeshData& mesh) {
 int Default2DOutputPlugin::update(const SimulationSnapshot& snap) {
     if (file_id_ < 0 || snap.surface_tri_count == 0) return 0;
 
+    // REPORT_2D_STEP cadence: update() arrives every [OPTIONS] REPORT_STEP;
+    // write only when the 2D instant is due (first call always writes).
+    if (report_2d_step_days_ > 0.0) {
+        if (next_due_days_ < 0.0) next_due_days_ = snap.sim_time;
+        if (snap.sim_time + 1e-9 < next_due_days_) return 0;
+        // Advance in whole 2D steps so a late call cannot double-write.
+        while (next_due_days_ <= snap.sim_time + 1e-9)
+            next_due_days_ += report_2d_step_days_;
+    }
+
     // Write time value
     {
         hsize_t new_dim = n_steps_ + 1;
@@ -488,26 +708,205 @@ int Default2DOutputPlugin::update(const SimulationSnapshot& snap) {
         H5Sclose(fspace);
     }
 
-    // Write per-face fields
-    extendAndWrite2D(ds_face_depth_,         snap.surface_depth.data(),          n_faces_);
-    extendAndWrite2D(ds_face_head_,          snap.surface_head.data(),           n_faces_);
-    extendAndWrite2D(ds_face_grad_hx_,       snap.surface_grad_hx.data(),       n_faces_);
-    extendAndWrite2D(ds_face_grad_hy_,       snap.surface_grad_hy.data(),       n_faces_);
-    extendAndWrite2D(ds_face_grad_hx_lim_,   snap.surface_grad_hx_lim.data(),   n_faces_);
-    extendAndWrite2D(ds_face_grad_hy_lim_,   snap.surface_grad_hy_lim.data(),   n_faces_);
-    extendAndWrite2D(ds_face_rainfall_,      snap.surface_rainfall.data(),      n_faces_);
-    extendAndWrite2D(ds_face_coupling_flux_, snap.surface_coupling_flux.data(), n_faces_);
-    extendAndWrite2D(ds_face_net_source_,    snap.surface_net_source.data(),    n_faces_);
-    extendAndWrite2D(ds_face_vx_,            snap.surface_face_vx.data(),       n_faces_);
-    extendAndWrite2D(ds_face_vy_,            snap.surface_face_vy.data(),       n_faces_);
-    extendAndWrite2D(ds_face_continuity_err_, snap.surface_continuity_err.data(), n_faces_);
-
-    // Write per-edge fields [nFace, 3]
-    extendAndWrite3D(ds_edge_flux_, snap.surface_edge_flux.data(), n_faces_, 3);
-
-    // Write per-node fields
-    extendAndWrite2D(ds_node_head_, snap.surface_vert_head.data(), n_nodes_);
-    if (static_cast(snap.surface_vert_depth.size()) == n_nodes_)
+    // Per-face fields — each guarded by its dataset handle, which is
+    // H5I_INVALID_HID for groups REPORT_2D_VARIABLES left out.
+    auto face = [&](hid_t ds, const std::vector& v) {
+        if (ds != H5I_INVALID_HID && v.size() == static_cast(n_faces_))
+            extendAndWrite2D(ds, v.data(), n_faces_);
+    };
+    face(ds_face_depth_,          snap.surface_depth);
+    face(ds_face_head_,           snap.surface_head);
+    face(ds_face_grad_hx_,        snap.surface_grad_hx);
+    face(ds_face_grad_hy_,        snap.surface_grad_hy);
+    face(ds_face_grad_hx_lim_,    snap.surface_grad_hx_lim);
+    face(ds_face_grad_hy_lim_,    snap.surface_grad_hy_lim);
+    face(ds_face_rainfall_,       snap.surface_rainfall);
+    face(ds_face_coupling_flux_,  snap.surface_coupling_flux);
+    face(ds_face_net_source_,     snap.surface_net_source);
+    face(ds_face_infil_rate_,     snap.surface_infil_rate);
+    face(ds_face_infil_cum_,      snap.surface_infil_cum);
+    face(ds_face_rain_cum_,       snap.surface_rain_cum);
+    face(ds_face_vx_,             snap.surface_face_vx);
+    face(ds_face_vy_,             snap.surface_face_vy);
+    face(ds_face_continuity_err_, snap.surface_continuity_err);
+
+    // Per-edge fields [nFace, edge_stride] (the snapshot is already packed to
+    // the public stride by SWMMEngine::fillSurfaceSnapshot).
+    if (ds_edge_flux_ != H5I_INVALID_HID &&
+        snap.surface_edge_flux.size() == static_cast(n_faces_ * edge_stride_))
+        extendAndWrite3D(ds_edge_flux_, snap.surface_edge_flux.data(), n_faces_,
+                         edge_stride_);
+
+    // Overland transport S1: species concentration [nTime, nSpecies, nFace].
+    // Created LAZILY on the first step that carries species, and only then:
+    // a model with no 2D transport gets no variable, which is the correct
+    // statement. REPORT_2D_SPECIES narrows the rows written; the
+    // species_names attribute always lists exactly the rows in the file.
+    if (want(report2d::SPECIES) && snap.surface_species_count > 0 &&
+        snap.surface_species_conc.size() ==
+            static_cast(snap.surface_species_count) * n_faces_) {
+        if (ds_face_species_conc_ == H5I_INVALID_HID) {
+            // Resolve the row selection once, by name against the surface's
+            // own row names (S4) or the pollutant list (pre-S4 fallback).
+            const std::vector* names_src =
+                snap.surface_species_names ? snap.surface_species_names
+                                           : snap.pollut_names;
+            species_rows_.clear();
+            const int n_in = snap.surface_species_count;
+            if (species_filter_.empty() || !names_src) {
+                for (int i = 0; i < n_in; ++i) species_rows_.push_back(i);
+            } else {
+                for (int i = 0; i < n_in && i < static_cast(names_src->size()); ++i) {
+                    const std::string& nm = (*names_src)[static_cast(i)];
+                    for (const auto& want_nm : species_filter_) {
+                        if (report2d::iequalsTok(want_nm, nm.c_str())) {
+                            species_rows_.push_back(i);
+                            break;
+                        }
+                    }
+                }
+            }
+            if (species_rows_.empty()) {
+                // Nothing selected matches — write nothing rather than an
+                // empty block; the mask says SPECIES, the filter said none.
+                n_species_ = 0;
+            } else {
+                n_species_ = static_cast(species_rows_.size());
+                hsize_t zero3s[3]  = {0, n_species_, n_faces_};
+                hsize_t chunk3[3]  = {1, n_species_, std::min(n_faces_, 4096)};
+                ds_face_species_conc_ = createUnlimitedDataset(
+                    "Mesh2_face_species_conc", 3, zero3s, chunk3);
+                writeStringAttr(ds_face_species_conc_, "long_name",
+                                "surface species concentration");
+                // Species units are per species; the dataset carries the
+                // layout, a name list and (S4b) a parallel unit list so a
+                // reader can join. "1" here means "see species_units".
+                writeStringAttr(ds_face_species_conc_, "units", "1");
+                writeStringAttr(ds_face_species_conc_, "mesh", "Mesh2");
+                writeStringAttr(ds_face_species_conc_, "location", "face");
+                writeStringAttr(ds_face_species_conc_, "layout",
+                                "[time, species, face]; species order = "
+                                "the species_names list (a REPORT_2D_SPECIES "
+                                "subset of pollutants, MSX, __WATER_AGE__, "
+                                "__TEMPERATURE__); dry cell reports 0");
+                if (names_src) {
+                    std::string names;
+                    for (std::size_t k = 0; k < species_rows_.size(); ++k) {
+                        const auto r = static_cast(species_rows_[k]);
+                        if (r >= names_src->size()) break;
+                        if (k) names += ",";
+                        names += (*names_src)[r];
+                    }
+                    if (!names.empty())
+                        writeStringAttr(ds_face_species_conc_, "species_names",
+                                        names.c_str());
+                }
+                // S4b: species_units — one label per selected row, same
+                // order as species_names; __WATER_AGE__ is reported in hours.
+                if (snap.surface_species_units) {
+                    std::string units;
+                    for (std::size_t k = 0; k < species_rows_.size(); ++k) {
+                        const auto r = static_cast(species_rows_[k]);
+                        if (r >= snap.surface_species_units->size()) break;
+                        if (k) units += ",";
+                        units += (*snap.surface_species_units)[r];
+                    }
+                    if (!units.empty())
+                        writeStringAttr(ds_face_species_conc_, "species_units",
+                                        units.c_str());
+                }
+            }
+        }
+        if (ds_face_species_conc_ != H5I_INVALID_HID && n_species_ > 0)
+            writeSpeciesRows(snap.surface_species_conc.data(),
+                             static_cast(snap.surface_species_count));
+    }
+
+    // S7: cell buildup per unit land area, one row per surface species (the
+    // pollutant and MSX rows, unfiltered — the store is what the user
+    // authored, and it is small). Absent when no [2D_COVERAGES] resolved.
+    if (want(report2d::BUILDUP) && snap.surface_buildup_count > 0 &&
+        snap.surface_buildup.size() ==
+            static_cast(snap.surface_buildup_count) * n_faces_) {
+        if (ds_face_buildup_ == H5I_INVALID_HID) {
+            n_buildup_ = static_cast(snap.surface_buildup_count);
+            hsize_t zero3b[3]  = {0, n_buildup_, n_faces_};
+            hsize_t chunk3b[3] = {1, n_buildup_, std::min(n_faces_, 4096)};
+            ds_face_buildup_ = createUnlimitedDataset("Mesh2_face_buildup", 3, zero3b, chunk3b);
+            writeStringAttr(ds_face_buildup_, "long_name",
+                            "surface pollutant buildup per unit land area");
+            // The 1D washoff summary's unit: lbs/acre (US) or kg/ha (SI);
+            // a reactions species declared in UG scales through its own
+            // unit factor — see species_units for the concentration side.
+            writeStringAttr(ds_face_buildup_, "units",
+                            (snap.flow_units_code >= 3) ? "kg ha-1" : "lb acre-1");
+            writeStringAttr(ds_face_buildup_, "mesh", "Mesh2");
+            writeStringAttr(ds_face_buildup_, "location", "face");
+            writeStringAttr(ds_face_buildup_, "layout",
+                            "[time, species, face]; species order = the first "
+                            "rows of species_names (pollutants, then MSX)");
+            if (snap.surface_species_names) {
+                std::string names;
+                for (hsize_t k = 0; k < n_buildup_ &&
+                                    k < snap.surface_species_names->size(); ++k) {
+                    if (k) names += ",";
+                    names += (*snap.surface_species_names)[static_cast(k)];
+                }
+                if (!names.empty())
+                    writeStringAttr(ds_face_buildup_, "species_names", names.c_str());
+            }
+        }
+        if (ds_face_buildup_ != H5I_INVALID_HID &&
+            n_buildup_ == static_cast(snap.surface_buildup_count))
+            extendAndWrite3D(ds_face_buildup_, snap.surface_buildup.data(),
+                             n_buildup_, n_faces_);
+    }
+
+    // G-O: the two-zone aquifer. Lazy like the species block: a model with no
+    // [2D_AQUIFER] gets no groundwater variable at all.
+    if (want(report2d::GROUNDWATER) && snap.gw2d_active &&
+        snap.gw2d_hg.size() == static_cast(n_faces_)) {
+        if (!gw_created_) createGroundwaterDatasets(snap);
+        const std::vector* fields[kGwFaceFields] = {
+            &snap.gw2d_table_elev, &snap.gw2d_hg, &snap.gw2d_hu, &snap.gw2d_recharge,
+            &snap.gw2d_lateral, &snap.gw2d_node_exchange, &snap.gw2d_deep, &snap.gw2d_et,
+            &snap.gw2d_dunne, &snap.gw2d_infil_in, &snap.gw2d_link_seepage};   // G-X3
+        for (int k = 0; k < kGwFaceFields; ++k) face(ds_gw_face_[k], *fields[k]);
+        if (ds_gw_ledger_ != H5I_INVALID_HID && snap.gw2d_ledger.size() == kGwLedgerTerms)
+            extendAndWrite2D(ds_gw_ledger_, snap.gw2d_ledger.data(), kGwLedgerTerms);
+        // T7.5
+        if (n_gw_species_ > 0) {
+            const auto want = static_cast(n_gw_species_) *
+                              static_cast(n_faces_);
+            if (ds_gw_sat_conc_ != H5I_INVALID_HID &&
+                snap.gw2d_sat_conc.size() == want)
+                extendAndWrite3D(ds_gw_sat_conc_, snap.gw2d_sat_conc.data(),
+                                 n_gw_species_, n_faces_);
+            if (ds_gw_unsat_conc_ != H5I_INVALID_HID &&
+                snap.gw2d_unsat_conc.size() == want)
+                extendAndWrite3D(ds_gw_unsat_conc_, snap.gw2d_unsat_conc.data(),
+                                 n_gw_species_, n_faces_);
+            if (ds_gw_species_ledger_ != H5I_INVALID_HID &&
+                snap.gw2d_species_ledger.size() ==
+                    static_cast(n_gw_species_) * kGwSpeciesLedgerTerms)
+                extendAndWrite3D(ds_gw_species_ledger_,
+                                 snap.gw2d_species_ledger.data(),
+                                 n_gw_species_, kGwSpeciesLedgerTerms);
+        }
+        if (ds_gw_bed_exchange_ != H5I_INVALID_HID &&
+            snap.gw2d_bed_exchange_cum.size() == static_cast(n_gw_beds_))
+            extendAndWrite2D(ds_gw_bed_exchange_, snap.gw2d_bed_exchange_cum.data(), n_gw_beds_);
+        if (ds_gw_theta_ != H5I_INVALID_HID &&
+            snap.gw2d_theta_sigma.size() == static_cast(n_gw_layers_ * n_faces_))
+            extendAndWrite3D(ds_gw_theta_, snap.gw2d_theta_sigma.data(), n_gw_layers_, n_faces_);
+    }
+
+    // Per-node fields
+    if (ds_node_head_ != H5I_INVALID_HID &&
+        snap.surface_vert_head.size() == static_cast(n_nodes_))
+        extendAndWrite2D(ds_node_head_, snap.surface_vert_head.data(), n_nodes_);
+    if (ds_node_depth_ != H5I_INVALID_HID &&
+        static_cast(snap.surface_vert_depth.size()) == n_nodes_)
         extendAndWrite2D(ds_node_depth_, snap.surface_vert_depth.data(), n_nodes_);
 
     // Overwrite cumulative envelopes in place (monotone; last write is final).
@@ -523,6 +922,188 @@ int Default2DOutputPlugin::update(const SimulationSnapshot& snap) {
     return 0;
 }
 
+// G-O: the aquifer's datasets, created on the first update() with a live kernel.
+void Default2DOutputPlugin::createGroundwaterDatasets(const SimulationSnapshot& snap) {
+    gw_created_ = true;
+    hsize_t zero2[2]      = {0, n_faces_};
+    hsize_t face_chunk[2] = {1, std::min(n_faces_, 4096)};
+    struct F { const char* name; const char* long_name; const char* units; };
+    // Same order as the `fields[]` table in update().
+    static const F kFields[kGwFaceFields] = {
+        {"Mesh2_face_gw_table_elev",    "water-table elevation (aquifer bottom + saturated thickness)", "m"},
+        {"Mesh2_face_gw_hg",            "saturated thickness", "m"},
+        {"Mesh2_face_gw_hu",            "closure A unsaturated storage (equivalent depth of water; 0 under closure B)", "m"},
+        {"Mesh2_face_gw_recharge",      "recharge from the unsaturated to the saturated zone, positive down, negative = capillary rise (last firing, held)", "m s-1"},
+        {"Mesh2_face_gw_lateral",       "net lateral Darcy flow into the cell (last firing, held)", "m3 s-1"},
+        {"Mesh2_face_gw_node_exchange", "exchange with the 1D node bed, positive out of the aquifer into the pipe (last firing, held)", "m3 s-1"},
+        {"Mesh2_face_gw_deep",          "deep percolation loss (last firing, held)", "m s-1"},
+        {"Mesh2_face_gw_et",            "subsurface evapotranspiration (last firing, held)", "m s-1"},
+        {"Mesh2_face_gw_dunne",         "saturation excess returned to the surface (last firing, held)", "m3 s-1"},
+        {"Mesh2_face_gw_infil_in",      "infiltration delivered from the surface (last firing, held)", "m s-1"},
+        {"Mesh2_face_gw_link_seepage",  "conduit seepage delivered into the cell, length-weighted over the conduits crossing it (last firing, held)", "m3 s-1"},   // G-X3
+    };
+    for (int k = 0; k < kGwFaceFields; ++k) {
+        hid_t ds = createUnlimitedDataset(kFields[k].name, 2, zero2, face_chunk);
+        writeStringAttr(ds, "long_name", kFields[k].long_name);
+        writeStringAttr(ds, "units", kFields[k].units);
+        writeStringAttr(ds, "mesh", "Mesh2");
+        writeStringAttr(ds, "location", "face");
+        ds_gw_face_[k] = ds;
+    }
+    // Static descriptors, written once: the aquifer bottom and the resolved
+    // closure per cell (0 closed form, 1 enslaved, 2 sigma) — the mask a
+    // reader needs for Mesh2_face_gw_theta_sigma and _hu.
+    if (snap.gw2d_bed_elev.size() == static_cast(n_faces_)) {
+        hid_t space = H5Screate_simple(1, &n_faces_, nullptr);
+        hid_t ds = H5Dcreate2(file_id_, "Mesh2_face_gw_bed_elev", H5T_NATIVE_DOUBLE, space,
+                               H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+        H5Dwrite(ds, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, snap.gw2d_bed_elev.data());
+        writeStringAttr(ds, "long_name", "aquifer bottom elevation (cell bed minus soil column thickness)");
+        writeStringAttr(ds, "units", "m");
+        writeStringAttr(ds, "mesh", "Mesh2");
+        writeStringAttr(ds, "location", "face");
+        H5Dclose(ds);
+        H5Sclose(space);
+    }
+    if (snap.gw2d_closure.size() == static_cast(n_faces_)) {
+        hid_t space = H5Screate_simple(1, &n_faces_, nullptr);
+        hid_t ds = H5Dcreate2(file_id_, "Mesh2_face_gw_closure", H5T_NATIVE_INT, space,
+                               H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+        H5Dwrite(ds, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, snap.gw2d_closure.data());
+        writeStringAttr(ds, "long_name", "resolved unsaturated-zone closure per cell");
+        writeStringAttr(ds, "flag_values", "0 1 2");
+        writeStringAttr(ds, "flag_meanings", "closed_form enslaved sigma");
+        writeStringAttr(ds, "mesh", "Mesh2");
+        writeStringAttr(ds, "location", "face");
+        H5Dclose(ds);
+        H5Sclose(space);
+    }
+    // T7.5: the transported tuple. `[time, species, face]` concentrations
+    // for each zone, and a per-species ledger — the species twin of the
+    // water's `groundwater_ledger`, written to the same cadence.
+    n_gw_species_ = static_cast(std::max(0, snap.gw2d_species_count));
+    if (n_gw_species_ > 0) {
+        hsize_t zero3[3] = {0, n_gw_species_, n_faces_};
+        hsize_t chunk3[3] = {1, n_gw_species_, std::min(n_faces_, 4096)};
+        struct S { const char* name; const char* what; hid_t* ds; };
+        const S kZones[2] = {
+            {"Mesh2_face_gw_sat_conc",   "saturated zone",   &ds_gw_sat_conc_},
+            {"Mesh2_face_gw_unsat_conc", "unsaturated column", &ds_gw_unsat_conc_},
+        };
+        for (const auto& z : kZones) {
+            *z.ds = createUnlimitedDataset(z.name, 3, zero3, chunk3);
+            const std::string ln =
+                std::string("groundwater species concentration in the ") + z.what;
+            writeStringAttr(*z.ds, "long_name", ln.c_str());
+            writeStringAttr(*z.ds, "units", "1");   // per species; see species_names
+            writeStringAttr(*z.ds, "mesh", "Mesh2");
+            writeStringAttr(*z.ds, "location", "face");
+            writeStringAttr(*z.ds, "layout",
+                            "[time, species, face]; species order = the "
+                            "species_names list (pollutants, MSX, "
+                            "__WATER_AGE__, __TEMPERATURE__); a zone with no "
+                            "water reports 0");
+            if (snap.gw2d_species_names) {
+                std::string names;
+                for (hsize_t k = 0; k < n_gw_species_ &&
+                                    k < snap.gw2d_species_names->size(); ++k) {
+                    if (k) names += ",";
+                    names += (*snap.gw2d_species_names)[static_cast(k)];
+                }
+                if (!names.empty())
+                    writeStringAttr(*z.ds, "species_names", names.c_str());
+            }
+        }
+        hsize_t zerol[3] = {0, n_gw_species_, kGwSpeciesLedgerTerms};
+        hsize_t chunkl[3] = {64, n_gw_species_, kGwSpeciesLedgerTerms};
+        ds_gw_species_ledger_ = createUnlimitedDataset(
+            "groundwater_species_ledger", 3, zerol, chunkl, H5T_NATIVE_DOUBLE);
+        writeStringAttr(ds_gw_species_ledger_, "long_name",
+                        "two-zone aquifer species ledger, cumulative");
+        writeStringAttr(ds_gw_species_ledger_, "units", "1");
+        writeStringAttr(ds_gw_species_ledger_, "terms",
+                        "init,storage,infil_in,node_in,link_in,lateral_net,"
+                        "deep_out,node_out,link_out,dunne_out,et_out,"
+                        "reaction_out,residual");
+        writeStringAttr(ds_gw_species_ledger_, "layout",
+                        "[time, species, term]; mass units are the species' "
+                        "own (concentration x m3); residual = storage + out "
+                        "- in - init and is zero for a conserving kernel");
+    }
+
+    // Domain ledger series [nTime, 12], cumulative m³ — the SWMM_GW2D_LED_*
+    // order plus the continuity residual last, so a plot of the residual
+    // over time is one column read. (G-X3 appended `link` at LED index 10;
+    // the residual moved to 11 — read the `terms` attribute, not a constant.)
+    {
+        hsize_t zero[2] = {0, kGwLedgerTerms}, chunk[2] = {64, kGwLedgerTerms};
+        ds_gw_ledger_ = createUnlimitedDataset("groundwater_ledger", 2, zero, chunk,
+                                               H5T_NATIVE_DOUBLE);
+        writeStringAttr(ds_gw_ledger_, "long_name", "two-zone aquifer domain ledger, cumulative");
+        writeStringAttr(ds_gw_ledger_, "units", "m3");
+        writeStringAttr(ds_gw_ledger_, "terms",
+                        "recharge,lateral,deep,node,dunne,caprise,et,infil_in,"
+                        "init_storage,storage,link,continuity_residual");
+        writeStringAttr(ds_gw_ledger_, "layout",
+                        "[time, term]; storage includes water in flight in the side "
+                        "accumulators; continuity_residual = ledgered storage − init − (in − out)");
+    }
+    // Per-bed cumulative node exchange [nTime, nBeds], + out of the aquifer.
+    n_gw_beds_ = static_cast(snap.gw2d_bed_exchange_cum.size());
+    if (n_gw_beds_ > 0) {
+        hsize_t zero[2] = {0, n_gw_beds_}, chunk[2] = {64, n_gw_beds_};
+        ds_gw_bed_exchange_ = createUnlimitedDataset("groundwater_node_exchange_cum", 2, zero, chunk,
+                                                     H5T_NATIVE_DOUBLE);
+        writeStringAttr(ds_gw_bed_exchange_, "long_name",
+                        "cumulative aquifer <-> 1D node exchange per [2D_AQUIFER_NODE] bed, positive out of the aquifer");
+        writeStringAttr(ds_gw_bed_exchange_, "units", "m3");
+        if (snap.gw2d_node_names) {
+            std::string names;
+            for (hsize_t k = 0; k < n_gw_beds_ && k < snap.gw2d_node_names->size(); ++k) {
+                if (k) names += ",";
+                names += (*snap.gw2d_node_names)[static_cast(k)];
+            }
+            if (!names.empty()) writeStringAttr(ds_gw_bed_exchange_, "node_names", names.c_str());
+        }
+    }
+    // GW_DETAILED: the σ columns — m × nFace per step, the one large variable.
+    n_gw_layers_ = static_cast(std::max(0, snap.gw2d_m_layers));
+    if (want(report2d::GW_DETAILED) && n_gw_layers_ > 0 &&
+        snap.gw2d_theta_sigma.size() == static_cast(n_gw_layers_ * n_faces_)) {
+        hsize_t zero3[3]  = {0, n_gw_layers_, n_faces_};
+        hsize_t chunk3[3] = {1, n_gw_layers_, std::min(n_faces_, 4096)};
+        ds_gw_theta_ = createUnlimitedDataset("Mesh2_face_gw_theta_sigma", 3, zero3, chunk3);
+        writeStringAttr(ds_gw_theta_, "long_name", "closure B water content per sigma layer");
+        writeStringAttr(ds_gw_theta_, "units", "1");
+        writeStringAttr(ds_gw_theta_, "mesh", "Mesh2");
+        writeStringAttr(ds_gw_theta_, "location", "face");
+        writeStringAttr(ds_gw_theta_, "layout",
+                        "[time, layer, face]; layer 0 at the ground surface; a cell whose "
+                        "Mesh2_face_gw_closure is not 2 carries 0 in every layer");
+    }
+}
+
+void Default2DOutputPlugin::writeSpeciesRows(const double* all, hsize_t n_species_in) {
+    // Fast path: every row selected in order — write the block directly.
+    bool identity = (n_species_ == n_species_in);
+    if (identity)
+        for (std::size_t k = 0; k < species_rows_.size(); ++k)
+            if (species_rows_[k] != static_cast(k)) { identity = false; break; }
+    if (identity) {
+        extendAndWrite3D(ds_face_species_conc_, all, n_species_, n_faces_);
+        return;
+    }
+    // Gather the selected rows into a compact [n_sel × n_faces] block.
+    std::vector sel(static_cast(n_species_ * n_faces_));
+    for (std::size_t k = 0; k < species_rows_.size(); ++k) {
+        const auto r = static_cast(species_rows_[k]);
+        if (r >= static_cast(n_species_in)) continue;
+        std::copy(all + r * n_faces_, all + (r + 1) * n_faces_,
+                  sel.begin() + static_cast(k * n_faces_));
+    }
+    extendAndWrite3D(ds_face_species_conc_, sel.data(), n_species_, n_faces_);
+}
+
 // ============================================================================
 // finalize()
 // ============================================================================
@@ -552,10 +1133,47 @@ int Default2DOutputPlugin::finalize(const SimulationContext& ctx) {
             writeScalar(grp, "outfall_out",           mb.outfall_out);
             writeScalar(grp, "boundary_in",           mb.boundary_in);
             writeScalar(grp, "boundary_out",          mb.boundary_out);
+            // Both loss channels (plan §5.5.4): evap_out was previously
+            // omitted here, so writing infil_out alone would leave the
+            // sidecar's budget silently non-closing.
+            writeScalar(grp, "evap_out",              mb.evap_out);
+            writeScalar(grp, "infil_out",             mb.infil_out);
             writeDoubleAttr(grp, "continuity_error",  mb.error());
             H5Gclose(grp);
         }
     }
+    // G-O: the aquifer's own ledger, once, beside the surface's — the same
+    // terms the .rpt "2D Aquifer Continuity" block prints.
+    if (file_id_ != H5I_INVALID_HID && ctx.twod_io.aquifer_state &&
+        ctx.twod_io.aquifer_state->active) {
+        const auto& g = *ctx.twod_io.aquifer_state;
+        hid_t grp = H5Gcreate2(file_id_, "/groundwater_2d",
+                                H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+        if (grp >= 0) {
+            auto writeScalar = [this](hid_t loc, const char* name, double v) {
+                hid_t space = H5Screate(H5S_SCALAR);
+                hid_t ds = H5Dcreate2(loc, name, H5T_NATIVE_DOUBLE, space,
+                                       H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
+                H5Dwrite(ds, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, H5P_DEFAULT, &v);
+                writeStringAttr(ds, "units", "m3");
+                H5Dclose(ds);
+                H5Sclose(space);
+            };
+            writeScalar(grp, "init_storage",  g.led_init_storage);
+            writeScalar(grp, "final_storage", g.liveStorage());
+            writeScalar(grp, "infil_in",      g.led_infil_in);
+            writeScalar(grp, "link_in",       g.led_link);   // G-X3: conduit seepage
+            writeScalar(grp, "lateral_in",    g.led_lateral);
+            writeScalar(grp, "recharge",      g.led_recharge);
+            writeScalar(grp, "capillary_rise", g.led_caprise);
+            writeScalar(grp, "deep_out",      g.led_deep);
+            writeScalar(grp, "node_out",      g.led_node);
+            writeScalar(grp, "et_out",        g.led_et);
+            writeScalar(grp, "dunne_out",     g.led_dunne);
+            writeDoubleAttr(grp, "continuity_error", g.continuityResidual());
+            H5Gclose(grp);
+        }
+    }
 
     // Close all datasets
     auto closeDS = [](hid_t& ds) {
@@ -571,6 +1189,17 @@ int Default2DOutputPlugin::finalize(const SimulationContext& ctx) {
     closeDS(ds_face_rainfall_);
     closeDS(ds_face_coupling_flux_);
     closeDS(ds_face_net_source_);
+    closeDS(ds_face_infil_rate_);
+    closeDS(ds_face_infil_cum_);
+    closeDS(ds_face_rain_cum_);
+    closeDS(ds_face_species_conc_);
+    closeDS(ds_face_buildup_);
+    for (int k = 0; k < kGwFaceFields; ++k) closeDS(ds_gw_face_[k]);   // G-O
+    closeDS(ds_gw_sat_conc_); closeDS(ds_gw_unsat_conc_);              // T7.5
+    closeDS(ds_gw_species_ledger_);
+    closeDS(ds_gw_ledger_);
+    closeDS(ds_gw_bed_exchange_);
+    closeDS(ds_gw_theta_);
     closeDS(ds_face_vx_);
     closeDS(ds_face_vy_);
     closeDS(ds_face_continuity_err_);
diff --git a/src/engine/2d/output/Default2DOutputPlugin.hpp b/src/engine/2d/output/Default2DOutputPlugin.hpp
index fb7930e70..85d2ac1d3 100644
--- a/src/engine/2d/output/Default2DOutputPlugin.hpp
+++ b/src/engine/2d/output/Default2DOutputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Default2DOutputPlugin.hpp
  * @brief Built-in HDF5 output plugin for 2D surface routing results.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #pragma once
@@ -23,11 +39,13 @@
 #include "../../../../include/openswmm/plugin_sdk/IOutputPlugin.hpp"
 
 #include 
+#include 
 #include 
 
 namespace openswmm::twoD {
 
-struct MeshData;  // forward declaration
+struct MeshData;          // forward declaration
+struct SolverOptions2D;   // forward declaration
 
 /**
  * @brief Default 2D output plugin: writes CF/UGRID-compliant HDF5 file.
@@ -40,6 +58,41 @@ struct MeshData;  // forward declaration
  * ### Root attributes
  *   - Conventions = "CF-1.11 UGRID-1.0"
  *
+ * ### Coordinate reference (written once in prepareMeshAndDatasets())
+ *   - /crs                           scalar georeferencing variable, pointed at
+ *                                    by the `openswmm_crs` attribute on /Mesh2
+ *                                    and the node/face coordinate variables.
+ *
+ *   All x/y coordinates in this file are stored in **SI metres**, because the
+ *   2D solver runs internally in SI. The model itself may be authored in a
+ *   different linear unit (US FLOW_UNITS projects are in feet, and their CRS
+ *   is typically a foot-based projected CRS such as EPSG:2249). The `/crs`
+ *   variable makes that relationship explicit rather than leaving a consumer
+ *   to assume the coordinates are already in the model CRS's unit:
+ *
+ *   - @model_crs             the model's CRS as authored in `[OPTIONS] CRS`
+ *                            (e.g. "EPSG:2249", a PROJ string, or WKT). This
+ *                            is the CRS of the MODEL coordinates, not of the
+ *                            metric values stored here.
+ *   - @metres_per_model_unit stored = model x this; model = stored / this.
+ *                            Precisely: the factor SurfaceRouter2D::initialize
+ *                            actually applied — 0.3048 for US FLOW_UNITS, and
+ *                            1.0 for SI projects AND for any mesh that
+ *                            declared `;; UNITS: SI (m)` (the engine skips its
+ *                            scaling there, so the stored metres already ARE
+ *                            the authored values).
+ *   - @units                 "m" — the unit of the stored coordinates.
+ *
+ *   Deliberately NOT a CF grid mapping — not `grid_mapping_name`, not
+ *   `spatial_ref`/`crs_wkt`, and the pointer attribute is `openswmm_crs`
+ *   rather than CF's `grid_mapping`. A generic CF/GDAL reader honouring those
+ *   would place the metric values in the foot-based CRS and reproduce the very
+ *   offset this variable exists to describe; and a `grid_mapping` pointing at
+ *   a variable with no `grid_mapping_name` is itself non-conformant, so strict
+ *   readers could warn or drop the coordinate variables. The OpenSWMM-
+ *   namespaced pair `model_crs` + `metres_per_model_unit` cannot be
+ *   half-consumed: neither means anything without the other. See issue #155.
+ *
  * ### Static mesh topology (written once in prepare())
  *   - /Mesh2                         topology variable (cf_role = "mesh_topology")
  *   - /Mesh2_node_x, /Mesh2_node_y  vertex coordinates
@@ -61,6 +114,9 @@ struct MeshData;  // forward declaration
  *   - /Mesh2_face_rainfall           [nTime, nFace] rainfall (m/s)
  *   - /Mesh2_face_coupling_flux      [nTime, nFace] node coupling (m/s)
  *   - /Mesh2_face_net_source         [nTime, nFace] net source/sink (m/s)
+ *   - /Mesh2_face_infil_rate         [nTime, nFace] held infiltration rate (m/s)
+ *   - /Mesh2_face_infil_cum          [nTime, nFace] cumulative infiltrated depth (m)
+ *   - /Mesh2_face_rain_cum           [nTime, nFace] cumulative rainfall volume (m³)
  *   - /Mesh2_face_vx                 [nTime, nFace] cell velocity X (m/s)
  *   - /Mesh2_face_vy                 [nTime, nFace] cell velocity Y (m/s)
  *   - /Mesh2_face_continuity_err     [nTime, nFace] per-cell continuity residual (m³/s)
@@ -122,11 +178,58 @@ class Default2DOutputPlugin final : public IOutputPlugin {
      */
     void prepareMeshAndDatasets(const MeshData& mesh);
 
+    /**
+     * @brief Declare the factor already applied to the stored coordinates.
+     *
+     * @details The model CRS reaches the plugin through prepare()'s
+     *          SimulationContext, but the mesh scale factor does not —
+     *          SurfaceRouter2D owns it. SWMMEngine calls this between
+     *          prepare() and prepareMeshAndDatasets(). Left uncalled, `/crs`
+     *          reports 1.0, i.e. it claims nothing it cannot substantiate.
+     *
+     * @param metres_per_model_unit Metres per model-CRS linear unit — the
+     *                              factor already applied to the stored
+     *                              coordinates (0.3048 for US, 1.0 for SI).
+     */
+    void setMeshCoordinateScale(double metres_per_model_unit);
+
+    /**
+     * @brief Apply the results-file size controls from [2D_OPTIONS]
+     *        (OUTPUT_PRECISION, OUTPUT_COMPRESSION, REPORT_2D_VARIABLES,
+     *        REPORT_2D_SPECIES, REPORT_2D_STEP). Called by SWMMEngine before
+     *        prepareMeshAndDatasets(); datasets not selected are never
+     *        created, so readers must treat every time-varying dataset as
+     *        optional.
+     * @param report_step_sec  [OPTIONS] REPORT_STEP, the cadence update() is
+     *                         called at; REPORT_2D_STEP is validated against it.
+     * @return Empty on success, else a validation message (REPORT_2D_STEP not
+     *         a positive multiple of REPORT_STEP).
+     */
+    std::string configureOutput(const SolverOptions2D& opts, double report_step_sec);
+
+    /// Bitmask of report2d::Var groups in effect (for tests / the C API).
+    unsigned reportVariables() const noexcept { return report_vars_; }
+
 private:
+    // ---- results-file size controls (configureOutput) ----
+    hid_t    storage_type_ = H5T_NATIVE_DOUBLE;  ///< H5T_IEEE_F32LE when FLOAT32
+    int      compression_  = 4;                  ///< zlib level; 0 = none
+    unsigned report_vars_  = 0x7FFu;             ///< report2d::ALL_MASK until configured
+    std::vector species_filter_;    ///< empty = every row
+    std::vector         species_rows_;      ///< row indices written (resolved on first update)
+    double   report_2d_step_days_ = 0.0;         ///< 0 = every update() call
+    double   next_due_days_       = -1.0;        ///< next write instant (days)
+    bool     want(unsigned bit) const noexcept { return (report_vars_ & bit) != 0; }
+    /// Write \p n_sel selected species rows of a [n_species × n_faces] block.
+    void writeSpeciesRows(const double* all, hsize_t n_species_in);
+
     std::string  h5_path_;
     PluginState  state_ = PluginState::UNLOADED;
     std::string  last_error_;
 
+    std::string  model_crs_;                ///< `[OPTIONS] CRS`, verbatim
+    double       metres_per_model_unit_ = 1.0;  ///< stored = model x this
+
     hid_t file_id_   = H5I_INVALID_HID;  ///< HDF5 file handle
 
     // Dataset handles for time-varying fields (unlimited time dimension)
@@ -140,6 +243,45 @@ class Default2DOutputPlugin final : public IOutputPlugin {
     hid_t ds_face_rainfall_        = H5I_INVALID_HID;
     hid_t ds_face_coupling_flux_   = H5I_INVALID_HID;
     hid_t ds_face_net_source_      = H5I_INVALID_HID;
+    hid_t ds_face_infil_rate_      = H5I_INVALID_HID;
+    hid_t ds_face_infil_cum_       = H5I_INVALID_HID;
+    hid_t ds_face_rain_cum_        = H5I_INVALID_HID;
+    /// Overland transport S1: [nTime, nSpecies, nFace] species concentration.
+    /// Created lazily on the first update() carrying species; absent when the
+    /// model has no 2D transport.
+    hid_t   ds_face_species_conc_  = H5I_INVALID_HID;
+    hsize_t n_species_             = 0;
+    /// S7: [nTime, nSurfaceSpecies, nFace] cell buildup per unit land area
+    /// (the pollutant and MSX rows). Created lazily; absent when no
+    /// [2D_COVERAGES] row resolved or BUILDUP is off.
+    hid_t   ds_face_buildup_       = H5I_INVALID_HID;
+    hsize_t n_buildup_             = 0;
+    /// G-O: the two-zone aquifer's results — ten per-cell [nTime, nFace]
+    /// fields, the domain ledger [nTime, 11], the per-bed cumulative node
+    /// exchange [nTime, nBeds] and (GW_DETAILED) the σ columns
+    /// [nTime, mLayers, nFace]. Created lazily on the first update() with a
+    /// live kernel; absent otherwise. `Mesh2_face_gw_bed_elev` and
+    /// `Mesh2_face_gw_closure` are static [nFace] and written once.
+    static constexpr int kGwFaceFields = 11;   // G-X3: + Mesh2_face_gw_link_seepage
+    static constexpr hsize_t kGwLedgerTerms = 12;   // G-X3: + link (LED 10), residual last
+    hid_t   ds_gw_face_[kGwFaceFields] = {H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
+                                          H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
+                                          H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
+                                          H5I_INVALID_HID, H5I_INVALID_HID};
+    hid_t   ds_gw_ledger_          = H5I_INVALID_HID;
+    /// T7.5: the aquifer's species fields, created with the rest of the
+    /// groundwater group when the kernel carries a tuple.
+    static constexpr hsize_t kGwSpeciesLedgerTerms = 13;
+    hid_t   ds_gw_sat_conc_        = H5I_INVALID_HID;
+    hid_t   ds_gw_unsat_conc_      = H5I_INVALID_HID;
+    hid_t   ds_gw_species_ledger_  = H5I_INVALID_HID;
+    hsize_t n_gw_species_          = 0;
+    hid_t   ds_gw_bed_exchange_    = H5I_INVALID_HID;
+    hid_t   ds_gw_theta_           = H5I_INVALID_HID;
+    hsize_t n_gw_beds_             = 0;
+    hsize_t n_gw_layers_           = 0;
+    bool    gw_created_            = false;
+    void createGroundwaterDatasets(const SimulationSnapshot& snap);
     hid_t ds_face_vx_              = H5I_INVALID_HID;
     hid_t ds_face_vy_              = H5I_INVALID_HID;
     hid_t ds_face_continuity_err_  = H5I_INVALID_HID;
@@ -154,13 +296,21 @@ class Default2DOutputPlugin final : public IOutputPlugin {
 
     hsize_t n_faces_  = 0;
     hsize_t n_nodes_  = 0;
+    hsize_t edge_stride_ = 3;  ///< Public edge-slot stride (3 all-tri, 4 mixed)
     hsize_t n_steps_  = 0;  ///< Current time step count (grows with each update)
 
     // Helpers
     void writeMeshTopology(const SimulationContext& ctx);
+    /// Write the scalar `/crs` georeferencing variable (see class docs).
+    void writeCrsVariable();
+    /// @param type  Storage type; -1 (the default) follows OUTPUT_PRECISION.
+    ///              The time axis passes H5T_NATIVE_DOUBLE explicitly: a day
+    ///              number in float32 loses ~0.1 ms on an hour, which the
+    ///              readers' time lookup cannot absorb.
     hid_t createUnlimitedDataset(const char* name, int rank,
                                   const hsize_t* dims,
-                                  const hsize_t* chunk_dims);
+                                  const hsize_t* chunk_dims,
+                                  hid_t type = -1);
     void writeStringAttr(hid_t loc, const char* name, const char* value);
     void writeDoubleAttr(hid_t loc, const char* name, double value);
     void extendAndWrite2D(hid_t ds, const double* data, hsize_t n_cols);
diff --git a/src/engine/2d/quality/SurfaceQuality2D.cpp b/src/engine/2d/quality/SurfaceQuality2D.cpp
new file mode 100644
index 000000000..b778c8b61
--- /dev/null
+++ b/src/engine/2d/quality/SurfaceQuality2D.cpp
@@ -0,0 +1,612 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SurfaceQuality2D.cpp
+ * @brief S7 — see SurfaceQuality2D.hpp. The buildup / washoff / sweeping
+ *        formulas are the subcatchment step's (SWMMEngine::stepSurfaceQuality,
+ *        the A7 sweeping block, initialize 11b — and their BW-MSX
+ *        transcription in quality/MsxSurfaceQuality.cpp), written in the 2D
+ *        module's SI: cell area m², runoff in m/s, cell rows in
+ *        concentration × m³. The land-use functions themselves are unit-free
+ *        in "days" and "user mass per normalizer unit", so buildup on a cell
+ *        with no flow is bit-identical to buildup on a subcatchment (gate 1).
+ */
+
+#include "SurfaceQuality2D.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../data/MeshData.hpp"
+#include "../data/SolverOptions2D.hpp"
+#include "../data/SurfaceStateData.hpp"
+#include "../data/SurfaceTransportState.hpp"
+#include "../../core/DateTime.hpp"
+#include "../../core/SimulationContext.hpp"
+#include "../../core/UnitConversion.hpp"
+#include "../../input/InputParseUtils.hpp"
+#include "../../input/Tokenizer.hpp"
+#include "../../quality/MsxSurfaceQuality.hpp"
+
+namespace openswmm::twoD {
+
+namespace {
+
+constexpr double kSqMPerAcre  = 4046.8564224;
+constexpr double kSqMPerHa    = 10000.0;
+constexpr double kM3PerFt3    = 0.028316846592;
+constexpr double kMinRunoffMs = 1.0e-9 * 0.3048;   // the 1D ft/s threshold, in m/s
+
+bool iequals(const std::string& a, const char* b) {
+    std::size_t i = 0;
+    for (; i < a.size() && b[i]; ++i)
+        if (std::toupper(static_cast(a[i])) !=
+            std::toupper(static_cast(b[i]))) return false;
+    return i == a.size() && b[i] == '\0';
+}
+bool num(const std::string& s, double& v) {
+    try { std::size_t n = 0; v = std::stod(s, &n); return n == s.size(); }
+    catch (...) { return false; }
+}
+
+double buildupAt(int type, double c0, double c1, double c2, double days) {
+    if (!(days > 0.0)) return 0.0;
+    switch (type) {
+        case 1: return std::min(c1 * std::pow(days, c2), c0);              // POW
+        case 2: return c0 * (1.0 - std::exp(-c1 * days));                  // EXP
+        case 3: return (c2 + days > 0.0) ? c0 * days / (c2 + days) : 0.0;  // SAT
+        default: return 0.0;
+    }
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// Scope tokens and line parsers
+// ---------------------------------------------------------------------------
+
+std::string formatSqScope(const SqScopeKey& k) {
+    switch (k.scope) {
+        case SqScope::TAG:  return "TAG " + k.tag;
+        case SqScope::CELL: return "CELL " + std::to_string(k.cell + 1);
+        default:            return "*";
+    }
+}
+
+std::string parseSqScope(const std::vector& tokens, std::size_t& at,
+                         SqScopeKey& key, const char* section) {
+    if (tokens.empty()) return std::string(section) + " empty row";
+    if (tokens[0] == "*") { key.scope = SqScope::GLOBAL; at = 1; return {}; }
+    if (iequals(tokens[0], "TAG")) {
+        if (tokens.size() < 2) return std::string(section) + " TAG needs a name";
+        key.scope = SqScope::TAG; key.tag = tokens[1]; at = 2; return {};
+    }
+    if (iequals(tokens[0], "CELL")) {
+        if (tokens.size() < 2) return std::string(section) + " CELL needs an index";
+        double d = 0.0;
+        if (!num(tokens[1], d) || d < 1.0 || d != std::floor(d))
+            return std::string(section) + " invalid CELL index (1-based): " + tokens[1];
+        key.scope = SqScope::CELL; key.cell = static_cast(d) - 1; at = 2; return {};
+    }
+    return std::string(section) + " row must start with CELL, TAG or '*': " + tokens[0];
+}
+
+std::string parse2DCoveragesLine(const std::vector& tokens,
+                                 std::vector& rows) {
+    CoverageRow2D r;
+    std::size_t at = 0;
+    std::string err = parseSqScope(tokens, at, r.key, "[2D_COVERAGES]");
+    if (!err.empty()) return err;
+    if (at >= tokens.size() || (tokens.size() - at) % 2 != 0)
+        return "[2D_COVERAGES] expects LANDUSE PERCENT pairs after the scope";
+    double sum = 0.0;
+    for (; at + 1 < tokens.size(); at += 2) {
+        double pct = 0.0;
+        if (!num(tokens[at + 1], pct) || pct < 0.0)
+            return "[2D_COVERAGES] invalid percent for '" + tokens[at] + "': " + tokens[at + 1];
+        sum += pct;
+        r.uses.emplace_back(tokens[at], pct);
+    }
+    if (sum > 100.0 + 1e-9)
+        return "[2D_COVERAGES] percents for scope '" + formatSqScope(r.key) +
+               "' sum to " + std::to_string(sum) + " (> 100)";
+    // A row REPLACES the set for its scope (the subcatchment [COVERAGES]
+    // semantics): drop an earlier row with the same key.
+    rows.erase(std::remove_if(rows.begin(), rows.end(), [&](const CoverageRow2D& o) {
+        return o.key.scope == r.key.scope && o.key.tag == r.key.tag && o.key.cell == r.key.cell;
+    }), rows.end());
+    rows.push_back(std::move(r));
+    return {};
+}
+
+std::string parse2DLoadingsLine(const std::vector& tokens,
+                                std::vector& rows) {
+    LoadingRow2D r;
+    std::size_t at = 0;
+    std::string err = parseSqScope(tokens, at, r.key, "[2D_LOADINGS]");
+    if (!err.empty()) return err;
+    if (at + 2 != tokens.size()) return "[2D_LOADINGS] expects SPECIES VALUE after the scope";
+    r.species = tokens[at];
+    if (!num(tokens[at + 1], r.value) || r.value < 0.0)
+        return "[2D_LOADINGS] invalid value for '" + r.species + "': " + tokens[at + 1];
+    rows.push_back(std::move(r));
+    return {};
+}
+
+std::string parse2DCurbLengthLine(const std::vector& tokens,
+                                  std::vector& rows) {
+    CurbRow2D r;
+    std::size_t at = 0;
+    std::string err = parseSqScope(tokens, at, r.key, "[2D_CURB_LENGTH]");
+    if (!err.empty()) return err;
+    if (at + 1 != tokens.size()) return "[2D_CURB_LENGTH] expects LENGTH after the scope";
+    if (!num(tokens[at], r.length) || r.length < 0.0)
+        return "[2D_CURB_LENGTH] invalid length: " + tokens[at];
+    rows.push_back(std::move(r));
+    return {};
+}
+
+void registerSurfaceQualitySections(SurfaceQuality2D& sq, input::SectionRegistry& registry) {
+    auto make = [&sq](const char* tag, auto parser, auto member) {
+        return [tag, parser, member, &sq](SimulationContext& ctx,
+                                          const std::vector& lines) {
+            for (const auto& raw : lines) {
+                auto tokens = input::Tokenizer::tokenize(raw);
+                if (tokens.empty()) continue;
+                const std::string err = parser(tokens, sq.*member);
+                if (!err.empty()) {
+                    ctx.error_code    = 5;   // SWMM_ERR_PARSE
+                    ctx.error_message = std::string("[2D] ") + err + " — line: " + raw;
+                    return;
+                }
+            }
+            (void)tag;
+        };
+    };
+    registry.register_custom("2D_COVERAGES",
+        make("2D_COVERAGES", &parse2DCoveragesLine, &SurfaceQuality2D::coverage_rows));
+    registry.register_custom("2D_LOADINGS",
+        make("2D_LOADINGS", &parse2DLoadingsLine, &SurfaceQuality2D::loading_rows));
+    registry.register_custom("2D_CURB_LENGTH",
+        make("2D_CURB_LENGTH", &parse2DCurbLengthLine, &SurfaceQuality2D::curb_rows));
+}
+
+// ---------------------------------------------------------------------------
+// Resolve
+// ---------------------------------------------------------------------------
+
+void SurfaceQuality2D::loadParams(const SimulationContext& ctx) {
+    const int np = ctx.n_pollutants();
+    params_.assign(static_cast(n_lu_) * static_cast(n_sp_), Params{});
+    for (int lu = 0; lu < n_lu_; ++lu) {
+        for (int s = 0; s < n_sp_; ++s) {
+            Params& P = params_[static_cast(lu) * static_cast(n_sp_) +
+                                static_cast(s)];
+            const int row = row_of_[static_cast(s)];
+            if (row < np) {                                    // pollutant tables
+                const auto k = static_cast(lu * np + row);
+                if (ctx.buildup.n_pollutants == np && k < ctx.buildup.func_type.size()) {
+                    P.bu_type = ctx.buildup.func_type[k];
+                    P.c0 = ctx.buildup.coeff1[k]; P.c1 = ctx.buildup.coeff2[k]; P.c2 = ctx.buildup.coeff3[k];
+                    if (P.bu_type == 4) P.ts_idx = static_cast(ctx.buildup.coeff3[k]);
+                    P.normalizer = ctx.buildup.normalizer[k];
+                }
+                if (ctx.washoff.n_pollutants == np && k < ctx.washoff.func_type.size()) {
+                    P.wo_type = ctx.washoff.func_type[k];
+                    P.coeff = ctx.washoff.coeff[k]; P.expon = ctx.washoff.expon[k];
+                    P.sweep_effic = ctx.washoff.sweep_effic[k]; P.bmp_effic = ctx.washoff.bmp_effic[k];
+                }
+            } else {                                           // BW-MSX tables
+                const auto& ms = ctx.reactions.surface;
+                const int m = row - np;
+                if (ms.n_landuses == n_lu_ && m >= 0 && m < ms.n_species) {
+                    const auto k = ms.pidx(lu, m);
+                    P.bu_type = ms.bu_type[k];
+                    P.c0 = ms.bu_c1[k]; P.c1 = ms.bu_c2[k]; P.c2 = ms.bu_c3[k];
+                    if (P.bu_type == 4) P.ts_idx = static_cast(ms.bu_c3[k]);
+                    P.normalizer = ms.bu_normalizer[k];
+                    P.wo_type = ms.wo_type[k];
+                    P.coeff = ms.wo_coeff[k]; P.expon = ms.wo_expon[k];
+                    P.sweep_effic = ms.wo_sweep_effic[k]; P.bmp_effic = ms.wo_bmp_effic[k];
+                }
+            }
+            // refreshLanduseParams(): time to reach 99.9 % of the maximum
+            if (P.bu_type == 2 && P.c1 > 0.0)                               P.max_days = -std::log(0.001) / P.c1;
+            else if (P.bu_type == 1 && P.c1 > 0.0 && P.c2 > 0.0 && P.c0 > 0.0) P.max_days = std::pow(P.c0 / P.c1, 1.0 / P.c2);
+            else if (P.bu_type == 3 && P.c2 > 0.0 && P.c0 > 0.0)             P.max_days = 999.0 * P.c2;
+        }
+    }
+}
+
+std::vector SurfaceQuality2D::resolve(const SimulationContext& ctx,
+                                                   const MeshData& mesh,
+                                                   const SurfaceTransportState& tr,
+                                                   const SolverOptions2D& opts) {
+    std::vector out;
+    active_ = false;
+    if (!authored()) return out;
+    if (coverage_rows.empty()) {
+        out.push_back("[2D_LOADINGS] / [2D_CURB_LENGTH] rows are present but no "
+                      "[2D_COVERAGES] names a land use on the mesh; nothing builds up.");
+        return out;
+    }
+
+    n_cells_ = mesh.n_triangles();
+    n_lu_    = ctx.n_landuses();
+    if (n_lu_ <= 0) { out.push_back("ERROR [2D_COVERAGES]: the model defines no [LANDUSES]."); return out; }
+    if (!tr.active()) {
+        out.push_back("ERROR [2D_COVERAGES]: the model carries no transported species "
+                      "([POLLUTANTS] empty or IGNORE_QUALITY set), so nothing could wash off.");
+        return out;
+    }
+    si_ = (ucf::getUnitSystem(static_cast(ctx.options.flow_units)) == 1);
+    area_to_landarea_ = si_ ? 1.0 / kSqMPerHa : 1.0 / kSqMPerAcre;
+
+    // ---- surface species: the pollutant and MSX rows of the transport layout
+    const int np = tr.n_pollut, nm = tr.n_msx;
+    n_sp_ = np + nm;
+    row_of_.clear(); names_.clear(); mcf_.clear();
+    const double mass_ucf = ucf::UCF(ucf::MASS, ctx.options);
+    for (int s = 0; s < n_sp_; ++s) {
+        row_of_.push_back(s);                         // rows [0, np+nm) are exactly these
+        names_.push_back(static_cast(s) < tr.row_names.size() ? tr.row_names[static_cast(s)] : std::string{});
+        double f = mass_ucf;
+        if (s < np) {
+            const auto up = static_cast(s);
+            if (up < ctx.pollutants.units.size()) {
+                if (ctx.pollutants.units[up] == MassUnits::UG_PER_L)     f = mass_ucf / 1000.0;
+                if (ctx.pollutants.units[up] == MassUnits::COUNTS_PER_L) f = 1.0;
+            }
+        } else {
+            const auto um = static_cast(s - np);
+            f = msxsurf::speciesUnitFactor(
+                um < ctx.reactions.species_units.size() ? ctx.reactions.species_units[um] : std::string{},
+                ctx.options);
+        }
+        mcf_.push_back(f);
+    }
+    loadParams(ctx);
+
+    // ---- coverages: GLOBAL < TAG < CELL, a row replaces the set -----------
+    cov_.assign(static_cast(n_cells_) * static_cast(n_lu_), 0.0);
+    std::vector covered(static_cast(n_cells_), 0);
+    auto apply = [&](const CoverageRow2D& r, int c) {
+        for (int lu = 0; lu < n_lu_; ++lu) cov_[cidx(c, lu)] = 0.0;
+        for (const auto& u : r.uses) {
+            const int lu = ctx.landuse_names.find(u.first);
+            cov_[cidx(c, lu)] = u.second / 100.0;
+        }
+        covered[static_cast(c)] = 1;
+    };
+    for (int pass = 0; pass < 3; ++pass) {
+        for (const auto& r : coverage_rows) {
+            if (static_cast(r.key.scope) != pass) continue;
+            bool bad = false;
+            for (const auto& u : r.uses)
+                if (ctx.landuse_names.find(u.first) < 0) {
+                    out.push_back("ERROR [2D_COVERAGES] land use '" + u.first + "' is not defined.");
+                    bad = true;
+                }
+            if (bad) continue;
+            if (r.key.scope == SqScope::GLOBAL) {
+                for (int c = 0; c < n_cells_; ++c) apply(r, c);
+            } else if (r.key.scope == SqScope::TAG) {
+                bool hit = false;
+                for (int c = 0; c < n_cells_; ++c)
+                    if (static_cast(c) < mesh.tri_tag.size() && mesh.tri_tag[static_cast(c)] == r.key.tag) {
+                        apply(r, c); hit = true;
+                    }
+                if (!hit) out.push_back("ERROR [2D_COVERAGES] TAG '" + r.key.tag + "' matches no cell.");
+            } else {
+                if (r.key.cell < 0 || r.key.cell >= n_cells_) {
+                    out.push_back("ERROR [2D_COVERAGES] CELL " + std::to_string(r.key.cell + 1) +
+                                  " is beyond the mesh (" + std::to_string(n_cells_) + " cells).");
+                    continue;
+                }
+                apply(r, r.key.cell);
+            }
+        }
+    }
+    for (const auto& d : out) if (d.rfind("ERROR", 0) == 0) return out;
+
+    // ---- curb lengths ------------------------------------------------------
+    curb_.assign(static_cast(n_cells_), 0.0);
+    for (int pass = 0; pass < 3; ++pass) {
+        for (const auto& r : curb_rows) {
+            if (static_cast(r.key.scope) != pass) continue;
+            if (r.key.scope == SqScope::GLOBAL) {
+                std::fill(curb_.begin(), curb_.end(), r.length);
+            } else if (r.key.scope == SqScope::TAG) {
+                for (int c = 0; c < n_cells_; ++c)
+                    if (static_cast(c) < mesh.tri_tag.size() && mesh.tri_tag[static_cast(c)] == r.key.tag)
+                        curb_[static_cast(c)] = r.length;
+            } else if (r.key.cell >= 0 && r.key.cell < n_cells_) {
+                curb_[static_cast(r.key.cell)] = r.length;
+            } else {
+                out.push_back("ERROR [2D_CURB_LENGTH] CELL " + std::to_string(r.key.cell + 1) + " is beyond the mesh.");
+                return out;
+            }
+        }
+    }
+    // D-A25: a PER_CURB land use on a covered cell needs a curb length.
+    for (int c = 0; c < n_cells_; ++c)
+        for (int lu = 0; lu < n_lu_; ++lu) {
+            if (cov_[cidx(c, lu)] <= 0.0) continue;
+            for (int s = 0; s < n_sp_; ++s)
+                if (param(lu, s).bu_type != 0 && param(lu, s).normalizer == 1 &&
+                    !(curb_[static_cast(c)] > 0.0)) {
+                    out.push_back("ERROR [2D_COVERAGES] cell " + std::to_string(c + 1) + " carries land use '" +
+                                  ctx.landuse_names.name_of(lu) + "', whose buildup of '" + names_[static_cast(s)] +
+                                  "' is PER_CURB, but no [2D_CURB_LENGTH] gives it a curb length.");
+                    return out;
+                }
+        }
+
+    // ---- loadings ----------------------------------------------------------
+    init_.assign(static_cast(n_cells_) * static_cast(n_sp_), 0.0);
+    for (int pass = 0; pass < 3; ++pass) {
+        for (const auto& r : loading_rows) {
+            if (static_cast(r.key.scope) != pass) continue;
+            int s = -1;
+            for (int i = 0; i < n_sp_; ++i) if (names_[static_cast(i)] == r.species) { s = i; break; }
+            if (s < 0) {
+                out.push_back("ERROR [2D_LOADINGS] '" + r.species + "' is neither a pollutant nor a "
+                              "reactions-component species (age and temperature do not build up).");
+                return out;
+            }
+            auto set = [&](int c) { init_[static_cast(c) * static_cast(n_sp_) + static_cast(s)] = r.value; };
+            if (r.key.scope == SqScope::GLOBAL) { for (int c = 0; c < n_cells_; ++c) set(c); }
+            else if (r.key.scope == SqScope::TAG) {
+                for (int c = 0; c < n_cells_; ++c)
+                    if (static_cast(c) < mesh.tri_tag.size() && mesh.tri_tag[static_cast(c)] == r.key.tag) set(c);
+            } else if (r.key.cell >= 0 && r.key.cell < n_cells_) set(r.key.cell);
+            else { out.push_back("ERROR [2D_LOADINGS] CELL " + std::to_string(r.key.cell + 1) + " is beyond the mesh."); return out; }
+        }
+    }
+
+    // ---- ownership (D-A23) ---------------------------------------------------
+    if (opts.rainfall_mode == RainfallMode::NONE) {
+        out.push_back("[2D_COVERAGES] authored but RAINFALL_MODE NONE — the subcatchments own the "
+                      "surface (no rain on the mesh); cell buildup / washoff is inert this run.");
+        return out;
+    }
+    {
+        // Covered cells inside a subcatchment that itself has [COVERAGES]:
+        // the same storm would load the outlet twice. One warning, naming
+        // the subcatchments; the run proceeds (a hybrid may be intended).
+        const auto& px = ctx.spatial.subcatch_polygon_x;
+        const auto& py = ctx.spatial.subcatch_polygon_y;
+        const int nsub = ctx.n_subcatches(), nlu1 = ctx.subcatches.coverage_n_landuses;
+        const double inv = (opts.mesh_to_si_factor > 0.0) ? 1.0 / opts.mesh_to_si_factor : 1.0;
+        std::set names;
+        for (int sub = 0; sub < nsub; ++sub) {
+            const auto us = static_cast(sub);
+            if (us >= px.size() || px[us].size() < 3) continue;
+            bool sub_covered = false;
+            for (int lu = 0; lu < nlu1 && !sub_covered; ++lu) {
+                const auto k = us * static_cast(nlu1) + static_cast(lu);
+                if (k < ctx.subcatches.coverage.size() && ctx.subcatches.coverage[k] > 0.0) sub_covered = true;
+            }
+            if (!sub_covered) continue;
+            const auto& xs = px[us]; const auto& ys = py[us];
+            for (int c = 0; c < n_cells_ && !names.count(ctx.subcatch_names.name_of(sub)); ++c) {
+                if (!covered[static_cast(c)]) continue;
+                const double x = mesh.tri_cx[static_cast(c)] * inv;
+                const double y = mesh.tri_cy[static_cast(c)] * inv;
+                bool in = false;
+                for (std::size_t i = 0, j = xs.size() - 1; i < xs.size(); j = i++)
+                    if (((ys[i] > y) != (ys[j] > y)) &&
+                        (x < (xs[j] - xs[i]) * (y - ys[i]) / (ys[j] - ys[i]) + xs[i])) in = !in;
+                if (in) names.insert(ctx.subcatch_names.name_of(sub));
+            }
+        }
+        if (!names.empty()) {
+            std::string list;
+            for (const auto& n : names) { if (!list.empty()) list += ", "; list += n; }
+            out.push_back("[2D_COVERAGES] covered cells lie inside subcatchment(s) that also carry "
+                          "[COVERAGES] (" + list + "): the same storm loads the outlet from both; "
+                          "if that is not intended, remove one side's coverages.");
+        }
+    }
+
+    area_la_.assign(static_cast(n_cells_), 0.0);
+    for (int c = 0; c < n_cells_; ++c)
+        area_la_[static_cast(c)] = mesh.tri_area[static_cast(c)] * area_to_landarea_;
+    bu_.assign(static_cast(n_lu_) * static_cast(n_sp_) * static_cast(n_cells_), 0.0);
+    last_swept_.assign(static_cast(n_cells_) * static_cast(n_lu_), 0.0);
+    runoff_vol_.assign(static_cast(n_cells_), 0.0);
+    led_init_.assign(static_cast(n_sp_), 0.0);
+    led_bu_ = led_wo_ = led_sw_ = led_bmp_ = led_init_;
+    active_ = true;
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+void SurfaceQuality2D::initState(const SimulationContext& ctx, const MeshData& mesh) {
+    if (!active_) return;
+    const double dry_days = ctx.options.dry_days;
+    for (int c = 0; c < n_cells_; ++c) {
+        const auto uc = static_cast(c);
+        const double area_la = mesh.tri_area[uc] * area_to_landarea_;
+        for (int lu = 0; lu < n_lu_; ++lu) {
+            const double frac = cov_[cidx(c, lu)];
+            if (frac <= 0.0) continue;
+            for (int s = 0; s < n_sp_; ++s) {
+                const Params& P = param(lu, s);
+                const double norm = (P.normalizer == 0) ? frac * area_la : frac * curb_[uc];
+                const double load0 = init_[uc * static_cast(n_sp_) + static_cast(s)];
+                double mass = 0.0;
+                if (load0 > 0.0) {
+                    mass = (P.normalizer == 0) ? load0
+                         : (curb_[uc] > 0.0 ? load0 * area_la / curb_[uc] : 0.0);
+                } else if (dry_days > 0.0 && P.bu_type != 0 && P.bu_type != 4) {
+                    mass = buildupAt(P.bu_type, P.c0, P.c1, P.c2, dry_days);
+                }
+                if (mass <= 0.0) continue;
+                bu_[bidx(c, lu, s)] = mass;
+                led_init_[static_cast(s)] += mass * norm;
+            }
+        }
+    }
+}
+
+double SurfaceQuality2D::buildupPerArea(int c, int s) const noexcept {
+    if (!active_) return 0.0;
+    const auto uc = static_cast(c);
+    const double area_la = area_la_[uc];
+    if (!(area_la > 0.0)) return 0.0;
+    double mass = 0.0;   // user mass on the cell
+    for (int lu = 0; lu < n_lu_; ++lu) {
+        const double frac = cov_[cidx(c, lu)];
+        if (frac <= 0.0) continue;
+        const Params& P = param(lu, s);
+        const double norm = (P.normalizer == 0) ? frac * area_la : frac * curb_[uc];
+        mass += bu_[bidx(c, lu, s)] * norm;
+    }
+    return mass / area_la;
+}
+
+void SurfaceQuality2D::step(const SimulationContext& ctx, const MeshData& mesh,
+                            SurfaceStateData& state, double dt_runoff, double abs_time,
+                            bool is_raining) {
+    if (!active_ || !(dt_runoff > 0.0)) return;
+    auto& tr = state.transport;
+    if (!tr.active() || tr.cell_runoff_vol.size() != static_cast(n_cells_)) return;
+    if (tr.gained_washoff.size() != static_cast(tr.n_species))
+        tr.gained_washoff.assign(static_cast(tr.n_species), 0.0);
+
+    const double dt_days = dt_runoff / ucf::SEC_PER_DAY;
+    // washoff-law unit factors
+    const double q_to_display = si_ ? 1000.0 * 3600.0 : 39.3700787 * 3600.0;   // m/s → mm/hr | in/hr
+    const double ucf_flow     = ucf::UCF(ucf::FLOW, ctx.options);                 // cfs → display flow
+    // sweeping season (the A7 block's rule)
+    const int sweep_doy = datetime::dayOfYear(abs_time);
+    const int ss = ctx.options.sweep_start, se = ctx.options.sweep_end;
+    const bool in_season = (ss <= se) ? (sweep_doy >= ss && sweep_doy <= se)
+                                      : (sweep_doy >= ss || sweep_doy <= se);
+
+    for (int c = 0; c < n_cells_; ++c) {
+        const auto uc = static_cast(c);
+        const double area_m2 = mesh.tri_area[uc];
+        const double area_la = area_m2 * area_to_landarea_;
+        // m³ the cell produced this step (net outflow, D-A22); a cell that
+        // received more than it passed on made none.
+        const double v_out   = std::max(tr.cell_runoff_vol[uc], 0.0);
+        tr.cell_runoff_vol[uc] = 0.0;
+        runoff_vol_[uc]     += v_out;
+        const double q_ms    = (area_m2 > 0.0) ? v_out / dt_runoff / area_m2 : 0.0;   // m/s
+        const double Q_m3s   = v_out / dt_runoff;
+        const double q_expon = q_ms * q_to_display;
+        const double q_flow  = (Q_m3s / kM3PerFt3) * ucf_flow;
+
+        for (int lu = 0; lu < n_lu_; ++lu) {
+            const double frac = cov_[cidx(c, lu)];
+            if (frac <= 0.0) continue;
+            const double interval = static_cast(lu) < ctx.landuses.sweep_interval.size()
+                                        ? ctx.landuses.sweep_interval[static_cast(lu)] : 0.0;
+            // --- sweeping event for this (cell, land use), the A7 rule -----------
+            bool sweep_now = false;
+            if (!is_raining && in_season && interval > 0.0) {
+                double& ls = last_swept_[cidx(c, lu)];
+                ls += dt_days;
+                if (ls >= interval) { ls = 0.0; sweep_now = true; }
+            }
+            const double removal_frac = sweep_now ? ctx.landuses.sweep_removal[static_cast(lu)] / 100.0 : 0.0;
+
+            for (int s = 0; s < n_sp_; ++s) {
+                const Params& P = param(lu, s);
+                const auto us = static_cast(s);
+                const double mcf  = mcf_[us];
+                const double norm = (P.normalizer == 0) ? frac * area_la : frac * curb_[uc];
+                double& B = bu_[bidx(c, lu, s)];
+
+                // --- buildup accrual (stepSurfaceQuality) ---------------------
+                if (P.bu_type != 0) {
+                    if (P.bu_type == 4) {                                   // EXT
+                        double rate = 0.0;
+                        if (P.ts_idx >= 0 && P.ts_idx < static_cast(ctx.tables.tables.size()))
+                            rate = P.c1 * table_lookup_cursor(
+                                const_cast(ctx.tables.tables[static_cast(P.ts_idx)]), abs_time);
+                        const double nb = std::max(0.0, std::min(B + rate * dt_days, P.c0));
+                        const double change = nb - B;
+                        if (change != 0.0) { B = nb; led_bu_[us] += change * norm; }
+                    } else {
+                        double days = 0.0;
+                        if (B > 0.0) {
+                            switch (P.bu_type) {
+                                case 1: days = (P.c1 * P.c2 > 0.0) ? std::pow(B / P.c1, 1.0 / P.c2) : 0.0; break;
+                                case 2: days = (P.c0 * P.c1 > 0.0 && B < P.c0) ? -std::log(1.0 - B / P.c0) / P.c1 : 0.0; break;
+                                case 3: days = (P.c0 > B) ? B * P.c2 / (P.c0 - B) : P.max_days; break;
+                                default: break;
+                            }
+                        }
+                        days += dt_days;
+                        const double nb = buildupAt(P.bu_type, P.c0, P.c1, P.c2, days);
+                        const double change = nb - B;
+                        B = nb;
+                        if (change > 0.0) led_bu_[us] += change * norm;
+                    }
+                }
+
+                // --- washoff into the cell row (stepSurfaceQuality, SI) ----------
+                if (P.wo_type != 0 && q_ms > kMinRunoffMs) {
+                    // W_row: concentration-units × m³ per second (the row's unit)
+                    double w_row = 0.0;
+                    const double b_mass_row = (mcf > 0.0) ? (B * norm) / mcf / 1000.0 : 0.0;  // user → conc-mass → row
+                    switch (P.wo_type) {
+                        case 3: w_row = P.coeff * Q_m3s; break;                                              // EMC
+                        case 1: if (B > 0.0) w_row = (P.coeff / 3600.0) * std::pow(q_expon, P.expon) * b_mass_row; break;  // EXP
+                        case 2: w_row = P.coeff * std::pow(q_flow, P.expon) / 1000.0; break;                 // RC
+                        default: break;
+                    }
+                    const double max_row = b_mass_row / dt_runoff;
+                    if (w_row > max_row && P.wo_type != 3) w_row = max_row;
+                    const double washed_user = w_row * 1000.0 * mcf * dt_runoff;
+                    if (P.bu_type == 0 && washed_user > B * norm) {
+                        led_bu_[us] += washed_user;          // "no buildup function" ledger branch
+                        B = 0.0;
+                    } else if (norm > 0.0) {
+                        B = std::max(B - washed_user / norm, 0.0);
+                    }
+                    const double bmp_row = w_row * (P.bmp_effic / 100.0);
+                    if (bmp_row > 0.0) { led_bmp_[us] += bmp_row * 1000.0 * mcf * dt_runoff; w_row -= bmp_row; }
+                    if (w_row > 0.0) {
+                        const double dm = w_row * dt_runoff;
+                        const int row = row_of_[us];
+                        tr.cell_mass[tr.idx(row, c)] += dm;
+                        tr.gained_washoff[static_cast(row)] += dm;
+                        led_wo_[us] += dm * 1000.0 * mcf;
+                    }
+                }
+
+                // --- sweeping removal (A7) -----------------------------------------
+                if (sweep_now) {
+                    const double removed = B * removal_frac * (P.sweep_effic / 100.0);
+                    if (removed > 0.0) { B = std::max(B - removed, 0.0); led_sw_[us] += removed * norm; }
+                }
+            }
+        }
+    }
+}
+
+}  // namespace openswmm::twoD
diff --git a/src/engine/2d/quality/SurfaceQuality2D.hpp b/src/engine/2d/quality/SurfaceQuality2D.hpp
new file mode 100644
index 000000000..5f7dd7a5e
--- /dev/null
+++ b/src/engine/2d/quality/SurfaceQuality2D.hpp
@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SurfaceQuality2D.hpp
+ * @brief S7 (2026-09-19) — cell coverages, buildup, washoff and street
+ *        sweeping on the 2D overland surface.
+ *
+ * @details The subcatchment land-use convention on the mesh: a cell (or a
+ *          tag, or the whole mesh) names which EXISTING land uses cover it
+ *          and by what percent; buildup accrues per (cell, land use, surface
+ *          species) with the land use's own `[BUILDUP]` function, is swept on
+ *          the `[LANDUSES]` schedule, and is washed off by the cell's runoff
+ *          into the cell's species row — from where it advects to the 1D
+ *          network with the water. Surface species = pollutants ∪ the
+ *          reactions component's (MSX) species (BW-MSX), keyed by the
+ *          transport row layout, so nothing here is pollutant-shaped.
+ *
+ *          Sections (`[2D_*]` family in the `.inp` for v1; scope keys and the
+ *          1-based CELL index as `[2D_INFILTRATION]` / `[GW_*]`):
+ *
+ *              [2D_COVERAGES]     scope LANDUSE PERCENT [LANDUSE PERCENT]…
+ *              [2D_LOADINGS]      scope SPECIES INITIAL_BUILDUP   (mass / unit area)
+ *              [2D_CURB_LENGTH]   scope LENGTH                    (project length units)
+ *
+ *          scope = `*` | `TAG name` | `CELL n`; GLOBAL < TAG < CELL; a
+ *          coverage row REPLACES the set for its scope (no merging).
+ *
+ *          Cell runoff rate (D-A22, revised 2026-09-19): the cell's NET
+ *          outflow over the runoff step — what left across its faces, open
+ *          boundary edges and drains to nodes, minus what arrived across
+ *          faces, from node spills, outfall discharge and inflow boundaries —
+ *          clamped at zero, per unit area; accumulated by the marcher in
+ *          `SurfaceTransportState::cell_runoff_vol`. That is the runoff the
+ *          cell itself produced (rain excess plus storage release), the cell
+ *          analogue of the subcatchment step's `q = outflow / area`: zero on
+ *          a still pond, zero on a cell that only passes upstream water
+ *          through, and independent of how finely a plane is meshed. (The
+ *          gross outward face flux was considered and rejected: it grows
+ *          with the count of cells upstream, so EMC and RC loads — and EXP's
+ *          rate — would scale with the mesh.) Defined on triangles and quads
+ *          alike.
+ *
+ *          Cadence (D-A26): buildup, washoff and sweeping run at the RUNOFF
+ *          step, right after the subcatchment surface-quality step, so the
+ *          two share one calendar (dry days, sweep season); the washoff mass
+ *          is added to the cell row as a source, which is conservative at any
+ *          cadence.
+ *
+ *          Design: `plans/transport/OVERLAND_TRANSPORT_HEAT_MSX_PLAN_2026-09-01.md`
+ *          §8 (2026-09-19); program plan D-A22–D-A26.
+ *
+ * @ingroup engine_2d
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_QUALITY_SURFACE_QUALITY_2D_HPP
+#define OPENSWMM_ENGINE_2D_QUALITY_SURFACE_QUALITY_2D_HPP
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../input/SectionRegistry.hpp"
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::twoD {
+
+struct MeshData;
+struct SurfaceStateData;
+struct SurfaceTransportState;
+struct SolverOptions2D;
+
+/// Row scope — the `[2D_INFILTRATION]` / `[GW_*]` ladder.
+enum class SqScope : int8_t { GLOBAL = 0, TAG = 1, CELL = 2 };
+
+struct SqScopeKey {
+    SqScope     scope = SqScope::GLOBAL;
+    std::string tag;          ///< TAG rows
+    int         cell  = -1;   ///< CELL rows, 0-based internally (1-based in the file)
+};
+
+/// `[2D_COVERAGES]` — one row = the whole coverage set of its scope.
+struct CoverageRow2D {
+    SqScopeKey key;
+    std::vector> uses;   ///< (land use, percent)
+};
+/// `[2D_LOADINGS]` — initial buildup, user mass per unit land area.
+struct LoadingRow2D {
+    SqScopeKey  key;
+    std::string species;
+    double      value = 0.0;
+};
+/// `[2D_CURB_LENGTH]` — curb length per cell, project length units.
+struct CurbRow2D {
+    SqScopeKey key;
+    double     length = 0.0;
+};
+
+/**
+ * @brief The S7 store: authored rows, resolved per-cell coverages and state,
+ *        and the per-species ledgers.
+ */
+class SurfaceQuality2D {
+public:
+    // ---- authoring (section handlers, C API, writer) -----------------------
+    std::vector coverage_rows;
+    std::vector  loading_rows;
+    std::vector     curb_rows;
+    bool authored() const noexcept {
+        return !coverage_rows.empty() || !loading_rows.empty() || !curb_rows.empty();
+    }
+    void clearRows() { coverage_rows.clear(); loading_rows.clear(); curb_rows.clear(); }
+
+    /**
+     * @brief Bind the rows to the mesh, the land uses and the transport rows.
+     * @return Diagnostics; an entry starting with "ERROR" is fatal (unknown
+     *         land use / species / tag / cell, percent > 100, PER_CURB land
+     *         use without a curb length), the rest are warnings (inert under
+     *         RAINFALL_MODE NONE; double-counting with a covered
+     *         subcatchment).
+     */
+    std::vector resolve(const SimulationContext& ctx, const MeshData& mesh,
+                                     const SurfaceTransportState& tr,
+                                     const SolverOptions2D& opts);
+
+    bool active() const noexcept { return active_; }
+
+    /// Seed initial buildup: `[2D_LOADINGS]` row, else the buildup function
+    /// at `[OPTIONS] DRY_DAYS` (legacy landuse_getInitBuildup).
+    void initState(const SimulationContext& ctx, const MeshData& mesh);
+
+    /**
+     * @brief One runoff step: buildup accrual, washoff into the cell rows,
+     *        street sweeping.
+     * @param dt_runoff  runoff step (s)
+     * @param abs_time   absolute date-time at the START of the step
+     * @param is_raining engine's current-step rainfall flag (sweeping gate)
+     */
+    void step(const SimulationContext& ctx, const MeshData& mesh, SurfaceStateData& state,
+              double dt_runoff, double abs_time, bool is_raining);
+
+    // ---- read-back --------------------------------------------------------
+    int nLandUses() const noexcept { return n_lu_; }
+    int nSpecies()  const noexcept { return n_sp_; }          ///< surface species (rows that build up)
+    int nCells()    const noexcept { return n_cells_; }
+    /// Transport row index of surface species `s` (pollutants first, then MSX).
+    int rowOf(int s) const noexcept { return row_of_[static_cast(s)]; }
+    const std::string& speciesName(int s) const noexcept { return names_[static_cast(s)]; }
+    double coverage(int c, int lu) const noexcept { return cov_[cidx(c, lu)]; }
+    double curbLength(int c) const noexcept { return curb_[static_cast(c)]; }
+    /// Buildup of species s on land use lu of cell c, user mass per normalizer unit.
+    double buildup(int c, int lu, int s) const noexcept { return bu_[bidx(c, lu, s)]; }
+    /// Total buildup of species s on cell c per unit land area (user mass /
+    /// acre or ha) — what the results file reports.
+    double buildupPerArea(int c, int s) const noexcept;
+    /// Per-species ledgers, user mass, cumulative.
+    const std::vector& ledInitBuildup() const noexcept { return led_init_; }
+    const std::vector& ledBuildup()     const noexcept { return led_bu_; }
+    const std::vector& ledWashoff()     const noexcept { return led_wo_; }
+    const std::vector& ledSweeping()    const noexcept { return led_sw_; }
+    const std::vector& ledBmp()         const noexcept { return led_bmp_; }
+    /// Per-species conversion: concentration-mass units → user mass (lbs / kg).
+    double mcf(int s) const noexcept { return mcf_[static_cast(s)]; }
+    /// Cumulative runoff volume (m³) the cell produced (the positive part of
+    /// its net outflow per step, D-A22) — the `q·A·dt` the washoff laws saw.
+    double runoffVolume(int c) const noexcept { return runoff_vol_[static_cast(c)]; }
+
+private:
+    std::size_t cidx(int c, int lu) const noexcept {
+        return static_cast(c) * static_cast(n_lu_) +
+               static_cast(lu);
+    }
+    std::size_t bidx(int c, int lu, int s) const noexcept {
+        return (static_cast(lu) * static_cast(n_sp_) +
+                static_cast(s)) * static_cast(n_cells_) +
+               static_cast(c);
+    }
+    struct Params {   // per (lu, s), read from the 1D tables at resolve
+        int    bu_type = 0; double c0 = 0, c1 = 0, c2 = 0; int ts_idx = -1; int normalizer = 0; double max_days = 0;
+        int    wo_type = 0; double coeff = 0, expon = 0, sweep_effic = 0, bmp_effic = 0;
+    };
+    const Params& param(int lu, int s) const noexcept {
+        return params_[static_cast(lu) * static_cast(n_sp_) +
+                       static_cast(s)];
+    }
+    void loadParams(const SimulationContext& ctx);
+
+    bool active_  = false;
+    int  n_cells_ = 0, n_lu_ = 0, n_sp_ = 0;
+    bool si_ = false;
+    double area_to_landarea_ = 1.0;   ///< m² → acres (US) or ha (SI)
+    std::vector         row_of_;   ///< [s] transport row
+    std::vector names_;    ///< [s]
+    std::vector      mcf_;      ///< [s]
+    std::vector      params_;   ///< [lu * n_sp + s]
+    std::vector      cov_;      ///< [c * n_lu + lu] fraction 0..1
+    std::vector      curb_;     ///< [c] project length units
+    std::vector      area_la_;  ///< [c] cell area in land-area units (acres | ha)
+    std::vector      init_;     ///< [c * n_sp + s] loading, user mass per area (0 = none)
+    std::vector      bu_;       ///< bidx(c, lu, s)
+    std::vector      last_swept_; ///< [c * n_lu + lu] days
+    std::vector      runoff_vol_; ///< [c] m³, cumulative
+    std::vector      led_init_, led_bu_, led_wo_, led_sw_, led_bmp_;   ///< [s] user mass
+};
+
+// ---- section parsers (exposed for tests) -----------------------------------
+std::string parse2DCoveragesLine (const std::vector& tokens, std::vector& rows);
+std::string parse2DLoadingsLine  (const std::vector& tokens, std::vector& rows);
+std::string parse2DCurbLengthLine(const std::vector& tokens, std::vector& rows);
+
+/// Register `[2D_COVERAGES]`, `[2D_LOADINGS]`, `[2D_CURB_LENGTH]` writing into @p sq.
+void registerSurfaceQualitySections(SurfaceQuality2D& sq, input::SectionRegistry& registry);
+
+/// Scope key ↔ file token ("*", "TAG name", "CELL n" — 1-based).
+std::string formatSqScope(const SqScopeKey& k);
+std::string parseSqScope(const std::vector& tokens, std::size_t& at, SqScopeKey& key,
+                         const char* section);
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_QUALITY_SURFACE_QUALITY_2D_HPP
diff --git a/src/engine/2d/solver/DiffusiveKernels.hpp b/src/engine/2d/solver/DiffusiveKernels.hpp
new file mode 100644
index 000000000..ae8ace593
--- /dev/null
+++ b/src/engine/2d/solver/DiffusiveKernels.hpp
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file DiffusiveKernels.hpp
+ * @brief Face law and step bound for MOMENTUM_EQUATION DIFFUSIVE_WAVE
+ *        (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.3).
+ *
+ * @details The explicit diffusive wave of Hunter et al. (2005) /
+ *          LISFLOOD-FP: no inertia, the face discharge is the Manning
+ *          quasi-steady balance of the free-surface slope,
+ *
+ *            q_f = − h_f^{5/3} · S / (n_f · √max(|S|, S_ε)),   S = Δη·inv_dx
+ *
+ *          with the slope regularised below S_ε so the conductance
+ *          h^{5/3}/(n√|S|) cannot diverge on a flat surface (the classic
+ *          explicit-DW failure). The scheme is a nonlinear diffusion
+ *          ∂h/∂t = ∇·(K∇η), K = h^{5/3}/(n√|S|), so the explicit step is
+ *          bounded by Δt ≤ L²/(4K) — the Δx² restriction that the
+ *          local-inertial term exists to remove. It is affordable here only
+ *          because the tiered LTS lets each cell pay its own Δt.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_DIFFUSIVE_KERNELS_HPP
+#define OPENSWMM_ENGINE_2D_DIFFUSIVE_KERNELS_HPP
+
+#include 
+#include 
+
+#ifndef OPENSWMM_KERNEL_FN
+#define OPENSWMM_KERNEL_FN inline
+#endif
+
+namespace openswmm::twoD::diffusive {
+
+/// Manning quasi-steady face discharge (m²/s, positive L→R) for face depth
+/// hf, surface slope S = (η_R − η_L)·inv_dx (positive ⇒ flow R→L), face
+/// Manning n_f and slope floor s_eps.
+OPENSWMM_KERNEL_FN double faceDischarge(double hf, double slope, double nf,
+                                        double s_eps) noexcept {
+    if (!(hf > 0.0) || !(nf > 0.0) || slope == 0.0) return 0.0;
+    const double h53 = hf * std::cbrt(hf * hf);
+    const double sa  = std::fabs(slope);
+    const double sr  = std::sqrt((sa > s_eps) ? sa : s_eps);
+    return -h53 * slope / (nf * sr);
+}
+
+/// Explicit-diffusion step bound for a cell of characteristic length L,
+/// depth h, Manning n and the largest face slope |S| among its faces (floored
+/// at s_eps): Δt = α · L² · n · √S / (4 · h^{5/3}). Returns a huge value for a
+/// dry cell.
+OPENSWMM_KERNEL_FN double cellDiffusiveDt(double alpha, double lchar, double h,
+                                          double n, double slope_abs,
+                                          double s_eps) noexcept {
+    if (!(h > 0.0)) return 1.0e30;
+    const double h53 = h * std::cbrt(h * h);
+    const double s   = (slope_abs > s_eps) ? slope_abs : s_eps;
+    return alpha * lchar * lchar * n * std::sqrt(s) / (4.0 * h53);
+}
+
+} // namespace openswmm::twoD::diffusive
+
+#endif // OPENSWMM_ENGINE_2D_DIFFUSIVE_KERNELS_HPP
diff --git a/src/engine/2d/solver/ExplicitInertialSolver.cpp b/src/engine/2d/solver/ExplicitInertialSolver.cpp
index e7a961178..6c4d9e18d 100644
--- a/src/engine/2d/solver/ExplicitInertialSolver.cpp
+++ b/src/engine/2d/solver/ExplicitInertialSolver.cpp
@@ -14,7 +14,7 @@
  *          construction (same FP products, booked at different times).
  *
  *          Positivity: at face cadence each exporting face is capped at
- *          (β/3)·V of its exporting cell, so a cell's ≤ 3 outgoing faces can
+ *          (β/nv)·V of its exporting cell, so a cell's ≤ nv outgoing faces can
  *          take at most β·V per own-step — V ≥ 0 without any cross-face
  *          coordination (exact at K = 1 where V is fresh every substep; the
  *          α-margin covers within-cycle depth drift for K > 1, with a
@@ -25,17 +25,27 @@
  */
 
 #include "ExplicitInertialSolver.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+
+#include "../subsurface/SubsurfaceSolver.hpp"
 
 #include 
 #include 
+#if defined(SWMM_USE_OPENMP)
+#include 
+#endif
 #include 
 #include 
+#include    // std::runtime_error ([2D_BOUNDARY_QUALITY] resolve)
+#include       // std::to_string
 
 #include "../data/MeshData.hpp"
 #include "../data/SolverOptions2D.hpp"
 #include "../data/SurfaceStateData.hpp"
 #include "../data/BoundaryData.hpp"
 #include "InertialKernels.hpp"
+#include "SweKernels.hpp"
+#include "DiffusiveKernels.hpp"
 #include "SurfaceFluxCalculator.hpp"   // evapSink, computeBoundaryEdgeFlux
 #include "../coupling/NodeCoupling.hpp"  // computeNodeCouplingQ (live exchange)
 #include "../../data/NodeData.hpp"
@@ -47,6 +57,10 @@ namespace {
 /// lists are frozen and inactive cells accumulate their (rain / held-coupling)
 /// sources lazily — this is where rain-on-grid thin films become near-free.
 constexpr int kRebuildEveryCycles = 4;
+/// Halo depth (rings) when FRONT_REBUILD is on — enough for a 2√(gh) front
+/// to cross a macro cycle of 2^(K−1) base substeps at CFL ½ (K = 4 ⇒ ~3–4
+/// cells). The breach flag then triggers the rebuild at the next cycle.
+constexpr int kFrontHaloRings = 5;
 }  // namespace
 
 void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
@@ -64,9 +78,99 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
     facc_L_.assign(ne, 0.0);
     facc_R_.assign(ne, 0.0);
     face_tier_.assign(ne, 0);
+
+    // Momentum closure (MOMENTUM_EQUATION). FULL_SWE carries cell momentum
+    // accumulators and a positivity-safe CFL; DIFFUSIVE_WAVE carries the
+    // per-cell slope its Δx² step bound needs.
+    mode_ = opts.momentum;
+    second_order_ = false;
+    macc_x_L_.clear(); macc_x_R_.clear(); macc_y_L_.clear(); macc_y_R_.clear();
+    dw_slope_.clear();
+    if (mode_ == Momentum2D::FULL_SWE) {
+        macc_x_L_.assign(ne, 0.0); macc_x_R_.assign(ne, 0.0);
+        macc_y_L_.assign(ne, 0.0); macc_y_R_.assign(ne, 0.0);
+        // First-order Godunov with hydrostatic reconstruction is positivity-
+        // preserving at Courant ≤ ½ on triangles/quads; the β-share is the
+        // backstop, not the guarantee, so the bound is enforced here.
+        if (opts.cfl_number > 0.5) {
+            std::fprintf(stderr,
+                "[openswmm 2D] MOMENTUM_EQUATION FULL_SWE: CFL_NUMBER %.3g "
+                "reduced to 0.5 (positivity bound of the Godunov update).\n",
+                opts.cfl_number);
+            opts.cfl_number = 0.5;
+        }
+        if (opts.reconstruction_order == 2 && opts.lts_tiers > 1) {
+            std::fprintf(stderr,
+                "[openswmm 2D] RECONSTRUCTION_ORDER 2 runs in global-dt mode: "
+                "LTS_TIERS %d reduced to 1.\n", opts.lts_tiers);
+            opts.lts_tiers = 1;
+        }
+        second_order_ = (opts.reconstruction_order == 2);
+        if (second_order_ && state.transport.active()) {
+            std::fprintf(stderr,
+                "[openswmm 2D] RECONSTRUCTION_ORDER 2 with overland transport "
+                "is not supported yet; using first order.\n");
+            second_order_ = false;
+        }
+        if (second_order_) {
+            const auto un = static_cast(nt);
+            gex_.assign(un, 0.0); gey_.assign(un, 0.0);
+            gux_.assign(un, 0.0); guy_.assign(un, 0.0);
+            gvx_.assign(un, 0.0); gvy_.assign(un, 0.0);
+        } else {
+            gex_.clear(); gey_.clear(); gux_.clear(); guy_.clear(); gvx_.clear(); gvy_.clear();
+        }
+    } else if (mode_ == Momentum2D::DIFFUSIVE_WAVE) {
+        dw_slope_.assign(static_cast(nt), 0.0);
+    }
+    // FRONT_REBUILD AUTO: on for FULL_SWE only. A Godunov front travels
+    // ~2√(gh) and can cross the 1-ring halo inside the 4-cycle cadence; a
+    // diffusive-wave front cannot (its Δx²-bounded step moves it a fraction
+    // of a cell per cycle), so DIFFUSIVE_WAVE keeps LI's cheap cadence
+    // (2D_PERF_REGRESSION_DIAGNOSIS §4 fix 3).
+    front_rebuild_ = (opts.front_rebuild < 0)
+        ? (mode_ == Momentum2D::FULL_SWE)
+        : (opts.front_rebuild != 0);
+    frontier_.assign(front_rebuild_ ? static_cast(nt) : 0, 0);
+    front_breach_ = false;
+    // Resolved once: MeshData::n_quads() is an O(n_cells) scan (F1).
+    has_quads_ = mesh.n_quads() > 0;
+    // FULL_SWE: WALL boundary slots per cell, CSR (F5). Slot order within a
+    // cell is ascending k, the order the per-cell scan used to visit them.
+    wall_ptr_.clear(); wall_slot_.clear();
+    if (mode_ == Momentum2D::FULL_SWE) {
+        wall_ptr_.reserve(static_cast(nt) + 1);
+        wall_ptr_.push_back(0);
+        for (int i = 0; i < nt; ++i) {
+            const int nvc = mesh.cell_vertex_count(i);
+            for (int k2 = 0; k2 < nvc; ++k2) {
+                if (mesh.cell_neighbour(i, k2) >= 0) continue;
+                const int slot = MeshData::slot(i, k2);
+                if (state.boundary &&
+                    static_cast(state.boundary->edge_bc_type[slot]) !=
+                        BoundaryType::WALL)
+                    continue;
+                wall_slot_.push_back(slot);
+            }
+            wall_ptr_.push_back(static_cast(wall_slot_.size()));
+        }
+    }
+    // S1: species accumulators, sized only when transport is live so a
+    // hydrodynamics-only model allocates nothing here.
+    species_on_ = state.transport.active();   // S7: see the member note
+    if (species_on_) {
+        const auto ns = static_cast(state.transport.n_species);
+        sacc_L_.assign(ns * ne, 0.0);
+        sacc_R_.assign(ns * ne, 0.0);
+    } else {
+        sacc_L_.clear();
+        sacc_R_.clear();
+    }
     // The Perot cell vectors serve the θ-blend AND the convective term, so
-    // ADVECTION forces them on even at θ = 1.
-    if (opts.theta < 1.0 || opts.advection) {
+    // ADVECTION forces them on even at θ = 1. FULL_SWE uses the same arrays
+    // as its prognostic cell momentum.
+    qcx_.clear(); qcy_.clear();
+    if (opts.theta < 1.0 || opts.advection || mode_ == Momentum2D::FULL_SWE) {
         qcx_.assign(static_cast(nt), 0.0);
         qcy_.assign(static_cast(nt), 0.0);
     }
@@ -82,13 +186,12 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
     bc_slot_.clear();
     if (state.boundary) {
         for (int i = 0; i < nt; ++i) {
-            for (int e = 0; e < 3; ++e) {
-                const int idx = i * 3 + e;
+            const int nvc = mesh.cell_vertex_count(i);
+            for (int e = 0; e < nvc; ++e) {
+                const int idx = MeshData::slot(i, e);
                 const auto ty =
                     static_cast(state.boundary->edge_bc_type[idx]);
-                const bool interior = (e == 0   ? mesh.tri_nbr0[i]
-                                       : e == 1 ? mesh.tri_nbr1[i]
-                                                : mesh.tri_nbr2[i]) >= 0;
+                const bool interior = mesh.cell_neighbour(i, e) >= 0;
                 if (!interior && ty != BoundaryType::WALL) {
                     bc_cell_.push_back(i);
                     bc_slot_.push_back(idx);
@@ -99,6 +202,31 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
     bc_accum_.assign(bc_cell_.size(), 0.0);
     bc_q_.assign(bc_cell_.size(), 0.0);
 
+    // S2: resolve [2D_BOUNDARY_QUALITY] rows onto THIS solver's boundary-edge
+    // list. bc_conc is [bc_slot * ns + s]; a row naming an edge that is not a
+    // non-WALL boundary edge cannot take effect and is fatal (a WALL admits
+    // no water, so a concentration on it describes nothing).
+    if (state.transport.active()) {
+        auto& tr = state.transport;
+        const auto ns = static_cast(tr.n_species);
+        tr.bc_conc.assign(bc_cell_.size() * ns, 0.0);
+        for (const auto& row : tr.bc_quality_rows) {
+            std::size_t k = 0;
+            bool found = false;
+            for (; k < bc_slot_.size(); ++k)
+                if (bc_slot_[k] == row.slot) { found = true; break; }
+            if (!found)
+                throw std::runtime_error(
+                    "[2D_BOUNDARY_QUALITY] edge slot " + std::to_string(row.slot) +
+                    " is not a non-WALL boundary edge, so its concentration "
+                    "could never enter the mesh.");
+            if (row.species < 0 || static_cast(row.species) >= ns)
+                throw std::runtime_error(
+                    "[2D_BOUNDARY_QUALITY] species index out of range.");
+            tr.bc_conc[k * ns + static_cast(row.species)] = row.conc;
+        }
+    }
+
     // Live junction exchange (windowless coupling): one ∫Q dt accumulator per
     // point; spill budget tracked per 1D node. Their cells pin to tier 0 (the
     // exchange forcing changes at the fastest cadence), as do BC cells.
@@ -124,7 +252,13 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
         bool any_uv = false;
         for (int i = 0; i < nt && !any_uv; ++i)
             any_uv = mesh.tri_init_u[i] != 0.0 || mesh.tri_init_v[i] != 0.0;
-        if (any_uv) {
+        if (any_uv && mode_ == Momentum2D::FULL_SWE) {
+            // Cell momentum seeds directly: q⃗ = h·u⃗ (nothing on the faces).
+            for (int i = 0; i < nt; ++i) {
+                qcx_[i] = state.depth[i] * mesh.tri_init_u[i];
+                qcy_[i] = state.depth[i] * mesh.tri_init_v[i];
+            }
+        } else if (any_uv) {
             for (int e = 0; e < edges_.ne; ++e) {
                 const int a = edges_.cL[e], b = edges_.cR[e];
                 const double qax = state.depth[a] * mesh.tri_init_u[a];
@@ -142,7 +276,7 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
                     double sx = 0.0, sy = 0.0;
                     for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
                         const int    e = ed.cell_edge[p];
-                        const double fq = ed.cell_sign[p] * q_[e] * ed.xi[e];
+                        const double fq = static_cast(ed.cell_sign[p]) * q_[e] * ed.xi[e];
                         sx += fq * (ed.mx[e] - mesh.tri_cx[i]);
                         sy += fq * (ed.my[e] - mesh.tri_cy[i]);
                     }
@@ -157,11 +291,139 @@ void ExplicitInertialSolver::initialize(MeshData& mesh, SurfaceStateData& state,
     substeps_run_ = face_passes_ = last_steps_ = 0;
     last_dt_ = 0.0;
     telemetry_.clear();
+    active_frac_min_ = 1.0e30; active_frac_max_ = -1.0e30;
+    active_frac_sum_ = 0.0;    active_samples_  = 0;
     if (const char* p = std::getenv("OPENSWMM_2D_MARCHER_TELEMETRY"))
         telemetry_path_ = p;
     initialized_ = true;
 }
 
+double ExplicitInertialSolver::donorConc(int s, int cell) const noexcept {
+    const auto& tr = state_->transport;
+    const double v = state_->volume[static_cast(cell)];
+    // Guard on V > 0 ONLY — deliberately NOT on the dry-depth threshold.
+    // A face fires when its FACE depth (from the two heads) exceeds
+    // dry_depth, which near a front can happen while the exporter's cell
+    // VOLUME sits below dry_depth·area. A depth-based guard here would let
+    // that face export water at zero species, concentrating what stays
+    // behind and breaking the uniform-concentration property exactly at the
+    // wet/dry front — where gate 1 looks hardest. The positivity share
+    // already bounds every take at β·V, so any V > 0 can export and its
+    // concentration is simply m/V. (The REPORTED concentration keeps the
+    // dry threshold: that is a display choice, this is a flux.)
+    if (!(v > 0.0)) return 0.0;
+    return tr.cell_mass[tr.idx(s, cell)] / v;
+}
+
+void ExplicitInertialSolver::sinkMassAtCellConc(int i, double dv_m3,
+                                                std::vector& ledger,
+                                                double* per_point_ledger)
+    noexcept {
+    if (!(dv_m3 > 0.0)) return;
+    auto& tr = state_->transport;
+    if (!tr.active()) return;
+    // S7 (D-A22): water leaving through an open edge or a drain to a node
+    // is runoff the cell produced; infiltration is not (it does not wash off).
+    if (!tr.cell_runoff_vol.empty() && &ledger != &tr.lost_infiltration)
+        tr.cell_runoff_vol[static_cast(i)] += dv_m3;
+    // Concentration is read BEFORE the volume was reduced (callers pass the
+    // pre-sink volume through state_->volume unchanged until after this
+    // call), so the mass removed is exactly dv * c_old — the mass the water
+    // that left was carrying.
+    for (int s = 0; s < tr.n_species; ++s) {
+        const double c  = donorConc(s, i);
+        if (c == 0.0) continue;
+        const double dm = dv_m3 * c;
+        double& m = tr.cell_mass[tr.idx(s, i)];
+        // Cannot remove more than is there (the volume clamps identically);
+        // the residual is a rounding artefact, not a modelling event. The
+        // SIGNED temperature row (S4) has no floor: °C·m³ below zero is a
+        // state, and "min(dm, m)" on two negatives would empty the row.
+        const double taken = tr.signedRow(s) ? dm : ((dm < m) ? dm : m);
+        m -= taken;
+        ledger[static_cast(s)] += taken;
+        if (per_point_ledger) per_point_ledger[s] += taken;
+    }
+}
+
+void ExplicitInertialSolver::gwInfiltrationSeam(int i, double infil_m3) noexcept {
+    auto& tr = state_->transport;
+    if (!tr.active()) return;
+    // No aquifer, or an aquifer that transports nothing: infiltration is a
+    // LOSS, exactly as it was before T7.1, and the ledger keeps saying so.
+    const bool to_gw = gw_ != nullptr && gw_->transport().active();
+    if (!to_gw) {
+        sinkMassAtCellConc(i, infil_m3, tr.lost_infiltration);
+        return;
+    }
+    // Otherwise it is a TRANSFER: the surface still books what it lost, and
+    // the aquifer gains the same number, read as the ledger's own delta so
+    // the two can never disagree.
+    const int ns = std::min(tr.n_species, gw_->transport().n_species);
+    std::vector& led = tr.lost_infiltration;
+    static thread_local std::vector before;
+    before.assign(led.begin(), led.begin() + ns);
+    sinkMassAtCellConc(i, infil_m3, led);
+    for (int s = 0; s < ns; ++s) {
+        const double dm = led[static_cast(s)] -
+                          before[static_cast(s)];
+        if (dm != 0.0) gw_->bookInfiltrationMass(i, s, dm);
+    }
+}
+
+void ExplicitInertialSolver::addRainMass(int i, double rain_m3) noexcept {
+    if (!(rain_m3 > 0.0)) return;
+    auto& tr = state_->transport;
+    if (!tr.active() || tr.rain_conc.empty()) return;
+    for (int s = 0; s < tr.n_species; ++s) {
+        const auto us = static_cast(s);
+        if (us >= tr.rain_conc.size() || tr.rain_conc[us] == 0.0) continue;
+        const double g = rain_m3 * tr.rain_conc[us];
+        tr.cell_mass[tr.idx(s, i)] += g;
+        tr.gained_rainfall[us] += g;
+    }
+}
+
+void ExplicitInertialSolver::sinkIntensiveRowsWithEvap(int i, double evap_m3) noexcept {
+    // Evaporation removes WATER and no solute (S1: concentrations rise), but
+    // it removes water AT the water's temperature AND at the water's age: the
+    // temperature row is a temperature-volume and the age row an age-volume,
+    // so leaving either untouched while the volume falls would heat the cell
+    // — or age it — by evaporating it. Sink both rows at the cell's own mean;
+    // no ledger — the enthalpy left with the vapour and the 1D engines book
+    // nothing for it either (H1's convention), and the mean age of what
+    // remains is unchanged (the 1D water-age convention, WaterAgeLegacy
+    // "no evap factor"; program plan D-A20, S4b).
+    if (!(evap_m3 > 0.0)) return;
+    auto& tr = state_->transport;
+    if (!tr.active()) return;
+    const double v = state_->volume[i];
+    if (!(v > 0.0)) return;
+    const double dv = (evap_m3 < v) ? evap_m3 : v;
+    const int rows[2] = { tr.temp_row, tr.age_row };
+    for (const int r : rows) {
+        if (r < 0) continue;
+        double& m = tr.cell_mass[tr.idx(r, i)];
+        m -= dv * (m / v);
+    }
+}
+
+void ExplicitInertialSolver::addCouplingSourceMass(int i, double area_dt) noexcept {
+    if (!(state_->coupling_flux[i] > 0.0) || !(area_dt > 0.0)) return;
+    auto& tr = state_->transport;
+    if (!tr.active()) return;
+    // S7 (D-A22): discharged / prescribed inflow is not runoff the cell made.
+    if (!tr.cell_runoff_vol.empty())
+        tr.cell_runoff_vol[static_cast(i)] -= state_->coupling_flux[i] * area_dt;
+    if (tr.coupling_src.empty()) return;
+    for (int s = 0; s < tr.n_species; ++s) {
+        const double g = tr.coupling_src[tr.idx(s, i)] * area_dt;
+        if (g == 0.0) continue;
+        tr.cell_mass[tr.idx(s, i)] += g;
+        tr.gained_coupling[static_cast(s)] += g;
+    }
+}
+
 void ExplicitInertialSolver::reconstructAll() {
     const int nt = mesh_->n_triangles();
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
@@ -172,6 +434,14 @@ void ExplicitInertialSolver::reconstructAll() {
 }
 
 void ExplicitInertialSolver::settleAccumulators() {
+    // G1: the subsurface settles on the SAME trigger and for the same
+    // reason. A re-tier re-indexes the tier lists, so any volume still
+    // sitting in a side accumulator would be gathered by a cell that no
+    // longer fires at that cadence — the stranded-flux hazard. Done first so
+    // Dunne water settled here is visible to the surface pass below.
+    if (gw_) { gw_->settle(*state_); gw_->compactPending(); }
+    if (!accumulators_pending_) return;
+    accumulators_pending_ = false;
     const int nt = mesh_->n_triangles();
     const auto& ed = edges_;
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
@@ -179,7 +449,7 @@ void ExplicitInertialSolver::settleAccumulators() {
         double pending = 0.0;
         for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
             const int e = ed.cell_edge[p];
-            if (ed.cell_sign[p] > 0.0) {
+            if (ed.cell_sign[p] > 0) {
                 pending += facc_L_[e];
                 facc_L_[e] = 0.0;
             } else {
@@ -187,6 +457,55 @@ void ExplicitInertialSolver::settleAccumulators() {
                 facc_R_[e] = 0.0;
             }
         }
+        // S1: settle the species side in the SAME sweep. A cell re-tiered
+        // or deactivated with a pending species accumulator would strand
+        // mass exactly as the header warns for volume.
+        if (species_on_) {
+            auto& tr = state_->transport;
+            const auto ns  = static_cast(tr.n_species);
+            const auto nef = static_cast(ed.ne);
+            for (std::size_t s = 0; s < ns; ++s) {
+                double dm = 0.0;
+                for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+                    const auto e = static_cast(ed.cell_edge[p]);
+                    if (ed.cell_sign[p] > 0) {
+                        dm += sacc_L_[s * nef + e]; sacc_L_[s * nef + e] = 0.0;
+                    } else {
+                        dm += sacc_R_[s * nef + e]; sacc_R_[s * nef + e] = 0.0;
+                    }
+                }
+                if (dm != 0.0) {
+                    double& m = tr.cell_mass[tr.idx(static_cast(s), i)];
+                    m += dm;
+                    // Backstop is for nonnegative rows only: the SIGNED
+                    // temperature row holds °C·m³ below zero as a state.
+                    if (m < 0.0 && !tr.signedRow(static_cast(s))) m = 0.0;
+                }
+            }
+        }
+        // FULL_SWE: settle the MOMENTUM accumulators in the same sweep, for
+        // the same reason as the species rows above — a cell re-tiered or
+        // deactivated between its firings would otherwise strand the momentum
+        // of mass that has already been applied, and pick it up stale on
+        // reactivation.
+        if (!macc_x_L_.empty()) {
+            double dmx = 0.0, dmy = 0.0;
+            for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+                const int e = ed.cell_edge[p];
+                if (ed.cell_sign[p] > 0) {
+                    dmx += macc_x_L_[e]; macc_x_L_[e] = 0.0;
+                    dmy += macc_y_L_[e]; macc_y_L_[e] = 0.0;
+                } else {
+                    dmx += macc_x_R_[e]; macc_x_R_[e] = 0.0;
+                    dmy += macc_y_R_[e]; macc_y_R_[e] = 0.0;
+                }
+            }
+            if (dmx != 0.0 || dmy != 0.0) {
+                const double A = mesh_->tri_area[i];
+                qcx_[i] += dmx / A;      // same normalisation as fireCells
+                qcy_[i] += dmy / A;
+            }
+        }
         if (pending == 0.0) continue;
         double v = state_->volume[i] + pending;
         state_->volume[i] = (v > 0.0) ? v : 0.0;
@@ -202,11 +521,46 @@ void ExplicitInertialSolver::lazySourcesOnly(double t) {
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
     for (int i = 0; i < nt; ++i) {
         if (cell_active_[i]) continue;
+        const double infil = infilSink(state_->infil_rate[i], state_->depth[i],
+                                       opts_->dry_depth);
+        // Book before the early-out: rain exactly cancelling the sink leaves
+        // src == 0, but water still infiltrated and the ledger counts the rain.
+        state_->infil_applied[i] += infil * dt_lazy;
+        // T7.1 (2026-09-20): …and hand it to the aquifer, which this pass
+        // never did. `syncAndRebuild`'s lazy pass books it (G1-c item 1);
+        // THIS one — the cheaper alternative taken on every non-rebuild
+        // cycle — infiltrated the water, counted it as an exit on the
+        // surface, and dropped it. The deck's continuity still closed,
+        // because a loss is a loss; the aquifer simply never received
+        // 1.4 % of its recharge on the gate deck. Found by T7.1's seam
+        // gate: the species could not balance while the water did not.
+        if (gw_ && infil > 0.0)
+            gw_->bookInfiltrationFromSurface(i, infil * dt_lazy *
+                                                    mesh_->tri_area[i]);
+        // Signed per-cell coupling volume, booked at the SAME dt the sink
+        // below integrates. Also before the early-out: a spill exactly
+        // cancelled by evaporation leaves src == 0 while water still crossed
+        // the coupling point, and an accumulator that misses those cells
+        // cannot be reconciled against the domain totals.
+        if (state_->coupling_flux[i] != 0.0)
+            state_->coupling_applied[i] +=
+                state_->coupling_flux[i] * dt_lazy * mesh_->tri_area[i];
+        const double evap =
+            evapSink(state_->evap_rate[i], state_->depth[i], opts_->dry_depth);
         const double src =
-            state_->rainfall[i] + state_->coupling_flux[i]
-            - evapSink(state_->evap_rate[i], state_->depth[i],
-                       opts_->dry_depth);
+            state_->rainfall[i] + state_->coupling_flux[i] - evap - infil;
         if (src == 0.0) continue;
+        if (species_on_) {   // S1: see syncAndRebuild's lazy pass
+            auto& tr = state_->transport;
+            const double area = mesh_->tri_area[i];
+            sinkIntensiveRowsWithEvap(i, evap * dt_lazy * area);        // S4/S4b
+            gwInfiltrationSeam(i, infil * dt_lazy * area);              // T7.1
+            if (state_->coupling_flux[i] < 0.0)
+                sinkMassAtCellConc(i, -state_->coupling_flux[i] * dt_lazy *
+                                          area, tr.lost_coupling);
+            addRainMass(i, state_->rainfall[i] * dt_lazy * area);   // S2
+            addCouplingSourceMass(i, dt_lazy * area);                // S3
+        }
         double v = state_->volume[i] + dt_lazy * src * mesh_->tri_area[i];
         state_->volume[i] = (v > 0.0) ? v : 0.0;
         inertial::cellEtaDepth(*mesh_, *opts_, i, state_->volume[i],
@@ -226,11 +580,45 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
         for (int i = 0; i < nt; ++i) {
             if (cell_active_[i]) continue;
+            const double infil = infilSink(state_->infil_rate[i],
+                                           state_->depth[i], opts_->dry_depth);
+            state_->infil_applied[i] += infil * dt_lazy;
+            if (state_->coupling_flux[i] != 0.0)
+                state_->coupling_applied[i] +=
+                    state_->coupling_flux[i] * dt_lazy * mesh_->tri_area[i];
+            // G1: the lazy tier infiltrates too, so its water must reach the
+            // aquifer on the same terms as an active cell's. Omitting this
+            // loses most of the recharge on a rain-on-grid deck, where the
+            // majority of cells sit below h_move for the whole storm and are
+            // never active — and loses it silently, since infil_applied still
+            // books it as an exit. The return direction needs nothing here:
+            // a cell the aquifer owes water to is seeded active by the pass
+            // below, so it takes it back through fireCellsImpl.
+            if (gw_ && infil > 0.0)
+                gw_->bookInfiltrationFromSurface(
+                    i, infil * dt_lazy * mesh_->tri_area[i]);
+            const double evap = evapSink(state_->evap_rate[i],
+                                         state_->depth[i], opts_->dry_depth);
             const double src =
-                state_->rainfall[i] + state_->coupling_flux[i]
-                - evapSink(state_->evap_rate[i], state_->depth[i],
-                           opts_->dry_depth);
+                state_->rainfall[i] + state_->coupling_flux[i] - evap - infil;
             if (src == 0.0) continue;
+            // S1: the lazy tier moves water without faces; the sinks still
+            // carry the cell's species out (same rule as fireCells).
+            if (species_on_) {
+                auto& tr = state_->transport;
+                const double area = mesh_->tri_area[i];
+                sinkIntensiveRowsWithEvap(i, evap * dt_lazy * area);    // S4/S4b
+                // T7.1: the lazy tier hands its infiltration mass down the
+                // same way the active one does — a cell that only ever
+                // fires lazily would otherwise send the aquifer water with
+                // no species in it.
+                gwInfiltrationSeam(i, infil * dt_lazy * area);
+                if (state_->coupling_flux[i] < 0.0)
+                    sinkMassAtCellConc(i, -state_->coupling_flux[i] * dt_lazy *
+                                              area, tr.lost_coupling);
+                addRainMass(i, state_->rainfall[i] * dt_lazy * area);   // S2
+                addCouplingSourceMass(i, dt_lazy * area);                // S3
+            }
             double v = state_->volume[i] + dt_lazy * src * mesh_->tri_area[i];
             state_->volume[i] = (v > 0.0) ? v : 0.0;
             inertial::cellEtaDepth(*mesh_, *opts_, i, state_->volume[i],
@@ -250,8 +638,10 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
     //    default h_move = 0.003 (band = 1 mm either way).
     const double band  = std::min(0.001, 0.5 * opts_->h_move);
     const double h_on  = opts_->h_move + band;
+    h_on_front_ = h_on;
     const double h_off = std::max(0.0, opts_->h_move - band);
-    std::vector next(static_cast(nt), 0);
+    rebuild_seed_.assign(static_cast(nt), 0);
+    std::vector& next = rebuild_seed_;
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
     for (int i = 0; i < nt; ++i) {
         const double thresh = cell_active_[i] ? h_off : h_on;
@@ -260,6 +650,19 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
             next[i] = 1;
     }
 
+    // G1: a cell the aquifer owes water to must route it. Exfiltration and
+    // Dunne excess are booked into the subsurface's xacc_to_surface and
+    // drained by the SURFACE cell's firing — so a dry cell above a rising
+    // table would hold that water forever, because on a dry bed nothing else
+    // ever activates it. This is the one seed that does not come from the
+    // surface's own state. Serial: the list is short (cells that saturated),
+    // and settleAccumulators() above already compacted it, so every entry is
+    // still owed.
+    if (gw_) {
+        for (const int i : gw_->pendingSurfaceCells())
+            if (i >= 0 && i < nt) next[static_cast(i)] = 1;
+    }
+
     // 3. One-ring halo so fronts can enter their neighbours within a rebuild
     //    period, then compact the work lists. A face flows only when BOTH
     //    incident cells are active — a one-sided face would export volume into
@@ -271,29 +674,105 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
         if (next[a] && !next[b]) cell_active_[b] = 1;
         else if (next[b] && !next[a]) cell_active_[a] = 1;
     }
+    // FRONT_REBUILD: a dry-bed front travels ~2√(gh) — about one cell per
+    // base substep at CFL ½ — so between two macro cycles it can cross
+    // several rings. Widen the halo so the front never runs out of active
+    // receiving cells before the breach-triggered rebuild lands.
+    if (front_rebuild_) {
+        // Cell-parallel Jacobi rings (each thread writes only its own cell,
+        // reading the previous ring's copy): the same set as the serial
+        // edge walk produced, without the O(n_edges) serial passes.
+        for (int ring = 1; ring < kFrontHaloRings; ++ring) {
+            rebuild_seed_ = cell_active_;
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+            for (int i = 0; i < nt; ++i) {
+                if (rebuild_seed_[i]) continue;
+                const int nvc = mesh_->cell_vertex_count(i);
+                for (int k2 = 0; k2 < nvc; ++k2) {
+                    const int j = mesh_->cell_neighbour(i, k2);
+                    if (j >= 0 && rebuild_seed_[j]) { cell_active_[i] = 1; break; }
+                }
+            }
+        }
+    }
     active_cells_.clear();
     for (int i = 0; i < nt; ++i)
         if (cell_active_[i]) active_cells_.push_back(i);
+    if (front_rebuild_) {
+        // Outer ring of the halo: an active cell with an inactive neighbour.
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+        for (int i = 0; i < nt; ++i) {
+            uint8_t f = 0;
+            if (cell_active_[i]) {
+                const int nvc = mesh_->cell_vertex_count(i);
+                for (int k2 = 0; k2 < nvc; ++k2) {
+                    const int j = mesh_->cell_neighbour(i, k2);
+                    if (j >= 0 && !cell_active_[j]) { f = 1; break; }
+                }
+            }
+            frontier_[i] = f;
+        }
+        front_breach_ = false;
+    }
 
     // 4. Tier assignment from the local CFL step. Pinned to tier 0: cells with
     //    concentrated sources (coupling points) and boundary cells — their
     //    forcing changes fastest. dt0_ = the finest active requirement.
-    const int K = static_cast(cells_by_tier_.size());
+    const int K  = static_cast(cells_by_tier_.size());
+    const int na = static_cast(active_cells_.size());
+    if (mode_ == Momentum2D::DIFFUSIVE_WAVE) refreshDiffusiveSlopes();
     dt0_ = 1.0e30;
-    std::vector dt_cell(active_cells_.size());
-    for (std::size_t k = 0; k < active_cells_.size(); ++k) {
-        const int i = active_cells_[k];
-        const double h = state_->depth[i];
-        double speed = 0.0;
-        if (!qcx_.empty() && h > 1.0e-6)
-            speed = std::hypot(qcx_[i], qcy_[i]) / h;
-        double dt = (h > opts_->dry_depth)
-                        ? inertial::cellCflDt(opts_->cfl_number,
-                                              edges_.cell_lchar[i], h, speed)
-                        : 1.0e30;
-        dt = std::min(dt, opts_->max_timestep);
-        dt_cell[k] = dt;
-        dt0_ = std::min(dt0_, dt);
+    rebuild_dt_cell_.resize(static_cast(na));
+    std::vector& dt_cell = rebuild_dt_cell_;
+    // Parallel, exactly like its twin refreshDt0(): each iteration writes only
+    // dt_cell[k], and the min is folded from per-thread partials. min over
+    // doubles is exact and order-independent, so the partition cannot change
+    // dt0_ — this was the longest serial stretch of the rebuild.
+    const int nthr = std::max(1, opts_->num_threads);
+    rebuild_dt_partial_.assign(static_cast(nthr), 1.0e30);
+#pragma omp parallel num_threads(nthr)
+    {
+#if defined(SWMM_USE_OPENMP)
+        const int tid = omp_get_thread_num();
+#else
+        const int tid = 0;
+#endif
+        double local = 1.0e30;
+#pragma omp for schedule(static) nowait
+        for (int k = 0; k < na; ++k) {
+            const int i = active_cells_[static_cast(k)];
+            const double h = state_->depth[i];
+            double speed = 0.0;
+            if (!qcx_.empty() && h > 1.0e-6)
+                speed = inertial::qMagnitude(qcx_[i], qcy_[i]) / h;
+            double dt = (h > opts_->dry_depth)
+                            ? inertial::cellCflDt(opts_->cfl_number,
+                                                  (mode_ == Momentum2D::FULL_SWE)
+                                                      ? edges_.cell_lpos[i]
+                                                      : edges_.cell_lchar[i],
+                                                  h, speed)
+                            : 1.0e30;
+            if (mode_ == Momentum2D::DIFFUSIVE_WAVE && h > opts_->dry_depth)
+                dt = diffusive::cellDiffusiveDt(
+                    opts_->cfl_number, edges_.cell_lchar[i], h,
+                    mesh_->mannings_n[i], dw_slope_[i],
+                    opts_->flux_dh_eps / std::max(edges_.cell_lchar[i], 1.0e-9));
+            dt = std::min(dt, opts_->max_timestep);
+            dt_cell[static_cast(k)] = dt;
+            if (dt < local) local = dt;
+        }
+        rebuild_dt_partial_[static_cast(tid)] = local;
+    }
+    for (double v : rebuild_dt_partial_) dt0_ = std::min(dt0_, v);
+    // G1-c item 2 (2026-09-19): the aquifer's own stability bound joins the
+    // base step. Before this the ladder's dt0 came from the ACTIVE surface
+    // cells alone: a groundwater cell whose Δt_g / Δt_u was finer than every
+    // wet cell's (or a whole domain with a dry surface, where dt0 fell back
+    // to MAX_TIMESTEP) landed on rung 0 and fired beyond its own bound. The
+    // scan is the one refreshDtCell() already does for assignTiers() below.
+    if (gw_) {
+        gw_->refreshDtCell(*mesh_, edges_);
+        dt0_ = std::min(dt0_, std::min(gw_->minDtCell(), opts_->max_timestep));
     }
     if (dt0_ >= 1.0e30) dt0_ = opts_->max_timestep;   // fully quiescent
 
@@ -304,21 +783,58 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
         int tk = 0;
         if (K > 1) {
             const double ratio = dt_cell[k] / dt0_;
-            tk = (ratio >= 2.0)
-                     ? std::min(K - 1, static_cast(std::log2(ratio)))
-                     : 0;
+            // ilogb(x) IS floor(log2(x)) for finite positive x, in a few
+            // cycles instead of a libm call (std::log2 measured 1.8 % of the
+            // run). They can only disagree where log2's <=1 ulp error crosses
+            // an integer — within an ulp of an exact power of two, where
+            // ilogb is the exactly-correct one.
+            tk = (ratio >= 2.0) ? std::min(K - 1, std::ilogb(ratio)) : 0;
             if (state_->coupling_flux[i] != 0.0 || pin_t0_[i]) tk = 0;
         }
         tier_[i] = static_cast(tk);
-        cells_by_tier_[static_cast(tk)].push_back(i);
+        if (!front_rebuild_)
+            cells_by_tier_[static_cast(tk)].push_back(i);
+    }
+    if (front_rebuild_) {
+        // Dry halo cells got the coarsest tier (dt = ∞), so a front could
+        // enter them only every 2^(K−1) substeps — one ring per macro cycle
+        // regardless of the halo width. Pull every dry active cell down to
+        // the finest tier among its active neighbours, propagated across the
+        // halo rings, so the receiving cells update at the front's cadence.
+        // Kept SERIAL (Gauss-Seidel over the edges) on purpose. The halo and
+        // frontier sweeps above are exact Jacobi rewrites of their edge loops,
+        // but this one is not: Gauss-Seidel propagates a pulled-down tier
+        // several rings within a single pass, so a Jacobi form reaches a
+        // different fixed point inside the kFrontHaloRings budget. Measured on
+        // the Bellinge 30-min slice, that changed DIFFUSIVE_WAVE materially
+        // (rainfall inflow +1.5 %, 1D→2D spill +165 %) and shifted the FULL_SWE
+        // LTS occupancy census, for ~4 % of the FULL_SWE deck time and nothing
+        // on LOCAL_INERTIAL or DIFFUSIVE_WAVE. It is O(n_edges) once per
+        // rebuild, not per firing.
+        for (int ring = 0; ring < kFrontHaloRings; ++ring) {
+            bool changed = false;
+            for (int e = 0; e < edges_.ne; ++e) {
+                const int a = edges_.cL[e], b = edges_.cR[e];
+                if (!cell_active_[a] || !cell_active_[b]) continue;
+                const bool dry_a = state_->depth[a] <= opts_->dry_depth;
+                const bool dry_b = state_->depth[b] <= opts_->dry_depth;
+                if (dry_a && tier_[a] > tier_[b]) { tier_[a] = tier_[b]; changed = true; }
+                if (dry_b && tier_[b] > tier_[a]) { tier_[b] = tier_[a]; changed = true; }
+            }
+            if (!changed) break;
+        }
+        for (const int i : active_cells_)
+            cells_by_tier_[static_cast(tier_[i])].push_back(i);
     }
 
+    active_faces_.clear();
     for (int e = 0; e < edges_.ne; ++e) {
         const int a = edges_.cL[e], b = edges_.cR[e];
         if (cell_active_[a] && cell_active_[b]) {
             const auto ft = std::min(tier_[a], tier_[b]);
             face_tier_[e] = ft;
             edges_by_tier_[ft].push_back(e);
+            active_faces_.push_back(e);
         } else {
             q_[e] = 0.0;   // walled faces carry no stale momentum
         }
@@ -328,7 +844,31 @@ void ExplicitInertialSolver::syncAndRebuild(double t) {
          tk < cells_by_tier_.size() && tk < tier_occupancy_.size(); ++tk)
         tier_occupancy_[tk] += static_cast(cells_by_tier_[tk].size());
 
-    telemetry_.emplace_back(t, static_cast(active_cells_.size()));
+    // G1: re-tier the subsurface on the same trigger, from ITS OWN stability
+    // steps against the same dt0_ and the same ladder height (G-A). A GW cell
+    // slower than 2^(K−1)·dt0_ lands on the coarsest rung and simply fires
+    // more often than it strictly needs — conservative, and it keeps the
+    // ladder height a single [2D_OPTIONS] LTS_TIERS rather than a second,
+    // silently different number. (D-N1's runtime tier count would let the
+    // ladder grow to `gw_->requiredTiers(dt0_)`; it is deliberately not taken
+    // here — see the handoff.)
+    if (gw_) {   // refreshDtCell() ran above, before dt0_ was fixed
+        gw_->assignTiers(dt0_, static_cast(cells_by_tier_.size()));
+    }
+
+    // Fold the sample into the run_stats() statistics now (same arithmetic,
+    // same order as the old end-of-run fold); keep the sample itself only
+    // when a telemetry CSV was requested.
+    const int n_active = static_cast(active_cells_.size());
+    if (mesh_ && mesh_->n_triangles() > 0) {
+        const double frac = n_active / static_cast(mesh_->n_triangles());
+        active_frac_min_ = std::min(active_frac_min_, frac);
+        active_frac_max_ = std::max(active_frac_max_, frac);
+        active_frac_sum_ += frac;
+        ++active_samples_;
+    }
+    if (!telemetry_path_.empty())
+        telemetry_.emplace_back(t, n_active);
 }
 
 void ExplicitInertialSolver::refreshDt0() {
@@ -341,6 +881,7 @@ void ExplicitInertialSolver::refreshDt0() {
     // wait for syncAndRebuild, which reassigns the tiers.
     const int na = static_cast(active_cells_.size());
     if (na == 0) return;
+    if (mode_ == Momentum2D::DIFFUSIVE_WAVE) refreshDiffusiveSlopes();
     double fresh = 1.0e30;
 #pragma omp parallel num_threads(opts_->num_threads)
     {
@@ -354,9 +895,17 @@ void ExplicitInertialSolver::refreshDt0() {
             if (h <= opts_->dry_depth) continue;
             double speed = 0.0;
             if (!qcx_.empty() && h > 1.0e-6)
-                speed = std::hypot(qcx_[i], qcy_[i]) / h;
-            const double dt = inertial::cellCflDt(opts_->cfl_number,
-                                                  edges_.cell_lchar[i], h, speed);
+                speed = inertial::qMagnitude(qcx_[i], qcy_[i]) / h;
+            double dt = inertial::cellCflDt(opts_->cfl_number,
+                                            (mode_ == Momentum2D::FULL_SWE)
+                                                ? edges_.cell_lpos[i]
+                                                : edges_.cell_lchar[i],
+                                            h, speed);
+            if (mode_ == Momentum2D::DIFFUSIVE_WAVE)
+                dt = diffusive::cellDiffusiveDt(
+                    opts_->cfl_number, edges_.cell_lchar[i], h,
+                    mesh_->mannings_n[i], dw_slope_[i],
+                    opts_->flux_dh_eps / std::max(edges_.cell_lchar[i], 1.0e-9));
             if (dt < local) local = dt;
         }
 #pragma omp critical
@@ -368,11 +917,48 @@ void ExplicitInertialSolver::refreshDt0() {
 }
 
 void ExplicitInertialSolver::fireFaces(const std::vector& faces,
-                                       double dt_f) {
+                                       double dt_f, bool global_step) {
+    switch (mode_) {
+        case Momentum2D::FULL_SWE:       fireFacesSwe(faces, dt_f, global_step); return;
+        case Momentum2D::DIFFUSIVE_WAVE: fireFacesDiffusive(faces, dt_f, global_step); return;
+        case Momentum2D::LOCAL_INERTIAL: break;
+    }
+    fireFacesInertial(faces, dt_f, global_step);
+}
+
+void ExplicitInertialSolver::refreshDiffusiveSlopes() {
+    // Largest |Δη·inv_dx| over each active cell's faces (walled faces count
+    // as zero): the conductance the explicit step bound must survive.
+    const auto& ed = edges_;
+    const int na = static_cast(active_cells_.size());
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+    for (int k = 0; k < na; ++k) {
+        const int i = active_cells_[static_cast(k)];
+        double smax = 0.0;
+        for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+            const int e = ed.cell_edge[p];
+            const double sl = std::fabs((state_->head[ed.cR[e]] - state_->head[ed.cL[e]]) *
+                                        ed.inv_dx_normal[e]);
+            if (sl > smax) smax = sl;
+        }
+        dw_slope_[i] = smax;
+    }
+}
+
+void ExplicitInertialSolver::fireFacesInertial(const std::vector& faces,
+                                               double dt_f, bool global_step) {
     const auto& ed = edges_;
     const int   na = static_cast(faces.size());
     const double theta = opts_->theta;
-    const double beta_share = opts_->exchange_beta / 3.0;
+    // Positivity share per face: a cell's ≤ nv outgoing faces may take at most
+    // β·V in total, so each takes β/nv of its EXPORTER's volume. Triangle
+    // meshes keep the historical β/3 exactly.
+    const double beta3 = opts_->exchange_beta / 3.0;
+    const double beta4 = opts_->exchange_beta / 4.0;
+    // All-triangle meshes skip the per-face cell_nv load entirely (resolved
+    // once in initialize(): the scan is O(n_cells)).
+    const bool   has_quads = has_quads_;
+    const bool   species   = species_on_;
     // VFR_FACE: block/convey at the shared edge's TRUE crest via the B&S
     // Eq. 14 wetted-edge depth; MEAN keeps the centroid zface bit-identical.
     const bool vfr_face =
@@ -401,7 +987,7 @@ void ExplicitInertialSolver::fireFaces(const std::vector& faces,
             // Friction magnitude: the face flow VECTOR, floored at |q_n| so
             // a face whose reconstruction lags its own discharge (front
             // arrival, first firing after activation) never under-damps.
-            q_mag = std::max(q_mag, std::hypot(qfx, qfy));
+            q_mag = std::max(q_mag, inertial::qMagnitude(qfx, qfy));
         }
         double deta = state_->head[b] - state_->head[a];
         if (std::fabs(deta) < inertial::kEtaDeadband) deta = 0.0;
@@ -430,7 +1016,10 @@ void ExplicitInertialSolver::fireFaces(const std::vector& faces,
         // ratio or the repeated takes drain the cell into the backstop
         // (measured: a dam-break basin discarded to exactly zero).
         const int    exp_cell = (qn1 > 0.0) ? a : b;
-        const int    refire   = 1 << (tier_[exp_cell] - face_tier_[e]);
+        const int    refire   =
+            global_step ? 1 : (1 << (tier_[exp_cell] - face_tier_[e]));
+        const double beta_share =
+            (has_quads && mesh_->cell_vertex_count(exp_cell) == 4) ? beta4 : beta3;
         const double budget   = beta_share / refire *
                                 std::max(state_->volume[exp_cell], 0.0);
         const double take = std::fabs(qn1) * ed.xi[e] * dt_f;
@@ -442,33 +1031,455 @@ void ExplicitInertialSolver::fireFaces(const std::vector& faces,
         const double dM = qn1 * ed.xi[e] * dt_f;   // positive = cL→cR
         facc_L_[e] -= dM;
         facc_R_[e] += dM;
+
+        if (species) bookFaceSpecies(e, a, b, dM, hf, dt_f, global_step);
+    }
+    face_passes_ += na;
+    accumulators_pending_ = true;
+}
+
+
+
+// ---------------------------------------------------------------------------
+// MOMENTUM_EQUATION FULL_SWE — Godunov face flux (SweKernels.hpp).
+// ---------------------------------------------------------------------------
+void ExplicitInertialSolver::fireFacesSwe(const std::vector& faces,
+                                          double dt_f, bool global_step) {
+    const auto& ed = edges_;
+    const int   na = static_cast(faces.size());
+    const double beta3 = opts_->exchange_beta / 3.0;
+    const double beta4 = opts_->exchange_beta / 4.0;
+    const double dry   = opts_->dry_depth;
+
+    static const bool muscl_off = std::getenv("OPENSWMM_2D_MUSCL_OFF") != nullptr;
+    if (second_order_) computeLimitedGradientsSwe();
+    const bool so = second_order_ && !muscl_off;
+    const bool species = species_on_;
+    const bool has_quads = has_quads_;
+
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+    for (int k = 0; k < na; ++k) {
+        const int e = faces[static_cast(k)];
+        const int a = ed.cL[e], b = ed.cR[e];
+        swe::FaceFlux F;
+        double cLx, cLy, cRx, cRy;
+        bool wet;
+        if (so) {
+            // MUSCL: extrapolate (η, u, v) from each centroid to the face
+            // midpoint along the precomputed Perot arms; the bed stays
+            // piecewise constant per cell.
+            const double ha = state_->depth[a], hb = state_->depth[b];
+            const double za = state_->head[a] - ha, zb = state_->head[b] - hb;
+            double axa = 0.0, aya = 0.0, axb = 0.0, ayb = 0.0;
+            for (int p = ed.cell_ptr[a]; p < ed.cell_ptr[a + 1]; ++p)
+                if (ed.cell_edge[p] == e) { axa = ed.cell_arm_x[p]; aya = ed.cell_arm_y[p]; break; }
+            for (int p = ed.cell_ptr[b]; p < ed.cell_ptr[b + 1]; ++p)
+                if (ed.cell_edge[p] == e) { axb = ed.cell_arm_x[p]; ayb = ed.cell_arm_y[p]; break; }
+            const double ua = (ha > dry) ? qcx_[a] / ha : 0.0, va = (ha > dry) ? qcy_[a] / ha : 0.0;
+            const double ub = (hb > dry) ? qcx_[b] / hb : 0.0, vb = (hb > dry) ? qcy_[b] / hb : 0.0;
+            const double etaLf = state_->head[a] + gex_[a] * axa + gey_[a] * aya;
+            const double etaRf = state_->head[b] + gex_[b] * axb + gey_[b] * ayb;
+            const double uLf = ua + gux_[a] * axa + guy_[a] * aya;
+            const double vLf = va + gvx_[a] * axa + gvy_[a] * aya;
+            const double uRf = ub + gux_[b] * axb + guy_[b] * ayb;
+            const double vRf = vb + gvx_[b] * axb + gvy_[b] * ayb;
+            wet = swe::faceFluxRecon(etaLf, uLf, vLf, za, ha,
+                                     etaRf, uRf, vRf, zb, hb,
+                                     ed.nx[e], ed.ny[e], dry, F, cLx, cLy, cRx, cRy);
+        } else {
+            wet = swe::faceFlux(
+                state_->head[a], state_->depth[a], qcx_[a], qcy_[a],
+                state_->head[b], state_->depth[b], qcx_[b], qcy_[b],
+                ed.nx[e], ed.ny[e], dry, F, cLx, cLy, cRx, cRy);
+        }
+        // Dry-dry face: no flux, no correction (faceFlux zeroes both), so
+        // nothing to book — the accumulator read-modify-writes of zero and
+        // the conveyance gather are skipped (F4). Species dispersion still
+        // gets its call.
+        if (!wet) {
+            q_[e] = 0.0;
+            if (species) {
+                const double hf0 = std::max(state_->head[a], state_->head[b]) - ed.zface[e];
+                bookFaceSpecies(e, a, b, 0.0, (hf0 > 0.0) ? hf0 : 0.0, dt_f, global_step);
+            }
+            continue;
+        }
+        // Face conveyance (leaky barriers) scales the whole flux vector.
+        const double conv = mesh_->edge_conveyance[ed.slotL[e]];
+        double fh = F.mass * conv, fmx = F.mx * conv, fmy = F.my * conv;
+
+        // Positivity share (same contract as the inertial law): the mass a
+        // face may take from its exporter over the exporter's cycle. Mass
+        // and momentum are scaled together so the flux stays consistent.
+        if (fh != 0.0) {
+            const int    exp_cell = (fh > 0.0) ? a : b;
+            const int    refire   =
+                global_step ? 1 : (1 << (tier_[exp_cell] - face_tier_[e]));
+            const double beta_share =
+                (has_quads && mesh_->cell_vertex_count(exp_cell) == 4) ? beta4 : beta3;
+            const double budget = beta_share / refire *
+                                  std::max(state_->volume[exp_cell], 0.0);
+            const double take = std::fabs(fh) * ed.xi[e] * dt_f;
+            if (take > budget) {
+                const double lam = (take > 0.0) ? budget / take : 0.0;
+                fh *= lam; fmx *= lam; fmy *= lam;
+            }
+        }
+        q_[e] = fh;
+        const double xdt = ed.xi[e] * dt_f;
+        const double dM  = fh * xdt;                       // m³, + = cL→cR
+        facc_L_[e] -= dM;
+        facc_R_[e] += dM;
+        // Momentum: −flux + bed-slope correction on the exporter side, +flux
+        // + correction on the receiver side (units m⁴/s).
+        macc_x_L_[e] += (-fmx + cLx) * xdt;
+        macc_y_L_[e] += (-fmy + cLy) * xdt;
+        macc_x_R_[e] += ( fmx + cRx) * xdt;
+        macc_y_R_[e] += ( fmy + cRy) * xdt;
+
+        // Species ride the mass flux at the face depth the inertial law
+        // would have used (dispersion conductance only).
+        if (species) {
+            const double hf = std::max(state_->head[a], state_->head[b]) - ed.zface[e];
+            bookFaceSpecies(e, a, b, dM, (hf > 0.0) ? hf : 0.0, dt_f, global_step);
+        }
     }
     face_passes_ += na;
+    accumulators_pending_ = true;
 }
 
+// ---------------------------------------------------------------------------
+// MOMENTUM_EQUATION DIFFUSIVE_WAVE — Manning quasi-steady face flux.
+// ---------------------------------------------------------------------------
+void ExplicitInertialSolver::fireFacesDiffusive(const std::vector& faces,
+                                                double dt_f, bool global_step) {
+    const auto& ed = edges_;
+    const int   na = static_cast(faces.size());
+    const double beta3 = opts_->exchange_beta / 3.0;
+    const double beta4 = opts_->exchange_beta / 4.0;
+    const bool vfr_face =
+        (opts_->face_reconstruction == FaceDepth2D::VFR_FACE);
+    const bool species   = species_on_;
+    const bool has_quads = has_quads_;
+
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+    for (int k = 0; k < na; ++k) {
+        const int e = faces[static_cast(k)];
+        const int a = ed.cL[e], b = ed.cR[e];
+        const double hf = vfr_face
+            ? inertial::faceFlowDepthVfr(state_->head[a], state_->head[b],
+                                         ed.ze_lo[e], ed.ze_hi[e])
+            : inertial::faceFlowDepth(state_->head[a], state_->head[b], ed.zface[e]);
+        if (hf <= opts_->dry_depth) { q_[e] = 0.0; continue; }
+        double deta = state_->head[b] - state_->head[a];
+        if (std::fabs(deta) < inertial::kEtaDeadband) deta = 0.0;
+        const double slope = deta * ed.inv_dx_normal[e];
+        const double s_eps = opts_->flux_dh_eps * ed.inv_dx_normal[e];
+        // n_face = sqrt(n2_face) precomputed per face (F7).
+        double qn1 = diffusive::faceDischarge(hf, slope, ed.n_face[e], s_eps);
+        qn1 *= mesh_->edge_conveyance[ed.slotL[e]];
+
+        // Same positivity share as the other closures.
+        const int    exp_cell = (qn1 > 0.0) ? a : b;
+        const int    refire   =
+            global_step ? 1 : (1 << (tier_[exp_cell] - face_tier_[e]));
+        const double beta_share =
+            (has_quads && mesh_->cell_vertex_count(exp_cell) == 4) ? beta4 : beta3;
+        const double budget = beta_share / refire *
+                              std::max(state_->volume[exp_cell], 0.0);
+        const double take = std::fabs(qn1) * ed.xi[e] * dt_f;
+        if (take > budget) qn1 *= (take > 0.0) ? budget / take : 0.0;
+        q_[e] = qn1;
+        const double dM = qn1 * ed.xi[e] * dt_f;
+        facc_L_[e] -= dM;
+        facc_R_[e] += dM;
+        if (species) bookFaceSpecies(e, a, b, dM, hf, dt_f, global_step);
+    }
+    face_passes_ += na;
+    accumulators_pending_ = true;
+}
+
+void ExplicitInertialSolver::bookFaceSpecies(int e, int a, int b, double dM,
+                                             double hf, double dt_f,
+                                             bool global_step) noexcept {
+    // Hydrodynamics-only models (no species) have nothing to book: return
+    // before the divisions below — this runs once per face evaluation.
+    if (!species_on_) return;
+    const auto& ed = edges_;
+    const double beta3 = opts_->exchange_beta / 3.0;
+    const double beta4 = opts_->exchange_beta / 4.0;
+        // S1 (D-2DT2): species mass rides THIS ΔM, from the FINAL qn1 —
+    // after the Froude cap and the positivity share — at the exporter's
+    // concentration read NOW, against the same published volume the
+    // share budgeted against. Same writer, same face, same substep:
+    // the species flux cannot disagree with the volume flux about
+    // cadence, direction or magnitude, which is the whole of the
+    // conservation argument.
+    if (species_on_ && dM != 0.0) {
+        const int   donor = (dM > 0.0) ? a : b;
+        // S7 (D-A22): the cells' NET runoff — the volume leaves the donor
+        // and arrives at the receiver, at the face's own cadence, so a cell
+        // that only passes water through produces none.
+        if (!state_->transport.cell_runoff_vol.empty()) {
+            auto& rv = state_->transport.cell_runoff_vol;
+            rv[static_cast(donor)] += std::fabs(dM);
+            rv[static_cast((dM > 0.0) ? b : a)] -= std::fabs(dM);
+        }
+        const auto  ns    = static_cast(
+            state_->transport.n_species);
+        const auto  ue    = static_cast(e);
+        const auto  nef   = static_cast(ed.ne);
+        for (std::size_t s = 0; s < ns; ++s) {
+            const double c = donorConc(static_cast(s), donor);
+            if (c == 0.0) continue;
+            const double dMs = dM * c;
+            sacc_L_[s * nef + ue] -= dMs;
+            sacc_R_[s * nef + ue] += dMs;
+        }
+    }
+
+    // S2 (D-2DT7): isotropic dispersion, booked on the SAME face, at the
+    // SAME cadence, into the SAME accumulators as the advective term —
+    // so it inherits the marcher's tier consistency exactly as advection
+    // does. Explicit exchange F = D·(h_f·ξ)·(c_a − c_b)/d over dt_f.
+    //
+    // Explicit diffusion has its own stability limit, D·dt/d² ≤ ~½, and
+    // the marcher's dt0 is set by gravity waves, not by D. Rather than
+    // couple dt0 to D (a global cost for a local term), the exchange is
+    // LIMITED so the pair can never cross: at most the amount that
+    // equalises the two concentrations, and at most the same β share of
+    // the giver's mass the volume flux is held to. Positivity and the
+    // pairwise max principle follow; a bind is COUNTED, because a face
+    // that binds is telling the modeller the dispersion is
+    // under-resolved at this dt.
+    if (species_on_ && opts_->dispersion > 0.0) {
+        const double va = state_->volume[a], vb = state_->volume[b];
+        if (va > 0.0 && vb > 0.0) {
+            const double cond =
+                opts_->dispersion * hf * ed.xi[e] * ed.inv_dx_normal[e] *
+                dt_f;                                  // m³ exchanged
+            const auto  ns  = static_cast(
+                state_->transport.n_species);
+            const auto  ue  = static_cast(e);
+            const auto  nef = static_cast(ed.ne);
+            auto& tr = state_->transport;
+            for (std::size_t s = 0; s < ns; ++s) {
+                const double ma = tr.cell_mass[tr.idx(static_cast(s), a)];
+                const double mb = tr.cell_mass[tr.idx(static_cast(s), b)];
+                const double ca = ma / va, cb = mb / vb;
+                double dMd = cond * (ca - cb);          // + = a → b
+                if (dMd == 0.0) continue;
+                // Equalisation bound, divided by 3 because PAIRWISE
+                // bounds do not compose: a cell receiving from up to
+                // three faces, each capped at FULL pairwise equalisation
+                // computed from the same start-of-substep state, can end
+                // richer than every donor (the check measured 15.31 on
+                // an initial max of 10 at D = 20). Each face may close
+                // at most a third of its gap; with the harmonic volume
+                // ≤ the receiver's own, the sum over ≤ 3 faces is then
+                // bounded by the largest donor concentration — the same
+                // 1/3 composition argument the volume side's β/3 makes.
+                // (A quad receiver has up to four faces: /4.)
+                const int    giver    = (dMd > 0.0) ? a : b;
+                const int    receiver = (dMd > 0.0) ? b : a;
+                const double eq = (ca - cb) * va * vb / (va + vb) /
+                    ((mesh_->cell_vertex_count(receiver) == 4) ? 4.0 : 3.0);
+                // β share of the GIVER's mass, divided by the refire
+                // ratio exactly as the volume share is.
+                const int    refire = global_step
+                    ? 1 : (1 << (tier_[giver] - face_tier_[e]));
+                // The giver-mass share is a POSITIVITY guard: give at
+                // most a β share of what is there. The SIGNED temperature
+                // row (S4) has no positivity to guard — its mass crosses
+                // zero at a warm/cold front, where a mass share would
+                // vanish and bind every smoothing exchange. For it the
+                // equalisation bound alone is the cap: it is what
+                // enforces the pairwise max principle in both directions.
+                const double share  =
+                    ((mesh_->cell_vertex_count(giver) == 4) ? beta4 : beta3) /
+                    refire * std::fabs((dMd > 0.0) ? ma : mb);
+                const double cap = tr.signedRow(static_cast(s))
+                    ? std::fabs(eq)
+                    : std::min(std::fabs(eq), share);
+                if (std::fabs(dMd) > cap) {
+                    dMd = (dMd > 0.0) ? cap : -cap;
+                    #pragma omp atomic
+                    ++tr.dispersion_limiter_binds;
+                }
+                sacc_L_[s * nef + ue] -= dMd;
+                sacc_R_[s * nef + ue] += dMd;
+            }
+        }
+    }
+}
+
+// The cell kernel is a template on the closure so the LOCAL_INERTIAL /
+// DIFFUSIVE_WAVE instantiation contains none of the FULL_SWE momentum code
+// (measured: the merged body cost the LI cell pass +17 % — register pressure
+// and dead branches inside the OpenMP-outlined loop; the LI instantiation is
+// the pre-FULL_SWE kernel again). Dispatch is one branch per firing.
 void ExplicitInertialSolver::fireCells(const std::vector& cells,
-                                       double dt_c) {
+                                       double dt_c, bool tier0) {
+    if (mode_ == Momentum2D::FULL_SWE) fireCellsImpl(cells, dt_c, tier0);
+    else                               fireCellsImpl(cells, dt_c, tier0);
+}
+
+template 
+void ExplicitInertialSolver::fireCellsImpl(const std::vector& cells,
+                                           double dt_c, bool tier0) {
     const auto& ed = edges_;
     const int   nc = static_cast(cells.size());
+    // Loop-invariant closure flags, resolved outside the parallel region so
+    // the outlined body carries them as firstprivate constants instead of
+    // re-reading members through `this` on every cell.
+    constexpr bool swe = kSwe;
+    const bool   perot   = !qcx_.empty() && !swe;
+    const bool   species = species_on_;
+    const bool   front   = front_rebuild_;
+    const double dry     = opts_->dry_depth;
 
 #pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
     for (int k = 0; k < nc; ++k) {
         const int i = cells[static_cast(k)];
-        // Gather + clear this cell's side of every incident face accumulator.
-        double flux_m3 = 0.0;
+        // ONE walk of this cell's CSR row: gather + clear its side of every
+        // incident face accumulator, and (when the Perot reconstruction is
+        // live) accumulate its discharge vector from the same face ids. The
+        // two loops used to load cell_edge/cell_sign twice for every incident
+        // face; the arms (m_e - c_i) are precomputed per CSR entry so the
+        // midpoint gather and the two subtractions are gone as well.
+        double flux_m3 = 0.0, sx = 0.0, sy = 0.0;
+        double dmx = 0.0, dmy = 0.0;          // FULL_SWE momentum gather (m⁴/s)
         for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
             const int e = ed.cell_edge[p];
-            if (ed.cell_sign[p] > 0.0) {
+            if (ed.cell_sign[p] > 0) {
                 flux_m3 += facc_L_[e];
                 facc_L_[e] = 0.0;
+                if constexpr (swe) {
+                    dmx += macc_x_L_[e]; macc_x_L_[e] = 0.0;
+                    dmy += macc_y_L_[e]; macc_y_L_[e] = 0.0;
+                }
             } else {
                 flux_m3 += facc_R_[e];
                 facc_R_[e] = 0.0;
+                if constexpr (swe) {
+                    dmx += macc_x_R_[e]; macc_x_R_[e] = 0.0;
+                    dmy += macc_y_R_[e]; macc_y_R_[e] = 0.0;
+                }
+            }
+            if (perot) {
+                const double f =
+                    static_cast(ed.cell_sign[p]) * q_[e] * ed.xi[e];
+                sx += f * ed.cell_arm_x[p];
+                sy += f * ed.cell_arm_y[p];
             }
         }
-        const double src =
-            state_->rainfall[i] + state_->coupling_flux[i]
-            - evapSink(state_->evap_rate[i], state_->depth[i], opts_->dry_depth);
+        const double infil =
+            infilSink(state_->infil_rate[i], state_->depth[i], dry);
+        state_->infil_applied[i] += infil * dt_c;
+        if (state_->coupling_flux[i] != 0.0)
+            state_->coupling_applied[i] +=
+                state_->coupling_flux[i] * dt_c * mesh_->tri_area[i];
+        const double evap =
+            evapSink(state_->evap_rate[i], state_->depth[i], dry);
+        // G1 step 11b. With a `[2D_AQUIFER]` present, infiltration is not
+        // LOST — it is booked to the cell's aquifer column, and saturation
+        // excess (Dunne and top-layer rejection) comes back the other way.
+        // Both directions are per-cell slots, so this stays race-free inside
+        // the parallel cell loop; the LIST bookkeeping is compacted serially
+        // at the rebuild.
+        double gw_return = 0.0;
+        if (gw_) {
+            const double A = mesh_->tri_area[i];
+            const double infil_m3 = infil * dt_c * A;
+            if (infil > 0.0)
+                gw_->bookInfiltrationFromSurface(i, infil_m3);
+            const double back = gw_->takeToSurface(i);   // m³
+            if (back != 0.0) gw_return = back / (A * dt_c);
+            // …and the saturation excess brings its own mass back up.
+            if (species && gw_->transport().active()) {
+                auto& tr = state_->transport;
+                const int ns = std::min(tr.n_species, gw_->transport().n_species);
+                for (int s = 0; s < ns; ++s) {
+                    const double dm = gw_->takeToSurfaceMass(i, s);
+                    if (dm == 0.0) continue;
+                    tr.cell_mass[tr.idx(s, i)] += dm;
+                    if (static_cast(s) < tr.gained_exfiltration.size())
+                        tr.gained_exfiltration[static_cast(s)] += dm;
+                }
+            }
+        }
+        const double src = state_->rainfall[i] + state_->coupling_flux[i] +
+                           gw_return - evap - infil;
+
+        // S1 species. ORDER MATTERS and is the same as the faces': sinks
+        // read this cell's concentration against its PUBLISHED volume
+        // (before the update below), then the face gather lands, then the
+        // volume moves. Infiltration and a negative (2D→1D) held coupling
+        // flux leave at the cell's concentration; rainfall and a positive
+        // coupling flux arrive at ZERO concentration in S1 (S2/S3 own their
+        // concentrations); evaporation removes no mass at all, so the
+        // concentration rises — the up-concentration the plan's §2.3 wants
+        // right from the start.
+        if (species) {
+            auto& tr = state_->transport;
+            const double area = mesh_->tri_area[i];
+            sinkIntensiveRowsWithEvap(i, evap * dt_c * area);            // S4/S4b
+            // T7.1: hand the aquifer EXACTLY the mass this sink removed —
+            // the ledger delta, not a second evaluation of `dv × c`. The
+            // sink clamps, it runs after the saturation excess above has
+            // already raised this cell's concentration, and it is the one
+            // place that knows what actually left; recomputing the product
+            // beside it was off by 3 % on the first cut, which is precisely
+            // the kind of seam that leaks water years later.
+            gwInfiltrationSeam(i, infil * dt_c * area);
+            if (state_->coupling_flux[i] < 0.0)
+                sinkMassAtCellConc(i, -state_->coupling_flux[i] * dt_c * area,
+                                   tr.lost_coupling);
+            // S2: rainfall arrives at the [POLLUTANTS] rain concentration.
+            // Volume × concentration, booked to the gained ledger so the
+            // continuity statement (S1 total − sources) still closes.
+            const double rain_m3 = state_->rainfall[i] * dt_c * area;
+            const auto ns  = static_cast(tr.n_species);
+            const auto nef = static_cast(ed.ne);
+            // S7 (D-A22): as addCouplingSourceMass — inflow, not runoff.
+            if (!tr.cell_runoff_vol.empty() && state_->coupling_flux[i] > 0.0)
+                tr.cell_runoff_vol[i] -= state_->coupling_flux[i] * dt_c * area;
+            for (std::size_t s = 0; s < ns; ++s) {
+                double dm = 0.0;
+                if (rain_m3 > 0.0 && s < tr.rain_conc.size() &&
+                    tr.rain_conc[s] != 0.0) {
+                    const double gained = rain_m3 * tr.rain_conc[s];
+                    dm += gained;
+                    tr.gained_rainfall[s] += gained;
+                }
+                // S3: outfall discharge (positive coupling_flux) carries the
+                // outfall's concentration as a mass-rate density.
+                if (!tr.coupling_src.empty() && state_->coupling_flux[i] > 0.0) {
+                    const double g = tr.coupling_src[tr.idx(static_cast(s), i)] *
+                                     dt_c * area;
+                    if (g != 0.0) { dm += g; tr.gained_coupling[s] += g; }
+                }
+                for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+                    const auto e = static_cast(ed.cell_edge[p]);
+                    if (ed.cell_sign[p] > 0) {
+                        dm += sacc_L_[s * nef + e];
+                        sacc_L_[s * nef + e] = 0.0;
+                    } else {
+                        dm += sacc_R_[s * nef + e];
+                        sacc_R_[s * nef + e] = 0.0;
+                    }
+                }
+                double& m = tr.cell_mass[tr.idx(static_cast(s), i)];
+                m += dm;
+                // The same backstop the volume has, for the same reason: the
+                // face caps make a deficit ~impossible, and a −1 ulp of mass
+                // must not become a negative concentration in a report.
+                // Nonnegative rows only — the SIGNED temperature row holds
+                // °C·m³ below zero as a state, not an artefact.
+                if (m < 0.0 && !tr.signedRow(static_cast(s))) m = 0.0;
+            }
+        }
+
         double v = state_->volume[i] + flux_m3 +
                    dt_c * src * mesh_->tri_area[i];
 #ifndef NDEBUG
@@ -488,19 +1499,63 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
                                                    // make deficits ~impossible
         inertial::cellEtaDepth(*mesh_, *opts_, i, state_->volume[i],
                                state_->head[i], state_->depth[i]);
+        // FRONT_REBUILD: the wetting front reached the halo's outer ring.
+        if (front && !front_breach_ && frontier_[i] &&
+            state_->depth[i] >= h_on_front_)
+            front_breach_ = true;   // benign race: any writer sets true
         // Refresh this cell's Perot discharge vector at its own cadence.
-        if (!qcx_.empty()) {
-            double sx = 0.0, sy = 0.0;
-            for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
-                const int    e = ed.cell_edge[p];
-                const double f = ed.cell_sign[p] * q_[e] * ed.xi[e];
-                sx += f * (ed.mx[e] - mesh_->tri_cx[i]);
-                sy += f * (ed.my[e] - mesh_->tri_cy[i]);
-            }
+        if (perot) {
             const double inv_a = 1.0 / mesh_->tri_area[i];
             qcx_[i] = sx * inv_a;
             qcy_[i] = sy * inv_a;
         }
+        // FULL_SWE momentum update: M = A·q⃗ + Σ face bookings (fluxes and
+        // bed-slope corrections), then semi-implicit friction against the
+        // NEW depth. Sources (rain, coupling, infiltration, evaporation)
+        // move volume only, so the velocity adjusts with the depth. A cell
+        // that fell below the dry depth carries no momentum.
+        if constexpr (swe) {
+            const double A = mesh_->tri_area[i];
+            const double h_new = state_->depth[i];
+            // WALL boundary faces (every boundary slot without a non-WALL
+            // type) close the pressure balance: the mirror-state Riemann
+            // flux carries no mass but ½g·h² of normal momentum, without
+            // which a cell at rest beside a wall would accelerate away from
+            // it. Booked here at the cell's own cadence (the non-WALL types
+            // fire at tier 0 through boundaryFluxSwe).
+            if (h_new > dry) {
+                // WALL slots come from the CSR built in initialize() (F5):
+                // interior cells have an empty row instead of a neighbour
+                // + boundary-type scan on every firing.
+                for (int w = wall_ptr_[i]; w < wall_ptr_[i + 1]; ++w) {
+                    const int slot = wall_slot_[static_cast(w)];
+                    const double nx = mesh_->edge_nx[slot], ny = mesh_->edge_ny[slot];
+                    const double ux = qcx_[i] / h_new, uy = qcy_[i] / h_new;
+                    const double un = ux * nx + uy * ny, ut = -ux * ny + uy * nx;
+                    // Mirror ghost: same depth, reversed normal velocity.
+                    const double qxg = h_new * (-un * nx - ut * ny);
+                    const double qyg = h_new * (-un * ny + ut * nx);
+                    swe::FaceFlux F;
+                    double cLx, cLy, cRx, cRy;
+                    if (swe::faceFlux(state_->head[i], h_new, qcx_[i], qcy_[i],
+                                      state_->head[i], h_new, qxg, qyg,
+                                      nx, ny, dry, F,
+                                      cLx, cLy, cRx, cRy)) {
+                        const double xdt = mesh_->edge_length[slot] * dt_c;
+                        dmx += (-F.mx + cLx) * xdt;
+                        dmy += (-F.my + cLy) * xdt;
+                    }
+                }
+            }
+            if (h_new > dry) {
+                double qx = (A * qcx_[i] + dmx) / A;
+                double qy = (A * qcy_[i] + dmy) / A;
+                swe::frictionUpdate(qx, qy, h_new, mesh_->mannings_n[i], dt_c);
+                qcx_[i] = qx; qcy_[i] = qy;
+            } else {
+                qcx_[i] = 0.0; qcy_[i] = 0.0;
+            }
+        }
     }
 
     // Boundary edges owned by cells of this firing (serial: perimeter-sized).
@@ -511,13 +1566,25 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
         if (tier_[i] != 0 || !cell_active_[i]) continue;
         // BC cells are pinned to tier 0, so they fire with every tier-0 list;
         // guard against double-firing when called for other tiers.
-        if (&cells != &cells_by_tier_[0]) continue;
+        if (!tier0) continue;
         const int    idx = bc_slot_[k];
         const auto   bt  = static_cast(
             state_->boundary->edge_bc_type[idx]);
         const double L = mesh_->edge_length[idx];
         double f;
-        if (bt == BoundaryType::SPECIFIED_STAGE && L > 1.0e-12) {
+        double f_requested_swe = 0.0;
+        if (mode_ == Momentum2D::FULL_SWE) {
+            // Ghost-cell Riemann boundary: mass AND momentum, no clamp
+            // beyond v ≥ 0 (the Riemann flux is bounded by the states).
+            swe_bc_dqx_ = swe_bc_dqy_ = 0.0;
+            f = boundaryFluxSwe(k, i, dt_c);
+            f_requested_swe = f;
+        } else if (mode_ == Momentum2D::DIFFUSIVE_WAVE) {
+            // The diffusive-wave boundary law for every type (collapsed
+            // Manning conductance against the prescribed stage).
+            f = computeBoundaryEdgeFlux(*mesh_, *state_, *opts_,
+                                        opts_->flux_dh_eps, i, idx);
+        } else if (bt == BoundaryType::SPECIFIED_STAGE && L > 1.0e-12) {
             // Inertial stage boundary: the SAME momentum law as an interior
             // face, integrated against a ghost held at the prescribed stage
             // (η = η_bc, zero-gradient q → the θ-blend collapses to the
@@ -532,12 +1599,11 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
             if (vfr_face_bc) {
                 // B&S Eq. 14 depth of the driving surface over the edge's
                 // TRUE endpoint beds (same endpoint rule as the interior
-                // VFR_FACE path: edge e is opposite vertex e).
-                const int vv[3] = {mesh_->tri_v0[i], mesh_->tri_v1[i],
-                                   mesh_->tri_v2[i]};
-                const int    e_l = idx % 3;
-                const double za  = mesh_->vz[vv[(e_l + 1) % 3]];
-                const double zb  = mesh_->vz[vv[(e_l + 2) % 3]];
+                // VFR_FACE path: edge k = (v[(k+1)%nv], v[(k+2)%nv])).
+                int va_e, vb_e;
+                mesh_->cell_edge_vertices(i, MeshData::slot_local(idx), va_e, vb_e);
+                const double za  = mesh_->vz[va_e];
+                const double zb  = mesh_->vz[vb_e];
                 hf = inertial::faceDepthFromEta(
                     std::max(state_->head[i], eta_bc),
                     std::min(za, zb), std::max(za, zb));
@@ -552,8 +1618,11 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
             double deta = state_->head[i] - eta_bc;
             if (std::fabs(deta) < inertial::kEtaDeadband) deta = 0.0;
             // The ghost sits across the boundary edge at the centroid→edge
-            // distance 2A/(3L) (triangle centroid is 1/3 of the height up).
-            const double slope = deta * (3.0 * L) / (2.0 * mesh_->tri_area[i]);
+            // normal distance: 2A/(3L) for a triangle (expression retained
+            // verbatim for bit-identity), edge_dist_c for a quad.
+            const double slope = (mesh_->cell_vertex_count(i) == 3)
+                ? deta * (3.0 * L) / (2.0 * mesh_->tri_area[i])
+                : deta / mesh_->edge_dist_c[idx];
             const double n     = mesh_->mannings_n[i];
             double qn1 = inertial::inertialFaceUpdate(
                 bc_q_[k], bc_q_[k], hf, dt_c, slope, n * n,
@@ -573,7 +1642,7 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
         // (no −1 ulp volume dust from the flux-space clamp).
         const double v_old = state_->volume[i];
         double v_new = v_old + dt_c * f;
-        if (bt == BoundaryType::SPECIFIED_STAGE) {
+        if (bt == BoundaryType::SPECIFIED_STAGE && mode_ != Momentum2D::FULL_SWE) {
             // Equilibrium clamp, kept as the tiny-cell / overshoot backstop:
             // one substep moves the cell AT MOST to the prescribed stage. At
             // the inertial law's gravity-scale takes it almost never binds.
@@ -584,10 +1653,47 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
         }
         if (v_new < 0.0) v_new = 0.0;   // availability clamp (exact floor)
         f = (v_new - v_old) / dt_c;
+        // FULL_SWE booked its momentum inside boundaryFluxSwe against the
+        // REQUESTED mass; when the clamp above shrank that mass, take the
+        // same fraction of the momentum back (what the comment below has
+        // always promised, and what the interior positivity cap does).
+        if (mode_ == Momentum2D::FULL_SWE && f != f_requested_swe &&
+            (swe_bc_dqx_ != 0.0 || swe_bc_dqy_ != 0.0))
+        {
+            const double lam = (f_requested_swe != 0.0) ? f / f_requested_swe : 0.0;
+            qcx_[i] += swe_bc_dqx_ * (lam - 1.0);
+            qcy_[i] += swe_bc_dqy_ * (lam - 1.0);
+        }
         // Momentum matches applied mass (mirrors the interior positivity-cap
         // rescale of qn1) — the prescribed-flux types record theirs here too.
         bc_q_[k] = (L > 1.0e-12) ? f / L : 0.0;
         if (f != 0.0) {
+            // S1: an OUTFLOW boundary carries the cell's concentration out;
+            // an inflow boundary brings water at zero concentration until S2
+            // gives edges a species column. Applied volume, not requested,
+            // so the species booking matches the water booking exactly.
+            if (species_on_) {
+                auto& tr = state_->transport;
+                if (v_new < v_old) {
+                    sinkMassAtCellConc(i, v_old - v_new, tr.lost_boundary);
+                } else {
+                    // S2: INFLOW carries the edge's [2D_BOUNDARY_QUALITY]
+                    // concentration (0 when none was given — clean water).
+                    if (!tr.cell_runoff_vol.empty())          // S7: inflow
+                        tr.cell_runoff_vol[i] -= v_new - v_old;
+                    const auto ns = static_cast(tr.n_species);
+                    if (k * ns + ns <= tr.bc_conc.size()) {
+                        const double dv = v_new - v_old;
+                        for (std::size_t s = 0; s < ns; ++s) {
+                            const double c = tr.bc_conc[k * ns + s];
+                            if (c == 0.0) continue;
+                            const double g = dv * c;
+                            tr.cell_mass[tr.idx(static_cast(s), i)] += g;
+                            tr.gained_boundary[s] += g;
+                        }
+                    }
+                }
+            }
             state_->volume[i] = v_new;
             bc_accum_[k] += dt_c * f;
             inertial::cellEtaDepth(*mesh_, *opts_, i, state_->volume[i],
@@ -598,12 +1704,9 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
         // through its boundary carried a systematic (1−θ) drag on every
         // face (the SPECIFIED_FLOW entrance jump). Add the boundary edge's
         // own contribution in the interior gather's outward-flux convention.
-        if (!qcx_.empty() && bc_q_[k] != 0.0) {
-            const int vv[3] = {mesh_->tri_v0[i], mesh_->tri_v1[i],
-                               mesh_->tri_v2[i]};
-            const int    e_l = idx % 3;
-            const int    va  = vv[(e_l + 1) % 3];
-            const int    vb  = vv[(e_l + 2) % 3];
+        if (!qcx_.empty() && mode_ == Momentum2D::LOCAL_INERTIAL && bc_q_[k] != 0.0) {
+            int va, vb;
+            mesh_->cell_edge_vertices(i, MeshData::slot_local(idx), va, vb);
             const double mxb = 0.5 * (mesh_->vx[va] + mesh_->vx[vb]);
             const double myb = 0.5 * (mesh_->vy[va] + mesh_->vy[vb]);
             const double fo    = -f;   // outward volumetric flux (m³/s)
@@ -618,7 +1721,7 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
     // Drains cap at the exchange-β share of the source cell; spills cap at
     // the node's stored volume for the whole advance (node_drawn_ ledger) —
     // the same water cannot spill twice within a routing step.
-    if (!exch_.empty() && &cells == &cells_by_tier_[0] &&
+    if (!exch_.empty() && tier0 &&
         state_->node_coupling && state_->nodes_1d) {
         const auto& pts = *state_->node_coupling;
         for (std::size_t k = 0; k < pts.size(); ++k) {
@@ -635,18 +1738,100 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
             if (Q > 0.0) {   // 2D → 1D drain: availability share of the cell
                 Q = std::min(Q, opts_->exchange_beta *
                                     std::max(state_->volume[ci], 0.0) / dt_c);
-            } else {         // 1D → 2D spill: node stored-volume budget
+            } else {
+                // 1D → 2D spill: the node may only give up its PONDED water,
+                // i.e. what it holds ABOVE full_volume.
+                //
+                // C3 (2026-09-07). This used to be the node's TOTAL stored
+                // volume, which let a surcharged-but-not-flooding node
+                // dewater its own pipes through the manhole cover: the spill
+                // physically exits at the rim, so below-crown conveyance
+                // storage is not reachable by it. On a surcharging network
+                // that is a large, one-signed transfer of water from the 1D
+                // system to the 2D surface with nothing to stop it.
+                //
+                // `full_volume` is the node's own capacity; SWMM's ponded
+                // branch stores ponded water as volume ABOVE it
+                // (commitNodeDepthState: volume = max(old + dV, full_volume)),
+                // so the difference is exactly the ponded share. Coupled
+                // junctions always pond — SurfaceRouter2D assigns them the
+                // 2D-cell footprint as ponded_area and DynamicWave lets
+                // is_coupled bypass ALLOW_PONDING — so this budget is the
+                // right one and is non-zero whenever there is water to give.
                 const auto ni = static_cast(cp.node_idx);
+                const double ponded_1d =
+                    std::max(0.0, state_->nodes_1d->volume[ni] -
+                                      state_->nodes_1d->full_volume[ni]);
                 const double avail =
-                    std::max(0.0, state_->nodes_1d->volume[ni] *
-                                      opts_->vol_1d_to_2d) -
-                    node_drawn_[ni];
+                    ponded_1d * opts_->vol_1d_to_2d - node_drawn_[ni];
                 if (avail <= 0.0) continue;
                 const double want = -Q * dt_c;
                 const double take = std::min(want, avail);
+                // The shortfall is what the orifice law asked for and the
+                // node could not supply. Booked so it is visible instead of
+                // being absorbed by the 1D side's `y_new = max(y_new, 0)`
+                // floor, which would create the water silently.
+                spill_deficit_ += std::max(0.0, want - take);
                 node_drawn_[ni] += take;
                 Q = -take / dt_c;
             }
+            // S1: a 2D→1D drain (Q > 0) leaves at the cell's concentration
+            // and is booked per coupling point so S3's tuple can hand it to
+            // the node's qual_mass_in; a 1D→2D spill arrives at zero
+            // concentration until S3 carries the node's published value.
+            if (species_on_ && Q > 0.0) {
+                auto& tr = state_->transport;
+                const auto ns = static_cast(tr.n_species);
+                double* pt = (k * ns < tr.exch_mass.size())
+                                 ? &tr.exch_mass[k * ns] : nullptr;
+                sinkMassAtCellConc(ci, Q * dt_c, tr.lost_coupling, pt);
+            } else if (species_on_ && Q < 0.0) {
+                // S3 (D-2DT4): the spill arrives at the NODE's published
+                // concentration (`nodes.conc`, which all three 1D engines
+                // write), frozen for the batch like the node head. Nothing is
+                // queued back to the node: the CSTR mix already takes every
+                // outflow — the spill included — at the mixed concentration
+                // through the reduced inflow volume, so a debit here would
+                // remove the mass twice.
+                auto& tr = state_->transport;
+                const auto ns = static_cast(tr.n_species);
+                const auto ni = static_cast(cp.node_idx);
+                // S4: the router publishes every ROW's node value (pollutant
+                // conc, MSX conc, age, temperature) in one ns-strided array,
+                // frozen for the batch like the node head. nodes.conc alone
+                // is np-strided and would mis-index once age/temp rows exist.
+                const auto* conc_p = state_->node_row_conc;
+                if (conc_p && (ni + 1) * ns <= conc_p->size()) {
+                    const auto& conc = *conc_p;
+                    const double v_in = -Q * dt_c;
+                    if (!tr.cell_runoff_vol.empty())          // S7: inflow
+                        tr.cell_runoff_vol[ci] -= v_in;
+                    for (std::size_t s = 0; s < ns; ++s) {
+                        const double c = conc[ni * ns + s];
+                        if (c == 0.0) continue;
+                        const double g = v_in * c;
+                        tr.cell_mass[tr.idx(static_cast(s), ci)] += g;
+                        tr.gained_coupling[s] += g;
+                    }
+                    // The spill VOLUME is tracked per point so the router can
+                    // pair it against this window's drained mass — see
+                    // SurfaceTransportState::exch_spill. (An incremental
+                    // per-substep debit here is ORDER-DEPENDENT — a spill
+                    // substep that precedes the window's drain finds nothing
+                    // to debit — and the check measured the residue; the
+                    // pairing must be done at window granularity.)
+                    if (static_cast(k) < tr.exch_spill.size())
+                        tr.exch_spill[static_cast(k)] += v_in;
+                }
+            }
+            // C1: book the signed per-cell abstraction HERE, where the node
+            // exchange actually moves water. The other three sites book
+            // `coupling_flux`, which only ever carries the FORCING API's
+            // prescribed rate — the node coupling below never writes it, so
+            // booking only there left the per-cell series identically zero on
+            // every genuinely coupled deck while the domain totals grew.
+            // Sign follows the volume update: + = into the cell.
+            state_->coupling_applied[ci] += -Q * dt_c;
             state_->volume[ci] -= Q * dt_c;
             if (state_->volume[ci] < 0.0) state_->volume[ci] = 0.0;
             exch_[k] += Q * dt_c;
@@ -656,7 +1841,283 @@ void ExplicitInertialSolver::fireCells(const std::vector& cells,
     }
     // Head-ramp clock: tier-0 fires once per finest substep, so dt_c here is
     // exactly the wall the batch has advanced since the last exchange pass.
-    if (&cells == &cells_by_tier_[0]) exch_tau_ += dt_c;
+    if (tier0) exch_tau_ += dt_c;
+}
+
+
+
+// RECONSTRUCTION_ORDER 2: Green-Gauss gradients of (η, u, v) over the active
+// cells (face value = mean of the two cells; boundary faces zero-gradient),
+// limited per cell and variable with Barth–Jespersen against the min/max of
+// the cell and its face neighbours. Cells that are dry, thin (< 10·h_dry) or
+// touch a dry cell fall back to first order (φ = 0) — the wet/dry front keeps
+// the robust monotone update.
+void ExplicitInertialSolver::computeLimitedGradientsSwe() {
+    const auto& ed = edges_;
+    const int na = static_cast(active_cells_.size());
+    const double dry = opts_->dry_depth;
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+    for (int k = 0; k < na; ++k) {
+        const int i = active_cells_[static_cast(k)];
+        gex_[i] = gey_[i] = gux_[i] = guy_[i] = gvx_[i] = gvy_[i] = 0.0;
+        const double hi = state_->depth[i];
+        if (hi <= 10.0 * dry) continue;
+        const double ei = state_->head[i];
+        const double ui = qcx_[i] / hi, vi = qcy_[i] / hi;
+        double gx[3] = {0, 0, 0}, gy[3] = {0, 0, 0};
+        double wmin[3] = {ei, ui, vi}, wmax[3] = {ei, ui, vi};
+        bool ok = true;
+        int nfaces = 0;
+        for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+            const int e = ed.cell_edge[p];
+            const int j = (ed.cL[e] == i) ? ed.cR[e] : ed.cL[e];
+            const double hj = state_->depth[j];
+            if (hj <= dry || !cell_active_[j]) { ok = false; break; }
+            const double ej = state_->head[j], uj = qcx_[j] / hj, vj = qcy_[j] / hj;
+            const double sgn = static_cast(ed.cell_sign[p]);   // outward normal sign
+            const double nx = sgn * ed.nx[e] * ed.xi[e], ny = sgn * ed.ny[e] * ed.xi[e];
+            const double w[3] = {0.5 * (ei + ej), 0.5 * (ui + uj), 0.5 * (vi + vj)};
+            const double wj[3] = {ej, uj, vj};
+            for (int m = 0; m < 3; ++m) {
+                gx[m] += w[m] * nx; gy[m] += w[m] * ny;
+                wmin[m] = std::min(wmin[m], wj[m]); wmax[m] = std::max(wmax[m], wj[m]);
+            }
+            ++nfaces;
+        }
+        // Boundary faces (no CSR entry): zero-gradient contribution w_i·n̂·ξ.
+        const int nvc = mesh_->cell_vertex_count(i);
+        if (ok && nfaces < nvc) {
+            for (int kk = 0; kk < nvc; ++kk) {
+                if (mesh_->cell_neighbour(i, kk) >= 0) continue;
+                const int slot = MeshData::slot(i, kk);
+                const double nx = mesh_->edge_nx[slot] * mesh_->edge_length[slot];
+                const double ny = mesh_->edge_ny[slot] * mesh_->edge_length[slot];
+                gx[0] += ei * nx; gy[0] += ei * ny;
+                gx[1] += ui * nx; gy[1] += ui * ny;
+                gx[2] += vi * nx; gy[2] += vi * ny;
+            }
+        }
+        if (!ok || nfaces == 0) continue;
+        const double inv_a = 1.0 / mesh_->tri_area[i];
+        const double wi[3] = {ei, ui, vi};
+        double phi[3] = {1.0, 1.0, 1.0};
+        for (int m = 0; m < 3; ++m) { gx[m] *= inv_a; gy[m] *= inv_a; }
+        for (int p = ed.cell_ptr[i]; p < ed.cell_ptr[i + 1]; ++p) {
+            const double ax = ed.cell_arm_x[p], ay = ed.cell_arm_y[p];
+            for (int m = 0; m < 3; ++m) {
+                const double wf = wi[m] + gx[m] * ax + gy[m] * ay;
+                phi[m] = std::min(phi[m], swe::bjLimiter(wi[m], wf, wmin[m], wmax[m]));
+            }
+        }
+        gex_[i] = phi[0] * gx[0]; gey_[i] = phi[0] * gy[0];
+        gux_[i] = phi[1] * gx[1]; guy_[i] = phi[1] * gy[1];
+        gvx_[i] = phi[2] * gx[2]; gvy_[i] = phi[2] * gy[2];
+    }
+}
+
+// SSP-RK2 (Heun) over the global active lists: U¹ = U⁰ + Δt·L(U⁰),
+// U² = U¹ + Δt·L(U¹), Uⁿ⁺¹ = ½(U⁰ + U²). The per-advance ledgers that both
+// stages incremented (boundary ∫F dt, coupling ∫Q dt, infiltration applied)
+// are reset to their trapezoidal value, ½·(stage-1 + stage-2) increments.
+void ExplicitInertialSolver::runRk2Step(double dt) {
+    const int nt = mesh_->n_triangles();
+    // Member buffers: vector assignment reuses capacity, so no per-step
+    // allocation (F6).
+    rk_v0_  = state_->volume;
+    rk_qx0_ = qcx_;
+    rk_qy0_ = qcy_;
+    rk_bc0_ = bc_accum_; rk_ex0_ = exch_; rk_inf0_ = state_->infil_applied;
+    rk_cpl0_ = state_->coupling_applied;
+    rk_drawn0_ = node_drawn_;
+    for (int stage = 0; stage < 2; ++stage) {
+        fireFaces(active_faces_, dt, /*global_step=*/true);
+        fireCells(active_cells_, dt, /*tier0=*/true);
+    }
+    // Parallel over every cell. An INACTIVE cell was not fired by either
+    // stage, so its average is the identity (volume, q⃗ and the infiltration
+    // ledger are unchanged) and only the dry-momentum reset is evaluated —
+    // the same value the serial all-cell loop produced.
+#pragma omp parallel for schedule(static) num_threads(opts_->num_threads)
+    for (int i = 0; i < nt; ++i) {
+        if (cell_active_[i]) {
+            state_->volume[i] = 0.5 * (rk_v0_[i] + state_->volume[i]);
+            qcx_[i] = 0.5 * (rk_qx0_[i] + qcx_[i]);
+            qcy_[i] = 0.5 * (rk_qy0_[i] + qcy_[i]);
+            inertial::cellEtaDepth(*mesh_, *opts_, i, state_->volume[i],
+                                   state_->head[i], state_->depth[i]);
+            state_->infil_applied[i] =
+                rk_inf0_[i] + 0.5 * (state_->infil_applied[i] - rk_inf0_[i]);
+            // Same half-step average as every other accumulator the RK2
+            // predictor advanced: without it the coupling volume books the
+            // full predictor step while the volume books the average, and
+            // the per-cell series drifts from the domain totals.
+            state_->coupling_applied[i] =
+                rk_cpl0_[i] + 0.5 * (state_->coupling_applied[i] - rk_cpl0_[i]);
+        }
+        if (state_->depth[i] <= opts_->dry_depth) { qcx_[i] = 0.0; qcy_[i] = 0.0; }
+    }
+    for (std::size_t k = 0; k < bc_accum_.size(); ++k)
+        bc_accum_[k] = rk_bc0_[k] + 0.5 * (bc_accum_[k] - rk_bc0_[k]);
+    for (std::size_t k = 0; k < exch_.size(); ++k)
+        exch_[k] = rk_ex0_[k] + 0.5 * (exch_[k] - rk_ex0_[k]);
+    for (std::size_t k = 0; k < node_drawn_.size(); ++k)
+        node_drawn_[k] = rk_drawn0_[k] + 0.5 * (node_drawn_[k] - rk_drawn0_[k]);
+    accumulators_pending_ = false;
+    substeps_run_ += 2;
+    last_steps_   += 2;
+}
+
+// FULL_SWE ghost-cell boundary (2D_FULL_SWE plan §2.2 item 9). The ghost
+// state per type: WALL mirrors u_n; NORMAL_FLOW is transmissive
+// (zero-gradient); SPECIFIED_STAGE holds η_bc with the interior velocity;
+// SPECIFIED_FLOW / RATING_CURVE prescribe the per-metre discharge (outward
+// positive) with the interior depth, or the critical depth of that
+// discharge when the cell is dry (dry-bed inflow). The Riemann flux against
+// the ghost gives the mass flux (returned inflow-positive, m³/s) and the
+// momentum change, which is applied to the cell here (tier-0 cadence, after
+// the parallel cell pass — the same slot the inertial law's Perot completion
+// uses).
+double ExplicitInertialSolver::boundaryFluxSwe(std::size_t k, int i, double dt_c) {
+    const int    idx = bc_slot_[k];
+    const auto   bt  = static_cast(state_->boundary->edge_bc_type[idx]);
+    const double L   = mesh_->edge_length[idx];
+    if (L <= 1.0e-12) return 0.0;
+    const double nx = mesh_->edge_nx[idx], ny = mesh_->edge_ny[idx];   // outward
+    const double eta_i = state_->head[i], h_i = state_->depth[i];
+    const double z_i   = eta_i - h_i;
+    const double dry   = opts_->dry_depth;
+    const double qx_i  = qcx_[i], qy_i = qcy_[i];
+    double u_n = 0.0, u_t = 0.0;
+    if (h_i > dry) {
+        const double ux = qx_i / h_i, uy = qy_i / h_i;
+        u_n = ux * nx + uy * ny;
+        u_t = -ux * ny + uy * nx;
+    }
+    // Ghost (h_g, u_ng, u_tg) in the outward-normal frame.
+    double h_g = h_i, un_g = u_n, ut_g = u_t, eta_g = eta_i;
+    // A prescribed-discharge boundary imposes its mass flux exactly; the
+    // Riemann solve below then only supplies the momentum flux.
+    bool   prescribed_mass = false;
+    double q_prescribed    = 0.0;      // outward-positive, per metre of edge
+    switch (bt) {
+        case BoundaryType::WALL:
+            un_g = -u_n;
+            break;
+        case BoundaryType::NORMAL_FLOW: {
+            // Manning normal-flow outlet, the same law the local-inertial and
+            // diffusive paths apply (SurfaceFluxCalculator::boundaryEdgeFlux):
+            // per-metre outflow q = h^{5/3}·sqrt(S)/n. Under FULL_SWE this used
+            // to be a bare zero-gradient ghost, i.e. the bed slope the modeller
+            // set on the edge did nothing.
+            // The slope is SIGNED: positive falls away from the domain and
+            // drains it (unchanged), negative falls toward it and feeds it.
+            // A negative slope cannot bootstrap a DRY cell — the law conveys
+            // with the interior depth, and h_i = 0 carries nothing; use a
+            // SPECIFIED_FLOW edge for dry-bed inflow, which reconstructs the
+            // critical depth of its discharge.
+            const double S = state_->boundary->edge_bed_slope[idx];
+            const double n_man = mesh_->mannings_n[i];
+            prescribed_mass = true;
+            if (S != 0.0 && h_i > 0.0 && n_man > 0.0) {
+                const double sgnS = (S > 0.0) ? 1.0 : -1.0;
+                const double h53 = h_i * std::cbrt(h_i * h_i);
+                q_prescribed = sgnS * h53 * std::sqrt(std::fabs(S)) / n_man; // outward +
+                un_g = q_prescribed / h_i;
+                ut_g = u_t;
+            } else {
+                // No slope, no depth, no roughness: the law conveys nothing.
+                // The mirror ghost keeps the momentum consistent with that —
+                // a bare zero-gradient ghost is an ABSORBING boundary and
+                // drained a lake at rest through an inert outlet.
+                q_prescribed = 0.0;
+                un_g = -u_n;
+            }
+            break;
+        }
+        case BoundaryType::SPECIFIED_STAGE: {
+            const double eta_bc = state_->boundary->edge_bc_head[idx];
+            const double c_i = std::sqrt(swe::kGravity * std::max(h_i, 0.0));
+            if (h_i > dry && u_n >= c_i) {
+                // Supercritical OUTFLOW: no characteristic enters the domain,
+                // the prescribed stage cannot act — transmissive ghost.
+                break;
+            }
+            eta_g = eta_bc;
+            h_g   = (eta_bc - z_i > 0.0) ? eta_bc - z_i : 0.0;
+            // Subcritical: the outgoing Riemann invariant u_n + 2c fixes the
+            // ghost velocity for the prescribed depth (characteristic
+            // extrapolation), instead of a bare copy of the interior velocity.
+            if (h_i > dry && h_g > 0.0)
+                un_g = u_n + 2.0 * (c_i - std::sqrt(swe::kGravity * h_g));
+            break;
+        }
+        case BoundaryType::SPECIFIED_FLOW:
+        case BoundaryType::RATING_CURVE: {
+            // A prescribed discharge is a FLUX boundary: the mass flux is the
+            // prescribed value (imposed below, as the local-inertial law does
+            // in SurfaceFluxCalculator), not whatever a Riemann problem
+            // against a ghost happens to deliver. The ghost still sets the
+            // MOMENTUM flux and keeps the Audusse pressure balance, so its
+            // depth should be the physical boundary depth:
+            //   * dry cell            — critical depth (dry-bed inflow),
+            //   * subcritical inflow  — from the outgoing invariant u + 2c
+            //                           together with q (one characteristic
+            //                           leaves, so depth is NOT free),
+            //   * supercritical inflow / any outflow — the interior depth.
+            const double q_out = state_->boundary->edge_bc_flow[idx];   // outward +
+            if (h_i > dry) {
+                h_g = h_i;
+                if (q_out < 0.0) {                       // inflow
+                    const double c_i = std::sqrt(swe::kGravity * h_i);
+                    if (std::fabs(u_n) < c_i)            // subcritical
+                        h_g = swe::depthFromInvariantAndDischarge(
+                            u_n + 2.0 * c_i, q_out, h_i);
+                }
+                eta_g = z_i + h_g;
+            } else {
+                h_g  = swe::criticalDepth(std::fabs(q_out));
+                eta_g = z_i + h_g;
+            }
+            un_g = (h_g > 0.0) ? q_out / h_g : 0.0;
+            ut_g = 0.0;
+            prescribed_mass = true;
+            q_prescribed    = q_out;
+            break;
+        }
+    }
+    // Interior = L, ghost = R, normal outward; velocities re-expressed as
+    // (x, y) unit discharges for the shared kernel.
+    const double qxg = h_g * (un_g * nx - ut_g * ny);
+    const double qyg = h_g * (un_g * ny + ut_g * nx);
+    swe::FaceFlux F;
+    double cLx, cLy, cRx, cRy;
+    const bool wet = swe::faceFlux(eta_i, h_i, qx_i, qy_i,
+                                   eta_g, h_g, qxg, qyg,
+                                   nx, ny, dry, F, cLx, cLy, cRx, cRy);
+    const double conv = mesh_->edge_conveyance[idx];
+    // A prescribed inflow must reach a DRY cell too — faceFlux reports "not
+    // wet" there (both reconstructed depths vanish), and returning 0 would
+    // make a dry-bed inflow boundary inert.
+    if (!wet)
+        return prescribed_mass ? -q_prescribed * conv * L : 0.0;
+    const double A = mesh_->tri_area[i];
+    // Momentum booked now (the mass is applied by the caller with the v ≥ 0
+    // clamp; a clamp rescales the momentum in the same ratio there).
+    const double fmx = -F.mx * conv + cLx, fmy = -F.my * conv + cLy;
+    // Remembered so the caller can rescale it in the same ratio when its
+    // availability clamp shrinks the mass (the boundary loop is serial).
+    swe_bc_dqx_ = fmx * L * dt_c / A;
+    swe_bc_dqy_ = fmy * L * dt_c / A;
+    qcx_[i] += swe_bc_dqx_;
+    qcy_[i] += swe_bc_dqy_;
+    // Mass: the prescribed discharge verbatim (the local-inertial law's
+    // contract, SurfaceFluxCalculator::boundaryEdgeFlux) — the Riemann
+    // solve's own mass flux is a wave-speed-weighted BLEND of the interior
+    // and prescribed states, which under-delivered the SWASHES bump inflows
+    // by 7-21 % and reversed a supercritical inlet outright.
+    if (prescribed_mass)
+        return -q_prescribed * conv * L;
+    return -F.mass * conv * L;                            // inflow-positive m³/s
 }
 
 void ExplicitInertialSolver::runMacroCycle(double dt0, int nsub) {
@@ -680,6 +2141,11 @@ void ExplicitInertialSolver::runMacroCycle(double dt0, int nsub) {
             if (s % (1 << k)) continue;
             if (!edges_by_tier_[k].empty())
                 fireFaces(edges_by_tier_[k], (1 << k) * dt0);
+            // G1: the subsurface's lateral Darcy faces ride the SAME rung of
+            // the SAME ladder. Its tier lists are its own (G-A), so a GW face
+            // fires here only if the groundwater's stability step put it on
+            // rung k — the two domains share the cadence, not the criterion.
+            if (gw_) gw_->fireGwFaces(k, (1 << k) * dt0);
         }
         if (dbg_invariant) {
             const double inv1 = invariant();
@@ -691,8 +2157,17 @@ void ExplicitInertialSolver::runMacroCycle(double dt0, int nsub) {
         for (int k = 0; k < K; ++k) {
             if (s % (1 << k)) continue;
             if (!cells_by_tier_[k].empty() || k == 0)
-                fireCells(cells_by_tier_[k], (1 << k) * dt0);
+                fireCells(cells_by_tier_[k], (1 << k) * dt0, k == 0);
+            // The GW cells of this rung fire AFTER the surface cells of the
+            // same rung, so a cell that infiltrated in this substep hands the
+            // water down within the substep rather than a rung later.
+            if (gw_) gw_->fireGwCells(k, (1 << k) * dt0, *state_);
         }
+        // Node exchange is sampled at tier-0 cadence against the batch-frozen
+        // 1D heads, exactly like the surface's junction exchange, and booked
+        // into the GW cells' accumulators (G-B) rather than applied directly.
+        if (gw_ && state_->nodes_1d)
+            gw_->sampleNodeExchange(state_->nodes_1d, dt0);
         if (dbg_invariant) {
             const double inv2 = invariant();
             if (std::fabs(inv2 - inv0) > 1.0e-9 * (std::fabs(inv0) + 1.0))
@@ -717,6 +2192,12 @@ double ExplicitInertialSolver::advance(double t_current, double t_target) {
     std::fill(bc_accum_.begin(), bc_accum_.end(), 0.0);
     std::fill(exch_.begin(), exch_.end(), 0.0);
     std::fill(node_drawn_.begin(), node_drawn_.end(), 0.0);
+    // S1: the per-point species drain resets with the per-point volume drain
+    // it rides on, so S3's tuple reads one advance's worth and not a total.
+    std::fill(state_->transport.exch_mass.begin(),
+              state_->transport.exch_mass.end(), 0.0);
+    std::fill(state_->transport.exch_spill.begin(),
+              state_->transport.exch_spill.end(), 0.0);
     exch_tau_ = 0.0;
     last_steps_ = 0;
     // Rebuild cadence persists ACROSS advances: under windowless co-advance
@@ -727,7 +2208,8 @@ double ExplicitInertialSolver::advance(double t_current, double t_target) {
     int cycles_since_rebuild = cycles_since_rebuild_;
 
     while (t < t_target) {
-        if (cycles_since_rebuild >= kRebuildEveryCycles) {
+        if (cycles_since_rebuild >= kRebuildEveryCycles ||
+            (front_breach_ && cycles_since_rebuild > 0)) {
             syncAndRebuild(t);
             cycles_since_rebuild = 0;
         } else {
@@ -737,40 +2219,86 @@ double ExplicitInertialSolver::advance(double t_current, double t_target) {
         const int nsub_full = 1 << (K - 1);
         const double remaining = t_target - t;
 
-        if (active_cells_.empty()) {
+        // G1-c item 2 (2026-09-19): a quiescent SURFACE no longer strides
+        // the window when an aquifer is live — the groundwater's lateral
+        // Darcy flow, deep loss, ET and node exchange fire on the ladder
+        // whether or not any surface cell is wet, and a dry cell the aquifer
+        // exfiltrates into is seeded active by syncAndRebuild's pending pass.
+        // Before this the whole macro cycle was skipped, so a dry summer
+        // froze the water table in place.
+        if (active_cells_.empty() && !(gw_ && gw_->active())) {
             // Quiescent: stride the window; the lazy tier keeps accumulating.
             t = t_target;
             last_dt_ = remaining;
             break;
         }
 
-        double dt0 = std::min(dt0_, remaining);
-        int    nsub = nsub_full;
-        if (nsub_full * dt0_ > remaining) {
-            // Tail: not enough room for a full macro cycle — degenerate to
-            // global-dt stepping so the window lands exactly. Settle pending
-            // transfers first: the re-tiering below invalidates the cap
-            // bookkeeping of any in-flight accumulator.
+        if (nsub_full * dt0_ <= remaining) {
+            // Full macro cycle fits (dt0_ <= remaining here, so no clamp).
+            if (second_order_) runRk2Step(dt0_);      // K == 1: one global step
+            else               runMacroCycle(dt0_, nsub_full);
+            t += nsub_full * dt0_;
+            last_dt_ = dt0_;
+            ++cycles_since_rebuild;
+            continue;
+        }
+
+        // Tail: not enough room for a full macro cycle — split the WHOLE
+        // remaining span into nt EQUAL global substeps so the window lands
+        // exactly with no degenerate step. nt = ceil(remaining/dt0_) is at
+        // most the substep count the un-split tail sequence took, and each
+        // dt_tail = remaining/nt is in (dt0_/2, dt0_] for nt >= 2 — still
+        // CFL-safe, never arbitrarily small. Settle pending transfers first:
+        // a cell about to be stepped out of cadence must not carry an
+        // in-flight accumulator whose cap bookkeeping assumed the tiered
+        // schedule.
+        //
+        // This used to be expressed by collapsing every cell and face to
+        // tier 0 and running a ONE-substep macro cycle at dt0 = remaining,
+        // which cost an O(n_cells + n_faces) re-tiering, forced a full
+        // syncAndRebuild on the next entry, and — because the leftover has
+        // no floor — fired degenerate substeps (down to ~1e-13 s when the
+        // macro path's `t += nsub*dt0` landed 1 ulp short of t_target).
+        // Firing the union lists directly is the same arithmetic in the
+        // same order (the collapsed tier-0 lists WERE these lists) and
+        // leaves the tiering intact, so the rebuild keeps its own cadence.
+        {
+            // Sub-ulp residue (macro landing shortfall): land without
+            // firing physics on a span below any numerical significance.
+            if (remaining <= dt0_ * 1.0e-9) {
+                t = t_target;
+                break;
+            }
             settleAccumulators();
-            nsub = 1;
-            for (auto& v : edges_by_tier_) v.clear();
-            for (auto& v : cells_by_tier_) v.clear();
-            for (int i : active_cells_) {
-                tier_[i] = 0;
-                cells_by_tier_[0].push_back(i);
-            }
-            for (int e = 0; e < edges_.ne; ++e)
-                if (cell_active_[edges_.cL[e]] && cell_active_[edges_.cR[e]]) {
-                    face_tier_[e] = 0;
-                    edges_by_tier_[0].push_back(e);
+            const int nt = std::max(
+                1, static_cast(std::ceil(remaining / dt0_)));
+            const double dt_tail = remaining / nt;
+            const int Kgw = static_cast(cells_by_tier_.size());
+            for (int s = 0; s < nt; ++s) {
+                if (second_order_) { runRk2Step(dt_tail); continue; }
+                fireFaces(active_faces_, dt_tail, /*global_step=*/true);
+                // G-X1 (2026-09-19): the tail fires the aquifer too. It
+                // used to fire the surface lists only, so on a deck whose
+                // routing step never fits a full macro cycle (a variable
+                // 1D step, or a step just under dt0) the groundwater never
+                // advanced at all — no lateral flow, no node exchange.
+                // Every GW tier fires once at the tail step, the same
+                // collapse the surface lists get.
+                if (gw_) for (int k = 0; k < Kgw; ++k) gw_->fireGwFaces(k, dt_tail);
+                fireCells(active_cells_, dt_tail, /*tier0=*/true);
+                if (gw_) {
+                    for (int k = 0; k < Kgw; ++k) gw_->fireGwCells(k, dt_tail, *state_);
+                    if (state_->nodes_1d) gw_->sampleNodeExchange(state_->nodes_1d, dt_tail);
                 }
-            cycles_since_rebuild = kRebuildEveryCycles;  // rebuild after tail
+                ++substeps_run_;
+                ++last_steps_;
+            }
+            accumulators_pending_ = false;   // every side just gathered
+            last_dt_ = dt_tail;
+            ++cycles_since_rebuild;
+            t = t_target;   // exact landing — no 1-ulp re-entry
+            break;
         }
-
-        runMacroCycle(dt0, nsub);
-        t += nsub * dt0;
-        last_dt_ = dt0;
-        ++cycles_since_rebuild;
     }
 
     cycles_since_rebuild_ = cycles_since_rebuild;
@@ -795,17 +2323,26 @@ double ExplicitInertialSolver::advance(double t_current, double t_target) {
     std::fill(state_->edge_flux.begin(), state_->edge_flux.end(), 0.0);
     const bool vfr_face =
         (opts_->face_reconstruction == FaceDepth2D::VFR_FACE);
-    for (int e = 0; e < edges_.ne; ++e) {
-        const double hf = vfr_face
-            ? inertial::faceFlowDepthVfr(state_->head[edges_.cL[e]],
-                                         state_->head[edges_.cR[e]],
-                                         edges_.ze_lo[e], edges_.ze_hi[e])
-            : inertial::faceFlowDepth(state_->head[edges_.cL[e]],
-                                      state_->head[edges_.cR[e]],
-                                      edges_.zface[e]);
+    // Only the ACTIVE faces can carry flux: a face with an inactive side had
+    // its q zeroed when the side deactivated, so the old full sweep spent
+    // O(n_faces) recomputing a face depth and a Froude cap in order to publish
+    // the zero the fill above already wrote. Identical output, and a quiescent
+    // tail (active fraction reached 0.0 % in the storm run) now costs nothing.
+    for (const int e : active_faces_) {
         double qp = 0.0;
-        if (hf > opts_->dry_depth)
-            qp = inertial::froudeCap(q_[e], hf, opts_->froude_max);
+        if (mode_ == Momentum2D::LOCAL_INERTIAL) {
+            const double hf = vfr_face
+                ? inertial::faceFlowDepthVfr(state_->head[edges_.cL[e]],
+                                             state_->head[edges_.cR[e]],
+                                             edges_.ze_lo[e], edges_.ze_hi[e])
+                : inertial::faceFlowDepth(state_->head[edges_.cL[e]],
+                                          state_->head[edges_.cR[e]],
+                                          edges_.zface[e]);
+            if (hf > opts_->dry_depth)
+                qp = inertial::froudeCap(q_[e], hf, opts_->froude_max);
+        } else {
+            qp = q_[e];   // last evaluated face mass flux (already limited)
+        }
         const double F = qp * edges_.xi[e];
         state_->edge_flux[edges_.slotL[e]] = -F;
         state_->edge_flux[edges_.slotR[e]] = +F;
@@ -826,6 +2363,15 @@ void ExplicitInertialSolver::reinitialize(double /*t0*/) {
     std::fill(bc_q_.begin(), bc_q_.end(), 0.0);
     std::fill(facc_L_.begin(), facc_L_.end(), 0.0);
     std::fill(facc_R_.begin(), facc_R_.end(), 0.0);
+    std::fill(macc_x_L_.begin(), macc_x_L_.end(), 0.0);
+    std::fill(macc_x_R_.begin(), macc_x_R_.end(), 0.0);
+    std::fill(macc_y_L_.begin(), macc_y_L_.end(), 0.0);
+    std::fill(macc_y_R_.begin(), macc_y_R_.end(), 0.0);
+    if (mode_ == Momentum2D::FULL_SWE) {
+        std::fill(qcx_.begin(), qcx_.end(), 0.0);
+        std::fill(qcy_.begin(), qcy_.end(), 0.0);
+    }
+    accumulators_pending_ = false;
     reconstructAll();
 }
 
@@ -839,7 +2385,7 @@ void ExplicitInertialSolver::resyncFromVolumes(double /*t0*/) {
 
 void ExplicitInertialSolver::finalize() {
     if (!telemetry_path_.empty() && !telemetry_.empty()) {
-        if (std::FILE* f = std::fopen(telemetry_path_.c_str(), "w")) {
+        if (std::FILE* f = openswmm::io::fopen_utf8(telemetry_path_, "w")) {
             std::fprintf(f, "t_s,active_cells,active_frac\n");
             const double nt = std::max(1, mesh_ ? mesh_->n_triangles() : 1);
             for (const auto& [t, n] : telemetry_)
@@ -849,11 +2395,15 @@ void ExplicitInertialSolver::finalize() {
     }
     q_.clear(); qcx_.clear(); qcy_.clear();
     facc_L_.clear(); facc_R_.clear();
+    macc_x_L_.clear(); macc_x_R_.clear(); macc_y_L_.clear(); macc_y_R_.clear();
+    dw_slope_.clear();
     cell_active_.clear(); active_cells_.clear();
     tier_.clear(); face_tier_.clear();
     cells_by_tier_.clear(); edges_by_tier_.clear();
     bc_cell_.clear(); bc_slot_.clear(); bc_accum_.clear(); bc_q_.clear();
     telemetry_.clear();
+    active_frac_min_ = 1.0e30; active_frac_max_ = -1.0e30;
+    active_frac_sum_ = 0.0;    active_samples_  = 0;
     initialized_ = false;
 }
 
@@ -864,20 +2414,13 @@ ISurfaceSolver::RunStats ExplicitInertialSolver::run_stats() const noexcept {
     s.last_h = last_dt_;
 
     // Marcher telemetry for the report block: active-fraction spread over the
-    // rebuild samples + cumulative tier-occupancy histogram. Must be read
-    // BEFORE finalize() (which clears telemetry_) — SurfaceRouter2D does.
-    if (!telemetry_.empty() && mesh_ && mesh_->n_triangles() > 0) {
-        const double nt = static_cast(mesh_->n_triangles());
-        double mn = 1.0e30, mx = -1.0e30, sum = 0.0;
-        for (const auto& [t, n] : telemetry_) {
-            const double frac = n / nt;
-            mn = std::min(mn, frac);
-            mx = std::max(mx, frac);
-            sum += frac;
-        }
-        s.active_frac_min  = mn;
-        s.active_frac_max  = mx;
-        s.active_frac_mean = sum / static_cast(telemetry_.size());
+    // rebuild samples (folded as they are taken — see syncAndRebuild) +
+    // cumulative tier-occupancy histogram. Must be read BEFORE finalize()
+    // (which resets the statistics) — SurfaceRouter2D does.
+    if (active_samples_ > 0) {
+        s.active_frac_min  = active_frac_min_;
+        s.active_frac_max  = active_frac_max_;
+        s.active_frac_mean = active_frac_sum_ / static_cast(active_samples_);
     }
     s.n_tiers = static_cast(
         std::min(cells_by_tier_.size(), tier_occupancy_.size()));
diff --git a/src/engine/2d/solver/ExplicitInertialSolver.hpp b/src/engine/2d/solver/ExplicitInertialSolver.hpp
index e37451e3d..135412004 100644
--- a/src/engine/2d/solver/ExplicitInertialSolver.hpp
+++ b/src/engine/2d/solver/ExplicitInertialSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExplicitInertialSolver.hpp
  * @brief Explicit local-inertial FV time-marcher for the 2D surface.
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_EXPLICIT_INERTIAL_SOLVER_HPP
@@ -35,9 +51,12 @@
 
 #include "ISurfaceSolver.hpp"
 #include "InertialEdges.hpp"
+#include "../data/SolverOptions2D.hpp"   // Momentum2D
 
 namespace openswmm::twoD {
 
+class SubsurfaceSolver;   // G1: the two-zone groundwater kernel, if authored
+
 class ExplicitInertialSolver final : public ISurfaceSolver {
 public:
     void initialize(MeshData& mesh, SurfaceStateData& state,
@@ -56,6 +75,12 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
         return exch_;
     }
 
+    /// C3: cumulative spill volume (m³) the coupled nodes could not supply
+    /// from their ponded storage. Should stay 0 on a well-posed deck; a
+    /// growing value means the orifice is sized to move more water than the
+    /// nodes hold above the rim.
+    double spillDeficit() const noexcept { return spill_deficit_; }
+
 private:
     // Recompute η/depth from state volumes for the whole mesh.
     void reconstructAll();
@@ -74,11 +99,20 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
     void refreshDt0();
     // Fire one tier's faces over their Δt: inertial update + Froude cap +
     // face-cadence positivity share, booking ±ΔM into both side accumulators.
-    void fireFaces(const std::vector& faces, double dt_f);
+    // global_step = every active cell fires at this same Δt (the window tail),
+    // so a face's exporter republishes its volume every time this face does
+    // and the positivity share is NOT divided down by a refire ratio.
+    void fireFaces(const std::vector& faces, double dt_f,
+                   bool global_step = false);
     // Fire one tier's cells over their Δt: gather + clear own-side face
     // accumulators, apply sources, refresh closure + Perot vector; tier-0
     // firings also evaluate the availability-clamped boundary edges.
-    void fireCells(const std::vector& cells, double dt_c);
+    // tier0 = this firing carries the tier-0 cadence work (boundary edges and
+    // the live junction exchange), which fires once per finest substep.
+    void fireCells(const std::vector& cells, double dt_c, bool tier0);
+    /// Closure-specialised body of fireCells (kSwe = FULL_SWE momentum update).
+    template 
+    void fireCellsImpl(const std::vector& cells, double dt_c, bool tier0);
     // One halving-order macro cycle of nsub base substeps: tier k fires every
     // 2^k substeps.
     void runMacroCycle(double dt0, int nsub);
@@ -88,10 +122,83 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
     SolverOptions2D*  opts_  = nullptr;
 
     InertialEdges edges_;
-    std::vector  q_;            ///< per unique interior face (m²/s)
-    std::vector  qcx_, qcy_;    ///< Perot cell discharge vector (θ < 1)
+    /// Per unique interior face (m²/s). LOCAL_INERTIAL: the prognostic face
+    /// discharge. FULL_SWE / DIFFUSIVE_WAVE: the last evaluated face mass
+    /// flux per unit width (diagnostic — published as edge_flux).
+    std::vector  q_;
+    /// LOCAL_INERTIAL: Perot cell discharge vector (θ < 1 / ADVECTION).
+    /// FULL_SWE: the PROGNOSTIC cell-mean unit discharge (h·u, h·v), m²/s.
+    std::vector  qcx_, qcy_;
+
+    // -----------------------------------------------------------------------
+    // Momentum closure (MOMENTUM_EQUATION, 2D_FULL_SWE plan §2.1). One
+    // marcher, three face laws; everything below the face/cell kernels
+    // (tiers, active sets, positivity, coupling, transport) is shared.
+    // -----------------------------------------------------------------------
+    Momentum2D mode_ = Momentum2D::LOCAL_INERTIAL;
+    /// Mesh carries at least one quad (2D_PERF_REGRESSION_DIAGNOSIS §2 F1):
+    /// resolved ONCE in initialize(). MeshData::n_quads() is an O(n_cells)
+    /// scan and was being re-run at the top of every face-tier fire.
+    bool       has_quads_ = false;
+    /// FULL_SWE: CSR of WALL boundary slots per cell (wall_ptr_[i] ..
+    /// wall_ptr_[i+1]) so the mirror-flux booking touches only the perimeter
+    /// cells that have one (F5); every other cell's row is empty.
+    std::vector     wall_ptr_, wall_slot_;
+    /// FULL_SWE momentum accumulators per face side (m⁴/s = m²·m²/s): the
+    /// x/y momentum the face booked for cL / cR, gathered and cleared by the
+    /// cell exactly like facc_L_/facc_R_ (same writer, same cadence).
+    std::vector  macc_x_L_, macc_x_R_, macc_y_L_, macc_y_R_;
+    /// Momentum the last boundaryFluxSwe() call booked into qcx_/qcy_, so its
+    /// caller can rescale it when the availability clamp shrinks the mass.
+    /// Scalar: the boundary loop is serial (perimeter-sized).
+    double               swe_bc_dqx_ = 0.0, swe_bc_dqy_ = 0.0;
+    /// RECONSTRUCTION_ORDER 2 (FULL_SWE): limited Green-Gauss gradients of
+    /// (η, u, v) per cell, refreshed at every face pass, and the SSP-RK2
+    /// stage buffers. Empty at order 1.
+    bool                 second_order_ = false;
+    std::vector  gex_, gey_, gux_, guy_, gvx_, gvy_;
+    std::vector  rk_v0_, rk_qx0_, rk_qy0_;
+    /// Stage-0 copies of the per-advance ledgers (F6): members so the RK2
+    /// step allocates nothing.
+    std::vector  rk_inf0_, rk_bc0_, rk_ex0_, rk_drawn0_, rk_cpl0_;
+    void computeLimitedGradientsSwe();
+    /// One SSP-RK2 (Heun) step of length dt over the active lists: two
+    /// forward-Euler substeps averaged with the start state; the ledgers
+    /// that accumulated over both stages are halved to the trapezoidal value.
+    void runRk2Step(double dt);
+    /// FRONT_REBUILD: frontier_[i] = 1 for an active cell with at least one
+    /// inactive neighbour (the outer ring of the halo). When such a cell
+    /// crosses the activation depth the front has used up the halo, and the
+    /// next macro cycle rebuilds the active set instead of waiting for the
+    /// cadence (front_breach_).
+    bool                 front_rebuild_ = false;
+    std::vector frontier_;
+    bool                 front_breach_  = false;
+    double               h_on_front_    = 0.0;   ///< activation depth of the last rebuild
+    /// DIFFUSIVE_WAVE: per-cell largest |surface slope| over its faces, from
+    /// the last rebuild/refresh — the explicit diffusion step bound's slope.
+    std::vector  dw_slope_;
+    /// Face kernels of the three closures (fireFaces dispatches on mode_).
+    void fireFacesInertial(const std::vector& faces, double dt_f, bool global_step);
+    void fireFacesSwe(const std::vector& faces, double dt_f, bool global_step);
+    void fireFacesDiffusive(const std::vector& faces, double dt_f, bool global_step);
+    /// Species advection + dispersion booked on face e for the mass transfer
+    /// dM (m³, positive cL→cR) at face depth hf — shared by every closure.
+    void bookFaceSpecies(int e, int a, int b, double dM, double hf, double dt_f,
+                         bool global_step) noexcept;
+    /// FULL_SWE ghost-cell Riemann boundary flux for BC entry k on cell i:
+    /// returns the inflow-positive volumetric flux (m³/s) and adds the
+    /// momentum change (with the bed-slope correction) to the cell's q⃗.
+    double boundaryFluxSwe(std::size_t k, int i, double dt_c);
+    /// DIFFUSIVE_WAVE step bound helper: refresh dw_slope_ for the active cells.
+    void refreshDiffusiveSlopes();
     std::vector cell_active_;
     std::vector     active_cells_;
+    /// Every face with both sides active, ascending — the union of the face
+    /// tier lists, in the order the tier-0 list would have carried them after
+    /// a collapse. Rebuilt with the tier lists; fired as one list by the
+    /// window tail.
+    std::vector     active_faces_;
     std::vector pin_t0_;       ///< cells pinned active + tier 0
                                         ///< (boundary + live coupling)
 
@@ -101,10 +208,66 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
     // identical ±ΔM into facc_L_/facc_R_ (single writer per face); each cell
     // applies + clears its own side at its own firing — conservation across
     // tier interfaces is exact by construction.
+    /// Rebuild scratch, held as members so a rebuild allocates nothing:
+    /// the seed flags (n_triangles) and the per-active-cell CFL step.
+    std::vector rebuild_seed_;
+    std::vector  rebuild_dt_cell_;
+    /// Per-thread minima for the rebuild's CFL reduction (min is exact and
+    /// order-independent, so any partition gives the identical dt0).
+    std::vector  rebuild_dt_partial_;
+
     std::vector tier_;         ///< per-cell tier
     std::vector face_tier_;    ///< per unique face
     std::vector  facc_L_;       ///< pending ΔM for the cL side (m³)
     std::vector  facc_R_;       ///< pending ΔM for the cR side (m³)
+
+    // S1 — species mass rides the SAME face accumulators, one pair per
+    // species, [s * ne + e]. Booked in fireFaces immediately after the volume
+    // ΔM, from the FINAL qn1 (after the Froude cap and the positivity share),
+    // at the exporting cell's concentration read at that same substep;
+    // gathered and cleared in fireCells alongside the volume side. That is
+    // D-2DT2: the species flux inherits the volume flux's tier cadence rather
+    // than reproducing it, so conservation across tier interfaces is the
+    // marcher's own property and not a second one to prove. Empty unless
+    // `state_->transport.active()`.
+    std::vector  sacc_L_;
+    std::vector  sacc_R_;
+    /// S7: "transport rows are live" — set with the accumulators above. The
+    /// sites used to test `!sacc_L_.empty()`, which is ALSO empty on a mesh
+    /// with no interior edge (one cell), where every species sink and source
+    /// then silently skipped while the rows were active.
+    bool                 species_on_ = false;
+    /// Exporter concentration for a species at a cell, read against the
+    /// cell's CURRENT published volume — the same volume the positivity share
+    /// budgets against, so cumulative species takes are bounded by the same
+    /// β share as the water and mass cannot go negative where volume cannot.
+    double donorConc(int s, int cell) const noexcept;
+    /// Remove `dv_m3` of water from cell `i` at the cell's concentration and
+    /// book it to `ledger` — infiltration, boundary outflow, coupling drain.
+    /// Evaporation deliberately does NOT go through here: it removes volume
+    /// and no mass, so the concentration rises (§2.3 of the plan).
+    void sinkMassAtCellConc(int i, double dv_m3, std::vector& ledger,
+                            double* per_point_ledger = nullptr) noexcept;
+    /// S2: rainfall of `rain_m3` on cell `i` brings species at the
+    /// `[POLLUTANTS]` rain concentration; booked to the gained ledger.
+    void addRainMass(int i, double rain_m3) noexcept;
+    /// T7.1: sink this cell's infiltration mass and, when an aquifer is
+    /// transporting under it, hand that exact mass to the aquifer.
+    void gwInfiltrationSeam(int i, double infil_m3) noexcept;
+    /// S3: outfall discharge onto cell `i` over `area_dt = area·dt` brings
+    /// species at `transport.coupling_src` (mass-rate density); gained ledger.
+    void addCouplingSourceMass(int i, double area_dt) noexcept;
+    /// S4/S4b: evaporation of `evap_m3` from cell `i` leaves at the cell's
+    /// own temperature AND its own mean age (the two intensive rows —
+    /// temperature-volume and age-volume); solutes concentrate (S1).
+    void sinkIntensiveRowsWithEvap(int i, double evap_m3) noexcept;
+    /// False when every booked ΔM is known to have been consumed already —
+    /// true after a GLOBAL substep, where every active face fired and then
+    /// every active cell gathered both of its sides (faces touching an
+    /// inactive cell carry q = 0 and were zeroed when it deactivated). Under
+    /// per-routing-step coupling every substep is global, so without this the
+    /// marcher walked the whole per-cell CSR once per substep to find nothing.
+    bool accumulators_pending_ = false;
     std::vector> cells_by_tier_;
     std::vector> edges_by_tier_;
     double dt0_ = 0.0;                  ///< base (tier-0) step from the rebuild
@@ -129,6 +292,13 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
     // volume so fill-and-spill thrash is structurally impossible.
     std::vector  exch_;
     std::vector  node_drawn_;   ///< spill drawn per node this advance (m³)
+    /// C3: cumulative volume (m³) the orifice law asked a node for and the
+    /// node's PONDED storage could not supply. Not an error — a spill that
+    /// empties the ponded water is the physically right outcome — but it must
+    /// be visible, because the 1D side's `y_new = max(y_new, 0)` floor would
+    /// otherwise absorb an over-draw silently and create water. A validator
+    /// watches this against zero on a well-posed deck.
+    double               spill_deficit_ = 0.0;
 
 public:
     /// Experimental (OPENSWMM_2D_HEAD_RAMP): per-coupling-point 1D head trend
@@ -157,10 +327,40 @@ class ExplicitInertialSolver final : public ISurfaceSolver {
     // rebuild; dumped as CSV at finalize() when OPENSWMM_2D_MARCHER_TELEMETRY
     // names a file. The Phase-1 gate reads this to verify the thin-film budget
     // assumption on the Bellinge storm slice.
-    std::vector> telemetry_;
+    std::vector> telemetry_;   ///< kept ONLY when telemetry_path_ is set
     std::string telemetry_path_;
+    /// Running active-fraction statistics for run_stats(). The samples above
+    /// used to be kept for the whole run unconditionally, just to be folded
+    /// into min/mean/max at the end (16 B per rebuild, ~10 MB per 2.6 M steps).
+    double active_frac_min_ = 1.0e30;
+    double active_frac_max_ = -1.0e30;
+    double active_frac_sum_ = 0.0;
+    long   active_samples_  = 0;
     /// Cumulative rebuild-sampled cell count per LTS tier (report histogram).
     std::array tier_occupancy_{};
+
+    /// G1: the two-zone groundwater kernel, or nullptr when no
+    /// `[2D_AQUIFER]` was authored. Not owned — SurfaceRouter2D holds it.
+    ///
+    /// The marcher drives it through four hooks (SubsurfaceSolver.hpp
+    /// §gw_lts) so the subsurface shares this ladder instead of running a
+    /// loop of its own. The subsurface's tiers come from ITS OWN stability
+    /// steps (guarantee G-A): a GW cell that exchanges with a node or
+    /// receives infiltration is deliberately NOT pinned to tier 0 — only its
+    /// surface twin is. Cross-cadence volume rides the same ±Δ side
+    /// accumulators the surface faces use (G-B).
+    SubsurfaceSolver* gw_ = nullptr;
+
+public:
+    /// Attach (or detach, with nullptr) the groundwater kernel. Must be
+    /// called before the first advance and after `initialize`.
+    void setSubsurface(SubsurfaceSolver* gw) noexcept { gw_ = gw; }
+
+    /// The unique interior-edge topology this marcher built. Exposed so the
+    /// groundwater kernel can put its lateral Darcy flux on the SAME faces
+    /// rather than build a second, necessarily-consistent copy of the same
+    /// graph. Valid only after `initialize`.
+    const InertialEdges& inertialEdges() const noexcept { return edges_; }
 };
 
 } // namespace openswmm::twoD
diff --git a/src/engine/2d/solver/GpuPluginAbi.h b/src/engine/2d/solver/GpuPluginAbi.h
index 5dde42af2..cf44caeb9 100644
--- a/src/engine/2d/solver/GpuPluginAbi.h
+++ b/src/engine/2d/solver/GpuPluginAbi.h
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpuPluginAbi.h
  * @brief Stable C ABI between the core engine and an optional GPU solver plugin.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_GPU_PLUGIN_ABI_H
@@ -53,11 +69,17 @@
 extern "C" {
 #endif
 
-/** ABI version. The core refuses a plugin whose abi_version disagrees.
+/** ABI version. The core refuses a plugin whose abi_version disagrees,
+ *  except that a v3 plugin is still accepted through the thread-count
+ *  environment fallback (see requested_threads below).
  *  v3: CVODE/ARKODE plugin solvers retired (D2, 2026-07-29) — the explicit
  *  marcher factory is the only solver entry, and SurfaceStateData dropped the
- *  active_set pointer, so a v2 plugin would mis-read the struct layout. */
-#define OPENSWMM_GPU_ABI_VERSION 3
+ *  active_set pointer, so a v2 plugin would mis-read the struct layout.
+ *  v4: OpenSwmmGpuProbe gained requested_threads (core → plugin, appended
+ *  so the v3 prefix layout is unchanged) and the optional entry point
+ *  openswmm_gpu_host_threads() (plugin → core). */
+#define OPENSWMM_GPU_ABI_VERSION 4
+#define OPENSWMM_GPU_ABI_VERSION_ENV_THREADS_FALLBACK 3
 
 /** GPU vendor / backend identifier reported by a plugin. */
 typedef enum OpenSwmmGpuVendor {
@@ -75,6 +97,12 @@ typedef struct OpenSwmmGpuProbe {
     int                vendor;            /**< an OpenSwmmGpuVendor value           */
     char               device_name[128];  /**< human-readable device name           */
     unsigned long long device_mem_bytes; /**< global memory of selected device     */
+    /** v4, core → plugin: [OPTIONS] THREADS for the host (OpenMP) backend.
+     *  0 = plugin default. Written by the core AFTER openswmm_gpu_probe()
+     *  returns and BEFORE openswmm_make_gpu_explicit_solver() is called; the
+     *  plugin zero-fills it in the probe. Device backends ignore it. The
+     *  OPENSWMM_2D_THREADS environment variable still overrides it. */
+    int                requested_threads;
 } OpenSwmmGpuProbe;
 
 /**
@@ -100,6 +128,17 @@ OPENSWMM_GPU_ABI int openswmm_gpu_probe(OpenSwmmGpuProbe* out);
  */
 OPENSWMM_GPU_ABI void* openswmm_make_gpu_explicit_solver(const OpenSwmmGpuProbe* probe);
 
+/**
+ * @brief (v4, optional) Host thread count the plugin's Kokkos runtime is
+ *        initialised with; 0 when not yet initialised or not a host backend.
+ *
+ * Kokkos initialises once per process, so this is the number every later
+ * solver in the process will run with regardless of requested_threads. The
+ * core dlsym()s it optionally — a plugin that does not export it is still
+ * accepted.
+ */
+OPENSWMM_GPU_ABI int openswmm_gpu_host_threads(void);
+
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
diff --git a/src/engine/2d/solver/ISurfaceSolver.hpp b/src/engine/2d/solver/ISurfaceSolver.hpp
index 3d4cedda3..0e9c4c2d5 100644
--- a/src/engine/2d/solver/ISurfaceSolver.hpp
+++ b/src/engine/2d/solver/ISurfaceSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ISurfaceSolver.hpp
  * @brief Backend-neutral interface for the 2D surface-routing time integrator.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_I_SURFACE_SOLVER_HPP
diff --git a/src/engine/2d/solver/InertialEdges.cpp b/src/engine/2d/solver/InertialEdges.cpp
index a66fce7cd..d2696e281 100644
--- a/src/engine/2d/solver/InertialEdges.cpp
+++ b/src/engine/2d/solver/InertialEdges.cpp
@@ -15,12 +15,6 @@
 
 namespace openswmm::twoD {
 
-namespace {
-inline int nbr_of(const MeshData& m, int t, int e) {
-    return (e == 0) ? m.tri_nbr0[t] : (e == 1) ? m.tri_nbr1[t] : m.tri_nbr2[t];
-}
-} // namespace
-
 void InertialEdges::build(const MeshData& mesh) {
     const int nt = mesh.n_triangles();
 
@@ -28,53 +22,57 @@ void InertialEdges::build(const MeshData& mesh) {
     ze_lo.clear(); ze_hi.clear();
     slotL.clear(); slotR.clear();
     nx.clear(); ny.clear(); mx.clear(); my.clear();
-    inv_dx_normal.clear(); n2_face.clear(); cell_lchar.clear();
+    inv_dx_normal.clear(); n2_face.clear(); n_face.clear(); cell_lchar.clear();
+    cell_lpos.clear();
 
     // slot_edge[t][e] = unique-edge id incident to (t, local edge e), or −1 for
     // a boundary edge. Filled for BOTH sides of every interior edge.
-    std::vector> slot_edge(
-        static_cast(nt), std::array{-1, -1, -1});
+    std::vector> slot_edge(
+        static_cast(nt), std::array{-1, -1, -1, -1});
 
     // 1. Enumerate unique interior edges. Count each once (nbr > t), and stamp
     //    the matching local edge on the neighbour so the CSR pass sees both.
     for (int t = 0; t < nt; ++t) {
-        for (int e = 0; e < 3; ++e) {
-            const int nb = nbr_of(mesh, t, e);
+        const int nv_t = mesh.cell_vertex_count(t);
+        for (int e = 0; e < nv_t; ++e) {
+            const int nb = mesh.cell_neighbour(t, e);
             if (nb < 0 || nb < t) continue;   // boundary, or already counted
 
             const int eid = static_cast(cL.size());
             cL.push_back(t);
             cR.push_back(nb);
-            xi.push_back(mesh.edge_length[t * 3 + e]);
+            xi.push_back(mesh.edge_length[MeshData::slot(t, e)]);
             const double ddx = std::hypot(mesh.tri_cx[t] - mesh.tri_cx[nb],
                                           mesh.tri_cy[t] - mesh.tri_cy[nb]);
             inv_dx.push_back(ddx > 1.0e-12 ? 1.0 / ddx : 0.0);
             zface.push_back(std::max(mesh.tri_cz[t], mesh.tri_cz[nb]));
             {
-                // Endpoint bed elevations of the shared edge (MeshBuilder
-                // convention: edge e is opposite vertex e). Same rule as
-                // SurfaceFluxCalculator's edgeEndpointZ — both incident cells
-                // see identical (z_lo, z_hi), so the VFR face depth is
+                // Endpoint bed elevations of the shared edge (MeshData
+                // convention: edge k = (v[(k+1)%nv], v[(k+2)%nv])). Same rule
+                // as SurfaceFluxCalculator's edgeEndpointZ — both incident
+                // cells see identical (z_lo, z_hi), so the VFR face depth is
                 // antisymmetric and the FV flux mass-conservative.
-                const int v[3] = {mesh.tri_v0[t], mesh.tri_v1[t], mesh.tri_v2[t]};
-                const double za = mesh.vz[v[(e + 1) % 3]];
-                const double zb = mesh.vz[v[(e + 2) % 3]];
+                int va, vb;
+                mesh.cell_edge_vertices(t, e, va, vb);
+                const double za = mesh.vz[va];
+                const double zb = mesh.vz[vb];
                 ze_lo.push_back(std::min(za, zb));
                 ze_hi.push_back(std::max(za, zb));
             }
-            slotL.push_back(t * 3 + e);
+            slotL.push_back(MeshData::slot(t, e));
 
             // Find nb's local edge facing t (the mirror slot) and record it.
+            const int nv_nb = mesh.cell_vertex_count(nb);
             int e2 = 0;
-            for (; e2 < 3; ++e2) if (nbr_of(mesh, nb, e2) == t) break;
-            slotR.push_back(nb * 3 + e2);
+            for (; e2 < nv_nb; ++e2) if (mesh.cell_neighbour(nb, e2) == t) break;
+            slotR.push_back(MeshData::slot(nb, e2));
 
             slot_edge[t][e]  = eid;
-            if (e2 < 3) slot_edge[nb][e2] = eid;
+            if (e2 < nv_nb) slot_edge[nb][e2] = eid;
 
             // Marcher extension. The mesh stores the OUTWARD normal per cell
             // slot; cL's slot normal already points cL→cR.
-            const int sl = t * 3 + e;
+            const int sl = MeshData::slot(t, e);
             nx.push_back(mesh.edge_nx[sl]);
             ny.push_back(mesh.edge_ny[sl]);
             mx.push_back(mesh.edge_mx[sl]);
@@ -91,6 +89,7 @@ void InertialEdges::build(const MeshData& mesh) {
             {
                 const double nf = 0.5 * (mesh.mannings_n[t] + mesh.mannings_n[nb]);
                 n2_face.push_back(nf * nf);
+                n_face.push_back(nf);
             }
         }
     }
@@ -121,35 +120,55 @@ void InertialEdges::build(const MeshData& mesh) {
         for (int t = 0; t < nt; ++t) {
             if (S[t] > 1.0e-30) {
                 cell_lchar[t] = std::sqrt(2.0 * mesh.tri_area[t] / S[t]);
-            } else {
+            } else if (mesh.cell_vertex_count(t) == 3) {
                 double xi_max = 0.0;
                 for (int e = 0; e < 3; ++e)
-                    xi_max = std::max(xi_max, mesh.edge_length[t * 3 + e]);
+                    xi_max = std::max(xi_max, mesh.edge_length[MeshData::slot(t, e)]);
                 cell_lchar[t] =
                     (xi_max > 0.0) ? 2.0 * mesh.tri_area[t] / xi_max : 0.0;
+            } else {
+                // Quad with no interior face: twice the smallest centroid→edge
+                // normal distance (Δx for a square; conservative for skewed
+                // cells). Only matters until a neighbour opens.
+                double dmin = 1.0e300;
+                for (int e = 0; e < mesh.cell_vertex_count(t); ++e)
+                    dmin = std::min(dmin, mesh.edge_dist_c[MeshData::slot(t, e)]);
+                cell_lchar[t] = (dmin > 0.0 && dmin < 1.0e300) ? 2.0 * dmin : 0.0;
             }
         }
     }
 
+    cell_lpos.assign(static_cast(nt), 0.0);
+    for (int t = 0; t < nt; ++t) {
+        double P = 0.0;
+        for (int e = 0; e < mesh.cell_vertex_count(t); ++e)
+            P += mesh.edge_length[MeshData::slot(t, e)];
+        cell_lpos[t] = (P > 0.0) ? 2.0 * mesh.tri_area[t] / P : 0.0;
+    }
+
     // 2. Per-cell CSR incidence with orientation signs.
     cell_ptr.assign(static_cast(nt) + 1, 0);
     for (int t = 0; t < nt; ++t) {
         int c = 0;
-        for (int e = 0; e < 3; ++e) if (slot_edge[t][e] >= 0) ++c;
+        for (int e = 0; e < kMaxCellVerts; ++e) if (slot_edge[t][e] >= 0) ++c;
         cell_ptr[t + 1] = cell_ptr[t] + c;
     }
     const int total = cell_ptr[nt];
     cell_edge.assign(static_cast(total), 0);
-    cell_sign.assign(static_cast(total), 0.0);
+    cell_sign.assign(static_cast(total), 0);
+    cell_arm_x.assign(static_cast(total), 0.0);
+    cell_arm_y.assign(static_cast(total), 0.0);
 
     std::vector fill(static_cast(nt), 0);
     for (int t = 0; t < nt; ++t) {
-        for (int e = 0; e < 3; ++e) {
+        for (int e = 0; e < kMaxCellVerts; ++e) {
             const int eid = slot_edge[t][e];
             if (eid < 0) continue;
             const int pos = cell_ptr[t] + fill[t]++;
             cell_edge[pos] = eid;
-            cell_sign[pos] = (cL[eid] == t) ? 1.0 : -1.0;
+            cell_sign[pos] = (cL[eid] == t) ? 1 : -1;
+            cell_arm_x[pos] = mx[eid] - mesh.tri_cx[t];
+            cell_arm_y[pos] = my[eid] - mesh.tri_cy[t];
         }
     }
 }
diff --git a/src/engine/2d/solver/InertialEdges.hpp b/src/engine/2d/solver/InertialEdges.hpp
index 0a5538e93..a7e442407 100644
--- a/src/engine/2d/solver/InertialEdges.hpp
+++ b/src/engine/2d/solver/InertialEdges.hpp
@@ -1,10 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InertialEdges.hpp
  * @brief Unique interior-edge structure for the local-inertial momentum DOFs.
  *
  * @details Phase 2 of docs/IMEX_LOCAL_INERTIAL_IMPLEMENTATION_PLAN.md. The
  *          diffusive-wave path stores edges redundantly per cell
- *          (MeshData edge arrays are flat [tri*3+edge]); the local-inertial
+ *          (MeshData edge arrays are flat [cell*kMaxCellVerts+edge]); the local-inertial
  *          scheme instead carries ONE prognostic discharge q per shared
  *          interior edge (the conservation invariant: a single antisymmetric
  *          flux per edge). This builds that canonical unique-edge enumeration
@@ -25,12 +41,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_INERTIAL_EDGES_HPP
 #define OPENSWMM_ENGINE_2D_INERTIAL_EDGES_HPP
 
+#include 
 #include 
 
 namespace openswmm::twoD {
@@ -55,7 +72,7 @@ struct InertialEdges {
     /// of the centroid-diluted zface (same endpoint rule as the boundary
     /// path's edgeEndpointZ — both incident cells see the identical pair).
     std::vector ze_lo, ze_hi;
-    std::vector    slotL, slotR; ///< flat mesh edge slots [tri*3+e] for writeback
+    std::vector    slotL, slotR; ///< flat mesh edge slots [cell*kMaxCellVerts+e] for writeback
 
     // Explicit-marcher extension (ExplicitInertialSolver). Precomputed here so
     // the per-substep kernels stay pure arithmetic.
@@ -67,9 +84,17 @@ struct InertialEdges {
     /// (inv_dx above) overestimates slopes on non-orthogonal triangle pairs.
     std::vector inv_dx_normal;
     std::vector n2_face;      ///< (½(n_L+n_R))² Manning coefficient
-    /// Per-CELL characteristic length L_char = 2A/ξ_max (smallest altitude, m)
-    /// for the CFL step bound dt = α·L_char/√(g·h).
+    std::vector n_face;       ///< ½(n_L+n_R) — sqrt(n2_face) precomputed for the diffusive law
+    /// Per-CELL characteristic length (m) for the CFL step bound
+    /// dt = α·L_char/√(g·h): √(2A/Σξ·inv_dx_normal) from the discrete wave
+    /// operator; isolated cells fall back to 2A/ξ_max (triangle) or
+    /// 2·min centroid→edge distance (quad).
     std::vector cell_lchar;
+    /// Per-CELL positivity length 2A/P (P = full perimeter, boundary edges
+    /// included; Δx/2 for a square). The FULL_SWE Godunov update uses
+    /// dt = α·(2A/P)/(√(gh)+|u|): α = 1 is the linear stability limit and
+    /// α = ½ the Audusse–Bristeau positivity bound (Σ_faces outflow ≤ ½·V).
+    std::vector cell_lpos;
 
     // Per-cell CSR incidence for the conservative continuity gather. For cell i,
     // the incident edges are cell_edge[cell_ptr[i] .. cell_ptr[i+1]) with sign
@@ -77,7 +102,15 @@ struct InertialEdges {
     //   dV_i/dt (flux part) = − Σ cell_sign · q[edge] · ξ[edge].
     std::vector    cell_ptr;     ///< [n_triangles + 1] CSR row pointers
     std::vector    cell_edge;    ///< incident edge id
-    std::vector cell_sign;    ///< +1 (i==cL) / −1 (i==cR)
+    /// +1 (i==cL) / −1 (i==cR). int8: the value is only ever branched on and
+    /// multiplied by exactly ±1, and as a double it cost 8 bytes of gather
+    /// traffic per CSR entry in the two hottest cell loops.
+    std::vector cell_sign;
+    /// Perot arm (m⃗_e − c⃗_i) per CSR entry — the vector fireCells multiplies
+    /// the signed face discharge by. Precomputed because the cell loop had to
+    /// gather mx[e]/my[e] (scattered by face id) and subtract the centroid on
+    /// every firing of every cell.
+    std::vector cell_arm_x, cell_arm_y;
 
     /// Build the structure from mesh topology. O(n_triangles).
     void build(const MeshData& mesh);
diff --git a/src/engine/2d/solver/InertialKernels.hpp b/src/engine/2d/solver/InertialKernels.hpp
index 5699b3ec5..905a132a9 100644
--- a/src/engine/2d/solver/InertialKernels.hpp
+++ b/src/engine/2d/solver/InertialKernels.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InertialKernels.hpp
  * @brief Single-source flat kernels for the explicit local-inertial marcher.
@@ -31,7 +47,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_INERTIAL_KERNELS_HPP
@@ -43,6 +59,7 @@
 #include "../data/MeshData.hpp"
 #include "../data/SolverOptions2D.hpp"
 #include "../mesh/VfrClosure.hpp"
+#include "../mesh/QuadVfr.hpp"
 
 // Portable kernel-function marker (P5 Kokkos port): host builds get plain
 // `inline`; the GPU plugin defines OPENSWMM_KERNEL_FN to
@@ -67,6 +84,19 @@ inline constexpr double kGravity = 9.80665;  ///< matches the existing kernels
 /// decays q geometrically and rest states are exact.
 inline constexpr double kEtaDeadband = 1.0e-12;
 
+/// |(x, y)| for the marcher's discharge vectors.
+///
+/// std::hypot's overflow/underflow safety costs ~10x a plain sqrt and buys
+/// nothing here: the arguments are unit-width discharges (m^2/s), which the
+/// Froude cap and the positivity limiter already bound to O(1..10). It was
+/// measured at ~8% of the marcher's runtime. Values differ from std::hypot by
+/// at most 1 ulp — and the Kokkos face kernel had ALREADY taken this liberty
+/// while the serial marcher had not, so routing every backend through this
+/// helper closes a real cross-backend bit-difference instead of opening one.
+OPENSWMM_KERNEL_FN double qMagnitude(double x, double y) noexcept {
+    return std::sqrt(x * x + y * y);
+}
+
 /// Scalar core of the V → (η, depth) closure (device-callable; the MeshData
 /// wrapper below loads the geometry and forwards — identical ops and order).
 OPENSWMM_KERNEL_FN void etaDepthScalar(double area, double cz,
@@ -97,15 +127,78 @@ OPENSWMM_KERNEL_FN double volumeFromEtaScalar(double area, double cz,
     return (d > 0.0) ? area * d : 0.0;
 }
 
+/// Quad (B&S 2007 two-plane) V → (η, depth) closure core. @p zs / @p A1 /
+/// @p A2 are the precomputed quad VFR data (MeshData::quad_vfr_*).
+OPENSWMM_KERNEL_FN void etaDepthQuadScalar(double area, double cz,
+                                           const double* zs, double A1, double A2,
+                                           bool vfr, double vfr_min_wet_frac,
+                                           double V, double& eta,
+                                           double& depth) noexcept {
+    const double v = (V > 0.0) ? V : 0.0;
+    depth = (area > 1.0e-30) ? v / area : 0.0;
+    if (vfr) eta = quadEtaFromMeanDepth(zs, A1, A2, depth, vfr_min_wet_frac);
+    else     eta = cz + depth;
+}
+
+/// Quad η → V inverse (device-callable).
+OPENSWMM_KERNEL_FN double volumeFromEtaQuadScalar(double area, double cz,
+                                                  const double* zs, double A1,
+                                                  double A2, bool vfr,
+                                                  double vfr_min_wet_frac,
+                                                  double eta) noexcept {
+    if (vfr) return area * quadMeanDepthFromEta(zs, A1, A2, eta, vfr_min_wet_frac);
+    const double d = eta - cz;
+    return (d > 0.0) ? area * d : 0.0;
+}
+
+#if defined(__GNUC__) || defined(__clang__)
+#define OPENSWMM_2D_NOINLINE __attribute__((noinline))
+#elif defined(_MSC_VER)
+#define OPENSWMM_2D_NOINLINE __declspec(noinline)
+#else
+#define OPENSWMM_2D_NOINLINE
+#endif
+
+/// Quad (B&S 2007 two-plane) VFR closure, kept OUT OF LINE on purpose: its
+/// safeguarded Newton (QuadVfr.hpp) is large, and inlining it into
+/// cellEtaDepth made GCC stop inlining cellEtaDepth itself into the cell
+/// kernels — a call per cell per firing on every mesh, quads or not
+/// (2D_PERF_REGRESSION_DIAGNOSIS: measured +30 % on Bellinge LI, profile
+/// showed cellEtaDepth as a 10 M-call function that used to be inlined).
+OPENSWMM_2D_NOINLINE inline void cellEtaDepthQuad(const MeshData& m,
+                                                  const SolverOptions2D& o,
+                                                  int i, double V, double& eta,
+                                                  double& depth) noexcept {
+    etaDepthQuadScalar(m.tri_area[i], m.tri_cz[i],
+                       &m.quad_vfr_z[static_cast(i) * kQuadVfrZ],
+                       m.quad_vfr_a[static_cast(i) * 2],
+                       m.quad_vfr_a[static_cast(i) * 2 + 1],
+                       true, o.vfr_min_wet_frac, V, eta, depth);
+}
+
 /// Volume → (η, depth) closure — the SAME semantics as the CVODE/ARKODE
 /// reconstructFromVolume: depth = max(V,0)/A; FLAT η = z_c + depth, VFR η from
-/// the Begnudelli–Sanders planar-bed relation (ε-regularized).
+/// the Begnudelli–Sanders planar-bed relation (ε-regularized) for triangles
+/// and the B&S 2007 two-plane relation for quads.
 inline void cellEtaDepth(const MeshData& m, const SolverOptions2D& o,
                          int i, double V, double& eta, double& depth) noexcept {
+    // Branch BEFORE the geometry loads: under the default FLAT closure the
+    // three vertex-index loads and the three scattered vz gathers below are
+    // dead, and this is the hottest call in the marcher (every cell, every
+    // firing).
+    if (o.cell_closure != CellClosure2D::VFR) {
+        etaDepthScalar(m.tri_area[i], m.tri_cz[i], 0.0, 0.0, 0.0,
+                       false, o.vfr_min_wet_frac, V, eta, depth);
+        return;
+    }
+    if (m.cell_nv[static_cast(i)] == 4) {
+        cellEtaDepthQuad(m, o, i, V, eta, depth);
+        return;
+    }
     etaDepthScalar(m.tri_area[i], m.tri_cz[i],
-                   m.vz[m.tri_v0[i]], m.vz[m.tri_v1[i]], m.vz[m.tri_v2[i]],
-                   o.cell_closure == CellClosure2D::VFR, o.vfr_min_wet_frac,
-                   V, eta, depth);
+                   m.vz[m.cell_vertex(i, 0)], m.vz[m.cell_vertex(i, 1)],
+                   m.vz[m.cell_vertex(i, 2)],
+                   true, o.vfr_min_wet_frac, V, eta, depth);
 }
 
 /// Exact inverse of the closure: cell volume holding free surface η — FLAT
@@ -113,9 +206,17 @@ inline void cellEtaDepth(const MeshData& m, const SolverOptions2D& o,
 /// with cellEtaDepth). Closure-consistent seeding for tests/hotstart.
 inline double cellVolumeFromEta(const MeshData& m, const SolverOptions2D& o,
                                 int i, double eta) noexcept {
+    if (m.cell_nv[static_cast(i)] == 4) {
+        return volumeFromEtaQuadScalar(
+            m.tri_area[i], m.tri_cz[i],
+            &m.quad_vfr_z[static_cast(i) * kQuadVfrZ],
+            m.quad_vfr_a[static_cast(i) * 2],
+            m.quad_vfr_a[static_cast(i) * 2 + 1],
+            o.cell_closure == CellClosure2D::VFR, o.vfr_min_wet_frac, eta);
+    }
     return volumeFromEtaScalar(m.tri_area[i], m.tri_cz[i],
-                               m.vz[m.tri_v0[i]], m.vz[m.tri_v1[i]],
-                               m.vz[m.tri_v2[i]],
+                               m.vz[m.cell_vertex(i, 0)], m.vz[m.cell_vertex(i, 1)],
+                               m.vz[m.cell_vertex(i, 2)],
                                o.cell_closure == CellClosure2D::VFR,
                                o.vfr_min_wet_frac, eta);
 }
diff --git a/src/engine/2d/solver/SurfaceFluxCalculator.cpp b/src/engine/2d/solver/SurfaceFluxCalculator.cpp
index caa5b6df9..ffee4ca6c 100644
--- a/src/engine/2d/solver/SurfaceFluxCalculator.cpp
+++ b/src/engine/2d/solver/SurfaceFluxCalculator.cpp
@@ -25,27 +25,22 @@ namespace openswmm::twoD {
 namespace {
 
 inline int tri_nbr(const MeshData& mesh, int t, int e) {
-    switch (e) {
-        case 0: return mesh.tri_nbr0[t];
-        case 1: return mesh.tri_nbr1[t];
-        case 2: return mesh.tri_nbr2[t];
-        default: return -1;
-    }
+    return (e >= 0 && e < mesh.cell_vertex_count(t)) ? mesh.cell_neighbour(t, e) : -1;
 }
 
 inline double sq(double x) noexcept { return x * x; }
 
-// Endpoint bed elevations of local edge e of triangle t, sorted z_lo <= z_hi.
-// MeshBuilder convention: edge e is opposite vertex e; its endpoints are the
-// triangle's other two vertices (same rule as MeshBuilder::edgeVertices and
-// recomputeVertexZDependents). For an interior edge both incident cells see
+// Endpoint bed elevations of local edge e of cell t, sorted z_lo <= z_hi.
+// MeshData convention: edge k = (v[(k+1)%nv], v[(k+2)%nv]) (for a triangle:
+// edge e is opposite vertex e). For an interior edge both incident cells see
 // the same two vertices, so both compute identical (z_lo, z_hi) — the face
 // depth below stays antisymmetric and the FV flux mass-conservative.
 inline void edgeEndpointZ(const MeshData& mesh, int t, int e,
                           double& z_lo, double& z_hi) noexcept {
-    const int v[3] = {mesh.tri_v0[t], mesh.tri_v1[t], mesh.tri_v2[t]};
-    const double za = mesh.vz[v[(e + 1) % 3]];
-    const double zb = mesh.vz[v[(e + 2) % 3]];
+    int va, vb;
+    mesh.cell_edge_vertices(t, e, va, vb);
+    const double za = mesh.vz[va];
+    const double zb = mesh.vz[vb];
     z_lo = (za < zb) ? za : zb;
     z_hi = (za < zb) ? zb : za;
 }
@@ -108,21 +103,30 @@ inline double boundaryEdgeFlux(const MeshData& mesh, const SurfaceStateData& sta
         case BoundaryType::WALL:
             return 0.0;
         case BoundaryType::NORMAL_FLOW: {
-            // Manning normal-flow outlet: per-metre outflow q = (1/n)·h^(5/3)·√S.
+            // Manning normal-flow boundary: per-metre discharge
+            // q = sign(S)·(1/n)·h^(5/3)·√|S|.
+            //
+            // The slope is SIGNED. A positive slope falls away from the
+            // domain and drains it (the historical behaviour, unchanged); a
+            // negative slope falls toward the domain and feeds it. Before
+            // this, S <= 0 conveyed nothing, so the only way to drive inflow
+            // was a SPECIFIED_FLOW edge with a negative discharge.
             const double S = b->edge_bed_slope[idx];
-            if (S <= 0.0 || depth <= 0.0 || n <= 0.0) return 0.0;
+            if (S == 0.0 || depth <= 0.0 || n <= 0.0) return 0.0;
+            const double sgnS = (S > 0.0) ? 1.0 : -1.0;
+            const double absS = std::fabs(S);
             // §VFR_FACE: convey with the depth AT the boundary edge (Eq. 14
             // from the cell's free surface) instead of the cell mean, so a
             // cell whose water pools away from the outlet edge does not leak.
             double h_out = depth;
             if (vfr_face) {
                 double z_lo, z_hi;
-                edgeEndpointZ(mesh, i, idx % 3, z_lo, z_hi);
+                edgeEndpointZ(mesh, i, MeshData::slot_local(idx), z_lo, z_hi);
                 h_out = faceDepthFromEta(state.head[i], z_lo, z_hi);
                 if (h_out <= 0.0) return 0.0;
             }
             const double h53 = h_out * std::cbrt(h_out * h_out);
-            return -(h53 * std::sqrt(S) / n) * L;
+            return -sgnS * (h53 * std::sqrt(absS) / n) * L;
         }
         case BoundaryType::SPECIFIED_FLOW:
         case BoundaryType::RATING_CURVE:
@@ -142,7 +146,11 @@ inline double boundaryEdgeFlux(const MeshData& mesh, const SurfaceStateData& sta
             const double h_bc = b->edge_bc_head[idx];
             const double dh   = state.head[i] - h_bc;
             const double A    = mesh.tri_area[i];
-            const double dx_b = (L > 1.0e-12) ? (2.0 * A) / (3.0 * L) : 0.0;
+            // Triangle expression retained verbatim (bit-identity); a quad
+            // uses the precomputed centroid→edge normal distance.
+            const double dx_b = (mesh.cell_vertex_count(i) == 3)
+                ? ((L > 1.0e-12) ? (2.0 * A) / (3.0 * L) : 0.0)
+                : mesh.edge_dist_c[idx];
             if (dx_b <= 1.0e-12) return 0.0;
             double h_up;
             if (vfr_face) {
@@ -150,7 +158,7 @@ inline double boundaryEdgeFlux(const MeshData& mesh, const SurfaceStateData& sta
                 // side is higher (cell surface on outflow, prescribed stage on
                 // inflow) — mirrors the interior Eq. 14 treatment.
                 double z_lo, z_hi;
-                edgeEndpointZ(mesh, i, idx % 3, z_lo, z_hi);
+                edgeEndpointZ(mesh, i, MeshData::slot_local(idx), z_lo, z_hi);
                 h_up = faceDepthFromEta((dh > 0.0) ? state.head[i] : h_bc,
                                         z_lo, z_hi);
             } else {
@@ -183,8 +191,9 @@ void computeUnlimitedGradients(const MeshData& mesh, SurfaceStateData& state,
                               ? 1.0 / mesh.tri_area[i] : 0.0;
         double gx = 0.0, gy = 0.0;
 
-        for (int e = 0; e < 3; ++e) {
-            int idx = i * 3 + e;
+        const int nv_i = mesh.cell_vertex_count(i);
+        for (int e = 0; e < nv_i; ++e) {
+            int idx = MeshData::slot(i, e);
             int nbr = tri_nbr(mesh, i, e);
 
             // Head at edge midpoint: average of this cell and neighbour
@@ -224,10 +233,11 @@ void computeLimitedGradients(const MeshData& mesh, SurfaceStateData& state,
         // 1/4 weights as all |∇h| → 0, avoiding a degenerate-division branch.
         double q0 = sq(state.grad_hx[i]) + sq(state.grad_hy[i]) + eps2;
 
-        double q[3];
-        double gx_nbr[3], gy_nbr[3];
+        double q[kMaxCellVerts];
+        double gx_nbr[kMaxCellVerts], gy_nbr[kMaxCellVerts];
+        const int nv_i = mesh.cell_vertex_count(i);
 
-        for (int e = 0; e < 3; ++e) {
+        for (int e = 0; e < nv_i; ++e) {
             int nbr = tri_nbr(mesh, i, e);
             if (nbr >= 0) {
                 q[e] = sq(state.grad_hx[nbr]) + sq(state.grad_hy[nbr]) + eps2;
@@ -241,6 +251,25 @@ void computeLimitedGradients(const MeshData& mesh, SurfaceStateData& state,
             }
         }
 
+        if (nv_i == 4) {
+            // Quad: the same JK product weights over 5 contributing
+            // gradients (self + 4 neighbours), w_k = ∏_{j≠k} q_j / Σ.
+            double qq[5] = {q0, q[0], q[1], q[2], q[3]};
+            double gx[5] = {state.grad_hx[i], gx_nbr[0], gx_nbr[1], gx_nbr[2], gx_nbr[3]};
+            double gy[5] = {state.grad_hy[i], gy_nbr[0], gy_nbr[1], gy_nbr[2], gy_nbr[3]};
+            double num[5], den = 0.0;
+            for (int k = 0; k < 5; ++k) {
+                double pr = 1.0;
+                for (int j = 0; j < 5; ++j) if (j != k) pr *= qq[j];
+                num[k] = pr; den += pr;
+            }
+            double sx = 0.0, sy = 0.0;
+            for (int k = 0; k < 5; ++k) { sx += num[k] / den * gx[k]; sy += num[k] / den * gy[k]; }
+            state.grad_hx_lim[i] = sx;
+            state.grad_hy_lim[i] = sy;
+            continue;
+        }
+
         // Canonical Jawahar-Kamath (JK 2000) weights for 4 contributing
         // gradients: w_k = (∏_{j≠k} q_j) / Σ_k (∏_{j≠k} q_j).
         //
@@ -287,16 +316,21 @@ void computeCellContinuity(const MeshData& mesh, SurfaceStateData& state,
 
         // Net inflow (m³/s): edge_flux is inflow-positive volumetric flux.
         double flux_sum = 0.0;
-        for (int e = 0; e < 3; ++e) {
-            flux_sum += state.edge_flux[i * 3 + e];
+        for (int e = 0; e < mesh.cell_vertex_count(i); ++e) {
+            flux_sum += state.edge_flux[MeshData::slot(i, e)];
         }
 
         // Source volume rate (m³/s): same source terms assembleRHS uses. The
-        // evaporation sink is evaluated at the accepted end-of-step depth
-        // (first-order, consistent with the diagnostic character above).
+        // evaporation and infiltration sinks are evaluated at the accepted
+        // end-of-step depth (first-order, consistent with the diagnostic
+        // character above). Omitting the infiltration term here would leave
+        // cell_continuity_err wrong on every infiltrating cell (plan §5.5.2,
+        // site 4) — a silently wrong diagnostic, not a crash.
         double source = (state.rainfall[i] + state.coupling_flux[i]
                          - evapSink(state.evap_rate[i], state.depth[i],
-                                    opts.dry_depth)) * area;
+                                    opts.dry_depth)
+                         - infilSink(state.infil_rate[i], state.depth[i],
+                                     opts.dry_depth)) * area;
 
         // Storage change rate (m³/s) — volume is the conserved state.
         double storage_rate =
@@ -327,8 +361,8 @@ void computeFaceVelocity(const MeshData& mesh, SurfaceStateData& state,
         // Normal equations for N·q ≈ b: NᵀN (2×2 SPD) and Nᵀb.
         double a00 = 0.0, a01 = 0.0, a11 = 0.0;
         double b0  = 0.0, b1  = 0.0;
-        for (int e = 0; e < 3; ++e) {
-            int idx = i * 3 + e;
+        for (int e = 0; e < mesh.cell_vertex_count(i); ++e) {
+            int idx = MeshData::slot(i, e);
             double nx  = mesh.edge_nx[idx];
             double ny  = mesh.edge_ny[idx];
             double len = mesh.edge_length[idx];
diff --git a/src/engine/2d/solver/SurfaceFluxCalculator.hpp b/src/engine/2d/solver/SurfaceFluxCalculator.hpp
index 371c6033b..3a507bfcd 100644
--- a/src/engine/2d/solver/SurfaceFluxCalculator.hpp
+++ b/src/engine/2d/solver/SurfaceFluxCalculator.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SurfaceFluxCalculator.hpp
  * @brief Edge flux computation, gradient calculation, and slope limiting.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SURFACE_FLUX_CALCULATOR_HPP
@@ -71,6 +87,34 @@ inline double evapSink(double rate, double depth, double dry_depth) noexcept {
     return rate * t * t * (3.0 - 2.0 * t);
 }
 
+/**
+ * @brief Depth-limited infiltration sink rate (m/s) for one cell (plan §5.5).
+ *
+ * Identical contract to evapSink: the held per-cell rate (D-I1,
+ * SurfaceStateData::infil_rate) applies in full for depth ≥ dry_depth and
+ * shuts off through the same cubic Hermite wet/dry ramp as the cell dries.
+ * Negative rates are treated as zero (infiltration is a loss only;
+ * exfiltration is not a v1 destination — D-I4).
+ *
+ * D-I2 sink ordering: evaporation is taken FIRST with its semantics
+ * unchanged, and infiltration is then applied against what is left, so a
+ * surface-only project (infil_rate all zero) is bitwise unchanged. Both sinks
+ * ramp to zero together as the cell dries, and every call site feeds the sum
+ * into a volume update that floors at zero, so the pair cannot leave a cell
+ * with negative water.
+ *
+ * @param rate      Held infiltration rate (m/s).
+ * @param depth     Current cell depth (m).
+ * @param dry_depth Dry-depth threshold (m).
+ * @return Effective sink rate (m/s, ≥ 0).
+ */
+inline double infilSink(double rate, double depth, double dry_depth) noexcept {
+    if (rate <= 0.0 || depth <= 0.0) return 0.0;
+    if (depth >= dry_depth) return rate;
+    double t = depth / dry_depth;
+    return rate * t * t * (3.0 - 2.0 * t);
+}
+
 /**
  * @brief Boundary-edge flux for cell @p i across flat mesh edge slot @p idx
  *        (m³/s, inflow-positive). Exported wrapper over the file-local
@@ -88,11 +132,12 @@ double computeBoundaryEdgeFlux(const MeshData& mesh,
  * Evaluates the discrete semi-discrete balance for each cell:
  *   residual_i = (ψ_i − ψ_old_i)·A_i/dt
  *                − ( Σ_e F_e  +  (rainfall_i + coupling_flux_i
- *                                 − evapSink_i)·A_i )
+ *                                 − evapSink_i − infilSink_i)·A_i )
  * where F_e = edge_flux[i·3+e] is the inflow-positive volumetric edge flux
  * (m³/s). A perfectly conservative step yields ~0 (first-order diagnostic,
  * not the solver's internal error). Reads old_depth, depth, edge_flux,
- * rainfall, evap_rate, coupling_flux; writes cell_continuity_err (m³/s).
+ * rainfall, evap_rate, infil_rate, coupling_flux; writes cell_continuity_err
+ * (m³/s).
  *
  * Call AFTER the solver advance, with old_depth holding the start-of-step
  * depths (i.e. after save_state() but before the next save_state()).
diff --git a/src/engine/2d/solver/SurfaceSolverFactory.cpp b/src/engine/2d/solver/SurfaceSolverFactory.cpp
index e0fd8775f..790f83c67 100644
--- a/src/engine/2d/solver/SurfaceSolverFactory.cpp
+++ b/src/engine/2d/solver/SurfaceSolverFactory.cpp
@@ -7,8 +7,9 @@
  *          prefer the Kokkos marcher plugin (openswmm_make_gpu_explicit_solver
  *          — OpenMP threads on the host build, device-resident on
  *          CUDA/HIP/SYCL), fall back to the serial ExplicitInertialSolver.
- *          Respects OPENSWMM_2D_BACKEND (cpu|auto|omp|cuda|hip|sycl) and the
- *          small-mesh launch-overhead gate. The marcher kernels implement both
+ *          Respects [2D_OPTIONS] BACKEND (AUTO|CPU|OMP|CUDA|HIP|SYCL), the
+ *          OPENSWMM_2D_BACKEND environment override, and the small-mesh
+ *          launch-overhead gates. The marcher kernels implement both
  *          cell closures, so no CELL_CLOSURE restriction applies.
  *
  * @see SurfaceSolverFactory.hpp
@@ -22,6 +23,7 @@
 #include "ExplicitInertialSolver.hpp"
 #include "GpuPluginAbi.h"
 #include "../data/SolverOptions2D.hpp"
+#include "../../core/ThreadInfo.hpp"
 
 #include 
 #include 
@@ -148,14 +150,31 @@ void* load_cached(const std::string& path) {
     return h;
 }
 
-using ProbeFn = int (*)(OpenSwmmGpuProbe*);
-using MakeFn  = void* (*)(const OpenSwmmGpuProbe*);
+using ProbeFn       = int (*)(OpenSwmmGpuProbe*);
+using MakeFn        = void* (*)(const OpenSwmmGpuProbe*);
+using HostThreadsFn = int (*)(void);
+
+// Set an environment variable in this process only if it is not already set.
+// Used for the ABI-v3 thread-count fallback (OPENSWMM_2D_THREADS).
+void setenv_if_unset(const char* name, const std::string& value) {
+    if (std::getenv(name)) return;
+#if defined(_WIN32)
+    _putenv_s(name, value.c_str());
+#else
+    setenv(name, value.c_str(), 0);
+#endif
+}
 
 // Try to load a specific backend plugin and build its marcher solver. Returns
 // null (without throwing) if the plugin is absent, broken, reports no device,
 // carries a stale ABI, or does not export the explicit-marcher factory.
+//
+// requested_threads: raw [OPTIONS] THREADS (0 = auto). Host (OpenMP) plugins
+// take it as OpenSwmmGpuProbe::requested_threads (ABI v4); for a v3 plugin it
+// is passed through the OPENSWMM_2D_THREADS environment fallback instead.
 std::unique_ptr try_plugin(const std::string& backend,
-                                           std::string* chosen) {
+                                           std::string* chosen,
+                                           int requested_threads) {
     for (const auto& dir : search_dirs()) {
         for (const auto& fname : plugin_filenames(backend)) {
             const fs::path path = fs::path(dir) / fname;
@@ -170,16 +189,57 @@ std::unique_ptr try_plugin(const std::string& backend,
             if (!probe || !make) continue;
             OpenSwmmGpuProbe info{};
             const int rc = probe(&info);
-            if (info.abi_version != OPENSWMM_GPU_ABI_VERSION) continue;
+            const bool abi_current  = info.abi_version == OPENSWMM_GPU_ABI_VERSION;
+            const bool abi_fallback = info.abi_version == OPENSWMM_GPU_ABI_VERSION_ENV_THREADS_FALLBACK;
+            if (!abi_current && !abi_fallback) continue;
             if (rc != 0 || info.device_count <= 0) {
                 // No usable device behind this plugin — try the next candidate.
                 continue;
             }
+
+            // Host-backend thread count. Auto (0) on Apple Silicon defaults to
+            // the performance-core count — efficiency cores drag the fenced
+            // kernel loops (plan §5.1); elsewhere 0 leaves the Kokkos default.
+            const bool host_backend = info.vendor == OPENSWMM_GPU_VENDOR_OPENMP;
+            int host_req = requested_threads;
+            if (host_backend && host_req == 0) host_req = threadinfo::perfCores();
+            if (host_backend) {
+                if (abi_current) {
+                    info.requested_threads = host_req;
+                } else if (host_req > 0) {
+                    // v3 plugin: no field to carry the request — fall back to
+                    // the environment variable the plugin already honours.
+                    setenv_if_unset("OPENSWMM_2D_THREADS", std::to_string(host_req));
+                    std::fprintf(stderr,
+                        "[openswmm 2D] plugin '%s' predates ABI v4; THREADS = %d "
+                        "passed via OPENSWMM_2D_THREADS (environment fallback).\n",
+                        fname.c_str(), host_req);
+                }
+            }
+
             void* raw = make(&info);
             if (!raw) continue;
             auto* solver = static_cast(raw);
             const std::string label = backend + " (" + info.device_name + ")";
             if (chosen) *chosen = label;
+
+            // Kokkos initialises once per process: record what the host
+            // backend actually runs with and warn when this model asked for
+            // something else (only a restart can change it).
+            if (host_backend) {
+                auto host_threads = reinterpret_cast(
+                    platform_sym(h, "openswmm_gpu_host_threads"));
+                const int in_use = host_threads ? host_threads() : 0;
+                if (in_use > 0) {
+                    threadinfo::setKokkosOmpThreads(in_use);
+                    if (host_req > 0 && in_use != host_req)
+                        std::fprintf(stderr,
+                            "[openswmm 2D] Kokkos OpenMP backend already initialised "
+                            "with %d threads in this process; THREADS = %d cannot "
+                            "take effect until the application restarts.\n",
+                            in_use, host_req);
+                }
+            }
             // Announce the selected acceleration backend once, on successful
             // plugin load. This is the signal the omp gate tests check for; it
             // also gives operators a record of which 2D backend ran.
@@ -191,44 +251,95 @@ std::unique_ptr try_plugin(const std::string& backend,
     return nullptr;
 }
 
+// [2D_OPTIONS] BACKEND value as the lower-case policy token the env var uses.
+std::string backend_name(Backend2D b) {
+    switch (b) {
+        case Backend2D::CPU:  return "cpu";
+        case Backend2D::OMP:  return "omp";
+        case Backend2D::CUDA: return "cuda";
+        case Backend2D::HIP:  return "hip";
+        case Backend2D::SYCL: return "sycl";
+        case Backend2D::AUTO: break;
+    }
+    return "auto";
+}
+
 } // anonymous namespace
 
-std::unique_ptr makeSurfaceSolver(const SolverOptions2D& /*opts*/,
+std::unique_ptr makeSurfaceSolver(const SolverOptions2D& opts,
                                                   std::string* chosen,
-                                                  int n_cells) {
-    auto serial_marcher = [&]() -> std::unique_ptr {
-        if (chosen) *chosen = "cpu (explicit local-inertial marcher)";
+                                                  int n_cells,
+                                                  bool plugin_capable) {
+    auto serial_marcher = [&](const char* label = "cpu (explicit marcher)")
+        -> std::unique_ptr {
+        if (chosen) *chosen = label;
         return std::make_unique();
     };
 
-    const std::string mode = lower(env("OPENSWMM_2D_BACKEND"));
+    // Policy: the environment variable (operator/CI override) wins; otherwise
+    // the model's own [2D_OPTIONS] BACKEND — same precedence as the FV
+    // module's OPENSWMM_FV_BACKEND over FV_BACKEND.
+    std::string mode = lower(env("OPENSWMM_2D_BACKEND"));
+    if (mode.empty()) mode = backend_name(opts.backend);
     if (mode == "cpu") return serial_marcher();
 
-    // Mesh-size gate: a Kokkos plugin pays a per-kernel launch overhead on
-    // EVERY marcher substep, and the built-in marcher is itself OpenMP-
-    // threaded — the plugin only pays off when per-cell work amortizes the
-    // launches. Measured on a 25k-cell coupled model (Bellinge, 48 h storm)
-    // the omp plugin ran 15–20× SLOWER than the built-in marcher (238 s vs
-    // >20× that pace), so the auto crossover sits far above the old 20k
-    // default. Below the threshold, stay serial unless the backend was
-    // requested explicitly (OPENSWMM_2D_BACKEND=omp|cuda|... bypasses it).
-    // Env-tunable (OPENSWMM_2D_MIN_PARALLEL_CELLS); 0 cells = unknown ⇒ no gate.
-    const bool gated = (mode.empty() || mode == "auto") && [&] {
-        if (n_cells <= 0) return false;
-        long min_par = 200000;
-        if (const char* s = std::getenv("OPENSWMM_2D_MIN_PARALLEL_CELLS"))
-            min_par = std::atol(s);
-        return n_cells < min_par;
-    }();
-    if (!gated) {
-        if (mode.empty() || mode == "auto") {
-            for (const char* b : {"cuda", "hip", "sycl", "omp"})
-                if (auto s = try_plugin(b, chosen)) return s;
-        } else if (mode == "omp" || mode == "cuda" || mode == "hip" ||
-                   mode == "sycl") {
-            if (auto s = try_plugin(mode, chosen)) return s;
-        }
+    // R6 (2D_TRI_QUAD_MESH_PLAN / 2D_FULL_SWE plan): the Kokkos plugin
+    // implements the triangle-only LOCAL_INERTIAL scheme. A mixed tri-quad
+    // mesh or a non-LI momentum closure is refused LOUDLY and served by the
+    // CPU marcher — never a silent physics substitution. S4b: a model with
+    // transport rows (species / age / temperature) is refused the same way.
+    if (!plugin_capable) {
+        // Say so under AUTO as well: a model that silently loses the plugin
+        // (a DIFFUSIVE_WAVE deck on a 100k-cell mesh, say) looks like a
+        // performance regression to the modeller.
+        std::fprintf(stderr,
+            "[openswmm 2D] backend '%s': the GPU/Kokkos plugin serves only "
+            "all-triangle meshes under MOMENTUM_EQUATION LOCAL_INERTIAL with "
+            "no transport rows (species / age / temperature); "
+            "using the CPU marcher for this model.\n",
+            mode.empty() ? "auto" : mode.c_str());
+        return serial_marcher("cpu (explicit marcher; plugin not applicable)");
+    }
+
+    // Explicit backend request bypasses every mesh-size gate — the operator
+    // asked for it by name (OPENSWMM_2D_BACKEND / BACKEND = omp|cuda|hip|sycl).
+    if (mode == "omp" || mode == "cuda" || mode == "hip" || mode == "sycl") {
+        if (auto s = try_plugin(mode, chosen, opts.requested_threads)) return s;
+        std::fprintf(stderr,
+            "[openswmm 2D] backend '%s' requested but no usable plugin/device "
+            "found; falling back to the CPU marcher.\n", mode.c_str());
+        return serial_marcher();
     }
+
+    // auto / empty: the two plugin classes have very different economics, so
+    // they get separate mesh-size floors (env-tunable; n_cells<=0 unknown = no
+    // gate).
+    //   * DEVICE backends (cuda/hip/sycl) offload to a SEPARATE accelerator, so
+    //     the launch/transfer overhead amortizes far earlier — a low floor.
+    //     Previously they shared the omp floor below and so a discrete GPU sat
+    //     idle for every sub-200k mesh (the reported "CUDA not utilized").
+    //   * The OMP host plugin competes with the already-OMP-threaded serial
+    //     marcher (measured 15-20x SLOWER at 25k cells on Bellinge), so it
+    //     keeps a high floor.
+    auto floor_for = [](const char* var, long dflt) -> long {
+        if (const char* s = std::getenv(var)) return std::atol(s);
+        return dflt;
+    };
+    const long dev_floor = floor_for("OPENSWMM_2D_MIN_PARALLEL_CELLS_DEVICE", 10000);
+    const long omp_floor = floor_for("OPENSWMM_2D_MIN_PARALLEL_CELLS", 50000);
+
+    if (n_cells <= 0 || n_cells >= dev_floor)
+        for (const char* b : {"cuda", "hip", "sycl"})
+            if (auto s = try_plugin(b, chosen, opts.requested_threads)) return s;
+    if (n_cells <= 0 || n_cells >= omp_floor)
+        if (auto s = try_plugin("omp", chosen, opts.requested_threads)) return s;
+
+    std::fprintf(stderr,
+        "[openswmm 2D] using CPU marcher (no GPU device selected; n_cells=%d, "
+        "device floor=%ld cells). Set [2D_OPTIONS] BACKEND CUDA (or "
+        "OPENSWMM_2D_BACKEND=cuda) to force the GPU, or lower "
+        "OPENSWMM_2D_MIN_PARALLEL_CELLS_DEVICE.\n",
+        n_cells, dev_floor);
     return serial_marcher();
 }
 
diff --git a/src/engine/2d/solver/SurfaceSolverFactory.hpp b/src/engine/2d/solver/SurfaceSolverFactory.hpp
index 48277f3c7..5311865e3 100644
--- a/src/engine/2d/solver/SurfaceSolverFactory.hpp
+++ b/src/engine/2d/solver/SurfaceSolverFactory.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SurfaceSolverFactory.hpp
  * @brief Runtime selection of the 2D surface solver backend (Phase 4).
@@ -10,17 +26,19 @@
  *          stays Kokkos/GPU-free; the device backend lives entirely in a
  *          separately built plugin loaded here at runtime.
  *
- *          Selection policy (env OPENSWMM_2D_BACKEND, case-insensitive):
- *            unset / "auto" : try device plugins (cuda, hip, sycl) in order;
- *                             if none load with a usable device, use the CPU
- *                             solver. The CPU-threaded "omp" plugin is NOT
- *                             auto-selected (it would change numerics on a
- *                             machine that merely has it installed) — request
- *                             it explicitly.
+ *          Selection policy. The mode comes from the OPENSWMM_2D_BACKEND
+ *          environment variable when set (case-insensitive), else from the
+ *          model's [2D_OPTIONS] BACKEND (SolverOptions2D::backend):
+ *            "auto" (default) : try device plugins (cuda, hip, sycl) in order
+ *                             above the device mesh-size floor, then the
+ *                             OpenMP plugin above its own (higher) floor; if
+ *                             none loads with a usable device, use the CPU
+ *                             solver.
  *            "cpu"          : always the serial CPU solver (no discovery).
- *            "omp"|"cuda"|"hip"|"sycl" : load exactly that plugin; if it is
- *                             absent or has no usable device, warn and fall
- *                             back to CPU (never hard-fail on GPU absence).
+ *            "omp"|"cuda"|"hip"|"sycl" : load exactly that plugin, bypassing
+ *                             the size floors; if it is absent or has no
+ *                             usable device, warn and fall back to CPU
+ *                             (never hard-fail on GPU absence).
  *
  *          Plugin search path: OPENSWMM_GPU_PLUGIN_PATH (os-separated list),
  *          then the directory of the engine shared library, then its `gpu`
@@ -30,7 +48,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_2D_SURFACE_SOLVER_FACTORY_HPP
@@ -51,7 +69,8 @@ class ISurfaceSolver;
  * CPU solver instead. A successfully loaded GPU plugin is reported on stderr;
  * the default CPU path is silent so ordinary runs produce no extra output.
  *
- * @param opts    Solver options (reserved for future per-model backend hints).
+ * @param opts    Solver options; `backend` ([2D_OPTIONS] BACKEND) is the
+ *                model's request, overridden by OPENSWMM_2D_BACKEND when set.
  * @param chosen  Optional out-param; receives a human-readable backend label
  *                (e.g. "cpu (serial CVODE)" or "cuda (NVIDIA A100)").
  * @param n_cells Triangle count of the mesh (0 = unknown). Under the default
@@ -59,14 +78,15 @@ class ISurfaceSolver;
  *                (env OPENSWMM_2D_MIN_PARALLEL_CELLS, default 20000) selects the
  *                serial CPU solver even when a GPU/OpenMP plugin is present —
  *                Kokkos' per-kernel launch overhead makes the accelerated path
- *                slower than serial on small meshes. An explicit
- *                OPENSWMM_2D_BACKEND always wins (no size gate).
+ *                slower than serial on small meshes. An explicit backend
+ *                (option or env) always wins (no size gate).
  * @return An owned ISurfaceSolver. For a plugin-backed solver the owning
  *         shared library is kept resident for the process lifetime.
  */
 std::unique_ptr makeSurfaceSolver(const SolverOptions2D& opts,
                                                   std::string* chosen = nullptr,
-                                                  int n_cells = 0);
+                                                  int n_cells = 0,
+                                                  bool plugin_capable = true);
 
 } // namespace openswmm::twoD
 
diff --git a/src/engine/2d/solver/SweKernels.hpp b/src/engine/2d/solver/SweKernels.hpp
new file mode 100644
index 000000000..a27294b9a
--- /dev/null
+++ b/src/engine/2d/solver/SweKernels.hpp
@@ -0,0 +1,349 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SweKernels.hpp
+ * @brief Face kernels for MOMENTUM_EQUATION FULL_SWE — the conservative
+ *        shallow-water equations with the convective term and shock capturing
+ *        (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.2).
+ *
+ * @details Cell state (h, q⃗ = h·u⃗) per cell; a face between cells L and R
+ *          with unit normal n̂ (L→R) evaluates one Godunov flux:
+ *
+ *            1. Hydrostatic reconstruction (Audusse et al. 2004) against the
+ *               face bed z_f = max(z_L, z_R), z_side = η_side − h_side:
+ *                 h*_L = max(0, η_L − z_f),  h*_R = max(0, η_R − z_f)
+ *            2. Rotate the velocities into the (n̂, t̂) frame, t̂ = (−n_y, n_x).
+ *            3. HLLC (Toro 2001) on U = [h, h·u_n, h·u_t]: HLL for mass and
+ *               normal momentum, tangential momentum upwinded on the contact
+ *               speed S*. Wave speeds from the two-rarefaction estimate with
+ *               the dry-bed limits.
+ *            4. Rotate the momentum flux back to (x, y).
+ *            5. Bed-slope source per side, ½·g·(h*² − h²)·n̂ (the Audusse
+ *               correction): at rest the HLLC flux is [0, ½g h*², 0] and the
+ *               correction cancels it face by face, so a lake at rest over any
+ *               bed is an exact steady state (C-property).
+ *
+ *          Friction is applied per cell after the flux update, semi-implicit
+ *          (the same division the local-inertial face law uses), which can
+ *          only shrink |q⃗| and never reverses it (Liang & Marche 2009's
+ *          stopping condition is satisfied by construction).
+ *
+ *          Everything is plain scalar arithmetic over raw values so the same
+ *          bodies can be annotated for Kokkos later (OPENSWMM_KERNEL_FN).
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SWE_KERNELS_HPP
+#define OPENSWMM_ENGINE_2D_SWE_KERNELS_HPP
+
+#include 
+#include 
+
+#ifndef OPENSWMM_KERNEL_FN
+#define OPENSWMM_KERNEL_FN inline
+#endif
+
+namespace openswmm::twoD::swe {
+
+inline constexpr double kGravity = 9.80665;
+
+/// One side of a face in the face-normal frame after hydrostatic
+/// reconstruction. `h` is the reconstructed depth h*, (un, ut) the normal and
+/// tangential velocity components (zero when the cell is dry).
+struct FaceSide {
+    double h  = 0.0;
+    double un = 0.0;
+    double ut = 0.0;
+};
+
+/// Flux through the face, positive L→R: mass (m²/s), momentum in the x/y
+/// frame (m³/s²). `sstar` is the HLLC contact speed used to upwind passive
+/// scalars (species ride the mass flux from the side S* points away from).
+struct FaceFlux {
+    double mass = 0.0;
+    double mx   = 0.0;
+    double my   = 0.0;
+    double sstar = 0.0;
+};
+
+/// Physical flux of the SWE in the normal frame: [h·un, h·un² + ½g h², h·un·ut].
+OPENSWMM_KERNEL_FN void physicalFlux(const FaceSide& s, double& fh, double& fn,
+                                     double& ft) noexcept {
+    fh = s.h * s.un;
+    fn = s.h * s.un * s.un + 0.5 * kGravity * s.h * s.h;
+    ft = s.h * s.un * s.ut;
+}
+
+/// Wave-speed estimates S_L ≤ S_R (Toro 2001 §10.4): two-rarefaction
+/// estimate for wet–wet faces, the exact dry-bed front speeds otherwise.
+OPENSWMM_KERNEL_FN void waveSpeeds(const FaceSide& L, const FaceSide& R,
+                                   double& sl, double& sr) noexcept {
+    const double cl = std::sqrt(kGravity * L.h);
+    const double cr = std::sqrt(kGravity * R.h);
+    if (L.h > 0.0 && R.h > 0.0) {
+        const double ustar = 0.5 * (L.un + R.un) + cl - cr;
+        const double cstar = 0.5 * (cl + cr) + 0.25 * (L.un - R.un);
+        sl = std::min(L.un - cl, ustar - cstar);
+        sr = std::max(R.un + cr, ustar + cstar);
+    } else if (L.h > 0.0) {            // dry right
+        sl = L.un - cl;
+        sr = L.un + 2.0 * cl;
+    } else if (R.h > 0.0) {            // dry left
+        sl = R.un - 2.0 * cr;
+        sr = R.un + cr;
+    } else {
+        sl = sr = 0.0;
+    }
+}
+
+/**
+ * @brief HLLC flux in the face-normal frame.
+ *
+ * @param L,R  reconstructed side states (h*, un, ut)
+ * @param fh   out: mass flux (m²/s), positive L→R
+ * @param fn   out: normal-momentum flux (m³/s²)
+ * @param ft   out: tangential-momentum flux (m³/s²)
+ * @param sstar out: contact speed (m/s)
+ */
+OPENSWMM_KERNEL_FN void hllcFlux(const FaceSide& L, const FaceSide& R,
+                                 double& fh, double& fn, double& ft,
+                                 double& sstar) noexcept {
+    if (L.h <= 0.0 && R.h <= 0.0) {
+        fh = fn = ft = 0.0; sstar = 0.0;
+        return;
+    }
+    double sl, sr;
+    waveSpeeds(L, R, sl, sr);
+    double fhl, fnl, ftl, fhr, fnr, ftr;
+    physicalFlux(L, fhl, fnl, ftl);
+    physicalFlux(R, fhr, fnr, ftr);
+
+    // Contact speed (Toro Eq. 10.70) — falls back to the mean normal
+    // velocity when the denominator degenerates (both sides at rest).
+    const double dl = L.h * (L.un - sl), dr = R.h * (R.un - sr);
+    const double den = dr - dl;
+    sstar = (std::fabs(den) > 1.0e-14) ? (sl * dr - sr * dl) / den
+                                       : 0.5 * (L.un + R.un);
+
+    if (sl >= 0.0) {
+        fh = fhl; fn = fnl; ft = ftl;
+    } else if (sr <= 0.0) {
+        fh = fhr; fn = fnr; ft = ftr;
+    } else {
+        // HLL middle state for mass and normal momentum.
+        const double inv = 1.0 / (sr - sl);
+        fh = (sr * fhl - sl * fhr + sl * sr * (R.h - L.h)) * inv;
+        fn = (sr * fnl - sl * fnr + sl * sr * (R.h * R.un - L.h * L.un)) * inv;
+        // Tangential momentum: passive scalar upwinded on the contact.
+        ft = fh * ((sstar >= 0.0) ? L.ut : R.ut);
+    }
+}
+
+/**
+ * @brief Full face evaluation: hydrostatic reconstruction, rotation, HLLC,
+ *        rotation back, and the per-side bed-slope corrections.
+ *
+ * @param etaL,hL,qxL,qyL   left cell free surface, depth, unit discharge
+ * @param etaR,hR,qxR,qyR   right cell
+ * @param nx,ny             unit normal L→R
+ * @param h_dry             depth below which a cell's velocity is zero
+ * @param out               flux (x/y frame), positive L→R
+ * @param corrL_x,corrL_y   out: bed-slope correction for L, ½g(h*_L² − h_L²)·n̂
+ *                          (per unit face length; multiply by ξ·Δt)
+ * @param corrR_x,corrR_y   out: for R, ½g(h*_R² − h_R²)·(−n̂)
+ * @return true when the face carries any flux (at least one side wet after
+ *         reconstruction); false ⇒ every output is zero.
+ */
+OPENSWMM_KERNEL_FN bool faceFlux(double etaL, double hL, double qxL, double qyL,
+                                 double etaR, double hR, double qxR, double qyR,
+                                 double nx, double ny, double h_dry,
+                                 FaceFlux& out,
+                                 double& corrL_x, double& corrL_y,
+                                 double& corrR_x, double& corrR_y) noexcept {
+    // Beds consistent with the storage: z = η − h̄ (FLAT closure: the cell
+    // mean bed; VFR: the flat-equivalent bed, which is what keeps a uniform η
+    // an exact rest state under either closure).
+    const double zL = etaL - hL, zR = etaR - hR;
+    const double zf = (zL > zR) ? zL : zR;
+    FaceSide L, R;
+    L.h = (etaL - zf > 0.0) ? etaL - zf : 0.0;
+    R.h = (etaR - zf > 0.0) ? etaR - zf : 0.0;
+    // A side whose reconstructed depth is negligible carries no velocity
+    // (avoids q/h blow-ups at fronts); the hydrostatic reconstruction alone
+    // already removes the "dry cell standing higher" flux.
+    const double tx = -ny, ty = nx;
+    if (hL > h_dry && L.h > 0.0) {
+        const double ux = qxL / hL, uy = qyL / hL;
+        L.un = ux * nx + uy * ny;
+        L.ut = ux * tx + uy * ty;
+    }
+    if (hR > h_dry && R.h > 0.0) {
+        const double ux = qxR / hR, uy = qyR / hR;
+        R.un = ux * nx + uy * ny;
+        R.ut = ux * tx + uy * ty;
+    }
+    corrL_x = corrL_y = corrR_x = corrR_y = 0.0;
+    if (L.h <= 0.0 && R.h <= 0.0) {
+        out = FaceFlux{};
+        return false;
+    }
+    double fh, fn, ft, sstar;
+    hllcFlux(L, R, fh, fn, ft, sstar);
+    out.mass  = fh;
+    out.mx    = fn * nx + ft * tx;
+    out.my    = fn * ny + ft * ty;
+    out.sstar = sstar;
+    // Audusse bed-slope corrections (½g(h*² − h²)·n̂_out per side).
+    const double cL = 0.5 * kGravity * (L.h * L.h - hL * hL);
+    const double cR = 0.5 * kGravity * (R.h * R.h - hR * hR);
+    corrL_x =  cL * nx; corrL_y =  cL * ny;
+    corrR_x = -cR * nx; corrR_y = -cR * ny;
+    return true;
+}
+
+/**
+ * @brief Face flux from RECONSTRUCTED side states (RECONSTRUCTION_ORDER 2).
+ *
+ * The free surface and velocities are the MUSCL-extrapolated face values and
+ * the bed stays piecewise constant per cell (z_side = η_cell − h_cell); the
+ * bed-slope correction uses the reconstructed face depth, so at rest (zero
+ * gradients) the face reduces exactly to the first-order well-balanced form.
+ *
+ * @param etaLf,uxLf,uyLf   left face-extrapolated free surface and velocity
+ * @param zL,hL_cell        left cell bed and cell-mean depth
+ * @param etaRf,...         right side likewise
+ */
+OPENSWMM_KERNEL_FN bool faceFluxRecon(double etaLf, double uxLf, double uyLf,
+                                      double zL, double hL_cell,
+                                      double etaRf, double uxRf, double uyRf,
+                                      double zR, double hR_cell,
+                                      double nx, double ny, double h_dry,
+                                      FaceFlux& out,
+                                      double& corrL_x, double& corrL_y,
+                                      double& corrR_x, double& corrR_y) noexcept {
+    const double zf = (zL > zR) ? zL : zR;
+    FaceSide L, R;
+    L.h = (etaLf - zf > 0.0) ? etaLf - zf : 0.0;
+    R.h = (etaRf - zf > 0.0) ? etaRf - zf : 0.0;
+    const double tx = -ny, ty = nx;
+    if (hL_cell > h_dry && L.h > 0.0) {
+        L.un = uxLf * nx + uyLf * ny;
+        L.ut = uxLf * tx + uyLf * ty;
+    }
+    if (hR_cell > h_dry && R.h > 0.0) {
+        R.un = uxRf * nx + uyRf * ny;
+        R.ut = uxRf * tx + uyRf * ty;
+    }
+    corrL_x = corrL_y = corrR_x = corrR_y = 0.0;
+    if (L.h <= 0.0 && R.h <= 0.0) { out = FaceFlux{}; return false; }
+    double fh, fn, ft, sstar;
+    hllcFlux(L, R, fh, fn, ft, sstar);
+    out.mass  = fh;
+    out.mx    = fn * nx + ft * tx;
+    out.my    = fn * ny + ft * ty;
+    out.sstar = sstar;
+    // Audusse et al. (2004) second order with a piecewise-constant bed per
+    // cell: the correction pairs h* with the RECONSTRUCTED face depth
+    // h⁻ = η_f − z_cell (the centred bed term vanishes), so the flux keeps the
+    // interface pressure difference a linear surface implies. Reduces to the
+    // first-order form when the gradients are zero (rest state exact).
+    const double hLf = (etaLf - zL > 0.0) ? etaLf - zL : 0.0;
+    const double hRf = (etaRf - zR > 0.0) ? etaRf - zR : 0.0;
+    const double cL = 0.5 * kGravity * (L.h * L.h - hLf * hLf);
+    const double cR = 0.5 * kGravity * (R.h * R.h - hRf * hRf);
+    corrL_x =  cL * nx; corrL_y =  cL * ny;
+    corrR_x = -cR * nx; corrR_y = -cR * ny;
+    return true;
+}
+
+/// Barth–Jespersen limiter factor φ ∈ [0, 1] for one cell/variable given the
+/// cell value w, the extrapolated face value wf and the min/max over the
+/// cell and its neighbours.
+OPENSWMM_KERNEL_FN double bjLimiter(double w, double wf, double wmin, double wmax) noexcept {
+    const double d = wf - w;
+    if (d > 1.0e-14)       return std::min(1.0, (wmax - w) / d);
+    else if (d < -1.0e-14) return std::min(1.0, (wmin - w) / d);
+    return 1.0;
+}
+
+/// Semi-implicit Manning friction on a cell's unit discharge over Δt:
+/// q⃗ ← q⃗ / (1 + g·Δt·n²·|q⃗| / h^{7/3}). Only shrinks |q⃗|; never reverses it.
+OPENSWMM_KERNEL_FN void frictionUpdate(double& qx, double& qy, double h, double n,
+                                       double dt) noexcept {
+    if (!(h > 0.0)) { qx = qy = 0.0; return; }
+    const double qm = std::sqrt(qx * qx + qy * qy);
+    if (qm == 0.0) return;
+    const double h73 = h * h * std::cbrt(h);
+    const double den = 1.0 + kGravity * dt * n * n * qm / h73;
+    qx /= den;
+    qy /= den;
+}
+
+/// Critical depth for a per-metre discharge q: (q²/g)^{1/3} — the ghost
+/// depth of a prescribed-flow boundary entering a dry cell.
+OPENSWMM_KERNEL_FN double criticalDepth(double q) noexcept {
+    return std::cbrt(q * q / kGravity);
+}
+
+/*!
+ * \brief Ghost depth of a SUBCRITICAL prescribed-discharge boundary.
+ *
+ * One characteristic leaves the domain there, so its Riemann invariant
+ * \p r = u + 2c is carried out from the interior and, with the prescribed
+ * per-metre discharge \p q = u·h, fixes the boundary depth:
+ *
+ *     q/h + 2·sqrt(g·h) = r      ⇔      2·sqrt(g)·s³ − r·s² + q = 0,  s = sqrt(h)
+ *
+ * Safeguarded Newton on s from the interior depth (bracketed to s > 0, ≤ 40
+ * iterations); returns \p h_interior when it cannot converge — the caller's
+ * mass flux is prescribed either way, so a fallback only costs accuracy in
+ * the momentum flux, never conservation. Signs follow the outward normal:
+ * an inflow has q < 0.
+ */
+OPENSWMM_KERNEL_FN double depthFromInvariantAndDischarge(double r, double q,
+                                                         double h_interior) noexcept {
+    const double rg = std::sqrt(kGravity);
+    double s = std::sqrt(h_interior > 0.0 ? h_interior : 1.0e-6);
+    for (int it = 0; it < 40; ++it) {
+        const double f  = 2.0 * rg * s * s * s - r * s * s + q;
+        const double df = 6.0 * rg * s * s - 2.0 * r * s;
+        if (!(std::fabs(df) > 1.0e-12)) break;
+        const double s1 = s - f / df;
+        if (!(s1 > 0.0) || !std::isfinite(s1)) break;
+        const double step = std::fabs(s1 - s);
+        s = s1;
+        if (step < 1.0e-12 * (1.0 + s)) {
+            const double h = s * s;
+            return (h > 0.0 && std::isfinite(h)) ? h : h_interior;
+        }
+    }
+    const double h = s * s;
+    // Accept only a converged, physical root; otherwise keep the interior
+    // depth (transmissive), which is what the pre-invariant code did.
+    return (h > 0.0 && std::isfinite(h) &&
+            std::fabs(2.0 * rg * s * s * s - r * s * s + q) < 1.0e-6 * (1.0 + std::fabs(q)))
+               ? h : h_interior;
+}
+
+} // namespace openswmm::twoD::swe
+
+#endif // OPENSWMM_ENGINE_2D_SWE_KERNELS_HPP
diff --git a/src/engine/2d/subsurface/SigmaColumn.cpp b/src/engine/2d/subsurface/SigmaColumn.cpp
new file mode 100644
index 000000000..b1c9778ee
--- /dev/null
+++ b/src/engine/2d/subsurface/SigmaColumn.cpp
@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SigmaColumn.cpp
+ * @brief G-steps 4 and 5 — see the header for the coordinate, the flux forms
+ *        and the handover convention.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SigmaColumn.hpp"
+
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD::sigma {
+
+namespace {
+
+constexpr double kLMin  = 1.0e-3;   ///< column thickness floor (m)
+constexpr double kTiny  = 1.0e-300;
+
+inline double& at(double* t, int j, int stride) noexcept {
+    return t[static_cast(j) * static_cast(stride)];
+}
+inline double at(const double* t, int j, int stride) noexcept {
+    return t[static_cast(j) * static_cast(stride)];
+}
+
+/// Harmonic mean, zero when either side is zero (the conductive-series rule).
+inline double harmonic(double a, double b) noexcept {
+    const double s = a + b;
+    return (s > kTiny) ? (2.0 * a * b / s) : 0.0;
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+
+double columnStorage(const double* theta, int m, int stride, double L) noexcept {
+    const double dz = std::max(L, kLMin) / static_cast(m);
+    double s = 0.0;
+    for (int j = 0; j < m; ++j) s += at(theta, j, stride) * dz;
+    return s;
+}
+
+void seedHydrostatic(const soil::Params& p, double* theta, int m, int stride,
+                     double L) noexcept {
+    const double Lc = std::max(L, kLMin);
+    const double dsig = 1.0 / static_cast(m);
+    for (int j = 0; j < m; ++j) {
+        // Layer centre: σ = (j + ½)/m, and ψ is the height ABOVE the table,
+        // so ψ = L·(1 − σ). Layer 0 is at the surface (largest suction).
+        const double sig = (static_cast(j) + 0.5) * dsig;
+        const double psi = Lc * (1.0 - sig);
+        at(theta, j, stride) = soil::waterContent(p, psi);
+    }
+}
+
+double columnDtLimit(const soil::Params& p, const double* theta, int m,
+                     int stride, double L, double Ldot, double c_col,
+                     bool capillary) noexcept {
+    const double Lc = std::max(L, kLMin);
+    const double dsig = 1.0 / static_cast(m);
+    const double dz = Lc * dsig;
+    double lim = 1.0e30;
+    for (int j = 0; j < m; ++j) {
+        const double th = std::clamp(at(theta, j, stride), p.theta_r, p.theta_s);
+        // Celerity c(θ) = dK/dθ, by a centred difference through the
+        // retention inverse: the analytic form differs per law and per
+        // branch, and this runs once per rebuild, not per firing.
+        const double span = std::max(p.theta_s - p.theta_r, 1.0e-9);
+        const double se   = std::clamp((th - p.theta_r) / span, 1.0e-8, 1.0);
+        const double dse  = 1.0e-3;
+        const double se_hi = std::min(se + dse, 1.0);
+        const double se_lo = std::max(se - dse, 1.0e-8);
+        const double k_hi = soil::conductivity(p, soil::suctionAtSaturation(p, se_hi));
+        const double k_lo = soil::conductivity(p, soil::suctionAtSaturation(p, se_lo));
+        const double c = std::fabs(k_hi - k_lo) /
+                         std::max((se_hi - se_lo) * span, 1.0e-12);
+
+        const double sig = (static_cast(j) + 0.5) * dsig;
+        const double grid = std::fabs(sig * Ldot);
+        double diff = 0.0;
+        if (capillary) {
+            const double psi = soil::suctionAtSaturation(p, se);
+            diff = 2.0 * soil::diffusivity(p, psi) / std::max(dz, 1.0e-12);
+        }
+        const double denom = c + grid + diff;
+        if (denom > kTiny) lim = std::min(lim, dz / denom);
+    }
+    return std::max(c_col, 1.0e-6) * lim;
+}
+
+// ---------------------------------------------------------------------------
+
+void advanceColumn(const soil::Params& p, double* theta, int m, int stride,
+                   ColumnStep& st) noexcept {
+    if (m <= 0 || !(st.dt > 0.0)) return;
+
+    const double dsig = 1.0 / static_cast(m);
+    const double L0   = std::max(st.L_old, kLMin);
+    const double L1   = std::max(st.L_new, kLMin);
+    const double Ldot = (L1 - L0) / st.dt;
+
+    st.dt_limit = columnDtLimit(p, theta, m, stride, L0, Ldot, 1.0, st.capillary);
+
+    // ---- 1. w_j from the OLD geometry. w is the conserved quantity; θ is a
+    //         derived view of it, and it is re-derived from the NEW L at the
+    //         end. That ordering is the whole ALE bookkeeping.
+    static thread_local std::vector w, w_new, th_old, f;
+    w.assign(static_cast(m), 0.0);
+    th_old.assign(static_cast(m), 0.0);
+    f.assign(static_cast(m) + 1, 0.0);
+    const double dz0 = L0 * dsig;
+    for (int j = 0; j < m; ++j) {
+        th_old[static_cast(j)] =
+            std::clamp(at(theta, j, stride), p.theta_r, p.theta_s);
+        w[static_cast(j)] = th_old[static_cast(j)] * dz0;
+    }
+
+    auto psiOf = [&](double th) {
+        const double span = std::max(p.theta_s - p.theta_r, 1.0e-9);
+        const double se = std::clamp((th - p.theta_r) / span, 1.0e-8, 1.0);
+        return soil::suctionAtSaturation(p, se);
+    };
+
+    // ---- 2. Interior faces. f[j] is the face ABOVE layer j (σ = j/m), so
+    //         f[0] is the top boundary and f[m] the bottom.
+    for (int jf = 1; jf < m; ++jf) {
+        const int up = jf - 1;              // layer above the face
+        const int dn = jf;                  // layer below
+        const double th_up = th_old[static_cast(up)];
+        const double th_dn = th_old[static_cast(dn)];
+        const double sig_f = static_cast(jf) * dsig;
+
+        // (a) gravity — downward, donor is the layer above.
+        double flux = soil::conductivity(p, psiOf(th_up));
+
+        // (b) grid motion, upwinded on its own sign. The face moves at
+        //     ż = σ_f·L̇; the relative flux is −θ_donor·ż, so L̇ > 0 (faces
+        //     sweeping down into the column) takes the layer BELOW.
+        const double zdot = sig_f * Ldot;
+        const double th_grid = (zdot > 0.0) ? th_dn : th_up;
+        flux -= th_grid * zdot;
+
+        // (c) capillary diffusion, harmonic-mean D̄ across the face.
+        if (st.capillary) {
+            const double d_up = soil::diffusivity(p, psiOf(th_up));
+            const double d_dn = soil::diffusivity(p, psiOf(th_dn));
+            const double dbar = harmonic(d_up, d_dn);
+            flux -= dbar * (th_dn - th_up) / std::max(L0 * dsig, 1.0e-12);
+        }
+        f[static_cast(jf)] = flux;
+    }
+
+    // ---- 3. Top boundary: infiltration in, ET out, with acceptance.
+    //         The top layer can hold at most (θ_s − θ_top)·dz more water;
+    //         anything beyond that is rejected to the surface.
+    {
+        const double th_top = th_old[0];
+        const double headroom = std::max(p.theta_s - th_top, 0.0) * dz0 / st.dt;
+        const double accept = std::min(std::max(st.q_in, 0.0), headroom);
+        st.f_top    = accept;
+        st.rejected = std::max(st.q_in, 0.0) - accept;
+
+        // ET is limited by what the top layer holds above residual, and by
+        // the Feddes stress at its own suction — no `if (infil <= 0)` gate.
+        const double avail = std::max(th_top - p.theta_r, 0.0) * dz0 / st.dt;
+        const double psi_top = psiOf(th_top);
+        // Wilting suction from the law's own residual end: the suction at
+        // 1 % effective saturation is a stable, law-agnostic proxy.
+        const double psi_w = soil::suctionAtSaturation(p, 0.01);
+        const double stress = soil::feddesStress(psi_top, psi_w);
+        st.et_taken = std::min(std::max(st.q_et, 0.0) * stress, avail);
+        f[0] = st.f_top - st.et_taken;
+    }
+
+    // ---- 4. Bottom boundary: physical Darcy across the table PLUS the
+    //         handover swept by the moving boundary (σ = 1, ż = L̇).
+    {
+        const double th_bot = th_old[static_cast(m - 1)];
+        st.f_bot = st.q0_phys - th_bot * Ldot;
+        f[static_cast(m)] = st.f_bot;
+    }
+
+    // ---- 5. Positivity share. A layer may not export more than it holds
+    //         above residual over this step; when its outgoing faces
+    //         over-subscribe it they are scaled together, exactly like the
+    //         surface solver's volume share. Applied to interior faces and
+    //         the bottom face (the top face is already capped above).
+    for (int j = 0; j < m; ++j) {
+        const double avail = std::max(w[static_cast(j)] -
+                                      p.theta_r * dz0, 0.0);
+        double out = 0.0;
+        if (f[static_cast(j)] < 0.0)
+            out += -f[static_cast(j)] * st.dt;      // upward out of j
+        if (f[static_cast(j + 1)] > 0.0)
+            out += f[static_cast(j + 1)] * st.dt;   // downward out of j
+        if (out > avail && out > kTiny) {
+            const double beta = avail / out;
+            if (f[static_cast(j)] < 0.0)
+                f[static_cast(j)] *= beta;
+            if (f[static_cast(j + 1)] > 0.0) {
+                f[static_cast(j + 1)] *= beta;
+                if (j == m - 1) st.f_bot = f[static_cast(m)];
+            }
+        }
+    }
+
+    // ---- 6. Update w, then re-derive θ from the NEW geometry. This is where
+    //         the layers compress: same water, new dz.
+    //
+    //   A rising table (L shrinking) compresses every layer. A layer whose
+    //   water then exceeds θ_s·dz_new is SATURATED, and the surplus belongs
+    //   to the saturated zone — it must not be clamped away. Clamping it was
+    //   the first version of this function and it lost 3.9e-1 m of water on
+    //   the closed-column oscillation gate: the classic σ-grid failure the
+    //   plan names in its risks. So the surplus cascades DOWNWARD layer by
+    //   layer (each full layer pushes into the one below) and whatever
+    //   reaches the bottom is reported as `overflow_to_sat`, which the
+    //   solver adds to the saturated zone in this same firing. A deficit
+    //   below residual is drawn the same way, reported as
+    //   `deficit_from_sat`. With both routed, Σw is conserved exactly and
+    //   the gate passes to machine precision.
+    const double dz1 = L1 * dsig;
+    w_new.assign(static_cast(m), 0.0);
+    for (int j = 0; j < m; ++j) {
+        w_new[static_cast(j)] =
+            w[static_cast(j)] +
+            st.dt * (f[static_cast(j)] -
+                     f[static_cast(j + 1)]);
+    }
+
+    const double w_max = p.theta_s * dz1;
+    const double w_min = p.theta_r * dz1;
+
+    // Cascade surplus downward; the bottom layer's surplus leaves the column.
+    double carry = 0.0;
+    for (int j = 0; j < m; ++j) {
+        double wj = w_new[static_cast(j)] + carry;
+        carry = 0.0;
+        if (wj > w_max) { carry = wj - w_max; wj = w_max; }
+        w_new[static_cast(j)] = wj;
+    }
+    st.overflow_to_sat = carry / st.dt;      // m/s down across the table
+
+    // Draw any residual deficit upward from the table (capillary support).
+    double draw = 0.0;
+    for (int j = m - 1; j >= 0; --j) {
+        double wj = w_new[static_cast(j)] - draw;
+        draw = 0.0;
+        if (wj < w_min) { draw = w_min - wj; wj = w_min; }
+        w_new[static_cast(j)] = wj;
+    }
+    st.deficit_from_sat = draw / st.dt;      // m/s up across the table
+
+    for (int j = 0; j < m; ++j)
+        at(theta, j, stride) =
+            w_new[static_cast(j)] / std::max(dz1, 1.0e-12);
+    st.theta_bot = at(theta, m - 1, stride);
+}
+
+}  // namespace openswmm::twoD::sigma
diff --git a/src/engine/2d/subsurface/SigmaColumn.hpp b/src/engine/2d/subsurface/SigmaColumn.hpp
new file mode 100644
index 000000000..819f63a34
--- /dev/null
+++ b/src/engine/2d/subsurface/SigmaColumn.hpp
@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SigmaColumn.hpp
+ * @brief G-steps 4 and 5 — closure B: the σ-coordinate explicit unsaturated
+ *        column with a moving lower boundary (the water table).
+ *
+ * @section sigma_layout Coordinate and state
+ *
+ * The column occupies `z ∈ [0, L]` measured DOWNWARD from the ground
+ * surface, `L = z_s − h_g`. Map to `σ = z/L ∈ [0,1]` with a **fixed** layer
+ * count `m`; layer `j` owns `σ ∈ [j/m, (j+1)/m]`, `Δσ = 1/m`. Layers
+ * stretch and compress as the table moves — no regridding, no variable layer
+ * counts, fixed SoA stride.
+ *
+ * The conserved quantity is **water depth per layer**, `w_j = θ_j·L·Δσ`
+ * (metres of water). Evolving `w` and deriving `θ = w/(L·Δσ)` from the NEW
+ * `L` is what makes the compression exact: a column whose faces move but
+ * whose fluxes vanish keeps every `w_j` unchanged, so total water is
+ * invariant to machine precision. That is plan gate 5, and it holds by
+ * construction here rather than by cancellation.
+ *
+ * @section sigma_fluxes Fluxes
+ *
+ * ```
+ * w_j ← w_j + Δt·( F_{j−1/2} − F_{j+1/2} )          [downward-positive]
+ *
+ * F_{j+1/2} = K(θ_up)                                  advective, upwind
+ *           − θ_donor·σ_{j+1/2}·L̇                      grid motion (ALE)
+ *           − ( D̄_{j+1/2} / (L·Δσ) )·( θ_{j+1} − θ_j ) optional capillary
+ * ```
+ *
+ * - Gravity is downward, so the advective donor is always the layer above.
+ * - The grid term is upwinded on its own sign: with `L̇ > 0` (table falling,
+ *   column growing) the faces sweep downward and the donor is the layer
+ *   below; with `L̇ < 0` it is the layer above.
+ * - `D̄` is the harmonic mean of the two layers' diffusivities. Off by
+ *   default (D-N3).
+ *
+ * @section sigma_bc Boundaries and the handover
+ *
+ * - **Top (σ=0):** `F_top = q⁺ − q_ET`, with the top layer's acceptance
+ *   capping `q⁺` — the excess is *rejected* and returned to the caller for
+ *   the surface state (Hortonian / saturation rejection).
+ * - **Bottom (σ=1):** `F_bot = q₀_phys − θ_bot·L̇`. The first term is the
+ *   physical Darcy flux across the table; the second is the **handover** —
+ *   the water swept across the moving boundary. Both together are what the
+ *   saturated zone gains, which is why `SubsurfaceSolver` books
+ *   `F_bot` and not `q₀_phys` as the recharge.
+ *
+ * @note **Specific yield.** Making the handover explicit forces the
+ *       saturated update's storage coefficient to be `θ_s − θ_bot`, not
+ *       `θ_s`. The plan's §2.1 writes `θ_s`; `θ_s − θ_bot` is what actually
+ *       conserves once the column retains water above a falling table, and
+ *       it is the textbook specific yield. This is the one place this
+ *       implementation is deliberately more precise than the plan text, and
+ *       it is called out again in `SubsurfaceSolver::fireCell`.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SIGMA_COLUMN_HPP
+#define OPENSWMM_ENGINE_2D_SIGMA_COLUMN_HPP
+
+#include "SoilCharacteristic.hpp"
+
+namespace openswmm::twoD::sigma {
+
+/// What one column sweep needs and what it reports back.
+struct ColumnStep {
+    // ---- in ----
+    double L_old   = 1.0;    ///< column thickness before the table moved (m)
+    double L_new   = 1.0;    ///< …and after (m). `L̇ = (L_new − L_old)/dt`.
+    double dt      = 1.0;    ///< the cell's tier step (s)
+    double q_in    = 0.0;    ///< infiltration offered at the top (m/s, ≥ 0)
+    double q_et    = 0.0;    ///< ET demand at the top (m/s, ≥ 0)
+    double q0_phys = 0.0;    ///< physical Darcy flux across the table (m/s)
+    bool   capillary = false;///< include the diffusive term
+
+    // ---- out ----
+    double f_top     = 0.0;  ///< accepted top flux (m/s) — `q_in` after rejection
+    double rejected  = 0.0;  ///< `q_in − f_top` (m/s, ≥ 0) back to the surface
+    double f_bot     = 0.0;  ///< total bottom flux incl. handover (m/s)
+    double et_taken  = 0.0;  ///< ET actually removed (m/s, ≤ `q_et`)
+    double theta_bot = 0.0;  ///< bottom-layer θ after the sweep (specific yield)
+    double dt_limit  = 1.0e30; ///< the column's own explicit stability bound (s)
+    /// Water (m/s) the compressed column could not hold, delivered DOWN to
+    /// the saturated zone in this same firing. A rising table saturates the
+    /// column from below; clamping this away is the ALE failure plan gate 5
+    /// exists to catch, so it is routed and the solver must apply it.
+    double overflow_to_sat  = 0.0;
+    /// …and the mirror: water (m/s) drawn UP from the table to hold layers
+    /// at residual when the column stretches faster than the fluxes fill it.
+    double deficit_from_sat = 0.0;
+};
+
+/**
+ * @brief Advance one σ column by `st.dt`.
+ *
+ * @param p      the cell's soil law and parameters
+ * @param theta  `m` layer water contents, layer 0 at the surface. Read and
+ *               written in place; stride is the caller's (the SoA is
+ *               layer-major, so the caller passes a gathered/scattered
+ *               buffer or a strided view — see `stride`).
+ * @param m      layer count
+ * @param stride distance between consecutive layers in @p theta (1 for a
+ *               packed buffer, `n_cells` for the layer-major SoA)
+ * @param st     step inputs and outputs
+ *
+ * Positivity is enforced per face by an availability share, the same idiom
+ * as the surface solver's volume share: a face may not take more water than
+ * its donor layer holds above `θ_r`, and the shares are scaled together when
+ * a layer's outgoing faces over-subscribe it. First-order upwind in v1
+ * (D-N4); MUSCL is a recorded follow-up.
+ */
+void advanceColumn(const soil::Params& p, double* theta, int m, int stride,
+                   ColumnStep& st) noexcept;
+
+/// The explicit stability bound of a column, without advancing it (§2.3):
+/// `Δt_u ≤ C_col·min_j[ L·Δσ / ( c(θ_j) + |σ_j·L̇| + 2·D̄_j/(L·Δσ) ) ]`
+/// with celerity `c(θ) = dK/dθ`.
+double columnDtLimit(const soil::Params& p, const double* theta, int m,
+                     int stride, double L, double Ldot, double c_col,
+                     bool capillary) noexcept;
+
+/// Seed a column to hydrostatic equilibrium above a table at depth `L`.
+void seedHydrostatic(const soil::Params& p, double* theta, int m, int stride,
+                     double L) noexcept;
+
+/// Total water in the column (m of water) — `Σ θ_j·L·Δσ`.
+double columnStorage(const double* theta, int m, int stride, double L) noexcept;
+
+}  // namespace openswmm::twoD::sigma
+
+#endif  // OPENSWMM_ENGINE_2D_SIGMA_COLUMN_HPP
diff --git a/src/engine/2d/subsurface/SoilCharacteristic.cpp b/src/engine/2d/subsurface/SoilCharacteristic.cpp
new file mode 100644
index 000000000..f74ba1589
--- /dev/null
+++ b/src/engine/2d/subsurface/SoilCharacteristic.cpp
@@ -0,0 +1,312 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SoilCharacteristic.cpp
+ * @brief G-steps 2 and 13 — see the header, especially its @warning about
+ *        which `q₀` rates are published closed forms and which are ours.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SoilCharacteristic.hpp"
+
+#include 
+#include 
+
+namespace openswmm::twoD::soil {
+
+namespace {
+
+/// Below this suction the column is at the table and everything is saturated.
+constexpr double kPsiEps = 1.0e-12;
+/// Floor on the column thickness so `L → 0` (water table at the surface)
+/// divides by something finite. A millimetre of column is already the Dunne
+/// regime, where the saturated update takes over.
+constexpr double kLMin = 1.0e-3;
+/// Se is kept strictly inside (0, 1] so `Se^(1/m)` and its inverse stay finite.
+constexpr double kSeMin = 1.0e-8;
+
+/// 4-point Gauss–Legendre on [0, 1]: enough for a monotone retention curve,
+/// and fixed-order so the cost is a compile-time constant (the plan budgets
+/// van Genuchten at ≈2× Gardner, which this meets).
+constexpr double kGlX[4] = {0.0694318442029737, 0.3300094782075719,
+                            0.6699905217924281, 0.9305681557970263};
+constexpr double kGlW[4] = {0.1739274225687269, 0.3260725774312731,
+                            0.3260725774312731, 0.1739274225687269};
+
+double clampSe(double se) noexcept {
+    return std::clamp(se, kSeMin, 1.0);
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// Retention and conductivity
+// ---------------------------------------------------------------------------
+
+double effectiveSaturation(const Params& p, double psi) noexcept {
+    if (!(psi > kPsiEps)) return 1.0;
+    switch (p.law) {
+        case SoilChar::GARDNER:
+            // Gardner's exponential retention: Se = e^(−αψ). Not
+            // Mualem-consistent (the reason Russo is the default), but it is
+            // the form that yields eq. 22.
+            return clampSe(std::exp(-p.alpha * psi));
+        case SoilChar::RUSSO:
+            // Russo (1988) retention consistent with Mualem at L = 0.5:
+            // Se = [ (1 + ½αψ)·e^(−½αψ) ]^(2/(2+L))  →  with L = 0.5 the
+            // exponent is 4/5. Kr below is then the Mualem integral of it.
+            {
+                const double a = 0.5 * p.alpha * psi;
+                const double base = (1.0 + a) * std::exp(-a);
+                const double expo = 2.0 / (2.0 + p.vg_L);
+                return clampSe(std::pow(std::max(base, kSeMin), expo));
+            }
+        case SoilChar::BROOKS_COREY:
+            // Se = 1 for ψ ≤ ψ_b, else (ψ_b/ψ)^λ. The branch at the
+            // air-entry pressure is the non-smoothness the draft flagged.
+            {
+                const double pb = std::max(p.psi_b, kPsiEps);
+                if (psi <= pb) return 1.0;
+                return clampSe(std::pow(pb / psi, p.lambda));
+            }
+        case SoilChar::VAN_GENUCHTEN:
+            {
+                const double n = std::max(p.vg_n, 1.0 + 1.0e-6);
+                const double m = 1.0 - 1.0 / n;
+                const double ap = std::pow(p.alpha * psi, n);
+                return clampSe(std::pow(1.0 + ap, -m));
+            }
+    }
+    return 1.0;
+}
+
+double waterContent(const Params& p, double psi) noexcept {
+    return p.theta_r + effectiveSaturation(p, psi) * (p.theta_s - p.theta_r);
+}
+
+double relativeConductivity(const Params& p, double psi) noexcept {
+    if (!(psi > kPsiEps)) return 1.0;
+    switch (p.law) {
+        case SoilChar::GARDNER:
+            return std::clamp(std::exp(-p.alpha * psi), 0.0, 1.0);
+        case SoilChar::RUSSO:
+            {
+                // Kr = [ (1 + ½αψ)·e^(−½αψ) ]² — Russo's own form, which is
+                // exactly the Mualem integral of his retention curve. This is
+                // why he costs the same as Gardner: one exp, no quadrature.
+                const double a = 0.5 * p.alpha * psi;
+                const double t = (1.0 + a) * std::exp(-a);
+                return std::clamp(t * t, 0.0, 1.0);
+            }
+        case SoilChar::BROOKS_COREY:
+            {
+                const double pb = std::max(p.psi_b, kPsiEps);
+                if (psi <= pb) return 1.0;
+                const double e = 2.0 + 3.0 * p.lambda;
+                return std::clamp(std::pow(pb / psi, e), 0.0, 1.0);
+            }
+        case SoilChar::VAN_GENUCHTEN:
+            {
+                const double n = std::max(p.vg_n, 1.0 + 1.0e-6);
+                const double m = 1.0 - 1.0 / n;
+                const double se = clampSe(effectiveSaturation(p, psi));
+                const double inner = 1.0 - std::pow(1.0 - std::pow(se, 1.0 / m), m);
+                return std::clamp(std::pow(se, p.vg_L) * inner * inner, 0.0, 1.0);
+            }
+    }
+    return 1.0;
+}
+
+double conductivity(const Params& p, double psi) noexcept {
+    return p.Ks * relativeConductivity(p, psi);
+}
+
+double suctionAtSaturation(const Params& p, double Se) noexcept {
+    const double se = clampSe(Se);
+    if (se >= 1.0 - 1.0e-12) return 0.0;
+    switch (p.law) {
+        case SoilChar::GARDNER:
+            return -std::log(se) / std::max(p.alpha, kPsiEps);
+        case SoilChar::RUSSO:
+            {
+                // (1 + a)·e^(−a) = se^((2+L)/2) has no elementary inverse;
+                // three Newton steps from the Gardner guess converge to
+                // machine precision over the whole range (the function is
+                // smooth and monotone in a).
+                const double target =
+                    std::pow(se, (2.0 + p.vg_L) * 0.5);
+                double a = std::max(-std::log(std::max(target, kSeMin)), 0.0);
+                for (int it = 0; it < 6; ++it) {
+                    const double f  = (1.0 + a) * std::exp(-a) - target;
+                    const double df = -a * std::exp(-a);     // d/da
+                    if (std::fabs(df) < 1.0e-300) break;
+                    const double step = f / df;
+                    a -= step;
+                    if (a < 0.0) a = 0.0;
+                    if (std::fabs(step) < 1.0e-13) break;
+                }
+                return 2.0 * a / std::max(p.alpha, kPsiEps);
+            }
+        case SoilChar::BROOKS_COREY:
+            return std::max(p.psi_b, kPsiEps) *
+                   std::pow(se, -1.0 / std::max(p.lambda, 1.0e-6));
+        case SoilChar::VAN_GENUCHTEN:
+            {
+                const double n = std::max(p.vg_n, 1.0 + 1.0e-6);
+                const double m = 1.0 - 1.0 / n;
+                const double t = std::pow(se, -1.0 / m) - 1.0;
+                return std::pow(std::max(t, 0.0), 1.0 / n) /
+                       std::max(p.alpha, kPsiEps);
+            }
+    }
+    return 0.0;
+}
+
+double diffusivity(const Params& p, double psi) noexcept {
+    // D(θ) = K(ψ)·dψ/dθ. dθ/dψ = (θ_s − θ_r)·dSe/dψ, evaluated by a centred
+    // difference in ψ — the analytic derivatives differ per law and per
+    // branch, and the column's diffusive term is optional and small (D-N3
+    // defaults it OFF), so a second-order difference is the right cost.
+    const double dpsi = std::max(1.0e-4, 1.0e-3 * std::fabs(psi));
+    const double se_hi = effectiveSaturation(p, psi + dpsi);
+    const double se_lo = effectiveSaturation(p, std::max(psi - dpsi, 0.0));
+    const double dse   = (se_hi - se_lo) / (psi + dpsi - std::max(psi - dpsi, 0.0));
+    const double dtheta_dpsi = dse * (p.theta_s - p.theta_r);
+    if (std::fabs(dtheta_dpsi) < 1.0e-12) return 0.0;
+    return conductivity(p, psi) / std::fabs(dtheta_dpsi);
+}
+
+// ---------------------------------------------------------------------------
+// Equilibrium storage and recharge
+// ---------------------------------------------------------------------------
+
+/// `∫₀ᴸ Se(ψ) dψ` — the SATURATION integral. Internal, because it is the
+/// scale eq. 22 is written on, not a quantity anyone outside this file should
+/// hold. `equilibriumStorage` converts it to metres of water, which is what
+/// every other `hu` in the engine means.
+static double saturationIntegral(const Params& p, double Lc) noexcept {
+    switch (p.law) {
+        case SoilChar::GARDNER:
+            // ∫₀ᴸ e^(−αψ) dψ = (1 − e^(−αL))/α — exactly eq. 39's hᵤ*.
+            return (1.0 - std::exp(-p.alpha * Lc)) / std::max(p.alpha, kPsiEps);
+        case SoilChar::BROOKS_COREY: {
+            // ∫₀ᴸ Se dψ = ψ_b + ∫_{ψ_b}^{L} (ψ_b/ψ)^λ dψ  (L > ψ_b)
+            const double pb = std::max(p.psi_b, kPsiEps);
+            if (Lc <= pb) return Lc;
+            const double lam = std::max(p.lambda, 1.0e-6);
+            if (std::fabs(lam - 1.0) < 1.0e-9)
+                return pb + pb * std::log(Lc / pb);
+            return pb + pb * (std::pow(Lc / pb, 1.0 - lam) - 1.0) / (1.0 - lam);
+        }
+        case SoilChar::RUSSO:
+        case SoilChar::VAN_GENUCHTEN:
+        default: {
+            double acc = 0.0;   // 4-point Gauss-Legendre on [0, L]
+            for (int g = 0; g < 4; ++g)
+                acc += kGlW[g] * effectiveSaturation(p, kGlX[g] * Lc);
+            return acc * Lc;
+        }
+    }
+}
+
+double equilibriumStorage(const Params& p, double L) noexcept {
+    // METRES OF WATER: `∫₀ᴸ θ(ψ) dψ = θ_r·L + (θ_s − θ_r)·∫₀ᴸ Se dψ`.
+    //
+    // This used to return the saturation integral, because that is the scale
+    // Qu & Duffy's eq. 22 measures `hᵤ` on. It made eq. 22 read beautifully
+    // and every other line of the engine wrong: `SubsurfaceState::storage()`
+    // adds `hu` to `h_g·θ_s`, the closure-A cap is `θ_s·L`, and the ENSLAVED
+    // reduction needs `d(hᵤ*)/dL = θ(L)` — all three are water depths. The
+    // seeded column came out ABOVE saturation, the cap fired on step 0, and
+    // the closure then drained a cell dry and kept going.
+    //
+    // So the public quantity is water, and eq. 22 converts on entry. Gates
+    // 1, 2 and 4 are what this note is for.
+    const double Lc = std::max(L, kLMin);
+    return p.theta_r * Lc +
+           (p.theta_s - p.theta_r) * saturationIntegral(p, Lc);
+}
+
+double enslavedStorage(const Params& p, double L) noexcept {
+    return equilibriumStorage(p, L);
+}
+
+double rechargeQ0(const Params& p, double L, double hu) noexcept {
+    const double Lc = std::max(L, kLMin);
+
+    // `hu` arrives as metres of WATER. Eq. 22 is written on the saturation
+    // scale, so convert once, here, at the only place that needs it.
+    const double span = std::max(p.theta_s - p.theta_r, 1.0e-12);
+    const double hu_se = (hu - p.theta_r * Lc) / span;
+
+    if (p.law == SoilChar::GARDNER) {
+        // Eq. 22, verbatim. Written in the published form (not the factored
+        // one) so a reader can compare it to the paper line for line; the
+        // header records that the two are the same expression.
+        const double e = std::exp(-p.alpha * Lc);
+        const double den = p.alpha * Lc * (1.0 - e);
+        if (!(std::fabs(den) > 1.0e-300)) return 0.0;
+        const double q = p.Ks * (1.0 - e - p.alpha * hu_se) / den;
+        return std::isfinite(q) ? q : 0.0;
+    }
+
+    // The generalised relaxation form (see the header's @warning — the rate
+    // below is ours, the equilibrium is the law's):
+    //     q₀ = C(L)·[hᵤ*(L) − hᵤ],   C(L) = K̄ / (L · hᵤ*(L)/L)  →  K̄/hᵤ*
+    // where K̄ is the conductivity at the column's mean suction. Reducing to
+    // Gardner: K̄ → Ks·e^(−αL/2) and hᵤ* → (1−e^(−αL))/α gives the same order
+    // and the same limits, which is the consistency this rests on.
+    // Relaxation on the SATURATION scale, so the rate constant means the
+    // same thing it does for Gardner, then reported as a water flux.
+    const double hu_eq_se = saturationIntegral(p, Lc);
+    if (!(hu_eq_se > 1.0e-12)) return 0.0;
+    const double Kbar = conductivity(p, 0.5 * Lc);
+    const double C = Kbar / hu_eq_se;
+    const double q = C * (hu_eq_se - hu_se);
+    return std::isfinite(q) ? q : 0.0;
+}
+
+double alphaL(const Params& p, double L) noexcept {
+    const double Lc = std::max(L, kLMin);
+    switch (p.law) {
+        case SoilChar::BROOKS_COREY:
+            // 1/ψ_b is Brooks–Corey's inverse length, so αL means the same
+            // "column thickness in capillary lengths" across every law and
+            // the §2.4 thresholds keep one interpretation.
+            return Lc / std::max(p.psi_b, kPsiEps);
+        default:
+            return p.alpha * Lc;
+    }
+}
+
+double feddesStress(double psi, double psi_w) noexcept {
+    // Smooth (C¹) ramp from full transpiration to zero at the wilting point.
+    // Deliberately NOT the legacy `if (infil <= 0)` gate, and deliberately
+    // not a hard piecewise linear: a kink here shows up as a kink in the ET
+    // ledger that reads like a solver artefact.
+    const double pw = std::max(psi_w, 1.0e-6);
+    if (psi <= 0.0) return 1.0;
+    if (psi >= pw)  return 0.0;
+    const double x = psi / pw;                 // 0 wet → 1 wilting
+    const double s = 1.0 - x;                  // 1 wet → 0 wilting
+    return s * s * (3.0 - 2.0 * s);            // smoothstep
+}
+
+}  // namespace openswmm::twoD::soil
diff --git a/src/engine/2d/subsurface/SoilCharacteristic.hpp b/src/engine/2d/subsurface/SoilCharacteristic.hpp
new file mode 100644
index 000000000..43da31dfa
--- /dev/null
+++ b/src/engine/2d/subsurface/SoilCharacteristic.hpp
@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SoilCharacteristic.hpp
+ * @brief G-steps 2 and 13 — the four production soil-characteristic laws and
+ *        the closure-A quasi-steady recharge `q₀(hᵤ, h_g)`.
+ *
+ * @section soilchar_forms The laws
+ *
+ * Each law supplies effective saturation `Se(ψ)`, water content `θ(ψ)` and
+ * relative conductivity `Kr(ψ)`, with suction head `ψ ≥ 0` measured upward
+ * from the water table (so `ψ = 0` at the table and `ψ = L` at the surface):
+ *
+ * | Law | `Kr(ψ)` |
+ * |---|---|
+ * | Gardner (1958)       | `e^(−αψ)` |
+ * | Russo (1988)         | `[(1 + ½αψ)·e^(−½αψ)]²` |
+ * | Brooks–Corey (1964)  | `1` for `ψ ≤ ψ_b`, else `(ψ_b/ψ)^(2+3λ)` |
+ * | van Genuchten (1980) | `Se^L·[1 − (1 − Se^(1/m))^m]²`, `Se = [1+(αψ)^n]^(−m)` |
+ *
+ * @section soilchar_q0 How q₀ is computed — read this before trusting a number
+ *
+ * For **Gardner**, Qu & Duffy's eq. 22 is used verbatim:
+ *
+ * ```
+ * q₀ = Ks · [ 1 − e^(−αL) − α·hᵤ ] / [ αL · (1 − e^(−αL)) ] ,   L = z_s − h_g
+ * ```
+ *
+ * That expression is algebraically identical to
+ *
+ * ```
+ * q₀ = C(L) · [ hᵤ*(L) − hᵤ ] ,
+ *      hᵤ*(L) = (1 − e^(−αL)) / α          <- exactly eq. 39, the enslaved form
+ *      C(L)   = Ks / ( L · (1 − e^(−αL)) )
+ * ```
+ *
+ * — a relaxation of the column's stored water toward its hydrostatic
+ * equilibrium, at a conductivity-set rate. The equivalence is a genuine
+ * identity, not an approximation, and it is worth stating because it makes
+ * the sign convention obvious (`hᵤ < hᵤ*` ⇒ `q₀ > 0`, downward recharge;
+ * `hᵤ > hᵤ*` ⇒ capillary rise) and because it is the form that generalises.
+ *
+ * **The other three laws use that generalised form**, with `hᵤ*(L)` the
+ * hydrostatic-equilibrium storage `∫₀ᴸ θ(ψ) dψ` of *that* law (closed form
+ * for Brooks–Corey, Gauss–Legendre for van Genuchten and Russo) and `C(L)`
+ * the same conductivity/length scale evaluated with the law's own `Kr`.
+ *
+ * @warning **This generalisation is ours, not the literature's.** Gardner
+ *          reproduces the published closed form exactly and is verified
+ *          against it. Russo, Brooks–Corey and van Genuchten reproduce the
+ *          correct *equilibrium* (`q₀ = 0` at hydrostatic storage) and the
+ *          correct sign, but their *relaxation rate* is a modelling choice
+ *          this file makes explicit rather than a published closed form.
+ *          Plan step 18's closure-ladder benchmark and step 4's HYDRUS-1D
+ *          comparison are what license them; until those run, prefer Gardner
+ *          or Russo for anything quantitative, and prefer closure B (the σ
+ *          column, which integrates the real Richards flux and needs none of
+ *          this) where the answer matters. Recorded for the migration guide.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SOIL_CHARACTERISTIC_HPP
+#define OPENSWMM_ENGINE_2D_SOIL_CHARACTERISTIC_HPP
+
+#include "SubsurfaceData.hpp"
+
+namespace openswmm::twoD::soil {
+
+/// The parameters one cell's law needs, gathered so the kernels take one
+/// argument and the SoA gather happens once per firing.
+struct Params {
+    SoilChar law     = SoilChar::RUSSO;
+    double   Ks      = 1.0e-5;
+    double   theta_s = 0.45;
+    double   theta_r = 0.10;
+    double   alpha   = 2.0;
+    double   psi_b   = 0.20;
+    double   lambda  = 0.40;
+    double   vg_n    = 1.6;
+    double   vg_L    = 0.5;
+};
+
+/// Effective saturation at suction head @p psi (m, ≥ 0). `Se ∈ (0, 1]`.
+double effectiveSaturation(const Params& p, double psi) noexcept;
+
+/// Water content θ(ψ) = θ_r + Se·(θ_s − θ_r).
+double waterContent(const Params& p, double psi) noexcept;
+
+/// Relative conductivity `Kr(ψ) ∈ (0, 1]`.
+double relativeConductivity(const Params& p, double psi) noexcept;
+
+/// Unsaturated conductivity `K(ψ) = Ks·Kr(ψ)` (m/s).
+double conductivity(const Params& p, double psi) noexcept;
+
+/// Suction head at a given effective saturation — the retention inverse,
+/// needed to give the σ column a ψ from its θ. Returns 0 at `Se ≥ 1`.
+double suctionAtSaturation(const Params& p, double Se) noexcept;
+
+/// Soil-moisture diffusivity `D(θ) = K(ψ)·dψ/dθ` (m²/s) at suction @p psi.
+/// Zero when the capillary term is off; evaluated by the analytic
+/// `dSe/dψ` of each law.
+double diffusivity(const Params& p, double psi) noexcept;
+
+/// Hydrostatic-equilibrium storage of a column of thickness @p L (m of
+/// water): `∫₀ᴸ θ(ψ) dψ`. Gardner and Brooks–Corey are closed form; Russo
+/// and van Genuchten use fixed-order Gauss–Legendre.
+double equilibriumStorage(const Params& p, double L) noexcept;
+
+/// Closure-A quasi-steady recharge (m/s). `+` down, `−` capillary rise.
+/// @param L  unsaturated column thickness `z_s − h_g` (m)
+/// @param hu bulk unsaturated storage as an equivalent water depth (m)
+/// For Gardner this IS eq. 22; see the file header for the other three.
+double rechargeQ0(const Params& p, double L, double hu) noexcept;
+
+/// The ENSLAVED reduction: `hᵤ` algebraic in `h_g` — the storage at which
+/// `rechargeQ0` vanishes. For Gardner this is eq. 39.
+double enslavedStorage(const Params& p, double L) noexcept;
+
+/// `αL`, the dimensionless group the AUTO closure selection reads. For
+/// Brooks–Corey and van Genuchten the law's own inverse length replaces α
+/// (`1/ψ_b`, and the van Genuchten `α`), so the thresholds mean the same
+/// thing across laws.
+double alphaL(const Params& p, double L) noexcept;
+
+/// Feddes-style smooth stress multiplier on potential ET, from the column's
+/// mean suction. 1 in the readily-available range, falling smoothly to 0 at
+/// the wilting point — no `if (infil <= 0)` gate, which is the behaviour §7
+/// retires. @p psi_w wilting suction (m).
+double feddesStress(double psi, double psi_w) noexcept;
+
+}  // namespace openswmm::twoD::soil
+
+#endif  // OPENSWMM_ENGINE_2D_SOIL_CHARACTERISTIC_HPP
diff --git a/src/engine/2d/subsurface/SubsurfaceData.cpp b/src/engine/2d/subsurface/SubsurfaceData.cpp
new file mode 100644
index 000000000..b364e0591
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceData.cpp
@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceData.cpp
+ * @brief Sizing, storage accounting and token round-trip for the two-zone
+ *        groundwater state (G-step 1).
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SubsurfaceData.hpp"
+
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+void SubsurfaceState::resize(int n, int m) {
+    n_cells  = n < 0 ? 0 : n;
+    m_layers = m < 1 ? 1 : m;
+    const auto nn = static_cast(n_cells);
+
+    Ks.assign(nn, 1.0e-5);
+    zs.assign(nn, 5.0);
+    theta_s.assign(nn, 0.45);
+    theta_r.assign(nn, 0.10);
+    alpha.assign(nn, 2.0);
+    psi_b.assign(nn, 0.20);
+    lambda.assign(nn, 0.40);
+    vg_n.assign(nn, 1.6);
+    vg_L.assign(nn, 0.5);
+    c_loss.assign(nn, 0.0);
+    soil_char.assign(nn, static_cast(SoilChar::RUSSO));
+    closure.assign(nn, static_cast(GwClosure::CLOSED_FORM));
+    area.assign(nn, 0.0);
+    z_bed.assign(nn, 0.0);
+
+    hg.assign(nn, 0.0);
+    hu.assign(nn, 0.0);
+    theta_sigma.assign(nn * static_cast(m_layers), 0.0);
+
+    q0_last.assign(nn, 0.0);
+    qnode_last.assign(nn, 0.0);
+    qlat_last.assign(nn, 0.0);
+    qdeep_last.assign(nn, 0.0);
+    qet_last.assign(nn, 0.0);
+    dunne_last.assign(nn, 0.0);
+    qplus_last.assign(nn, 0.0);
+    qlink_last.assign(nn, 0.0);   // G-X3
+
+    dt_cell.assign(nn, 0.0);
+    tier.assign(nn, 0);
+    xacc_from_surface.assign(nn, 0.0);
+    xacc_to_surface.assign(nn, 0.0);
+    lacc.assign(nn, 0.0);         // G-X3
+    // eacc_L/R and nacc are sized by the solver against the edge and node
+    // counts, which this struct deliberately does not know.
+}
+
+double SubsurfaceState::storage() const noexcept {
+    // Saturated: h_g·θ_s·A (drainable + retained; the aquifer is full below
+    // the table). Unsaturated: closure A carries `hu` as an equivalent depth
+    // directly; closure B integrates the σ layers, which is Σ w_j = Σ θ_j·L·Δσ.
+    double s = 0.0;
+    const double dsig = 1.0 / static_cast(m_layers <= 0 ? 1 : m_layers);
+    for (int i = 0; i < n_cells; ++i) {
+        const auto u = static_cast(i);
+        double col = 0.0;
+        if (closure[u] == static_cast(GwClosure::SIGMA)) {
+            const double L = zs[u] - hg[u];
+            const double Ldsig = (L > 0.0 ? L : 0.0) * dsig;
+            for (int j = 0; j < m_layers; ++j) {
+                col += theta_sigma[static_cast(j) *
+                                       static_cast(n_cells) + u] *
+                       Ldsig;
+            }
+        } else {
+            col = hu[u];
+        }
+        s += (hg[u] * theta_s[u] + col) * area[u];
+    }
+    return s;
+}
+
+// G-O: the three storage views the C API, the results file and the report share.
+double SubsurfaceState::liveStorage() const noexcept {
+    double s = storage();
+    for (double v : eacc_L) s += v;
+    for (double v : eacc_R) s += v;
+    for (double v : xacc_from_surface) s += v;
+    for (double v : xacc_to_surface)   s += v;
+    for (double v : lacc)              s += v;   // G-X3: seepage in flight
+    return s;
+}
+
+double SubsurfaceState::ledgeredStorage() const noexcept {
+    double s = storage();
+    for (double v : eacc_L) s += v;
+    for (double v : eacc_R) s += v;
+    return s;
+}
+
+double SubsurfaceState::continuityResidual() const noexcept {
+    const double in  = led_infil_in + led_lateral + led_link;   // G-X3
+    const double out = led_deep + led_node + led_et + led_dunne;
+    return ledgeredStorage() - led_init_storage - (in - out);
+}
+
+namespace {
+
+std::string upperTrim(const std::string& t) {
+    std::string s;
+    s.reserve(t.size());
+    for (char c : t) {
+        if (!std::isspace(static_cast(c))) {
+            s.push_back(static_cast(
+                std::toupper(static_cast(c))));
+        }
+    }
+    return s;
+}
+
+}  // namespace
+
+const char* soilCharToken(SoilChar s) noexcept {
+    switch (s) {
+        case SoilChar::RUSSO:         return "RUSSO";
+        case SoilChar::GARDNER:       return "GARDNER";
+        case SoilChar::BROOKS_COREY:  return "BROOKS_COREY";
+        case SoilChar::VAN_GENUCHTEN: return "VAN_GENUCHTEN";
+    }
+    return "RUSSO";
+}
+
+bool parseSoilChar(const std::string& t, SoilChar& s) noexcept {
+    const std::string u = upperTrim(t);
+    if (u == "RUSSO")                                    { s = SoilChar::RUSSO;         return true; }
+    if (u == "GARDNER")                                  { s = SoilChar::GARDNER;       return true; }
+    if (u == "BROOKS_COREY" || u == "BROOKSCOREY" ||
+        u == "BROOKS-COREY" || u == "BC")                { s = SoilChar::BROOKS_COREY;  return true; }
+    if (u == "VAN_GENUCHTEN" || u == "VANGENUCHTEN" ||
+        u == "VAN-GENUCHTEN" || u == "VG")               { s = SoilChar::VAN_GENUCHTEN; return true; }
+    return false;
+}
+
+const char* gwClosureToken(GwClosure c) noexcept {
+    switch (c) {
+        case GwClosure::AUTO:        return "AUTO";
+        case GwClosure::CLOSED_FORM: return "CLOSED_FORM";
+        case GwClosure::ENSLAVED:    return "ENSLAVED";
+        case GwClosure::SIGMA:       return "SIGMA";
+    }
+    return "AUTO";
+}
+
+bool parseGwClosure(const std::string& t, GwClosure& c) noexcept {
+    const std::string u = upperTrim(t);
+    if (u == "AUTO")                              { c = GwClosure::AUTO;        return true; }
+    if (u == "CLOSED_FORM" || u == "CLOSEDFORM" ||
+        u == "CLOSED-FORM" || u == "A")           { c = GwClosure::CLOSED_FORM; return true; }
+    if (u == "ENSLAVED")                          { c = GwClosure::ENSLAVED;    return true; }
+    if (u == "SIGMA" || u == "COLUMN" || u == "B"){ c = GwClosure::SIGMA;       return true; }
+    return false;
+}
+
+}  // namespace openswmm::twoD
diff --git a/src/engine/2d/subsurface/SubsurfaceData.hpp b/src/engine/2d/subsurface/SubsurfaceData.hpp
new file mode 100644
index 000000000..86f6da13f
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceData.hpp
@@ -0,0 +1,326 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceData.hpp
+ * @brief G-step 1 — state, parameters and options for the two-zone
+ *        groundwater kernel (TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN §4).
+ *
+ * @details Two zones per mesh cell, glued at a moving water table:
+ *
+ *          - **Saturated:** one state `hg` (m of saturated thickness above the
+ *            aquifer bottom), updated by an explicit FV balance of recharge,
+ *            lateral Darcy across the cell's edges, deep loss and node
+ *            exchange (§2.1).
+ *          - **Unsaturated:** either closure A — one bulk state `hu` (m of
+ *            water stored as an equivalent depth) driven by a closed-form
+ *            quasi-steady recharge — or closure B, an explicit σ-coordinate
+ *            column of `m` layers whose bottom flux IS the recharge (§2.3).
+ *
+ *          **Everything here is SI.** The 2D module runs in metres and
+ *          seconds throughout; the 1D engine's feet never reach this code.
+ *          `[2D_AQUIFER]` rows are authored in the project's own units and
+ *          converted once, at parse.
+ *
+ *          **Cell-generic.** A cell is a triangle or a quad; nothing here
+ *          divides by 3 or indexes a fixed edge count. Lateral edges come
+ *          from the mesh's own per-cell slot range.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SUBSURFACE_DATA_HPP
+#define OPENSWMM_ENGINE_2D_SUBSURFACE_DATA_HPP
+
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+/// Soil-characteristic law: how `K(ψ)` and `θ(ψ)` are shaped.
+/// (Draft plan §2.5. Broadbridge–White is verification-only and is not a
+/// production selection — it lives in the test harness, not here.)
+enum class SoilChar : int8_t {
+    RUSSO         = 0,  ///< default; Mualem-consistent, same α slot as Gardner
+    GARDNER       = 1,  ///< K = Ks·e^(αψ); the closed form of eq. 22
+    BROOKS_COREY  = 2,  ///< piecewise about the air-entry pressure
+    VAN_GENUCHTEN = 3   ///< Rosetta/UNSODA parameter databases
+};
+
+/// Unsaturated-zone closure, resolved per cell from AUTO at initialize.
+enum class GwClosure : int8_t {
+    AUTO        = -1, ///< select from αL at initialize (never stored per cell)
+    CLOSED_FORM = 0,  ///< closure A: bulk `hu` + quasi-steady recharge
+    ENSLAVED    = 1,  ///< closure A reduced: `hu` algebraic in `hg` (eq. 39)
+    SIGMA       = 2   ///< closure B: explicit σ column of `m` layers
+};
+
+/// Node ↔ aquifer exchange configuration for one coupled node.
+/// Absent bed layer ⇒ direct Darcy (MODFLOW-River config a).
+struct GwNodeBed {
+    int    node = -1;   ///< 1D node index
+    int    cell = -1;   ///< containing mesh cell, resolved at initialize
+    double Kc   = 0.0;  ///< semi-confining bed conductivity (m/s); 0 = direct
+    double dC   = 0.0;  ///< bed thickness (m)
+    double area = 0.0;  ///< exchange area (m²); 0 ⇒ derived from the cell area
+    /// G-X2 (2026-09-19): `CELL AUTO` (or an auto-enrolled node) — the cell
+    /// is the one the node's [COORDINATES] fall in, located at resolve.
+    bool   locate    = false;
+    /// G-X2: `EXCHANGE NO` — the row exists to opt the node OUT of the
+    /// channel (auto-enrolment would otherwise give it a bed); the bed is
+    /// dropped at resolve and the node exchanges with nothing.
+    bool   exchange  = true;
+    /// G-X2: enrolled by location, not authored — the writer does not echo
+    /// it (`NODE_ENROLMENT AUTO` recreates it).
+    bool   automatic = false;
+};
+
+/// G-X4 (2026-09-20): `LINK_SEEPAGE` mode. AUTO is G-X3's one-way delivery
+/// (the conduit's existing `[LOSSES]` seepage volume is routed to the cells
+/// it crosses); TWO_WAY replaces the legacy loss law with the signed
+/// MODFLOW-River conductance, so a conduit below the water table GAINS.
+enum class GwLinkMode : int8_t { NONE = 0, AUTO = 1, TWO_WAY = 2 };
+
+/// G-X4: one authored `[2D_AQUIFER_LINKS]` row — the per-conduit override of
+/// the signed exchange. `link` is a NAME until `resolveLinkSeepage` maps it.
+struct GwLinkRow {
+    int    link = -1;
+    double Kc   = 0.0;   ///< bed conductivity, [LOSSES]-seepage units; 0 ⇒ the conduit's own seep rate
+    double dC   = 0.0;   ///< bed thickness (project length); 0 ⇒ the conduit's full depth
+    bool   exchange = true;   ///< EXCHANGE NO — this conduit stays a legacy loss
+};
+
+/// G-X3 (2026-09-19): one conduit's share of one mesh cell — the fraction
+/// of the conduit's polyline length ([COORDINATES] + [VERTICES]) that lies
+/// in the cell. The router books `weight × (the conduit's seepage volume
+/// this routing step)` into the cell; a conduit's shares sum to ≤ 1 (the
+/// part of its length outside the mesh seeps to nowhere, as before).
+struct GwLinkShare {
+    int    link   = -1;   ///< 1D link index (a conduit)
+    int    cell   = -1;   ///< mesh cell
+    double weight = 0.0;  ///< length fraction in (0, 1]
+};
+
+/// `[2D_AQUIFER_OPTIONS]`. Defaults are the plan's starred values.
+struct GwOptions {
+    SoilChar  soil_char = SoilChar::RUSSO;
+    GwClosure closure   = GwClosure::AUTO;
+    int       m_layers  = 8;      ///< σ layers under closure B (global default)
+    bool      capillary_diff = false;  ///< closure B optional diffusive term (D-N3: OFF)
+    double    c_gw   = 0.5;       ///< saturated stability safety factor
+    double    c_col  = 0.9;       ///< column stability safety factor
+    bool      force_closed_form = false;  ///< suppress the αL ≥ 5 auto-override
+    /// `MODE PER_SUBCATCH` — one degenerate cell per subcatchment, no mesh
+    /// sections, lateral flux zero, node exchange to the outlet node. This is
+    /// G1's vehicle and shares the whole code path (§8).
+    bool      per_subcatch = false;
+    /// Dunne saturation-excess transfer to the surface twin. Default ON —
+    /// it IS the mass balance (G0 sign-off, draft decision 9); the flag
+    /// exists for compatibility comparisons, not as a modelling choice.
+    bool      dunne = true;
+    /// GW_ET: NONE | CAPILLARY_RISE | BOUNDARY_ET | BOTH.
+    std::string gw_et = "NONE";
+    /// G-X2: `NODE_ENROLMENT AUTO | ROWS`. AUTO (default, program plan
+    /// §B.4b): every node whose [COORDINATES] fall in a mesh cell gets a bed
+    /// (direct Darcy, the cell's area) unless a `[2D_AQUIFER_NODE]` row
+    /// names it — rows override, `EXCHANGE NO` opts out. ROWS: only the
+    /// authored rows exchange (the pre-G-X2 behaviour).
+    bool      node_auto = true;
+    /// G-X3/G-X4: `LINK_SEEPAGE AUTO | NONE | TWO_WAY`. AUTO (default,
+    /// program plan §B.4b): every conduit with a [LOSSES] seepage rate whose
+    /// polyline crosses the mesh delivers its seepage volume into the cells
+    /// it crosses, length-weighted (one-way; the 1D still books the loss).
+    /// NONE: seepage is a system loss, as before. TWO_WAY (G-X4): the signed
+    /// conductance law replaces the fixed loss, and a conduit under the
+    /// water table gains.
+    GwLinkMode link_seepage = GwLinkMode::AUTO;
+    /// True once any [2D_AQUIFER*] row was authored.
+    bool      authored = false;
+};
+
+/// One authored `[2D_AQUIFER]` row, before resolution onto cells.
+/// Scope `*` / `TAG ` / `CELL `, resolved `* < TAG < CELL` by order.
+struct GwAquiferRow {
+    int         scope = 0;      ///< 0 GLOBAL, 1 TAG, 2 CELL (mirrors GwScope)
+    std::string tag;
+    int         cell = -1;      ///< 0-based
+
+    double Ks      = 1.0e-5;    ///< saturated hydraulic conductivity (m/s)
+    double zs      = 5.0;       ///< soil column thickness, bottom→surface (m)
+    double theta_s = 0.45;      ///< porosity / saturated water content
+    double theta_r = 0.10;      ///< residual water content
+    double alpha   = 2.0;       ///< Gardner/Russo sorptive number (1/m)
+    /// Brooks–Corey: `psi_b` air-entry head (m, positive) and `lambda` shape.
+    double psi_b   = 0.20;
+    double lambda  = 0.40;
+    /// van Genuchten: `n` (m = 1 − 1/n) and the Mualem exponent `L`.
+    double vg_n    = 1.6;
+    double vg_L    = 0.5;
+    /// Deep-loss coefficient (m/s at full saturation): q⁻ = c_loss·hg/zs.
+    double c_loss  = 0.0;
+    /// Initial saturated thickness (m). < 0 ⇒ the option default seeds it.
+    double hg0     = -1.0;
+
+    SoilChar  soil_char = SoilChar::RUSSO;
+    GwClosure closure   = GwClosure::AUTO;
+    int       m_layers  = -1;   ///< < 0 ⇒ the global M_LAYERS
+    bool      soil_char_set = false, closure_set = false;
+};
+
+/**
+ * @brief Per-cell resolved parameters and state (SoA).
+ *
+ * @details Sized to the mesh cell count at initialize. Under
+ *          `MODE PER_SUBCATCH` the "mesh" is one degenerate cell per
+ *          subcatchment and every lateral term is absent — the identical
+ *          code path, which is what makes G1 and G2 the same kernel.
+ */
+struct SubsurfaceState {
+    int n_cells = 0;
+    int m_layers = 0;            ///< σ layers per closure-B column (fixed)
+
+    // ---- resolved parameters (per cell) ---------------------------------
+    std::vector  Ks, zs, theta_s, theta_r, alpha;
+    std::vector  psi_b, lambda, vg_n, vg_L, c_loss;
+    std::vector  soil_char;   ///< SoilChar
+    std::vector  closure;     ///< GwClosure, AUTO already resolved
+    std::vector  area;        ///< cell planimetric area (m²)
+    std::vector  z_bed;       ///< aquifer bottom elevation (m) = cell z − zs
+
+    // ---- state ----------------------------------------------------------
+    std::vector  hg;          ///< saturated thickness (m)
+    std::vector  hu;          ///< closure A: bulk unsat storage (m of water)
+    /// Closure B: layer water content θ, `[layer * n_cells + cell]` — layer-major
+    /// so a fixed-layer sweep walks contiguous cells and vectorizes ACROSS
+    /// columns (the σ pivot's key win over the draft's per-cell MOC column).
+    std::vector  theta_sigma;
+
+    // ---- per-firing diagnostics + transport donors ------------------------
+    std::vector  q0_last;     ///< recharge (m/s), + down, − capillary rise
+    std::vector  qnode_last;  ///< node exchange (m³/s), + into the pipe
+    std::vector  qlat_last;   ///< net lateral Darcy into the cell (m³/s)
+    std::vector  qdeep_last;  ///< deep loss (m/s)
+    std::vector  qet_last;    ///< subsurface ET (m/s, ≥ 0 out)
+    std::vector  dunne_last;  ///< saturation-excess to the surface (m³/s)
+    std::vector  qplus_last;  ///< infiltration delivered in (m/s)
+    std::vector  qlink_last;  ///< G-X3: conduit seepage delivered in (m³/s)
+
+    // ---- LTS ------------------------------------------------------------
+    std::vector  dt_cell;     ///< min(Δt_g, Δt_u) per cell (s)
+    std::vector tier;        ///< assigned tier
+    /// Lateral Darcy side accumulators, one pair per unique GW edge — the
+    /// same ±ΔV strategy as the surface `facc_L_/facc_R_`, which is what
+    /// makes cross-tier conservation a property inherited rather than
+    /// re-proved (G-B).
+    std::vector  eacc_L, eacc_R;
+    /// Cross-domain accumulator: volume (m³) the SURFACE booked for this GW
+    /// cell at the surface's finer cadence, gathered at the GW firing.
+    std::vector  xacc_from_surface;
+    /// …and the reverse: volume the GW cell owes the surface twin (Dunne,
+    /// exfiltration), gathered by the surface cell.
+    std::vector  xacc_to_surface;
+    /// Node-exchange accumulator, per coupled node (m³), booked at tier-0
+    /// node-head sampling and gathered at the GW cell's firing.
+    std::vector  nacc;
+    /// G-X3: conduit-seepage accumulator per cell (m³, + into the aquifer),
+    /// booked by the router at the ROUTING cadence from the conduits' seepage
+    /// rates and gathered at the GW cell's firing — the `xacc_from_surface`
+    /// pattern, one phase behind `led_link` for the same reason.
+    std::vector  lacc;
+
+    // ---- ledger (m³, cumulative) ----------------------------------------
+    double led_recharge = 0.0;   ///< unsat → sat (negative = capillary rise)
+    double led_lateral  = 0.0;   ///< net lateral Darcy across the domain edge
+    double led_deep     = 0.0;   ///< deep percolation out
+    double led_node     = 0.0;   ///< node exchange, + out of the aquifer
+    double led_dunne    = 0.0;   ///< saturation excess to the surface
+    double led_caprise  = 0.0;   ///< capillary rise (the negative recharge share)
+    double led_et       = 0.0;   ///< subsurface ET out
+    double led_infil_in = 0.0;   ///< q⁺ delivered from the surface
+    double led_link     = 0.0;   ///< G-X3: conduit seepage delivered in
+    double led_init_storage  = 0.0;
+    double led_final_storage = 0.0;
+
+    bool active = false;         ///< the kernel ran this simulation
+
+    void resize(int n, int m);
+    /// Total water in both zones (m³) — the continuity check's storage term.
+    double storage() const noexcept;
+    /// G-O: everything the aquifer HOLDS now, including water parked in a
+    /// side accumulator (in flight between cells, received from the surface
+    /// and not yet absorbed, pushed out and not yet taken) — what
+    /// SWMM_GW2D_LED_STORAGE reports. `nacc` is deliberately not subtracted:
+    /// that water is still inside `hg` until a cell applies it.
+    double liveStorage() const noexcept;
+    /// G-O: the storage the LEDGER can account for — holdings less the two
+    /// surface accumulators, which are always one firing out of phase with
+    /// `led_infil_in` / `led_dunne` (see continuityResidual).
+    double ledgeredStorage() const noexcept;
+    /// G-O: `ledgeredStorage − led_init_storage − (in − out)` with
+    /// in = infil_in + lateral + link (G-X3), out = deep + node + et + dunne; recharge and
+    /// capillary rise are internal to a cell and do not appear. Zero to
+    /// machine precision for a conserving kernel (swmm_gw2d_get_continuity_error).
+    double continuityResidual() const noexcept;
+};
+
+/**
+ * @brief Project-unit → SI multipliers for the four kinds of aquifer number.
+ *
+ * @details The authored `SubsurfaceConfig` is never converted in place. It
+ *          stays in the user's units for its whole life, and the SI values
+ *          exist only in `SubsurfaceState`, where the kernel needs them.
+ *          That is what makes the writer trivial and correct: it writes the
+ *          rows it parsed, unchanged, so a load-and-save with no edits is
+ *          byte-identical and no double-conversion is reachable. (An earlier
+ *          shape converted the config and let the writer invert; a hotstart
+ *          re-initialize then converted twice and shrank every aquifer by
+ *          3.28×. The state/config split removes the bug rather than
+ *          guarding it with a flag.)
+ */
+struct GwUnitFactors {
+    double length = 1.0;   ///< ft → m,      or m → m
+    double rate   = 1.0;   ///< in/hr → m/s, or mm/hr → m/s
+    double inv_len = 1.0;  ///< 1/ft → 1/m,  or 1/m → 1/m
+    double area   = 1.0;   ///< ft² → m²,    or m² → m²
+};
+
+/// Everything the parser fills, before resolution onto cells.
+struct SubsurfaceConfig {
+    GwOptions                 options;
+    std::vector rows;
+    std::vector    node_beds;
+    std::vector    link_rows;   ///< G-X4: [2D_AQUIFER_LINKS]
+
+    bool empty() const noexcept {
+        return !options.authored && rows.empty() && node_beds.empty() &&
+               link_rows.empty();
+    }
+    void clear() { *this = SubsurfaceConfig{}; }
+};
+
+const char* soilCharToken(SoilChar s) noexcept;
+bool        parseSoilChar(const std::string& t, SoilChar& s) noexcept;
+const char* gwClosureToken(GwClosure c) noexcept;
+bool        parseGwClosure(const std::string& t, GwClosure& c) noexcept;
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_SUBSURFACE_DATA_HPP
diff --git a/src/engine/2d/subsurface/SubsurfaceSections.cpp b/src/engine/2d/subsurface/SubsurfaceSections.cpp
new file mode 100644
index 000000000..543aa5e9e
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceSections.cpp
@@ -0,0 +1,824 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceSections.cpp
+ * @brief Parsers, resolution and writer for the `[2D_AQUIFER*]` sections.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SubsurfaceSections.hpp"
+
+#include "../data/MeshData.hpp"
+#include "../../core/SimulationContext.hpp"
+#include "../../core/UnitConversion.hpp"
+#include "../../input/InputParseUtils.hpp"
+#include "../../input/Tokenizer.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+namespace {
+
+bool iequals(const std::string& a, const char* b) {
+    std::size_t i = 0;
+    for (; i < a.size() && b[i]; ++i)
+        if (std::toupper(static_cast(a[i])) !=
+            std::toupper(static_cast(b[i]))) return false;
+    return i == a.size() && b[i] == '\0';
+}
+
+bool num(const std::string& s, double& v) {
+    auto [p, ec] = openswmm::from_chars_double(s.data(), s.data() + s.size(), v);
+    return ec == std::errc{} && p == s.data() + s.size() && std::isfinite(v);
+}
+
+bool inum(const std::string& s, int& v) {
+    double d = 0.0;
+    if (!num(s, d)) return false;
+    v = static_cast(d);
+    return static_cast(v) == d;
+}
+
+bool boolTok(const std::string& s, bool& v) {
+    if (iequals(s, "YES") || iequals(s, "TRUE")  || s == "1") { v = true;  return true; }
+    if (iequals(s, "NO")  || iequals(s, "FALSE") || s == "0") { v = false; return true; }
+    return false;
+}
+
+/// Format a double the way the rest of the 2D writers do: shortest round-trip
+/// that a human can still read, with trailing zeros trimmed.
+std::string fmt(double v) {
+    char buf[40];
+    std::snprintf(buf, sizeof buf, "%.6g", v);
+    return buf;
+}
+
+input::SectionHandler makeHandler(
+    const char* label,
+    std::function&)> lp,
+    GwOptions& opts) {
+    return [label, lp = std::move(lp), &opts](
+               openswmm::SimulationContext& ctx,
+               const std::vector& lines) {
+        opts.authored = true;
+        for (const auto& raw : lines) {
+            auto tokens = openswmm::input::Tokenizer::tokenize(raw);
+            if (tokens.empty()) continue;
+            const std::string err = lp(tokens);
+            if (!err.empty()) {
+                ctx.error_code    = 5;  // SWMM_ERR_PARSE
+                ctx.error_message =
+                    std::string("[") + label + "] " + err + " - line: " + raw;
+                return;
+            }
+        }
+    };
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER_OPTIONS]
+// ---------------------------------------------------------------------------
+
+std::string parseAquiferOptionsLine(const std::vector& tokens,
+                                    GwOptions& opts) {
+    if (tokens.size() < 2) return "expected KEY VALUE: " + tokens[0];
+    const std::string& k = tokens[0];
+    const std::string& v = tokens[1];
+
+    if (iequals(k, "SOIL_CHAR")) {
+        if (!parseSoilChar(v, opts.soil_char)) return "unknown SOIL_CHAR: " + v;
+        return {};
+    }
+    if (iequals(k, "CLOSURE")) {
+        if (!parseGwClosure(v, opts.closure)) return "unknown CLOSURE: " + v;
+        return {};
+    }
+    if (iequals(k, "M_LAYERS")) {
+        int m = 0;
+        if (!inum(v, m) || m < 2 || m > 128) return "M_LAYERS must be 2..128: " + v;
+        opts.m_layers = m;
+        return {};
+    }
+    if (iequals(k, "CAPILLARY_DIFF")) {
+        if (!boolTok(v, opts.capillary_diff)) return "CAPILLARY_DIFF must be YES/NO: " + v;
+        return {};
+    }
+    if (iequals(k, "FORCE_CLOSED_FORM")) {
+        if (!boolTok(v, opts.force_closed_form)) return "FORCE_CLOSED_FORM must be YES/NO: " + v;
+        return {};
+    }
+    if (iequals(k, "DUNNE")) {
+        if (!boolTok(v, opts.dunne)) return "DUNNE must be YES/NO: " + v;
+        return {};
+    }
+    if (iequals(k, "C_GW") || iequals(k, "C_COL")) {
+        double d = 0.0;
+        if (!num(v, d) || d <= 0.0 || d > 1.0)
+            return std::string(iequals(k, "C_GW") ? "C_GW" : "C_COL") +
+                   " must be in (0, 1]: " + v;
+        (iequals(k, "C_GW") ? opts.c_gw : opts.c_col) = d;
+        return {};
+    }
+    if (iequals(k, "MODE")) {
+        if (iequals(v, "MESH"))              { opts.per_subcatch = false; return {}; }
+        if (iequals(v, "PER_SUBCATCH"))      { opts.per_subcatch = true;  return {}; }
+        return "MODE must be MESH or PER_SUBCATCH: " + v;
+    }
+    if (iequals(k, "NODE_ENROLMENT")) {                 // G-X2
+        if (iequals(v, "AUTO")) { opts.node_auto = true;  return {}; }
+        if (iequals(v, "ROWS")) { opts.node_auto = false; return {}; }
+        return "NODE_ENROLMENT must be AUTO or ROWS: " + v;
+    }
+    if (iequals(k, "LINK_SEEPAGE")) {                   // G-X3 / G-X4
+        if (iequals(v, "AUTO"))    { opts.link_seepage = GwLinkMode::AUTO;    return {}; }
+        if (iequals(v, "NONE"))    { opts.link_seepage = GwLinkMode::NONE;    return {}; }
+        if (iequals(v, "TWO_WAY")) { opts.link_seepage = GwLinkMode::TWO_WAY; return {}; }
+        return "LINK_SEEPAGE must be AUTO, NONE or TWO_WAY: " + v;
+    }
+    if (iequals(k, "GW_ET")) {
+        if (iequals(v, "NONE") || iequals(v, "CAPILLARY_RISE") ||
+            iequals(v, "BOUNDARY_ET") || iequals(v, "BOTH")) {
+            opts.gw_et.assign(v.size(), '\0');
+            std::transform(v.begin(), v.end(), opts.gw_et.begin(),
+                           [](unsigned char c) {
+                               return static_cast(std::toupper(c));
+                           });
+            return {};
+        }
+        return "GW_ET must be NONE, CAPILLARY_RISE, BOUNDARY_ET or BOTH: " + v;
+    }
+    return "unknown option: " + k;
+}
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER]
+// ---------------------------------------------------------------------------
+
+std::string parseAquiferLine(const std::vector& tokens,
+                             std::vector& rows) {
+    GwAquiferRow r;
+    std::size_t at = 0;
+
+    if (tokens[0] == "*") { r.scope = 0; at = 1; }
+    else if (iequals(tokens[0], "TAG")) {
+        if (tokens.size() < 2) return "TAG needs a name";
+        r.scope = 1; r.tag = tokens[1]; at = 2;
+    } else if (iequals(tokens[0], "CELL")) {
+        int n = 0;
+        if (tokens.size() < 2 || !inum(tokens[1], n) || n < 1)
+            return "CELL needs a 1-based index";
+        r.scope = 2; r.cell = n - 1; at = 2;
+    } else {
+        return "row must start with CELL, TAG or '*': " + tokens[0];
+    }
+
+    // Five positional columns: KS ZS THETA_S THETA_R ALPHA.
+    static const char* kPos[5] = {"KS", "ZS", "THETA_S", "THETA_R", "ALPHA"};
+    double* const dst[5] = {&r.Ks, &r.zs, &r.theta_s, &r.theta_r, &r.alpha};
+    for (int i = 0; i < 5; ++i) {
+        if (at >= tokens.size()) return std::string("missing ") + kPos[i];
+        if (!num(tokens[at], *dst[i]))
+            return std::string("invalid ") + kPos[i] + ": " + tokens[at];
+        ++at;
+    }
+
+    // Everything law-specific is a keyword, so a fifth law never renumbers an
+    // existing file.
+    while (at < tokens.size()) {
+        const std::string& k = tokens[at];
+        if (at + 1 >= tokens.size()) return "keyword " + k + " needs a value";
+        const std::string& v = tokens[at + 1];
+        at += 2;
+        if      (iequals(k, "PSI_B"))  { if (!num(v, r.psi_b))  return "invalid PSI_B: " + v; }
+        else if (iequals(k, "LAMBDA")) { if (!num(v, r.lambda)) return "invalid LAMBDA: " + v; }
+        else if (iequals(k, "N"))      { if (!num(v, r.vg_n))   return "invalid N: " + v; }
+        else if (iequals(k, "L"))      { if (!num(v, r.vg_L))   return "invalid L: " + v; }
+        else if (iequals(k, "C_LOSS")) { if (!num(v, r.c_loss)) return "invalid C_LOSS: " + v; }
+        else if (iequals(k, "HG0"))    { if (!num(v, r.hg0))    return "invalid HG0: " + v; }
+        else if (iequals(k, "SOIL_CHAR")) {
+            if (!parseSoilChar(v, r.soil_char)) return "unknown SOIL_CHAR: " + v;
+            r.soil_char_set = true;
+        } else if (iequals(k, "CLOSURE")) {
+            if (!parseGwClosure(v, r.closure)) return "unknown CLOSURE: " + v;
+            r.closure_set = true;
+        } else if (iequals(k, "M_LAYERS")) {
+            if (!inum(v, r.m_layers) || r.m_layers < 2 || r.m_layers > 128)
+                return "M_LAYERS must be 2..128: " + v;
+        } else {
+            return "unknown keyword: " + k;
+        }
+    }
+
+    if (r.Ks <= 0.0)      return "KS must be > 0";
+    if (r.zs <= 0.0)      return "ZS must be > 0";
+    if (r.theta_s <= 0.0 || r.theta_s > 1.0) return "THETA_S must be in (0, 1]";
+    if (r.theta_r < 0.0 || r.theta_r >= r.theta_s)
+        return "THETA_R must be in [0, THETA_S)";
+    if (r.alpha <= 0.0)   return "ALPHA must be > 0";
+    if (r.vg_n <= 1.0)    return "N must be > 1";
+    if (r.lambda <= 0.0)  return "LAMBDA must be > 0";
+    if (r.psi_b < 0.0)    return "PSI_B must be >= 0";
+    if (r.c_loss < 0.0)   return "C_LOSS must be >= 0";
+
+    rows.push_back(r);
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// [2D_AQUIFER_NODE]
+// ---------------------------------------------------------------------------
+
+std::string parseAquiferNodeLine(const std::vector& tokens,
+                                 std::vector& beds,
+                                 std::vector& names) {
+    if (tokens.size() < 2)
+        return "expected NODE CELL|AUTO [KC k DC d] [AREA a] [EXCHANGE YES|NO]";
+    GwNodeBed b;
+    int cell = 0;
+    if (iequals(tokens[1], "AUTO")) {
+        b.locate = true;                      // G-X2: located at resolve
+    } else {
+        if (!inum(tokens[1], cell) || cell < 1)
+            return "CELL must be a 1-based index or AUTO: " + tokens[1];
+        b.cell = cell - 1;
+    }
+
+    std::size_t at = 2;
+    while (at < tokens.size()) {
+        const std::string& k = tokens[at];
+        if (at + 1 >= tokens.size()) return "keyword " + k + " needs a value";
+        const std::string& v = tokens[at + 1];
+        at += 2;
+        if      (iequals(k, "KC"))   { if (!num(v, b.Kc))   return "invalid KC: " + v; }
+        else if (iequals(k, "DC"))   { if (!num(v, b.dC))   return "invalid DC: " + v; }
+        else if (iequals(k, "AREA")) { if (!num(v, b.area)) return "invalid AREA: " + v; }
+        else if (iequals(k, "EXCHANGE")) {              // G-X2 opt-out
+            if (!boolTok(v, b.exchange)) return "EXCHANGE must be YES/NO: " + v;
+        }
+        else return "unknown keyword: " + k;
+    }
+    if (b.Kc < 0.0 || b.dC < 0.0 || b.area < 0.0)
+        return "KC, DC and AREA must be >= 0";
+    if (b.Kc > 0.0 && b.dC <= 0.0)
+        return "KC given without a positive DC (a bed needs a thickness)";
+
+    beds.push_back(b);
+    names.push_back(tokens[0]);
+    return {};
+}
+
+// G-X4: one `[2D_AQUIFER_LINKS]` line — `LINK [KC k] [DC d] [EXCHANGE YES|NO]`.
+std::string parseAquiferLinkLine(const std::vector& tokens,
+                                 std::vector& rows,
+                                 std::vector& names) {
+    if (tokens.empty())
+        return "expected LINK [KC k] [DC d] [EXCHANGE YES|NO]";
+    GwLinkRow r;
+    std::size_t at = 1;
+    while (at < tokens.size()) {
+        const std::string& k = tokens[at];
+        if (at + 1 >= tokens.size()) return "keyword " + k + " needs a value";
+        const std::string& v = tokens[at + 1];
+        at += 2;
+        if      (iequals(k, "KC")) { if (!num(v, r.Kc)) return "invalid KC: " + v; }
+        else if (iequals(k, "DC")) { if (!num(v, r.dC)) return "invalid DC: " + v; }
+        else if (iequals(k, "EXCHANGE")) {
+            if (!boolTok(v, r.exchange)) return "EXCHANGE must be YES/NO: " + v;
+        }
+        else return "unknown keyword: " + k;
+    }
+    if (r.Kc < 0.0 || r.dC < 0.0) return "KC and DC must be >= 0";
+    rows.push_back(r);
+    names.push_back(tokens[0]);
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+void registerSubsurfaceSections(SubsurfaceConfig& cfg,
+                                std::vector& node_names,
+                                std::vector& link_names,
+                                input::SectionRegistry& registry) {
+    registry.register_custom("2D_AQUIFER_OPTIONS",
+        makeHandler("2D_AQUIFER_OPTIONS",
+            [&cfg](const std::vector& t) {
+                return parseAquiferOptionsLine(t, cfg.options);
+            }, cfg.options));
+    registry.register_custom("2D_AQUIFER",
+        makeHandler("2D_AQUIFER",
+            [&cfg](const std::vector& t) {
+                return parseAquiferLine(t, cfg.rows);
+            }, cfg.options));
+    registry.register_custom("2D_AQUIFER_NODE",
+        makeHandler("2D_AQUIFER_NODE",
+            [&cfg, &node_names](const std::vector& t) {
+                return parseAquiferNodeLine(t, cfg.node_beds, node_names);
+            }, cfg.options));
+    registry.register_custom("2D_AQUIFER_LINKS",              // G-X4
+        makeHandler("2D_AQUIFER_LINKS",
+            [&cfg, &link_names](const std::vector& t) {
+                return parseAquiferLinkLine(t, cfg.link_rows, link_names);
+            }, cfg.options));
+}
+
+// ---------------------------------------------------------------------------
+// Units and resolution
+// ---------------------------------------------------------------------------
+
+GwUnitFactors gwUnitFactors(const SimulationContext& ctx) noexcept {
+    GwUnitFactors f;
+    const int sys = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    if (sys == 0) {                       // US
+        f.length  = 0.3048;               // ft  → m
+        f.rate    = 0.0254 / 3600.0;      // in/hr → m/s
+        f.inv_len = 1.0 / 0.3048;         // 1/ft → 1/m
+        f.area    = 0.3048 * 0.3048;      // ft² → m²
+    } else {                              // SI
+        f.length  = 1.0;                  // m
+        f.rate    = 0.001 / 3600.0;       // mm/hr → m/s
+        f.inv_len = 1.0;
+        f.area    = 1.0;
+    }
+    return f;
+}
+
+namespace {
+
+/// G-X2: which cell (−1 = none) contains the point (x, y) in the mesh's own
+/// coordinates. A uniform bin grid over the cell bounding boxes keeps a
+/// whole network's nodes O(n) rather than O(n_nodes × n_cells).
+class CellLocator {
+public:
+    explicit CellLocator(const MeshData& m) : m_(m) {
+        const int n = m.n_cells();
+        if (n == 0 || m.vx.empty()) return;
+        xmin_ = ymin_ =  1.0e300; xmax_ = ymax_ = -1.0e300;
+        for (std::size_t v = 0; v < m.vx.size(); ++v) {
+            xmin_ = std::min(xmin_, m.vx[v]); xmax_ = std::max(xmax_, m.vx[v]);
+            ymin_ = std::min(ymin_, m.vy[v]); ymax_ = std::max(ymax_, m.vy[v]);
+        }
+        nb_ = std::max(1, static_cast(std::sqrt(static_cast(n))));
+        dx_ = std::max((xmax_ - xmin_) / nb_, 1.0e-9);
+        dy_ = std::max((ymax_ - ymin_) / nb_, 1.0e-9);
+        bins_.assign(static_cast(nb_) * nb_, {});
+        for (int c = 0; c < n; ++c) {
+            double bx0 = 1.0e300, by0 = 1.0e300, bx1 = -1.0e300, by1 = -1.0e300;
+            for (int k = 0; k < m.cell_nv[static_cast(c)]; ++k) {
+                const auto v = static_cast(m.cell_vertex(c, k));
+                bx0 = std::min(bx0, m.vx[v]); bx1 = std::max(bx1, m.vx[v]);
+                by0 = std::min(by0, m.vy[v]); by1 = std::max(by1, m.vy[v]);
+            }
+            for (int j = bin(by0, ymin_, dy_); j <= bin(by1, ymin_, dy_); ++j)
+                for (int i = bin(bx0, xmin_, dx_); i <= bin(bx1, xmin_, dx_); ++i)
+                    bins_[static_cast(j) * nb_ + i].push_back(c);
+        }
+    }
+    int locate(double x, double y) const {
+        if (bins_.empty() || x < xmin_ || x > xmax_ || y < ymin_ || y > ymax_) return -1;
+        const auto& cand = bins_[static_cast(bin(y, ymin_, dy_)) * nb_ +
+                                 bin(x, xmin_, dx_)];
+        for (const int c : cand) if (inside(c, x, y)) return c;
+        return -1;
+    }
+    /// G-X3: every cell whose bounding box may meet the box [x0,x1]×[y0,y1]
+    /// (the union of the bins the box covers, de-duplicated), for a segment
+    /// clip. Empty when the box misses the mesh entirely.
+    std::vector candidates(double x0, double y0, double x1, double y1) const {
+        std::vector out;
+        if (bins_.empty()) return out;
+        if (std::max(x0, x1) < xmin_ || std::min(x0, x1) > xmax_ ||
+            std::max(y0, y1) < ymin_ || std::min(y0, y1) > ymax_) return out;
+        const int i0 = bin(std::min(x0, x1), xmin_, dx_), i1 = bin(std::max(x0, x1), xmin_, dx_);
+        const int j0 = bin(std::min(y0, y1), ymin_, dy_), j1 = bin(std::max(y0, y1), ymin_, dy_);
+        for (int j = j0; j <= j1; ++j)
+            for (int i = i0; i <= i1; ++i)
+                for (const int c : bins_[static_cast(j) * nb_ + i])
+                    out.push_back(c);
+        std::sort(out.begin(), out.end());
+        out.erase(std::unique(out.begin(), out.end()), out.end());
+        return out;
+    }
+    /// G-X3: the length of the segment (x0,y0)→(x1,y1) inside cell `c`.
+    /// Cells are CCW and convex (MeshBuilder validates both), so this is
+    /// the Cyrus–Beck clip: the parameter interval [t_lo, t_hi] that lies on
+    /// the inner side of every edge's half-plane. Exact for a straight
+    /// segment — no sampling, no step error.
+    double lengthInside(int c, double x0, double y0, double x1, double y1) const {
+        const int nv = m_.cell_nv[static_cast(c)];
+        const double dx = x1 - x0, dy = y1 - y0;
+        double t_lo = 0.0, t_hi = 1.0;
+        for (int i = 0, j = nv - 1; i < nv; j = i++) {
+            const auto vi = static_cast(m_.cell_vertex(c, j));
+            const auto vj = static_cast(m_.cell_vertex(c, i));
+            const double ex = m_.vx[vj] - m_.vx[vi], ey = m_.vy[vj] - m_.vy[vi];
+            // signed distance ∝ cross(edge, P − v_i): ≥ 0 inside for CCW
+            const double d0 = ex * (y0 - m_.vy[vi]) - ey * (x0 - m_.vx[vi]);
+            const double d1 = ex * (y1 - m_.vy[vi]) - ey * (x1 - m_.vx[vi]);
+            const double dd = d1 - d0;                // d(t) = d0 + dd·t
+            if (std::fabs(dd) < 1.0e-300) {
+                if (d0 < 0.0) return 0.0;             // parallel, outside
+                continue;                             // parallel, inside/on the edge
+            }
+            const double t = -d0 / dd;
+            if (dd < 0.0) t_hi = std::min(t_hi, t);   // leaving the half-plane
+            else          t_lo = std::max(t_lo, t);   // entering it
+            if (t_lo >= t_hi) return 0.0;
+        }
+        return (t_hi - t_lo) * std::hypot(dx, dy);
+    }
+private:
+    int bin(double v, double v0, double d) const {
+        return std::clamp(static_cast((v - v0) / d), 0, nb_ - 1);
+    }
+    bool inside(int c, double x, double y) const {   // ray casting, any polygon
+        const int nv = m_.cell_nv[static_cast(c)];
+        bool in = false;
+        for (int i = 0, j = nv - 1; i < nv; j = i++) {
+            const auto vi = static_cast(m_.cell_vertex(c, i));
+            const auto vj = static_cast(m_.cell_vertex(c, j));
+            const double xi = m_.vx[vi], yi = m_.vy[vi], xj = m_.vx[vj], yj = m_.vy[vj];
+            if (((yi > y) != (yj > y)) &&
+                (x < (xj - xi) * (y - yi) / (yj - yi) + xi))
+                in = !in;
+        }
+        return in;
+    }
+    const MeshData& m_;
+    double xmin_ = 0, xmax_ = 0, ymin_ = 0, ymax_ = 0, dx_ = 1, dy_ = 1;
+    int nb_ = 0;
+    std::vector> bins_;
+};
+
+}  // namespace
+
+std::vector resolveSubsurface(
+    SimulationContext& ctx, const MeshData& mesh, SubsurfaceConfig& cfg,
+    std::vector& names, double node_xy_to_mesh) {
+    std::vector errs;
+    if (cfg.empty()) return errs;
+
+    const int n = mesh.n_cells();
+    for (const auto& r : cfg.rows) {
+        if (r.scope == 2 && (r.cell < 0 || r.cell >= n))
+            errs.push_back("[2D_AQUIFER] CELL " + std::to_string(r.cell + 1) +
+                           " is not on the mesh (" + std::to_string(n) +
+                           " cells).");
+    }
+
+    // G-X2: the locator serves `CELL AUTO` rows and auto-enrolment alike.
+    const CellLocator locator(mesh);
+    auto locateNode = [&](int ni) -> int {
+        const auto u = static_cast(ni);
+        if (u >= ctx.spatial.node_x.size() || u >= ctx.spatial.node_y.size()) return -1;
+        if (u >= ctx.spatial.node_has_xy.size() || !ctx.spatial.node_has_xy[u]) return -1;
+        return locator.locate(ctx.spatial.node_x[u] * node_xy_to_mesh,
+                              ctx.spatial.node_y[u] * node_xy_to_mesh);
+    };
+
+    for (std::size_t i = 0; i < cfg.node_beds.size(); ++i) {
+        auto& b = cfg.node_beds[i];
+        const std::string& nm = (i < names.size()) ? names[i] : std::string{};
+        b.node = ctx.node_names.find(nm);
+        if (b.node < 0) {
+            errs.push_back("[2D_AQUIFER_NODE] unknown node '" + nm + "'.");
+            continue;
+        }
+        if (b.locate) {
+            b.cell = locateNode(b.node);
+            if (b.cell < 0 && b.exchange)
+                errs.push_back("[2D_AQUIFER_NODE] node '" + nm + "' CELL AUTO: the node's "
+                               "[COORDINATES] fall in no mesh cell.");
+        } else if (b.exchange && (b.cell < 0 || b.cell >= n)) {
+            errs.push_back("[2D_AQUIFER_NODE] node '" + nm + "' CELL " +
+                           std::to_string(b.cell + 1) +
+                           " is not on the mesh.");
+        }
+    }
+
+    // G-X2: auto-enrolment — every node whose coordinates fall in a cell
+    // and that no row names gets a direct-Darcy bed over the cell's area.
+    // Rows override (their bed, or their EXCHANGE NO). Nodes without
+    // coordinates are simply not in any cell.
+    if (cfg.options.node_auto && errs.empty()) {
+        std::vector named(static_cast(ctx.n_nodes()), 0);
+        for (const auto& b : cfg.node_beds)
+            if (b.node >= 0 && b.node < ctx.n_nodes()) named[static_cast(b.node)] = 1;
+        int enrolled = 0;
+        for (int ni = 0; ni < ctx.n_nodes(); ++ni) {
+            if (named[static_cast(ni)]) continue;
+            const int c = locateNode(ni);
+            if (c < 0) continue;
+            GwNodeBed b;
+            b.node = ni; b.cell = c; b.locate = true; b.automatic = true;
+            cfg.node_beds.push_back(b);
+            names.push_back(ctx.node_names.name_of(ni));
+            ++enrolled;
+        }
+        if (enrolled > 0)
+            ctx.warnings.push_back("2D aquifer: " + std::to_string(enrolled) +
+                                   " node(s) inside the mesh enrolled in the node <-> aquifer "
+                                   "exchange by their coordinates (NODE_ENROLMENT AUTO; a "
+                                   "[2D_AQUIFER_NODE] row with EXCHANGE NO opts a node out).");
+    }
+
+    // One bed per node: two beds on one node would double the exchange and
+    // the node would never know.
+    std::vector seen;
+    for (const auto& b : cfg.node_beds) {
+        if (b.node < 0) continue;
+        if (std::find(seen.begin(), seen.end(), b.node) != seen.end())
+            errs.push_back("[2D_AQUIFER_NODE] node index " +
+                           std::to_string(b.node) +
+                           " has more than one bed row.");
+        else seen.push_back(b.node);
+    }
+    // G-X2: an EXCHANGE NO row has done its job (it kept auto-enrolment
+    // away) — drop it from the beds the kernel sees. The authored row stays
+    // in the config for the writer, so the flag is carried on the bed and
+    // the solver skips it (SubsurfaceSolver::initialize).
+    return errs;
+}
+
+// G-X3 (2026-09-19): which cells each seeping conduit crosses, and by how
+// much of its length. The polyline (node1 → [VERTICES] → node2, project map
+// units) is clipped segment by segment against the convex cells the locator
+// offers for its bounding box; the per-cell length over the whole polyline
+// length is the share — exact, so an evenly split conduit gives 0.5/0.5 to
+// the last bit. A segment lying ON a shared edge is inside both cells; the
+// shares are then scaled so a conduit never delivers more than its length
+// (each side gets half). Only conduits with a [LOSSES] seepage rate at
+// initialize take part (the others have nothing to deliver).
+std::vector resolveLinkSeepage(SimulationContext& ctx,
+                                            const MeshData& mesh,
+                                            SubsurfaceConfig& cfg,
+                                            std::vector& link_names,
+                                            double node_xy_to_mesh,
+                                            int& n_conduits) {
+    std::vector out;
+    n_conduits = 0;
+    const int n = mesh.n_cells();
+    if (n == 0 || mesh.vx.empty()) return out;
+    const CellLocator locator(mesh);
+
+    // G-X4: resolve the `[2D_AQUIFER_LINKS]` names once. A row on a link the
+    // model does not have, or on something that is not a conduit, is an
+    // authoring error — it would otherwise be silently ignored and the
+    // modeller would never learn why the reach did not gain.
+    for (std::size_t i = 0; i < cfg.link_rows.size(); ++i) {
+        auto& r = cfg.link_rows[i];
+        const std::string& nm = (i < link_names.size()) ? link_names[i]
+                                                        : std::string{};
+        r.link = ctx.link_names.find(nm);
+        if (r.link < 0) {
+            ctx.warnings.push_back("[2D_AQUIFER_LINKS] unknown link '" + nm +
+                                   "' — the row was ignored.");
+        } else if (ctx.links.type[static_cast(r.link)] !=
+                   LinkType::CONDUIT) {
+            ctx.warnings.push_back("[2D_AQUIFER_LINKS] link '" + nm +
+                                   "' is not a conduit — only conduits exchange "
+                                   "with the aquifer along their length; the row "
+                                   "was ignored.");
+            r.link = -1;
+        }
+    }
+    auto rowFor = [&cfg](int link) -> const GwLinkRow* {
+        for (const auto& r : cfg.link_rows) if (r.link == link) return &r;
+        return nullptr;
+    };
+    const bool two_way = cfg.options.link_seepage == GwLinkMode::TWO_WAY;
+
+    auto xy = [&](int ni, double& x, double& y) -> bool {
+        const auto u = static_cast(ni);
+        if (ni < 0 || u >= ctx.spatial.node_x.size() || u >= ctx.spatial.node_y.size()) return false;
+        if (u >= ctx.spatial.node_has_xy.size() || !ctx.spatial.node_has_xy[u]) return false;
+        x = ctx.spatial.node_x[u] * node_xy_to_mesh;
+        y = ctx.spatial.node_y[u] * node_xy_to_mesh;
+        return true;
+    };
+
+    const auto& CD = ctx.link_subtypes.conduits;
+    for (int j = 0; j < ctx.n_links(); ++j) {
+        const auto uj = static_cast(j);
+        if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        if (cr < 0) continue;
+        // G-X4: TWO_WAY, a row may give a conduit that never leaked its own
+        // conductivity (`KC`) — a pipe under the table gains without ever
+        // having had a [LOSSES] seepage rate — and `EXCHANGE NO` keeps a
+        // conduit out of the channel entirely.
+        const GwLinkRow* row = rowFor(j);
+        if (row != nullptr && !row->exchange) continue;
+        const double k_authored =
+            (two_way && row != nullptr && row->Kc > 0.0)
+                ? row->Kc : CD.seep_rate[static_cast(cr)];
+        if (k_authored <= 0.0) continue;
+
+        std::vector px, py;
+        double x = 0.0, y = 0.0;
+        if (!xy(ctx.links.node1[uj], x, y)) continue;
+        px.push_back(x); py.push_back(y);
+        if (uj < ctx.spatial.link_vertices_x.size() &&
+            uj < ctx.spatial.link_vertices_y.size()) {
+            const auto& vx = ctx.spatial.link_vertices_x[uj];
+            const auto& vy = ctx.spatial.link_vertices_y[uj];
+            for (std::size_t k = 0; k < vx.size() && k < vy.size(); ++k) {
+                px.push_back(vx[k] * node_xy_to_mesh);
+                py.push_back(vy[k] * node_xy_to_mesh);
+            }
+        }
+        if (!xy(ctx.links.node2[uj], x, y)) continue;
+        px.push_back(x); py.push_back(y);
+
+        double L = 0.0;
+        for (std::size_t k = 1; k < px.size(); ++k)
+            L += std::hypot(px[k] - px[k - 1], py[k] - py[k - 1]);
+        if (L <= 0.0) continue;
+
+        std::vector> len_in;   // cell, length
+        double sum = 0.0;
+        for (std::size_t k = 1; k < px.size(); ++k) {
+            const double x0 = px[k - 1], y0 = py[k - 1], x1 = px[k], y1 = py[k];
+            if (std::hypot(x1 - x0, y1 - y0) <= 0.0) continue;
+            for (const int c : locator.candidates(x0, y0, x1, y1)) {
+                const double len = locator.lengthInside(c, x0, y0, x1, y1);
+                if (len <= 0.0) continue;
+                sum += len;
+                auto it = std::find_if(len_in.begin(), len_in.end(),
+                                       [c](const std::pair& e) { return e.first == c; });
+                if (it == len_in.end()) len_in.emplace_back(c, len);
+                else it->second += len;
+            }
+        }
+        if (len_in.empty()) continue;
+        ++n_conduits;
+        const double denom = std::max(L, sum);   // on-edge double coverage → halves
+        for (const auto& e : len_in) {
+            GwLinkShare sh;
+            sh.link = j; sh.cell = e.first; sh.weight = e.second / denom;
+            out.push_back(sh);
+        }
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Writer
+// ---------------------------------------------------------------------------
+
+void writeSubsurfaceSections(const SubsurfaceConfig& cfg,
+                             const std::vector& node_names,
+                             const std::vector& link_names,
+                             std::string& out) {
+    if (cfg.empty()) return;
+    const GwOptions d{};   // defaults, for the omit-if-unchanged rule
+
+    if (cfg.options.authored) {
+        std::string body;
+        auto kv = [&body](const char* k, const std::string& v) {
+            body += k;
+            body.append(std::max(1, 18 - std::strlen(k)), ' ');
+            body += v;
+            body += '\n';
+        };
+        if (cfg.options.soil_char != d.soil_char)
+            kv("SOIL_CHAR", soilCharToken(cfg.options.soil_char));
+        if (cfg.options.closure != d.closure)
+            kv("CLOSURE", gwClosureToken(cfg.options.closure));
+        if (cfg.options.m_layers != d.m_layers)
+            kv("M_LAYERS", std::to_string(cfg.options.m_layers));
+        if (cfg.options.capillary_diff != d.capillary_diff)
+            kv("CAPILLARY_DIFF", cfg.options.capillary_diff ? "YES" : "NO");
+        if (cfg.options.c_gw != d.c_gw)   kv("C_GW",  fmt(cfg.options.c_gw));
+        if (cfg.options.c_col != d.c_col) kv("C_COL", fmt(cfg.options.c_col));
+        if (cfg.options.force_closed_form != d.force_closed_form)
+            kv("FORCE_CLOSED_FORM", cfg.options.force_closed_form ? "YES" : "NO");
+        if (cfg.options.per_subcatch != d.per_subcatch)
+            kv("MODE", cfg.options.per_subcatch ? "PER_SUBCATCH" : "MESH");
+        if (cfg.options.dunne != d.dunne)
+            kv("DUNNE", cfg.options.dunne ? "YES" : "NO");
+        if (cfg.options.gw_et != d.gw_et) kv("GW_ET", cfg.options.gw_et);
+        if (cfg.options.node_auto != d.node_auto)
+            kv("NODE_ENROLMENT", cfg.options.node_auto ? "AUTO" : "ROWS");   // G-X2
+        if (cfg.options.link_seepage != d.link_seepage)                    // G-X3/G-X4
+            kv("LINK_SEEPAGE",
+               cfg.options.link_seepage == GwLinkMode::NONE    ? "NONE"
+             : cfg.options.link_seepage == GwLinkMode::TWO_WAY ? "TWO_WAY"
+                                                               : "AUTO");
+        if (!body.empty()) {
+            out += "\n[2D_AQUIFER_OPTIONS]\n";
+            out += body;
+        }
+    }
+
+    if (!cfg.rows.empty()) {
+        out += "\n[2D_AQUIFER]\n";
+        out += ";;Scope           KS         ZS         Theta_s    Theta_r    "
+               "Alpha      Options\n";
+        const GwAquiferRow rd{};
+        for (const auto& r : cfg.rows) {
+            std::string line;
+            if      (r.scope == 0) line = "*";
+            else if (r.scope == 1) line = "TAG  " + r.tag;
+            else                   line = "CELL " + std::to_string(r.cell + 1);
+            line.append(std::max(1, 18 - line.size()), ' ');
+            for (double v : {r.Ks, r.zs, r.theta_s, r.theta_r, r.alpha}) {
+                const std::string s = fmt(v);
+                line += s;
+                line.append(std::max(1, 11 - s.size()), ' ');
+            }
+            auto opt = [&line](const char* k, const std::string& v) {
+                line += k; line += ' '; line += v; line += ' ';
+            };
+            if (r.psi_b  != rd.psi_b)  opt("PSI_B",  fmt(r.psi_b));
+            if (r.lambda != rd.lambda) opt("LAMBDA", fmt(r.lambda));
+            if (r.vg_n   != rd.vg_n)   opt("N",      fmt(r.vg_n));
+            if (r.vg_L   != rd.vg_L)   opt("L",      fmt(r.vg_L));
+            if (r.c_loss != rd.c_loss) opt("C_LOSS", fmt(r.c_loss));
+            if (r.hg0    != rd.hg0)    opt("HG0",    fmt(r.hg0));
+            if (r.soil_char_set) opt("SOIL_CHAR", soilCharToken(r.soil_char));
+            if (r.closure_set)   opt("CLOSURE",   gwClosureToken(r.closure));
+            if (r.m_layers > 0)  opt("M_LAYERS",  std::to_string(r.m_layers));
+            while (!line.empty() && line.back() == ' ') line.pop_back();
+            out += line;
+            out += '\n';
+        }
+    }
+
+    // G-X2: auto-enrolled beds are not echoed — NODE_ENROLMENT AUTO recreates
+    // them from the coordinates, and echoing would turn a located bed into an
+    // authored CELL row that no longer follows the node if it moves.
+    bool any_authored = false;
+    for (const auto& b : cfg.node_beds) if (!b.automatic) { any_authored = true; break; }
+    if (any_authored) {
+        out += "\n[2D_AQUIFER_NODE]\n";
+        out += ";;Node             Cell       Options\n";
+        for (std::size_t i = 0; i < cfg.node_beds.size(); ++i) {
+            const auto& b = cfg.node_beds[i];
+            if (b.automatic) continue;
+            std::string line = (i < node_names.size()) ? node_names[i]
+                                                       : std::string("?");
+            line.append(std::max(1, 19 - line.size()), ' ');
+            const std::string c = b.locate ? std::string("AUTO")
+                                           : std::to_string(b.cell + 1);
+            line += c;
+            line.append(std::max(1, 11 - c.size()), ' ');
+            if (b.Kc   > 0.0) { line += "KC ";   line += fmt(b.Kc);   line += ' '; }
+            if (b.dC   > 0.0) { line += "DC ";   line += fmt(b.dC);   line += ' '; }
+            if (b.area > 0.0) { line += "AREA "; line += fmt(b.area); line += ' '; }
+            if (!b.exchange)  { line += "EXCHANGE NO "; }
+            while (!line.empty() && line.back() == ' ') line.pop_back();
+            out += line;
+            out += '\n';
+        }
+    }
+
+    // G-X4: the per-conduit overrides. Echoed verbatim — the rows carry the
+    // authored numbers, never a converted copy (the GwUnitFactors note).
+    if (!cfg.link_rows.empty()) {
+        out += "\n[2D_AQUIFER_LINKS]\n";
+        out += ";;Link              Options\n";
+        for (std::size_t i = 0; i < cfg.link_rows.size(); ++i) {
+            const auto& r = cfg.link_rows[i];
+            std::string line = (i < link_names.size()) ? link_names[i]
+                                                       : std::string("?");
+            line.append(std::max(1, 19 - line.size()), ' ');
+            if (r.Kc > 0.0) { line += "KC "; line += fmt(r.Kc); line += ' '; }
+            if (r.dC > 0.0) { line += "DC "; line += fmt(r.dC); line += ' '; }
+            if (!r.exchange) { line += "EXCHANGE NO "; }
+            while (!line.empty() && line.back() == ' ') line.pop_back();
+            out += line;
+            out += '\n';
+        }
+    }
+}
+
+}  // namespace openswmm::twoD
diff --git a/src/engine/2d/subsurface/SubsurfaceSections.hpp b/src/engine/2d/subsurface/SubsurfaceSections.hpp
new file mode 100644
index 000000000..d42e07ffb
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceSections.hpp
@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceSections.hpp
+ * @brief G-step 1 — `[2D_AQUIFER_OPTIONS]`, `[2D_AQUIFER]` and
+ *        `[2D_AQUIFER_NODE]`: parsing, unit resolution and writing.
+ *
+ * @section aq_units One rule for units, not seven
+ *
+ * Rows are authored in the project's own unit system and converted once, by
+ * the kernel, through `GwUnitFactors` (declared in SubsurfaceData.hpp). The
+ * rule is deliberately uniform so a user who has read one row can read them
+ * all:
+ *
+ * | quantity | US | SI |
+ * |---|---|---|
+ * | lengths — `ZS`, `PSI_B`, `HG0`, `DC` | ft | m |
+ * | rates — `KS`, `C_LOSS`, `KC`        | in/hr | mm/hr |
+ * | inverse lengths — `ALPHA`           | 1/ft | 1/m |
+ * | areas — `AREA`                      | ft² | m² |
+ * | `THETA_S`, `THETA_R`, `LAMBDA`, `N`, `L` | — | — |
+ *
+ * The rates follow `[INFILTRATION]` and `[AQUIFERS]` (in/hr, mm/hr), which is
+ * what a SWMM user already expects for a conductivity. The lengths follow the
+ * project length unit rather than `[INFILTRATION]`'s inches, because `ZS` is a
+ * soil-column depth of metres, not a suction head of millimetres, and mixing
+ * the two in one section is how unit bugs are authored.
+ *
+ * @section aq_syntax Syntax
+ *
+ * ```
+ * [2D_AQUIFER_OPTIONS]
+ * SOIL_CHAR      RUSSO | GARDNER | BROOKS_COREY | VAN_GENUCHTEN
+ * CLOSURE        AUTO | CLOSED_FORM | ENSLAVED | SIGMA
+ * M_LAYERS       8
+ * CAPILLARY_DIFF NO
+ * C_GW           0.5
+ * C_COL          0.9
+ * FORCE_CLOSED_FORM NO
+ * MODE           MESH | PER_SUBCATCH
+ * DUNNE          YES
+ * GW_ET          NONE | CAPILLARY_RISE | BOUNDARY_ET | BOTH
+ *
+ * [2D_AQUIFER]
+ * ;;scope         KS      ZS   THETA_S THETA_R ALPHA  [key value]…
+ * *               0.5     5.0  0.45    0.10    2.0    C_LOSS 0.0  HG0 1.0
+ * TAG  clay       0.02    3.0  0.50    0.15    1.2    SOIL_CHAR VAN_GENUCHTEN N 1.3
+ * CELL 42         1.0     6.0  0.42    0.08    3.0    CLOSURE SIGMA M_LAYERS 16
+ *
+ * [2D_AQUIFER_NODE]
+ * ;;node   cell   [KC kc DC dc] [AREA a]
+ * J1       17     KC 0.01 DC 0.5
+ * ```
+ *
+ * The five positional columns are the ones every law needs. Everything a
+ * particular law adds (`PSI_B`, `LAMBDA`, `N`, `L`) is a keyword, so adding a
+ * law later does not renumber anyone's file.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SUBSURFACE_SECTIONS_HPP
+#define OPENSWMM_ENGINE_2D_SUBSURFACE_SECTIONS_HPP
+
+#include "SubsurfaceData.hpp"
+#include "../../input/SectionRegistry.hpp"
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::twoD {
+
+struct MeshData;
+
+/// One `[2D_AQUIFER_OPTIONS]` line (`KEY VALUE`). Empty return = OK.
+std::string parseAquiferOptionsLine(const std::vector& tokens,
+                                    GwOptions& opts);
+
+/// One `[2D_AQUIFER]` line. Empty return = OK.
+std::string parseAquiferLine(const std::vector& tokens,
+                             std::vector& rows);
+
+/// One `[2D_AQUIFER_NODE]` line. `node` is left as a NAME in @p names until
+/// `resolveSubsurface` maps it to an index. Empty return = OK.
+std::string parseAquiferNodeLine(const std::vector& tokens,
+                                 std::vector& beds,
+                                 std::vector& names);
+
+/// One `[2D_AQUIFER_LINKS]` line (G-X4). `link` stays a NAME in @p names
+/// until `resolveLinkSeepage` maps it. Empty return = OK.
+std::string parseAquiferLinkLine(const std::vector& tokens,
+                                 std::vector& rows,
+                                 std::vector& names);
+
+/// Register the four handlers against @p registry, writing into @p cfg.
+void registerSubsurfaceSections(SubsurfaceConfig& cfg,
+                                std::vector& node_names,
+                                std::vector& link_names,
+                                input::SectionRegistry& registry);
+
+/// The factors for this project's unit system.
+GwUnitFactors gwUnitFactors(const SimulationContext& ctx) noexcept;
+
+/// Resolve node names to indices and each bed's cell to a mesh cell; locate
+/// `CELL AUTO` rows and (G-X2, `NODE_ENROLMENT AUTO`) enrol every node whose
+/// [COORDINATES] fall in a cell, appending to @p cfg.node_beds and @p names.
+/// @p node_xy_to_mesh converts node coordinates (project map units) into the
+/// mesh's coordinates (SI metres once the router has scaled it).
+/// Returns diagnostics; empty on success.
+std::vector resolveSubsurface(SimulationContext& ctx,
+                                           const MeshData& mesh,
+                                           SubsurfaceConfig& cfg,
+                                           std::vector& names,
+                                           double node_xy_to_mesh);
+
+/// G-X3 (2026-09-19): the length-weighted (conduit, cell) shares for every
+/// conduit with a [LOSSES] seepage rate whose polyline crosses the mesh
+/// (`LINK_SEEPAGE AUTO`). @p n_conduits receives how many conduits got at
+/// least one share. Same coordinate factor as resolveSubsurface.
+std::vector resolveLinkSeepage(SimulationContext& ctx,
+                                            const MeshData& mesh,
+                                            SubsurfaceConfig& cfg,
+                                            std::vector& link_names,
+                                            double node_xy_to_mesh,
+                                            int& n_conduits);
+
+/// Write the three sections back in the project's own units — that is, the
+/// authored values verbatim — omitting anything at its default so a
+/// round-trip with no edits adds nothing.
+void writeSubsurfaceSections(const SubsurfaceConfig& cfg,
+                             const std::vector& node_names,
+                             const std::vector& link_names,
+                             std::string& out);
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_SUBSURFACE_SECTIONS_HPP
diff --git a/src/engine/2d/subsurface/SubsurfaceSolver.cpp b/src/engine/2d/subsurface/SubsurfaceSolver.cpp
new file mode 100644
index 000000000..31ee2a4cd
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceSolver.cpp
@@ -0,0 +1,1657 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceSolver.cpp
+ * @brief The two-zone groundwater kernel (G-steps 3, 6-12, 14, 16).
+ *
+ * @section sy Specific yield — one derivation, three closures
+ *
+ * Write total water per unit area as `W = θ_s·h_g + S_col`, with `S_col` the
+ * unsaturated column's storage. Each closure gives the same shape:
+ *
+ * | closure | `S_col` | saturated equation |
+ * |---|---|---|
+ * | CLOSED_FORM | `hᵤ`, its own ODE | `θ_s·ḣ_g = q₀ + lat/A − deep − node/A` |
+ * | SIGMA       | `Σ θ_j·L·Δσ`      | `(θ_s − θ_bot)·ḣ_g = q₀_phys + …` |
+ * | ENSLAVED    | `hᵤ*(L)`, algebraic | `(θ_s − θ(ψ=L))·ḣ_g = q⁺ + …` |
+ *
+ * The SIGMA row is the one the plan text writes with `θ_s`. It is wrong by
+ * exactly the handover: the column's bottom flux is `f_bot = q₀_phys −
+ * θ_bot·L̇`, and `L̇ = −ḣ_g`, so `θ_s·ḣ_g = f_bot` rearranges to
+ * `(θ_s − θ_bot)·ḣ_g = q₀_phys`. Same equation, but only the second form can
+ * be written down without also tracking `f_bot`, and only the second form
+ * conserves once the column retains water above a falling table.
+ *
+ * ENSLAVED falls out of the same algebra: `S_col = hᵤ*(L)` gives
+ * `Ṡ_col = d(hᵤ*)/dL · L̇ = −θ(ψ=L)·ḣ_g`, since `d(hᵤ*)/dL = θ(L)` by the
+ * fundamental theorem. So the enslaved column contributes its top water
+ * content as a storage debit — no lag, no separate state, and `q⁺` drives the
+ * table directly. This is the reduction plan step 14 asks for, and it is one
+ * line of code rather than a separate branch of physics.
+ *
+ * @section split Why the split is ordered the way it is
+ *
+ * `fireCell` runs: q₀ → saturated update → clamp → column sweep at the
+ * CLAMPED `L̇` → apply the column's overflow/deficit → Dunne. Deriving `L̇`
+ * from the clamped `h_g` is what makes the clamp harmless: the column and the
+ * saturated zone always agree on how far the table actually moved, so no
+ * water is created at `h_g = z_s` or destroyed at `h_g = 0`.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SubsurfaceSolver.hpp"
+
+#include "../data/MeshData.hpp"
+#include "../data/SolverOptions2D.hpp"
+#include "../data/SurfaceStateData.hpp"
+#include "../solver/InertialEdges.hpp"
+#include "../gw/GwTransportData.hpp"   // T7.1
+#include "../../data/NodeData.hpp"
+
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+namespace {
+
+constexpr double kTiny     = 1.0e-12;
+/// Minimum drainable porosity. Guards `Sy` against a column that has
+/// saturated to `θ_s` at the table (which is physically where it should be —
+/// the specific yield genuinely vanishes there, and the table stops moving).
+constexpr double kSyFloor  = 1.0e-3;
+/// Availability share a single face may take of its donor cell per step —
+/// the surface solver's `exchange_beta` idiom, applied to Darcy.
+constexpr double kFaceShare = 0.5;
+/// G-X1: a column within this fraction of z_s of the ground is "saturated"
+/// for the node → aquifer guard.
+constexpr double kSatGuard  = 1.0e-4;
+
+double harmonic(double a, double b) noexcept {
+    if (a <= 0.0 || b <= 0.0) return 0.0;
+    return 2.0 * a * b / (a + b);
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// initialize
+// ---------------------------------------------------------------------------
+
+soil::Params SubsurfaceSolver::paramsOf(int i) const noexcept {
+    const auto u = static_cast(i);
+    soil::Params p;
+    p.law     = static_cast(state_.soil_char[u]);
+    p.Ks      = state_.Ks[u];
+    p.theta_s = state_.theta_s[u];
+    p.theta_r = state_.theta_r[u];
+    p.alpha   = state_.alpha[u];
+    p.psi_b   = state_.psi_b[u];
+    p.lambda  = state_.lambda[u];
+    p.vg_n    = state_.vg_n[u];
+    p.vg_L    = state_.vg_L[u];
+    return p;
+}
+
+void SubsurfaceSolver::resolveRows(const MeshData& mesh,
+                                   const GwUnitFactors& uf,
+                                   SubsurfaceConfig& cfg,
+                                   std::vector& warnings) {
+    // The authored config stays in the user's units for its whole life; SI
+    // exists only here, in the state. See GwUnitFactors' note — this split is
+    // what makes the writer a verbatim echo and double conversion
+    // unreachable.
+    const int n = state_.n_cells;
+
+    // `* < TAG < CELL` by scope, then by authored order within a scope — the
+    // same precedence the 2D infiltration and roughness sections use, so a
+    // user who has learned one has learned all of them.
+    for (int pass = 0; pass < 3; ++pass) {
+        for (const auto& r : cfg.rows) {
+            if (r.scope != pass) continue;
+            for (int i = 0; i < n; ++i) {
+                if (pass == 1) {
+                    if (i >= static_cast(mesh.tri_tag.size()) ||
+                        mesh.tri_tag[static_cast(i)] != r.tag)
+                        continue;
+                } else if (pass == 2) {
+                    if (r.cell != i) continue;
+                }
+                const auto u = static_cast(i);
+                state_.Ks[u]      = r.Ks * uf.rate;
+                state_.zs[u]      = r.zs * uf.length;
+                state_.theta_s[u] = r.theta_s;      // dimensionless
+                state_.theta_r[u] = r.theta_r;      // dimensionless
+                state_.alpha[u]   = r.alpha * uf.inv_len;
+                state_.psi_b[u]   = r.psi_b * uf.length;
+                state_.lambda[u]  = r.lambda;       // dimensionless
+                state_.vg_n[u]    = r.vg_n;         // dimensionless
+                state_.vg_L[u]    = r.vg_L;         // dimensionless
+                state_.c_loss[u]  = r.c_loss * uf.rate;
+                state_.soil_char[u] = static_cast(
+                    r.soil_char_set ? r.soil_char : options_.soil_char);
+                state_.closure[u] = static_cast(
+                    r.closure_set ? r.closure : options_.closure);
+                if (r.hg0 >= 0.0)
+                    state_.hg[u] = std::min(r.hg0 * uf.length, state_.zs[u]);
+            }
+        }
+    }
+
+    for (int i = 0; i < n; ++i) {
+        const auto u = static_cast(i);
+        state_.area[u] = (i < static_cast(mesh.tri_area.size()))
+                             ? mesh.tri_area[u] : 1.0;
+        const double zc = (i < static_cast(mesh.tri_cz.size()))
+                              ? mesh.tri_cz[u] : 0.0;
+        state_.z_bed[u] = zc - state_.zs[u];
+        if (state_.theta_r[u] >= state_.theta_s[u]) {
+            state_.theta_r[u] = 0.5 * state_.theta_s[u];
+            warnings.emplace_back(
+                "2D aquifer: THETA_R >= THETA_S on a cell; clamped to "
+                "THETA_S/2.");
+        }
+    }
+}
+
+void SubsurfaceSolver::resolveClosures(std::vector& warnings) {
+    // Step 6. AUTO reads the dimensionless group αL of the cell's INITIAL
+    // column. The thresholds are the plan's: a column that equilibrates far
+    // faster than the table moves is enslaved; one that does not equilibrate
+    // at all within the quasi-steady assumption gets the real column.
+    long n_ens = 0, n_cf = 0, n_sig = 0;
+    for (int i = 0; i < state_.n_cells; ++i) {
+        const auto u = static_cast(i);
+        auto c = static_cast(state_.closure[u]);
+        if (c == GwClosure::AUTO) {
+            const double L  = std::max(state_.zs[u] - state_.hg[u], kTiny);
+            const double aL = soil::alphaL(paramsOf(i), L);
+            if (aL < 1.0)                              c = GwClosure::ENSLAVED;
+            else if (aL < 5.0 || options_.force_closed_form)
+                                                       c = GwClosure::CLOSED_FORM;
+            else                                       c = GwClosure::SIGMA;
+            state_.closure[u] = static_cast(c);
+        }
+        switch (c) {
+            case GwClosure::ENSLAVED: ++n_ens; break;
+            case GwClosure::SIGMA:    ++n_sig; break;
+            default:                  ++n_cf;  break;
+        }
+    }
+    if (n_sig + n_cf + n_ens > 0) {
+        char buf[192];
+        std::snprintf(buf, sizeof buf,
+                      "2D aquifer closures resolved: %ld ENSLAVED, %ld "
+                      "CLOSED_FORM, %ld SIGMA.",
+                      n_ens, n_cf, n_sig);
+        warnings.emplace_back(buf);
+    }
+}
+
+std::string SubsurfaceSolver::initialize(const MeshData& mesh,
+                                         const InertialEdges& edges,
+                                         const SolverOptions2D& opts,
+                                         const GwUnitFactors& uf, int n_nodes,
+                                         SubsurfaceConfig& cfg,
+                                         std::vector& warnings) {
+    state_ = SubsurfaceState{};
+    if (cfg.empty()) return {};
+
+    options_   = cfg.options;
+    node_beds_ = cfg.node_beds;
+    mesh_  = &mesh;
+    edges_ = &edges;
+    opts_  = &opts;
+
+    const int n = mesh.n_cells();
+    if (n <= 0) return "2D aquifer: [2D_AQUIFER] authored but the mesh is empty.";
+    if (options_.m_layers < 2 || options_.m_layers > 128)
+        return "2D aquifer: M_LAYERS must be in [2, 128].";
+
+    state_.resize(n, options_.m_layers);
+    resolveRows(mesh, uf, cfg, warnings);
+    resolveClosures(warnings);
+
+    // Seed each closure-B column to hydrostatic equilibrium above its table.
+    // Closure A's `hu` gets the same equilibrium, so the two closures start
+    // from the identical water content and the closure-ladder benchmark
+    // (step 18) compares trajectories, not initial conditions.
+    for (int i = 0; i < n; ++i) {
+        const auto u = static_cast(i);
+        const double L = std::max(state_.zs[u] - state_.hg[u], 0.0);
+        const soil::Params p = paramsOf(i);
+        if (static_cast(state_.closure[u]) == GwClosure::SIGMA) {
+            sigma::seedHydrostatic(p, &state_.theta_sigma[u], state_.m_layers,
+                                   n, L);
+            state_.hu[u] = sigma::columnStorage(&state_.theta_sigma[u],
+                                                state_.m_layers, n, L);
+        } else {
+            state_.hu[u] = soil::equilibriumStorage(p, L);
+        }
+    }
+
+    // Lateral topology. PER_SUBCATCH has none — degenerate cells, zero
+    // lateral flux, and the identical code path everywhere else (§8).
+    const int ne = options_.per_subcatch ? 0 : edges.ne;
+    state_.eacc_L.assign(static_cast(ne), 0.0);
+    state_.eacc_R.assign(static_cast(ne), 0.0);
+    face_tier_.assign(static_cast(ne), 0);
+    cell_nface_.assign(static_cast(n), 0);
+    if (ne > 0 && static_cast(edges.cell_ptr.size()) == n + 1) {
+        for (int i = 0; i < n; ++i)
+            cell_nface_[static_cast(i)] =
+                edges.cell_ptr[static_cast(i) + 1] -
+                edges.cell_ptr[static_cast(i)];
+    }
+
+    // Node beds: resolve each coupled node onto its containing cell. A bed
+    // authored for a node outside the mesh is a warning, not an error — the
+    // 1D node keeps working, it simply has no aquifer under it.
+    state_.nacc.assign(node_beds_.size(), 0.0);
+    bed_exchange_cum_.assign(node_beds_.size(), 0.0);   // G-O
+    bed_gathered_.assign(node_beds_.size(), 0.0);       // T7.4
+    node_exchange_vol_.assign(static_cast(std::max(0, n_nodes)),
+                              0.0);
+    node_drawn_gw_ = node_exchange_vol_;                // G-X1
+    drain_cap_binds_ = 0;                               // G-W1b
+    node_refunds_    = 0;                               // G-W1b
+    {
+        // `node_beds_` is the solver's own copy, so converting it in place
+        // leaves the authored config — and therefore the writer — untouched.
+        for (auto& b : node_beds_) {
+            if (!b.exchange) { b.cell = -1; continue; }   // G-X2: opted out
+            if (b.cell < 0 || b.cell >= n) {
+                b.cell = -1;
+                warnings.emplace_back(
+                    "2D aquifer: [2D_AQUIFER_NODE] row has no containing mesh "
+                    "cell; the node exchanges with nothing.");
+                continue;
+            }
+            b.Kc   *= uf.rate;
+            b.dC   *= uf.length;
+            b.area *= uf.area;
+            if (b.area <= 0.0)
+                b.area = state_.area[static_cast(b.cell)];
+        }
+    }
+
+    pending_flag_.assign(static_cast(n), 0);
+    pending_surface_.clear();
+    accumulators_pending_ = false;
+    state_.active = true;
+    // Seed the tier lists so the kernel is usable BEFORE the first
+    // syncAndRebuild. dt0 is not known yet, so everything starts on the
+    // finest rung — conservative, and it means a solver that is initialized
+    // and then immediately marched does physics rather than silently nothing.
+    // (It silently did nothing, and gates 6 and 7 are what said so.)
+    assignTiers(0.0, std::clamp(opts.lts_tiers, 1, 8));
+    state_.led_init_storage = state_.storage();
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// stability and tiering (steps 10, 11)
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::refreshDtCell(const MeshData& mesh,
+                                     const InertialEdges& edges) {
+    if (!state_.active) return;
+    const int n  = state_.n_cells;
+    const int ne = static_cast(state_.eacc_L.size());
+    const bool has_lat = ne > 0 &&
+                         static_cast(edges.cell_ptr.size()) == n + 1;
+
+    for (int i = 0; i < n; ++i) {
+        const auto u = static_cast(i);
+        const double A  = std::max(state_.area[u], kTiny);
+        const double zs = state_.zs[u];
+        const double L  = std::max(zs - state_.hg[u], kTiny);
+        const soil::Params p = paramsOf(i);
+
+        // --- Δt_g: explicit diffusion on the saturated head ---------------
+        // A cell's transmissivity sum over its faces; the drainable storage
+        // A·Sy is the capacitance. `T` uses the WETTER of the pair with a
+        // floor, so an empty aquifer does not report an infinite step and
+        // then take one.
+        double sumT = 0.0;
+        if (has_lat) {
+            const int b0 = edges.cell_ptr[u];
+            const int b1 = edges.cell_ptr[u + 1];
+            for (int k = b0; k < b1; ++k) {
+                const int e = edges.cell_edge[static_cast(k)];
+                const auto eu = static_cast(e);
+                const int  j  = (edges.cL[eu] == i) ? edges.cR[eu] : edges.cL[eu];
+                const auto ju = static_cast(j);
+                const double Ke = harmonic(state_.Ks[u], state_.Ks[ju]);
+                const double Te = std::max({state_.hg[u], state_.hg[ju],
+                                            0.01 * zs});
+                sumT += Ke * Te * edges.xi[eu] * edges.inv_dx[eu];
+            }
+        }
+        // Deep loss is a linear sink with rate c_loss/z_s; the node exchange
+        // conductance is folded in where a bed sits on this cell.
+        double lin = state_.c_loss[u] / std::max(zs, kTiny) * A;
+        for (const auto& b : node_beds_) {
+            if (b.cell != i) continue;
+            lin += (b.Kc > 0.0 && b.dC > 0.0)
+                       ? b.Kc * b.area / b.dC
+                       : state_.Ks[u] * b.area / std::max(0.5 * zs, kTiny);
+        }
+        const double Sy  = std::max(state_.theta_s[u] - state_.theta_r[u],
+                                    kSyFloor);
+        const double den = sumT + lin;
+        double dt_g = 1.0e30;
+        if (den > kTiny) dt_g = options_.c_gw * A * Sy / den;
+
+        // --- Δt_u: the column's own bound --------------------------------
+        double dt_u = 1.0e30;
+        const auto cl = static_cast(state_.closure[u]);
+        if (cl == GwClosure::SIGMA) {
+            // L̇ is unknown before the step; use the previous firing's table
+            // velocity implied by q0_last, which is the term that actually
+            // drives it.
+            const double Ldot = -state_.q0_last[u] / Sy;
+            dt_u = sigma::columnDtLimit(p, &state_.theta_sigma[u],
+                                        state_.m_layers, n, L, Ldot,
+                                        options_.c_col,
+                                        options_.capillary_diff);
+        } else if (cl == GwClosure::CLOSED_FORM) {
+            // The closed form is a relaxation ẏ = −C·(y − y*); its stiffness
+            // is C = −∂q₀/∂hᵤ. Taken numerically so every soil law is
+            // covered by one expression rather than four differentiations.
+            const double hu = state_.hu[u];
+            const double d  = std::max(1.0e-6 * std::max(hu, 1.0e-3), 1.0e-9);
+            const double C  = (soil::rechargeQ0(p, L, hu) -
+                               soil::rechargeQ0(p, L, hu + d)) / d;
+            if (C > kTiny) dt_u = options_.c_col / C;
+        }
+        // ENSLAVED has no unsaturated state, so no unsaturated step bound —
+        // that is the whole point of the reduction.
+
+        state_.dt_cell[u] = std::min(dt_g, dt_u);
+    }
+}
+
+int SubsurfaceSolver::requiredTiers(double dt0) const noexcept {
+    if (!state_.active || dt0 <= 0.0) return 1;
+    double dtmax = dt0;
+    for (int i = 0; i < state_.n_cells; ++i)
+        dtmax = std::max(dtmax, state_.dt_cell[static_cast(i)]);
+    if (!std::isfinite(dtmax) || dtmax <= dt0) return 1;
+    // K such that 2^(K−1)·dt0 >= dt_max.
+    const int k = static_cast(std::ceil(std::log2(dtmax / dt0))) + 1;
+    return std::max(1, k);
+}
+
+void SubsurfaceSolver::assignTiers(double dt0, int n_tiers) {
+    if (!state_.active) return;
+    const int K = std::max(1, n_tiers);
+    cells_by_tier_.assign(static_cast(K), {});
+    faces_by_tier_.assign(static_cast(K), {});
+    tier_firings_.assign(static_cast(K), 0);
+
+    for (int i = 0; i < state_.n_cells; ++i) {
+        const auto u = static_cast(i);
+        int t = 0;
+        if (dt0 > 0.0 && std::isfinite(state_.dt_cell[u])) {
+            const double ratio = state_.dt_cell[u] / dt0;
+            // std::ilogb(ratio) is exactly floor(log2(ratio)) for finite
+            // positive ratios and is what the surface marcher uses — the two
+            // ladders must agree on the arithmetic or a cell can sit one rung
+            // off its twin for no physical reason.
+            t = (ratio >= 1.0) ? std::ilogb(ratio) : 0;
+        }
+        // G-A: the tier is `min(Δt_g, Δt_u)` and nothing else. A cell with
+        // node exchange, infiltration or Dunne is NOT pinned to tier 0 — the
+        // cross-domain volume accumulates and is gathered when this cell
+        // fires. Pinning is the surface twin's business.
+        t = std::clamp(t, 0, K - 1);
+        state_.tier[u] = static_cast(t);
+        cells_by_tier_[static_cast(t)].push_back(i);
+    }
+
+    // A face fires at the FINER of its two cells — the standard LTS face
+    // rule. The finer cell then gathers a full-cadence flux and the coarser
+    // one gathers the accumulated sum, which is where G-B's ±Δ pair earns
+    // its keep.
+    const int ne = static_cast(state_.eacc_L.size());
+    for (int e = 0; e < ne; ++e) {
+        const auto eu = static_cast(e);
+        const int tL = state_.tier[static_cast(edges_->cL[eu])];
+        const int tR = state_.tier[static_cast(edges_->cR[eu])];
+        const int t  = std::min(tL, tR);
+        face_tier_[eu] = static_cast(t);
+        faces_by_tier_[static_cast(t)].push_back(e);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// lateral Darcy (step 9)
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::fireGwFaces(int tier, double dt) {
+    if (!state_.active || !tierHasFaces(tier)) return;
+    const auto& list = faces_by_tier_[static_cast(tier)];
+    const InertialEdges& E = *edges_;
+
+    for (const int e : list) {
+        const auto eu = static_cast(e);
+        const auto l  = static_cast(E.cL[eu]);
+        const auto r  = static_cast(E.cR[eu]);
+
+        const double HL = state_.z_bed[l] + state_.hg[l];
+        const double HR = state_.z_bed[r] + state_.hg[r];
+        const double dH = HL - HR;
+        if (dH == 0.0) continue;
+
+        // Upwind transmissivity: the DONOR cell's saturated thickness. Using
+        // the mean here is the classic way to make a drying aquifer pump
+        // water it does not have.
+        const std::size_t don = (dH > 0.0) ? l : r;
+        const double T = state_.hg[don];
+        if (T <= kTiny) continue;
+
+        const double K = harmonic(state_.Ks[l], state_.Ks[r]);
+        if (K <= 0.0) continue;
+
+        double Q = K * T * E.xi[eu] * E.inv_dx[eu] * dH;   // m³/s, + is L→R
+
+        // Positivity: no face may take more than its share of the donor's
+        // drainable water in one step. The share is split across the donor's
+        // own faces so a cell with many wet neighbours cannot be emptied
+        // several times over within one firing.
+        const double Sy = std::max(state_.theta_s[don] - state_.theta_r[don],
+                                   kSyFloor);
+        const int nf = std::max(1, cell_nface_[don]);
+        const double cap = kFaceShare * T * Sy * state_.area[don] /
+                           (static_cast(nf) * std::max(dt, kTiny));
+        if (std::abs(Q) > cap) Q = (Q > 0.0) ? cap : -cap;
+
+        const double vol = Q * dt;
+        state_.eacc_L[eu] -= vol;   // leaves cL
+        state_.eacc_R[eu] += vol;   // enters cR
+
+        // T7.1: the tuple rides the same water, at the DONOR's saturated
+        // concentration — the upwind rule the transmissivity above already
+        // chose, so mass and water never disagree about which cell exported.
+        // T7.2 adds the dispersive term below, on the same face, into the
+        // same accumulators, at the same cadence.
+        if (tr_.active() && vol != 0.0) {
+            const double vd = satVolume(static_cast(don));
+            if (vd > 0.0) {
+                const auto ne = static_cast(E.ne);
+                for (int s = 0; s < tr_.n_species; ++s) {
+                    const double m_don = tr_.sat_mass[tr_.idx(s, static_cast(don))];
+                    if (m_don == 0.0) continue;
+                    // T7.2: only the DISSOLVED share travels — what is
+                    // sorbed on the grains stays with the cell. That single
+                    // multiplier is the whole of retardation here, which is
+                    // why no channel carries an R of its own.
+                    const double mob =
+                        tr_.dissolvedFraction(s, static_cast(don),
+                                              state_.theta_s[don]);
+                    double dm = std::abs(vol) * (m_don / vd) * mob;
+                    // Never export more than the donor holds (the water's
+                    // own positivity share bounds the volume the same way);
+                    // the signed temperature row has no floor.
+                    if (!tr_.signedRow(s) && dm > std::abs(m_don))
+                        dm = std::abs(m_don);
+                    const double sgn = (vol > 0.0) ? 1.0 : -1.0;
+                    const auto k = static_cast(s) * ne + eu;
+                    tr_.sacc_L[k] -= sgn * dm;
+                    tr_.sacc_R[k] += sgn * dm;
+                }
+            }
+        }
+
+        // T7.2: hydrodynamic dispersion, D = α_L·|v| + D_m with the pore
+        // velocity v = Q/(θ_s·h_g·B). Booked on the SAME face into the SAME
+        // accumulators as the advective term above, so it inherits the
+        // marcher's tier consistency rather than needing its own argument —
+        // the surface's §S2 rule, and the reason the limiter below mirrors
+        // the surface's limiter down to the 1/nf composition bound.
+        if (tr_.active() && tr_.dispersion_on) {
+            const double Ta = state_.hg[l], Tb = state_.hg[r];
+            const double va = satVolume(static_cast(l));
+            const double vb = satVolume(static_cast(r));
+            if (Ta > kTiny && Tb > kTiny && va > 0.0 && vb > 0.0) {
+                const double hbar = 0.5 * (Ta + Tb);
+                const double B    = E.xi[eu];              // face width (m)
+                const double thet = 0.5 * (state_.theta_s[l] + state_.theta_s[r]);
+                // Pore velocity across this face, from the advective Q the
+                // block above already computed.
+                const double area_f = std::max(thet * hbar * B, kTiny);
+                const double vpore  = std::abs(Q) / area_f;
+                const double alpha  = 0.5 * (tr_.alpha_L[l] + tr_.alpha_L[r]);
+                const double Dm     = 0.5 * (tr_.D_m[l] + tr_.D_m[r]);
+                const double D      = alpha * vpore + Dm;
+                if (D > 0.0) {
+                    // Exchanged volume-equivalent: D·(θ·h̄·B)·dt/d.
+                    const double cond = D * area_f * E.inv_dx[eu] * dt;
+                    const auto ne = static_cast(E.ne);
+                    const int nf_r = std::max(1, cell_nface_[r]);
+                    const int nf_l = std::max(1, cell_nface_[l]);
+                    for (int s = 0; s < tr_.n_species; ++s) {
+                        const double ma = tr_.sat_mass[tr_.idx(s, static_cast(l))];
+                        const double mb = tr_.sat_mass[tr_.idx(s, static_cast(r))];
+                        const double ca = ma / va *
+                            tr_.dissolvedFraction(s, static_cast(l), state_.theta_s[l]);
+                        const double cb = mb / vb *
+                            tr_.dissolvedFraction(s, static_cast(r), state_.theta_s[r]);
+                        double dMd = cond * (ca - cb);      // + = l → r
+                        if (dMd == 0.0) continue;
+                        // The pairwise equalisation bound, divided by the
+                        // RECEIVER's face count: pairwise bounds do not
+                        // compose, and a cell fed by several faces each
+                        // closing its whole gap can end richer than every
+                        // donor. The surface proved this the hard way
+                        // (its own comment records 15.31 against a max of
+                        // 10); the same 1/nf argument holds here.
+                        const std::size_t recv = (dMd > 0.0) ? r : l;
+                        const double eq = (ca - cb) * va * vb / (va + vb) /
+                                          static_cast((dMd > 0.0) ? nf_r : nf_l);
+                        double cap = std::abs(eq);
+                        // …and a positivity share of the giver's mass. The
+                        // SIGNED temperature row has no positivity to
+                        // guard and would bind every exchange across a
+                        // warm/cold front, so for it the equalisation
+                        // bound alone is the cap.
+                        if (!tr_.signedRow(s)) {
+                            const double give = std::abs((dMd > 0.0) ? ma : mb) * kFaceShare;
+                            cap = std::min(cap, give);
+                        }
+                        if (std::abs(dMd) > cap) {
+                            dMd = (dMd > 0.0) ? cap : -cap;
+                            ++tr_.dispersion_limiter_binds;
+                        }
+                        const auto k = static_cast(s) * ne + eu;
+                        tr_.sacc_L[k] -= dMd;
+                        tr_.sacc_R[k] += dMd;
+                    }
+                }
+            }
+        }
+    }
+    accumulators_pending_ = true;
+}
+
+double SubsurfaceSolver::gatherLateralMass(int i, int s) noexcept {
+    if (tr_.sacc_L.empty() || edges_ == nullptr) return 0.0;
+    const InertialEdges& E = *edges_;
+    const auto u = static_cast(i);
+    if (u + 1 >= E.cell_ptr.size()) return 0.0;
+    const auto ne = static_cast(E.ne);
+    double m = 0.0;
+    const int b0 = E.cell_ptr[u];
+    const int b1 = E.cell_ptr[u + 1];
+    for (int k = b0; k < b1; ++k) {
+        const auto ku = static_cast(k);
+        const auto eu = static_cast(E.cell_edge[ku]);
+        const auto j  = static_cast(s) * ne + eu;
+        if (E.cell_sign[ku] > 0) { m += tr_.sacc_L[j]; tr_.sacc_L[j] = 0.0; }
+        else                     { m += tr_.sacc_R[j]; tr_.sacc_R[j] = 0.0; }
+    }
+    return m;
+}
+
+double SubsurfaceSolver::gatherLateral(int i) noexcept {
+    if (state_.eacc_L.empty()) return 0.0;
+    const InertialEdges& E = *edges_;
+    const auto u = static_cast(i);
+    if (u + 1 >= E.cell_ptr.size()) return 0.0;
+    double v = 0.0;
+    const int b0 = E.cell_ptr[u];
+    const int b1 = E.cell_ptr[u + 1];
+    for (int k = b0; k < b1; ++k) {
+        const auto ku = static_cast(k);
+        const auto eu = static_cast(E.cell_edge[ku]);
+        if (E.cell_sign[ku] > 0) { v += state_.eacc_L[eu]; state_.eacc_L[eu] = 0.0; }
+        else                     { v += state_.eacc_R[eu]; state_.eacc_R[eu] = 0.0; }
+    }
+    return v;
+}
+
+// ---------------------------------------------------------------------------
+// node exchange (step 8)
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::resetNodeExchangeVolumes() noexcept {
+    std::fill(node_exchange_vol_.begin(), node_exchange_vol_.end(), 0.0);
+    std::fill(node_drawn_gw_.begin(), node_drawn_gw_.end(), 0.0);   // G-X1
+}
+
+void SubsurfaceSolver::sampleNodeExchange(const NodeData* nodes, double dt) {
+    if (!state_.active || node_beds_.empty() || nodes == nullptr) return;
+    const double l12 = opts_ ? opts_->len_1d_to_2d : 1.0;
+
+    for (std::size_t b = 0; b < node_beds_.size(); ++b) {
+        const auto& bed = node_beds_[b];
+        if (bed.cell < 0) continue;
+        const auto ni = static_cast(bed.node);
+        if (ni >= nodes->invert_elev.size()) continue;
+        const auto ci = static_cast(bed.cell);
+
+        // 1D heads are project units; the 2D module is metres throughout.
+        const double h_pipe = (nodes->invert_elev[ni] + nodes->depth[ni]) * l12;
+        const double h_gw   = state_.z_bed[ci] + state_.hg[ci];
+
+        // MODFLOW-River conductance. With a semi-confining bed the bed
+        // dominates (config b); without one the aquifer's own conductivity
+        // over half the soil column is the characteristic path (config a).
+        const double cond = (bed.Kc > 0.0 && bed.dC > 0.0)
+            ? bed.Kc * bed.area / bed.dC
+            : state_.Ks[ci] * bed.area /
+                  std::max(0.5 * state_.zs[ci], kTiny);
+
+        double Q = cond * (h_gw - h_pipe);   // m³/s, + out of the aquifer
+        const double Sy = std::max(
+            state_.theta_s[ci] - state_.theta_r[ci], kSyFloor);
+        if (Q > 0.0) {
+            // Cap an aquifer→pipe drain at the cell's drainable water.
+            //
+            // G-W1 (2026-09-22): against the SAME specific yield the column
+            // will spend it against. This used the textbook θ_s − θ_r while
+            // the column used the floored θ_s − θ_bot; for a table a few
+            // centimetres under the ground those are 0.35 and 0.001, so the
+            // cap sat 350× above anything reachable and never bound. The
+            // column then went short on essentially every firing and the
+            // shortfall was refunded (fireCell §2) into the AQUIFER's books
+            // alone — the router had already handed the unrefunded volume to
+            // the node. Both ledgers closed and the seam still created water:
+            // 0.625 m³ delivered against 0.067 m³ released on the gate deck,
+            // 89 % of it refunded. With the two agreeing, the refund path no
+            // longer fires for the node at all (measured: 0 refunds, and
+            // still 0 across three closures and five geometries).
+            //
+            // The FILL direction below keeps θ_s − θ_r, and that is a
+            // decision rather than an oversight — see the handoff §3. Two
+            // attempts to make it consistent too both regressed G-X1's
+            // `FloodedManholeRechargesUntilTheColumnIsFullThenStops`: the
+            // floored yield leaves a saturated column claiming 1e-3 of
+            // headroom it does not have (a 3.15e-5 m³/s trickle into a full
+            // column — the ping-pong G-X1's guard exists to stop), and the
+            // unfloored one takes the bed-only deck's continuity from
+            // −0.66 % to −1.99 %. The measured leak was on the drain side;
+            // the fill side needs its own round.
+            const double Sy_col = specificYield(
+                ci, paramsOf(bed.cell), state_.theta_s[ci],
+                std::max(state_.zs[ci] - state_.hg[ci], 0.0),
+                static_cast(state_.closure[ci]), nullptr);
+            const double avail = state_.hg[ci] * Sy_col * state_.area[ci];
+            // G-W1b (2026-09-23): count the firings this cap actually
+            // CLAMPS. A gate needs to prove its own deck exercises the cap
+            // before it can claim anything from the deck's numbers, and the
+            // ratio between the two yields does not tell it that: a deck
+            // whose ratio is 56.8× was measured BIT-IDENTICAL with the
+            // defect present, because `avail` at h_g = 7.6 m is enormous
+            // under either yield and the cap never binds. What binds is
+            // `avail` being small in ABSOLUTE terms, which only the clamp
+            // itself knows. No threshold to tune, and no geometry can make
+            // this lie.
+            const double cap = kFaceShare * avail / std::max(dt, kTiny);
+            if (Q > cap) {
+                Q = cap;
+                ++drain_cap_binds_;
+            }
+        } else if (Q < 0.0) {
+            // G-X1 (2026-09-19): node → aquifer, the direction that was
+            // uncapped. (i) Saturation guard: a column whose table is at the
+            // ground takes nothing — water it accepted here would come
+            // straight back as Dunne excess in the same firing, and the
+            // one-step lag between the frozen node head and the delivery
+            // would ping-pong it (program plan §B.4b). (ii) Headroom: the
+            // saturated zone can hold (z_s − h_g)·Sy·A, taken in the same
+            // per-step share as the drain side so a step cannot fill it
+            // more than once. (iii) The node's own water: what it holds
+            // (frozen for the batch, so the batch as a whole may not draw
+            // more than that — `node_drawn_gw_`, the surface's `node_drawn_`
+            // rule) plus what flows through it — a junction stores nothing
+            // below its rim (legacy: junction volume is ponding only) but
+            // can lose water at the rate it is fed.
+            const double L = state_.zs[ci] - state_.hg[ci];
+            if (L <= kSatGuard * state_.zs[ci]) {
+                Q = 0.0;
+            } else {
+                const double headroom = L * Sy * state_.area[ci];
+                double cap = kFaceShare * headroom / std::max(dt, kTiny);
+                const double v12 = opts_ ? opts_->vol_1d_to_2d : 1.0;
+                const double held = (ni < nodes->volume.size())
+                    ? std::max(0.0, nodes->volume[ni]) * v12 : 0.0;
+                const double drawn = (ni < node_drawn_gw_.size())
+                    ? node_drawn_gw_[ni] : 0.0;
+                const double through = (ni < nodes->inflow.size())
+                    ? std::max(0.0, nodes->inflow[ni]) * v12 : 0.0;
+                cap = std::min(cap, std::max(0.0, held - drawn) /
+                                        std::max(dt, kTiny) + through);
+                Q = std::max(Q, -cap);
+                if (ni < node_drawn_gw_.size())
+                    node_drawn_gw_[ni] += std::min(-Q * dt, std::max(0.0, held - drawn));
+            }
+        }
+        if (Q == 0.0) continue;
+
+        const double vol = Q * dt;
+        // T7.4: a node pushing water DOWN its bed (Q < 0) sends its own
+        // quality with it. The row layout is shared with the 1D (both come
+        // from TransportPolicy), so row s means the same species on both
+        // sides and no mapping is needed — only the unit factor the volume
+        // already takes. The aquifer→node direction is booked at the CELL's
+        // firing instead, where the cell's concentration is known.
+        if (tr_.active() && vol < 0.0 && node_row_conc_ != nullptr &&
+            node_row_ns_ == tr_.n_species) {
+            const double vol_1d_to_2d = opts_ ? opts_->vol_1d_to_2d : 1.0;
+            const double v_1d = -vol / std::max(vol_1d_to_2d, kTiny);  // 1D volume units
+            const auto nb = node_beds_.size();
+            for (int sp = 0; sp < tr_.n_species; ++sp) {
+                const double c = node_row_conc_[ni * static_cast(node_row_ns_) +
+                                                static_cast(sp)];
+                if (c == 0.0) continue;
+                tr_.nacc_mass[static_cast(sp) * nb + b] += v_1d * c;
+            }
+        }
+        state_.nacc[b] += vol;                       // gathered at the GW firing
+        bed_exchange_cum_[b] += vol;                 // G-O: the per-bed series
+        if (ni < node_exchange_vol_.size())
+            node_exchange_vol_[ni] += vol;           // flushed by the router
+    }
+    accumulators_pending_ = true;
+}
+
+double SubsurfaceSolver::gatherNodeMass(int i, int s) noexcept {
+    if (tr_.nacc_mass.empty()) return 0.0;
+    const auto nb = node_beds_.size();
+    double m = 0.0;
+    for (std::size_t b = 0; b < nb; ++b) {
+        if (node_beds_[b].cell != i) continue;
+        const auto k = static_cast(s) * nb + b;
+        m += tr_.nacc_mass[k];
+        tr_.nacc_mass[k] = 0.0;
+    }
+    return m;
+}
+
+void SubsurfaceSolver::bookLinkSeepageMass(int cell, int species,
+                                           double mass) noexcept {
+    if (!tr_.active() || mass == 0.0) return;
+    if (cell < 0 || cell >= tr_.n_cells) return;
+    if (species < 0 || species >= tr_.n_species) return;
+    tr_.lacc_mass[tr_.idx(species, cell)] += mass;
+}
+
+// G-W1 (2026-09-21): the single owner of specific yield.
+//
+// `Sy` is the storage coefficient every saturated source spends against, so
+// a withdrawal CAPPED against `h_g·Sy·A` and then SPENT against `Sy·A` must
+// use the same `Sy` or the cap does not bind. It did not: `sampleNodeExchange`
+// used the textbook θ_s − θ_r while the column used the floored θ_s − θ_bot,
+// which for a table a few centimetres under the ground sits on `kSyFloor` —
+// 0.35 against 0.001, a factor of 350. The cap was therefore never reached,
+// the column went short on essentially every firing, and the shortfall was
+// refunded (fireCell §2's clamp) into the aquifer's OWN books only. The 1D
+// had already been handed the unrefunded volume by the router, so the
+// aquifer's continuity closed to 0.000 % while the node received water the
+// aquifer never released: 0.625 m³ delivered against 0.067 m³ given up on
+// the G-W1 gate deck, 89 % of it refunded.
+//
+// One function, so the cap and the spend cannot disagree again. `theta_bot`
+// is reported back because the CLOSED_FORM branch pairs the handover slab
+// with the `Sy` actually used (G-X4) and SIGMA's recharge flux needs the
+// bottom layer's content.
+double SubsurfaceSolver::specificYield(std::size_t u, const soil::Params& p,
+                                       double ts, double L0, GwClosure cl,
+                                       double* theta_bot_out) const noexcept {
+    double theta_bot = state_.theta_r[u];
+    double Sy = std::max(ts - theta_bot, kSyFloor);
+    if (cl == GwClosure::SIGMA) {
+        const auto n = static_cast(state_.n_cells);
+        const auto bot =
+            static_cast(state_.m_layers - 1) * n + u;
+        if (bot < state_.theta_sigma.size()) {
+            theta_bot = state_.theta_sigma[bot];
+            // The plan writes θ_s here. See the file header: with the
+            // handover explicit, θ_s − θ_bot is what conserves, and it IS
+            // specific yield.
+            Sy = std::max(ts - theta_bot, kSyFloor);
+        }
+    } else if (cl == GwClosure::ENSLAVED) {
+        // hᵤ = hᵤ*(L) algebraically ⇒ the storage debit is θ(ψ=L), the
+        // equilibrium water content at the SURFACE. `q⁺` then drives the
+        // table with no unsaturated lag at all.
+        Sy = std::max(ts - soil::waterContent(p, L0), kSyFloor);
+    } else {
+        // CONSISTENCY, not taste: `Sy` and the handover slab content the
+        // column pairs with it must sum to θ_s, or the two zones disagree
+        // about how much water a moving table carries and the cell leaks at
+        // a rate proportional to |ḣ_g|. The bulk store's own mean content is
+        // the self-consistent choice — and it reduces to the textbook
+        // θ_s − θ_r once the column has drained.
+        theta_bot = std::clamp(state_.hu[u] / std::max(L0, kTiny),
+                               state_.theta_r[u], ts);
+        Sy = std::max(ts - theta_bot, kSyFloor);
+    }
+    if (theta_bot_out != nullptr) *theta_bot_out = theta_bot;
+    return Sy;
+}
+
+double SubsurfaceSolver::specificYieldOf(int cell) const noexcept {
+    const auto u = static_cast(cell);
+    if (u >= state_.hg.size()) return 0.0;
+    return specificYield(u, paramsOf(cell), state_.theta_s[u],
+                         std::max(state_.zs[u] - state_.hg[u], 0.0),
+                         static_cast(state_.closure[u]), nullptr);
+}
+
+double SubsurfaceSolver::gatherNode(int i) noexcept {
+    double v = 0.0;
+    // T7.4 fix (2026-09-21): the per-bed split weights are the volumes THIS
+    // gather takes, recorded here. They were previously accumulated across a
+    // routing step and cleared at its flush — but a cell fires on the LTS
+    // ladder, not the routing step, so any firing whose weights had already
+    // been cleared found `drew == 0` and dropped its outgoing mass on the
+    // floor. The aquifer still booked `lost_node`, so the mass left the
+    // aquifer's books and never reached the node's: 75 % of it on the gate
+    // deck. Tying the weights to the gather makes them exact by
+    // construction, because they ARE the volumes that produced this
+    // firing's `node_out`.
+    std::fill(bed_gathered_.begin(), bed_gathered_.end(), 0.0);
+    for (std::size_t b = 0; b < node_beds_.size(); ++b) {
+        if (node_beds_[b].cell != i) continue;
+        if (b < bed_gathered_.size()) bed_gathered_[b] = state_.nacc[b];
+        v += state_.nacc[b];
+        state_.nacc[b] = 0.0;
+    }
+    return v;
+}
+
+// ---------------------------------------------------------------------------
+// T7.1 — the transported tuple
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::initTransport(const RowLayoutLite& rows,
+                                     const GwTransportData* gw,
+                                     const std::vector& pollut_decay,
+                                     std::vector& warnings) {
+    tr_.clear();
+    if (!state_.active || rows.n_species <= 0) return;
+    const int ne = options_.per_subcatch ? 0
+                                         : (edges_ ? edges_->ne : 0);
+    tr_.resize(rows.n_species, state_.n_cells, ne);
+    // T7.4: the two 1D seams' accumulators, sized against the bed and node
+    // counts the water side already uses.
+    tr_.nacc_mass.assign(static_cast(rows.n_species) *
+                             node_beds_.size(), 0.0);
+    tr_.node_out_mass.assign(static_cast(rows.n_species) *
+                                 node_exchange_vol_.size(), 0.0);
+    tr_.n_pollut  = rows.n_pollut;
+    tr_.n_msx     = rows.n_msx;
+    tr_.age_row   = rows.age_row;
+    tr_.temp_row  = rows.temp_row;
+    tr_.row_names = rows.names;
+
+    // Seed both stores from `[GW_INITIAL_QUALITY]`. A row is a
+    // CONCENTRATION; the mass it seeds is that concentration times the
+    // zone's water volume, so a cell whose table starts at zero starts with
+    // no saturated mass however the row is written.
+    if (gw != nullptr) {
+        for (const auto& r : gw->initial_quality) {
+            const int s = tr_.rowIndex(r.species);
+            if (s < 0) continue;   // resolveGwTransport already warned
+            for (int i = 0; i < state_.n_cells; ++i) {
+                if (r.scope == GwScope::CELL && r.cell != i) continue;
+                if (r.scope == GwScope::TAG &&
+                    (mesh_ == nullptr ||
+                     i >= static_cast(mesh_->tri_tag.size()) ||
+                     mesh_->tri_tag[static_cast(i)] != r.tag))
+                    continue;
+                const double v = (r.zone == GwZone::SAT) ? satVolume(i)
+                                                         : unsatVolume(i);
+                if (!(v > 0.0)) continue;
+                auto& store = (r.zone == GwZone::SAT) ? tr_.sat_mass
+                                                      : tr_.unsat_mass;
+                store[tr_.idx(s, i)] = r.value * v;
+            }
+        }
+        // LAYER rows address a closure-B σ layer, which T7.1 does not carry
+        // (the unsaturated store is bulk — see SubsurfaceTransportState's
+        // header). Say so once rather than seeding them into the wrong
+        // place or dropping them silently.
+        bool any_layer = false;
+        for (const auto& r : gw->initial_quality)
+            if (r.zone == GwZone::LAYER) { any_layer = true; break; }
+        if (any_layer)
+            warnings.emplace_back(
+                "[GW_INITIAL_QUALITY] LAYER rows were not applied: the "
+                "unsaturated store is bulk in this release (per-layer "
+                "transport is a later phase). Use ZONE UNSAT to seed the "
+                "whole column.");
+    }
+    // T7.2: resolve `[GW_TRANSPORT_PARAMS]` and `[GW_SORPTION]` onto cells,
+    // `* < TAG < CELL` by pass — the same precedence the `[2D_AQUIFER]`
+    // rows use, so one deck's two aquifer sections behave the same way.
+    if (gw != nullptr) {
+        tr_.dispersion_on = gw->options.dispersion;
+        for (int i = 0; i < state_.n_cells; ++i) {
+            const auto u = static_cast(i);
+            tr_.rho_b[u] = 2650.0 * (1.0 - state_.theta_s[u]);
+        }
+        for (int pass = 0; pass < 3; ++pass) {
+            for (const auto& r : gw->params) {
+                if (static_cast(r.scope) != pass) continue;
+                for (int i = 0; i < state_.n_cells; ++i) {
+                    if (!scopeCoversCell(i, r.scope, r.tag, r.cell)) continue;
+                    const auto u = static_cast(i);
+                    tr_.alpha_L[u] = r.alpha_L;
+                    tr_.alpha_T[u] = r.alpha_T;
+                    tr_.D_m[u]     = r.D_m;
+                    // Bulk density from the grain density and the porosity
+                    // the aquifer row already resolved: ρ_b = ρ_s(1 − θ_s).
+                    tr_.rho_b[u]   = r.rho_s * (1.0 - state_.theta_s[u]);
+                }
+            }
+            for (const auto& r : gw->sorption) {
+                if (static_cast(r.scope) != pass) continue;
+                const int s = tr_.rowIndex(r.species);
+                if (s < 0) continue;
+                for (int i = 0; i < state_.n_cells; ++i) {
+                    if (!scopeCoversCell(i, r.scope, r.tag, r.cell)) continue;
+                    // The row is L/kg; the kernel works in m³/kg.
+                    tr_.kd[tr_.idx(s, i)] = r.kd * 1.0e-3;
+                    // A negative decay means "use the [POLLUTANTS] Kdecay",
+                    // which the engine already holds in 1/s; an authored one
+                    // is 1/day.
+                    tr_.decay[tr_.idx(s, i)] =
+                        (r.decay >= 0.0) ? r.decay / 86400.0
+                                         : pollutantDecay(s, pollut_decay);
+                }
+            }
+        }
+    }
+
+    for (int s = 0; s < tr_.n_species; ++s)
+        tr_.init_mass[static_cast(s)] = tr_.storage(s);
+}
+
+bool SubsurfaceSolver::scopeCoversCell(int i, GwScope scope,
+                                       const std::string& tag,
+                                       int cell) const noexcept {
+    switch (scope) {
+        case GwScope::CELL: return cell == i;
+        case GwScope::TAG:
+            return mesh_ != nullptr &&
+                   i < static_cast(mesh_->tri_tag.size()) &&
+                   mesh_->tri_tag[static_cast(i)] == tag;
+        default: return true;   // GLOBAL
+    }
+}
+
+double SubsurfaceSolver::pollutantDecay(
+    int s, const std::vector& pollut_decay) const noexcept {
+    const auto u = static_cast(s);
+    return (u < pollut_decay.size()) ? pollut_decay[u] : 0.0;
+}
+
+void SubsurfaceSolver::bookInfiltrationMass(int cell, int species,
+                                            double mass) noexcept {
+    if (!tr_.active() || mass == 0.0) return;
+    if (cell < 0 || cell >= tr_.n_cells) return;
+    if (species < 0 || species >= tr_.n_species) return;
+    tr_.xacc_from_surface[tr_.idx(species, cell)] += mass;
+}
+
+double SubsurfaceSolver::takeToSurfaceMass(int cell, int species) noexcept {
+    if (!tr_.active()) return 0.0;
+    if (cell < 0 || cell >= tr_.n_cells) return 0.0;
+    if (species < 0 || species >= tr_.n_species) return 0.0;
+    double& m = tr_.xacc_to_surface[tr_.idx(species, cell)];
+    const double v = m;
+    m = 0.0;
+    return v;
+}
+
+// ---------------------------------------------------------------------------
+// surface ↔ subsurface (step 11b)
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::bookInfiltrationFromSurface(int cell,
+                                                   double vol_m3) noexcept {
+    if (!state_.active || cell < 0 || cell >= state_.n_cells) return;
+    state_.xacc_from_surface[static_cast(cell)] += vol_m3;
+    accumulators_pending_ = true;
+}
+
+// G-X3 (2026-09-19): conduit seepage lands in the saturated zone of the
+// cells the conduit crosses. Booked per routing step, gathered per firing —
+// the same cross-cadence accumulator the surface infiltration uses.
+void SubsurfaceSolver::bookLinkSeepage(int cell, double vol_m3) noexcept {
+    if (!state_.active || cell < 0 || cell >= state_.n_cells) return;
+    state_.lacc[static_cast(cell)] += vol_m3;
+    accumulators_pending_ = true;
+}
+
+void SubsurfaceSolver::markPendingSurface(int i) noexcept {
+    const auto u = static_cast(i);
+    if (pending_flag_[u]) return;
+    pending_flag_[u] = 1;
+    pending_surface_.push_back(i);
+}
+
+double SubsurfaceSolver::takeToSurface(int cell) noexcept {
+    // Called from the surface marcher's per-cell loop, which is parallel, so
+    // this touches only cell-indexed slots. The pending LIST is compacted
+    // serially in compactPending() instead of being erased from here — an
+    // O(n) erase inside the hot cell loop is exactly the kind of thing that
+    // does not show up until a large deck.
+    if (!state_.active || cell < 0 || cell >= state_.n_cells) return 0.0;
+    const auto u = static_cast(cell);
+    const double v = state_.xacc_to_surface[u];
+    state_.xacc_to_surface[u] = 0.0;
+    pending_flag_[u] = 0;
+    return v;
+}
+
+void SubsurfaceSolver::compactPending() noexcept {
+    if (pending_surface_.empty()) return;
+    pending_surface_.erase(
+        std::remove_if(pending_surface_.begin(), pending_surface_.end(),
+                       [this](int c) {
+                           return pending_flag_[static_cast(c)] == 0;
+                       }),
+        pending_surface_.end());
+}
+
+// ---------------------------------------------------------------------------
+// the cell firing (steps 3, 7, 12, 14)
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::fireCell(int i, double dt, SurfaceStateData& surf) {
+    const auto u = static_cast(i);
+    const int  n = state_.n_cells;
+    const double A  = std::max(state_.area[u], kTiny);
+    const double zs = state_.zs[u];
+    const double ts = state_.theta_s[u];
+    const soil::Params p = paramsOf(i);
+    const auto cl = static_cast(state_.closure[u]);
+
+    const double hg0 = state_.hg[u];
+    const double hu_pre = state_.hu[u];   // T7.1: the column store this firing starts from
+    const double L0  = std::max(zs - hg0, 0.0);
+
+    // --- gather the accumulated cross-cadence volumes ---------------------
+    const double lat_vol  = gatherLateral(i);                 // m³, + in
+    const double node_vol = gatherNode(i);                    // m³, + OUT
+    double infil_vol = state_.xacc_from_surface[u];           // m³, + in
+    state_.xacc_from_surface[u] = 0.0;
+    // G-X3: conduit seepage delivered to this cell since its last firing —
+    // a saturated-zone inflow, so it rides the table update with the
+    // lateral and node volumes and shares their storage coefficient.
+    const double link_vol = state_.lacc[u];                   // m³, + in
+    state_.lacc[u] = 0.0;
+    state_.qlink_last[u] = link_vol / dt;
+    state_.led_link += link_vol;
+
+    const double q_in = infil_vol / (A * dt);                 // m/s at the top
+    state_.qplus_last[u] = q_in;
+    state_.led_infil_in += infil_vol;
+
+    // --- ET demand (step 7) -----------------------------------------------
+    // BOUNDARY_ET removes water from the unsaturated column's top with a
+    // Feddes stress from its mean suction. The retired behaviour was a hard
+    // `if (infil <= 0)` gate; the smooth multiplier is what §7 asks for, and
+    // it is why a drying column stops taking ET gradually instead of at a
+    // step.
+    double q_et = 0.0;
+    const bool et_boundary = (options_.gw_et == "BOUNDARY_ET" ||
+                              options_.gw_et == "BOTH");
+    const bool et_caprise  = (options_.gw_et == "CAPILLARY_RISE" ||
+                              options_.gw_et == "BOTH");
+    if (et_boundary && u < surf.evap_rate.size()) {
+        const double demand = std::max(surf.evap_rate[u], 0.0);
+        if (demand > 0.0) {
+            const double Se = (state_.hu[u] > 0.0 && L0 > kTiny)
+                ? std::clamp((state_.hu[u] / L0 - state_.theta_r[u]) /
+                                 std::max(ts - state_.theta_r[u], kTiny),
+                             1.0e-6, 1.0)
+                : 1.0e-6;
+            const double psi   = soil::suctionAtSaturation(p, Se);
+            const double psi_w = 150.0;   // ≈ −15 bar wilting point, in metres
+            q_et = demand * soil::feddesStress(psi, psi_w);
+        }
+    }
+
+    // --- 1. recharge across the table -------------------------------------
+    double q0 = 0.0;      // m/s, + down
+    double theta_bot = state_.theta_r[u];
+    // G-W1 (2026-09-21): `Sy` comes from the one function that owns it, so
+    // that anything CAPPING a withdrawal against the cell's drainable water
+    // caps against the same number the column will then use to spend it.
+    // `sampleNodeExchange` used the textbook θ_s − θ_r while the column used
+    // the floored θ_s − θ_bot — see specificYield().
+    double Sy = specificYield(u, p, ts, L0, cl, &theta_bot);
+
+    if (cl == GwClosure::SIGMA) {
+        // The physical Darcy flux across the table is the bottom layer's
+        // gravity drainage. It is passed INTO the sweep as `q0_phys` and
+        // comes back inside `f_bot` together with the handover, which is why
+        // the saturated update above books `q0` and not `f_bot`.
+        q0 = soil::conductivity(p, soil::suctionAtSaturation(
+                 p, std::clamp((theta_bot - state_.theta_r[u]) /
+                                   std::max(ts - state_.theta_r[u], kTiny),
+                               1.0e-6, 1.0)));
+    } else if (cl == GwClosure::ENSLAVED) {
+        q0 = q_in - q_et;
+    } else {
+        q0 = soil::rechargeQ0(p, std::max(L0, kTiny), state_.hu[u]);
+        // G-X4 (2026-09-20): …and when the FLOOR binds, the pairing above is
+        // the floored number, not the raw content. A column already at θ_s
+        // just under the table (θ_s − θ_bot → 0) otherwise loses
+        // `Sy_floor·|Δh|` from the saturated zone and hands `θ_bot·|Δh|` to
+        // the unsaturated one — the two no longer sum to θ_s and the cell
+        // CREATES `(θ_bot − (θ_s − Sy_floor))·|Δh|·A` every firing. Invisible
+        // until something withdrew hard from a near-saturated column: a
+        // conduit under a high water table did, at 0.08 m³ over half an hour
+        // on the G-X4 gate deck. Deriving the slab from the Sy actually used
+        // makes the identity hold unconditionally, and is a no-op whenever
+        // the floor does not bind (every deck that was already right).
+        theta_bot = ts - Sy;
+    }
+    if (!et_caprise && q0 < 0.0) q0 = 0.0;   // GW_ET NONE: no capillary rise
+
+    // Availability, the same idiom as every other flux here: a column may not
+    // hand down more than it holds above residual, and the table may not hand
+    // up more than it holds. Without the first cap a closure-A cell whose
+    // equilibrium it cannot reach drains itself past residual and then keeps
+    // "delivering" at K̄ forever — a leak that grows without bound and looks,
+    // from the ledger, like recharge.
+    if (cl != GwClosure::ENSLAVED) {
+        if (q0 > 0.0) {
+            const double give = std::max(state_.hu[u] - state_.theta_r[u] * L0,
+                                         0.0) / dt;
+            q0 = std::min(q0, give);
+        } else if (q0 < 0.0) {
+            const double take = std::max(hg0, 0.0) *
+                                std::max(ts - state_.theta_r[u], 0.0) / dt;
+            q0 = std::max(q0, -take);
+        }
+    }
+    state_.q0_last[u] = q0;
+
+    // --- 2. saturated explicit FV update ----------------------------------
+    const double q_deep = state_.c_loss[u] * hg0 / std::max(zs, kTiny);
+    state_.qdeep_last[u] = q_deep;
+    state_.qlat_last[u]  = lat_vol / dt;
+    state_.qnode_last[u] = node_vol / dt;
+
+    // Every saturated source shares one storage coefficient — that is the
+    // §sy table's whole content.
+    const double dV_sat = (q0 - q_deep) * A * dt + lat_vol - node_vol + link_vol;   // G-X3: + link_vol
+    double hg1 = hg0 + dV_sat / (Sy * A);
+
+    // G1-c (2026-09-19): the ENSLAVED solve is BRACKETED. The Newton it
+    // replaced started from the linearised guess and took unguarded steps;
+    // with the table a centimetre under the ground the surface content is
+    // ≈ θ_s, `Sy` sits on its floor, the guess lands above z_s, the clamped
+    // L = 0 makes F' the floor too, and the step is O(−1e5 m): the table
+    // was zeroed and the column re-evaluated at full length in one firing
+    // (measured: 23.5 m³ created on a two-cell exfiltration deck, −32 % on
+    // the Dunne gate deck). The balance W(h) = θ_s·h + hᵤ*(z_s − h) is
+    // monotone in h, so it is solved on [0, z_s] with a safeguarded Newton
+    // (bisection fallback), and what the interval cannot hold is booked
+    // exactly: above z_s as Dunne excess, below 0 as the sinks' refund —
+    // the same two channels the clamp below serves for the other closures.
+    double ens_dunne = -1.0, ens_short = -1.0;   // < 0: not decided here
+    if (cl == GwClosure::ENSLAVED) {
+        const double hu0    = soil::equilibriumStorage(p, L0);
+        const double target = ts * hg0 + hu0 + dV_sat / A;   // W(h1) wanted
+        auto W = [&](double h) {
+            return ts * h + soil::equilibriumStorage(p, std::clamp(zs - h, 0.0, zs));
+        };
+        const double W_hi = W(zs), W_lo = W(0.0);
+        if (target >= W_hi) {
+            hg1 = zs;
+            ens_dunne = (target - W_hi) * A;
+        } else if (target <= W_lo) {
+            hg1 = 0.0;
+            ens_short = (W_lo - target) * A;
+        } else {
+            // G-X1 (2026-09-19): W is monotone but can be FLAT across the capillary fringe
+            // (θ(L) = θ_s for L below the air-entry head): there the true
+            // derivative is zero and Newton has nothing to say, so the step
+            // falls back to bisection — never a floored derivative, which
+            // made Newton creep and leave the balance unmet by up to
+            // 1e-5 m³ per firing. Convergence is on the RESIDUAL (the
+            // volume), not on the step in h.
+            double lo = 0.0, hi = zs;          // W(lo) < target < W(hi)
+            double h = std::clamp(hg1, lo, hi);
+            const double f_tol = 1.0e-15 * std::max(1.0, std::fabs(target));
+            for (int it = 0; it < 200; ++it) {
+                const double F = W(h) - target;
+                if (std::fabs(F) <= f_tol) break;
+                if (F > 0.0) hi = h; else lo = h;
+                if (hi - lo <= 1.0e-15 * zs) break;
+                const double dF = ts - soil::waterContent(p, std::clamp(zs - h, 0.0, zs));
+                double hn = (dF > kTiny) ? h - F / dF : 0.5 * (lo + hi);
+                if (!(hn > lo && hn < hi)) hn = 0.5 * (lo + hi);   // safeguard
+                h = hn;
+            }
+            hg1 = h;
+        }
+    }
+
+    // Clamp with the books kept. A negative table means the sinks asked for
+    // more than the aquifer holds; give back what was not there rather than
+    // silently creating it.
+    double dunne_vol = 0.0;
+    if (ens_dunne >= 0.0) {
+        dunne_vol = ens_dunne;                       // ENSLAVED: exact, above
+    } else if (hg1 > zs) {
+        dunne_vol = (hg1 - zs) * Sy * A;
+        hg1 = zs;
+    } else if (hg1 < 0.0 || ens_short >= 0.0) {
+        const double short_vol = (ens_short >= 0.0) ? ens_short : -hg1 * Sy * A;
+        hg1 = 0.0;
+        // Refund proportionally to the sinks that overdrew: deep loss first
+        // (it is the least physical), then the node.
+        const double deep_vol = q_deep * A * dt;
+        const double refund_deep = std::min(short_vol, deep_vol);
+        state_.qdeep_last[u] = (deep_vol - refund_deep) / (A * dt);
+        const double rest = short_vol - refund_deep;
+        if (rest > 0.0 && node_vol > 0.0) {
+            const double refund_node = std::min(rest, node_vol);
+            // G-W1b (2026-09-23): this is the defect's own signature. The
+            // router has ALREADY handed the unrefunded volume to the node,
+            // so every count here is water the 1D keeps and the aquifer
+            // disowns. With the drain cap measured against the yield the
+            // column spends against, it should never fire: ~120 → 0 on the
+            // gate deck (124 on Linux, 117 on macOS — the count is
+            // platform-dependent, the zero is not). A gate asserting zero
+            // fails loudly on the bug and needs no tolerance; it held at 0
+            // across three closures, five geometries and 20 min to 12 h,
+            // including a deck that clamps 8,635 times.
+            ++node_refunds_;
+            state_.qnode_last[u] = (node_vol - refund_node) / dt;
+        }
+    }
+    state_.led_recharge += q0 * A * dt;
+    if (q0 < 0.0) state_.led_caprise += -q0 * A * dt;
+    state_.led_deep += state_.qdeep_last[u] * A * dt;
+    state_.led_lateral += lat_vol;
+    state_.led_node    += state_.qnode_last[u] * dt;
+
+    // --- 3-4. the unsaturated zone sees the CLAMPED table ------------------
+    const double L1 = std::max(zs - hg1, 0.0);
+    double rejected = 0.0;
+
+    if (cl == GwClosure::SIGMA) {
+        sigma::ColumnStep cs;
+        cs.L_old     = std::max(L0, kTiny);
+        cs.L_new     = std::max(L1, kTiny);
+        cs.dt        = dt;
+        cs.q_in      = q_in;
+        cs.q_et      = q_et;
+        cs.q0_phys   = q0;
+        cs.capillary = options_.capillary_diff;
+        sigma::advanceColumn(p, &state_.theta_sigma[u], state_.m_layers, n, cs);
+        rejected = cs.rejected;
+        state_.qet_last[u] = cs.et_taken;
+        state_.led_et += cs.et_taken * A * dt;
+        state_.hu[u] = sigma::columnStorage(&state_.theta_sigma[u],
+                                            state_.m_layers, n, cs.L_new);
+        // The compression surplus / stretch deficit the ALE sweep could not
+        // hold. Applying it here, in the same firing, is what plan gate 5
+        // measures; clamping it away inside the sweep is the classic σ-grid
+        // conservation bug and it cost 3.9e-1 m before this line existed.
+        const double net = (cs.overflow_to_sat - cs.deficit_from_sat) * dt;
+        if (net != 0.0) {
+            hg1 += net / Sy;
+            if (hg1 > zs) { dunne_vol += (hg1 - zs) * Sy * A; hg1 = zs; }
+            if (hg1 < 0.0) hg1 = 0.0;
+        }
+    } else if (cl == GwClosure::ENSLAVED) {
+        // No state to advance — the column IS its equilibrium. Rejection is
+        // whatever the (now saturated) table cannot accept.
+        state_.hu[u] = soil::equilibriumStorage(p, L1);
+        state_.qet_last[u] = q_et;
+        state_.led_et += q_et * A * dt;
+    } else {
+        // Closure A: one bulk ODE, ḣᵤ = q⁺ − q_ET − q₀ + the handover the
+        // moving table performs on the bulk store. The handover term keeps
+        // total water exact for the same reason it does in the σ column.
+        const double dL = L1 - L0;
+        // `theta_bot` is the slab content the saturated update above paired
+        // with `Sy = θ_s − theta_bot`. The two MUST be the same number.
+        double hu1 = state_.hu[u] + (q_in - q_et - q0) * dt + theta_bot * dL;
+        const double hu_max = ts * L1;
+        if (hu1 > hu_max) { rejected = (hu1 - hu_max) / dt; hu1 = hu_max; }
+        const double hu_min = state_.theta_r[u] * L1;
+        state_.qet_last[u] = q_et;
+        if (hu1 < hu_min) {
+            // A table RISING faster than the fluxes refill the column absorbs
+            // its bottom slab at `theta_bot` and leaves the rest below
+            // residual. This is closure A's version of the sigma column's
+            // `deficit_from_sat`, and it is settled the same way: draw the
+            // shortfall back UP out of the saturated zone in this same
+            // firing. Simply raising `hu1` to residual — which is what this
+            // did first — creates water out of nothing, and gate 6 found it
+            // at 2e-8 m3.
+            //
+            // Lowering the table by δ hands the column a slab holding θ_s·δ
+            // and lengthens it by δ, so residual is met when
+            //     hu1 + θ_s·δ >= θ_r·(L1 + δ)   ⇒   δ = deficit/(θ_s − θ_r).
+            // Total water is untouched: −θ_s·δ from the table, +θ_s·δ to the
+            // column.
+            const double deficit = hu_min - hu1;
+            const double drain   = std::max(ts - state_.theta_r[u], kSyFloor);
+            double delta = deficit / drain;
+            if (delta > hg1) delta = hg1;   // the table has no more to give
+            hg1 -= delta;
+            hu1 += ts * delta;
+            const double still = state_.theta_r[u] * (zs - hg1) - hu1;
+            if (still > 0.0) {
+                // Genuinely dry: there is no water anywhere to meet residual.
+                // Book the shortfall as ET that was never actually available
+                // rather than inventing it.
+                state_.qet_last[u] = std::max(0.0, q_et - still / dt);
+                hu1 += still;
+            }
+        }
+        state_.led_et += state_.qet_last[u] * A * dt;
+        state_.hu[u] = hu1;
+    }
+
+    // --- 5. Dunne saturation excess (step 12) -----------------------------
+    // Two routes reach the surface twin and they are physically distinct:
+    // `dunne_vol` is the table itself arriving at the ground (`h_g → z_s`),
+    // and `reject_vol` is water the top layer would not take. Both are
+    // saturation excess, both are booked to the same accumulator, and
+    // neither is a correction — together they ARE the mass balance
+    // (draft decision 9), which is why DUNNE defaults ON.
+    const double reject_vol = rejected * A * dt;
+    const double to_surface = (options_.dunne ? dunne_vol : 0.0) + reject_vol;
+    if (to_surface > 0.0) {
+        state_.xacc_to_surface[u] += to_surface;
+        markPendingSurface(i);
+        state_.led_dunne += to_surface;
+    }
+    state_.dunne_last[u] = to_surface / dt;
+
+    // --- T7.1: the tuple rides the volumes this firing just decided -------
+    // Every number below is the one the water used, read AFTER the refund
+    // paths may have rewritten a rate (`qnode_last`, `qdeep_last`, `qet_last`),
+    // so mass can never travel on a volume the water gave back.
+    if (tr_.active()) {
+        CellFlux f;
+        f.v_sat0   = hg0 * ts * A;
+        f.v_uns0   = hu_pre * A;
+        f.lateral  = lat_vol;
+        f.node_out = state_.qnode_last[u] * dt;
+        f.infil_in = infil_vol;
+        f.link     = link_vol;
+        f.recharge = q0 * A * dt;
+        f.et       = state_.qet_last[u] * A * dt;
+        f.deep     = state_.qdeep_last[u] * A * dt;
+        f.dt       = dt;   // T7.2
+        f.dunne    = options_.dunne ? dunne_vol : 0.0;
+        f.reject   = reject_vol;
+        // What the column's own balance could not have been produced by a
+        // flux IS the moving boundary's swap. Reading it off the final
+        // store rather than re-deriving `θ_bot·ΔL` keeps it exact under
+        // every closure — including the σ column, whose handover lives
+        // inside its ALE sweep.
+        f.handover = (state_.hu[u] * A - f.v_uns0) - f.infil_in + f.et +
+                     f.recharge + f.reject;
+        fireCellSpecies(i, f);
+    }
+
+    state_.hg[u] = hg1;
+}
+
+// ---------------------------------------------------------------------------
+// T7.1 — one cell's species pass
+// ---------------------------------------------------------------------------
+
+void SubsurfaceSolver::fireCellSpecies(int i, const CellFlux& f) noexcept {
+    const auto k0 = static_cast(i);
+    (void)k0;
+    // Arrivals land before anything is taken, so a cell that receives and
+    // gives in the same firing gives at the MIXED concentration — the
+    // surface marcher's rule (its face gather lands before the sinks read
+    // the cell). The denominators are the post-arrival water volumes; every
+    // sink in this firing reads the same pair, because the water update
+    // decided all of them simultaneously.
+    const double v_sat = f.v_sat0 + f.lateral + std::max(f.link, 0.0);
+    const double v_uns = f.v_uns0 + f.infil_in;
+    const auto   uc = static_cast(i);
+    // T7.2: the water contents retardation is computed against. The
+    // saturated zone is at θ_s by definition; the column's mean content is
+    // its store over its thickness, floored so a vanishing column does not
+    // divide.
+    const double ts_cell  = state_.theta_s[uc];
+    const double L_cell   = std::max(state_.zs[uc] - state_.hg[uc], kTiny);
+    const double theta_uns = std::clamp(state_.hu[uc] / L_cell,
+                                        state_.theta_r[uc], ts_cell);
+
+    for (int s = 0; s < tr_.n_species; ++s) {
+        const auto k  = tr_.idx(s, i);
+        const auto us = static_cast(s);
+        double& msat = tr_.sat_mass[k];
+        double& muns = tr_.unsat_mass[k];
+
+        // Take `vol` worth of water out of `m`, which is riding `v_store`.
+        // The clamp is the surface's: never remove more than is there, and
+        // no floor at all on the signed temperature row, where °C·m³ below
+        // zero is a state rather than an error.
+        // T7.2: `mob` is the dissolved share — sorbed mass does not travel,
+        // in any channel. Passing it through the ONE place a sink reads a
+        // concentration is what keeps retardation from having to be
+        // remembered at each of the eight channels below.
+        const double mob_sat = tr_.dissolvedFraction(s, i, ts_cell);
+        const double mob_uns = tr_.dissolvedFraction(s, i, theta_uns);
+        auto take = [&](double& m, double vol, double v_store,
+                        double mob) -> double {
+            if (!(vol > 0.0) || !(v_store > 0.0) || m == 0.0) return 0.0;
+            double dm = vol * (m / v_store) * mob;
+            if (!tr_.signedRow(s) && dm > m) dm = m;
+            m -= dm;
+            return dm;
+        };
+
+        // (1) lateral Darcy — internal between cells, so the sum over the
+        //     mesh is zero on a closed domain and the ledger says exactly
+        //     that (the water's `led_lateral` behaves identically).
+        const double lat_m = gatherLateralMass(i, s);
+        msat += lat_m;
+        tr_.net_lateral[us] += lat_m;
+
+        // (2) infiltration the surface handed down, with the mass the water
+        //     was carrying when it left the surface cell.
+        const double in_m = tr_.xacc_from_surface[k];
+        if (in_m != 0.0) {
+            tr_.xacc_from_surface[k] = 0.0;
+            muns += in_m;
+            tr_.gained_infil[us] += in_m;
+        }
+
+        // (3) conduit seepage (G-X3/G-X4). T7.4 opened this seam: a LEAKING
+        //     pipe now fills the cell with water carrying the conduit's own
+        //     concentration, booked by the router at the same cadence and
+        //     with the same length weights the volume took. The 1D already
+        //     DEBITS that mass as its exfiltration loss
+        //     (`qual_routing_seep`), so this side only receives it —
+        //     booking a second removal there would be the classic
+        //     double-count. A GAINING pipe draws water out, and that water
+        //     leaves at the cell's own concentration.
+        const double link_in_m = tr_.lacc_mass[k];
+        if (link_in_m != 0.0) {
+            tr_.lacc_mass[k] = 0.0;
+            msat += link_in_m;
+            tr_.gained_link[us] += link_in_m;
+        }
+        if (f.link < 0.0)
+            tr_.lost_link[us] += take(msat, -f.link, v_sat, mob_sat);
+
+        // (4) recharge across the table, or capillary rise — internal to
+        //     this cell, so it is informational only.
+        if (f.recharge > 0.0) {
+            const double dm = take(muns, f.recharge, v_uns, mob_uns);
+            msat += dm;
+            tr_.internal_recharge[us] += dm;
+        } else if (f.recharge < 0.0) {
+            const double dm = take(msat, -f.recharge, v_sat, mob_sat);
+            muns += dm;
+            tr_.internal_recharge[us] -= dm;
+        }
+
+        // (4b) …and the moving table's own swap, which carries water across
+        //      the same boundary with no flux behind it. Without this the
+        //      TOTAL still conserves — the gate would pass — while the two
+        //      zones quietly end up holding each other's solute.
+        if (f.handover > 0.0) {
+            // The moving boundary carries the water's whole content across,
+            // sorbed included: the grains themselves change zone when the
+            // table passes them. `mob = 1`.
+            const double dm = take(msat, f.handover, v_sat, 1.0);
+            muns += dm;
+            tr_.internal_recharge[us] -= dm;
+        } else if (f.handover < 0.0) {
+            const double dm = take(muns, -f.handover, v_uns, 1.0);
+            msat += dm;
+            tr_.internal_recharge[us] += dm;
+        }
+
+        // (5) the saturated zone's sinks, and the node seam (T7.4). A node
+        //     RECHARGING the aquifer sent its own quality down the bed;
+        //     `sampleNodeExchange` sampled it at the node's concentration
+        //     when it sampled the head, and this is where the cell takes
+        //     it. The reverse — the aquifer draining INTO the node — leaves
+        //     at the cell's concentration and is booked per NODE here, for
+        //     the router to hand to that node's coupling queues.
+        const double node_in_m = gatherNodeMass(i, s);
+        if (node_in_m != 0.0) {
+            msat += node_in_m;
+            tr_.gained_node[us] += node_in_m;
+        }
+        if (f.node_out > 0.0) {
+            const double dm = take(msat, f.node_out, v_sat, mob_sat);
+            tr_.lost_node[us] += dm;
+            if (dm != 0.0 && !tr_.node_out_mass.empty()) {
+                // Split across the beds this cell serves, in proportion to
+                // what each one drew — a cell can carry more than one.
+                const auto nn = tr_.node_out_mass.size() /
+                                static_cast(tr_.n_species);
+                double drew = 0.0;
+                for (std::size_t b = 0; b < node_beds_.size(); ++b)
+                    if (node_beds_[b].cell == i)
+                        drew += std::max(bed_gathered_[b], 0.0);
+                if (drew > 0.0) {
+                    for (std::size_t b = 0; b < node_beds_.size(); ++b) {
+                        if (node_beds_[b].cell != i) continue;
+                        const double share = std::max(bed_gathered_[b], 0.0) / drew;
+                        const auto ni = static_cast(node_beds_[b].node);
+                        if (ni < nn)
+                            tr_.node_out_mass[static_cast(s) * nn + ni] +=
+                                dm * share;
+                    }
+                }
+            }
+        }
+        tr_.lost_deep[us] += take(msat, f.deep, v_sat, mob_sat);
+
+        // (6) ET carries the INTENSIVE rows only: the solutes stay and the
+        //     column up-concentrates (GW plan §3.5), while temperature and
+        //     age leave with the water at the column's own mean — the
+        //     program plan's D-A20 convention, the same one the surface
+        //     marcher applies to evaporation, so a parcel's age is not
+        //     changed by the act of evaporating part of it.
+        if (f.et > 0.0 && (s == tr_.age_row || s == tr_.temp_row))
+            tr_.lost_et[us] += take(muns, f.et, v_uns, 1.0);
+
+        // (7) saturation excess back to the surface: the table's own water
+        //     from the saturated zone, the column's rejection from the
+        //     unsaturated one. Both are owed to the surface twin, which
+        //     drains them with `takeToSurfaceMass`.
+        double up = 0.0;
+        if (f.dunne  > 0.0) up += take(msat, f.dunne,  v_sat, mob_sat);
+        if (f.reject > 0.0) up += take(muns, f.reject, v_uns, mob_uns);
+        if (up != 0.0) {
+            tr_.xacc_to_surface[k] += up;
+            tr_.lost_dunne[us] += up;
+        }
+
+        // (8) T7.2: first-order decay, on the TOTAL mass of both zones —
+        //     dissolved and sorbed alike, the usual assumption for a
+        //     partitioning solute whose reaction does not care which phase
+        //     it is in. Applied last, on what the channels left behind, and
+        //     never to age or temperature: `__WATER_AGE__` grows with time
+        //     by construction and a temperature does not decay.
+        const double kdec = tr_.decay.empty() ? 0.0 : tr_.decay[k];
+        if (kdec > 0.0 && f.dt > 0.0 && s != tr_.age_row && s != tr_.temp_row) {
+            const double keep = std::exp(-kdec * f.dt);
+            const double gone = (msat + muns) * (1.0 - keep);
+            msat *= keep;
+            muns *= keep;
+            tr_.lost_reaction[us] += gone;
+        }
+    }
+}
+
+void SubsurfaceSolver::fireGwCells(int tier, double dt, SurfaceStateData& surf) {
+    if (!state_.active || !tierHasCells(tier)) return;
+    for (const int i : cells_by_tier_[static_cast(tier)])
+        fireCell(i, dt, surf);
+    if (tier < static_cast(tier_firings_.size()))
+        ++tier_firings_[static_cast(tier)];
+}
+
+void SubsurfaceSolver::settle(SurfaceStateData& surf) {
+    // Deliberately NOT "apply everything pending".
+    //
+    // The surface marcher's settleAccumulators can add pending face volume
+    // straight into `volume[i]`, because volume IS its conserved state. The
+    // subsurface's state is a water TABLE, and turning a volume into a table
+    // rise also moves the unsaturated store — the two zones share a moving
+    // boundary. A settle that did the saturated half and skipped the
+    // unsaturated one leaked at a rate proportional to |ḣ_g|; it passed a
+    // closed-cell gate (nothing pending) and failed every forced one. That
+    // version of this function is why gates 2-4 exist.
+    //
+    // So all volume goes through `fireCell`, which owns the paired update,
+    // and settling reduces to what actually needs doing here:
+    //
+    //  - Nothing can strand. Side accumulators are indexed by EDGE and
+    //    gathered through the cell's CSR incidence; neither changes on a
+    //    re-tier. The owner picks its volume up at its next firing, and the
+    //    macro cycle fires every tier at least once per cycle.
+    //  - `storage()` therefore is not the whole invariant between firings.
+    //    Anything auditing continuity (the ledger, a hotstart, a gate) must
+    //    add the accumulators — see gw2d_gates.cpp's `totalWater()`.
+    //  - The one genuine hazard is the OTHER direction: `xacc_to_surface` is
+    //    drained by the surface cell, and a dry surface cell that never
+    //    fires would hold exfiltrated water forever. That is what
+    //    `pendingSurfaceCells()` is for, and it is the marcher's job to pin
+    //    those cells active.
+    (void)surf;
+    compactPending();
+    accumulators_pending_ = false;
+}
+
+}  // namespace openswmm::twoD
diff --git a/src/engine/2d/subsurface/SubsurfaceSolver.hpp b/src/engine/2d/subsurface/SubsurfaceSolver.hpp
new file mode 100644
index 000000000..d9737174b
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceSolver.hpp
@@ -0,0 +1,431 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceSolver.hpp
+ * @brief G-steps 3, 6-12, 16 — the two-zone groundwater kernel: saturated FV
+ *        update, lateral Darcy, closure dispatch, node exchange, Dunne
+ *        transfer, ET, and the LTS tier hooks the surface marcher calls.
+ *
+ * @section gw_lts How this joins the marcher (§3, guarantees G-A and G-B)
+ *
+ * The subsurface does **not** get a loop of its own. `ExplicitInertialSolver`
+ * calls four hooks, mirroring what it already does for the surface:
+ *
+ * | Hook | When | What |
+ * |---|---|---|
+ * | `assignTiers` | every `syncAndRebuild` | Δt_g / Δt_u per cell → tier lists |
+ * | `fireGwFaces(tier, dt)` | face phase of a due tier | lateral Darcy → ±ΔV side accumulators |
+ * | `fireGwCells(tier, dt)` | cell phase of a due tier | gather, closure, node/deep/ET/Dunne |
+ * | `settle()` | before any re-tier | flush every accumulator |
+ *
+ * **G-A** — a GW cell's tier comes only from `min(Δt_g, Δt_u)`. The surface's
+ * pin-to-tier-0 rule for coupling cells is deliberately NOT applied here: a
+ * GW cell with node exchange or infiltration keeps its own tier and the
+ * exchange accumulates until it fires. Only the surface twin is ever pinned.
+ *
+ * **G-B** — every new flux channel books ±Δ into a side accumulator at the
+ * producer's cadence and is gathered by the owner at its own firing, exactly
+ * like `facc_L_`/`facc_R_`. Cross-tier conservation is inherited, not
+ * re-proved.
+ *
+ * @section gw_split Operator split within one cell firing
+ *
+ * The order matters and is the plan's (§2.3 "apply saturated Δh_g first,
+ * then the column sees the new L"):
+ *
+ * 1. `q₀_phys` — the physical Darcy flux across the table, from the current
+ *    column state (closure B) or the closed form (closure A).
+ * 2. Saturated update with `q₀_phys`, lateral gather, node exchange, deep
+ *    loss → new `h_g`, clamped to `[0, z_s]`.
+ * 3. `L̇` from the CLAMPED `h_g`, so clamping cannot break conservation.
+ * 4. Column sweep with that `L̇`; its `f_bot` carries the handover, and its
+ *    `overflow_to_sat` / `deficit_from_sat` are applied to `h_g` in this same
+ *    firing.
+ * 5. Dunne: `h_g > z_s − ε` moves the excess to the surface twin.
+ *
+ * @note **Specific yield.** Step 2 divides by `θ_s − θ_bot`, not `θ_s`. See
+ *       `SigmaColumn.hpp`'s note: with the handover made explicit, `θ_s`
+ *       does not conserve and `θ_s − θ_bot` is the textbook specific yield.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SUBSURFACE_SOLVER_HPP
+#define OPENSWMM_ENGINE_2D_SUBSURFACE_SOLVER_HPP
+
+#include "SigmaColumn.hpp"
+#include "SubsurfaceData.hpp"
+#include "SubsurfaceTransportState.hpp"   // T7.1
+
+#include 
+#include 
+
+namespace openswmm {
+struct NodeData;
+}  // namespace openswmm
+
+namespace openswmm::twoD {
+
+struct MeshData;
+struct InertialEdges;
+struct SurfaceStateData;
+struct SolverOptions2D;
+struct GwTransportData;
+/// T7.2: declared in GwTransportData.hpp; the solver only needs the tag.
+enum class GwScope : int8_t;
+
+/// T7.1: the row layout `initTransport` needs, without the solver having to
+/// include `TransportPolicy` (and with it the whole SimulationContext) — the
+/// router resolves the policy and hands the answer over.
+struct RowLayoutLite {
+    int n_species = 0;
+    int n_pollut  = 0;
+    int n_msx     = 0;
+    int age_row   = -1;
+    int temp_row  = -1;
+    std::vector names;
+};
+
+using openswmm::NodeData;
+
+/**
+ * @brief The two-zone kernel. Owned by SurfaceRouter2D; driven by the
+ *        marcher's tier hooks.
+ */
+class SubsurfaceSolver {
+public:
+    /**
+     * @brief Resolve the authored rows onto cells, seed state, size the
+     *        accumulators.
+     *
+     * @param mesh     cell areas, centroid elevations and tags
+     * @param edges    the marcher's unique interior-edge topology, shared
+     * @param opts     the 2D solver options (LTS ladder, unit factors)
+     * @param uf       project-unit → SI multipliers for the authored rows
+     * @param n_nodes  1D node count, to size the node-exchange ledger
+     * @param cfg      the authored rows — read, never modified
+     * @param warnings advisory diagnostics appended here
+     * @returns a fatal diagnostic; empty on success.
+     *
+     * @note Takes what it needs rather than a `SimulationContext`. That is
+     *       not tidiness: it is what lets the numerical gates build a mesh,
+     *       a soil and a table in twenty lines and check a conservation
+     *       identity, with no engine, no project file and no units. A kernel
+     *       that can only be exercised through a full model is a kernel
+     *       whose failures are found late.
+     */
+    std::string initialize(const MeshData& mesh, const InertialEdges& edges,
+                           const SolverOptions2D& opts,
+                           const GwUnitFactors& uf, int n_nodes,
+                           SubsurfaceConfig& cfg,
+                           std::vector& warnings);
+
+    bool active() const noexcept { return state_.active; }
+    SubsurfaceState&       state()       noexcept { return state_; }
+    const SubsurfaceState& state() const noexcept { return state_; }
+
+    // ---- T7.1: species / age / enthalpy -----------------------------------
+
+    /// The transported tuple, sized from `TransportPolicy` at `initTransport`
+    /// and inert (`active() == false`) until then.
+    SubsurfaceTransportState&       transport()       noexcept { return tr_; }
+    const SubsurfaceTransportState& transport() const noexcept { return tr_; }
+    /// Size the rows and seed both stores from `[GW_INITIAL_QUALITY]`.
+    /// Separate from `initialize` because the row layout needs the resolved
+    /// `[GW_*]` sections, which the router owns. @p names is the row layout's
+    /// name list (TransportPolicy order).
+    /// @param pollut_decay the engine's `[POLLUTANTS]` Kdecay column (1/s),
+    ///        row-aligned with the layout — what a `[GW_SORPTION]` row with
+    ///        no DECAY of its own falls back to.
+    void initTransport(const RowLayoutLite& rows, const GwTransportData* gw,
+                       const std::vector& pollut_decay,
+                       std::vector& warnings);
+    /// Water volume of one cell's saturated zone (m³) — the denominator for
+    /// a saturated concentration.
+    double satVolume(int cell) const noexcept {
+        const auto u = static_cast(cell);
+        return state_.hg[u] * state_.theta_s[u] * state_.area[u];
+    }
+    /// …and of its unsaturated column store (m³), whatever closure holds it.
+    double unsatVolume(int cell) const noexcept {
+        const auto u = static_cast(cell);
+        return state_.hu[u] * state_.area[u];
+    }
+    /// The surface hands mass down with its infiltration (T7.1 seam): the
+    /// mass the water it booked through `bookInfiltrationFromSurface` was
+    /// carrying, gathered when the GW cell fires.
+    void bookInfiltrationMass(int cell, int species, double mass) noexcept;
+    /// …and takes back what saturation excess and rejection carried up.
+    /// Drained by the surface cell in the same call that takes the water.
+    double takeToSurfaceMass(int cell, int species) noexcept;
+    const GwOptions&       options() const noexcept { return options_; }
+
+    // ---- LTS hooks -------------------------------------------------------
+
+    /// Per-cell stability step `min(Δt_g, Δt_u)`, written into
+    /// `state_.dt_cell`. Called once per rebuild; cheap enough to be
+    /// unconditional (the plan's "they rarely bind").
+    void refreshDtCell(const MeshData& mesh, const InertialEdges& edges);
+    /// G1-c (2026-09-19): the smallest per-cell stability step after
+    /// `refreshDtCell` (s), or +inf when nothing bounds it — the marcher folds
+    /// it into the ladder's base step so a groundwater cell whose own bound is
+    /// finer than every active surface cell's does not fire beyond it.
+    double minDtCell() const noexcept {
+        double m = 1.0e30;
+        for (const double v : state_.dt_cell) if (v < m) m = v;
+        return m;
+    }
+
+    /// Assign tiers from `dt_cell` against the marcher's `dt0` and tier
+    /// count, and rebuild the per-tier cell/face lists. **G-A:** no surface
+    /// quantity enters this.
+    void assignTiers(double dt0, int n_tiers);
+
+    /// Minimum tier count the ladder needs so it reaches the slowest GW cell
+    /// (`K ≥ 1 + ⌈log2(Δt_gw_max/dt0)⌉`, G-A point 3). The marcher grows its
+    /// ladder to this before assigning.
+    int requiredTiers(double dt0) const noexcept;
+
+    /// Lateral Darcy on the faces of one tier; books ±ΔV into `eacc_L/R`.
+    void fireGwFaces(int tier, double dt);
+    /// Gather + closure + node/deep/ET/Dunne for the cells of one tier.
+    void fireGwCells(int tier, double dt, SurfaceStateData& surf);
+    /// Flush every pending accumulator into its owner. Mandatory before any
+    /// re-tier or active-set change (the stranded-flux hazard).
+    void settle(SurfaceStateData& surf);
+
+    /// True when the tier's cell list is non-empty.
+    bool tierHasCells(int tier) const noexcept {
+        return tier >= 0 && tier < static_cast(cells_by_tier_.size()) &&
+               !cells_by_tier_[static_cast(tier)].empty();
+    }
+    bool tierHasFaces(int tier) const noexcept {
+        return tier >= 0 && tier < static_cast(faces_by_tier_.size()) &&
+               !faces_by_tier_[static_cast(tier)].empty();
+    }
+    int tierCount() const noexcept {
+        return static_cast(cells_by_tier_.size());
+    }
+    /// Per-tier firing counts — the G-A telemetry (`swmm_gw2d_get_tier_histogram`).
+    const std::vector& tierFirings() const noexcept { return tier_firings_; }
+
+    // ---- surface ↔ subsurface --------------------------------------------
+
+    /// The surface books infiltration it delivered to cell `i` (m³) at its
+    /// own (finer) cadence; the GW cell gathers it when it fires.
+    void bookInfiltrationFromSurface(int cell, double vol_m3) noexcept;
+    /// G-X3 (2026-09-19): the router books a conduit's seepage volume (m³,
+    /// SI, its length-weighted share for this cell) at the routing cadence;
+    /// the GW cell gathers it at its firing as a saturated-zone inflow.
+    void bookLinkSeepage(int cell, double vol_m3) noexcept;
+    /// Volume (m³) the subsurface owes the surface twin — Dunne and
+    /// exfiltration — drained by the surface at its firing.
+    double takeToSurface(int cell) noexcept;
+    /// Cells with pending surface-bound water, so the marcher can pin them
+    /// active (a dry surface cell above an exfiltrating column must route).
+    /// Call `compactPending()` first — `takeToSurface` clears flags but does
+    /// not erase from this list, because it runs inside the parallel cell
+    /// loop.
+    const std::vector& pendingSurfaceCells() const noexcept {
+        return pending_surface_;
+    }
+    /// Drop drained cells from `pendingSurfaceCells()`. Serial; call from
+    /// the marcher's rebuild, not from a firing.
+    void compactPending() noexcept;
+
+    /// T7.4: the node's own species row, `[node * n_species + s]`, published
+    /// by the router each batch — what a RECHARGING node's water carries
+    /// down its bed. Null (or a zero row count) means the seam moves water
+    /// only, which is what every pre-T7.4 deck did.
+    void setNodeRowConc(const double* rows, int n_species) noexcept {
+        node_row_conc_ = rows;
+        node_row_ns_   = n_species;
+    }
+    /// T7.4: mass the aquifer owes each 1D node this batch
+    /// (`[s * n_nodes + node]`, + out of the aquifer), flushed by the router
+    /// into the node's coupling queues alongside the volume.
+    const std::vector& nodeExchangeMass() const noexcept {
+        return tr_.node_out_mass;
+    }
+    /// T7.4: mass a leaking conduit delivered into one cell, at the
+    /// conduit's own concentration — the species twin of `bookLinkSeepage`.
+    void bookLinkSeepageMass(int cell, int species, double mass) noexcept;
+
+    /// Node ↔ aquifer exchange, evaluated at tier-0 cadence against the
+    /// batch-frozen 1D heads and booked into `nacc` (G-B row 3). The GW cell
+    /// gathers its share when IT fires — the node is never pinned to the
+    /// aquifer's tier and the aquifer is never pinned to tier 0.
+    /// @param nodes 1D node data, or nullptr when nothing is coupled.
+    void sampleNodeExchange(const NodeData* nodes, double dt);
+
+    /// Per-node exchange volume this advance (m³ SI, + out of the aquifer
+    /// into the pipe). The router books it into `nodes.coupling_volume`
+    /// through the same `flow_2d_to_1d` factor the surface exchange uses.
+    const std::vector& nodeExchangeVolumes() const noexcept {
+        return node_exchange_vol_;
+    }
+    /// Zero the per-node ledger at the start of a routing batch.
+    void resetNodeExchangeVolumes() noexcept;
+    /// G-O: the `[2D_AQUIFER_NODE]` beds as resolved (cell index filled),
+    /// in the authored order — parallel to SurfaceRouter2D::aquiferNodeNames().
+    const std::vector& nodeBeds() const noexcept { return node_beds_; }
+    /// G-O: cumulative exchange per bed (m³, + out of the aquifer into the
+    /// pipe) since the start — the results-file series behind the GUI's
+    /// GwExchange plot. Never reset.
+    const std::vector& bedExchangeCumulative() const noexcept {
+        return bed_exchange_cum_;
+    }
+
+    // ---- G-W1b: what a gate needs to prove its own deck is an instrument --
+    //
+    // A gate that measures a cap must first establish that the cap BOUND on
+    // the deck it is measuring, or it can pass with the defect present. The
+    // ratio between the two specific yields does not establish that — a deck
+    // scoring 56.8× was measured bit-identical with the bug — because what
+    // makes the cap bind is `h_g · Sy · A` being small in absolute terms.
+    // Only the clamp knows. These three say so directly, with no threshold
+    // to tune and no geometry that can make them lie.
+
+    /// Firings on which the aquifer→node drain cap actually clamped `Q`.
+    /// Zero means the deck cannot see anything this cap does.
+    long drainCapBinds() const noexcept { return drain_cap_binds_; }
+    /// Firings on which a column went short and the node's share of the
+    /// overdraw was refunded — into the aquifer's books alone, after the
+    /// router had already paid the node. The defect's signature: 124 before
+    /// G-W1, 0 after.
+    long nodeRefunds() const noexcept { return node_refunds_; }
+    /// The specific yield the column ACTUALLY uses for `cell`, from the one
+    /// definition. Exposed so a test never re-derives it: re-deriving only
+    /// the CLOSED_FORM branch (as the first version of the G-W1b guard did)
+    /// silently computes a number the solver never uses under SIGMA or
+    /// ENSLAVED, and agrees only for as long as every fixture is closure A.
+    double specificYieldOf(int cell) const noexcept;
+
+    /// Storage now, for the continuity ledger.
+    double storage() const noexcept { return state_.storage(); }
+
+private:
+    void resolveRows(const MeshData& mesh, const GwUnitFactors& uf,
+                     SubsurfaceConfig& cfg, std::vector& warnings);
+    void resolveClosures(std::vector& warnings);
+    soil::Params paramsOf(int i) const noexcept;
+    /// One cell's firing — the §gw_split sequence.
+    void fireCell(int i, double dt, SurfaceStateData& surf);
+
+    /// T7.1: every water volume one cell's firing moved, so the species pass
+    /// can ride exactly the same numbers. Volumes are m³ and signed as the
+    /// kernel books them: `+ node_out` LEAVES the aquifer, `link` is signed
+    /// (G-X4: `+` a leaking conduit filling the cell, `−` a gaining one
+    /// drawing from it), `+ recharge` is unsaturated → saturated.
+    struct CellFlux {
+        double v_sat0 = 0.0, v_uns0 = 0.0;   ///< water volumes BEFORE the firing
+        double lateral = 0.0;                ///< gathered, + into the cell
+        double node_out = 0.0;
+        double infil_in = 0.0;
+        double link = 0.0;
+        double recharge = 0.0;
+        /// The MOVING TABLE's own swap between the two stores (m³, `+` into
+        /// the unsaturated one, i.e. a falling table handing its drained
+        /// slab up). Water crosses the boundary here without any flux
+        /// driving it, so the mass has to cross with it or the two zones
+        /// end the step holding each other's solute. Derived from the
+        /// column's own balance, which makes it exact for every closure
+        /// rather than only for closure A's explicit `θ_bot·ΔL`.
+        double handover = 0.0;
+        double et = 0.0;                     ///< out of the column
+        double deep = 0.0;
+        double dt = 0.0;                     ///< T7.2: the firing's own step (s), for decay
+        double dunne = 0.0;                  ///< saturation excess, out of the saturated zone
+        double reject = 0.0;                 ///< column rejection, out of the unsaturated zone
+    };
+    /// Move the tuple along @p f. Called at the END of `fireCell`, when every
+    /// volume is final.
+    void fireCellSpecies(int i, const CellFlux& f) noexcept;
+    /// Gather this cell's lateral side accumulators (m³) and zero them.
+    double gatherLateral(int i) noexcept;
+    /// T7.1: the same gather for one species' mass.
+    double gatherLateralMass(int i, int s) noexcept;
+    /// T7.2: does a `* / TAG / CELL` scoped row cover this cell?
+    bool scopeCoversCell(int i, GwScope scope, const std::string& tag,
+                         int cell) const noexcept;
+    /// T7.4: gather one species' share of this cell's node-seam arrivals.
+    double gatherNodeMass(int i, int s) noexcept;
+    /// T7.2: the `[POLLUTANTS]` decay constant for a transport row (1/s).
+    double pollutantDecay(int s, const std::vector& pollut_decay) const noexcept;
+    /// Gather this cell's booked node exchange (m³, + out of the aquifer).
+    double gatherNode(int i) noexcept;
+
+    /// G-W1: specific yield for cell `u` under closure `cl` — the ONE
+    /// definition. Anything capping a withdrawal against the cell's drainable
+    /// water must cap against the same number the column will spend it
+    /// against, or the cap does not bind and the column goes short. Optionally
+    /// reports the bottom/mean unsaturated content the derivation used.
+    double specificYield(std::size_t u, const soil::Params& p, double ts,
+                         double L0, GwClosure cl,
+                         double* theta_bot_out) const noexcept;
+    void markPendingSurface(int i) noexcept;
+
+    SubsurfaceState  state_;
+    SubsurfaceTransportState tr_;   ///< T7.1
+    GwOptions        options_;
+    std::vector node_beds_;
+    std::vector    bed_exchange_cum_;   ///< G-O: per bed (m³), cumulative
+    /// T7.4: the per-bed volumes the CURRENT gather took — the weights that
+    /// split this firing's outgoing mass across the cell's beds. Written by
+    /// `gatherNode`, read by `fireCellSpecies` in the same firing, so it can
+    /// never be stale (the bug the first cut had).
+    std::vector    bed_gathered_;
+    /// G-X1: water taken FROM each 1D node by the recharge direction within
+    /// the current routing batch (m³, 2D units), reset with
+    /// `node_exchange_vol_` — the frozen node volume is a batch budget, not a
+    /// per-substep one, exactly as the surface's `node_drawn_` ledger.
+    std::vector    node_drawn_gw_;
+    /// T7.4: the router's published node species rows (not owned).
+    const double* node_row_conc_ = nullptr;
+    int           node_row_ns_   = 0;
+
+    const MeshData*      mesh_  = nullptr;
+    const InertialEdges* edges_ = nullptr;
+    const SolverOptions2D* opts_ = nullptr;
+
+    std::vector> cells_by_tier_;
+    std::vector> faces_by_tier_;
+    std::vector          face_tier_;
+    std::vector             tier_firings_;
+    std::vector              pending_surface_;
+    std::vector          pending_flag_;
+    std::vector              cell_nface_;   ///< incident GW faces per cell
+    std::vector           node_exchange_vol_;  ///< per 1D node (m³)
+    long                          drain_cap_binds_ = 0;  ///< G-W1b
+    long                          node_refunds_    = 0;  ///< G-W1b
+    bool accumulators_pending_ = false;
+
+    /// PER_SUBCATCH: cell i ↔ subcatchment i, and the outlet node it
+    /// exchanges with. Empty in mesh mode.
+    std::vector subcatch_outlet_node_;
+    /// Mesh mode: cell → containing subcatchment for the legacy arbitration
+    /// (centroid-in-polygon, draft decision 13). −1 = not covered.
+    std::vector cell_subcatch_;
+};
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_SUBSURFACE_SOLVER_HPP
diff --git a/src/engine/2d/subsurface/SubsurfaceTransportState.hpp b/src/engine/2d/subsurface/SubsurfaceTransportState.hpp
new file mode 100644
index 000000000..a511ce89a
--- /dev/null
+++ b/src/engine/2d/subsurface/SubsurfaceTransportState.hpp
@@ -0,0 +1,322 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SubsurfaceTransportState.hpp
+ * @brief T7.1 — species / age / enthalpy carried by the two-zone groundwater
+ *        kernel (GW transport plan §3.4).
+ *
+ * @details The subsurface twin of `SurfaceTransportState`, and deliberately
+ *          the same shape so the two read alike and the seam between them is
+ *          one concentration:
+ *
+ *          - **Mass, not concentration.** A store holds `conc × m³`; the age
+ *            row holds age-volume and the temperature row temperature-volume
+ *            (°C·m³, signed). A report divides by the SI water volume.
+ *          - **Species-major**, `[s * n_cells + c]`, so a species sweep walks
+ *            contiguous cells.
+ *          - **Rows come from `TransportPolicy`** — pollutants, MSX,
+ *            `__WATER_AGE__`, `__TEMPERATURE__` last — never re-derived here
+ *            (GW plan §3.4: "do not re-derive np/nm/na/nt a fourth time").
+ *
+ *          **Two bulk stores, one per zone.** `sat_mass` rides the saturated
+ *          water `h_g·θ_s·A`; `unsat_mass` rides the column store `h_u·A`,
+ *          whatever closure produced it. The plan's third store, the
+ *          per-layer `layer_mass` for closure B, is **T7.2's**: it is a
+ *          resolution refinement, and a bulk unsaturated store already
+ *          conserves exactly — which is what T7.1 is for. Under closure B
+ *          the bulk store means the column is treated as well mixed for
+ *          transport while its WATER stays σ-resolved.
+ *
+ *          **Heat is water-only in T7.1.** The temperature row is a water
+ *          temperature-volume, exactly as on the surface. The soil matrix's
+ *          own heat capacity (`[GW_PARAMS] rho_s / c_s`), conduction and the
+ *          thermal boundaries are T7.3; until then a temperature row in the
+ *          aquifer transports, but it does not yet exchange heat with the
+ *          solids.
+ *
+ * @ingroup engine_2d
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_2D_SUBSURFACE_TRANSPORT_STATE_HPP
+#define OPENSWMM_ENGINE_2D_SUBSURFACE_TRANSPORT_STATE_HPP
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::twoD {
+
+/**
+ * @brief Species mass in both aquifer zones, and where mass crossed a
+ *        boundary.
+ */
+struct SubsurfaceTransportState {
+    // ---- rows (TransportPolicy's layout, copied at initialize) ------------
+    int n_species = 0;
+    int n_cells   = 0;
+    int n_pollut  = 0;
+    int n_msx     = 0;
+    int age_row   = -1;
+    int temp_row  = -1;
+    std::vector row_names;
+
+    /// A row whose mass may legitimately be negative — the temperature row
+    /// (°C·m³ below zero is a state, not an error), so no clamp applies.
+    bool signedRow(int s) const noexcept { return s == temp_row; }
+
+    /// Row index of a species by name, or −1 — the `[GW_*]` sections address
+    /// species by name and resolve through this.
+    int rowIndex(std::string_view name) const noexcept {
+        for (std::size_t i = 0; i < row_names.size(); ++i)
+            if (row_names[i] == name) return static_cast(i);
+        return -1;
+    }
+
+    // ---- the two stores ---------------------------------------------------
+    // T7.2: a store holds the cell's TOTAL mass of a species — dissolved
+    // plus whatever is sorbed on the grains. Only the dissolved part
+    // travels, and `dissolvedFraction` is what every flux multiplies by, so
+    // retardation is a property of the CONCENTRATION the channels read
+    // rather than a factor sprinkled through them.
+    std::vector sat_mass;     ///< [s*n_cells+c] in the saturated water
+    std::vector unsat_mass;   ///< [s*n_cells+c] in the column store
+
+    // ---- T7.2 resolved parameters ----------------------------------------
+    /// `[GW_TRANSPORT_PARAMS]` per cell, after `* < TAG < CELL` resolution.
+    std::vector alpha_L;      ///< longitudinal dispersivity (m)
+    std::vector alpha_T;      ///< transverse dispersivity (m)
+    std::vector D_m;          ///< molecular diffusivity (m²/s)
+    std::vector rho_b;        ///< bulk density ρ_s(1 − θ_s) (kg/m³)
+    /// `[GW_SORPTION]` per cell and species, `[s*n_cells+c]`: the linear
+    /// partition coefficient (m³/kg — the row is L/kg and converts once)
+    /// and the first-order decay constant (1/s).
+    std::vector kd;
+    std::vector decay;
+    /// Whether dispersion runs at all (`[GW_TRANSPORT_OPTIONS] DISPERSION`).
+    bool dispersion_on = true;
+    /// T7.2 telemetry: faces whose dispersive exchange hit the limiter. A
+    /// bind is not an error — it is the face telling the modeller the
+    /// dispersion is under-resolved at this Δt, which is the surface's
+    /// rule too (`dispersion_limiter_binds`).
+    long dispersion_limiter_binds = 0;
+
+    /// The share of a cell's stored mass that is DISSOLVED and therefore
+    /// mobile: `1 / R` with the retardation factor `R = 1 + ρ_b·K_d/θ`.
+    /// Age and temperature never sorb — they are properties of the water,
+    /// not solutes — so they are always fully mobile.
+    double dissolvedFraction(int s, int c, double theta) const noexcept {
+        if (s == age_row || s == temp_row) return 1.0;
+        if (kd.empty() || !(theta > 0.0)) return 1.0;
+        const double k = kd[idx(s, c)];
+        if (!(k > 0.0)) return 1.0;
+        const double R = 1.0 + rho_b[static_cast(c)] * k / theta;
+        return (R > 1.0) ? 1.0 / R : 1.0;
+    }
+
+    // ---- cross-cadence accumulators (paired with the water's) -------------
+    /// Lateral Darcy face sides, `[s*ne + e]` — the twin of `eacc_L/eacc_R`,
+    /// gathered by the owning cell at ITS firing (GW plan §3.1).
+    std::vector sacc_L, sacc_R;
+    /// `[s*n_cells+c]` mass the SURFACE handed down with its infiltration,
+    /// gathered when the GW cell fires — the twin of `xacc_from_surface`.
+    std::vector xacc_from_surface;
+    /// …and the mass owed back to the surface with saturation excess and
+    /// column rejection — the twin of `xacc_to_surface`, drained by the
+    /// surface cell.
+    std::vector xacc_to_surface;
+
+    // ---- T7.4: the 1D seams ----------------------------------------------
+    /// `[s * n_beds + b]` mass a RECHARGING node pushed down its bed,
+    /// sampled at the node's own concentration at tier-0 cadence and
+    /// gathered by the cell when it fires — the twin of the water's `nacc`.
+    std::vector nacc_mass;
+    /// `[s * n_cells + c]` mass a LEAKING conduit delivered, at the
+    /// conduit's own concentration — the twin of the water's `lacc`.
+    std::vector lacc_mass;
+    /// `[s * n_nodes]` mass the aquifer owes each 1D node, booked at the
+    /// cell's firing and flushed by the router into the node's coupling
+    /// queues. Reset per routing batch, exactly as `node_exchange_vol_` is.
+    std::vector node_out_mass;
+
+    // ---- ledgers (per species, cumulative) --------------------------------
+    // Signs follow the water ledger they mirror: a "lost_" row is mass that
+    // left the aquifer, a "gained_" row is mass that arrived.
+    std::vector lost_deep;       ///< deep percolation
+    std::vector lost_node;       ///< to a 1D node through its bed
+    std::vector lost_link;       ///< to a gaining conduit (G-X4)
+    std::vector lost_dunne;      ///< saturation excess + rejection, to the surface
+    std::vector lost_et;         ///< the intensive rows ET carried off
+    std::vector gained_infil;    ///< from the surface's infiltration
+    std::vector gained_node;     ///< from a recharging node (T7.4 seam)
+    std::vector gained_link;     ///< from a leaking conduit (T7.4 seam)
+    std::vector net_lateral;     ///< net across the domain edge (0 on a closed mesh)
+    std::vector lost_reaction;   ///< T7.2: first-order decay
+    /// Mass in both stores at the start of the run — the conservation gate's
+    /// reference (the aquifer is seeded from `[GW_INITIAL_QUALITY]`).
+    std::vector init_mass;
+    /// Internal, informational: the unsaturated ⇄ saturated handover. Not in
+    /// the balance — both ends are inside the same cell.
+    std::vector internal_recharge;
+
+    bool active() const noexcept { return n_species > 0 && n_cells > 0; }
+
+    std::size_t idx(int s, int c) const noexcept {
+        return static_cast(s) * static_cast(n_cells) +
+               static_cast(c);
+    }
+
+    void resize(int n_spec, int n_cell, int n_edges) {
+        n_species = (n_spec > 0) ? n_spec : 0;
+        n_cells   = (n_cell > 0) ? n_cell : 0;
+        const auto ns = static_cast(n_species);
+        const auto nc = static_cast(n_cells);
+        const auto ne = static_cast(n_edges > 0 ? n_edges : 0);
+        sat_mass.assign(ns * nc, 0.0);
+        unsat_mass.assign(ns * nc, 0.0);
+        sacc_L.assign(ns * ne, 0.0);
+        sacc_R.assign(ns * ne, 0.0);
+        xacc_from_surface.assign(ns * nc, 0.0);
+        xacc_to_surface.assign(ns * nc, 0.0);
+        lacc_mass.assign(ns * nc, 0.0);          // T7.4
+        // nacc_mass and node_out_mass are sized by the solver, which knows
+        // the bed and node counts.
+        lost_deep.assign(ns, 0.0);
+        lost_node.assign(ns, 0.0);
+        lost_link.assign(ns, 0.0);
+        lost_dunne.assign(ns, 0.0);
+        lost_et.assign(ns, 0.0);
+        gained_infil.assign(ns, 0.0);
+        gained_node.assign(ns, 0.0);
+        gained_link.assign(ns, 0.0);
+        net_lateral.assign(ns, 0.0);
+        lost_reaction.assign(ns, 0.0);          // T7.2
+        init_mass.assign(ns, 0.0);
+        internal_recharge.assign(ns, 0.0);
+        alpha_L.assign(nc, 1.0);                // T7.2: the row defaults
+        alpha_T.assign(nc, 0.1);
+        D_m.assign(nc, 1.0e-9);
+        rho_b.assign(nc, 0.0);
+        kd.assign(ns * nc, 0.0);
+        decay.assign(ns * nc, 0.0);
+        dispersion_limiter_binds = 0;
+    }
+
+    void clear() { *this = SubsurfaceTransportState{}; }
+
+    /// T7.4: mass in flight on the two 1D seams — booked by the producer,
+    /// not yet taken by the owner. Part of `storage`, for the same reason
+    /// the surface accumulators are.
+    double inFlight1D(int s) const noexcept {
+        double m = 0.0;
+        const auto ns = static_cast(n_species > 0 ? n_species : 1);
+        if (!nacc_mass.empty()) {
+            const auto nb = nacc_mass.size() / ns;
+            for (std::size_t b = 0; b < nb; ++b)
+                m += nacc_mass[static_cast(s) * nb + b];
+        }
+        const auto base = static_cast(s) *
+                          static_cast(n_cells);
+        for (int c = 0; c < n_cells; ++c)
+            m += lacc_mass[base + static_cast(c)];
+        return m;
+    }
+
+    /// Everything the aquifer HOLDS of one species, including mass in flight
+    /// in a side accumulator (the water's `liveStorage` rule).
+    double storage(int s) const noexcept {
+        double m = 0.0;
+        const auto base = static_cast(s) *
+                          static_cast(n_cells);
+        for (int c = 0; c < n_cells; ++c) {
+            m += sat_mass[base + static_cast(c)];
+            m += unsat_mass[base + static_cast(c)];
+            m += xacc_from_surface[base + static_cast(c)];
+            m += xacc_to_surface[base + static_cast(c)];
+        }
+        const auto ne = sacc_L.size() / (n_species > 0 ? static_cast(n_species) : 1);
+        for (std::size_t e = 0; e < ne; ++e) {
+            const auto k = static_cast(s) * ne + e;
+            m += sacc_L[k] + sacc_R[k];
+        }
+        return m + inFlight1D(s);   // T7.4
+    }
+
+    /// The storage the LEDGER can account for: holdings less the two surface
+    /// accumulators, which are always one firing out of phase with
+    /// `gained_infil` (booked when the cell gathers) and `lost_dunne`
+    /// (booked when the cell pushes). The water side's `ledgeredStorage`
+    /// makes the identical exclusion for the identical reason — the two
+    /// pending terms cancel on both sides of the balance.
+    double ledgeredStorage(int s) const noexcept {
+        double m = 0.0;
+        const auto base = static_cast(s) *
+                          static_cast(n_cells);
+        for (int c = 0; c < n_cells; ++c)
+            m += sat_mass[base + static_cast(c)] +
+                 unsat_mass[base + static_cast(c)];
+        const auto ne = sacc_L.size() / (n_species > 0 ? static_cast(n_species) : 1);
+        for (std::size_t e = 0; e < ne; ++e) {
+            const auto k = static_cast(s) * ne + e;
+            m += sacc_L[k] + sacc_R[k];
+        }
+        // T7.4: the two 1D arrival accumulators are booked into
+        // `gained_node` / `gained_link` only when the CELL gathers them, so
+        // until then they are storage the ledger has not yet named — the
+        // same phase rule the surface accumulators follow, and the reason
+        // they are counted here while `xacc_*` are not.
+        return m + inFlight1D(s);
+    }
+
+    /// T7.4 (2026-09-21): the scale a residual is judged against — what the
+    /// aquifer started with plus **every** route mass can arrive by. It lives
+    /// here, beside `residual()`, because the two must name the same channels:
+    /// T7.4 added the node and link seams as routes and the `.rpt` block's
+    /// own copy of this sum was not updated, so a deck fed only through its
+    /// beds divided a machine-precision residual by a machine-precision
+    /// denominator and printed 6 198 889.840 % beside an exact balance. One
+    /// definition, one place to add a channel to.
+    double continuityDenominator(int s) const noexcept {
+        const auto us = static_cast(s);
+        return std::fabs(init_mass[us]) + std::fabs(gained_infil[us]) +
+               std::fabs(gained_node[us]) + std::fabs(gained_link[us]) +
+               std::fabs(net_lateral[us]);
+    }
+
+    /// T7.1's conservation statement, the twin of
+    /// `SurfaceTransportState::totalIncludingLedgers`: what the aquifer holds
+    /// now, plus everything that left, minus everything that arrived, equals
+    /// what it started with. Zero to machine precision for a conserving
+    /// kernel — GW plan gate 6's stub.
+    double residual(int s) const noexcept {
+        const auto us = static_cast(s);
+        const double out = lost_deep[us] + lost_node[us] + lost_link[us] +
+                           lost_dunne[us] + lost_et[us] + lost_reaction[us];
+        const double in  = gained_infil[us] + gained_node[us] + gained_link[us] +
+                           net_lateral[us];
+        return ledgeredStorage(s) + out - in - init_mass[us];
+    }
+};
+
+}  // namespace openswmm::twoD
+
+#endif  // OPENSWMM_ENGINE_2D_SUBSURFACE_TRANSPORT_STATE_HPP
diff --git a/src/engine/CMakeLists.txt b/src/engine/CMakeLists.txt
index 22da04d8e..ea27c6709 100644
--- a/src/engine/CMakeLists.txt
+++ b/src/engine/CMakeLists.txt
@@ -40,8 +40,12 @@ file(GLOB_RECURSE OPENSWMM_ENGINE_SOURCES
     output/*.cpp
     plugins/*.cpp
     math/*.cpp
+    transport/*.cpp
+    io/*.cpp
 )
 list(FILTER OPENSWMM_ENGINE_SOURCES EXCLUDE REGEX "input/geopackage/.*")
+# io/hdf5 is gated on OPENSWMM_WITH_HDF5 and re-added below when it is on.
+list(FILTER OPENSWMM_ENGINE_SOURCES EXCLUDE REGEX "io/hdf5/.*")
 
 file(GLOB_RECURSE OPENSWMM_ENGINE_HEADERS
     RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
@@ -56,20 +60,34 @@ file(GLOB_RECURSE OPENSWMM_ENGINE_HEADERS
     output/*.hpp
     plugins/*.hpp
     math/*.hpp
+    transport/*.hpp
 )
 list(FILTER OPENSWMM_ENGINE_HEADERS EXCLUDE REGEX "input/geopackage/.*")
 
 # ---- Library target ----
+# WebAssembly (Emscripten) has no shared objects: the engine is built as a
+# STATIC archive and linked into the consumer's .wasm (openswmm.engine.wasm).
+# OPENSWMM_ENGINE_STATIC makes SWMM_ENGINE_API expand to nothing there.
+if(EMSCRIPTEN)
+    set(_OPENSWMM_ENGINE_LIB_TYPE STATIC)
+else()
+    set(_OPENSWMM_ENGINE_LIB_TYPE SHARED)
+endif()
+
 # NOTE: If there are no .cpp files yet (skeleton phase), use a placeholder.
 # Remove this condition when real sources exist.
 if(OPENSWMM_ENGINE_SOURCES)
-    add_library(openswmm_engine SHARED ${OPENSWMM_ENGINE_SOURCES})
+    add_library(openswmm_engine ${_OPENSWMM_ENGINE_LIB_TYPE} ${OPENSWMM_ENGINE_SOURCES})
 else()
     # Placeholder object library until sources are written
     file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/placeholder.cpp
          "// OpenSWMM Engine — placeholder (Phase 2+ sources not yet written)\n"
          "// See docs/MASTER_IMPLEMENTATION_PLAN.md\n")
-    add_library(openswmm_engine SHARED ${CMAKE_CURRENT_BINARY_DIR}/placeholder.cpp)
+    add_library(openswmm_engine ${_OPENSWMM_ENGINE_LIB_TYPE} ${CMAKE_CURRENT_BINARY_DIR}/placeholder.cpp)
+endif()
+
+if(EMSCRIPTEN)
+    target_compile_definitions(openswmm_engine PUBLIC OPENSWMM_ENGINE_STATIC)
 endif()
 
 # ---- Alias targets ----
@@ -122,8 +140,12 @@ target_link_libraries(openswmm_engine
 )
 
 # ---- Threads (for IOThread) ----
-find_package(Threads REQUIRED)
-target_link_libraries(openswmm_engine PRIVATE Threads::Threads)
+# Emscripten: single-threaded build (no -pthread / SharedArrayBuffer);
+# IOThread runs synchronously there (see output/IOThread.cpp).
+if(NOT EMSCRIPTEN)
+    find_package(Threads REQUIRED)
+    target_link_libraries(openswmm_engine PRIVATE Threads::Threads)
+endif()
 
 # ---- OpenMP (for parallel solver loops) ----
 # macOS/AppleClang is the only platform where the stock FindOpenMP cannot
@@ -136,7 +158,7 @@ target_link_libraries(openswmm_engine PRIVATE Threads::Threads)
 if(APPLE)
     list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
     include(${PROJECT_SOURCE_DIR}/cmake/FindOpenMP.cmake)
-else()
+elseif(NOT EMSCRIPTEN)
     find_package(OpenMP)
 endif()
 
@@ -149,7 +171,8 @@ else()
 endif()
 
 # ---- Platform-specific DLL loading ----
-if(UNIX AND NOT APPLE)
+# Emscripten: dlopen() is in libc (returns NULL without -sMAIN_MODULE), no -ldl.
+if(UNIX AND NOT APPLE AND NOT EMSCRIPTEN)
     target_link_libraries(openswmm_engine PRIVATE dl)
 elseif(APPLE)
     # dl is part of libSystem on macOS
@@ -187,27 +210,37 @@ else()
     endif()
 endif()
 
-# ---- Fast geometry / Manning kernels (opt-OUT; default ON) ----
-# The refactored engine ships with the fast cross-section table lookup
-# (reciprocal-multiply + `*inv_delta`, no per-element IEEE divide) and the fast
-# Manning friction (x*cbrt(x) instead of libm pow). Together ~10% faster DW
-# routing. These are NOT bit-exact vs legacy (ULP-level; ~1e-4 flow accumulated
-# over long runs — well inside the abs 1e-8 / rel 1e-7 gate per lookup). Turn
-# BOTH off for bit-exact legacy parity (the QA parity harness / regression
-# baselines): -DOPENSWMM_FAST_XSECT_LOOKUP=OFF -DOPENSWMM_FAST_MANNING_POW=OFF
+# ---- Fast geometry / Manning kernels (opt-IN; default OFF) ----
+# The fast cross-section table lookup (reciprocal-multiply + `*inv_delta`, no
+# per-element IEEE divide) and the fast Manning friction (x*cbrt(x) instead of
+# libm pow) are together ~10% faster DW routing, but they are NOT bit-exact vs
+# legacy (ULP-level per lookup; the error accumulates over a long run — on the
+# East Boston 5-day model, ON diverges from legacy at routing step 1, OFF stays
+# bit-identical for 133,472 steps).
+#
+# They default OFF because the SHIPPED engine — the one the GUI loads — must be
+# bit-identical to the legacy engine: that is what makes a v6-vs-5.x comparison
+# in the GUI a parity comparison rather than an apples-to-oranges one. Perf is
+# opt-in, via the `-fast` configure presets (or -D...=ON directly).
+#
+# BOTH must be ON to get the speedup and BOTH OFF for parity; do not mix.
 option(OPENSWMM_FAST_XSECT_LOOKUP
-    "Fast cross-section table lookup (reciprocal-multiply; not bit-exact vs legacy)" ON)
+    "Fast cross-section table lookup (reciprocal-multiply; NOT bit-exact vs legacy)" OFF)
 option(OPENSWMM_FAST_MANNING_POW
-    "Fast Manning friction via cbrt instead of libm pow (not bit-exact vs legacy)" ON)
+    "Fast Manning friction via cbrt instead of libm pow (NOT bit-exact vs legacy)" OFF)
 if(OPENSWMM_FAST_XSECT_LOOKUP)
     target_compile_definitions(openswmm_engine PRIVATE SWMM_XSECT_FAST_LOOKUP)
 endif()
 if(OPENSWMM_FAST_MANNING_POW)
     target_compile_definitions(openswmm_engine PRIVATE SWMM_FAST_MANNING_POW)
 endif()
-message(STATUS "OpenSWMM Engine: fast kernels — xsect_lookup=${OPENSWMM_FAST_XSECT_LOOKUP}"
-        " manning_pow=${OPENSWMM_FAST_MANNING_POW}"
-        " (ON ⇒ ~10% faster DW routing, NOT bit-exact vs legacy)")
+if(OPENSWMM_FAST_XSECT_LOOKUP OR OPENSWMM_FAST_MANNING_POW)
+    message(STATUS "OpenSWMM Engine: fast kernels — xsect_lookup=${OPENSWMM_FAST_XSECT_LOOKUP}"
+            " manning_pow=${OPENSWMM_FAST_MANNING_POW}"
+            " (~10% faster DW routing, NOT bit-exact vs legacy — do not ship)")
+else()
+    message(STATUS "OpenSWMM Engine: fast kernels OFF — bit-exact vs legacy (shipping default)")
+endif()
 
 # ---- Force-optimized override (for Debug parent builds) ----
 # When the engine is consumed as a subdirectory by a parent project that's
@@ -433,6 +466,10 @@ if(OPENSWMM_BUILD_2D)
     file(GLOB_RECURSE OPENSWMM_2D_SOURCES
         RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
         2d/data/*.cpp
+        2d/gw/*.cpp
+        2d/quality/*.cpp   # S7
+        2d/infil/*.cpp
+        2d/subsurface/*.cpp
         2d/mesh/*.cpp
         2d/solver/SurfaceFluxCalculator.cpp
         2d/coupling/*.cpp
@@ -501,6 +538,64 @@ else()
     message(STATUS "OpenSWMM Engine: 2D surface routing disabled (set -DOPENSWMM_BUILD_2D=ON to enable)")
 endif()
 
+# ---- Optional HDF5 model I/O ----
+#
+# Compiled straight into the engine rather than as a separate static library
+# (the GeoPackage pattern): it is a few translation units, it needs no
+# dependency of its own beyond HDF5, and HDF5 is already PRIVATE-linked here
+# when the 2D module is on. Its own option exists so a 2D-less build can still
+# write .h5 models. See src/engine/io/hdf5/STRATEGY.md §8.
+if(OPENSWMM_WITH_HDF5)
+    file(GLOB OPENSWMM_HDF5_SOURCES
+        RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
+        io/hdf5/*.cpp
+    )
+    target_sources(openswmm_engine PRIVATE ${OPENSWMM_HDF5_SOURCES})
+
+    # The 2D block above already resolved HDF5 when it is enabled; only look
+    # again when it is not, so the two paths cannot disagree about which HDF5
+    # the engine links.
+    if(NOT OPENSWMM_BUILD_2D)
+        find_package(hdf5 CONFIG QUIET)
+        if(hdf5_FOUND)
+            if(TARGET hdf5::hdf5-shared)
+                set(_OPENSWMM_HDF5_TARGET hdf5::hdf5-shared)
+            elseif(TARGET hdf5::hdf5-static)
+                set(_OPENSWMM_HDF5_TARGET hdf5::hdf5-static)
+            else()
+                message(FATAL_ERROR "hdf5 CONFIG package found but neither hdf5::hdf5-shared nor hdf5::hdf5-static is defined")
+            endif()
+        else()
+            find_package(HDF5 REQUIRED COMPONENTS C)
+        endif()
+    endif()
+
+    if(hdf5_FOUND)
+        target_link_libraries(openswmm_engine PRIVATE ${_OPENSWMM_HDF5_TARGET})
+    else()
+        target_link_libraries(openswmm_engine PRIVATE ${HDF5_C_LIBRARIES})
+        target_include_directories(openswmm_engine PRIVATE ${HDF5_INCLUDE_DIRS})
+    endif()
+
+    # PUBLIC so PluginFactory's own TU sees it and registers the singleton.
+    target_compile_definitions(openswmm_engine PUBLIC OPENSWMM_HAS_HDF5_MODEL=1)
+
+    if(TARGET openswmm_engine_internal)
+        target_sources(openswmm_engine_internal PRIVATE ${OPENSWMM_HDF5_SOURCES})
+        if(hdf5_FOUND)
+            target_link_libraries(openswmm_engine_internal PRIVATE ${_OPENSWMM_HDF5_TARGET})
+        else()
+            target_link_libraries(openswmm_engine_internal PRIVATE ${HDF5_C_LIBRARIES})
+            target_include_directories(openswmm_engine_internal PRIVATE ${HDF5_INCLUDE_DIRS})
+        endif()
+        target_compile_definitions(openswmm_engine_internal PUBLIC OPENSWMM_HAS_HDF5_MODEL=1)
+    endif()
+
+    message(STATUS "OpenSWMM Engine: HDF5 model I/O enabled")
+else()
+    message(STATUS "OpenSWMM Engine: HDF5 model I/O disabled (set -DOPENSWMM_WITH_HDF5=ON to enable)")
+endif()
+
 # ---- Optional GeoPackage I/O library ----
 if(OPENSWMM_WITH_GEOPACKAGE)
     add_subdirectory(input/geopackage)
@@ -549,6 +644,10 @@ if(OPENSWMM_WITH_GEOPACKAGE)
         target_link_options(openswmm_engine PRIVATE
             "LINKER:-force_load,$"
         )
+    elseif(EMSCRIPTEN)
+        # Engine is STATIC here; link options on a static archive are not
+        # applied. The wasm consumer retains swmm_gpkg_* by naming them in
+        # -sEXPORTED_FUNCTIONS, which forces wasm-ld to pull the objects.
     else()
         # GNU ld / lld accept bracketed --whole-archive; the archive path
         # must appear between the two flags.
diff --git a/src/engine/controls/Controls.cpp b/src/engine/controls/Controls.cpp
index 0c53dfcf4..d1860b3db 100644
--- a/src/engine/controls/Controls.cpp
+++ b/src/engine/controls/Controls.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Controls.cpp
  * @brief Rule-based control engine — full legacy parity implementation.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Controls.hpp"
@@ -41,7 +57,6 @@ void ControlEngine::init(const std::vector& rules) {
     // timeLastSet storage moved to ctx.links.time_last_set, owned by
     // SWMMEngine::stepRouting (P1-C09).
     link_time_last_set_.clear();
-    next_rule_eval_time_ = -1.0;
 }
 
 // ============================================================================
@@ -177,23 +192,30 @@ void ControlEngine::batchEvaluateGroup(PremiseSoA& g,
 // Main evaluate — short-circuit AND, priority dedup, modulated actions
 // ============================================================================
 
-int ControlEngine::evaluate(SimulationContext& ctx, double current_time, double dt) {
-    // ---- RULE_STEP gating (P1-C10) ----
-    // Legacy routing.c:286-290 only invokes controls_evaluate when the
-    // routing clock reaches the next configured rule-evaluation time.
-    // rule_step == 0 means "every routing step" (legacy default).
-    if (ctx.options.rule_step > 0.0) {
-        if (next_rule_eval_time_ < 0.0)
-            next_rule_eval_time_ = ctx.current_date;
-        if (ctx.current_date + 0.5 * dt / constants::SEC_PER_DAY
-            < next_rule_eval_time_) {
-            last_action_count_ = 0;
-            return 0;
-        }
-        next_rule_eval_time_ =
-            ctx.current_date + ctx.options.rule_step / constants::SEC_PER_DAY;
+int ControlEngine::evaluate(SimulationContext& ctx, double current_date, double dt,
+                            bool rule_time_reached) {
+    // ---- RULE_STEP gating ----
+    // legacy evaluateControlRules (routing.c) calls controls_evaluate only
+    // when `RuleStep == 0 || fabs(NewRoutingTime - NewRuleTime) < 1.0`;
+    // the caller owns that ms clock and passes the verdict.
+    if (!rule_time_reached) {
+        last_action_count_ = 0;
+        return 0;
     }
 
+    // legacy controls_evaluate: CurrentDate = floor(currentTime),
+    // CurrentTime = currentTime - floor(currentTime), ElapsedTime =
+    // routing.c's currentDate - StartDateTime. The date is the step's
+    // start plus 1 ms, so "SIMULATION TIME > 0" is already true on the
+    // first step and "> 0:00:10" on the step that starts at 10 s
+    // (type5-pump-test's pumps ran their first step at setting 1.0
+    // where legacy ran 1.2).
+    eval_date_    = current_date;
+    cur_date_     = std::floor(current_date);
+    cur_time_     = current_date - cur_date_;
+    elapsed_days_ = current_date - ctx.options.start_date;
+    const double current_time = current_date;  // threaded to the value getters
+
     // dt is passed in seconds (matches the rest of stepRouting).  Convert
     // to days so compareTimes() tolerances are in the same unit as the
     // LHS for SIM_TIME / CLOCK_TIME / LINK_TIMEOPEN / LINK_TIMECLOSED.
@@ -315,15 +337,23 @@ int ControlEngine::applyPendingActions(SimulationContext& ctx, double current_ti
             // the report — match that here (P1-C08).
             if (ctx.options.rpt_controls &&
                 kv.second.type == ActionType::NUMERIC) {
-                int ri = kv.second.rule_idx;
-                std::string rname = (ri >= 0 && ri < static_cast(rules_.size()))
-                    ? rules_[static_cast(ri)].name : "Rule?";
+                const int  ri    = kv.second.rule_idx;
+                const bool known = ri >= 0 && ri < static_cast(rules_.size());
+                if (known) {
+                    // Intern the rule name once; the entry carries the index
+                    // (no per-action string on a deck that toggles every step).
+                    auto& names = ctx.control_rule_names;
+                    if (names.size() < rules_.size()) names.resize(rules_.size());
+                    auto& slot = names[static_cast(ri)];
+                    if (slot != rules_[static_cast(ri)].name)
+                        slot = rules_[static_cast(ri)].name;
+                }
                 SimulationContext::ControlLogEntry entry;
                 entry.link_idx    = kv.first;
-                entry.rule_name   = std::move(rname);
+                entry.rule_idx    = known ? ri : -1;
                 entry.new_setting = kv.second.value;
-                entry.date        = ctx.current_date;
-                ctx.control_log.push_back(std::move(entry));
+                entry.date        = eval_date_;
+                ctx.logControlAction(entry);
             }
             changes++;
         }
@@ -348,10 +378,11 @@ void ControlEngine::updateActionValue(Action& a, SimulationContext& ctx,
             }
             break;
         case ActionType::TIMESERIES:
-            // Look up from timeseries using current absolute date.
-            // Matches legacy: a->value = table_tseriesLookup(&Tseries[a->tseries], currentTime, TRUE)
+            // Look up from timeseries at legacy's currentTime (the
+            // evaluation date): a->value =
+            // table_tseriesLookup(&Tseries[a->tseries], currentTime, TRUE)
             if (a.tseries_idx >= 0 && a.tseries_idx < static_cast(ctx.tables.count())) {
-                a.value = table_lookup_cursor(ctx.tables[a.tseries_idx], ctx.current_date);
+                a.value = table_lookup_cursor(ctx.tables[a.tseries_idx], eval_date_);
             }
             break;
         case ActionType::PID:
@@ -523,7 +554,7 @@ double ControlEngine::getVariableValue(const SimulationContext& ctx,
             if (idx < 0 || idx >= ctx.n_links()) return MISSING;
             if (ctx.links.setting[ui] <= 0.0) return MISSING;
             if (ui < ctx.links.time_last_set.size())
-                return ctx.current_date - ctx.links.time_last_set[ui];
+                return cur_date_ + cur_time_ - ctx.links.time_last_set[ui];
             return 0.0;
         case ConditionVar::LINK_TIMECLOSED:
             // Returns MISSING if link is open (setting > 0).
@@ -531,7 +562,7 @@ double ControlEngine::getVariableValue(const SimulationContext& ctx,
             if (idx < 0 || idx >= ctx.n_links()) return MISSING;
             if (ctx.links.setting[ui] > 0.0) return MISSING;
             if (ui < ctx.links.time_last_set.size())
-                return ctx.current_date - ctx.links.time_last_set[ui];
+                return cur_date_ + cur_time_ - ctx.links.time_last_set[ui];
             return 0.0;
 
         case ConditionVar::GAGE_RAIN:
@@ -546,31 +577,26 @@ double ControlEngine::getVariableValue(const SimulationContext& ctx,
             return total;
         }
 
-        case ConditionVar::SIM_TIME:
-            // ctx.current_time is stored in SECONDS (see TimestepController.cpp:88).
-            // Legacy uses ElapsedTime in days; convert here so SIM_TIME LHS
-            // matches the RHS parsed by parseTimeToken (decimal days).
-            // (Extension to P0-C01 — same root cause: unit mismatch.)
-            return current_time / constants::SEC_PER_DAY;
-        case ConditionVar::SIM_DATE:      return ctx.current_date;
-        case ConditionVar::CLOCK_TIME:
-            // Legacy controls.c:1851-1852 returns CurrentTime = fractional
-            // part of the day (decimal days, 0..1).  RHS is parsed in days
-            // too via datetime_strToTime, so both sides agree.  (P0-C02)
-            return ctx.current_date - std::floor(ctx.current_date);
+        // legacy getVariableValue: r_TIME = ElapsedTime (days), r_DATE =
+        // CurrentDate (the WHOLE day, so a date premise compares dates
+        // only), r_CLOCKTIME = CurrentTime (the fraction), the calendar
+        // attributes from CurrentDate. All formed by evaluate() from the
+        // step's start-plus-1-ms date.
+        case ConditionVar::SIM_TIME:      (void)current_time; return elapsed_days_;
+        case ConditionVar::SIM_DATE:      return cur_date_;
+        case ConditionVar::CLOCK_TIME:    return cur_time_;
         case ConditionVar::SIM_DAY: {
             // Matches legacy datetime.c:469-478:
             //   ((floor(date) + DateDelta) % 7) + 1
             // The DateDelta shift is essential — without it the result is
             // wrong by 6 days. (P0-C06)
-            int t = static_cast(std::floor(ctx.current_date))
-                  + openswmm::datetime::DateDelta;
+            int t = static_cast(cur_date_) + openswmm::datetime::DateDelta;
             return static_cast((t % 7) + 1);
         }
         case ConditionVar::SIM_MONTH:
-            return static_cast(datetime::monthOfYear(ctx.current_date));
+            return static_cast(datetime::monthOfYear(cur_date_));
         case ConditionVar::SIM_DAYOFYEAR:
-            return static_cast(datetime::dayOfYear(ctx.current_date));
+            return static_cast(datetime::dayOfYear(cur_date_));
     }
     return MISSING;
 }
@@ -583,8 +609,11 @@ double ControlEngine::computePIDSetting(PIDState& pid, double control_value,
                                          double current_setting, bool is_pump, double dt) {
     if (dt <= 0.0) return current_setting;
 
-    // Convert dt from seconds to minutes (matching legacy: dt *= 1440 from days)
-    double dt_min = dt / 60.0;
+    // legacy getPIDSetting receives tStep = routingStep / SECperDAY (days)
+    // and forms minutes as dt *= 1440.0 — the same two roundings here, not
+    // dt / 60 (an ulp apart for a 20 s step, and the PID integrates it:
+    // extran3-bottom-orifice-pid drifted from period 41).
+    double dt_min = (dt / constants::SEC_PER_DAY) * 1440.0;
     constexpr double TINY = 1.0e-6;
     constexpr double tolerance = 0.0001;
 
@@ -1256,12 +1285,28 @@ int ControlEngine::parseRuleText(const std::string& text, SimulationContext& ctx
             if (link_idx < 0)
                 return fail("no link named '" + toks[static_cast(k)] +
                             "' exists in the model");
+            // Legacy addAction (controls.c:1435-1461) validates the declared
+            // subtype as well as the name. LINK remains the generic spelling.
+            const auto link_type = ctx.links.type[static_cast(link_idx)];
+            if ((obj_type == "CONDUIT" && link_type != LinkType::CONDUIT) ||
+                (obj_type == "PUMP" && link_type != LinkType::PUMP) ||
+                (obj_type == "ORIFICE" && link_type != LinkType::ORIFICE) ||
+                (obj_type == "WEIR" && link_type != LinkType::WEIR) ||
+                (obj_type == "OUTLET" && link_type != LinkType::OUTLET))
+                return fail("link '" + toks[static_cast(k)] +
+                            "' is not a " + obj_type);
             k++;
 
-            // Parse attribute (STATUS or SETTING)
+            // Parse attribute — legacy addAction (controls.c) accepts only
+            // STATUS or SETTING as an action attribute; any other keyword (e.g.
+            // FLOW) is ERR_KEYWORD. v6 formerly swallowed any attribute as a
+            // numeric setting.
             if (k >= static_cast(toks.size()))
                 return fail("action is missing its attribute (STATUS or SETTING)");
             std::string attr = to_upper(toks[static_cast(k)]);
+            if (attr != "STATUS" && attr != "SETTING")
+                return fail("'" + toks[static_cast(k)] + "' is not a valid "
+                            "action attribute (expected STATUS or SETTING)");
             k++;
 
             // Skip '=' token
diff --git a/src/engine/controls/Controls.hpp b/src/engine/controls/Controls.hpp
index b3c822abb..15a8a9aad 100644
--- a/src/engine/controls/Controls.hpp
+++ b/src/engine/controls/Controls.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Controls.hpp
  * @brief Rule-based control engine — full legacy parity.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CONTROLS_HPP
@@ -193,11 +209,22 @@ class ControlEngine {
      *   - ControlValue tracking for modulated actions
      *
      * @param ctx           Simulation context.
-     * @param current_time  Current simulation time (seconds).
+     * @param current_date  legacy routing_execute's currentDate: the
+     *                      absolute date (days) of the START of the step
+     *                      plus 1 ms (swmm5.c getDateTime), from which the
+     *                      rule clock's CurrentDate (its floor), CurrentTime
+     *                      (its fraction) and ElapsedTime (minus the start
+     *                      date) are formed, as controls_evaluate does.
      * @param dt            Routing timestep (seconds).
+     * @param rule_time_reached  legacy evaluateControlRules' RULE_STEP gate
+     *                      (RuleStep == 0 || |NewRoutingTime - NewRuleTime|
+     *                      < 1 ms), decided on the caller's ms clock; false
+     *                      skips the rules (the caller still applies the
+     *                      pending target settings).
      * @returns Number of setting changes made.
      */
-    int evaluate(SimulationContext& ctx, double current_time, double dt);
+    int evaluate(SimulationContext& ctx, double current_date, double dt,
+                 bool rule_time_reached = true);
 
     // Rule parsing (from [CONTROLS] text)
     int parseRuleText(const std::string& text, SimulationContext& ctx);
@@ -224,11 +251,6 @@ class ControlEngine {
     /// Number of actions taken in the last evaluate() call.
     int lastActionCount() const { return last_action_count_; }
 
-    /// Reset the RULE_STEP timer; called when a new run begins so the
-    /// first call to evaluate() always runs.
-    /// @see Legacy: routing.c:286-290 (RuleStep gating)
-    void resetRuleStep() { next_rule_eval_time_ = -1.0; }
-
     // ========================================================================
     // SoA batch evaluation index (AD-14)
     // ========================================================================
@@ -313,14 +335,16 @@ class ControlEngine {
     // Step 6 of the parity remediation will move this to ctx.links.time_last_set.
     std::vector link_time_last_set_;
 
-    /// Next absolute date (decimal days) at which evaluate() should run.
-    /// Honors options.rule_step.  -1.0 means "not yet primed".
-    /// @see Legacy: routing.c:286-290 (NewRuleTime)
-    double next_rule_eval_time_ = -1.0;
-
     // Tracked across a single evaluate() call
     double control_value_ = 0.0;
     double set_point_     = 0.0;
+    /// legacy controls.c shared variables for the call: the currentDate
+    /// argument, CurrentDate = floor(currentDate), CurrentTime = the
+    /// fraction, ElapsedTime = currentDate - StartDateTime (days).
+    double eval_date_    = 0.0;
+    double cur_date_     = 0.0;
+    double cur_time_     = 0.0;
+    double elapsed_days_ = 0.0;
 
     // Pending action list (for priority deduplication)
     struct PendingAction {
diff --git a/src/engine/core/AtomicOutputFile.hpp b/src/engine/core/AtomicOutputFile.hpp
new file mode 100644
index 000000000..13964a907
--- /dev/null
+++ b/src/engine/core/AtomicOutputFile.hpp
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "FileIO.hpp"
+#include 
+#include 
+#include 
+#include 
+#ifdef _WIN32
+#include 
+#else
+#include 
+#endif
+
+namespace openswmm::io {
+
+// One output only: checked serialization into an exclusively created sibling,
+// followed by atomic replacement. This is not a multi-file transaction.
+class AtomicOutputFile {
+public:
+    // `binary` publishes exactly the bytes written; the default text mode lets
+    // Windows turn "\n" into "\r\n".
+    explicit AtomicOutputFile(const std::filesystem::path& destination, bool binary = false)
+        : destination_(destination)
+    {
+        namespace fs = std::filesystem;
+        std::error_code ec;
+        // Preserve ordinary Save-through-symlink semantics. A dangling link
+        // is refused rather than silently replacing the link itself.
+        if (fs::is_symlink(destination_, ec)) {
+            const auto resolved = fs::canonical(destination_, ec);
+            if (ec) { fail("resolve destination", ec); return; }
+            destination_ = resolved;
+        } else if (ec && ec != std::errc::no_such_file_or_directory) {
+            fail("inspect destination", ec); return;
+        }
+        ec.clear();
+        const auto status = fs::status(destination_, ec);
+        const bool exists = fs::exists(status);
+        if (ec && ec != std::errc::no_such_file_or_directory) {
+            fail("inspect destination", ec); return;
+        }
+        if (exists && !fs::is_regular_file(status)) {
+            fail("replace a non-regular destination", std::make_error_code(std::errc::invalid_argument));
+            return;
+        }
+        const auto writable = fs::perms::owner_write | fs::perms::group_write | fs::perms::others_write;
+        if (exists && (status.permissions() & writable) == fs::perms::none) {
+            fail("write a read-only destination", std::make_error_code(std::errc::permission_denied));
+            return;
+        }
+        static std::atomic sequence{0};
+        const auto stamp = std::chrono::steady_clock::now().time_since_epoch().count();
+        for (int attempt = 0; attempt < 32; ++attempt) {
+            const auto candidate = destination_.parent_path() /
+                (".openswmm-save-" + std::to_string(stamp) + "-" + std::to_string(sequence++));
+            file_ = fopen_path(candidate, binary ? "wbx" : "wx");
+            if (file_) { staging_ = candidate; break; }
+            if (errno != EEXIST) break;
+        }
+        if (!file_) { fail("create temporary output", systemError()); return; }
+        if (exists) {
+            fs::permissions(staging_, status.permissions(), ec);
+            if (ec) { fail("preserve destination permissions", ec); closeAndDiscard(); }
+        }
+    }
+
+    ~AtomicOutputFile() { closeAndDiscard(); }
+    AtomicOutputFile(const AtomicOutputFile&) = delete;
+    AtomicOutputFile& operator=(const AtomicOutputFile&) = delete;
+
+    FILE* stream() const { return file_; }
+    const std::string& error() const { return error_; }
+
+    bool commit()
+    {
+        if (!file_) return false;
+        bool ok = std::ferror(file_) == 0;
+        if (!ok) fail("write output", systemError());
+        if (std::fflush(file_) != 0) {
+            if (ok) fail("flush output", systemError());
+            ok = false;
+        }
+        if (ok) {
+#ifdef _WIN32
+            const int sync = ::_commit(::_fileno(file_));
+#else
+            int sync;
+            do { sync = ::fsync(::fileno(file_)); } while (sync != 0 && errno == EINTR);
+#endif
+            if (sync != 0) { fail("sync output", systemError()); ok = false; }
+        }
+        if (std::fclose(file_) != 0) {
+            if (ok) fail("close output", systemError());
+            ok = false;
+        }
+        file_ = nullptr;
+        if (!ok) return false;
+        std::error_code ec;
+        std::filesystem::rename(staging_, destination_, ec);
+        if (ec) { fail("publish output", ec); return false; }
+        staging_.clear();
+        return true;
+    }
+
+private:
+    static std::error_code systemError()
+    {
+        return errno ? std::error_code(errno, std::generic_category())
+                     : std::make_error_code(std::errc::io_error);
+    }
+    void fail(const char* operation, const std::error_code& ec)
+    {
+        error_ = "Cannot " + std::string(operation) + " '" + path_utf8(destination_) + "': " + ec.message();
+    }
+    void closeAndDiscard()
+    {
+        if (file_) { std::fclose(file_); file_ = nullptr; }
+        if (!staging_.empty()) {
+            std::error_code ec;
+            std::filesystem::remove(staging_, ec);
+        }
+    }
+    std::filesystem::path destination_, staging_;
+    FILE* file_ = nullptr;
+    std::string error_;
+};
+} // namespace openswmm::io
diff --git a/src/engine/core/Constants.hpp b/src/engine/core/Constants.hpp
index 5385bc07d..80e0cfd7d 100644
--- a/src/engine/core/Constants.hpp
+++ b/src/engine/core/Constants.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Constants.hpp
  * @brief Global physical, numerical, and model constants for OpenSWMM Engine.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CONSTANTS_HPP
@@ -78,6 +94,13 @@ constexpr double FUDGE         = 0.0001;
 /// @see Legacy: MIN_SURFAREA in consts.h
 constexpr double MIN_SURFAREA  = 12.566;  // 4*pi
 
+/// Lateral-inflow floor (cfs): a node's external, dry-weather or groundwater
+/// inflow whose magnitude is below this is dropped to zero before it joins
+/// the node's lateral inflow.
+/// @see Legacy: FLOW_TOL in consts.h; routing.c addExternalInflows,
+///      addDryWeatherInflows, addGroundwaterInflows
+constexpr double FLOW_TOL      = 0.00001;
+
 /// Minimum elevation drop for conduit slope computation (ft).
 constexpr double MIN_DELTA_Z   = 0.001;
 
diff --git a/src/engine/core/DateTime.hpp b/src/engine/core/DateTime.hpp
index df8898df2..27b5c2376 100644
--- a/src/engine/core/DateTime.hpp
+++ b/src/engine/core/DateTime.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DateTime.hpp
  * @brief DateTime utility functions — numerically identical to legacy datetime.c.
@@ -25,7 +41,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DATETIME_HPP
diff --git a/src/engine/core/ErrorCodes.cpp b/src/engine/core/ErrorCodes.cpp
index a64f798f3..41a0f4b02 100644
--- a/src/engine/core/ErrorCodes.cpp
+++ b/src/engine/core/ErrorCodes.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ErrorCodes.cpp
  * @brief Error/warning description table and formatting — legacy-compatible.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ErrorCodes.hpp"
@@ -167,9 +183,16 @@ static const std::unordered_map& error_table() {
         {611, "Virtual Junction %s connects conduits with different cross sections."},
         {613, "Virtual Junction %s has a conduit with a nonzero offset."},
         {615, "Virtual Junction %s conduit inverts do not agree at the node."},
-        {617, "Virtual Junction %s cannot receive lateral inflow."},
+        {617, "Virtual Junction %s cannot be coupled to a 2D surface mesh."},
         {619, "Virtual Junction %s requires DYNWAVE or FV flow routing."},
         {621, "too many items for Virtual Junction %s."},
+        {623, "Inlet Junction %s must connect two STREET conduits."},
+        {625, "Inlet Junction %s references an unknown inlet design."},
+        {627, "Inlet Junction %s has an invalid capture node."},
+        {629, "Inlet Junction %s has a conduit that also carries an [INLET_USAGE] entry."},
+        {631, "too many items for Inlet Junction %s."},
+        {633, "Inlet Junction %s has no inlet design assigned."},
+        {635, "Inlet %s cannot be used with the cross section of its host."},
     };
     return table;
 }
@@ -180,19 +203,27 @@ static const std::unordered_map& error_table() {
 
 static const std::unordered_map& warning_table() {
     static const std::unordered_map table = {
-        {1,  "wet weather time step reduced to recording interval for Rain Gage %s."},
-        {2,  "maximum depth increased for Node %s."},
-        {3,  "negative offset ignored for Link %s."},
-        {4,  "minimum elevation drop used for Conduit %s."},
-        {5,  "minimum slope used for Conduit %s."},
-        {6,  "dry weather time step increased to the wet weather time step."},
-        {7,  "routing time step reduced to the wet weather time step."},
-        {8,  "elevation drop exceeds length for Conduit %s."},
-        {9,  "time series interval greater than recording interval for Rain Gage %s."},
-        {10, "crest elevation is below downstream invert for regulator Link %s."},
-        {11, "non-matching attributes in Control Rule %s."},
-        {12, "inlet removed due to unsupported shape for Conduit %s."},
-        {13, "parameters for same month provided more than once for Unit Hydrograph %s."},
+        // Codes 1-13 are legacy's own, and legacy's report_writeWarningMsg
+        // prints `"%s %s"` — the text from text.h then the object ID, with
+        // NO closing period (report.c:writeWarningMsg, text.h:47-64). v6
+        // ended each of these with '.', so every deck that raises one
+        // differed from the oracle on punctuation alone: `WARNING 04:
+        // minimum elevation drop used for Conduit 31.` against legacy's
+        // `... Conduit 31`. Kept verbatim against text.h; the 6.0-only
+        // warnings below have no legacy counterpart and keep their own style.
+        {1,  "wet weather time step reduced to recording interval for Rain Gage %s"},
+        {2,  "maximum depth increased for Node %s"},
+        {3,  "negative offset ignored for Link %s"},
+        {4,  "minimum elevation drop used for Conduit %s"},
+        {5,  "minimum slope used for Conduit %s"},
+        {6,  "dry weather time step increased to the wet weather time step"},
+        {7,  "routing time step reduced to the wet weather time step"},
+        {8,  "elevation drop exceeds length for Conduit %s"},
+        {9,  "time series interval greater than recording interval for Rain Gage %s"},
+        {10, "crest elevation is below downstream invert for regulator Link %s"},
+        {11, "non-matching attributes in Control Rule %s"},
+        {12, "inlet removed due to unsupported shape for Conduit %s"},
+        {13, "parameters for same month provided more than once for Unit Hydrograph %s"},
 
         // New 6.0
         {101, "Time Series %s has duplicate x values."},
@@ -204,6 +235,11 @@ static const std::unordered_map& warning_table() {
         {105, "%s is accepted but has no effect yet under FLOW_ROUTING FV."},
         {106, "%s is a dynamic wave option and does not apply under "
               "FLOW_ROUTING FV."},
+        {107, "unreadable row(s) were skipped in the rainfall CSV for Rain "
+              "Gage %s."},
+        {108, "the Preissmann slot width cap (5% of the section top width) "
+              "overrides the requested FV_SLOT_CELERITY for %s; celerities "
+              "below the cap-implied value have no effect there."},
     };
     return table;
 }
diff --git a/src/engine/core/ErrorCodes.hpp b/src/engine/core/ErrorCodes.hpp
index 537d2b7c7..58441c6b8 100644
--- a/src/engine/core/ErrorCodes.hpp
+++ b/src/engine/core/ErrorCodes.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ErrorCodes.hpp
  * @brief Legacy-compatible error and warning codes with description lookup.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_ERROR_CODES_HPP
@@ -177,9 +193,18 @@ enum ErrorCode : int {
     ERR_VJ_XSECT_MISMATCH       = 611,  ///< Virtual Junction %s connects conduits with different cross sections
     ERR_VJ_OFFSET               = 613,  ///< Virtual Junction %s has a conduit with a nonzero offset
     ERR_VJ_INVERT_MISMATCH      = 615,  ///< Virtual Junction %s conduit inverts do not agree at the node
-    ERR_VJ_LATERAL_INFLOW       = 617,  ///< Virtual Junction %s cannot receive lateral inflow
+    ERR_VJ_LATERAL_INFLOW       = 617,  ///< Virtual Junction %s cannot be coupled to a 2D surface mesh (point laterals are allowed)
     ERR_VJ_ROUTING_MODEL        = 619,  ///< Virtual Junction %s requires DYNWAVE or FV flow routing
     ERR_VJ_EXTRA_TOKENS         = 621,  ///< too many items for Virtual Junction %s
+
+    // --- Inlet junctions (623–635) — refactored engine only ---
+    ERR_IJ_NOT_STREET           = 623,  ///< Inlet Junction %s must connect two STREET conduits (or RECT_OPEN/TRAPEZOIDAL for drop inlets)
+    ERR_IJ_DESIGN               = 625,  ///< Inlet Junction %s references an unknown inlet design
+    ERR_IJ_CAPTURE_NODE         = 627,  ///< Inlet Junction %s has an invalid capture node (missing, itself, or virtual)
+    ERR_IJ_USAGE_ON_PAIR        = 629,  ///< Inlet Junction %s conduit also carries an [INLET_USAGE] entry
+    ERR_IJ_EXTRA_TOKENS         = 631,  ///< too many items for Inlet Junction %s
+    ERR_IJ_NO_USAGE             = 633,  ///< Inlet Junction %s has no inlet design assigned
+    ERR_INLET_USAGE_SHAPE       = 635,  ///< Inlet %s cannot be used with the cross section of %s
 };
 
 // ============================================================================
@@ -249,6 +274,8 @@ enum WarnCode : int {
     WARN_2D_OPTION_RETIRED      = 104, ///< [2D_OPTIONS] %s retired with CVODE/ARKODE and was ignored
     WARN_FV_OPTION_INERT        = 105, ///< %s has no effect under FLOW_ROUTING FV
     WARN_DW_OPTION_UNDER_FV     = 106, ///< %s is a dynamic wave option and does not apply under FLOW_ROUTING FV
+    WARN_RAIN_CSV_ROWS_SKIPPED  = 107, ///< unreadable row(s) skipped in rainfall CSV for Rain Gage %s
+    WARN_FV_SLOT_CAP            = 108, ///< slot width cap (5% of top width) overrides FV_SLOT_CELERITY for %s
 };
 
 // ============================================================================
diff --git a/src/engine/core/FileIO.hpp b/src/engine/core/FileIO.hpp
new file mode 100644
index 000000000..8d7316caf
--- /dev/null
+++ b/src/engine/core/FileIO.hpp
@@ -0,0 +1,152 @@
+/**
+ * @file FileIO.hpp
+ * @brief Opening files by UTF-8 path on every platform.
+ *
+ * @details Paths reach the engine as UTF-8 `std::string` — that is what the
+ *          GUI hands over (`QString::toUtf8`), what the C API documents, and
+ *          what a UTF-8 `.inp` carries in `[FILES]`.
+ *
+ *          On POSIX a path is an opaque byte string, so UTF-8 bytes go
+ *          straight through. On Windows they do not: the narrow `char*` file
+ *          APIs — `std::fopen`, and the `const char*` `fstream` constructors —
+ *          interpret their argument in the process's ACTIVE ANSI CODE PAGE
+ *          (CP936/GBK on a Chinese system, CP1252 on a Western one), never as
+ *          UTF-8. A path such as
+ *
+ *              C:/…/模拟情景8/模拟情景[8].inp
+ *
+ *          is therefore mangled before it reaches the filesystem and the open
+ *          fails with a plain "no such file" — issue #7.
+ *
+ *          `std::filesystem::path` is the fix because on Windows it stores
+ *          `wchar_t` natively and the standard `fstream`/`fopen`-equivalent
+ *          overloads that take a `path` use the wide APIs. The trap is that
+ *          `path(const std::string&)` assumes the NATIVE NARROW encoding, so
+ *          simply switching to `fs::path` fixes nothing; the input has to be
+ *          declared as UTF-8, which is what `utf8_path()` below does.
+ *
+ * @ingroup engine_core
+ */
+
+#ifndef OPENSWMM_ENGINE_CORE_FILEIO_HPP
+#define OPENSWMM_ENGINE_CORE_FILEIO_HPP
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::io {
+
+/**
+ * @brief Interpret a UTF-8 byte string as a filesystem path.
+ *
+ * On Windows the bytes are decoded as UTF-8 and re-encoded to the native
+ * UTF-16. On POSIX they are passed through unchanged — deliberately NOT via
+ * `u8string`, because a POSIX path is any byte sequence and need not be valid
+ * UTF-8; round-tripping one through a UTF-8 decode would corrupt it.
+ */
+inline std::filesystem::path utf8_path(const std::string& utf8) {
+#ifdef _WIN32
+    return std::filesystem::path(
+        std::u8string(reinterpret_cast(utf8.data()), utf8.size()));
+#else
+    return std::filesystem::path(utf8);
+#endif
+}
+
+/**
+ * @brief Passing an `fs::path` to `utf8_path()` is always a mistake — refuse it
+ *        at compile time, on EVERY platform.
+ *
+ * The value is already a path; re-encoding it is at best a no-op and at worst
+ * the very corruption this header exists to prevent. The reason this needs a
+ * deleted overload rather than a code review is that the mistake COMPILES ON
+ * POSIX: `fs::path::string_type` is `std::string` there, so `path` converts
+ * implicitly to the `const std::string&` parameter. On Windows `string_type`
+ * is `std::wstring`, no such conversion exists, and it is a hard error — so a
+ * Linux/macOS build and a local `-fsyntax-only` check both pass and only the
+ * MSVC job fails. That cost two Windows CI cycles (b3b1590d → b814bcf8, then
+ * again at 92e63366) before this guard existed.
+ *
+ * Constrained to match ONLY an actual path: a bare overload taking
+ * `const fs::path&` would make `utf8_path("literal")` and `utf8_path(char_ptr)`
+ * ambiguous, since converting `const char*` to `std::string` and to `path` are
+ * equally good user-defined conversions. A template that matches `path`
+ * exactly wins against the conversion to `std::string` and loses for
+ * everything else, which is precisely the rule we want.
+ */
+template 
+    requires std::same_as, std::filesystem::path>
+std::filesystem::path utf8_path(P&&) = delete;
+
+/**
+ * @brief Render a path back to UTF-8 bytes — the inverse of `utf8_path()`.
+ *
+ * `path::string()` / `path::generic_string()` are the wrong tool for this on
+ * Windows: they re-encode to the native NARROW form (the ANSI code page), so a
+ * value that only passed THROUGH a `path` on its way from one UTF-8 string to
+ * another comes out mangled, which is issue #7 with an extra step. Any code
+ * that constructs a path with `utf8_path()` and then wants a `std::string`
+ * again has to come back through here.
+ *
+ * @param p         The path.
+ * @param generic   Use '/' separators (`generic_u8string`) rather than the
+ *                  native ones — needed where the result is an .inp token or
+ *                  is concatenated with '/' by hand.
+ */
+inline std::string path_utf8(const std::filesystem::path& p,
+                             bool generic = false) {
+#ifdef _WIN32
+    const std::u8string s = generic ? p.generic_u8string() : p.u8string();
+    return std::string(reinterpret_cast(s.data()), s.size());
+#else
+    // Mirror of utf8_path's POSIX branch: bytes through unchanged, never via
+    // u8string, because a POSIX path need not be valid UTF-8.
+    return generic ? p.generic_string() : p.string();
+#endif
+}
+
+/**
+ * @brief The mirror guard: `path_utf8()` takes a path, never a string.
+ *
+ * A `std::string` or `const char*` argument would silently construct the
+ * `fs::path` parameter from the NATIVE NARROW encoding — the ANSI code page on
+ * Windows — which is issue #7 itself, arrived at through the very helper meant
+ * to prevent it, and again visible only on MSVC. Convert explicitly with
+ * `utf8_path()` first if that is genuinely what was meant.
+ */
+template 
+    requires (!std::same_as, std::filesystem::path>)
+std::string path_utf8(S&&, bool = false) = delete;
+
+/**
+ * @brief `std::fopen` for a path that is ALREADY a `std::filesystem::path`.
+ *
+ * Prefer this over `fopen_utf8(p.string(), …)` at such call sites: on Windows
+ * `path::string()` re-encodes to the native NARROW form (the ANSI code page),
+ * which throws away exactly the characters this header exists to preserve.
+ *
+ * @param p    The path.
+ * @param mode An ordinary `fopen` mode string ("r", "wb", "w+b", …), ASCII.
+ * @return The stream, or `nullptr` exactly as `std::fopen` would.
+ */
+inline std::FILE* fopen_path(const std::filesystem::path& p, const char* mode) {
+#ifdef _WIN32
+    // _wfopen is the only fopen that takes a wide path. The mode is ASCII by
+    // construction, so widening it character-by-character is exact.
+    const std::wstring wmode(mode, mode + std::char_traits::length(mode));
+    return ::_wfopen(p.c_str(), wmode.c_str());
+#else
+    return std::fopen(p.c_str(), mode);
+#endif
+}
+
+inline std::FILE* fopen_utf8(const std::string& utf8, const char* mode) {
+    return fopen_path(utf8_path(utf8), mode);
+}
+
+}  // namespace openswmm::io
+
+#endif  // OPENSWMM_ENGINE_CORE_FILEIO_HPP
diff --git a/src/engine/core/FilePathPair.hpp b/src/engine/core/FilePathPair.hpp
index 87f91ec3e..c0bec12e2 100644
--- a/src/engine/core/FilePathPair.hpp
+++ b/src/engine/core/FilePathPair.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FilePathPair.hpp
  * @brief Carrier for an external file reference in a SWMM model.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FILE_PATH_PAIR_HPP
diff --git a/src/engine/core/HotStartManager.cpp b/src/engine/core/HotStartManager.cpp
index 897b00ed3..91d395411 100644
--- a/src/engine/core/HotStartManager.cpp
+++ b/src/engine/core/HotStartManager.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HotStartManager.cpp
  * @brief Hot start file I/O — implementation.
@@ -22,16 +38,23 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "HotStartManager.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "SimulationContext.hpp"
 #include "../hydrology/Runoff.hpp"
 #include "../hydrology/Groundwater.hpp"
+#ifdef OPENSWMM_HAS_2D
+#include "../2d/subsurface/SubsurfaceData.hpp"
+#include "../2d/subsurface/SubsurfaceTransportState.hpp"   // T7.5   // G1: the V5 aquifer block
+#endif
 
+#include 
 #include 
 #include 
+#include 
 #include 
 #include 
 
@@ -140,6 +163,10 @@ bool HotStartManager::write_file(const HotStartFile& hs, const std::string& path
         if (!write_pod(buf, n.depth))    return false;
         if (!write_pod(buf, n.head))     return false;
         if (!write_pod(buf, n.volume))   return false;
+        // V3 (A2a): water age, -1 = not tracked.
+        if (hs.header.version >= 3u) {
+            if (!write_pod(buf, n.age))  return false;
+        }
     }
 
     // Links
@@ -150,6 +177,10 @@ bool HotStartManager::write_file(const HotStartFile& hs, const std::string& path
         if (!write_pod(buf, l.flow))     return false;
         if (!write_pod(buf, l.depth))    return false;
         if (!write_pod(buf, l.volume))   return false;
+        // V3 (A2a): water age, -1 = not tracked.
+        if (hs.header.version >= 3u) {
+            if (!write_pod(buf, l.age))  return false;
+        }
     }
 
     // Subcatchments
@@ -171,6 +202,76 @@ bool HotStartManager::write_file(const HotStartFile& hs, const std::string& path
         }
     }
 
+    // V4 (U2, D-IQ5): species block — names, then [node * ns + s] and
+    // [link * ns + s] concentrations in the element order above.
+    if (hs.header.version >= 4u) {
+        const auto ns = static_cast(hs.species.size());
+        if (!write_pod(buf, ns)) return false;
+        for (const auto& name : hs.species)
+            if (!write_string(buf, name)) return false;
+        const std::size_t want_n = hs.nodes.size() * hs.species.size();
+        const std::size_t want_l = hs.links.size() * hs.species.size();
+        for (std::size_t i = 0; i < want_n; ++i)
+            if (!write_pod(buf, i < hs.node_species.size() ? hs.node_species[i] : 0.0))
+                return false;
+        for (std::size_t i = 0; i < want_l; ++i)
+            if (!write_pod(buf, i < hs.link_species.size() ? hs.link_species[i] : 0.0))
+                return false;
+    }
+
+    // V5 (G1): the two-zone groundwater state. Written only when a kernel
+    // actually ran, so a model without [2D_AQUIFER] still produces a V4 file
+    // and every existing reader keeps working.
+    if (hs.header.version >= 5u) {
+        if (!write_pod(buf, hs.gw_n_cells))  return false;
+        if (!write_pod(buf, hs.gw_m_layers)) return false;
+        const auto nc = static_cast(hs.gw_n_cells);
+        const std::size_t want_t =
+            nc * static_cast(hs.gw_m_layers);
+        for (std::size_t i = 0; i < nc; ++i)
+            if (!write_pod(buf, i < hs.gw_hg.size() ? hs.gw_hg[i] : 0.0))
+                return false;
+        for (std::size_t i = 0; i < nc; ++i)
+            if (!write_pod(buf, i < hs.gw_hu.size() ? hs.gw_hu[i] : 0.0))
+                return false;
+        // An empty theta block is legal and means "no cell uses closure B";
+        // it is flagged by a zero layer count so the reader does not have to
+        // infer it from a size.
+        for (std::size_t i = 0; i < want_t; ++i)
+            if (!write_pod(buf, i < hs.gw_theta_sigma.size()
+                                    ? hs.gw_theta_sigma[i] : 0.0))
+                return false;
+        const auto nl = static_cast(hs.gw_ledger.size());
+        if (!write_pod(buf, nl)) return false;
+        for (double v : hs.gw_ledger)
+            if (!write_pod(buf, v)) return false;
+    }
+
+    // T7.5 (V6): the aquifer's transported tuple. Written only when the
+    // kernel actually carried species, so an aquifer deck with no quality
+    // still produces a V5 file and every V5 reader keeps working.
+    if (hs.header.version >= 6u) {
+        const auto ns = static_cast(hs.gw_species.size());
+        if (!write_pod(buf, ns)) return false;
+        for (const auto& name : hs.gw_species)
+            if (!write_string(buf, name)) return false;
+        const std::size_t want =
+            static_cast(ns) * static_cast(hs.gw_n_cells);
+        for (std::size_t i = 0; i < want; ++i)
+            if (!write_pod(buf, i < hs.gw_sat_mass.size() ? hs.gw_sat_mass[i] : 0.0))
+                return false;
+        for (std::size_t i = 0; i < want; ++i)
+            if (!write_pod(buf, i < hs.gw_unsat_mass.size() ? hs.gw_unsat_mass[i] : 0.0))
+                return false;
+        const std::size_t want_l =
+            static_cast(ns) *
+            static_cast(HotStartFile::kGwSpeciesLedgerTerms);
+        for (std::size_t i = 0; i < want_l; ++i)
+            if (!write_pod(buf, i < hs.gw_species_ledger.size()
+                                    ? hs.gw_species_ledger[i] : 0.0))
+                return false;
+    }
+
     // Compute CRC32 over the body
     const std::string body = buf.str();
     const uint32_t crc = crc32(
@@ -179,7 +280,7 @@ bool HotStartManager::write_file(const HotStartFile& hs, const std::string& path
     );
 
     // Write body + checksum to actual file
-    std::ofstream file(path, std::ios::binary | std::ios::trunc);
+    std::ofstream file(openswmm::io::utf8_path(path), std::ios::binary | std::ios::trunc);
     if (!file) {
         tl_last_io_error = "Cannot open '" + path + "' for writing";
         return false;
@@ -197,7 +298,7 @@ bool HotStartManager::write_file(const HotStartFile& hs, const std::string& path
 // ============================================================================
 
 bool HotStartManager::read_file(HotStartFile& hs, const std::string& path) {
-    std::ifstream file(path, std::ios::binary);
+    std::ifstream file(openswmm::io::utf8_path(path), std::ios::binary);
     if (!file) {
         tl_last_io_error = "Cannot open '" + path + "' for reading";
         return false;
@@ -241,7 +342,7 @@ bool HotStartManager::read_file(HotStartFile& hs, const std::string& path) {
 
     // Header
     if (!read_pod(is, hs.header.version))    return false;
-    if (hs.header.version != 1u && hs.header.version != 2u) {
+    if (hs.header.version < 1u || hs.header.version > 6u) {
         tl_last_io_error = "Unsupported hot start version " +
                            std::to_string(hs.header.version) + " in '" + path + "'";
         return false;
@@ -261,6 +362,10 @@ bool HotStartManager::read_file(HotStartFile& hs, const std::string& path) {
         if (!read_pod(is, n.depth))  return false;
         if (!read_pod(is, n.head))   return false;
         if (!read_pod(is, n.volume)) return false;
+        // V3 (A2a): water age; pre-V3 files leave the -1 default.
+        if (hs.header.version >= 3u) {
+            if (!read_pod(is, n.age)) return false;
+        }
     }
 
     // Links
@@ -272,6 +377,10 @@ bool HotStartManager::read_file(HotStartFile& hs, const std::string& path) {
         if (!read_pod(is, l.flow))   return false;
         if (!read_pod(is, l.depth))  return false;
         if (!read_pod(is, l.volume)) return false;
+        // V3 (A2a): water age; pre-V3 files leave the -1 default.
+        if (hs.header.version >= 3u) {
+            if (!read_pod(is, l.age)) return false;
+        }
     }
 
     // Subcatchments
@@ -295,6 +404,65 @@ bool HotStartManager::read_file(HotStartFile& hs, const std::string& path) {
         }
     }
 
+    // V4 (U2, D-IQ5): species block.
+    hs.species.clear();
+    hs.node_species.clear();
+    hs.link_species.clear();
+    if (hs.header.version >= 4u) {
+        uint32_t ns = 0;
+        if (!read_pod(is, ns)) return false;
+        hs.species.resize(ns);
+        for (auto& name : hs.species)
+            if (!read_string(is, name)) return false;
+        hs.node_species.resize(hs.nodes.size() * static_cast(ns));
+        hs.link_species.resize(hs.links.size() * static_cast(ns));
+        for (auto& v : hs.node_species) if (!read_pod(is, v)) return false;
+        for (auto& v : hs.link_species) if (!read_pod(is, v)) return false;
+    }
+
+    hs.gw_n_cells  = 0;
+    hs.gw_m_layers = 0;
+    hs.gw_hg.clear();
+    hs.gw_hu.clear();
+    hs.gw_theta_sigma.clear();
+    hs.gw_ledger.clear();
+    if (hs.header.version >= 5u) {
+        if (!read_pod(is, hs.gw_n_cells))  return false;
+        if (!read_pod(is, hs.gw_m_layers)) return false;
+        const auto nc = static_cast(hs.gw_n_cells);
+        hs.gw_hg.resize(nc);
+        hs.gw_hu.resize(nc);
+        hs.gw_theta_sigma.resize(nc * static_cast(hs.gw_m_layers));
+        for (auto& v : hs.gw_hg)          if (!read_pod(is, v)) return false;
+        for (auto& v : hs.gw_hu)          if (!read_pod(is, v)) return false;
+        for (auto& v : hs.gw_theta_sigma) if (!read_pod(is, v)) return false;
+        uint32_t nl = 0;
+        if (!read_pod(is, nl)) return false;
+        hs.gw_ledger.resize(nl);
+        for (auto& v : hs.gw_ledger) if (!read_pod(is, v)) return false;
+    }
+
+    hs.gw_species.clear();
+    hs.gw_sat_mass.clear();
+    hs.gw_unsat_mass.clear();
+    hs.gw_species_ledger.clear();
+    if (hs.header.version >= 6u) {            // T7.5
+        uint32_t ns = 0;
+        if (!read_pod(is, ns)) return false;
+        hs.gw_species.resize(ns);
+        for (auto& n : hs.gw_species) if (!read_string(is, n)) return false;
+        const std::size_t want =
+            static_cast(ns) * static_cast(hs.gw_n_cells);
+        hs.gw_sat_mass.resize(want);
+        hs.gw_unsat_mass.resize(want);
+        for (auto& v : hs.gw_sat_mass)   if (!read_pod(is, v)) return false;
+        for (auto& v : hs.gw_unsat_mass) if (!read_pod(is, v)) return false;
+        hs.gw_species_ledger.resize(
+            static_cast(ns) *
+            static_cast(HotStartFile::kGwSpeciesLedgerTerms));
+        for (auto& v : hs.gw_species_ledger) if (!read_pod(is, v)) return false;
+    }
+
     hs.path = path;
     return true;
 }
@@ -342,18 +510,344 @@ bool HotStartFile::set_subcatch_runoff(const std::string& id, double v) {
 // HotStartManager::save()
 // ============================================================================
 
+// ============================================================================
+// U2 (D-IQ5): species block capture / restore
+// ============================================================================
+
+namespace {
+
+/// Fill hs.species / node_species / link_species from the live arrays:
+/// pollutants from nodes.conc / links.conc, reactions species from the
+/// msx_*_conc state when it is sized (else the GLOBAL seed). Returns true
+/// when at least one species was captured (the file then promotes to V4).
+bool captureSpeciesBlock(const SimulationContext& ctx, HotStartFile& hs) {
+    const int np = ctx.n_pollutants();
+    const int nm = ctx.reactions.configured ? ctx.reactions.n_species() : 0;
+    const int ns = np + nm;
+    if (ns <= 0) return false;
+    const auto nn = static_cast(ctx.n_nodes());
+    const auto nl = static_cast(ctx.n_links());
+    const auto uns = static_cast(ns);
+    const auto unp = static_cast(np);
+    const auto unm = static_cast(nm);
+    hs.species.clear();
+    for (int p = 0; p < np; ++p) hs.species.push_back(ctx.pollutant_names.name_of(p));
+    for (int m = 0; m < nm; ++m)
+        hs.species.push_back(ctx.reactions.species_name[static_cast(m)]);
+    hs.node_species.assign(nn * uns, 0.0);
+    hs.link_species.assign(nl * uns, 0.0);
+    const bool msx_sized = ctx.reactions.msx_node_conc.size() == nn * unm &&
+                           ctx.reactions.msx_link_conc.size() == nl * unm;
+    for (std::size_t e = 0; e < nn; ++e) {
+        for (std::size_t p = 0; p < unp; ++p)
+            if (e * unp + p < ctx.nodes.conc.size())
+                hs.node_species[e * uns + p] = ctx.nodes.conc[e * unp + p];
+        for (std::size_t m = 0; m < unm; ++m)
+            hs.node_species[e * uns + unp + m] =
+                msx_sized ? ctx.reactions.msx_node_conc[e * unm + m]
+                          : (m < ctx.reactions.init_global.size()
+                                 ? ctx.reactions.init_global[m] : 0.0);
+    }
+    for (std::size_t e = 0; e < nl; ++e) {
+        for (std::size_t p = 0; p < unp; ++p)
+            if (e * unp + p < ctx.links.conc.size())
+                hs.link_species[e * uns + p] = ctx.links.conc[e * unp + p];
+        for (std::size_t m = 0; m < unm; ++m)
+            hs.link_species[e * uns + unp + m] =
+                msx_sized ? ctx.reactions.msx_link_conc[e * unm + m]
+                          : (m < ctx.reactions.init_global.size()
+                                 ? ctx.reactions.init_global[m] : 0.0);
+    }
+    return true;
+}
+
+/// Restore the species block by NAME. Pollutants land in nodes/links.conc
+/// (+conc_old); reactions species pre-size and fill msx_*_conc, which every
+/// engine seeds from (ensureMsxState skips its GLOBAL fill once sized).
+/// Runs after initialize()'s seeds, so the file wins (D-IQ5).
+void restoreSpeciesBlock(const HotStartFile& hs, SimulationContext& ctx,
+                         const std::function& warn) {
+    if (hs.species.empty()) return;
+    const int np = ctx.n_pollutants();
+    const int nm = ctx.reactions.configured ? ctx.reactions.n_species() : 0;
+    const auto nn = static_cast(ctx.n_nodes());
+    const auto nl = static_cast(ctx.n_links());
+    const auto unp = static_cast(np);
+    const auto unm = static_cast(nm);
+    const auto uns = hs.species.size();
+
+    // Column → (is_msx, index) in this model; -1 = not carried here.
+    std::vector col_p(uns, -1), col_m(uns, -1);
+    int matched = 0;
+    for (std::size_t s = 0; s < uns; ++s) {
+        const int p = ctx.pollutant_names.find(hs.species[s]);
+        if (p >= 0) { col_p[s] = p; ++matched; continue; }
+        const int m = nm > 0 ? ctx.reactions.find_species(hs.species[s]) : -1;
+        if (m >= 0) { col_m[s] = m; ++matched; continue; }
+        warn("Hot start: species '" + hs.species[s] +
+             "' is not in the current model — its concentrations are skipped");
+    }
+    if (matched == 0) return;
+
+    bool any_msx = false;
+    for (std::size_t s = 0; s < uns; ++s) any_msx = any_msx || col_m[s] >= 0;
+    if (any_msx) {
+        auto& rx = ctx.reactions;
+        if (rx.msx_node_conc.size() != nn * unm || rx.msx_link_conc.size() != nl * unm) {
+            // Size and seed exactly as ensureMsxState would, then overwrite
+            // the restored columns below.
+            rx.msx_node_conc.assign(nn * unm, 0.0);
+            rx.msx_link_conc.assign(nl * unm, 0.0);
+            for (std::size_t e = 0; e < nn; ++e)
+                for (std::size_t m = 0; m < unm; ++m)
+                    rx.msx_node_conc[e * unm + m] =
+                        m < rx.init_global.size() ? rx.init_global[m] : 0.0;
+            for (std::size_t e = 0; e < nl; ++e)
+                for (std::size_t m = 0; m < unm; ++m)
+                    rx.msx_link_conc[e * unm + m] =
+                        m < rx.init_global.size() ? rx.init_global[m] : 0.0;
+            for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+                const auto e = static_cast(rx.init_elem_idx[k]);
+                const auto m = static_cast(rx.init_elem_species[k]);
+                if (m >= unm) continue;
+                auto& arr = rx.init_elem_is_link[k] ? rx.msx_link_conc : rx.msx_node_conc;
+                if (e * unm + m < arr.size()) arr[e * unm + m] = rx.init_elem_value[k];
+            }
+        }
+    }
+
+    for (std::size_t r = 0; r < hs.nodes.size(); ++r) {
+        const int idx = ctx.node_names.find(hs.nodes[r].id);
+        if (idx < 0) continue;   // already warned by the record pass
+        const auto e = static_cast(idx);
+        for (std::size_t s = 0; s < uns; ++s) {
+            const std::size_t src = r * uns + s;
+            if (src >= hs.node_species.size()) break;
+            const double v = hs.node_species[src];
+            if (col_p[s] >= 0) {
+                const std::size_t i = e * unp + static_cast(col_p[s]);
+                if (i < ctx.nodes.conc.size())     ctx.nodes.conc[i] = v;
+                if (i < ctx.nodes.conc_old.size()) ctx.nodes.conc_old[i] = v;
+            } else if (col_m[s] >= 0) {
+                const std::size_t i = e * unm + static_cast(col_m[s]);
+                if (i < ctx.reactions.msx_node_conc.size()) ctx.reactions.msx_node_conc[i] = v;
+            }
+        }
+    }
+    for (std::size_t r = 0; r < hs.links.size(); ++r) {
+        const int idx = ctx.link_names.find(hs.links[r].id);
+        if (idx < 0) continue;
+        const auto e = static_cast(idx);
+        for (std::size_t s = 0; s < uns; ++s) {
+            const std::size_t src = r * uns + s;
+            if (src >= hs.link_species.size()) break;
+            const double v = hs.link_species[src];
+            if (col_p[s] >= 0) {
+                const std::size_t i = e * unp + static_cast(col_p[s]);
+                if (i < ctx.links.conc.size())     ctx.links.conc[i] = v;
+                if (i < ctx.links.conc_old.size()) ctx.links.conc_old[i] = v;
+            } else if (col_m[s] >= 0) {
+                const std::size_t i = e * unm + static_cast(col_m[s]);
+                if (i < ctx.reactions.msx_link_conc.size()) ctx.reactions.msx_link_conc[i] = v;
+            }
+        }
+    }
+}
+
+
+/// G1 (V5): copy the running two-zone groundwater state into the file.
+/// @returns true when there was a kernel to capture.
+bool captureAquiferBlock(const SimulationContext& ctx, HotStartFile& hs) {
+#ifdef OPENSWMM_HAS_2D
+    const twoD::SubsurfaceState* st = ctx.twod_io.aquifer_state;
+    if (st == nullptr || !st->active || st->n_cells <= 0) return false;
+    hs.gw_n_cells = static_cast(st->n_cells);
+    hs.gw_hg = st->hg;
+    hs.gw_hu = st->hu;
+    // The sigma layers are only meaningful if some cell actually uses
+    // closure B. Writing them for an all-closure-A model would triple the
+    // block for nothing, so a zero layer count is the signal.
+    const bool any_sigma =
+        std::any_of(st->closure.begin(), st->closure.end(), [](int8_t c) {
+            return c == static_cast(twoD::GwClosure::SIGMA);
+        });
+    if (any_sigma) {
+        hs.gw_m_layers    = static_cast(st->m_layers);
+        hs.gw_theta_sigma = st->theta_sigma;
+    }
+    hs.gw_ledger = {st->led_recharge, st->led_lateral, st->led_deep,
+                    st->led_node,     st->led_dunne,   st->led_caprise,
+                    st->led_et,       st->led_infil_in, st->led_init_storage,
+                    st->led_link};   // G-X3: 10th term; the block is length-prefixed
+    return true;
+#else
+    (void)ctx; (void)hs;
+    return false;
+#endif
+}
+
+/// T7.5: the aquifer's transported tuple. Returns false when the kernel
+/// carried no species, which keeps the file at V5.
+bool captureAquiferSpeciesBlock(const SimulationContext& ctx, HotStartFile& hs) {
+#ifdef OPENSWMM_HAS_2D
+    const twoD::SubsurfaceTransportState* tr = ctx.twod_io.aquifer_transport;
+    if (tr == nullptr || !tr->active() || hs.gw_n_cells == 0) return false;
+    if (static_cast(tr->n_cells) != hs.gw_n_cells) return false;
+    hs.gw_species     = tr->row_names;
+    hs.gw_sat_mass    = tr->sat_mass;
+    hs.gw_unsat_mass  = tr->unsat_mass;
+    hs.gw_species_ledger.assign(
+        static_cast(tr->n_species) *
+            static_cast(HotStartFile::kGwSpeciesLedgerTerms), 0.0);
+    for (int s = 0; s < tr->n_species; ++s) {
+        const auto u = static_cast(s);
+        double* d = &hs.gw_species_ledger[u * HotStartFile::kGwSpeciesLedgerTerms];
+        d[0]  = tr->init_mass[u];
+        d[1]  = tr->gained_infil[u];
+        d[2]  = tr->gained_node[u];
+        d[3]  = tr->gained_link[u];
+        d[4]  = tr->net_lateral[u];
+        d[5]  = tr->lost_deep[u];
+        d[6]  = tr->lost_node[u];
+        d[7]  = tr->lost_link[u];
+        d[8]  = tr->lost_dunne[u];
+        d[9]  = tr->lost_et[u];
+        d[10] = tr->lost_reaction[u];
+    }
+    return true;
+#else
+    (void)ctx; (void)hs;
+    return false;
+#endif
+}
+
+/// …and back, matching species by NAME (§ the V6 block's note). A species
+/// the file has and this model does not is dropped with a warning; one this
+/// model has and the file does not keeps its `[GW_INITIAL_QUALITY]` seed.
+void restoreAquiferSpeciesBlock(const HotStartFile& hs, SimulationContext& ctx,
+                                const std::function& warn) {
+#ifdef OPENSWMM_HAS_2D
+    twoD::SubsurfaceTransportState* tr = ctx.twod_io.aquifer_transport;
+    if (tr == nullptr || !tr->active() || hs.gw_species.empty()) return;
+    if (static_cast(tr->n_cells) != hs.gw_n_cells) return;   // V5 already warned
+    const auto nc = static_cast(tr->n_cells);
+    std::string dropped;
+    for (std::size_t fs = 0; fs < hs.gw_species.size(); ++fs) {
+        const int row = tr->rowIndex(hs.gw_species[fs]);
+        if (row < 0) {
+            if (!dropped.empty()) dropped += ", ";
+            dropped += hs.gw_species[fs];
+            continue;
+        }
+        const auto src = fs * nc;
+        const auto dst = static_cast(row) * nc;
+        for (std::size_t c = 0; c < nc; ++c) {
+            if (src + c < hs.gw_sat_mass.size())
+                tr->sat_mass[dst + c] = hs.gw_sat_mass[src + c];
+            if (src + c < hs.gw_unsat_mass.size())
+                tr->unsat_mass[dst + c] = hs.gw_unsat_mass[src + c];
+        }
+        const auto lsrc = fs * static_cast(HotStartFile::kGwSpeciesLedgerTerms);
+        if (lsrc + 10 < hs.gw_species_ledger.size()) {
+            const double* d = &hs.gw_species_ledger[lsrc];
+            const auto u = static_cast(row);
+            tr->init_mass[u]     = d[0];
+            tr->gained_infil[u]  = d[1];
+            tr->gained_node[u]   = d[2];
+            tr->gained_link[u]   = d[3];
+            tr->net_lateral[u]   = d[4];
+            tr->lost_deep[u]     = d[5];
+            tr->lost_node[u]     = d[6];
+            tr->lost_link[u]     = d[7];
+            tr->lost_dunne[u]    = d[8];
+            tr->lost_et[u]       = d[9];
+            tr->lost_reaction[u] = d[10];
+        }
+    }
+    if (!dropped.empty())
+        warn("Hot start: the file carries aquifer species (" + dropped +
+             ") this model does not have — their stored mass was dropped. "
+             "Species are matched by name, so a [POLLUTANTS] change between "
+             "runs drops exactly what it removed and keeps the rest.");
+#else
+    (void)hs; (void)ctx; (void)warn;
+#endif
+}
+
+/// …and back. Cells are matched by INDEX, so a mismatched count is refused
+/// outright: applying cell 400's table to cell 400 of a different mesh is a
+/// silent, plausible-looking corruption, which is worse than not restarting.
+void restoreAquiferBlock(const HotStartFile& hs, SimulationContext& ctx,
+                         const std::function& warn) {
+#ifdef OPENSWMM_HAS_2D
+    twoD::SubsurfaceState* st = ctx.twod_io.aquifer_state;
+    if (st == nullptr || !st->active || hs.gw_n_cells == 0) return;
+    if (static_cast(hs.gw_n_cells) != st->n_cells) {
+        warn("Hot start: the file carries " + std::to_string(hs.gw_n_cells) +
+             " groundwater cells but this model has " +
+             std::to_string(st->n_cells) +
+             " — the aquifer state was NOT restored (cells are matched by "
+             "index; a mesh has no cell ids).");
+        return;
+    }
+    const auto nc = static_cast(st->n_cells);
+    for (std::size_t i = 0; i < nc && i < hs.gw_hg.size(); ++i)
+        st->hg[i] = std::min(std::max(hs.gw_hg[i], 0.0), st->zs[i]);
+    for (std::size_t i = 0; i < nc && i < hs.gw_hu.size(); ++i)
+        st->hu[i] = std::max(hs.gw_hu[i], 0.0);
+    if (hs.gw_m_layers > 0) {
+        if (static_cast(hs.gw_m_layers) != st->m_layers) {
+            warn("Hot start: the file has " + std::to_string(hs.gw_m_layers) +
+                 " sigma layers and this model has " +
+                 std::to_string(st->m_layers) +
+                 " — the columns were left at their seeded profiles. Set "
+                 "M_LAYERS to match, or accept the reseed.");
+        } else if (hs.gw_theta_sigma.size() == st->theta_sigma.size()) {
+            st->theta_sigma = hs.gw_theta_sigma;
+        }
+    }
+    if (hs.gw_ledger.size() >= 9) {
+        st->led_recharge     = hs.gw_ledger[0];
+        st->led_lateral      = hs.gw_ledger[1];
+        st->led_deep         = hs.gw_ledger[2];
+        st->led_node         = hs.gw_ledger[3];
+        st->led_dunne        = hs.gw_ledger[4];
+        st->led_caprise      = hs.gw_ledger[5];
+        st->led_et           = hs.gw_ledger[6];
+        st->led_infil_in     = hs.gw_ledger[7];
+        st->led_init_storage = hs.gw_ledger[8];
+        if (hs.gw_ledger.size() >= 10) st->led_link = hs.gw_ledger[9];   // G-X3
+    }
+#else
+    (void)hs; (void)ctx; (void)warn;
+#endif
+}
+
+}  // namespace
+
 HotStartFile* HotStartManager::save(const SimulationContext& ctx,
                                     const std::string& path) {
     tl_last_io_error.clear();
 
-    // Auto-promote to V2 when ctx exposes solver-internal state via accessors.
+    // Auto-promote to V2 when ctx exposes solver-internal state via
+    // accessors, and to V3 when water age is tracked (A2a — the age field
+    // rides every node/link record; V3 implies the V2 subcatch fields,
+    // written as defaults when no accessors are wired).
     const bool use_v2 = ctx.state_accessors.can_read();
 
     auto* hs = new HotStartFile();
     hs->path = path;
 
-    // Header
-    hs->header.version    = use_v2 ? 2u : 1u;
+    // Header. V4 (U2) whenever the model carries species: the block is
+    // written after the subcatchments and implies the V3 age field.
+    hs->header.version    = ctx.options.water_age ? 3u : (use_v2 ? 2u : 1u);
+    if (captureSpeciesBlock(ctx, *hs)) hs->header.version = 4u;
+    // V5 (G1) implies V4: the aquifer block sits after the species block, so
+    // a reader that stops at V4 still reads a coherent file.
+    if (captureAquiferBlock(ctx, *hs)) {
+        hs->header.version = 5u;
+        if (captureAquiferSpeciesBlock(ctx, *hs)) hs->header.version = 6u;   // T7.5
+    }
     hs->header.timestamp  = static_cast(std::time(nullptr));
     hs->header.sim_time   = ctx.current_time;
     hs->header.start_date = ctx.options.start_date;
@@ -369,6 +863,9 @@ HotStartFile* HotStartManager::save(const SimulationContext& ctx,
         hs->nodes[ui].depth  = ctx.nodes.depth[ui];
         hs->nodes[ui].head   = ctx.nodes.head[ui];
         hs->nodes[ui].volume = ctx.nodes.volume[ui];
+        if (ctx.options.water_age &&
+            ui < ctx.water_age_state.node_age.size())
+            hs->nodes[ui].age = ctx.water_age_state.node_age[ui];
     }
 
     // Links
@@ -380,6 +877,9 @@ HotStartFile* HotStartManager::save(const SimulationContext& ctx,
         hs->links[ui].flow   = ctx.links.flow[ui];
         hs->links[ui].depth  = ctx.links.depth[ui];
         hs->links[ui].volume = ctx.links.volume[ui];
+        if (ctx.options.water_age &&
+            ui < ctx.water_age_state.link_age.size())
+            hs->links[ui].age = ctx.water_age_state.link_age[ui];
     }
 
     // Subcatchments — V2 includes infil + GW state pulled via accessors
@@ -425,8 +925,15 @@ HotStartFile* HotStartManager::save(const SimulationContext& ctx,
     auto* hs = new HotStartFile();
     hs->path = path;
 
-    // Header — V2
+    // Header — V2 (V4 when the model carries species, U2)
     hs->header.version    = 2;
+    if (captureSpeciesBlock(ctx, *hs)) hs->header.version = 4u;
+    // V5 (G1) implies V4: the aquifer block sits after the species block, so
+    // a reader that stops at V4 still reads a coherent file.
+    if (captureAquiferBlock(ctx, *hs)) {
+        hs->header.version = 5u;
+        if (captureAquiferSpeciesBlock(ctx, *hs)) hs->header.version = 6u;   // T7.5
+    }
     hs->header.timestamp  = static_cast(std::time(nullptr));
     hs->header.sim_time   = ctx.current_time;
     hs->header.start_date = ctx.options.start_date;
@@ -442,6 +949,9 @@ HotStartFile* HotStartManager::save(const SimulationContext& ctx,
         hs->nodes[ui].depth  = ctx.nodes.depth[ui];
         hs->nodes[ui].head   = ctx.nodes.head[ui];
         hs->nodes[ui].volume = ctx.nodes.volume[ui];
+        if (ctx.options.water_age &&
+            ui < ctx.water_age_state.node_age.size())
+            hs->nodes[ui].age = ctx.water_age_state.node_age[ui];
     }
 
     // Links
@@ -453,6 +963,9 @@ HotStartFile* HotStartManager::save(const SimulationContext& ctx,
         hs->links[ui].flow   = ctx.links.flow[ui];
         hs->links[ui].depth  = ctx.links.depth[ui];
         hs->links[ui].volume = ctx.links.volume[ui];
+        if (ctx.options.water_age &&
+            ui < ctx.water_age_state.link_age.size())
+            hs->links[ui].age = ctx.water_age_state.link_age[ui];
     }
 
     // Subcatchments — V2: include infil + GW state
@@ -533,6 +1046,19 @@ int HotStartManager::apply(HotStartFile& hs,
         ctx.nodes.depth[i]  = rec.depth;
         ctx.nodes.head[i]   = rec.head;
         ctx.nodes.volume[i] = rec.volume;
+        // A2a: restore water age. Sizing happens once (guarded resize);
+        // both engines then seed FROM the loaded state instead of
+        // INITIAL_STATE (hotstart_loaded; legacy_seeded suppresses the
+        // mirror's first-step fill).
+        if (rec.age >= 0.0 && ctx.options.water_age) {
+            auto& ws = ctx.water_age_state;
+            if (ws.node_age.size() !=
+                static_cast(ctx.n_nodes()))
+                ws.resize(ctx.n_nodes(), ctx.n_links(), ctx.n_subcatches());
+            ws.node_age[i]     = rec.age;
+            ws.hotstart_loaded = true;
+            ws.legacy_seeded   = true;
+        }
     }
 
     // Apply link records
@@ -546,6 +1072,15 @@ int HotStartManager::apply(HotStartFile& hs,
         ctx.links.flow[i]  = rec.flow;
         ctx.links.depth[i] = rec.depth;
         ctx.links.volume[i] = rec.volume;
+        if (rec.age >= 0.0 && ctx.options.water_age) {
+            auto& ws = ctx.water_age_state;
+            if (ws.link_age.size() !=
+                static_cast(ctx.n_links()))
+                ws.resize(ctx.n_nodes(), ctx.n_links(), ctx.n_subcatches());
+            ws.link_age[i]     = rec.age;
+            ws.hotstart_loaded = true;
+            ws.legacy_seeded   = true;
+        }
     }
 
     // Apply subcatchment records — and any V2 solver-internal state via
@@ -573,6 +1108,27 @@ int HotStartManager::apply(HotStartFile& hs,
         }
     }
 
+    // V4 (U2, D-IQ5): species concentrations, by name.
+    if (hs.header.version >= 4u)
+        restoreSpeciesBlock(hs, ctx, [&](const std::string& m) {
+            hs.warnings.push_back(m);
+            if (warn_cb) warn_cb(m);
+        });
+
+    // V5 (G1): the two-zone groundwater state, by cell index.
+    if (hs.header.version >= 5u)
+        restoreAquiferBlock(hs, ctx, [&](const std::string& m) {
+            hs.warnings.push_back(m);
+            if (warn_cb) warn_cb(m);
+        });
+    // V6 (T7.5): and what is dissolved in it, by species name. After the
+    // water, because it reads `gw_n_cells` the V5 block validated.
+    if (hs.header.version >= 6u)
+        restoreAquiferSpeciesBlock(hs, ctx, [&](const std::string& m) {
+            hs.warnings.push_back(m);
+            if (warn_cb) warn_cb(m);
+        });
+
     return missing;
 }
 
@@ -625,7 +1181,7 @@ int HotStartManager::apply_legacy_routing(
         const std::string& path,
         SimulationContext& ctx,
         std::function warn_cb) {
-    std::ifstream file(path, std::ios::binary);
+    std::ifstream file(openswmm::io::utf8_path(path), std::ios::binary);
     if (!file) {
         tl_last_io_error = "Cannot open hotstart file '" + path + "'";
         return 1;
@@ -803,7 +1359,7 @@ int HotStartManager::apply_legacy_routing(
 
 int HotStartManager::save_legacy_routing(const std::string& path,
                                          const SimulationContext& ctx) {
-    std::ofstream file(path, std::ios::binary | std::ios::trunc);
+    std::ofstream file(openswmm::io::utf8_path(path), std::ios::binary | std::ios::trunc);
     if (!file) {
         tl_last_io_error = "Cannot open hotstart save file '" + path + "'";
         return 1;
diff --git a/src/engine/core/HotStartManager.hpp b/src/engine/core/HotStartManager.hpp
index f7ce3071a..7665746d9 100644
--- a/src/engine/core/HotStartManager.hpp
+++ b/src/engine/core/HotStartManager.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HotStartManager.hpp
  * @brief Hot start file manager — in-memory representation + I/O.
@@ -57,7 +73,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_HOT_START_MANAGER_HPP
@@ -84,6 +100,8 @@ struct HotStartNodeRecord {
     double      depth  = 0.0;
     double      head   = 0.0;
     double      volume = 0.0;
+    /// A2a (V3): water age (seconds); -1 = not tracked / pre-V3 file.
+    double      age    = -1.0;
 };
 
 /** @brief Link hydraulic state at hot-start save time. */
@@ -92,6 +110,8 @@ struct HotStartLinkRecord {
     double      flow   = 0.0;
     double      depth  = 0.0;
     double      volume = 0.0;
+    /// A2a (V3): water age (seconds); -1 = not tracked / pre-V3 file.
+    double      age    = -1.0;
 };
 
 /** @brief Subcatchment state at hot-start save time. */
@@ -141,6 +161,59 @@ struct HotStartFile {
     std::vector   links;
     std::vector subcatches;
 
+    /// U2 (2026-09-07, D-IQ5) — V4 species block: per-element concentrations
+    /// for every [POLLUTANTS] entry and every reactions-component species,
+    /// keyed by NAME so a file applies to a model whose species order
+    /// differs. `node_species` / `link_species` are [element * n + s] with
+    /// the same element order as `nodes` / `links`. Age keeps its per-record
+    /// field (V3); temperature is not carried (its seed paths are per
+    /// engine — a follow-up).
+    std::vector species;
+    std::vector      node_species;
+    std::vector      link_species;
+
+    /// G1 (2026-09-07) — V5 block: the two-zone groundwater state.
+    ///
+    /// A run restarted without this reruns the entire wetting history from a
+    /// dry table, which for an aquifer is not an approximation — the whole
+    /// point of the kernel is that it has memory measured in seasons. Cells
+    /// are carried by INDEX, not name, because a mesh has no cell ids; a file
+    /// whose `gw_n_cells` does not match the model is reported and skipped
+    /// rather than applied to the wrong cells.
+    ///
+    /// `gw_theta_sigma` is layer-major `[layer * n_cells + cell]`, the SoA's
+    /// own order, and is empty when no cell uses closure B. The ledger terms
+    /// ride along so a restarted run's continuity check continues the
+    /// original's instead of starting from zero against a non-zero storage.
+    uint32_t            gw_n_cells  = 0;
+    uint32_t            gw_m_layers = 0;
+    std::vector gw_hg;           ///< saturated thickness (m)
+    std::vector gw_hu;           ///< unsaturated storage (m of water)
+    std::vector gw_theta_sigma;  ///< closure-B layers, layer-major
+    std::vector gw_ledger;       ///< the cumulative terms (m3): 9, +link since G-X3
+
+    /// T7.5 (2026-09-21) — V6 block: the aquifer's TRANSPORTED tuple.
+    ///
+    /// Without it a restarted run keeps the water table's memory (V5) and
+    /// throws away what is dissolved in it, which for a plume is the whole
+    /// state. Species are carried by NAME, not by row index: a row layout
+    /// depends on `[POLLUTANTS]`, the MSX species list and the AGE /
+    /// TEMPERATURE switches, any of which can differ between the run that
+    /// wrote the file and the run that reads it. A species the reader does
+    /// not have is dropped with a warning; one it has and the file does not
+    /// simply starts from its `[GW_INITIAL_QUALITY]` seed.
+    ///
+    /// Both stores are species-major `[s * n_cells + cell]`, the kernel's
+    /// own order. `gw_species_ledger` is `[s * kGwSpeciesLedgerTerms + t]`.
+    std::vector gw_species;        ///< row names, in file order
+    std::vector      gw_sat_mass;       ///< saturated-zone mass
+    std::vector      gw_unsat_mass;     ///< column-store mass
+    std::vector      gw_species_ledger; ///< per species, cumulative
+    /// init, infil_in, node_in, link_in, lateral_net, deep, node_out,
+    /// link_out, dunne, et, reaction — the `residual` is derived, never
+    /// stored, so a file can never disagree with itself about it.
+    static constexpr int kGwSpeciesLedgerTerms = 11;
+
     std::string               path;      ///< File path (for flush-on-close)
     bool                      dirty = false; ///< True if set_*() was called
 
diff --git a/src/engine/core/InpWriter.cpp b/src/engine/core/InpWriter.cpp
index f25895c9f..171922746 100644
--- a/src/engine/core/InpWriter.cpp
+++ b/src/engine/core/InpWriter.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InpWriter.cpp
  * @brief Comprehensive .inp serialisation — round-trip identical output.
@@ -11,25 +27,32 @@
  *   TITLE, OPTIONS, EVAPORATION, TEMPERATURE, SNOWPACKS, ADJUSTMENTS,
  *   EVENTS,
  *   RAINGAGES, SUBCATCHMENTS, SUBAREAS, INFILTRATION,
+ *   AQUIFERS, GROUNDWATER, GWF,
  *   JUNCTIONS, OUTFALLS, DIVIDERS, STORAGE, CONDUITS, PUMPS, ORIFICES,
  *   WEIRS, OUTLETS, XSECTIONS, LOSSES, TRANSECTS, STREETS, INLETS,
+ *   INLET_USAGE,
  *   CONTROLS, REPORT, POLLUTANTS, LANDUSES, COVERAGES, BUILDUP, WASHOFF,
  *   LOADINGS, TREATMENT,
  *   INFLOWS, DWF, RDII, PATTERNS, TIMESERIES, CURVES,
  *   MAP, COORDINATES, VERTICES, Polygons, SYMBOLS,
  *   USER_FLAGS, USER_FLAG_VALUES, PLUGINS,
- *   2D_OPTIONS, 2D_MESH_FILE (external mode) or 2D_VERTICES, 2D_TRIANGLES,
- *   2D_VERTEX_NODE_MAP, 2D_TRIANGLE_NODE_MAP, 2D_BOUNDARY_CONDITIONS,
- *   2D_EDGE_CONVEYANCE (inline mode)
+ *   2D_OPTIONS, 2D_INFILTRATION_OPTIONS, 2D_INFILTRATION_DEFAULTS,
+ *   2D_INFILTRATION, 2D_MESH_FILE (external mode) or 2D_VERTICES,
+ *   2D_TRIANGLES, 2D_QUADS, 2D_VERTEX_NODE_MAP, 2D_TRIANGLE_NODE_MAP,
+ *   2D_BOUNDARY_CONDITIONS, 2D_EDGE_CONVEYANCE (inline mode),
+ *   2D_INITIAL_QUALITY, 2D_BOUNDARY_QUALITY
  *
  * @ingroup engine_core
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "InpWriter.hpp"
+#include "AtomicOutputFile.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "Constants.hpp"
 #include "PathResolver.hpp"
 #include "SimulationContext.hpp"
 #include "../data/StorageGeometry.hpp"
@@ -41,14 +64,32 @@
 // through ctx.twod_io — null in non-2D engine builds).
 #include "../2d/data/MeshData.hpp"
 #include "../2d/data/SolverOptions2D.hpp"
+#include "../2d/data/Report2DVars.hpp"
+#include "../2d/gw/GwTransportData.hpp"   // U4
+#include "../2d/quality/SurfaceQuality2D.hpp"   // S7
+#include "../2d/subsurface/SubsurfaceSections.hpp"   // G1
 #include "../2d/data/BoundaryData.hpp"
 #include "../2d/data/PendingRows2D.hpp"
 #include "../2d/data/Serialize2D.hpp"
 
+#ifdef OPENSWMM_HAS_2D
+// Unlike the 2D data headers above, Infil2D's grammar helpers
+// (infil2DMethodToken / infil2DDestToken / infil2DParamCount) are defined in
+// 2d/infil/Infil2D.cpp, which is compiled only when the 2D module is built —
+// so the [2D_INFILTRATION*] emission is guarded rather than runtime-checked.
+#include "../2d/infil/Infil2D.hpp"
+#endif
+
 #include 
 #include 
 #include 
 #include 
+#include 
+#include 
+
+// IO3a: the component save hook — each component writes its own config file.
+#include "../plugins/ProcessComponentRegistry.hpp"
+#include "../edit/VirtualJunctionOps.hpp"   // ij_host_conduit (SWMM 5.x profile)
 #include 
 #include 
 #include 
@@ -94,7 +135,10 @@ static void fmt_step(char (&buf)[N], double secs) {
 // Format a day-of-year integer as M/D (no leading zeros, matching legacy GUI)
 template
 static void fmt_sweep(char (&buf)[N], int doy) {
-    // Anchor to a non-leap year to get a stable month/day
+    // Anchor to a non-leap year to get a stable month/day. Clamp 366 (a
+    // value only the retired leap-year parse anchor could store, e.g. in a
+    // GeoPackage saved before the fix) to 12/31 instead of wrapping to 1/1.
+    if (doy > 365) doy = 365;
     double dt = datetime::encodeDate(2001, 1, 1) + static_cast(doy - 1);
     int y, m, d;
     datetime::decodeDate(dt, y, m, d);
@@ -128,6 +172,7 @@ static const std::unordered_map CURVE_TYPE_LABEL = {
     {static_cast(TableType::CURVE_SHAPE),      "SHAPE"},
     {static_cast(TableType::CURVE_CONTROL),    "CONTROL"},
     {static_cast(TableType::CURVE_TIDAL),      "TIDAL"},
+    {static_cast(TableType::CURVE_WEIR),       "WEIR"},
     {static_cast(TableType::CURVE_PUMP1),      "PUMP1"},
     {static_cast(TableType::CURVE_PUMP2),      "PUMP2"},
     {static_cast(TableType::CURVE_PUMP3),      "PUMP3"},
@@ -138,18 +183,64 @@ static const std::unordered_map CURVE_TYPE_LABEL = {
 static const char* nN(const SimulationContext& c, int i) {
     return (i>=0 && i=0 && i=0 && i=0 && i(c.snowpack_names.size())) ? c.snowpack_names.name_of(i).c_str() : "*";
-}
 static const char* pN(const SimulationContext& c, int i) {
     return (i>=0 && i=0 && i(i)].c_str() : "*";
+}
+
+// ---------------------------------------------------------------------------
+// Index-or-name accessors.
+//
+// Several model fields keep BOTH a resolved index and the raw name parsed from
+// the .inp (for deferred resolution). Writing the index alone emits '*' when it
+// is -1, which either fails reload with ERR_NAME (209) or silently drops the
+// reference. These helpers fall back to the retained name before giving up.
+// All returned pointers alias stable members of the context.
+// ---------------------------------------------------------------------------
+
+// [SUBCATCHMENTS] Outlet: a node, another subcatchment, or the raw name.
+// A subcatch draining to another subcatch (or itself) has outlet_node == -1,
+// so nN() alone would emit '*' and fail reload with ERR_NAME (209).
+static const char* oN(const SimulationContext& c, size_t u) {
+    const int n = c.subcatches.outlet_node[u];
+    if (n>=0 && n=0 && s=0 && g=0 && s(c.snowpack_names.size()))
+        return c.snowpack_names.name_of(s).c_str();
+    if (u < c.subcatches.snowpack_name.size() &&
+        !c.subcatches.snowpack_name[u].empty())
+        return c.subcatches.snowpack_name[u].c_str();
+    return "*";
+}
 
 static const char* xsName(int s) {
     // Indexed by LinkData::XsectShape enum values
@@ -174,13 +265,48 @@ static bool hasNT(const SimulationContext& c, NodeType t) {
 static bool isVirtualNode(const SimulationContext& c, size_t u) {
     return u < c.nodes.is_virtual.size() && c.nodes.is_virtual[u] != 0;
 }
+// Inlet junctions are virtual junctions carrying a street inlet; they emit into
+// [INLET_JUNCTIONS] instead. A node flagged is_inlet whose usage row is missing
+// or unresolved cannot be written in that grammar, so it falls back to
+// [VIRTUAL_JUNCTIONS] (with a warning) rather than disappearing.
+static int inletUsageRow(const SimulationContext& c, size_t u) {
+    if(u>=c.nodes.is_inlet.size()||!c.nodes.is_inlet[u]) return -1;
+    const int r=c.inlet_usages.find_by_node_host(static_cast(u));
+    if(r<0) return -1;
+    const auto ur=static_cast(r);
+    const int di=c.inlet_usages.design_index[ur];
+    const int ni=c.inlet_usages.node_index[ur];
+    if(di<0||di>=c.inlets.count()||ni<0||ni>=c.n_nodes()) return -1;
+    return r;
+}
+static bool isInletNode(const SimulationContext& c, size_t u) {
+    return inletUsageRow(c,u)>=0;
+}
 static bool hasRegularJunction(const SimulationContext& c) {
     for(int j=0;j(j);
         if(c.nodes.type[u]==NodeType::JUNCTION && !isVirtualNode(c,u)) return true;}
     return false;
 }
 static bool hasVirtualJunction(const SimulationContext& c) {
-    for(int j=0;j(j))) return true;
+    for(int j=0;j(j);
+        if(isVirtualNode(c,u) && !isInletNode(c,u)) return true;}
+    return false;
+}
+static bool hasInletJunction(const SimulationContext& c) {
+    for(int j=0;j(j))) return true;
+    return false;
+}
+// Placement words, [INLET_USAGE] token 9 / [INLET_JUNCTIONS] token 11.
+static const char* const kInletPlacementWords[]={"AUTOMATIC","ON_GRADE","ON_SAG"};
+// Curb-opening throat words, legacy inlet.c ThroatAngleWords order.
+static const char* const kInletThroatWords[]={"HORIZONTAL","INCLINED","VERTICAL"};
+// True when any virtual junction carries a rendering rim depth, which is what
+// widens [VIRTUAL_JUNCTIONS] to its optional third column. Models without one
+// keep writing the two-column section byte-for-byte.
+static bool hasVirtualJunctionRim(const SimulationContext& c) {
+    for(int j=0;j(j);
+        if(isVirtualNode(c,u) && !isInletNode(c,u) &&
+           u0.0) return true;}
     return false;
 }
 static bool hasLT(const SimulationContext& c, LinkType t) {
@@ -280,23 +406,318 @@ static const char* bc2d_type_token(const twoD::PendingBoundaryRow& r) {
 
 static void emit2DMeshSections(FILE* f, const SimulationContext& ctx);
 
-static void write2DSections(FILE* f, const SimulationContext& ctx,
+#ifdef OPENSWMM_HAS_2D
+// ---- [2D_INFILTRATION_OPTIONS] / _DEFAULTS / [2D_INFILTRATION] (plan §5.5) --
+//
+// §5.5.5: these are per-cell mesh attributes, so they FOLLOW THE MESH exactly
+// as [2D_VERTICES]/[2D_TRIANGLES] do — into the .2dm sidecar in external-mesh
+// mode, into the .inp when the mesh is inline. This function is therefore
+// called from exactly one place, the tail of emit2DMeshSections(), which is
+// itself invoked once per save against one destination stream; double emission
+// is impossible by construction rather than being resolved by read-side
+// precedence. Emitting into both files would be actively wrong:
+// load2DMeshExternalFile applies SIDECAR-WINS-PER-SECTION, so an .inp copy of
+// a section the .2dm also carries is silently discarded on reload.
+//
+// [2D_TRIANGLES] is deliberately NOT extended with infiltration columns
+// (§5.5.3): its columns are positional (V1 V2 V3 MANNINGS_N [INIT_DEPTH]
+// [TAG], a numeric 5th token meaning INIT_DEPTH) and appending would break
+// hand-authored meshes.
+static void emit2DInfilSections(FILE* f, const SimulationContext& ctx) {
+    const twoD::Infil2D* infil = ctx.twod_io.infil;
+    if (!infil) return;
+
+    // METHOD [P1..Pn] DEST. Parameter columns are POSITIONAL and in PROJECT
+    // UNITS (stored verbatim; Infil2D::resolve converts). Trailing columns the
+    // method does not use are trimmed with infil2DParamCount(); the one
+    // interior no-op in the legacy [INFILTRATION] layout — CURVE_NUMBER's
+    // middle column, see the table on Infil2DRow — is written as "-" so the
+    // columns after it keep their positions.
+    auto emit_row = [f](const twoD::Infil2DRow& row) {
+        std::fprintf(f, " %-20s", twoD::infil2DMethodToken(row));
+        if (!row.has_method) { std::fprintf(f, "\n"); return; }
+        const int np = twoD::infil2DParamCount(row.method);
+        for (int k = 0; k < np && k < twoD::kInfil2DMaxParams; ++k) {
+            if (row.method == InfilModel::CURVE_NUM && k == 1)
+                std::fprintf(f, " %-12s", "-");
+            else
+                std::fprintf(f, " %-12.12g", row.p[k]);
+        }
+        // E2: DEST only when the row spelled it; unspelled rows follow
+        // [2D_OPTIONS] INFIL_DESTINATION and must not freeze a copy here.
+        if (row.dest_explicit)
+            std::fprintf(f, " %s\n", twoD::infil2DDestToken(row.dest));
+        else
+            std::fprintf(f, "\n");
+    };
+
+    if (infil->options().infil_step > 0.0) {
+        char sb[32];
+        fmt_step(sb, infil->options().infil_step);
+        sec(f, "2D_INFILTRATION_OPTIONS");
+        std::fprintf(f, ";;%-20s %s\n", "Parameter", "Value");
+        std::fprintf(f, "%-22s %s\n", "INFIL_STEP", sb);
+    }
+
+    if (!infil->defaults().empty()) {
+        sec(f, "2D_INFILTRATION_DEFAULTS");
+        std::fprintf(f, ";;%-14s %-20s %-12s %-12s %-12s %-12s %-12s %s\n",
+                     "TAG", "METHOD", "P1", "P2", "P3", "P4", "P5", "DEST");
+        for (const auto& d : infil->defaults()) {
+            std::fprintf(f, "%-16s", d.tag.c_str());
+            emit_row(d.row);
+        }
+    }
+
+    if (!infil->overrides().empty()) {
+        sec(f, "2D_INFILTRATION");
+        std::fprintf(f, ";;%-14s %-20s %-12s %-12s %-12s %-12s %-12s %s\n",
+                     "CELL", "METHOD", "P1", "P2", "P3", "P4", "P5", "DEST");
+        for (const auto& o : infil->overrides()) {
+            // CELL is 1-BASED in the file (tri is 0-based internally).
+            std::fprintf(f, "%-16d", o.tri + 1);
+            emit_row(o.row);
+        }
+    }
+}
+#endif // OPENSWMM_HAS_2D
+
+// ---- U4 (2026-09-07) — [GW_*] subsurface-transport authoring sections -----
+//
+// Round-trip fidelity is the whole contract in this release: the kernel does
+// not run these rows, so a save that lost or reshaped one would be the ONLY
+// observable, and it would be silent. Every row is written back with the
+// scope token it was authored with; nothing is expanded, resolved or
+// defaulted away. The FILE sidecar is referenced, not inlined (its rows
+// carry layer == -2).
+// ---- S7 (2026-09-19) — [2D_COVERAGES] / [2D_LOADINGS] / [2D_CURB_LENGTH] ----
+// Echoed with the scope token they were authored with (GLOBAL < TAG < CELL
+// is the reader's ladder, not a writer expansion).
+static void emitSurfaceQualitySections(FILE* f, const SimulationContext& ctx) {
+    const twoD::SurfaceQuality2D* sq = ctx.twod_io.surface_quality;
+    if (!sq || !sq->authored()) return;
+    if (!sq->coverage_rows.empty()) {
+        sec(f, "2D_COVERAGES");
+        std::fprintf(f, ";;%-14s %-16s %-8s ...\n", "Scope", "LandUse", "Percent");
+        for (const auto& r : sq->coverage_rows) {
+            std::fprintf(f, "%-16s", twoD::formatSqScope(r.key).c_str());
+            for (const auto& u : r.uses) std::fprintf(f, " %-16s %8.3f", u.first.c_str(), u.second);
+            std::fprintf(f, "\n");
+        }
+    }
+    if (!sq->loading_rows.empty()) {
+        sec(f, "2D_LOADINGS");
+        std::fprintf(f, ";;%-14s %-16s %-10s\n", "Scope", "Species", "Buildup");
+        for (const auto& r : sq->loading_rows)
+            std::fprintf(f, "%-16s %-16s %10.4f\n", twoD::formatSqScope(r.key).c_str(),
+                         r.species.c_str(), r.value);
+    }
+    if (!sq->curb_rows.empty()) {
+        sec(f, "2D_CURB_LENGTH");
+        std::fprintf(f, ";;%-14s %-10s\n", "Scope", "Length");
+        for (const auto& r : sq->curb_rows)
+            std::fprintf(f, "%-16s %10.4f\n", twoD::formatSqScope(r.key).c_str(), r.length);
+    }
+}
+
+static void emitGwTransportSections(FILE* f, const SimulationContext& ctx) {
+    const twoD::GwTransportData* gw = ctx.twod_io.gw;
+    if (!gw || gw->empty()) return;
+
+    auto scope_col = [](const twoD::GwScope s, const std::string& tag, int cell,
+                        char* buf, std::size_t n) {
+        switch (s) {
+            case twoD::GwScope::TAG:
+                std::snprintf(buf, n, "TAG %s", tag.c_str());
+                break;
+            case twoD::GwScope::CELL:
+                std::snprintf(buf, n, "CELL %d", cell + 1);   // 1-based in file
+                break;
+            default:
+                std::snprintf(buf, n, "*");
+                break;
+        }
+    };
+    char sc[128];
+
+    // [GW_TRANSPORT_OPTIONS] — every key, so the file states the model
+    // (unlike [2D_OPTIONS], where the defaults are the pre-existing
+    // behaviour and omission means "unchanged").
+    {
+        const auto& o = gw->options;
+        sec(f, "GW_TRANSPORT_OPTIONS");
+        std::fprintf(f, ";;%-22s %s\n", "Parameter", "Value");
+        std::fprintf(f, "%-24s %s\n", "TRANSPORT_POLLUTANTS",  o.transport_pollutants  ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s\n", "TRANSPORT_MSX",         o.transport_msx         ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s\n", "TRANSPORT_AGE",         o.transport_age         ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s\n", "TRANSPORT_TEMPERATURE", o.transport_temperature ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s\n", "DISPERSION",            o.dispersion ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s\n", "CONDUCTION",            o.conduction ? "YES" : "NO");
+        std::fprintf(f, "%-24s %s%s%s\n", "SURFACE_THERMAL_BC",
+                     o.surface_thermal_bc.c_str(),
+                     o.surface_thermal_arg.empty() ? "" : " ",
+                     o.surface_thermal_arg.c_str());
+        // Every DEEP_THERMAL_BC kind carries an argument (a flux, a
+        // temperature or a series name), so an empty one means the deck never
+        // authored the key. Writing the bare default kind would emit
+        // "DEEP_THERMAL_BC GEOTHERMAL_FLUX" — which the reader refuses for
+        // want of a value, making the saved file unloadable.
+        if (!o.deep_thermal_arg.empty()) {
+            if (o.deep_depth > 0.0)
+                std::fprintf(f, "%-24s %s %s DEPTH %.12g\n", "DEEP_THERMAL_BC",
+                             o.deep_thermal_bc.c_str(),
+                             o.deep_thermal_arg.c_str(), o.deep_depth);
+            else
+                std::fprintf(f, "%-24s %s %s\n", "DEEP_THERMAL_BC",
+                             o.deep_thermal_bc.c_str(),
+                             o.deep_thermal_arg.c_str());
+        }
+        std::fprintf(f, "%-24s %s\n", "THERMAL_MIXING", o.thermal_mixing.c_str());
+        std::fprintf(f, "%-24s %.12g\n", "C_DIFF", o.c_diff);
+    }
+
+    if (!gw->params.empty()) {
+        sec(f, "GW_TRANSPORT_PARAMS");
+        std::fprintf(f, ";;%-14s %-9s %-7s %-9s %-7s %-8s %-8s %-9s %-9s %s\n",
+                     "Scope", "rho_s", "c_s", "lambda_s", "a_s", "alpha_L",
+                     "alpha_T", "D_m", "D_v", "geo_flux");
+        for (const auto& r : gw->params) {
+            scope_col(r.scope, r.tag, r.cell, sc, sizeof sc);
+            std::fprintf(f,
+                "%-16s %-9.12g %-7.12g %-9.12g %-7.12g %-8.12g %-8.12g "
+                "%-9.12g %-9.12g %.12g\n",
+                sc, r.rho_s, r.c_s, r.lambda_s, r.a_s, r.alpha_L, r.alpha_T,
+                r.D_m, r.D_v, r.geo_flux);
+        }
+    }
+
+    if (!gw->sorption.empty()) {
+        sec(f, "GW_SORPTION");
+        std::fprintf(f, ";;%-14s %-16s %-12s %s\n", "Scope", "Species",
+                     "Kd(L/kg)", "Decay(1/d)");
+        for (const auto& r : gw->sorption) {
+            scope_col(r.scope, r.tag, r.cell, sc, sizeof sc);
+            if (r.decay >= 0.0)
+                std::fprintf(f, "%-16s %-16s %-12.12g %.12g\n", sc,
+                             r.species.c_str(), r.kd, r.decay);
+            else
+                std::fprintf(f, "%-16s %-16s %-12.12g -\n", sc,
+                             r.species.c_str(), r.kd);
+        }
+    }
+
+    {
+        bool any_inline = false;
+        for (const auto& r : gw->initial_quality)
+            if (r.layer != -2) { any_inline = true; break; }
+        if (any_inline || !gw->initial_quality_file.empty()) {
+            sec(f, "GW_INITIAL_QUALITY");
+            if (!gw->initial_quality_file.empty())
+                std::fprintf(f, "%-16s %s\n", "FILE",
+                             gw->initial_quality_file.c_str());
+            std::fprintf(f, ";;%-14s %-14s %-16s %s\n", "Scope", "Zone",
+                         "Species", "Value");
+            for (const auto& r : gw->initial_quality) {
+                if (r.layer == -2) continue;   // the FILE's row
+                scope_col(r.scope, r.tag, r.cell, sc, sizeof sc);
+                char zone[32];
+                if (r.zone == twoD::GwZone::LAYER)
+                    std::snprintf(zone, sizeof zone, "LAYER %d", r.layer);
+                else
+                    std::snprintf(zone, sizeof zone, "%s", twoD::gwZoneToken(r.zone));
+                std::fprintf(f, "%-16s %-14s %-16s %.12g\n", sc, zone,
+                             r.species.c_str(), r.value);
+            }
+        }
+    }
+
+    if (!gw->boundary_quality.empty()) {
+        sec(f, "GW_BOUNDARY_QUALITY");
+        std::fprintf(f, ";;%-6s %-6s %-16s %-10s %s\n", "Cell", "Edge",
+                     "Species", "Kind", "Value/Series");
+        for (const auto& r : gw->boundary_quality) {
+            // CELL 1-based, EDGE 0-based (0..nv-1 of its own cell).
+            if (!r.ts_name.empty())
+                std::fprintf(f, "%-8d %-6d %-16s %-10s %s\n", r.cell + 1, r.edge,
+                             r.species.c_str(), r.kind.c_str(), r.ts_name.c_str());
+            else
+                std::fprintf(f, "%-8d %-6d %-16s %-10s %.12g\n", r.cell + 1, r.edge,
+                             r.species.c_str(), r.kind.c_str(), r.value);
+        }
+    }
+
+    if (!gw->sources.empty()) {
+        sec(f, "GW_SOURCES");
+        std::fprintf(f, ";;%-12s %-16s %-16s %s\n", "Name", "Location",
+                     "Flow", "Species terms");
+        for (const auto& r : gw->sources) {
+            char loc[128];
+            if (r.by_xy)
+                std::snprintf(loc, sizeof loc, "XY %.12g %.12g", r.x, r.y);
+            else if (r.scope == twoD::GwScope::TAG)
+                std::snprintf(loc, sizeof loc, "TAG %s", r.tag.c_str());
+            else
+                std::snprintf(loc, sizeof loc, "CELL %d", r.cell + 1);
+            std::fprintf(f, "%-14s %-16s FLOW ", r.name.c_str(), loc);
+            if (!r.flow_ts.empty()) std::fprintf(f, "%-12s", r.flow_ts.c_str());
+            else                    std::fprintf(f, "%-12.12g", r.flow);
+            for (const auto& t : r.species) {
+                if (!t.ts_name.empty())
+                    std::fprintf(f, " %s %s %s", t.species.c_str(),
+                                 t.kind.c_str(), t.ts_name.c_str());
+                else
+                    std::fprintf(f, " %s %s %.12g", t.species.c_str(),
+                                 t.kind.c_str(), t.value);
+            }
+            std::fprintf(f, "\n");
+        }
+    }
+}
+
+// Reference tokens always use final paths. Only physical writes are redirected.
+static std::string mappedOutputPath(const std::string& finalPath,
+                                    InpWriteOptions::OutputKind kind,
+                                    const InpWriteOptions& opts,
+                                    std::vector* warnings) {
+    if (!opts.map_output) return finalPath;
+    const std::string staged = opts.map_output(finalPath, kind);
+    std::error_code ec;
+    bool aliases = staged == finalPath;
+    if (!staged.empty() && !aliases) {
+        aliases = std::filesystem::equivalent(io::utf8_path(staged), io::utf8_path(finalPath), ec);
+        const auto a = std::filesystem::weakly_canonical(io::utf8_path(staged), ec);
+        if (!ec) {
+            const auto b = std::filesystem::weakly_canonical(io::utf8_path(finalPath), ec);
+            if (!ec && a == b) aliases = true;
+        }
+    }
+    if (staged.empty() || aliases) {
+        if (warnings) warnings->push_back("Cannot stage output '" + finalPath
+            + "': callback refused output or returned its final destination");
+        return {};
+    }
+    return staged;
+}
+
+static bool write2DSections(FILE* f, const SimulationContext& ctx,
                             const std::string& dst_dir,
                             bool force_abs_paths,
-                            std::vector* warnings) {
+                            std::vector* warnings,
+                            const InpWriteOptions& opts) {
     const auto& tio = ctx.twod_io;
-    if (!tio.mesh || !tio.options) return;
+    if (!tio.mesh || !tio.options) return true;
     const auto& mesh = *tio.mesh;
     const auto& o    = *tio.options;
 
     const bool has_mesh = mesh.n_vertices() > 0 && mesh.n_triangles() > 0;
     const bool external = !o.mesh_file.empty();
-    if (!has_mesh && !external) return;
+    if (!has_mesh && !external) return true;
 
     // ---- [2D_OPTIONS] -----------------------------------------------------
     // Exact key set accepted by parse2DOptionsLine — nothing else (unknown
     // keys are parse errors on reload).
-    static const char* sRainMode[]  = {"NATURAL_NEIGHBOUR", "SYSTEM", "NONE"};
+    static const char* sRainMode[]  = {"NATURAL_NEIGHBOUR", "SYSTEM", "NONE",
+                                       "NEAREST_NEIGHBOUR"};   // RainfallMode order
     sec(f, "2D_OPTIONS");
     std::fprintf(f, ";;%-20s %s\n", "Parameter", "Value");
     std::fprintf(f, "%-22s %.12g\n", "MAX_TIMESTEP",      o.max_timestep);
@@ -307,7 +728,7 @@ static void write2DSections(FILE* f, const SimulationContext& ctx,
     std::fprintf(f, "%-22s %.12g\n", "COUPLING_SYNC",     o.coupling_sync);
     std::fprintf(f, "%-22s %s\n",    "RAINFALL_MODE",
                  sRainMode[static_cast(o.rainfall_mode) >= 0 &&
-                           static_cast(o.rainfall_mode) <= 2
+                           static_cast(o.rainfall_mode) <= 3
                                ? static_cast(o.rainfall_mode) : 0]);
     std::fprintf(f, "%-22s %s\n",    "REPORT_2D", o.report_2d ? "YES" : "NO");
     std::fprintf(f, "%-22s %s\n",    "CELL_CLOSURE",
@@ -318,6 +739,16 @@ static void write2DSections(FILE* f, const SimulationContext& ctx,
     std::fprintf(f, "%-22s %.12g\n", "VFR_MIN_WET_FRAC",  o.vfr_min_wet_frac);
     // Explicit-marcher configuration (the only 2D integrator).
     std::fprintf(f, "%-22s %s\n",    "INTEGRATOR",        "EXPLICIT");
+    // Momentum closure: the LOCAL_INERTIAL default is omitted (option-default
+    // rule — pre-2026-09 files round-trip byte-identically).
+    if (o.momentum == twoD::Momentum2D::FULL_SWE)
+        std::fprintf(f, "%-22s %s\n", "MOMENTUM_EQUATION", "FULL_SWE");
+    else if (o.momentum == twoD::Momentum2D::DIFFUSIVE_WAVE)
+        std::fprintf(f, "%-22s %s\n", "MOMENTUM_EQUATION", "DIFFUSIVE_WAVE");
+    if (o.reconstruction_order != 1)
+        std::fprintf(f, "%-22s %d\n", "RECONSTRUCTION_ORDER", o.reconstruction_order);
+    if (o.front_rebuild >= 0)
+        std::fprintf(f, "%-22s %s\n", "FRONT_REBUILD", o.front_rebuild ? "YES" : "NO");
     std::fprintf(f, "%-22s %.12g\n", "THETA",             o.theta);
     std::fprintf(f, "%-22s %.12g\n", "CFL_NUMBER",        o.cfl_number);
     std::fprintf(f, "%-22s %.12g\n", "H_MOVE",            o.h_move);
@@ -327,18 +758,90 @@ static void write2DSections(FILE* f, const SimulationContext& ctx,
                  o.advection ? "YES" : "NO");
     std::fprintf(f, "%-22s %s\n",    "COUPLING_AREA",
                  o.coupling_area_auto ? "AUTO" : "DEFAULT");
-    if (!o.output_file.empty())
-        std::fprintf(f, "%-22s %s\n", "OUTPUT_FILE", o.output_file.c_str());
+    if (o.dispersion > 0.0)   // S2: default 0 is omitted (option-default rule)
+        std::fprintf(f, "%-22s %.12g\n", "DISPERSION", o.dispersion);
+    {
+        static const char* sBackend2D[] = {"CPU","AUTO","OMP","CUDA","HIP","SYCL"};
+        const int bi = static_cast(o.backend);
+        std::fprintf(f, "%-22s %s\n", "BACKEND",
+                     (bi >= 0 && bi <= 5) ? sBackend2D[bi] : "AUTO");
+    }
+    if (!o.output_file.empty()) {
+        const std::string of_tok =
+            emit_path_token(o.output_file, dst_dir, force_abs_paths, warnings);
+        if (!of_tok.empty())
+            std::fprintf(f, "%-22s %s\n", "OUTPUT_FILE", of_tok.c_str());
+    }
+    // Results-file size controls — option-default rule: only non-defaults are
+    // emitted so pre-2026-09 files round-trip byte-identically.
+    if (o.output_precision != twoD::OutputPrecision2D::FLOAT32)
+        std::fprintf(f, "%-22s %s\n", "OUTPUT_PRECISION", "FLOAT64");
+    if (o.output_compression != 4)
+        std::fprintf(f, "%-22s %d\n", "OUTPUT_COMPRESSION", o.output_compression);
+    if ((o.report_2d_vars & twoD::report2d::ALL_MASK) != twoD::report2d::DEFAULT_MASK)
+        std::fprintf(f, "%-22s %s\n", "REPORT_2D_VARIABLES",
+                     twoD::report2d::formatMask(o.report_2d_vars).c_str());
+    if (!o.report_2d_species.empty())
+        std::fprintf(f, "%-22s %s\n", "REPORT_2D_SPECIES",
+                     twoD::report2d::formatSpecies(o.report_2d_species).c_str());
+    if (o.report_2d_step > 0.0)
+        std::fprintf(f, "%-22s %s\n", "REPORT_2D_STEP",
+                     twoD::report2d::formatStep(o.report_2d_step).c_str());
+
+    // ---- E2 process enables — non-defaults only (a deck without them is
+    // written back without them). INFIL_STEP is not emitted here: its
+    // single source of truth is Infil2D::options(), written as
+    // [2D_INFILTRATION_OPTIONS] beside the rows (§5.5.5, sidecar-follows-mesh).
+    if (o.infiltration >= 0)
+        std::fprintf(f, "%-22s %s\n", "INFILTRATION", o.infiltration ? "YES" : "NO");
+    if (!o.infil_default_method.empty())
+        std::fprintf(f, "%-22s %s\n", "INFIL_DEFAULT_METHOD", o.infil_default_method.c_str());
+    if (!o.infil_destination.empty() && o.infil_destination != "LOST")
+        std::fprintf(f, "%-22s %s\n", "INFIL_DESTINATION", o.infil_destination.c_str());
+    if (o.evaporation != 1)
+        std::fprintf(f, "%-22s %s\n", "EVAPORATION", o.evaporation == 0 ? "NO" : "CLIMATE");
+    if (!o.transport_pollutants)  std::fprintf(f, "%-22s NO\n", "TRANSPORT_POLLUTANTS");
+    if (!o.transport_msx)         std::fprintf(f, "%-22s NO\n", "TRANSPORT_MSX");
+    if (!o.transport_age)         std::fprintf(f, "%-22s NO\n", "TRANSPORT_AGE");
+    if (!o.transport_temperature) std::fprintf(f, "%-22s NO\n", "TRANSPORT_TEMPERATURE");
+    // U5 — the 2D groundwater process enable. AUTO is the default and is not
+    // written (same rule as INFILTRATION). GW_ET is NOT emitted here: it is an
+    // alias that open() folds into [2D_AQUIFER_OPTIONS], which writes it —
+    // emitting it in both places would double-author one setting.
+    if (o.groundwater >= 0)
+        std::fprintf(f, "%-22s %s\n", "GROUNDWATER", o.groundwater ? "YES" : "NO");
 
     // ---- [2D_MESH_FILE] — keep the reference, refresh the sidecar ----------
     if (external) {
-        std::string tok = o.mesh_file;
-        if (!force_abs_paths && !dst_dir.empty() && io::isAbsolutePath(tok)) {
-            auto r = io::makeRelative(tok, dst_dir);
-            if (warnings && r.classification != io::PathClass::Relative
-                && !r.warning.empty())
-                warnings->push_back(r.warning);
-            tok = r.path;
+        // TWO regimes, and the difference matters on Save-As:
+        //
+        //  * has_mesh — the mesh is in memory, so the sidecar below is REWRITTEN
+        //    at the token's destination-resolved location. The mesh therefore
+        //    TRAVELS with the .inp and the stored token stays correct as-is
+        //    (only an absolute token needs rebasing, so the model does not carry
+        //    a machine-specific path). Re-anchoring here would be actively
+        //    wrong: it would point the reference back at the source folder AND
+        //    make Save-As overwrite the original .2dm.
+        //
+        //  * !has_mesh — nothing is written (the external mesh failed to load,
+        //    or the model was opened leniently). A bare relative token then
+        //    silently starts resolving against the NEW directory, where no mesh
+        //    exists, and the saved model opens 1D-only with no diagnostic. Here
+        //    the reference must be re-anchored against `.absolute` — which
+        //    resolve_external_file_slots filled from the SOURCE .inp dir — so it
+        //    keeps pointing at the file that actually holds the mesh.
+        std::string tok;
+        if (has_mesh) {
+            tok = o.mesh_file.original;
+            if (!force_abs_paths && !dst_dir.empty() && io::isAbsolutePath(tok)) {
+                auto r = io::makeRelative(tok, dst_dir);
+                if (warnings && r.classification != io::PathClass::Relative
+                    && !r.warning.empty())
+                    warnings->push_back(r.warning);
+                tok = r.path;
+            }
+        } else {
+            tok = emit_path_token(o.mesh_file, dst_dir, force_abs_paths, warnings);
         }
         sec(f, "2D_MESH_FILE");
         std::fprintf(f, "FILE %s\n", tok.c_str());
@@ -351,31 +854,45 @@ static void write2DSections(FILE* f, const SimulationContext& ctx,
         // never clobbered with emptiness.
         if (has_mesh) {
             namespace fs = std::filesystem;
-            fs::path sp(tok);
-            if (sp.is_relative() && !dst_dir.empty()) sp = fs::path(dst_dir) / sp;
+            // utf8_path, not fs::path(std::string): the emitted token and the
+            // destination directory are UTF-8 (issue #7).
+            fs::path sp = openswmm::io::utf8_path(tok);
+            if (sp.is_relative() && !dst_dir.empty())
+                sp = openswmm::io::utf8_path(dst_dir) / sp;
+            const std::string physical = mappedOutputPath(io::path_utf8(sp),
+                InpWriteOptions::OutputKind::Mesh, opts, warnings);
+            if (physical.empty()) return false;
+            sp = io::utf8_path(physical);
             std::error_code ec;
             if (sp.has_parent_path()) fs::create_directories(sp.parent_path(), ec);
-            if (FILE* sf = std::fopen(sp.string().c_str(), "w")) {
+            if (ec) {
+                if (warnings) warnings->push_back("Cannot create mesh output directory '"
+                    + openswmm::io::path_utf8(sp.parent_path()) + "': " + ec.message());
+                return false;
+            }
+            openswmm::io::AtomicOutputFile sidecar(sp);
+            if (FILE* sf = sidecar.stream()) {
                 std::fprintf(sf, ";; OpenSWMM 2D mesh — written by the engine "
                                  "alongside the .inp save.\n");
                 emit2DMeshSections(sf, ctx);
-                std::fclose(sf);
-            } else if (warnings) {
-                warnings->push_back(
-                    "[2D_MESH_FILE]: could not write mesh sidecar '"
-                    + sp.string() + "' — mesh state was NOT saved");
+                if (sidecar.commit()) return true;
             }
+            if (warnings) warnings->push_back(sidecar.error());
+            return false;
         }
-        return;
+        return true;
     }
 
     emit2DMeshSections(f, ctx);
+    return true;
 }
 
 // Emit [2D_VERTICES] / [2D_TRIANGLES] / node maps / [2D_BOUNDARY_CONDITIONS]
-// / [2D_EDGE_CONVEYANCE] from the in-memory mesh state. Target is either the
-// main .inp (inline mode) or the external .2dm sidecar — both are parsed by
-// the same section grammar (SectionHandlers2D / load2DMeshExternalFile).
+// / [2D_EDGE_CONVEYANCE] / the [2D_INFILTRATION*] family from the in-memory
+// mesh state. Target is either the main .inp (inline mode) or the external
+// .2dm sidecar — both are parsed by the same section grammar
+// (SectionHandlers2D / load2DMeshExternalFile). Exactly one destination per
+// save, which is what keeps every section here single-emission.
 static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
     const auto& tio  = ctx.twod_io;
     const auto& mesh = *tio.mesh;
@@ -408,6 +925,9 @@ static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
         if (!mesh.tri_tag[t].empty()) any_tag = true;
     }
     const bool write_depth_col = any_init_depth || any_tag;
+    // Cells are triangles first, then quads (MeshData contract); the two
+    // sections below preserve that order so cell indices round-trip.
+    const int n_quads = mesh.n_quads();
     sec(f, "2D_TRIANGLES");
     if (write_depth_col)
         std::fprintf(f, ";;%-6s %-8s %-8s %-12s %-12s %s\n", "V1", "V2", "V3",
@@ -416,8 +936,9 @@ static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
         std::fprintf(f, ";;%-6s %-8s %-8s %-12s %s\n", "V1", "V2", "V3",
                      "MANNINGS_N", "TAG");
     for (int t = 0; t < nt; ++t) {
-        std::fprintf(f, "%-8d %-8d %-8d %-12.6g", mesh.tri_v0[t],
-                     mesh.tri_v1[t], mesh.tri_v2[t], mesh.mannings_n[t]);
+        if (mesh.cell_vertex_count(t) != 3) continue;
+        std::fprintf(f, "%-8d %-8d %-8d %-12.6g", mesh.cell_vertex(t, 0),
+                     mesh.cell_vertex(t, 1), mesh.cell_vertex(t, 2), mesh.mannings_n[t]);
         if (write_depth_col)
             std::fprintf(f, " %-12.6g", mesh.tri_init_depth[t]);
         if (!mesh.tri_tag[t].empty())
@@ -425,6 +946,30 @@ static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
         std::fprintf(f, "\n");
     }
 
+    // ---- [2D_QUADS] -----------------------------------------------------------
+    // Emitted only when the mesh holds quads (all-triangle files are
+    // byte-identical to the triangle-only writer). Same INIT_DEPTH/TAG rule.
+    if (n_quads > 0) {
+        sec(f, "2D_QUADS");
+        if (write_depth_col)
+            std::fprintf(f, ";;%-6s %-8s %-8s %-8s %-12s %-12s %s\n", "V1", "V2",
+                         "V3", "V4", "MANNINGS_N", "INIT_DEPTH", "TAG");
+        else
+            std::fprintf(f, ";;%-6s %-8s %-8s %-8s %-12s %s\n", "V1", "V2", "V3",
+                         "V4", "MANNINGS_N", "TAG");
+        for (int t = 0; t < nt; ++t) {
+            if (mesh.cell_vertex_count(t) != 4) continue;
+            std::fprintf(f, "%-8d %-8d %-8d %-8d %-12.6g", mesh.cell_vertex(t, 0),
+                         mesh.cell_vertex(t, 1), mesh.cell_vertex(t, 2),
+                         mesh.cell_vertex(t, 3), mesh.mannings_n[t]);
+            if (write_depth_col)
+                std::fprintf(f, " %-12.6g", mesh.tri_init_depth[t]);
+            if (!mesh.tri_tag[t].empty())
+                std::fprintf(f, " %s", mesh.tri_tag[t].c_str());
+            std::fprintf(f, "\n");
+        }
+    }
+
     // ---- [2D_INITIAL_VELOCITY] ------------------------------------------------
     // Sparse: only triangles with a nonzero initial velocity get a row.
     // Emitted after [2D_TRIANGLES] — rows validate against loaded triangles.
@@ -517,7 +1062,8 @@ static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
     // drain); BoundaryData reconstruction fallback loses the GROUP label.
     {
         const auto rows = twoD::collectBCRows(tio.pending_bc, tio.boundary,
-                                              o.pending_rows_drained);
+                                              o.pending_rows_drained,
+                                              o.bc_flow_to_si_applied);
         if (!rows.empty()) {
             sec(f, "2D_BOUNDARY_CONDITIONS");
             std::fprintf(f, ";;%-4s %-4s %-16s %-14s %-8s %s\n", "TRI", "EDGE",
@@ -557,11 +1103,162 @@ static void emit2DMeshSections(FILE* f, const SimulationContext& ctx) {
             }
         }
     }
+
+    // ---- [2D_INITIAL_QUALITY] / [2D_BOUNDARY_QUALITY] (S2/S3) ------------------
+    // Authored rows verbatim: CELL is the user's 1-based spelling, TRI/EDGE the
+    // 0-based [2D_BOUNDARY_CONDITIONS] spelling — both exactly as parsed.
+    if (tio.pending_iq && !tio.pending_iq->empty()) {
+        sec(f, "2D_INITIAL_QUALITY");
+        std::fprintf(f, ";;%-6s %-16s %-12s %s\n", "SCOPE", "NAME", "SPECIES", "CONC");
+        for (const auto& r : *tio.pending_iq) {
+            if (r.all)
+                std::fprintf(f, "%-8s %-16s %-12s %.12g\n", "*", "", r.species.c_str(), r.conc);
+            else if (r.tri >= 0)
+                std::fprintf(f, "%-8s %-16d %-12s %.12g\n", "CELL", r.tri + 1, r.species.c_str(), r.conc);
+            else
+                std::fprintf(f, "%-8s %-16s %-12s %.12g\n", "TAG", r.tag.c_str(), r.species.c_str(), r.conc);
+        }
+    }
+    if (tio.pending_bq && !tio.pending_bq->empty()) {
+        sec(f, "2D_BOUNDARY_QUALITY");
+        std::fprintf(f, ";;%-4s %-4s %-12s %s\n", "TRI", "EDGE", "SPECIES", "CONC");
+        for (const auto& r : *tio.pending_bq)
+            std::fprintf(f, "%-6d %-4d %-12s %.12g\n", r.tri, r.edge, r.species.c_str(), r.conc);
+    }
+
+#ifdef OPENSWMM_HAS_2D
+    // ---- [2D_INFILTRATION_OPTIONS] / _DEFAULTS / [2D_INFILTRATION] ------------
+    // Per-cell mesh attributes (§5.5.5): they travel with the mesh, into
+    // whichever single destination this function was pointed at. THE ONLY CALL
+    // SITE — see emit2DInfilSections.
+    emit2DInfilSections(f, ctx);
+
+    // ---- U4 (2026-09-07) — [GW_*] subsurface transport --------------------
+    // Written to the MAIN .inp, never the mesh sidecar: these are model
+    // physics, not per-cell mesh geometry, and [2D_QUADS] must already be in
+    // hand before a [GW_*] CELL/EDGE row can be read (D-A15) — which the
+    // section order here guarantees, since the mesh sections precede this
+    // call in write2DSections.
+    emitGwTransportSections(f, ctx);
+    emitSurfaceQualitySections(f, ctx);   // S7
+
+    // G1: the [2D_AQUIFER*] rows, echoed in the units they were authored in.
+    // The writer is a verbatim echo because the config is never converted in
+    // place — see SubsurfaceSections.hpp's GwUnitFactors note.
+    if (ctx.twod_io.aquifer != nullptr) {
+        std::string aq;
+        static const std::vector kNoNames;
+        twoD::writeSubsurfaceSections(
+            *ctx.twod_io.aquifer,
+            ctx.twod_io.aquifer_nodes ? *ctx.twod_io.aquifer_nodes : kNoNames,
+            ctx.twod_io.aquifer_links ? *ctx.twod_io.aquifer_links : kNoNames,  // G-X4
+            aq);
+        if (!aq.empty()) std::fputs(aq.c_str(), f);
+    }
+#endif
 }
 
-int writeInpFile(const SimulationContext& ctx_internal,
+// Component render hooks produce text; this writer owns checked file publication.
+// Copy fallback is used only when a component declines rendering, never after a
+// failed rendered write (which would replace edited data with the old config).
+static bool writeComponentConfig(const SimulationContext& ctx,
+                                 const ProcessComponentSpec& pc,
+                                 const std::string& token,
+                                 const std::string& dst_dir,
+                                 std::vector* warnings,
+                                 const InpWriteOptions& opts) {
+    namespace fs = std::filesystem;
+    fs::path destination = io::utf8_path(token);
+    if (destination.is_relative() && !dst_dir.empty())
+        destination = io::utf8_path(dst_dir) / destination;
+    auto fail = [&](const std::string& reason) {
+        if (warnings) warnings->push_back("Cannot save component '" + pc.id
+            + "' configuration '" + io::path_utf8(destination) + "': " + reason);
+        return false;
+    };
+    std::string text;
+    const auto* entry = components::ProcessComponentRegistry::instance().find(pc.id);
+    if (entry && entry->save) text = entry->save(ctx, pc);
+    const bool rendered = !text.empty();
+    std::ifstream source;
+    fs::path source_path;
+    std::error_code ec;
+    if (!rendered) {
+        // Absolute input references stay in place. Relative configurations
+        // travel with Save As, using the source resolved at model open.
+        if (pc.resolved_config_path.empty() || io::utf8_path(pc.config_path).is_absolute())
+            return true;
+        source_path = io::utf8_path(pc.resolved_config_path);
+        if (!fs::is_regular_file(source_path, ec))
+            return fail("source '" + pc.resolved_config_path + "' is missing or not a regular file");
+        source.open(source_path, std::ios::binary);
+        if (!source.is_open()) return fail("cannot read source '" + pc.resolved_config_path + "'");
+        ec.clear();
+        if (fs::equivalent(source_path, destination, ec) && !ec) return true;
+    }
+    const std::string physical = mappedOutputPath(io::path_utf8(destination),
+        InpWriteOptions::OutputKind::Component, opts, warnings);
+    if (physical.empty()) return false;
+    const fs::path staging = io::utf8_path(physical);
+    ec.clear();
+    if (staging.has_parent_path()) fs::create_directories(staging.parent_path(), ec);
+    if (ec) return fail("cannot create output directory: " + ec.message());
+    // Binary: configs are copied and compared byte for byte.
+    io::AtomicOutputFile output(staging, /*binary=*/true);
+    FILE* f = output.stream();
+    if (!f) return fail(output.error());
+    // Preserve the existing notice when a successful save replaces different
+    // destination content. Failure diagnostics below take precedence.
+    bool replacing_different = false;
+    std::ifstream previous;
+    // Staging redirects the writer's output validation. The final destination
+    // can still be non-regular; it is not a readable comparison source.
+    if (fs::is_regular_file(destination, ec)) previous.open(destination, std::ios::binary);
+    if (previous.is_open()) {
+        if (rendered) {
+            const std::string old((std::istreambuf_iterator(previous)), {});
+            replacing_different = old != text;
+        } else {
+            std::ifstream comparison(source_path, std::ios::binary);
+            replacing_different = !std::equal(std::istreambuf_iterator(previous),
+                std::istreambuf_iterator(), std::istreambuf_iterator(comparison),
+                std::istreambuf_iterator());
+        }
+        previous.close();
+    }
+    if (rendered) {
+        if (std::fwrite(text.data(), 1, text.size(), f) != text.size())
+            return fail("incomplete configuration write");
+    } else {
+        char buffer[65536];
+        while (source) {
+            source.read(buffer, sizeof buffer);
+            const auto count = static_cast(source.gcount());
+            if (count && std::fwrite(buffer, 1, count, f) != count)
+                return fail("incomplete configuration copy");
+        }
+        if (source.bad() || !source.eof())
+            return fail("cannot finish reading source '" + pc.resolved_config_path + "'");
+        source.close();
+    }
+    if (!output.commit()) return fail(output.error());
+    if (replacing_different && warnings)
+        warnings->push_back("Saving this model replaced an existing, different '"
+            + pc.config_path + "' in the destination folder with this model's "
+            + (rendered ? "rendered configuration." : "configuration copy."));
+    return true;
+}
+
+int writeInpFile(const SimulationContext& ctx,
                  const std::string&       path,
                  std::vector* warnings) {
+    return writeInpFile(ctx, path, warnings, InpWriteOptions{});
+}
+
+int writeInpFile(const SimulationContext&  ctx_internal,
+                 const std::string&        path,
+                 std::vector* warnings,
+                 const InpWriteOptions&    opts) {
     // The engine stores 1D input fields in internal units (feet/cfs); the .inp
     // must carry display units matching FLOW_UNITS. For SI models, convert a
     // local copy back to display units so the live engine state is never
@@ -570,22 +1267,71 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // re-applies the m→ft factor, compounding ×3.28084 per cycle.
     const int us_check = ucf::getUnitSystem(
         static_cast(ctx_internal.options.flow_units));
+    const auto us_idx = static_cast(us_check);
+    // Gate on EVERY factor convert_internal_to_display touches, not just
+    // LENGTH. Keying it on LENGTH alone (which is 1.0 for all US flow units)
+    // meant the function never ran for a US model, silently killing two
+    // back-conversions that are not length-dimensioned and that the READ side
+    // performs unconditionally:
+    //   * [LOSSES] seepage, /= UCF(RAINFALL) = 43200 on read — written back in
+    //     internal ft/s under an in/hr column, and at %10.6f it prints
+    //     0.000000 after one save, so the error is a FIXED POINT that a
+    //     save-convergence test can never catch.
+    //   * q0 / q_limit / divider cutoff, /= Qcf on read for GPM and MGD decks.
+    // convert_internal_to_display already self-guards per quantity, so a
+    // broader gate costs a copy on decks that need one and nothing else.
     const bool needs_display_conv =
-        ucf::Ucf[ucf::LENGTH][static_cast(us_check)] != 1.0;
+        ucf::Ucf[ucf::LENGTH][us_idx]   != 1.0 ||
+        ucf::Ucf[ucf::RAINFALL][us_idx] != 1.0 ||
+        ucf::Qcf[static_cast(ctx_internal.options.flow_units)] != 1.0;
+
+    // Likewise, parse-time normalisations (adverse-slope conduit reversal and
+    // ELEVATION→depth offset conversion) must be undone so the file carries
+    // the authored orientation and offset convention. Otherwise Open → Save
+    // swaps From/To on adverse conduits and writes depths under an ELEVATION
+    // header, which the next open re-subtracts (clamping offsets to 0).
+    const bool needs_authored_conv = input::needs_authored_conversion(ctx_internal);
 
     SimulationContext ctx_display;
-    if (needs_display_conv) {
+    if (needs_display_conv || needs_authored_conv) {
         ctx_display = ctx_internal;
-        input::convert_internal_to_display(ctx_display);
+        if (needs_display_conv)  input::convert_internal_to_display(ctx_display);
+        if (needs_authored_conv) input::convert_internal_to_authored(ctx_display);
     }
-    const SimulationContext& ctx = needs_display_conv ? ctx_display : ctx_internal;
-
-    FILE* f = std::fopen(path.c_str(), "w");
-    if (!f) return -1;
+    const SimulationContext& ctx =
+        (needs_display_conv || needs_authored_conv) ? ctx_display : ctx_internal;
+
+    // SWMM 5.x write profile (MULTI_ENGINE plan V2 Phase 4): omit the v6-only
+    // sections and option keys, map incompatible option values, and write
+    // virtual / inlet junctions in their legacy-equivalent form. Every
+    // substitution is reported so the caller can surface it as a run warning.
+    // `swmm5` covers both 5.x profiles; `stock5` is the stricter one for an
+    // engine without the OpenSWMM legacy grammar extensions (see
+    // InpWriteOptions::Profile::Swmm5Stock).
+    const bool stock5 = (opts.profile == InpWriteOptions::Profile::Swmm5Stock);
+    const bool swmm5  = (opts.profile == InpWriteOptions::Profile::Swmm5) || stock5;
+    auto note = [&](const std::string& s) { if (warnings) warnings->push_back(s); };
+
+    const std::string physical = mappedOutputPath(path, InpWriteOptions::OutputKind::Model, opts, warnings);
+    if (physical.empty()) return -1;
+    openswmm::io::AtomicOutputFile output(openswmm::io::utf8_path(physical));
+    FILE* f = output.stream();
+    if (!f) { note(output.error()); return -1; }
+    if (swmm5)
+        std::fprintf(f, ";; Written by OpenSWMM for a SWMM 5.x engine: v6-only sections and "
+                        "options omitted; virtual and inlet junctions written as junctions.\n");
 
     // Slice IO-4: pre-compute the rebase anchor + opt-out flag once so each
     // section can pass them to emit_path_token() without re-deriving.
-    const std::string dst_dir = openswmm::io::parentDir(path);
+    // makeRelative needs an absolute anchor (it roots a relative one at "/"),
+    // so a save to "dir/model.inp" is anchored at the working directory.
+    const std::string dst_dir = [&] {
+        const std::string dir = openswmm::io::parentDir(path);
+        if (dir.empty() || openswmm::io::isAbsolutePath(dir)) return dir;
+        std::error_code ec;
+        const auto abs = std::filesystem::absolute(openswmm::io::utf8_path(dir), ec);
+        return ec ? dir : openswmm::io::path_utf8(abs);
+    }();
     const bool        force_abs_paths = ctx.options.write_absolute_paths;
 
     sec(f,"TITLE");
@@ -610,7 +1356,8 @@ int writeInpFile(const SimulationContext& ctx_internal,
     static const char* sRouting[]    = {"STEADY","KINWAVE","DYNWAVE","FV"};
     static const char* sInertial[]   = {"NONE","PARTIAL","FULL"};
     static const char* sNormFlow[]   = {"SLOPE","FROUDE","BOTH","NEITHER"};
-    static const char* sSurcharge[]  = {"EXTRAN","SLOT","DYNAMIC_SLOT"};
+    static const char* sSurcharge[]  = {"EXTRAN","SLOT","DYNAMIC_SLOT","TPA"};
+    static const char* sUnsteadyFriction[] = {"NONE","VITKOVSKY"};  // issue #156
 
     const SimulationOptions& o = ctx.options;
     int fu  = static_cast(o.flow_units);
@@ -623,7 +1370,14 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // --- Group 1: Core process options (FLOW_UNITS .. SKIP_STEADY_STATE) ---
     std::fprintf(f,"%-20s %s\n",  "FLOW_UNITS",       (fu>=0&&fu<=5)?sFlowUnits[fu]:"CFS");
     std::fprintf(f,"%-20s %s\n",  "INFILTRATION",     (inf>=0&&inf<=4)?sInfilt[inf]:"HORTON");
-    std::fprintf(f,"%-20s %s\n",  "FLOW_ROUTING",     (rm>=0&&rm<=3)?sRouting[rm]:"DYNWAVE");
+    {
+        const char* routing_word = (rm>=0&&rm<=3)?sRouting[rm]:"DYNWAVE";
+        if (swmm5 && rm == 3) {   // FV has no 5.x counterpart
+            routing_word = "DYNWAVE";
+            note("[OPTIONS] FLOW_ROUTING FV written as DYNWAVE (SWMM 5.x profile)");
+        }
+        std::fprintf(f,"%-20s %s\n",  "FLOW_ROUTING",     routing_word);
+    }
     std::fprintf(f,"%-20s %s\n",  "LINK_OFFSETS",     o.link_offsets==1?"ELEVATION":"DEPTH");
     std::fprintf(f,"%-20s %g\n",  "MIN_SLOPE",        o.min_slope);
     std::fprintf(f,"%-20s %s\n",  "ALLOW_PONDING",    o.allow_ponding?"YES":"NO");
@@ -639,8 +1393,46 @@ int writeInpFile(const SimulationContext& ctx_internal,
     std::fprintf(f,"%-20s %s\n",  "IGNORE_QUALITY",    o.ignore_quality?"YES":"NO");
     // OpenSWMM extension, not a legacy key — emit only when set so 1D-only
     // models keep a legacy-clean [OPTIONS] block.
-    if (o.ignore_2d)
+    if (o.ignore_2d && !swmm5)
         std::fprintf(f,"%-20s %s\n",  "IGNORE_2D",         "YES");
+    // Same rule for the two transport engine-selection keys. Both were
+    // dropped on save: a EULERIAN_ARD model came back LEGACY and a
+    // WATER_AGE model came back with age tracking off, silently. They are
+    // written TOGETHER because either alone is worse than neither — a deck
+    // carrying WATER_AGE ON without its EULERIAN_ARD line opens with the
+    // "no age is tracked this simulation" warning instead of the model the
+    // user saved.
+    if (o.quality_solver == QualitySolverKind::EULERIAN_ARD && !swmm5)
+        std::fprintf(f,"%-20s %s\n",  "QUALITY_SOLVER",    "EULERIAN_ARD");
+    // X1: same rule for LAGRANGIAN — a save-as must not silently reopen as
+    // LEGACY (the A1a defect shape, third instance guarded).
+    if (o.quality_solver == QualitySolverKind::LAGRANGIAN && !swmm5)
+        std::fprintf(f,"%-20s %s\n",  "QUALITY_SOLVER",    "LAGRANGIAN");
+    // X3a: the LARD stepping keys ride the same save-as rule — dropping
+    // either silently changes the transport discretization on reopen.
+    if (o.quality_step > 0.0 && !swmm5) {
+        char qsb[32];
+        fmt_step(qsb, o.quality_step);
+        std::fprintf(f,"%-20s %s\n",  "QUALITY_STEP",      qsb);
+    }
+    if (o.max_segments_per_link != 100 && !swmm5)
+        std::fprintf(f,"%-20s %d\n",  "MAX_SEGMENTS_PER_LINK",
+                     o.max_segments_per_link);
+    // X3b: the RWPT keys ride the same rule.
+    if (o.lard_rwpt && !swmm5)
+        std::fprintf(f,"%-20s %s\n",  "DISPERSION",         "RWPT");
+    if (o.rwpt_seed != 0 && !swmm5)
+        std::fprintf(f,"%-20s %d\n",  "RWPT_SEED",          o.rwpt_seed);
+    if (o.water_age && !swmm5)
+        std::fprintf(f,"%-20s %s\n",  "WATER_AGE",         "ON");
+    // Same save-as rule: dropping this line silently reverts a fresh-boundary
+    // model to the legacy held-quality backflow on reopen.
+    if (o.outfall_backflow_zero)
+        std::fprintf(f,"%-20s %s\n",  "OUTFALL_BACKFLOW_QUALITY", "ZERO");
+    // H1: same rule, same reason — a save-as that dropped this reopened as a
+    // model with no temperature tracking, silently (the A1a defect).
+    if (o.heat_transport && !swmm5)
+        std::fprintf(f,"%-20s %s\n",  "HEAT_TRANSPORT",    "ON");
     std::fprintf(f,"\n");
 
     // --- Group 3: Date / time options (START_DATE .. RULE_STEP) ---
@@ -681,7 +1473,26 @@ int writeInpFile(const SimulationContext& ctx_internal,
     std::fprintf(f,"%-20s %s\n",  "INERTIAL_DAMPING",    (id>=0&&id<=2)?sInertial[id]:"PARTIAL");
     std::fprintf(f,"%-20s %s\n",  "NORMAL_FLOW_LIMITED", (nfl>=0&&nfl<=3)?sNormFlow[nfl]:"BOTH");
     std::fprintf(f,"%-20s %s\n",  "FORCE_MAIN_EQUATION", o.force_main_eqn==1?"D-W":"H-W");
-    std::fprintf(f,"%-20s %s\n",  "SURCHARGE_METHOD",    (sm>=0&&sm<=2)?sSurcharge[sm]:"EXTRAN");
+    {
+        const char* sm_word = (sm>=0&&sm<=3)?sSurcharge[sm]:"EXTRAN";
+        if (swmm5 && sm >= 2) {   // DYNAMIC_SLOT / TPA: 5.x knows only EXTRAN and SLOT
+            note(std::string("[OPTIONS] SURCHARGE_METHOD ") + sm_word +
+                 " written as SLOT (SWMM 5.x profile)");
+            sm_word = "SLOT";
+        }
+        std::fprintf(f,"%-20s %s\n",  "SURCHARGE_METHOD",    sm_word);
+    }
+    if (sm == 3 && !swmm5)   // issue #156: TPA acoustic celerity, non-default method only
+        std::fprintf(f,"%-20s %g\n","TPA_CELERITY", o.tpa_celerity);
+    if (!swmm5) {   // Unsteady friction (issue #156): round-tripped unconditionally, like
+        // SURCHARGE_METHOD — the keys are inert unless a consuming solver runs.
+        const int uf = o.unsteady_friction;
+        std::fprintf(f,"%-20s %s\n","UNSTEADY_FRICTION",
+                     (uf>=0&&uf<=1)?sUnsteadyFriction[uf]:"NONE");
+        std::fprintf(f,"%-20s %g\n","UF_K3", o.uf_k3);
+        if (o.report_signed_heads)   // issue #156 O-6: non-default only
+            std::fprintf(f,"%-20s %s\n","REPORT_SIGNED_HEADS","YES");
+    }
     std::fprintf(f,"%-20s %.2f\n","VARIABLE_STEP",       o.variable_step);
     std::fprintf(f,"%-20s %g\n",  "LENGTHENING_STEP",    o.lengthening_step);
     std::fprintf(f,"%-20s %g\n",  "MIN_SURFAREA",        o.min_surf_area);
@@ -689,29 +1500,34 @@ int writeInpFile(const SimulationContext& ctx_internal,
     std::fprintf(f,"%-20s %g\n",  "HEAD_TOLERANCE",      o.head_tol);
     std::fprintf(f,"%-20s %g\n",  "SYS_FLOW_TOL",        o.sys_flow_tol * 100.0);
     std::fprintf(f,"%-20s %g\n",  "LAT_FLOW_TOL",        o.lat_flow_tol * 100.0);
-    fmt_step(sb, o.min_routing_step);
-    std::fprintf(f,"%-20s %s\n",  "MINIMUM_STEP",        sb);
+    // MINIMUM_STEP takes DECIMAL SECONDS only — legacy's MIN_ROUTE_STEP is a
+    // bare getDouble with no clock fallback (project.c:701-704), unlike
+    // ROUTE_STEP/LENGTHENING_STEP which try both (:676-690). Running it through
+    // fmt_step emitted "0:00:00" for every whole-second value, which legacy
+    // rejects with ERROR 211 — refusing the ENTIRE deck, not just the option.
+    std::fprintf(f,"%-20s %.15g\n", "MINIMUM_STEP",       o.min_routing_step);
     std::fprintf(f,"%-20s %d\n",  "THREADS",             o.num_threads);
 
     // --- Engine-specific extensions (not in legacy GUI) ---
-    if (sm == 2) {
+    if (sm == 2 && !swmm5) {
         std::fprintf(f,"%-20s %.4f\n","DPS_CELERITY",   o.dps_target_celerity);
         std::fprintf(f,"%-20s %.4f\n","DPS_ALPHA",      o.dps_alpha);
         std::fprintf(f,"%-20s %.4f\n","DPS_DECAY_TIME", o.dps_decay_time);
     }
-    if (o.node_continuity != NodeContinuity::EXPLICIT)
+    if (o.node_continuity != NodeContinuity::EXPLICIT && !swmm5)
         std::fprintf(f,"%-20s %s\n",  "NODE_CONTINUITY","SEMI_IMPLICIT");
-    if (o.anderson_accel)
+    if (o.anderson_accel && !swmm5)
         std::fprintf(f,"%-20s %s\n",  "ANDERSON_ACCEL", "YES");
-    if (o.virtual_junction_momentum == 1)
-        std::fprintf(f,"%-20s %s\n",  "VIRTUAL_JUNCTION_MOMENTUM", "FULL");
+    // VIRTUAL_JUNCTION_MOMENTUM is not emitted: FULL is retired (see
+    // SimulationOptions.hpp) and virtual_junction_momentum is now always 0,
+    // so writing the key could only ever re-emit the retired value.
 
     // Explicit finite-volume solver knobs. Emitted only under FLOW_ROUTING FV
     // so a DW model's [OPTIONS] block stays legacy-clean; the keys are inert
     // under other routing models, so a round-trip that changes FLOW_ROUTING
     // does not lose a user's FV configuration mid-session — it is simply not
     // written until FV is selected again.
-    if (o.routing_model == RoutingModel::FV) {
+    if (o.routing_model == RoutingModel::FV && !swmm5) {
         static const char* sRiemann[] = {"HLL","HLLC"};
         static const char* sLimiter[] = {"MINMOD","VANLEER","SUPERBEE"};
         static const char* sScalar[]  = {"UPWIND","MUSCL","QUICKEST_ULTIMATE"};
@@ -728,16 +1544,14 @@ int writeInpFile(const SimulationContext& ctx_internal,
         std::fprintf(f,"%-20s %s\n", "FV_TIME_INTEGRATION",
                      sTime[static_cast(fvo.time_integration)]);
         std::fprintf(f,"%-20s %g\n", "FV_SLOT_CELERITY", fvo.slot_celerity);
+        if (fvo.pressurized_implicit)
+            std::fprintf(f,"%-20s %s\n", "FV_PRESSURIZED_IMPLICIT", "YES");
+        if (fvo.pressure_closure == 1)  // issue #156: non-default only
+            std::fprintf(f,"%-20s %s\n", "FV_PRESSURE_CLOSURE", "TPA");
         if (fvo.dispersion > 0.0)
             std::fprintf(f,"%-20s %g\n", "FV_DISPERSION", fvo.dispersion);
         if (fvo.structure_coupling != fv::StructureCoupling::SUBSTEP)
             std::fprintf(f,"%-20s %s\n", "FV_STRUCTURE_COUPLING", "ROUTING_STEP");
-        if (fvo.node_coupling != fv::NodeCoupling::SEMI_IMPLICIT)
-            std::fprintf(f,"%-20s %s\n", "FV_NODE_COUPLING", "EXPLICIT");
-        if (fvo.node_dt_limit != fv::NodeDtLimit::STABILITY)
-            std::fprintf(f,"%-20s %s\n", "FV_NODE_DT", "NONE");
-        if (fvo.node_picard_sweeps != 1)
-            std::fprintf(f,"%-20s %d\n", "FV_NODE_PICARD", fvo.node_picard_sweeps);
         if (!fvo.compaction)
             std::fprintf(f,"%-20s %s\n", "FV_COMPACTION", "NO");
         std::fprintf(f,"%-20s %s\n", "FV_BACKEND",      sBackend[static_cast(fvo.backend)]);
@@ -748,13 +1562,24 @@ int writeInpFile(const SimulationContext& ctx_internal,
         if (fvo.cfl_census_interval != 1)
             std::fprintf(f,"%-20s %d\n","FV_CFL_CENSUS_INTERVAL", fvo.cfl_census_interval);
     }
-    if (!o.crs.empty())
-        std::fprintf(f,"%-20s %s\n",  "CRS",            o.crs.c_str());
+    // The spatial frame is the only CRS store a GeoPackage open fills, so
+    // fall back to it — otherwise a .gpkg model saved as .inp loses its CRS.
+    {
+        const std::string& crs = !o.crs.empty() ? o.crs : ctx.spatial.crs;
+        if (!crs.empty())
+            std::fprintf(f,"%-20s %s\n",  "CRS",            crs.c_str());
+    }
     if (o.write_absolute_paths)
         std::fprintf(f,"%-20s %s\n",  "WRITE_ABSOLUTE_PATHS", "YES");
-    for (const auto& kv : o.ext_options)
+    for (const auto& kv : o.ext_options) {
+        // "GWF::" entries are the parsed [GWF] section, not real
+        // options — they are re-emitted by the [GWF] writer. Round-tripping them
+        // through here corrupts them: handle_options() uppercases the key and
+        // keeps only the first value token.
+        if (kv.first.rfind("GWF:", 0) == 0) continue;
         std::fprintf(f,"%-20s %s\n",  kv.first.c_str(), kv.second.c_str());
     }
+    }
 
     // [EVAPORATION]
     {
@@ -801,6 +1626,12 @@ int writeInpFile(const SimulationContext& ctx_internal,
         // Check monthly wind speeds
         for (int i = 0; i < 12 && !has_temp; ++i)
             if (opts.wind_speed[i] != 0.0) has_temp = true;
+        // Humidity is written whenever it departs from the 50 % RH constant
+        // default (a HUMIDITY line used to be dropped on save).
+        bool has_humidity = (opts.humidity_type != 0 || opts.humidity_var != 0);
+        for (int i = 0; i < 12 && !has_humidity; ++i)
+            if (opts.humidity[i] != 50.0) has_humidity = true;
+        if (has_humidity) has_temp = true;
 
         if (has_temp) {
             sec(f,"TEMPERATURE");
@@ -832,21 +1663,31 @@ int writeInpFile(const SimulationContext& ctx_internal,
                 std::fprintf(f,"WINDSPEED    FILE\n");
             }
 
-            if (opts.snow_dtlong != 0.0) {
-                // Legacy 9-token form carries the longitude/solar-time
-                // correction (minutes):
-                //   SNOWMELT divt ati nrg elev lat dtlong minMelt maxMelt
-                std::fprintf(f,"SNOWMELT     %.2f %.4f %.4f %.4f %.4f %.4f %.6f %.6f\n",
-                             opts.snow_divt, opts.snow_ati_wt, opts.snow_nrg_ratio,
-                             opts.snow_elev, opts.snow_lat, opts.snow_dtlong,
-                             opts.snow_min_melt, opts.snow_max_melt);
-            } else {
-                std::fprintf(f,"SNOWMELT     %.2f %.4f %.4f %.4f %.6f %.6f %.4f\n",
-                             opts.snow_divt, opts.snow_ati_wt, opts.snow_nrg_ratio,
-                             opts.snow_lat, opts.snow_min_melt, opts.snow_max_melt,
-                             opts.snow_elev);
+            if (has_humidity) {
+                std::fprintf(f,"HUMIDITY    ");
+                if (opts.humidity_var == 1) std::fprintf(f," DEWPOINT");
+                if (opts.humidity_type == 2) {
+                    std::fprintf(f," TIMESERIES %s\n", opts.humidity_ts_name.c_str());
+                } else if (opts.humidity_type == 1) {
+                    std::fprintf(f," MONTHLY");
+                    for (int i = 0; i < 12; ++i)
+                        std::fprintf(f," %.4f", opts.humidity[i]);
+                    std::fprintf(f,"\n");
+                } else {
+                    std::fprintf(f," %.4f\n", opts.humidity[0]);
+                }
             }
 
+            // Legacy form: SNOWMELT Stemp ATIwt RNM Elev Lat DTLong (minutes).
+            // The v6-only minMelt/maxMelt ride as tokens 7-8 only when set
+            // (legacy ignores extra tokens; the solver does not use them).
+            std::fprintf(f,"SNOWMELT     %.2f %.4f %.4f %.4f %.4f %.4f",
+                         opts.snow_divt, opts.snow_ati_wt, opts.snow_nrg_ratio,
+                         opts.snow_elev, opts.snow_lat, opts.snow_dtlong);
+            if (opts.snow_min_melt != 0.0 || opts.snow_max_melt != 0.0)
+                std::fprintf(f," %.6f %.6f", opts.snow_min_melt, opts.snow_max_melt);
+            std::fprintf(f,"\n");
+
             std::fprintf(f,"ADC          IMPERVIOUS");
             for (int i = 0; i < 10; ++i)
                 std::fprintf(f," %.4f", opts.adc_imperv[i]);
@@ -904,7 +1745,7 @@ int writeInpFile(const SimulationContext& ctx_internal,
     {
         bool has_adj = false;
         for (int i = 0; i < 12; ++i) {
-            if (ctx.adjust_temp[i] != 0.0 || ctx.adjust_evap[i] != 1.0 ||
+            if (ctx.adjust_temp[i] != 0.0 || ctx.adjust_evap[i] != 0.0 ||
                 ctx.adjust_rain[i] != 1.0 || ctx.adjust_hydcon[i] != 1.0)
             { has_adj = true; break; }
         }
@@ -933,21 +1774,21 @@ int writeInpFile(const SimulationContext& ctx_internal,
                 if (pi >= 0)
                     std::fprintf(f,"N-PERV       %-16s %s\n",
                                  ctx.subcatch_names.name_of(static_cast(i)).c_str(),
-                                 tN(ctx, pi));
+                                 patN(ctx, pi));
             }
             for (size_t i = 0; i < ctx.subcatch_d_store_pattern.size(); ++i) {
                 int pi = ctx.subcatch_d_store_pattern[i];
                 if (pi >= 0)
                     std::fprintf(f,"DSTORE       %-16s %s\n",
                                  ctx.subcatch_names.name_of(static_cast(i)).c_str(),
-                                 tN(ctx, pi));
+                                 patN(ctx, pi));
             }
             for (size_t i = 0; i < ctx.subcatch_infil_pattern.size(); ++i) {
                 int pi = ctx.subcatch_infil_pattern[i];
                 if (pi >= 0)
                     std::fprintf(f,"INFIL        %-16s %s\n",
                                  ctx.subcatch_names.name_of(static_cast(i)).c_str(),
-                                 tN(ctx, pi));
+                                 patN(ctx, pi));
             }
         }
     }
@@ -980,13 +1821,23 @@ int writeInpFile(const SimulationContext& ctx_internal,
     for(int j=0;j(j);
     write_obj_comment(f, ctx.gages.comments, u);
     int iv=ctx.gages.interval_sec[u];int h=iv/3600,m=(iv%3600)/60;int ts=ctx.gages.ts_index[u];
+    // The recording interval is H:MM only while it IS a whole number of
+    // minutes. Legacy reads this column with getDouble FIRST and only then
+    // falls back to a clock (gage.c readGageSeriesFormat), so decimal hours
+    // are always legal — and they are the only form that can carry a
+    // sub-minute interval. A 4-second gage (0.001111 h, which real HEC-HMS
+    // decks carry) was being written as "0:00", which legacy rejects with
+    // ERROR 213 and refuses the whole deck.
+    char gsb[32];
+    if(iv>0&&iv%60==0) std::snprintf(gsb,sizeof(gsb),"%d:%02d",h,m);
+    else               std::snprintf(gsb,sizeof(gsb),"%.10g",iv/3600.0);
     // Emit the actual rain-data format (0=INTENSITY,1=VOLUME,2=CUMULATIVE) — a
     // prior hardcoded "INTENSITY" silently rewrote VOLUME/CUMULATIVE gages.
     const char* fmt = ctx.gages.rain_type[u]==1 ? "VOLUME"
                     : ctx.gages.rain_type[u]==2 ? "CUMULATIVE" : "INTENSITY";
     const double sf = ctx.gages.scale_factor[u];
     if(ts>=0){
-        std::fprintf(f,"%-16s %-12s %d:%02d     %.2f     TIMESERIES %s",ctx.gage_names.name_of(j).c_str(),fmt,h,m,ctx.gages.snow_factor[u],tN(ctx,ts));
+        std::fprintf(f,"%-16s %-12s %-8s     %.2f     TIMESERIES %s",ctx.gage_names.name_of(j).c_str(),fmt,gsb,ctx.gages.snow_factor[u],tN(ctx,ts));
         if(sf!=1.0)std::fprintf(f," %.4g",sf);
         std::fprintf(f,"\n");
     }
@@ -994,12 +1845,16 @@ int writeInpFile(const SimulationContext& ctx_internal,
         const std::string tok = emit_path_token(ctx.gages.file_path[u],
                                                  dst_dir, force_abs_paths, warnings);
         if(ctx.gages.file_format[u]==RainFileFormat::USER_CSV){
-            // Compact openswmm extension — the reader expects one "path:col" token.
-            std::fprintf(f,"%-16s %-12s %d:%02d     %.2f     FILE \"%s:%s\"",
-                          ctx.gage_names.name_of(j).c_str(),fmt,h,m,
+            // Compact openswmm extension — the reader expects one "path:col"
+            // token. An EMPTY column is a legal state (it means "first data
+            // column"), so emit the bare path rather than a dangling
+            // "path:" that reads as malformed to EPA SWMM / PCSWMM.
+            const std::string& col = ctx.gages.col_name[u];
+            const std::string src = col.empty() ? tok : tok + ":" + col;
+            std::fprintf(f,"%-16s %-12s %-8s     %.2f     FILE \"%s\"",
+                          ctx.gage_names.name_of(j).c_str(),fmt,gsb,
                           ctx.gages.snow_factor[u],
-                          tok.c_str(),
-                          ctx.gages.col_name[u].c_str());
+                          src.c_str());
             if(sf!=1.0)std::fprintf(f," %.4g",sf);
         }else{
             // Legacy FILE grammar: Fname Station Units [StartDate] [SF] — the
@@ -1011,8 +1866,8 @@ int writeInpFile(const SimulationContext& ctx_internal,
                 warnings->push_back("[RAINGAGES] gage \""+ctx.gage_names.name_of(j)+
                                     "\": no station ID set; wrote '*' — the legacy "
                                     "engine will match no rows in \""+tok+"\"");
-            std::fprintf(f,"%-16s %-12s %d:%02d     %.2f     FILE \"%s\" %s %s",
-                          ctx.gage_names.name_of(j).c_str(),fmt,h,m,
+            std::fprintf(f,"%-16s %-12s %-8s     %.2f     FILE \"%s\" %s %s",
+                          ctx.gage_names.name_of(j).c_str(),fmt,gsb,
                           ctx.gages.snow_factor[u],
                           tok.c_str(),
                           sta.empty() ? "*" : sta.c_str(),
@@ -1021,6 +1876,23 @@ int writeInpFile(const SimulationContext& ctx_internal,
         }
         std::fprintf(f,"\n");
     }
+    else{
+        // Neither a resolved series index nor a file path. Dropping the row
+        // entirely would delete the gage while [SUBCATCHMENTS] still names it,
+        // which fails reload with a fatal ERR_NAME (209) on the subcatchment.
+        // Emit the retained series name (or the '*' placeholder, which the gage
+        // resolver tolerates) so the gage definition always survives.
+        const std::string& tsn = ctx.gages.ts_name[u];
+        if(tsn.empty() && warnings)
+            warnings->push_back("[RAINGAGES] gage \""+ctx.gage_names.name_of(j)+
+                                "\": no rainfall source set; wrote 'TIMESERIES *'");
+        std::fprintf(f,"%-16s %-12s %-8s     %.2f     TIMESERIES %s",
+                      ctx.gage_names.name_of(j).c_str(),fmt,gsb,
+                      ctx.gages.snow_factor[u],
+                      tsn.empty() ? "*" : tsn.c_str());
+        if(sf!=1.0)std::fprintf(f," %.4g",sf);
+        std::fprintf(f,"\n");
+    }
     }}
 
     // [SUBCATCHMENTS]
@@ -1037,13 +1909,29 @@ int writeInpFile(const SimulationContext& ctx_internal,
     std::fprintf(f,";;%-16s %-16s %-16s %-12s %-10s %-12s %-10s %-10s %-16s %-10s %-10s\n","----------------","----------------","----------------","------------","----------","------------","----------","----------","----------------","----------","----------");
     for(int j=0;j(j);
     write_obj_comment(f, ctx.subcatches.comments, u);
-    const int  sp = ctx.subcatches.snowpack[u];
+    const char* spname = sspN(ctx,u);          // index, else retained name, else "*"
+    const bool  has_sp = std::strcmp(spname,"*")!=0;
     const double rsf = ctx.subcatches.rain_scale_factor[u];
     const double ssf = ctx.subcatches.snow_scale_factor[u];
-    const bool need_scale = (rsf!=1.0 || ssf!=1.0);
-    std::fprintf(f,"%-16s %-16s %-16s %12.4f %10.2f %12.4f %10.4f %10.4f",ctx.subcatch_names.name_of(j).c_str(),gN(ctx,ctx.subcatches.gage[u]),nN(ctx,ctx.subcatches.outlet_node[u]),ctx.subcatches.area[u],ctx.subcatches.frac_imperv[u]*100.0,ctx.subcatches.width[u],ctx.subcatches.slope[u]*100.0,ctx.subcatches.curb_length[u]);
+    bool need_scale = (rsf!=1.0 || ssf!=1.0);
+    // A stock SWMM 5 parser has no scale-factor columns: it reads the '*'
+    // placeholder as a snowpack name (ERROR 209) and a factor as a stray
+    // token. Drop them for that profile, and say so when they carried a value.
+    if(stock5 && need_scale){
+        note("[SUBCATCHMENTS] " + ctx.subcatch_names.name_of(j) + ": rain/snow scale factors " +
+             std::to_string(rsf) + "/" + std::to_string(ssf) +
+             " dropped (stock SWMM 5 has no such columns)");
+        need_scale = false;
+    }
+    // Full precision on every solver-facing field. %12.4f is an ABSOLUTE
+    // 4-decimal format, so a small area lost most of its significance
+    // (0.018939394 ac -> 0.0189, a 0.2% error applied straight to runoff
+    // volume); of the corpus decks whose [SUBCATCHMENTS] changed on round
+    // trip, 13 of 13 went on to simulate differently. Keeps the column width
+    // so the file still reads as a table (same form as [CONDUITS] length).
+    std::fprintf(f,"%-16s %-16s %-16s %12.15g %10.15g %12.15g %10.15g %10.15g",ctx.subcatch_names.name_of(j).c_str(),sgN(ctx,u),oN(ctx,u),ctx.subcatches.area[u],ctx.subcatches.frac_imperv[u]*100.0,ctx.subcatches.width[u],ctx.subcatches.slope[u]*100.0,ctx.subcatches.curb_length[u]);
     // Token 8 must be present to reach tokens 9/10 positionally.
-    if(sp>=0 || need_scale) std::fprintf(f," %-16s",spN(ctx,sp));
+    if(has_sp || need_scale) std::fprintf(f," %-16s",spname);
     if(need_scale){
         // RainScale must be written even when 1.0 if SnowScale is not, to hold
         // the position of token 10.
@@ -1076,13 +1964,114 @@ int writeInpFile(const SimulationContext& ctx_internal,
     for(int j=0;j(j);
     int im=ctx.subcatches.infil_model[u];
     const char* mn=(im>=0&&im<=4)?infilNames[im]:"HORTON";
-    std::fprintf(f,"%-16s %10.4f %10.4f %10.4f %10.4f %10.4f %s\n",
+    // Full precision, like the other solver-facing fields. %10.4f is an
+    // ABSOLUTE 4-decimal format, so a Green-Ampt Ksat of 1e-6 in/hr — which
+    // real low-conductivity decks carry — was written as 0.0000, and legacy
+    // rejects a non-positive Ksat outright with ERROR 235 (grnampt_setParams).
+    std::fprintf(f,"%-16s %10.15g %10.15g %10.15g %10.15g %10.15g %s\n",
         ctx.subcatch_names.name_of(j).c_str(),
         ctx.subcatches.infil_p1[u],ctx.subcatches.infil_p2[u],
         ctx.subcatches.infil_p3[u],ctx.subcatches.infil_p4[u],
         ctx.subcatches.infil_p5[u],mn);
     }}
 
+    // [AQUIFERS]
+    // Grammar: Name Por WP FC Ksat Kslope Tslope ETu ETs Seep Ebot Egw Umc [ETupat]
+    // %.10g preserves full double precision without scientific notation for the
+    // magnitudes seen in elevations and conductivities.
+    if(ctx.aquifers.count()>0){sec(f,"AQUIFERS");
+    std::fprintf(f,";;%-16s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-16s\n","Name","Porosity","WiltPoint","FieldCap","Ksat","Kslope","Tslope","ETu","ETs","Seepage","Ebot","Egw","Umc","ETupat");
+    std::fprintf(f,";;%-16s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-16s\n","----------------","----------","----------","----------","----------","----------","----------","----------","----------","----------","----------","----------","----------","----------------");
+    for(int j=0;j(j);
+    std::fprintf(f,"%-16s %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g",
+        ctx.aquifers.names[u].c_str(),
+        ctx.aquifers.porosity[u],ctx.aquifers.wilting_point[u],ctx.aquifers.field_capacity[u],
+        ctx.aquifers.conductivity[u],ctx.aquifers.conduct_slope[u],ctx.aquifers.tension_slope[u],
+        ctx.aquifers.upper_evap[u],ctx.aquifers.lower_evap[u],ctx.aquifers.lower_loss[u],
+        ctx.aquifers.bottom_elev[u],ctx.aquifers.water_table_elev[u],ctx.aquifers.upper_moist[u]);
+    if(!ctx.aquifers.upper_evap_pat[u].empty())
+        std::fprintf(f," %-16s",ctx.aquifers.upper_evap_pat[u].c_str());
+    std::fprintf(f,"\n");
+    }}
+
+    // [GROUNDWATER]
+    // Grammar: Subcatch Aquifer Node SurfElev A1 B1 A2 B2 A3 Twgr Hstar
+    // A subcatchment carries a groundwater row iff gw_aquifer >= 0. gw_node is
+    // resolved by PostParseResolver (the section normally precedes [JUNCTIONS]);
+    // a row whose node still will not resolve is skipped with a warning rather
+    // than written with '*', which would fail reload with ERR_NAME (209).
+    // The gw_* vectors are grown per-row by the parser (ensure_subcatch_gw_capacity),
+    // so they can be SHORTER than the subcatchment count — bound the loop by them.
+    {size_t nGw=static_cast(ctx.n_subcatches());
+    if(ctx.subcatches.gw_aquifer.size()=0 && a=0){anyGw=true;break;}}
+    if(anyGw){sec(f,"GROUNDWATER");
+    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s\n","Subcatchment","Aquifer","Node","SurfElev","A1","B1","A2","B2","A3","Tw","Hstar");
+    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-10s %-10s %-10s %-10s %-10s\n","----------------","----------------","----------------","----------","----------","----------","----------","----------","----------","----------","----------");
+    for(size_t u=0;u(u);
+    const int aq=ctx.subcatches.gw_aquifer[u];
+    if(aq<0 || aq>=ctx.aquifers.count()) continue;
+    if(ctx.subcatches.gw_node[u]<0){
+        if(warnings)
+            warnings->push_back("[GROUNDWATER] subcatchment \""+ctx.subcatch_names.name_of(s)+
+                                "\": receiving node unresolved; row omitted");
+        continue;
+    }
+    std::fprintf(f,"%-16s %-16s %-16s %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g %-10.10g",
+        ctx.subcatch_names.name_of(s).c_str(),
+        ctx.aquifers.names[static_cast(aq)].c_str(),
+        nN(ctx,ctx.subcatches.gw_node[u]),
+        ctx.subcatches.gw_surf_elev[u],ctx.subcatches.gw_a1[u],ctx.subcatches.gw_b1[u],
+        ctx.subcatches.gw_a2[u],ctx.subcatches.gw_b2[u],ctx.subcatches.gw_a3[u],
+        ctx.subcatches.gw_tw[u]);
+    // Optional Egwt Ebot Wgw Umc: legacy reads `*` (or absence) as MISSING —
+    // the node invert / the aquifer's values — so a missing field is written
+    // as `*`, and only as far as the last field actually given.
+    //
+    // At least ONE of them is always emitted, because legacy rejects the row
+    // with ERR_ITEMS at `ntoks < 11` (gwater.c gwater_readGroundwaterParams)
+    // even though only ten tokens are mandatory — the eleventh may be `*`, but
+    // it must be there. Stopping at ten when every optional was unset produced
+    // a file legacy refused outright.
+    {
+        const double opt[4] = {ctx.subcatches.gw_hstar[u], ctx.subcatches.gw_bot_elev[u],
+                               ctx.subcatches.gw_wt_elev[u], ctx.subcatches.gw_upper_moist[u]};
+        int last = 0;
+        for (int k = 0; k < 4; ++k) if (opt[k] != constants::MISSING) last = k;
+        for (int k = 0; k <= last; ++k) {
+            if (opt[k] != constants::MISSING) std::fprintf(f, " %-10.10g", opt[k]);
+            else                              std::fprintf(f, " %-10s", "*");
+        }
+        std::fprintf(f, "\n");
+    }
+    }}}
+
+    // [GWF]
+    // Grammar: Subcatch LATERAL|DEEP 
+    // handle_gwf() stores these in options.ext_options under "GWF::"
+    // (SWMMEngine reads them back from there). They must NOT be emitted through
+    // the [OPTIONS] ext_options passthrough: handle_options() uppercases the key
+    // and keeps only the first value token, which mangles the key case and
+    // truncates any multi-token expression. Iterate subcatchments (not the
+    // unordered_map) so the output order is deterministic.
+    {bool wroteGwf=false;
+    static const char* kGwfTypes[]={"LATERAL","DEEP"};
+    for(int s=0;ssecond.empty()) continue;
+            if(!wroteGwf){sec(f,"GWF");
+                std::fprintf(f,";;%-16s %-10s %s\n","Subcatchment","Type","Expression");
+                wroteGwf=true;}
+            std::fprintf(f,"%-16s %-10s %s\n",scn.c_str(),ty,it->second.c_str());
+        }
+    }}
+
     // [LID_CONTROLS]
     if (ctx.lid_controls.count() > 0) {
         sec(f,"LID_CONTROLS");
@@ -1178,10 +2167,19 @@ int writeInpFile(const SimulationContext& ctx_internal,
                          ctx.lid_usage.init_sat[uj],
                          ctx.lid_usage.from_imperv[uj],
                          ctx.lid_usage.to_perv[uj]);
-            if (uj < ctx.lid_usage.rpt_file.size() && !ctx.lid_usage.rpt_file[uj].empty())
-                std::fprintf(f," %s", ctx.lid_usage.rpt_file[uj].c_str());
-            else
-                std::fprintf(f," *");
+            const std::string rpt_tok =
+                (uj < ctx.lid_usage.rpt_file.size())
+                    ? emit_path_token(ctx.lid_usage.rpt_file[uj], dst_dir,
+                                      force_abs_paths, warnings)
+                    : std::string{};
+            // Quote the report path, as every other FILE token here does
+            // (see the [TIMESERIES] and [RAINGAGES] FILE emissions). Legacy
+            // strips the quotes, and without them a path containing a space
+            // tokenises into several columns and shifts DrainTo and FromPerv
+            // along with it. `*` is the "no report" sentinel, never a path,
+            // so it stays bare.
+            if (rpt_tok.empty()) std::fprintf(f," *");
+            else                 std::fprintf(f," \"%s\"", rpt_tok.c_str());
             if (uj < ctx.lid_usage.drain_to.size() && !ctx.lid_usage.drain_to[uj].empty())
                 std::fprintf(f," %s", ctx.lid_usage.drain_to[uj].c_str());
             else
@@ -1193,22 +2191,82 @@ int writeInpFile(const SimulationContext& ctx_internal,
     }
 
     // [JUNCTIONS]
-    if(hasRegularJunction(ctx)){sec(f,"JUNCTIONS");
+    // Under the SWMM 5.x profile virtual and inlet junctions are written here as
+    // ordinary junctions (no [VIRTUAL_JUNCTIONS] / [INLET_JUNCTIONS] in 5.x).
+    if(hasRegularJunction(ctx)||(swmm5&&(hasVirtualJunction(ctx)||hasInletJunction(ctx)))){sec(f,"JUNCTIONS");
     std::fprintf(f,";;%-16s %-12s %-12s %-12s %-12s %-12s\n","Name","Elev","MaxDepth","InitDepth","SurDepth","Aponded");
     std::fprintf(f,";;%-16s %-12s %-12s %-12s %-12s %-12s\n","----------------","------------","------------","------------","------------","------------");
-    for(int j=0;j(j);if(ctx.nodes.type[u]!=NodeType::JUNCTION||isVirtualNode(ctx,u))continue;
+    for(int j=0;j(j);if(ctx.nodes.type[u]!=NodeType::JUNCTION)continue;
+    const bool vnode=isVirtualNode(ctx,u);
+    if(vnode&&!swmm5)continue;
     write_obj_comment(f, ctx.nodes.comments, u);
+    if(vnode){
+        // MaxDepth: the rim / flood threshold when one was given, else 0 so the
+        // 5.x engine derives it from the crown as for any junction. The node
+        // had no surcharge depth and no ponded area.
+        const double rim=(u0.0?rim:0.0,0.0,0.0,0.0);
+        note("Node "+ctx.node_names.name_of(j)+(isInletNode(ctx,u)
+            ?": inlet junction written as a junction plus an [INLET_USAGE] row on its approach conduit"
+            :": virtual junction written as a junction")+" (SWMM 5.x profile)");
+        continue;
+    }
     std::fprintf(f,"%-16s %12.4f %12.4f %12.4f %12.4f %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],ctx.nodes.sur_depth[u],ctx.nodes.ponded_area[u]);
     }}
 
-    // [VIRTUAL_JUNCTIONS] — name + invert elevation; all other geometry is
+    // [VIRTUAL_JUNCTIONS] — name + invert elevation, plus an optional MaxDepth
+    // that is used ONLY to draw the ground surface. All solver geometry is
     // derived from the attached conduits at load time (refactored engine only).
-    if(hasVirtualJunction(ctx)){sec(f,"VIRTUAL_JUNCTIONS");
-    std::fprintf(f,";;%-16s %-12s\n","Name","Elev");
-    std::fprintf(f,";;%-16s %-12s\n","----------------","------------");
-    for(int j=0;j(j);if(!isVirtualNode(ctx,u))continue;
+    if(!swmm5&&hasVirtualJunction(ctx)){sec(f,"VIRTUAL_JUNCTIONS");
+    const bool anyRim = hasVirtualJunctionRim(ctx);
+    if(anyRim){
+        std::fprintf(f,";;%-16s %-12s %-12s\n","Name","Elev","MaxDepth");
+        std::fprintf(f,";;%-16s %-12s %-12s\n","----------------","------------","------------");
+    } else {
+        std::fprintf(f,";;%-16s %-12s\n","Name","Elev");
+        std::fprintf(f,";;%-16s %-12s\n","----------------","------------");
+    }
+    for(int j=0;j(j);
+    if(!isVirtualNode(ctx,u)||isInletNode(ctx,u))continue;
+    if(upush_back("Node "+ctx.node_names.name_of(j)+
+                            ": inlet junction has no resolved inlet usage; "
+                            "written as a plain [VIRTUAL_JUNCTIONS] row");
     write_obj_comment(f, ctx.nodes.comments, u);
-    std::fprintf(f,"%-16s %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u]);
+    const double rim = (u0.0)
+        std::fprintf(f,"%-16s %12.4f %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],rim);
+    else
+        std::fprintf(f,"%-16s %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u]);
+    }}
+
+    // [INLET_JUNCTIONS] — a virtual junction plus its street inlet. Tokens 1-3
+    // mirror [VIRTUAL_JUNCTIONS] (MaxDepth here is the flood threshold, carried
+    // in rim_depth); tokens 4-11 are the [INLET_USAGE] tail.
+    if(!swmm5&&hasInletJunction(ctx)){sec(f,"INLET_JUNCTIONS");
+    std::fprintf(f,";;%-16s %-12s %-12s %-16s %-16s %-8s %-8s %-10s %-10s %-10s %-10s\n",
+        "Name","Elev","MaxDepth","Inlet","CaptureNode","#Inlets","%Clog","Qmax","aLocal","wLocal","Placement");
+    std::fprintf(f,";;%-16s %-12s %-12s %-16s %-16s %-8s %-8s %-10s %-10s %-10s %-10s\n",
+        "----------------","------------","------------","----------------","----------------",
+        "--------","--------","----------","----------","----------","----------");
+    for(int j=0;j(j);
+    const int r=inletUsageRow(ctx,u); if(r<0)continue;
+    const auto ur=static_cast(r);
+    write_obj_comment(f, ctx.nodes.comments, u);
+    int pl=ctx.inlet_usages.placement[ur]; if(pl<0||pl>2)pl=0;
+    std::fprintf(f,"%-16s %12.4f %12.4f %-16s %-16s %8d %8.4g %10.4g %10.4g %10.4g %-10s\n",
+        ctx.node_names.name_of(j).c_str(),
+        ctx.nodes.invert_elev[u],
+        (u(ctx.inlet_usages.design_index[ur])].c_str(),
+        ctx.node_names.name_of(ctx.inlet_usages.node_index[ur]).c_str(),
+        ctx.inlet_usages.num_inlets[ur],
+        (1.0-ctx.inlet_usages.clog_factor[ur])*100.0,
+        ctx.inlet_usages.flow_limit[ur],
+        ctx.inlet_usages.local_depress[ur],
+        ctx.inlet_usages.local_width[ur],
+        kInletPlacementWords[pl]);
     }}
 
     // [OUTFALLS]
@@ -1238,10 +2296,22 @@ int writeInpFile(const SimulationContext& ctx_internal,
             std::snprintf(stage,sizeof(stage),"%s",ctx.tables[t].id.c_str());
     }
 
-    std::fprintf(f,"%-16s %12.4f %-12s",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ofName(otype));
+    const bool has_route = (oroute>=0 && oroutepush_back("[OUTFALLS] node \""+ctx.node_names.name_of(j)+
+            "\": a flap gate together with a Route To subcatchment cannot be "
+            "expressed in SWMM 5.x — a legacy engine reading this file will "
+            "ignore the flap gate.");
+    std::fprintf(f,"%-16s %12.15g %-12s",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ofName(otype));
     if(stage[0]!='\0')std::fprintf(f," %-16s",stage);
     std::fprintf(f," %-8s",oflap?"YES":"NO");
-    if(oroute>=0 && oroute=0) ? D.cd[static_cast(drow)] : 0.0;
         double maxd = (drow>=0) ? D.max_depth[static_cast(drow)] : 0.0;
+        // Legacy column order: qMin dhMax cWeir (node.c:1112)
         std::fprintf(f,"%-16s %12.4f %-16s WEIR     %12.4f %12.4f %12.4f %12.4f %12.4f %12.4f %12.4f\n",
             ctx.node_names.name_of(j).c_str(), ctx.nodes.invert_elev[u], divLinkName,
-            cutoff, cd, maxd, ctx.nodes.full_depth[u], ctx.nodes.init_depth[u],
+            cutoff, maxd, cd, ctx.nodes.full_depth[u], ctx.nodes.init_depth[u],
             ctx.nodes.sur_depth[u], ctx.nodes.ponded_area[u]);
         break;
     }
@@ -1317,8 +2388,13 @@ int writeInpFile(const SimulationContext& ctx_internal,
     const int srow = ctx.node_subtypes.storage_row(j); const auto& S = ctx.node_subtypes.storages;
     const int scurve = (srow>=0)?S.curve[static_cast(srow)]:-1;
     const StorageShape sshape = (srow>=0)?S.shape[static_cast(srow)]:StorageShape::FUNCTIONAL;
+    // Shape, then legacy 5.2's trailing columns in storage_readParams' order:
+    // SurDepth, Fevap, and the exfiltration triple Psi Ksat IMD when Ksat is
+    // set (exfil_readStorageParams). The former `0 0 ` /
+    // `0 ` tails re-read the surcharge depth as Fevap or as a bare
+    // Ksat.
     if(scurve>=0)
-        std::fprintf(f,"%-16s %12.4f %12.4f %12.4f TABULAR    %s 0 0 %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],tN(ctx,scurve),ctx.nodes.sur_depth[u]);
+        std::fprintf(f,"%-16s %12.15g %12.15g %12.15g TABULAR    %s",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],tN(ctx,scurve));
     else if(storage_shape_is_geometric(sshape)){
         // Geometric shapes re-emit the RAW L/W/Z the user gave us, not the derived
         // a/b/c — that is the whole point of keeping p1..p3 in the SoA. Writing the
@@ -1326,13 +2402,25 @@ int writeInpFile(const SimulationContext& ctx_internal,
         const double q1=S.p1[static_cast(srow)];
         const double q2=S.p2[static_cast(srow)];
         const double q3=S.p3[static_cast(srow)];
-        std::fprintf(f,"%-16s %12.4f %12.4f %12.4f %-10s %g %g %g 0 %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],storage_shape_keyword(sshape),q1,q2,q3,ctx.nodes.sur_depth[u]);
+        std::fprintf(f,"%-16s %12.15g %12.15g %12.15g %-10s %.15g %.15g %.15g",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],storage_shape_keyword(sshape),q1,q2,q3);
     }
     else {
         const double sa=(srow>=0)?S.a[static_cast(srow)]:0.0;
         const double sb=(srow>=0)?S.b[static_cast(srow)]:0.0;
         const double sc=(srow>=0)?S.c[static_cast(srow)]:0.0;
-        std::fprintf(f,"%-16s %12.4f %12.4f %12.4f FUNCTIONAL %g %g %g 0 %12.4f\n",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],sa,sb,sc,ctx.nodes.sur_depth[u]);
+        // Bare %g is 6 significant digits, so a coefficient of any size lost
+        // its fraction (278.539816 -> 278.54). A1 scales storage surface area,
+        // hence volume and routing: 13 of 14 corpus decks whose [STORAGE] rows
+        // changed on round trip went on to simulate differently.
+        std::fprintf(f,"%-16s %12.15g %12.15g %12.15g FUNCTIONAL %.15g %.15g %.15g",ctx.node_names.name_of(j).c_str(),ctx.nodes.invert_elev[u],ctx.nodes.full_depth[u],ctx.nodes.init_depth[u],sa,sb,sc);
+    }
+    {
+        const double fevap=(srow>=0)?S.evap_frac[static_cast(srow)]:0.0;
+        const double ksat=(srow>=0)?S.exfil_ksat[static_cast(srow)]:0.0;
+        std::fprintf(f," %12.15g %.15g",ctx.nodes.sur_depth[u],fevap);
+        if(ksat!=0.0)
+            std::fprintf(f," %g %g %g",S.exfil_suction[static_cast(srow)],ksat,S.exfil_imd[static_cast(srow)]);
+        std::fprintf(f,"\n");
     }
     }}
 
@@ -1347,7 +2435,9 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // fixed 4/6-decimal field: real models carry sub-metre lengths and 1/n-derived
     // roughness with many significant figures, and truncating them perturbs the
     // routing solution — noticeable on large, control-heavy (chaos-sensitive) models.
-    std::fprintf(f,"%-16s %-16s %-16s %15.15g %15.15g %12.4f %12.4f %10.4f %10.4f\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),(cr>=0)?CD.length[static_cast(cr)]:0.0,(cr>=0)?CD.roughness[static_cast(cr)]:0.01,ctx.links.offset1[u],ctx.links.offset2[u],ctx.links.q0[u],ctx.links.q_limit[u]);
+    // The offsets and flows on the same row were left at %12.4f/%10.4f and so
+    // kept truncating (0.000195 -> 0.0002); they feed the solver just as directly.
+    std::fprintf(f,"%-16s %-16s %-16s %15.15g %15.15g %12.15g %12.15g %10.15g %10.15g\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),(cr>=0)?CD.length[static_cast(cr)]:0.0,(cr>=0)?CD.roughness[static_cast(cr)]:0.01,ctx.links.offset1[u],ctx.links.offset2[u],ctx.links.q0[u],ctx.links.q_limit[u]);
     }}
 
     // [PUMPS]
@@ -1362,24 +2452,38 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // on/off. Dropping them makes every pump run unconditionally on re-read,
     // changing the pumping regime and downstream flooding/continuity.
     const char* pstat=(pr>=0)?(PD.init_state[static_cast(pr)]?"ON":"OFF"):(ctx.links.setting[u]>0?"ON":"OFF");
-    std::fprintf(f,"%-16s %-16s %-16s %-16s %-10s %.10g %.10g\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),tN(ctx,(pr>=0)?PD.curve[static_cast(pr)]:-1),pstat,(pr>=0)?PD.startup[static_cast(pr)]:0.0,(pr>=0)?PD.shutoff[static_cast(pr)]:0.0);
+    // Pump curve: prefer the resolved index, then the retained curve name (the
+    // [OUTLETS] writer already does this). Writing tN() alone silently
+    // downgraded a curved pump to IDEAL whenever only the name was known.
+    // '*' is the legal IDEAL placeholder, so an empty name is not an error.
+    const int pcurve=(pr>=0)?PD.curve[static_cast(pr)]:-1;
+    const char* pcname=(pcurve>=0)?tN(ctx,pcurve)
+                      :(ctx.links.pump_curve_name[u].empty()?"*"
+                        :ctx.links.pump_curve_name[u].c_str());
+    std::fprintf(f,"%-16s %-16s %-16s %-16s %-10s %.10g %.10g\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),pcname,pstat,(pr>=0)?PD.startup[static_cast(pr)]:0.0,(pr>=0)?PD.shutoff[static_cast(pr)]:0.0);
     }}
 
     // [ORIFICES]
     if(hasLT(ctx,LinkType::ORIFICE)){sec(f,"ORIFICES");
-    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-8s\n","Name","FromNode","ToNode","Type","Offset","Cd","Gated");
-    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-8s\n","----------------","----------------","----------------","----------","----------","----------","--------");
+    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-8s %-10s\n","Name","FromNode","ToNode","Type","Offset","Cd","Gated","CloseTime");
+    std::fprintf(f,";;%-16s %-16s %-16s %-10s %-10s %-10s %-8s %-10s\n","----------------","----------------","----------------","----------","----------","----------","--------","----------");
     for(int j=0;j(j);if(ctx.links.type[u]!=LinkType::ORIFICE)continue;
     write_obj_comment(f, ctx.links.comments, u);
     const int orr=ctx.link_subtypes.orifice_row(j);
-    std::fprintf(f,"%-16s %-16s %-16s SIDE       %10.4f %10.4f NO\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),ctx.links.offset1[u],(orr>=0)?ctx.link_subtypes.orifices.cd[static_cast(orr)]:0.0);
+    const auto uorr=static_cast(orr);
+    // orifice_type: 0 = BOTTOM, 1 = SIDE (LinkSubtypes.hpp). `orate` is stored
+    // as parsed — HOURS, converted at use (SWMMEngine.cpp:2927) — so it is
+    // emitted verbatim. All four were previously hardcoded/dropped, which
+    // destroyed the orientation, the flap gate and the close time on save.
+    const char* otype=(orr>=0&&ctx.link_subtypes.orifices.orifice_type[uorr]!=0.0)?"SIDE":"BOTTOM";
+    std::fprintf(f,"%-16s %-16s %-16s %-10s %10.4f %10.4f %-8s %10.4f\n",ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),otype,ctx.links.offset1[u],(orr>=0)?ctx.link_subtypes.orifices.cd[uorr]:0.0,ctx.links.has_flap_gate[u]?"YES":"NO",(orr>=0)?ctx.link_subtypes.orifices.orate[uorr]:0.0);
     }}
 
     // [WEIRS]
     if(hasLT(ctx,LinkType::WEIR)){sec(f,"WEIRS");
-    std::fprintf(f,";;%-16s %-16s %-16s %-12s %-10s %-10s %-8s %-10s %-10s %-10s\n","Name","FromNode","ToNode","Type","CrestHt","Cd","Gated","EndCon","EndCoeff","Surcharge");
-    std::fprintf(f,";;%-16s %-16s %-16s %-12s %-10s %-10s %-8s %-10s %-10s %-10s\n","----------------","----------------","----------------","------------","----------","----------","--------","----------","----------","----------");
-    static const char* WEIR_TYPE[]={"TRANSVERSE","SIDEFLOW","V-NOTCH","TRAPEZOIDAL"};
+    std::fprintf(f,";;%-16s %-16s %-16s %-12s %-10s %-10s %-8s %-10s %-10s %-10s %-10s %-10s %s\n","Name","FromNode","ToNode","Type","CrestHt","Cd","Gated","EndCon","EndCoeff","Surcharge","RoadWidth","RoadSurf","Coeff.Curve");
+    std::fprintf(f,";;%-16s %-16s %-16s %-12s %-10s %-10s %-8s %-10s %-10s %-10s %-10s %-10s %s\n","----------------","----------------","----------------","------------","----------","----------","--------","----------","----------","----------","----------","----------","----------------");
+    static const char* WEIR_TYPE[]={"TRANSVERSE","SIDEFLOW","V-NOTCH","TRAPEZOIDAL","ROADWAY"};
     for(int j=0;j(j);if(ctx.links.type[u]!=LinkType::WEIR)continue;
     write_obj_comment(f, ctx.links.comments, u);
     const int wr=ctx.link_subtypes.weir_row(j); const auto& WD=ctx.link_subtypes.weirs;
@@ -1388,10 +2492,10 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // surcharge flag defaults it back to YES on re-read, changing drowned-weir
     // flow (weir↔orifice switch) and hence overflow/flooding.
     const int wt=(wr>=0)?static_cast(WD.weir_type[static_cast(wr)]):0;
-    const char* wtStr=(wt>=0&&wt<4)?WEIR_TYPE[wt]:"TRANSVERSE";
+    const char* wtStr=(wt>=0&&wt<5)?WEIR_TYPE[wt]:"TRANSVERSE";
     const char* wgate=ctx.links.has_flap_gate[u]?"YES":"NO";
     const char* wsurch=(wr>=0&&WD.can_surcharge[static_cast(wr)])?"YES":"NO";
-    std::fprintf(f,"%-16s %-16s %-16s %-12s %10.4f %10.4f %-8s %10.4f %10.4f %s\n",
+    std::fprintf(f,"%-16s %-16s %-16s %-12s %10.4f %10.4f %-8s %10.4f %10.4f %-10s",
         ctx.link_names.name_of(j).c_str(),nN(ctx,ctx.links.node1[u]),nN(ctx,ctx.links.node2[u]),
         wtStr,
         (wr>=0)?WD.crest_height[static_cast(wr)]:0.0,
@@ -1400,6 +2504,17 @@ int writeInpFile(const SimulationContext& ctx_internal,
         (wr>=0)?WD.end_contractions[static_cast(wr)]:0.0,
         (wr>=0)?WD.cd2[static_cast(wr)]:0.0,
         wsurch);
+    // ROADWAY road width / surface (legacy columns 11-12, read for that type
+    // only) and the optional Cd(head) curve (column 13, any type).
+    const int cdc=(wr>=0)?WD.cd_curve[static_cast(wr)]:-1;
+    if(wt==4||cdc>=0){
+        const int rs=(wr>=0)?WD.road_surface[static_cast(wr)]:0;
+        std::fprintf(f," %10.4f %-10s",(wr>=0)?WD.road_width[static_cast(wr)]:0.0,
+            rs==1?"PAVED":rs==2?"GRAVEL":"*");
+        if(cdc>=0&&static_cast(cdc)(cdc)].id.c_str());
+    }
+    std::fprintf(f,"\n");
     }}
 
     // [OUTLETS]
@@ -1430,8 +2545,8 @@ int writeInpFile(const SimulationContext& ctx_internal,
 
     // [XSECTIONS]
     {sec(f,"XSECTIONS");
-    std::fprintf(f,";;%-16s %-16s %-12s %-12s %-12s %-12s %-8s\n","Link","Shape","Geom1","Geom2","Geom3","Geom4","Barrels");
-    std::fprintf(f,";;%-16s %-16s %-12s %-12s %-12s %-12s %-8s\n","----------------","----------------","------------","------------","------------","------------","--------");
+    std::fprintf(f,";;%-16s %-16s %-12s %-12s %-12s %-12s %-8s %-8s\n","Link","Shape","Geom1","Geom2","Geom3","Geom4","Barrels","Culvert");
+    std::fprintf(f,";;%-16s %-16s %-12s %-12s %-12s %-12s %-8s %-8s\n","----------------","----------------","------------","------------","------------","------------","--------","--------");
     for(int j=0;j(j);
     // [XSECTIONS] applies to conduits, orifices and weirs only. Pumps and
     // outlets have no cross-section; emitting one (a default CIRCULAR with
@@ -1439,6 +2554,13 @@ int writeInpFile(const SimulationContext& ctx_internal,
     if(ctx.links.type[u]==LinkType::PUMP||ctx.links.type[u]==LinkType::OUTLET)continue;
     const int cr=ctx.link_subtypes.conduit_row(j);
     const int xbarrels=(cr>=0)?ctx.link_subtypes.conduits.barrels[static_cast(cr)]:1;
+    // Culvert code (legacy tok[7], conduits only, link.c:258-264). It is read
+    // back, drives inlet control in the dynamic wave and is persisted by the
+    // GeoPackage writer — but was never written here, so Open -> Save silently
+    // turned every culvert into an ordinary conduit. Legacy offers no way to
+    // skip the Barrels column, so the code can only be reached by emitting
+    // both; a 0 means "not a culvert" and is simply omitted.
+    const int xculvert=(cr>=0)?ctx.link_subtypes.conduits.culvert_code[static_cast(cr)]:0;
     // Emit the retained raw Geom1–Geom4 (preserves trapezoid bottom width /
     // side slopes the derived fields can't reproduce).  xsect_geom1 == 0 means
     // the object was built by a path that didn't populate them; fall back to
@@ -1453,6 +2575,27 @@ int writeInpFile(const SimulationContext& ctx_internal,
             ctx.links.pump_curve_name[u].c_str(),0.0,0.0,0.0,xbarrels);
         continue;
     }
+    // IRREGULAR cross-sections reference a named [TRANSECTS] entry: Geom1 is
+    // the transect NAME, not a dimension. The parser retains it in
+    // pump_curve_name (and keeps xsect_geom1 at 0), so falling through to the
+    // numeric emission below wrote the resolver-derived y_full/w_max where the
+    // name belongs — on reload that numeric failed to resolve as a transect
+    // and the conduit silently degenerated to zero area. The trailing zeros
+    // land in w_max/y_bot/r_bot at reparse but the resolver re-derives all of
+    // them from the transect table; barrels stay in the tok[6] column. Legacy
+    // SWMM returns right after reading the name, so the tail is harmless there.
+    if(ctx.links.xsect_shape[u]==XsectShape::IRREGULAR){
+        const char* tname=ctx.links.pump_curve_name[u].c_str();
+        // API-built link that resolved a transect without retaining the name.
+        if(!*tname&&ctx.links.xsect_curve[u]>=0&&
+           ctx.links.xsect_curve[u](ctx.links.xsect_curve[u])].c_str();
+        std::fprintf(f,"%-16s %-16s %-12s %12.4f %12.4f %12.4f %8d\n",
+            ctx.link_names.name_of(j).c_str(),
+            xsName(static_cast(ctx.links.xsect_shape[u])),
+            tname,0.0,0.0,0.0,xbarrels);
+        continue;
+    }
     // CUSTOM cross-sections reference a named shape curve: Geom1 is the max
     // height and the Geom2 slot holds the curve NAME (not a dimension), barrels
     // stay in the Geom5 column. Emitting numeric geometry drops the curve name,
@@ -1471,11 +2614,31 @@ int writeInpFile(const SimulationContext& ctx_internal,
         g1=ctx.links.xsect_geom1[u]; g2=ctx.links.xsect_geom2[u];
         g3=ctx.links.xsect_geom3[u]; g4=ctx.links.xsect_geom4[u];
     } else {
+        // Fallback for an object built by a path that never populated the raw
+        // Geom1-4 (every .inp- and API-built link does, so this is rare).
+        // It reconstructs only what the derived fields actually carry, and
+        // cannot recover Geom3/Geom4 in general — a shape that needs them is
+        // reported below rather than written wrong in silence.
         g1=ctx.links.xsect_y_full[u]; g2=ctx.links.xsect_w_max[u]; g3=0.0; g4=0.0;
+        // FORCE_MAIN Geom2 is the Hazen-Williams C-factor / D-W roughness,
+        // which xsect::setParams parks in r_bot (legacy xsect.c:266) — w_max
+        // there is the DIAMETER, so the generic fallback wrote the diameter
+        // into the roughness column.
+        if(ctx.links.xsect_shape[u]==XsectShape::FORCE_MAIN)
+            g2=ctx.links.xsect_r_bot[u];
     }
+    // Legacy rejects Geom1 <= 0 for every shape but DUMMY (xsect.c:233) and
+    // answers ERROR 211, which refuses the whole deck. Writing it anyway
+    // produces a file no SWMM 5.x engine will open, so say so.
+    if(warnings&&g1<=0.0&&ctx.links.xsect_shape[u]!=XsectShape::DUMMY)
+        warnings->push_back("[XSECTIONS] link \""+ctx.link_names.name_of(j)+
+            "\": Geom1 is "+std::to_string(g1)+", which SWMM 5.x rejects "
+            "(ERROR 211) for shape "+xsName(static_cast(ctx.links.xsect_shape[u])));
     // Full precision on the geometry: xsect dimensions (e.g. CUSTOM/irregular
     // heights like 0.61875) set conduit conveyance; %.4f truncation perturbs routing.
-    std::fprintf(f,"%-16s %-16s %.15g %.15g %.15g %.15g %8d\n",ctx.link_names.name_of(j).c_str(),xsName(static_cast(ctx.links.xsect_shape[u])),g1,g2,g3,g4,xbarrels);
+    std::fprintf(f,"%-16s %-16s %.15g %.15g %.15g %.15g %8d",ctx.link_names.name_of(j).c_str(),xsName(static_cast(ctx.links.xsect_shape[u])),g1,g2,g3,g4,xbarrels);
+    if(xculvert>0)std::fprintf(f," %8d",xculvert);
+    std::fprintf(f,"\n");
     }}
 
     // [LOSSES]
@@ -1514,9 +2677,12 @@ int writeInpFile(const SimulationContext& ctx_internal,
         ctx.transects.length_factor[ut],
         ctx.transects.x_factor[ut],
         ctx.transects.y_factor[ut]);
+    // Full precision on the GR pairs: they are token-parsed on both engines
+    // (column width is not load-bearing) and %.4f silently rounded >4-dp
+    // stations/elevations on every save. Matches the [XSECTIONS] precedent.
     for(int k=0;k(k);
     if(k%5==0)std::fprintf(f,"GR");
-    std::fprintf(f," %10.4f %10.4f",ctx.transects.elevations[ut][uk],ctx.transects.stations[ut][uk]);
+    std::fprintf(f," %10.15g %10.15g",ctx.transects.elevations[ut][uk],ctx.transects.stations[ut][uk]);
     if(k%5==4||k==nsta-1)std::fprintf(f,"\n");
     }}}
 
@@ -1532,19 +2698,92 @@ int writeInpFile(const SimulationContext& ctx_internal,
         ctx.streets.back_width[u],ctx.streets.back_slope[u],ctx.streets.back_n[u]);
     }}
 
-    // [INLETS]
+    // [INLETS] — the legacy per-type grammar (inlet.c:321-327). A COMBO design
+    // is written the way legacy encodes it: a GRATE line and a CURB line
+    // sharing one name, which handle_inlets merges back into one row.
     if(ctx.inlets.count()>0){sec(f,"INLETS");
+    auto grate_line=[&](const std::string& name,size_t u,const char* kw){
+        std::fprintf(f,"%-16s %-12s %10.4f %10.4f %s",name.c_str(),kw,
+            ctx.inlets.length[u],ctx.inlets.width[u],ctx.inlets.grate_type[u].c_str());
+        if(ieq(ctx.inlets.grate_type[u],"GENERIC")){
+            std::fprintf(f," %g",ctx.inlets.open_area[u]);
+            if(ctx.inlets.splash_veloc[u]>0) std::fprintf(f," %g",ctx.inlets.splash_veloc[u]);
+        }
+        std::fprintf(f,"\n");
+    };
+    auto curb_line=[&](const std::string& name,size_t u,bool drop){
+        std::fprintf(f,"%-16s %-12s %10.4f %10.4f",name.c_str(),drop?"DROP_CURB":"CURB",
+            ctx.inlets.curb_length[u],ctx.inlets.curb_height[u]);
+        // DROP_CURB has no throat token in the legacy grammar.
+        if(!drop){int th=ctx.inlets.curb_throat[u]; if(th<0||th>2)th=2;
+            std::fprintf(f," %s",kInletThroatWords[th]);}
+        std::fprintf(f,"\n");
+    };
     for(int j=0;j(j);
-    std::fprintf(f,"%-16s %-12s %10.4f %10.4f",
-        ctx.inlets.names[u].c_str(),ctx.inlets.inlet_type[u].c_str(),
-        ctx.inlets.length[u],ctx.inlets.width[u]);
-    if(!ctx.inlets.grate_type[u].empty())
-        std::fprintf(f," %s",ctx.inlets.grate_type[u].c_str());
-    if(ctx.inlets.open_area[u]>0)
-        std::fprintf(f," %g",ctx.inlets.open_area[u]);
-    if(ctx.inlets.splash_veloc[u]>0)
-        std::fprintf(f," %g",ctx.inlets.splash_veloc[u]);
-    std::fprintf(f,"\n");
+    write_obj_comment(f, ctx.inlets.comments, u);
+    const std::string& name=ctx.inlets.names[u];
+    const std::string& t=ctx.inlets.inlet_type[u];
+    if(t=="COMBO"){ grate_line(name,u,"GRATE"); curb_line(name,u,false); }
+    else if(t=="GRATE"||t=="DROP_GRATE") grate_line(name,u,t.c_str());
+    else if(t=="CURB"||t=="DROP_CURB")   curb_line(name,u,t=="DROP_CURB");
+    else if(t=="CUSTOM")
+        std::fprintf(f,"%-16s %-12s %s\n",name.c_str(),"CUSTOM",ctx.inlets.curve_id[u].c_str());
+    else   // SLOTTED (and any type string carried through verbatim)
+        std::fprintf(f,"%-16s %-12s %10.4f %10.4f\n",name.c_str(),t.c_str(),
+            ctx.inlets.length[u],ctx.inlets.width[u]);
+    }}
+
+    // [INLET_USAGE]
+    // Grammar: Link Inlet Node #Inlets %Clog Qmax aLocal wLocal Placement
+    // Parsed into ctx.inlet_usages but previously never written, so every
+    // inlet-to-link assignment was lost on save and [STREETS]/[INLETS] became
+    // inert. clog_factor is stored as 1 - pctClogged/100 (InfraHandler).
+    // Node-hosted rows belong to [INLET_JUNCTIONS] and are skipped here.
+    bool anyLinkUsage=false;
+    for(int j=0;j(j)]<0||swmm5){anyLinkUsage=true;break;}
+    if(anyLinkUsage){sec(f,"INLET_USAGE");
+    std::fprintf(f,";;%-16s %-16s %-16s %-8s %-8s %-10s %-10s %-10s %-10s\n","Link","Inlet","Node","#Inlets","%Clog","Qmax","aLocal","wLocal","Placement");
+    std::fprintf(f,";;%-16s %-16s %-16s %-8s %-8s %-10s %-10s %-10s %-10s\n","----------------","----------------","----------------","--------","--------","----------","----------","----------","----------");
+    const char* const* kPlacement=kInletPlacementWords;
+    for(int j=0;j(j);
+    int li=ctx.inlet_usages.link_index[u];
+    const int nh=ctx.inlet_usages.node_host[u];
+    if(nh>=0){
+        if(!swmm5)continue;
+        // SWMM 5.x profile: the inlet junction's row moves onto its approach
+        // conduit — legacy books the capture at that conduit's downstream node,
+        // which is this junction — keeping design, capture node and the
+        // placement columns (plan §2.3).
+        li=edit::ij_host_conduit(ctx,/*host_kind=*/1,nh);
+        if(li<0){
+            note("Node "+ctx.node_names.name_of(nh)+
+                 ": inlet junction has no approach conduit; its inlet is dropped in the SWMM 5.x profile");
+            continue;
+        }
+    }
+    const int di=ctx.inlet_usages.design_index[u];
+    const int ni=ctx.inlet_usages.node_index[u];
+    // The reader drops rows naming an unknown link/inlet/node, so a stale index
+    // here would be silently discarded on reload — skip it with a warning
+    // instead of writing '*'.
+    if(li<0||li>=ctx.n_links()||di<0||di>=ctx.inlets.count()||ni<0||ni>=ctx.n_nodes()){
+        if(warnings)
+            warnings->push_back("[INLET_USAGE] row "+std::to_string(j)+
+                                ": unresolved link/inlet/node; row omitted");
+        continue;
+    }
+    int pl=ctx.inlet_usages.placement[u]; if(pl<0||pl>2)pl=0;
+    std::fprintf(f,"%-16s %-16s %-16s %8d %8.4g %10.4g %10.4g %10.4g %-10s\n",
+        ctx.link_names.name_of(li).c_str(),
+        ctx.inlets.names[static_cast(di)].c_str(),
+        ctx.node_names.name_of(ni).c_str(),
+        ctx.inlet_usages.num_inlets[u],
+        (1.0-ctx.inlet_usages.clog_factor[u])*100.0,
+        ctx.inlet_usages.flow_limit[u],
+        ctx.inlet_usages.local_depress[u],
+        ctx.inlet_usages.local_width[u],
+        kPlacement[pl]);
     }}
 
     // [CONTROLS]
@@ -1580,7 +2819,29 @@ int writeInpFile(const SimulationContext& ctx_internal,
     for(int p=0;p(p);
     write_obj_comment(f, ctx.pollutants.comments, u);
     const char*un="MG/L";if(ctx.pollutants.units[u]==MassUnits::UG_PER_L)un="UG/L";if(ctx.pollutants.units[u]==MassUnits::COUNTS_PER_L)un="#/L";
-    std::fprintf(f,"%-16s %-8s %10.4f %10.4f %10.4f %10.4f %-10s %-16s %10.4f %10.4f %10.4f\n",pN(ctx,p),un,ctx.pollutants.c_rain[u],ctx.pollutants.c_gw[u],ctx.pollutants.c_rdii[u],ctx.pollutants.k_decay[u],ctx.pollutants.snow_only[u]?"YES":"NO",ctx.pollutants.co_pollut[u]>=0?pN(ctx,ctx.pollutants.co_pollut[u]):"*",ctx.pollutants.co_frac[u],ctx.pollutants.c_dwf[u],ctx.pollutants.init_conc[u]);
+    std::fprintf(f,"%-16s %-8s %10.4f %10.4f %10.4f %10.4f %-10s %-16s %10.4f %10.4f %10.4f\n",pN(ctx,p),un,ctx.pollutants.c_rain[u],ctx.pollutants.c_gw[u],ctx.pollutants.c_rdii[u],ctx.pollutants.k_decay[u]*constants::SEC_PER_DAY,ctx.pollutants.snow_only[u]?"YES":"NO",ctx.pollutants.co_pollut[u]>=0?pN(ctx,ctx.pollutants.co_pollut[u]):"*",ctx.pollutants.co_frac[u],ctx.pollutants.c_dwf[u],ctx.pollutants.init_conc[u]);
+    }}
+
+    // [INITIAL_QUALITY] — per-element initial concentrations (raw constituent
+    // name + raw value retained by the store; resolved element names preferred,
+    // falling back to the retained raw name for never-resolved rows).
+    if(ctx.initial_quality.count()>0||!ctx.initial_quality.file.empty()){sec(f,"INITIAL_QUALITY");
+    // U2: the CSV sidecar is referenced, not expanded — its rows carry
+    // from_file and are skipped below.
+    if(!ctx.initial_quality.file.empty())
+        std::fprintf(f,"%-8s %s\n","FILE",ctx.initial_quality.file.c_str());
+    std::fprintf(f,";;%-8s %-16s %-16s %-10s\n","Scope","Element","Constituent","Value");
+    std::fprintf(f,";;%-8s %-16s %-16s %-10s\n","--------","----------------","----------------","----------");
+    for(int j=0;j(j);
+    const auto& iq=ctx.initial_quality;
+    if(u=0&&ei=0&&ei0&&ctx.buildup.n_pollutants>0){sec(f,"BUILDUP");
+    // [BUILDUP] — pollutant rows, then (BW-MSX) the reactions component's
+    // species from ctx.reactions.surface (resolved params, by name).
+    const auto& msxs=ctx.reactions.surface;
+    auto msxHasBu=[&]{for(std::size_t k=0;k0&&ctx.buildup.n_pollutants>0)||msxHasBu){sec(f,"BUILDUP");
     std::fprintf(f,";;%-16s %-16s %-10s %-10s %-10s %-10s %-8s\n","LandUse","Pollutant","FuncType","Coeff1","Coeff2","Coeff3","PerUnit");
     std::fprintf(f,";;%-16s %-16s %-10s %-10s %-10s %-10s %-8s\n","----------------","----------------","----------","----------","----------","----------","--------");
     static const char* buNames[]={"NONE","POW","EXP","SAT","EXT"};
@@ -1630,10 +2895,31 @@ int writeInpFile(const SimulationContext& ctx_internal,
         (ft>=0&&ft<=4)?buNames[ft]:"NONE",
         ctx.buildup.coeff1[idx],ctx.buildup.coeff2[idx],ctx.buildup.coeff3[idx],
         ctx.buildup.normalizer[idx]==0?"AREA":"CURB");
+    }}
+    for(int lu=0;lu(m)(m)]:std::string{};
+    if(ft==4){
+        const int ts=static_cast(msxs.bu_c3[idx]);
+        const std::string tsn=(ts>=0&&ts(ctx.tables.tables.size()))?ctx.tables.tables[static_cast(ts)].id:std::string{"*"};
+        std::fprintf(f,"%-16s %-16s %-10s %10.4f %10.4f %-10s %-8s\n",
+            ctx.landuse_names.name_of(lu).c_str(),sp.c_str(),"EXT",
+            msxs.bu_c1[idx],msxs.bu_c2[idx],tsn.c_str(),
+            msxs.bu_normalizer[idx]==0?"AREA":"CURB");
+    }else{
+        std::fprintf(f,"%-16s %-16s %-10s %10.4f %10.4f %10.4f %-8s\n",
+            ctx.landuse_names.name_of(lu).c_str(),sp.c_str(),
+            (ft>=0&&ft<=4)?buNames[ft]:"NONE",
+            msxs.bu_c1[idx],msxs.bu_c2[idx],msxs.bu_c3[idx],
+            msxs.bu_normalizer[idx]==0?"AREA":"CURB");
+    }
     }}}
 
-    // [WASHOFF]
-    if(ctx.washoff.n_landuses>0&&ctx.washoff.n_pollutants>0){sec(f,"WASHOFF");
+    // [WASHOFF] — pollutant rows, then (BW-MSX) species rows.
+    if((ctx.washoff.n_landuses>0&&ctx.washoff.n_pollutants>0)||msxHasWo){sec(f,"WASHOFF");
     std::fprintf(f,";;%-16s %-16s %-10s %-10s %-10s %-10s %-10s\n","LandUse","Pollutant","FuncType","Coeff","Expon","SweepEff","BmpEff");
     std::fprintf(f,";;%-16s %-16s %-10s %-10s %-10s %-10s %-10s\n","----------------","----------------","----------","----------","----------","----------","----------");
     static const char* woNames[]={"NONE","EXP","RC","EMC"};
@@ -1647,27 +2933,52 @@ int writeInpFile(const SimulationContext& ctx_internal,
         (ft>=0&&ft<=3)?woNames[ft]:"NONE",
         ctx.washoff.coeff[idx],ctx.washoff.expon[idx],
         ctx.washoff.sweep_effic[idx],ctx.washoff.bmp_effic[idx]);
+    }}
+    for(int lu=0;lu(m)(m)]:std::string{};
+    std::fprintf(f,"%-16s %-16s %-10s %10.4f %10.4f %10.2f %10.2f\n",
+        ctx.landuse_names.name_of(lu).c_str(),sp.c_str(),
+        (ft>=0&&ft<=3)?woNames[ft]:"NONE",
+        msxs.wo_coeff[idx],msxs.wo_expon[idx],
+        msxs.wo_sweep_effic[idx],msxs.wo_bmp_effic[idx]);
     }}}
 
     // [LOADINGS] — initial pollutant buildup per subcatchment (stored in
     // ctx.subcatches.conc by handle_loadings; see also the object-deletion
     // re-pack tests). Zero rows are skipped: absent rows parse back to 0.
-    if(ctx.subcatches.conc_n_pollutants>0&&ctx.n_subcatches()>0&&ctx.n_pollutants()>0){
+    {
     const int np=ctx.subcatches.conc_n_pollutants;
+    const bool polluts=(np>0&&ctx.n_subcatches()>0&&ctx.n_pollutants()>0);
     bool any=false;
-    for(std::size_t i=0;i(s)*static_cast(np)+static_cast(p);
-    if(idx>=ctx.subcatches.conc.size())break;
-    const double w=ctx.subcatches.conc[idx];
+    if(idx>=ctx.subcatches.init_loading.size())break;
+    const double w=ctx.subcatches.init_loading[idx];
     if(w==0.0)continue;
     std::fprintf(f,"%-16s %-16s %10.4f\n",
         ctx.subcatch_names.name_of(s).c_str(),pN(ctx,p),w);
+    }}
+    if(anyMsx)for(int s=0;s=msxs.init_loading.size())break;
+    const double w=msxs.init_loading[msxs.sidx(s,m)];
+    if(w==0.0)continue;
+    const std::string& sp=(static_cast(m)(m)]:std::string{};
+    std::fprintf(f,"%-16s %-16s %10.4f\n",
+        ctx.subcatch_names.name_of(s).c_str(),sp.c_str(),w);
     }}}}
 
     // [TREATMENT]
@@ -1757,7 +3068,8 @@ int writeInpFile(const SimulationContext& ctx_internal,
 
     // [RDII_DECAY] (exponential IA decay parameters; optional degree-day snow
     // clause "SNOW snow_T snow_ddf" appended to rows with the snow model on)
-    if(ctx.rdii_decay.count()>0){sec(f,"RDII_DECAY");
+    if(swmm5&&ctx.rdii_decay.count()>0) note("[RDII_DECAY] omitted (SWMM 5.x profile)");
+    if(!swmm5&&ctx.rdii_decay.count()>0){sec(f,"RDII_DECAY");
     std::fprintf(f,";;%-16s %-8s %-10s %-10s %-10s %-8s %-10s %-10s %-4s %-8s %-10s\n",
         "UHGroup","Response","k_dep","k_0","k_T","T_ref","theta_rec","T_freeze",
         "Snow","snow_T","snow_ddf");
@@ -1819,31 +3131,34 @@ int writeInpFile(const SimulationContext& ctx_internal,
         std::fprintf(f,"%-16s FILE         \"%s\"\n",tN(ctx,t),tok.c_str());
         continue;
     }
-    // PostParseResolver offsets relative time series by start_date so the
-    // engine can do absolute OADate lookups.  Detect this using the same
-    // condition it uses (x[0] - start_date < 366) and strip the offset
-    // before writing so the output matches the original time-only format.
-    const double startDate = ctx.options.start_date;
-    const double x0 = tb.x.empty() ? 0.0 : tb.x.front();
-    const bool wasRelative = (x0 - startDate) >= 0.0 && (x0 - startDate) < 366.0;
-    // A true absolute series (calendar dates entered by the user) has x values
-    // that are large OADates even before any start_date offset would be added
-    // — i.e. x0 is already >> 3650 regardless of start_date.
-    const bool isAbsolute  = !wasRelative && x0 >= 3650.0;
-
+    // Rows below n_relative were authored as elapsed times anchored at the
+    // simulation start; rel_anchor is the start_date offset the resolver
+    // baked into them (0 if the model was never resolved). Subtract it to
+    // emit those rows back in their authored time-only form. All later rows
+    // carry explicit dates and are written date + time — never inferred
+    // from x-value magnitude (the old x[0]-start heuristic rewrote a series
+    // the user authored WITH dates near the start date as elapsed times,
+    // silently re-basing that data onto START_DATE).
     char dateBuf[16], timeBuf[12];
     for(size_t k=0;k(k) < tb.n_relative;
+        if(relative){
+            // Elapsed fractional days → H:MM[:SS]; hours may exceed 23.
+            // Round to whole seconds first so 0.99999998 days prints as
+            // 24:00 and not the truncated-then-rounded "23:60".
+            const double xv = tb.x[k] - tb.rel_anchor;
+            const long long totalSecs = std::llround(xv * 86400.0);
+            const long long hh = totalSecs / 3600;
+            const int       mm = static_cast((totalSecs / 60) % 60);
+            const int       ss = static_cast(totalSecs % 60);
+            if(ss)
+                std::fprintf(f,"%-16s %lld:%02d:%02d %12.6f\n",tN(ctx,t),hh,mm,ss,tb.y[k]);
+            else
+                std::fprintf(f,"%-16s %lld:%02d %12.6f\n",tN(ctx,t),hh,mm,tb.y[k]);
         } else {
-            // Relative: convert fractional days → HH:MM; allow hours > 23.
-            const double totalHours = xv * 24.0;
-            const int hh = static_cast(totalHours);
-            const int mm = static_cast((totalHours - hh) * 60.0 + 0.5);
-            std::fprintf(f,"%-16s %d:%02d %12.6f\n",tN(ctx,t),hh,mm,tb.y[k]);
+            fmt_date(dateBuf, tb.x[k]);
+            fmt_time(timeBuf, tb.x[k]);
+            std::fprintf(f,"%-16s %-12s %-8s %12.6f\n",tN(ctx,t),dateBuf,timeBuf,tb.y[k]);
         }
     }
     }}}
@@ -1867,7 +3182,10 @@ int writeInpFile(const SimulationContext& ctx_internal,
     // The curve TYPE keyword goes on the FIRST row only; continuation rows are
     // "Name X Y". Legacy SWMM reads a repeated type on a later row as the
     // X-value → ERROR 211 (invalid number).
-    for(size_t k=0;k0){sec(f,"USER_FLAGS");
+    if(swmm5&&ctx.user_flags.def_count()>0) note("[USER_FLAGS] / [USER_FLAG_VALUES] omitted (SWMM 5.x profile)");
+    if(!swmm5&&ctx.user_flags.def_count()>0){sec(f,"USER_FLAGS");
     std::fprintf(f,";;%-20s %-10s %s\n","Name","Type","Description");
     std::fprintf(f,";;%-20s %-10s\n","--------------------","----------");
     for(const auto&d:ctx.user_flags.all_defs()){
@@ -2004,7 +3330,7 @@ int writeInpFile(const SimulationContext& ctx_internal,
     }}
 
     // [USER_FLAG_VALUES]
-    if(ctx.user_flags.value_count()>0){sec(f,"USER_FLAG_VALUES");
+    if(!swmm5&&ctx.user_flags.value_count()>0){sec(f,"USER_FLAG_VALUES");
     std::fprintf(f,";;%-14s %-16s %-20s %s\n","ObjectType","ObjectName","FlagName","Value");
     std::fprintf(f,";;%-14s %-16s %-20s\n","--------------","----------------","--------------------");
     for(const auto&kv:ctx.user_flags.all_values()){const auto&k=kv.first;
@@ -2076,16 +3402,66 @@ int writeInpFile(const SimulationContext& ctx_internal,
     }
 
     // [PLUGINS]
-    if(!ctx.plugin_specs.empty()){sec(f,"PLUGINS");
+    if(swmm5&&!ctx.plugin_specs.empty()) note("[PLUGINS] omitted (SWMM 5.x profile)");
+    if(!swmm5&&!ctx.plugin_specs.empty()){sec(f,"PLUGINS");
     for(const auto&ps:ctx.plugin_specs){std::fprintf(f,"%s",ps.path.c_str());
     for(const auto&a:ps.init_args)std::fprintf(f," %s",a.c_str());std::fprintf(f,"\n");
     }}
 
+    // Do not publish component files after a detected main-output failure.
+    if (std::ferror(f) || std::fflush(f) != 0) {
+        note("Cannot serialize model output '" + path + "' before component configurations");
+        return -1;
+    }
+
+    // [PROCESS_COMPONENTS] — Unified Transport suite D-UT8 (round-trip; the
+    // component config FILES are each component's own to write, never ours).
+    // The config= reference is an external-file slot like any other, so it
+    // goes through emit_path_token (Slice IO-4): an absolute path is rebased
+    // against the destination directory, a relative one passes through.
+    if(swmm5&&!ctx.process_component_specs.empty()) note("[PROCESS_COMPONENTS] omitted (SWMM 5.x profile)");
+    if(!swmm5&&!ctx.process_component_specs.empty()){sec(f,"PROCESS_COMPONENTS");
+    for(const auto&pc:ctx.process_component_specs){std::fprintf(f,"%s",pc.id.c_str());
+    if(!pc.config_path.empty()){const std::string cfg=
+    emit_path_token(pc.config_path,dst_dir,force_abs_paths,warnings);
+    std::fprintf(f," config=\"%s\"",cfg.c_str());
+
+    if (!writeComponentConfig(ctx, pc, cfg, dst_dir, warnings, opts)) return -1;
+    }
+    for(const auto&a:pc.args)std::fprintf(f," %s=\"%s\"",a.first.c_str(),a.second.c_str());
+    std::fprintf(f,"\n");
+    }}
+
+    // Embedded component sections ([REACTION_*] today) are NOT serialized —
+    // there is no per-component saveData() until IO3, and the intended layout
+    // is an external config file anyway. Say so rather than dropping
+    // user-authored model data silently: whether they were applied or
+    // overridden by an external file, they are gone from the deck we just
+    // wrote.
+    if(warnings && !ctx.embedded_component_sections.empty()){
+    std::string tags;
+    for(const auto&es:ctx.embedded_component_sections){
+    if(!tags.empty())tags+=", ";tags+="["+es.first+"]";}
+    warnings->push_back(
+    "Embedded component sections are NOT written back to the .inp and are "
+    "lost from this save: "+tags+". Move them to an external component "
+    "config file registered in [PROCESS_COMPONENTS] (config=\"model.rxn\") "
+    "to keep them — per-component serialization arrives with plan phase IO3.");
+    }
+
     // [2D_*] — 2D surface-routing model definition (no-op for 1D models
     // and for engine builds without the 2D module).
-    write2DSections(f, ctx, dst_dir, force_abs_paths, warnings);
-
-    std::fclose(f);
+    // Do not publish a sidecar after an already-detected main stream failure.
+    // The outputs still need coordinated publication/rollback at project level.
+    if (std::ferror(f) || std::fflush(f) != 0) {
+        const auto ec = errno ? std::error_code(errno, std::generic_category())
+                              : std::make_error_code(std::errc::io_error);
+        note("Cannot serialize model output '" + path + "': " + ec.message());
+        return -1;
+    }
+    if (!swmm5 && !write2DSections(f, ctx, dst_dir, force_abs_paths, warnings, opts))
+        return -1;
+    if (!output.commit()) { note(output.error()); return -1; }
     return 0;
 }
 
diff --git a/src/engine/core/InpWriter.hpp b/src/engine/core/InpWriter.hpp
index 94a5570cd..62fa5bb1b 100644
--- a/src/engine/core/InpWriter.hpp
+++ b/src/engine/core/InpWriter.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InpWriter.hpp
  * @brief Write a SimulationContext to a SWMM .inp file.
@@ -10,12 +26,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INP_WRITER_HPP
 #define OPENSWMM_INP_WRITER_HPP
 
+#include 
 #include 
 #include 
 
@@ -54,12 +71,58 @@ namespace inp_writer {
  * @param path      Output file path.
  * @param warnings  Optional sink for non-fatal portability warnings
  *                  (cross-volume slots, etc.). Pass nullptr to discard.
+ * @details Main INP, engine-owned mesh and written component configs use adjacent temporary files,
+ *          checked write/flush/sync/close, and individual atomic replacement.
+ *          Errors are returned and described in warnings when supplied.
+ *          This is not a multi-file transaction: a later main-file failure
+ *          does not roll back an already-published mesh or component
+ *          configuration. Output redirection/recovery remain caller concerns.
  * @returns 0 on success, -1 on file error.
  */
 int writeInpFile(const SimulationContext& ctx,
                  const std::string&       path,
                  std::vector* warnings = nullptr);
 
+/**
+ * @brief Write profile: which engine the file is written for.
+ *
+ * @details `Full` is the native format. `Swmm5` writes a file a SWMM 5.x
+ *          engine can read (MULTI_ENGINE plan V2 Phase 4): the v6-only
+ *          sections are omitted ([2D_*], [PLUGINS], [PROCESS_COMPONENTS],
+ *          [USER_FLAGS], [USER_FLAG_VALUES], [RDII_DECAY]), v6-only option
+ *          keys are omitted and incompatible values mapped (FLOW_ROUTING FV →
+ *          DYNWAVE, SURCHARGE_METHOD DYNAMIC_SLOT/TPA → SLOT), a virtual
+ *          junction becomes an ordinary junction, and an inlet junction
+ *          becomes an ordinary junction plus an [INLET_USAGE] row on its
+ *          approach conduit with the same capture node (the legacy-equivalent
+ *          model). Every substitution is reported through `warnings`; the
+ *          file starts with a comment naming the profile.
+ *
+ *          `Swmm5Stock` is `Swmm5` for a STOCK EPA SWMM 5 engine (5.2.4 as
+ *          built for SWMMVis): it additionally drops the positional grammar
+ *          extensions the in-tree legacy 5.3.0 engine added — the
+ *          [SUBCATCHMENTS] Snowpack `*` placeholder with the RainScale /
+ *          SnowScale columns behind it, and the [RAINGAGES] scale-factor
+ *          column — which a stock parser reads as an object name or a
+ *          malformed row (ERROR 209 / 200). A dropped factor that is not 1.0
+ *          is reported through `warnings`, since it is real model content.
+ */
+struct InpWriteOptions {
+    enum class Profile { Full, Swmm5, Swmm5Stock };
+    Profile profile = Profile::Full;
+    enum class OutputKind { Model = 0, Mesh = 1, Component = 2 };
+    // Final paths remain the reference anchor. Every actual output is sent
+    // here before opening; an empty mapped path refuses that output.
+    // The caller owns staging cleanup, validation and publication.
+    std::function map_output;
+
+};
+
+int writeInpFile(const SimulationContext&  ctx,
+                 const std::string&        path,
+                 std::vector* warnings,
+                 const InpWriteOptions&    opts);
+
 } // namespace inp_writer
 } // namespace openswmm
 
diff --git a/src/engine/core/InterfaceFile.cpp b/src/engine/core/InterfaceFile.cpp
index b942251bb..74eb879ac 100644
--- a/src/engine/core/InterfaceFile.cpp
+++ b/src/engine/core/InterfaceFile.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InterfaceFile.cpp
  * @brief Routing interface file — coupling between separate SWMM simulations.
@@ -19,10 +35,12 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "InterfaceFile.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "Constants.hpp"
 #include "SimulationContext.hpp"
 #include "DateTime.hpp"
 #include "UnitConversion.hpp"
@@ -92,13 +110,13 @@ int InterfaceManager::openFiles(const std::string& infile_path,
 
     // Open output file for writing
     if (!outfile_path.empty()) {
-        outfile_ = std::fopen(outfile_path.c_str(), "wt");
+        outfile_ = openswmm::io::fopen_utf8(outfile_path, "wt");
         if (!outfile_) return -2;
     }
 
     // Open input file for reading
     if (!infile_path.empty()) {
-        infile_ = std::fopen(infile_path.c_str(), "rt");
+        infile_ = openswmm::io::fopen_utf8(infile_path, "rt");
         if (!infile_) return -3;
     }
 
@@ -311,6 +329,9 @@ void InterfaceManager::readInflows(SimulationContext& ctx, double current_time)
         if (node < 0 || node >= ctx.n_nodes()) continue;
 
         double flow = getFlow(i, iface_frac_);
+        // legacy addIfaceInflows: `if (fabs(q) < FLOW_TOL) continue;` — the
+        // flow AND its pollutant loads are skipped below the floor.
+        if (std::fabs(flow) < constants::FLOW_TOL) continue;
         ctx.nodes.iface_inflow[static_cast(node)] += flow;
 
         // Add interpolated quality mass rates (w = q * c), matching legacy
diff --git a/src/engine/core/InterfaceFile.hpp b/src/engine/core/InterfaceFile.hpp
index 24194eaff..845f67765 100644
--- a/src/engine/core/InterfaceFile.hpp
+++ b/src/engine/core/InterfaceFile.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InterfaceFile.hpp
  * @brief Routing interface file — coupling between separate SWMM simulations.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INTERFACE_FILE_HPP
diff --git a/src/engine/core/PathResolver.cpp b/src/engine/core/PathResolver.cpp
index ed01314b7..41656ac3d 100644
--- a/src/engine/core/PathResolver.cpp
+++ b/src/engine/core/PathResolver.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PathResolver.cpp
  * @brief PathResolver implementation — see PathResolver.hpp.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "PathResolver.hpp"
+#include "FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include 
 #include 
@@ -197,20 +214,20 @@ std::string resolveRelative(const std::string& stored_token,
     // forward-slash and Windows accepts them in filesystem ops. On POSIX this
     // is identical to the prior output.
     if (isAbsolutePath(stored_token)) {
-        fs::path p(toForwardSlashes(stored_token));
-        return p.generic_string();
+        fs::path p = openswmm::io::utf8_path(toForwardSlashes(stored_token));
+        return openswmm::io::path_utf8(p, /*generic=*/true);
     }
 
     // No anchor → return as-is (caller owns the relative-token semantics).
     if (anchor_dir.empty()) {
-        fs::path p(toForwardSlashes(stored_token));
-        return p.lexically_normal().generic_string();
+        fs::path p = openswmm::io::utf8_path(toForwardSlashes(stored_token));
+        return openswmm::io::path_utf8(p.lexically_normal(), /*generic=*/true);
     }
 
     // Join anchor + token, lexically normalise (collapses "..").
-    fs::path joined = fs::path(toForwardSlashes(anchor_dir))
-                    / fs::path(toForwardSlashes(stored_token));
-    return joined.lexically_normal().generic_string();
+    fs::path joined = openswmm::io::utf8_path(toForwardSlashes(anchor_dir))
+                    / openswmm::io::utf8_path(toForwardSlashes(stored_token));
+    return openswmm::io::path_utf8(joined.lexically_normal(), /*generic=*/true);
 }
 
 // ============================================================================
@@ -261,7 +278,8 @@ RelativeResult makeRelative(const std::string& target_absolute,
     // Only when both roots are empty (POSIX vs POSIX) do we treat them as the
     // same volume and fall through to the relative computation below.
     if (!eq_ci(tgt_root, anc_root)) {
-        r.path = fs::path(tgt_fs).generic_string();
+        r.path = openswmm::io::path_utf8(
+            openswmm::io::utf8_path(tgt_fs), /*generic=*/true);
         r.classification = PathClass::AbsoluteCrossVolume;
         r.warning = "target on a different volume ('" + tgt_root
                   + "' vs '" + anc_root + "') — cannot express relatively";
@@ -282,25 +300,31 @@ RelativeResult makeRelative(const std::string& target_absolute,
     if (tgt_body.empty() || tgt_body.front() != '/') tgt_body.insert(0, "/");
     if (anc_body.empty() || anc_body.front() != '/') anc_body.insert(0, "/");
 
-    fs::path tgt(tgt_body);
-    fs::path anc(anc_body);
+    // utf8_path/path_utf8 throughout: this whole function is UTF-8 string in,
+    // UTF-8 string out, and fs::path is only a lexical normaliser here. The
+    // narrow round trip (path(std::string) -> generic_string()) is lossy on
+    // Windows for any byte sequence the ANSI code page cannot represent (#7).
+    fs::path tgt = openswmm::io::utf8_path(tgt_body);
+    fs::path anc = openswmm::io::utf8_path(anc_body);
     fs::path prox = tgt.lexically_proximate(anc);
 
     if (prox.empty() || prox.is_absolute()) {
-        r.path = fs::path(tgt_fs).generic_string();
+        r.path = openswmm::io::path_utf8(
+            openswmm::io::utf8_path(tgt_fs), /*generic=*/true);
         r.classification = PathClass::AbsoluteSameVolume;
         r.warning = "lexical relative form unavailable";
         return r;
     }
 
-    std::string out = prox.generic_string();   // forward slashes
+    std::string out = openswmm::io::path_utf8(prox, /*generic=*/true);  // forward slashes
     out = collapseSlashesAndDots(out);
     // lexically_proximate may return "" for an exact match; surface as "."
     if (out.empty()) out = ".";
 
     const int up = countUpLevels(out);
     if (up > max_up_levels) {
-        r.path = fs::path(tgt_fs).generic_string();
+        r.path = openswmm::io::path_utf8(
+            openswmm::io::utf8_path(tgt_fs), /*generic=*/true);
         r.classification = PathClass::AbsoluteSameVolume;
         r.warning = "relative form exceeds " + std::to_string(max_up_levels)
                   + " '..' levels (would be " + std::to_string(up) + ")";
diff --git a/src/engine/core/PathResolver.hpp b/src/engine/core/PathResolver.hpp
index de90b6dd8..1ffabc658 100644
--- a/src/engine/core/PathResolver.hpp
+++ b/src/engine/core/PathResolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PathResolver.hpp
  * @brief Pure-function path normalisation and relative-path math.
@@ -25,7 +41,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_PATH_RESOLVER_HPP
diff --git a/src/engine/core/PerfTimers.hpp b/src/engine/core/PerfTimers.hpp
index dbc7918c7..f259103e9 100644
--- a/src/engine/core/PerfTimers.hpp
+++ b/src/engine/core/PerfTimers.hpp
@@ -9,6 +9,8 @@
 // set. Zero cost when the env var is unset except the clock reads themselves.
 // -----------------------------------------------------------------------------
 #include 
+#include 
+#include 
 
 namespace openswmm::perf {
 
@@ -16,6 +18,235 @@ inline double sec_2d_window  = 0.0;  // full 2D advance window (rainfall+couplin
 inline double sec_2d_advance = 0.0;  // pure 2D solve (solver_->advance)
 inline double sec_1d_step    = 0.0;  // 1D routing (router_.step)
 
+// ---------------------------------------------------------------------------
+// Load-phase accumulators — the open() / initialize() / start() window, which
+// is what the user sees between clicking Run and the first routing step. Same
+// env gate and same ScopedTimer as above; reset by open() so a process that
+// runs several models reports each one separately.
+// ---------------------------------------------------------------------------
+
+inline double sec_open_prescan2d = 0.0;  // twoD::prescan2DUnitsHeader (whole-file pass)
+inline double sec_open_read      = 0.0;  // input_plugin->read (tokenize + handlers)
+// open.read split: the line scan (getline, trim, section_lines assembly) is
+// everything in read() that is not a section handler. Dispatch is measured and
+// scan is derived as the remainder, so the two always sum to open.read.
+inline double sec_read_dispatch  = 0.0;  // SectionRegistry handler execution
+inline double sec_open_resolve   = 0.0;  // input::resolve_cross_references
+inline double sec_open_validate  = 0.0;  // validate_project
+
+// resolve_cross_references sub-phases (sum <= sec_open_resolve; the remainder
+// is everything not individually bracketed).
+inline double sec_res_extfiles   = 0.0;  // FILE-backed timeseries/curve loads
+inline double sec_res_tables     = 0.0;  // gage/inflow/table name bindings
+inline double sec_res_transects  = 0.0;  // transect + street/inlet resolution
+inline double sec_res_xsect      = 0.0;  // per-link cross-section parameter loop
+inline double sec_res_shrink     = 0.0;  // shrink_all_to_fit
+
+inline double sec_init_state      = 0.0; // initialize() body before init_modules()
+inline double sec_init_hydraulics = 0.0; // initHydraulics (router_.init, FV mesh build)
+inline double sec_init_hydrology  = 0.0; // initHydrology
+inline double sec_init_quality    = 0.0; // initQuality
+inline double sec_init_geometry   = 0.0; // initGeometry
+
+inline double sec_start_iface   = 0.0;   // [FILES] interface-file open block
+inline double sec_start_plugins = 0.0;   // plugins_.prepare_all (report preamble + .out header)
+
+// ---------------------------------------------------------------------------
+// FV 1D solver phase breakdown. `sec_1d_step` brackets the whole router step,
+// which is enough to say the FV solver is slow and nothing about WHY. These
+// split it by phase so a plan can be ranked against a profile instead of a
+// recollection.
+//
+// Granularity is per-substep-phase, never per-cell or per-face: at hundreds of
+// substeps a steady_clock read per phase is noise, at millions of faces it
+// would BE the profile. The counters are therefore incremented by loop extents
+// (`+= n`) at loop boundaries rather than by ++ inside the loop, which also
+// keeps them correct without atomics when the flux loop goes parallel.
+//
+// `n_fv_alg_*` are incremented inside solveAlgebraicNode, which runs in
+// parallel over nodes above kOmpMinNodes since Phase 3d: exact at THREADS 1,
+// an estimate above (plain increments, like the closure counters in the
+// parallel flux loop) — the report says so.
+// ---------------------------------------------------------------------------
+
+inline double sec_fv_census      = 0.0;  // censusDt (Courant min-reduction)
+inline double sec_fv_flux        = 0.0;  // computeFluxes (active-face sweep)
+inline double sec_fv_nodesolve   = 0.0;  // relaxNodeFluxes + solveAlgebraicNode
+inline double sec_fv_positivity  = 0.0;  // limitPositivity
+inline double sec_fv_cellupdate  = 0.0;  // updateCells (incl. depth inversion)
+inline double sec_fv_nodeupdate  = 0.0;  // updateNodes
+inline double sec_fv_refreshdep  = 0.0;  // refreshDepths (full-mesh inversion)
+inline double sec_fv_savestate   = 0.0;  // saveState (11-vector snapshot)
+inline double sec_fv_restore     = 0.0;  // restoreState (snapshot + refreshDepths)
+inline double sec_fv_structref   = 0.0;  // refreshStructFlows (solver side)
+inline double sec_fv_bndcallback = 0.0;  // Router::refreshFvBoundaryFlows (engine side)
+inline double sec_fv_rebuild     = 0.0;  // rebuildActiveLists (halo growth)
+inline double sec_fv_reconstruct = 0.0;  // reconstructState (MUSCL slopes)
+inline double sec_fv_ltsfire     = 0.0;  // fireFaces (LTS face pass)
+inline double sec_fv_settle      = 0.0;  // settleAccumulators
+inline double sec_fv_tier        = 0.0;  // assignTiers
+
+inline long n_fv_substep     = 0;  // accepted substeps
+inline long n_fv_census      = 0;  // censusDt calls
+inline long n_fv_census_face = 0;  // faces visited by all censuses
+inline long n_fv_invert      = 0;  // depthOfArea calls (by loop extent)
+inline long n_fv_savestate   = 0;  // saveState calls
+inline long n_fv_restore     = 0;  // ROLLBACKS — the rate saveState pays for
+inline long n_fv_structref   = 0;  // substep structure refreshes
+inline long n_fv_alg_visit   = 0;  // solveAlgebraicNode calls that got past the
+                                   // fixed-head early-out
+inline long n_fv_alg_passthru= 0;  // ...of which took the degree-2 shortcut.
+                                   // passthru/visit is the fraction Phase 3c
+                                   // is trying to raise
+inline long n_fv_alg_solve   = 0;  // ...of which ran the root solve
+inline long n_fv_alg_resid   = 0;  // residual(h) evaluations inside them
+inline long n_fv_alg_flux    = 0;  // computeFaceFlux calls made from residuals
+
+// Closure-call counts at the solver's call sites (FV1D closure-kernel program,
+// Phase 0). share = count × per-op ns from bench_fv_closure, which is how the
+// closure's slice of the step is sized without a sampling profiler. These are
+// plain increments from inside parallel regions: EXACT at one thread, an
+// estimate above — read them from THREADS 1 rows only.
+inline long n_fv_geom_area   = 0;  // areaOfDepth
+inline long n_fv_geom_width  = 0;  // widthOfDepth
+inline long n_fv_geom_i1     = 0;  // i1OfDepth
+inline long n_fv_geom_hydrad = 0;  // hydRadOfDepth (friction)
+
+// LTS macro cycles that actually ran vs were rejected by the post-cycle
+// census. The tier histogram is filled by assignTiers whether or not a cycle
+// ever fires, so without these two the report cannot tell "tiering did not
+// help" from "tiering never engaged" (baseline verification 2026-08-20 §2.3).
+inline long n_fv_macro_cycles   = 0;
+inline long n_fv_macro_rejected = 0;
+
+/** @brief Zeroes the FV phase accumulators. Called from Router::initFv. */
+inline void reset_fv() noexcept {
+    sec_fv_census = sec_fv_flux = sec_fv_nodesolve = sec_fv_positivity = 0.0;
+    sec_fv_cellupdate = sec_fv_nodeupdate = sec_fv_refreshdep = 0.0;
+    sec_fv_savestate = sec_fv_restore = 0.0;
+    sec_fv_structref = sec_fv_bndcallback = 0.0;
+    sec_fv_rebuild = sec_fv_reconstruct = sec_fv_ltsfire = 0.0;
+    sec_fv_settle = sec_fv_tier = 0.0;
+    n_fv_substep = n_fv_census = n_fv_census_face = n_fv_invert = 0;
+    n_fv_savestate = n_fv_restore = n_fv_structref = 0;
+    n_fv_alg_visit = n_fv_alg_passthru = 0;
+    n_fv_alg_solve = n_fv_alg_resid = n_fv_alg_flux = 0;
+    n_fv_geom_area = n_fv_geom_width = n_fv_geom_i1 = n_fv_geom_hydrad = 0;
+    n_fv_macro_cycles = n_fv_macro_rejected = 0;
+}
+
+/**
+ * @brief One machine-scrapeable line for the FV phase split.
+ * @details Same `[PERF-FV] key=value` contract as dump_load(); emitted from
+ *          close() when OPENSWMM_PERF is set and the FV solver actually ran.
+ *          Each phase is SELF time: a phase that calls another timed phase is
+ *          charged only for its own work (see `nested_wall`), so the phases
+ *          partition the time rather than overlapping it. `total` is their sum,
+ *          NOT the router step — the difference between the two is unattributed
+ *          time and is itself the useful signal when a phase is missing. It
+ *          cannot be negative; if it ever is, a timer is nested inside a scope
+ *          that does not go through GatedTimer.
+ */
+inline void dump_fv() noexcept {
+    const double total = sec_fv_census + sec_fv_flux + sec_fv_nodesolve
+                       + sec_fv_positivity + sec_fv_cellupdate + sec_fv_nodeupdate
+                       + sec_fv_refreshdep + sec_fv_savestate + sec_fv_restore
+                       + sec_fv_structref + sec_fv_bndcallback + sec_fv_rebuild
+                       + sec_fv_reconstruct + sec_fv_ltsfire + sec_fv_settle
+                       + sec_fv_tier;
+    std::fprintf(stderr,
+        "[PERF-FV] step=%.4f total=%.4f "
+        "census=%.4f flux=%.4f nodesolve=%.4f positivity=%.4f "
+        "cellupdate=%.4f nodeupdate=%.4f refreshdepths=%.4f "
+        "savestate=%.4f restore=%.4f structrefresh=%.4f bndcallback=%.4f "
+        "rebuild=%.4f reconstruct=%.4f ltsfire=%.4f settle=%.4f tier=%.4f "
+        "n.substep=%ld n.census=%ld n.censusface=%ld n.invert=%ld "
+        "n.savestate=%ld n.rollback=%ld n.structrefresh=%ld "
+        "n.algvisit=%ld n.algpassthru=%ld n.algsolve=%ld "
+        "n.algresidual=%ld n.algfaceflux=%ld "
+        "n.area=%ld n.width=%ld n.i1=%ld n.hydrad=%ld "
+        "n.macro=%ld n.macrorej=%ld "
+        "passthru_frac=%.4f rollback_frac=%.4f "
+        "algresid_per_solve=%.2f algflux_per_solve=%.2f\n",
+        sec_1d_step, total,
+        sec_fv_census, sec_fv_flux, sec_fv_nodesolve, sec_fv_positivity,
+        sec_fv_cellupdate, sec_fv_nodeupdate, sec_fv_refreshdep,
+        sec_fv_savestate, sec_fv_restore, sec_fv_structref, sec_fv_bndcallback,
+        sec_fv_rebuild, sec_fv_reconstruct, sec_fv_ltsfire, sec_fv_settle,
+        sec_fv_tier,
+        n_fv_substep, n_fv_census, n_fv_census_face, n_fv_invert,
+        n_fv_savestate, n_fv_restore, n_fv_structref,
+        n_fv_alg_visit, n_fv_alg_passthru, n_fv_alg_solve,
+        n_fv_alg_resid, n_fv_alg_flux,
+        n_fv_geom_area, n_fv_geom_width, n_fv_geom_i1, n_fv_geom_hydrad,
+        n_fv_macro_cycles, n_fv_macro_rejected,
+        (n_fv_alg_visit > 0)
+            ? static_cast(n_fv_alg_passthru) / static_cast(n_fv_alg_visit) : 0.0,
+        (n_fv_savestate > 0)
+            ? static_cast(n_fv_restore) / static_cast(n_fv_savestate) : 0.0,
+        (n_fv_alg_solve > 0)
+            ? static_cast(n_fv_alg_resid) / static_cast(n_fv_alg_solve) : 0.0,
+        (n_fv_alg_solve > 0)
+            ? static_cast(n_fv_alg_flux) / static_cast(n_fv_alg_solve) : 0.0);
+}
+
+/** @brief Manual timing pair, for phases that do not fit a lexical scope. */
+inline std::chrono::steady_clock::time_point now() noexcept {
+    return std::chrono::steady_clock::now();
+}
+inline double since(std::chrono::steady_clock::time_point t0) noexcept {
+    return std::chrono::duration(now() - t0).count();
+}
+
+/** @brief True when OPENSWMM_PERF is set. Cached — getenv is not free. */
+inline bool enabled() noexcept {
+    static const bool on = (std::getenv("OPENSWMM_PERF") != nullptr);
+    return on;
+}
+
+/** @brief Zeroes the load-phase accumulators. Called from open(). */
+inline void reset_load() noexcept {
+    sec_open_prescan2d = sec_open_read = sec_open_resolve = sec_open_validate = 0.0;
+    sec_read_dispatch = 0.0;
+    sec_res_extfiles = sec_res_tables = sec_res_transects = 0.0;
+    sec_res_xsect = sec_res_shrink = 0.0;
+    sec_init_state = sec_init_hydraulics = sec_init_hydrology = 0.0;
+    sec_init_quality = sec_init_geometry = 0.0;
+    sec_start_iface = sec_start_plugins = 0.0;
+}
+
+/**
+ * @brief One machine-scrapeable line per phase on stderr.
+ * @details Emitted from close() so all three benchmark cuts (open only,
+ *          open+initialize, full) report. Format is `[PERF-LOAD] key=value`
+ *          pairs in seconds; tests/benchmarks/scripts/ parses it.
+ */
+inline void dump_load() noexcept {
+    const double open_total = sec_open_prescan2d + sec_open_read
+                            + sec_open_resolve + sec_open_validate;
+    const double init_total = sec_init_state + sec_init_hydraulics
+                            + sec_init_hydrology + sec_init_quality
+                            + sec_init_geometry;
+    const double start_total = sec_start_iface + sec_start_plugins;
+    std::fprintf(stderr,
+        "[PERF-LOAD] open=%.4f open.prescan2d=%.4f open.read=%.4f "
+        "read.scan=%.4f read.dispatch=%.4f "
+        "open.resolve=%.4f open.validate=%.4f "
+        "res.extfiles=%.4f res.tables=%.4f res.transects=%.4f res.xsect=%.4f "
+        "res.shrink=%.4f "
+        "init=%.4f init.state=%.4f init.hydraulics=%.4f init.hydrology=%.4f "
+        "init.quality=%.4f init.geometry=%.4f "
+        "start=%.4f start.iface=%.4f start.plugins=%.4f\n",
+        open_total, sec_open_prescan2d, sec_open_read,
+        sec_open_read - sec_read_dispatch, sec_read_dispatch,
+        sec_open_resolve, sec_open_validate,
+        sec_res_extfiles, sec_res_tables, sec_res_transects, sec_res_xsect,
+        sec_res_shrink,
+        init_total, sec_init_state, sec_init_hydraulics, sec_init_hydrology,
+        sec_init_quality, sec_init_geometry,
+        start_total, sec_start_iface, sec_start_plugins);
+}
+
 // Adds the elapsed wall time between construction and destruction to `acc`.
 struct ScopedTimer {
     double* acc;
@@ -30,4 +261,68 @@ struct ScopedTimer {
     ScopedTimer& operator=(const ScopedTimer&) = delete;
 };
 
+/**
+ * @brief ScopedTimer that reads the clock only when OPENSWMM_PERF is set.
+ *
+ * @details ScopedTimer is used at per-routing-step and per-load-phase call
+ *          sites, where two unconditional clock reads are free. The FV phase
+ *          timers are not in that regime: a 30 h / 5 s run is ~21,600 routing
+ *          steps, each of which can carry hundreds of substeps, each carrying a
+ *          dozen phases. At ~20 ns a read that is seconds of pure instrument on
+ *          a run that has nothing to do with profiling. `enabled()` is a cached
+ *          static bool, so the gated form costs a predicted branch instead.
+ *
+ */
+/// Wall time booked by GatedTimers that opened and closed inside the one
+/// currently running on this thread. Read and reset by each timer so that what
+/// lands in the accumulator is SELF time.
+///
+/// Without this the phase split double-counts wherever one timed phase calls
+/// another, which it does in three places today: `restoreState` and
+/// `settleAccumulators` both call `refreshDepths`, and `runMacroCycle`'s
+/// boundary callback sits inside the settle window. The visible symptom was
+/// `total` exceeding the routing step it is a breakdown of — the LTS rows of
+/// the phase table reported between -7.9 % and -18.1 % "unattributed" time,
+/// which is not a quantity that can be negative. A breakdown whose parts can
+/// exceed the whole cannot rank optimization targets, which is the only reason
+/// these timers exist.
+///
+/// Thread-local because the accumulators are serial-path today but the flux
+/// sweep is slated to go parallel; a shared counter would then attribute one
+/// thread's children to another thread's parent. Nothing here is atomic and
+/// nothing needs to be: a timer only ever touches its own thread's tally.
+inline thread_local double nested_wall = 0.0;
+
+struct GatedTimer {
+    double* acc = nullptr;
+    double  outer = 0.0;   ///< enclosing timer's tally, restored on close
+    std::chrono::steady_clock::time_point t0;
+    explicit GatedTimer(double& a) noexcept {
+        if (enabled()) {
+            acc = &a;
+            outer = nested_wall;   // stash whatever our parent has collected
+            nested_wall = 0.0;     // ...and start a fresh tally for our own
+            t0 = std::chrono::steady_clock::now();
+        }
+    }
+    ~GatedTimer() noexcept {
+        if (!acc) return;
+        const double wall = std::chrono::duration(
+                                std::chrono::steady_clock::now() - t0).count();
+        // Ours is what the clock says minus what our children already claimed.
+        *acc += wall - nested_wall;
+        // Our FULL wall time is our parent's child time — the parent must not
+        // be charged for us twice, once through its own clock and once here.
+        nested_wall = outer + wall;
+    }
+    GatedTimer(const GatedTimer&) = delete;
+    GatedTimer& operator=(const GatedTimer&) = delete;
+};
+
+/// Adds @p n to a counter only when profiling is on, so the counters cost the
+/// same predicted branch as the timers and never appear in a release profile.
+inline void count(long& c, long n = 1) noexcept {
+    if (enabled()) c += n;
+}
+
 } // namespace openswmm::perf
diff --git a/src/engine/core/SWMMEngine.cpp b/src/engine/core/SWMMEngine.cpp
index 18fcdf9bc..b81be6811 100644
--- a/src/engine/core/SWMMEngine.cpp
+++ b/src/engine/core/SWMMEngine.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SWMMEngine.cpp
  * @brief Implementation of the SWMMEngine lifecycle manager.
@@ -7,14 +23,16 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "SWMMEngine.hpp"
 #include "DateTime.hpp"
+#include "FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "SimulationContext.hpp"
 #include "PerfTimers.hpp"
 #include "UnitConversion.hpp"
+#include "../quality/MsxSurfaceQuality.hpp"   // BW-MSX: species buildup / washoff
 #include "../hydrology/Gage.hpp"
 #include "../hydraulics/Link.hpp"
 #include "../hydraulics/XSectBatch.hpp"
@@ -27,7 +45,23 @@
 #include 
 #include "../hydraulics/TimestepController.hpp"
 #include "../input/PostParseResolver.hpp"
+#ifdef OPENSWMM_HAS_2D
+#include "../2d/gw/GwTransportSections.hpp"   // U4
+#include "../2d/subsurface/SubsurfaceSections.hpp"   // G1
+#endif
+#include "../transport/components/HeatFluxModules/HeatOverrides.hpp"  // PE2
+#include "../transport/components/HeatFluxModules/SurfaceExchange.hpp" // dew point -> RH
 #include "../plugins/DefaultInputPlugin.hpp"
+#include "../plugins/ProcessComponentRegistry.hpp"
+#include "../transport/components/EulerianArdComponent/ArdConfig.hpp"
+#include "../transport/components/ReactionModule/ReactionLegacyBinding.hpp"
+#include "../transport/components/ReactionModule/ReactionsComponent.hpp"
+#include "../transport/components/HeatModule/HeatComponent.hpp"
+#include "../transport/components/WaterAgeModule/WaterAgeComponent.hpp"
+#include "../transport/components/HeatModule/HeatLid.hpp"
+#include "../transport/components/HeatModule/HeatWatershed.hpp"
+#include "../transport/components/WaterAgeModule/WaterAgeWatershed.hpp"
+#include "../transport/components/WaterAgeModule/WaterAgeLid.hpp"
 #include "../plugins/DefaultStateIOPlugin.hpp"
 #include "HotStartManager.hpp"
 #include "../../../include/openswmm/plugin_sdk/IPluginComponentInfo.hpp"
@@ -37,14 +71,17 @@
 #ifdef OPENSWMM_HAS_2D
 #include "../2d/input/SectionHandlers2D.hpp"
 #include "../2d/output/Default2DOutputPlugin.hpp"
-#include 
 #endif
+#include   // 2D mesh file + [PROCESS_COMPONENTS] path resolution
 
 #include 
+#include 
 #include 
 #include 
 #include 
+#include        // call_once: process-global one-time init, see open()
 #include "ErrorCodes.hpp"
+#include "ThreadInfo.hpp"
 
 // libomp's KMP_BLOCKTIME override — declared here at file scope because
 // OpenMP support — graceful degradation when not available
@@ -99,6 +136,17 @@ void SWMMEngine::wire2DModelIO() noexcept {
     ctx_.twod_io.boundary   = &surface_router_.boundary();
     ctx_.twod_io.pending_bc = &surface_router_.pendingBCRows();
     ctx_.twod_io.pending_ec = &surface_router_.pendingEdgeConveyanceRows();
+    ctx_.twod_io.pending_iq = &surface_router_.pendingInitialQualityRows();
+    ctx_.twod_io.pending_bq = &surface_router_.pendingBoundaryQualityRows();
+    ctx_.twod_io.infil      = &surface_router_.infil();
+    ctx_.twod_io.gw         = &surface_router_.gwTransport();   // U4
+    ctx_.twod_io.surface_quality = &surface_router_.surfaceQuality();   // S7
+    ctx_.twod_io.aquifer       = &surface_router_.aquiferConfig();     // G1
+    ctx_.twod_io.aquifer_nodes = &surface_router_.aquiferNodeNames();  // G1
+    ctx_.twod_io.aquifer_links = &surface_router_.aquiferLinkNames();  // G-X4
+    ctx_.twod_io.aquifer_state = &surface_router_.subsurface().state();  // G1
+    ctx_.twod_io.aquifer_transport =
+        &surface_router_.subsurface().transport();                       // T7.5
 }
 #endif
 
@@ -127,6 +175,19 @@ int SWMMEngine::open(const char* inp_path,
     // Reset context for a fresh run
     ctx_.reset();
 
+    // Zero the load-phase accumulators so a process that opens several models
+    // reports each one separately (see core/PerfTimers.hpp).
+    perf::reset_load();
+    perf::reset_fv();
+
+    // Stamp the report wall clock before any parsing work. Legacy takes this
+    // timestamp in report_writeLogo(), which swmm_open() calls before
+    // project_readInput(), so its "Total elapsed time" covers parse +
+    // validate + init. Stamping here keeps the reported elapsed time
+    // comparable with legacy/PCSWMM instead of excluding the (potentially
+    // very long, on large models) initialization window.
+    std::time(&ctx_.wall_start);
+
     rpt_path_ = rpt_path ? rpt_path : "";
     out_path_ = out_path ? out_path : "";
 
@@ -164,7 +225,25 @@ int SWMMEngine::open(const char* inp_path,
                                  surface_router_.options(),
                                  surface_router_.pendingBCRows(),
                                  surface_router_.pendingEdgeConveyanceRows(),
+                                 surface_router_.pendingInitialQualityRows(),
+                                 surface_router_.pendingBoundaryQualityRows(),
                                  dip->registry());
+        // U4 (2026-09-07): the [GW_*] subsurface-transport authoring
+        // sections. Parsed, validated and round-tripped; inert at run until
+        // the integrated groundwater kernel lands (one warning, below).
+        twoD::registerGwTransportSections(surface_router_.gwTransport(),
+                                          dip->registry());
+        // S7 (2026-09-19): [2D_COVERAGES] / [2D_LOADINGS] / [2D_CURB_LENGTH]
+        // — cell buildup / washoff / sweeping by the land-use convention.
+        twoD::registerSurfaceQualitySections(surface_router_.surfaceQuality(),
+                                             dip->registry());
+        // G1: the [2D_AQUIFER*] sections — the two-zone groundwater kernel's
+        // own parameters. Unlike the [GW_*] transport rows above, these are
+        // NOT inert: a resolved row runs the kernel.
+        twoD::registerSubsurfaceSections(surface_router_.aquiferConfig(),
+                                         surface_router_.aquiferNodeNames(),
+                                         surface_router_.aquiferLinkNames(),   // G-X4
+                                         dip->registry());
     }
 
     // Scan the inline .inp for `;; UNITS: SI (m)` so SurfaceRouter2D::initialize
@@ -172,12 +251,16 @@ int SWMMEngine::open(const char* inp_path,
     // the mesh is already SI. The external-mesh path runs its own prescan
     // below and overrides this if both files carry the header.
     if (inp_path && inp_path[0] != '\0') {
+        perf::ScopedTimer _pt(perf::sec_open_prescan2d);
         twoD::prescan2DUnitsHeader(inp_path, surface_router_.options());
     }
 #endif
 
-    if (input_plugin->read(inp_path ? inp_path : "", ctx_) != 0) {
-        return ctx_.error_code != 0 ? ctx_.error_code : SWMM_ERR_PARSE;
+    {
+        perf::ScopedTimer _pt(perf::sec_open_read);
+        if (input_plugin->read(inp_path ? inp_path : "", ctx_) != 0) {
+            return ctx_.error_code != 0 ? ctx_.error_code : SWMM_ERR_PARSE;
+        }
     }
 
 #ifdef OPENSWMM_HAS_2D
@@ -187,12 +270,16 @@ int SWMMEngine::open(const char* inp_path,
         if (!mf.empty()) {
             std::string base_dir;
             if (inp_path && inp_path[0] != '\0')
-                base_dir = std::filesystem::path(inp_path).parent_path().string();
+                base_dir = openswmm::io::path_utf8(
+                    openswmm::io::utf8_path(inp_path).parent_path());
             std::string err = twoD::load2DMeshExternalFile(
                 surface_router_.mesh(), surface_router_.options(),
                 surface_router_.pendingBCRows(),
                 surface_router_.pendingEdgeConveyanceRows(),
-                mf, base_dir, &ctx_.warnings);
+                &surface_router_.infil(),
+                mf, base_dir, &ctx_.warnings,
+                &surface_router_.pendingInitialQualityRows(),
+                &surface_router_.pendingBoundaryQualityRows());
             if (!err.empty()) {
                 if (lenient_open_) {
                     // A missing/unreadable external mesh must not make the
@@ -213,8 +300,244 @@ int SWMMEngine::open(const char* inp_path,
             }
         }
     }
+    // E2: [2D_OPTIONS] INFIL_STEP is an alias of [2D_INFILTRATION_OPTIONS]
+    // INFIL_STEP. Infil2D::options().infil_step is the single source of
+    // truth (the C API and the writer read it); fold the alias in now that
+    // both the .inp and any sidecar have been read. The alias wins when both
+    // were spelled.
+    {
+        auto& o2d = surface_router_.options();
+        if (o2d.infil_step > 0.0) {
+            surface_router_.infil().options().infil_step = o2d.infil_step;
+            o2d.infil_step = 0.0;
+        }
+        // U5: [2D_OPTIONS] GW_ET is the same kind of alias, for
+        // [2D_AQUIFER_OPTIONS] GW_ET. GwOptions::gw_et is the single source of
+        // truth (the kernel reads it, the writer emits it); fold the alias in
+        // and clear it so the setting is never stored in two places. The alias
+        // wins when both were spelled, and it counts as authoring the section
+        // so a deck that only says GW_ET still reaches the kernel.
+        if (!o2d.gw_et.empty()) {
+            auto& gw = surface_router_.aquiferConfig();
+            gw.options.gw_et    = o2d.gw_et;
+            gw.options.authored = true;
+            o2d.gw_et.clear();
+        }
+    }
 #endif
 
+    // Species registry (master plan §4.1, phase T0a): pollutants occupy the
+    // first slots, index-aligned with the legacy pollutant index. MSX
+    // species (reactions component, below) and reserved species (age A1,
+    // temperature H1) append after. Rebuilt on every open.
+    ctx_.species_registry.clear();
+    for (int p = 0; p < ctx_.n_pollutants(); ++p)
+        ctx_.species_registry.add(ctx_.pollutant_names.name_of(p),
+                                  SpeciesKind::POLLUTANT, std::string{});
+
+    // Resolve [PROCESS_COMPONENTS] registrations (Unified Transport suite
+    // D-UT8, phase IO1): look up each id, read its external config file
+    // (relative to the .inp, [2D_MESH_FILE] path rules), and deliver the
+    // parsed sections to the component's apply hook. Mirrors the external
+    // 2D mesh handling directly above: fatal on strict open, recorded and
+    // survivable on lenient (editor) open. Implemented components register
+    // first (idempotent — overwrites the planned-id placeholder).
+    //
+    // ONCE per process, not once per open(). ProcessComponentRegistry is a
+    // singleton whose header states it is not thread-safe for registration
+    // ("register at startup only"), and register_component() move-assigns a
+    // heap-allocated std::string description over the existing map node. Two
+    // engines opening on different threads therefore both freed the same
+    // string buffer — the `malloc(): unaligned tcache chunk detected` abort in
+    // ConcurrentEngines.TwoInstancesDeterministic. Registration is idempotent
+    // (same four ids, same data every time), so hoisting it to a one-time init
+    // is behaviour-preserving for a single engine and removes the race.
+    static std::once_flag process_components_registered;
+    std::call_once(process_components_registered, [] {
+        transport::registerReactionsComponent();
+        transport::registerArdComponent();
+        transport::registerWaterAgeComponent();
+        transport::registerHeatComponent();
+    });
+    {
+        std::string base_dir;
+        if (inp_path && inp_path[0] != '\0')
+            base_dir = openswmm::io::path_utf8(
+                openswmm::io::utf8_path(inp_path).parent_path());
+
+        std::vector errs;
+        if (!ctx_.process_component_specs.empty())
+            errs = components::resolve_process_components(ctx_, base_dir);
+
+        // Embedded [REACTION_*] fallback (D-UT8): honored with a style
+        // warning when no external reactions component is registered; the
+        // external file wins wholesale otherwise.
+        bool reactions_registered = false;
+        for (const auto& spec : ctx_.process_component_specs)
+            if (spec.id == "org.hydrocouple.openswmm.reactions")
+                reactions_registered = true;
+        transport::applyEmbeddedReactionSections(ctx_, reactions_registered,
+                                                 errs);
+
+        // E5a: [TRANSPORT_BOUNDARIES]/[TRANSPORT_SOURCES] rows reference MSX
+        // species by NAME, and the reactions component may apply before OR
+        // after transport.ard in file order — so the rows are stored raw at
+        // apply and resolved HERE, after every component (and the embedded
+        // fallback) has run. Resolution failures are fatal like any other
+        // component config error.
+        transport::resolveArdTransportRows(ctx_, errs);
+
+        // PE2: per-element heat attributes resolve here for the SAME reason
+        // — the rows name links, nodes and tags, and every component plus
+        // the full .inp parse must be complete before a name can be
+        // resolved or reported as unknown (D-RQ1 timing, D-PE5 fatality).
+        {
+            auto pe = transport::heat::resolveHeatOverrides(ctx_);
+            for (auto& e : pe) errs.push_back(std::move(e));
+        }
+
+        if (!errs.empty()) {
+            for (const auto& e : errs) ctx_.errors.push_back(e);
+            if (!lenient_open_) {
+                ctx_.error_code    = SWMM_ERR_PARSE;
+                ctx_.error_message = errs.front();
+                write_open_failure_report();
+                return SWMM_ERR_PARSE;
+            }
+        }
+
+        // A configured reactions component that no engine will run is a
+        // silent no-result run unless we say so (R4).
+        transport::warnIfLegacyBindingBypassed(ctx_);
+        // The mirror case for E3: dispersion spelled the FV way while the
+        // ARD engine reads it from model.ard.
+        transport::warnIfFvDispersionKeyIgnored(ctx_);
+
+        // X2: pollutant transport under LARD is live. X4: water age is
+        // live too (segment age row + node stores). What still does not
+        // run under this dispatch: temperature (H7), the reactions
+        // component (deferred L3) and treatment expressions. Each
+        // remaining bypass warns by name at open (silent no-result runs
+        // are never allowed — the E1-era rule; enumerate silent-bypass
+        // configurations, R4 lesson 5). All stay inside stepRouting's
+        // !ignore_quality condition: under IGNORE_QUALITY the stage is
+        // skipped before the solver choice is consulted, and that
+        // configuration's own warning family covers it.
+        // P2.3 (2026-09-01): treatment interop under LARD landed — the
+        // legacy evaluator runs on the published node concentrations after
+        // lard_.step, which ARE the LARD node stores (nodes.conc), so no
+        // absorb step exists the way ARD needs one. The LAST LARD bypass
+        // warning is GONE, not narrowed; this engine now runs every
+        // configured quality feature or refuses at parse.
+        // H6b bed bindings (2026-09-01): ALL THREE engines now carry the
+        // bed — LEGACY on links, ARD per cell (1:1 slices, the reference's
+        // own element mapping), LARD per link against the segment mean with
+        // uniform increments. The "binds to LEGACY only" warning that stood
+        // here is gone WITH its condition, not narrowed.
+
+        // H6b: the ground temperature is usually the LARGEST term acting on
+        // a buried pipe, and it has a default. An unstated one is therefore
+        // warned, not refused — the `SolarConfig::has_timezone` precedent,
+        // not the `has_latitude` one.
+        if (ctx_.heat_config.sediment_exchange &&
+            !ctx_.heat_config.sediment.has_ground_temp) {
+            ctx_.warnings.push_back(
+                "[SEDIMENT_EXCHANGE] GROUND_TEMPERATURE is not set; the "
+                "default 12 degC is in force. For a buried conduit this term "
+                "is often the largest one in the energy balance, so the "
+                "default is unlikely to be what you meant.");
+        }
+
+        // X3a: the LARD stepping keys are consumed by no other engine —
+        // the inverse bypass direction (E3 lesson 10: config spelled for
+        // one engine while another runs).
+        if (ctx_.options.quality_solver != QualitySolverKind::LAGRANGIAN &&
+            !ctx_.options.ignore_quality) {
+            if (ctx_.options.quality_step > 0.0)
+                ctx_.warnings.push_back(
+                    "[OPTIONS] QUALITY_STEP is set but QUALITY_SOLVER is "
+                    "not LAGRANGIAN — only the LARD engine substeps on "
+                    "this key; it has no effect this simulation.");
+            if (ctx_.options.max_segments_per_link != 100)
+                ctx_.warnings.push_back(
+                    "[OPTIONS] MAX_SEGMENTS_PER_LINK is set but "
+                    "QUALITY_SOLVER is not LAGRANGIAN — only the LARD "
+                    "engine holds segments; it has no effect this "
+                    "simulation.");
+            if (ctx_.options.lard_rwpt)
+                ctx_.warnings.push_back(
+                    "[OPTIONS] DISPERSION RWPT is set but QUALITY_SOLVER "
+                    "is not LAGRANGIAN — RWPT is the LARD engine's "
+                    "dispersion; the ARD engine reads dispersion from the "
+                    "transport.ard component instead. No dispersion is "
+                    "applied from this key this simulation.");
+        }
+        // D-NS1 (X6): a configured negative quality inflow is EXTRACTION —
+        // legal, warned per row at open (subplan §3.1 rule 2). Runtime
+        // clamps + the end-of-run summary are the other two warnings of
+        // the contract. Only the configured BASELINE is scanned here; a
+        // timeseries that goes negative at runtime is caught by the clamp
+        // warning instead.
+        for (int i = 0; i < ctx_.ext_inflows.count(); ++i) {
+            const auto ui = static_cast(i);
+            if (ctx_.ext_inflows.inflow_type[ui] == "FLOW") continue;
+            if (ctx_.ext_inflows.baseline[ui] >= 0.0) continue;
+            ctx_.warnings.push_back(
+                "[INFLOWS] node '" + ctx_.ext_inflows.node_name[ui] +
+                "' pollutant '" + ctx_.ext_inflows.constituent[ui] +
+                "': the baseline is negative — this row EXTRACTS mass "
+                "(D-NS1). Extraction clamps per step to the mass the "
+                "element holds.");
+        }
+
+        // A1a/A1b: the reserved species registers so downstream consumers
+        // see the registry truth. Age now tracks under BOTH engines (ARD
+        // mesh row / LEGACY CSTR mirror) — the A1b bypass warning is
+        // retired; IGNORE_QUALITY remains the only bypass and warns via
+        // the waterage component.
+        // A2b: the REPORTED species list — pollutants, then the age
+        // pseudo-column. Built once here so the snapshot's pollut_names
+        // pointer stays valid for the whole run.
+        ctx_.reported_species_names.clear();
+        for (int p = 0; p < ctx_.n_pollutants(); ++p)
+            ctx_.reported_species_names.push_back(
+                ctx_.pollutant_names.name_of(p));
+
+        if (ctx_.options.water_age) {
+            ctx_.species_registry.add("__WATER_AGE__",
+                                      SpeciesKind::RESERVED_AGE, "hours");
+            ctx_.reported_species_names.push_back("__WATER_AGE__");
+            if (ctx_.options.ignore_quality)
+                ctx_.warnings.push_back(
+                    "[OPTIONS] WATER_AGE ON but IGNORE_QUALITY is YES — the "
+                    "quality stage does not run, so no age is tracked this "
+                    "simulation.");
+        }
+
+        // H1: temperature is the LAST reported column — after age — so a
+        // deck that adds heat to an existing water-age model does not move
+        // the age column a consumer already keys on by index. The NAME is
+        // the contract either way (lesson 40), which is what
+        // swmm_output_get_pollut_id exists to expose.
+        if (ctx_.options.heat_transport) {
+            ctx_.species_registry.add("__TEMPERATURE__",
+                                      SpeciesKind::RESERVED_TEMPERATURE,
+                                      "degC");
+            ctx_.reported_species_names.push_back("__TEMPERATURE__");
+            if (ctx_.options.ignore_quality)
+                ctx_.warnings.push_back(
+                    "[OPTIONS] HEAT_TRANSPORT ON but IGNORE_QUALITY is YES — "
+                    "the quality stage does not run, so no temperature is "
+                    "tracked this simulation.");
+            // H4 retired H1's "ARD tracks no temperature" warning: the
+            // reserved row now rides the mesh under EULERIAN_ARD, with
+            // advection, dispersion, node mixing and per-cell surface
+            // fluxes. Retiring a deferral means flipping its gate in the
+            // same changeset (lesson 21) — see
+            // test_heat_transport.cpp's ARD gate, now inverted.
+        }
+    }
+
     // Warn about unknown/skipped sections. Route through push_report_warning so
     // the warning reaches the .rpt (legacy report_writeWarningMsg), not just the
     // API callback. Wording matches legacy input.c ("Unknown section '[X]' ...");
@@ -226,12 +549,58 @@ int SWMMEngine::open(const char* inp_path,
     }
 
     // Resolve cross-references (forward refs, final array sizing, head init)
-    input::resolve_cross_references(ctx_);
+    {
+        perf::ScopedTimer _pt(perf::sec_open_resolve);
+        input::resolve_cross_references(ctx_);
+    }
+    // BW-MSX: bind the [BUILDUP]/[WASHOFF]/[LOADINGS] rows that name a
+    // reactions-component species — the component is applied above, the
+    // name tables are final here. Unresolvable names warn, never fail.
+    for (auto& w : msxsurf::resolve(ctx_)) ctx_.warnings.push_back(std::move(w));
+
+#ifdef OPENSWMM_HAS_2D
+    // U4: validate the [GW_*] authoring rows now that the mesh, the species
+    // registry and the timeseries are all final — same timing (and same
+    // fatality) as the other cross-reference resolution above. The single
+    // "authored but inert" warning is emitted here so it reaches the report
+    // whether or not the run proceeds.
+    {
+        auto gw_errs = twoD::resolveGwTransport(ctx_, surface_router_.mesh(),
+                                                surface_router_.gwTransport());
+        for (auto& e : gw_errs) ctx_.errors.push_back(std::move(e));
+        // T7.1: the rows are inert only where there is no kernel to
+        // configure. With a resolved [2D_AQUIFER] they now drive the
+        // transported tuple, and the warning would be false. The kernel
+        // resolves in surface_router_.initialize(), which runs AFTER this
+        // point, so the question asked here is the authored one: are there
+        // [2D_AQUIFER] rows for these [GW_*] rows to configure at all.
+        if (surface_router_.aquiferConfig().empty()) {
+            const std::string inert =
+                twoD::gwTransportInertWarning(surface_router_.gwTransport());
+            if (!inert.empty()) push_report_warning(inert, 0);
+        }
+        // U5 (rewired 2026-09-07): GROUNDWATER is a real process enable now
+        // that the G1 two-zone kernel runs it. YES on a deck with no
+        // [2D_AQUIFER*] rows is a deck that expects groundwater and has
+        // none — the same "asked for it, got nothing" case INFILTRATION YES
+        // reports. NO and AUTO are silent: AUTO is the default, and NO is a
+        // deliberate switch-off whose rows are still saved.
+        const auto& o2d = surface_router_.options();
+        if (o2d.groundwater > 0 && surface_router_.aquiferConfig().empty())
+            push_report_warning(
+                "[2D_OPTIONS] GROUNDWATER YES but no [2D_AQUIFER_OPTIONS] / "
+                "[2D_AQUIFER] row was authored — there is no subsurface to "
+                "run this simulation.", 0);
+    }
+#endif
 
     // Project-level sanity checks + step-clamp warnings (legacy project_validate:
     // WARNING 01/06/07). Must run before the fatal gate below so any warnings it
     // records reach the report.
-    validate_project();
+    {
+        perf::ScopedTimer _pt(perf::sec_open_validate);
+        validate_project();
+    }
 
     // Post-parse validation errors accumulated during resolution (e.g.
     // ERR_TRANSECT_MANNING 227 for a zero channel Manning's n) are fatal:
@@ -286,9 +655,13 @@ int SWMMEngine::open(const char* inp_path,
         const std::string& of = surface_router_.options().output_file;
         if (!of.empty()) {
             std::string resolved = of;
-            std::filesystem::path p(of);
+            // utf8_path/path_utf8, not fs::path(std::string)/.string(): the
+            // [2D_OPTIONS] token and inp_path are UTF-8, and the narrow forms
+            // decode/encode in the ANSI code page instead (issue #7).
+            std::filesystem::path p = openswmm::io::utf8_path(of);
             if (p.is_relative() && inp_path && inp_path[0] != '\0') {
-                resolved = (std::filesystem::path(inp_path).parent_path() / p).string();
+                resolved = openswmm::io::path_utf8(
+                    openswmm::io::utf8_path(inp_path).parent_path() / p);
             }
             auto* op = new twoD::Default2DOutputPlugin(resolved);
             op->initialize({}, nullptr);
@@ -376,6 +749,11 @@ int SWMMEngine::initialize() noexcept {
         return SWMM_ERR_WRONG_STATE;
     }
 
+    // Everything from here to init_modules() is the "state seeding" phase —
+    // per-node/per-link loops over ctx_. Closed out just before init_modules(),
+    // which is broken into its own four legs.
+    const auto _pt_state0 = perf::now();
+
     // Apply initial depths/flows from input (all defaults already in NodeData etc.)
     // reset_state() applies init_depth to depth/old_depth/head but volumes need
     // separate computation using node geometry tables.
@@ -433,11 +811,17 @@ int SWMMEngine::initialize() noexcept {
         }
     }
 
-    // Legacy-convention reported full volume (see report_full_volume_ doc): 0 for
-    // plain junctions/outfalls/dividers, pump wet-well xMax set in the loop below.
-    // Used ONLY to map the reported .out NODE_VOLUME to legacy; the internal
-    // volume-state (ctx_.nodes.volume / full_volume) is untouched.
-    report_full_volume_.assign(static_cast(ctx_.n_nodes()), 0.0);
+    // Legacy-convention full volume (NodeData::rpt_full_volume, legacy
+    // Node.fullVolume): 0 for plain junctions/outfalls/dividers, the curve
+    // volume for storage, pump wet-well xMax set in the loop below. The
+    // dynamic wave books node volume in this convention; full_volume keeps
+    // MIN_SURFAREA*fullDepth for the FV mesh's node area.
+    for (int i = 0; i < ctx_.n_nodes(); ++i) {
+        auto ui = static_cast(i);
+        ctx_.nodes.rpt_full_volume[ui] =
+            (ctx_.nodes.type[ui] == NodeType::STORAGE) ? ctx_.nodes.full_volume[ui]
+                                                       : 0.0;
+    }
 
     // Type-1 (volume-controlled) pumps: the inlet junction acts as a wet well
     // whose full volume is the pump curve's maximum volume. Legacy pump_validate
@@ -471,8 +855,8 @@ int SWMMEngine::initialize() noexcept {
             ctx_.nodes.full_volume[un1] =
                 std::max(ctx_.nodes.full_volume[un1], xmax_internal);
             // Legacy reports the pump wet-well's volume from this xMax.
-            report_full_volume_[un1] =
-                std::max(report_full_volume_[un1], xmax_internal);
+            ctx_.nodes.rpt_full_volume[un1] =
+                std::max(ctx_.nodes.rpt_full_volume[un1], xmax_internal);
             // The initial volume/old_volume loop above ran BEFORE this xMax
             // override, so it sized the wet well with the MIN_SURFAREA fallback
             // (full_volume was still 0). Legacy sets fullVolume in pump_validate
@@ -491,6 +875,23 @@ int SWMMEngine::initialize() noexcept {
         }
     }
 
+    // The dynamic wave books non-storage node volume in the legacy
+    // convention (NodeData::rpt_full_volume), so seed its initial volume the
+    // way legacy node_initState does: fullVolume * (initDepth / fullDepth) —
+    // 0 for a plain junction, the wet-well share for a Type-1 pump inlet.
+    if (ctx_.options.routing_model == RoutingModel::DYNWAVE) {
+        for (int i = 0; i < ctx_.n_nodes(); ++i) {
+            auto ui = static_cast(i);
+            if (ctx_.nodes.type[ui] == NodeType::STORAGE) continue;
+            const double fd = ctx_.nodes.full_depth[ui];
+            const double d0 = ctx_.nodes.init_depth[ui];
+            const double v0 = (fd > 0.0 && d0 > 0.0)
+                ? ctx_.nodes.rpt_full_volume[ui] * (d0 / fd) : 0.0;
+            ctx_.nodes.volume[ui]     = v0;
+            ctx_.nodes.old_volume[ui] = v0;
+        }
+    }
+
     // Apply q0 to link flow and compute initial conduit depth (Gap #43)
     // Cache the translated batch cross-section code for every conduit BEFORE
     // the initial-state loops below. buildXSectParams()/getAofY() dispatch on
@@ -507,14 +908,39 @@ int SWMMEngine::initialize() noexcept {
             link::translateShape(ctx_.links.xsect_shape[uj]);
     }
 
+    // Lengthen the conduits and re-derive their conveyance BEFORE the initial
+    // state is built. Legacy does both in conduit_validate (link.c:1107-1140),
+    // i.e. before link_initState solves each q0 conduit's normal depth — and a
+    // lengthened conduit's beta carries the rounding of an algebraic identity,
+    // PHI*sqrt(S/f)/(n/sqrt(f)), that is one ULP away from the unlengthened
+    // PHI*sqrt(S)/n. Running it only in Router::init (inside init_modules,
+    // after these loops) seeded 405-h-h-elements' junction 83 one ULP off and
+    // split the network at its very first routing step. Router::init still
+    // calls it; the routine is idempotent.
+    {
+        RouteModel rm0 = RouteModel::DYNWAVE;
+        if (ctx_.options.routing_model == RoutingModel::KINWAVE) rm0 = RouteModel::KINWAVE;
+        else if (ctx_.options.routing_model == RoutingModel::STEADY) rm0 = RouteModel::STEADY;
+        else if (ctx_.options.routing_model == RoutingModel::FV) rm0 = RouteModel::FV;
+        applyConduitLengthening(ctx_, rm0);
+    }
+
     // Matches legacy link_initState / conduit_initState in link.c:
     //   Link[j].oldFlow = Link[j].newFlow = q0
     //   conduit: newDepth = oldDepth = link_getYnorm(j, q0/barrels)
+    // legacy link_initState (link.c:529) seeds timeLastSet with StartDate —
+    // the start DATE, midnight of the first day, not the start date-time.
+    // v6 left it at 0.0 (the SWMM epoch), so a TIMEOPEN / TIMECLOSED premise
+    // read ~32000 days at the first rule evaluation and fired immediately:
+    // `timeoff`'s RULE PIDFORORIFICE closed conduit 1570E on the first step
+    // instead of an hour in.
+    const double start_date0 = std::floor(ctx_.options.start_date);
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
         double q0 = ctx_.links.q0[uj];
         ctx_.links.flow[uj]     = q0;
         ctx_.links.old_flow[uj] = q0;
+        ctx_.links.time_last_set[uj] = start_date0;
         if (ctx_.links.type[uj] == LinkType::CONDUIT && q0 != 0.0) {
             const int cr = ctx_.link_subtypes.conduit_row(j);
             const auto& CD = ctx_.link_subtypes.conduits;
@@ -522,7 +948,8 @@ int SWMMEngine::initialize() noexcept {
             int barrels = (cr >= 0) ? CD.barrels[static_cast(cr)] : 1;
             double q_per_barrel = std::fabs(q0) / std::max(barrels, 1);
             double beta = (cr >= 0) ? CD.beta[static_cast(cr)] : 0.0;
-            double y = link::getDepthFromFlow(xs, beta, q_per_barrel);
+            double q_max = (cr >= 0) ? CD.q_max[static_cast(cr)] : -1.0;
+            double y = link::getDepthFromFlow(xs, beta, q_per_barrel, q_max);
             ctx_.links.depth[uj]     = y;
             ctx_.links.old_depth[uj] = y;
             // Initial conduit storage volume = area(y) * length * barrels,
@@ -530,7 +957,10 @@ int SWMMEngine::initialize() noexcept {
             // * barrels). Without this the routing mass-balance "Initial Stored
             // Volume" omitted conduits that start with flow (e.g. extran8a
             // q0=20), producing a large false continuity error (-22%).
-            double len = (cr >= 0) ? CD.length[static_cast(cr)] : 0.0;
+            // legacy flowrout.c:507 books a conduit's initial volume over
+            // link_getLength(i) — the ROUTING length (an IRREGULAR section's
+            // flood-plain length, not its authored main-channel length).
+            double len = (cr >= 0) ? CD.true_length[static_cast(cr)] : 0.0;
             double vol = xsect::getAofY(xs, y) * len * barrels;
             ctx_.links.volume[uj]     = vol;
             ctx_.links.old_volume[uj] = vol;
@@ -573,7 +1003,16 @@ int SWMMEngine::initialize() noexcept {
             ctx_.nodes.depth[ui]     = y;
             ctx_.nodes.old_depth[ui] = y;
             ctx_.nodes.head[ui]      = ctx_.nodes.invert_elev[ui] + y;
-            double vol = node::getVolume(ctx_.nodes, i, y, &ctx_.tables, us);
+            // Legacy node_getVolume(i, newDepth): fullVolume * (depth /
+            // fullDepth), 0 for a junction — the dynamic wave books volume
+            // in that convention (rpt_full_volume); FV keeps its own.
+            double vol;
+            if (ctx_.options.routing_model == RoutingModel::DYNWAVE) {
+                const double fd = ctx_.nodes.full_depth[ui];
+                vol = (fd > 0.0) ? ctx_.nodes.rpt_full_volume[ui] * (y / fd) : 0.0;
+            } else {
+                vol = node::getVolume(ctx_.nodes, i, y, &ctx_.tables, us);
+            }
             ctx_.nodes.volume[ui]     = vol;
             ctx_.nodes.old_volume[ui] = vol;
         }
@@ -587,22 +1026,17 @@ int SWMMEngine::initialize() noexcept {
     // created during the first routing step and showing up as a continuity
     // error (e.g. extran2's fixed 94.4 ft outfall backs ~1.57 ac-ft into the
     // downstream trapezoidal channels).
-    // Set FIXED-outfall node depths from their stage (= stage − invert), so the
-    // downstream conduit backwater can be computed below. Done inline rather
-    // than via outfall::setAllOutfallDepths because that routine's
-    // outfall→conduit cache is not populated until init_modules (and it gives
-    // FREE/NORMAL outfalls zero depth at zero initial flow anyway).
-    for (int oi = 0; oi < ctx_.n_nodes(); ++oi) {
-        auto uo = static_cast(oi);
-        if (ctx_.nodes.type[uo] != NodeType::OUTFALL) continue;
-        const int r = ctx_.node_subtypes.outfall_row(oi);
-        if (r >= 0 &&
-            ctx_.node_subtypes.outfalls.bc_type[static_cast(r)] == OutfallType::FIXED) {
-            double stage = ctx_.node_subtypes.outfalls.param[static_cast(r)];  // internal ft
-            ctx_.nodes.depth[uo] =
-                std::max(0.0, stage - ctx_.nodes.invert_elev[uo]);
-        }
-    }
+    // Every outfall type, as legacy link_setOutfallDepth at flowrout_init
+    // does (NewRoutingTime = 0): FIXED at its stage, TIDAL at the curve's
+    // first x, TIMESERIES at the start date, FREE / NORMAL from the q0
+    // flow's normal / critical depth. Only the FIXED ones were seeded, so a
+    // TIDAL outfall's conduit started at FUDGE depth instead of half the
+    // tide's depth, and its aOld carried that into dq3 on the first step
+    // (routing-outfall-tidal, routing-outfall-timeseries). Legacy calls it
+    // per LINK, so only an outfall some link names in that per-link choice
+    // of end gets a depth (buildOutfallLinkMap); the others stay at 0.
+    outfall::buildOutfallLinkMap(ctx_);
+    outfall::setAllOutfallDepths(ctx_, 0.0);
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
         if (ctx_.links.type[uj] != LinkType::CONDUIT) continue;
@@ -623,7 +1057,7 @@ int SWMMEngine::initialize() noexcept {
         const int cr = ctx_.link_subtypes.conduit_row(j);
         const auto& CD = ctx_.link_subtypes.conduits;
         int barrels = std::max((cr >= 0) ? CD.barrels[static_cast(cr)] : 1, 1);
-        double len = (cr >= 0) ? CD.length[static_cast(cr)] : 0.0;
+        double len = (cr >= 0) ? CD.true_length[static_cast(cr)] : 0.0;
         double vol = xsect::getAofY(xs, y) * len * barrels;
         ctx_.links.volume[uj]     = vol;
         ctx_.links.old_volume[uj] = vol;
@@ -683,7 +1117,7 @@ int SWMMEngine::initialize() noexcept {
                 const int cr = ctx_.link_subtypes.conduit_row(j);
                 const auto& CD = ctx_.link_subtypes.conduits;
                 int barrels = std::max((cr >= 0) ? CD.barrels[static_cast(cr)] : 1, 1);
-                double len = (cr >= 0) ? CD.length[static_cast(cr)] : 0.0;
+                double len = (cr >= 0) ? CD.true_length[static_cast(cr)] : 0.0;
                 double vol = xsect::getAofY(xs, y) * len * barrels;
                 ctx_.links.volume[uj]     = vol;
                 ctx_.links.old_volume[uj] = vol;
@@ -698,6 +1132,9 @@ int SWMMEngine::initialize() noexcept {
     ctx_.old_elapsed_ms      = 0.0;
     // Legacy swmm5.c:721 — ReportTime = 1000 * (double)ReportStep
     ctx_.next_report_ms      = 1000.0 * ctx_.options.report_step;
+    new_rule_time_ms_        = 0.0;   // legacy NewRuleTime (routing.c:131)
+
+    perf::sec_init_state += perf::since(_pt_state0);
 
     // Initialize all computational modules (batch SoA setup)
     init_modules();
@@ -769,6 +1206,53 @@ int SWMMEngine::initialize() noexcept {
 // start()
 // ============================================================================
 
+// ============================================================================
+// F8 — snow cover volume, the ledger term the engine never had
+// ============================================================================
+//
+// Legacy `snow_getSnowCover` (snow.c:587):
+//
+//     for (i = SNOW_PLOWABLE; i <= SNOW_PERV; i++)
+//         snowCover += (wsnow[i] + fw[i]) * fArea[i];
+//     return snowCover * (Subcatch[j].area - Subcatch[j].lidArea);
+//
+// Two details are load-bearing and easy to drop:
+//   * `fw` is IN. The free-water store is water the pack is holding, not
+//     water that has left it. Counting only `wsnow` understates the term by
+//     up to `fwfrac` of every pack and would leave a residual that looks
+//     like a leak -- which is exactly the shape of the residual F8's first
+//     write-up chased and had to retract.
+//   * LID area is OUT, matching the plow-removal volume (Gap #60) and legacy
+//     Build 5.2.0. Water in a LID unit is already counted by
+//     `lid_.storedVolume()` in init/final STORAGE; counting it here as well
+//     would double it.
+static double snowCoverVolumeFt3(const openswmm::SimulationContext& ctx,
+                                 const openswmm::snow::SnowSoA& soa) {
+    double total = 0.0;
+    for (int i = 0; i < ctx.n_subcatches(); ++i) {
+        auto ui = static_cast(i);
+        if (ctx.subcatches.snowpack[ui] < 0) continue;
+        double depth = 0.0;
+        for (int k = 0; k < openswmm::snow::N_SUBAREAS; ++k) {
+            auto idx = static_cast(i * openswmm::snow::N_SUBAREAS + k);
+            if (idx >= soa.wsnow.size()) break;
+            depth += (soa.wsnow[idx] + soa.fw[idx]) * soa.fArea[idx];
+        }
+        const double lid_ft2 = (ui < ctx.subcatches.total_lid_area_ft2.size())
+                                   ? ctx.subcatches.total_lid_area_ft2[ui] : 0.0;
+        // `subcatches.area` is in PROJECT LAND-AREA UNITS (acres in US,
+        // hectares in SI); `total_lid_area_ft2` is in ft². Subtracting one
+        // from the other without converting is the defect the comment at
+        // the rainfall-volume site warns about — it was 2.471x wrong on SI
+        // there, and would be here.
+        double area_ft2 = ctx.subcatches.area[ui] /
+                              ucf::UCF(ucf::LANDAREA, ctx.options) - lid_ft2;
+        if (area_ft2 < 0.0) area_ft2 = 0.0;
+        total += depth * area_ft2;
+    }
+    return total;
+}
+
 int SWMMEngine::start(int save_results) noexcept {
     if (ctx_.state != EngineState::INITIALIZED) {
         set_error(SWMM_ERR_WRONG_STATE,
@@ -784,6 +1268,10 @@ int SWMMEngine::start(int save_results) noexcept {
     // gated on this in step()/postOutputSnapshot().
     do_routing_ = (ctx_.n_nodes() > 0 && !ctx_.options.ignore_routing);
 
+    // Everything up to prepare_all() is interface-file work ([FILES] inflows /
+    // outflows / hotstart / RDII / rainfall).
+    const auto _pt_iface0 = perf::now();
+
     // Open routing interface files ([FILES] USE INFLOWS / SAVE OUTFLOWS) and
     // process headers eagerly — matching legacy routing_open() →
     // iface_openRoutingFiles(). Without this the InterfaceManager stays
@@ -903,8 +1391,12 @@ int SWMMEngine::start(int save_results) noexcept {
                                   "supported by this engine and was ignored");
     }
 
+    perf::sec_start_iface += perf::since(_pt_iface0);
+
     // Phase 4: call prepare() on all plugins (opens output files/headers)
     if (!plugins_.empty()) {
+        perf::ScopedTimer _pt(perf::sec_start_plugins);
+        plugins_prepare_attempted_ = true;
         const int rc = plugins_.prepare_all(ctx_);
         if (rc != 0) {
             set_error(SWMM_ERR_PLUGIN, "swmm_engine_start: plugin prepare() failed");
@@ -918,6 +1410,20 @@ int SWMMEngine::start(int save_results) noexcept {
     // a separate step because the IOutputPlugin contract has no mesh access
     // through SimulationContext — SurfaceRouter2D owns the mesh privately.
     if (surface_output_plugin_ && surface_router_.isActive()) {
+        // The mesh coordinates about to be written were scaled to SI by
+        // SurfaceRouter2D::initialize(); hand the plugin the factor so the
+        // file's /crs variable can state how they relate to the model CRS's
+        // own linear unit (issue #155). The CRS itself arrived via prepare().
+        surface_output_plugin_->setMeshCoordinateScale(
+            surface_router_.options().mesh_to_si_factor);
+        // Results-file size controls ([2D_OPTIONS] OUTPUT_PRECISION /
+        // OUTPUT_COMPRESSION / REPORT_2D_VARIABLES / REPORT_2D_SPECIES /
+        // REPORT_2D_STEP) — applied before the datasets are created.
+        {
+            const std::string cfg_err = surface_output_plugin_->configureOutput(
+                surface_router_.options(), ctx_.options.report_step);
+            if (!cfg_err.empty()) push_report_warning(cfg_err, 0);
+        }
         surface_output_plugin_->prepareMeshAndDatasets(surface_router_.mesh());
     }
 #endif
@@ -938,6 +1444,25 @@ int SWMMEngine::start(int save_results) noexcept {
 // step()
 // ============================================================================
 
+namespace {
+/// A reserved-species node OVERRIDE is the node's PUBLISHED state
+/// (openswmm_forcing.h). applyForcings writes it before the step, but the
+/// quality stage recomputes a flow-through junction from its inflow, so
+/// step() re-asserts it once transport has run.
+void reassertNodeStateOverrides(SimulationContext& ctx) noexcept {
+    const auto& f = ctx.forcing;
+    const auto nn = static_cast(ctx.n_nodes());
+    if (ctx.options.heat_transport && ctx.heat_state.node_temp.size() == nn)
+        for (std::size_t u = 0; u < nn && u < f.node_temperature_mode.size(); ++u)
+            if (f.node_temperature_mode[u] == ForcingMode::OVERRIDE)
+                ctx.heat_state.node_temp[u] = f.node_temperature_value[u];
+    if (ctx.options.water_age && ctx.water_age_state.node_age.size() == nn)
+        for (std::size_t u = 0; u < nn && u < f.node_age_mode.size(); ++u)
+            if (f.node_age_mode[u] == ForcingMode::OVERRIDE)
+                ctx.water_age_state.node_age[u] = f.node_age_value[u] * 3600.0;
+}
+}  // namespace
+
 int SWMMEngine::step(double* elapsed_time) noexcept {
     if (ctx_.state != EngineState::RUNNING) {
         if (elapsed_time) *elapsed_time = 0.0;
@@ -970,8 +1495,37 @@ int SWMMEngine::step(double* elapsed_time) noexcept {
         }
         dt_next = dt;
     } else {
+        // legacy routing_getRoutingStep (routing.c): BETWEEN routing events
+        // (the BetweenEvents flag the previous routing_execute set) the
+        // step jumps to MIN(NewRunoffTime, ReportTime) when that instant is
+        // ahead and before the next event's start, else takes the fixed
+        // step when it stays before the event — the CFL step is never
+        // formed (its 1 ms first value put session64-custom-shapes, whose
+        // event window lies outside the run, on a 1 ms / 20.001 s grid
+        // where legacy steps 20 s, and the reports blended the never-routed
+        // old/new pairs at f = 0.99995 instead of 1).
+        double dt_between = 0.0;
+        if (!ctx_.events.empty() && between_events_ &&
+            next_event_ < static_cast(ctx_.events.size())) {
+            const double fixed = ctx_.options.routing_step;
+            const double ev_start = ctx_.events[static_cast(next_event_)].start;
+            const double next_ms = std::min(new_runoff_ms_, ctx_.next_report_ms);
+            const double date1 = datetime::addSeconds(ctx_.options.start_date,
+                                                      (ctx_.elapsed_ms + 1.0) / 1000.0);
+            const double date2 = datetime::addSeconds(ctx_.options.start_date,
+                                                      (next_ms + 1.0) / 1000.0);
+            if (date2 > date1 && date2 < ev_start) {
+                dt_between = (next_ms - ctx_.elapsed_ms) / 1000.0;
+            } else {
+                const double d1 = datetime::addSeconds(ctx_.options.start_date,
+                                                       (ctx_.elapsed_ms + 1000.0 * fixed + 1.0) / 1000.0);
+                if (d1 < ev_start) dt_between = fixed;
+            }
+        }
         double dt_cfl = ctx_.options.routing_step;
-        if (ctx_.options.variable_step > 0.0) {
+        if (dt_between > 0.0) {
+            dt_cfl = dt_between;
+        } else if (ctx_.options.variable_step > 0.0) {
             dt_cfl = router_.getAdaptiveStep(ctx_, ctx_.options.routing_step,
                                               ctx_.options.variable_step);
             // Track max Courant number: ratio of fixed step to CFL-limited step
@@ -981,10 +1535,30 @@ int SWMMEngine::step(double* elapsed_time) noexcept {
                     std::max(ctx_.routing_stats.max_courant, courant);
             }
         }
+        // Control-rule grid alignment (legacy routing.c:196-204): when
+        // RULE_STEP > 0 the routing step is snapped so it lands exactly on
+        // the next rule-evaluation boundary. Recomputed from the ABSOLUTE
+        // rule grid each step (advance()'s decrement would drift); the
+        // clamp itself lives in TimestepController::compute_next step 3.
+        if (ctx_.options.rule_step > 0.0) {
+            ctx_.dt_controls_remaining =
+                (new_rule_time_ms_ + 1000.0 * ctx_.options.rule_step -
+                 ctx_.elapsed_ms) / 1000.0;
+        }
         // No 2D constraint on the 1D step: the marcher owns 2D stability
         // through its internal CFL subcycling, and exchange stability is owned
         // by per-substep evaluation + limiter + the node conductance.
         dt_next = hydraulics::TimestepController::compute_next(ctx_, dt_cfl);
+        // The between-events jump is not bounded by the routing step
+        // (compute_next's min); only the duration and rule-grid clamps apply.
+        if (dt_between > ctx_.options.routing_step) {
+            dt_next = dt_between;
+            const double total_msec = ctx_.options.totalDurationMs();
+            if (ctx_.elapsed_ms + 1000.0 * dt_next > total_msec)
+                dt_next = std::max((total_msec - ctx_.elapsed_ms) / 1000.0, 0.001);
+            if (ctx_.dt_controls_remaining > 0.0 && ctx_.dt_controls_remaining < dt_next)
+                dt_next = ctx_.dt_controls_remaining;
+        }
     }
 
     // Fire step-begin callback
@@ -998,8 +1572,13 @@ int SWMMEngine::step(double* elapsed_time) noexcept {
         );
     }
 
-    // Snapshot state before solving
-    ctx_.save_state();
+    // Snapshot the every-step old state (legacy initSystemInflows'
+    // oldLatFlow and the quality old state). The HYDRAULIC old state rolls
+    // in stepRouting once the step is known to be routed (legacy routeFlow's
+    // node/link _setOldHydState): a SKIP_STEADY_STATE step keeps the last
+    // routed step's old/new pair, which its reports interpolate and its
+    // steady test (oldFlowInflow vs inflow) compares.
+    ctx_.save_lat_qual_state();
 
     // Reset mass balance accumulators (matching legacy massbal_initTimeStepTotals)
     resetStepMassBalance();
@@ -1017,9 +1596,22 @@ int SWMMEngine::step(double* elapsed_time) noexcept {
     // run every step.
     if (do_routing_) {
         stepRouting(dt_next);
-        updateStatistics(dt_next);
-        updateRoutingMassBalance(dt_next);
-    }
+        if (const int drc = checkRoutingDiverged(); drc != SWMM_OK)
+            return drc;
+        // Legacy keeps BOTH of these inside the !BetweenEvents branch of
+        // routing_execute (routing.c:240-268): stats_updateFlowStats /
+        // stats_updateTimeStepStats, and the removeSystemOutflows that fills
+        // StepFlowTotals. Between events its step totals therefore stay at the
+        // zero massbal_initTimeStepTotals left them, and the system rows read
+        // zero. updateRoutingMassBalance re-derives step_outflow from node
+        // state, so running it on a skipped step republished the last routed
+        // step's outflow for the rest of the window.
+        if (!between_events_) {
+            updateStatistics(dt_next);
+            updateRoutingMassBalance(dt_next);
+        }
+    }
+    reassertNodeStateOverrides(ctx_);
     computeFinalStorage();
     // IGNORE_QUALITY: surface buildup was never updated this run, so skip the
     // final quality mass-balance pass (legacy skips the whole quality path).
@@ -1027,22 +1619,48 @@ int SWMMEngine::step(double* elapsed_time) noexcept {
         computeFinalQualityMassBalance();
     }
 
-    // Accumulate node/link results for time-step averaging (legacy RptFlags.averages)
-    if (ctx_.options.rpt_averages) {
-        accumulateAvgResults();
-    }
-
     // ---- Clear auto-reset forcings ----
     ctx_.forcing.clear_reset_entries();
 
     // Advance clock (must happen before output_due check)
     hydraulics::TimestepController::advance(ctx_, dt_next);
 
+    // Advance the control-rule clock when the step landed on its grid
+    // (legacy routing.c:407-408, 1 ms tolerance).
+    if (do_routing_ && ctx_.options.rule_step > 0.0 &&
+        std::fabs(ctx_.elapsed_ms -
+                  (new_rule_time_ms_ + 1000.0 * ctx_.options.rule_step)) < 1.0) {
+        new_rule_time_ms_ += 1000.0 * ctx_.options.rule_step;
+    }
+
+    // Accumulate node/link results for time-step averaging with legacy's
+    // update ordering (swmm5.c saveResults): each step's END state
+    // accumulates exactly once, into the report period whose window it
+    // terminates in — a boundary hit (NewRoutingTime == ReportTime) goes to
+    // the CLOSING period (update BEFORE the save), an overshoot (>) goes to
+    // the NEXT period (update AFTER the save), and non-boundary steps always
+    // accumulate. The == compare is exact only because elapsed_ms and
+    // next_report_ms use the identical `+= 1000.0 * x` recurrences
+    // (TimestepController::advance / reset_output_timer) — keep the three
+    // sites in lockstep.
+    const bool avg_out_due =
+        ctx_.options.rpt_averages &&
+        hydraulics::TimestepController::output_due(ctx_);
+    const bool avg_exact =
+        avg_out_due && (ctx_.elapsed_ms == ctx_.next_report_ms);
+    if (ctx_.options.rpt_averages && (!avg_out_due || avg_exact)) {
+        accumulateAvgResults();
+    }
+
     // Post snapshot after advance so output_due() fires correctly.
     // All subcatch/node/link state arrays still reflect the end of the
     // just-completed routing step — advance only updates timers, not state.
     postOutputSnapshot(dt_next);
 
+    if (avg_out_due && !avg_exact) {
+        accumulateAvgResults();
+    }
+
     // Fire step-end callback
     if (callbacks_.on_step_end) {
         callbacks_.on_step_end(
@@ -1087,51 +1705,122 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
     // 15-18% higher peak rates (same volume, sharper peaks).
     // ================================================================
 
-    double routing_time = ctx_.current_time;  // seconds from simulation start
-
     // --- Phase 1: Advance runoff clock if needed ---
     // Legacy: while (NewRunoffTime < nextRoutingTime) runoff_execute();
     // Runoff must catch up past the END of this routing step so that
     // infil/evap/runoff reflect the interval STARTING at the report
-    // boundary. Legacy achieves this accidentally via variable timestep
-    // Legacy uses strict < (runoff.c line 164: while(NewRunoffTime < nextRoutingTime))
+    // boundary. Legacy uses strict < (swmm5.c execRouting).
     //
-    // Clamp next_routing_time to the simulation end, matching legacy
-    // swmm5.c::execRouting() line 900-905. Without this clamp, floating-point
-    // drift in `routing_time + dt_routing` can leave next_routing_time slightly
-    // above total_sec while new_runoff_time_ has already been clamped to
-    // total_sec inside this loop body — causing the while-loop to fire
-    // indefinitely with dt_runoff = 0.
+    // Clamp the step end to the simulation end, matching legacy
+    // swmm5.c::execRouting(). Without this clamp, floating-point drift can
+    // leave the step end slightly above the total duration while
+    // new_runoff_time_ has already been clamped to it inside this loop body
+    // — causing the while-loop to fire indefinitely with dt_runoff = 0.
     // PARITY: use the legacy-exact TotalDuration (swmm5.c:3198-3200) — the
     // combined-serial product (end-start)*86400 rounds differently and
     // perturbs the final clipped runoff step (see totalDurationMs()).
     const double total_sec_clamp = ctx_.options.totalDurationMs() / 1000.0;
-    double next_routing_time = std::min(routing_time + dt_routing, total_sec_clamp);
-    while (new_runoff_time_ < next_routing_time) {
-        // Save old runoff/runon/conc + GW state for interpolation at the RUNOFF
-        // step cadence (matching legacy subcatch_setOldState, which legacy calls
-        // inside runoff_execute — NOT per routing step). subcatches.save_state()
-        // snapshots old_runoff/old_runon_inflow/conc_old; old_gw_flow is saved
-        // separately (not covered by save_state). This is the ONLY place the
-        // subcatch old-state is taken (see SimulationContext::save_state()).
+    // The trigger itself is legacy's, on the ms clocks (swmm5.c execRouting:
+    // nextRoutingTime = NewRoutingTime + 1000*routingStep, clamped to
+    // RoutingDuration; while (NewRunoffTime < nextRoutingTime)). The
+    // seconds clocks carry their own accumulated rounding, and a routing
+    // step ending exactly on a runoff boundary came out an ulp past it —
+    // one extra runoff step, a step early, on rtk-long-r3-only at day 114.
+    const double next_routing_ms =
+        std::min(ctx_.elapsed_ms + 1000.0 * dt_routing,
+                 ctx_.options.totalDurationMs());
+    while (new_runoff_ms_ < next_routing_ms) {
+        // Save old runoff/runon/conc + GW/snow/LID-drain state for interpolation
+        // at the RUNOFF step cadence (matching legacy subcatch_setOldState +
+        // lid_setOldGroupState, which legacy calls inside runoff_execute — NOT
+        // per routing step). subcatches.save_state() snapshots
+        // old_runoff/old_runon_inflow/conc_old; the rest is saved separately
+        // (not covered by save_state). This is the ONLY place the subcatch
+        // old-state is taken (see SimulationContext::save_state()).
+        // lid_drain_flow is zeroed after the roll (legacy lid.c:1341-1342) and
+        // re-accumulated by the A6b drain-routing loop later this substep.
         ctx_.subcatches.save_state();
+        // The MSX species mirror of conc_old. save_state() only knows the
+        // pollutant arrays, so the species washoff concentration is rolled
+        // here, on the same runoff cadence, for the same reason: the delivery
+        // seam interpolates between the two runoff steps and needs both ends.
+        if (ctx_.reactions.surface.active())
+            ctx_.reactions.surface.washoff_conc_old =
+                ctx_.reactions.surface.washoff_conc;
         for (int i = 0; i < ctx_.n_subcatches(); ++i) {
             auto ui = static_cast(i);
             ctx_.subcatches.old_gw_flow[ui] = ctx_.subcatches.gw_flow[ui];
+            // legacy gw->oldFlow = gw->newFlow: the RATE, not the cfs product.
+            if (ui < old_gw_rate_.size())
+                old_gw_rate_[ui] = (ui < groundwater_.state().gw_flow.size())
+                                 ? groundwater_.state().gw_flow[ui] : 0.0;
+            ctx_.subcatches.old_snow_depth[ui] = ctx_.subcatches.snow_depth[ui];
+            ctx_.subcatches.old_lid_drain_flow[ui] =
+                ctx_.subcatches.lid_drain_flow[ui];
+            ctx_.subcatches.lid_drain_flow[ui] = 0.0;
+        }
+        // legacy lid_setOldGroupState: each unit's oldDrainFlow = newDrainFlow
+        // — the underdrain hysteresis memory the kernel reads this step and
+        // the "old" end of the routing-step drain interpolation.
+        for (int t = 0; t < lid_.numGroups(); ++t) {
+            auto& g = lid_.group(t);
+            for (int u = 0; u < g.count; ++u) {
+                auto uu = static_cast(u);
+                g.old_drain_flow[uu] = g.drain_flow[uu];
+            }
         }
 
-        // Advance runoff clock
+        // Advance runoff clock. legacy runoff.c:177 forms the PREVIOUS step's
+        // span first; runoff_getOutfallRunon divides the routed outfall
+        // volume by it (not by the step about to be taken).
+        prev_runoff_step_sec_ = (new_runoff_ms_ - old_runoff_ms_) / 1000.0;
         old_runoff_time_ = new_runoff_time_;
         old_runoff_ms_   = new_runoff_ms_;   // legacy runoff.c:229
-        double abs_time = datetime::addSeconds(ctx_.options.start_date, old_runoff_time_);
+        // Run-on for THIS step (legacy runoff.c:247-253: outfall runon, then
+        // upstream runoff and LID drains, right after the old-state roll).
+        // It used to be assembled at the END of the previous step, so the
+        // outfall volume routed during the routing steps since then reached
+        // the subcatchment one runoff step late.
+        assembleRunon();
+        // legacy runoff.c:180 currentDate = getDateTime(NewRunoffTime) =
+        // StartDateTime + (elapsedMsec + 1)/1000 s (swmm5.c getDateTime):
+        // the step's start on the ms clock plus one millisecond. The
+        // interpolated climate lookups (temperature series) see that
+        // millisecond.
+        double abs_time = datetime::addSeconds(ctx_.options.start_date,
+                                               (old_runoff_ms_ + 1.0) / 1000.0);
 
         // Gap #26: clear LID drain quality node accumulators each runoff step.
         // They are repopulated in A6b and consumed each routing step by addWetWeatherLoads().
-        if (ctx_.n_pollutants() > 0) {
+        // A4: water age keeps this alive at zero pollutants. The drain
+        // volume accumulator is the age's mixing denominator, so the two
+        // must be cleared and refilled on the same cadence.
+        // The drain's WATER channel is cleared on this cadence regardless of
+        // quality — it is what carries the drain into the network at all.
+        std::fill(ctx_.nodes.lid_drain_inflow.begin(),
+                  ctx_.nodes.lid_drain_inflow.end(), 0.0);
+        if (ctx_.n_pollutants() > 0 || ctx_.options.water_age ||
+            ctx_.options.heat_transport) {
+            // legacy lid_addDrainInflow interpolates the drain's water AND
+            // its load between the previous and current runoff steps at
+            // every routing step. Keep the outgoing step's rates as the
+            // "old" ends of that pair before zeroing for the refill; on a
+            // sharp first flush the constant current-rate form delivered
+            // the pulse one full runoff step early
+            // (swmm-5-model-with-lid-but-no-bottom-infiltration's node
+            // XXXXX00035: v6 899 mg/L at period 8 against legacy ~0, with
+            // legacy's 999 arriving at period 9).
+            ctx_.nodes.lid_drain_qual_load_old = ctx_.nodes.lid_drain_qual_load;
+            ctx_.nodes.lid_drain_qual_vol_old  = ctx_.nodes.lid_drain_qual_vol;
             std::fill(ctx_.nodes.lid_drain_qual_load.begin(),
                       ctx_.nodes.lid_drain_qual_load.end(), 0.0);
             std::fill(ctx_.nodes.lid_drain_qual_vol.begin(),
                       ctx_.nodes.lid_drain_qual_vol.end(), 0.0);
+            std::fill(ctx_.water_age_state.node_lid_drain_age_vol_in.begin(),
+                      ctx_.water_age_state.node_lid_drain_age_vol_in.end(),
+                      0.0);
+            std::fill(ctx_.heat_state.node_lid_drain_temp_vol_in.begin(),
+                      ctx_.heat_state.node_lid_drain_temp_vol_in.end(), 0.0);
         }
 
         // Current-step rainfall flag (legacy IsRaining): set BEFORE the timestep
@@ -1157,6 +1846,12 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
             // Temperature from timeseries
             auto& tbl = ctx_.tables.tables[static_cast(ctx_.climate_state.temp_ts_index)];
             ctx_.climate_state.temperature_src = table_lookup_cursor(tbl, abs_time);
+            // legacy setTemp: an SI deck's series is degC, converted to the
+            // degF the engine runs on before the (already scaled) monthly
+            // adjustment is added.
+            if (unit_sys == 1)
+                ctx_.climate_state.temperature_src =
+                    (9. / 5.) * ctx_.climate_state.temperature_src + 32.0;
             ctx_.climate_state.temperature_src += ctx_.climate_state.adjust_temp[mon];
         } else if (ctx_.options.temp_source == 2 && climate_file_.isOpen()) {
             // Temperature from climate file (Gap #9: sub-daily sinusoidal interp)
@@ -1202,13 +1897,31 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
 
         climate::updateDailyClimate(ctx_.climate_state, doy, mon);
 
-        // A2b. Evaporation from timeseries or climate file
+        // A2b'. Seasonal snowmelt coefficients. Legacy recomputes these once
+        // a day, from setTemp in climate.c:1176-1180, and NOTHING in this
+        // engine called the modern equivalent: `dhm` stayed at its
+        // `assign(0.0)` value, so `imelt = dhm * (temp - tbase)` was
+        // identically zero and the degree-day melt term never fired on any
+        // deck. Only rain-on-snow melt could produce water. The unit suite
+        // did not catch it because every snow gate calls setMeltCoeffs
+        // itself before stepping the solver.
+        if (doy != last_melt_doy_) {
+            last_melt_doy_ = doy;
+            snow_.setMeltCoeffs(doy);
+        }
+
+        // A2b. Evaporation from timeseries or climate file (legacy setEvap).
+        //      TIMESERIES is step-wise: the rate changes only when the date
+        //      reaches NextEvapDate (climate.c setEvap / setNextEvapDate) —
+        //      it was interpolated between entries before, which put a
+        //      ramp where legacy has a step (w-wo-pp: 0.417 in/day reported
+        //      against legacy's 0.5 an hour before the series drops to 0).
         if (ctx_.climate_state.evap_method == climate::EvapMethod::TIMESERIES &&
             ctx_.climate_state.evap_ts_index >= 0) {
-            auto& tbl = ctx_.tables.tables[static_cast(ctx_.climate_state.evap_ts_index)];
-            double evap_user = table_lookup_cursor(tbl, abs_time);
-            ctx_.climate_state.evap_rate = evap_user / ucf::Ucf[ucf::EVAPRATE][unit_sys];
-            ctx_.climate_state.evap_rate *= ctx_.climate_state.adjust_evap[mon];
+            if (abs_time >= ctx_.climate_state.next_evap_date)
+                ctx_.climate_state.evap_rate =
+                    ctx_.climate_state.next_evap_rate / ucf::Ucf[ucf::EVAPRATE][unit_sys];
+            ctx_.climate_state.evap_rate += ctx_.climate_state.adjust_evap[mon];
         }
         else if (ctx_.climate_state.evap_method == climate::EvapMethod::PAN &&
                  climate_file_.isOpen()) {
@@ -1218,9 +1931,13 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 // rec.evap is in user units (in/day US, mm/day SI)
                 ctx_.climate_state.evap_rate = rec.evap / ucf::Ucf[ucf::EVAPRATE][unit_sys];
                 ctx_.climate_state.evap_rate *= ctx_.options.pan_coeff[mon];
-                ctx_.climate_state.evap_rate *= ctx_.climate_state.adjust_evap[mon];
+                ctx_.climate_state.evap_rate += ctx_.climate_state.adjust_evap[mon];
             }
         }
+        // legacy climate_setState ends by advancing NextEvapDate past the
+        // current date (every evaporation type); runoff_getTimeStep then
+        // clamps the runoff step so it never crosses it.
+        setNextEvapDate(abs_time);
 
         // A2b'. System-wide evaporation forcing — applied after all evap
         // sources and monthly adjustments so the prescription is final.
@@ -1231,7 +1948,10 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
 
         // A2c. Wind speed lookup
         if (ctx_.options.wind_type == 0) {
-            ctx_.climate_state.wind_speed_src = ctx_.options.wind_speed[mon];
+            // legacy setWind: Wind.ws = Wind.aws[mon-1] / UCF(WINDSPEED)
+            // (km/hr -> mph on an SI deck).
+            ctx_.climate_state.wind_speed_src = ctx_.options.wind_speed[mon]
+                / ucf::UCF(ucf::WINDSPEED, ctx_.options);
         } else if (ctx_.options.wind_type == 1 && climate_file_.isOpen()) {
             // Wind from climate file
             climate::DailyClimateRecord rec;
@@ -1245,6 +1965,33 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
         ctx_.climate_state.wind_speed =
             ctx_.forcing.effective_wind(ctx_.climate_state.wind_speed_src);
 
+        // A2c''. H2: relative humidity. ClimateState::humidity has carried a
+        // 50 % default since before the transport program with NO writer
+        // anywhere; SurfaceExchange is its first consumer, so this is where
+        // it starts being real. CONSTANT/MONTHLY read the monthly array;
+        // TIMESERIES looks the table up. A DEWPOINT deck stores dew-point
+        // temperature (project units) and is converted to RH here from the
+        // effective air temperature: RH = 100·e_s(Td)/e_s(Ta).
+        {
+            double h = ctx_.options.humidity[mon];
+            if (ctx_.climate_state.humidity_ts_index >= 0) {
+                auto& tbl = ctx_.tables.tables[
+                    static_cast(ctx_.climate_state.humidity_ts_index)];
+                h = table_lookup_cursor(tbl, abs_time);
+            }
+            if (ctx_.options.humidity_var == 1) {
+                // Dew point: SI decks author degC, US decks degF; the air
+                // temperature is held in degF internally.
+                const double td_c = (unit_sys == 1)
+                    ? h : (h - 32.0) * 5.0 / 9.0;
+                const double ta_c = (ctx_.climate_state.temperature - 32.0) * 5.0 / 9.0;
+                using openswmm::transport::heat::saturationVapourPressure;
+                h = 100.0 * saturationVapourPressure(td_c) /
+                    saturationVapourPressure(ta_c);
+            }
+            ctx_.climate_state.humidity = std::clamp(h, 0.0, 100.0);
+        }
+
         // A2d. Monthly adjustment factors
         ctx_.climate_state.infil_factor = ctx_.adjust_hydcon[mon];
 
@@ -1266,6 +2013,12 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                     ctx_.gages.rainfall[static_cast(g)] *= rain_factor;
             }
         }
+#ifdef OPENSWMM_HAS_2D
+        // The 2D integrates exactly the rates this runoff step applies, from
+        // its start, so mesh and subcatchments receive the same gage depth.
+        if (surface_router_.isActive())
+            surface_router_.bookGageRates(ctx_, old_runoff_ms_ / 1000.0);
+#endif
 
         // A2z. [FILES] USE RUNOFF — replace this runoff substep with the
         // next record from the runoff interface file (legacy
@@ -1303,8 +2056,7 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 && !ctx_.options.ignore_rainfall
                 && !(rdii_iface_file_.isOpen()
                      && !rdii_iface_file_.isWriting())) {
-                int rdii_month_use = datetime::monthOfYear(abs_time) - 1;
-                rdii_.computeAll(ctx_, rdii_month_use, file_dt);
+                rdii_.advance(ctx_, new_runoff_time_);
             }
             continue;   // file replaces snowmelt/runoff/GW/LID/quality steps
         }
@@ -1343,8 +2095,7 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 // straight from the interface file in stepRouting() B2a
                 // (legacy rdii_openRdii() skips createRdiiFile()).
             } else {
-                int rdii_month = datetime::monthOfYear(abs_time) - 1;
-                rdii_.computeAll(ctx_, rdii_month, dt_runoff);
+                rdii_.advance(ctx_, new_runoff_time_);
                 // [FILES] SAVE RDII: export the freshly computed flows
                 // (legacy saveRdiiFlows(): date + per-node cfs).
                 if (rdii_iface_file_.isOpen() && rdii_iface_file_.isWriting()) {
@@ -1381,14 +2132,31 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 // Returns ft/sec.
                 gage::PrecipSplit p = gage::splitPrecip(ctx_, ui);
                 // Forcing channels resolve on top. effective_rainfall() takes
-                // user units, so convert out and back; the snowfall channel
-                // already stores ft/sec.
-                double rain_inhr = p.rainfall * ucf::Ucf[ucf::RAINFALL][0];
-                rain_inhr = ctx_.forcing.effective_rainfall(ui, rain_inhr);
-                snow_rain_[ui] = rain_inhr / ucf::Ucf[ucf::RAINFALL][0];
+                // user units, so convert out and back — only when a forcing
+                // is set, the round trip not being a floating-point identity;
+                // the snowfall channel already stores ft/sec.
+                snow_rain_[ui] = p.rainfall;
+                if (ui < ctx_.forcing.subcatch_rainfall_mode.size() &&
+                    ctx_.forcing.subcatch_rainfall_mode[ui] != ForcingMode::NONE) {
+                    double rain_inhr = p.rainfall * ucf::Ucf[ucf::RAINFALL][0];
+                    rain_inhr = ctx_.forcing.effective_rainfall(ui, rain_inhr);
+                    snow_rain_[ui] = rain_inhr / ucf::Ucf[ucf::RAINFALL][0];
+                }
                 snow_snow_[ui] = ctx_.forcing.effective_snowfall(ui, p.snowfall);
             }
 
+            // S2b — hand the snow solver what it needs to carry water age.
+            // A scalar in, nothing out: hydrology keeps no dependency on the
+            // transport layer, the same way `season` is handed in. Set
+            // BEFORE plowSnow, because plowSnow is where snowfall is mixed
+            // into the pack at its source age.
+            {
+                auto& snow_soa = snow_.state();
+                snow_soa.track_age  = ctx_.options.water_age;
+                snow_soa.precip_age = ctx_.water_age_config.global_age[
+                    static_cast(WaterAgeSource::RAINFALL)];
+            }
+
             // Accumulation + plowing BEFORE melt (legacy runoff.c:254).
             snow_.plowSnow(ctx_, dt_runoff, snow_snow_.data());
 
@@ -1413,7 +2181,9 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
 
                 double fPlow   = soa.fArea[plow_idx];
                 double fImperv = soa.fArea[imperv_idx];
-                double fTotalI = fPlow + fImperv;
+                // legacy snow.c:570-575 divides the blend by the
+                // subcatchment's fracImperv (fPlow + fImperv up to an ulp).
+                double fTotalI = ctx_.subcatches.frac_imperv[ui];
 
                 double net_plow   = soa.imelt[plow_idx]   + rainfall_ft * (1.0 - soa.asc[plow_idx]);
                 double net_imperv = soa.imelt[imperv_idx] + rainfall_ft * (1.0 - soa.asc[imperv_idx]);
@@ -1423,56 +2193,105 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                     ? (net_plow * fPlow + net_imperv * fImperv) / fTotalI
                     : net_plow;
                 ctx_.subcatches.snow_net_perv[ui] = net_perv;
+
+                // S2: the MELT-ONLY part, under the identical area blend.
+                // Arriving water under a pack is two different waters —
+                // meltwater at 0 C carrying the pack's age, and rain that
+                // reached the ground through the snow-free fraction — and
+                // their sum cannot say what either is worth. The split is a
+                // local here; publishing it follows A4's precedent rather
+                // than having transport reconstruct it.
+                ctx_.subcatches.snow_melt_imperv[ui] = (fTotalI > 0.0)
+                    ? (soa.imelt[plow_idx] * fPlow +
+                       soa.imelt[imperv_idx] * fImperv) / fTotalI
+                    : soa.imelt[plow_idx];
+                ctx_.subcatches.snow_melt_perv[ui] = soa.imelt[perv_idx];
+
+                // S2b — the AGE of that meltwater, under the identical
+                // blend. Weighted by melt VOLUME rather than by area alone:
+                // the impervious value mixes plowable and non-plowable melt,
+                // and two surfaces contributing different rates do not
+                // contribute their ages equally. Weighting by area would be
+                // the same expression as the rate blend and would still be
+                // wrong, because an age is an intensive property of the
+                // water and the rate is not.
+                if (soa.track_age) {
+                    const double m_plow = soa.imelt[plow_idx] * fPlow;
+                    const double m_imp  = soa.imelt[imperv_idx] * fImperv;
+                    const double m_sum  = m_plow + m_imp;
+                    ctx_.subcatches.snow_melt_age_imperv[ui] =
+                        (m_sum > 0.0)
+                            ? (soa.out_age[plow_idx] * m_plow +
+                               soa.out_age[imperv_idx] * m_imp) / m_sum
+                            : soa.out_age[plow_idx];
+                    ctx_.subcatches.snow_melt_age_perv[ui] =
+                        soa.out_age[perv_idx];
+                }
             }
-        }
 
-        // A3b. Apply N-PERV/DSTORE pattern adjustments (before runoff)
-        if (ctx_.has_subcatch_adj_patterns) {
+            // Legacy newSnowDepth (subcatch.c:816): the per-subcatch SWE
+            // snapshot is taken each runoff step so the reporter can blend
+            // old/new to the report instant (subcatch.c:888-890). Same
+            // recompute as the API getter.
             for (int i = 0; i < ctx_.n_subcatches(); ++i) {
                 auto ui = static_cast(i);
-                // N-PERV pattern
-                if (ui < ctx_.subcatch_n_perv_pattern.size()) {
-                    int pi = ctx_.subcatch_n_perv_pattern[ui];
-                    if (pi >= 0 && static_cast(pi) < ctx_.patterns.factors.size()) {
-                        const auto& facs = ctx_.patterns.factors[static_cast(pi)];
-                        auto umon = static_cast(mon);
-                        double f = (umon < facs.size()) ? facs[umon] : 1.0;
-                        ctx_.subcatches.n_perv[ui] = ctx_.base_n_perv[ui] * f;
-                    }
-                }
-                // DSTORE pattern
-                if (ui < ctx_.subcatch_d_store_pattern.size()) {
-                    int pi = ctx_.subcatch_d_store_pattern[ui];
-                    if (pi >= 0 && static_cast(pi) < ctx_.patterns.factors.size()) {
-                        const auto& facs = ctx_.patterns.factors[static_cast(pi)];
-                        auto umon = static_cast(mon);
-                        double f = (umon < facs.size()) ? facs[umon] : 1.0;
-                        ctx_.subcatches.ds_perv[ui] = ctx_.base_ds_perv[ui] * f;
-                    }
-                }
-                // INFIL pattern: scales infil_factor for this subcatchment
-                // (applied globally via ctx_.climate_state.infil_factor already;
-                //  per-subcatchment INFIL pattern would require per-subcatch
-                //  infil_factor which is a deeper refactor — noted for future)
+                ctx_.subcatches.snow_depth[ui] = subcatchSnowDepth(i);
             }
         }
 
+        // A3b. The N-PERV / DSTORE / INFIL monthly patterns are applied where
+        // legacy applies them — inside the runoff kernel, per subarea, per
+        // runoff step (adjustSubareaParams / infil_setInfilFactor). Scaling
+        // ctx_.subcatches.n_perv / .ds_perv here did nothing for the solve
+        // (RunoffSoA snapshots both in init() and never re-reads them) and
+        // wrote the adjusted values back over the authored ones, which the
+        // .inp writer and the C API then reported as the user's input.
+
         // A4. Runoff (computes subcatches.runoff[i] = newRunoff rate)
         //     Runoff solver is self-contained; output is subcatches.runoff[i].
         //     Routing picks it up via Phase 2 interpolation → nodes.runoff_inflow[].
         runoff_.execute(ctx_, dt_runoff, ctx_.climate_state.evap_rate,
                         ctx_.climate_state.infil_factor, ctx_.climate_state.recovery_factor, mon);
 
+        // A3: subcatchment surface age, immediately after the depths this
+        // step produced. Reads the solver's own SoA because
+        // ctx.subcatches.ponded_depth is declared but written by NOBODY.
+        transport::routeSubcatchmentAge(ctx_, runoff_.soa(), dt_runoff);
+
+        // H5a: the temperature mirror, on the same clock and reading the
+        // same SoA. It carries the surface energy balance (D-H5a), so it
+        // must see dt_runoff — H2's node/link bindings run on the ROUTING
+        // clock and pass their own dt; handing either the other's interval
+        // would scale every flux wrongly.
+        transport::routeSubcatchmentTemperature(ctx_, runoff_.soa(),
+                                                dt_runoff);
+
         // Update persistent state flags for the NEXT step's timestep selection
         // (legacy runoff.c sets HasRunoff/HasSnow here, after computing runoff,
         // and reads them in the next runoff_getTimeStep call — one-step lag).
         // Keeping wet_step while has_runoff_ holds integrates the recession limb
         // at the fine step legacy uses.
+        // Legacy runoff.c:270-271 sets both flags in the same subcatchment
+        // loop: HasRunoff from the runoff rate, HasSnow from newSnowDepth.
+        // has_snow_ was declared but never assigned, so a snow-covered study
+        // area with no rain took the DRY step (23 h on the snowmelt decks)
+        // and the melt, which legacy evaluates every WET step, never ran.
+        // HasRunoff tests subcatch_getRunoff's RETURN value — the three
+        // subareas' runoff over the full area, before the inter-subarea
+        // transfer and the LID exchange — not newRunoff (the outlet flow):
+        // an impervious subarea routed to the pervious one keeps the WET
+        // step alive while it trickles (117-h-h-elements-si-units). A
+        // zero-area subcatchment is skipped there (runoff.c:266).
         has_runoff_ = false;
-        for (int i = 0; i < ctx_.n_subcatches(); ++i) {
-            if (ctx_.subcatches.runoff[static_cast(i)] > 0.0) {
-                has_runoff_ = true;
-                break;
+        has_snow_   = false;
+        {
+            const auto& rsoa = runoff_.soa();
+            for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+                auto usi = static_cast(i);
+                if (ctx_.subcatches.area[usi] == 0.0) continue;
+                if (usi < rsoa.subarea_runoff_rate.size() &&
+                    rsoa.subarea_runoff_rate[usi] > 0.0) has_runoff_ = true;
+                if (ctx_.subcatches.snow_depth[usi] > 0.0) has_snow_ = true;
             }
         }
 
@@ -1492,6 +2311,20 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
         //      `if (IgnoreQuality) continue;`).
         if (!ctx_.options.ignore_quality) {
             stepSurfaceQuality(dt_runoff);
+            // BW-MSX: the same buildup / washoff arithmetic over the reactions
+            // component's species (separate store, same cadence).
+            msxsurf::step(ctx_, dt_runoff,
+                          datetime::addSeconds(ctx_.options.start_date, old_runoff_time_));
+#ifdef OPENSWMM_HAS_2D
+            // S7: the same relations on the 2D cells' land-use coverages —
+            // buildup, washoff into the cell rows, sweeping — at the runoff
+            // cadence, on the runoff calendar (dry days, sweep season).
+            if (surface_router_.surfaceQuality().active())
+                surface_router_.surfaceQuality().step(
+                    ctx_, surface_router_.mesh(), surface_router_.state(), dt_runoff,
+                    datetime::addSeconds(ctx_.options.start_date, old_runoff_time_),
+                    is_raining);
+#endif
         }
 
         // A5. Groundwater — IGNORE_GROUNDWATER skips the coupling + solver
@@ -1501,13 +2334,7 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
         //     balance terms (accumulated inside groundwater_.execute) self-zero
         //     (legacy massbal.c:286). The auto-coupling in resolve_cross_references
         //     already forces this flag on when the model has no aquifers.
-        if (!ctx_.options.ignore_groundwater) {
-            // A5a. Assemble GW coupling (pre-compute sw_head from routing state)
-            assembleGWCoupling(dt_runoff);
-
-            // A5b. Groundwater solver (reads subcatches.gw_sw_head, not nodes directly)
-            stepGroundwater(dt_runoff);
-        }
+        // A5. Groundwater runs AFTER the LID units (A6b'), as legacy orders it.
 
         // A6. LID performance
         // A6a. Compute per-unit LID inflow from non-LID subarea runoff + rainfall.
@@ -1515,6 +2342,10 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
         //   lidInflow = (qImperv * fromImperv + qPerv * fromPerv) / lidArea
         // where qImperv/qPerv are CFS from non-LID impervious/pervious subareas.
         const auto& rsoa = runoff_.soa();
+        // Legacy VlidIn / qRunoff accumulators for this runoff step (see the
+        // volume-domain fold after A6b).
+        lid_vlidin_vol_.assign(static_cast(ctx_.n_subcatches()), 0.0);
+        lid_qsurf_cfs_.assign(static_cast(ctx_.n_subcatches()), 0.0);
         for (int t = 0; t < lid_.numGroups(); ++t) {
             auto& g = lid_.group(t);
             if (g.count == 0) continue;
@@ -1526,10 +2357,11 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                     continue;
                 }
                 auto usc = static_cast(sc);
-                // Subcatchment precipitation (ft/sec, internal units) — set by
-                // RunoffSolver from the gage AFTER applying per-subcatchment
-                // rainfall forcing and snowmelt, so the LID sees the same
-                // precip the rest of the subcatchment does (issue #102).
+                // Net precip on the LID surface in INTERNAL units (ft/s) —
+                // set by RunoffSolver::execute() earlier this step, matching
+                // legacy lidInflow += subcatch->rainfall. ctx_.gages.rainfall
+                // holds display in/hr and must not be used here (issue #131:
+                // it saturated LID soils in one step, 43200x the real rate).
                 double rain = ctx_.subcatches.rainfall[usc];
                 // Per-subarea runoff CFS from non-LID area (set by RunoffSolver, Gap #23)
                 double q_imperv = rsoa.imperv_runoff_cfs[usc];
@@ -1539,17 +2371,114 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 double captured_cfs = q_imperv * g.from_imperv[uu]
                                     + q_perv   * g.from_perv[uu];
                 double q_from_sc = (lid_area > 0.0) ? captured_cfs / lid_area : 0.0;
-                g.inflow[uu] = rain + q_from_sc;
-                // Remove the captured runon from the subcatchment outlet — that
-                // runoff is now treated by the LID, not discharged. This is the
-                // "− VlidIn" term of legacy subcatch_getRunoff() (#102 D); the
-                // LID's own surface outflow (+ VlidOut) is added back in A6b.
-                ctx_.subcatches.runoff[usc] -= captured_cfs;
+                // −VlidIn (legacy subcatch.c:746-751,
+                // `vOutflow = Voutflow − VlidIn + VlidOut`): the captured share
+                // is the LID's inflow, so it is no longer the subcatchment's
+                // outflow. Booked in legacy's exact op sequence — lid.c:1698
+                // `VlidIn += lidInflow * lidArea * tStep` with lidInflow the
+                // PRE-rain captured share — and folded back into the runoff
+                // in the VOLUME domain after A6b; subtracting captured_cfs
+                // from the runoff RATE here rounded differently (1-ULP runoff
+                // drift on every LID deck, greenville-all's pump flip at 12 h).
+                // q_imperv/q_perv already carry legacy's fOutlet scaling
+                // (Runoff.cpp), which is what keeps this deduction bounded by
+                // the outlet runoff it is removed from.
+                lid_vlidin_vol_[usc] += q_from_sc * lid_area * dt_runoff;
+                // legacy lid_getRunoff: a COVERED rain barrel takes no rain
+                // — the rain on the subcatchment's LID footprint goes back to
+                // the pervious area instead (lid.c: qReturn += rainfall *
+                // lidArea); every other unit adds the rain onto its inflow
+                // (lid.c:1712 `lidInflow = lidInflow + rainfall`).
+                if (g.type == lid::LIDType::RAIN_BARREL && g.stor_covered[uu]) {
+                    g.inflow[uu] = q_from_sc;
+                    if (usc < ctx_.subcatches.total_lid_area_ft2.size())
+                        ctx_.subcatches.lid_return_to_perv_cfs[usc] +=
+                            rain * ctx_.subcatches.total_lid_area_ft2[usc];
+                } else {
+                    g.inflow[uu] = q_from_sc + rain;
+                }
+                // Legacy lid.c:1713-1717 (5.3.0): `if (subcatch->area >=
+                // subcatch->lidArea) lidInflow += subcatch->runon;` — the
+                // test is always true for validated input (lidArea never
+                // exceeds area), so the subcatchment's run-on depth rate
+                // (over its non-LID area, or the full area when there is
+                // none) is added onto EVERY unit's inflow, partial coverage
+                // included, AFTER the rain (FP addition is not associative,
+                // so the legacy order (captured + rain) + runon must hold).
+                // 5.2.4 tested `==` (full coverage only); the pinned oracle
+                // is 5.3.0.
+                g.inflow[uu] += ctx_.subcatches.runon_rate[usc];
+                // Rain-barrel dry-time reset signal (legacy lid.c:1920 uses
+                // Subcatch.rainfall, independent of what the unit captures).
+                g.subcatch_rain[uu] = rain;
+                // A4: the age of that inflow, weighted by the same four
+                // rates. This is the only place they exist together, which
+                // is why the age is assembled here rather than in the
+                // transport module.
+                // The run-on share this unit takes (its area x the depth
+                // rate), so the age/temperature paths carry the same water
+                // the inflow above does.
+                const double q_runon_unit =
+                    ctx_.subcatches.runon_rate[usc] * lid_area;
+                transport::setLidInflowAge(
+                    ctx_, t, u, sc, rain,
+                    q_imperv * g.from_imperv[uu], q_perv * g.from_perv[uu],
+                    q_runon_unit, lid_area);
+                // H5b: the temperature of that same inflow, weighted by the
+                // same four rates.
+                transport::setLidInflowTemperature(
+                    ctx_, t, u, sc, rain,
+                    q_imperv * g.from_imperv[uu], q_perv * g.from_perv[uu],
+                    q_runon_unit, lid_area);
             }
         }
 
+        // legacy findNativeInfil: the native soil's infiltration rate a unit
+        // without its own soil layer sees (Vinfil over the non-LID area, or
+        // the subcatchment's own model when there is no pervious non-LID
+        // area) and the aquifer's ceiling on it; the subcatchment's
+        // infiltration factor for the units' Green-Ampt states; the runoff
+        // clock for pavement regeneration.
+        {
+            const int ns_l = ctx_.n_subcatches();
+            std::vector native(static_cast(ns_l), 0.0);
+            std::vector max_native(static_cast(ns_l), 1.0e10);
+            std::vector factors(static_cast(ns_l), 1.0);
+            const auto& rs = runoff_.soa();
+            for (int i = 0; i < ns_l; ++i) {
+                auto ui = static_cast(i);
+                const double lid_area = (ui < ctx_.subcatches.total_lid_area_ft2.size())
+                    ? ctx_.subcatches.total_lid_area_ft2[ui] : 0.0;
+                if (lid_area <= 0.0) continue;
+                const double non_lid = rs.area[ui];       // max(0, area - lidArea), ft2
+                if (non_lid > 0.0 && ctx_.subcatches.frac_imperv[ui] < 1.0)
+                    native[ui] = rs.infil_vol[ui] / non_lid / dt_runoff;
+                else
+                    native[ui] = runoff_.nativeInfilFullLid(ctx_, i, dt_runoff,
+                                     ctx_.climate_state.recovery_factor);
+                if (!ctx_.options.ignore_groundwater &&
+                    ctx_.subcatches.gw_aquifer[ui] >= 0 &&
+                    ctx_.subcatches.gw_max_infil_vol[ui] < 1.0e30)
+                    max_native[ui] = ctx_.subcatches.gw_max_infil_vol[ui] / dt_runoff;
+                factors[ui] = runoff_.infilFactorUsed(i);
+            }
+            lid_.setNativeInfil(std::move(native), std::move(max_native));
+            lid_.setInfilFactors(std::move(factors), ctx_.climate_state.recovery_factor);
+            lid_.setRunoffTime(old_runoff_time_);
+        }
         lid_.execute(ctx_, dt_runoff, 0.0, ctx_.climate_state.evap_rate);
 
+        // A4: LID layer ages, immediately after the depths this step
+        // produced — the same slot A3's watershed update occupies relative
+        // to the runoff solver.
+        transport::routeLidLayerAge(ctx_, lid_, dt_runoff);
+        // H5b: and the temperature column, on the same clock. Separate
+        // entry point rather than a species loop inside one routine: the
+        // two tracks differ in their operators (no aging, no zero floor, a
+        // dry-layer policy, and a coupled conduction solve), not merely in
+        // which row they write.
+        transport::routeLidLayerTemperature(ctx_, lid_, dt_runoff);
+
         // A6b. Route LID outputs back to subcatchment runoff totals
         for (int t = 0; t < lid_.numGroups(); ++t) {
             const auto& g = lid_.group(t);
@@ -1564,35 +2493,131 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                 // Surface runoff from LID (ft/sec * ft² = CFS):
                 //  to_perv==0 → goes to subcatch outlet (add to subcatch runoff CFS)
                 //  to_perv==1 → returned to pervious area next step (Gap #23)
-                if (!g.to_perv[uu]) {
-                    ctx_.subcatches.runoff[usc] += g.surface_runoff[uu] * lid_area;  // CFS
+                // legacy evalLidUnit: the return to the pervious area needs
+                // ToPerv AND a pervious non-LID area to return to (area >
+                // lidArea); the surface runoff is then always returned, the
+                // drain only when its target is the subcatchment's own outlet
+                // (validateLidGroup resolves a missing target to that outlet).
+                // A returned drain is not this step's drain flow: newDrainFlow
+                // (the hysteresis memory and the reported drain) is the value
+                // after the return.
+                const double lid_area_sc = (usc < ctx_.subcatches.total_lid_area_ft2.size())
+                    ? ctx_.subcatches.total_lid_area_ft2[usc] : 0.0;
+                const double sub_area_ft2 = ctx_.subcatches.area[usc]
+                    / ucf::UCF(ucf::LANDAREA, ctx_.options);
+                const bool can_return = g.to_perv[uu] && sub_area_ft2 > lid_area_sc;
+                if (!can_return) {
+                    // Legacy evalLidUnit accumulates qRunoff (cfs) across the
+                    // group's units; VlidOut = qRunoff*tStep enters the runoff
+                    // through the volume-domain fold below, not by adjusting
+                    // the rate per unit.
+                    lid_qsurf_cfs_[usc] += g.surface_runoff[uu] * lid_area;  // CFS
                 } else {
                     // Store as pervious return flow; consumed by RunoffSolver next step.
                     // Matches legacy lid_getFlowToPerv() one-step-lag mechanism.
                     ctx_.subcatches.lid_return_to_perv_cfs[usc] +=
                         g.surface_runoff[uu] * lid_area;  // CFS
+                    const int dn0  = g.drain_node[uu];
+                    const int dsc0 = g.drain_subcatch[uu];
+                    const bool to_outlet =
+                        (dn0 < 0 && dsc0 < 0) ||
+                        (dn0 == ctx_.subcatches.outlet_node[usc] &&
+                         dsc0 == ctx_.subcatches.outlet_subcatch[usc]);
+                    if (to_outlet) {
+                        ctx_.subcatches.lid_return_to_perv_cfs[usc] +=
+                            g.drain_flow[uu] * lid_area;
+                        lid_.group(t).drain_flow[uu] = 0.0;
+                    }
                 }
+                lid_.group(t).drain_open[uu] = (g.drain_flow[uu] > 0.0) ? 1 : 0;
                 // Drain flow (ft/sec * ft² = CFS):
                 //  drain_node >= 0        → external node inflow (lid_addDrainInflow)
                 //  drain_subcatch != self → runon to that subcatch (lid_addDrainRunon)
-                //  no target / self       → discharge to THIS subcatchment's outlet
-                //  The no-target case previously recirculated as runon-to-self,
+                //  no target / self       → the subcatchment's OWN outlet, node
+                //                           or subcatchment (legacy lid.c:1215
+                //                           assigns drainNode = outNode and
+                //                           drainSubcatch = outSubcatch at
+                //                           init when the user set neither).
+                //  The no-target case once recirculated as runon-to-self,
                 //  which double-feeds the subcatchment and leaks continuity;
-                //  EPA sends it straight to the outlet (issue #102 E).
-                if (g.drain_node[uu] >= 0) {
-                    auto un = static_cast(g.drain_node[uu]);
-                    if (un < ctx_.nodes.ext_inflow.size()) {
-                        ctx_.nodes.ext_inflow[un] += g.drain_flow[uu] * lid_area;  // CFS
+                //  then (merge a38f0c0b) it was added to subcatches.runoff,
+                //  which routed the water through the runoff channel while the
+                //  quality block below booked the same volume to the outlet
+                //  NODE — water once, quality twice, and neither temperature
+                //  nor age paired on the water side. Resolving to the outlet
+                //  here makes water and quality take the SAME path.
+                // Legacy group newDrainFlow (lid.c:1729): destination-agnostic
+                // total drain rate, rolled per runoff step so the reporter can
+                // fold interpolated drain flow into reported runoff
+                // (subcatch.c:897-902). Legacy zeroes a unit's drain when it
+                // returns to the pervious area (lid.c:1893-1898); that path is
+                // not modeled here, so the rollup matches what is routed.
+                ctx_.subcatches.lid_drain_flow[usc] +=
+                    g.drain_flow[uu] * lid_area;  // CFS
+                int dn  = g.drain_node[uu];
+                int dsc = g.drain_subcatch[uu];
+                if (dn < 0 && (dsc < 0 || dsc == sc)) {
+                    dn  = ctx_.subcatches.outlet_node[usc];
+                    dsc = ctx_.subcatches.outlet_subcatch[usc];
+                }
+                if (dn >= 0) {
+                    auto un = static_cast(dn);
+                    // NOT ext_inflow: clearInflowSources() zeroes that at the
+                    // top of every routing step, after this ran, so a drain
+                    // booked there never reached the network. See
+                    // NodeData::lid_drain_inflow.
+                    if (un < ctx_.nodes.lid_drain_inflow.size()) {
+                        ctx_.nodes.lid_drain_inflow[un] += g.drain_flow[uu] * lid_area;  // CFS
                     }
-                } else if (g.drain_subcatch[uu] >= 0 && g.drain_subcatch[uu] != sc) {
-                    auto utsc = static_cast(g.drain_subcatch[uu]);
+                } else if (dsc >= 0 && dsc != sc) {
+                    auto utsc = static_cast(dsc);
                     if (utsc < ctx_.subcatches.lid_drain_runon_cfs.size()) {
-                        ctx_.subcatches.lid_drain_runon_cfs[utsc] +=
-                            g.drain_flow[uu] * lid_area;  // CFS
+                        const double q_dr = g.drain_flow[uu] * lid_area;
+                        ctx_.subcatches.lid_drain_runon_cfs[utsc] += q_dr;
+                        // A4: and its age, so assembleRunon can hand the
+                        // rate and the q·age together.
+                        auto& wsr = ctx_.water_age_state
+                                        .subcatch_lid_drain_age_cfs;
+                        const auto& lst = ctx_.lid_layer_state;
+                        const auto uts2 = static_cast(t);
+                        if (ctx_.options.water_age && lst.active() &&
+                            utsc < wsr.size() &&
+                            uts2 + 1 < lst.group_offset.size()) {
+                            const int fl = lst.group_offset[uts2] + u;
+                            if (fl >= 0 && fl < lst.n_units)
+                                wsr[utsc] += q_dr * lst.drain_value[
+                                    static_cast(fl) *
+                                        static_cast(
+                                            lst.n_species) +
+                                    static_cast(LidSpecies::AGE)];
+                        }
+                        // H5b: the same seam for temperature — and this is
+                        // the third run-on contributor H5a carried as owed,
+                        // because a drain's temperature is a per-layer
+                        // quantity that did not exist until now. It goes
+                        // through addRunonTemperatureAt so the numerator and
+                        // the rate move together (H5a's pair invariant).
+                        if (ctx_.options.heat_transport && lst.active() &&
+                            uts2 + 1 < lst.group_offset.size()) {
+                            const int fl = lst.group_offset[uts2] + u;
+                            // Merge repair (issue #156 session, 2026-08-29):
+                            // the merged H5b block referenced `target_sc`,
+                            // which does not exist in this branch — the runon
+                            // receiver here is g.drain_subcatch[uu] (utsc).
+                            auto& hdr = ctx_.heat_state.subcatch_lid_drain_temp_cfs;
+                            if (fl >= 0 && fl < lst.n_units && utsc < hdr.size())
+                                hdr[utsc] += q_dr *
+                                    lst.drain_value[
+                                        static_cast(fl) *
+                                            static_cast(
+                                                lst.n_species) +
+                                        static_cast(
+                                            LidSpecies::TEMPERATURE)];
+                        }
                     }
-                } else {
-                    ctx_.subcatches.runoff[usc] += g.drain_flow[uu] * lid_area;  // CFS
                 }
+                // (A subcatchment with neither an outlet node nor an outlet
+                //  subcatchment drops its runoff too; the drain follows it.)
 
                 // Gap #26: LID drain quality routing.
                 // The drain carries source-subcatch quality, reduced by drainRmvl.
@@ -1606,7 +2631,16 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                     int np_lid = g.n_pollutants;
                     int np_use = std::min(np_ctx, np_lid);
                     // IGNORE_QUALITY: no LID drain pollutant loads (runoff.c:274).
-                    if (np_use > 0 && g.drain_flow[uu] > 0.0
+                    // A4: water age joins the guard. Gated on np_use alone,
+                    // a pure-age model never accumulated the drain volume at
+                    // all, so neither the water nor its age reached the node
+                    // — the np-guard family once more.
+                    // LID fix round: heat joins the guard for the same
+                    // reason age did — the drain's temperature is paired
+                    // inside this block, so a heat-only deck must reach it.
+                    if ((np_use > 0 || ctx_.options.water_age ||
+                         ctx_.options.heat_transport)
+                        && g.drain_flow[uu] > 0.0
                         && !ctx_.options.ignore_quality) {
                         double drain_cfs = g.drain_flow[uu] * lid_area;
                         // Determine destination node index
@@ -1624,6 +2658,56 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                             // Add drain volume to node quality vol accumulator
                             if (udn < ctx_.nodes.lid_drain_qual_vol.size())
                                 ctx_.nodes.lid_drain_qual_vol[udn] += drain_cfs;
+                            // A4: and its age, as the usual q·age rate. The
+                            // drain draws from the storage layer (decision
+                            // 2026-08-18), which is what drain_value holds.
+                            if (ctx_.options.water_age) {
+                                const auto& lst = ctx_.lid_layer_state;
+                                const auto uts = static_cast(t);
+                                if (lst.active() &&
+                                    uts + 1 < lst.group_offset.size()) {
+                                    const int flat = lst.group_offset[uts] + u;
+                                    const auto ai =
+                                        static_cast(flat) *
+                                            static_cast(
+                                                lst.n_species) +
+                                        static_cast(
+                                            LidSpecies::AGE);
+                                    if (flat >= 0 && flat < lst.n_units &&
+                                        udn < ctx_.water_age_state
+                                                  .node_lid_drain_age_vol_in
+                                                  .size())
+                                        ctx_.water_age_state
+                                            .node_lid_drain_age_vol_in[udn] +=
+                                            drain_cfs * lst.drain_value[ai];
+                                }
+                            }
+                            // H5b pairing at the NODE seam: the drain leaves
+                            // at the storage layer's temperature, booked as
+                            // the usual q·T rate beside its age. Consumed by
+                            // the wet-weather loader in place of the RAINFALL
+                            // stand-in it used until the LID fix round.
+                            if (ctx_.options.heat_transport) {
+                                const auto& lst = ctx_.lid_layer_state;
+                                const auto uts = static_cast(t);
+                                if (lst.active() &&
+                                    uts + 1 < lst.group_offset.size()) {
+                                    const int flat = lst.group_offset[uts] + u;
+                                    const auto ti =
+                                        static_cast(flat) *
+                                            static_cast(
+                                                lst.n_species) +
+                                        static_cast(
+                                            LidSpecies::TEMPERATURE);
+                                    if (flat >= 0 && flat < lst.n_units &&
+                                        udn < ctx_.heat_state
+                                                  .node_lid_drain_temp_vol_in
+                                                  .size())
+                                        ctx_.heat_state
+                                            .node_lid_drain_temp_vol_in[udn] +=
+                                            drain_cfs * lst.drain_value[ti];
+                                }
+                            }
                             // Add drain mass load per pollutant
                             for (int p = 0; p < np_use; ++p) {
                                 auto rmvl_idx = static_cast(u * np_lid + p);
@@ -1637,6 +2721,53 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                                 if (nd_idx < ctx_.nodes.lid_drain_qual_load.size())
                                     ctx_.nodes.lid_drain_qual_load[nd_idx] +=
                                         drain_cfs * c_src * (1.0 - rmvl);
+
+                                // legacy lid_addDrainLoads (lid.c:1505-1516).
+                                // v6 routed the drain's load to the node but
+                                // never booked its LEDGER half, which only
+                                // showed once bookWashoffLoads narrowed the
+                                // Surface Runoff row to the surface volume:
+                                // the drain share would otherwise vanish from
+                                // the ledger entirely. A unit whose drain is
+                                // returned to the pervious area sheds no
+                                // external load at all (legacy's `!toPerv`).
+                                if (!g.to_perv[uu]) {
+                                    const double mass_ucf_d =
+                                        ucf::UCF(ucf::MASS, ctx_.options);
+                                    double mcf_d = mass_ucf_d;
+                                    auto upd = static_cast(p);
+                                    if (upd < ctx_.pollutants.units.size()) {
+                                        switch (ctx_.pollutants.units[upd]) {
+                                            case MassUnits::UG_PER_L:
+                                                mcf_d = mass_ucf_d / 1000.0; break;
+                                            case MassUnits::COUNTS_PER_L:
+                                                mcf_d = 1.0; break;
+                                            default: break;
+                                        }
+                                    }
+                                    // c_src is mg/L, so LperFT3 brings
+                                    // cfs·mg/L·s to concentration mass.
+                                    const double w = drain_cfs * c_src *
+                                                     dt_runoff * 28.317 * mcf_d;
+                                    if (w > 0.0) {
+                                        if (upd < ctx_.mass_balance
+                                                      .qual_bmp_removal.size())
+                                            ctx_.mass_balance
+                                                .qual_bmp_removal[upd] += rmvl * w;
+                                        // "isRunoffLoad": the drain reaches
+                                        // the system only when it has a node,
+                                        // or returns to its own subcatchment.
+                                        const bool is_runoff_load =
+                                            (g.drain_node[uu] >= 0 ||
+                                             g.drain_subcatch[uu] == sc);
+                                        if (is_runoff_load &&
+                                            upd < ctx_.mass_balance
+                                                      .qual_runoff_load.size())
+                                            ctx_.mass_balance
+                                                .qual_runoff_load[upd] +=
+                                                w * (1.0 - rmvl);
+                                    }
+                                }
                             }
                         }
                     }
@@ -1644,10 +2775,47 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
             }
         }
 
+        // A6b''. Volume-domain runoff fold for LID subcatchments — legacy
+        // subcatch.c:746-751 verbatim:
+        //     vOutflow = Voutflow      // runoff from all non-LID areas
+        //                - VlidIn      // runoff treated by LID units
+        //                + VlidOut;    // runoff from LID units
+        //     Subcatch[j].newRunoff = vOutflow / tStep;
+        // with VlidOut = qRunoff * tStep (lid.c:1733). Non-LID subcatchments
+        // keep the solver's Voutflow/dt bytes untouched.
+        if (dt_runoff > 0.0) {
+            for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+                auto ui = static_cast(i);
+                if (ui >= ctx_.subcatches.total_lid_area_ft2.size() ||
+                    ctx_.subcatches.total_lid_area_ft2[ui] <= 0.0) continue;
+                const double v_lid_out = lid_qsurf_cfs_[ui] * dt_runoff;
+                const double v_outflow =
+                    rsoa.outflow_vol[ui] - lid_vlidin_vol_[ui] + v_lid_out;
+                ctx_.subcatches.runoff[ui] = v_outflow / dt_runoff;
+            }
+        }
+
+        // A6b'. Groundwater — AFTER the LID units, as legacy subcatch_getRunoff
+        // orders it (lid_getRunoff then gwater_getGroundwater, subcatch.c:
+        // 730-738): the aquifer receives the LID units' infiltration and
+        // pervious evaporation of this step, and the LID units' native-
+        // infiltration ceiling (maxInfilVol) is the PREVIOUS step's, exactly
+        // as findNativeInfil reads it.
+        if (!ctx_.options.ignore_groundwater) {
+            // A5a. Assemble GW coupling (pre-compute sw_head from routing state)
+            assembleGWCoupling(dt_runoff);
+            // A5b. Groundwater solver (reads subcatches.gw_sw_head, not nodes directly)
+            stepGroundwater(dt_runoff);
+        }
+
         // A6c. Accumulate runoff mass-balance totals now that the LID routing
         // has finalised subcatches.runoff (moved from A4b — see note there).
         accumulateRunoffMassBalance(dt_runoff);
 
+        // A6c'. The QUALITY half of the same deferral: legacy books the
+        // washoff mass against the POST-LID volumes, which only exist here.
+        if (!ctx_.options.ignore_quality) bookWashoffLoads(dt_runoff);
+
         // A7. Street sweeping buildup removal (Gap #34)
         // Matches legacy surfqual_sweepBuildup(): per-(subcatch, landuse)
         // last-swept tracking so each subcatchment sweeps on its own schedule.
@@ -1655,7 +2823,7 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
             int np  = ctx_.n_pollutants();
             int nlu = ctx_.n_landuses();
             // IGNORE_QUALITY: skip street-sweeping buildup removal (runoff.c:274).
-            if (np > 0 && nlu > 0 && !is_raining
+            if ((np > 0 || msxsurf::active(ctx_)) && nlu > 0
                 && !ctx_.options.ignore_quality) {
                 int sweep_doy = datetime::dayOfYear(abs_time);
                 int ss = ctx_.options.sweep_start;
@@ -1664,14 +2832,36 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                     ? (sweep_doy >= ss && sweep_doy <= se)
                     : (sweep_doy >= ss || sweep_doy <= se);
 
-                if (in_season) {
+                // The clock advances in CALENDAR time. legacy's test is
+                // `aDate - lastSwept >= interval` (surfqual.c:228) — real
+                // dates, so a sweep can come due DURING a storm or out of
+                // season and fire at the next eligible step. This
+                // accumulator only advanced on eligible steps, so every
+                // rainy or off-season day pushed the whole schedule back.
+                {
                     double dt_days = dt_runoff / ucf::SEC_PER_DAY;
+                    for (auto& d : ctx_.subcatches.sweep_last_swept)
+                        d += dt_days;
+                }
+
+                if (in_season) {
                     int nlu_sz = static_cast(ctx_.subcatches.sweep_last_swept.size())
                                  / std::max(ctx_.n_subcatches(), 1);
+                    // legacy MIN_RUNOFF (consts.h): 2.31481e-8 ft/s = 0.001 in/hr.
+                    constexpr double MIN_RUNOFF_FTS = 2.31481e-8;
 
                     for (int i = 0; i < ctx_.n_subcatches(); ++i) {
                         auto ui = static_cast(i);
 
+                        // legacy runoff.c:284 gates on the SUBCATCHMENT's own
+                        // rainfall, `Subcatch[j].rainfall <= MIN_RUNOFF` — not
+                        // on "any gage raining". A subcatchment whose gage is
+                        // dry sweeps while another's storm runs, and a drizzle
+                        // below MIN_RUNOFF still permits sweeping.
+                        if (ui < ctx_.subcatches.rainfall.size() &&
+                            ctx_.subcatches.rainfall[ui] > MIN_RUNOFF_FTS)
+                            continue;
+
                         // Skip subcatchment if snow on plowable impervious area.
                         // Matches legacy: if (snowpack->wsnow[IMPERV0] > MIN_TOTAL_DEPTH) return;
                         int sp = ctx_.subcatches.snowpack[ui];
@@ -1696,11 +2886,17 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                                               std::max(nlu_sz, nlu)) + ulu;
                             if (sw_idx >= ctx_.subcatches.sweep_last_swept.size()) continue;
 
-                            ctx_.subcatches.sweep_last_swept[sw_idx] += dt_days;
                             if (ctx_.subcatches.sweep_last_swept[sw_idx] < interval) continue;
                             ctx_.subcatches.sweep_last_swept[sw_idx] = 0.0;
 
-                            double removal_frac = ctx_.landuses.sweep_removal[ulu] / 100.0;
+                            // legacy sweepRemoval is the [LANDUSES] Availability
+                            // column read RAW — a fraction (landuse.c:70). Only
+                            // the [WASHOFF] sweeping efficiency is a percent,
+                            // divided by 100 below. The /100 here removed 200x
+                            // too little on the sweeps that did fire.
+                            double removal_frac = ctx_.landuses.sweep_removal[ulu];
+                            // BW-MSX: same event, same fractions, MSX store.
+                            msxsurf::sweep(ctx_, i, lu, frac, removal_frac);
                             for (int p = 0; p < np; ++p) {
                                 auto k = static_cast(lu * np + p);
                                 double effic = landuse_solver_.washoff_params[k].sweep_effic / 100.0;
@@ -1710,11 +2906,19 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
                                     ? frac * ctx_.subcatches.area[ui]
                                     : frac * ctx_.subcatches.curb_length[ui];
                                 double old_bu = surface_quality_.buildup[bu];
-                                double removed = old_bu * removal_frac * effic;
-                                surface_quality_.buildup[bu] =
-                                    std::max(old_bu - removed, 0.0);
+                                // legacy surfqual_sweepBuildup (surfqual.c:
+                                // 236-242): clamp the new store into [0, old]
+                                // FIRST and book the clamped difference, so
+                                // the ledger closes even when removal_frac *
+                                // effic falls outside [0, 1].
+                                double new_bu =
+                                    old_bu * (1.0 - removal_frac * effic);
+                                new_bu = std::min(old_bu, new_bu);
+                                new_bu = std::max(0.0, new_bu);
+                                surface_quality_.buildup[bu] = new_bu;
                                 ctx_.mass_balance.qual_sweeping[
-                                    static_cast(p)] += removed * norm;
+                                    static_cast(p)] +=
+                                    (old_bu - new_bu) * norm;
                             }
                         }
                     }
@@ -1722,8 +2926,6 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
             }
         }
 
-        // A8. Subcatchment-to-subcatchment + outfall runon → runon_inflow[]
-        assembleRunon(dt_runoff);
     }
 
     // --- Phase 2: Interpolate runoff & GW to decomposed node inflow arrays ---
@@ -1744,6 +2946,10 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
     double f = (span > 0.0) ? (ctx_.elapsed_ms - old_runoff_ms_) / span : 1.0;
     if (f < 0.0) f = 0.0;
     if (f > 1.0) f = 1.0;
+    // Publish it: the quality loaders weight the washoff load with the SAME
+    // number legacy weights the runoff flow with, one line apart in
+    // addWetWeatherInflows. They had been assuming a midpoint.
+    ctx_.runoff_interp_f = f;
 
     // Zero decomposed node inflow arrays before accumulating from subcatchments.
     // Multiple subcatchments may drain to the same node, so we must use += below,
@@ -1758,19 +2964,63 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
     const auto un_sub = static_cast(ctx_.n_subcatches());
     wet_q_interp_.assign(un_sub, 0.0);
     gw_q_interp_.assign(un_sub, 0.0);
+    if (old_gw_rate_.size() != un_sub) old_gw_rate_.resize(un_sub, 0.0);
     gw_q_node_.assign(un_sub, -1);
+    // legacy addLidDrainInflows → lid_addDrainInflow: each unit's drain flow
+    // to a node is (1-f)*oldDrainFlow + f*newDrainFlow (cfs, both already
+    // scaled by the unit footprint), on the same runoff-clock weight as the
+    // wet-weather inflow, added per unit. Before this the runoff step's
+    // un-interpolated drain was added at every routing step in between.
+    lid_drain_q_interp_.assign(static_cast(ctx_.n_nodes()), 0.0);
+    for (int t = 0; t < lid_.numGroups(); ++t) {
+        const auto& g = lid_.group(t);
+        for (int u = 0; u < g.count; ++u) {
+            auto uu = static_cast(u);
+            const int sc = g.subcatch_idx[uu];
+            if (sc < 0 || sc >= ctx_.n_subcatches()) continue;
+            const auto usc = static_cast(sc);
+            int dn = g.drain_node[uu];
+            const int dsc = g.drain_subcatch[uu];
+            if (dn < 0 && (dsc < 0 || dsc == sc)) dn = ctx_.subcatches.outlet_node[usc];
+            if (dn < 0 || dn >= ctx_.n_nodes()) continue;
+            const double q_old = g.old_drain_flow[uu] * g.area[uu];
+            const double q_new = g.drain_flow[uu] * g.area[uu];
+            lid_drain_q_interp_[static_cast(dn)] +=
+                (1.0 - f) * q_old + f * q_new;
+        }
+    }
 
     for (int i = 0; i < ctx_.n_subcatches(); ++i) {
         auto ui = static_cast(i);
         if (ctx_.subcatches.area[ui] <= 0.0) continue;
 
-        // Interpolated runoff rate including runon from upstream subcatchments.
-        // (matching legacy subcatch_getWtdOutflow)
-        double q_runoff = (1.0 - f) * ctx_.subcatches.old_runoff[ui]
-                        +        f  * ctx_.subcatches.runoff[ui];
-        double q_runon  = (1.0 - f) * ctx_.subcatches.old_runon_inflow[ui]
-                        +        f  * ctx_.subcatches.runon_inflow[ui];
-        double q = q_runoff + q_runon;
+        // Interpolated runoff rate. RUN-ON IS NOT ADDED HERE: it is already
+        // inside `runoff[]`.
+        //
+        // `assembleRunon` sums every run-on contributor into
+        // `runon_inflow[]` — subcatchment-to-subcatchment, LID drain
+        // (Gap #25) and outfall return (Gap #28) — and `Runoff.cpp:333`
+        // consumes that array WHOLESALE as an inflow rate:
+        // `precip += runon_q / total_area`. Whatever went in comes back out
+        // in `runoff[]`, so adding `q_runon` again at the node booked the
+        // same water twice.
+        //
+        // The per-contributor question is answered uniformly, and that is
+        // why: the solver does not distinguish where a contribution came
+        // from, it reads one lump. `total_area` there is `soa_.area[ui]`,
+        // the same area this loop already guards on, so there is no
+        // subcatchment that receives run-on and fails to consume it.
+        //
+        // Legacy is unambiguous — `subcatch_getWtdOutflow` is
+        // `(1-f)*oldRunoff + f*newRunoff` and nothing else. Measured:
+        // cascade 0.511 acre-feet against legacy's 0.218, three-deep 0.536
+        // against 0.318; the excess on cascade is 0.293 against the donor's
+        // own runoff of 0.294. The conveyance was receiving 2.3× what our
+        // own runoff ledger said left the surface — and NEITHER continuity
+        // check noticed, because each balance was self-consistent on its own
+        // side of the seam.
+        double q = (1.0 - f) * ctx_.subcatches.old_runoff[ui]
+                 +        f  * ctx_.subcatches.runoff[ui];
 
         // Scatter to decomposed runoff inflow array
         int out_node = ctx_.subcatches.outlet_node[ui];
@@ -1783,9 +3033,22 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
         int gw_node = ctx_.subcatches.gw_node[ui];
         if (gw_node < 0) gw_node = ctx_.subcatches.outlet_node[ui];
         if (gw_node >= 0 && gw_node < ctx_.n_nodes()) {
-            double gw_q = (1.0 - f) * ctx_.subcatches.old_gw_flow[ui]
-                        +        f  * ctx_.subcatches.gw_flow[ui];
-            if (std::fabs(gw_q) > 1.0e-6) {
+            // PARITY routing.c:766 `q = ((1-f)*gw->oldFlow + f*gw->newFlow)
+            // * Subcatch[i].area`: legacy interpolates the per-unit-area RATE
+            // and multiplies by the area LAST. v6 interpolated the cfs
+            // products — a 1-ULP different number that seeded usgs-runoff's
+            // divergence at routing step 2 and grew from there.
+            const double area_ft2 = ctx_.subcatches.area[ui]
+                                  / ucf::UCF(ucf::LANDAREA, ctx_.options);
+            const double gw_rate_new = (ui < groundwater_.state().gw_flow.size())
+                                     ? groundwater_.state().gw_flow[ui] : 0.0;
+            const double gw_rate_old = (ui < old_gw_rate_.size())
+                                     ? old_gw_rate_[ui] : 0.0;
+            double gw_q = ((1.0 - f) * gw_rate_old + f * gw_rate_new) * area_ft2;
+            // PARITY routing.c addGroundwaterInflows:
+            // `if (fabs(q) < FLOW_TOL) continue;` — FLOW_TOL is 1e-5 cfs
+            // (consts.h), not the 1e-6 this used to carry.
+            if (std::fabs(gw_q) >= constants::FLOW_TOL) {
                 ctx_.nodes.gw_inflow[static_cast(gw_node)] += gw_q;
                 gw_q_interp_[ui] = gw_q;
                 gw_q_node_[ui]   = gw_node;
@@ -1810,6 +3073,55 @@ void SWMMEngine::stepRunoff(double dt_routing) noexcept {
  * @param has_snow     True if any subcatchment has snow depth > 0.
  * @returns Runoff timestep in seconds.
  */
+// legacy climate.c setNextEvapDate(theDate): when the current NextEvapDate has
+// been reached, find when the evaporation source next changes.
+void SWMMEngine::setNextEvapDate(double the_date) noexcept {
+    auto& cs = ctx_.climate_state;
+    if (cs.next_evap_date > the_date) return;
+    switch (cs.evap_method) {
+        case climate::EvapMethod::CONSTANT:
+            cs.next_evap_date = the_date + 365.;
+            break;
+        case climate::EvapMethod::MONTHLY: {
+            int yr, mon, day;
+            datetime::decodeDate(the_date, yr, mon, day);
+            if (mon == 12) { mon = 1; yr++; }
+            else mon++;
+            cs.next_evap_date = datetime::encodeDate(yr, mon, 1);
+            break;
+        }
+        case climate::EvapMethod::TIMESERIES: {
+            cs.next_evap_date = the_date + 365.;
+            if (cs.evap_ts_index >= 0) {
+                const auto& tbl = ctx_.tables.tables[static_cast(cs.evap_ts_index)];
+                const int n = static_cast(tbl.x.size());
+                const double end_date = datetime::addSeconds(
+                    ctx_.options.start_date, ctx_.options.totalDurationMs() / 1000.0);
+                int pos = cs.evap_ts_pos;
+                while (pos + 1 < n) {
+                    ++pos;
+                    const double d = tbl.x[static_cast(pos)];
+                    const double e = tbl.y[static_cast(pos)];
+                    if (d > end_date) break;
+                    if (d >= the_date) {
+                        cs.next_evap_date = d;
+                        cs.next_evap_rate = e;
+                        break;
+                    }
+                }
+                cs.evap_ts_pos = pos;
+            }
+            break;
+        }
+        case climate::EvapMethod::PAN:
+            cs.next_evap_date = std::floor(the_date) + 1.0;
+            break;
+        default:
+            cs.next_evap_date = the_date + 365.;
+            break;
+    }
+}
+
 double SWMMEngine::computeRunoffTimestep(double abs_time, bool is_raining,
                                          bool has_runoff, bool has_snow) noexcept {
     // Matches legacy runoff_getTimeStep() exactly:
@@ -1820,54 +3132,25 @@ double SWMMEngine::computeRunoffTimestep(double abs_time, bool is_raining,
     //   5. Return min(wet/dry step, maxStep)
     long max_step = static_cast(ctx_.options.dry_step);
 
+    // legacy runoff_getTimeStep: never step past the next evaporation change
+    {
+        const long to_evap = datetime::timeDiff(ctx_.climate_state.next_evap_date, abs_time);
+        if (to_evap > 0 && to_evap < max_step) max_step = to_evap;
+    }
+
     // Shorten to next rain gage boundary
     // (matching legacy gage_getNextRainDate)
     for (int g = 0; g < ctx_.n_gages(); ++g) {
-        auto ug = static_cast(g);
-
-        // Select the gage's rain series the same way updateAllGages() does:
-        // a FILE_RAIN gage reads from its own resolved rain_series (built by
-        // load_external_rain_files and NOT present in the shared tables pool),
-        // while a TIMESERIES gage reads from tables[ts_index].  Using only
-        // ts_index here skipped every file gage (ts_index == -1), so the runoff
-        // step was never shortened to a file gage's rain-interval boundary —
-        // dry_step then overshot rain-burst onsets and dropped rainfall.
-        // Matches legacy gage_getNextRainDate(), which snaps for all gages.
-        Table* rtbl = nullptr;
-        int ts_idx = ctx_.gages.ts_index[ug];
-        if (ctx_.gages.source[ug] == RainSource::FILE_RAIN) {
-            if (ug < ctx_.gages.rain_series.size() &&
-                !ctx_.gages.rain_series[ug].empty())
-                rtbl = &ctx_.gages.rain_series[ug];
-        } else if (ts_idx >= 0 && ts_idx < static_cast(ctx_.tables.tables.size())) {
-            rtbl = &ctx_.tables.tables[static_cast(ts_idx)];
-        }
-        if (!rtbl) continue;
-        auto& tbl = *rtbl;
-        int idx = tbl.cursor.index;
-        int n = static_cast(tbl.x.size());
-        if (idx < 0 || idx >= n) continue;
-
-        // gage_getNextRainDate logic:
-        // - If before startDate: return startDate
-        // - If before endDate: return endDate
-        // - Otherwise: return nextDate
-        double interval_sec = ctx_.gages.interval_sec[ug];
-        double entry_start = tbl.x[static_cast(idx)];
-        double entry_end = datetime::addSeconds(entry_start, interval_sec);
-        double t_shifted = abs_time + datetime::OneSecond;
-
-        double next_rain_date;
-        if (t_shifted < entry_start) {
-            next_rain_date = entry_start;
-        } else if (t_shifted < entry_end) {
-            next_rain_date = entry_end;
-        } else if (idx + 1 < n) {
-            next_rain_date = tbl.x[static_cast(idx + 1)];
-        } else {
-            continue; // No more data
-        }
-
+        // legacy gage_getNextRainDate on the gage's state machine as this
+        // step's updateAllGages left it (Gage.cpp): the current interval's
+        // start or end, else the next NON-ZERO record — getNextRainfall
+        // skips explicit zeros, so a dry spell written as zeros no longer
+        // holds the runoff step at the recording interval (runoff11-regen-
+        // sw5, hec-hms-hyetographs); the first record seeds the state
+        // whatever its value (runoff25a-sw5's lone zero record limits the
+        // first step to its interval); an unused gage returns the date
+        // itself; NO_DATE gives a negative difference and no limit.
+        const double next_rain_date = gage::gageNextRainDate(ctx_, g, abs_time);
         long secs_to_change = datetime::timeDiff(next_rain_date, abs_time);
         if (secs_to_change > 0 && secs_to_change < max_step)
             max_step = secs_to_change;
@@ -1875,7 +3158,10 @@ double SWMMEngine::computeRunoffTimestep(double abs_time, bool is_raining,
 
     // Choose wet or dry step based on conditions
     long time_step;
-    if (is_raining || has_snow || has_runoff)
+    // legacy runoff_getTimeStep: the WET step also while any LID unit is wet
+    // (HasWetLids, set by lidproc_saveResults when a unit's inflow, outflow,
+    // drain, exfiltration or evaporation exceeded MINFLOW).
+    if (is_raining || has_snow || has_runoff || lid_.anyWet())
         time_step = static_cast(ctx_.options.wet_step);
     else
         time_step = static_cast(ctx_.options.dry_step);
@@ -1948,9 +3234,35 @@ void SWMMEngine::accumulateRunoffMassBalance(double dt_runoff) noexcept {
         ctx_.mass_balance.runoff_infil +=
             ctx_.subcatches.infil_loss[ui] * nonlid_area_ft2 * dt_runoff;
 
-        // Surface runoff volume (ft³) — runoff is cfs
-        ctx_.mass_balance.runoff_runoff +=
-            ctx_.subcatches.runoff[ui] * dt_runoff;
+        // Surface runoff volume (ft³) — runoff is cfs.
+        //
+        // ONLY when the outlet is a drainage-system node. A subcatchment that
+        // sheds onto another subcatchment has not left the runoff system: its
+        // water arrives as run-on and is counted again when the receiver
+        // discharges. Adding it here books the same water twice and the
+        // ledger reads a system output that never happened — measured on
+        // tests/parity/transport/age_legacy.inp, whose S1 drains onto S2:
+        // runoff continuity −23.667 % against legacy's −0.271 %, precipitation
+        // and infiltration agreeing to the digit and only runoff differing,
+        // by S1's own 1.628 in.
+        //
+        // Legacy guards exactly this (subcatch.c:761-765): `outNode == -1 &&
+        // outSubcatch != subcatchIndex` zeroes vOutflow before
+        // massbal_updateRunoffTotals. The self-outlet exclusion matters —
+        // a subcatchment routed to ITSELF is a real system output, not a
+        // cascade.
+        //
+        // This is a LEDGER term only: runoff_runoff is read by the continuity
+        // total, the report row and the mass-balance API, and by nothing that
+        // routes water. The routed hydrology and every .out column are
+        // unaffected.
+        const bool sheds_to_node = ctx_.subcatches.outlet_node[ui] >= 0;
+        const bool sheds_to_self =
+            ctx_.subcatches.outlet_subcatch[ui] == i;
+        if (sheds_to_node || sheds_to_self) {
+            ctx_.mass_balance.runoff_runoff +=
+                ctx_.subcatches.runoff[ui] * dt_runoff;
+        }
 
         // Subcatchment-level statistics
         if (ctx_.subcatches.runoff[ui] > ctx_.subcatches.stat_max_runoff[ui])
@@ -1961,17 +3273,31 @@ void SWMMEngine::accumulateRunoffMassBalance(double dt_runoff) noexcept {
             ctx_.subcatches.runoff[ui] * dt_runoff;
     }
 
-    // Fold this step's LID exfiltration / evaporation into the runoff-continuity
-    // infil / evap outflow terms (legacy VlidInfil / VlidEvap in subcatch.c).
-    // The LID solver tracks cumulative wb_infil/wb_evap; add the delta since the
-    // previous runoff step. Without this a LID with storage-layer exfiltration
-    // (STORAGE Ksat > 0) loses water that never appears as a continuity outflow.
-    double lid_infil_vol = lid_.totalInfilVolume();
-    double lid_evap_vol  = lid_.totalEvapVolume();
-    ctx_.mass_balance.runoff_infil += (lid_infil_vol - prev_lid_infil_vol_);
-    ctx_.mass_balance.runoff_evap  += (lid_evap_vol  - prev_lid_evap_vol_);
-    prev_lid_infil_vol_ = lid_infil_vol;
-    prev_lid_evap_vol_  = lid_evap_vol;
+    // LID unit losses belong in the runoff mass balance — legacy
+    // evalLidUnit() adds lidEvap/lidInfil × lidArea to the runoff totals
+    // (lid.c:1912-1913). Without them, rain captured by LID units reads as
+    // a runoff continuity error once the LID footprint is excluded from
+    // runoff generation (issue #131). evap_loss/infil_loss are per-step
+    // loss depths (ft).
+    for (int t = 0; t < lid_.numGroups(); ++t) {
+        const auto& g = lid_.group(t);
+        for (int u = 0; u < g.count; ++u) {
+            auto uu = static_cast(u);
+            ctx_.mass_balance.runoff_evap  += g.evap_loss[uu] * g.area[uu];
+            ctx_.mass_balance.runoff_infil += g.infil_loss[uu] * g.area[uu];
+        }
+    }
+
+    // LID drain flow discharged to a NODE has left the runoff system — the
+    // legacy RUNOFF_DRAINS term (evalLidUnit books it only when
+    // drainNode >= 0; drains onto another subcatchment stay internal and are
+    // counted when the receiver sheds). nodes.lid_drain_inflow holds exactly
+    // that set for this runoff step. Without this term the ledger sprang a
+    // hole the size of the drain the moment the water stopped riding
+    // subcatches.runoff (LID fix round, 2026-08-30).
+    double lid_drain_cfs = 0.0;
+    for (double q : ctx_.nodes.lid_drain_inflow) lid_drain_cfs += q;
+    ctx_.mass_balance.runoff_lid_drain += lid_drain_cfs * dt_runoff;
 }
 
 // ============================================================================
@@ -2060,7 +3386,12 @@ int SWMMEngine::refreshTreatment(int node_idx, int pollut_idx) noexcept {
         ctx_.treatment.compiled[idx] = treatment::TreatExpr{};
     } else {
         treatment::TreatExpr te;
-        rc = treatment::parse(expr_str, te);
+        // Resolve pollutant references against the deck's own names: a bare
+        // pollutant name is legacy's second lookup (treatmnt.c:313) and R_xxx
+        // its third. The lookup-less overload used here compiled neither, so
+        // an expression naming a pollutant produced an EMPTY token list and
+        // the treatment was skipped without any error.
+        rc = treatment::parse(expr_str, te, ctx_.pollutant_names.names());
         if (rc == 0) {
             te.pollutant_idx = pollut_idx;
             ctx_.treatment.compiled[idx] = std::move(te);
@@ -2170,21 +3501,103 @@ void SWMMEngine::refreshAquiferParams() noexcept {
  */
 void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
     //      Matching legacy surfqual_getBuildup + surfqual_getWashoff
-    if (ctx_.n_pollutants() > 0 && ctx_.n_landuses() > 0) {
+    // legacy surfqual_getWashoff (surfqual.c:283-286) returns only on
+    //     Nobjects[POLLUT] == 0 || area <= 0.0
+    // — there is NO land-use condition, and there must not be one here. Only
+    // findWashoffLoads needs a land use; findPondedLoads does not, and that is
+    // where WET DEPOSITION lives: rainfall carrying Pollut[p].pptConcen onto
+    // the surface (surfqual.c:428), which a deck can have with no [LANDUSES]
+    // at all. Requiring a land use skipped the whole step for those decks, so
+    // they ran with zero pollutant from any source and reported a 0.000 %
+    // runoff-quality continuity error over it — lid1d books 263,134 kg of COD
+    // deposition in legacy and 0.000 here. The land-use loop below is already
+    // correct at nlu == 0: it simply does not execute, exactly as legacy's
+    // findWashoffLoads contributes nothing without coverages.
+    if (ctx_.n_pollutants() > 0) {
         int np = ctx_.n_pollutants();
         int nlu = ctx_.n_landuses();
-        constexpr double MIN_RUNOFF_RATE = 1.0e-9; // ft/sec threshold
+        // legacy consts.h MIN_RUNOFF: 2.31481e-8 ft/sec = 0.001 in/hr.
+        constexpr double MIN_RUNOFF_FTS = 2.31481e-8;
         double dt_days = dt_runoff / ucf::SEC_PER_DAY;
 
+        const double ucf_landarea_sq = ucf::UCF(ucf::LANDAREA, ctx_.options);
         for (int i = 0; i < ctx_.n_subcatches(); ++i) {
             auto ui = static_cast(i);
+            // `q` is legacy's Voutflow / tStep — the PRE-LID runoff volume
+            // rate. stepSurfaceQuality runs before the LID block subtracts
+            // the captured share (A4c precedes A6), exactly as legacy's
+            // surfqual_getWashoff reads the Voutflow accumulated by
+            // subcatch_getRunoff.
             double q = ctx_.subcatches.runoff[ui];  // cfs
             double area_ac = ctx_.subcatches.area[ui]; // acres
+            const double area_ft2_sc = area_ac / ucf_landarea_sq;
+
+            // legacy's `runoff` argument to findWashoffLoads /
+            // landuse_getWashoffQual: the area-averaged subarea runoff RATE
+            // in ft/sec (subcatch_getRunoff's return, `runoff / area`), which
+            // carries NO fOutlet and no LID adjustment. Using Voutflow/area
+            // instead understates it on any deck with inter-subarea routing.
+            const double runoff_fts = (ui < ctx_.subcatches.subarea_runoff_rate.size())
+                                    ? ctx_.subcatches.subarea_runoff_rate[ui] : 0.0;
+
+            // legacy surfqual_getWashoff (surfqual.c:305-316): the washoff
+            // CONCENTRATION denominator is the pre-LID inflow volume
+            //     vOut1 = Voutflow + vLidRain + vLidRunon
+            // — rain landing on the LID footprint, and the subcatchment's
+            // run-on when the units cover it entirely, are water that dilutes
+            // the washoff without carrying any of it. v6 divided by the
+            // runoff alone, so a fully LID-covered subcatchment reported its
+            // undiluted EMC: variations-on-emc's wRG_O_100 read a flat
+            // 100 mg/L where legacy ramps 60 -> 84 -> 92 -> 95 as surface
+            // runoff grows against the rain on the rain garden.
+            double q_out1 = q;
+            {
+                const double lid_ft2_sc = (ui < ctx_.subcatches.total_lid_area_ft2.size())
+                                        ? ctx_.subcatches.total_lid_area_ft2[ui] : 0.0;
+                if (lid_ft2_sc > 0.0) {
+                    q_out1 += ctx_.subcatches.rainfall[ui] * lid_ft2_sc;
+                    if (area_ft2_sc == lid_ft2_sc)
+                        q_out1 += ctx_.subcatches.runon_rate[ui] * area_ft2_sc;
+                }
+            }
+            // Keep vOut1 for bookWashoffLoads. By the time the mass bookings
+            // can be made the LID units have run and `runoff` is the POST-LID
+            // value, so this is the last moment the pre-LID volume exists.
+            if (ui < ctx_.subcatches.washoff_vout1.size())
+                ctx_.subcatches.washoff_vout1[ui] = q_out1 * dt_runoff;
 
             for (int p = 0; p < np; ++p) {
                 auto sq_idx = ui * static_cast(np)
                               + static_cast(p);
-                double total_washoff_load = 0.0; // mass/sec
+                // THE UNIT CONVENTION, fixed 2026-08-23 after the known-mass
+                // audit (QUALITY_LEDGER_UNITS_AUDIT §7): total_washoff_load
+                // accumulates in CONCENTRATION MASS UNITS per second (mg/s,
+                // or µg/s, or counts/s — whatever the pollutant's units are),
+                // and every LEDGER booking converts to USER MASS (lbs/kg) at
+                // the seam via mcf_p, exactly as legacy applies Pollut[].mcf
+                // at source (landuse.c:585, surfqual.c:352/357/366). Before
+                // this, the accumulator mixed three unit systems — EMC in
+                // mg/L·ft³/s, EXPON in user-mass/s, RATING in mg/s — and the
+                // ledger row printed 16057× legacy on a 100 mg/L EMC deck
+                // while the Washoff Summary printed 1/28.3 of it.
+                //
+                // mcf_p mirrors legacy landuse.c:167-169: UCF(MASS) for mg,
+                // /1000 for µg, 1.0 for counts.
+                const double mass_ucf_p = ucf::UCF(ucf::MASS, ctx_.options);
+                double mcf_p = mass_ucf_p;
+                if (static_cast(p) < ctx_.pollutants.units.size()) {
+                    switch (ctx_.pollutants.units[static_cast(p)]) {
+                        case MassUnits::UG_PER_L:     mcf_p = mass_ucf_p / 1000.0; break;
+                        case MassUnits::COUNTS_PER_L: mcf_p = 1.0; break;
+                        default: break;
+                    }
+                }
+                constexpr double kLperFt3 = 28.317;
+                double total_washoff_load = 0.0; // concen. mass units / sec
+                // legacy landuse_getAvgBmpEffic(j, p): the coverage-weighted
+                // BMP removal fraction, which findPondedLoads applies to the
+                // ponded outflow load.
+                double avg_bmp_effic = 0.0;
 
                 // Iterate over land uses weighted by coverage
                 // Buildup is now stored PER LAND USE: bu_idx(i, lu, p)
@@ -2193,6 +3606,11 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                                    + static_cast(lu);
                     double frac = (cov_idx < ctx_.subcatches.coverage.size())
                                   ? ctx_.subcatches.coverage[cov_idx] / 100.0 : 0.0;
+                    avg_bmp_effic +=
+                        frac * landuse_solver_
+                                   .washoff_params[static_cast(
+                                       lu * np + p)]
+                                   .bmp_effic / 100.0;
                     if (frac <= 0.0) continue;
 
                     auto k = static_cast(lu * np + p);
@@ -2204,8 +3622,30 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                     double norm = (bp.normalizer == 0)
                         ? frac * area_ac : frac * ctx_.subcatches.curb_length[ui];
 
-                    // --- Buildup accumulation (matching legacy surfqual_getBuildup)
-                    if (bp.type != landuse::BuildupType::NONE) {
+                    // --- Buildup accumulation (matching legacy
+                    //     surfqual_getBuildup). Legacy calls it from
+                    //     runoff.c:280 under `if (runoff < MIN_RUNOFF)`:
+                    //     pollutant accumulates only while the subcatchment is
+                    //     effectively DRY, and stops for as long as it is
+                    //     running off. This engine accumulated on every runoff
+                    //     step, through the storm as well as between storms, so
+                    //     it kept laying down mass that the washoff was
+                    //     simultaneously removing — runoff44-sw5 built up
+                    //     64.383 lb of COD over the run against legacy's
+                    //     18.148. The test is the complement of the washoff
+                    //     gate below, on the same ft/sec rate.
+                    //
+                    //     The snow-only skip is legacy's too (surfqual.c:141):
+                    //     a SnowOnly pollutant does not accumulate on bare
+                    //     ground, only under a pack deeper than 0.001 in.
+                    const bool subcatch_is_dry = (runoff_fts < MIN_RUNOFF_FTS);
+                    const bool snow_only_blocked =
+                        (static_cast(p) < ctx_.pollutants.snow_only.size() &&
+                         ctx_.pollutants.snow_only[static_cast(p)] &&
+                         (ui >= ctx_.subcatches.snow_depth.size() ||
+                          ctx_.subcatches.snow_depth[ui] < 0.001 / 12.0));
+                    if (bp.type != landuse::BuildupType::NONE &&
+                        subcatch_is_dry && !snow_only_blocked) {
                         double mass = surface_quality_.buildup[bu];  // per-normalizer-unit
 
                         // Gap #35: EXTERNAL buildup uses a time series for rate.
@@ -2270,6 +3710,11 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                                 default: break;
                             }
                         }
+                        // legacy surfqual.c:149 `newBuildup = MAX(newBuildup,
+                        // oldBuildup)` — buildup never DECREASES across a
+                        // step, whatever the inverse/forward round trip
+                        // returns.
+                        new_mass = std::max(new_mass, mass);
                         double buildup_change = new_mass - mass;
                         surface_quality_.buildup[bu] = new_mass;
 
@@ -2281,7 +3726,22 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                     }
 
                     // --- Washoff computation (matching legacy surfqual_getWashoff)
-                    if (wp.type != landuse::WashoffType::NONE && q > MIN_RUNOFF_RATE) {
+                    // legacy findWashoffLoads returns early below MIN_RUNOFF
+                    // (consts.h 2.31481e-8 ft/sec = 0.001 in/hr), tested on
+                    // the ft/sec rate — not on a cfs flow against 1e-9.
+                    // legacy landuse_getWashoffLoad closes with
+                    //   washoffLoad = washoffQual * vOutflow * landuseArea/area
+                    // — the load is PROPORTIONAL to vOutflow, the runoff
+                    // volume that actually leaves the subcatchment. A
+                    // subcatchment covered entirely by LID has Voutflow = 0
+                    // and therefore washes off NOTHING, whatever is on the
+                    // ground. `q` here is that same number (legacy's
+                    // Voutflow/tStep), and requiring it keeps the all-LID case
+                    // at zero; where runoff does leave, the magnitude already
+                    // matches legacy exactly (runoff44-sw5's Surface Runoff
+                    // ledger term is exact), so this only closes the zero end.
+                    if (wp.type != landuse::WashoffType::NONE &&
+                        runoff_fts >= MIN_RUNOFF_FTS && q > 0.0) {
                         double buildup = surface_quality_.buildup[bu];
 
                         // Unit conversions matching legacy landuse_getWashoffLoad:
@@ -2289,42 +3749,157 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                         //     q_expon = (q_cfs / area_ft2) * UCF(RAINFALL)
                         //   RATING and EMC use volumetric flow in display units:
                         //     q_flow = q_cfs * UCF(FLOW)
-                        double area_ft2 = area_ac * 43560.0;
-                        double q_expon  = (area_ft2 > 0.0)
-                            ? (q / area_ft2) * ucf::UCF(ucf::RAINFALL, ctx_.options)
-                            : 0.0;
+                        // legacy keeps Subcatch.area in ft2 as
+                        // area / UCF(LANDAREA) — 43561.6 ft2 per ACRE and
+                        // 107639 per HECTARE. The exact-acre 43560 is
+                        // 3.7e-5 off on a US deck and a factor 2.471 off
+                        // on an SI one;
+                        // on swmm5buildupwashoff (CMS) that made the EXPON
+                        // washoff's unit runoff 2.471x too high, so the
+                        // 40 kg of SF1 on the ground left in three report
+                        // periods instead of ten.
+                        double area_ft2 = area_ac / ucf::UCF(ucf::LANDAREA, ctx_.options);
+                        double q_expon = runoff_fts
+                                       * ucf::UCF(ucf::RAINFALL, ctx_.options);
                         double q_flow   = q * ucf::UCF(ucf::FLOW, ctx_.options);
-
-                        double load = 0.0; // mass/sec (absolute)
+                        // legacy's land-use area, `landFactor[i].fraction *
+                        // Subcatch[j].area` (landuse.c:346).
+                        const double landuse_ft2 = frac * area_ft2;
+
+                        // `load` is in CONCENTRATION MASS UNITS per second
+                        // (mg/s for a mg/L pollutant). Each branch mirrors
+                        // legacy landuse_getWashoffQual × Q, with the
+                        // parse-time coefficient pre-multiplies
+                        // (landuse.c:332-334) applied here at runtime instead,
+                        // because our parser stores the user coefficient raw:
+                        //
+                        //   EMC:    coeff[mg/L] × LperFT3 → mg/ft³, × Q[cfs].
+                        //           Legacy uses INTERNAL flow here, not
+                        //           UCF(FLOW) — the previous q_flow form was
+                        //           inert under CFS and wrong under any other
+                        //           flow unit.
+                        //   EXPON:  coeff is PER HOUR in the deck; legacy
+                        //           divides by 3600 at parse. Without it the
+                        //           load was 3600× the formulation. Buildup
+                        //           is stored in user mass, so /mcf brings it
+                        //           to concentration mass units (legacy:
+                        //           `buildup / Pollut[p].mcf`).
+                        //   RATING: coeff × (Q·UCF(FLOW))^expon is already
+                        //           legacy's coeff·UCF^e × Q_int^e — unchanged.
+                        double load = 0.0; // concen. mass units / sec
                         switch (wp.type) {
                             case landuse::WashoffType::EMC:
-                                load = wp.coeff * q_flow * frac;
+                                load = wp.coeff * kLperFt3 * q * frac;
                                 break;
+                            // EXPON and RATING both close through legacy's
+                            // landuse_getWashoffLoad (landuse.c:351):
+                            //   washoffLoad = washoffQual * vOutflow
+                            //                 * landuseArea / area * mcf
+                            // where washoffQual is a CONCENTRATION formed by
+                            // dividing the rate by `runoff * landuseArea`.
+                            // With vOutflow = q * dt, the step's mass carries
+                            // the factor q / (runoff_fts * area) — the share
+                            // of the subareas' runoff that actually reaches
+                            // the OUTLET, legacy's fOutlet. v6 dropped it, so
+                            // any deck whose [SUBAREAS] routes one subarea
+                            // into another washed off as if every drop left
+                            // directly. On greenroofs — where subcatchment 9
+                            // sends 97 % of its impervious runoff to the
+                            // pervious subarea — that published 1983 mg/L of
+                            // TKN on the first wet period against legacy's 92,
+                            // stripped the buildup store, and then ran BELOW
+                            // legacy for the rest of the storm; the crossover
+                            // at period 17 is the depletion catching up.
                             case landuse::WashoffType::EXPON:
-                                if (buildup > 0.0)
-                                    load = wp.coeff * std::pow(q_expon, wp.expon) * buildup * norm;
+                                if (buildup > 0.0 && mcf_p > 0.0 &&
+                                    landuse_ft2 > 0.0) {
+                                    double wq = (wp.coeff / 3600.0)
+                                              * std::pow(q_expon, wp.expon)
+                                              * (buildup * norm) / mcf_p;
+                                    wq /= runoff_fts * landuse_ft2;
+                                    load = ((wq * q) * landuse_ft2) / area_ft2;
+                                }
                                 break;
                             case landuse::WashoffType::RATING:
-                                load = wp.coeff * std::pow(q_flow, wp.expon) * frac;
+                                if (area_ft2 > 0.0) {
+                                    // legacy pre-multiplies the RATING coeff
+                                    // by UCF(FLOW)^expon at parse
+                                    // (landuse.c:333); our parser keeps the
+                                    // user value, so it is applied here.
+                                    double wq = wp.coeff
+                                              * std::pow(ucf::UCF(ucf::FLOW,
+                                                                  ctx_.options),
+                                                         wp.expon)
+                                              * std::pow(runoff_fts * landuse_ft2,
+                                                         wp.expon - 1.0);
+                                    load = ((wq * q) * landuse_ft2) / area_ft2;
+                                }
+                                (void)q_flow;
                                 break;
                             default: break;
                         }
 
-                        // Cap washoff to available buildup (mass/sec <= total_mass / dt)
-                        double avail = buildup * norm;
+                        // Cap washoff to available buildup. Buildup is user
+                        // mass; the cap must be in the SAME units as `load`
+                        // (concen. mass), or the comparison is the mixed-unit
+                        // defect all over again — before this fix the EMC/
+                        // RATING mg-based load was compared against a lbs cap.
+                        double avail = (mcf_p > 0.0)
+                            ? (buildup * norm) / mcf_p : 0.0;
                         double max_load = (dt_runoff > 0.0) ? avail / dt_runoff : 0.0;
-                        if (load > max_load && wp.type != landuse::WashoffType::EMC)
+                        // legacy landuse_getWashoffLoad caps every washoff
+                        // type only when a buildup function is modelled.
+                        // RATING without buildup supplies its own mass, just
+                        // as EMC does; capping it to an empty store erases it.
+                        if (load > max_load && bp.type != landuse::BuildupType::NONE)
                             load = max_load;
 
-                        // Reduce per-landuse buildup by washoff amount
-                        if (norm > 0.0) {
-                            double washed = load * dt_runoff / norm;
+                        // Reduce per-landuse buildup by washoff amount —
+                        // buildup is user mass per normalizer unit, so the
+                        // reduction converts back (legacy reduces buildup by
+                        // washoffLoad, which is already lbs).
+                        //
+                        // ...unless there is NO buildup function and the
+                        // washoff exceeds what is on the ground, in which
+                        // case legacy books the load as BUILDUP_LOAD instead
+                        // (landuse.c:585-593, "otherwise add washoff to
+                        // buildup mass balance totals so that things will
+                        // balance"). Without that branch an EMC-only deck
+                        // discharges mass the ledger never received: the
+                        // Runoff Quality Continuity block reads Surface
+                        // Buildup 0.000 against Surface Runoff 113.269 where
+                        // legacy reads 113.082 on both. It is also what makes
+                        // the printed continuity error meaningful rather than
+                        // merely non-zero.
+                        const double washed_mass = load * mcf_p * dt_runoff;
+                        const bool has_buildup_fn =
+                            bp.type != landuse::BuildupType::NONE;
+                        if (!has_buildup_fn && washed_mass > buildup * norm) {
+                            auto upb2 = static_cast(p);
+                            if (upb2 < ctx_.mass_balance.qual_surface_buildup.size())
+                                ctx_.mass_balance.qual_surface_buildup[upb2] +=
+                                    washed_mass;
+                            surface_quality_.buildup[bu] = 0.0;
+                        } else if (norm > 0.0) {
+                            double washed = washed_mass / norm;
                             surface_quality_.buildup[bu] =
                                 std::max(surface_quality_.buildup[bu] - washed, 0.0);
                         }
 
-                        // Apply BMP removal
-                        load *= (1.0 - wp.bmp_effic / 100.0);
+                        // BMP removal — and BOOK it. qual_bmp_removal had no
+                        // writer anywhere (Finding 8, the fourth
+                        // rendered-but-never-written ledger row after the
+                        // snapshot quality vectors, the snow rows and the
+                        // subcatchment temperature column). Legacy books it at
+                        // surfqual.c:352 in user mass.
+                        double bmp_removed = load * (wp.bmp_effic / 100.0);
+                        if (bmp_removed > 0.0) {
+                            auto upb = static_cast(p);
+                            if (upb < ctx_.mass_balance.qual_bmp_removal.size())
+                                ctx_.mass_balance.qual_bmp_removal[upb] +=
+                                    bmp_removed * dt_runoff * mcf_p;
+                            load -= bmp_removed;
+                        }
 
                         total_washoff_load += load;
                     }
@@ -2334,17 +3909,36 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                 // Matches legacy findPondedLoads() in surfqual.c.
                 // Mixes wet deposition with existing ponded mass; distributes
                 // to infiltration and runoff outflow proportionally.
-                if (sq_idx < ctx_.subcatches.ponded_qual.size()) {
+                const double lid_ft2_pq =
+                    (ui < ctx_.subcatches.total_lid_area_ft2.size())
+                        ? ctx_.subcatches.total_lid_area_ft2[ui] : 0.0;
+                const double area_ft2_full_pq =
+                    area_ac / ucf::UCF(ucf::LANDAREA, ctx_.options);
+                // legacy findPondedLoads opens `if (area == lidArea) return;`
+                // — a subcatchment that is entirely LID has no ponded surface
+                // to mix into.
+                const double non_lid_ft2_pq = area_ft2_full_pq - lid_ft2_pq;
+                if (sq_idx < ctx_.subcatches.ponded_qual.size() &&
+                    non_lid_ft2_pq > 0.0) {
                     constexpr double L_PER_FT3 = 28.317;  // liters per ft3
                     auto up = static_cast(p);
-                    double area_ft2_pq = area_ac * 43560.0;
-
-                    // Rainfall at this subcatch (ft/sec)
-                    double rrate = ctx_.gages.rainfall.empty() ? 0.0
-                        : (ctx_.subcatches.gage[ui] >= 0 &&
-                           ctx_.subcatches.gage[ui] < static_cast(ctx_.gages.rainfall.size()))
-                          ? ctx_.gages.rainfall[static_cast(ctx_.subcatches.gage[ui])]
-                          : 0.0;
+                    // Every volume here is over the NON-LID area: legacy forms
+                    // vRain, the ponded store and the closing pondedQual on
+                    // `nonLidArea`, not the full area.
+                    const double area_ft2_pq = non_lid_ft2_pq;
+
+                    // Rainfall at this subcatch, INTERNAL ft/sec. This read
+                    // the GAGE's rate, which is carried in the project's
+                    // rainfall units (in/hr or mm/hr) — legacy's
+                    // `Subcatch[j].rainfall` is ft/sec. On a US deck that is
+                    // a factor of 12*3600 = 43200, and it went straight into
+                    // the wet-deposition volume: runoff44-sw5 booked 843,742
+                    // lb of deposited COD against legacy's 19.531, and
+                    // reported a 99.998 % runoff-quality continuity error.
+                    // `subcatches.rainfall` is the same number legacy uses,
+                    // already scaled by the gage and subcatchment factors.
+                    double rrate = (ui < ctx_.subcatches.rainfall.size())
+                        ? ctx_.subcatches.rainfall[ui] : 0.0;
 
                     // Volumes over dt (ft3)
                     double v_rain_pq    = rrate * area_ft2_pq * dt_runoff;
@@ -2352,8 +3946,12 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                     double v_infil_pq   = ctx_.subcatches.infil_loss[ui] * area_ft2_pq * dt_runoff;
                     double v_outflow_pq = q * dt_runoff;
 
-                    // Vinflow: rain + runon + existing ponded water volume
-                    double v_ponded_pq  = ctx_.subcatches.ponded_depth[ui] * area_ft2_pq;
+                    // Vinflow: rain + runon + the water ALREADY ponded at the
+                    // START of the step (legacy subcatch.c:694 forms this
+                    // before the subareas are stepped, which is why the
+                    // opening depth is kept aside rather than read back here).
+                    double v_ponded_pq  =
+                        ctx_.subcatches.old_ponded_depth[ui] * area_ft2_pq;
                     double v_inflow_pq  = v_rain_pq + v_runon_pq + v_ponded_pq;
 
                     // Wet deposition mass: c_rain[mg/L] * LperFT3[L/ft3] * v_rain[ft3]
@@ -2361,39 +3959,83 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                         ? ctx_.pollutants.c_rain[up] : 0.0;
                     double w_rain_pq = c_rain_pq * L_PER_FT3 * v_rain_pq;
 
-                    // Accumulate wet deposition in mass balance
+                    // Accumulate wet deposition in mass balance — LEDGER
+                    // booking, so convert to user mass at the seam (legacy
+                    // books WET_DEPOSITION_LOAD in lbs/kg).
                     if (w_rain_pq > 0.0 && up < ctx_.mass_balance.qual_wet_deposition.size())
-                        ctx_.mass_balance.qual_wet_deposition[up] += w_rain_pq;
+                        ctx_.mass_balance.qual_wet_deposition[up] += w_rain_pq * mcf_p;
 
                     double w_mass_pq = ctx_.subcatches.ponded_qual[sq_idx];  // mg
 
                     if (v_inflow_pq <= 0.0) {
-                        // Dry surface — move remaining ponded mass to final stored load
-                        if (w_mass_pq > 0.0 && up < ctx_.mass_balance.qual_final_buildup.size())
-                            ctx_.mass_balance.qual_final_buildup[up] += w_mass_pq;
+                        // Dry surface. The `+=` into qual_final_buildup that
+                        // used to sit here was DEAD (Finding 9):
+                        // computeFinalQualityMassBalance overwrites the term
+                        // with `=` at end-of-run, discarding every value
+                        // accumulated here — and it was in mg against that
+                        // site's user mass, so surviving would have corrupted
+                        // the term. Removed rather than converted. The
+                        // residual ponded mass at final time is NOT in the
+                        // final-buildup term on either path; that matches the
+                        // 4073 computation and is recorded as a small parity
+                        // gap against legacy's FINAL_STORED_LOAD.
                         ctx_.subcatches.ponded_qual[sq_idx] = 0.0;
                     } else {
                         // Complete-mix balance (matching legacy findPondedLoads):
-                        //   wRunon ≈ 0 (upstream subcatch concentrations not propagated here)
-                        double w_total_pq  = w_mass_pq + w_rain_pq;
+                        // wRunon = the run-on load assembleRunon accumulated
+                        // from the donors' oldRunoff x oldQual (surfqual.c:
+                        // 442-443, reading the newQual accumulator) — the
+                        // run-on WATER was already in v_inflow_pq, so leaving
+                        // the load out both starved and DILUTED the mix.
+                        double w_runon_pq =
+                            (sq_idx < ctx_.subcatches.runon_qual_rate.size())
+                                ? ctx_.subcatches.runon_qual_rate[sq_idx] *
+                                      dt_runoff
+                                : 0.0;
+                        double w_total_pq  = w_mass_pq + w_rain_pq + w_runon_pq;
                         double c_ponded_pq = w_total_pq / v_inflow_pq;  // mg/ft3
 
                         // Mass lost to infiltration
                         double w_infil_pq = std::min(c_ponded_pq * v_infil_pq, w_total_pq);
                         w_total_pq -= w_infil_pq;
+                        // Ledger booking → user mass (legacy INFIL_LOAD, lbs/kg)
                         if (w_infil_pq > 0.0 && up < ctx_.mass_balance.qual_infil_loss.size())
-                            ctx_.mass_balance.qual_infil_loss[up] += w_infil_pq;
+                            ctx_.mass_balance.qual_infil_loss[up] += w_infil_pq * mcf_p;
 
                         // Mass carried out with runoff outflow
                         double w_outflow_pq = std::min(c_ponded_pq * v_outflow_pq, w_total_pq);
                         w_total_pq -= w_outflow_pq;
 
+                        // legacy reduces the ponded outflow load by the land
+                        // uses' area-weighted BMP efficiency, exactly as the
+                        // washoff loads above are reduced. Only the washoff
+                        // half was booked here, so a BMP removed nothing from
+                        // the rain- and run-on-borne share.
+                        double bmp_pq = avg_bmp_effic * w_outflow_pq;
+                        if (bmp_pq > 0.0) {
+                            if (up < ctx_.mass_balance.qual_bmp_removal.size())
+                                ctx_.mass_balance.qual_bmp_removal[up] +=
+                                    bmp_pq * mcf_p;
+                            w_outflow_pq -= bmp_pq;
+                        }
+
                         // Add ponded outflow to total washoff load (mass/sec)
                         if (w_outflow_pq > 0.0 && dt_runoff > 0.0)
                             total_washoff_load += w_outflow_pq / dt_runoff;
 
-                        // Update remaining ponded mass for next timestep
-                        ctx_.subcatches.ponded_qual[sq_idx] = std::max(w_total_pq, 0.0);
+                        // legacy closes by RE-DERIVING the ponded store from
+                        // the mixed concentration and the depth the step
+                        // actually ended at — `cPonded * subcatch_getDepth(j)
+                        // * nonLidArea` — not by carrying whatever mass was
+                        // left over. The two differ whenever the surface
+                        // gained or lost water, and the leftover form drained
+                        // the pool to nothing: a subcatchment shed its
+                        // rainfall-borne load the instant the rain stopped
+                        // instead of releasing it down the recession.
+                        ctx_.subcatches.ponded_qual[sq_idx] = std::max(
+                            c_ponded_pq * ctx_.subcatches.ponded_depth[ui] *
+                                area_ft2_pq,
+                            0.0);
                     }
                 }
 
@@ -2406,53 +4048,273 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
                     double lid_ft2 = ctx_.subcatches.total_lid_area_ft2[ui];
                     if (lid_ft2 > 0.0 && dt_runoff > 0.0) {
                         constexpr double L_PER_FT3_37 = 28.317;
-                        // Rainfall rate for this subcatch (ft/sec)
-                        int gi37 = ctx_.subcatches.gage[ui];
-                        double rrate37 = (gi37 >= 0 &&
-                                          gi37 < static_cast(ctx_.gages.rainfall.size()))
-                                          ? ctx_.gages.rainfall[static_cast(gi37)]
-                                          : 0.0;
+                        // legacy `vLidRain = Subcatch[j].rainfall * lidArea *
+                        // tStep`, and Subcatch[j].rainfall is INTERNAL ft/sec.
+                        // This read ctx_.gages.rainfall, which carries the
+                        // project's DISPLAY rate — in/hr on a US deck, mm/hr
+                        // on an SI one — straight into a volume, exactly the
+                        // defect the ponded stage carried until b0924c78. The
+                        // inflated volume never reached the vOut1 denominator
+                        // (which already used subcatches.rainfall), so it
+                        // landed undivided on the numerator: greenroofs'
+                        // subcatchment 3 washed off 64,673,001 against
+                        // legacy's 1,264.
+                        double rrate37 = (ui < ctx_.subcatches.rainfall.size())
+                                          ? ctx_.subcatches.rainfall[ui] : 0.0;
                         auto up37 = static_cast(p);
                         double c_rain37 = (up37 < ctx_.pollutants.c_rain.size())
                                           ? ctx_.pollutants.c_rain[up37] : 0.0;
                         // Wet deposition on LID area (mass/sec)
                         double v_lid_rain = rrate37 * lid_ft2 * dt_runoff;  // ft³
                         double w_lid_rain = c_rain37 * L_PER_FT3_37 * v_lid_rain;  // mg
-                        if (w_lid_rain > 0.0)
+                        if (w_lid_rain > 0.0) {
                             total_washoff_load += w_lid_rain / dt_runoff;
+                            // legacy books the LID footprint's share of the
+                            // wet deposition too (surfqual.c:496). Only the
+                            // ponded stage booked it here, so the ledger was
+                            // short by exactly the LID area's rain.
+                            if (up37 < ctx_.mass_balance.qual_wet_deposition.size())
+                                ctx_.mass_balance.qual_wet_deposition[up37] +=
+                                    w_lid_rain * mcf_p;
+                        }
                         // Runon quality (only when LIDs cover full subcatchment)
-                        double full_ft2 = ctx_.subcatches.area[ui] * 43560.0;
+                        double full_ft2 = ctx_.subcatches.area[ui]
+                                        / ucf::UCF(ucf::LANDAREA, ctx_.options);
                         if (std::fabs(lid_ft2 - full_ft2) < 1.0) {
-                            double q_runon37 = ctx_.subcatches.runon_inflow[ui];  // CFS
-                            double c_old37 = (sq_idx < ctx_.subcatches.conc_old.size())
-                                             ? ctx_.subcatches.conc_old[sq_idx] : 0.0;
-                            double w_lid_runon = q_runon37 * c_old37 * dt_runoff;  // mg
+                            // legacy findLidLoads (surfqual.c:560-561) reads
+                            // the SAME accumulator findPondedLoads reads —
+                            // the donors' oldRunoff x oldQual assembled into
+                            // newQual — not the RECEIVER's own concentration,
+                            // which this block used before (right only when
+                            // donor and receiver happened to share an EMC).
+                            double w_lid_runon =
+                                (sq_idx < ctx_.subcatches.runon_qual_rate.size())
+                                    ? ctx_.subcatches.runon_qual_rate[sq_idx] *
+                                          dt_runoff
+                                    : 0.0;                                   // mg
                             if (w_lid_runon > 0.0)
                                 total_washoff_load += w_lid_runon / dt_runoff;
                         }
                     }
                 }
 
-                // Convert washoff load to concentration (mass/ft3)
+                // Convert washoff load to the REPORTED concentration, mg/L.
+                // load/q is mass/ft³; ÷ LperFT3 gives mass/L, exactly
+                // legacy's `newQual[p] = cOut / LperFT3` (surfqual.c:370).
+                // For EMC this leaves the value where it already was (the
+                // old form skipped LperFT3 in both load and conc, cancelling);
+                // for EXPON and RATING it is a real correction — their
+                // concentrations were in incompatible units before this.
                 double conc = 0.0;
-                if (q > MIN_RUNOFF_RATE && total_washoff_load > 0.0)
-                    conc = total_washoff_load / q;
+                if (q_out1 > 0.0 && total_washoff_load > 0.0)
+                    conc = total_washoff_load / q_out1 / kLperFt3;
 
                 ctx_.subcatches.conc[sq_idx] = conc;
 
-                // Update quality mass balance and per-subcatch total load
-                if (total_washoff_load > 0.0) {
-                    double mass = total_washoff_load * dt_runoff;
-                    ctx_.mass_balance.qual_runoff_load[
-                        static_cast(p)] += mass;
-                    // Accumulate per-subcatchment washoff load
-                    ctx_.subcatches.total_load[sq_idx] += mass;
-                }
+                // The mass bookings that used to close this loop now live in
+                // bookWashoffLoads, called after the LID units have run: they
+                // need the POST-LID volumes, which do not exist yet here.
+                // Only the concentration is formed at this point, because
+                // legacy forms it over the PRE-LID vOut1 (surfqual.c:330).
             } // end pollutant loop
+
+            // --- Co-pollutant washoff (legacy findWashoffLoads,
+            // surfqual.c:505-521). A pollutant may be generated as a FRACTION
+            // of another's washoff:
+            //
+            //     k = Pollut[p].coPollut;
+            //     if (k >= 0) {
+            //         w = Pollut[p].coFraction * OutflowLoad[k];
+            //         massbal_updateLoadingTotals(BUILDUP_LOAD, p, w*mcf);
+            //         OutflowLoad[p] += w;
+            //     }
+            //
+            // [POLLUTANTS] parses coPollut/coFraction into ctx_.pollutants and
+            // LanduseSolver::applyCoPollutant implements the relation and is
+            // unit-tested — but NOTHING in the engine ever called it, and this
+            // loop never mentioned a co-pollutant. Five corpus decks declare
+            // Lead as 20 % of TSS and v6 washed off exactly ZERO Lead:
+            // pond-design's ORI-19 read 0 against legacy's 5.112 from the
+            // first wet period, and the gap propagated to every node and link
+            // downstream.
+            //
+            // It must run AFTER the whole pollutant loop, over the SUMMED
+            // loads, exactly as legacy does — and as a single FORWARD pass, so
+            // that a co-pollutant of a co-pollutant sees the already-updated
+            // value where legacy would. Operating on `conc` is equivalent to
+            // operating on OutflowLoad: both divide by the same q_out1 and
+            // LperFT3, so the fraction carries through unchanged.
+            if (q_out1 > 0.0) {
+                const double mass_ucf_cp = ucf::UCF(ucf::MASS, ctx_.options);
+                for (int p = 0; p < np; ++p) {
+                    const auto up = static_cast(p);
+                    if (up >= ctx_.pollutants.co_pollut.size()) continue;
+                    const int k = ctx_.pollutants.co_pollut[up];
+                    if (k < 0 || k >= np) continue;
+                    const double frac = (up < ctx_.pollutants.co_frac.size())
+                                        ? ctx_.pollutants.co_frac[up] : 0.0;
+                    if (frac <= 0.0) continue;
+
+                    const auto ip = ui * static_cast(np) + up;
+                    const auto ik = ui * static_cast(np)
+                                  + static_cast(k);
+                    if (ip >= ctx_.subcatches.conc.size() ||
+                        ik >= ctx_.subcatches.conc.size()) continue;
+
+                    const double add = frac * ctx_.subcatches.conc[ik];
+                    if (add <= 0.0) continue;
+                    ctx_.subcatches.conc[ip] += add;
+
+                    // legacy books the co-pollutant's share as BUILDUP_LOAD so
+                    // the ledger balances — this mass was never on the ground.
+                    double mcf_cp = mass_ucf_cp;
+                    if (up < ctx_.pollutants.units.size()) {
+                        switch (ctx_.pollutants.units[up]) {
+                            case MassUnits::UG_PER_L:     mcf_cp = mass_ucf_cp / 1000.0; break;
+                            case MassUnits::COUNTS_PER_L: mcf_cp = 1.0; break;
+                            default: break;
+                        }
+                    }
+                    // conc -> load rate: x q_out1 x LperFT3 (the inverse of
+                    // the conversion the pollutant loop just applied).
+                    const double w = add * q_out1 * 28.317;
+                    if (up < ctx_.mass_balance.qual_surface_buildup.size())
+                        ctx_.mass_balance.qual_surface_buildup[up] +=
+                            w * dt_runoff * mcf_cp;
+                }
+            }
         } // end subcatch loop
     }
 }
 
+// ============================================================================
+// bookWashoffLoads() — the washoff MASS bookings, deferred past the LID units
+// ============================================================================
+
+/**
+ * @brief Book this runoff step's washoff mass, now that the LID units have
+ *        run and it is known how much of the inflow actually left.
+ *
+ * @details legacy surfqual_getWashoff (surfqual.c:322-371) forms ONE washoff
+ *          concentration, over the PRE-LID inflow volume vOut1 — which is why
+ *          stepSurfaceQuality still forms `conc` where it does — and then
+ *          books it against THREE different volumes:
+ *
+ *          - `vLost = vOut1 - vOut2` never reaches the network at all. Its
+ *            share up to VlidInfil is Infiltration Loss; the remainder is BMP
+ *            Removal (surfqual.c:338-353).
+ *          - the subcatchment's own reported total takes `vOut2`, the surface
+ *            runoff plus the LID drains (surfqual.c:356).
+ *          - the Surface Runoff ledger row takes `vSurfOut` ONLY. The drain
+ *            half is booked beside the drains themselves, because a drain can
+ *            reach a different outlet than its parent (surfqual.c:363-367,
+ *            lid.c:1513-1515).
+ *
+ *          v6 booked `cOut * vOut1` for both the total and the ledger, so
+ *          every deck whose units capture a large share of their inflow
+ *          reported mass the system never received. `duobiocell` and
+ *          `more-process-100-bio-cell` book all 40 kg of their [LOADINGS] as
+ *          Surface Runoff where legacy books it as BMP Removal. The
+ *          concentration was already right; only the bookings were wrong, and
+ *          they cannot be made until A6 has run the units.
+ */
+void SWMMEngine::bookWashoffLoads(double dt_runoff) noexcept {
+    const int np = ctx_.n_pollutants();
+    const int ns = ctx_.n_subcatches();
+    // No land-use condition, for the same reason stepSurfaceQuality has none:
+    // the load this books is whatever reached the runoff, and on a deck with
+    // no [LANDUSES] that is the wet deposition the ponded stage mixed in.
+    // Returning early left the mass created and never booked — lid1d closed at
+    // a 94.898 % runoff-quality continuity error with Surface Runoff 0.000
+    // against legacy's 110,015.701.
+    if (np <= 0 || ns <= 0 || ctx_.options.ignore_quality) return;
+
+    constexpr double kLperFt3 = 28.317;
+    const double mass_ucf = ucf::UCF(ucf::MASS, ctx_.options);
+
+    // legacy VlidInfil — infiltration into the native soil beneath the units,
+    // the same sum stepGroundwater forms for the aquifer's recharge.
+    // g.infil_loss is a DEPTH over this step, so × area is already ft³.
+    std::vector lid_infil_vol(static_cast(ns), 0.0);
+    for (int t = 0; t < lid_.numGroups(); ++t) {
+        const auto& g = lid_.group(t);
+        for (int u = 0; u < g.count; ++u) {
+            auto uu = static_cast(u);
+            int sc = g.subcatch_idx[uu];
+            if (sc < 0 || sc >= ns) continue;
+            lid_infil_vol[static_cast(sc)] +=
+                g.infil_loss[uu] * g.area[uu];
+        }
+    }
+
+    for (int i = 0; i < ns; ++i) {
+        const auto ui = static_cast(i);
+        if (ctx_.subcatches.area[ui] <= 0.0) continue;
+
+        const double v_out1 = (ui < ctx_.subcatches.washoff_vout1.size())
+                            ? ctx_.subcatches.washoff_vout1[ui] : 0.0;
+        // POST-LID: `runoff` carries the units' effect by now (A6b), and the
+        // drains were accumulated beside it as a CFS this same step.
+        const double v_surf_out = ctx_.subcatches.runoff[ui] * dt_runoff;
+        const double v_drain = (ui < ctx_.subcatches.lid_drain_flow.size())
+                             ? ctx_.subcatches.lid_drain_flow[ui] * dt_runoff
+                             : 0.0;
+        const double v_out2 = v_surf_out + v_drain;
+
+        const double lid_ft2 = (ui < ctx_.subcatches.total_lid_area_ft2.size())
+                             ? ctx_.subcatches.total_lid_area_ft2[ui] : 0.0;
+        const bool has_lid = lid_ft2 > 0.0;
+        const double v_lost = has_lid ? std::max(v_out1 - v_out2, 0.0) : 0.0;
+        const double v_infil = std::min(lid_infil_vol[ui], v_lost);
+
+        // legacy's third `outNode >= 0 || outSubcatch == subcatchIndex` site
+        // (surfqual.c:363): a subcatchment shedding onto a peer has not
+        // delivered its load to the system; the receiver books it on
+        // discharge, and booking it here counts the same mass twice.
+        const bool load_reaches_system =
+            (ctx_.subcatches.outlet_node[ui] >= 0 ||
+             ctx_.subcatches.outlet_subcatch[ui] == i);
+
+        for (int p = 0; p < np; ++p) {
+            const auto sq_idx = ui * static_cast(np)
+                              + static_cast(p);
+            const auto up = static_cast(p);
+            if (sq_idx >= ctx_.subcatches.conc.size()) continue;
+            // stepSurfaceQuality stored legacy's `newQual[p] = cOut/LperFT3`,
+            // so cOut reads straight back out — no second array to carry.
+            const double c_out = ctx_.subcatches.conc[sq_idx] * kLperFt3;
+            if (c_out <= 0.0) continue;
+
+            // mcf mirrors legacy landuse.c:167-169, as stepSurfaceQuality does.
+            double mcf_p = mass_ucf;
+            if (up < ctx_.pollutants.units.size()) {
+                switch (ctx_.pollutants.units[up]) {
+                    case MassUnits::UG_PER_L:     mcf_p = mass_ucf / 1000.0; break;
+                    case MassUnits::COUNTS_PER_L: mcf_p = 1.0; break;
+                    default: break;
+                }
+            }
+
+            if (has_lid) {
+                const double m_infil = c_out * v_infil * mcf_p;
+                if (m_infil > 0.0 && up < ctx_.mass_balance.qual_infil_loss.size())
+                    ctx_.mass_balance.qual_infil_loss[up] += m_infil;
+                const double m_bmp = c_out * (v_lost - v_infil) * mcf_p;
+                if (m_bmp > 0.0 && up < ctx_.mass_balance.qual_bmp_removal.size())
+                    ctx_.mass_balance.qual_bmp_removal[up] += m_bmp;
+            }
+
+            // The PER-SUBCATCHMENT total is unconditional, as legacy's is
+            // (surfqual.c:356, above its own guard): what this subcatchment
+            // washed off, not what the system received.
+            ctx_.subcatches.total_load[sq_idx] += c_out * v_out2 * mcf_p;
+
+            if (load_reaches_system && up < ctx_.mass_balance.qual_runoff_load.size())
+                ctx_.mass_balance.qual_runoff_load[up] += c_out * v_surf_out * mcf_p;
+        }
+    }
+}
+
 // ============================================================================
 // stepGroundwater() — groundwater computation for one substep
 // ============================================================================
@@ -2468,32 +4330,119 @@ void SWMMEngine::stepSurfaceQuality(double dt_runoff) noexcept {
  */
 void SWMMEngine::stepGroundwater(double dt_runoff) noexcept {
     int ns = ctx_.n_subcatches();
+    // Legacy keeps Subcatch.area in ft2 as area / UCF(LANDAREA) (ac or ha
+    // over 2.2956e-5 / 0.92903e-5): 43561.6 ft2 per acre, not 43560, and
+    // 107 639 ft2 per hectare — the exact-acre constant was 3.7e-5 off on
+    // US decks and a factor 2.47 off on SI decks.
+    const double ucf_landarea = ucf::UCF(ucf::LANDAREA, ctx_.options);
 
     // GW surface water head and available node flow are pre-computed by
     // assembleGWCoupling() before this function is called.
 
-    // Build per-subcatchment FracPerv and pervious evap rate
-    // Legacy: FracPerv = subcatch_getFracPerv(j)
-    //         MaxEvap = Evap.rate * FracPerv
-    //         AvailEvap = max(MaxEvap - evap, 0)
+    // Per-subcatchment inputs, formed as legacy subcatch_getRunoff hands
+    // them to gwater_getGroundwater (subcatch.c:738) and as it then scales
+    // them (gwater.c): the pervious-subarea evaporation VOLUME Vpevap and
+    // the infiltration VOLUME Vinfil + VlidInfil, each divided by the FULL
+    // subcatchment area and then by tStep — in that order — and FracPerv =
+    // subcatch_getFracPerv, which folds the pervious LID footprint in.
+    //
+    // subcatches.evap_loss / infil_loss are the wrong quantities here: the
+    // evap loss is the whole subcatchment's (impervious subareas included,
+    // so the available aquifer evaporation was under-stated on every deck
+    // with impervious cover), and both are rates over the NON-LID area
+    // formed as V / dt / A — a different rounding from legacy's V / A / dt
+    // that drifted example5-3aquifers at the 1e-7 level from period 23.
+    //
+    // The LID shares (legacy evalLidUnit: VlidInfil from every unit,
+    // Vpevap from the pervious ones — isLidPervious: no storage layer, or a
+    // storage layer that exfiltrates) come from the LID solver, which now
+    // runs before this step as it does in legacy.
     gw_frac_perv_.assign(static_cast(ns), 0.0);
     gw_perv_evap_.assign(static_cast(ns), 0.0);
-    for (int i = 0; i < ns; ++i) {
-        auto ui = static_cast(i);
-        double total_area = ctx_.subcatches.area[ui] * ucf::ACRES_TO_FT2;
-        if (total_area <= 0.0) continue;
-        double frac_perv = 1.0 - ctx_.subcatches.frac_imperv[ui];
-        gw_frac_perv_[ui] = std::max(frac_perv, 0.0);
-        gw_perv_evap_[ui] = ctx_.subcatches.evap_loss[ui];
-    }
-
-    // Pass actual infiltration rate to groundwater (upper zone percolation input).
-    // sw_head is read from the pre-assembled subcatches.gw_sw_head[].
-    groundwater_.execute(ctx_, dt_runoff, ctx_.climate_state.evap_rate,
-                         ctx_.subcatches.infil_loss.data(),
-                         ctx_.subcatches.gw_sw_head.data(),
-                         gw_frac_perv_.data(), gw_perv_evap_.data());
-
+    gw_infil_rate_.assign(static_cast(ns), 0.0);
+    {
+        const auto& rsoa = runoff_.soa();
+        std::vector lid_perv_area(static_cast(ns), 0.0);
+        std::vector lid_infil_vol(static_cast(ns), 0.0);
+        std::vector lid_perv_evap_vol(static_cast(ns), 0.0);
+        for (int t = 0; t < lid_.numGroups(); ++t) {
+            const auto& g = lid_.group(t);
+            for (int u = 0; u < g.count; ++u) {
+                auto uu = static_cast(u);
+                int sc = g.subcatch_idx[uu];
+                if (sc < 0 || sc >= ns) continue;
+                auto usc = static_cast(sc);
+                const bool pervious = (g.stor_thick[uu] == 0.0 || g.stor_ksat[uu] > 0.0);
+                lid_infil_vol[usc] += g.infil_loss[uu] * g.area[uu];
+                if (pervious) {
+                    lid_perv_area[usc]     += g.area[uu];
+                    lid_perv_evap_vol[usc] += g.evap_loss[uu] * g.area[uu];
+                }
+            }
+        }
+        for (int i = 0; i < ns; ++i) {
+            auto ui = static_cast(i);
+            double total_area = ctx_.subcatches.area[ui] / ucf_landarea;   // legacy Subcatch.area (ft2)
+            if (total_area <= 0.0) continue;
+            double frac_perv = 1.0 - ctx_.subcatches.frac_imperv[ui];
+            const double lid_area = (ui < ctx_.subcatches.total_lid_area_ft2.size())
+                ? ctx_.subcatches.total_lid_area_ft2[ui] : 0.0;
+            if (lid_area > 0.0) {
+                frac_perv = (frac_perv * (total_area - lid_area) + lid_perv_area[ui])
+                            / total_area;
+                frac_perv = std::min(frac_perv, 1.0);
+            }
+            gw_frac_perv_[ui] = frac_perv;
+            const double v_pevap = (ui < rsoa.perv_evap_vol.size() ? rsoa.perv_evap_vol[ui] : 0.0)
+                                   + lid_perv_evap_vol[ui];
+            const double v_infil = (ui < rsoa.infil_vol.size() ? rsoa.infil_vol[ui] : 0.0)
+                                   + lid_infil_vol[ui];
+            gw_perv_evap_[ui]  = v_pevap / total_area / dt_runoff;
+            gw_infil_rate_[ui] = v_infil / total_area / dt_runoff;
+        }
+    }
+
+    // U3 (track I-b): 2D per-cell infiltration whose destination is
+    // SUBCATCH_AQUIFER recharges the containing subcatchment's legacy
+    // aquifer. The router accumulated it in m³ since the last drain; the GW
+    // solver's `infil_rate` is ft/s over the FULL subcatchment area, so the
+    // volume converts with the area and this runoff step. Cells outside every
+    // polygon contributed nothing (they stayed LOST, warned at initialize).
+    const double* gw_infil_ptr = gw_infil_rate_.data();
+#ifdef OPENSWMM_HAS_2D
+    if (surface_router_.isActive() && dt_runoff > 0.0) {
+        surface_router_.drainSubcatchRecharge(gw_2d_recharge_vol_);
+        if (!gw_2d_recharge_vol_.empty()) {
+            gw_infil_with_2d_.assign(gw_infil_rate_.begin(),
+                                     gw_infil_rate_.end());
+            constexpr double kM3ToFt3 = 1.0 / (0.3048 * 0.3048 * 0.3048);
+            for (int i = 0; i < ns && i < static_cast(gw_2d_recharge_vol_.size());
+                 ++i) {
+                const auto ui = static_cast(i);
+                const double vol_m3 = gw_2d_recharge_vol_[ui];
+                if (vol_m3 <= 0.0) continue;
+                const double area_ft2 = ctx_.subcatches.area[ui] / ucf_landarea;
+                if (area_ft2 <= 0.0) continue;
+                gw_infil_with_2d_[ui] +=
+                    (vol_m3 * kM3ToFt3) / (area_ft2 * dt_runoff);
+                ctx_.mass_balance.gw_infil_2d_recharge += vol_m3 * kM3ToFt3;
+                // G1-c item 1: the 2D ledger's transfer row is booked HERE,
+                // at delivery, from the same volume (SurfaceRouter2D keeps
+                // only what is still in flight).
+                ctx_.mass_balance_2d.infil_to_aquifer += vol_m3;
+            }
+            gw_infil_ptr = gw_infil_with_2d_.data();
+        }
+    }
+#endif
+
+    // Pass actual infiltration rate to groundwater (upper zone percolation input).
+    // sw_head is read from the pre-assembled subcatches.gw_sw_head[].
+    groundwater_.execute(ctx_, dt_runoff, ctx_.climate_state.evap_rate,
+                         gw_infil_ptr,
+                         ctx_.subcatches.gw_sw_head.data(),
+                         gw_frac_perv_.data(), gw_perv_evap_.data());
+
     // Store GW flow rates in subcatch state for Phase 2 interpolation.
     // GW flow is in ft/sec (rate per unit area).
     // Convert to CFS: q_cfs = gw_flow * area_ft2
@@ -2502,7 +4451,7 @@ void SWMMEngine::stepGroundwater(double dt_runoff) noexcept {
     for (int i = 0; i < ns; ++i) {
         auto ui = static_cast(i);
         double gw_rate = groundwater_.state().gw_flow[ui]; // ft/sec
-        double area_ft2 = ctx_.subcatches.area[ui] * ucf::ACRES_TO_FT2;
+        double area_ft2 = ctx_.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx_.options);
         ctx_.subcatches.gw_flow[ui] = gw_rate * area_ft2; // CFS
 
         // Gap #40: propagate max infiltration volume to SubcatchData for next
@@ -2519,8 +4468,8 @@ void SWMMEngine::stepGroundwater(double dt_runoff) noexcept {
     for (int i = 0; i < ns; ++i) {
         auto ui = static_cast(i);
         if (ctx_.subcatches.gw_aquifer[ui] < 0) continue;
-        double area_ft2 = ctx_.subcatches.area[ui] * ucf::ACRES_TO_FT2;
-        ctx_.subcatches.stat_gw_infil_vol[ui]      += ctx_.subcatches.infil_loss[ui] * area_ft2 * dt_runoff;
+        double area_ft2 = ctx_.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx_.options);
+        ctx_.subcatches.stat_gw_infil_vol[ui]      += gw_infil_rate_[ui] * area_ft2 * dt_runoff;
         ctx_.subcatches.stat_gw_upper_evap_vol[ui] += gws.upper_evap[ui]  * area_ft2 * dt_runoff;
         ctx_.subcatches.stat_gw_lower_evap_vol[ui] += gws.lower_evap[ui]  * area_ft2 * dt_runoff;
         ctx_.subcatches.stat_gw_deep_perc_vol[ui]  += gws.deep_loss[ui]   * area_ft2 * dt_runoff;
@@ -2559,12 +4508,47 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
     // Reference: routing_execute() in legacy routing.c
     // ================================================================
 
+    // Legacy dates this whole step — the control rules, every inflow —
+    // with getDateTime(NewRoutingTime) taken at routing_execute entry
+    // (swmm5.c getDateTime: StartDateTime + (elapsedMsec + 1) / 1000
+    // seconds), the START of the step plus 1 ms, so a step landing exactly
+    // on a pattern / time-series / RDII boundary reads the interval that
+    // begins there. Formed from the ms clock, not from current_time +
+    // 0.001: the ms count is an exact integer, so (ms + 1) / 1000 is
+    // legacy's number, while the seconds clock carries its own accumulated
+    // rounding and 0.001 is not representable.
+    const double routing_secs = (ctx_.elapsed_ms + 1.0) / 1000.0;
+    const double routing_date = datetime::addSeconds(ctx_.options.start_date,
+                                                     routing_secs);
+
     // B0a. Check if between routing events — skip routing if so
-    //       (matching legacy isBetweenEvents() in routing.c)
-    if (isBetweenEvents(ctx_.current_date)) {
-        // Advance next_event_ index past expired events
-        while (next_event_ < static_cast(ctx_.events.size()) &&
-               ctx_.current_date > ctx_.events[static_cast(next_event_)].end) {
+    //      (legacy isBetweenEvents(), routing.c). The test takes legacy's
+    //      currentDate, the one formed just above: ctx_.current_date is the
+    //      seconds clock WITHOUT legacy's 1 ms, so a step starting exactly on
+    //      an event's end date read as "still inside the event" and routed one
+    //      step past every window legacy had already closed (events-example
+    //      diverged at period 864 = Event[0].end for precisely this reason).
+    //      The index advances by ONE event per call, which is where legacy
+    //      puts it — inside the > end branch — and not by a sweep to the first
+    //      unexpired event: legacy re-tests the next one on the next step.
+    between_events_ = isBetweenEvents(routing_date);
+    if (between_events_) {
+        // legacy initSystemInflows() runs BEFORE the event test, and both it
+        // and the node_/link_setOldQualState it calls roll the old state AND
+        // ZERO the new one (routing.c:432, node.c, link.c). v6 splits those:
+        // save_lat_qual_state() (step(), every step) does the roll, while the
+        // zero is implicit in clearInflowSources/assembleLateralInflows and in
+        // the quality router assigning conc — all of which this early return
+        // skips. Without it a skipped window keeps reporting the last routed
+        // step's lateral inflow and concentrations forever, where legacy,
+        // having zeroed them and then routed nothing, reports none.
+        std::fill(ctx_.nodes.lat_flow.begin(), ctx_.nodes.lat_flow.end(), 0.0);
+        if (!ctx_.options.ignore_quality) {
+            std::fill(ctx_.nodes.conc.begin(), ctx_.nodes.conc.end(), 0.0);
+            std::fill(ctx_.links.conc.begin(), ctx_.links.conc.end(), 0.0);
+        }
+        if (next_event_ < static_cast(ctx_.events.size()) &&
+            routing_date > ctx_.events[static_cast(next_event_)].end) {
             next_event_++;
         }
         return;
@@ -2580,7 +4564,13 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
 
     // B1b. Evaluate control rules (P8-G18: orifice gradual open/close)
     //      Control rules can override pump target_setting set above.
-    controls_.evaluate(ctx_, ctx_.current_time, dt_routing);
+    //      legacy evaluateControlRules: at currentDate (above), only when
+    //      RuleStep == 0 or the ms clock sits on the rule grid
+    //      (|NewRoutingTime - NewRuleTime| < 1).
+    const bool rule_time_reached =
+        ctx_.options.rule_step <= 0.0 ||
+        std::fabs(ctx_.elapsed_ms - new_rule_time_ms_) < 1.0;
+    controls_.evaluate(ctx_, routing_date, dt_routing, rule_time_reached);
     // Apply setting transitions: move setting toward target_setting
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
@@ -2592,7 +4582,7 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
             // routing.c:295-299. LINK_TIMEOPEN / LINK_TIMECLOSED rule
             // premises read this via ctx.links.time_last_set. (P1-C09)
             if (target * current == 0.0)
-                ctx_.links.time_last_set[uj] = ctx_.current_date;
+                ctx_.links.time_last_set[uj] = routing_date;  // legacy: = currentDate
 
             // Gradual transition (P8-G18): use orifice open/close rate
             // Legacy: link_setSetting() applies orate for time-based ramp
@@ -2624,26 +4614,35 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
     //     sums them all into nodes.lat_flow[] for the routing solver.
     ctx_.nodes.clearInflowSources();
 
-    // Legacy getDateTime() adds +1ms offset to avoid boundary rounding issues
-    // with pattern lookups at exact hour/day boundaries.
-    double routing_date = datetime::addSeconds(ctx_.options.start_date,
-                                               ctx_.current_time + 0.001);
     inflow_.computeAll(ctx_, routing_date, dt_routing);
+    // BW-MSX: this step's species washoff joins the external species loads
+    // (msx_ext_mass_in, re-zeroed by computeAll) that the ARD engine, the
+    // legacy MSX dispatch and LARD consume later in the step.
+    if (!ctx_.options.ignore_quality) msxsurf::deliver(ctx_, dt_routing);
 
     // B2a. RDII inflows — apply pre-computed values from wet weather step,
     //      or, under [FILES] USE RDII, the interface file's flows (legacy
     //      addRdiiInflows() always reads from the RDII file; USE just
     //      changes whose file it is).
+    //      Dated like every other legacy inflow: addRdiiInflows(currentDate)
+    //      takes currentDate = getDateTime(NewRoutingTime) at routing_execute
+    //      entry, i.e. the START of this step PLUS legacy's 1 ms (swmm5.c
+    //      getDateTime adds (elapsedMsec + 1)). The raw start time picked the
+    //      previous RDII block whenever a variable step happened to end 1 ms
+    //      before a block boundary (rtk-long, day 142: legacy applied the
+    //      08:05 record at a step starting 08:04:59.999, v6 the 08:00 one,
+    //      and the two runs never re-converged).
     if (!ctx_.options.ignore_rdii) {
         if (rdii_iface_file_.isOpen() && !rdii_iface_file_.isWriting()) {
-            rdii_iface_file_.applyFlows(ctx_, ctx_.current_date);
+            rdii_iface_file_.applyFlows(ctx_, routing_date);
         } else {
-            rdii_.applyRdiiInflows(ctx_);
+            rdii_.applyRdiiInflows(ctx_, routing_secs);
         }
     }
 
-    // B2b. Interface file inflows (from upstream model coupling)
-    iface_.readInflows(ctx_, ctx_.current_date);
+    // B2b. Interface file inflows (from upstream model coupling) — legacy
+    //      addIfaceInflows(currentDate), the same +1 ms date.
+    iface_.readInflows(ctx_, routing_date);
 
     // B2c. Assemble all decomposed sources into nodes.lat_flow[]
     assembleLateralInflows(dt_routing);
@@ -2661,6 +4660,8 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
     if (isInSteadyState(action_count)) {
         return;
     }
+    // legacy routeFlow: the hydraulic old state rolls only on a routed step.
+    ctx_.save_hyd_state();
 
     // B3. Hydraulic routing (batch xsect geometry → batch momentum)
     //     Includes: conduit flow, pump/orifice/weir/outlet flow,
@@ -2894,23 +4895,18 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
     surface_router_.advancePostRouting(ctx_, dt_routing, ctx_.current_time);
 #endif
 
-    // B3a. Inlet capture (street inlet HEC-22 calculations)
-    inlet_.computeAll(ctx_, dt_routing);
+    // B3a. Inlet capture (street inlet HEC-22 calculations) runs at the END of
+    //      assembleLateralInflows — i.e. BEFORE routing, like legacy
+    //      inlet_findCapturedFlows at routing.c:244. Computing it here would
+    //      write a sink into lat_flow that the next step's assembly overwrites
+    //      before the router ever sees it (plan G6).
 
-    // B3b. Culvert inlet control (FHWA HEC-5 equations)
-    //      Uses pre-built culvert_links_ (populated in initHydraulics)
-    //
-    //      NOT for FV: it applies the same closure as a cap on the flux
-    //      crossing the culvert's upstream face, inside the solver. Rewriting
-    //      links.flow here afterwards would contradict the node ledger
-    //      publishFv already booked from those fluxes.
-    if (!culvert_links_.empty() &&
-        ctx_.options.routing_model != RoutingModel::FV) {
-        culvert::batchComputeInletControl(
-            culvert_links_.data(),
-            static_cast(culvert_links_.size()),
-            ctx_);
-    }
+    // B3b. Culvert inlet control is applied where legacy applies it: inside
+    //      the dynamic-wave momentum solve, once per iteration
+    //      (dwflow.c:328 culvert_getInflow -> DWSolver::applyFlowLimits),
+    //      and by the FV solver as a cap on its upstream-face flux. Legacy
+    //      never limits a kinematic-wave culvert, and a second application
+    //      after the solve rewrote the converged flow (routing-culvert-codes).
 
     // B4. Non-conduit link flows are now computed inside the DW Picard loop
     //     via the non_conduit_fn callback passed to router_.step().
@@ -2926,9 +4922,82 @@ void SWMMEngine::stepRouting(double dt_routing) noexcept {
         inlet_.adjustQualInflows(ctx_, dt_routing);
     }
 
-    // B5. Water quality routing (P8-G13: fill stub bodies)
-    if (ctx_.n_pollutants() > 0 && !ctx_.options.ignore_quality) {
-        quality_.execute(ctx_, dt_routing);
+    // B5. Water quality routing (P8-G13: fill stub bodies).
+    //     QUALITY_SOLVER EULERIAN_ARD (master plan D-UT6, phase E1): the
+    //     external-load assembly is shared with the legacy path; the CSTR
+    //     transport stages are replaced by the ARD engine on the FV cell
+    //     mesh. Lazy first-step init because the transport mesh needs
+    //     Router::init's mod_length/rough_factor. Init failure falls back
+    //     to LEGACY with a warning — never a silent no-quality run.
+    //
+    //     R4: a reactions component keeps the stage alive with zero
+    //     pollutants — an MSX-only model has species to react but no
+    //     [POLLUTANTS] row to gate on. Bypasses that DO skip it
+    //     (EULERIAN_ARD, IGNORE_QUALITY) warn at open rather than running
+    //     silently; see transport::warnIfLegacyBindingBypassed.
+    //     H1: HEAT_TRANSPORT joins the same list for the same reason — a
+    //     temperature-only deck has no [POLLUTANTS] row to gate on, and
+    //     without this the quality stage never runs, so heat_state is never
+    //     sized and routeLegacyHeat never fires.
+    if ((ctx_.n_pollutants() > 0 ||
+         transport::legacyReactionsActive(ctx_) ||
+         ctx_.options.water_age ||
+         ctx_.options.heat_transport) &&
+        !ctx_.options.ignore_quality) {
+        if (ctx_.options.quality_solver == QualitySolverKind::EULERIAN_ARD) {
+            if (!ard_init_attempted_) {
+                ard_init_attempted_ = true;
+                const bool ok = ard_.init(ctx_);
+                for (const auto& w : ard_.warnings())
+                    ctx_.warnings.push_back(w);
+                if (!ok)
+                    ctx_.warnings.push_back(
+                        std::string(
+                            "QUALITY_SOLVER EULERIAN_ARD: transport mesh "
+                            "unavailable — falling back to LEGACY quality "
+                            "routing.") +
+                        (ctx_.ard_config.any_dispersion()
+                             ? " The transport.ard dispersion configuration "
+                               "does not apply under the LEGACY engine."
+                             : ""));
+            }
+            if (ard_.initialized()) {
+                quality_.assembleExternalLoads(ctx_, dt_routing);
+                ard_.step(ctx_, dt_routing);
+                // E5b treatment interop: the legacy evaluator runs on the
+                // PUBLISHED node concentrations (same expressions, same
+                // process variables, books its own reacted losses); the
+                // engine then absorbs the treated concentrations back into
+                // its node stores. Ordering note (documented decision):
+                // under ARD treatment applies AFTER the reaction stage at
+                // end of step, where legacy applies it before decay.
+                if (ctx_.treatment.hasAny()) {
+                    quality_.applyTreatment(ctx_, dt_routing,
+                                            /*full_inflow=*/false);
+                    ard_.absorbTreatedNodeConc(ctx_);
+                }
+            } else {
+                quality_.execute(ctx_, dt_routing);
+            }
+        } else if (ctx_.options.quality_solver ==
+                   QualitySolverKind::LAGRANGIAN) {
+            // X2: LTD segment transport. External loads come from the SAME
+            // shared loader seam both other engines consume (the ARD
+            // precedent one branch up); the solver drains them as rate×dt /
+            // volume inside its topological mixing pass. Treatment and the
+            // reactions component do not run here yet — warned at open.
+            quality_.assembleExternalLoads(ctx_, dt_routing);
+            lard_.step(ctx_, dt_routing);
+            // P2.3: treatment applies INSIDE the solver's MIX (per node,
+            // this substep's own inflow figures, before RELEASE draws the
+            // treated state) — quality::applyNodeTreatment, the seam shared
+            // with the LEGACY pass. The handoff's end-of-step call here was
+            // a no-op twice over (cin read the LEGACY accumulators, and a
+            // junction's ~zero stored volume gave the late write no weight
+            // in the next mix) and its own gate caught it on first run.
+        } else {
+            quality_.execute(ctx_, dt_routing);
+        }
     }
 }
 
@@ -3002,14 +5071,23 @@ void SWMMEngine::updateStatistics(double dt_routing) noexcept {
         // Node inflow statistics (matching legacy stats_updateNodeStats)
         double lat = ctx_.nodes.lat_flow[uj];
         double total_inflow = ctx_.nodes.inflow[uj];
-        if (std::fabs(lat) > ctx_.nodes.stat_max_lat_inflow[uj])
-            ctx_.nodes.stat_max_lat_inflow[uj] = std::fabs(lat);
+        // Signed, as legacy stats.c keeps them: a street inlet's transfer shows
+        // as a NEGATIVE lateral at its bypass node, and the Node Inflow Summary
+        // reports it that way (the peak is the largest magnitude, sign kept).
+        if (std::fabs(lat) > std::fabs(ctx_.nodes.stat_max_lat_inflow[uj]))
+            ctx_.nodes.stat_max_lat_inflow[uj] = lat;
         if (total_inflow > ctx_.nodes.stat_max_total_inflow[uj]) {
             ctx_.nodes.stat_max_total_inflow[uj] = total_inflow;
             ctx_.nodes.stat_max_inflow_date[uj] = ctx_.current_date;
         }
-        ctx_.nodes.stat_lat_inflow_vol[uj]   += std::fabs(lat) * dt_routing;
+        ctx_.nodes.stat_lat_inflow_vol[uj]   += lat * dt_routing;
         ctx_.nodes.stat_total_inflow_vol[uj] += total_inflow * dt_routing;
+        // PARITY stats.c:588 stats_updateStorageStats — a storage unit's peak
+        // RELEASE, which is what its outlet structures actually passed. Not
+        // interchangeable with peak inflow: attenuating the two is the point.
+        if (ctx_.nodes.type[uj] == NodeType::STORAGE &&
+            ctx_.nodes.outflow[uj] > ctx_.nodes.stat_storage_max_outflow[uj])
+            ctx_.nodes.stat_storage_max_outflow[uj] = ctx_.nodes.outflow[uj];
         // For outfall nodes, outflow = inflow by definition (matching legacy
         // massbal.c line 587: NodeOutflow[j] += Node[j].inflow * tStep).
         // For non-storage terminal nodes (degree==0), same treatment.
@@ -3047,6 +5125,7 @@ void SWMMEngine::updateStatistics(double dt_routing) noexcept {
         }
     }
     ensureXspCache();
+    double step_slot_vol = 0.0, step_stored_vol = 0.0;   // slot program R0
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
         double q = std::fabs(ctx_.links.flow[uj]);
@@ -3081,6 +5160,25 @@ void SWMMEngine::updateStatistics(double dt_routing) noexcept {
         if (d >= y_full && y_full > 0.0)
             ctx_.links.stat_time_surcharged[uj] += dt_routing;
 
+        // Slot-storage share accumulation (FV slot program R0). The run
+        // share is ∫slot dt / ∫stored dt — a ratio of integrals, never an
+        // average of ratios. All terms are 0 under the dynamic-wave router.
+        {
+            const double v  = ctx_.links.volume[uj];
+            const double sv = ctx_.links.slot_volume[uj];
+            ctx_.links.stat_vol_dt[uj]      += v  * dt_routing;
+            step_stored_vol += v;
+            if (sv > 0.0) {
+                ctx_.links.stat_slot_vol_dt[uj] += sv * dt_routing;
+                step_slot_vol += sv;
+                const double share = (v > 0.0) ? sv / v : 0.0;
+                if (share > ctx_.links.stat_peak_slot_share[uj])
+                    ctx_.links.stat_peak_slot_share[uj] = share;
+                if (share > 0.01)
+                    ctx_.links.stat_time_slot_above[uj] += dt_routing;
+            }
+        }
+
         // Conduit surcharge detail tracking (upstream/downstream/both)
         // Gap #57: use persistent full_state set by routing solver (area/depth-based).
         if (ctx_.links.type[uj] == LinkType::CONDUIT && y_full > 0.0) {
@@ -3198,6 +5296,29 @@ void SWMMEngine::updateStatistics(double dt_routing) noexcept {
             }
         }
     }
+
+    // System-level slot share (FV slot program R0): the peak instantaneous
+    // share and the time above the 1 % budget need the per-step totals; the
+    // run-level integrated share is recovered at report time by summing the
+    // per-link integrals.
+    if (step_slot_vol > 0.0) {
+        const double sys_share =
+            (step_stored_vol > 0.0) ? step_slot_vol / step_stored_vol : 0.0;
+        if (sys_share > ctx_.routing_stats.slot_peak_share)
+            ctx_.routing_stats.slot_peak_share = sys_share;
+        if (sys_share > 0.01)
+            ctx_.routing_stats.slot_time_above_s += dt_routing;
+    }
+    // OPENSWMM_FV_SLOT_TRACE=1 → one CSV row per routing step on stdout.
+    static const bool slot_trace = []() {
+        const char* e = std::getenv("OPENSWMM_FV_SLOT_TRACE");
+        return e && *e && *e != '0';
+    }();
+    if (slot_trace && step_stored_vol > 0.0) {
+        std::printf("SLOT_TRACE,%.6f,%.6g,%.6g,%.6g\n",
+                    ctx_.current_time, step_slot_vol, step_stored_vol,
+                    step_slot_vol / step_stored_vol);
+    }
 }
 
 // ============================================================================
@@ -3242,7 +5363,13 @@ void SWMMEngine::updateRoutingMassBalance(double dt_routing) noexcept {
     // B7. Mass balance update (P8-G12: routing totals)
     //     Accumulate ALL flow paths matching legacy massbal_updateRoutingTotals
     ctx_.mass_balance.step_flooding  = 0.0;
-    ctx_.mass_balance.step_outflow   = 0.0;
+    // legacy StepFlowTotals.outflow: the withdrawals (negative external
+    // inflows, addExternalInflows) come first, the outfall / flooding terms
+    // of removeOutflows follow in node order below.
+    ctx_.mass_balance.step_outflow   = ctx_.mass_balance.step_ext_withdrawal;
+    double step_loss_rate = 0.0;   // legacy StepFlowTotals.evapLoss + seepLoss
+    double step_ww_rate   = 0.0;   // legacy StepFlowTotals.wwInflow
+    ctx_.mass_balance.routing_outflow += ctx_.mass_balance.step_ext_withdrawal * dt_routing;
 
     // Accumulate DWF, GW, RDII, and external inflow volumes from step accumulators
     // (step accumulators are set during Inflow::computeAll / RDIISolver::computeAll
@@ -3270,65 +5397,179 @@ void SWMMEngine::updateRoutingMassBalance(double dt_routing) noexcept {
     // degree==0 non-STORAGE nodes are interior under FV exactly as under DW.
     const bool is_dw = (ctx_.options.routing_model == RoutingModel::DYNWAVE ||
                         ctx_.options.routing_model == RoutingModel::FV);
+    const int np = ctx_.n_pollutants();
+
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
         const NodeType nt = ctx_.nodes.type[uj];
+        double quality_outflow = 0.0;
+        bool quality_flooding = false;
 
         if (nt == NodeType::OUTFALL) {
-            // Legacy node_getSystemOutflow (node.c:428-447) + removeOutflows
-            // (routing.c:921-931): an outfall's system flow is its pipe inflow
-            // when discharging. When the outfall instead sends water BACK into
-            // the network (outflow > 0, inflow == 0 — e.g. a 2D tailwater or a
-            // FIXED/TIDAL/TIMESERIES stage above the upstream HGL), the system
-            // flow is NEGATIVE and legacy books it as an EXTERNAL system INFLOW
-            // of magnitude outflow (massbal_addInflowFlow(EXTERNAL_INFLOW, -q)).
-            // Mirroring that closes routing continuity for any backflowing
-            // outfall (a pre-existing gap for tidal/fixed outfalls, and required
-            // for the 2D-coupled withdrawal path in transferOutfallDischarges).
-            double q_in  = ctx_.nodes.inflow[uj];
-            double q_out = ctx_.nodes.outflow[uj];
-            if (q_out > 0.0 && q_in <= 0.0) {
-                // Backflow into the network — system external inflow. step_*
-                // is added here (after the step_ext_inflow consumption at the
-                // top of this function) for the per-step snapshot only,
-                // mirroring the coupling-spill booking below.
-                ctx_.mass_balance.routing_external += q_out * dt_routing;
-                ctx_.mass_balance.step_ext_inflow  += q_out;
-            } else {
-                // Normal discharge — system outflow = inflow.
-                ctx_.mass_balance.routing_outflow += q_in * dt_routing;
-                ctx_.mass_balance.step_outflow    += q_in;
-
-                // Gap #28: accumulate outfall discharge as routed volume for next
-                // runoff step (matching legacy Outfall[i].vRouted accumulation).
+            // legacy removeOutflows + node_getSystemOutflow (routing.c:
+            // 906-935, node.c:414-447), in that order:
+            //   1. the outfall's inflow (before anything below rewrites it)
+            //      accumulates as routed volume for a RouteTo subcatchment;
+            //   2. system flow q: outflow == 0 -> q = inflow (a discharging
+            //      outfall); else, inflow == 0 -> q = -outflow and
+            //      Node.inflow = |q| (an outfall FEEDING the network — a
+            //      FIXED/TIDAL/TIMESERIES stage above the HGL, or here a
+            //      FREE outfall whose weir runs backwards); else NOTHING;
+            //   3. q > 0 books outflow, q <= 0 books EXTERNAL inflow -q.
+            // The earlier "backflow if outflow>0 && inflow<=0, else discharge"
+            // booked an outfall carrying BOTH — the state a skipped
+            // SKIP_STEADY_STATE step inherits from rule 2's inflow write —
+            // as outflow: weir-overtopping's Spill added its 1186 cfs
+            // reverse flow to OUTFALL_FLOWS on every skipped step.
+            const double q_in  = ctx_.nodes.inflow[uj];
+            const double q_out = ctx_.nodes.outflow[uj];
+
+            // Gap #28: routed volume for the next runoff step (legacy
+            // Outfall[k].vRouted, from Node.inflow > 0).
+            {
                 const int ofr = ctx_.node_subtypes.outfall_row(static_cast(uj));
                 int sc = (ofr >= 0)
                     ? ctx_.node_subtypes.outfalls.route_to[static_cast(ofr)] : -1;
                 if (sc >= 0 && sc < ctx_.n_subcatches() && q_in > 0.0) {
                     auto usc = static_cast(sc);
                     ctx_.subcatches.outfall_runon_vol[usc] += q_in * dt_routing;
+                    // A4: water returning from an outfall carries that
+                    // node's age. Without it the run-on age is divided by a
+                    // rate this volume contributed to but its age did not.
+                    auto& wo = ctx_.water_age_state.subcatch_outfall_age_vol;
+                    if (ctx_.options.water_age && usc < wo.size() &&
+                        uj < ctx_.water_age_state.node_age.size())
+                        wo[usc] += q_in * dt_routing *
+                                   ctx_.water_age_state.node_age[uj];
+                    // H5a: and that node's temperature, at the same seam.
+                    auto& ho = ctx_.heat_state.subcatch_outfall_temp_vol;
+                    if (ctx_.options.heat_transport && usc < ho.size() &&
+                        uj < ctx_.heat_state.node_temp.size())
+                        ho[usc] += q_in * dt_routing *
+                                   ctx_.heat_state.node_temp[uj];
+                }
+            }
+
+            double q_sys = 0.0;
+            if (ctx_.options.routing_model == RoutingModel::FV) {
+                // FV books an outfall's boundary discharge in BOTH halves of
+                // its ledger (publishFv: face flux in, boundary flux out), so
+                // legacy's "both nonzero -> nothing" would drop it; FV keeps
+                // the direct rule: feeding the network when it only sends,
+                // discharging its inflow otherwise.
+                if (q_out > 0.0 && q_in <= 0.0) {
+                    q_sys = -q_out;
+                    ctx_.nodes.inflow[uj] = q_out;
+                } else {
+                    q_sys = q_in;
                 }
+            } else if (q_out == 0.0) {
+                q_sys = q_in;
+            } else if (q_in == 0.0) {
+                q_sys = -q_out;
+                // Legacy node_getSystemOutflow (node.c:441-444): a backflowing
+                // outfall reports its discharge magnitude as node inflow.
+                ctx_.nodes.inflow[uj] = std::fabs(q_sys);
+            }
+            if (q_sys > 0.0) {
+                quality_outflow = q_sys;
+                ctx_.mass_balance.routing_outflow += q_sys * dt_routing;
+                ctx_.mass_balance.step_outflow    += q_sys;
+            } else {
+                // massbal_addInflowFlow(EXTERNAL_INFLOW, -q): step_* is added
+                // here (after the step_ext_inflow consumption at the top of
+                // this function) for the per-step snapshot only.
+                ctx_.mass_balance.routing_external += -q_sys * dt_routing;
+                ctx_.mass_balance.step_ext_inflow  += -q_sys;
+            }
+            // Legacy node_getSystemOutflow zeroes an outfall's overflow and
+            // volume every step (node.c:445-447) so an outfall never reports
+            // flooding or stored volume. Applied for the tree-layout routers
+            // only: KW/SF setNewNodeState computes a raw net-inflow overflow
+            // at outfalls that legacy discards here. DW outfalls never
+            // acquire overflow (boundary-condition depth path), so the DW
+            // behavior is left untouched.
+            if (!is_dw) {
+                ctx_.nodes.overflow[uj] = 0.0;
+                ctx_.nodes.volume[uj]   = 0.0;
             }
         }
         else if (!is_dw && ctx_.nodes.degree[uj] == 0 && nt != NodeType::STORAGE) {
-            // Non-DW terminal node: counted as system outflow.
-            ctx_.mass_balance.routing_outflow += ctx_.nodes.inflow[uj] * dt_routing;
-            ctx_.mass_balance.step_outflow    += ctx_.nodes.inflow[uj];
+            // Non-DW terminal node (no OUTFLOW links — legacy KW degree):
+            // its inflow is system outflow, and legacy node_getSystemOutflow
+            // (node.c:453-459) zeroes its overflow and volume so it reports
+            // neither flooding nor storage.
+            if (ctx_.nodes.outflow[uj] == 0.0) {
+                quality_outflow = ctx_.nodes.inflow[uj];
+                ctx_.mass_balance.routing_outflow += ctx_.nodes.inflow[uj] * dt_routing;
+                ctx_.mass_balance.step_outflow    += ctx_.nodes.inflow[uj];
+            }
+            ctx_.nodes.overflow[uj] = 0.0;
+            ctx_.nodes.volume[uj]   = 0.0;
         }
         else {
             // Interior node (also DW terminal nodes): overflow counted as
-            // flooding only if newVolume <= fullVolume (matching legacy).
+            // flooding only if newVolume <= fullVolume (matching legacy). The
+            // dynamic wave AND the tree routers book volume in the legacy
+            // convention, whose full volume is rpt_full_volume (0 for a
+            // junction, so a ponded one is never booked as flooding —
+            // 304-nodes-234-subs under KW booked a ponded junction's
+            // overflow as FLOOD_LOSSES against the MIN_SURFAREA full volume);
+            // FV books it against full_volume.
+            const double full_vol =
+                (ctx_.options.routing_model == RoutingModel::FV)
+                    ? ctx_.nodes.full_volume[uj]
+                    : ctx_.nodes.rpt_full_volume[uj];
             if (ctx_.nodes.overflow[uj] > 0.0 &&
-                ctx_.nodes.volume[uj] <= ctx_.nodes.full_volume[uj]) {
+                ctx_.nodes.volume[uj] <= full_vol) {
+                quality_outflow = ctx_.nodes.overflow[uj];
+                quality_flooding = true;
                 ctx_.mass_balance.routing_flooding += ctx_.nodes.overflow[uj] * dt_routing;
                 ctx_.mass_balance.step_flooding    += ctx_.nodes.overflow[uj];
             }
         }
 
-        // Node evaporation and seepage losses
-        ctx_.mass_balance.routing_evap_loss += ctx_.nodes.losses[uj] * dt_routing;
+        // Legacy removeOutflows (routing.c:1016-1042) books quality through
+        // the SAME system-outflow classification as water, including a
+        // non-DW terminal junction and unponded flooding. An OUTFALL-only
+        // pass discarded all exported mass from ejemplo-epa's terminal 50.
+        if (quality_outflow > 0.0) {
+            auto& total = quality_flooding ? ctx_.mass_balance.qual_routing_flood
+                                          : ctx_.mass_balance.qual_routing_outflow;
+            for (int p = 0; p < np; ++p) {
+                const auto up = static_cast(p);
+                total[up] += quality_outflow * ctx_.nodes.conc[uj * np + up] * dt_routing;
+            }
+        }
+        // Negative lateral flow withdraws the current mixed concentration.
+        // Its water has already been booked by the inflow assembly.
+        if (ctx_.nodes.lat_flow[uj] < 0.0) {
+            for (int p = 0; p < np; ++p) {
+                const auto up = static_cast(p);
+                ctx_.mass_balance.qual_routing_outflow[up] +=
+                    -ctx_.nodes.lat_flow[uj] * ctx_.nodes.conc[uj * np + up] * dt_routing;
+            }
+        }
+
+        // Storage losses are separate volumes (legacy removeStorageLosses,
+        // routing.c:927-951). nodes.losses combines their rates and would
+        // mislabel all storage exfiltration as evaporation in the report.
+        const int sr = ctx_.node_subtypes.storage_row(j);
+        if (sr >= 0) {
+            const auto us = static_cast(sr);
+            ctx_.mass_balance.routing_evap_loss += ctx_.node_subtypes.storages.evap_loss[us];
+            ctx_.mass_balance.routing_seep_loss += ctx_.node_subtypes.storages.exfil_loss[us];
+        }
+        step_loss_rate += ctx_.nodes.losses[uj];
     }
 
+    // A street inlet's capture node hands its overflow back to the corridor as
+    // backflow, so that water never left the system and must come back out of
+    // the flooding total just booked. Legacy's slot exactly: routing.c:259-260
+    // runs removeSystemOutflows() then inlet_adjustQualOutflows(). Node-level
+    // flooding statistics are unaffected — updateStatistics() has already run.
+    inlet_.adjustFloodingTotals(ctx_, dt_routing);
+
     // Accumulate link evaporation and seepage losses
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
@@ -3339,8 +5580,19 @@ void SWMMEngine::updateRoutingMassBalance(double dt_routing) noexcept {
             int barrels = std::max((cr >= 0) ? CD.barrels[ucr] : 1, 1);
             ctx_.mass_balance.routing_evap_loss +=
                 ((cr >= 0) ? CD.evap_loss_rate[ucr] : 0.0) * barrels * dt_routing;
+            // G-X4: the seepage rate is SIGNED once a conduit is coupled to
+            // the two-zone aquifer. The two halves are booked to opposite
+            // sides of the balance — a loss to `routing_seep_loss`, a gain to
+            // `routing_link_gw_inflow` — so neither term can be quietly
+            // cancelled by the other and the .rpt shows what actually
+            // happened on a reach that switched direction mid-storm.
+            const double seep_rate_s = (cr >= 0) ? CD.seep_loss_rate[ucr] : 0.0;
             ctx_.mass_balance.routing_seep_loss +=
-                ((cr >= 0) ? CD.seep_loss_rate[ucr] : 0.0) * barrels * dt_routing;
+                std::max(seep_rate_s, 0.0) * barrels * dt_routing;
+            ctx_.mass_balance.routing_link_gw_inflow +=
+                std::max(-seep_rate_s, 0.0) * barrels * dt_routing;
+            step_loss_rate += ((cr >= 0) ? CD.evap_loss_rate[ucr] : 0.0) * barrels
+                            + seep_rate_s * barrels;
         }
     }
 
@@ -3354,6 +5606,10 @@ void SWMMEngine::updateRoutingMassBalance(double dt_routing) noexcept {
             auto uj = static_cast(j);
             if (ctx_.nodes.runoff_inflow[uj] > 0.0)
                 runoff_q += ctx_.nodes.runoff_inflow[uj];
+            // LID drains to nodes are WET_WEATHER inflow in legacy
+            // (lid_addDrainInflow → massbal_addInflowFlow(WET_WEATHER_INFLOW)).
+            if (uj < lid_drain_q_interp_.size() && lid_drain_q_interp_[uj] > 0.0)
+                runoff_q += lid_drain_q_interp_[uj];
             if (const double q_user = effectiveUserLatFlow(ctx_, uj);
                 q_user > 0.0)
                 user_q_total += q_user;
@@ -3363,52 +5619,55 @@ void SWMMEngine::updateRoutingMassBalance(double dt_routing) noexcept {
         if (runoff_q > 0.0) {
             ctx_.mass_balance.routing_wet_weather += runoff_q * dt_routing;
         }
+        step_ww_rate = runoff_q;
         if (user_q_total > 0.0) {
             ctx_.mass_balance.routing_forcing_inflow += user_q_total * dt_routing;
         }
-        // 1D → 2D coupling spill folds into routing_flooding (and the
-        // per-step accumulator) so it appears under the existing "Flooding
-        // Loss" row in the continuity report. The positive (2D → 1D) side
+        // C2 (2026-09-07): the 1D → 2D spill gets its OWN outflow category.
+        // It used to fold into routing_flooding, which reported a coupling
+        // TRANSFER under "Flooding Loss": the water did not flood, it moved
+        // to the 2D surface, where MassBalance2D::coupling_1d_to_2d_in books
+        // it arriving. Both ledgers were individually right and the sum was
+        // conserved — only the row a modeller reads was wrong.
+        //
+        // It is still an outflow of the 1D system, so routing_error() is
+        // unchanged (routing_coupling_out joins total_out where the spill's
+        // share of routing_flooding used to sit). The positive (2D → 1D) side
         // was already added to step_ext_inflow → routing_external by
         // assembleLateralInflows. See review §11.
+        //
+        // step_flooding keeps the spill in BOTH groupings: it drives the
+        // per-step flood reporting and node flooding statistics, which are
+        // about "water leaving the node upward" — and a spill is that,
+        // whatever row the continuity table puts it in.
         if (coupling_out_q > 0.0) {
-            ctx_.mass_balance.routing_flooding += coupling_out_q * dt_routing;
-            ctx_.mass_balance.step_flooding    += coupling_out_q;
+#ifdef OPENSWMM_HAS_2D
+            const bool as_flooding =
+                ctx_.twod_io.options && ctx_.twod_io.options->coupling_in_flooding;
+#else
+            // No surface coupling exists in a build without the 2D feature.
+            const bool as_flooding = false;
+#endif
+            if (as_flooding)
+                ctx_.mass_balance.routing_flooding     += coupling_out_q * dt_routing;
+            else
+                ctx_.mass_balance.routing_coupling_out += coupling_out_q * dt_routing;
+            ctx_.mass_balance.step_flooding += coupling_out_q;
         }
     }
 
-    // Quality routing mass balance (matching legacy massbal_updateRoutingTotals)
-    int np = ctx_.n_pollutants();
-    if (np > 0) {
-        for (int j = 0; j < ctx_.n_nodes(); ++j) {
-            auto uj = static_cast(j);
-
-            // Wet weather quality inflow: lateral flow × concentration
-            if (ctx_.nodes.lat_flow[uj] > 0.0) {
-                for (int p = 0; p < np; ++p) {
-                    auto qi = uj * static_cast(np) + static_cast(p);
-                    if (qi < ctx_.nodes.conc.size()) {
-                        double load = ctx_.nodes.lat_flow[uj] *
-                                      ctx_.nodes.conc[qi] * dt_routing;
-                        if (load > 0.0)
-                            ctx_.mass_balance.qual_routing_wet[static_cast(p)] += load;
-                    }
-                }
-            }
-
-            // Quality outflow at outfalls: inflow × concentration
-            if (ctx_.nodes.type[uj] == NodeType::OUTFALL && ctx_.nodes.inflow[uj] > 0.0) {
-                for (int p = 0; p < np; ++p) {
-                    auto qi = uj * static_cast(np) + static_cast(p);
-                    if (qi < ctx_.nodes.conc.size()) {
-                        double load = ctx_.nodes.inflow[uj] *
-                                      ctx_.nodes.conc[qi] * dt_routing;
-                        if (load > 0.0)
-                            ctx_.mass_balance.qual_routing_outflow[static_cast(p)] += load;
-                    }
-                }
-            }
-        }
+    // legacy massbal_getStepFlowError on THIS step's StepFlowTotals, read
+    // by isInSteadyState at the start of the next step (routing.c:234,
+    // before massbal_initTimeStepTotals clears them).
+    {
+        const auto& mb = ctx_.mass_balance;
+        const double total_in  = mb.step_dw_inflow + step_ww_rate + mb.step_gw_inflow +
+                                 mb.step_rdii_inflow + mb.step_ext_inflow;
+        const double total_out = mb.step_flooding + mb.step_outflow + step_loss_rate;
+        double err = 0.0;
+        if (std::fabs(total_in) > 0.0)       err = 1.0 - total_out / total_in;
+        else if (std::fabs(total_out) > 0.0) err = total_in / total_out - 1.0;
+        ctx_.mass_balance.last_step_flow_error = err;
     }
 }
 
@@ -3432,18 +5691,31 @@ void SWMMEngine::computeFinalStorage() noexcept {
             auto ui = static_cast(i);
             double fi = soa.imperv_pct[ui];
             double fp = 1.0 - fi;
-            double f0 = fi * soa.imperv0_pct[ui];
-            double f1 = fi * (1.0 - soa.imperv0_pct[ui]);
+            double f0 = soa.frac_imperv0[ui];
+            double f1 = soa.frac_imperv1[ui];
             double area = soa.area[ui]; // ft²
             ctx_.mass_balance.runoff_final_store +=
                 (soa.depth_imperv0[ui] * f0
                  + soa.depth_imperv1[ui] * f1
                  + soa.depth_perv[ui] * fp) * area;
         }
-        // Credit water retained inside LID units — otherwise LID retention
-        // reads as a continuity leak (issue #102 C). Matches legacy
-        // subcatch_getStorage()'s + lid_getStoredVolume() term.
-        ctx_.mass_balance.runoff_final_store += lid_.totalStoredVolume();
+        // Water still held in LID units is runoff-system storage (legacy
+        // massbal counts lid_getStoredVolume() in final storage).
+        ctx_.mass_balance.runoff_final_store += lid_.storedVolume();
+
+        // F8 — the pack still standing, and the snow ploughed out of the
+        // system. Legacy massbal.c:671-679.
+        ctx_.mass_balance.runoff_final_snow =
+            snowCoverVolumeFt3(ctx_, snow_.state());
+        // `runoff_snowremov` HAD NO WRITER ANYWHERE. It was declared, exposed
+        // through `SWMM_RUNOFF_SNOWREMOV`, returned by the mass-balance API
+        // and read by callers — and nothing ever assigned it, so every deck
+        // that ploughs snow reported zero removal while `SnowSoA::removed`
+        // accumulated the real figure with no consumer. Same shape as F1
+        // (`setMeltCoeffs` with no caller) and as the snapshot quality
+        // vectors that wrote every pollutant column as zero: a field that
+        // exists, is exposed, is read, and is never written.
+        ctx_.mass_balance.runoff_snowremov = snow_.state().removed;
     }
 
     // (LID exfiltration / evaporation are folded into the runoff-continuity
@@ -3464,6 +5736,39 @@ void SWMMEngine::computeFinalStorage() noexcept {
         auto uj = static_cast(j);
         ctx_.mass_balance.routing_final_storage += ctx_.links.volume[uj];
     }
+
+    // B8a. Final stored pollutant mass — the closing term of the quality
+    //      ledger, mirroring the opening term recorded in initMassBalance().
+    //      Without it every quality continuity error was reported as the whole
+    //      of the mass still in the system (~51 % on a steady feed).
+    //      Legacy: massbal_getStoredMass().
+    {
+        const int np = ctx_.n_pollutants();
+        for (int p = 0; p < np; ++p) {
+            const auto up = static_cast(p);
+            if (up >= ctx_.mass_balance.qual_routing_final.size()) break;
+            double m = 0.0;
+            for (int j = 0; j < ctx_.n_nodes(); ++j) {
+                const auto idx = static_cast(j) *
+                                 static_cast(np) + up;
+                if (idx < ctx_.nodes.conc.size())
+                    m += ctx_.nodes.conc[idx] * reportedNodeVolume(j);
+            }
+            for (int j = 0; j < ctx_.n_links(); ++j) {
+                const auto uj  = static_cast(j);
+                const auto idx = uj * static_cast(np) + up;
+                if (idx < ctx_.links.conc.size())
+                    m += ctx_.links.conc[idx] * ctx_.links.volume[uj];
+            }
+            // Legacy adds the stored mass ON TOP of what
+            // massbal_addToFinalStorage booked as links went dry during the
+            // run (massbal.c:885); without that term the litre-or-less each
+            // drying conduit gives up surfaces as continuity error.
+            if (up < ctx_.mass_balance.qual_routing_final_dry.size())
+                m += ctx_.mass_balance.qual_routing_final_dry[up];
+            ctx_.mass_balance.qual_routing_final[up] = m;
+        }
+    }
 }
 
 // ============================================================================
@@ -3546,8 +5851,12 @@ void convertSnapshotToDisplay(SimulationSnapshot& s, const ucf::DisplayUnits& du
     scale(s.links.depth,    du.length);
     scale(s.links.velocity, du.length);
     scale(s.links.volume,   du.volume);
-    // System scalars (legacy SysResults order)
-    s.sys_temperature = du.temperature(s.sys_temperature);
+    // System scalars (legacy SysResults order).
+    // The temperature conversion is AFFINE, so it must be skipped — not merely
+    // fed a zero — on a model with no subcatchments; see
+    // SimulationSnapshot::has_subcatchments.
+    if (s.has_subcatchments)
+        s.sys_temperature = du.temperature(s.sys_temperature);
     s.sys_rainfall   *= du.rainfall;
     s.sys_snow_depth *= du.raindepth;
     s.sys_infil      *= du.rainfall;
@@ -3611,7 +5920,9 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             snap.link_count       = ctx_.n_links();
             snap.subcatch_count   = ctx_.n_subcatches();
             snap.gage_count       = ctx_.n_gages();
-            snap.pollut_count     = ctx_.n_pollutants();
+            // A2b: the reported species block is pollutants + the water-age
+            // pseudo-column, so consumers stride by the REPORTED count.
+            snap.pollut_count     = ctx_.n_reported_species();
             snap.flow_units_code  = static_cast(ctx_.options.flow_units);
 
             // Legacy-parity interpolation weight at the report instant
@@ -3642,8 +5953,25 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
                                    + f_rt  * ctx_.nodes.depth[ui];
                     snap.nodes.depth[ui] = y;
                     // Placeholder; rewritten below in float32 arithmetic to
-                    // reproduce legacy NODE_HEAD bit-for-bit.
-                    snap.nodes.head[ui] = ctx_.nodes.invert_elev[ui] + y;
+                    // reproduce legacy NODE_HEAD bit-for-bit. Under
+                    // REPORT_SIGNED_HEADS (issue #156 O-6) the HEAD field
+                    // carries the TRUE signed head, interpolated like every
+                    // other snapshot field via the SIGNED offset head−invert
+                    // (== depth exactly for any node at/above its invert, so
+                    // never-negative decks differ from the legacy rewrite by
+                    // float32 rounding only). There is no old_head array; the
+                    // old endpoint uses the floored old_depth, so a sub-invert
+                    // excursion is attenuated toward the invert only when the
+                    // report instant falls strictly inside a routing span.
+                    // DEPTH stays floored either way. (A point-in-time head
+                    // was measured 2.175 ft off the interpolated series on a
+                    // never-negative FV corpus deck — P5 task-2 finding.)
+                    snap.nodes.head[ui] = ctx_.options.report_signed_heads
+                        ? ctx_.nodes.invert_elev[ui]
+                          + f1_rt * ctx_.nodes.old_depth[ui]
+                          + f_rt  * (ctx_.nodes.head[ui]
+                                     - ctx_.nodes.invert_elev[ui])
+                        : ctx_.nodes.invert_elev[ui] + y;
                     snap.nodes.volume[ui] =
                         f1_rt * reportedNodeVolume(i, ctx_.nodes.old_depth[ui],
                                                    ctx_.nodes.old_volume[ui])
@@ -3712,12 +6040,13 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
                 }
             }
 
-            // When rpt_averages is enabled, overwrite node/link snapshot arrays
-            // with time-step-averaged values (subcatchments stay point-in-time,
-            // matching legacy behavior).
-            if (ctx_.options.rpt_averages) {
-                applyAvgResults(snap);
-            }
+            // When rpt_averages is enabled, the node/link snapshot arrays are
+            // overwritten with time-step averages AFTER the display-unit
+            // conversion below (the accumulators hold float32 DISPLAY values,
+            // legacy output.c:72). The averaging machinery covers ONLY nodes
+            // and links — legacy writes subcatchment results via
+            // subcatch_getResults(j, f) unconditionally (output.c:479-490),
+            // so the interpolated subcatch blocks below run in ALL modes.
 
             // Copy subcatchment state
             // Rainfall, infil, and evap all come from the most recent runoff
@@ -3730,6 +6059,66 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             snap.subcatch.runoff   = ctx_.subcatches.runoff;
             snap.subcatch.gw_flow  = ctx_.subcatches.gw_flow;
 
+            // Legacy-parity reported losses on LID subcatchments. Legacy
+            // (subcatch.c:740-744) reports rates averaged over the FULL
+            // subcatchment area and includes the LID units' own losses:
+            //   evapLoss  = Vevap / tStep / area   (Vevap includes LID evap)
+            //   infilLoss = (Vinfil + VlidInfil) / tStep / area
+            // This engine keeps evap_loss/infil_loss averaged over the
+            // NON-LID area with the LID losses ledgered separately (see
+            // accumulateRunoffMassBalance) — coherent internally, but the
+            // reported value must be legacy's. Rebuild it here from the
+            // non-LID rate and the LID units' last-step losses (per-step
+            // depths over each unit's area; the last runoff step's span is
+            // the divisor legacy used when it formed the rate).
+            {
+                const double land2ft2 =
+                    1.0 / ucf::UCF(ucf::LANDAREA, ctx_.options);
+                const double dt_last =
+                    (new_runoff_ms_ - old_runoff_ms_) / 1000.0;
+                const auto& rsoa = runoff_.soa();
+                std::vector lid_evap_cfs, lid_infil_cfs;
+                for (int t = 0; t < lid_.numGroups(); ++t) {
+                    const auto& g = lid_.group(t);
+                    for (int u = 0; u < g.count; ++u) {
+                        auto uu = static_cast(u);
+                        int sc = g.subcatch_idx[uu];
+                        if (sc < 0 || sc >= ctx_.n_subcatches() ||
+                            dt_last <= 0.0) continue;
+                        if (lid_evap_cfs.empty()) {
+                            auto un = static_cast(
+                                ctx_.n_subcatches());
+                            lid_evap_cfs.assign(un, 0.0);
+                            lid_infil_cfs.assign(un, 0.0);
+                        }
+                        auto usc = static_cast(sc);
+                        lid_evap_cfs[usc] +=
+                            g.evap_loss[uu] * g.area[uu] / dt_last;
+                        lid_infil_cfs[usc] +=
+                            g.infil_loss[uu] * g.area[uu] / dt_last;
+                    }
+                }
+                for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+                    auto ui = static_cast(i);
+                    if (ctx_.subcatches.total_lid_area_ft2[ui] <= 0.0)
+                        continue;
+                    const double full_ft2 =
+                        ctx_.subcatches.area[ui] * land2ft2;
+                    if (full_ft2 <= 0.0) continue;
+                    const double nonlid_ft2 = rsoa.area[ui];
+                    const double ev = lid_evap_cfs.empty()
+                        ? 0.0 : lid_evap_cfs[ui];
+                    const double in = lid_infil_cfs.empty()
+                        ? 0.0 : lid_infil_cfs[ui];
+                    snap.subcatch.evap[ui] =
+                        (ctx_.subcatches.evap_loss[ui] * nonlid_ft2 + ev)
+                        / full_ft2;
+                    snap.subcatch.infil[ui] =
+                        (ctx_.subcatches.infil_loss[ui] * nonlid_ft2 + in)
+                        / full_ft2;
+                }
+            }
+
             // Report subcatchment RUNOFF time-interpolated between the old/new
             // WET_STEP values, matching legacy subcatch_getResults (subcatch.c:865)
             // + output.c:323 which use f = (reportTime-OldRunoffTime)/span. The
@@ -3737,9 +6126,10 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             // column previously used the raw constant new value, so the reported
             // runoff stepped instead of ramping within a WET_STEP. This is
             // OUTPUT-ONLY (the applied routing inflow is unchanged). Legacy also
-            // zeroes runoff below MIN_RUNOFF * area_ft2. Skipped under rpt_averages
-            // (that path accumulates its own average).
-            if (!ctx_.options.rpt_averages) {
+            // zeroes runoff below MIN_RUNOFF * area_ft2. Runs in ALL report
+            // modes — the averages machinery covers only nodes/links; legacy
+            // interpolates subcatchments unconditionally (output.c:479-490).
+            {
                 constexpr double MIN_RUNOFF = 2.31481e-8;  // ft/s (legacy consts.h)
                 // Weight at the REPORT instant (legacy output.c:593):
                 // f = (reportTime - OldRunoffTime)/(NewRunoffTime - OldRunoffTime).
@@ -3758,9 +6148,30 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
                     auto ui = static_cast(i);
                     double ro = f1 * ctx_.subcatches.old_runoff[ui]
                               + f  * ctx_.subcatches.runoff[ui];
+                    // Legacy adds the interpolated LID drain to reported
+                    // runoff BEFORE the MIN_RUNOFF cutoff, gated on
+                    // lidArea > 0 (subcatch.c:897-905).
+                    if (ctx_.subcatches.total_lid_area_ft2[ui] > 0.0)
+                        ro += f1 * ctx_.subcatches.old_lid_drain_flow[ui]
+                            + f  * ctx_.subcatches.lid_drain_flow[ui];
                     if (ro < MIN_RUNOFF * (ctx_.subcatches.area[ui] * land2ft2))
                         ro = 0.0;
                     snap.subcatch.runoff[ui] = ro;
+                    // Legacy interpolates GW flow on the same runoff-clock
+                    // weight (subcatch.c:909-910); the raw copy above only
+                    // sized the array.
+                    // subcatch.c:912 interpolates the RATE, then multiplies
+                    // by the subcatchment area (same op order as the routing
+                    // inflow above).
+                    {
+                        const double a_ft2 = ctx_.subcatches.area[ui]
+                                           / ucf::UCF(ucf::LANDAREA, ctx_.options);
+                        const double r_new = (ui < groundwater_.state().gw_flow.size())
+                                           ? groundwater_.state().gw_flow[ui] : 0.0;
+                        const double r_old = (ui < old_gw_rate_.size())
+                                           ? old_gw_rate_[ui] : 0.0;
+                        snap.subcatch.gw_flow[ui] = (f1 * r_old + f * r_new) * a_ft2;
+                    }
                 }
             }
 
@@ -3776,97 +6187,63 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
                     auto us = static_cast(s);
                     int aq = ctx_.subcatches.gw_aquifer[us];
                     if (aq >= 0) {
-                        auto uaq = static_cast(aq);
-                        double bot = ctx_.aquifers.bottom_elev[uaq];
-                        snap.subcatch.gw_elev[us] = bot + gw.lower_depth[us];
+                        // legacy subcatch_getResults: (lowerDepth + bottomElev)
+                        // with both in ft (the row's Ebot when given).
+                        snap.subcatch.gw_elev[us] = gw.bottom_elev[us] + gw.lower_depth[us];
                         snap.subcatch.soil_moist[us] = gw.theta[us];
                     }
                 }
             }
 
-            // Per-subcatch snow depth (from snow pack state)
+            // Per-subcatch snow depth: legacy interpolates oldSnowDepth/
+            // newSnowDepth to the report instant on the runoff-clock weight
+            // (subcatch.c:888-890) — in ALL report modes. The per-step SWE
+            // recompute now lives in stepRunoff (ctx_.subcatches.snow_depth).
             {
                 const int nS = ctx_.n_subcatches();
                 snap.subcatch.snow_depth.resize(static_cast(nS), 0.0);
-                const auto& soa = snow_.state();
+                const double span = new_runoff_ms_ - old_runoff_ms_;
+                const double f = (span > 0.0)
+                               ? (ctx_.next_report_ms - old_runoff_ms_) / span
+                               : 1.0;
+                const double f1 = 1.0 - f;
                 for (int s = 0; s < nS; ++s) {
                     auto us = static_cast(s);
-                    if (ctx_.subcatches.snowpack[us] < 0) continue;
-                    double fi = ctx_.subcatches.frac_imperv[us];
-                    double sn = (us < soa.snn.size()) ? soa.snn[us] : 0.0;
-                    double fArea[3] = { sn * fi, (1.0 - sn) * fi, 1.0 - fi };
-                    int base = s * snow::N_SUBAREAS;
-                    double sd = 0.0;
-                    for (int k = 0; k < snow::N_SUBAREAS; ++k) {
-                        auto uk = static_cast(base + k);
-                        if (uk < soa.wsnow.size())
-                            sd += soa.wsnow[uk] * fArea[k];
-                    }
-                    snap.subcatch.snow_depth[us] = sd;
-                }
-            }
-
-            // System-level results
-            snap.sys_temperature = ctx_.climate_state.temperature;
-
-            // Area-weighted average rainfall across subcatchments
-            // (matching legacy output_saveSubcatchResults accumulation)
-            // Uses snap.subcatch.rainfall (queried at report time above)
-            {
-                double total_rain = 0.0;
-                double total_area = 0.0;
-                for (int s = 0; s < ctx_.n_subcatches(); ++s) {
-                    auto us = static_cast(s);
-                    double a = ctx_.subcatches.area[us];
-                    total_rain += snap.subcatch.rainfall[us] * a;
-                    total_area += a;
+                    snap.subcatch.snow_depth[us] =
+                        f1 * ctx_.subcatches.old_snow_depth[us]
+                        + f * ctx_.subcatches.snow_depth[us];
                 }
-                snap.sys_rainfall = (total_area > 0.0)
-                    ? total_rain / total_area : 0.0;
             }
 
-            // Area-weighted average snow depth across all subcatchments.
-            // Gap #60: weight by non-LID area (matches legacy snow_getSnowCover).
-            {
-                double total_snow = 0.0;
-                double total_area = 0.0;
-                for (int s = 0; s < ctx_.n_subcatches(); ++s) {
-                    auto us = static_cast(s);
-                    double a = ctx_.subcatches.area[us]
-                               - ctx_.subcatches.total_lid_area_ft2[us] / 43560.0;
-                    if (a < 0.0) a = 0.0;
-                    total_snow += snap.subcatch.snow_depth[us] * a;
-                    total_area += a;
-                }
-                snap.sys_snow_depth = (total_area > 0.0) ? total_snow / total_area : 0.0;
-            }
-            snap.sys_pet = ctx_.climate_state.evap_rate;
-
-            // Area-weighted averages of evap and infil; total runoff
-            // Legacy adds GW evaporation (gw->evapLoss) to system evap
-            // (output.c:612-613): SYS_EVAP += gw->evapLoss * UCF(EVAPRATE) * area
-            {
-                double tot_evap = 0.0, tot_infil = 0.0, tot_runoff = 0.0;
-                double total_area = 0.0;
-                const auto& gw = groundwater_.state();
-                for (int i = 0; i < ctx_.n_subcatches(); ++i) {
-                    auto ui = static_cast(i);
-                    double a = ctx_.subcatches.area[ui];
-                    tot_evap   += ctx_.subcatches.evap_loss[ui] * a;
-                    // Add GW evaporation (matching legacy output.c:612-613)
-                    if (ctx_.subcatches.gw_aquifer[ui] >= 0 &&
-                        ui < gw.upper_evap.size()) {
-                        double gw_evap = gw.upper_evap[ui] + gw.lower_evap[ui];
-                        tot_evap += gw_evap * a;
-                    }
-                    tot_infil  += ctx_.subcatches.infil_loss[ui] * a;
-                    tot_runoff += ctx_.subcatches.runoff[ui];
-                    total_area += a;
-                }
-                snap.sys_evap   = (total_area > 0.0) ? tot_evap / total_area : 0.0;
-                snap.sys_infil  = (total_area > 0.0) ? tot_infil / total_area : 0.0;
-                snap.sys_runoff = tot_runoff;
-            }
+            // System-level results.
+            //
+            // Legacy assigns SYS_TEMPERATURE and SYS_PET at the END of
+            // output_saveSubcatchResults, and that function is called only
+            // behind `if (Nobjects[SUBCATCH] > 0)` (output.c:489-490). On a
+            // deck with NO subcatchments both therefore stay at the
+            // zero-initialised value of SysResults — regardless of the
+            // temperature data or the unit system. Reproducing that is not
+            // cosmetic: on an SI model this engine correctly converts its
+            // 0 degF to -17.78 degC, which is a defensible number and a parity
+            // failure on every period (extran-family and other pipe-only decks
+            // are exactly this shape).
+            const bool has_subcatchments = ctx_.n_subcatches() > 0;
+            snap.has_subcatchments = has_subcatchments;
+            snap.sys_temperature =
+                has_subcatchments ? ctx_.climate_state.temperature : 0.0;
+
+            // The subcatchment-derived system results (rainfall, snow depth,
+            // evap, infil, runoff) are computed AFTER the unit-conversion
+            // boundary from the reported per-subcatch float32 values — see the
+            // legacy-REAL4 accumulation block below. Zero them here so a deck
+            // with no subcatchments writes legacy's zero-initialised
+            // SysResults and the conversion boundary scales inert values.
+            snap.sys_rainfall   = 0.0;
+            snap.sys_snow_depth = 0.0;
+            snap.sys_evap       = 0.0;
+            snap.sys_infil      = 0.0;
+            snap.sys_runoff     = 0.0;
+            snap.sys_pet = has_subcatchments ? ctx_.climate_state.evap_rate : 0.0;
 
             snap.sys_dw_inflow  = ctx_.mass_balance.step_dw_inflow;
             snap.sys_gw_inflow  = ctx_.mass_balance.step_gw_inflow;
@@ -3875,22 +6252,55 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             snap.sys_flooding   = ctx_.mass_balance.step_flooding;
             snap.sys_outflow    = ctx_.mass_balance.step_outflow;
 
-            // Total storage volume (sum of node + link volumes). Nodes use the
-            // legacy-convention reported volume (junctions => 0, as legacy
-            // node_getVolume) so SYS_STORAGE matches legacy rather than crediting
-            // the MIN_SURFAREA junction-state volume (same basis as #A).
+            // Total storage volume — the SUM OF THE REPORTED node and link
+            // volumes, not of the raw end-of-step state. Legacy accumulates
+            // SYS_STORAGE from the routing-time-INTERPOLATED NodeResults /
+            // LinkResults it is writing (output.c:667, 700), in a REAL4
+            // accumulator (element-by-element float rounding). Summing the
+            // un-interpolated ctx state diverged from the per-element output
+            // during transients (deadend repro: 1.0127 vs 1.0046 at period 0)
+            // even though every element cell matched. snap.nodes/links.volume
+            // are internal-unit; legacy accumulates display-unit REAL4 —
+            // convert per element before the float add, then return to
+            // internal units (convertSnapshotToDisplay scales sys_storage).
             {
-                double tot_store = 0.0;
-                for (int j = 0; j < ctx_.n_nodes(); ++j)
-                    tot_store += reportedNodeVolume(j);
-                for (int j = 0; j < ctx_.n_links(); ++j)
-                    tot_store += ctx_.links.volume[static_cast(j)];
-                snap.sys_storage = tot_store;
+                const double vol_ucf = ucf::Ucf[ucf::VOLUME][
+                    ucf::getUnitSystem(static_cast(ctx_.options.flow_units))];
+                float tot_store = 0.0f;
+                if (ctx_.options.rpt_averages) {
+                    // Averages mode: legacy output_saveAvgResults sums the
+                    // RAW end-of-step volumes over ALL nodes then ALL links
+                    // (output.c:926-948, Node/Link newVolume), not the
+                    // averaged or interpolated report values.
+                    for (int j = 0; j < ctx_.n_nodes(); ++j)
+                        tot_store += static_cast(
+                            reportedNodeVolume(j) * vol_ucf);
+                    for (std::size_t uj = 0; uj < ctx_.links.volume.size(); ++uj)
+                        tot_store += static_cast(
+                            ctx_.links.volume[uj] * vol_ucf);
+                } else {
+                    for (std::size_t uj = 0; uj < snap.nodes.volume.size(); ++uj)
+                        tot_store += static_cast(snap.nodes.volume[uj] * vol_ucf);
+                    for (std::size_t uj = 0; uj < snap.links.volume.size(); ++uj)
+                        tot_store += static_cast(snap.links.volume[uj] * vol_ucf);
+                }
+                snap.sys_storage = static_cast(tot_store) / vol_ucf;
             }
 
             // 2D surface routing state (deep-copied; empty when 2D inactive,
             // and Default2DOutputPlugin::update() short-circuits on
-            // surface_tri_count == 0).
+            // surface_tri_count == 0). The render fields refresh on the
+            // REPORT_STEP grid; bring them up to date first for the case where
+            // the report instant does not land on a co-advance batch boundary.
+#ifdef OPENSWMM_HAS_2D
+            if (surface_router_.isActive()) {
+                // Close any pending (COUPLING_SYNC-batched) 2D window first
+                // so the report-time blend brackets the report instant; a
+                // no-op under default per-routing-step coupling.
+                surface_router_.flushPendingBatch(ctx_);
+                surface_router_.refreshRenderFieldsIfStale();
+            }
+#endif
             fillSurfaceSnapshot(snap);
 
             // Single conversion boundary: convert the 1D snapshot to project
@@ -3899,6 +6309,14 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             const auto du = ucf::DisplayUnits::from(ctx_.options);
             convertSnapshotToDisplay(snap, du);
 
+            // Averages mode: overwrite node/link arrays with the float32
+            // display-unit averages (legacy output_saveAvgResults). Must be
+            // after the conversion boundary — the accumulators already hold
+            // display values.
+            if (ctx_.options.rpt_averages) {
+                applyAvgResults(snap);
+            }
+
             // Reproduce legacy node_getResults() NODE_HEAD bit-for-bit (node.c:484-486):
             //   x[NODE_DEPTH] = (float)(depth_disp);
             //   x[NODE_HEAD]  = x[NODE_DEPTH] + (float)(invertElev * UCF(LENGTH));
@@ -3912,7 +6330,11 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             // unit system, including SI where du.length != 1.0. Skipped under
             // rpt_averages (that path averages the double head; legacy averages the
             // per-step float32 head — a separate concern from this 1-ULP instant bug).
-            if (!ctx_.options.rpt_averages) {
+            // Skipped under REPORT_SIGNED_HEADS (issue #156 O-6): the parity
+            // rewrite derives head from the FLOORED depth, which is exactly
+            // what the option exists to bypass.
+            if (!ctx_.options.rpt_averages &&
+                !ctx_.options.report_signed_heads) {
                 const std::size_t nn =
                     std::min(snap.nodes.head.size(), snap.nodes.depth.size());
                 for (std::size_t i = 0; i < nn; ++i) {
@@ -3946,12 +6368,336 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
                 }
             }
 
+            // Legacy-parity subcatchment-derived system results. Legacy
+            // accumulates SysResults (a REAL4 array) from the REPORTED
+            // per-subcatch float32 display-unit values as it writes them
+            // (output.c:596-630): SYS_RUNOFF is a plain float sum of
+            // SUBCATCH_RUNOFF, the others are area-weighted with a REAL4
+            // running totalArea and divided in float at the end. Summing the
+            // raw double state diverged three ways: no report-time
+            // interpolation, no MIN_RUNOFF zeroing (an LID draining to
+            // pervious keeps a sub-threshold trickle alive that legacy
+            // reports as 0.0 system runoff for the rest of the run), and
+            // double instead of float32 rounding. The writer's SYS_INFLOW
+            // (reader name TOTAL_LATFLOW) is a float sum that includes
+            // SYS_RUNOFF, so it inherits this fix. Placed after the
+            // conversion boundary (and after the gage report-rainfall
+            // overwrite) so the accumulation sees exactly the float32 values
+            // the writer emits; ctx_.subcatches.area is already in display
+            // land-area units (legacy's Subcatch[j].area * UCF(LANDAREA)).
+            if (has_subcatchments) {
+                float total_area = 0.0f;
+                float a_rain = 0.0f, a_snow = 0.0f, a_evap = 0.0f;
+                float a_infil = 0.0f, a_runoff = 0.0f;
+                const auto& gw = groundwater_.state();
+                // legacy's area operand here is a ROUND TRIP, not the authored
+                // number: [SUBCATCHMENTS] stores `area = x[3] / UCF(LANDAREA)`
+                // (subcatch.c:197) and output_saveSubcatchResults multiplies it
+                // straight back, `area = Subcatch[j].area * UCF(LANDAREA)`
+                // (output.c:608). Division then multiplication in double is not
+                // the identity, and this engine keeps the authored value, so
+                // the two operands differed in the last place — enough to tip
+                // the float32 rounding of `reported * area` by one ulp and put
+                // the area-weighted system rows one ulp out. usgs-5-pollutants
+                // read 0.63000005 of system rainfall where legacy reads 0.63,
+                // on a deck where every subcatchment sees the same gage.
+                const double ucf_land = ucf::UCF(ucf::LANDAREA, ctx_.options);
+                for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+                    auto ui = static_cast(i);
+                    const double area =
+                        (ctx_.subcatches.area[ui] / ucf_land) * ucf_land;
+                    total_area += static_cast(area);
+                    a_rain += static_cast(
+                        static_cast(snap.subcatch.rainfall[ui]) * area);
+                    a_snow += static_cast(
+                        static_cast(snap.subcatch.snow_depth[ui]) * area);
+                    a_evap += static_cast(
+                        static_cast(snap.subcatch.evap[ui]) * area);
+                    // Legacy adds GW evaporation un-rounded (output.c:616-617):
+                    // SYS_EVAP += (REAL4)(gw->evapLoss * UCF(EVAPRATE) * area)
+                    if (ctx_.subcatches.gw_aquifer[ui] >= 0 &&
+                        ui < gw.upper_evap.size()) {
+                        a_evap += static_cast(
+                            (gw.upper_evap[ui] + gw.lower_evap[ui]) *
+                            du.evaprate * area);
+                    }
+                    a_infil += static_cast(
+                        static_cast(snap.subcatch.infil[ui]) * area);
+                    a_runoff += static_cast(snap.subcatch.runoff[ui]);
+                }
+                if (total_area > 0.0) {
+                    a_evap  /= total_area;
+                    a_rain  /= total_area;
+                    a_snow  /= total_area;
+                    a_infil /= total_area;
+                }
+                snap.sys_rainfall   = static_cast(a_rain);
+                snap.sys_snow_depth = static_cast(a_snow);
+                snap.sys_evap       = static_cast(a_evap);
+                snap.sys_infil      = static_cast(a_infil);
+                snap.sys_runoff     = static_cast(a_runoff);
+            }
+
+            // ---------------------------------------------------------------
+            // Pollutant concentrations.
+            //
+            // These three vectors are what DefaultOutputPlugin (binary .out)
+            // and GeoPackageOutputPlugin write into their pollutant columns.
+            // NOTHING populated them: both readers guard with
+            // `qi < size()` and fall back to 0.0, so every pollutant column
+            // in every .out file was written as ZERO while the header
+            // advertised the column count and unit codes. The engine's own
+            // state was correct throughout (nodes.conc / links.conc carry
+            // the routed values, which is why the transport gates — all of
+            // which read the arrays directly — never saw it).
+            //
+            // Interpolation matches the neighbouring fields AND legacy:
+            //   node.c:502    z = f1*oldQual[p] + wt*newQual[p]
+            //   link.c:724    c = f1*oldQual[p] + f *newQual[p]
+            //   subcatch.c:929-930  runoff == 0 ? 0 : f1*old + wt*new
+            // Concentrations are already in user units (no UCF applies).
+            // IGNORE_QUALITY leaves the vectors EMPTY, which is also what
+            // the writer wants (it sets n_polluts_ = 0 in that mode).
+            //
+            // A2b: the reported block is (pollutants, then water age when
+            // enabled) — see ctx_.reported_species_names. TWO strides are in
+            // play and must not be confused (lessons 14/15): the SOURCE
+            // arrays are np-strided (nodes.conc etc.), the REPORTED arrays
+            // are nr-strided. Age converts SECONDS → HOURS here, the unit
+            // the plan reports it in (§1).
+            if (!ctx_.options.ignore_quality &&
+                ctx_.n_reported_species() > 0) {
+                const auto np_s = static_cast(ctx_.n_pollutants());
+                const auto nr_s =
+                    static_cast(ctx_.n_reported_species());
+                const auto nN_s = static_cast(ctx_.n_nodes());
+                const auto nL_s = static_cast(ctx_.n_links());
+                const auto nS_s = static_cast(ctx_.n_subcatches());
+                const bool age_col = ctx_.options.water_age && nr_s > np_s;
+                // H1: temperature is the trailing column, after age when
+                // both are on. Its index is derived from the SAME toggle
+                // that built reported_species_names, so the two cannot
+                // disagree without the species-name gate catching it.
+                const bool temp_col = ctx_.options.heat_transport;
+                const std::size_t temp_i = np_s + (ctx_.options.water_age ? 1u : 0u);
+                constexpr double kSecPerHour = 3600.0;
+                // Reported-depth threshold for "this element holds water".
+                // Deliberately tiny: the intent is to exclude elements the
+                // report itself shows as empty, not to impose a physical
+                // wetting depth.
+                constexpr double kDryReportDepth = 1.0e-9;
+
+                snap.node_quality.assign(nN_s * nr_s, 0.0);
+                for (std::size_t n = 0; n < nN_s; ++n) {
+                    for (std::size_t p = 0; p < np_s; ++p) {
+                        const std::size_t src = n * np_s + p;
+                        if (src < ctx_.nodes.conc.size() &&
+                            src < ctx_.nodes.conc_old.size())
+                            snap.node_quality[n * nr_s + p] =
+                                f1_rt * ctx_.nodes.conc_old[src] +
+                                f_rt * ctx_.nodes.conc[src];
+                    }
+                    // Age is a published state (already the step's value),
+                    // so it takes no old/new interpolation — there is no
+                    // node_age_old to weight against.
+                    //
+                    // DRY-ELEMENT MASK (A2b carry c). An element with no
+                    // water still ages in the STATE — it has to, or a
+                    // refilling pipe would jump discontinuously and a
+                    // hotstart would lose the age it must restore — but
+                    // REPORTING that age is nonsense: validation saw links
+                    // publish exactly 6.000000 h of age on water that never
+                    // existed. The mask lives at the report boundary only,
+                    // keyed on the element's own REPORTED depth, so the
+                    // record is internally consistent (a reader seeing
+                    // depth 0 sees age 0) and the state is untouched. Same
+                    // shape as legacy's washoff runoff gate
+                    // (subcatch.c:929), which reports 0 rather than a
+                    // residual concentration.
+                    //
+                    // Keyed on DEPTH, not reported volume: legacy maps a
+                    // junction's reported volume to 0 by convention, so a
+                    // volume test would mask every junction age in the
+                    // model.
+                    if (age_col && n < ctx_.water_age_state.node_age.size()) {
+                        const bool wet = (n < snap.nodes.depth.size() &&
+                                          snap.nodes.depth[n] > kDryReportDepth);
+                        snap.node_quality[n * nr_s + np_s] =
+                            wet ? ctx_.water_age_state.node_age[n] / kSecPerHour
+                                : 0.0;
+                    }
+                    // H1 temperature. NOTE THE OPPOSITE CALL from age above,
+                    // and it is deliberate: there is NO dry-element mask on
+                    // temperature. The age mask can write 0 because zero age
+                    // is unambiguous — no water has ever been 0 h old and
+                    // present. Zero DEGREES is an ordinary temperature, so a
+                    // mask here would publish "freezing" for "empty" and a
+                    // reader could not tell the two apart. Reporting the
+                    // carried state is the lesser of the two wrongs; it is
+                    // recorded as a convention rather than defended as
+                    // correct, and the honest fix is a per-column no-data
+                    // convention the .out format does not currently have.
+                    if (temp_col && n < ctx_.heat_state.node_temp.size())
+                        snap.node_quality[n * nr_s + temp_i] =
+                            ctx_.heat_state.node_temp[n];
+                }
+
+                snap.link_quality.assign(nL_s * nr_s, 0.0);
+                for (std::size_t l = 0; l < nL_s; ++l) {
+                    for (std::size_t p = 0; p < np_s; ++p) {
+                        const std::size_t src = l * np_s + p;
+                        if (src < ctx_.links.conc.size() &&
+                            src < ctx_.links.conc_old.size())
+                            snap.link_quality[l * nr_s + p] =
+                                f1_rt * ctx_.links.conc_old[src] +
+                                f_rt * ctx_.links.conc[src];
+                    }
+                    // Dry-element mask — see the node comment above, but note
+                    // the test differs, and has to. A node reports depth 0
+                    // when empty; a LINK never does, because the dynamic-wave
+                    // router floors a dry conduit at FUDGE (1e-4 ft). That is
+                    // 1e5 times any "tiny" depth threshold, so a depth test
+                    // cannot fire on the very case this mask exists for —
+                    // measured on the bone-dry gate deck: depth
+                    // 9.99999975e-05 and age 6.166667 h, the original defect
+                    // untouched.
+                    //
+                    // Links therefore key on VOLUME (the field that IS
+                    // meaningful for them — the inverse of the node trap),
+                    // against the volume the quality subsystem itself calls
+                    // empty. Read from INTERNAL state so the comparison is
+                    // unit-safe: snap volumes are in user units, ZERO_VOLUME
+                    // is ft3. Using the transport's own criterion means the
+                    // age is reported exactly when the age was routed.
+                    //
+                    // ...OR the link is CONVEYING water. A pump, orifice or
+                    // weir stores nothing — volume is 0 by construction — but
+                    // it carries flow, and its link_age is its upstream
+                    // node's age, which is a real number a user wants
+                    // (measured: pump 0.124060 h against node J1's 0.124060).
+                    // A volume-only test would blank the age of every
+                    // regulator in every model, which is the node trap again
+                    // with the fields exchanged. An idle regulator has
+                    // neither volume nor flow and is still masked.
+                    if (age_col && l < ctx_.water_age_state.link_age.size()) {
+                        const bool holds =
+                            (l < ctx_.links.volume.size() &&
+                             ctx_.links.volume[l] > quality::ZERO_VOLUME);
+                        const bool conveys =
+                            (l < ctx_.links.flow.size() &&
+                             std::fabs(ctx_.links.flow[l]) > constants::TINY);
+                        const bool wet = holds || conveys;
+                        snap.link_quality[l * nr_s + np_s] =
+                            wet ? ctx_.water_age_state.link_age[l] / kSecPerHour
+                                : 0.0;
+                    }
+                    // H1 temperature — unmasked, for the reason given in the
+                    // node loop (0 degC is a real temperature, so it cannot
+                    // double as "no water").
+                    if (temp_col && l < ctx_.heat_state.link_temp.size())
+                        snap.link_quality[l * nr_s + temp_i] =
+                            ctx_.heat_state.link_temp[l];
+                }
+
+                // Subcatchment washoff carries legacy's runoff gate: a
+                // subcatchment with no runoff reports 0, not its residual
+                // concentration (subcatch.c:929). A3 landed the watershed
+                // age states, so the age column below now reports the age of
+                // the water being shed rather than the placeholder 0 this
+                // comment used to promise.
+                snap.subcatch_quality.assign(nS_s * nr_s, 0.0);
+                // The washoff blend below rides the RUNOFF clock, not the
+                // routing clock. legacy keeps two separate report weights —
+                // output_saveSubcatchResults forms
+                //   f = (reportTime - OldRunoffTime)/(NewRunoffTime - OldRunoffTime)
+                // (output.c:593) and hands it to subcatch_getResults, while
+                // output_saveNodeResults forms its own from the ROUTING
+                // times. This block used the routing weight (f_rt), which
+                // inside a 15-minute runoff step sits near 1 on every routing
+                // step, so the reported concentration was essentially the new
+                // value every period instead of sweeping old -> new across
+                // the runoff step. greenroofs' subcatchment 9 published 1983
+                // mg/L of TSS on the first wet period where legacy publishes
+                // 92, then decayed ~3.5x per period against legacy's ~0.85 —
+                // a front-loaded first flush that never happened. The mass
+                // was never affected, which is why the deck's washoff total
+                // matched legacy exactly while its time series did not.
+                const double ro_span_q = new_runoff_ms_ - old_runoff_ms_;
+                const double f_ro_q = (ro_span_q > 0.0)
+                    ? (ctx_.next_report_ms - old_runoff_ms_) / ro_span_q
+                    : 1.0;
+                const double f1_ro_q = 1.0 - f_ro_q;
+                for (std::size_t s = 0; s < nS_s; ++s) {
+                    // H5a temperature — written BEFORE the runoff gate, and
+                    // unmasked, exactly as the node and link loops above do.
+                    //
+                    // Until 2026-08-22 there was no writer here at all: the
+                    // age row below had one and temperature did not, so
+                    // subcatch_quality kept the assign(…, 0.0) and the output
+                    // plugin faithfully wrote the zero. Measured on
+                    // tests/parity/transport/heat_parity.inp — nodes and links
+                    // carried −4.147…17.66 °C while every subcatchment read
+                    // exactly 0.0 for the whole run. The column existed in the
+                    // header the whole time, which is why a column-presence
+                    // check passed over it.
+                    //
+                    // It is OUTSIDE the has_runoff gate on purpose, and that
+                    // is a deliberate divergence from the age column beside
+                    // it. Age is gated because legacy's washoff convention
+                    // says a subcatchment producing nothing reports nothing.
+                    // Temperature cannot use that convention: 0 °C is a real
+                    // temperature and cannot double as "no water" — the same
+                    // reasoning H1 applied at nodes and links. D-H5c exists
+                    // precisely so the dry-element value is the deck's choice
+                    // (HOLD | AIR | DEFAULT) rather than an accident, so the
+                    // state carries a meaningful number when dry and blanking
+                    // it here would throw that away.
+                    if (temp_col && s < ctx_.heat_state
+                                            .subcatch_runoff_temp.size())
+                        snap.subcatch_quality[s * nr_s + temp_i] =
+                            ctx_.heat_state.subcatch_runoff_temp[s];
+
+                    // The gate is legacy's OWN reported runoff — the one
+                    // interpolated onto the report instant, with the LID
+                    // drain added and the MIN_RUNOFF * area cutoff applied
+                    // (subcatch.c:894-905, then :927-931 `if (runoff ==
+                    // 0.0) z = 0.0`). Testing the raw NEW state instead let
+                    // a subcatchment whose reported runoff had been zeroed
+                    // publish a washoff concentration anyway: every EMC
+                    // deck reported its full concentration at period 0,
+                    // where legacy reports 0 because no water has left yet.
+                    const bool has_runoff =
+                        (s < snap.subcatch.runoff.size() &&
+                         snap.subcatch.runoff[s] != 0.0);
+                    if (!has_runoff) continue;
+                    for (std::size_t p = 0; p < np_s; ++p) {
+                        const std::size_t src = s * np_s + p;
+                        if (src < ctx_.subcatches.conc.size() &&
+                            src < ctx_.subcatches.conc_old.size())
+                            snap.subcatch_quality[s * nr_s + p] =
+                                f1_ro_q * ctx_.subcatches.conc_old[src] +
+                                f_ro_q * ctx_.subcatches.conc[src];
+                    }
+                    // A3 retires the placeholder that reported 0 here: the
+                    // subcatchment now publishes the age of the water it is
+                    // shedding, in HOURS like every other age column. Gated
+                    // on has_runoff above, which is legacy's own washoff
+                    // convention — a subcatchment producing nothing reports
+                    // nothing rather than the age of a puddle it is keeping.
+                    if (age_col && s < ctx_.water_age_state
+                                           .subcatch_runoff_age.size())
+                        snap.subcatch_quality[s * nr_s + np_s] =
+                            ctx_.water_age_state.subcatch_runoff_age[s] /
+                            kSecPerHour;
+                }
+            }
+
             // Attach name table pointers (valid for lifetime of ctx_)
             snap.node_ids     = &ctx_.node_names.names();
             snap.link_ids     = &ctx_.link_names.names();
             snap.subcatch_ids = &ctx_.subcatch_names.names();
             snap.gage_ids     = &ctx_.gage_names.names();
-            snap.pollut_names = &ctx_.pollutant_names.names();
+            snap.pollut_names = &ctx_.reported_species_names;
 
             io_thread_.post(std::move(snap));
         }
@@ -3965,6 +6711,8 @@ void SWMMEngine::postOutputSnapshot(double /*dt_step*/) noexcept {
             // never consumed; DefaultReportPlugin::update() is a no-op.
             SimulationSnapshot snap;
             snap.sim_time = report_date;
+            surface_router_.flushPendingBatch(ctx_);
+            surface_router_.refreshRenderFieldsIfStale();
             fillSurfaceSnapshot(snap);
             io_thread_.post(std::move(snap));
         }
@@ -3978,17 +6726,136 @@ void SWMMEngine::fillSurfaceSnapshot(SimulationSnapshot& snap) const noexcept {
 #ifdef OPENSWMM_HAS_2D
     if (!surface_router_.isActive()) return;
     const auto& st  = surface_router_.state();
-    snap.surface_tri_count     = surface_router_.mesh().n_triangles();
-    snap.surface_vert_count    = surface_router_.mesh().n_vertices();
+    const auto& msh = surface_router_.mesh();
+    snap.surface_tri_count     = msh.n_triangles();
+    snap.surface_vert_count    = msh.n_vertices();
+    snap.surface_quad_count    = msh.n_quads();
+    snap.surface_edge_stride   = msh.edge_stride();
+    if (snap.surface_quad_count > 0) snap.surface_cell_nv = msh.cell_nv;
+    else                             snap.surface_cell_nv.clear();
     snap.surface_depth          = st.depth;
     snap.surface_head           = st.head;
+    // Report-time blend (the 2D analogue of the 1D old/new interpolation):
+    // continuous cell state — depth and head only — is blended to the exact
+    // report instant, so snap.sim_time is truthful for these fields instead
+    // of carrying window-end state stamped with the report date. Derived and
+    // forcing fields (gradients, vertex/render fields, rainfall, coupling
+    // flux, loss cumulatives, edge flux, species) stay current-valued: they are
+    // instantaneous forcings, window-mean contracts, or reconstruction
+    // outputs whose recompute on blended copies would be a full extra
+    // machinery pass (mixed time base, documented — same spirit as legacy's
+    // derived quantities). Internal state, coupling heads, and the API
+    // getters are untouched; the blend lives in the snapshot COPIES only.
+    {
+        const double f = surface_router_.reportWeight(ctx_.next_report_ms);
+        if (f < 1.0) {
+            const double f1 = 1.0 - f;
+            const auto& od = surface_router_.reportOldDepth();
+            const auto& oh = surface_router_.reportOldHead();
+            const std::size_t n =
+                std::min(snap.surface_depth.size(), od.size());
+            for (std::size_t i = 0; i < n; ++i) {
+                snap.surface_depth[i] = f1 * od[i] + f * snap.surface_depth[i];
+                snap.surface_head[i]  = f1 * oh[i] + f * snap.surface_head[i];
+            }
+        }
+    }
     snap.surface_grad_hx        = st.grad_hx;
     snap.surface_grad_hy        = st.grad_hy;
     snap.surface_grad_hx_lim    = st.grad_hx_lim;
     snap.surface_grad_hy_lim    = st.grad_hy_lim;
-    snap.surface_rainfall       = st.rainfall;
+    // Rainfall is reported as the .out reports subcatchment rainfall: the
+    // gage rate current at the report instant (the rate that starts there),
+    // not the rate applied over the window that ended there. The applied
+    // volume is Mesh2_face_rain_cum.
+    surface_router_.reportRainfall(ctx_, snap.sim_time, snap.surface_rainfall);
     snap.surface_coupling_flux  = st.coupling_flux;
     snap.surface_net_source     = st.net_source;
+    // Per-cell infiltration (plan §5.5.6). The held rate lives on the surface
+    // state; the cumulative depth comes from the ROUTER's applied-loss
+    // accumulator (SurfaceRouter2D::infilCumulative) rather than
+    // Infil2D::cumulative(), so sum(infil_cum * area) equals the ledger's
+    // infil_out exactly. It is empty when no [2D_INFILTRATION*] model
+    // resolved — publish zeros then, so both sidecar variables always carry
+    // one full [nFace] row per time step.
+    snap.surface_infil_rate     = st.infil_rate;
+    // Overland transport S1: species concentration per cell, derived from the
+    // mass store behind the hydraulics' own dry threshold. Species-major, one
+    // block per species, so the plugin can write a [time, species, face]
+    // dataset with a single extend.
+    {
+        const auto& tr = st.transport;
+        snap.surface_species_count = tr.n_species;
+        snap.surface_species_names = tr.active() ? &tr.row_names : nullptr;
+        if (tr.active()) {
+            const auto& mesh = surface_router_.mesh();
+            const double dry_depth = surface_router_.options().dry_depth;
+            const auto nt = static_cast(tr.n_cells);
+            snap.surface_species_conc.assign(
+                static_cast(tr.n_species) * nt, 0.0);
+            for (int sp = 0; sp < tr.n_species; ++sp) {
+                // S4b: the age row is an age-volume in SECONDS; every other
+                // age column the engine reports is in HOURS (the .out node /
+                // link / subcatchment columns above), so the 2D file is too.
+                const double scale = (sp == tr.age_row) ? 1.0 / 3600.0 : 1.0;
+                for (int c = 0; c < tr.n_cells; ++c) {
+                    const double v_dry = dry_depth * mesh.tri_area[c];
+                    snap.surface_species_conc[static_cast(sp) * nt +
+                                              static_cast(c)] =
+                        scale * tr.concentration(sp, c, st.volume[c], v_dry);
+                }
+            }
+            // S4b: per-row unit labels so the file is self-describing —
+            // pollutant units from [POLLUTANTS], MSX units from the reactions
+            // component, hours for age, degC for temperature.
+            surface_species_units_.assign(static_cast(tr.n_species),
+                                          std::string{});
+            for (int sp = 0; sp < tr.n_species; ++sp) {
+                std::string& u = surface_species_units_[static_cast(sp)];
+                if (sp == tr.age_row)            u = "hours";
+                else if (sp == tr.temp_row)      u = "degC";
+                else if (sp < tr.n_pollut) {
+                    const auto up = static_cast(sp);
+                    u = "MG/L";
+                    if (up < ctx_.pollutants.units.size()) {
+                        if (ctx_.pollutants.units[up] == MassUnits::UG_PER_L)     u = "UG/L";
+                        if (ctx_.pollutants.units[up] == MassUnits::COUNTS_PER_L) u = "#/L";
+                    }
+                } else {
+                    const auto um = static_cast(sp - tr.n_pollut);
+                    u = (um < ctx_.reactions.species_units.size())
+                            ? ctx_.reactions.species_units[um] : std::string{"1"};
+                }
+            }
+            snap.surface_species_units = &surface_species_units_;
+        } else {
+            snap.surface_species_conc.clear();
+            snap.surface_species_units = nullptr;
+        }
+        // S7: the cells' buildup store, per surface species, user mass per
+        // unit land area — the same number the .rpt and the C API report.
+        const auto& sq = surface_router_.surfaceQuality();
+        if (sq.active()) {
+            const auto nt = static_cast(sq.nCells());
+            snap.surface_buildup_count = sq.nSpecies();
+            snap.surface_buildup.assign(static_cast(sq.nSpecies()) * nt, 0.0);
+            for (int s = 0; s < sq.nSpecies(); ++s)
+                for (int c = 0; c < sq.nCells(); ++c)
+                    snap.surface_buildup[static_cast(s) * nt +
+                                         static_cast(c)] = sq.buildupPerArea(c, s);
+        } else {
+            snap.surface_buildup_count = 0;
+            snap.surface_buildup.clear();
+        }
+    }
+    const auto& infil_cum = surface_router_.infilCumulative();
+    if (infil_cum.size() == st.infil_rate.size())
+        snap.surface_infil_cum = infil_cum;
+    else
+        snap.surface_infil_cum.assign(st.infil_rate.size(), 0.0);
+    // Rain integrates the gage step function to the report boundary, even
+    // when the routing window extends past it (depth/head use a blend).
+    snap.surface_rain_cum = surface_router_.reportRainCumulative(ctx_.next_report_ms);
     // Output sign convention: the integrator stores edge_flux and the face
     // velocity INFLOW-positive (a positive edge_flux raises the cell — see
     // SurfaceFluxCalculator), whereas the documented public/HDF5 convention
@@ -3996,8 +6863,18 @@ void SWMMEngine::fillSurfaceSnapshot(SimulationSnapshot& snap) const noexcept {
     // reported velocity is the physical down-gradient flow. Flip the sign here,
     // at the output boundary only; the internal state is untouched so the volume
     // update and mass balance are unaffected.
-    snap.surface_edge_flux      = st.edge_flux;
-    for (double& f : snap.surface_edge_flux) f = -f;
+    // Public stride: pack the internal kMaxCellVerts-stride slots down to 3
+    // for an all-triangle mesh so pre-quad consumers see the historical
+    // [tri*3+edge] layout; mixed meshes publish the full stride.
+    {
+        const int stride = snap.surface_edge_stride;
+        const int nc     = snap.surface_tri_count;
+        snap.surface_edge_flux.assign(static_cast(nc) * stride, 0.0);
+        for (int c = 0; c < nc; ++c)
+            for (int k = 0; k < stride; ++k)
+                snap.surface_edge_flux[static_cast(c) * stride + k] =
+                    -st.edge_flux[static_cast(twoD::MeshData::slot(c, k))];
+    }
     snap.surface_vert_head      = st.vert_head;
     snap.surface_vert_depth     = st.vert_depth_signed;
     snap.surface_face_vx        = st.face_vx;
@@ -4009,6 +6886,99 @@ void SWMMEngine::fillSurfaceSnapshot(SimulationSnapshot& snap) const noexcept {
     snap.surface_stat_max_depth    = st.stat_max_depth;
     snap.surface_stat_max_velocity = st.stat_max_velocity;
     snap.surface_stat_max_cont_err = st.stat_max_cont_err;
+    // G-O: the two-zone aquifer's per-cell state and ledgers, SI, straight
+    // from the kernel's state (the same arrays swmm_gw2d_get_cell_bulk reads).
+    {
+        const auto& gw = surface_router_.subsurface();
+        snap.gw2d_active = gw.active();
+        if (gw.active()) {
+            const auto& g = gw.state();
+            const auto n = static_cast(g.n_cells);
+            snap.gw2d_table_elev.assign(n, 0.0);
+            for (std::size_t c = 0; c < n; ++c)
+                snap.gw2d_table_elev[c] = g.z_bed[c] + g.hg[c];
+            snap.gw2d_hg            = g.hg;
+            snap.gw2d_hu            = g.hu;
+            snap.gw2d_recharge      = g.q0_last;
+            snap.gw2d_lateral       = g.qlat_last;
+            snap.gw2d_node_exchange = g.qnode_last;
+            snap.gw2d_deep          = g.qdeep_last;
+            snap.gw2d_et            = g.qet_last;
+            snap.gw2d_dunne         = g.dunne_last;
+            snap.gw2d_infil_in      = g.qplus_last;
+            snap.gw2d_link_seepage  = g.qlink_last;   // G-X3
+            // T7.5: concentrations, derived from the stores and the zone
+            // water volumes the kernel already knows.
+            {
+                const auto& tr = gw.transport();
+                snap.gw2d_species_count = tr.active() ? tr.n_species : 0;
+                snap.gw2d_species_names = tr.active() ? &tr.row_names : nullptr;
+                if (tr.active()) {
+                    const auto nn = static_cast(tr.n_species) *
+                                    static_cast(n);
+                    snap.gw2d_sat_conc.assign(nn, 0.0);
+                    snap.gw2d_unsat_conc.assign(nn, 0.0);
+                    for (int c = 0; c < n; ++c) {
+                        const double vs = gw.satVolume(c);
+                        const double vu = gw.unsatVolume(c);
+                        for (int sp = 0; sp < tr.n_species; ++sp) {
+                            const auto k = tr.idx(sp, c);
+                            if (vs > 0.0) snap.gw2d_sat_conc[k]   = tr.sat_mass[k] / vs;
+                            if (vu > 0.0) snap.gw2d_unsat_conc[k] = tr.unsat_mass[k] / vu;
+                        }
+                    }
+                    snap.gw2d_species_ledger.assign(
+                        static_cast(tr.n_species) * 13, 0.0);
+                    for (int sp = 0; sp < tr.n_species; ++sp) {
+                        const auto u = static_cast(sp);
+                        double* d = &snap.gw2d_species_ledger[u * 13];
+                        d[0]  = tr.init_mass[u];
+                        d[1]  = tr.ledgeredStorage(sp);
+                        d[2]  = tr.gained_infil[u];
+                        d[3]  = tr.gained_node[u];
+                        d[4]  = tr.gained_link[u];
+                        d[5]  = tr.net_lateral[u];
+                        d[6]  = tr.lost_deep[u];
+                        d[7]  = tr.lost_node[u];
+                        d[8]  = tr.lost_link[u];
+                        d[9]  = tr.lost_dunne[u];
+                        d[10] = tr.lost_et[u];
+                        d[11] = tr.lost_reaction[u];
+                        d[12] = tr.residual(sp);
+                    }
+                } else {
+                    snap.gw2d_sat_conc.clear();
+                    snap.gw2d_unsat_conc.clear();
+                    snap.gw2d_species_ledger.clear();
+                }
+            }
+            snap.gw2d_bed_elev      = g.z_bed;
+            snap.gw2d_closure.assign(n, 0);
+            for (std::size_t c = 0; c < n; ++c)
+                snap.gw2d_closure[c] = static_cast(g.closure[c]);
+            snap.gw2d_m_layers      = g.m_layers;
+            snap.gw2d_theta_sigma   = g.theta_sigma;
+            snap.gw2d_ledger = {g.led_recharge, g.led_lateral, g.led_deep, g.led_node,
+                                g.led_dunne, g.led_caprise, g.led_et, g.led_infil_in,
+                                g.led_init_storage, g.liveStorage(),
+                                g.led_link,   // G-X3
+                                g.continuityResidual()};
+            snap.gw2d_bed_exchange_cum = gw.bedExchangeCumulative();
+            snap.gw2d_node_names = surface_router_.aquiferNodeNames().empty()
+                                       ? nullptr : &surface_router_.aquiferNodeNames();
+        } else {
+            snap.gw2d_table_elev.clear(); snap.gw2d_hg.clear(); snap.gw2d_hu.clear();
+            snap.gw2d_recharge.clear(); snap.gw2d_lateral.clear(); snap.gw2d_node_exchange.clear();
+            snap.gw2d_deep.clear(); snap.gw2d_et.clear(); snap.gw2d_dunne.clear();
+            snap.gw2d_infil_in.clear(); snap.gw2d_link_seepage.clear();   // G-X3
+            snap.gw2d_sat_conc.clear(); snap.gw2d_unsat_conc.clear();     // T7.5
+            snap.gw2d_species_ledger.clear(); snap.gw2d_species_count = 0;
+            snap.gw2d_species_names = nullptr;
+            snap.gw2d_bed_elev.clear(); snap.gw2d_closure.clear();
+            snap.gw2d_theta_sigma.clear(); snap.gw2d_m_layers = 0; snap.gw2d_ledger.clear();
+            snap.gw2d_bed_exchange_cum.clear(); snap.gw2d_node_names = nullptr;
+        }
+    }
 #else
     (void)snap;
 #endif
@@ -4019,40 +6989,63 @@ void SWMMEngine::fillSurfaceSnapshot(SimulationSnapshot& snap) const noexcept {
 // ============================================================================
 
 void SWMMEngine::accumulateAvgResults() noexcept {
-    // Node accumulators: depth, head, volume, lat_inflow, total_inflow, overflow
+    // Legacy output_updateAvgResults (output.c:853-901): per routing step it
+    // evaluates node_getResults/link_getResults at f = 1.0 — the REAL4
+    // DISPLAY-unit report values — and adds them into REAL4 xAvg slots. The
+    // whole chain is float32 arithmetic on display values; reproduce it
+    // exactly (see AvgAccumulator). Quality columns are NOT averaged yet —
+    // legacy also averages NODE_QUAL/LINK_QUAL; documented follow-up.
+    const auto du = ucf::DisplayUnits::from(ctx_.options);
+
+    // Node slots — legacy node_getResults at f = 1 (node.c:481-505):
+    // head = f32(depth_display) + f32(invert_display), summed in float.
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
-        avg_.node_depth[uj]        += ctx_.nodes.depth[uj];
-        avg_.node_head[uj]         += ctx_.nodes.head[uj];
-        avg_.node_volume[uj]       += ctx_.nodes.volume[uj];
-        avg_.node_lat_inflow[uj]   += ctx_.nodes.lat_flow[uj];
-        avg_.node_total_inflow[uj] += ctx_.nodes.inflow[uj];
-        avg_.node_overflow[uj]     += ctx_.nodes.overflow[uj];
-    }
-
-    // Link accumulators: flow, depth, velocity, volume, capacity
+        const float dd =
+            static_cast(ctx_.nodes.depth[uj] * du.length);
+        avg_.node_depth[uj] += dd;
+        avg_.node_head[uj] += dd +
+            static_cast(ctx_.nodes.invert_elev[uj] * du.length);
+        avg_.node_volume[uj] +=
+            static_cast(reportedNodeVolume(j) * du.volume);
+        avg_.node_lat_inflow[uj] +=
+            static_cast(ctx_.nodes.lat_flow[uj] * du.flow);
+        avg_.node_total_inflow[uj] +=
+            static_cast(ctx_.nodes.inflow[uj] * du.flow);
+        avg_.node_overflow[uj] +=
+            static_cast(ctx_.nodes.overflow[uj] * du.flow);
+    }
+
+    // Link slots — legacy link_getResults at f = 1 (link.c:677-727):
+    // flow/velocity carry direction; velocity converts with UCF(LENGTH).
     ensureXspCache();
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
         double q = ctx_.links.flow[uj];
         double d = ctx_.links.depth[uj];
+        const double dir = static_cast(ctx_.links.direction[uj]);
 
-        avg_.link_flow[uj]   += q;
-        avg_.link_depth[uj]  += d;
-        avg_.link_volume[uj] += ctx_.links.volume[uj];
+        avg_.link_flow[uj]   += static_cast(q * du.flow * dir);
+        avg_.link_depth[uj]  += static_cast(d * du.length);
+        avg_.link_volume[uj] +=
+            static_cast(ctx_.links.volume[uj] * du.volume);
 
         auto lt = ctx_.links.type[uj];
         if (lt == LinkType::CONDUIT) {
             const XSectParams& xs = xsp_cache_[uj];
             const int cr = ctx_.link_subtypes.conduit_row(j);
             const int nb = (cr >= 0) ? ctx_.link_subtypes.conduits.barrels[static_cast(cr)] : 1;
-            avg_.link_velocity[uj] += link::getVelocity(xs, q, d, nb);
-            avg_.link_capacity[uj] += link::getCapacity(xs, d);
+            avg_.link_velocity[uj] += static_cast(
+                link::getVelocity(xs, q, d, nb) * du.length * dir);
+            avg_.link_capacity[uj] +=
+                static_cast(link::getCapacity(xs, d));
         } else {
             // Non-conduit capacity (pump speed, regulator opening):
             // Legacy preserves last value — multiply by (n_steps+1) so that
-            // division by n_steps in applyAvgResults yields the last value.
-            avg_.link_capacity[uj] = ctx_.links.setting[uj] * (avg_.n_steps + 1);
+            // division by n_steps in applyAvgResults yields the last value
+            // (output.c:889-895; float times int, in float).
+            avg_.link_capacity[uj] = static_cast(ctx_.links.setting[uj])
+                * static_cast(avg_.n_steps + 1);
         }
     }
 
@@ -4065,28 +7058,32 @@ void SWMMEngine::accumulateAvgResults() noexcept {
 
 void SWMMEngine::applyAvgResults(SimulationSnapshot& snap) noexcept {
     if (avg_.n_steps <= 0) return;
-    double inv = 1.0 / avg_.n_steps;
-
-    // Average node results
+    // Legacy output_saveAvgResults (output.c:907-951): REAL4 slot divided by
+    // Nsteps in float arithmetic. The results are DISPLAY-unit values, so
+    // this must run AFTER convertSnapshotToDisplay — the doubles written
+    // here hold exact float32 values that the writer's final float cast
+    // reproduces bit-for-bit.
+    const float n = static_cast(avg_.n_steps);
+
+    // Average node results (direction/units already in the accumulators)
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
-        snap.nodes.depth[uj]          = avg_.node_depth[uj] * inv;
-        snap.nodes.head[uj]           = avg_.node_head[uj] * inv;
-        snap.nodes.volume[uj]         = avg_.node_volume[uj] * inv;
-        snap.nodes.lateral_inflow[uj] = avg_.node_lat_inflow[uj] * inv;
-        snap.nodes.total_inflow[uj]   = avg_.node_total_inflow[uj] * inv;
-        snap.nodes.overflow[uj]       = avg_.node_overflow[uj] * inv;
+        snap.nodes.depth[uj]          = avg_.node_depth[uj] / n;
+        snap.nodes.head[uj]           = avg_.node_head[uj] / n;
+        snap.nodes.volume[uj]         = avg_.node_volume[uj] / n;
+        snap.nodes.lateral_inflow[uj] = avg_.node_lat_inflow[uj] / n;
+        snap.nodes.total_inflow[uj]   = avg_.node_total_inflow[uj] / n;
+        snap.nodes.overflow[uj]       = avg_.node_overflow[uj] / n;
     }
 
-    // Average link results (direction applied here, not during accumulation)
+    // Average link results
     for (int j = 0; j < ctx_.n_links(); ++j) {
         auto uj = static_cast(j);
-        int dir = ctx_.links.direction[uj];
-        snap.links.flow[uj]     = avg_.link_flow[uj] * inv * dir;
-        snap.links.depth[uj]    = avg_.link_depth[uj] * inv;
-        snap.links.velocity[uj] = avg_.link_velocity[uj] * inv * dir;
-        snap.links.volume[uj]   = avg_.link_volume[uj] * inv;
-        snap.links.capacity[uj] = avg_.link_capacity[uj] * inv;
+        snap.links.flow[uj]     = avg_.link_flow[uj] / n;
+        snap.links.depth[uj]    = avg_.link_depth[uj] / n;
+        snap.links.velocity[uj] = avg_.link_velocity[uj] / n;
+        snap.links.volume[uj]   = avg_.link_volume[uj] / n;
+        snap.links.capacity[uj] = avg_.link_capacity[uj] / n;
     }
 
     // Reset for next report period
@@ -4096,6 +7093,13 @@ void SWMMEngine::applyAvgResults(SimulationSnapshot& snap) noexcept {
 int SWMMEngine::end() noexcept {
     if (ctx_.state != EngineState::RUNNING &&
         ctx_.state != EngineState::ENDED) {
+        // A failed run sits in ERROR_STATE holding the root-cause message.
+        // Callers (GUI, CLI, swmm_engine_run) call end() unconditionally on
+        // their teardown path, so a wrong-state set_error here would clobber
+        // the reason swmm_get_last_error_msg reports. Preserve it.
+        if (ctx_.state == EngineState::ERROR_STATE)
+            return (ctx_.error_code != SWMM_OK) ? ctx_.error_code
+                                                : SWMM_ERR_WRONG_STATE;
         set_error(SWMM_ERR_WRONG_STATE,
                   "swmm_engine_end: engine must be running or ended");
         return SWMM_ERR_WRONG_STATE;
@@ -4110,14 +7114,54 @@ int SWMMEngine::end() noexcept {
             if (gw.total_depth[ui] <= 0.0) continue;
             double upper_d = gw.total_depth[ui] - gw.lower_depth[ui];
             double vol = gw.theta[ui] * upper_d + gw.porosity[ui] * gw.lower_depth[ui];
-            double area = ctx_.subcatches.area[ui] * 43560.0;
+            double area = ctx_.subcatches.area[ui]
+                        / ucf::UCF(ucf::LANDAREA, ctx_.options);
             ctx_.mass_balance.gw_final_storage += vol * area;
         }
     }
 
+    // D-NS1 (X6): summarize extraction clamps before the report renders,
+    // so the counts reach the .rpt warning block (gates read
+    // ctx.warnings directly, so .rpt ordering is not load-bearing).
+    quality::summarizeNegativeSourceClamps(ctx_);
+
     // Build routing time step histogram for report
     ctx_.routing_stats.build_histogram();
 
+    // Publish the FV solver's cumulative counters into the context so the
+    // report plugin can print them — IReportPlugin only ever sees a
+    // SimulationContext, never the Router. Exactly the 2D pattern
+    // (SurfaceRouter2D::finalize -> mass_balance_2d.solver_*), except the FV
+    // solver's counters survive finalize(), so ordering here is free.
+    // The nsteps > 0 test is load-bearing: INetworkSolver::run_stats() defaults
+    // to a ZEROED struct, so a backend carrying no counters returns nsteps == 0
+    // — not the -1 the report block treats as "skip me". Leaving the sentinel
+    // in place for that case is what keeps the block from printing a row of
+    // zeros, which reads as "the solver did nothing" instead of "nobody
+    // counted".
+    if (const auto* fv = router_.fvSolver();
+        fv != nullptr && fv->run_stats().nsteps > 0) {
+        const auto s = fv->run_stats();
+        auto& rs = ctx_.routing_stats;
+        rs.fv_nsteps      = s.nsteps;
+        rs.fv_nflux       = s.nflux;
+        rs.fv_avg_h       = s.avg_h;
+        rs.fv_last_h      = s.last_h;
+        rs.fv_min_h       = s.min_h;
+        rs.fv_active_min  = s.active_frac_min;
+        rs.fv_active_mean = s.active_frac_mean;
+        rs.fv_active_max  = s.active_frac_max;
+        rs.fv_n_tiers     = s.n_tiers;
+        for (int k = 0; k < s.n_tiers && k < 8; ++k)
+            rs.fv_tier_cells[k] = s.tier_cells[k];
+        rs.fv_dt_argmin_pressurized = s.dt_argmin_pressurized;
+        rs.fv_dt_argmin_band        = s.dt_argmin_band;
+        rs.fv_dt_argmin_free        = s.dt_argmin_free;
+        rs.fv_dt_argmin_node        = s.dt_argmin_node;
+        rs.fv_macro_cycles          = s.n_macro_cycles;
+        rs.fv_macro_rejected        = s.n_macro_rejected;
+    }
+
     // Finalize per-element max stats for report (top-5 CFL-critical, flow turns,
     // non-convergence — matching legacy stats_findMaxStats)
 #ifdef OPENSWMM_HAS_2D
@@ -4178,6 +7222,11 @@ int SWMMEngine::end() noexcept {
 
 int SWMMEngine::report() noexcept {
     if (ctx_.state != EngineState::ENDED) {
+        // Same preservation as end(): never clobber a failed run's recorded
+        // cause with a wrong-state complaint on the unconditional teardown path.
+        if (ctx_.state == EngineState::ERROR_STATE)
+            return (ctx_.error_code != SWMM_OK) ? ctx_.error_code
+                                                : SWMM_ERR_WRONG_STATE;
         set_error(SWMM_ERR_WRONG_STATE,
                   "swmm_engine_report: must call end() first");
         return SWMM_ERR_WRONG_STATE;
@@ -4213,9 +7262,9 @@ int SWMMEngine::report() noexcept {
         }
     }
 
-    // Gap #68: copy inlet stats into inlet_usages for reporting
+    // Gap #68: copy inlet stats into inlet_usages / inlet_diag for reporting
     if (ctx_.inlet_usages.count() > 0)
-        inlet_.gatherStats(ctx_.inlet_usages);
+        inlet_.gatherStats(ctx_);
 
     // Phase 4: write summary reports via all report plugins
     if (!plugins_.empty()) {
@@ -4231,9 +7280,41 @@ int SWMMEngine::report() noexcept {
 // ============================================================================
 
 int SWMMEngine::close() noexcept {
+    // Load-phase breakdown. Emitted here rather than from end() so it reports
+    // for a bare open()+close() too — the benchmark harness times open alone,
+    // open+initialize, and the full sequence. (See core/PerfTimers.hpp.)
+    if (perf::enabled()) perf::dump_load();
+
+    // FV phase breakdown, only when the FV solver actually ran — an empty line
+    // on a DYNWAVE run would be noise the harness has to filter.
+    if (perf::enabled() && perf::n_fv_substep > 0) perf::dump_fv();
+
     // Stop IO thread if still running (safe to call even if already stopped)
     io_thread_.stop();
 
+    // A run that failed after open() never reaches end()/report(), so without
+    // this flush the root cause would never reach the .rpt — the report
+    // plugin's destructor only stamps the generic "[Report interrupted]"
+    // footer. Record the fatal message alongside any accumulated errors and
+    // write them out, mirroring write_open_failure_report() for open()-time
+    // failures. Many set_error sites (hotstart, interface files) do not push
+    // into ctx_.errors themselves, hence the append here.
+    if (ctx_.state == EngineState::ERROR_STATE) {
+        try {
+            if (!ctx_.error_message.empty() &&
+                std::find(ctx_.errors.begin(), ctx_.errors.end(),
+                          ctx_.error_message) == ctx_.errors.end())
+                ctx_.errors.push_back(ctx_.error_message);
+        } catch (...) {
+            // Out-of-memory recording the error is non-fatal for close().
+        }
+        if (plugins_prepare_attempted_)
+            plugins_.finalize_all(ctx_);   // flushes into the open .rpt/.out
+        else
+            write_open_failure_report();   // .rpt was never opened — write one
+    }
+    plugins_prepare_attempted_ = false;
+
     // Close routing interface files
     iface_.closeFiles();
 
@@ -4350,6 +7431,38 @@ void SWMMEngine::applyForcings(double dt) noexcept {
         }
     }
 
+    // ---- U2: reserved-species node forcing (temperature, age) ----
+    // OVERRIDE writes the published state (degC / hours -> the internal
+    // seconds for age); ADD injects into the loader accumulator every
+    // quality engine reads, so the value mixes instead of replacing.
+    if (ctx_.options.heat_transport &&
+        ctx_.heat_state.node_temp.size() == static_cast(ctx_.n_nodes())) {
+        for (int i = 0; i < ctx_.n_nodes(); ++i) {
+            const auto u = static_cast(i);
+            if (u >= f.node_temperature_mode.size()) break;
+            if (f.node_temperature_mode[u] == ForcingMode::OVERRIDE) {
+                ctx_.heat_state.node_temp[u] = f.node_temperature_value[u];
+            } else if (f.node_temperature_mode[u] == ForcingMode::ADD &&
+                       u < ctx_.heat_state.node_temp_vol_in.size()) {
+                ctx_.heat_state.node_temp_vol_in[u] += f.node_temperature_value[u];
+            }
+        }
+    }
+    if (ctx_.options.water_age &&
+        ctx_.water_age_state.node_age.size() == static_cast(ctx_.n_nodes())) {
+        for (int i = 0; i < ctx_.n_nodes(); ++i) {
+            const auto u = static_cast(i);
+            if (u >= f.node_age_mode.size()) break;
+            if (f.node_age_mode[u] == ForcingMode::OVERRIDE) {
+                ctx_.water_age_state.node_age[u] = f.node_age_value[u] * 3600.0;
+            } else if (f.node_age_mode[u] == ForcingMode::ADD &&
+                       u < ctx_.water_age_state.node_age_vol_in.size()) {
+                ctx_.water_age_state.node_age_vol_in[u] +=
+                    f.node_age_value[u] * 3600.0;
+            }
+        }
+    }
+
     // ---- Node quality mass flux forcing (transient via ForcingData) ----
     // For OVERRIDE mode, the concentration is set directly.
     // For ADD mode, mass_rate (mass/sec) is added as concentration delta.
@@ -4375,28 +7488,16 @@ void SWMMEngine::applyForcings(double dt) noexcept {
         // mixing during the same routing step.
 
         // ---- Persistent user quality mass flux (user_conc_mass_flux) ----
-        // Applied as additive mass source each step, analogous to user_lat_flow.
-        // mass_rate is in mass/sec; converted to concentration delta via volume.
-        if (!ctx_.nodes.user_conc_mass_flux.empty()) {
-            for (int i = 0; i < ctx_.n_nodes(); ++i) {
-                auto ui = static_cast(i);
-                double vol = ctx_.nodes.volume[ui];
-                for (int p = 0; p < np; ++p) {
-                    auto flat = ui * static_cast(np)
-                              + static_cast(p);
-                    double mass_rate = ctx_.nodes.user_conc_mass_flux[flat];
-                    if (mass_rate == 0.0) continue;
-
-                    // Convert mass flux to concentration: C += (mass_rate * dt) / volume
-                    if (vol > 0.0) {
-                        ctx_.nodes.conc[flat] += mass_rate * dt / vol;
-                    }
-                    // Track cumulative forced quality mass (mass = rate * dt)
-                    ctx_.mass_balance.routing_forcing_qual_inflow[
-                        static_cast(p)] += mass_rate * dt;
-                }
-            }
-        }
+        // NOT applied here. It used to be a post-quality concentration bump
+        // (C += mass_rate*dt/volume), which the next routing step's mixing
+        // overwrote, so the forced mass was booked in the ledger but never
+        // actually entered the system. It is delivered in the loader stage
+        // instead — QualitySolver::addExtInflowLoads() — exactly as legacy
+        // addExternalInflows() does it (routing.c: Node[j].newQual[p] += w;
+        // massbal_addInflowQual(EXTERNAL_INFLOW, p, w)). That is also the
+        // only place that reaches BOTH the legacy CSTR mixing and the ARD
+        // node stores. This mirrors the forced-lateral-inflow treatment,
+        // which likewise counts as external inflow (issue #113).
     }
 }
 
@@ -4496,8 +7597,13 @@ void SWMMEngine::validate_project() noexcept {
     // WARNING 01: wet-weather routing step reduced to a rain gage's recording
     // interval (legacy gage_validate / gage.c). Progressively clamp WetStep to
     // the smallest gage interval it exceeds, warning per gage.
+    // Only a USED gage (legacy gage_validate returns at once for one no
+    // subcatchment or UH group reads): hec-hms-hyetographs carries 44 gages
+    // down to a 4 s interval, one of which its single subcatchment uses,
+    // and legacy keeps WetStep at 60 s and the routing step at 30 s there.
     const int ng = ctx_.n_gages();
     for (int g = 0; g < ng; ++g) {
+        if (!gage::gageIsUsed(ctx_, g)) continue;
         const double interval =
             static_cast(ctx_.gages.interval_sec[static_cast(g)]);
         if (interval > 0.0 && opt.wet_step > interval) {
@@ -4515,12 +7621,98 @@ void SWMMEngine::validate_project() noexcept {
     }
 
     // WARNING 07: routing step reduced to the wet-weather step (legacy project.c).
+    // legacy link_validate has already consumed the AUTHORED step by then
+    // (project_validate validates the links first): keep it for the
+    // link constants formed at hydraulics init (Router::init lengthening,
+    // StructureSolver::init equivalent lengths). surchargedweirs (LPS,
+    // ROUTING_STEP 60 s, WET_STEP 10 s) gave its side orifice a 206 ft
+    // equivalent length where legacy's is 1233 ft.
+    opt.routing_step_authored = opt.routing_step;
     if (opt.routing_step > opt.wet_step) {
         opt.routing_step = opt.wet_step;
         ctx_.warnings.push_back(format_warning(WARN_ROUTING_STEP_REDUCED, ""));
     }
 }
 
+int SWMMEngine::checkRoutingDiverged() noexcept {
+    // A diverged routing solve used to run to completion and write NaN into
+    // the report, which reads as a finished simulation (TwinOaks-v2 under
+    // DYNWAVE + SURCHARGE_METHOD SLOT: a slot-surcharged pass-through node
+    // beside a dry one drove 2.8e5 cfs through a 9 ft pipe, cascaded, and
+    // reached 1e290 before the report accumulators overflowed). Stop at the
+    // step that goes non-physical and name the element, so the failure is
+    // reportable instead of silent.
+    //
+    // The bound is deliberately absurd, not tight: real heads are O(1e3) ft
+    // and real flows O(1e5) cfs at the very largest, so 1e9 cannot fire on a
+    // converging model however badly conditioned. Catching a merely LARGE
+    // value is the caller's job (continuity error, non-convergence percent);
+    // this exists only to stop unbounded growth. Note an isfinite() test
+    // alone is not enough -- the runaway stays finite for a long way up.
+    constexpr double kAbsurd = 1.0e9;
+    auto diverged = [](double v) {
+        return !std::isfinite(v) || std::fabs(v) > kAbsurd;
+    };
+
+    // FV cell-state guard (issue #156 R3). The published node/link state
+    // checked below is a per-conduit REDUCTION of the FV cells, and the
+    // reduction stays far under kAbsurd long after the cells have left the
+    // physics (the mixed-flow study P6 measured 30 of 118 series beyond 10x
+    // the observed range, every run status OK — the substep retry loop cannot
+    // reject a dt-independent amplification, so it accepts the diverged step
+    // silently). The solver checks its own cells against physical-absurdity
+    // bounds once per routing step and reports the worst offender here.
+    if (const fv::INetworkSolver* s = router_.fvSolver()) {
+        fv::INetworkSolver::Divergence dv;
+        if (s->divergence(dv)) {
+            char buf[256];
+            std::snprintf(buf, sizeof(buf),
+                "ERROR %d: the FV solution diverged in conduit '%s' "
+                "(%s %.6g) after %.4f hours -- a step-size-independent "
+                "instability the substep retry cannot shrink away; the run "
+                "cannot continue.",
+                CFFI_ERR_NUMERICAL,
+                dv.link >= 0 ? ctx_.link_names.name_of(dv.link).c_str() : "?",
+                dv.what ? dv.what : "state", dv.value,
+                ctx_.current_time / 3600.0);
+            ctx_.errors.push_back(buf);
+            set_error(CFFI_ERR_NUMERICAL, buf);
+            return CFFI_ERR_NUMERICAL;
+        }
+    }
+
+    const int nn = ctx_.n_nodes();
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        if (!diverged(ctx_.nodes.head[ui])) continue;
+        char buf[256];
+        std::snprintf(buf, sizeof(buf),
+            "ERROR %d: the routing solution diverged at node '%s' "
+            "(head %.6g) after %.4f hours -- the run cannot continue.",
+            CFFI_ERR_NUMERICAL, ctx_.node_names.name_of(i).c_str(),
+            ctx_.nodes.head[ui], ctx_.current_time / 3600.0);
+        ctx_.errors.push_back(buf);
+        set_error(CFFI_ERR_NUMERICAL, buf);
+        return CFFI_ERR_NUMERICAL;
+    }
+
+    const int nl = ctx_.n_links();
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        if (!diverged(ctx_.links.flow[uj])) continue;
+        char buf[256];
+        std::snprintf(buf, sizeof(buf),
+            "ERROR %d: the routing solution diverged at link '%s' "
+            "(flow %.6g) after %.4f hours -- the run cannot continue.",
+            CFFI_ERR_NUMERICAL, ctx_.link_names.name_of(j).c_str(),
+            ctx_.links.flow[uj], ctx_.current_time / 3600.0);
+        ctx_.errors.push_back(buf);
+        set_error(CFFI_ERR_NUMERICAL, buf);
+        return CFFI_ERR_NUMERICAL;
+    }
+    return SWMM_OK;
+}
+
 void SWMMEngine::write_open_failure_report() noexcept {
     if (rpt_path_.empty() || ctx_.options.rpt_disabled) return;
     try {
@@ -4579,10 +7771,10 @@ void SWMMEngine::emit_progress() noexcept {
 // ============================================================================
 
 void SWMMEngine::init_modules() noexcept {
-    initHydraulics();
-    initHydrology();
-    initQuality();
-    initGeometry();
+    { perf::ScopedTimer _pt(perf::sec_init_hydraulics); initHydraulics(); }
+    { perf::ScopedTimer _pt(perf::sec_init_hydrology);  initHydrology();  }
+    { perf::ScopedTimer _pt(perf::sec_init_quality);    initQuality();    }
+    { perf::ScopedTimer _pt(perf::sec_init_geometry);   initGeometry();   }
     initMassBalance();
 
     // Allocate forcing arrays to match object counts
@@ -4645,14 +7837,51 @@ void SWMMEngine::initHydraulics() noexcept {
             if (n1 >= 0 && n1 < n_nl) n_out[static_cast(n1)]++;
             if (n2 >= 0 && n2 < n_nl) n_in[static_cast(n2)]++;
         }
-        // Count outfall nodes (legacy does not error on multiple inlets or outlet links for outfalls)
+        // An outfall QUALIFIES as an outlet only if at most one link touches
+        // it; otherwise legacy rejects the model (flowrout.c:322-329):
+        //
+        //     if (Node[i].degree + (int)Node[i].inflow > 1)
+        //          report_writeErrorMsg(ERR_OUTFALL, Node[i].ID);
+        //     else outletCount++;
+        //
+        // where `inflow` is a link count credited to the OUTFALL end when a
+        // link has one (flowrout.c:293-295) and `degree` is the outflow count,
+        // credited to the OTHER node when the upstream end is an outfall
+        // (toposort.c:80-90) — so for an outfall the test reduces to "more
+        // than one connected link, in either direction".
+        //
+        // The comment that stood here said legacy does not error on this. It
+        // does, as ERROR 141, and v6 carried the code in its table with no
+        // writer: eleven corpus decks ran to completion in v6 against a legacy
+        // that produced no results at all — advancedflowsplit and exam70-sw5
+        // among them. Accepting a model the reference REJECTS is the one
+        // failure mode a parity corpus cannot show as a diff, because there is
+        // nothing on the other side to diff against.
+        //
+        // Gated on DYNWAVE alone, which is legacy's own gate: flowrout.c:83
+        // runs validateGeneralLayout only for DW, and KINWAVE/STEADY go
+        // through validateTreeLayout, which never requires an outfall at all.
+        // FV is deliberately NOT included even though the no-outlets test
+        // below treats it as DW-class — legacy has no FV to be a reference
+        // for, so rejecting an FV deck here would be a behaviour change with
+        // no oracle behind it.
         int n_outlets = 0;
         for (int i = 0; i < n_nl; ++i) {
             auto ui = static_cast(i);
-            if (ctx_.nodes.type[ui] == NodeType::OUTFALL)
+            if (ctx_.nodes.type[ui] != NodeType::OUTFALL) continue;
+            if (rm == RouteModel::DYNWAVE && n_in[ui] + n_out[ui] > 1) {
+                ctx_.errors.push_back(
+                    format_error(ERR_OUTFALL, ctx_.node_names.names()[ui]));
+                set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+            } else {
                 ++n_outlets;
+            }
         }
         // Gap #83b: drainage system must have at least one outlet.
+        // Legacy raises ERR_NO_OUTLETS from validateGeneralLayout(), which
+        // flowrout_init() calls ONLY for dynamic wave; kinematic wave and
+        // steady routing go through validateTreeLayout(), which never
+        // requires an outfall. FV joins DW here as the DW-class scheme.
         // A model with a 2D surface mesh is exempt: water can leave the
         // system through the 2D domain (boundary conditions / vertex-node
         // coupling), so a 1D outfall is not required. The mesh is parsed at
@@ -4663,22 +7892,66 @@ void SWMMEngine::initHydraulics() noexcept {
         has_2d_domain = surface_router_.mesh().n_triangles() >= 1
                         && surface_router_.mesh().n_vertices() >= 3;
 #endif
-        if (n_outlets == 0 && rm != RouteModel::STEADY && !has_2d_domain) {
+        if (n_outlets == 0
+            && (rm == RouteModel::DYNWAVE || rm == RouteModel::FV)
+            && !has_2d_domain) {
             ctx_.errors.push_back(format_error(ERR_NO_OUTLETS, ""));
             set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
         }
         // Gap #84a: adverse slope only errors for non-DW routing. FV joins DW
         // here — a conservative scheme resolves an adverse slope natively.
+        // DUMMY cross-sections are exempt, exactly as legacy
+        // validateTreeLayout (flowrout.c:255-257: `slope < 0 &&
+        // xsect.type != DUMMY`) — a dummy conveys the node's inflow and has
+        // no slope-driven physics (490-kw-h-h-elements CDT-39).
         if (rm != RouteModel::DYNWAVE && rm != RouteModel::FV) {
             for (int j = 0; j < n_ll; ++j) {
                 auto uj = static_cast(j);
                 if (ctx_.links.type[uj] != LinkType::CONDUIT) continue;
+                if (ctx_.links.xsect_shape[uj] == XsectShape::DUMMY) continue;
                 const int cr = ctx_.link_subtypes.conduit_row(j);
                 if (cr >= 0 && ctx_.link_subtypes.conduits.slope[static_cast(cr)] < 0.0) {
                     ctx_.errors.push_back(format_error(ERR_SLOPE, ctx_.link_names.names()[uj]));
                     set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
                 }
             }
+            // The rest of legacy validateTreeLayout's NODE half
+            // (flowrout.c:219-249). Kinematic wave and steady flow route down
+            // a TREE: every node has at most one way out, a divider exactly
+            // two, and an outfall none at all. Storage is exempt because its
+            // volume decouples the outflows. Only the conduit-slope half of
+            // this function had been carried over, so v6 routed networks that
+            // are not trees under a solver that assumes one —
+            // 10311-h-elements is the corpus case, where legacy stops with
+            // ERROR 133 and v6 produced a full run.
+            for (int i = 0; i < n_nl; ++i) {
+                auto ui = static_cast(i);
+                const int deg = n_out[ui];   // legacy's DIRECTED out-degree
+                switch (ctx_.nodes.type[ui]) {
+                    case NodeType::DIVIDER:
+                        if (deg > 2) {
+                            ctx_.errors.push_back(format_error(
+                                ERR_DIVIDER, ctx_.node_names.names()[ui]));
+                            set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+                        }
+                        break;
+                    case NodeType::OUTFALL:
+                        if (deg > 0) {
+                            ctx_.errors.push_back(format_error(
+                                ERR_OUTFALL, ctx_.node_names.names()[ui]));
+                            set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+                        }
+                        break;
+                    case NodeType::STORAGE:
+                        break;
+                    default:
+                        if (deg > 1) {
+                            ctx_.errors.push_back(format_error(
+                                ERR_MULTI_OUTLET, ctx_.node_names.names()[ui]));
+                            set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+                        }
+                }
+            }
         }
         // Gap #84b: legacy SWMM5 does not report ERROR 139 for regulators on
         // non-storage nodes in practice, so we suppress this check to match legacy output.
@@ -4712,10 +7985,22 @@ void SWMMEngine::initHydraulics() noexcept {
 #endif
 
     // 1b. Configure OpenMP thread count from THREADS option.
-    //     0 = use all available; N = use min(N, available).
+    //     0 = auto (omp_get_max_threads() + heuristics); N = honoured exactly,
+    //     with warnings when N exceeds the logical CPUs / the runtime limit
+    //     (see ThreadInfo.hpp and THREAD_LIMITS_AND_OVERSUBSCRIPTION_PLAN).
     //     DWSolver applies its own per-thread conduit-count gate.
     //     The global OMP thread count is also set for Runoff/Quality modules.
     {
+        // Resolve first: the wait-policy decision below depends on whether
+        // the requested team oversubscribes the machine.
+        // Thread warnings are collected locally and pushed through
+        // push_report_warning() at the end of this block so they reach both
+        // the .rpt warning list and the host's warning callback.
+        std::vector thread_warnings;
+        const int nt = threadinfo::resolveRequested(
+            ctx_.options.num_threads, "OpenMP team", &thread_warnings);
+        const bool oversubscribed = threadinfo::isOversubscribed(nt);
+        (void)oversubscribed;   // only consulted by the POSIX wait-policy block
 #if defined(SWMM_USE_OPENMP) && !defined(_WIN32)
         // B2 threading wait policy: the persistent-team DW Picard loop
         // synchronizes with several barriers per iteration (~1.2M iterations
@@ -4738,30 +8023,71 @@ void SWMMEngine::initHydraulics() noexcept {
                 rm == RouteModel::DYNWAVE &&
                 (ctx_.options.num_threads != 1 || dw_forced > 1) &&
                 dw_forced != 1;
-            if (dw_threading_possible) {
-                setenv("OMP_WAIT_POLICY", "active", 0);
-                setenv("KMP_BLOCKTIME", "infinite", 0);
+            // Never request active spinning for an oversubscribed team: a
+            // spinner waiting on a DESCHEDULED spinner turns every barrier
+            // into a scheduler-quantum stall (far worse than passive waits).
+            if (dw_threading_possible && !oversubscribed) {
+                // setenv() is not thread-safe in glibc: adding a name reallocs
+                // the environ array and frees the old block, while ~30 getenv()
+                // call sites on the routing hot path read it concurrently. Two
+                // engines starting on different threads double-freed that block.
+                // libomp reads the environment once at lazy runtime init, so
+                // doing this on the first engine to get here is sufficient —
+                // the values do not vary per engine. kmp_set_blocktime below
+                // stays per-call: it is a runtime call, not an environment write.
+                static std::once_flag omp_wait_policy_set;
+                // A host that pre-set KMP_BLOCKTIME (a GUI sharing the CPUs
+                // with its own threads, or a user A/B) keeps its value: the
+                // setenv below already leaves it alone, and the runtime call
+                // after it must not override it either.
+                static bool host_set_blocktime = false;
+                std::call_once(omp_wait_policy_set, [] {
+                    host_set_blocktime = std::getenv("KMP_BLOCKTIME") != nullptr;
+                    setenv("OMP_WAIT_POLICY", "active", 0);
+                    setenv("KMP_BLOCKTIME", "infinite", 0);
+                });
 #if defined(KMP_VERSION_MAJOR)
                 // libomp extension: set spin-wait blocktime on the calling
                 // (master) thread; workers forked by it inherit the setting.
                 // Effective even when the runtime pre-dates the setenv above.
-                kmp_set_blocktime(2147483647);
+                if (!host_set_blocktime) kmp_set_blocktime(2147483647);
 #endif
             }
         }
 #endif
-        int nt = ctx_.options.num_threads;
-        if (nt == 0)
-            nt = omp_get_max_threads();
-        else
-            nt = std::min(nt, omp_get_max_threads());
         omp_set_num_threads(nt);
+#if defined(SWMM_USE_OPENMP)
+        // OMP_THREAD_LIMIT (or a runtime that refuses oversubscription) caps
+        // the team silently — measure what we actually got and say so.
+        if (nt > 1) {
+            int got = 1;
+#pragma omp parallel num_threads(nt)
+            {
+#pragma omp master
+                got = omp_get_num_threads();
+            }
+            if (got < nt) {
+                char buf[256];
+                std::snprintf(buf, sizeof buf,
+                    "THREADS = %d requested but the OpenMP runtime provided a "
+                    "team of %d (OMP_THREAD_LIMIT or runtime policy).", nt, got);
+                thread_warnings.emplace_back(buf);
+            }
+        }
+#endif
 
         // DWSolver gets its own thread count with per-thread conduit gate
         // (or the SWMM_DW_THREADS forced override).
         if (rm == RouteModel::DYNWAVE) {
-            router_.setDWNumThreads(ctx_.options.num_threads);
+            router_.setDWNumThreads(ctx_.options.num_threads, &thread_warnings);
         }
+
+#ifdef OPENSWMM_HAS_2D
+        for (const auto& w : surface_router_.threadWarnings())
+            thread_warnings.push_back(w);
+#endif
+        for (const auto& w : thread_warnings)
+            push_report_warning(w, 0);   // code 0: advisory, no SWMM_WarnCode applies
     }
 
     // Initialize routing time-step histogram bins (log-scale from RouteStep
@@ -4807,17 +8133,26 @@ void SWMMEngine::initHydraulics() noexcept {
             for (int m = 0; m < 12 && (!time_err || !ratio_err); ++m) {
                 double rsum = 0.0;
                 for (int k = 0; k < 3; ++k) {
-                    if (!time_err && (uh.tPeak[m][k] < 0.0 || uh.tBase[m][k] < uh.tPeak[m][k])) {
+                    // Legacy rdii.c:873: a zero base time means the UH does
+                    // not exist for this month/term — skipped entirely, no
+                    // rsum contribution. Legacy checks ONLY tPeak < 0; a
+                    // recession constant K < 0 (tBase < tPeak) is accepted
+                    // (e.g. simple-two-pump-model CHES_47_SEP Short K=-0.42).
+                    if (uh.tBase[m][k] == 0.0) continue;
+                    if (!time_err && uh.tPeak[m][k] < 0.0) {
                         ctx_.errors.push_back(format_error(ERR_UNITHYD_TIMES, uh_name));
                         set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
                         time_err = true;
                     }
-                    if (!ratio_err && uh.r[m][k] < 0.0) {
-                        ctx_.errors.push_back(format_error(ERR_UNITHYD_RATIOS, uh_name));
-                        set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
-                        ratio_err = true;
+                    if (uh.r[m][k] < 0.0) {
+                        if (!ratio_err) {
+                            ctx_.errors.push_back(format_error(ERR_UNITHYD_RATIOS, uh_name));
+                            set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+                            ratio_err = true;
+                        }
+                    } else {
+                        rsum += uh.r[m][k];
                     }
-                    rsum += uh.r[m][k];
                 }
                 if (!ratio_err && rsum > 1.01) {
                     ctx_.errors.push_back(format_error(ERR_UNITHYD_RATIOS, uh_name));
@@ -4847,22 +8182,119 @@ void SWMMEngine::initHydraulics() noexcept {
     // gone — the side-tables stand on their own.
     hydstruct_.init(ctx_);
 
+    // 10b-1. Illegal DUMMY / ideal-pump connections (legacy ERROR 134).
+    //
+    // Ports legacy checkDummyLinks (toposort.c:480-528) and the degree test in
+    // validateGeneralLayout (flowrout.c:301-313), which the C++ engine had
+    // never carried over (plans/FULL_GAP_ANALYSIS.md:618).
+    //
+    // These are not cosmetic. A dummy link and an ideal pump are both PURE
+    // PASS-THROUGHS: their discharge is defined as everything arriving at the
+    // upstream node, so the node's continuity reduces to dV/dt = 0. That
+    // definition is only well posed when the pass-through is the node's ONLY
+    // outlet — give the node a second outlet and both links claim the whole
+    // inflow, creating water — and it is circular when a node passes through to
+    // another node that passes back, since neither arrival rate is defined
+    // without the other.
+    //
+    // Runs after hydstruct_.init because that is what resolves a pump's curve
+    // type (6 == ideal, HydStructures.cpp:147); it is not available earlier.
+    // Restricted to the two models that implement the pass-through: KINWAVE
+    // returns immediately on a dummy (kinwave.c:85) and STEADY gives it zero
+    // area (flowrout.c:774), so neither can violate the invariant.
+    if (rm == RouteModel::DYNWAVE || rm == RouteModel::FV) {
+        const int n_ll = ctx_.n_links();
+        const int n_nl = ctx_.n_nodes();
+        auto is_pass_through = [&](std::size_t uj) {
+            if (ctx_.links.type[uj] == LinkType::CONDUIT)
+                return ctx_.links.xsect_shape[uj] == XsectShape::DUMMY;
+            if (ctx_.links.type[uj] != LinkType::PUMP) return false;
+            const int pr = ctx_.link_subtypes.pump_row(static_cast(uj));
+            return pr >= 0 &&
+                   ctx_.link_subtypes.pumps.curve_type[static_cast(pr)] == 6;
+        };
+
+        // Outgoing link count per node, and whether every incoming link is a
+        // pass-through (legacy's `marked`: 1 = yes so far, −1 = disqualified).
+        //
+        // BOTH counts are taken on the AUTHORED orientation, recovered through
+        // `direction`. An adverse-slope conduit has already had its node1 and
+        // node2 SWAPPED under DW/FV (PostParseResolver, legacy conduit_reverse),
+        // and legacy's own loops undo that swap: the degree count takes
+        // `node1`, or `node2` when direction < 0 (toposort.c:75-91), and the
+        // incoming mark takes `node2`, or `node1` when direction < 0
+        // (toposort.c:502-512). Reading the post-swap node1 instead counts every
+        // uphill pipe as LEAVING the node it actually enters: MC_STP in
+        // noinflow-1200nodes is fed by three conduits that climb 17 ft to 32 ft,
+        // so its outflow count read 4 where legacy reads 1, and its one real
+        // outlet — a DUMMY to the outfall — was rejected as an illegal
+        // connection on a network legacy routes without complaint.
+        //
+        // The same rule, with the same outfall redirect, is computed for
+        // ctx_.nodes.degree further down this function; it is not reused here
+        // only because that runs after this check.
+        std::vector n_out(static_cast(n_nl), 0);
+        std::vector all_in_pass(static_cast(n_nl), 0);
+        for (int j = 0; j < n_ll; ++j) {
+            const auto uj = static_cast(j);
+            const int n1 = ctx_.links.node1[uj], n2 = ctx_.links.node2[uj];
+            if (n1 < 0 || n1 >= n_nl || n2 < 0 || n2 >= n_nl) continue;
+            const bool rev = ctx_.links.direction[uj] < 0;
+
+            // Outflow count, credited to the downstream end when the upstream
+            // one is an outfall (legacy toposort.c:82-90).
+            int up = rev ? n2 : n1;
+            if (ctx_.nodes.type[static_cast(up)] == NodeType::OUTFALL)
+                up = rev ? n1 : n2;
+            n_out[static_cast(up)]++;
+
+            auto& m = all_in_pass[static_cast(rev ? n1 : n2)];
+            if (!is_pass_through(uj))    m = -1;
+            else if (m == 0)             m = 1;
+        }
+
+        std::vector reported(static_cast(n_nl), 0);
+        auto report = [&](int node) {
+            if (node < 0 || node >= n_nl) return;
+            auto un = static_cast(node);
+            if (reported[un]) return;   // one message per node, not per link
+            reported[un] = 1;
+            ctx_.errors.push_back(
+                format_error(ERR_DUMMY_LINK, ctx_.node_names.names()[un]));
+            set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+        };
+
+        for (int j = 0; j < n_ll; ++j) {
+            const auto uj = static_cast(j);
+            if (!is_pass_through(uj)) continue;
+            const int n1 = ctx_.links.node1[uj];
+            if (n1 < 0 || n1 >= n_nl) continue;
+            const auto u1 = static_cast(n1);
+            // Must be the node's only outlet (flowrout.c:309).
+            if (n_out[u1] > 1) report(n1);
+            // Must not also be fed by a pass-through (toposort.c:522).
+            if (all_in_pass[u1] > 0) report(n1);
+            // A storage node's outlet cannot be a dummy: legacy link.c:1006-1014
+            // rejects it because the pass-through would drain the whole storage
+            // volume's inflow while the curve says otherwise.
+            if (ctx_.links.type[uj] == LinkType::CONDUIT &&
+                ctx_.nodes.type[u1] == NodeType::STORAGE)
+                report(n1);
+        }
+    }
+
+    // KINWAVE/STEADY evaluate orifice/weir/outlet/pump discharge inline inside
+    // their sorted-link loop (legacy getLinkInflow), so the router needs the
+    // structure solver itself — DW/FV get theirs via the non_conduit_fn
+    // callback below. Must be wired before the first router_.step().
+    router_.setStructureSolver(&hydstruct_);
+
     // 10c. Exfiltration solver: initialize Green-Ampt state for storage nodes
     exfil_.init(ctx_);
 
     // 10d. Inlet solver: initialize street inlet data
     inlet_.init(ctx_);
 
-    // 10d-1. Pre-build culvert link index list (avoids per-timestep heap alloc)
-    culvert_links_.clear();
-    for (int j = 0; j < ctx_.n_links(); ++j) {
-        auto uj = static_cast(j);
-        if (ctx_.links.type[uj] == LinkType::CONDUIT) {
-            const int cr = ctx_.link_subtypes.conduit_row(j);
-            if (cr >= 0 && ctx_.link_subtypes.conduits.culvert_code[static_cast(cr)] > 0)
-                culvert_links_.push_back(j);
-        }
-    }
 
     // 10d. Interface file manager: initialize (files opened later in start())
     iface_.init(ctx_);
@@ -4880,6 +8312,7 @@ void SWMMEngine::initHydraulics() noexcept {
                 ctx_.events[i].end = ctx_.events[i + 1].start;
         }
         next_event_ = 0;
+        between_events_ = true;   // legacy routing_open: BetweenEvents = (NumEvents > 0)
     }
 
     // 10e. Control rule parsing from [CONTROLS] section text.
@@ -4923,33 +8356,17 @@ void SWMMEngine::initHydraulics() noexcept {
  *          states, and initializes snow, groundwater, and LID solvers.
  */
 void SWMMEngine::initHydrology() noexcept {
-    // 1. Pre-populate each subcatchment's total LID footprint (ft²) BEFORE the
-    //    runoff solver initialises. RunoffSolver::init() sizes the pervious /
-    //    impervious subareas as (full_area − total_lid_area_ft2), but lid_.init()
-    //    (which normally fills total_lid_area_ft2) runs later in the init
-    //    sequence — so without this pre-pass the runoff solver reads zero LID
-    //    area and the LID footprint is never removed from the runoff-producing
-    //    area, making LIDs a near-noop on subcatchment runoff (issue #102 B).
-    //    lid_.init() recomputes the identical sum later; this is idempotent.
-    {
-        int n_sc = ctx_.n_subcatches();
-        if (n_sc > 0) {
-            const double ucfLen2 = ucf::UCF(ucf::LENGTH, ctx_.options)
-                                 * ucf::UCF(ucf::LENGTH, ctx_.options);
-            ctx_.subcatches.total_lid_area_ft2.assign(
-                static_cast(n_sc), 0.0);
-            const auto& lu = ctx_.lid_usage;
-            for (int j = 0; j < lu.count(); ++j) {
-                auto uj = static_cast(j);
-                int sc = lu.subcatch_index[uj];
-                if (sc < 0 || sc >= n_sc) continue;
-                int num = (uj < lu.number.size()) ? lu.number[uj] : 1;
-                if (num < 1) num = 1;
-                ctx_.subcatches.total_lid_area_ft2[static_cast(sc)]
-                    += lu.area[uj] * static_cast(num) / ucfLen2;  // → ft²
-            }
-        }
-    }
+    // 1. LID solver — must run before the runoff solver: it fills
+    //    ctx_.subcatches.total_lid_area_ft2, which RunoffSolver::init()
+    //    subtracts from the runoff-generating area (Gap #23). With the
+    //    order reversed the array is still zeroed, the subtraction is a
+    //    no-op, and the LID footprint's rainfall is counted twice
+    //    (issue #131).
+    lid_.init(ctx_);
+    // A4: size the per-layer species block against the units the manager
+    // just built, and seed whatever they already hold.
+    transport::initLidLayerAge(ctx_, lid_);
+    transport::initLidLayerTemperature(ctx_, lid_);
 
     // 2. Runoff solver: populate RunoffSoA from subcatchment properties
     runoff_.init(ctx_);
@@ -5019,17 +8436,37 @@ void SWMMEngine::initHydrology() noexcept {
                 if (!surfaces[k]) continue;
                 const auto& p = *surfaces[k];
                 // p[0]=Cmin, p[1]=Cmax, p[2]=Tbase, p[3]=FWF, p[4]=SD0, p[5]=FW0, p[6]=SNN0
-                soa.dhmin[idx]  = p[0] / ucf::Ucf[ucf::RAINFALL][unit_sys_snow];
-                soa.dhmax[idx]  = p[1] / ucf::Ucf[ucf::RAINFALL][unit_sys_snow];
+                // legacy setMeltParams (snow.c): the melt coefficients are
+                // per DEGREE, so an SI deck's mm/hr-degC also carries
+                // UCF(TEMPERATURE) = 1.8; the initial free water is capped
+                // at FWF x SD0; ATI starts at the base temperature.
+                soa.dhmin[idx]  = p[0] * ucf::Ucf[ucf::TEMPERATURE][unit_sys_snow]
+                                       / ucf::Ucf[ucf::RAINFALL][unit_sys_snow];
+                soa.dhmax[idx]  = p[1] * ucf::Ucf[ucf::TEMPERATURE][unit_sys_snow]
+                                       / ucf::Ucf[ucf::RAINFALL][unit_sys_snow];
                 soa.tbase[idx]  = p[2];
                 if (unit_sys_snow == 1) // SI: convert °C to °F
-                    soa.tbase[idx] = soa.tbase[idx] * 9.0 / 5.0 + 32.0;
+                    soa.tbase[idx] = (9. / 5.) * soa.tbase[idx] + 32.0;
                 soa.fwfrac[idx] = p[3];
                 soa.wsnow[idx]  = p[4] / ucf::Ucf[ucf::RAINDEPTH][unit_sys_snow];
-                soa.fw[idx]     = p[5] / ucf::Ucf[ucf::RAINDEPTH][unit_sys_snow];
-                soa.si[idx]     = soa.wsnow[idx]; // depth at 100% cover = initial depth
-                if (k == snow::SNOW_PLOWABLE)
+                soa.fw[idx]     = std::min(p[5], p[3] * p[4])
+                                  / ucf::Ucf[ucf::RAINDEPTH][unit_sys_snow];
+                soa.ati[idx]    = soa.tbase[idx];
+                // F6: the 7th field is SNN0 on the PLOWABLE row and SD100 —
+                // the depth at which areal coverage reaches 100 % — on the
+                // other two. Legacy splits it exactly this way
+                // (`snow.c:348-352`). Pinning `si` to the INITIAL pack depth
+                // instead made `asc` identically 1 on every deck, so
+                // `rain·(1 − asc)` was always zero and no rain ever reached
+                // the ground under a pack unless the deck wrote an explicit
+                // ADC row.
+                if (k == snow::SNOW_PLOWABLE) {
                     soa.snn[ui] = p[6];
+                    // The plowable surface has no SD100 of its own; legacy
+                    // leaves its `si` at the init value (0).
+                } else {
+                    soa.si[idx] = p[6] / ucf::Ucf[ucf::RAINDEPTH][unit_sys_snow];
+                }
             }
 
             // Fractional area of each snow surface (legacy snow_initSnowpack,
@@ -5078,6 +8515,41 @@ void SWMMEngine::initHydrology() noexcept {
             }
         }
     }
+    // legacy snow_initSnowpack (snow.c:202): newSnowDepth starts at the
+    // initial pack's depth, so the first runoff step's old-state roll
+    // carries it into oldSnowDepth. It started at 0 here, and a run whose
+    // first runoff step is the DRY step (no rain, HasSnow not yet set —
+    // runoff25a-sw5, 23 h) reported the initial cover ramping up from 0
+    // for the whole step.
+    for (int i = 0; i < ctx_.n_subcatches(); ++i)
+        ctx_.subcatches.snow_depth[static_cast(i)] = subcatchSnowDepth(i);
+
+    // Date sanity (legacy project_validate, project.c:161-169): the run must
+    // end after it starts, and the report window must begin before the end.
+    // Push + set_error only (this function is void); the collected errors
+    // abort the run at the initialize-time errors gate.
+    // Gated on an EXPLICIT end date: a programmatically-built model reaches
+    // initialize() through swmm_finalize_model with end_date still at its
+    // zero default, and the check must not reject that build path.
+    if (ctx_.options.end_date > 0.0 &&
+        ctx_.options.end_date <= ctx_.options.start_date) {
+        ctx_.errors.push_back(format_error(ERR_START_DATE, ""));
+        set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+    } else if (ctx_.options.report_start > 0.0 &&
+               ctx_.options.end_date <= ctx_.options.report_start) {
+        ctx_.errors.push_back(format_error(ERR_REPORT_DATE, ""));
+        set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+    }
+
+    // Climate-file requirement (legacy climate_validate, climate.c:850-858):
+    // FILE wind, FILE evaporation, or TEMPERATURE (Hargreaves) evaporation
+    // need the [TEMPERATURE] FILE — its daily min/max drive them.
+    if ((ctx_.options.wind_type == 1 || ctx_.options.evap_type == 4 ||
+         ctx_.options.evap_type == 3) &&
+        ctx_.options.temp_file.empty()) {
+        ctx_.errors.push_back(format_error(ERR_NO_CLIMATE_FILE, ""));
+        set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+    }
 
     // 5. Climate: transfer evaporation data from options to climate state
     {
@@ -5090,6 +8562,10 @@ void SWMMEngine::initHydrology() noexcept {
             // SI (CMS) model with `CONSTANT 3.0` means 3 mm/day, and using the
             // US factor (1036800 vs 26334720) over-evaporates by ~25×.
             ctx_.climate_state.evap_method = climate::EvapMethod::CONSTANT;
+            ctx_.climate_state.evaprate_ucf = ucf::UCF(ucf::EVAPRATE, ctx_.options);
+            // legacy keeps the constant in monthlyEvap[0]; setEvap re-derives
+            // Evap.rate from it every runoff step before the adjustment.
+            ctx_.climate_state.monthly_evap[0] = ctx_.options.evap_values[0];
             ctx_.climate_state.evap_rate = ctx_.options.evap_values[0]
                                / ucf::UCF(ucf::EVAPRATE, ctx_.options);
         } else if (evap_type == 1) {
@@ -5109,8 +8585,15 @@ void SWMMEngine::initHydrology() noexcept {
         // Transfer latitude for Hargreaves ET calculation
         ctx_.climate_state.latitude = ctx_.options.snow_lat;
 
-        // Transfer site elevation for psychrometric constant (Gap #8)
-        ctx_.climate_state.elev = ctx_.options.snow_elev;
+        // Transfer site elevation for psychrometric constant (Gap #8) —
+        // legacy Temp.elev = x[3] / UCF(LENGTH) — and the rain/snow dividing
+        // temperature, in degF internally (legacy converts degC at parse).
+        ctx_.climate_state.elev = ctx_.options.snow_elev
+                                  / ucf::UCF(ucf::LENGTH, ctx_.options);
+        ctx_.climate_state.snow_divt =
+            (ucf::getUnitSystem(static_cast(ctx_.options.flow_units)) == 1)
+                ? 9. / 5. * ctx_.options.snow_divt + 32.0
+                : ctx_.options.snow_divt;
 
         // Transfer longitude/solar-time correction. The [TEMPERATURE] SNOWMELT
         // field and the C API store minutes; ClimateState::dtlong is in hours
@@ -5120,8 +8603,13 @@ void SWMMEngine::initHydrology() noexcept {
 
         // Transfer monthly adjustment arrays
         for (int i = 0; i < 12; ++i) {
-            ctx_.climate_state.adjust_temp[i] = ctx_.adjust_temp[i];
-            ctx_.climate_state.adjust_evap[i] = ctx_.adjust_evap[i];
+            // legacy climate_validate: an SI deck's degC adjustment is a
+            // degF DIFFERENCE, x 9/5.
+            ctx_.climate_state.adjust_temp[i] = ctx_.adjust_temp[i] *
+                ((ucf::getUnitSystem(static_cast(ctx_.options.flow_units)) == 1)
+                     ? 9.0 / 5.0 : 1.0);
+            ctx_.climate_state.adjust_evap[i] =
+                ctx_.adjust_evap[i] / ucf::UCF(ucf::EVAPRATE, ctx_.options);  // legacy climate_validate
             ctx_.climate_state.adjust_rain[i] = ctx_.adjust_rain[i];
             ctx_.climate_state.adjust_hydcon[i] = ctx_.adjust_hydcon[i];
         }
@@ -5130,9 +8618,52 @@ void SWMMEngine::initHydrology() noexcept {
         if (ctx_.options.temp_source == 1 && !ctx_.options.temp_ts_name.empty()) {
             ctx_.climate_state.temp_ts_index = ctx_.find_timeseries(ctx_.options.temp_ts_name);
         }
+
+        // With NO temperature source, legacy's air temperature stays at its
+        // project_setDefaults value: `Temp.ta = 70.0` degF (project.c:941).
+        // climate.c's setTemp never reassigns it without FILE_TEMP or
+        // TSERIES_TEMP data, so a deck with no [TEMPERATURE] section computes
+        // AND reports with 70 degF — 21.11 degC after the SI display
+        // conversion (221-h-h-si-units-elements, 15-subs-si-units). A deck
+        // with no subcatchments still reports a raw 0, because legacy assigns
+        // SYS_TEMPERATURE only inside output_saveSubcatchResults — that path
+        // is the has_subcatchments guard at the snapshot, not this default.
+        //
+        // An API-prescribed temperature still overrides this, exactly as
+        // legacy's `Temp.apiTemp` does (climate.c:1222).
+        if (ctx_.options.temp_source == 0 && ctx_.climate_state.temp_ts_index < 0) {
+            ctx_.climate_state.temperature_src = 70.0;
+            ctx_.climate_state.temperature = 70.0;
+        }
         if (evap_type == 2 && !ctx_.options.evap_ts_name.empty()) {
             ctx_.climate_state.evap_ts_index = ctx_.find_timeseries(ctx_.options.evap_ts_name);
         }
+        // legacy climate_initState: NextEvapDate / NextEvapRate. A time-series
+        // evaporation starts on its first entry (or, if that lies before the
+        // start date, on the first entry at or after it) and holds each
+        // entry's rate until the next entry's date — it is never interpolated.
+        {
+            auto& cs = ctx_.climate_state;
+            cs.next_evap_date = ctx_.options.start_date;
+            cs.next_evap_rate = 0.0;
+            cs.evap_ts_pos    = -1;
+            if (cs.evap_method == climate::EvapMethod::TIMESERIES && cs.evap_ts_index >= 0) {
+                const auto& tbl = ctx_.tables.tables[static_cast(cs.evap_ts_index)];
+                if (!tbl.x.empty()) {
+                    cs.evap_ts_pos    = 0;
+                    cs.next_evap_date = tbl.x[0];
+                    cs.next_evap_rate = tbl.y[0];
+                }
+                if (cs.next_evap_date < ctx_.options.start_date)
+                    setNextEvapDate(ctx_.options.start_date);
+                cs.evap_rate = cs.next_evap_rate / ucf::UCF(ucf::EVAPRATE, ctx_.options);
+                setNextEvapDate(cs.next_evap_date);
+            }
+        }
+        if (ctx_.options.humidity_type == 2 && !ctx_.options.humidity_ts_name.empty()) {
+            ctx_.climate_state.humidity_ts_index =
+                ctx_.find_timeseries(ctx_.options.humidity_ts_name);
+        }
 
         // Resolve recovery pattern name to pattern index (case-insensitive)
         if (!ctx_.options.evap_recovery_pat.empty()) {
@@ -5146,13 +8677,28 @@ void SWMMEngine::initHydrology() noexcept {
             }
         }
 
-        // Open climate file if temperature or evaporation uses FILE source
+        // Open climate file if temperature or evaporation uses FILE source.
+        // Use the RESOLVED path: `.original` is the token as authored, so a
+        // relative one fopen()s against the process cwd rather than the .inp
+        // directory — and ClimateFileReader::open just returns false, which
+        // nothing here checks, so the run silently proceeds with no climate
+        // data. `.absolute` is filled by resolve_external_file_slots; fall back
+        // to the token for programmatic models where the resolver never ran.
         if ((ctx_.options.temp_source == 2 || evap_type == 4) &&
             !ctx_.options.temp_file.empty()) {
             int us = ucf::getUnitSystem(static_cast(ctx_.options.flow_units));
-            climate_file_.open(ctx_.options.temp_file,
-                               ctx_.options.temp_file_start, us,
-                               ctx_.options.temp_units);
+            const std::string& climate_path =
+                !ctx_.options.temp_file.absolute.empty()
+                    ? ctx_.options.temp_file.absolute
+                    : ctx_.options.temp_file.original;
+            if (!climate_file_.open(climate_path,
+                                    ctx_.options.temp_file_start, us,
+                                    ctx_.options.temp_units)) {
+                ctx_.warnings.push_back(
+                    "[TEMPERATURE] climate file '" + climate_path +
+                    "' could not be opened or its format was not recognised — "
+                    "no climate data will be applied");
+            }
         }
     }
 
@@ -5187,9 +8733,29 @@ void SWMMEngine::initHydrology() noexcept {
                                       / ucf::Ucf[ucf::LENGTH][unit_sys];
             gw.lower_loss_coeff[ui] = ctx_.aquifers.lower_loss[uaq]
                                       / ucf::Ucf[ucf::RAINFALL][unit_sys];
-            gw.total_depth[ui]      = (ctx_.subcatches.gw_surf_elev[ui]
-                                       - ctx_.aquifers.bottom_elev[uaq])
-                                      / ucf::Ucf[ucf::LENGTH][unit_sys];
+            // The [GROUNDWATER] row's optional Ebot / Wgw / Umc override the
+            // aquifer's bottom elevation, initial water table and initial
+            // moisture (legacy gwater_validate fills MISSING from the
+            // aquifer); Egwt overrides the node invert as the lateral-flow
+            // threshold (legacy Hstar = nodeElev - bottomElev, else
+            // Node.invertElev - bottomElev). Every elevation is converted to
+            // ft as legacy does at read (x / UCF(LENGTH)) and the depths are
+            // then differences of converted elevations. Before this the
+            // threshold was the raw Egwt (0 for `*`, so a water table 10 ft
+            // over a 10 ft-high invert drove 1680 cfs into the node on the
+            // Dupuit deck), the initial lower depth was the water-table
+            // ELEVATION rather than its height above the bottom, and the
+            // three overrides were ignored.
+            const double ucf_len = ucf::Ucf[ucf::LENGTH][unit_sys];
+            const double bot_elev = (ctx_.subcatches.gw_bot_elev[ui] != constants::MISSING)
+                ? ctx_.subcatches.gw_bot_elev[ui] / ucf_len
+                : ctx_.aquifers.bottom_elev[uaq] / ucf_len;
+            const double wt_elev  = (ctx_.subcatches.gw_wt_elev[ui] != constants::MISSING)
+                ? ctx_.subcatches.gw_wt_elev[ui] / ucf_len
+                : ctx_.aquifers.water_table_elev[uaq] / ucf_len;
+            const double surf_elev = ctx_.subcatches.gw_surf_elev[ui] / ucf_len;
+            gw.total_depth[ui]      = surf_elev - bot_elev;
+            gw.bottom_elev[ui]      = bot_elev;
 
             // Copy GW lateral flow coefficients
             gw.a1[ui]     = ctx_.subcatches.gw_a1[ui];
@@ -5197,13 +8763,28 @@ void SWMMEngine::initHydrology() noexcept {
             gw.a2[ui]     = ctx_.subcatches.gw_a2[ui];
             gw.b2[ui]     = ctx_.subcatches.gw_b2[ui];
             gw.a3[ui]     = ctx_.subcatches.gw_a3[ui];
-            gw.h_star[ui] = ctx_.subcatches.gw_hstar[ui]
-                            / ucf::Ucf[ucf::LENGTH][unit_sys];
+            {
+                double node_elev;
+                if (ctx_.subcatches.gw_hstar[ui] != constants::MISSING) {
+                    node_elev = ctx_.subcatches.gw_hstar[ui] / ucf_len;
+                } else {
+                    int gwn = ctx_.subcatches.gw_node[ui];
+                    if (gwn < 0) gwn = ctx_.subcatches.outlet_node[ui];
+                    node_elev = (gwn >= 0 && gwn < ctx_.n_nodes())
+                        ? ctx_.nodes.invert_elev[static_cast(gwn)] : 0.0;
+                }
+                gw.h_star[ui] = node_elev - bot_elev;
+            }
 
-            // Initial conditions from aquifer
-            gw.theta[ui]      = ctx_.aquifers.upper_moist[uaq];
-            gw.lower_depth[ui] = ctx_.aquifers.water_table_elev[uaq]
-                                 / ucf::Ucf[ucf::LENGTH][unit_sys];
+            // Initial conditions (legacy gwater_initState)
+            double theta0 = (ctx_.subcatches.gw_upper_moist[ui] != constants::MISSING)
+                ? ctx_.subcatches.gw_upper_moist[ui]
+                : ctx_.aquifers.upper_moist[uaq];
+            if (theta0 >= gw.porosity[ui]) theta0 = gw.porosity[ui] - constants::XTOL;
+            gw.theta[ui] = theta0;
+            double lower0 = wt_elev - bot_elev;
+            if (lower0 >= gw.total_depth[ui]) lower0 = gw.total_depth[ui] - constants::XTOL;
+            gw.lower_depth[ui] = lower0;
         }
 
         // Parse [GWF] custom expressions (stored in ext_options during input parsing).
@@ -5215,25 +8796,30 @@ void SWMMEngine::initHydrology() noexcept {
 
             const std::string& sc_name = ctx_.subcatch_names.names()[ui];
 
-            auto lat_it = ctx_.options.ext_options.find("GWF:" + sc_name + ":LATERAL");
-            if (lat_it != ctx_.options.ext_options.end() && !lat_it->second.empty()) {
-                mathexpr::Expression expr;
-                if (mathexpr::parse(lat_it->second, expr) == 0 && expr.valid) {
-                    mathexpr::bind_variables(expr,
-                        groundwater::GW_VAR_NAMES, groundwater::GWV_MAX);
-                    gw.lateral_expr[ui] = std::move(expr);
-                }
-            }
-
-            auto deep_it = ctx_.options.ext_options.find("GWF:" + sc_name + ":DEEP");
-            if (deep_it != ctx_.options.ext_options.end() && !deep_it->second.empty()) {
+            // An expression that fails to compile is a model error, not
+            // something to drop silently (legacy ERR_MATH_EXPR). gwf_validate
+            // is stricter than mathexpr::parse (unknown identifiers would
+            // otherwise evaluate to 0.0) and supplies the diagnostic.
+            auto compile = [&](const char* type, mathexpr::Expression& out) {
+                auto it = ctx_.options.ext_options.find("GWF:" + sc_name + ":" + type);
+                if (it == ctx_.options.ext_options.end() || it->second.empty()) return;
+                std::string msg;
+                int col = -1;
                 mathexpr::Expression expr;
-                if (mathexpr::parse(deep_it->second, expr) == 0 && expr.valid) {
-                    mathexpr::bind_variables(expr,
-                        groundwater::GW_VAR_NAMES, groundwater::GWV_MAX);
-                    gw.deep_expr[ui] = std::move(expr);
+                if (groundwater::gwf_validate(it->second, msg, col) != 0 ||
+                    mathexpr::parse(it->second, expr) != 0 || !expr.valid) {
+                    ctx_.errors.push_back(format_error(ERR_MATH_EXPR, "",
+                        "in [GWF] " + std::string(type) + " for Subcatchment " +
+                        sc_name + ": " + msg));
+                    set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
+                    return;
                 }
-            }
+                mathexpr::bind_variables(expr,
+                    groundwater::GW_VAR_NAMES, groundwater::GWV_MAX);
+                out = std::move(expr);
+            };
+            compile("LATERAL", gw.lateral_expr[ui]);
+            compile("DEEP",    gw.deep_expr[ui]);
         }
     }
 
@@ -5260,8 +8846,8 @@ void SWMMEngine::initHydrology() noexcept {
         }
     }
 
-    // 7. LID solver
-    lid_.init(ctx_);
+    // 7. LID solver: initialized first (step 1) so total_lid_area_ft2 is
+    //    populated before RunoffSolver::init() consumes it.
 
     // Gap #82: LID parameter validation
     {
@@ -5280,18 +8866,21 @@ void SWMMEngine::initHydrology() noexcept {
                     }
                 }
             }
-            // Storage layer: [0]=thickness, [1]=voidFrac
+            // Storage layer: [0]=thickness, [1]=void RATIO (voids/solids),
+            // converted to a fraction p/(p+1) in LIDSolver::init (issue #102).
+            // Legacy readStorageData accepts any non-negative ratio; a cap at
+            // 1.0 here would silently limit storage to 50 % voids.
             if (uj < ctx_.lid_controls.storage.size()) {
                 const auto& s = ctx_.lid_controls.storage[uj];
-                if (s[0] > 0.0 && (s[1] <= 0.0 || s[1] > 1.0)) {
+                if (s[0] > 0.0 && s[1] <= 0.0) {
                     ctx_.errors.push_back(format_error(ERR_LID_PARAMS, lname));
                     set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
                 }
             }
-            // Pavement layer: [0]=thickness, [1]=voidRatio
+            // Pavement layer: [0]=thickness, [1]=void RATIO — same convention.
             if (uj < ctx_.lid_controls.pavement.size()) {
                 const auto& p = ctx_.lid_controls.pavement[uj];
-                if (p[0] > 0.0 && (p[1] <= 0.0 || p[1] > 1.0)) {
+                if (p[0] > 0.0 && p[1] <= 0.0) {
                     ctx_.errors.push_back(format_error(ERR_LID_PARAMS, lname));
                     set_error(SWMM_ERR_PARSE, ctx_.errors.back().c_str());
                 }
@@ -5324,6 +8913,80 @@ void SWMMEngine::initQuality() noexcept {
     // 7. Quality solver
     quality_.init(ctx_.n_nodes(), ctx_.n_links(), ctx_.n_pollutants());
 
+    // Seed initial concentrations from [POLLUTANTS] Cinit. A wet node/link
+    // starts at the pollutant's initial concentration, a dry one at zero —
+    // legacy qualrout.c qualrout_init(), called from routing_open() at the
+    // same point in the sequence (after the router has set initial depths).
+    // Without this every run started clean and "Initial Stored Mass" was
+    // always 0.
+    {
+        const int np = ctx_.n_pollutants();
+        if (np > 0) {
+            // Legacy qualrout.c: static const double ZeroDepth = 0.003281 (1 mm).
+            constexpr double zero_depth = 0.003281;
+            for (int i = 0; i < ctx_.n_nodes(); ++i) {
+                const auto ui = static_cast(i);
+                const bool wet = ctx_.nodes.depth[ui] > zero_depth;
+                for (int p = 0; p < np; ++p) {
+                    const auto idx = ui * static_cast(np) +
+                                     static_cast(p);
+                    if (idx >= ctx_.nodes.conc.size()) continue;
+                    const double c = wet
+                        ? ctx_.pollutants.init_conc[static_cast(p)]
+                        : 0.0;
+                    ctx_.nodes.conc[idx]     = c;
+                    ctx_.nodes.conc_old[idx] = c;
+                }
+            }
+            for (int j = 0; j < ctx_.n_links(); ++j) {
+                const auto uj = static_cast(j);
+                const bool wet = ctx_.links.depth[uj] > zero_depth;
+                for (int p = 0; p < np; ++p) {
+                    const auto idx = uj * static_cast(np) +
+                                     static_cast(p);
+                    if (idx >= ctx_.links.conc.size()) continue;
+                    const double c = wet
+                        ? ctx_.pollutants.init_conc[static_cast(p)]
+                        : 0.0;
+                    ctx_.links.conc[idx]     = c;
+                    ctx_.links.conc_old[idx] = c;
+                }
+            }
+
+            // [INITIAL_QUALITY] per-element pollutant overrides — applied
+            // after the global Cinit seed ("specific beats general"), wet or
+            // dry (D-IQ4: an explicit per-element row is the user's intent,
+            // unlike the global default; mass stays C·V-safe because a dry
+            // element holds no volume). One write site feeds all three
+            // quality engines (D-IQ6): ARD and LARD both initialize lazily
+            // on their first step FROM these arrays, and the legacy CSTR
+            // routes on them directly. Reserved-species rows (age /
+            // temperature, kind < 0) are consumed at their seed sites (E-A3).
+            // When hotstart quality restore lands it must win over both
+            // seeds — apply it AFTER this block (D-IQ5).
+            {
+                const auto& iq = ctx_.initial_quality;
+                for (int r = 0; r < iq.count(); ++r) {
+                    const auto ur = static_cast(r);
+                    const int k = iq.kind[ur];
+                    if (k < 0 || k >= np) continue;   // reserved/unresolved
+                    const int ei = iq.elem_idx[ur];
+                    if (ei < 0) continue;
+                    auto& conc     = iq.is_link[ur] ? ctx_.links.conc
+                                                    : ctx_.nodes.conc;
+                    auto& conc_old = iq.is_link[ur] ? ctx_.links.conc_old
+                                                    : ctx_.nodes.conc_old;
+                    const auto idx = static_cast(ei) *
+                                     static_cast(np) +
+                                     static_cast(k);
+                    if (idx >= conc.size()) continue;
+                    conc[idx]     = iq.value[ur];
+                    conc_old[idx] = iq.value[ur];
+                }
+            }
+        }
+    }
+
     // 10. Treatment: resize for nodes x pollutants + compile expressions
     if (ctx_.n_pollutants() > 0 && ctx_.n_nodes() > 0) {
         if (ctx_.treatment.n_nodes == 0) {
@@ -5337,7 +9000,8 @@ void SWMMEngine::initQuality() noexcept {
                 const auto& expr_str = ctx_.treatment.expressions[idx];
                 if (expr_str.empty()) continue;
                 treatment::TreatExpr te;
-                if (treatment::parse(expr_str, te) == 0) {
+                if (treatment::parse(expr_str, te,
+                                     ctx_.pollutant_names.names()) == 0) {
                     te.pollutant_idx = p;
                     ctx_.treatment.compiled[idx] = std::move(te);
                     ctx_.treatment.has_treatment[static_cast(n)] = true;
@@ -5413,54 +9077,126 @@ void SWMMEngine::initQuality() noexcept {
         // Initialize quality mass balance vectors
         ctx_.mass_balance.resize_quality(np);
 
-        // Compute initial buildup from antecedent dry days
-        // (matching legacy landuse_getInitBuildup)
-        // Buildup is stored PER LAND USE: buildup[bu_idx(sc,lu,p)] = mass/normalizer
-        double dry_days = ctx_.options.dry_days;
-        if (dry_days > 0.0 && ctx_.n_landuses() > 0) {
+        // Initial surface buildup — legacy landuse_getInitBuildup
+        // (landuse.c:347-400), which runs for EVERY land use of EVERY
+        // subcatchment whatever DRY_DAYS is, and takes one of two branches
+        // per pollutant:
+        //
+        //   a [LOADINGS] initial loading, if one was supplied, seeds
+        //   `initBuildup[p] * fArea` — a mass per unit AREA, applied whether
+        //   or not the land use has a buildup function at all;
+        //
+        //   otherwise the land use's own buildup function is run over the
+        //   antecedent dry period.
+        //
+        // v6 ran only the second branch, and only when DRY_DAYS was
+        // positive, so every [LOADINGS] row was inert. swmm5buildupwashoff
+        // starts legacy with 40 kg of SF1 on the ground and started v6 with
+        // nothing — its first-flush washoff read 1.9 mg/L against legacy's
+        // 3600.
+        //
+        // Buildup is stored PER LAND USE and PER NORMALIZER UNIT:
+        // buildup[bu_idx(sc,lu,p)] * norm is the absolute mass.
+        const double dry_days = ctx_.options.dry_days;
+        if (ctx_.n_landuses() > 0) {
             for (int i = 0; i < ctx_.n_subcatches(); ++i) {
                 auto ui = static_cast(i);
                 for (int lu = 0; lu < nlu; ++lu) {
+                    // legacy landuse_initState (landuse.c:377):
+                    //     lastSwept = StartDateTime - sweepDays0
+                    // — the days-since-last-sweep clock STARTS at the
+                    // [LANDUSES] SweepDays0 column, for every land use,
+                    // covered or not. Left at zero, a deck due for its first
+                    // sweep at t = 0 (runoff46-sw5: interval 1 day,
+                    // days-since-last 1) never swept within a short run:
+                    // legacy removed 886 lbs of COD there, v6 0.000.
+                    {
+                        auto sw_idx = ui * static_cast(nlu)
+                                      + static_cast(lu);
+                        if (sw_idx < ctx_.subcatches.sweep_last_swept.size())
+                            ctx_.subcatches.sweep_last_swept[sw_idx] =
+                                ctx_.landuses.last_swept[
+                                    static_cast(lu)];
+                    }
                     auto cov_idx = ui * static_cast(nlu)
                                    + static_cast(lu);
                     double frac = (cov_idx < ctx_.subcatches.coverage.size())
                                   ? ctx_.subcatches.coverage[cov_idx] / 100.0 : 0.0;
                     if (frac <= 0.0) continue;
 
+                    // legacy fArea = fraction * area, in the user's land-area
+                    // units (landuse.c:377) — the [LOADINGS] multiplier.
+                    const double f_area = frac * ctx_.subcatches.area[ui];
+
                     for (int p = 0; p < np; ++p) {
                         auto k = static_cast(lu * np + p);
                         const auto& bp = landuse_solver_.buildup_params[k];
-                        if (bp.type == landuse::BuildupType::NONE) continue;
 
-                        double mass = 0.0;
-                        double c0 = bp.coeff[0], c1 = bp.coeff[1], c2 = bp.coeff[2];
-                        switch (bp.type) {
-                            case landuse::BuildupType::POWER:
-                                mass = std::min(c1 * std::pow(dry_days, c2), c0);
-                                break;
-                            case landuse::BuildupType::EXPON:
-                                mass = c0 * (1.0 - std::exp(-c1 * dry_days));
-                                break;
-                            case landuse::BuildupType::SATUR:
-                                mass = (c2 + dry_days > 0.0) ? c0 * dry_days / (c2 + dry_days) : 0.0;
-                                break;
-                            default: break;
+                        const double norm = (bp.normalizer == 0)
+                            ? f_area : frac * ctx_.subcatches.curb_length[ui];
+
+                        const auto li = ui * static_cast(np)
+                                      + static_cast(p);
+                        const double init_load =
+                            (li < ctx_.subcatches.init_loading.size())
+                                ? ctx_.subcatches.init_loading[li] : 0.0;
+
+                        double mass = 0.0;   // per normalizer unit
+                        if (init_load > 0.0) {
+                            // Legacy multiplies the loading by fArea whatever
+                            // the buildup function's own normalizer is, so
+                            // convert into the per-normalizer store. For the
+                            // PER_AREA default norm IS f_area and the ratio
+                            // is exactly 1.
+                            if (norm > 0.0) mass = init_load * f_area / norm;
+                        } else if (bp.type != landuse::BuildupType::NONE &&
+                                   dry_days > 0.0) {
+                            double c0 = bp.coeff[0], c1 = bp.coeff[1], c2 = bp.coeff[2];
+                            switch (bp.type) {
+                                case landuse::BuildupType::POWER:
+                                    mass = std::min(c1 * std::pow(dry_days, c2), c0);
+                                    break;
+                                case landuse::BuildupType::EXPON:
+                                    mass = c0 * (1.0 - std::exp(-c1 * dry_days));
+                                    break;
+                                case landuse::BuildupType::SATUR:
+                                    mass = (c2 + dry_days > 0.0) ? c0 * dry_days / (c2 + dry_days) : 0.0;
+                                    break;
+                                default: break;
+                            }
+                        } else {
+                            continue;
                         }
 
-                        // Store per-landuse buildup (per normalizer unit)
                         auto bu = surface_quality_.bu_idx(i, lu, p);
                         surface_quality_.buildup[bu] = mass;
-
-                        // Normalize to absolute mass for mass balance
-                        double norm = (bp.normalizer == 0)
-                            ? frac * ctx_.subcatches.area[ui]
-                            : frac * ctx_.subcatches.curb_length[ui];
                         ctx_.mass_balance.qual_init_buildup[static_cast(p)] += mass * norm;
                     }
                 }
             }
         }
     }
+
+    // MSX element state is INITIAL state, so it belongs here with the rest of
+    // the initial quality — not on the first step. Every caller of
+    // ensureMsxState was a stepping path (ArdEngine::execute, routeLegacyMsx,
+    // reactElements, the LARD solver), so between initialize() and the first
+    // step reactions.msx_node_conc was empty: [INITIAL_QUALITY] species rows
+    // had parsed and were readable through swmm_init_quality_get, but had not
+    // reached the element state the solvers and the C API read.
+    //
+    // Placement is load-bearing. initialize() applies USE HOTSTART before
+    // init_modules() (see the ordering comment there), so a hotstart run has
+    // already sized and seeded these arrays by now and ensureMsxState's
+    // size check makes this a no-op — which is the contract HotStartManager
+    // documents ("ensureMsxState skips its GLOBAL fill once sized"). Calling
+    // it any earlier would seed from GLOBAL and let the hotstart overwrite,
+    // calling it later leaves the gap this closes.
+    if (ctx_.reactions.n_species() > 0) transport::ensureMsxState(ctx_);
+    // BW-MSX: initial buildup of the reactions component's species —
+    // [LOADINGS] row or the buildup function at DRY_DAYS (legacy
+    // landuse_getInitBuildup), like the pollutant block above.
+    if (!ctx_.options.ignore_quality) msxsurf::initState(ctx_);
 }
 
 // ============================================================================
@@ -5492,72 +9228,93 @@ void SWMMEngine::initGeometry() noexcept {
         // link, so a weir or orifice hanging off a junction raises its crown
         // (and thus its EXTRAN surcharge threshold), e.g. Bellinge G75F65Y.
         // Legacy link_readParams mirrors offset2 = offset1 for orifices,
-        // weirs and outlets (link.c:368-391); weir/outlet crest heights live
-        // in the subtype tables here, so reconstruct them per type. Pumps
-        // keep offset 0 and yFull 0 (link.c:334-335, pump_validate), making
-        // their contribution the node invert — a no-op under MAX.
+        // weirs and outlets (link.c:368-391) and link_validate's WARNING-10
+        // raise then lifts offset1 ALONE to the downstream invert; weir /
+        // outlet crest heights (raised) live in the subtype tables here and
+        // the resolver keeps the un-raised crest in links.offset2 for every
+        // regulator. Pumps keep offset 0 and yFull 0 (link.c:334-335,
+        // pump_validate), making their contribution the node invert — a
+        // no-op under MAX. Using the raised crest at the downstream end
+        // lifted extran1-dual-drainage's JCT-12 crown above its 0.6 ft
+        // channel crown, so the node never surcharged where legacy did.
         double off1 = ctx_.links.offset1[uj];
         double off2 = ctx_.links.offset2[uj];
         switch (ctx_.links.type[uj]) {
             case LinkType::ORIFICE:
-                off2 = off1;                              // link.c:368-369
-                break;
+                break;                                    // offset1 raised, offset2 as parsed
             case LinkType::WEIR: {
                 const int wr = ctx_.link_subtypes.weir_row(j);
                 off1 = (wr >= 0) ? ctx_.link_subtypes.weirs
                            .crest_height[static_cast(wr)] : 0.0;
-                off2 = off1;                              // link.c:377-378
                 break;
             }
             case LinkType::OUTLET: {
                 const int olr = ctx_.link_subtypes.outlet_row(j);
                 off1 = (olr >= 0) ? ctx_.link_subtypes.outlets
                            .crest_height[static_cast(olr)] : 0.0;
-                off2 = off1;                              // link.c:390-391
                 break;
             }
             default: break;  // CONDUIT: parsed offsets; PUMP: zeros
         }
-        double z1 = ctx_.nodes.invert_elev[un1] + off1
-                     + ctx_.links.xsect_y_full[uj];
-        double z2 = ctx_.nodes.invert_elev[un2] + off2
-                     + ctx_.links.xsect_y_full[uj];
+        // legacy xsect.yFull of a DUMMY section (an outlet's, a DUMMY
+        // conduit's — xsect_setParams(DUMMY) sets every dimension to TINY)
+        // is 1e-6, not 0: a junction whose only link is an outlet gets a
+        // crown 1e-6 above its invert and is EXTRAN-"surcharged" from the
+        // first drop, with sumdqdh 0 — its depth freezes and its inflow is
+        // lost (high-low-flow's 81009E, 5.8 % continuity error in legacy).
+        // A pump's yFull is 0 (pump_validate).
+        double yf = ctx_.links.xsect_y_full[uj];
+        if (ctx_.links.type[uj] == LinkType::OUTLET ||
+            (ctx_.links.type[uj] == LinkType::CONDUIT &&
+             ctx_.links.xsect_shape[uj] == XsectShape::DUMMY))
+            yf = constants::TINY;
+        double z1 = ctx_.nodes.invert_elev[un1] + off1 + yf;
+        double z2 = ctx_.nodes.invert_elev[un2] + off2 + yf;
         if (z1 > ctx_.nodes.crown_elev[un1])
             ctx_.nodes.crown_elev[un1] = z1;
         if (z2 > ctx_.nodes.crown_elev[un2])
             ctx_.nodes.crown_elev[un2] = z2;
-        // Track node degree (connectivity count) — conduits only, unchanged.
-        if (ctx_.links.type[uj] != LinkType::CONDUIT) continue;
-        ctx_.nodes.degree[un1]++;
-        ctx_.nodes.degree[un2]++;
-    }
-
-    // 12b. PARITY: negate the degree of nodes with NO inflow links so that
-    // `degree < 0` marks an "upstream terminal" node — matching legacy
-    // flowrout.c::validateGeneralLayout. The EXTRAN surcharge depth update
-    // (setNodeDepth) multiplies dy by corr = 0.6 for these nodes
-    // (`if (Node[i].degree < 0) corr = 0.6`); without it a surcharging headwater
-    // junction (e.g. extran1 node 80408, fed only by a 45-cfs external inflow
-    // through a single OUTFLOW conduit) raised its head 1/0.6 = 1.67x too fast.
-    // An "inflow link" is one whose DOWNSTREAM node — node2, or node1 when node1
-    // is an OUTFALL — is this node. Done here, after BOTH degree passes, so the
-    // sign is not clobbered by a subsequent ++.
+    }
+
+    // 12b. legacy Node.degree, in full (toposort_sortLinks + flowrout.c
+    // validateGeneralLayout): the OUTFLOW-link count — each link at its
+    // upstream node, the downstream one when the upstream node is an
+    // outfall, a reversed conduit (direction < 0) taken from its other end —
+    // negated under the dynamic wave for a node with no INFLOW links (the
+    // downstream end being node2, or node1 when node1 is an outfall). Every
+    // reader wants those semantics: `degree < 0` is the headwater whose
+    // EXTRAN surcharge update uses corr = 0.6, `== 0` the terminal node of
+    // node_getSystemOutflow / iface outlets / inflowHasChanged, `<= 0` the
+    // stats skip. The former value (every link counted at both ends, plus
+    // the conduits again, negated) read -4 for session79-squaremodel's
+    // dead-end J-641 — two reversed conduits in, nothing out, legacy 0 —
+    // and its surcharge step took corr 0.6 where legacy takes 1.0, so the
+    // Picard loop converged after 2 iterations where legacy ran 15.
     {
         const int nn = ctx_.n_nodes();
+        std::fill(ctx_.nodes.degree.begin(), ctx_.nodes.degree.end(), 0);
         std::vector inflow_links(static_cast(nn), 0);
         for (int j = 0; j < ctx_.n_links(); ++j) {
             auto uj = static_cast(j);
-            int n1 = ctx_.links.node1[uj];
-            int n2 = ctx_.links.node2[uj];
-            int dn = n2;
-            if (n1 >= 0 && n1 < nn &&
-                ctx_.nodes.type[static_cast(n1)] == NodeType::OUTFALL)
-                dn = n1;
-            if (dn >= 0 && dn < nn) inflow_links[static_cast(dn)]++;
-        }
-        for (int i = 0; i < nn; ++i) {
-            auto ui = static_cast(i);
-            if (inflow_links[ui] == 0) ctx_.nodes.degree[ui] = -ctx_.nodes.degree[ui];
+            const int n1 = ctx_.links.node1[uj];
+            const int n2 = ctx_.links.node2[uj];
+            if (n1 < 0 || n1 >= nn || n2 < 0 || n2 >= nn) continue;
+            // outflow count (toposort.c:75-91)
+            int n = (ctx_.links.direction[uj] < 0) ? n2 : n1;
+            if (ctx_.nodes.type[static_cast(n)] == NodeType::OUTFALL)
+                n = (ctx_.links.direction[uj] < 0) ? n1 : n2;
+            ctx_.nodes.degree[static_cast(n)]++;
+            // inflow count (flowrout.c validateGeneralLayout)
+            int dn = n1;
+            if (ctx_.nodes.type[static_cast(dn)] != NodeType::OUTFALL) dn = n2;
+            inflow_links[static_cast(dn)]++;
+        }
+        if (ctx_.options.routing_model == RoutingModel::DYNWAVE ||
+            ctx_.options.routing_model == RoutingModel::FV) {
+            for (int i = 0; i < nn; ++i) {
+                auto ui = static_cast(i);
+                if (inflow_links[ui] == 0) ctx_.nodes.degree[ui] = -ctx_.nodes.degree[ui];
+            }
         }
     }
 
@@ -5589,6 +9346,7 @@ void SWMMEngine::resetStepMassBalance() noexcept {
     ctx_.mass_balance.step_gw_inflow    = 0.0;
     ctx_.mass_balance.step_rdii_inflow  = 0.0;
     ctx_.mass_balance.step_ext_inflow   = 0.0;
+    ctx_.mass_balance.step_ext_withdrawal = 0.0;
 }
 
 // ============================================================================
@@ -5610,10 +9368,14 @@ void SWMMEngine::assembleGWCoupling(double dt_runoff) noexcept {
         if (gw_node < 0) gw_node = ctx_.subcatches.outlet_node[ui];
         if (gw_node >= 0 && gw_node < ctx_.n_nodes()) {
             auto un = static_cast(gw_node);
-            double bottom_elev = ctx_.aquifers.bottom_elev[static_cast(aq_idx)];
+            // The subcatchment's effective aquifer bottom in ft (the row's
+            // Ebot when given, else the aquifer's), as resolved at init.
+            double bottom_elev = groundwater_.state().bottom_elev[ui];
             // Gap #41: fixedDepth option — use a fixed SW head instead of live node depth.
-            // gw_tw stores the fixedDepth parameter (tok[9] in [GROUNDWATER] section).
-            double fixed_depth = ctx_.subcatches.gw_tw[ui];
+            // gw_tw stores the fixedDepth parameter (tok[9] in [GROUNDWATER] section)
+            // in the deck's length units, legacy's x[6] / UCF(LENGTH).
+            double fixed_depth = ctx_.subcatches.gw_tw[ui]
+                / ucf::UCF(ucf::LENGTH, ctx_.options);
             if (fixed_depth > 0.0) {
                 // Hsw = fixedDepth + nodeInvertElev - bottomElev  (matching legacy gwater.c)
                 ctx_.subcatches.gw_sw_head[ui] =
@@ -5624,7 +9386,7 @@ void SWMMEngine::assembleGWCoupling(double dt_runoff) noexcept {
             }
 
             // Available node flow for GW negative flow limit
-            double area_ft2 = ctx_.subcatches.area[ui] * ucf::ACRES_TO_FT2;
+            double area_ft2 = ctx_.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx_.options);
             if (area_ft2 > 0.0 && dt_runoff > 0.0) {
                 ctx_.subcatches.gw_node_avail_flow[ui] =
                     (ctx_.nodes.inflow[un] + ctx_.nodes.volume[un] / dt_runoff) / area_ft2;
@@ -5637,41 +9399,167 @@ void SWMMEngine::assembleGWCoupling(double dt_runoff) noexcept {
 // assembleRunon — subcatch-to-subcatch + outfall runon into runon_inflow[]
 // ============================================================================
 
-void SWMMEngine::assembleRunon(double dt_runoff) noexcept {
+void SWMMEngine::assembleRunon() noexcept {
     std::fill(ctx_.subcatches.runon_inflow.begin(),
               ctx_.subcatches.runon_inflow.end(), 0.0);
+    std::fill(ctx_.subcatches.runon_rate.begin(),
+              ctx_.subcatches.runon_rate.end(), 0.0);
+    // The run-on POLLUTANT load is assembled here with its water, from the
+    // same previous-substep values (legacy zeroes Subcatch.newQual at
+    // setOldState and getRunon then accumulates into it, subcatch.c:488,553).
+    std::fill(ctx_.subcatches.runon_qual_rate.begin(),
+              ctx_.subcatches.runon_qual_rate.end(), 0.0);
+    // The age and temperature of that run-on are assembled here too, so
+    // their accumulators start clean here (not in the transport step that
+    // consumes them — the flow and its temperature must be booked, and
+    // readable, together for the whole runoff step).
+    {
+        auto& ws = ctx_.water_age_state;
+        std::fill(ws.subcatch_runon_age_vol_in.begin(),
+                  ws.subcatch_runon_age_vol_in.end(), 0.0);
+        auto& hs = ctx_.heat_state;
+        std::fill(hs.subcatch_runon_temp_vol_in.begin(),
+                  hs.subcatch_runon_temp_vol_in.end(), 0.0);
+        std::fill(hs.subcatch_runon_temp_rate.begin(),
+                  hs.subcatch_runon_temp_rate.end(), 0.0);
+    }
+    const int nsc = ctx_.n_subcatches();
+    const double land2ft2 = 1.0 / ucf::UCF(ucf::LANDAREA, ctx_.options);
+    const auto& rsoa = runoff_.soa();
 
-    // Subcatch-to-subcatch: upstream runoff → downstream runon (CFS)
-    for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+    // legacy subcatch_addRunonFlow: each contribution is divided by the
+    // NON-LID area (the full area when there is none) and added to the
+    // depth rate; the CFS twin feeds the ledgers, age and temperature.
+    auto add_runon = [&](int k, double q) {
+        auto uk = static_cast(k);
+        const double full_ft2 = ctx_.subcatches.area[uk] * land2ft2;
+        if (full_ft2 <= 0.0) return;
+        const double nonlid = rsoa.area[uk];
+        ctx_.subcatches.runon_rate[uk] +=
+            (nonlid > 0.0) ? q / nonlid : q / full_ft2;
+        ctx_.subcatches.runon_inflow[uk] += q;
+    };
+
+    // Gap #28: outfall runon FIRST (legacy runoff.c:247 runoff_getOutfallRunon
+    // precedes subcatch_getRunon) — the routed volume over the PREVIOUS
+    // runoff step's span (oldRunoffStep), held over while there is none yet.
+    const double dt_prev = prev_runoff_step_sec_;
+    if (dt_prev > 0.0) {
+        for (int i = 0; i < nsc; ++i) {
+            auto ui = static_cast(i);
+            double vol = ctx_.subcatches.outfall_runon_vol[ui];
+            if (vol > 0.0) {
+                add_runon(i, vol / dt_prev);
+                auto& wo = ctx_.water_age_state.subcatch_outfall_age_vol;
+                if (ctx_.options.water_age && ui < wo.size() &&
+                    ui < ctx_.water_age_state.subcatch_runon_age_vol_in.size()) {
+                    ctx_.water_age_state.subcatch_runon_age_vol_in[ui] +=
+                        wo[ui] / dt_prev;
+                    wo[ui] = 0.0;
+                }
+                // H5a: the temperature of that returning water. Goes through
+                // addRunonTemperatureAt so the numerator and the rate move
+                // together — see HeatData.hpp on why they are a pair.
+                auto& ho = ctx_.heat_state.subcatch_outfall_temp_vol;
+                if (ctx_.options.heat_transport && ui < ho.size()) {
+                    transport::addRunonTemperatureAt(
+                        ctx_, i, vol / dt_prev, ho[ui] / vol);
+                    ho[ui] = 0.0;
+                }
+                // Water re-entering the runoff system from an outfall is new
+                // inflow to its mass balance (legacy runoff.c:520
+                // RUNOFF_RUNON) — without this, LID or subarea uptake of the
+                // routed volume reads as a continuity error (issue #131).
+                ctx_.mass_balance.runoff_runon += vol;
+                ctx_.subcatches.outfall_runon_vol[ui] = 0.0;
+            }
+        }
+    }
+
+    // Subcatch-to-subcatch: upstream runoff → downstream runon (CFS), in
+    // subcatchment order (legacy subcatch_getRunon per j; a subcatchment
+    // without area is skipped, runoff.c:252).
+    for (int i = 0; i < nsc; ++i) {
         auto ui = static_cast(i);
+        if (ctx_.subcatches.area[ui] == 0.0) continue;
         int out_sc = ctx_.subcatches.outlet_subcatch[ui];
-        if (out_sc >= 0 && out_sc < ctx_.n_subcatches()) {
-            auto usc = static_cast(out_sc);
-            ctx_.subcatches.runon_inflow[usc] += ctx_.subcatches.runoff[ui];
+        // `out_sc != i` is legacy's guard (subcatch.c:546-548,
+        // `k >= 0 && k != subcatchIndex`) and its absence here was the whole
+        // defect: a subcatchment routed to ITSELF fed its own runoff back into
+        // its own run-on every step and recirculated. Measured against legacy
+        // 5.x on the selfroute fixture: 2.328 acre-feet of surface runoff
+        // booked against legacy's 0.417 — 5.6× — with −265 % continuity, while
+        // direct, 2-deep, 3-deep and all-direct cascades all agreed to the
+        // digit.
+        //
+        // A self-route is not a cascade. Legacy treats it as a subcatchment
+        // that discharges to the system like any other; the outlet name is
+        // simply a no-op. `421e95c2` already carries that reading in the
+        // runoff ledger (`sheds_to_self`), and this is the site that makes the
+        // ledger's number true rather than merely consistent.
+        //
+        // This guard covers the age and temperature run-on seams below too:
+        // both live inside this branch, so a self-route was also feeding its
+        // own age and its own heat back to itself.
+        if (out_sc >= 0 && out_sc < nsc && out_sc != i) {
+            add_runon(out_sc, ctx_.subcatches.runoff[ui]);
+            // The donor's pollutant load rides with its water: legacy
+            // subcatch.c:553, newQual[k] += oldRunoff * oldQual * LperFT3.
+            // conc_old is the donor's previous-substep washoff concentration
+            // in mg/L (rolled by save_state before this assembly, exactly
+            // legacy's oldQual after setOldState), and runoff[ui] still
+            // holds the previous substep's value here, legacy's oldRunoff —
+            // so cfs * mg/L * L/ft3 accumulates mg/sec. Without this the
+            // receiver mixed the donor's WATER at zero concentration:
+            // washoff-runon's subcatchment 2 reported a flat EMC 10 against
+            // legacy's ponded mix rising above it from the first period.
+            {
+                const int np_r = ctx_.n_pollutants();
+                for (int p = 0; p < np_r; ++p) {
+                    auto src = ui * static_cast(np_r)
+                               + static_cast(p);
+                    auto dst = static_cast(out_sc)
+                               * static_cast(np_r)
+                               + static_cast(p);
+                    if (src < ctx_.subcatches.conc_old.size() &&
+                        dst < ctx_.subcatches.runon_qual_rate.size())
+                        ctx_.subcatches.runon_qual_rate[dst] +=
+                            ctx_.subcatches.runoff[ui] *
+                            ctx_.subcatches.conc_old[src] * 28.317;
+                }
+            }
+            // A3: run-on carries the donor's runoff age. Without this the
+            // FLOW path adds q_runon while the age path adds nothing, and a
+            // two-subcatchment cascade — the plan's own A3 criterion —
+            // delivers water with no upstream age attached.
+            transport::addRunonAge(ctx_, i, out_sc,
+                                   ctx_.subcatches.runoff[ui]);
+            // H5a: the same seam for temperature.
+            transport::addRunonTemperature(ctx_, i, out_sc,
+                                           ctx_.subcatches.runoff[ui]);
         }
     }
 
     // Gap #25: LID drain runon — drain accumulated CFS into runon_inflow and reset.
     // Matches legacy lid_addDrainRunon(): LID drain flow reaching a subcatch is
     // treated as runon inflow to that subcatch for the next runoff step.
-    for (int i = 0; i < ctx_.n_subcatches(); ++i) {
+    for (int i = 0; i < nsc; ++i) {
         auto ui = static_cast(i);
         double q = ctx_.subcatches.lid_drain_runon_cfs[ui];
         if (q > 0.0) {
-            ctx_.subcatches.runon_inflow[ui] += q;
+            add_runon(i, q);
             ctx_.subcatches.lid_drain_runon_cfs[ui] = 0.0;
-        }
-    }
-
-    // Gap #28: outfall runon — drain accumulated volume into runon_inflow (CFS)
-    // and reset the accumulator (matching legacy Outfall[i].vRouted / tStep).
-    if (dt_runoff > 0.0) {
-        for (int i = 0; i < ctx_.n_subcatches(); ++i) {
-            auto ui = static_cast(i);
-            double vol = ctx_.subcatches.outfall_runon_vol[ui];
-            if (vol > 0.0) {
-                ctx_.subcatches.runon_inflow[ui] += vol / dt_runoff;
-                ctx_.subcatches.outfall_runon_vol[ui] = 0.0;
+            auto& wsr = ctx_.water_age_state.subcatch_lid_drain_age_cfs;
+            if (ctx_.options.water_age && ui < wsr.size() &&
+                ui < ctx_.water_age_state.subcatch_runon_age_vol_in.size()) {
+                ctx_.water_age_state.subcatch_runon_age_vol_in[ui] += wsr[ui];
+                wsr[ui] = 0.0;
+            }
+            // H5b: the drain's temperature, booked with its flow.
+            auto& hdr = ctx_.heat_state.subcatch_lid_drain_temp_cfs;
+            if (ctx_.options.heat_transport && ui < hdr.size()) {
+                transport::addRunonTemperatureAt(ctx_, i, q, hdr[ui] / q);
+                hdr[ui] = 0.0;
             }
         }
     }
@@ -5690,6 +9578,7 @@ void SWMMEngine::assembleLateralInflows(double dt_routing) noexcept {
     double sum_gw   = 0.0;
     double sum_rdii = 0.0;
     double sum_ext  = 0.0;
+    double sum_wd   = 0.0;   // withdrawals: negative external inflows (legacy: outflow)
 
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
@@ -5733,6 +9622,41 @@ void SWMMEngine::assembleLateralInflows(double dt_routing) noexcept {
                 ctx_.nodes.coupling_volume[uj] = 0.0;
             }
             ctx_.nodes.coupling_inflow[uj] = q_couple;
+
+            // S3: the 2D→1D species mass queue drains by the SAME rule as the
+            // volume queue above (uniform rate over the remaining span, flushed
+            // when remaining ≤ dt), so the delivered mass/volume ratio is the
+            // cell concentration the marcher booked. Written as a RATE for
+            // QualitySolver::addCouplingLoads (sized [node*np+p]; empty when
+            // the model carries no pollutants).
+            auto drain_queue = [&](double& qm) -> double {
+                double rate = 0.0;
+                if (dt_routing > 0.0 && qm != 0.0) {
+                    if (ctx_.coupling_delivery_remaining > dt_routing) {
+                        rate = qm / ctx_.coupling_delivery_remaining;
+                        qm  -= rate * dt_routing;
+                    } else {
+                        rate = qm / dt_routing;
+                        qm   = 0.0;
+                    }
+                }
+                return rate;
+            };
+            if (!ctx_.nodes.coupling_qual_queue.empty()) {
+                const auto np = static_cast(ctx_.n_pollutants());
+                for (std::size_t p = 0; p < np; ++p) {
+                    const std::size_t idx = uj * np + p;
+                    ctx_.nodes.coupling_qual_inflow[idx] =
+                        drain_queue(ctx_.nodes.coupling_qual_queue[idx]);
+                }
+            }
+            // S4: the age-volume and temperature-volume halves, same rule.
+            if (uj < ctx_.nodes.coupling_age_vol_queue.size())
+                ctx_.nodes.coupling_age_vol_inflow[uj] =
+                    drain_queue(ctx_.nodes.coupling_age_vol_queue[uj]);
+            if (uj < ctx_.nodes.coupling_temp_vol_queue.size())
+                ctx_.nodes.coupling_temp_vol_inflow[uj] =
+                    drain_queue(ctx_.nodes.coupling_temp_vol_queue[uj]);
         }
 
         // PARITY: accumulate in legacy routing_execute source ORDER
@@ -5748,10 +9672,21 @@ void SWMMEngine::assembleLateralInflows(double dt_routing) noexcept {
         sum_dw   += ctx_.nodes.dwf_inflow[uj];
         sum_gw   += ctx_.nodes.gw_inflow[uj];
         sum_rdii += ctx_.nodes.rdii_inflow[uj];
+        // legacy addExternalInflows (routing.c): the node's external flow
+        // joins newLatFlow either way, but a NEGATIVE one (a withdrawal) is
+        // booked as system OUTFLOW (massbal_addOutflowFlow(-q)), not as a
+        // negative external inflow — the epanet-swmm-hazen-williams decks
+        // draw 950 GPM out of a network fed back through a FIXED outfall,
+        // and reported DIRECT_INFLOW 0.9 where legacy reports 950.9 and
+        // OUTFALL_FLOWS 0.9 where legacy reports 950.9.
         // Interface file inflows count as external inflow for continuity
         // (legacy addIfaceInflows → massbal_addInflowFlow(EXTERNAL_INFLOW, q))
-        sum_ext  += ctx_.nodes.ext_inflow[uj]
-                  + ctx_.nodes.iface_inflow[uj];
+        {
+            const double q_ext = ctx_.nodes.ext_inflow[uj];
+            if (q_ext >= 0.0) sum_ext += q_ext;
+            else              sum_wd  += -q_ext;
+        }
+        sum_ext  += ctx_.nodes.iface_inflow[uj];
 
         // 2D → 1D coupling (positive coupling_inflow) folds into the
         // routing_external category for continuity reporting; the negative
@@ -5793,9 +9728,12 @@ void SWMMEngine::assembleLateralInflows(double dt_routing) noexcept {
         }
     }
 
-    // RDII, then iface, then engine-only extensions — legacy source order.
+    // LID drains (legacy addLidDrainInflows, after groundwater), then RDII,
+    // then iface, then engine-only extensions — legacy source order.
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
+        if (uj < lid_drain_q_interp_.size() && lid_drain_q_interp_[uj] != 0.0)
+            ctx_.nodes.lat_flow[uj] += lid_drain_q_interp_[uj];
         ctx_.nodes.lat_flow[uj] += ctx_.nodes.rdii_inflow[uj];
         ctx_.nodes.lat_flow[uj] += ctx_.nodes.iface_inflow[uj];
 
@@ -5821,6 +9759,15 @@ void SWMMEngine::assembleLateralInflows(double dt_routing) noexcept {
     ctx_.mass_balance.step_gw_inflow   = sum_gw;
     ctx_.mass_balance.step_rdii_inflow = sum_rdii;
     ctx_.mass_balance.step_ext_inflow  = sum_ext;
+    ctx_.mass_balance.step_ext_withdrawal = sum_wd;
+
+    // Street inlet capture / backflow: a transfer between the bypass and
+    // capture nodes, applied after every other lateral source is summed and
+    // before the router runs — legacy inlet_findCapturedFlows (routing.c:244,
+    // "called after regular lateral flows to all nodes have been set but
+    // before a flow routing step has been taken"). Not a mass-balance source:
+    // both sides of the transfer stay inside the system.
+    inlet_.computeAll(ctx_, dt_routing);
 }
 
 // ============================================================================
@@ -5851,24 +9798,41 @@ bool SWMMEngine::isBetweenEvents(double current_date) const {
 
 bool SWMMEngine::isInSteadyState(int action_count) const {
     if (!ctx_.options.skip_steady_state) return false;
+    // legacy isInSteadyState (routing.c): never on the first step, never
+    // after a control action, not when the PREVIOUS step's flow error
+    // (massbal_getStepFlowError, its StepFlowTotals) exceeds SysFlowTol —
+    // the cumulative routing_error() it used to test is a different
+    // quantity — and not when an inflow has changed (inflowHasChanged).
+    if (ctx_.old_elapsed_ms == 0.0 && ctx_.elapsed_ms == 0.0) return false;
     if (ctx_.current_time == 0.0) return false;
     if (action_count > 0) return false;
-
-    // Check flow error exceeds tolerance
-    double flow_error = std::abs(ctx_.mass_balance.routing_error());
-    if (flow_error > ctx_.options.sys_flow_tol) return false;
-
-    // Check if any lateral inflow has changed significantly
+    if (std::fabs(ctx_.mass_balance.last_step_flow_error) > ctx_.options.sys_flow_tol)
+        return false;
+
+    // legacy inflowHasChanged: the lateral inflow at every node, and at an
+    // outfall or a node with no outflow links the flow inflow as well —
+    // oldFlowInflow, rolled only by routeFlow, against the inflow the last
+    // routed step left. Without the second test a steady period began a
+    // step early while the outfall's inflow was still changing
+    // (routing-skip-steady).
     constexpr double TINY = 1e-6;
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         auto uj = static_cast(j);
         double qOld = ctx_.nodes.old_lat_flow[uj];
         double qNew = ctx_.nodes.lat_flow[uj];
         double diff;
-        if (std::abs(qOld) > TINY)      diff = (qNew / qOld) - 1.0;
-        else if (std::abs(qNew) > TINY)  diff = 1.0;
+        if (std::fabs(qOld) > TINY)      diff = (qNew / qOld) - 1.0;
+        else if (std::fabs(qNew) > TINY)  diff = 1.0;
         else                              diff = 0.0;
-        if (std::abs(diff) > ctx_.options.lat_flow_tol) return false;
+        if (std::fabs(diff) > ctx_.options.lat_flow_tol) return false;
+        if (ctx_.nodes.type[uj] == NodeType::OUTFALL || ctx_.nodes.degree[uj] == 0) {
+            qOld = ctx_.nodes.old_inflow[uj];
+            qNew = ctx_.nodes.inflow[uj];
+            if (std::fabs(qOld) > TINY)      diff = (qNew / qOld) - 1.0;
+            else if (std::fabs(qNew) > TINY)  diff = 1.0;
+            else                              diff = 0.0;
+            if (std::fabs(diff) > ctx_.options.lat_flow_tol) return false;
+        }
     }
     return true;
 }
@@ -5883,6 +9847,17 @@ double SWMMEngine::reportedNodeVolume(int i, double depth,
     auto ui = static_cast(i);
     if (ctx_.nodes.type[ui] == NodeType::STORAGE)
         return volume;                         // storage curve volume (= legacy)
+    // Kinematic wave / steady flow: legacy setNewNodeState carries a
+    // junction's newVolume as the accumulated net inflow (oldVolume +
+    // net*dt, kept above fullVolume when it ponds, capped at fullVolume
+    // otherwise) and node_getResults reports that number as it is — the
+    // depth is a separate quantity, raised from the conduit ends. The
+    // depth relation below is the dynamic wave's convention. new-mikeurbancn
+    // (KW, ALLOW_PONDING) reported 0 for junction 6032's 7 019 ft3 pond
+    // because the raise caps the depth AT the rim.
+    if (ctx_.options.routing_model == RoutingModel::KINWAVE ||
+        ctx_.options.routing_model == RoutingModel::STEADY)
+        return volume;
     double fd = ctx_.nodes.full_depth[ui];
     if (!(fd > 0.0)) return 0.0;
 
@@ -5900,7 +9875,7 @@ double SWMMEngine::reportedNodeVolume(int i, double depth,
         return volume;
 
     // Legacy convention: a plain junction contributes ZERO to reported
-    // storage, because report_full_volume_ is 0 for it. FV junctions are now
+    // storage, because rpt_full_volume is 0 for it. FV junctions are now
     // algebraic INTERFACES that hold no water of their own — the water at a
     // junction's head stands in the incident cells, already counted through
     // link volumes — so FV shares the convention. (The earlier bucket model
@@ -5910,14 +9885,13 @@ double SWMMEngine::reportedNodeVolume(int i, double depth,
     // junction count — measured −0.005 % per junction on a 120-junction
     // chain, one MIN_SURFAREA·depth per node.)
 
-    return report_full_volume_[ui] * (depth / fd);
+    return ctx_.nodes.rpt_full_volume[ui] * (depth / fd);
 }
 
 void SWMMEngine::initMassBalance() noexcept {
     // 14. Mass balance: record initial storage (nodes + links, matching legacy)
     ctx_.mass_balance.reset();
-    prev_lid_infil_vol_ = 0.0;  // reset per-step LID infil/evap delta trackers
-    prev_lid_evap_vol_  = 0.0;
+    ctx_.negsrc.reset();  // D-NS1 (X6): clamp counters share the lifecycle
     for (int j = 0; j < ctx_.n_nodes(); ++j) {
         // Legacy-convention node volume (junctions => 0) so init storage matches
         // legacy; the internal volume-state is unchanged.
@@ -5928,6 +9902,32 @@ void SWMMEngine::initMassBalance() noexcept {
             ctx_.links.volume[static_cast(j)];
     }
 
+    // Initial stored pollutant mass, from the concentrations initQuality()
+    // seeded out of [POLLUTANTS] Cinit. Legacy: massbal_open() sums
+    // Node[j].newQual[p] * Node[j].newVolume + Link[j].newQual[p] * link volume
+    // into QualTotals[p].initStorage.
+    {
+        const int np = ctx_.n_pollutants();
+        for (int p = 0; p < np; ++p) {
+            const auto up = static_cast(p);
+            if (up >= ctx_.mass_balance.qual_routing_init.size()) break;
+            double m = 0.0;
+            for (int j = 0; j < ctx_.n_nodes(); ++j) {
+                const auto idx = static_cast(j) *
+                                 static_cast(np) + up;
+                if (idx < ctx_.nodes.conc.size())
+                    m += ctx_.nodes.conc[idx] * reportedNodeVolume(j);
+            }
+            for (int j = 0; j < ctx_.n_links(); ++j) {
+                const auto uj  = static_cast(j);
+                const auto idx = uj * static_cast(np) + up;
+                if (idx < ctx_.links.conc.size())
+                    m += ctx_.links.conc[idx] * ctx_.links.volume[uj];
+            }
+            ctx_.mass_balance.qual_routing_init[up] = m;
+        }
+    }
+
     // Record initial runoff storage
     for (int j = 0; j < ctx_.n_subcatches(); ++j) {
         // Initial surface storage approximated from initial depth * area
@@ -5935,9 +9935,14 @@ void SWMMEngine::initMassBalance() noexcept {
         ctx_.mass_balance.runoff_init_store +=
             ctx_.subcatches.ponded_depth[uj] * ctx_.subcatches.area[uj];
     }
-    // Initial LID storage (INITSAT-filled soil/storage layers) — symmetric with
-    // the final-storage LID credit so the runoff continuity balances (#102 C).
-    ctx_.mass_balance.runoff_init_store += lid_.totalInitVolume();
+    // Initial water in LID units (InitSat + wilting-point soil moisture) is
+    // part of runoff storage, mirroring the final-storage accounting.
+    ctx_.mass_balance.runoff_init_store += lid_.storedVolume();
+
+    // F8 — the pack the deck starts with is water the model was GIVEN, and
+    // the ledger had no row for it. Legacy massbal.c:124-129.
+    ctx_.mass_balance.runoff_init_snow =
+        snowCoverVolumeFt3(ctx_, snow_.state());
 
     // Record initial groundwater storage
     // Legacy: GwaterTotals.initStorage += gwater_getVolume(j) * Subcatch[j].area
@@ -5949,7 +9954,7 @@ void SWMMEngine::initMassBalance() noexcept {
             if (gw.total_depth[ui] <= 0.0) continue;
             double upper_d = gw.total_depth[ui] - gw.lower_depth[ui];
             double vol = gw.theta[ui] * upper_d + gw.porosity[ui] * gw.lower_depth[ui];
-            double area = ctx_.subcatches.area[ui] * ucf::ACRES_TO_FT2;
+            double area = ctx_.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx_.options);
             ctx_.mass_balance.gw_init_storage += vol * area;
         }
     }
diff --git a/src/engine/core/SWMMEngine.hpp b/src/engine/core/SWMMEngine.hpp
index e573c9e4e..7835dec7a 100644
--- a/src/engine/core/SWMMEngine.hpp
+++ b/src/engine/core/SWMMEngine.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SWMMEngine.hpp
  * @brief Lifecycle manager for the new openswmm.engine.
@@ -30,7 +46,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SWMM_ENGINE_HPP
@@ -52,6 +68,8 @@
 #include "../hydrology/RunoffInterface.hpp"
 #include "../hydrology/RdiiInterface.hpp"
 #include "../quality/QualityRouting.hpp"
+#include "../quality/lard/LagrangianSolver.hpp"
+#include "../transport/components/EulerianArdComponent/ArdEngine.hpp"
 #include "../quality/Landuse.hpp"
 #include "../controls/Controls.hpp"
 #include "../hydraulics/Exfiltration.hpp"
@@ -201,6 +219,11 @@ class SWMMEngine {
     SimulationContext&       context()       noexcept { return ctx_; }
     const SimulationContext& context() const noexcept { return ctx_; }
 
+    /// A4: LID solver access. The per-layer age block is keyed on a FLAT unit
+    /// index while the units themselves live in per-type groups, so anything
+    /// reading that block needs the manager to resolve the two.
+    const lid::LIDSolver& lid() const noexcept { return lid_; }
+
     /// Groundwater solver access (for C API state injection).
     groundwater::GWSolver&       gwSolver()       noexcept { return groundwater_; }
     const groundwater::GWSolver& gwSolver() const noexcept { return groundwater_; }
@@ -337,6 +360,9 @@ class SWMMEngine {
      */
     void set_lenient_open(bool on) noexcept { lenient_open_ = on; }
 
+    /// BW-MSX gate access: the pollutant surface-quality store (read-only).
+    const landuse::SurfaceQualitySoA& surfaceQuality() const noexcept { return surface_quality_; }
+
 #ifdef OPENSWMM_HAS_2D
     /** @brief Access the 2D surface router (for C API delegation). */
     twoD::SurfaceRouter2D&       surfaceRouter2D()       noexcept { return surface_router_; }
@@ -351,6 +377,7 @@ class SWMMEngine {
 
     SimulationContext      ctx_;        ///< All simulation data (SoA + options)
     bool                   lenient_open_ = false;  ///< permissive open (see setter)
+    bool                   plugins_prepare_attempted_ = false;  ///< start() reached prepare_all (report file may be open)
     PluginFactory          plugins_;   ///< Phase 4: plugin loader + lifecycle
     IOThread               io_thread_; ///< Phase 5: writer thread
 
@@ -359,9 +386,13 @@ class SWMMEngine {
     runoff::RunoffSolver         runoff_;       ///< Subcatchment runoff (batch nonlinear reservoir)
     climate::ClimateFileReader   climate_file_; ///< Climate file reader (temp/evap/wind from file)
     snow::SnowSolver             snow_;         ///< Snowmelt (batch over subcatch×subareas)
+    int                          last_melt_doy_ = -1;  ///< Day the seasonal melt coeffs were last set (legacy climate.c LastDay)
     groundwater::GWSolver        groundwater_;  ///< Groundwater (batch ODE per subcatchment)
     lid::LIDSolver               lid_;          ///< LID (batch by type group)
     quality::QualitySolver       quality_;      ///< Quality routing (batch link-load + mixing)
+    transport::ArdEngine         ard_;          ///< QUALITY_SOLVER EULERIAN_ARD engine (phase E1)
+    bool                         ard_init_attempted_ = false;  ///< lazy init after Router::init
+    lard::LagrangianSolver       lard_;         ///< QUALITY_SOLVER LAGRANGIAN (X1 skeleton — no-op)
     landuse::LanduseSolver       landuse_solver_; ///< Buildup/washoff computation
     landuse::SurfaceQualitySoA   surface_quality_; ///< Per-subcatch surface quality state
     controls::ControlEngine      controls_;     ///< Control rule evaluation
@@ -369,9 +400,15 @@ class SWMMEngine {
     rdii::RDIISolver             rdii_;         ///< RDII (unit hydrograph convolution)
     exfil::ExfilSolver           exfil_;        ///< Storage node exfiltration
     inlet::InletSolver           inlet_;        ///< Street inlet capture
-    std::vector             culvert_links_;///< Pre-built culvert link indices (avoid per-timestep alloc)
     std::vector          gw_frac_perv_; ///< Per-subcatch pervious fraction for GW evap
     std::vector          gw_perv_evap_; ///< Per-subcatch pervious evap rate (ft/sec)
+    /// U3 (track I-b, 2026-09-07): the 2D surface's per-subcatchment
+    /// infiltration recharge, drained from SurfaceRouter2D once per runoff
+    /// step (m³) and converted to the ft/sec-over-full-area rate the GW
+    /// solver's `infil_rate` argument expects.
+    std::vector          gw_2d_recharge_vol_;
+    std::vector          gw_infil_with_2d_;
+    std::vector          gw_infil_rate_;      ///< (Vinfil + VlidInfil) / area / dt, legacy's `infil` (ft/s)
     std::vector          snow_rain_;    ///< Per-subcatch rainfall into snow step (ft/sec)
     std::vector          snow_snow_;    ///< Per-subcatch snowfall into snow step (ft/sec)
     hydstruct::StructureSolver  hydstruct_;    ///< Pumps, orifices, weirs, outlets
@@ -393,12 +430,17 @@ class SWMMEngine {
 
     // Event and steady-state tracking
     int next_event_ = 0;                        ///< Index of next event in ctx_.events
+    bool between_events_ = false;               ///< legacy BetweenEvents, as the last stepRouting evaluated it
     bool isBetweenEvents(double current_date) const; ///< Check if between routing events
     bool isInSteadyState(int action_count) const;    ///< Check if system is in steady state
     std::vector gage_states_;  ///< Per-gage state (SoA)
 
 #ifdef OPENSWMM_HAS_2D
     twoD::SurfaceRouter2D        surface_router_; ///< Optional 2D surface routing solver
+    /// S4b: per-row unit labels for the 2D species snapshot (pollutant units,
+    /// MSX units, "hours", "degC"), rebuilt by fillSurfaceSnapshot() and
+    /// pointed to by SimulationSnapshot::surface_species_units.
+    mutable std::vector surface_species_units_;
     /// Non-owning pointer to the 2D HDF5 output plugin (lifetime owned by
     /// PluginFactory's output_plugins_). Set in open() when [2D_OPTIONS]
     /// OUTPUT_FILE is configured; used in start() to call prepareMeshAndDatasets
@@ -428,7 +470,9 @@ class SWMMEngine {
     // (routing.c:703) and the report-instant runoff weight (output.c) must be
     // formed from MILLISECOND quantities to round identically to legacy.
     double old_runoff_ms_ = 0.0;    ///< legacy OldRunoffTime (msec)
+    double prev_runoff_step_sec_ = 0.0;  ///< span of the runoff step just completed (legacy oldRunoffStep)
     double new_runoff_ms_ = 0.0;    ///< legacy NewRunoffTime (msec)
+    double new_rule_time_ms_ = 0.0; ///< legacy NewRuleTime (msec, routing.c:58)
 
     // Previous cumulative LID exfiltration / evaporation volumes (ft³), so the
     // per-step delta can be folded into the runoff-continuity infil / evap
@@ -442,9 +486,23 @@ class SWMMEngine {
     // ext, dwf, then PER-SUBCATCHMENT wet-weather q (routing.c:716), then GW,
     // RDII, iface into Node.newLatFlow. Pre-summing per node and adding in a
     // different source order rounds differently (1-ULP lat-flow drift).
-    std::vector wet_q_interp_;  ///< per-subcatch interpolated runoff+runon (cfs)
+    std::vector wet_q_interp_;  ///< per-subcatch interpolated runoff (cfs; NOT runon — it is already inside runoff[])
+    std::vector lid_drain_q_interp_; ///< per-node interpolated LID drain inflow this routing step (cfs; legacy lid_addDrainInflow)
     std::vector gw_q_interp_;   ///< per-subcatch interpolated GW flow (cfs)
     std::vector    gw_q_node_;     ///< receiving node for gw_q_interp_ (-1 = skip)
+    // Legacy lid_getRunoff volume accumulators, per subcatchment per runoff
+    // step: VlidIn (= sum over units of (captured/area)*area*tStep, ft3) and
+    // qRunoff (= sum of unit surface outflow*area, cfs; *tStep = VlidOut).
+    // subcatch.c:746-751 rebuilds newRunoff from these in the VOLUME domain;
+    // adjusting the runoff RATE incrementally instead rounds differently
+    // (1-ULP runoff drift on every LID deck).
+    std::vector lid_vlidin_vol_;  ///< per-subcatch VlidIn this runoff step (ft3)
+    std::vector lid_qsurf_cfs_;   ///< per-subcatch LID surface outflow to outlet (cfs)
+    /// Previous runoff step's GW flow RATE per subcatch (ft/s per unit area,
+    /// legacy TGroundwater::oldFlow). Legacy interpolates the RATE and
+    /// multiplies by the area afterwards (routing.c:766, subcatch.c:912);
+    /// interpolating the cfs product instead is a 1-ULP different number.
+    std::vector old_gw_rate_;
 
     // Persistent runoff-state flags read by computeRunoffTimestep() on the NEXT
     // runoff step (one-step lag), matching legacy globals HasRunoff/HasSnow in
@@ -469,54 +527,59 @@ class SWMMEngine {
     // -----------------------------------------------------------------------
     // When rpt_averages is true, node and link results are accumulated over
     // each routing step and averaged at report boundaries.  Subcatchment
-    // results are always point-in-time (matching legacy).
+    // results are always interpolated point values (matching legacy).
+    // PARITY: the accumulators are float32 DISPLAY-unit sums — legacy's xAvg
+    // slots are REAL4 fed by node_getResults/link_getResults at f = 1.0
+    // (output.c:72, 853-901), so the whole accumulate/divide chain is float
+    // arithmetic on display values. Accumulating doubles (or internal units)
+    // diverges by ~1e-5 rel over a report period.
     struct AvgAccumulator {
         // Node accumulators (6 variables per node)
-        std::vector node_depth;
-        std::vector node_head;
-        std::vector node_volume;
-        std::vector node_lat_inflow;
-        std::vector node_total_inflow;
-        std::vector node_overflow;
+        std::vector node_depth;
+        std::vector node_head;
+        std::vector node_volume;
+        std::vector node_lat_inflow;
+        std::vector node_total_inflow;
+        std::vector node_overflow;
 
         // Link accumulators (5 variables per link)
-        std::vector link_flow;
-        std::vector link_depth;
-        std::vector link_velocity;
-        std::vector link_volume;
-        std::vector link_capacity;
+        std::vector link_flow;
+        std::vector link_depth;
+        std::vector link_velocity;
+        std::vector link_volume;
+        std::vector link_capacity;
 
         int n_steps = 0;  ///< Number of routing steps accumulated
 
         void resize(int n_nodes, int n_links) {
             auto un = static_cast(n_nodes);
             auto ul = static_cast(n_links);
-            node_depth.assign(un, 0.0);
-            node_head.assign(un, 0.0);
-            node_volume.assign(un, 0.0);
-            node_lat_inflow.assign(un, 0.0);
-            node_total_inflow.assign(un, 0.0);
-            node_overflow.assign(un, 0.0);
-            link_flow.assign(ul, 0.0);
-            link_depth.assign(ul, 0.0);
-            link_velocity.assign(ul, 0.0);
-            link_volume.assign(ul, 0.0);
-            link_capacity.assign(ul, 0.0);
+            node_depth.assign(un, 0.0f);
+            node_head.assign(un, 0.0f);
+            node_volume.assign(un, 0.0f);
+            node_lat_inflow.assign(un, 0.0f);
+            node_total_inflow.assign(un, 0.0f);
+            node_overflow.assign(un, 0.0f);
+            link_flow.assign(ul, 0.0f);
+            link_depth.assign(ul, 0.0f);
+            link_velocity.assign(ul, 0.0f);
+            link_volume.assign(ul, 0.0f);
+            link_capacity.assign(ul, 0.0f);
             n_steps = 0;
         }
 
         void reset() {
-            std::fill(node_depth.begin(), node_depth.end(), 0.0);
-            std::fill(node_head.begin(), node_head.end(), 0.0);
-            std::fill(node_volume.begin(), node_volume.end(), 0.0);
-            std::fill(node_lat_inflow.begin(), node_lat_inflow.end(), 0.0);
-            std::fill(node_total_inflow.begin(), node_total_inflow.end(), 0.0);
-            std::fill(node_overflow.begin(), node_overflow.end(), 0.0);
-            std::fill(link_flow.begin(), link_flow.end(), 0.0);
-            std::fill(link_depth.begin(), link_depth.end(), 0.0);
-            std::fill(link_velocity.begin(), link_velocity.end(), 0.0);
-            std::fill(link_volume.begin(), link_volume.end(), 0.0);
-            std::fill(link_capacity.begin(), link_capacity.end(), 0.0);
+            std::fill(node_depth.begin(), node_depth.end(), 0.0f);
+            std::fill(node_head.begin(), node_head.end(), 0.0f);
+            std::fill(node_volume.begin(), node_volume.end(), 0.0f);
+            std::fill(node_lat_inflow.begin(), node_lat_inflow.end(), 0.0f);
+            std::fill(node_total_inflow.begin(), node_total_inflow.end(), 0.0f);
+            std::fill(node_overflow.begin(), node_overflow.end(), 0.0f);
+            std::fill(link_flow.begin(), link_flow.end(), 0.0f);
+            std::fill(link_depth.begin(), link_depth.end(), 0.0f);
+            std::fill(link_velocity.begin(), link_velocity.end(), 0.0f);
+            std::fill(link_volume.begin(), link_volume.end(), 0.0f);
+            std::fill(link_capacity.begin(), link_capacity.end(), 0.0f);
             n_steps = 0;
         }
     };
@@ -539,17 +602,10 @@ class SWMMEngine {
     /** @brief Rebuild xsp_cache_ if links/xsect state changed (cheap check). */
     void ensureXspCache() noexcept;
 
-    /// Legacy-convention full volume per node for .out NODE_VOLUME reporting:
-    /// 0 for plain junctions/outfalls/dividers (legacy node_getVolume returns 0
-    /// when fullVolume==0), pump wet-well xMax for Type-1 pump inlets. STORAGE
-    /// reports its curve volume directly. This DECOUPLES the reported node volume
-    /// from the internal volume-state (which keeps MIN_SURFAREA*depth for the
-    /// volume-based solver + surcharge detection). See postOutputSnapshot().
-    std::vector report_full_volume_;
 
     /// Legacy-convention reported node volume (mirrors legacy node_getVolume):
     /// STORAGE → curve volume (ctx_.nodes.volume); junction/outfall/divider →
-    /// report_full_volume_·(depth/fullDepth) = 0 for plain junctions. Used for
+    /// nodes.rpt_full_volume·(depth/fullDepth) = 0 for plain junctions. Used for
     /// the .out NODE_VOLUME and the routing mass-balance storage sums so both
     /// match legacy, while the internal volume-state (MIN_SURFAREA) is preserved.
     double reportedNodeVolume(int i) const noexcept;
@@ -612,6 +668,7 @@ class SWMMEngine {
      * @param has_snow     True if any subcatchment has snow depth > 0.
      * @returns Runoff timestep in seconds.
      */
+    void setNextEvapDate(double the_date) noexcept;   ///< legacy climate.c setNextEvapDate
     double computeRunoffTimestep(double abs_time, bool is_raining,
                                  bool has_runoff, bool has_snow) noexcept;
 
@@ -629,6 +686,10 @@ class SWMMEngine {
      */
     void stepSurfaceQuality(double dt_runoff) noexcept;
 
+    /// Book the washoff mass against the POST-LID volumes (legacy
+    /// surfqual_getWashoff's three bookings), after the units have run.
+    void bookWashoffLoads(double dt_runoff) noexcept;
+
     /**
      * @brief Execute groundwater computation for one substep.
      *
@@ -645,9 +706,11 @@ class SWMMEngine {
      *
      * @param dt_routing  Routing timestep (seconds).
      */
-    /** @brief Assemble subcatch-to-subcatch and outfall runon into subcatches.runon_inflow[].
-     *  @param dt_runoff  Runoff timestep (sec) — used to convert outfall_runon_vol to CFS. */
-    void assembleRunon(double dt_runoff) noexcept;
+    /** @brief Assemble the run-on for the runoff step about to be taken —
+     *  outfall return (over the previous step's span), upstream runoff and
+     *  LID drains — into subcatches.runon_rate[] (ft/s, legacy Subcatch.runon)
+     *  and runon_inflow[] (CFS). Legacy runoff.c:247-253 order. */
+    void assembleRunon() noexcept;
 
     /** @brief Pre-compute GW surface water head and available node flow from routing state. */
     void assembleGWCoupling(double dt_runoff) noexcept;
@@ -745,6 +808,11 @@ class SWMMEngine {
      * @details Matches legacy behavior where a failed swmm_open still leaves a
      *          .rpt with the ERROR/WARNING lines. No-op if no report path is set.
      */
+    /*! Stop a routing solve that has gone non-physical (non-finite or absurd
+     *  head/flow) instead of letting it run on and write NaN into the report.
+     *  Returns SWMM_OK when the state is sane. */
+    [[nodiscard]] int checkRoutingDiverged() noexcept;
+
     void write_open_failure_report() noexcept;
 
     /** @brief Set a fatal error on the context and transition to ERROR_STATE. */
diff --git a/src/engine/core/SimulationContext.hpp b/src/engine/core/SimulationContext.hpp
index c88c7dafd..aeb4ebcce 100644
--- a/src/engine/core/SimulationContext.hpp
+++ b/src/engine/core/SimulationContext.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SimulationContext.hpp
  * @brief The central, reentrant simulation context for the new engine.
@@ -54,28 +70,37 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SIMULATION_CONTEXT_HPP
 #define OPENSWMM_ENGINE_SIMULATION_CONTEXT_HPP
 
 #include 
+#include 
 #include 
 #include "FilePathPair.hpp"
+#include "../data/ArdConfigData.hpp"
+#include "../data/BedZoneData.hpp"
 #include "../data/GageData.hpp"
+#include "../data/HeatData.hpp"
+#include "../data/WaterAgeData.hpp"
+#include "../data/LidLayerSpeciesData.hpp"
 #include "../data/LinkData.hpp"
 #include "../data/NameIndex.hpp"
 #include "../data/NodeData.hpp"
 #include "../data/NodeSubtypes.hpp"
 #include "../data/LinkSubtypes.hpp"
 #include "../data/PollutantData.hpp"
+#include "../data/ReactionData.hpp"
+#include "../data/SpeciesRegistry.hpp"
 #include "../data/SubcatchData.hpp"
 #include "../data/TableData.hpp"
 #include "SimulationOptions.hpp"
 #include "SpatialFrame.hpp"
 #include "UserFlags.hpp"
 #include "../data/QualityData.hpp"
+#include "../data/InitialQualityData.hpp"
 #include "../data/InflowData.hpp"
 #include "../data/InfraData.hpp"
 #include "../hydraulics/Transect.hpp"
@@ -109,6 +134,35 @@ struct PluginSpec {
     std::vector init_args;  ///< Extra tokens from the [PLUGINS] row
 };
 
+// ============================================================================
+// [PROCESS_COMPONENTS] section spec — process-component registrations
+// ============================================================================
+
+/**
+ * @brief One row of [PROCESS_COMPONENTS] (Unified Transport suite, D-UT8).
+ *
+ * @details `id` is a registered component id
+ *          (e.g. `org.hydrocouple.openswmm.reactions`) or — reserved for the
+ *          HC2 phase — a shared-library path exporting
+ *          `hydrocouple_component_info()`. `config_path` is the component's
+ *          external configuration file (the `config="…"` argument), resolved
+ *          relative to the parent .inp per the [2D_MESH_FILE] rules. `args`
+ *          holds any further key="value" pairs verbatim.
+ *
+ * @see plans/transport/TRANSPORT_IO_PLUGIN_CONFIG_PLAN.md §2
+ */
+struct ProcessComponentSpec {
+    std::string id;           ///< Component id (or library path — HC2)
+    std::string config_path;  ///< config="…" argument (may be empty)
+    std::vector> args;  ///< other key/value args
+
+    /// Effective path the config was READ from (set by
+    /// resolve_process_components; empty until then). IO3 uses it to copy
+    /// the config file alongside a save-as so relative references never
+    /// dangle in the destination directory.
+    std::string resolved_config_path;
+};
+
 // ============================================================================
 // [FILES] section spec — secondary file references
 // ============================================================================
@@ -274,8 +328,16 @@ namespace twoD {
 struct MeshData;
 struct SolverOptions2D;
 struct BoundaryData;
+class  Infil2D;
 struct PendingBoundaryRow;
 struct PendingEdgeConveyanceRow;
+struct PendingInitialQualityRow;
+struct PendingBoundaryQualityRow;
+struct GwTransportData;
+class SurfaceQuality2D;   // S7 (2026-09-19)
+struct SubsurfaceConfig;  // G1: the [2D_AQUIFER*] rows
+struct SubsurfaceState;   // G1: the running two-zone kernel state
+struct SubsurfaceTransportState;   // T7.5: and what is dissolved in it
 } // namespace twoD
 
 // ============================================================================
@@ -299,6 +361,19 @@ struct SimulationContext {
     /** @brief Current lifecycle state of the engine. */
     EngineState state = EngineState::CREATED;
 
+    /**
+     * @brief Wall-clock time stamped at the start of SWMMEngine::open().
+     *
+     * @details Reported as "Analysis begun on:" and used as the origin for
+     *          "Total elapsed time:" in the .rpt. Stamped before input
+     *          parsing so that parse + cross-reference resolution +
+     *          validation + module initialization are all included in the
+     *          reported elapsed time. This matches legacy, which takes its
+     *          timestamp in report_writeLogo() before project_readInput()
+     *          (see legacy/engine/report.c). Zero until open() runs.
+     */
+    std::time_t wall_start = 0;
+
     // =========================================================================
     // Project title / notes
     // =========================================================================
@@ -404,6 +479,19 @@ struct SimulationContext {
      */
     double next_report_ms = 0.0;
 
+    /**
+     * @brief Where this routing instant falls between the two runoff times.
+     * @details Legacy's `f = (routingTime - OldRunoffTime) /
+     *          (NewRunoffTime - OldRunoffTime)`, clamped to [0,1]
+     *          (routing.c:707). It weights EVERY subcatchment quantity handed
+     *          to a node this step — the runoff flow in
+     *          addWetWeatherInflows, and the washoff load right beside it in
+     *          surfqual_getWtdWashoff. SWMMEngine::assembleLateralInflows
+     *          forms it and publishes it here so the quality loaders use the
+     *          same number rather than assuming a midpoint.
+     */
+    double runoff_interp_f = 1.0;
+
     /**
      * @brief Time remaining until the next control rule event (seconds).
      *
@@ -465,6 +553,90 @@ struct SimulationContext {
      */
     PollutantData pollutants;
 
+    /**
+     * @brief Species registry — the single source of truth for transported
+     *        constituents (master plan §4.1, phase T0a). Pollutants occupy
+     *        the first slots (index-aligned with the legacy pollutant
+     *        index); MSX species append via the reactions component (R1);
+     *        reserved age/temperature species append with phases A1/H1.
+     *        Rebuilt at each open().
+     */
+    SpeciesRegistry species_registry;
+
+    /**
+     * @brief Multispecies reaction system (EPANET-MSX conventions), parsed
+     *        from the reactions component's config file or embedded
+     *        [REACTION_*] sections (phase R1). Compiled bytecode arrives
+     *        with phase R2.
+     */
+    ReactionData reactions;
+
+    /**
+     * @brief Eulerian ARD transport component configuration, parsed from the
+     *        `model.ard` config file registered via [PROCESS_COMPONENTS]
+     *        (phase E3: the dispersion subset — global mode + per-conduit
+     *        overrides). @see data/ArdConfigData.hpp.
+     */
+    ArdConfigData ard_config;
+
+    /**
+     * @brief Water-age tracking (phase A1a): per-source initial ages parsed
+     *        from the waterage component (`model.age`) + the runtime age
+     *        state the engines and loaders share. @see data/WaterAgeData.hpp.
+     */
+    WaterAgeConfigData water_age_config;
+    WaterAgeState      water_age_state;
+
+    /**
+     * @brief A4: per-(LID unit, layer, species) transported state.
+     * @see data/LidLayerSpeciesData.hpp — generic over species so H5's
+     *      temperature is a row rather than a second array.
+     */
+    LidLayerSpeciesState lid_layer_state;
+
+    /**
+     * @brief Heat transport (phase H1): per-source inlet temperatures parsed
+     *        from the heat component (`model.heat`) + the runtime
+     *        temperature state the engines and loaders share.
+     *        @see data/HeatData.hpp.
+     */
+    HeatConfigData heat_config;
+    HeatState      heat_state;
+
+    /**
+     * @brief The bed / hyporheic transient-storage zone (phase H6b).
+     *
+     * @details One entry per LINK, carrying a temperature and a per-species
+     *          concentration. It sits beside `heat_state` rather than inside
+     *          it because it holds solute state too — the reference's HTS
+     *          zone is a transient-storage zone for tracers as much as a
+     *          thermal mass. Empty and untouched unless `[HEAT_FLUXES]
+     *          SEDIMENT_EXCHANGE` is on. @see data/BedZoneData.hpp.
+     */
+    BedZoneState bed_state;
+
+    /**
+     * @brief Species names as REPORTED (phase A2b): the pollutant names,
+     *        then `__WATER_AGE__` when `[OPTIONS] WATER_AGE` is on.
+     *
+     * @details The `.out` format has exactly one per-species column block,
+     *          so age reports as a trailing pseudo-pollutant column. This
+     *          vector is the single naming truth the output writers and the
+     *          snapshot's `pollut_names` pointer share — built once at open
+     *          so the pointer stays valid for the run. `n_reported_species()`
+     *          is its length and is what the writers must stride by; plain
+     *          `n_pollutants()` remains the TRANSPORT stride for
+     *          `nodes.conc` etc. Keeping the two counts distinct and named
+     *          is deliberate: conflating them is the stride-slip family
+     *          (roadmap lessons 14/15).
+     */
+    std::vector reported_species_names;
+
+    /// Length of reported_species_names (pollutants + age when enabled).
+    int n_reported_species() const noexcept {
+        return static_cast(reported_species_names.size());
+    }
+
     /**
      * @brief All time series and rating curves.
      * @see Legacy: Tseries[], Curve[] in globals.h + TTable in objects.h
@@ -521,6 +693,15 @@ struct SimulationContext {
     WashoffData      washoff;
     TreatmentData    treatment;
 
+    /**
+     * @brief Per-element initial quality rows from [INITIAL_QUALITY].
+     * @details Pollutant + reserved-species (__WATER_AGE__/__TEMPERATURE__)
+     *          per-node/per-link initial values overriding the global
+     *          [POLLUTANTS] Cinit / sidecar INITIAL_STATE seeds. Names are
+     *          resolved and constituents classified in PostParseResolver.
+     */
+    InitialQualityData initial_quality;
+
     // =========================================================================
     // Inflow data (external, DWF, RDII, patterns)
     // =========================================================================
@@ -585,7 +766,7 @@ struct SimulationContext {
      * @see Legacy: Adjust struct (temp[], evap[], rain[], hydcon[])
      */
     double adjust_temp[12]   = {0,0,0,0,0,0,0,0,0,0,0,0};
-    double adjust_evap[12]   = {1,1,1,1,1,1,1,1,1,1,1,1};
+    double adjust_evap[12]   = {0,0,0,0,0,0,0,0,0,0,0,0};   ///< [ADJUSTMENTS] EVAP: ADDED to the evaporation rate (in/day or mm/day), legacy Adjust.evap
     double adjust_rain[12]   = {1,1,1,1,1,1,1,1,1,1,1,1};
     double adjust_hydcon[12] = {1,1,1,1,1,1,1,1,1,1,1,1};
 
@@ -615,6 +796,24 @@ struct SimulationContext {
     NameIndex        lid_names;
     LidUsageStore    lid_usage;
 
+    // =========================================================================
+    // Transient deferred-resolution capture lists (input loading only)
+    // =========================================================================
+    // Sections whose referenced objects may be defined later in the .inp store
+    // the raw name here so PostParseResolver can re-resolve after every section
+    // has been parsed. Cleared by the resolver; empty outside input loading, so
+    // they can never desync with the editing APIs.
+
+    /// [GROUNDWATER] receiving-node names (subcatch index -> node name).
+    /// [GROUNDWATER] normally precedes [JUNCTIONS] in EPA SWMM output.
+    std::vector> pending_gw_nodes;
+
+    /// Link end-node names (link index -> {from-node name, to-node name}).
+    /// Legacy parsing is order-independent, so [CONDUITS] may precede the node
+    /// sections; without this the link loads silently orphaned (node1/node2 -1).
+    std::vector>>
+        pending_link_nodes;
+
     // =========================================================================
     // Spatial data
     // =========================================================================
@@ -670,6 +869,25 @@ struct SimulationContext {
      */
     std::vector plugin_specs;
 
+    /**
+     * @brief Process-component registrations parsed from [PROCESS_COMPONENTS].
+     * @details Resolved against the ProcessComponentRegistry during open()
+     *          (after the input read, mirroring the external 2D mesh file);
+     *          each resolved component's config file is parsed and delivered
+     *          to its apply hook. Unified Transport suite D-UT8.
+     */
+    std::vector process_component_specs;
+
+    /**
+     * @brief Embedded component sections found in the legacy .inp
+     *        ([REACTION_*] today; other component families as they land) —
+     *        the D-UT8 embedded-fallback path. (tag, lines) pairs in file
+     *        order; consumed after component resolution with a style
+     *        warning, or reported ignored when the external file wins.
+     */
+    std::vector>>
+        embedded_component_sections;
+
     /**
      * @brief Secondary file references parsed from [FILES].
      * @details Mirrors legacy SWMM5's TFile struct array — rainfall,
@@ -716,6 +934,45 @@ struct SimulationContext {
         twoD::BoundaryData*                          boundary   = nullptr;
         std::vector*       pending_bc = nullptr;
         std::vector* pending_ec = nullptr;
+        /// S2/S3: authored [2D_INITIAL_QUALITY] / [2D_BOUNDARY_QUALITY] rows,
+        /// retained after initialize() so the InpWriter can round-trip them.
+        std::vector*  pending_iq = nullptr;
+        std::vector* pending_bq = nullptr;
+        /// Per-cell infiltration (track I, plan §5.5). Owned by
+        /// SurfaceRouter2D; the [2D_INFILTRATION*] section handlers populate
+        /// its defaults()/overrides()/options() and the InpWriter reads them
+        /// back. Null when the engine was built without 2D support.
+        twoD::Infil2D*                               infil      = nullptr;
+        /// U4 (2026-09-07): the `[GW_*]` subsurface-transport authoring rows.
+        /// Owned by SurfaceRouter2D like `infil`; null without 2D support.
+        /// Authoring-only until the integrated groundwater kernel lands —
+        /// see GwTransportData.hpp.
+        twoD::GwTransportData*                       gw         = nullptr;
+        /// S7 (2026-09-19): the `[2D_COVERAGES]` / `[2D_LOADINGS]` /
+        /// `[2D_CURB_LENGTH]` rows and the cell buildup store. Owned by
+        /// SurfaceRouter2D like `gw`; null without 2D support.
+        twoD::SurfaceQuality2D*                      surface_quality = nullptr;
+        /// G1: the `[2D_AQUIFER*]` rows, in the user's OWN units. Owned by
+        /// SurfaceRouter2D; the section handlers fill it and the InpWriter
+        /// echoes it back verbatim. The SI values live only in the kernel's
+        /// state — see SubsurfaceSections.hpp's GwUnitFactors note.
+        twoD::SubsurfaceConfig*                      aquifer    = nullptr;
+        /// The `[2D_AQUIFER_NODE]` node NAMES, parallel to
+        /// `aquifer->node_beds`, kept so the writer can round-trip names it
+        /// resolved to indices.
+        std::vector*                    aquifer_nodes = nullptr;
+        /// G-X4: the `[2D_AQUIFER_LINKS]` row names, parallel to
+        /// `aquifer->link_rows` — the writer's round-trip key.
+        std::vector*                    aquifer_links = nullptr;
+        /// G1: the RUNNING kernel state (SI), or null when no `[2D_AQUIFER]`
+        /// resolved. Published so the hotstart can carry a water table
+        /// across a restart without HotStartManager needing to know about
+        /// the 2D module's solver — an aquifer restarted dry has lost the
+        /// months of memory that were the reason to model it.
+        twoD::SubsurfaceState*                       aquifer_state = nullptr;
+        /// T7.5: the aquifer's transported tuple, for the hotstart block,
+        /// the results writer and the `.rpt` quality continuity.
+        twoD::SubsurfaceTransportState*              aquifer_transport = nullptr;
     } twod_io;
 
     /**
@@ -818,20 +1075,59 @@ struct SimulationContext {
     struct MassBalance {
         // Runoff totals
         double runoff_rainfall   = 0.0;  ///< Total rainfall volume (ft3)
+        double runoff_runon      = 0.0;  ///< Outfall-routed runon volume (ft3), legacy RUNOFF_RUNON
         double runoff_evap       = 0.0;  ///< Total evaporation volume (ft3)
         double runoff_infil      = 0.0;  ///< Total infiltration volume (ft3)
         double runoff_runoff     = 0.0;  ///< Total surface runoff volume (ft3)
+        double runoff_lid_drain  = 0.0;  ///< LID drain-to-node outflow (ft3), legacy RUNOFF_DRAINS / VlidDrain
         double runoff_snowremov  = 0.0;  ///< Total snow removal volume (ft3)
         double runoff_init_store = 0.0;  ///< Initial surface storage (ft3)
         double runoff_final_store= 0.0;  ///< Final surface storage (ft3)
+        /// Snow water equivalent PLUS free water held in every pack at the
+        /// start of the run (ft3). Legacy `RunoffTotals.initSnowCover`,
+        /// summed from `snow_getSnowCover` (`snow.c:587`).
+        double runoff_init_snow  = 0.0;
+        /// The same quantity at the end of the run (ft3). Legacy
+        /// `RunoffTotals.finalSnowCover`.
+        ///
+        /// **These two, and `runoff_snowremov`, were the whole of F8.** The
+        /// ledger had no snow terms at all, so on any deck with a
+        /// `[SNOWPACKS]` section the starting pack was unaccounted INPUT and
+        /// the surviving pack unaccounted OUTPUT, and the printed continuity
+        /// percentage was not a meaningful number. Measured on the snow
+        /// parity deck: **-8.193 % before, +1.419 % after.**
+        double runoff_final_snow = 0.0;
 
         // Routing totals
         double routing_dry_weather   = 0.0;
         double routing_wet_weather   = 0.0;
         double routing_gw_inflow     = 0.0;
+        /// G-X4 (2026-09-20): water the two-zone `[2D_AQUIFER]` handed to
+        /// conduits running below the water table (ft³, ≥ 0) — a gaining
+        /// reach, the inflow term legacy SWMM has no conduit source for.
+        /// It is the negative half of `seep_loss_rate`; the positive half
+        /// stays `routing_seep_loss`, so the two never net each other out
+        /// and a deck can report both in the same run.
+        double routing_link_gw_inflow = 0.0;
         double routing_rdii          = 0.0;
         double routing_external      = 0.0;
         double routing_flooding      = 0.0;
+        /// C2 (2026-09-07): cumulative water the 1D→2D coupling spill removed
+        /// from coupled nodes (ft³). It used to be folded into
+        /// `routing_flooding`, which reported a coupling TRANSFER under
+        /// "Flooding Loss" — the water did not flood, it went to the 2D
+        /// surface, where `MassBalance2D::coupling_1d_to_2d_in` books it
+        /// arriving. Both ledgers are individually right; only the 1D report
+        /// row was misleading, and a modeller reading it saw flooding they
+        /// did not have.
+        ///
+        /// It remains an OUTFLOW of the 1D system, so `routing_error()`
+        /// counts it exactly as before — this change moves a number between
+        /// report rows, it does not move water.
+        ///
+        /// `[2D_OPTIONS] COUPLING_IN_FLOODING YES` restores the old grouping
+        /// for run-to-run comparison against previous versions.
+        double routing_coupling_out  = 0.0;
         double routing_outflow       = 0.0;
         double routing_evap_loss     = 0.0;
         double routing_seep_loss     = 0.0;
@@ -853,6 +1149,16 @@ struct SimulationContext {
         double gw_lateral_flow  = 0.0; ///< Cumulative lateral GW flow (ft)
         double gw_init_storage  = 0.0; ///< Initial GW storage (ft)
         double gw_final_storage = 0.0; ///< Final GW storage (ft)
+        /// U3 (track I-b, 2026-09-07): the part of the groundwater's
+        /// infiltration input that arrived from the 2D surface
+        /// ([2D_OPTIONS] INFIL_DESTINATION SUBCATCH_AQUIFER), ft³ — the same
+        /// unit as `gw_infil` (rate × area × dt). Already inside it: the
+        /// recharge is added to each subcatchment's infiltration rate before
+        /// GWSolver::execute books it, so this is a diagnostic split, not a
+        /// second inflow. Booked at delivery, in the same loop as
+        /// `mass_balance_2d.infil_to_aquifer` (G1-c item 1), so the two are
+        /// the same volumes in two units.
+        double gw_infil_2d_recharge = 0.0;
 
         // Per-step accumulators (reset each step for reporting)
         double step_flooding     = 0.0;
@@ -861,6 +1167,16 @@ struct SimulationContext {
         double step_gw_inflow    = 0.0;
         double step_rdii_inflow  = 0.0;
         double step_ext_inflow   = 0.0;
+        /// legacy massbal_getStepFlowError() of the PREVIOUS routing step —
+        /// 1 - outflow/inflow of that step's StepFlowTotals, formed at the
+        /// end of updateRoutingMassBalance — which isInSteadyState compares
+        /// with SysFlowTol at the start of the next step.
+        double last_step_flow_error = 0.0;
+        /// legacy addExternalInflows (routing.c): a node's NEGATIVE external
+        /// flow (a withdrawal) is booked as system OUTFLOW, not as a negative
+        /// external inflow; summed here per step, ahead of the outfall and
+        /// flooding terms as legacy's StepFlowTotals.outflow is.
+        double step_ext_withdrawal = 0.0;
 
         // Quality mass balance (per-pollutant, in mass units)
         std::vector qual_init_buildup;   ///< Initial buildup mass
@@ -883,6 +1199,12 @@ struct SimulationContext {
         std::vector qual_routing_ex_in;  ///< External (interface file) quality mass inflow
         std::vector qual_routing_seep;   ///< Quality mass lost to seepage
         std::vector qual_routing_evap;   ///< Quality mass lost to evaporation
+        /// Mass booked to final storage as a link went dry, accumulated over
+        /// the run (legacy massbal_addToFinalStorage). Legacy adds the
+        /// end-of-run stored mass ON TOP of this running total
+        /// (massbal.c:885), so it is kept apart from qual_routing_final,
+        /// which SWMMEngine recomputes from state every routing step.
+        std::vector qual_routing_final_dry;
 
         void resize_quality(int n_pollutants) {
             auto np = static_cast(n_pollutants);
@@ -906,6 +1228,7 @@ struct SimulationContext {
             qual_routing_ex_in.assign(np, 0.0);
             qual_routing_seep.assign(np, 0.0);
             qual_routing_evap.assign(np, 0.0);
+            qual_routing_final_dry.assign(np, 0.0);
             routing_forcing_qual_inflow.assign(np, 0.0);
         }
 
@@ -931,6 +1254,7 @@ struct SimulationContext {
             auto qrex = std::move(qual_routing_ex_in);
             auto qrseep = std::move(qual_routing_seep);
             auto qrevap = std::move(qual_routing_evap);
+            auto qrfd = std::move(qual_routing_final_dry);
             auto qrfqi = std::move(routing_forcing_qual_inflow);
             *this = MassBalance{};
             qual_init_buildup = std::move(qi);
@@ -953,6 +1277,7 @@ struct SimulationContext {
             qual_routing_ex_in = std::move(qrex);
             qual_routing_seep = std::move(qrseep);
             qual_routing_evap = std::move(qrevap);
+            qual_routing_final_dry = std::move(qrfd);
             routing_forcing_qual_inflow = std::move(qrfqi);
             // Zero out the quality vectors (except init_buildup which is
             // computed once during initQuality and must survive reset)
@@ -969,6 +1294,7 @@ struct SimulationContext {
                             &qual_routing_ex_in,
                             &qual_routing_seep,
                             &qual_routing_evap,
+                            &qual_routing_final_dry,
                             &routing_forcing_qual_inflow}) {
                 std::fill(v->begin(), v->end(), 0.0);
             }
@@ -976,17 +1302,27 @@ struct SimulationContext {
 
         /// Runoff continuity error (fraction).
         double runoff_error() const {
-            double total_in = runoff_rainfall + runoff_init_store;
-            double total_out = runoff_evap + runoff_infil + runoff_runoff + runoff_final_store;
+            // Snow is a STORE on both sides, and snow ploughed out of the
+            // system is a loss — matching legacy massbal.c:685-692. A pack
+            // present at the start is water the model was given; a pack still
+            // standing at the end is water it still holds.
+            double total_in = runoff_rainfall + runoff_runon + runoff_init_store +
+                              runoff_init_snow;
+            double total_out = runoff_evap + runoff_infil + runoff_runoff +
+                               runoff_lid_drain +
+                               runoff_final_store + runoff_snowremov +
+                               runoff_final_snow;
             return (total_in > 0.0) ? (total_in - total_out) / total_in : 0.0;
         }
 
         /// Routing continuity error (fraction).
         double routing_error() const {
             double total_in = routing_dry_weather + routing_wet_weather +
-                              routing_gw_inflow + routing_rdii + routing_external +
+                              routing_gw_inflow + routing_link_gw_inflow +   // G-X4
+                              routing_rdii + routing_external +
                               routing_init_storage;
-            double total_out = routing_flooding + routing_outflow +
+            double total_out = routing_flooding + routing_coupling_out +
+                               routing_outflow +
                                routing_evap_loss + routing_seep_loss +
                                routing_final_storage;
             return (total_in > 0.0) ? (total_in - total_out) / total_in : 0.0;
@@ -1001,6 +1337,31 @@ struct SimulationContext {
         }
     } mass_balance;
 
+    /**
+     * @brief D-NS1 negative-source clamp bookkeeping (subplan §3.1, X6).
+     *
+     * @details A negative source (mass extraction) is clamped per step to
+     *          the mass its element holds; each clamp is counted here, its
+     *          shortfall un-booked from the extraction's ledger row (the
+     *          ledger carries what was ACTUALLY removed), and the first
+     *          clamp warns. Age extraction (age·volume) is counted but not
+     *          ledgered — age has no continuity row until A2c.
+     */
+    struct NegativeSourceStats {
+        long   clamp_events     = 0;   ///< pollutant clamps, all engines
+        double shortfall_mass   = 0.0; ///< unmet extraction, internal units
+        long   age_clamp_events = 0;   ///< age-row clamps
+        int    first_node       = -1;  ///< element of the first clamp
+        /// First clamp seen — captures `first_node` once. NOT a warning flag:
+        /// the per-clamp runtime warning was removed 2026-08-29 because it
+        /// fired on every correct extraction deck (a deck extracting 40 % of
+        /// its inflow logged 108 clamps while the chain wetted). The
+        /// end-of-run summary is the diagnostic.
+        bool   first_clamp_recorded = false;
+        bool   api_warned       = false; ///< first negative API mass flux
+        void reset() { *this = NegativeSourceStats{}; }
+    } negsrc;
+
     /**
      * @brief System mass-balance totals for the optional 2D surface domain.
      *
@@ -1022,6 +1383,33 @@ struct SimulationContext {
         double boundary_in           = 0.0;  ///< Cumulative boundary inflow (m³)
         double boundary_out          = 0.0;  ///< Cumulative boundary outflow (m³)
         double evap_out              = 0.0;  ///< Cumulative evaporation loss (m³)
+        /// Cumulative 2D per-cell infiltration loss (m³). Track I, plan §5.5.4.
+        /// Destination is LOST in this release (D-I4), so this is a true exit
+        /// from the modelled system and enters the continuity balance as a loss
+        /// term alongside evap_out.
+        double infil_out             = 0.0;
+        /// U3 (track I-b, 2026-09-07): the part of `infil_out` routed into a
+        /// legacy subcatchment aquifer ([2D_OPTIONS] INFIL_DESTINATION
+        /// SUBCATCH_AQUIFER), m³. It is a TRANSFER, not an exit: the same
+        /// volume enters the 1D groundwater ledger as recharge, so a
+        /// whole-model balance nets it out. `infil_out` still carries it,
+        /// so the 2D-only continuity check is unchanged.
+        double infil_to_aquifer      = 0.0;
+        /// G1-c item 1 (2026-09-19): the SUBCATCH_AQUIFER share the marcher
+        /// has applied but the runoff step has not yet delivered to the
+        /// aquifer (m³) — the volume between one runoff drain and the next,
+        /// non-zero at the end of a run. `infil_to_aquifer` is booked at
+        /// delivery, so `infil_to_aquifer + infil_aquifer_pending` is the
+        /// aquifer-bound share of `infil_out` at any instant.
+        double infil_aquifer_pending = 0.0;
+        /// G1 (2026-09-07): cumulative water the two-zone `[2D_AQUIFER]`
+        /// returned to the surface — Dunne saturation excess and top-layer
+        /// rejection — m³. An INFLOW to the surface domain, and the mirror of
+        /// the `infil_out` share the aquifer received. Without it the returned
+        /// water reads as storage created from nothing and the 2D continuity
+        /// error grows by exactly the volume that came back up. Zero unless a
+        /// `[2D_AQUIFER]` resolved.
+        double aquifer_in            = 0.0;
         bool   active                = false;///< True if the 2D module ran
 
         // Cumulative marcher statistics (published by SurfaceRouter2D at
@@ -1042,9 +1430,9 @@ struct SimulationContext {
         /// 2D surface continuity error (fraction).
         double error() const {
             double total_in  = rainfall_in + coupling_1d_to_2d_in + outfall_in
-                               + boundary_in + init_storage;
+                               + boundary_in + aquifer_in + init_storage;
             double total_out = coupling_2d_to_1d_out + outfall_out + boundary_out
-                               + evap_out + final_storage;
+                               + evap_out + infil_out + final_storage;
             return (total_in > 0.0) ? (total_in - total_out) / total_in : 0.0;
         }
     } mass_balance_2d;
@@ -1148,6 +1536,47 @@ struct SimulationContext {
         double computed_avg_iterations() const {
             return (n_steps > 0) ? sum_iterations / static_cast(n_steps) : 0.0;
         }
+
+        // ---------------------------------------------------------------
+        // FV 1D solver statistics (published by SWMMEngine::end() from
+        // INetworkSolver::run_stats, printed as the "FV Solver Statistics"
+        // report block). The 1D counterpart of mass_balance_2d.solver_*.
+        //
+        // -1 = not populated: the run was not FLOW_ROUTING FV, or a backend
+        // that carries no counters was selected. The report block is skipped
+        // on the sentinel rather than printing a row of zeros, which would
+        // read as "the solver did nothing" instead of "nobody counted".
+        // ---------------------------------------------------------------
+        // Slot-storage share (FV slot program R0). Peak instantaneous
+        // system share slot/stored and the time that share exceeded 1 %;
+        // the run-level integrated share is Σ links.stat_slot_vol_dt /
+        // Σ links.stat_vol_dt, summed at report time. 0 under DW.
+        double slot_peak_share   = 0.0;
+        double slot_time_above_s = 0.0;
+
+        long   fv_nsteps        = -1;   ///< explicit substeps over the run
+        long   fv_nflux         = 0;    ///< face flux evaluations
+        double fv_avg_h         = 0.0;  ///< mean substep (s)
+        double fv_last_h        = 0.0;  ///< last substep (s)
+        double fv_min_h         = 0.0;  ///< smallest substep taken (s)
+        double fv_active_min    = -1.0; ///< min active-face fraction
+        double fv_active_mean   = -1.0; ///< mean active-face fraction
+        double fv_active_max    = -1.0; ///< max active-face fraction
+        long   fv_tier_cells[8] = {0};  ///< rebuild-sampled cells per LTS tier
+        int    fv_n_tiers       = 0;    ///< populated tier count
+
+        // dt-argmin attribution (slot program R0): who owned the binding
+        // CFL element, counted per census / re-tier.
+        long   fv_dt_argmin_pressurized = 0;
+        long   fv_dt_argmin_band        = 0;
+        long   fv_dt_argmin_free        = 0;
+        long   fv_dt_argmin_node        = 0;
+
+        // LTS macro cycles that ran / were rejected. Distinguishes "tiering
+        // never engaged" from "tiering did not help" (the tier histogram
+        // alone cannot).
+        long   fv_macro_cycles   = 0;
+        long   fv_macro_rejected = 0;
     } routing_stats;
 
     // =========================================================================
@@ -1175,21 +1604,90 @@ struct SimulationContext {
         }
     } vj_diag;
 
+    // =========================================================================
+    // Street inlet performance diagnostics
+    // =========================================================================
+
+    /**
+     * @brief Per-inlet-usage performance block for the .rpt street tables.
+     *
+     * @details Row i corresponds to `inlet_usages` row i. Populated by
+     *          `inlet::InletSolver::gatherStats()` before the summary is
+     *          written; these are the legacy `TInletStats` counters
+     *          (inlet.c:78-87) that the Street Flow Summary reports and that
+     *          `InletUsageStore` (a persistent .inp store) deliberately does
+     *          not carry.
+     */
+    struct InletDiag {
+        std::vector     host_node;         ///< inlet-junction node (−1 = conduit host)
+        std::vector     up_link;           ///< approach conduit (−1 = none)
+        std::vector is_sag;            ///< resolved placement: 1 = ON_SAG
+        std::vector     num_inlets;
+        std::vector     flow_periods;      ///< # periods with approach flow
+        std::vector     capture_periods;   ///< # periods with captured flow
+        std::vector     backflow_periods;  ///< # periods with backflow
+        std::vector  peak_flow;         ///< peak approach flow (cfs)
+        std::vector  peak_flow_capture; ///< capture efficiency at peak flow (%)
+        std::vector  avg_flow_capture;  ///< Σ capture efficiency over capture periods
+        std::vector  bypass_freq;       ///< # capture periods that also bypassed
+
+        int count() const { return static_cast(host_node.size()); }
+
+        void resize(int n) {
+            auto un = static_cast(n);
+            host_node.assign(un, -1);
+            up_link.assign(un, -1);
+            is_sag.assign(un, static_cast(0));
+            num_inlets.assign(un, 1);
+            flow_periods.assign(un, 0);
+            capture_periods.assign(un, 0);
+            backflow_periods.assign(un, 0);
+            peak_flow.assign(un, 0.0);
+            peak_flow_capture.assign(un, 0.0);
+            avg_flow_capture.assign(un, 0.0);
+            bypass_freq.assign(un, 0.0);
+        }
+
+        void clear() {
+            host_node.clear(); up_link.clear(); is_sag.clear(); num_inlets.clear();
+            flow_periods.clear(); capture_periods.clear(); backflow_periods.clear();
+            peak_flow.clear(); peak_flow_capture.clear(); avg_flow_capture.clear();
+            bypass_freq.clear();
+        }
+    } inlet_diag;
+
     // =========================================================================
     // Control action log — Gap #67
     // Populated by ControlEngine::applyPendingActions() when rpt_controls is on.
     // =========================================================================
 
-    /// One entry per control rule action that changed a link setting.
+    /// One entry per control rule action that changed a link setting. POD:
+    /// the rule NAME is interned in control_rule_names (index rule_idx), so a
+    /// deck that toggles a pump every routing step does not heap-allocate a
+    /// string per action — this log is only drained at report time.
     struct ControlLogEntry {
-        int         link_idx;    ///< Index of the link whose setting changed
-        std::string rule_name;   ///< Name of the rule that triggered the change
-        double      new_setting; ///< The new target setting value (0-1)
-        double      date;        ///< OADate when the change occurred
+        int    link_idx;    ///< Index of the link whose setting changed
+        int    rule_idx;    ///< Index into control_rule_names; -1 = unknown ("Rule?")
+        double new_setting; ///< The new target setting value (0-1)
+        double date;        ///< OADate when the change occurred
     };
 
-    /// Chronological log of all control actions taken during the simulation.
+    /// Chronological log of the control actions taken during the simulation,
+    /// capped at kMaxControlLog entries (see logControlAction).
     std::vector control_log;
+    /// Rule names by rule index, interned by ControlEngine as actions are logged.
+    std::vector control_rule_names;
+    /// Actions NOT logged because the cap was reached; the report says so once.
+    std::size_t control_log_dropped = 0;
+    static constexpr std::size_t kMaxControlLog = 1'000'000;
+
+    /// Append to control_log unless the cap is reached, in which case count
+    /// the overflow instead: bounds memory on multi-week oscillating decks
+    /// (24 B per entry → 24 MB at the cap).
+    void logControlAction(const ControlLogEntry& e) {
+        if (control_log.size() >= kMaxControlLog) { ++control_log_dropped; return; }
+        control_log.push_back(e);
+    }
 
     // =========================================================================
     // Input file path (for model write / hot start)
@@ -1270,6 +1768,8 @@ struct SimulationContext {
     void reset() {
         state = EngineState::CREATED;
         control_log.clear();
+        control_rule_names.clear();
+        control_log_dropped = 0;
         current_time = 0.0;
         current_date = 0.0;
         dt_controls_remaining = 0.0;
@@ -1283,6 +1783,8 @@ struct SimulationContext {
         errors.clear();
         title_notes.clear();
         deferred_section_rows.clear();
+        pending_gw_nodes.clear();
+        pending_link_nodes.clear();
 
         // Clear SoA stores
         nodes      = NodeData{};
@@ -1302,8 +1804,24 @@ struct SimulationContext {
         // Clear inflow-related stores that aren't reset by their owning solvers
         rdii_decay = RDIIDecayData{};
 
+        // E3: transport.ard component config — its apply hook resets it, but
+        // a reopen WITHOUT the component would otherwise inherit the previous
+        // model's dispersion.
+        ard_config = ArdConfigData{};
+
+        // A1a: same stale-on-reopen hygiene for water age.
+        water_age_config = WaterAgeConfigData{};
+        water_age_state.clear();
+
+        // H1: and for heat.
+        heat_config = HeatConfigData{};
+        heat_state.clear();
+        lid_layer_state.clear();
+        bed_state.clear();      // H6b
+
         // Virtual-junction diagnostics
         vj_diag.clear();
+        inlet_diag.clear();
 
         // Clear daily climate state (re-initialized by SWMMEngine on next run)
         climate_state = climate::ClimateState{};
@@ -1315,7 +1833,7 @@ struct SimulationContext {
         user_flags.clear();
         events.clear();
         std::fill(std::begin(adjust_temp), std::end(adjust_temp), 0.0);
-        std::fill(std::begin(adjust_evap), std::end(adjust_evap), 1.0);
+        std::fill(std::begin(adjust_evap), std::end(adjust_evap), 0.0);
         std::fill(std::begin(adjust_rain), std::end(adjust_rain), 1.0);
         std::fill(std::begin(adjust_hydcon), std::end(adjust_hydcon), 1.0);
         subcatch_n_perv_pattern.clear();
@@ -1336,6 +1854,8 @@ struct SimulationContext {
     void save_state() noexcept {
         nodes.save_state();
         links.save_state();
+        // (SWMMEngine::step rolls the two halves separately — see
+        // save_lat_qual_state / save_hyd_state.)
         // NOTE: subcatches.save_state() is intentionally NOT called here.
         // Subcatchment old-state (old_runoff/old_runon/conc_old) is the
         // runoff-step snapshot used to linearly interpolate lateral inflow
@@ -1347,6 +1867,20 @@ struct SimulationContext {
         // runoff-advance loop in SWMMEngine::stepRunoff().
     }
 
+    /// The every-step half of legacy routing_execute: initSystemInflows'
+    /// oldLatFlow roll and node/link _setOldQualState.
+    void save_lat_qual_state() noexcept {
+        nodes.save_lat_qual_state();
+        links.save_qual_state();
+    }
+
+    /// The routed-step half: legacy routeFlow's node/link _setOldHydState,
+    /// skipped with the routing on a SKIP_STEADY_STATE step.
+    void save_hyd_state() noexcept {
+        nodes.save_hyd_state();
+        links.save_hyd_state();
+    }
+
     /**
      * @brief Reset all state variables to initial conditions (cold start).
      *
@@ -1392,6 +1926,7 @@ struct SimulationContext {
         // Resize spatial coordinate arrays
         spatial.node_x.assign(static_cast(node_names.size()), 0.0);
         spatial.node_y.assign(static_cast(node_names.size()), 0.0);
+        spatial.node_has_xy.assign(static_cast(node_names.size()), 0);   // G-X2
         spatial.link_x.assign(static_cast(link_names.size()), 0.0);
         spatial.link_y.assign(static_cast(link_names.size()), 0.0);
         spatial.subcatch_x.assign(static_cast(subcatch_names.size()), 0.0);
@@ -1459,20 +1994,18 @@ struct SimulationContext {
     // which kind it wants.
     // =========================================================================
 
-    /** @brief Find a timeseries table by name; -1 if none. */
+    /**
+     * @brief Find a timeseries table by name; -1 if none.
+     * @details O(1) via TableData::by_name. Returns the lowest matching index,
+     *          exactly as the previous linear scan did.
+     */
     int find_timeseries(std::string_view name) const noexcept {
-        for (int i = 0; i < n_tables(); ++i)
-            if (tables[i].type == TableType::TIMESERIES && ieq(tables[i].id, name))
-                return i;
-        return -1;
+        return tables.find_by_kind(name, /*want_timeseries=*/true);
     }
 
     /** @brief Find a curve table (any CURVE_* type) by name; -1 if none. */
     int find_curve(std::string_view name) const noexcept {
-        for (int i = 0; i < n_tables(); ++i)
-            if (tables[i].type != TableType::TIMESERIES && ieq(tables[i].id, name))
-                return i;
-        return -1;
+        return tables.find_by_kind(name, /*want_timeseries=*/false);
     }
 
     /**
diff --git a/src/engine/core/SimulationOptions.hpp b/src/engine/core/SimulationOptions.hpp
index 658734809..9654c743c 100644
--- a/src/engine/core/SimulationOptions.hpp
+++ b/src/engine/core/SimulationOptions.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SimulationOptions.hpp
  * @brief Simulation options parsed from the [OPTIONS] section.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SIMULATION_OPTIONS_HPP
@@ -63,6 +79,29 @@ enum class RoutingModel : int {
     FV       = 3   ///< Explicit conservative finite volume (Godunov, HLL/HLLC)
 };
 
+/**
+ * @brief Water-quality engine (`[OPTIONS] QUALITY_SOLVER`, master plan D-UT6).
+ */
+enum class QualitySolverKind : int {
+    LEGACY       = 0,  ///< Legacy-parity CSTR mixing (QualityRouting.cpp)
+    EULERIAN_ARD = 1,  ///< Eulerian ARD on the FV cell mesh (all routing models)
+    LAGRANGIAN   = 2   ///< LARD segment transport. LIVE: LTD advection +
+                       ///< junction/storage mixing (X2 `8c141a5e`), RWPT
+                       ///< dispersion (X3b `b9852cee`), water age (X4
+                       ///< `9f155227`), exact-exponential KDECAY.
+                       ///< NOT YET, each behind a live open() warning in
+                       ///< SWMMEngine::open: MSX reactions on segments (L3),
+                       ///< treatment interop, heat (H7). Storage mixing
+                       ///< beyond CMSTR is also absent but is NOT warned —
+                       ///< there is no input surface for it yet, so there is
+                       ///< nothing to bypass.
+                       ///< (This comment said "X1 skeleton dispatch only;
+                       ///< transport lands in X2" until 2026-08-25, five
+                       ///< rounds after X2 landed.)
+                       ///< (plans/transport/LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md,
+                       ///< plans/LAGRANGIAN_QUALITY_STRATEGY.md)
+};
+
 /**
  * @brief Infiltration methods.
  * @see Legacy: InfilModelType in enums.h
@@ -153,6 +192,23 @@ struct SimulationOptions {
     /** @brief Hydraulic routing timestep in seconds. Legacy default: 20. */
     double routing_step = 20.0;
 
+    /**
+     * @brief The ROUTING_STEP as authored, before WARNING 07 reduces
+     *        routing_step to the wet-weather step (SWMMEngine::validate_project).
+     * @details legacy project_validate runs link_validate BEFORE that
+     *          reduction, so every RouteStep-derived link constant — the
+     *          Courant lengthening's MIN(RouteStep, LengtheningStep), an
+     *          orifice's / weir's equivalent length 2·RouteStep·sqrt(g·yFull)
+     *          — is formed from the written value. 0 = not recorded (use
+     *          routing_step). Runtime-only; not written by the .inp writer.
+     */
+    double routing_step_authored = 0.0;
+
+    /// The routing step legacy's link_validate saw (see routing_step_authored).
+    double linkValidateRoutingStep() const noexcept {
+        return routing_step_authored > 0.0 ? routing_step_authored : routing_step;
+    }
+
     /** @brief Minimum routing timestep in seconds (CFL floor). */
     double min_routing_step = 0.5;
 
@@ -195,6 +251,153 @@ struct SimulationOptions {
     /** @brief Routing method. Legacy default: DYNWAVE. */
     RoutingModel routing_model = RoutingModel::DYNWAVE;
 
+    /**
+     * @brief Water-quality engine selection (`[OPTIONS] QUALITY_SOLVER`).
+     *
+     * @details LEGACY = the legacy-parity CSTR QualitySolver (default,
+     *          bit-identical behavior). EULERIAN_ARD = the solver-agnostic
+     *          Eulerian ARD engine on the FV cell mesh
+     *          (plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md rev. 2;
+     *          master plan D-UT6). LAGRANGIAN = the LARD segment engine —
+     *          X1 wiring only: the dispatch exists, transport does not, so
+     *          quality state reads zero and the open() warning says so
+     *          (plans/transport/LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md).
+     */
+    QualitySolverKind quality_solver = QualitySolverKind::LEGACY;
+
+    /**
+     * @brief `[OPTIONS] QUALITY_STEP` — transport substep, seconds
+     *        (HH:MM:SS or seconds; 0 = follow ROUTING_STEP).
+     *
+     * @details X3a: consumed by the LARD engine only, which splits each
+     *          routing step into ceil(dt_routing / quality_step) equal
+     *          substeps (strategy §4.2). Setting it under LEGACY or
+     *          EULERIAN_ARD warns at open — those engines do not substep
+     *          on this key.
+     */
+    double quality_step = 0.0;
+
+    /**
+     * @brief `[OPTIONS] MAX_SEGMENTS_PER_LINK` — LARD slab capacity per
+     *        link (strategy §4.1; default 100, the EPANET MAXSEGS shape).
+     *
+     * @details Values below 2 are clamped to 2 at solver init. Consumed by
+     *          the LARD engine only; warns at open under other solvers.
+     */
+    int max_segments_per_link = 100;
+
+    /**
+     * @brief `[OPTIONS] DISPERSION RWPT|OFF` — LARD RWPT dispersion (X3b;
+     *        strategy §5; the GUI plan's Lagrangian-group key).
+     *
+     * @details Resolved vertical-shear dispersion on the segments
+     *          (RwptDispersion.hpp). LARD-only; warns under other solvers
+     *          (the ARD engine's dispersion is E3's `transport.ard`
+     *          machinery, deliberately separate).
+     */
+    bool lard_rwpt = false;
+
+    /**
+     * @brief `[OPTIONS] RWPT_SEED` — deterministic counter-RNG seed
+     *        (D-L6). Same seed ⇒ bit-identical runs at any thread count.
+     */
+    int rwpt_seed = 0;
+
+    /**
+     * @brief `[OPTIONS] WATER_AGE ON|OFF` — transported water-age tracking
+     *        (water age plan §1, reserved species __WATER_AGE__).
+     *
+     * @details A1a scope: the age species rides the EULERIAN_ARD mesh
+     *          (unit zero-order aging + volume-weighted mixing); per-source
+     *          initial ages come from the waterage component's
+     *          [WATER_AGE_SOURCES]. LEGACY-engine age arrives with A1b and
+     *          warns until then.
+     */
+    bool water_age = false;
+
+    /**
+     * @brief `[OPTIONS] OUTFALL_BACKFLOW_QUALITY LAST|ZERO` — quality carried
+     *        by reverse flow at outfalls (false = LAST, the default).
+     *
+     * @details LAST is the legacy convention (src/legacy/engine/qualrout.c
+     *          findNodeQual): an outfall that takes no inflow keeps its last
+     *          mixed concentration while wet, and backflow re-injects that
+     *          held value — under WATER_AGE the held boundary water also
+     *          keeps aging 1:1, so a permanently supplying outfall becomes an
+     *          unbounded age source. ZERO makes a supplying outfall a fresh
+     *          boundary: whenever it takes no volume inflow its held state
+     *          reads zero for every pollutant AND __WATER_AGE__, so
+     *          re-entering water carries no mass and no age (the
+     *          EPANET-reservoir picture). ZERO deliberately does NOT return
+     *          the mass that left through the outfall — the receiving water
+     *          is an infinite fresh reservoir; tidal-flushing studies where
+     *          returned mass matters keep LAST.
+     */
+    bool outfall_backflow_zero = false;
+
+    /**
+     * @brief `[OPTIONS] HEAT_TRANSPORT ON|OFF` — transported temperature
+     *        (heat plan §1, reserved species __TEMPERATURE__).
+     *
+     * @details H1 scope: TRANSPORT ONLY. Temperature is advected and mixed
+     *          as a conservative tracer under the LEGACY CSTR engine and
+     *          reported as a trailing species column; per-source inlet
+     *          temperatures come from the heat component's [HEAT_SOURCES].
+     *          The surface/radiative/sediment flux modules of plan §2 —
+     *          the terms that make temperature change rather than merely
+     *          move — arrive with H2–H4.
+     */
+    bool heat_transport = false;
+
+    /**
+     * @brief Monthly relative humidity, % (`[TEMPERATURE] HUMIDITY`).
+     *
+     * @details H2. `ClimateState::humidity` has existed with a 50 % default
+     *          since before this program and **nothing ever wrote to it** —
+     *          the GeoPackage climate format reads a humidity column that
+     *          never reached the running state. Surface heat exchange is the
+     *          first consumer, so the deck key arrives with it. Monthly like
+     *          `WINDSPEED`; a single value fills all twelve months.
+     *
+     *          Holds RH (%) when `humidity_var == 0`, dew point (project
+     *          temperature units) when `humidity_var == 1`. Used when
+     *          `humidity_type` is CONSTANT (0) or MONTHLY (1).
+     */
+    double humidity[12] = {50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50};
+
+    /** @brief Humidity source: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES. */
+    int humidity_type = 0;
+
+    /** @brief Humidity quantity: 0=RELATIVE (%), 1=DEWPOINT (deg F US / deg C SI).
+     *  @details Dew point is converted to RH each step from the effective air
+     *           temperature: RH = 100·e_s(Td)/e_s(Ta), clamped to [0, 100]. */
+    int humidity_var = 0;
+
+    /** @brief Timeseries name for humidity (humidity_type == 2). */
+    std::string humidity_ts_name;
+
+    /**
+     * @brief Water density, kg/m³ (`[OPTIONS] WATER_DENSITY`; CSH Table 4.1).
+     * @details H2. Load-bearing from this phase on: it sets the weight of a
+     *          surface flux against advected heat. H1 deliberately shipped
+     *          without it because with no fluxes it cancelled identically
+     *          and no gate could observe its value.
+     */
+    double water_density = 1000.0;
+
+    /// Water specific heat capacity, J/kg/°C (`WATER_SPECIFIC_HEAT_CAPACITY`).
+    double water_specific_heat = 4184.0;
+
+    /**
+     * @brief Wind-function coefficients (`WIND_FUNC_COEFF_A` / `_B`), CSH
+     *        Table 4.1 — `f(w) = a + b·w`, Dunne & Leopold (1978) defaults.
+     */
+    double wind_func_coeff_a = 1.505e-8;
+    double wind_func_coeff_b = 1.6e-8;
+
+    /// Pa/P elevation correction in the Bowen ratio (`PRESSURE_RATIO`).
+    double pressure_ratio = 1.0;
+
     /**
      * @brief Knobs for FLOW_ROUTING FV, grouped rather than spread across this
      *        struct (plan §4.2 — first-class [OPTIONS] keys, no new section).
@@ -225,6 +428,12 @@ struct SimulationOptions {
      *  @see Sharior et al. (2023) for DYNAMIC_SLOT */
     int surcharge_method = 0;
 
+    /** @brief TPA acoustic celerity a for SURCHARGE_METHOD TPA (PROJECT
+     *         length units per second, converted like FV_SLOT_CELERITY).
+     *         Sets the constant slot width w = g·A_full/a² (issue #156).
+     *  @see Vasconcelos, Wright & Roe (2006) */
+    double tpa_celerity = 100.0;
+
     /** @brief DPS target pressure celerity (m/s, converted to ft/s at init).
      *  @details Controls the maximum modeled pressure wave speed. Lower values
      *           allow larger timesteps but reduce transient fidelity.
@@ -245,16 +454,48 @@ struct SimulationOptions {
      *  @see Sharior et al. (2023) Eq. 22 */
     double dps_decay_time = 0.5;
 
+    /** @brief Unsteady friction model: 0=NONE (default, inert), 1=VITKOVSKY.
+     *  @details Adds the Pinto/Vasconcelos/Soares (2025) unsteady-friction
+     *           source term S_fu = (k3/g)(dV/dt + c·sgn(V)|dV/dx|) with
+     *           regime-dependent celerity c to the momentum equation.
+     *           CONSUMED BY THE FV SOLVER as of issue #156 Phase 2 (copied
+     *           into FvOptions by Router::initFv; applied by
+     *           kernels::ufUpdate after the steady-friction stage, with the
+     *           convective term precomputed per substep). Under DYNWAVE the
+     *           key is still parsed, round-tripped and echoed but inert —
+     *           the dynamic wave source term is Phase 3.
+     *  @see Pinto, Vasconcelos & Soares (2025), J. Hydraul. Eng. 152(1);
+     *       Vitkovsky et al. (2000). Plan: plans/MIXED_FLOW_CLOSURES_TPA_UF_PLAN_2026-08-29.md §3 */
+    int unsteady_friction = 0;
+
+    /** @brief Report signed piezometric heads: 0 = NO (default, legacy
+     *         bit-parity — NODE_HEAD is rebuilt as f32(floored depth) +
+     *         f32(invert)), 1 = YES — the .out HEAD field carries the TRUE
+     *         signed head (point-in-time), so sub-atmospheric TPA columns are
+     *         observable (issue #156 O-6). DEPTH stays floored either way. */
+    int report_signed_heads = 0;
+
+    /** @brief Unsteady friction coefficient k3 (dimensionless).
+     *  @details Brunone-type coefficient; used only when unsteady_friction != 0.
+     *           Paper-calibrated range 0.005–0.020 (tested to 0.045).
+     *  @see Pinto et al. (2025) Table 1 (issue #156) */
+    double uf_k3 = 0.015;
+
     /** @brief Node continuity formulation for depth update. Default: EXPLICIT (legacy). */
     NodeContinuity node_continuity = NodeContinuity::EXPLICIT;
 
-    /** @brief Virtual-junction momentum treatment: 0=BASIC, 1=FULL.
+    /** @brief Virtual-junction momentum treatment. Always 0 (BASIC).
      *  @details BASIC applies zero storage, the shared junction sigma and
-     *           cross-junction upwinding; FULL adds the cross-junction
-     *           convective flux correction (dq4_j). Refactored engine only.
+     *           cross-junction upwinding of area/hydraulic radius; it
+     *           transmits no cross-junction convective momentum. FULL, which
+     *           added the dq4_j correction, is RETIRED (2026-08-14): the term
+     *           was sign-inverted relative to the per-link convective term and
+     *           applied to both adjacent links, destroying 224-325 % of the
+     *           routed volume on SWASHES macdonald-periodic. The keyword is
+     *           still parsed, warns, and is treated as BASIC; the field is
+     *           kept only so existing writers/readers keep their layout.
      *  @code
-     *  VIRTUAL_JUNCTION_MOMENTUM  BASIC  ;; default
-     *  VIRTUAL_JUNCTION_MOMENTUM  FULL
+     *  VIRTUAL_JUNCTION_MOMENTUM  BASIC  ;; default; FULL warns and maps here
      *  @endcode
      */
     int virtual_junction_momentum = 0;
@@ -293,8 +534,11 @@ struct SimulationOptions {
     double min_surf_area = 0.0;  // 0 = use MIN_SURFAREA constant
 
     /** @brief Convergence head tolerance in project length units.
-     *  @details Legacy default: 0.0 (sentinel → runtime default 0.005 ft). */
-    double head_tol = 0.005;
+     *  @details Legacy default: 0.0 (sentinel → runtime default 0.005 ft,
+     *  dynwave_validate). A written value is in the project's length unit
+     *  and is divided by UCF(LENGTH) at routing init — a 0.005 on an SI
+     *  deck is 0.005 m (0.0164 ft), not the default. */
+    double head_tol = 0.0;
 
     /** @brief System flow tolerance (fraction, e.g., 0.05 = 5%).
      *  @details Legacy default: 0.05. Input is in percent, divided by 100. */
@@ -376,14 +620,24 @@ struct SimulationOptions {
     /**
      * @brief Number of OpenMP threads for parallel solver loops.
      *
-     * @details Parsed from the THREADS keyword in [OPTIONS].
-     *   - 0 → use all available threads (omp_get_max_threads()).
+     * @details Parsed from the THREADS keyword in [OPTIONS]. Resolution
+     * (core/ThreadInfo.hpp, THREAD_LIMITS_AND_OVERSUBSCRIPTION_PLAN):
+     *   - 0 → auto: omp_get_max_threads() — the logical processors the
+     *     OpenMP runtime allows (lowered by OMP_NUM_THREADS / OMP_THREAD_LIMIT
+     *     / CPU affinity) — then the model-size gates and, on Apple Silicon,
+     *     the dynamic-wave performance-core clamp.
      *   - 1 → single-threaded (default, no OpenMP overhead).
-     *   - N → use min(N, omp_get_max_threads()) threads.
+     *   - N → exactly N threads. Values above the logical processors or the
+     *     runtime limit are honoured (oversubscription) with a warning; the
+     *     active spin-wait policy is disabled for an oversubscribed run.
+     *
+     * Model-size gates still apply to explicit values (warned): dynamic wave
+     * keeps >= 100 conduits per thread; the 2D marcher needs >= 4 triangles
+     * per thread. The 2D Kokkos OpenMP backend receives the raw value via
+     * the plugin ABI (v4) and initialises once per process.
      *
-     * A performance threshold is applied at startup: if the number of
-     * conduit links is less than 4 × num_threads, threading is disabled
-     * to avoid overhead dominating on small networks.
+     * Environment overrides (each warned when active): SWMM_DW_THREADS forces
+     * the dynamic-wave count; OPENSWMM_2D_THREADS forces the Kokkos backend.
      *
      * @see Legacy reference: globals.h NumThreads, project.c
      */
diff --git a/src/engine/core/SpatialFrame.hpp b/src/engine/core/SpatialFrame.hpp
index f9852fb55..b26e5e7ab 100644
--- a/src/engine/core/SpatialFrame.hpp
+++ b/src/engine/core/SpatialFrame.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SpatialFrame.hpp
  * @brief Spatial frame — CRS specification and coordinate data for nodes/links.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SPATIAL_FRAME_HPP
@@ -137,6 +153,12 @@ struct SpatialFrame {
     /** @brief Node Y coordinates (northing or latitude). */
     std::vector node_y;
 
+    /** @brief G-X2 (2026-09-19): 1 when the node's coordinates were authored
+     *  ([COORDINATES], the GeoPackage geometry, the spatial C API or a
+     *  virtual-junction split). A node whose entry is 0 sits at the (0, 0)
+     *  fill and must not be located on a mesh by it. Sized with node_x. */
+    std::vector node_has_xy;
+
     // -----------------------------------------------------------------------
     // Link coordinates (one point per link — nominal centroid or from-node)
     // -----------------------------------------------------------------------
diff --git a/src/engine/core/StringCase.hpp b/src/engine/core/StringCase.hpp
index f64137767..69c56e502 100644
--- a/src/engine/core/StringCase.hpp
+++ b/src/engine/core/StringCase.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file StringCase.hpp
  * @brief Case-insensitive string helpers matching legacy SWMM name semantics.
@@ -20,7 +36,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_STRING_CASE_HPP
diff --git a/src/engine/core/ThreadInfo.cpp b/src/engine/core/ThreadInfo.cpp
new file mode 100644
index 000000000..d6cd164bc
--- /dev/null
+++ b/src/engine/core/ThreadInfo.cpp
@@ -0,0 +1,193 @@
+/**
+ * @file ThreadInfo.cpp
+ * @brief Process-wide hardware / OpenMP thread capability query.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+#include "ThreadInfo.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+#if defined(SWMM_USE_OPENMP)
+#include 
+#endif
+
+#if defined(__APPLE__)
+#include 
+#endif
+
+namespace openswmm {
+namespace threadinfo {
+
+namespace {
+std::atomic g_kokkos_omp_threads{0};
+} // namespace
+
+int logicalCpus() {
+    const unsigned n = std::thread::hardware_concurrency();
+    return static_cast(n);
+}
+
+int ompMaxThreads() {
+#if defined(SWMM_USE_OPENMP)
+    const int n = omp_get_max_threads();
+    return n > 0 ? n : 1;
+#else
+    return 1;
+#endif
+}
+
+int ompAvailable() {
+#if defined(SWMM_USE_OPENMP)
+    return 1;
+#else
+    return 0;
+#endif
+}
+
+int perfCores() {
+#if defined(__APPLE__)
+    int n = 0;
+    std::size_t sz = sizeof(n);
+    if (sysctlbyname("hw.perflevel0.logicalcpu", &n, &sz, nullptr, 0) != 0)
+        return 0;
+    return (n > 0) ? n : 0;
+#else
+    return 0;
+#endif
+}
+
+int kokkosOmpThreads() {
+    return g_kokkos_omp_threads.load(std::memory_order_relaxed);
+}
+
+void setKokkosOmpThreads(int n) {
+    g_kokkos_omp_threads.store(n > 0 ? n : 0, std::memory_order_relaxed);
+}
+
+int hostReservedThreads() {
+    const char* s = std::getenv("OPENSWMM_HOST_RESERVED_THREADS");
+    if (!s || !*s) return 0;
+    const int n = std::atoi(s);
+    return n > 0 ? n : 0;
+}
+
+bool isOversubscribed(int threads) {
+    const int logical = logicalCpus();
+    return logical > 0 && threads + hostReservedThreads() > logical;
+}
+
+int resolveRequested(int requested, const char* what,
+                     std::vector* warnings) {
+    const int omp_max = ompMaxThreads();
+    if (requested <= 0) return omp_max;
+
+    const int nt = requested;
+    if (!warnings) return nt;
+
+    char buf[512];
+    const int logical  = logicalCpus();
+    const int reserved = hostReservedThreads();
+    if (logical > 0 && nt + reserved > logical) {
+        if (reserved > 0)
+            std::snprintf(buf, sizeof buf,
+                "THREADS = %d plus the %d threads the host application reserves "
+                "for itself exceed the %d logical processors on this machine "
+                "(%s). The run is oversubscribed and is likely to be slower; "
+                "active spin-wait is disabled for this run.",
+                nt, reserved, logical, what);
+        else
+            std::snprintf(buf, sizeof buf,
+                "THREADS = %d exceeds the %d logical processors on this machine "
+                "(%s). The run will be oversubscribed and is likely to be slower; "
+                "active spin-wait is disabled for this run.",
+                nt, logical, what);
+        warnings->emplace_back(buf);
+    } else if (nt > omp_max) {
+        std::snprintf(buf, sizeof buf,
+            "THREADS = %d exceeds the OpenMP limit of %d in this process "
+            "(OMP_NUM_THREADS / OMP_THREAD_LIMIT / CPU affinity) for the %s; "
+            "requesting %d anyway.",
+            nt, omp_max, what, nt);
+        warnings->emplace_back(buf);
+    }
+
+#if defined(__APPLE__)
+    const int pcores = perfCores();
+    if (pcores > 0 && nt > pcores) {
+        std::snprintf(buf, sizeof buf,
+            "THREADS = %d exceeds the %d performance cores on this Mac (%s). "
+            "Efficiency cores slow barrier-synchronised solvers (measured up "
+            "to 3-4x slower). Use THREADS = 0 (auto) or <= %d.",
+            nt, pcores, what, pcores);
+        warnings->emplace_back(buf);
+    }
+#endif
+    return nt;
+}
+
+int dwThreads(int requested, int n_conduits, std::vector* warnings) {
+    int nt = resolveRequested(requested, "dynamic wave", warnings);
+
+    // Model-size gate: step the team down until each thread keeps
+    // >= kMinConduitsPerThread conduits of momentum work. Applies to explicit
+    // requests too — a 16-thread team on 40 conduits is never useful.
+    if (nt > 1) {
+        int cap = n_conduits / kMinConduitsPerThread;
+        if (cap < 1) cap = 1;
+        if (cap < nt) {
+            if (requested > 0 && warnings) {
+                char buf[256];
+                std::snprintf(buf, sizeof buf,
+                    "THREADS = %d reduced to %d for dynamic wave: the model has "
+                    "only %d conduits (%d per thread minimum).",
+                    requested, cap, n_conduits, kMinConduitsPerThread);
+                warnings->emplace_back(buf);
+            }
+            nt = cap;
+        }
+    }
+
+    // Auto only: Apple Silicon performance-core clamp. With active waiting a
+    // team thread on an efficiency core turns every Picard barrier into a
+    // straggler wait (measured T=8 on 8P+2E: 204 s vs 57 s at T=4). Leave two
+    // P-cores for the OS / IO thread. Explicit requests bypass this and are
+    // warned by resolveRequested() instead.
+    if (requested == 0 && nt > 1) {
+        const int pcores = perfCores();
+        if (pcores > 2 && nt > pcores - 2) nt = pcores - 2;
+    }
+    return nt;
+}
+
+int twoDThreads(int requested, int n_triangles, std::vector* warnings) {
+    int nt = resolveRequested(requested, "2D surface", warnings);
+    // Auto only: the same Apple Silicon performance-core clamp dwThreads
+    // applies. The marcher forks 2·(2^K−1) parallel regions per macro cycle
+    // (30 at LTS_TIERS 4), and a team member on an efficiency core turns each
+    // barrier into a straggler wait. Leave two P-cores for the OS / IO thread.
+    if (requested == 0 && nt > 1) {
+        const int pcores = perfCores();
+        if (pcores > 2 && nt > pcores - 2) nt = pcores - 2;
+    }
+    if (n_triangles < 4 * nt) {
+        if (requested > 0 && nt > 1 && warnings) {
+            char buf[256];
+            std::snprintf(buf, sizeof buf,
+                "THREADS = %d reduced to 1 for the 2D surface: the mesh has only "
+                "%d triangles (need >= 4 per thread).",
+                requested, n_triangles);
+            warnings->emplace_back(buf);
+        }
+        nt = 1;
+    }
+    return nt;
+}
+
+} // namespace threadinfo
+} // namespace openswmm
diff --git a/src/engine/core/ThreadInfo.hpp b/src/engine/core/ThreadInfo.hpp
new file mode 100644
index 000000000..91ee0b1c0
--- /dev/null
+++ b/src/engine/core/ThreadInfo.hpp
@@ -0,0 +1,107 @@
+/**
+ * @file ThreadInfo.hpp
+ * @brief Process-wide hardware / OpenMP thread capability query.
+ *
+ * @details Single source of truth for "how many threads can this process
+ *          usefully run", shared by SWMMEngine::start (global OMP team),
+ *          DWSolver::setNumThreads (dynamic-wave Picard team),
+ *          SurfaceRouter2D (2D marcher) and the C API
+ *          swmm_get_thread_info(). See
+ *          plans/THREAD_LIMITS_AND_OVERSUBSCRIPTION_PLAN_2026-09-03.md.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+#ifndef OPENSWMM_CORE_THREADINFO_HPP
+#define OPENSWMM_CORE_THREADINFO_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+namespace threadinfo {
+
+/// Logical processors visible to the OS (SMT / hyper-threads included).
+/// std::thread::hardware_concurrency(); 0 when unknown.
+int logicalCpus();
+
+/// omp_get_max_threads() as seen by this process — the OpenMP runtime's
+/// default team size. Lower than logicalCpus() when OMP_NUM_THREADS,
+/// OMP_THREAD_LIMIT or a CPU-affinity mask limits the process. 1 when
+/// the engine is built without OpenMP.
+int ompMaxThreads();
+
+/// 1 when built with SWMM_USE_OPENMP, else 0.
+int ompAvailable();
+
+/// macOS: logical CPUs on the PERFORMANCE cluster (hw.perflevel0.logicalcpu);
+/// 0 on Intel Macs, other platforms, or sysctl failure.
+int perfCores();
+
+/// Threads the HOST application keeps busy alongside the engine
+/// (OPENSWMM_HOST_RESERVED_THREADS; 0 when unset or invalid). A GUI that
+/// runs the engine in-process sets it — its own event thread, a render
+/// thread, the engine IO thread — so that isOversubscribed() and the
+/// active spin-wait decision see the whole process, not just the team.
+int hostReservedThreads();
+
+/// Threads the Kokkos OpenMP 2D backend was initialised with in this
+/// process; 0 until the plugin initialises (or when no plugin is loaded).
+int kokkosOmpThreads();
+
+/// Recorded by the engine when it hands a thread count to the Kokkos plugin.
+void setKokkosOmpThreads(int n);
+
+/**
+ * @brief Resolve a [OPTIONS] THREADS request into a thread count.
+ *
+ * @details Rule (plan §2):
+ *   - requested == 0 → auto: ompMaxThreads(), callers then apply their own
+ *     heuristics (model-size gate, macOS P-core clamp).
+ *   - requested  > 0 → honoured exactly. Warnings are appended when it
+ *     exceeds logicalCpus() (oversubscription), exceeds ompMaxThreads()
+ *     (environment / affinity lowered the runtime limit), or, on macOS,
+ *     exceeds perfCores() (efficiency cores slow barrier-synchronised teams).
+ *
+ * @param requested  [OPTIONS] THREADS value.
+ * @param what       Short label for warning text ("OpenMP team", "dynamic wave", "2D").
+ * @param warnings   Sink for human-readable warnings; may be nullptr.
+ * @return           Thread count to request from the runtime (>= 1).
+ */
+int resolveRequested(int requested, const char* what,
+                     std::vector* warnings);
+
+/// True when @p threads plus hostReservedThreads() exceed the logical CPU
+/// count (the runtime would oversubscribe). Used to decide whether an active
+/// spin-wait policy is safe: a spinner waiting on a DESCHEDULED spinner
+/// turns every barrier into a scheduler-quantum stall.
+bool isOversubscribed(int threads);
+
+/// Minimum conduits of momentum work per dynamic-wave team thread before an
+/// extra thread pays for its barriers (PERFORMANCE-ONLY; bit-identical).
+constexpr int kMinConduitsPerThread = 100;
+
+/**
+ * @brief Dynamic-wave Picard team size for a THREADS request.
+ *
+ * @details resolveRequested(), then the model-size gate
+ *          (`n_conduits / kMinConduitsPerThread`, applied to explicit values
+ *          too — with a warning), then, for auto only, the macOS
+ *          performance-core clamp (`perfCores() - 2`). Does NOT consult
+ *          SWMM_DW_THREADS; the caller handles that override.
+ */
+int dwThreads(int requested, int n_conduits, std::vector* warnings);
+
+/**
+ * @brief 2D CPU-marcher team size for a THREADS request.
+ *
+ * @details resolveRequested(), then `n_triangles < 4 * nt → 1` (warned when
+ *          it reduces an explicit request).
+ */
+int twoDThreads(int requested, int n_triangles, std::vector* warnings);
+
+} // namespace threadinfo
+} // namespace openswmm
+
+#endif // OPENSWMM_CORE_THREADINFO_HPP
diff --git a/src/engine/core/TypeHelpers.hpp b/src/engine/core/TypeHelpers.hpp
index f317f193c..ce9dcac6c 100644
--- a/src/engine/core/TypeHelpers.hpp
+++ b/src/engine/core/TypeHelpers.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TypeHelpers.hpp
  * @brief Shared C↔internal type mapping utilities for node and link type enums.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TYPE_HELPERS_HPP
diff --git a/src/engine/core/UnitConversion.cpp b/src/engine/core/UnitConversion.cpp
index 0dc0264dc..402e4453a 100644
--- a/src/engine/core/UnitConversion.cpp
+++ b/src/engine/core/UnitConversion.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UnitConversion.cpp
  * @brief Global unit conversion — matching legacy SWMM UCF().
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "UnitConversion.hpp"
diff --git a/src/engine/core/UnitConversion.hpp b/src/engine/core/UnitConversion.hpp
index f741e6088..02be5cb9c 100644
--- a/src/engine/core/UnitConversion.hpp
+++ b/src/engine/core/UnitConversion.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UnitConversion.hpp
  * @brief Global unit conversion factors — matching legacy SWMM Ucf[]/Qcf[].
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_UNIT_CONVERSION_HPP
diff --git a/src/engine/core/UserFlags.hpp b/src/engine/core/UserFlags.hpp
index a9c9da0f2..db58ecd7e 100644
--- a/src/engine/core/UserFlags.hpp
+++ b/src/engine/core/UserFlags.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UserFlags.hpp
  * @brief User-defined model flags (InfoWorks ICM-style, two-section design).
@@ -37,7 +53,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_USER_FLAGS_HPP
diff --git a/src/engine/core/charconv_compat.hpp b/src/engine/core/charconv_compat.hpp
index c25aec8ae..707deaa6c 100644
--- a/src/engine/core/charconv_compat.hpp
+++ b/src/engine/core/charconv_compat.hpp
@@ -3,9 +3,14 @@
  * @brief Portable from_chars for floating-point types.
  *
  * @details Apple libc++ does not support std::from_chars for floating-point
- *          types.  This header provides a drop-in wrapper that uses std::strtod
+ *          types.  This header provides a drop-in wrapper that uses strtod
  *          as a fallback when the standard library lacks the feature.
  *
+ *          Every numeric token in every `.inp` section goes through here, so
+ *          the fallback is on the hottest path in the whole load sequence —
+ *          on a 500k-element model with geometry, parsing is ~80% of open().
+ *          See plans/MODEL_LOAD_INIT_OPTIMIZATION_PLAN_2026-08-12.md item 2.1.
+ *
  * @ingroup engine_core
  */
 
@@ -14,17 +19,53 @@
 
 #include 
 #include 
+#include 
 #include 
 #include 
 
+#if !defined(__cpp_lib_to_chars) || __cpp_lib_to_chars < 201611L
+// The fallback path is only compiled where float from_chars is missing, which
+// in practice means Apple libc++. strtod_l lives in  there and in
+//  on glibc; both provide newlocale/freelocale from POSIX.2008.
+#  define OPENSWMM_CHARCONV_FALLBACK 1
+#  include 
+#  if defined(__APPLE__)
+#    include 
+#  endif
+#endif
+
 namespace openswmm {
 
+#ifdef OPENSWMM_CHARCONV_FALLBACK
+namespace detail {
+
+/**
+ * @brief Process-wide "C" locale handle for strtod_l.
+ *
+ * @details Plain strtod consults the current global locale on every call to
+ *          find the decimal separator. Pinning the C locale removes that work
+ *          and, more importantly, makes the conversion locale-independent —
+ *          which is what std::from_chars guarantees on the platforms that take
+ *          the other branch. Without it a host running under a comma-decimal
+ *          locale would parse "0.013" as 0.
+ *
+ *          Constructed once on first use. If newlocale() fails the handle is
+ *          null and the call sites fall back to plain strtod.
+ */
+inline locale_t c_locale() noexcept {
+    static locale_t loc = newlocale(LC_NUMERIC_MASK, "C", nullptr);
+    return loc;
+}
+
+}  // namespace detail
+#endif
+
 /**
  * @brief Locale-independent parse of a double from a character range.
  *
  * On toolchains that support std::from_chars for doubles this forwards
- * directly; otherwise it falls back to std::strtod via a null-terminated
- * temporary copy.
+ * directly; otherwise it converts via strtod_l against a cached C locale,
+ * using a stack buffer for the null termination strtod requires.
  */
 inline std::from_chars_result from_chars_double(const char* first,
                                                 const char* last,
@@ -35,15 +76,38 @@ inline std::from_chars_result from_chars_double(const char* first,
     if (first == last) {
         return {first, std::errc::invalid_argument};
     }
-    // std::strtod needs a null-terminated string
-    std::string tmp(first, last);
-    char* end = nullptr;
-    double v = std::strtod(tmp.c_str(), &end);
-    if (end == tmp.c_str()) {
+
+    // strtod needs a null-terminated string. Numeric tokens in a .inp are
+    // short; a stack buffer keeps the common case free of any std::string
+    // construction at all. Anything longer than the buffer cannot be a
+    // meaningful double anyway, but is still handled correctly via the heap
+    // path rather than being truncated.
+    const std::size_t n = static_cast(last - first);
+    char        stack_buf[64];
+    std::string heap_buf;
+    const char* cstr = nullptr;
+    if (n < sizeof(stack_buf)) {
+        std::memcpy(stack_buf, first, n);
+        stack_buf[n] = '\0';
+        cstr = stack_buf;
+    } else {
+        heap_buf.assign(first, last);
+        cstr = heap_buf.c_str();
+    }
+
+    char*  end = nullptr;
+    double v   = 0.0;
+    if (const locale_t loc = detail::c_locale(); loc != nullptr) {
+        v = strtod_l(cstr, &end, loc);
+    } else {
+        v = std::strtod(cstr, &end);
+    }
+
+    if (end == cstr) {
         return {first, std::errc::invalid_argument};
     }
     value = v;
-    return {first + (end - tmp.c_str()), std::errc{}};
+    return {first + (end - cstr), std::errc{}};
 #endif
 }
 
diff --git a/src/engine/core/openswmm_api_common.hpp b/src/engine/core/openswmm_api_common.hpp
index 4c557438c..afbc66a23 100644
--- a/src/engine/core/openswmm_api_common.hpp
+++ b/src/engine/core/openswmm_api_common.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_api_common.hpp
  * @brief Internal shared helpers for C API impl files.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_API_COMMON_HPP
diff --git a/src/engine/core/openswmm_climate_impl.cpp b/src/engine/core/openswmm_climate_impl.cpp
index 6f585af7e..f888146da 100644
--- a/src/engine/core/openswmm_climate_impl.cpp
+++ b/src/engine/core/openswmm_climate_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_climate_impl.cpp
  * @brief C API implementation — climatology configuration get/set.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -291,6 +307,74 @@ SWMM_ENGINE_API int swmm_climate_set_wind_monthly(SWMM_Engine engine, const doub
     return copy_array_in(ctx.options.wind_speed, values, count, SWMM_CLIMATE_MONTHS);
 }
 
+// ============================================================================
+// Humidity  ([TEMPERATURE] HUMIDITY)
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_climate_get_humidity_type(SWMM_Engine engine, int* type) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    if (type) *type = ctx.options.humidity_type;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_climate_set_humidity_type(SWMM_Engine engine, int type) {
+    CHECK_HANDLE(engine);
+    if (type < 0 || type > 2) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    ctx.options.humidity_type = type;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_climate_get_humidity_variable(SWMM_Engine engine, int* var) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    if (var) *var = ctx.options.humidity_var;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_climate_set_humidity_variable(SWMM_Engine engine, int var) {
+    CHECK_HANDLE(engine);
+    if (var < 0 || var > 1) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    ctx.options.humidity_var = var;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_climate_get_humidity_monthly(SWMM_Engine engine, double* buf, int count) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    return copy_array_out(buf, count, ctx.options.humidity, SWMM_CLIMATE_MONTHS);
+}
+
+SWMM_ENGINE_API int swmm_climate_set_humidity_monthly(SWMM_Engine engine, const double* values, int count) {
+    CHECK_HANDLE(engine);
+    if (!values || count != SWMM_CLIMATE_MONTHS) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    return copy_array_in(ctx.options.humidity, values, count, SWMM_CLIMATE_MONTHS);
+}
+
+SWMM_ENGINE_API int swmm_climate_get_humidity_timeseries(SWMM_Engine engine, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    climate_fill_buf(buf, buflen, ctx.options.humidity_ts_name);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_climate_set_humidity_timeseries(SWMM_Engine engine, const char* ts_id) {
+    CHECK_HANDLE(engine);
+    if (!ts_id) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    ctx.options.humidity_ts_name = ts_id;
+    ctx.options.humidity_type = 2;  // TIMESERIES
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Snowmelt globals  ([TEMPERATURE] SNOWMELT)
 // ============================================================================
diff --git a/src/engine/core/openswmm_controls_impl.cpp b/src/engine/core/openswmm_controls_impl.cpp
index 247fb57c9..62daa1233 100644
--- a/src/engine/core/openswmm_controls_impl.cpp
+++ b/src/engine/core/openswmm_controls_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_controls_impl.cpp
  * @brief C API implementation — control rules and direct link control actions.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
diff --git a/src/engine/core/openswmm_datetime_impl.cpp b/src/engine/core/openswmm_datetime_impl.cpp
index 144ebac6b..49dbff14a 100644
--- a/src/engine/core/openswmm_datetime_impl.cpp
+++ b/src/engine/core/openswmm_datetime_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_datetime_impl.cpp
  * @brief C API implementation — SWMM DateTime encode/decode utilities.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DateTime.hpp"
diff --git a/src/engine/core/openswmm_edit_impl.cpp b/src/engine/core/openswmm_edit_impl.cpp
index c2b544d71..dbeb6a898 100644
--- a/src/engine/core/openswmm_edit_impl.cpp
+++ b/src/engine/core/openswmm_edit_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_edit_impl.cpp
  * @brief C API implementation — object deletion and type conversion.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -19,6 +35,7 @@
 
 #include 
 #include 
+#include 
 
 // ============================================================================
 // Internal helpers — convert C++ results to C structs
@@ -340,6 +357,52 @@ SWMM_ENGINE_API int swmm_gage_delete(SWMM_Engine engine, int idx,
     return SWMM_OK;
 }
 
+// ---------------------------------------------------------------------------
+// Batch deletes (perf plan Phase A1) — equivalent to sequential descending
+// per-object deletes with ONE name-index rebuild per batch.  Every index is
+// validated BEFORE any mutation so the call is all-or-nothing.
+// ---------------------------------------------------------------------------
+
+#define SWMM_DELETE_MANY_BODY(COUNT_EXPR, MANY_FN)                             \
+    CHECK_HANDLE(engine);                                                      \
+    auto& ctx = to_engine(engine)->context();                                  \
+    CHECK_EDITABLE(ctx);                                                       \
+    if (n <= 0) { cascade_to_c(openswmm::edit::CascadeResult{}, cascade_out);  \
+                  return SWMM_OK; }                                            \
+    if (!indices) return SWMM_ERR_BADPARAM;                                    \
+    for (int k = 0; k < n; ++k)                                                \
+        CHECK_INDEX(indices[k] >= 0 && indices[k] < (COUNT_EXPR));             \
+    auto res = openswmm::edit::MANY_FN(ctx,                                    \
+                                       std::vector(indices, indices + n));\
+    cascade_to_c(res, cascade_out);                                            \
+    return SWMM_OK
+
+SWMM_ENGINE_API int swmm_node_delete_many(SWMM_Engine engine,
+                                          const int* indices, int n,
+                                          SWMM_ImpactReport* cascade_out) {
+    SWMM_DELETE_MANY_BODY(ctx.n_nodes(), delete_nodes_many);
+}
+
+SWMM_ENGINE_API int swmm_link_delete_many(SWMM_Engine engine,
+                                          const int* indices, int n,
+                                          SWMM_ImpactReport* cascade_out) {
+    SWMM_DELETE_MANY_BODY(ctx.n_links(), delete_links_many);
+}
+
+SWMM_ENGINE_API int swmm_subcatch_delete_many(SWMM_Engine engine,
+                                              const int* indices, int n,
+                                              SWMM_ImpactReport* cascade_out) {
+    SWMM_DELETE_MANY_BODY(ctx.n_subcatches(), delete_subcatches_many);
+}
+
+SWMM_ENGINE_API int swmm_gage_delete_many(SWMM_Engine engine,
+                                          const int* indices, int n,
+                                          SWMM_ImpactReport* cascade_out) {
+    SWMM_DELETE_MANY_BODY(ctx.n_gages(), delete_gages_many);
+}
+
+#undef SWMM_DELETE_MANY_BODY
+
 SWMM_ENGINE_API int swmm_table_delete(SWMM_Engine engine, int idx,
                                        SWMM_ImpactReport* cascade_out) {
     CHECK_HANDLE(engine);
@@ -539,4 +602,53 @@ SWMM_ENGINE_API int swmm_virtual_junction_fuse(SWMM_Engine engine, int node_idx,
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_conduit_split_inlet(SWMM_Engine engine, int link_idx, double t,
+                                             const char* new_node_name,
+                                             const char* new_link_name,
+                                             const char* inlet_id,
+                                             const char* capture_node,
+                                             int* new_node_idx, int* new_link_idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(link_idx >= 0 && link_idx < ctx.n_links());
+    if (!new_node_name || !new_link_name || !inlet_id || !capture_node)
+        return SWMM_ERR_BADPARAM;
+
+    // Inlet designs have no NameIndex — swmm_inlet_index scans with ieq.
+    int design = -1;
+    for (int i = 0; i < ctx.inlets.count(); ++i)
+        if (openswmm::ieq(ctx.inlets.names[static_cast(i)], inlet_id)) {
+            design = i;
+            break;
+        }
+    const int capture = ctx.node_names.find(capture_node);
+
+    const auto res = openswmm::edit::ij_split_conduit(
+        ctx, link_idx, t, new_node_name, new_link_name, design, capture);
+    if (res.err != 0) {
+        // -1 is the split's own rejection (bad t / duplicate or empty name /
+        // non-conduit); everything else is a distinct rule code.
+        return (res.err == -1) ? SWMM_ERR_BADPARAM : res.err;
+    }
+    if (new_node_idx) *new_node_idx = res.new_node_idx;
+    if (new_link_idx) *new_link_idx = res.new_link_idx;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_junction_fuse(SWMM_Engine engine, int node_idx,
+                                             int* surviving_link_idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(node_idx >= 0 && node_idx < ctx.n_nodes());
+
+    int surviving = -1;
+    const int code = openswmm::edit::ij_fuse(ctx, node_idx, &surviving);
+    if (code == -1) return SWMM_ERR_BADPARAM;   // not an inlet junction
+    if (code != 0)  return code;                // ERR_VJ_LINK_COUNT
+    if (surviving_link_idx) *surviving_link_idx = surviving;
+    return SWMM_OK;
+}
+
 } // extern "C"
diff --git a/src/engine/core/openswmm_engine_impl.cpp b/src/engine/core/openswmm_engine_impl.cpp
index 03abb20cb..cb990fc02 100644
--- a/src/engine/core/openswmm_engine_impl.cpp
+++ b/src/engine/core/openswmm_engine_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_engine_impl.cpp
  * @brief C API implementation — engine lifecycle, callbacks, errors, timing.
@@ -7,10 +23,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
+#include "ThreadInfo.hpp"
+#include "../transport/TransportPolicy.hpp"   // E2: swmm_get_transport_matrix
+
+#include 
 
 extern "C" {
 
@@ -235,6 +255,87 @@ SWMM_ENGINE_API const char* swmm_get_warning_at(SWMM_Engine engine, int index) {
     return warns[static_cast(index)].c_str();
 }
 
+// ============================================================================
+// Thread capability query
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_get_thread_info(SWMM_ThreadInfo* out) {
+    if (!out) return SWMM_ERR_BADPARAM;
+    namespace ti = openswmm::threadinfo;
+    out->logical_cpus       = ti::logicalCpus();
+    out->omp_max_threads    = ti::ompMaxThreads();
+    out->omp_available      = ti::ompAvailable();
+    out->perf_cores         = ti::perfCores();
+    out->kokkos_omp_threads = ti::kokkosOmpThreads();
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_get_effective_threads(SWMM_Engine engine, int threads_option,
+                                               int* global_threads, int* dw_threads,
+                                               int* twod_threads) {
+    if (!engine) return SWMM_ERR_BADPARAM;
+    namespace ti = openswmm::threadinfo;
+    const auto& ctx = to_engine(engine)->context();
+
+    if (global_threads)
+        *global_threads = ti::resolveRequested(threads_option, "OpenMP team", nullptr);
+
+    if (dw_threads) {
+        *dw_threads = 0;
+        if (ctx.options.routing_model == openswmm::RoutingModel::DYNWAVE) {
+            int n_conduits = 0;
+            for (const auto t : ctx.links.type)
+                if (t == openswmm::LinkType::CONDUIT) ++n_conduits;
+            *dw_threads = ti::dwThreads(threads_option, n_conduits, nullptr);
+        }
+    }
+
+    if (twod_threads) {
+        *twod_threads = 0;
+#ifdef OPENSWMM_HAS_2D
+        const int n_tri = to_engine(engine)->surfaceRouter2D().mesh().n_triangles();
+        if (n_tri > 0 && !ctx.options.ignore_2d)
+            *twod_threads = ti::twoDThreads(threads_option, n_tri, nullptr);
+#endif
+    }
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// E2 — transport matrix
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_get_transport_matrix(SWMM_Engine engine,
+                                              SWMM_TransportMatrix* out) {
+    if (!engine || !out) return SWMM_ERR_BADPARAM;
+    namespace tp = openswmm::transport;
+    const tp::Matrix m = tp::resolve(to_engine(engine)->context());
+    std::memset(out, 0, sizeof(*out));
+    for (int d = 0; d < SWMM_TRANSPORT_DOMAIN_COUNT; ++d) {
+        for (int c = 0; c < SWMM_TRANSPORT_CLASS_COUNT; ++c) {
+            const tp::Cell& src = m.cells[d][c];
+            SWMM_TransportCell& dst = out->cell[d][c];
+            dst.state = static_cast(src.state);
+            dst.count = src.count;
+            std::strncpy(dst.reason, src.reason.c_str(), sizeof(dst.reason) - 1);
+            dst.reason[sizeof(dst.reason) - 1] = '\0';
+        }
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API const char* swmm_transport_domain_name(int domain) {
+    if (domain < 0 || domain >= SWMM_TRANSPORT_DOMAIN_COUNT) return "";
+    return openswmm::transport::domainName(
+        static_cast(domain));
+}
+
+SWMM_ENGINE_API const char* swmm_transport_class_name(int species_class) {
+    if (species_class < 0 || species_class >= SWMM_TRANSPORT_CLASS_COUNT) return "";
+    return openswmm::transport::speciesClassName(
+        static_cast(species_class));
+}
+
 SWMM_ENGINE_API const char* swmm_error_message(int code) {
     switch (code) {
         case SWMM_OK:            return "Success";
@@ -258,9 +359,17 @@ SWMM_ENGINE_API const char* swmm_error_message(int code) {
         case 611: return "Virtual junction connects conduits with different cross sections";
         case 613: return "Virtual junction has a conduit with a nonzero offset";
         case 615: return "Virtual junction conduit inverts do not agree at the node";
-        case 617: return "Virtual junction cannot receive lateral inflow";
-        case 619: return "Virtual junctions require DYNWAVE flow routing";
+        case 617: return "Virtual junction cannot be coupled to a 2D surface mesh";
+        case 619: return "Virtual junctions require DYNWAVE or FV flow routing";
         case 621: return "Too many items for virtual junction";
+        // Inlet-junction rule codes (ErrorCodes.hpp ERR_IJ_* / ERR_INLET_*)
+        case 623: return "Inlet junction must connect two STREET conduits (RECT_OPEN or TRAPEZOIDAL for drop inlets)";
+        case 625: return "Inlet junction references an unknown inlet design";
+        case 627: return "Inlet junction has an invalid capture node (missing, itself, or virtual)";
+        case 629: return "Inlet junction conduit also carries an inlet usage entry";
+        case 631: return "Too many items for inlet junction";
+        case 633: return "Inlet junction has no inlet design assigned";
+        case 635: return "Inlet cannot be used with the cross section of its host";
         default:                 return "Unknown error";
     }
 }
diff --git a/src/engine/core/openswmm_forcing_impl.cpp b/src/engine/core/openswmm_forcing_impl.cpp
index c1885cb3e..311ab7a26 100644
--- a/src/engine/core/openswmm_forcing_impl.cpp
+++ b/src/engine/core/openswmm_forcing_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_forcing_impl.cpp
  * @brief C API implementation — runtime forcing with mass-balance tracking.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -89,6 +105,40 @@ SWMM_ENGINE_API int swmm_forcing_node_quality(
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_forcing_node_temperature(
+    SWMM_Engine engine, int node_idx, double value, int mode, int persist)
+{
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_RUNNING(ctx);
+    CHECK_INDEX(node_idx >= 0 && node_idx < ctx.n_nodes());
+    if (!valid_mode(mode) || !valid_persist(persist)) return SWMM_ERR_BADPARAM;
+    if (!ctx.options.heat_transport) return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(node_idx);
+    if (u >= ctx.forcing.node_temperature_mode.size()) return SWMM_ERR_BADINDEX;
+    ctx.forcing.node_temperature_mode[u]    = static_cast(mode);
+    ctx.forcing.node_temperature_value[u]   = value;
+    ctx.forcing.node_temperature_persist[u] = static_cast(persist);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_forcing_node_age(
+    SWMM_Engine engine, int node_idx, double value, int mode, int persist)
+{
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_RUNNING(ctx);
+    CHECK_INDEX(node_idx >= 0 && node_idx < ctx.n_nodes());
+    if (!valid_mode(mode) || !valid_persist(persist)) return SWMM_ERR_BADPARAM;
+    if (!ctx.options.water_age) return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(node_idx);
+    if (u >= ctx.forcing.node_age_mode.size()) return SWMM_ERR_BADINDEX;
+    ctx.forcing.node_age_mode[u]    = static_cast(mode);
+    ctx.forcing.node_age_value[u]   = value;
+    ctx.forcing.node_age_persist[u] = static_cast(persist);
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Link forcing
 // ============================================================================
@@ -125,6 +175,22 @@ SWMM_ENGINE_API int swmm_forcing_link_setting(
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_forcing_link_seepage(
+    SWMM_Engine engine, int idx, double value, int mode, int persist)
+{
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_RUNNING(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
+    if (!valid_mode(mode) || !valid_persist(persist)) return SWMM_ERR_BADPARAM;
+
+    auto ui = static_cast(idx);
+    ctx.forcing.link_seepage_mode[ui]    = static_cast(mode);
+    ctx.forcing.link_seepage_value[ui]   = value;
+    ctx.forcing.link_seepage_persist[ui] = static_cast(persist);
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Subcatchment forcing
 // ============================================================================
@@ -342,6 +408,68 @@ SWMM_ENGINE_API int swmm_forcing_gage_rainfall(
 // Clear forcing
 // ============================================================================
 
+/* ---- PE4: per-element climate ------------------------------------------ */
+
+namespace {
+
+/// The channel a variable id selects, or nullptr. One lookup shared by the
+/// setter, the getter and the targeted clear, so the three cannot disagree
+/// about which enum value means which array.
+openswmm::ForcingData::ElemClimateChannel* elem_channel(
+    openswmm::ForcingData& f, int variable, int slot) {
+    switch (variable) {
+        case SWMM_FORCE_ELEM_AIR_TEMPERATURE: return &f.elem_air_temp[slot];
+        case SWMM_FORCE_ELEM_HUMIDITY:        return &f.elem_humidity[slot];
+        case SWMM_FORCE_ELEM_WIND_SPEED:      return &f.elem_wind[slot];
+        case SWMM_FORCE_ELEM_SHORTWAVE:       return &f.elem_shortwave[slot];
+        default: return nullptr;
+    }
+}
+
+/// Element count for a kind, or -1 when the kind carries no per-element
+/// climate. SUBCATCH is absent BY DESIGN: a subcatchment's air temperature
+/// has competing consumers (snowmelt, evaporation), so honouring it here
+/// would silently make the snowpack and the conduit disagree about the
+/// atmosphere. See the header.
+int elem_count(const openswmm::SimulationContext& ctx, int kind) {
+    if (kind == SWMM_HEAT_ELEM_LINK) return ctx.n_links();
+    if (kind == SWMM_HEAT_ELEM_NODE) return ctx.n_nodes();
+    return -1;
+}
+
+int elem_slot(int kind) {
+    return (kind == SWMM_HEAT_ELEM_LINK) ? 0
+         : (kind == SWMM_HEAT_ELEM_NODE) ? 1 : -1;
+}
+
+/// User units → the internal units the flux evaluators read. Mirrors the
+/// system-wide setters exactly: an ADD delta in degC is 1.8 degF with NO
+/// offset, which is the trap the global path already documents.
+double to_internal(const openswmm::SimulationContext& ctx, int variable,
+                   double v, int mode) {
+    const int us = openswmm::ucf::getUnitSystem(
+        static_cast(ctx.options.flow_units));
+    if (us != 1) return v;                       // US: already internal
+    if (variable == SWMM_FORCE_ELEM_AIR_TEMPERATURE)
+        return (mode == SWMM_FORCING_ADD) ? v * 1.8 : v * 1.8 + 32.0;
+    if (variable == SWMM_FORCE_ELEM_WIND_SPEED)
+        return v / 1.609344;                     // km/hr -> mph
+    return v;                                    // % and W/m2 are unitless-ish
+}
+
+double from_internal(const openswmm::SimulationContext& ctx, int variable,
+                     double v, int mode) {
+    const int us = openswmm::ucf::getUnitSystem(
+        static_cast(ctx.options.flow_units));
+    if (us != 1) return v;
+    if (variable == SWMM_FORCE_ELEM_AIR_TEMPERATURE)
+        return (mode == SWMM_FORCING_ADD) ? v / 1.8 : (v - 32.0) * 5.0 / 9.0;
+    if (variable == SWMM_FORCE_ELEM_WIND_SPEED) return v * 1.609344;
+    return v;
+}
+
+}  // namespace
+
 SWMM_ENGINE_API int swmm_forcing_clear(SWMM_Engine engine, int type, int idx) {
     CHECK_HANDLE(engine);
     auto& ctx = to_engine(engine)->context();
@@ -374,6 +502,10 @@ SWMM_ENGINE_API int swmm_forcing_clear(SWMM_Engine engine, int type, int idx) {
             CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
             ctx.forcing.link_setting_mode[static_cast(idx)] = openswmm::ForcingMode::NONE;
             break;
+        case SWMM_FORCE_LINK_SEEPAGE:          // G-X4
+            CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
+            ctx.forcing.link_seepage_mode[static_cast(idx)] = openswmm::ForcingMode::NONE;
+            break;
         case SWMM_FORCE_SUBCATCH_RAINFALL:
             CHECK_INDEX(idx >= 0 && idx < ctx.n_subcatches());
             ctx.forcing.subcatch_rainfall_mode[static_cast(idx)] = openswmm::ForcingMode::NONE;
@@ -410,12 +542,85 @@ SWMM_ENGINE_API int swmm_forcing_clear(SWMM_Engine engine, int type, int idx) {
             }
             break;
         }
+        case SWMM_FORCE_ELEM_AIR_TEMPERATURE:
+        case SWMM_FORCE_ELEM_HUMIDITY:
+        case SWMM_FORCE_ELEM_WIND_SPEED:
+        case SWMM_FORCE_ELEM_SHORTWAVE: {
+            // PE4: `idx` alone cannot say which KIND, so a targeted clear
+            // clears that index in BOTH kinds. Clearing something already
+            // clear is a no-op, and the alternative — a separate clear entry
+            // per kind — would double this enum for no gain.
+            for (int slot = 0; slot < 2; ++slot) {
+                auto* ch = elem_channel(ctx.forcing, type, slot);
+                if (ch == nullptr) continue;
+                const auto u = static_cast(idx);
+                if (idx >= 0 && u < ch->mode.size())
+                    ch->mode[u] = openswmm::ForcingMode::NONE;
+            }
+            break;
+        }
         default:
             return SWMM_ERR_BADPARAM;
     }
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_forcing_element_climate(
+    SWMM_Engine engine, int kind, int index, int variable, double value,
+    int mode, int persist) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    const int slot = elem_slot(kind);
+    const int n    = elem_count(ctx, kind);
+    if (slot < 0 || n < 0) return SWMM_ERR_BADPARAM;
+    CHECK_INDEX(index >= 0 && index < n);
+    if (mode != SWMM_FORCING_OVERRIDE && mode != SWMM_FORCING_ADD)
+        return SWMM_ERR_BADPARAM;
+    if (persist != SWMM_FORCING_RESET && persist != SWMM_FORCING_PERSIST)
+        return SWMM_ERR_BADPARAM;
+    auto* ch = elem_channel(ctx.forcing, variable, slot);
+    if (ch == nullptr) return SWMM_ERR_BADPARAM;
+
+    // Sized lazily (D-PE2): a model that never calls this allocates nothing
+    // and pays one `.empty()` check per flux evaluation.
+    ch->ensure(static_cast(n));
+    const auto u = static_cast(index);
+    ch->mode[u]    = (mode == SWMM_FORCING_ADD)
+                         ? openswmm::ForcingMode::ADD
+                         : openswmm::ForcingMode::OVERRIDE;
+    ch->value[u]   = to_internal(ctx, variable, value, mode);
+    ch->persist[u] = (persist == SWMM_FORCING_PERSIST)
+                         ? openswmm::ForcingPersist::PERSIST
+                         : openswmm::ForcingPersist::RESET;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_forcing_element_climate_get(
+    SWMM_Engine engine, int kind, int index, int variable, double* value,
+    int* mode) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    const int slot = elem_slot(kind);
+    const int n    = elem_count(ctx, kind);
+    if (slot < 0 || n < 0) return SWMM_ERR_BADPARAM;
+    CHECK_INDEX(index >= 0 && index < n);
+    auto* ch = elem_channel(ctx.forcing, variable, slot);
+    if (ch == nullptr) return SWMM_ERR_BADPARAM;
+
+    const auto u = static_cast(index);
+    if (u >= ch->mode.size() ||
+        ch->mode[u] == openswmm::ForcingMode::NONE) {
+        if (mode)  *mode  = SWMM_FORCING_NONE;
+        if (value) *value = 0.0;
+        return SWMM_OK;
+    }
+    const int m = (ch->mode[u] == openswmm::ForcingMode::ADD)
+                      ? SWMM_FORCING_ADD : SWMM_FORCING_OVERRIDE;
+    if (mode)  *mode  = m;
+    if (value) *value = from_internal(ctx, variable, ch->value[u], m);
+    return SWMM_OK;
+}
+
 SWMM_ENGINE_API int swmm_forcing_clear_all(SWMM_Engine engine) {
     CHECK_HANDLE(engine);
     to_engine(engine)->context().forcing.clear_all();
diff --git a/src/engine/core/openswmm_gages_impl.cpp b/src/engine/core/openswmm_gages_impl.cpp
index ecedb3e64..daf90cf62 100644
--- a/src/engine/core/openswmm_gages_impl.cpp
+++ b/src/engine/core/openswmm_gages_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_gages_impl.cpp
  * @brief C API implementation — rain gage identity, creation, properties, state, bulk.
@@ -7,12 +23,15 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
 #include "../../../include/openswmm/engine/openswmm_gages.h"
 
+#include "../hydrology/Gage.hpp"
+#include "../input/PostParseResolver.hpp"
+
 extern "C" {
 
 // ============================================================================
@@ -118,7 +137,15 @@ SWMM_ENGINE_API int swmm_gage_set_filename(SWMM_Engine engine, int idx, const ch
     // station_id (not the CSV column-name slot used by the "path:col" form).
     ctx.gages.file_path[uidx]   = path;
     ctx.gages.station_id[uidx]  = station_id ? station_id : "";
-    ctx.gages.file_format[uidx] = openswmm::RainFileFormat::STAN_PRCP;
+    // B1 fix: do NOT unconditionally force STAN_PRCP — that destroyed a
+    // USER_CSV gage's column binding when the GUI edited the path. Preserve
+    // an existing USER_CSV format; otherwise auto-detect (a non-empty
+    // col_name implies the multi-column "path:col" form).
+    if (ctx.gages.file_format[uidx] != openswmm::RainFileFormat::USER_CSV) {
+        ctx.gages.file_format[uidx] = !ctx.gages.col_name[uidx].empty()
+                                        ? openswmm::RainFileFormat::USER_CSV
+                                        : openswmm::RainFileFormat::STAN_PRCP;
+    }
     ctx.gages.source[uidx]      = openswmm::RainSource::FILE_RAIN;
     return SWMM_OK;
 }
@@ -129,8 +156,49 @@ SWMM_ENGINE_API int swmm_gage_set_station_id(SWMM_Engine engine, int idx, const
     CHECK_GEOMETRY(ctx);
     CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
     auto uidx = static_cast(idx);
+    // B1 fix: only the station id changes here. Forcing file_format to
+    // STAN_PRCP silently corrupted USER_CSV gages when a host edited the
+    // Station ID field.
     ctx.gages.station_id[uidx]  = station_id ? station_id : "";
-    ctx.gages.file_format[uidx] = openswmm::RainFileFormat::STAN_PRCP;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gage_set_file_column(SWMM_Engine engine, int idx, const char* column) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+    auto uidx = static_cast(idx);
+    ctx.gages.col_name[uidx] = column ? column : "";
+    // A named column only exists in the multi-column "path:col" form, so a
+    // non-empty selector implies USER_CSV. Clearing it leaves the format
+    // alone: an empty column on a USER_CSV gage means "first data column".
+    if (!ctx.gages.col_name[uidx].empty())
+        ctx.gages.file_format[uidx] = openswmm::RainFileFormat::USER_CSV;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gage_set_file_format(SWMM_Engine engine, int idx, int format) {
+    CHECK_HANDLE(engine);
+    // Validate against RainFileFormat (GageData.hpp): UNKNOWN(-1)..USER_CSV(6).
+    if (format < static_cast(openswmm::RainFileFormat::UNKNOWN) ||
+        format > static_cast(openswmm::RainFileFormat::USER_CSV))
+        return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+    auto uidx = static_cast(idx);
+    const auto fmt = static_cast(format);
+    ctx.gages.file_format[uidx] = fmt;
+    // The row selectors are mutually exclusive — a standard rain file picks
+    // rows by station id and has no columns; a multi-column file picks a
+    // column and has no station column. Clearing the inapplicable one keeps
+    // the gage in a state InpWriter can express, and gives a host an explicit
+    // way OUT of USER_CSV (set_filename/set_file_column both preserve it).
+    if (fmt == openswmm::RainFileFormat::USER_CSV)
+        ctx.gages.station_id[uidx].clear();
+    else
+        ctx.gages.col_name[uidx].clear();
     return SWMM_OK;
 }
 
@@ -243,6 +311,24 @@ SWMM_ENGINE_API int swmm_gage_get_station_id(SWMM_Engine engine, int idx, char*
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_gage_get_file_column(SWMM_Engine engine, int idx, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+    gage_fill_buf(buf, buflen, ctx.gages.col_name[static_cast(idx)]);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gage_get_file_format(SWMM_Engine engine, int idx, int* format) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+    if (format)
+        *format = static_cast(ctx.gages.file_format[static_cast(idx)]);
+    return SWMM_OK;
+}
+
 SWMM_ENGINE_API int swmm_gage_get_rain_units(SWMM_Engine engine, int idx, int* units) {
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
@@ -294,4 +380,61 @@ SWMM_ENGINE_API int swmm_gage_rename(SWMM_Engine engine, int idx, const char* ne
     return ctx.gage_names.rename(idx, newId) ? SWMM_OK : SWMM_ERR_BADPARAM;
 }
 
+// ============================================================================
+// Resolved rainfall series
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_gage_get_rainfall_series_count(SWMM_Engine engine, int idx,
+                                                        int* count) {
+    CHECK_HANDLE(engine);
+    if (!count) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+
+    const openswmm::Table* tbl = openswmm::gage::gageRainSeries(ctx, idx);
+    *count = tbl ? static_cast(tbl->x.size()) : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gage_get_rainfall_series(SWMM_Engine engine, int idx,
+                                                  double* times, double* values,
+                                                  int count) {
+    CHECK_HANDLE(engine);
+    if (count < 0) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_gages());
+
+    const openswmm::Table* tbl = openswmm::gage::gageRainSeries(ctx, idx);
+    if (!tbl) return SWMM_OK;   // no series: nothing to write, not an error
+
+    const auto ug = static_cast(idx);
+    const int  rain_type    = ctx.gages.rain_type[ug];
+    const double interval   = ctx.gages.interval_sec[ug];
+    const double units_fac  = openswmm::gage::gageUnitsFactor(ctx, idx);
+    const double scale_fac  = ctx.gages.scale_factor[ug];
+
+    // The CUMULATIVE accumulator is stateful across entries, so the series must
+    // be walked in order from a fresh accumulator — reusing the live one would
+    // both corrupt the run and make this call order-dependent.
+    double cumul_accum = 0.0;
+
+    const int n = std::min(count, static_cast(tbl->x.size()));
+    for (int k = 0; k < n; ++k) {
+        const auto uk = static_cast(k);
+        if (times) times[k] = tbl->x[uk];
+        const double v = openswmm::gage::convertGageValue(
+            tbl->y[uk], rain_type, interval, cumul_accum, units_fac, scale_fac);
+        if (values) values[k] = v;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gage_reload_rain_files(SWMM_Engine engine) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    openswmm::input::load_external_rain_files(ctx);
+    return SWMM_OK;
+}
+
 } /* extern "C" */
diff --git a/src/engine/core/openswmm_heat_impl.cpp b/src/engine/core/openswmm_heat_impl.cpp
new file mode 100644
index 000000000..56735f6c1
--- /dev/null
+++ b/src/engine/core/openswmm_heat_impl.cpp
@@ -0,0 +1,611 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_heat_impl.cpp
+ * @brief Heat-configuration C API (phase H6a).
+ *
+ * @details Every setter here enforces the SAME range rule the `model.heat`
+ *          parser does, and enforces it the same way: **refuse, do not
+ *          clamp**. Two entry points into one configuration that disagree
+ *          about what is legal is how a deck and a GUI come to describe
+ *          different models, and the parser's rule is the older one.
+ *
+ * @see include/openswmm/engine/openswmm_heat.h
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §5
+ */
+
+#include "openswmm_api_common.hpp"
+#include "../../../include/openswmm/engine/openswmm_heat.h"
+
+namespace {
+
+using openswmm::HeatConfigData;
+using openswmm::HeatSource;
+using openswmm::ShortwaveMode;
+
+/// The parser's own range (`HeatComponent.cpp` kMinTemp/kMaxTemp, used by
+/// `parse_celsius`). Duplicated as a literal here rather than shared,
+/// because the constants are file-local to the component and hoisting them
+/// into a header is a wider change than this round earns — but they MUST
+/// agree: a value the deck refuses and the API accepts is exactly the
+/// deck/API disagreement the refuse-don't-clamp rule exists to prevent.
+/// A gate pins the two together.
+constexpr double kApiMinTempC = -50.0;
+constexpr double kApiMaxTempC = 100.0;
+
+bool temp_ok(double c) { return c >= kApiMinTempC && c <= kApiMaxTempC; }
+
+/// Copy a bound-series name out, NUL-terminated and truncated to the
+/// caller's buffer — the `climate_fill_buf` convention, one API over.
+/// An out-of-range index (no binding, or a table list that shrank) is "".
+void ts_name_out(const openswmm::SimulationContext& ctx, int ts_index,
+                 char* buf, int buflen) {
+    std::string name;
+    if (ts_index >= 0 && ts_index < static_cast(ctx.tables.count()))
+        name = ctx.tables[ts_index].id;
+    const auto n = std::min(static_cast(buflen - 1), name.size());
+    std::memcpy(buf, name.data(), n);
+    buf[n] = '\0';
+}
+
+/// Sources that accept a NODE-scope override in H1 (HeatComponent.cpp's
+/// rule: "NODE scope applies to DWF and EXTERNAL_INFLOW in H1").
+bool node_scope_ok(int src) {
+    return src == static_cast(HeatSource::DWF) ||
+           src == static_cast(HeatSource::EXTERNAL_INFLOW);
+}
+
+bool source_ok(int src) {
+    return src >= 0 && src < static_cast(HeatSource::COUNT_);
+}
+
+/// Fraction guard, shared by every [0,1] parameter below.
+bool frac_ok(double v) { return v >= 0.0 && v <= 1.0; }
+
+}  // namespace
+
+// ===========================================================================
+// Toggles
+// ===========================================================================
+
+SWMM_ENGINE_API int swmm_heat_get_enabled(SWMM_Engine engine, int* enabled) {
+    CHECK_HANDLE(engine);
+    if (enabled == nullptr) return SWMM_ERR_BADPARAM;
+    *enabled = to_engine(engine)->context().options.heat_transport ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_module(SWMM_Engine engine, int module,
+                                         int* on) {
+    CHECK_HANDLE(engine);
+    if (on == nullptr) return SWMM_ERR_BADPARAM;
+    const auto& cfg = to_engine(engine)->context().heat_config;
+    switch (module) {
+        case SWMM_HEAT_SURFACE_EXCHANGE:   *on = cfg.surface_exchange ? 1 : 0;
+                                           return SWMM_OK;
+        case SWMM_HEAT_RADIATIVE_EXCHANGE: *on = cfg.radiative_exchange ? 1 : 0;
+                                           return SWMM_OK;
+        case SWMM_HEAT_LAYER_CONDUCTION:   *on = cfg.layer_conduction ? 1 : 0;
+                                           return SWMM_OK;
+        default:                           return SWMM_ERR_BADINDEX;
+    }
+}
+
+SWMM_ENGINE_API int swmm_heat_set_module(SWMM_Engine engine, int module,
+                                         int on) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    const bool b = (on != 0);
+    switch (module) {
+        case SWMM_HEAT_SURFACE_EXCHANGE:   cfg.surface_exchange   = b; break;
+        case SWMM_HEAT_RADIATIVE_EXCHANGE: cfg.radiative_exchange = b; break;
+        case SWMM_HEAT_LAYER_CONDUCTION:   cfg.layer_conduction   = b; break;
+        default:                           return SWMM_ERR_BADINDEX;
+    }
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+// ===========================================================================
+// [RADIATIVE_FLUXES]
+// ===========================================================================
+
+SWMM_ENGINE_API int swmm_heat_get_radiative(SWMM_Engine engine, int param,
+                                            double* value) {
+    CHECK_HANDLE(engine);
+    if (value == nullptr) return SWMM_ERR_BADPARAM;
+    const auto& rc = to_engine(engine)->context().heat_config.radiative;
+    switch (param) {
+        case SWMM_HEAT_RAD_SHORTWAVE:       *value = rc.shortwave_wm2;   break;
+        case SWMM_HEAT_RAD_ALBEDO:          *value = rc.albedo;          break;
+        case SWMM_HEAT_RAD_SHADE_FACTOR:    *value = rc.shade_factor;    break;
+        case SWMM_HEAT_RAD_SKY_VIEW:        *value = rc.sky_view;        break;
+        case SWMM_HEAT_RAD_EMISS_WATER:     *value = rc.emiss_water;     break;
+        case SWMM_HEAT_RAD_EMISS_LANDCOVER: *value = rc.emiss_landcover; break;
+        case SWMM_HEAT_RAD_ATM_EMISS_COEFF: *value = rc.atm_emiss_coeff; break;
+        case SWMM_HEAT_RAD_LW_REFLECTION:   *value = rc.lw_reflection;   break;
+        default:                            return SWMM_ERR_BADINDEX;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_radiative(SWMM_Engine engine, int param,
+                                            double value) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    auto& rc  = cfg.radiative;
+    switch (param) {
+        case SWMM_HEAT_RAD_SHORTWAVE:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            // A constant only means anything in CONSTANT mode. Silently
+            // accepting it under TIMESERIES/COMPUTED would store a number
+            // nothing reads — the bypass lessons 10/20 name.
+            //
+            // BOTH checks run BEFORE the assignment. Written the other way
+            // round this refused the call and kept the write, which is the
+            // half-apply `applyHeatSections` guards against at the end of
+            // every parse — an API that errors and mutates anyway is worse
+            // than one that only errors.
+            if (rc.sw_mode != ShortwaveMode::CONSTANT) return SWMM_ERR_BADPARAM;
+            rc.shortwave_wm2 = value;
+            break;
+        case SWMM_HEAT_RAD_ALBEDO:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.albedo = value; break;
+        case SWMM_HEAT_RAD_SHADE_FACTOR:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.shade_factor = value; break;
+        case SWMM_HEAT_RAD_SKY_VIEW:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.sky_view = value; break;
+        case SWMM_HEAT_RAD_EMISS_WATER:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.emiss_water = value; break;
+        case SWMM_HEAT_RAD_EMISS_LANDCOVER:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.emiss_landcover = value; break;
+        case SWMM_HEAT_RAD_ATM_EMISS_COEFF:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.atm_emiss_coeff = value; break;
+        case SWMM_HEAT_RAD_LW_REFLECTION:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            rc.lw_reflection = value; break;
+        default:
+            return SWMM_ERR_BADINDEX;
+    }
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_shortwave_mode(SWMM_Engine engine,
+                                                 int* mode) {
+    CHECK_HANDLE(engine);
+    if (mode == nullptr) return SWMM_ERR_BADPARAM;
+    *mode = static_cast(
+        to_engine(engine)->context().heat_config.radiative.sw_mode);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_shortwave_mode(SWMM_Engine engine,
+                                                 int mode) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    switch (mode) {
+        case SWMM_HEAT_SW_CONSTANT:
+            cfg.radiative.sw_mode = ShortwaveMode::CONSTANT;
+            break;
+        case SWMM_HEAT_SW_TIMESERIES:
+            // Refuse a mode with nothing behind it. Accepting it would leave
+            // the model reading 0 W/m2 forever and looking configured.
+            if (cfg.radiative.sw_ts_index < 0) return SWMM_ERR_BADPARAM;
+            cfg.radiative.sw_mode = ShortwaveMode::TIMESERIES;
+            break;
+        case SWMM_HEAT_SW_COMPUTED:
+            // The §2.5 trap, enforced at the API exactly as at the parser:
+            // no coordinates, no COMPUTED. Never fall back on the SNOWMELT
+            // latitude — it defaults to 0 and would model equatorial noon.
+            if (!cfg.solar.has_latitude || !cfg.solar.has_longitude)
+                return SWMM_ERR_BADPARAM;
+            cfg.radiative.sw_mode = ShortwaveMode::COMPUTED;
+            break;
+        default:
+            return SWMM_ERR_BADINDEX;
+    }
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_shortwave_timeseries(SWMM_Engine engine,
+                                                       const char* name) {
+    CHECK_HANDLE(engine);
+    if (name == nullptr || *name == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    // BADPARAM, not BADINDEX: this is a NAME that did not resolve, and the
+    // sibling convention reserves BADINDEX for out-of-range integers
+    // (openswmm_gages_impl.cpp:121, openswmm_api_common.hpp:74).
+    const int ts = ctx.find_timeseries(name);
+    if (ts < 0) return SWMM_ERR_BADPARAM;
+    ctx.heat_config.radiative.sw_ts_index = ts;
+    ctx.heat_config.radiative.sw_mode     = ShortwaveMode::TIMESERIES;
+    ctx.heat_config.configured            = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_shortwave_timeseries(SWMM_Engine engine,
+                                                       char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (buf == nullptr || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    ts_name_out(ctx, ctx.heat_config.radiative.sw_ts_index, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_current_shortwave(SWMM_Engine engine,
+                                                    double* wm2) {
+    CHECK_HANDLE(engine);
+    if (wm2 == nullptr) return SWMM_ERR_BADPARAM;
+    // `shortwave_now` carries a NEGATIVE "not yet resolved" sentinel
+    // internally (HeatData.hpp). The documented API contract is 0 before
+    // the first step, so the sentinel is folded here rather than leaking a
+    // magic number to callers.
+    const double sw = to_engine(engine)->context().heat_state.shortwave_now;
+    *wm2 = (sw < 0.0) ? 0.0 : sw;
+    return SWMM_OK;
+}
+
+// ===========================================================================
+// [SOLAR_RADIATION]
+// ===========================================================================
+
+SWMM_ENGINE_API int swmm_heat_get_solar(SWMM_Engine engine, int param,
+                                        double* value) {
+    CHECK_HANDLE(engine);
+    if (value == nullptr) return SWMM_ERR_BADPARAM;
+    const auto& sc = to_engine(engine)->context().heat_config.solar;
+    switch (param) {
+        case SWMM_HEAT_SOLAR_LATITUDE:      *value = sc.latitude_deg;    break;
+        case SWMM_HEAT_SOLAR_LONGITUDE:     *value = sc.longitude_deg;   break;
+        case SWMM_HEAT_SOLAR_TIMEZONE:      *value = sc.timezone_hours;  break;
+        case SWMM_HEAT_SOLAR_ELEVATION:     *value = sc.elevation_m;     break;
+        case SWMM_HEAT_SOLAR_TURBIDITY_380: *value = sc.aod380;          break;
+        case SWMM_HEAT_SOLAR_TURBIDITY_500: *value = sc.aod500;          break;
+        case SWMM_HEAT_SOLAR_PRECIP_WATER:  *value = sc.precip_water_cm; break;
+        case SWMM_HEAT_SOLAR_OZONE:         *value = sc.ozone_cm;        break;
+        case SWMM_HEAT_SOLAR_GROUND_ALBEDO: *value = sc.ground_albedo;   break;
+        default:                            return SWMM_ERR_BADINDEX;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_solar(SWMM_Engine engine, int param,
+                                        double value) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    auto& sc  = cfg.solar;
+    switch (param) {
+        case SWMM_HEAT_SOLAR_LATITUDE:
+            if (value < -90.0 || value > 90.0) return SWMM_ERR_BADPARAM;
+            sc.latitude_deg = value;
+            sc.has_latitude = true;   // what COMPUTED checks for
+            break;
+        case SWMM_HEAT_SOLAR_LONGITUDE:
+            if (value < -180.0 || value > 180.0) return SWMM_ERR_BADPARAM;
+            sc.longitude_deg = value;
+            sc.has_longitude = true;
+            break;
+        case SWMM_HEAT_SOLAR_TIMEZONE:
+            if (value < -14.0 || value > 14.0) return SWMM_ERR_BADPARAM;
+            sc.timezone_hours = value;
+            sc.has_timezone   = true;
+            break;
+        case SWMM_HEAT_SOLAR_ELEVATION:
+            // The SAME band the parser enforces. This used to refuse only
+            // absurd positives, on the theory that a negative was the
+            // "use climate elev" sentinel — but that sentinel is gone
+            // (SolarConfig::has_elevation), and the divergence contradicted
+            // this file's own docblock.
+            if (value < -500.0 || value > 9000.0) return SWMM_ERR_BADPARAM;
+            sc.elevation_m   = value;
+            sc.has_elevation = true;
+            break;
+        case SWMM_HEAT_SOLAR_TURBIDITY_380:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            sc.aod380 = value; break;
+        case SWMM_HEAT_SOLAR_TURBIDITY_500:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            sc.aod500 = value; break;
+        case SWMM_HEAT_SOLAR_PRECIP_WATER:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            sc.precip_water_cm = value; break;
+        case SWMM_HEAT_SOLAR_OZONE:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            sc.ozone_cm = value; break;
+        case SWMM_HEAT_SOLAR_GROUND_ALBEDO:
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            sc.ground_albedo = value; break;
+        default:
+            return SWMM_ERR_BADINDEX;
+    }
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_solar_sited(SWMM_Engine engine, int* sited) {
+    CHECK_HANDLE(engine);
+    if (sited == nullptr) return SWMM_ERR_BADPARAM;
+    const auto& sc = to_engine(engine)->context().heat_config.solar;
+    *sited = (sc.has_latitude && sc.has_longitude) ? 1 : 0;
+    return SWMM_OK;
+}
+
+// ===========================================================================
+// [CLOUD_COVER]
+// ===========================================================================
+
+SWMM_ENGINE_API int swmm_heat_get_cloud_configured(SWMM_Engine engine,
+                                                   int* configured) {
+    CHECK_HANDLE(engine);
+    if (configured == nullptr) return SWMM_ERR_BADPARAM;
+    *configured =
+        to_engine(engine)->context().heat_config.cloud.configured ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_cloud(SWMM_Engine engine, int param,
+                                        double* value) {
+    CHECK_HANDLE(engine);
+    if (value == nullptr) return SWMM_ERR_BADPARAM;
+    const auto& cc = to_engine(engine)->context().heat_config.cloud;
+    switch (param) {
+        case SWMM_HEAT_CLOUD_FRACTION:   *value = cc.fraction;   break;
+        case SWMM_HEAT_CLOUD_SW_ATTEN_K: *value = cc.sw_atten_k; break;
+        case SWMM_HEAT_CLOUD_SW_ATTEN_N: *value = cc.sw_atten_n; break;
+        case SWMM_HEAT_CLOUD_LW_CLOUD_K: *value = cc.lw_cloud_k; break;
+        default:                         return SWMM_ERR_BADINDEX;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_cloud(SWMM_Engine engine, int param,
+                                        double value) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    auto& cc  = cfg.cloud;
+    switch (param) {
+        case SWMM_HEAT_CLOUD_FRACTION:
+            // Refused, not clamped: a 75 meant as 75% must not quietly
+            // become an overcast sky that looks deliberate.
+            if (!frac_ok(value)) return SWMM_ERR_BADPARAM;
+            cc.fraction       = value;
+            cc.use_timeseries = false;
+            break;
+        case SWMM_HEAT_CLOUD_SW_ATTEN_K:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            cc.sw_atten_k = value; break;
+        case SWMM_HEAT_CLOUD_SW_ATTEN_N:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            cc.sw_atten_n = value; break;
+        case SWMM_HEAT_CLOUD_LW_CLOUD_K:
+            if (value < 0.0) return SWMM_ERR_BADPARAM;
+            cc.lw_cloud_k = value; break;
+        default:
+            return SWMM_ERR_BADINDEX;
+    }
+    cc.configured  = true;
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_cloud_timeseries(SWMM_Engine engine,
+                                                   const char* name) {
+    CHECK_HANDLE(engine);
+    if (name == nullptr || *name == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    const int ts = ctx.find_timeseries(name);   // BADPARAM: see above
+    if (ts < 0) return SWMM_ERR_BADPARAM;
+    auto& cc = ctx.heat_config.cloud;
+    cc.ts_index        = ts;
+    cc.use_timeseries  = true;
+    cc.configured      = true;
+    ctx.heat_config.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_cloud_timeseries(SWMM_Engine engine,
+                                                   char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (buf == nullptr || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    ts_name_out(ctx, ctx.heat_config.cloud.ts_index, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_clear_cloud(SWMM_Engine engine) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    // Whole-struct reset, not field-by-field: the coefficients go back to
+    // their documented defaults along with the fraction, so "clear" means
+    // the same thing as "no [CLOUD_COVER] section" rather than "the
+    // section, with the last k you happened to type".
+    ctx.heat_config.cloud = openswmm::CloudConfig{};
+    ctx.heat_state.cloud_now = 0.0;
+    // Back to unresolved, not to the last CLOUDED value: the cached
+    // shortwave was attenuated by the cloud cover just removed, and a
+    // reader between now and the next step should not see it.
+    ctx.heat_state.shortwave_now = -1.0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_current_cloud(SWMM_Engine engine,
+                                                double* fraction) {
+    CHECK_HANDLE(engine);
+    if (fraction == nullptr) return SWMM_ERR_BADPARAM;
+    *fraction = to_engine(engine)->context().heat_state.cloud_now;
+    return SWMM_OK;
+}
+
+/* -------------------------------------------------------- [HEAT_SOURCES]
+ *
+ * Every refusal mirrors HeatComponent.cpp's parser, so the deck and the API
+ * agree about what a model may contain. Values are refused, never clamped,
+ * and a refused call does not mutate — the half-apply the radiative setter's
+ * comment names.
+ */
+
+SWMM_ENGINE_API int swmm_heat_source_count(SWMM_Engine engine, int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    // A fixed enum extent, not a parsed list: this answers on a model with
+    // no heat configured, which is the MCP's first call on most models.
+    *count = static_cast(HeatSource::COUNT_);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_source_temp(SWMM_Engine engine, int source,
+                                              double* temp_c) {
+    CHECK_HANDLE(engine);
+    if (temp_c == nullptr) return SWMM_ERR_BADPARAM;
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    *temp_c = to_engine(engine)->context()
+                  .heat_config.global_temp[static_cast(source)];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_source_temp(SWMM_Engine engine, int source,
+                                              double temp_c) {
+    CHECK_HANDLE(engine);
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    if (!temp_ok(temp_c))   return SWMM_ERR_BADPARAM;
+    auto& cfg = to_engine(engine)->context().heat_config;
+    const auto us = static_cast(source);
+    cfg.global_temp[us]       = temp_c;
+    cfg.configured_source[us] = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_source_configured(SWMM_Engine engine,
+                                                    int source,
+                                                    int* configured) {
+    CHECK_HANDLE(engine);
+    if (configured == nullptr) return SWMM_ERR_BADPARAM;
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    *configured = to_engine(engine)->context()
+                      .heat_config
+                      .configured_source[static_cast(source)]
+                      ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_clear_source_temp(SWMM_Engine engine,
+                                                int source) {
+    CHECK_HANDLE(engine);
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    auto& cfg = to_engine(engine)->context().heat_config;
+    const auto us = static_cast(source);
+    cfg.global_temp[us]       = HeatConfigData::kDefaultTemp;
+    cfg.configured_source[us] = false;
+    // NODE overrides are deliberately untouched: they are separate rows, and
+    // removing model the caller did not name is the data-loss shape this
+    // program has already paid for once (the embedded-section round).
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_node_override_count(SWMM_Engine engine,
+                                                  int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    *count = static_cast(
+        to_engine(engine)->context().heat_config.node_over_source.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_node_override(SWMM_Engine engine, int index,
+                                                int* source, int* node,
+                                                double* temp_c) {
+    CHECK_HANDLE(engine);
+    const auto& cfg = to_engine(engine)->context().heat_config;
+    if (index < 0 ||
+        static_cast(index) >= cfg.node_over_source.size())
+        return SWMM_ERR_BADINDEX;
+    const auto ui = static_cast(index);
+    if (source) *source = cfg.node_over_source[ui];
+    if (node)   *node   = cfg.node_over_node[ui];
+    if (temp_c) *temp_c = cfg.node_over_temp[ui];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_set_node_override(SWMM_Engine engine,
+                                                int source, int node,
+                                                double temp_c) {
+    CHECK_HANDLE(engine);
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    // H1 scope, refused rather than deferred silently — the same answer the
+    // deck gets from HeatComponent.cpp ("NODE scope applies to DWF and
+    // EXTERNAL_INFLOW in H1").
+    if (!node_scope_ok(source)) return SWMM_ERR_BADPARAM;
+    if (!temp_ok(temp_c))       return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    if (node < 0 || node >= ctx.n_nodes()) return SWMM_ERR_BADINDEX;
+    auto& cfg = ctx.heat_config;
+    // ALL checks precede any mutation. Written the other way round this
+    // would refuse the call and keep the write.
+    for (std::size_t i = 0; i < cfg.node_over_source.size(); ++i)
+        if (cfg.node_over_source[i] == source &&
+            cfg.node_over_node[i] == node) {
+            // Update, not refuse. The parser refuses a duplicate ROW because
+            // one deck cannot mean two temperatures; an API caller setting
+            // the same pair twice is editing, and refusing would leave the
+            // editor unable to change a value it had just written. The
+            // invariant — one row per (source, node) — is identical.
+            cfg.node_over_temp[i] = temp_c;
+            return SWMM_OK;
+        }
+    cfg.node_over_source.push_back(source);
+    cfg.node_over_node.push_back(node);
+    cfg.node_over_temp.push_back(temp_c);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_remove_node_override(SWMM_Engine engine,
+                                                   int index) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().heat_config;
+    if (index < 0 ||
+        static_cast(index) >= cfg.node_over_source.size())
+        return SWMM_ERR_BADINDEX;
+    const auto ui = static_cast(index);
+    cfg.node_over_source.erase(cfg.node_over_source.begin() + ui);
+    cfg.node_over_node.erase(cfg.node_over_node.begin() + ui);
+    cfg.node_over_temp.erase(cfg.node_over_temp.begin() + ui);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_heat_get_effective_source_temp(SWMM_Engine engine,
+                                                        int source, int node,
+                                                        double* temp_c) {
+    CHECK_HANDLE(engine);
+    if (temp_c == nullptr) return SWMM_ERR_BADPARAM;
+    if (!source_ok(source)) return SWMM_ERR_BADINDEX;
+    auto& ctx = to_engine(engine)->context();
+    if (node < 0 || node >= ctx.n_nodes()) return SWMM_ERR_BADINDEX;
+    // Delegate to the engine's own resolver rather than re-deriving the
+    // override-beats-global precedence here: two copies of a precedence rule
+    // drift, and the API's copy would drift silently.
+    *temp_c = ctx.heat_config.source_temp(
+        static_cast(source), node);
+    return SWMM_OK;
+}
diff --git a/src/engine/core/openswmm_hotstart_impl.cpp b/src/engine/core/openswmm_hotstart_impl.cpp
index d715070ec..2a9fcc13a 100644
--- a/src/engine/core/openswmm_hotstart_impl.cpp
+++ b/src/engine/core/openswmm_hotstart_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_hotstart_impl.cpp
  * @brief Hot start C API implementation — thin wrappers around HotStartManager.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "SWMMEngine.hpp"
diff --git a/src/engine/core/openswmm_inflows_impl.cpp b/src/engine/core/openswmm_inflows_impl.cpp
index 935e29abb..48c0b1013 100644
--- a/src/engine/core/openswmm_inflows_impl.cpp
+++ b/src/engine/core/openswmm_inflows_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_inflows_impl.cpp
  * @brief C API implementation — external inflows, DWF, RDII.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
diff --git a/src/engine/core/openswmm_infrastructure_impl.cpp b/src/engine/core/openswmm_infrastructure_impl.cpp
index d6e85543f..98ce5a092 100644
--- a/src/engine/core/openswmm_infrastructure_impl.cpp
+++ b/src/engine/core/openswmm_infrastructure_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_infrastructure_impl.cpp
  * @brief C API implementation — transects, streets, inlets, LID controls, LID usage.
@@ -7,12 +23,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
 #include "../../../include/openswmm/engine/openswmm_infrastructure.h"
 #include "StringCase.hpp"
+#include "ErrorCodes.hpp"
+#include "../edit/VirtualJunctionOps.hpp"
 
 #include 
 #include 
@@ -44,7 +62,12 @@ SWMM_ENGINE_API int swmm_transect_add(SWMM_Engine engine, const char* id) {
     ts.x_left_encroachment.push_back(0.0);
     ts.x_right_encroachment.push_back(0.0);
     ts.x_factor.push_back(1.0);
-    ts.y_factor.push_back(1.0);
+    // y_factor is an ADDITIVE elevation offset (legacy transect.c:382:
+    // Yfactor = x9/UCF, applied as elev + Yfactor), not a multiplier — it gets
+    // no 0→1 normalization. 1.0 here silently shifted every API-created
+    // transect up one length unit; 0.0 is the neutral value and the INP
+    // parser's default.
+    ts.y_factor.push_back(0.0);
     ts.length_factor.push_back(1.0);
     ts.stations.push_back({});
     ts.elevations.push_back({});
@@ -305,6 +328,44 @@ SWMM_ENGINE_API int swmm_street_add(SWMM_Engine engine, const char* id) {
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_street_rename(SWMM_Engine engine, int idx, const char* new_id) {
+    CHECK_HANDLE(engine);
+    if (!new_id || new_id[0] == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    auto& st  = ctx.streets;
+    CHECK_INDEX(idx >= 0 && idx < st.count());
+    const auto ui = static_cast(idx);
+
+    // Same-name (case-sensitive) is a no-op.
+    if (st.names[ui] == new_id) return SWMM_OK;
+
+    // Streets have no NameIndex — lookups are linear ieq scans — so do the
+    // collision check the same way.
+    const std::string newName(new_id);
+    for (std::size_t i = 0; i < st.names.size(); ++i) {
+        if (i == ui) continue;
+        if (openswmm::ieq(st.names[i], newName)) return SWMM_ERR_BADPARAM;
+    }
+
+    const std::string prev = st.names[ui];
+    st.names[ui] = newName;
+
+    // Unlike the other four, a street IS referenced by name after parsing:
+    // STREET_XSECT links keep it in links.pump_curve_name (that field is
+    // overloaded for named cross-section references). InpWriter emits it as
+    // [XSECTIONS] Geom1 and swmm_link_get_xsect resolves the street back by
+    // name, so skipping this fixup would write a dangling reference.
+    for (std::size_t i = 0; i < ctx.links.pump_curve_name.size(); ++i) {
+        if (i < ctx.links.xsect_shape.size() &&
+            ctx.links.xsect_shape[i] != openswmm::XsectShape::STREET_XSECT)
+            continue;
+        if (openswmm::ieq(ctx.links.pump_curve_name[i], prev))
+            ctx.links.pump_curve_name[i] = newName;
+    }
+
+    return SWMM_OK;
+}
+
 SWMM_ENGINE_API int swmm_street_set_params(SWMM_Engine engine, int idx,
                                              double t_crown, double h_curb, double sx, double n_road,
                                              double gutter_depres, double gutter_width, int sides,
@@ -382,19 +443,43 @@ SWMM_ENGINE_API int swmm_inlet_add(SWMM_Engine engine, const char* id, const cha
     if (!id || !type) return SWMM_ERR_BADPARAM;
 
     auto& ctx = to_engine(engine)->context();
-    auto& inl = ctx.inlets;
+    ctx.inlets.add_row(id, type);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_rename(SWMM_Engine engine, int idx, const char* new_id) {
+    CHECK_HANDLE(engine);
+    if (!new_id || new_id[0] == '\0') return SWMM_ERR_BADPARAM;
+    auto& inl = to_engine(engine)->context().inlets;
+    CHECK_INDEX(idx >= 0 && idx < inl.count());
+    const auto ui = static_cast(idx);
 
-    inl.names.push_back(id);
-    inl.inlet_type.push_back(type);
-    inl.length.push_back(0.0);
-    inl.width.push_back(0.0);
-    inl.grate_type.push_back("");
-    inl.open_area.push_back(0.0);
-    inl.splash_veloc.push_back(0.0);
+    if (inl.names[ui] == new_id) return SWMM_OK;
 
+    // No NameIndex for inlets — swmm_inlet_index scans with ieq, so the
+    // collision check must match.
+    const std::string newName(new_id);
+    for (std::size_t i = 0; i < inl.names.size(); ++i) {
+        if (i == ui) continue;
+        if (openswmm::ieq(inl.names[i], newName)) return SWMM_ERR_BADPARAM;
+    }
+
+    inl.names[ui] = newName;
+    // [INLET_USAGE] rows hold inlet_usages.design_index, not a name string, so
+    // there is nothing further to fix up.
     return SWMM_OK;
 }
 
+namespace {
+// A curb-opening design keeps its length/height in its own columns, so the
+// legacy 5-arg convenience API maps length/width onto them for CURB and
+// DROP_CURB and onto the grate/slot columns for everything else.
+bool inlet_is_curb(const openswmm::SimulationContext& ctx, std::size_t ui) {
+    const std::string& t = ctx.inlets.inlet_type[ui];
+    return t == "CURB" || t == "DROP_CURB";
+}
+} // namespace
+
 SWMM_ENGINE_API int swmm_inlet_set_params(SWMM_Engine engine, int idx, double length, double width,
                                             const char* grate_type, double open_area, double splash_veloc) {
     CHECK_HANDLE(engine);
@@ -402,8 +487,13 @@ SWMM_ENGINE_API int swmm_inlet_set_params(SWMM_Engine engine, int idx, double le
     CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
     const auto ui = static_cast(idx);
 
-    ctx.inlets.length[ui]       = length;
-    ctx.inlets.width[ui]        = width;
+    if (inlet_is_curb(ctx, ui)) {
+        ctx.inlets.curb_length[ui] = length;
+        ctx.inlets.curb_height[ui] = width;
+    } else {
+        ctx.inlets.length[ui] = length;
+        ctx.inlets.width[ui]  = width;
+    }
     ctx.inlets.grate_type[ui]   = grate_type ? grate_type : "";
     ctx.inlets.open_area[ui]    = open_area;
     ctx.inlets.splash_veloc[ui] = splash_veloc;
@@ -454,8 +544,9 @@ SWMM_ENGINE_API int swmm_inlet_get_params(SWMM_Engine engine, int idx,
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
     const auto ui = static_cast(idx);
-    if (length)       *length       = ctx.inlets.length[ui];
-    if (width)        *width        = ctx.inlets.width[ui];
+    const bool curb = inlet_is_curb(ctx, ui);
+    if (length)       *length       = curb ? ctx.inlets.curb_length[ui] : ctx.inlets.length[ui];
+    if (width)        *width        = curb ? ctx.inlets.curb_height[ui] : ctx.inlets.width[ui];
     if (open_area)    *open_area    = ctx.inlets.open_area[ui];
     if (splash_veloc) *splash_veloc = ctx.inlets.splash_veloc[ui];
     if (grate_type) {
@@ -472,6 +563,294 @@ SWMM_ENGINE_API int swmm_inlet_get_type(SWMM_Engine engine, int idx, char* buf,
     return copy_str(ctx.inlets.inlet_type[static_cast(idx)], buf, buflen);
 }
 
+// ============================================================================
+// Full inlet-design surface + inlet usage rows (2026-09-05)
+// ============================================================================
+
+namespace {
+
+// SWMM_InletType order (== legacy InletTypeWords, with COMBO in slot 2).
+const char* const kInletTypeWords[] = {
+    "GRATE", "CURB", "COMBO", "SLOTTED", "DROP_GRATE", "DROP_CURB", "CUSTOM"};
+// SWMM_GrateType order (== legacy GrateTypeWords).
+const char* const kGrateTypeWords[] = {
+    "P_BAR-50", "P_BAR-50x100", "P_BAR-30", "CURVED_VANE",
+    "TILT_BAR-45", "TILT_BAR-30", "RETICULINE", "GENERIC"};
+
+int word_index(const char* const* words, int n, const std::string& w) {
+    for (int i = 0; i < n; ++i)
+        if (openswmm::ieq(words[i], w)) return i;
+    return -1;
+}
+
+bool is_grate_kind(int type) {
+    return type == SWMM_INLET_GRATE || type == SWMM_INLET_DROP_GRATE ||
+           type == SWMM_INLET_COMBO;
+}
+bool is_curb_kind(int type) {
+    return type == SWMM_INLET_CURB || type == SWMM_INLET_DROP_CURB ||
+           type == SWMM_INLET_COMBO;
+}
+
+} // namespace
+
+SWMM_ENGINE_API int swmm_inlet_get_design(SWMM_Engine engine, int idx, SWMM_InletDesign* out) {
+    CHECK_HANDLE(engine);
+    if (!out) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
+    const auto ui = static_cast(idx);
+    const auto& I = ctx.inlets;
+
+    *out = SWMM_InletDesign{};
+    out->type = word_index(kInletTypeWords, 7, I.inlet_type[ui]);
+    if (out->type < 0) out->type = SWMM_INLET_GRATE;
+
+    if (is_grate_kind(out->type)) {
+        out->grate_length = I.length[ui];
+        out->grate_width  = I.width[ui];
+    } else if (out->type == SWMM_INLET_SLOTTED) {
+        out->slot_length = I.length[ui];
+        out->slot_width  = I.width[ui];
+    }
+    out->grate_type   = word_index(kGrateTypeWords, 8, I.grate_type[ui]);
+    if (out->grate_type < 0) out->grate_type = SWMM_GRATE_P_BAR_50;
+    out->open_area    = I.open_area[ui];
+    out->splash_veloc = I.splash_veloc[ui];
+
+    if (is_curb_kind(out->type)) {
+        out->curb_length = I.curb_length[ui];
+        out->curb_height = I.curb_height[ui];
+    }
+    out->throat = I.curb_throat[ui];
+
+    copy_str(I.curve_id[ui], out->curve_id, static_cast(sizeof(out->curve_id)));
+    out->curve_kind = I.curve_kind[ui];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_set_design(SWMM_Engine engine, int idx, const SWMM_InletDesign* design) {
+    CHECK_HANDLE(engine);
+    if (!design) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
+    if (design->type < 0 || design->type > SWMM_INLET_CUSTOM) return SWMM_ERR_BADPARAM;
+
+    // --- validate only the fields the type actually uses ---
+    if (is_grate_kind(design->type)) {
+        if (design->grate_length <= 0.0 || design->grate_width <= 0.0) return SWMM_ERR_BADPARAM;
+        if (design->grate_type < 0 || design->grate_type > SWMM_GRATE_GENERIC) return SWMM_ERR_BADPARAM;
+        if (design->grate_type == SWMM_GRATE_GENERIC &&
+            (design->open_area <= 0.0 || design->open_area > 1.0)) return SWMM_ERR_BADPARAM;
+        if (design->splash_veloc < 0.0) return SWMM_ERR_BADPARAM;
+    }
+    if (is_curb_kind(design->type)) {
+        if (design->curb_length <= 0.0 || design->curb_height <= 0.0) return SWMM_ERR_BADPARAM;
+        if (design->throat < SWMM_THROAT_HORIZONTAL ||
+            design->throat > SWMM_THROAT_VERTICAL) return SWMM_ERR_BADPARAM;
+    }
+    if (design->type == SWMM_INLET_SLOTTED &&
+        (design->slot_length <= 0.0 || design->slot_width <= 0.0)) return SWMM_ERR_BADPARAM;
+    // CUSTOM: the legacy [INLETS] grammar carries no kind token, so the curve's
+    // own table type is the authority and PostParseResolver re-derives the kind
+    // on load. Resolve it here as well when the curve already exists, so a
+    // programmatically built model is complete without a reparse, and reject a
+    // kind that contradicts the curve.
+    int custom_curve_index = -1;
+    int custom_curve_kind  = SWMM_INLET_CURVE_NONE;
+    if (design->type == SWMM_INLET_CUSTOM) {
+        if (design->curve_id[0] == '\0') return SWMM_ERR_BADPARAM;
+        if (design->curve_kind < SWMM_INLET_CURVE_NONE ||
+            design->curve_kind > SWMM_INLET_CURVE_RATING) return SWMM_ERR_BADPARAM;
+        custom_curve_kind  = design->curve_kind;
+        custom_curve_index = ctx.find_curve(design->curve_id);
+        if (custom_curve_index >= 0) {
+            const openswmm::TableType tt =
+                ctx.tables[static_cast(custom_curve_index)].type;
+            const int actual = (tt == openswmm::TableType::CURVE_DIVERSION)
+                                   ? SWMM_INLET_CURVE_DIVERSION
+                                   : (tt == openswmm::TableType::CURVE_RATING)
+                                         ? SWMM_INLET_CURVE_RATING
+                                         : SWMM_INLET_CURVE_NONE;
+            if (actual == SWMM_INLET_CURVE_NONE) return SWMM_ERR_BADPARAM;
+            if (custom_curve_kind != SWMM_INLET_CURVE_NONE &&
+                custom_curve_kind != actual) return SWMM_ERR_BADPARAM;
+            custom_curve_kind = actual;
+        }
+    }
+
+    const auto ui = static_cast(idx);
+    auto& I = ctx.inlets;
+    I.inlet_type[ui] = kInletTypeWords[design->type];
+
+    if (is_grate_kind(design->type)) {
+        I.length[ui]       = design->grate_length;
+        I.width[ui]        = design->grate_width;
+        I.grate_type[ui]   = kGrateTypeWords[design->grate_type];
+        I.open_area[ui]    = design->open_area;
+        I.splash_veloc[ui] = design->splash_veloc;
+    } else if (design->type == SWMM_INLET_SLOTTED) {
+        I.length[ui]       = design->slot_length;
+        I.width[ui]        = design->slot_width;
+        I.grate_type[ui].clear();
+        I.open_area[ui]    = 0.0;
+        I.splash_veloc[ui] = 0.0;
+    } else {
+        I.length[ui] = 0.0;
+        I.width[ui]  = 0.0;
+        I.grate_type[ui].clear();
+        I.open_area[ui]    = 0.0;
+        I.splash_veloc[ui] = 0.0;
+    }
+
+    if (is_curb_kind(design->type)) {
+        I.curb_length[ui] = design->curb_length;
+        I.curb_height[ui] = design->curb_height;
+        I.curb_throat[ui] = design->throat;
+    } else {
+        I.curb_length[ui] = 0.0;
+        I.curb_height[ui] = 0.0;
+        I.curb_throat[ui] = SWMM_THROAT_VERTICAL;
+    }
+
+    if (design->type == SWMM_INLET_CUSTOM) {
+        I.curve_id[ui]    = design->curve_id;
+        I.curve_index[ui] = custom_curve_index;  // -1 until PostParseResolver
+        I.curve_kind[ui]  = custom_curve_kind;
+    } else {
+        I.curve_id[ui].clear();
+        I.curve_index[ui] = -1;
+        I.curve_kind[ui]  = SWMM_INLET_CURVE_NONE;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_get_comment(SWMM_Engine engine, int idx, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
+    return copy_str(ctx.inlets.comments[static_cast(idx)], buf, buflen);
+}
+
+SWMM_ENGINE_API int swmm_inlet_set_comment(SWMM_Engine engine, int idx, const char* text) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.inlets.count());
+    ctx.inlets.comments[static_cast(idx)] = text ? text : "";
+    return SWMM_OK;
+}
+
+// ---------------------------------------------------------------------------
+// Inlet usage rows
+// ---------------------------------------------------------------------------
+
+SWMM_ENGINE_API int swmm_inlet_usage_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return to_engine(engine)->context().inlet_usages.count();
+}
+
+SWMM_ENGINE_API int swmm_inlet_usage_find_link(SWMM_Engine engine, int link_idx) {
+    if (!engine) return -1;
+    return to_engine(engine)->context().inlet_usages.find_by_link(link_idx);
+}
+
+SWMM_ENGINE_API int swmm_inlet_usage_find_node(SWMM_Engine engine, int node_idx) {
+    if (!engine) return -1;
+    return to_engine(engine)->context().inlet_usages.find_by_node_host(node_idx);
+}
+
+SWMM_ENGINE_API int swmm_inlet_usage_get(SWMM_Engine engine, int usage_idx, SWMM_InletUsage* out) {
+    CHECK_HANDLE(engine);
+    if (!out) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(usage_idx >= 0 && usage_idx < ctx.inlet_usages.count());
+    const auto ur = static_cast(usage_idx);
+    const auto& U = ctx.inlet_usages;
+
+    const bool node_host = U.node_host[ur] >= 0;
+    out->host_kind        = node_host ? SWMM_INLET_HOST_NODE : SWMM_INLET_HOST_LINK;
+    out->host_idx         = node_host ? U.node_host[ur] : U.link_index[ur];
+    out->design_idx       = U.design_index[ur];
+    out->capture_node_idx = U.node_index[ur];
+    out->num_inlets       = U.num_inlets[ur];
+    out->pct_clogged      = (1.0 - U.clog_factor[ur]) * 100.0;
+    out->flow_limit       = U.flow_limit[ur];
+    out->local_depress    = U.local_depress[ur];
+    out->local_width      = U.local_width[ur];
+    out->placement        = U.placement[ur];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_usage_set(SWMM_Engine engine, const SWMM_InletUsage* usage, int* usage_idx) {
+    CHECK_HANDLE(engine);
+    if (!usage) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+
+    const bool node_host = (usage->host_kind == SWMM_INLET_HOST_NODE);
+    if (usage->host_kind != SWMM_INLET_HOST_LINK && !node_host) return SWMM_ERR_BADPARAM;
+
+    if (node_host) {
+        CHECK_INDEX(usage->host_idx >= 0 && usage->host_idx < ctx.n_nodes());
+        const auto uh = static_cast(usage->host_idx);
+        // Only a node already promoted to an inlet junction may host a row.
+        if (uh >= ctx.nodes.is_inlet.size() || !ctx.nodes.is_inlet[uh]) return SWMM_ERR_BADPARAM;
+    } else {
+        CHECK_INDEX(usage->host_idx >= 0 && usage->host_idx < ctx.n_links());
+        if (ctx.links.type[static_cast(usage->host_idx)] !=
+            openswmm::LinkType::CONDUIT) return SWMM_ERR_BADPARAM;
+    }
+    CHECK_INDEX(usage->design_idx >= 0 && usage->design_idx < ctx.inlets.count());
+    CHECK_INDEX(usage->capture_node_idx >= 0 && usage->capture_node_idx < ctx.n_nodes());
+    if (node_host && usage->capture_node_idx == usage->host_idx) return SWMM_ERR_BADPARAM;
+    if (ctx.nodes.is_virtual[static_cast(usage->capture_node_idx)]) return SWMM_ERR_BADPARAM;
+    if (usage->num_inlets < 1) return SWMM_ERR_BADPARAM;
+    if (usage->pct_clogged < 0.0 || usage->pct_clogged > 99.0) return SWMM_ERR_BADPARAM;
+    if (usage->flow_limit < 0.0 || usage->local_depress < 0.0 ||
+        usage->local_width < 0.0) return SWMM_ERR_BADPARAM;
+    if (usage->placement < SWMM_INLET_AUTOMATIC ||
+        usage->placement > SWMM_INLET_ON_SAG) return SWMM_ERR_BADPARAM;
+
+    // Legacy inlet_validate shape rule (inlet.c:498-505).
+    const int host_link = openswmm::edit::ij_host_conduit(
+        ctx, node_host ? 1 : 0, usage->host_idx);
+    if (!openswmm::edit::ij_usage_shape_ok(ctx, usage->design_idx, host_link))
+        return openswmm::ERR_INLET_USAGE_SHAPE;
+
+    // At most one row per host: replace in place, else append.
+    int row = node_host ? ctx.inlet_usages.find_by_node_host(usage->host_idx)
+                        : ctx.inlet_usages.find_by_link(usage->host_idx);
+    if (row < 0) {
+        row = ctx.inlet_usages.add_row(node_host ? -1 : usage->host_idx,
+                                       node_host ? usage->host_idx : -1,
+                                       usage->design_idx, usage->capture_node_idx);
+    }
+    const auto ur = static_cast(row);
+    auto& U = ctx.inlet_usages;
+    U.design_index[ur]   = usage->design_idx;
+    U.node_index[ur]     = usage->capture_node_idx;
+    U.num_inlets[ur]     = usage->num_inlets;
+    U.placement[ur]      = usage->placement;
+    U.clog_factor[ur]    = 1.0 - usage->pct_clogged / 100.0;
+    U.flow_limit[ur]     = usage->flow_limit;
+    U.local_depress[ur]  = usage->local_depress;
+    U.local_width[ur]    = usage->local_width;
+    U.pending_design_name[ur].clear();
+    U.pending_capture_name[ur].clear();
+    if (usage_idx) *usage_idx = row;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_inlet_usage_remove(SWMM_Engine engine, int usage_idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(usage_idx >= 0 && usage_idx < ctx.inlet_usages.count());
+    ctx.inlet_usages.erase_row(usage_idx);
+    return SWMM_OK;
+}
+
 // ============================================================================
 // LID controls
 // ============================================================================
@@ -523,6 +902,25 @@ SWMM_ENGINE_API int swmm_lid_add(SWMM_Engine engine, const char* id, int type) {
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_lid_rename(SWMM_Engine engine, int idx, const char* new_id) {
+    CHECK_HANDLE(engine);
+    if (!new_id || new_id[0] == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    if (ctx.state != openswmm::EngineState::BUILDING &&
+        ctx.state != openswmm::EngineState::OPENED)
+        return SWMM_ERR_LIFECYCLE;
+    CHECK_INDEX(idx >= 0 && idx < ctx.lid_controls.count());
+
+    // Both stores are read: lid_controls.names backs swmm_lid_id and the
+    // [LID_CONTROLS] writer, the NameIndex backs swmm_lid_index and the
+    // [LID_USAGE] writer. NameIndex::rename arbitrates the collision.
+    if (!ctx.lid_names.rename(idx, new_id)) return SWMM_ERR_BADPARAM;
+    ctx.lid_controls.names[static_cast(idx)] = new_id;
+
+    // lid_usage rows carry lid_index, not a name string — nothing else to fix.
+    return SWMM_OK;
+}
+
 // The surface/soil/storage layer parameters seed per-unit LID state at
 // start() (soil moisture from wilting point/porosity, storage depth from the
 // initial saturation), so mid-run mutation has no single correct meaning —
diff --git a/src/engine/core/openswmm_initial_quality_impl.cpp b/src/engine/core/openswmm_initial_quality_impl.cpp
new file mode 100644
index 000000000..5bd71942c
--- /dev/null
+++ b/src/engine/core/openswmm_initial_quality_impl.cpp
@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_initial_quality_impl.cpp
+ * @brief C API implementation — [INITIAL_QUALITY] per-element rows (E-A4).
+ *
+ * @see include/openswmm/engine/openswmm_initial_quality.h
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "openswmm_api_common.hpp"
+#include "../transport/MsxInitialQuality.hpp"   // U2
+#include "../../../include/openswmm/engine/openswmm_initial_quality.h"
+
+#include 
+#include 
+
+namespace {
+
+/// Copy a std::string into a NUL-terminated caller buffer, truncating safely.
+inline void copy_to_buf(const std::string& src, char* buf, int buflen) {
+    if (!buf || buflen <= 0) return;
+    const int copy_len = std::min(static_cast(src.size()), buflen - 1);
+    std::memcpy(buf, src.c_str(), static_cast(copy_len));
+    buf[copy_len] = '\0';
+}
+
+/// Classify a constituent name against the current model: pollutant index,
+/// the reserved kinds, or kKindUnresolved when it matches nothing.
+inline int classify(const openswmm::SimulationContext& ctx,
+                    const std::string& cons) {
+    if (cons == "__WATER_AGE__")
+        return openswmm::InitialQualityData::kKindWaterAge;
+    if (cons == "__TEMPERATURE__")
+        return openswmm::InitialQualityData::kKindTemperature;
+    const int p = ctx.pollutant_names.find(cons);
+    if (p >= 0) return p;
+    // U2: reactions-component species are first-class constituents here.
+    if (ctx.reactions.configured) {
+        const int m = ctx.reactions.find_species(cons);
+        if (m >= 0) return openswmm::InitialQualityData::msxKind(m);
+    }
+    return openswmm::InitialQualityData::kKindUnresolved;
+}
+
+} // namespace
+
+extern "C" {
+
+SWMM_ENGINE_API int swmm_init_quality_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return to_engine(engine)->context().initial_quality.count();
+}
+
+SWMM_ENGINE_API int swmm_init_quality_get(SWMM_Engine engine, int entry_idx,
+                                          int* is_link, int* elem_idx,
+                                          char* constituent_buf,
+                                          int constituent_len, double* value) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(entry_idx >= 0 && entry_idx < ctx.initial_quality.count());
+    if (!is_link || !elem_idx || !value ||
+        !constituent_buf || constituent_len <= 0)
+        return SWMM_ERR_BADPARAM;
+
+    const auto u = static_cast(entry_idx);
+    const auto& iq = ctx.initial_quality;
+    *is_link  = iq.is_link[u] ? 1 : 0;
+    *elem_idx = iq.elem_idx[u];
+    *value    = iq.value[u];
+    copy_to_buf(iq.constituent[u], constituent_buf, constituent_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_init_quality_set(SWMM_Engine engine, int is_link,
+                                          int elem_idx,
+                                          const char* constituent,
+                                          double value) {
+    CHECK_HANDLE(engine);
+    if (!constituent) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    // Rows only seed state at initialize(); a mid-run edit would silently
+    // no-op — guard to the editable states (swmm_pollutant_set_init_conc
+    // contract).
+    CHECK_GEOMETRY(ctx);
+    const int n_elems = is_link ? ctx.n_links() : ctx.n_nodes();
+    CHECK_INDEX(elem_idx >= 0 && elem_idx < n_elems);
+
+    const std::string cons(constituent);
+    const int kind = classify(ctx, cons);
+    if (kind == openswmm::InitialQualityData::kKindUnresolved)
+        return SWMM_ERR_BADPARAM;
+    // Pollutant / species concentrations may not be negative; the reserved
+    // species may (signed age per D-NS1; degC temperatures).
+    if ((kind >= 0 || kind <= openswmm::InitialQualityData::kKindMsxFirst) && value < 0.0)
+        return SWMM_ERR_BADPARAM;
+
+    auto& iq = ctx.initial_quality;
+    const std::string& name = is_link
+        ? ctx.link_names.name_of(elem_idx)
+        : ctx.node_names.name_of(elem_idx);
+
+    // Upsert on (is_link, elem_idx, kind) — the parser rejects duplicates,
+    // so at most one row matches.
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if ((iq.is_link[ur] != 0) == (is_link != 0) &&
+            iq.elem_idx[ur] == elem_idx && iq.kind[ur] == kind) {
+            iq.value[ur]       = value;
+            iq.constituent[ur] = cons;
+            iq.elem_name[ur]   = name;
+            if (kind <= openswmm::InitialQualityData::kKindMsxFirst) {
+                // Keep the engines' seed table in step (upsert there too).
+                auto& rx = ctx.reactions;
+                const int m = openswmm::InitialQualityData::msxSpecies(kind);
+                for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k)
+                    if ((rx.init_elem_is_link[k] != 0) == (is_link != 0) &&
+                        rx.init_elem_idx[k] == elem_idx && rx.init_elem_species[k] == m)
+                        rx.init_elem_value[k] = value;
+                openswmm::transport::mirrorInitialQualityMsxRows(ctx);
+            }
+            return SWMM_OK;
+        }
+    }
+    iq.add(is_link != 0, name, cons, value, elem_idx, kind);
+    if (kind <= openswmm::InitialQualityData::kKindMsxFirst)
+        openswmm::transport::mirrorInitialQualityMsxRows(ctx);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_init_quality_remove(SWMM_Engine engine,
+                                             int entry_idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    CHECK_INDEX(entry_idx >= 0 && entry_idx < ctx.initial_quality.count());
+    // U2: an MSX row leaves the engines' seed table with it.
+    {
+        const auto u = static_cast(entry_idx);
+        const auto& iq = ctx.initial_quality;
+        const int m = openswmm::InitialQualityData::msxSpecies(iq.kind[u]);
+        if (m >= 0) {
+            auto& rx = ctx.reactions;
+            for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+                if ((rx.init_elem_is_link[k] != 0) == (iq.is_link[u] != 0) &&
+                    rx.init_elem_idx[k] == iq.elem_idx[u] &&
+                    rx.init_elem_species[k] == m) {
+                    rx.init_elem_is_link.erase(rx.init_elem_is_link.begin() + static_cast(k));
+                    rx.init_elem_idx.erase(rx.init_elem_idx.begin() + static_cast(k));
+                    rx.init_elem_species.erase(rx.init_elem_species.begin() + static_cast(k));
+                    rx.init_elem_value.erase(rx.init_elem_value.begin() + static_cast(k));
+                    break;
+                }
+            }
+        }
+    }
+    ctx.initial_quality.erase(entry_idx);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_init_quality_file_get(SWMM_Engine engine, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    copy_to_buf(to_engine(engine)->context().initial_quality.file, buf, buflen);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_init_quality_file_set(SWMM_Engine engine, const char* path) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    ctx.initial_quality.file = path ? path : "";
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_init_quality_is_file(SWMM_Engine engine, int entry_idx) {
+    if (!engine) return 0;
+    const auto& iq = to_engine(engine)->context().initial_quality;
+    if (entry_idx < 0 || entry_idx >= iq.count()) return 0;
+    const auto u = static_cast(entry_idx);
+    return (u < iq.from_file.size() && iq.from_file[u]) ? 1 : 0;
+}
+
+} // extern "C"
diff --git a/src/engine/core/openswmm_links_impl.cpp b/src/engine/core/openswmm_links_impl.cpp
index 60ae8ef00..34f077393 100644
--- a/src/engine/core/openswmm_links_impl.cpp
+++ b/src/engine/core/openswmm_links_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_links_impl.cpp
  * @brief C API implementation — link identity, creation, properties, state, bulk.
@@ -7,13 +23,15 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
 #include "../../../include/openswmm/engine/openswmm_links.h"
 #include "../input/PostParseResolver.hpp"
+#include "../hydraulics/Link.hpp"
 #include "../hydraulics/Street.hpp"
+#include "../hydraulics/Transect.hpp"
 #include "TypeHelpers.hpp"
 #include "StringCase.hpp"
 
@@ -179,6 +197,15 @@ SWMM_ENGINE_API int swmm_link_set_nodes(SWMM_Engine engine, int idx,
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_links_restore_authored_orientation(SWMM_Engine engine, int* count) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    const int n = openswmm::input::restore_authored_orientation(ctx);
+    if (count) *count = n;
+    return SWMM_OK;
+}
+
 SWMM_ENGINE_API int swmm_link_get_from_node(SWMM_Engine engine, int idx, int* node_idx) {
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
@@ -229,13 +256,24 @@ SWMM_ENGINE_API int swmm_link_set_roughness(SWMM_Engine engine, int idx, double
     return SWMM_OK;
 }
 
+// Link offsets cross the C API as AUTHORED values (what the .inp carries). A
+// resolved FILLED_CIRCULAR conduit stores them raised by the sediment depth
+// (link::filledCircularOffsetBump); the accessors add / remove that amount so a
+// get→set round trip and a saved file both keep the authored value.
+static double offsetBump(const openswmm::SimulationContext& ctx, int idx) {
+    return openswmm::link::filledCircularOffsetBump(
+        ctx.links, static_cast(idx),
+        ctx.state != openswmm::EngineState::BUILDING);
+}
+
 SWMM_ENGINE_API int swmm_link_set_offset_up(SWMM_Engine engine, int idx, double offset) {
     CHECK_HANDLE(engine);
     auto& ctx = to_engine(engine)->context();
     CHECK_GEOMETRY(ctx);
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
-    // units: display LENGTH -> internal ft
-    ctx.links.offset1[static_cast(idx)] = to_internal(ctx, openswmm::ucf::LENGTH, offset);
+    // units: display LENGTH -> internal ft; authored -> stored (sediment bump)
+    ctx.links.offset1[static_cast(idx)] =
+        to_internal(ctx, openswmm::ucf::LENGTH, offset) + offsetBump(ctx, idx);
     return SWMM_OK;
 }
 
@@ -244,8 +282,9 @@ SWMM_ENGINE_API int swmm_link_set_offset_dn(SWMM_Engine engine, int idx, double
     auto& ctx = to_engine(engine)->context();
     CHECK_GEOMETRY(ctx);
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
-    // units: display LENGTH -> internal ft
-    ctx.links.offset2[static_cast(idx)] = to_internal(ctx, openswmm::ucf::LENGTH, offset);
+    // units: display LENGTH -> internal ft; authored -> stored (sediment bump)
+    ctx.links.offset2[static_cast(idx)] =
+        to_internal(ctx, openswmm::ucf::LENGTH, offset) + offsetBump(ctx, idx);
     return SWMM_OK;
 }
 
@@ -571,6 +610,15 @@ SWMM_ENGINE_API int swmm_link_set_xsect(SWMM_Engine engine, int idx,
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
     auto uidx = static_cast(idx);
 
+    // The stored offsets of a resolved FILLED_CIRCULAR conduit carry the
+    // sediment bump (see swmm_link_set_offset_up). A shape edit changes that
+    // amount, not the authored offsets, so every exit below re-bases them.
+    const double old_bump = offsetBump(ctx, idx);
+    const auto rebump = [&]() {
+        const double d = offsetBump(ctx, idx) - old_bump;
+        if (d != 0.0) { ctx.links.offset1[uidx] += d; ctx.links.offset2[uidx] += d; }
+    };
+
     auto xs = static_cast(shape);
     ctx.links.xsect_shape[uidx] = xs;
 
@@ -623,6 +671,57 @@ SWMM_ENGINE_API int swmm_link_set_xsect(SWMM_Engine engine, int idx,
         ctx.links.xsect_a_full[uidx] = built.a_full;
         ctx.links.xsect_r_full[uidx] = built.r_full;
         ctx.links.xsect_w_max[uidx]  = built.w_max;
+        rebump();
+        return SWMM_OK;
+    }
+
+    // IRREGULAR cross-sections reference a [TRANSECTS] entry by index in
+    // geom1, mirroring STREET. geom1 is an index, not a length; without this
+    // branch it fell into the default arm below, which stored the index as
+    // y_full (feet) and left the transect reference dangling — the GUI's
+    // transect picker corrupted the link it assigned to.
+    if (xs == openswmm::XsectShape::IRREGULAR) {
+        const int si = static_cast(std::llround(geom1));
+        if (si < 0 || si >= ctx.transects.count()) return SWMM_ERR_BADPARAM;
+        const auto su = static_cast(si);
+        ctx.links.pump_curve_name[uidx] = ctx.transects.names[su];
+        // geom1 for IRREGULAR is the transect reference, whose identity is the
+        // NAME in pump_curve_name — never keep the numeric index in retained
+        // storage where a fallback path could read it as a dimension. geom2-4
+        // stay as plain retained storage (already set above): they are not
+        // part of the section's geometry, but the GUI's inline editors expect
+        // sibling values to survive a set/get cycle.
+        ctx.links.xsect_geom1[uidx] = 0.0;
+
+        // After a deck open PostParseResolver builds ctx.transect_tables
+        // store-aligned, so row si usually already has its table — reuse it,
+        // matching the resolver's xsect_curve = store index. A transect added
+        // through the API after open has no table yet: build one from the
+        // store with the shared helper (bit-identical to the resolver) and
+        // push it. Push-back only — cached table pointers must stay stable
+        // (test_transect_table_stability).
+        int ti;
+        if (su < ctx.transect_tables.size() &&
+            ctx.transect_tables[su].name == ctx.transects.names[su]) {
+            ti = si;
+        } else {
+            const int t_us = openswmm::ucf::getUnitSystem(
+                static_cast(ctx.options.flow_units));
+            const double t_ucf =
+                openswmm::ucf::Ucf[openswmm::ucf::LENGTH][static_cast(t_us)];
+            openswmm::transect::TransectData td;
+            if (!openswmm::transect::buildFromStore(ctx.transects, si, t_ucf, td))
+                return SWMM_ERR_BADPARAM;   // no valid channel Manning's n
+            ti = static_cast(ctx.transect_tables.size());
+            ctx.transect_tables.push_back(std::move(td));
+        }
+        const auto& built = ctx.transect_tables[static_cast(ti)];
+        ctx.links.xsect_curve[uidx]  = ti;
+        ctx.links.xsect_y_full[uidx] = built.y_full;
+        ctx.links.xsect_a_full[uidx] = built.a_full;
+        ctx.links.xsect_r_full[uidx] = built.r_full;
+        ctx.links.xsect_w_max[uidx]  = built.w_max;
+        rebump();
         return SWMM_OK;
     }
 
@@ -675,6 +774,41 @@ SWMM_ENGINE_API int swmm_link_set_xsect(SWMM_Engine engine, int idx,
             ctx.links.xsect_w_max[uidx]  = tw;
             break;
         }
+        case openswmm::XsectShape::FILLED_CIRCULAR: {
+            // Same single source of truth as PostParseResolver's default arm:
+            // legacy-faithful xsect::setParams on the RAW Geom1–4 retained
+            // above, so the sediment fields (y_bot / a_bot / s_bot / r_bot) and
+            // the reduced full-flow values match a deck open exactly — the
+            // offset bump re-based below reads y_bot. Invalid geometry
+            // (sediment >= diameter) keeps the generic fallback with no bump.
+            const int us = openswmm::ucf::getUnitSystem(
+                static_cast(ctx.options.flow_units));
+            const double ucf_len =
+                openswmm::ucf::Ucf[openswmm::ucf::LENGTH][static_cast(us)];
+            openswmm::XSectParams xsp;
+            const double p[4] = { ctx.links.xsect_geom1[uidx], ctx.links.xsect_geom2[uidx],
+                                  ctx.links.xsect_geom3[uidx], ctx.links.xsect_geom4[uidx] };
+            if (openswmm::xsect::setParams(xsp, openswmm::link::translateShape(xs), p, ucf_len) == 0 &&
+                xsp.a_full > 0.0) {
+                ctx.links.xsect_y_full[uidx] = xsp.y_full;
+                ctx.links.xsect_a_full[uidx] = xsp.a_full;
+                ctx.links.xsect_r_full[uidx] = xsp.r_full;
+                ctx.links.xsect_s_full[uidx] = xsp.s_full;
+                ctx.links.xsect_s_max[uidx]  = xsp.s_max;
+                ctx.links.xsect_w_max[uidx]  = xsp.w_max;
+                ctx.links.xsect_yw_max[uidx] = xsp.yw_max;
+                ctx.links.xsect_y_bot[uidx]  = xsp.y_bot;
+                ctx.links.xsect_a_bot[uidx]  = xsp.a_bot;
+                ctx.links.xsect_s_bot[uidx]  = xsp.s_bot;
+                ctx.links.xsect_r_bot[uidx]  = xsp.r_bot;
+                break;
+            }
+            ctx.links.xsect_y_full[uidx] = geom1;
+            ctx.links.xsect_a_full[uidx] = geom1 * geom2;
+            ctx.links.xsect_w_max[uidx]  = geom2;
+            ctx.links.xsect_y_bot[uidx]  = 0.0;
+            break;
+        }
         default: {
             // Generic fallback: store geom1 as y_full, compute area if possible
             ctx.links.xsect_y_full[uidx] = geom1;
@@ -685,6 +819,7 @@ SWMM_ENGINE_API int swmm_link_set_xsect(SWMM_Engine engine, int idx,
     }
 
     (void)geom3; (void)geom4;
+    rebump();
     return SWMM_OK;
 }
 
@@ -721,6 +856,35 @@ SWMM_ENGINE_API int swmm_link_get_xsect(SWMM_Engine engine, int idx,
         return SWMM_OK;
     }
 
+    // IRREGULAR links report geom1 = transect index, mirroring STREET. The
+    // transect identity is the name retained in pump_curve_name (xsect_curve
+    // can point at a session-pushed table, not the store row). The old default
+    // path returned y_full here — a depth where a reference belongs — so any
+    // get→set cycle rewrote the reference as a number.
+    if (xs == openswmm::XsectShape::IRREGULAR) {
+        int si = -1;
+        const auto& nm = ctx.links.pump_curve_name[uidx];
+        if (!nm.empty()) {
+            for (int t = 0; t < ctx.transects.count(); ++t) {
+                if (openswmm::ieq(ctx.transects.names[static_cast(t)],
+                                  nm)) {
+                    si = t;
+                    break;
+                }
+            }
+        } else if (ctx.links.xsect_curve[uidx] >= 0 &&
+                   ctx.links.xsect_curve[uidx] < ctx.transects.count()) {
+            si = ctx.links.xsect_curve[uidx];
+        }
+        if (geom1) *geom1 = static_cast(si);
+        // geom2-4: plain retained storage (0 for parser-loaded links — the
+        // [XSECTIONS] handler retains nothing for IRREGULAR).
+        if (geom2) *geom2 = ctx.links.xsect_geom2[uidx];
+        if (geom3) *geom3 = ctx.links.xsect_geom3[uidx];
+        if (geom4) *geom4 = ctx.links.xsect_geom4[uidx];
+        return SWMM_OK;
+    }
+
     // Prefer the retained raw Geom1–Geom4 (set by swmm_link_set_xsect / the
     // [XSECTIONS] parser) so the call mirrors what was supplied — these survive
     // the derived-geometry overwrite that loses trapezoid bottom width / side
@@ -823,16 +987,24 @@ SWMM_ENGINE_API int swmm_link_get_velocity(SWMM_Engine engine, int idx, double*
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
     if (velocity) {
         auto uidx = static_cast(idx);
-        double q = ctx.links.flow[uidx];
-        double d = ctx.links.depth[uidx];
-        double y_full = ctx.links.xsect_y_full[uidx];
-        double a_full = ctx.links.xsect_a_full[uidx];
-        // Approximate flow area from depth/y_full ratio times full area
-        double area = (y_full > 0.0 && a_full > 0.0 && d > 0.0)
-                      ? a_full * (d / y_full)
-                      : 0.0;
+        // Same arithmetic as the .out reporting path (link::getVelocity at
+        // the published depth): the true cross-section area replaces the old
+        // linear depth-ratio approximation, and multi-barrel conduits divide
+        // the aggregate flow across barrels. The published depth is clamped
+        // to y_full, so above the crown this is the conveyance velocity —
+        // never diluted by Preissmann-slot area.
+        double v_internal = 0.0;
+        if (ctx.links.xsect_y_full[uidx] > 0.0) {
+            const openswmm::XSectParams xs = openswmm::link::buildXSectParams(
+                ctx.links, uidx, &ctx.transect_tables);
+            const int cr = ctx.link_subtypes.conduit_row(idx);
+            const int nb = (cr >= 0)
+                ? ctx.link_subtypes.conduits.barrels[static_cast(cr)]
+                : 1;
+            v_internal = openswmm::link::getVelocity(
+                xs, ctx.links.flow[uidx], ctx.links.depth[uidx], nb);
+        }
         // units: internal ft/s -> display LENGTH (velocity carries LENGTH UCF)
-        const double v_internal = (area > 1.0e-12) ? q / area : 0.0;
         *velocity = to_display(ctx, openswmm::ucf::LENGTH, v_internal);
     }
     return SWMM_OK;
@@ -861,6 +1033,15 @@ SWMM_ENGINE_API int swmm_link_get_volume(SWMM_Engine engine, int idx, double* vo
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_link_get_slot_volume(SWMM_Engine engine, int idx, double* volume) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
+    // units: internal ft^3 -> display VOLUME. FV routing only; 0.0 under DW.
+    if (volume) *volume = to_display(ctx, openswmm::ucf::VOLUME, ctx.links.slot_volume[static_cast(idx)]);
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Runtime forcing
 // ============================================================================
@@ -1008,14 +1189,21 @@ SWMM_ENGINE_API int swmm_link_get_velocities_bulk(SWMM_Engine engine, double* bu
     const int n = std::min(count, ctx.n_links());
     for (int i = 0; i < n; ++i) {
         const auto ui = static_cast(i);
-        const double q = ctx.links.flow[ui];
-        const double d = ctx.links.depth[ui];
-        const double y_full = ctx.links.xsect_y_full[ui];
-        const double a_full = ctx.links.xsect_a_full[ui];
-        const double area = (y_full > 0.0 && a_full > 0.0 && d > 0.0)
-                            ? a_full * (d / y_full) : 0.0;
+        // Verbatim the scalar swmm_link_get_velocity arithmetic (true
+        // cross-section area at the published depth, aggregate flow split
+        // across barrels) so bulk vs scalar stays bit-equivalent.
+        double v_internal = 0.0;
+        if (ctx.links.xsect_y_full[ui] > 0.0) {
+            const openswmm::XSectParams xs = openswmm::link::buildXSectParams(
+                ctx.links, ui, &ctx.transect_tables);
+            const int cr = ctx.link_subtypes.conduit_row(i);
+            const int nb = (cr >= 0)
+                ? ctx.link_subtypes.conduits.barrels[static_cast(cr)]
+                : 1;
+            v_internal = openswmm::link::getVelocity(
+                xs, ctx.links.flow[ui], ctx.links.depth[ui], nb);
+        }
         // units: internal ft/s -> display LENGTH (velocity carries LENGTH UCF)
-        const double v_internal = (area > 1.0e-12) ? q / area : 0.0;
         buf[i] = to_display(ctx, openswmm::ucf::LENGTH, v_internal);
     }
     return SWMM_OK;
@@ -1408,8 +1596,9 @@ SWMM_ENGINE_API int swmm_link_get_offset_up(SWMM_Engine engine, int idx, double*
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
-    // units: internal ft -> display LENGTH
-    if (offset) *offset = to_display(ctx, openswmm::ucf::LENGTH, ctx.links.offset1[static_cast(idx)]);
+    // units: internal ft -> display LENGTH; stored -> authored (sediment bump)
+    if (offset) *offset = to_display(ctx, openswmm::ucf::LENGTH,
+                                     ctx.links.offset1[static_cast(idx)] - offsetBump(ctx, idx));
     return SWMM_OK;
 }
 
@@ -1417,8 +1606,9 @@ SWMM_ENGINE_API int swmm_link_get_offset_dn(SWMM_Engine engine, int idx, double*
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
-    // units: internal ft -> display LENGTH
-    if (offset) *offset = to_display(ctx, openswmm::ucf::LENGTH, ctx.links.offset2[static_cast(idx)]);
+    // units: internal ft -> display LENGTH; stored -> authored (sediment bump)
+    if (offset) *offset = to_display(ctx, openswmm::ucf::LENGTH,
+                                     ctx.links.offset2[static_cast(idx)] - offsetBump(ctx, idx));
     return SWMM_OK;
 }
 
@@ -1452,6 +1642,26 @@ SWMM_ENGINE_API int swmm_link_get_stat_max_filling(SWMM_Engine engine, int idx,
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_link_get_stat_peak_slot_share(SWMM_Engine engine, int idx, double* val) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
+    // dimensionless 0..1; FV routing only, 0 under DW
+    if (val) *val = ctx.links.stat_peak_slot_share[static_cast(idx)];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_link_get_stat_slot_share(SWMM_Engine engine, int idx, double* val) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_links());
+    // run-level time-integrated share: (∫slot dt)/(∫stored dt), 0..1
+    const auto u = static_cast(idx);
+    const double denom = ctx.links.stat_vol_dt[u];
+    if (val) *val = (denom > 0.0) ? ctx.links.stat_slot_vol_dt[u] / denom : 0.0;
+    return SWMM_OK;
+}
+
 SWMM_ENGINE_API int swmm_link_get_stat_vol_flow(SWMM_Engine engine, int idx, double* val) {
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
diff --git a/src/engine/core/openswmm_massbalance_impl.cpp b/src/engine/core/openswmm_massbalance_impl.cpp
index 0a4d1925b..8ccaf0f62 100644
--- a/src/engine/core/openswmm_massbalance_impl.cpp
+++ b/src/engine/core/openswmm_massbalance_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_massbalance_impl.cpp
  * @brief C API implementation — continuity errors and flux totals.
@@ -7,9 +23,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
+#include 
+
 #include "openswmm_api_common.hpp"
 #include "../../../include/openswmm/engine/openswmm_massbalance.h"
 
@@ -65,8 +83,22 @@ SWMM_ENGINE_API int swmm_get_quality_continuity_error(SWMM_Engine engine,
     double init_stored = (p < mb.qual_routing_init.size()) ? mb.qual_routing_init[p] : 0.0;
     double final_stored = (p < mb.qual_routing_final.size()) ? mb.qual_routing_final[p] : 0.0;
 
-    if (total_in > 0.0) {
-        *error = (total_in + init_stored - final_stored - total_out) / total_in;
+    // Legacy massbal_getQualError (massbal.c:900-911) has THREE branches, and
+    // the third is the one this function lacked: when nothing came IN but
+    // something went OUT, the error is measured against the outflow. Without
+    // it, a system that discharges mass it never received reports a
+    // continuity error of exactly 0.000 — measured on the known-mass EMC
+    // deck, where 1.8M units of booked mass left a system whose total_in was
+    // zero under a printed error of 0.000 (Finding 10, third instance of the
+    // vacuous-denominator shape after runoff_error's F8 case).
+    const double in_total  = total_in + init_stored;
+    const double out_total = total_out + final_stored;
+    if (std::fabs(in_total - out_total) < 0.001) {
+        *error = 0.0;
+    } else if (in_total > 0.0) {
+        *error = (in_total - out_total) / in_total;
+    } else if (out_total > 0.0) {
+        *error = (in_total - out_total) / out_total;
     } else {
         *error = 0.0;
     }
@@ -87,6 +119,8 @@ SWMM_ENGINE_API int swmm_get_runoff_total(SWMM_Engine engine, int component, dou
         case SWMM_RUNOFF_INFIL:      *volume = mb.runoff_infil;       break;
         case SWMM_RUNOFF_RUNOFF:     *volume = mb.runoff_runoff;      break;
         case SWMM_RUNOFF_SNOWREMOV:  *volume = mb.runoff_snowremov;   break;
+        case SWMM_RUNOFF_INITSNOW:   *volume = mb.runoff_init_snow;   break;
+        case SWMM_RUNOFF_FINALSNOW:  *volume = mb.runoff_final_snow;  break;
         case SWMM_RUNOFF_INITSTORE:  *volume = mb.runoff_init_store;  break;
         case SWMM_RUNOFF_FINALSTORE: *volume = mb.runoff_final_store; break;
         default: return SWMM_ERR_BADPARAM;
@@ -111,6 +145,8 @@ SWMM_ENGINE_API int swmm_get_routing_total(SWMM_Engine engine, int component, do
         case SWMM_ROUTING_INIT_STORAGE:  *volume = mb.routing_init_storage;  break;
         case SWMM_ROUTING_FINAL_STORAGE: *volume = mb.routing_final_storage; break;
         case SWMM_ROUTING_FORCING_INFLOW: *volume = mb.routing_forcing_inflow; break;
+        case SWMM_ROUTING_COUPLING_OUT:  *volume = mb.routing_coupling_out;  break;
+        case SWMM_ROUTING_LINK_GW_INFLOW: *volume = mb.routing_link_gw_inflow; break;   // G-X4
         default: return SWMM_ERR_BADPARAM;
     }
     return SWMM_OK;
diff --git a/src/engine/core/openswmm_model_impl.cpp b/src/engine/core/openswmm_model_impl.cpp
index 1c0d13b21..b8ce88e12 100644
--- a/src/engine/core/openswmm_model_impl.cpp
+++ b/src/engine/core/openswmm_model_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_model_impl.cpp
  * @brief C API implementation — model building, options, user flags, CRS.
@@ -7,9 +23,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
+#include 
+#include 
+#include 
+
 #include "openswmm_api_common.hpp"
 #include "InpWriter.hpp"
 #include "DateTime.hpp"
@@ -94,6 +114,67 @@ std::string upper_key(const char* key) {
 
 std::string upper_copy(const std::string& v) { return upper_key(v.c_str()); }
 
+// ── Strict numeric parses for the options dispatch (H1) ────────────────
+// The exception guard in swmm_options_set catches what THROWS — but two
+// parse families never do: input::parse_time_seconds fabricates 0.0 from
+// junk (and "1e999999" becomes 3600 s through its H[:M] fallthrough), and
+// std::stoi/stol accept a numeric PREFIX ("1e999999" parses as 1). An API
+// caller must get SWMM_ERR_BADPARAM, never a silent guess. Deck parsing
+// (OptionsHandler) keeps the lenient forms deliberately — file semantics
+// are parity-bound; only the C API is strict.
+double stod_strict(const std::string& v) {
+    std::size_t pos = 0;
+    const double d = std::stod(v, &pos);              // throws on junk/overflow
+    while (pos < v.size() &&
+           isspace(static_cast(v[pos]))) ++pos;
+    if (pos != v.size()) throw std::invalid_argument("trailing characters");
+    return d;
+}
+int stoi_strict(const std::string& v) {
+    std::size_t pos = 0;
+    const int i = std::stoi(v, &pos);
+    while (pos < v.size() &&
+           isspace(static_cast(v[pos]))) ++pos;
+    if (pos != v.size()) throw std::invalid_argument("trailing characters");
+    return i;
+}
+long stol_strict(const std::string& v) {
+    std::size_t pos = 0;
+    const long l = std::stol(v, &pos);
+    while (pos < v.size() &&
+           isspace(static_cast(v[pos]))) ++pos;
+    if (pos != v.size()) throw std::invalid_argument("trailing characters");
+    return l;
+}
+// Exactly the forms input::parse_time_seconds documents — a plain number
+// of seconds, or H:M[:S] with digit-only H and M — validated to full
+// consumption and computed with the SAME expression, so a well-formed
+// value is bit-identical to the deck parser's result.
+double time_seconds_strict(const std::string& v) {
+    try { return stod_strict(v); } catch (const std::exception&) {}
+    const auto c1 = v.find(':');
+    if (c1 == std::string::npos)
+        throw std::invalid_argument("neither seconds nor H:M[:S]");
+    auto uint_strict = [](const std::string& f) -> unsigned long {
+        if (f.empty()) throw std::invalid_argument("empty time field");
+        for (const char ch : f)
+            if (!isdigit(static_cast(ch)))
+                throw std::invalid_argument("non-digit time field");
+        return std::stoul(f);
+    };
+    const unsigned long h = uint_strict(v.substr(0, c1));
+    const auto c2 = v.find(':', c1 + 1);
+    unsigned long m = 0;
+    double s = 0.0;
+    if (c2 == std::string::npos) {
+        m = uint_strict(v.substr(c1 + 1));
+    } else {
+        m = uint_strict(v.substr(c1 + 1, c2 - c1 - 1));
+        s = stod_strict(v.substr(c2 + 1));
+    }
+    return h * 3600.0 + m * 60.0 + s;
+}
+
 } // anonymous
 
 extern "C" {
@@ -182,10 +263,74 @@ SWMM_ENGINE_API int swmm_finalize_model(SWMM_Engine engine) {
 // Model serialisation
 // ============================================================================
 
+namespace {
+
+// The writer's `warnings` sink is OPTIONAL, and until 2026-08-26 every
+// production caller passed nullptr — so the "embedded [REACTION_*] sections
+// are lost from this save" notice (InpWriter.cpp:2580-2586) was real code
+// that NEVER FIRED. Opening a deck with embedded reaction sections, editing
+// anything and saving destroyed the reaction system silently, from the GUI
+// included. The test that certified the behaviour called the writer directly
+// WITH a sink, so it could not see this.
+//
+// Every write path now collects and forwards into `ctx.warnings` — the same
+// vector `swmm_get_warning_count`/`swmm_get_warning_at` read
+// (`openswmm_engine_impl.cpp:242-252`), which the GUI already consumes. The
+// save still SUCCEEDS: warn-not-refuse is the writer's existing intent and
+// the defect was the silence, not the policy. Whether a save that loses model
+// data should refuse outright is a real question, deliberately left to IO3 —
+// where per-component saveData() removes the loss and makes the question moot.
+void forwardWriteWarnings(openswmm::SimulationContext& ctx,
+                          std::vector&    sink) {
+    for (auto& w : sink) ctx.warnings.push_back(std::move(w));
+}
+
+}  // namespace
+
 SWMM_ENGINE_API int swmm_model_write(SWMM_Engine engine, const char* new_inp_path) {
     CHECK_HANDLE(engine);
     if (!new_inp_path) return SWMM_ERR_BADPARAM;
-    return openswmm::inp_writer::writeInpFile(to_engine(engine)->context(), new_inp_path);
+    auto& ctx = to_engine(engine)->context();
+    std::vector warns;
+    const int rc = openswmm::inp_writer::writeInpFile(ctx, new_inp_path, &warns);
+    forwardWriteWarnings(ctx, warns);
+    return rc;
+}
+
+SWMM_ENGINE_API int swmm_model_write_staged(SWMM_Engine engine,
+                                             const char* final_inp_path,
+                                             SWMM_StageOutputCallback mapper,
+                                             void* user_data) {
+    CHECK_HANDLE(engine);
+    if (!final_inp_path || !final_inp_path[0] || !mapper) return SWMM_ERR_BADPARAM;
+    openswmm::inp_writer::InpWriteOptions opts;
+    opts.map_output = [=](const std::string& path, auto kind) {
+        const char* mapped = mapper(user_data, path.c_str(), static_cast(kind));
+        return mapped ? std::string(mapped) : std::string();
+    };
+    auto& ctx = to_engine(engine)->context();
+    std::vector warns;
+    const int rc = openswmm::inp_writer::writeInpFile(ctx, final_inp_path, &warns, opts);
+    forwardWriteWarnings(ctx, warns);
+    return rc;
+}
+
+SWMM_ENGINE_API int swmm_model_write_compat(SWMM_Engine engine, const char* new_inp_path,
+                                            int profile) {
+    CHECK_HANDLE(engine);
+    if (!new_inp_path) return SWMM_ERR_BADPARAM;
+    openswmm::inp_writer::InpWriteOptions opts;
+    switch (profile) {
+        case SWMM_INP_PROFILE_FULL:        opts.profile = openswmm::inp_writer::InpWriteOptions::Profile::Full;       break;
+        case SWMM_INP_PROFILE_SWMM5:       opts.profile = openswmm::inp_writer::InpWriteOptions::Profile::Swmm5;      break;
+        case SWMM_INP_PROFILE_SWMM5_STOCK: opts.profile = openswmm::inp_writer::InpWriteOptions::Profile::Swmm5Stock; break;
+        default: return SWMM_ERR_BADPARAM;
+    }
+    auto& ctx = to_engine(engine)->context();
+    std::vector warns;
+    const int rc = openswmm::inp_writer::writeInpFile(ctx, new_inp_path, &warns, opts);
+    forwardWriteWarnings(ctx, warns);
+    return rc;
 }
 
 SWMM_ENGINE_API int swmm_model_write_with_plugin(SWMM_Engine engine,
@@ -195,9 +340,14 @@ SWMM_ENGINE_API int swmm_model_write_with_plugin(SWMM_Engine engine,
     if (!new_path) return SWMM_ERR_BADPARAM;
 
     // Empty / NULL plugin id → built-in .inp writer.
+    // This is the path the GUI takes; see forwardWriteWarnings above for why
+    // the sink is no longer nullptr.
     if (!output_plugin_id || output_plugin_id[0] == '\0') {
-        return openswmm::inp_writer::writeInpFile(
-            to_engine(engine)->context(), new_path);
+        auto& ctx = to_engine(engine)->context();
+        std::vector warns;
+        const int rc = openswmm::inp_writer::writeInpFile(ctx, new_path, &warns);
+        forwardWriteWarnings(ctx, warns);
+        return rc;
     }
 
     auto* eng = to_engine(engine);
@@ -363,7 +513,10 @@ SWMM_ENGINE_API int swmm_files_set(SWMM_Engine engine,
     }
     else if (k == "HOTSTART_SAVE_DATETIME") {
         double dt = 0.0;
-        try { dt = v.empty() ? 0.0 : std::stod(v); }
+        // H1 §7 residue: std::stod alone accepts a numeric PREFIX, so
+        // "1.5abc" stored 1.5 and "01/01/2026" stored 1.0 silently. The
+        // contract is a decimal-day floating-point string — strict.
+        try { dt = v.empty() ? 0.0 : stod_strict(v); }
         catch (...) { return SWMM_ERR_BADPARAM; }
         if (f.hotstart_saves.empty()) f.hotstart_saves.emplace_back();
         f.hotstart_saves.front().datetime = dt;
@@ -416,7 +569,9 @@ openswmm::FilePathPair* resolve_slot(SWMM_Engine             engine,
         case SWMM_FILE_HOTSTART_SAVE: {
             if (!owner) return nullptr;
             int idx = 0;
-            try { idx = std::stoi(owner); } catch (...) { return nullptr; }
+            // H1 §7 residue: a partial parse ("1.5") resolved to slot 1
+            // instead of failing. The owner contract is a decimal index.
+            try { idx = stoi_strict(owner); } catch (...) { return nullptr; }
             if (idx < 0 ||
                 static_cast(idx) >= ctx.files.hotstart_saves.size())
                 return nullptr;
@@ -438,6 +593,32 @@ openswmm::FilePathPair* resolve_slot(SWMM_Engine             engine,
                 return nullptr;
             return &ctx.tables.tables[static_cast(idx)].file_path;
         }
+
+        case SWMM_FILE_MESH_2D:
+#ifdef OPENSWMM_HAS_2D
+            return ctx.twod_io.options ? &ctx.twod_io.options->mesh_file
+                                       : nullptr;
+#else
+            return nullptr;
+#endif
+        case SWMM_FILE_OUTPUT_2D:
+#ifdef OPENSWMM_HAS_2D
+            return ctx.twod_io.options ? &ctx.twod_io.options->output_file
+                                       : nullptr;
+#else
+            return nullptr;
+#endif
+        case SWMM_FILE_LID_REPORT: {
+            if (!owner) return nullptr;
+            int idx = 0;
+            // H1 §7 residue: a partial parse ("1.5") resolved to slot 1
+            // instead of failing. The owner contract is a decimal index.
+            try { idx = stoi_strict(owner); } catch (...) { return nullptr; }
+            if (idx < 0 ||
+                static_cast(idx) >= ctx.lid_usage.rpt_file.size())
+                return nullptr;
+            return &ctx.lid_usage.rpt_file[static_cast(idx)];
+        }
     }
     return nullptr;
 }
@@ -777,10 +958,11 @@ SWMM_ENGINE_API int swmm_options_get(SWMM_Engine engine,
     else if (k == "RULE_STEP") val = std::to_string(static_cast(opt.rule_step));
     else if (k == "DRY_DAYS")  val = std::to_string(opt.dry_days);
 
-    // Sweep day-of-year → MM/DD via year-2000 anchor (matches the
-    // OptionsHandler parser's convention).
+    // Sweep day-of-year → MM/DD via the NON-leap year-2001 anchor (matches
+    // OptionsHandler's parser and InpWriter's fmt_sweep — the 2000 anchor
+    // was the leap-year half of the SWEEP_END 12/31→1/1 drift).
     else if (k == "SWEEP_START") {
-        const auto dt = openswmm::datetime::encodeDate(2000, 1, 1)
+        const auto dt = openswmm::datetime::encodeDate(2001, 1, 1)
                       + (opt.sweep_start - 1);
         int y, m, d;
         openswmm::datetime::decodeDate(dt, y, m, d);
@@ -789,7 +971,7 @@ SWMM_ENGINE_API int swmm_options_get(SWMM_Engine engine,
         val = tmp;
     }
     else if (k == "SWEEP_END") {
-        const auto dt = openswmm::datetime::encodeDate(2000, 1, 1)
+        const auto dt = openswmm::datetime::encodeDate(2001, 1, 1)
                       + (opt.sweep_end - 1);
         int y, m, d;
         openswmm::datetime::decodeDate(dt, y, m, d);
@@ -822,8 +1004,16 @@ SWMM_ENGINE_API int swmm_options_get(SWMM_Engine engine,
     else if (k == "SURCHARGE_METHOD") {
         if      (opt.surcharge_method == 0) val = "EXTRAN";
         else if (opt.surcharge_method == 1) val = "SLOT";
+        else if (opt.surcharge_method == 3) val = "TPA";   // issue #156
         else                                val = "DYNAMIC_SLOT";
     }
+    else if (k == "TPA_CELERITY")      val = std::to_string(opt.tpa_celerity);
+    else if (k == "UNSTEADY_FRICTION") {  // issue #156
+        val = (opt.unsteady_friction == 1) ? "VITKOVSKY" : "NONE";
+    }
+    else if (k == "UF_K3")             val = std::to_string(opt.uf_k3);
+    else if (k == "REPORT_SIGNED_HEADS")  // issue #156 O-6
+        val = opt.report_signed_heads ? "YES" : "NO";
     else if (k == "NODE_CONTINUITY") {
         val = (opt.node_continuity == openswmm::NodeContinuity::SEMI_IMPLICIT)
               ? "SEMI_IMPLICIT" : "EXPLICIT";
@@ -892,19 +1082,21 @@ SWMM_ENGINE_API int swmm_options_get(SWMM_Engine engine,
         val = (opt.fv.time_integration == openswmm::fv::TimeIntegration::RK2)
                   ? "RK2" : "EULER";
     else if (k == "FV_SLOT_CELERITY")  val = std::to_string(opt.fv.slot_celerity);
+    else if (k == "FV_PRESSURIZED_IMPLICIT")
+        val = opt.fv.pressurized_implicit ? "YES" : "NO";
+    else if (k == "FV_PRESSURE_CLOSURE")  // issue #156
+        val = (opt.fv.pressure_closure == 1) ? "TPA" : "SLOT";
     else if (k == "FV_DISPERSION")     val = std::to_string(opt.fv.dispersion);
     else if (k == "FV_STRUCTURE_COUPLING")
         val = (opt.fv.structure_coupling == openswmm::fv::StructureCoupling::ROUTING_STEP)
                   ? "ROUTING_STEP" : "SUBSTEP";
     else if (k == "FV_COMPACTION")     val = opt.fv.compaction ? "YES" : "NO";
     else if (k == "FV_NODE_COUPLING")
-        val = (opt.fv.node_coupling == openswmm::fv::NodeCoupling::EXPLICIT)
-                  ? "EXPLICIT" : "SEMI_IMPLICIT";
+        val = "SEMI_IMPLICIT";            // retired option; the only coupling
     else if (k == "FV_NODE_DT")
-        val = (opt.fv.node_dt_limit == openswmm::fv::NodeDtLimit::NONE)
-                  ? "NONE" : "STABILITY";
+        val = "STABILITY";                // retired option; bound always armed
     else if (k == "FV_NODE_PICARD")
-        val = std::to_string(opt.fv.node_picard_sweeps);
+        val = "1";                        // retired option; always one sweep
     else if (k == "FV_NODE_CELL_COUPLING")
         val = "NO";                       // retired option; kept readable
     else if (k == "FV_JUNCTION_MODEL")
@@ -926,6 +1118,31 @@ SWMM_ENGINE_API int swmm_options_get(SWMM_Engine engine,
     else if (k == "FV_CFL_CENSUS_INTERVAL")
         val = std::to_string(opt.fv.cfl_census_interval);
 
+    // Quality & transport (subplan Y0). Readable and writable under ANY
+    // solver — the keys are inert rather than rejected, the same contract
+    // the FV group above documents, so a GUI can configure LARD before
+    // selecting it. Without these the C API returned BADPARAM and the
+    // options dialog could not hydrate the page at all.
+    else if (k == "QUALITY_SOLVER") {
+        switch (opt.quality_solver) {
+            case openswmm::QualitySolverKind::EULERIAN_ARD:
+                val = "EULERIAN_ARD"; break;
+            case openswmm::QualitySolverKind::LAGRANGIAN:
+                val = "LAGRANGIAN";   break;
+            default:
+                val = "LEGACY";       break;
+        }
+    }
+    else if (k == "WATER_AGE")         val = opt.water_age ? "YES" : "NO";
+    else if (k == "OUTFALL_BACKFLOW_QUALITY")
+        val = opt.outfall_backflow_zero ? "ZERO" : "LAST";
+    else if (k == "HEAT_TRANSPORT")    val = opt.heat_transport ? "YES" : "NO";
+    else if (k == "QUALITY_STEP")      val = std::to_string(opt.quality_step);
+    else if (k == "MAX_SEGMENTS_PER_LINK")
+        val = std::to_string(opt.max_segments_per_link);
+    else if (k == "DISPERSION")        val = opt.lard_rwpt ? "RWPT" : "OFF";
+    else if (k == "RWPT_SEED")         val = std::to_string(opt.rwpt_seed);
+
     // System / Performance
     else if (k == "THREADS")           val = std::to_string(opt.num_threads);
 
@@ -946,6 +1163,24 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     for (auto& c : k) c = static_cast(toupper(static_cast(c)));
     std::string v(value);
 
+    // ── Exception guard at the C boundary ────────────────────────────────
+    // Thirty of this function's key branches parse with raw std::stod /
+    // std::stoi, which THROW on a malformed value. An exception crossing
+    // `extern "C"` terminates the process: measured, `swmm_options_set(e,
+    // "FV_CFL", "abc")` aborted, while `ROUTING_STEP = "xyz"` survived
+    // because that one branch already had a local try/catch. A caller that
+    // hands us a bad string — the MCP server's set_option tool takes
+    // arbitrary text, and a GUI line edit is transiently empty while being
+    // typed — must get SWMM_ERR_BADPARAM, never a dead process.
+    //
+    // One guard around the whole dispatch rather than 30 local ones: a
+    // per-site fix can miss a site (and a future branch would be born
+    // unguarded), whereas this cannot. Nothing in the dispatch throws for
+    // any reason OTHER than a bad parse — the rest is assignment — so the
+    // broad catch costs no diagnostic precision, and "no exception escapes
+    // a C entry point" is the correct contract regardless.
+    try {
+
     if (k == "FLOW_UNITS") {
         std::string vu(v);
         for (auto& c : vu) c = static_cast(toupper(static_cast(c)));
@@ -978,16 +1213,16 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     // zeroing the step.  Matches WET_STEP/DRY_STEP below and the OptionsHandler
     // parser, both of which use parse_time_seconds.
     else if (k == "ROUTING_STEP") {
-        opt.routing_step = openswmm::input::parse_time_seconds(v);
+        opt.routing_step = time_seconds_strict(v);
     }
     else if (k == "REPORT_STEP") {
-        opt.report_step = openswmm::input::parse_time_seconds(v);
+        opt.report_step = time_seconds_strict(v);
     }
     // Date/time keys are stored combined in a single OADate double. Get/set
     // for *_DATE addresses the integer (date) portion only and *_TIME the
     // fractional (time-of-day) portion, so the GUI can write them
     // independently — matching the OptionsHandler parser composition rule.
-    // The previous std::stod(v) implementation for START_DATE/END_DATE was
+    // The previous stod_strict(v) implementation for START_DATE/END_DATE was
     // a pre-existing bug — std::stod("01/01/2004") writes 1.0 — fixed here
     // as part of Slice CY (closes the §M.4 deferred get/set parity gap).
     else if (k == "START_DATE") {
@@ -997,7 +1232,7 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     }
     else if (k == "START_TIME") {
         opt.start_date = std::floor(opt.start_date)
-                       + openswmm::input::parse_time_seconds(v)
+                       + time_seconds_strict(v)
                          / openswmm::datetime::SecsPerDay;
         opt.total_duration_ms = -1.0;  // stale — recompute via totalDurationMs()
     }
@@ -1008,7 +1243,7 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     }
     else if (k == "END_TIME") {
         opt.end_date = std::floor(opt.end_date)
-                     + openswmm::input::parse_time_seconds(v)
+                     + time_seconds_strict(v)
                        / openswmm::datetime::SecsPerDay;
         opt.total_duration_ms = -1.0;  // stale — recompute via totalDurationMs()
     }
@@ -1018,11 +1253,14 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     }
     else if (k == "REPORT_START_TIME") {
         opt.report_start = std::floor(opt.report_start)
-                         + openswmm::input::parse_time_seconds(v)
+                         + time_seconds_strict(v)
                            / openswmm::datetime::SecsPerDay;
     }
     else if (k == "CRS") {
+        // Mirror into the spatial frame as well — see swmm_spatial_set_crs
+        // for why the two CRS stores must stay in step.
         opt.crs = v;
+        to_engine(engine)->context().spatial.crs = v;
     }
 
     // [REPORT] section keys (Slice BV.1 — added 2026-05-22). Boolean keys
@@ -1084,10 +1322,10 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     // ------------------------------------------------------------------
 
     // Step keys — accept seconds or HH:MM:SS per parse_time_seconds.
-    else if (k == "DRY_STEP")  opt.dry_step  = openswmm::input::parse_time_seconds(v);
-    else if (k == "WET_STEP")  opt.wet_step  = openswmm::input::parse_time_seconds(v);
-    else if (k == "RULE_STEP") opt.rule_step = openswmm::input::parse_time_seconds(v);
-    else if (k == "DRY_DAYS")  opt.dry_days  = std::stod(v);
+    else if (k == "DRY_STEP")  opt.dry_step  = time_seconds_strict(v);
+    else if (k == "WET_STEP")  opt.wet_step  = time_seconds_strict(v);
+    else if (k == "RULE_STEP") opt.rule_step = time_seconds_strict(v);
+    else if (k == "DRY_DAYS")  opt.dry_days  = stod_strict(v);
 
     // Sweep — accept MM/DD (legacy form, what the GUI writes), convert to
     // day-of-year via year-2000 anchor matching the parser convention.
@@ -1101,7 +1339,7 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
         std::from_chars(sp, se, sd);
         if (sm < 1 || sm > 12 || sd < 1 || sd > 31) return SWMM_ERR_BADPARAM;
         const int doy = openswmm::datetime::dayOfYear(
-            openswmm::datetime::encodeDate(2000,
+            openswmm::datetime::encodeDate(2001,   // non-leap: see the getter
                                            static_cast(sm),
                                            static_cast(sd)));
         if (k == "SWEEP_START") opt.sweep_start = doy;
@@ -1162,8 +1400,23 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
         if      (vu == "EXTRAN")       opt.surcharge_method = 0;
         else if (vu == "SLOT")         opt.surcharge_method = 1;
         else if (vu == "DYNAMIC_SLOT") opt.surcharge_method = 2;
+        else if (vu == "TPA")          opt.surcharge_method = 3;  // issue #156
+        else return SWMM_ERR_BADPARAM;
+    }
+    else if (k == "UNSTEADY_FRICTION") {  // issue #156
+        std::string vu(v);
+        for (auto& c : vu) c = static_cast(toupper(static_cast(c)));
+        if      (vu == "NONE")      opt.unsteady_friction = 0;
+        else if (vu == "VITKOVSKY") opt.unsteady_friction = 1;
         else return SWMM_ERR_BADPARAM;
     }
+    else if (k == "UF_K3")             opt.uf_k3 = stod_strict(v);
+    else if (k == "TPA_CELERITY")      opt.tpa_celerity = stod_strict(v);
+    else if (k == "REPORT_SIGNED_HEADS") {  // issue #156 O-6
+        const std::string vu = upper_copy(v);
+        opt.report_signed_heads =
+            (vu == "YES" || vu == "TRUE" || vu == "ON" || vu == "1") ? 1 : 0;
+    }
     else if (k == "NODE_CONTINUITY") {
         std::string vu(v);
         for (auto& c : vu) c = static_cast(toupper(static_cast(c)));
@@ -1197,69 +1450,69 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
     }
 
     // Numeric scalars.
-    else if (k == "DPS_CELERITY")      opt.dps_target_celerity = std::stod(v);
-    else if (k == "DPS_ALPHA")         opt.dps_alpha           = std::stod(v);
-    else if (k == "DPS_DECAY_TIME")    opt.dps_decay_time      = std::stod(v);
-    else if (k == "LENGTHENING_STEP")  opt.lengthening_step    = std::stod(v);
-    else if (k == "VARIABLE_STEP")     opt.variable_step       = std::stod(v);
+    else if (k == "DPS_CELERITY")      opt.dps_target_celerity = stod_strict(v);
+    else if (k == "DPS_ALPHA")         opt.dps_alpha           = stod_strict(v);
+    else if (k == "DPS_DECAY_TIME")    opt.dps_decay_time      = stod_strict(v);
+    else if (k == "LENGTHENING_STEP")  opt.lengthening_step    = stod_strict(v);
+    else if (k == "VARIABLE_STEP")     opt.variable_step       = stod_strict(v);
     // MINIMUM_STEP takes seconds or HH:MM:SS, same grammar as the [OPTIONS]
     // parser (OptionsHandler) and ROUTING_STEP above.
     else if (k == "MINIMUM_STEP")
-        opt.min_routing_step = openswmm::input::parse_time_seconds(v);
-    else if (k == "MAX_TRIALS")        opt.max_trials          = std::stoi(v);
-    else if (k == "HEAD_TOLERANCE")    opt.head_tol            = std::stod(v);
+        opt.min_routing_step = time_seconds_strict(v);
+    else if (k == "MAX_TRIALS")        opt.max_trials          = stoi_strict(v);
+    else if (k == "HEAD_TOLERANCE")    opt.head_tol            = stod_strict(v);
     // Flow tolerances are percentages per the INP/[OPTIONS] contract; the
     // OptionsHandler parser and the routing solver store them as fractions
     // (value / 100), so convert here to match — a raw std::stod stored 500%
     // for a "5" input and skewed dynamic-wave convergence.
-    else if (k == "LAT_FLOW_TOL")      opt.lat_flow_tol        = std::stod(v) / 100.0;
-    else if (k == "SYS_FLOW_TOL")      opt.sys_flow_tol        = std::stod(v) / 100.0;
-    else if (k == "MIN_SURFAREA")      opt.min_surf_area       = std::stod(v);
-    else if (k == "MIN_SLOPE")         opt.min_slope           = std::stod(v);
-    else if (k == "THREADS")           opt.num_threads         = std::stoi(v);
+    else if (k == "LAT_FLOW_TOL")      opt.lat_flow_tol        = stod_strict(v) / 100.0;
+    else if (k == "SYS_FLOW_TOL")      opt.sys_flow_tol        = stod_strict(v) / 100.0;
+    else if (k == "MIN_SURFAREA")      opt.min_surf_area       = stod_strict(v);
+    else if (k == "MIN_SLOPE")         opt.min_slope           = stod_strict(v);
+    else if (k == "THREADS")           opt.num_threads         = stoi_strict(v);
 
     // Explicit finite-volume solver. Same value grammar as the [OPTIONS]
     // parser, so a value round-trips between the file and this API unchanged.
-    else if (k == "FV_CELL_LENGTH")    opt.fv.cell_length      = std::stod(v);
-    else if (k == "FV_MIN_CELLS")      opt.fv.min_cells        = std::max(1, std::stoi(v));
-    else if (k == "FV_CFL")            opt.fv.cfl              = std::stod(v);
-    else if (k == "FV_ORDER")          opt.fv.order            = std::stoi(v);
-    else if (k == "FV_SLOT_CELERITY")  opt.fv.slot_celerity    = std::stod(v);
-    else if (k == "FV_DISPERSION")     opt.fv.dispersion       = std::stod(v);
-    else if (k == "FV_MIN_PARALLEL_CELLS")
-        opt.fv.min_parallel_cells = std::stol(v);
-    else if (k == "FV_COMPACTION") {
+    else if (k == "FV_CELL_LENGTH")    opt.fv.cell_length      = stod_strict(v);
+    else if (k == "FV_MIN_CELLS")      opt.fv.min_cells        = std::max(1, stoi_strict(v));
+    else if (k == "FV_CFL")            opt.fv.cfl              = stod_strict(v);
+    else if (k == "FV_ORDER")          opt.fv.order            = stoi_strict(v);
+    else if (k == "FV_SLOT_CELERITY")  opt.fv.slot_celerity    = stod_strict(v);
+    else if (k == "FV_PRESSURIZED_IMPLICIT") {
         const std::string vu = upper_copy(v);
-        opt.fv.compaction = !(vu == "NO" || vu == "FALSE" || vu == "0" || vu == "OFF");
+        opt.fv.pressurized_implicit =
+            (vu == "YES" || vu == "TRUE" || vu == "ON" || vu == "1");
     }
-    else if (k == "FV_NODE_COUPLING") {
+    else if (k == "FV_PRESSURE_CLOSURE") {  // issue #156
         const std::string vu = upper_copy(v);
-        if      (vu == "EXPLICIT")
-            opt.fv.node_coupling = openswmm::fv::NodeCoupling::EXPLICIT;
-        else if (vu == "SEMI_IMPLICIT")
-            opt.fv.node_coupling = openswmm::fv::NodeCoupling::SEMI_IMPLICIT;
+        if      (vu == "SLOT") opt.fv.pressure_closure = 0;
+        else if (vu == "TPA")  opt.fv.pressure_closure = 1;
         else return SWMM_ERR_BADPARAM;
     }
-    else if (k == "FV_NODE_DT") {
+    else if (k == "FV_DISPERSION")     opt.fv.dispersion       = stod_strict(v);
+    else if (k == "FV_MIN_PARALLEL_CELLS")
+        opt.fv.min_parallel_cells = stol_strict(v);
+    else if (k == "FV_COMPACTION") {
         const std::string vu = upper_copy(v);
-        if      (vu == "STABILITY") opt.fv.node_dt_limit = openswmm::fv::NodeDtLimit::STABILITY;
-        else if (vu == "NONE")      opt.fv.node_dt_limit = openswmm::fv::NodeDtLimit::NONE;
-        else return SWMM_ERR_BADPARAM;
+        opt.fv.compaction = !(vu == "NO" || vu == "FALSE" || vu == "0" || vu == "OFF");
     }
-    else if (k == "FV_NODE_PICARD")
-        opt.fv.node_picard_sweeps = std::max(1, std::stoi(v));
-    else if (k == "FV_NODE_CELL_COUPLING" || k == "FV_JUNCTION_MODEL") {
+    else if (k == "FV_NODE_CELL_COUPLING" || k == "FV_JUNCTION_MODEL" ||
+             k == "FV_NODE_COUPLING" || k == "FV_NODE_DT" ||
+             k == "FV_NODE_PICARD") {
         // Retired options, accepted and ignored: junctions are always
-        // algebraic interfaces now.
+        // algebraic interfaces, storage-node coupling is always semi-implicit
+        // with a single sweep, and the node accuracy bound is always armed.
+        // The .inp parser warns when a retired key asks for the behaviour that
+        // no longer exists; the C API stays silent, as for the older two.
     }
     else if (k == "FV_LTS") {
         const std::string vu = upper_copy(v);
         opt.fv.lts = !(vu == "NO" || vu == "FALSE" || vu == "0" || vu == "OFF");
     }
     else if (k == "FV_LTS_MAX_TIERS")
-        opt.fv.lts_max_tiers = std::max(1, std::stoi(v));
+        opt.fv.lts_max_tiers = std::max(1, stoi_strict(v));
     else if (k == "FV_CFL_CENSUS_INTERVAL")
-        opt.fv.cfl_census_interval = std::max(1, std::stoi(v));
+        opt.fv.cfl_census_interval = std::max(1, stoi_strict(v));
     else if (k == "FV_RIEMANN") {
         const std::string vu = upper_copy(v);
         if      (vu == "HLL")  opt.fv.riemann = openswmm::fv::RiemannSolver::HLL;
@@ -1306,10 +1559,61 @@ SWMM_ENGINE_API int swmm_options_set(SWMM_Engine engine,
         else return SWMM_ERR_BADPARAM;
     }
 
+    // Quality & transport (subplan Y0) — the setter half of the getter
+    // block above. Enum keys REJECT unknown tokens (the FV precedent the
+    // hydration contract's rejectBadEnumTokens case relies on) so a typo
+    // surfaces as a failed set instead of a silently lost edit.
+    else if (k == "QUALITY_SOLVER") {
+        const std::string vu = upper_copy(v);
+        if      (vu == "LEGACY")
+            opt.quality_solver = openswmm::QualitySolverKind::LEGACY;
+        else if (vu == "EULERIAN_ARD" || vu == "ARD")
+            opt.quality_solver = openswmm::QualitySolverKind::EULERIAN_ARD;
+        else if (vu == "LAGRANGIAN" || vu == "LARD")
+            opt.quality_solver = openswmm::QualitySolverKind::LAGRANGIAN;
+        else return SWMM_ERR_BADPARAM;
+    }
+    else if (k == "WATER_AGE") {
+        const std::string vu = upper_copy(v);
+        opt.water_age = (vu == "YES" || vu == "ON" || vu == "TRUE" ||
+                         vu == "1");
+    }
+    else if (k == "OUTFALL_BACKFLOW_QUALITY") {
+        const std::string vu = upper_copy(v);
+        if      (vu == "LAST") opt.outfall_backflow_zero = false;
+        else if (vu == "ZERO") opt.outfall_backflow_zero = true;
+        else return SWMM_ERR_BADPARAM;
+    }
+    else if (k == "HEAT_TRANSPORT") {
+        const std::string vu = upper_copy(v);
+        opt.heat_transport = (vu == "YES" || vu == "ON" || vu == "TRUE" ||
+                              vu == "1");
+    }
+    else if (k == "QUALITY_STEP")
+        opt.quality_step = std::max(0.0, stod_strict(v));
+    else if (k == "MAX_SEGMENTS_PER_LINK")
+        opt.max_segments_per_link = std::max(2, stoi_strict(v));
+    else if (k == "DISPERSION") {
+        const std::string vu = upper_copy(v);
+        if      (vu == "RWPT")                 opt.lard_rwpt = true;
+        else if (vu == "OFF" || vu == "NONE")  opt.lard_rwpt = false;
+        else return SWMM_ERR_BADPARAM;
+    }
+    else if (k == "RWPT_SEED")
+        opt.rwpt_seed = stoi_strict(v);
+
     else {
         return SWMM_ERR_BADPARAM;
     }
 
+    } catch (...) {
+        // A malformed numeric for a recognised key. The key was valid, the
+        // value was not — BADPARAM is the same answer an out-of-range enum
+        // token gets, and the option keeps its previous value because the
+        // throwing branch assigned nothing.
+        return SWMM_ERR_BADPARAM;
+    }
+
     return SWMM_OK;
 }
 
@@ -1333,8 +1637,10 @@ SWMM_ENGINE_API int swmm_options_get_ext(SWMM_Engine engine,
     // of truth, wired through ctx.twod_io) instead of the generic
     // ext_options map — see swmm_options_set_ext for the write side.
     if (ctx.twod_io.options && openswmm::twoD::is2DOptionKey(key)) {
-        const std::string v =
-            openswmm::twoD::format2DOptionValue(*ctx.twod_io.options, key);
+        // E2: the infiltration keys resolve AUTO / unset against the rows;
+        // U5: the groundwater keys likewise against the [2D_AQUIFER*] rows.
+        const std::string v = openswmm::twoD::format2DOptionValueEx(
+            *ctx.twod_io.options, ctx.twod_io.infil, ctx.twod_io.aquifer, key);
         std::strncpy(buf, v.c_str(), static_cast(buflen - 1));
         buf[buflen - 1] = '\0';
         return SWMM_OK;
@@ -1357,6 +1663,18 @@ SWMM_ENGINE_API int swmm_options_set_ext(SWMM_Engine engine,
 
     auto& ctx = to_engine(engine)->context();
 
+    // WRITE_ABSOLUTE_PATHS is a first-class SimulationOptions field, not an
+    // extension key. Letting it fall through to ext_options produced a
+    // round-trip asymmetry: the save itself still wrote RELATIVE paths (the
+    // writer reads the bool, which stayed false), but the emitted deck carried
+    // WRITE_ABSOLUTE_PATHS YES and so re-opened with the opt-out armed.
+    if (upper_key(key) == "WRITE_ABSOLUTE_PATHS") {
+        ctx.options.write_absolute_paths =
+            openswmm::input::Tokenizer::parse_boolean(value);
+        ctx.options.ext_options.erase(key);
+        return SWMM_OK;
+    }
+
 #ifdef OPENSWMM_HAS_2D
     // [2D_MESH_FILE] reference: route to the live SolverOptions2D::mesh_file
     // so the GUI/API can attach (or detach) an external .2dm and have the
@@ -1392,6 +1710,20 @@ SWMM_ENGINE_API int swmm_options_set_ext(SWMM_Engine engine,
             openswmm::twoD::parse2DOptionsLine({key, value}, tmp);
         if (!err.empty()) return SWMM_ERR_BADPARAM;
         *ctx.twod_io.options = std::move(tmp);
+        // E2: INFIL_STEP is an alias — write through to the Infil2D options
+        // (the C API's swmm_infil2d_get_options and the writer read there).
+        if (ctx.twod_io.infil && upper_key(key) == "INFIL_STEP") {
+            ctx.twod_io.infil->options().infil_step = ctx.twod_io.options->infil_step;
+            ctx.twod_io.options->infil_step = 0.0;
+        }
+        // U5: GW_ET is an alias of [2D_AQUIFER_OPTIONS] GW_ET — write through
+        // so a host that sets it here and the 2D Groundwater editor are
+        // editing ONE value, not two that disagree.
+        if (ctx.twod_io.aquifer && upper_key(key) == "GW_ET") {
+            ctx.twod_io.aquifer->options.gw_et    = ctx.twod_io.options->gw_et;
+            ctx.twod_io.aquifer->options.authored = true;
+            ctx.twod_io.options->gw_et.clear();
+        }
         ctx.options.ext_options.erase(key);
         return SWMM_OK;
     }
@@ -1404,7 +1736,10 @@ SWMM_ENGINE_API int swmm_options_set_ext(SWMM_Engine engine,
 SWMM_ENGINE_API int swmm_get_crs(SWMM_Engine engine, char* buf, int buflen) {
     CHECK_HANDLE(engine);
     if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
-    const auto& crs = to_engine(engine)->context().options.crs;
+    // Prefer the [OPTIONS] value; fall back to the spatial frame, which is
+    // the only store a GeoPackage open fills (see swmm_spatial_set_crs).
+    const auto& ctx = to_engine(engine)->context();
+    const auto& crs = !ctx.options.crs.empty() ? ctx.options.crs : ctx.spatial.crs;
     if (crs.empty()) return SWMM_ERR_CRS;
     std::strncpy(buf, crs.c_str(), static_cast(buflen - 1));
     buf[buflen - 1] = '\0';
diff --git a/src/engine/core/openswmm_nodes_impl.cpp b/src/engine/core/openswmm_nodes_impl.cpp
index b0504297a..3effb9490 100644
--- a/src/engine/core/openswmm_nodes_impl.cpp
+++ b/src/engine/core/openswmm_nodes_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_nodes_impl.cpp
  * @brief C API implementation — node identity, creation, properties, state, bulk.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -173,6 +189,18 @@ SWMM_ENGINE_API int swmm_node_set_initial_depth(SWMM_Engine engine, int idx, dou
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_node_set_rim_depth(SWMM_Engine engine, int idx, double depth) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
+    // Rendering-only (see header): stored like any other length, read by no
+    // solver path. Negative input means "unset".
+    const double d = (depth > 0.0) ? to_internal(ctx, openswmm::ucf::LENGTH, depth) : 0.0; // units
+    ctx.nodes.rim_depth[static_cast(idx)] = d;
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Geometry getters
 // ============================================================================
@@ -216,6 +244,39 @@ SWMM_ENGINE_API int swmm_node_virtual_eligible(SWMM_Engine engine, int idx, int*
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_node_is_inlet(SWMM_Engine engine, int idx, int* is_inlet) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
+    if (is_inlet) {
+        const auto ui = static_cast(idx);
+        *is_inlet = (ui < ctx.nodes.is_inlet.size() &&
+                     ctx.nodes.is_inlet[ui]) ? 1 : 0;
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_node_inlet_eligible(SWMM_Engine engine, int idx,
+                                             int for_drop_inlet, int* rule_code) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
+    if (rule_code)
+        *rule_code = openswmm::edit::ij_rule_violation(ctx, idx, for_drop_inlet != 0);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_node_set_inlet(SWMM_Engine engine, int idx, int make_inlet) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
+    const int code = openswmm::edit::ij_set_inlet(ctx, idx, make_inlet != 0);
+    if (code == 0)  return SWMM_OK;
+    if (code == -1) return SWMM_ERR_BADPARAM;   // non-junction node
+    return code;   // distinct ERR_VJ_* / ERR_IJ_* rule code (openswmm_nodes.h)
+}
+
 SWMM_ENGINE_API int swmm_node_get_invert_elev(SWMM_Engine engine, int idx, double* elev) {
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
@@ -232,6 +293,14 @@ SWMM_ENGINE_API int swmm_node_get_max_depth(SWMM_Engine engine, int idx, double*
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_node_get_rim_depth(SWMM_Engine engine, int idx, double* depth) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
+    if (depth) *depth = to_display(ctx, openswmm::ucf::LENGTH, ctx.nodes.rim_depth[static_cast(idx)]); // units
+    return SWMM_OK;
+}
+
 // ============================================================================
 // Hydraulic state getters/setters
 // ============================================================================
@@ -304,10 +373,6 @@ SWMM_ENGINE_API int swmm_node_set_lateral_inflow(SWMM_Engine engine, int idx, do
     CHECK_RUNNING(ctx);
     CHECK_INDEX(idx >= 0 && idx < ctx.n_nodes());
     auto uidx = static_cast(idx);
-    // Virtual junctions cannot receive lateral inflow (zero-storage contract).
-    if (uidx < ctx.nodes.is_virtual.size() && ctx.nodes.is_virtual[uidx] &&
-        flow != 0.0)
-        return SWMM_ERR_BADPARAM;
     if (uidx >= ctx.nodes.user_lat_flow.size()) {
         // Lazily resize if not yet allocated (e.g. hot-started context)
         ctx.nodes.user_lat_flow.resize(ctx.nodes.lat_flow.size(), 0.0);
@@ -430,14 +495,6 @@ SWMM_ENGINE_API int swmm_node_set_lat_inflows_bulk(SWMM_Engine engine, const dou
     CHECK_RUNNING(ctx);
     if (!buf || count <= 0) return SWMM_ERR_BADPARAM;
     const int n = std::min(count, ctx.n_nodes());
-    // Virtual junctions cannot receive lateral inflow: a nonzero entry for a
-    // virtual node rejects the whole call so the caller can fix its buffer.
-    for (int i = 0; i < n; ++i) {
-        const auto ui = static_cast(i);
-        if (ui < ctx.nodes.is_virtual.size() && ctx.nodes.is_virtual[ui] &&
-            buf[i] != 0.0)
-            return SWMM_ERR_BADPARAM;
-    }
     for (int i = 0; i < n; ++i)
         ctx.nodes.lat_flow[static_cast(i)] = to_internal(ctx, openswmm::ucf::FLOW, buf[i]); // units
     return SWMM_OK;
diff --git a/src/engine/core/openswmm_pollutants_impl.cpp b/src/engine/core/openswmm_pollutants_impl.cpp
index 6fcc8c31e..985692ba8 100644
--- a/src/engine/core/openswmm_pollutants_impl.cpp
+++ b/src/engine/core/openswmm_pollutants_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_pollutants_impl.cpp
  * @brief C API implementation — pollutant identity, creation, properties, quality injection.
@@ -7,10 +23,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
+#include "Constants.hpp"
 #include "../../../include/openswmm/engine/openswmm_pollutants.h"
 
 namespace {
@@ -177,7 +194,10 @@ SWMM_ENGINE_API int swmm_pollutant_set_kdecay(SWMM_Engine engine, int idx, doubl
     CHECK_HANDLE(engine);
     auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(idx >= 0 && idx < ctx.n_pollutants());
-    ctx.pollutants.k_decay[static_cast(idx)] = k;
+    // The API speaks deck units (1/day) — the header's contract all
+    // along; storage is 1/sec (KD1), like legacy's swmm_POLLUT_KDECAY.
+    ctx.pollutants.k_decay[static_cast(idx)] =
+        k / openswmm::constants::SEC_PER_DAY;
     return SWMM_OK;
 }
 
@@ -239,7 +259,8 @@ SWMM_ENGINE_API int swmm_pollutant_get_kdecay(SWMM_Engine engine, int idx, doubl
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(idx >= 0 && idx < ctx.n_pollutants());
-    if (k) *k = ctx.pollutants.k_decay[static_cast(idx)];
+    if (k) *k = ctx.pollutants.k_decay[static_cast(idx)] *
+                openswmm::constants::SEC_PER_DAY;
     return SWMM_OK;
 }
 
diff --git a/src/engine/core/openswmm_process_components_impl.cpp b/src/engine/core/openswmm_process_components_impl.cpp
new file mode 100644
index 000000000..4d817f040
--- /dev/null
+++ b/src/engine/core/openswmm_process_components_impl.cpp
@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_process_components_impl.cpp
+ * @brief C API implementation — [PROCESS_COMPONENTS] registrations (E-C3).
+ *
+ * @see include/openswmm/engine/openswmm_process_components.h
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "openswmm_api_common.hpp"
+#include "../../../include/openswmm/engine/openswmm_process_components.h"
+#include "../plugins/ProcessComponentRegistry.hpp"   // U1: built-in catalogue
+
+#include 
+#include 
+
+namespace {
+
+inline void copy_to_buf(const std::string& src, char* buf, int buflen) {
+    if (!buf || buflen <= 0) return;
+    const int copy_len = std::min(static_cast(src.size()), buflen - 1);
+    std::memcpy(buf, src.c_str(), static_cast(copy_len));
+    buf[copy_len] = '\0';
+}
+
+} // namespace
+
+extern "C" {
+
+SWMM_ENGINE_API int swmm_process_component_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return static_cast(
+        to_engine(engine)->context().process_component_specs.size());
+}
+
+SWMM_ENGINE_API int swmm_process_component_get(SWMM_Engine engine, int idx,
+        char* id_buf, int id_len, char* config_buf, int config_len,
+        char* resolved_buf, int resolved_len) {
+    CHECK_HANDLE(engine);
+    const auto& specs =
+        to_engine(engine)->context().process_component_specs;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(specs.size()));
+    if (!id_buf || id_len <= 0 || !config_buf || config_len <= 0 ||
+        !resolved_buf || resolved_len <= 0)
+        return SWMM_ERR_BADPARAM;
+    const auto& s = specs[static_cast(idx)];
+    copy_to_buf(s.id, id_buf, id_len);
+    copy_to_buf(s.config_path, config_buf, config_len);
+    copy_to_buf(s.resolved_config_path, resolved_buf, resolved_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_process_component_known_count(void) {
+    return static_cast(
+        openswmm::components::ProcessComponentRegistry::instance().known_ids().size());
+}
+
+SWMM_ENGINE_API int swmm_process_component_known_get(int idx,
+        char* id_buf, int id_len, char* desc_buf, int desc_len,
+        int* implemented) {
+    const auto& reg = openswmm::components::ProcessComponentRegistry::instance();
+    const auto ids = reg.known_ids();
+    if (idx < 0 || idx >= static_cast(ids.size())) return SWMM_ERR_BADINDEX;
+    const std::string& id = ids[static_cast(idx)];
+    const auto* entry = reg.find(id);
+    if (!entry) return SWMM_ERR_INTERNAL;
+    copy_to_buf(id, id_buf, id_len);
+    copy_to_buf(entry->description, desc_buf, desc_len);
+    if (implemented) *implemented = entry->apply ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_process_component_find(SWMM_Engine engine,
+        const char* id) {
+    if (!engine || !id) return -1;
+    const auto& specs =
+        to_engine(engine)->context().process_component_specs;
+    for (std::size_t i = 0; i < specs.size(); ++i)
+        if (specs[i].id == id) return static_cast(i);
+    return -1;
+}
+
+SWMM_ENGINE_API int swmm_process_component_register(SWMM_Engine engine,
+        const char* id, const char* config_path) {
+    CHECK_HANDLE(engine);
+    if (!id || !*id) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    if (swmm_process_component_find(engine, id) >= 0)
+        return SWMM_ERR_BADPARAM;   // duplicate id — the parser's rule
+    openswmm::ProcessComponentSpec spec;
+    spec.id = id;
+    if (config_path) spec.config_path = config_path;
+    // The file need not exist yet: the GUI's "create component + config
+    // file" flow registers first, then swmm_reactions_save writes it;
+    // resolve_process_components reads it at the next open (D-RC8).
+    ctx.process_component_specs.push_back(std::move(spec));
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_process_component_remove(SWMM_Engine engine,
+        int idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& specs = ctx.process_component_specs;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(specs.size()));
+    specs.erase(specs.begin() + static_cast(idx));
+    return SWMM_OK;
+}
+
+} // extern "C"
diff --git a/src/engine/core/openswmm_quality_impl.cpp b/src/engine/core/openswmm_quality_impl.cpp
index b721b346a..2cd63ec79 100644
--- a/src/engine/core/openswmm_quality_impl.cpp
+++ b/src/engine/core/openswmm_quality_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_quality_impl.cpp
  * @brief C API implementation — landuse, buildup, washoff, treatment.
@@ -7,12 +23,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
 #include "../../../include/openswmm/engine/openswmm_quality.h"
 #include "../quality/Treatment.hpp"
+#include "../quality/MsxSurfaceQuality.hpp"   // BW-MSX
 
 #include 
 
@@ -179,6 +196,21 @@ SWMM_ENGINE_API int swmm_buildup_set(SWMM_Engine engine, int lu_idx, int pollut_
     CHECK_HANDLE(engine);
     auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(lu_idx >= 0 && lu_idx < ctx.n_landuses());
+    // BW-MSX: indices past the pollutants address the reactions component's
+    // species (surface species index = n_pollutants + m).
+    if (pollut_idx >= ctx.n_pollutants()) {
+        auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        if (ms.n_landuses != ctx.n_landuses() || ms.n_species != ctx.reactions.n_species())
+            ms.resize_params(ctx.n_landuses(), ctx.reactions.n_species());
+        const auto k = ms.pidx(lu_idx, m);
+        ms.bu_type[k] = func_type; ms.bu_c1[k] = c1; ms.bu_c2[k] = c2; ms.bu_c3[k] = c3;
+        ms.bu_normalizer[k] = normalizer;
+        ms.resolved = true;
+        openswmm::msxsurf::refreshDerived(ctx);
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
     // Ensure buildup matrix is sized
@@ -207,6 +239,24 @@ SWMM_ENGINE_API int swmm_buildup_get(SWMM_Engine engine, int lu_idx, int pollut_
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(lu_idx >= 0 && lu_idx < ctx.n_landuses());
+    if (pollut_idx >= ctx.n_pollutants()) {          // BW-MSX species index
+        const auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        if (ms.n_landuses != ctx.n_landuses() || ms.n_species != ctx.reactions.n_species()) {
+            if (func_type) *func_type = 0;
+            if (c1) *c1 = 0.0; if (c2) *c2 = 0.0; if (c3) *c3 = 0.0;
+            if (normalizer) *normalizer = 0;
+            return SWMM_OK;
+        }
+        const auto k = ms.pidx(lu_idx, m);
+        if (func_type)  *func_type  = ms.bu_type[k];
+        if (c1)         *c1         = ms.bu_c1[k];
+        if (c2)         *c2         = ms.bu_c2[k];
+        if (c3)         *c3         = ms.bu_c3[k];
+        if (normalizer) *normalizer = ms.bu_normalizer[k];
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
     auto k = static_cast(lu_idx) *
@@ -233,6 +283,18 @@ SWMM_ENGINE_API int swmm_washoff_set(SWMM_Engine engine, int lu_idx, int pollut_
     CHECK_HANDLE(engine);
     auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(lu_idx >= 0 && lu_idx < ctx.n_landuses());
+    if (pollut_idx >= ctx.n_pollutants()) {          // BW-MSX species index
+        auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        if (ms.n_landuses != ctx.n_landuses() || ms.n_species != ctx.reactions.n_species())
+            ms.resize_params(ctx.n_landuses(), ctx.reactions.n_species());
+        const auto k = ms.pidx(lu_idx, m);
+        ms.wo_type[k] = func_type; ms.wo_coeff[k] = coeff; ms.wo_expon[k] = expon;
+        ms.wo_sweep_effic[k] = sweep_effic; ms.wo_bmp_effic[k] = bmp_effic;
+        ms.resolved = true;
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
     // Ensure washoff matrix is sized
@@ -260,6 +322,24 @@ SWMM_ENGINE_API int swmm_washoff_get(SWMM_Engine engine, int lu_idx, int pollut_
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(lu_idx >= 0 && lu_idx < ctx.n_landuses());
+    if (pollut_idx >= ctx.n_pollutants()) {          // BW-MSX species index
+        const auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        if (ms.n_landuses != ctx.n_landuses() || ms.n_species != ctx.reactions.n_species()) {
+            if (func_type) *func_type = 0;
+            if (coeff) *coeff = 0.0; if (expon) *expon = 0.0;
+            if (sweep_effic) *sweep_effic = 0.0; if (bmp_effic) *bmp_effic = 0.0;
+            return SWMM_OK;
+        }
+        const auto k = ms.pidx(lu_idx, m);
+        if (func_type)   *func_type   = ms.wo_type[k];
+        if (coeff)       *coeff       = ms.wo_coeff[k];
+        if (expon)       *expon       = ms.wo_expon[k];
+        if (sweep_effic) *sweep_effic = ms.wo_sweep_effic[k];
+        if (bmp_effic)   *bmp_effic   = ms.wo_bmp_effic[k];
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
     auto k = static_cast(lu_idx) *
diff --git a/src/engine/core/openswmm_reactions_impl.cpp b/src/engine/core/openswmm_reactions_impl.cpp
new file mode 100644
index 000000000..bf85af90b
--- /dev/null
+++ b/src/engine/core/openswmm_reactions_impl.cpp
@@ -0,0 +1,827 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_reactions_impl.cpp
+ * @brief C API implementation — reaction-system validation + discovery
+ *        (E-C1).
+ *
+ * @see include/openswmm/engine/openswmm_reactions.h
+ * @ingroup engine_api
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "openswmm_api_common.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "../../../include/openswmm/engine/openswmm_reactions.h"
+
+#include "../transport/components/ReactionModule/ReactionExpression.hpp"
+#include "../transport/components/ReactionModule/ReactionsComponent.hpp"
+#include "../transport/components/ReactionModule/ReactionsWriter.hpp"
+#include "../plugins/ProcessComponentRegistry.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace {
+
+/// Copy a std::string into a NUL-terminated caller buffer, truncating safely.
+inline void copy_to_buf(const std::string& src, char* buf, int buflen) {
+    if (!buf || buflen <= 0) return;
+    const int copy_len = std::min(static_cast(src.size()), buflen - 1);
+    std::memcpy(buf, src.c_str(), static_cast(copy_len));
+    buf[copy_len] = '\0';
+}
+
+/// True when any compiled expression pushes slot @p idx of kind @p op —
+/// the authoritative referenced-check for remove refusals (D-RC3): the
+/// compiled tokens are what evaluation actually reads, so a scan over the
+/// pool cannot miss or over-count.
+bool pool_references(const openswmm::ReactionData& rx, uint8_t op, int idx) {
+    for (const auto& t : rx.token_pool)
+        if (t.op == op && t.idx == idx) return true;
+    return false;
+}
+
+/// Rebuild the species registry's MSX block from ctx.reactions after a
+/// species add/remove (D-RC3): snapshot every row after the old MSX block
+/// (the reserved species live there), truncate, re-add the MSX species in
+/// ReactionData order, restore the tail. Legal in BUILDING/OPENED only —
+/// nothing downstream has latched registry indexes before initialize().
+void rebuild_msx_registry(openswmm::SimulationContext& ctx, int old_base,
+                          int old_n_msx) {
+    auto& reg = ctx.species_registry;
+    auto& rx  = ctx.reactions;
+    const int base = (old_base >= 0) ? old_base : reg.pollutant_count();
+    struct Row { std::string name; openswmm::SpeciesKind kind;
+                 std::string units; };
+    std::vector tail;
+    for (int i = base + ((old_base >= 0) ? old_n_msx : 0);
+         i < reg.count(); ++i)
+        tail.push_back({reg.name(i), reg.kind(i), reg.units(i)});
+
+    reg.truncate_to(base);
+    rx.registry_base = -1;
+    for (int s = 0; s < rx.n_species(); ++s) {
+        const auto us = static_cast(s);
+        const int idx = reg.add(rx.species_name[us],
+                                rx.species_is_wall[us]
+                                    ? openswmm::SpeciesKind::MSX_WALL
+                                    : openswmm::SpeciesKind::MSX_BULK,
+                                rx.species_units[us]);
+        if (rx.registry_base < 0) rx.registry_base = idx;
+    }
+    for (auto& r : tail)
+        reg.add(std::move(r.name), r.kind, std::move(r.units));
+}
+
+/// Recompile after a mutation; on failure restore the given backups and
+/// return false (D-RC5: the engine never holds an uncompilable system).
+bool recompile_or_rollback(openswmm::SimulationContext& ctx,
+                           openswmm::ReactionData& rx_backup,
+                           openswmm::SpeciesRegistry& reg_backup) {
+    std::vector errs;
+    if (openswmm::transport::recompileReactionSystem(ctx, errs)) return true;
+    ctx.reactions        = std::move(rx_backup);
+    ctx.species_registry = std::move(reg_backup);
+    return false;
+}
+
+} // namespace
+
+extern "C" {
+
+SWMM_ENGINE_API int swmm_reaction_validate_expression(SWMM_Engine engine,
+        int scope, const char* expr, char* errbuf, int buflen, int* col_out) {
+    CHECK_HANDLE(engine);
+    if (errbuf && buflen > 0) errbuf[0] = '\0';
+    if (col_out) *col_out = -1;
+    if (!expr) return SWMM_ERR_BADPARAM;
+    if (scope != SWMM_RXN_SCOPE_TERM && scope != SWMM_RXN_SCOPE_PIPE &&
+        scope != SWMM_RXN_SCOPE_TANK)
+        return SWMM_ERR_BADPARAM;
+
+    const auto& ctx = to_engine(engine)->context();
+    const auto& rx  = ctx.reactions;
+
+    openswmm::transport::RxSymbols sym;
+    sym.species    = &rx.species_name;
+    sym.coefs      = &rx.coef_name;
+    sym.terms      = &rx.term_name;
+    sym.pollutants = &ctx.pollutant_names.names();
+    // D-RC1: validation accepts references to ALL terms — the forward-only
+    // rule is a file-ordering property enforced at apply time.
+    sym.max_term   = static_cast(rx.term_name.size());
+
+    std::vector pool;   // scratch, discarded
+    openswmm::transport::RxExprSpan span;
+    int col = -1;
+    const std::string err = openswmm::transport::compileReactionExpression(
+        expr, sym, pool, span, col);
+    if (err.empty()) return SWMM_OK;
+
+    if (errbuf && buflen > 0) copy_to_buf(err, errbuf, buflen);
+    if (col_out) *col_out = col;
+    return SWMM_ERR_BADPARAM;
+}
+
+// ============================================================================
+// Model discovery
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_reaction_species_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return to_engine(engine)->context().reactions.n_species();
+}
+
+SWMM_ENGINE_API int swmm_reaction_species_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, int* is_wall,
+        char* units, int units_len, double* atol, double* rtol) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(idx >= 0 && idx < rx.n_species());
+    if (!name || name_len <= 0 || !is_wall || !units || units_len <= 0 ||
+        !atol || !rtol)
+        return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(idx);
+    copy_to_buf(rx.species_name[u], name, name_len);
+    *is_wall = rx.species_is_wall[u] ? 1 : 0;
+    copy_to_buf(rx.species_units[u], units, units_len);
+    *atol = rx.species_atol[u];
+    *rtol = rx.species_rtol[u];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_coeff_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return static_cast(
+        to_engine(engine)->context().reactions.coef_name.size());
+}
+
+SWMM_ENGINE_API int swmm_reaction_coeff_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, int* is_param, double* value) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(idx >= 0 &&
+                idx < static_cast(rx.coef_name.size()));
+    if (!name || name_len <= 0 || !is_param || !value)
+        return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(idx);
+    copy_to_buf(rx.coef_name[u], name, name_len);
+    *is_param = rx.coef_is_param[u] ? 1 : 0;
+    *value    = rx.coef_value[u];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_term_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return static_cast(
+        to_engine(engine)->context().reactions.term_name.size());
+}
+
+SWMM_ENGINE_API int swmm_reaction_term_get(SWMM_Engine engine, int idx,
+        char* name, int name_len, char* expr, int expr_len) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(idx >= 0 &&
+                idx < static_cast(rx.term_name.size()));
+    if (!name || name_len <= 0 || !expr || expr_len <= 0)
+        return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(idx);
+    copy_to_buf(rx.term_name[u], name, name_len);
+    copy_to_buf(rx.term_expr_src[u], expr, expr_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_expr_get(SWMM_Engine engine, int scope,
+        int species_idx, int* form, char* expr, int expr_len) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(species_idx >= 0 && species_idx < rx.n_species());
+    if (!form || !expr || expr_len <= 0) return SWMM_ERR_BADPARAM;
+    if (scope != SWMM_RXN_SCOPE_PIPE && scope != SWMM_RXN_SCOPE_TANK)
+        return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(species_idx);
+    if (scope == SWMM_RXN_SCOPE_PIPE) {
+        *form = static_cast(rx.pipe_form[u]);
+        copy_to_buf(rx.pipe_expr_src[u], expr, expr_len);
+    } else {
+        *form = static_cast(rx.tank_form[u]);
+        copy_to_buf(rx.tank_expr_src[u], expr, expr_len);
+    }
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_option_get(SWMM_Engine engine,
+        const char* key, char* value, int value_len) {
+    CHECK_HANDLE(engine);
+    if (!key || !value || value_len <= 0) return SWMM_ERR_BADPARAM;
+    const auto& rx = to_engine(engine)->context().reactions;
+
+    std::string k(key);
+    for (auto& ch : k)
+        ch = static_cast(std::toupper(static_cast(ch)));
+
+    std::string v;
+    if (k == "SOLVER") {
+        static const char* kTok[] = {"EUL", "RK5", "ROS2", "BDF2"};
+        v = kTok[static_cast(rx.solver)];
+    } else if (k == "COUPLING") {
+        v = (static_cast(rx.coupling) == 1) ? "FULL" : "NONE";
+    } else if (k == "RATE_UNITS") {
+        static const char* kTok[] = {"SEC", "MIN", "HR", "DAY"};
+        v = kTok[static_cast(rx.rate_units)];
+    } else if (k == "AREA_UNITS") {
+        static const char* kTok[] = {"FT2", "M2", "CM2"};
+        v = kTok[static_cast(rx.area_units)];
+    } else if (k == "TIMESTEP") {
+        v = std::to_string(rx.timestep);
+    } else if (k == "ATOL") {
+        v = std::to_string(rx.atol);
+    } else if (k == "RTOL") {
+        v = std::to_string(rx.rtol);
+    } else if (k == "TEMPERATURE") {
+        v = std::to_string(rx.default_temp_c);
+    } else {
+        return SWMM_ERR_BADPARAM;
+    }
+    copy_to_buf(v, value, value_len);
+    return SWMM_OK;
+}
+
+// ============================================================================
+// CRUD (E-C2) — BUILDING/OPENED, eager validation, rollback on failure
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_reaction_species_add(SWMM_Engine engine,
+        const char* name, int is_wall, const char* units, double atol,
+        double rtol) {
+    CHECK_HANDLE(engine);
+    if (!name || !*name || !units || atol < 0.0 || rtol < 0.0)
+        return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    // Names are unique across ALL kinds (an MSX species may not shadow a
+    // pollutant or reserved species) — the parser's collision rule — and a
+    // species named like a coefficient or term would silently SHADOW it in
+    // expressions (resolution order: species first), so those collide too.
+    if (ctx.species_registry.find(name) >= 0 ||
+        ctx.reactions.find_coef(name) >= 0 ||
+        ctx.reactions.find_term(name) >= 0)
+        return SWMM_ERR_BADPARAM;
+
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    auto& rx = ctx.reactions;
+    const int old_base = rx.registry_base;
+    const int old_n    = rx.n_species();
+    rx.species_name.push_back(name);
+    rx.species_is_wall.push_back(is_wall ? 1 : 0);
+    rx.species_units.push_back(units);
+    rx.species_atol.push_back(atol);
+    rx.species_rtol.push_back(rtol);
+    rx.pipe_form.push_back(openswmm::ReactionExprForm::NONE);
+    rx.pipe_expr_src.emplace_back();
+    rx.tank_form.push_back(openswmm::ReactionExprForm::NONE);
+    rx.tank_expr_src.emplace_back();
+    rx.init_global.push_back(0.0);
+    rebuild_msx_registry(ctx, old_base, old_n);
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    rx.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_species_remove(SWMM_Engine engine,
+        int idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(idx >= 0 && idx < rx.n_species());
+    // D-RC3: refuse while any compiled expression references the species.
+    if (pool_references(rx, openswmm::RxToken::PUSH_SPECIES, idx))
+        return SWMM_ERR_BADPARAM;
+
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    const int old_base = rx.registry_base;
+    const int old_n    = rx.n_species();
+    const auto u = static_cast(idx);
+    // Erase the row from EVERY index-aligned vector (the D-RC3 hazard).
+    rx.species_name.erase(rx.species_name.begin() + u);
+    rx.species_is_wall.erase(rx.species_is_wall.begin() + u);
+    rx.species_units.erase(rx.species_units.begin() + u);
+    rx.species_atol.erase(rx.species_atol.begin() + u);
+    rx.species_rtol.erase(rx.species_rtol.begin() + u);
+    rx.pipe_form.erase(rx.pipe_form.begin() + u);
+    rx.pipe_expr_src.erase(rx.pipe_expr_src.begin() + u);
+    rx.tank_form.erase(rx.tank_form.begin() + u);
+    rx.tank_expr_src.erase(rx.tank_expr_src.begin() + u);
+    rx.init_global.erase(rx.init_global.begin() + u);
+    // Per-element initial rows for the species vanish with it; higher
+    // species indexes shift down.
+    for (int r = static_cast(rx.init_elem_idx.size()) - 1; r >= 0; --r) {
+        const auto ur = static_cast(r);
+        if (rx.init_elem_species[ur] == idx) {
+            rx.init_elem_is_link.erase(rx.init_elem_is_link.begin() + ur);
+            rx.init_elem_idx.erase(rx.init_elem_idx.begin() + ur);
+            rx.init_elem_species.erase(rx.init_elem_species.begin() + ur);
+            rx.init_elem_value.erase(rx.init_elem_value.begin() + ur);
+        } else if (rx.init_elem_species[ur] > idx) {
+            --rx.init_elem_species[ur];
+        }
+    }
+    // U2: the [INITIAL_QUALITY] rows that encode this species follow the
+    // same rule (their kind is kKindMsxFirst - species).
+    {
+        auto& iq = ctx.initial_quality;
+        for (int r = iq.count() - 1; r >= 0; --r) {
+            const auto ur = static_cast(r);
+            const int m = openswmm::InitialQualityData::msxSpecies(iq.kind[ur]);
+            if (m < 0) continue;
+            if (m == idx)      iq.erase(r);
+            else if (m > idx)  iq.kind[ur] = openswmm::InitialQualityData::msxKind(m - 1);
+        }
+    }
+    rebuild_msx_registry(ctx, old_base, old_n);
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_coeff_add(SWMM_Engine engine,
+        const char* name, int is_param, double value) {
+    CHECK_HANDLE(engine);
+    if (!name || !*name) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    // The parser's duplicate rule: a coefficient may not duplicate a
+    // coefficient, species, or term name.
+    if (rx.find_coef(name) >= 0 || rx.find_species(name) >= 0 ||
+        rx.find_term(name) >= 0)
+        return SWMM_ERR_BADPARAM;
+    rx.coef_name.push_back(name);
+    rx.coef_is_param.push_back(is_param ? 1 : 0);
+    rx.coef_value.push_back(value);
+    // Appending shifts no compiled index — no recompile needed.
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_coeff_set_value(SWMM_Engine engine,
+        int idx, double value) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(rx.coef_name.size()));
+    rx.coef_value[static_cast(idx)] = value;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_coeff_remove(SWMM_Engine engine, int idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(rx.coef_name.size()));
+    if (pool_references(rx, openswmm::RxToken::PUSH_COEF, idx))
+        return SWMM_ERR_BADPARAM;
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    const auto u = static_cast(idx);
+    rx.coef_name.erase(rx.coef_name.begin() + u);
+    rx.coef_is_param.erase(rx.coef_is_param.begin() + u);
+    rx.coef_value.erase(rx.coef_value.begin() + u);
+    // Higher coefficient indexes shift — recompile re-derives them from
+    // the sources.
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_term_add(SWMM_Engine engine,
+        const char* name, const char* expr) {
+    CHECK_HANDLE(engine);
+    if (!name || !*name || !expr) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    if (rx.find_term(name) >= 0 || rx.find_species(name) >= 0 ||
+        rx.find_coef(name) >= 0)
+        return SWMM_ERR_BADPARAM;
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    rx.term_name.push_back(name);
+    rx.term_expr_src.push_back(expr);
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_term_set_expr(SWMM_Engine engine, int idx,
+        const char* expr) {
+    CHECK_HANDLE(engine);
+    if (!expr) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(rx.term_name.size()));
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    rx.term_expr_src[static_cast(idx)] = expr;
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_term_remove(SWMM_Engine engine, int idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(idx >= 0 && idx < static_cast(rx.term_name.size()));
+    if (pool_references(rx, openswmm::RxToken::PUSH_TERM, idx))
+        return SWMM_ERR_BADPARAM;
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    const auto u = static_cast(idx);
+    rx.term_name.erase(rx.term_name.begin() + u);
+    rx.term_expr_src.erase(rx.term_expr_src.begin() + u);
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_expr_set(SWMM_Engine engine, int scope,
+        int species_idx, int form, const char* expr) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(species_idx >= 0 && species_idx < rx.n_species());
+    if (scope != SWMM_RXN_SCOPE_PIPE && scope != SWMM_RXN_SCOPE_TANK)
+        return SWMM_ERR_BADPARAM;
+    if (form < SWMM_RXN_FORM_NONE || form > SWMM_RXN_FORM_FORMULA)
+        return SWMM_ERR_BADPARAM;
+    if (form != SWMM_RXN_FORM_NONE && (!expr || !*expr))
+        return SWMM_ERR_BADPARAM;
+
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+    const auto u = static_cast(species_idx);
+    auto& forms = (scope == SWMM_RXN_SCOPE_PIPE) ? rx.pipe_form
+                                                 : rx.tank_form;
+    auto& srcs  = (scope == SWMM_RXN_SCOPE_PIPE) ? rx.pipe_expr_src
+                                                 : rx.tank_expr_src;
+    forms[u] = static_cast(form);
+    srcs[u]  = (form == SWMM_RXN_FORM_NONE) ? std::string() : expr;
+    if (!recompile_or_rollback(ctx, rx_backup, reg_backup))
+        return SWMM_ERR_BADPARAM;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_option_set(SWMM_Engine engine,
+        const char* key, const char* value) {
+    CHECK_HANDLE(engine);
+    if (!key || !value) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+
+    auto up = [](const char* s) {
+        std::string r(s);
+        for (auto& ch : r)
+            ch = static_cast(
+                std::toupper(static_cast(ch)));
+        return r;
+    };
+    const std::string k = up(key);
+    const std::string v = up(value);
+
+    if (k == "SOLVER") {
+        if      (v == "EUL")  rx.solver = openswmm::ReactionSolverKind::EUL;
+        else if (v == "RK5")  rx.solver = openswmm::ReactionSolverKind::RK5;
+        else if (v == "ROS2") rx.solver = openswmm::ReactionSolverKind::ROS2;
+        else if (v == "BDF2") rx.solver = openswmm::ReactionSolverKind::BDF2;
+        else return SWMM_ERR_BADPARAM;
+    } else if (k == "COUPLING") {
+        if      (v == "NONE") rx.coupling = openswmm::ReactionCoupling::NONE;
+        else if (v == "FULL") rx.coupling = openswmm::ReactionCoupling::FULL;
+        else return SWMM_ERR_BADPARAM;
+    } else if (k == "RATE_UNITS") {
+        if      (v == "SEC") rx.rate_units = openswmm::ReactionRateUnits::SEC;
+        else if (v == "MIN") rx.rate_units = openswmm::ReactionRateUnits::MIN;
+        else if (v == "HR")  rx.rate_units = openswmm::ReactionRateUnits::HR;
+        else if (v == "DAY") rx.rate_units = openswmm::ReactionRateUnits::DAY;
+        else return SWMM_ERR_BADPARAM;
+    } else if (k == "AREA_UNITS") {
+        if      (v == "FT2") rx.area_units = openswmm::ReactionAreaUnits::FT2;
+        else if (v == "M2")  rx.area_units = openswmm::ReactionAreaUnits::M2;
+        else if (v == "CM2") rx.area_units = openswmm::ReactionAreaUnits::CM2;
+        else return SWMM_ERR_BADPARAM;
+    } else if (k == "TIMESTEP") {
+        char* end = nullptr;
+        const double d = std::strtod(value, &end);
+        if (!end || *end != '\0' || end == value || d < 0.0)
+            return SWMM_ERR_BADPARAM;
+        rx.timestep = d;
+    } else if (k == "ATOL" || k == "RTOL") {
+        char* end = nullptr;
+        const double d = std::strtod(value, &end);
+        if (!end || *end != '\0' || end == value || d <= 0.0)
+            return SWMM_ERR_BADPARAM;
+        (k == "ATOL" ? rx.atol : rx.rtol) = d;
+    } else if (k == "TEMPERATURE") {
+        // Any finite value is a temperature (degC); no range gate.
+        char* end = nullptr;
+        const double d = std::strtod(value, &end);
+        if (!end || *end != '\0' || end == value || !std::isfinite(d))
+            return SWMM_ERR_BADPARAM;
+        rx.default_temp_c = d;
+    } else {
+        return SWMM_ERR_BADPARAM;
+    }
+    return SWMM_OK;
+}
+
+// ============================================================================
+// Initial quality (GLOBAL + the E-B NODE/LINK rows)
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_reaction_init_global_get(SWMM_Engine engine,
+        int species_idx, double* value) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(species_idx >= 0 && species_idx < rx.n_species());
+    if (!value) return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(species_idx);
+    *value = (u < rx.init_global.size()) ? rx.init_global[u] : 0.0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_init_global_set(SWMM_Engine engine,
+        int species_idx, double value) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(species_idx >= 0 && species_idx < rx.n_species());
+    if (value < 0.0) return SWMM_ERR_BADPARAM;
+    if (rx.init_global.size() < static_cast(rx.n_species()))
+        rx.init_global.resize(static_cast(rx.n_species()), 0.0);
+    rx.init_global[static_cast(species_idx)] = value;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_init_elem_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return static_cast(
+        to_engine(engine)->context().reactions.init_elem_idx.size());
+}
+
+SWMM_ENGINE_API int swmm_reaction_init_elem_get(SWMM_Engine engine,
+        int entry_idx, int* is_link, int* elem_idx, int* species_idx,
+        double* value) {
+    CHECK_HANDLE(engine);
+    const auto& rx = to_engine(engine)->context().reactions;
+    CHECK_INDEX(entry_idx >= 0 &&
+                entry_idx < static_cast(rx.init_elem_idx.size()));
+    if (!is_link || !elem_idx || !species_idx || !value)
+        return SWMM_ERR_BADPARAM;
+    const auto u = static_cast(entry_idx);
+    *is_link     = rx.init_elem_is_link[u] ? 1 : 0;
+    *elem_idx    = rx.init_elem_idx[u];
+    *species_idx = rx.init_elem_species[u];
+    *value       = rx.init_elem_value[u];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_init_elem_set(SWMM_Engine engine,
+        int is_link, int elem_idx, int species_idx, double value) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(species_idx >= 0 && species_idx < rx.n_species());
+    const int n_elems = is_link ? ctx.n_links() : ctx.n_nodes();
+    CHECK_INDEX(elem_idx >= 0 && elem_idx < n_elems);
+    if (value < 0.0) return SWMM_ERR_BADPARAM;
+    for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+        if ((rx.init_elem_is_link[k] != 0) == (is_link != 0) &&
+            rx.init_elem_idx[k] == elem_idx &&
+            rx.init_elem_species[k] == species_idx) {
+            rx.init_elem_value[k] = value;                    // upsert
+            return SWMM_OK;
+        }
+    }
+    rx.init_elem_is_link.push_back(is_link ? 1 : 0);
+    rx.init_elem_idx.push_back(elem_idx);
+    rx.init_elem_species.push_back(species_idx);
+    rx.init_elem_value.push_back(value);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_init_elem_remove(SWMM_Engine engine,
+        int entry_idx) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    auto& rx = ctx.reactions;
+    CHECK_INDEX(entry_idx >= 0 &&
+                entry_idx < static_cast(rx.init_elem_idx.size()));
+    const auto u = static_cast(entry_idx);
+    rx.init_elem_is_link.erase(rx.init_elem_is_link.begin() + u);
+    rx.init_elem_idx.erase(rx.init_elem_idx.begin() + u);
+    rx.init_elem_species.erase(rx.init_elem_species.begin() + u);
+    rx.init_elem_value.erase(rx.init_elem_value.begin() + u);
+    return SWMM_OK;
+}
+
+// ============================================================================
+// Whole-file text surface (E-C3)
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_reactions_serialize(SWMM_Engine engine, char* buf,
+        int buflen, int* needed_len) {
+    CHECK_HANDLE(engine);
+    if (!needed_len) return SWMM_ERR_BADPARAM;
+    const std::string text = openswmm::transport::serializeReactionSystem(
+        to_engine(engine)->context());
+    *needed_len = static_cast(text.size()) + 1;
+    if (!buf) return SWMM_OK;
+    if (buflen < *needed_len) return SWMM_ERR_BADPARAM;
+    std::memcpy(buf, text.c_str(), text.size() + 1);
+    return SWMM_OK;
+}
+
+namespace {
+
+/// Shared body of check_text (keep=false) and apply_text (keep=true):
+/// parse, strip the current MSX system (preserving the reserved-species
+/// tail so the re-applied block lands back in canonical position), apply,
+/// and either keep or restore. On ANY failure both ctx.reactions and the
+/// registry are restored byte-identical (the staged-swap contract).
+int apply_or_check_text(openswmm::SimulationContext& ctx, const char* text,
+                        char* errbuf, int buflen, bool keep) {
+    if (errbuf && buflen > 0) errbuf[0] = '\0';
+    if (!text || !*text) {
+        if (errbuf && buflen > 0)
+            copy_to_buf("empty reactions text", errbuf, buflen);
+        return SWMM_ERR_BADPARAM;
+    }
+
+    openswmm::components::ComponentConfigSections sections;
+    const std::string perr = openswmm::components::parse_component_config_text(
+        text, "", sections);
+    if (!perr.empty()) {
+        if (errbuf && buflen > 0) copy_to_buf(perr, errbuf, buflen);
+        return SWMM_ERR_BADPARAM;
+    }
+
+    auto rx_backup  = ctx.reactions;
+    auto reg_backup = ctx.species_registry;
+
+    // Strip: remove the current MSX block but SNAPSHOT everything after it
+    // (the reserved species), so the fresh apply's registry adds land in
+    // the canonical pollutants < MSX < reserved order.
+    auto& reg = ctx.species_registry;
+    auto& rx  = ctx.reactions;
+    const int base = (rx.registry_base >= 0) ? rx.registry_base
+                                             : reg.pollutant_count();
+    const int old_msx = (rx.registry_base >= 0) ? rx.n_species() : 0;
+    struct Row { std::string name; openswmm::SpeciesKind kind;
+                 std::string units; };
+    std::vector tail;
+    for (int i = base + old_msx; i < reg.count(); ++i)
+        tail.push_back({reg.name(i), reg.kind(i), reg.units(i)});
+    reg.truncate_to(base);
+    rx.clear();
+
+    std::vector errs;
+    openswmm::transport::applyReactionSections(ctx, sections, errs);
+    if (!errs.empty()) {
+        ctx.reactions        = std::move(rx_backup);
+        ctx.species_registry = std::move(reg_backup);
+        if (errbuf && buflen > 0) copy_to_buf(errs.front(), errbuf, buflen);
+        return SWMM_ERR_BADPARAM;
+    }
+    for (auto& r : tail)
+        reg.add(std::move(r.name), r.kind, std::move(r.units));
+
+    if (!keep) {
+        ctx.reactions        = std::move(rx_backup);
+        ctx.species_registry = std::move(reg_backup);
+    }
+    return SWMM_OK;
+}
+
+} // namespace
+
+SWMM_ENGINE_API int swmm_reactions_check_text(SWMM_Engine engine,
+        const char* text, char* errbuf, int buflen) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    // The dry-run stages through the live context (restore-always), so it
+    // shares apply's editable-states guard rather than racing a running
+    // solver with a transient swap.
+    CHECK_GEOMETRY(ctx);
+    return apply_or_check_text(ctx, text, errbuf, buflen, /*keep=*/false);
+}
+
+SWMM_ENGINE_API int swmm_reactions_apply_text(SWMM_Engine engine,
+        const char* text, char* errbuf, int buflen) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_GEOMETRY(ctx);
+    return apply_or_check_text(ctx, text, errbuf, buflen, /*keep=*/true);
+}
+
+SWMM_ENGINE_API int swmm_reactions_save(SWMM_Engine engine,
+        const char* path_or_null) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+
+    std::string path = path_or_null ? path_or_null : "";
+    if (path.empty()) {
+        // The bound reactions component's config path — resolved when the
+        // model was opened from a file, verbatim otherwise.
+        for (const auto& spec : ctx.process_component_specs) {
+            if (spec.id != "org.hydrocouple.openswmm.reactions") continue;
+            path = !spec.resolved_config_path.empty()
+                       ? spec.resolved_config_path
+                       : spec.config_path;
+            break;
+        }
+    }
+    if (path.empty()) return SWMM_ERR_BADPARAM;
+
+    const std::string text =
+        openswmm::transport::serializeReactionSystem(ctx);
+    std::ofstream f(openswmm::io::utf8_path(path), std::ios::binary | std::ios::trunc);
+    if (!f.is_open()) return SWMM_ERR_BADPARAM;
+    f << text;
+    return f.good() ? SWMM_OK : SWMM_ERR_BADPARAM;
+}
+
+// ============================================================================
+// Static vocabulary — served by the expression compiler's own tables so the
+// completer/highlighter cannot drift from what actually compiles.
+// ============================================================================
+
+SWMM_ENGINE_API int swmm_reaction_hydvar_count(void) {
+    return openswmm::transport::reactionHydVarCount();
+}
+
+SWMM_ENGINE_API int swmm_reaction_hydvar_get(int idx, char* name,
+        int name_len, char* description, int desc_len) {
+    const char* n = nullptr;
+    const char* d = nullptr;
+    if (!openswmm::transport::reactionHydVarInfo(idx, &n, &d))
+        return SWMM_ERR_BADINDEX;
+    if (!name || name_len <= 0) return SWMM_ERR_BADPARAM;
+    copy_to_buf(n, name, name_len);
+    if (description && desc_len > 0) copy_to_buf(d, description, desc_len);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_reaction_function_count(void) {
+    return openswmm::transport::reactionFunctionCount();
+}
+
+SWMM_ENGINE_API int swmm_reaction_function_get(int idx, char* name,
+        int name_len, int* arity) {
+    const char* n = nullptr;
+    int a = 0;
+    if (!openswmm::transport::reactionFunctionInfo(idx, &n, &a))
+        return SWMM_ERR_BADINDEX;
+    if (!name || name_len <= 0 || !arity) return SWMM_ERR_BADPARAM;
+    copy_to_buf(n, name, name_len);
+    *arity = a;
+    return SWMM_OK;
+}
+
+} // extern "C"
diff --git a/src/engine/core/openswmm_spatial_impl.cpp b/src/engine/core/openswmm_spatial_impl.cpp
index 0bfa40723..96d43b8dc 100644
--- a/src/engine/core/openswmm_spatial_impl.cpp
+++ b/src/engine/core/openswmm_spatial_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_spatial_impl.cpp
  * @brief C API implementation — spatial frame: CRS, coordinates, vertices, polygons.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -23,7 +39,14 @@ SWMM_ENGINE_API int swmm_spatial_set_crs(SWMM_Engine engine, const char* crs) {
     CHECK_HANDLE(engine);
     if (!crs) return SWMM_ERR_BADPARAM;
     auto& ctx = to_engine(engine)->context();
+    // The CRS is held in two places: the spatial frame (this API, the
+    // GeoPackage reader/writer, hot-start headers) and the [OPTIONS] table
+    // (swmm_get_crs, swmm_options_set("CRS"), and the .inp writer). The .inp
+    // reader fills both; this setter used to fill only the frame, so a caller
+    // that reprojected coordinates and then saved the model wrote the NEW
+    // coordinates under the OLD `CRS` line. Keep both in step.
     ctx.spatial.crs = crs;
+    ctx.options.crs = crs;
     return SWMM_OK;
 }
 
@@ -49,6 +72,9 @@ SWMM_ENGINE_API int swmm_spatial_set_node_coord(SWMM_Engine engine, int idx, dou
     const auto ui = static_cast(idx);
     ctx.spatial.node_x[ui] = x;
     ctx.spatial.node_y[ui] = y;
+    if (ctx.spatial.node_has_xy.size() < ctx.spatial.node_x.size())
+        ctx.spatial.node_has_xy.resize(ctx.spatial.node_x.size(), 0);
+    ctx.spatial.node_has_xy[ui] = 1;   // G-X2
     return SWMM_OK;
 }
 
diff --git a/src/engine/core/openswmm_statistics_impl.cpp b/src/engine/core/openswmm_statistics_impl.cpp
index 30113524b..f42d951ff 100644
--- a/src/engine/core/openswmm_statistics_impl.cpp
+++ b/src/engine/core/openswmm_statistics_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_statistics_impl.cpp
  * @brief C API implementation — node, link, subcatchment statistics queries.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
diff --git a/src/engine/core/openswmm_subcatchments_impl.cpp b/src/engine/core/openswmm_subcatchments_impl.cpp
index cf3529413..eeeac4f55 100644
--- a/src/engine/core/openswmm_subcatchments_impl.cpp
+++ b/src/engine/core/openswmm_subcatchments_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_subcatchments_impl.cpp
  * @brief C API implementation — subcatchment identity, creation, properties, state, bulk.
@@ -7,10 +23,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
+#include "StringCase.hpp"
+#include "../hydrology/Groundwater.hpp"
+#include "../math/MathExpr.hpp"
 #include "../../../include/openswmm/engine/openswmm_subcatchments.h"
 
 #include 
@@ -127,6 +146,7 @@ SWMM_ENGINE_API int swmm_subcatch_set_zero_imperv_pct(SWMM_Engine engine, int id
     auto& ctx = to_engine(engine)->context();
     CHECK_GEOMETRY(ctx);
     CHECK_INDEX(idx >= 0 && idx < ctx.n_subcatches());
+    ctx.subcatches.pct_zero[static_cast(idx)] = pct;
     ctx.subcatches.frac_imperv_no_store[static_cast(idx)] = pct / 100.0;
     return SWMM_OK;
 }
@@ -508,10 +528,23 @@ SWMM_ENGINE_API int swmm_subcatch_set_initial_loading(SWMM_Engine engine, int sc
     auto& ctx = to_engine(engine)->context();
     CHECK_GEOMETRY(ctx);
     CHECK_INDEX(sc_idx >= 0 && sc_idx < ctx.n_subcatches());
+    if (pollut_idx >= ctx.n_pollutants()) {          // BW-MSX species index
+        auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        if (ms.n_landuses != ctx.n_landuses() || ms.n_species != ctx.reactions.n_species())
+            ms.resize_params(ctx.n_landuses(), ctx.reactions.n_species());
+        const auto want = static_cast(ctx.n_subcatches()) *
+                          static_cast(ms.n_species);
+        if (ms.init_loading.size() != want) ms.init_loading.assign(want, 0.0);
+        ms.init_loading[ms.sidx(sc_idx, m)] = buildup;
+        ms.resolved = true;
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
     // Ensure the quality arrays are sized ([LOADINGS] parks the initial
-    // buildup in subcatches.conc — same storage handle_loadings uses).
+    // buildup in subcatches.init_loading — same storage handle_loadings uses).
     if (ctx.subcatches.conc_n_pollutants != ctx.n_pollutants() ||
         static_cast(ctx.subcatches.conc.size()) !=
             ctx.n_subcatches() * ctx.n_pollutants()) {
@@ -521,7 +554,7 @@ SWMM_ENGINE_API int swmm_subcatch_set_initial_loading(SWMM_Engine engine, int sc
     auto k = static_cast(sc_idx) *
              static_cast(ctx.n_pollutants()) +
              static_cast(pollut_idx);
-    ctx.subcatches.conc[k] = buildup;
+    ctx.subcatches.init_loading[k] = buildup;
     return SWMM_OK;
 }
 
@@ -529,9 +562,20 @@ SWMM_ENGINE_API int swmm_subcatch_get_initial_loading(SWMM_Engine engine, int sc
     CHECK_HANDLE(engine);
     const auto& ctx = to_engine(engine)->context();
     CHECK_INDEX(sc_idx >= 0 && sc_idx < ctx.n_subcatches());
+    if (pollut_idx >= ctx.n_pollutants()) {          // BW-MSX species index
+        const auto& ms = ctx.reactions.surface;
+        const int m = pollut_idx - ctx.n_pollutants();
+        CHECK_INDEX(m >= 0 && m < ctx.reactions.n_species());
+        const auto want = static_cast(ctx.n_subcatches()) *
+                          static_cast(ms.n_species);
+        if (buildup) *buildup = (ms.n_species == ctx.reactions.n_species() &&
+                                 ms.init_loading.size() == want)
+                                    ? ms.init_loading[ms.sidx(sc_idx, m)] : 0.0;
+        return SWMM_OK;
+    }
     CHECK_INDEX(pollut_idx >= 0 && pollut_idx < ctx.n_pollutants());
 
-    if (ctx.subcatches.conc.empty() ||
+    if (ctx.subcatches.init_loading.empty() ||
         ctx.subcatches.conc_n_pollutants != ctx.n_pollutants()) {
         if (buildup) *buildup = 0.0;
         return SWMM_OK;
@@ -540,7 +584,7 @@ SWMM_ENGINE_API int swmm_subcatch_get_initial_loading(SWMM_Engine engine, int sc
     auto k = static_cast(sc_idx) *
              static_cast(ctx.n_pollutants()) +
              static_cast(pollut_idx);
-    if (buildup) *buildup = ctx.subcatches.conc[k];
+    if (buildup) *buildup = ctx.subcatches.init_loading[k];
     return SWMM_OK;
 }
 
@@ -671,6 +715,105 @@ SWMM_ENGINE_API int swmm_subcatch_get_gw_params(SWMM_Engine engine, int idx,
     return SWMM_OK;
 }
 
+// ============================================================================
+// Custom groundwater flow expressions ([GWF])
+// ============================================================================
+// Single source of truth stays where handle_gwf() / InpWriter / start() already
+// look: options.ext_options["GWF::LATERAL|DEEP"], keyed by the
+// registry (canonical) spelling of the subcatchment name.
+
+// C++ linkage for the helpers: this file body sits inside extern "C", and a
+// C-linkage function returning std::string draws -Wreturn-type-c-linkage.
+extern "C++" {
+namespace {
+
+std::string gwf_key(const openswmm::SimulationContext& ctx, int idx, int type) {
+    const char* ty = (type == SWMM_GWF_LATERAL) ? "LATERAL" : "DEEP";
+    return "GWF:" + ctx.subcatch_names.name_of(idx) + ":" + ty;
+}
+
+int gwf_copy_out(const std::string& s, char* buf, int buflen) {
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    const std::size_t n = std::min(s.size(), static_cast(buflen - 1));
+    std::memcpy(buf, s.data(), n);
+    buf[n] = '\0';
+    return SWMM_OK;
+}
+
+} // namespace
+} // extern "C++"
+
+SWMM_ENGINE_API int swmm_subcatch_get_gwf_expression(SWMM_Engine engine, int index, int type,
+                                                     char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    if (!buf || buflen <= 0) return SWMM_ERR_BADPARAM;
+    if (type != SWMM_GWF_LATERAL && type != SWMM_GWF_DEEP) return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(index >= 0 && index < ctx.n_subcatches());
+    auto it = ctx.options.ext_options.find(gwf_key(ctx, index, type));
+    return gwf_copy_out(it == ctx.options.ext_options.end() ? std::string{} : it->second,
+                    buf, buflen);
+}
+
+SWMM_ENGINE_API int swmm_subcatch_set_gwf_expression(SWMM_Engine engine, int index, int type,
+                                                     const char* expr) {
+    CHECK_HANDLE(engine);
+    if (type != SWMM_GWF_LATERAL && type != SWMM_GWF_DEEP) return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    // Compiled at start() like the aquifer evap pattern — pre-start-only.
+    CHECK_GEOMETRY(ctx);
+    CHECK_INDEX(index >= 0 && index < ctx.n_subcatches());
+    const std::string key = gwf_key(ctx, index, type);
+    if (!expr || !*expr) ctx.options.ext_options.erase(key);
+    else                 ctx.options.ext_options[key] = expr;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_gwf_validate_expression(SWMM_Engine engine, const char* expr,
+                                                 char* errbuf, int buflen, int* col_out) {
+    CHECK_HANDLE(engine);
+    if (errbuf && buflen > 0) errbuf[0] = '\0';
+    if (col_out) *col_out = -1;
+    if (!expr) return SWMM_ERR_BADPARAM;
+
+    std::string msg;
+    int col = -1;
+    if (openswmm::groundwater::gwf_validate(expr, msg, col) == 0) return SWMM_OK;
+
+    if (errbuf && buflen > 0) gwf_copy_out(msg, errbuf, buflen);
+    if (col_out) *col_out = col;
+    return SWMM_ERR_BADPARAM;
+}
+
+SWMM_ENGINE_API int swmm_gwf_variable_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return openswmm::groundwater::GWV_MAX;
+}
+
+SWMM_ENGINE_API int swmm_gwf_variable_name(SWMM_Engine engine, int i, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    CHECK_INDEX(i >= 0 && i < openswmm::groundwater::GWV_MAX);
+    return gwf_copy_out(openswmm::groundwater::GW_VAR_NAMES[i], buf, buflen);
+}
+
+SWMM_ENGINE_API int swmm_gwf_variable_description(SWMM_Engine engine, int i, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    CHECK_INDEX(i >= 0 && i < openswmm::groundwater::GWV_MAX);
+    return gwf_copy_out(openswmm::groundwater::GW_VAR_DESCRIPTIONS[i], buf, buflen);
+}
+
+SWMM_ENGINE_API int swmm_gwf_function_count(SWMM_Engine engine) {
+    if (!engine) return -1;
+    return static_cast(openswmm::mathexpr::function_names().size());
+}
+
+SWMM_ENGINE_API int swmm_gwf_function_name(SWMM_Engine engine, int i, char* buf, int buflen) {
+    CHECK_HANDLE(engine);
+    const auto& names = openswmm::mathexpr::function_names();
+    CHECK_INDEX(i >= 0 && static_cast(i) < names.size());
+    return gwf_copy_out(names[static_cast(i)], buf, buflen);
+}
+
 // ============================================================================
 // State injection (data assimilation)
 // ============================================================================
@@ -1046,6 +1189,26 @@ SWMM_ENGINE_API int swmm_aquifer_add(SWMM_Engine engine, const char* id) {
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_aquifer_rename(SWMM_Engine engine, int idx, const char* new_id) {
+    CHECK_HANDLE(engine);
+    if (!new_id || new_id[0] == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.aquifers.count());
+
+    // The name lives in TWO stores: aquifers.names backs swmm_aquifer_id, the
+    // NameIndex backs swmm_aquifer_index. Updating one without the other makes
+    // the two disagree. NameIndex::rename does the collision check (and allows
+    // a pure case-respelling of this same entry), so run it first and only
+    // touch the vector once it has accepted.
+    if (!ctx.aquifer_names.rename(idx, new_id)) return SWMM_ERR_BADPARAM;
+    ctx.aquifers.names[static_cast(idx)] = new_id;
+
+    // No fixup needed elsewhere: [GROUNDWATER] resolves to an aquifer INDEX at
+    // parse time (subcatches.gw_aquifer) and keeps no name string.
+    return SWMM_OK;
+}
+
 namespace {
 // Map a SWMM_AquiferParam code to the backing store vector (input-file units).
 std::vector* aquifer_param_vec(openswmm::SimulationContext& ctx, int param) {
@@ -1202,6 +1365,32 @@ SWMM_ENGINE_API int swmm_snowpack_add(SWMM_Engine engine, const char* id) {
     return SWMM_OK;
 }
 
+SWMM_ENGINE_API int swmm_snowpack_rename(SWMM_Engine engine, int idx, const char* new_id) {
+    CHECK_HANDLE(engine);
+    if (!new_id || new_id[0] == '\0') return SWMM_ERR_BADPARAM;
+    auto& ctx = to_engine(engine)->context();
+    CHECK_EDITABLE(ctx);
+    CHECK_INDEX(idx >= 0 && idx < ctx.snowpacks.count());
+    const auto ui = static_cast(idx);
+
+    // Two stores hold the name and both are read: snowpacks.names backs
+    // swmm_snowpack_id and the [SNOWPACKS] writer, while the NameIndex backs
+    // swmm_snowpack_index and the [SUBCATCHMENTS] snow-pack column. Let
+    // NameIndex::rename arbitrate the collision, then mirror into the vector.
+    const std::string prev = ctx.snowpacks.names[ui];
+    if (!ctx.snowpack_names.rename(idx, new_id)) return SWMM_ERR_BADPARAM;
+    ctx.snowpacks.names[ui] = new_id;
+
+    // subcatches.snowpack_name is the parse-time deferred-resolution string.
+    // PostParseResolver has already turned it into subcatches.snowpack, and no
+    // writer reads it, but keeping it coherent means a re-resolve cannot bind
+    // the subcatchment to a name that no longer exists.
+    for (auto& ref : ctx.subcatches.snowpack_name) {
+        if (openswmm::ieq(ref, prev)) ref = new_id;
+    }
+    return SWMM_OK;
+}
+
 namespace {
 // The three snow-melt surfaces (PLOWABLE / IMPERVIOUS / PERVIOUS) share an
 // identical 7-value layout; these helpers back the per-surface API functions.
diff --git a/src/engine/core/openswmm_tables_impl.cpp b/src/engine/core/openswmm_tables_impl.cpp
index 05dc17b23..128540352 100644
--- a/src/engine/core/openswmm_tables_impl.cpp
+++ b/src/engine/core/openswmm_tables_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_tables_impl.cpp
  * @brief C API implementation — tables (time series, curves) and patterns.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -147,6 +163,36 @@ SWMM_ENGINE_API int swmm_table_clear(SWMM_Engine engine, int idx) {
     tbl.x.clear();
     tbl.y.clear();
     tbl.cursor.reset();
+    // A cleared series has no authored rows left, so no time-only rows
+    // either; callers that rebuild a relative series re-declare it via
+    // swmm_timeseries_set_relative_info() after re-adding points.
+    tbl.n_relative = 0;
+    tbl.rel_anchor = 0.0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_timeseries_get_relative_info(SWMM_Engine engine, int idx,
+                                                      int* n_relative, double* anchor) {
+    CHECK_HANDLE(engine);
+    const auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_tables());
+    const auto& tbl = ctx.tables[idx];
+    if (tbl.type != openswmm::TableType::TIMESERIES) return SWMM_ERR_BADPARAM;
+    if (n_relative) *n_relative = tbl.n_relative;
+    if (anchor)     *anchor     = tbl.rel_anchor;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_timeseries_set_relative_info(SWMM_Engine engine, int idx,
+                                                      int n_relative, double anchor) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(idx >= 0 && idx < ctx.n_tables());
+    auto& tbl = ctx.tables[idx];
+    if (tbl.type != openswmm::TableType::TIMESERIES) return SWMM_ERR_BADPARAM;
+    if (n_relative < 0) return SWMM_ERR_BADPARAM;
+    tbl.n_relative = std::min(n_relative, static_cast(tbl.x.size()));
+    tbl.rel_anchor = anchor;
     return SWMM_OK;
 }
 
diff --git a/src/engine/core/openswmm_transport_impl.cpp b/src/engine/core/openswmm_transport_impl.cpp
new file mode 100644
index 000000000..6fb987421
--- /dev/null
+++ b/src/engine/core/openswmm_transport_impl.cpp
@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_transport_impl.cpp
+ * @brief E6 — ARD transport configuration surface. See the header for the
+ *        read-only-rows decision and its reason.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "openswmm_api_common.hpp"
+#include "../../../include/openswmm/engine/openswmm_transport.h"
+
+#include 
+#include 
+#include 
+#include 
+
+namespace {
+
+/// NUL-safe copy into a caller buffer; a NULL/zero-length buffer skips the
+/// field rather than failing the call, so a reader can take only the
+/// columns it wants (the pollutant-id reader's convention).
+void put_str(const std::string& s, char* buf, int len) {
+    if (buf == nullptr || len <= 0) return;
+    const auto n = std::min(static_cast(len - 1), s.size());
+    std::memcpy(buf, s.data(), n);
+    buf[n] = '\0';
+}
+
+int get_row(const std::vector& rows, int index,
+            char* element, int elem_len, char* species, int spec_len,
+            int* is_ts, double* value, char* ts_name, int ts_len) {
+    if (index < 0 || index >= static_cast(rows.size()))
+        return SWMM_ERR_BADINDEX;
+    const auto& r = rows[static_cast(index)];
+    put_str(r.element, element, elem_len);
+    put_str(r.species, species, spec_len);
+    if (is_ts) *is_ts = r.is_ts ? 1 : 0;
+    if (value) *value = r.value;
+    put_str(r.ts_name, ts_name, ts_len);
+    return SWMM_OK;
+}
+
+}  // namespace
+
+SWMM_ENGINE_API int swmm_transport_get_configured(SWMM_Engine engine,
+                                                  int* configured) {
+    CHECK_HANDLE(engine);
+    if (configured == nullptr) return SWMM_ERR_BADPARAM;
+    *configured =
+        to_engine(engine)->context().ard_config.configured ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_dispersion_mode(SWMM_Engine engine,
+                                                       int* mode) {
+    CHECK_HANDLE(engine);
+    if (mode == nullptr) return SWMM_ERR_BADPARAM;
+    *mode = static_cast(
+        to_engine(engine)->context().ard_config.dispersion_mode);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_set_dispersion_mode(SWMM_Engine engine,
+                                                       int mode) {
+    CHECK_HANDLE(engine);
+    if (mode < static_cast(openswmm::ArdDispersionMode::OFF) ||
+        mode > static_cast(openswmm::ArdDispersionMode::VALUE))
+        return SWMM_ERR_BADPARAM;
+    auto& cfg = to_engine(engine)->context().ard_config;
+    cfg.dispersion_mode = static_cast(mode);
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_dispersion_value(SWMM_Engine engine,
+                                                        double* value) {
+    CHECK_HANDLE(engine);
+    if (value == nullptr) return SWMM_ERR_BADPARAM;
+    *value = to_engine(engine)->context().ard_config.dispersion_value;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_set_dispersion_value(SWMM_Engine engine,
+                                                        double value) {
+    CHECK_HANDLE(engine);
+    // Refused, not clamped — the [RADIATIVE_FLUXES] convention: a negative
+    // dispersion coefficient is anti-diffusion, which the implicit solve
+    // would happily integrate into growing oscillations that look like a
+    // model result.
+    if (!(value >= 0.0) || !std::isfinite(value)) return SWMM_ERR_BADPARAM;
+    auto& cfg = to_engine(engine)->context().ard_config;
+    cfg.dispersion_value = value;
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_target_dx(SWMM_Engine engine,
+                                                 double* dx) {
+    CHECK_HANDLE(engine);
+    if (dx == nullptr) return SWMM_ERR_BADPARAM;
+    *dx = to_engine(engine)->context().ard_config.target_dx;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_set_target_dx(SWMM_Engine engine,
+                                                 double dx) {
+    CHECK_HANDLE(engine);
+    if (!(dx >= 0.0) || !std::isfinite(dx)) return SWMM_ERR_BADPARAM;
+    auto& cfg = to_engine(engine)->context().ard_config;
+    cfg.target_dx = dx;
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_conduit_disp_count(SWMM_Engine engine,
+                                                      int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    *count = static_cast(
+        to_engine(engine)->context().ard_config.conduit_disp_link.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_conduit_disp(SWMM_Engine engine,
+                                                    int index,
+                                                    int* link_index,
+                                                    double* value) {
+    CHECK_HANDLE(engine);
+    const auto& cfg = to_engine(engine)->context().ard_config;
+    CHECK_INDEX(index >= 0 &&
+                index < static_cast(cfg.conduit_disp_link.size()));
+    const auto ui = static_cast(index);
+    if (link_index) *link_index = cfg.conduit_disp_link[ui];
+    if (value) *value = cfg.conduit_disp_value[ui];
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_boundary_count(SWMM_Engine engine,
+                                                  int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    *count = static_cast(
+        to_engine(engine)->context().ard_config.boundary_rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_boundary(SWMM_Engine engine, int index,
+                                                char* element, int elem_len,
+                                                char* species, int spec_len,
+                                                int* is_ts, double* value,
+                                                char* ts_name, int ts_len) {
+    CHECK_HANDLE(engine);
+    return get_row(to_engine(engine)->context().ard_config.boundary_rows,
+                   index, element, elem_len, species, spec_len, is_ts,
+                   value, ts_name, ts_len);
+}
+
+SWMM_ENGINE_API int swmm_transport_source_count(SWMM_Engine engine,
+                                                int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    *count = static_cast(
+        to_engine(engine)->context().ard_config.source_rows.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_transport_get_source(SWMM_Engine engine, int index,
+                                              char* element, int elem_len,
+                                              char* species, int spec_len,
+                                              int* is_ts, double* value,
+                                              char* ts_name, int ts_len) {
+    CHECK_HANDLE(engine);
+    return get_row(to_engine(engine)->context().ard_config.source_rows,
+                   index, element, elem_len, species, spec_len, is_ts,
+                   value, ts_name, ts_len);
+}
diff --git a/src/engine/core/openswmm_water_age_impl.cpp b/src/engine/core/openswmm_water_age_impl.cpp
new file mode 100644
index 000000000..1e655109b
--- /dev/null
+++ b/src/engine/core/openswmm_water_age_impl.cpp
@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file openswmm_water_age_impl.cpp
+ * @brief Water-age source-table CRUD implementation (subplan X5).
+ *
+ * @details Values cross the boundary in HOURS (the config file's unit);
+ *          the engine stores SECONDS. Negative values are legal and pass
+ *          straight through — a negative source age extracts age-volume
+ *          (D-NS1), clamped at consumption by the engines. There is no
+ *          `ucf` conversion here: hours are hours in every unit system.
+ *
+ * @see include/openswmm/engine/openswmm_water_age.h
+ */
+
+#include "openswmm_api_common.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "../../../include/openswmm/engine/openswmm_water_age.h"
+#include "../transport/components/WaterAgeModule/WaterAgeComponent.hpp"
+
+#include 
+#include 
+
+namespace {
+
+constexpr double kSecPerHour = 3600.0;
+
+bool valid_source(int s) {
+    return s >= 0 && s < static_cast(openswmm::WaterAgeSource::COUNT_);
+}
+
+/// The A1a scope rule the parser enforces: only DWF and EXTERNAL_INFLOW
+/// take per-node overrides.
+bool node_scoped(int s) {
+    return s == static_cast(openswmm::WaterAgeSource::DWF) ||
+           s == static_cast(openswmm::WaterAgeSource::EXTERNAL_INFLOW);
+}
+
+/// Row index of (source, node) in the override arrays, or -1.
+int find_override(const openswmm::WaterAgeConfigData& cfg, int source,
+                  int node) {
+    for (std::size_t i = 0; i < cfg.node_over_source.size(); ++i)
+        if (cfg.node_over_source[i] == source &&
+            cfg.node_over_node[i] == node)
+            return static_cast(i);
+    return -1;
+}
+
+}  // namespace
+
+SWMM_ENGINE_API int swmm_water_age_get_enabled(SWMM_Engine engine,
+                                               int* enabled) {
+    CHECK_HANDLE(engine);
+    if (enabled == nullptr) return SWMM_ERR_BADPARAM;
+    *enabled = to_engine(engine)->context().options.water_age ? 1 : 0;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_get_global_source(SWMM_Engine engine,
+                                                     int source,
+                                                     double* hours) {
+    CHECK_HANDLE(engine);
+    if (hours == nullptr) return SWMM_ERR_BADPARAM;
+    CHECK_INDEX(valid_source(source));
+    const auto& cfg = to_engine(engine)->context().water_age_config;
+    *hours = cfg.global_age[source] / kSecPerHour;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_set_global_source(SWMM_Engine engine,
+                                                     int source,
+                                                     double hours) {
+    CHECK_HANDLE(engine);
+    CHECK_INDEX(valid_source(source));
+    auto& cfg = to_engine(engine)->context().water_age_config;
+    // Negative hours are legal — extraction (D-NS1). No floor here: the
+    // clamp lives at consumption, where the held age is known.
+    cfg.global_age[source] = hours * kSecPerHour;
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_override_count(SWMM_Engine engine,
+                                                  int* count) {
+    CHECK_HANDLE(engine);
+    if (count == nullptr) return SWMM_ERR_BADPARAM;
+    *count = static_cast(
+        to_engine(engine)->context().water_age_config.node_over_source.size());
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_get_override(SWMM_Engine engine, int index,
+                                                int* source, int* node_index,
+                                                double* hours) {
+    CHECK_HANDLE(engine);
+    const auto& cfg = to_engine(engine)->context().water_age_config;
+    CHECK_INDEX(index >= 0 &&
+                index < static_cast(cfg.node_over_source.size()));
+    const auto ui = static_cast(index);
+    if (source != nullptr)     *source = cfg.node_over_source[ui];
+    if (node_index != nullptr) *node_index = cfg.node_over_node[ui];
+    if (hours != nullptr)      *hours = cfg.node_over_age[ui] / kSecPerHour;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_set_override(SWMM_Engine engine,
+                                                int source, int node_index,
+                                                double hours) {
+    CHECK_HANDLE(engine);
+    auto& ctx = to_engine(engine)->context();
+    CHECK_INDEX(valid_source(source));
+    CHECK_INDEX(node_index >= 0 && node_index < ctx.n_nodes());
+    // The parser's A1a scope rule, enforced identically here — an editor
+    // must not be able to author a table the file parser would refuse.
+    if (!node_scoped(source)) return SWMM_ERR_BADPARAM;
+
+    auto& cfg = ctx.water_age_config;
+    const int row = find_override(cfg, source, node_index);
+    if (row >= 0) {
+        cfg.node_over_age[static_cast(row)] =
+            hours * kSecPerHour;
+    } else {
+        cfg.node_over_source.push_back(source);
+        cfg.node_over_node.push_back(node_index);
+        cfg.node_over_age.push_back(hours * kSecPerHour);
+    }
+    cfg.configured = true;
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_remove_override(SWMM_Engine engine,
+                                                   int source,
+                                                   int node_index) {
+    CHECK_HANDLE(engine);
+    auto& cfg = to_engine(engine)->context().water_age_config;
+    const int row = find_override(cfg, source, node_index);
+    CHECK_INDEX(row >= 0);
+    const auto ui = static_cast(row);
+    cfg.node_over_source.erase(cfg.node_over_source.begin() + ui);
+    cfg.node_over_node.erase(cfg.node_over_node.begin() + ui);
+    cfg.node_over_age.erase(cfg.node_over_age.begin() + ui);
+    return SWMM_OK;
+}
+
+SWMM_ENGINE_API int swmm_water_age_save(SWMM_Engine engine,
+                                        const char* path) {
+    CHECK_HANDLE(engine);
+    if (path == nullptr || *path == '\0') return SWMM_ERR_BADPARAM;
+    const auto& ctx = to_engine(engine)->context();
+
+    // IO3c: one spelling for this table — the component's serializer,
+    // shared with the ComponentConfigSave hook (the reactions pattern).
+    // Upgrades the old %g (6 significant digits, NOT read-back-exact) to
+    // the shortest-exact convention. An unconfigured model still writes
+    // the empty header, this function's historical contract.
+    const std::string text = openswmm::transport::serializeWaterAgeConfig(ctx);
+    std::FILE* f = openswmm::io::fopen_utf8(path, "w");
+    if (f == nullptr) return SWMM_ERR_IO;
+    if (text.empty())
+        std::fprintf(f, "[WATER_AGE_SOURCES]\n");
+    else
+        std::fwrite(text.data(), 1, text.size(), f);
+    std::fclose(f);
+    return SWMM_OK;
+}
diff --git a/src/engine/core/openswmm_xsect_impl.cpp b/src/engine/core/openswmm_xsect_impl.cpp
index 916c220ea..43ee61680 100644
--- a/src/engine/core/openswmm_xsect_impl.cpp
+++ b/src/engine/core/openswmm_xsect_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_xsect_impl.cpp
  * @brief C API implementation — standalone cross-section geometry.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "openswmm_api_common.hpp"
@@ -418,6 +434,7 @@ SWMM_ENGINE_API int swmm_link_create_xsect(SWMM_Engine engine, int link_idx,
         h->params.area_tbl          = h->table.area_tbl;
         h->params.hrad_tbl          = h->table.hrad_tbl;
         h->params.width_tbl         = h->table.width_tbl;
+        h->params.area_lut          = &h->table.area_lut;
         h->params.transect_tbl_size = openswmm::transect::N_TRANSECT_TBL;
     }
 
diff --git a/src/engine/data/ArdConfigData.hpp b/src/engine/data/ArdConfigData.hpp
new file mode 100644
index 000000000..bc78a10d1
--- /dev/null
+++ b/src/engine/data/ArdConfigData.hpp
@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ArdConfigData.hpp
+ * @brief Parsed configuration of the Eulerian ARD transport component
+ *        (`org.hydrocouple.openswmm.transport.ard`, config file `model.ard`).
+ *
+ * @details Phase E3 of the Eulerian ARD plan activates the dispersion
+ *          subset of the component config (D-UT8 placement: these options
+ *          live in the external component file, NOT in [OPTIONS]):
+ *
+ *          ```
+ *          [TRANSPORT_OPTIONS]
+ *          DISPERSION   OFF | FISCHER |    ; global coefficient model
+ *
+ *          [CONDUIT_DISPERSION]
+ *                            ; per-conduit override
+ *          ```
+ *
+ *          Values are entered in project display units (len²/s — m²/s under
+ *          SI flow units, ft²/s under US); the engine converts to internal
+ *          ft²/s at init, mirroring the FV_DISPERSION treatment in
+ *          Router::initFv. Per-conduit overrides win over the global model
+ *          in their conduit regardless of mode (including OFF). The
+ *          remaining [TRANSPORT_OPTIONS] keys and the shared 1D sections
+ *          ([TRANSPORT_BOUNDARIES]/[TRANSPORT_SOURCES]/[STORAGE_MIXING])
+ *          arrive with plan phases E5/E2b and are refused with precise
+ *          deferral errors until then.
+ *
+ * @see plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md §4, §6 E3
+ * @see plans/transport/TRANSPORT_IO_PLUGIN_CONFIG_PLAN.md §3.2
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_ARD_CONFIG_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_ARD_CONFIG_DATA_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+/**
+ * @brief One raw [TRANSPORT_BOUNDARIES] or [TRANSPORT_SOURCES] row (E5a).
+ *
+ * @details Stored UNRESOLVED at component-apply time: the rows name MSX
+ *          species, and the reactions component may apply before or after
+ *          transport.ard in [PROCESS_COMPONENTS] file order. Resolution to
+ *          indices happens once, after all components applied
+ *          (transport::resolveArdTransportRows, called from
+ *          SWMMEngine::open) — failures are fatal there with the row's own
+ *          text in the diagnostic.
+ */
+struct ArdTransportRow {
+    std::string element;   ///< node name (boundary) / conduit name (source)
+    std::string species;   ///< MSX species name (pollutants refused in E5a)
+    bool        is_ts = false;
+    double      value = 0.0;   ///< VALUE mode: conc (BC, species units) or
+                               ///< mass rate (source, species mass units/s)
+    std::string ts_name;       ///< TIMESERIES mode
+};
+
+/// Global dispersion coefficient model ([TRANSPORT_OPTIONS] DISPERSION).
+enum class ArdDispersionMode : int {
+    OFF     = 0,  ///< no global dispersion (per-conduit overrides still apply)
+    FISCHER = 1,  ///< Fischer et al. (1979): D = 0.011 v²B²/(Y·U*), U* = √(gYS)
+    VALUE   = 2,  ///< uniform user value (display units, len²/s)
+};
+
+/**
+ * @brief Parsed `model.ard` state consumed by ArdEngine::init (phase E3).
+ *
+ * @details Filled by the transport.ard component apply hook at open; reset
+ *          wholesale at the start of each apply so a reopened model never
+ *          inherits stale rows. Per-conduit overrides are resolved to LINK
+ *          indices at apply time (unknown names are fatal there, where the
+ *          row text is still available for the diagnostic).
+ */
+struct ArdConfigData {
+    /// True once a [PROCESS_COMPONENTS] transport.ard registration applied.
+    bool configured = false;
+
+    ArdDispersionMode dispersion_mode = ArdDispersionMode::OFF;
+
+    /// Global coefficient for VALUE mode (display units, len²/s).
+    double dispersion_value = 0.0;
+
+    // Per-conduit overrides (parallel arrays, SoA): link index + coefficient
+    // in display units. Applied to every cell of the conduit; wins over the
+    // global model.
+    std::vector    conduit_disp_link;
+    std::vector conduit_disp_value;
+
+    // ---- E5a: raw boundary/source rows (cold; see ArdTransportRow) -------
+    std::vector boundary_rows;
+    std::vector source_rows;
+
+    // ---- E5a: resolved rows (hot; filled by resolveArdTransportRows) -----
+    // Boundaries: the node's EXTERNAL INFLOW water carries the MSX species
+    // at the given concentration (species units — internal store mass is
+    // conc·ft³, so no conversion). Sources: distributed over the conduit's
+    // cells, INTERNAL units conc·ft³/s (converted from species-mass/s by
+    // dividing by kLitersPerFt3 at resolution).
+    std::vector    bc_node;    ///< node index
+    std::vector    bc_msx;     ///< ReactionData species index
+    std::vector bc_value;   ///< VALUE-mode concentration
+    std::vector    bc_ts;      ///< timeseries table index, -1 ⇒ VALUE
+    std::vector    src_link;   ///< link index (conduit)
+    std::vector    src_msx;
+    std::vector src_value;  ///< VALUE-mode rate, internal conc·ft³/s
+    std::vector    src_ts;     ///< ts index, -1 ⇒ VALUE (ts values are
+                                    ///< species-mass/s; engine converts)
+    bool transport_rows_resolved = false;
+
+    // ---- E5b ------------------------------------------------------------
+    /// [TRANSPORT_OPTIONS] TARGET_DX: transport-mesh cell length under
+    /// non-FV hydraulics (display length units; 0 ⇒ FV_CELL_LENGTH rules).
+    /// Ignored with a warning under FLOW_ROUTING FV (the solver mesh
+    /// governs) — the plan §8 open item resolved.
+    double target_dx = 0.0;
+    /// IO3c provenance: true when THIS component's file carried the
+    /// SCALAR_SCHEME / LIMITER alias. The live values sit in
+    /// ctx.options.fv (the aliases write through at apply), and the
+    /// INP writer emits FV_SCALAR_SCHEME/FV_LIMITER only under
+    /// FLOW_ROUTING FV — so on a non-FV deck this file is the ONLY
+    /// carrier of that state across a save. The serializer emits the
+    /// alias (with the CURRENT live value, so API/GUI edits persist)
+    /// exactly when the flag says the file owned it; a file that
+    /// never spelled the alias never gains one (lesson 196).
+    bool sets_scalar_scheme = false;
+    bool sets_limiter = false;
+
+    /// [TRANSPORT_OPTIONS] DETAILED_OUTPUT: per-cell CSV sidecar path,
+    /// resolved at apply against the CONFIG file's directory (empty ⇒ off).
+    std::string detailed_output_path;
+
+    bool any_dispersion() const noexcept {
+        return dispersion_mode != ArdDispersionMode::OFF ||
+               !conduit_disp_link.empty();
+    }
+    bool any_transport_rows() const noexcept {
+        return !boundary_rows.empty() || !source_rows.empty();
+    }
+    /// Anything in this config that only the ARD engine can honour — the
+    /// bypass-warning predicate (lesson 10: silence is misleading whenever
+    /// ANY of it is configured but the engine will not run).
+    bool any_engine_content() const noexcept {
+        return any_dispersion() || any_transport_rows() ||
+               !detailed_output_path.empty() || target_dx > 0.0;
+    }
+};
+
+/// Litres per cubic foot — the species-mass/s → internal conc·ft³/s source
+/// conversion (internal MSX store mass is concentration (mass/L) × ft³).
+inline constexpr double kLitersPerFt3 = 28.316846592;
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_ARD_CONFIG_DATA_HPP
diff --git a/src/engine/data/BedZoneData.hpp b/src/engine/data/BedZoneData.hpp
new file mode 100644
index 000000000..fba7dff77
--- /dev/null
+++ b/src/engine/data/BedZoneData.hpp
@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file BedZoneData.hpp
+ * @brief Plan H6b — the bed / hyporheic transient-storage zone.
+ *
+ * @details A second, immobile water-and-sediment body beneath each conduit.
+ *          It exchanges with the channel by conduction and by hyporheic
+ *          advection, and it conducts to a deep-ground boundary held at a
+ *          fixed or time-varying temperature. It is the zone
+ *          HydroCouple's `HTSComponent` models as a coupled component; here
+ *          it is internal state, because SWMM has no component to couple to.
+ *
+ * @par The reference, verbatim
+ *      `HTSComponent/src/element.cpp:132-141`:
+ *      @code
+ *      mainChannelConductionHeat = alpha * W * L * (T_ch - T) * rho_s * c_s / depth;
+ *      groundConductionHeat      = alpha * W * L * (T_gr - T) * rho_s * c_s / groundConductionDepth;
+ *      mainChannelAdvectionHeat  = rho_w * c_p * Q_hts * (T_ch - T);
+ *      DTDt = (cond_mc + cond_gr + adv + ext + rad*L*W) / (rho_s * c_s * V);
+ *      @endcode
+ *      and `elementoutput.cpp:104,117` hands the channel back **`-adv` and
+ *      `-cond_mc`** — exact reciprocity. Only the ground term is a true
+ *      source or sink; everything else moves energy between two bodies that
+ *      this engine owns, so their sum is conserved and a gate asserts it.
+ *
+ * @par Three deliberate divergences from the reference, and why
+ *      1. **Contact area is the WETTED PERIMETER, not the top width.**
+ *         `HTSComponent` is an open-channel model where `W` is both. A SWMM
+ *         conduit is usually a closed pipe, whose contact with the
+ *         surrounding soil is `P = A/R`, and for a full circular pipe the
+ *         top width is **zero** — the reference's spelling would switch the
+ *         whole module off exactly when a surcharged pipe conducts most.
+ *         This is the "clear conceptual issue" exception to parity.
+ *      2. **Hyporheic exchange is a VELOCITY (m/s), not a discharge.**
+ *         `HTSComponent` receives `mainChannelAdvectionCoeff` per element
+ *         from a coupled subsurface model (`elementinput.cpp:368`). SWMM has
+ *         no such supplier, and one absolute m³/s applied to every conduit in
+ *         a network of mixed lengths is not a physical statement. `Q_hts =
+ *         v_hyp · A_bed` scales with the element the way the conduction term
+ *         already does.
+ *      3. **Sediment properties default to the STREAMBED pair (1670 kg/m³,
+ *         1807 J/kg/K)**, which is `HTSComponent`'s own
+ *         (`htsmodel.cpp:50-51`) — deliberately NOT `ConductionConfig`'s
+ *         1970/2758, which came from `GWComponent` and describes a
+ *         bioretention soil column. `HeatData.hpp:128` already records that
+ *         the two are different materials; this is the file that needs the
+ *         other one.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.3, §6.5 D-H6b
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_BED_ZONE_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_BED_ZONE_DATA_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+/**
+ * @brief `[SEDIMENT_EXCHANGE]` — the bed zone's material and geometry.
+ *
+ * @details Every field has a defensible default, so `[HEAT_FLUXES]
+ *          SEDIMENT_EXCHANGE ON` alone is a runnable configuration. Two
+ *          fields deliberately do NOT: `ground_temp` and the initial bed
+ *          temperature. See `has_ground_temp`.
+ */
+struct SedimentConfig {
+    /// Bed thermal diffusivity alpha_sed, m²/s. `HTSComponent` takes this
+    /// per element from a coupled model; 1.0e-6 is the usual saturated-sand
+    /// value and is what the reference's own test decks carry.
+    double thermal_diffusivity = 1.0e-6;
+
+    /// Bed effective solute diffusivity D_sed, m²/s. ONE value for every
+    /// species: `HTSComponent` carries a per-solute array
+    /// (`sedSoluteDiffCoefficients`) fed element by element, which SWMM
+    /// cannot supply. A per-species spelling is a later key, not a later
+    /// meaning — the physics below is already per species.
+    double solute_diffusivity = 1.0e-9;
+
+    /// Bed layer thickness Y_hts, m. The conduction length between the
+    /// channel and the bed's own mean temperature, AND the thickness that
+    /// sets the bed's heat capacity.
+    double bed_thickness = 0.20;
+
+    /// Depth from the bed to the deep-ground boundary Y_gr, m. The reference
+    /// defaults this to 0.01 m (`element.cpp:38`), which makes the ground
+    /// term dominate everything else; that is a placeholder awaiting a
+    /// coupled `GWComponent`, not a recommendation. 2 m is the depth below
+    /// which the annual signal is small for typical soils.
+    double ground_depth = 2.0;
+
+    /// Deep-ground temperature T_gr, °C. Constant spelling.
+    double ground_temp = 12.0;
+
+    /// Set by the parser when the deck stated `GROUND_TEMPERATURE`. The
+    /// module RUNS without it — 12 °C is a real number, not a sentinel — but
+    /// the ground term is often the largest one in a buried pipe, so an
+    /// unstated value is WARNED about rather than silently accepted. This is
+    /// the `SolarConfig::has_timezone` precedent, not the `has_latitude` one:
+    /// warn, do not refuse.
+    bool has_ground_temp = false;
+
+    /// `GROUND_TEMPERATURE TIMESERIES ` — index into `ctx.tables`,
+    /// -1 when the constant spelling is in force.
+    int ground_ts_index = -1;
+
+    /// Hyporheic exchange velocity v_hyp, m/s, across the bed interface.
+    /// `Q_hts = v_hyp * A_bed`. Defaults to 0 — conduction only — so a deck
+    /// that turns the module on without naming an exchange rate gets the
+    /// conduction the user asked for and no invented advection.
+    double hyporheic_velocity = 0.0;
+
+    /// Bed bulk density rho_sed, kg/m³ (`htsmodel.cpp:50`).
+    double sed_density = 1670.0;
+
+    /// Bed specific heat c_sed, J/kg/K (`htsmodel.cpp:51`).
+    double sed_specific_heat = 1807.0;
+
+    /// Initial bed temperature, °C. When the deck does not state one the
+    /// bed starts at `ground_temp`, which is the only temperature in the
+    /// configuration that describes the subsurface.
+    double initial_temp = 12.0;
+    bool   has_initial_temp = false;
+};
+
+/**
+ * @brief Runtime bed state, one entry per LINK.
+ *
+ * @details Sized to links rather than to the active engine's own elements
+ *          (ARD cells, LARD parcels) because the bed does not move and does
+ *          not subdivide: it is a property of the conduit, and every engine
+ *          can address it by link index without agreeing on a mesh.
+ *
+ * @warning Under `EULERIAN_ARD` this means the bed exchanges with the link's
+ *          VOLUME-WEIGHTED MEAN temperature, not cell by cell, so a bed
+ *          under a long conduit cannot resolve a front the way the water
+ *          above it does. That is a real loss of resolution against the
+ *          reference (whose HTS elements map 1:1 onto channel elements) and
+ *          it is recorded here rather than in a handoff because the next
+ *          person to add a cell-resolved bed needs to find it attached to
+ *          the array they would have to widen.
+ */
+struct BedZoneState {
+    std::vector link_temp;   ///< [link], °C
+    /// [link * n_species + s], concentration in the bed water, in each
+    /// species' own units. Species-minor to match `node_mass_`'s layout in
+    /// the ARD store, which is the binding most likely to index it.
+    std::vector link_conc;
+    int  n_species = 0;
+    bool seeded    = false;
+
+    // ---- ARD (cell-resolved) bed. The per-link arrays above are the
+    //      LEGACY and LARD substrate; under EULERIAN_ARD every CELL gets
+    //      its own bed slice, 1:1 — which is exactly the reference's
+    //      element mapping (HTSComponent pairs one HTS element with one
+    //      channel element) and answers "which cell does the bed under a
+    //      400 ft conduit exchange with?" with "its own". The two shapes
+    //      coexist because engine choice is per model and this state is
+    //      runtime-only (not persisted), so nothing ever has to convert
+    //      one into the other.
+    std::vector cell_temp;   ///< [cell], °C
+    /// SPECIES-MAJOR [s * n_cells + c] — `cell_phi`'s own layout, because
+    /// the ARD binding walks both arrays in the same loop and two layouts
+    /// in one loop is how a stride bug reads plausibly.
+    std::vector cell_conc;
+    int  cell_n_species = 0;
+    bool cells_seeded   = false;
+
+    void resizeCells(int n_cells, int n_spec, double t_init) {
+        const auto nc = static_cast(n_cells > 0 ? n_cells : 0);
+        const auto ns = static_cast(n_spec > 0 ? n_spec : 0);
+        cell_n_species = static_cast(ns);
+        cell_temp.assign(nc, t_init);
+        cell_conc.assign(ns * nc, 0.0);
+        cells_seeded = true;
+    }
+
+    void resize(int n_links, int n_spec, double t_init) {
+        const auto nl = static_cast(n_links > 0 ? n_links : 0);
+        const auto ns = static_cast(n_spec > 0 ? n_spec : 0);
+        n_species = static_cast(ns);
+        link_temp.assign(nl, t_init);
+        link_conc.assign(nl * ns, 0.0);
+        seeded = false;
+    }
+
+    bool sized(int n_links) const noexcept {
+        return link_temp.size() == static_cast(n_links > 0 ? n_links : 0);
+    }
+
+    void clear() { *this = BedZoneState{}; }
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_BED_ZONE_DATA_HPP
diff --git a/src/engine/data/ForcingData.hpp b/src/engine/data/ForcingData.hpp
index 5aef32da7..b72fb22e7 100644
--- a/src/engine/data/ForcingData.hpp
+++ b/src/engine/data/ForcingData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ForcingData.hpp
  * @brief Per-element runtime forcing state — SoA layout.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_FORCING_DATA_HPP
@@ -28,6 +44,8 @@
 #include 
 #include 
 
+#include "HeatOverrideData.hpp"   // HeatElement — PE4
+
 namespace openswmm {
 
 // ============================================================================
@@ -66,6 +84,19 @@ struct ForcingData {
     std::vector         node_quality_value;     ///< mass rate (mass/sec)
     std::vector node_quality_persist;
 
+    // U2 (2026-09-07) — the reserved species, the twins of node_quality:
+    // OVERRIDE sets the PUBLISHED state (degC / hours); ADD injects a rate
+    // into the loader accumulator every engine already reads
+    // (heat_state.node_temp_vol_in in degC·ft3/s,
+    // water_age_state.node_age_vol_in in s·ft3/s). One entry per node.
+    std::vector    node_temperature_mode;
+    std::vector         node_temperature_value;
+    std::vector node_temperature_persist;
+
+    std::vector    node_age_mode;
+    std::vector         node_age_value;
+    std::vector node_age_persist;
+
     // ------ Link forcing (sized to n_links) ---------------------------------
 
     std::vector    link_flow_mode;
@@ -76,6 +107,16 @@ struct ForcingData {
     std::vector         link_setting_value;     ///< 0.0–1.0 for pump/orifice/weir
     std::vector link_setting_persist;
 
+    /// G-X4 (2026-09-20): a host's conduit ⇄ groundwater exchange rate
+    /// (internal flow units, `+` OUT of the conduit — the `seep_loss_rate`
+    /// sign). This is the HydroCouple `link_exchange_flow` inlet: an
+    /// external groundwater model computes the exchange and the conduit
+    /// routes it, in place of (OVERRIDE) or on top of (ADD) whatever the
+    /// [LOSSES] rate or the internal signed law produced.
+    std::vector    link_seepage_mode;
+    std::vector         link_seepage_value;
+    std::vector link_seepage_persist;
+
     std::vector    link_quality_mode;      ///< flattened link × pollutant
     std::vector         link_quality_value;     ///< OVERRIDE: concentration; ADD: mass rate (mass/sec)
     std::vector link_quality_persist;
@@ -114,6 +155,89 @@ struct ForcingData {
     double         climate_evap_value   = 0.0;         ///< ft/sec (internal; converted from in/day or mm/day at the C API boundary)
     ForcingPersist climate_evap_persist = ForcingPersist::RESET;
 
+    // ------ PE4: per-ELEMENT climate (API only; no deck syntax) -------------
+    //
+    // Air temperature, humidity, wind and incoming shortwave are GLOBAL in
+    // every deck and per-element ONLY through this API. The caller is a
+    // coupled driver — an MCP session, a calibration loop, or a HydroCouple
+    // composition where an atmospheric or riparian-shade model owns the
+    // near-surface field — asserting the heterogeneity deliberately, per
+    // step, and answerable for it. That is how the reference works too:
+    // RHEComponent and CSHComponent receive per-element meteorology through
+    // EXCHANGE ITEMS, never through their input files.
+    //
+    // ⚠ These are resolved AT THE FLUX CALL (SurfaceExchange/RadiativeExchange),
+    // never written into ClimateState. That is the whole safety property:
+    // ClimateState is shared with hydrology, snowmelt and evaporation, and a
+    // per-link push must not reach them. A "simplification" that assigned
+    // these into climate_state would silently give the snowpack above a
+    // conduit that conduit's air temperature.
+    //
+    // Scope is LINK and NODE only. Neither has a competing consumer for air
+    // temperature — snowmelt runs on subcatchments, evaporation on
+    // subcatchment and storage surfaces — so no subsystem divergence is
+    // possible. SUBCATCH is refused at the API boundary, naming that reason.
+    //
+    // Sized lazily on first use (the D-PE2 pattern): a model that never
+    // calls these allocates nothing and pays one `.empty()` check per flux.
+    struct ElemClimateChannel {
+        std::vector    mode;
+        std::vector         value;
+        std::vector persist;
+
+        void ensure(std::size_t n) {
+            if (mode.size() == n) return;
+            mode.assign(n, ForcingMode::NONE);
+            value.assign(n, 0.0);
+            persist.assign(n, ForcingPersist::RESET);
+        }
+        /// Apply this channel at `i` to `base`; `base` when unset.
+        double apply(int i, double base) const noexcept {
+            if (i < 0) return base;
+            const auto u = static_cast(i);
+            if (u >= mode.size() || mode[u] == ForcingMode::NONE) return base;
+            return (mode[u] == ForcingMode::OVERRIDE) ? value[u]
+                                                      : base + value[u];
+        }
+        void resetPerStep() {
+            for (std::size_t i = 0; i < mode.size(); ++i)
+                if (persist[i] == ForcingPersist::RESET)
+                    mode[i] = ForcingMode::NONE;
+        }
+        void clear() { *this = ElemClimateChannel{}; }
+    };
+
+    /// [0] = LINK, [1] = NODE. Indexed by `elemSlot` below so the two kinds
+    /// cannot be confused at a call site.
+    ElemClimateChannel elem_air_temp[2];   ///< deg F
+    ElemClimateChannel elem_humidity[2];   ///< %
+    ElemClimateChannel elem_wind[2];       ///< mph
+    ElemClimateChannel elem_shortwave[2];  ///< W/m2
+
+    /// -1 for a kind that carries no per-element climate (SUBCATCH, LID).
+    static int elemSlot(HeatElemKind k) noexcept {
+        if (k == HeatElemKind::LINK) return 0;
+        if (k == HeatElemKind::NODE) return 1;
+        return -1;
+    }
+
+    double elementAirTempF(const HeatElement& e, double base) const noexcept {
+        const int s = elemSlot(e.kind);
+        return (s < 0) ? base : elem_air_temp[s].apply(e.index, base);
+    }
+    double elementHumidity(const HeatElement& e, double base) const noexcept {
+        const int s = elemSlot(e.kind);
+        return (s < 0) ? base : elem_humidity[s].apply(e.index, base);
+    }
+    double elementWindMph(const HeatElement& e, double base) const noexcept {
+        const int s = elemSlot(e.kind);
+        return (s < 0) ? base : elem_wind[s].apply(e.index, base);
+    }
+    double elementShortwave(const HeatElement& e, double base) const noexcept {
+        const int s = elemSlot(e.kind);
+        return (s < 0) ? base : elem_shortwave[s].apply(e.index, base);
+    }
+
     // ------ Counts (for iteration) ------------------------------------------
 
     int n_nodes_      = 0;
@@ -156,6 +280,14 @@ struct ForcingData {
         node_quality_value.assign(unp, 0.0);
         node_quality_persist.assign(unp, ForcingPersist::RESET);
 
+        node_temperature_mode.assign(un, ForcingMode::NONE);
+        node_temperature_value.assign(un, 0.0);
+        node_temperature_persist.assign(un, ForcingPersist::RESET);
+
+        node_age_mode.assign(un, ForcingMode::NONE);
+        node_age_value.assign(un, 0.0);
+        node_age_persist.assign(un, ForcingPersist::RESET);
+
         link_flow_mode.assign(ul, ForcingMode::NONE);
         link_flow_value.assign(ul, 0.0);
         link_flow_persist.assign(ul, ForcingPersist::RESET);
@@ -164,6 +296,10 @@ struct ForcingData {
         link_setting_value.assign(ul, 0.0);
         link_setting_persist.assign(ul, ForcingPersist::RESET);
 
+        link_seepage_mode.assign(ul, ForcingMode::NONE);          // G-X4
+        link_seepage_value.assign(ul, 0.0);
+        link_seepage_persist.assign(ul, ForcingPersist::RESET);
+
         auto ulp = static_cast(n_links) *
                    static_cast(n_pollutants);
         link_quality_mode.assign(ulp, ForcingMode::NONE);
@@ -197,8 +333,11 @@ struct ForcingData {
         set_none(node_lat_inflow_mode);
         set_none(node_head_boundary_mode);
         set_none(node_quality_mode);
+        set_none(node_temperature_mode);
+        set_none(node_age_mode);
         set_none(link_flow_mode);
         set_none(link_setting_mode);
+        set_none(link_seepage_mode);   // G-X4
         set_none(link_quality_mode);
         set_none(subcatch_rainfall_mode);
         set_none(subcatch_evap_mode);
@@ -226,8 +365,11 @@ struct ForcingData {
         clear_resets(node_lat_inflow_mode,      node_lat_inflow_persist);
         clear_resets(node_head_boundary_mode,    node_head_boundary_persist);
         clear_resets(node_quality_mode,          node_quality_persist);
+        clear_resets(node_temperature_mode,      node_temperature_persist);
+        clear_resets(node_age_mode,              node_age_persist);
         clear_resets(link_flow_mode,             link_flow_persist);
         clear_resets(link_setting_mode,          link_setting_persist);
+        clear_resets(link_seepage_mode,          link_seepage_persist);   // G-X4
         clear_resets(link_quality_mode,          link_quality_persist);
         clear_resets(subcatch_rainfall_mode,     subcatch_rainfall_persist);
         clear_resets(subcatch_evap_mode,         subcatch_evap_persist);
@@ -239,6 +381,19 @@ struct ForcingData {
             climate_wind_mode = ForcingMode::NONE;
         if (climate_evap_persist == ForcingPersist::RESET)
             climate_evap_mode = ForcingMode::NONE;
+        // PE4: the per-element channels join the SAME sweep, so RESET
+        // semantics cannot drift between the global and element spellings.
+        // RESET is the documented default for a coupled driver: under
+        // PERSIST, a driver that pushes on some steps and not others
+        // silently reuses a stale field that looks like data and is hours
+        // old. Under RESET the value falls back to the global broadcast the
+        // moment the driver stops feeding it.
+        for (int k = 0; k < 2; ++k) {
+            elem_air_temp[k].resetPerStep();
+            elem_humidity[k].resetPerStep();
+            elem_wind[k].resetPerStep();
+            elem_shortwave[k].resetPerStep();
+        }
     }
 
     /**
diff --git a/src/engine/data/GageData.hpp b/src/engine/data/GageData.hpp
index 4b346f31f..b087f29d7 100644
--- a/src/engine/data/GageData.hpp
+++ b/src/engine/data/GageData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GageData.hpp
  * @brief Structure-of-Arrays (SoA) storage for rain gages.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_GAGE_DATA_HPP
@@ -55,7 +71,9 @@ enum class RainFileFormat : int8_t {
     DSI_3260 = 3,   ///< NCDC DSI 3260 15-minute
     HLY_PRCP = 4,   ///< HLY_PRCP format
     STAN_PRCP = 5,  ///< Standard SWMM rain file
-    USER_CSV = 6    ///< User-supplied multi-column CSV (new in 6.0.0, R08)
+    USER_CSV = 6    ///< User-supplied multi-column text file — CSV, TSV, or
+                    ///< PCSWMM TSF, auto-detected by content (new in 6.0.0,
+                    ///< R08; extended per MULTICOLUMN_SERIES_SINGLE_READ plan)
 };
 
 // ============================================================================
@@ -110,8 +128,9 @@ struct GageData {
     std::vector    ts_name;
 
     /**
-     * @brief Column name in the external CSV (when source == FILE_RAIN).
-     * @details New in 6.0.0 — supports "FILE path.csv:COLUMN_NAME" syntax (R08).
+     * @brief Column name in the external multi-column file (source == FILE_RAIN).
+     * @details New in 6.0.0 — supports "FILE path.csv:COLUMN_NAME" syntax (R08)
+     *          for multi-column CSV/TSV/TSF files (format auto-detected).
      *          Empty string means use the first/only data column.
      */
     std::vector    col_name;
@@ -225,6 +244,38 @@ struct GageData {
      */
     std::vector           is_raining;
 
+    /**
+     * @brief Legacy rain-gage state machine (gage_initState / gage_setState /
+     *        getNextRainfall), kept as record indices on the gage's series
+     *        and advanced by updateAllGages():
+     *        - st_cur: the record legacy's startDate/endDate name — -2 while
+     *          there is no state (NO_DATE: no series, empty series,
+     *          IGNORE_RAINFALL, not yet initialised), -1 for the pre-record
+     *          interval [StartDateTime, x0) legacy forms when the record
+     *          begins after the simulation start, else a record index (the
+     *          FIRST record whatever its value, afterwards only records with
+     *          a non-zero rate: getNextRainfall skips zero rates);
+     *        - st_next: the record legacy's nextDate/nextRainfall name, -1
+     *          for NO_DATE;
+     *        - st_rain: legacy Gage.rainfall as the machine last left it
+     *          (0 in a gap, the current record's rate otherwise), the value
+     *          gage_setReportRainfall reads; user rain units with the units
+     *          and scale factors, before the monthly rain adjustment.
+     *        - st_init: the machine has been seeded (lazily, on the first
+     *          update, from the simulation start date); st_used: legacy
+     *          Gage.isUsed as found then — an unused gage's machine never
+     *          advances and its rainfall keeps the seeded value (legacy
+     *          gage_setState returns at once; runoff_execute still reads
+     *          Gage.rainfall for IsRaining).
+     * @see Legacy: gage_initState, gage_setState, getNextRainfall,
+     *      gage_getNextRainDate, gage_setReportRainfall
+     */
+    std::vector            st_cur;
+    std::vector            st_next;
+    std::vector         st_rain;
+    std::vector        st_init;
+    std::vector        st_used;
+
     // -----------------------------------------------------------------------
     // Past-rain history (for control rules — GAGE_RAIN_PAST)
     // -----------------------------------------------------------------------
@@ -295,6 +346,11 @@ struct GageData {
         api_rainfall.assign(un, -1.0);  // -1.0 means no API override
         next_rain_date.assign(un, 0.0);
         is_raining.assign(un, false);
+        st_cur.assign(un, -2);
+        st_next.assign(un, -1);
+        st_rain.assign(un, 0.0);
+        st_init.assign(un, 0);
+        st_used.assign(un, 0);
 
         past_rain.assign(un * MAXPASTRAIN, 0.0);
         past_rain_accum.assign(un, 0.0);
@@ -326,6 +382,8 @@ struct GageData {
         g(scale_factor, 1.0);
         g(rainfall, 0.0); g(next_rainfall, 0.0);
         g(api_rainfall, -1.0); g(next_rain_date, 0.0); g(is_raining, false);
+        g(st_cur, -2); g(st_next, -1); g(st_rain, 0.0); g(st_init, static_cast(0));
+        g(st_used, static_cast(0));
         // Flat 2D: [gage * MAXPASTRAIN + hour]
         past_rain.resize(un * static_cast(MAXPASTRAIN), 0.0);
         g(past_rain_accum, 0.0); g(past_rain_time, 0.0); g(cumul_rain_accum, 0.0);
@@ -348,6 +406,7 @@ struct GageData {
         e(file_path); e(col_name); e(file_format); e(interval_sec); e(snow_factor);
         e(scale_factor);
         e(rainfall); e(next_rainfall); e(api_rainfall); e(next_rain_date); e(is_raining);
+        e(st_cur); e(st_next); e(st_rain); e(st_init); e(st_used);
         e(past_rain_accum); e(past_rain_time); e(cumul_rain_accum); e(co_gage_index);
         e(comments);
 
@@ -379,6 +438,11 @@ struct GageData {
         api_rainfall.shrink_to_fit();
         next_rain_date.shrink_to_fit();
         is_raining.shrink_to_fit();
+        st_cur.shrink_to_fit();
+        st_next.shrink_to_fit();
+        st_rain.shrink_to_fit();
+        st_init.shrink_to_fit();
+        st_used.shrink_to_fit();
 
         past_rain.shrink_to_fit();
         past_rain_accum.shrink_to_fit();
@@ -393,6 +457,11 @@ struct GageData {
         std::fill(next_rainfall.begin(), next_rainfall.end(), 0.0);
         std::fill(api_rainfall.begin(),  api_rainfall.end(),  -1.0); // -1 = no override
         std::fill(is_raining.begin(),    is_raining.end(),    false);
+        std::fill(st_cur.begin(),  st_cur.end(),  -2);
+        std::fill(st_next.begin(), st_next.end(), -1);
+        std::fill(st_rain.begin(), st_rain.end(), 0.0);
+        std::fill(st_init.begin(), st_init.end(), static_cast(0));
+        std::fill(st_used.begin(), st_used.end(), static_cast(0));
         std::fill(past_rain.begin(),     past_rain.end(),     0.0);
         std::fill(past_rain_accum.begin(), past_rain_accum.end(), 0.0);
         std::fill(past_rain_time.begin(),  past_rain_time.end(),  0.0);
diff --git a/src/engine/data/HeatData.hpp b/src/engine/data/HeatData.hpp
new file mode 100644
index 000000000..61c322cc3
--- /dev/null
+++ b/src/engine/data/HeatData.hpp
@@ -0,0 +1,557 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatData.hpp
+ * @brief Heat-transport data (heat plan §1, §3; phase H1).
+ *
+ * @details Temperature is the reserved species `__TEMPERATURE__` (registry
+ *          kind RESERVED_TEMPERATURE), advected and mixed by whichever
+ *          quality engine is active. H1 delivers TRANSPORT ONLY — the
+ *          surface, radiative and sediment flux modules of plan §2 arrive
+ *          with H2–H4, so nothing here adds or removes energy; temperature
+ *          is carried and mixed exactly as a conservative tracer.
+ *
+ *          Per-source inlet temperatures come from the heat component's
+ *          `[HEAT_SOURCES]` (`model.heat`, D-UT8), mirroring
+ *          `[WATER_AGE_SOURCES]` row-for-row. Each QualitySolver loader
+ *          contributes `q · T_source` to its node, the same seam the age
+ *          channel uses (master plan §4.3 / D-UT10).
+ *
+ * @par Why this carries temperature-volume and not Joules
+ *      Plan §3 describes the channel as enthalpy `ρw cp V T_source`. At H1
+ *      there are no energy fluxes, so ρw and cp appear on BOTH sides of
+ *      every mixing operation and cancel identically — carrying them would
+ *      ship two constants that no H1 gate could observe being wrong
+ *      (lesson 39: unobserved is not tested). `node_temp_vol_in` is
+ *      therefore `q · T` (°C·ft³/s), the exact analogue of
+ *      `node_age_vol_in`. **H2 introduces the constants together with the
+ *      W/m² fluxes that make them load-bearing and observable**, and
+ *      rescales this accumulator to J/s at that point — a rename in the
+ *      same loader sites, which is the churn D-UT10 already accepted as
+ *      cheap.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §1, §3, §6 H1
+ * @see data/WaterAgeData.hpp — the shape this mirrors
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_HEAT_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_HEAT_DATA_HPP
+
+#include 
+#include 
+
+#include "BedZoneData.hpp"      // SedimentConfig — H6b's bed zone configuration
+#include "HeatOverrideData.hpp" // HeatElement / HeatAttr / HeatScope — PE
+
+namespace openswmm {
+
+/// Source pathways with a configurable inlet temperature ([HEAT_SOURCES]).
+/// Order is the storage index of HeatConfigData::global_temp, and matches
+/// WaterAgeSource one-for-one so the two tables read the same way.
+enum class HeatSource : int {
+    RAINFALL        = 0,  ///< washoff runoff. H5b retired this row's
+                          ///< second job: a LID drain now leaves at its
+                          ///< own storage-layer temperature, not the rain's.
+    DWF             = 1,
+    GW              = 2,
+    RDII            = 3,
+    EXTERNAL_INFLOW = 4,
+    IFACE           = 5,
+    INITIAL_STATE   = 6,  ///< water in the network at t = 0
+    COUNT_          = 7
+};
+
+/// H5a: which subarea of a subcatchment a ponded temperature belongs to.
+/// Deliberately a SEPARATE enum from `openswmm::SubArea` (A3's), even though
+/// the members coincide today: nothing guarantees the age and heat tracks
+/// keep the same subarea decomposition, and a shared enum would make a
+/// future divergence a silent index error rather than a compile error.
+enum class HeatSubArea : int {
+    IMPERV0 = 0,
+    IMPERV1 = 1,
+    PERV    = 2,
+    COUNT_  = 3
+};
+
+/**
+ * @brief What a dry or absent element reports (plan D-H5c, user 2026-08-19).
+ *
+ * @details A4 zeroes a LID layer holding no water — "no water, no age" — and
+ *          that is right for age and wrong for temperature, because 0 °C is
+ *          a real temperature. The three defensible answers serve different
+ *          studies, so the deck picks one rather than the engine deciding.
+ */
+enum class DryTempPolicy : int {
+    /// Freeze the last wet value; rewetting mixes against it. Invents no
+    /// number and needs no forcing series, which is why it is the default.
+    HOLD    = 0,
+    /// Track air temperature — the physical answer for an exposed dry
+    /// surface. Costs a dependency on the met forcing.
+    AIR     = 1,
+    /// Fall to `HeatConfigData::kDefaultTemp`. Reproducible, but it invents
+    /// a number that then looks like data.
+    DEFAULT = 2
+};
+
+
+/**
+ * @brief Vertical conduction between LID layers (plan §6.1 D-H5b, H5b).
+ *
+ * @details **New physics with no in-engine precedent** — every
+ *          "conductivity" elsewhere in `src/engine/` is HYDRAULIC. Values
+ *          follow HydroCouple's `GWComponent`, a porous soil/gravel column
+ *          being the closest analogue to a bioretention or permeable-
+ *          pavement stack.
+ *
+ * @warning The values below are the ones GWComponent's CONSTRUCTOR sets
+ *          (`gwmodel.cpp:51-52`), **not** the in-class initializers in
+ *          `gwmodel.h:870-871`, which say 2650 kg/m³ and 880 J/kg/°C and are
+ *          dead — the member-init list overrides both. The two differ by a
+ *          factor of 2.3 in `ρ·cp`. The plan originally recorded the header
+ *          pair; that was lesson 69 (a declaration is not a value) landing
+ *          on the parameters the decision itself named.
+ *          `HTSComponent` uses 1670/1807 for STREAMBED sediment — a third
+ *          defensible pair, deliberately not taken here.
+ */
+struct ConductionConfig {
+    double water_conductivity = 0.606;   ///< W/m/K  (gwmodel.h:885)
+    double sed_conductivity   = 2.6;     ///< W/m/K  (gwmodel.h:886)
+    double sed_density        = 1970.0;  ///< kg/m³  (gwmodel.cpp:51)
+    double sed_specific_heat  = 2758.0;  ///< J/kg/K (gwmodel.cpp:52)
+};
+
+/**
+ * @brief Where incoming shortwave `Jin` comes from (plan §2.5, phase H6a).
+ *
+ * @details The three spellings of `[RADIATIVE_FLUXES] SHORTWAVE` are
+ *          **mutually exclusive by parse error, not by precedence**
+ *          (D-H6a-3). A ladder would let a deck configuring two sources run
+ *          plausibly while silently discarding one; the parser refuses
+ *          instead, the way it already refuses an out-of-range fraction
+ *          rather than clamping it.
+ */
+enum class ShortwaveMode : int {
+    CONSTANT   = 0,  ///< `SHORTWAVE GLOBAL ` — the H3 spelling.
+    TIMESERIES = 1,  ///< `SHORTWAVE GLOBAL TIMESERIES ` — measured.
+    COMPUTED   = 2   ///< `SHORTWAVE GLOBAL COMPUTED` — position + clear-sky.
+};
+
+/**
+ * @brief `[SOLAR_RADIATION]` — site geometry and Bird atmosphere (H6a).
+ *
+ * @warning `latitude`/`longitude` have **no usable default** and the
+ *          COMPUTED branch refuses without them. This is deliberate and is
+ *          stricter than D-H5c's dry-element policy, which does default:
+ *          a dry-element convention has a defensible default, an unstated
+ *          latitude does not. `ClimateState::latitude` cannot stand in —
+ *          it is the `[TEMPERATURE]` SNOWMELT field, defaults to 0, and is
+ *          written only by decks carrying that line, so borrowing it would
+ *          silently model equatorial noon (plan §2.5 trap 1).
+ *
+ * @note `ClimateState::dtlong` cannot stand in for `longitude` either: it
+ *       is a solar-time correction in MINUTES carrying a sentinel (0 means
+ *       "true solar time", which is not "longitude 0"). Plan §2.5 trap 2.
+ */
+struct SolarConfig {
+    double latitude_deg   = 0.0;    ///< +N. REQUIRED under COMPUTED.
+    double longitude_deg  = 0.0;    ///< +E. REQUIRED under COMPUTED.
+    double timezone_hours = 0.0;    ///< Offset from UTC, +E (e.g. MST = -7).
+    bool   has_latitude   = false;  ///< Set by the parser, checked at close.
+    bool   has_longitude  = false;
+    /// Not required — 0 (UTC) is a legal answer — but an OMITTED timezone
+    /// shifts the whole diurnal curve by up to 12 h, which dwarfs every
+    /// other error in this module. Tracked so the parser can WARN.
+    bool   has_timezone   = false;
+
+    /// Site elevation, metres, for the Bird pressure term. Absent means
+    /// "take the climate state's `elev`", which is the usual case.
+    ///
+    /// A `< 0` sentinel was the first spelling and was wrong: the parser
+    /// deliberately admits elevations below sea level (the Dead Sea, the
+    /// Salton Sea), and every one of them would have been silently
+    /// discarded in favour of the climate value. An explicit flag cannot
+    /// collide with a legal value.
+    double elevation_m    = 0.0;
+    bool   has_elevation  = false;
+
+    // ---- Bird & Hulstrom (1981) atmosphere. Defaults are the paper's
+    //      standard atmosphere.
+    double aod380        = 0.30;   ///< Aerosol optical depth at 380 nm
+    double aod500        = 0.20;   ///< Aerosol optical depth at 500 nm
+    double precip_water_cm = 1.42; ///< Precipitable water vapour, cm
+    double ozone_cm        = 0.34; ///< Ozone column, cm (NTP)
+    double ground_albedo   = 0.20; ///< Surface albedo for the sky-ground
+                                   ///< multiple-reflection term. NOT
+                                   ///< `RadiativeConfig::albedo`, which is
+                                   ///< the WATER's reflectance — two
+                                   ///< different surfaces, deliberately two
+                                   ///< different fields.
+};
+
+/**
+ * @brief `[CLOUD_COVER]` — one fraction driving two modules (H6a, D-H6a-2).
+ *
+ * @details Cloud lives here rather than in `RadiativeConfig` because the
+ *          same `C` feeds BOTH shortwave attenuation and the longwave
+ *          emissivity correction. Two modules reading a value from two
+ *          copies is free to drift; D-H5e is the nearest precedent in kind.
+ *
+ * @warning `lw_cloud_k` reaches into the H3-validated Brunt path. The
+ *          factor MUST reduce to exactly 1.0 at `C = 0` — see
+ *          `cloudLongwaveFactor`, which returns a literal 1.0 on the
+ *          `!configured` path rather than evaluating `1 + k·0²`.
+ */
+struct CloudConfig {
+    bool   configured = false;  ///< No `[CLOUD_COVER]` section → clear sky.
+    bool   use_timeseries = false;
+    int    ts_index   = -1;     ///< Index into `ctx.tables`, -1 = none.
+    double fraction   = 0.0;    ///< C ∈ [0,1], constant spelling.
+
+    double sw_atten_k = 0.75;   ///< Kasten–Czeplak k
+    double sw_atten_n = 3.4;    ///< Kasten–Czeplak n
+    double lw_cloud_k = 0.17;   ///< Bolz k_lw
+};
+
+/**
+ * @brief `[RADIATIVE_FLUXES]` parameters (heat plan §2.2, phase H3).
+ *
+ * @details Defaults are RHEComponent's (`rhemodel.cpp:43-47`) except where
+ *          noted. GLOBAL scope only in H3; per-element ranges are RHE's
+ *          `[RADIATIVE_FLUXES]` semantics and refuse until a later phase.
+ *          H6a keeps GLOBAL scope deliberately — plan §7 records why (the
+ *          per-step solar position is computed once, not per element).
+ */
+struct RadiativeConfig {
+    double shortwave_wm2   = 0.0;   ///< Incoming solar Jin, W/m² (0 = night)
+    double albedo          = 0.0;   ///< Rs, reference default
+    double shade_factor    = 0.0;   ///< fs, 0 = unshaded
+    double sky_view        = 1.0;   ///< fsky, 1 = open sky
+    double emiss_water     = 0.97;  ///< εw
+    double emiss_landcover = 0.97;  ///< εlc
+    double atm_emiss_coeff = 0.5;   ///< Brunt Aa
+    double lw_reflection   = 0.03;  ///< RL
+
+    /**
+     * @brief Land-cover radiating temperature, °C. NaN ⇒ use air temperature.
+     *
+     * @details PE2. `RadiativeExchange` computed the land-cover longwave
+     *          term from AIR temperature and its own header recorded that as
+     *          a departure from the reference, which carries a per-element
+     *          `landCoverTemperature`. The consequence is a daytime
+     *          understatement: a sunlit canopy or a concrete wall runs well
+     *          above air temperature and radiates accordingly.
+     *
+     *          The NaN sentinel — not a plausible number — is what keeps
+     *          every pre-PE model bit-identical and makes "the deck set
+     *          this" distinguishable from "the deck did not", the
+     *          `configured_source[]` distinction one struct over. A default
+     *          of, say, 20.0 would be indistinguishable from a deliberate
+     *          20 °C and would change every existing answer.
+     */
+    double landcover_temp = std::numeric_limits::quiet_NaN();
+
+    /// H6a. CONSTANT keeps `shortwave_wm2` load-bearing and is the default,
+    /// so an H3-era deck is unaffected.
+    ShortwaveMode sw_mode = ShortwaveMode::CONSTANT;
+    /// Index into `ctx.tables` under TIMESERIES; -1 otherwise.
+    int sw_ts_index = -1;
+};
+
+/**
+ * @brief Dense per-element attribute storage (PE2, D-PE2).
+ *
+ * @details Sized ONLY when at least one override row targets the family.
+ *          `radiativeFor`/`sedimentFor` return the global when the vector is
+ *          empty, so a model without overrides allocates nothing and passes
+ *          the same object it passed before PE — byte-identity is structural
+ *          rather than tested.
+ *
+ * @warning Do not size these unconditionally "for uniformity". That single
+ *          change would move every heat deck in the corpus, and it would do
+ *          it by writing globals into a vector that then reads back as
+ *          per-element configuration.
+ */
+struct HeatOverrideData {
+    std::vector rows;   ///< as parsed; the serializer's input
+
+    std::vector rad_link;   ///< [link], empty ⇒ use global
+    std::vector rad_node;   ///< [node], empty ⇒ use global
+    std::vector  sed_link;   ///< [link], empty ⇒ use global
+
+    bool resolved = false;
+
+    bool empty() const noexcept { return rows.empty(); }
+    void clear() { *this = HeatOverrideData{}; }
+};
+
+/**
+ * @brief Parsed `model.heat` state (heat component, phase H1).
+ *
+ * @details Mirrors WaterAgeConfigData, with one difference that matters:
+ *          the default is **not** zero. An unset source temperature means
+ *          "not configured", and 0 °C is a perfectly ordinary temperature,
+ *          so a defaulted-to-zero table would silently chill every model.
+ *          `kDefaultTemp` is the documented default inlet temperature and
+ *          `configured_source[]` records which rows the user actually set,
+ *          so a gate (and a user) can tell a deliberate 0 °C from a
+ *          default.
+ */
+struct HeatConfigData {
+    bool configured = false;
+
+    /// `[HEAT_FLUXES] RADIATIVE_EXCHANGE ON` (plan §2.2, phase H3).
+    /// Defaults OFF for the same reason SurfaceExchange does.
+    bool radiative_exchange = false;
+
+    /// Parameters for the module above.
+    RadiativeConfig radiative;
+
+    /**
+     * @brief `[HEAT_FLUXES] SURFACE_EXCHANGE ON` — latent + sensible
+     *        exchange at the free surface (plan §2.1, phase H2).
+     *
+     * @details Defaults OFF so H1's pure-transport behaviour is what a deck
+     *          gets unless it asks for physics, and so every existing
+     *          `.out` stays byte-identical. Each flux module of plan §2 is
+     *          independently toggleable; radiative and sediment exchange
+     *          arrive with H3/H4 and their keys refuse until then.
+     */
+    bool surface_exchange = false;
+
+    /// `[HEAT_FLUXES] DRY_ELEMENT_TEMPERATURE HOLD|AIR|DEFAULT` (D-H5c).
+    DryTempPolicy dry_temp_policy = DryTempPolicy::HOLD;
+
+    /// `[HEAT_FLUXES] LAYER_CONDUCTION ON` — vertical conduction between
+    /// LID layers (plan §2, phase H5b, D-H5b). Defaults OFF like every other
+    /// flux module, so a deck gets pure transport unless it asks for physics.
+    bool layer_conduction = false;
+
+    /// Parameters for the module above.
+    ConductionConfig conduction;
+
+    /// `[HEAT_FLUXES] SEDIMENT_EXCHANGE ON` — the bed / hyporheic transient
+    /// storage zone (plan §2.3, phase H6b). Defaults OFF like every other
+    /// flux module. **Unlike the others it is not a surface flux**: it adds a
+    /// second state variable and is integrated as a coupled pair, which is
+    /// why its physics lives in `BedExchange.hpp` rather than as another
+    /// term in `netFluxOut`. See that header for why the earlier prediction
+    /// that it would be one term was wrong.
+    bool sediment_exchange = false;
+
+    /// `[SEDIMENT_EXCHANGE]` — parameters for the module above. Deliberately
+    /// a SEPARATE struct from `ConductionConfig`: that one describes a
+    /// bioretention soil column (GWComponent, 1970/2758), this one describes
+    /// streambed sediment (HTSComponent, 1670/1807). Sharing them would make
+    /// one number stand for two materials.
+    SedimentConfig sediment;
+
+    /// PE2 — per-element overrides for `radiative` and `sediment` above.
+    /// Empty on every model that does not use them.
+    HeatOverrideData overrides;
+
+    /// `[SOLAR_RADIATION]` — only consulted under `ShortwaveMode::COMPUTED`
+    /// (plan §2.5, phase H6a).
+    SolarConfig solar;
+
+    /// `[CLOUD_COVER]` — consulted by BOTH the shortwave and longwave paths
+    /// (plan §2.5, D-H6a-2).
+    CloudConfig cloud;
+
+    /// Default inlet temperature when a source has no row (°C).
+    static constexpr double kDefaultTemp = 20.0;
+
+    /// GLOBAL inlet temperature per source, °C.
+    double global_temp[static_cast(HeatSource::COUNT_)] = {
+        kDefaultTemp, kDefaultTemp, kDefaultTemp, kDefaultTemp,
+        kDefaultTemp, kDefaultTemp, kDefaultTemp};
+
+    /// Whether the user set this source explicitly (vs. taking the default).
+    bool configured_source[static_cast(HeatSource::COUNT_)] = {};
+
+    // NODE-scope overrides (DWF / EXTERNAL_INFLOW), parallel arrays.
+    std::vector    node_over_source;  ///< HeatSource as int
+    std::vector    node_over_node;    ///< node index
+    std::vector node_over_temp;    ///< °C
+
+    /// Temperature of `source` water entering `node` (°C).
+    double source_temp(HeatSource s, int node) const noexcept {
+        for (std::size_t i = 0; i < node_over_source.size(); ++i)
+            if (node_over_source[i] == static_cast(s) &&
+                node_over_node[i] == node)
+                return node_over_temp[i];
+        return global_temp[static_cast(s)];
+    }
+};
+
+/**
+ * @brief Runtime heat state shared by the engines (phase H1).
+ *
+ * @details `node_temp_vol_in` is a RATE (°C·ft³/s) — loaders add `q · T`
+ *          and the engine integrates it over its substeps, exactly as
+ *          `node_age_vol_in` does for age. `node_temp`/`link_temp` are the
+ *          PUBLISHED temperatures (°C) the reports and gates read.
+ */
+struct HeatState {
+    std::vector node_temp_vol_in;  ///< [node], °C·ft³/s
+    /// [node], °C·ft³/s arriving through LID underdrains, accumulated in the
+    /// runoff step beside `nodes.lid_drain_qual_vol` and consumed by the
+    /// wet-weather loader on that same per-runoff-step cadence — the twin of
+    /// `WaterAgeState::node_lid_drain_age_vol_in`. Until this existed the
+    /// drain-to-node loader handed the drain the RAINFALL temperature, so
+    /// H5b's storage-layer temperature reached run-on receivers but never a
+    /// node (LID fix round, 2026-08-30).
+    std::vector node_lid_drain_temp_vol_in;
+    std::vector node_temp;         ///< [node], °C
+    std::vector link_temp;         ///< [link], °C
+
+    /// The LEGACY mirror seeds INITIAL_STATE on its first step.
+    bool legacy_seeded = false;
+
+    // ---- H6a per-step solar forcing (plan §2.5). RESOLVED ONCE PER STEP by
+    //      `updateSolarForcing`, then read const by every flux call.
+    //
+    //      This is state, not config, which is why it lives here: `Jin`
+    //      under TIMESERIES or COMPUTED changes every step, while
+    //      `RadiativeConfig::shortwave_wm2` is what the deck wrote and must
+    //      not be overwritten (a hot-started or re-opened model would
+    //      otherwise resume from a stale interpolation rather than from its
+    //      own configuration).
+    //
+    //      It is also what keeps the SPA cost argument honest: shortwave is
+    //      GLOBAL scope, so the position is computed once per step and every
+    //      element reads the same cached number. A per-element solve is
+    //      plan §7 work and would not use this field.
+
+    /// Incoming shortwave at the current step, W/m², cloud already applied.
+    ///
+    /// **NEGATIVE means "not yet resolved this run"**, and that is
+    /// load-bearing, not decorative. `radiativeFluxOut` passes this
+    /// straight into `netRadiativeFluxOut`'s `jin_wm2`, whose documented
+    /// sentinel for "use the configured constant" is a negative value. A
+    /// 0.0 default would make that sentinel unreachable from the
+    /// production path, so any call landing before the step's
+    /// `updateSolarForcing` would silently drop the shortwave term to zero
+    /// instead of falling back on `RadiativeConfig::shortwave_wm2`.
+    /// `updateSolarForcing` never writes a negative (it ends in
+    /// `max(0.0, ...)`), so the sentinel cannot be confused with a
+    /// resolved night-time 0.
+    double shortwave_now = -1.0;
+    /// Cloud fraction at the current step, C ∈ [0,1]. 0 = clear.
+    double cloud_now = 0.0;
+
+    // ---- H5a watershed rows. Sized by `resizeWatershed`, NOT by `resize`.
+    //      Kept a separate call deliberately: A3 widened `WaterAgeState::
+    //      resize` with a defaulted third parameter, four existing two-
+    //      argument call sites then silently emptied the new arrays at
+    //      runtime, and the validator had to remove the default to move the
+    //      failure back to the compiler. A second function cannot be called
+    //      short, so the hazard is unrepresentable rather than observed.
+
+    /// [subcatch * kNSubArea + subarea], °C — ponded surface temperature.
+    std::vector subarea_temp;
+    /// [subcatch * kNSubArea + subarea], ft³ — that subarea's stored water at
+    /// the END of the previous step. The solver overwrites its depths in
+    /// place, so the old volume is otherwise gone by the time this runs.
+    std::vector subarea_vol_prev;
+    /// [subcatch], °C — temperature the subcatchment's runoff leaves at.
+    std::vector subcatch_runoff_temp;
+    /// [subcatch], °C·ft³/s — per-step RATE accumulator for arriving run-on,
+    /// following the `node_temp_vol_in` convention: donors accumulate
+    /// `q · T`, and it is zeroed once consumed.
+    std::vector subcatch_runon_temp_vol_in;
+
+    /// [subcatch], ft³/s — the run-on rate whose temperature is KNOWN, i.e.
+    /// the flow actually represented in `subcatch_runon_temp_vol_in`.
+    ///
+    /// @details This is the pair that keeps A3's defect from recurring.
+    ///          `subcatches.runon_inflow` has THREE contributors (the
+    ///          subcatchment cascade, the LID underdrain return, and the
+    ///          outfall return); A3 filled its age numerator from one of
+    ///          them and divided by all three, so the arriving age was
+    ///          dragged toward zero — measured at 3.834 h under a 4 h rain,
+    ///          younger than anything entering the model.
+    ///
+    ///          Carrying the rate alongside the numerator makes the ratio a
+    ///          true mean of whatever was counted, whether that is one
+    ///          contributor or three. **H5a counts the cascade and the
+    ///          outfall return; the LID underdrain arrives with H5b**,
+    ///          because a drain's temperature is a per-layer quantity that
+    ///          does not exist until the LID layer species row does. Until
+    ///          then the omission biases nothing — it simply averages over
+    ///          less water, which is the difference between an incomplete
+    ///          answer and a wrong one.
+    std::vector subcatch_runon_temp_rate;
+
+    /// [subcatch], °C·ft³ — outfall-return temperature-volume, accumulated on
+    /// the ROUTING clock beside `subcatches.outfall_runon_vol` and consumed
+    /// on the RUNOFF clock. A volume, not a rate, for exactly the reason its
+    /// age counterpart is: the two clocks differ, so the producer cannot
+    /// know the interval the consumer will divide by.
+    std::vector subcatch_outfall_temp_vol;
+
+    /// LID underdrain water sent to a subcatchment: cfs x temperature,
+    /// accumulated when the units run and handed to the run-on assembly at
+    /// the start of the NEXT runoff step beside the drain's cfs
+    /// (subcatches.lid_drain_runon_cfs) — the run-on assembly is where every
+    /// contributor's flow and temperature are booked together.
+    std::vector subcatch_lid_drain_temp_cfs;
+
+    static constexpr int kNSubArea = static_cast(HeatSubArea::COUNT_);
+
+    void resize(int n_nodes, int n_links, double initial_temp) {
+        node_temp_vol_in.assign(static_cast(n_nodes), 0.0);
+        node_lid_drain_temp_vol_in.assign(static_cast(n_nodes), 0.0);
+        node_temp.assign(static_cast(n_nodes), initial_temp);
+        link_temp.assign(static_cast(n_links), initial_temp);
+        legacy_seeded = false;
+        // H6a. `clear()` resets these via whole-struct assignment, but
+        // `resize()` is what runs at INITIALIZE — so a re-initialize on an
+        // already-run context would otherwise leave the previous run's
+        // forcing readable, and `swmm_heat_get_current_shortwave` documents
+        // itself as unresolved before the first step.
+        shortwave_now = -1.0;
+        cloud_now     = 0.0;
+    }
+
+    void resizeWatershed(int n_subcatch, double initial_temp) {
+        const auto n = static_cast(n_subcatch);
+        subarea_temp.assign(n * static_cast(kNSubArea),
+                            initial_temp);
+        subarea_vol_prev.assign(n * static_cast(kNSubArea), 0.0);
+        subcatch_runoff_temp.assign(n, initial_temp);
+        subcatch_runon_temp_vol_in.assign(n, 0.0);
+        subcatch_runon_temp_rate.assign(n, 0.0);
+        subcatch_outfall_temp_vol.assign(n, 0.0);
+        subcatch_lid_drain_temp_cfs.assign(n, 0.0);
+    }
+
+    bool watershedSized(int n_subcatch) const noexcept {
+        return subarea_temp.size() == static_cast(n_subcatch) *
+                                          static_cast(kNSubArea);
+    }
+
+    void clear() { *this = HeatState{}; }
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_HEAT_DATA_HPP
diff --git a/src/engine/data/HeatOverrideData.hpp b/src/engine/data/HeatOverrideData.hpp
new file mode 100644
index 000000000..9ce184afa
--- /dev/null
+++ b/src/engine/data/HeatOverrideData.hpp
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatOverrideData.hpp
+ * @brief Plan PE — per-element radiative and bed attributes.
+ *
+ * @details Shading, sky view, land-cover emissivity and temperature, burial
+ *          depth, ground temperature, hyporheic velocity and bed material
+ *          are properties of a PLACE. Until PE they were one number for the
+ *          whole model, which collapses exactly the spatial signal a heat
+ *          model exists to produce: a shaded riparian reach and an exposed
+ *          concrete channel shared one shade factor, and a 4 m trunk and a
+ *          0.8 m lateral shared one ground depth.
+ *
+ * @par The element token (D-PE1)
+ *      Flux evaluators take a `HeatElement` — a kind and an index. **ARD
+ *      cells and LARD parcels deliberately do NOT get their own kind**: both
+ *      resolve to their parent LINK. Shading does not vary within one
+ *      conduit in any data a modeller can supply, and a finer table would be
+ *      one nothing can fill. Do not "improve" this into a per-cell table.
+ *
+ * @par Resolution is dense-on-demand (D-PE2)
+ *      Parsing produces sparse rows. `resolveHeatOverrides` runs once at
+ *      open, after every component has applied, and materialises a dense
+ *      vector **only if at least one row targets that family**. The step
+ *      loop then reads `ov.empty() ? global : ov[i]` — one predictable
+ *      branch, no hashing, no search.
+ *
+ *      Two properties follow, and both are the reason for the choice:
+ *      a model with no overrides **allocates nothing and passes the same
+ *      global object it passed before PE**, so byte-identity is structural
+ *      rather than tested; and the per-step cost of this whole feature on
+ *      such a model is one `.empty()` check.
+ *
+ * @par Precedence (D-PE3)
+ *      `GLOBAL` < `TAG` < element. Most specific wins. `TAG` reads SWMM's
+ *      own `[TAGS]` section, already parsed and already round-tripped, so
+ *      fifty shaded conduits are tagged once rather than listed fifty times.
+ *      **This replaces the reference's ` ` element range**, which
+ *      does not map onto a network graph with no linear element ordering.
+ *
+ * @see plans/transport/PER_ELEMENT_HEAT_ATTRIBUTES_PLAN_2026-09-01.md
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_HEAT_OVERRIDE_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_HEAT_OVERRIDE_DATA_HPP
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm {
+
+/// What kind of element a flux is being evaluated for (D-PE1).
+enum class HeatElemKind : std::uint8_t {
+    NODE     = 0,
+    LINK     = 1,
+    SUBCATCH = 2,
+    LID      = 3,
+    /// S4 (D-2DT5): a 2D surface cell. Carries no per-element override
+    /// storage yet (S5 adds the `CELL2D` scope); the accessors' LINK/NODE
+    /// tests fall through to the global, which is the safe answer.
+    CELL2D   = 4
+};
+
+/**
+ * @brief Which element a flux evaluator is being called for.
+ *
+ * @details Default-constructs to an INVALID index deliberately: a binding
+ *          that forgets to pass a real element gets the global config (the
+ *          accessors treat index < 0 as "no override"), which is the safe
+ *          answer, while a gate that pins per-element behaviour still
+ *          catches the omission. The alternative — defaulting to index 0 —
+ *          would silently give every element the FIRST link's attributes.
+ */
+struct HeatElement {
+    HeatElemKind kind  = HeatElemKind::LINK;
+    int          index = -1;
+
+    static HeatElement node(int i) { return {HeatElemKind::NODE, i}; }
+    static HeatElement link(int i) { return {HeatElemKind::LINK, i}; }
+    static HeatElement subcatch(int i) { return {HeatElemKind::SUBCATCH, i}; }
+    static HeatElement cell2d(int i)   { return {HeatElemKind::CELL2D, i}; }
+};
+
+/// Scope of one override row (D-PE3). Ordered by specificity.
+enum class HeatScope : std::uint8_t {
+    GLOBAL = 0,
+    TAG    = 1,
+    NODE   = 2,
+    LINK   = 3
+};
+
+/**
+ * @brief Which attribute an override row sets.
+ *
+ * @details One enum spanning both config structs, so one row type serves
+ *          both and the parser, the resolver and the serializer share a
+ *          single table. `COUNT_` is load-bearing: the attribute-name table
+ *          in `HeatComponent.cpp` static_asserts against it, so adding an
+ *          attribute here without teaching the parser and the writer breaks
+ *          the build rather than silently dropping the new key on save.
+ */
+enum class HeatAttr : int {
+    // RadiativeConfig
+    ALBEDO = 0,
+    SHADE_FACTOR,
+    SKY_VIEW,
+    EMISS_WATER,
+    EMISS_LANDCOVER,
+    LANDCOVER_TEMP,        ///< NEW (PE2) — NaN means "use air temperature"
+    // SedimentConfig
+    SED_THERMAL_DIFFUSIVITY,
+    SED_SOLUTE_DIFFUSIVITY,
+    SED_BED_THICKNESS,
+    SED_GROUND_DEPTH,
+    SED_GROUND_TEMP,
+    SED_HYPORHEIC_VELOCITY,
+    SED_DENSITY,
+    SED_SPECIFIC_HEAT,
+    COUNT_
+};
+
+/// True when the attribute belongs to `SedimentConfig` rather than
+/// `RadiativeConfig`. One predicate, so the two families cannot drift apart
+/// about which struct owns a key.
+inline bool isSedimentAttr(HeatAttr a) noexcept {
+    return static_cast(a) >= static_cast(HeatAttr::SED_THERMAL_DIFFUSIVITY);
+}
+
+/// One parsed override row, kept verbatim so the serializer can render what
+/// the user wrote rather than a resolved expansion of it.
+struct HeatOverrideRow {
+    HeatAttr    attr  = HeatAttr::ALBEDO;
+    HeatScope   scope = HeatScope::GLOBAL;
+    std::string name;    ///< tag or element name; empty at GLOBAL scope
+    double      value = 0.0;
+};
+
+// The dense storage that these rows resolve into lives in HeatData.hpp, as
+// `HeatOverrideData`, because it holds real `RadiativeConfig` /
+// `SedimentConfig` values and those are declared there. Keeping the TOKENS
+// here lets BedExchange.hpp and the flux evaluators take a `HeatElement`
+// without pulling in the whole heat-config header.
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_HEAT_OVERRIDE_DATA_HPP
diff --git a/src/engine/data/HydrologyData.hpp b/src/engine/data/HydrologyData.hpp
index 58db155dd..d091f2140 100644
--- a/src/engine/data/HydrologyData.hpp
+++ b/src/engine/data/HydrologyData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydrologyData.hpp
  * @brief SoA stores for snowpacks, aquifers, LID controls, and LID usage.
@@ -8,7 +24,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_HYDROLOGY_DATA_HPP
@@ -18,6 +34,8 @@
 #include 
 #include 
 
+#include "../core/FilePathPair.hpp"
+
 namespace openswmm {
 
 // ============================================================================
@@ -148,7 +166,10 @@ struct LidUsageStore {
     std::vector      init_sat;         ///< Initial saturation (0–1)
     std::vector      from_imperv;      ///< % of impervious area routed to LID
     std::vector         to_perv;          ///< 1 = route outflow to pervious area
-    std::vector rpt_file;         ///< Report file name (optional)
+    /// Per-unit LID report file (optional). A FilePathPair so the writer can
+    /// re-anchor it against the destination directory on Save-As, like every
+    /// other external-file slot.
+    std::vector rpt_file;
     std::vector drain_to;         ///< Drain-to subcatchment name (optional)
     std::vector      from_perv;        ///< % of pervious area routed to LID
 
diff --git a/src/engine/data/InflowData.hpp b/src/engine/data/InflowData.hpp
index cfda64004..5e097a92e 100644
--- a/src/engine/data/InflowData.hpp
+++ b/src/engine/data/InflowData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InflowData.hpp
  * @brief SoA stores for external inflows, DWF, RDII, and time patterns.
@@ -9,7 +25,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INFLOW_DATA_HPP
diff --git a/src/engine/data/InfraData.hpp b/src/engine/data/InfraData.hpp
index 8fb382a99..913f6ec2f 100644
--- a/src/engine/data/InfraData.hpp
+++ b/src/engine/data/InfraData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InfraData.hpp
  * @brief SoA stores for transects, streets, inlets, and control rules.
@@ -8,7 +24,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INFRA_DATA_HPP
@@ -71,35 +87,145 @@ struct StreetStore {
 // Inlet definitions (from [INLETS] section)
 // ============================================================================
 
+/// Inlet design store. All lengths/velocities are kept in USER (display)
+/// units exactly as read from the .inp (as StreetStore does); the runtime
+/// InletSolver converts to internal units at init.
+///
+/// Column usage by type (2026-09-05 schema, see
+/// plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §2.5):
+///   GRATE / DROP_GRATE : length, width, grate_type, open_area, splash_veloc
+///   SLOTTED            : length, width
+///   CURB / DROP_CURB   : curb_length, curb_height, curb_throat
+///   COMBO              : grate columns + curb columns (legacy two-line form:
+///                        a GRATE line and a CURB line sharing one name are
+///                        merged into a single COMBO row by handle_inlets)
+///   CUSTOM             : curve_id, curve_index, curve_kind
 struct InletStore {
     int count() const { return static_cast(names.size()); }
 
     std::vector names;
-    std::vector inlet_type;   ///< GRATE/CURB/SLOTTED/DROP_GRATE/DROP_CURB/CUSTOM
-    std::vector      length;
-    std::vector      width;        ///< or height for curb
-    std::vector grate_type;   ///< P-50, P-50x100, CURVED_VANE, etc.
-    std::vector      open_area;
-    std::vector      splash_veloc;
+    std::vector inlet_type;   ///< GRATE/CURB/COMBO/SLOTTED/DROP_GRATE/DROP_CURB/CUSTOM
+    std::vector      length;       ///< grate or slotted length
+    std::vector      width;        ///< grate or slotted width
+    std::vector grate_type;   ///< P_BAR-50, P_BAR-50x100, P_BAR-30, CURVED_VANE, TILT_BAR-45, TILT_BAR-30, RETICULINE, GENERIC
+    std::vector      open_area;    ///< GENERIC only: open-area fraction (0,1]
+    std::vector      splash_veloc; ///< GENERIC only: splash-over velocity
+    std::vector      curb_length;  ///< CURB/DROP_CURB/COMBO
+    std::vector      curb_height;  ///< CURB/DROP_CURB/COMBO
+    std::vector         curb_throat;  ///< 0=HORIZONTAL 1=INCLINED 2=VERTICAL (legacy ThroatAngleWords order); default 2
+    std::vector curve_id;     ///< CUSTOM: capture curve name
+    std::vector         curve_index;  ///< CUSTOM: resolved curve index (-1 until PostParseResolver)
+    std::vector         curve_kind;   ///< CUSTOM: 0=unresolved, 1=DIVERSION (captured vs approach flow), 2=RATING (captured vs depth)
+    std::vector comments;     ///< optional description (round-tripped as ';' comment)
+
+    /// Append a fully defaulted row; returns its index.
+    int add_row(const std::string& name, const std::string& type) {
+        names.push_back(name);
+        inlet_type.push_back(type);
+        length.push_back(0.0);
+        width.push_back(0.0);
+        grate_type.push_back("");
+        open_area.push_back(0.0);
+        splash_veloc.push_back(0.0);
+        curb_length.push_back(0.0);
+        curb_height.push_back(0.0);
+        curb_throat.push_back(2);
+        curve_id.push_back("");
+        curve_index.push_back(-1);
+        curve_kind.push_back(0);
+        comments.push_back("");
+        return count() - 1;
+    }
+
+    void erase_row(int idx) {
+        auto u = static_cast(idx);
+        names.erase(names.begin() + static_cast(u));
+        inlet_type.erase(inlet_type.begin() + static_cast(u));
+        length.erase(length.begin() + static_cast(u));
+        width.erase(width.begin() + static_cast(u));
+        grate_type.erase(grate_type.begin() + static_cast(u));
+        open_area.erase(open_area.begin() + static_cast(u));
+        splash_veloc.erase(splash_veloc.begin() + static_cast(u));
+        curb_length.erase(curb_length.begin() + static_cast(u));
+        curb_height.erase(curb_height.begin() + static_cast(u));
+        curb_throat.erase(curb_throat.begin() + static_cast(u));
+        curve_id.erase(curve_id.begin() + static_cast(u));
+        curve_index.erase(curve_index.begin() + static_cast(u));
+        curve_kind.erase(curve_kind.begin() + static_cast(u));
+        comments.erase(comments.begin() + static_cast(u));
+    }
 };
 
 // ============================================================================
 // Inlet usage (from [INLET_USAGE] section)
 // ============================================================================
 
+/// One row per inlet placement. Two host kinds share the store:
+///   * conduit-attribute usage ([INLET_USAGE]): link_index >= 0, node_host == -1
+///   * inlet junction ([INLET_JUNCTIONS]):      link_index == -1, node_host >= 0
+/// flow_limit / local_depress / local_width are kept in USER units (as read);
+/// InletSolver converts at init.
 struct InletUsageStore {
-    int count() const { return static_cast(link_index.size()); }
+    int count() const { return static_cast(design_index.size()); }
 
-    std::vector         link_index;     ///< Conduit link index
+    std::vector         link_index;     ///< Host conduit link index (-1 for an inlet junction)
+    std::vector         node_host;      ///< Host inlet-junction node index (-1 for a conduit usage)
     std::vector         design_index;   ///< Index into InletStore
-    std::vector         node_index;     ///< Receiving node index
+    std::vector         node_index;     ///< Capture (receiving / underdrain) node index
     std::vector         num_inlets;     ///< Number of inlets per side
     std::vector         placement;      ///< 0=auto, 1=on_grade, 2=on_sag
     std::vector      clog_factor;    ///< 1.0 - pctClogged/100
-    std::vector      flow_limit;     ///< Max capture flow (cfs), 0=unlimited
-    std::vector      local_depress;  ///< Local gutter depression (ft)
-    std::vector      local_width;    ///< Local depression width (ft)
-    std::vector         street_index;   ///< Index into StreetStore (-1 if none)
+    std::vector      flow_limit;     ///< Max capture flow per inlet (user flow units), 0=unlimited
+    std::vector      local_depress;  ///< Local gutter depression (user length units)
+    std::vector      local_width;    ///< Local depression width (user length units)
+    std::vector         street_index;   ///< Index into StreetStore, resolved by PostParseResolver (-1 if host xsect is not STREET)
+    /// Design / capture-node names of an [INLET_JUNCTIONS] row, kept until
+    /// PostParseResolver turns them into design_index / node_index. Empty on a
+    /// row whose references were already resolved at parse time.
+    std::vector pending_design_name;
+    std::vector pending_capture_name;
+
+    /// Append a defaulted row; returns its index.
+    int add_row(int link_idx, int node_host_idx, int design_idx, int capture_node_idx) {
+        link_index.push_back(link_idx);
+        node_host.push_back(node_host_idx);
+        design_index.push_back(design_idx);
+        node_index.push_back(capture_node_idx);
+        num_inlets.push_back(1);
+        placement.push_back(0);
+        clog_factor.push_back(1.0);
+        flow_limit.push_back(0.0);
+        local_depress.push_back(0.0);
+        local_width.push_back(0.0);
+        street_index.push_back(-1);
+        pending_design_name.emplace_back();
+        pending_capture_name.emplace_back();
+        return count() - 1;
+    }
+
+    void erase_row(int idx) {
+        auto e = [idx](auto& v) {
+            if (static_cast(idx) < v.size())
+                v.erase(v.begin() + static_cast(idx));
+        };
+        e(link_index); e(node_host); e(design_index); e(node_index); e(num_inlets);
+        e(placement); e(clog_factor); e(flow_limit); e(local_depress); e(local_width);
+        e(street_index); e(pending_design_name); e(pending_capture_name);
+        e(stat_capture_vol); e(stat_bypass_vol); e(stat_backflow_vol); e(stat_peak_flow);
+    }
+
+    /// Row index of the usage hosted by conduit `link_idx`, or -1.
+    int find_by_link(int link_idx) const {
+        for (int i = 0; i < count(); ++i)
+            if (link_index[static_cast(i)] == link_idx) return i;
+        return -1;
+    }
+    /// Row index of the usage hosted by inlet-junction node `node_idx`, or -1.
+    int find_by_node_host(int node_idx) const {
+        for (int i = 0; i < count(); ++i)
+            if (node_host[static_cast(i)] == node_idx) return i;
+        return -1;
+    }
 
     // Stats (populated by InletSolver::gatherStats() before reporting)
     std::vector stat_capture_vol;   ///< Total captured volume (ft³)
diff --git a/src/engine/data/InitialQualityData.hpp b/src/engine/data/InitialQualityData.hpp
new file mode 100644
index 000000000..2c44605d2
--- /dev/null
+++ b/src/engine/data/InitialQualityData.hpp
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file InitialQualityData.hpp
+ * @brief SoA store for [INITIAL_QUALITY] per-element initial concentrations.
+ *
+ * @details Persistent data for .inp round-trip, mirroring ExtInflowData.
+ *          Rows prescribe a per-node/per-link initial value for a pollutant
+ *          or a reserved species (__WATER_AGE__ hours, __TEMPERATURE__ degC),
+ *          overriding the global [POLLUTANTS] Cinit / sidecar INITIAL_STATE
+ *          seeds. Raw names and raw values are retained for writer fidelity;
+ *          unit conversion happens only at the consumption sites.
+ *
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_INITIAL_QUALITY_DATA_HPP
+#define OPENSWMM_ENGINE_INITIAL_QUALITY_DATA_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+// ============================================================================
+// Per-element initial quality (from [INITIAL_QUALITY] section)
+// ============================================================================
+
+struct InitialQualityData {
+    /// Classified constituent kinds (see `kind`).
+    static constexpr int kKindWaterAge    = -1;  ///< __WATER_AGE__ (hours)
+    static constexpr int kKindTemperature = -2;  ///< __TEMPERATURE__ (degC)
+    static constexpr int kKindUnresolved  = -3;  ///< Not yet classified
+    /// U2 (2026-09-07): MSX species m of the reactions component is encoded
+    /// as kind = kKindMsxFirst - m (every value <= kKindMsxFirst). The row
+    /// stays here for the writer ([INITIAL_QUALITY] is the canonical home)
+    /// and is mirrored into ReactionData::init_elem_* for the engines by
+    /// transport::mirrorInitialQualityMsxRows.
+    static constexpr int kKindMsxFirst    = -100;
+    static constexpr int msxKind(int species) noexcept { return kKindMsxFirst - species; }
+    /// Species index for an MSX kind, -1 for any other kind.
+    static constexpr int msxSpecies(int k) noexcept {
+        return (k <= kKindMsxFirst) ? (kKindMsxFirst - k) : -1;
+    }
+
+    int count() const { return static_cast(is_link.size()); }
+
+    std::vector     is_link;      ///< 0 = NODE row, 1 = LINK row
+    std::vector elem_name;    ///< Raw element name (post-parse re-resolution)
+    std::vector         elem_idx;     ///< Resolved node/link index (-1 until resolved)
+    std::vector constituent;  ///< Raw constituent name (writer round-trip)
+    std::vector         kind;         ///< >=0 pollutant idx; kKind* otherwise
+    std::vector      value;        ///< Raw user-units value
+    /// U2: 1 when the row came from the `[INITIAL_QUALITY] FILE `
+    /// sidecar. The writer emits the FILE line and the inline rows only;
+    /// the sidecar is the source of its rows (edit or re-import it).
+    std::vector     from_file;
+
+    /// U2: `[INITIAL_QUALITY] FILE ` as written (relative to the .inp);
+    /// empty when none. Read at open, after the .inp parse.
+    std::string file;
+
+    void add(bool link, const std::string& name, const std::string& cons,
+             double v, int ei = -1, int k = kKindUnresolved, bool fromFile = false) {
+        is_link.push_back(link ? 1 : 0);
+        elem_name.push_back(name);
+        elem_idx.push_back(ei);
+        constituent.push_back(cons);
+        kind.push_back(k);
+        value.push_back(v);
+        from_file.push_back(fromFile ? 1 : 0);
+    }
+
+    /// Remove the entry at @p idx. No-op if out of range. Subsequent entries
+    /// shift down by one — callers that hold cached indices must re-resolve.
+    void erase(int idx) {
+        if (idx < 0 || idx >= count()) return;
+        const auto u = static_cast(idx);
+        is_link.erase(is_link.begin() + u);
+        elem_name.erase(elem_name.begin() + u);
+        elem_idx.erase(elem_idx.begin() + u);
+        constituent.erase(constituent.begin() + u);
+        kind.erase(kind.begin() + u);
+        value.erase(value.begin() + u);
+        if (u < from_file.size()) from_file.erase(from_file.begin() + u);
+    }
+};
+
+} // namespace openswmm
+
+#endif // OPENSWMM_ENGINE_INITIAL_QUALITY_DATA_HPP
diff --git a/src/engine/data/LidLayerSpeciesData.hpp b/src/engine/data/LidLayerSpeciesData.hpp
new file mode 100644
index 000000000..793fd3e88
--- /dev/null
+++ b/src/engine/data/LidLayerSpeciesData.hpp
@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file LidLayerSpeciesData.hpp
+ * @brief Phase A4 — per-(LID unit, layer, species) transported state.
+ *
+ * @details Plan §7 A4 asks for a "generic per-layer species block — heat
+ *          reuses it", so this carries a species stride from the start.
+ *          Water age is species 0; H5's temperature becomes species 1 by
+ *          raising `n_species` and writing its own row, with no second
+ *          array and no change to the layer indexing.
+ *
+ *          LID units live in per-TYPE groups (`LIDManager::group(t)`), not
+ *          one flat list, so `group_offset` maps (type, unit-within-group)
+ *          to the flat unit index this block is keyed on. It is built once
+ *          from the manager and asserted against it on every use.
+ *
+ * @see plans/transport/WATER_AGE_TRACKING_PLAN.md §7 A4
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_LIDLAYERSPECIESDATA_HPP
+#define OPENSWMM_ENGINE_DATA_LIDLAYERSPECIESDATA_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+/// A4: layer index within a LID unit. These are exactly the four
+/// `LIDGroupSoA` fields that carry water state (`surf_depth`, `pave_depth`,
+/// `soil_moist`, `stor_depth`) and exactly the four terms
+/// `LIDSolver::storedVolume()` sums. A drainage mat has thickness and void
+/// but no depth field of its own — the green roof stores its mat water in
+/// `stor_depth` — so it is not a fifth layer here.
+enum class LidLayer : int {
+    SURFACE  = 0,
+    PAVEMENT = 1,
+    SOIL     = 2,
+    STORAGE  = 3,
+    COUNT_   = 4
+};
+
+/// Species rows carried on the LID layers.
+enum class LidSpecies : int {
+    AGE         = 0,
+    /// H5b. A4 reserved the stride for exactly this: one more row, no second
+    /// array, no change to `layer_index`.
+    TEMPERATURE = 1,
+    COUNT_      = 2
+};
+
+/**
+ * @brief Per-(unit, layer, species) state for every LID unit in the model.
+ *
+ * @details Values are whatever the species means — seconds for AGE. The
+ *          update is complete-mix per layer: what is held ages, what
+ *          arrives mixes in by volume, and what leaves does so at the
+ *          layer's own value, which is why only the INFLOW is needed.
+ */
+struct LidLayerSpeciesState {
+    int n_units   = 0;
+    int n_species = 0;
+
+    /// [type] flat index of that group's first unit; size = numGroups() + 1,
+    /// so `group_offset.back() == n_units`.
+    std::vector group_offset;
+
+    /// [(unit * kLayerCount + layer) * n_species + species]
+    std::vector value;
+
+    /// [unit * kLayerCount + layer] — the layer's stored water at the END of
+    /// the previous step, as a depth per unit area (ft), void-weighted the
+    /// way `LIDSolver::storedVolume()` weights it. Kept because the solver
+    /// overwrites its depths in place, so the old volume is otherwise gone
+    /// by the time the age update runs.
+    std::vector vol_prev;
+
+    /// [unit * n_species + species] — what leaves through the underdrain.
+    /// Decision (2026-08-18): the drain draws from the STORAGE layer, so
+    /// this is the storage row for every type that has one.
+    std::vector drain_value;
+
+    /// [unit * n_species + species] — the value of the water arriving at the
+    /// unit from its subcatchment (rainfall, captured subarea runoff, and
+    /// run-on where the LID occupies the whole subcatchment), flow-weighted
+    /// at the point those terms are assembled.
+    std::vector inflow_value;
+
+    static constexpr int kLayerCount = static_cast(LidLayer::COUNT_);
+
+    bool active() const noexcept { return n_units > 0 && n_species > 0; }
+
+    std::size_t layer_index(int unit, LidLayer layer, int species) const noexcept {
+        return (static_cast(unit) * kLayerCount +
+                static_cast(layer)) *
+                   static_cast(n_species) +
+               static_cast(species);
+    }
+
+    /// @note No defaulted arguments, deliberately. A3's round removed a
+    ///       default from `WaterAgeState::resize` because a short call
+    ///       compiled and emptied the new arrays at runtime, where nothing
+    ///       could observe it — every call site was guarded by a size
+    ///       mismatch that repaired itself on the next step. Requiring both
+    ///       counts keeps that failure at the compiler.
+    void resize(int units, int species, const std::vector& offsets) {
+        n_units   = units;
+        n_species = species;
+        group_offset = offsets;
+        const auto n_layers = static_cast(units) *
+                              static_cast(kLayerCount);
+        value.assign(n_layers * static_cast(species), 0.0);
+        vol_prev.assign(n_layers, 0.0);
+        drain_value.assign(static_cast(units) *
+                               static_cast(species), 0.0);
+        inflow_value.assign(static_cast(units) *
+                                static_cast(species), 0.0);
+    }
+
+    /**
+     * @brief Size the block if it is not already the requested shape.
+     *
+     * @details H5b: the block is now shared by TWO capabilities that are
+     *          independently switchable. A4's `initLidLayerAge` both sized
+     *          and seeded, under a `water_age` guard — so a HEAT-only deck
+     *          would never have sized it, and an AGE-only deck would have
+     *          left the temperature row at 0 °C, which D-H5c exists to say
+     *          is a real temperature and not a sentinel.
+     *
+     *          Both initialisers now call this first and seed only their own
+     *          row, so neither depends on the other having run. That is the
+     *          lesson-20 configuration trap, whose eighth instance this
+     *          would otherwise have been.
+     */
+    void ensureSized(int units, int species, const std::vector& offsets) {
+        const auto want = static_cast(units) *
+                          static_cast(kLayerCount) *
+                          static_cast(species);
+        if (n_units == units && n_species == species && value.size() == want)
+            return;
+        resize(units, species, offsets);
+    }
+
+    void clear() { *this = LidLayerSpeciesState{}; }
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_LIDLAYERSPECIESDATA_HPP
diff --git a/src/engine/data/LinkData.hpp b/src/engine/data/LinkData.hpp
index eb27e2f75..619c8136f 100644
--- a/src/engine/data/LinkData.hpp
+++ b/src/engine/data/LinkData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LinkData.hpp
  * @brief Structure-of-Arrays (SoA) storage for all link types.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_LINK_DATA_HPP
@@ -327,6 +343,10 @@ struct LinkData {
      */
     std::vector     flow;
 
+    /// Kinematic-wave accepted upstream flow, all barrels (cfs). Published
+    /// by each hydraulic solve before transport; not persisted in hotstarts.
+    std::vector     kw_inflow;
+
     /**
      * @brief Current water depth at midpoint (project length units).
      * @see Legacy: Link[i].newDepth
@@ -339,6 +359,29 @@ struct LinkData {
      */
     std::vector     volume;
 
+    /**
+     * @brief Portion of `volume` held in the Preissmann slot (ft³).
+     * @details FV routing only — `Σ max(0, cell_a − a_crown)·dx` per conduit
+     *          (Router::publishFv). Always a subset of `volume`; stays 0.0
+     *          under the dynamic-wave router and below the pipe crown. No
+     *          legacy counterpart: legacy never separates slot storage.
+     */
+    std::vector     slot_volume;
+
+    // Slot-storage share statistics (FV slot program R0). All stay 0.0
+    // under the dynamic-wave router. The share of a link at an instant is
+    // slot_volume/volume; the run-level share is the ratio of the two
+    // time integrals below, never an average of instantaneous ratios.
+
+    /** @brief ∫ slot_volume dt over the run (ft³·s). */
+    std::vector     stat_slot_vol_dt;
+    /** @brief ∫ volume dt over the run (ft³·s) — the share denominator. */
+    std::vector     stat_vol_dt;
+    /** @brief Peak instantaneous slot share (slot_volume/volume, 0..1). */
+    std::vector     stat_peak_slot_share;
+    /** @brief Time (s) the instantaneous slot share exceeded 1 %. */
+    std::vector     stat_time_slot_above;
+
     /**
      * @brief Current froude number (absolute).
      * @see Legacy: Link[i].froude
@@ -577,8 +620,14 @@ struct LinkData {
         pump_curve_name.resize(un);
 
         flow.assign(un, 0.0);
+        kw_inflow.assign(un, 0.0);
         depth.assign(un, 0.0);
         volume.assign(un, 0.0);
+        slot_volume.assign(un, 0.0);
+        stat_slot_vol_dt.assign(un, 0.0);
+        stat_vol_dt.assign(un, 0.0);
+        stat_peak_slot_share.assign(un, 0.0);
+        stat_time_slot_above.assign(un, 0.0);
         froude.assign(un, 0.0);
         flow_class.assign(un, FlowClass::DRY);
         is_closed.assign(un, 0);
@@ -635,7 +684,10 @@ struct LinkData {
         g(direction, 1);
         g(has_flap_gate, uint8_t{0}); g(dqdh, 0.0);
         pump_curve_name.resize(un);
-        g(flow, 0.0); g(depth, 0.0); g(volume, 0.0);
+        g(flow, 0.0); g(depth, 0.0); g(volume, 0.0); g(slot_volume, 0.0);
+        g(kw_inflow, 0.0);
+        g(stat_slot_vol_dt, 0.0); g(stat_vol_dt, 0.0);
+        g(stat_peak_slot_share, 0.0); g(stat_time_slot_above, 0.0);
         g(froude, 0.0); g(flow_class, FlowClass::DRY); g(is_closed, uint8_t{0});
         g(old_flow, 0.0); g(old_depth, 0.0); g(old_volume, 0.0);
         comments.resize(un, std::string{});
@@ -659,6 +711,49 @@ struct LinkData {
         // Note: stat_total_load handled by resize_loads()
     }
 
+    /**
+     * @brief Reserve capacity for `n` links without changing count().
+     *
+     * @details Parsing grows these arrays one row at a time via grow_to(),
+     *          so each of the ~65 parallel vectors reallocates and copies
+     *          O(log n) times over a section — the dominant memory traffic in
+     *          handler dispatch on a large model.
+     *
+     *          This reserves capacity only. It deliberately does NOT resize:
+     *          count() is the vector size, and PostParseResolver compares it
+     *          against the final name count and calls resize() when they
+     *          differ — a call with destructive assign semantics. Growing the
+     *          SIZE speculatively here would trip that path and wipe parsed
+     *          data. Capacity is invisible to all of it.
+     *
+     *          Over-reserving is harmless, so callers pass the section's row
+     *          count as an upper bound.
+     */
+    void reserve_to(int n) {
+        if (n <= 0) return;
+        const auto un = static_cast(n);
+        if (type.capacity() >= un) return;
+        auto r = [&](auto& vec) { vec.reserve(un); };
+        r(type); r(node1); r(node2); r(offset1);
+        r(offset2); r(q0); r(q_limit); r(xsect_shape);
+        r(xsect_y_full); r(xsect_a_full); r(xsect_w_max); r(xsect_geom1);
+        r(xsect_geom2); r(xsect_geom3); r(xsect_geom4); r(xsect_curve);
+        r(xsect_r_full); r(xsect_s_full); r(xsect_s_max); r(xsect_y_bot);
+        r(xsect_a_bot); r(xsect_s_bot); r(xsect_r_bot); r(xsect_yw_max);
+        r(xsect_batch_shape); r(setting); r(target_setting); r(time_last_set);
+        r(direction); r(has_flap_gate); r(dqdh); r(flow);
+        r(kw_inflow);
+        r(depth); r(volume); r(froude); r(flow_class);
+        r(is_closed); r(old_flow); r(old_depth); r(old_volume);
+        r(rpt_flag); r(stat_vol_flow); r(stat_max_flow); r(stat_max_veloc);
+        r(stat_max_filling); r(stat_time_surcharged); r(stat_max_flow_date); r(stat_time_full_upstream);
+        r(stat_time_full_dnstream); r(stat_time_full_both); r(stat_time_capacity_limited); r(stat_pump_cycles);
+        r(stat_pump_on_time); r(stat_pump_volume); r(stat_pump_energy); r(stat_pump_was_on);
+        r(stat_flow_turns); r(stat_flow_turn_sign); r(stat_time_courant_critical); r(stat_norm_ltd);
+        r(stat_inlet_ctrl); r(pump_curve_name); r(comments); r(tags);
+        r(stat_flow_class);
+    }
+
     /**
      * @brief Erase the link at index `idx` from every parallel array.
      *
@@ -683,6 +778,7 @@ struct LinkData {
         e(has_flap_gate); e(dqdh);
 
         e(flow); e(depth); e(volume); e(froude); e(flow_class); e(is_closed);
+        e(kw_inflow);
         e(old_flow); e(old_depth); e(old_volume);
         e(comments); e(tags); e(rpt_flag);
 
@@ -786,6 +882,7 @@ struct LinkData {
         pump_curve_name.shrink_to_fit();
 
         flow.shrink_to_fit();
+        kw_inflow.shrink_to_fit();
         depth.shrink_to_fit();
         volume.shrink_to_fit();
         froude.shrink_to_fit();
@@ -824,14 +921,26 @@ struct LinkData {
     }
 
     void save_state() noexcept {
+        save_hyd_state();
+        save_qual_state();
+    }
+
+    /// Legacy link_setOldHydState — rolled by routeFlow only (not on a
+    /// SKIP_STEADY_STATE step).
+    void save_hyd_state() noexcept {
         std::copy(flow.begin(),   flow.end(),   old_flow.begin());
         std::copy(depth.begin(),  depth.end(),  old_depth.begin());
         std::copy(volume.begin(), volume.end(), old_volume.begin());
+    }
+
+    /// Legacy link_setOldQualState — every routing step.
+    void save_qual_state() noexcept {
         std::copy(conc.begin(),   conc.end(),   conc_old.begin());
     }
 
     void reset_state() noexcept {
         std::fill(flow.begin(),  flow.end(),  0.0);
+        std::fill(kw_inflow.begin(), kw_inflow.end(), 0.0);
         std::fill(depth.begin(), depth.end(), 0.0);
         std::fill(volume.begin(), volume.end(), 0.0);
         std::fill(froude.begin(), froude.end(), 0.0);
diff --git a/src/engine/data/LinkSubtypes.hpp b/src/engine/data/LinkSubtypes.hpp
index afa68f54b..1d0df08d0 100644
--- a/src/engine/data/LinkSubtypes.hpp
+++ b/src/engine/data/LinkSubtypes.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LinkSubtypes.hpp
  * @brief Relational (normalized) Structure-of-Arrays side-tables for link subtypes.
@@ -33,7 +49,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_LINK_SUBTYPES_HPP
@@ -64,7 +80,13 @@ struct ConduitData {
     std::vector    link_idx;       ///< Base LinkData index (join key)
 
     std::vector roughness;
-    std::vector length;
+    std::vector length;       ///< Authored [CONDUITS] length (ft)
+    /// The length the routing uses — legacy conduit_getLength. Equal to
+    /// `length` for every section but IRREGULAR, where the authored value
+    /// is the main channel's and the routing length is the flood plain's,
+    /// `length / Transect.lengthFactor`. Derived; refreshed by
+    /// routing::applyConduitLengthening, never serialized.
+    std::vector true_length;
     std::vector slope;
     std::vector mod_length;
     std::vector    barrels;
@@ -85,25 +107,43 @@ struct ConduitData {
     std::vector inlet_control;       ///< per-step culvert inlet-control flag
     std::vector  full_state;          ///< per-step up/down full bitmask
 
+    // G-X4 (2026-09-20): the two-zone aquifer's frozen coupling for this
+    // routing step, published by SurfaceRouter2D before routing and read by
+    // the two loss laws (DynamicWave and routing::computeConduitLosses).
+    // `gw_coupled == 0` on every conduit of every deck without a
+    // `[2D_AQUIFER]` + `LINK_SEEPAGE TWO_WAY`, and the laws then take their
+    // legacy branch unchanged.
+    std::vector gw_coupled;   ///< 1 = signed conductance law applies
+    std::vector  gw_head_rel;  ///< water-table elevation MINUS the conduit's mid invert (project length)
+    std::vector  gw_kc;        ///< bed conductivity (project rate units); seeded from seep_rate
+    std::vector  gw_dc;        ///< bed thickness / characteristic path (project length); seeded from the full depth
+    std::vector  gw_gain_max;  ///< cap on the gaining direction, ONE barrel (project flow units)
+
     int count() const noexcept { return static_cast(link_idx.size()); }
 
     void clear() noexcept {
-        link_idx.clear(); roughness.clear(); length.clear(); slope.clear();
+        link_idx.clear(); roughness.clear(); length.clear();
+        true_length.clear(); slope.clear();
         mod_length.clear(); barrels.clear(); beta.clear(); rough_factor.clear();
         q_full.clear(); q_max.clear(); loss_inlet.clear(); loss_outlet.clear();
         loss_avg.clear(); seep_rate.clear(); culvert_code.clear();
         evap_loss_rate.clear(); seep_loss_rate.clear(); normal_flow_limited.clear();
         inlet_control.clear(); full_state.clear();
+        gw_coupled.clear(); gw_head_rel.clear(); gw_kc.clear();   // G-X4
+        gw_dc.clear(); gw_gain_max.clear();
     }
 
     void reserve(int n) {
         const auto un = static_cast(n);
-        link_idx.reserve(un); roughness.reserve(un); length.reserve(un); slope.reserve(un);
+        link_idx.reserve(un); roughness.reserve(un); length.reserve(un);
+        true_length.reserve(un); slope.reserve(un);
         mod_length.reserve(un); barrels.reserve(un); beta.reserve(un); rough_factor.reserve(un);
         q_full.reserve(un); q_max.reserve(un); loss_inlet.reserve(un); loss_outlet.reserve(un);
         loss_avg.reserve(un); seep_rate.reserve(un); culvert_code.reserve(un);
         evap_loss_rate.reserve(un); seep_loss_rate.reserve(un); normal_flow_limited.reserve(un);
         inlet_control.reserve(un); full_state.reserve(un);
+        gw_coupled.reserve(un); gw_head_rel.reserve(un); gw_kc.reserve(un);   // G-X4
+        gw_dc.reserve(un); gw_gain_max.reserve(un);
     }
 
     /// Insert a default conduit row for base link @p i, keeping link_idx
@@ -114,6 +154,7 @@ struct ConduitData {
         link_idx.insert(link_idx.begin() + p, i);
         roughness.insert(roughness.begin() + p, 0.01);
         length.insert(length.begin() + p, 0.0);
+        true_length.insert(true_length.begin() + p, 0.0);
         slope.insert(slope.begin() + p, 0.0);
         mod_length.insert(mod_length.begin() + p, 0.0);
         barrels.insert(barrels.begin() + p, 1);
@@ -131,6 +172,11 @@ struct ConduitData {
         normal_flow_limited.insert(normal_flow_limited.begin() + p, uint8_t{0});
         inlet_control.insert(inlet_control.begin() + p, uint8_t{0});
         full_state.insert(full_state.begin() + p, int8_t{0});
+        gw_coupled.insert(gw_coupled.begin() + p, uint8_t{0});      // G-X4
+        gw_head_rel.insert(gw_head_rel.begin() + p, 0.0);
+        gw_kc.insert(gw_kc.begin() + p, 0.0);
+        gw_dc.insert(gw_dc.begin() + p, 0.0);
+        gw_gain_max.insert(gw_gain_max.begin() + p, 0.0);
         return static_cast(p);
     }
 
@@ -139,6 +185,7 @@ struct ConduitData {
         link_idx.erase(link_idx.begin() + p);
         roughness.erase(roughness.begin() + p);
         length.erase(length.begin() + p);
+        true_length.erase(true_length.begin() + p);
         slope.erase(slope.begin() + p);
         mod_length.erase(mod_length.begin() + p);
         barrels.erase(barrels.begin() + p);
@@ -215,7 +262,10 @@ struct OrificeData {
     std::vector    link_idx;
     std::vector orifice_type;    ///< 0 = BOTTOM, 1 = SIDE (legacy param1)
     std::vector cd;              ///< Discharge coefficient
-    std::vector orate;           ///< Open/close time (s)
+    std::vector orate;           ///< Open/close time in HOURS, as parsed
+                                         ///< from [ORIFICES]; x3600 at use
+                                         ///< (SWMMEngine.cpp:2927), matching
+                                         ///< legacy link.c:372.
 
     int count() const noexcept { return static_cast(link_idx.size()); }
 
@@ -250,12 +300,15 @@ struct OrificeData {
 
 struct WeirData {
     std::vector    link_idx;
-    std::vector weir_type;       ///< TRANSVERSE/SIDEFLOW/V-NOTCH/TRAPEZOIDAL (legacy param1)
+    std::vector weir_type;       ///< TRANSVERSE/SIDEFLOW/V-NOTCH/TRAPEZOIDAL/ROADWAY = 0..4 (legacy param1)
     std::vector cd;              ///< Discharge coefficient
     std::vector end_contractions;///< End contractions (legacy param2)
     std::vector crest_height;
     std::vector cd2;             ///< End-section discharge coeff (legacy cDisch2)
     std::vector can_surcharge;  ///< Surcharge YES/NO (legacy Weir.canSurcharge, default YES)
+    std::vector road_width;      ///< ROADWAY weir: road width across the flow (legacy Weir.roadWidth; authored length units until the resolver, then ft)
+    std::vector road_surface;    ///< ROADWAY weir: 0 none, 1 PAVED, 2 GRAVEL (legacy Weir.roadSurface)
+    std::vector    cd_curve;        ///< Discharge-coefficient curve index in ctx.tables, -1 none (legacy Weir.cdCurve)
 
     int count() const noexcept { return static_cast(link_idx.size()); }
 
@@ -263,12 +316,14 @@ struct WeirData {
         link_idx.clear(); weir_type.clear(); cd.clear();
         end_contractions.clear(); crest_height.clear();
         cd2.clear(); can_surcharge.clear();
+        road_width.clear(); road_surface.clear(); cd_curve.clear();
     }
     void reserve(int n) {
         const auto un = static_cast(n);
         link_idx.reserve(un); weir_type.reserve(un); cd.reserve(un);
         end_contractions.reserve(un); crest_height.reserve(un);
         cd2.reserve(un); can_surcharge.reserve(un);
+        road_width.reserve(un); road_surface.reserve(un); cd_curve.reserve(un);
     }
     int add_default(int i) {
         const auto p = static_cast(
@@ -280,6 +335,9 @@ struct WeirData {
         crest_height.insert(crest_height.begin() + p, 0.0);
         cd2.insert(cd2.begin() + p, 0.0);
         can_surcharge.insert(can_surcharge.begin() + p, uint8_t{1});
+        road_width.insert(road_width.begin() + p, 0.0);
+        road_surface.insert(road_surface.begin() + p, int8_t{0});
+        cd_curve.insert(cd_curve.begin() + p, -1);
         return static_cast(p);
     }
     void erase_at(int r) {
@@ -291,6 +349,9 @@ struct WeirData {
         crest_height.erase(crest_height.begin() + p);
         cd2.erase(cd2.begin() + p);
         can_surcharge.erase(can_surcharge.begin() + p);
+        road_width.erase(road_width.begin() + p);
+        road_surface.erase(road_surface.begin() + p);
+        cd_curve.erase(cd_curve.begin() + p);
     }
 };
 
diff --git a/src/engine/data/MsxSurfaceData.hpp b/src/engine/data/MsxSurfaceData.hpp
new file mode 100644
index 000000000..c16d5db71
--- /dev/null
+++ b/src/engine/data/MsxSurfaceData.hpp
@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxSurfaceData.hpp
+ * @brief BW-MSX (2026-09-19) — surface buildup / washoff / sweeping state and
+ *        parameters for the reactions component's (MSX) species.
+ *
+ * @details `[BUILDUP]`, `[WASHOFF]` and `[LOADINGS]` are pollutant-keyed
+ *          everywhere (`BuildupData`, `WashoffData`, `SurfaceQualitySoA`,
+ *          `subcatches.conc`). MSX species are declared by the reactions
+ *          component, which is applied only after the `.inp` has been read,
+ *          so a row naming one cannot be resolved by the section handler.
+ *          The handlers therefore park such rows here BY NAME
+ *          (`MsxSurfaceRows`) and `msxsurf::resolve()` binds them after the
+ *          component is in (PostParseResolver time), exactly the deferred
+ *          pattern `[INITIAL_QUALITY]` and `[INFLOWS]` use for MSX species.
+ *
+ *          The resolved parameters and the per-(subcatchment × land use ×
+ *          species) buildup state live in this struct, separate from the
+ *          pollutant arrays so the pollutant path is untouched (bit-identity
+ *          for decks without MSX rows). The arithmetic that advances them is
+ *          the subcatchment surface-quality step's, transcribed once in
+ *          `quality/MsxSurfaceQuality.cpp`.
+ *
+ *          Design: `plans/transport/OVERLAND_TRANSPORT_HEAT_MSX_PLAN_2026-09-01.md`
+ *          §8.9; program plan decisions D-A24, D-A27–D-A29.
+ *
+ * @ingroup engine_data
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_MSX_SURFACE_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_MSX_SURFACE_DATA_HPP
+
+#include 
+#include 
+#include 
+
+namespace openswmm {
+
+/// Rows parked by the section handlers for names that are not pollutants.
+struct MsxSurfaceRows {
+    struct Buildup {
+        std::string landuse, species;
+        int    func_type = 0;      ///< 0=NONE,1=POW,2=EXP,3=SAT,4=EXT
+        double c1 = 0.0, c2 = 0.0, c3 = 0.0;
+        std::string ts_name;       ///< EXT: time series name (resolved later)
+        int    normalizer = 0;     ///< 0=PER_AREA, 1=PER_CURB
+    };
+    struct Washoff {
+        std::string landuse, species;
+        int    func_type = 0;      ///< 0=NONE,1=EXP,2=RC,3=EMC
+        double coeff = 0.0, expon = 0.0, sweep_effic = 0.0, bmp_effic = 0.0;
+    };
+    struct Loading {
+        std::string subcatch, species;
+        double value = 0.0;        ///< initial buildup, mass per unit area
+    };
+    std::vector buildup;
+    std::vector washoff;
+    std::vector loadings;
+    bool empty() const noexcept {
+        return buildup.empty() && washoff.empty() && loadings.empty();
+    }
+};
+
+/**
+ * @brief Resolved MSX surface-quality parameters and state.
+ *
+ * Index conventions (nlu = land uses, nm = MSX species, nsc = subcatchments):
+ *  - parameters: `[lu * nm + m]`
+ *  - buildup state: `bu_idx(sc, lu, m) = (sc * nlu + lu) * nm + m`
+ *    (mass per normalizer unit — user mass per acre/ha or per curb unit —
+ *    the `SurfaceQualitySoA` convention)
+ *  - per-(sc, m) washoff concentration: `[sc * nm + m]` (concentration units)
+ *  - ledgers per species `[m]` in USER MASS (lbs / kg), the `mass_balance.qual_*`
+ *    convention.
+ */
+struct MsxSurfaceData {
+    MsxSurfaceRows rows;                 ///< parse-time, by name
+
+    int n_landuses = 0;
+    int n_species  = 0;                  ///< MSX species count at resolve time
+    int n_subcatch = 0;
+
+    // ---- parameters [lu * n_species + m] --------------------------------
+    std::vector    bu_type;         ///< 0=NONE,1=POW,2=EXP,3=SAT,4=EXT
+    std::vector bu_c1, bu_c2, bu_c3;   ///< EXT: c3 = time-series index
+    std::vector    bu_normalizer;   ///< 0=PER_AREA, 1=PER_CURB
+    std::vector bu_max_days;     ///< derived (99.9 % of max)
+    std::vector    wo_type;         ///< 0=NONE,1=EXP,2=RC,3=EMC
+    std::vector wo_coeff, wo_expon, wo_sweep_effic, wo_bmp_effic;
+
+    // ---- initial loading [sc * n_species + m] (mass per unit area) ------
+    std::vector init_loading;
+
+    // ---- per-species unit factor: concentration-mass → user mass --------
+    std::vector mcf;             ///< D-A27: MG → UCF(MASS), UG → /1000, else 1
+
+    // ---- state ----------------------------------------------------------
+    std::vector buildup;         ///< bu_idx(sc, lu, m), per normalizer unit
+    std::vector washoff_conc;    ///< [sc * n_species + m], conc units (mg/L-like)
+    /// Previous runoff step's `washoff_conc`, the "old" end of the routing-step
+    /// interpolation the delivery seam does. The pollutant mirror of this is
+    /// `SubcatchData::conc_old`, rolled by `SubcatchData::save_state()`; this
+    /// one is rolled beside it, on the same runoff cadence.
+    std::vector washoff_conc_old;
+
+    // ---- ledgers per species [m], user mass ---------------------------
+    std::vector led_init_buildup;
+    std::vector led_buildup;     ///< net accrual over the run
+    std::vector led_runoff_load; ///< delivered to the network
+    std::vector led_sweeping;
+    std::vector led_bmp_removal;
+    std::vector led_subcatch_load; ///< [sc * n_species + m], per-subcatchment total (report)
+
+    bool resolved = false;
+    bool active() const noexcept { return resolved && n_species > 0 && n_landuses > 0; }
+
+    std::size_t pidx(int lu, int m) const noexcept {
+        return static_cast(lu) * static_cast(n_species) +
+               static_cast(m);
+    }
+    std::size_t bu_idx(int sc, int lu, int m) const noexcept {
+        return (static_cast(sc) * static_cast(n_landuses) +
+                static_cast(lu)) * static_cast(n_species) +
+               static_cast(m);
+    }
+    std::size_t sidx(int sc, int m) const noexcept {
+        return static_cast(sc) * static_cast(n_species) +
+               static_cast(m);
+    }
+
+    void resize_params(int nlu, int nm) {
+        n_landuses = nlu; n_species = nm;
+        const auto n = static_cast(nlu) * static_cast(nm);
+        bu_type.assign(n, 0); bu_c1.assign(n, 0.0); bu_c2.assign(n, 0.0); bu_c3.assign(n, 0.0);
+        bu_normalizer.assign(n, 0); bu_max_days.assign(n, 0.0);
+        wo_type.assign(n, 0); wo_coeff.assign(n, 0.0); wo_expon.assign(n, 0.0);
+        wo_sweep_effic.assign(n, 0.0); wo_bmp_effic.assign(n, 0.0);
+        mcf.assign(static_cast(nm), 1.0);
+    }
+    void resize_state(int nsc) {
+        n_subcatch = nsc;
+        const auto nm = static_cast(n_species);
+        buildup.assign(static_cast(nsc) * static_cast(n_landuses) * nm, 0.0);
+        washoff_conc.assign(static_cast(nsc) * nm, 0.0);
+        washoff_conc_old.assign(static_cast(nsc) * nm, 0.0);
+        if (init_loading.size() != static_cast(nsc) * nm)
+            init_loading.assign(static_cast(nsc) * nm, 0.0);
+        led_init_buildup.assign(nm, 0.0); led_buildup.assign(nm, 0.0);
+        led_runoff_load.assign(nm, 0.0);  led_sweeping.assign(nm, 0.0);
+        led_bmp_removal.assign(nm, 0.0);
+        led_subcatch_load.assign(static_cast(nsc) * nm, 0.0);
+    }
+};
+
+} // namespace openswmm
+
+#endif // OPENSWMM_ENGINE_DATA_MSX_SURFACE_DATA_HPP
diff --git a/src/engine/data/NameIndex.hpp b/src/engine/data/NameIndex.hpp
index d6baeddd8..a7fde8e8f 100644
--- a/src/engine/data/NameIndex.hpp
+++ b/src/engine/data/NameIndex.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NameIndex.hpp
  * @brief O(1) name-to-index lookup for SWMM objects.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_NAME_INDEX_HPP
@@ -204,14 +220,38 @@ class NameIndex {
      *          The map is rebuilt from scratch — O(n) — which is acceptable
      *          since this is only called in BUILDING or OPENED state.
      *          No-op if idx is out of range.
+     *
+     *          Inside a begin_bulk_remove()/end_bulk_remove() scope only the
+     *          vector entry is erased (index→name stays exact) and the ONE
+     *          rebuild happens at scope end — deleting K objects then costs
+     *          one rehash instead of K.  That per-delete rehash was the
+     *          dominant bulk-delete cost on large models
+     *          (BULK_DELETE_AND_WINDOWS_OPEN_PERF_PLAN_2026-09-01 Phase A1).
      */
     void remove_at(int idx) noexcept {
         if (idx < 0 || idx >= static_cast(names_.size())) return;
         names_.erase(names_.begin() + idx);
-        map_.clear();
-        map_.reserve(names_.size());
-        for (int i = 0; i < static_cast(names_.size()); ++i)
-            map_[names_[i]] = i;
+        if (bulk_depth_ > 0) return;   // map rebuilt once in end_bulk_remove()
+        rebuild_map_();
+    }
+
+    /**
+     * @brief Defer map rebuilds across a batch of remove_at() calls.
+     *
+     * @details Between begin and end the name→index MAP is stale: find(),
+     *          try_find(), canonical() and rename() must not be used (the
+     *          index→name direction — name_of()/names()/size() — stays
+     *          exact throughout).  Nestable; the outermost end rebuilds.
+     *          ObjectDeleter's delete_*_many are the intended callers and
+     *          are audited to perform no map lookups while deferred.
+     */
+    void begin_bulk_remove() noexcept { ++bulk_depth_; }
+
+    /** @brief Close a begin_bulk_remove() scope; outermost close rebuilds
+     *         the map once.  Unbalanced calls are ignored. */
+    void end_bulk_remove() {
+        if (bulk_depth_ == 0 || --bulk_depth_ > 0) return;
+        rebuild_map_();
     }
 
     // -----------------------------------------------------------------------
@@ -222,9 +262,17 @@ class NameIndex {
     const std::vector& names() const noexcept { return names_; }
 
 private:
+    void rebuild_map_() {
+        map_.clear();
+        map_.reserve(names_.size());
+        for (int i = 0; i < static_cast(names_.size()); ++i)
+            map_[names_[static_cast(i)]] = i;
+    }
+
     /// name → index; case-insensitive (legacy hash.c parity), original-case keys
     std::unordered_map map_;
     std::vector names_;  ///< index → name (original spelling)
+    int bulk_depth_ = 0;              ///< begin/end_bulk_remove() nesting
 };
 
 } /* namespace openswmm */
diff --git a/src/engine/data/NodeData.hpp b/src/engine/data/NodeData.hpp
index ae3980099..e13cd5a11 100644
--- a/src/engine/data/NodeData.hpp
+++ b/src/engine/data/NodeData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NodeData.hpp
  * @brief Structure-of-Arrays (SoA) storage for all node types.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_NODE_DATA_HPP
@@ -161,6 +177,34 @@ struct NodeData {
      */
     std::vector    is_virtual;
 
+    /**
+     * @brief Inlet-junction flag (0 = plain node, 1 = inlet junction).
+     *
+     * @details An inlet junction is a virtual junction (`is_virtual` is always
+     *          set alongside this flag) that additionally carries a street
+     *          inlet: it sits between two STREET conduits and diverts captured
+     *          gutter flow to a separate capture node through the usage row
+     *          `InletUsageStore::find_by_node_host(idx)` (INP section
+     *          [INLET_JUNCTIONS]). Refactored engine only.
+     */
+    std::vector    is_inlet;
+
+    /**
+     * @brief Rendering-only rim (ground) depth above the invert, project
+     *        length units. 0 = unset.
+     *
+     * @details Optional third token of a [VIRTUAL_JUNCTIONS] row. A virtual
+     *          junction's `full_depth` is derived — it is always the shared
+     *          pipe crown — which makes every ground/terrain line a viewer
+     *          draws collapse to the crown at the break point. This field
+     *          carries the surface elevation for those drawings and nothing
+     *          else: it is written by the input and edit paths and read only
+     *          by renderers. No hydraulics, routing, reporting or output-file
+     *          code may read it, so a model produces bit-identical results
+     *          whether or not it is supplied.
+     */
+    std::vector     rim_depth;
+
     // -----------------------------------------------------------------------
     // Node subtype properties (storage / outfall / divider)
     // -----------------------------------------------------------------------
@@ -270,6 +314,12 @@ struct NodeData {
      *          In-memory only (not serialized to hotstart). See plan / review §11.
      */
     std::vector     coupling_volume;
+    /// G-X2 (2026-09-19): 1 when the node has a two-zone aquifer bed under
+    /// it (a `[2D_AQUIFER_NODE]` row or auto-enrolment). A storage node so
+    /// flagged exchanges through the conductance channel and its own
+    /// exfiltration is skipped (one owner). Empty until the 2D router
+    /// resolved an aquifer.
+    std::vector    aquifer2d_bed;
 
     /**
      * @brief Delivery queue for the 1D↔2D junction exchange (1D units, ft³).
@@ -289,6 +339,42 @@ struct NodeData {
      */
     std::vector     coupling_queue;
 
+    /**
+     * @brief S3 — species MASS queue for the 2D→1D junction drain, per
+     *        (node, pollutant), 1D mass units (conc × ft³).
+     * @details Filled by SurfaceRouter2D from the marcher's per-point
+     *          `exch_mass` (2D→1D drains only, at the CELL's concentration);
+     *          drained by assembleLateralInflows with the SAME rule as
+     *          `coupling_queue` (uniform rate over the remaining delivery span,
+     *          flushed when remaining ≤ dt) so mass and water arrive in the
+     *          same proportions. Flat 2D `[node * n_pollutants + pollutant]`.
+     *          Never negative: a 1D→2D spill removes mass from the node
+     *          IMPLICITLY through the reduced mixing volume (the CSTR takes
+     *          every outflow at the mixed concentration), so no debit is
+     *          queued for it. In-memory only.
+     */
+    std::vector     coupling_qual_queue;
+    /** @brief S3 — this step's delivered 2D→1D species mass RATE per
+     *  (node, pollutant) (mass/sec); read by QualitySolver::addCouplingLoads(). */
+    std::vector     coupling_qual_inflow;
+
+    /**
+     * @brief S4 — the tuple's age-volume and temperature-volume halves,
+     *        per node (age·ft³ / °C·ft³ queued; age·ft³/s / °C·ft³/s
+     *        delivered). Same queue/drain rule as `coupling_qual_queue`;
+     *        consumed by addCouplingLoads into `node_age_vol_in` /
+     *        `node_temp_vol_in` when the 2D surface carries the row
+     *        (`coupling_tuple_age` / `coupling_tuple_temp`), which replaces
+     *        the EXTERNAL_INFLOW stand-in S3 used. Sized with the node
+     *        count (cheap); untouched on decks without a 2D surface.
+     */
+    std::vector     coupling_age_vol_queue;
+    std::vector     coupling_temp_vol_queue;
+    std::vector     coupling_age_vol_inflow;
+    std::vector     coupling_temp_vol_inflow;
+    bool coupling_tuple_age  = false;  ///< set by SurfaceRouter2D at initialize
+    bool coupling_tuple_temp = false;
+
     // -----------------------------------------------------------------------
     // Quality mass inflow assembly arrays
     // assembleQualityInflows() writes these; mixAtNodes() reads them.
@@ -311,6 +397,31 @@ struct NodeData {
      */
     std::vector     iface_qual_mass;
 
+    /**
+     * @brief Direct external inflow quality mass rate per (node, pollutant)
+     *        (mass/sec).
+     * @details Written by inflow::InflowSolver::evaluate() each routing step
+     *          from the `[INFLOWS]` CONCEN/MASS rows (cleared in
+     *          clearInflowSources()); read by
+     *          QualitySolver::addExtInflowLoads() → added to qual_mass_in.
+     *          Flat 2D: [node * n_pollutants + pollutant]. CONCEN rows are
+     *          already multiplied by the node's external flow inflow, so this
+     *          is a mass rate for either row type.
+     * @see Legacy: routing.c addExternalInflows() pollutant portion
+     */
+    std::vector     ext_qual_mass;
+
+    /**
+     * @brief Per-node DWF pollutant mass-rate ADJUSTMENT (mass/sec), net of
+     *        the global default: row mass (q·pattern-adjusted value) minus
+     *        q·Pollut.dwfConcen when the global default is set. Adding it on
+     *        top of the global-default DWF load reproduces legacy
+     *        addDryWeatherInflows' add-row-then-subtract-default exactly.
+     *        Flat 2D: [node * n_pollutants + pollutant].
+     * @see Legacy: routing.c addDryWeatherInflows() pollutant portion
+     */
+    std::vector     dwf_qual_mass;
+
     /**
      * @brief LID drain quality mass rate per (node, pollutant) (mass/sec).
      * @details Set once per runoff step (cleared at runoff step start); read
@@ -329,6 +440,27 @@ struct NodeData {
      * @see Legacy: lid.c lid_addDrainInflow() Node[k].newLatFlow contribution
      */
     std::vector     lid_drain_qual_vol;
+    /// Previous runoff step's lid_drain_qual_load, for legacy
+    /// lid_addDrainInflow's routing-step interpolation:
+    ///   w = (1-f)*oldDrainFlow*oldQual + f*newDrainFlow*newQual
+    /// (lid.c). Rolled from the current arrays at the top of each runoff
+    /// step, before A6b refills them.
+    std::vector     lid_drain_qual_load_old;
+    /// Previous runoff step's lid_drain_qual_vol (the q half of the pair).
+    std::vector     lid_drain_qual_vol_old;
+    /**
+     * @brief LID drain WATER inflow rate per node (ft3/sec) — the routing
+     *        twin of `lid_drain_qual_vol`.
+     * @details Set once per runoff step by the LID block in stepRunoff() and
+     *          read by assembleLateralInflows() every routing step until the
+     *          next runoff step overwrites it. It is NOT `ext_inflow`: that
+     *          array is cleared by clearInflowSources() at the top of every
+     *          routing step, i.e. AFTER stepRunoff has added to it, so a drain
+     *          booked there never reached the network (LID fix round,
+     *          2026-08-30 — every drain-to-node case, not only the target-less
+     *          one). Legacy books it as Node.newLatFlow + EXTERNAL_INFLOW.
+     */
+    std::vector     lid_drain_inflow;
 
     // -----------------------------------------------------------------------
     // Per-node quality state — flat 2D: [node * n_pollutants + pollutant]
@@ -392,7 +524,13 @@ struct NodeData {
     std::vector     crown_elev;
 
     /**
-     * @brief Node degree — number of connecting links (+ve downstream, -ve upstream terminal).
+     * @brief legacy Node.degree: the OUTFLOW-link count (toposort_sortLinks,
+     *        a reversed conduit counted from its other end, an outfall's
+     *        link at its downstream node), negated under the dynamic wave
+     *        for a node with no inflow links (validateGeneralLayout):
+     *        < 0 headwater (EXTRAN surcharge corr 0.6), == 0 terminal.
+     *        Set in SWMMEngine::initialize (the resolver's connectivity
+     *        count is provisional).
      * @see Legacy: Node[i].degree
      */
     std::vector        degree;
@@ -409,6 +547,20 @@ struct NodeData {
      */
     std::vector     full_volume;
 
+    /**
+     * @brief Full volume in the LEGACY convention (legacy Node.fullVolume as
+     *        node_validate leaves it): 0 for junctions, outfalls and dividers,
+     *        the pump curve's maximum volume for a Type-1 pump's wet well
+     *        (link.c:1529), the curve volume for storage.
+     *
+     * The dynamic wave books node volume in this convention, so a ponded
+     * junction holds only the water above its rim and a plain junction none;
+     * that is what the .out NODE_VOLUME, the routing mass balance, control
+     * rules and quality mixing see. full_volume keeps MIN_SURFAREA*fullDepth
+     * for junctions because the FV mesh derives its node area from it.
+     */
+    std::vector     rpt_full_volume;
+
     // -----------------------------------------------------------------------
     // Previous-step state (for output interpolation / CFL checks)
     // -----------------------------------------------------------------------
@@ -540,6 +692,12 @@ struct NodeData {
     /// @see Legacy: NodeStats[i].maxInflow
     std::vector     stat_max_total_inflow;
 
+    /// Peak outflow released by a storage unit (project flow units). Storage
+    /// only; stays zero elsewhere. Tracked separately from inflow because a
+    /// pond's whole purpose is that the two differ.
+    /// @see Legacy: StorageStats[k].maxFlow (stats.c:588)
+    std::vector     stat_storage_max_outflow;
+
     /// Cumulative lateral inflow volume at each node (ft3).
     /// @see Legacy: NodeStats[i].totLatFlow
     std::vector     stat_lat_inflow_vol;
@@ -612,6 +770,8 @@ struct NodeData {
         sur_depth.assign(un, 0.0);
         ponded_area.assign(un, 0.0);
         is_virtual.assign(un, 0);
+        is_inlet.assign(un, 0);
+        rim_depth.assign(un, 0.0);
 
         // Subtype config (storage/outfall/divider) lives in NodeSubtypes side-tables.
         depth.assign(un, 0.0);
@@ -628,11 +788,22 @@ struct NodeData {
         coupling_inflow.assign(un, 0.0);
         coupling_volume.assign(un, 0.0);
         coupling_queue.assign(un, 0.0);
+        coupling_age_vol_queue.assign(un, 0.0);
+        coupling_temp_vol_queue.assign(un, 0.0);
+        coupling_age_vol_inflow.assign(un, 0.0);
+        coupling_temp_vol_inflow.assign(un, 0.0);
         qual_mass_in.clear();
         iface_qual_mass.clear();
+        coupling_qual_queue.clear();
+        coupling_qual_inflow.clear();
+        ext_qual_mass.clear();
+        dwf_qual_mass.clear();
         qual_vol_in.assign(un, 0.0);
         lid_drain_qual_load.clear();
         lid_drain_qual_vol.assign(un, 0.0);
+        lid_drain_qual_load_old.clear();
+        lid_drain_qual_vol_old.assign(un, 0.0);
+        lid_drain_inflow.assign(un, 0.0);
         inflow.assign(un, 0.0);
         outflow.assign(un, 0.0);
         overflow.assign(un, 0.0);
@@ -641,6 +812,7 @@ struct NodeData {
         degree.assign(un, 0);
         old_net_inflow.assign(un, 0.0);
         full_volume.assign(un, 0.0);
+        rpt_full_volume.assign(un, 0.0);
         old_depth.assign(un, 0.0);
         old_volume.assign(un, 0.0);
         old_lat_flow.assign(un, 0.0);
@@ -665,6 +837,7 @@ struct NodeData {
         stat_max_surcharge_height.assign(un, 0.0);
         stat_max_lat_inflow.assign(un, 0.0);
         stat_max_total_inflow.assign(un, 0.0);
+        stat_storage_max_outflow.assign(un, 0.0);
         stat_lat_inflow_vol.assign(un, 0.0);
         stat_total_inflow_vol.assign(un, 0.0);
         stat_total_outflow_vol.assign(un, 0.0);
@@ -690,17 +863,23 @@ struct NodeData {
         g(invert_elev, 0.0); g(full_depth, 0.0); g(init_depth, 0.0);
         g(sur_depth, 0.0); g(ponded_area, 0.0);
         g(is_virtual, static_cast(0));
+        g(is_inlet, static_cast(0));
+        g(rim_depth, 0.0);
         // Subtype config (storage/outfall/divider) lives in NodeSubtypes side-tables.
         g(depth, 0.0); g(head, 0.0); g(volume, 0.0);
         g(lat_flow, 0.0); g(user_lat_flow, 0.0);
         g(runoff_inflow, 0.0); g(gw_inflow, 0.0); g(ext_inflow, 0.0);
         g(dwf_inflow, 0.0); g(rdii_inflow, 0.0); g(iface_inflow, 0.0);
         g(coupling_inflow, 0.0); g(coupling_volume, 0.0); g(coupling_queue, 0.0);
+        g(coupling_age_vol_queue, 0.0); g(coupling_temp_vol_queue, 0.0);
+        g(coupling_age_vol_inflow, 0.0); g(coupling_temp_vol_inflow, 0.0);
         qual_vol_in.resize(un, 0.0);
         lid_drain_qual_vol.resize(un, 0.0);
+        lid_drain_qual_vol_old.resize(un, 0.0);
+        lid_drain_inflow.resize(un, 0.0);
         g(inflow, 0.0); g(outflow, 0.0); g(overflow, 0.0);
         g(losses, 0.0); g(crown_elev, 0.0); g(degree, 0);
-        g(old_net_inflow, 0.0); g(full_volume, 0.0);
+        g(old_net_inflow, 0.0); g(full_volume, 0.0); g(rpt_full_volume, 0.0);
         g(old_depth, 0.0); g(old_volume, 0.0); g(old_lat_flow, 0.0);
         g(old_inflow, 0.0);
         comments.resize(un, std::string{});
@@ -715,6 +894,7 @@ struct NodeData {
         g(stat_max_inflow_date, 0.0); g(stat_time_surcharged, 0.0);
         g(stat_max_surcharge_height, 0.0);
         g(stat_max_lat_inflow, 0.0); g(stat_max_total_inflow, 0.0);
+        g(stat_storage_max_outflow, 0.0);
         g(stat_lat_inflow_vol, 0.0); g(stat_total_inflow_vol, 0.0);
         g(stat_total_outflow_vol, 0.0);
         g(stat_outfall_avg_flow, 0.0); g(stat_outfall_max_flow, 0.0);
@@ -723,6 +903,49 @@ struct NodeData {
         // Note: qual_mass_in, conc, conc_old, hrt handled by resize_quality()
     }
 
+    /**
+     * @brief Reserve capacity for `n` nodes without changing count().
+     *
+     * @details Parsing grows these arrays one row at a time via grow_to(),
+     *          so each of the ~60 parallel vectors reallocates and copies
+     *          O(log n) times over a section — the dominant memory traffic in
+     *          handler dispatch on a large model.
+     *
+     *          This reserves capacity only. It deliberately does NOT resize:
+     *          count() is the vector size, and PostParseResolver compares it
+     *          against the final name count and calls resize() when they
+     *          differ — a call with destructive assign semantics. Growing the
+     *          SIZE speculatively here would trip that path and wipe parsed
+     *          data. Capacity is invisible to all of it.
+     *
+     *          Over-reserving is harmless, so callers pass the section's row
+     *          count as an upper bound.
+     */
+    void reserve_to(int n) {
+        if (n <= 0) return;
+        const auto un = static_cast(n);
+        if (type.capacity() >= un) return;
+        auto r = [&](auto& vec) { vec.reserve(un); };
+        r(type); r(invert_elev); r(full_depth); r(init_depth);
+        r(sur_depth); r(ponded_area); r(is_virtual); r(is_inlet); r(rim_depth); r(depth);
+        r(head); r(volume); r(lat_flow); r(user_lat_flow);
+        r(runoff_inflow); r(gw_inflow); r(ext_inflow); r(dwf_inflow);
+        r(rdii_inflow); r(iface_inflow); r(coupling_inflow); r(coupling_volume);
+        r(coupling_queue); r(inflow); r(outflow); r(overflow);
+        r(coupling_age_vol_queue); r(coupling_temp_vol_queue);
+        r(coupling_age_vol_inflow); r(coupling_temp_vol_inflow);
+        r(losses); r(crown_elev); r(degree); r(old_net_inflow);
+        r(full_volume); r(rpt_full_volume); r(old_depth); r(old_volume); r(old_lat_flow);
+        r(old_inflow); r(rpt_flag); r(stat_vol_flooded); r(stat_time_flooded);
+        r(stat_max_depth); r(stat_max_overflow); r(stat_max_overflow_date); r(stat_sum_depth);
+        r(stat_sum_volume); r(stat_max_depth_date); r(stat_max_rpt_depth); r(stat_max_inflow_date);
+        r(stat_time_surcharged); r(stat_max_surcharge_height); r(stat_max_lat_inflow); r(stat_max_total_inflow);
+        r(stat_storage_max_outflow);
+        r(stat_lat_inflow_vol); r(stat_total_inflow_vol); r(stat_total_outflow_vol); r(stat_outfall_avg_flow);
+        r(stat_outfall_max_flow); r(stat_outfall_periods); r(stat_non_converged_count); r(stat_time_courant_critical);
+        r(qual_vol_in); r(lid_drain_qual_vol); r(lid_drain_inflow); r(comments); r(tags);
+    }
+
     /**
      * @brief Erase the node at index `idx` from every parallel array.
      *
@@ -737,7 +960,7 @@ struct NodeData {
         auto e = [&](auto& v) { if (ui < v.size()) v.erase(v.begin() + static_cast(idx)); };
 
         e(type); e(invert_elev); e(full_depth); e(init_depth); e(sur_depth); e(ponded_area);
-        e(is_virtual);
+        e(is_virtual); e(is_inlet); e(rim_depth);
 
         // Subtype config (storage/outfall/divider) lives in NodeSubtypes side-tables;
         // its rows are erased/renumbered by NodeSubtypes::erase_node (called by the
@@ -747,9 +970,11 @@ struct NodeData {
         e(runoff_inflow); e(gw_inflow); e(ext_inflow); e(dwf_inflow);
         e(rdii_inflow); e(iface_inflow);
         e(coupling_inflow); e(coupling_volume); e(coupling_queue);
-        e(qual_vol_in); e(lid_drain_qual_vol);
+        e(coupling_age_vol_queue); e(coupling_temp_vol_queue);
+        e(coupling_age_vol_inflow); e(coupling_temp_vol_inflow);
+        e(qual_vol_in); e(lid_drain_qual_vol); e(lid_drain_inflow);
         e(inflow); e(outflow); e(overflow); e(losses);
-        e(crown_elev); e(degree); e(old_net_inflow); e(full_volume);
+        e(crown_elev); e(degree); e(old_net_inflow); e(full_volume); e(rpt_full_volume);
         e(old_depth); e(old_volume); e(old_lat_flow); e(old_inflow);
         e(comments); e(tags); e(rpt_flag);
 
@@ -757,7 +982,8 @@ struct NodeData {
         e(stat_max_overflow_date); e(stat_sum_depth); e(stat_sum_volume); e(stat_max_depth_date);
         e(stat_max_rpt_depth); e(stat_max_inflow_date); e(stat_time_surcharged);
         e(stat_max_surcharge_height); e(stat_outfall_avg_flow); e(stat_max_lat_inflow);
-        e(stat_max_total_inflow); e(stat_lat_inflow_vol); e(stat_total_inflow_vol);
+        e(stat_max_total_inflow); e(stat_storage_max_outflow);
+        e(stat_lat_inflow_vol); e(stat_total_inflow_vol);
         e(stat_total_outflow_vol); e(stat_outfall_max_flow); e(stat_outfall_periods);
         e(stat_non_converged_count); e(stat_time_courant_critical);
 
@@ -772,6 +998,9 @@ struct NodeData {
             };
             erase2d(conc); erase2d(conc_old);
             erase2d(qual_mass_in); erase2d(iface_qual_mass);
+            erase2d(coupling_qual_queue); erase2d(coupling_qual_inflow);
+            erase2d(ext_qual_mass);
+            erase2d(dwf_qual_mass);
             erase2d(lid_drain_qual_load); erase2d(user_conc_mass_flux);
             if (ui < hrt.size()) hrt.erase(hrt.begin() + static_cast(idx));
         }
@@ -813,6 +1042,10 @@ struct NodeData {
             user_conc_mass_flux.assign(total, 0.0);
             qual_mass_in.assign(total, 0.0);
             iface_qual_mass.assign(total, 0.0);
+            coupling_qual_queue.assign(total, 0.0);
+            coupling_qual_inflow.assign(total, 0.0);
+            ext_qual_mass.assign(total, 0.0);
+            dwf_qual_mass.assign(total, 0.0);
             lid_drain_qual_load.assign(total, 0.0);
         }
     }
@@ -832,6 +1065,8 @@ struct NodeData {
         sur_depth.shrink_to_fit();
         ponded_area.shrink_to_fit();
         is_virtual.shrink_to_fit();
+        is_inlet.shrink_to_fit();
+        rim_depth.shrink_to_fit();
 
         // Subtype config (storage/outfall/divider) lives in NodeSubtypes side-tables.
         depth.shrink_to_fit();
@@ -848,8 +1083,14 @@ struct NodeData {
         coupling_inflow.shrink_to_fit();
         coupling_volume.shrink_to_fit();
         coupling_queue.shrink_to_fit();
+        coupling_age_vol_queue.shrink_to_fit(); coupling_temp_vol_queue.shrink_to_fit();
+        coupling_age_vol_inflow.shrink_to_fit(); coupling_temp_vol_inflow.shrink_to_fit();
         qual_mass_in.shrink_to_fit();
         iface_qual_mass.shrink_to_fit();
+        coupling_qual_queue.shrink_to_fit();
+        coupling_qual_inflow.shrink_to_fit();
+        ext_qual_mass.shrink_to_fit();
+        dwf_qual_mass.shrink_to_fit();
         qual_vol_in.shrink_to_fit();
         conc.shrink_to_fit();
         conc_old.shrink_to_fit();
@@ -862,6 +1103,7 @@ struct NodeData {
         degree.shrink_to_fit();
         old_net_inflow.shrink_to_fit();
         full_volume.shrink_to_fit();
+        rpt_full_volume.shrink_to_fit();
         old_depth.shrink_to_fit();
         old_volume.shrink_to_fit();
         old_lat_flow.shrink_to_fit();
@@ -885,6 +1127,7 @@ struct NodeData {
         stat_max_surcharge_height.shrink_to_fit();
         stat_max_lat_inflow.shrink_to_fit();
         stat_max_total_inflow.shrink_to_fit();
+        stat_storage_max_outflow.shrink_to_fit();
         stat_lat_inflow_vol.shrink_to_fit();
         stat_total_inflow_vol.shrink_to_fit();
         stat_total_outflow_vol.shrink_to_fit();
@@ -898,15 +1141,28 @@ struct NodeData {
      * @brief Snapshot current state into old-step arrays before solving.
      */
     void save_state() noexcept {
+        save_hyd_state();
+        save_lat_qual_state();
+    }
+
+    /// Legacy node_setOldHydState (node.c:294-299): oldDepth, oldVolume,
+    /// oldFlowInflow, oldNetInflow — rolled by routeFlow, i.e. ONLY on a
+    /// step that is actually routed (a SKIP_STEADY_STATE step keeps the last
+    /// routed step's old/new pair for its reports and its steady test).
+    void save_hyd_state() noexcept {
         std::copy(depth.begin(),    depth.end(),    old_depth.begin());
         std::copy(volume.begin(),   volume.end(),   old_volume.begin());
-        std::copy(lat_flow.begin(), lat_flow.end(), old_lat_flow.begin());
-        // Legacy node_setOldHydState (node.c:294): oldFlowInflow = inflow
         std::copy(inflow.begin(),   inflow.end(),   old_inflow.begin());
         // Save net inflow for trapezoidal averaging in next step
         for (std::size_t i = 0; i < inflow.size(); ++i) {
             old_net_inflow[i] = inflow[i] - outflow[i];
         }
+    }
+
+    /// Legacy initSystemInflows (oldLatFlow = newLatFlow) and
+    /// node_setOldQualState — rolled every routing step, routed or not.
+    void save_lat_qual_state() noexcept {
+        std::copy(lat_flow.begin(), lat_flow.end(), old_lat_flow.begin());
         std::copy(conc.begin(), conc.end(), conc_old.begin());
     }
 
@@ -943,6 +1199,12 @@ struct NodeData {
         std::fill(coupling_inflow.begin(), coupling_inflow.end(), 0.0);
         std::fill(coupling_volume.begin(), coupling_volume.end(), 0.0);
         std::fill(coupling_queue.begin(), coupling_queue.end(), 0.0);
+        std::fill(coupling_qual_queue.begin(), coupling_qual_queue.end(), 0.0);
+        std::fill(coupling_qual_inflow.begin(), coupling_qual_inflow.end(), 0.0);
+        std::fill(coupling_age_vol_queue.begin(),  coupling_age_vol_queue.end(),  0.0);
+        std::fill(coupling_temp_vol_queue.begin(), coupling_temp_vol_queue.end(), 0.0);
+        std::fill(coupling_age_vol_inflow.begin(),  coupling_age_vol_inflow.end(),  0.0);
+        std::fill(coupling_temp_vol_inflow.begin(), coupling_temp_vol_inflow.end(), 0.0);
         clearInflowSources();
         std::fill(conc.begin(), conc.end(), 0.0);
         std::fill(conc_old.begin(), conc_old.end(), 0.0);
@@ -965,6 +1227,8 @@ struct NodeData {
         std::fill(rdii_inflow.begin(),   rdii_inflow.end(),   0.0);
         std::fill(iface_inflow.begin(),  iface_inflow.end(),  0.0);
         std::fill(iface_qual_mass.begin(), iface_qual_mass.end(), 0.0);
+        std::fill(ext_qual_mass.begin(),   ext_qual_mass.end(),   0.0);
+        std::fill(dwf_qual_mass.begin(),   dwf_qual_mass.end(),   0.0);
         std::fill(qual_mass_in.begin(),  qual_mass_in.end(),  0.0);
         std::fill(qual_vol_in.begin(),   qual_vol_in.end(),   0.0);
     }
diff --git a/src/engine/data/NodeSubtypes.hpp b/src/engine/data/NodeSubtypes.hpp
index 50c22dfbf..514e695e5 100644
--- a/src/engine/data/NodeSubtypes.hpp
+++ b/src/engine/data/NodeSubtypes.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NodeSubtypes.hpp
  * @brief Relational (normalized) Structure-of-Arrays side-tables for node subtypes.
@@ -32,7 +48,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_NODE_SUBTYPES_HPP
@@ -90,6 +106,11 @@ struct StorageData {
     std::vector      evap_loss;
     /** @brief Exfiltration loss this timestep (ft3). */
     std::vector      exfil_loss;
+    /** @brief Raw (uncapped) exfiltration rate this timestep (cfs), written by
+     *  ExfilSolver::computeAll and consumed by Router::initNodeFlows, which
+     *  applies legacy's single joint evap+exfil volume cap and books the final
+     *  exfil_loss volume. Kept as a rate so no dt round-trip perturbs bits. */
+    std::vector      exfil_rate;
     /** @brief Green-Ampt suction head for exfiltration. */
     std::vector      exfil_suction;
     /** @brief Green-Ampt saturated conductivity for exfiltration. */
@@ -107,6 +128,7 @@ struct StorageData {
         a.clear(); b.clear(); c.clear();
         p1.clear(); p2.clear(); p3.clear();
         seep_rate.clear(); evap_frac.clear(); evap_loss.clear(); exfil_loss.clear();
+        exfil_rate.clear();
         exfil_suction.clear(); exfil_ksat.clear(); exfil_imd.clear();
     }
 
@@ -118,7 +140,7 @@ struct StorageData {
         a.reserve(un); b.reserve(un); c.reserve(un);
         p1.reserve(un); p2.reserve(un); p3.reserve(un);
         seep_rate.reserve(un); evap_frac.reserve(un);
-        evap_loss.reserve(un); exfil_loss.reserve(un);
+        evap_loss.reserve(un); exfil_loss.reserve(un); exfil_rate.reserve(un);
         exfil_suction.reserve(un); exfil_ksat.reserve(un); exfil_imd.reserve(un);
     }
 
@@ -144,6 +166,7 @@ struct StorageData {
         evap_frac.insert(evap_frac.begin() + p, 0.0);
         evap_loss.insert(evap_loss.begin() + p, 0.0);
         exfil_loss.insert(exfil_loss.begin() + p, 0.0);
+        exfil_rate.insert(exfil_rate.begin() + p, 0.0);
         exfil_suction.insert(exfil_suction.begin() + p, 0.0);
         exfil_ksat.insert(exfil_ksat.begin() + p, 0.0);
         exfil_imd.insert(exfil_imd.begin() + p, 0.0);
@@ -167,6 +190,7 @@ struct StorageData {
         evap_frac.erase(evap_frac.begin() + p);
         evap_loss.erase(evap_loss.begin() + p);
         exfil_loss.erase(exfil_loss.begin() + p);
+        exfil_rate.erase(exfil_rate.begin() + p);
         exfil_suction.erase(exfil_suction.begin() + p);
         exfil_ksat.erase(exfil_ksat.begin() + p);
         exfil_imd.erase(exfil_imd.begin() + p);
diff --git a/src/engine/data/PollutantData.hpp b/src/engine/data/PollutantData.hpp
index 9d1401d4a..90b52f8f7 100644
--- a/src/engine/data/PollutantData.hpp
+++ b/src/engine/data/PollutantData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PollutantData.hpp
  * @brief Structure-of-Arrays (SoA) storage for pollutants and water quality.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_POLLUTANT_DATA_HPP
@@ -71,7 +87,10 @@ struct PollutantData {
     std::vector     mwt;
 
     /**
-     * @brief First-order decay coefficient (1/day).
+     * @brief First-order decay coefficient (1/sec). The [POLLUTANTS]
+     *        Kdecay column is 1/day: the parser divides by SEC_PER_DAY
+     *        and every writer multiplies back (KD1) — the same seam
+     *        legacy keeps (landuse.c / SECperDAY).
      * @see Legacy: Pollut[i].kDecay
      */
     std::vector     k_decay;
diff --git a/src/engine/data/QualityData.hpp b/src/engine/data/QualityData.hpp
index cb89cfa02..8b099535b 100644
--- a/src/engine/data/QualityData.hpp
+++ b/src/engine/data/QualityData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file QualityData.hpp
  * @brief SoA stores for land uses, buildup, washoff, and treatment.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_QUALITY_DATA_HPP
diff --git a/src/engine/data/ReactionData.hpp b/src/engine/data/ReactionData.hpp
new file mode 100644
index 000000000..12d7ae1f6
--- /dev/null
+++ b/src/engine/data/ReactionData.hpp
@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionData.hpp
+ * @brief Multispecies reaction system data (EPANET-MSX conventions) — SoA,
+ *        hot/cold split per LARD plan §16 D-L3 / reactions plan D-R3.
+ *
+ * @details Phase R1 populates this from the reactions component's config
+ *          file (`model.rxn`, sections [REACTION_*]). Expression SOURCES
+ *          are stored here (cold); the compiled flat RPN token pool arrives
+ *          with phase R2 and lives in separate hot arrays so no
+ *          std::string enters an integrator loop. Layout notes:
+ *          per-species expression slots are dense (size n_species,
+ *          form == NONE ⇒ no expression for that species in that scope).
+ *
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md §2–§3
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_REACTION_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_REACTION_DATA_HPP
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "ReactionTokens.hpp"
+#include "MsxSurfaceData.hpp"
+
+namespace openswmm {
+
+enum class ReactionSolverKind : int { EUL = 0, RK5 = 1, ROS2 = 2, BDF2 = 3 };
+enum class ReactionCoupling : int { NONE = 0, FULL = 1 };
+enum class ReactionRateUnits : int { SEC = 0, MIN = 1, HR = 2, DAY = 3 };
+enum class ReactionAreaUnits : int { FT2 = 0, M2 = 1, CM2 = 2 };
+enum class ReactionExprForm : int { NONE = 0, RATE = 1, EQUIL = 2, FORMULA = 3 };
+
+struct ReactionData {
+    // ---- [REACTION_OPTIONS] ------------------------------------------------
+    /**
+     * @brief Default integrator.
+     *
+     * @details RK5, not an implicit solver. Measured substeps for one
+     *          routing step, at the shipping tolerances below and at
+     *          1e-10/1e-8:
+     *
+     *          | case                        | RK5   | ROS2   | BDF2   |
+     *          |-----------------------------|-------|--------|--------|
+     *          | first-order decay, default  |     5 |    134 |    197 |
+     *          | stiff (λ ratio 1e6), default|  2682 |    281 |    408 |
+     *          | stiff, atol 1e-10           |  2744 |  26938 |  39693 |
+     *
+     *          RK5 wins the common case by ~27x. It loses the stiff case at
+     *          loose tolerance by ~10x but still COMPLETES, with the slow
+     *          mode exact. At tight tolerance it beats both implicit solvers
+     *          on the stiff problem, because RK5's step is STABILITY-limited
+     *          (nearly flat in tolerance) while the Rosenbrock/BDF pairs are
+     *          ACCURACY-limited and scale as sqrt(tol).
+     *
+     *          The cliff: RK5 costs about lambda_fast*dt/3.3 substeps, so
+     *          past lambda_fast*dt ~ 3e5 it hits kMaxSubsteps and fails.
+     *          That failure is loud and names ROS2/BDF2 as the remedy
+     *          (ReactionIntegrator's substep-cap message) — a slow default
+     *          that fails legibly beats an implicit default that is slower
+     *          everywhere except the stiff-and-loose corner.
+     */
+    ReactionSolverKind solver      = ReactionSolverKind::RK5;
+    ReactionCoupling   coupling    = ReactionCoupling::NONE;
+    ReactionRateUnits  rate_units  = ReactionRateUnits::HR;
+    ReactionAreaUnits  area_units  = ReactionAreaUnits::FT2;
+    double             timestep    = 0.0;   ///< 0 ⇒ follow QUALITY_STEP
+    double             atol        = 1.0e-6;
+    double             rtol        = 1.0e-4;
+    /// TEMP's value when no heat-transport temperature exists for the
+    /// element (HEAT_TRANSPORT off, or state not yet seeded). 20 degC is
+    /// the standard water-quality reference temperature.
+    double             default_temp_c = 20.0;
+
+    // ---- [REACTION_SPECIES] — index-aligned with the SpeciesRegistry MSX
+    //      block (registry index = registry_base + i). ------------------------
+    int registry_base = -1;                  ///< first MSX index in the registry
+    std::vector species_name;   ///< cold
+    std::vector     species_is_wall;///< 0 = BULK, 1 = WALL
+    std::vector species_units;  ///< cold
+    std::vector      species_atol;   ///< hot (0 ⇒ global)
+    std::vector      species_rtol;   ///< hot (0 ⇒ global)
+
+    // ---- [REACTION_COEFFICIENTS] -------------------------------------------
+    std::vector coef_name;      ///< cold
+    std::vector     coef_is_param;  ///< 1 = PARAMETER (overridable), 0 = CONSTANT
+    std::vector      coef_value;     ///< hot (global values; per-element
+                                             ///< overrides arrive with [REACTION_PARAMETERS])
+
+    // ---- [REACTION_TERMS] --------------------------------------------------
+    std::vector term_name;      ///< cold
+    std::vector term_expr_src;  ///< cold (compiled in R2)
+
+    // ---- [REACTION_PIPES] / [REACTION_TANKS] — dense per species -----------
+    std::vector pipe_form;     ///< size n_species
+    std::vector      pipe_expr_src; ///< size n_species (cold)
+    std::vector tank_form;
+    std::vector      tank_expr_src;
+
+    // ---- [REACTION_QUALITY] GLOBAL initial values (R1) ---------------------
+    std::vector init_global;         ///< size n_species
+
+    // ---- [REACTION_QUALITY] NODE/LINK per-element overrides (E-B) ----------
+    // Sparse row table over the GLOBAL seed; covered by clear() via the
+    // *this = ReactionData{} reset.
+    std::vector init_elem_is_link;  ///< 0 = NODE row, 1 = LINK row
+    std::vector     init_elem_idx;      ///< resolved node/link index
+    std::vector     init_elem_species;  ///< 0..n_species()-1
+    std::vector  init_elem_value;
+
+    // ---- Compiled bytecode (R2 — D-L3 flat pool; spans index token_pool) ----
+    std::vector    token_pool;      ///< hot: one contiguous pool
+    std::vector term_expr;       ///< per term, in-order evaluation
+    std::vector pipe_expr;       ///< per species (len 0 ⇒ none)
+    std::vector tank_expr;       ///< per species
+    bool compiled = false;                   ///< R2 compile pass succeeded
+    bool warned_react_failure       = false;
+
+    // ---- R4: MSX species element state under QUALITY_SOLVER LEGACY --------
+    // [element * n_species + s]; sized lazily by the legacy binding. R4b
+    // (2026-09-01): species react per element AND advect between elements
+    // (routeLegacyMsx, the CSTR mirror family) — the not-transported
+    // warning and its once-per-run flag are gone with the limitation.
+    std::vector msx_node_conc;
+    std::vector msx_link_conc;
+
+    // ---- U2 (2026-09-07): external MSX loads at the node seam ------------
+    // [node * n_species + m], a mass RATE in the species' internal unit
+    // convention (conc-units × ft3/s — the qual_mass_in shape), assembled
+    // every routing step by InflowSolver::computeAll from [INFLOWS] rows
+    // that name a species (CONCEN × node external flow, or MASS ÷ LperFT3).
+    // Empty until a species inflow row exists. Consumed by every quality
+    // engine's node mixing: routeLegacyMsx (LEGACY), ArdEngine stage 1b /
+    // 1a' (EULERIAN_ARD) and the LARD node stage.
+    std::vector msx_ext_mass_in;
+
+    /// BW-MSX (2026-09-19): surface buildup / washoff / sweeping of MSX
+    /// species — rows parked by name at parse, resolved after this component
+    /// is applied, stepped beside the pollutant surface-quality step, and
+    /// delivered into `msx_ext_mass_in` each routing step. See
+    /// `quality/MsxSurfaceQuality.hpp`.
+    MsxSurfaceData surface;
+
+    bool configured = false;                 ///< a reactions component applied
+
+    int n_species() const noexcept {
+        return static_cast(species_name.size());
+    }
+    int find_species(std::string_view n) const {
+        for (std::size_t i = 0; i < species_name.size(); ++i)
+            if (species_name[i] == n) return static_cast(i);
+        return -1;
+    }
+    int find_coef(std::string_view n) const {
+        for (std::size_t i = 0; i < coef_name.size(); ++i)
+            if (coef_name[i] == n) return static_cast(i);
+        return -1;
+    }
+    int find_term(std::string_view n) const {
+        for (std::size_t i = 0; i < term_name.size(); ++i)
+            if (term_name[i] == n) return static_cast(i);
+        return -1;
+    }
+
+    /// Reset the component's own state. The `surface` block is authored by
+    /// the .inp ([BUILDUP]/[WASHOFF]/[LOADINGS] rows parked by name before
+    /// the component is applied), so it survives a (re)apply and is bound
+    /// afterwards by msxsurf::resolve().
+    void clear() {
+        MsxSurfaceData keep = std::move(surface);
+        *this = ReactionData{};
+        surface = std::move(keep);
+    }
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_REACTION_DATA_HPP
diff --git a/src/engine/data/ReactionTokens.hpp b/src/engine/data/ReactionTokens.hpp
new file mode 100644
index 000000000..d9877cda4
--- /dev/null
+++ b/src/engine/data/ReactionTokens.hpp
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionTokens.hpp
+ * @brief POD reaction-VM instruction + span types (phase R2, D-L3 flat
+ *        pool). Data-layer header: no dependencies, included by both
+ *        ReactionData (which owns the pool) and the transport-side
+ *        compiler/evaluator (ReactionExpression).
+ *
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_REACTION_TOKENS_HPP
+#define OPENSWMM_ENGINE_DATA_REACTION_TOKENS_HPP
+
+#include 
+
+namespace openswmm {
+
+/// Hydraulic variables available in reaction expressions (reactions plan
+/// §2; engines populate the evaluation environment at R6). Order is the
+/// ABI of the evaluator's hydvar array.
+enum class RxHydVar : int {
+    D = 0,    ///< depth (ft)
+    Q,        ///< flow (cfs)
+    U,        ///< velocity (ft/s)
+    RE,       ///< Reynolds number
+    US,       ///< shear velocity (ft/s)
+    FF,       ///< Darcy-Weisbach friction factor
+    AV,       ///< wetted surface area per volume (1/ft)
+    HRT,      ///< hydraulic residence time (s)
+    DT,       ///< reaction step (s)
+    TEMP,     ///< local water temperature (degC); [REACTION_OPTIONS]
+              ///< TEMPERATURE constant when HEAT_TRANSPORT is off
+    COUNT_
+};
+
+/// One VM instruction. POD, contiguous in the shared pool — no
+/// per-expression heap vectors (LARD plan §16 D-L3).
+struct RxToken {
+    enum Op : uint8_t {
+        PUSH_NUM = 0,   ///< value
+        PUSH_SPECIES,   ///< idx = local species slot
+        PUSH_COEF,      ///< idx = coefficient slot
+        PUSH_TERM,      ///< idx = term slot (evaluated earlier in-order)
+        PUSH_HYDVAR,    ///< idx = RxHydVar
+        PUSH_POLLUT,    ///< idx = pollutant index (READ-ONLY coupling, R4)
+        ADD, SUB, MUL, DIV, POW, NEG,
+        F_EXP, F_LOG, F_LOG10, F_SQRT, F_ABS, F_SGN, F_STEP,
+        F_SIN, F_COS, F_TAN,
+        F_MIN, F_MAX    ///< binary
+    };
+    uint8_t  op    = PUSH_NUM;
+    int32_t  idx   = 0;
+    double   value = 0.0;
+};
+
+/// Compiled expression = span into the shared pool. len 0 ⇒ no expression.
+struct RxExprSpan {
+    int32_t begin = 0;
+    int32_t len   = 0;
+};
+
+/// Maximum operand-stack depth; the compiler rejects deeper expressions so
+/// the evaluator's fixed stack can never overflow.
+inline constexpr int kRxMaxStackDepth = 32;
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_REACTION_TOKENS_HPP
diff --git a/src/engine/data/SpeciesRegistry.hpp b/src/engine/data/SpeciesRegistry.hpp
new file mode 100644
index 000000000..717550f0b
--- /dev/null
+++ b/src/engine/data/SpeciesRegistry.hpp
@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SpeciesRegistry.hpp
+ * @brief Single source of truth for all transported constituents
+ *        (Unified Transport master plan §4.1; phase T0a).
+ *
+ * @details Legacy `[POLLUTANTS]` entries occupy the first slots with kind
+ *          POLLUTANT (indices align 1:1 with the legacy pollutant index, so
+ *          every existing `[link*np+p]` array stays valid). MSX species
+ *          (reactions component, phase R1) append with MSX_BULK/MSX_WALL.
+ *          Reserved species (water age A1, temperature H1) append with
+ *          their reserved kinds when those phases land.
+ *
+ *          Engine consumption note: as of E4/R6 the ARD engine carries
+ *          pollutants + MSX_BULK species on its mesh (it sizes from
+ *          n_pollutants() + ReactionData::n_species(), refusing WALL);
+ *          `transported_count()` counts POLLUTANT + MSX_BULK to match.
+ *          The LEGACY engine still transports pollutants only (MSX
+ *          transport under LEGACY is plan phase R4b).
+ *
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_SPECIES_REGISTRY_HPP
+#define OPENSWMM_ENGINE_DATA_SPECIES_REGISTRY_HPP
+
+#include 
+#include 
+#include 
+
+namespace openswmm {
+
+/// Constituent kinds (master plan §4.1).
+enum class SpeciesKind : int {
+    POLLUTANT            = 0,  ///< legacy [POLLUTANTS] entry
+    RESERVED_AGE         = 1,  ///< __WATER_AGE__ (phase A1)
+    RESERVED_TEMPERATURE = 2,  ///< __TEMPERATURE__ (phase H1)
+    MSX_BULK             = 3,  ///< reactions component BULK species (R1)
+    MSX_WALL             = 4   ///< reactions component WALL species (R1)
+};
+
+class SpeciesRegistry {
+public:
+    void clear() {
+        name_.clear();
+        kind_.clear();
+        units_.clear();
+        n_pollutants_ = 0;
+    }
+
+    /// Append a species. Returns the new index, or -1 on a name collision
+    /// (names are unique across ALL kinds — an MSX species may not shadow a
+    /// pollutant).
+    int add(std::string name, SpeciesKind kind, std::string units) {
+        if (find(name) >= 0) return -1;
+        name_.push_back(std::move(name));
+        kind_.push_back(kind);
+        units_.push_back(std::move(units));
+        if (kind == SpeciesKind::POLLUTANT) ++n_pollutants_;
+        return static_cast(name_.size()) - 1;
+    }
+
+    int find(std::string_view name) const {
+        for (std::size_t i = 0; i < name_.size(); ++i)
+            if (name_[i] == name) return static_cast(i);
+        return -1;
+    }
+
+    int count() const noexcept { return static_cast(name_.size()); }
+    int pollutant_count() const noexcept { return n_pollutants_; }
+
+    /// Species the ARD engine carries on its mesh: POLLUTANT + MSX_BULK
+    /// (E4/R6) + RESERVED_AGE (A1a) + RESERVED_TEMPERATURE (H4). WALL
+    /// species are element-local and stay off the mesh.
+    ///
+    /// @note This is a KIND whitelist, the shape lesson 51 warns about: it
+    ///       had to be edited when temperature joined, and will again for
+    ///       the next reserved kind. It currently has no callers in `src/`,
+    ///       so a stale entry here is latent rather than live — which is
+    ///       exactly why it was still wrong when H4 arrived.
+    int transported_count() const noexcept {
+        int n = 0;
+        for (const auto k : kind_)
+            if (k == SpeciesKind::POLLUTANT || k == SpeciesKind::MSX_BULK ||
+                k == SpeciesKind::RESERVED_AGE ||
+                k == SpeciesKind::RESERVED_TEMPERATURE)
+                ++n;
+        return n;
+    }
+
+    const std::string& name(int i) const { return name_[static_cast(i)]; }
+    SpeciesKind kind(int i) const { return kind_[static_cast(i)]; }
+    const std::string& units(int i) const { return units_[static_cast(i)]; }
+
+    /// Drop every entry at index >= @p n (E-C2: the MSX-block rebuild in
+    /// the reactions CRUD API snapshots the tail, truncates, re-adds the
+    /// MSX species from ReactionData, then restores the tail). Recounts
+    /// pollutants defensively, though the pollutant block always precedes n.
+    void truncate_to(int n) {
+        if (n < 0) n = 0;
+        if (n >= count()) return;
+        const auto un = static_cast(n);
+        name_.resize(un);
+        kind_.resize(un);
+        units_.resize(un);
+        n_pollutants_ = 0;
+        for (const auto k : kind_)
+            if (k == SpeciesKind::POLLUTANT) ++n_pollutants_;
+    }
+
+private:
+    std::vector name_;
+    std::vector kind_;
+    std::vector units_;
+    int n_pollutants_ = 0;
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_SPECIES_REGISTRY_HPP
diff --git a/src/engine/data/StorageGeometry.hpp b/src/engine/data/StorageGeometry.hpp
index 6333c806c..0558e328a 100644
--- a/src/engine/data/StorageGeometry.hpp
+++ b/src/engine/data/StorageGeometry.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file StorageGeometry.hpp
  * @brief Storage-shape raw parameters ⇄ area-relation coefficients, and the
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DATA_STORAGEGEOMETRY_HPP
diff --git a/src/engine/data/SubcatchData.hpp b/src/engine/data/SubcatchData.hpp
index 005d2a070..0a87fc323 100644
--- a/src/engine/data/SubcatchData.hpp
+++ b/src/engine/data/SubcatchData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SubcatchData.hpp
  * @brief Structure-of-Arrays (SoA) storage for subcatchments.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SUBCATCH_DATA_HPP
@@ -151,6 +167,21 @@ struct SubcatchData {
      */
     std::vector frac_imperv_no_store;
 
+    /**
+     * @brief The AUTHORED [SUBAREAS] PctZero column, in percent.
+     * @details Kept alongside the 0-1 fraction because legacy forms the
+     *          impervious-without-storage subarea fraction as
+     *          `fracImperv * x[4] / 100.0` (subcatch.c:268) — it multiplies
+     *          by the PERCENT and divides after. `fracImperv * (x[4]/100)`
+     *          is a different double for about a tenth of all percentages,
+     *          and the difference lands straight in the subarea's area, so
+     *          the runoff kernel needs the number legacy multiplied by.
+     *          A model loaded from GeoPackage, which stores only the
+     *          fraction, recovers it as `fraction * 100`.
+     * @see Legacy: the x[4] of subcatch_readSubareaParams
+     */
+    std::vector pct_zero;
+
     /**
      * @brief Manning's n for impervious area.
      * @see Legacy: Subcatch[i].subArea[IMPERV0].N
@@ -248,12 +279,46 @@ struct SubcatchData {
      */
     std::vector ponded_depth;
 
+    /**
+     * @brief Ponded depth at the START of the runoff step (project length).
+     * @details Legacy forms `Vinflow = vRunon + subcatch_getDepth(j) *
+     *          nonLidArea` at the top of subcatch_getRunoff, BEFORE the
+     *          subareas are stepped, and only later re-derives the ponded
+     *          store from the new depth. findPondedLoads runs after the
+     *          step, so it needs the opening depth kept aside.
+     * @see Legacy: the Vinflow term in subcatch.c:694
+     */
+    std::vector old_ponded_depth;
+
+    /**
+     * @brief This runoff step's PRE-LID outflow volume, ft³ (legacy vOut1).
+     * @details `vOut1 = Voutflow + vLidRain + vLidRunon`, the denominator the
+     *          washoff concentration is formed over. The surface-quality step
+     *          runs before the LID units, so it is the only place this volume
+     *          still exists; the mass bookings that need it happen after the
+     *          units have run and `runoff` has become the POST-LID value.
+     * @see Legacy: surfqual.c:308
+     */
+    std::vector washoff_vout1;
+
     /**
      * @brief Groundwater outflow rate (project flow units).
      * @see Legacy: Subcatch[i].groundwater->newFlow
      */
     std::vector gw_flow;
 
+    /**
+     * @brief Area-weighted snow pack SWE depth (ft), end of runoff step.
+     * @see Legacy: Subcatch[i].newSnowDepth (subcatch.c:816, snow.c:202)
+     */
+    std::vector snow_depth;
+
+    /**
+     * @brief Total LID drain outflow (cfs) over the current runoff step.
+     * @see Legacy: LidGroups[i]->newDrainFlow (lid.c:1729)
+     */
+    std::vector lid_drain_flow;
+
     // -----------------------------------------------------------------------
     // Previous-step state
     // -----------------------------------------------------------------------
@@ -264,6 +329,12 @@ struct SubcatchData {
     /** @brief GW flow at the previous runoff evaluation (for interpolation). */
     std::vector old_gw_flow;
 
+    /** @brief Snow depth at the previous runoff evaluation (for interpolation). */
+    std::vector old_snow_depth;
+
+    /** @brief LID drain outflow at the previous runoff evaluation (for interpolation). */
+    std::vector old_lid_drain_flow;
+
     // -----------------------------------------------------------------------
     // Runon coupling — subcatch-to-subcatch routing
     // -----------------------------------------------------------------------
@@ -275,6 +346,14 @@ struct SubcatchData {
     /** @brief Previous-step runon inflow (for interpolation). */
     std::vector old_runon_inflow;
 
+    /** @brief Legacy Subcatch.runon: the run-on as a depth rate (ft/s).
+     *  @details Accumulated per contributor in legacy subcatch_addRunonFlow's
+     *           order and form — each flow divided by the non-LID area (or the
+     *           full area when there is none) BEFORE the add — so the sum
+     *           rounds as legacy's does. runon_inflow is the same water in CFS
+     *           for the ledgers. */
+    std::vector runon_rate;
+
     /** @brief Gap #28: accumulated outfall-routed volume (ft³) between runoff steps.
      *  @details Matches legacy Outfall[i].vRouted. Drained to runon_inflow at
      *           each assembleRunon() call, then reset to 0. */
@@ -329,6 +408,44 @@ struct SubcatchData {
      *  @see Legacy: Subcatch[i].pondedQual[] */
     std::vector ponded_qual;
 
+    /** @brief Incoming run-on pollutant mass RATE per (subcatch, pollutant),
+     *         mg/sec.
+     *  @details Legacy uses Subcatch.newQual[] as a temporary accumulator for
+     *           this between subcatch_getRunon and surfqual_getWashoff:
+     *           upstream subcatchments add oldRunoff * oldQual * LperFT3
+     *           (subcatch.c:553) and findPondedLoads / findLidLoads consume
+     *           it as wRunon = newQual * tStep (surfqual.c:443,561). v6 keeps
+     *           the washoff concentration in `conc`, so the accumulator needs
+     *           its own storage. Rebuilt by assembleRunon() every runoff
+     *           substep, like runon_inflow. */
+    std::vector runon_qual_rate;
+
+    /**
+     * @brief Area-averaged subarea runoff RATE, ft/sec — legacy's
+     *        `subcatch_getRunoff` return value (`runoff / area`).
+     * @details The quantity legacy hands findWashoffLoads and
+     *          landuse_getWashoffQual. It is NOT `runoff` (cfs): it carries
+     *          no fOutlet and no LID adjustment, and it never round-trips
+     *          through a volume, so the two surface-quality paths (pollutant
+     *          and reactions species) that both need it read one number
+     *          rather than each re-deriving it a ULP apart.
+     */
+    std::vector subarea_runoff_rate;
+
+    /**
+     * @brief The [LOADINGS] initial surface buildup, mass per unit AREA.
+     * @details Size = n_subcatches * n_pollutants. This is NOT a
+     *          concentration: legacy seeds each land use with
+     *          `initBuildup[p] * fArea` in landuse_getInitBuildup
+     *          (landuse.c:388-395), whatever DRY_DAYS is and whether or not
+     *          the land use has a buildup function. It used to be parked in
+     *          `conc`, which is the reported washoff concentration — so it
+     *          was both unreachable by the initial-buildup seeding and able
+     *          to leak into the first reported concentration.
+     * @see Legacy: Subcatch[i].initBuildup[]
+     */
+    std::vector init_loading;
+
     /** @brief Number of pollutants in the quality arrays. */
     int                 conc_n_pollutants = 0;
 
@@ -426,12 +543,26 @@ struct SubcatchData {
     /** @brief Groundwater flow coefficient A3. */
     std::vector gw_a3;
 
-    /** @brief Threshold groundwater table elevation. */
+    /** @brief [GROUNDWATER] Dsw: fixed surface-water depth (project length units, 0 = live node depth). */
     std::vector gw_tw;
 
-    /** @brief Water table elevation at which lateral GW flow ceases. */
+    /**
+     * @brief [GROUNDWATER] Egwt: threshold groundwater table elevation
+     *        (project length units) below which no lateral flow occurs.
+     *        constants::MISSING when the row gave `*` or omitted it, in which
+     *        case legacy uses the receiving node's invert (gwater.c Hstar).
+     */
     std::vector gw_hstar;
 
+    /** @brief [GROUNDWATER] Ebot: aquifer bottom elevation override; MISSING = the aquifer's. */
+    std::vector gw_bot_elev;
+
+    /** @brief [GROUNDWATER] Wgw: initial water-table elevation override; MISSING = the aquifer's. */
+    std::vector gw_wt_elev;
+
+    /** @brief [GROUNDWATER] Umc: initial upper-zone moisture override; MISSING = the aquifer's. */
+    std::vector gw_upper_moist;
+
     // -----------------------------------------------------------------------
     // Snowpack assignment (index into SnowpackStore, -1 = none)
     // -----------------------------------------------------------------------
@@ -457,6 +588,48 @@ struct SubcatchData {
      */
     std::vector snow_net_perv;
 
+    /**
+     * @brief The MELT-ONLY part of `snow_net_imperv` (ft/sec).
+     *
+     * @details Same plowable/non-plowable area blend as `snow_net_imperv`,
+     *          over `imelt` alone — so `snow_net_imperv − snow_melt_imperv`
+     *          is the rain that fell on the snow-free fraction and reached
+     *          the ground directly.
+     *
+     *          Published for S2: arriving water under a pack is **two
+     *          different waters**. Meltwater is at 0 °C essentially by
+     *          definition — that is what melting means — and carries the
+     *          pack's age; rain-through carries the configured RAINFALL
+     *          values. Their SUM is all `snow_net_*` records, and a sum
+     *          cannot say what the water is worth. Following A4's precedent:
+     *          the split exists as a local in the solver, so publish it
+     *          rather than reconstruct it downstream.
+     *
+     *          -1.0 means no snowpack active, matching `snow_net_*`.
+     */
+    std::vector snow_melt_imperv;
+
+    /// The melt-only part of `snow_net_perv` (ft/sec). See above.
+    std::vector snow_melt_perv;
+
+    /**
+     * @brief S2b — WATER AGE of the meltwater in `snow_melt_imperv` (sec).
+     *
+     * @details The pack's own residence time, area-blended over plowable and
+     *          non-plowable impervious with the **identical** weights
+     *          `snow_melt_imperv` uses. Reusing the blend is not tidiness:
+     *          the rate and the age it describes have to come from the same
+     *          weighting or a caller mixing by one and ageing by the other
+     *          gets a mixture that never existed.
+     *
+     *          -1.0 means no snowpack active, matching `snow_net_*` and
+     *          `snow_melt_*`. Only meaningful where `snow_melt_imperv > 0`.
+     */
+    std::vector snow_melt_age_imperv;
+
+    /// S2b — water age of the meltwater in `snow_melt_perv` (sec). See above.
+    std::vector snow_melt_age_perv;
+
     /**
      * @brief Total LID area for this subcatchment (ft²).
      * @details Sum of all LID unit areas (ft²) that belong to this subcatchment.
@@ -559,6 +732,8 @@ struct SubcatchData {
         snow_scale_factor.assign(un, 1.0);
         frac_imperv.assign(un, 0.0);
         frac_imperv_no_store.assign(un, 0.0);
+        pct_zero.assign(un, 0.0);
+        subarea_runoff_rate.assign(un, 0.0);
         n_imperv.assign(un, 0.013);
         n_perv.assign(un, 0.1);
         ds_imperv.assign(un, 0.0);
@@ -578,11 +753,18 @@ struct SubcatchData {
         evap_loss.assign(un, 0.0);
         infil_loss.assign(un, 0.0);
         ponded_depth.assign(un, 0.0);
+        old_ponded_depth.assign(un, 0.0);
+        washoff_vout1.assign(un, 0.0);
         gw_flow.assign(un, 0.0);
+        snow_depth.assign(un, 0.0);
+        lid_drain_flow.assign(un, 0.0);
         old_runoff.assign(un, 0.0);
         old_gw_flow.assign(un, 0.0);
+        old_snow_depth.assign(un, 0.0);
+        old_lid_drain_flow.assign(un, 0.0);
         runon_inflow.assign(un, 0.0);
         old_runon_inflow.assign(un, 0.0);
+        runon_rate.assign(un, 0.0);
         outfall_runon_vol.assign(un, 0.0);
         gw_sw_head.assign(un, 0.0);
         gw_node_avail_flow.assign(un, 0.0);
@@ -621,10 +803,17 @@ struct SubcatchData {
         gw_b2.assign(un, 0.0);
         gw_a3.assign(un, 0.0);
         gw_tw.assign(un, 0.0);
-        gw_hstar.assign(un, 0.0);
+        gw_hstar.assign(un, -1.0e10);        // constants::MISSING
+        gw_bot_elev.assign(un, -1.0e10);
+        gw_wt_elev.assign(un, -1.0e10);
+        gw_upper_moist.assign(un, -1.0e10);
         snowpack.assign(un, -1);
         snow_net_imperv.assign(un, -1.0);
         snow_net_perv.assign(un, -1.0);
+        snow_melt_imperv.assign(un, -1.0);
+        snow_melt_perv.assign(un, -1.0);
+        snow_melt_age_imperv.assign(un, -1.0);
+        snow_melt_age_perv.assign(un, -1.0);
         total_lid_area_ft2.assign(un, 0.0);
         lid_return_to_perv_cfs.assign(un, 0.0);
         lid_drain_runon_cfs.assign(un, 0.0);
@@ -642,7 +831,8 @@ struct SubcatchData {
         gage_name.resize(un); g(gage, -1);
         g(area, 0.0); g(width, 0.0); g(slope, 0.0); g(curb_length, 0.0);
         g(rain_scale_factor, 1.0); g(snow_scale_factor, 1.0);
-        g(frac_imperv, 0.0); g(frac_imperv_no_store, 0.0);
+        g(frac_imperv, 0.0); g(frac_imperv_no_store, 0.0); g(pct_zero, 0.0);
+        g(subarea_runoff_rate, 0.0);
         g(n_imperv, 0.013); g(n_perv, 0.1);
         g(ds_imperv, 0.0); g(ds_perv, 0.0);
         g(subarea_routing, 0); g(pct_routed, 0.0);
@@ -651,9 +841,12 @@ struct SubcatchData {
         g(infil_p4, 0.0); g(infil_p5, 0.0);
         g(runoff, 0.0); g(rainfall, 0.0);
         g(evap_loss, 0.0); g(infil_loss, 0.0);
-        g(ponded_depth, 0.0); g(gw_flow, 0.0);
+        g(ponded_depth, 0.0); g(old_ponded_depth, 0.0);
+        g(washoff_vout1, 0.0); g(gw_flow, 0.0);
+        g(snow_depth, 0.0); g(lid_drain_flow, 0.0);
         g(old_runoff, 0.0); g(old_gw_flow, 0.0);
-        g(runon_inflow, 0.0); g(old_runon_inflow, 0.0);
+        g(old_snow_depth, 0.0); g(old_lid_drain_flow, 0.0);
+        g(runon_inflow, 0.0); g(old_runon_inflow, 0.0); g(runon_rate, 0.0);
         g(gw_sw_head, 0.0); g(gw_node_avail_flow, 0.0);
         g(gw_max_infil_vol, std::numeric_limits::max());
         g(outfall_runon_vol, 0.0);
@@ -673,10 +866,15 @@ struct SubcatchData {
         stat_gw_steps.resize(un, 0L);
         g(gw_aquifer, -1); g(gw_node, -1); g(gw_surf_elev, 0.0);
         g(gw_a1, 0.0); g(gw_b1, 0.0); g(gw_a2, 0.0); g(gw_b2, 0.0);
-        g(gw_a3, 0.0); g(gw_tw, 0.0); g(gw_hstar, 0.0);
+        g(gw_a3, 0.0); g(gw_tw, 0.0); g(gw_hstar, -1.0e10);
+        g(gw_bot_elev, -1.0e10); g(gw_wt_elev, -1.0e10); g(gw_upper_moist, -1.0e10);
         g(snowpack, -1);
         g(snow_net_imperv, -1.0);
         g(snow_net_perv,   -1.0);
+        g(snow_melt_imperv, -1.0);
+        g(snow_melt_perv,   -1.0);
+        g(snow_melt_age_imperv, -1.0);
+        g(snow_melt_age_perv,   -1.0);
         g(total_lid_area_ft2, 0.0);
         g(lid_return_to_perv_cfs, 0.0);
         g(lid_drain_runon_cfs, 0.0);
@@ -684,6 +882,55 @@ struct SubcatchData {
         // Note: coverage, total_load handled separately
     }
 
+    /**
+     * @brief Reserve capacity for `n` subcatchments without changing count().
+     *
+     * @details Parsing grows these arrays one row at a time via grow_to(),
+     *          so each of the ~76 parallel vectors reallocates and copies
+     *          O(log n) times over a section — the dominant memory traffic in
+     *          handler dispatch on a large model.
+     *
+     *          This reserves capacity only. It deliberately does NOT resize:
+     *          count() is the vector size, and PostParseResolver compares it
+     *          against the final name count and calls resize() when they
+     *          differ — a call with destructive assign semantics. Growing the
+     *          SIZE speculatively here would trip that path and wipe parsed
+     *          data. Capacity is invisible to all of it.
+     *
+     *          Over-reserving is harmless, so callers pass the section's row
+     *          count as an upper bound.
+     */
+    void reserve_to(int n) {
+        if (n <= 0) return;
+        const auto un = static_cast(n);
+        if (outlet_node.capacity() >= un) return;
+        auto r = [&](auto& vec) { vec.reserve(un); };
+        r(outlet_node); r(outlet_subcatch); r(gage); r(area);
+        r(width); r(slope); r(curb_length); r(rain_scale_factor);
+        r(snow_scale_factor); r(frac_imperv); r(frac_imperv_no_store);
+        r(pct_zero); r(subarea_runoff_rate); r(n_imperv);
+        r(n_perv); r(ds_imperv); r(ds_perv); r(subarea_routing);
+        r(pct_routed); r(infil_model); r(infil_p1); r(infil_p2);
+        r(infil_p3); r(infil_p4); r(infil_p5); r(runoff);
+        r(rainfall); r(evap_loss); r(infil_loss); r(ponded_depth);
+        r(gw_flow); r(snow_depth); r(lid_drain_flow); r(old_runoff);
+        r(old_gw_flow); r(old_snow_depth); r(old_lid_drain_flow); r(runon_inflow);
+        r(old_runon_inflow); r(runon_rate); r(gw_sw_head); r(gw_node_avail_flow); r(gw_max_infil_vol);
+        r(outfall_runon_vol); r(rpt_flag); r(stat_precip_vol); r(stat_evap_vol);
+        r(stat_infil_vol); r(stat_imperv_vol); r(stat_perv_vol); r(stat_runoff_vol);
+        r(stat_max_runoff); r(stat_gw_infil_vol); r(stat_gw_upper_evap_vol); r(stat_gw_lower_evap_vol);
+        r(stat_gw_deep_perc_vol); r(stat_gw_flow_vol); r(stat_gw_max_flow); r(stat_gw_sum_theta);
+        r(stat_gw_sum_depth); r(stat_gw_final_theta); r(stat_gw_final_depth); r(gw_aquifer);
+        r(gw_node); r(gw_surf_elev); r(gw_a1); r(gw_b1);
+        r(gw_a2); r(gw_b2); r(gw_a3); r(gw_tw);
+        r(gw_hstar); r(gw_bot_elev); r(gw_wt_elev); r(gw_upper_moist);
+        r(snowpack); r(snow_net_imperv); r(snow_net_perv);
+        r(snow_melt_imperv); r(snow_melt_perv);
+        r(snow_melt_age_imperv); r(snow_melt_age_perv);
+        r(total_lid_area_ft2); r(lid_return_to_perv_cfs); r(lid_drain_runon_cfs); r(outlet_name);
+        r(gage_name); r(comments); r(tags); r(stat_gw_steps);
+    }
+
     /**
      * @brief Erase the subcatchment at index `idx` from every parallel array.
      *
@@ -699,14 +946,16 @@ struct SubcatchData {
         e(outlet_node); e(outlet_subcatch); e(outlet_name); e(gage);
         e(area); e(width); e(slope); e(curb_length);
         e(rain_scale_factor); e(snow_scale_factor);
-        e(frac_imperv); e(frac_imperv_no_store); e(n_imperv); e(n_perv);
+        e(frac_imperv); e(frac_imperv_no_store); e(pct_zero);
+        e(subarea_runoff_rate); e(n_imperv); e(n_perv);
         e(ds_imperv); e(ds_perv); e(subarea_routing); e(pct_routed);
 
         e(infil_model); e(infil_p1); e(infil_p2); e(infil_p3); e(infil_p4); e(infil_p5);
 
         e(runoff); e(rainfall); e(evap_loss); e(infil_loss); e(ponded_depth);
-        e(gw_flow); e(old_runoff); e(old_gw_flow);
-        e(runon_inflow); e(old_runon_inflow); e(outfall_runon_vol);
+        e(gw_flow); e(snow_depth); e(lid_drain_flow);
+        e(old_runoff); e(old_gw_flow); e(old_snow_depth); e(old_lid_drain_flow);
+        e(runon_inflow); e(old_runon_inflow); e(runon_rate); e(outfall_runon_vol);
         e(gw_sw_head); e(gw_node_avail_flow); e(gw_max_infil_vol);
         e(comments); e(tags); e(rpt_flag);
 
@@ -719,7 +968,10 @@ struct SubcatchData {
 
         e(gw_aquifer); e(gw_node); e(gw_surf_elev);
         e(gw_a1); e(gw_b1); e(gw_a2); e(gw_b2); e(gw_a3); e(gw_tw); e(gw_hstar);
+        e(gw_bot_elev); e(gw_wt_elev); e(gw_upper_moist);
         e(snowpack); e(snow_net_imperv); e(snow_net_perv);
+        e(snow_melt_imperv); e(snow_melt_perv);
+        e(snow_melt_age_imperv); e(snow_melt_age_perv);
         e(total_lid_area_ft2); e(lid_return_to_perv_cfs); e(lid_drain_runon_cfs);
 
         // Flat 2D quality arrays: [sc * np + p]
@@ -731,7 +983,8 @@ struct SubcatchData {
                     v.erase(v.begin() + static_cast(base),
                             v.begin() + static_cast(base + np));
             };
-            erase2d(conc); erase2d(conc_old); erase2d(ponded_qual); erase2d(washoff_load);
+            erase2d(conc); erase2d(conc_old); erase2d(init_loading);
+            erase2d(ponded_qual); erase2d(runon_qual_rate); erase2d(washoff_load);
         }
 
         // Flat 2D total load: [sc * np + p]
@@ -767,7 +1020,9 @@ struct SubcatchData {
                          static_cast(n_pollutants);
             conc.assign(total, 0.0);
             conc_old.assign(total, 0.0);
+            init_loading.assign(total, 0.0);
             ponded_qual.assign(total, 0.0);
+            runon_qual_rate.assign(total, 0.0);
             washoff_load.assign(total, 0.0);
         }
     }
@@ -796,6 +1051,8 @@ struct SubcatchData {
         snow_scale_factor.shrink_to_fit();
         frac_imperv.shrink_to_fit();
         frac_imperv_no_store.shrink_to_fit();
+        pct_zero.shrink_to_fit();
+        subarea_runoff_rate.shrink_to_fit();
         n_imperv.shrink_to_fit();
         n_perv.shrink_to_fit();
         ds_imperv.shrink_to_fit();
@@ -816,10 +1073,15 @@ struct SubcatchData {
         infil_loss.shrink_to_fit();
         ponded_depth.shrink_to_fit();
         gw_flow.shrink_to_fit();
+        snow_depth.shrink_to_fit();
+        lid_drain_flow.shrink_to_fit();
         old_runoff.shrink_to_fit();
         old_gw_flow.shrink_to_fit();
+        old_snow_depth.shrink_to_fit();
+        old_lid_drain_flow.shrink_to_fit();
         runon_inflow.shrink_to_fit();
         old_runon_inflow.shrink_to_fit();
+        runon_rate.shrink_to_fit();
         outfall_runon_vol.shrink_to_fit();
         gw_sw_head.shrink_to_fit();
         gw_node_avail_flow.shrink_to_fit();
@@ -848,13 +1110,21 @@ struct SubcatchData {
         gw_a3.shrink_to_fit();
         gw_tw.shrink_to_fit();
         gw_hstar.shrink_to_fit();
+        gw_bot_elev.shrink_to_fit();
+        gw_wt_elev.shrink_to_fit();
+        gw_upper_moist.shrink_to_fit();
         snowpack.shrink_to_fit();
         snow_net_imperv.shrink_to_fit();
         snow_net_perv.shrink_to_fit();
+        snow_melt_imperv.shrink_to_fit();
+        snow_melt_perv.shrink_to_fit();
+        snow_melt_age_imperv.shrink_to_fit();
+        snow_melt_age_perv.shrink_to_fit();
 
         conc.shrink_to_fit();
         conc_old.shrink_to_fit();
         ponded_qual.shrink_to_fit();
+        runon_qual_rate.shrink_to_fit();
         washoff_load.shrink_to_fit();
         total_load.shrink_to_fit();
         coverage.shrink_to_fit();
@@ -865,6 +1135,8 @@ struct SubcatchData {
         std::copy(runoff.begin(),        runoff.end(),        old_runoff.begin());
         std::copy(runon_inflow.begin(),  runon_inflow.end(),  old_runon_inflow.begin());
         std::copy(conc.begin(),          conc.end(),          conc_old.begin());
+        std::copy(ponded_depth.begin(), ponded_depth.end(),
+                  old_ponded_depth.begin());
     }
 
     void reset_state() noexcept {
@@ -872,13 +1144,22 @@ struct SubcatchData {
         std::fill(rainfall.begin(),     rainfall.end(),     0.0);
         std::fill(snow_net_imperv.begin(), snow_net_imperv.end(), -1.0);
         std::fill(snow_net_perv.begin(),   snow_net_perv.end(),   -1.0);
+        std::fill(snow_melt_imperv.begin(), snow_melt_imperv.end(), -1.0);
+        std::fill(snow_melt_perv.begin(),   snow_melt_perv.end(),   -1.0);
+        std::fill(snow_melt_age_imperv.begin(), snow_melt_age_imperv.end(), -1.0);
+        std::fill(snow_melt_age_perv.begin(),   snow_melt_age_perv.end(),   -1.0);
         std::fill(evap_loss.begin(),    evap_loss.end(),    0.0);
         std::fill(infil_loss.begin(),   infil_loss.end(),   0.0);
         std::fill(ponded_depth.begin(), ponded_depth.end(), 0.0);
         std::fill(old_runoff.begin(),   old_runoff.end(),   0.0);
         std::fill(old_gw_flow.begin(),  old_gw_flow.end(),  0.0);
+        std::fill(snow_depth.begin(),   snow_depth.end(),   0.0);
+        std::fill(old_snow_depth.begin(), old_snow_depth.end(), 0.0);
+        std::fill(lid_drain_flow.begin(), lid_drain_flow.end(), 0.0);
+        std::fill(old_lid_drain_flow.begin(), old_lid_drain_flow.end(), 0.0);
         std::fill(runon_inflow.begin(), runon_inflow.end(), 0.0);
         std::fill(old_runon_inflow.begin(), old_runon_inflow.end(), 0.0);
+        std::fill(runon_rate.begin(), runon_rate.end(), 0.0);
         std::fill(gw_sw_head.begin(),   gw_sw_head.end(),   0.0);
         std::fill(gw_node_avail_flow.begin(), gw_node_avail_flow.end(), 0.0);
         std::fill(washoff_load.begin(), washoff_load.end(), 0.0);
diff --git a/src/engine/data/TableData.cpp b/src/engine/data/TableData.cpp
index 9306f17f2..3bd8c21db 100644
--- a/src/engine/data/TableData.cpp
+++ b/src/engine/data/TableData.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TableData.cpp
  * @brief File-backed I/O, cache management, validation, and multicolumn
@@ -12,10 +28,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TableData.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "../core/DateTime.hpp"
 #include "../core/ErrorCodes.hpp"
 #include "../core/charconv_compat.hpp"
@@ -397,11 +414,20 @@ TableValidation validate_table(Table& tbl) {
 // ============================================================================
 // table_open_file
 // ============================================================================
+// NOTE (2026-08-17): this streaming, sliding-cache reader (and its
+// column_ids/column_map/table_lookup_column/table_step_column companions)
+// has no callers. The multi-column series feature was implemented with an
+// eager parse-once cache instead — see src/engine/input/MultiColumnSeriesFile
+// and plans/MULTICOLUMN_SERIES_SINGLE_READ_2026-08-17.md (decision D1):
+// runtime consumers copy their column into their own x/y arrays, so wiring
+// this streaming path would have changed every lookup call site for no
+// footprint win at current model sizes. Left in place per repo guidelines
+// (do not delete pre-existing dead code).
 
 bool table_open_file(Table& tbl, std::size_t boundary_rows) {
     if (tbl.file_path.empty()) return false;
 
-    std::FILE* fp = std::fopen(tbl.file_path.c_str(), "r");
+    std::FILE* fp = openswmm::io::fopen_utf8(tbl.file_path, "r");
     if (!fp) return false;
 
     tbl.file_handle = fp;
diff --git a/src/engine/data/TableData.hpp b/src/engine/data/TableData.hpp
index a2dc49847..164668203 100644
--- a/src/engine/data/TableData.hpp
+++ b/src/engine/data/TableData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TableData.hpp
  * @brief Time series and rating curve data with bidirectional cursor.
@@ -26,13 +42,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TABLE_DATA_HPP
 #define OPENSWMM_ENGINE_TABLE_DATA_HPP
 
 #include "../core/FilePathPair.hpp"
+#include "../core/StringCase.hpp"
 #include 
 #include 
 #include 
@@ -64,7 +81,8 @@ enum class TableType : int {
     CURVE_PUMP2   = 8,  ///< Pump curve type 2 (head vs flow)
     CURVE_PUMP3   = 9,  ///< Pump curve type 3 (volume vs time)
     CURVE_PUMP4   = 10, ///< Pump curve type 4 (depth vs speed)
-    CURVE_PUMP5   = 11  ///< Pump curve type 5 (head vs flow, variable speed)
+    CURVE_PUMP5   = 11, ///< Pump curve type 5 (head vs flow, variable speed)
+    CURVE_WEIR    = 12  ///< Weir rating curve (legacy CurveTypeWords "WEIR")
 };
 
 // ============================================================================
@@ -131,6 +149,20 @@ struct Table {
     std::vector y;       ///< Dependent variable (flow, volume, etc.)
     TableCursor         cursor;  ///< Bidirectional lookup cursor
 
+    // ---- Time-only (relative) timeseries rows ----
+    // Legacy SWMM seeds every timeseries' lastDate with StartDate+StartTime
+    // (input.c:170), so rows authored WITHOUT a date are elapsed times
+    // anchored at the simulation start, until an explicit date re-anchors
+    // the series. The parser counts those leading date-less rows here and
+    // resolve_cross_references() adds options.start_date to exactly those
+    // rows (recording the applied offset in rel_anchor so re-resolution is
+    // idempotent and a later START_DATE change re-anchors by the delta).
+    // InpWriter subtracts rel_anchor to emit the rows back in their
+    // authored time-only form; rows at index >= n_relative are absolute
+    // date/times and are written with explicit dates.
+    int    n_relative = 0;  ///< Leading rows authored as elapsed time-of-start
+    double rel_anchor = 0.0; ///< start_date offset currently baked into them
+
     // ---- File-backed time series support ----
     bool               is_file_based = false; ///< True if data is read from external file
     std::FILE*         file_handle = nullptr;  ///< Open file handle (owned)
@@ -604,11 +636,15 @@ inline double table_getSlope(const Table& tbl, double x_query) noexcept {
         return (dx > 0.0) ? (tbl.y[1] - tbl.y[0]) / dx : 0.0;
     }
 
-    // Use last interval for x above range
-    if (x_query >= tbl.x[n - 1]) {
-        double dx = tbl.x[n - 1] - tbl.x[n - 2];
-        return (dx > 0.0) ? (tbl.y[n - 1] - tbl.y[n - 2]) / dx : 0.0;
-    }
+    // Above the last entry the slope is 0: legacy table_getSlope's scan
+    // runs off the end with x1 = x2 = the last entry (dx == 0 → 0.0). A
+    // head-based pump driven past its curve therefore contributes NO dqdh
+    // to its end nodes' surcharge denominator (session81-small-pump-fm-
+    // model's 5002 at 142 ft of head: the last segment's -15.6 GPM/ft
+    // here kept node 16's Picard update damped where legacy let it run).
+    // Exactly AT the last entry legacy breaks on `x <= x2` with the last
+    // segment bracketed, so that case falls through to the loop.
+    if (x_query > tbl.x[n - 1]) return 0.0;
 
     for (int i = 1; i < n; ++i) {
         if (tbl.x[i] >= x_query) {
@@ -658,6 +694,26 @@ inline double table_getMaxY(const Table& tbl) noexcept {
 struct TableData {
     std::vector tables;  ///< All tables in index order
 
+    /**
+     * @brief Case-insensitive name → table indices, ascending.
+     *
+     * @details Replaces the linear `ieq` scan that find_timeseries() /
+     *          find_curve() used to run over every table. That scan was the
+     *          load path's worst complexity defect: `[TIMESERIES]` and
+     *          `[CURVES]` rows repeat their object's name on every row in
+     *          standard SWMM files, so parsing a model with many long series
+     *          cost O(total_rows x n_tables) string compares before anything
+     *          else happened.
+     *
+     *          A name maps to a *list* because legacy keeps TSERIES and CURVE
+     *          in separate hash tables, so one name may legitimately denote
+     *          both a timeseries and a curve. Lists are in ascending index
+     *          order (add() only appends), which is what makes a hash hit
+     *          return the same winner the old first-match scan did — the
+     *          duplicate-name parity the name-case tests pin.
+     */
+    std::unordered_map, CiHash, CiEqual> by_name;
+
     std::size_t count() const noexcept { return tables.size(); }
 
     Table&       operator[](int idx)       { return tables[static_cast(idx)]; }
@@ -668,8 +724,42 @@ struct TableData {
      * @returns Index of the new table.
      */
     int add(const std::string& id, TableType type) {
-        tables.push_back({id, type, {}, {}, {}});
-        return static_cast(tables.size()) - 1;
+        Table t;
+        t.id   = id;
+        t.type = type;
+        tables.push_back(std::move(t));
+        const int idx = static_cast(tables.size()) - 1;
+        by_name[id].push_back(idx);
+        return idx;
+    }
+
+    /**
+     * @brief Rebuilds by_name from `tables`.
+     * @details Required after any structural change that is not an append —
+     *          in practice only ObjectDeleter's erase-and-renumber, which is
+     *          already O(n). Anything that mutates `tables` directly without
+     *          calling this leaves lookups stale.
+     */
+    void rebuild_index() {
+        by_name.clear();
+        by_name.reserve(tables.size());
+        for (std::size_t i = 0; i < tables.size(); ++i)
+            by_name[tables[i].id].push_back(static_cast(i));
+    }
+
+    /**
+     * @brief Lowest-indexed table with this name and kind; -1 if none.
+     * @param want_timeseries true for TIMESERIES, false for any CURVE_*.
+     */
+    int find_by_kind(std::string_view name, bool want_timeseries) const noexcept {
+        const auto it = by_name.find(name);
+        if (it == by_name.end()) return -1;
+        for (const int i : it->second) {
+            const bool is_ts =
+                tables[static_cast(i)].type == TableType::TIMESERIES;
+            if (is_ts == want_timeseries) return i;
+        }
+        return -1;
     }
 
     /**
diff --git a/src/engine/data/WaterAgeData.hpp b/src/engine/data/WaterAgeData.hpp
new file mode 100644
index 000000000..4d7191828
--- /dev/null
+++ b/src/engine/data/WaterAgeData.hpp
@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeData.hpp
+ * @brief Water-age tracking data (water age plan §1–§2, phase A1a).
+ *
+ * @details Age is the reserved species `__WATER_AGE__` (registry kind
+ *          RESERVED_AGE): zero-order growth d(age)/dt = 1 in every water
+ *          parcel, volume-weighted mixing everywhere water mixes. Internal
+ *          unit is SECONDS (the config file speaks HOURS — ×3600 at
+ *          parse). Per-source initial ages come from the waterage
+ *          component's `[WATER_AGE_SOURCES]` (`model.age`, D-UT8): each
+ *          QualitySolver loader contributes `age_volume = q · age_source`
+ *          to its node, and the transport engine mixes it in exactly like
+ *          a pollutant load.
+ *
+ *          A1a scope: the age species rides the EULERIAN_ARD mesh; the
+ *          LEGACY CSTR age mirror is phase A1b (warned until then);
+ *          watershed/LID/GW age states are A3/A4.
+ *
+ * @ingroup engine_data
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_DATA_WATER_AGE_DATA_HPP
+#define OPENSWMM_ENGINE_DATA_WATER_AGE_DATA_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+/// Source pathways with configurable initial age ([WATER_AGE_SOURCES]).
+/// Order is the storage index of WaterAgeConfigData::global_age.
+enum class WaterAgeSource : int {
+    RAINFALL        = 0,  ///< washoff runoff (and LID drains until A4)
+    DWF             = 1,
+    GW              = 2,
+    RDII            = 3,
+    EXTERNAL_INFLOW = 4,
+    IFACE           = 5,
+    INITIAL_STATE   = 6,  ///< water in the network at t = 0
+    COUNT_          = 7
+};
+
+/**
+ * @brief Parsed `model.age` state (waterage component, phase A1a).
+ *
+ * @details Node-scope overrides are resolved to node indices at apply (the
+ *          rows reference nothing that another component declares, so no
+ *          post-apply resolution pass is needed — unlike E5a's transport
+ *          rows). TIMESERIES ages and SUBCATCH/EDGE_BC scopes are later
+ *          phases and refuse with precise deferral errors.
+ */
+struct WaterAgeConfigData {
+    bool configured = false;
+
+    /// GLOBAL initial age per source, SECONDS (default 0 = fresh water).
+    double global_age[static_cast(WaterAgeSource::COUNT_)] = {};
+
+    // NODE-scope overrides (DWF / EXTERNAL_INFLOW), parallel arrays.
+    std::vector    node_over_source;  ///< WaterAgeSource as int
+    std::vector    node_over_node;    ///< node index
+    std::vector node_over_age;     ///< seconds
+
+    /// Age of `source` water entering `node` (seconds).
+    double source_age(WaterAgeSource s, int node) const noexcept {
+        for (std::size_t i = 0; i < node_over_source.size(); ++i)
+            if (node_over_source[i] == static_cast(s) &&
+                node_over_node[i] == node)
+                return node_over_age[i];
+        return global_age[static_cast(s)];
+    }
+};
+
+/**
+ * @brief Runtime age state shared by the engines (phase A1a).
+ *
+ * @details `node_age_vol_in` is a RATE (age·ft³/s), the age analogue of
+ *          nodes.qual_mass_in — loaders add `q · age_source` and the
+ *          engine integrates it over its substeps. `node_age`/`link_age`
+ *          are the PUBLISHED mean ages (seconds) the API and gates read.
+ */
+/// A3: subarea index within a subcatchment. Matches the RunoffSolver's
+/// three ponded depths (`depth_imperv0/1/perv`, `Runoff.hpp:86-88`) so the
+/// age array can be indexed the same way the water is.
+enum class SubArea : int {
+    IMPERV0 = 0,  ///< impervious, no depression storage
+    IMPERV1 = 1,  ///< impervious with depression storage
+    PERV    = 2,
+    COUNT_  = 3
+};
+
+struct WaterAgeState {
+    std::vector node_age_vol_in;  ///< [node], age·ft³/s
+    std::vector node_age;         ///< [node], seconds
+    std::vector link_age;         ///< [link], seconds
+
+    /// A1b: the LEGACY mirror seeds INITIAL_STATE on its first step
+    /// (the ARD engine seeds at its own init instead).
+    bool legacy_seeded = false;
+
+    // --- A3: watershed age -------------------------------------------
+    /// [subcatch*3 + subarea] mean age of the water ponded on each subarea,
+    /// SECONDS. Per-subarea rather than per-subcatchment (user decision,
+    /// 2026-08-17): impervious water is systematically younger than
+    /// pervious, and the three depths already exist separately.
+    std::vector subarea_age;
+
+    /// [subcatch*3 + subarea] the previous step's stored volume (ft³) —
+    /// the mixing denominator. Kept here rather than recomputed because
+    /// the RunoffSolver overwrites its depths in place.
+    std::vector subarea_vol_prev;
+
+    /// [subcatch] age of the water LEAVING as runoff, SECONDS — the
+    /// volume-weighted mean of the contributing subareas. This is what the
+    /// wet-weather loader delivers to the outlet node, and what run-on
+    /// carries to a downstream subcatchment.
+    std::vector subcatch_runoff_age;
+
+    /// [subcatch] age·ft³/s arriving as RUN-ON from upstream subcatchments,
+    /// the watershed analogue of node_age_vol_in. Without this, run-on
+    /// water arrived with no age at all — the flow path adds q_runon while
+    /// the quality path never did.
+    std::vector subcatch_runon_age_vol_in;
+
+    /// A4: [node] age·ft³/s arriving through LID underdrains, accumulated in
+    /// A6b beside the drain volume and consumed by the wet-weather loader.
+    /// Separate from `node_age_vol_in` because the drain volume has its own
+    /// per-runoff-step lifecycle (`nodes.lid_drain_qual_vol`), and the age
+    /// has to be zeroed and consumed on exactly that cadence or it would be
+    /// counted against a volume from a different step.
+    std::vector node_lid_drain_age_vol_in;
+
+    /// A4: [subcatch] age·ft³ (LID drain) and age·ft³ (outfall) waiting to be
+    /// handed to `subcatch_runon_age_vol_in` when `assembleRunon` converts the
+    /// matching volumes into run-on rates.
+    ///
+    /// A3 filled `subcatch_runon_age_vol_in` from the subcatchment cascade
+    /// ALONE, then divided it by `runon_inflow` — a denominator that also
+    /// carries LID drain water and outfall return flow. A numerator missing
+    /// terms the denominator has does not merely lose precision: it produced
+    /// a run-on age BELOW every source age in the model (3.834 h of arriving
+    /// water under a 4 h rain, with nothing younger than 4 h anywhere). The
+    /// flow path knew about all three contributors; the age path knew about
+    /// one.
+    std::vector subcatch_lid_drain_age_cfs;
+    std::vector subcatch_outfall_age_vol;
+
+    /// Z1 (amendment D-Y4): [node] age (SECONDS) prescribed by an
+    /// [INFLOWS] row naming `__WATER_AGE__`, refreshed by
+    /// InflowSolver::computeAll each routing step; quiet_NaN where no row
+    /// exists. The row is the more specific statement of the node's
+    /// inflow age and WINS over the source table's EXTERNAL_INFLOW entry
+    /// (global or node override) — the conflict is warned at init.
+    std::vector node_ext_inflow_age;
+
+    /// A2a: set by HotStartManager::apply when a V3 file restored ages —
+    /// both engines then seed from node_age/link_age instead of
+    /// INITIAL_STATE (the ARD engine consumes and clears it at init).
+    bool hotstart_loaded = false;
+
+    /// @note `n_subcatch` is deliberately NOT defaulted. A default would
+    ///       let a two-argument call compile and silently empty the
+    ///       watershed arrays at runtime — and every one of the five call
+    ///       sites is guarded by a size mismatch, so the wipe would be
+    ///       repaired by the next `routeSubcatchmentAge` and never show up
+    ///       in any assertion. Requiring the argument moves the trap from
+    ///       runtime to the compiler, which is the only observer that can
+    ///       actually see it.
+    void resize(int n_nodes, int n_links, int n_subcatch) {
+        node_age_vol_in.assign(static_cast(n_nodes), 0.0);
+        node_age.assign(static_cast(n_nodes), 0.0);
+        link_age.assign(static_cast(n_links), 0.0);
+        node_lid_drain_age_vol_in.assign(static_cast(n_nodes), 0.0);
+        // Z1: PRESERVE when already sized. InflowSolver::init sizes and
+        // fills this at open — BEFORE the first routing step's
+        // computeAll — and the loaders' first lazy resize() lands between
+        // that write and its first read. A blanket assign here re-NaN'd
+        // the array and cost the row exactly one routing step of table-
+        // default age (measured: a 4-ULP C5 residue that broke the
+        // Z1 equivalence gate). init() re-asserts NaN on every re-init,
+        // so a removed row cannot leave a stale age behind.
+        if (node_ext_inflow_age.size() != static_cast(n_nodes))
+            node_ext_inflow_age.assign(
+                static_cast(n_nodes),
+                std::numeric_limits::quiet_NaN());
+        const auto ns3 = static_cast(n_subcatch) *
+                         static_cast(SubArea::COUNT_);
+        subarea_age.assign(ns3, 0.0);
+        subarea_vol_prev.assign(ns3, 0.0);
+        subcatch_runoff_age.assign(static_cast(n_subcatch), 0.0);
+        subcatch_runon_age_vol_in.assign(
+            static_cast(n_subcatch), 0.0);
+        subcatch_lid_drain_age_cfs.assign(
+            static_cast(n_subcatch), 0.0);
+        subcatch_outfall_age_vol.assign(
+            static_cast(n_subcatch), 0.0);
+        legacy_seeded   = false;
+        hotstart_loaded = false;
+    }
+    void clear() { *this = WaterAgeState{}; }
+};
+
+}  // namespace openswmm
+
+#endif  // OPENSWMM_ENGINE_DATA_WATER_AGE_DATA_HPP
diff --git a/src/engine/edit/ObjectDeleter.cpp b/src/engine/edit/ObjectDeleter.cpp
index cb3fa2050..5478a85f7 100644
--- a/src/engine/edit/ObjectDeleter.cpp
+++ b/src/engine/edit/ObjectDeleter.cpp
@@ -1,10 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ObjectDeleter.cpp
  * @brief Implementation of object deletion and cascade analysis.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ObjectDeleter.hpp"
@@ -13,6 +29,8 @@
 
 #include 
 #include 
+#include 
+#include 
 #include 
 #include 
 
@@ -37,6 +55,7 @@ static void erase_node_spatial(SimulationContext& ctx, int idx) {
     auto e = [&](auto& v) { if (ui < v.size()) v.erase(v.begin() + static_cast(idx)); };
     e(ctx.spatial.node_x);
     e(ctx.spatial.node_y);
+    e(ctx.spatial.node_has_xy);   // G-X2
 }
 
 static void erase_link_spatial(SimulationContext& ctx, int idx) {
@@ -104,14 +123,7 @@ static bool treatment_stripe_valid(const TreatmentData& T, int node_idx) {
 
 // Erase inlet_usage at idx (all parallel arrays in InletUsageStore)
 static void erase_inlet_usage(SimulationContext& ctx, int idx) {
-    auto& iu = ctx.inlet_usages;
-    const auto ui = static_cast(idx);
-    auto e = [&](auto& v) { if (ui < v.size()) v.erase(v.begin() + static_cast(idx)); };
-    e(iu.link_index); e(iu.design_index); e(iu.node_index); e(iu.num_inlets);
-    e(iu.placement); e(iu.clog_factor); e(iu.flow_limit);
-    e(iu.local_depress); e(iu.local_width); e(iu.street_index);
-    e(iu.stat_capture_vol); e(iu.stat_bypass_vol);
-    e(iu.stat_backflow_vol); e(iu.stat_peak_flow);
+    ctx.inlet_usages.erase_row(idx);
 }
 
 // ============================================================================
@@ -188,9 +200,14 @@ CascadeResult analyze_node_impact(const SimulationContext& ctx, int node_idx) {
             result.add(SWMM_REF_NODE, i, "outfall_route_to", false);
     }
     const int niu = ctx.inlet_usages.count();
-    for (int i = 0; i < niu; ++i) {
-        if (ctx.inlet_usages.node_index[static_cast(i)] == node_idx)
-            result.add(SWMM_REF_INLET_USAGE, i, "node_index", false);
+    for (int i = niu - 1; i >= 0; --i) {
+        const auto uu = static_cast(i);
+        // A node-hosted row IS the inlet junction, and a row whose capture node
+        // disappears has nowhere to send its flow: both go with the node.
+        if (ctx.inlet_usages.node_host[uu] == node_idx)
+            result.add(SWMM_REF_INLET_USAGE, i, "node_host", true);
+        else if (ctx.inlet_usages.node_index[uu] == node_idx)
+            result.add(SWMM_REF_INLET_USAGE, i, "node_index", true);
     }
     for (int i = ctx.ext_inflows.count() - 1; i >= 0; --i)
         if (ctx.ext_inflows.node_idx[static_cast(i)] == node_idx)
@@ -462,13 +479,18 @@ CascadeResult delete_node(SimulationContext& ctx, int node_idx) {
         }
     }
 
-    // --- Step 4: nullify inlet_usage node_index references ---
-    const int niu = ctx.inlet_usages.count();
-    for (int i = 0; i < niu; ++i) {
-        if (ctx.inlet_usages.node_index[static_cast(i)] == node_idx) {
-            ctx.inlet_usages.node_index[static_cast(i)] = -1;
-            result.add(SWMM_REF_INLET_USAGE, i, "node_index", false);
-        }
+    // --- Step 4: cascade-delete inlet_usage rows tied to this node ---
+    // Mirrors the link case (delete_link Step 2): a node-hosted row IS the
+    // inlet junction being deleted, and a row whose capture node is deleted
+    // has nowhere to deliver captured flow. Descending so the erase does not
+    // shift rows still to be visited.
+    for (int i = ctx.inlet_usages.count() - 1; i >= 0; --i) {
+        const auto uu = static_cast(i);
+        const bool hosted  = ctx.inlet_usages.node_host[uu] == node_idx;
+        const bool capture = ctx.inlet_usages.node_index[uu] == node_idx;
+        if (!hosted && !capture) continue;
+        result.add(SWMM_REF_INLET_USAGE, i, hosted ? "node_host" : "node_index", true);
+        erase_inlet_usage(ctx, i);
     }
 
     // --- Step 4b: cascade-delete ext-inflow / DWF / RDII rows for this node ---
@@ -521,6 +543,7 @@ CascadeResult delete_node(SimulationContext& ctx, int node_idx) {
     renumber_refs(ctx.subcatches.outlet_node, node_idx);
     renumber_refs(ctx.node_subtypes.outfalls.route_to, node_idx);
     renumber_refs(ctx.inlet_usages.node_index, node_idx);
+    renumber_refs(ctx.inlet_usages.node_host, node_idx);
     // gw_node in subcatches also references nodes
     renumber_refs(ctx.subcatches.gw_node, node_idx);
     // inflow-row stores also key on node index (rows for node_idx already erased)
@@ -703,6 +726,74 @@ CascadeResult delete_gage(SimulationContext& ctx, int gage_idx) {
     return result;
 }
 
+// ============================================================================
+// DELETE — batches (perf plan Phase A1)
+// ============================================================================
+// Each batch runs the per-object delete above in DESCENDING index order —
+// semantics identical by construction — inside a bulk-remove scope on the
+// name indexes that type can touch, so the name→index map rebuilds ONCE per
+// batch instead of once per delete (the dominant K-delete cost).  The map is
+// stale for the scope's duration; the delete paths are audited to perform no
+// name→index lookups (name_of() reads the vector, which stays exact).
+
+namespace {
+
+/// Scoped begin/end_bulk_remove over the name indexes a batch touches.
+class NameBulkScope {
+public:
+    NameBulkScope(std::initializer_list idxs) : idxs_(idxs) {
+        for (auto* n : idxs_) n->begin_bulk_remove();
+    }
+    ~NameBulkScope() {
+        for (auto* n : idxs_) n->end_bulk_remove();
+    }
+    NameBulkScope(const NameBulkScope&)            = delete;
+    NameBulkScope& operator=(const NameBulkScope&) = delete;
+
+private:
+    std::vector idxs_;
+};
+
+/// Dedupe + sort descending, then apply `del` per index, aggregating entries.
+template 
+CascadeResult delete_many_impl(std::vector indices, DeleteFn&& del) {
+    CascadeResult result;
+    std::sort(indices.begin(), indices.end(), std::greater());
+    indices.erase(std::unique(indices.begin(), indices.end()), indices.end());
+    for (int idx : indices) {
+        CascadeResult r = del(idx);
+        for (auto& e : r.entries) result.entries.push_back(e);
+    }
+    return result;
+}
+
+} // namespace
+
+CascadeResult delete_nodes_many(SimulationContext& ctx, std::vector indices) {
+    // delete_node removes node names AND cascade-deleted link names.
+    NameBulkScope scope{&ctx.node_names, &ctx.link_names};
+    return delete_many_impl(std::move(indices),
+                            [&ctx](int i) { return delete_node(ctx, i); });
+}
+
+CascadeResult delete_links_many(SimulationContext& ctx, std::vector indices) {
+    NameBulkScope scope{&ctx.link_names};
+    return delete_many_impl(std::move(indices),
+                            [&ctx](int i) { return delete_link(ctx, i); });
+}
+
+CascadeResult delete_subcatches_many(SimulationContext& ctx, std::vector indices) {
+    NameBulkScope scope{&ctx.subcatch_names};
+    return delete_many_impl(std::move(indices),
+                            [&ctx](int i) { return delete_subcatch(ctx, i); });
+}
+
+CascadeResult delete_gages_many(SimulationContext& ctx, std::vector indices) {
+    NameBulkScope scope{&ctx.gage_names};
+    return delete_many_impl(std::move(indices),
+                            [&ctx](int i) { return delete_gage(ctx, i); });
+}
+
 // ============================================================================
 // DELETE — table/curve
 // ============================================================================
@@ -802,6 +893,10 @@ CascadeResult delete_table(SimulationContext& ctx, int table_idx) {
 
     // --- Step 2: erase the table entry ---
     ctx.tables.tables.erase(ctx.tables.tables.begin() + static_cast(table_idx));
+    // Every index at or past table_idx just shifted down by one, so the
+    // name→index map is stale. Erase is the only non-append mutation of the
+    // table store, and it is already O(n) from the renumbering below.
+    ctx.tables.rebuild_index();
 
     // Subcatchment adjustment patterns index ctx.tables (see InpWriter tN)
     auto clear_adj = [&](std::vector& v, const char* field) {
@@ -868,14 +963,23 @@ CascadeResult delete_transect(SimulationContext& ctx, int transect_idx) {
     auto erase_ts = [&](auto& v) {
         if (ui < v.size()) v.erase(v.begin() + static_cast(transect_idx));
     };
+    // Lock-step with EVERY parallel array in TransectStore (InfraData.hpp:42)
+    // — missing one here leaves every transect past the deleted index reading
+    // its neighbour's value for that field (comments/encroachments/Lfactor
+    // were missed once and the writer then emitted the wrong Lfactor for all
+    // of them). swmm_transect_remove keeps its own complete copy of this list.
     erase_ts(ctx.transects.names);
+    erase_ts(ctx.transects.comments);
     erase_ts(ctx.transects.n_left);
     erase_ts(ctx.transects.n_right);
     erase_ts(ctx.transects.n_channel);
     erase_ts(ctx.transects.x_left_bank);
     erase_ts(ctx.transects.x_right_bank);
+    erase_ts(ctx.transects.x_left_encroachment);
+    erase_ts(ctx.transects.x_right_encroachment);
     erase_ts(ctx.transects.x_factor);
     erase_ts(ctx.transects.y_factor);
+    erase_ts(ctx.transects.length_factor);
     erase_ts(ctx.transects.stations);
     erase_ts(ctx.transects.elevations);
 
@@ -1388,13 +1492,7 @@ CascadeResult delete_inlet(SimulationContext& ctx, int inlet_idx) {
     }
 
     // --- Step 2: erase the inlet-design row ---
-    {
-        auto& I = ctx.inlets;
-        const auto ui = static_cast(inlet_idx);
-        auto e = [&](auto& v) { if (ui < v.size()) v.erase(v.begin() + static_cast(inlet_idx)); };
-        e(I.names); e(I.inlet_type); e(I.length); e(I.width);
-        e(I.grate_type); e(I.open_area); e(I.splash_veloc);
-    }
+    ctx.inlets.erase_row(inlet_idx);
 
     // --- Step 3: renumber ---
     renumber_refs(ctx.inlet_usages.design_index, inlet_idx);
@@ -1467,6 +1565,26 @@ CascadeResult delete_landuse(SimulationContext& ctx, int landuse_idx) {
         erase_matrix_row(W.bmp_effic,   W.n_landuses, np, landuse_idx);
         --W.n_landuses;
     }
+    // BW-MSX: the reactions-component species' surface parameters share the
+    // land-use dimension ([lu * n_species + m]); re-pack them the same way.
+    {
+        auto& M = ctx.reactions.surface;
+        if (M.n_landuses > landuse_idx && M.n_species > 0) {
+            const int nm = M.n_species;
+            erase_matrix_row(M.bu_type,        M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.bu_c1,          M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.bu_c2,          M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.bu_c3,          M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.bu_normalizer,  M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.bu_max_days,    M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.wo_type,        M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.wo_coeff,       M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.wo_expon,       M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.wo_sweep_effic, M.n_landuses, nm, landuse_idx);
+            erase_matrix_row(M.wo_bmp_effic,   M.n_landuses, nm, landuse_idx);
+            --M.n_landuses;
+        }
+    }
 
     // --- Step 2: erase this landuse's column from subcatch coverage/sweep ---
     {
diff --git a/src/engine/edit/ObjectDeleter.hpp b/src/engine/edit/ObjectDeleter.hpp
index 134101cd1..8ba283111 100644
--- a/src/engine/edit/ObjectDeleter.hpp
+++ b/src/engine/edit/ObjectDeleter.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ObjectDeleter.hpp
  * @brief Internal C++ API for object deletion and cascade analysis.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_OBJECT_DELETER_HPP
@@ -91,6 +107,32 @@ CascadeResult delete_node    (SimulationContext& ctx, int node_idx);
 CascadeResult delete_link    (SimulationContext& ctx, int link_idx);
 CascadeResult delete_subcatch(SimulationContext& ctx, int sc_idx);
 CascadeResult delete_gage    (SimulationContext& ctx, int gage_idx);
+
+/**
+ * @brief Batch deletion — equivalent to sequential per-object deletes in
+ *        DESCENDING index order, with ONE name-index rebuild per batch.
+ *
+ * @details The K-object cost of the per-object path is dominated by
+ *          NameIndex::remove_at rebuilding the whole name→index map per
+ *          delete (K full rehashes over every remaining name).  These run
+ *          the SAME per-object delete code — semantics are identical by
+ *          construction, cascade behaviour included — inside a
+ *          begin/end_bulk_remove() scope on the affected name indexes, so
+ *          the map rebuilds once.  `indices` are deduplicated and sorted
+ *          descending internally (descending also keeps each entry's
+ *          reported index equal to its pre-batch index for the objects
+ *          named in `indices`; cascade entries report indices as the
+ *          sequential-descending equivalent would).  Out-of-range indices
+ *          are the CALLER's job to reject (the C wrapper validates before
+ *          any mutation, keeping the call all-or-nothing).
+ */
+CascadeResult delete_nodes_many     (SimulationContext& ctx, std::vector indices);
+/** @copydoc delete_nodes_many */
+CascadeResult delete_links_many     (SimulationContext& ctx, std::vector indices);
+/** @copydoc delete_nodes_many */
+CascadeResult delete_subcatches_many(SimulationContext& ctx, std::vector indices);
+/** @copydoc delete_nodes_many */
+CascadeResult delete_gages_many     (SimulationContext& ctx, std::vector indices);
 CascadeResult delete_table   (SimulationContext& ctx, int table_idx);
 CascadeResult delete_transect(SimulationContext& ctx, int transect_idx);
 
diff --git a/src/engine/edit/TypeConverter.cpp b/src/engine/edit/TypeConverter.cpp
index b0e8baaed..310a98d57 100644
--- a/src/engine/edit/TypeConverter.cpp
+++ b/src/engine/edit/TypeConverter.cpp
@@ -1,14 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TypeConverter.cpp
  * @brief In-place node and link type conversion.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TypeConverter.hpp"
 #include "../core/TypeHelpers.hpp"
+#include "VirtualJunctionOps.hpp"
 
 namespace openswmm::edit {
 
@@ -101,9 +118,14 @@ ConversionResult convert_node(SimulationContext& ctx, int idx, NodeType new_type
 
     // Converting a virtual junction to any other type clears the virtual
     // flag (the zero-storage contract only exists for JUNCTION-typed nodes).
+    // vj_clear_virtual also promotes the rendering rim depth back to the real
+    // full depth, so the converted node keeps the surface it was drawn at.
+    // An inlet junction also loses its inlet flag and its usage row there.
     if (ui < nd.is_virtual.size() && nd.is_virtual[ui]) {
-        nd.is_virtual[ui] = 0;
+        const bool was_inlet = ui < nd.is_inlet.size() && nd.is_inlet[ui] != 0;
+        vj_clear_virtual(ctx, idx);
         result.cleared_fields.push_back("is_virtual");
+        if (was_inlet) result.cleared_fields.push_back("is_inlet");
     }
 
     // Move the subtype row and set nd.type (single source of truth). Erases the
diff --git a/src/engine/edit/TypeConverter.hpp b/src/engine/edit/TypeConverter.hpp
index b5bacb6c1..8b9469de0 100644
--- a/src/engine/edit/TypeConverter.hpp
+++ b/src/engine/edit/TypeConverter.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TypeConverter.hpp
  * @brief Internal C++ API for in-place node and link type conversion.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TYPE_CONVERTER_HPP
diff --git a/src/engine/edit/VirtualJunctionOps.cpp b/src/engine/edit/VirtualJunctionOps.cpp
index 3a8884fc1..d21166f78 100644
--- a/src/engine/edit/VirtualJunctionOps.cpp
+++ b/src/engine/edit/VirtualJunctionOps.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file VirtualJunctionOps.cpp
  * @brief Virtual-junction rule validation, flag editing, split and fusion.
@@ -6,12 +22,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "VirtualJunctionOps.hpp"
 #include "ObjectDeleter.hpp"
 #include "../core/ErrorCodes.hpp"
+#include "../hydraulics/Link.hpp"
 #include "../input/PostParseResolver.hpp"
 #include "../2d/data/MeshData.hpp"
 
@@ -102,31 +119,34 @@ int vj_rule_violation(const SimulationContext& ctx, int node_idx) {
         std::fabs(offset_at_node(ctx, j2, node_idx)) > VJ_OFFSET_TOL)
         return ERR_VJ_OFFSET;
 
-    // Rule 5: no lateral inflow source may target the node.
-    for (int r = 0; r < ctx.ext_inflows.count(); ++r)
-        if (ctx.ext_inflows.node_idx[static_cast(r)] == node_idx)
-            return ERR_VJ_LATERAL_INFLOW;
-    for (int r = 0; r < ctx.dwf_inflows.count(); ++r)
-        if (ctx.dwf_inflows.node_idx[static_cast(r)] == node_idx)
-            return ERR_VJ_LATERAL_INFLOW;
-    for (int r = 0; r < ctx.rdii_assigns.count(); ++r)
-        if (ctx.rdii_assigns.node_idx[static_cast(r)] == node_idx)
-            return ERR_VJ_LATERAL_INFLOW;
-    for (int s = 0; s < ctx.subcatches.count(); ++s)
-        if (ctx.subcatches.outlet_node[static_cast(s)] == node_idx)
-            return ERR_VJ_LATERAL_INFLOW;
-    {
-        const std::string& name = ctx.node_names.name_of(node_idx);
-        for (const auto& d : ctx.lid_usage.drain_to)
-            if (!d.empty() && d == name)
-                return ERR_VJ_LATERAL_INFLOW;
-    }
+    // Rule 5: no 2D surface coupling. A virtual junction has no opening —
+    // its sealed head cannot pond against the overlying surface — so it
+    // cannot be a coupling point. Every point lateral source ([INFLOWS],
+    // [DWF], RDII, subcatchment outlets, LID drains, interface files, the
+    // runtime API) IS permitted: the dynamic-wave update integrates it at
+    // the zero-storage node and the finite-volume solver splits it into the
+    // two spliced cells (plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md).
     if (ctx.twod_io.mesh != nullptr) {
         const auto& m = *ctx.twod_io.mesh;
-        for (const int n : m.vert_coupled_node)
-            if (n == node_idx) return ERR_VJ_LATERAL_INFLOW;
-        for (const int n : m.tri_coupled_node)
-            if (n == node_idx) return ERR_VJ_LATERAL_INFLOW;
+        // The [2D_*_NODE_MAP] handlers store the node NAME; the index is
+        // resolved only when the surface router initialises, so at post-parse
+        // validation the name is what identifies the coupling point.
+        const auto targets = [&](int stored, const std::string& name) {
+            if (stored >= 0) return stored == node_idx;
+            return !name.empty() && ctx.node_names.find(name) == node_idx;
+        };
+        for (std::size_t v = 0; v < m.vert_coupled_node.size(); ++v) {
+            const std::string& nm = (v < m.vert_coupled_node_name.size())
+                ? m.vert_coupled_node_name[v] : std::string{};
+            if (targets(m.vert_coupled_node[v], nm)) return ERR_VJ_LATERAL_INFLOW;
+        }
+        for (std::size_t t = 0; t < m.tri_coupled_node.size(); ++t) {
+            const std::string& nm = (t < m.tri_coupled_node_name.size())
+                ? m.tri_coupled_node_name[t] : std::string{};
+            if (targets(m.tri_coupled_node[t], nm)) return ERR_VJ_LATERAL_INFLOW;
+        }
+        for (const auto& row : m.tri_couplings)
+            if (targets(row.node, row.node_name)) return ERR_VJ_LATERAL_INFLOW;
     }
 
     return 0;
@@ -143,18 +163,44 @@ void vj_apply_derived_geometry(SimulationContext& ctx, int node_idx) {
     ctx.nodes.full_depth[ui]  = ctx.links.xsect_y_full[static_cast(j1)];
     ctx.nodes.sur_depth[ui]   = 0.0;
     ctx.nodes.ponded_area[ui] = 0.0;
+    // rim_depth is deliberately NOT touched: it is user/split-supplied
+    // rendering data, not derived geometry, and this runs on every load and
+    // every set-virtual.
 }
 
 // ============================================================================
 // vj_set_virtual
 // ============================================================================
 
+void vj_clear_virtual(SimulationContext& ctx, int node_idx) {
+    if (node_idx < 0 || node_idx >= ctx.n_nodes()) return;
+    const auto ui = static_cast(node_idx);
+    if (ui >= ctx.nodes.is_virtual.size() || !ctx.nodes.is_virtual[ui]) return;
+
+    ctx.nodes.is_virtual[ui] = 0;
+    // An inlet junction is a virtual junction, so leaving virtual leaves inlet
+    // too — and its node-hosted usage row goes with it (a row whose host is a
+    // plain junction has no meaning and would fail validation with 633).
+    if (ui < ctx.nodes.is_inlet.size() && ctx.nodes.is_inlet[ui]) {
+        ctx.nodes.is_inlet[ui] = 0;
+        const int row = ctx.inlet_usages.find_by_node_host(node_idx);
+        if (row >= 0) ctx.inlet_usages.erase_row(row);
+    }
+    // The node keeps a real full depth from here on, so the rendering-only
+    // rim becomes it — a junction that was made virtual and then made regular
+    // again gets its max depth back instead of keeping the pipe crown.
+    if (ui < ctx.nodes.rim_depth.size() && ctx.nodes.rim_depth[ui] > 0.0) {
+        ctx.nodes.full_depth[ui] = ctx.nodes.rim_depth[ui];
+        ctx.nodes.rim_depth[ui]  = 0.0;
+    }
+}
+
 int vj_set_virtual(SimulationContext& ctx, int node_idx, bool make_virtual) {
     if (node_idx < 0 || node_idx >= ctx.n_nodes()) return -1;
     const auto ui = static_cast(node_idx);
 
     if (!make_virtual) {
-        ctx.nodes.is_virtual[ui] = 0;
+        vj_clear_virtual(ctx, node_idx);
         return 0;
     }
 
@@ -162,6 +208,19 @@ int vj_set_virtual(SimulationContext& ctx, int node_idx, bool make_virtual) {
     const int code = vj_rule_violation(ctx, node_idx);
     if (code != 0) return code;
 
+    // The full depth is about to be replaced by the derived pipe crown. When
+    // the node carried a taller max depth (a real manhole being converted),
+    // keep it as the rendering rim so the drawn ground surface doesn't drop.
+    // Only the INTERACTIVE path reaches here — an INP load applies the derived
+    // geometry directly, where full_depth is still 0.
+    int j1 = -1, j2 = -1;
+    if (ui < ctx.nodes.rim_depth.size() && ctx.nodes.rim_depth[ui] == 0.0 &&
+        find_attached(ctx, node_idx, j1, j2) >= 1 && j1 >= 0) {
+        const double crown = ctx.links.xsect_y_full[static_cast(j1)];
+        if (ctx.nodes.full_depth[ui] > crown)
+            ctx.nodes.rim_depth[ui] = ctx.nodes.full_depth[ui];
+    }
+
     ctx.nodes.is_virtual[ui] = 1;
     vj_apply_derived_geometry(ctx, node_idx);
     return 0;
@@ -198,6 +257,21 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
     const double e2 = nodes.invert_elev[static_cast(n2)] + links.offset2[uj];
     const double break_invert = e1 + (e2 - e1) * t;
 
+    // --- Break-point rim (rendering only): interpolate the ground surface
+    // between the two end nodes the same way. A virtual junction's full depth
+    // is the pipe crown, so without this every split would punch a hole in the
+    // drawn ground line. Each end contributes its own rim: the rendering rim
+    // when it has one (a chain of splits), else its real full depth.
+    const auto un1 = static_cast(n1);
+    const auto un2 = static_cast(n2);
+    const double d1 = (nodes.rim_depth[un1] > 0.0) ? nodes.rim_depth[un1]
+                                                   : nodes.full_depth[un1];
+    const double d2 = (nodes.rim_depth[un2] > 0.0) ? nodes.rim_depth[un2]
+                                                   : nodes.full_depth[un2];
+    const double r1 = nodes.invert_elev[un1] + d1;
+    const double r2 = nodes.invert_elev[un2] + d2;
+    const double break_rim = r1 + (r2 - r1) * t;
+
     // --- Vertex-aware polyline split point + vertex partition ---
     std::vector px, py;
     px.push_back(ctx.spatial.node_x[static_cast(n1)]);
@@ -247,6 +321,9 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
     nodes.full_depth[uni]  = links.xsect_y_full[uj];
     ctx.spatial.node_x[uni] = sx;
     ctx.spatial.node_y[uni] = sy;
+    if (ctx.spatial.node_has_xy.size() < ctx.spatial.node_x.size())
+        ctx.spatial.node_has_xy.resize(ctx.spatial.node_x.size(), 0);
+    ctx.spatial.node_has_xy[uni] = 1;   // G-X2
 
     // --- New downstream conduit ---
     const int nj = ctx.link_names.add(new_link_name);
@@ -269,6 +346,10 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
     links.xsect_geom3[unj]  = links.xsect_geom3[uj];
     links.xsect_geom4[unj]  = links.xsect_geom4[uj];
     links.xsect_curve[unj]  = links.xsect_curve[uj];
+    // Named cross-section slot (STREET / IRREGULAR / CUSTOM reference the
+    // section BY NAME here). Without it a split STREET conduit loses its
+    // [STREETS] reference and no longer round-trips or resolves a street.
+    links.pump_curve_name[unj] = links.pump_curve_name[uj];
     links.xsect_r_full[unj] = links.xsect_r_full[uj];
     links.xsect_s_full[unj] = links.xsect_s_full[uj];
     links.xsect_s_max[unj]  = links.xsect_s_max[uj];
@@ -310,13 +391,17 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
     }
 
     // Rewire: original keeps the upstream end; new conduit takes the
-    // downstream end and its offset.
-    links.offset1[unj] = 0.0;
+    // downstream end and its offset. An authored 0 at the new junction is
+    // stored WITH the sediment bump of a filled circular section (see
+    // link::filledCircularOffsetBump), as the resolver would have stored it.
+    const double bump = link::filledCircularOffsetBump(
+        links, uj, ctx.state != EngineState::BUILDING);
+    links.offset1[unj] = bump;
     links.offset2[unj] = links.offset2[uj];
     links.node1[unj]   = ni;
     links.node2[unj]   = n2;
     links.node2[uj]    = ni;
-    links.offset2[uj]  = 0.0;
+    links.offset2[uj]  = bump;
 
     // Vertex partition: interior points at cumulative length <= t stay with
     // the original conduit; the rest move to the new conduit.
@@ -344,6 +429,13 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
     if (make_virtual) {
         const int code = vj_set_virtual(ctx, ni, true);
         if (code != 0) { res.err = code; }  // node/link remain as a regular split
+        else {
+            // Carry the interpolated ground surface, but only when it clears
+            // the crown — a rim buried inside the pipe would draw worse than
+            // the crown fallback.
+            const double rim = break_rim - break_invert;
+            if (rim > nodes.full_depth[uni]) nodes.rim_depth[uni] = rim;
+        }
     }
 
     res.new_node_idx = ni;
@@ -449,7 +541,12 @@ int vj_fuse(SimulationContext& ctx, int node_idx, int* surviving_link_out) {
         CD.slope[uur] = slope_from_ends(eu, ed, L);
     }
 
-    // Retire the downstream conduit, then the (now link-free) node.
+    // Retire the downstream conduit, then the (now link-free) node. The node
+    // deletion runs the ordinary cascade: any [INFLOWS]/[DWF]/RDII rows and
+    // treatment stripe attached to the virtual junction are erased, and
+    // subcatchment outlets / LID drains that targeted it are unassigned —
+    // the same outcome as deleting the node outright (documented policy,
+    // plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md).
     edit::delete_link(ctx, dn);
     const int surviving = (up > dn) ? up - 1 : up;
     edit::delete_node(ctx, node_idx);
@@ -460,4 +557,148 @@ int vj_fuse(SimulationContext& ctx, int node_idx, int* surviving_link_out) {
     return 0;
 }
 
+// ============================================================================
+// Inlet junctions
+// ============================================================================
+
+namespace {
+
+/// Rule 623 for one conduit: the cross-section the design needs.
+bool ij_conduit_shape_ok(const SimulationContext& ctx, int link_idx,
+                         bool for_drop_inlet) {
+    if (link_idx < 0 || link_idx >= ctx.n_links()) return false;
+    const XsectShape shape = ctx.links.xsect_shape[static_cast(link_idx)];
+    if (for_drop_inlet)
+        return shape == XsectShape::RECT_OPEN || shape == XsectShape::TRAPEZOIDAL;
+    return shape == XsectShape::STREET_XSECT;
+}
+
+/// True when the design at `design_idx` is a drop inlet (open-channel shapes).
+bool ij_design_is_drop(const SimulationContext& ctx, int design_idx) {
+    if (design_idx < 0 || design_idx >= ctx.inlets.count()) return false;
+    const std::string& t = ctx.inlets.inlet_type[static_cast(design_idx)];
+    return t == "DROP_GRATE" || t == "DROP_CURB";
+}
+
+} // namespace
+
+int ij_host_conduit(const SimulationContext& ctx, int host_kind, int host_idx) {
+    if (host_kind == 0) {
+        if (host_idx < 0 || host_idx >= ctx.n_links()) return -1;
+        return (ctx.links.type[static_cast(host_idx)] == LinkType::CONDUIT)
+                   ? host_idx : -1;
+    }
+    if (host_idx < 0 || host_idx >= ctx.n_nodes()) return -1;
+    int a = -1, b = -1;
+    if (find_attached(ctx, host_idx, a, b) == 0) return -1;
+    if (a >= 0 && ctx.links.node2[static_cast(a)] == host_idx) return a;
+    if (b >= 0 && ctx.links.node2[static_cast(b)] == host_idx) return b;
+    return a;
+}
+
+bool ij_usage_shape_ok(const SimulationContext& ctx, int design_idx, int link_idx) {
+    if (design_idx < 0 || design_idx >= ctx.inlets.count()) return false;
+    if (link_idx < 0 || link_idx >= ctx.n_links()) return false;
+    const std::string& t = ctx.inlets.inlet_type[static_cast(design_idx)];
+    if (t == "CUSTOM") return true;
+    return ij_conduit_shape_ok(ctx, link_idx, ij_design_is_drop(ctx, design_idx));
+}
+
+int ij_rule_violation(const SimulationContext& ctx, int node_idx,
+                      bool for_drop_inlet) {
+    const int code = vj_rule_violation(ctx, node_idx);
+    if (code != 0) return code;
+
+    // vj_rule_violation guarantees exactly two attached conduits here.
+    int j1 = -1, j2 = -1;
+    find_attached(ctx, node_idx, j1, j2);
+    if (!ij_conduit_shape_ok(ctx, j1, for_drop_inlet) ||
+        !ij_conduit_shape_ok(ctx, j2, for_drop_inlet))
+        return ERR_IJ_NOT_STREET;
+    return 0;
+}
+
+int ij_set_inlet(SimulationContext& ctx, int node_idx, bool make_inlet) {
+    if (node_idx < 0 || node_idx >= ctx.n_nodes()) return -1;
+    const auto ui = static_cast(node_idx);
+
+    if (!make_inlet) {
+        if (ui < ctx.nodes.is_inlet.size() && ctx.nodes.is_inlet[ui]) {
+            ctx.nodes.is_inlet[ui] = 0;
+            const int row = ctx.inlet_usages.find_by_node_host(node_idx);
+            if (row >= 0) ctx.inlet_usages.erase_row(row);
+        }
+        return 0;
+    }
+
+    if (ctx.nodes.type[ui] != NodeType::JUNCTION) return -1;
+
+    // Rules first: ij_rule_violation is read-only, so a violated rule leaves
+    // the node exactly as it was instead of stranding it as a virtual junction.
+    const int row = ctx.inlet_usages.find_by_node_host(node_idx);
+    const bool drop = (row >= 0) &&
+        ij_design_is_drop(ctx, ctx.inlet_usages.design_index[static_cast(row)]);
+    const int code = ij_rule_violation(ctx, node_idx, drop);
+    if (code != 0) return code;
+
+    if (!ctx.nodes.is_virtual[ui]) {
+        const int vcode = vj_set_virtual(ctx, node_idx, true);
+        if (vcode != 0) return vcode;
+    }
+    ctx.nodes.is_inlet[ui] = 1;
+    return 0;
+}
+
+SplitResult ij_split_conduit(SimulationContext& ctx, int link_idx, double t,
+                             const std::string& new_node_name,
+                             const std::string& new_link_name,
+                             int design_idx, int capture_node_idx) {
+    SplitResult res;
+    // Both references are validated BEFORE the split so the common failure
+    // modes never disturb the model at all.
+    if (design_idx < 0 || design_idx >= ctx.inlets.count()) {
+        res.err = ERR_IJ_DESIGN;
+        return res;
+    }
+    if (capture_node_idx < 0 || capture_node_idx >= ctx.n_nodes() ||
+        ctx.nodes.is_virtual[static_cast(capture_node_idx)] != 0) {
+        res.err = ERR_IJ_CAPTURE_NODE;
+        return res;
+    }
+
+    res = vj_split_conduit(ctx, link_idx, t, new_node_name, new_link_name, true);
+    if (res.new_node_idx < 0) return res;              // split itself refused
+    const int ni = res.new_node_idx;
+
+    auto undo = [&](int err) {
+        int surviving = -1;
+        vj_fuse(ctx, ni, &surviving);
+        SplitResult failed;
+        failed.err = err;
+        return failed;
+    };
+    if (res.err != 0) return undo(res.err);            // make_virtual rule failed
+
+    // The usage row must exist before ij_set_inlet so rule 623 can tell a drop
+    // inlet from a street inlet.
+    const int row = ctx.inlet_usages.add_row(-1, ni, design_idx, capture_node_idx);
+    const int code = ij_set_inlet(ctx, ni, true);
+    if (code != 0) {
+        ctx.inlet_usages.erase_row(row);
+        return undo(code);
+    }
+    return res;
+}
+
+int ij_fuse(SimulationContext& ctx, int node_idx, int* surviving_link_out) {
+    if (node_idx < 0 || node_idx >= ctx.n_nodes()) return -1;
+    const auto ui = static_cast(node_idx);
+    if (ui >= ctx.nodes.is_inlet.size() || !ctx.nodes.is_inlet[ui]) return -1;
+
+    // vj_fuse merges the pair and deletes the node; delete_node's cascade
+    // erases the node-hosted usage row along with it. A failed fuse leaves the
+    // node, its flag and its row untouched.
+    return vj_fuse(ctx, node_idx, surviving_link_out);
+}
+
 } // namespace openswmm::edit
diff --git a/src/engine/edit/VirtualJunctionOps.hpp b/src/engine/edit/VirtualJunctionOps.hpp
index 8523e2c41..6637c5969 100644
--- a/src/engine/edit/VirtualJunctionOps.hpp
+++ b/src/engine/edit/VirtualJunctionOps.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file VirtualJunctionOps.hpp
  * @brief Internal C++ API for virtual-junction editing: rule validation,
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_VIRTUAL_JUNCTION_OPS_HPP
@@ -34,10 +50,11 @@ namespace openswmm::edit {
  *          (ERR_VJ_LINK_COUNT); identical cross-section — shape, geom1..4,
  *          curve/transect, barrels; roughness may differ
  *          (ERR_VJ_XSECT_MISMATCH); zero offsets at the node (ERR_VJ_OFFSET);
- *          no lateral inflow source targets the node — [INFLOWS], [DWF],
- *          RDII, subcatchment outlets, LID drains, 2D coupling
- *          (ERR_VJ_LATERAL_INFLOW). The routing-model rule is model-level
- *          and checked by PostParseResolver, not here.
+ *          the node is not a 2D surface-coupling point
+ *          (ERR_VJ_LATERAL_INFLOW). Point lateral sources — [INFLOWS],
+ *          [DWF], RDII, subcatchment outlets, LID drains, the runtime API —
+ *          are permitted. The routing-model rule is model-level and checked
+ *          by PostParseResolver, not here.
  *
  * @returns 0 when all rules pass, else the ERR_VJ_* code of the first
  *          violated rule (ErrorCodes.hpp).
@@ -47,16 +64,32 @@ int vj_rule_violation(const SimulationContext& ctx, int node_idx);
 /**
  * @brief Apply the derived-geometry contract to a validated virtual junction:
  *        full depth = pipe crown (xsect y_full), zero surcharge depth,
- *        zero ponded area. The invert is user/split-supplied data.
+ *        zero ponded area. The invert and the rendering-only rim depth are
+ *        user/split-supplied data and are left alone.
  */
 void vj_apply_derived_geometry(SimulationContext& ctx, int node_idx);
 
+/**
+ * @brief Clear a node's virtual flag, promoting its rendering rim depth (if
+ *        any) back to the real full depth.
+ *
+ * @details The single exit from virtual: shared by swmm_node_set_virtual(0)
+ *          and the node type converter, so `J(4 ft) → VJ → J` returns 4 ft
+ *          instead of keeping the pipe crown. A no-op on a non-virtual node.
+ *          An inlet junction is a virtual junction too, so this also clears
+ *          `is_inlet` and drops the node's inlet-usage row — nothing may hold
+ *          a node-hosted usage once the node is a plain junction again.
+ */
+void vj_clear_virtual(SimulationContext& ctx, int node_idx);
+
 /**
  * @brief Set or clear a node's virtual flag.
  *
  * @details Setting runs the full rule check first and applies the derived
- *          geometry on success; the node must be JUNCTION-typed. Clearing
- *          always succeeds for a virtual node.
+ *          geometry on success; the node must be JUNCTION-typed. A max depth
+ *          taller than the pipe crown is carried over as the node's rendering
+ *          rim depth so the drawn ground surface survives the conversion.
+ *          Clearing (vj_clear_virtual) always succeeds for a virtual node.
  *
  * @returns 0 on success, ERR_VJ_* on a violated rule, or -1 for a bad
  *          index / non-junction node.
@@ -105,6 +138,77 @@ SplitResult vj_split_conduit(SimulationContext& ctx, int link_idx, double t,
  */
 int vj_fuse(SimulationContext& ctx, int node_idx, int* surviving_link_out);
 
+// ---------------------------------------------------------------------------
+// Inlet junctions — a virtual junction that also carries a street inlet
+// (plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §2.6).
+// ---------------------------------------------------------------------------
+
+/**
+ * @brief Check the inlet-junction usage rules for a node: every
+ *        virtual-junction rule, then rule 623 — both attached conduits carry
+ *        the cross-section the design needs (STREET_XSECT, or
+ *        RECT_OPEN/TRAPEZOIDAL when @p for_drop_inlet).
+ *
+ * @returns 0 when eligible, else the ERR_VJ_* / ERR_IJ_NOT_STREET code.
+ */
+int ij_rule_violation(const SimulationContext& ctx, int node_idx, bool for_drop_inlet);
+
+/**
+ * @brief The conduit whose cross-section governs an inlet usage row.
+ *
+ * @param host_kind 0 = link host (the conduit itself), 1 = node host (the
+ *                  conduit approaching the inlet junction — `node2 == host` —
+ *                  else the first attached conduit).
+ * @returns The link index, or -1 when there is none.
+ */
+int ij_host_conduit(const SimulationContext& ctx, int host_kind, int host_idx);
+
+/**
+ * @brief Legacy inlet_validate shape rule (inlet.c:498-505): CUSTOM designs
+ *        fit any shape, DROP_* need RECT_OPEN/TRAPEZOIDAL, everything else
+ *        needs STREET_XSECT.
+ */
+bool ij_usage_shape_ok(const SimulationContext& ctx, int design_idx, int link_idx);
+
+/**
+ * @brief Promote a node to an inlet junction or demote it.
+ *
+ * @details Promotion runs @ref ij_rule_violation first (nothing is changed on
+ *          a violation), makes the node virtual when it is not already, and
+ *          sets `is_inlet`. The drop-inlet variant of rule 623 is selected
+ *          from the node's existing usage row when it has one. Demotion clears
+ *          `is_inlet` and erases the node's usage row, leaving a plain virtual
+ *          junction (use @ref vj_set_virtual to go further).
+ *
+ * @returns 0 on success, a rule code on a violation, or -1 for a bad index /
+ *          non-junction node.
+ */
+int ij_set_inlet(SimulationContext& ctx, int node_idx, bool make_inlet);
+
+/**
+ * @brief Split a conduit and make the inserted node an inlet junction with the
+ *        given design and capture node.
+ *
+ * @details @ref vj_split_conduit (make_virtual) followed by the usage row and
+ *          @ref ij_set_inlet. Atomic: any failure after the split is undone
+ *          with @ref vj_fuse and reported through SplitResult::err
+ *          (625 for a bad design, 627 for a bad capture node, else a rule code).
+ */
+SplitResult ij_split_conduit(SimulationContext& ctx, int link_idx, double t,
+                             const std::string& new_node_name,
+                             const std::string& new_link_name,
+                             int design_idx, int capture_node_idx);
+
+/**
+ * @brief Inverse of @ref ij_split_conduit: re-fuse an inlet junction's conduit
+ *        pair. The node deletion inside @ref vj_fuse cascades the node-hosted
+ *        usage row away with the node; a failed fuse changes nothing.
+ *
+ * @returns 0 on success, ERR_VJ_LINK_COUNT when the node is not a through
+ *          two-conduit pair, or -1 when it is not an inlet junction.
+ */
+int ij_fuse(SimulationContext& ctx, int node_idx, int* surviving_link_out);
+
 } // namespace openswmm::edit
 
 #endif /* OPENSWMM_ENGINE_VIRTUAL_JUNCTION_OPS_HPP */
diff --git a/src/engine/hydraulics/AquiferLinkExchange.hpp b/src/engine/hydraulics/AquiferLinkExchange.hpp
new file mode 100644
index 000000000..9e6e997ab
--- /dev/null
+++ b/src/engine/hydraulics/AquiferLinkExchange.hpp
@@ -0,0 +1,97 @@
+/**
+ * @file AquiferLinkExchange.hpp
+ * @brief G-X4 (2026-09-20) — the signed conduit ⇄ two-zone-aquifer
+ *        conductance law, shared by the two places that compute a conduit's
+ *        seepage rate (DynamicWave's fused kernel and
+ *        routing::computeConduitLosses for KINWAVE / STEADY / FV).
+ *
+ * @details Legacy SWMM gives a conduit a one-way seepage LOSS at a fixed
+ *          rate: `q = K · W · L`, an assumed unit gradient, whatever the
+ *          groundwater does. With a `[2D_AQUIFER]` under the conduit and
+ *          `LINK_SEEPAGE TWO_WAY`, that becomes a MODFLOW-River exchange
+ *          about the conduit's own invert:
+ *
+ *              h_link = z_inv + depth                     (water surface)
+ *              h_eff  = max(h_gw, z_inv)                  (bottom clamp)
+ *              Q      = K · W · L · min((h_link − h_eff)/d_c, 1)
+ *
+ *          `+` is out of the pipe, the sign the whole engine already uses
+ *          for `seep_loss_rate`, so a gaining reach is simply a negative
+ *          seepage. The three properties that matter:
+ *
+ *          1. **It reproduces legacy exactly where legacy is right.** With
+ *             the table at or below the invert and the pipe full
+ *             (`depth ≥ d_c`, whose default IS the conduit's full depth),
+ *             the factor is 1 and the rate is the legacy `K · W · L` to the
+ *             bit. This is MODFLOW's disconnected-stream limit: once the
+ *             aquifer head falls below the bed, the leakage saturates.
+ *          2. **It is continuous through the water table.** A rising table
+ *             throttles the loss smoothly to zero and then reverses.
+ *          3. **The gain is bounded by the aquifer, not by the pipe.**
+ *             `gw_gain_max` is the aquifer's frozen per-step share of the
+ *             drainable water in the cells the conduit crosses, so the 1D
+ *             can never take water the 2D does not have — the same
+ *             budget-then-deliver rule the node exchange uses (G-X1).
+ *
+ *          The publisher (SurfaceRouter2D, before routing) owns the datum:
+ *          it hands over the table elevation already relative to the
+ *          conduit's mid invert, so neither loss site needs node inverts or
+ *          the mesh datum.
+ */
+#ifndef OPENSWMM_ENGINE_HYDRAULICS_AQUIFER_LINK_EXCHANGE_HPP
+#define OPENSWMM_ENGINE_HYDRAULICS_AQUIFER_LINK_EXCHANGE_HPP
+
+#include 
+#include 
+
+#include "../core/SimulationContext.hpp"
+
+namespace openswmm::hydraulics {
+
+/**
+ * @brief The signed multiplier on `K · W · L` for an aquifer-coupled conduit.
+ *
+ * @param depth       water depth in the conduit (project length units).
+ * @param gw_head_rel water-table elevation minus the conduit's mid invert
+ *                    (project length units; negative = table under the pipe).
+ * @param d_c         bed thickness / characteristic path (project length).
+ * @returns `> 0` losing, `< 0` gaining, `1.0` exactly the legacy loss.
+ */
+inline double aquiferSeepFactor(double depth, double gw_head_rel,
+                                double d_c) noexcept {
+    if (!(d_c > 0.0)) return 1.0;                  // no path length: legacy
+    const double h_eff = (gw_head_rel > 0.0) ? gw_head_rel : 0.0;
+    return std::min((depth - h_eff) / d_c, 1.0);
+}
+
+/**
+ * @brief Apply the aquifer's per-step gain budget to a signed seepage rate.
+ *
+ * @param seep_rate signed rate for ONE barrel (project flow units).
+ * @param gain_max  the cap on the gaining direction, one barrel, `≥ 0`.
+ */
+inline double capAquiferGain(double seep_rate, double gain_max) noexcept {
+    return (seep_rate < -gain_max) ? -gain_max : seep_rate;
+}
+
+/**
+ * @brief Apply a host's `swmm_forcing_link_seepage` to a conduit's rate.
+ *
+ * @details OVERRIDE replaces the computed exchange, ADD superimposes one —
+ *          the same two modes every other forcing channel offers. The sign
+ *          convention is `seep_loss_rate`'s: `+` out of the conduit.
+ */
+inline void applySeepageForcing(const SimulationContext& ctx, std::size_t link,
+                                double& seep_rate) noexcept {
+    const auto& f = ctx.forcing;
+    if (link >= f.link_seepage_mode.size()) return;
+    switch (f.link_seepage_mode[link]) {
+        case ForcingMode::OVERRIDE: seep_rate  = f.link_seepage_value[link]; break;
+        case ForcingMode::ADD:      seep_rate += f.link_seepage_value[link]; break;
+        default: break;
+    }
+}
+
+}  // namespace openswmm::hydraulics
+
+#endif  // OPENSWMM_ENGINE_HYDRAULICS_AQUIFER_LINK_EXCHANGE_HPP
diff --git a/src/engine/hydraulics/Culvert.cpp b/src/engine/hydraulics/Culvert.cpp
index 55d6ddb40..f69817371 100644
--- a/src/engine/hydraulics/Culvert.cpp
+++ b/src/engine/hydraulics/Culvert.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Culvert.cpp
  * @brief Culvert inlet control — numerically identical to legacy culvert.c.
@@ -5,12 +21,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Culvert.hpp"
-#include "HydClosureKernels.hpp"
-#include "../core/SimulationContext.hpp"
+#include "XSectBatch.hpp"
+#include "XSectKernels.hpp"
+#include "../core/Constants.hpp"
+#include "../math/FindRoot.hpp"
 #include 
 #include 
 
@@ -22,178 +40,224 @@ namespace culvert {
 /// Each entry stores {K, M, C, Y} (FORM is handled via the code ranges).
 static const CulvertCoeffs COEFFS[] = {
     // 0: unused
-    {0.0,    0.0,   0.0,    0.00},
+    {0.0, 0.0,    0.0,   0.0,    0.00},
 
     // Circular concrete
-    {0.0098, 2.00,  0.0398, 0.67},   //  1: Square edge w/headwall
-    {0.0018, 2.00,  0.0292, 0.74},   //  2: Groove end w/headwall
-    {0.0045, 2.00,  0.0317, 0.69},   //  3: Groove end projecting
+    {1.0, 0.0098, 2.00,  0.0398, 0.67},   //  1: Square edge w/headwall
+    {1.0, 0.0018, 2.00,  0.0292, 0.74},   //  2: Groove end w/headwall
+    {1.0, 0.0045, 2.00,  0.0317, 0.69},   //  3: Groove end projecting
 
     // Circular Corrugated Metal Pipe
-    {0.0078, 2.00,  0.0379, 0.69},   //  4: Headwall
-    {0.0210, 1.33,  0.0463, 0.75},   //  5: Mitered to slope
-    {0.0340, 1.50,  0.0553, 0.54},   //  6: Projecting
+    {1.0, 0.0078, 2.00,  0.0379, 0.69},   //  4: Headwall
+    {1.0, 0.0210, 1.33,  0.0463, 0.75},   //  5: Mitered to slope
+    {1.0, 0.0340, 1.50,  0.0553, 0.54},   //  6: Projecting
 
     // Circular Pipe, Beveled Ring Entrance
-    {0.0018, 2.50,  0.0300, 0.74},   //  7: Beveled ring, 45 deg bevels
-    {0.0018, 2.50,  0.0243, 0.83},   //  8: Beveled ring, 33.7 deg bevels
+    {1.0, 0.0018, 2.50,  0.0300, 0.74},   //  7: Beveled ring, 45 deg bevels
+    {1.0, 0.0018, 2.50,  0.0243, 0.83},   //  8: Beveled ring, 33.7 deg bevels
 
     // Rectangular Box with Flared Wingwalls
-    {0.026,  1.0,   0.0347, 0.81},   //  9: 30-75 deg wingwall flares
-    {0.061,  0.75,  0.0400, 0.80},   // 10: 90 or 15 deg wingwall flares
-    {0.061,  0.75,  0.0423, 0.82},   // 11: 0 deg wingwall flares (straight sides)
+    {1.0, 0.026,  1.0,   0.0347, 0.81},   //  9: 30-75 deg wingwall flares
+    {1.0, 0.061,  0.75,  0.0400, 0.80},   // 10: 90 or 15 deg wingwall flares
+    {1.0, 0.061,  0.75,  0.0423, 0.82},   // 11: 0 deg wingwall flares (straight sides)
 
     // Rectangular Box with Flared Wingwalls & Top Edge Bevel
-    {0.510,  0.667, 0.0309, 0.80},   // 12: 45 deg flare; 0.43D top edge bevel
-    {0.486,  0.667, 0.0249, 0.83},   // 13: 18-33.7 deg flare; 0.083D top edge bevel
+    {2.0, 0.510,  0.667, 0.0309, 0.80},   // 12: 45 deg flare; 0.43D top edge bevel
+    {2.0, 0.486,  0.667, 0.0249, 0.83},   // 13: 18-33.7 deg flare; 0.083D top edge bevel
 
     // Rectangular Box; 90-deg Headwall; Chamfered or Beveled Inlet Edges
-    {0.515,  0.667, 0.0375, 0.79},   // 14: chamfered 3/4-in
-    {0.495,  0.667, 0.0314, 0.82},   // 15: beveled 1/2-in/ft at 45 deg (1:1)
-    {0.486,  0.667, 0.0252, 0.865},  // 16: beveled 1-in/ft at 33.7 deg (1:1.5)
+    {2.0, 0.515,  0.667, 0.0375, 0.79},   // 14: chamfered 3/4-in
+    {2.0, 0.495,  0.667, 0.0314, 0.82},   // 15: beveled 1/2-in/ft at 45 deg (1:1)
+    {2.0, 0.486,  0.667, 0.0252, 0.865},  // 16: beveled 1-in/ft at 33.7 deg (1:1.5)
 
     // Rectangular Box; Skewed Headwall; Chamfered or Beveled Inlet Edges
-    {0.545,  0.667, 0.04505,0.73},   // 17: 3/4" chamfered edge, 45 deg skewed headwall
-    {0.533,  0.667, 0.0425, 0.705},  // 18: 3/4" chamfered edge, 30 deg skewed headwall
-    {0.522,  0.667, 0.0402, 0.68},   // 19: 3/4" chamfered edge, 15 deg skewed headwall
-    {0.498,  0.667, 0.0327, 0.75},   // 20: 45 deg beveled edge, 10-45 deg skewed headwall
+    {2.0, 0.545,  0.667, 0.04505,0.73},   // 17: 3/4" chamfered edge, 45 deg skewed headwall
+    {2.0, 0.533,  0.667, 0.0425, 0.705},  // 18: 3/4" chamfered edge, 30 deg skewed headwall
+    {2.0, 0.522,  0.667, 0.0402, 0.68},   // 19: 3/4" chamfered edge, 15 deg skewed headwall
+    {2.0, 0.498,  0.667, 0.0327, 0.75},   // 20: 45 deg beveled edge, 10-45 deg skewed headwall
 
     // Rectangular box, Non-offset Flared Wingwalls; 3/4" Chamfer at Top of Inlet
-    {0.497,  0.667, 0.0339, 0.803},  // 21: 45 deg (1:1) wingwall flare
-    {0.493,  0.667, 0.0361, 0.806},  // 22: 18.4 deg (3:1) wingwall flare
-    {0.495,  0.667, 0.0386, 0.71},   // 23: 18.4 deg (3:1) wingwall flare, 30 deg inlet skew
+    {2.0, 0.497,  0.667, 0.0339, 0.803},  // 21: 45 deg (1:1) wingwall flare
+    {2.0, 0.493,  0.667, 0.0361, 0.806},  // 22: 18.4 deg (3:1) wingwall flare
+    {2.0, 0.495,  0.667, 0.0386, 0.71},   // 23: 18.4 deg (3:1) wingwall flare, 30 deg inlet skew
 
     // Rectangular box, Offset Flared Wingwalls, Beveled Edge at Inlet Top
-    {0.497,  0.667, 0.0302, 0.835},  // 24: 45 deg (1:1) flare, 0.042D top edge bevel
-    {0.495,  0.667, 0.0252, 0.881},  // 25: 33.7 deg (1.5:1) flare, 0.083D top edge bevel
-    {0.493,  0.667, 0.0227, 0.887},  // 26: 18.4 deg (3:1) flare, 0.083D top edge bevel
+    {2.0, 0.497,  0.667, 0.0302, 0.835},  // 24: 45 deg (1:1) flare, 0.042D top edge bevel
+    {2.0, 0.495,  0.667, 0.0252, 0.881},  // 25: 33.7 deg (1.5:1) flare, 0.083D top edge bevel
+    {2.0, 0.493,  0.667, 0.0227, 0.887},  // 26: 18.4 deg (3:1) flare, 0.083D top edge bevel
 
     // Corrugated Metal Box
-    {0.0083, 2.00,  0.0379, 0.69},   // 27: 90 deg headwall
-    {0.0145, 1.75,  0.0419, 0.64},   // 28: Thick wall projecting
-    {0.0340, 1.50,  0.0496, 0.57},   // 29: Thin wall projecting
+    {1.0, 0.0083, 2.00,  0.0379, 0.69},   // 27: 90 deg headwall
+    {1.0, 0.0145, 1.75,  0.0419, 0.64},   // 28: Thick wall projecting
+    {1.0, 0.0340, 1.50,  0.0496, 0.57},   // 29: Thin wall projecting
 
     // Horizontal Ellipse Concrete
-    {0.0100, 2.00,  0.0398, 0.67},   // 30: Square edge w/headwall
-    {0.0018, 2.50,  0.0292, 0.74},   // 31: Grooved end w/headwall
-    {0.0045, 2.00,  0.0317, 0.69},   // 32: Grooved end projecting
+    {1.0, 0.0100, 2.00,  0.0398, 0.67},   // 30: Square edge w/headwall
+    {1.0, 0.0018, 2.50,  0.0292, 0.74},   // 31: Grooved end w/headwall
+    {1.0, 0.0045, 2.00,  0.0317, 0.69},   // 32: Grooved end projecting
 
     // Vertical Ellipse Concrete
-    {0.0100, 2.00,  0.0398, 0.67},   // 33: Square edge w/headwall
-    {0.0018, 2.50,  0.0292, 0.74},   // 34: Grooved end w/headwall
-    {0.0095, 2.00,  0.0317, 0.69},   // 35: Grooved end projecting
+    {1.0, 0.0100, 2.00,  0.0398, 0.67},   // 33: Square edge w/headwall
+    {1.0, 0.0018, 2.50,  0.0292, 0.74},   // 34: Grooved end w/headwall
+    {1.0, 0.0095, 2.00,  0.0317, 0.69},   // 35: Grooved end projecting
 
     // Pipe Arch, 18" Corner Radius, Corrugated Metal
-    {0.0083, 2.00,  0.0379, 0.69},   // 36: 90 deg headwall
-    {0.0300, 1.00,  0.0463, 0.75},   // 37: Mitered to slope
-    {0.0340, 1.50,  0.0496, 0.57},   // 38: Projecting
+    {1.0, 0.0083, 2.00,  0.0379, 0.69},   // 36: 90 deg headwall
+    {1.0, 0.0300, 1.00,  0.0463, 0.75},   // 37: Mitered to slope
+    {1.0, 0.0340, 1.50,  0.0496, 0.57},   // 38: Projecting
 
     // Pipe Arch, 18" Corner Radius, Corrugated Metal (cont.)
-    {0.0300, 1.50,  0.0496, 0.57},   // 39: Projecting
-    {0.0088, 2.00,  0.0368, 0.68},   // 40: No bevels
-    {0.0030, 2.00,  0.0269, 0.77},   // 41: 33.7 deg bevels
+    {1.0, 0.0300, 1.50,  0.0496, 0.57},   // 39: Projecting
+    {1.0, 0.0088, 2.00,  0.0368, 0.68},   // 40: No bevels
+    {1.0, 0.0030, 2.00,  0.0269, 0.77},   // 41: 33.7 deg bevels
 
     // Pipe Arch, 31" Corner Radius, Corrugated Metal
-    {0.0300, 1.50,  0.0496, 0.57},   // 42: Projecting
-    {0.0088, 2.00,  0.0368, 0.68},   // 43: No bevels
-    {0.0030, 2.00,  0.0269, 0.77},   // 44: 33.7 deg bevels
+    {1.0, 0.0300, 1.50,  0.0496, 0.57},   // 42: Projecting
+    {1.0, 0.0088, 2.00,  0.0368, 0.68},   // 43: No bevels
+    {1.0, 0.0030, 2.00,  0.0269, 0.77},   // 44: 33.7 deg bevels
 
     // Arch, Corrugated Metal
-    {0.0083, 2.00,  0.0379, 0.69},   // 45: 90 deg headwall
-    {0.0300, 1.00,  0.0473, 0.75},   // 46: Mitered to slope
-    {0.0340, 1.50,  0.0496, 0.57},   // 47: Thin wall projecting
+    {1.0, 0.0083, 2.00,  0.0379, 0.69},   // 45: 90 deg headwall
+    {1.0, 0.0300, 1.00,  0.0473, 0.75},   // 46: Mitered to slope
+    {1.0, 0.0340, 1.50,  0.0496, 0.57},   // 47: Thin wall projecting
 
     // Circular Culvert
-    {0.534,  0.555, 0.0196, 0.90},   // 48: Smooth tapered inlet throat
-    {0.519,  0.640, 0.0210, 0.90},   // 49: Rough tapered inlet throat
+    {2.0, 0.534,  0.555, 0.0196, 0.90},   // 48: Smooth tapered inlet throat
+    {2.0, 0.519,  0.640, 0.0210, 0.90},   // 49: Rough tapered inlet throat
 
     // Elliptical Inlet Face
-    {0.536,  0.622, 0.0368, 0.83},   // 50: Tapered inlet, beveled edges
-    {0.5035, 0.719, 0.0478, 0.80},   // 51: Tapered inlet, square edges
-    {0.547,  0.800, 0.0598, 0.75},   // 52: Tapered inlet, thin edge projecting
+    {2.0, 0.536,  0.622, 0.0368, 0.83},   // 50: Tapered inlet, beveled edges
+    {2.0, 0.5035, 0.719, 0.0478, 0.80},   // 51: Tapered inlet, square edges
+    {2.0, 0.547,  0.800, 0.0598, 0.75},   // 52: Tapered inlet, thin edge projecting
 
     // Rectangular
-    {0.475,  0.667, 0.0179, 0.97},   // 53: Tapered inlet throat
+    {2.0, 0.475,  0.667, 0.0179, 0.97},   // 53: Tapered inlet throat
 
     // Rectangular Concrete
-    {0.560,  0.667, 0.0446, 0.85},   // 54: Side tapered, less favorable edges
-    {0.560,  0.667, 0.0378, 0.87},   // 55: Side tapered, more favorable edges
+    {2.0, 0.560,  0.667, 0.0446, 0.85},   // 54: Side tapered, less favorable edges
+    {2.0, 0.560,  0.667, 0.0378, 0.87},   // 55: Side tapered, more favorable edges
 
     // Rectangular Concrete
-    {0.500,  0.667, 0.0446, 0.65},   // 56: Slope tapered, less favorable edges
-    {0.500,  0.667, 0.0378, 0.71},   // 57: Slope tapered, more favorable edges
+    {2.0, 0.500,  0.667, 0.0446, 0.65},   // 56: Slope tapered, less favorable edges
+    {2.0, 0.500,  0.667, 0.0378, 0.71},   // 57: Slope tapered, more favorable edges
 };
 static constexpr int MAX_CULVERT_CODE = 57;
 static constexpr int N_COEFFS = sizeof(COEFFS) / sizeof(COEFFS[0]);
 
-/// Determine the FHWA equation form for a culvert code.
-/// Form 1 codes: 1-8, 27-47 (legacy Params[][FORM] == 1.0).
-/// Form 2 codes: 9-26, 48-57 (legacy Params[][FORM] == 2.0).
-static int getForm(int code) {
-    if (code >= 1 && code <= 8)   return 1;
-    if (code >= 27 && code <= 47) return 1;
-    // codes 9-26 and 48-57 are form 2
-    return 2;
-}
-
 CulvertCoeffs getCoeffs(int code) {
     if (code >= 1 && code <= MAX_CULVERT_CODE) return COEFFS[code];
     return COEFFS[0];
 }
 
-double getInflow(double q_proposed, double head, double y_full,
-                 double a_full, double slope, int code, double& dqdh) {
-    // The curve itself lives in HydClosureKernels.hpp, portable to the device
-    // backend, which is where the FV solver applies it (as a cap on the flux
-    // crossing the culvert's upstream face). This entry point resolves the
-    // type code and hands over.
-    const CulvertCoeffs cc = getCoeffs(code);
-    const hydkernels::CulvertCurve curve{cc.K, cc.M, cc.C, cc.Y};
-    // Mitered inlet codes, per legacy culvert.c's switch.
-    const bool mitered = (code == 5 || code == 37 || code == 46);
-    return hydkernels::culvertInflow(q_proposed, head, y_full, a_full, slope,
-                                     curve, mitered, dqdh);
+// ---------------------------------------------------------------------------
+// legacy culvert.c, op for op. The unsubmerged Form-1 flow comes out of
+// Ridder's method on form1Eqn: the flow is whatever the LAST evaluation of
+// form1Eqn left in qc (the root itself is discarded), so the root finder has
+// to call the equation in legacy's exact sequence (findroot::ridder).
+// ---------------------------------------------------------------------------
+namespace {
+
+constexpr double BIG = 1.0e10;   // legacy consts.h
+
+struct TCulvert {
+    double yFull = 0.0;   // full depth of culvert (ft)
+    double scf   = 0.0;   // slope correction factor
+    double dQdH  = 0.0;   // derivative of flow w.r.t. head
+    double qc    = 0.0;   // unsubmerged critical flow
+    double kk = 0.0, mm = 0.0;   // coeffs. for unsubmerged flow
+    double ad    = 0.0;
+    double hPlus = 0.0;   // intermediate terms
+    const XSectParams* xsect = nullptr;
+};
+
+// h/yFull + 0.5*s = yc/yFull + yh/2/yFull + K[ac/aFull*sqrt(g*yh/yFull)]^M
+double form1Eqn(double yc, TCulvert* culvert) {
+    const double ac = xsect::getAofY(*culvert->xsect, yc);
+    const double wc = xsect::getWofY(*culvert->xsect, yc);
+    const double yh = ac / wc;
+    culvert->qc = ac * std::sqrt(constants::GRAVITY * yh);
+    return culvert->hPlus - yc / culvert->yFull - yh / 2.0 / culvert->yFull -
+           culvert->kk * std::pow(culvert->qc / culvert->ad, culvert->mm);
 }
 
-void batchComputeInletControl(const int* link_indices, int n,
-                               SimulationContext& ctx) {
-    auto& links = ctx.links;
-    auto& nodes = ctx.nodes;
-
-    for (int ii = 0; ii < n; ++ii) {
-        int j = link_indices[ii];
-
-        // Only process conduit links with a valid culvert code
-        if (links.type[j] != LinkType::CONDUIT) continue;
-        auto& CD = ctx.link_subtypes.conduits;
-        const auto ucr = static_cast(ctx.link_subtypes.conduit_row(j));
-        int code = CD.culvert_code[ucr];
-        if (code <= 0 || code > MAX_CULVERT_CODE) continue;
-
-        // Gather parameters
-        double y_full = links.xsect_y_full[j];
-        double a_full = links.xsect_a_full[j];
-        double s      = CD.slope[ucr];
-        double q0     = links.flow[j];
-
-        // Compute upstream head above culvert invert
-        int n1 = links.node1[j];
-        double head = nodes.head[n1]
-                     - (nodes.invert_elev[n1] + links.offset1[j]);
-
-        // Compute inlet-controlled flow
-        double dq = 0.0;
-        double q_inlet = getInflow(std::fabs(q0), head, y_full, a_full, s,
-                                   code, dq);
-
-        // Inlet controls only if q_inlet < |q0|
-        if (q_inlet < std::fabs(q0)) {
-            CD.inlet_control[ucr] = uint8_t{1};
-            links.dqdh[j] = dq;  // dqdh stays on base LinkData
-            // Preserve flow sign (direction)
-            links.flow[j] = (q0 >= 0.0) ? q_inlet : -q_inlet;
-        }
+double getForm1Flow(double h, TCulvert* culvert) {
+    culvert->hPlus = h / culvert->yFull + culvert->scf;
+    // Ridder's method between 0.01h and h; the result is culvert->qc
+    findroot::ridder(0.01 * h, h, 0.001,
+                     [culvert](double yc) { return form1Eqn(yc, culvert); });
+    return culvert->qc;
+}
+
+double getUnsubmergedFlow(const CulvertCoeffs& P, double h, TCulvert* culvert) {
+    culvert->kk = P.K;
+    culvert->mm = P.M;
+    const double arg = h / culvert->yFull / culvert->kk;
+    double q;
+    if (P.form == 1.0) q = getForm1Flow(h, culvert);
+    else               q = culvert->ad * std::pow(arg, 1.0 / culvert->mm);
+    culvert->dQdH = q / h / culvert->mm;
+    return q;
+}
+
+double getSubmergedFlow(const CulvertCoeffs& P, double h, TCulvert* culvert) {
+    const double cc = P.C;
+    const double yy = P.Y;
+    const double arg = (h / culvert->yFull - yy + culvert->scf) / cc;
+    if (arg <= 0.0) {
+        culvert->dQdH = 0.0;
+        return BIG;
+    }
+    const double q = std::sqrt(arg) * culvert->ad;
+    culvert->dQdH = 0.5 * q / arg / culvert->yFull / cc;
+    return q;
+}
+
+double getTransitionFlow(const CulvertCoeffs& P, double h, double h1, double h2,
+                         TCulvert* culvert) {
+    const double q1 = getUnsubmergedFlow(P, h1, culvert);
+    const double q2 = getSubmergedFlow(P, h2, culvert);
+    const double q = q1 + (q2 - q1) * (h - h1) / (h2 - h1);
+    culvert->dQdH = (q2 - q1) / (h2 - h1);
+    return q;
+}
+
+} // namespace
+
+double getInflow(double q0, double y, const XSectParams& xs, double slope,
+                 int code, double& dqdh, bool& controls) {
+    controls = false;
+    if (code <= 0 || code > MAX_CULVERT_CODE) return q0;
+    const CulvertCoeffs P = COEFFS[code];
+
+    TCulvert culvert;
+    culvert.xsect = &xs;
+    culvert.yFull = xs.y_full;
+    culvert.ad    = xs.a_full * std::sqrt(culvert.yFull);
+
+    // slope correction factor (-7 for mitered inlets, 0.5 for others)
+    switch (code) {
+        case 5: case 37: case 46: culvert.scf = -7.0 * slope; break;
+        default:                  culvert.scf =  0.5 * slope;
+    }
+
+    double q;
+    // submerged flow (FHWA criterion Q/AD > 4)
+    const double y2 = culvert.yFull * (16.0 * P.C + P.Y - culvert.scf);
+    if (y >= y2) {
+        q = getSubmergedFlow(P, y, &culvert);
+    } else {
+        // unsubmerged below the arbitrary 0.95-full limit, transition between
+        const double y1 = 0.95 * culvert.yFull;
+        if (y <= y1) q = getUnsubmergedFlow(P, y, &culvert);
+        else         q = getTransitionFlow(P, y, y1, y2, &culvert);
+    }
+
+    if (q < q0) {
+        controls = true;
+        dqdh = culvert.dQdH;
+        return q;
     }
+    return q0;
 }
 
 } // namespace culvert
diff --git a/src/engine/hydraulics/Culvert.hpp b/src/engine/hydraulics/Culvert.hpp
index 8e0f53ea5..83eca2227 100644
--- a/src/engine/hydraulics/Culvert.hpp
+++ b/src/engine/hydraulics/Culvert.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Culvert.hpp
  * @brief Culvert inlet control — FHWA HEC-5 equations.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CULVERT_HPP
@@ -25,11 +41,14 @@
 namespace openswmm {
 
 struct SimulationContext;
+struct XSectParams;
 
 namespace culvert {
 
-/// Culvert curve coefficients (K, M, C, Y) per type code.
+/// Culvert curve coefficients per type code — legacy culvert.c Params[]:
+/// the FHWA equation FORM (1 or 2) and K, M, C, Y.
 struct CulvertCoeffs {
+    double form = 0.0;
     double K = 0.0;
     double M = 0.0;
     double C = 0.0;
@@ -40,29 +59,25 @@ struct CulvertCoeffs {
 CulvertCoeffs getCoeffs(int culvert_code);
 
 /**
- * @brief Compute culvert inlet-controlled inflow.
- *
- * @param q_proposed  Proposed flow from routing (cfs).
- * @param head        Upstream head above invert (ft).
- * @param y_full      Full depth of culvert (ft).
- * @param a_full      Full area (ft2).
- * @param slope       Conduit slope.
- * @param code        Culvert type code.
- * @param[out] dqdh   Derivative dQ/dH.
- * @returns Inlet-controlled flow (cfs). If < q_proposed, inlet controls.
- */
-double getInflow(double q_proposed, double head, double y_full,
-                 double a_full, double slope, int code, double& dqdh);
-
-/**
- * @brief Batch compute culvert inlet control for all culvert links.
+ * @brief legacy culvert_getInflow (culvert.c): FHWA HDS-5 inlet-controlled
+ *        flow through a culvert, as the dynamic wave applies it inside
+ *        dwflow_findConduitFlow once per iteration.
  *
- * @param link_indices  Indices of culvert links.
- * @param n             Number of culvert links.
- * @param ctx           Simulation context.
+ * @param q0     The conduit's dynamic-wave flow (cfs, positive).
+ * @param y      Upstream head above the culvert's upstream invert (ft):
+ *               legacy `h - (Node[n1].invertElev + Link.offset1)`.
+ * @param xs     The culvert's cross section (form1Eqn evaluates its area and
+ *               top width at the trial critical depth).
+ * @param slope  Conduit slope (the slope correction factor).
+ * @param code   Culvert type code (1-57).
+ * @param[out] dqdh      Legacy culvert.dQdH — replaces the link's dqdh when
+ *                       the inlet controls.
+ * @param[out] controls  TRUE when the inlet flow is below q0 (legacy
+ *                       Link.inletControl).
+ * @returns The inlet flow when it is below q0, else q0.
  */
-void batchComputeInletControl(const int* link_indices, int n,
-                               SimulationContext& ctx);
+double getInflow(double q0, double y, const XSectParams& xs, double slope,
+                 int code, double& dqdh, bool& controls);
 
 } // namespace culvert
 } // namespace openswmm
diff --git a/src/engine/hydraulics/Divider.cpp b/src/engine/hydraulics/Divider.cpp
index e86c0841c..9c8b003ba 100644
--- a/src/engine/hydraulics/Divider.cpp
+++ b/src/engine/hydraulics/Divider.cpp
@@ -1,11 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Divider.cpp
- * @brief Flow divider — numerically identical to legacy node.c divider logic.
+ * @brief Flow divider node logic — legacy-faithful divider_getOutflow.
+ *
  * @ingroup new_engine
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Divider.hpp"
@@ -17,66 +34,75 @@
 namespace openswmm {
 namespace divider {
 
-void computeDividerFlows(SimulationContext& ctx, const DividerData& divs) {
-    double ucf_flow = ucf::Qcf[static_cast(ctx.options.flow_units)];
+/// Legacy FLOW_TOL (consts.h): minimum signficant flow, cfs.
+static constexpr double FLOW_TOL = 0.00001;
 
-    for (int k = 0; k < divs.count(); ++k) {
-        auto uk = static_cast(k);
-        int ni = divs.node_idx[uk];
-        if (ni < 0 || ni >= ctx.n_nodes()) continue;
-        auto uni = static_cast(ni);
+double getOutflow(SimulationContext& ctx, int node_idx, int link_idx) {
+    // Legacy node.c divider_getOutflow(j, k). Requires links be routed so the
+    // non-diversion link is evaluated before the diversion link (the topo sort
+    // guarantees it, as in legacy).
+    const int r = ctx.node_subtypes.divider_row(node_idx);
+    if (r < 0) return 0.0;
+    const auto ur = static_cast(r);
+    const auto& divs = ctx.node_subtypes.dividers;
+    const auto un = static_cast(node_idx);
 
-        double q_total = ctx.nodes.inflow[uni];
-        if (q_total <= 0.0) continue;
+    const double ucf_flow =
+        ucf::Qcf[static_cast(ctx.options.flow_units)];
 
-        double q_divert = 0.0;
-        auto dm = static_cast(static_cast(divs.method[uk]));
+    const double qIn = ctx.nodes.inflow[un] + ctx.nodes.overflow[un];
+    const int div_link = divs.link[ur];
+    double qOut = 0.0;
 
-        switch (dm) {
-            case DividerMethod::CUTOFF: {
-                // Diversion gets flow above cutoff
-                double qmin = divs.cutoff[uk];
-                q_divert = std::max(0.0, q_total - qmin);
-                break;
-            }
-            case DividerMethod::OVERFLOW_DIV: {
-                // Diversion gets flow exceeding primary link capacity
-                // (primary link capacity = q_full of non-diversion link)
-                // For now: divert excess above node full volume rate
-                double full_depth = ctx.nodes.full_depth[uni];
-                double q_primary = full_depth > 0.0
-                    ? q_total * (full_depth / (full_depth + 1.0)) : q_total;
-                q_divert = std::max(0.0, q_total - q_primary);
-                break;
-            }
-            case DividerMethod::TABULAR: {
-                // Lookup diversion fraction from curve
-                int ti = divs.curve[uk];
-                if (ti >= 0 && ti < static_cast(ctx.tables.tables.size())) {
-                    double frac = table_lookup_cursor(ctx.tables.tables[static_cast(ti)], q_total * ucf_flow);
-                    q_divert = q_total * std::max(0.0, std::min(1.0, frac));
-                }
-                break;
-            }
-            case DividerMethod::WEIR: {
-                // Weir equation: Q = Cd * W * H^1.5
-                double depth = ctx.nodes.depth[uni];
-                double cd = divs.cd[uk];
-                double w = divs.max_depth[uk];  // weir width
-                if (depth > 0.0 && cd > 0.0 && w > 0.0) {
-                    q_divert = cd * w * depth * std::sqrt(depth);
-                    q_divert = std::min(q_divert, q_total);
-                }
-                break;
+    switch (static_cast(static_cast(divs.method[ur]))) {
+        case DividerMethod::CUTOFF:
+            // cutoff holds qMin, pre-converted to internal flow units
+            if (qIn <= divs.cutoff[ur]) qOut = 0.0;
+            else qOut = qIn - divs.cutoff[ur];
+            break;
+
+        case DividerMethod::OVERFLOW_DIV:
+            // Non-diversion link simply carries the node's inflow; the
+            // diversion link receives the excess of inflow over what was
+            // already sent into the non-diversion link (node.c:1265-1273).
+            if (link_idx != div_link) qOut = qIn;
+            else qOut = qIn - ctx.nodes.outflow[un];
+            if (qOut < FLOW_TOL) qOut = 0.0;
+            return qOut;
+
+        case DividerMethod::WEIR: {
+            // cutoff = qMin (internal units); max_depth = dhMax and
+            // cd = cWeir stay in USER units (legacy node.c:192-194).
+            const double qMin  = divs.cutoff[ur];
+            const double dhMax = divs.max_depth[ur];
+            const double cWeir = divs.cd[ur];
+            // qMax derived as in legacy divider_validate (node.c:1227)
+            const double qMax = cWeir * std::pow(dhMax, 1.5) / ucf_flow;
+            if (qIn <= qMin) qOut = 0.0;
+            else {
+                const double f = (qIn - qMin) / (qMax - qMin);
+                if (f > 1.0) qOut = qMax * std::sqrt(f);
+                else qOut = cWeir * std::pow(f * dhMax, 1.5) / ucf_flow;
             }
+            break;
         }
 
-        // Apply diversion: set diversion link flow
-        int dl = divs.link[uk];
-        if (dl >= 0 && dl < ctx.n_links()) {
-            ctx.links.flow[static_cast(dl)] = q_divert;
+        case DividerMethod::TABULAR: {
+            const int m = divs.curve[ur];
+            if (m >= 0 && m < static_cast(ctx.tables.tables.size()))
+                qOut = table_lookup_cursor(
+                           ctx.tables.tables[static_cast(m)],
+                           qIn * ucf_flow) / ucf_flow;
+            else qOut = 0.0;
+            break;
         }
     }
+
+    // Outflow cannot exceed inflow; a non-diversion link carries the
+    // undiverted remainder (node.c:1305-1312).
+    if (qOut > qIn) qOut = qIn;
+    if (link_idx != div_link) qOut = qIn - qOut;
+    return qOut;
 }
 
 } // namespace divider
diff --git a/src/engine/hydraulics/Divider.hpp b/src/engine/hydraulics/Divider.hpp
index 6bdf3c1d3..ea3df9f34 100644
--- a/src/engine/hydraulics/Divider.hpp
+++ b/src/engine/hydraulics/Divider.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Divider.hpp
  * @brief Flow divider node logic — cutoff, overflow, tabular, weir.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_DIVIDER_HPP
@@ -39,22 +55,22 @@ enum class DividerMethod : int {
 };
 
 /**
- * @brief Compute diversion flows for all divider nodes.
- *
- * @details For each divider:
- *   - Reads total inflow at the divider node
- *   - Computes diversion flow based on method
- *   - Sets diversion link flow and reduces primary link flow
+ * @brief Flow sent from a divider node into one of its outflow links.
  *
- *   Reads the relational DividerData side-table (ctx.node_subtypes.dividers),
- *   which replaces the former standalone DividerSoA. The data is identical
- *   (same dividers, same node-index order, same fields) so results are
- *   unchanged; the side-table is simply the single source of truth.
+ * @details Legacy-faithful divider_getOutflow (node.c:1237-1312): the
+ *          diversion link receives the diverted portion of the node's
+ *          inflow + overflow per the divider method; any other outflow
+ *          link receives the undiverted remainder. Requires links be
+ *          routed in topological order so the non-diversion link is
+ *          evaluated before the diversion link (OVERFLOW dividers read
+ *          the node's accumulated outflow).
  *
- * @param ctx   Simulation context.
- * @param divs  Divider side-table (ctx.node_subtypes.dividers).
+ * @param ctx       Simulation context.
+ * @param node_idx  Divider node index.
+ * @param link_idx  Outflow link being evaluated.
+ * @returns         Flow rate into the link (internal flow units).
  */
-void computeDividerFlows(SimulationContext& ctx, const DividerData& divs);
+double getOutflow(SimulationContext& ctx, int node_idx, int link_idx);
 
 } // namespace divider
 } // namespace openswmm
diff --git a/src/engine/hydraulics/DynamicWave.cpp b/src/engine/hydraulics/DynamicWave.cpp
index b766bdceb..73556c8b6 100644
--- a/src/engine/hydraulics/DynamicWave.cpp
+++ b/src/engine/hydraulics/DynamicWave.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DynamicWave.cpp
  * @brief Dynamic wave routing -- batch-oriented St. Venant equations.
@@ -11,7 +27,10 @@
  *      - Slot area/width/hrad overrides for surcharged depths
  *
  *   2. solveMomentumBatch() -- pure array arithmetic over ALL links:
- *      - velocity = old_flow / area_mid (vectorisable)
+ *      - velocity = old_flow / conveyArea(area_mid) -- the Preissmann slot is
+ *        storage, not conveyance, so it is stripped from every momentum term
+ *        (velocity, aWtd, dq3/dq4, local losses) while node continuity and
+ *        link volume keep the slot-inclusive area. Issue #144.
  *      - Froude from velocity and hydraulic depth (vectorisable)
  *      - sigma (inertial damping) from Froude (vectorisable)
  *      - full inertial damping when closed conduit is surcharged
@@ -31,18 +50,21 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DynamicWave.hpp"
 #include "Node.hpp"
 #include "Outfall.hpp"
 #include "XSectBatch.hpp"
+#include "Link.hpp"
 #include "ForceMain.hpp"
 #include "Culvert.hpp"
+#include "AquiferLinkExchange.hpp"   // G-X4
 #include "../core/Constants.hpp"
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
+#include "../core/ThreadInfo.hpp"
 #include "../math/SIMD.hpp"
 
 #include 
@@ -60,11 +82,10 @@ static inline int omp_get_num_threads() { return 1; }
 static inline int omp_get_thread_num()  { return 0; }
 #endif
 
-// Darwin/Apple-Silicon scheduling helpers (see setNumThreads / execute):
-// sysctl for the performance-core count, pthread QoS to keep team threads
-// off the efficiency cores.
+// Darwin/Apple-Silicon scheduling helper (see execute): pthread QoS to keep
+// team threads off the efficiency cores. The P-core count query lives in
+// core/ThreadInfo.
 #if defined(__APPLE__)
-#include 
 #include 
 #include 
 #endif
@@ -88,76 +109,81 @@ using constants::FUDGE;
 
 double DWSolver::getCrownCutoff() const {
     if (surcharge_method == SurchargeMethod::SLOT ||
-        surcharge_method == SurchargeMethod::DYNAMIC_SLOT)
+        surcharge_method == SurchargeMethod::DYNAMIC_SLOT ||
+        surcharge_method == SurchargeMethod::TPA)
         return SLOT_CROWN_CUTOFF;
     return EXTRAN_CROWN_CUTOFF;
 }
 
 /**
- * @brief Compute Preissmann slot width at depth y.
- *
- * @details Matches legacy dwflow.c::getSlotWidth():
- *   - Returns 0 if SLOT method not used, shape is open, or y/yFull < cutoff
- *   - For y/yFull > 1.78: slot width = 1% of max width
- *   - Otherwise: Sjoberg formula: wMax * 0.5423 * exp(-yNorm^2.4)
- *
- * When EXTRAN method is used: slot width = y_full / 1000 (constant)
+ * @brief Legacy xsect_isOpen(): a shape is open iff its Amax entry is 1.0
+ * (xsect.c:59-85, 215) — DUMMY, RECT_OPEN, TRAPEZOIDAL, TRIANGULAR,
+ * PARABOLIC, POWERFUNC, IRREGULAR and STREET. Every other shape has a crown.
  */
-double DWSolver::getSlotWidth(double y, double y_full, double w_max,
-                              XsectShape shape) const {
-    if (y_full <= 0.0) return 0.0;
-
-    // Open shapes (trapezoidal, triangular, rectangular open, parabolic)
-    // never use a slot -- they have no crown
-    bool is_open = (shape == XsectShape::RECT_OPEN ||
-                    shape == XsectShape::TRAPEZOIDAL ||
-                    shape == XsectShape::TRIANGULAR ||
-                    shape == XsectShape::PARABOLIC);
-    if (is_open) return 0.0;
-
-    double yNorm = y / y_full;
-
-    if (surcharge_method == SurchargeMethod::SLOT) {
-        if (yNorm < SLOT_CROWN_CUTOFF) return 0.0;
-        // For depth > 1.78 * pipe depth, slot width = 1% of max width
-        if (yNorm > 1.78) return 0.01 * w_max;
-        // Sjoberg formula: pow(yNorm, 2.4) = yNorm^2 * yNorm^0.4
-        // Use cbrt(yNorm^2) = yNorm^(2/3), then yNorm^0.4 = (yNorm^2)^0.2
-        // Faster: yNorm^2.4 = yNorm^2 * yNorm^(2/5) = yNorm^2 * sqrt(cbrt(yNorm^2))
-        double y2 = yNorm * yNorm;
-        return w_max * 0.5423 * std::exp(-y2 * std::sqrt(std::cbrt(y2)));
-    }
-
-    // EXTRAN method: no slot — surcharge uses dQ/dH in node depth solver.
-    // Legacy getSlotWidth() returns 0.0 when SurchargeMethod != SLOT.
-    return 0.0;
+static bool isOpenShape(XsectShape shape) {
+    switch (shape) {
+        case XsectShape::DUMMY:
+        case XsectShape::RECT_OPEN:
+        case XsectShape::TRAPEZOIDAL:
+        case XsectShape::TRIANGULAR:
+        case XsectShape::PARABOLIC:
+        case XsectShape::POWER:
+        case XsectShape::IRREGULAR:
+        case XsectShape::STREET_XSECT:
+            return true;
+        default:
+            return false;
+    }
 }
 
 /**
- * @brief Compute flow area including Preissmann slot contribution.
+ * @brief Compute Preissmann slot width at depth y.
  *
- * @details Matches legacy dwflow.c::getArea():
- *   - If y >= y_full: A = A_full + (y - y_full) * slot_width
- *   - Otherwise: standard cross-section area (from batch)
+ * @details Op-for-op legacy dwflow.c::getSlotWidth():
+ *   - 0 if the SLOT method is not in use, the shape is open (legacy
+ *     xsect_isOpen), or y/yFull < CrownCutoff (0.985257 under SLOT)
+ *   - y/yFull > 1.78: 1% of the max width
+ *   - otherwise the Sjoberg formula wMax * 0.5423 * exp(-pow(yNorm, 2.4)).
+ *     `pow` is the same libm call legacy makes; a former rewrite as
+ *     yNorm^2 * sqrt(cbrt(yNorm^2)) evaluated yNorm^(7/3), not yNorm^2.4.
+ * DYNAMIC_SLOT and TPA are v6 extensions with their own geometry; they take
+ * legacy's "not SLOT" branch here (0).
  */
-double DWSolver::getSlotArea(double y, double y_full, double a_full,
-                             double slot_width) const {
-    if (y >= y_full && slot_width > 0.0) {
-        return a_full + (y - y_full) * slot_width;
-    }
-    return a_full;  // caller should use batch area for y < y_full
+double DWSolver::getSlotWidth(double y, double y_full, double w_max,
+                              XsectShape shape) const {
+    if (surcharge_method != SurchargeMethod::SLOT) return 0.0;
+    if (y_full <= 0.0 || isOpenShape(shape)) return 0.0;
+    const double yNorm = y / y_full;
+    if (yNorm < SLOT_CROWN_CUTOFF) return 0.0;
+    if (yNorm > 1.78) return 0.01 * w_max;
+    return w_max * 0.5423 * std::exp(-std::pow(yNorm, 2.4));
 }
 
 /**
- * @brief Compute hydraulic radius including Preissmann slot.
+ * @brief Strip the Preissmann slot from a flow area, leaving conveyance area.
  *
- * @details Matches legacy dwflow.c::getHydRad():
- *   - If y >= y_full: return R_full (hydraulic radius stays at full value)
- *   - Otherwise: standard hydraulic radius (from batch)
+ * @details The slot is a fictitious gap above the crown that supplies a finite
+ * free-surface top width so the Saint-Venant system stays hyperbolic once a
+ * conduit pressurizes. It stores water but conveys none, so the momentum
+ * equation — velocity, friction, inertial terms, local losses — must use the
+ * closed-section area. This mirrors the hydraulic-radius clamp to `r_full`
+ * applied in STEP E and in `applyDPSGeometry()`, which excludes the slot from
+ * the wetted perimeter on exactly the same reasoning.
+ *
+ * Node continuity (`surf_area1/2_`, `width_mid_`) and link storage
+ * (`links.volume`) deliberately keep the slot-inclusive area — that is where
+ * the slot does its work, and where the water it holds is booked. Clamping
+ * the volume too would delete water the node-depth solve already absorbed.
+ * See issue #144 and plans/PREISSMANN_SLOT_VELOCITY_ISSUE_2026-08-22.md.
+ *
+ * Covers both surcharge methods: the static Sjoberg slot (STEP E) and DPS,
+ * whose `applyDPSGeometry()` writes `area_mid_ = a_full + As`.
+ *
+ * Off the slot path this is the identity — an open shape or EXTRAN never
+ * produces an area above `a_full`.
  */
-double DWSolver::getSlotHydRad(double y, double y_full, double r_full) const {
-    if (y >= y_full) return r_full;
-    return r_full;  // caller should use batch hrad for y < y_full
+static inline double conveyArea(double a, double a_full) {
+    return (a > a_full) ? a_full : a;
 }
 
 // ============================================================================
@@ -254,6 +280,104 @@ void DWSolver::applyDPSGeometry(SimulationContext& ctx) {
     }
 }
 
+// ============================================================================
+// TPA (issue #156 Phase 5) — latch update + geometry override
+// ============================================================================
+
+// Once per routing step, BEFORE the Picard loop, from last-committed state:
+// the operator stays fixed within the iteration (mirrors how DPS advances its
+// state outside the iteration). Vent rule carries P4's SUBMERGENCE lesson:
+// air enters only where a VENTED node's water level sits below the pipe crown
+// at that end — a submerged connection holds the column. Sealed = virtual
+// junction or SUR_DEPTH > 0. Column separation at yMid < y_full − 30 ft
+// clears unconditionally (documented two-phase limitation).
+void DWSolver::updateTpaLatch(SimulationContext& ctx) {
+    const auto& links = ctx.links;
+    const auto& nodes = ctx.nodes;
+    constexpr double kCavHead = 30.0;   // ft, mirrors the FV closure
+    for (int ci = 0; ci < n_conduits_; ++ci) {
+        const auto uci = static_cast(ci);
+        const int j = conduit_idx_[uci];
+        const auto uj = static_cast(j);
+        tpa_latch_changed_[uci] = 0;
+        if (is_open_[uj]) { tpa_latch_[uci] = 0; continue; }
+        const double yf = links.xsect_y_full[uj];
+        if (yf <= 0.0) { tpa_latch_[uci] = 0; continue; }
+        const double y1 = depth1_[uj];
+        const double y2 = depth2_[uj];
+        const uint8_t old = tpa_latch_[uci];
+        uint8_t latched = old;
+        if (!old) {
+            // Set when the conduit reaches full — the same condition that
+            // engages the slot branch today (TPA plan §B2).
+            latched = (y1 >= yf && y2 >= yf) ? uint8_t{1} : uint8_t{0};
+        } else {
+            const double yMid = depth_mid_[uj];
+            if (yMid < yf - kCavHead) {
+                latched = 0;   // column separation
+            } else {
+                // Clear on atmosphere contact: a vented end whose level is
+                // below the crown AT THAT END.
+                auto vented_end = [&](int n, double y_end) -> bool {
+                    if (n < 0) return false;
+                    const auto un2 = static_cast(n);
+                    const bool sealed =
+                        (un2 < nodes.is_virtual.size() &&
+                         nodes.is_virtual[un2] != 0) ||
+                        (un2 < nodes.sur_depth.size() &&
+                         nodes.sur_depth[un2] > 0.0);
+                    return !sealed && y_end < yf;
+                };
+                if (vented_end(links.node1[uj], y1) ||
+                    vented_end(links.node2[uj], y2))
+                    latched = 0;
+            }
+        }
+        tpa_latch_[uci] = latched;
+        tpa_latch_changed_[uci] = (latched != old) ? uint8_t{1} : uint8_t{0};
+    }
+}
+
+// DPS-style geometry override (called where applyDPSGeometry is): engaged
+// when latched OR above the crown cutoff (memoryless above the crown — the
+// latch only matters below it). Area rides the SIGNED slot line
+// A = A_full + w_tpa·(y − y_full) — "shrinkage" for sub-atmospheric heads —
+// width is the constant w_tpa, the hydraulic radius stays r_full (the slot
+// carries no wetted perimeter), and both ends contribute slot surface area
+// to node continuity (the latch keeps sealed heads meaningful).
+void DWSolver::applyTpaGeometry(SimulationContext& ctx) {
+    auto& links = ctx.links;
+    for (int ci = 0; ci < n_conduits_; ++ci) {
+        const auto uci = static_cast(ci);
+        const int j = conduit_idx_[uci];
+        const auto uj = static_cast(j);
+        if (is_open_[uj]) continue;
+        const double yf = links.xsect_y_full[uj];
+        const double af = links.xsect_a_full[uj];
+        const double rf = links.xsect_r_full[uj];
+        if (yf <= 0.0 || af <= 0.0) continue;
+        const double w = tpa_w_[uci];
+        if (w <= 0.0) continue;
+        const double yMid = depth_mid_[uj];
+        const bool engaged = (tpa_latch_[uci] != 0) ||
+                             (yMid >= SLOT_CROWN_CUTOFF * yf);
+        if (!engaged) continue;
+
+        auto line_area = [&](double y) {
+            return std::max(af + w * (y - yf), 0.05 * af);
+        };
+        area_mid_[uj] = line_area(yMid);
+        area1_[uj]    = line_area(depth1_[uj]);
+        area2_[uj]    = line_area(depth2_[uj]);
+        width_mid_[uj] = w;
+        const double L = cached_length_[uj];
+        const double slot_surf_per_end = 0.25 * w * L;  // (w+w)·L/4 convention
+        surf_area1_[uj] = slot_surf_per_end;
+        surf_area2_[uj] = slot_surf_per_end;
+        hrad_mid_[uj] = rf;   // slot/elastic area carries no wetted perimeter
+    }
+}
+
 // ============================================================================
 // DPS post-Picard state update — P decay, surcharge tracking
 // Sharior et al. (2023) Eqs. 22, 23
@@ -396,6 +520,61 @@ void DWSolver::init(int n_nodes, int n_links, const XSectGroups& groups,
     auto un = static_cast(n_nodes);
     auto ul = static_cast(n_links);
 
+    // Unsteady-friction cross-link stencil (issue #156): see the member
+    // comment in DynamicWave.hpp. Topology is static, so build once.
+    if (unsteady_friction != 0) {
+        uf_nb_up_.assign(ul, -1);
+        uf_nb_dn_.assign(ul, -1);
+        uf_sg_up_.assign(ul, 0);
+        uf_sg_dn_.assign(ul, 0);
+        // Per-node incidence: count of incident CONDUITS (any other link
+        // type attached disqualifies the node as a "simple" pass-through),
+        // plus the first two conduit indices.
+        std::vector ccount(un, 0), other(un, 0);
+        std::vector> inc(un, {-1, -1});
+        for (int j = 0; j < n_links; ++j) {
+            const auto ujj = static_cast(j);
+            const bool is_cond = (ctx.links.type[ujj] == LinkType::CONDUIT);
+            for (const int nd : {ctx.links.node1[ujj], ctx.links.node2[ujj]}) {
+                if (nd < 0 || nd >= n_nodes) continue;
+                const auto und = static_cast(nd);
+                if (!is_cond) { ++other[und]; continue; }
+                if (ccount[und] < 2) inc[und][ccount[und]] = j;
+                ++ccount[und];
+            }
+        }
+        for (int j = 0; j < n_links; ++j) {
+            const auto ujj = static_cast(j);
+            if (ctx.links.type[ujj] != LinkType::CONDUIT) continue;
+            const int n1 = ctx.links.node1[ujj];
+            const int n2 = ctx.links.node2[ujj];
+            if (n1 >= 0 && n1 < n_nodes) {
+                const auto u1 = static_cast(n1);
+                if (ccount[u1] == 2 && other[u1] == 0) {
+                    const int k = (inc[u1][0] == j) ? inc[u1][1] : inc[u1][0];
+                    if (k >= 0) {
+                        uf_nb_up_[ujj] = k;
+                        uf_sg_up_[ujj] =
+                            (ctx.links.node2[static_cast(k)] == n1)
+                                ? int8_t{1} : int8_t{-1};
+                    }
+                }
+            }
+            if (n2 >= 0 && n2 < n_nodes) {
+                const auto u2 = static_cast(n2);
+                if (ccount[u2] == 2 && other[u2] == 0) {
+                    const int k = (inc[u2][0] == j) ? inc[u2][1] : inc[u2][0];
+                    if (k >= 0) {
+                        uf_nb_dn_[ujj] = k;
+                        uf_sg_dn_[ujj] =
+                            (ctx.links.node1[static_cast(k)] == n2)
+                                ? int8_t{1} : int8_t{-1};
+                    }
+                }
+            }
+        }
+    }
+
     // Seepage possibility is static input — scan once so the loss recompute
     // pass can be skipped bit-exactly on loss-free models (see
     // recomputeConduitLosses).
@@ -441,11 +620,18 @@ void DWSolver::init(int n_nodes, int n_links, const XSectGroups& groups,
     wcap_d2_.resize(ul, 0.0);
     wcap_dm_.resize(ul, 0.0);
 
-    // Build conduit index list
+    // Build conduit index list. DUMMY cross-sections are excluded to match
+    // legacy isTrueConduit (dynwave.c:411-414): a dummy conduit is never
+    // momentum-solved — findNonConduitFlow passes the upstream node's
+    // inflow + overflow straight through (conduit_getInflow). Solving it
+    // here instead gives zero-area geometry, zero flow, and an upstream
+    // node that fills without bound (221-h-h-si-units-elements node "1").
     conduit_idx_.clear();
     conduit_idx_.reserve(ul);
     for (int j = 0; j < n_links; ++j) {
-        if (ctx.links.type[static_cast(j)] == LinkType::CONDUIT)
+        auto ujc = static_cast(j);
+        if (ctx.links.type[ujc] == LinkType::CONDUIT &&
+            ctx.links.xsect_shape[ujc] != XsectShape::DUMMY)
             conduit_idx_.push_back(j);
     }
     n_conduits_ = static_cast(conduit_idx_.size());
@@ -466,10 +652,7 @@ void DWSolver::init(int n_nodes, int n_links, const XSectGroups& groups,
         const auto ucr = static_cast(ctx.link_subtypes.conduit_row(j));
         XsectShape shape = links.xsect_shape[uj];
 
-        is_open_[uj] = (shape == XsectShape::RECT_OPEN ||
-                        shape == XsectShape::TRAPEZOIDAL ||
-                        shape == XsectShape::TRIANGULAR ||
-                        shape == XsectShape::PARABOLIC);
+        is_open_[uj] = isOpenShape(shape);   // legacy xsect_isOpen (Amax == 1)
         is_force_main_[uj] = (shape == XsectShape::FORCE_MAIN);
         has_losses_[uj] = (CD.loss_inlet[ucr] != 0.0 ||
                            CD.loss_outlet[ucr] != 0.0 ||
@@ -514,6 +697,26 @@ void DWSolver::init(int n_nodes, int n_links, const XSectGroups& groups,
     aa_r_prev_.resize(un, 0.0);
     aa_skip_.resize(un, 0);
 
+    // TPA initialization (issue #156 Phase 5): per-conduit constant slot
+    // width w = g·A_full/a², a in PROJECT units converted like the other
+    // length-per-time options.
+    if (surcharge_method == SurchargeMethod::TPA) {
+        const double ucf_len2 = ucf::Ucf[ucf::LENGTH][
+            ucf::getUnitSystem(static_cast(ctx.options.flow_units))];
+        const double a_fts = std::max(tpa_celerity / ucf_len2, 1.0);
+        const auto ucn = static_cast(n_conduits_);
+        tpa_w_.assign(ucn, 0.0);
+        tpa_latch_.assign(ucn, 0);
+        tpa_latch_changed_.assign(ucn, 0);
+        for (int ci = 0; ci < n_conduits_; ++ci) {
+            const auto uj = static_cast(
+                conduit_idx_[static_cast(ci)]);
+            const double af = ctx.links.xsect_a_full[uj];
+            tpa_w_[static_cast(ci)] =
+                (af > 0.0) ? GRAVITY * af / (a_fts * a_fts) : 0.0;
+        }
+    }
+
     // Dynamic Preissmann Slot (DPS) initialization
     if (surcharge_method == SurchargeMethod::DYNAMIC_SLOT) {
         // Convert c_pT from m/s to ft/s (internal units)
@@ -584,6 +787,7 @@ void DWSolver::init(int n_nodes, int n_links, const XSectGroups& groups,
 void DWSolver::refreshConduitTile(const SimulationContext& ctx) {
     auto nc = static_cast(n_conduits_);
     tile_uj_.resize(nc);
+    tile_crow_.resize(nc);
     tile_n1_.resize(nc);
     tile_n2_.resize(nc);
     tile_inv1_elev_.resize(nc);
@@ -615,6 +819,8 @@ void DWSolver::refreshConduitTile(const SimulationContext& ctx) {
     tile_loss_outlet_.resize(nc);
     tile_loss_avg_.resize(nc);
     tile_roughness_.resize(nc);
+    tile_fm_sbot_.resize(nc);
+    tile_fm_rbot_.resize(nc);
     tile_has_flap_gate_.resize(nc);
     tile_direction_.resize(nc);
     // Reverse map sized n_links_, -1 for non-conduits
@@ -637,6 +843,7 @@ void DWSolver::refreshConduitTile(const SimulationContext& ctx) {
         auto un2 = static_cast(n2);
 
         tile_uj_[uci]            = j;
+        tile_crow_[uci]          = static_cast(ucr);
         tile_n1_[uci]            = n1;
         tile_n2_[uci]            = n2;
         tile_inv1_elev_[uci]     = nodes.invert_elev[un1];
@@ -649,7 +856,8 @@ void DWSolver::refreshConduitTile(const SimulationContext& ctx) {
         tile_w_max_[uci]         = links.xsect_w_max[uj];
         tile_length_[uci]        = cached_length_[uj];
         tile_inv_length_[uci]    = inv_length_[uj];
-        tile_links_length_[uci]  = CD.length[ucr];
+        tile_links_length_[uci]  = (CD.true_length[ucr] > 0.0)
+                                 ? CD.true_length[ucr] : CD.length[ucr];
         tile_beta_[uci]          = CD.beta[ucr];
         tile_q_max_[uci]         = CD.q_max[ucr];
         tile_rough_factor_[uci]  = CD.rough_factor[ucr];
@@ -669,6 +877,8 @@ void DWSolver::refreshConduitTile(const SimulationContext& ctx) {
         tile_loss_outlet_[uci]   = CD.loss_outlet[ucr];
         tile_loss_avg_[uci]      = CD.loss_avg[ucr];
         tile_roughness_[uci]     = CD.roughness[ucr];
+        tile_fm_sbot_[uci]       = links.xsect_s_bot[uj];
+        tile_fm_rbot_[uci]       = links.xsect_r_bot[uj];
         tile_has_flap_gate_[uci] = links.has_flap_gate[uj] ? 1 : 0;
         tile_direction_[uci]     = static_cast(links.direction[uj]);
         tile_uj_to_ci_[uj]       = ci;
@@ -755,6 +965,7 @@ void DWSolver::buildVirtualJunctionPairs(const SimulationContext& ctx) {
     vjunc_.clear();
     vj_pair_n1_.assign(static_cast(n_links_), -1);
     vj_pair_n2_.assign(static_cast(n_links_), -1);
+    vj_wet_floor_.assign(static_cast(n_nodes_), 0.0);
 
     std::vector row_of_node(static_cast(n_nodes_), -1);
     for (int i = 0; i < n_nodes_; ++i) {
@@ -808,6 +1019,20 @@ void DWSolver::buildVirtualJunctionPairs(const SimulationContext& ctx) {
         const double la = (ca >= 0) ? CD.length[static_cast(ca)] : 0.0;
         const double lb = (cb >= 0) ? CD.length[static_cast(cb)] : 0.0;
         p.lambda = 0.5 * (la + lb);
+
+        // Wetting floor for a fed pair: end and mid widths both at the seed
+        // depth, through the same (w_end + w_mid)·L/4 per-link accumulation
+        // computeLinkGeometry feeds the node — two links ⇒ w·(L_a+L_b)/2 —
+        // per barrel. Read by setNodeDepth only while the node carries a
+        // lateral inflow (plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md §E2).
+        {
+            const XSectParams xs = buildXSP(ctx, ua);
+            const double y_seed = kVjWetSeedFrac * links.xsect_y_full[ua];
+            const double w_seed = (y_seed > 0.0) ? xsect::getWofY(xs, y_seed) : 0.0;
+            const int barrels = (ca >= 0) ? CD.barrels[static_cast(ca)] : 1;
+            vj_wet_floor_[static_cast(p.node)] =
+                w_seed * p.lambda * static_cast(barrels);
+        }
     }
 }
 
@@ -836,6 +1061,17 @@ void DWSolver::vjPrepareIteration(const SimulationContext& ctx, double dt) {
         p.dq4j = 0.0;
         if (!p.through || p.up_link < 0 || p.dn_link < 0) continue;
 
+        // Inlet junctions run mechanism 1 (zero storage) ONLY. Mechanisms 2-4
+        // — the shared junction sigma, the cross-junction upwind state and the
+        // dq4_j convective correction — assume a SEALED pair with no lateral
+        // exchange at the node; an inlet junction is unsealed (it floods) and
+        // carries a capture sink, so leaving p.active at 0 keeps the pair's
+        // per-link momentum treatment. See
+        // plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §4.1.
+        if (p.node >= 0 &&
+            static_cast(p.node) < ctx.nodes.is_inlet.size() &&
+            ctx.nodes.is_inlet[static_cast(p.node)] != 0) continue;
+
         const auto uu = static_cast(p.up_link);
         const auto ud = static_cast(p.dn_link);
         const auto ucu = static_cast(tile_uj_to_ci_[uu]);
@@ -847,9 +1083,15 @@ void DWSolver::vjPrepareIteration(const SimulationContext& ctx, double dt) {
         const double wj = width2_[uu];
         if (aj <= FUDGE) continue;    // dry junction — per-link behaviour
 
+        // #144: the junction through-flow velocity and the upwind state handed
+        // to the neighbour's aWtd are momentum quantities, so both use
+        // conveyance areas. `dh` keeps `aj` — the hydraulic depth is a
+        // free-surface property, and a surcharged closed pipe leaves width2_
+        // at the crown-capped value so the wj > FUDGE gate already zeroes it.
+        const double ajFull = links.xsect_a_full[uu];
         const double qU = links.flow[uu] / tile_barrels_d_[ucu];
         const double qD = links.flow[ud] / tile_barrels_d_[ucd];
-        double vj = 0.5 * (qU + qD) / aj;
+        double vj = 0.5 * (qU + qD) / conveyArea(aj, ajFull);
         if (std::fabs(vj) > MAX_VELOCITY)
             vj = (vj > 0.0) ? MAX_VELOCITY : -MAX_VELOCITY;
 
@@ -858,7 +1100,7 @@ void DWSolver::vjPrepareIteration(const SimulationContext& ctx, double dt) {
             ? std::fabs(vj) / std::sqrt(constants::GRAVITY * dh) : 0.0;
         p.sigma_j = std::max(0.0, std::min(1.0, 2.0 * (1.0 - frj)));
 
-        p.a_up_mid = area_mid_[uu];
+        p.a_up_mid = conveyArea(area_mid_[uu], ajFull);
         p.r_up_mid = hrad_mid_[uu];
         p.active   = 1;
         // Coherent signed through-flow: momentum is transmitted across the
@@ -873,6 +1115,23 @@ void DWSolver::vjPrepareIteration(const SimulationContext& ctx, double dt) {
             const double aMd = std::max(area_mid_[ud], FUDGE);
             const double vu = qU / aMu;
             const double vd = qD / aMd;
+            // MEASURED DEFECT (2026-08-14, epaswmm5_qa suites/swashes
+            // runs/_fv_vj_probe/vj_full_sign_test.py). This term is
+            // SIGN-INVERTED relative to the per-link convective term it
+            // supplements. At constant Q, Δ(v²A) = Q²Δ(1/A) = −v²ΔA, whereas
+            // the per-link dq4 = σ·v²·(A₂−A₁)/L below is the correct
+            // non-conservative EXTRAN form (d(v²A)/dx = −v²dA/dx at constant
+            // Q is exactly what makes gA·dH/dx = v²dA/dx − gA·Sf reproduce
+            // the steady momentum equation at σ=1). Negating dq4j on
+            // macdonald-periodic restores mass conservation outright at
+            // dx=10 (−224.2 % → 0.000 %) and moves the depth bias from +0.629
+            // to +0.135 velocity heads. It does NOT make FULL useful: even
+            // sign-corrected it is l1 5.24 % against BASIC's 0.163 % and
+            // plain DW's 0.141 %, because dq4j is also added to BOTH adjacent
+            // links (2485/2503) on top of each link's own full-length dq4, so
+            // the convective term is applied ~3x. Attributing it to one side
+            // instead is worse still (l1 86-103 %). No term-level correction
+            // salvages this; see plans/VJ_MOMENTUM_SCOPE.md Phase 3.
             p.dq4j = dt * p.sigma_j * (vd * vd * aMd - vu * vu * aMu) / p.lambda;
         }
     }
@@ -940,21 +1199,6 @@ void DWSolver::vjAccumulateResiduals(SimulationContext& ctx) {
 // ============================================================================
 
 #if defined(__APPLE__)
-// Number of PERFORMANCE-core logical CPUs on Apple Silicon (hw.perflevel0),
-// 0 when unknown (Intel Macs / sysctl failure). With OMP_WAIT_POLICY=active
-// (see SWMMEngine::start), a team thread scheduled onto an EFFICIENCY core
-// turns every Picard barrier into a straggler wait (E-cores run this
-// workload ~3x slower), which is why T=8 on an 8P+2E M1 Max collapsed to
-// 2.2x SLOWER than serial. Timing-only: results are bit-identical at any
-// thread count.
-static int darwinPerfCoreCount() {
-    int n = 0;
-    std::size_t sz = sizeof(n);
-    if (sysctlbyname("hw.perflevel0.logicalcpu", &n, &sz, nullptr, 0) != 0)
-        return 0;
-    return (n > 0) ? n : 0;
-}
-
 // Pin the calling thread's QoS to USER_INTERACTIVE so the macOS scheduler
 // keeps it on P-cores. Called once per team thread from the persistent
 // parallel region prologue in execute() (thread_local latch). Errors are
@@ -968,7 +1212,7 @@ static void darwinPinThreadToPerfCores() {
 }
 #endif
 
-void DWSolver::setNumThreads(int n) {
+void DWSolver::setNumThreads(int n, std::vector* warnings) {
     // A/B override: SWMM_DW_THREADS= forces the DW Picard thread count,
     // bypassing the model-size gate below (unset or invalid → normal path).
     // Results are bit-identical at any thread count (single-producer writes,
@@ -977,47 +1221,22 @@ void DWSolver::setNumThreads(int n) {
         const int forced = std::atoi(e);
         if (forced >= 1) {
             num_threads_ = forced;
+            if (warnings) {
+                char buf[160];
+                std::snprintf(buf, sizeof buf,
+                    "Dynamic-wave thread count forced to %d by the "
+                    "SWMM_DW_THREADS environment variable ([OPTIONS] THREADS "
+                    "ignored for dynamic wave).", forced);
+                warnings->emplace_back(buf);
+            }
             return;
         }
     }
 
-    int max_threads = omp_get_max_threads();
-
-    if (n == 0)
-        num_threads_ = max_threads;
-    else
-        num_threads_ = std::min(n, max_threads);
-
-    // Threshold: with the persistent-team Picard region + active wait policy
-    // (see execute()), the per-iteration sync cost is a handful of ~0.5-3µs
-    // barriers, so the break-even model size is far lower than the old
-    // region-per-phase structure (whose kMinLinksPerThread=1000 gate forced
-    // serial DW even on ~1000-conduit models). Enable T threads only while
-    // each thread keeps >= kMinConduitsPerThread conduits of momentum work;
-    // otherwise step the thread count down (a partial reduction beats the
-    // old all-or-nothing gate on mid-size models).
-    // PERFORMANCE-ONLY deviation from legacy (`4 * NumThreads`, project.c:277
-    // — far too low): results are bit-identical at any thread count.
-    static constexpr int kMinConduitsPerThread = 100;
-    if (num_threads_ > 1) {
-        int cap = n_conduits_ / kMinConduitsPerThread;
-        if (cap < 1) cap = 1;
-        num_threads_ = std::min(num_threads_, cap);
-    }
-
-#if defined(__APPLE__)
-    // Apple Silicon P-core clamp (see darwinPerfCoreCount): never run more
-    // team threads than PERFORMANCE cores. Measured on Bellinge (M1 Max,
-    // 8P+2E): unclamped T=8 with active waits = 204s vs T=4 = 57s; with the
-    // QoS pin (execute() prologue) T=8 recovers but T=6 is the sweet spot —
-    // leaving P-core headroom for the OS/IO thread avoids barrier-straggler
-    // preemption. PERFORMANCE-ONLY: bit-identical at any thread count.
-    if (num_threads_ > 1) {
-        const int pcores = darwinPerfCoreCount();
-        if (pcores > 2)
-            num_threads_ = std::min(num_threads_, pcores - 2);
-    }
-#endif
+    // Resolution rules (THREADS = 0 auto vs explicit N, model-size gate,
+    // Apple Silicon P-core clamp for auto only) live in ThreadInfo so the
+    // C API's swmm_get_effective_threads() reports exactly what runs here.
+    num_threads_ = threadinfo::dwThreads(n, n_conduits_, warnings);
 }
 
 // ============================================================================
@@ -1046,6 +1265,10 @@ int DWSolver::execute(SimulationContext& ctx, double dt,
     // area_mid_ still holds the final midpoint areas from the previous timestep.
     std::copy(area_mid_.begin(), area_mid_.end(), area_old_.begin());
 
+    // TPA latch (issue #156 Phase 5): advanced once per routing step from the
+    // last committed state, so Picard/Anderson iterate a FIXED operator.
+    if (surcharge_method == SurchargeMethod::TPA) updateTpaLatch(ctx);
+
     // Clear bypass flags at the start of each timestep
     // (matching legacy initRoutingStep: Link[i].bypassed = FALSE)
     std::fill(bypassed_.begin(), bypassed_.end(), uint8_t{0});
@@ -1067,6 +1290,7 @@ int DWSolver::execute(SimulationContext& ctx, double dt,
             t.ponded_area = nd.ponded_area[ui];
             t.sur_depth   = nd.sur_depth[ui];
             t.full_volume = nd.full_volume[ui];
+            t.rpt_full_volume = nd.rpt_full_volume[ui];
             t.degree      = nd.degree[ui];
             t.is_storage  = (nd.type[ui] == NodeType::STORAGE) ? 1 : 0;
             t.is_outfall  = (nd.type[ui] == NodeType::OUTFALL) ? 1 : 0;
@@ -1111,7 +1335,7 @@ int DWSolver::execute(SimulationContext& ctx, double dt,
         // One-time per pool thread (thread_local latch inside): QoS pin to
         // P-cores. Without it, macOS may schedule active-spinning team
         // threads onto E-cores, making every barrier wait on an E-core
-        // straggler (the T=8 collapse — see darwinPerfCoreCount).
+        // straggler (the T=8 collapse — see threadinfo::dwThreads).
         darwinPinThreadToPerfCores();
 #endif
         int  t_steps     = 0;      // per-thread replica of legacy `Steps`
@@ -1172,7 +1396,7 @@ int DWSolver::execute(SimulationContext& ctx, double dt,
                 // critical/normal depth by one iteration (e.g. extran1's free
                 // outfall 10208 read 0 while legacy had a non-zero yCrit),
                 // seeding a per-iteration divergence.
-                openswmm::outfall::setAllOutfallDepths(ctx, ctx.current_date);
+                openswmm::outfall::setAllOutfallDepths(ctx, dt);
 
                 // Step 5: flag nodes where AA must be skipped (non-smooth
                 // operator). Only needed when Anderson acceleration is active.
@@ -1373,9 +1597,12 @@ void DWSolver::findBypassedLinks(const SimulationContext& ctx) {
 static XSectParams buildXSP(const SimulationContext& ctx, std::size_t uk) {
     const LinkData& links = ctx.links;
     XSectParams xs{};
-    // Translate LinkData enum (CIRCULAR=0) to batch enum (CIRCULAR=1)
+    // PARITY: LinkData::XsectShape and the batch XSectShape are NOT a uniform +1
+    // offset — the middle block (MODBASKET..ARCH, data 8-20) is ordered
+    // differently, so `+1` mapped e.g. CATENARY (12) onto VERT_ELLIPSE (13)
+    // and every tabular shape onto the wrong kernel. Use the canonical map.
     auto ls = links.xsect_shape[uk];
-    xs.type = (ls == XsectShape::DUMMY) ? 0 : static_cast(ls) + 1;
+    xs.type = link::translateShape(ls);
     xs.y_full = links.xsect_y_full[uk];
     xs.a_full = links.xsect_a_full[uk];
     xs.w_max  = links.xsect_w_max[uk];
@@ -1408,6 +1635,7 @@ static XSectParams buildXSP(const SimulationContext& ctx, std::size_t uk) {
             xs.area_tbl        = td.area_tbl;
             xs.hrad_tbl        = td.hrad_tbl;
             xs.width_tbl       = td.width_tbl;
+            xs.area_lut        = &td.area_lut;
             xs.transect_tbl_size = transect::N_TRANSECT_TBL;
         }
     }
@@ -1576,18 +1804,16 @@ void DWSolver::computeLinkGeometry(SimulationContext& ctx) {
             double yf = tile_y_full_[uci];
             double wm = tile_w_max_[uci];
             XsectShape shape = tile_shape_[uci];
-            if (depth1_[uj] > yf) {
-                double ws = getSlotWidth(depth1_[uj], yf, wm, shape);
-                if (ws > 0.0) width1_[uj] = ws;
-            }
-            if (depth2_[uj] > yf) {
-                double ws = getSlotWidth(depth2_[uj], yf, wm, shape);
-                if (ws > 0.0) width2_[uj] = ws;
-            }
-            if (depth_mid_[uj] > yf) {
-                double ws = getSlotWidth(depth_mid_[uj], yf, wm, shape);
-                if (ws > 0.0) width_mid_[uj] = ws;
-            }
+            // PARITY dwflow.c getWidth(): the slot width replaces the
+            // tabulated top width whenever getSlotWidth() is nonzero, i.e.
+            // from the crown cutoff (0.985257·yFull) upward — not only above
+            // full depth. Below the cutoff getSlotWidth() is 0 by itself.
+            double ws = getSlotWidth(depth1_[uj], yf, wm, shape);
+            if (ws > 0.0) width1_[uj] = ws;
+            ws = getSlotWidth(depth2_[uj], yf, wm, shape);
+            if (ws > 0.0) width2_[uj] = ws;
+            ws = getSlotWidth(depth_mid_[uj], yf, wm, shape);
+            if (ws > 0.0) width_mid_[uj] = ws;
         }
     }   // end STEP B
 
@@ -1757,10 +1983,13 @@ void DWSolver::computeLinkGeometry(SimulationContext& ctx) {
                 double w1 = width1_[uj];
                 double wM = width_mid_[uj];
                 double w2 = width2_[uj];
-                if (width_mid_[uj] > FUDGE) {
-                    surfArea1 = (w1 + wM) * length / 4.0;
-                    surfArea2 = (wM + w2) * length / 4.0 * fasnh;
-                }
+                // No width floor: legacy assigns the area unconditionally
+                // (dwflow.c:550-554). Gating on width_mid_ > FUDGE dropped the
+                // whole contribution of a barely-wet conduit, so its end nodes
+                // fell back to MIN_SURFAREA and their depth update overshot —
+                // 1950-h-h-elements' S147-283 at routing step 197.
+                surfArea1 = (w1 + wM) * length / 4.0;
+                surfArea2 = (wM + w2) * length / 4.0 * fasnh;
                 break;
             }
             case FlowClass::UP_CRITICAL: {
@@ -1929,6 +2158,14 @@ void DWSolver::computeLinkGeometry(SimulationContext& ctx) {
         applyDPSGeometry(ctx);
         }
     }
+    else if (surcharge_method == SurchargeMethod::TPA) {
+        // TPA (issue #156): same serialization rationale as DPS — the
+        // override is a cheap per-conduit pass and stays off the team.
+        #pragma omp single
+        {
+        applyTpaGeometry(ctx);
+        }
+    }
     // Static slot (Sjoberg formula) / EXTRAN STEP E overrides are FUSED into
     // the per-conduit momentumKernels loop (own-element writes only; a
     // bypassed conduit's overrides are held — identical values, since its
@@ -1967,14 +2204,33 @@ void DWSolver::recomputeConduitLossOne(SimulationContext& ctx, double dt,
         const auto uci = static_cast(ci);
         const int uj = conduit_idx_[uci];
         const auto u = static_cast(uj);
-
-        // Legacy dwflow.c:162 early return for DRY/UP_DRY/DN_DRY: link_getLossRate
-        // is NOT called, so the previously-stored rate is retained. Skip (leave
-        // CD.evap_loss_rate/seep_loss_rate[uci] untouched).
+        // ConduitData is indexed by conduit ROW, which is NOT the tile index:
+        // conduit_idx_ skips DUMMY-shaped conduits, so on any deck holding one
+        // the two diverge from that conduit on. Reading `CD.length[uci]` /
+        // `CD.seep_rate[uci]` took ANOTHER conduit's geometry (greenville's
+        // 407OF evaporated over 215 ft instead of its own 415), and writing
+        // the loss rates at `[uci]` put them in a row that SWMMEngine's mass
+        // balance, QualityRouting and the KW solver then read as some other
+        // conduit's.
+        const auto ucr = static_cast(tile_crow_[uci]);
+
+        // PARITY dwflow.c:118-119 + :189-203: findConduitFlow ZEROES
+        // Conduit.evapLossRate/seepLossRate on entry and only recomputes them
+        // (link_getLossRate at :261) past the dry/closed/empty early return —
+        // a conduit that comes out DRY, UP_DRY, DN_DRY, closed by its setting,
+        // or with aMid <= FUDGE books NO loss that iteration. Retaining the
+        // previous value here left a stale evaporation loss on a near-dry
+        // reach (50-transects CDT-521), halved into both end nodes' outflow.
+        // A bypassed conduit keeps its last-computed class and aMid, so this
+        // recompute reproduces the value legacy retains for it.
         const FlowClass fc = links.flow_class[u];
         if (fc == FlowClass::DRY || fc == FlowClass::UP_DRY ||
-            fc == FlowClass::DN_DRY)
+            fc == FlowClass::DN_DRY || area_mid_[u] <= FUDGE ||
+            tile_is_closed_[uci] || links.setting[u] == 0.0) {
+            CD.evap_loss_rate[ucr] = 0.0;
+            CD.seep_loss_rate[ucr] = 0.0;
             return;
+        }
 
         // depth = 0.5*(oldDepth + newDepth) — current iterate (legacy link.c:1349)
         const double depth = 0.5 * (links.old_depth[u] + links.depth[u]);
@@ -1982,13 +2238,20 @@ void DWSolver::recomputeConduitLossOne(SimulationContext& ctx, double dt,
         double seep_loss = 0.0;
 
         if (depth > FUDGE) {
-            // Raw user length (legacy conduit_getLength), not modLength.
-            double length = CD.length[uci];
-            if (length <= 0.0) length = CD.mod_length[uci];
+            // Routing length (legacy conduit_getLength), not modLength.
+            double length = CD.true_length[ucr];
+            if (length <= 0.0) length = CD.length[ucr];
+            if (length <= 0.0) length = CD.mod_length[ucr];
             const int shape = links.xsect_batch_shape[u];
 
+            // G-X4: an aquifer-coupled conduit runs the signed law even
+            // with no [LOSSES] seepage rate — `[2D_AQUIFER_LINKS] KC` is
+            // what lets a pipe that never leaked GAIN below the table.
+            const bool gw_two_way = !CD.gw_coupled.empty() &&
+                                    CD.gw_coupled[ucr] != 0;
+            const double k_seep = gw_two_way ? CD.gw_kc[ucr] : CD.seep_rate[ucr];
             const bool wantEvap = xsect::isOpen(shape) && evap > 0.0;
-            const bool wantSeep = CD.seep_rate[uci] > 0.0;
+            const bool wantSeep = k_seep > 0.0;
             if (wantEvap || wantSeep) {
                 const XSectParams xs = buildXSP(ctx, u);  // faithful incl. transect
                 if (wantEvap) {
@@ -2004,24 +2267,49 @@ void DWSolver::recomputeConduitLossOne(SimulationContext& ctx, double dt,
                         (shape == static_cast(XSectShape::RECT_CLOSED))
                             ? xs.w_max
                             : xsect::getWofY(xs, d_seep);
-                    seep_loss = CD.seep_rate[uci] * width * length;
+                    seep_loss = k_seep * width * length;
+                    // Monthly conductivity adjustment (legacy link.c:1378:
+                    // seepLossRate *= Adjust.hydconFactor). infil_factor
+                    // mirrors adjust_hydcon[mon] each step (A2d) and is 1.0
+                    // exactly on unadjusted decks.
+                    seep_loss *= ctx.climate_state.infil_factor;
+                    // G-X4: the signed conductance about the invert. The
+                    // factor is 1.0 — this line a no-op — for a full pipe
+                    // over a table at or below its invert, which is the
+                    // regime legacy's unit gradient assumes.
+                    if (gw_two_way) {
+                        seep_loss *= hydraulics::aquiferSeepFactor(
+                            depth, CD.gw_head_rel[ucr], CD.gw_dc[ucr]);
+                        seep_loss = hydraulics::capAquiferGain(
+                            seep_loss, CD.gw_gain_max[ucr]);
+                    }
                 }
             }
 
             // DW volume cap (legacy link.c:1389): q = newVolume/tstep; if the
             // total loss exceeds it, scale each component (comp*q/total order).
-            double total = evap_loss + seep_loss;
+            // G-X4: a GAINING conduit (seep_loss < 0) adds water rather than
+            // taking it, so it is not part of what the conduit can afford —
+            // the cap sees the losing components only, and the gain passes
+            // through untouched (it is bounded by the aquifer instead).
+            double total = evap_loss + std::max(seep_loss, 0.0);
             if (total > 0.0) {
                 const double q = links.volume[u] / dt;
                 if (total > q) {
                     evap_loss = evap_loss * q / total;
-                    seep_loss = seep_loss * q / total;
+                    if (seep_loss > 0.0) seep_loss = seep_loss * q / total;
                 }
             }
         }
 
-        CD.evap_loss_rate[uci] = evap_loss;
-        CD.seep_loss_rate[uci] = seep_loss;
+        // G-X4: a host's exchange (swmm_forcing_link_seepage) has the last
+        // word — it is applied after the volume cap, because the host is
+        // asserting a flux the conduit is required to carry, not competing
+        // for the water the conduit happens to hold.
+        hydraulics::applySeepageForcing(ctx, u, seep_loss);
+
+        CD.evap_loss_rate[ucr] = evap_loss;
+        CD.seep_loss_rate[ucr] = seep_loss;
     }
 }
 
@@ -2073,13 +2361,19 @@ void DWSolver::momentumKernels(SimulationContext& ctx, double dt, int step) {
         // (90% non-converging vs legacy's ~36%).
         new_flow_[uj] = links.flow[uj];
 
+        // A BYPASSED conduit (both end nodes converged) is not solved this
+        // iteration, and legacy findLinkFlows does not call findConduitFlow
+        // for it — so its evap/seepage loss rates stay at whatever its LAST
+        // solve left (dwflow.c:118-119 zero them on entry, :261 recomputes
+        // them). Its depth keeps moving with its end nodes, so recomputing
+        // the loss here from that fresher depth booked a different loss than
+        // legacy into both end nodes (50-transects: node PURGATORY_7's
+        // outflow after step 1 was half a stale-vs-fresh evaporation loss).
+        if (bypassed_[uj]) continue;
+
         // Per-iterate evap/seepage loss recompute (flow-class gated inside).
-        // Runs for bypassed conduits too, keeping the former whole-array
-        // pass's cadence bit-exactly (its inputs are all own-element).
         if (do_losses) recomputeConduitLossOne(ctx, dt, ci);
 
-        if (bypassed_[uj]) continue;
-
         dqdh_[uj] = 0.0;
 
         // ---- STEP E: Preissmann slot overrides (static slot / EXTRAN) ----
@@ -2097,25 +2391,39 @@ void DWSolver::momentumKernels(SimulationContext& ctx, double dt, int step) {
             double wm = tile_w_max_[uci];
             XsectShape shape = tile_shape_[uci];
 
+            // legacy getArea / getHydRad (dwflow.c): AT or above full depth
+            // the area is aFull (+ the slot's share, below) and the
+            // hydraulic radius is rFull — the geometry kernels do not all
+            // reproduce the setup's rFull at exactly y == yFull: the
+            // FILLED_CIRCULAR scalar fallback forms a/p through the circular
+            // tables and lands an ulp off (user1-filled-circular, a 1-ulp
+            // flow difference on step 559 that grew to 0.3 %).
+            if (depth1_[uj] >= yf)   { area1_[uj]    = af; hrad1_[uj]    = rf; }
+            if (depth2_[uj] >= yf)   { area2_[uj]    = af; }
+            if (depth_mid_[uj] >= yf){ area_mid_[uj] = af; hrad_mid_[uj] = rf; }
+
+            // PARITY dwflow.c getArea()/getHydRad(): above full depth the
+            // area is aFull + (y - yFull)·wSlot UNCONDITIONALLY — wSlot is 0
+            // for an open shape under SLOT (its depth is not capped, so its
+            // area stops at aFull while its width keeps growing) — and the
+            // hydraulic radius is rFull. Legacy tests `y >= yFull`; at exactly
+            // full depth every kernel already returns aFull/rFull (tables end
+            // at 1.0, formula shapes reproduce setParams), so the strict test
+            // is numerically the same and leaves the kernel values in place.
             if (depth1_[uj] > yf) {
-                double wSlot = getSlotWidth(depth1_[uj], yf, wm, shape);
-                if (wSlot > 0.0) area1_[uj] = af + (depth1_[uj] - yf) * wSlot;
-                // Upstream hyd-rad clamps to r_full once surcharged (legacy
-                // behaviour: slot is narrow so wetted perimeter stays
-                // ~constant).
+                const double wSlot = getSlotWidth(depth1_[uj], yf, wm, shape);
+                area1_[uj] = af + (depth1_[uj] - yf) * wSlot;
                 hrad1_[uj] = rf;
             }
             if (depth2_[uj] > yf) {
-                double wSlot = getSlotWidth(depth2_[uj], yf, wm, shape);
-                if (wSlot > 0.0) area2_[uj] = af + (depth2_[uj] - yf) * wSlot;
+                const double wSlot = getSlotWidth(depth2_[uj], yf, wm, shape);
+                area2_[uj] = af + (depth2_[uj] - yf) * wSlot;
             }
-            double yMid = depth_mid_[uj];
+            const double yMid = depth_mid_[uj];
             if (yMid > yf) {
-                double wSlot = getSlotWidth(yMid, yf, wm, shape);
-                if (wSlot > 0.0) {
-                    area_mid_[uj] = af + (yMid - yf) * wSlot;
-                    width_mid_[uj] = wSlot;
-                }
+                const double wSlot = getSlotWidth(yMid, yf, wm, shape);
+                area_mid_[uj] = af + (yMid - yf) * wSlot;
+                if (wSlot > 0.0) width_mid_[uj] = wSlot;
                 hrad_mid_[uj] = rf;
             }
         }
@@ -2127,11 +2435,19 @@ void DWSolver::momentumKernels(SimulationContext& ctx, double dt, int step) {
         bool isFull = (depth1_[uj] >= yf_c && depth2_[uj] >= yf_c);
 
         MomentumCategory cat;
+        // dwflow.c:111 `if (Link.setting == 0) isClosed = TRUE`: a conduit a
+        // control rule has CLOSED (setting 0, e.g. `CONDUIT X STATUS =
+        // CLOSED`) takes the zero-flow branch every iteration. The tile flag
+        // is the C-API's static closure; the rule's setting changes at run
+        // time (miami-usgs-rdii's valve conduit kept flowing while closed).
         if (fc == FlowClass::DRY || fc == FlowClass::UP_DRY ||
-            fc == FlowClass::DN_DRY || aMid <= FUDGE || tile_is_closed_[uci]) {
+            fc == FlowClass::DN_DRY || aMid <= FUDGE || tile_is_closed_[uci] ||
+            links.setting[uj] == 0.0) {
             cat = MomentumCategory::SKIP_DRY;
         } else if (tile_is_force_main_[uci] && isFull) {
-            cat = (tile_roughness_[uci] < 1.0)
+            // Legacy selects by the global FORCE_MAIN_EQUATION option
+            // (forcmain.c ForceMainEqn), not by inspecting the coefficient.
+            cat = (ctx.options.force_main_eqn == 1)
                 ? MomentumCategory::FORCE_MAIN_DW
                 : MomentumCategory::FORCE_MAIN_HW;
         } else if (!tile_is_open_[uci] && isFull) {
@@ -2165,6 +2481,12 @@ void DWSolver::momentumKernels(SimulationContext& ctx, double dt, int step) {
         // element: no kernel reads another link's flow, and the bypassed
         // path above holds links.flow == new_flow_ from its last commit.
         links.flow[uj] = new_flow_[uj];
+        // Publish the conduit dqdh alongside (legacy keeps Link.dqdh
+        // current for every link). Nothing in the conduit path reads it —
+        // the CSR gather uses dqdh_ directly — but the SWMM_TRACE_DUMP_STEP
+        // element dump prints links.dqdh, which held 0 for conduits and
+        // made per-element dqdh comparison against legacy impossible.
+        links.dqdh[uj] = dqdh_[uj];
     }
 }
 
@@ -2214,7 +2536,7 @@ void DWSolver::applyFlowLimits(SimulationContext& ctx, double dt, int step,
                                double barrels_d, bool isFull) {
     auto& links = ctx.links;
     auto& nodes = ctx.nodes;
-    auto& CD = ctx.link_subtypes.conduits;  // Phase 6 Stage B: inlet_control / normal_flow_limited (row==uci)
+    auto& CD = ctx.link_subtypes.conduits;  // inlet_control / normal_flow_limited, indexed by conduit ROW
     const int normal_flow_ltd = ctx.options.normal_flow_ltd;
     // Phase A extension: read invariants from the conduit-dense tile.
     auto uci = static_cast(tile_uj_to_ci_[uj]);
@@ -2226,17 +2548,26 @@ void DWSolver::applyFlowLimits(SimulationContext& ctx, double dt, int step,
     auto un2 = static_cast(n2);
 
     // Inlet control and normal flow limiting
-    CD.inlet_control[uci] = uint8_t{0};
-    CD.normal_flow_limited[uci] = uint8_t{0};
+    const auto ucr = static_cast(tile_crow_[uci]);
+    CD.inlet_control[ucr] = uint8_t{0};
+    CD.normal_flow_limited[ucr] = uint8_t{0};
     if (q > 0.0) {
         if (tile_culvert_code_[uci] > 0 && !isFull) {
+            // legacy culvert_getInflow(j, q, h1): the head above the
+            // culvert's upstream invert, the conduit's own section (the
+            // Form-1 codes solve for critical depth on it), and — when the
+            // inlet controls — legacy's dQdH replaces the link's dqdh.
+            const double y_in = h1 - (tile_inv1_elev_[uci] + tile_z1_off_[uci]);
             double dqdh_culv = 0.0;
-            double q_inlet = culvert::getInflow(
-                q, h1, yf, tile_a_full_[uci],
-                tile_slope_[uci], tile_culvert_code_[uci], dqdh_culv);
-            if (q_inlet < q) {
+            bool inlet = false;
+            const XSectParams xs_c = buildXSP(ctx, uj);
+            const double q_inlet = culvert::getInflow(
+                q, y_in, xs_c, tile_slope_[uci], tile_culvert_code_[uci],
+                dqdh_culv, inlet);
+            if (inlet) {
                 q = q_inlet;
-                CD.inlet_control[uci] = uint8_t{1};
+                dqdh_[uj] = dqdh_culv;
+                CD.inlet_control[ucr] = uint8_t{1};
             }
         } else {
             FlowClass fc2 = links.flow_class[uj];
@@ -2289,7 +2620,7 @@ void DWSolver::applyFlowLimits(SimulationContext& ctx, double dt, int step,
 #endif
                     if (qNorm < q) {
                         q = qNorm;
-                        CD.normal_flow_limited[uci] = uint8_t{1};
+                        CD.normal_flow_limited[ucr] = uint8_t{1};
                     }
                 }
             }
@@ -2365,8 +2696,16 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     double yf = tile_y_full_[uci];
     bool isFull = (depth1_[uj] >= yf && depth2_[uj] >= yf);
 
+    // Conveyance areas for the momentum equation — Preissmann slot excluded
+    // (issue #144, see conveyArea). aMid/area1_/area2_ keep the slot for
+    // storage and node continuity; only the momentum terms below are clamped.
+    const double aFull   = tile_a_full_[uci];
+    const double a1Conv  = conveyArea(area1_[uj], aFull);
+    const double a2Conv  = conveyArea(area2_[uj], aFull);
+    const double aMidConv = conveyArea(aMid, aFull);
+
     // Velocity (clamped)
-    double v = qLast / aMid;
+    double v = qLast / aMidConv;
     double absv = std::fabs(v);
     if (absv > MAX_VELOCITY) {
         v = (v > 0.0) ? MAX_VELOCITY : -MAX_VELOCITY;
@@ -2402,6 +2741,12 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
         const bool closed_nearfull =
             !tile_is_open_[uci] && (yf - depth_mid_[uj] <= FUDGE);
         if (depth_mid_[uj] > FUDGE && !closed_nearfull) {
+            // #144: aMid, not aMidConv, is deliberate and equivalent here.
+            // The slot only inflates area once depth_mid > y_full, and that
+            // case is unreachable in this branch: a closed conduit above its
+            // crown trips closed_nearfull above (fr = 0), and an open shape
+            // gets slot width 0 from getSlotWidth() so STEP E never overrides
+            // it. Keeping aMid preserves the legacy hydraulic-depth grouping.
             double dh = (wMid > FUDGE) ? aMid / wMid : 0.0;
             // PARITY: legacy link_getFroude computes sqrt(GRAVITY * y) directly
             // (link.c). Using the precomputed SQRT_GRAVITY constant (a truncated
@@ -2430,7 +2775,7 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     double rho = 1.0;
     if (!is_closed_full && !isFull && qLast > 0.0 && h1 >= h2)
         rho = sig;
-    double aWtd = area1_[uj] + (aMid - area1_[uj]) * rho;
+    double aWtd = a1Conv + (aMidConv - a1Conv) * rho;
     // PARITY dwflow.c:198: legacy uses the raw interpolated rWtd in pow(rWtd,
     // 1.33333) — no clamp. The DRY / aMid<=FUDGE branch already returned, and
     // r1_val/rMid > 0 for any wet section, so rWtd > 0 here (no div-by-zero).
@@ -2463,12 +2808,20 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
             if (p.active) {
                 if (vj_m3 && p.dirn > 0 && static_cast(uj) == p.dn_link &&
                     !is_closed_full && !isFull && qLast > 0.0) {
-                    aWtd = p.a_up_mid + (aMid - p.a_up_mid) * rho;
+                    // p.a_up_mid is already a conveyance area (#144).
+                    aWtd = p.a_up_mid + (aMidConv - p.a_up_mid) * rho;
                     rWtd = p.r_up_mid + (rMid - p.r_up_mid) * rho;
                 }
                 if (vj_m4) vj_dq4 += p.dq4j;
             }
         }
+        // NOTE (2026-08-14): each interface's dq4j spans midpoint-to-midpoint
+        // (Λ = ½(L_a+L_b)) and is added HERE as well as at r1 above, so an
+        // interior link picks up two of them on top of its own full-length
+        // dq4. Attributing each interface to a single link instead was
+        // measured and is far worse (l1 86-103 % vs 4-9 %), so the
+        // duplication is not the primary defect — the sign inversion noted at
+        // vjPrepareIteration is. See plans/VJ_MOMENTUM_SCOPE.md Phase 3.
         if (r2 >= 0) {
             const VJuncPair& p = vjunc_[static_cast(r2)];
             if (p.active && vj_m4) vj_dq4 += p.dq4j;
@@ -2515,12 +2868,16 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     double dq2 = dt_g * aWtd * (h2 - h1) / length;
 
     // Unsteady + convective acceleration (skip if sig==0)
-    double aOld = std::max(area_old_[uj], FUDGE);
+    // #144: area_old_ is a copy of the slot-inclusive area_mid_ taken at the
+    // start of the step, so it must be clamped alongside aMid — otherwise the
+    // dq3 difference mixes a conveyance area with a slot area and manufactures
+    // a spurious inertial impulse on any step that crosses the crown.
+    double aOld = std::max(conveyArea(area_old_[uj], aFull), FUDGE);
     double dq3 = 0.0, dq4 = 0.0;
     if (sig > 0.0) {
-        dq3 = 2.0 * v * (aMid - aOld) * sig;
+        dq3 = 2.0 * v * (aMidConv - aOld) * sig;
         if (length > 0.0)
-            dq4 = dt * v * v * (area2_[uj] - area1_[uj]) / length * sig;  // PARITY dwflow.c:222
+            dq4 = dt * v * v * (a2Conv - a1Conv) / length * sig;  // PARITY dwflow.c:222
         // Cross-junction convective correction for virtual-junction pairs
         // (0 unless VIRTUAL_JUNCTION_MOMENTUM FULL and the pair is active);
         // gated on sig so the inertial-damping overrides silence it too.
@@ -2532,9 +2889,10 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     if (tile_has_losses_[uci]) {
         double absq = std::fabs(qLast);
         double losses = 0.0;
-        if (area1_[uj] > FUDGE) losses += tile_loss_inlet_[uci] * (absq / area1_[uj]);
-        if (area2_[uj] > FUDGE) losses += tile_loss_outlet_[uci] * (absq / area2_[uj]);
-        if (aMid > FUDGE) losses += tile_loss_avg_[uci] * (absq / aMid);
+        // #144: local losses are velocity heads — conveyance areas.
+        if (a1Conv > FUDGE) losses += tile_loss_inlet_[uci] * (absq / a1Conv);
+        if (a2Conv > FUDGE) losses += tile_loss_outlet_[uci] * (absq / a2Conv);
+        if (aMidConv > FUDGE) losses += tile_loss_avg_[uci] * (absq / aMidConv);
         dq5 = losses / 2.0 / length * dt;  // PARITY dwflow.c:229
     }
 
@@ -2544,7 +2902,8 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     double dq6 = 0.0;
     {
         double conduit_length = tile_links_length_[uci];
-        double loss_rate = CD.evap_loss_rate[uci] + CD.seep_loss_rate[uci];  // row==uci
+        const auto ucr6 = static_cast(tile_crow_[uci]);
+        double loss_rate = CD.evap_loss_rate[ucr6] + CD.seep_loss_rate[ucr6];
         if (loss_rate > 0.0 && conduit_length > 0.0)
             dq6 = loss_rate * 2.5 * dt * v / conduit_length;
     }
@@ -2552,14 +2911,104 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
     // Flow update
     double qOld = links.old_flow[uj] / barrels_d;
     double denom = 1.0 + dq1 + dq5;
-    double q = (qOld - dq2 + dq3 + dq4 + dq6) / denom;
+
+    // Unsteady friction (issue #156 Phase 3). S_fu = (k3/g)(∂V/∂t +
+    // c·sgn(V)|∂V/∂x|), Pinto et al. (2025). The local-acceleration half is
+    // folded into the SAME denominator the dqdh Jacobian is built from
+    // (q·(denom + k3) = ... + k3·aWtd·vOld), so the surcharge node iteration
+    // stays consistent by construction; the convective half is explicit from
+    // the end-velocity difference (same |Q| through both ends, conveyance
+    // areas), clamped to half the incoming momentum. Celerity is
+    // regime-consistent through width_mid_: the slot width when surcharged
+    // under SLOT/DYNAMIC_SLOT (acoustic), the free-surface width otherwise,
+    // and the near-crown width under EXTRAN (plan §3.2 O-1 default). The
+    // 0.01 ft/s dead-band mirrors kernels::ufUpdate (added-inertia noise
+    // amplification, measured on the FV side). When inactive, the original
+    // expression is evaluated verbatim so the default path stays bit-exact.
+    bool   uf_applied = false;
+    double uf_num = 0.0;
+    if (unsteady_friction != 0 && uf_k3 > 0.0) {
+        constexpr double kUfVelFloor = 0.01;  // ft/s, mirrors FvKernels
+        const double vOld = (aOld > FUDGE) ? qOld / aOld : 0.0;
+        if (std::fabs(vOld) >= kUfVelFloor || absv >= kUfVelFloor) {
+            const double wMid = width_mid_[uj];
+            const double c_wave = (wMid > FUDGE && aMid > FUDGE)
+                ? std::sqrt(GRAVITY * aMid / wMid) : 0.0;
+            // ∂V/∂x: cross-link stencil first (a full link has equal end
+            // areas, so the within-link estimator is structurally zero in
+            // exactly the pressurized cases UF exists for — measured
+            // anti-damping without this). Neighbor previous-iterate
+            // velocities, sign-mapped into this link's frame; falls back to
+            // the within-link end-velocity difference when no simple
+            // degree-2 conduit neighbor exists on either side.
+            double dv_dx = 0.0;
+            {
+                auto nb_vel = [&](int nbj, int8_t sg) -> double {
+                    const auto unb = static_cast(nbj);
+                    const auto uci_nb =
+                        static_cast(tile_uj_to_ci_[unb]);
+                    const double a_nb = std::max(
+                        conveyArea(area_mid_[unb], tile_a_full_[uci_nb]),
+                        FUDGE);
+                    return static_cast(sg) *
+                           (links.flow[unb] / tile_barrels_d_[uci_nb]) / a_nb;
+                };
+                double vL = v, vR = v, dsum = 0.0;
+                if (uf_nb_up_[uj] >= 0) {
+                    const auto uci_nb = static_cast(
+                        tile_uj_to_ci_[static_cast(uf_nb_up_[uj])]);
+                    vL = nb_vel(uf_nb_up_[uj], uf_sg_up_[uj]);
+                    dsum += 0.5 * (length + tile_length_[uci_nb]);
+                }
+                if (uf_nb_dn_[uj] >= 0) {
+                    const auto uci_nb = static_cast(
+                        tile_uj_to_ci_[static_cast(uf_nb_dn_[uj])]);
+                    vR = nb_vel(uf_nb_dn_[uj], uf_sg_dn_[uj]);
+                    dsum += 0.5 * (length + tile_length_[uci_nb]);
+                }
+                if (dsum > 0.0) {
+                    dv_dx = std::fabs(vR - vL) / dsum;
+                } else if (length > 0.0) {
+                    const double absq = std::fabs(qLast);
+                    const double v1e = (a1Conv > FUDGE) ? absq / a1Conv : 0.0;
+                    const double v2e = (a2Conv > FUDGE) ? absq / a2Conv : 0.0;
+                    dv_dx = std::fabs(v2e - v1e) / length;
+                }
+            }
+            const double sgn = (v > 0.0) ? 1.0 : ((v < 0.0) ? -1.0 : 0.0);
+            double dq_grad = dt * uf_k3 * aWtd * c_wave * sgn * dv_dx;
+            const double cap = 0.5 * std::fabs(qOld);
+            if (std::fabs(dq_grad) > cap)
+                dq_grad = (dq_grad > 0.0) ? cap : -cap;
+            denom += uf_k3;
+            uf_num = uf_k3 * aWtd * vOld - dq_grad;
+            uf_applied = true;
+        }
+    }
+    double q = uf_applied
+        ? (qOld - dq2 + dq3 + dq4 + dq6 + uf_num) / denom
+        : (qOld - dq2 + dq3 + dq4 + dq6) / denom;
     // PARITY dwflow.c:240: legacy groups ((1/denom)*GRAVITY)*dt and divides by
     // length directly (NOT dt_g=dt*GRAVITY). dqdh feeds the surcharge node-depth
     // Jacobian (sumdqdh denominator), so the grouping/divide must match exactly.
     dqdh_[uj] = 1.0 / denom * GRAVITY * dt * aWtd / length * barrels_d;
 
-    // A3 parity term tracing for one link (SWMM_TRACE_LINK=, first 64
-    // invocations; format-matched to the legacy trace in dwflow.c).
+    traceLinkTerms(ctx, uj, qLast, v, sig, rho, aWtd, rWtd, dq1, dq2, dq3, dq4,
+                   dq5, dq6, qOld, q, aMidConv);
+
+    // Shared post-processing
+    applyFlowLimits(ctx, dt, step, uj, q, qLast, barrels_d, isFull);
+}
+
+// A3 parity term tracing for one link (SWMM_TRACE_LINK=, first 64
+// invocations; format-matched to the legacy trace in dwflow.c). Shared by
+// the Manning and force-main kernels.
+void DWSolver::traceLinkTerms(const SimulationContext& ctx, std::size_t uj,
+                              double qLast, double v, double sig, double rho,
+                              double aWtd, double rWtd, double dq1, double dq2,
+                              double dq3, double dq4, double dq5, double dq6,
+                              double qOld, double q, double aMidConv) {
+    const auto& links = ctx.links;
     {
         static FILE* lf = nullptr;
         static long  lf_target = -2;
@@ -2581,7 +3030,7 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
                 std::snprintf(fname, sizeof(fname), "%s.link%ld", tr, lf_target);
                 lf = std::fopen(fname, "w");
                 if (lf) std::fprintf(lf,
-                    "n,qLast,v,sigma,rho,aWtd,rWtd,dq1,dq2,dq3,dq4,dq5,dq6,qOld,q,sa1,sa2,fc,y1,yMid,a1,aMid,r1,rMid\n");
+                    "n,qLast,v,sigma,rho,aWtd,rWtd,dq1,dq2,dq3,dq4,dq5,dq6,qOld,q,sa1,sa2,fc,y1,yMid,a1,aMid,r1,rMid,aMidConv,dqdh,h1,h2,n1,n2,yn1,yn2\n");
             }
         }
         if (lf && static_cast(uj) == lf_target) {
@@ -2595,20 +3044,21 @@ void DWSolver::processManningLink(SimulationContext& ctx, double dt, int step,
                 : (lf_count > lf_skip);
             if (in_window && lf_rows < 128) {
                 ++lf_rows;
-                std::fprintf(lf, "%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%a,%a,%a,%a,%a,%a\n",
+                std::fprintf(lf, "%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%d,%a,%a\n",
                              lf_count, qLast, v, sig, rho, aWtd, rWtd,
                              dq1, dq2, dq3, dq4, dq5, dq6, qOld, q,
                              surf_area1_[uj], surf_area2_[uj],
                              static_cast(links.flow_class[uj]),
                              depth1_[uj], depth_mid_[uj], area1_[uj],
-                             area_mid_[uj], hrad1_[uj], hrad_mid_[uj]);
+                             area_mid_[uj], hrad1_[uj], hrad_mid_[uj],
+                             aMidConv, dqdh_[uj], h1_[uj], h2_[uj],
+                             links.node1[uj], links.node2[uj],
+                             ctx.nodes.depth[static_cast(links.node1[uj])],
+                             ctx.nodes.depth[static_cast(links.node2[uj])]);
                 if (lf_rows >= 128) { std::fclose(lf); lf = nullptr; }
             }
         }
     }
-
-    // Shared post-processing
-    applyFlowLimits(ctx, dt, step, uj, q, qLast, barrels_d, isFull);
 }
 
 // ============================================================================
@@ -2625,16 +3075,23 @@ void DWSolver::processForceMainLink(SimulationContext& ctx, double dt, int step,
     // Phase A extension: read invariants from the conduit-dense tile.
     auto uci = static_cast(tile_uj_to_ci_[uj]);
     double barrels_d = tile_barrels_d_[uci];
-    double inv_len = tile_inv_length_[uci];
     double aMid = area_mid_[uj];
     double rMid = hrad_mid_[uj];
     double qLast = links.flow[uj] / barrels_d;
 
+    // Conveyance areas — Preissmann slot excluded (issue #144). A force main
+    // is full for the whole simulation, so under SLOT the slot is always
+    // active here; this is the systematically affected case.
+    const double aFull    = tile_a_full_[uci];
+    const double a1Conv   = conveyArea(area1_[uj], aFull);
+    const double a2Conv   = conveyArea(area2_[uj], aFull);
+    const double aMidConv = conveyArea(aMid, aFull);
+
     // Force main is always full (that's the classification condition)
     bool isFull = true;
 
     // Velocity (clamped)
-    double v = qLast / aMid;
+    double v = qLast / aMidConv;
     double absv = std::fabs(v);
     if (absv > MAX_VELOCITY) {
         v = (v > 0.0) ? MAX_VELOCITY : -MAX_VELOCITY;
@@ -2650,22 +3107,46 @@ void DWSolver::processForceMainLink(SimulationContext& ctx, double dt, int step,
     double h1 = h1_[uj];
     double h2 = h2_[uj];
 
-    // No upstream weighting when full (rho=1)
-    double aWtd = area1_[uj] + (aMid - area1_[uj]);  // = aMid
+    // No upstream weighting when full (rho=1). The a1Conv +/- form is kept
+    // rather than collapsing to aMidConv: the two differ in the last ULP.
+    double aWtd = a1Conv + (aMidConv - a1Conv);  // = aMidConv
     double rWtd = std::max(rMid, FUDGE);
     (void)rWtd;  // reserved for future friction variants
 
-    // Force main friction
-    double fm_coeff = tile_roughness_[uci];
-    double sf;
-    if (is_dw)
-        sf = forcemain::getFricSlope_DW(v, rMid, fm_coeff);
-    else
-        sf = forcemain::getFricSlope_HW(v, rMid, fm_coeff);
-    double dq1 = (absv > FUDGE) ? dt * GRAVITY * sf / absv : 0.0;
+    // Force main friction — legacy dwflow.c:236-237 via forcmain.c
+    // getFricSlope, using the PRECOMPUTED sBot rough factor
+    // (link.c:1127-1131: gravity and the artificial-lengthening
+    // compensation lf^0.54 are baked in; PostParseResolver stores it in
+    // xsect_s_bot). The kernel previously recomputed a textbook Sf from
+    // the raw coefficient (velocity exponent 1/0.54 vs legacy's literal
+    // 1.852, R exponent 0.63/0.54 vs 1.1667, no lengthFactor) — a
+    // systematic ~1e-4 relative friction bias that flips knife-edge
+    // surcharge onsets (PS4D on 800-node-sewer at t = 4.55 h).
+    const double sbot = tile_fm_sbot_[uci];
+    double dq1;
+    // PARITY dwflow.c:237: dq1 = dt * forcemain_getFricSlope(...) — the
+    // slope expression is evaluated FIRST and multiplied by dt LAST.
+    // Regrouping (dt*sbot)*... rounds differently by 1 ULP, and dq1 feeds
+    // the link dqdh scattered into the node sumdqdh surcharge denominator,
+    // where a single ULP flips the PS4D knife-edge onset (800-node-sewer).
+    if (is_dw) {
+        // forcmain.c:108-112: re = 4·R·|v|/VISCOS; f from Colebrook;
+        // Sf-term = f · sBot · |v| / R  (sBot = 1/(8·lengthFactor)).
+        const double re = 4.0 * rMid * absv / forcemain::VISCOS;
+        const double f  = forcemain::getFricFactor(tile_fm_rbot_[uci],
+                                                   rMid, re);
+        dq1 = dt * (f * sbot * absv / rMid);
+    } else {
+        // forcmain.c:105-106: Sf-term = sBot · |v|^0.852 / R^1.1667.
+        dq1 = dt * (sbot * std::pow(absv, 0.852) / std::pow(rMid, 1.1667));
+    }
 
-    // Head gradient
-    double dq2 = dt_g * aWtd * (h2 - h1) * inv_len;
+    // Head gradient — PARITY dwflow.c:242: divide by length directly, like
+    // the Manning kernel; x*inv_len rounds differently by 1 ULP, and on a
+    // pressurized force main that ULP reaches dqdh and the node sumdqdh
+    // surcharge denominator (PS4D on 800-node-sewer).
+    const double fm_length = tile_length_[uci];
+    double dq2 = dt_g * aWtd * (h2 - h1) / fm_length;
 
     // sig=0: no unsteady/convective terms (dq3=dq4=0)
 
@@ -2674,10 +3155,11 @@ void DWSolver::processForceMainLink(SimulationContext& ctx, double dt, int step,
     if (has_losses_[uj]) {
         double absq = std::fabs(qLast);
         double losses = 0.0;
-        if (area1_[uj] > FUDGE) losses += tile_loss_inlet_[uci] * (absq / area1_[uj]);
-        if (area2_[uj] > FUDGE) losses += tile_loss_outlet_[uci] * (absq / area2_[uj]);
-        if (aMid > FUDGE) losses += tile_loss_avg_[uci] * (absq / aMid);
-        dq5 = losses * 0.5 * inv_len * dt;
+        // #144: local losses are velocity heads — conveyance areas.
+        if (a1Conv > FUDGE) losses += tile_loss_inlet_[uci] * (absq / a1Conv);
+        if (a2Conv > FUDGE) losses += tile_loss_outlet_[uci] * (absq / a2Conv);
+        if (aMidConv > FUDGE) losses += tile_loss_avg_[uci] * (absq / aMidConv);
+        dq5 = losses / 2.0 / fm_length * dt;  // PARITY dwflow.c:229
     }
 
     // Evaporation/seepage. Length divisor uses RAW length (matching legacy
@@ -2686,7 +3168,8 @@ void DWSolver::processForceMainLink(SimulationContext& ctx, double dt, int step,
     double dq6 = 0.0;
     {
         double conduit_length = tile_links_length_[uci];
-        double loss_rate = CD.evap_loss_rate[uci] + CD.seep_loss_rate[uci];  // row==uci
+        const auto ucr6 = static_cast(tile_crow_[uci]);
+        double loss_rate = CD.evap_loss_rate[ucr6] + CD.seep_loss_rate[ucr6];
         if (loss_rate > 0.0 && conduit_length > 0.0)
             dq6 = loss_rate * 2.5 * dt * v / conduit_length;
     }
@@ -2694,8 +3177,35 @@ void DWSolver::processForceMainLink(SimulationContext& ctx, double dt, int step,
     // Flow update
     double qOld = links.old_flow[uj] / barrels_d;
     double denom = 1.0 + dq1 + dq5;
-    double q = (qOld - dq2 + dq6) / denom;
-    dqdh_[uj] = (1.0 / denom) * dt_g * aWtd * inv_len * barrels_d;
+
+    // Unsteady friction (issue #156 Phase 3), force-main arm: full pipe, so
+    // the end areas are equal and the convective |∂V/∂x| term vanishes within
+    // the link — only the local-acceleration fold applies (vOld from the
+    // constant full-flow area). Same dead-band as the Manning arm; the
+    // default path evaluates the original expression verbatim.
+    bool uf_applied = false;
+    if (unsteady_friction != 0 && uf_k3 > 0.0) {
+        constexpr double kUfVelFloor = 0.01;  // ft/s, mirrors FvKernels
+        const double vOld = (aWtd > FUDGE)
+            ? qOld / aWtd : 0.0;
+        if (std::fabs(vOld) >= kUfVelFloor ||
+            std::fabs(v) >= kUfVelFloor) {
+            denom += uf_k3;
+            uf_applied = true;
+        }
+    }
+    // k3·aWtd·vOld with vOld = qOld/aWtd collapses to k3·qOld exactly.
+    double q = uf_applied
+        ? (qOld - dq2 + dq6 + uf_k3 * qOld) / denom
+        : (qOld - dq2 + dq6) / denom;
+    // PARITY dwflow.c:240 (same grouping as the Manning kernel):
+    // ((1/denom)*GRAVITY)*dt, divide by length — NOT dt_g / inv_len.
+    dqdh_[uj] = 1.0 / denom * GRAVITY * dt * aWtd / fm_length * barrels_d;
+
+    // The same A3 term trace as the Manning kernel (SWMM_TRACE_LINK), so a
+    // traced force main is not silent.
+    traceLinkTerms(ctx, uj, qLast, v, 0.0, 1.0, aWtd, rWtd, dq1, dq2, 0.0, 0.0,
+                   dq5, dq6, qOld, q, aMidConv);
 
     // Shared post-processing
     applyFlowLimits(ctx, dt, step, uj, q, qLast, barrels_d, isFull);
@@ -2751,11 +3261,27 @@ void DWSolver::updateNodeFlows(SimulationContext& ctx) {
 
         // Add conduit evap/seepage loss to node outflows (matching legacy lines 542-558)
         if (links.type[uj] == LinkType::CONDUIT) {
-            const auto uci_l = static_cast(tile_uj_to_ci_[uj]);  // row==ci
-            double conduit_loss = (ctx.link_subtypes.conduits.evap_loss_rate[uci_l]
-                                   + ctx.link_subtypes.conduits.seep_loss_rate[uci_l])
+            const auto uci_l = static_cast(tile_uj_to_ci_[uj]);
+            const auto ucr_l = static_cast(tile_crow_[uci_l]);
+            double conduit_loss = (ctx.link_subtypes.conduits.evap_loss_rate[ucr_l]
+                                   + ctx.link_subtypes.conduits.seep_loss_rate[ucr_l])
                                   * tile_barrels_d_[uci_l];
-            if (conduit_loss > 0.0) {
+            // G-X4: a net-GAINING conduit arrives here as a negative loss.
+            // It is an INFLOW to the end nodes — booked on `inflow`, not as
+            // a negative `outflow`, because the depth solver takes
+            // inflow − outflow (identical either way) while flooding and the
+            // node statistics read the two separately, and aquifer water
+            // entering a pipe is an inflow in both.
+            if (conduit_loss < 0.0) {
+                double gain = -conduit_loss;
+                if (nodes.type[un1] != NodeType::OUTFALL &&
+                    nodes.type[un2] != NodeType::OUTFALL)
+                    gain /= 2.0;
+                if (nodes.type[un1] != NodeType::OUTFALL)
+                    nodes.inflow[un1] += gain;
+                if (nodes.type[un2] != NodeType::OUTFALL)
+                    nodes.inflow[un2] += gain;
+            } else if (conduit_loss > 0.0) {
                 // Split loss between nodes unless one is an outfall
                 if (nodes.type[un1] != NodeType::OUTFALL &&
                     nodes.type[un2] != NodeType::OUTFALL)
@@ -2835,10 +3361,17 @@ void DWSolver::gatherConduitNodeFlows(SimulationContext& ctx) {
             // 542-558): halved when neither end is an outfall; outfall ends
             // receive no share. Recomputing the halved value per node is
             // bit-identical to the serial once-per-link computation.
-            double conduit_loss = (CD.evap_loss_rate[uci]
-                                   + CD.seep_loss_rate[uci])
+            const auto ucr_g = static_cast(tile_crow_[uci]);
+            double conduit_loss = (CD.evap_loss_rate[ucr_g]
+                                   + CD.seep_loss_rate[ucr_g])
                                   * tile_barrels_d_[uci];
-            if (conduit_loss > 0.0) {
+            if (conduit_loss < 0.0) {                       // G-X4: gaining
+                double gain = -conduit_loss;
+                if (!self_outfall && !csr_other_outfall_[uk])
+                    gain /= 2.0;
+                if (!self_outfall)
+                    inflow += gain;
+            } else if (conduit_loss > 0.0) {
                 if (!self_outfall && !csr_other_outfall_[uk])
                     conduit_loss /= 2.0;
                 if (!self_outfall)
@@ -2900,6 +3433,22 @@ void DWSolver::computeAASkipFlags(const SimulationContext& ctx) {
         }
     }
 
+    // TPA (issue #156, plan §B3): skip AA at both end nodes of any conduit
+    // whose latch CHANGED this step — a discrete operator switch, the same
+    // reasoning as the static-slot kink walk. Steady latched or steady free
+    // conduits remain AA-eligible.
+    if (surcharge_method == SurchargeMethod::TPA) {
+        for (int ci = 0; ci < n_conduits_; ++ci) {
+            const auto uci = static_cast(ci);
+            if (!tpa_latch_changed_[uci]) continue;
+            const auto uj = static_cast(conduit_idx_[uci]);
+            const int n1 = links.node1[uj];
+            const int n2 = links.node2[uj];
+            if (n1 >= 0) aa_skip_[static_cast(n1)] = 1;
+            if (n2 >= 0) aa_skip_[static_cast(n2)] = 1;
+        }
+    }
+
     // DYNAMIC_SLOT: skip AA for nodes incident to a conduit with active slot area
     if (surcharge_method == SurchargeMethod::DYNAMIC_SLOT) {
         for (int ci = 0; ci < n_conduits_; ++ci) {
@@ -3208,6 +3757,8 @@ void DWSolver::setNodeDepth(SimulationContext& ctx, int node_idx, double dt,
     // committed volume stays identically zero).
     if (t.is_virtual == 0)
         surf_area = std::max(surf_area, min_surf_area_);
+    else if (nodes.lat_flow[ui] != 0.0 && ui < vj_wet_floor_.size())
+        surf_area = std::max(surf_area, vj_wet_floor_[ui]);
 
     // --- Net flow volume change (trapezoidal averaging with previous step) ---
     double dQ = nodes.inflow[ui] - nodes.outflow[ui];
@@ -3248,12 +3799,46 @@ void DWSolver::setNodeDepth(SimulationContext& ctx, int node_idx, double dt,
     // convention the EXTRAN surcharge branch divides by. Flooding cannot
     // occur (commitNodeDepthState seals the node: volume ≡ 0, overflow ≡ 0,
     // no cap at full depth).
+    // Under SEMI_IMPLICIT the two regimes below collapse into one denominator,
+    // exactly as they do for real nodes: a virtual junction carries no storage,
+    // so its natural area can be arbitrarily small (a dry pass-through node
+    // between two conduits has almost none) and the explicit dV/A step then
+    // divides a finite volume change by ~0. On a 5028-VJ transmission main a
+    // full-pipe neighbour drove dV = -4.1e6 ft^3 into a node holding
+    // A = 2.4 ft^2, reaching head 1.9e14 by the fourth routing step. Folding
+    // the head-response Jacobian into the denominator keeps it bounded as
+    // A -> 0, where it degrades to the zero-storage Newton step dy = dQ/Σdqdh
+    // — the relation this node type actually obeys. sumdqdh is accumulated
+    // non-negative (g*dt*A/L/denom per link), so the sum is positive whenever
+    // the node has either storage or a live flow path.
+    // A lateral inflow at the node (allowed since
+    // plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md) needs one more guard: at a
+    // dry pair the natural area is ~FUDGE·L and sumdqdh is 0, so the explicit
+    // dV/A step would divide an imposed volume by nothing and the dry-pair
+    // hold below would swallow it — booked as system inflow, never routed.
+    // While lat_flow is nonzero the area is floored at vj_wet_floor_ (applied
+    // above): the pair's own natural area at a seed depth of
+    // kVjWetSeedFrac·y_full, continuous with the natural area (max of the
+    // two) and inert once the pair is wetter than the seed depth. Unfed
+    // virtual junctions and every real node keep their exact arithmetic.
     if (t.is_virtual != 0) {
         const double sum = xnode_.sumdqdh[ui];
+        const double denom_semi = surf_area + 0.5 * dt * sum;
+        const bool semi_implicit =
+            (node_continuity == NodeContinuity::SEMI_IMPLICIT) &&
+            denom_semi > FUDGE;
         double y_vj;
-        if (surf_area > FUDGE && !is_surcharged) {
-            // Free surface: standard dV/A path on the natural area, with the
-            // usual under-relaxation.
+        if (semi_implicit) {
+            // Unified path — free-surface and surcharged alike, matching the
+            // real-node SEMI_IMPLICIT branch (which likewise ignores the
+            // is_surcharged dQ/dH split and the crown clamp).
+            y_vj = y_old + dV / denom_semi;
+            xnode_.old_surf_area[ui] = surf_area;
+            if (step > 0) y_vj = (1.0 - omega) * y_last + omega * y_vj;
+        } else if (surf_area > FUDGE && !is_surcharged) {
+            // EXPLICIT free surface: historical dV/A path on the natural area,
+            // with the usual under-relaxation. Decks that do not ask for
+            // semi-implicit node continuity stay bit-identical.
             y_vj = y_old + dV / surf_area;
             xnode_.old_surf_area[ui] = surf_area;
             if (step > 0) y_vj = (1.0 - omega) * y_last + omega * y_vj;
@@ -3471,11 +4056,21 @@ void DWSolver::commitNodeDepthState(SimulationContext& ctx, int node_idx,
     // --- Depth cannot be negative ---
     y_new = std::max(y_new, 0.0);
 
+    // --- Inlet junction: virtual, but NOT sealed ---
+    // An inlet junction sits on a street surface, so water above the section
+    // leaves the corridor: it must flood (or pond) like an ordinary junction
+    // rather than surcharge without bound. It keeps every other virtual-
+    // junction property — the unfloored natural surface area and the
+    // zero-storage head update in setNodeDepth still apply.
+    // See plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §2.2.7.
+    const bool is_inlet_node =
+        (ui < ctx.nodes.is_inlet.size() && ctx.nodes.is_inlet[ui] != 0);
+
     // --- Virtual junction: zero storage, no flooding by construction ---
     // The head may rise above the pipe crown without cap (surcharge is
     // expressed through the connecting conduits' slot/EXTRAN treatment,
     // like a sealed manhole); volume and overflow are identically zero.
-    if (t.is_virtual != 0) {
+    if (t.is_virtual != 0 && !is_inlet_node) {
         nodes.overflow[ui] = 0.0;
         nodes.volume[ui]   = 0.0;
         if (dt > 0.0)
@@ -3492,32 +4087,59 @@ void DWSolver::commitNodeDepthState(SimulationContext& ctx, int node_idx,
         (ctx.options.allow_ponding || is_coupled) && (t.ponded_area > 0.0);
 
     // --- Determine max non-flooded depth ---
+    // Plan D-E2: an inlet junction's flood threshold is the [INLET_JUNCTIONS]
+    // MaxDepth token when one was supplied (carried on NodeData::rim_depth),
+    // else the derived street y_full. Never below the derived depth, so a
+    // rendering-only rim cannot make the node flood early.
     double y_max = t.full_depth;
+    if (is_inlet_node && nodes.rim_depth[ui] > 0.0)
+        y_max = std::max(y_max, nodes.rim_depth[ui]);
     if (!can_pond) y_max += t.sur_depth;
 
     // --- Flooding logic (matching legacy getFloodedDepth) ---
     // Reset first so a re-commit (accepted Anderson mix after the raw Picard
     // commit) cannot inherit stale overflow from the earlier candidate.
+    //
+    // Volume is booked in the LEGACY convention (NodeTile::rpt_full_volume,
+    // legacy Node.fullVolume): a junction's full volume is 0 unless it is a
+    // Type-1 pump wet well, so a ponded junction carries only the water above
+    // its rim — legacy max(oldVolume + dV, fullVolume) with fullVolume = 0 —
+    // and a plain junction none. Booking MIN_SURFAREA*fullDepth here (the FV
+    // mesh convention in full_volume) put every ponded junction's reported
+    // volume, the routing mass balance's flooding gate and the control-rule /
+    // quality node volume off by that amount (sampleram JCT-38: +50.26 ft3,
+    // 4 ft * 12.566 ft2, from the first ponded step on).
     nodes.overflow[ui] = 0.0;
     if (y_new > y_max) {
         if (!can_pond) {
             // Non-ponded flooding: cap at max, excess is overflow
             nodes.overflow[ui] = dV / dt;
-            nodes.volume[ui] = t.full_volume;
+            nodes.volume[ui] = t.rpt_full_volume;
             y_new = y_max;
         } else {
             // Ponded: volume can exceed full volume
             nodes.volume[ui] = std::max(nodes.old_volume[ui] + dV,
-                                        t.full_volume);
+                                        t.rpt_full_volume);
             nodes.overflow[ui] = (nodes.volume[ui] -
-                std::max(nodes.old_volume[ui], t.full_volume)) / dt;
+                std::max(nodes.old_volume[ui], t.rpt_full_volume)) / dt;
         }
         if (nodes.overflow[ui] < FUDGE) nodes.overflow[ui] = 0.0;
-    } else {
+    } else if (t.is_storage) {
         nodes.volume[ui] = node::getVolume(nodes, node_idx, y_new, &ctx.tables,
                                            unit_sys_, &ctx.node_subtypes);
+    } else {
+        // Legacy node_getVolume default branch: fullVolume * (depth / fullDepth)
+        nodes.volume[ui] = (t.full_depth > 0.0)
+            ? t.rpt_full_volume * (y_new / t.full_depth) : 0.0;
     }
 
+    // An inlet junction floods (above) but is still a zero-storage node: the
+    // half-link surface area it carries is the continuity linearization of the
+    // adjacent conduits, not storage of its own, and node::getVolume would
+    // book the artificial MIN_SURFAREA junction volume the feature exists to
+    // remove (VJ plan D3; inlet plan §2.2.7 "no MIN_SURFAREA floor").
+    if (is_inlet_node) nodes.volume[ui] = 0.0;
+
     // --- Compute change in depth w.r.t. time (for CFL) ---
     if (dt > 0.0) {
         xnode_.dYdT[ui] = std::fabs(y_new - nodes.old_depth[ui]) / dt;
@@ -3672,7 +4294,10 @@ double DWSolver::getLinkStep(const SimulationContext& ctx, int link_idx) const {
     double a = area_mid_[uj];
     if (a <= FUDGE) return 1.0e10;
 
-    double L = CD.length[ucr];
+    // legacy dynwave.c:900 scales by modLength / link_getLength(i) — the
+    // denominator is the ROUTING length.
+    double L = CD.true_length[ucr];
+    if (L <= 0.0) L = CD.length[ucr];
     double modL = CD.mod_length[ucr];
     const double Lscale = (L > 0.0 && modL > 0.0) ? (modL / L) : 1.0;
 
@@ -3687,7 +4312,9 @@ double DWSolver::getLinkStep(const SimulationContext& ctx, int link_idx) const {
         if (ci >= 0) {
             auto uci = static_cast(ci);
             if (dps_.surcharged[uci] && L > 0.0) {
-                double v = q / a;                            // per-barrel velocity
+                // #144: conveyance area — the DPS slot stores, it does not
+                // convey, so it must not dilute the advective signal speed.
+                double v = q / conveyArea(a, ctx.links.xsect_a_full[uj]);
                 double P = std::max(dps_.P[uci], 1.0);
                 double c_p = dps_config_.c_pT / P;           // pressure celerity
                 double denom = std::fabs(v) + c_p;
diff --git a/src/engine/hydraulics/DynamicWave.hpp b/src/engine/hydraulics/DynamicWave.hpp
index 752de3599..37424aa18 100644
--- a/src/engine/hydraulics/DynamicWave.hpp
+++ b/src/engine/hydraulics/DynamicWave.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DynamicWave.hpp
  * @brief Dynamic wave routing solver — batch-oriented St. Venant equations.
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_DYNAMIC_WAVE_HPP
@@ -35,6 +51,7 @@
 #include "../data/LinkData.hpp"
 #include 
 #include 
+#include 
 #include 
 
 namespace openswmm {
@@ -141,7 +158,11 @@ struct DWNodeArrays {
 enum class SurchargeMethod : int {
     EXTRAN = 0,  ///< Classic EXTRAN approach — dQ/dH for surcharged nodes
     SLOT   = 1,  ///< Preissmann slot — fictitious narrow slot above crown
-    DYNAMIC_SLOT = 2   ///< Dynamic slot — slot width varies with flow conditions (experimental) Sharior, S., Hodges, B.R., & Vasconcelos, J.G. (2023). Generalized, Dynamic, and Transient-Storage Form of the Preissmann Slot. Journal of Hydraulic Engineering, 149(11), 04023046.
+    DYNAMIC_SLOT = 2,  ///< Dynamic slot — slot width varies with flow conditions (experimental) Sharior, S., Hodges, B.R., & Vasconcelos, J.G. (2023). Generalized, Dynamic, and Transient-Storage Form of the Preissmann Slot. Journal of Hydraulic Engineering, 149(11), 04023046.
+    TPA    = 3   ///< Two-component pressure approach (experimental, issue #156):
+                 ///< constant-width slot w = g·A_full/a² above the crown plus a
+                 ///< per-conduit sub-atmospheric latch below it. Vasconcelos,
+                 ///< Wright & Roe (2006), J. Hydraul. Eng. 132(6).
 };
 
 /**
@@ -178,12 +199,17 @@ class DWSolver {
      * @brief Set the number of OpenMP threads for parallel loops.
      *
      * @details Called after init() when the thread count is finalized.
-     *          A threshold is applied: if n_links < 4 * n, threading is
-     *          disabled (matching legacy dynwave.c behaviour).
+     *          Resolution (threadinfo::dwThreads): 0 = auto —
+     *          omp_get_max_threads(), the conduits-per-thread gate and the
+     *          Apple Silicon P-core clamp; N > 0 = honoured exactly, subject
+     *          only to the conduits-per-thread gate, with warnings when N
+     *          exceeds the machine / runtime limits. SWMM_DW_THREADS forces
+     *          the count outright (warned).
      *
-     * @param n  Requested thread count (0 = use omp_get_max_threads()).
+     * @param n         Requested thread count ([OPTIONS] THREADS).
+     * @param warnings  Optional sink for human-readable warnings.
      */
-    void setNumThreads(int n);
+    void setNumThreads(int n, std::vector* warnings = nullptr);
 
     /// Callback for computing non-conduit link flows inside the Picard loop.
     /// Parameters: (ctx, dt, picard_step) where step=0 is first iteration.
@@ -222,6 +248,30 @@ class DWSolver {
     NodeContinuity  node_continuity  = NodeContinuity::EXPLICIT;
     bool   anderson_accel = false;       ///< Enable Anderson acceleration
 
+    /// Unsteady friction (issue #156 Phase 3): 0 = NONE (default, bit-inert),
+    /// 1 = VITKOVSKY. Folded into the momentum denominator (so dqdh_ stays
+    /// consistent with the surcharge Jacobian) with the same dead-band and
+    /// half-momentum clamp as kernels::ufUpdate on the FV side.
+    int    unsteady_friction = 0;
+    double uf_k3 = 0.015;  ///< Brunone-type k3; consumed only when active.
+
+    /// TPA acoustic celerity a (PROJECT length units per second, converted to
+    /// ft/s at init like FV_SLOT_CELERITY). Sets the constant slot width
+    /// w_tpa = g·A_full/a² per conduit (TPA plan §B1). Issue #156.
+    double tpa_celerity = 100.0;
+
+    /// Cross-link ∂V/∂x stencil for UF (issue #156). A full link has equal
+    /// end areas, so the within-link |v2−v1| estimator is structurally ZERO
+    /// in exactly the pressurized cases UF exists for (measured: pure added
+    /// inertia, slight ANTI-damping). The gradient therefore comes from the
+    /// neighboring conduits' previous-iterate velocities across simple
+    /// degree-2 conduit junctions (links.flow is double-buffered within a
+    /// Picard iteration, so neighbor reads are deterministic at any thread
+    /// count). Built once in init() when unsteady_friction != 0; -1 = no
+    /// simple neighbor on that side (falls back one-sided / within-link).
+    std::vector    uf_nb_up_, uf_nb_dn_;
+    std::vector uf_sg_up_, uf_sg_dn_;   ///< +1 same sense, -1 opposed
+
     /// Evaporation rate (ft/s) — set by Router::step() each timestep so that
     /// solveMomentumBatch can recompute dq6 per Picard iteration (Gap #14).
     double evap_rate  = 0.0;
@@ -272,6 +322,11 @@ class DWSolver {
     // timestep, or per outfall update.
     // ------------------------------------------------------------------------
     std::vector    tile_uj_;            ///< == conduit_idx_, co-located with rest
+    /// ConduitData row of tile entry ci. NOT the tile index: conduit_idx_
+    /// skips DUMMY-shaped conduits, so every ConduitData array (length,
+    /// seep_rate, evap_loss_rate, inlet_control, …) must be indexed by this,
+    /// never by ci — the two only coincide on a deck with no DUMMY conduit.
+    std::vector    tile_crow_;
     std::vector    tile_n1_;            ///< links.node1[uj] for ci
     std::vector    tile_n2_;            ///< links.node2[uj]
     std::vector tile_inv1_elev_;     ///< nodes.invert_elev[node1]
@@ -284,7 +339,7 @@ class DWSolver {
     std::vector tile_w_max_;         ///< links.xsect_w_max
     std::vector tile_length_;        ///< cached_length_ = max(mod_length, length); used for arithmetic stability
     std::vector tile_inv_length_;    ///< inv_length_
-    std::vector tile_links_length_;  ///< raw ConduitData.length — used for volume calculations only
+    std::vector tile_links_length_;  ///< routing length (legacy link_getLength) — volume and the dq6 divisor
     std::vector tile_beta_;          ///< ConduitData.beta
     std::vector tile_q_max_;         ///< ConduitData.q_max
     std::vector tile_rough_factor_;  ///< ConduitData.rough_factor
@@ -316,6 +371,8 @@ class DWSolver {
     std::vector  tile_loss_outlet_;
     std::vector  tile_loss_avg_;     ///< ConduitData.loss_avg
     std::vector  tile_roughness_;    ///< ConduitData.roughness (force-main detection)
+    std::vector  tile_fm_sbot_;      ///< Force-main sBot rough factor (legacy link.c:1127-1131, incl. lengthFactor)
+    std::vector  tile_fm_rbot_;      ///< Force-main C / roughness height (xsect rBot) for the D-W friction factor
     std::vector tile_has_flap_gate_;
     std::vector  tile_direction_;
 
@@ -427,6 +484,17 @@ class DWSolver {
     std::vector   vj_pair_n1_;
     std::vector   vj_pair_n2_;
 
+    /// Wetting floor for a virtual junction that receives lateral inflow
+    /// (plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md): the pair's natural
+    /// half-link free-surface area evaluated at the seed depth
+    /// kVjWetSeedFrac · y_full, so an imposed lateral can wet a dry pair
+    /// without dividing dV by a vanishing area — and without the fixed
+    /// MIN_SURFAREA storage the feature exists to remove. max(natural, floor)
+    /// is continuous at the seed depth and inert above it. Zero for every
+    /// other node; read only when is_virtual && lat_flow != 0.
+    static constexpr double kVjWetSeedFrac = 0.02;
+    std::vector    vj_wet_floor_;
+
     /// Build vjunc_ / vj_of_link_ from topology (called from init(), post-CSR).
     void buildVirtualJunctionPairs(const SimulationContext& ctx);
     /// Per-Picard-iteration pair cache: shared sigma, upwind states, dq4j.
@@ -451,6 +519,7 @@ class DWSolver {
         double  ponded_area;
         double  sur_depth;
         double  full_volume;
+        double  rpt_full_volume; ///< legacy Node.fullVolume convention (NodeData::rpt_full_volume)
         int32_t degree;
         uint8_t is_storage;
         uint8_t is_outfall;
@@ -519,6 +588,12 @@ class DWSolver {
     void processDryLink(SimulationContext& ctx, double dt, std::size_t uj);
     void processManningLink(SimulationContext& ctx, double dt, int step,
                             std::size_t uj, MomentumCategory cat);
+    /// SWMM_TRACE_LINK term trace shared by the Manning and force-main kernels.
+    void traceLinkTerms(const SimulationContext& ctx, std::size_t uj,
+                        double qLast, double v, double sig, double rho,
+                        double aWtd, double rWtd, double dq1, double dq2,
+                        double dq3, double dq4, double dq5, double dq6,
+                        double qOld, double q, double aMidConv);
     void processForceMainLink(SimulationContext& ctx, double dt, int step,
                               std::size_t uj, MomentumCategory cat);
     void applyFlowLimits(SimulationContext& ctx, double dt, int step,
@@ -615,8 +690,6 @@ class DWSolver {
 
     // Preissmann slot helpers (matching legacy dwflow.c)
     double getSlotWidth(double y, double y_full, double w_max, XsectShape shape) const;
-    double getSlotArea(double y, double y_full, double a_full, double slot_width) const;
-    double getSlotHydRad(double y, double y_full, double r_full) const;
     double getCrownCutoff() const;
 
     // Dynamic Preissmann Slot (DPS) state and methods
@@ -627,6 +700,29 @@ class DWSolver {
     /// Apply DPS geometry overrides for surcharged conduits (replaces static slot in STEP E).
     void applyDPSGeometry(SimulationContext& ctx);
 
+    // -- TPA (SurchargeMethod::TPA, issue #156 Phase 5) ----------------------
+    /// Constant slot width g·A_full/a² per conduit (ft), from tpa_celerity.
+    std::vector tpa_w_;
+    /// Sub-atmospheric latch per conduit: while set, the conduit keeps
+    /// full-pipe geometry (signed slot line) even when node heads drop below
+    /// the crown — the latch's only job is preventing the free-surface
+    /// tables from reinterpreting a sealed head as a depth (TPA plan §B2).
+    std::vector tpa_latch_;
+    /// Latch transitions this routing step (for the AA skip walk, §B3).
+    std::vector tpa_latch_changed_;
+
+    /// Once per routing step, BEFORE the Picard loop (the operator stays
+    /// fixed within the iteration): set on isFull; clear on atmosphere
+    /// contact at an UNSUBMERGED vented end (P4's submergence lesson) or on
+    /// column separation (yMid < y_full − 30 ft).
+    void updateTpaLatch(SimulationContext& ctx);
+
+    /// DPS-style geometry override for TPA conduits (called where
+    /// applyDPSGeometry is): engaged when latched or above the crown —
+    /// area on the SIGNED slot line, width w_tpa, hyd radius r_full, slot
+    /// surface areas at both ends.
+    void applyTpaGeometry(SimulationContext& ctx);
+
     /// Update DPS temporal state after Picard convergence (P decay, t_s tracking).
     void updateDPSState(SimulationContext& ctx, double dt);
 
diff --git a/src/engine/hydraulics/Exfiltration.cpp b/src/engine/hydraulics/Exfiltration.cpp
index f632e764b..f345a88be 100644
--- a/src/engine/hydraulics/Exfiltration.cpp
+++ b/src/engine/hydraulics/Exfiltration.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Exfiltration.cpp
  * @brief Storage exfiltration — numerically identical to legacy exfil.c.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Exfiltration.hpp"
@@ -185,48 +201,78 @@ void ExfilSolver::computeAll(SimulationContext& ctx, double dt) {
         int ni = soa_.node_idx[uk];
         if (ni < 0) continue;
         auto uni = static_cast(ni);
+        // G-X2 one-owner rule: a storage node with a two-zone aquifer bed
+        // exchanges through the conductance channel instead.
+        if (uni < nodes.aquifer2d_bed.size() && nodes.aquifer2d_bed[uni]) {
+            const int sr0 = ctx.node_subtypes.storage_row(ni);
+            if (sr0 >= 0)
+                ctx.node_subtypes.storages.exfil_rate[static_cast(sr0)] = 0.0;
+            continue;
+        }
 
+        // Legacy storage_getLosses calls exfil_getLoss whenever the exfil
+        // object exists, INCLUDING at zero depth: the Green-Ampt state keeps
+        // evolving (recovering) through dry spells, and the volume cap in
+        // Router::initNodeFlows zeroes the booked loss on an empty node.
+        // Skipping dry nodes froze the GA state legacy keeps drying.
         double depth = nodes.depth[uni];
-        if (depth <= 0.0) continue;
 
         double total_loss = 0.0;
 
+        // legacy exfil_getLoss (exfil.c): the Green-Ampt object is always
+        // evaluated as MOD_GREEN_AMPT (no inter-event reset of F), with the
+        // global InfilFactor (the monthly conductivity adjustment) and the
+        // evaporation recovery factor; a zero IMDmax means a constant
+        // rate Ks * hydconFactor. Evaluated as plain GREEN_AMPT at factor
+        // 1, the pond of infiltration-detetention-pond lost ~0 where legacy
+        // drains 0.8 cfs.
+        const double infil_factor    = ctx.climate_state.infil_factor;
+        const double recovery_factor = ctx.climate_state.recovery_factor;
+        auto ga_rate = [&](infil::GreenAmptState& ga, double d) {
+            if (ga.IMDmax == 0.0) return ga.Ks * infil_factor;
+            return infil::grnampt_getInfil(ga, 0.0, d, dt, InfilModel::MOD_GREEN_AMPT,
+                                           infil_factor, recovery_factor);
+        };
+
         // Bottom exfiltration
-        double btm_rate = infil::grnampt_getInfil(soa_.btm_ga[uk], 0.0, depth, dt);
-        total_loss += btm_rate * soa_.btm_area[uk];
-
-        // Bank exfiltration (only above bank_min_depth)
-        if (depth > soa_.bank_min_depth[uk] && soa_.bank_max_area[uk] > 0.0) {
-            double bank_depth;
-            if (depth > soa_.bank_max_depth[uk]) {
-                bank_depth = depth - soa_.bank_max_depth[uk]
-                           + (soa_.bank_max_depth[uk] - soa_.bank_min_depth[uk]) / 2.0;
-            } else {
-                bank_depth = (depth - soa_.bank_min_depth[uk]) / 2.0;
-            }
+        total_loss += ga_rate(soa_.btm_ga[uk], depth) * soa_.btm_area[uk];
 
-            // Cap bank area at bank_max_area (matching legacy exfil.c line 191:
-            // area = MIN(area, exfil->bankMaxArea))
+        // Bank exfiltration (only above bank_min_depth): the bank area is
+        // the surface area (capped at the largest area the curve reaches)
+        // LESS the bottom area (exfil.c:191 `MIN(area, bankMaxArea) -
+        // btmArea`), and only when positive.
+        if (depth > soa_.bank_min_depth[uk]) {
             double area = openswmm::node::getSurfArea(ctx.nodes, soa_.node_idx[uk], depth,
                                             &ctx.tables,
                                             openswmm::ucf::getUnitSystem(static_cast(ctx.options.flow_units)),
                                             &ctx.node_subtypes);
-            double bank_area = std::min(area, soa_.bank_max_area[uk]);
-            double bank_rate = infil::grnampt_getInfil(soa_.bank_ga[uk], 0.0, bank_depth, dt);
-            total_loss += bank_rate * bank_area;
+            area = std::min(area, soa_.bank_max_area[uk]) - soa_.btm_area[uk];
+            if (area > 0.0) {
+                double bank_depth = depth;
+                if (soa_.bank_ga[uk].IMDmax != 0.0) {
+                    if (depth > soa_.bank_max_depth[uk]) {
+                        bank_depth = depth - soa_.bank_max_depth[uk]
+                                   + (soa_.bank_max_depth[uk] - soa_.bank_min_depth[uk]) / 2.0;
+                    } else {
+                        bank_depth = (depth - soa_.bank_min_depth[uk]) / 2.0;
+                    }
+                }
+                total_loss += area * ga_rate(soa_.bank_ga[uk], bank_depth);
+            }
         }
 
-        // Limit to available volume
-        double max_loss = nodes.volume[uni] / dt;
-        total_loss = std::min(total_loss, max_loss);
-
-        // Write pre-computed exfil volume (ft3) into the side-table for
-        // Router::initNodeFlows. Volume is reduced through the routing continuity
-        // equation (nodes.losses) rather than here, so that evap + exfil are
-        // jointly capped to available storage before advancing the timestep.
+        // Hand the RAW rate (cfs) to Router::initNodeFlows, which applies
+        // legacy's single joint evap+exfil cap (node.c storage_getLosses:
+        // ratio = newVolume / ((evapRate + exfilRate) * tStep), both rates
+        // scaled by the ratio of the UNCAPPED values) and books the final
+        // exfil_loss volume. Pre-capping here fed the joint cap a clamped
+        // rate — a different split and different bits whenever a near-dry
+        // storage's fresh Green-Ampt rate exceeded the stored volume — and
+        // the old volume*dt/dt round-trip perturbed the rate by an ULP on
+        // every step (greenville-epa's node 83 at its first wetting).
         const int sr = ctx.node_subtypes.storage_row(static_cast(uni));
         if (sr >= 0)
-            ctx.node_subtypes.storages.exfil_loss[static_cast(sr)] = total_loss * dt;
+            ctx.node_subtypes.storages.exfil_rate[static_cast(sr)] = total_loss;
     }
 }
 
diff --git a/src/engine/hydraulics/Exfiltration.hpp b/src/engine/hydraulics/Exfiltration.hpp
index e45c98b71..a944dfa7e 100644
--- a/src/engine/hydraulics/Exfiltration.hpp
+++ b/src/engine/hydraulics/Exfiltration.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Exfiltration.hpp
  * @brief Storage node exfiltration — Green-Ampt bottom/bank seepage.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_EXFILTRATION_HPP
diff --git a/src/engine/hydraulics/ForceMain.cpp b/src/engine/hydraulics/ForceMain.cpp
index 14b637cd2..72306279b 100644
--- a/src/engine/hydraulics/ForceMain.cpp
+++ b/src/engine/hydraulics/ForceMain.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ForceMain.cpp
  * @brief Force main friction — numerically identical to legacy forcmain.c.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ForceMain.hpp"
@@ -44,20 +60,26 @@ double getFricSlope_DW(double velocity, double hyd_rad, double roughness) {
 
 double getFricFactor(double r_bot, double hrad, double re) {
     if (hrad <= 0.0) return 0.0;
-    double diameter = 4.0 * hrad;
-    if (re <= 0.0) {
-        // Fully turbulent approximation (Colebrook at Re→∞)
-        re = 1.0e12;
-    }
+    // Legacy forcmain.c forcemain_getFricFactor, bit-exact (Swamee-Jain
+    // approximation to Colebrook-White). The three arms — laminar, the
+    // transitional 2000
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_FORCEMAIN_HPP
diff --git a/src/engine/hydraulics/HydClosureKernels.hpp b/src/engine/hydraulics/HydClosureKernels.hpp
index eb19f5f10..45af41d89 100644
--- a/src/engine/hydraulics/HydClosureKernels.hpp
+++ b/src/engine/hydraulics/HydClosureKernels.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydClosureKernels.hpp
  * @brief Portable scalar closures shared by the host solvers and the device
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_HYD_CLOSURE_KERNELS_HPP
diff --git a/src/engine/hydraulics/HydStructures.cpp b/src/engine/hydraulics/HydStructures.cpp
index 3542bf09d..77d61bf74 100644
--- a/src/engine/hydraulics/HydStructures.cpp
+++ b/src/engine/hydraulics/HydStructures.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydStructures.cpp
  * @brief Non-conduit link flow — batch by type, numerically identical to legacy.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "HydStructures.hpp"
@@ -13,8 +29,11 @@
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
 #include "../math/SIMD.hpp"
+#include "Divider.hpp"
 #include "Node.hpp"
 #include "XSectBatch.hpp"
+#include "Link.hpp"
+#include "Roadway.hpp"
 #include 
 #include 
 #include 
@@ -28,9 +47,48 @@ extern long g_trace_rstep_sn;
 
 namespace hydstruct {
 
+// PARITY link.c:1836-1845 (orifice), 2266-2275 (weir), 2664-2673 (outlet).
+// Legacy reads the tailwater head from the DOWNSTREAM node only under DW:
+//     if ( RouteModel == DW ) h2 = Node[n2].newDepth + Node[n2].invertElev;
+//     else                    h2 = Node[n1].invertElev;
+// Steady and Kinematic Wave routing carry no downstream head — they route on
+// a tree layout where a link's flow can only depend on its upstream end — so
+// every structure discharges freely to its own upstream invert. Using the
+// DW form under KW/SF submerges a structure against whatever depth its
+// downstream junction happened to reach, which is not information KW has.
+// FV keeps the DW form: it does solve for downstream head.
+static inline double tailwaterHead(const SimulationContext& ctx,
+                                   std::size_t un1, std::size_t un2) {
+    const auto rm = ctx.options.routing_model;
+    if (rm == RoutingModel::KINWAVE || rm == RoutingModel::STEADY)
+        return ctx.nodes.invert_elev[un1];
+    return ctx.nodes.depth[un2] + ctx.nodes.invert_elev[un2];
+}
+
+// PARITY link.c:646-673 link_setFlapGate. Both halves, in legacy's order.
+bool flapGateBlocks(const SimulationContext& ctx, int j, int n1, int n2, double q) {
+    const auto uj = static_cast(j);
+
+    // --- reverse flow through the link's own flap gate
+    if (ctx.links.has_flap_gate[uj] &&
+        q * static_cast(ctx.links.direction[uj]) < 0.0)
+        return true;
+
+    // --- gated OUTFALL on the INFLOW end of the link. q == 0 selects neither
+    //     end, matching legacy's `n = -1` initialisation.
+    int n = -1;
+    if (q < 0.0) n = n2;
+    if (q > 0.0) n = n1;
+    if (n < 0) return false;
+    if (ctx.nodes.type[static_cast(n)] != NodeType::OUTFALL) return false;
+    const int ofr = ctx.node_subtypes.outfall_row(n);
+    return ofr >= 0 &&
+           ctx.node_subtypes.outfalls.has_flap_gate[static_cast(ofr)] != 0;
+}
+
 void PumpGroup::resize(int n)    { count=n; auto u=static_cast(n); link_idx.resize(u); curve_idx.resize(u,-1); curve_type.resize(u,0); speed.resize(u,1.0); y_on.resize(u,0); y_off.resize(u,0); }
-void OrificeGroup::resize(int n) { count=n; auto u=static_cast(n); link_idx.resize(u); shape.resize(u,0); c_orifice.resize(u,0); c_weir.resize(u,0); h_crit.resize(u,0); has_flap.resize(u,false); surf_area.resize(u,0); length_eff.resize(u,0); }
-void WeirGroup::resize(int n)    { count=n; auto u=static_cast(n); link_idx.resize(u); weir_type.resize(u,0); c_disch1.resize(u,0); c_disch2.resize(u,0); end_con.resize(u,0); slope.resize(u,0); cd_curve.resize(u,-1); has_flap.resize(u,false); surf_area.resize(u,0); length_eff.resize(u,0); can_surcharge.resize(u,1); }
+void OrificeGroup::resize(int n) { count=n; auto u=static_cast(n); link_idx.resize(u); shape.resize(u,0); surf_area.resize(u,0); length_eff.resize(u,0); }
+void WeirGroup::resize(int n)    { count=n; auto u=static_cast(n); link_idx.resize(u); weir_type.resize(u,0); c_disch1.resize(u,0); c_disch2.resize(u,0); end_con.resize(u,0); slope.resize(u,0); cd_curve.resize(u,-1); road_width.resize(u,0); road_surface.resize(u,0); surf_area.resize(u,0); length_eff.resize(u,0); can_surcharge.resize(u,1); }
 void OutletGroup::resize(int n)  { count=n; auto u=static_cast(n); link_idx.resize(u); curve_idx.resize(u,-1); q_coeff.resize(u,0); q_expon.resize(u,1); }
 
 void StructureSolver::init(SimulationContext& ctx) {
@@ -88,7 +146,13 @@ void StructureSolver::init(SimulationContext& ctx) {
                     if (tt >= 7 && tt <= 11)
                         pumps_.curve_type[uk] = tt - 6; // 7→1, 8→2, 9→3, 10→4, 11→5
                     else
-                        pumps_.curve_type[uk] = 6; // Ideal pump if no curve
+                        pumps_.curve_type[uk] = 6; // curve present but not a pump type
+                } else {
+                    // No curve ('*' in [PUMPS]) => IDEAL_PUMP (legacy link.c:81).
+                    // Without this the type stayed 0, matched no case in
+                    // computePumpFlowK, and the pump conveyed nothing — its inlet
+                    // node filled instead of draining (e.g. longfm node T).
+                    pumps_.curve_type[uk] = 6;
                 }
                 // Mirror curve_type for use by DW non_conduit_fn (TYPE4_PUMP
                 // excluded from dqdh per legacy dynwave.c:565-575). Phase 6
@@ -102,31 +166,18 @@ void StructureSolver::init(SimulationContext& ctx) {
             case LinkType::ORIFICE: {
                 auto uk = static_cast(io);
                 orifices_.link_idx[uk] = j;
-                orifices_.has_flap[uk] = ctx.links.has_flap_gate[uj];
 
-                // Pre-compute orifice coefficients matching legacy orifice.c
-                // c_orifice = Cd * A_full * sqrt(2g)  (full orifice flow)
-                // c_weir = Cw * L                      (weir-like partial flow)
-                // h_crit = A_full / L                  (transition depth)
+                // No init-time cOrif/cWeir/hCrit snapshot: legacy
+                // orifice_setSetting derives them from the CURRENT setting,
+                // so computeOrificeFlowK computes them inline per call
+                // (legacy-exact, including the getWeirCoeff bottom/side
+                // split). See the OrificeGroup note in HydStructures.hpp.
                 using constants::GRAVITY;
-                double a_full = ctx.links.xsect_a_full[uj];
                 double y_full = ctx.links.xsect_y_full[uj];
-                double cd_val = ctx.link_subtypes.orifices.cd[
-                    static_cast(ctx.link_subtypes.orifice_row(j))];
-
-                orifices_.c_orifice[uk] = cd_val * a_full * std::sqrt(2.0 * GRAVITY);
-                // Weir coefficient for partially-open orifice
-                // Legacy: CW = Cd * L * sqrt(2g) where L = perimeter
-                // For rectangular: L = 2*(w+h), for circular: L = pi*d
-                double w_max = ctx.links.xsect_w_max[uj];
-                double perim = (w_max > 0.0 && y_full > 0.0)
-                    ? 2.0 * (w_max + y_full) : 3.14159 * y_full;
-                orifices_.c_weir[uk] = cd_val * perim * std::sqrt(2.0 * GRAVITY);
-                orifices_.h_crit[uk] = (perim > 0.0) ? a_full / perim : y_full;
                 // Equivalent length for SIDE-orifice surface-area scatter
                 // (legacy link.c:1724: max(200, 2·routingStep·sqrt(g·yFull))).
                 {
-                    double route_step = ctx.options.routing_step;
+                    double route_step = ctx.options.linkValidateRoutingStep();
                     double L = 2.0 * route_step * std::sqrt(GRAVITY * y_full);
                     orifices_.length_eff[uk] = std::max(200.0, L);
                 }
@@ -142,9 +193,11 @@ void StructureSolver::init(SimulationContext& ctx) {
                 weirs_.c_disch1[uk]   = W.cd[wr];   // RAW (see PARITY note above)
                 weirs_.c_disch2[uk]   = W.cd2[wr];  // RAW end-section coeff
                 weirs_.can_surcharge[uk] = W.can_surcharge[wr];
-                weirs_.has_flap[uk]   = ctx.links.has_flap_gate[uj];
                 weirs_.weir_type[uk]  = static_cast(W.weir_type[wr]);
                 weirs_.end_con[uk]    = W.end_contractions[wr];
+                weirs_.cd_curve[uk]     = W.cd_curve[wr];
+                weirs_.road_width[uk]   = W.road_width[wr];
+                weirs_.road_surface[uk] = W.road_surface[wr];
                 // V-notch / trapezoidal side slope comes from the cross-section,
                 // not from the INP weir row. Legacy: Weir[k].slope = xsect.sBot
                 // (populated by weir_validate). SIDEFLOW / TRANSVERSE → 0.
@@ -154,7 +207,7 @@ void StructureSolver::init(SimulationContext& ctx) {
                 {
                     using constants::GRAVITY;
                     double y_full = ctx.links.xsect_y_full[uj];
-                    double route_step = ctx.options.routing_step;
+                    double route_step = ctx.options.linkValidateRoutingStep();
                     double L = 2.0 * route_step * std::sqrt(GRAVITY * y_full);
                     weirs_.length_eff[uk] = std::max(200.0, L);
                 }
@@ -176,12 +229,17 @@ void StructureSolver::init(SimulationContext& ctx) {
         }
     }
 
-    // Build flat index of all non-conduit links for fast iteration
+    // Build flat index of all non-conduit links for fast iteration.
+    // DUMMY-xsect conduits belong here too: legacy isTrueConduit
+    // (dynwave.c:411-414) is false for them, so findLinkFlows routes them
+    // through findNonConduitFlow in link-index order — their flow is the
+    // upstream node's inflow + overflow, not a momentum solve.
     nc_indices_.clear();
     nc_indices_.reserve(static_cast(n_pumps + n_orifices + n_weirs + n_outlets));
     for (int j = 0; j < ctx.n_links(); ++j) {
         auto uj = static_cast(j);
-        if (ctx.links.type[uj] != LinkType::CONDUIT)
+        if (ctx.links.type[uj] != LinkType::CONDUIT ||
+            ctx.links.xsect_shape[uj] == XsectShape::DUMMY)
             nc_indices_.push_back(j);
     }
 
@@ -303,14 +361,20 @@ void StructureSolver::computePumpFlowK(SimulationContext& ctx, double dt,
                     q = table_intervalLookup(ctx.tables.tables[uci], depth * ucf_len);
                 }
                 break;
-            case 3: // Head-based with speed
-            case 5: {
-                double s = links.setting[uj];
+            case 3: // Head-based: Q = f(head) — PUMP3_CURVE
+            case 5: {  // Variable speed: Q = f(head/s²) — PUMP5_CURVE
+                // Legacy pump_getInflow PUMP3/PUMP5: s stays 1.0 for a PUMP3
+                // curve — ONLY PUMP5 reads the live speed setting (affinity
+                // scaling head/s² before the lookup). The setting multiplies
+                // the flow exactly ONCE, after the switch (legacy
+                // `return qIn * Link[j].setting`) — no *s here, or a
+                // fractional speed lands as s²·Curve instead of s·Curve.
+                double s = (ct == 5) ? links.setting[uj] : 1.0;
                 double h = (s > 0.0) ? std::max(head / (s * s), 0.0) : 0.0;
                 if (ci >= 0 && uci < ctx.tables.tables.size()) {
                     auto& curve = ctx.tables.tables[uci];
-                    q = table_lookup_cursor(curve, h * ucf_len) * s;
-                    // dQ/dh matching legacy pump.c PUMP3/5 lines 1606-1609:
+                    q = table_lookup_cursor(curve, h * ucf_len);
+                    // dQ/dh matching legacy link.c PUMP3/5:
                     //   Link[j].dqdh = -table_getSlope(&Curve[m], head)
                     //                  * UCF(LENGTH) / UCF(FLOW) / s
                     // sign reversed because flow decreases with increasing head.
@@ -338,8 +402,15 @@ void StructureSolver::computePumpFlowK(SimulationContext& ctx, double dt,
         }
 
         q = std::max(q, 0.0);
-        // Convert from display flow units to CFS (matching legacy / UCF(FLOW))
-        q /= ucf_flow;
+        // Convert from display flow units to CFS (matching legacy / UCF(FLOW)).
+        // The curve pumps (1-5) yield flow in display units; the ideal pump (6)
+        // already yields CFS (it is the node inflow), so it must NOT be divided
+        // again — legacy pump_getInflow applies UCF(FLOW) only inside the curve
+        // cases, never to IDEAL_PUMP (link.c:81-82). Under non-CFS units this
+        // spurious division shrank the ideal pump ~UCF-fold, so its inlet node
+        // filled instead of draining (e.g. longfm node T under LPS). No-op for
+        // CFS (ucf_flow == 1), so CFS decks stay bit-identical.
+        if (ct != 6) q /= ucf_flow;
         q *= links.setting[uj];
 
         // Limit pump flow to prevent inlet node from going dry
@@ -351,7 +422,14 @@ void StructureSolver::computePumpFlowK(SimulationContext& ctx, double dt,
                 // volume doesn't go negative. Legacy uses oldVolume (the
                 // start-of-step volume), not the current-iter volume, to
                 // avoid cascading clamps across Picard iterations.
-                if (nodes.full_volume[un1] > 0.0) {
+                // Legacy node_getMaxOutflow tests Node.fullVolume, which is 0
+                // for a junction wet well unless a Type-1 pump gave it the
+                // curve's max volume; the dynamic wave books volume in that
+                // convention (NodeData::rpt_full_volume), FV in full_volume.
+                const double full_vol =
+                    (ctx.options.routing_model == RoutingModel::DYNWAVE)
+                        ? nodes.rpt_full_volume[un1] : nodes.full_volume[un1];
+                if (full_vol > 0.0) {
                     double max_q = nodes.inflow[un1] + nodes.old_volume[un1] / dt;
                     if (q > max_q) q = max_q;
                 }
@@ -385,10 +463,11 @@ void StructureSolver::computePumpFlowK(SimulationContext& ctx, double dt,
 // Helper: build XSectParams from link SoA data
 // ============================================================================
 
-static XSectParams buildXSP(const LinkData& links, std::size_t uk) {
+static XSectParams buildXSP(const SimulationContext& ctx, std::size_t uk) {
+    const LinkData& links = ctx.links;
     XSectParams xs{};
     auto ls = links.xsect_shape[uk];
-    xs.type = (ls == XsectShape::DUMMY) ? 0 : static_cast(ls) + 1;
+    xs.type = link::translateShape(ls);
     xs.y_full = links.xsect_y_full[uk];
     xs.a_full = links.xsect_a_full[uk];
     xs.w_max  = links.xsect_w_max[uk];
@@ -399,6 +478,25 @@ static XSectParams buildXSP(const LinkData& links, std::size_t uk) {
     xs.a_bot  = links.xsect_a_bot[uk];
     xs.s_bot  = links.xsect_s_bot[uk];
     xs.r_bot  = links.xsect_r_bot[uk];
+    // Tabulated shapes (IRREGULAR / CUSTOM / STREET) carry their A/R/W vs depth
+    // in per-link transect tables; without them every scalar getter returns 0.
+    // Under KW that made getAofS's Newton walk its whole bracket and report the
+    // conduit's FULL inlet area for a trickle of inflow (1710-2014-20year-r3's
+    // transect channels), so the upstream node depth came out full instead of
+    // ~2 mm. Same block as DynamicWave.cpp::buildXSP.
+    if (ls == XsectShape::IRREGULAR || ls == XsectShape::CUSTOM ||
+        ls == XsectShape::STREET_XSECT) {
+        const int ci = links.xsect_curve[uk];
+        if (ci >= 0 && static_cast(ci) < ctx.transect_tables.size()) {
+            const auto& td = ctx.transect_tables[static_cast(ci)];
+            xs.transect          = ci;
+            xs.area_tbl          = td.area_tbl;
+            xs.hrad_tbl          = td.hrad_tbl;
+            xs.width_tbl         = td.width_tbl;
+            xs.area_lut          = &td.area_lut;
+            xs.transect_tbl_size = transect::N_TRANSECT_TBL;
+        }
+    }
     return xs;
 }
 
@@ -469,18 +567,23 @@ void StructureSolver::computeOrificeFlowK(SimulationContext& ctx,
         double y_full = links.xsect_y_full[uj];
         double cd_val = ctx.link_subtypes.orifices.cd[static_cast(ctx.link_subtypes.orifice_row(j))];
         double h_open = setting * y_full;
-        if (h_open < FUDGE_ORI) {
+        if (setting == 0.0) {
             links.flow[uj] = 0.0;
             // PARITY link.c:553: legacy link_getInflow early-returns on
-            // setting == 0 WITHOUT touching newDepth — a closed orifice's
-            // reported depth stays FROZEN at its last open-state value.
-            // (links.depth deliberately not zeroed here.)
-            orifices_.surf_area[uk] = 0.0;
+            // setting == 0 (exactly — a tiny opening still runs the
+            // orifice equations) WITHOUT touching newDepth, flowClass or
+            // Orifice.surfArea — a closed orifice's reported depth stays
+            // FROZEN at its last open-state value, and findNonConduitSurfArea
+            // + updateNodeFlows still scatter that last open surface area
+            // to its end nodes every iteration. Zeroing it here dropped the
+            // closed bottom orifice's share of node 82309's surface area
+            // (extran3-bottom-orifice-pid, the step the PID shut it).
+            scatterOrificeSurfArea(ctx, node_new_surf_area, uk, uj, un1, un2);
             return;
         }
 
         // Use xsect::getAofY for proper cross-section area at partial opening
-        XSectParams xs = buildXSP(links, uj);
+        XSectParams xs = buildXSP(ctx, uj);
         double a_eff = xsect::getAofY(xs, h_open);
         double f_area = a_eff * std::sqrt(2.0 * GRAVITY);
         double cOrif = cd_val * f_area;
@@ -507,7 +610,7 @@ void StructureSolver::computeOrificeFlowK(SimulationContext& ctx,
 
         // --- Compute nodal heads (matching legacy orifice_getInflow) ---
         double h1 = nodes.depth[un1] + nodes.invert_elev[un1];
-        double h2 = nodes.depth[un2] + nodes.invert_elev[un2];
+        double h2 = tailwaterHead(ctx, un1, un2);
         double dir = (h1 >= h2) ? 1.0 : -1.0;
 
         double y1 = nodes.depth[un1];
@@ -551,8 +654,9 @@ void StructureSolver::computeOrificeFlowK(SimulationContext& ctx,
             return;
         }
 
-        // Flap gate: block reverse flow
-        if (links.has_flap_gate[uj] && dir < 0.0) {
+        // Flap gate: the link's own gate OR a gated outfall on the inflow end
+        // (legacy link.c:1895 passes `dir` to link_setFlapGate).
+        if (flapGateBlocks(ctx, j, n1, n2, dir)) {
             links.flow[uj] = 0.0;
             links.depth[uj] = 0.0;
             links.dqdh[uj] = 0.0;
@@ -658,15 +762,17 @@ void StructureSolver::computeOrificeFlowK(SimulationContext& ctx,
                     std::snprintf(fname, sizeof(fname), "%s.orif%ld", tr, of_target);
                     of = std::fopen(fname, "w");
                     if (of) std::fprintf(of,
-                        "h1,h2,hcrest,hcrown,f,head,cWeir,cOrif,hCrit,dqdh,q\n");
+                        "h1,h2,hcrest,hcrown,f,head,cWeir,cOrif,hCrit,dqdh,q,surfArea,length,newDepth\n");
                 }
             }
             if (of && j == of_target &&
                 (of_step <= 0 || g_trace_rstep_sn + 1 >= of_step) && of_rows < 128) {
                 ++of_rows;
-                std::fprintf(of, "%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a\n",
+                std::fprintf(of, "%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a\n",
                              h1, h2, hcrest, hcrown, f, head,
-                             cWeir, cOrif, hCrit, dqdh, q * dir);
+                             cWeir, cOrif, hCrit, dqdh, q * dir,
+                             orifices_.surf_area[uk], orifices_.length_eff[uk],
+                             links.depth[uj]);
                 if (of_rows >= 128) { std::fclose(of); of = nullptr; }
             }
         }
@@ -710,13 +816,52 @@ void StructureSolver::computeWeirFlowK(SimulationContext& ctx,
         auto un1 = static_cast(n1);
         auto un2 = static_cast(n2);
 
+        // legacy link_getInflow (link.c:553): a closed link carries no flow
+        // and its routine is not called — depth, flow class and surface
+        // area stay at their last open values (dqdh was zeroed by the
+        // caller, as findNonConduitFlow does).
+        if (links.setting[uj] == 0.0) {
+            links.flow[uj] = 0.0;
+            (void)node_new_surf_area;
+            return;
+        }
+
         double hgl1 = nodes.depth[un1] + nodes.invert_elev[un1];
-        double hgl2 = nodes.depth[un2] + nodes.invert_elev[un2];
+        double hgl2 = tailwaterHead(ctx, un1, un2);
         double dir = (hgl1 >= hgl2) ? 1.0 : -1.0;
 
-        // Flap gate check — legacy link_setFlapGate: if forward flow blocked,
-        // zero flow. Our has_flap_gate flag matches the legacy sense.
-        if (links.has_flap_gate[uj] && dir < 0.0) {
+        // ROADWAY weir — legacy weir_getInflow hands the swapped heads and
+        // the DESIGN crest (invert + offset, no setting adjustment) to
+        // roadway_getInflow before the flap-gate test, the surface-area
+        // update and the surcharge branches; its surfArea stays at
+        // weir_validate's 0. Ran as a TRANSVERSE weir with the written Cd
+        // (extran4-roadway's 90010, first overtopping step 0.0144 vs
+        // legacy's HDS-5 0.0124 cfs).
+        if (weirs_.weir_type[uk] == 4) {
+            // legacy: dir = (h1 > h2) ? +1 : -1 — equal heads run in
+            // reverse, and the submerged HDS-5 flow is not zero there.
+            dir = (hgl1 > hgl2) ? 1.0 : -1.0;
+            if (dir < 0.0) std::swap(hgl1, hgl2);
+            const double h_road = nodes.invert_elev[un1]
+                + ctx.link_subtypes.weirs.crest_height[static_cast(ctx.link_subtypes.weir_row(j))];
+            const bool si = ucf::getUnitSystem(static_cast(ctx.options.flow_units)) == 1;
+            double dqdh_r = 0.0, depth_r = 0.0;
+            links.flow[uj] = roadway::getInflow(dir, h_road, hgl1, hgl2,
+                                                weirs_.c_disch1[uk], si,
+                                                weirs_.road_width[uk],
+                                                weirs_.road_surface[uk],
+                                                links.xsect_w_max[uj],
+                                                dqdh_r, depth_r);
+            links.dqdh[uj]  = dqdh_r;
+            links.depth[uj] = depth_r;
+            weirs_.surf_area[uk] = 0.0;
+            (void)node_new_surf_area;
+            return;
+        }
+
+        // Flap gate check — legacy link_setFlapGate (link.c:2303 passes `dir`):
+        // the link's own gate OR a gated outfall on the inflow end.
+        if (flapGateBlocks(ctx, j, n1, n2, dir)) {
             links.flow[uj] = 0.0;
             links.depth[uj] = 0.0;
             links.dqdh[uj] = 0.0;
@@ -752,11 +897,14 @@ void StructureSolver::computeWeirFlowK(SimulationContext& ctx,
             return;
         }
 
-        double cd     = weirs_.c_disch1[uk];
+        const double cd_written = weirs_.c_disch1[uk];
         double cd2    = weirs_.c_disch2[uk];
         double length = links.xsect_w_max[uj];
         int    wt     = weirs_.weir_type[uk];
-        const bool flap = weirs_.has_flap[uk] != 0;
+        // The ARMCO head loss keys on the LINK's own gate only — legacy passes
+        // Link[j].hasFlapGate into weir_getFlow (link.c:2343) rather than
+        // calling link_setFlapGate, so an outfall gate must NOT trigger it.
+        const bool flap = links.has_flap_gate[uj] != 0;
         double q = 0.0;
 
         // PARITY link.c weir_getFlow (2323-2412): legacy evaluates the weir
@@ -774,6 +922,15 @@ void StructureSolver::computeWeirFlowK(SimulationContext& ctx,
             if (head_ft <= 0.0) return;
             double lengthD = length * ucfL;
             double h = head_ft * ucfL;
+            // legacy weir_getFlow: a discharge-coefficient curve (the
+            // [WEIRS] line's 13th column) replaces cDisch1 with its value at
+            // the head in DISPLAY units.
+            double cd = cd_written;
+            if (weirs_.cd_curve[uk] >= 0) {
+                const auto uci = static_cast(weirs_.cd_curve[uk]);
+                if (uci < ctx.tables.tables.size())
+                    cd = table_lookup_cursor(ctx.tables.tables[uci], h);
+            }
             // Partially-open V-notch behaves as a trapezoidal weir
             // (legacy link.c:2358-2360).
             int wType = wt;
@@ -1025,8 +1182,16 @@ void StructureSolver::computeOutletFlowK(SimulationContext& ctx, int k) {
         auto un1 = static_cast(n1);
         auto un2 = static_cast(n2);
 
+        // legacy link_getInflow (link.c:553): a closed outlet carries no
+        // flow and outlet_getInflow is not called — its depth stays at the
+        // last open value (the setting multiplies the flow only when open).
+        if (links.setting[uj] == 0.0) {
+            links.flow[uj] = 0.0;
+            return;
+        }
+
         double h1 = nodes.depth[un1] + nodes.invert_elev[un1];
-        double h2 = nodes.depth[un2] + nodes.invert_elev[un2];
+        double h2 = tailwaterHead(ctx, un1, un2);
         int dir = (h1 >= h2) ? 1 : -1;
 
         // Track which node provides the upstream depth (legacy: y1 is
@@ -1040,7 +1205,13 @@ void StructureSolver::computeOutletFlowK(SimulationContext& ctx, int k) {
         // Crest elevation is a physical feature of the outlet — ALWAYS
         // referenced to n1's invert regardless of flow direction. Matches
         // legacy link.c:2650  hcrest = Node[n1].invertElev + Link[j].offset1.
-        double hcrest = nodes.invert_elev[un1] + links.offset1[uj];
+        // The outlet's offset lives in its side table (parsed, unit
+        // converted and WARNING-10-raised there); links.offset1 is 0 for an
+        // outlet, so every [OUTLETS] offset was ignored (21 corpus decks;
+        // dividers-in-dynamic-wave's Under5 opened 0.25 m early).
+        const int olr_c = ctx.link_subtypes.outlet_row(j);
+        double hcrest = nodes.invert_elev[un1]
+            + ((olr_c >= 0) ? ctx.link_subtypes.outlets.crest_height[static_cast(olr_c)] : 0.0);
 
         // Effective head — NODE_HEAD (functional/tabular head-based) outlets
         // in DW routing account for downstream submergence via
@@ -1056,8 +1227,9 @@ void StructureSolver::computeOutletFlowK(SimulationContext& ctx, int k) {
         double head = depth_based
                         ? (h1 - hcrest)
                         : (h1 - std::max(h2, hcrest));
-        // Flap gate (closed against reverse flow)
-        bool blocked_by_flap = (links.has_flap_gate[uj] && dir < 0);
+        // Flap gate (closed against reverse flow) — the link's own gate OR a
+        // gated outfall on the inflow end (legacy link.c:2697 passes `dir`).
+        bool blocked_by_flap = flapGateBlocks(ctx, j, n1, n2, dir);
 
         if (head <= FUDGE_OUT || y1 <= FUDGE_OUT || blocked_by_flap) {
             links.flow[uj] = 0.0;
@@ -1068,10 +1240,13 @@ void StructureSolver::computeOutletFlowK(SimulationContext& ctx, int k) {
         }
 
         // Rating curve is indexed on user-units of length (legacy calls
-        // UCF(LENGTH) before the table lookup).
-        double lookup_val = depth_based
-                                ? (y1 * ucf_len)
-                                : (head * ucf_len);
+        // UCF(LENGTH) before the table lookup) — on the HEAD for both curve
+        // types (outlet_getFlow(k, head)): a NODE_DEPTH curve's head is the
+        // depth above the outlet's crest, not the node depth (the two
+        // differ once the crest sits above the invert —
+        // dividers-in-dynamic-wave's raised Under5 rated 0.96 L/s at 0.25 m
+        // of node depth where legacy rates 0.0063 at 1.6 mm of head).
+        double lookup_val = head * ucf_len;
 
         double q = 0.0;
         int ci = outlets_.curve_idx[uk];
@@ -1134,6 +1309,35 @@ void StructureSolver::computeNonConduitFlowOne(SimulationContext& ctx, double dt
                                                double* node_new_surf_area,
                                                int link_idx) {
     auto uj = static_cast(link_idx);
+
+    // DUMMY conduit (legacy isTrueConduit == false): findNonConduitFlow →
+    // link_getInflow → conduit_getInflow — node_getOutflow's dispatch
+    // (DIVIDER split, else the upstream node's inflow + overflow) passes
+    // straight through, capped by the conduit's MaxFlow (link.c:1323-1333);
+    // a closed setting carries no flow (link.c:553). The STORAGE branch is
+    // unreachable for dummies — a storage node cannot have a dummy outflow
+    // link (link.c:1006 raises an input error).
+    // Surface area: findNonConduitSurfArea (dynwave.c:498) contributes 0
+    // for anything but an orifice, so there is nothing to scatter.
+    if (ctx.links.type[uj] == LinkType::CONDUIT) {
+        ctx.links.dqdh[uj] = 0.0;
+        double q = 0.0;
+        if (ctx.links.setting[uj] != 0.0) {
+            const int n1 = ctx.links.node1[uj];
+            if (n1 >= 0) {
+                const auto un1 = static_cast(n1);
+                if (ctx.nodes.type[un1] == NodeType::DIVIDER)
+                    q = divider::getOutflow(ctx, n1, link_idx);
+                else
+                    q = ctx.nodes.inflow[un1] + ctx.nodes.overflow[un1];
+            }
+            const double qlim = ctx.links.q_limit[uj];
+            if (qlim > 0.0 && q > qlim) q = qlim;
+        }
+        ctx.links.flow[uj] = q;
+        return;
+    }
+
     int k = (uj < nc_group_k_.size()) ? nc_group_k_[uj] : -1;
     if (k < 0) return;
 
diff --git a/src/engine/hydraulics/HydStructures.hpp b/src/engine/hydraulics/HydStructures.hpp
index 902603656..5cdf2f4b9 100644
--- a/src/engine/hydraulics/HydStructures.hpp
+++ b/src/engine/hydraulics/HydStructures.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydStructures.hpp
  * @brief Non-conduit link flow: pumps, orifices, weirs, outlets.
@@ -26,7 +42,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_HYD_STRUCTURES_HPP
@@ -50,6 +66,34 @@ namespace hydstruct {
 constexpr double GRAVITY = 32.2;
 constexpr double FUDGE   = 0.0001;
 
+// ============================================================================
+// Flap gates
+// ============================================================================
+
+/**
+ * @brief Is flow through link @p j blocked by a flap gate?
+ *
+ * @details Mirrors legacy `link_setFlapGate` (link.c:646-673), which applies
+ *          TWO independent tests and is called from all four link-flow paths
+ *          (dwflow.c:332 for conduits, link.c:1895/2303/2697 for
+ *          orifice/weir/outlet):
+ *
+ *          1. The link's OWN gate ([LOSSES] col 5, or the `Gated` column on
+ *             an orifice/weir/outlet) blocks flow opposing `links.direction`.
+ *          2. A gated OUTFALL on the link's INFLOW end blocks any flow that
+ *             would leave that outfall and enter the network — regardless of
+ *             whether the link itself carries a gate.
+ *
+ *          Test (2) is why this must be a shared predicate rather than an
+ *          inline `has_flap_gate` check: three structure kernels previously
+ *          implemented only test (1), so a tide gate modelled as a gated
+ *          outfall with an orifice or weir on it admitted reverse flow.
+ *
+ * @param q Signed flow (or a bare direction indicator — magnitude and units
+ *          are irrelevant, only the sign is read).
+ */
+bool flapGateBlocks(const SimulationContext& ctx, int j, int n1, int n2, double q);
+
 // ============================================================================
 // Per-type SoA groups (like XSectGroups but for structure types)
 // ============================================================================
@@ -69,13 +113,12 @@ struct OrificeGroup {
     int count = 0;
     std::vector    link_idx;
     std::vector    shape;         ///< BOTTOM or SIDE
-    std::vector c_orifice;     ///< Cd * sqrt(2g) * Area
-    std::vector c_weir;        ///< Cd * L * sqrt(2g) for partial fill
-    std::vector h_crit;        ///< Transition depth
-    std::vector has_flap;     ///< Flap gate (uint8_t, not bool: avoids
-                                       ///< vector bit-packing overhead in
-                                       ///< per-iteration hot loops and enables
-                                       ///< parallel-for writes without atomics).
+    // No cached cOrif/cWeir/hCrit: legacy orifice_setSetting recomputes them
+    // from the CURRENT setting every step, so computeOrificeFlowK derives
+    // them inline per call (see the legacy-exact block there) — an init-time
+    // snapshot at full opening could only ever go stale.
+    // No cached flap-gate flag: the kernels read ctx.links.has_flap_gate (and
+    // flapGateBlocks) directly, so a stale init-time snapshot cannot diverge.
     /// Most-recently-computed surface area (ft²) for scatter into node
     /// new_surf_area (matches legacy Orifice[k].surfArea).
     std::vector surf_area;
@@ -89,13 +132,15 @@ struct OrificeGroup {
 struct WeirGroup {
     int count = 0;
     std::vector    link_idx;
-    std::vector    weir_type;     ///< TRANSVERSE/SIDE/VNOTCH/TRAPEZOIDAL
+    std::vector    weir_type;     ///< TRANSVERSE/SIDE/VNOTCH/TRAPEZOIDAL/ROADWAY (0..4)
     std::vector c_disch1;      ///< Main discharge coefficient
     std::vector c_disch2;      ///< End section coefficient (trapezoidal)
     std::vector end_con;       ///< End contraction factor
     std::vector slope;         ///< V-notch slope or trap slope
-    std::vector    cd_curve;      ///< Optional Cd(head) curve index
-    std::vector has_flap;     ///< See comment on OrificeGroup::has_flap.
+    std::vector    cd_curve;      ///< Optional Cd(head) curve index (legacy Weir.cdCurve), -1 none
+    std::vector road_width;    ///< ROADWAY weir road width (ft, legacy Weir.roadWidth)
+    std::vector    road_surface;  ///< ROADWAY weir surface: 0 none, 1 PAVED, 2 GRAVEL
+    // No cached flap-gate flag — see the note on OrificeGroup.
     /// Most-recently-computed surface area (ft²), populated by
     /// computeWeirFlows and scattered to node surface-area accumulators
     /// by the non_conduit_fn callback. Matches legacy Weir[k].surfArea.
diff --git a/src/engine/hydraulics/Inlet.cpp b/src/engine/hydraulics/Inlet.cpp
index 8337e42ec..2738ce51b 100644
--- a/src/engine/hydraulics/Inlet.cpp
+++ b/src/engine/hydraulics/Inlet.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Inlet.cpp
  * @brief Street inlet capture — numerically identical to legacy inlet.c.
@@ -5,54 +21,116 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Inlet.hpp"
+#include "Link.hpp"
+#include "XSectBatch.hpp"
+#include "../core/Constants.hpp"
 #include "../core/SimulationContext.hpp"
+#include "../core/UnitConversion.hpp"
 #include "../data/InfraData.hpp"
-#include 
+#include "../data/TableData.hpp"
 #include 
-#include 
+#include 
+#include 
 
 namespace openswmm {
 namespace inlet {
 
-// Minimum flow threshold (matches legacy MIN_RUNOFF_FLOW = 2.5e-5 cfs)
-static constexpr double MIN_FLOW = 2.5e-5;
+// ============================================================================
+// Constant tables (HEC-22 charts, legacy inlet.c:152-170)
+// ============================================================================
+
+// Cubic fits to the Splash-Over Velocity vs. Grate Length curves of HEC-22
+// Chart 5B. PARITY NOTE: legacy declares this table with SEVEN rows for EIGHT
+// grate types (inlet.c:152-159) — a GENERIC grate index would read past the
+// end. Legacy never does because every caller special-cases GENERIC, but the
+// out-of-range read is one memcpy away; getSplashOverVelocity() guards it here
+// instead of relying on the callers.
+static const double SPLASH_COEFFS[7][4] = {
+    {2.22, 4.03, 0.65, 0.06},     // P_BAR-50
+    {0.74, 2.44, 0.27, 0.02},     // P_BAR-50x100
+    {1.76, 3.12, 0.45, 0.03},     // P_BAR-30
+    {0.30, 4.85, 1.31, 0.15},     // CURVED_VANE
+    {0.99, 2.64, 0.36, 0.03},     // TILT_BAR-45
+    {0.51, 2.34, 0.20, 0.01},     // TILT_BAR-30
+    {0.28, 2.28, 0.18, 0.01},     // RETICULINE
+};
+
+// Grate opening ratios (HEC-22 Chart 9B, inlet.c:162-170)
+static const double GRATE_OPEN_RATIOS[8] = {
+    0.90,     // P_BAR-50
+    0.80,     // P_BAR-50x100
+    0.60,     // P_BAR-30
+    0.35,     // CURVED_VANE
+    0.17,     // TILT_BAR-45 (assumed)
+    0.34,     // TILT_BAR-30
+    0.80,     // RETICULINE
+    1.00,     // GENERIC
+};
+
+// ============================================================================
+// InletSoA
+// ============================================================================
 
 void InletSoA::resize(int n) {
     count = n;
-    auto un = static_cast(n);
+    auto un = static_cast(n);
+
     link_idx.assign(un, -1);
+    host_node.assign(un, -1);
     node_idx.assign(un, -1);
     bypass_node.assign(un, -1);
-    inlet_type.assign(un, 0);
-    grate_type.assign(un, 0);
+    up_link.assign(un, -1);
+    up_link2.assign(un, -1);
+    two_inbound.assign(un, uint8_t{0});
+
+    inlet_type.assign(un, static_cast(InletType::CUSTOM));
+    grate_type.assign(un, static_cast(GrateType::GENERIC));
     grate_length.assign(un, 0.0);
     grate_width.assign(un, 0.0);
+    open_area.assign(un, 0.0);
+    splash_veloc.assign(un, 0.0);
     curb_length.assign(un, 0.0);
     curb_height.assign(un, 0.0);
-    curb_throat.assign(un, 0);
+    curb_throat.assign(un, static_cast(ThroatAngle::VERTICAL));
     slotted_length.assign(un, 0.0);
     slotted_width.assign(un, 0.0);
-    clog_factor.assign(un, 1.0);
-    opening_ratio.assign(un, 1.0);
+    curve_index.assign(un, -1);
+    curve_kind.assign(un, static_cast(CurveKind::UNRESOLVED));
+
     num_inlets.assign(un, 1);
+    clog_factor.assign(un, 1.0);
     flow_limit.assign(un, 0.0);
     local_depress.assign(un, 0.0);
     local_width.assign(un, 0.0);
-    n_sides.assign(un, 1);
+    placement.assign(un, static_cast(Placement::AUTOMATIC));
+    is_sag.assign(un, uint8_t{0});
+
     sx.assign(un, 0.01);
     gutter_depression.assign(un, 0.0);
     gutter_width.assign(un, 0.0);
-    road_roughness.assign(un, 0.013);
-    t_crown.assign(un, 0.0);
+    road_roughness.assign(un, 0.016);
+    t_crown.assign(un, 100.0);
+    n_sides.assign(un, 1);
+    slope.assign(un, 0.0);
+    flow_factor.assign(un, 0.0);
+
+    q_approach.assign(un, 0.0);
     flow_capture.assign(un, 0.0);
-    // Gap #56
-    backflow_ratio.assign(un, 0.0);
     backflow.assign(un, 0.0);
-    // Gap #68
+    backflow_ratio.assign(un, 0.0);
+
+    flow_periods.assign(un, 0);
+    capture_periods.assign(un, 0);
+    backflow_periods.assign(un, 0);
+    peak_flow.assign(un, 0.0);
+    peak_flow_capture.assign(un, 0.0);
+    avg_flow_capture.assign(un, 0.0);
+    bypass_freq.assign(un, 0.0);
+
     stat_capture_vol.assign(un, 0.0);
     stat_bypass_vol.assign(un, 0.0);
     stat_backflow_vol.assign(un, 0.0);
@@ -60,787 +138,1163 @@ void InletSoA::resize(int n) {
 }
 
 // ============================================================================
-// Splash-over velocity coefficients per grate type (HEC-22 Chart 5B)
+// Pure kernel — 1:1 ports of the legacy static functions
 // ============================================================================
 
-// Corrected coefficients from legacy inlet.c (SplashCoeffs)
-static const double SPLASH_COEFFS[][4] = {
-    {2.22, 4.03, 0.65, 0.06},     // P_BAR_50
-    {0.74, 2.44, 0.27, 0.02},     // P_BAR_50x100
-    {1.76, 3.12, 0.45, 0.03},     // P_BAR_30
-    {0.30, 4.85, 1.31, 0.15},     // CURVED_VANE
-    {0.99, 2.64, 0.36, 0.03},     // TILT_BAR_45
-    {0.51, 2.34, 0.20, 0.01},     // TILT_BAR_30
-    {0.28, 2.28, 0.18, 0.01},     // RETICULINE
-    {0.00, 0.00, 0.00, 0.00},     // GENERIC (no splash-over limit)
-};
-
-// Grate opening ratios (HEC-22 Chart 9B)
-static const double GRATE_OPEN_RATIOS[] = {
-    0.90,     // P_BAR_50
-    0.80,     // P_BAR_50x100
-    0.60,     // P_BAR_30
-    0.35,     // CURVED_VANE
-    0.17,     // TILT_BAR_45 (assumed)
-    0.34,     // TILT_BAR_30
-    0.80,     // RETICULINE
-    1.00,     // GENERIC
-};
-
-// ============================================================================
-// Static helper methods
-// ============================================================================
-
-double InletSolver::splashOverVelocity(double L, int gt) {
-    if (gt < 0 || gt >= 7) {
-        if (gt == 7) return 0.0;  // GENERIC: no splash-over limit handled by caller
-        return 100.0;
-    }
-    const auto& c = SPLASH_COEFFS[gt];
-    return c[0] + c[1] * L - c[2] * L * L + c[3] * L * L * L;
-}
-
-double InletSolver::computeEo(double sr, double ts, double w) {
-    // HEC-22 Eq 4-4: gutter flow ratio
-    if (w <= 0.0 || ts <= 0.0) return 1.0;
-    double x = sr / (ts / w);
-    x = std::pow(1.0 + x, 2.67) - 1.0;
-    x = 1.0 + sr / x;
+double getEo(double Sr, double Ts, double w) {
+    // HEC-22 Eq(4-4) with Ts/w substituted for (T/w) − 1 (inlet.c:1248).
+    double x = Sr / (Ts / w);
+    x = std::pow((1.0 + x), 2.67) - 1.0;
+    x = 1.0 + Sr / x;
     return 1.0 / x;
 }
 
-double InletSolver::computeFlowSpread(double Q, double qfactor,
-                                       double sx, double sw, double a_gutter,
-                                       double w_gutter, double t_crown) {
-    // Izzard's form of Manning equation for triangular gutter: Q = qfactor * T^(8/3)
-    // qfactor = (0.56 / n) * SL^0.5 * Sx^(5/3)
-    double f = qfactor;
+double getFlowSpread(const Geom& g, double Q) {
+    // inlet.c:1200 — Izzard's form of Manning's equation, Q = f·T^2.67.
+    const double f = g.qfactor;
     double Ts1;
 
-    if (a_gutter == 0.0) {
-        // No depressed curb
-        Ts1 = std::pow(Q / f, 0.375);                           // HEC-22 Eq(4-2)
+    if (g.a == 0.0) {
+        Ts1 = std::pow(Q / f, 0.375);                       // HEC-22 Eq(4-2)
     } else {
-        // Check if spread is within curb width
-        double f1 = f * std::pow((a_gutter / w_gutter) / sx, 1.67);
-        double Tw = std::pow(Q / f1, 0.375);                    // HEC-22 Eq(4-2)
-        if (Tw <= w_gutter) {
+        // --- check if spread is within curb width
+        const double f1 = f * std::pow((g.a / g.w) / g.sx, 1.67);
+        const double Tw = std::pow(Q / f1, 0.375);          // HEC-22 Eq(4-2)
+        if (Tw <= g.w) {
             Ts1 = Tw;
         } else {
-            // Spread extends beyond curb width — iterative solution
-            double Sr = sw / sx;
+            // --- spread extends beyond curb width
+            const double Sr = (g.sx + g.a / g.w) / g.sx;
             int iter = 1;
-            Ts1 = std::pow(Q / f, 0.375) - w_gutter;
-            if (Ts1 <= 0.0) Ts1 = Tw - w_gutter;
-            double Ts2 = Ts1;
+            double Ts2 = 0.0;
+            Ts1 = std::pow(Q / f, 0.375) - g.w;
+            if (Ts1 <= 0) Ts1 = Tw - g.w;
             while (iter < 11) {
-                double Eo = computeEo(Sr, Ts1, w_gutter);
-                double Qs = (1.0 - Eo) * Q;                     // HEC-22 Eq(4-6)
-                Ts2 = std::pow(Qs / f, 0.375);                  // HEC-22 Eq(4-2)
+                const double Eo = getEo(Sr, Ts1, g.w);
+                const double Qs = (1.0 - Eo) * Q;           // HEC-22 Eq(4-6)
+                Ts2 = std::pow(Qs / f, 0.375);              // HEC-22 Eq(4-2)
                 if (std::fabs(Ts2 - Ts1) < 0.01) break;
                 Ts1 = Ts2;
                 iter++;
             }
-            Ts1 = Ts2 + w_gutter;
+            Ts1 = Ts2 + g.w;
         }
     }
-    return std::min(Ts1, t_crown);
+    return std::min(Ts1, g.t_crown);
 }
 
-double InletSolver::grateCapture(double flow, double velocity, double length,
-                                  double sx, int grate_type, double open_ratio) {
-    if (flow <= 0.0 || velocity <= 0.0) return 0.0;
+double getGutterFlowRatio(const Geom& g, double w) {
+    // inlet.c:1518
+    if (g.t <= w) return 1.0;
+    else if (g.a > 0.0) return getEo(g.sw / g.sx, g.t - w, w);
+    else return 1.0 - std::pow((1.0 - w / g.t), 2.67);      // HEC-22 Eq(4-16)
+}
 
-    double Vo;
-    if (grate_type < 0 || grate_type == static_cast(GrateType::GENERIC))
-        Vo = 0.0;  // No splash-over limit for generic
-    else
-        Vo = splashOverVelocity(length, grate_type);
+double getGutterAreaRatio(const Geom& g, double Wg, double A) {
+    // inlet.c:1535
+    if (Wg >= g.w)  return 1.0;
+    if (g.t <= Wg)  return 1.0;
+    if (g.t <= g.w) return Wg / g.t;
+    const double As = 0.5 * (g.t - g.w) * (g.t - g.w) * g.sx;
+    const double Ag = Wg * ((g.t * g.sx) + g.a - (Wg * g.sw / 2.0));
+    return Ag / (A - As);
+}
+
+double getSplashOverVelocity(int grate_type, double L) {
+    // inlet.c:1557. GENERIC (and any out-of-range code) has no fitted curve —
+    // its splash-over velocity is the user-supplied value on the design.
+    if (grate_type < 0 || grate_type >= 7) return 0.0;
+    const auto gt = static_cast(grate_type);
+    return SPLASH_COEFFS[gt][0] +
+           SPLASH_COEFFS[gt][1] * L -
+           SPLASH_COEFFS[gt][2] * L * L +
+           SPLASH_COEFFS[gt][3] * L * L * L;
+}
+
+/// Grate open-area ratio for a design (legacy GrateOpeningRatios lookup with
+/// the GENERIC/out-of-range guard the 7-row SplashCoeffs table lacks).
+static double grateOpenRatio(const Design& d) {
+    const int gt = d.grate_type;
+    if (gt < 0 || gt >= static_cast(GrateType::GENERIC))
+        return d.frac_open_area;
+    return GRATE_OPEN_RATIOS[static_cast(gt)];
+}
+
+double getGrateInletCapture(const Design& d, Geom& g, double Q) {
+    // inlet.c:1387. g.t (spread), g.a, g.w and g.sx come from the caller
+    // exactly as legacy's shared T / a / W / Sx do.
+    const double Lg = d.grate_length;
+    double Wg = d.grate_width;
+    double A;                 // total cross-section flow area (ft2)
+    double Eo;                // ratio of gutter to total flow
+    double Qo = Q;            // flow over street area (cfs)
+    double Rf = 1.0;          // ratio of intercepted to total frontal flow
+    double Rs = 0.0;          // ratio of intercepted to total side flow
+
+    const bool channel = (g.xs != nullptr) &&
+        (g.xs->type == static_cast(XSectShape::TRAPEZOIDAL) ||
+         g.xs->type == static_cast(XSectShape::RECT_OPEN));
+
+    // --- flow ratio for drop inlet in a rectangular/trapezoidal channel
+    if (channel) {
+        A = xsect::getAofS(*g.xs, Q / g.beta);
+        const double Y = xsect::getYofA(*g.xs, A);
+        g.t = xsect::getWofY(*g.xs, Y);
+        Eo = g.beta * std::pow(Y * Wg, 1.67) / std::pow(Wg + 2 * Y, 0.67) / Q;
+        if (Wg > 0.99 * g.xs->y_bot &&
+            g.xs->type == static_cast(XSectShape::TRAPEZOIDAL) &&
+            g.xs->s_bot > 0.0) {
+            Wg   = g.xs->y_bot;
+            g.sx = 1.0 / g.xs->s_bot;
+        }
+    }
 
-    // Frontal flow capture efficiency (HEC-22 Eq 4-18)
-    double Rf = 1.0;
-    if (velocity > Vo)
-        Rf = 1.0 - 0.09 * (velocity - Vo);
+    // --- flow ratio & area for conventional street gutter
+    else if (g.a == 0.0) {
+        A  = g.t * g.t * g.sx / 2.0;
+        Eo = getGutterFlowRatio(g, Wg);   // flow ratio based on grate width
+        if (g.t >= g.t_crown) Qo = g.qfactor * std::pow(g.t_crown, 2.67);
+    }
 
-    // Side flow capture efficiency (HEC-22 Eq 4-19)
-    double Rs = 0.0;
-    if (sx > 0.0 && length > 0.0) {
-        Rs = 1.0 / (1.0 + 0.15 * std::pow(velocity, 1.8)
-                     / (sx * std::pow(length, 2.3)));
+    // --- flow ratio & area for composite street gutter
+    else {
+        if (g.t <= g.w) A = g.t * g.t * g.sw / 2.0;        // spread within gutter
+        else            A = (g.t * g.t * g.sx + g.a * g.w) / 2.0;
+
+        // flow ratio based on gutter width corrected for grate width
+        Eo = getGutterFlowRatio(g, g.w);
+        if (Eo < 1.0) {
+            if (g.t >= g.t_crown)
+                Qo = g.qfactor * std::pow(g.t_crown, 2.67) / (1.0 - Eo);
+            Eo = Eo * getGutterAreaRatio(g, Wg, A);        // HEC-22 Eq(4-20a)
+        }
     }
 
-    // Eo = frontal flow ratio = opening_ratio for grate
-    double Eo = open_ratio;
+    // --- flow and splash-over velocities
+    const double V = Qo / A;
+    double Vo;
+    if (d.grate_type < 0 || d.grate_type == static_cast(GrateType::GENERIC))
+        Vo = d.splash_veloc;
+    else
+        Vo = getSplashOverVelocity(d.grate_type, Lg);
+
+    // --- frontal flow capture efficiency
+    if (V > Vo) Rf = 1.0 - 0.09 * (V - Vo);                // HEC-22 Eq(4-18)
 
-    // HEC-22 Eq 4-21: total capture
-    return flow * (Rf * Eo + Rs * (1.0 - Eo));
+    // --- side flow capture efficiency
+    if (Eo < 1.0)
+        Rs = 1.0 / (1.0 + (0.15 * std::pow(V, 1.8) /
+             g.sx / std::pow(Lg, 2.3)));                   // HEC-22 Eq(4-19)
+
+    return Q * (Rf * Eo + Rs * (1.0 - Eo));                // HEC-22 Eq(4-21)
 }
 
-double InletSolver::curbCapture(double flow, double curb_length,
-                                 double sx, double sl, double n,
-                                 double gutter_depress, double gutter_width,
-                                 double spread) {
-    // HEC-22 Eq 4-22a/4-23: curb opening inlet capture
-    if (flow <= 0.0 || curb_length <= 0.0) return 0.0;
-
-    double Se = sx;   // equivalent gutter slope
-    double Sw = sx;
-    double a = gutter_depress;
-    double W = gutter_width;
-
-    // For depressed gutter section
-    if (a > 0.0 && W > 0.0) {
-        Sw = sx + a / W;
-        double Sr = Sw / sx;
-        double Ts = spread - W;
-        if (Ts > 0.0) {
-            double Eo = computeEo(Sr, Ts, W);
-            Se = sx + (a / W) * Eo;                              // HEC-22 Eq(4-24)
-        }
+double getCurbInletCapture(const Geom& g, double Q, double L) {
+    // inlet.c:1477
+    double Se = g.sx;     // equivalent gutter slope
+    double E  = 1.0;      // capture efficiency
+
+    // --- for depressed gutter section
+    if (g.a > 0.0) {
+        const double Sr = g.sw / g.sx;
+        const double Eo = getEo(Sr, g.t - g.w, g.w);
+        Se = g.sx + (g.a / g.w) * Eo;                      // HEC-22 Eq(4-24)
     }
 
-    // Opening length for full capture (HEC-22 Eq 4-22a)
-    double Lt = 0.6 * std::pow(flow, 0.42) * std::pow(sl, 0.3)
-                * std::pow(1.0 / (n * Se), 0.6);
+    // --- opening length for full capture
+    const double Lt = 0.6 * std::pow(Q, 0.42) * std::pow(g.sl, 0.3) *
+                      std::pow(1.0 / (g.n * Se), 0.6);     // HEC-22 Eq(4-22a)
 
-    // Capture efficiency for actual opening length (HEC-22 Eq 4-23)
-    double E = 1.0;
-    if (curb_length < Lt) {
-        E = 1.0 - curb_length / Lt;
-        E = 1.0 - std::pow(E, 1.8);
+    // --- capture efficiency for actual opening length
+    if (L < Lt) {
+        E = 1.0 - (L / Lt);
+        E = 1 - std::pow(E, 1.8);                          // HEC-22 Eq(4-23)
     }
     E = std::min(E, 1.0);
     E = std::max(E, 0.0);
-    return E * flow;
+    return E * Q;
 }
 
-// ============================================================================
-// On-grade capture for a single inlet (one call to this per inlet evaluation)
-// ============================================================================
-
-double InletSolver::computeOnGradeCapture(int idx, double flow, double /*depth*/) const {
-    if (flow <= MIN_FLOW) return 0.0;
-
-    int itype = soa_.inlet_type[idx];
-    double Sx_i  = soa_.sx[idx];
-    double a_i   = soa_.gutter_depression[idx] + soa_.local_depress[idx];
-    double W_i   = (soa_.local_width[idx] > 0.0) ? soa_.local_width[idx]
-                                                   : soa_.gutter_width[idx];
-    double n_i   = soa_.road_roughness[idx];
-    double Tc    = soa_.t_crown[idx];
-    double Sw_i  = (W_i * a_i > 0.0) ? Sx_i + a_i / W_i : Sx_i;
-
-    // Longitudinal slope from link
-    // We need slope; store it from link during init or compute it here
-    // For now we use link slope from soa (we'll compute qfactor)
-    // qfactor = (0.56 / n) * sqrt(SL) * Sx^(5/3)
-    // We need SL — store it during init. For now, derive from link.
-    // Actually, we don't have direct access to link slope in the SoA here,
-    // so we use qfactor that was computed during init.
-    // Let's instead just compute spread inline.
-
-    // Since we don't store slope directly in the InletSoA, we need it.
-    // We'll pass slope=0 and it will be used by caller. Actually, we
-    // need to store slope in the InletSoA. Let me check.
-    // We'll retrieve it from the link in computeAll() before calling this.
-    // For now, this function assumes qfactor is pre-computed.
-    // Actually, let's just pass the necessary vars. The function is const
-    // and accesses soa_. We need SL. Let's store it.
-
-    // This is a problem — we need SL from the link's slope.
-    // Since this is called from computeAll() which has ctx, we can
-    // just compute everything there. Let's refactor to compute inline.
-
-    // For now, return 0. The actual computation is done in computeAll().
-    (void)itype; (void)Sx_i; (void)a_i; (void)W_i; (void)n_i; (void)Tc; (void)Sw_i;
-    return 0.0;
-}
+double getOnGradeInletCapture(const Design& d, Geom& g, double Q, double depth) {
+    // inlet.c:1325
+    double Q1 = Q, Qc = 0.0;
 
-// ============================================================================
-// init() — populate InletSoA from ctx.inlet_usages and resolve geometry
-// ============================================================================
+    // --- drop curb inlet (in non-Street conduit) only operates in on-sag mode
+    if (d.type == static_cast(InletType::DROP_CURB)) {
+        Qc = getOnSagInletCapture(d, g, depth);
+        return std::min(Qc, Q);
+    }
 
-void InletSolver::init(SimulationContext& ctx) {
-    auto& usages = ctx.inlet_usages;
-    int n = usages.count();
-    if (n == 0) return;
+    // --- drop grate inlet (in non-Street conduit)
+    if (d.type == static_cast(InletType::DROP_GRATE)) {
+        Qc = getGrateInletCapture(d, g, Q);
+        return std::min(Qc, Q);
+    }
 
-    soa_.resize(n);
+    // --- remaining inlet types apply to Street conduits
+    g.t = getFlowSpread(g, Q);
 
-    for (int i = 0; i < n; ++i) {
-        int li = usages.link_index[i];
-        int di = usages.design_index[i];
-
-        soa_.link_idx[i]      = li;
-        soa_.node_idx[i]      = usages.node_index[i];
-        soa_.bypass_node[i]   = ctx.links.node2[li];  // downstream node
-        soa_.num_inlets[i]    = usages.num_inlets[i];
-        soa_.clog_factor[i]   = usages.clog_factor[i];
-        soa_.flow_limit[i]    = usages.flow_limit[i];
-        soa_.local_depress[i] = usages.local_depress[i];
-        soa_.local_width[i]   = usages.local_width[i];
-
-        // Resolve inlet design parameters
-        if (di >= 0 && di < ctx.inlets.count()) {
-            // Parse inlet type string to enum
-            const auto& type_str = ctx.inlets.inlet_type[di];
-            if (type_str == "GRATE")           soa_.inlet_type[i] = static_cast(InletType::GRATE);
-            else if (type_str == "CURB")        soa_.inlet_type[i] = static_cast(InletType::CURB);
-            else if (type_str == "COMBO")       soa_.inlet_type[i] = static_cast(InletType::COMBO);
-            else if (type_str == "SLOTTED")     soa_.inlet_type[i] = static_cast(InletType::SLOTTED);
-            else if (type_str == "DROP_GRATE")  soa_.inlet_type[i] = static_cast(InletType::DROP_GRATE);
-            else if (type_str == "DROP_CURB")   soa_.inlet_type[i] = static_cast(InletType::DROP_CURB);
-            else if (type_str == "CUSTOM")      soa_.inlet_type[i] = static_cast(InletType::CUSTOM);
-
-            soa_.grate_length[i] = ctx.inlets.length[di];
-            soa_.grate_width[i]  = ctx.inlets.width[di];
-
-            // Parse grate type string
-            const auto& gt_str = ctx.inlets.grate_type[di];
-            int gt = static_cast(GrateType::GENERIC);
-            if (gt_str == "P_BAR-50" || gt_str == "P_BAR_50")
-                gt = static_cast(GrateType::P_BAR_50);
-            else if (gt_str == "P_BAR-50x100" || gt_str == "P_BAR_50x100")
-                gt = static_cast(GrateType::P_BAR_50x100);
-            else if (gt_str == "P_BAR-30" || gt_str == "P_BAR_30")
-                gt = static_cast(GrateType::P_BAR_30);
-            else if (gt_str == "CURVED_VANE")
-                gt = static_cast(GrateType::CURVED_VANE);
-            else if (gt_str == "TILT_BAR-45" || gt_str == "TILT_BAR_45")
-                gt = static_cast(GrateType::TILT_BAR_45);
-            else if (gt_str == "TILT_BAR-30" || gt_str == "TILT_BAR_30")
-                gt = static_cast(GrateType::TILT_BAR_30);
-            else if (gt_str == "RETICULINE")
-                gt = static_cast(GrateType::RETICULINE);
-            soa_.grate_type[i] = gt;
-
-            // Set opening ratio from standard table or custom value
-            if (gt >= 0 && gt <= static_cast(GrateType::GENERIC)) {
-                soa_.opening_ratio[i] = GRATE_OPEN_RATIOS[gt];
-            }
-            if (ctx.inlets.open_area[di] > 0.0) {
-                soa_.opening_ratio[i] = ctx.inlets.open_area[di];
-            }
+    // --- slotted inlet (behaves as a curb opening inlet per HEC-22)
+    if (d.type == static_cast(InletType::SLOTTED)) {
+        Qc = getCurbInletCapture(g, Q, d.slotted_length);
+        return std::min(Qc, Q);
+    }
 
-            // For curb/combo inlets, the length field is curb length,
-            // width is curb height. These are set from the second design
-            // line in legacy. For simplicity, if type is CURB or COMBO,
-            // store curb dimensions.
-            if (soa_.inlet_type[i] == static_cast(InletType::CURB) ||
-                soa_.inlet_type[i] == static_cast(InletType::DROP_CURB)) {
-                soa_.curb_length[i] = ctx.inlets.length[di];
-                soa_.curb_height[i] = ctx.inlets.width[di];
-                soa_.grate_length[i] = 0.0;
-                soa_.grate_width[i] = 0.0;
-            }
+    const double Lcurb  = d.curb_length;
+    const double Lgrate = d.grate_length;
 
-            if (soa_.inlet_type[i] == static_cast(InletType::SLOTTED)) {
-                soa_.slotted_length[i] = ctx.inlets.length[di];
-                soa_.slotted_width[i]  = ctx.inlets.width[di];
-                soa_.grate_length[i] = 0.0;
-                soa_.grate_width[i] = 0.0;
-            }
+    // --- curb opening inlet (the sweeper length ahead of the grate)
+    if (Lcurb > 0.0) {
+        const double Lsweep = Lcurb - Lgrate;
+        if (Lsweep > 0.0) {
+            Qc = getCurbInletCapture(g, Q1, Lsweep);
+            Q1 -= Qc;
         }
+    }
 
-        // Resolve street geometry from the street store (if link has a street xsect)
-        int si = (usages.street_index.size() > static_cast(i))
-                 ? usages.street_index[i] : -1;
-        if (si >= 0 && si < ctx.streets.count()) {
-            soa_.sx[i]                = ctx.streets.sx[si];
-            soa_.gutter_depression[i] = ctx.streets.gutter_depres[si];
-            soa_.gutter_width[i]      = ctx.streets.gutter_width[si];
-            soa_.road_roughness[i]    = ctx.streets.n_road[si];
-            soa_.n_sides[i]           = ctx.streets.sides[si];
-            soa_.t_crown[i]           = ctx.streets.t_crown[si];
-        } else {
-            // Non-street conduit defaults
-            soa_.sx[i]                = 0.01;
-            soa_.gutter_depression[i] = 0.0;
-            soa_.gutter_width[i]      = 0.0;
-            {
-                const int cr = ctx.link_subtypes.conduit_row(li);
-                soa_.road_roughness[i] = (cr >= 0)
-                    ? ctx.link_subtypes.conduits.roughness[static_cast(cr)] : 0.01;
-            }
-            soa_.n_sides[i]           = 1;
-            soa_.t_crown[i]           = 100.0;  // effectively unlimited spread
-        }
+    // --- grate inlet
+    if (Lgrate > 0.0 && Q1 > 0.0) {
+        if (Q1 != Q) g.t = getFlowSpread(g, Q1);
+        Qc += getGrateInletCapture(d, g, Q1);
     }
+    return Qc;
+}
 
-    // Gap #56: pre-compute backflow ratios after all inlets are built
-    computeBackflowRatios();
+double getOnGradeCapturedFlow(const Design& d, const UsageParams& u, Geom& g,
+                              double q, double depth) {
+    // inlet.c:1267 — replicate inlets in series: each one sees the flow the
+    // previous ones bypassed.
+    if (u.num_inlets == 0) return 0.0;
+
+    double qApproach = q;
+    if (qApproach < MIN_RUNOFF_FLOW) return 0.0;
+
+    // --- adjust flow for 2-sided street
+    qApproach /= g.nsides;
+    double qBypassed = qApproach;
+    double qCaptured = 0.0;
+
+    // --- set limit on max. flow captured per inlet
+    double qMax = INLET_BIG;
+    if (u.flow_limit > 0.0) qMax = u.flow_limit;
+
+    for (int i = 1; i <= u.num_inlets; ++i) {
+        double qc = getOnGradeInletCapture(d, g, qBypassed, depth) * u.clog_factor;
+        qc = std::min(qc, qMax);
+        qc = std::min(qc, qBypassed);
+        qCaptured += qc;
+        qBypassed -= qc;
+        if (qBypassed < MIN_RUNOFF_FLOW) break;
+    }
+    return qCaptured * g.nsides;
 }
 
-// ============================================================================
-// computeAll() — batch compute inlet capture for all inlets
-// ============================================================================
+void findOnSagGrateFlows(const Design& d, const Geom& g, double depth,
+                         double* Qw, double* Qo) {
+    // inlet.c:1644
+    const double Lg = d.grate_length;
+    double Wg = d.grate_width;
+    double P;      // grate perimeter (ft)
+    double di;     // average flow depth across grate (ft)
+
+    // --- for drop grate inlets
+    if (d.type == static_cast(InletType::DROP_GRATE)) {
+        di = depth;
+        P  = 2.0 * (Lg + Wg);
+    }
+    // --- for gutter grate inlets
+    else {
+        if (depth <= Wg * g.sw) Wg = depth / g.sw;   // spread within grate width
+        di = depth - (Wg / 2.0) * g.sw;              // average depth over grate
+        P  = Lg + 2.0 * Wg;                          // effective grate perimeter
+    }
 
-void InletSolver::computeAll(SimulationContext& ctx, double dt) {
-    int ni = soa_.count;
-    if (ni == 0) return;
+    const double Ao = Lg * Wg * grateOpenRatio(d);   // grate opening area (ft2)
 
-    auto& links = ctx.links;
-    auto& nodes = ctx.nodes;
+    // --- weir flow applies (below the depth where the weir and orifice
+    //     equations agree), otherwise orifice flow
+    if (depth <= 1.79 * Ao / P)
+        *Qw = 3.0 * P * std::pow(di, 1.5);           // HEC-22 Eq(4-26)
+    else
+        *Qo = 0.67 * Ao * std::sqrt(2.0 * 32.16 * di); // HEC-22 Eq(4-27)
+}
 
-    // Working array: total captured flow per bypass node (for on-sag limiting)
-    // Use a temporary vector indexed by node
-    int nn = ctx.n_nodes();
-    std::vector inlet_flow_per_node(static_cast(nn), 0.0);
+double getCurbOrificeFlow(double di, double h, double L, int throat_angle) {
+    // inlet.c:1764
+    double d = di;
+    if (throat_angle == static_cast(ThroatAngle::HORIZONTAL))
+        d = di - h / 2.0;
+    else if (throat_angle == static_cast(ThroatAngle::INCLINED))
+        d = di - (h / 2.0) * 0.7071;
+    return 0.67 * h * L * std::sqrt(2.0 * 32.16 * d);  // HEC-22 Eq(4-31a)
+}
 
-    // First pass: compute capture for each inlet
-    for (int ii = 0; ii < ni; ++ii) {
-        soa_.flow_capture[ii] = 0.0;
-
-        int li = soa_.link_idx[ii];
-        if (li < 0 || li >= links.count()) continue;
-
-        int bypass = soa_.bypass_node[ii];  // downstream node of street conduit
-        int capture_node = soa_.node_idx[ii];
-        int itype = soa_.inlet_type[ii];
-
-        double q = std::fabs(links.flow[li]);
-        if (q < MIN_FLOW) continue;
-
-        // Get conduit geometry for this inlet
-        const int cr = ctx.link_subtypes.conduit_row(li);
-        double SL    = (cr >= 0) ? ctx.link_subtypes.conduits.slope[static_cast(cr)] : 0.0;
-        double Sx_i  = soa_.sx[ii];
-        double a_i   = soa_.gutter_depression[ii];
-        double W_i   = soa_.gutter_width[ii];
-        double n_i   = soa_.road_roughness[ii];
-        int nsides   = soa_.n_sides[ii];
-        double Tc    = soa_.t_crown[ii];
-
-        // Apply local depression
-        if (soa_.local_depress[ii] > 0.0 && soa_.local_width[ii] > 0.0) {
-            a_i += soa_.local_depress[ii];
-            W_i = soa_.local_width[ii];
+void findOnSagCurbFlows(const Design& d, const Geom& g, double depth, double L,
+                        double* Qw, double* Qo) {
+    // inlet.c:1703
+    const int    throat = d.curb_throat;
+    const double h      = d.curb_height;
+    double Qweir = 0.0, dweir;
+
+    if (L <= 0.0) return;
+    // A drop curb opening in a channel is open on all four sides.
+    if (d.type == static_cast(InletType::DROP_CURB)) L = L * 4.0;
+
+    // --- check for orifice flow
+    const double dorif = 1.4 * h;
+    if (depth > dorif) {
+        *Qo = getCurbOrificeFlow(depth, h, L, throat);
+        return;
+    }
+
+    // --- for uniform cross slope or very long opening
+    if (g.a == 0.0 || L > 12.0) {
+        dweir = h;
+        if (depth < dweir) {
+            *Qw = 3.0 * L * std::pow(depth, 1.5);          // HEC-22 Eq(4-30)
+            return;
+        }
+        Qweir = 3.0 * L * std::pow(dweir, 1.5);
+    }
+    // --- for depressed gutter
+    else {
+        const double P = L + 1.8 * g.w;
+        dweir = h + g.a;
+        if (depth < dweir) {
+            *Qw = 2.3 * P * std::pow(depth, 1.5);          // HEC-22 Eq(4-28)
+            return;
         }
+        Qweir = 2.3 * P * std::pow(dweir, 1.5);
+    }
+
+    // --- interpolate between Qweir at dweir and Qorif at dorif
+    const double Qorif = getCurbOrificeFlow(dorif, h, L, throat);
+    const double r = (depth - dweir) / (dorif - dweir);
+    *Qw = (1.0 - r) * Qweir;
+    *Qo = r * Qorif;
+}
+
+double getOnSagSlottedFlow(const Design& d, double depth) {
+    // inlet.c:1785 — weir flow = orifice flow at d = 2.587 · inlet width.
+    const double L = d.slotted_length;
+    const double w = d.slotted_width;
+    if (depth <= 2.587 * w)
+        return 2.48 * L * std::pow(depth, 1.5);            // HEC-22 Eq(4-32)
+    return 0.8 * L * w * std::sqrt(64.32 * depth);         // HEC-22 Eq(4-33)
+}
+
+double getOnSagInletCapture(const Design& d, const Geom& g, double depth) {
+    // inlet.c:1610
+    double Qsw = 0.0,   // sweeper curb opening weir flow
+           Qso = 0.0,   // sweeper curb opening orifice flow
+           Qgw = 0.0,   // grate weir flow
+           Qgo = 0.0,   // grate orifice flow
+           Qcw = 0.0,   // curb opening weir flow (deliberately not summed)
+           Qco = 0.0;   // curb opening orifice flow
+
+    if (d.slotted_length > 0.0) return getOnSagSlottedFlow(d, depth);
+
+    const double Lgrate = d.grate_length;
+    if (Lgrate > 0.0) findOnSagGrateFlows(d, g, depth, &Qgw, &Qgo);
+
+    const double Lcurb = d.curb_length;
+    if (Lcurb > 0.0) {
+        const double Lsweep = Lcurb - Lgrate;
+        if (Lsweep > 0.0) findOnSagCurbFlows(d, g, depth, Lsweep, &Qsw, &Qso);
+        if (Qgo > 0.0)    findOnSagCurbFlows(d, g, depth, Lgrate, &Qcw, &Qco);
+    }
+    // Qcw is excluded: once the grate is in orifice mode the curb opening over
+    // the grate can only add its orifice share (legacy inlet.c:1639).
+    (void)Qcw;
+    return Qgw + Qgo + Qsw + Qso + Qco;
+}
 
-        // Slope of depressed gutter section
-        double Sw_i = (W_i > 0.0 && a_i > 0.0) ? Sx_i + a_i / W_i : Sx_i;
+double getOnSagCapturedFlow(const Design& d, const UsageParams& u,
+                            const Geom& g, double depth, int nsides_prev) {
+    // inlet.c:1574. `totalInlets` is formed from the module-level Nsides as it
+    // stood on ENTRY — legacy computes it before getConduitGeometry() sets
+    // Nsides for this inlet, so it carries the previous inlet's street.
+    if (u.num_inlets == 0) return 0.0;
+    const int totalInlets = nsides_prev * u.num_inlets;
+
+    double qMax = INLET_BIG;
+    if (u.flow_limit > 0.0) qMax = u.flow_limit;
+
+    double qCaptured = getOnSagInletCapture(d, g, std::fabs(depth));
+    qCaptured *= u.clog_factor;
+    qCaptured = std::min(qCaptured, qMax);
+    qCaptured *= static_cast(totalInlets);
+    return qCaptured;
+}
 
-        // Qfactor = (0.56 / n) * SL^0.5 * Sx^(5/3)  (Izzard's equation factor)
-        double qfactor = 0.0;
-        if (n_i > 0.0 && SL > 0.0 && Sx_i > 0.0) {
-            qfactor = (0.56 / n_i) * std::sqrt(SL) * std::pow(Sx_i, 5.0 / 3.0);
+double getCustomCapturedFlow(const UsageParams& u, const Geom& g,
+                             const Table& curve, int curve_kind,
+                             double q, double depth,
+                             double ucf_flow, double ucf_len) {
+    // inlet.c:1902
+    if (u.num_inlets == 0) return 0.0;
+
+    double qMax = INLET_BIG;
+    if (u.flow_limit > 0.0) qMax = u.flow_limit;
+
+    // --- adjust flow for 2-sided street (1 for a non-Street conduit)
+    const int sides = g.nsides;
+    double qBypassed = q / sides;
+    double qCaptured = 0.0;
+
+    if (curve_kind == static_cast(CurveKind::DIVERSION)) {
+        // --- curve is captured flow v. approach flow
+        for (int j = 1; j <= u.num_inlets; ++j) {
+            double qIncrement = u.clog_factor *
+                table_lookupEx(curve, qBypassed * ucf_flow) / ucf_flow;
+            qIncrement = std::min(qIncrement, qMax);
+            qIncrement = std::min(qIncrement, qBypassed);
+            qCaptured += qIncrement;
+            qBypassed -= qIncrement;
+            if (qBypassed < MIN_RUNOFF_FLOW) break;
         }
+    } else if (curve_kind == static_cast(CurveKind::RATING)) {
+        // --- curve is captured flow v. downstream node depth
+        qCaptured = u.num_inlets * u.clog_factor *
+            table_lookupEx(curve, depth * ucf_len) / ucf_flow;
+    }
+    return qCaptured * sides;
+}
 
-        // Beta = 1.486 * sqrt(SL) / n  (Manning conveyance)
-        double beta_val = (n_i > 0.0 && SL > 0.0)
-                          ? 1.486 * std::sqrt(SL) / n_i : 0.0;
+double getInletArea(const Design& d, const UsageParams& u) {
+    // inlet.c:1870
+    double area = 0.0;
+    if (d.grate_length > 0.0)
+        area = d.grate_length * d.grate_width * grateOpenRatio(d);
 
-        // Adjust flow for 2-sided street
-        double qApproach = q / nsides;
-        double qBypassed = qApproach;
-        double qCaptured = 0.0;
+    const double curbLength = d.curb_length - d.grate_length;
+    if (curbLength > 0.0) area += curbLength * d.curb_height;
 
-        // Max capture per inlet
-        double qMax = (soa_.flow_limit[ii] > 0.0) ? soa_.flow_limit[ii] : 1.0e30;
+    if (d.slotted_length > 0.0) area = d.slotted_length * d.slotted_width;
 
-        int numInlets = soa_.num_inlets[ii];
-        if (numInlets <= 0) continue;
+    return area * u.num_inlets * u.clog_factor;
+}
 
-        // Evaluate each inlet sequentially (bypass flow reduces)
-        for (int k = 0; k < numInlets; ++k) {
-            if (qBypassed < MIN_FLOW) break;
+// ============================================================================
+// InletSolver — per-row accessors
+// ============================================================================
 
-            double qc = 0.0;
+Design InletSolver::designOf(int ii) const {
+    const auto ui = static_cast(ii);
+    Design d;
+    d.type           = soa_.inlet_type[ui];
+    d.grate_type     = soa_.grate_type[ui];
+    d.grate_length   = soa_.grate_length[ui];
+    d.grate_width    = soa_.grate_width[ui];
+    d.frac_open_area = soa_.open_area[ui];
+    d.splash_veloc   = soa_.splash_veloc[ui];
+    d.curb_length    = soa_.curb_length[ui];
+    d.curb_height    = soa_.curb_height[ui];
+    d.curb_throat    = soa_.curb_throat[ui];
+    d.slotted_length = soa_.slotted_length[ui];
+    d.slotted_width  = soa_.slotted_width[ui];
+    return d;
+}
 
-            // Compute flow spread for current approach flow
-            double T_spread = 0.0;
-            if (qfactor > 0.0) {
-                T_spread = computeFlowSpread(qBypassed, qfactor, Sx_i, Sw_i,
-                                              a_i, W_i, Tc);
-            }
+UsageParams InletSolver::usageOf(int ii) const {
+    const auto ui = static_cast(ii);
+    UsageParams u;
+    u.num_inlets  = soa_.num_inlets[ui];
+    u.clog_factor = soa_.clog_factor[ui];
+    u.flow_limit  = soa_.flow_limit[ui];
+    return u;
+}
 
-            // Flow area and velocity for grate capture
-            double A_flow = 0.0;
-            if (a_i == 0.0) {
-                A_flow = T_spread * T_spread * Sx_i / 2.0;
-            } else {
-                if (T_spread <= W_i) {
-                    A_flow = T_spread * T_spread * Sw_i / 2.0;
-                } else {
-                    A_flow = (T_spread * T_spread * Sx_i + a_i * W_i) / 2.0;
-                }
-            }
-            double V_flow = (A_flow > 0.0) ? qBypassed / A_flow : 0.0;
-
-            switch (static_cast(itype)) {
-            case InletType::GRATE:
-            case InletType::DROP_GRATE: {
-                // Grate-only capture
-                double Lg = soa_.grate_length[ii];
-                double Wg = soa_.grate_width[ii];
-                int gt    = soa_.grate_type[ii];
-
-                // Compute Eo (gutter flow ratio)
-                double Eo;
-                if (a_i == 0.0) {
-                    // Conventional gutter: Eo based on grate width
-                    if (T_spread <= Wg) Eo = 1.0;
-                    else Eo = 1.0 - std::pow(1.0 - Wg / T_spread, 2.67);
-                } else {
-                    // Composite gutter
-                    if (T_spread <= W_i) Eo = 1.0;
-                    else {
-                        double Sr = Sw_i / Sx_i;
-                        Eo = computeEo(Sr, T_spread - W_i, W_i);
-                    }
-                }
+Geom InletSolver::geomOf(const SimulationContext& ctx, int ii,
+                         const XSectParams* xs) const {
+    (void)ctx;
+    const auto ui = static_cast(ii);
+    Geom g;
+    g.sx      = soa_.sx[ui];
+    g.sl      = soa_.slope[ui];
+    g.a       = soa_.gutter_depression[ui];
+    g.w       = soa_.gutter_width[ui];
+    g.n       = soa_.road_roughness[ui];
+    g.nsides  = soa_.n_sides[ui];
+    g.t_crown = soa_.t_crown[ui];
+    g.qfactor = soa_.flow_factor[ui];
+    g.xs      = xs;
+
+    // --- add the inlet's local depression to the street's continuous one
+    //     (inlet.c:1175-1180)
+    if (soa_.local_depress[ui] * soa_.local_width[ui] > 0.0) {
+        g.a += soa_.local_depress[ui];
+        g.w  = soa_.local_width[ui];
+    }
 
-                // Splash-over velocity
-                double Vo;
-                if (gt < 0 || gt == static_cast(GrateType::GENERIC))
-                    Vo = (soa_.opening_ratio[ii] > 0.0) ? 100.0 : 0.0;
-                else
-                    Vo = splashOverVelocity(Lg, gt);
-
-                // Frontal flow capture efficiency (HEC-22 Eq 4-18)
-                double Rf = 1.0;
-                if (V_flow > Vo) Rf = 1.0 - 0.09 * (V_flow - Vo);
-
-                // Side flow capture efficiency (HEC-22 Eq 4-19)
-                double Rs = 0.0;
-                if (Eo < 1.0 && Sx_i > 0.0 && Lg > 0.0) {
-                    Rs = 1.0 / (1.0 + 0.15 * std::pow(V_flow, 1.8)
-                                / (Sx_i * std::pow(Lg, 2.3)));
-                }
+    // --- slope of depressed gutter section (inlet.c:1182-1183)
+    g.sw = (g.w * g.a > 0.0) ? g.sx + g.a / g.w : g.sx;
 
-                // HEC-22 Eq 4-21
-                qc = qBypassed * (Rf * Eo + Rs * (1.0 - Eo));
-                break;
-            }
+    // --- Beta = 1.486·√SL / n (Conduit[k].beta), used only by the channel
+    //     drop-grate branch of getGrateInletCapture.
+    g.beta = (g.n > 0.0 && g.sl > 0.0) ? 1.486 * std::sqrt(g.sl) / g.n : 0.0;
+    return g;
+}
+
+// ============================================================================
+// init() — resolve designs, geometry, host topology and placement
+// ============================================================================
 
-            case InletType::CURB:
-            case InletType::DROP_CURB: {
-                double Lc = soa_.curb_length[ii];
-                qc = curbCapture(qBypassed, Lc, Sx_i, SL, n_i,
-                                  a_i, W_i, T_spread);
-                break;
+void InletSolver::init(SimulationContext& ctx) {
+    auto& usages = ctx.inlet_usages;
+    const int n = usages.count();
+    soa_.resize(n);
+    if (n == 0) return;
+
+    const int nn = ctx.n_nodes();
+    const int nl = ctx.n_links();
+    node_inlet_flow_.assign(static_cast(nn), 0.0);
+    node_inflow_.assign(static_cast(nn), 0.0);
+    is_capture_node_.assign(static_cast(nn), uint8_t{0});
+
+    // Stores keep user (display) units; convert once here (same treatment the
+    // street transect builder gives StreetStore, PostParseResolver.cpp:2287).
+    const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    const double inv_len  = ucf::Ucf_inv[ucf::LENGTH][static_cast(us)];
+    const double inv_flow = ucf::Qcf_inv[static_cast(ctx.options.flow_units)];
+
+    // Legacy Node[].degree = outflow-link count (toposort.c:70-91), consulted
+    // by getInletPlacement for AUTOMATIC placement. ctx.nodes.degree is the DW
+    // hybrid (both ends counted), so rebuild the legacy quantity here.
+    std::vector out_degree(static_cast(nn), 0);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        int m = (ctx.links.direction[uj] < 0) ? ctx.links.node2[uj]
+                                              : ctx.links.node1[uj];
+        if (m < 0 || m >= nn) continue;
+        if (ctx.nodes.type[static_cast(m)] == NodeType::OUTFALL) {
+            m = (ctx.links.direction[uj] < 0) ? ctx.links.node1[uj]
+                                              : ctx.links.node2[uj];
+            if (m < 0 || m >= nn) continue;
+        }
+        out_degree[static_cast(m)]++;
+    }
+
+    for (int i = 0; i < n; ++i) {
+        const auto ui = static_cast(i);
+        const int li = usages.link_index[ui];
+        const int nh = usages.node_host[ui];
+        const int di = usages.design_index[ui];
+
+        soa_.link_idx[ui]      = li;
+        soa_.host_node[ui]     = nh;
+        soa_.node_idx[ui]      = usages.node_index[ui];
+        // legacy inlet.c:512 `Node[inlet->nodeIndex].inlet = CAPTURE`
+        if (soa_.node_idx[ui] >= 0 && soa_.node_idx[ui] < nn)
+            is_capture_node_[static_cast(soa_.node_idx[ui])] = 1;
+        soa_.num_inlets[ui]    = usages.num_inlets[ui];
+        soa_.clog_factor[ui]   = usages.clog_factor[ui];
+        soa_.flow_limit[ui]    = usages.flow_limit[ui] * inv_flow;
+        soa_.local_depress[ui] = usages.local_depress[ui] * inv_len;
+        soa_.local_width[ui]   = usages.local_width[ui] * inv_len;
+        soa_.placement[ui]     = usages.placement[ui];
+
+        // ------------------------------------------------------------------
+        // Design (InletStore rows are in user units)
+        // ------------------------------------------------------------------
+        if (di >= 0 && di < ctx.inlets.count()) {
+            const auto ud = static_cast(di);
+            const std::string& type_str = ctx.inlets.inlet_type[ud];
+            int itype = static_cast(InletType::CUSTOM);
+            if      (type_str == "GRATE")      itype = static_cast(InletType::GRATE);
+            else if (type_str == "CURB")       itype = static_cast(InletType::CURB);
+            else if (type_str == "COMBO")      itype = static_cast(InletType::COMBO);
+            else if (type_str == "SLOTTED")    itype = static_cast(InletType::SLOTTED);
+            else if (type_str == "DROP_GRATE") itype = static_cast(InletType::DROP_GRATE);
+            else if (type_str == "DROP_CURB")  itype = static_cast(InletType::DROP_CURB);
+            else if (type_str == "CUSTOM")     itype = static_cast(InletType::CUSTOM);
+            soa_.inlet_type[ui] = itype;
+
+            const std::string& gt_str = ctx.inlets.grate_type[ud];
+            int gt = static_cast(GrateType::GENERIC);
+            if      (gt_str == "P_BAR-50")     gt = static_cast(GrateType::P_BAR_50);
+            else if (gt_str == "P_BAR-50x100") gt = static_cast(GrateType::P_BAR_50x100);
+            else if (gt_str == "P_BAR-30")     gt = static_cast(GrateType::P_BAR_30);
+            else if (gt_str == "CURVED_VANE")  gt = static_cast(GrateType::CURVED_VANE);
+            else if (gt_str == "TILT_BAR-45")  gt = static_cast(GrateType::TILT_BAR_45);
+            else if (gt_str == "TILT_BAR-30")  gt = static_cast(GrateType::TILT_BAR_30);
+            else if (gt_str == "RETICULINE")   gt = static_cast(GrateType::RETICULINE);
+            soa_.grate_type[ui] = gt;
+
+            // `length`/`width` are the grate dimensions for the grate family
+            // and the slot dimensions for SLOTTED (InfraData.hpp column map).
+            if (itype == static_cast(InletType::SLOTTED)) {
+                soa_.slotted_length[ui] = ctx.inlets.length[ud] * inv_len;
+                soa_.slotted_width[ui]  = ctx.inlets.width[ud]  * inv_len;
+            } else if (itype == static_cast(InletType::GRATE) ||
+                       itype == static_cast(InletType::DROP_GRATE) ||
+                       itype == static_cast(InletType::COMBO)) {
+                soa_.grate_length[ui] = ctx.inlets.length[ud] * inv_len;
+                soa_.grate_width[ui]  = ctx.inlets.width[ud]  * inv_len;
+            }
+            soa_.open_area[ui]    = ctx.inlets.open_area[ud];
+            soa_.splash_veloc[ui] = ctx.inlets.splash_veloc[ud] * inv_len;
+
+            if (itype == static_cast(InletType::CURB) ||
+                itype == static_cast(InletType::DROP_CURB) ||
+                itype == static_cast(InletType::COMBO)) {
+                soa_.curb_length[ui] = ctx.inlets.curb_length[ud] * inv_len;
+                soa_.curb_height[ui] = ctx.inlets.curb_height[ud] * inv_len;
+                soa_.curb_throat[ui] = ctx.inlets.curb_throat[ud];
             }
 
-            case InletType::COMBO: {
-                // Combo inlet: curb captures sweep portion first,
-                // then grate captures from remaining flow
-                double Lgrate = soa_.grate_length[ii];
-                double Lcurb  = soa_.curb_length[ii];
-                double Q1 = qBypassed;
-                double qc_total = 0.0;
-
-                // Curb portion (sweep length = curb length - grate length)
-                double Lsweep = Lcurb - Lgrate;
-                if (Lsweep > 0.0) {
-                    double qc_curb = curbCapture(Q1, Lsweep, Sx_i, SL, n_i,
-                                                  a_i, W_i, T_spread);
-                    qc_total += qc_curb;
-                    Q1 -= qc_curb;
-                }
+            soa_.curve_index[ui] = ctx.inlets.curve_index[ud];
+            soa_.curve_kind[ui]  = ctx.inlets.curve_kind[ud];
+        }
 
-                // Grate portion on bypass flow
-                if (Lgrate > 0.0 && Q1 > 0.0) {
-                    // Recompute spread for reduced flow
-                    double T2 = (Q1 != qBypassed && qfactor > 0.0)
-                                ? computeFlowSpread(Q1, qfactor, Sx_i, Sw_i,
-                                                     a_i, W_i, Tc)
-                                : T_spread;
-                    double A2 = 0.0;
-                    if (a_i == 0.0) {
-                        A2 = T2 * T2 * Sx_i / 2.0;
-                    } else {
-                        A2 = (T2 <= W_i) ? T2 * T2 * Sw_i / 2.0
-                                          : (T2 * T2 * Sx_i + a_i * W_i) / 2.0;
-                    }
-                    double V2 = (A2 > 0.0) ? Q1 / A2 : 0.0;
-
-                    double Wg = soa_.grate_width[ii];
-                    int gt    = soa_.grate_type[ii];
-
-                    double Eo;
-                    if (a_i == 0.0) {
-                        Eo = (T2 <= Wg) ? 1.0
-                                        : 1.0 - std::pow(1.0 - Wg / T2, 2.67);
-                    } else {
-                        if (T2 <= W_i) Eo = 1.0;
-                        else {
-                            double Sr = Sw_i / Sx_i;
-                            Eo = computeEo(Sr, T2 - W_i, W_i);
-                        }
-                    }
-
-                    double Vo;
-                    if (gt < 0 || gt == static_cast(GrateType::GENERIC))
-                        Vo = 100.0;
-                    else
-                        Vo = splashOverVelocity(Lgrate, gt);
-
-                    double Rf = 1.0;
-                    if (V2 > Vo) Rf = 1.0 - 0.09 * (V2 - Vo);
-
-                    double Rs = 0.0;
-                    if (Eo < 1.0 && Sx_i > 0.0 && Lgrate > 0.0) {
-                        Rs = 1.0 / (1.0 + 0.15 * std::pow(V2, 1.8)
-                                    / (Sx_i * std::pow(Lgrate, 2.3)));
-                    }
-
-                    qc_total += Q1 * (Rf * Eo + Rs * (1.0 - Eo));
+        // ------------------------------------------------------------------
+        // Host topology: bypass node, approach conduit(s)
+        // ------------------------------------------------------------------
+        int bypass = -1, up = -1, up2 = -1;
+        if (nh >= 0 && nh < nn) {
+            // Inlet junction: the host node is its own bypass node. Its two
+            // attached conduits are found by scan; node1/node2 are already the
+            // post-reversal orientation (PostParseResolver.cpp:2539 swaps the
+            // ends of an adverse-slope conduit under DW/FV), so "flows toward
+            // the host" is exactly node2 == host.
+            bypass = nh;
+            for (int j = 0; j < nl && up2 < 0; ++j) {
+                const auto uj = static_cast(j);
+                if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+                if (ctx.links.node2[uj] != nh) continue;
+                if (up < 0) up = j; else up2 = j;
+            }
+            if (up < 0) {
+                // Both conduits leave the node (a crest): fall back to either
+                // one for geometry; the approach flow is then 0 by definition.
+                for (int j = 0; j < nl; ++j) {
+                    const auto uj = static_cast(j);
+                    if (ctx.links.type[uj] == LinkType::CONDUIT &&
+                        ctx.links.node1[uj] == nh) { up = j; break; }
                 }
-                qc = qc_total;
-                break;
             }
-
-            case InletType::SLOTTED: {
-                // Slotted inlet behaves as curb opening (per HEC-22)
-                double Ls = soa_.slotted_length[ii];
-                qc = curbCapture(qBypassed, Ls, Sx_i, SL, n_i,
-                                  a_i, W_i, T_spread);
-                break;
+            if (up2 >= 0) {
+                soa_.two_inbound[ui] = 1;
+                // Geometry comes from the steeper of the two approaches
+                // (plan §4 item 5 — the one that governs the gutter flow).
+                const int ca  = ctx.link_subtypes.conduit_row(up);
+                const int cb  = ctx.link_subtypes.conduit_row(up2);
+                const double sa = (ca >= 0) ? ctx.link_subtypes.conduits
+                                      .slope[static_cast(ca)] : 0.0;
+                const double sb = (cb >= 0) ? ctx.link_subtypes.conduits
+                                      .slope[static_cast(cb)] : 0.0;
+                if (sb > sa) std::swap(up, up2);
             }
+        } else if (li >= 0 && li < nl) {
+            // Conduit-attribute usage: legacy books bypass at node2 of the
+            // host link — post-reversal, so an adverse conduit's bypass is its
+            // true downstream end (plan G7).
+            bypass = ctx.links.node2[static_cast(li)];
+            up = li;
+        }
+        soa_.bypass_node[ui] = bypass;
+        soa_.up_link[ui]     = up;
+        soa_.up_link2[ui]    = up2;
+
+        // ------------------------------------------------------------------
+        // Street / channel geometry (inlet.c:1147-1196)
+        // ------------------------------------------------------------------
+        const int si = usages.street_index[ui];
+        if (si >= 0 && si < ctx.streets.count()) {
+            const auto su = static_cast(si);
+            soa_.sx[ui]                = ctx.streets.sx[su] / 100.0;  // % → fraction
+            soa_.gutter_depression[ui] = ctx.streets.gutter_depres[su] * inv_len;
+            soa_.gutter_width[ui]      = ctx.streets.gutter_width[su] * inv_len;
+            soa_.road_roughness[ui]    = ctx.streets.n_road[su];
+            soa_.n_sides[ui]           = ctx.streets.sides[su];
+            soa_.t_crown[ui]           = ctx.streets.t_crown[su] * inv_len;
+        } else {
+            // Rectangular / trapezoidal channel defaults (inlet.c:1188-1195).
+            // PARITY NOTE: legacy leaves the shared Tcrown at whatever the
+            // previous street inlet set it to; use an unreachable spread
+            // instead so the result does not depend on evaluation order.
+            const int cr = (up >= 0) ? ctx.link_subtypes.conduit_row(up) : -1;
+            soa_.sx[ui]                = 0.01;
+            soa_.gutter_depression[ui] = 0.0;
+            soa_.gutter_width[ui]      = 0.0;
+            soa_.road_roughness[ui]    = (cr >= 0)
+                ? ctx.link_subtypes.conduits.roughness[static_cast(cr)]
+                : 0.01;
+            soa_.n_sides[ui]           = 1;
+            soa_.t_crown[ui]           = 100.0;
+        }
 
-            case InletType::CUSTOM:
-            default:
-                qc = 0.0;
-                break;
-            }
+        // Longitudinal slope of the approach conduit + Izzard's flow factor.
+        {
+            const int cr = (up >= 0) ? ctx.link_subtypes.conduit_row(up) : -1;
+            const double sl = (cr >= 0)
+                ? ctx.link_subtypes.conduits.slope[static_cast(cr)]
+                : 0.0;
+            soa_.slope[ui] = sl;
+            // inlet.c:520 — pow(Sx, 1.67), NOT the exact 5/3 exponent.
+            soa_.flow_factor[ui] = (soa_.road_roughness[ui] > 0.0 && sl > 0.0)
+                ? (0.56 / soa_.road_roughness[ui]) * std::pow(sl, 0.5)
+                  * std::pow(soa_.sx[ui], 1.67)
+                : 0.0;
+        }
 
-            // Apply clogging factor
-            qc *= soa_.clog_factor[ii];
+        // ------------------------------------------------------------------
+        // Placement (inlet.c:1129-1143 for conduit hosts; plan D-E3 for nodes)
+        // ------------------------------------------------------------------
+        uint8_t sag = 0;
+        if (soa_.placement[ui] == static_cast(Placement::ON_SAG)) {
+            sag = 1;
+        } else if (soa_.placement[ui] == static_cast(Placement::ON_GRADE)) {
+            sag = 0;
+        } else if (nh >= 0) {
+            // AUTOMATIC at an inlet junction: legacy's "degree > 0 ⇒ ON_GRADE"
+            // would make every inlet junction on-grade (it always has a
+            // downstream conduit). Sag iff both attached conduits fall toward
+            // the node, i.e. both far-end inverts sit above the host invert.
+            const double z = ctx.nodes.invert_elev[static_cast(nh)];
+            int n_toward = 0, n_attached = 0;
+            for (int j = 0; j < nl; ++j) {
+                const auto uj = static_cast(j);
+                if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+                const int a = ctx.links.node1[uj], b = ctx.links.node2[uj];
+                int far = -1;
+                if (a == nh) far = b; else if (b == nh) far = a; else continue;
+                ++n_attached;
+                if (far >= 0 && far < nn &&
+                    ctx.nodes.invert_elev[static_cast(far)]
+                        > z + constants::FUDGE)
+                    ++n_toward;
+            }
+            sag = (n_attached > 0 && n_toward == n_attached) ? 1 : 0;
+        } else if (bypass >= 0 && bypass < nn) {
+            sag = (out_degree[static_cast(bypass)] > 0) ? 0 : 1;
+        }
+        soa_.is_sag[ui] = sag;
+    }
 
-            // Limit capture
-            qc = std::min(qc, qMax);
-            qc = std::min(qc, qBypassed);
+    // Seed legacy's carried-over Nsides. inlet_validate (inlet.c:517-519) calls
+    // getConduitGeometry once per VALID inlet while computing its Izzard flow
+    // factor, walking the same reversed list, so when routing starts Nsides
+    // holds the sides of the LAST inlet that loop touched — the FIRST
+    // [INLET_USAGE] row. Without this an on-sag inlet captures nothing on its
+    // first evaluation (totalInlets = 0 * numInlets).
+    for (int ii = soa_.count - 1; ii >= 0; --ii)
+        nsides_prev_ = soa_.n_sides[static_cast(ii)];
 
-            qCaptured += qc;
-            qBypassed -= qc;
-        }
+    computeBackflowRatios();
+}
 
-        // Scale back to full street (both sides)
-        qCaptured *= nsides;
-        soa_.flow_capture[ii] = qCaptured;
+// ============================================================================
+// computeAll() — capture, backflow and the lateral-flow coupling
+// ============================================================================
 
-        // Gap #68: accumulate capture/bypass stats
-        auto uii = static_cast(ii);
-        soa_.stat_capture_vol[uii] += qCaptured * dt;
-        soa_.stat_bypass_vol[uii]  += qBypassed * nsides * dt;
-        if (qCaptured > soa_.stat_peak_flow[uii])
-            soa_.stat_peak_flow[uii] = qCaptured;
+void InletSolver::computeAll(SimulationContext& ctx, double dt) {
+    const int ni = soa_.count;
+    if (ni == 0) return;
 
-        // Accumulate per bypass node
-        if (bypass >= 0 && bypass < nn) {
-            inlet_flow_per_node[static_cast(bypass)] += qCaptured;
+    auto& links = ctx.links;
+    auto& nodes = ctx.nodes;
+    const int nn = ctx.n_nodes();
+    const int nl = ctx.n_links();
+    const bool is_dw = (ctx.options.routing_model == RoutingModel::DYNWAVE);
+    const bool report_on = (ctx.current_date > ctx.options.report_start);
+
+    const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    const double ucf_len  = ucf::Ucf[ucf::LENGTH][static_cast(us)];
+    const double ucf_flow = ucf::Qcf[static_cast(ctx.options.flow_units)];
+
+    // Sized in init(); re-sized only if the model grew through the edit API.
+    if (static_cast(node_inlet_flow_.size()) < nn) {
+        node_inlet_flow_.assign(static_cast(nn), 0.0);
+        node_inflow_.assign(static_cast(nn), 0.0);
+    }
+    std::fill(node_inlet_flow_.begin(), node_inlet_flow_.end(), 0.0);
+
+    // --- For non-DW routing find conduit flow into each node (used to limit
+    //     the max. amount of on-sag capture). Legacy writes this into
+    //     Node[].inflow (inlet.c:572-579); keep it in a scratch column so the
+    //     routing solvers' own node ledger is untouched.
+    if (!is_dw) {
+        for (int j = 0; j < nn; ++j) {
+            const auto uj = static_cast(j);
+            node_inflow_[uj] = std::max(0.0, nodes.lat_flow[uj]);
+        }
+        for (int j = 0; j < nl; ++j) {
+            const auto uj = static_cast(j);
+            const int n2 = links.node2[uj];
+            if (n2 >= 0 && n2 < nn)
+                node_inflow_[static_cast(n2)] +=
+                    std::max(0.0, links.flow[uj]);
         }
     }
 
-    // Second pass: compute backflow and adjust lateral flows at bypass and capture nodes
-    for (int ii = 0; ii < ni; ++ii) {
-        double qcap = soa_.flow_capture[ii];
+    // ---- first pass: capture + backflow -----------------------------------
+    // REVERSE file order: legacy PREPENDS each [INLET_USAGE] row to its list
+    // (`inlet->nextInlet = FirstInlet; FirstInlet = inlet;`, inlet.c:441) and
+    // walks that list in both passes. The order is observable — it decides
+    // whose street the stale `Nsides` carries into the next on-sag inlet, and
+    // the order in which captures accumulate into a shared node.
+    for (int ii = ni - 1; ii >= 0; --ii) {
+        const auto ui = static_cast(ii);
+        soa_.flow_capture[ui] = 0.0;
+        soa_.q_approach[ui]   = 0.0;
+        soa_.backflow[ui]     = 0.0;
+
+        const int host    = soa_.bypass_node[ui];
+        const int capture = soa_.node_idx[ui];
+        if (host < 0 || host >= nn) continue;
+        if (capture < 0 || capture >= nn) continue;
 
-        int bypass = soa_.bypass_node[ii];
-        int capture_node = soa_.node_idx[ii];
+        const int up  = soa_.up_link[ui];
+        const int up2 = soa_.up_link2[ui];
+
+        // --- approach flow
+        double q = 0.0;
+        if (soa_.host_node[ui] >= 0) {
+            // Inlet junction: only conduits carrying flow TOWARD the node
+            // contribute (plan D-E8); both of them at a true sag.
+            if (up >= 0 && links.node2[static_cast(up)] == host)
+                q += std::max(0.0, links.flow[static_cast(up)]);
+            if (soa_.two_inbound[ui] && up2 >= 0)
+                q += std::max(0.0, links.flow[static_cast(up2)]);
+        } else if (up >= 0) {
+            q = std::fabs(links.flow[static_cast(up)]);
+        }
+        soa_.q_approach[ui] = q;
+
+        const double depth = nodes.depth[static_cast(host)];
+
+        const Design      d = designOf(ii);
+        const UsageParams u = usageOf(ii);
+
+        // The channel cross-section is needed only by the DROP_* designs.
+        XSectParams xs{};
+        const XSectParams* xsp = nullptr;
+        if (up >= 0 &&
+            (d.type == static_cast(InletType::DROP_GRATE) ||
+             d.type == static_cast(InletType::DROP_CURB))) {
+            xs  = link::buildXSectParams(links, static_cast(up),
+                                         &ctx.transect_tables);
+            xsp = &xs;
+        }
+        Geom g = geomOf(ctx, ii, xsp);
+
+        double qc = 0.0;
+        if (d.type == static_cast(InletType::CUSTOM)) {
+            const int ci = soa_.curve_index[ui];
+            if (ci >= 0 && ci < static_cast(ctx.tables.tables.size()))
+                qc = getCustomCapturedFlow(u, g,
+                        ctx.tables.tables[static_cast(ci)],
+                        soa_.curve_kind[ui], q, depth, ucf_flow, ucf_len);
+        } else if (soa_.is_sag[ui] == 0) {
+            qc = getOnGradeCapturedFlow(d, u, g, q, depth);
+            // getConduitGeometry runs past both early returns (inlet.c:1290).
+            if (u.num_inlets != 0 && q >= MIN_RUNOFF_FLOW) nsides_prev_ = g.nsides;
+        } else {
+            // On-sag capture is depth-driven; the approach flow only caps it
+            // (second pass). Under non-DW routing legacy feeds the node's
+            // accumulated inflow instead of the link flow.
+            qc = getOnSagCapturedFlow(d, u, g, depth, nsides_prev_);
+            if (u.num_inlets != 0) nsides_prev_ = g.nsides;
+        }
+        if (std::fabs(qc) < INLET_FUDGE) qc = 0.0;
+        soa_.flow_capture[ui] = qc;
+        node_inlet_flow_[static_cast(host)] += qc;
+
+        // --- capture node's overflow becomes the inlet's backflow
+        double qbf = nodes.overflow[static_cast(capture)]
+                     * soa_.backflow_ratio[ui];
+        if (std::fabs(qbf) < INLET_FUDGE) qbf = 0.0;
+        soa_.backflow[ui] = qbf;
+    }
 
-        if (bypass < 0 || bypass >= nn) continue;
-        if (capture_node < 0 || capture_node >= nn) continue;
+    // ---- second pass: throttle, couple, accumulate -------------------------
+    for (int ii = ni - 1; ii >= 0; --ii) {
+        const auto ui = static_cast(ii);
+        const int host    = soa_.bypass_node[ui];
+        const int capture = soa_.node_idx[ui];
+        if (host < 0 || host >= nn) continue;
+        if (capture < 0 || capture >= nn) continue;
+        const auto uh = static_cast(host);
+
+        // For on-sag placement under non-DW routing, captured flow is limited
+        // to the inlet's share of the bypass node's inflow plus stored volume
+        // (inlet.c:633-639).
+        if (!is_dw && soa_.is_sag[ui] != 0 && soa_.host_node[ui] < 0) {
+            double qlim = nodes.volume[uh] / dt;
+            qlim += std::max(node_inflow_[uh], 0.0);
+            if (node_inlet_flow_[uh] > qlim)
+                soa_.flow_capture[ui] *= qlim / node_inlet_flow_[uh];
+        }
 
-        // Gap #56: backflow = capture node overflow × pre-computed ratio
-        double qbf = nodes.overflow[static_cast(capture_node)]
-                     * soa_.backflow_ratio[static_cast(ii)];
-        static constexpr double FUDGE = 2.5e-5;
-        if (std::fabs(qbf) < FUDGE) qbf = 0.0;
-        soa_.backflow[static_cast(ii)] = qbf;
+        // Plan D-E4: an inlet junction is a (near) zero-storage node — the
+        // sink must never exceed what actually reaches it, in any routing
+        // model, or the node is driven negative.
+        if (soa_.host_node[ui] >= 0) {
+            const double qlim = soa_.q_approach[ui] + nodes.volume[uh] / dt;
+            soa_.flow_capture[ui] = std::min(soa_.flow_capture[ui], qlim);
+        }
 
-        // Gap #68: accumulate backflow stats
-        soa_.stat_backflow_vol[static_cast(ii)] += qbf * dt;
+        const double qcap = soa_.flow_capture[ui];
+        const double qbf  = soa_.backflow[ui];
 
-        if (qcap <= 0.0 && qbf <= 0.0) continue;
+        // Adjust lateral flows: subtract the captured flow from the bypass
+        // node, add it to the capture node, return any backflow to the bypass.
+        nodes.lat_flow[uh] -= (qcap - qbf);
+        nodes.lat_flow[static_cast(capture)] += qcap;
 
-        // Subtract net captured flow from bypass node lateral flow
-        // Net = capture - backflow (backflow reduces net extraction from bypass)
-        nodes.lat_flow[bypass] -= (qcap - qbf);
+        // Volume statistics (Gap #68) — cumulative over the whole run.
+        const double qnet = qcap - qbf;
+        soa_.stat_capture_vol[ui]  += qcap * dt;
+        soa_.stat_bypass_vol[ui]   += std::max(0.0, soa_.q_approach[ui] - qnet) * dt;
+        soa_.stat_backflow_vol[ui] += qbf * dt;
+        if (qcap > soa_.stat_peak_flow[ui]) soa_.stat_peak_flow[ui] = qcap;
 
-        // Add captured flow to receiving (capture) node lateral flow
-        nodes.lat_flow[capture_node] += qcap;
+        // Legacy performance statistics, gated on the reporting window
+        // (inlet.c:648-649).
+        if (report_on) updateStats(ii, soa_.q_approach[ui]);
     }
-
-    (void)dt;  // dt available for future on-sag volume limiting
 }
 
 // ============================================================================
-// Gap #56: getInletArea() — unclogged open area of one inlet (ft²)
-// Matches legacy getInletArea().  Returns 0 for CUSTOM type (uses count-based
-// backflow ratio instead).
+// updateStats() — legacy updateInletStats (inlet.c:985)
 // ============================================================================
 
-double InletSolver::getInletArea(int ii) const noexcept {
-    const auto ui = static_cast(ii);
-    double cf = soa_.clog_factor[ui];
-    int n     = soa_.num_inlets[ui];
-    auto t    = static_cast(soa_.inlet_type[ui]);
-
-    switch (t) {
-        case InletType::GRATE:
-        case InletType::DROP_GRATE:
-            return soa_.grate_length[ui] * soa_.grate_width[ui]
-                   * soa_.opening_ratio[ui] * cf * n;
-
-        case InletType::CURB:
-        case InletType::DROP_CURB:
-            return soa_.curb_height[ui] * soa_.curb_length[ui] * cf * n;
-
-        case InletType::COMBO:
-            return (soa_.grate_length[ui] * soa_.grate_width[ui] * soa_.opening_ratio[ui]
-                    + soa_.curb_height[ui] * soa_.curb_length[ui]) * cf * n;
-
-        case InletType::SLOTTED:
-            return soa_.slotted_length[ui] * soa_.slotted_width[ui] * cf * n;
+void InletSolver::updateStats(int ii, double q) {
+    const auto ui = static_cast(ii);
+    const double qCapture  = soa_.flow_capture[ui];
+    const double qBackflow = soa_.backflow[ui];
+    const double qNet      = qCapture - qBackflow;
+    const double qBypass   = q - qNet;
+    double fCapture = 0.0;
+
+    // --- check for no flow condition
+    if (q < MIN_RUNOFF_FLOW && qBackflow <= 0.0) return;
+    soa_.flow_periods[ui]++;
+
+    // --- there is positive net flow from inlet to capture node
+    if (qNet > 0.0) {
+        soa_.capture_periods[ui]++;
+        fCapture = qNet / q;
+        fCapture = std::min(fCapture, 1.0);
+        soa_.avg_flow_capture[ui] += fCapture;
+        if (qBypass > MIN_RUNOFF_FLOW) soa_.bypass_freq[ui] += 1.0;
+    }
+    // --- otherwise inlet receives backflow from capture node
+    else soa_.backflow_periods[ui]++;
 
-        case InletType::CUSTOM:
-        default:
-            return 0.0;  // custom: area-based ratio not used
+    // --- update peak flow stats
+    if (q > soa_.peak_flow[ui]) {
+        soa_.peak_flow[ui] = q;
+        soa_.peak_flow_capture[ui] = fCapture * 100.0;
     }
 }
 
 // ============================================================================
-// Gap #56: computeBackflowRatios() — pre-compute fraction of overflow → backflow
-// Matches legacy getBackflowRatios().
+// computeBackflowRatios() — legacy getBackflowRatios (inlet.c:1805)
 // ============================================================================
+//
+// PARITY NOTE (plan D-E6): legacy assigns the capture-node index to the
+// file-scope Manning roughness `n` (`n = inlet->nodeIndex;`) and then indexes
+// its per-node accumulator with the local `nodeIndex`, which is initialised to
+// 0 and never advanced (inlet.c:1836/1853). Every inlet in the model therefore
+// lands in slot 0 and every ratio is read back out of that one slot: the
+// backflow of ANY capture node is split across ALL of the model's inlets by
+// open area, not among the inlets that actually drain into it.
+//
+// That is a bug, but it is the oracle's behaviour and it is observable —
+// example7-inlets' four one-inlet capture nodes get ratio 0.2 (their share of
+// the whole model's grate area), not the 1.0 a per-node grouping gives, which
+// changes every backflow and split the deck from routing step 287. Reproduced
+// deliberately; the grouping v6 used to do is the documented divergence.
 
 void InletSolver::computeBackflowRatios() {
-    int ni = soa_.count;
+    const int ni = soa_.count;
     if (ni == 0) return;
 
-    // Per capture-node accumulators (indexed by capture node idx, but we don't
-    // know max node idx here; use a flat map keyed by capture node)
-    struct NodeInfo {
-        int    n_links       = 0; ///< total inlet links to this node
-        int    n_std_links   = 0; ///< links with standard (area > 0) inlets
-        int    n_custom      = 0; ///< total custom inlets (sum of num_inlets)
-        double total_area    = 0.0;
-    };
-    std::vector> node_map; // sparse: (node_idx, info)
-
-    auto get_node = [&](int node) -> NodeInfo& {
-        for (auto& kv : node_map) {
-            if (kv.first == node) return kv.second;
-        }
-        node_map.push_back({node, NodeInfo{}});
-        return node_map.back().second;
-    };
-
-    // First pass: accumulate totals per capture node
-    for (int ii = 0; ii < ni; ++ii) {
-        int m = soa_.node_idx[static_cast(ii)];
+    // One aggregate bucket — legacy's inletNodes[0] (see the note above).
+    int    n_links     = 0;   // total inlet usages in the model
+    int    n_std_links = 0;   // those with a standard (area > 0) inlet
+    int    n_custom    = 0;   // sum of num_inlets over the custom ones
+    double total_area  = 0.0;
+
+    // Legacy walks its inlet list, which is the [INLET_USAGE] rows in REVERSE
+    // (inlet.c:441 prepends); the area sum is a float accumulation, so the
+    // order is part of the answer.
+    for (int ii = ni - 1; ii >= 0; --ii) {
+        const int m = soa_.node_idx[static_cast(ii)];
         if (m < 0) continue;
-        auto& info = get_node(m);
-        info.n_links++;
-        double area = getInletArea(ii);
+        n_links++;
+        const double area = getInletArea(designOf(ii), usageOf(ii));
         if (area > 0.0) {
-            info.n_std_links++;
-            info.total_area += area;
+            n_std_links++;
+            total_area += area;
         } else {
-            info.n_custom += soa_.num_inlets[static_cast(ii)];
+            n_custom += soa_.num_inlets[static_cast(ii)];
         }
     }
+    if (n_links == 0) return;
 
-    // Second pass: assign ratios
-    for (int ii = 0; ii < ni; ++ii) {
-        const auto ui = static_cast(ii);
-        int m = soa_.node_idx[ui];
+    // f = share of usages carrying a standard inlet (legacy inlet.c:1851-1853)
+    const double f = static_cast(n_std_links) / static_cast(n_links);
+
+    for (int ii = ni - 1; ii >= 0; --ii) {
+        const auto ui = static_cast(ii);
         soa_.backflow_ratio[ui] = 0.0;
-        if (m < 0) continue;
+        if (soa_.node_idx[ui] < 0) continue;
 
-        NodeInfo* info = nullptr;
-        for (auto& kv : node_map) {
-            if (kv.first == m) { info = &kv.second; break; }
-        }
-        if (!info || info->n_links == 0) continue;
-
-        double f = (info->n_links > 0)
-                   ? static_cast(info->n_std_links)
-                     / static_cast(info->n_links)
-                   : 0.0;
-
-        double area = getInletArea(ii);
-        if (area > 0.0 && info->total_area > 0.0) {
-            soa_.backflow_ratio[ui] = area / info->total_area * f;
-        } else if (area == 0.0 && info->n_custom > 0) {
-            soa_.backflow_ratio[ui] = static_cast(soa_.num_inlets[ui])
-                                      / static_cast(info->n_custom)
-                                      * (1.0 - f);
+        const double area = getInletArea(designOf(ii), usageOf(ii));
+        if (area > 0.0) {
+            if (total_area > 0.0)
+                soa_.backflow_ratio[ui] = area / total_area * f;
+        } else if (n_custom > 0) {
+            soa_.backflow_ratio[ui] =
+                static_cast(soa_.num_inlets[ui])
+                / static_cast(n_custom) * (1.0 - f);
         }
     }
 }
 
 // ============================================================================
-// Gap #55: adjustQualInflows() — quality mass transfer at inlet bypass/capture
-// Matches legacy inlet_adjustQualInflows().
+// adjustQualInflows() — legacy inlet_adjustQualInflows (inlet.c:655)
 // ============================================================================
 
 void InletSolver::adjustQualInflows(SimulationContext& ctx, double dt) {
-    int ni = soa_.count;
+    const int ni = soa_.count;
     if (ni == 0) return;
 
-    int np = ctx.n_pollutants();
+    const int np = ctx.n_pollutants();
     if (np == 0) return;
 
     auto& nodes = ctx.nodes;
     const int nn = ctx.n_nodes();
+    const auto unp = static_cast(np);
 
     for (int ii = 0; ii < ni; ++ii) {
-        const auto ui = static_cast(ii);
-        int bypass  = soa_.bypass_node[ui];
-        int capture = soa_.node_idx[ui];
-
+        const auto ui = static_cast(ii);
+        // Bypass node = the conduit usage's downstream node, or the inlet
+        // junction itself — resolved once in init().
+        const int bypass  = soa_.bypass_node[ui];
+        const int capture = soa_.node_idx[ui];
         if (bypass < 0 || bypass >= nn) continue;
         if (capture < 0 || capture >= nn) continue;
 
-        double qcap = soa_.flow_capture[ui];
-        double qbf  = soa_.backflow[ui];
-        double qNet = qcap - qbf;
-
-        auto ub = static_cast(bypass);
-        auto uc = static_cast(capture);
+        const double qNet = soa_.flow_capture[ui] - soa_.backflow[ui];
+        const auto ub = static_cast(bypass);
+        const auto uc = static_cast(capture);
 
         if (qNet > 0.0) {
             // Net flow: bypass → capture
-            // Add volume and mass to capture node's quality inflow accumulators
             nodes.qual_vol_in[uc] += qNet * dt;
-            for (int p = 0; p < np; ++p) {
-                auto nd_idx = uc * static_cast(np) + static_cast(p);
-                auto by_idx = ub * static_cast(np) + static_cast(p);
-                if (nd_idx < nodes.qual_mass_in.size() && by_idx < nodes.conc_old.size()) {
+            for (std::size_t p = 0; p < unp; ++p) {
+                const std::size_t nd_idx = uc * unp + p;
+                const std::size_t by_idx = ub * unp + p;
+                if (nd_idx < nodes.qual_mass_in.size() &&
+                    by_idx < nodes.conc_old.size())
                     nodes.qual_mass_in[nd_idx] += qNet * nodes.conc_old[by_idx];
-                }
             }
         } else if (qNet < 0.0) {
             // Net backflow: capture → bypass
-            double qBkf = -qNet;
+            const double qBkf = -qNet;
             nodes.qual_vol_in[ub] += qBkf * dt;
-            for (int p = 0; p < np; ++p) {
-                auto nd_idx = ub * static_cast(np) + static_cast(p);
-                auto cp_idx = uc * static_cast(np) + static_cast(p);
-                if (nd_idx < nodes.qual_mass_in.size() && cp_idx < nodes.conc_old.size()) {
+            for (std::size_t p = 0; p < unp; ++p) {
+                const std::size_t nd_idx = ub * unp + p;
+                const std::size_t cp_idx = uc * unp + p;
+                if (nd_idx < nodes.qual_mass_in.size() &&
+                    cp_idx < nodes.conc_old.size())
                     nodes.qual_mass_in[nd_idx] += qBkf * nodes.conc_old[cp_idx];
-                }
             }
         }
     }
 }
 
 // ============================================================================
-// Gap #68: gatherStats() — copy per-inlet stats into InletUsageStore
+// adjustFloodingTotals() — legacy inlet_adjustQualOutflows (inlet.c:706)
 // ============================================================================
 
-void InletSolver::gatherStats(InletUsageStore& usages) const {
-    int n = std::min(soa_.count, usages.count());
+void InletSolver::adjustFloodingTotals(SimulationContext& ctx, double dt) const {
+    const int ni = soa_.count;
+    if (ni == 0) return;
+
+    auto& nodes = ctx.nodes;
+    auto& mb    = ctx.mass_balance;
+    const int nn = ctx.n_nodes();
+
+    // A capture node's overflow does not leave the system: computeAll hands it
+    // straight back to the street as the inlet's backflow (inlet.c:618, mirrored
+    // above). Booking it under Flooding Loss counts the same water twice — once
+    // as a loss, once as water returned to the corridor — and when the capture
+    // node cannot pass what the inlet offers (an undersized trunk sewer, so it
+    // sits at its rim and overflows nearly everything it receives) the two feed
+    // each other: capture -> flood -> backflow -> capture. Measured -255.6 %
+    // routing continuity on a four-inlet street over a 1 ft trunk.
+    //
+    // Legacy subtracts the overflow of every CAPTURE node (inlet.c:727-735).
+    // Summing each inlet's SHARE instead credits exactly what is returned: the
+    // ratios sum to 1 over the inlets on a shared capture node, and an inlet
+    // computeAll skipped contributes nothing — legacy's per-node subtraction
+    // over-credits in that case.
+    //
+    // Read the overflow fresh rather than reusing soa_.backflow: that column
+    // still holds the value computeAll derived from the PREVIOUS step's
+    // overflow, while the flooding just booked is this step's. Legacy reads the
+    // node for the same reason (routing.c:259-260 — removeSystemOutflows then
+    // inlet_adjustQualOutflows, both on current state).
+    // Legacy loops over NODES, not inlets: every node marked CAPTURE gives back
+    // its WHOLE overflow, once, with no volume gate (inlet.c:727-735 —
+    // `q = Node[j].overflow; if (q > 0) StepFlowTotals.flooding -= q;`). It is
+    // therefore free to drive the step's flooding slightly negative when the
+    // ledger booked none (example7-inlets' legacy series sits at -8.9e-16), and
+    // crediting per-inlet shares instead leaves most of the overflow booked as
+    // flooding now that the backflow ratios follow legacy's single-bucket split
+    // and no longer sum to 1 over a capture node's inlets.
+    for (int j = 0; j < nn; ++j) {
+        const auto uj = static_cast(j);
+        if (uj >= is_capture_node_.size() || !is_capture_node_[uj]) continue;
+        const double q = nodes.overflow[uj];
+        if (q <= 0.0) continue;
+        mb.routing_flooding -= q * dt;
+        mb.step_flooding    -= q;
+        // Legacy inlet_adjustQualOutflows (inlet.c:737-743): captured
+        // overflow returns its pollutant mass to the street as well.
+        const int np = ctx.n_pollutants();
+        for (int p = 0; p < np; ++p) {
+            const auto up = static_cast(p);
+            mb.qual_routing_flood[up] -= q * nodes.conc[uj * np + up] * dt;
+        }
+    }
+}
+
+// ============================================================================
+// gatherStats() — publish to InletUsageStore + ctx.inlet_diag for the report
+// ============================================================================
+
+void InletSolver::gatherStats(SimulationContext& ctx) const {
+    const int n = std::min(soa_.count, ctx.inlet_usages.count());
     if (n <= 0) return;
-    usages.resize_stats(usages.count());
+
+    ctx.inlet_usages.resize_stats(ctx.inlet_usages.count());
+    ctx.inlet_diag.resize(n);
+
     for (int i = 0; i < n; ++i) {
-        auto ui = static_cast(i);
-        usages.stat_capture_vol[ui]  = soa_.stat_capture_vol[ui];
-        usages.stat_bypass_vol[ui]   = soa_.stat_bypass_vol[ui];
-        usages.stat_backflow_vol[ui] = soa_.stat_backflow_vol[ui];
-        usages.stat_peak_flow[ui]    = soa_.stat_peak_flow[ui];
+        const auto ui = static_cast(i);
+        ctx.inlet_usages.stat_capture_vol[ui]  = soa_.stat_capture_vol[ui];
+        ctx.inlet_usages.stat_bypass_vol[ui]   = soa_.stat_bypass_vol[ui];
+        ctx.inlet_usages.stat_backflow_vol[ui] = soa_.stat_backflow_vol[ui];
+        ctx.inlet_usages.stat_peak_flow[ui]    = soa_.stat_peak_flow[ui];
+
+        auto& dg = ctx.inlet_diag;
+        dg.host_node[ui]         = soa_.host_node[ui];
+        dg.up_link[ui]           = soa_.up_link[ui];
+        dg.is_sag[ui]            = soa_.is_sag[ui];
+        dg.num_inlets[ui]        = soa_.num_inlets[ui];
+        dg.flow_periods[ui]      = soa_.flow_periods[ui];
+        dg.capture_periods[ui]   = soa_.capture_periods[ui];
+        dg.backflow_periods[ui]  = soa_.backflow_periods[ui];
+        dg.peak_flow[ui]         = soa_.peak_flow[ui];
+        dg.peak_flow_capture[ui] = soa_.peak_flow_capture[ui];
+        dg.avg_flow_capture[ui]  = soa_.avg_flow_capture[ui];
+        dg.bypass_freq[ui]       = soa_.bypass_freq[ui];
     }
 }
 
diff --git a/src/engine/hydraulics/Inlet.hpp b/src/engine/hydraulics/Inlet.hpp
index 3dfe6085d..a11039d92 100644
--- a/src/engine/hydraulics/Inlet.hpp
+++ b/src/engine/hydraulics/Inlet.hpp
@@ -1,33 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Inlet.hpp
  * @brief Street inlet capture efficiency — FHWA HEC-22.
  *
- * @details Inlet types: GRATE, CURB, COMBO, SLOTTED, DROP_GRATE, DROP_CURB, CUSTOM.
- *          On-grade capture uses splash-over velocity and frontal/longitudinal
- *          flow fractions. On-sag capture uses weir/orifice transition.
+ * @details Inlet types: GRATE, CURB, COMBO, SLOTTED, DROP_GRATE, DROP_CURB,
+ *          CUSTOM. On-grade capture uses splash-over velocity and frontal /
+ *          side flow fractions (HEC-22 Eq. 4-16 … 4-24); on-sag capture uses
+ *          the weir ↔ orifice transition (Eq. 4-26 … 4-33).
+ *
+ *          Two host kinds share one kernel and one statistics block
+ *          (plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §2.1):
+ *            * conduit-attribute usage — `[INLET_USAGE]`, host = a STREET
+ *              conduit, bypass node = that conduit's downstream node;
+ *            * inlet junction — `[INLET_JUNCTIONS]`, host = the node itself,
+ *              approach flow from the attached street conduit(s).
  *
- *          Batch: group inlets by type, compute capture in vectorised batches.
+ *          The pure kernel functions below are transliterations of the legacy
+ *          file-scope routines and carry the HEC-22 equation numbers; they take
+ *          their state through @ref inlet::Geom / @ref inlet::Design /
+ *          @ref inlet::UsageParams instead of legacy's module-level shared
+ *          variables, so they are directly unit-testable.
  *
  * @note Legacy reference: src/legacy/engine/inlet.c
  * @ingroup new_engine
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INLET_HPP
 #define OPENSWMM_INLET_HPP
 
+#include 
 #include 
 
 namespace openswmm {
 
 struct SimulationContext;
-struct InletUsageStore;
+struct XSectParams;
+struct Table;
 
 namespace inlet {
 
+/// Legacy `enum InletType` (inlet.c:119-122) — the COMBO slot is the merged
+/// GRATE+CURB design the legacy parser encodes as two `[INLETS]` lines.
 enum class InletType : int {
     GRATE       = 0,
     CURB        = 1,
@@ -38,6 +70,7 @@ enum class InletType : int {
     CUSTOM      = 6
 };
 
+/// Legacy `enum GrateType` (inlet.c:124-127).
 enum class GrateType : int {
     P_BAR_50      = 0,
     P_BAR_50x100  = 1,
@@ -49,113 +82,315 @@ enum class GrateType : int {
     GENERIC       = 7
 };
 
+/// Legacy `enum InletPlacementType` (inlet.c:129) — matches the token order of
+/// `[INLET_USAGE]` / `[INLET_JUNCTIONS]` and `InletUsageStore::placement`.
+enum class Placement : int { AUTOMATIC = 0, ON_GRADE = 1, ON_SAG = 2 };
+
+/// Legacy `enum ThroatAngleType` (inlet.c:131) — `InletStore::curb_throat`.
+enum class ThroatAngle : int { HORIZONTAL = 0, INCLINED = 1, VERTICAL = 2 };
+
+/// `InletStore::curve_kind` codes for a CUSTOM design.
+enum class CurveKind : int { UNRESOLVED = 0, DIVERSION = 1, RATING = 2 };
+
+/// Legacy MIN_RUNOFF_FLOW (consts.h:203) — cfs.
+inline constexpr double MIN_RUNOFF_FLOW = 0.001;
+/// Legacy FUDGE (consts.h:272).
+inline constexpr double INLET_FUDGE = 0.0001;
+/// Legacy BIG (consts.h:118).
+inline constexpr double INLET_BIG = 1.0e10;
+
+// ============================================================================
+// Kernel inputs — the legacy module-level shared variables, made explicit
+// ============================================================================
+
+/**
+ * @brief Street / channel geometry seen by one inlet, in INTERNAL units.
+ *
+ * @details Mirrors the file-scope block of legacy inlet.c (`Sx`, `SL`, `Sw`,
+ *          `a`, `W`, `T`, `n`, `Nsides`, `Tcrown`, `Beta`, `Qfactor`, `xsect`)
+ *          that `getConduitGeometry()` (inlet.c:1147-1196) fills. `t` (the flow
+ *          spread) is an output of `getFlowSpread()` that later kernels read,
+ *          exactly as legacy's shared `T` is.
+ */
+struct Geom {
+    double sx      = 0.01;   ///< Street cross slope (fraction)
+    double sl      = 0.0;    ///< Conduit longitudinal slope (fraction)
+    double sw      = 0.01;   ///< Gutter + cross slope
+    double a       = 0.0;    ///< Gutter depression (ft)
+    double w       = 0.0;    ///< Gutter width (ft)
+    double t       = 0.0;    ///< Top width of flow spread (ft) — set by getFlowSpread
+    double n       = 0.016;  ///< Manning's roughness
+    int    nsides  = 1;      ///< 1- or 2-sided street
+    double t_crown = 100.0;  ///< Distance from curb to crown (ft)
+    double beta    = 0.0;    ///< 1.486·√SL / n
+    double qfactor = 0.0;    ///< Izzard's f in Q = f·T^2.67
+
+    /// Host conduit cross-section — non-null only for the DROP_* (channel)
+    /// designs, whose grate kernel needs A(S)/Y(A)/W(Y) of the channel.
+    const XSectParams* xs = nullptr;
+};
+
+/// One inlet design in INTERNAL units (legacy `TInletDesign`, inlet.c:66-74).
+struct Design {
+    int    type            = 0;    ///< inlet::InletType
+    int    grate_type      = static_cast(GrateType::GENERIC);
+    double grate_length    = 0.0;  ///< ft (0 ⇒ no grate half)
+    double grate_width     = 0.0;  ///< ft
+    double frac_open_area  = 0.0;  ///< GENERIC grates only
+    double splash_veloc    = 0.0;  ///< ft/s, GENERIC grates only
+    double curb_length     = 0.0;  ///< ft (0 ⇒ no curb half)
+    double curb_height     = 0.0;  ///< ft
+    int    curb_throat     = static_cast(ThroatAngle::VERTICAL);
+    double slotted_length  = 0.0;  ///< ft (0 ⇒ not a slotted drain)
+    double slotted_width   = 0.0;  ///< ft
+};
+
+/// The per-placement half of one usage row (legacy `TInlet` fields).
+struct UsageParams {
+    int    num_inlets  = 1;
+    double clog_factor = 1.0;   ///< 1 − %clog/100
+    double flow_limit  = 0.0;   ///< cfs per inlet; 0 ⇒ unlimited
+};
+
+// ============================================================================
+// Pure kernel — 1:1 ports of the legacy static functions
+// ============================================================================
+
+/// HEC-22 Eq(4-4) solved for Eo with Ts/w substituted for (T/w)−1 (inlet.c:1248).
+double getEo(double sr, double ts, double w);
+
+/// Width of flow spread, HEC-22 Eq(4-2)/(4-6) (inlet.c:1200).
+double getFlowSpread(const Geom& g, double Q);
+
+/// Ratio of the flow over width `w` to the total street flow, Eq(4-16) (inlet.c:1518).
+double getGutterFlowRatio(const Geom& g, double w);
+
+/// Ratio of the flow area above the grate to that above the depressed gutter,
+/// Eq(4-20a) numerator/denominator (inlet.c:1535).
+double getGutterAreaRatio(const Geom& g, double grate_width, double area);
+
+/// Splash-over velocity for a standard grate type (HEC-22 Chart 5B, inlet.c:1557).
+/// Returns 0 for GENERIC / out-of-range types — those carry a user velocity.
+double getSplashOverVelocity(int grate_type, double grate_length);
+
+/// On-grade grate capture, Eq(4-16)/(4-18)/(4-19)/(4-20a)/(4-21) (inlet.c:1387).
+/// Reads `g.t` (spread) and may update `g.t` / `g.sx` for a channel drop grate.
+double getGrateInletCapture(const Design& d, Geom& g, double Q);
+
+/// On-grade curb-opening capture, Eq(4-22a)/(4-23)/(4-24) (inlet.c:1477).
+double getCurbInletCapture(const Geom& g, double Q, double opening_length);
+
+/// Capture of a single on-grade inlet — type dispatch + COMBO sweeper (inlet.c:1325).
+double getOnGradeInletCapture(const Design& d, Geom& g, double Q, double depth);
+
+/// Total capture of an on-grade usage: `num_inlets` in series, both sides (inlet.c:1267).
+double getOnGradeCapturedFlow(const Design& d, const UsageParams& u, Geom& g,
+                              double q, double depth);
+
+/// On-sag grate weir/orifice flows, Eq(4-26)/(4-27) (inlet.c:1644).
+void findOnSagGrateFlows(const Design& d, const Geom& g, double depth,
+                         double* weir_flow, double* orifice_flow);
+
+/// On-sag curb weir/orifice flows with the transition band, Eq(4-28)/(4-30)
+/// (inlet.c:1703). A DROP_CURB opening acts on all four sides (`L × 4`).
+void findOnSagCurbFlows(const Design& d, const Geom& g, double depth,
+                        double opening_length,
+                        double* weir_flow, double* orifice_flow);
+
+/// Curb-opening orifice flow with the throat-angle head, Eq(4-31a) (inlet.c:1764).
+double getCurbOrificeFlow(double flow_depth, double opening_height,
+                          double opening_length, int throat_angle);
+
+/// On-sag slotted drain flow, Eq(4-32)/(4-33) (inlet.c:1785).
+double getOnSagSlottedFlow(const Design& d, double depth);
+
+/// Capture of a single on-sag inlet (inlet.c:1610).
+double getOnSagInletCapture(const Design& d, const Geom& g, double depth);
+
+/// Total capture of an on-sag usage: single inlet × `nsides_prev · num_inlets`
+/// (inlet.c:1574). `nsides_prev` is legacy's module-level Nsides as it stood on
+/// entry — the PREVIOUSLY processed inlet's street — because legacy forms
+/// totalInlets before getConduitGeometry refreshes it.
+double getOnSagCapturedFlow(const Design& d, const UsageParams& u,
+                            const Geom& g, double depth, int nsides_prev);
+
+/**
+ * @brief Capture of a CUSTOM inlet from its diversion / rating curve (inlet.c:1902).
+ *
+ * @param curve      Resolved capture curve (`InletStore::curve_index`).
+ * @param curve_kind inlet::CurveKind — DIVERSION (capture vs approach flow) or
+ *                   RATING (capture vs depth).
+ * @param ucf_flow   internal → display flow factor (curve x/y are user units).
+ * @param ucf_len    internal → display length factor.
+ */
+double getCustomCapturedFlow(const UsageParams& u, const Geom& g,
+                             const Table& curve, int curve_kind,
+                             double q, double depth,
+                             double ucf_flow, double ucf_len);
+
+/// Unclogged open area of one usage (ft²) — legacy getInletArea (inlet.c:1870).
+double getInletArea(const Design& d, const UsageParams& u);
+
+// ============================================================================
+// Runtime SoA
+// ============================================================================
+
 struct InletSoA {
     int count = 0;
-    std::vector    link_idx;       ///< Street conduit link index
-    std::vector    node_idx;       ///< Receiving node index
-    std::vector    bypass_node;    ///< Bypass node (downstream of street conduit)
+
+    // --- host / topology -----------------------------------------------------
+    std::vector    link_idx;       ///< Host conduit link index (−1 for a node host)
+    std::vector    host_node;      ///< Host inlet-junction node (−1 for a conduit host)
+    std::vector    node_idx;       ///< Capture (receiving) node index
+    std::vector    bypass_node;    ///< Node the uncaptured flow stays at
+    std::vector    up_link;        ///< Approach conduit (node host: node2 == host)
+    std::vector    up_link2;       ///< Second inbound conduit at a sag node host (−1)
+    std::vector two_inbound;   ///< 1 when both attached conduits flow toward the host
+
+    // --- design --------------------------------------------------------------
     std::vector    inlet_type;
     std::vector    grate_type;
-    std::vector grate_length;   ///< Grate inlet length (ft)
-    std::vector grate_width;    ///< Grate inlet width (ft)
-    std::vector curb_length;    ///< Curb opening length (ft)
-    std::vector curb_height;    ///< Curb opening height (ft)
-    std::vector    curb_throat;    ///< Throat angle type (0=horiz, 1=inclined, 2=vert)
-    std::vector slotted_length; ///< Slotted drain length (ft)
-    std::vector slotted_width;  ///< Slotted drain width (ft)
-    std::vector clog_factor;    ///< Clogging reduction (0-1)
-    std::vector opening_ratio;  ///< Grate opening ratio
-    std::vector    num_inlets;     ///< Number of inlets per side
-    std::vector flow_limit;     ///< Max capture flow per inlet (cfs)
-    std::vector local_depress;  ///< Local gutter depression (ft)
-    std::vector local_width;    ///< Local depression width (ft)
-    std::vector    n_sides;        ///< 1 or 2 sided street
-
-    // Street geometry (resolved from StreetStore)
-    std::vector sx;             ///< Street cross slope (fraction)
-    std::vector gutter_depression; ///< Street gutter depression (ft)
-    std::vector gutter_width;   ///< Street gutter width (ft)
-    std::vector road_roughness; ///< Street Manning's n
-    std::vector t_crown;        ///< Distance curb to crown (ft)
-
-    // Working arrays (per-inlet results)
+    std::vector grate_length;   ///< ft
+    std::vector grate_width;    ///< ft
+    std::vector open_area;      ///< GENERIC open-area fraction
+    std::vector splash_veloc;   ///< ft/s (GENERIC)
+    std::vector curb_length;    ///< ft
+    std::vector curb_height;    ///< ft
+    std::vector    curb_throat;    ///< 0=HORIZONTAL 1=INCLINED 2=VERTICAL
+    std::vector slotted_length; ///< ft
+    std::vector slotted_width;  ///< ft
+    std::vector    curve_index;    ///< CUSTOM: index into ctx.tables
+    std::vector    curve_kind;     ///< CUSTOM: inlet::CurveKind
+
+    // --- usage ---------------------------------------------------------------
+    std::vector    num_inlets;
+    std::vector clog_factor;
+    std::vector flow_limit;     ///< cfs per inlet (0 = unlimited)
+    std::vector local_depress;  ///< ft
+    std::vector local_width;    ///< ft
+    std::vector    placement;      ///< as authored (inlet::Placement)
+    std::vector is_sag;        ///< resolved placement: 1 = ON_SAG
+
+    // --- street / conduit geometry (internal units) --------------------------
+    std::vector sx;                 ///< Cross slope (fraction)
+    std::vector gutter_depression;  ///< ft
+    std::vector gutter_width;       ///< ft
+    std::vector road_roughness;     ///< Manning's n
+    std::vector t_crown;            ///< ft
+    std::vector    n_sides;
+    std::vector slope;              ///< Host/approach conduit slope
+    std::vector flow_factor;        ///< Izzard f = (0.56/n)·√SL·Sx^1.67
+
+    // --- per-step results ----------------------------------------------------
+    std::vector q_approach;     ///< Approach flow seen this step (cfs)
     std::vector flow_capture;   ///< Captured flow rate (cfs)
+    std::vector backflow;       ///< Backflow from the capture node (cfs)
+    std::vector backflow_ratio; ///< inlet backflow / capture-node overflow
 
-    // Gap #56: backflow — fraction of capture node overflow that returns to bypass
-    std::vector backflow_ratio; ///< Pre-computed fraction of node overflow → backflow
-    std::vector backflow;       ///< Current backflow rate (cfs), updated each step
+    // --- legacy statistics (inlet.c:78-87, updateInletStats :985) ------------
+    std::vector    flow_periods;
+    std::vector    capture_periods;
+    std::vector    backflow_periods;
+    std::vector peak_flow;          ///< Peak approach flow (cfs)
+    std::vector peak_flow_capture;  ///< Capture efficiency at peak flow (%)
+    std::vector avg_flow_capture;   ///< Σ capture efficiency over capture periods
+    std::vector bypass_freq;        ///< # capture periods that also bypassed
 
-    // Gap #68: statistics (accumulated each timestep)
-    std::vector stat_capture_vol;   ///< Total captured volume (ft³)
-    std::vector stat_bypass_vol;    ///< Total bypassed volume (ft³)
-    std::vector stat_backflow_vol;  ///< Total backflow volume (ft³)
-    std::vector stat_peak_flow;     ///< Peak captured flow rate (cfs)
+    // --- volume statistics (Gap #68 → InletUsageStore) -----------------------
+    std::vector stat_capture_vol;   ///< ft³
+    std::vector stat_bypass_vol;    ///< ft³
+    std::vector stat_backflow_vol;  ///< ft³
+    std::vector stat_peak_flow;     ///< Peak captured flow (cfs)
 
     void resize(int n);
 };
 
 class InletSolver {
 public:
+    /// Resolve designs, street geometry, host topology and placement.
     void init(SimulationContext& ctx);
 
     /**
-     * @brief Batch compute inlet capture for all inlets.
+     * @brief Compute capture + backflow and fold them into `nodes.lat_flow`.
+     *
+     * @details Runs at the END of `SWMMEngine::assembleLateralInflows`, i.e.
+     *          BEFORE the router sees `lat_flow` — matching legacy
+     *          `inlet_findCapturedFlows` at routing.c:244 (plan G6).
      *
      * @param ctx  Simulation context.
-     * @param dt   Timestep (seconds).
+     * @param dt   Routing timestep (seconds).
      */
     void computeAll(SimulationContext& ctx, double dt);
 
     /**
-     * @brief Adjust quality inflows at bypass and capture nodes for inlet transfers.
-     *
-     * @details Gap #55: called after hydraulic routing + inlet capture, before
-     *          quality routing. For each inlet, transfers pollutant mass based on
-     *          net flow direction (capture → capture node, backflow → bypass node).
-     *          Matches legacy `inlet_adjustQualInflows()`.
+     * @brief Adjust quality inflows at the bypass and capture nodes.
      *
-     * @param ctx  Simulation context.
-     * @param dt   Routing timestep (seconds).
+     * @details Called after hydraulic routing, before quality routing; moves
+     *          pollutant mass by the net flow direction. Matches legacy
+     *          `inlet_adjustQualInflows()`. Covers both host kinds.
      */
     void adjustQualInflows(SimulationContext& ctx, double dt);
 
     /**
-     * @brief Gap #68: Copy accumulated stats from internal SoA into InletUsageStore.
-     *        Called by SWMMEngine::report() before writing summary reports.
+     * @brief Take the backflow returned to the street back out of the
+     *        system flooding totals.
+     *
+     * @details A capture node's overflow is handed back to the street through
+     *          its inlets as backflow (computeAll), so it never leaves the
+     *          system — booking it as flooding counts the same water once as a
+     *          loss and once as water put back on the corridor. Matches legacy
+     *          `inlet_adjustQualOutflows()` (inlet.c:706), called from
+     *          routing.c:260 directly after `removeSystemOutflows()`.
+     *
+     * @param ctx  Simulation context.
+     * @param dt   Routing timestep (seconds).
      */
-    void gatherStats(InletUsageStore& usages) const;
+    void adjustFloodingTotals(SimulationContext& ctx, double dt) const;
 
-private:
-    InletSoA soa_;
+    /// Copy accumulated statistics into `ctx.inlet_usages` (volumes, Gap #68)
+    /// and `ctx.inlet_diag` (the legacy per-inlet performance block the report
+    /// needs). Called by SWMMEngine::report() before the summary tables.
+    void gatherStats(SimulationContext& ctx) const;
 
-    /// On-grade grate capture efficiency (HEC-22 Eq 4-19/4-21).
-    static double grateCapture(double flow, double velocity, double length,
-                                double sx, int grate_type, double open_ratio);
+    const InletSoA& soa() const noexcept { return soa_; }
+    bool hasInlets() const noexcept { return soa_.count > 0; }
 
-    /// On-grade curb opening capture (HEC-22 Eq 4-22a/4-23).
-    static double curbCapture(double flow, double curb_length,
-                               double sx, double sl, double n,
-                               double gutter_depress, double gutter_width,
-                               double spread);
+private:
+    InletSoA soa_;
 
-    /// Splash-over velocity for grate type.
-    static double splashOverVelocity(double length, int grate_type);
+    /// Scratch, sized to the node count in init(): legacy `InletFlow[]` and the
+    /// non-DW `Node[].inflow` pre-pass (inlet.c:572-579). Members so computeAll
+    /// allocates nothing (it is called from a noexcept assembly step).
+    std::vector node_inlet_flow_;
+    std::vector node_inflow_;
 
-    /// Compute flow spread from Izzard's Manning equation for triangular gutter.
-    static double computeFlowSpread(double flow, double qfactor,
-                                     double sx, double sw, double a_gutter,
-                                     double w_gutter, double t_crown);
+    /// Legacy inlet.c's file-scope `Nsides`, which OUTLIVES each inlet and each
+    /// routing step (a static, zero at the first evaluation). getOnSagCaptured-
+    /// Flow reads it for `totalInlets = Nsides * numInlets` BEFORE
+    /// getConduitGeometry refreshes it, so an on-sag inlet is scaled by the
+    /// street sides of the PREVIOUSLY processed inlet — a HalfStreet sag inlet
+    /// captures double when the inlet before it sat on a FullStreet
+    /// (example7-inlets' Street5). Reproduced deliberately; see computeAll.
+    int nsides_prev_ = 0;
 
-    /// Compute Eo (gutter flow ratio) from HEC-22 Eq 4-4.
-    static double computeEo(double sr, double ts, double w);
+    /// Per-node flag for legacy's `Node[].inlet == CAPTURE` (inlet.c:512),
+    /// set in init() for every valid usage's capture node. Sized to the node
+    /// count; empty when the model has no inlets.
+    std::vector is_capture_node_;
 
-    /// Compute on-grade capture for a single inlet (grate, curb, combo, slotted).
-    double computeOnGradeCapture(int idx, double flow, double depth) const;
+    /// Assemble the kernel geometry block for row `ii` (legacy getConduitGeometry).
+    Geom geomOf(const SimulationContext& ctx, int ii,
+                const XSectParams* xs) const;
+    /// Assemble the design block for row `ii`.
+    Design designOf(int ii) const;
+    /// Assemble the usage block for row `ii`.
+    UsageParams usageOf(int ii) const;
 
-    /// Gap #56: Total unclogged open area of inlet ii (ft²). Returns 0 for CUSTOM type.
-    double getInletArea(int ii) const noexcept;
+    /// Legacy updateInletStats (inlet.c:985) for row `ii` at approach flow `q`.
+    void updateStats(int ii, double q);
 
-    /// Gap #56: Pre-compute backflow_ratio[] for all inlets from capture-node topology.
+    /// Pre-compute backflow_ratio[] from the capture-node topology
+    /// (legacy getBackflowRatios, with the inlet.c:1836 node-index bug fixed).
     void computeBackflowRatios();
 };
 
diff --git a/src/engine/hydraulics/KinematicWave.cpp b/src/engine/hydraulics/KinematicWave.cpp
index 8d9e5c389..a79bd76a0 100644
--- a/src/engine/hydraulics/KinematicWave.cpp
+++ b/src/engine/hydraulics/KinematicWave.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file KinematicWave.cpp
  * @brief Kinematic wave routing — batch-oriented, numerically identical to legacy.
@@ -13,13 +29,18 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "KinematicWave.hpp"
 #include "XSectBatch.hpp"
+#include "Link.hpp"
 #include "../core/SimulationContext.hpp"
+#include "../core/UnitConversion.hpp"
+#include "HydStructures.hpp"
 #include "Node.hpp"
+#include "Divider.hpp"
+#include "../math/FindRoot.hpp"
 
 #include 
 #include 
@@ -27,9 +48,155 @@
 namespace openswmm {
 namespace kinwave {
 
-static constexpr int    MAX_ITERS = 40;
 static constexpr double TINY      = 1.0e-6;
 
+// Storage successive-approximation constants (legacy flowrout.c:56-58).
+static constexpr int    STOR_MAXITER = 10;
+static constexpr double STOR_OMEGA   = 0.55;
+static constexpr double STOR_STOPTOL = 0.005;
+
+// ============================================================================
+// Tree-layout routing helpers (legacy flowrout.c) — shared with STEADY
+// ============================================================================
+
+static XSectParams buildXSP_KW(const SimulationContext& ctx, std::size_t uk);
+
+/// PARITY node.c:1008 storage_getOutflow — flow from a storage unit into a
+/// CONDUIT is the conduit's NORMAL-DEPTH flow at the pond's current depth,
+/// not the pond's inflow. (Non-conduit outlets have their own head-discharge
+/// functions; legacy returns 0 for them here.)
+static double storageConduitOutflow(SimulationContext& ctx, int i, int j) {
+    const auto uj = static_cast(j);
+    const auto ui = static_cast(i);
+    if (ctx.links.type[uj] != LinkType::CONDUIT) return 0.0;
+
+    const double y = ctx.nodes.depth[ui] - ctx.links.offset1[uj];
+    if (y <= 0.0) return 0.0;
+
+    const auto& CD = ctx.link_subtypes.conduits;
+    const auto ucr = static_cast(ctx.link_subtypes.conduit_row(j));
+    if (y >= ctx.links.xsect_y_full[uj]) return CD.q_full[ucr];
+
+    const XSectParams xs = buildXSP_KW(ctx, uj);
+    const double a = xsect::getAofY(xs, y);
+    return CD.beta[ucr] * xsect::getSofA(xs, a);
+}
+
+double getLinkInflow(SimulationContext& ctx,
+                     hydstruct::StructureSolver* structures,
+                     int j, double dt) {
+    auto& links = ctx.links;
+    auto& nodes = ctx.nodes;
+    const auto uj = static_cast(j);
+
+    const int n1 = links.node1[uj];
+    if (n1 < 0) return 0.0;
+    const auto un1 = static_cast(n1);
+
+    const LinkType lt = links.type[uj];
+    double q = 0.0;
+
+    // PARITY link.c:553 link_getInflow: a link whose setting is 0 (closed
+    // by a control rule) admits NO inflow, before any type dispatch — the
+    // conduit still routes (kinwave_execute runs with qin = 0) and drains.
+    if (links.setting[uj] == 0.0) return 0.0;
+
+    if (lt == LinkType::CONDUIT) {
+        // PARITY link.c conduit_getInflow → node_getOutflow: a conduit
+        // draining a STORAGE unit carries normal-depth flow at the pond's
+        // depth; off a DIVIDER it carries that divider's split; off any
+        // other node it carries that node's inflow + overflow (node.c:395).
+        // qLimit then caps the inflow (link.c:1331).
+        if (nodes.type[un1] == NodeType::STORAGE)
+            q = storageConduitOutflow(ctx, n1, j);
+        else if (nodes.type[un1] == NodeType::DIVIDER)
+            q = divider::getOutflow(ctx, n1, j);
+        else
+            q = nodes.inflow[un1] + nodes.overflow[un1];
+        const double qlim = links.q_limit[uj];
+        if (qlim > 0.0 && q > qlim) q = qlim;
+    } else if (lt == LinkType::PUMP || nodes.type[un1] == NodeType::STORAGE) {
+        // PARITY link.c:546 link_getInflow — evaluate the structure's own
+        // head-discharge relation at the upstream node's CURRENT depth.
+        if (structures) {
+            const double q_saved = links.flow[uj];
+            structures->computeNonConduitFlowOne(ctx, dt, nullptr, j);
+            q = links.flow[uj];
+            // The trial evaluations inside updateStorageState must not leave
+            // a flow behind; the caller stores the accepted value explicitly.
+            links.flow[uj] = q_saved;
+        }
+    }
+    // else: a non-conduit draining a non-storage node carries no flow under
+    // KW/SF (legacy `else q = 0.0`) — there is no head to drive it.
+
+    return node::getMaxOutflow(nodes, n1, q, dt);
+}
+
+void updateStorageState(SimulationContext& ctx,
+                        hydstruct::StructureSolver* structures,
+                        const std::vector& order,
+                        int pos, int i, double dt) {
+    auto& nodes = ctx.nodes;
+    const auto ui = static_cast(i);
+    const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+
+    // --- terms of the flow balance that do not depend on end-of-step depth
+    //     (legacy flowrout.c:563-565). The trapezoidal average of old and new
+    //     net inflow is what makes this second-order in time.
+    const double v_fixed = nodes.old_volume[ui]
+        + 0.5 * (nodes.old_net_inflow[ui] + nodes.inflow[ui] - nodes.outflow[ui]) * dt;
+
+    const double full_vol = node::getVolume(nodes, i, nodes.full_depth[ui],
+                                            &ctx.tables, us, &ctx.node_subtypes);
+
+    // --- sum the outflow of every link this node drains through, at the
+    //     current depth estimate (legacy getStorageOutflow). The sorted order
+    //     emits a node's outgoing links contiguously.
+    auto storageOutflow = [&]() {
+        double outflow = 0.0;
+        for (std::size_t k = static_cast(pos); k < order.size(); ++k) {
+            const int m = order[k];
+            if (ctx.links.node1[static_cast(m)] != i) break;
+            outflow += getLinkInflow(ctx, structures, m, dt);
+        }
+        return outflow;
+    };
+
+    double d1 = nodes.depth[ui];
+    // legacy: `iter = 1; while (iter < MAXITER && !stopped)` — at most
+    // MAXITER - 1 = 9 passes. A storage whose pump switches at the trial
+    // depth oscillates between two states, and the pass count decides
+    // which one the step keeps (304-nodes-234-subs' wet well 1: a tenth pass
+    // handed PumpSR the ON state legacy leaves OFF).
+    for (int iter = 1; iter < STOR_MAXITER; ++iter) {
+        double v2 = v_fixed - 0.5 * storageOutflow() * dt;
+        v2 = std::max(v2, 0.0);
+
+        nodes.overflow[ui] = 0.0;
+        if (v2 > full_vol) {
+            nodes.overflow[ui] =
+                (v2 - std::max(nodes.old_volume[ui], full_vol)) / dt;
+            if (nodes.overflow[ui] < constants::FUDGE) nodes.overflow[ui] = 0.0;
+            if (!ctx.options.allow_ponding || nodes.ponded_area[ui] == 0.0)
+                v2 = full_vol;
+        }
+
+        nodes.volume[ui] = v2;
+        double d2 = node::getDepth(nodes, i, v2, &ctx.tables, us,
+                                   &ctx.node_subtypes);
+        nodes.depth[ui] = d2;
+
+        // Under-relaxation on the DEPTH iterate only — the volume and depth
+        // written above stay the un-relaxed pair that satisfies the balance.
+        d2 = (1.0 - STOR_OMEGA) * d1 + STOR_OMEGA * d2;
+        const bool stop = std::fabs(d2 - d1) <= STOR_STOPTOL;
+        d1 = d2;
+        if (stop) break;
+    }
+    nodes.head[ui] = nodes.invert_elev[ui] + nodes.depth[ui];
+}
+
 // ============================================================================
 // Init
 // ============================================================================
@@ -48,6 +215,8 @@ void KWSolver::init(int n_conduits, const XSectGroups& /*groups*/) {
     q_out_.resize(un);
     a_out_.resize(un);
     sf_in_.resize(un);
+    y1_.assign(un, 0.0);
+    y2_.assign(un, 0.0);
 }
 
 // ============================================================================
@@ -86,6 +255,23 @@ int KWSolver::solveConduit(int idx, const XSectParams& xs,
         a_in_norm = xsect::getAofS(xs, s_needed) / a_full;
     }
 
+    // Legacy kinwave.c early no-flow branch (`qin <= TINY && q2 <= TINY`):
+    // negligible inflow with a negligible previous outflow yields EXACT
+    // zeros with no continuity solve. Skipping this let the Newton solve
+    // produce ~1e-8 outflows from a dry start, seeding a startup transient
+    // that took ~250 report periods to relax (extran1-kw-divider).
+    if (q_in_norm <= TINY && prev_q2 <= TINY) {
+        a_in_[ui]  = a_in_norm * a_full;
+        a_out_[ui] = 0.0;
+        q_out_[ui] = 0.0;
+        // Same normalise → denormalise round trip as the main path below.
+        if (q_in_norm > 1.0) q_in_norm = 1.0;
+        q_in_[ui] = q_in_norm * q_full;
+        q1_[ui] = q_in_[ui]; a1_[ui] = a_in_[ui];
+        q2_[ui] = 0.0;       a2_[ui] = 0.0;
+        return 1;
+    }
+
     // Finite-difference coefficients
     double dxdt = length / dt * a_full / q_full;
     double dq = prev_q2 - prev_q1;
@@ -93,105 +279,96 @@ int KWSolver::solveConduit(int idx, const XSectParams& xs,
     double C1 = dxdt * WT / WX;
     double C2 = (1.0 - WT) * (a_in_norm - prev_a1);
     C2 -= WT * prev_a2;
-    C2 *= dxdt / WX;
-    C2 += (1.0 - WX) / WX * dq - q_in_norm;
-    C2 += q3 / WX;
-
-    // Gap #59: bound the Newton iteration using the same Amax bracket that
-    // legacy kinwave.c uses (findroot_Newton with aLo/aHi bounds).
-    //
-    // The section factor S(a) peaks at a = Amax (< a_full for non-circular
-    // shapes). Above Amax, S decreases back toward s_full, so the continuity
-    // function f(a) = beta1*S(a) + C1*a + C2 can have two roots.
-    // Legacy pre-screens for this:
-    //   aHi = 1.0 (full area),   fHi = 1 + C1 + C2
-    //   aLo = getAmax(xs),       fLo = beta1*s_max + C1*aLo + C2
-    // If fLo and fHi share the same sign, reset the bracket:
-    //   [0, aLo] → handles near-zero-flow and high-flow cases
-    // If both bounds produce negative f → full flow (no sub-critical root).
-    // If both bounds produce positive f → zero flow.
+    // legacy's statements, left to right: (C2 * dxdt) / WX, then
+    // (C2 + k*dq) - qin — not C2 * (dxdt / WX) or C2 + (k*dq - qin), each
+    // an ulp off on the first wet steps (runoff2-sw5).
+    C2 = C2 * dxdt / WX;
+    C2 = C2 + (1.0 - WX) / WX * dq - q_in_norm;
+    C2 = C2 + q3 / WX;
+
+    // legacy solveContinuity (kinwave.c), op for op: bracket f(a) =
+    // Beta1*S(a) + C1*a + C2 between the area of maximum section factor
+    // and full area, fall back to [0, aLo] when both ends share a sign,
+    // hand the previous outlet area (or the bracket's midpoint when it lies
+    // outside) to findroot_Newton with the ends switched when f(aLo) >
+    // f(aHi); both ends negative = full flow, both positive = no flow. The
+    // former home-grown Newton loop (own start guess, per-step bracket
+    // clamps, its own stop test) took a different path on the first wet
+    // step of every kinematic-wave conduit (runoff2-sw5's 101: 3.77e-5 vs
+    // legacy 3.40e-5 cfs).
     double aHi = 1.0;
-    double fHi = 1.0 + C1 + C2;     // f(a=1.0): beta1*s_full = 1 by construction
-    double aLo = xsect::getAmax(xs); // normalized area at max section factor
-    double fLo = beta1 * xs.s_max + C1 * aLo + C2;
-
-    if (aLo >= aHi) { aLo = 0.0; fLo = C2; }  // shouldn't happen; guard anyway
+    double fHi = 1.0 + C1 + C2;
+    // xsect_getAmax: Amax[type]*aFull, or aBot for IRREGULAR / CUSTOM
+    // (the kernel's getAmax is the ratio Amax[type]).
+    double aLo = (xs.type == static_cast(XSectShape::IRREGULAR) ||
+                  xs.type == static_cast(XSectShape::CUSTOM))
+                 ? xs.a_bot / a_full : xsect::getAmax(xs);
+    double fLo;
+    if (aLo < aHi) fLo = (beta1 * xs.s_max) + (C1 * aLo) + C2;
+    else           fLo = fHi;
 
     if (fHi * fLo > 0.0) {
-        // Same sign — root is not between [aLo, aHi]; reset bracket to [0, aLo]
         aHi = aLo;
         fHi = fLo;
         aLo = 0.0;
         fLo = C2;
     }
 
-    // Both bounds negative → flow always exceeds maximum; use full flow
-    if (fLo < 0.0 && fHi < 0.0) {
-        a_in_[ui]  = a_in_norm * a_full;
-        a_out_[ui] = a_full;   // full-pipe area
-        q_out_[ui] = q_full;   // cap at full flow
-        q1_[ui] = q_in_[ui];  a1_[ui] = a_in_[ui];
-        q2_[ui] = q_out_[ui]; a2_[ui] = a_out_[ui];
-        return -2;
-    }
-
-    // Both bounds positive → no flow
-    if (fLo > 0.0 && fHi > 0.0) {
-        a_in_[ui]  = a_in_norm * a_full;
-        a_out_[ui] = 0.0;
-        q_out_[ui] = 0.0;
-        q1_[ui] = q_in_[ui];  a1_[ui] = a_in_[ui];
-        q2_[ui] = 0.0;        a2_[ui] = 0.0;
-        return -3;
-    }
-
-    // Ensure fLo < fHi for monotone bracketing
-    if (fLo > fHi) {
-        std::swap(aLo, aHi);
-        std::swap(fLo, fHi);
-    }
-
-    // Newton-Raphson: solve f(a) = beta1*S(a*Afull) + C1*a + C2 = 0
-    // Initial guess: previous outlet area (warm start), clamped to [aLo, aHi].
-    double a = (prev_a2 > TINY) ? prev_a2 : a_in_norm;
-    a = std::max(std::min(a, aHi), aLo);
-
-    int iters = 0;
-    for (; iters < MAX_ITERS; ++iters) {
-        double a_abs = a * a_full;
-        double s = xsect::getSofA(xs, a_abs);
-        double f = beta1 * s + C1 * a + C2;
-
-        double dsda = xsect::getdSdA(xs, a_abs);
-        double df = beta1 * a_full * dsda + C1;
-
-        if (std::fabs(df) < TINY) break;
-
-        double da = -f / df;
-        a += da;
-        // Clamp to bracket so Newton doesn't wander past Amax or below zero
-        a = std::max(std::min(a, aHi), aLo);
-        if (std::fabs(da) < EPSIL) break;
+    double a = prev_a2;
+    int result;
+    if (fHi * fLo <= 0.0) {
+        if (a < aLo || a > aHi) a = 0.5 * (aLo + aHi);
+        if (fLo > fHi) {
+            const double aTmp = aLo;
+            aLo = aHi;
+            aHi = aTmp;
+        }
+        result = findroot::newton(aLo, aHi, &a, EPSIL,
+            [&](double an, double* f, double* df) {
+                *f  = (beta1 * xsect::getSofA(xs, an * a_full)) + (C1 * an) + C2;
+                *df = (beta1 * a_full * xsect::getdSdA(xs, an * a_full)) + C1;
+            });
+        if (result <= 0) result = -1;
+    } else if (fLo < 0.0) {
+        // both bounds negative → full flow
+        a = (q_in_norm > 1.0) ? a_in_norm : 1.0;
+        result = -2;
+    } else if (fLo > 0.0) {
+        // both bounds positive → no flow
+        a = 0.0;
+        result = -3;
+    } else {
+        result = -1;
     }
-    a = std::max(a, 0.0);
+    // legacy reports ERR_KINWAVE and returns when the root finder fails;
+    // the engine keeps the finder's last iterate (the bracket holds it).
+    if (result <= 0) result = 1;
 
-    // Outflow from outlet area
-    double s_out = xsect::getSofA(xs, a * a_full);
-    double q_out_norm = beta1 * s_out;
-    q_out_norm = std::max(q_out_norm, 0.0);
+    // Outflow from outlet area (legacy: qout = Beta1 * S(aout*Afull))
+    double q_out_norm = beta1 * xsect::getSofA(xs, a * a_full);
 
     // De-normalise and store
     a_in_[ui]  = a_in_norm * a_full;
     a_out_[ui] = a * a_full;
     q_out_[ui] = q_out_norm * q_full;
 
+    // Legacy post-solve inflow cap (kinwave.c: `if (qin > 1.0) qin = 1.0`) —
+    // the accepted inflow returned to the node never exceeds qFull. Legacy
+    // caps the NORMALISED inflow and then writes `Conduit[k].q1 = qin * Qfull`,
+    // so the value handed back to the node has been through a divide by Qfull
+    // and a multiply by it again — a round trip that is NOT the identity in
+    // IEEE-754. Keeping the raw dimensional inflow instead left the upstream
+    // node's outflow 1 ULP light (1710-2014-20year-r3's J1 at step 6).
+    if (q_in_norm > 1.0) q_in_norm = 1.0;
+    q_in_[ui] = q_in_norm * q_full;
+
     // Update state for next timestep
     q1_[ui] = q_in_[ui];
     a1_[ui] = a_in_[ui];
     q2_[ui] = q_out_[ui];
     a2_[ui] = a_out_[ui];
 
-    return iters;
+    return result;
 }
 
 // ============================================================================
@@ -199,10 +376,11 @@ int KWSolver::solveConduit(int idx, const XSectParams& xs,
 // ============================================================================
 
 /// Build XSectParams from link SoA data (matching DynamicWave.cpp::buildXSP).
-static XSectParams buildXSP_KW(const LinkData& links, std::size_t uk) {
+static XSectParams buildXSP_KW(const SimulationContext& ctx, std::size_t uk) {
+    const LinkData& links = ctx.links;
     XSectParams xs{};
     auto ls = links.xsect_shape[uk];
-    xs.type = (ls == XsectShape::DUMMY) ? 0 : static_cast(ls) + 1;
+    xs.type = link::translateShape(ls);
     xs.y_full = links.xsect_y_full[uk];
     xs.a_full = links.xsect_a_full[uk];
     xs.w_max  = links.xsect_w_max[uk];
@@ -213,15 +391,39 @@ static XSectParams buildXSP_KW(const LinkData& links, std::size_t uk) {
     xs.a_bot  = links.xsect_a_bot[uk];
     xs.s_bot  = links.xsect_s_bot[uk];
     xs.r_bot  = links.xsect_r_bot[uk];
+    // Tabulated shapes (IRREGULAR / CUSTOM / STREET) carry their A/R/W vs depth
+    // in per-link transect tables; without them every scalar getter returns 0.
+    // Under KW that made getAofS's Newton walk its whole bracket and report the
+    // conduit's FULL inlet area for a trickle of inflow (1710-2014-20year-r3's
+    // transect channels), so the upstream node depth came out full instead of
+    // ~2 mm. Same block as DynamicWave.cpp::buildXSP.
+    if (ls == XsectShape::IRREGULAR || ls == XsectShape::CUSTOM ||
+        ls == XsectShape::STREET_XSECT) {
+        const int ci = links.xsect_curve[uk];
+        if (ci >= 0 && static_cast(ci) < ctx.transect_tables.size()) {
+            const auto& td = ctx.transect_tables[static_cast(ci)];
+            xs.transect          = ci;
+            xs.area_tbl          = td.area_tbl;
+            xs.hrad_tbl          = td.hrad_tbl;
+            xs.width_tbl         = td.width_tbl;
+            xs.area_lut          = &td.area_lut;
+            xs.transect_tbl_size = transect::N_TRANSECT_TBL;
+        }
+    }
     return xs;
 }
 
-int KWSolver::execute(SimulationContext& ctx, double dt) {
+int KWSolver::execute(SimulationContext& ctx, double dt,
+                      hydstruct::StructureSolver* structures) {
     auto& links = ctx.links;
     auto& nodes = ctx.nodes;
     int total_iters = 0;
     int n_solved = 0;
 
+    storage_updated_.assign(static_cast(ctx.n_nodes()), 0);
+    std::fill(y1_.begin(), y1_.end(), 0.0);
+    std::fill(y2_.begin(), y2_.end(), 0.0);
+
     // Process links in topological order (upstream → downstream).
     // If no sorted order set, fall back to natural order.
     const auto& order = sorted_links_.empty()
@@ -238,28 +440,51 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
         int j = order[static_cast(idx)];
         auto uj = static_cast(j);
 
-        // Skip non-conduit links — pass through flow unchanged
+        // PARITY flowrout.c:181-183 — if this link drains a storage unit,
+        // converge that unit's depth BEFORE routing the link, so an outlet
+        // structure is evaluated at the end-of-step depth it actually sees.
+        // `updated` guards the node against a second pass when it has more
+        // than one outlet link (legacy Node[i].updated).
+        {
+            int n1s = links.node1[uj];
+            if (n1s >= 0 && nodes.type[static_cast(n1s)] == NodeType::STORAGE
+                && !storage_updated_[static_cast(n1s)]) {
+                updateStorageState(ctx, structures, order, idx, n1s, dt);
+                storage_updated_[static_cast(n1s)] = 1;
+            }
+        }
+
+        // Non-conduit links (pump / orifice / weir / outlet) are not routed —
+        // kinwave_execute returns *qoutflow = *qinflow for them (legacy
+        // kinwave.c:113-117) — but their INFLOW is their own head-discharge
+        // relation, not the upstream node's inflow (legacy getLinkInflow).
         if (links.type[uj] != LinkType::CONDUIT) {
-            // Non-conduit: outflow = inflow from upstream node
             int n1 = links.node1[uj];
-            if (n1 >= 0) {
-                double q = nodes.inflow[static_cast(n1)];
-                links.flow[uj] = q;
-                int n2 = links.node2[uj];
-                if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
-            }
+            int n2 = links.node2[uj];
+            double q = getLinkInflow(ctx, structures, j, dt);
+            links.flow[uj] = q;
+            if (n1 >= 0) nodes.outflow[static_cast(n1)] += q;
+            if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
             continue;
         }
 
-        // Skip dummy cross-sections
+        // Dummy cross-sections: legacy routes them like every other link —
+        // getLinkInflow (divider/storage dispatch, qLimit and max-outflow
+        // caps) then kinwave_execute returns qout = qin (kinwave.c:113-117)
+        // — and scatters BOTH the upstream node's outflow and the
+        // downstream node's inflow (flowrout.c:196-197).
         if (links.xsect_shape[uj] == XsectShape::DUMMY) {
             int n1 = links.node1[uj];
             int n2 = links.node2[uj];
-            if (n1 >= 0 && n2 >= 0) {
-                double q = nodes.inflow[static_cast(n1)];
-                links.flow[uj] = q;
-                nodes.inflow[static_cast(n2)] += q;
-            }
+            double q = getLinkInflow(ctx, structures, j, dt);
+            links.flow[uj] = q;
+            if (n1 >= 0) nodes.outflow[static_cast(n1)] += q;
+            if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
+            // legacy kinwave_execute leaves a dummy's a1/a2 at 0, so
+            // setNewLinkState reports depth 0 and volume 0 (extran1-dummy's
+            // 8040 kept the FUDGE depth its initialisation left).
+            links.depth[uj]  = 0.0;
+            links.volume[uj] = 0.0;
             continue;
         }
         auto& CD = ctx.link_subtypes.conduits;
@@ -270,11 +495,9 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
         int n1 = links.node1[uj];
         double qin = 0.0;
         if (n1 >= 0) {
-            auto un1 = static_cast(n1);
-            qin = nodes.inflow[un1];
-            // Limit by available volume at node (prevent negative depth)
-            double q_max = node::getMaxOutflow(nodes, n1, qin, dt);
-            qin = std::min(qin, q_max);
+            // Legacy getLinkInflow (flowrout.c:517): storage/divider/junction
+            // dispatch, the conduit's qLimit, then the max-outflow cap.
+            qin = getLinkInflow(ctx, structures, j, dt);
         }
 
         // Divide by barrels (KW solves per barrel)
@@ -282,17 +505,22 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
         double qin_per_barrel = qin / barrels;
 
         // Build XSectParams for this conduit
-        XSectParams xs = buildXSP_KW(links, uj);
+        XSectParams xs = buildXSP_KW(ctx, uj);
 
         double q_full = CD.q_full[ucr];
         double a_full = links.xsect_a_full[uj];
         double s_full = links.xsect_s_full[uj];
         double beta   = CD.beta[ucr];
-        double length = CD.mod_length[ucr];
+        // legacy kinwave.c:126 / flowrout.c:507 take link_getLength(j) —
+        // the routing length. Under KW modLength never differs from the
+        // authored length (lengthening is dynamic-wave only), but an
+        // IRREGULAR conduit's routing length does.
+        double length = CD.true_length[ucr];
         if (length <= 0.0) length = CD.length[ucr];
 
-        // Compute evaporation + seepage loss rate
-        double loss_rate = CD.evap_loss_rate[ucr] + CD.seep_loss_rate[ucr];
+        // Evaporation + seepage loss rate, capped on this solve's per-barrel
+        // inflow (legacy link_getLossRate(j, KW, qin*Qfull, tStep)).
+        double loss_rate = capConduitLoss(ctx, ucr, std::fabs(qin_per_barrel));
 
         // Set inflow for this conduit
         q_in_[uj] = qin_per_barrel;
@@ -308,6 +536,9 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
         double qout = q_out_[uj] * barrels;
         qin = q_in_[uj] * barrels;  // may have been capped at qFull
         links.flow[uj] = qout;
+        // Legacy qualrout.c:318 mixes with Conduit.q1, not Link.newFlow
+        // (q2). Preserve the accepted upstream rate for all transport passes.
+        links.kw_inflow[uj] = qin;
 
         // Update node flows
         if (n1 >= 0) {
@@ -323,6 +554,8 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
         double y_out = xsect::getYofA(xs, a_out_[uj]);
         links.depth[uj]  = 0.5 * (y_in + y_out);
         links.volume[uj] = 0.5 * (a_in_[uj] + a_out_[uj]) * length * barrels;
+        y1_[uj] = y_in;
+        y2_[uj] = y_out;
 
         // Gap #57: persist full-pipe state (bit 0 = upstream, bit 1 = downstream)
         {
@@ -333,32 +566,164 @@ int KWSolver::execute(SimulationContext& ctx, double dt) {
             }
             CD.full_state[ucr] = fs;
         }
-
-        // Update non-storage end-node depths (Gap #13)
-        // Matches legacy setNewLinkState/updateNodeDepth in flowrout.c:
-        //   non-storage nodes get max(current_depth, conduit_end_depth + offset)
-        auto updateNodeDepth = [&](int ni, double y_conduit, double link_offset) {
-            if (ni < 0) return;
-            auto uni = static_cast(ni);
-            NodeType nt = nodes.type[uni];
-            if (nt == NodeType::STORAGE) return;  // storage updated separately
-            double y = y_conduit + link_offset;
-            // If flooded non-outfall, clamp to full depth
-            if (nt != NodeType::OUTFALL && nodes.overflow[uni] > 0.0)
-                y = nodes.full_depth[uni];
-            // Only raise depth, never lower (take max)
-            if (nodes.depth[uni] < y) {
-                nodes.depth[uni] = std::min(y, nodes.full_depth[uni] > 0.0
-                                              ? nodes.full_depth[uni] : y);
-                nodes.head[uni] = nodes.invert_elev[uni] + nodes.depth[uni];
-            }
-        };
-        updateNodeDepth(n1, y_in,  links.offset1[uj]);
-        updateNodeDepth(n2, y_out, links.offset2[uj]);
+        // Node depths are raised AFTER the per-node volume/overflow pass, in
+        // finishRouting — legacy runs setNewNodeState for every node before
+        // any setNewLinkState raises a depth (flowrout.c:203-205).
     }
 
+    // Legacy end-of-step passes: setNewNodeState for every node, then
+    // setNewLinkState's node-depth raises for every conduit.
+    finishRouting(ctx, structures, order, storage_updated_, y1_, y2_, dt);
+
     return (n_solved > 0) ? total_iters / n_solved : 1;
 }
 
+// ============================================================================
+// finishRouting — legacy flowrout_execute post-passes (KW/steady)
+// ============================================================================
+
+void finishRouting(SimulationContext& ctx,
+                   hydstruct::StructureSolver* structures,
+                   const std::vector& order,
+                   const std::vector& storage_updated,
+                   const std::vector& link_y1,
+                   const std::vector& link_y2,
+                   double dt) {
+    auto& nodes = ctx.nodes;
+    auto& links = ctx.links;
+    const int n_nodes = ctx.n_nodes();
+    const int n_links = ctx.n_links();
+    const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+
+    // Legacy Node.fullVolume for the non-storage overflow threshold:
+    // identically 0 (node_getVolume's default branch is 0 at init) EXCEPT a
+    // Type-1 pump wet well, whose fullVolume is the pump curve's largest
+    // volume (legacy pump_validate). The engine-internal full_volume
+    // convention (MIN_SURFAREA·fullDepth, for the DW surcharge test) must
+    // not leak in here — it would let a junction store water legacy sheds.
+    std::vector legacy_fv(static_cast(n_nodes), 0.0);
+    {
+        const double ucf_vol = ucf::Ucf[ucf::VOLUME][us];
+        for (int j = 0; j < n_links; ++j) {
+            auto uj = static_cast(j);
+            if (links.type[uj] != LinkType::PUMP) continue;
+            const int pr = ctx.link_subtypes.pump_row(j);
+            const int ci = (pr >= 0)
+                ? ctx.link_subtypes.pumps.curve[static_cast(pr)] : -1;
+            if (ci < 0 || ci >= static_cast(ctx.tables.tables.size())) continue;
+            const auto& tbl = ctx.tables.tables[static_cast(ci)];
+            if (tbl.type != TableType::CURVE_PUMP1) continue;
+            const int n1 = links.node1[uj];
+            if (n1 < 0 || nodes.type[static_cast(n1)] == NodeType::STORAGE)
+                continue;
+            double xmax = tbl.x_max;
+            if (xmax <= 0.0 && !tbl.x.empty())
+                xmax = *std::max_element(tbl.x.begin(), tbl.x.end());
+            auto un1 = static_cast(n1);
+            legacy_fv[un1] = std::max(legacy_fv[un1], xmax / ucf_vol);
+        }
+    }
+
+    // Outflow-link count per node (legacy toposort.c:75-91 — a link whose
+    // upstream node is an outfall counts toward its DOWNSTREAM node).
+    std::vector degree(static_cast(n_nodes), 0);
+    for (int j = 0; j < n_links; ++j) {
+        auto uj = static_cast(j);
+        int n = (links.direction[uj] < 0) ? links.node2[uj] : links.node1[uj];
+        if (n < 0 || n >= n_nodes) continue;
+        if (nodes.type[static_cast(n)] == NodeType::OUTFALL) {
+            n = (links.direction[uj] < 0) ? links.node1[uj] : links.node2[uj];
+            if (n < 0 || n >= n_nodes) continue;
+        }
+        degree[static_cast(n)]++;
+    }
+
+    // --- legacy setNewNodeState for every node (flowrout.c:558-599) ---
+    for (int i = 0; i < n_nodes; ++i) {
+        auto ui = static_cast(i);
+        if (nodes.type[ui] == NodeType::STORAGE) {
+            // Terminal storage (no outlet link) was never visited by the
+            // sorted-link loop; update it here (legacy flowrout.c:88-91).
+            if (ui >= storage_updated.size() || !storage_updated[ui])
+                updateStorageState(ctx, structures, order,
+                                   static_cast(order.size()), i, dt);
+            continue;
+        }
+
+        double net = nodes.inflow[ui] - nodes.outflow[ui] - nodes.losses[ui];
+        double v = nodes.old_volume[ui] + net * dt;
+        if (v < constants::FUDGE) v = 0.0;
+
+        nodes.overflow[ui] = 0.0;
+        const bool can_pond =
+            ctx.options.allow_ponding && nodes.ponded_area[ui] > 0.0;
+        if (v > legacy_fv[ui]) {
+            nodes.overflow[ui] =
+                (v - std::max(nodes.old_volume[ui], legacy_fv[ui])) / dt;
+            if (nodes.overflow[ui] < constants::FUDGE) nodes.overflow[ui] = 0.0;
+            if (!can_pond) v = legacy_fv[ui];
+        }
+        nodes.volume[ui] = v;
+
+        // legacy node_getDepth: 0 for anything but storage — the depth comes
+        // from the conduit-end raises below.
+        nodes.depth[ui] = 0.0;
+        nodes.head[ui]  = nodes.invert_elev[ui];
+    }
+
+    // --- legacy setNewLinkState → updateNodeDepth raises (flowrout.c:632) ---
+    auto raise = [&](int ni, double y) {
+        if (ni < 0 || ni >= n_nodes) return;
+        auto uni = static_cast(ni);
+        NodeType nt = nodes.type[uni];
+        if (nt == NodeType::STORAGE) return;
+        // A flooded non-outfall node WITH an outlet link reads full depth.
+        if (nt != NodeType::OUTFALL && degree[uni] > 0 &&
+            nodes.overflow[uni] > 0.0)
+            y = nodes.full_depth[uni];
+        if (nodes.depth[uni] < y) {
+            nodes.depth[uni] = (nodes.full_depth[uni] > 0.0 &&
+                                y > nodes.full_depth[uni])
+                                   ? nodes.full_depth[uni] : y;
+            nodes.head[uni] = nodes.invert_elev[uni] + nodes.depth[uni];
+        }
+    };
+    for (int j = 0; j < n_links; ++j) {
+        auto uj = static_cast(j);
+        if (links.type[uj] != LinkType::CONDUIT) {
+            // setNewLinkState starts every link at newDepth = newVolume = 0
+            // and fills them for conduits only: a non-conduit's depth that
+            // its head-discharge routine wrote during the step is not what
+            // the step reports (control-rules-test's orifice 3 under
+            // STEADY reported a growing depth where legacy reports 0).
+            links.depth[uj]  = 0.0;
+            links.volume[uj] = 0.0;
+            continue;
+        }
+        const double y1 = (uj < link_y1.size()) ? link_y1[uj] : 0.0;
+        const double y2 = (uj < link_y2.size()) ? link_y2[uj] : 0.0;
+        raise(links.node1[uj], y1 + links.offset1[uj]);
+        raise(links.node2[uj], y2 + links.offset2[uj]);
+    }
+}
+
+double capConduitLoss(SimulationContext& ctx, std::size_t ucr, double q) {
+    auto& CD = ctx.link_subtypes.conduits;
+    double evap  = CD.evap_loss_rate[ucr];
+    double seep  = CD.seep_loss_rate[ucr];
+    // G-X4: a gaining conduit (seep < 0) adds water; it does not compete for
+    // the inflow the cap rations, so only the losing part is scaled. The
+    // returned total stays the NET rate the solver subtracts.
+    double losing = evap + std::max(seep, 0.0);
+    if (losing > q) {
+        const double ratio = q / losing;
+        evap = evap * ratio;
+        if (seep > 0.0) seep = seep * ratio;
+        CD.evap_loss_rate[ucr] = evap;
+        CD.seep_loss_rate[ucr] = seep;
+    }
+    return evap + seep;
+}
+
 } // namespace kinwave
 } // namespace openswmm
diff --git a/src/engine/hydraulics/KinematicWave.hpp b/src/engine/hydraulics/KinematicWave.hpp
index 902a0a05b..b9cd2811b 100644
--- a/src/engine/hydraulics/KinematicWave.hpp
+++ b/src/engine/hydraulics/KinematicWave.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file KinematicWave.hpp
  * @brief Kinematic wave routing solver — batch-oriented design.
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_KINEMATIC_WAVE_HPP
@@ -35,8 +51,109 @@ namespace openswmm {
 
 struct SimulationContext;
 
+namespace hydstruct { class StructureSolver; }
+
 namespace kinwave {
 
+// ============================================================================
+// Tree-layout routing helpers — shared by KINWAVE and STEADY
+// ============================================================================
+//
+// Legacy keeps these in flowrout.c because Steady Flow and Kinematic Wave run
+// the SAME outer loop (flowrout_execute) over a topologically sorted link
+// array; only the per-conduit kernel differs. They live here so the KW loop
+// and Router::executeSteadyFlow share one implementation.
+
+/**
+ * @brief Flow into the upstream end of a link under Steady/Kin. Wave routing.
+ *
+ * @details PARITY flowrout.c:517 getLinkInflow:
+ * @code
+ *     if ( Link[j].type == CONDUIT || Link[j].type == PUMP ||
+ *          Node[n1].type == STORAGE )  q = link_getInflow(j);
+ *     else                             q = 0.0;
+ *     return node_getMaxOutflow(n1, q, dt);
+ * @endcode
+ * A non-conduit link therefore carries its own HEAD-DISCHARGE flow when it
+ * drains a storage unit, and NOTHING otherwise — never the upstream node's
+ * inflow. Passing the node inflow through gives every outlet of a node the
+ * full inflow, so N outlets manufacture N× the water.
+ *
+ * @param ctx         Simulation context.
+ * @param structures  Structure solver used to evaluate pump/orifice/weir/
+ *                    outlet discharge. May be null (structures then carry 0).
+ * @param j           Link index.
+ * @param dt          Routing timestep (seconds).
+ * @returns Link inflow (cfs), already limited by the upstream node's
+ *          available volume.
+ */
+double getLinkInflow(SimulationContext& ctx,
+                     hydstruct::StructureSolver* structures,
+                     int j, double dt);
+
+/**
+ * @brief Update a storage node's depth & volume by successive approximation.
+ *
+ * @details PARITY flowrout.c:537 updateStorageState + :611 getStorageOutflow.
+ * Called from inside the sorted-link loop, BEFORE routing the links that
+ * drain node `i`, so those links see the converged end-of-step depth. The
+ * outflow term is re-evaluated at each iterate because it depends on that
+ * depth — an orifice on a pond is an implicit relation, not a known rate.
+ *
+ * `order`/`pos` locate the node's outlet links: the topological sort emits a
+ * node's outgoing links contiguously, so the scan runs forward from `pos`
+ * until node1 changes (matching legacy's `if (Link[m].node1 != i) break`).
+ *
+ * @param ctx         Simulation context.
+ * @param structures  Structure solver (see getLinkInflow).
+ * @param order       Topologically sorted link order.
+ * @param pos         Current position in `order`.
+ * @param i           Storage node index.
+ * @param dt          Routing timestep (seconds).
+ */
+void updateStorageState(SimulationContext& ctx,
+                        hydstruct::StructureSolver* structures,
+                        const std::vector& order,
+                        int pos, int i, double dt);
+
+/**
+ * @brief End-of-step node/link state for tree-layout routing (KW/steady).
+ *
+ * @details PARITY flowrout.c:203-205 — after every link is routed, legacy
+ * runs setNewNodeState for every node (non-storage volume integration,
+ * overflow shedding, depth reset — a junction stores nothing under KW/SF)
+ * and then setNewLinkState's updateNodeDepth raises, which lift each
+ * conduit's end-node depths to the conduit end flow depths plus offsets,
+ * with a flooded non-outfall node pinned at its full depth. A terminal
+ * storage unit (no outlet link, so never visited by the sorted-link loop)
+ * gets its updateStorageState here, as legacy does (flowrout.c:88-91).
+ *
+ * @param ctx              Simulation context.
+ * @param structures       Structure solver (see getLinkInflow).
+ * @param order            Topologically sorted link order.
+ * @param storage_updated  Per-node flags set by the sorted-link loop.
+ * @param link_y1          Per-link flow depth at the upstream end (ft).
+ * @param link_y2          Per-link flow depth at the downstream end (ft).
+ * @param dt               Routing timestep (seconds).
+ */
+void finishRouting(SimulationContext& ctx,
+                   hydstruct::StructureSolver* structures,
+                   const std::vector& order,
+                   const std::vector& storage_updated,
+                   const std::vector& link_y1,
+                   const std::vector& link_y2,
+                   double dt);
+
+/**
+ * @brief legacy conduit_getLossRate's cap under SF / KW: the conduit's
+ *        evaporation + seepage rate (computed for the step by
+ *        Router::computeConduitLosses, per barrel) cannot exceed the CURRENT
+ *        solve's per-barrel inflow @p q; both components are scaled by
+ *        q / total and the capped rates are stored back for the mass
+ *        balance. Returns the (capped) total.
+ */
+double capConduitLoss(SimulationContext& ctx, std::size_t ucr, double q);
+
 // ============================================================================
 // Constants (matching legacy)
 // ============================================================================
@@ -79,11 +196,16 @@ class KWSolver {
      * @param dt   Timestep (seconds).
      * @returns Average number of Newton iterations across all conduits.
      */
-    int execute(SimulationContext& ctx, double dt);
+    int execute(SimulationContext& ctx, double dt,
+                hydstruct::StructureSolver* structures = nullptr);
 
     /// Topological link order (upstream → downstream)
     std::vector sorted_links_;
 
+    /// Per-node "already converged this step" flag for storage units
+    /// (legacy Node[i].updated). Reset at the top of every execute().
+    std::vector storage_updated_;
+
     /// Per-conduit Newton solve. Returns iteration count.
     int solveConduit(int idx, const XSectParams& xs,
                      double q_full, double a_full, double s_full,
@@ -103,6 +225,8 @@ class KWSolver {
     std::vector q_out_;     ///< Computed outflow (cfs)
     std::vector a_out_;     ///< Outlet area from Newton solve (ft2)
     std::vector sf_in_;     ///< Section factor at inlet
+    std::vector y1_;        ///< End-of-step upstream flow depth (ft)
+    std::vector y2_;        ///< End-of-step downstream flow depth (ft)
 
 private:
     int n_conduits_ = 0;
diff --git a/src/engine/hydraulics/Link.cpp b/src/engine/hydraulics/Link.cpp
index 72c032593..245e39f36 100644
--- a/src/engine/hydraulics/Link.cpp
+++ b/src/engine/hydraulics/Link.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Link.cpp
  * @brief Link hydraulics — numerically identical to legacy link.c.
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Link.hpp"
@@ -108,8 +124,14 @@ void computeConveyance(double roughness, double slope, double s_full,
 // Per-element: getDepthFromFlow
 // ============================================================================
 
-double getDepthFromFlow(const XSectParams& xs, double beta, double q) {
-    if (beta <= 0.0 || q <= 0.0) return 0.0;
+double getDepthFromFlow(const XSectParams& xs, double beta, double q,
+                        double q_max) {
+    if (beta <= 0.0) return 0.0;
+    // legacy link_getYnorm (link.c:800): cap the flow at the conduit's qMax
+    // BEFORE forming the section factor — the tabular shapes derive their
+    // inverse-lookup argument from the uncapped psi inside getAofS.
+    if (q_max >= 0.0 && q > q_max) q = q_max;
+    if (q <= 0.0) return 0.0;
 
     double s = q / beta;               // section factor needed
     double a = xsect::getAofS(xs, s);  // area from section factor
@@ -178,6 +200,7 @@ XSectParams buildXSectParams(
             xs.area_tbl          = td.area_tbl;
             xs.hrad_tbl          = td.hrad_tbl;
             xs.width_tbl         = td.width_tbl;
+            xs.area_lut          = &td.area_lut;
             xs.transect_tbl_size = transect::N_TRANSECT_TBL;
         }
     }
@@ -256,6 +279,7 @@ void applyTabulatedXSectParams(XSectParams& xs, const transect::TransectData& td
     xs.area_tbl          = td.area_tbl;
     xs.hrad_tbl          = td.hrad_tbl;
     xs.width_tbl         = td.width_tbl;
+    xs.area_lut          = &td.area_lut;
     xs.transect_tbl_size = transect::N_TRANSECT_TBL;
 }
 
diff --git a/src/engine/hydraulics/Link.hpp b/src/engine/hydraulics/Link.hpp
index 62d0e46eb..3efcf4797 100644
--- a/src/engine/hydraulics/Link.hpp
+++ b/src/engine/hydraulics/Link.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Link.hpp
  * @brief Link hydraulics — velocity, Froude, Manning conveyance, settings.
@@ -11,7 +27,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_LINK_HPP
@@ -86,9 +102,17 @@ void computeConveyance(double roughness, double slope, double s_full,
  * @param xs    Cross-section parameters.
  * @param beta  Manning conveyance factor.
  * @param q     Flow rate (ft3/s).
+ * @param q_max Conduit's flow at the maximum section factor; q is capped at it
+ *              first, as legacy link_getYnorm does (link.c:800). getAofS caps
+ *              the section factor at sMax anyway, but the tabular shapes take
+ *              their inverse-lookup argument from the UNcapped psi = s/sFull,
+ *              so an over-capacity q0 on an egg / horseshoe / gothic / catenary
+ *              / semi-elliptical / basket-handle / semi-circular conduit reads
+ *              the table past its end. Negative disables the cap.
  * @returns Normal depth (ft).
  */
-double getDepthFromFlow(const XSectParams& xs, double beta, double q);
+double getDepthFromFlow(const XSectParams& xs, double beta, double q,
+                        double q_max = -1.0);
 
 /**
  * @brief Compute the capacity fraction (depth / full depth for conduits,
@@ -143,6 +167,27 @@ XSectParams buildXSectParams(
  */
 int translateShape(XsectShape link_shape);
 
+/**
+ * @brief Sediment bump carried by a FILLED_CIRCULAR conduit's stored offsets.
+ *
+ * @details Once resolve_cross_references() has run, offset1 / offset2 of a
+ *          partly filled circular conduit hold the AUTHORED offset plus the
+ *          sediment depth y_bot (legacy link.c:1072-1077), so the hydraulics
+ *          see the sediment surface as the invert. Everything that speaks
+ *          authored offsets — the C API getters / setters, the edit ops that
+ *          write an authored 0 at a new junction, and the writers' inverse in
+ *          convert_internal_to_authored() — adds or removes this amount.
+ *          @p resolved is false in the BUILDING state, where the stores hold
+ *          authored values until swmm_finalize_model() resolves them once.
+ * @return y_bot (internal ft) for a resolved FILLED_CIRCULAR conduit, else 0.
+ */
+inline double filledCircularOffsetBump(const LinkData& links, std::size_t j, bool resolved) {
+    if (!resolved) return 0.0;
+    if (links.type[j] != LinkType::CONDUIT ||
+        links.xsect_shape[j] != XsectShape::FILLED_CIRCULAR) return 0.0;
+    return links.xsect_y_bot[j];
+}
+
 /**
  * @brief Derive the full-flow properties of a tabulated cross-section.
  *
diff --git a/src/engine/hydraulics/Node.cpp b/src/engine/hydraulics/Node.cpp
index 54ef99ab4..bd89d7fcb 100644
--- a/src/engine/hydraulics/Node.cpp
+++ b/src/engine/hydraulics/Node.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Node.cpp
  * @brief Node hydraulics — numerically identical to legacy node.c.
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Node.hpp"
@@ -335,8 +351,17 @@ double getPondedArea(const NodeData& nodes, int idx, double depth,
 double getMaxOutflow(const NodeData& nodes, int idx, double q, double dt) {
     auto ui = static_cast(idx);
 
-    double full_vol = constants::MIN_SURFAREA * nodes.full_depth[ui];
-    if (full_vol > 0.0) {
+    // Legacy node_getMaxOutflow (node.c:415-424) caps only nodes whose
+    // fullVolume is nonzero — storage units and Type-1 pump wet wells. A
+    // plain junction/outfall/divider has fullVolume identically 0 in legacy,
+    // so its conduits are NEVER capped, and the engine-internal full_volume
+    // convention (MIN_SURFAREA·fullDepth) must not leak into this cap.
+    // NodeData::rpt_full_volume IS legacy's Node.fullVolume, so test it
+    // directly — the old heuristic on full_volume capped a plain junction
+    // whose MIN_SURFAREA volume happened to clear the threshold, trimming a
+    // 1-ULP overflow contribution off its conduit's inflow
+    // (1710-2014-20year-r3's node 0 at routing step 6).
+    if (nodes.rpt_full_volume[ui] > 0.0) {
         double q_max = nodes.inflow[ui] + nodes.old_volume[ui] / dt;
         q = std::min(q, q_max);
     }
@@ -354,6 +379,26 @@ double getOverflow(double new_volume, double full_volume, double dt) {
     return 0.0;
 }
 
+double storeVolume(const NodeData& nodes, int idx, double depth, double volume) {
+    auto ui = static_cast(idx);
+    const double v = std::max(volume, 0.0);
+    // Storage: the curve volume. Outfall: a boundary, it stores nothing of
+    // its own (the routers never book it a volume), so the store is whatever
+    // was booked — 0 — rather than a MIN_SURFAREA bucket.
+    if (nodes.type[ui] == NodeType::STORAGE ||
+        nodes.type[ui] == NodeType::OUTFALL) return v;
+    const double fd = nodes.full_depth[ui];
+    if (!(fd > 0.0)) return v;
+    double store = nodes.full_volume[ui] * (std::min(depth, fd) / fd);
+    if (depth > fd) store += v;           // ponded water above the rim
+    return store;
+}
+
+double storeVolume(const NodeData& nodes, int idx) {
+    auto ui = static_cast(idx);
+    return storeVolume(nodes, idx, nodes.depth[ui], nodes.volume[ui]);
+}
+
 // ============================================================================
 // Batch: computeHeads
 // ============================================================================
diff --git a/src/engine/hydraulics/Node.hpp b/src/engine/hydraulics/Node.hpp
index 6990d541c..eecdda4b1 100644
--- a/src/engine/hydraulics/Node.hpp
+++ b/src/engine/hydraulics/Node.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Node.hpp
  * @brief Node hydraulics — volume/depth/head conversions, surface area, overflow.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_NODE_HPP
@@ -103,6 +119,34 @@ double getMaxOutflow(const NodeData& nodes, int idx, double q, double dt);
  */
 double getOverflow(double new_volume, double full_volume, double dt);
 
+/**
+ * @brief Water held at a node as a completely mixed transport STORE (ft3).
+ *
+ * @details The routers book nodes.volume in legacy's Node.newVolume
+ *          convention: a junction, outfall or divider holds nothing below
+ *          its rim (legacy fullVolume is 0 there, node.c node_getVolume) and
+ *          only the ponded water above it. A transport module that models a
+ *          node as a mixed store needs the water the dynamic wave's
+ *          continuity equation attributes to the node — its MIN_SURFAREA-
+ *          floored surface area times depth, which is full_volume scaled by
+ *          depth / full_depth (full_volume carries that area for a junction)
+ *          — plus the ponded water. A storage node's store is its curve
+ *          volume, i.e. nodes.volume itself, and an outfall — a boundary
+ *          the routers never book a volume for — stores nothing.
+ *
+ * @param nodes  SoA node data.
+ * @param idx    Node index.
+ * @returns Store volume (ft3, >= 0).
+ */
+double storeVolume(const NodeData& nodes, int idx);
+
+/**
+ * @brief storeVolume() for an explicit depth / booked-volume pair, so a
+ *        caller can evaluate the previous step's store from old_depth and
+ *        old_volume.
+ */
+double storeVolume(const NodeData& nodes, int idx, double depth, double volume);
+
 /**
  * @brief Compute depth from volume for a single node (inverse of getVolume).
  *
diff --git a/src/engine/hydraulics/Outfall.cpp b/src/engine/hydraulics/Outfall.cpp
index b39524c2a..3fd3a23a7 100644
--- a/src/engine/hydraulics/Outfall.cpp
+++ b/src/engine/hydraulics/Outfall.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Outfall.cpp
  * @brief Outfall boundary depths — matching legacy link_setOutfallDepth / outfall_setOutletDepth.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Outfall.hpp"
@@ -14,6 +30,7 @@
 #include "../core/UnitConversion.hpp"
 #include "XSectBatch.hpp"
 #include "Link.hpp"
+#include "Transect.hpp"
 
 #include 
 #include 
@@ -68,6 +85,26 @@ static XSectParams buildXSectParams(const SimulationContext& ctx, std::size_t uk
     xs.a_bot  = ctx.links.xsect_a_bot[uk];
     xs.s_bot  = ctx.links.xsect_s_bot[uk];
     xs.r_bot  = ctx.links.xsect_r_bot[uk];
+    // Tabulated shapes (IRREGULAR / CUSTOM / STREET) carry their A/R/W vs
+    // depth in per-link transect tables. Without them getAofS/getYofA/
+    // getYcrit return 0, so a NORMAL or FREE outfall on such a conduit sat
+    // at depth 0 while legacy computed a real normal/critical depth
+    // (customconduitshape D/S_Culvert1). Same wiring as DynamicWave's
+    // buildXSP.
+    const auto ls = ctx.links.xsect_shape[uk];
+    if (ls == XsectShape::IRREGULAR || ls == XsectShape::CUSTOM ||
+        ls == XsectShape::STREET_XSECT) {
+        const int ci = ctx.links.xsect_curve[uk];
+        if (ci >= 0 && static_cast(ci) < ctx.transect_tables.size()) {
+            const auto& td = ctx.transect_tables[static_cast(ci)];
+            xs.transect          = ci;
+            xs.area_tbl          = td.area_tbl;
+            xs.hrad_tbl          = td.hrad_tbl;
+            xs.width_tbl         = td.width_tbl;
+            xs.area_lut          = &td.area_lut;
+            xs.transect_tbl_size = transect::N_TRANSECT_TBL;
+        }
+    }
     return xs;
 }
 
@@ -83,6 +120,36 @@ static double getYnorm(const XSectParams& xs, double beta, double q_max,
     return y;
 }
 
+// Legacy Link.offset1 / offset2 for any link type: a conduit's two invert
+// offsets; a weir's / outlet's crest and an orifice's offset, which legacy
+// stores in BOTH offset fields (link.c:369-391) while this engine keeps the
+// weir/outlet crest in its side table and the orifice offset in offset1;
+// a pump has none.
+static double legacyOffset(const SimulationContext& ctx, std::size_t uk, bool downstream) {
+    // A regulator's downstream offset is legacy's un-raised crest (the
+    // resolver's WARNING-10 pass keeps it in offset2 before raising offset1
+    // / the side-table crest to the downstream invert).
+    if (downstream && ctx.links.type[uk] != LinkType::CONDUIT &&
+        ctx.links.type[uk] != LinkType::PUMP)
+        return ctx.links.offset2[uk];
+    switch (ctx.links.type[uk]) {
+        case LinkType::CONDUIT:
+            return downstream ? ctx.links.offset2[uk] : ctx.links.offset1[uk];
+        case LinkType::ORIFICE:
+            return ctx.links.offset1[uk];
+        case LinkType::WEIR: {
+            const int wr = ctx.link_subtypes.weir_row(static_cast(uk));
+            return (wr >= 0) ? ctx.link_subtypes.weirs.crest_height[static_cast(wr)] : 0.0;
+        }
+        case LinkType::OUTLET: {
+            const int olr = ctx.link_subtypes.outlet_row(static_cast(uk));
+            return (olr >= 0) ? ctx.link_subtypes.outlets.crest_height[static_cast(olr)] : 0.0;
+        }
+        default:
+            return 0.0;
+    }
+}
+
 void buildOutfallLinkMap(SimulationContext& ctx) {
     auto& nodes = ctx.nodes;
     auto& outs  = ctx.node_subtypes.outfalls;   // relational side-table (authoritative)
@@ -92,28 +159,30 @@ void buildOutfallLinkMap(SimulationContext& ctx) {
     outs.link_idx.assign(static_cast(outs.count()), -1);
     outs.link_offset.assign(static_cast(outs.count()), 0.0);
 
-    // Single pass over links; first matching conduit wins (matches the
-    // first-break legacy behaviour of the inner scan).
+    // Legacy link_setOutfallDepth (link.c:731) is called for EVERY link, of
+    // any type, in link order, and each call sets the depth of ONE end: the
+    // downstream node if it is an outfall, else the upstream node if it is.
+    // So a link with an outfall at both ends sets only its downstream one —
+    // lid-single-outfall-upstream's conduit runs FIXED outfall 1 (stage 1)
+    // to FIXED outfall 3, and legacy leaves outfall 1 at depth 0 — an
+    // outfall no link names is never set at all, and when several links
+    // name the same outfall the LAST one's call stands. The former map took
+    // the first CONDUIT at either end independently.
     for (int k = 0; k < n_links; ++k) {
         auto uk = static_cast(k);
-        if (ctx.links.type[uk] != LinkType::CONDUIT) continue;
-
         int n1 = ctx.links.node1[uk];
         int n2 = ctx.links.node2[uk];
-
+        int n = -1;
+        double z = 0.0;
         if (n2 >= 0 && nodes.type[static_cast(n2)] == NodeType::OUTFALL) {
-            const int r = ctx.node_subtypes.outfall_row(n2);
-            if (r >= 0 && outs.link_idx[static_cast(r)] < 0) {
-                outs.link_idx[static_cast(r)]    = k;
-                outs.link_offset[static_cast(r)] = ctx.links.offset2[uk];
-            }
-        }
-        if (n1 >= 0 && nodes.type[static_cast(n1)] == NodeType::OUTFALL) {
-            const int r = ctx.node_subtypes.outfall_row(n1);
-            if (r >= 0 && outs.link_idx[static_cast(r)] < 0) {
-                outs.link_idx[static_cast(r)]    = k;
-                outs.link_offset[static_cast(r)] = ctx.links.offset1[uk];
-            }
+            n = n2; z = legacyOffset(ctx, uk, true);
+        } else if (n1 >= 0 && nodes.type[static_cast(n1)] == NodeType::OUTFALL) {
+            n = n1; z = legacyOffset(ctx, uk, false);
+        } else continue;
+        const int r = ctx.node_subtypes.outfall_row(n);
+        if (r >= 0) {
+            outs.link_idx[static_cast(r)]    = k;
+            outs.link_offset[static_cast(r)] = z;
         }
     }
 }
@@ -149,11 +218,20 @@ inline OutfallStatic outfallStatic(const NodeData& nodes, const NodeSubtypes& su
 }
 }  // namespace
 
-void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
+void setAllOutfallDepths(SimulationContext& ctx, double dt_routing) {
     auto& nodes = ctx.nodes;
     int unit_sys = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
     double ucf_len = ucf::Ucf[ucf::LENGTH][unit_sys];
 
+    // legacy NewRoutingTime after routing_execute's advance (routing.c:
+    // NewRoutingTime + 1000.0 * routingStep, the same expression
+    // TimestepController::advance forms afterwards) — the stage boundaries
+    // are evaluated at the END of the step. routing-outfall-tidal read the
+    // calendar hour of the step's START, rounded to whole seconds.
+    const double new_routing_ms = ctx.elapsed_ms + 1000.0 * dt_routing;
+    constexpr double kMsecPerDay = 86400000.0;   // legacy MSECperDAY
+    const double elapsed_days = new_routing_ms / kMsecPerDay;
+
     // Legacy: iterates over LINKS and calls link_setOutfallDepth(j) for each.
     // Each link finds if either end is an outfall and computes yNorm + yCrit.
     // Then calls node_setOutletDepth(n, yNorm, yCrit, z).
@@ -167,27 +245,29 @@ void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
 
         double depth = 0.0;
 
-        // Cached outfall → conduit mapping (populated once at init).
-        // Falls back to a scan only if the cache is empty (e.g. in unit
-        // tests that skip Router::init).
+        // Cached outfall → link mapping (buildOutfallLinkMap, legacy
+        // link_setOutfallDepth's per-link choice of end). An outfall no link
+        // names is never set by legacy: leave its depth alone.
         const OutfallStatic ost = outfallStatic(nodes, ctx.node_subtypes, uj);
         int link_idx = ost.link_idx;
         double z = ost.link_offset;
-        if (link_idx < 0) {
+        if (link_idx < 0 && ctx.node_subtypes.outfall_row(j) < 0) {
+            // No side-table (unit tests that skip hydraulics init): the same
+            // per-link choice, scanned here.
             for (int k = 0; k < ctx.n_links(); ++k) {
                 auto uk = static_cast(k);
-                if (ctx.links.type[uk] != LinkType::CONDUIT) continue;
-                if (ctx.links.node2[uk] == j) {
-                    link_idx = k; z = ctx.links.offset2[uk]; break;
-                } else if (ctx.links.node1[uk] == j) {
-                    link_idx = k; z = ctx.links.offset1[uk]; break;
-                }
+                const int n2 = ctx.links.node2[uk], n1 = ctx.links.node1[uk];
+                if (n2 == j) { link_idx = k; z = legacyOffset(ctx, uk, true); }
+                else if (n2 >= 0 && nodes.type[static_cast(n2)] == NodeType::OUTFALL) continue;
+                else if (n1 == j) { link_idx = k; z = legacyOffset(ctx, uk, false); }
             }
         }
+        if (link_idx < 0) return;
 
-        // Compute normal and critical depths for the connecting conduit
+        // Normal and critical depths for the current flow — conduits only
+        // (legacy: yNorm = yCrit = 0 for any other link type).
         double yNorm = 0.0, yCrit = 0.0;
-        if (link_idx >= 0) {
+        if (ctx.links.type[static_cast(link_idx)] == LinkType::CONDUIT) {
             auto uk = static_cast(link_idx);
             const auto& CD = ctx.link_subtypes.conduits;
             const int cr = ctx.link_subtypes.conduit_row(link_idx);
@@ -249,10 +329,14 @@ void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
                 int curve_idx = static_cast(ost.param);
                 double stage = nodes.invert_elev[uj];
                 if (curve_idx >= 0 && curve_idx < static_cast(ctx.tables.tables.size())) {
-                    int h_tmp, m_tmp, s_tmp;
-                    datetime::decodeTime(current_time, h_tmp, m_tmp, s_tmp);
-                    double hour = static_cast(h_tmp) + m_tmp / 60.0 + s_tmp / 3600.0;
-                    stage = table_lookup_cursor(ctx.tables.tables[static_cast(curve_idx)], hour) / ucf_len;
+                    // legacy: table_getFirstEntry(&Curve[k], &x, &y);
+                    //         currentDate = NewRoutingTime / MSECperDAY;
+                    //         x += (currentDate - floor(currentDate)) * 24.0;
+                    //         stage = table_lookup(&Curve[k], x) / UCF(LENGTH);
+                    auto& curve = ctx.tables.tables[static_cast(curve_idx)];
+                    double x = curve.x.empty() ? 0.0 : curve.x[0];
+                    x += (elapsed_days - std::floor(elapsed_days)) * 24.0;
+                    stage = table_lookup_cursor(curve, x) / ucf_len;
                 }
                 yCrit = std::min(yCrit, yNorm);
                 if (yCrit + z + nodes.invert_elev[uj] < stage)
@@ -270,7 +354,10 @@ void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
                 int ts_idx = static_cast(ost.param);
                 double stage = nodes.invert_elev[uj];
                 if (ts_idx >= 0 && ts_idx < static_cast(ctx.tables.tables.size())) {
-                    stage = table_lookup_cursor(ctx.tables.tables[static_cast(ts_idx)], current_time) / ucf_len;
+                    // legacy: currentDate = StartDateTime + NewRoutingTime / MSECperDAY;
+                    //         stage = table_tseriesLookup(&Tseries[k], currentDate, TRUE) / UCF(LENGTH)
+                    const double date = ctx.options.start_date + elapsed_days;
+                    stage = table_lookup_cursor(ctx.tables.tables[static_cast(ts_idx)], date) / ucf_len;
                 }
                 yCrit = std::min(yCrit, yNorm);
                 if (yCrit + z + nodes.invert_elev[uj] < stage)
@@ -363,7 +450,10 @@ void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
         // is the sole consumer.
         //
         // See docs/1D_2D_COUPLING_GATE_REVIEW.md §6 (C6).
-        if (ctx.forcing.node_head_boundary_mode[uj] == ForcingMode::OVERRIDE) {
+        // (The forcing arrays are sized in init_modules; the init-time seeding
+        // call from SWMMEngine::initialize runs before that, with them empty.)
+        if (uj < ctx.forcing.node_head_boundary_mode.size() &&
+            ctx.forcing.node_head_boundary_mode[uj] == ForcingMode::OVERRIDE) {
             double prescribed_stage = ctx.forcing.node_head_boundary_value[uj];
             depth = std::max(prescribed_stage - z_inv, 0.0);
         }
@@ -378,8 +468,12 @@ void setAllOutfallDepths(SimulationContext& ctx, double current_time) {
     // results stay bit-for-bit identical. Falls back to a full node scan when
     // the side-tables are not built (e.g. unit tests that skip hydraulics init).
     // See docs/relational/RELATIONAL_NODE_REFACTOR_PLAN.md (Phase 2).
-    const auto& outs = ctx.node_subtypes.outfalls;
+    auto& outs = ctx.node_subtypes.outfalls;
     if (static_cast(ctx.node_subtypes.subtype_row.size()) == ctx.n_nodes()) {
+        // The map is built at Router::init; a caller that skipped it (unit
+        // tests driving the solver directly) gets it built here.
+        if (static_cast(outs.link_idx.size()) != outs.count())
+            buildOutfallLinkMap(ctx);
         for (int r = 0; r < outs.count(); ++r)
             process_outfall(outs.node_idx[static_cast(r)]);
     } else {
diff --git a/src/engine/hydraulics/Outfall.hpp b/src/engine/hydraulics/Outfall.hpp
index 8f30de9c6..8a4538e53 100644
--- a/src/engine/hydraulics/Outfall.hpp
+++ b/src/engine/hydraulics/Outfall.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Outfall.hpp
  * @brief Outfall boundary depth computation — free/normal/fixed/tidal/timeseries.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_OUTFALL_HPP
@@ -29,13 +45,22 @@ namespace outfall {
  *   - FREE: critical depth from downstream conduit
  *   - NORMAL: normal depth from downstream conduit
  *   - FIXED: specified water surface elevation
- *   - TIDAL: elevation from tidal curve at current time
- *   - TIMESERIES: elevation from timeseries at current time
+ *   - TIDAL: elevation from the tidal curve at the END of the routing step,
+ *     legacy node.c outfall_setOutletDepth: x = the curve's first x +
+ *     the fractional ELAPSED day (NewRoutingTime / MSECperDAY) * 24 — the
+ *     time of day counted from the simulation start, not the calendar hour
+ *   - TIMESERIES: elevation from the time series at StartDateTime +
+ *     NewRoutingTime / MSECperDAY (plain division, not getDateTime),
+ *     interpolated
+ *
+ * Legacy routing_execute advances NewRoutingTime before routeFlow, so the
+ * stage boundaries belong to the end of the step while the inflows and the
+ * control rules belong to its start (ctx.current_date, still the start here).
  *
- * @param ctx           Simulation context.
- * @param current_time  Current simulation time (decimal days).
+ * @param ctx         Simulation context (ctx.elapsed_ms = the step's start).
+ * @param dt_routing  The routing step being taken (s).
  */
-void setAllOutfallDepths(SimulationContext& ctx, double current_time);
+void setAllOutfallDepths(SimulationContext& ctx, double dt_routing);
 
 /**
  * @brief Precompute outfall → connecting-conduit index map.
diff --git a/src/engine/hydraulics/Roadway.cpp b/src/engine/hydraulics/Roadway.cpp
index 43d96fd6a..3430836b9 100644
--- a/src/engine/hydraulics/Roadway.cpp
+++ b/src/engine/hydraulics/Roadway.cpp
@@ -1,96 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Roadway.cpp
- * @brief Roadway weir overflow — numerically identical to legacy roadway.c.
+ * @brief Roadway weir overflow — legacy roadway.c, op for op.
  * @ingroup new_engine
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Roadway.hpp"
-#include 
 #include 
+#include 
 
 namespace openswmm {
 namespace roadway {
 
-// Discharge coefficients — low head/width ratio (h/w <= 0.15)
-static const double CR_LOW_PAVED[][2] = {
-    {0.00, 2.84}, {0.04, 2.87}, {0.08, 2.93}, {0.12, 3.03}, {0.15, 3.08}
-};
-static const double CR_LOW_GRAVEL[][2] = {
-    {0.00, 2.50}, {0.04, 2.54}, {0.08, 2.61}, {0.12, 2.70}, {0.15, 2.74}
-};
-// High ratio (h/w > 0.15)
-static const double CR_HIGH_PAVED[][2] = {
-    {0.15, 3.08}, {0.20, 3.20}, {0.30, 3.28}, {0.40, 3.30}
-};
-static const double CR_HIGH_GRAVEL[][2] = {
-    {0.15, 2.74}, {0.20, 2.81}, {0.30, 2.87}, {0.40, 2.90}
-};
-
-// Submergence correction factor
-static const double KT_PAVED[][2] = {
-    {0.00, 1.00}, {0.76, 1.00}, {0.80, 0.99}, {0.84, 0.98}, {0.88, 0.95},
-    {0.90, 0.91}, {0.92, 0.86}, {0.94, 0.78}, {0.96, 0.65}
-};
-static const double KT_GRAVEL[][2] = {
-    {0.00, 1.00}, {0.76, 1.00}, {0.80, 0.99}, {0.84, 0.97}, {0.88, 0.93},
-    {0.90, 0.88}, {0.92, 0.80}, {0.94, 0.68}, {0.96, 0.50}, {0.98, 0.25}
-};
-
-static double interpolate(const double table[][2], int n, double x) {
+// The discharge coefficients and submergence factors below were derived
+// from Figure 10 in "Bridge Waterways Analysis Model: Research Report",
+// FHWA/RD-86/108, July 1986 — legacy roadway.c tables verbatim.
+
+// Discharge coefficients for (head / road width) <= 0.15, keyed on the HEAD
+static const double Cr_Low_Paved[4][2] = {
+    {0.0, 2.85}, {0.2, 2.95}, {0.7, 3.03}, {4.0, 3.05}};
+
+static const double Cr_Low_Gravel[8][2] = {
+    {0.0, 2.5}, {0.5, 2.7},  {1.0, 2.8}, {1.5, 2.9}, {2.0, 2.98},
+    {2.5, 3.02}, {3.0, 3.03}, {4.0, 3.05}};
+
+// Discharge coefficients for (head / road width) > 0.15, keyed on the ratio
+static const double Cr_High_Paved[2][2] = {{0.15, 3.05}, {0.25, 3.10}};
+
+static const double Cr_High_Gravel[2][2] = {{0.15, 2.95}, {0.30, 3.10}};
+
+// Submergence factors, keyed on downstream / upstream head
+static const double Kt_Paved[9][2] = {
+    {0.8, 1.0}, {0.85, 0.98}, {0.90, 0.92}, {0.93, 0.85}, {0.95, 0.80},
+    {0.97, 0.70}, {0.98, 0.60}, {0.99, 0.50}, {1.00, 0.40}};
+
+static const double Kt_Gravel[12][2] = {
+    {0.75, 1.00}, {0.80, 0.985}, {0.83, 0.97}, {0.86, 0.93}, {0.89, 0.90},
+    {0.90, 0.87}, {0.92, 0.80},  {0.94, 0.70}, {0.96, 0.60}, {0.98, 0.50},
+    {0.99, 0.40}, {1.00, 0.24}};
+
+// legacy getY
+static double getY(double x, const double table[][2], const int n) {
     if (x <= table[0][0]) return table[0][1];
-    if (x >= table[n-1][0]) return table[n-1][1];
-    for (int i = 1; i < n; ++i) {
+    if (x >= table[n - 1][0]) return table[n - 1][1];
+    for (int i = 1; i < n; i++) {
         if (x <= table[i][0]) {
-            double frac = (x - table[i-1][0]) / (table[i][0] - table[i-1][0]);
-            return table[i-1][1] + frac * (table[i][1] - table[i-1][1]);
+            const double x1 = table[i - 1][0];
+            const double dx = table[i][0] - x1;
+            const double y1 = table[i - 1][1];
+            const double dy = table[i][1] - y1;
+            return y1 + (x - x1) * dy / dx;
         }
     }
-    return table[n-1][1];
+    return table[n - 1][1];
 }
 
-double getDischargeCoeff(double hw_ratio, SurfaceType surface) {
-    if (hw_ratio <= 0.15) {
-        return (surface == SurfaceType::PAVED)
-            ? interpolate(CR_LOW_PAVED, 5, hw_ratio)
-            : interpolate(CR_LOW_GRAVEL, 5, hw_ratio);
+// legacy getCd
+static double getCd(double hWr, double ht, double roadWidth, int roadSurf) {
+    double kT = 1.0;
+    double cR;
+    if (hWr <= 0.0) return 0.0;
+    const double hL = hWr / roadWidth;
+    if (hL <= 0.15) {
+        if (roadSurf == SURFACE_PAVED) cR = getY(hWr, Cr_Low_Paved, 4);
+        else                           cR = getY(hWr, Cr_Low_Gravel, 8);
     } else {
-        return (surface == SurfaceType::PAVED)
-            ? interpolate(CR_HIGH_PAVED, 4, hw_ratio)
-            : interpolate(CR_HIGH_GRAVEL, 4, hw_ratio);
+        if (roadSurf == SURFACE_PAVED) cR = getY(hL, Cr_High_Paved, 2);
+        else                           cR = getY(hL, Cr_High_Gravel, 2);
     }
+    if (ht > 0.0) {
+        const double htH = ht / hWr;
+        if (roadSurf == SURFACE_PAVED) kT = getY(htH, Kt_Paved, 9);
+        else                           kT = getY(htH, Kt_Gravel, 12);
+    }
+    return cR * kT;
 }
 
-double getSubmergenceFactor(double ht_ratio, SurfaceType surface) {
-    if (ht_ratio <= 0.0) return 1.0;
-    return (surface == SurfaceType::PAVED)
-        ? interpolate(KT_PAVED, 9, ht_ratio)
-        : interpolate(KT_GRAVEL, 10, ht_ratio);
-}
-
-double getFlow(double head_up, double head_down,
-               double road_width, double road_length,
-               SurfaceType surface, double& dqdh) {
+double getInflow(double dir, double h_road, double h1, double h2,
+                 double cd_user, bool si, double road_width, int road_surf,
+                 double length, double& dqdh, double& depth) {
+    constexpr double FUDGE = 0.0001;
+    double q = 0.0;
     dqdh = 0.0;
-    if (head_up <= 0.0 || road_length <= 0.0 || road_width <= 0.0) return 0.0;
 
-    double hw_ratio = head_up / road_width;
-    double Cr = getDischargeCoeff(hw_ratio, surface);
+    // --- user-supplied discharge coeff.
+    double cD = cd_user;
+    if (si) cD = cD / 0.552;
 
-    double Kt = 1.0;
-    if (head_down > 0.0) {
-        double ht_ratio = head_down / head_up;
-        Kt = getSubmergenceFactor(ht_ratio, surface);
-    }
+    // --- check if there's enough info to use a variable cD value
+    const bool useVariableCd = (road_width > 0.0 && road_surf >= 1);
 
-    double Cd = Cr * Kt;
-    double q = Cd * road_length * head_up * std::sqrt(head_up);
-    dqdh = 1.5 * q / head_up;
+    // --- upstream and downstream heads
+    const double hWr = h1 - h_road;
+    const double ht  = h2 - h_road;
+    if (hWr > FUDGE) {
+        // --- get discharge coeff. as function of heads
+        if (useVariableCd) cD = getCd(hWr, ht, road_width, road_surf);
+
+        // --- weir eqn. for discharge across roadway
+        q = cD * length * std::pow(hWr, 1.5);
+        dqdh = 1.5 * q / hWr;
+    }
 
-    return q;
+    depth = std::max(h1 - h_road, 0.0);
+    return dir * q;
 }
 
 } // namespace roadway
diff --git a/src/engine/hydraulics/Roadway.hpp b/src/engine/hydraulics/Roadway.hpp
index 4305f232b..53954d94b 100644
--- a/src/engine/hydraulics/Roadway.hpp
+++ b/src/engine/hydraulics/Roadway.hpp
@@ -1,17 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Roadway.hpp
- * @brief Roadway weir overflow — FHWA HDS-5.
+ * @brief Roadway weir overflow — FHWA HDS-5 (legacy roadway.c, op for op).
  *
- * @details Q = Cd * L * hWr^1.5 where Cd depends on head/width ratio
- *          and road surface type (paved/gravel). Submergence correction
- *          factor Kt applied when tailwater is significant.
+ * @details Q = Cd * L * hWr^1.5 over the road crest. With a road width and
+ *          surface the coefficient is the HDS-5 curve value: Cr from the
+ *          HEAD (ft) when head / width <= 0.15, from the ratio above that,
+ *          times the submergence factor Kt(ht / hWr); without them the
+ *          user's Cd (SI decks: / 0.552).
  *
  * @note Legacy reference: src/legacy/engine/roadway.c
  * @ingroup new_engine
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ROADWAY_HPP
@@ -21,43 +39,32 @@ namespace openswmm {
 
 namespace roadway {
 
-enum class SurfaceType : int {
-    PAVED  = 0,
-    GRAVEL = 1
-};
-
-/**
- * @brief Compute roadway weir overflow.
- *
- * @param head_up    Upstream head above road crest (ft).
- * @param head_down  Downstream head above road crest (ft).
- * @param road_width Road width (ft).
- * @param road_length Crest length perpendicular to flow (ft).
- * @param surface    Road surface type.
- * @param[out] dqdh  Derivative dQ/dH.
- * @returns Overflow rate (cfs).
- */
-double getFlow(double head_up, double head_down,
-               double road_width, double road_length,
-               SurfaceType surface, double& dqdh);
-
-/**
- * @brief Get discharge coefficient Cr from head/width ratio.
- *
- * @param hw_ratio  head / road_width.
- * @param surface   Paved or gravel.
- * @returns Discharge coefficient.
- */
-double getDischargeCoeff(double hw_ratio, SurfaceType surface);
+/// legacy roadway.c RoadSurface: 0 = none (user Cd), 1 = PAVED, 2 = GRAVEL.
+constexpr int SURFACE_NONE   = 0;
+constexpr int SURFACE_PAVED  = 1;
+constexpr int SURFACE_GRAVEL = 2;
 
 /**
- * @brief Get submergence correction factor Kt.
+ * @brief legacy roadway_getInflow: flow across a roadway weir.
  *
- * @param ht_ratio  head_down / head_up.
- * @param surface   Paved or gravel.
- * @returns Submergence factor (0-1).
+ * @param dir         Flow direction (+1 or -1); the heads are already
+ *                    swapped for reverse flow.
+ * @param h_road      Road (crest) elevation (ft).
+ * @param h1          Upstream head (ft).
+ * @param h2          Downstream head (ft).
+ * @param cd_user     The weir's discharge coefficient as written (Cd for
+ *                    cfs; divided by 0.552 on an SI project).
+ * @param si          True on an SI project.
+ * @param road_width  Road width across the flow (ft); 0 = unknown.
+ * @param road_surf   SURFACE_PAVED / SURFACE_GRAVEL / SURFACE_NONE.
+ * @param length      Weir length (the section's wMax, ft).
+ * @param[out] dqdh   dQ/dH (ft2/s), 0 when dry.
+ * @param[out] depth  Link depth: max(h1 - h_road, 0).
+ * @returns dir * q (cfs).
  */
-double getSubmergenceFactor(double ht_ratio, SurfaceType surface);
+double getInflow(double dir, double h_road, double h1, double h2,
+                 double cd_user, bool si, double road_width, int road_surf,
+                 double length, double& dqdh, double& depth);
 
 } // namespace roadway
 } // namespace openswmm
diff --git a/src/engine/hydraulics/Routing.cpp b/src/engine/hydraulics/Routing.cpp
index d543ff9f6..5a1358345 100644
--- a/src/engine/hydraulics/Routing.cpp
+++ b/src/engine/hydraulics/Routing.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Routing.cpp
  * @brief Top-level routing dispatcher.
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Routing.hpp"
@@ -17,11 +33,14 @@
 #include "../core/ErrorCodes.hpp"
 #include "../core/UnitConversion.hpp"
 #include "Outfall.hpp"
+#include "AquiferLinkExchange.hpp"   // G-X4
 #include "Divider.hpp"
+#include "ForceMain.hpp"
 #include "Node.hpp"
 #include "Link.hpp"
 #include "TopoSort.hpp"
 #include "../core/SimulationContext.hpp"
+#include "../input/PostParseResolver.hpp"
 
 #include 
 #include 
@@ -35,10 +54,11 @@ namespace openswmm {
 // because the function is tiny and tightly coupled to the SoA layout.
 // ============================================================================
 
-static XSectParams buildXSP(const LinkData& links, std::size_t uk) {
+static XSectParams buildXSP(const SimulationContext& ctx, std::size_t uk) {
+    const LinkData& links = ctx.links;
     XSectParams xs{};
     auto ls = links.xsect_shape[uk];
-    xs.type   = (ls == XsectShape::DUMMY) ? 0 : static_cast(ls) + 1;
+    xs.type   = link::translateShape(ls);
     xs.y_full = links.xsect_y_full[uk];
     xs.a_full = links.xsect_a_full[uk];
     xs.w_max  = links.xsect_w_max[uk];
@@ -49,100 +69,110 @@ static XSectParams buildXSP(const LinkData& links, std::size_t uk) {
     xs.a_bot  = links.xsect_a_bot[uk];
     xs.s_bot  = links.xsect_s_bot[uk];
     xs.r_bot  = links.xsect_r_bot[uk];
+    // Tabulated shapes (IRREGULAR / CUSTOM / STREET) carry their A/R/W vs depth
+    // in per-link transect tables; without them every scalar getter returns 0.
+    // Under KW that made getAofS's Newton walk its whole bracket and report the
+    // conduit's FULL inlet area for a trickle of inflow (1710-2014-20year-r3's
+    // transect channels), so the upstream node depth came out full instead of
+    // ~2 mm. Same block as DynamicWave.cpp::buildXSP.
+    if (ls == XsectShape::IRREGULAR || ls == XsectShape::CUSTOM ||
+        ls == XsectShape::STREET_XSECT) {
+        const int ci = links.xsect_curve[uk];
+        if (ci >= 0 && static_cast(ci) < ctx.transect_tables.size()) {
+            const auto& td = ctx.transect_tables[static_cast(ci)];
+            xs.transect          = ci;
+            xs.area_tbl          = td.area_tbl;
+            xs.hrad_tbl          = td.hrad_tbl;
+            xs.width_tbl         = td.width_tbl;
+            xs.area_lut          = &td.area_lut;
+            xs.transect_tbl_size = transect::N_TRANSECT_TBL;
+        }
+    }
     return xs;
 }
 
-// ============================================================================
-// Init
-// ============================================================================
-
-void Router::init(SimulationContext& ctx, RouteModel model) {
-    model_ = model;
-
-    int n_links = ctx.n_links();
-    int n_nodes = ctx.n_nodes();
-
-    // Build XSectParams array from ctx.links SoA fields
-    // NOTE: LinkData::XsectShape and XSectBatch::XSectShape have different
-    //       orderings. LinkData follows legacy enums.h (CIRCULAR=0), while
-    //       XSectBatch prepends DUMMY=0 and reorders some shapes.
-    //       Use explicit mapping to avoid misalignment.
-    auto translateShape = [](XsectShape link_shape) -> int {
-        switch (link_shape) {
-            case XsectShape::CIRCULAR:        return static_cast(XSectShape::CIRCULAR);
-            case XsectShape::FILLED_CIRCULAR: return static_cast(XSectShape::FILLED_CIRCULAR);
-            case XsectShape::RECT_CLOSED:     return static_cast(XSectShape::RECT_CLOSED);
-            case XsectShape::RECT_OPEN:       return static_cast(XSectShape::RECT_OPEN);
-            case XsectShape::TRAPEZOIDAL:     return static_cast(XSectShape::TRAPEZOIDAL);
-            case XsectShape::TRIANGULAR:      return static_cast(XSectShape::TRIANGULAR);
-            case XsectShape::PARABOLIC:       return static_cast(XSectShape::PARABOLIC);
-            case XsectShape::POWER:           return static_cast(XSectShape::POWERFUNC);
-            case XsectShape::MODBASKETHANDLE: return static_cast(XSectShape::MOD_BASKET);
-            case XsectShape::EGGSHAPED:       return static_cast(XSectShape::EGGSHAPED);
-            case XsectShape::HORSESHOE:       return static_cast(XSectShape::HORSESHOE);
-            case XsectShape::GOTHIC:          return static_cast(XSectShape::GOTHIC);
-            case XsectShape::CATENARY:        return static_cast(XSectShape::CATENARY);
-            case XsectShape::SEMIELLIPTICAL:  return static_cast(XSectShape::SEMIELLIPTICAL);
-            case XsectShape::BASKETHANDLE:    return static_cast(XSectShape::BASKETHANDLE);
-            case XsectShape::SEMICIRCULAR:    return static_cast(XSectShape::SEMICIRCULAR);
-            case XsectShape::RECT_TRIANG:     return static_cast(XSectShape::RECT_TRIANG);
-            case XsectShape::RECT_ROUND:      return static_cast(XSectShape::RECT_ROUND);
-            case XsectShape::HORIZ_ELLIPSE:   return static_cast(XSectShape::HORIZ_ELLIPSE);
-            case XsectShape::VERT_ELLIPSE:    return static_cast(XSectShape::VERT_ELLIPSE);
-            case XsectShape::ARCH:            return static_cast(XSectShape::ARCH);
-            case XsectShape::IRREGULAR:       return static_cast(XSectShape::IRREGULAR);
-            case XsectShape::CUSTOM:          return static_cast(XSectShape::CUSTOM);
-            case XsectShape::FORCE_MAIN:      return static_cast(XSectShape::FORCE_MAIN);
-            case XsectShape::STREET_XSECT:    return static_cast(XSectShape::STREET_XSECT);
-            case XsectShape::DUMMY:           return static_cast(XSectShape::DUMMY);
-            default:                          return static_cast(XSectShape::DUMMY);
-        }
-    };
 
-    std::vector xsect_params(static_cast(n_links));
-    for (int j = 0; j < n_links; ++j) {
-        auto uj = static_cast(j);
-        if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+// Per-node diversion-link index for toposort::sortLinks (legacy adjustAdjList):
+// the link a 2-outlet DIVIDER diverts into, -1 for every other node.
+static std::vector buildDivertLinks(const SimulationContext& ctx) {
+    std::vector divert(static_cast(ctx.n_nodes()), -1);
+    const auto& divs = ctx.node_subtypes.dividers;
+    for (int i = 0; i < ctx.n_nodes(); ++i) {
+        if (ctx.nodes.type[static_cast(i)] != NodeType::DIVIDER) continue;
+        const int r = ctx.node_subtypes.divider_row(i);
+        if (r < 0) continue;
+        divert[static_cast(i)] = divs.link[static_cast(r)];
+    }
+    return divert;
+}
 
-        auto& xs = xsect_params[uj];
-        xs.type   = translateShape(ctx.links.xsect_shape[uj]);
-        // Cache translated shape code to avoid per-timestep switch dispatch
-        ctx.links.xsect_batch_shape[uj] = xs.type;
-        xs.y_full = ctx.links.xsect_y_full[uj];
-        xs.a_full = ctx.links.xsect_a_full[uj];
-        xs.w_max  = ctx.links.xsect_w_max[uj];
-        xs.r_full = ctx.links.xsect_r_full[uj];
-        xs.s_full = ctx.links.xsect_s_full[uj];
+// ============================================================================
+// applyConduitLengthening — legacy conduit_validate's Courant lengthening and
+// the conveyance (beta / roughFactor / qFull / qMax) re-derivation that goes
+// with it.
+//
+// Legacy does BOTH inside conduit_validate, i.e. during project validation —
+// before link_initState computes each q0 conduit's normal depth and before
+// flowrout_init seeds the node depths from it. Living only in Router::init
+// (which runs after those initial-state loops) left every lengthened conduit's
+// q0 normal depth computed from the UNLENGTHENED beta. The lengthening cancels
+// algebraically — beta = PHI*sqrt(S/f)/(n/sqrt(f)) = PHI*sqrt(S)/n — but not
+// in IEEE-754: the two extra roundings move beta one ULP, which moved the
+// seeded node depths and split 405-h-h-elements at the very first routing step.
+// SWMMEngine calls this before the initial-state loops; Router::init calls it
+// again. It is idempotent: every input (length, slope, the effective n) is a
+// stored, unmodified quantity.
+// ============================================================================
 
-        // Shape-specific parameters for batch kernels
-        xs.y_bot  = ctx.links.xsect_y_bot[uj];   // bottom width (TRAP), bottom depth (FILLED_CIRC)
-        xs.a_bot  = ctx.links.xsect_a_bot[uj];   // bottom area
-        xs.s_bot  = ctx.links.xsect_s_bot[uj];   // side slope (TRAP), C-factor (FORCE_MAIN)
-        xs.r_bot  = ctx.links.xsect_r_bot[uj];   // side slope2, wetted perimeter
+void applyConduitLengthening(SimulationContext& ctx, RouteModel model) {
+    const int n_links = ctx.n_links();
 
-        // Compute full-depth properties if not already set
-        if (xs.a_full == 0.0 && xs.y_full > 0.0) {
-            double p[4] = {xs.y_full, xs.w_max, 0, 0};
-            xsect::setParams(xs, xs.type, p, 1.0);
-            // Write back computed values to link SoA
-            ctx.links.xsect_a_full[uj] = xs.a_full;
-            ctx.links.xsect_r_full[uj] = xs.r_full;
-            ctx.links.xsect_s_full[uj] = xs.s_full;
-            ctx.links.xsect_w_max[uj]  = xs.w_max;
+    // Refresh the routing length (legacy conduit_getLength) before anything
+    // reads it. It differs from the authored [CONDUITS] length only for an
+    // IRREGULAR section, whose authored number is the MAIN CHANNEL's while
+    // the routing length is the flood plain's — see conduit_true_length.
+    // Filled here rather than at parse so an .inp load, a GeoPackage load
+    // and a C-API edit all reach a run with it current.
+    {
+        auto& CD = ctx.link_subtypes.conduits;
+        for (int j = 0; j < n_links; ++j) {
+            if (ctx.links.type[static_cast(j)] != LinkType::CONDUIT)
+                continue;
+            const int cr = ctx.link_subtypes.conduit_row(j);
+            if (cr < 0) continue;
+            CD.true_length[static_cast(cr)] =
+                openswmm::input::conduit_true_length(ctx, j);
         }
     }
 
+    // The Courant lengthening factor per conduit row (legacy's local
+    // `lengthFactor`), carried from the lengthening pass to the conveyance
+    // re-derivation below. It cannot be recovered as modLength / length:
+    // legacy forms modLength from the ROUTING length (link.c:1118
+    // `modLength = lengthFactor * conduit_getLength(j)`) and leaves it at
+    // the AUTHORED length when the factor is 1, so on an IRREGULAR conduit
+    // the two lengths are not the same number.
+    std::vector courant_factor(
+        static_cast(ctx.link_subtypes.conduits.count()), 1.0);
+
     // Compute modified conduit lengths for CFL stability
     // (matching legacy link.c conduit_getLengthFactor / conduit_validate:
-    //  lengthening is only applied when LENGTHENING_STEP > 0 in OPTIONS)
+    //  lengthening is only applied when LENGTHENING_STEP > 0 in OPTIONS
+    //  AND the routing is dynamic wave — `RouteModel == DW &&
+    //  LengtheningStep > 0.0` (link.c:1109); under kinematic wave or steady
+    //  flow modLength stays the conduit's length, and link_getLength reads
+    //  that for the continuity solve and the volume. FV shares the dynamic
+    //  wave's mesh floor.) small-linear-si-unit-model (LPS, KW,
+    //  LENGTHENING_STEP 5) routed its 7.9 m outfall pipe as 19.8 m.
     {
         using constants::PHI;
         using constants::GRAVITY;
-        double route_step = ctx.options.routing_step;
+        double route_step = ctx.options.linkValidateRoutingStep();  // legacy: the authored RouteStep
         double lengthening_step = ctx.options.lengthening_step;
+        const bool dw_like = (model == RouteModel::DYNWAVE || model == RouteModel::FV);
 
         auto& CD = ctx.link_subtypes.conduits;  // Phase 6 Stage B: mod_length authority
-        if (lengthening_step <= 0.0) {
+        if (lengthening_step <= 0.0 || !dw_like) {
             // Legacy: skip Courant lengthening when LENGTHENING_STEP not set
             for (int r = 0; r < CD.count(); ++r) {
                 const auto ur = static_cast(r);
@@ -157,27 +187,33 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
                 const int cr = ctx.link_subtypes.conduit_row(j);  // ≥0 (conduit)
                 const auto ucr = static_cast(cr);
 
-                double L = CD.length[ucr];
+                // legacy conduit_getLengthFactor divides the Courant length
+                // by conduit_getLength(j), and conduit_validate then forms
+                // modLength from the same routing length.
+                double L = CD.true_length[ucr];
                 if (L <= 0.0) {
-                    CD.mod_length[ucr] = L;
+                    CD.mod_length[ucr] = CD.length[ucr];
                     continue;
                 }
 
                 double yFull = ctx.links.xsect_y_full[uj];
                 double aFull = ctx.links.xsect_a_full[uj];
                 double sFull = ctx.links.xsect_s_full[uj];
-                double n_rough = CD.roughness[ucr];
+                // PARITY link.c:1085-1105: the roughness that feeds
+                // conduit_getLengthFactor is the EFFECTIVE n — a transect
+                // conduit's channel n (times its meander factor), a force
+                // main's equivalent n — not the [CONDUITS] value.
+                double n_rough = openswmm::input::conduit_manning_n(ctx, j);
                 double slope_abs = std::fabs(CD.slope[ucr]);
 
                 // For open channels, use hydraulic depth (aFull / top-width)
                 // rather than geometric full depth for the wave-speed term.
                 // Matches legacy link.c:1241-1243:
                 //   if (xsect_isOpen(type)) yFull = aFull / getWofY(yFull)
-                bool is_open = (ctx.links.xsect_shape[uj] == XsectShape::TRAPEZOIDAL ||
-                                ctx.links.xsect_shape[uj] == XsectShape::RECT_OPEN   ||
-                                ctx.links.xsect_shape[uj] == XsectShape::TRIANGULAR  ||
-                                ctx.links.xsect_shape[uj] == XsectShape::PARABOLIC);
-                if (is_open) {
+                // xsect_isOpen is Amax == 1 (POWERFUNC, IRREGULAR and STREET
+                // included), and W(yFull) is wMax for every open shape — a
+                // transect's wMax IS its top-of-table width (transect.c:299).
+                if (xsect::isOpen(ctx.links.xsect_batch_shape[uj])) {
                     double wFull = ctx.links.xsect_w_max[uj];
                     if (wFull > 0.0) yFull = aFull / wFull;
                 }
@@ -186,9 +222,14 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
                     double vFull = PHI / n_rough * sFull * std::sqrt(slope_abs) / aFull;
                     double ratio = (std::sqrt(GRAVITY * yFull) + vFull) * tStep / L;
                     double factor = (ratio > 1.0) ? ratio : 1.0;
-                    CD.mod_length[ucr] = factor * L;
+                    courant_factor[ucr] = factor;
+                    // legacy conduit_validate only assigns modLength when the
+                    // factor differs from 1 — an unlengthened conduit keeps the
+                    // AUTHORED length link_setParams gave it (link.c:348).
+                    CD.mod_length[ucr] =
+                        (factor != 1.0) ? factor * L : CD.length[ucr];
                 } else {
-                    CD.mod_length[ucr] = L;
+                    CD.mod_length[ucr] = CD.length[ucr];
                 }
             }
         }
@@ -207,13 +248,18 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
             const int cr = ctx.link_subtypes.conduit_row(j);
             const auto ucr = static_cast(cr);
 
-            double L = CD.length[ucr];
-            double modL = CD.mod_length[ucr];
-            if (L <= 0.0 || modL <= L) continue;  // not lengthened
+            // legacy conduit_validate keys this on its `lengthFactor` local,
+            // not on a length ratio (see courant_factor above).
+            double factor = courant_factor[ucr];
+            if (factor == 1.0) continue;  // not lengthened
 
-            double factor = modL / L;
             double slope_abs = std::fabs(CD.slope[ucr]) / factor;
-            double roughness = CD.roughness[ucr] / std::sqrt(factor);
+            // PARITY link.c:1113-1116: the lengthening divides the EFFECTIVE
+            // n (see conduit_manning_n) by sqrt(factor). Dividing the stored
+            // [CONDUITS] value here silently dropped a transect conduit's
+            // channel n for every lengthened conduit (50-transects: the two
+            // short reaches routed with n = 1.0 instead of 0.1).
+            double roughness = openswmm::input::conduit_manning_n(ctx, j) / std::sqrt(factor);
 
             // Update conveyance with adjusted slope and roughness
             double beta = PHI * std::sqrt(slope_abs) / roughness;
@@ -222,9 +268,107 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
             CD.rough_factor[ucr] = GRAVITY * ((roughness / PHI) * (roughness / PHI));
             CD.q_full[ucr]       = ctx.links.xsect_s_full[uj] * beta;
             CD.q_max[ucr]        = ctx.links.xsect_s_max[uj] * beta;
+
+            // PARITY link.c:1127-1131: a lengthened FORCE MAIN's pressurized
+            // friction factor (xsect.sBot = forcemain_getRoughFactor(j,
+            // lengthFactor)) compensates the artificial lengthening —
+            // H-W: G / (1.318·C·lf^0.54)^1.852, D-W: 1/(8·lf). The resolver
+            // formed it before the lengthening (factor 1); the 7 ft force
+            // mains of 375-h-h-elements (LENGTHENING_STEP 10) carried 14x
+            // legacy's friction on their first full-pipe step.
+            if (ctx.links.xsect_shape[uj] == XsectShape::FORCE_MAIN &&
+                (model == RouteModel::DYNWAVE || model == RouteModel::FV)) {
+                auto fm = static_cast(ctx.options.force_main_eqn);
+                ctx.links.xsect_s_bot[uj] =
+                    forcemain::getRoughFactor(fm, ctx.links.xsect_r_bot[uj], factor);
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Init
+// ============================================================================
+
+void Router::init(SimulationContext& ctx, RouteModel model) {
+    model_ = model;
+
+    int n_links = ctx.n_links();
+    int n_nodes = ctx.n_nodes();
+
+    // Build XSectParams array from ctx.links SoA fields
+    // NOTE: LinkData::XsectShape and XSectBatch::XSectShape have different
+    //       orderings. LinkData follows legacy enums.h (CIRCULAR=0), while
+    //       XSectBatch prepends DUMMY=0 and reorders some shapes.
+    //       Use explicit mapping to avoid misalignment.
+    auto translateShape = [](XsectShape link_shape) -> int {
+        switch (link_shape) {
+            case XsectShape::CIRCULAR:        return static_cast(XSectShape::CIRCULAR);
+            case XsectShape::FILLED_CIRCULAR: return static_cast(XSectShape::FILLED_CIRCULAR);
+            case XsectShape::RECT_CLOSED:     return static_cast(XSectShape::RECT_CLOSED);
+            case XsectShape::RECT_OPEN:       return static_cast(XSectShape::RECT_OPEN);
+            case XsectShape::TRAPEZOIDAL:     return static_cast(XSectShape::TRAPEZOIDAL);
+            case XsectShape::TRIANGULAR:      return static_cast(XSectShape::TRIANGULAR);
+            case XsectShape::PARABOLIC:       return static_cast(XSectShape::PARABOLIC);
+            case XsectShape::POWER:           return static_cast(XSectShape::POWERFUNC);
+            case XsectShape::MODBASKETHANDLE: return static_cast(XSectShape::MOD_BASKET);
+            case XsectShape::EGGSHAPED:       return static_cast(XSectShape::EGGSHAPED);
+            case XsectShape::HORSESHOE:       return static_cast(XSectShape::HORSESHOE);
+            case XsectShape::GOTHIC:          return static_cast(XSectShape::GOTHIC);
+            case XsectShape::CATENARY:        return static_cast(XSectShape::CATENARY);
+            case XsectShape::SEMIELLIPTICAL:  return static_cast(XSectShape::SEMIELLIPTICAL);
+            case XsectShape::BASKETHANDLE:    return static_cast(XSectShape::BASKETHANDLE);
+            case XsectShape::SEMICIRCULAR:    return static_cast(XSectShape::SEMICIRCULAR);
+            case XsectShape::RECT_TRIANG:     return static_cast(XSectShape::RECT_TRIANG);
+            case XsectShape::RECT_ROUND:      return static_cast(XSectShape::RECT_ROUND);
+            case XsectShape::HORIZ_ELLIPSE:   return static_cast(XSectShape::HORIZ_ELLIPSE);
+            case XsectShape::VERT_ELLIPSE:    return static_cast(XSectShape::VERT_ELLIPSE);
+            case XsectShape::ARCH:            return static_cast(XSectShape::ARCH);
+            case XsectShape::IRREGULAR:       return static_cast(XSectShape::IRREGULAR);
+            case XsectShape::CUSTOM:          return static_cast(XSectShape::CUSTOM);
+            case XsectShape::FORCE_MAIN:      return static_cast(XSectShape::FORCE_MAIN);
+            case XsectShape::STREET_XSECT:    return static_cast(XSectShape::STREET_XSECT);
+            case XsectShape::DUMMY:           return static_cast(XSectShape::DUMMY);
+            default:                          return static_cast(XSectShape::DUMMY);
+        }
+    };
+
+    std::vector xsect_params(static_cast(n_links));
+    for (int j = 0; j < n_links; ++j) {
+        auto uj = static_cast(j);
+        if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+
+        auto& xs = xsect_params[uj];
+        xs.type   = translateShape(ctx.links.xsect_shape[uj]);
+        // Cache translated shape code to avoid per-timestep switch dispatch
+        ctx.links.xsect_batch_shape[uj] = xs.type;
+        xs.y_full = ctx.links.xsect_y_full[uj];
+        xs.a_full = ctx.links.xsect_a_full[uj];
+        xs.w_max  = ctx.links.xsect_w_max[uj];
+        xs.r_full = ctx.links.xsect_r_full[uj];
+        xs.s_full = ctx.links.xsect_s_full[uj];
+
+        // Shape-specific parameters for batch kernels
+        xs.y_bot  = ctx.links.xsect_y_bot[uj];   // bottom width (TRAP), bottom depth (FILLED_CIRC)
+        xs.a_bot  = ctx.links.xsect_a_bot[uj];   // bottom area
+        xs.s_bot  = ctx.links.xsect_s_bot[uj];   // side slope (TRAP), C-factor (FORCE_MAIN)
+        xs.r_bot  = ctx.links.xsect_r_bot[uj];   // side slope2, wetted perimeter
+
+        // Compute full-depth properties if not already set
+        if (xs.a_full == 0.0 && xs.y_full > 0.0) {
+            double p[4] = {xs.y_full, xs.w_max, 0, 0};
+            xsect::setParams(xs, xs.type, p, 1.0);
+            // Write back computed values to link SoA
+            ctx.links.xsect_a_full[uj] = xs.a_full;
+            ctx.links.xsect_r_full[uj] = xs.r_full;
+            ctx.links.xsect_s_full[uj] = xs.s_full;
+            ctx.links.xsect_w_max[uj]  = xs.w_max;
         }
     }
 
+    applyConduitLengthening(ctx, model);
+
+
     // Build shape-grouped batch index
     groups_.build(xsect_params.data(), n_links);
 
@@ -242,9 +386,11 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
             kw_solver_.init(n_links, groups_);
             // Build topological link order for upstream → downstream processing
             std::vector sorted;
+            const std::vector divert = buildDivertLinks(ctx);
             int n_sorted = toposort::sortLinks(ctx.links.node1.data(),
                                                ctx.links.node2.data(),
-                                               n_links, n_nodes, sorted);
+                                               n_links, n_nodes, sorted,
+                                               divert.data());
             // Gap #44: detect routing loop (cycle) — matching legacy ERR_LOOP check
             if (n_sorted < n_links) cycle_detected_ = true;
             kw_solver_.setLinkOrder(sorted);
@@ -264,17 +410,43 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
             // compiled default (DEFAULT_HEAD_TOL, already in feet) is left as-is.
             // Skipping this made an SI model's 0.0015 m tolerance act as
             // 0.0015 ft (~3.3× too tight) → chronic non-convergence.
+            //
+            // A deck may also carry an explicit ZERO for either option.
+            // Legacy treats zero as "use the compiled default"
+            // (dynwave.c:182-184):
+            //     if (HeadTol == 0.0)  HeadTol  = DEFAULT_HEADTOL;
+            //     if (MaxTrials == 0)  MaxTrials = DEFAULT_MAXTRIALS;
+            // and SWMM itself writes those zeros — project.c:897-898 sets
+            // MaxTrials/HeadTol to 0 precisely to "force use of default", so
+            // decks saved by the GUI ship them. Without the substitution
+            // `while (t_steps < max_trials)` runs ZERO Picard iterations: every
+            // link flow and node depth stays at its initial value for the whole
+            // simulation, silently, with no error and a clean mass balance.
+            // 362 of the 1,396 corpus decks (26%) carry MAX_TRIALS 0.
             const double ucf_len = ucf::Ucf[ucf::LENGTH][
                 ucf::getUnitSystem(static_cast(ctx.options.flow_units))];
+            // dynwave_validate: only a ZERO tolerance takes the default; any
+            // written value is in the deck's length unit and is converted.
+            // The former `== 0.005 -> default` shortcut left an SI deck's
+            // HEAD_TOLERANCE 0.005 (metres, 0.0164 ft) at 0.005 ft, so its
+            // Picard loop converged and bypassed differently from step 1
+            // (si-very-simple-cfs-flow-import-icm-swmm).
             dw_solver_.head_tol =
-                (ctx.options.head_tol == constants::DEFAULT_HEAD_TOL)
+                (ctx.options.head_tol == 0.0)
                     ? constants::DEFAULT_HEAD_TOL
                     : ctx.options.head_tol / ucf_len;
-            dw_solver_.max_trials = ctx.options.max_trials;
+            dw_solver_.max_trials = (ctx.options.max_trials > 0)
+                    ? ctx.options.max_trials
+                    : constants::DEFAULT_MAX_TRIALS;
             dw_solver_.surcharge_method =
                 static_cast(ctx.options.surcharge_method);
             dw_solver_.node_continuity = ctx.options.node_continuity;
             dw_solver_.anderson_accel = ctx.options.anderson_accel;
+            // Unsteady friction (issue #156): dimensionless, no unit
+            // conversion.
+            dw_solver_.unsteady_friction = ctx.options.unsteady_friction;
+            dw_solver_.uf_k3             = ctx.options.uf_k3;
+            dw_solver_.tpa_celerity      = ctx.options.tpa_celerity;  // #156
 
             dw_solver_.init(n_nodes, n_links, groups_, ctx);
             break;
@@ -285,9 +457,11 @@ void Router::init(SimulationContext& ctx, RouteModel model) {
         }
         case RouteModel::STEADY: {
             // Build topological link order (same as KW — upstream → downstream)
+            const std::vector divert = buildDivertLinks(ctx);
             int n_sorted = toposort::sortLinks(ctx.links.node1.data(),
                                                ctx.links.node2.data(),
-                                               n_links, n_nodes, steady_sorted_links_);
+                                               n_links, n_nodes,
+                                               steady_sorted_links_, divert.data());
             // Gap #44: detect routing loop (cycle)
             if (n_sorted < n_links) cycle_detected_ = true;
             break;
@@ -331,62 +505,23 @@ int Router::step(SimulationContext& ctx, double dt,
     if (model_ != RouteModel::DYNWAVE)
         computeConduitLosses(ctx, dt, evap_rate);
 
-    // 3. Set outfall boundary depths (P8-G03)
-    outfall::setAllOutfallDepths(ctx, ctx.current_date);
+    // 3. Set outfall boundary depths (P8-G03) — at the START of the step:
+    // legacy's dynamic wave enters iteration 0 with the depth its previous
+    // step's last link_setOutfallDepth left (that step's end-of-step stage
+    // = this step's start), and re-evaluates at the end of THIS step only
+    // from iteration 1 on (dynwave.c:600, inside the iteration loop —
+    // DynamicWave.cpp's Step 4b). KW/SF set it once at init (flowrout.c:390).
+    outfall::setAllOutfallDepths(ctx, 0.0);
 
     // 4. Dispatch to solver
     int iters = 0;
     switch (model_) {
         case RouteModel::KINWAVE:
-            iters = kw_solver_.execute(ctx, dt);
-
-            // Storage node iterative update for KW (P8-G07)
-            // After KW routing, storage nodes need depth from volume balance
-            for (int j = 0; j < ctx.n_nodes(); ++j) {
-                auto uj = static_cast(j);
-                if (ctx.nodes.type[uj] != NodeType::STORAGE) continue;
-
-                double v_old = ctx.nodes.old_volume[uj];
-                double q_in = ctx.nodes.inflow[uj];
-                double q_out = 0.0;
-                // Sum outgoing link flows
-                for (int k = 0; k < ctx.n_links(); ++k) {
-                    auto uk = static_cast(k);
-                    if (ctx.links.node1[uk] == j && ctx.links.flow[uk] > 0.0)
-                        q_out += ctx.links.flow[uk];
-                    if (ctx.links.node2[uk] == j && ctx.links.flow[uk] < 0.0)
-                        q_out -= ctx.links.flow[uk];
-                }
-
-                // Successive approximation (omega=0.55, max 10 iters)
-                double d1 = ctx.nodes.depth[uj];
-                for (int iter = 0; iter < 10; ++iter) {
-                    double v_new = v_old + (q_in - q_out) * dt;
-                    v_new = std::max(v_new, 0.0);
-
-                    // Overflow check
-                    double full_vol = node::getVolume(ctx.nodes, j, ctx.nodes.full_depth[uj], &ctx.tables,
-                        ucf::getUnitSystem(static_cast(ctx.options.flow_units)),
-                        &ctx.node_subtypes);
-                    if (v_new > full_vol) {
-                        ctx.nodes.overflow[uj] = (v_new - full_vol) / dt;
-                        v_new = full_vol;
-                    }
-
-                    ctx.nodes.volume[uj] = v_new;
-                    // Invert volume → depth using node::getDepth (Newton / table lookup)
-                    // Matches legacy node_getDepth() in node.c (Gap #12)
-                    int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
-                    double d2 = node::getDepth(ctx.nodes, j, v_new, &ctx.tables, us, &ctx.node_subtypes);
-
-                    // Under-relaxation
-                    d2 = 0.45 * d1 + 0.55 * d2;
-                    if (std::fabs(d2 - d1) < 0.005) { d1 = d2; break; }
-                    d1 = d2;
-                }
-                ctx.nodes.depth[uj] = d1;
-                ctx.nodes.head[uj] = ctx.nodes.invert_elev[uj] + d1;
-            }
+            // Storage nodes are converged INSIDE the sorted-link loop, before
+            // the links they drain through are routed (legacy flowrout.c:183).
+            // A post-pass cannot do it: an outlet structure's flow depends on
+            // the very depth the pass is trying to find.
+            iters = kw_solver_.execute(ctx, dt, structures_);
             break;
 
         case RouteModel::DYNWAVE:
@@ -404,11 +539,29 @@ int Router::step(SimulationContext& ctx, double dt,
             break;
     }
 
-    // 5. Compute divider flows (P8-G02)
-    divider::computeDividerFlows(ctx, ctx.node_subtypes.dividers);
+    // Divider flows are computed where legacy computes them — inside the
+    // routing passes via divider::getOutflow (node_getOutflow dispatch), not
+    // as a post-step overwrite. A post-step pass clobbered the diversion
+    // link's routed flow under every model, including DYNWAVE where legacy
+    // ignores the divider relation for true conduits.
 
     // 6. Update link final states (depth, volume)
-    updateLinkStates(ctx);
+    //
+    // NOT under FV: publishFv has already written every node's head, and an
+    // FV head is PIEZOMETRIC. `head = invert + depth` cannot express one that
+    // sits below the node's own invert, because the published depth is a
+    // water depth floored at zero — so recomputing here silently replaced it
+    // with the invert. Measured on the issue #156 TPA sealed-drawdown
+    // fixture: the apex head reached 3.5 ft inside the step (invert 6.0) and
+    // every reader outside the solver saw exactly 6.0, which is what made the
+    // sub-atmospheric gate unfalsifiable. For every node whose head is at or
+    // above its invert the two agree exactly, so this changes nothing else.
+    //
+    // The other routers still need it: they set depth as the primary variable
+    // and derive head from it, and DYNWAVE's own head writes happen per
+    // Picard pass rather than once at the end.
+    if (ctx.options.routing_model != RoutingModel::FV)
+        updateLinkStates(ctx);
 
     return iters;
 }
@@ -419,6 +572,13 @@ int Router::step(SimulationContext& ctx, double dt,
 
 double Router::getAdaptiveStep(SimulationContext& ctx,
                                 double fixed_step, double courant) {
+    // Legacy routing_getRoutingStep (routing.c:170): a model with no links
+    // always routes at the user's fixed step — the DW variable-step machinery
+    // is never entered. Without this guard the DW path returns MinRouteStep
+    // (0.5 s) for the FIRST step, permanently offsetting the routing grid so
+    // runoff windows advance one step early relative to every report
+    // boundary (all non-interpolated report values shift a window).
+    if (ctx.n_links() == 0) return fixed_step;
     if (model_ == RouteModel::DYNWAVE) {
         return dw_solver_.getRoutingStep(ctx, fixed_step, courant);
     }
@@ -463,11 +623,10 @@ void Router::initNodeFlows(SimulationContext& ctx, double dt, double evap_rate)
             double stor_evap_rate = evap_rate * evap_frac;
 
             // exfil_cfs is pre-computed by ExfilSolver::computeAll() (called before
-            // router_.step()) and stored as a volume in the side-table's exfil_loss.
-            // Convert back to a rate for joint capping with evaporation.
-            double exfil_cfs = 0.0;
-            if (dt > 0.0 && sr >= 0)
-                exfil_cfs = st.exfil_loss[sru] / dt;
+            // router_.step()) and handed over as the RAW rate in exfil_rate, so
+            // the joint cap below sees exactly what legacy storage_getLosses
+            // sees (no pre-cap, no volume*dt/dt round-trip).
+            double exfil_cfs = (sr >= 0) ? st.exfil_rate[sru] : 0.0;
 
             if (stor_evap_rate > 0.0 || seep_rate > 0.0 || exfil_cfs > 0.0) {
                 double depth = nodes.depth[ui];
@@ -475,8 +634,15 @@ void Router::initNodeFlows(SimulationContext& ctx, double dt, double evap_rate)
                     ucf::getUnitSystem(static_cast(ctx.options.flow_units)),
                     &ctx.node_subtypes);
 
-                // Evaporation rate over surface area (cfs)
-                double evap_cfs = 0.0;
+                // Evaporation rate over surface area (cfs). Legacy
+                // storage_getLosses (node.c:1069) multiplies by the area ONLY
+                // when the stored volume exceeds FUDGE and otherwise leaves
+                // `evapRate` as the bare ft/s rate — which it then returns as
+                // a cfs loss. v6 zeroed that case; an almost-empty storage
+                // therefore lost nothing where legacy books ~4e-8 cfs, and the
+                // 1-ULP gap in the node's outflow grew into a deck-wide
+                // divergence (usgs-runoff's P005). Quirk reproduced verbatim.
+                double evap_cfs = stor_evap_rate;
                 if (nodes.volume[ui] > constants::FUDGE)
                     evap_cfs = area * stor_evap_rate;
 
@@ -508,8 +674,20 @@ void Router::initNodeFlows(SimulationContext& ctx, double dt, double evap_rate)
 
         // Set overflow from excess stored volume
         // (matching legacy node.c node_initFlows lines 324-326)
-        if (nodes.volume[ui] > nodes.full_volume[ui] && dt > 0.0) {
-            nodes.overflow[ui] = (nodes.volume[ui] - nodes.full_volume[ui]) / dt;
+        // Legacy node_initInflow: overflow = any excess stored volume over
+        // legacy's Node.fullVolume — NodeData::rpt_full_volume (0 for a
+        // junction, the curve's full volume for storage, a Type-1 pump wet
+        // well's curve maximum). The dynamic wave and the tree routers both
+        // book node volume in that convention (kinwave::finishRouting's
+        // setNewNodeState port); FV keeps its own full_volume. Under KW a
+        // ponded junction's whole pond is the overflow that getLinkInflow
+        // re-injects (Node.inflow + Node.overflow) — new-mikeurbancn's 6033
+        // fed its pipe 0.2816 cfs against legacy's 0.2831 with the engine's
+        // MIN_SURFAREA-based full volume subtracted.
+        const double full_vol = (ctx.options.routing_model == RoutingModel::FV)
+            ? nodes.full_volume[ui] : nodes.rpt_full_volume[ui];
+        if (nodes.volume[ui] > full_vol && dt > 0.0) {
+            nodes.overflow[ui] = (nodes.volume[ui] - full_vol) / dt;
         } else {
             nodes.overflow[ui] = 0.0;
         }
@@ -536,14 +714,14 @@ void Router::computeConduitLosses(SimulationContext& ctx, double dt, double evap
         double seep_loss = 0.0;
 
         if (depth > constants::FUDGE) {
-            // Use RAW user-input length (matching legacy
-            // `link.c::conduit_getLossRate` line 1358:
-            //   length = conduit_getLength(j);
-            // which returns `Conduit[k].length` (raw) for non-IRREGULAR
-            // conduits — NOT `Conduit[k].modLength` (lengthened).
-            // The lengthened length appears only in the momentum equation
-            // (`dwflow.c:133`), not in loss-volume accounting.
-            double length = CD.length[ucr];
+            // Use the ROUTING length (legacy `conduit_getLossRate`
+            // line 1358: `length = conduit_getLength(j)`) — the authored
+            // [CONDUITS] length for every section but IRREGULAR, and NOT
+            // `Conduit[k].modLength` (lengthened). The lengthened length
+            // appears only in the momentum equation (`dwflow.c:133`), not
+            // in loss-volume accounting.
+            double length = CD.true_length[ucr];
+            if (length <= 0.0) length = CD.length[ucr];
             if (length <= 0.0) length = CD.mod_length[ucr];
             int batch_shape = links.xsect_batch_shape[uj];
 
@@ -563,62 +741,126 @@ void Router::computeConduitLosses(SimulationContext& ctx, double dt, double evap
             // The transect top-width below uses the linear approximation; the
             // faithful getWofY was tried and does NOT resolve the parity gap
             // (the gap is the timing, not the width). See PARITY_FINDINGS.
-            if (xsect::isOpen(batch_shape) && evap_rate > 0.0) {
-                double top_width = 0.0;
-                if (batch_shape == static_cast(XSectShape::IRREGULAR) ||
-                    batch_shape == static_cast(XSectShape::CUSTOM)) {
-                    double y_full = links.xsect_y_full[uj];
-                    double w_max  = links.xsect_w_max[uj];
-                    top_width = (y_full > 0.0) ? w_max * std::min(depth / y_full, 1.0) : 0.0;
-                } else {
-                    XSectParams xs{};
-                    xs.type   = batch_shape;
-                    xs.y_full = links.xsect_y_full[uj];
-                    xs.a_full = links.xsect_a_full[uj];
-                    xs.w_max  = links.xsect_w_max[uj];
-                    top_width = xsect::getWofY(xs, depth);
-                }
-                evap_loss = top_width * length * evap_rate;
-            }
-
-            // Seepage loss
-            if (CD.seep_rate[ucr] > 0.0) {
+            // G-X4: with the aquifer coupled the seepage is signed and
+            // `[2D_AQUIFER_LINKS] KC` can give a conduit with no [LOSSES]
+            // rate an exchange, so the gate is the effective conductivity.
+            const bool gw_two_way = !CD.gw_coupled.empty() &&
+                                    CD.gw_coupled[ucr] != 0;
+            const double k_seep = gw_two_way ? CD.gw_kc[ucr] : CD.seep_rate[ucr];
+            const bool wantEvap = xsect::isOpen(batch_shape) && evap_rate > 0.0;
+            const bool wantSeep = k_seep > 0.0;
+            if (wantEvap || wantSeep) {
+                // Faithful params (matching DynamicWave.cpp::buildXSP): the
+                // previous minimal {type, y_full, a_full, w_max} left y_bot/
+                // s_bot/a_bot/r_bot at 0, so getWofY returned width 0 — and
+                // seepage/evap were identically zero — for every shape whose
+                // width law needs them (TRAPEZOIDAL, TRIANGULAR, PARABOLIC,
+                // POWER, RECT_TRIANG, RECT_ROUND, MOD_BASKET) plus every
+                // tabulated shape (no transect tables wired). Legacy
+                // conduit_getLossRate uses the full xsect for all of them.
                 XSectParams xs{};
                 xs.type   = batch_shape;
                 xs.y_full = links.xsect_y_full[uj];
                 xs.a_full = links.xsect_a_full[uj];
                 xs.w_max  = links.xsect_w_max[uj];
                 xs.yw_max = links.xsect_yw_max[uj];
+                xs.r_full = links.xsect_r_full[uj];
+                xs.s_full = links.xsect_s_full[uj];
+                xs.s_max  = links.xsect_s_max[uj];
+                xs.y_bot  = links.xsect_y_bot[uj];
+                xs.a_bot  = links.xsect_a_bot[uj];
+                xs.s_bot  = links.xsect_s_bot[uj];
+                xs.r_bot  = links.xsect_r_bot[uj];
+                if (batch_shape == static_cast(XSectShape::IRREGULAR) ||
+                    batch_shape == static_cast(XSectShape::CUSTOM) ||
+                    batch_shape == static_cast(XSectShape::STREET_XSECT)) {
+                    const int ci = links.xsect_curve[uj];
+                    if (ci >= 0 &&
+                        static_cast(ci) < ctx.transect_tables.size()) {
+                        const auto& td =
+                            ctx.transect_tables[static_cast(ci)];
+                        xs.transect          = ci;
+                        xs.area_tbl          = td.area_tbl;
+                        xs.hrad_tbl          = td.hrad_tbl;
+                        xs.width_tbl         = td.width_tbl;
+                        xs.area_lut          = &td.area_lut;
+                        xs.transect_tbl_size = transect::N_TRANSECT_TBL;
+                    }
+                }
+
+                if (wantEvap) {
+                    double top_width;
+                    if (batch_shape == static_cast(XSectShape::IRREGULAR) ||
+                        batch_shape == static_cast(XSectShape::CUSTOM)) {
+                        // Deliberate linear approximation — see the PARITY
+                        // note above (the gap is timing, not the width law).
+                        top_width = (xs.y_full > 0.0)
+                            ? xs.w_max * std::min(depth / xs.y_full, 1.0) : 0.0;
+                    } else {
+                        top_width = xsect::getWofY(xs, depth);
+                    }
+                    evap_loss = top_width * length * evap_rate;
+                }
 
-                double d_seep = depth;
-                // Limit depth to depth at max width (matching legacy)
-                if (batch_shape == static_cast(XSectShape::RECT_CLOSED))
-                    ; // use wMax directly
-                else if (d_seep >= xs.yw_max)
-                    d_seep = xs.yw_max;
-                double width = xsect::getWofY(xs, d_seep);
-                seep_loss = CD.seep_rate[ucr] * width * length;
+                // Seepage loss
+                if (wantSeep) {
+                    double d_seep = depth;
+                    // Legacy conduit_getLossRate: RECT_CLOSED uses wMax
+                    // directly (getWofY's tabulated crown width is 0 exactly
+                    // at full depth); every other shape clamps depth to
+                    // yw_max first.
+                    double width;
+                    if (batch_shape ==
+                        static_cast(XSectShape::RECT_CLOSED)) {
+                        width = xs.w_max;
+                    } else {
+                        if (d_seep >= xs.yw_max)
+                            d_seep = xs.yw_max;
+                        width = xsect::getWofY(xs, d_seep);
+                    }
+                    seep_loss = k_seep * width * length;
+                    // Monthly conductivity adjustment (legacy link.c:1378:
+                    // seepLossRate *= Adjust.hydconFactor). infil_factor
+                    // mirrors adjust_hydcon[mon] each step (A2d) and is 1.0
+                    // exactly on unadjusted decks.
+                    seep_loss *= ctx.climate_state.infil_factor;
+                    if (gw_two_way) {   // G-X4: signed conductance + gain cap
+                        seep_loss *= hydraulics::aquiferSeepFactor(
+                            depth, CD.gw_head_rel[ucr], CD.gw_dc[ucr]);
+                        seep_loss = hydraulics::capAquiferGain(
+                            seep_loss, CD.gw_gain_max[ucr]);
+                    }
+                }
             }
 
             // Limit the total to what is actually there. A volume-tracking
-            // solver caps on the water it holds; KINWAVE/STEADY have no conduit
-            // volume state of their own and cap on the flow instead. FV holds
-            // volume, so capping it on |flow| meant standing water in a conduit
-            // with no flow never evaporated at all.
-            double total = evap_loss + seep_loss;
-            if (total > 0.0) {
-                double q_avail = (model_ == RouteModel::DYNWAVE ||
-                                  model_ == RouteModel::FV)
-                    ? links.volume[uj] / dt
-                    : std::fabs(links.flow[uj]);
+            // solver caps on the water it holds (legacy conduit_getLossRate
+            // under DW: newVolume / tstep); FV holds volume too, so capping
+            // it on |flow| meant standing water in a conduit with no flow
+            // never evaporated at all. KINWAVE / STEADY cap on the CURRENT
+            // solve's inflow (legacy passes qin*Qfull per barrel into
+            // link_getLossRate, `q = ABS(q)`), which the solvers apply
+            // themselves and write back — the previous step's outflow used
+            // here was 0 on the first wet step, so the rate was capped to 0
+            // where legacy lost evaporation from the start (runoff29-sw5).
+            // G-X4: a gaining conduit brings water IN, so it is not part of
+            // what the conduit can afford to lose; the cap sees the losing
+            // components only and the gain passes through (the aquifer's own
+            // budget bounds it).
+            double total = evap_loss + std::max(seep_loss, 0.0);
+            if (total > 0.0 &&
+                (model_ == RouteModel::DYNWAVE || model_ == RouteModel::FV)) {
+                double q_avail = links.volume[uj] / dt;
                 if (total > q_avail && q_avail >= 0.0) {
                     double ratio = q_avail / total;
                     evap_loss *= ratio;
-                    seep_loss *= ratio;
+                    if (seep_loss > 0.0) seep_loss *= ratio;
                 }
             }
         }
 
+        hydraulics::applySeepageForcing(ctx, uj, seep_loss);   // G-X4
+
         CD.evap_loss_rate[ucr] = evap_loss;
         CD.seep_loss_rate[ucr] = seep_loss;
     }
@@ -649,61 +891,77 @@ int Router::executeSteadyFlow(SimulationContext& ctx, double dt) {
           }()
         : steady_sorted_links_;
 
+    steady_storage_updated_.assign(static_cast(ctx.n_nodes()), 0);
+    steady_y_.assign(static_cast(ctx.n_links()), 0.0);
+
     for (int idx = 0; idx < static_cast(order.size()); ++idx) {
         int j   = order[static_cast(idx)];
         auto uj = static_cast(j);
 
-        // Non-conduit links: outflow equals upstream node inflow (pass-through).
-        // Matches legacy steadyflow_execute() else branch: *qout = *qin.
+        // PARITY flowrout.c:181-183 — converge a storage unit's depth before
+        // routing the links it drains through (see the KINWAVE case).
+        {
+            int n1s = links.node1[uj];
+            if (n1s >= 0
+                && nodes.type[static_cast(n1s)] == NodeType::STORAGE
+                && !steady_storage_updated_[static_cast(n1s)]) {
+                kinwave::updateStorageState(ctx, structures_, order, idx, n1s, dt);
+                steady_storage_updated_[static_cast(n1s)] = 1;
+            }
+        }
+
+        // Non-conduit links are not routed — steadyflow_execute returns
+        // *qout = *qin for them — but their INFLOW is their own head-discharge
+        // relation, not the upstream node's inflow (legacy getLinkInflow).
         if (links.type[uj] != LinkType::CONDUIT) {
             int n1 = links.node1[uj];
-            if (n1 >= 0) {
-                double q = nodes.inflow[static_cast(n1)];
-                links.flow[uj] = q;
-                int n2 = links.node2[uj];
-                if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
-            }
+            int n2 = links.node2[uj];
+            double q = kinwave::getLinkInflow(ctx, structures_, j, dt);
+            links.flow[uj] = q;
+            if (n1 >= 0) nodes.outflow[static_cast(n1)] += q;
+            if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
             continue;
         }
         auto& CD = ctx.link_subtypes.conduits;
         const auto ucr = static_cast(ctx.link_subtypes.conduit_row(j));
 
-        // DUMMY cross-section: zero area, pass flow through.
+        // DUMMY cross-section: routed like every other link in legacy —
+        // getLinkInflow (divider/storage dispatch, qLimit and max-outflow
+        // caps), steadyflow_execute passes it through, and BOTH end nodes'
+        // flow accumulators are updated (flowrout.c:196-197).
         if (links.xsect_shape[uj] == XsectShape::DUMMY) {
             int n1 = links.node1[uj];
             int n2 = links.node2[uj];
-            if (n1 >= 0) {
-                double q = nodes.inflow[static_cast(n1)];
-                links.flow[uj] = q;
-                if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
-            }
+            double q = kinwave::getLinkInflow(ctx, structures_, j, dt);
+            links.flow[uj] = q;
+            if (n1 >= 0) nodes.outflow[static_cast(n1)] += q;
+            if (n2 >= 0) nodes.inflow[static_cast(n2)] += q;
             links.depth[uj]  = 0.0;
             links.volume[uj] = 0.0;
             continue;
         }
 
-        // Gather inflow at upstream node, limited by available volume.
-        // Matches legacy getLinkInflow → node_getMaxOutflow.
+        // Gather inflow at upstream node — legacy getLinkInflow
+        // (storage/divider/junction dispatch, qLimit, max-outflow cap).
         int n1 = links.node1[uj];
         double qin = 0.0;
         if (n1 >= 0) {
-            auto un1 = static_cast(n1);
-            qin = nodes.inflow[un1];
-            double q_max = node::getMaxOutflow(nodes, n1, qin, dt);
-            qin = std::min(qin, q_max);
+            qin = kinwave::getLinkInflow(ctx, structures_, j, dt);
         }
 
         double barrels = static_cast(std::max(CD.barrels[ucr], 1));
         double q       = qin / barrels;
 
-        // Subtract pre-computed conduit loss rate (evap + seep per barrel).
-        // Matches legacy link_getLossRate call in steadyflow_execute().
-        double loss_rate = CD.evap_loss_rate[ucr] + CD.seep_loss_rate[ucr];
+        // Subtract the conduit loss rate (evap + seep per barrel), capped on
+        // this solve's per-barrel inflow as legacy conduit_getLossRate does
+        // for SF (`q = ABS(q)`; both components scaled by q / total and
+        // stored for the mass balance).
+        double loss_rate = kinwave::capConduitLoss(ctx, ucr, std::fabs(q));
         q -= loss_rate;
         if (q < 0.0) q = 0.0;
 
         // Build cross-section params once (used for getAofS and getYofA below).
-        XSectParams xs = buildXSP(links, uj);
+        XSectParams xs = buildXSP(ctx, uj);
 
         // Manning normal-depth area.
         double q_full = CD.q_full[ucr];
@@ -739,35 +997,27 @@ int Router::executeSteadyFlow(SimulationContext& ctx, double dt) {
         // Update link depth and volume.
         // In steady state a1 == a2, so depth and volume are uniform.
         double y = xsect::getYofA(xs, a);
-        double length = CD.mod_length[ucr];
+        // legacy flowrout.c:698 books the steady-flow volume over
+        // link_getLength(j) — the routing length, not modLength.
+        double length = CD.true_length[ucr];
         if (length <= 0.0) length = CD.length[ucr];
 
         links.depth[uj]  = y;
         links.volume[uj] = a * length * barrels;
+        steady_y_[uj]    = y;
 
         // Gap #57: steady flow — same area at both ends, so both full or neither.
         CD.full_state[ucr] = (a_full > 0.0 && a >= a_full) ? int8_t{3} : int8_t{0};
-
-        // Update non-storage end-node depths (max of current and conduit end).
-        // Matches legacy setNewLinkState → updateNodeDepth in flowrout.c.
-        auto updateNodeDepth = [&](int ni, double y_conduit, double link_offset) {
-            if (ni < 0) return;
-            auto uni = static_cast(ni);
-            NodeType nt = nodes.type[uni];
-            if (nt == NodeType::STORAGE) return;
-            double y_node = y_conduit + link_offset;
-            if (nt != NodeType::OUTFALL && nodes.overflow[uni] > 0.0)
-                y_node = nodes.full_depth[uni];
-            if (nodes.depth[uni] < y_node) {
-                double full_d = nodes.full_depth[uni];
-                nodes.depth[uni] = (full_d > 0.0) ? std::min(y_node, full_d) : y_node;
-                nodes.head[uni]  = nodes.invert_elev[uni] + nodes.depth[uni];
-            }
-        };
-        updateNodeDepth(n1, y, links.offset1[uj]);
-        updateNodeDepth(n2, y, links.offset2[uj]);
+        // Node depths are raised AFTER the per-node volume/overflow pass, in
+        // kinwave::finishRouting — legacy runs setNewNodeState for every node
+        // before any setNewLinkState raises a depth (flowrout.c:203-205).
     }
 
+    // Legacy end-of-step passes: setNewNodeState for every node, then
+    // setNewLinkState's node-depth raises (steady: same depth at both ends).
+    kinwave::finishRouting(ctx, structures_, order, steady_storage_updated_,
+                           steady_y_, steady_y_, dt);
+
     return 1;  // steady flow always converges in one pass
 }
 
@@ -808,6 +1058,10 @@ void Router::initFv(SimulationContext& ctx) {
     fv_opts_.cell_length   = ctx.options.fv.cell_length   / ucf_len;
     fv_opts_.slot_celerity = ctx.options.fv.slot_celerity / ucf_len;
     fv_opts_.dispersion    = ctx.options.fv.dispersion    / (ucf_len * ucf_len);
+    // Unsteady friction (issue #156): shared [OPTIONS] keys, dimensionless —
+    // copied here so the solver keeps seeing only FvOptions.
+    fv_opts_.unsteady_friction = ctx.options.unsteady_friction;
+    fv_opts_.uf_k3             = ctx.options.uf_k3;
 
     // Options that are parsed and stored but reach nothing. Saying so at open
     // is the whole point: a model calibrated with FV_DISPERSION set would
@@ -843,6 +1097,103 @@ void Router::initFv(SimulationContext& ctx) {
     const int nn = fv_mesh_.n_nodes();
     fv_state_.resize(nc, nn, 0);
 
+    // Virtual junctions have no [JUNCTIONS] InitDepth row, and the post-parse
+    // seeding that interpolates one (issue #156 P1) is DYNWAVE-only by
+    // measurement — so under FV a VJ is dry here, links.depth on a conduit
+    // that ends at one has averaged in a zero, and a chain the mesh treats as
+    // ONE run of cells starts with a hole at every splice. On the mixed-flow
+    // study's e2 deck (initial level 0.073 m) the mid reach seeded at 0.001 m
+    // and the bore reached the 9.9 m station 3.6x late (P6 finding F1).
+    //
+    // So interpolate a free surface for every conduit-degree-2 VJ between the
+    // nearest NON-virtual nodes reached by walking its spliced chain in both
+    // directions — the same walk, with the same at-least-one-wet-endpoint
+    // rule, as PostParseResolver's DW seeding — and let the loop below read a
+    // VJ end through that surface. A VJ becomes as transparent to the initial
+    // condition as its spliced face is to the solution. CELL seeding only:
+    // node state is untouched, so the P1 measurement that live VJ node
+    // seeding destabilizes FV is not disturbed. Decks without VJs take the
+    // any_vj early-out and are bitwise unaffected.
+    std::vector vj_eta;  // per node; NaN = no surface seeded
+    {
+        const int n_nodes = ctx.n_nodes();
+        const int n_links = ctx.n_links();
+        bool any_vj = false;
+        for (int n = 0; n < n_nodes && !any_vj; ++n)
+            any_vj = ctx.nodes.is_virtual[static_cast(n)] != 0;
+        if (any_vj) {
+            vj_eta.assign(static_cast(n_nodes),
+                          std::numeric_limits::quiet_NaN());
+            // Incident CONDUITS per virtual node (VJ splices are conduit-only
+            // by validation; anything else is rejected by the mesh builder).
+            std::vector incA(static_cast(n_nodes), -1);
+            std::vector incB(static_cast(n_nodes), -1);
+            std::vector inc_n(static_cast(n_nodes), 0);
+            for (int j = 0; j < n_links; ++j) {
+                const auto ujj = static_cast(j);
+                if (ctx.links.type[ujj] != LinkType::CONDUIT) continue;
+                for (int nd : {ctx.links.node1[ujj], ctx.links.node2[ujj]}) {
+                    if (nd < 0 || nd >= n_nodes) continue;
+                    const auto und = static_cast(nd);
+                    if (ctx.nodes.is_virtual[und] == 0) continue;
+                    if (inc_n[und] == 0)      incA[und] = j;
+                    else if (inc_n[und] == 1) incB[und] = j;
+                    ++inc_n[und];
+                }
+            }
+            auto walk = [&](int start_node, int via_link, double& eta_out,
+                            double& dist_out, bool& wet_out) -> bool {
+                int node = start_node, link = via_link;
+                double dist = 0.0;
+                for (int guard = 0; guard <= n_links; ++guard) {
+                    const auto ul = static_cast(link);
+                    const int cr = ctx.link_subtypes.conduit_row(link);
+                    dist += (cr >= 0)
+                        ? ctx.link_subtypes.conduits
+                              .length[static_cast(cr)]
+                        : 0.0;
+                    const int other = (ctx.links.node1[ul] == node)
+                        ? ctx.links.node2[ul] : ctx.links.node1[ul];
+                    if (other < 0 || other >= n_nodes) return false;
+                    const auto uo = static_cast(other);
+                    if (ctx.nodes.is_virtual[uo] == 0) {
+                        eta_out = ctx.nodes.invert_elev[uo] +
+                                  ctx.nodes.depth[uo];
+                        dist_out = dist;
+                        wet_out  = ctx.nodes.depth[uo] > 0.0;
+                        return true;
+                    }
+                    if (inc_n[uo] != 2) return false;
+                    link = (incA[uo] == link) ? incB[uo] : incA[uo];
+                    if (link < 0) return false;
+                    node = other;
+                }
+                return false;  // cycle of VJs (rejected elsewhere)
+            };
+            for (int i = 0; i < n_nodes; ++i) {
+                const auto ui = static_cast(i);
+                if (ctx.nodes.is_virtual[ui] == 0 || inc_n[ui] != 2) continue;
+                double eA = 0.0, dA = 0.0, eB = 0.0, dB = 0.0;
+                bool wetA = false, wetB = false;
+                const bool okA = walk(i, incA[ui], eA, dA, wetA);
+                const bool okB = walk(i, incB[ui], eB, dB, wetB);
+                // A dry node's surface is just its invert — interpolating
+                // between two dry endpoints with differing inverts would
+                // MANUFACTURE water on a dry deck. At least one wet endpoint,
+                // exactly as the DW seeding requires.
+                if (!(okA && wetA) && !(okB && wetB)) continue;
+                if (okA && okB) {
+                    const double d_sum = dA + dB;
+                    vj_eta[ui] = (d_sum > 0.0)
+                        ? (eA * dB + eB * dA) / d_sum
+                        : 0.5 * (eA + eB);
+                } else {
+                    vj_eta[ui] = okA ? eA : eB;
+                }
+            }
+        }
+    }
+
     // Seed cell state from the model's initial condition. LinkData carries ONE
     // depth per conduit, and that depth is the average of the two end-node
     // DEPTHS — which are measured from different inverts. Laying it down as a
@@ -878,15 +1229,23 @@ void Router::initFv(SimulationContext& ctx) {
         if (begin < 0) continue;
         const int j = fv_mesh_.conduit_link[ur];
         const auto uj = static_cast(j);
-        const fv::FvGeometry& g = fv_mesh_.geom[ur];
+        const fv::FvGeometry& g =
+            fv_mesh_.geom[static_cast(fv_mesh_.conduit_section[ur])];
         // areaOfDepth already returns the AGGREGATE section of all barrels, and
         // links.flow is the aggregate discharge, so neither is divided here.
         const double q = ctx.links.flow[uj];
 
-        // Surface at each end, where that end has water to define one.
+        // Surface at each end, where that end has water to define one. A
+        // virtual end carries the surface interpolated across its chain above.
         auto bank_eta = [&](int nd, double& eta) {
             if (nd < 0) return false;
             const auto und = static_cast(nd);
+            if (und < vj_eta.size() && ctx.nodes.is_virtual[und] != 0) {
+                if (!std::isfinite(vj_eta[und]) ||
+                    vj_eta[und] <= ctx.nodes.invert_elev[und]) return false;
+                eta = vj_eta[und];
+                return true;
+            }
             if (ctx.nodes.depth[und] <= 0.0) return false;
             eta = ctx.nodes.invert_elev[und] + ctx.nodes.depth[und];
             return true;
@@ -906,10 +1265,35 @@ void Router::initFv(SimulationContext& ctx) {
         const bool shoreline = (wet1 != wet2) && step;
         const double eta_wet = wet1 ? eta1 : eta2;
 
-        const double uniform =
-            fv::kernels::areaOfDepth(g, ctx.links.depth[uj]);
+        // links.depth is the average of the two end-node depths, and a virtual
+        // end contributed a zero to it. Rebuild the average through the
+        // interpolated VJ surfaces so the projection is the one the deck's
+        // real nodes define.
+        double init_depth = ctx.links.depth[uj];
+        {
+            const int n1 = ctx.links.node1[uj];
+            const int n2 = ctx.links.node2[uj];
+            const bool v1 = n1 >= 0 && static_cast(n1) <
+                vj_eta.size() &&
+                ctx.nodes.is_virtual[static_cast(n1)] != 0;
+            const bool v2 = n2 >= 0 && static_cast(n2) <
+                vj_eta.size() &&
+                ctx.nodes.is_virtual[static_cast(n2)] != 0;
+            if ((v1 || v2) && n1 >= 0 && n2 >= 0) {
+                auto end_depth = [&](int nd, bool v) {
+                    const auto und = static_cast(nd);
+                    if (!v) return ctx.nodes.depth[und];
+                    return std::isfinite(vj_eta[und])
+                        ? std::max(0.0,
+                                   vj_eta[und] - ctx.nodes.invert_elev[und])
+                        : 0.0;
+                };
+                init_depth = 0.5 * (end_depth(n1, v1) + end_depth(n2, v2));
+            }
+        }
+        const double uniform = fv::kernels::areaOfDepth(g, init_depth);
 
-        double vol = 0.0, a_len = 0.0, sum_len = 0.0;
+        double vol = 0.0, a_len = 0.0, sum_len = 0.0, slot_vol = 0.0;
         for (int c = begin; c < begin + count; ++c) {
             const auto uc = static_cast(c);
             double a_c = uniform;
@@ -924,9 +1308,10 @@ void Router::initFv(SimulationContext& ctx) {
             fv_state_.cell_q[uc] = (a_c > fv::kernels::kDryArea) ? q : 0.0;
 
             const double dx = fv_mesh_.cell_dx[uc];
-            sum_len += dx;
-            a_len   += a_c * dx;
-            vol     += a_c * dx;
+            sum_len  += dx;
+            a_len    += a_c * dx;
+            vol      += a_c * dx;
+            slot_vol += std::max(0.0, a_c - g.a_crown) * dx;
         }
 
         // Publish what was actually seeded, by the same reduction publishFv
@@ -938,9 +1323,11 @@ void Router::initFv(SimulationContext& ctx) {
         // acre-feet, reported as a 17 % continuity error on a model where
         // nothing moves and nothing leaves.
         if (sum_len > 0.0) {
-            ctx.links.volume[uj] = vol;
-            ctx.links.depth[uj]  =
-                fv::kernels::depthOfArea(g, a_len / sum_len);
+            ctx.links.volume[uj]      = vol;
+            ctx.links.slot_volume[uj] = slot_vol;
+            // R0b: published depth truncated to y_full (see publishFv).
+            ctx.links.depth[uj]  = std::min(
+                fv::kernels::depthOfArea(g, a_len / sum_len), g.y_full);
         }
     }
     for (int n = 0; n < nn; ++n) {
@@ -969,6 +1356,7 @@ void Router::initFv(SimulationContext& ctx) {
     fv_struct_flow_.assign(static_cast(ctx.n_links()), 0.0);
     fv_cond_loss_.assign(static_cast(fv_mesh_.n_conduits()), 0.0);
     fv_struct_int_.assign(static_cast(ctx.n_links()), 0.0);
+    fv_link_q_cap_.assign(static_cast(ctx.n_links()), -1.0);
 }
 
 /**
@@ -992,7 +1380,8 @@ int Router::stepFv(SimulationContext& ctx, double dt,
     const int nl = ctx.n_links();
 
     // Lateral inflows exactly as assembled by SWMMEngine::assembleLateralInflows.
-    // Virtual junctions cannot carry them (rule 5), so they never appear here.
+    // A virtual junction may carry one too; the solver splits it into the two
+    // cells adjoining its spliced face (ExplicitFvSolver::refreshStructFlows).
     for (int n = 0; n < nn; ++n) {
         const auto un = static_cast(n);
         // Net of the node's own losses. `nodes.losses` carries storage
@@ -1012,12 +1401,28 @@ int Router::stepFv(SimulationContext& ctx, double dt,
     }
 
     // Non-conduit structures, evaluated against the CURRENT node heads.
+    //
+    // DUMMY conduits are in the callback's list too (StructureSolver::
+    // nc_indices_ matches mesh.struct_is_dummy), but the discharge it computes
+    // for them is not usable here: its pass-through reads ctx.nodes.inflow,
+    // which under FV holds only laterals and structure scatter until publishFv
+    // writes the real boundary fluxes at end of step. So the flow it produces
+    // is dropped by the CONDUIT test below and the solver derives its own from
+    // the fluxes it is actually integrating (ExplicitFvSolver::
+    // refreshDummyFlows). What the solver cannot see is the control setting and
+    // the FLOW_LIMIT, so those are forwarded as a cap.
     auto evaluate_structures = [&]() {
         if (non_conduit_fn) non_conduit_fn(ctx, dt, 0);
         for (int j = 0; j < nl; ++j) {
             const auto uj = static_cast(j);
             fv_struct_flow_[uj] = (ctx.links.type[uj] == LinkType::CONDUIT)
                                       ? 0.0 : ctx.links.flow[uj];
+            if (ctx.links.xsect_shape[uj] == XsectShape::DUMMY) {
+                const double lim = ctx.links.q_limit[uj];
+                fv_link_q_cap_[uj] = (ctx.links.setting[uj] == 0.0)
+                                         ? 0.0
+                                         : ((lim > 0.0) ? lim : -1.0);
+            }
         }
     };
     std::fill(fv_struct_int_.begin(), fv_struct_int_.end(), 0.0);
@@ -1048,6 +1453,7 @@ int Router::stepFv(SimulationContext& ctx, double dt,
     forcing.node_lateral    = fv_lateral_.data();
     forcing.node_fixed_head = fv_fixed_head_.data();
     forcing.structure_flow  = fv_struct_flow_.data();
+    forcing.link_q_cap      = fv_link_q_cap_.data();
     forcing.conduit_loss    = fv_cond_loss_.data();
     forcing.n_nodes = nn;
     forcing.n_links = nl;
@@ -1121,8 +1527,9 @@ void Router::refreshFvBoundaryFlows(SimulationContext& ctx, double t_elapsed,
 
     // Stage boundaries first — a FREE or NORMAL outfall's depth is a function
     // of the conduit that feeds it, so it moves within the step exactly as the
-    // structures do.
-    outfall::setAllOutfallDepths(ctx, ctx.current_date);
+    // structures do. A TIDAL / TIMESERIES stage is read at the substep's own
+    // instant (start of step + t_elapsed).
+    outfall::setAllOutfallDepths(ctx, t_elapsed);
     for (int n = 0; n < nn; ++n) {
         const auto un = static_cast(n);
         if (ctx.nodes.type[un] != NodeType::OUTFALL) continue;
@@ -1153,10 +1560,12 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
         if (begin < 0 || count <= 0) continue;
         const int j = fv_mesh_.conduit_link[ur];
         const auto uj = static_cast(j);
-        const fv::FvGeometry& g = fv_mesh_.geom[ur];
+        const fv::FvGeometry& g =
+            fv_mesh_.geom[static_cast(fv_mesh_.conduit_section[ur])];
         // Cell area and discharge are ALREADY the aggregate of all barrels
         // (FvGeometry::barrel_scale), so nothing here is scaled by the count.
         double sum_len = 0.0, q_len = 0.0, a_len = 0.0, vol = 0.0;
+        double slot_vol = 0.0;
         for (int c = begin; c < begin + count; ++c) {
             const auto uc = static_cast(c);
             const double dx = fv_mesh_.cell_dx[uc];
@@ -1167,12 +1576,26 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
             q_len   += q * dx;
             a_len   += fv_state_.cell_a[uc] * dx;
             vol     += fv_state_.cell_a[uc] * dx;
+            // Slot share of the cell's storage: area above a_crown is water
+            // standing in the Preissmann slot (the crown-band taper's tiny
+            // content lives inside a_crown and is deliberately not counted).
+            slot_vol += std::max(0.0, fv_state_.cell_a[uc] - g.a_crown) * dx;
         }
         const double q_mean = (sum_len > 0.0) ? q_len / sum_len : 0.0;
         const double a_mean = (sum_len > 0.0) ? a_len / sum_len : 0.0;
 
         ctx.links.flow[uj]   = q_mean;
-        ctx.links.depth[uj]  = fv::kernels::depthOfArea(g, a_mean);
+        // Slot program R0b: the PUBLISHED depth is a water depth, truncated
+        // to the pipe's true max height — matching the dynamic-wave
+        // convention (DynamicWave.cpp links.depth = min(depth_mid, yf)).
+        // Above the crown the piezometric surplus lives in node heads and
+        // links.slot_volume; the .out depth column stops doubling as a head
+        // channel, and stat_max_filling reads ≤ 1 like legacy. The clamp is
+        // publish-only: every internal use of the mean state works from
+        // a_mean, and widthOfDepth(y_full) == widthOfDepth(piezo) == t_slot,
+        // so the derived hyd-depth/Froude below are unchanged.
+        ctx.links.depth[uj]  = std::min(
+            fv::kernels::depthOfArea(g, a_mean), g.y_full);
         // Inlet control was applied inside the solver, at the culvert's
         // upstream face; only the report flag comes back out here.
         if (impl) {
@@ -1181,11 +1604,19 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
                 ctx.link_subtypes.conduits.inlet_control[
                     static_cast(cr)] = impl->inlet_control()[ur];
         }
-        ctx.links.volume[uj] = vol;
-        const double v = (a_mean > 0.0) ? q_mean / a_mean : 0.0;
+        ctx.links.volume[uj]      = vol;
+        ctx.links.slot_volume[uj] = slot_vol;
+        // Conveyance velocity: above the crown the conserved area carries
+        // Preissmann-slot content that conveys no momentum, so Q/a_mean is
+        // slot-diluted — the same rationale as the implicit face law
+        // (PressurizedHeadSolver). Open sections have no slot; their area
+        // above y_full is genuine conveyance and stays uncapped.
+        const double a_conv = (!g.is_open && a_mean > g.a_crown) ? g.a_crown
+                                                                 : a_mean;
+        const double v = (a_conv > 0.0) ? q_mean / a_conv : 0.0;
         const double hyd_depth =
             (fv::kernels::widthOfDepth(g, ctx.links.depth[uj]) > 0.0)
-                ? a_mean / fv::kernels::widthOfDepth(g, ctx.links.depth[uj])
+                ? a_conv / fv::kernels::widthOfDepth(g, ctx.links.depth[uj])
                 : 0.0;
         ctx.links.froude[uj] =
             (hyd_depth > 0.0)
@@ -1235,9 +1666,69 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
             // has a sensible head in the .out file.
             continue;
         }
-        const double depth = fv_state_.node_head[un] - fv_mesh_.node_invert[un];
+        double head = fv_state_.node_head[un];
+        // Storage-less clean junctions, ANY degree: publish the
+        // face-consistent stage — the same reconstruction the
+        // virtual-junction loop below uses — instead of the solver's own
+        // head, which sits ~S0·dx/2 above the face stage on steep COARSE
+        // chains and steps against the VJ rule in the plotted HGL
+        // (mechanism B).
+        //
+        // Originally this covered degree-2 pass-through junctions only,
+        // because that is the set the SOLVER splices. Measured on Example1
+        // under FLOW_ROUTING FV, that left two thirds of nodes publishing the
+        // raw head and standing up to 0.91 ft above their own adjacent cell
+        // at FV_MIN_CELLS 1 — falling ~first-order under refinement, so a
+        // datum term, not physics. Nodes inside the set never exceeded
+        // 0.0002 ft at any refinement, and the excess survives on nodes with
+        // NO lateral inflow, which rules out "head needed to drive the
+        // inflow out". See tests/manual/fv_node_stage/RESULTS.md.
+        //
+        // Culvert-inlet and flap-gate faces are excluded: those node heads
+        // are genuine headwaters that must not be reconstructed away. So are
+        // nodes carrying a structure flow or an unbled carry.
+        //
+        // REPORTING only, on purpose: changing the solver-internal head
+        // instead destabilized the lake-at-rest diameter-change case through
+        // the LTS-hold ghost channel (70 cfs standing oscillation from a
+        // 0.007 cfs residual).
+        // A dry cell's vote is bare ground, so only wet neighbours vote; the
+        // all-dry case keeps the solver's lowest-adjacent-bed contract.
+        if (impl && un < impl->node_publish_stage().size() &&
+            impl->node_publish_stage()[un]) {
+            const int b0 = fv_mesh_.node_face_ptr[un];
+            const int e0 = fv_mesh_.node_face_ptr[un + 1];
+            double eta = -1.0e30;
+            bool wet = false;
+            for (int p = b0; p < e0; ++p) {
+                const auto uf = static_cast(
+                    fv_mesh_.node_face_idx[static_cast(p)]);
+                const int c = (fv_mesh_.face_cl[uf] >= 0) ? fv_mesh_.face_cl[uf]
+                                                          : fv_mesh_.face_cr[uf];
+                if (c < 0) continue;
+                const auto uc = static_cast(c);
+                if (fv_state_.cell_h[uc] <= fv::kernels::kDryDepth) continue;
+                // A face perched ABOVE the node's own water surface is
+                // discharging as a free overfall (manual §8.6, ghost state
+                // 8-28: "a node standing below the face invert presents a dry
+                // ghost"). Its stage describes the pipe, not the node, and
+                // letting it vote reads the pipe's OFFSET as node depth --
+                // measured on Example1's J11, where conduit C2 enters 4 ft
+                // above the invert and an unguarded vote drove the reported
+                // average depth from 0.28 ft to 4.11 ft. The solver head is
+                // used only as the submergence THRESHOLD here, never as the
+                // published value, so its datum bias cannot leak back in.
+                if (fv_mesh_.face_zb[uf] > head) continue;
+                eta = std::max(eta, std::min(fv_mesh_.cell_zb[uc],
+                                             fv_mesh_.face_zb[uf]) +
+                                    fv_state_.cell_h[uc]);
+                wet = true;
+            }
+            if (wet) head = eta;
+        }
+        const double depth = head - fv_mesh_.node_invert[un];
         ctx.nodes.depth[un] = std::max(0.0, depth);
-        ctx.nodes.head[un]  = fv_state_.node_head[un];
+        ctx.nodes.head[un]  = head;
         // Volume through the ENGINE's own storage relation, not the solver's
         // flattened table, so the reported mass balance stays on one authority.
         //
@@ -1280,6 +1771,10 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
             ctx.nodes.outflow[un] = impl->node_outflow_volume()[un] / dt +
                                     ((lat < 0.0) ? -lat : 0.0) +
                                     ctx.nodes.losses[un];
+            // A lateral the solver credits straight into the incident cells
+            // (pass-through junction) is booked into node_out_ by the solver
+            // per substep (bookDivertedLateral), so the split above already
+            // carries it.
         }
     }
 
@@ -1298,12 +1793,35 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
         }
     }
 
+    // DUMMY links carry no section, so publishFv's conduit loop skipped them
+    // (their mesh row is unmeshed). Their discharge is the solver's own
+    // pass-through integral, published as the step mean for the same reason
+    // structure flow is. Depth and volume are zero by definition — legacy
+    // link_getYnorm returns 0 for a DUMMY xsect (link.c:798) — and have to be
+    // written rather than left at whatever the previous step held.
+    if (impl && dt > 0.0) {
+        const auto& dvol = impl->dummy_volume();
+        for (std::size_t s = 0; s < fv_mesh_.struct_link.size(); ++s) {
+            if (fv_mesh_.struct_is_dummy.empty() || !fv_mesh_.struct_is_dummy[s])
+                continue;
+            const auto uj = static_cast(fv_mesh_.struct_link[s]);
+            ctx.links.flow[uj]   = dvol[s] / dt;
+            ctx.links.depth[uj]  = 0.0;
+            ctx.links.volume[uj] = 0.0;
+        }
+    }
+
     // Non-conduit structures move water between node ledgers exactly as they do
     // under DW (DynamicWave.cpp:2723-2727): positive flow leaves node1 and
-    // arrives at node2.
+    // arrives at node2. DUMMY links are included — the pass-through really did
+    // take water out of the upstream node and put it in the downstream one, and
+    // omitting it leaves the mass balance charging an outfall for water that
+    // never reached it.
     for (int j = 0; j < ctx.n_links(); ++j) {
         const auto uj = static_cast(j);
-        if (ctx.links.type[uj] == LinkType::CONDUIT) continue;
+        if (ctx.links.type[uj] == LinkType::CONDUIT &&
+            ctx.links.xsect_shape[uj] != XsectShape::DUMMY)
+            continue;
         const int n1 = ctx.links.node1[uj];
         const int n2 = ctx.links.node2[uj];
         if (n1 < 0 || n2 < 0) continue;
@@ -1314,26 +1832,82 @@ void Router::publishFv(SimulationContext& ctx, double dt) {
         else         { ctx.nodes.inflow[u1]  -= q;  ctx.nodes.outflow[u2] -= q; }
     }
 
-    // Virtual junctions take the head of the cell on either side of their
-    // spliced face, which is what "the shared face state" means for reporting.
+    // Virtual junctions take the head at their spliced face, reconstructed
+    // from BOTH adjacent cells. The face→node association comes from the mesh
+    // (face_vj_node, recorded at build); re-deriving it by matching inverts
+    // collided whenever two virtual junctions shared a bit-identical invert,
+    // leaving the loser permanently unreported (depth 0 for the whole run).
+    //
+    // Each cell's WSE extrapolated to the face is bracketed by its two
+    // first-order models: flat water surface (cell_zb + h — exact when the
+    // reach is ponded or pressurized) and uniform depth along the bed
+    // (face_zb + h — exact in steep shallow flow, where the flat-surface
+    // form from the downhill cell reads below the invert and used to clamp
+    // the reported depth to zero). Taking the per-cell MIN of the bracket and
+    // the MAX across the two cells reproduces the correct head in all three
+    // regimes: the uphill cell's uniform-depth vote carries shallow flow, the
+    // downhill cell's flat-surface vote carries ponding and surcharge.
     for (int f = 0; f < fv_mesh_.n_faces(); ++f) {
         const auto uf = static_cast(f);
         if (!fv_mesh_.face_virtual[uf]) continue;
-        const int cl = fv_mesh_.face_cl[uf];
-        if (cl < 0) continue;
-        const auto ucl = static_cast(cl);
-        // Find the virtual node this face replaced by matching its invert.
-        for (int n = 0; n < ctx.n_nodes(); ++n) {
-            const auto un = static_cast(n);
-            if (fv_mesh_.node_kind[un] != fv::kNodeVirtual) continue;
-            if (std::fabs(fv_mesh_.node_invert[un] - fv_mesh_.face_zb[uf]) > 1.0e-9)
+        const int n = fv_mesh_.face_vj_node[uf];
+        if (n < 0) continue;
+        const auto un = static_cast(n);
+        const double zf = fv_mesh_.face_zb[uf];
+        // TPA (issue #156): a FLAGGED side carries a signed piezometric
+        // level cell_zb + cell_h with no zf floor — the station VJ is
+        // exactly where E3's sub-atmospheric trace is measured. Unflagged
+        // sides keep the legacy wetting convention bit-for-bit.
+        double eta = zf;                    // both sides dry ⇒ dry node
+        bool any_tpa = false;
+        double eta_tpa = 0.0;
+        for (const int c : {fv_mesh_.face_cl[uf], fv_mesh_.face_cr[uf]}) {
+            if (c < 0) continue;
+            const auto uc = static_cast(c);
+            if (!fv_state_.cell_tpa.empty() && fv_state_.cell_tpa[uc] != 0) {
+                const double e_t = fv_mesh_.cell_zb[uc] + fv_state_.cell_h[uc];
+                eta_tpa = any_tpa ? std::max(eta_tpa, e_t) : e_t;
+                any_tpa = true;
                 continue;
-            const double eta = fv_mesh_.cell_zb[ucl] + fv_state_.cell_h[ucl];
-            ctx.nodes.head[un]  = eta;
-            ctx.nodes.depth[un] = std::max(0.0, eta - fv_mesh_.node_invert[un]);
-            ctx.nodes.volume[un] = 0.0;   // zero-storage by construction
-            break;
+            }
+            eta = std::max(eta, std::min(fv_mesh_.cell_zb[uc], zf) +
+                                fv_state_.cell_h[uc]);
+        }
+        // A TPA side sets the head; an unflagged side only competes when it
+        // is genuinely wet above the floor (the bare zf floor must not mask
+        // a signed TPA level).
+        if (any_tpa) eta = (eta > zf) ? std::max(eta, eta_tpa) : eta_tpa;
+        ctx.nodes.head[un]  = eta;
+        ctx.nodes.depth[un] = std::max(0.0, eta - fv_mesh_.node_invert[un]);
+        ctx.nodes.volume[un] = 0.0;   // zero-storage by construction
+        ctx.nodes.overflow[un] = 0.0; // sealed: never floods
+
+        // Through-flow + lateral, so the node reports the same total inflow
+        // it would under DW (gatherConduitNodeFlows) and a lateral fed to it
+        // (plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md) shows in the Node
+        // Inflow Summary. The two conduits are the ones owning the spliced
+        // face's cells; their step-mean flows were published above. Positive
+        // conduit flow runs node1 → node2, so it enters this node when the
+        // node is the conduit's downstream end.
+        double q_in = 0.0, q_out = 0.0;
+        for (const int c : {fv_mesh_.face_cl[uf], fv_mesh_.face_cr[uf]}) {
+            if (c < 0) continue;
+            const auto ur = static_cast(
+                fv_mesh_.cell_conduit[static_cast(c)]);
+            if (ur >= fv_mesh_.conduit_link.size()) continue;
+            const auto uj = static_cast(fv_mesh_.conduit_link[ur]);
+            const double q = ctx.links.flow[uj];
+            const double toward = (ctx.links.node2[uj] == n) ? q : -q;
+            if (toward > 0.0) q_in += toward; else q_out -= toward;
         }
+        const double lat = ctx.nodes.lat_flow[un];
+        ctx.nodes.inflow[un]  = q_in  + ((lat > 0.0) ? lat : 0.0);
+        ctx.nodes.outflow[un] = q_out + ((lat < 0.0) ? -lat : 0.0);
+        // The virtual junction's lateral went straight into the two spliced
+        // cells (half each); the through-flow above does not carry it, so it
+        // is node outflow for the node's own ledger (same as the pass-through
+        // case in publishFv).
+        if (lat > 0.0) ctx.nodes.outflow[un] += lat;
     }
 }
 
diff --git a/src/engine/hydraulics/Routing.hpp b/src/engine/hydraulics/Routing.hpp
index 342386531..04df27122 100644
--- a/src/engine/hydraulics/Routing.hpp
+++ b/src/engine/hydraulics/Routing.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Routing.hpp
  * @brief Top-level routing dispatcher — KW / DW / Steady-state.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ROUTING_HPP
@@ -48,6 +64,19 @@ enum class RouteModel : int {
     FV        = 3    ///< Explicit conservative finite volume (Godunov)
 };
 
+/**
+ * @brief Apply legacy conduit_validate's Courant lengthening and the
+ *        conveyance re-derivation (beta, roughFactor, qFull, qMax) it implies.
+ *
+ * @details Legacy performs both during project validation — before
+ *          link_initState computes a q0 conduit's normal depth and before
+ *          flowrout_init seeds node depths from it — so the initial state must
+ *          see the lengthened beta. Idempotent: every input is a stored,
+ *          unmodified quantity, so SWMMEngine may call it ahead of the
+ *          initial-state loops and Router::init again afterwards.
+ */
+void applyConduitLengthening(SimulationContext& ctx, RouteModel model);
+
 // ============================================================================
 // Routing orchestrator
 // ============================================================================
@@ -103,11 +132,19 @@ class Router {
     bool hasCycle() const { return cycle_detected_; }
 
     /// Set the DWSolver OpenMP thread count (delegates to DWSolver::setNumThreads).
-    void setDWNumThreads(int n) { dw_solver_.setNumThreads(n); }
+    void setDWNumThreads(int n, std::vector* warnings = nullptr) {
+        dw_solver_.setNumThreads(n, warnings);
+    }
 
     /// Access the DW solver (for non-conduit node state scatter).
     dynwave::DWSolver& dwSolver() { return dw_solver_; }
 
+    /// Supply the structure solver used to evaluate pump/orifice/weir/outlet
+    /// discharge. DYNWAVE/FV get theirs through the non_conduit_fn callback,
+    /// but KINWAVE/STEADY evaluate structures inline (legacy getLinkInflow),
+    /// so they need the solver itself. Must be set before the first step().
+    void setStructureSolver(hydstruct::StructureSolver* s) { structures_ = s; }
+
     /// Whether the most recent step() converged. DYNWAVE returns the solver's
     /// real final Picard flag; other models always converge (legacy only tracks
     /// dynwave non-convergence). FV has no convergence loop at all — that is a
@@ -136,6 +173,17 @@ class Router {
     RouteModel model_ = RouteModel::DYNWAVE;
     XSectGroups groups_;
 
+    /// Non-owning; set by SWMMEngine. Null in standalone Router unit tests,
+    /// where structures then carry no flow.
+    hydstruct::StructureSolver* structures_ = nullptr;
+
+    /// Per-node "already converged this step" flag for storage units under
+    /// STEADY (the KW solver keeps its own).
+    std::vector steady_storage_updated_;
+    /// Per-link end-of-step flow depth under STEADY routing (uniform along
+    /// the conduit); consumed by kinwave::finishRouting's node-depth raises.
+    std::vector steady_y_;
+
     // --- Explicit finite-volume solver (FLOW_ROUTING FV) -------------------
     // The mesh and state are owned here, not by the solver, exactly as
     // SurfaceRouter2D owns MeshData/SurfaceStateData: the solver is swappable
@@ -150,6 +198,12 @@ class Router {
     // Per-step forcing buffers, allocated once at init.
     std::vector fv_lateral_, fv_fixed_head_, fv_struct_flow_, fv_cond_loss_;
 
+    /// Per-link cap on a DUMMY link's pass-through discharge: the control
+    /// setting and FLOW_LIMIT, which the solver cannot see. Negative means
+    /// unlimited; only DUMMY entries are ever read. Refreshed with the
+    /// structures, because a control rule can close the link mid-step.
+    std::vector fv_link_q_cap_;
+
     /// Time integral of each structure's discharge over the routing step
     /// (ft³), and the elapsed time the last segment started at. Under
     /// per-substep coupling the discharge MOVES within the step, so the
diff --git a/src/engine/hydraulics/Street.cpp b/src/engine/hydraulics/Street.cpp
index 01b3c446e..c8660dfef 100644
--- a/src/engine/hydraulics/Street.cpp
+++ b/src/engine/hydraulics/Street.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Street.cpp
  * @brief Street cross-section — numerically identical to legacy street.c.
@@ -5,96 +21,84 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Street.hpp"
 
+#include 
+
 namespace openswmm {
 namespace street {
 
 void buildTransect(const StreetParams& sp, transect::TransectData& td) {
+    // Literal port of legacy transect_createStreetTransect (transect.c:625).
+    //
+    //   Point 0 = top of backing    Point 3 = bottom of depressed gutter
+    //   Point 1 = top of curb       Point 4 = top of depressed gutter (crown)
+    //   Point 2 = bottom of curb    Point 5 = street crown wall
+    //
+    // The two elevations v6 used to get wrong:
+    //   y3 = Hdep + Sx*Wg   — the gutter's outer edge is the depression PLUS
+    //                         the road cross-slope over the gutter width,
+    //   y4 = y3 + Sx*(W-Wg) — and the crown builds on y3, not on Hdep.
+    // Omitting Sx*Wg dropped the whole roadway 0.04 ft on a 2 %/2 ft gutter,
+    // which is a 24 % area error at a 0.046 ft gutter flow depth (the STREET
+    // inlet decks diverged from period 0).
     td.stations.clear();
     td.elevations.clear();
 
-    double y_gutter = sp.gutter_depression;
-    double y_crown  = y_gutter + sp.slope * (sp.width - sp.gutter_width);
-
-    if (sp.sides == 2) {
-        // Full street: left backing → left curb → left gutter → crown → right gutter → right curb → right backing
-        double x = 0.0;
-        double y_max = sp.curb_height + y_gutter;
-
-        // Left backing
-        if (sp.back_width > 0.0) {
-            td.stations.push_back(x);
-            td.elevations.push_back(y_max + sp.back_slope * sp.back_width);
-            x += sp.back_width;
-        }
-
-        // Left curb top
-        td.stations.push_back(x);
-        td.elevations.push_back(y_max);
-
-        // Left curb bottom
-        td.stations.push_back(x);
-        td.elevations.push_back(0.0);
-
-        // Left gutter bottom
-        x += sp.gutter_width;
-        td.stations.push_back(x);
-        td.elevations.push_back(y_gutter);
-
-        // Crown
-        x += (sp.width - sp.gutter_width);
-        td.stations.push_back(x);
-        td.elevations.push_back(y_crown);
-
-        // Right gutter bottom
-        x += (sp.width - sp.gutter_width);
-        td.stations.push_back(x);
-        td.elevations.push_back(y_gutter);
-
-        // Right curb bottom
-        x += sp.gutter_width;
-        td.stations.push_back(x);
-        td.elevations.push_back(0.0);
-
-        // Right curb top
+    const double w1 = sp.back_width;                   // backing
+    const double w2 = sp.gutter_width;                 // depressed gutter
+    const double w3 = sp.width;                        // curb to crown
+    const double w4 = w3 - w2;                         // road, less the gutter
+    const double y3 = sp.gutter_depression + sp.slope * w2;
+    const double y1 = sp.curb_height + sp.gutter_depression;
+    const double y4 = y3 + sp.slope * w4;
+    // The backing's top is raised to the crown elevation when the crown is
+    // higher (legacy `ymax = MAX(ymax, y4)` before Elev[0] is assigned).
+    const double ymax = std::max(sp.back_slope * w1 + y1, y4);
+
+    auto pt = [&](double x, double y) {
         td.stations.push_back(x);
-        td.elevations.push_back(y_max);
-
-        // Right backing
-        if (sp.back_width > 0.0) {
-            x += sp.back_width;
-            td.stations.push_back(x);
-            td.elevations.push_back(y_max + sp.back_slope * sp.back_width);
-        }
+        td.elevations.push_back(y);
+    };
+
+    pt(0.0,      ymax);   // 0: top of backing
+    pt(w1,       y1);     // 1: top of curb
+    pt(w1,       0.0);    // 2: bottom of curb (the thalweg)
+    pt(w1 + w2,  y3);     // 3: outer edge of the depressed gutter
+    pt(w1 + w3,  y4);     // 4: crown
+
+    if (sp.sides == 1) {
+        // A half street is closed by a vertical wall at the crown.
+        pt(w1 + w3, ymax);
     } else {
-        // Half street: curb → gutter → crown
-        double x = 0.0;
-        double y_max = sp.curb_height + y_gutter;
-
-        td.stations.push_back(x);
-        td.elevations.push_back(y_max);
-
-        td.stations.push_back(x);
-        td.elevations.push_back(0.0);
-
-        x += sp.gutter_width;
-        td.stations.push_back(x);
-        td.elevations.push_back(y_gutter);
-
-        x += (sp.width - sp.gutter_width);
-        td.stations.push_back(x);
-        td.elevations.push_back(y_crown);
+        // The right side mirrors the left.
+        pt(w1 + w3 + w4,           y3);
+        pt(w1 + w3 + w4 + w2,      0.0);
+        pt(w1 + w3 + w4 + w2,      y1);
+        pt(w1 + w3 + w4 + w2 + w1, ymax);
     }
 
+    // Manning's n and the bank stations (legacy: a street with no backing is
+    // ALL main channel, keyed on backWidth — not on whether nBack was given).
     td.n_channel = sp.roughness;
-    td.n_left = sp.back_roughness > 0.0 ? sp.back_roughness : sp.roughness;
-    td.n_right = td.n_left;
+    if (sp.back_width == 0.0) {
+        td.n_left  = sp.roughness;
+        td.n_right = sp.roughness;
+        td.x_left_bank  = td.stations.front();
+        td.x_right_bank = td.stations.back();
+    } else {
+        td.n_left  = sp.back_roughness;
+        td.n_right = sp.back_roughness;
+        td.x_left_bank  = td.stations[1];
+        td.x_right_bank = (sp.sides == 2)
+                        ? td.stations[td.stations.size() - 2]
+                        : td.stations.back();
+    }
 
-    transect::buildTables(td);
+    transect::buildTables(td, /*add_end_walls=*/false);
 }
 
 } // namespace street
diff --git a/src/engine/hydraulics/Street.hpp b/src/engine/hydraulics/Street.hpp
index 6e319aefe..66be311e5 100644
--- a/src/engine/hydraulics/Street.hpp
+++ b/src/engine/hydraulics/Street.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Street.hpp
  * @brief Street cross-section geometry — gutter + road crown + backing.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_STREET_HPP
diff --git a/src/engine/hydraulics/TimestepController.cpp b/src/engine/hydraulics/TimestepController.cpp
index f813ab06d..a9bf2f846 100644
--- a/src/engine/hydraulics/TimestepController.cpp
+++ b/src/engine/hydraulics/TimestepController.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TimestepController.cpp
  * @brief Explicit next-timestep computation — implementation.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TimestepController.hpp"
diff --git a/src/engine/hydraulics/TimestepController.hpp b/src/engine/hydraulics/TimestepController.hpp
index ec826827f..c27704131 100644
--- a/src/engine/hydraulics/TimestepController.hpp
+++ b/src/engine/hydraulics/TimestepController.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TimestepController.hpp
  * @brief Explicit next-timestep computation for the new engine.
@@ -19,13 +35,17 @@
  * REPORT_START are skipped by the writer but the grid still advances
  * (output.c:481).
  *
- * ### Key design decision (R18) — superseded for parity
+ * ### Key design decision (R18) — resolved for parity
  *
  * The original refactored design shortened dt so the clock lands exactly on
  * report boundaries (no interpolation). Legacy instead free-steps and
- * interpolates results to the report instant (output.c:650/682). The clamp
- * is retained temporarily and is removed by the A2 reporting-parity work in
- * favor of legacy-identical interpolation.
+ * interpolates results to the report instant (output.c:650/682). That clamp
+ * was REMOVED by the A2 reporting-parity work: compute_next never aligns to
+ * the report grid, and postOutputSnapshot performs the legacy-identical
+ * interpolation. The only step alignments that remain are legacy-real: the
+ * total-duration clamp (swmm5.c:975-980, 1 ms floor) and the RULE_STEP
+ * control grid (routing.c:196-204, via ctx.dt_controls_remaining set by
+ * SWMMEngine::step from the absolute rule clock).
  *
  * ### Integration with IO thread (Phase 5)
  *
@@ -54,7 +74,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TIMESTEP_CONTROLLER_HPP
diff --git a/src/engine/hydraulics/TopoSort.cpp b/src/engine/hydraulics/TopoSort.cpp
index 39bfc69ae..c5faeea47 100644
--- a/src/engine/hydraulics/TopoSort.cpp
+++ b/src/engine/hydraulics/TopoSort.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TopoSort.cpp
  * @brief Topological sort — Kahn's algorithm, numerically identical to legacy.
@@ -5,18 +21,20 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TopoSort.hpp"
 #include 
+#include 
 
 namespace openswmm {
 namespace toposort {
 
 int sortLinks(const int* node1, const int* node2,
               int n_links, int n_nodes,
-              std::vector& sorted_links) {
+              std::vector& sorted_links,
+              const int* divert_link) {
     sorted_links.clear();
     sorted_links.reserve(static_cast(n_links));
 
@@ -47,6 +65,23 @@ int sortLinks(const int* node1, const int* node2,
         }
     }
 
+    // legacy adjustAdjList (toposort.c:191-217): at a DIVIDER with exactly two
+    // outgoing links, put the NON-diversion link first. divider_getOutflow
+    // hands the diversion link `qIn - Node.outflow` — the remainder after the
+    // other link has taken its share — so evaluating the diversion link first
+    // sends the node's entire inflow down both (1710-2014-20year-r3's J23
+    // doubled its outflow at routing step 127).
+    if (divert_link != nullptr) {
+        for (int i = 0; i < n_nodes; ++i) {
+            const auto ui = static_cast(i);
+            if (divert_link[ui] < 0) continue;
+            if (degree[ui] != 2) continue;
+            const auto m = static_cast(start_pos[ui]);
+            if (adj_list[m] == divert_link[ui])
+                std::swap(adj_list[m], adj_list[m + 1]);
+        }
+    }
+
     // Compute in-degree
     for (int j = 0; j < n_links; ++j) {
         int n2 = node2[j];
diff --git a/src/engine/hydraulics/TopoSort.hpp b/src/engine/hydraulics/TopoSort.hpp
index 00f66dc7d..5e4679ac0 100644
--- a/src/engine/hydraulics/TopoSort.hpp
+++ b/src/engine/hydraulics/TopoSort.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TopoSort.hpp
  * @brief Topological sort of network links for KW/steady-state routing.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_TOPOSORT_HPP
@@ -38,11 +54,19 @@ namespace toposort {
  * @param n_links      Number of links.
  * @param n_nodes      Number of nodes.
  * @param sorted_links [out] Topologically sorted link indices.
+ * @param divert_link  [in] Optional, per node: the index of that node's
+ *        DIVERSION link when the node is a 2-outlet divider, else -1. Legacy
+ *        adjustAdjList (toposort.c:191-217) swaps a divider's two outgoing
+ *        links so the NON-diversion one is routed first — divider_getOutflow
+ *        gives the diversion link `qIn - Node.outflow`, i.e. only what the
+ *        other link left behind, so the wrong order sends the node's whole
+ *        inflow down BOTH links. Pass nullptr to skip the adjustment.
  * @returns Number of sorted links (< n_links indicates cycle).
  */
 int sortLinks(const int* node1, const int* node2,
               int n_links, int n_nodes,
-              std::vector& sorted_links);
+              std::vector& sorted_links,
+              const int* divert_link = nullptr);
 
 } // namespace toposort
 } // namespace openswmm
diff --git a/src/engine/hydraulics/Transect.cpp b/src/engine/hydraulics/Transect.cpp
index ca56ef12b..f63672da9 100644
--- a/src/engine/hydraulics/Transect.cpp
+++ b/src/engine/hydraulics/Transect.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Transect.cpp
  * @brief Irregular transect — numerically identical to legacy transect.c.
@@ -5,10 +21,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Transect.hpp"
+#include "../data/InfraData.hpp"
 #include 
 #include 
 #include 
@@ -29,7 +46,7 @@ static constexpr double PHI = 1.486;
 // too SMALL on overbank / multi-roughness sections (e.g. user5 T171: R=2.46 vs
 // legacy 3.22 at full depth), over-stating friction and collapsing the initial
 // flow on q0 transect conduits (extran8a). See src/legacy/engine/transect.c.
-void buildTables(TransectData& td) {
+void buildTables(TransectData& td, bool add_end_walls) {
     int n_in = static_cast(td.stations.size());
     if (n_in < 2 || static_cast(td.elevations.size()) != n_in) return;
 
@@ -54,16 +71,39 @@ void buildTables(TransectData& td) {
 
     // add vertical end-walls reaching full height (legacy transect_validate)
     int N = n_in;
-    std::vector X(static_cast(N) + 2);
-    std::vector Y(static_cast(N) + 2);
-    X[0] = td.stations[0];              Y[0] = ymax;
-    for (int i = 0; i < N; ++i) {
-        X[static_cast(i + 1)] = td.stations[static_cast(i)];
-        Y[static_cast(i + 1)] = td.elevations[static_cast(i)];
+    // N+3, not N+2: getFlow() below reads X[k+1] at k == Nsta == N+1 when the
+    // right-bank branch is taken, which is one past the last written element.
+    // Legacy indexes fixed `static double Station[MAXSTATION+1]` arrays, so the
+    // same read lands on zero-initialised slack rather than out of bounds — the
+    // trailing element here is value-initialised to 0.0 to match it.
+    //
+    // Reachable only when accumulated `y` overshoots ymax by a rounding step,
+    // so the last end-wall segment is not skipped by `ylo >= y`. That made it a
+    // silent over-read on Linux and an abort on the Windows debug STL
+    // ("vector subscript out of range", exit 0xc0000409) — dependent on the
+    // deck: 7-station flood-plain transects trip it, 3-station V-notches do not.
+    std::vector X(static_cast(N) + 3);
+    std::vector Y(static_cast(N) + 3);
+    int Nsta;
+    if (add_end_walls) {
+        X[0] = td.stations[0];              Y[0] = ymax;
+        for (int i = 0; i < N; ++i) {
+            X[static_cast(i + 1)] = td.stations[static_cast(i)];
+            Y[static_cast(i + 1)] = td.elevations[static_cast(i)];
+        }
+        X[static_cast(N + 1)] = td.stations[static_cast(N - 1)];
+        Y[static_cast(N + 1)] = ymax;
+        Nsta = N + 1;
+    } else {
+        // A street's points already include its end walls, so they are laid
+        // out exactly as legacy's Station[0..Nstations] (transect.c
+        // createStreetTransect -> createTables) with Nstations = N - 1.
+        for (int i = 0; i < N; ++i) {
+            X[static_cast(i)] = td.stations[static_cast(i)];
+            Y[static_cast(i)] = td.elevations[static_cast(i)];
+        }
+        Nsta = N - 1;
     }
-    X[static_cast(N + 1)] = td.stations[static_cast(N - 1)];
-    Y[static_cast(N + 1)] = ymax;
-    const int Nsta = N + 1;
 
     auto getFlow = [&](int k, double a, double wp, bool findFlow) -> double {
         if (!findFlow) {
@@ -178,6 +218,11 @@ void buildTables(TransectData& td) {
     // width at zero depth = width at first increment (legacy createTables:309)
     td.width_tbl[0] = td.width_tbl[1];
 
+    // Bucket map for the getYofA inversion (plan XSECT_LOOKUP_ACCEL A1) — a
+    // search accelerator only; it returns the same bracketing index bisection
+    // would, so the interpolated depth is unchanged.
+    xsect::build_invlookup_lut(td.area_lut, td.area_tbl, N_TRANSECT_TBL);
+
     // --- A3 transect-table parity dump (env-gated), mirrors legacy transect.c
     if (const char* p = std::getenv("SWMM_TRACE_TRANSECT")) {
         if (*p) {
@@ -375,6 +420,42 @@ void buildCustomTables(TransectData& td, double y_full,
     td.w_max  = wMax * y_full;
     td.a_full = aFull * y_full * y_full;
     td.r_full = rFull * y_full;
+
+    xsect::build_invlookup_lut(td.area_lut, td.area_tbl, N_TRANSECT_TBL);
+}
+
+bool buildFromStore(const TransectStore& ts, int index, double ucf_length,
+                    TransectData& td) {
+    const auto ut = static_cast(index);
+    td.name      = ts.names[ut];
+    td.n_left    = ts.n_left[ut];
+    td.n_right   = ts.n_right[ut];
+    td.n_channel = ts.n_channel[ut];
+    if (td.n_channel <= 0.0) return false;
+    td.stations   = ts.stations[ut];
+    td.elevations = ts.elevations[ut];
+    td.length_factor = ts.length_factor[ut];
+    // PARITY: legacy transect setParams/addStation (transect.c:360-410)
+    // transform the raw [TRANSECTS] GR data BEFORE building the tables:
+    //   Station = x * Xfactor / UCF(LENGTH)          (mult, then divide)
+    //   Elev    = (y + Yfactor) / UCF(LENGTH),  Yfactor = x9 / UCF
+    //   Xbank   = (xbank / UCF) * Xfactor            (divide, then mult)
+    // The elevation OFFSET (x9, e.g. 799/798 in extran8a) is the load-
+    // bearing part: legacy builds every slice area/width/hrad at the
+    // real bed elevation (~800 ft), so `y - yhi` rounds at that
+    // magnitude. Building on the raw ~0-ft elevations rounds
+    // differently (~1e-13 per entry) and breaks bit-parity even though
+    // the geometry is offset-invariant in exact arithmetic. Applied to
+    // the td COPY only, so [TRANSECTS] round-trips the raw GR values.
+    double xFactor = ts.x_factor[ut];      // parse-time 0→1 default
+    if (xFactor == 0.0) xFactor = 1.0;
+    const double yFactor = ts.y_factor[ut] / ucf_length;   // x9 / UCF
+    for (auto& s : td.stations)   s = s * xFactor / ucf_length;
+    for (auto& e : td.elevations) e = (e + yFactor) / ucf_length;
+    td.x_left_bank  = (ts.x_left_bank[ut]  / ucf_length) * xFactor;
+    td.x_right_bank = (ts.x_right_bank[ut] / ucf_length) * xFactor;
+    buildTables(td);
+    return true;
 }
 
 } // namespace transect
diff --git a/src/engine/hydraulics/Transect.hpp b/src/engine/hydraulics/Transect.hpp
index 8c0d763fc..bfeb5d0e1 100644
--- a/src/engine/hydraulics/Transect.hpp
+++ b/src/engine/hydraulics/Transect.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Transect.hpp
  * @brief Irregular transect cross-section geometry (HEC-2 style).
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_TRANSECT_HPP
@@ -21,8 +37,12 @@
 #include 
 #include 
 
+#include "XSectLookup.hpp"
+
 namespace openswmm {
 
+struct TransectStore;  // engine/data/InfraData.hpp
+
 namespace transect {
 
 constexpr int N_TRANSECT_TBL = 51;
@@ -55,6 +75,11 @@ struct TransectData {
     double area_tbl[N_TRANSECT_TBL]  = {};
     double hrad_tbl[N_TRANSECT_TBL]  = {};
     double width_tbl[N_TRANSECT_TBL] = {};
+
+    /// Bucket map over `area_tbl`, used by getYofA's invLookup (plan
+    /// XSECT_LOOKUP_ACCEL A1). Rebuilt by the two table builders below; stays
+    /// disabled (and callers bisect as before) if either bails out early.
+    xsect::LocateLut area_lut;
 };
 
 /**
@@ -66,8 +91,16 @@ struct TransectData {
  *
  * @param td  [in/out] TransectData with stations/elevations filled.
  *            On output, tables and full-depth properties are set.
+ * @param add_end_walls  Close the section with vertical walls up to the
+ *            highest station before tabulating, as legacy transect_validate
+ *            does for a [TRANSECTS] section. A STREET section is already
+ *            closed by its own points (transect_createStreetTransect calls
+ *            createTables directly), and adding walls there shifts every
+ *            station index — which moves the `k == Nstations - 1` split in
+ *            getFlow and so changes the composite-roughness flow the hyd.
+ *            radius table is solved from. Pass false for streets.
  */
-void buildTables(TransectData& td);
+void buildTables(TransectData& td, bool add_end_walls = true);
 
 /**
  * @brief Build tabulated geometry from a CUSTOM shape curve.
@@ -85,6 +118,28 @@ void buildTables(TransectData& td);
 void buildCustomTables(TransectData& td, double y_full,
                        const double* curve_x, const double* curve_y, int n_pts);
 
+/**
+ * @brief Build one transect's geometry tables from the raw [TRANSECTS] store.
+ *
+ * @details Copies the store entry into @p td, applies the legacy parse-time
+ *          transforms (Station = x·Xfactor/UCF; Elev = (y + Yfactor)/UCF with
+ *          Yfactor = y_factor/UCF; banks = (x/UCF)·Xfactor — see
+ *          transect.c::setParams/addStation) to the COPY only, then calls
+ *          buildTables(). The store itself stays raw/display so [TRANSECTS]
+ *          round-trips losslessly. Shared by PostParseResolver (per-store
+ *          resolve pass) and swmm_link_set_xsect (IRREGULAR assignment of a
+ *          transect added after open) — the two must stay bit-identical.
+ *
+ * @param ts          Raw transect store.
+ * @param index       Store row to build.
+ * @param ucf_length  UCF(LENGTH) for the model's unit system.
+ * @param td          [out] Built tables.
+ * @return false when the entry has no valid channel Manning's n (caller
+ *         reports the error); true on success.
+ */
+bool buildFromStore(const TransectStore& ts, int index, double ucf_length,
+                    TransectData& td);
+
 } // namespace transect
 } // namespace openswmm
 
diff --git a/src/engine/hydraulics/XSectBatch.cpp b/src/engine/hydraulics/XSectBatch.cpp
index b65356910..35b75e7b4 100644
--- a/src/engine/hydraulics/XSectBatch.cpp
+++ b/src/engine/hydraulics/XSectBatch.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file XSectBatch.cpp
  * @brief Data-oriented batch cross-section geometry — shape-grouped SoA.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "XSectBatch.hpp"
@@ -36,6 +52,8 @@
 #include 
 #include 
 #include 
+#include 
+#include 
 
 #if defined(SWMM_USE_OPENMP)
 #include 
@@ -133,6 +151,68 @@ void XSectGroups::build(const XSectParams* params, int n_links) {
     }
 }
 
+namespace {
+
+/// Reorder a transect-backed shape group so links sharing a transect table sit
+/// together (plan XSECT_LOOKUP_ACCEL §4 item A3).
+///
+/// A model's IRREGULAR links are grouped by SHAPE, so a group's elements chase
+/// their per-link table pointers in whatever order the links appear in the
+/// input — with a few hundred transects and 51-row × 3 tables each (~1.2 kB per
+/// transect), consecutive elements evict each other's tables from L1. Sorting
+/// by transect index turns that into a run per transect.
+///
+/// This is a pure permutation of the group's element order. Every batch kernel
+/// is elementwise, results scatter through `link_idx`, and the bypass-mask
+/// packed mirrors already reposition elements arbitrarily — so the computed
+/// values are unchanged, position for position. The sort key is the transect
+/// index (not the table address) and ties keep the original order, so the
+/// permutation is reproducible run to run and platform to platform.
+void sortGroupByTransect(ShapeGroup& g, const SimulationContext& ctx) {
+    const int count = g.count;
+    if (count < 2 || g.area_tables.empty()) return;
+
+    std::vector order(static_cast(count));
+    for (int k = 0; k < count; ++k) order[static_cast(k)] = k;
+
+    const auto curve_of = [&](int k) {
+        const auto uj = static_cast(g.link_idx[static_cast(k)]);
+        return ctx.links.xsect_curve[uj];
+    };
+    std::stable_sort(order.begin(), order.end(),
+                     [&](int lhs, int rhs) { return curve_of(lhs) < curve_of(rhs); });
+
+    bool already_sorted = true;
+    for (int k = 0; k < count; ++k)
+        if (order[static_cast(k)] != k) { already_sorted = false; break; }
+    if (already_sorted) return;
+
+    const auto permute = [&order, count](auto& vec) {
+        if (static_cast(vec.size()) != count) return;
+        std::decay_t tmp(vec.size());
+        for (int k = 0; k < count; ++k)
+            tmp[static_cast(k)] =
+                vec[static_cast(order[static_cast(k)])];
+        vec.swap(tmp);
+    };
+    permute(g.link_idx);
+    permute(g.y_full);
+    permute(g.inv_y_full);
+    permute(g.a_full);
+    permute(g.r_full);
+    permute(g.s_full);
+    permute(g.w_max);
+    permute(g.y_bot);
+    permute(g.a_bot);
+    permute(g.s_bot);
+    permute(g.r_bot);
+    permute(g.area_tables);
+    permute(g.hrad_tables);
+    permute(g.width_tables);
+}
+
+}  // namespace
+
 void XSectGroups::attachTransectTables(const SimulationContext& ctx) {
     // The packed mirrors must include the per-link table pointers; force a
     // lazy re-init so they pick up the arrays attached below.
@@ -156,6 +236,15 @@ void XSectGroups::attachTransectTables(const SimulationContext& ctx) {
 
             int ci = ctx.links.xsect_curve[uj];
             if (ci >= 0 && static_cast(ci) < ctx.transect_tables.size()) {
+                // These are raw pointers INTO a vector element. They stay
+                // valid only because every API that can append to
+                // ctx.transect_tables is gated to BUILDING/OPENED
+                // (CHECK_GEOMETRY / CHECK_TOPOLOGY), so nothing can grow the
+                // store once this capture has happened. Pinned by
+                // test_engine_transect_table_stability. Relaxing that gate
+                // requires giving transect_tables stable element addresses
+                // first — std::deque is a drop-in, nothing indexes it
+                // contiguously.
                 const auto& td = ctx.transect_tables[static_cast(ci)];
                 g.area_tables[uk]  = td.area_tbl;
                 g.hrad_tables[uk]  = td.hrad_tbl;
@@ -168,6 +257,8 @@ void XSectGroups::attachTransectTables(const SimulationContext& ctx) {
                 g.w_max[uk]  = td.w_max;
             }
         }
+
+        sortGroupByTransect(g, ctx);
     }
 }
 
@@ -290,13 +381,109 @@ void area_inv_tabulated(
     const double* OPENSWMM_RESTRICT a_full,
     const double* table,
     int            table_size,
+    const xsect::LocateLut* lut,
     double*       OPENSWMM_RESTRICT area,
     int count
 ) {
     // Shapes whose area table is Y vs A (inverted) use invLookup. Legacy getAofY:
     // a_full * invLookup(y/yFull); norm_x gives x==0 at y<=0 (invLookup(0)==0).
     for (int k = 0; k < count; ++k)
-        area[k] = a_full[k] * xsect::invLookup(norm_x(depth[k], nrm[k]), table, table_size);
+        area[k] = a_full[k] * xsect::invLookup(norm_x(depth[k], nrm[k]), table,
+                                               table_size, lut);
+}
+
+/// Fused per-link tabulated pair — the tabulated analog of
+/// area_hydrad_circular (plan XSECT_LOOKUP_ACCEL §4 item A2).
+///
+/// A transect's area and hydraulic-radius tables share one 51-row normalized
+/// depth grid, so evaluating both at the same depth repeats the whole index
+/// computation: the normalization, the `x / delta` truncation, the segment
+/// origin and the interpolation weights. This does that work once and
+/// interpolates both tables from it, and gathers each link's two table
+/// pointers in one visit instead of two.
+///
+/// Bit-identical to two `perlink_tabulated` passes by construction: every
+/// arithmetic op is the DIVIDE form of `xsect::lookup_exact` in legacy's
+/// grouping (no reciprocal, no FMA), the quadratic refinement and the negative
+/// clamp are applied per table exactly as `lookup_exact` applies them, and the
+/// `i >= n-1` early-out returns the last row unclamped, as there.
+///
+/// (The top width cannot join this pass: the dynamic-wave loop computes widths
+/// in STEP B from crown-capped depths and areas in STEP D from depths STEP C
+/// has since modified — different inputs, so there is no shared index to
+/// share. Fusing them would change the algorithm, not just its cost.)
+void perlink_tabulated_pair(
+    const double* OPENSWMM_RESTRICT depth,
+    const double* OPENSWMM_RESTRICT nrm,
+    const double* OPENSWMM_RESTRICT scale_a,     // a_full
+    const double* OPENSWMM_RESTRICT scale_b,     // r_full
+    const double* const* tables_a,               // per-link area tables
+    const double* const* tables_b,               // per-link hyd-rad tables
+    int            table_size,
+    double*       OPENSWMM_RESTRICT out_a,
+    double*       OPENSWMM_RESTRICT out_b,
+    int count
+) {
+    const int n = table_size;
+#ifdef SWMM_XSECT_FAST_LOOKUP
+    const double inv_delta = static_cast(n - 1);   // exact integer
+    const double delta     = 1.0 / inv_delta;
+#else
+    const double delta = 1.0 / static_cast(n - 1);
+    const double dd    = delta * delta;
+#endif
+
+    for (int k = 0; k < count; ++k) {
+        const double* ta = tables_a[k];
+        const double* tb = tables_b[k];
+        if (!ta || !tb) {                       // degenerate link — no fusion to do
+            out_a[k] = ta ? scale_a[k] * norm_lookup(depth[k], nrm[k], ta, n) : 0.0;
+            out_b[k] = tb ? scale_b[k] * norm_lookup(depth[k], nrm[k], tb, n) : 0.0;
+            continue;
+        }
+
+        const double x = norm_x(depth[k], nrm[k]);
+#ifdef SWMM_XSECT_FAST_LOOKUP
+        const int i = static_cast(x * inv_delta);
+#else
+        const int i = static_cast(x / delta);
+#endif
+        if (i >= n - 1) {                       // lookup_exact's early-out (no clamp)
+            out_a[k] = scale_a[k] * ta[n - 1];
+            out_b[k] = scale_b[k] * tb[n - 1];
+            continue;
+        }
+
+        const double x0 = i * delta;
+#ifdef SWMM_XSECT_FAST_LOOKUP
+        double a = ta[i] + (x - x0) * (ta[i + 1] - ta[i]) * inv_delta;
+        double b = tb[i] + (x - x0) * (tb[i + 1] - tb[i]) * inv_delta;
+        if (i < 2) {
+            const double x1 = (static_cast(i) + 1.0) * delta;
+            const double q  = (x - x0) * (x - x1) * (inv_delta * inv_delta);
+            const double a2 = a + q * (ta[i] / 2.0 - ta[i + 1] + ta[i + 2] / 2.0);
+            const double b2 = b + q * (tb[i] / 2.0 - tb[i + 1] + tb[i + 2] / 2.0);
+            if (a2 > 0.0) a = a2;
+            if (b2 > 0.0) b = b2;
+        }
+#else
+        double a = ta[i] + (x - x0) * (ta[i + 1] - ta[i]) / delta;
+        double b = tb[i] + (x - x0) * (tb[i + 1] - tb[i]) / delta;
+        if (i < 2) {                            // quadratic refinement (legacy lookup)
+            const double x1 = (static_cast(i) + 1.0) * delta;
+            const double a2 = a + (x - x0) * (x - x1) / dd *
+                                  (ta[i] / 2.0 - ta[i + 1] + ta[i + 2] / 2.0);
+            const double b2 = b + (x - x0) * (x - x1) / dd *
+                                  (tb[i] / 2.0 - tb[i + 1] + tb[i + 2] / 2.0);
+            if (a2 > 0.0) a = a2;
+            if (b2 > 0.0) b = b2;
+        }
+#endif
+        if (a < 0.0) a = 0.0;
+        if (b < 0.0) b = 0.0;
+        out_a[k] = scale_a[k] * a;
+        out_b[k] = scale_b[k] * b;
+    }
 }
 
 /// Per-link tabulated lookup (for IRREGULAR shapes where each link has its own table).
@@ -714,6 +901,20 @@ TableRef area_inv_table_for(XSectShape shape) {
     }
 }
 
+/// The bucket map matching area_inv_table_for's table (plan A1). Reads the
+/// host-bound block so the batch path and the per-element accessor accelerate
+/// the same searches with the same maps.
+const xsect::LocateLut* area_inv_lut_for(XSectShape shape) {
+    using xsect::LutId;
+    switch (shape) {
+        case XSectShape::GOTHIC:         return xsect::hostTables().lut(LutId::Y_Gothic);
+        case XSectShape::CATENARY:       return xsect::hostTables().lut(LutId::Y_Catenary);
+        case XSectShape::SEMIELLIPTICAL: return xsect::hostTables().lut(LutId::Y_SemiEllip);
+        case XSectShape::SEMICIRCULAR:   return xsect::hostTables().lut(LutId::Y_SemiCirc);
+        default: return nullptr;
+    }
+}
+
 TableRef hydrad_table_for(XSectShape shape) {
     using namespace xsect_tables;
     switch (shape) {
@@ -808,7 +1009,7 @@ static void apply_area_kernel(const ShapeGroup& g,
                 if (inv.data) {
                     xsect_batch::area_inv_tabulated(ld, norm_param(g) + lo,
                                                     g.a_full.data() + lo, inv.data, inv.size,
-                                                    la, n);
+                                                    area_inv_lut_for(g.shape), la, n);
                 } else {
                     for (int k = lo; k < lo + n; ++k) {
                         auto uk = static_cast(k);
@@ -957,10 +1158,24 @@ static void apply_area_hydrad_kernel(const ShapeGroup& g, const double* local_d,
         xsect_batch::area_hydrad_circular(local_d + lo, norm_param(g) + lo,
                                           g.a_full.data() + lo, g.r_full.data() + lo,
                                           local_a + lo, local_h + lo, n);
-    } else {
-        apply_area_kernel(g, local_d, local_a, lo, n);
-        apply_hydrad_kernel(g, local_d, local_h, lo, n);
+        return;
+    }
+    // Transect-backed shapes get the same treatment: their area and hyd-rad
+    // tables share one depth grid, so one index serves both (plan A2).
+    if ((g.shape == XSectShape::IRREGULAR || g.shape == XSectShape::CUSTOM ||
+         g.shape == XSectShape::STREET_XSECT) &&
+        !g.area_tables.empty() && !g.hrad_tables.empty()) {
+        const auto ulo = static_cast(lo);
+        xsect_batch::perlink_tabulated_pair(local_d + lo, norm_param(g) + lo,
+                                            g.a_full.data() + lo, g.r_full.data() + lo,
+                                            g.area_tables.data() + ulo,
+                                            g.hrad_tables.data() + ulo,
+                                            g.transect_tbl_size,
+                                            local_a + lo, local_h + lo, n);
+        return;
     }
+    apply_area_kernel(g, local_d, local_a, lo, n);
+    apply_hydrad_kernel(g, local_d, local_h, lo, n);
 }
 
 static void apply_area_hydrad_kernel(const ShapeGroup& g, const double* local_d,
diff --git a/src/engine/hydraulics/XSectBatch.hpp b/src/engine/hydraulics/XSectBatch.hpp
index 44a225420..04c3dccbc 100644
--- a/src/engine/hydraulics/XSectBatch.hpp
+++ b/src/engine/hydraulics/XSectBatch.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file XSectBatch.hpp
  * @brief Cross-section geometry — unified batch + per-element API.
@@ -28,7 +44,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_XSECT_BATCH_HPP
@@ -47,6 +63,8 @@
 #include 
 #include 
 
+#include "XSectLookup.hpp"
+
 namespace openswmm {
 
 // Forward declaration
@@ -117,6 +135,11 @@ struct XSectParams {
     const double* hrad_tbl  = nullptr;   ///< Normalized hyd-radius vs y/y_full
     const double* width_tbl = nullptr;   ///< Normalized width     vs y/y_full
     int    transect_tbl_size = 0;        ///< Entry count of the tables above
+
+    /// Bucket map over `area_tbl` for the getYofA inversion (plan A1). Points
+    /// into the owning TransectData, so it has the same lifetime as area_tbl
+    /// and is null whenever that is.
+    const xsect::LocateLut* area_lut = nullptr;
 };
 
 // ============================================================================
@@ -140,7 +163,8 @@ int    setParams(XSectParams& xs, int type, const double p[], double ucf);
 
 // Lookup table helpers (exposed for batch kernels and testing)
 double lookup(double x, const double* table, int n_items);
-double invLookup(double y, const double* table, int n_items);
+double invLookup(double y, const double* table, int n_items,
+                 const LocateLut* lut = nullptr);
 int    locate(double y, const double* table, int n);
 double getYcircular(double alpha);
 double getScircular(double alpha);
@@ -495,13 +519,42 @@ void area_tabulated(
     int count
 );
 
+/// Per-link tabulated lookup — one shared quantity per call (IRREGULAR/CUSTOM/
+/// STREET, where every link carries its own transect table).
+void perlink_tabulated(
+    const double* OPENSWMM_RESTRICT depth,
+    const double* OPENSWMM_RESTRICT nrm,
+    const double* OPENSWMM_RESTRICT scale,
+    const double* const* tables,
+    int            table_size,
+    double*       OPENSWMM_RESTRICT result,
+    int count
+);
+
+/// Fused per-link tabulated pair (area + hyd-radius) sharing one table index —
+/// bit-identical to two perlink_tabulated passes (plan A2).
+void perlink_tabulated_pair(
+    const double* OPENSWMM_RESTRICT depth,
+    const double* OPENSWMM_RESTRICT nrm,
+    const double* OPENSWMM_RESTRICT scale_a,
+    const double* OPENSWMM_RESTRICT scale_b,
+    const double* const* tables_a,
+    const double* const* tables_b,
+    int            table_size,
+    double*       OPENSWMM_RESTRICT out_a,
+    double*       OPENSWMM_RESTRICT out_b,
+    int count
+);
+
 /// Batch area for shapes using invLookup (gothic, catenary, semielliptical, semicircular).
+/// @param lut  Bucket map for `table` (plan A1), or null to bisect.
 void area_inv_tabulated(
     const double* OPENSWMM_RESTRICT depth,
     const double* OPENSWMM_RESTRICT y_full,
     const double* OPENSWMM_RESTRICT a_full,
     const double* table,
     int            table_size,
+    const xsect::LocateLut* lut,
     double*       OPENSWMM_RESTRICT area,
     int count
 );
diff --git a/src/engine/hydraulics/XSectKernels.hpp b/src/engine/hydraulics/XSectKernels.hpp
index a2e4312b8..0b24251b5 100644
--- a/src/engine/hydraulics/XSectKernels.hpp
+++ b/src/engine/hydraulics/XSectKernels.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file XSectKernels.hpp
  * @brief Portable cross-section geometry kernels — one implementation, three
@@ -36,7 +52,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_XSECT_KERNELS_HPP
@@ -180,6 +196,35 @@ OPENSWMM_KERNEL_FN double powerfuncWofY(double y, double s_bot, double r_bot) {
  * are deliberately identical to the `xsect_tables::` symbols they bind to, so
  * the moved bodies differ from the originals by exactly one token.
  */
+/**
+ * @brief The tables `invLookup()` inverts, and so the ones that carry a
+ *        `LocateLut` (plan XSECT_LOOKUP_ACCEL §4 item A1).
+ *
+ * Every other shared table is only ever read forward, where the index is a
+ * divide-and-truncate and there is no search to accelerate. Keeping the maps in
+ * one array indexed by this enum costs XsectTables a single pointer instead of
+ * fifteen, and keeps the host binding (XSection.cpp hostTables) and any device
+ * binding to one block to copy.
+ */
+enum class LutId : int {
+    Y_Gothic = 0,
+    Y_Catenary,
+    Y_SemiEllip,
+    Y_SemiCirc,
+    A_HorizEllipse,
+    A_VertEllipse,
+    A_Arch,
+    S_Circ,
+    S_Egg,
+    S_Horseshoe,
+    S_Gothic,
+    S_Catenary,
+    S_SemiEllip,
+    S_BasketHandle,
+    S_SemiCirc,
+    COUNT
+};
+
 struct XsectTables {
     const double* A_Arch = nullptr;
     const double* A_Baskethandle = nullptr;
@@ -223,6 +268,8 @@ struct XsectTables {
     const double* Y_SemiCirc = nullptr;
     const double* Y_SemiEllip = nullptr;
     const double* Amax = nullptr;
+    /// Bucket maps for the inverted tables, indexed by LutId; null == bisect.
+    const LocateLut* luts = nullptr;
     int N_A_Arch = 0;
     int N_A_Baskethandle = 0;
     int N_A_Circ = 0;
@@ -264,6 +311,11 @@ struct XsectTables {
     int N_Y_Horseshoe = 0;
     int N_Y_SemiCirc = 0;
     int N_Y_SemiEllip = 0;
+
+    /// The bucket map for one inverted table, or null when none was built.
+    OPENSWMM_KERNEL_FN const LocateLut* lut(LutId id) const {
+        return luts ? (luts + static_cast(id)) : nullptr;
+    }
 };
 
 /**
@@ -359,16 +411,7 @@ struct XsectEval {
 
     OPENSWMM_KERNEL_FN int locate(double y, const double* table, int jLast) const {
         // Bisection: highest index j with table[j] <= y (legacy locate()).
-        int j1 = 0;
-        int j2 = jLast;
-        if (y <= table[0])     return 0;
-        if (y >= table[jLast]) return jLast;
-        while (j2 - j1 > 1) {
-            int j = (j1 + j2) >> 1;
-            if (y >= table[j]) j1 = j;
-            else               j2 = j;
-        }
-        return j1;
+        return locate_bisect(y, table, jLast);
     }
 
     OPENSWMM_KERNEL_FN double lookup(double x, const double* table, int n_items) const {
@@ -395,7 +438,11 @@ struct XsectEval {
         return lookup_exact(x, table, n_items);
     }
 
-    OPENSWMM_KERNEL_FN double invLookup(double y, const double* table, int n_items) const {
+    /// @param lut  Optional bucket map for `table` (plan A1). It changes only
+    ///             how the bracketing index is *found*, never which one — so
+    ///             passing it or not gives byte-identical results.
+    OPENSWMM_KERNEL_FN double invLookup(double y, const double* table, int n_items,
+                                        const LocateLut* lut = nullptr) const {
         double dx = 1.0 / static_cast(n_items - 1);
         int n = n_items;
 
@@ -408,7 +455,7 @@ struct XsectEval {
             if (y <= table[n_items - 2]) i = n_items - 2;
             else                         i = n_items - 3;
         } else {
-            i = locate(y, table, n - 1);
+            i = locate_maybe_lut(y, table, n - 1, lut);
         }
         if (i >= n - 1) return static_cast(n - 1) * dx;
 
@@ -549,7 +596,7 @@ struct XsectEval {
         if (psi == 0.0) return 0.0;
         if (psi >= 1.0) return xs.a_full;
         if (psi <= 0.015) return xs.a_full * getAcircular(psi);
-        return xs.a_full * invLookup(psi, tbl.S_Circ, tbl.N_S_Circ);
+        return xs.a_full * invLookup(psi, tbl.S_Circ, tbl.N_S_Circ, tbl.lut(LutId::S_Circ));
     }
 
     OPENSWMM_KERNEL_FN double circ_getdSdA(const XSectParams& xs, double a) const {
@@ -982,15 +1029,15 @@ struct XsectEval {
             case XSectShape::HORSESHOE:
                 return xs.a_full * lookup(y_norm, tbl.A_Horseshoe, tbl.N_A_Horseshoe);
             case XSectShape::GOTHIC:
-                return xs.a_full * invLookup(y_norm, tbl.Y_Gothic, tbl.N_Y_Gothic);
+                return xs.a_full * invLookup(y_norm, tbl.Y_Gothic, tbl.N_Y_Gothic, tbl.lut(LutId::Y_Gothic));
             case XSectShape::CATENARY:
-                return xs.a_full * invLookup(y_norm, tbl.Y_Catenary, tbl.N_Y_Catenary);
+                return xs.a_full * invLookup(y_norm, tbl.Y_Catenary, tbl.N_Y_Catenary, tbl.lut(LutId::Y_Catenary));
             case XSectShape::SEMIELLIPTICAL:
-                return xs.a_full * invLookup(y_norm, tbl.Y_SemiEllip, tbl.N_Y_SemiEllip);
+                return xs.a_full * invLookup(y_norm, tbl.Y_SemiEllip, tbl.N_Y_SemiEllip, tbl.lut(LutId::Y_SemiEllip));
             case XSectShape::BASKETHANDLE:
                 return xs.a_full * lookup(y_norm, tbl.A_Baskethandle, tbl.N_A_Baskethandle);
             case XSectShape::SEMICIRCULAR:
-                return xs.a_full * invLookup(y_norm, tbl.Y_SemiCirc, tbl.N_Y_SemiCirc);
+                return xs.a_full * invLookup(y_norm, tbl.Y_SemiCirc, tbl.N_Y_SemiCirc, tbl.lut(LutId::Y_SemiCirc));
             case XSectShape::HORIZ_ELLIPSE:
                 return xs.a_full * lookup(y_norm, tbl.A_HorizEllipse, tbl.N_A_HorizEllipse);
             case XSectShape::VERT_ELLIPSE:
@@ -1147,11 +1194,11 @@ struct XsectEval {
             case XSectShape::SEMICIRCULAR:
                 return xs.y_full * lookup(alpha, tbl.Y_SemiCirc, tbl.N_Y_SemiCirc);
             case XSectShape::HORIZ_ELLIPSE:
-                return xs.y_full * invLookup(alpha, tbl.A_HorizEllipse, tbl.N_A_HorizEllipse);
+                return xs.y_full * invLookup(alpha, tbl.A_HorizEllipse, tbl.N_A_HorizEllipse, tbl.lut(LutId::A_HorizEllipse));
             case XSectShape::VERT_ELLIPSE:
-                return xs.y_full * invLookup(alpha, tbl.A_VertEllipse, tbl.N_A_VertEllipse);
+                return xs.y_full * invLookup(alpha, tbl.A_VertEllipse, tbl.N_A_VertEllipse, tbl.lut(LutId::A_VertEllipse));
             case XSectShape::ARCH:
-                return xs.y_full * invLookup(alpha, tbl.A_Arch, tbl.N_A_Arch);
+                return xs.y_full * invLookup(alpha, tbl.A_Arch, tbl.N_A_Arch, tbl.lut(LutId::A_Arch));
             case XSectShape::RECT_CLOSED:
             case XSectShape::RECT_OPEN:    return a / xs.w_max;
             case XSectShape::RECT_TRIANG:  return rect_triang_getYofA(xs, a);
@@ -1166,7 +1213,7 @@ struct XsectEval {
             case XSectShape::STREET_XSECT:
                 // Invert the normalized area table (legacy xsect_getYofA IRREGULAR).
                 if (xs.area_tbl)
-                    return xs.y_full * invLookup(alpha, xs.area_tbl, xs.transect_tbl_size);
+                    return xs.y_full * invLookup(alpha, xs.area_tbl, xs.transect_tbl_size, xs.area_lut);
                 return 0.0;
             default: return 0.0;
         }
@@ -1289,19 +1336,19 @@ struct XsectEval {
             case XSectShape::FORCE_MAIN:
             case XSectShape::CIRCULAR:     return circ_getAofS(xs, s);
             case XSectShape::EGGSHAPED:
-                return xs.a_full * invLookup(psi, tbl.S_Egg, tbl.N_S_Egg);
+                return xs.a_full * invLookup(psi, tbl.S_Egg, tbl.N_S_Egg, tbl.lut(LutId::S_Egg));
             case XSectShape::HORSESHOE:
-                return xs.a_full * invLookup(psi, tbl.S_Horseshoe, tbl.N_S_Horseshoe);
+                return xs.a_full * invLookup(psi, tbl.S_Horseshoe, tbl.N_S_Horseshoe, tbl.lut(LutId::S_Horseshoe));
             case XSectShape::GOTHIC:
-                return xs.a_full * invLookup(psi, tbl.S_Gothic, tbl.N_S_Gothic);
+                return xs.a_full * invLookup(psi, tbl.S_Gothic, tbl.N_S_Gothic, tbl.lut(LutId::S_Gothic));
             case XSectShape::CATENARY:
-                return xs.a_full * invLookup(psi, tbl.S_Catenary, tbl.N_S_Catenary);
+                return xs.a_full * invLookup(psi, tbl.S_Catenary, tbl.N_S_Catenary, tbl.lut(LutId::S_Catenary));
             case XSectShape::SEMIELLIPTICAL:
-                return xs.a_full * invLookup(psi, tbl.S_SemiEllip, tbl.N_S_SemiEllip);
+                return xs.a_full * invLookup(psi, tbl.S_SemiEllip, tbl.N_S_SemiEllip, tbl.lut(LutId::S_SemiEllip));
             case XSectShape::BASKETHANDLE:
-                return xs.a_full * invLookup(psi, tbl.S_BasketHandle, tbl.N_S_BasketHandle);
+                return xs.a_full * invLookup(psi, tbl.S_BasketHandle, tbl.N_S_BasketHandle, tbl.lut(LutId::S_BasketHandle));
             case XSectShape::SEMICIRCULAR:
-                return xs.a_full * invLookup(psi, tbl.S_SemiCirc, tbl.N_S_SemiCirc);
+                return xs.a_full * invLookup(psi, tbl.S_SemiCirc, tbl.N_S_SemiCirc, tbl.lut(LutId::S_SemiCirc));
             default: {
                 // Newton-Raphson on S(a) = s, bracketed in [a1, a2] (legacy generic_getAofS).
                 // a2 = absolute area at max flow = xsect_getAmax.
@@ -1440,13 +1487,18 @@ struct XsectEval {
     // ============================================================================
 
     OPENSWMM_KERNEL_FN bool isOpen(int type) const {
+        // PARITY xsect.c:215 xsect_isOpen() = (Amax[type] >= 1.0): the shapes
+        // whose Amax entry is 1.0 (xsect.c:59-85) are DUMMY, RECT_OPEN,
+        // TRAPEZOIDAL, TRIANGULAR, PARABOLIC, POWERFUNC, IRREGULAR and STREET.
         switch (static_cast(type)) {
+            case XSectShape::DUMMY:
             case XSectShape::RECT_OPEN:
             case XSectShape::TRAPEZOIDAL:
             case XSectShape::TRIANGULAR:
             case XSectShape::PARABOLIC:
             case XSectShape::POWERFUNC:
             case XSectShape::IRREGULAR:
+            case XSectShape::STREET_XSECT:
                 return true;
             default:
                 return false;
diff --git a/src/engine/hydraulics/XSectLookup.hpp b/src/engine/hydraulics/XSectLookup.hpp
index 06116d261..a0ce58808 100644
--- a/src/engine/hydraulics/XSectLookup.hpp
+++ b/src/engine/hydraulics/XSectLookup.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file XSectLookup.hpp
  * @brief Bit-exact geometry-table interpolation — the single source of truth.
@@ -34,7 +50,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_XSECT_LOOKUP_HPP
@@ -128,6 +144,139 @@ inline double norm_lookup(double depth, double param, const double* t, int n) no
 #endif
 }
 
+// ============================================================================
+// Bucket LUT for locate() — plan XSECT_LOOKUP_ACCEL §4 item A1.
+//
+// `locate()` is a bisection over a monotone table: ~log2(n) data-dependent
+// branches (~6 on the 51-row transect/built-in tables). The LUT replaces the
+// first few of them with one multiply + truncate: the table's VALUE range is
+// split into kBuckets equal spans, and for each span we precompute an index
+// bracket that provably contains locate()'s answer. A short bisection inside
+// that bracket finishes the job.
+//
+// **Index identity (why this stays bit-exact).** `locate()`'s answer is the
+// unique index `max{ j <= jLast : table[j] <= y }`. This routine returns the
+// same index for every input — it only narrows the search window — so the
+// interpolation arithmetic downstream is byte-for-byte unchanged. The proof
+// rests on one property: `bucket_of()` is monotone non-decreasing in y (an
+// affine map with a positive scale, then a truncating cast, then a clamp), and
+// the table is checked monotone non-decreasing at build time. Then
+//
+//   lo[b] = max{ j : bucket_of(table[j]) < b }        (0 if the set is empty)
+//
+// satisfies table[lo[b]] <= y for every y in bucket b, and — because
+// `bucket_of(table[j])` is non-decreasing in j, so {j : bucket_of <= b} is a
+// prefix — `lo[b+1] + 1` is exactly `min{ j : bucket_of(table[j]) > b }`, whose
+// table value is strictly greater than y. That is precisely the bisection
+// invariant, on a window of one or two table cells instead of the whole table.
+//
+// A table that fails the monotonicity check (or is degenerate) leaves `scale`
+// at 0, which callers read as "no LUT" and fall back to plain bisection — so a
+// pathological table can never change a result, only its speed.
+// ============================================================================
+
+/// Precomputed value→index-bracket map for one geometry table.
+///
+/// POD: trivially copyable into a device kernel alongside the table it indexes
+/// (the Kokkos FV path copies XsectTables by value).
+struct LocateLut {
+    static constexpr int kBuckets = 64;
+
+    double        t0     = 0.0;   ///< table[0] — the low end of the value range
+    double        scale  = 0.0;   ///< kBuckets / (table[jLast] - t0); 0 == disabled
+    int           j_last = 0;     ///< the `jLast` this map was built for
+    unsigned char lo[kBuckets + 1] = {};  ///< lo[b] = max{ j : bucket(table[j]) < b }
+};
+
+/// Bucket index for a value — the ONE expression used by both build and query.
+inline int lut_bucket(const LocateLut& L, double y) noexcept {
+    int b = static_cast((y - L.t0) * L.scale);
+    if (b < 0) b = 0;
+    else if (b >= LocateLut::kBuckets) b = LocateLut::kBuckets - 1;
+    return b;
+}
+
+/// Plain bisection — the shipped `locate()` body, kept here so the LUT builder
+/// and the fallback path share one definition with XsectEval::locate.
+inline int locate_bisect(double y, const double* table, int jLast) noexcept {
+    int j1 = 0;
+    int j2 = jLast;
+    if (y <= table[0])     return 0;
+    if (y >= table[jLast]) return jLast;
+    while (j2 - j1 > 1) {
+        int j = (j1 + j2) >> 1;
+        if (y >= table[j]) j1 = j;
+        else               j2 = j;
+    }
+    return j1;
+}
+
+/// Build the bucket map for `table` over indices [0, jLast].
+///
+/// Leaves the map disabled (scale == 0) for a degenerate or non-monotone table,
+/// or one too long to index with a byte — the caller then bisects as before.
+inline void build_locate_lut(LocateLut& L, const double* table, int jLast) noexcept {
+    L = LocateLut{};
+    if (!table || jLast < 2 || jLast > 254) return;
+    for (int j = 1; j <= jLast; ++j)
+        if (!(table[j] >= table[j - 1])) return;   // non-monotone (or NaN) — no LUT
+
+    const double span = table[jLast] - table[0];
+    if (!(span > 0.0)) return;                     // flat table — nothing to bracket
+
+    L.t0     = table[0];
+    L.scale  = static_cast(LocateLut::kBuckets) / span;
+    L.j_last = jLast;
+    for (int b = 0; b <= LocateLut::kBuckets; ++b) {
+        int best = 0;
+        for (int j = 0; j <= jLast; ++j) {
+            if (lut_bucket(L, table[j]) >= b) break;   // bucket(table[.]) is sorted
+            best = j;
+        }
+        L.lo[b] = static_cast(best);
+    }
+}
+
+/// LUT-accelerated `locate()` — returns the identical index for every input.
+inline int locate_lut(double y, const double* table, int jLast,
+                      const LocateLut& L) noexcept {
+    // `!(y > table[0])` (not `y <= table[0]`) also catches NaN, which plain
+    // bisection resolves to 0 because every `y >= table[j]` test is false.
+    if (!(y > table[0])) return 0;
+    if (y >= table[jLast]) return jLast;
+
+    const int b  = lut_bucket(L, y);
+    int       j1 = L.lo[b];
+    int       j2 = L.lo[b + 1] + 1;
+    if (j2 > jLast) j2 = jLast;
+    while (j2 - j1 > 1) {
+        int jm = (j1 + j2) >> 1;
+        if (y >= table[jm]) j1 = jm;
+        else                j2 = jm;
+    }
+    return j1;
+}
+
+/// Dispatch: use the map when one was built for this exact table extent.
+inline int locate_maybe_lut(double y, const double* table, int jLast,
+                            const LocateLut* L) noexcept {
+    if (L && L->scale > 0.0 && L->j_last == jLast)
+        return locate_lut(y, table, jLast, *L);
+    return locate_bisect(y, table, jLast);
+}
+
+/// Build the map for the extent `invLookup(y, table, n_items)` actually
+/// searches — including the section-factor tables' two-row top truncation, so
+/// the S_* maps bracket the same window `locate()` is called on. (The
+/// truncated top rows are resolved by invLookup's own branch, outside
+/// `locate`, and are unaffected.)
+inline void build_invlookup_lut(LocateLut& L, const double* table, int n_items) noexcept {
+    if (!table || n_items < 4) { L = LocateLut{}; return; }
+    int n = n_items;
+    if (table[n - 3] > table[n - 1]) n = n - 2;
+    build_locate_lut(L, table, n - 1);
+}
+
 } // namespace openswmm::xsect
 
 #endif // OPENSWMM_XSECT_LOOKUP_HPP
diff --git a/src/engine/hydraulics/XSection.cpp b/src/engine/hydraulics/XSection.cpp
index 65f2207b5..a01fe2675 100644
--- a/src/engine/hydraulics/XSection.cpp
+++ b/src/engine/hydraulics/XSection.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file XSection.cpp
  * @brief Cross-section geometry — faithful 1:1 port of legacy xsect.c.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "XSectBatch.hpp"
@@ -32,6 +48,7 @@
 #  pragma STDC FP_CONTRACT OFF
 #endif
 
+#include 
 #include 
 #include 
 
@@ -60,6 +77,40 @@ double getWofY(const XSectParams& xs, double y);
 // entry points are one-line forwarders so every existing caller is unchanged.
 // ============================================================================
 
+// ============================================================================
+// Bucket maps for the inverted built-in tables (plan XSECT_LOOKUP_ACCEL A1).
+//
+// One static block, built on first use and never mutated afterwards, so the
+// shared `const XsectEval` stays safe to read from every thread and copyable
+// to a device. Each entry is index-identical to plain bisection by
+// construction (see XSectLookup.hpp), so this changes speed only.
+// ============================================================================
+static const LocateLut* builtinLuts() {
+    static const std::array(LutId::COUNT)> luts = [] {
+        std::array(LutId::COUNT)> a{};
+        const auto set = [&a](LutId id, const double* t, int n) {
+            xsect::build_invlookup_lut(a[static_cast(id)], t, n);
+        };
+        set(LutId::Y_Gothic,       xsect_tables::Y_Gothic,       xsect_tables::N_Y_Gothic);
+        set(LutId::Y_Catenary,     xsect_tables::Y_Catenary,     xsect_tables::N_Y_Catenary);
+        set(LutId::Y_SemiEllip,    xsect_tables::Y_SemiEllip,    xsect_tables::N_Y_SemiEllip);
+        set(LutId::Y_SemiCirc,     xsect_tables::Y_SemiCirc,     xsect_tables::N_Y_SemiCirc);
+        set(LutId::A_HorizEllipse, xsect_tables::A_HorizEllipse, xsect_tables::N_A_HorizEllipse);
+        set(LutId::A_VertEllipse,  xsect_tables::A_VertEllipse,  xsect_tables::N_A_VertEllipse);
+        set(LutId::A_Arch,         xsect_tables::A_Arch,         xsect_tables::N_A_Arch);
+        set(LutId::S_Circ,         xsect_tables::S_Circ,         xsect_tables::N_S_Circ);
+        set(LutId::S_Egg,          xsect_tables::S_Egg,          xsect_tables::N_S_Egg);
+        set(LutId::S_Horseshoe,    xsect_tables::S_Horseshoe,    xsect_tables::N_S_Horseshoe);
+        set(LutId::S_Gothic,       xsect_tables::S_Gothic,       xsect_tables::N_S_Gothic);
+        set(LutId::S_Catenary,     xsect_tables::S_Catenary,     xsect_tables::N_S_Catenary);
+        set(LutId::S_SemiEllip,    xsect_tables::S_SemiEllip,    xsect_tables::N_S_SemiEllip);
+        set(LutId::S_BasketHandle, xsect_tables::S_BasketHandle, xsect_tables::N_S_BasketHandle);
+        set(LutId::S_SemiCirc,     xsect_tables::S_SemiCirc,     xsect_tables::N_S_SemiCirc);
+        return a;
+    }();
+    return luts.data();
+}
+
 const XsectTables& hostTables() {
     static const XsectTables t = [] {
         XsectTables t;
@@ -105,6 +156,7 @@ const XsectTables& hostTables() {
     t.Y_SemiCirc = xsect_tables::Y_SemiCirc;
     t.Y_SemiEllip = xsect_tables::Y_SemiEllip;
     t.Amax = xsect_tables::Amax;
+    t.luts = builtinLuts();
     t.N_A_Arch = xsect_tables::N_A_Arch;
     t.N_A_Baskethandle = xsect_tables::N_A_Baskethandle;
     t.N_A_Circ = xsect_tables::N_A_Circ;
@@ -161,7 +213,8 @@ const XsectEval& hostEval() {
 
 int    locate(double y, const double* table, int jLast)  { return hostEval().locate(y, table, jLast); }
 double lookup(double x, const double* table, int n)      { return hostEval().lookup(x, table, n); }
-double invLookup(double y, const double* table, int n)   { return hostEval().invLookup(y, table, n); }
+double invLookup(double y, const double* table, int n, const LocateLut* lut)
+                                                         { return hostEval().invLookup(y, table, n, lut); }
 double getYcircular(double alpha)                        { return hostEval().getYcircular(alpha); }
 double getScircular(double alpha)                        { return hostEval().getScircular(alpha); }
 
diff --git a/src/engine/hydraulics/fv/ExplicitFvSolver.cpp b/src/engine/hydraulics/fv/ExplicitFvSolver.cpp
index 6423741c0..7db56c079 100644
--- a/src/engine/hydraulics/fv/ExplicitFvSolver.cpp
+++ b/src/engine/hydraulics/fv/ExplicitFvSolver.cpp
@@ -10,11 +10,14 @@
 
 #include 
 #include 
+#include 
 #include 
 
 #include "FvKernels.hpp"
 #include "../HydClosureKernels.hpp"
 #include "../../core/Constants.hpp"
+#include "../../core/PerfTimers.hpp"
+#include "../../transport/fvkernels/SpeciesTransportKernels.hpp"
 
 #ifdef SWMM_USE_OPENMP
 #include 
@@ -27,26 +30,37 @@ namespace k = kernels;
 namespace {
 
 /// Below this many faces the OpenMP fork/join costs more than the flux loop.
-constexpr int kOmpMinFaces = 4096;
-
-/// Slope limiters for the second-order scalar reconstruction. All three are
-/// TVD; superbee is the sharpest and can artificially steepen smooth profiles,
-/// minmod the most diffusive and most robust.
-inline double limitSlope(double a, double b, Limiter lim) {
-    if (a * b <= 0.0) return 0.0;                  // extremum ⇒ no slope
-    switch (lim) {
-        case Limiter::VANLEER:
-            return 2.0 * a * b / (a + b);
-        case Limiter::SUPERBEE: {
-            const double s = (a > 0.0) ? 1.0 : -1.0;
-            return s * std::max(std::min(2.0 * std::fabs(a), std::fabs(b)),
-                                std::min(std::fabs(a), 2.0 * std::fabs(b)));
-        }
-        case Limiter::MINMOD:
-        default:
-            return (std::fabs(a) < std::fabs(b)) ? a : b;
-    }
+/// Env-overridable for the Phase 3 gate sweep (OPENSWMM_FV_OMP_MIN_FACES /
+/// _CELLS / _NODES); read once.
+int ompMinEnv(const char* name, int dflt) {
+    const char* e = std::getenv(name);
+    return (e && e[0]) ? std::atoi(e) : dflt;
 }
+const int kOmpMinFaces = ompMinEnv("OPENSWMM_FV_OMP_MIN_FACES", 4096);
+
+/// Same trade for the per-cell loops (depth refresh, cell update). Kept at the
+/// face threshold: a conduit mesh carries comparable cell and face counts, and
+/// the per-item work is the same order.
+const int kOmpMinCells = ompMinEnv("OPENSWMM_FV_OMP_MIN_CELLS", 4096);
+
+/// Node solves (Phase 3d): each junction's algebraic solve re-evaluates only
+/// its own incident faces and writes only its own head, so the loop is
+/// order-independent and bit-identical at any thread count. A solve costs
+/// ~10 face fluxes, so far fewer items amortize the fork/join than a cell loop.
+const int kOmpMinNodes = ompMinEnv("OPENSWMM_FV_OMP_MIN_NODES", 64);
+
+/// Column-separation vacuum limit, ~1 atm of water column (issue #156): a
+/// sealed TPA reach can sustain sub-atmospheric pressure only to about
+/// hs ≈ −30 ft before the column separates and a vapor cavity forms — modeled
+/// as an unconditional exit to free surface (documented limitation; real
+/// cavity dynamics are out of scope). Shared by the substep entry/exit rule
+/// (updateTpaFlags) and the same-substep floor check (R4d).
+constexpr double kCavHead = 30.0;   // ft
+
+/// limitSlope moved to transport/fvkernels/SpeciesTransportKernels.hpp
+/// (phase E0) — shared between the species kernels and the hydrodynamic
+/// second-order reconstruction below.
+using openswmm::transport::fvkernels::limitSlope;
 
 } // namespace
 
@@ -70,6 +84,10 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
     // indexing short vectors: no ponding, no surcharge depth.
     if (mesh.node_sur_depth.size() < nn) mesh.node_sur_depth.resize(nn, 0.0);
     if (mesh.node_can_pond.size() < nn)  mesh.node_can_pond.resize(nn, 0);
+    // Same reason: faceSide indexes face_geom unconditionally, so a mesh that
+    // never went through NetworkMeshBuilder must get the per-cell fallback
+    // here rather than reading an empty vector. No-op for a built mesh.
+    mesh.deriveFaceGeom();
     if (mesh.face_gate.size() < nf)      mesh.face_gate.resize(nf, 0);
     if (mesh.face_culvert.size() < nf)   mesh.face_culvert.resize(nf, -1);
 
@@ -78,7 +96,6 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
     f_sstar_.assign(nf, 0.0);
     f_corr_l_.assign(nf, 0.0);
     f_corr_r_.assign(nf, 0.0);
-    f_scale_.assign(nf, 1.0);
     f_phi_l_.assign(ns * nf, 0.0);
     f_phi_r_.assign(ns * nf, 0.0);
     f_phi_flux_.assign(ns * nf, 0.0);
@@ -93,17 +110,59 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
 
     cell_eta_.assign(nc, 0.0);
     cell_u_.assign(nc, 0.0);
+    cell_ah_.assign(nc, 0.0);
+    cell_t_.assign(nc, 0.0);
+    cell_i1_.assign(nc, 0.0);
     cell_q_int_.assign(nc, 0.0);
+    // Unsteady friction (issue #156): scratch sized only when active so the
+    // default path allocates nothing.
+    uf_grad_.assign((opts.unsteady_friction != 0) ? nc : 0, 0.0);
+
+    // TPA pressure closure (issue #156 Phase 4): the regime flag lives in the
+    // STATE so the static membership predicates see it; empty ⇒ SLOT closure
+    // everywhere (bit-inert default). Cold start: all-free (worst case one
+    // spurious re-pressurization step after a hotstart — TPA plan §5).
+    tpa_ = (opts.pressure_closure == 1);
+    // Dev switch for the slot/free-surface interface treatment (entrance
+    // lock investigation, 2026-09-11): OPENSWMM_FV_MIXED_WAVE=0 restores the
+    // symmetric Davis estimate and the acoustic vented-node ghost.
+    {
+        const char* mw = std::getenv("OPENSWMM_FV_MIXED_WAVE");
+        mixed_wave_ = !(mw && mw[0] == '0');
+        mw_rh_  = mixed_wave_;
+        const char* d1 = std::getenv("OPENSWMM_FV_DEG1");
+        deg1_guard_slot_ = !(d1 && d1[0] == '1');
+        const char* cp = std::getenv("OPENSWMM_FV_CENSUS_PASS");
+        census_pass_far_ = !(cp && cp[0] == '0');
+        const char* lf = std::getenv("OPENSWMM_FV_LTS_FIT");
+        lts_fit_ = (lf && lf[0] == '1');
+        // Phase 4a sweep: OPENSWMM_FV_CFL overrides the deck's FV_CFL so the
+        // analytic harnesses run unchanged. Dev only.
+        if (const char* cf = std::getenv("OPENSWMM_FV_CFL")) {
+            const double v = std::atof(cf);
+            if (v > 0.0 && v <= 1.0) opts_.cfl = v;
+        }
+    }
+    if (tpa_) {
+        state.cell_tpa.assign(nc, 0);
+        tpa_scratch_.assign(nc, 0);
+    } else {
+        state.cell_tpa.clear();
+        tpa_scratch_.clear();
+    }
 
     node_exch_.assign(nn, 0.0);
     node_in_.assign(nn, 0.0);
     node_out_.assign(nn, 0.0);
     flood_vol_.assign(nn, 0.0);
+    node_qdummy_.assign(mesh.struct_is_dummy.empty() ? 0 : nn, 0.0);
+    dummy_vol_.assign(mesh.struct_link.size(), 0.0);
     inlet_control_.assign(static_cast(mesh.n_conduits()), 0);
 
     cell_tier_.assign(nc, 0);
     node_tier_.assign(nn, 0);
     face_tier_.assign(nf, 0);
+    relax_beta_.assign(nf, 0.0);
     acc_a_.clear();
     acc_q_.clear();
     acc_nvol_.clear();
@@ -119,6 +178,7 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
     since_rebuild_ = 0;
     census_count_ = 0;
     dt_cache_     = 0.0;
+    dt_census_    = 0.0;
     lts_valid_    = false;
     lts_countdown_ = 0;
     lts_dt0_      = 0.0;
@@ -131,6 +191,10 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
     active_min_  = -1.0;
     active_max_  = -1.0;
     active_n_    = 0;
+    n_macro_cycles_   = 0;
+    n_macro_rejected_ = 0;
+    state_clean_      = false;
+    acc_dirty_        = false;
 
     refreshDepths();
     refreshNodeAreas();
@@ -139,12 +203,16 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
     // (no storage table) with at least one incident face. A node with only
     // structure links has no face flux to balance — its residual would carry
     // no head dependence — so it keeps the bucket machinery. Outfalls are
-    // excluded by kind; virtual junctions never reach the node paths at all.
+    // excluded by kind; virtual junctions never reach the node paths at all
+    // (their only node-level state is a lateral inflow, which
+    // refreshStructFlows diverts into the two spliced cells).
     node_alg_.assign(nn, 0);
     node_carry_.assign(nn, 0.0);
     node_vfull_.assign(nn, 0.0);
     node_pass_static_.assign(nn, 0);
     node_pass_.assign(nn, 0);
+    node_pub_static_.assign(nn, 0);
+    node_pub_.assign(nn, 0);
     for (std::size_t un = 0; un < nn; ++un) {
         node_vfull_[un] = nodeVolumeFromDepth(static_cast(un),
                                               mesh_->node_full_depth[un]);
@@ -153,13 +221,13 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
              mesh_->node_vol_off[un] < 0 &&
              mesh_->node_face_ptr[un + 1] > mesh_->node_face_ptr[un])
                 ? 1 : 0;
-        // Static half of the pass-through test: exactly two incident conduit
-        // faces, neither carrying a culvert inlet or a flap gate (those need
-        // their head- and direction-dependent laws applied against a solved
-        // node state, not bypassed by a direct face).
-        if (node_alg_[un] &&
-            mesh_->node_face_ptr[un + 1] - mesh_->node_face_ptr[un] == 2) {
-            bool clean = true;
+        // "Clean" = every incident face is a plain conduit face. A culvert
+        // inlet or a flap gate needs its head- and direction-dependent law
+        // applied against a solved node state, not bypassed by a direct face,
+        // and its node head is a genuine headwater that must not be
+        // reconstructed away.
+        bool clean = node_alg_[un] != 0;
+        if (clean) {
             for (int p = mesh_->node_face_ptr[un];
                  p < mesh_->node_face_ptr[un + 1]; ++p) {
                 const auto uf = static_cast(
@@ -167,7 +235,45 @@ void ExplicitFvSolver::initialize(NetworkMeshData& mesh, NetworkStateData& state
                 if (mesh_->face_culvert[uf] >= 0 || mesh_->face_gate[uf] != 0)
                     clean = false;
             }
-            node_pass_static_[un] = clean ? 1 : 0;
+        }
+        // Static half of the PUBLISH test: clean at ANY degree. The degree-2
+        // restriction below exists because the SOLVER's direct-face bypass
+        // needs exactly two faces to present to each other; reconstructing a
+        // REPORTED stage from the incident wet cells has no such requirement.
+        node_pub_static_[un] = clean ? 1 : 0;
+        // Static half of the pass-through test: clean AND exactly two faces.
+        if (clean &&
+            mesh_->node_face_ptr[un + 1] - mesh_->node_face_ptr[un] == 2)
+            node_pass_static_[un] = 1;
+    }
+
+    // Rim cap for the diverted lateral (face_a_rim_ in the header): the
+    // receiving cell's area at the junction rim, per boundary face of every
+    // statically pass-through-eligible junction. Static for the run, as the
+    // rim and the cell bed are. The rim is the same ceiling the solved path
+    // brackets against (solveAlgebraicNode's `top`).
+    face_a_rim_.assign(nf, std::numeric_limits::infinity());
+    face_lat_spill_.assign(nf, 0.0);
+    for (std::size_t un = 0; un < nn; ++un) {
+        if (!node_pass_static_[un]) continue;
+        const double full = mesh_->node_full_depth[un];
+        if (!(full > 0.0)) continue;
+        const double rim = mesh_->node_invert[un] + full +
+                           (mesh_->node_can_pond[un] ? 0.0
+                                                     : mesh_->node_sur_depth[un]);
+        for (int p = mesh_->node_face_ptr[un];
+             p < mesh_->node_face_ptr[un + 1]; ++p) {
+            const auto uf = static_cast(
+                mesh_->node_face_idx[static_cast(p)]);
+            const int c = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                    : mesh_->face_cr[uf];
+            if (c < 0) continue;
+            const auto uc = static_cast(c);
+            const FvGeometry& g =
+                mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+            if (g.is_open) continue;   // a real free surface has no slot to overfill
+            const double h_rim = rim - mesh_->cell_zb[uc];
+            face_a_rim_[uf] = (h_rim > 0.0) ? k::areaOfDepth(g, h_rim) : 0.0;
         }
     }
 }
@@ -178,6 +284,8 @@ void ExplicitFvSolver::reinitialize(double /*t0*/) {
     lists_valid_  = false;
     census_count_ = 0;
     dt_cache_     = 0.0;
+    dt_census_    = 0.0;
+    state_clean_  = false;   // the caller may have written the state
     refreshDepths();
     refreshNodeAreas();
 }
@@ -206,6 +314,12 @@ INetworkSolver::RunStats ExplicitFvSolver::run_stats() const noexcept {
     s.n_tiers = std::min(lts_tiers_, static_cast(kMaxLtsTiers));
     for (int k = 0; k < s.n_tiers; ++k)
         s.tier_cells[k] = tier_occupancy_[static_cast(k)];
+    s.dt_argmin_pressurized = dt_argmin_pressurized_;
+    s.dt_argmin_band        = dt_argmin_band_;
+    s.dt_argmin_free        = dt_argmin_free_;
+    s.dt_argmin_node        = dt_argmin_node_;
+    s.n_macro_cycles        = n_macro_cycles_;
+    s.n_macro_rejected      = n_macro_rejected_;
     return s;
 }
 
@@ -282,20 +396,64 @@ double ExplicitFvSolver::nodeDepthFromVolume(int node, double volume) const {
 // State refresh
 // ===========================================================================
 
+// The closure at the cell's own depth, kept beside cell_h. Every consumer that
+// used to evaluate A/T/I₁ at cell_h reads these instead; a dry or TPA-flagged
+// cell stores zeros because no consumer reads the cache in those states
+// (faceSide takes the TPA branch, the census uses t_slot). Per-cell writes
+// only, so it is safe inside the parallel cell loops.
+void ExplicitFvSolver::cacheClosure(std::size_t uc, const FvGeometry& g,
+                                    double h) noexcept {
+    if (h > k::kDryDepth && !tpaCell(uc)) {
+        perf::count(perf::n_fv_geom_area);
+        perf::count(perf::n_fv_geom_width);
+        perf::count(perf::n_fv_geom_i1);
+        // One panel locate for all three: the closure's A, T and I₁ come
+        // from the same cubic.
+        const k::ClosureEval e = k::closureEval(g.closure_tbl, h);
+        cell_ah_[uc] = e.a;
+        cell_t_[uc]  = e.t;
+        cell_i1_[uc] = e.i1;
+    } else {
+        cell_ah_[uc] = 0.0;
+        cell_t_[uc]  = 0.0;
+        cell_i1_[uc] = 0.0;
+    }
+}
+
 void ExplicitFvSolver::refreshDepths() {
+    perf::GatedTimer _pt(perf::sec_fv_refreshdep);
     const int nc = mesh_->n_cells();
+    // Every iteration reads and writes only its OWN cell index, and
+    // depthOfArea is a pure function of (const geometry, area) -- no table
+    // cursor, no shared scratch -- so the loop carries no dependence and the
+    // result is bit-identical to the serial order regardless of thread count
+    // (there is no reduction here to reassociate). The inversion counter is
+    // hoisted out: incrementing it per iteration would be a data race, and
+    // the count is exactly nc either way.
+    perf::count(perf::n_fv_invert, static_cast(nc));
+#ifdef SWMM_USE_OPENMP
+#pragma omp parallel for schedule(static) if (nc >= kOmpMinCells)
+#endif
     for (int c = 0; c < nc; ++c) {
         const auto uc = static_cast(c);
         const FvGeometry& g = mesh_->geom[static_cast(mesh_->cell_geom[uc])];
         double a = state_->cell_a[uc];
         if (a < 0.0) a = 0.0;
-        const double h = k::depthOfArea(g, a);
+        const bool tpa_cell = tpaCell(uc);   // regime-consistent h(A) (#156)
+        const double h = tpa_cell ? k::tpaDepthOfArea(g, a)
+                                  : k::depthOfArea(g, a);
         state_->cell_a[uc] = a;
         state_->cell_h[uc] = h;
         cell_eta_[uc] = mesh_->cell_zb[uc] + h;
-        if (h <= k::kDryDepth) {
+        cacheClosure(uc, g, h);
+        if (!tpa_cell && h <= k::kDryDepth) {
             state_->cell_q[uc] = 0.0;
             cell_u_[uc]        = 0.0;
+        } else if (tpa_cell) {
+            // A flagged cell has no dry cutoff above, so a == 0.0 exactly
+            // would put inf/NaN in cell_u_ (issue #156 R4b). Floor at
+            // kDryArea, the same vacuum floor faceSide's TPA side uses.
+            cell_u_[uc] = state_->cell_q[uc] / std::max(a, k::kDryArea);
         } else {
             cell_u_[uc] = state_->cell_q[uc] / a;
         }
@@ -346,6 +504,7 @@ void ExplicitFvSolver::refreshNodeAreas() {
 // ===========================================================================
 
 void ExplicitFvSolver::rebuildActiveLists() {
+    perf::GatedTimer _pt(perf::sec_fv_rebuild);
     const int nc = mesh_->n_cells();
     const int nf = mesh_->n_faces();
 
@@ -374,11 +533,30 @@ void ExplicitFvSolver::rebuildActiveLists() {
 
     // Seed: any cell holding water or momentum, plus any cell fed by a node
     // that stands above the conduit invert — a dry pipe hanging off a full
-    // manhole must not be skipped.
+    // manhole must not be skipped. A TPA-SEALED cell is active at any h
+    // (issue #156 R4a): a sealed sub-atmospheric column has NEGATIVE cell_h,
+    // so an at-rest one (q exactly 0) read as dry here, was deactivated, and
+    // updateTpaFlags then cleared its seal — converting a resting vacuum
+    // column into a free-surface film whose eta sits ~|hs| above the truth,
+    // primed to inject that head on reactivation. Today only q's float
+    // non-zeroness protects the quiescent sealed column (the P5 at-rest
+    // pressurized class); this makes the protection structural.
+    // A cell that receives a diverted junction lateral (cell_qlat_, filled by
+    // refreshStructFlows) is active whatever its depth: updateCells is the
+    // only place the injection lands, and it skips inactive cells. Without
+    // this a lateral into a DRY reach vanished — the node had marked it
+    // delivered (node_lat_div_), the ledger booked it as inflow, and no cell
+    // ever took it. Measured on a 7 km tunnel filling from dry (Klaver
+    // Example_02, 2026-09-13): 100 % of the first 70 min of lateral inflow at
+    // a degree-2 junction lost, 4.7 % of the run's total, until the wetting
+    // front from upstream activated the cells.
+    const bool have_qlat = !cell_qlat_.empty();
     for (int c = 0; c < nc; ++c) {
         const auto uc = static_cast(c);
         cell_active_[uc] = (state_->cell_h[uc] > k::kDryDepth ||
-                            state_->cell_q[uc] != 0.0) ? char{1} : char{0};
+                            state_->cell_q[uc] != 0.0 ||
+                            (have_qlat && cell_qlat_[uc] != 0.0) ||
+                            tpaCell(uc)) ? char{1} : char{0};
     }
     for (int f = 0; f < nf; ++f) {
         const auto uf = static_cast(f);
@@ -448,7 +626,24 @@ void ExplicitFvSolver::rebuildActiveLists() {
 // CFL census
 // ===========================================================================
 
-double ExplicitFvSolver::censusDt() const {
+int ExplicitFvSolver::passThroughFarCell(int face, int nd) const noexcept {
+    if (nd < 0 || node_pass_.empty() ||
+        !node_pass_[static_cast(nd)] || !algebraicActive(nd))
+        return -1;
+    const auto und = static_cast(nd);
+    for (int p = mesh_->node_face_ptr[und]; p < mesh_->node_face_ptr[und + 1]; ++p) {
+        const int of = mesh_->node_face_idx[static_cast(p)];
+        if (of == face) continue;
+        const auto uof = static_cast(of);
+        return (mesh_->face_cl[uof] >= 0) ? mesh_->face_cl[uof] : mesh_->face_cr[uof];
+    }
+    return -1;
+}
+
+double ExplicitFvSolver::censusDt(bool press_edit) const {
+    perf::GatedTimer _pt(perf::sec_fv_census);
+    perf::count(perf::n_fv_census);
+    perf::count(perf::n_fv_census_face, static_cast(active_faces_.size()));
     double dt = std::numeric_limits::max();
     static const bool kDtTrace = [] {
         const char* e = std::getenv("OPENSWMM_FV_DT_TRACE");
@@ -473,34 +668,85 @@ double ExplicitFvSolver::censusDt() const {
         double speed = 0.0;
         double dx_ref = 1.0e30;
 
+        // R2 census edit: on a FULL face the implicit pass covers this
+        // substep, a pressurized side no longer time-steps its acoustic pair
+        // explicitly, so its bound is advective only. Face-level eligibility
+        // comes from the SAME predicate classify() uses, so gated/culvert
+        // faces AND transition (DELTA) faces — which stay entirely explicit,
+        // bores included — keep the full explicit bound.
+        const std::uint8_t fmode =
+            press_edit ? PressurizedHeadSolver::faceModeOf(*mesh_, *state_, f)
+                       : PressurizedHeadSolver::kNone;
+
         auto consider_cell = [&](int cell) {
             const auto uc = static_cast(cell);
             dx_ref = std::min(dx_ref, mesh_->cell_dx[uc]);
             const double h = state_->cell_h[uc];
-            if (h <= k::kDryDepth) return;
+            const bool tpa_c = tpaCell(uc);   // full of water at any h (#156)
+            if (!tpa_c && h <= k::kDryDepth) return;
             const FvGeometry& g =
                 mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+            if (fmode == PressurizedHeadSolver::kFull &&
+                (tpa_c || (!g.is_open && h >= g.y_crown))) {
+                speed = std::max(speed, std::fabs(cell_u_[uc]));
+                return;
+            }
+            // T(cell_h) from the cache filled at the depth write — the same
+            // widthOfDepth(g, h) this used to evaluate, bit for bit.
             speed = std::max(speed,
                              std::fabs(cell_u_[uc]) +
                                  k::celerity(state_->cell_a[uc],
-                                             k::widthOfDepth(g, h)));
+                                             tpa_c ? g.t_slot
+                                                   : cell_t_[uc]));
         };
         if (cl >= 0) consider_cell(cl);
         if (cr >= 0) consider_cell(cr);
 
         if (nd >= 0) {
             const int other = (cl >= 0) ? cl : cr;
-            if (other >= 0) {
+            // Pass-through junction (plan Phase 1e): the flux presents the FAR
+            // cell's centred state at this face (faceSide), so the census
+            // bounds THAT state — not a ghost rebuilt from node_head − z_face,
+            // which after a drop offset stands above the downstream crown and
+            // carries the slot celerity the flux never sees (Bellinge measured
+            // a dry-weather dt0 of 0.036 s from exactly this).
+            const int far = census_pass_far_ ? passThroughFarCell(f, nd) : -1;
+            if (far >= 0) {
+                const auto ufar = static_cast(far);
+                const bool tpa_f = tpaCell(ufar);
+                if (tpa_f || state_->cell_h[ufar] > k::kDryDepth) {
+                    const FvGeometry& gfar =
+                        mesh_->geom[static_cast(mesh_->cell_geom[ufar])];
+                    speed = std::max(speed,
+                                     std::fabs(cell_u_[ufar]) +
+                                         k::celerity(state_->cell_a[ufar],
+                                                     tpa_f ? gfar.t_slot
+                                                           : cell_t_[ufar]));
+                }
+            } else if (other >= 0) {
                 const auto uo = static_cast(other);
                 const FvGeometry& g =
                     mesh_->geom[static_cast(mesh_->cell_geom[uo])];
                 const double hg = state_->node_head[static_cast(nd)] -
                                   mesh_->face_zb[uf];
                 if (hg > k::kDryDepth) {
-                    const double ag = k::areaOfDepth(g, hg);
-                    speed = std::max(speed,
-                                     std::fabs(cell_u_[uo]) +
-                                         k::celerity(ag, k::widthOfDepth(g, hg)));
+                    // Same edit for the ghost: an implicit-covered face
+                    // integrates the ghost's acoustic exchange in the head
+                    // system. A pressurized ghost feeding a FREE cell is the
+                    // filling bore, stays explicit (fmode == kNone there),
+                    // and keeps its full celerity.
+                    if (fmode == PressurizedHeadSolver::kFull && !g.is_open &&
+                        hg >= g.y_crown) {
+                        speed = std::max(speed, std::fabs(cell_u_[uo]));
+                    } else {
+                        perf::count(perf::n_fv_geom_area);
+                        perf::count(perf::n_fv_geom_width);
+                        const double ag = k::areaOfDepth(g, hg);
+                        speed = std::max(speed,
+                                         std::fabs(cell_u_[uo]) +
+                                             k::celerity(ag,
+                                                         k::widthOfDepth(g, hg)));
+                    }
                 }
             }
         }
@@ -512,6 +758,40 @@ double ExplicitFvSolver::censusDt() const {
         }
     }
 
+    // dt-argmin attribution (slot program R0): classify the binding element
+    // once per census — pressurized / taper-band / free from the argmin
+    // face's wettest side (ghost included), or the node bound when a node
+    // loop below lowers dt past the face census. Telemetry only.
+    bool node_owns_dt = false;
+    auto count_argmin = [&]() {
+        if (node_owns_dt) { ++dt_argmin_node_; return; }
+        if (trace_face < 0) return;
+        const auto uf = static_cast(trace_face);
+        const int cl = mesh_->face_cl[uf], cr = mesh_->face_cr[uf];
+        const int nd = mesh_->face_node[uf];
+        double h_max = 0.0;
+        const FvGeometry* gm = nullptr;
+        auto consider = [&](int cell, double h) {
+            if (cell < 0 || h <= h_max) return;
+            h_max = h;
+            gm = &mesh_->geom[static_cast(
+                mesh_->cell_geom[static_cast(cell)])];
+        };
+        if (cl >= 0) consider(cl, state_->cell_h[static_cast(cl)]);
+        if (cr >= 0) consider(cr, state_->cell_h[static_cast(cr)]);
+        if (nd >= 0) {
+            const int other = (cl >= 0) ? cl : cr;
+            if (other >= 0)
+                consider(other,
+                         state_->node_head[static_cast(nd)] -
+                             mesh_->face_zb[uf]);
+        }
+        if (!gm) return;
+        if      (h_max >= gm->y_full)  ++dt_argmin_pressurized_;
+        else if (h_max >= gm->y_crown) ++dt_argmin_band_;
+        else                           ++dt_argmin_free_;
+    };
+
     // Diagnostic: report which face is setting the step, and what its dx and
     // wave speed are. Explaining a substep count needs the argmin, not the min.
     if (kDtTrace) {
@@ -559,29 +839,34 @@ double ExplicitFvSolver::censusDt() const {
     // on does not mean tiering runs: RK2 disables the LTS path outright, and
     // a water-quality run (species FCT needs a synchronous sweep) degenerates
     // assignTiers() to K = 1. Both fall through to the global path, and
-    // skipping the node term there silently reproduced FV_NODE_DT NONE —
-    // with its measured 10-50× accuracy loss — while the option still read
-    // STABILITY.
-    //
-    // FV_NODE_DT NONE is honoured here as well, so the option means the same
-    // thing on both paths — and only under SEMI_IMPLICIT coupling, because
-    // for explicitly coupled nodes the bound buys stability, not accuracy,
-    // and there is no opting out of it.
+    // skipping the node term there silently dropped the bound — with its
+    // measured 10-50× accuracy loss — while nothing had asked for that.
     //
     // The relaxation was swept rather than assumed: with tiering on, 1×, 4×,
     // 16×, 64× and unbounded gave 14.7 / 7.3 / 5.1 / 5.1 / 5.0 s at 7.2 / 7.2 /
     // 7.1 / 7.2 / 7.2 % mean agreement.
-    if (opts_.node_coupling == NodeCoupling::SEMI_IMPLICIT &&
-        (ltsEligible() || opts_.node_dt_limit == NodeDtLimit::NONE)) {
+    if (ltsEligible()) {
         if (dt >= std::numeric_limits::max() * 0.5) dt = 1.0e30;
+        count_argmin();
         return dt;
     }
     for (int n = 0; n < nn; ++n) {
         const auto un = static_cast(n);
         if (mesh_->node_kind[un] == kNodeVirtual) continue;
-        // Algebraic junctions have no volume state and hence no stability or
-        // accuracy bound of their own — their head is solved, not integrated.
-        if (!node_alg_.empty() && node_alg_[un]) continue;
+        // Algebraic junctions: no storage bound, but the ghost-feedback bound
+        // above still applies. On this path (tiering not running) there is
+        // nowhere to put it but the global step.
+        if (!node_alg_.empty() && node_alg_[un]) {
+            if (opts_.node_feedback_dt) {
+                // A junction the implicit pass folds has no explicit
+                // ghost-feedback loop left to bound — its head is a row of
+                // the SPD system (slot program R2).
+                if (press_edit && nodePressFolded(n)) continue;
+                const double dt_n = algebraicNodeStableDt(n);
+                if (dt_n < dt) { dt = dt_n; node_owns_dt = true; }
+            }
+            continue;
+        }
         // Outfalls: head imposed, volume never integrated — nothing to bound
         // (mirrors nodeStableDt's skip, same rationale).
         if (mesh_->node_kind[un] == kNodeOutfall) continue;
@@ -604,300 +889,62 @@ double ExplicitFvSolver::censusDt() const {
             const double t = k::widthOfDepth(g, h);
             if (t <= 0.0) continue;
             const double c_wave = k::celerity(state_->cell_a[uc], t);
-            dt = std::min(dt, k::faceCflDt(opts_.cfl, as / t, cell_u_[uc], c_wave));
+            const double dt_n =
+                k::faceCflDt(opts_.cfl, as / t, cell_u_[uc], c_wave);
+            if (dt_n < dt) { dt = dt_n; node_owns_dt = true; }
         }
     }
 
     if (dt >= std::numeric_limits::max() * 0.5) dt = 1.0e30;
+    count_argmin();
     return dt;
 }
 
 // ===========================================================================
-// Scalar reconstruction — the anti-diffusion layer (plan §3.2)
+// Species transport — forwarders to the shared kernels (phase E0)
 // ===========================================================================
-
-void ExplicitFvSolver::reconstructScalars(double dt) {
-    const int ns = state_->n_species;
-    if (ns <= 0) return;
-
-    const int nc = mesh_->n_cells();
-    const int nf = mesh_->n_faces();
-
-    for (int s = 0; s < ns; ++s) {
-        const auto sbase = static_cast(s) * static_cast(nc);
-        const auto fbase = static_cast(s) * static_cast(nf);
-
-        // ---- per-cell limited slope along the chain ------------------------
-        if (opts_.scalar_scheme == ScalarScheme::UPWIND) {
-            std::fill(cell_slope_.begin(), cell_slope_.end(), 0.0);
-        } else {
-            for (int ch = 0; ch < mesh_->n_chains(); ++ch) {
-                const int b = mesh_->chain_ptr[static_cast(ch)];
-                const int e = mesh_->chain_ptr[static_cast(ch) + 1];
-                for (int i = b; i < e; ++i) {
-                    const int c = mesh_->chain_cells[static_cast(i)];
-                    const auto uc = static_cast(c);
-                    if (i == b || i == e - 1) { cell_slope_[uc] = 0.0; continue; }
-                    const int cm = mesh_->chain_cells[static_cast(i - 1)];
-                    const int cp = mesh_->chain_cells[static_cast(i + 1)];
-                    const auto um = static_cast(cm);
-                    const auto up = static_cast(cp);
-                    const double dm = 0.5 * (mesh_->cell_dx[um] + mesh_->cell_dx[uc]);
-                    const double dp = 0.5 * (mesh_->cell_dx[uc] + mesh_->cell_dx[up]);
-                    const double gm = (state_->cell_phi[sbase + uc] -
-                                       state_->cell_phi[sbase + um]) / dm;
-                    const double gp = (state_->cell_phi[sbase + up] -
-                                       state_->cell_phi[sbase + uc]) / dp;
-                    // Chain-space slope → the cell's OWN axis.
-                    cell_slope_[uc] =
-                        limitSlope(gm, gp, opts_.limiter) *
-                        static_cast(mesh_->chain_dir[static_cast(i)]);
-                }
-            }
-        }
-
-        // ---- face values ----------------------------------------------------
-        for (const int f : active_faces_) {
-            const auto uf = static_cast(f);
-            const int cl = mesh_->face_cl[uf];
-            const int cr = mesh_->face_cr[uf];
-            // A node ghost presents the interior cell's own value (zero
-            // gradient). That keeps a uniform field uniform under inflow, which
-            // is the §6.11(a) gate, without inventing a node concentration this
-            // solver does not track.
-            const int el = (cl >= 0) ? cl : cr;
-            const int er = (cr >= 0) ? cr : cl;
-            const auto ul = static_cast(el);
-            const auto ur = static_cast(er);
-
-            double phil = state_->cell_phi[sbase + ul];
-            double phir = state_->cell_phi[sbase + ur];
-            if (cl >= 0) {
-                const double sign = static_cast(mesh_->face_dir_l[uf]);
-                phil += sign * cell_slope_[ul] * 0.5 * mesh_->cell_dx[ul];
-            }
-            if (cr >= 0) {
-                const double sign = -static_cast(mesh_->face_dir_r[uf]);
-                phir += sign * cell_slope_[ur] * 0.5 * mesh_->cell_dx[ur];
-            }
-
-            if (opts_.scalar_scheme == ScalarScheme::QUICKEST_ULTIMATE) {
-                // QUICKEST needs TWO upstream cells. Where the stencil exists
-                // it is 3rd order; where it does not — the first cell below a
-                // manhole with several inflowing pipes, or a short conduit —
-                // it degrades, and the MUSCL value computed above is the
-                // fallback. In COARSE mode a sewer spends much of its length in
-                // that degraded regime, which is exactly what the §6.11(d)
-                // junction-density sweep is there to quantify.
-                const bool fwd = (f_sstar_[uf] >= 0.0);
-                const int cu = fwd ? cl : cr;         // upwind cell
-                const int cd = fwd ? cr : cl;         // downwind cell
-                if (cu >= 0 && cd >= 0) {
-                    const auto uu = static_cast(cu);
-                    const int chn = mesh_->cell_chain[uu];
-                    const int pos = mesh_->cell_chain_pos[uu];
-                    const int cb = mesh_->chain_ptr[static_cast(chn)];
-                    const int ce = mesh_->chain_ptr[static_cast(chn) + 1];
-                    // Step one further upstream ALONG THE FLOW, which is the
-                    // downwind cell's opposite neighbour in the chain.
-                    const int dpos = mesh_->cell_chain_pos[static_cast(cd)];
-                    const int upos = pos + (pos - dpos);   // one further upstream
-                    if (upos >= 0 && upos < ce - cb) {
-                        const int cuu = mesh_->chain_cells[
-                            static_cast(cb + upos)];
-                        const auto uuu = static_cast(cuu);
-                        const double pu  = state_->cell_phi[sbase + uu];
-                        const double pd  = state_->cell_phi[sbase + static_cast(cd)];
-                        const double puu = state_->cell_phi[sbase + uuu];
-                        const double dx  = mesh_->cell_dx[uu];
-                        const double cr_no = std::min(
-                            1.0, std::fabs(cell_u_[uu]) * dt / std::max(dx, 1.0e-12));
-                        const double q = pd - 2.0 * pu + puu;
-                        double pf = 0.5 * (pd + pu) - 0.5 * cr_no * (pd - pu) -
-                                    (1.0 - cr_no * cr_no) / 6.0 * q;
-                        // ULTIMATE monotonicity limiter (Leonard 1991), applied
-                        // in normalized variables.
-                        const double den = pd - puu;
-                        if (std::fabs(den) > 1.0e-30) {
-                            const double un_ = (pu - puu) / den;
-                            if (un_ <= 0.0 || un_ >= 1.0) {
-                                pf = pu;                       // non-monotone ⇒ upwind
-                            } else {
-                                double fn = (pf - puu) / den;
-                                const double hi = std::min(1.0, un_ / std::max(cr_no, 1.0e-12));
-                                fn = std::clamp(fn, un_, hi);
-                                pf = puu + fn * den;
-                            }
-                        } else {
-                            pf = pu;
-                        }
-                        if (fwd) phil = pf; else phir = pf;
-                    }
-                }
-            }
-
-            // Local-extremum clamp — the last line of defence for the "no new
-            // extrema, no negative concentrations" contract (§6.11b). Both
-            // higher-order reconstructions are TVD for PURE advection on a
-            // fixed grid; here the cell areas are evolving underneath them
-            // (reflections, wetting, drying), and QUICKEST's normalized-variable
-            // limiter measurably loses monotonicity in that regime. Clamping the
-            // face value into the bracket its own two cells span costs nothing
-            // where the scheme is already monotone and restores the guarantee
-            // where it is not.
-            if (opts_.scalar_scheme != ScalarScheme::UPWIND) {
-                const double a = state_->cell_phi[sbase + ul];
-                const double b = state_->cell_phi[sbase + ur];
-                const double lo = std::min(a, b);
-                const double hi = std::max(a, b);
-                phil = std::clamp(phil, lo, hi);
-                phir = std::clamp(phir, lo, hi);
-            }
-
-            f_phi_l_[fbase + uf] = phil;
-            f_phi_r_[fbase + uf] = phir;
-        }
-
-        // ---- flux assembly + Zalesak limiting ------------------------------
-        limitSpeciesFluxes(s, dt);
-    }
+//
+// The scalar reconstruction, Zalesak FCT flux limiting, and implicit
+// dispersion bodies moved VERBATIM to
+// transport/fvkernels/SpeciesTransportKernels.cpp so the standalone Eulerian
+// ARD engine shares this exact implementation
+// (plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md, D-UT1 as amended).
+// This solver supplies its members through a non-owning view; behavior is
+// bitwise-identical to the pre-move code.
+
+transport::fvkernels::SpeciesKernelView ExplicitFvSolver::speciesKernelView() {
+    transport::fvkernels::SpeciesKernelView v;
+    v.mesh          = mesh_;
+    v.state         = state_;
+    v.scalar_scheme = opts_.scalar_scheme;
+    v.limiter       = opts_.limiter;
+    v.dispersion    = opts_.dispersion;
+    v.hllc          = hllc_;
+    v.f_mass        = &f_mass_;
+    v.f_sstar       = &f_sstar_;
+    v.f_state_l     = &f_state_l_;
+    v.f_state_r     = &f_state_r_;
+    v.f_flux        = &f_flux_;
+    v.cell_u        = &cell_u_;
+    v.cell_active   = &cell_active_;
+    v.active_faces  = &active_faces_;
+    v.f_phi_l       = &f_phi_l_;
+    v.f_phi_r       = &f_phi_r_;
+    v.f_phi_flux    = &f_phi_flux_;
+    v.cell_slope    = &cell_slope_;
+    v.lo_flux       = &lo_flux_;
+    v.anti_flux     = &anti_flux_;
+    v.td            = &td_;
+    v.anew          = &anew_;
+    v.rplus         = &rplus_;
+    v.rminus        = &rminus_;
+    return v;
 }
 
-/**
- * @brief Assemble the face species fluxes and limit them (Zalesak FCT).
- *
- * @details Bracketing the reconstructed FACE value between its two cells is
- *          necessary but NOT sufficient for the discrete maximum principle:
- *          under reversing, unsteady flow with the cell areas evolving
- *          underneath the scalar, a face value legitimately inside its bracket
- *          can still drain more solute than its donor cell holds. Measured:
- *          QUICKEST-ULTIMATE produced −1.3e-3 on a step-function advection case
- *          with wall reflections, which is not acceptable in a water-quality
- *          model.
- *
- *          The fix has to limit the FLUX, not the result. Clipping the updated
- *          concentration would enforce the bound but destroy exact solute
- *          conservation (§6.11c) — the two properties trade off, and Zalesak
- *          (1979) is the construction that keeps both: blend each face's
- *          high-order flux back toward first-order upwind by the largest factor
- *          that no incident cell's bound rejects. The SAME limited flux updates
- *          both incident cells, so conservation is untouched.
- */
-void ExplicitFvSolver::limitSpeciesFluxes(int species, double dt) {
-    const int nc = mesh_->n_cells();
-    const int nf = mesh_->n_faces();
-    const auto cbase = static_cast(species) *
-                       static_cast(nc);
-    const auto fbase = static_cast(species) *
-                       static_cast(nf);
-
-    lo_flux_.assign(static_cast(nf), 0.0);
-    anti_flux_.assign(static_cast(nf), 0.0);
-
-    // Low-order (first-order upwind on the sign of the mass flux) and the
-    // antidiffusive remainder.
-    for (const int f : active_faces_) {
-        const auto uf = static_cast(f);
-        const int cl = mesh_->face_cl[uf];
-        const int cr = mesh_->face_cr[uf];
-        const auto ul = static_cast((cl >= 0) ? cl : cr);
-        const auto ur = static_cast((cr >= 0) ? cr : cl);
-        const double fm = f_mass_[uf];
-        const double lo = fm * ((fm >= 0.0) ? state_->cell_phi[cbase + ul]
-                                            : state_->cell_phi[cbase + ur]);
-        const double hi = k::speciesFlux(f_state_l_[uf], f_state_r_[uf],
-                                         adjustedFlux(f), f_phi_l_[fbase + uf],
-                                         f_phi_r_[fbase + uf], hllc_);
-        lo_flux_[uf]   = lo;
-        anti_flux_[uf] = hi - lo;
-    }
-
-    // Transported-diffused state under the low-order flux alone, plus the
-    // local bounds it and its neighbours span.
-    td_.assign(static_cast(nc), 0.0);
-    anew_.assign(static_cast(nc), 0.0);
-    for (int c = 0; c < nc; ++c) {
-        const auto uc = static_cast(c);
-        if (!cell_active_[uc]) { td_[uc] = state_->cell_phi[cbase + uc];
-                                 anew_[uc] = state_->cell_a[uc]; continue; }
-        const int faces[2]    = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
-        const int8_t sides[2] = {mesh_->cell_side0[uc], mesh_->cell_side1[uc]};
-        double dA = 0.0, dm = 0.0;
-        for (int e = 0; e < 2; ++e) {
-            const auto uf = static_cast(faces[e]);
-            const double sg = (sides[e] == 0) ? -1.0 : 1.0;
-            dA += sg * f_mass_[uf];
-            dm += sg * lo_flux_[uf];
-        }
-        const double inv_dx = 1.0 / mesh_->cell_dx[uc];
-        const double a_new = std::max(0.0, state_->cell_a[uc] + dt * dA * inv_dx);
-        anew_[uc] = a_new;
-        const double m = state_->cell_a[uc] * state_->cell_phi[cbase + uc] +
-                         dt * dm * inv_dx;
-        td_[uc] = (a_new > k::kDryArea) ? m / a_new : state_->cell_phi[cbase + uc];
-    }
-
-    rplus_.assign(static_cast(nc), 1.0);
-    rminus_.assign(static_cast(nc), 1.0);
-    for (int c = 0; c < nc; ++c) {
-        const auto uc = static_cast(c);
-        if (!cell_active_[uc]) continue;
-        const int faces[2]    = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
-        const int8_t sides[2] = {mesh_->cell_side0[uc], mesh_->cell_side1[uc]};
-
-        double pmax = std::max(state_->cell_phi[cbase + uc], td_[uc]);
-        double pmin = std::min(state_->cell_phi[cbase + uc], td_[uc]);
-        double pplus = 0.0, pminus = 0.0;
-        for (int e = 0; e < 2; ++e) {
-            const auto uf = static_cast(faces[e]);
-            const int cl = mesh_->face_cl[uf];
-            const int cr = mesh_->face_cr[uf];
-            const int nb = (cl == c) ? cr : cl;
-            if (nb >= 0) {
-                const auto un = static_cast(nb);
-                pmax = std::max({pmax, state_->cell_phi[cbase + un], td_[un]});
-                pmin = std::min({pmin, state_->cell_phi[cbase + un], td_[un]});
-            }
-            const double sg = (sides[e] == 0) ? -1.0 : 1.0;
-            const double a = sg * anti_flux_[uf];
-            if (a > 0.0) pplus += a; else pminus -= a;
-        }
-        const double cap = anew_[uc] * mesh_->cell_dx[uc] / dt;
-        if (pplus  > 0.0) rplus_[uc]  = std::min(1.0, (pmax - td_[uc]) * cap / pplus);
-        if (pminus > 0.0) rminus_[uc] = std::min(1.0, (td_[uc] - pmin) * cap / pminus);
-        rplus_[uc]  = std::max(0.0, rplus_[uc]);
-        rminus_[uc] = std::max(0.0, rminus_[uc]);
-    }
-
-    for (const int f : active_faces_) {
-        const auto uf = static_cast(f);
-        const double a = anti_flux_[uf];
-        double coef = 1.0;
-        if (a != 0.0) {
-            const int cl = mesh_->face_cl[uf];
-            const int cr = mesh_->face_cr[uf];
-            // The face contributes −a to its LEFT cell and +a to its RIGHT one.
-            const double from_r = (cr >= 0)
-                ? ((a > 0.0) ? rplus_[static_cast(cr)]
-                             : rminus_[static_cast(cr)])
-                : 1.0;
-            const double from_l = (cl >= 0)
-                ? ((a > 0.0) ? rminus_[static_cast(cl)]
-                             : rplus_[static_cast(cl)])
-                : 1.0;
-            coef = std::min(from_r, from_l);
-        }
-        f_phi_flux_[fbase + uf] = lo_flux_[uf] + coef * a;
-    }
+void ExplicitFvSolver::reconstructScalars(double dt) {
+    transport::fvkernels::reconstructScalars(speciesKernelView(), dt);
 }
 
-/// The flux record with the positivity-scaled mass flux substituted in, so the
-/// species rides on exactly the water the hydrodynamic update moved.
-kernels::FaceFlux ExplicitFvSolver::adjustedFlux(int face) const {
-    kernels::FaceFlux f = f_flux_[static_cast(face)];
-    f.mass = f_mass_[static_cast(face)];
-    return f;
-}
 
 // ===========================================================================
 // Second-order state reconstruction (FV_ORDER 2)
@@ -923,6 +970,7 @@ kernels::FaceFlux ExplicitFvSolver::adjustedFlux(int face) const {
  * hydrostatic flux difference no longer vanishes at rest on its own.
  */
 void ExplicitFvSolver::reconstructState() {
+    perf::GatedTimer _pt(perf::sec_fv_reconstruct);
     const int nc = mesh_->n_cells();
     if (opts_.order < 2) {
         std::fill(cell_eta_slope_.begin(), cell_eta_slope_.end(), 0.0);
@@ -944,7 +992,11 @@ void ExplicitFvSolver::reconstructState() {
         const auto uc = static_cast(c);
         const double h = state_->cell_h[uc];
         const double fall = std::fabs(mesh_->cell_dzdx[uc]) * mesh_->cell_dx[uc];
-        cell_ho2_[uc] = (h > k::kDryDepth && fall < 0.5 * h) ? char{1} : char{0};
+        // TPA-flagged cells stay first-order: the HO2 bed source and slope
+        // extrapolation evaluate free-surface geometry, which a pressurized
+        // (possibly sub-atmospheric) cell no longer has (#156).
+        cell_ho2_[uc] = (h > k::kDryDepth && fall < 0.5 * h && !tpaCell(uc))
+                            ? char{1} : char{0};
     }
 
     for (int ch = 0; ch < mesh_->n_chains(); ++ch) {
@@ -1020,6 +1072,22 @@ void ExplicitFvSolver::faceSide(int face, int cell, int node, double zstar,
     const FvGeometry* g = nullptr;
     double eta = 0.0, h_raw = 0.0, u = 0.0;
     z_side = 0.0;
+    // Set when this side is a cell presented at its stored centred depth, so
+    // the closure at h_raw is exactly what cacheClosure() holds for it.
+    bool centred = false;
+    std::size_t uc_cached = 0;
+    // Set when this side is a ghost built from the node's own head (a vented
+    // node's free surface), as opposed to a pass-through far cell or a
+    // closed-end mirror: only that ghost takes the free-surface celerity cap.
+    bool node_head_ghost = false;
+
+    // The section this FACE reconstructs in — the same one for both sides, so
+    // the Riemann problem is posed between states in a single geometry. It is
+    // the cells' own section everywhere except at a width step between two
+    // conduits (mesh.face_geom), where using each side's own section would
+    // leave the step's wall exerting no force on the flow.
+    const FvGeometry* gf =
+        &mesh_->geom[static_cast(mesh_->face_geom[uf])];
 
     if (cell >= 0) {
         const auto uc = static_cast(cell);
@@ -1033,6 +1101,8 @@ void ExplicitFvSolver::faceSide(int face, int cell, int node, double zstar,
             h_raw  = state_->cell_h[uc];
             u      = static_cast(dir) * cell_u_[uc];
             z_side = mesh_->cell_zb[uc];
+            centred   = true;
+            uc_cached = uc;
         } else {
             // Extrapolate to the face along the cell's own axis. `half` is
             // signed: positive toward the cell's downstream end. The BED is
@@ -1066,6 +1136,7 @@ void ExplicitFvSolver::faceSide(int face, int cell, int node, double zstar,
             h_raw = std::max(0.0, eta - mesh_->face_zb[uf]);
             u     = u_interior;
             z_side = mesh_->face_zb[uf];
+            node_head_ghost = true;
             // PASS-THROUGH junction: the ghost presents the FAR cell's full
             // centred state — surface, depth, bed — so together with the far
             // velocity (computeFaceFlux) the two node faces reproduce the
@@ -1091,6 +1162,7 @@ void ExplicitFvSolver::faceSide(int face, int cell, int node, double zstar,
                         eta    = cell_eta_[uoc];
                         h_raw  = state_->cell_h[uoc];
                         z_side = mesh_->cell_zb[uoc];
+                        node_head_ghost = false;
                     }
                 }
             }
@@ -1106,23 +1178,135 @@ void ExplicitFvSolver::faceSide(int face, int cell, int node, double zstar,
         }
     }
 
-    i1_raw = (h_raw > k::kDryDepth)
-                 ? k::i1OfDepth(*g, h_raw, k::areaOfDepth(*g, h_raw)) : 0.0;
-    if (measure_only) { out = k::FaceState{}; return; }
+    // measure_only asks for the reconstructed BED only — it is pass 1 of
+    // computeFaceFlux, whose sole output is z* = max(z_L, z_R). Every z_side
+    // branch above is arithmetic on stored bed values (cell_zb, the second-order
+    // dzdx extrapolation, face_zb, or the pass-through far cell's bed), so the
+    // geometry below is not needed: leaving it here cost two virtual
+    // getAofY/getRofY-class evaluations per face side whose result the probe
+    // pass discarded (its i1 out-param is written twice and never read).
+    if (measure_only) { i1_raw = 0.0; out = k::FaceState{}; return; }
+
+    // TPA pressurized side (issue #156 Phase 4): the closure line extends to
+    // hs < 0, so neither dry cutoff applies — the pipe is full of water at
+    // (possibly sub-atmospheric) piezometric head. Which regime a SIDE uses:
+    // a cell side follows its own cell's flag; a node ghost follows the
+    // interior cell's flag only when the node is SEALED (SUR_DEPTH > 0) —
+    // a vented node's ghost carries hs = 0 by construction (plan §A3); a
+    // closed-end mirror ghost mirrors the interior regime.
+    bool tpa_side = false;
+    if (tpa_) {
+        if (cell >= 0) {
+            tpa_side = tpaCell(static_cast(cell));
+        } else {
+            const int other2 = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                         : mesh_->face_cr[uf];
+            if (other2 >= 0) {
+                const bool interior_tpa =
+                    tpaCell(static_cast(other2));
+                if (node >= 0) {
+                    tpa_side = interior_tpa &&
+                        mesh_->node_sur_depth[static_cast(node)] > 0.0;
+                } else {
+                    tpa_side = interior_tpa;
+                }
+            }
+        }
+    }
+    if (tpa_side) {
+        // Use the UNCLAMPED piezometric depth (eta − z_side): every h_raw
+        // branch above floors at 0, which is wrong for a sub-atmospheric
+        // column whose head can sit below the local invert.
+        i1_raw = k::tpaI1OfDepth(*g, eta - z_side);
+        const double h_star_t = eta - zstar;          // signed; no clamp
+        double a_t = k::tpaAreaOfDepth(*gf, h_star_t);
+        if (a_t < k::kDryArea) a_t = k::kDryArea;     // vacuum floor guard
+        out.a  = a_t;
+        out.u  = u;
+        out.q  = a_t * u;
+        out.c  = k::celerity(a_t, gf->t_slot);        // acoustic celerity
+        out.i1 = k::tpaI1OfDepth(*gf, h_star_t);
+        out.press = (mixed_wave_ && mw_rh_) ? uint8_t{1} : uint8_t{0};
+        return;
+    }
+
+    // i1_raw stays in the CELL's own section — it is the cell's true
+    // hydrostatic moment, and the difference from the reconstructed one is the
+    // correction that puts the balance back (computeFaceFlux).
+    // ...and only a CELL side's is ever read: computeFaceFlux books the
+    // Audusse correction as a cell source and drops a ghost side's i1_raw
+    // (`(cl >= 0) ? … : 0.0`), so evaluating it there was pure waste — one
+    // area and one I₁ per node face per flux, and per node-solve trial.
+    if (cell >= 0 && h_raw > k::kDryDepth) {
+        if (centred) {
+            i1_raw = cell_i1_[uc_cached];   // I₁(cell_h), cached at the write
+        } else {
+            // Second-order side: reconstructed depth, no cache — one locate.
+            i1_raw = k::closureI1(g->closure_tbl, h_raw);
+            perf::count(perf::n_fv_geom_i1);
+        }
+    } else {
+        i1_raw = 0.0;
+    }
 
     const double h_star = std::max(0.0, eta - zstar);
     if (h_star <= k::kDryDepth) {
         out = k::FaceState{};
         return;
     }
-    out.a  = k::areaOfDepth(*g, h_star);
+    // …while the reconstructed state is evaluated in the FACE's section, which
+    // both sides share. Where they are the same section (every prismatic face)
+    // this is the identical computation — and where the reconstructed depth IS
+    // the stored depth (the higher-bed side, z* being its own bed), it is the
+    // cached one: same function, same arguments, same bits.
+    // Slot/free-surface interface treatment (OPENSWMM_FV_MIXED_WAVE, on by
+    // default): a side standing in the slot is flagged so waveSpeeds can bound
+    // the wave crossing into a free-surface neighbour by the bore speed. A
+    // vented junction's own-head ghost never takes part (press 2): marked
+    // free, a face whose cell side stands in the slot too (a whole tunnel
+    // pressurized 50 m above the junction crowns) became a "slot/free" pair
+    // and the bound cut the acoustic waves at every lateral junction — the
+    // node solve then found no head below its ceiling, clamped at the rim
+    // and booked 63 000 m³ of "flooding" at junctions whose published depth
+    // never exceeded half their rim (Klaver Example_02, 2026-09-13). The
+    // entrance lock the bound exists for lives at the INTERIOR slot/free
+    // faces (measured: the bound alone releases it, a ghost celerity cap
+    // alone does not). That cap — the vented ghost held to the free-surface
+    // crown celerity — was removed the same day: with the ghost in the slot
+    // and the cell beside it momentarily free it fed a 20× overloaded 0.5 ft
+    // pipe through a near-upwind flux at 4.4 cfs, a 2× over-conveying limit
+    // cycle. A sealed node's ghost carries the slot celerity like any side.
+    auto finish = [&](k::FaceState& o) {
+        if (!mixed_wave_) return;
+        o.press = (mw_rh_ && !gf->is_open && h_star >= gf->y_full) ? uint8_t{1} : uint8_t{0};
+        if (node_head_ghost && node >= 0 &&
+            mesh_->node_sur_depth[static_cast(node)] <= 0.0)
+            o.press = mw_rh_ ? uint8_t{2} : uint8_t{0};
+    };
+    if (centred && gf == g && h_star == h_raw) {
+        out.a  = cell_ah_[uc_cached];
+        out.u  = u;
+        out.q  = out.a * u;
+        out.c  = k::celerity(out.a, cell_t_[uc_cached]);
+        out.i1 = cell_i1_[uc_cached];
+        finish(out);
+        return;
+    }
+    perf::count(perf::n_fv_geom_area);
+    perf::count(perf::n_fv_geom_width);
+    perf::count(perf::n_fv_geom_i1);
+    // Fused: A, T and I₁ from one panel locate.
+    const k::ClosureEval e = k::closureEval(gf->closure_tbl, h_star);
+    out.a  = e.a;
     out.u  = u;
-    out.q  = out.a * u;
-    out.c  = k::celerity(out.a, k::widthOfDepth(*g, h_star));
-    out.i1 = k::i1OfDepth(*g, h_star, out.a);
+    out.q  = e.a * u;
+    out.c  = k::celerity(e.a, e.t);
+    out.i1 = e.i1;
+    finish(out);
 }
 
 void ExplicitFvSolver::computeFluxes() {
+    perf::GatedTimer _pt(perf::sec_fv_flux);
     const int n_act = static_cast(active_faces_.size());
 
 #ifdef SWMM_USE_OPENMP
@@ -1133,7 +1317,7 @@ void ExplicitFvSolver::computeFluxes() {
     total_flux_ += n_act;
 }
 
-void ExplicitFvSolver::computeFaceFlux(int f) {
+void ExplicitFvSolver::computeFaceFlux(int f, bool mass_only) {
     {
         const auto uf = static_cast(f);
         const int cl = mesh_->face_cl[uf];
@@ -1200,8 +1384,57 @@ void ExplicitFvSolver::computeFaceFlux(int f) {
         faceSide(f, cl, nd, zstar, mesh_->face_dir_l[uf], u_int, L, i1l, zdummy, false);
         faceSide(f, cr, nd, zstar, mesh_->face_dir_r[uf], u_int, R, i1r, zdummy, false);
 
+        // Mass-only trial (plan Phase 1c): the algebraic node solve reads back
+        // f_mass_ alone per trial head. Same reconstruction, same wave speeds,
+        // same gate and culvert decisions — riemannMassFlux is bit-identical to
+        // riemannFlux().mass — so the residual sequence, hence the root and the
+        // final full flux, are unchanged; what is skipped is the momentum flux,
+        // the contact speed, the Audusse corrections and ~130 bytes of stores.
+        if (mass_only) {
+            double mass = k::riemannMassFlux(L, R);
+            const uint8_t gate_m = mesh_->face_gate[uf];
+            if (gate_m != 0 && ((mass > 0.0 && (gate_m & 1u)) ||
+                                (mass < 0.0 && (gate_m & 2u))))
+                mass = 0.0;
+            const int cvr_m = mesh_->face_culvert[uf];
+            if (cvr_m >= 0 && mass > 0.0 && nd >= 0) {
+                const auto ucv = static_cast(cvr_m);
+                const FvGeometry& gc = mesh_->geom[
+                    static_cast(mesh_->conduit_section[ucv])];
+                const double head =
+                    state_->node_head[static_cast(nd)] - mesh_->face_zb[uf];
+                double dqdh = 0.0;
+                const double q_cap = hydkernels::culvertInflow(
+                    mass, head, gc.y_full, gc.xs.a_full, mesh_->conduit_slope[ucv],
+                    mesh_->conduit_culvert_curve[ucv],
+                    mesh_->conduit_culvert_mitered[ucv] != 0, dqdh);
+                if (q_cap < mass) {
+                    mass = q_cap;
+                    inlet_control_[ucv] = 1;
+                }
+            }
+            f_mass_[uf] = mass;
+            return;
+        }
+
         k::FaceFlux fl = k::riemannFlux(L, R);
 
+        // Non-prismatic pass-through junction — RESOLVED 2026-08-13 by giving
+        // the face its own section (mesh.face_geom, see faceSide). Both sides
+        // of a width step are now reconstructed in ONE shared section, so the
+        // pair poses a single well-posed Riemann problem and the per-side
+        // hydrostatic correction below IS the wall-pressure term.
+        //
+        // The earlier additive closures failed because they were bolted onto a
+        // flux that was ill-posed to begin with: each side was reconstructed in
+        // its OWN geometry, so no added term could fix it and each one
+        // double-counted (p2d-sub-short nx=20: splice-only l1 0.186, plus
+        // convective ½Q̂²Δ(1/A) → 0.313, plus wall-pressure ½gΔI1(h̄) → 0.286).
+        // With the shared face section instead, the SWASHES §3.5 family goes
+        // from l1 5.4-16.5% to 0.17-0.60% and the jump on p2d-jump-long lands
+        // within half a cell (7.50 m → 0.50 m). Prismatic decks are
+        // bit-identical: there the face section IS the cells' section.
+
         // Flap gate. A check valve, not a wall: the face stays open while the
         // flux runs the permitted way and closes the instant it would reverse.
         // Closing it means MIRRORING the interior state across the face — equal
@@ -1230,13 +1463,16 @@ void ExplicitFvSolver::computeFaceFlux(int f) {
         // compares Link.newFlow against a per-barrel capacity.
         const int cvr = mesh_->face_culvert[uf];
         if (cvr >= 0 && fl.mass > 0.0 && nd >= 0) {
-            const FvGeometry& gc = mesh_->geom[static_cast(cvr)];
+            const auto ucv = static_cast(cvr);
+            const FvGeometry& gc = mesh_->geom[
+                static_cast(mesh_->conduit_section[ucv])];
             const double head =
                 state_->node_head[static_cast(nd)] - mesh_->face_zb[uf];
             double dqdh = 0.0;
             const double q_cap = hydkernels::culvertInflow(
-                fl.mass, head, gc.y_full, gc.xs.a_full, gc.slope,
-                gc.culvert_curve, gc.culvert_mitered != 0, dqdh);
+                fl.mass, head, gc.y_full, gc.xs.a_full, mesh_->conduit_slope[ucv],
+                mesh_->conduit_culvert_curve[ucv],
+                mesh_->conduit_culvert_mitered[ucv] != 0, dqdh);
             if (q_cap < fl.mass) {
                 // Inlet control means the INLET is the control section, so the
                 // face becomes a prescribed-discharge boundary and its flux is
@@ -1256,15 +1492,21 @@ void ExplicitFvSolver::computeFaceFlux(int f) {
 
         f_mass_[uf]  = fl.mass;
         f_mom_[uf]   = fl.mom;
-        f_sstar_[uf] = fl.sstar;
         f_state_l_[uf] = L;
         f_state_r_[uf] = R;
-        f_flux_[uf]    = fl;
+        // Species-only stores (plan Phase 1g): the contact speed and the whole
+        // flux record are read by the transport kernels alone (the implicit
+        // head update only WRITES them, to keep the species copies coherent),
+        // so a run without species skips the 48 bytes per face flux. The face
+        // STATES stay: the degree-1 fallback and the implicit view read them.
+        if (state_->n_species > 0) {
+            f_sstar_[uf] = fl.sstar;
+            f_flux_[uf]  = fl;
+        }
         // Audusse well-balanced correction — a CELL source, so it exists only
         // on sides that are cells.
         f_corr_l_[uf] = (cl >= 0) ? k::kGravity * (i1l - L.i1) : 0.0;
         f_corr_r_[uf] = (cr >= 0) ? k::kGravity * (i1r - R.i1) : 0.0;
-        f_scale_[uf]  = 1.0;
     }
 }
 
@@ -1273,6 +1515,7 @@ void ExplicitFvSolver::computeFaceFlux(int f) {
 // ===========================================================================
 
 void ExplicitFvSolver::limitPositivity(double dt) {
+    perf::GatedTimer _pt(perf::sec_fv_positivity);
     const int nc = mesh_->n_cells();
     const int nn = mesh_->n_nodes();
     static thread_local std::vector out_cell, out_node;
@@ -1336,7 +1579,6 @@ void ExplicitFvSolver::limitPositivity(double dt) {
             // conservation is untouched by the limiter.
             f_mass_[uf] *= s;
             f_mom_[uf]  *= s;
-            f_scale_[uf] = s;
         }
     }
 }
@@ -1346,178 +1588,347 @@ void ExplicitFvSolver::limitPositivity(double dt) {
 // ===========================================================================
 
 void ExplicitFvSolver::relaxNodeFluxes(double dt, const FvStepForcing& forcing) {
-    const bool semi = (opts_.node_coupling == NodeCoupling::SEMI_IMPLICIT);
+    perf::GatedTimer _pt(perf::sec_fv_nodesolve);
     all_faces_live_ = true;      // global path: every face was just computed
     const int nn = mesh_->n_nodes();
+    const auto& fold = press_.foldedNodes();
+    const bool have_fold = press_step_ && !fold.empty();
+    node_solve_list_.clear();
     for (int n = 0; n < nn; ++n) {
-        // The algebraic solve is not a relaxation — it applies under either
-        // coupling mode. Storage nodes (and demoted ponding junctions) keep
-        // the semi-implicit correction.
-        if (algebraicActive(n))  solveAlgebraicNode(n, dt, forcing);
-        else if (semi)           relaxOneNode(n, dt, forcing);
+        // A junction the implicit pass folds is a ROW of the SPD head
+        // system — solving or damping it here would overwrite the very
+        // fluxes the solve is about to own (slot program R2).
+        if (have_fold && fold[static_cast(n)]) continue;
+        node_solve_list_.push_back(n);
     }
+    solveNodes(node_solve_list_, [&](int) { return dt; }, forcing);
 }
 
-// dV/dH at a given depth — the storage response the correction is damped
-// against. Mirrors refreshNodeAreas' three cases, but evaluated at an
-// ARBITRARY depth rather than at the node's current one, because that is the
-// whole point of iterating: past the first sweep the head has moved.
-double ExplicitFvSolver::nodeStorageSlope(int node, double depth) const {
-    const auto un = static_cast(node);
-    const double full = mesh_->node_full_depth[un];
-    if (mesh_->node_can_pond[un] && full > 0.0 && depth > full)
-        return mesh_->node_ponded_area[un];
-    if (mesh_->node_vol_off[un] < 0)          // junction: V = A_s·depth, A_s fixed
-        return state_->node_surf_area[un];
-    const double dd = mesh_->node_vol_dmax[un] /
-                      static_cast(kNodeVolSamples - 1);
-    const double d = std::max(0.0, depth);
-    return std::max((nodeVolumeFromDepth(node, d + dd) -
-                     nodeVolumeFromDepth(node, d)) / dd,
-                    constants::MIN_SURFAREA);
+// Phase 3d: the node solves in parallel. Every node's solve reads cell state
+// and its own incident faces and writes only those faces and its own head
+// (a pass-through ghost reads the FAR CELL, never another node), so the
+// nodes are independent and the result is bit-identical in any order and at
+// any thread count. The `perf::n_fv_alg_*` counters inside are plain
+// increments: exact at THREADS 1, an estimate above (same as the closure
+// counters in the flux loop). Dynamic schedule: a junction's cost varies
+// with its bracket expansion (1 to ~80 residuals).
+template 
+void ExplicitFvSolver::solveNodes(const std::vector& nodes, DtOf&& dt_of,
+                                  const FvStepForcing& forcing) {
+    // Split by cost. A pass-through junction (node_pass_) takes the degree-2
+    // shortcut inside solveAlgebraicNode — an average of two surfaces — and a
+    // storage node's relaxation is one pass over its faces; only a junction
+    // that actually runs the bracketed root solve (~10 face fluxes, up to ~80
+    // residuals) is worth a thread. Measured on TwinOaks (5084 pipes, 96 %
+    // pass-through): forking all 5000 nodes per substep cost more than the
+    // solves it distributed (+30 s at 8 threads on a 129 s run).
+    // Solver members, NOT thread_local scratch: the heavy list is read by
+    // every thread of the parallel loop below (a thread_local would hand each
+    // worker its own, empty, copy).
+    std::vector& heavy = node_heavy_;
+    std::vector& light = node_light_;
+    heavy.clear(); light.clear();
+    const bool have_pass = !node_pass_.empty();
+    for (const int n : nodes) {
+        const auto un = static_cast(n);
+        const bool fixed = forcing.node_fixed_head &&
+                           std::isfinite(forcing.node_fixed_head[un]);
+        if (!fixed && algebraicActive(n) && !(have_pass && node_pass_[un]))
+            heavy.push_back(n);
+        else
+            light.push_back(n);
+    }
+    for (const int n : light) {
+        // The algebraic solve is not a relaxation. Storage nodes (and demoted
+        // ponding junctions) get the semi-implicit correction.
+        if (algebraicActive(n))  solveAlgebraicNode(n, dt_of(n), forcing);
+        else                     relaxOneNode(n, dt_of(n), forcing);
+    }
+    const int nh = static_cast(heavy.size());
+    // An explicit branch, not an `if` clause on the pragma: a parallel region
+    // that the clause disables still enters the runtime, and this loop runs
+    // once per tier firing — 13 M times on the 5-day East Boston deck, where
+    // the clause form cost 30 % of the run at ONE thread.
+#ifdef SWMM_USE_OPENMP
+    if (nh >= kOmpMinNodes && omp_get_max_threads() > 1) {
+#pragma omp parallel for schedule(dynamic, 2)
+        for (int i = 0; i < nh; ++i)
+            solveAlgebraicNode(heavy[static_cast(i)],
+                               dt_of(heavy[static_cast(i)]), forcing);
+        return;
+    }
+#endif
+    for (int i = 0; i < nh; ++i)
+        solveAlgebraicNode(heavy[static_cast(i)],
+                           dt_of(heavy[static_cast(i)]), forcing);
 }
 
 void ExplicitFvSolver::relaxOneNode(int n, double dt,
                                     const FvStepForcing& forcing) {
-    {
-        const auto un = static_cast(n);
-        if (mesh_->node_kind[un] == kNodeVirtual) return;
-        // A prescribed head has no continuity equation to damp — the stage is
-        // imposed and the exchange is whatever the Riemann solver produced.
-        if (forcing.node_fixed_head && std::isfinite(forcing.node_fixed_head[un]))
-            return;
-        if (!(state_->node_surf_area[un] > 0.0)) return;
+    const auto un = static_cast(n);
+    if (mesh_->node_kind[un] == kNodeVirtual) return;
+    // A prescribed head has no continuity equation to damp — the stage is
+    // imposed and the exchange is whatever the Riemann solver produced.
+    if (forcing.node_fixed_head && std::isfinite(forcing.node_fixed_head[un]))
+        return;
+    if (!(state_->node_surf_area[un] > 0.0)) return;
+    // A dummy-drain node has no head to relax toward: the pass-through removes
+    // exactly what arrives, so its continuity residual — the numerator of the
+    // correction below — is identically zero. Computing it anyway would only
+    // add a spurious resistance at the incident faces and turn a free-drainage
+    // boundary into a mild backwater.
+    if (!mesh_->node_dummy_drain.empty() && mesh_->node_dummy_drain[un]) return;
 
-        const int b = mesh_->node_face_ptr[un];
-        const int e = mesh_->node_face_ptr[un + 1];
+    const int b = mesh_->node_face_ptr[un];
+    const int e = mesh_->node_face_ptr[un + 1];
 
-        const double q_lat = (forcing.node_lateral ? forcing.node_lateral[un]
-                                                   : 0.0) +
-                             node_qstruct_[un];
-        const double invert  = mesh_->node_invert[un];
-        const double h_start = state_->node_head[un];
-        const double v_start =
-            nodeVolumeFromDepth(n, std::max(0.0, h_start - invert));
-
-        // One sweep is the original scheme, and stays bit-identical to it: the
-        // residual is the raw face sum, and the resistance, the storage area
-        // and the fluxes are all the ones the substep started with. Additional
-        // sweeps re-evaluate all three at the head the previous sweep landed
-        // on, so the node converges on its own continuity equation rather than
-        // on a tangent taken at the start of the step (plan §7B.8).
-        const int sweeps = std::max(1, opts_.node_picard_sweeps);
-        double h_k = h_start;
-
-        for (int it = 0; it < sweeps; ++it) {
-            // Σ ∂F/∂H over the incident faces, from the characteristic relation
-            // for a simple wave: |dQ/dH| = gA/c = √(g·A·T) at the ghost state.
-            // Always a RESISTANCE — raising the head drives more out and lets
-            // less in, on either side of the face — so the denominator below
-            // can only grow, and the correction can only damp.
-            double sum_f = 0.0, resist = 0.0;
-            for (int p = b; p < e; ++p) {
-                const auto up = static_cast(p);
-                const int f = mesh_->node_face_idx[up];
-                const auto uf = static_cast(f);
-                sum_f += mesh_->node_face_sign[up] * f_mass_[uf];
+    const double q_lat = nodeLateral(forcing, un) + node_qstruct_[un] +
+                         nodeQDummy(un);
+    // ONE correction, with the characteristic resistance √(g·A·T), the node
+    // surface area and the face fluxes all frozen at the head the substep
+    // started from. Exact for the linearized problem — the residual after it
+    // is identically zero. The real problem's nonlinearity is what a fine LTS
+    // tier resolves; iterating this correction instead (FV_NODE_PICARD) was
+    // retired with a recorded negative result (4987f552).
+    const double h0 = state_->node_head[un];
 
-                const int cell = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
-                                                           : mesh_->face_cr[uf];
-                if (cell < 0) continue;
-                const auto uc = static_cast(cell);
-                const FvGeometry& g =
-                    mesh_->geom[static_cast(mesh_->cell_geom[uc])];
-                const double hg = h_k - mesh_->face_zb[uf];
-                if (hg <= k::kDryDepth) continue;
-                const double ag = k::areaOfDepth(g, hg);
-                const double tg = k::widthOfDepth(g, hg);
-                if (ag <= k::kDryArea || tg <= 0.0) continue;
-                resist += std::sqrt(k::kGravity * ag * tg);
-            }
-            if (resist <= 0.0) break;
-
-            // Residual of the node's own continuity equation at h_k. On the
-            // first sweep h_k == h_start, so the storage term is identically
-            // zero and this is the original expression.
-            const double as = (it == 0)
-                                  ? state_->node_surf_area[un]
-                                  : nodeStorageSlope(n, h_k - invert);
-            const double dv =
-                (it == 0) ? 0.0
-                          : nodeVolumeFromDepth(n, std::max(0.0, h_k - invert)) -
-                                v_start;
-            const double dh =
-                dt * (sum_f + q_lat - dv / dt) / (as + dt * resist);
-            if (dh == 0.0) break;
-
-            const bool last = (it + 1 >= sweeps) ||
-                              (std::fabs(dh) <= opts_.node_picard_tol);
-            if (!last) {
-                // Re-solve the incident faces against the corrected head. This
-                // REPLACES the linear extrapolation with the flux the Riemann
-                // solver actually returns there, which is the part a single
-                // tangent gets wrong at a large Δt.
-                //
-                // Two gates, and they are different claims. cell_active_ keeps
-                // work-list compaction results-transparent (§6.10): only faces
-                // the flux pass itself would have computed are touched.
-                // faceIsLive keeps LOCAL TIME STEPPING correct: under LTS a
-                // node's incident faces can sit in different tiers, and a face
-                // that is not firing on this base step is holding the flux it
-                // will book over its own 2^k·dt₀ window. Re-solving it here
-                // would re-time that flux against the wrong Δt and break the
-                // macro cycle's face-open/volume-close contract — the very
-                // property that makes a tiered step conservative in TIME as
-                // well as in mass.
-                h_k += dh;
-                state_->node_head[un] = h_k;
-                for (int p = b; p < e; ++p) {
-                    const auto up = static_cast(p);
-                    const int f = mesh_->node_face_idx[up];
-                    const auto uf = static_cast(f);
-                    if (!faceIsLive(f)) continue;
-                    const int cl = mesh_->face_cl[uf];
-                    const int cr = mesh_->face_cr[uf];
-                    const bool la = (cl >= 0) &&
-                                    cell_active_[static_cast(cl)];
-                    const bool ra = (cr >= 0) &&
-                                    cell_active_[static_cast(cr)];
-                    if (la || ra) computeFaceFlux(f);
-                }
-                continue;
-            }
+    // Σ ∂F/∂H over the incident faces, from the characteristic relation
+    // for a simple wave: |dQ/dH| = gA/c = √(g·A·T) at the ghost state.
+    // Always a RESISTANCE — raising the head drives more out and lets
+    // less in, on either side of the face — so the denominator below
+    // can only grow, and the correction can only damp.
+    double sum_f = 0.0, resist = 0.0;
+    for (int p = b; p < e; ++p) {
+        const auto up = static_cast(p);
+        const int f = mesh_->node_face_idx[up];
+        const auto uf = static_cast(f);
+        sum_f += mesh_->node_face_sign[up] * f_mass_[uf];
+        relax_beta_[uf] = 0.0;
+
+        const int cell = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                   : mesh_->face_cr[uf];
+        if (cell < 0) continue;
+        const auto uc = static_cast(cell);
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        const double hg = h0 - mesh_->face_zb[uf];
+        if (hg <= k::kDryDepth) continue;
+        perf::count(perf::n_fv_geom_area);
+        perf::count(perf::n_fv_geom_width);
+        const double ag = k::areaOfDepth(g, hg);
+        const double tg = k::widthOfDepth(g, hg);
+        if (ag <= k::kDryArea || tg <= 0.0) continue;
+        // β = √(gAT) per face, kept for pass 2 — the same geometry used to be
+        // evaluated a second time there to produce this same number.
+        const double beta = std::sqrt(k::kGravity * ag * tg);
+        relax_beta_[uf] = beta;
+        resist += beta;
+    }
+    if (resist <= 0.0) return;
+
+    const double as = state_->node_surf_area[un];
+    const double dh = dt * (sum_f + q_lat) / (as + dt * resist);
+    if (dh == 0.0) return;
+
+    // Write the correction into f_mass_ — the ONE array both the cell
+    // update and the node update read. That is what keeps mass
+    // conservation exact: whatever the correction does, the two sides
+    // of every face see the same number.
+    for (int p = b; p < e; ++p) {
+        const auto up = static_cast(p);
+        const int f = mesh_->node_face_idx[up];
+        const auto uf = static_cast(f);
+        // β = −sign·√(gAT): the node on a face's LEFT exports on a
+        // positive flux, the node on its RIGHT imports, and raising the
+        // head opposes the import in both cases. √(gAT) is the value pass 1
+        // evaluated for this face (zero for every face it skipped).
+        const double a = relax_beta_[uf];
+        if (a <= 0.0) continue;
+        f_mass_[uf] += -mesh_->node_face_sign[up] * a * dh;
+    }
+}
 
-            // Write the correction into f_mass_ — the ONE array both the cell
-            // update and the node update read. That is what keeps mass
-            // conservation exact: whatever the correction does, the two sides
-            // of every face see the same number.
-            for (int p = b; p < e; ++p) {
-                const auto up = static_cast(p);
-                const int f = mesh_->node_face_idx[up];
+// ===========================================================================
+// Unsteady friction (issue #156)
+// ===========================================================================
+
+// Precompute the convective UF term c·sgn(Vⁿ)·|∂V/∂x|ⁿ per cell from the
+// CURRENT (pre-update) cell_u_/state snapshot, so the parallel update loops
+// never read a mid-update neighbor. Stencil is same-conduit only: within one
+// conduit every cell shares the conduit frame, while across virtual-junction
+// splices and node faces the frames may oppose (face_dir_l/r flips), so the
+// stencil degrades to one-sided/own there — slightly diffusive at splices,
+// never sign-wrong. Wave celerity is regime-consistent by construction:
+// kernels::celerity(A, T) delivers √(gA/T), which above the crown is the slot
+// (acoustic) celerity because T = t_slot — exactly the paper's Eq. (12).
+void ExplicitFvSolver::computeUfGradients(const std::vector* cells) {
+    const int nc = mesh_->n_cells();
+    auto grad_for = [&](int c) {
+        const auto uc = static_cast(c);
+        uf_grad_[uc] = 0.0;
+        if (!cell_active_[uc]) return;
+        const double h = state_->cell_h[uc];
+        if (h <= k::kDryDepth) return;
+        const double u = cell_u_[uc];
+        if (u == 0.0) return;
+
+        const int cond = mesh_->cell_conduit[uc];
+        const double dx_c = mesh_->cell_dx[uc];
+        double uL = u, uR = u, dsum = 0.0;
+        const int faces[2]    = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
+        const int8_t sides[2] = {mesh_->cell_side0[uc], mesh_->cell_side1[uc]};
+        for (int e = 0; e < 2; ++e) {
+            const auto uf = static_cast(faces[e]);
+            // sides==0: this cell is the face's LEFT cell -> neighbor right.
+            const int nb = (sides[e] == 0) ? mesh_->face_cr[uf]
+                                           : mesh_->face_cl[uf];
+            if (nb < 0) continue;                                  // node face
+            const auto unb = static_cast(nb);
+            if (mesh_->cell_conduit[unb] != cond) continue;        // VJ splice
+            const double d = 0.5 * (dx_c + mesh_->cell_dx[unb]);
+            if (sides[e] == 0) { uR = cell_u_[unb]; dsum += d; }
+            else               { uL = cell_u_[unb]; dsum += d; }
+        }
+        if (dsum <= 0.0) return;
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        // Regime-consistent wave speed (issue #156 P5b — same rule as the
+        // dt census and the implicit storage width): a FLAGGED cell's h is
+        // the SIGNED slot-line depth, and the free-surface table width is
+        // wrong at every h off the slot band (at 0 < h < y_crown it is the
+        // free width, ~1e5 × t_slot at study celerities, and the resulting
+        // c_wave drives the Vitkovsky term unstable — e4 × TPA + UF NaN'd at
+        // the reflected surge once the P5b refresh made regime-true h
+        // reachable there). A flagged cell's celerity is the constant
+        // acoustic value from the slot width at ANY h.
+        const double c_wave = tpaCell(uc)
+                                  ? k::celerity(state_->cell_a[uc], g.t_slot)
+                                  : k::celerity(state_->cell_a[uc],
+                                                k::widthOfDepth(g, h));
+        const double sgn = (u > 0.0) ? 1.0 : -1.0;
+        uf_grad_[uc] = c_wave * sgn * std::fabs((uR - uL) / dsum);
+    };
+    if (cells) {
+        for (const int c : *cells) grad_for(c);
+    } else {
+#ifdef SWMM_USE_OPENMP
+#pragma omp parallel for schedule(dynamic, 64) if (nc >= kOmpMinCells)
+#endif
+        for (int c = 0; c < nc; ++c) grad_for(c);
+    }
+}
+
+// ===========================================================================
+// TPA regime flags (issue #156 Phase 4)
+// ===========================================================================
+// Once per substep, BEFORE reconstruction (TPA plan §A2 — not per RK stage,
+// so both Heun stages see one operator). Entry (FS→P) is unconditional at
+// A ≥ a_crown (the cell filled through the taper). Exit (P→FS) requires
+// ΔA at/below the crown area (with an ε-hysteresis band, gate A-G2) AND
+// atmosphere contact this step. Contact rule — air is not modeled, so any
+// free surface is atmospheric (the paper's own assumption): an unsealed node
+// face (SURCHARGE_DEPTH == 0; virtual junctions never reach the node set and
+// are sealed splices by construction, plan §2.2(6)), or a face neighbor that
+// was free-surface last step. Transitions read the PREVIOUS flags via the
+// tpa_scratch_ snapshot, so the pass is order-independent and parallel-safe.
+void ExplicitFvSolver::updateTpaFlags() {
+    const int nc = mesh_->n_cells();
+    tpa_scratch_ = state_->cell_tpa;
+    constexpr double kEpsHead = 1.0e-4;   // ft — FUDGE-scale hysteresis
+#ifdef SWMM_USE_OPENMP
+#pragma omp parallel for schedule(static) if (nc >= kOmpMinCells)
+#endif
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        // An inactive cell is SKIPPED, not mutated (issue #156 R4a): the old
+        // `cell_tpa = 0` write here destroyed the seal of any flagged cell
+        // the compaction predicate missed. With the rebuild seed keeping
+        // flagged cells active, a flagged inactive cell no longer exists —
+        // and if one ever does, silently unsealing it is the worst response.
+        if (!cell_active_[uc]) continue;
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        if (g.is_open) { state_->cell_tpa[uc] = 0; continue; }
+        const double a = state_->cell_a[uc];
+        // Atmosphere contact of THIS cell (the exit rule's vent test): an
+        // unsealed node face whose water level sits below the pipe crown at
+        // that face, or a free-surface neighbor whose level sits below the
+        // shared crown.
+        auto ventedCell = [&]() -> bool {
+            const int faces2[2] = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
+            for (const int f : faces2) {
                 const auto uf = static_cast(f);
-                const int cell = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
-                                                           : mesh_->face_cr[uf];
-                if (cell < 0) continue;
-                const auto uc = static_cast(cell);
-                const FvGeometry& g =
-                    mesh_->geom[static_cast(mesh_->cell_geom[uc])];
-                const double hg = h_k - mesh_->face_zb[uf];
-                if (hg <= k::kDryDepth) continue;
-                const double ag = k::areaOfDepth(g, hg);
-                const double tg = k::widthOfDepth(g, hg);
-                if (ag <= k::kDryArea || tg <= 0.0) continue;
-                // β = −sign·√(gAT): the node on a face's LEFT exports on a
-                // positive flux, the node on its RIGHT imports, and raising the
-                // head opposes the import in both cases.
-                const double a = std::sqrt(k::kGravity * ag * tg);
-                f_mass_[uf] += -mesh_->node_face_sign[up] * a * dh;
+                const double crown_elev = mesh_->face_zb[uf] + g.y_full;
+                const int nd = mesh_->face_node[uf];
+                if (nd >= 0) {
+                    const auto und = static_cast(nd);
+                    if (mesh_->node_sur_depth[und] <= 0.0 &&
+                        state_->node_head[und] < crown_elev)
+                        return true;
+                    continue;
+                }
+                const int nb = (mesh_->face_cl[uf] == c) ? mesh_->face_cr[uf]
+                                                         : mesh_->face_cl[uf];
+                // Interface rule (P5b, measured both ways — the P4/P5
+                // submergence-checked contact rule STANDS). The paper vents
+                // the regime-transition interface unconditionally ("…or the
+                // flow regime transition interface, hs is set to zero"), but
+                // taken literally that unzips a submerged pressurized leg
+                // through a chain of momentary exits (the open-apex gate
+                // diverged), and a ±2 ft "weakly sub-atmospheric" band
+                // variant failed the same gates — both REJECTED (see the P5b
+                // handoff delta). An interface vents only when air actually
+                // sits at the shared face: a free-surface neighbor whose
+                // level is below the shared crown.
+                if (nb >= 0 &&
+                    tpa_scratch_[static_cast(nb)] == 0 &&
+                    cell_eta_[static_cast(nb)] < crown_elev)
+                    return true;
             }
-            break;
+            return false;
+        };
+        // Regime-consistent state refresh on ANY transition (P5b, measured on
+        // the e2 filling deck): the stored cell_h belongs to the OLD regime —
+        // an exited cell otherwise carries its line-depth (−200 ft class)
+        // through the whole substep's reconstruction, and the resulting eta
+        // gradients pump mass until the run NaNs at the reflected surge
+        // (~21.6 s, ERROR 14; traced: heads to 2485 ft with 5–15 flag flips
+        // per substep).
+        auto refresh = [&](uint8_t now) {
+            state_->cell_tpa[uc] = now;
+            const double h2 = now ? k::tpaDepthOfArea(g, a)
+                                  : k::depthOfArea(g, a);
+            state_->cell_h[uc] = h2;
+            cell_eta_[uc] = mesh_->cell_zb[uc] + h2;
+            cacheClosure(uc, g, h2);
+        };
+        if (tpa_scratch_[uc] == 0) {
+            // Entry at the crown area is unconditional (Phase-4 rule,
+            // unchanged). A P5b variant that ALSO forced entry for un-vented
+            // essentially-full cells (A ≥ a_full islands) was measured and
+            // REJECTED — it broke e4 and the open-apex gate (see the P5b
+            // handoff delta); do not resurrect without new evidence.
+            const uint8_t now = (a >= g.a_crown) ? uint8_t{1} : uint8_t{0};
+            if (now != tpa_scratch_[uc]) refresh(now);
+            continue;
         }
-
-        // The head is the node update's to set, from the volume ledger. Any
-        // provisional value above was scaffolding for the flux re-solve.
-        state_->node_head[un] = h_start;
+        // Column separation floor (the paper's own two-phase boundary; the
+        // kCavHead constant is file-scope, shared with the R4d same-substep
+        // check in takeSubstep).
+        if (a < g.a_crown - g.t_slot * kCavHead) {
+            refresh(0);   // column separation: exit + regime-true h
+            continue;
+        }
+        if (a > g.a_crown - g.t_slot * kEpsHead) continue;   // stays P
+        // Atmosphere contact requires an UNSUBMERGED opening: air cannot
+        // enter through a vented node whose water level stands above the
+        // pipe crown at that face (a submerged inlet holds the siphon), nor
+        // from a free-surface neighbor whose surface is above the shared
+        // crown. Without the submergence check every sealed reach unzips
+        // from its vented ends (measured: the sealed-siphon fixture drained
+        // and then diverged). A closed end (nb < 0, no node) is a sealed
+        // wall, not a vent. Shares ventedCell with the entry rule above.
+        if (ventedCell()) refresh(0);
     }
 }
 
@@ -1526,10 +1937,28 @@ void ExplicitFvSolver::relaxOneNode(int n, double dt,
 // ===========================================================================
 
 void ExplicitFvSolver::updateCells(double dt, const FvStepForcing& forcing) {
+    perf::GatedTimer _pt(perf::sec_fv_cellupdate);
     const int nc = mesh_->n_cells();
     const int nf = mesh_->n_faces();
     const int ns = state_->n_species;
 
+    // Cell-local update: every write is indexed by this cell (state cell_a /
+    // cell_h / cell_q / cell_phi, cell_eta_, cell_u_, cell_q_int_), the face
+    // and mesh arrays are read-only here, and frictionFor / depthOfArea are
+    // pure. No cross-cell dependence and no floating-point reduction, so the
+    // result is bit-identical to the serial order at any thread count. The
+    // only accumulator is the inversion COUNT, reduced as an integer (exact,
+    // order-independent) and applied once after the loop.
+    // Dynamic schedule, not static: inactive cells are skipped outright and
+    // they arrive in spatial runs (a filling main leaves whole stretches
+    // quiescent), so a contiguous static split hands some threads nothing to
+    // do. Measured on TwinOaks-v2 (5086 cells, 2 h) against the same run at
+    // one thread: static 2.05x, dynamic 2.92x.
+    long n_inv = 0;
+#ifdef SWMM_USE_OPENMP
+#pragma omp parallel for schedule(dynamic, 64) reduction(+ : n_inv) \
+        if (nc >= kOmpMinCells)
+#endif
     for (int c = 0; c < nc; ++c) {
         const auto uc = static_cast(c);
         if (!cell_active_[uc]) continue;
@@ -1560,7 +1989,9 @@ void ExplicitFvSolver::updateCells(double dt, const FvStepForcing& forcing) {
             // is: the node sitting on the face's LEFT means this is the
             // conduit's upstream end, hence the entrance loss.
             if (mesh_->face_node[uf] >= 0)
-                k_loss += (mesh_->face_cl[uf] < 0) ? g.loss_inlet : g.loss_outlet;
+                k_loss += (mesh_->face_cl[uf] < 0)
+                              ? mesh_->conduit_loss_inlet[static_cast(mesh_->cell_conduit[uc])]
+                              : mesh_->conduit_loss_outlet[static_cast(mesh_->cell_conduit[uc])];
         }
         // Reported DISCHARGE is the mass actually moving through the cell —
         // the mean of its two face fluxes in the conduit frame — not the
@@ -1601,6 +2032,8 @@ void ExplicitFvSolver::updateCells(double dt, const FvStepForcing& forcing) {
             const double hm = std::max(0.0, eta_c - zm);
             const double i1p = (hp > 0.0) ? k::i1OfDepth(g, hp, k::areaOfDepth(g, hp)) : 0.0;
             const double i1m = (hm > 0.0) ? k::i1OfDepth(g, hm, k::areaOfDepth(g, hm)) : 0.0;
+            perf::count(perf::n_fv_geom_area, (hp > 0.0 ? 1L : 0L) + (hm > 0.0 ? 1L : 0L));
+            perf::count(perf::n_fv_geom_i1,   (hp > 0.0 ? 1L : 0L) + (hm > 0.0 ? 1L : 0L));
             dQ += k::kGravity * (i1p - i1m);
         }
 
@@ -1608,6 +2041,13 @@ void ExplicitFvSolver::updateCells(double dt, const FvStepForcing& forcing) {
         double a_new = a_old + dt * dA * inv_dx;
         double q_new = state_->cell_q[uc] + dt * dQ * inv_dx;
 
+        // Diverted junction lateral inflow (refreshStructFlows): mass only,
+        // zero momentum, added BEFORE the scalar divide so clean inflow
+        // dilutes the advected species. Capped at the junction rim; the
+        // surplus is banked for the node update (face_a_rim_).
+        if (!cell_qlat_.empty() && cell_qlat_[uc] != 0.0)
+            a_new = injectDivertedLateral(uc, a_new, dt, inv_dx);
+
         // ---- advected scalars, on the SAME divergence -----------------------
         // Updating m = A·φ with the same face MASS fluxes and dividing by the
         // hydrodynamic a_new is what makes a uniform field exactly invariant:
@@ -1646,22 +2086,42 @@ void ExplicitFvSolver::updateCells(double dt, const FvStepForcing& forcing) {
         if (a_new < 0.0) a_new = 0.0;
 
         // ---- friction + local losses, both semi-implicit --------------------
-        const double h_new = k::depthOfArea(g, a_new);
+        ++n_inv;
+        const bool tpa_cell = tpaCell(uc);   // regime-consistent closure (#156)
+        const double h_new = tpa_cell ? k::tpaDepthOfArea(g, a_new)
+                                      : k::depthOfArea(g, a_new);
         state_->cell_a[uc] = a_new;
         state_->cell_h[uc] = h_new;
         cell_eta_[uc] = mesh_->cell_zb[uc] + h_new;
-        if (h_new <= k::kDryDepth) {
+        cacheClosure(uc, g, h_new);
+        // A flagged cell is FULL of water at (possibly sub-atmospheric)
+        // piezometric head — the dry cutoff must not fire on h < kDryDepth.
+        // A degenerate vacuum cell (area collapsed toward zero before the
+        // column-separation exit fires next flag update) must not divide by
+        // ~zero area.
+        if ((!tpa_cell && h_new <= k::kDryDepth) ||
+            (tpa_cell && a_new <= k::kDryArea)) {
             state_->cell_q[uc] = 0.0;
             cell_u_[uc]        = 0.0;
             continue;
         }
         const double u = q_new / a_new;
-        q_new = frictionFor(g, q_new, u, h_new, dt);
+        // Friction for a flagged cell evaluates at full depth (R = r_full,
+        // and a full FORCE_MAIN keeps its pressurized law).
+        q_new = frictionFor(g, mesh_->conduit_roughness[static_cast(mesh_->cell_conduit[uc])],
+                            mesh_->conduit_rough_factor[static_cast(mesh_->cell_conduit[uc])],
+                            q_new, u, tpa_cell ? g.y_full : h_new, dt);
         if (k_loss > 0.0) q_new = k::localLossUpdate(q_new, u, k_loss, dx, dt);
+        // Unsteady friction (issue #156): cell_u_[uc] still holds Vⁿ here —
+        // it is overwritten only below, and only by this cell's own iteration.
+        if (opts_.unsteady_friction != 0)
+            q_new = k::ufUpdate(q_new, a_new, cell_u_[uc], opts_.uf_k3,
+                                uf_grad_[uc], dt);
 
         state_->cell_q[uc] = q_new;
         cell_u_[uc] = q_new / a_new;
     }
+    perf::count(perf::n_fv_invert, n_inv);
 }
 
 // ===========================================================================
@@ -1677,6 +2137,10 @@ namespace {
 /// a bracketing probe cannot disturb lake-at-rest by the solve tolerance.
 constexpr double kAlgQEps     = 1.0e-12;
 constexpr int    kAlgMaxIters = 16;
+/// |Δh| convergence floor of the root find and the bracket's seed step (ft).
+/// Was FvOptions::node_picard_tol, which the retired Picard sweeps shared;
+/// the value is load-bearing here and must stay 1.0e-6.
+constexpr double kAlgHeadTol  = 1.0e-6;
 // The EXPANSION loop gets its own, larger budget: its first step is the
 // quasi-Newton scale |R|/resist, which below a pipe crown (large open-channel
 // resistance) can start near the tolerance floor — 16 doublings from 1e-6 ft
@@ -1715,6 +2179,7 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     const auto un = static_cast(n);
     if (forcing.node_fixed_head && std::isfinite(forcing.node_fixed_head[un]))
         return;
+    perf::count(perf::n_fv_alg_visit);
     // PASS-THROUGH junction: the fluxes present the neighbouring cells to
     // each other directly (faceSide/computeFaceFlux) and do not depend on the
     // node head at all, so there is no balance to solve — the head is purely
@@ -1753,7 +2218,12 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
             const auto uc = static_cast(c);
             const double eta = cell_eta_[uc];
             if (!any || eta < lowest) { lowest = eta; any = true; }
-            if (state_->cell_h[uc] <= k::kDryDepth) continue;
+            // A TPA-flagged cell is FULL of water at a (possibly negative)
+            // gauge pressure — it is the wettest state there is, and its eta
+            // is the piezometric level the node shares. The h > kDryDepth
+            // test reads it as dry, which dropped the sealed column's own
+            // vacuum out of the average and left the node on the fallback.
+            if (!tpaCell(uc) && state_->cell_h[uc] <= k::kDryDepth) continue;
             s += eta;
             ++m;
         }
@@ -1762,14 +2232,15 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
                                                            // lowest adjacent bed
                                                            // rather than freeze
                                                            // a stale wet head
+        perf::count(perf::n_fv_alg_passthru);
         return;
     }
+    perf::count(perf::n_fv_alg_solve);
     const int b = mesh_->node_face_ptr[un];
     const int e = mesh_->node_face_ptr[un + 1];
     const double invert = mesh_->node_invert[un];
     const double q_ext =
-        (forcing.node_lateral ? forcing.node_lateral[un] : 0.0) +
-        node_qstruct_[un] + node_carry_[un] / dt;
+        nodeLateral(forcing, un) + node_qstruct_[un] + node_carry_[un] / dt;
 
     // Fallback for a degree-1 node whose head solve clamps at the ceiling
     // with inflow still unpassed: continuity fixes the answer — the one face
@@ -1803,6 +2274,22 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
                              (mesh_->node_can_pond[un]
                                   ? 0.0 : mesh_->node_sur_depth[un]);
         if (mesh_->node_full_depth[un] > 0.0 && eta_c >= rim) return false;
+        // A cell already standing in the slot cannot take a prescribed
+        // discharge: its stage below the rim is a slot head, not a free
+        // surface with room, and forcing q_ext into it lifts that head by
+        // q_ext·dt/(t_slot·dx) per substep — measured on the 0.5 ft pipe fed
+        // 10 cfs (8× capacity): the junction chattered between dry and
+        // 40–80 ft while the clamp-and-flood path it displaced holds the rim.
+        // The fallback keeps its force-main role for a FREE-SURFACE interior
+        // (the pressurized-main plateau the solve under-delivers on) and
+        // hands a slot interior back to the clamp (dev: OPENSWMM_FV_DEG1=1
+        // restores the stage-only guard).
+        if (deg1_guard_slot_) {
+            const auto ucg = static_cast(cell);
+            const FvGeometry& gg =
+                mesh_->geom[static_cast(mesh_->cell_geom[ucg])];
+            if (!gg.is_open && state_->cell_h[ucg] >= gg.y_full) return false;
+        }
         const double sgn = mesh_->node_face_sign[up0];
         const k::FaceState& in = (mesh_->face_cl[uf0] >= 0) ? f_state_l_[uf0]
                                                             : f_state_r_[uf0];
@@ -1817,8 +2304,11 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     // every incident face shares one tier, so whenever this runs they are all
     // live and the balance is complete.
     double h_best = 0.0, r_best = std::numeric_limits::infinity();
+    double h_last = std::numeric_limits::quiet_NaN();
     auto residual = [&](double h) -> double {
+        perf::count(perf::n_fv_alg_resid);
         state_->node_head[un] = h;
+        h_last = h;
         double r = q_ext;
         for (int p = b; p < e; ++p) {
             const auto up = static_cast(p);
@@ -1831,13 +2321,38 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
                     (cl >= 0) && cell_active_[static_cast(cl)];
                 const bool ra =
                     (cr >= 0) && cell_active_[static_cast(cr)];
-                if (la || ra) computeFaceFlux(f);
+                // Every trial head reads back one scalar, f_mass_: the trial
+                // flux is MASS-ONLY (plan Phase 1c); finalize() below runs the
+                // full flux once at the accepted head. Counted separately from
+                // the residual count so the multiplier is measured, not assumed.
+                if (la || ra) { perf::count(perf::n_fv_alg_flux); computeFaceFlux(f, true); }
             }
             r += mesh_->node_face_sign[up] * f_mass_[uf];
         }
         if (std::fabs(r) < std::fabs(r_best)) { h_best = h; r_best = r; }
         return r;
     };
+    // The full flux (momentum, corrections, face states) at the head the last
+    // trial evaluated — exactly what the last full-flux residual used to leave
+    // behind, so every exit below calls this first. The head itself is
+    // restored to whatever the exit chose (the balanced exit keeps h0).
+    auto finalize = [&]() {
+        if (!(h_last == h_last)) return;              // no trial ran
+        const double keep = state_->node_head[un];
+        state_->node_head[un] = h_last;
+        for (int p = b; p < e; ++p) {
+            const auto up = static_cast(p);
+            const int f = mesh_->node_face_idx[up];
+            const auto uf = static_cast(f);
+            if (!faceIsLive(f)) continue;
+            const int cl = mesh_->face_cl[uf];
+            const int cr = mesh_->face_cr[uf];
+            const bool la = (cl >= 0) && cell_active_[static_cast(cl)];
+            const bool ra = (cr >= 0) && cell_active_[static_cast(cr)];
+            if (la || ra) computeFaceFlux(f);
+        }
+        state_->node_head[un] = keep;
+    };
     // Σ|dQ/dH| at the ghost states — the quasi-Newton step estimate.
     auto resistAt = [&](double h) -> double {
         double resist = 0.0;
@@ -1852,6 +2367,8 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
                 mesh_->cell_geom[static_cast(cell)])];
             const double hg = h - mesh_->face_zb[uf];
             if (hg <= k::kDryDepth) continue;
+            perf::count(perf::n_fv_geom_area);
+            perf::count(perf::n_fv_geom_width);
             const double ag = k::areaOfDepth(g, hg);
             const double tg = k::widthOfDepth(g, hg);
             if (ag <= k::kDryArea || tg <= 0.0) continue;
@@ -1886,13 +2403,32 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     }
     double lo = invert;
     double hi = invert + top;
+    // TPA (issue #156 Phase 4): a SEALED node inside a pressurized column
+    // carries sub-atmospheric head — the floor extends below the invert by
+    // the column-separation bound, matching the flag update's kCavHead. Only
+    // when at least one incident cell is flagged: an all-free sealed node is
+    // an ordinary junction and keeps the ordinary floor.
+    if (tpa_ && mesh_->node_sur_depth[un] > 0.0) {
+        bool any_flagged = false;
+        for (int p = b; p < e; ++p) {
+            const auto uf = static_cast(
+                mesh_->node_face_idx[static_cast(p)]);
+            const int cell = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                       : mesh_->face_cr[uf];
+            if (cell >= 0 && tpaCell(static_cast(cell))) {
+                any_flagged = true;
+                break;
+            }
+        }
+        if (any_flagged) lo = invert - 35.0;
+    }
 
     const double h0 = state_->node_head[un];
     double h = std::min(std::max(h0, lo), hi);
     double r = (h == h0) ? residual(h0) : residual(h);
     // Already balanced (a lake at rest is the load-bearing case): leave the
     // head exactly where it is.
-    if (std::fabs(r) <= kAlgQEps) { state_->node_head[un] = h0; return; }
+    if (std::fabs(r) <= kAlgQEps) { state_->node_head[un] = h0; finalize(); return; }
 
     // Expanding bracket from the CURRENT head, never a probe of the domain
     // ends: the ceiling can be arbitrarily high (a junction with no rim gets
@@ -1905,9 +2441,9 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     // evaluated at the clamped head.
     const double dir  = (r > 0.0) ? 1.0 : -1.0;
     const double res0 = resistAt(h);
-    double step = std::max(opts_.node_picard_tol,
+    double step = std::max(kAlgHeadTol,
                            (res0 > 0.0) ? std::fabs(r) / res0
-                                        : opts_.node_picard_tol);
+                                        : kAlgHeadTol);
     double h_a = h, r_a = r;
     bool bracketed = false;
     for (int it = 0; it < kAlgMaxExpand; ++it) {
@@ -1915,7 +2451,7 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
         if (h_b <= lo) h_b = lo;
         if (h_b >= hi) h_b = hi;
         const double r_b = residual(h_b);
-        if (std::fabs(r_b) <= kAlgQEps) return;      // landed on the root
+        if (std::fabs(r_b) <= kAlgQEps) { finalize(); return; }   // landed on the root
         if ((r_a > 0.0) != (r_b > 0.0)) {            // sign change: bracketed
             if (dir > 0.0) { lo = h_a; hi = h_b; }
             else           { lo = h_b; hi = h_a; }
@@ -1926,6 +2462,7 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
         if (h_b == lo || h_b == hi) {                // clamped at an end
             // Ceiling with inflow still unpassed = the slot plateau; hand
             // the face to the prescribed-discharge fallback if it applies.
+            finalize();   // the fallback reads the face STATE at this head
             if (h_b == hi && r_b > 0.0 && prescribeDegree1()) return;
             return;
         }
@@ -1935,6 +2472,7 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     if (!bracketed) {
         // Budget spent walking: settle on the best head seen.
         if (h_best != h_a) residual(h_best);
+        finalize();
         return;
     }
 
@@ -1950,7 +2488,7 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
         h = h_new;
         r = residual(h);
         if (r > 0.0) lo = h; else hi = h;
-        if (std::fabs(dh) <= opts_.node_picard_tol ||
+        if (std::fabs(dh) <= kAlgHeadTol ||
             std::fabs(r) <= kAlgQEps)
             break;
     }
@@ -1959,9 +2497,10 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
     // would otherwise park the head a full tolerance away and bleed
     // tolerance-scale noise into a system at rest.
     if (std::fabs(r_best) < std::fabs(r)) residual(h_best);
-    // The final residual() evaluation left both the head and the incident
-    // fluxes at the accepted root — the solve owns the head; updateNodes will
-    // not overwrite it for this node.
+    // The final residual() evaluation left the head at the accepted root and
+    // finalize() the incident fluxes — the solve owns the head; updateNodes
+    // will not overwrite it for this node.
+    finalize();
 }
 
 // Structure links contribute a source/sink pair. They are held constant
@@ -1970,12 +2509,20 @@ void ExplicitFvSolver::solveAlgebraicNode(int n, double dt,
 // which the plugin boundary deliberately excludes, and would chatter
 // controls tuned for DW-scale steps. Scattered once per forcing refresh.
 void ExplicitFvSolver::refreshStructFlows(const FvStepForcing& forcing) {
+    perf::GatedTimer _pt(perf::sec_fv_structref);
+    perf::count(perf::n_fv_structref);
     const auto nn = static_cast(mesh_->n_nodes());
     node_qstruct_.assign(nn, 0.0);
     if (forcing.structure_flow) {
         const int nstruct = static_cast(mesh_->struct_link.size());
         for (int s = 0; s < nstruct; ++s) {
             const auto us = static_cast(s);
+            // A DUMMY entry's forcing slot holds nothing meaningful: its
+            // discharge is derived per substep by refreshDummyFlows and lands
+            // in node_qdummy_, not here. Reading it would double-count against
+            // whatever the engine-side pass-through last happened to compute.
+            if (!mesh_->struct_is_dummy.empty() && mesh_->struct_is_dummy[us])
+                continue;
             const double q = forcing.structure_flow[mesh_->struct_link[us]];
             if (q == 0.0) continue;
             node_qstruct_[static_cast(mesh_->struct_n1[us])] -= q;
@@ -1984,19 +2531,195 @@ void ExplicitFvSolver::refreshStructFlows(const FvStepForcing& forcing) {
     }
     // Dynamic half of the pass-through test, refreshed with the forcing: a
     // degree-2 junction is a pure interface only while nothing is injected at
-    // it. A lateral or structure flow needs a head the fluxes respond to, so
-    // the node falls back to the flux-balance solve for that routing step.
-    for (std::size_t un = 0; un < nn; ++un)
-        node_pass_[un] =
-            (node_pass_static_[un] && node_qstruct_[un] == 0.0 &&
-             node_carry_[un] == 0.0 &&
-             (!forcing.node_lateral || forcing.node_lateral[un] == 0.0))
-                ? 1 : 0;
+    // it. A structure flow (or unbled carry) needs a head the fluxes respond
+    // to, so the node falls back to the flux-balance solve for that step.
+    //
+    // A LATERAL inflow does not: it carries no directed momentum (a manhole
+    // pour), so a clean degree-2 junction keeps the pass-through splice and
+    // the inflow is DIVERTED into the two incident cells, half each, as a
+    // zero-momentum area source integrated by updateCells/fireCells.
+    // Dropping to the head solve instead costs the split-Riemann ~1 mm of
+    // head per junction (see faceSide) — with rain on every junction of a
+    // 400-conduit channel that integrated into an 18-25% deep bias with
+    // exact q (SWASHES §3.3 benchmark finding, 2026-08-12).
+    if (cell_qlat_.size() != static_cast(mesh_->n_cells()))
+        cell_qlat_.assign(static_cast(mesh_->n_cells()), 0.0);
+    else
+        std::fill(cell_qlat_.begin(), cell_qlat_.end(), 0.0);
+    if (node_lat_div_.size() != nn) node_lat_div_.assign(nn, 0);
+    else std::fill(node_lat_div_.begin(), node_lat_div_.end(), 0);
+    for (std::size_t un = 0; un < nn; ++un) {
+        // A dummy-drain node is never a clean splice, however few faces it has:
+        // the pass-through removes water at it, so its two neighbours are not
+        // presenting anything to each other.
+        const bool drains =
+            !mesh_->node_dummy_drain.empty() && mesh_->node_dummy_drain[un];
+        // A SURCHARGED degree-2 junction takes the solved path too. The splice
+        // has no head state and so no rim: the water an overloaded pipe cannot
+        // pass has nowhere to go but the Preissmann slot, and its ~1e-3 m² of
+        // storage per pipe turns a tenth of a m³ of excess into a hundred
+        // metres of head (Bellinge, 2026-09-05 — ERROR 14 within a routing
+        // step of the first overload). Capping the injection alone
+        // (face_a_rim_) bounds the mass but leaves an on/off relief valve on a
+        // stiff acoustic line, which chatters and still diverged on chains of
+        // small pipes. The solved path is the boundary condition DW provides:
+        // a ghost head clamped at the rim, the surplus booked as flooding or
+        // ponding. Under pressure the ~1 mm splice accuracy is moot, so the
+        // trade is free. Evaluated here, at the top of a cycle with the
+        // ledger settled, like every other forcing change; the injection cap
+        // covers the cycle in between. Sticky in practice — a solved node
+        // banks a tolerance-scale residual carry every substep, which the
+        // carry test below reads as "not clean" — exactly as a structure flow
+        // has always revoked the splice for good.
+        const bool clean = node_pass_static_[un] && !drains &&
+                           node_qstruct_[un] == 0.0 && node_carry_[un] == 0.0 &&
+                           !incidentPressurized(un);
+        const double lat =
+            forcing.node_lateral ? forcing.node_lateral[un] : 0.0;
+        if (clean && lat != 0.0) {
+            bool credited = false;
+            for (int p = mesh_->node_face_ptr[un];
+                 p < mesh_->node_face_ptr[un + 1]; ++p) {
+                const auto uf = static_cast(
+                    mesh_->node_face_idx[static_cast(p)]);
+                const int c = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                        : mesh_->face_cr[uf];
+                if (c >= 0) {
+                    cell_qlat_[static_cast(c)] += 0.5 * lat;
+                    credited = true;
+                    // A dry receiving cell is inactive under compaction; the
+                    // rebuild (see rebuildActiveLists) activates it.
+                    if (!cell_active_.empty() &&
+                        !cell_active_[static_cast(c)])
+                        lists_valid_ = false;
+                }
+            }
+            // Flag only once a cell actually took the water: nodeLateral()
+            // reads the flag as "already delivered", so flagging a node whose
+            // faces credited nothing would make the inflow vanish. (A clean
+            // node always has two boundary faces, so this is a no-op today.)
+            if (credited) node_lat_div_[un] = 1;
+        } else if (lat != 0.0 && mesh_->node_kind[un] == kNodeVirtual &&
+                   !mesh_->node_vj_face.empty() &&
+                   mesh_->node_vj_face[un] >= 0) {
+            // A virtual junction owns no faces — its two conduits were spliced
+            // into one interior face — so the same half/half zero-momentum
+            // split goes to the two cells adjoining that face. Without this
+            // the lateral was booked by the mass balance and routed nowhere
+            // (plans/VJ_LATERAL_INFLOW_PLAN_2026-09-04.md §E3).
+            const auto uf = static_cast(mesh_->node_vj_face[un]);
+            const int cl = mesh_->face_cl[uf];
+            const int cr = mesh_->face_cr[uf];
+            if (cl >= 0 && cr >= 0) {
+                cell_qlat_[static_cast(cl)] += 0.5 * lat;
+                cell_qlat_[static_cast(cr)] += 0.5 * lat;
+                node_lat_div_[un] = 1;
+                if (!cell_active_.empty() &&
+                    (!cell_active_[static_cast(cl)] ||
+                     !cell_active_[static_cast(cr)]))
+                    lists_valid_ = false;
+            }
+        }
+        node_pass_[un] = (clean && (lat == 0.0 || node_lat_div_[un])) ? 1 : 0;
+        // PUBLISH eligibility at any degree. A structure flow means the node
+        // head carries information the incident conduit cells do not, so it
+        // must be reported as solved.
+        //
+        // Carry deliberately does NOT disqualify, unlike the pass-through
+        // test above. A SOLVED algebraic junction banks a root-solve residual
+        // every substep by construction, so `carry == 0` is false for
+        // essentially every node in this class and testing it would exclude
+        // exactly the nodes this reconstruction exists for. The carry is a
+        // tolerance-scale volume bled back into the next solve, not a
+        // headwater the cells fail to see.
+        //
+        // Lateral inflow does not disqualify either: it changes what the node
+        // head is, not whether the incident wet cells describe the stage the
+        // profile should draw. Confirmed by measurement — the published
+        // excess survives on nodes with no lateral inflow at all.
+        node_pub_[un] = (node_pub_static_[un] && node_qstruct_[un] == 0.0 &&
+                         !drains) ? 1 : 0;
+    }
+}
+
+// A DUMMY conduit has no section to march, so it cannot be a control volume;
+// but it is not a wall either. It declares that whatever reaches its upstream
+// node leaves immediately for its downstream node, with no storage and no head
+// loss — legacy findNonConduitFlow (dynwave.c:418-449) sets Q = inflow +
+// overflow and updateNodeFlows books it as outflow, so the upstream node's
+// continuity reduces to dV/dt = 0. It is a free-drainage boundary.
+//
+// That is what this reproduces, and it is why the discharge cannot come from
+// the forcing array the way a weir's does: the answer is not a head relation,
+// it is the arrival rate at the upstream node — a quantity only the solver
+// knows, and only at the moment the node update is about to consume it.
+// Calling this immediately before each node update, with the SAME arrival
+// volume that update will integrate, makes the drain exact rather than lagged
+// by a substep.
+template 
+void ExplicitFvSolver::refreshDummyFlows(double dt, const FvStepForcing& forcing,
+                                         ArrivedFn&& arrived) {
+    if (mesh_->struct_is_dummy.empty() || dt <= 0.0) return;
+    std::fill(node_qdummy_.begin(), node_qdummy_.end(), 0.0);
+
+    const int nstruct = static_cast(mesh_->struct_link.size());
+    for (int s = 0; s < nstruct; ++s) {
+        const auto us = static_cast(s);
+        if (!mesh_->struct_is_dummy[us]) continue;
+        const auto u1 = static_cast(mesh_->struct_n1[us]);
+        const auto u2 = static_cast(mesh_->struct_n2[us]);
+
+        // Everything arriving at the upstream node over this window: the net
+        // face volume, plus its lateral and structure forcing. node_qdummy_ is
+        // deliberately NOT in the sum — checkDummyLinks guarantees a dummy is
+        // the only outlet of its upstream node, so there is no second dummy
+        // here to chase, and a node cannot be the upstream end of one dummy
+        // and the downstream end of another.
+        double q = arrived(u1) / dt + nodeLateral(forcing, u1) +
+                   node_qstruct_[u1];
+
+        // Never reverses: a dummy is a one-way declaration of connectivity,
+        // and legacy's Q = inflow + overflow is a magnitude sum that cannot go
+        // negative. A node running dry simply passes nothing.
+        if (q < 0.0) q = 0.0;
+
+        // Control setting, then FLOW_LIMIT — the same order and the same
+        // meaning as computeNonConduitFlowOne's DUMMY branch. A closed dummy
+        // is a wall, and the upstream node then fills on its own continuity,
+        // exactly as it does under DW.
+        if (forcing.link_q_cap) {
+            const double cap =
+                forcing.link_q_cap[static_cast(mesh_->struct_link[us])];
+            if (cap >= 0.0 && q > cap) q = cap;
+        }
+
+        node_qdummy_[u1] -= q;
+        node_qdummy_[u2] += q;
+        dummy_vol_[us]   += q * dt;
+    }
 }
 
 void ExplicitFvSolver::updateNodes(double dt, const FvStepForcing& forcing) {
+    perf::GatedTimer _pt(perf::sec_fv_nodeupdate);
     const int nn = mesh_->n_nodes();
 
+    // Net face volume arriving at a node over this substep, which is exactly
+    // what the loop below is about to add to its storage.
+    refreshDummyFlows(dt, forcing, [&](std::size_t un) {
+        double sum = 0.0;
+        for (int p = mesh_->node_face_ptr[un]; p < mesh_->node_face_ptr[un + 1]; ++p) {
+            const auto up = static_cast(p);
+            sum += mesh_->node_face_sign[up] *
+                   f_mass_[static_cast(mesh_->node_face_idx[up])];
+        }
+        return sum * dt;
+    });
+
+    // Lateral the incident cells refused at their rim this substep
+    // (injectDivertedLateral) — booked before the ledger loop so a pondable
+    // node demoted by it integrates the bucket path in this same substep.
+    bookLateralSpills(nullptr);
+
     for (int n = 0; n < nn; ++n) {
         const auto un = static_cast(n);
         if (mesh_->node_kind[un] == kNodeVirtual) continue;
@@ -2017,6 +2740,7 @@ void ExplicitFvSolver::updateNodes(double dt, const FvStepForcing& forcing) {
             if (q > 0.0) node_in_[un]  += q * dt;
             else         node_out_[un] -= q * dt;
         }
+        bookDivertedLateral(un, dt, forcing);
 
         if (forcing.node_fixed_head && std::isfinite(forcing.node_fixed_head[un])) {
             // Stage boundary (outfalls, tide/time-series). The head is imposed;
@@ -2026,8 +2750,8 @@ void ExplicitFvSolver::updateNodes(double dt, const FvStepForcing& forcing) {
             continue;
         }
 
-        const double q_lat = (forcing.node_lateral ? forcing.node_lateral[un] : 0.0) +
-                             node_qstruct_[un];
+        const double q_lat = nodeLateral(forcing, un) + node_qstruct_[un] +
+                             nodeQDummy(un);
 
         if (algebraicActive(n)) {
             settleAlgebraicNode(n, node_carry_[un] + dt * (sum_faces + q_lat));
@@ -2084,6 +2808,62 @@ void ExplicitFvSolver::settleAlgebraicNode(int n, double carry) {
             return;
         }
     }
+    // PASS-THROUGH node: no solve will ever bleed this carry back, and a
+    // nonzero carry REVOKES the splice at the next forcing refresh (the
+    // clean test) — which is exactly how every width-varying junction
+    // silently fell back to the lossy head solve at steady state (the two
+    // prismatic views of a spliced non-prismatic face legitimately disagree
+    // by O(ΔB) in mass flux each step; SWASHES §3.5 finding, 2026-08-13).
+    // Dispose the residual as VOLUME in the incident cells instead — they
+    // are where an interface junction's water physically stands — split
+    // evenly, zero momentum. Anything a near-dry cell cannot absorb stays
+    // in the carry and demotes the node next step (conservative fallback).
+    //
+    // Never into a PRESSURIZED cell. Above the crown a cell's storage is the
+    // Preissmann slot, t_slot·dx, so the O(ΔB) window residual that is
+    // harmless as free-surface volume lands as hundreds of metres of head
+    // (Bellinge 2026-09-05: single-step spikes to 0.7–1.8 km at width-step
+    // junctions, recovering within the next step). Bank it instead — the
+    // banked carry is also what hands the junction to the solved path at
+    // the next refresh (refreshStructFlows), where the solve absorbs the
+    // residual as forcing.
+    if (!node_pass_.empty() && node_pass_[un] && carry != 0.0 &&
+        !incidentPressurized(un)) {
+        double left = carry;
+        const int b = mesh_->node_face_ptr[un];
+        const int e = mesh_->node_face_ptr[un + 1];
+        const int deg = (e > b) ? (e - b) : 1;
+        for (int p = b; p < e; ++p) {
+            const auto uf = static_cast(
+                mesh_->node_face_idx[static_cast(p)]);
+            const int c = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                    : mesh_->face_cr[uf];
+            if (c < 0) continue;
+            const auto uc = static_cast(c);
+            const double dx = mesh_->cell_dx[uc];
+            double a_new = state_->cell_a[uc] +
+                           (carry / static_cast(deg)) / dx;
+            if (a_new < 0.0) a_new = 0.0;
+            left -= (a_new - state_->cell_a[uc]) * dx;
+            const FvGeometry& g = mesh_->geom[static_cast(
+                mesh_->cell_geom[uc])];
+            perf::count(perf::n_fv_invert);
+            const double h_new = k::depthOfArea(g, a_new);
+            state_->cell_a[uc] = a_new;
+            state_->cell_h[uc] = h_new;
+            cell_eta_[uc] = mesh_->cell_zb[uc] + h_new;
+            cacheClosure(uc, g, h_new);
+            if (h_new <= k::kDryDepth) {
+                state_->cell_q[uc] = 0.0;
+                cell_u_[uc]        = 0.0;
+            } else {
+                cell_u_[uc] = state_->cell_q[uc] / a_new;
+            }
+        }
+        node_carry_[un] = (std::fabs(left) > 1.0e-12) ? left : 0.0;
+        state_->node_volume[un] = std::max(0.0, node_carry_[un]);
+        return;
+    }
     // Published volume is the REAL water the node holds — the carry ledger
     // and nothing else. An algebraic junction is an interface: the water at
     // its head stands in the incident cells, and publishing V(depth) on top
@@ -2095,6 +2875,66 @@ void ExplicitFvSolver::settleAlgebraicNode(int n, double carry) {
     state_->node_volume[un] = std::max(0.0, carry);
 }
 
+// ===========================================================================
+// Diverted lateral: rim cap and spill booking (face_a_rim_ in the header)
+// ===========================================================================
+
+double ExplicitFvSolver::injectDivertedLateral(std::size_t uc, double a_new,
+                                               double dt, double inv_dx) {
+    const double add = dt * cell_qlat_[uc] * inv_dx;
+    // Withdrawals are not capped (the a_new >= 0 clamp that follows handles
+    // them), and a cell with no rimmed face takes the whole inflow as before.
+    if (add <= 0.0 || face_a_rim_.empty()) return a_new + add;
+    const int faces[2] = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
+    int    f_rim = -1;
+    double a_rim = std::numeric_limits::infinity();
+    for (const int f : faces) {
+        const auto uf = static_cast(f);
+        if (face_a_rim_[uf] < a_rim) { a_rim = face_a_rim_[uf]; f_rim = f; }
+    }
+    if (f_rim < 0 || a_new + add <= a_rim) return a_new + add;
+    // The lowest rim binds first, as it would for two manholes on one pipe.
+    // Nothing already in the cell is removed — water its neighbours pushed
+    // above the rim stays and drains through the fluxes; only the INJECTION
+    // is refused, and the refused volume is banked for the node update.
+    const double room = std::max(0.0, a_rim - a_new);
+    face_lat_spill_[static_cast(f_rim)] += (add - room) / inv_dx;
+    return a_new + room;
+}
+
+void ExplicitFvSolver::bookLateralSpills(const std::vector* nodes) {
+    if (face_lat_spill_.empty()) return;
+    auto book = [&](int n) {
+        const auto un = static_cast(n);
+        if (!node_pass_static_[un]) return;      // only their faces carry a rim
+        double spill = 0.0;
+        for (int p = mesh_->node_face_ptr[un];
+             p < mesh_->node_face_ptr[un + 1]; ++p) {
+            const auto uf = static_cast(
+                mesh_->node_face_idx[static_cast(p)]);
+            spill += face_lat_spill_[uf];
+            face_lat_spill_[uf] = 0.0;
+        }
+        if (spill <= 0.0) return;
+        if (mesh_->node_can_pond[un]) {
+            // Same destination as settleAlgebraicNode's ponding branch: real
+            // water on the ponded area. algebraicActive() then reads the node
+            // as demoted and the ledger loop that follows integrates it on the
+            // bucket path, head from volume, until it drains below v_full.
+            state_->node_volume[un] =
+                std::max(state_->node_volume[un], node_vfull_[un]) + spill;
+        } else {
+            flood_vol_[un] += spill;
+        }
+    };
+    if (nodes) {
+        for (const int n : *nodes) book(n);
+    } else {
+        const int nn = mesh_->n_nodes();
+        for (int n = 0; n < nn; ++n) book(n);
+    }
+}
+
 // ===========================================================================
 // frictionFor — Manning, or the force main's own pressurized law
 // ===========================================================================
@@ -2116,18 +2956,20 @@ void ExplicitFvSolver::settleAlgebraicNode(int n, double carry) {
 // The friction laws come from HydClosureKernels.hpp — the same bodies
 // ForceMain.cpp's public entry points forward to — so this compiles unchanged
 // for the device backend (plan §5.1).
-double ExplicitFvSolver::frictionFor(const FvGeometry& g, double q, double u,
+double ExplicitFvSolver::frictionFor(const FvGeometry& g, double roughness,
+                                     double rough_factor, double q, double u,
                                      double h, double dt) const {
+    perf::count(perf::n_fv_geom_hydrad);
     const double r = k::hydRadOfDepth(g, h);
     if (g.xs.type == static_cast(XSectShape::FORCE_MAIN) && h >= g.y_full) {
         const double absu = std::fabs(u);
         if (absu <= 0.0) return q;
-        const double sf = (g.roughness < 1.0)
-                              ? hydkernels::fricSlopeDW(u, r, g.roughness)
-                              : hydkernels::fricSlopeHW(u, r, g.roughness);
+        const double sf = (roughness < 1.0)
+                              ? hydkernels::fricSlopeDW(u, r, roughness)
+                              : hydkernels::fricSlopeHW(u, r, roughness);
         return q / (1.0 + dt * k::kGravity * sf / absu);
     }
-    return k::frictionUpdate(q, u, r, dt, g.rough_factor);
+    return k::frictionUpdate(q, u, r, dt, rough_factor);
 }
 
 // ===========================================================================
@@ -2167,76 +3009,12 @@ void ExplicitFvSolver::applyNodeCapacity(int node, double v_prev,
 }
 
 // ===========================================================================
-// Implicit dispersion (D-FV1)
+// Implicit dispersion (D-FV1) — forwarder (phase E0, body in
+// transport/fvkernels/SpeciesTransportKernels.cpp)
 // ===========================================================================
 
 void ExplicitFvSolver::dispersionSolve(double dt) {
-    const int ns = state_->n_species;
-    if (ns <= 0 || opts_.dispersion <= 0.0) return;
-
-    const int nc = mesh_->n_cells();
-    static thread_local std::vector aa, bb, ccv, rr, xx;
-
-    // One tridiagonal system per chain (Thomas) — cheap, unconditionally
-    // stable, and it removes the Δx²/(2·D_L) explicit constraint entirely,
-    // which at fine Δx is MORE restrictive than CFL (plan §3.2, D-FV1). Chains
-    // span virtual junctions, so a spliced pair disperses as one conduit.
-    for (int ch = 0; ch < mesh_->n_chains(); ++ch) {
-        const int b = mesh_->chain_ptr[static_cast(ch)];
-        const int e = mesh_->chain_ptr[static_cast(ch) + 1];
-        const int m = e - b;
-        if (m < 2) continue;
-        aa.assign(static_cast(m), 0.0);
-        bb.assign(static_cast(m), 0.0);
-        ccv.assign(static_cast(m), 0.0);
-        rr.assign(static_cast(m), 0.0);
-        xx.assign(static_cast(m), 0.0);
-
-        for (int s = 0; s < ns; ++s) {
-            const auto base = static_cast(s) *
-                              static_cast(nc);
-            for (int i = 0; i < m; ++i) {
-                const int c = mesh_->chain_cells[static_cast(b + i)];
-                const auto uc = static_cast(c);
-                const double dx = mesh_->cell_dx[uc];
-                const double a  = std::max(state_->cell_a[uc], k::kDryArea);
-                double lo = 0.0, hi = 0.0;
-                if (i > 0) {
-                    const int cm = mesh_->chain_cells[static_cast(b + i - 1)];
-                    const double am = std::max(
-                        state_->cell_a[static_cast(cm)], k::kDryArea);
-                    lo = opts_.dispersion * 0.5 * (a + am) * dt / (dx * dx * a);
-                }
-                if (i < m - 1) {
-                    const int cp = mesh_->chain_cells[static_cast(b + i + 1)];
-                    const double ap = std::max(
-                        state_->cell_a[static_cast(cp)], k::kDryArea);
-                    hi = opts_.dispersion * 0.5 * (a + ap) * dt / (dx * dx * a);
-                }
-                aa[static_cast(i)]  = -lo;
-                ccv[static_cast(i)] = -hi;
-                bb[static_cast(i)]  = 1.0 + lo + hi;
-                rr[static_cast(i)]  = state_->cell_phi[base + uc];
-            }
-            for (int i = 1; i < m; ++i) {
-                const auto ui = static_cast(i);
-                const double w = aa[ui] / bb[ui - 1];
-                bb[ui] -= w * ccv[ui - 1];
-                rr[ui] -= w * rr[ui - 1];
-            }
-            const auto ulast = static_cast(m - 1);
-            xx[ulast] = rr[ulast] / bb[ulast];
-            for (int i = m - 2; i >= 0; --i) {
-                const auto ui = static_cast(i);
-                xx[ui] = (rr[ui] - ccv[ui] * xx[ui + 1]) / bb[ui];
-            }
-            for (int i = 0; i < m; ++i) {
-                const int c = mesh_->chain_cells[static_cast(b + i)];
-                state_->cell_phi[base + static_cast(c)] =
-                    xx[static_cast(i)];
-            }
-        }
-    }
+    transport::fvkernels::dispersionSolve(speciesKernelView(), dt);
 }
 
 // ===========================================================================
@@ -2244,6 +3022,8 @@ void ExplicitFvSolver::dispersionSolve(double dt) {
 // ===========================================================================
 
 void ExplicitFvSolver::saveState() {
+    perf::GatedTimer _pt(perf::sec_fv_savestate);
+    perf::count(perf::n_fv_savestate);
     save_cell_a_    = state_->cell_a;
     save_cell_q_    = state_->cell_q;
     save_cell_phi_  = state_->cell_phi;
@@ -2255,9 +3035,13 @@ void ExplicitFvSolver::saveState() {
     save_flood_     = flood_vol_;
     save_qint_      = cell_q_int_;
     save_carry_     = node_carry_;
+    if (tpa_) save_tpa_ = state_->cell_tpa;   // regime flags roll back with
+                                              // the state that set them (#156)
 }
 
 void ExplicitFvSolver::restoreState() {
+    perf::GatedTimer _pt(perf::sec_fv_restore);
+    perf::count(perf::n_fv_restore);
     state_->cell_a      = save_cell_a_;
     state_->cell_q      = save_cell_q_;
     state_->cell_phi    = save_cell_phi_;
@@ -2269,6 +3053,12 @@ void ExplicitFvSolver::restoreState() {
     flood_vol_          = save_flood_;
     cell_q_int_         = save_qint_;
     node_carry_         = save_carry_;
+    // Spill banked by the cells is drained by the node update of the same
+    // substep, so nothing should be pending here; a rolled-back step must not
+    // leave any to be booked against the restored state.
+    std::fill(face_lat_spill_.begin(), face_lat_spill_.end(), 0.0);
+    if (tpa_) state_->cell_tpa = save_tpa_;   // BEFORE refreshDepths: h(A)
+                                              // is regime-dependent (#156)
     refreshDepths();               // cell_h / eta / u are derived
 }
 
@@ -2276,16 +3066,126 @@ void ExplicitFvSolver::restoreState() {
 // Substep and time integration
 // ===========================================================================
 
+bool ExplicitFvSolver::anyPressurizedCell() const {
+    if (!opts_.pressurized_implicit) return false;
+    const int nc = mesh_->n_cells();
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        if (!cell_active_[uc]) continue;
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        if (!g.is_open && state_->cell_h[uc] >= g.y_crown) return true;
+    }
+    return false;
+}
+
+bool ExplicitFvSolver::nodePressFolded(int n) const {
+    const auto un = static_cast(n);
+    if (!algebraicActive(n)) return false;
+    if (forcing_ && forcing_->node_fixed_head &&
+        std::isfinite(forcing_->node_fixed_head[un]))
+        return false;
+    const int b = mesh_->node_face_ptr[un];
+    const int e = mesh_->node_face_ptr[un + 1];
+    if (e <= b) return false;
+    for (int p = b; p < e; ++p) {
+        const int f = mesh_->node_face_idx[static_cast(p)];
+        if (PressurizedHeadSolver::faceModeOf(*mesh_, *state_, f) !=
+            PressurizedHeadSolver::kFull)
+            return false;
+    }
+    return true;
+}
+
+PressurizedView ExplicitFvSolver::pressView(const FvStepForcing& forcing) {
+    PressurizedView pv;
+    pv.mesh         = mesh_;
+    pv.state        = state_;
+    pv.opts         = &opts_;
+    pv.forcing      = &forcing;
+    pv.f_mass       = f_mass_.data();
+    pv.f_sstar      = f_sstar_.data();
+    pv.f_state_l    = f_state_l_.data();
+    pv.f_state_r    = f_state_r_.data();
+    pv.f_flux       = f_flux_.data();
+    pv.cell_eta     = cell_eta_.data();
+    pv.cell_u       = cell_u_.data();
+    pv.active_faces = &active_faces_;
+    pv.cell_active  = &cell_active_;
+    pv.node_qstruct = &node_qstruct_;
+    pv.node_carry   = &node_carry_;
+    pv.node_alg     = &node_alg_;
+    pv.node_vfull   = &node_vfull_;
+    pv.node_lat_div = &node_lat_div_;
+    pv.cell_qlat    = &cell_qlat_;
+    pv.uf_grad      = &uf_grad_;   // empty unless unsteady_friction (issue #156)
+    return pv;
+}
+
 void ExplicitFvSolver::takeSubstep(double dt, const FvStepForcing& forcing) {
+    if (tpa_) updateTpaFlags();   // once per substep, before reconstruction;
+                                  // rolled back with the state on rejection
     reconstructState();
     computeFluxes();
+    // R2a: derive the pressurized subset BEFORE the node pass, so the node
+    // pass can leave the folded junctions to the implicit solve.
+    press_step_ = false;
+    if (opts_.pressurized_implicit) {
+        PressurizedView pv = pressView(forcing);
+        press_step_ = press_.classify(pv);
+    }
     relaxNodeFluxes(dt, forcing);   // BEFORE limiting: the limiter must bound
                                     // the flux that is actually applied
+    if (opts_.unsteady_friction != 0)
+        computeUfGradients(nullptr);   // old-state snapshot (issue #156);
+                                       // BEFORE the implicit solve, whose
+                                       // face fold consumes the same snapshot
+                                       // (nothing between here and updateCells
+                                       // writes cell_u_ or the cell state)
+    if (press_step_) {
+        // The implicit acoustic solve: overwrites the implicit faces'
+        // entries in f_mass_ (the single flux ledger), so everything
+        // downstream — limiter, transport, cell and node updates —
+        // integrates the solved discharges with no further branching.
+        PressurizedView pv = pressView(forcing);
+        press_.solve(pv, dt);
+    }
     limitPositivity(dt);
     reconstructScalars(dt);   // AFTER limiting: the species must ride on the
                               // same water the hydrodynamics moved
     updateCells(dt, forcing);
     updateNodes(dt, forcing);
+    if (press_step_) {
+        // Slave the pressurized cells' momentum to the solved face
+        // discharges — the collocated Q must carry no explicit acoustic
+        // residue, or the instability re-enters through the predictor.
+        PressurizedView pv = pressView(forcing);
+        press_.finalizeCells(pv);
+    }
+    // Same-substep column-separation floor (issue #156 R4d). The entry/exit
+    // rule at the TOP of this function applies the floor to the state the
+    // substep STARTED from, so a single substep could overshoot it and carry
+    // the overshoot through the post-step census and the next reconstruction
+    // (measured −35 ft at the crest on the diverged e3 RK2 run, against the
+    // −30 ft physical limit). Apply the exit in the substep that crosses the
+    // floor — same action as updateTpaFlags' refresh(0): regime change with
+    // regime-true h, no mass touched.
+    if (tpa_) {
+        const int nc2 = mesh_->n_cells();
+        for (int c = 0; c < nc2; ++c) {
+            const auto uc = static_cast(c);
+            if (!cell_active_[uc] || state_->cell_tpa[uc] == 0) continue;
+            const FvGeometry& g =
+                mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+            const double a = state_->cell_a[uc];
+            if (a >= g.a_crown - g.t_slot * kCavHead) continue;
+            state_->cell_tpa[uc] = 0;
+            const double h2 = k::depthOfArea(g, a);
+            state_->cell_h[uc] = h2;
+            cell_eta_[uc] = mesh_->cell_zb[uc] + h2;
+            cacheClosure(uc, g, h2);
+        }
+    }
     dispersionSolve(dt);
 }
 
@@ -2301,6 +3201,7 @@ void ExplicitFvSolver::rkSave() {
     rk_flood_     = flood_vol_;
     rk_qint_      = cell_q_int_;
     rk_carry_     = node_carry_;
+    if (tpa_) rk_tpa_ = state_->cell_tpa;
 }
 
 void ExplicitFvSolver::rkAverage(const FvStepForcing& forcing) {
@@ -2351,6 +3252,18 @@ void ExplicitFvSolver::rkAverage(const FvStepForcing& forcing) {
     avg_delta(cell_q_int_, rk_qint_);
     avg_delta(node_carry_, rk_carry_);
 
+    // The regime latch travels with the state (issue #156 R4c) — the same
+    // invariant saveState/restoreState carry for step rejection: h(A) must be
+    // read in the regime that produced A. The averaged area anchors on Uⁿ,
+    // exactly as a rollback does; leaving stage 2's flags here made the
+    // refresh below read the average on whatever regime the SECOND stage
+    // happened to end in. Anchoring is not a stability fix (measured: it does
+    // not touch the RK2 x TPA amplification, which the divergence guard now
+    // catches) — it is the file's own documented invariant, restored. The
+    // next substep's updateTpaFlags re-derives transitions on the averaged
+    // state as usual.
+    if (tpa_) state_->cell_tpa = rk_tpa_;
+
     refreshDepths();
 }
 
@@ -2365,9 +3278,20 @@ double ExplicitFvSolver::cellStableDt(int c) const {
 
     double speed = 0.0;
     const double h = state_->cell_h[uc];
-    if (h > k::kDryDepth)
+    // TPA (issue #156): a FLAGGED cell's fluxes run at the acoustic slot
+    // celerity at ANY h — the signed slot line has no free-surface width, and
+    // a sub-crown (or sub-invert, h < 0) sealed cell tiered on the table
+    // width lands in a coarse tier its own acoustic exchange then detonates.
+    // Same predicate the global census (censusDt::consider_cell) uses; the
+    // LTS bounds were the one place the regime was missed (measured on E3:
+    // the at-rest pressurized sloped column NaN'd inside the first report
+    // step — P5 task-3 finding).
+    const bool tpa_c = tpaCell(uc);
+    if (tpa_c || h > k::kDryDepth) {
         speed = std::fabs(cell_u_[uc]) +
-                k::celerity(state_->cell_a[uc], k::widthOfDepth(g, h));
+                k::celerity(state_->cell_a[uc],
+                            tpa_c ? g.t_slot : cell_t_[uc]);   // cached T(cell_h)
+    }
 
     // The ghost a boundary face presents counts against THIS cell's step, for
     // the same reason the global census is face-based: a surcharged manhole
@@ -2379,9 +3303,28 @@ double ExplicitFvSolver::cellStableDt(int c) const {
         const auto uf = static_cast(f);
         const int nd = mesh_->face_node[uf];
         if (nd < 0) continue;
+        // Pass-through junction (plan Phase 1e): bound the far cell's state,
+        // which is what the face actually fluxes (see censusDt).
+        const int far = census_pass_far_ ? passThroughFarCell(f, nd) : -1;
+        if (far >= 0) {
+            const auto ufar = static_cast(far);
+            const bool tpa_f = tpaCell(ufar);
+            if (tpa_f || state_->cell_h[ufar] > k::kDryDepth) {
+                const FvGeometry& gfar =
+                    mesh_->geom[static_cast(mesh_->cell_geom[ufar])];
+                speed = std::max(speed,
+                                 std::fabs(cell_u_[ufar]) +
+                                     k::celerity(state_->cell_a[ufar],
+                                                 tpa_f ? gfar.t_slot
+                                                       : cell_t_[ufar]));
+            }
+            continue;
+        }
         const double hg = state_->node_head[static_cast(nd)] -
                           mesh_->face_zb[uf];
         if (hg <= k::kDryDepth) continue;
+        perf::count(perf::n_fv_geom_area);
+        perf::count(perf::n_fv_geom_width);
         speed = std::max(speed, std::fabs(cell_u_[uc]) +
                                     k::celerity(k::areaOfDepth(g, hg),
                                                 k::widthOfDepth(g, hg)));
@@ -2390,11 +3333,60 @@ double ExplicitFvSolver::cellStableDt(int c) const {
     return (speed > 1.0e-12) ? opts_.cfl * dx / speed : 1.0e30;
 }
 
+double ExplicitFvSolver::algebraicNodeStableDt(int n) const noexcept {
+    const auto un = static_cast(n);
+    const int b = mesh_->node_face_ptr[un];
+    const int e = mesh_->node_face_ptr[un + 1];
+
+    double store_min = std::numeric_limits::max();  // min 0.5*dx*T
+    double admit_sum = 0.0;                                 // sum T*c
+
+    for (int p = b; p < e; ++p) {
+        const int f = mesh_->node_face_idx[static_cast(p)];
+        const auto uf = static_cast(f);
+        const int cell = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                   : mesh_->face_cr[uf];
+        if (cell < 0) continue;
+        const auto uc = static_cast(cell);
+        // Not gated on cell_active_, for the same reason nodeStableDt is not:
+        // the tier schedule must not depend on whether compaction is on.
+        const double h = state_->cell_h[uc];
+        const bool tpa_c = tpaCell(uc);   // full of water at any h (#156)
+        if (!tpa_c && h <= k::kDryDepth) continue;
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        const double t = tpa_c ? g.t_slot : cell_t_[uc];   // cached T(cell_h)
+        if (t <= 0.0) continue;
+
+        // Every live face contributes flux the junction has to balance.
+        admit_sum += t * k::celerity(state_->cell_a[uc], t);
+
+        // Only a PRESSURIZED face contributes the stiff storage. Below the
+        // crown the slot has not engaged and the response is soft. A FLAGGED
+        // cell is pressurized at any h (#156).
+        if (tpa_c || h >= g.y_crown) {
+            const double store = 0.5 * mesh_->cell_dx[uc] * t;
+            if (store < store_min) store_min = store;
+        }
+    }
+
+    if (store_min >= std::numeric_limits::max() * 0.5) return 1.0e30;
+    if (!(admit_sum > 0.0)) return 1.0e30;
+    const double tau = store_min / admit_sum;
+    return (tau > 0.0) ? opts_.cfl * tau : 1.0e30;
+}
+
 double ExplicitFvSolver::nodeStableDt(int n) const {
     const auto un = static_cast(n);
     if (mesh_->node_kind[un] == kNodeVirtual) return 1.0e30;
-    // An algebraic junction has no volume state to bound; its tier is pinned
-    // to its incident cells in assignTiers so its faces fire together.
+    // An algebraic junction has no volume state to bound, and its tier is
+    // pinned to its finest incident cell in assignTiers so its faces fire
+    // together. Its ghost-feedback limit is real (algebraicNodeStableDt) but
+    // it must NOT be routed through dt_node: the pin discards the resulting
+    // tier while dt_node still drags dt0 down, which desynchronises the
+    // schedule. assignTiers applies it to the incident CELLS instead, which
+    // is where the feedback actually destabilises the solution and what the
+    // pin then follows.
     if (!node_alg_.empty() && node_alg_[un]) return 1.0e30;
     // An outfall's head is IMPOSED (forcing.node_fixed_head) and its volume
     // ledger is never integrated — there is nothing for a bound to protect.
@@ -2419,10 +3411,11 @@ double ExplicitFvSolver::nodeStableDt(int n) const {
         // the same whether or not compaction is on (§6.10), and a dry cell is
         // excluded by its own depth test in either case.
         const double h = state_->cell_h[uc];
-        if (h <= k::kDryDepth) continue;
+        const bool tpa_c = tpaCell(uc);   // full of water at any h (#156)
+        if (!tpa_c && h <= k::kDryDepth) continue;
         const FvGeometry& g =
             mesh_->geom[static_cast(mesh_->cell_geom[uc])];
-        const double t = k::widthOfDepth(g, h);
+        const double t = tpa_c ? g.t_slot : cell_t_[uc];   // cached T(cell_h)
         if (t <= 0.0) continue;
         dt = std::min(dt, k::faceCflDt(opts_.cfl, as / t, cell_u_[uc],
                                        k::celerity(state_->cell_a[uc], t)));
@@ -2430,7 +3423,8 @@ double ExplicitFvSolver::nodeStableDt(int n) const {
     return dt;
 }
 
-int ExplicitFvSolver::assignTiers(double& dt0) {
+int ExplicitFvSolver::assignTiers(double& dt0, int k_cap_override) {
+    perf::GatedTimer _pt(perf::sec_fv_tier);
     const int nc = mesh_->n_cells();
     const int nf = mesh_->n_faces();
     const int nn = mesh_->n_nodes();
@@ -2452,31 +3446,84 @@ int ExplicitFvSolver::assignTiers(double& dt0) {
     // the compacted run would then not merely skip work but integrate on a
     // different clock, breaking the §6.10 transparency contract outright.
     double dt_min = 1.0e30;
+    int    dt_argmin_cell = -1;   // slot program R0: attribution
     for (int c = 0; c < nc; ++c) {
         const auto uc = static_cast(c);
         dt_cell[uc] = cellStableDt(c);
-        dt_min = std::min(dt_min, dt_cell[uc]);
-    }
-    // FV_NODE_DT NONE: the node's term is an EXPLICIT stability bound on an
-    // unconditionally-stable semi-implicit update (see NodeDtLimit). Dropping
-    // it from dt0 lets the CELL Courant limit set the base step — which is what
-    // the non-LTS path has always used — while tiering stays intact. Nodes are
-    // still TIERED (dt_node feeds tier_of below), just not allowed to drag the
-    // global base step down with them.
-    // As in censusDt(): NONE is a semi-implicit privilege — an explicitly
-    // coupled node's bound is a genuine stability limit and always applies.
-    const bool node_sets_dt0 =
-        (opts_.node_dt_limit == NodeDtLimit::STABILITY) ||
-        (opts_.node_coupling != NodeCoupling::SEMI_IMPLICIT);
+        if (dt_cell[uc] < dt_min) { dt_min = dt_cell[uc]; dt_argmin_cell = c; }
+    }
+    // The node's term is an EXPLICIT stability bound on an unconditionally
+    // stable semi-implicit update; it stays in dt0 for ACCURACY (censusDt's
+    // rationale). nodeStableDt() exempts algebraic junctions and outfalls, so
+    // only storage-like nodes ever set the base step; every node is still
+    // TIERED (dt_node feeds tier_of below).
     for (int n = 0; n < nn; ++n) {
         const auto un = static_cast(n);
         dt_node[un] = nodeStableDt(n);
-        if (node_sets_dt0) dt_min = std::min(dt_min, dt_node[un]);
+        if (dt_node[un] < dt_min) {
+            dt_min = dt_node[un];
+            dt_argmin_cell = -2;   // node bound owns dt0
+        }
     }
+    // An ALGEBRAIC junction's ghost-feedback bound (algebraicNodeStableDt) is a
+    // CFL constraint like any other, and CFL constraints are local -- so it
+    // belongs on the entity that actually integrates state. A plain junction
+    // does not: it has no volume, its head is the instantaneous solution of
+    // sum Q_i(H) = 0, and assignTiers pins it to its finest incident cell so
+    // every incident face is live when that solve happens. Routing the bound
+    // through dt_node therefore buys nothing (the pin discards the tier) while
+    // still dragging dt0 down -- all of the cost, none of the locality.
+    //
+    // Its incident CELLS are what integrate against the solved head, and they
+    // are where the feedback shows up as oscillation, so the constraint lands
+    // on them. Tier grading then spreads it outward one level at a time and
+    // coarse cells keep advancing at 2^k*dt0, which is exactly the locality
+    // tiering exists to provide.
+    //
+    // This MUST run before `dt0 = dt_min`: tightening dt_cell alone only moves
+    // tier indices, while the base step the tiers are measured against stays
+    // put -- an inconsistent schedule that changes answers without enforcing
+    // anything.
+    if (opts_.node_feedback_dt) {
+        for (int n = 0; n < nn; ++n) {
+            const auto un = static_cast(n);
+            if (node_alg_.empty() || !node_alg_[un]) continue;
+            const double dtn = algebraicNodeStableDt(n);
+            if (dtn >= 1.0e29) continue;
+            const int b = mesh_->node_face_ptr[un], e = mesh_->node_face_ptr[un + 1];
+            for (int q = b; q < e; ++q) {
+                const auto uf = static_cast(
+                    mesh_->node_face_idx[static_cast(q)]);
+                const int cl = mesh_->face_cl[uf], cr = mesh_->face_cr[uf];
+                if (cl >= 0) dt_cell[static_cast(cl)] =
+                    std::min(dt_cell[static_cast(cl)], dtn);
+                if (cr >= 0) dt_cell[static_cast(cr)] =
+                    std::min(dt_cell[static_cast(cr)], dtn);
+            }
+            if (dtn < dt_min) { dt_min = dtn; dt_argmin_cell = -2; }
+        }
+    }
+
     if (!(dt_min > 0.0) || dt_min >= 1.0e29) return 1;
     dt0 = dt_min;
 
-    const int k_cap = std::min(std::max(opts_.lts_max_tiers, 1), kMaxLtsTiers);
+    // dt-argmin attribution (slot program R0), LTS path: counted once per
+    // re-tier — coarser sampling than the global path's per-census count,
+    // which is fine for a "who owns the step" ratio.
+    if (dt_argmin_cell == -2) {
+        ++dt_argmin_node_;
+    } else if (dt_argmin_cell >= 0) {
+        const auto uc = static_cast(dt_argmin_cell);
+        const FvGeometry& g =
+            mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+        const double h = state_->cell_h[uc];
+        if      (h >= g.y_full)  ++dt_argmin_pressurized_;
+        else if (h >= g.y_crown) ++dt_argmin_band_;
+        else                     ++dt_argmin_free_;
+    }
+
+    int k_cap = std::min(std::max(opts_.lts_max_tiers, 1), kMaxLtsTiers);
+    if (k_cap_override > 0) k_cap = std::min(k_cap, k_cap_override);
     auto tier_of = [&](double dt) -> int {
         if (dt >= 1.0e29) return k_cap - 1;
         const int k = static_cast(std::floor(std::log2(dt / dt_min)));
@@ -2646,6 +3693,7 @@ int ExplicitFvSolver::assignTiers(double& dt0) {
 }
 
 void ExplicitFvSolver::fireFaces(const std::vector& faces, double dt0) {
+    perf::GatedTimer _pt(perf::sec_fv_ltsfire);
     const int n = static_cast(faces.size());
     if (n == 0) return;
 
@@ -2675,24 +3723,29 @@ void ExplicitFvSolver::fireFaces(const std::vector& faces, double dt0) {
     // node's OWN tier step. Conservation is untouched for the same reason: the
     // correction lands in f_mass_, which is what gets booked into both incident
     // accumulators below.
-    const bool semi = (opts_.node_coupling == NodeCoupling::SEMI_IMPLICIT);
     if (forcing_) {
         static thread_local std::vector touched;
+        static thread_local std::vector touched_nodes;
         touched.assign(acc_nvol_.size(), 0);
+        touched_nodes.clear();
         for (const int f : faces) {
             const int nd = mesh_->face_node[static_cast(f)];
-            if (nd >= 0) touched[static_cast(nd)] = 1;
-        }
-        for (std::size_t nd = 0; nd < touched.size(); ++nd) {
-            if (!touched[nd]) continue;
-            const int n = static_cast(nd);
-            const double dtn = static_cast(1 << node_tier_[nd]) * dt0;
-            // Algebraic junctions share one tier across their incident faces
-            // (assignTiers pinning), so a touched node's faces are all in this
-            // due set and the flux-balance solve is complete.
-            if (algebraicActive(n))  solveAlgebraicNode(n, dtn, *forcing_);
-            else if (semi)           relaxOneNode(n, dtn, *forcing_);
+            if (nd >= 0 && !touched[static_cast(nd)]) {
+                touched[static_cast(nd)] = 1;
+                touched_nodes.push_back(nd);
+            }
         }
+        // Face order, deduplicated by the bitmap: the node solves are
+        // independent, so the visiting order does not affect the result.
+        // Algebraic junctions share one tier across their incident faces
+        // (assignTiers pinning), so a touched node's faces are all in this
+        // due set and the flux-balance solve is complete.
+        solveNodes(touched_nodes,
+                   [&](int n) {
+                       return static_cast(
+                                  1 << node_tier_[static_cast(n)]) * dt0;
+                   },
+                   *forcing_);
     }
 
     // Positivity, in VOLUME rather than rate: the faces in this set fire with
@@ -2756,12 +3809,12 @@ void ExplicitFvSolver::fireFaces(const std::vector& faces, double dt0) {
             if (s < 1.0) {
                 f_mass_[uf] *= s;
                 f_mom_[uf]  *= s;
-                f_scale_[uf] = s;
                 fa = f_mass_[uf];
             }
         }
         const double fq = f_mom_[uf];
 
+        acc_dirty_ = true;   // flux booked; settleAccumulators has work again
         if (cl >= 0) {
             const auto ul = static_cast(cl);
             acc_a_[ul] -= fa * dt;
@@ -2816,6 +3869,8 @@ void ExplicitFvSolver::fireCells(const std::vector& cells, double dt0,
             const double hm = std::max(0.0, eta_c - zm);
             const double i1p = (hp > 0.0) ? k::i1OfDepth(g, hp, k::areaOfDepth(g, hp)) : 0.0;
             const double i1m = (hm > 0.0) ? k::i1OfDepth(g, hm, k::areaOfDepth(g, hm)) : 0.0;
+            perf::count(perf::n_fv_geom_area, (hp > 0.0 ? 1L : 0L) + (hm > 0.0 ? 1L : 0L));
+            perf::count(perf::n_fv_geom_i1,   (hp > 0.0 ? 1L : 0L) + (hm > 0.0 ? 1L : 0L));
             dQ_src = k::kGravity * (i1p - i1m) * dt;
         }
 
@@ -2824,7 +3879,9 @@ void ExplicitFvSolver::fireCells(const std::vector& cells, double dt0,
         for (const int f : faces) {
             const auto uf = static_cast(f);
             if (mesh_->face_node[uf] >= 0)
-                k_loss += (mesh_->face_cl[uf] < 0) ? g.loss_inlet : g.loss_outlet;
+                k_loss += (mesh_->face_cl[uf] < 0)
+                              ? mesh_->conduit_loss_inlet[static_cast(mesh_->cell_conduit[uc])]
+                              : mesh_->conduit_loss_outlet[static_cast(mesh_->cell_conduit[uc])];
         }
 
         // Drain. Zeroing here — not at the top of the cycle — is what makes the
@@ -2835,24 +3892,41 @@ void ExplicitFvSolver::fireCells(const std::vector& cells, double dt0,
         acc_a_[uc] = 0.0;
         acc_q_[uc] = 0.0;
 
+        // Diverted junction lateral inflow over this cell's LTS window
+        // (mirrors updateCells; dt here is the tier window span), capped at
+        // the junction rim exactly as on the global path.
+        if (!cell_qlat_.empty() && cell_qlat_[uc] != 0.0)
+            a_new = injectDivertedLateral(uc, a_new, dt, inv_dx);
+
         if (forcing.conduit_loss) {
             const int cr = mesh_->cell_conduit[uc];
             if (cr >= 0) a_new -= dt * forcing.conduit_loss[cr];
         }
         if (a_new < 0.0) a_new = 0.0;
 
-        const double h_new = k::depthOfArea(g, a_new);
+        perf::count(perf::n_fv_invert);
+        const bool tpa_cell = tpaCell(uc);   // regime-consistent closure (#156)
+        const double h_new = tpa_cell ? k::tpaDepthOfArea(g, a_new)
+                                      : k::depthOfArea(g, a_new);
         state_->cell_a[uc] = a_new;
         state_->cell_h[uc] = h_new;
         cell_eta_[uc] = mesh_->cell_zb[uc] + h_new;
-        if (h_new <= k::kDryDepth) {
+        cacheClosure(uc, g, h_new);
+        if (!tpa_cell && h_new <= k::kDryDepth) {
             state_->cell_q[uc] = 0.0;
             cell_u_[uc]        = 0.0;
             continue;
         }
         const double u = q_new / a_new;
-        q_new = frictionFor(g, q_new, u, h_new, dt);
+        q_new = frictionFor(g, mesh_->conduit_roughness[static_cast(mesh_->cell_conduit[uc])],
+                            mesh_->conduit_rough_factor[static_cast(mesh_->cell_conduit[uc])],
+                            q_new, u, tpa_cell ? g.y_full : h_new, dt);
         if (k_loss > 0.0) q_new = k::localLossUpdate(q_new, u, k_loss, dx, dt);
+        // Unsteady friction (issue #156): dt here is the tier window span,
+        // matching the local-acceleration difference (Vⁿ over the same span).
+        if (opts_.unsteady_friction != 0)
+            q_new = k::ufUpdate(q_new, a_new, cell_u_[uc], opts_.uf_k3,
+                                uf_grad_[uc], dt);
 
         state_->cell_q[uc] = q_new;
         cell_u_[uc] = q_new / a_new;
@@ -2861,20 +3935,34 @@ void ExplicitFvSolver::fireCells(const std::vector& cells, double dt0,
 
 void ExplicitFvSolver::fireNodes(const std::vector& nodes, double dt0,
                                  const FvStepForcing& forcing) {
+    // Both ends of a structure link are pinned to tier 0 (assignTiers), so a
+    // dummy's two nodes always fire in the same window with the same dt — the
+    // source and the sink integrate the identical discharge over the identical
+    // span, which is what keeps the pair exactly conservative. acc_nvol_ is the
+    // window's arrival volume and is zeroed below, so the drain has to be
+    // computed from it BEFORE the loop consumes it.
+    refreshDummyFlows(dt0, forcing, [&](std::size_t un) { return acc_nvol_[un]; });
+
+    // A pass-through node is pinned to its finest incident cell (assignTiers),
+    // so it is due whenever either cell fired: everything the cells refused at
+    // their rim in this window is booked here, in the same window.
+    bookLateralSpills(&nodes);
+
     for (const int n : nodes) {
         const auto un = static_cast(n);
         const double dt = static_cast(1 << node_tier_[un]) * dt0;
 
         const double drained = acc_nvol_[un];
         acc_nvol_[un] = 0.0;
+        bookDivertedLateral(un, dt, forcing);
 
         if (forcing.node_fixed_head && std::isfinite(forcing.node_fixed_head[un])) {
             state_->node_head[un] = forcing.node_fixed_head[un];
             continue;
         }
 
-        const double q_lat = (forcing.node_lateral ? forcing.node_lateral[un] : 0.0) +
-                             node_qstruct_[un];
+        const double q_lat = nodeLateral(forcing, un) + node_qstruct_[un] +
+                             nodeQDummy(un);
 
         if (algebraicActive(n)) {
             // Head was set by the flux-balance solve at face-firing time; the
@@ -2896,6 +3984,9 @@ void ExplicitFvSolver::fireNodes(const std::vector& nodes, double dt0,
 
 void ExplicitFvSolver::runMacroCycle(double dt0, int nsub,
                                      const FvStepForcing& forcing) {
+    if (tpa_) updateTpaFlags();   // once per macro cycle (#156); the caller's
+                                  // saveState precedes this, so rejection
+                                  // restores the pre-cycle flags
     const int K = static_cast(cells_by_tier_.size());
 
     // A tier-k FACE opens its window at s ≡ 0 (mod 2^k); a tier-k VOLUME closes
@@ -2917,6 +4008,8 @@ void ExplicitFvSolver::runMacroCycle(double dt0, int nsub,
 
         if (opts_.order >= 2) reconstructState();
         fireFaces(due_f_upto_[jf], dt0);
+        if (opts_.unsteady_friction != 0)
+            computeUfGradients(&due_c_upto_[jv]);  // pre-tier snapshot (#156)
         fireCells(due_c_upto_[jv], dt0, forcing);
         fireNodes(due_n_upto_[jv], dt0, forcing);
     }
@@ -2929,7 +4022,16 @@ void ExplicitFvSolver::runMacroCycle(double dt0, int nsub,
 }
 
 void ExplicitFvSolver::settleAccumulators() {
+    perf::GatedTimer _pt(perf::sec_fv_settle);
     if (acc_a_.empty()) return;
+    // Nothing pending: fireFaces has not run since the last settle, so every
+    // accumulator is exactly zero, the transfer below is a no-op, and the
+    // full-mesh refreshDepths() it ends with would recompute the state that
+    // is already there. On the 2026-09-11 baseline LTS never fired a cycle on
+    // any deck, so this was every call — at two full-mesh inversions each.
+    // TPA keeps the unconditional path: its regime latch is re-run here on
+    // purpose before depths are derived (see below).
+    if (!acc_dirty_ && !tpa_) return;
     const int nc = mesh_->n_cells();
     const int nn = mesh_->n_nodes();
 
@@ -2964,6 +4066,18 @@ void ExplicitFvSolver::settleAccumulators() {
         state_->node_head[un] =
             mesh_->node_invert[un] + nodeDepthFromVolume(n, vol);
     }
+    acc_dirty_ = false;   // everything booked has now been drained
+    // TPA (#156): re-evaluate the regime BEFORE deriving depths, so the state
+    // this cycle exports is regime-consistent. updateTpaFlags otherwise runs
+    // only at substep/cycle ENTRY, and a cell whose area collapses DURING the
+    // cycle keeps the flag until the next entry — long enough for the exported
+    // depth to come off the TPA line far past the column-separation floor the
+    // flag update itself enforces. Measured on the vented sealed-apex fixture
+    // (t_slot 2.5e-3 ft, so 0.25 ft^2 of lost area is ~98 ft of head): the
+    // published apex head reached -95.06 ft on a deck whose apex is OPEN to
+    // atmosphere and can hold no vacuum at all. It was invisible until node
+    // heads stopped being overwritten by invert+depth (Routing.cpp).
+    if (tpa_) updateTpaFlags();
     refreshDepths();
 }
 
@@ -2983,8 +4097,15 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
     std::fill(flood_vol_.begin(), flood_vol_.end(), 0.0);
     std::fill(inlet_control_.begin(), inlet_control_.end(), uint8_t{0});
     std::fill(cell_q_int_.begin(), cell_q_int_.end(), 0.0);
-
-    refreshDepths();
+    // The pass-through ledger is per routing step, like cell_q_int_: the Router
+    // divides it by dt to publish a step-mean discharge.
+    std::fill(dummy_vol_.begin(), dummy_vol_.end(), 0.0);
+
+    // A full-mesh inversion, needed only when someone other than this solver
+    // wrote cell_a since the last advance() (see state_clean_). The solver's
+    // own last update left cell_h/cell_eta_/cell_u_ as exactly what this call
+    // would recompute, so skipping it is bit-identical.
+    if (!state_clean_) refreshDepths();
     // Re-seed the node volume ledger from the head the engine currently holds,
     // so external edits (API writes, hot start, an outfall stage) take effect.
     // With the junction area fixed at init this is EXACT — it reproduces the
@@ -3021,12 +4142,43 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
         // first pass is skipped because the caller has just computed them.
         if (steps > 0 && forcing.refresh &&
             opts_.structure_coupling == StructureCoupling::SUBSTEP) {
-            forcing.refresh(forcing.refresh_user, t - t_current);
+            {
+                // Timed apart from refreshStructFlows below because Phase 1a
+                // has to attack them separately: this is the ENGINE side
+                // (Router::refreshFvBoundaryFlows — 2x O(n_nodes) + 2x
+                // O(n_links) + the structure equations), the call below is the
+                // SOLVER side (three O(n) fills + an O(n_nodes) CSR walk).
+                perf::GatedTimer _pt_cb(perf::sec_fv_bndcallback);
+                forcing.refresh(forcing.refresh_user, t - t_current);
+            }
             refreshStructFlows(forcing);
         }
 
-        if (!lists_valid_ || since_rebuild_ >= kRebuildInterval)
+        if (!lists_valid_ || since_rebuild_ >= kRebuildInterval) {
             rebuildActiveLists();
+            // A rebuild rewrites active_faces_ and cell_active_, which are
+            // exactly what censusDt() iterates. A cached Courant bound from
+            // the old list makes no promise about the new one, so the
+            // countdown restarts. No-op at the default interval of 1, where
+            // the counter is already spent by this point.
+            census_count_ = 0;
+        }
+
+        // ---- implicit pressurized head update (slot program R2a) ----------
+        // With FV_PRESSURIZED_IMPLICIT on and any cell at/above band entry,
+        // the substep runs the implicit pass on the GLOBAL path: the census
+        // takes the R2 edit (pressurized sides advection-bound), and the LTS
+        // macro cycle — whose face/volume cadences the synchronized solve
+        // cannot honour yet (R2b) — stands down for this iteration. A run
+        // that never pressurizes takes none of these branches and stays
+        // bit-identical, option on or off.
+        const bool press = anyPressurizedCell();
+        if (press && lts_valid_) {
+            // The macro cycle may hold booked-but-undrained flux; settle it
+            // before stepping globally or that water is double-timed.
+            settleAccumulators();
+            lts_valid_ = false;
+        }
 
         // ---- local time stepping (plan §3.3) -------------------------------
         // Tiers are reassigned only HERE, at a macro-cycle boundary with the
@@ -3036,7 +4188,7 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
         // different steps, so the two stages would be averaging states that
         // never shared a Δt. They are mutually exclusive, and the integrator
         // wins because it is the more specific request.
-        if (ltsEligible()) {
+        if (!press && ltsEligible()) {
             // Re-tiering costs a pass over every cell, face and node plus the
             // grading sweep. Doing it every cycle is what made tiering SLOWER
             // than global stepping on the reference model — the assignment is
@@ -3058,11 +4210,19 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
             const bool stiffness_moved =
                 lts_valid_ && lts_tiers_ > 1 &&
                 (now < 0.9 * lts_dt0_ || now > 2.0 * lts_dt0_);
+            bool retiered = false;
             if (!lts_valid_ || lts_countdown_ <= 0 || stiffness_moved) {
+                retiered = true;
                 settleAccumulators();
                 lts_tiers_ = assignTiers(lts_dt0_);
                 lts_valid_ = true;
                 lts_countdown_ = kRetierEveryCycles;
+                // settleAccumulators() drains pending flux into cells and
+                // nodes — it MOVES the state the census reads. If this cycle
+                // then falls through to the global path (K == 1, or the span
+                // does not fit), a cached bound would describe the pre-settle
+                // state. Same no-op at the default interval of 1.
+                census_count_ = 0;
             }
             const int K = lts_tiers_;
             double dt0 = lts_dt0_;
@@ -3080,17 +4240,23 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
                 // cleared on rollback, since the fluxes that produced them are
                 // being discarded with the state that produced them.
                 if (censusDt() < kStepAcceptRatio * dt0) {
+                    ++n_macro_rejected_;
+                    perf::count(perf::n_fv_macro_rejected);
                     restoreState();
                     lts_valid_ = false;      // the state that produced these
                                              // tiers is being discarded
                     std::fill(acc_a_.begin(), acc_a_.end(), 0.0);
                     std::fill(acc_q_.begin(), acc_q_.end(), 0.0);
                     std::fill(acc_nvol_.begin(), acc_nvol_.end(), 0.0);
-                    dt_cache_ = censusDt();
+                    acc_dirty_ = false;
                     census_count_ = 0;
                     // Fall through to the global path, which carries the
-                    // shrink-and-retry loop.
+                    // shrink-and-retry loop — and which censuses immediately,
+                    // on this same state, because the countdown is zero. A
+                    // census here would be that identical call made twice.
                 } else {
+                    ++n_macro_cycles_;
+                    perf::count(perf::n_fv_macro_cycles);
                     t += span;
                     steps += nsub;
                     since_rebuild_ += nsub;
@@ -3100,20 +4266,91 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
                     census_count_ = 0;
                     continue;
                 }
+            } else if (K > 1 && lts_fit_ && (t_target - t) >= 2.0 * dt0) {
+                // Phase 4c experiment: the full cycle does not fit the rest of
+                // the routing step, which today hands the remainder to GLOBAL
+                // stepping at dt₀ — every face and cell at the finest step.
+                // Cut a cycle that fits instead: re-tier with the tier count
+                // capped so 2^(K_f−1)·dt₀ ≤ remaining, run it, and invalidate
+                // the cache so the next cycle re-tiers at the full cap.
+                const double remaining = t_target - t;
+                int kf = 1 + static_cast(std::floor(std::log2(remaining / dt0)));
+                kf = std::min(kf, K);
+                if (kf >= 2) {
+                    settleAccumulators();
+                    double dt0f = lts_dt0_;
+                    const int Kf = assignTiers(dt0f, kf);
+                    lts_valid_ = false;
+                    lts_countdown_ = 0;
+                    census_count_ = 0;
+                    const int nsubf = 1 << (Kf - 1);
+                    const double spanf = static_cast(nsubf) * dt0f;
+                    if (Kf > 1 && spanf <= remaining) {
+                        if (opts_.order < 2) reconstructState();
+                        saveState();
+                        runMacroCycle(dt0f, nsubf, forcing);
+                        if (censusDt() < kStepAcceptRatio * dt0f) {
+                            ++n_macro_rejected_;
+                            perf::count(perf::n_fv_macro_rejected);
+                            restoreState();
+                            std::fill(acc_a_.begin(), acc_a_.end(), 0.0);
+                            std::fill(acc_q_.begin(), acc_q_.end(), 0.0);
+                            std::fill(acc_nvol_.begin(), acc_nvol_.end(), 0.0);
+                            acc_dirty_ = false;
+                        } else {
+                            ++n_macro_cycles_;
+                            perf::count(perf::n_fv_macro_cycles);
+                            t += spanf;
+                            steps += nsubf;
+                            since_rebuild_ += nsubf;
+                            last_h_ = dt0f;
+                            min_h_ = (min_h_ <= 0.0) ? dt0f : std::min(min_h_, dt0f);
+                            dt_cache_ = dt0f;
+                            continue;
+                        }
+                    }
+                }
+            }
+            // Fell through to the global path without settling, re-tiering
+            // or moving the state: the census taken above for the stiffness
+            // test read this same state through this same function (press
+            // is false on this path), so it IS the global path's census.
+            // Reusing it removes the second full face sweep every substep
+            // paid on the LTS path — 2.5 censuses per substep against the
+            // global path's 2.0 in the 2026-08-20 verification. A rejected
+            // cycle leaves lts_valid_ false and takes the fresh census.
+            if (!retiered && lts_valid_ && now > 0.0) {
+                dt_census_    = now;
+                census_count_ = std::max(1, opts_.cfl_census_interval);
             }
         }
 
         if (census_count_ <= 0) {
-            dt_cache_ = censusDt();
+            dt_census_ = censusDt(press);
             census_count_ = std::max(1, opts_.cfl_census_interval);
         }
         --census_count_;
 
         const double remaining = t_target - t;
-        double dt = std::min(dt_cache_, remaining);
+        double dt = std::min(dt_census_, remaining);
         if (!(dt > 0.0)) dt = remaining;
-        if (dt < constants::MIN_TIMESTEP)
-            dt = std::min(constants::MIN_TIMESTEP, remaining);
+        // The floor is a LOOP GUARD, not a granularity (issue #156 R2 root
+        // cause). constants::MIN_TIMESTEP (0.001 s) is legacy DYNWAVE routing
+        // granularity — sane for an iterated implicit scheme, fatal for an
+        // explicit one: clamping the census UP past the CFL limit detonated
+        // every deck whose stiffest cell demanded dt < 1 ms. That single
+        // clamp was the whole "high-celerity TPA instability" class, measured:
+        // the a = 25 vs 150 m/s filling threshold IS the clamp boundary
+        // (stable dt 1.4e-3 vs 2.4e-4 s on 0.04 m cells); e3's 0.23 m stub at
+        // a = 300 was clamped ~7x over CFL and blew up bit-identically at
+        // every FV_CFL because the census was discarded either way; e4's
+        // non-monotone k3 "knife edge" was cells wandering across the clamp;
+        // and the RK2-vs-Euler asymmetry was never the integrator — RK2
+        // disables LTS, whose tier-0 dt is unclamped, so only RK2 was forced
+        // through the clamped global path. kMinSubstep below exists solely so
+        // a pathological collapse cannot loop forever (the 2M-step backstop
+        // is the second line).
+        if (dt < kMinSubstep) dt = std::min(kMinSubstep, remaining);
 
         // Take the substep, then re-census the state it produced. If a cell
         // crossed the crown (or wetted, or pressurized a node) the stable step
@@ -3139,15 +4376,49 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
                 takeSubstep(dt, forcing);
             }
 
-            if (attempt >= kMaxStepRetries || dt <= constants::MIN_TIMESTEP) break;
-            const double dt_post = censusDt();
+            if (attempt >= kMaxStepRetries || dt <= kMinSubstep) break;
+            // Post-step census on the state actually reached — membership is
+            // memoryless, so re-derive it (a cell may have crossed the crown
+            // inside the step, in EITHER direction).
+            const double dt_post = censusDt(anyPressurizedCell());
             if (dt_post >= kStepAcceptRatio * dt) break;          // admissible
             restoreState();
-            dt = std::max(0.9 * dt_post, constants::MIN_TIMESTEP);
+            dt = std::max(0.9 * dt_post, kMinSubstep);
             if (dt > remaining) dt = remaining;
         }
-        dt_cache_ = dt;                 // next step starts from what worked
-        census_count_ = 0;
+        dt_cache_ = dt;                 // what suggested_step() reports
+
+        // The Courant bound, unlike the step taken, may legitimately survive
+        // into a skipped census — that is the whole point of
+        // FV_CFL_CENSUS_INTERVAL. Everything that can invalidate it resets the
+        // countdown at its own site: a rebuild of the active lists and a
+        // re-tier's settleAccumulators() above, an accepted or rejected macro
+        // cycle, and — here — a RETRY, which is the post-step census having
+        // proved the bound inadmissible for the state actually reached.
+        //
+        // A clamp to `remaining` proves nothing about the bound: the routing
+        // step is simply ending, so it must NOT be written back. Writing the
+        // clamped step into the cache is what the old `dt_cache_ = dt` did, and
+        // the unconditional `census_count_ = 0` beside it existed to undo the
+        // damage on the next substep. Both are gone; the countdown now counts,
+        // which is what makes the option mean anything for the first time.
+        //
+        // Two known gaps at k > 1, neither reachable at the default of 1:
+        //   * a retry whose shrunken dt is then clamped back up to `remaining`
+        //     (line above) does not invalidate — benign because `t` then
+        //     reaches t_target and the next advance() resets the countdown;
+        //   * dt_post from the retry loop is a FRESHER bound than the one being
+        //     counted down toward, and is discarded. Using it is the revised
+        //     plan's Phase 1c', which also removes the pre-step census.
+        //
+        // At the default interval of 1 all of this is bit-identical: the
+        // counter is reloaded to 1 and decremented to 0 in the same pass, so
+        // the next substep censuses either way, and dt_cache_ still receives
+        // the step taken so suggested_step() is unchanged.
+        if (dt < dt_census_ && dt < remaining) {
+            dt_census_    = dt;
+            census_count_ = 0;
+        }
 
         t += dt;
         // RK2 is two full operator evaluations per accepted step; count both,
@@ -3166,9 +4437,67 @@ double ExplicitFvSolver::advance(double t_current, double t_target,
     // Publish a complete state: any flux still booked but not yet drained is
     // water the engine would otherwise never see.
     settleAccumulators();
+    // From here until the next advance() nothing but this solver derives the
+    // cell state, so the entry refresh can be skipped next time. The
+    // pressurized-implicit and TPA paths rewrite cell momentum / regime
+    // flags outside the plain update and keep the unconditional refresh.
+    state_clean_ = !opts_.pressurized_implicit && !tpa_;
+
+    // Publish eligibility must reflect the state actually reached, not the
+    // static classification: a pondable junction that rose above its rim was
+    // DEMOTED to the bucket path mid-step (algebraicActive), and its head now
+    // comes from a real volume ledger that the incident conduit cells cannot
+    // describe. Reconstructing it would erase the pond -- caught by
+    // FvEngine.PondedNodeStillReportsItsFloodingRate.
+    for (std::size_t un = 0; un < node_pub_.size(); ++un)
+        if (node_pub_[un] && !algebraicActive(static_cast(un)))
+            node_pub_[un] = 0;
+
+    // Divergence guard (issue #156 R3, bounds documented at their definition).
+    // The retry loop cannot reject a dt-independent amplification — all 8
+    // retries fail identically and the step is accepted — so the state that
+    // survives to here is the last line of defence. Track the worst offender
+    // by its ratio to the bound so the reported element is the one furthest
+    // gone, not the first one found.
+    div_link_ = -1;
+    {
+        double worst = 1.0;
+        const int n_cells = mesh_->n_cells();
+        for (int c = 0; c < n_cells; ++c) {
+            const auto uc = static_cast(c);
+            const double a = state_->cell_a[uc];
+            const double q = state_->cell_q[uc];
+            const double h = state_->cell_h[uc];
+            const double u = cell_u_[uc];
+            double ratio;
+            const char* what;
+            double bad = h;
+            if (!std::isfinite(a) || !std::isfinite(q) || !std::isfinite(h)) {
+                ratio = std::numeric_limits::infinity();
+                what  = "non-finite state";
+                bad   = !std::isfinite(a) ? a : (!std::isfinite(q) ? q : h);
+            } else if (std::fabs(u) > kDivergedVelocity * worst) {
+                ratio = std::fabs(u) / kDivergedVelocity;
+                what  = "velocity (ft/s)";
+            } else if (std::fabs(h) > kDivergedDepth * worst) {
+                ratio = std::fabs(h) / kDivergedDepth;
+                what  = "depth magnitude (ft)";
+            } else {
+                continue;
+            }
+            worst      = std::min(ratio,
+                                  std::numeric_limits::max());
+            div_link_  = mesh_->conduit_link[static_cast(
+                mesh_->cell_conduit[uc])];
+            div_value_ = (what[0] == 'v') ? u : bad;
+            div_what_  = what;
+            if (!std::isfinite(ratio)) break;  // cannot get worse
+        }
+    }
 
     last_nsteps_ = steps;
     total_steps_ += steps;
+    perf::count(perf::n_fv_substep, steps);
     sim_time_ += (t - t_current);
     suggested_h_ = (dt_cache_ > 0.0 && dt_cache_ < 1.0e29) ? dt_cache_ : 0.0;
     return t;
diff --git a/src/engine/hydraulics/fv/ExplicitFvSolver.hpp b/src/engine/hydraulics/fv/ExplicitFvSolver.hpp
index e270f67f3..3fb09828e 100644
--- a/src/engine/hydraulics/fv/ExplicitFvSolver.hpp
+++ b/src/engine/hydraulics/fv/ExplicitFvSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExplicitFvSolver.hpp
  * @brief Serial/OpenMP CPU reference implementation of the explicit FV 1D solver.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_EXPLICIT_FV_SOLVER_HPP
@@ -31,6 +47,11 @@
 #include "FvOptions.hpp"
 #include "INetworkSolver.hpp"
 #include "NetworkMeshData.hpp"
+#include "PressurizedHeadSolver.hpp"
+
+namespace openswmm::transport::fvkernels {
+struct SpeciesKernelView;  // transport/fvkernels/SpeciesTransportKernels.hpp
+}
 
 namespace openswmm::fv {
 
@@ -54,6 +75,13 @@ class ExplicitFvSolver : public INetworkSolver {
     double suggested_step() const noexcept override { return suggested_h_; }
     RunStats run_stats() const noexcept override;
     bool   is_initialized() const noexcept override { return mesh_ != nullptr; }
+    bool   divergence(Divergence& d) const noexcept override {
+        if (div_link_ < 0) return false;
+        d.link  = div_link_;
+        d.value = div_value_;
+        d.what  = div_what_;
+        return true;
+    }
 
     /// Per-node net exchange VOLUME (ft³) accumulated over the last advance().
     /// Signed positive INTO the node. The Router glue turns this into the node
@@ -68,6 +96,21 @@ class ExplicitFvSolver : public INetworkSolver {
     /// reconstructed from the net afterwards.
     const std::vector& node_inflow_volume() const noexcept { return node_in_; }
     const std::vector& node_outflow_volume() const noexcept { return node_out_; }
+    /// Book a diverted lateral (credited straight into the incident cells,
+    /// bypassing the node's faces) as node OUTFLOW for the substep — it
+    /// entered the node's ledger as lateral inflow and left it, but never
+    /// crossed a face, so the face ledger holds no outflow for it. Per
+    /// substep, on both stepping paths, so a junction that alternates between
+    /// the pass-through and the solved path within a routing step is booked
+    /// exactly (the report's per-node continuity read 80–100 % at every
+    /// lateral-fed pass-through junction without it, 2026-09-13).
+    void bookDivertedLateral(std::size_t un, double dt,
+                             const FvStepForcing& forcing) noexcept {
+        if (node_lat_div_.empty() || !node_lat_div_[un] || !forcing.node_lateral)
+            return;
+        const double lat = forcing.node_lateral[un];
+        if (lat > 0.0) node_out_[un] += lat * dt;
+    }
 
     /// Per-conduit flag: did HEC-5 inlet control cap this culvert's inflow at
     /// any point in the last advance()? Reported as the "Inlet Ctrl" column.
@@ -80,6 +123,39 @@ class ExplicitFvSolver : public INetworkSolver {
         return flood_vol_;
     }
 
+    /// Per-structure-entry pass-through VOLUME (ft³) over the last advance(),
+    /// parallel to mesh.struct_link. Nonzero only for DUMMY entries, whose
+    /// discharge the solver derives rather than receiving in the forcing — the
+    /// Router has no other way to report their flow or book their node ledger.
+    const std::vector& dummy_volume() const noexcept {
+        return dummy_vol_;
+    }
+
+    /// Pass-through classification (clean degree-2 junctions whose faces
+    /// present the neighbouring cells to each other directly; refreshed with
+    /// the structure flows). The publish path reads it to reconstruct those
+    /// nodes' REPORTED heads face-consistently — the solver-internal head
+    /// stays the stable wet-mean, which also serves as the ghost boundary
+    /// state under LTS tier holds.
+    const std::vector& node_passthrough() const noexcept {
+        return node_pass_;
+    }
+
+    /// Nodes whose PUBLISHED stage should be reconstructed from the incident
+    /// wet cells rather than reported as the solver's own head. A superset of
+    /// node_passthrough(): the same cleanliness and structure/carry tests, but
+    /// at any degree, because the degree-2 restriction exists only for the
+    /// solver's direct-face bypass.
+    ///
+    /// Measured on Example1 under FLOW_ROUTING FV: nodes outside this set
+    /// published a stage up to 0.91 ft above their own adjacent cell at
+    /// FV_MIN_CELLS 1, falling ~first-order with refinement (a datum term),
+    /// while nodes inside it never exceeded 0.0002 ft at any refinement.
+    /// See tests/manual/fv_node_stage/RESULTS.md.
+    const std::vector& node_publish_stage() const noexcept {
+        return node_pub_;
+    }
+
     /// Time-integrated cell discharge (ft³) over the last advance(), used to
     /// publish a routing-step MEAN link flow rather than an end-of-step
     /// snapshot — the snapshot aliases badly when a routing step spans many
@@ -107,12 +183,22 @@ class ExplicitFvSolver : public INetworkSolver {
     void   refreshDepths();
     void   refreshNodeAreas();
     void   rebuildActiveLists();
-    double censusDt() const;
+    /// Global Courant census. @p press_edit applies the R2 edit: a
+    /// pressurized side of an implicit-eligible face is advection-bound only
+    /// (its acoustic pair is integrated implicitly this substep), and a
+    /// junction the implicit pass will fold is exempt from the algebraic
+    /// feedback bound. false everywhere the implicit pass will NOT run —
+    /// the LTS macro path, and every run without FV_PRESSURIZED_IMPLICIT.
+    double censusDt(bool press_edit = false) const;
     void   reconstructState();
-    void   computeFaceFlux(int face);
+    /// @p mass_only: the node solve's trial evaluation — same reconstruction
+    /// and wave speeds, writes f_mass_ only (plan Phase 1c).
+    void   computeFaceFlux(int face, bool mass_only = false);
+    /// Species transport forwarders (phase E0): the reconstruction / FCT /
+    /// dispersion bodies live in transport/fvkernels/SpeciesTransportKernels
+    /// and consume this solver's members through the view below.
     void   reconstructScalars(double dt);
-    void   limitSpeciesFluxes(int species, double dt);
-    kernels::FaceFlux adjustedFlux(int face) const;
+    transport::fvkernels::SpeciesKernelView speciesKernelView();
     void   computeFluxes();
     void   limitPositivity(double dt);
 
@@ -128,6 +214,14 @@ class ExplicitFvSolver : public INetworkSolver {
     /// conservation for stability, which is the one trade this solver cannot
     /// make.
     void   relaxNodeFluxes(double dt, const FvStepForcing& forcing);
+    /// Phase 3d: solve/relax every node in @p nodes, in parallel above
+    /// kOmpMinNodes (order-independent, bit-identical at any thread count).
+    template 
+    void   solveNodes(const std::vector& nodes, DtOf&& dt_of,
+                      const FvStepForcing& forcing);
+    std::vector node_solve_list_;   ///< global-path node list (scratch)
+    std::vector node_heavy_;        ///< junctions that run the bracketed solve (shared by the parallel loop)
+    std::vector node_light_;        ///< pass-through / storage nodes (serial)
 
     /// One node's worth of the above. Split out because the tiered path applies
     /// it per node at that node's own Δt, while the global path applies it to
@@ -167,10 +261,58 @@ class ExplicitFvSolver : public INetworkSolver {
     /// other directly (faceSide/computeFaceFlux) — the direct spliced face —
     /// which transmits both momentum and depth across the interface exactly.
     std::vector node_pass_;
+    /// Static/full halves of the PUBLISH-stage test — see
+    /// node_publish_stage(). Deliberately separate from node_pass_, which the
+    /// SOLVER reads: widening node_pass_ instead would change the direct-face
+    /// bypass and with it the routing, which this is explicitly not allowed to
+    /// do (solver-internal heads are load-bearing ghost states under LTS tier
+    /// holds).
+    std::vector node_pub_static_;
+    std::vector node_pub_;
     /// Residual-volume carry (ft³) for algebraic junctions: root-solve
     /// tolerance and any cell-side positivity scaling land here and are bled
     /// back into the next solve's forcing. ≈0 in a converged steady state.
     std::vector node_carry_;
+    /// Lateral inflow diverted from a clean degree-2 junction into its two
+    /// incident cells (half each) as a zero-momentum area source, so the node
+    /// KEEPS the pass-through splice. Head-solving such junctions costs the
+    /// split-Riemann ~1 mm of head per junction that pass-through exists to
+    /// avoid — with rain on every junction of a 400-conduit channel that
+    /// integrated into an 18-25% deep bias with exact q (SWASHES §3.3).
+    /// cell_qlat_ is m³/s per cell; node_lat_div_ flags the nodes whose
+    /// forcing.node_lateral must read as zero on every node path.
+    std::vector cell_qlat_;
+    std::vector node_lat_div_;
+    double nodeLateral(const FvStepForcing& forcing,
+                       std::size_t un) const noexcept {
+        if (!node_lat_div_.empty() && node_lat_div_[un]) return 0.0;
+        return forcing.node_lateral ? forcing.node_lateral[un] : 0.0;
+    }
+    /// The diverted lateral's RIM. A pass-through junction has no head state,
+    /// so the injection above had no ceiling: once the incident cells were
+    /// full, every m³ the pipe could not convey went into the Preissmann
+    /// slot, whose storage is t_slot·L ≈ 1e-3 m² per pipe — about a kilometre
+    /// of head per m³ — and the divergence guard (ERROR 14) fired within a
+    /// routing step of the first overload (Bellinge, 2026-09-05: junction
+    /// depths of 90–200 m alternating with 0.1 m as the 2D drain toggled
+    /// sign, then 3,346 m). A solved junction clamps at its rim and books the
+    /// surplus as flooding or ponded volume; the diverted path now does the
+    /// same at the cell. face_a_rim_ is the receiving cell's area at the node
+    /// rim (invert + full depth, + surcharge depth when sealed; +inf where no
+    /// rim applies: open sections, no full depth on record, faces of
+    /// non-pass-through nodes). The injection stops at that area and the
+    /// remainder is banked per FACE in face_lat_spill_ (ft³) — per face, not
+    /// per cell, because a one-cell conduit can receive from a pass-through
+    /// junction at each end — and drained by bookLateralSpills at the node
+    /// update into flood_vol_ (sealed) or the ponded-volume ledger (pondable,
+    /// which demotes the node to the bucket path exactly as
+    /// settleAlgebraicNode's ponding branch does). Only the owning cell writes
+    /// a boundary face's slot, so the cell update stays race-free.
+    std::vector face_a_rim_;
+    std::vector face_lat_spill_;
+    double injectDivertedLateral(std::size_t uc, double a_new, double dt,
+                                 double inv_dx);
+    void   bookLateralSpills(const std::vector* nodes);
     /// Cached V(full_depth) per node, for the ponding demote test.
     std::vector node_vfull_;
 
@@ -185,6 +327,28 @@ class ExplicitFvSolver : public INetworkSolver {
             state_->node_volume[un] > node_vfull_[un]) return false;
         return true;
     }
+
+    /// Is any cell incident to node @p un pressurized (closed section at or
+    /// above its crown, or a TPA-flagged column)? Same predicate as the step
+    /// census and anyPressurizedCell(). Read by refreshStructFlows: a
+    /// surcharged degree-2 junction leaves the pass-through splice for the
+    /// solved path, whose rim clamp and flooding are what the splice lacks.
+    bool incidentPressurized(std::size_t un) const noexcept {
+        for (int p = mesh_->node_face_ptr[un];
+             p < mesh_->node_face_ptr[un + 1]; ++p) {
+            const auto uf = static_cast(
+                mesh_->node_face_idx[static_cast(p)]);
+            const int c = (mesh_->face_cl[uf] >= 0) ? mesh_->face_cl[uf]
+                                                    : mesh_->face_cr[uf];
+            if (c < 0) continue;
+            const auto uc = static_cast(c);
+            if (tpaCell(uc)) return true;
+            const FvGeometry& g =
+                mesh_->geom[static_cast(mesh_->cell_geom[uc])];
+            if (!g.is_open && state_->cell_h[uc] >= g.y_crown) return true;
+        }
+        return false;
+    }
     void   updateCells(double dt, const FvStepForcing& forcing);
     void   updateNodes(double dt, const FvStepForcing& forcing);
     void   dispersionSolve(double dt);
@@ -198,12 +362,41 @@ class ExplicitFvSolver : public INetworkSolver {
     void   refreshStructFlows(const FvStepForcing& forcing);
     std::vector node_qstruct_;
 
-    double nodeDepthFromVolume(int node, double volume) const;
+    /// Pass-through source/sink from DUMMY links, kept separate from
+    /// node_qstruct_ because it is derived, not forced: a dummy carries
+    /// whatever arrives at its upstream node, so its value depends on the very
+    /// fluxes the node update is about to integrate. Computed by
+    /// refreshDummyFlows() immediately before each node update, from the same
+    /// arrival volume that update will use, which makes the drain exact rather
+    /// than lagged. Folded into q_lat alongside node_qstruct_ at all three
+    /// integration sites (relaxOneNode, updateNodes, fireNodes).
+    std::vector node_qdummy_;
+
+    /// Volume each DUMMY link has passed through so far this routing step
+    /// (ft³), parallel to mesh.struct_link. Router divides by dt to publish the
+    /// step-mean discharge, matching how real structure flows are reported.
+    std::vector dummy_vol_;
+
+    /// Compute the DUMMY pass-through for one node-update pass and scatter it
+    /// into node_qdummy_. `arrived(n)` must return the NET volume (ft³) that
+    /// reached node n over `dt` from its faces — the quantity the caller is
+    /// about to add to the node's storage. The dummy removes exactly that,
+    /// plus the node's lateral and structure forcing, so the upstream node's
+    /// volume is unchanged: DW's own continuity for a dummy reduces to
+    /// dV/dt = 0 (findNonConduitFlow sets Q = inflow + overflow, and
+    /// updateNodeFlows books it as outflow — dynwave.c:418-449).
+    template 
+    void refreshDummyFlows(double dt, const FvStepForcing& forcing,
+                           ArrivedFn&& arrived);
+
+    /// node_qdummy_ with the empty-vector case folded in — a model with no
+    /// dummy links never allocates it, and every integration site would
+    /// otherwise need the same guard.
+    double nodeQDummy(std::size_t un) const noexcept {
+        return node_qdummy_.empty() ? 0.0 : node_qdummy_[un];
+    }
 
-    /// dV/dH at an arbitrary depth — what the semi-implicit node correction is
-    /// damped against once Picard sweeping has moved the head off the one
-    /// `node_surf_area` was refreshed at.
-    double nodeStorageSlope(int node, double depth) const;
+    double nodeDepthFromVolume(int node, double volume) const;
 
     /// Is this face's flux the one being computed and booked RIGHT NOW?
     ///
@@ -214,21 +407,20 @@ class ExplicitFvSolver : public INetworkSolver {
     /// that belongs to a different window, which is the one property the
     /// macro cycle's face-open/volume-close offset exists to guarantee.
     ///
-    /// Picard's flux re-solve is therefore restricted to live faces. The
-    /// residual still sums over ALL incident faces (a held flux is the best
-    /// estimate of what that face is carrying), and the linear correction is
-    /// still written to all of them, exactly as the single-sweep scheme did —
-    /// only the re-solve is gated. On the global path every face is live.
+    /// The algebraic-junction re-solve and the LTS due-set machinery are the
+    /// callers; both must touch only live faces. On the global path every
+    /// face is live.
     /// Can the LTS macro cycle run under the current options and state?
     /// One predicate shared by advance() and censusDt(): tiering is off under
     /// RK2 (the two stages must share one Δt) and under transport (the FCT
-    /// sweep is synchronous). censusDt() skips the node stability term only
+    /// sweep is synchronous). censusDt() skips the node accuracy bound only
     /// when tiering can actually supply the node its own fine tier — gating
     /// that skip on the FV_LTS option alone silently dropped the node bound
     /// from the global path whenever the option was on but tiering was not
-    /// running (RK2, species), reproducing FV_NODE_DT NONE unasked.
+    /// running (RK2, species).
     bool ltsEligible() const noexcept {
-        return opts_.lts && opts_.time_integration != TimeIntegration::RK2 &&
+        return opts_.lts &&
+               opts_.time_integration != TimeIntegration::RK2 &&
                state_ && state_->n_species == 0;
     }
 
@@ -251,8 +443,41 @@ class ExplicitFvSolver : public INetworkSolver {
     /// Semi-implicit friction for one cell: Manning, or — for a FORCE_MAIN
     /// running full — the Hazen-Williams / Darcy-Weisbach law the section
     /// actually obeys, through the engine's own forcemain functions.
-    double frictionFor(const FvGeometry& g, double q, double u, double h,
-                       double dt) const;
+    /// Explicit stability bound for an ALGEBRAIC junction (issue: FV rings on
+    /// pressurized networks while dynamic wave does not).
+    ///
+    /// An algebraic junction has no volume state, so it has no STORAGE bound --
+    /// which is why it was exempted here. But it is not unbounded. Its head is
+    /// solved from the instantaneous flux balance and then handed to the
+    /// incident cells as a ghost, so the neighbours integrate against a
+    /// boundary state that can travel a long way inside one step. That feedback
+    /// loop is explicit, and it has its own limit:
+    ///
+    ///     tau = min_i( 0.5*dx_i*T_i )  /  sum_j( T_j*c_j )
+    ///
+    /// Every incident conduit pushes flux into the junction (the sum), but the
+    /// solved head has to be resolved on the TIGHTEST incident storage (the
+    /// min) -- that is the ghost the stiffest neighbour sees. Summing the
+    /// numerator instead, the obvious first guess and what legacy DW does for
+    /// its own node continuity solve, makes the bound LOOSER at exactly the
+    /// junctions that need it: at a 12 ft barrel meeting a 3 ft one the summed
+    /// area gives an effective length of 2123 ft against a 250 ft cell.
+    ///
+    /// Relative to the cell bound this is 1/(2n) * (T_min/T_max), i.e. purely
+    /// geometric: 4x for two identical barrels, 32x across a 16:1 area step.
+    /// Those are the factors the EPA QA decks were measured to need (test5 2x,
+    /// test2 25x), which is what the global FV_CFL had to be hand-lowered to
+    /// 0.1 and 0.02 to fake.
+    ///
+    /// Gated on the junction actually being pressurized: below the crown the
+    /// slot is not engaged, the head response is soft, and the measured
+    /// oscillation disappears entirely (enlarging the barrels so they never
+    /// surcharge takes the zigzag index from 37.6 to 4.97, dynamic wave's own
+    /// value). So an open-channel network pays nothing for this.
+    double algebraicNodeStableDt(int n) const noexcept;
+
+    double frictionFor(const FvGeometry& g, double roughness, double rough_factor,
+                       double q, double u, double h, double dt) const;
 
     /// Apply the node's capacity rule to a freshly-integrated volume: ponding,
     /// surcharge depth, and the flooding that removes water once neither can
@@ -274,7 +499,9 @@ class ExplicitFvSolver : public INetworkSolver {
     /// Partition the active mesh into power-of-two tiers. Returns the tier
     /// count K and writes the finest requirement to @p dt0. K == 1 means the
     /// mesh is uniformly stiff and the caller should take the global path.
-    int    assignTiers(double& dt0);
+    /// @p k_cap_override > 0 caps the tier count (plan Phase 4c: a cycle cut
+    /// to fit the remaining routing-step window).
+    int    assignTiers(double& dt0, int k_cap_override = 0);
 
     /// Fire every entity due at one base substep. Faces compute their flux and
     /// BOOK `±F·Δt` into both incident control volumes' accumulators; cells and
@@ -309,6 +536,20 @@ class ExplicitFvSolver : public INetworkSolver {
     /// positivity-limit, transport, then the cell and node updates.
     void   takeSubstep(double dt, const FvStepForcing& forcing);
 
+    // -- implicit pressurized head update (slot program R2a) ----------------
+    /// Any active closed-section cell at/above band entry? Cheap early-exit
+    /// scan deciding whether this substep runs the implicit pass (and
+    /// whether the census may apply the R2 edit).
+    bool   anyPressurizedCell() const;
+    /// Would the implicit pass fold this junction as an unknown row RIGHT
+    /// NOW? Pure state predicate, shared by the census's feedback-bound
+    /// exemption and classify()'s fold pass.
+    bool   nodePressFolded(int n) const;
+    PressurizedView pressView(const FvStepForcing& forcing);
+    PressurizedHeadSolver press_;
+    /// Did classify() find implicit work for the substep in flight?
+    bool   press_step_ = false;
+
     /// Snapshot / average for SSP-RK2. `rkSave` records Uⁿ and the ledger
     /// totals; `rkAverage` forms ½(Uⁿ + U⁽²⁾) and halves the ledger deltas the
     /// two stages accumulated, which is what makes the reported flow integral
@@ -340,7 +581,6 @@ class ExplicitFvSolver : public INetworkSolver {
     // g·(I₁(h_K) − I₁(h*_K)) — per-cell, not per-face, which is why they are
     // stored separately from the shared flux.
     std::vector f_mass_, f_mom_, f_sstar_, f_corr_l_, f_corr_r_;
-    std::vector f_scale_;
 
     /// Reconstructed species values on each side of each face, species-major
     /// [s * n_faces + f]. Filled by reconstructScalars() — this is the
@@ -385,6 +625,52 @@ class ExplicitFvSolver : public INetworkSolver {
     // Cell scratch.
     std::vector cell_eta_;     ///< z_b + h
     std::vector cell_u_;       ///< Q/A, dry-guarded
+
+    /// Closure at the CELL depth, refreshed by cacheClosure() at every write
+    /// of cell_h: A(h), T(h) and I₁(h) of the cell's own section. Zero for a
+    /// dry or TPA-flagged cell (neither consumer reads it then). faceSide, the
+    /// census and the LTS stability bounds evaluated exactly these at the
+    /// stored depth, several times per substep and once per node-solve trial;
+    /// read from here the value is the same call on the same inputs, so the
+    /// results are bit-identical (plan Phase 1b).
+    std::vector cell_ah_;      ///< areaOfDepth(g, cell_h)
+    std::vector cell_t_;       ///< widthOfDepth(g, cell_h)
+    std::vector cell_i1_;      ///< i1OfDepth(g, cell_h, cell_ah_)
+    void cacheClosure(std::size_t uc, const FvGeometry& g, double h) noexcept;
+
+    /// Unsteady-friction convective term c·sgn(Vⁿ)·|∂V/∂x|ⁿ per cell
+    /// (issue #156). Precomputed from a consistent old-state snapshot before
+    /// each (parallel) cell-update loop so no update reads a mid-update
+    /// neighbor; sized only when FvOptions::unsteady_friction != 0.
+    std::vector uf_grad_;
+
+    /// Fill uf_grad_ for @p cells (nullptr = all cells) from the current
+    /// cell_u_/state snapshot. Same-conduit neighbors only: across virtual
+    /// junction splices the conduit frames may point into each other, so the
+    /// stencil falls back to one-sided there rather than risk a sign flip.
+    void computeUfGradients(const std::vector* cells);
+
+    // -- TPA pressure closure (issue #156 Phase 4) ---------------------------
+    bool tpa_ = false;                    ///< FV_PRESSURE_CLOSURE == TPA
+    bool mixed_wave_ = true;              ///< slot/free interface wave bound (dev switch)
+    bool mw_rh_  = true;                  ///< bore-speed bound at interior slot/free faces
+    bool deg1_guard_slot_ = true;         ///< degree-1 prescribed discharge skips a slot interior (dev: DEG1=1 off)
+    bool census_pass_far_ = true;         ///< census bounds a pass-through ghost by the FAR cell it fluxes (dev: CENSUS_PASS=0 off)
+    bool lts_fit_ = false;                ///< 4c experiment: a shorter macro cycle when the full one does not fit (OPENSWMM_FV_LTS_FIT=1)
+    /// The far cell a pass-through junction's ghost presents at @p face, or
+    /// -1 when the node is not an active pass-through (plan Phase 1e).
+    int  passThroughFarCell(int face, int nd) const noexcept;
+    std::vector tpa_scratch_;    ///< previous-flag snapshot (sweep)
+    std::vector save_tpa_;       ///< step-rejection snapshot
+
+    /// Update the per-cell regime flags (state_->cell_tpa) once per substep
+    /// from the venting rule — see the implementation comment.
+    void updateTpaFlags();
+
+    /// Regime of one cell under TPA; always false when the closure is SLOT.
+    bool tpaCell(std::size_t uc) const noexcept {
+        return tpa_ && state_->cell_tpa[uc] != 0;
+    }
     std::vector cell_q_int_;   ///< ∫(mean face mass flux) dt over the
                                        ///< routing step — the DISCHARGE the
                                        ///< report publishes; equals ∫Q dt in
@@ -415,12 +701,38 @@ class ExplicitFvSolver : public INetworkSolver {
     std::vector rk_node_vol_, rk_node_head_;
     std::vector rk_exch_, rk_in_, rk_out_, rk_flood_, rk_qint_,
                         rk_carry_;
+    std::vector rk_tpa_;   ///< Uⁿ regime latch (issue #156 R4c)
 
     /// Accept a substep when the post-step stable step is at least this
     /// fraction of the step actually taken.
     static constexpr double kStepAcceptRatio = 0.5;
     static constexpr int    kMaxStepRetries  = 8;
 
+    /// Substep floor — a loop guard only, far below any stable step this
+    /// solver legitimately computes. NOT constants::MIN_TIMESTEP (0.001 s,
+    /// legacy DYNWAVE routing granularity): clamping an EXPLICIT scheme's
+    /// census up to that value violates CFL wherever a cell demands
+    /// dt < 1 ms, which is routine at acoustic slot celerities on sub-foot
+    /// cells — and was the root cause of the issue-#156 "high-celerity TPA
+    /// instability" class (see the comment at the clamp site in advance()).
+    static constexpr double kMinSubstep = 1.0e-6;   ///< s
+
+    // Divergence guard (issue #156 R3). The retry loop above is sound for CFL
+    // violations, which shrink away with dt — but a dt-INDEPENDENT
+    // amplification (measured: RK2 x TPA on the study's e3 siphon grows the
+    // crown head x20-40 per millisecond at FV_CFL 0.9, 0.45 and 0.25 alike)
+    // fails all 8 retries identically and the loop then ACCEPTS the diverged
+    // step silently. These bounds are physical absurdities, not tolerances: no
+    // water transient carries particle velocity past 1000 ft/s (celerity is
+    // not particle speed), and 10,000 ft of pressure head is 300 bar. A run
+    // that crosses either has left the physics and must say so instead of
+    // scoring OK (P6 finding F3). Checked once per routing step, O(cells).
+    static constexpr double kDivergedVelocity = 1000.0;    ///< ft/s
+    static constexpr double kDivergedDepth    = 10000.0;   ///< ft
+    int         div_link_  = -1;       ///< engine link index, -1 = clean
+    double      div_value_ = 0.0;
+    const char* div_what_  = nullptr;
+
     // Work lists (plan §5.2.1). `halo_` is the compaction safety margin: a wet
     // front advances at most CFL cells per substep, so a halo of `rebuild_
     // interval_` cells keeps a stale list conservative between rebuilds.
@@ -473,11 +785,57 @@ class ExplicitFvSolver : public INetworkSolver {
     long   total_flux_   = 0;
     double min_h_        = 0.0;
     double sim_time_     = 0.0;
+    /// LTS macro cycles that ran / were rejected by the post-cycle census.
+    /// The tier histogram is filled whether or not a cycle ever fits the
+    /// routing step; these say whether tiering ENGAGED.
+    long   n_macro_cycles_   = 0;
+    long   n_macro_rejected_ = 0;
+
+    /// True while cell_h / cell_eta_ / cell_u_ are exactly what the solver's
+    /// own last update derived from cell_a. advance() then skips its entry
+    /// refreshDepths() — a full-mesh depth inversion that was 27-32 % of a
+    /// reach deck's step in the 2026-09-11 baseline — bit-identically, since
+    /// the refresh would recompute the same values from the same areas. The
+    /// Router writes cell_a only before initialize() (the initial seed), so
+    /// initialize()/reinitialize() are the only places that clear it; the
+    /// pressurized-implicit and TPA paths keep the refresh unconditional.
+    bool   state_clean_ = false;
+    /// True while acc_a_/acc_q_/acc_nvol_ hold flux fireFaces booked and no
+    /// volume has drained. Lets settleAccumulators() skip its transfer AND the
+    /// two full-mesh refreshDepths() it ends with when no macro cycle has run
+    /// since the last settle — which, on every deck of the 2026-09-11
+    /// baseline, was always (LTS fired 0 cycles) while costing 25-50 % of wall.
+    bool   acc_dirty_ = false;
+    /// Per-face √(g·A·T) scratch for relaxOneNode: pass 1 evaluates it into
+    /// here and pass 2 reads it, instead of evaluating the same geometry twice.
+    std::vector relax_beta_;
+
+    // dt-argmin attribution (slot program R0): who owned the binding CFL
+    // element, counted once per censusDt (global path) / assignTiers (LTS
+    // path). `mutable` because censusDt is const; these are telemetry.
+    mutable long dt_argmin_pressurized_ = 0;
+    mutable long dt_argmin_band_        = 0;
+    mutable long dt_argmin_free_        = 0;
+    mutable long dt_argmin_node_        = 0;
     double active_sum_   = 0.0;
     double active_min_   = -1.0;
     double active_max_   = -1.0;
     long   active_n_     = 0;
+
+    /// The step the last accepted substep actually TOOK. Published as
+    /// suggested_step() and therefore what Router::getAdaptiveStep offers the
+    /// engine as the next routing step.
     double dt_cache_     = 0.0;
+
+    /// The CFL bound the last census returned — deliberately distinct from
+    /// dt_cache_. `dt_cache_` is clamped to the time remaining in the routing
+    /// step, so caching it as the Courant bound would drag every later substep
+    /// down to whatever fragment closed the previous step. Only this one may be
+    /// carried across a skipped census (FV_CFL_CENSUS_INTERVAL > 1).
+    double dt_census_    = 0.0;
+
+    /// Substeps remaining before the next full Courant census. Reloaded from
+    /// FV_CFL_CENSUS_INTERVAL; zero forces a census on the next substep.
     int    census_count_ = 0;
 };
 
diff --git a/src/engine/hydraulics/fv/FvClosureKernels.hpp b/src/engine/hydraulics/fv/FvClosureKernels.hpp
new file mode 100644
index 000000000..a820365e2
--- /dev/null
+++ b/src/engine/hydraulics/fv/FvClosureKernels.hpp
@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file FvClosureKernels.hpp
+ * @brief The explicit-FV cross-section closure as a single-source POD kernel:
+ *        one monotone cubic-Hermite table per section, with T ≡ dA/dh and
+ *        I₁ ≡ ∫A by construction, and a Newton inverse on the same cubic.
+ *
+ * @details Plan FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11 §2a/§2a‴. The table is
+ *          built once at mesh build (NetworkMeshBuilder::buildClosure) by
+ *          sampling the EXACT section geometry (SectionGeometry.hpp) at N+1
+ *          uniform depths on [0, y_full], with the tapered Preissmann slot
+ *          folded in; above y_full the closure is the analytic slot line, as
+ *          it always was. Every function here is a plain inline over scalars
+ *          and a `const FvClosure&` — no pointers, no allocation, no
+ *          exceptions, no dispatch on shape — so the same bodies compile for
+ *          the CPU solver and, annotated, for the device backend.
+ *
+ *          Two classes share the struct:
+ *            - kTabulated: the Hermite table (closed shapes, table-defined
+ *              shapes, transects). A per panel is a cubic in the local
+ *              coordinate t ∈ [0,1]; T is its derivative; I₁ its integral
+ *              plus the running sum; R is interpolated linearly.
+ *            - kPolynomial: open sections whose area is a polynomial of
+ *              degree ≤ 2 (RECT_OPEN, TRAPEZOIDAL, TRIANGULAR). Closed forms
+ *              in the hot loop — cheaper than any table gather — with an exact
+ *              quadratic-formula inverse (plan §2a″ cost weighting).
+ *
+ *          Why a Hermite table with the exact width as node slope: the legacy
+ *          A and W tables are independent tabulations, so Newton on them was
+ *          unsafe and the solver paid Brent's ~6-8 evaluations and a
+ *          dependent divide chain per inversion (185 ns on a circle, of which
+ *          only ~28 ns were closure calls). Here the derivative IS the
+ *          closure's own, monotone by the Fritsch–Carlson limiter, so a
+ *          safeguarded Newton converges in 2-3 steps and cannot fail.
+ *
+ * @ingroup engine_fv
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_FV_CLOSURE_KERNELS_HPP
+#define OPENSWMM_ENGINE_FV_CLOSURE_KERNELS_HPP
+
+#include 
+#include 
+#include 
+
+// Same portable-kernel marker as FvKernels.hpp / InertialKernels.hpp.
+#ifndef OPENSWMM_KERNEL_FN
+#define OPENSWMM_KERNEL_FN inline
+#endif
+
+namespace openswmm::fv {
+
+/// Panels of the closure table, uniform in depth on [0, y_full].
+inline constexpr int kClosurePanels = 128;
+
+/// The closure's representation class.
+enum : uint8_t { kClosureTabulated = 0, kClosurePolynomial = 1 };
+
+/**
+ * @brief One section's closure. Fixed-size POD: inline arrays, no pointers.
+ *
+ * Node i sits at h_i = i·dh, dh = y_full / kClosurePanels. `A` and `M` are the
+ * area and its slope (top width) at the nodes, `I1` the running integral of the
+ * panel cubics, `R` the hydraulic radius. `j_of_a[k]` is the panel containing
+ * area k·a_crown/kClosurePanels — the inverse's O(1) locate.
+ *
+ * All areas and widths are per CELL (barrels folded in); R is per barrel, as
+ * everywhere else in the solver.
+ */
+struct FvClosure {
+    double y_full   = 0.0;
+    double dh       = 0.0;
+    double inv_dh   = 0.0;
+    double a_crown  = 0.0;   ///< A(y_full) incl. the tapered slot = A[N]
+    double t_slot   = 0.0;   ///< slot top width above the crown
+    double i1_crown = 0.0;   ///< I₁(y_full) = I1[N]
+    double r_full   = 0.0;   ///< R above the crown
+    double inv_a_crown_n = 0.0;   ///< kClosurePanels / a_crown
+
+    // kClosurePolynomial: A = c2·h² + c1·h, P = p0 + p1·h on [0, y_full].
+    double c2 = 0.0, c1 = 0.0, p0 = 0.0, p1 = 0.0;
+
+    uint8_t kind = kClosureTabulated;
+
+    double  A [kClosurePanels + 1] = {};
+    double  M [kClosurePanels + 1] = {};
+    double  I1[kClosurePanels + 1] = {};
+    double  R [kClosurePanels + 1] = {};
+    int16_t j_of_a[kClosurePanels + 1] = {};
+};
+
+static_assert(std::is_trivially_copyable_v,
+              "FvClosure must be a plain buffer a device backend can copy");
+static_assert(std::is_standard_layout_v,
+              "FvClosure must be standard-layout");
+
+namespace kernels {
+
+/// A, T and I₁ at one depth, from one panel locate.
+struct ClosureEval {
+    double a  = 0.0;
+    double t  = 0.0;
+    double i1 = 0.0;
+};
+
+/// Panel index and local coordinate for a sub-crown depth (0 ≤ h < y_full).
+OPENSWMM_KERNEL_FN void closureLocate(const FvClosure& c, double h,
+                                      int& i, double& t) noexcept {
+    double x = h * c.inv_dh;
+    i = static_cast(x);
+    if (i < 0) i = 0;
+    if (i > kClosurePanels - 1) i = kClosurePanels - 1;
+    t = x - static_cast(i);
+    if (t < 0.0) t = 0.0;
+    if (t > 1.0) t = 1.0;
+}
+
+/// Hermite cubic on panel i at local t: value, d/dh and ∫₀ᵗ (× dh).
+OPENSWMM_KERNEL_FN void closureHermite(const FvClosure& c, int i, double t,
+                                       double& a, double& dadh,
+                                       double& int_dh) noexcept {
+    const double a0 = c.A[i], a1 = c.A[i + 1];
+    const double m0 = c.M[i] * c.dh, m1 = c.M[i + 1] * c.dh;   // slopes in t
+    const double t2 = t * t, t3 = t2 * t;
+    const double h00 = 2.0 * t3 - 3.0 * t2 + 1.0;
+    const double h10 = t3 - 2.0 * t2 + t;
+    const double h01 = -2.0 * t3 + 3.0 * t2;
+    const double h11 = t3 - t2;
+    a = h00 * a0 + h10 * m0 + h01 * a1 + h11 * m1;
+    const double d00 = 6.0 * t2 - 6.0 * t;
+    const double d10 = 3.0 * t2 - 4.0 * t + 1.0;
+    const double d01 = -6.0 * t2 + 6.0 * t;
+    const double d11 = 3.0 * t2 - 2.0 * t;
+    dadh = (d00 * a0 + d10 * m0 + d01 * a1 + d11 * m1) * c.inv_dh;
+    const double t4 = t2 * t2;
+    const double i00 = 0.5 * t4 - t3 + t;
+    const double i10 = 0.25 * t4 - (2.0 / 3.0) * t3 + 0.5 * t2;
+    const double i01 = -0.5 * t4 + t3;
+    const double i11 = 0.25 * t4 - t3 / 3.0;
+    int_dh = (i00 * a0 + i10 * m0 + i01 * a1 + i11 * m1) * c.dh;
+}
+
+/// A, T, I₁ at depth h — one locate, one Hermite evaluation.
+OPENSWMM_KERNEL_FN ClosureEval closureEval(const FvClosure& c, double h) noexcept {
+    ClosureEval e;
+    if (h <= 0.0) return e;
+    if (h >= c.y_full) {
+        const double d = h - c.y_full;
+        e.a  = c.a_crown + c.t_slot * d;
+        e.t  = c.t_slot;
+        e.i1 = c.i1_crown + c.a_crown * d + 0.5 * c.t_slot * d * d;
+        return e;
+    }
+    if (c.kind == kClosurePolynomial) {
+        e.a  = (c.c2 * h + c.c1) * h;
+        e.t  = 2.0 * c.c2 * h + c.c1;
+        e.i1 = (c.c2 * h / 3.0 + 0.5 * c.c1) * h * h;
+        return e;
+    }
+    int i; double t;
+    closureLocate(c, h, i, t);
+    double a, dadh, idh;
+    closureHermite(c, i, t, a, dadh, idh);
+    e.a  = a;
+    e.t  = (dadh > 0.0) ? dadh : 0.0;
+    e.i1 = c.I1[i] + idh;
+    return e;
+}
+
+OPENSWMM_KERNEL_FN double closureArea(const FvClosure& c, double h) noexcept {
+    if (h <= 0.0) return 0.0;
+    if (h >= c.y_full) return c.a_crown + c.t_slot * (h - c.y_full);
+    if (c.kind == kClosurePolynomial) return (c.c2 * h + c.c1) * h;
+    int i; double t;
+    closureLocate(c, h, i, t);
+    double a, dadh, idh;
+    closureHermite(c, i, t, a, dadh, idh);
+    return a;
+}
+
+OPENSWMM_KERNEL_FN double closureWidth(const FvClosure& c, double h) noexcept {
+    if (h <= 0.0) return 0.0;
+    if (h >= c.y_full) return c.t_slot;
+    if (c.kind == kClosurePolynomial) return 2.0 * c.c2 * h + c.c1;
+    int i; double t;
+    closureLocate(c, h, i, t);
+    double a, dadh, idh;
+    closureHermite(c, i, t, a, dadh, idh);
+    return (dadh > 0.0) ? dadh : 0.0;
+}
+
+OPENSWMM_KERNEL_FN double closureI1(const FvClosure& c, double h) noexcept {
+    return closureEval(c, h).i1;
+}
+
+/// Hydraulic radius: linear between nodes (friction only), r_full above.
+OPENSWMM_KERNEL_FN double closureHydRad(const FvClosure& c, double h) noexcept {
+    if (h <= 0.0) return 0.0;
+    if (h >= c.y_full) return c.r_full;
+    if (c.kind == kClosurePolynomial) {
+        const double p = c.p0 + c.p1 * h;
+        return (p > 0.0) ? (c.c2 * h + c.c1) * h / p : 0.0;
+    }
+    int i; double t;
+    closureLocate(c, h, i, t);
+    return c.R[i] + t * (c.R[i + 1] - c.R[i]);
+}
+
+/**
+ * @brief Depth from area — the inverse of closureArea on the same closure.
+ *
+ * Polynomial class: the quadratic formula in its cancellation-free form.
+ * Tabulated class: the area-uniform index picks the panel, a linear seed
+ * starts Newton on the panel cubic (whose derivative is the closure's own
+ * top width, ≥ 0 by the monotone limiter), and a bisection bracket guards
+ * every step. Exit at 1e-15·y_full in depth, as the Brent inverse did.
+ */
+OPENSWMM_KERNEL_FN double closureDepthOfArea(const FvClosure& c, double a) noexcept {
+    if (a <= 0.0) return 0.0;
+    if (a >= c.a_crown) return c.y_full + (a - c.a_crown) / c.t_slot;
+    if (c.kind == kClosurePolynomial) {
+        if (c.c2 <= 0.0) return (c.c1 > 0.0) ? a / c.c1 : 0.0;
+        return 2.0 * a / (c.c1 + std::sqrt(c.c1 * c.c1 + 4.0 * c.c2 * a));
+    }
+
+    int k = static_cast(a * c.inv_a_crown_n);
+    if (k < 0) k = 0;
+    if (k > kClosurePanels) k = kClosurePanels;
+    int i = c.j_of_a[k];
+    while (i > 0 && c.A[i] > a) --i;
+    while (i < kClosurePanels - 1 && c.A[i + 1] < a) ++i;
+
+    const double a0 = c.A[i], a1 = c.A[i + 1];
+    if (a <= a0) return static_cast(i) * c.dh;
+    if (a >= a1) return static_cast(i + 1) * c.dh;
+
+    const double tol = 1.0e-15 * c.y_full * c.inv_dh;   // in units of t
+    double lo = 0.0, hi = 1.0;
+    const double frac = (a - a0) / (a1 - a0);
+    // Seed: the secant, except in a panel whose lower node has zero width
+    // (the invert of a round section, A ∝ t² there): sqrt overestimates by
+    // ≤ √1.5 and Newton on the convex panel then descends monotonically.
+    double t = (c.M[i] > 0.0) ? frac : std::sqrt(frac);
+    for (int it = 0; it < 12; ++it) {
+        double f, dadh, idh;
+        closureHermite(c, i, t, f, dadh, idh);
+        f -= a;
+        if (f == 0.0) break;
+        if (f > 0.0) hi = t; else lo = t;
+        // Newton in the panel coordinate: dA/dt = dA/dh · dh. A step at
+        // round-off is convergence, not an excursion (it lands ON the
+        // bracket edge just set, which the bracket test would reject).
+        const double dadt = dadh * c.dh;
+        double step = (dadt > 0.0) ? -f / dadt : 0.0;
+        if (dadt > 0.0 && std::fabs(step) <= tol) break;
+        double tn = t + step;
+        if (!(dadt > 0.0) || !(tn > lo && tn < hi)) tn = 0.5 * (lo + hi);
+        step = tn - t;
+        t = tn;
+        if (std::fabs(step) <= tol) break;
+    }
+    return static_cast(i) * c.dh + t * c.dh;
+}
+
+} // namespace kernels
+} // namespace openswmm::fv
+
+#endif // OPENSWMM_ENGINE_FV_CLOSURE_KERNELS_HPP
diff --git a/src/engine/hydraulics/fv/FvKernels.hpp b/src/engine/hydraulics/fv/FvKernels.hpp
index 38d5e6d16..c6aac0c7f 100644
--- a/src/engine/hydraulics/fv/FvKernels.hpp
+++ b/src/engine/hydraulics/fv/FvKernels.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FvKernels.hpp
  * @brief Single-source scalar kernels for the explicit FV 1D network solver.
@@ -38,7 +54,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_KERNELS_HPP
@@ -77,41 +93,6 @@ inline constexpr double kDryArea = 1.0e-12;
 /// 1e-12 ft is far below any physical head.
 inline constexpr double kEtaDeadband = 1.0e-12;
 
-// ===========================================================================
-// Section evaluation — the ONE place the cross-section machinery is called
-// ===========================================================================
-//
-// These three go through the geometry's own evaluator (XSectKernels.hpp) — the
-// SAME bodies XSection.cpp's public accessors and XSectBatch's kernels run.
-// Only where the evaluator's tables live differs between the host solver and
-// the device backend, so the §6.8 parity harness compares two instantiations of
-// one implementation rather than two implementations.
-
-/// Section area at depth h, EXCLUDING the slot (h clamped to the crown).
-/// Scaled by the barrel count: a cell is the aggregate of the parallel barrels
-/// at a shared depth (see FvGeometry::barrel_scale).
-OPENSWMM_KERNEL_FN double sectionArea(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    return g.barrel_scale * g.eval->getAofY(g.xs, (h < g.y_full) ? h : g.y_full);
-}
-
-/// Section top width at depth h, EXCLUDING the slot. RECT_CLOSED returns 0 at
-/// exactly y_full (the crown is a point); the slot term added by widthOfDepth
-/// is what keeps the total width — and hence the celerity — finite there.
-OPENSWMM_KERNEL_FN double sectionWidth(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    return g.barrel_scale * g.eval->getWofY(g.xs, (h < g.y_full) ? h : g.y_full);
-}
-
-/// Section hydraulic radius at depth h. Frozen at r_full above the crown —
-/// the slot is a numerical device and must not contribute wetted perimeter
-/// (same convention as legacy dwflow.c::getHydRad).
-OPENSWMM_KERNEL_FN double sectionHydRad(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    if (h >= g.y_full) return g.r_full;
-    return g.eval->getRofY(g.xs, h);
-}
-
 // ===========================================================================
 // Preissmann slot taper (plan §3.3.2)
 // ===========================================================================
@@ -137,66 +118,44 @@ OPENSWMM_KERNEL_FN double slotRampIntegral(double s) noexcept {
 // ===========================================================================
 // Closure — one continuous geometry from dry bed to full pressurization
 // ===========================================================================
+//
+// This is the memoryless SLOT closure — every cell, every state, no history.
+// TPA exception (issue #156): under FV_PRESSURE_CLOSURE TPA a cell whose
+// regime flag is set evaluates the tpa* kernels at the end of this file
+// instead. The flag is physical air-pathway history (cleared on cold start
+// and hotstart restore), not numerical relaxation; unflagged cells — and the
+// entire SLOT closure path — are untouched.
 
 /// Flow area at depth @p h, INCLUDING the tapered slot. Monotone in h for any
-/// section, which is what makes the depth inversion well posed.
+/// section, which is what makes the depth inversion well posed. Every closure
+/// function here evaluates the geometry's FvClosure (FvClosureKernels.hpp):
+/// the exact section sampled at build time into a monotone cubic on which the
+/// top width IS dA/dh and the first moment IS ∫A, with the slot folded in.
 OPENSWMM_KERNEL_FN double areaOfDepth(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    if (h >= g.y_full) return g.a_crown + g.t_slot * (h - g.y_full);
-    const double band = g.y_full - g.y_crown;
-    const double ax = sectionArea(g, h);
-    if (band <= 0.0) return ax;                 // open section: no taper band
-    const double s = (h - g.y_crown) / band;
-    return ax + g.t_slot * band * slotRampIntegral(s);
+    return closureArea(g.closure_tbl, h);
 }
 
 /// Top width dA/dh at depth @p h, INCLUDING the tapered slot.
 OPENSWMM_KERNEL_FN double widthOfDepth(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    if (h >= g.y_full) return g.t_slot;
-    const double band = g.y_full - g.y_crown;
-    const double wx = sectionWidth(g, h);
-    if (band <= 0.0) return wx;
-    const double s = (h - g.y_crown) / band;
-    return wx + g.t_slot * slotRamp(s);
+    return closureWidth(g.closure_tbl, h);
 }
 
 /// Hydraulic radius at depth @p h.
 OPENSWMM_KERNEL_FN double hydRadOfDepth(const FvGeometry& g, double h) noexcept {
-    if (h <= 0.0) return 0.0;
-    if (h >= g.y_full) return g.r_full;
-    return sectionHydRad(g, h);
+    return closureHydRad(g.closure_tbl, h);
 }
 
 /**
- * @brief Hydrostatic first moment I₁(h) = ∫₀ʰ A(η)dη.
- *
- * Below the crown this reads the per-geometry table built at init (uniform on
- * [0, y_full]) and refines with one trapezoid step using the exact A(h) the
- * caller needs anyway — second-order accurate and, crucially, a single-valued
- * function of h, which is all the well-balanced property requires.
- *
- * Above the crown A is exactly linear (A = a_crown + t_slot·(h − y_full)), so
- * the extension is analytic — deep surcharge stays exact with a small table.
+ * @brief Hydrostatic first moment I₁(h) = ∫₀ʰ A(η)dη — the closure's own
+ *        integral of its own A, so it is single-valued in h by construction
+ *        (all the well-balanced property requires). Above the crown A is
+ *        exactly linear and the extension is analytic. @p area_at_h is kept
+ *        for the call sites that already hold it; the closure does not need it.
  */
 OPENSWMM_KERNEL_FN double i1OfDepth(const FvGeometry& g, double h,
                                     double area_at_h) noexcept {
-    if (h <= 0.0) return 0.0;
-    if (h >= g.y_full) {
-        const double d = h - g.y_full;
-        return g.i1_crown + g.a_crown * d + 0.5 * g.t_slot * d * d;
-    }
-    const int n = static_cast(kI1Samples);
-    const double dh = g.y_full / static_cast(n - 1);
-    int i = static_cast(h / dh);
-    if (i < 0) i = 0;
-    if (i > n - 2) i = n - 2;
-    const double h_i = static_cast(i) * dh;
-    // i1_tbl stores I₁ at the sample points; the companion area sample is the
-    // second half of the same buffer (see buildI1Table).
-    const double i1_i = g.i1_tbl[static_cast(i)];
-    const double a_i  = g.i1_tbl[static_cast(n + i)];
-    return i1_i + 0.5 * (a_i + area_at_h) * (h - h_i);
+    (void)area_at_h;
+    return closureI1(g.closure_tbl, h);
 }
 
 /**
@@ -210,154 +169,15 @@ OPENSWMM_KERNEL_FN double i1OfDepth(const FvGeometry& g, double h,
  *          whole well-balanced construction exists to deliver — would fail on
  *          every partly-full pipe.
  *
- *          `xsect::getYofA` cannot be used for this. The legacy geometry tables
- *          are INDEPENDENT tabulations of the same shape — `A_Circ` gives area
- *          from depth, `Y_Circ` gives depth from area — and they round-trip only
- *          to table resolution (measured: 0.016 ft on a 3 ft circular pipe near
- *          the crown, ~0.5 % of the diameter). That is fine for the legacy
- *          solver, which never composes them; it is fatal here.
- *
- *          So the inverse is built from the forward closure itself: bracket on
- *          the A samples stored alongside the I₁ table (both were produced by
- *          areaOfDepth, so the bracket is exact), then Illinois-regula-falsi
- *          inside the panel. A is strictly increasing — a monotone section plus
- *          a strictly increasing slot term — so the bracket always holds and
- *          convergence is unconditional; within one panel A is nearly linear, so
- *          it typically takes four or five evaluations.
- *
- *          Above the crown A is exactly linear, so that branch is closed-form.
- */
-OPENSWMM_KERNEL_FN double depthOfAreaBracketed(const FvGeometry& g,
-                                               double a) noexcept {
-    if (a <= 0.0) return 0.0;
-    if (a >= g.a_crown) return g.y_full + (a - g.a_crown) / g.t_slot;
-
-    const int n = static_cast(kI1Samples);
-    const double dh = g.y_full / static_cast(n - 1);
-
-    int lo = 0, hi = n - 1;
-    while (hi - lo > 1) {
-        const int mid = (lo + hi) / 2;
-        if (g.i1_tbl[static_cast(n + mid)] <= a) lo = mid;
-        else                                                  hi = mid;
-    }
-
-    double xa = static_cast(lo) * dh;
-    double xb = static_cast(hi) * dh;
-    double fa = g.i1_tbl[static_cast(n + lo)] - a;
-    double fb = g.i1_tbl[static_cast(n + hi)] - a;
-    if (fa >= 0.0) return xa;
-    if (fb <= 0.0) return xb;
-
-    for (int it = 0; it < 40; ++it) {
-        double x = xb - fb * (xb - xa) / (fb - fa);
-        if (!(x > xa && x < xb)) x = 0.5 * (xa + xb);
-        const double f = areaOfDepth(g, x) - a;
-        if (f == 0.0) return x;
-        if (f < 0.0) { xa = x; fa = f; fb *= 0.5; }   // Illinois down-weighting
-        else         { xb = x; fb = f; fa *= 0.5; }
-        if (xb - xa <= 1.0e-15 * g.y_full) break;
-    }
-    return 0.5 * (xa + xb);
-}
-
-/**
- * @brief Invert A → h. Same root as depthOfAreaBracketed, found far faster.
- *
- * @details This is the solver's hottest kernel by a wide margin — profiling a
- *          Δx = 20 ft run put it and the closure evaluations it drives at 87 %
- *          of total time — so how it converges matters more than anywhere else
- *          in the scheme.
- *
- *          **Why the obvious approach is slow.** Illinois regula-falsi on the
- *          depth-uniform bracket does not converge superlinearly here: measured
- *          16 closure evaluations per call on a circular pipe and 35 on a
- *          trapezoid, with the iteration count falling only linearly as the
- *          tolerance is relaxed — the signature of bisection. Seeding it better
- *          changes nothing, because the exit test is the BRACKET collapsing and
- *          Illinois replaces only one end per step.
- *
- *          **Why not Newton.** The width is dA/dh analytically, and Newton with
- *          it needs 3–5 evaluations. But for tabulated shapes W and A are
- *          INDEPENDENT legacy tabulations rather than an exact derivative pair
- *          (§7A.2), and the error that introduces is not small: measured
- *          round-trip error 4.7e-4 ft on a 3 ft circular pipe, five orders
- *          worse than the scheme needs and enough to break lake-at-rest.
- *
- *          **Brent.** Inverse quadratic interpolation with a secant fallback
- *          and a bisection safeguard — superlinear using function values ONLY,
- *          so the width inconsistency cannot mislead it. 5.9 / 3.1 / 6.3
- *          evaluations on circular / rectangular / trapezoidal at full
- *          round-trip accuracy (≤ 2.7e-15 ft).
- *
- *          The bracket comes from the area-uniform inverse table widened by one
- *          panel each side and is then VERIFIED by evaluating both ends. The
- *          two evaluations that costs are why a rectangular pipe — which the
- *          old path nailed in 1.5 — now takes 3.1; that trade is worth it, and
- *          the guard falls back to the bracketed inverse if the table's bracket
- *          somehow fails to contain the root.
+ *          The inverse is therefore a bracketed Newton iteration on the same
+ *          panel cubic the forward closure evaluates (closureDepthOfArea):
+ *          the cubic is monotone by construction, its derivative is the
+ *          closure's own top width, and the exit is 1e-15·y_full in depth —
+ *          measured round trip ≤ 1.2e-15·y_full over the whole depth range,
+ *          slot band included. The polynomial class inverts in closed form.
  */
 OPENSWMM_KERNEL_FN double depthOfArea(const FvGeometry& g, double a) noexcept {
-    if (a <= 0.0) return 0.0;
-    if (a >= g.a_crown) return g.y_full + (a - g.a_crown) / g.t_slot;
-
-    const int n = static_cast(kI1Samples);
-    const double da = g.a_crown / static_cast(n - 1);
-    if (!(da > 0.0)) return depthOfAreaBracketed(g, a);
-
-    int j = static_cast(a / da);
-    if (j < 1) j = 1;
-    if (j > n - 3) j = n - 3;
-
-    double xa = g.h_tbl[static_cast(j - 1)];
-    double xb = g.h_tbl[static_cast(j + 2)];
-    if (!(xb > xa)) return depthOfAreaBracketed(g, a);
-
-    double fa = areaOfDepth(g, xa) - a;
-    double fb = areaOfDepth(g, xb) - a;
-    if (fa > 0.0 || fb < 0.0) return depthOfAreaBracketed(g, a);
-    if (fa == 0.0) return xa;
-    if (fb == 0.0) return xb;
-
-    const double tol = 1.0e-15 * g.y_full;
-    double c = xa, fc = fa, d = xb - xa, e = d;
-    for (int it = 0; it < 60; ++it) {
-        if (fb * fc > 0.0) { c = xa; fc = fa; d = xb - xa; e = d; }
-        if (std::fabs(fc) < std::fabs(fb)) {
-            xa = xb; xb = c; c = xa;
-            fa = fb; fb = fc; fc = fa;
-        }
-        const double m = 0.5 * (c - xb);
-        if (std::fabs(m) <= tol || fb == 0.0) return xb;
-
-        if (std::fabs(e) < tol || std::fabs(fa) <= std::fabs(fb)) {
-            d = m; e = m;                                   // bisect
-        } else {
-            const double sfb = fb / fa;
-            double p, q;
-            if (xa == c) {                                  // secant
-                p = 2.0 * m * sfb;
-                q = 1.0 - sfb;
-            } else {                                        // inverse quadratic
-                const double qq = fa / fc;
-                const double r  = fb / fc;
-                p = sfb * (2.0 * m * qq * (qq - r) - (xb - xa) * (r - 1.0));
-                q = (qq - 1.0) * (r - 1.0) * (sfb - 1.0);
-            }
-            if (p > 0.0) q = -q; else p = -p;
-            if (2.0 * p < ((3.0 * m * q - std::fabs(tol * q) < std::fabs(e * q))
-                               ? 3.0 * m * q - std::fabs(tol * q)
-                               : std::fabs(e * q))) {
-                e = d; d = p / q;
-            } else {
-                d = m; e = m;
-            }
-        }
-        xa = xb; fa = fb;
-        xb += (std::fabs(d) > tol) ? d : ((m > 0.0) ? tol : -tol);
-        fb = areaOfDepth(g, xb) - a;
-    }
-    return xb;
+    return closureDepthOfArea(g.closure_tbl, a);
 }
 
 /// Gravity-wave celerity √(g·A/T). Guarded so a vanishing top width (dry, or a
@@ -378,6 +198,11 @@ struct FaceState {
     double u  = 0.0;  ///< velocity (ft/s)
     double c  = 0.0;  ///< celerity (ft/s)
     double i1 = 0.0;  ///< hydrostatic first moment at the reconstructed depth
+    /// 1: the side stands in the Preissmann slot (or is TPA-flagged) and its
+    /// `c` is the acoustic slot celerity; 0: free surface; 2: a vented
+    /// junction's own-head ghost, which never takes part in the slot/free
+    /// bore bound (see waveSpeeds). Set by the solver.
+    uint8_t press = 0;
 };
 
 /// Result of a face flux evaluation.
@@ -399,6 +224,35 @@ OPENSWMM_KERNEL_FN void waveSpeeds(const FaceState& L, const FaceState& R,
     if (wetL && wetR) {
         sl = std::min(L.u - L.c, R.u - R.c);
         sr = std::max(L.u + L.c, R.u + R.c);
+        // Slot/free-surface interface (one side in the slot, the other not).
+        // Davis's symmetric estimate carries the slot's acoustic celerity into
+        // BOTH waves, but no signal enters the free-surface side at the slot
+        // speed: the wave that crosses into it is the filling/emptying bore,
+        // whose speed is the Rankine–Hugoniot jump (ΔQ/ΔA), bounded below by
+        // that side's own u ± c and above by the Davis bound. With the slot
+        // celerity on both waves the HLL diffusion term at a pressurized
+        // entrance is O(c_slot·ΔA) — measured 52 cfs of spurious mass flux and
+        // a −245 ft⁴/s² momentum sink on a 3 ft culvert whose junction then
+        // flooded at 108 of 120 cfs however high its head rose.
+        // A vented junction's ghost (press == 2) is excluded: bounding the
+        // wave into a pressurized cell beside it cut the acoustic exchange at
+        // every lateral junction of a pressurized tunnel (the node solve then
+        // clamped at its rim and booked 63 000 m³ of flooding — Klaver
+        // Example_02, 2026-09-13), and bounding the wave into a free cell
+        // beside it drove a 2× over-conveying limit cycle at an overloaded
+        // entrance. The bound acts at the INTERIOR slot/free faces, which is
+        // where the entrance lock lived.
+        if (L.press != R.press && L.press < 2 && R.press < 2) {
+            if (L.press) {
+                const double da = L.a - R.a;
+                const double w  = (da > 0.0) ? (L.q - R.q) / da : sr;
+                sr = std::max(R.u + R.c, std::min(sr, w));
+            } else {
+                const double da = R.a - L.a;
+                const double w  = (da > 0.0) ? (R.q - L.q) / da : sl;
+                sl = std::min(L.u - L.c, std::max(sl, w));
+            }
+        }
     } else if (wetR) {                      // dry left
         sl = R.u - 2.0 * R.c;
         sr = R.u + R.c;
@@ -418,6 +272,23 @@ OPENSWMM_KERNEL_FN void physicalFlux(const FaceState& S,
     fq = S.q * S.u + kGravity * S.i1;
 }
 
+/// The MASS component of riemannFlux alone — the same wave speeds and the
+/// same HLL expression, so the value is bit-identical to `riemannFlux().mass`;
+/// what it skips is the momentum flux, the contact speed and every store. The
+/// algebraic node solve reads back one scalar per trial head (plan Phase 1c).
+OPENSWMM_KERNEL_FN double riemannMassFlux(const FaceState& L,
+                                          const FaceState& R) noexcept {
+    if (L.a <= kDryArea && R.a <= kDryArea) return 0.0;
+    double sl = 0.0, sr = 0.0;
+    waveSpeeds(L, R, sl, sr);
+    double fal = 0.0, fql = 0.0, far = 0.0, fqr = 0.0;
+    physicalFlux(L, fal, fql);
+    physicalFlux(R, far, fqr);
+    if (sl >= 0.0) return fal;
+    if (sr <= 0.0) return far;
+    return (sr * fal - sl * far + sl * sr * (R.a - L.a)) / (sr - sl);
+}
+
 /**
  * @brief Flux for the conservative St. Venant system, plus the contact speed.
  *
@@ -540,6 +411,73 @@ OPENSWMM_KERNEL_FN double localLossUpdate(double q, double u, double k,
     return q / (1.0 + dt * k * std::fabs(u) / (2.0 * dx));
 }
 
+/**
+ * @brief Unsteady-friction momentum update (issue #156).
+ *
+ * Pinto/Vasconcelos/Soares (2025) source term, split by stiffness:
+ *   S_fu = (k3/g)·(∂V/∂t + c·sgn(V)·|∂V/∂x|)
+ * The local-acceleration half integrates IMPLICITLY (Δt cancels:
+ * ΔQ = −k3·A·(V^{n+1} − Vⁿ) ⇒ Q^{n+1} = (Q* + k3·A·Vⁿ)/(1 + k3)),
+ * so it is unconditionally stable like frictionUpdate. The convective half
+ * enters explicitly through @p grad_term = c·sgn(Vⁿ)·|∂V/∂x|ⁿ, precomputed by
+ * the solver from a consistent old-state snapshot (never from mid-update
+ * neighbors). The combined change is clamped to half the incoming momentum
+ * per substep — the paper reports instability for k3 ≳ 0.02 with no such
+ * guard; the clamp also makes UF exactly inert at rest (q = 0 ⇒ cap = 0,
+ * and u_old = grad = 0 anyway), preserving the well-balanced property.
+ * k3 = 0 returns q bit-unchanged.
+ */
+OPENSWMM_KERNEL_FN double ufUpdate(double q, double a, double u_old,
+                                   double k3, double grad_term,
+                                   double dt) noexcept {
+    if (k3 <= 0.0 || a <= 0.0) return q;
+    // Dead-band (measured, issue #156): the implicit fold acts as added
+    // inertia — it resists velocity DECAY too, so applied to the ~mm/s
+    // numerical ripple of a storage-coupled pool it sustained noise that
+    // steady friction was correctly killing (0.004 → 0.011 cfs on the
+    // at-rest fixture). UF correlations are calibrated for real transients
+    // (paper velocities O(0.1–1 m/s)); below 0.01 ft/s the term is noise
+    // amplification, not physics. Both the old and candidate velocities must
+    // clear the floor, so a genuinely at-rest deck stays bit-identical.
+    constexpr double kUfVelFloor = 0.01;  // ft/s, internal units
+    if (std::fabs(u_old) < kUfVelFloor && std::fabs(q / a) < kUfVelFloor)
+        return q;
+    double qn = (q + k3 * a * u_old) / (1.0 + k3);
+    qn -= dt * k3 * a * grad_term;
+    const double dq  = qn - q;
+    const double cap = 0.5 * std::fabs(q);
+    if (std::fabs(dq) > cap) qn = q + ((dq > 0.0) ? cap : -cap);
+    return qn;
+}
+
+// ---------------------------------------------------------------------------
+// TPA — two-component pressure approach (issue #156 Phase 4)
+// ---------------------------------------------------------------------------
+// Vasconcelos, Wright & Roe (2006). For a cell whose regime FLAG is set
+// (state.cell_tpa — physical air-pathway history, updated once per substep by
+// the solver, NOT evaluated here), the closure is the slot line extended to
+// BOTH signs of ΔA = A − a_crown:
+//     h(A) = y_full + (A − a_crown)/t_slot        (hs = h − y_full, signed)
+//     A(h) = a_crown + t_slot·(h − y_full)
+//     I₁(h) = i1_crown + a_crown·(h − y_full)     (paper Eq. 12b: the slot's
+//                                                  ½·t_slot·d² numerical
+//                                                  storage pressure is dropped)
+//     T = t_slot,  R = r_full,  c = √(g·A/t_slot) ≈ acoustic celerity a.
+// Free-surface (unflagged) cells use the table closure above UNCHANGED,
+// including the crown taper. The pair is continuous at A = a_crown, h = y_full.
+
+OPENSWMM_KERNEL_FN double tpaDepthOfArea(const FvGeometry& g, double a) noexcept {
+    return g.y_full + (a - g.a_crown) / g.t_slot;
+}
+
+OPENSWMM_KERNEL_FN double tpaAreaOfDepth(const FvGeometry& g, double h) noexcept {
+    return g.a_crown + g.t_slot * (h - g.y_full);
+}
+
+OPENSWMM_KERNEL_FN double tpaI1OfDepth(const FvGeometry& g, double h) noexcept {
+    return g.i1_crown + g.a_crown * (h - g.y_full);
+}
+
 /// CFL-limited step for one face: α·Δx/(|u| + c).
 OPENSWMM_KERNEL_FN double faceCflDt(double cfl, double dx, double u,
                                     double c) noexcept {
diff --git a/src/engine/hydraulics/fv/FvOptions.hpp b/src/engine/hydraulics/fv/FvOptions.hpp
index b29adb2d8..f7876bb6e 100644
--- a/src/engine/hydraulics/fv/FvOptions.hpp
+++ b/src/engine/hydraulics/fv/FvOptions.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FvOptions.hpp
  * @brief Option struct for the explicit finite-volume 1D network solver.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_OPTIONS_HPP
@@ -61,56 +77,14 @@ enum class TimeIntegration : int {
     RK2   = 1   ///< SSP-RK2 (Heun) — strong-stability-preserving
 };
 
-/// How a node's continuity equation is coupled to the faces that feed it.
-enum class NodeCoupling : int {
-    EXPLICIT      = 0,  ///< face fluxes frozen across the node update
-    SEMI_IMPLICIT = 1   ///< default: fluxes linearized in the node head
-};
-
-/// What a node contributes to the LTS base timestep.
-///
-/// `dt0` is the minimum over every cell AND every node, and the node's term is
-/// `A_s / (sum T*c)` — the correct EXPLICIT stability bound for a control
-/// volume of surface area A_s. But the node is not updated explicitly: the
-/// semi-implicit correction carries the step in its denominator,
-/// `dh = dt*R / (A_s + dt*resist)`, which is unconditionally stable. So the
-/// term is not buying STABILITY, whatever its form says; and a manhole's plan
-/// area is one to two orders of magnitude below a conduit cell's, so it sets
-/// `dt0` for the whole network.
-///
-/// It is, however, buying ACCURACY, and far more of it than the shape of the
-/// expression suggests. Scored against the SWASHES analytic solutions, L1 depth
-/// error, STABILITY vs NONE with three node sweeps:
-///
-///     bump-subcritical      0.1045  ->  1.132     10.8x worse
-///     bump-transcritical    0.2979  ->  0.9067     3.0x worse
-///     bump-shock            0.0596  ->  2.897     48.6x worse
-///     thacker-planar-1d     0.7559  ->  0.8636     1.1x worse
-///     macdonald-long-sub         -  -> 10.23      unusable
-///     macdonald-long-sup         -  -> 51.84      unusable
-///     ritter / stoker / lake-at-rest    unchanged (PASS either way)
-///
-/// NONE is 24-134x faster (bump-transcritical 120 s -> 5 s, bump-subcritical
-/// 134 s -> 1 s, both continuity-clean) and wrong wherever the node coupling
-/// carries the solution: steady frictional channels and anything transcritical.
-/// Three Picard sweeps do not stand in for the term at large dt — the sweeps
-/// converge the node's own continuity equation at the step it is handed, which
-/// is a different thing from that step being small enough to resolve the
-/// coupling. Only the cases the nodes barely participate in (dam breaks on a
-/// flat bed, a lake at rest) are indifferent.
-///
-/// So this is not a performance lever to reach for; it is the instrument that
-/// showed the node term is load-bearing, which is why STABILITY is the default
-/// and why the way out has to bound the node's step by what accuracy needs
-/// rather than by deleting the bound.
-///
-/// (An earlier note here claimed NONE scored 0.00159 on bump-subcritical, 66x
-/// BETTER. That does not reproduce: STABILITY's half of it, 0.1045, reproduces
-/// exactly, and NONE's is 1.132. Recorded so the number is not trusted again.)
-enum class NodeDtLimit : int {
-    STABILITY = 0,  ///< default: the explicit A_s/(sum T*c) bound (today)
-    NONE      = 1   ///< nodes do not constrain dt0; accuracy rests on sweeps
-};
+// FV_NODE_COUPLING, FV_NODE_DT and FV_NODE_PICARD were retired 2026-08-29
+// (parsed and warned when they ask for the behaviour that no longer exists):
+// storage-node coupling is always semi-implicit, the node accuracy bound is
+// always armed, and the correction is always a single sweep -- each the
+// former default. The SWASHES table that justified FV_NODE_DT was measured
+// under the BUCKET junction model described below, three days before that
+// model was deleted, and never re-measured
+// (plans/FV1D_PERF_PLAN_REVIEW_2026-08-20.md §3.1).
 
 // Junctions are always ALGEBRAIC interfaces, not states (matching legacy
 // DYNWAVE, where a junction's own surface area is exactly zero and all
@@ -175,6 +149,26 @@ struct FvOptions {
     /// flows or in-conduit profiles matter.
     int min_cells = 4;
 
+    // -- Pressure closure (issue #156 Phase 4) -------------------------------
+    /// [OPTIONS] FV_PRESSURE_CLOSURE SLOT|TPA. 0 = SLOT (default,
+    /// parity-preserving), 1 = TPA (Vasconcelos/Wright/Roe 2006): a per-cell
+    /// regime flag extends the slot line to ΔA < 0 (sub-atmospheric full-pipe
+    /// flow), with venting governed by atmosphere contact. FV_SLOT_CELERITY
+    /// doubles as the TPA acoustic celerity a (same physical dial).
+    /// Plan: plans/TPA_TWO_COMPONENT_PRESSURE_PLAN.md + MIXED_FLOW §2.2.
+    int pressure_closure = 0;
+
+    // -- Unsteady friction (issue #156) --------------------------------------
+    // Mirrors SimulationOptions::unsteady_friction / uf_k3 (shared [OPTIONS]
+    // keys UNSTEADY_FRICTION / UF_K3, not FV_*); copied in Router::initFv so
+    // the solver keeps seeing only FvOptions. Both dimensionless.
+
+    /// 0 = NONE (default, bit-inert), 1 = VITKOVSKY.
+    int unsteady_friction = 0;
+
+    /// Brunone-type k3 coefficient; consumed only when unsteady_friction != 0.
+    double uf_k3 = 0.015;
+
     // -- Scheme -------------------------------------------------------------
 
     double        cfl              = 0.5;
@@ -190,19 +184,25 @@ struct FvOptions {
     /// ft/s is the same order DW's SLOT surcharge method produces.
     double slot_celerity = 100.0;
 
+    /// Integrate the acoustic/slot pair implicitly on the pressurized subset
+    /// (slot program R2a, Strategy E). Above the taper band the closure is
+    /// linear in head, so cells at/above band entry solve an SPD head system
+    /// per substep (Thomas on chains, Jacobi-CG past folded junctions) whose
+    /// back-substituted face discharges overwrite `f_mass_` — a pure flux
+    /// predictor: conservation, rollback and hot start are untouched, and a
+    /// run that never pressurizes is bit-identical with the option on.
+    ///
+    /// With it, pressurized cells are advection-bound in the step census —
+    /// FV_SLOT_CELERITY leaves the dt law entirely, making the slot width a
+    /// pure accuracy parameter (a narrow slot no longer costs runtime).
+    /// Default OFF while the R2 gates land; the R4 default flip is a
+    /// separate, deliberate commit.
+    bool pressurized_implicit = false;
+
     // -- Coupling -----------------------------------------------------------
 
     StructureCoupling structure_coupling = StructureCoupling::SUBSTEP;
 
-    /// A junction's storage area is the MIN_SURFAREA floor, which as an
-    /// effective length A_s/T is a few feet against a conduit Δx of several
-    /// hundred — so under explicit coupling the MANHOLE, not the pipe, sets the
-    /// substep for the whole model. Linearizing each coupling face's flux in
-    /// the node head removes the node from the explicit stability limit.
-    /// Conservation is unaffected: the corrected flux is what BOTH the node and
-    /// the cell see.
-    NodeCoupling node_coupling = NodeCoupling::SEMI_IMPLICIT;
-
     // -- Execution ----------------------------------------------------------
 
     Backend backend = Backend::AUTO;
@@ -225,39 +225,73 @@ struct FvOptions {
     /// path bit-for-bit, so this is on by default (plan §3.3).
     bool lts = true;
 
+    /// Bound the explicit step by the ALGEBRAIC JUNCTION feedback limit.
+    /// Opt-in: correct but costly (see the wall-time note below).
+    ///
+    /// An algebraic junction has no volume state, so it carries no storage
+    /// bound and was exempted from the step census on both paths. But its head
+    /// is solved from the instantaneous flux balance and then handed to the
+    /// incident cells as a ghost, so the neighbours integrate against a
+    /// boundary state that can travel a long way inside one step. That feedback
+    /// is explicit and has its own limit (algebraicNodeStableDt):
+    ///
+    ///     tau = min_i(0.5*dx_i*T_i) / sum_j(T_j*c_j)
+    ///
+    /// `min` in the numerator, not `sum`: every incident conduit pushes flux
+    /// (the sum), but the solved head must resolve on the TIGHTEST incident
+    /// storage. Summing -- what legacy DW does for its own node continuity --
+    /// makes the bound LOOSER at exactly the junctions that need it (a 12 ft
+    /// barrel meeting a 3 ft one gives a 2123 ft effective length against a
+    /// 250 ft cell). Gated on the junction being pressurized, so open-channel
+    /// networks pay nothing.
+    ///
+    /// Relative to the cell bound this is 1/(2n) * (T_min/T_max) -- purely
+    /// geometric: 4x for two equal barrels, 32x across a 16:1 area step. Those
+    /// are the factors the EPA QA decks were measured to need, and they are
+    /// CELERITY-INVARIANT (T ~ 1/c^2 cancels), which is why lowering
+    /// FV_SLOT_CELERITY suppresses the symptom without fixing the bound.
+    ///
+    /// The constraint is applied to the junction's INCIDENT CELLS in
+    /// assignTiers, not to dt_node: a plain junction integrates no state and is
+    /// pinned to its finest incident cell, so routing it through dt_node
+    /// discards the tier while still dragging dt0 down. On the cells it is an
+    /// ordinary local CFL number and tiering localises it normally.
+    ///
+    /// Measured at stock FV_CFL 0.5 with LTS on (zigzag = total variation /
+    /// range of the worst link, against dynamic wave):
+    ///   test5  37.95 -> 4.97  (DW 5.08), peak Q 1.06x -> 1.01x,  8.5 s ->  121 s
+    ///   test2  52.01 -> 2.99  (DW 6.87), peak Q 11.9x -> 0.99x,  1.0 s -> 9.7 s
+    /// It also closes an accuracy hole unrelated to oscillation: on the culvert
+    /// fixture the un-tiered path floods 0.885 acre-ft against DW's 0.003, and
+    /// 0.001 with this on.
+    ///
+    /// Default OFF because of that 10-14x wall cost on pressurized networks.
+    /// The cost is the bound doing its job -- a stiff junction genuinely needs
+    /// a small step -- but it is the user's call whether to pay it. It does NOT
+    /// disable tiering (an earlier revision did): LTS still localises the cost,
+    /// and turning LTS off instead costs 376 s / 38 s on the same decks.
+    bool node_feedback_dt = false;
+
     /// Maximum LTS tier count (tier k advances at 2^k·dt₀). 6 ⇒ 64× spread.
     int lts_max_tiers = 6;
 
     /// Recompute the global CFL min-reduction every k substeps instead of every
-    /// substep, with a safety margin. 1 = every substep (exact).
-    int cfl_census_interval = 1;
-
-    /// Whether a node's explicit stability estimate enters the LTS base step.
-    NodeDtLimit node_dt_limit = NodeDtLimit::STABILITY;
-
-    /// Picard sweeps on the node head inside the semi-implicit coupling.
+    /// substep. 1 = every substep (exact).
     ///
-    /// 1 (default) is the original behaviour: ONE correction, with the
-    /// characteristic resistance √(g·A·T), the node surface area and the face
-    /// fluxes all frozen at the head the substep started from. That is exact
-    /// for the linearized problem — the residual after one sweep is
-    /// identically zero — so more sweeps only help because the real problem is
-    /// not linear: A, T and the storage area all move with the head, and the
-    /// Riemann flux is not the straight line the correction extrapolates
-    /// along. Freezing them is why the node is stable at a large Δt but not
-    /// ACCURATE at one, which is what forces it into a fine LTS tier and sets
-    /// the substep count (plan §7B.8).
+    /// INERT BEFORE 2026-08-20. The accepted-substep tail wrote the step it had
+    /// just taken into the census cache and forced the countdown to zero, so
+    /// the pre-step census ran every substep for every value of k. The step
+    /// taken and the Courant bound are now separate quantities (`dt_cache_` vs
+    /// `dt_census_`) and the countdown survives; a retry — the post-step census
+    /// proving the bound inadmissible — still resets it. The default of 1 is
+    /// bit-identical across the change.
     ///
-    /// > 1 re-evaluates all three at the provisional head each sweep and
-    /// re-solves the incident faces' Riemann problems, so the node converges
-    /// on its own continuity equation instead of a tangent to it.
-    /// Conservation is untouched either way: every sweep leaves the answer in
-    /// `f_mass_`, the single array both the cell update and the node update
-    /// read.
-    int node_picard_sweeps = 1;
-
-    /// Stop sweeping when the head correction falls below this (ft).
-    double node_picard_tol = 1.0e-6;
+    /// NOT YET SWEPT. k > 1 throttles only the PRE-step census; the post-step
+    /// acceptance census still runs every substep and is the safety net that
+    /// makes skipping the pre-step one defensible at all. The ceiling on this
+    /// option is therefore ~2× on census cost, not k×. Measure before raising
+    /// the default (Phase 1, FV1D_PERF_PLAN_REVISED_2026-08-20.md).
+    int cfl_census_interval = 1;
 
     // -- Transport (plan §3.2 / §6.11) --------------------------------------
 
diff --git a/src/engine/hydraulics/fv/INetworkSolver.hpp b/src/engine/hydraulics/fv/INetworkSolver.hpp
index 2416264a4..6d798e0aa 100644
--- a/src/engine/hydraulics/fv/INetworkSolver.hpp
+++ b/src/engine/hydraulics/fv/INetworkSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file INetworkSolver.hpp
  * @brief Backend-neutral interface for the explicit FV 1D network integrator.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_I_NETWORK_SOLVER_HPP
@@ -35,8 +51,13 @@ struct FvOptions;
 /// and results pulled back after. Kept as a flat struct so the plugin ABI can
 /// pass it across the C boundary unchanged.
 struct FvStepForcing {
-    /// Lateral inflow at each regular node (cfs), as assembled by
-    /// SWMMEngine::assembleLateralInflows. Indexed by node.
+    /// Lateral inflow at each node (cfs), as assembled by
+    /// SWMMEngine::assembleLateralInflows. Indexed by node. May be nonzero at
+    /// a kNodeVirtual node too: the in-tree solver splits it half/half into
+    /// the two cells adjoining the node's spliced face (node_vj_face) as a
+    /// zero-momentum area source, and a device backend must do the same —
+    /// a virtual junction owns no faces, so any node-side integration of the
+    /// value silently drops the water.
     const double* node_lateral = nullptr;
 
     /// Prescribed head at boundary-controlled nodes (ft, absolute elevation);
@@ -46,8 +67,21 @@ struct FvStepForcing {
 
     /// Non-conduit (pump/orifice/weir/outlet) link flows in cfs, signed
     /// positive from node1 to node2. Indexed by link; conduits are ignored.
+    ///
+    /// DUMMY-xsect conduits are the exception: they are structure links
+    /// (mesh.struct_is_dummy) but their discharge is not a head relation the
+    /// engine can evaluate outside the solver — it is whatever arrives at the
+    /// upstream node. The solver derives it from its own fluxes and ignores
+    /// this array for them; `link_q_cap` carries the only thing it cannot know.
     const double* structure_flow = nullptr;
 
+    /// Upper bound on the pass-through discharge of each DUMMY link (cfs),
+    /// indexed by link: the FLOW_LIMIT from [CONDUITS], or 0 when a control
+    /// rule has closed the link. Negative means unlimited. Only DUMMY entries
+    /// are read. Legacy applies both gates in the same order — setting first,
+    /// then the limit (computeNonConduitFlowOne, HydStructures.cpp:1196-1212).
+    const double* link_q_cap = nullptr;
+
     /// Distributed conduit loss rate per unit length (ft²/s, positive = loss)
     /// from evaporation and seepage. Indexed by conduit row.
     const double* conduit_loss = nullptr;
@@ -131,11 +165,46 @@ class INetworkSolver {
 
         long   tier_cells[8] = {0}; ///< cumulative rebuild-sampled cells per LTS tier
         int    n_tiers       = 0;   ///< populated tier count (≤ 8)
+
+        // dt-argmin attribution (slot program R0): which regime owned the
+        // binding CFL element, counted once per census (global path) or
+        // re-tier (LTS path). Answers "who sets the step" without a trace.
+        long   dt_argmin_pressurized = 0;  ///< h ≥ y_full (slot celerity)
+        long   dt_argmin_band        = 0;  ///< y_crown ≤ h < y_full (mouth)
+        long   dt_argmin_free        = 0;  ///< open-channel cell
+        long   dt_argmin_node        = 0;  ///< node storage / feedback bound
+
+        // LTS macro cycles that ran vs were rejected. The tier histogram
+        // above is filled by assignTiers whether or not a cycle ever fires,
+        // so these are what say tiering ENGAGED rather than was assigned.
+        long   n_macro_cycles   = 0;
+        long   n_macro_rejected = 0;
     };
 
     /// Read cumulative statistics. Default: zeros (backend has no counters).
     virtual RunStats run_stats() const noexcept { return {}; }
 
+    /// Worst offender of a diverged advance() (issue #156 R3). The substep
+    /// retry loop shrinks dt away from CFL violations, but a dt-INDEPENDENT
+    /// amplification fails all retries identically and the loop then accepts
+    /// the diverged step — after which nothing downstream said a word: the
+    /// published heads stay under the engine's absurd-value bound for a long
+    /// time while the physics is garbage (P6 finding F3: 30 of 118 study
+    /// series beyond 10x the observed range, every run status OK).
+    struct Divergence {
+        int         link  = -1;       ///< engine link index of the offender
+        double      value = 0.0;      ///< offending magnitude (internal units)
+        const char* what  = nullptr;  ///< "velocity (ft/s)" | "depth (ft)"
+    };
+
+    /// True when the last advance() left a cell beyond physical bounds (or
+    /// non-finite), with @p d describing the worst offender. Default: never
+    /// reports, for a backend without the check.
+    virtual bool divergence(Divergence& d) const noexcept {
+        (void)d;
+        return false;
+    }
+
     /// True once initialize() has completed and the solver is ready.
     virtual bool is_initialized() const noexcept = 0;
 };
diff --git a/src/engine/hydraulics/fv/NetworkMeshBuilder.cpp b/src/engine/hydraulics/fv/NetworkMeshBuilder.cpp
index 9d3dc584e..72787aa5f 100644
--- a/src/engine/hydraulics/fv/NetworkMeshBuilder.cpp
+++ b/src/engine/hydraulics/fv/NetworkMeshBuilder.cpp
@@ -10,8 +10,13 @@
 
 #include 
 #include 
+#include 
+#include 
+#include 
 
 #include "FvKernels.hpp"
+#include "SectionGeometry.hpp"
+#include "../../core/ErrorCodes.hpp"
 #include "../Culvert.hpp"
 #include "../Link.hpp"
 #include "../Node.hpp"
@@ -29,53 +34,134 @@ struct Attachment {
     int end     = 0;    ///< 0 = conduit's upstream (node1) end, 1 = downstream
 };
 
-/// Composite integration of A(h) over [0, y_full] onto the kI1Samples grid.
-/// Each table interval is integrated with kSub Simpson panels of the exact
-/// closure, so the tabulated I₁ is far more accurate than a trapezoid over the
-/// coarse grid would be — it is the pressure term of every momentum flux.
-void buildI1Table(FvGeometry& g) {
-    constexpr int kSub = 8;                      // Simpson panels per interval
-    const int n = kI1Samples;
-    for (int q = 0; q < 2 * n; ++q) g.i1_tbl[q] = 0.0;
-    if (g.y_full <= 0.0) return;
-
-    const double dh = g.y_full / static_cast(n - 1);
-    const double hs = dh / static_cast(2 * kSub);   // Simpson half-panel
-
-    double acc = 0.0;
-    g.i1_tbl[0] = 0.0;
-    g.i1_tbl[static_cast(n)] = 0.0;            // A(0) = 0
-    for (int i = 1; i < n; ++i) {
-        const double h0 = static_cast(i - 1) * dh;
-        // Composite Simpson over [h0, h0 + dh].
-        double s = kernels::areaOfDepth(g, h0) +
-                   kernels::areaOfDepth(g, h0 + dh);
-        for (int k = 1; k < 2 * kSub; ++k) {
-            const double hk = h0 + static_cast(k) * hs;
-            s += ((k & 1) ? 4.0 : 2.0) * kernels::areaOfDepth(g, hk);
+/**
+ * @brief Build the exact-geometry closure table for one section.
+ *
+ * Samples SectionGeometry (closed forms where they exist, the legacy
+ * evaluator where the table is the definition) at kClosurePanels+1 uniform
+ * depths with the tapered slot folded in, takes the exact top width as the
+ * Hermite slope, limits the slopes for monotonicity (Fritsch–Carlson), and
+ * integrates the panel cubics for I₁. Open polynomial sections get the
+ * closed-form class instead. Areas and widths are per cell (barrels folded
+ * in); R is per barrel. a_crown / i1_crown are then the closure's own values.
+ */
+void buildClosure(FvGeometry& g) {
+    FvClosure& c = g.closure_tbl;
+    c = FvClosure{};
+    const int N = kClosurePanels;
+    if (!(g.y_full > 0.0)) return;
+
+    c.y_full = g.y_full;
+    c.dh     = g.y_full / static_cast(N);
+    c.inv_dh = static_cast(N) / g.y_full;
+    c.t_slot = g.t_slot;
+    c.r_full = g.r_full;
+    const double bs   = g.barrel_scale;
+    const double band = g.y_full - g.y_crown;
+    const XSectParams& xs = g.xs;
+
+    if (g.is_open && secgeom::isPolynomialOpen(xs.type)) {
+        c.kind = kClosurePolynomial;
+        switch (static_cast(xs.type)) {
+            case XSectShape::RECT_OPEN:
+                c.c2 = 0.0;            c.c1 = bs * xs.w_max;
+                c.p0 = bs * xs.w_max;  c.p1 = bs * (2.0 - xs.s_bot);
+                break;
+            case XSectShape::TRAPEZOIDAL:
+                c.c2 = bs * xs.s_bot;  c.c1 = bs * xs.y_bot;
+                c.p0 = bs * xs.y_bot;  c.p1 = bs * xs.r_bot;
+                break;
+            default:  // TRIANGULAR
+                c.c2 = bs * xs.s_bot;  c.c1 = 0.0;
+                c.p0 = 0.0;            c.p1 = bs * 2.0 * xs.r_bot;
+                break;
+        }
+        c.a_crown  = (c.c2 * g.y_full + c.c1) * g.y_full;
+        c.i1_crown = (c.c2 * g.y_full / 3.0 + 0.5 * c.c1) * g.y_full * g.y_full;
+        c.inv_a_crown_n = (c.a_crown > 0.0) ? static_cast(N) / c.a_crown : 0.0;
+    } else {
+        c.kind = kClosureTabulated;
+        for (int i = 0; i <= N; ++i) {
+            const double h = g.y_full * static_cast(i) / static_cast(N);
+            double a = bs * secgeom::areaOfDepth(xs, h);
+            double w = bs * secgeom::widthOfDepth(xs, h);
+            const double r = secgeom::hydRadOfDepth(xs, h);
+            if (band > 0.0 && h > g.y_crown) {
+                const double s = (h - g.y_crown) / band;
+                a += g.t_slot * band * kernels::slotRampIntegral(s);
+                w += g.t_slot * kernels::slotRamp(s);
+            }
+            c.A[i] = a;
+            c.M[i] = (w > 0.0) ? w : 0.0;
+            c.R[i] = (r > 0.0) ? r : 0.0;
+        }
+        c.A[0] = 0.0;
+        c.R[N] = g.r_full;
+
+        // Node slopes. For a closed-form section the exact top width IS dA/dh
+        // and is used directly. For a table-defined section the legacy W table
+        // is an INDEPENDENT tabulation that is not the derivative of the
+        // legacy A table (the very inconsistency this closure exists to
+        // remove), so the slopes come from the A samples themselves: the
+        // PCHIP three-point formula (harmonic mean of the adjacent secants),
+        // which is monotone by construction and keeps T consistent with A.
+        if (!secgeom::hasClosedForm(xs.type)) {
+            double d[kClosurePanels];
+            for (int i = 0; i < N; ++i) d[i] = (c.A[i + 1] - c.A[i]) * c.inv_dh;
+            c.M[0] = d[0];
+            c.M[N] = d[N - 1];
+            for (int i = 1; i < N; ++i) {
+                if (d[i - 1] > 0.0 && d[i] > 0.0)
+                    c.M[i] = 2.0 / (1.0 / d[i - 1] + 1.0 / d[i]);
+                else
+                    c.M[i] = 0.0;
+            }
+            // Keep the slot's own slope at the crown node: above it the
+            // closure is the slot line, and continuity of T there is what the
+            // taper band is for.
+            if (band > 0.0) c.M[N] = std::max(c.M[N], g.t_slot);
+        }
+
+        // Fritsch–Carlson: with the exact width as node slope the limiter
+        // almost never engages, but it is what makes monotonicity a property
+        // of the table rather than of the shape.
+        for (int i = 0; i < N; ++i) {
+            const double delta = (c.A[i + 1] - c.A[i]) * c.inv_dh;
+            if (!(delta > 0.0)) { c.M[i] = 0.0; c.M[i + 1] = 0.0; continue; }
+            double alpha = c.M[i] / delta, beta = c.M[i + 1] / delta;
+            if (alpha < 0.0) { alpha = 0.0; c.M[i] = 0.0; }
+            if (beta  < 0.0) { beta  = 0.0; c.M[i + 1] = 0.0; }
+            const double s2 = alpha * alpha + beta * beta;
+            if (s2 > 9.0) {
+                const double tau = 3.0 / std::sqrt(s2);
+                c.M[i]     = tau * alpha * delta;
+                c.M[i + 1] = tau * beta  * delta;
+            }
+        }
+
+        // I₁ = running integral of the panel cubics (Hermite quadrature).
+        c.I1[0] = 0.0;
+        for (int i = 0; i < N; ++i)
+            c.I1[i + 1] = c.I1[i] + c.dh * (0.5 * (c.A[i] + c.A[i + 1]) +
+                                            c.dh / 12.0 * (c.M[i] - c.M[i + 1]));
+        c.a_crown  = c.A[N];
+        c.i1_crown = c.I1[N];
+        c.inv_a_crown_n = (c.a_crown > 0.0) ? static_cast(N) / c.a_crown : 0.0;
+
+        // Area-uniform panel index for the inverse.
+        for (int k = 0; k <= N; ++k) {
+            const double ak = c.a_crown * static_cast(k) / static_cast(N);
+            int lo = 0, hi = N;
+            while (hi - lo > 1) {
+                const int mid = (lo + hi) / 2;
+                if (c.A[mid] <= ak) lo = mid; else hi = mid;
+            }
+            c.j_of_a[k] = static_cast((lo > N - 1) ? N - 1 : lo);
         }
-        acc += s * hs / 3.0;
-        const double h_i = static_cast(i) * dh;
-        g.i1_tbl[static_cast(i)] = acc;
-        g.i1_tbl[static_cast(n + i)] = kernels::areaOfDepth(g, h_i);
     }
-    g.i1_crown = acc;
-}
 
-/// The area-uniform inverse table, built from the bracketed inverse so the
-/// fast path and the slow one converge to the same root by construction. Must
-/// run AFTER buildI1Table and after a_crown is set — it inverts what they
-/// produced.
-void buildDepthTable(FvGeometry& g) {
-    const int n = kI1Samples;
-    for (int j = 0; j < n; ++j) g.h_tbl[j] = 0.0;
-    if (!(g.a_crown > 0.0) || g.y_full <= 0.0) return;
-
-    const double da = g.a_crown / static_cast(n - 1);
-    g.h_tbl[0] = 0.0;
-    for (int j = 1; j < n - 1; ++j)
-        g.h_tbl[j] = kernels::depthOfAreaBracketed(g, static_cast(j) * da);
-    g.h_tbl[n - 1] = g.y_full;              // A(y_full) == a_crown by definition
+    g.a_crown  = c.a_crown;
+    g.i1_crown = c.i1_crown;
 }
 
 } // namespace
@@ -89,10 +175,6 @@ void buildGeometry(const XSectParams& xs, bool is_open, double slot_celerity,
     g.xs      = xs;
     g.barrels = std::max(1, barrels);
     g.barrel_scale = static_cast(g.barrels);
-    // Host binding by default. A device backend rebinds this to its own
-    // evaluator over device copies of the same tables (plan §5.1); nothing else
-    // about the geometry changes.
-    g.eval    = &xsect::hostEval();
     // Area and width are aggregate over the barrels; depth and hydraulic radius
     // are per barrel and unscaled.
     g.y_full  = xs.y_full;
@@ -125,8 +207,7 @@ void buildGeometry(const XSectParams& xs, bool is_open, double slot_celerity,
     const double band = g.y_full - g.y_crown;
     g.a_crown = g.a_full + g.t_slot * band * 0.5;   // ∫₀¹ ramp = ½
 
-    buildI1Table(g);
-    buildDepthTable(g);
+    buildClosure(g);
 }
 
 // ===========================================================================
@@ -153,6 +234,7 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
     mesh.node_sur_depth.resize(static_cast(n_nodes));
     mesh.node_can_pond.resize(static_cast(n_nodes));
     mesh.node_kind.resize(static_cast(n_nodes));
+    mesh.node_vj_face.assign(static_cast(n_nodes), -1);
     mesh.node_area.assign(static_cast(n_nodes),
                           constants::MIN_SURFAREA);
     for (int i = 0; i < n_nodes; ++i) {
@@ -220,24 +302,87 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
     // -----------------------------------------------------------------------
     // Per-conduit geometry + cell allocation
     // -----------------------------------------------------------------------
-    mesh.geom.resize(static_cast(n_cond));
+    // One section block per DISTINCT (section, barrels, open) — plan Phase 1f.
+    mesh.geom.clear();
+    {
+        const auto un_cond = static_cast(n_cond);
+        mesh.conduit_section.assign(un_cond, -1);
+        mesh.conduit_roughness.assign(un_cond, 0.01);
+        mesh.conduit_rough_factor.assign(un_cond, 0.0);
+        mesh.conduit_loss_inlet.assign(un_cond, 0.0);
+        mesh.conduit_loss_outlet.assign(un_cond, 0.0);
+        mesh.conduit_slope.assign(un_cond, 0.0);
+        mesh.conduit_culvert_code.assign(un_cond, 0);
+        mesh.conduit_culvert_curve.assign(un_cond, hydkernels::CulvertCurve{});
+        mesh.conduit_culvert_mitered.assign(un_cond, 0);
+    }
     mesh.conduit_cell_begin.assign(static_cast(n_cond), -1);
     mesh.conduit_cell_count.assign(static_cast(n_cond), 0);
     mesh.conduit_link.assign(static_cast(n_cond), -1);
 
     rep.min_dx = 1.0e30;
 
+    // Tabulation memo. buildGeometry() runs ~2,200 areaOfDepth evaluations plus
+    // 127 bracketed root solves per call, and its result depends only on
+    // (cross-section, open/closed, slot celerity, barrels) — slot celerity
+    // being constant across this loop. Real models have tens of distinct
+    // sections and can have hundreds of thousands of conduits, so without a
+    // memo this dominates initialize().
+    //
+    // The key is an explicit tuple of every XSectParams field rather than the
+    // struct's bytes: the struct has padding, whose contents are unspecified,
+    // so memcmp would report spurious mismatches. The three table pointers are
+    // part of the key — same pointer means the same transect table, and two
+    // identical tables at different addresses merely miss the memo, which is
+    // safe. (After the STREET/CUSTOM memoization in the resolver, links sharing
+    // a street already share one table address, so they hit.)
+    using GeomKey = std::tuple;
+    const auto geom_key = [](const XSectParams& x, int barrels, bool is_open) {
+        return GeomKey{x.type, x.culvert_code, x.transect,
+                       x.y_full, x.w_max, x.yw_max, x.a_full, x.r_full,
+                       x.s_full, x.s_max, x.y_bot, x.a_bot, x.s_bot, x.r_bot,
+                       x.area_tbl, x.hrad_tbl, x.width_tbl,
+                       x.transect_tbl_size, barrels, is_open};
+    };
+    std::map geom_memo;   // key -> conduit row already tabulated
+
+    // Slot-cap transparency tally (surfaced once after the loop): where
+    // g·A_full/c² exceeds the 5%-of-top-width cap, the cap sets the slot and
+    // the requested FV_SLOT_CELERITY is inert for that conduit — its
+    // effective celerity is the cap-implied √(g·A_full/T_cap).
+    int n_closed = 0, n_capped = 0;
+    double c_implied_max = 0.0;
+
     for (int r = 0; r < n_cond; ++r) {
         const auto ur = static_cast(r);
         const int j = CD.link_idx[ur];
         if (j < 0 || j >= n_links) continue;
         const auto uj = static_cast(j);
+
+        // A DUMMY conduit is connectivity, not a channel: it declares that
+        // water leaving one node arrives at another with no section, no
+        // storage and no head loss. Legacy isTrueConduit (dynwave.c:411-414)
+        // is false for it and DW never momentum-solves one — it is routed as a
+        // pass-through by findNonConduitFlow. Do the same here: leave the row
+        // unmeshed (cell_begin −1, count 0, conduit_link −1, so every downstream
+        // consumer skips it) and pick it up in the structure loop below.
+        //
+        // This has to be tested on the SHAPE, before buildXSectParams, rather
+        // than falling through to the zero-geometry check: that check must stay
+        // an error for a link whose geometry genuinely failed to resolve.
+        if (ctx.links.xsect_shape[uj] == XsectShape::DUMMY) continue;
+
         mesh.conduit_link[ur] = j;
 
         XSectParams xs = link::buildXSectParams(ctx.links, uj, &ctx.transect_tables);
         if (xs.y_full <= 0.0 || xs.a_full <= 0.0) {
-            // A control volume needs a real section. DUMMY-shape conduits and
-            // links whose geometry never resolved cannot be marched.
+            // A control volume needs a real section. A link whose geometry
+            // never resolved cannot be marched. (DUMMY shapes are handled
+            // above and never reach here.)
             rep.errors.push_back(
                 "FV routing: conduit '" + ctx.link_names.name_of(j) +
                 "' has no usable cross-section (full depth/area is zero). "
@@ -245,21 +390,48 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
             continue;
         }
 
-        auto& g = mesh.geom[ur];
-        buildGeometry(xs, xsect::isOpen(xs.type), opts.slot_celerity, g,
-                      CD.barrels[ur]);
-        g.roughness    = CD.roughness[ur];
-        g.rough_factor = CD.rough_factor[ur];
-        g.loss_inlet   = CD.loss_inlet[ur];
-        g.loss_outlet  = CD.loss_outlet[ur];
-        g.culvert_code = CD.culvert_code[ur];
-        g.slope        = CD.slope[ur];
-        if (g.culvert_code > 0) {
-            const culvert::CulvertCoeffs cc = culvert::getCoeffs(g.culvert_code);
-            g.culvert_curve = {cc.K, cc.M, cc.C, cc.Y};
-            g.culvert_mitered = static_cast(
-                g.culvert_code == 5 || g.culvert_code == 37 ||
-                g.culvert_code == 46);
+        const bool is_open = xsect::isOpen(xs.type);
+        int sec;
+        if (const auto hit = geom_memo.find(geom_key(xs, CD.barrels[ur], is_open));
+            hit != geom_memo.end()) {
+            // Shared section block (plan Phase 1f): the block carries nothing
+            // per-conduit any more, so every conduit with this key points at
+            // the same entry. Same bytes → bit-identical to the per-conduit
+            // copies it replaces.
+            sec = hit->second;
+        } else {
+            sec = static_cast(mesh.geom.size());
+            mesh.geom.emplace_back();
+            buildGeometry(xs, is_open, opts.slot_celerity, mesh.geom.back(),
+                          CD.barrels[ur]);
+            geom_memo.emplace(geom_key(xs, CD.barrels[ur], is_open), sec);
+        }
+        mesh.conduit_section[ur] = sec;
+        const FvGeometry& g = mesh.geom[static_cast(sec)];
+        if (!g.is_open) {
+            const double c_req = std::max(opts.slot_celerity, 1.0);
+            const double uncapped = kernels::kGravity * g.a_full / (c_req * c_req);
+            const double cap = 0.05 * ((g.w_max > 0.0) ? g.w_max : 1.0);
+            ++n_closed;
+            if (uncapped > cap && g.t_slot > 0.0) {
+                ++n_capped;
+                c_implied_max = std::max(
+                    c_implied_max,
+                    std::sqrt(kernels::kGravity * g.a_full / g.t_slot));
+            }
+        }
+        mesh.conduit_roughness[ur]    = CD.roughness[ur];
+        mesh.conduit_rough_factor[ur] = CD.rough_factor[ur];
+        mesh.conduit_loss_inlet[ur]   = CD.loss_inlet[ur];
+        mesh.conduit_loss_outlet[ur]  = CD.loss_outlet[ur];
+        mesh.conduit_culvert_code[ur] = CD.culvert_code[ur];
+        mesh.conduit_slope[ur]        = CD.slope[ur];
+        if (CD.culvert_code[ur] > 0) {
+            const culvert::CulvertCoeffs cc = culvert::getCoeffs(CD.culvert_code[ur]);
+            mesh.conduit_culvert_curve[ur] = {cc.K, cc.M, cc.C, cc.Y};
+            mesh.conduit_culvert_mitered[ur] = static_cast(
+                CD.culvert_code[ur] == 5 || CD.culvert_code[ur] == 37 ||
+                CD.culvert_code[ur] == 46);
         }
 
         // Mesh length: the Courant-lengthened mod_length is reused as the Δx
@@ -295,7 +467,7 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
         for (int i = 0; i < ncell; ++i) {
             const double t = (static_cast(i) + 0.5) /
                              static_cast(ncell);
-            mesh.cell_geom.push_back(r);
+            mesh.cell_geom.push_back(sec);
             mesh.cell_conduit.push_back(r);
             mesh.cell_dx.push_back(dx);
             mesh.cell_zb.push_back(z1 + (z2 - z1) * t);
@@ -305,6 +477,14 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
     if (!rep.errors.empty()) return rep;
     if (rep.min_dx > 1.0e29) rep.min_dx = 0.0;
 
+    if (n_capped > 0) {
+        char buf[160];
+        std::snprintf(buf, sizeof(buf),
+                      "%d of %d closed conduits (cap-implied celerity up to "
+                      "%.0f ft/s)", n_capped, n_closed, c_implied_max);
+        rep.warnings.push_back(format_warning(WARN_FV_SLOT_CAP, buf));
+    }
+
     // -----------------------------------------------------------------------
     // Interior faces inside each conduit chain
     // -----------------------------------------------------------------------
@@ -318,6 +498,7 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
         mesh.face_dir_l.push_back(dl);
         mesh.face_dir_r.push_back(dr);
         mesh.face_virtual.push_back(is_vj ? uint8_t{1} : uint8_t{0});
+        mesh.face_vj_node.push_back(-1);
         mesh.face_gate.push_back(0);
         mesh.face_culvert.push_back(-1);
     };
@@ -442,6 +623,8 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
             const double dxr = mesh.cell_dx[static_cast(cr)];
             add_face(cl, cr, -1, mesh.node_invert[ui], 0.5 * (dxl + dxr),
                      dl, dr, true);
+            mesh.face_vj_node.back() = i;
+            mesh.node_vj_face[ui] = mesh.n_faces() - 1;
             ++rep.n_virtual;
             continue;
         }
@@ -467,7 +650,7 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
 
             // HEC-5 inlet control acts at the culvert's UPSTREAM face only.
             if (a.end == 0 &&
-                mesh.geom[static_cast(a.conduit)].culvert_code > 0)
+                mesh.conduit_culvert_code[static_cast(a.conduit)] > 0)
                 mesh.face_culvert[static_cast(fidx)] = a.conduit;
         }
     }
@@ -492,6 +675,82 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
         }
     }
 
+    // -----------------------------------------------------------------------
+    // Face sections. Every face reconstructs BOTH sides in ONE section, so the
+    // Riemann problem it poses is well posed. That is already true everywhere
+    // the two sides share a conduit section — which is every face in a
+    // prismatic network, so this pass is a no-op there and the scheme is
+    // bit-identical.
+    //
+    // It is NOT true where two conduits of different section meet at a clean
+    // degree-2 node: each conduit's end face reconstructs its neighbour's
+    // state in its OWN section (ExplicitFvSolver::faceSide takes the geometry
+    // from the surviving cell), so the same physical interface is solved twice
+    // in two different geometries and the wall the width step presents exerts
+    // no force. Give both faces of such a pair one section-averaged geometry
+    // and the per-side hydrostatic correction becomes the wall-pressure term.
+    // -----------------------------------------------------------------------
+    mesh.face_geom.clear();
+    mesh.deriveFaceGeom();
+    {
+        // Averaged sections are memoized on the ordered conduit pair, so a
+        // 400-conduit variable-width chain adds ~400 entries, not one per face.
+        std::map, int> pair_geom;
+        for (int i = 0; i < n_nodes; ++i) {
+            const auto ui = static_cast(i);
+            const int nb = mesh.node_face_ptr[ui];
+            const int ne = mesh.node_face_ptr[ui + 1];
+            if (ne - nb != 2) continue;              // only clean degree-2
+            const int f0 = mesh.node_face_idx[static_cast(nb)];
+            const int f1 = mesh.node_face_idx[static_cast(nb + 1)];
+            const int g0 = mesh.face_geom[static_cast(f0)];
+            const int g1 = mesh.face_geom[static_cast(f1)];
+            if (g0 < 0 || g1 < 0 || g0 == g1) continue;   // same section: no-op
+            const auto& a = mesh.geom[static_cast(g0)];
+            const auto& b = mesh.geom[static_cast(g1)];
+            // Only average like with like. Different shape types, transect
+            // tables (IRREGULAR/CUSTOM/STREET) and differing barrel counts have
+            // no meaningful average; those faces keep their own section, which
+            // is still well balanced (the C-property holds for ANY consistent
+            // choice) and merely first order in the step.
+            if (a.xs.type != b.xs.type || a.barrels != b.barrels ||
+                a.xs.transect >= 0 || b.xs.transect >= 0 ||
+                a.xs.area_tbl != nullptr || b.xs.area_tbl != nullptr)
+                continue;
+            const auto key = std::make_pair(std::min(g0, g1), std::max(g0, g1));
+            int gf;
+            if (const auto hit = pair_geom.find(key); hit != pair_geom.end()) {
+                gf = hit->second;
+            } else {
+                XSectParams xs = a.xs;               // shape, tables, culvert
+                const XSectParams& xb = b.xs;
+                const auto mid = [](double p, double q) { return 0.5 * (p + q); };
+                xs.y_full = mid(a.xs.y_full, xb.y_full);
+                xs.w_max  = mid(a.xs.w_max,  xb.w_max);
+                xs.yw_max = mid(a.xs.yw_max, xb.yw_max);
+                xs.a_full = mid(a.xs.a_full, xb.a_full);
+                xs.r_full = mid(a.xs.r_full, xb.r_full);
+                xs.s_full = mid(a.xs.s_full, xb.s_full);
+                xs.s_max  = mid(a.xs.s_max,  xb.s_max);
+                xs.y_bot  = mid(a.xs.y_bot,  xb.y_bot);
+                xs.a_bot  = mid(a.xs.a_bot,  xb.a_bot);
+                xs.s_bot  = mid(a.xs.s_bot,  xb.s_bot);
+                xs.r_bot  = mid(a.xs.r_bot,  xb.r_bot);
+                FvGeometry g{};
+                buildGeometry(xs, xsect::isOpen(xs.type), opts.slot_celerity, g,
+                              a.barrels);
+                // A face section is geometry only: friction and losses are
+                // read through the CELL's conduit (mesh.conduit_*), never
+                // through the face (faceSide uses only A, W and I₁ from it).
+                gf = static_cast(mesh.geom.size());
+                mesh.geom.push_back(g);
+                pair_geom.emplace(key, gf);
+            }
+            mesh.face_geom[static_cast(f0)] = gf;
+            mesh.face_geom[static_cast(f1)] = gf;
+        }
+    }
+
     // -----------------------------------------------------------------------
     // Cell → face back-references. Every cell is bounded by exactly two faces
     // (interior, spliced, or node-coupling), so this is a fixed-width map and
@@ -601,16 +860,35 @@ MeshBuildReport buildNetworkMesh(SimulationContext& ctx,
 
     // -----------------------------------------------------------------------
     // Non-conduit links — applied as node source/sink pairs (plan §3.4).
+    //
+    // The membership test matches StructureSolver::nc_indices_
+    // (HydStructures.cpp:221-233) exactly, DUMMY conduits included: the two
+    // lists have to agree or a link is computed by one side and applied by
+    // neither. Dummies are flagged so the solver knows to derive their
+    // discharge itself instead of reading it from the forcing array.
     // -----------------------------------------------------------------------
+    mesh.node_dummy_drain.assign(static_cast(n_nodes), 0);
     for (int j = 0; j < n_links; ++j) {
         const auto uj = static_cast(j);
-        if (ctx.links.type[uj] == LinkType::CONDUIT) continue;
+        const bool is_dummy = (ctx.links.type[uj] == LinkType::CONDUIT &&
+                               ctx.links.xsect_shape[uj] == XsectShape::DUMMY);
+        if (ctx.links.type[uj] == LinkType::CONDUIT && !is_dummy) continue;
         const int a = ctx.links.node1[uj];
         const int b = ctx.links.node2[uj];
         if (a < 0 || b < 0) continue;
         mesh.struct_link.push_back(j);
         mesh.struct_n1.push_back(a);
         mesh.struct_n2.push_back(b);
+        mesh.struct_is_dummy.push_back(is_dummy ? 1 : 0);
+        if (is_dummy) mesh.node_dummy_drain[static_cast(a)] = 1;
+    }
+    // Leave both vectors EMPTY when the model has no dummy links at all, so
+    // `node_dummy_drain.empty()` is a cheap "nothing to do" test the solver's
+    // hot paths can branch on, and a model without dummies allocates nothing.
+    if (std::find(mesh.struct_is_dummy.begin(), mesh.struct_is_dummy.end(),
+                  uint8_t{1}) == mesh.struct_is_dummy.end()) {
+        mesh.struct_is_dummy.clear();
+        mesh.node_dummy_drain.clear();
     }
 
     rep.n_cells    = nc;
diff --git a/src/engine/hydraulics/fv/NetworkMeshBuilder.hpp b/src/engine/hydraulics/fv/NetworkMeshBuilder.hpp
index 6aba5bbe5..e0f8c66e0 100644
--- a/src/engine/hydraulics/fv/NetworkMeshBuilder.hpp
+++ b/src/engine/hydraulics/fv/NetworkMeshBuilder.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NetworkMeshBuilder.hpp
  * @brief Build the FV cell/face mesh from a SimulationContext.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_NETWORK_MESH_BUILDER_HPP
diff --git a/src/engine/hydraulics/fv/NetworkMeshData.hpp b/src/engine/hydraulics/fv/NetworkMeshData.hpp
index 42a1a6f50..a1ad8ca44 100644
--- a/src/engine/hydraulics/fv/NetworkMeshData.hpp
+++ b/src/engine/hydraulics/fv/NetworkMeshData.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NetworkMeshData.hpp
  * @brief SoA storage for the 1D finite-volume network mesh and its state.
@@ -22,7 +38,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_NETWORK_MESH_DATA_HPP
@@ -34,16 +50,10 @@
 #include "../XSectBatch.hpp"
 #include "../HydClosureKernels.hpp"
 #include "../XSectKernels.hpp"
+#include "FvClosureKernels.hpp"
 
 namespace openswmm::fv {
 
-/// Samples in the per-geometry first-moment (I₁) table over [0, y_full].
-/// I₁ is the antiderivative of A(h); above the crown the closure is exactly
-/// linear in h so the table is extended analytically rather than sampled
-/// (see FvKernels::i1OfDepth), which is what keeps deep surcharge accurate
-/// with a small table.
-inline constexpr int kI1Samples = 129;
-
 /// Samples in a STORAGE node's flattened depth→volume table.
 inline constexpr int kNodeVolSamples = 129;
 
@@ -61,14 +71,6 @@ inline constexpr int kNodeVolSamples = 129;
 struct FvGeometry {
     XSectParams xs{};              ///< section parameters (owns transect table ptrs)
 
-    /// Where the section's own geometry is evaluated. A pointer, not a copy:
-    /// the evaluator carries the shared geometry tables, and which memory space
-    /// those live in is exactly what differs between the host solver and the
-    /// device backend. The mesh builder binds this to xsect::hostEval(); a
-    /// device backend rebinds it to its own device-resident pair, and the same
-    /// kernel bodies then run unchanged on both (plan §5.1).
-    const xsect::XsectEval* eval = nullptr;
-
     double y_full = 0.0;           ///< full depth (ft)
     double a_full = 0.0;           ///< area when full (ft²)
     double w_max  = 0.0;           ///< width at widest point (ft)
@@ -97,60 +99,22 @@ struct FvGeometry {
 
     uint8_t is_open = 0;           ///< open section: no crown, no slot taper
 
-    // -- Friction and losses (already lengthening-adjusted, see Router::init) --
-
-    double roughness    = 0.01;    ///< Manning n
-    double rough_factor = 0.0;     ///< g·(n/PHI)² — friction denominator factor
-    double loss_inlet   = 0.0;     ///< entrance loss coefficient K
-    double loss_outlet  = 0.0;     ///< exit loss coefficient K
-
     int    barrels = 1;            ///< parallel identical barrels
 
-    /// [XSECTIONS] culvert code (0 = not a culvert), and the conduit slope the
-    /// HEC-5 inlet-control equations need. Cold: read only at the conduit's
-    /// upstream boundary face, and only when the code is set.
-    int    culvert_code = 0;
-    double slope        = 0.0;
-
-    /// The type code's inlet-control curve, RESOLVED at mesh build. Keeping the
-    /// resolved coefficients rather than the code is what lets the solver
-    /// evaluate the closure with no engine dependency — the table lookup is
-    /// host work, the curve is all the kernel needs.
-    hydkernels::CulvertCurve culvert_curve{};
-    uint8_t culvert_mitered = 0;
-
-    /// First moment I₁(h) = ∫₀ʰ A(η)dη sampled uniformly on h ∈ [0, y_full],
-    /// followed by the companion A(h) samples on the same grid — 2·kI1Samples
-    /// entries, `[0, kI1Samples)` = I₁ and `[kI1Samples, 2·kI1Samples)` = A.
-    /// One buffer because both are read together on every evaluation.
-    ///
-    /// Built once at init by composite integration of the same A(h) the solver
-    /// evaluates. Quadrature error does not threaten well-balancedness — that
-    /// needs only a single-valued I₁(h) — but it does set the accuracy of the
-    /// pressure term, hence the fine sub-sampling in buildI1Table.
-    ///
-    /// A fixed inline array rather than a vector: the whole struct is copied
-    /// into device memory by the accelerated backend, and an owning container
-    /// cannot cross that boundary. At 129 samples this is 2 kB per DISTINCT
-    /// cross-section — a few hundred at most in a real model.
-    double i1_tbl[2 * kI1Samples] = {};
-
-    /// The INVERSE of the area column: depth sampled uniformly in AREA over
-    /// [0, a_crown], `h_tbl[j]` being the exact root of A(h) = j·a_crown/(n−1).
-    ///
-    /// The forward table is uniform in depth, which is the wrong grid to invert
-    /// on. Bracketing a query area in it costs a binary search — seven
-    /// dependent loads with unpredictable branches — and near the crown, where
-    /// A is nearly flat in h, one depth panel spans a wide range of areas, so
-    /// the bracket it yields is loose and the root-find needs several
-    /// evaluations of the closure. Profiling put `depthOfArea` and the area
-    /// lookups it drives at 87 % of solver time on a Δx = 20 ft run.
-    ///
-    /// Sampling uniformly in area instead makes the panel a single divide, and
-    /// makes the residuals at its two ends known WITHOUT evaluating the
-    /// closure — they are the sample areas themselves. Built at init from the
-    /// bracketed inverse, so it costs nothing at run time.
-    double h_tbl[kI1Samples] = {};
+    // Friction, losses, slope and the culvert curve are PER CONDUIT and live
+    // in NetworkMeshData::conduit_* (plan Phase 1f): this block is one shared
+    // entry per DISTINCT (section, barrels, open) so a 5000-pipe network with
+    // a dozen sections keeps a dozen closure tables cache-resident instead of
+    // streaming ~4 kB of geometry per cell every substep.
+
+    /// The closure every FvKernels section function evaluates: the exact
+    /// section (SectionGeometry.hpp) sampled at build time into a monotone
+    /// cubic table with the slot folded in, or the polynomial class for open
+    /// sections (FvClosureKernels.hpp). A fixed-size, pointer-free POD block,
+    /// so the whole geometry can be captured by a device backend as plain
+    /// bytes; `xs` above still carries host table pointers for the table-
+    /// defined shapes and is read only at build time.
+    FvClosure closure_tbl{};
 
 };
 
@@ -199,6 +163,48 @@ struct NetworkMeshData {
     std::vector    face_cr;      ///< right cell (-1 ⇒ node on the right)
     std::vector    face_node;    ///< coupled node (-1 for interior faces)
 
+    /// Cross-section (index into `geom`) that this face reconstructs BOTH of
+    /// its sides in. Almost always the adjacent cells' own section, which
+    /// leaves the scheme untouched.
+    ///
+    /// It differs only where two conduits of DIFFERENT section meet at a
+    /// clean degree-2 node, and there it is the section-averaged pair. Without
+    /// it, such an interface is evaluated twice in two different geometries —
+    /// each conduit's end face reconstructs the neighbour's state in its OWN
+    /// section — so the wall the width step physically presents to the flow
+    /// exerts no force. That missing wall-pressure term is the measured
+    /// pseudo-2D defect (SWASHES §3.5): depths run too deep wherever the
+    /// channel contracts and too shallow wherever it expands, antisymmetric in
+    /// dB/dx and independent of Δx. Reconstructing both sides in one shared
+    /// section makes the pair a single well-posed Riemann problem, and the
+    /// hydrostatic-reconstruction correction already applied per side,
+    /// g·(I₁(cell section, h) − I₁(face section, h*)), becomes exactly the
+    /// discrete wall-pressure (I₂) source — consistently discretized with the
+    /// flux it has to balance, which is what every additive closure got wrong.
+    std::vector    face_geom;    ///< index into `geom`
+
+    /// Give every face the section of its adjacent cell, sizing `face_geom` if
+    /// a caller never populated it. This reproduces the behaviour that
+    /// preceded `face_geom` exactly, so it is always safe; NetworkMeshBuilder
+    /// calls it and then overrides the entries at width-step junctions.
+    /// Idempotent, and a no-op once `face_geom` is already the right size.
+    ///
+    /// It exists because `face_geom` is the one face array a hand-built mesh
+    /// can silently omit: the unit-test fixtures assemble NetworkMeshData
+    /// field by field without a SimulationContext, and an omission there is an
+    /// empty vector that `faceSide` would index straight into a null page.
+    void deriveFaceGeom() {
+        if (face_geom.size() == static_cast(n_faces())) return;
+        face_geom.assign(static_cast(n_faces()), 0);
+        for (int f = 0; f < n_faces(); ++f) {
+            const auto uf = static_cast(f);
+            const int c = (face_cl[uf] >= 0) ? face_cl[uf] : face_cr[uf];
+            face_geom[uf] = (c >= 0 &&
+                             static_cast(c) < cell_geom.size())
+                ? cell_geom[static_cast(c)] : 0;
+        }
+    }
+
     /// Flap-gate mask on a boundary face: bit 0 blocks a POSITIVE mass flux,
     /// bit 1 blocks a NEGATIVE one, 0 leaves the face open. A gate is a check
     /// valve, so a blocked face behaves as a wall only while the flux would run
@@ -232,6 +238,22 @@ struct NetworkMeshData {
     /// equivalence test and the reporting path read it.
     std::vector face_virtual;
 
+    /// Node index of the virtual junction a spliced face replaced (-1 for
+    /// every other face). face_node must stay -1 for spliced faces — they are
+    /// interior to the solver — so the reporting path carries the association
+    /// here instead of re-deriving it (matching inverts collides when two
+    /// virtual junctions share a bit-identical invert, leaving the loser
+    /// permanently unreported).
+    std::vector face_vj_node;
+
+    /// Spliced face of each virtual junction (−1 for every other node): the
+    /// reverse of face_vj_node. A lateral inflow at a virtual junction is
+    /// diverted into the two cells adjoining that face
+    /// (ExplicitFvSolver::refreshStructFlows), and the reporting path reads
+    /// the same two cells' conduits for the node's through-flow — neither
+    /// should scan the face list per node per step.
+    std::vector node_vj_face;
+
     // -----------------------------------------------------------------------
     // Conduit → cell map. Cells of a conduit are CONTIGUOUS by construction,
     // so a begin/count pair is a complete (and cheaper) CSR.
@@ -240,6 +262,21 @@ struct NetworkMeshData {
     std::vector conduit_cell_begin; ///< first cell of conduit row r
     std::vector conduit_cell_count; ///< cells in conduit row r
     std::vector conduit_link;       ///< base LinkData index of conduit row r
+    std::vector conduit_section;    ///< index into `geom` (shared section block)
+
+    // Per-conduit friction and losses (already lengthening-adjusted, see
+    // Router::init) and the culvert inlet-control data — everything that
+    // differs between conduits sharing one section block (plan Phase 1f).
+    std::vector  conduit_roughness;      ///< Manning n
+    std::vector  conduit_rough_factor;   ///< g·(n/PHI)² — friction denominator factor
+    std::vector  conduit_loss_inlet;     ///< entrance loss coefficient K
+    std::vector  conduit_loss_outlet;    ///< exit loss coefficient K
+    std::vector  conduit_slope;          ///< bed slope the HEC-5 equations need
+    std::vector     conduit_culvert_code;   ///< [XSECTIONS] culvert code (0 = none)
+    /// The type code's inlet-control curve, RESOLVED at mesh build so the
+    /// solver evaluates the closure with no engine dependency.
+    std::vector conduit_culvert_curve;
+    std::vector conduit_culvert_mitered;
 
     // -----------------------------------------------------------------------
     // Cell chains (CSR). A chain is a maximal run of cells joined by INTERIOR
@@ -267,12 +304,32 @@ struct NetworkMeshData {
     // Non-conduit links (pumps, orifices, weirs, outlets). Evaluated by their
     // existing structure equations outside the solver and applied here as
     // source/sink pairs on the two node volumes.
+    //
+    // DUMMY-xsect conduits belong here too. Legacy isTrueConduit
+    // (dynwave.c:411-414) is false for them: they carry no cross-section, so
+    // there is nothing to march, and DW routes them through findNonConduitFlow
+    // as a pure pass-through instead. They differ from a real structure in that
+    // their discharge is not a head relation the engine can evaluate outside
+    // the solver — it is whatever arrives at the upstream node — so the solver
+    // computes it itself (`struct_is_dummy`, see ExplicitFvSolver::
+    // refreshDummyFlows) rather than reading FvStepForcing::structure_flow.
     // -----------------------------------------------------------------------
 
     std::vector struct_link;  ///< LinkData index
     std::vector struct_n1;    ///< upstream node
     std::vector struct_n2;    ///< downstream node
 
+    /// 1 for a DUMMY-xsect conduit, 0 for a real structure. Parallel to
+    /// `struct_link`.
+    std::vector struct_is_dummy;
+
+    /// 1 when the node is the upstream end of a DUMMY link. Such a node is a
+    /// free-drainage boundary, not a storing junction: the pass-through removes
+    /// exactly what arrives, so its volume is constant and its head needs no
+    /// relaxation (the correction would be identically zero — see
+    /// ExplicitFvSolver::relaxOneNode).
+    std::vector node_dummy_drain;
+
     // -----------------------------------------------------------------------
     // Node → face map (CSR). Two-pass gather with NO atomics: the node update
     // reads its own face list in a fixed order, so the result is deterministic
@@ -354,13 +411,21 @@ struct NetworkMeshData {
         cell_face0.clear(); cell_face1.clear();
         cell_side0.clear(); cell_side1.clear();
         face_cl.clear(); face_cr.clear(); face_node.clear(); face_gate.clear();
+        face_geom.clear();
         face_culvert.clear();
         face_zb.clear(); face_dx.clear(); face_virtual.clear();
+        face_vj_node.clear(); node_vj_face.clear();
         face_dir_l.clear(); face_dir_r.clear();
         conduit_cell_begin.clear(); conduit_cell_count.clear(); conduit_link.clear();
+        conduit_section.clear();
+        conduit_roughness.clear(); conduit_rough_factor.clear();
+        conduit_loss_inlet.clear(); conduit_loss_outlet.clear(); conduit_slope.clear();
+        conduit_culvert_code.clear(); conduit_culvert_curve.clear();
+        conduit_culvert_mitered.clear();
         chain_ptr.clear(); chain_cells.clear(); chain_dir.clear();
         cell_chain.clear(); cell_chain_pos.clear();
         struct_link.clear(); struct_n1.clear(); struct_n2.clear();
+        struct_is_dummy.clear(); node_dummy_drain.clear();
         node_face_ptr.clear(); node_face_idx.clear();
         node_face_sign.clear(); node_face_zb.clear();
         node_invert.clear(); node_full_depth.clear(); node_ponded_area.clear();
@@ -416,6 +481,17 @@ struct NetworkStateData {
     std::vector cell_phi;
     int n_species = 0;
 
+    /// TPA regime flag per cell (issue #156 Phase 4): EMPTY unless
+    /// FV_PRESSURE_CLOSURE TPA; 1 = pressurized (closure evaluates on the
+    /// extended slot line, both signs of ΔA), 0 = free surface (table
+    /// closure). Lives in the STATE because the static membership predicates
+    /// (PressurizedHeadSolver::cellPressurized, the census edit) must see it.
+    /// The flag is physical air-pathway history — updated once per substep by
+    /// the solver's venting rule, saved/restored with the step-rejection
+    /// snapshot, cleared (all-free) on cold start; a restart worst-case is
+    /// one spurious re-pressurization step (TPA plan §5).
+    std::vector cell_tpa;
+
     void resize(int n_cells, int n_nodes, int n_species_in) {
         const auto nc = static_cast(n_cells);
         const auto nn = static_cast(n_nodes);
diff --git a/src/engine/hydraulics/fv/NetworkSolverFactory.cpp b/src/engine/hydraulics/fv/NetworkSolverFactory.cpp
index 6edee60eb..55ba58493 100644
--- a/src/engine/hydraulics/fv/NetworkSolverFactory.cpp
+++ b/src/engine/hydraulics/fv/NetworkSolverFactory.cpp
@@ -200,6 +200,13 @@ std::unique_ptr makeNetworkSolver(const FvOptions& opts,
     if (mode.empty()) mode = backend_name(opts.backend);
     if (mode == "cpu") return cpu();
 
+    // The implicit pressurized head update (FV_PRESSURIZED_IMPLICIT, slot
+    // program R2a) lives in the CPU reference solver only — a device plugin
+    // would silently run the pressurized subset explicitly at the edited
+    // (advective) census bound, which is exactly the instability the pass
+    // exists to remove. Honour the option over the backend request.
+    if (opts.pressurized_implicit) return cpu();
+
     // Small-problem gate. A Kokkos plugin pays a per-kernel launch overhead on
     // EVERY substep, and the built-in solver is itself OpenMP-threaded, so the
     // plugin only pays off once per-cell work amortizes the launches. Carried
diff --git a/src/engine/hydraulics/fv/NetworkSolverFactory.hpp b/src/engine/hydraulics/fv/NetworkSolverFactory.hpp
index 17960960e..71212ed2e 100644
--- a/src/engine/hydraulics/fv/NetworkSolverFactory.hpp
+++ b/src/engine/hydraulics/fv/NetworkSolverFactory.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NetworkSolverFactory.hpp
  * @brief Runtime backend selection for the explicit FV 1D network solver.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FV_NETWORK_SOLVER_FACTORY_HPP
diff --git a/src/engine/hydraulics/fv/PressurizedHeadSolver.cpp b/src/engine/hydraulics/fv/PressurizedHeadSolver.cpp
new file mode 100644
index 000000000..f0d1396dd
--- /dev/null
+++ b/src/engine/hydraulics/fv/PressurizedHeadSolver.cpp
@@ -0,0 +1,908 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file PressurizedHeadSolver.cpp
+ * @brief Implementation of the R2a implicit pressurized head update.
+ * @ingroup engine_fv
+ */
+
+#include "PressurizedHeadSolver.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+#include "../HydClosureKernels.hpp"
+
+namespace openswmm::fv {
+
+namespace k = kernels;
+
+namespace {
+
+/// Friction coefficient γ in the semi-implicit denominator 1 + Δt·γ — the
+/// SAME laws frictionFor applies to the cell momentum (Manning by default;
+/// a full FORCE_MAIN switches to its own HW/DW slope), expressed per unit
+/// time so the face conductance damps exactly as the cell does.
+///
+/// Evaluated at the PHYSICAL velocity Q/min(A, a_crown), not Q/A: above the
+/// crown the conserved A carries the slot's numerical storage, and a
+/// velocity diluted by it under-states the friction slope by exactly the
+/// slot share — which is the mechanism that made the explicit scheme's
+/// full-bore head loss a function of FV_SLOT_CELERITY (R1: 8.8 ft at c=30
+/// against 13.30 analytic). The implicit face law is not a conservative
+/// Godunov flux — no bore-speed consistency binds it — so it is free to use
+/// the conveyance area, the same distinction legacy DW draws with
+/// conveyArea (#144).
+double frictionGamma(const FvGeometry& g, double roughness, double rough_factor,
+                     double q, double a, double h) {
+    const double a_conv = std::min(a, std::max(g.a_crown, k::kDryArea));
+    if (a_conv <= k::kDryArea) return 0.0;
+    const double u = q / a_conv;
+    const double absu = std::fabs(u);
+    const double r = k::hydRadOfDepth(g, h);
+    if (r <= 0.0) return 0.0;
+    if (g.xs.type == static_cast(XSectShape::FORCE_MAIN) &&
+        h >= g.y_full) {
+        if (absu <= 0.0) return 0.0;
+        const double sf = (roughness < 1.0)
+                              ? hydkernels::fricSlopeDW(u, r, roughness)
+                              : hydkernels::fricSlopeHW(u, r, roughness);
+        return k::kGravity * sf / absu;
+    }
+    if (rough_factor <= 0.0) return 0.0;
+    const double r43 = r * std::cbrt(r);
+    return rough_factor * absu / r43;
+}
+
+bool fixedHead(const FvStepForcing* f, std::size_t un) {
+    return f && f->node_fixed_head && std::isfinite(f->node_fixed_head[un]);
+}
+
+/// algebraicActive, replicated from ExplicitFvSolver over the view's data:
+/// eligible AND not demoted to the bucket path by a real pond above v_full.
+bool algActive(const PressurizedView& v, int n) {
+    const auto un = static_cast(n);
+    if (!(*v.node_alg)[un]) return false;
+    if (v.mesh->node_can_pond[un] &&
+        v.state->node_volume[un] > (*v.node_vfull)[un])
+        return false;
+    return true;
+}
+
+/// The node's physical ceiling — the same bracket top solveAlgebraicNode
+/// uses: the rim for a pondable node (above it the water is real storage),
+/// rim + surcharge depth for a sealed one, and a generous crown-derived
+/// ceiling for a junction with no rim on record.
+double nodeCeiling(const NetworkMeshData& m, int n) {
+    const auto un = static_cast(n);
+    const double invert = m.node_invert[un];
+    const double full = m.node_full_depth[un];
+    if (full > 0.0)
+        return invert +
+               (m.node_can_pond[un] ? full : full + m.node_sur_depth[un]);
+    double top = 1.0;
+    for (int p = m.node_face_ptr[un]; p < m.node_face_ptr[un + 1]; ++p) {
+        const auto uf = static_cast(
+            m.node_face_idx[static_cast(p)]);
+        const int cell = (m.face_cl[uf] >= 0) ? m.face_cl[uf] : m.face_cr[uf];
+        if (cell < 0) continue;
+        const FvGeometry& g = m.geom[static_cast(
+            m.cell_geom[static_cast(cell)])];
+        top = std::max(top, (m.face_zb[uf] - invert) + 2.0 * g.y_full);
+    }
+    return invert + top;
+}
+
+} // namespace
+
+// ---------------------------------------------------------------------------
+// Union-find
+// ---------------------------------------------------------------------------
+
+int PressurizedHeadSolver::ufFind(int i) {
+    while (uf_parent_[static_cast(i)] != i) {
+        uf_parent_[static_cast(i)] =
+            uf_parent_[static_cast(
+                uf_parent_[static_cast(i)])];
+        i = uf_parent_[static_cast(i)];
+    }
+    return i;
+}
+
+void PressurizedHeadSolver::ufUnion(int a, int b) {
+    const int ra = ufFind(a), rb = ufFind(b);
+    if (ra != rb) uf_parent_[static_cast(std::max(ra, rb))] =
+        std::min(ra, rb);
+}
+
+// ---------------------------------------------------------------------------
+// classify — the memoryless subset derivation
+// ---------------------------------------------------------------------------
+
+bool PressurizedHeadSolver::classify(const PressurizedView& v) {
+    const NetworkMeshData& mesh = *v.mesh;
+    const NetworkStateData& state = *v.state;
+    const auto nc = static_cast(mesh.n_cells());
+    const auto nn = static_cast(mesh.n_nodes());
+
+    imp_faces_.clear();
+    cell_press_.assign(nc, 0);
+    node_fold_.assign(nn, 0);
+
+    bool any = false;
+    for (std::size_t c = 0; c < nc; ++c) {
+        if (!(*v.cell_active)[c]) continue;
+        if (cellPressurized(mesh, state, static_cast(c))) {
+            cell_press_[c] = 1;
+            any = true;
+        }
+    }
+    if (!any) return false;
+
+    cell_unk_.assign(nc, -1);
+    node_unk_.assign(nn, -1);
+
+    // Face pass: the implicit set is the FULL faces only. Transition
+    // (kDelta) faces stay entirely explicit — flux and census bound — so
+    // fronts keep shock-captured physics at a front-resolving dt (see the
+    // kDelta taxonomy note in the header for the measured reasons).
+    for (const int f : *v.active_faces) {
+        const std::uint8_t mode = faceModeOf(mesh, state, f);
+        if (mode != kFull) continue;
+        ImpFace F;
+        F.face = f;
+        F.mode = mode;
+        imp_faces_.push_back(F);
+    }
+    if (imp_faces_.empty()) return false;
+
+    // Fold pass: a pressurized algebraic junction whose EVERY incident face
+    // is FULL-implicit becomes an unknown row. Anything else stays Dirichlet
+    // data (fixed heads, storage/demoted nodes, transition junctions).
+    for (std::size_t un = 0; un < nn; ++un) {
+        const int n = static_cast(un);
+        if (!algActive(v, n)) continue;
+        if (fixedHead(v.forcing, un)) continue;
+        const int b = mesh.node_face_ptr[un];
+        const int e = mesh.node_face_ptr[un + 1];
+        if (e <= b) continue;
+        bool all_full = true;
+        for (int p = b; p < e && all_full; ++p) {
+            const int f = mesh.node_face_idx[static_cast(p)];
+            all_full = faceModeOf(mesh, state, f) == kFull;
+        }
+        if (all_full) node_fold_[un] = 1;
+    }
+
+    // Unknown table: pressurized cell sides of implicit faces, then folded
+    // nodes. (A pressurized cell isolated behind gates never appears — its
+    // faces keep their explicit laws and its dt keeps the explicit bound.)
+    unk_entity_.clear();
+    auto cellUnknown = [&](int c) {
+        auto& id = cell_unk_[static_cast(c)];
+        if (id < 0) {
+            id = static_cast(unk_entity_.size());
+            unk_entity_.push_back(c);
+        }
+        return id;
+    };
+    auto nodeUnknown = [&](int n) {
+        auto& id = node_unk_[static_cast(n)];
+        if (id < 0) {
+            id = static_cast(unk_entity_.size());
+            unk_entity_.push_back(mesh.n_cells() + n);
+        }
+        return id;
+    };
+
+    for (ImpFace& F : imp_faces_) {
+        const auto uf = static_cast(F.face);
+        const int cl = mesh.face_cl[uf];
+        const int cr = mesh.face_cr[uf];
+        const int nd = mesh.face_node[uf];
+
+        // Left side.
+        if (cl >= 0) {
+            if (cell_press_[static_cast(cl)])
+                F.unk_l = cellUnknown(cl);
+            else
+                F.dir_l = 0.0;  // value filled at solve time (cell_eta)
+        } else if (nd >= 0 && node_fold_[static_cast(nd)]) {
+            F.unk_l = nodeUnknown(nd);
+        }
+        // Right side.
+        if (cr >= 0) {
+            if (cell_press_[static_cast(cr)])
+                F.unk_r = cellUnknown(cr);
+        } else if (nd >= 0 && node_fold_[static_cast(nd)]) {
+            F.unk_r = nodeUnknown(nd);
+        }
+    }
+
+    // Components over FULL faces whose both endpoints are unknowns.
+    const int nu = static_cast(unk_entity_.size());
+    uf_parent_.resize(static_cast(nu));
+    for (int i = 0; i < nu; ++i) uf_parent_[static_cast(i)] = i;
+    for (const ImpFace& F : imp_faces_)
+        if (F.unk_l >= 0 && F.unk_r >= 0) ufUnion(F.unk_l, F.unk_r);
+
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// solve
+// ---------------------------------------------------------------------------
+
+void PressurizedHeadSolver::solve(const PressurizedView& v, double dt) {
+    if (imp_faces_.empty() || dt <= 0.0) return;
+    const NetworkMeshData& mesh = *v.mesh;
+    NetworkStateData& state = *v.state;
+    const int nu = static_cast(unk_entity_.size());
+    const auto unu = static_cast(nu);
+
+    // ---- per-unknown constants -------------------------------------------
+    unk_eta0_.assign(unu, 0.0);
+    unk_store_.assign(unu, 0.0);
+    unk_rhs_ext_.assign(unu, 0.0);
+    unk_head_.assign(unu, 0.0);
+    unk_dirichlet_.assign(unu, 0);
+    unk_dirvalue_.assign(unu, 0.0);
+
+    for (int u = 0; u < nu; ++u) {
+        const int ent = unk_entity_[static_cast(u)];
+        if (ent < mesh.n_cells()) {
+            const auto uc = static_cast(ent);
+            const FvGeometry& g =
+                mesh.geom[static_cast(mesh.cell_geom[uc])];
+            const double h = state.cell_h[uc];
+            // TPA (issue #156 Phase 5): a FLAGGED cell lives on the SIGNED
+            // slot line, whose storage derivative dA/dη is the constant
+            // t_slot at ANY piezometric depth — including h < 0 (where the
+            // table width is zero and the clamp made this an almost
+            // storage-free row) and 0 < h < y_crown (where the table returns
+            // the free-surface width, ~1e5 × t_slot at study celerities).
+            // Either mis-width detonates the linearized head update on a
+            // sloped pressurized start: measured on E3 implicit × TPA, the
+            // apex cell's head left the physical range within 4 substeps and
+            // the run NaN'd at t=0 (P5 task-3). The width must follow the
+            // regime, exactly as censusDt/cellStableDt already do.
+            const bool tpa_c =
+                !state.cell_tpa.empty() && state.cell_tpa[uc] != 0;
+            const double T =
+                std::max(tpa_c ? g.t_slot : k::widthOfDepth(g, h), 1.0e-12);
+            unk_store_[static_cast(u)] =
+                T * mesh.cell_dx[uc] / dt;
+            unk_eta0_[static_cast(u)] = v.cell_eta[uc];
+            if (v.cell_qlat && !v.cell_qlat->empty())
+                unk_rhs_ext_[static_cast(u)] +=
+                    (*v.cell_qlat)[uc];
+            // Explicit faces of a pressurized cell — transition faces,
+            // gates, culvert caps, walls — enter as constants: the
+            // divergence updateCells will integrate has to be the
+            // divergence this solve balanced.
+            const int faces[2] = {mesh.cell_face0[uc], mesh.cell_face1[uc]};
+            const std::int8_t sides[2] = {mesh.cell_side0[uc],
+                                          mesh.cell_side1[uc]};
+            for (int e2 = 0; e2 < 2; ++e2) {
+                const int f = faces[e2];
+                if (faceModeOf(mesh, state, f) == kFull) continue;
+                const double fa = v.f_mass[static_cast(f)];
+                unk_rhs_ext_[static_cast(u)] +=
+                    (sides[e2] == 0) ? -fa : fa;
+            }
+        } else {
+            const int n = ent - mesh.n_cells();
+            const auto un = static_cast(n);
+            // Algebraic junction row: zero storage (today's convention — the
+            // balance is instantaneous), sources on the RHS. The carry bleeds
+            // in exactly as solveAlgebraicNode bled it.
+            unk_eta0_[static_cast(u)] = state.node_head[un];
+            double q_ext = (*v.node_qstruct)[un] + (*v.node_carry)[un] / dt;
+            if (!(v.node_lat_div && !v.node_lat_div->empty() &&
+                  (*v.node_lat_div)[un]) &&
+                v.forcing && v.forcing->node_lateral)
+                q_ext += v.forcing->node_lateral[un];
+            unk_rhs_ext_[static_cast(u)] = q_ext;
+        }
+    }
+
+    // ---- per-face coefficients ---------------------------------------------
+    for (ImpFace& F : imp_faces_) {
+        const auto uf = static_cast(F.face);
+        const k::FaceState& L = v.f_state_l[uf];
+        const k::FaceState& R = v.f_state_r[uf];
+        // Conveyance area, not conserved area: the slot's numerical storage
+        // must not conduct (see frictionGamma above). Capped at the FACE
+        // section's crown area — both sides were reconstructed in it.
+        const FvGeometry& gf =
+            mesh.geom[static_cast(mesh.face_geom[uf])];
+        const double ahat =
+            std::min(0.5 * (L.a + R.a), std::max(gf.a_crown, k::kDryArea));
+        const double Lf = mesh.face_dx[uf];
+        F.cond = 0.0;
+        if (ahat <= k::kDryArea || Lf <= 0.0) continue;
+
+        double gamma = 0.0;
+        int ngam = 0;
+        for (const int c : {mesh.face_cl[uf], mesh.face_cr[uf]}) {
+            if (c < 0) continue;
+            const auto uc = static_cast(c);
+            const FvGeometry& g =
+                mesh.geom[static_cast(mesh.cell_geom[uc])];
+            // A TPA-flagged cell (issue #156) is full at any piezometric
+            // depth: friction evaluates at y_full (R = r_full, and a full
+            // FORCE_MAIN keeps its pressurized law) rather than at a
+            // sub-atmospheric h the table would read as part-full.
+            const double h_fric =
+                (!state.cell_tpa.empty() && state.cell_tpa[uc] != 0 &&
+                 state.cell_h[uc] < g.y_full)
+                    ? g.y_full : state.cell_h[uc];
+            const auto ucd = static_cast(mesh.cell_conduit[uc]);
+            gamma += frictionGamma(g, mesh.conduit_roughness[ucd],
+                                   mesh.conduit_rough_factor[ucd],
+                                   state.cell_q[uc], state.cell_a[uc], h_fric);
+            ++ngam;
+        }
+        if (ngam > 0) gamma /= static_cast(ngam);
+
+        const int cl = mesh.face_cl[uf];
+        const int cr = mesh.face_cr[uf];
+        const double qstar0 = 0.5 * (L.q + R.q);
+
+        // Unsteady friction (issue #156): the Vitkovsky local-acceleration
+        // part folds into the SAME semi-implicit denominator steady friction
+        // uses — q^{n+1}·(1 + Δt·γ + k3) = (1+k3)·q* − Δt·gÂ/L·Δη −
+        // Δt·k3·Â·grad — so the implicit path damps exactly as
+        // kernels::ufUpdate does on the explicit path (without this the
+        // fully-pressurized e1 waterhammer is byte-inert under UF, U-G2).
+        // The convective part rides the old-state uf_grad snapshot the
+        // solver precomputed BEFORE this pass. Dead-band and the
+        // half-momentum clamp mirror the kernel, so a discretely-at-rest
+        // deck stays bit-identical; k3 = 0 (or UF off) leaves every
+        // coefficient bit-unchanged (adding 0.0 is exact).
+        double k3 = 0.0, uf_src = 0.0;
+        if (v.opts && v.opts->unsteady_friction != 0 &&
+            v.opts->uf_k3 > 0.0 && v.uf_grad && !v.uf_grad->empty() &&
+            std::fabs(qstar0 / ahat) >= 0.01 /* ft/s dead-band */) {
+            k3 = v.opts->uf_k3;
+            double gterm = 0.0;
+            if (cl >= 0 && cr >= 0) {
+                const auto ucl = static_cast(cl);
+                const auto ucr = static_cast(cr);
+                if (mesh.cell_conduit[ucl] == mesh.cell_conduit[ucr])
+                    gterm = 0.5 * ((*v.uf_grad)[ucl] + (*v.uf_grad)[ucr]);
+                // else: VJ splice — the frames may oppose; drop the
+                // convective part rather than risk an energizing sign
+                // (same rule as the cell stencil, one-sided there).
+            } else if (cl >= 0) {
+                gterm = (*v.uf_grad)[static_cast(cl)];
+            } else if (cr >= 0) {
+                gterm = (*v.uf_grad)[static_cast(cr)];
+            }
+            uf_src = dt * k3 * ahat * gterm;
+            const double cap = 0.5 * std::fabs(qstar0);
+            if (std::fabs(uf_src) > cap)
+                uf_src = (uf_src > 0.0) ? cap : -cap;
+        }
+
+        F.alpha = 1.0 / (1.0 + dt * gamma + k3);
+        F.cond  = F.alpha * dt * k::kGravity * ahat / Lf;
+        F.qstar = qstar0 * (1.0 + k3) - uf_src;
+
+        // Time-n heads / Dirichlet values of each side.
+        const int nd = mesh.face_node[uf];
+        F.eta_l = (cl >= 0) ? v.cell_eta[static_cast(cl)]
+                            : state.node_head[static_cast(nd)];
+        F.eta_r = (cr >= 0) ? v.cell_eta[static_cast(cr)]
+                            : state.node_head[static_cast(nd)];
+        F.dir_l = F.eta_l;
+        F.dir_r = F.eta_r;
+    }
+
+    // ---- assemble + solve, with a bounded demote-and-re-solve loop --------
+    // A folded junction whose solved head violates its physical ceiling (or
+    // floor) is demoted to a Dirichlet row at the clamp and the system is
+    // re-solved; the flux imbalance that creates lands in the carry ledger,
+    // where settleAlgebraicNode books flooding/ponding exactly as today.
+    auto solvePass = [&]() {
+        unk_dirichlet_.assign(unu, 0);
+        unk_dirvalue_.assign(unu, 0.0);
+        for (int pass = 0; pass < 4; ++pass) {
+            assembleRhs(v, dt);
+            buildComponents();
+            const int ncomp =
+                static_cast(comp_ptr_.empty() ? 0 : comp_ptr_.size() - 1);
+            for (int cidx = 0; cidx < ncomp; ++cidx)
+                solveComponent(cidx, v, dt);
+
+            bool violated = false;
+            for (int u = 0; u < nu; ++u) {
+                const auto uu = static_cast(u);
+                if (unk_dirichlet_[uu]) continue;
+                const int ent = unk_entity_[uu];
+                if (ent < mesh.n_cells()) continue;
+                const int n = ent - mesh.n_cells();
+                // TPA (issue #156 Phase 5): a SEALED folded junction inside
+                // a pressurized column carries sub-atmospheric head —
+                // demoting it to a Dirichlet row AT THE INVERT is what broke
+                // the sealed drawdown column under FV_PRESSURIZED_IMPLICIT
+                // (measured |TA−TB| 3.743 vs 0.003 explicit). Extend the
+                // floor by the column-separation bound, mirroring
+                // solveAlgebraicNode.
+                double lo = mesh.node_invert[static_cast(n)];
+                if (!state.cell_tpa.empty() &&
+                    mesh.node_sur_depth[static_cast(n)] > 0.0)
+                    lo -= 35.0;
+                const double hi = nodeCeiling(mesh, n);
+                if (unk_head_[uu] > hi) {
+                    unk_dirichlet_[uu] = 1;
+                    unk_dirvalue_[uu] = hi;
+                    violated = true;
+                } else if (unk_head_[uu] < lo) {
+                    unk_dirichlet_[uu] = 1;
+                    unk_dirvalue_[uu] = lo;
+                    violated = true;
+                }
+            }
+            if (!violated) break;
+        }
+    };
+    solvePass();
+
+    // ---- secant correction of the storage linearization --------------------
+    // The storage row above is the TANGENT dA/dh at the old depth, but the
+    // mass update that follows is exact: a cell rising through the crown
+    // realizes Δh = ΔA / T(new), not ΔA / T(old). Below a closed crown T
+    // falls to the slot width — the exact circle's width vanishes like
+    // √(y_full − h) — so a single tangent step overshoots into the slot and
+    // the realized head spikes by ΔA / t_slot (measured on the e2 rapid-fill
+    // implicit cell with the exact-geometry closure: single-substep spikes to
+    // 0.98 m against 0.37 m; e3 at c = 300 m/s diverged to 31 m). The legacy
+    // 51-row table hid this because its last chord kept dA/dh ≥ ~0.15·D
+    // right up to the crown. Picard corrections: re-solve with each cell's
+    // storage set to the SECANT of its own closure between the old depth and
+    // the latest predicted one (Casulli & Zanolli's nested iteration on the
+    // nonlinear wet area), until the predicted heads stop moving. One secant
+    // step toward a wild tangent prediction over-stiffens the crown cell and
+    // the front creeps (bore arrival 75 s at c = 660 against 45 s at
+    // c = 150), so the iteration is carried further. CAVEAT (measured
+    // 2026-09-11): on stiff slots (t_slot ~ 1e-4 ft²) this Picard map does
+    // NOT contract — the e2 c = 50 spike reads 1.17 / 1.41 / 0.38 / 0.98 m at
+    // 1 / 2 / 3 / 4 passes, and ½-under-relaxation does not cure it — so
+    // three passes is the best measured point, not a converged solve. The
+    // converged remedy is a Newton iteration on the nonlinear storage with a
+    // monotone line search (Casulli–Zanolli's nested Newton); until it lands
+    // the UF ring relation at c = 1000 ft/s does not hold under the exact
+    // closure (ValveClosureDampsOnImplicitPath). A cell that stays on the
+    // slot line keeps t_slot exactly, so a fully pressurized column re-solves
+    // to the same heads; TPA-flagged rows keep their regime width.
+    {
+        // Development knob for the follow-up on the nonlinear storage
+        // (see the caveat above): number of secant passes, default 3.
+        static const int kSecantPasses = [] {
+            const char* e = std::getenv("OPENSWMM_FV_PRESS_SECANT_PASSES");
+            return e ? std::atoi(e) : 3;
+        }();
+        std::vector eta_prev(unu, 0.0);
+        for (int it = 0; it < kSecantPasses; ++it) {
+            bool changed = false;
+            double move = 0.0;
+            for (int u = 0; u < nu; ++u) {
+                const auto uu = static_cast(u);
+                const int ent = unk_entity_[uu];
+                if (ent >= mesh.n_cells()) continue;
+                const auto uc = static_cast(ent);
+                if (!state.cell_tpa.empty() && state.cell_tpa[uc] != 0) continue;
+                const FvGeometry& g =
+                    mesh.geom[static_cast(mesh.cell_geom[uc])];
+                const double h0 = state.cell_h[uc];
+                const double eta1 =
+                    unk_dirichlet_[uu] ? unk_dirvalue_[uu] : unk_head_[uu];
+                if (it > 0) move = std::max(move, std::fabs(eta1 - eta_prev[uu]));
+                eta_prev[uu] = eta1;
+                double h1 = h0 + (eta1 - unk_eta0_[uu]);
+                if (h1 < 0.0) h1 = 0.0;
+                if (h0 >= g.y_full && h1 >= g.y_full) continue;   // slot: T = t_slot
+                const double dh = h1 - h0;
+                if (std::fabs(dh) <= 1.0e-12 * g.y_full) continue;
+                const double T_sec =
+                    std::max((k::areaOfDepth(g, h1) - k::areaOfDepth(g, h0)) / dh,
+                             1.0e-12);
+                unk_store_[uu] = T_sec * mesh.cell_dx[uc] / dt;
+                changed = true;
+            }
+            if (!changed) break;
+            if (it > 0 && move <= 1.0e-9) break;   // ft — predictions converged
+            solvePass();
+        }
+    }
+
+    backSubstitute(v);
+
+    // Folded junction heads: the solve owns them (updateNodes leaves
+    // algebraic heads alone, and settleAlgebraicNode never recomputes one).
+    for (int u = 0; u < nu; ++u) {
+        const auto uu = static_cast(u);
+        const int ent = unk_entity_[uu];
+        if (ent < mesh.n_cells()) continue;
+        const auto un = static_cast(ent - mesh.n_cells());
+        state.node_head[un] =
+            unk_dirichlet_[uu] ? unk_dirvalue_[uu] : unk_head_[uu];
+    }
+}
+
+void PressurizedHeadSolver::assembleRhs(const PressurizedView& v, double dt) {
+    (void)v;
+    (void)dt;
+    const int nu = static_cast(unk_entity_.size());
+    diag_.assign(static_cast(nu), 0.0);
+    rhs_.assign(static_cast(nu), 0.0);
+
+    for (int u = 0; u < nu; ++u) {
+        const auto uu = static_cast(u);
+        if (unk_dirichlet_[uu]) {
+            diag_[uu] = 1.0;
+            rhs_[uu] = unk_dirvalue_[uu];
+            continue;
+        }
+        diag_[uu] = unk_store_[uu];
+        rhs_[uu] = unk_store_[uu] * unk_eta0_[uu] + unk_rhs_ext_[uu];
+    }
+
+    for (const ImpFace& F : imp_faces_) {
+        if (F.cond <= 0.0) continue;
+        // Base flux — the Casulli predictor (the implicit set is FULL
+        // faces only; transition faces never reach this assembly).
+        const double base = F.alpha * F.qstar;
+        const bool ul = F.unk_l >= 0 &&
+                        !unk_dirichlet_[static_cast(F.unk_l)];
+        const bool ur = F.unk_r >= 0 &&
+                        !unk_dirichlet_[static_cast(F.unk_r)];
+        const double val_l =
+            (F.unk_l >= 0)
+                ? (ul ? 0.0
+                      : unk_dirvalue_[static_cast(F.unk_l)])
+                : F.dir_l;
+        const double val_r =
+            (F.unk_r >= 0)
+                ? (ur ? 0.0
+                      : unk_dirvalue_[static_cast(F.unk_r)])
+                : F.dir_r;
+
+        if (ul) {
+            const auto lu = static_cast(F.unk_l);
+            diag_[lu] += F.cond;
+            rhs_[lu] -= base;
+            if (!ur) rhs_[lu] += F.cond * val_r;
+        }
+        if (ur) {
+            const auto ru = static_cast(F.unk_r);
+            diag_[ru] += F.cond;
+            rhs_[ru] += base;
+            if (!ul) rhs_[ru] += F.cond * val_l;
+        }
+    }
+}
+
+void PressurizedHeadSolver::buildComponents() {
+    const int nu = static_cast(unk_entity_.size());
+    // Component ids via union-find roots, compacted in ascending root order
+    // for a deterministic solve order.
+    comp_ptr_.clear();
+    comp_unks_.clear();
+    unk_comp_.assign(static_cast(nu), -1);
+
+    std::vector roots;
+    roots.reserve(static_cast(nu));
+    for (int u = 0; u < nu; ++u) roots.push_back(ufFind(u));
+
+    std::vector order(static_cast(nu));
+    for (int u = 0; u < nu; ++u) order[static_cast(u)] = u;
+    std::sort(order.begin(), order.end(), [&](int a, int b) {
+        const int ra = roots[static_cast(a)];
+        const int rb = roots[static_cast(b)];
+        return (ra != rb) ? ra < rb : a < b;
+    });
+
+    int prev_root = -1;
+    for (const int u : order) {
+        const int r = roots[static_cast(u)];
+        if (r != prev_root) {
+            comp_ptr_.push_back(static_cast(comp_unks_.size()));
+            prev_root = r;
+        }
+        unk_comp_[static_cast(u)] =
+            static_cast(comp_ptr_.size()) - 1;
+        comp_unks_.push_back(u);
+    }
+    comp_ptr_.push_back(static_cast(comp_unks_.size()));
+
+    // Global adjacency (CSR over unknowns) from the FULL both-unknown faces.
+    const auto unu = static_cast(nu);
+    degree_.assign(unu, 0);
+    for (const ImpFace& F : imp_faces_) {
+        if (F.cond <= 0.0 || F.unk_l < 0 || F.unk_r < 0) continue;
+        ++degree_[static_cast(F.unk_l)];
+        ++degree_[static_cast(F.unk_r)];
+    }
+    adj_ptr_.assign(unu + 1, 0);
+    for (std::size_t u2 = 0; u2 < unu; ++u2)
+        adj_ptr_[u2 + 1] = adj_ptr_[u2] + degree_[u2];
+    adj_idx_.assign(static_cast(adj_ptr_[unu]), -1);
+    adj_c_.assign(static_cast(adj_ptr_[unu]), 0.0);
+    std::vector fill(unu, 0);
+    for (const ImpFace& F : imp_faces_) {
+        if (F.cond <= 0.0 || F.unk_l < 0 || F.unk_r < 0) continue;
+        const auto lu = static_cast(F.unk_l);
+        const auto ru = static_cast(F.unk_r);
+        adj_idx_[static_cast(adj_ptr_[lu] + fill[lu])] = F.unk_r;
+        adj_c_[static_cast(adj_ptr_[lu] + fill[lu])] = F.cond;
+        ++fill[lu];
+        adj_idx_[static_cast(adj_ptr_[ru] + fill[ru])] = F.unk_l;
+        adj_c_[static_cast(adj_ptr_[ru] + fill[ru])] = F.cond;
+        ++fill[ru];
+    }
+}
+
+void PressurizedHeadSolver::solveComponent(int comp, const PressurizedView& v,
+                                           double dt) {
+    (void)v;
+    (void)dt;
+    const int b = comp_ptr_[static_cast(comp)];
+    const int e = comp_ptr_[static_cast(comp) + 1];
+    const int n = e - b;
+    if (n <= 0) return;
+
+    // Demoted (Dirichlet) rows solve trivially; edges to them were folded
+    // into neighbours' RHS at assembly. They still occupy a slot here so the
+    // indexing stays uniform.
+    auto isDir = [&](int u) {
+        return unk_dirichlet_[static_cast(u)] != 0;
+    };
+    auto edgeActive = [&](int a2, int b2) { return !isDir(a2) && !isDir(b2); };
+
+    if (n == 1) {
+        const int u = comp_unks_[static_cast(b)];
+        const auto uu = static_cast(u);
+        unk_head_[uu] = (diag_[uu] > 0.0) ? rhs_[uu] / diag_[uu]
+                                          : unk_eta0_[uu];
+        return;
+    }
+
+    // Path test: within the component every unknown has adjacency degree ≤ 2
+    // (counting only active edges) and the active edge count is n_active−1.
+    int m_edges = 0;
+    bool path = true;
+    int endpoint = -1;
+    for (int p = b; p < e; ++p) {
+        const int u = comp_unks_[static_cast(p)];
+        if (isDir(u)) continue;
+        int deg = 0;
+        for (int a2 = adj_ptr_[static_cast(u)];
+             a2 < adj_ptr_[static_cast(u) + 1]; ++a2)
+            if (edgeActive(u, adj_idx_[static_cast(a2)])) ++deg;
+        m_edges += deg;
+        if (deg > 2) path = false;
+        if (deg <= 1 && endpoint < 0) endpoint = u;
+    }
+    m_edges /= 2;
+
+    // Collect the active unknowns of this component.
+    std::vector act;
+    act.reserve(static_cast(n));
+    for (int p = b; p < e; ++p) {
+        const int u = comp_unks_[static_cast(p)];
+        if (!isDir(u)) act.push_back(u);
+    }
+    if (act.empty()) return;
+    if (m_edges != static_cast(act.size()) - 1) path = false;
+
+    if (path && endpoint >= 0) {
+        // Order the path from an endpoint and run Thomas — exact, O(n).
+        path_order_.clear();
+        path_order_.reserve(act.size());
+        int prev = -1, cur = endpoint;
+        while (cur >= 0) {
+            path_order_.push_back(cur);
+            int next = -1;
+            for (int a2 = adj_ptr_[static_cast(cur)];
+                 a2 < adj_ptr_[static_cast(cur) + 1]; ++a2) {
+                const int w = adj_idx_[static_cast(a2)];
+                if (w == prev || !edgeActive(cur, w)) continue;
+                next = w;
+                break;
+            }
+            prev = cur;
+            cur = next;
+        }
+        const int np = static_cast(path_order_.size());
+        if (np == static_cast(act.size())) {
+            thom_b_.assign(static_cast(np), 0.0);
+            thom_a_.assign(static_cast(np), 0.0);
+            thom_c_.assign(static_cast(np), 0.0);
+            thom_d_.assign(static_cast(np), 0.0);
+            for (int i = 0; i < np; ++i) {
+                const int u = path_order_[static_cast(i)];
+                thom_b_[static_cast(i)] =
+                    diag_[static_cast(u)];
+                thom_d_[static_cast(i)] =
+                    rhs_[static_cast(u)];
+                if (i + 1 < np) {
+                    const int w = path_order_[static_cast(i) + 1];
+                    double cval = 0.0;
+                    for (int a2 = adj_ptr_[static_cast(u)];
+                         a2 < adj_ptr_[static_cast(u) + 1]; ++a2)
+                        if (adj_idx_[static_cast(a2)] == w)
+                            cval += adj_c_[static_cast(a2)];
+                    thom_c_[static_cast(i)] = -cval;
+                    thom_a_[static_cast(i) + 1] = -cval;
+                }
+            }
+            for (int i = 1; i < np; ++i) {
+                const double w =
+                    thom_a_[static_cast(i)] /
+                    thom_b_[static_cast(i) - 1];
+                thom_b_[static_cast(i)] -=
+                    w * thom_c_[static_cast(i) - 1];
+                thom_d_[static_cast(i)] -=
+                    w * thom_d_[static_cast(i) - 1];
+            }
+            double x = thom_d_[static_cast(np - 1)] /
+                       thom_b_[static_cast(np - 1)];
+            unk_head_[static_cast(
+                path_order_[static_cast(np - 1)])] = x;
+            for (int i = np - 2; i >= 0; --i) {
+                x = (thom_d_[static_cast(i)] -
+                     thom_c_[static_cast(i)] * x) /
+                    thom_b_[static_cast(i)];
+                unk_head_[static_cast(
+                    path_order_[static_cast(i)])] = x;
+            }
+            return;
+        }
+        // Walk failed to cover the component (shouldn't happen for a true
+        // path) — fall through to CG.
+    }
+
+    // Jacobi-preconditioned CG on the component — SPD by construction.
+    const std::size_t na = act.size();
+    cg_r_.assign(na, 0.0);
+    cg_p_.assign(na, 0.0);
+    cg_ap_.assign(na, 0.0);
+    cg_z_.assign(na, 0.0);
+    std::vector lidx(unk_entity_.size(), -1);
+    for (std::size_t i = 0; i < na; ++i)
+        lidx[static_cast(act[i])] = static_cast(i);
+
+    std::vector x(na);
+    for (std::size_t i = 0; i < na; ++i)
+        x[i] = unk_eta0_[static_cast(act[i])];
+
+    auto matvec = [&](const std::vector& in, std::vector& out) {
+        for (std::size_t i = 0; i < na; ++i) {
+            const int u = act[i];
+            double s = diag_[static_cast(u)] * in[i];
+            for (int a2 = adj_ptr_[static_cast(u)];
+                 a2 < adj_ptr_[static_cast(u) + 1]; ++a2) {
+                const int w = adj_idx_[static_cast(a2)];
+                if (isDir(w)) continue;
+                const int lw = lidx[static_cast(w)];
+                if (lw < 0) continue;
+                s -= adj_c_[static_cast(a2)] *
+                     in[static_cast(lw)];
+            }
+            out[i] = s;
+        }
+    };
+
+    matvec(x, cg_ap_);
+    double bnorm = 0.0;
+    for (std::size_t i = 0; i < na; ++i) {
+        cg_r_[i] = rhs_[static_cast(act[i])] - cg_ap_[i];
+        bnorm += rhs_[static_cast(act[i])] *
+                 rhs_[static_cast(act[i])];
+    }
+    const double tol2 = std::max(1.0e-24 * bnorm, 1.0e-28);
+    double rz = 0.0;
+    for (std::size_t i = 0; i < na; ++i) {
+        cg_z_[i] = cg_r_[i] / diag_[static_cast(act[i])];
+        rz += cg_r_[i] * cg_z_[i];
+        cg_p_[i] = cg_z_[i];
+    }
+    const int itmax = 200 + 2 * static_cast(na);
+    for (int it = 0; it < itmax; ++it) {
+        double r2 = 0.0;
+        for (std::size_t i = 0; i < na; ++i) r2 += cg_r_[i] * cg_r_[i];
+        if (r2 <= tol2) break;
+        matvec(cg_p_, cg_ap_);
+        double pap = 0.0;
+        for (std::size_t i = 0; i < na; ++i) pap += cg_p_[i] * cg_ap_[i];
+        if (!(pap > 0.0)) break;
+        const double a2 = rz / pap;
+        for (std::size_t i = 0; i < na; ++i) {
+            x[i] += a2 * cg_p_[i];
+            cg_r_[i] -= a2 * cg_ap_[i];
+        }
+        double rz_new = 0.0;
+        for (std::size_t i = 0; i < na; ++i) {
+            cg_z_[i] = cg_r_[i] / diag_[static_cast(act[i])];
+            rz_new += cg_r_[i] * cg_z_[i];
+        }
+        const double beta = (rz > 0.0) ? rz_new / rz : 0.0;
+        rz = rz_new;
+        for (std::size_t i = 0; i < na; ++i)
+            cg_p_[i] = cg_z_[i] + beta * cg_p_[i];
+    }
+    for (std::size_t i = 0; i < na; ++i)
+        unk_head_[static_cast(act[i])] = x[i];
+}
+
+void PressurizedHeadSolver::backSubstitute(const PressurizedView& v) {
+    auto headOf = [&](int unk, double dirval) {
+        if (unk < 0) return dirval;
+        const auto uu = static_cast(unk);
+        return unk_dirichlet_[uu] ? unk_dirvalue_[uu] : unk_head_[uu];
+    };
+    for (const ImpFace& F : imp_faces_) {
+        if (F.cond <= 0.0) continue;
+        const auto uf = static_cast(F.face);
+        const double base = F.alpha * F.qstar;
+        const double hl = headOf(F.unk_l, F.dir_l);
+        const double hr = headOf(F.unk_r, F.dir_r);
+        const double q = base - F.cond * (hr - hl);
+        v.f_mass[uf] = q;
+        // Keep the species-facing copies coherent: transport rides the SAME
+        // mass flux the water used, and the contact sign selects its upwind
+        // side (plan §3.2).
+        v.f_flux[uf].mass = q;
+        v.f_flux[uf].sstar = q;
+        v.f_sstar[uf] = q;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// finalizeCells — slave the pressurized cells' momentum to the face solve
+// ---------------------------------------------------------------------------
+
+void PressurizedHeadSolver::finalizeCells(const PressurizedView& v) {
+    if (imp_faces_.empty()) return;
+    const NetworkMeshData& mesh = *v.mesh;
+    NetworkStateData& state = *v.state;
+    const int nc = mesh.n_cells();
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        if (cell_unk_[uc] < 0 || !cell_press_[uc]) continue;
+        const int faces[2] = {mesh.cell_face0[uc], mesh.cell_face1[uc]};
+        const std::int8_t sides[2] = {mesh.cell_side0[uc], mesh.cell_side1[uc]};
+        double q_thru = 0.0;
+        for (int e2 = 0; e2 < 2; ++e2) {
+            const auto uf = static_cast(faces[e2]);
+            const double fa = v.f_mass[uf];
+            q_thru += (sides[e2] == 0)
+                          ? static_cast(mesh.face_dir_l[uf]) * fa
+                          : static_cast(mesh.face_dir_r[uf]) * fa;
+        }
+        const double a = state.cell_a[uc];
+        const double q = 0.5 * q_thru;
+        state.cell_q[uc] = q;
+        v.cell_u[uc] = (a > k::kDryArea) ? q / a : 0.0;
+    }
+}
+
+} // namespace openswmm::fv
diff --git a/src/engine/hydraulics/fv/PressurizedHeadSolver.hpp b/src/engine/hydraulics/fv/PressurizedHeadSolver.hpp
new file mode 100644
index 000000000..68411b8e4
--- /dev/null
+++ b/src/engine/hydraulics/fv/PressurizedHeadSolver.hpp
@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file PressurizedHeadSolver.hpp
+ * @brief Implicit acoustic/slot head update on the pressurized subset
+ *        (slot program R2a, Strategy E).
+ *
+ * @details Above the taper band the Preissmann-slot closure is linear in head
+ *          (A = a_crown + t_slot·(h − y_full)), so the acoustic pair — slot
+ *          storage T·∂H/∂t against the pressure gradient g·A·∂H/∂x — is a
+ *          LINEAR diffusion system in H that can be integrated implicitly
+ *          (θ = 1), unconditionally stably. Everything else stays exactly the
+ *          explicit Godunov scheme: membership is a pure function of the
+ *          instantaneous state (h ≥ y_crown, band entry — no flags, no
+ *          memory) — EXCEPT under the TPA closure (issue #156), where
+ *          membership IS the regime flag (physical air-pathway history,
+ *          cleared on cold start and hotstart restore; see cellPressurized
+ *          below — the SLOT-closure path above is untouched). The flag is
+ *          fixed within a substep, so the SPD structure is unchanged either
+ *          way — and the solve is a FLUX PREDICTOR whose back-substituted
+ *          face discharges overwrite `f_mass_`, the single array both the
+ *          cell update and the node update read — so conservation, rollback,
+ *          hot start and reporting are structurally untouched.
+ *
+ *          Per implicit face (α = 1/(1 + Δt·γ_f), friction semi-implicit as
+ *          everywhere else in the scheme):
+ *
+ *            Q_f^{n+1} = α·Q*_f − C_f·(H_b − H_a),   C_f = α·Δt·g·Â_f/L_f
+ *
+ *          and eliminating Q from each pressurized cell's continuity gives
+ *
+ *            (T_i·Δx_i/Δt)·H_i + Σ_f C_f·(H_i − H_nbr) = RHS_i
+ *
+ *          — symmetric, diagonally dominant with strictly positive cell
+ *          diagonals: SPD per pressurized component. Chains solve by the
+ *          Thomas algorithm; components with a degree-≥3 folded junction by
+ *          Jacobi-preconditioned CG.
+ *
+ *          Face taxonomy (re-derived every substep; memoryless under SLOT,
+ *          flag-consistent under TPA via cellPressurized/ghostPressurized):
+ *            FULL   — both sides pressurized (cell–cell, or cell–node with a
+ *                     pressurized ghost). The Casulli-form flux above; at
+ *                     steady state it reduces to ΔH/L = −S_f exactly, which
+ *                     is what makes full-bore head loss independent of the
+ *                     slot width (gate G1).
+ *            DELTA  — exactly one side pressurized: the TRANSITION face.
+ *                     Stays FULLY explicit — Godunov mass and momentum flux,
+ *                     and the full explicit census bound. Bores live here,
+ *                     and a filling front advanced at the implicit Δt moves
+ *                     one cell per substep regardless of physics (measured:
+ *                     arrival 65 s / 345 s at c = 150 / 660 against the
+ *                     explicit 115 s). Keeping the front explicit costs dt
+ *                     only WHILE a front exists; a fully pressurized network
+ *                     has no transition faces and runs advection-bound,
+ *                     which is where the R2 runtime win lives. (Giving
+ *                     standing fronts their own fine tier is R2b's job.)
+ *            (none) — gated, culvert-capped and closed-end faces are never
+ *                     implicit: their laws stand and enter the pressurized
+ *                     rows as explicit constants.
+ *
+ *          Pressurized ALGEBRAIC junctions are folded in as unknown rows
+ *          (zero storage — today's algebraic convention — plus the face
+ *          conductances), because lagging their heads would re-create the
+ *          ghost-feedback stiffness this solver exists to delete. Fixed-head
+ *          nodes and storage/demoted nodes enter as Dirichlet data at their
+ *          current heads. A folded row whose solved head violates the node's
+ *          physical ceiling (rim + surcharge depth) or floor (invert) is
+ *          demoted to a Dirichlet row at the clamp and the affected
+ *          components re-solved once — the flux imbalance then lands in the
+ *          node's carry ledger, where settleAlgebraicNode already books
+ *          flooding and ponding exactly as before.
+ *
+ * @see plans/FV_SLOT_STORAGE_PROGRAM_2026-08-24.md §R2
+ * @ingroup engine_fv
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_FV_PRESSURIZED_HEAD_SOLVER_HPP
+#define OPENSWMM_ENGINE_FV_PRESSURIZED_HEAD_SOLVER_HPP
+
+#include 
+#include 
+
+#include "FvKernels.hpp"
+#include "INetworkSolver.hpp"
+#include "NetworkMeshData.hpp"
+
+namespace openswmm::fv {
+
+/// Non-owning view of the solver internals the implicit pass reads and
+/// writes. Same pattern as transport's SpeciesKernelView: the pass stays a
+/// separate module without widening ExplicitFvSolver's friend surface.
+struct PressurizedView {
+    const NetworkMeshData*  mesh    = nullptr;
+    NetworkStateData*       state   = nullptr;
+    const FvOptions*        opts    = nullptr;
+    const FvStepForcing*    forcing = nullptr;
+
+    // Face scratch (owned by ExplicitFvSolver).
+    double*              f_mass    = nullptr;
+    double*              f_sstar   = nullptr;
+    kernels::FaceState*  f_state_l = nullptr;
+    kernels::FaceState*  f_state_r = nullptr;
+    kernels::FaceFlux*   f_flux    = nullptr;
+
+    // Cell scratch.
+    const double* cell_eta = nullptr;
+    double*       cell_u   = nullptr;
+
+    /// Unsteady-friction convective term c·sgn(Vⁿ)·|∂V/∂x|ⁿ per cell
+    /// (issue #156), precomputed by ExplicitFvSolver::computeUfGradients from
+    /// the old-state snapshot BEFORE solve() runs. Null/empty when
+    /// FvOptions::unsteady_friction == 0.
+    const std::vector* uf_grad = nullptr;
+
+    const std::vector*  active_faces = nullptr;
+    const std::vector* cell_active  = nullptr;
+
+    // Node machinery (owned by ExplicitFvSolver).
+    const std::vector*       node_qstruct = nullptr;
+    std::vector*             node_carry   = nullptr;
+    const std::vector* node_alg     = nullptr;
+    const std::vector*       node_vfull   = nullptr;
+    const std::vector* node_lat_div = nullptr;
+    const std::vector*       cell_qlat    = nullptr;
+};
+
+class PressurizedHeadSolver {
+public:
+    /// Face treatment decided by classify(). Values are load-bearing for the
+    /// assembly switch; kNone faces are untouched.
+    ///   kFull  — both sides pressurized: Casulli form (steady state reduces
+    ///            to ΔH/L = −S_f exactly — the head-loss invariance gate).
+    ///   kDelta — a transition face (exactly one side pressurized, with a
+    ///            pressurized CELL side). CLASSIFICATION ONLY in R2a: the
+    ///            face stays fully explicit — Godunov flux and census bound.
+    ///            Folding transitions in was built and MEASURED before being
+    ///            cut: every memoryless fold (frozen-ghost delta form, free
+    ///            cell as a soft unknown, free-side depth thresholds at 0.05
+    ///            and 0.5·y_full) re-times an ADVANCING fill — bore arrival
+    ///            65/345 s, 60/545 s, 75/1320 s at c = 150/660 against the
+    ///            42 s quasi-steady analytic — because any instantaneous
+    ///            threshold is swept through transiently while a cell fills.
+    ///            A STANDING transition (backwater below an internal jump)
+    ///            is only distinguishable by cadence, so releasing its
+    ///            census throttle belongs to the LTS composition (R2b),
+    ///            which can put the front on its own fine tier.
+    ///   kNone  — everything else: gated/culvert faces (their laws stand),
+    ///            closed ends, and faces with no pressurized CELL side (a
+    ///            pressurized ghost against a free cell is the classic
+    ///            manhole bore).
+    enum : std::uint8_t { kNone = 0, kFull = 1, kDelta = 2 };
+
+    /// Re-derive the pressurized subset from the instantaneous state:
+    /// pressurized cells, implicit faces with their mode, folded junction
+    /// rows and the component partition. Returns true when at least one
+    /// implicit face exists (i.e. solve() has work).
+    bool classify(const PressurizedView& v);
+
+    /// Assemble and solve the SPD head system per component, then overwrite
+    /// the implicit faces' entries in f_mass (and the species-facing copies
+    /// f_flux.mass / f_sstar) with the back-substituted discharges, and
+    /// write the folded junctions' heads (ceiling/floor clamped, with a
+    /// one-shot Dirichlet re-solve for violating rows).
+    void solve(const PressurizedView& v, double dt);
+
+    /// Post-update pass: a pressurized cell's momentum state is slaved to
+    /// the solved face discharges (Q_i = mean of its two face fluxes in the
+    /// cell frame) so no explicit acoustic residue survives in the
+    /// collocated Q. Call AFTER updateCells/updateNodes.
+    void finalizeCells(const PressurizedView& v);
+
+    /// Folded-node mask from the last classify() — relaxNodeFluxes must skip
+    /// these (their continuity is a row of the implicit system).
+    const std::vector& foldedNodes() const noexcept {
+        return node_fold_;
+    }
+
+    bool anyImplicit() const noexcept { return !imp_faces_.empty(); }
+
+    // -- static predicates shared with the census edit ----------------------
+
+    /// Is this cell pressurized (band entry and above) under the R2 rule?
+    /// Under the TPA closure (issue #156: state.cell_tpa non-empty) membership
+    /// IS the regime flag — a latched sub-atmospheric cell sits below y_crown
+    /// yet is exactly the stiff-acoustic case this solver exists for (plan
+    /// §2.2(1)). The flag is fixed within a substep, so the SPD structure and
+    /// the census edit stay consistent.
+    static bool cellPressurized(const NetworkMeshData& mesh,
+                                const NetworkStateData& state, int cell) {
+        const auto uc = static_cast(cell);
+        if (!state.cell_tpa.empty()) return state.cell_tpa[uc] != 0;
+        const FvGeometry& g =
+            mesh.geom[static_cast(mesh.cell_geom[uc])];
+        return !g.is_open && state.cell_h[uc] >= g.y_crown;
+    }
+
+    /// Implicit eligibility and mode of one face, derived from the
+    /// instantaneous state alone — the ONE predicate classify() and the
+    /// census edit share, so the dt bound and the solve can never disagree
+    /// about which faces are covered. Gated and culvert-capped faces are
+    /// never implicit (their laws stand, explicitly); a pressurized ghost
+    /// against a FREE cell is the filling bore and stays explicit too.
+    static std::uint8_t faceModeOf(const NetworkMeshData& mesh,
+                                   const NetworkStateData& state, int f) {
+        const auto uf = static_cast(f);
+        if (mesh.face_gate[uf] != 0) return kNone;
+        if (mesh.face_culvert[uf] >= 0) return kNone;
+        const int cl = mesh.face_cl[uf];
+        const int cr = mesh.face_cr[uf];
+        const int nd = mesh.face_node[uf];
+        if (nd < 0 && (cl < 0 || cr < 0)) return kNone;
+
+        bool pl = false, pr = false, cell_side_press = false;
+        if (cl >= 0) {
+            pl = cellPressurized(mesh, state, cl);
+            cell_side_press = cell_side_press || pl;
+        }
+        if (cr >= 0) {
+            pr = cellPressurized(mesh, state, cr);
+            cell_side_press = cell_side_press || pr;
+        }
+        if (nd >= 0) {
+            const bool gp = ghostPressurized(mesh, state, f);
+            if (cl < 0) pl = gp;
+            if (cr < 0) pr = gp;
+        }
+        if (!cell_side_press) return kNone;
+        return (pl && pr) ? kFull : kDelta;
+    }
+
+    /// Is the node-side ghost of face @p f pressurized?
+    static bool ghostPressurized(const NetworkMeshData& mesh,
+                                 const NetworkStateData& state, int f) {
+        const auto uf = static_cast(f);
+        const int nd = mesh.face_node[uf];
+        if (nd < 0) return false;
+        const int other = (mesh.face_cl[uf] >= 0) ? mesh.face_cl[uf]
+                                                  : mesh.face_cr[uf];
+        if (other < 0) return false;
+        const FvGeometry& g = mesh.geom[static_cast(
+            mesh.cell_geom[static_cast(other)])];
+        if (g.is_open) return false;
+        // TPA (issue #156 Phase 5): a SEALED node against a flagged interior
+        // cell carries the pressurized column at sub-atmospheric head — the
+        // ghost is pressurized even though head < crown (the same rule
+        // faceSide uses for its ghost regime). Without this the sealed
+        // sub-crown junction's faces degrade to kDelta, the fold pass skips
+        // the node, and the implicit path breaks the column (the P4 pinned
+        // known-issue).
+        if (!state.cell_tpa.empty() &&
+            state.cell_tpa[static_cast(other)] != 0 &&
+            mesh.node_sur_depth[static_cast(nd)] > 0.0)
+            return true;
+        const double hg =
+            state.node_head[static_cast(nd)] - mesh.face_zb[uf];
+        return hg >= g.y_crown;
+    }
+
+private:
+    struct ImpFace {
+        int          face  = -1;
+        std::uint8_t mode  = kNone;
+        // Unknown index of each side (-1 = known/Dirichlet). Left/right in
+        // the FACE frame, so the assembly's sign convention is the flux's.
+        int  unk_l = -1;
+        int  unk_r = -1;
+        // Dirichlet head of a known side (valid where unk < 0).
+        double dir_l = 0.0;
+        double dir_r = 0.0;
+        // Time-n heads of both sides (the DELTA form needs them).
+        double eta_l = 0.0;
+        double eta_r = 0.0;
+        double alpha = 1.0;  ///< 1/(1 + Δt·γ_f)
+        double cond  = 0.0;  ///< C_f = α·Δt·g·Â_f/L_f
+        double qstar = 0.0;  ///< predictor (FULL) — face-frame discharge
+    };
+
+    // classify() products, persistent to avoid per-substep allocation.
+    std::vector cell_press_;
+    std::vector node_fold_;
+    std::vector          cell_unk_;   ///< cell → unknown index (-1 none)
+    std::vector          node_unk_;   ///< node → unknown index (-1 none)
+    std::vector      imp_faces_;
+
+    // Unknown table: entity id (cell c → c; node n → n_cells + n), time-n
+    // head, storage coefficient (T·Δx/Δt for cells, 0 for folded junctions —
+    // filled with Δt at solve time), and component id.
+    std::vector    unk_entity_;
+    std::vector unk_eta0_;
+    std::vector unk_store_;  ///< T·Δx for cells (divided by Δt in solve)
+    std::vector unk_rhs_ext_;///< explicit-face + source constants (cfs)
+    std::vector    unk_comp_;
+    std::vector unk_head_;   ///< solution
+
+    // Union-find over unknowns.
+    std::vector uf_parent_;
+    int ufFind(int i);
+    void ufUnion(int a, int b);
+
+    // Per-component scratch.
+    std::vector    comp_ptr_, comp_unks_;
+    std::vector thom_a_, thom_b_, thom_c_, thom_d_;
+    std::vector    path_order_, degree_, adj_ptr_, adj_idx_;
+    std::vector adj_c_;
+    std::vector cg_r_, cg_p_, cg_ap_, cg_z_;
+
+    void buildComponents();
+    void assembleRhs(const PressurizedView& v, double dt);
+    void solveComponent(int comp, const PressurizedView& v, double dt);
+    void backSubstitute(const PressurizedView& v);
+
+    /// Solve one component given the per-unknown diag/rhs and the edge list;
+    /// writes unk_head_. Thomas when the component is a simple path, CG
+    /// otherwise.
+    void linearSolve(const std::vector& unks,
+                     const std::vector& diag,
+                     const std::vector& rhs);
+
+    // diag/rhs assembled per solve (indexed by unknown).
+    std::vector diag_, rhs_;
+    std::vector unk_dirichlet_;  ///< demoted rows (2nd pass)
+    std::vector       unk_dirvalue_;
+};
+
+} // namespace openswmm::fv
+
+#endif // OPENSWMM_ENGINE_FV_PRESSURIZED_HEAD_SOLVER_HPP
diff --git a/src/engine/hydraulics/fv/SectionGeometry.hpp b/src/engine/hydraulics/fv/SectionGeometry.hpp
new file mode 100644
index 000000000..b22088548
--- /dev/null
+++ b/src/engine/hydraulics/fv/SectionGeometry.hpp
@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SectionGeometry.hpp
+ * @brief Exact cross-section geometry — area, top width and wetted perimeter
+ *        as closed forms of the section's defining dimensions.
+ *
+ * @details Build-time only (plan FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11 §2a′):
+ *          the FV closure tables are sampled from these functions, never from
+ *          the legacy 51-row lookup tables, so the solver's geometry is the
+ *          section to interpolation accuracy rather than to table accuracy.
+ *          Full-precision π; no legacy operand-order constraints — this header
+ *          is not under the dynamic-wave bit-parity contract and must not be
+ *          used by the dynamic-wave path.
+ *
+ *          Closed forms exist for CIRCULAR, FORCE_MAIN, FILLED_CIRCULAR,
+ *          RECT_CLOSED, RECT_OPEN, TRAPEZOIDAL, TRIANGULAR, PARABOLIC and
+ *          POWERFUNC (`hasClosedForm`). Every other shape — the composites
+ *          RECT_TRIANG / RECT_ROUND / MOD_BASKET, the table-defined ARCH /
+ *          EGGSHAPED / HORSESHOE / GOTHIC / CATENARY / SEMIELLIPTICAL /
+ *          BASKETHANDLE / SEMICIRCULAR, and the transect shapes IRREGULAR /
+ *          CUSTOM / STREET — is evaluated through the legacy evaluator, whose
+ *          table (or piecewise formula) is that shape's definition. The
+ *          closure built from them still gains the derivative pair T ≡ dA/dh
+ *          and I₁ ≡ ∫A, which the legacy tables lack.
+ *
+ *          HORIZ_ELLIPSE and VERT_ELLIPSE are table-defined on purpose: SWMM's
+ *          elliptical pipes are the standard elliptical concrete-pipe profiles,
+ *          not mathematical ellipses — measured against a true ellipse of the
+ *          same height and width, the legacy 3×4 ft horizontal section carries
+ *          21 % more full area and a different perimeter. Treating them as
+ *          ellipses would silently change what the shape keyword means.
+ *
+ *          Everything here is a plain function over `XSectParams`, host-only
+ *          (`acos`, adaptive quadrature), and may be freely reused by a later
+ *          dynamic-wave program under its own gates.
+ *
+ * @ingroup engine_fv
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_FV_SECTION_GEOMETRY_HPP
+#define OPENSWMM_ENGINE_FV_SECTION_GEOMETRY_HPP
+
+#include 
+#include 
+
+#include "../XSectBatch.hpp"
+
+namespace openswmm::fv::secgeom {
+
+inline constexpr double kPi = 3.14159265358979323846;
+
+/// Legacy `RECT_ALFMAX` (xsect.c): the filling fraction above which a closed
+/// rectangle's wetted perimeter is ramped toward the full-pipe value, so R(h)
+/// reaches r_full continuously instead of jumping at the crown.
+inline constexpr double kRectAlfMax = 0.97;
+
+namespace detail {
+
+/// Circular segment of radius r at water depth y (from the invert).
+inline double circTheta(double r, double y) {
+    double c = 1.0 - y / r;
+    if (c > 1.0) c = 1.0;
+    if (c < -1.0) c = -1.0;
+    return 2.0 * std::acos(c);
+}
+inline double circArea(double r, double y) {
+    if (y <= 0.0) return 0.0;
+    if (y >= 2.0 * r) return kPi * r * r;
+    const double th = circTheta(r, y);
+    return 0.5 * r * r * (th - std::sin(th));
+}
+inline double circWidth(double r, double y) {
+    if (y <= 0.0 || y >= 2.0 * r) return 0.0;
+    const double s = y * (2.0 * r - y);
+    return (s > 0.0) ? 2.0 * std::sqrt(s) : 0.0;
+}
+inline double circPerim(double r, double y) {
+    if (y <= 0.0) return 0.0;
+    if (y >= 2.0 * r) return 2.0 * kPi * r;
+    return r * circTheta(r, y);
+}
+
+/// Adaptive Simpson quadrature — build-time helper for the perimeters that
+/// have no closed form (ellipse arc, power-function arc).
+template 
+double simpsonStep(F& f, double a, double b, double fa, double fm, double fb,
+                   double whole, double eps, int depth) {
+    const double m = 0.5 * (a + b);
+    const double lm = 0.5 * (a + m), rm = 0.5 * (m + b);
+    const double flm = f(lm), frm = f(rm);
+    const double left  = (m - a) / 6.0 * (fa + 4.0 * flm + fm);
+    const double right = (b - m) / 6.0 * (fm + 4.0 * frm + fb);
+    const double delta = left + right - whole;
+    if (depth <= 0 || std::fabs(delta) <= 15.0 * eps)
+        return left + right + delta / 15.0;
+    return simpsonStep(f, a, m, fa, flm, fm, left, 0.5 * eps, depth - 1) +
+           simpsonStep(f, m, b, fm, frm, fb, right, 0.5 * eps, depth - 1);
+}
+template 
+double integrate(F f, double a, double b, double eps = 1.0e-12, int depth = 40) {
+    if (!(b > a)) return 0.0;
+    const double fa = f(a), fb = f(b), fm = f(0.5 * (a + b));
+    const double whole = (b - a) / 6.0 * (fa + 4.0 * fm + fb);
+    return simpsonStep(f, a, b, fa, fm, fb, whole, eps, depth);
+}
+
+/// Wetted perimeter of an ellipse with horizontal semi-axis ax and vertical
+/// semi-axis by, water depth y from the bottom: parametrize the boundary as
+/// x = ax·sin φ, y = by·(1 − cos φ) and integrate the arc length.
+inline double ellipsePerim(double ax, double by, double y) {
+    if (y <= 0.0) return 0.0;
+    double c = 1.0 - y / by;
+    if (c < -1.0) c = -1.0;
+    if (c > 1.0) c = 1.0;
+    const double phi_max = std::acos(c);
+    auto ds = [&](double phi) {
+        const double cx = ax * std::cos(phi), sy = by * std::sin(phi);
+        return std::sqrt(cx * cx + sy * sy);
+    };
+    return 2.0 * integrate(ds, 0.0, phi_max, 1.0e-12 * (ax + by));
+}
+
+} // namespace detail
+
+/// True for the shapes this header evaluates in closed form.
+inline bool hasClosedForm(int type) {
+    switch (static_cast(type)) {
+        case XSectShape::CIRCULAR:
+        case XSectShape::FORCE_MAIN:
+        case XSectShape::FILLED_CIRCULAR:
+        case XSectShape::RECT_CLOSED:
+        case XSectShape::RECT_OPEN:
+        case XSectShape::TRAPEZOIDAL:
+        case XSectShape::TRIANGULAR:
+        case XSectShape::PARABOLIC:
+        case XSectShape::POWERFUNC:
+            return true;
+        default:
+            return false;
+    }
+}
+
+/// True for the open sections whose A(h) is a polynomial of degree ≤ 2 and
+/// whose perimeter is linear in h — the closure's polynomial class, evaluated
+/// in closed form in the hot loop rather than tabulated (plan §2a″).
+inline bool isPolynomialOpen(int type) {
+    switch (static_cast(type)) {
+        case XSectShape::RECT_OPEN:
+        case XSectShape::TRAPEZOIDAL:
+        case XSectShape::TRIANGULAR:
+            return true;
+        default:
+            return false;
+    }
+}
+
+/// Flow area at depth h ∈ [0, y_full] (per barrel).
+inline double areaOfDepth(const XSectParams& xs, double h) {
+    if (h <= 0.0) return 0.0;
+    if (h > xs.y_full) h = xs.y_full;
+    switch (static_cast(xs.type)) {
+        case XSectShape::CIRCULAR:
+        case XSectShape::FORCE_MAIN:
+            return detail::circArea(0.5 * xs.y_full, h);
+        case XSectShape::FILLED_CIRCULAR: {
+            const double r = 0.5 * (xs.y_full + xs.y_bot);
+            return detail::circArea(r, xs.y_bot + h) - detail::circArea(r, xs.y_bot);
+        }
+        case XSectShape::RECT_CLOSED:
+        case XSectShape::RECT_OPEN:
+            return h * xs.w_max;
+        case XSectShape::TRAPEZOIDAL:
+            return (xs.y_bot + xs.s_bot * h) * h;
+        case XSectShape::TRIANGULAR:
+            return xs.s_bot * h * h;
+        case XSectShape::PARABOLIC:
+            return (4.0 / 3.0) * xs.r_bot * h * std::sqrt(h);
+        case XSectShape::POWERFUNC:
+            return xs.r_bot * std::pow(h, xs.s_bot + 1.0);
+        default:
+            return xsect::getAofY(xs, h);
+    }
+}
+
+/// Top width at depth h ∈ [0, y_full] (per barrel). Evaluated AT h = 0 too
+/// (a rectangle is w wide at its invert; a circle 0) — the closure takes it
+/// as the first node's slope, and a spurious 0 there put a w·dh²/12 offset
+/// into every I₁ of a flat-bottomed section. At the crown of a closed
+/// rectangle this is the wall width, not the legacy table's 0 — the crown is a
+/// line, and the closure's slot term is what the solver adds above it.
+inline double widthOfDepth(const XSectParams& xs, double h) {
+    if (h < 0.0) return 0.0;
+    if (h > xs.y_full) h = xs.y_full;
+    switch (static_cast(xs.type)) {
+        case XSectShape::CIRCULAR:
+        case XSectShape::FORCE_MAIN:
+            return detail::circWidth(0.5 * xs.y_full, h);
+        case XSectShape::FILLED_CIRCULAR:
+            return detail::circWidth(0.5 * (xs.y_full + xs.y_bot), xs.y_bot + h);
+        case XSectShape::RECT_CLOSED:
+        case XSectShape::RECT_OPEN:
+            return xs.w_max;
+        case XSectShape::TRAPEZOIDAL:
+            return xs.y_bot + 2.0 * xs.s_bot * h;
+        case XSectShape::TRIANGULAR:
+            return 2.0 * xs.s_bot * h;
+        case XSectShape::PARABOLIC:
+            return 2.0 * xs.r_bot * std::sqrt(h);
+        case XSectShape::POWERFUNC:
+            return (h > 0.0) ? (xs.s_bot + 1.0) * xs.r_bot * std::pow(h, xs.s_bot) : 0.0;
+        default:
+            return xsect::getWofY(xs, h);
+    }
+}
+
+/// Wetted perimeter at depth h ∈ [0, y_full] (per barrel). For shapes without
+/// a closed form it is A/R of the legacy evaluator (R = 0 ⇒ 0).
+inline double perimeterOfDepth(const XSectParams& xs, double h) {
+    if (h <= 0.0) return 0.0;
+    if (h > xs.y_full) h = xs.y_full;
+    switch (static_cast(xs.type)) {
+        case XSectShape::CIRCULAR:
+        case XSectShape::FORCE_MAIN:
+            return detail::circPerim(0.5 * xs.y_full, h);
+        case XSectShape::FILLED_CIRCULAR: {
+            const double r = 0.5 * (xs.y_full + xs.y_bot);
+            // Arc above the sediment plus the flat sediment surface.
+            return detail::circPerim(r, xs.y_bot + h) - detail::circPerim(r, xs.y_bot) +
+                   detail::circWidth(r, xs.y_bot);
+        }
+        case XSectShape::RECT_CLOSED: {
+            double p = xs.w_max + 2.0 * h;
+            const double alf = (xs.a_full > 0.0) ? (h * xs.w_max) / xs.a_full : 0.0;
+            if (alf > kRectAlfMax)
+                p += (alf - kRectAlfMax) / (1.0 - kRectAlfMax) * xs.w_max;
+            return p;
+        }
+        case XSectShape::RECT_OPEN:
+            return xs.w_max + (2.0 - xs.s_bot) * h;
+        case XSectShape::TRAPEZOIDAL:
+            return xs.y_bot + h * xs.r_bot;
+        case XSectShape::TRIANGULAR:
+            return 2.0 * h * xs.r_bot;
+        case XSectShape::PARABOLIC: {
+            const double x = 2.0 * std::sqrt(h) / xs.r_bot;
+            const double t = std::sqrt(1.0 + x * x);
+            return 0.5 * xs.r_bot * xs.r_bot * (x * t + std::log(x + t));
+        }
+        case XSectShape::POWERFUNC: {
+            // Half-width x(y) = hc·y^m; arc length 2∫√(1 + x'(y)²) dy. The
+            // integrand has an integrable singularity at y → 0 when m < 1;
+            // adaptive Simpson from a tiny offset handles it at build time.
+            const double hc = (xs.s_bot + 1.0) * xs.r_bot / 2.0;
+            const double m  = xs.s_bot;
+            auto ds = [&](double y) {
+                const double dxdy = (y > 0.0) ? hc * m * std::pow(y, m - 1.0) : 0.0;
+                return std::sqrt(1.0 + dxdy * dxdy);
+            };
+            const double y0 = 1.0e-9 * h;
+            return 2.0 * (detail::integrate(ds, y0, h, 1.0e-12 * h) +
+                          std::hypot(y0, hc * std::pow(y0, m)));
+        }
+        default: {
+            const double r = xsect::getRofY(xs, h);
+            return (r > 0.0) ? xsect::getAofY(xs, h) / r : 0.0;
+        }
+    }
+}
+
+/// Hydraulic radius A/P at depth h ∈ [0, y_full] (per barrel).
+inline double hydRadOfDepth(const XSectParams& xs, double h) {
+    if (h <= 0.0) return 0.0;
+    if (!hasClosedForm(xs.type)) return xsect::getRofY(xs, std::min(h, xs.y_full));
+    const double p = perimeterOfDepth(xs, h);
+    return (p > 0.0) ? areaOfDepth(xs, h) / p : 0.0;
+}
+
+} // namespace openswmm::fv::secgeom
+
+#endif // OPENSWMM_ENGINE_FV_SECTION_GEOMETRY_HPP
diff --git a/src/engine/hydraulics/xsect_tables.hpp b/src/engine/hydraulics/xsect_tables.hpp
index f65480826..694fc9433 100644
--- a/src/engine/hydraulics/xsect_tables.hpp
+++ b/src/engine/hydraulics/xsect_tables.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file xsect_tables.hpp
  * @brief Cross-section lookup tables — translated from legacy xsect.dat.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_XSECT_TABLES_HPP
diff --git a/src/engine/hydrology/Climate.cpp b/src/engine/hydrology/Climate.cpp
index 096688471..4c9c135a3 100644
--- a/src/engine/hydrology/Climate.cpp
+++ b/src/engine/hydrology/Climate.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Climate.cpp
  * @brief Climate processing — numerically identical to legacy climate.c.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Climate.hpp"
@@ -94,7 +110,10 @@ void updateDailyClimate(ClimateState& state, int day_of_year, int month) {
 
     switch (state.evap_method) {
         case EvapMethod::CONSTANT:
-            // evap_rate already set
+            // legacy setEvap: Evap.rate = monthlyEvap[0] / UCF(EVAPRATE) on
+            // EVERY call, so the monthly adjustment added below is applied
+            // to the constant, not accumulated step after step.
+            state.evap_rate = state.monthly_evap[0] / state.evaprate_ucf;
             break;
 
         case EvapMethod::MONTHLY:
@@ -122,8 +141,13 @@ void updateDailyClimate(ClimateState& state, int day_of_year, int month) {
             break;
     }
 
-    // Apply monthly adjustment
-    state.evap_rate *= state.adjust_evap[month];
+    // Apply monthly adjustment — legacy setEvap: Evap.rate += Adjust.evap[mon-1]
+    // (the [ADJUSTMENTS] EVAP row is a rate ADDED to the source, not a factor).
+    // TIMESERIES and PAN are resolved by the engine's climate step, which
+    // adds the adjustment itself.
+    if (state.evap_method != EvapMethod::TIMESERIES &&
+        state.evap_method != EvapMethod::PAN)
+        state.evap_rate += state.adjust_evap[month];
 
     // Saturation vapor pressure (for snowmelt rain-on-snow)
     double ta = state.temperature;
diff --git a/src/engine/hydrology/Climate.hpp b/src/engine/hydrology/Climate.hpp
index 9b171e798..a5a7da35f 100644
--- a/src/engine/hydrology/Climate.hpp
+++ b/src/engine/hydrology/Climate.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Climate.hpp
  * @brief Climate processing — evaporation, temperature, wind.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CLIMATE_HPP
@@ -91,6 +107,7 @@ struct ClimateState {
 
     // Site elevation for psychrometric constant (matching legacy Temp.elev)
     double elev         = 0.0;   ///< Site elevation above sea level (ft)
+    double snow_divt    = 34.0;  ///< Rain/snow dividing temperature (degF), legacy Snow.snotmp
 
     // Monthly evaporation table (for MONTHLY method)
     double monthly_evap[12] = {};
@@ -101,7 +118,16 @@ struct ClimateState {
     double evaprate_ucf = 1036800.0;
 
     // Monthly adjustment factors
-    double adjust_evap[12]   = {1,1,1,1,1,1,1,1,1,1,1,1};
+    double adjust_evap[12]   = {0,0,0,0,0,0,0,0,0,0,0,0};   ///< ADDED to the rate (ft/s), legacy Adjust.evap /= UCF(EVAPRATE)
+    // Legacy climate.c NextEvapDate / NextEvapRate: the date the evaporation
+    // source next changes (every type — a year ahead for CONSTANT, the first
+    // of next month for MONTHLY, the next series entry for TIMESERIES, the
+    // next day for a climate file) and the rate that entry carries. A
+    // time-series evaporation is STEP-WISE: the rate holds until the date
+    // is reached, and the runoff step never crosses it (runoff_getTimeStep).
+    double next_evap_date = 0.0;
+    double next_evap_rate = 0.0;   ///< user units
+    int    evap_ts_pos    = -1;    ///< index of the last series entry read (legacy table_getNextEntry cursor)
     double adjust_temp[12]   = {0,0,0,0,0,0,0,0,0,0,0,0};
     double adjust_rain[12]   = {1,1,1,1,1,1,1,1,1,1,1,1};
     double adjust_hydcon[12] = {1,1,1,1,1,1,1,1,1,1,1,1}; ///< Infiltration conductivity multipliers
@@ -122,6 +148,7 @@ struct ClimateState {
     // Resolved timeseries/pattern indices (set at init, -1 = none)
     int temp_ts_index     = -1;   ///< Temperature timeseries table index
     int evap_ts_index     = -1;   ///< Evaporation timeseries table index
+    int humidity_ts_index = -1;   ///< Humidity / dew-point timeseries table index
     int recovery_pat_index = -1;  ///< Recovery pattern index in ctx.patterns
 
     // Sub-daily sinusoidal temperature interpolation (Gap #9)
diff --git a/src/engine/hydrology/ClimateFile.cpp b/src/engine/hydrology/ClimateFile.cpp
index fe378bdbb..ee59216d6 100644
--- a/src/engine/hydrology/ClimateFile.cpp
+++ b/src/engine/hydrology/ClimateFile.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ClimateFile.cpp
  * @brief Multi-format climate file reader — faithful to legacy climate.c.
@@ -5,10 +21,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ClimateFile.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "../core/DateTime.hpp"
 #include 
 #include 
@@ -40,7 +57,7 @@ bool ClimateFileReader::open(const std::string& path, double /*start_oa_date*/,
     close();
     unit_system_ = unit_system;
 
-    file_ = std::fopen(path.c_str(), "r");
+    file_ = openswmm::io::fopen_utf8(path, "r");
     if (!file_) return false;
 
     // Read first line for format detection
diff --git a/src/engine/hydrology/ClimateFile.hpp b/src/engine/hydrology/ClimateFile.hpp
index 80a8481c8..1fc6e8345 100644
--- a/src/engine/hydrology/ClimateFile.hpp
+++ b/src/engine/hydrology/ClimateFile.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ClimateFile.hpp
  * @brief Multi-format climate file reader for temperature, evaporation, wind.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_CLIMATE_FILE_HPP
diff --git a/src/engine/hydrology/Gage.cpp b/src/engine/hydrology/Gage.cpp
index b2a509259..ce8b7a18f 100644
--- a/src/engine/hydrology/Gage.cpp
+++ b/src/engine/hydrology/Gage.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Gage.cpp
  * @brief Rain gage processing — numerically identical to legacy gage.c.
@@ -5,13 +21,15 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Gage.hpp"
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
 #include "../core/DateTime.hpp"
+#include "../2d/data/MeshData.hpp"          // S7: gageIsUsed — the mesh reads gages
+#include "../2d/data/SolverOptions2D.hpp"
 #include 
 #include 
 #include 
@@ -63,22 +81,19 @@ PrecipSplit splitPrecip(const SimulationContext& ctx, std::size_t sub) {
     // downstream concern. With snowmelt ignored, ALL precip is treated as rain
     // regardless of temperature.
     const bool is_snowing = !ctx.options.ignore_snow_melt &&
-                            (ctx.climate_state.temperature <= ctx.options.snow_divt);
+                            (ctx.climate_state.temperature <= ctx.climate_state.snow_divt);
 
+    // Legacy order: gage_getPrecip divides by UCF(RAINFALL) first
+    // (gage.c:524-526), then getNetPrecip applies the subcatchment's scale
+    // factor (subcatch.c:789-790).
+    const double ucf_rain = ucf::UCF(ucf::RAINFALL, ctx.options);
     if (is_snowing) {
-        // snowfall = gage_intensity * SCF * subcatch snow scale
-        out.snowfall = intensity
-                     * ctx.gages.snow_factor[ug]
-                     * ctx.subcatches.snow_scale_factor[sub];
+        out.snowfall = intensity * ctx.gages.snow_factor[ug] / ucf_rain;
+        out.snowfall *= ctx.subcatches.snow_scale_factor[sub];
     } else {
-        // rainfall = gage_intensity * subcatch rain scale
-        out.rainfall = intensity * ctx.subcatches.rain_scale_factor[sub];
+        out.rainfall = intensity / ucf_rain;
+        out.rainfall *= ctx.subcatches.rain_scale_factor[sub];
     }
-
-    // Convert to internal units (ft/sec), matching legacy's / UCF(RAINFALL).
-    const double ucf_rain = ucf::UCF(ucf::RAINFALL, ctx.options);
-    out.rainfall /= ucf_rain;
-    out.snowfall /= ucf_rain;
     return out;
 }
 
@@ -107,10 +122,213 @@ double getPastRain(const GageState& state, int hours) {
     return total;
 }
 
+// ---------------------------------------------------------------------------
+// Shared rainfall resolution (see Gage.hpp)
+// ---------------------------------------------------------------------------
+
+const Table* gageRainSeries(const SimulationContext& ctx, int gage_idx) {
+    if (gage_idx < 0 || gage_idx >= ctx.n_gages()) return nullptr;
+    const auto ug = static_cast(gage_idx);
+
+    if (ctx.gages.source[ug] == RainSource::FILE_RAIN) {
+        if (ug < ctx.gages.rain_series.size() && !ctx.gages.rain_series[ug].empty())
+            return &ctx.gages.rain_series[ug];
+        return nullptr;
+    }
+    const int ts_idx = ctx.gages.ts_index[ug];
+    if (ts_idx >= 0 && ts_idx < static_cast(ctx.tables.tables.size()))
+        return &ctx.tables.tables[static_cast(ts_idx)];
+    return nullptr;
+}
+
+double gageUnitsFactor(const SimulationContext& ctx, int gage_idx) {
+    if (gage_idx < 0 || gage_idx >= ctx.n_gages()) return 1.0;
+    const auto ug = static_cast(gage_idx);
+
+    // PARITY: legacy sets Gage.unitsFactor = MMperINCH for SI projects
+    // (gage.c:300) because the rain interface file stores inches. Only the
+    // STANDARD loader reproduces that storage convention — USER_CSV holds
+    // project units directly — so the factor is pinned to the format, which
+    // leaves the legacy path byte-identical.
+    if (ctx.gages.source[ug] == RainSource::FILE_RAIN &&
+        ctx.gages.file_format[ug] == RainFileFormat::STAN_PRCP &&
+        static_cast(ctx.options.flow_units) >= 3)
+        return 25.40;  // legacy MMperINCH (consts.h:389)
+    return 1.0;
+}
+
+double convertGageValue(double raw, int rain_type, double interval_sec,
+                        double& cumul_accum, double units_factor,
+                        double scale_factor) {
+    if (rain_type == 1 && interval_sec > 0.0) {
+        // VOLUME: depth per interval -> in/hr. Match legacy operand order
+        // exactly (gage.c:692): r/interval*3600.0 — one divide then one
+        // multiply, NOT r/(interval/3600.0), which forms a non-representable
+        // constant first and rounds differently.
+        raw = raw / interval_sec * 3600.0;
+    } else if (rain_type == 2 && interval_sec > 0.0) {
+        // CUMULATIVE: a decrease is a counter reset, and the new value is then
+        // the whole interval's depth (legacy convertRainfall).
+        const double depth = (raw < cumul_accum) ? raw : (raw - cumul_accum);
+        cumul_accum = raw;
+        raw = depth / interval_sec * 3600.0;
+    }
+    // INTENSITY (0): already in/hr.
+
+    // PARITY: unitsFactor BEFORE scaleFactor (legacy gage.c:705).
+    return raw * units_factor * scale_factor;
+}
+
+bool gageIsUsed(const SimulationContext& ctx, int gage_idx) {
+    for (int i = 0; i < ctx.n_subcatches(); ++i)
+        if (ctx.subcatches.gage[static_cast(i)] == gage_idx) return true;
+    for (const auto& gname : ctx.unit_hyds.gage_names)
+        if (ctx.gage_names.find(gname) == gage_idx) return true;
+    // S7 (2026-09-19): the 2D mesh reads EVERY gage under RAINFALL_MODE
+    // SYSTEM / NATURAL_NEIGHBOUR (SurfaceRouter2D::updateRainfall). A gage no
+    // subcatchment names kept its seeded first record for the whole run
+    // (legacy's "unused gage" rule), so a rain-on-grid deck with no
+    // subcatchment rained at its first non-zero intensity forever.
+    if (ctx.twod_io.mesh && ctx.twod_io.options &&
+        ctx.twod_io.mesh->n_triangles() > 0 &&
+        ctx.twod_io.options->rainfall_mode != twoD::RainfallMode::NONE)
+        return true;
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Legacy rain-gage state machine — gage.c gage_initState / gage_setState /
+// getNextRainfall / gage_getNextRainDate / gage_setReportRainfall — kept on
+// the gage's series as record indices (GageData::st_*). A record's rate is
+// legacy convertRainfall: VOLUME r / interval * 3600; CUMULATIVE the delta
+// from the previous record (rainAccum is the previous record's raw value,
+// legacy reads the records in order), a decrease being a counter reset;
+// then unitsFactor, then scaleFactor. The monthly rain adjustment is applied
+// by the runoff step afterwards (legacy folds it in at read time).
+// ---------------------------------------------------------------------------
+namespace {
+
+constexpr int    kNoState   = -2;   ///< st_cur: legacy startDate == NO_DATE
+constexpr int    kPreRecord = -1;   ///< st_cur: the [StartDateTime, x0) interval
+constexpr int    kNoDate    = -1;   ///< st_next: legacy nextDate == NO_DATE
+constexpr double kNoDateValue = -693594.0;   ///< legacy NO_DATE (1/1/0001)
+
+double recordRate(const SimulationContext& ctx, int j, const Table& tbl, int k) {
+    const auto uk = static_cast(k);
+    const auto uj = static_cast(j);
+    const int rain_type = ctx.gages.rain_type[uj];
+    const double interval = ctx.gages.interval_sec[uj];
+    double r = tbl.y[uk];
+    if (rain_type == 1 && interval > 0.0) {
+        // one divide then one multiply (gage.c:692), not r/(interval/3600)
+        r = r / interval * 3600.0;
+    } else if (rain_type == 2 && interval > 0.0) {
+        const double prev = (k > 0) ? tbl.y[uk - 1] : 0.0;
+        r = (r < prev) ? (r / interval * 3600.0)
+                       : ((r - prev) / interval * 3600.0);
+    }
+    // unitsFactor BEFORE scaleFactor (gage.c:705)
+    return r * gageUnitsFactor(ctx, j) * ctx.gages.scale_factor[uj];
+}
+
+// getNextRainfall: the next record after `from` whose rate is not zero
+// (explicit zeros — and a cumulative gage's zero deltas — are skipped so the
+// wet/dry accounting sees them as a gap).
+int nextNonzeroRecord(const SimulationContext& ctx, int j, const Table& tbl, int from) {
+    const int n = static_cast(tbl.x.size());
+    for (int k = from + 1; k < n; ++k)
+        if (recordRate(ctx, j, tbl, k) != 0.0) return k;
+    return kNoDate;
+}
+
+// gage_initState (project_init): seeded from the FIRST record whatever its
+// value (getFirstRainfall); a record beginning after the simulation start
+// makes the current interval [StartDateTime, x0) with no rain and record 0
+// the next one. Under IGNORE_RAINFALL legacy returns before reading the
+// series, so there is no state (and no runoff-step limit) at all.
+void initGageState(SimulationContext& ctx, int j, const Table* tbl) {
+    const auto uj = static_cast(j);
+    ctx.gages.st_init[uj] = 1;
+    ctx.gages.st_used[uj] = gageIsUsed(ctx, j) ? 1 : 0;
+    ctx.gages.st_cur[uj]  = kNoState;
+    ctx.gages.st_next[uj] = kNoDate;
+    ctx.gages.st_rain[uj] = 0.0;
+    if (ctx.options.ignore_rainfall) return;
+    if (!tbl || tbl->x.empty()) return;
+    if (tbl->x[0] > ctx.options.start_date) {
+        ctx.gages.st_cur[uj]  = kPreRecord;
+        ctx.gages.st_next[uj] = 0;
+    } else {
+        ctx.gages.st_cur[uj]  = 0;
+        ctx.gages.st_rain[uj] = recordRate(ctx, j, *tbl, 0);
+        ctx.gages.st_next[uj] = nextNonzeroRecord(ctx, j, *tbl, 0);
+    }
+}
+
+// legacy startDate / endDate of the current interval
+void currentInterval(const SimulationContext& ctx, int j, const Table& tbl,
+                     double& start, double& end) {
+    const auto uj = static_cast(j);
+    const int cur = ctx.gages.st_cur[uj];
+    if (cur == kPreRecord) {
+        start = ctx.options.start_date;
+        end   = tbl.x[0];
+    } else {
+        start = tbl.x[static_cast(cur)];
+        end   = datetime::addSeconds(start, ctx.gages.interval_sec[uj]);
+    }
+}
+
+// gage_setState's march (t already carries legacy's +1 s)
+void setGageState(SimulationContext& ctx, int j, const Table& tbl, double t) {
+    const auto uj = static_cast(j);
+    for (;;) {
+        if (ctx.gages.st_cur[uj] == kNoState) { ctx.gages.st_rain[uj] = 0.0; return; }
+        double start, end;
+        currentInterval(ctx, j, tbl, start, end);
+        if (t < start) { ctx.gages.st_rain[uj] = 0.0; return; }   // before the interval
+        if (t < end)   return;                                     // inside it: keep
+        const int nxt = ctx.gages.st_next[uj];
+        if (nxt < 0)   { ctx.gages.st_rain[uj] = 0.0; return; }   // no next interval
+        if (t < tbl.x[static_cast(nxt)]) { ctx.gages.st_rain[uj] = 0.0; return; }
+        ctx.gages.st_cur[uj]  = nxt;                               // advance
+        ctx.gages.st_rain[uj] = recordRate(ctx, j, tbl, nxt);
+        ctx.gages.st_next[uj] = nextNonzeroRecord(ctx, j, tbl, nxt);
+    }
+}
+
+} // namespace
+
+double gageNextRainDate(const SimulationContext& ctx, int gage_idx, double t) {
+    const auto ug = static_cast(gage_idx);
+    if (ug >= ctx.gages.st_cur.size() || !ctx.gages.st_used[ug]) return t;   // legacy: aDate
+    const int cur = ctx.gages.st_cur[ug];
+    const Table* tbl = gageRainSeries(ctx, gage_idx);
+    if (cur == kNoState || !tbl || tbl->x.empty()) return kNoDateValue;
+    const double t1 = t + datetime::OneSecond;
+    double start, end;
+    currentInterval(ctx, gage_idx, *tbl, start, end);
+    if (t1 < start) return start;
+    if (t1 < end)   return end;
+    const int nxt = ctx.gages.st_next[ug];
+    return (nxt >= 0) ? tbl->x[static_cast(nxt)] : kNoDateValue;
+}
+
 void updateAllGages(SimulationContext& ctx, double current_time) {
     // current_time is absolute OADate (days since 12/30/1899) in fractional days
     for (int j = 0; j < ctx.n_gages(); ++j) {
         auto uj = static_cast(j);
+        Table* rtbl = const_cast(gageRainSeries(ctx, j));
+        if (uj < ctx.gages.st_init.size() && !ctx.gages.st_init[uj])
+            initGageState(ctx, j, rtbl);   // legacy gage_initState, once
+
+        // legacy gage_setState returns at once for a gage no subcatchment
+        // or unit-hydrograph group reads; its rainfall keeps the seeded
+        // value (runoff_execute still tests it for IsRaining).
+        if (uj < ctx.gages.st_used.size() && !ctx.gages.st_used[uj]) {
+            ctx.gages.rainfall[uj] = ctx.gages.st_rain[uj];
+            continue;
+        }
 
         // IGNORE_RAINFALL: force this gage's rainfall to zero every step
         // (legacy gage_setState, gage.c:344-347). Zeroing here — ahead of the
@@ -143,107 +361,16 @@ void updateAllGages(SimulationContext& ctx, double current_time) {
             continue;
         }
 
-        // Read gage properties
-        int rain_type = ctx.gages.rain_type[uj];
-        double interval = ctx.gages.interval_sec[uj]; // seconds
-
-        // Look up raw rainfall from timeseries using step-function (piecewise constant).
-        // Matches legacy gage_setState() exactly:
-        //   1. Adds OneSecond offset to time for robust boundary comparison
-        //   2. Rain applies for [entryTime, entryTime + rainInterval)
-        //   3. Returns 0 in gaps between end-of-interval and next entry
-        //   4. Returns 0 after the last time series entry
-        //   5. Uses datetime::addSeconds for interval end computation
-        //      (decompose-recompose via integer H:M:S — deterministic rounding)
-        double t = current_time + datetime::OneSecond;
-
-        int ts_idx = ctx.gages.ts_index[uj];
+        // The legacy machine's march to this step's date (+1 s): the
+        // current record's rate inside its interval, 0 before it, in the
+        // gap before the next non-zero record, or past the last one.
+        // (The value is kept in the project's rain units, in/hr or mm/hr,
+        // as legacy Gage.rainfall; the runoff solver converts to ft/s.)
         double raw_value = 0.0;
-        // Select the source series: a FILE_RAIN gage reads from its own resolved
-        // rain_series (built by load_external_rain_files); a TIMESERIES gage reads
-        // from the shared table pool.  Both reuse the identical step-function below.
-        Table* rtbl = nullptr;
-        if (ctx.gages.source[uj] == RainSource::FILE_RAIN) {
-            if (uj < ctx.gages.rain_series.size() && !ctx.gages.rain_series[uj].empty())
-                rtbl = &ctx.gages.rain_series[uj];
-        } else if (ts_idx >= 0 && ts_idx < static_cast(ctx.tables.tables.size())) {
-            rtbl = &ctx.tables.tables[static_cast(ts_idx)];
-        }
         if (rtbl) {
-            auto& tbl = *rtbl;
-            int n = static_cast(tbl.x.size());
-
-            // Step-function lookup: find rightmost entry where x[idx] <= t
-            raw_value = table_step_cursor(tbl, t);
-
-            int idx = tbl.cursor.index;
-            if (idx >= 0 && idx < n) {
-                double entry_start = tbl.x[static_cast(idx)];
-                // Use legacy-identical datetime arithmetic for interval end
-                double entry_end = datetime::addSeconds(entry_start, interval);
-
-                if (t >= entry_end) {
-                    // Past end of this entry's rain interval.
-                    // Check if there's a next entry and t has reached it.
-                    int next_idx = idx + 1;
-                    if (next_idx < n && t >= tbl.x[static_cast(next_idx)]) {
-                        // Advance to the next entry
-                        raw_value = tbl.y[static_cast(next_idx)];
-                        tbl.cursor.index = next_idx;
-                        // Check if we're also past this next entry's interval
-                        double next_end = datetime::addSeconds(
-                            tbl.x[static_cast(next_idx)], interval);
-                        if (t >= next_end) {
-                            raw_value = 0.0; // In gap after next entry too
-                        }
-                    } else {
-                        // In dry gap between entries, or past last entry
-                        raw_value = 0.0;
-                    }
-                }
-            }
+            setGageState(ctx, j, *rtbl, current_time + datetime::OneSecond);
+            raw_value = ctx.gages.st_rain[uj];
         }
-
-        if (rain_type == 1 && interval > 0.0) {
-            // VOLUME: value is depth per interval → convert to in/hr.
-            // Match legacy gage.c:692 operand order exactly: r/interval*3600.0
-            // (one divide then one multiply), NOT r/(interval/3600.0) which forms
-            // the non-representable 1/12 constant first and rounds differently.
-            raw_value = raw_value / interval * 3600.0;
-        } else if (rain_type == 2 && interval > 0.0) {
-            // CUMULATIVE (Gap #31): raw_value is cumulative depth; compute delta.
-            // Matches legacy convertRainfall() CUMULATIVE_RAINFALL case:
-            //   if new < accum (counter reset) → treat new value as depth this interval
-            //   else → delta = new - accum (depth this interval)
-            //   always update accumulator with new raw value
-            double prev = ctx.gages.cumul_rain_accum[uj];
-            double depth = (raw_value < prev)
-                ? raw_value              // counter reset — use full value as depth
-                : (raw_value - prev);    // normal incremental delta
-            ctx.gages.cumul_rain_accum[uj] = raw_value;
-            raw_value = depth / interval * 3600.0;  // depth → in/hr (legacy gage.c:697 order)
-        }
-        // INTENSITY (type 0): already in/hr — no conversion needed
-
-        // PARITY: legacy convertRainfall (gage.c:705) applies
-        //   r1 * unitsFactor * scaleFactor * Adjust.rainFactor
-        // where Gage.unitsFactor = MMperINCH for FILE gages in SI projects
-        // (gage.c:300 — "rain depths on interface file are in inches") and
-        // 1.0 otherwise. The FILE series here holds float-quantized inches
-        // (see load_external_rain_files), so this restores project mm/hr.
-        // Multiplication order must match legacy: unitsFactor BEFORE
-        // scaleFactor.
-        {
-            double units_factor = 1.0;
-            if (ctx.gages.source[uj] == RainSource::FILE_RAIN &&
-                static_cast(ctx.options.flow_units) >= 3)
-                units_factor = 25.40;  // legacy MMperINCH (consts.h:389)
-            raw_value = raw_value * units_factor * ctx.gages.scale_factor[uj];
-        }
-
-        // Convert from in/hr to ft/sec for internal use
-        // Legacy: rainfall stored as in/hr for reporting, converted to ft/sec for runoff
-        // We store in in/hr (project rain units) and convert in the runoff solver
         ctx.gages.rainfall[uj] = raw_value;
 
         // Update past-rain history (hourly buckets for control rules)
@@ -267,8 +394,8 @@ void updateAllGages(SimulationContext& ctx, double current_time) {
     }
 }
 
-double getReportRainfall(const SimulationContext& ctx, int gage_idx,
-                         double report_date) {
+static double reportRainfall(const SimulationContext& ctx, int gage_idx,
+                             double report_date, bool from_series) {
     // IGNORE_RAINFALL: nothing is reported (legacy leaves gage rainfall 0).
     if (ctx.options.ignore_rainfall) return 0.0;
 
@@ -284,7 +411,7 @@ double getReportRainfall(const SimulationContext& ctx, int gage_idx,
         double primary_sf = ctx.gages.scale_factor[uco];
         double this_sf    = ctx.gages.scale_factor[ug];
         double ratio = (primary_sf > 0.0) ? (this_sf / primary_sf) : 1.0;
-        return getReportRainfall(ctx, co, report_date) * ratio;
+        return reportRainfall(ctx, co, report_date, from_series) * ratio;
     }
 
     // API override (legacy gage.c:544-548)
@@ -292,72 +419,63 @@ double getReportRainfall(const SimulationContext& ctx, int gage_idx,
         return ctx.gages.api_rainfall[ug];
     }
 
-    // Select the same series the gage state machine reads (Gage.cpp setState):
-    // FILE_RAIN gages use their private resolved rain_series; TIMESERIES gages
-    // use the shared table pool. (The previous version read only the shared
-    // pool, so FILE gages always reported 0.)
-    const Table* rtbl = nullptr;
-    if (ctx.gages.source[ug] == RainSource::FILE_RAIN) {
-        if (ug < ctx.gages.rain_series.size() && !ctx.gages.rain_series[ug].empty())
-            rtbl = &ctx.gages.rain_series[ug];
-    } else {
-        int ts_idx = ctx.gages.ts_index[ug];
-        if (ts_idx >= 0 && ts_idx < static_cast(ctx.tables.tables.size()))
-            rtbl = &ctx.tables.tables[static_cast(ts_idx)];
+    // legacy gage_setReportRainfall (gage.c:550-564) on the machine's state
+    // as the last gage update left it (the start of the current runoff
+    // step): the report instant + 1 s inside the current interval reads
+    // Gage.rainfall as setState left it (0 when it found the date before
+    // the interval), before the next record 0, otherwise the next record's
+    // rate (a report instant on a record boundary reads the record that
+    // begins there even though the runoff step reading it has not run).
+    const Table* rtbl = gageRainSeries(ctx, gage_idx);
+    if (!rtbl || rtbl->x.empty()) return 0.0;
+    if (ug >= ctx.gages.st_cur.size() || ctx.gages.st_cur[ug] == kNoState) return 0.0;
+    const double t = report_date + datetime::OneSecond;
+
+    // [ADJUSTMENTS] RAINFALL — the monthly multiplier. legacy applies it
+    // inside gage_getRainfall itself (`r1 * unitsFactor * scaleFactor *
+    // Adjust.rainFactor`, gage.c:710), so EVERY value derived from it carries
+    // it, including the Gage.rainfall and nextRainfall that
+    // gage_setReportRainfall hands back. This engine applies it to
+    // gages.rainfall at the simulation seam only (SWMMEngine A2f), and the
+    // report path reads st_rain / recordRate, which do not, so the reported
+    // rainfall came out UNADJUSTED: lid-master-sustain reported 0.0867 in/hr
+    // where legacy reports 0.084966 — exactly 1/0.98, its January factor.
+    // The co-gage branch above must NOT be adjusted here: it recurses into
+    // this function, which applies the factor once, matching legacy's use of
+    // the primary's already-adjusted reportRainfall. The API branch is
+    // likewise unadjusted, as legacy returns apiRainfall verbatim.
+    const int mon = datetime::monthOfYear(report_date) - 1;
+    const double radj = (mon >= 0 && mon < 12) ? ctx.adjust_rain[mon] : 1.0;
+
+    if (from_series) {
+        // A routing step can cross both a report date and a later rain
+        // boundary. The runoff cursor then describes a future record, so
+        // reading st_rain would report that future rate at the earlier date.
+        const auto it = std::upper_bound(rtbl->x.begin(), rtbl->x.end(), t);
+        if (it == rtbl->x.begin()) return 0.0;
+        const int k = static_cast(it - rtbl->x.begin()) - 1;
+        const double end = datetime::addSeconds(rtbl->x[static_cast(k)],
+                                                ctx.gages.interval_sec[ug]);
+        return t < end ? recordRate(ctx, gage_idx, *rtbl, k) * radj : 0.0;
     }
-    if (!rtbl) return 0.0;
-
-    const auto& tbl = *rtbl;
-    int n = static_cast(tbl.x.size());
-    int idx = tbl.cursor.index;
-    if (idx < 0 || idx >= n) return 0.0;
-
-    double interval = ctx.gages.interval_sec[ug];
 
-    // Legacy gage_setReportRainfall (gage.c:550-564): advance the report time
-    // by one second, then three-way branch on the current interval end and the
-    // next interval start.
-    double t = report_date + datetime::OneSecond;
-
-    double entry_start = tbl.x[static_cast(idx)];
-    double entry_end = datetime::addSeconds(entry_start, interval);
-
-    double result;
-    if (t < entry_end) {
-        // Report time is within current rain interval
-        result = tbl.y[static_cast(idx)];
-    } else {
-        // Check next entry
-        int next_idx = idx + 1;
-        if (next_idx < n && t >= tbl.x[static_cast(next_idx)]) {
-            result = tbl.y[static_cast(next_idx)];
-        } else {
-            result = 0.0; // In dry gap between entries
-        }
-    }
+    double start, end;
+    currentInterval(ctx, gage_idx, *rtbl, start, end);
+    if (t < end) return ctx.gages.st_rain[ug] * radj;
+    const int nxt = ctx.gages.st_next[ug];
+    if (nxt < 0) return 0.0;                                   // nextRainfall = 0 past the end
+    if (t < rtbl->x[static_cast(nxt)]) return 0.0;
+    return recordRate(ctx, gage_idx, *rtbl, nxt) * radj;
+}
 
-    // Convert VOLUME to INTENSITY. Match legacy operand order exactly
-    // (gage.c:692): r / interval * 3600.0 — NOT r / (interval/3600.0), which
-    // forms a non-representable constant first and rounds differently.
-    int rain_type = ctx.gages.rain_type[ug];
-    if (rain_type == 1 && interval > 0.0) {
-        result = result / interval * 3600.0;
-    }
-    // CUMULATIVE gages would need the interval delta here (legacy carries the
-    // converted value in gage state); none of the parity models use them with
-    // report rainfall — revisit if one does.
-
-    // PARITY: unitsFactor (MMperINCH for SI-project FILE gages, gage.c:300)
-    // BEFORE scaleFactor — legacy convertRainfall (gage.c:705).
-    {
-        double units_factor = 1.0;
-        if (ctx.gages.source[ug] == RainSource::FILE_RAIN &&
-            static_cast(ctx.options.flow_units) >= 3)
-            units_factor = 25.40;  // legacy MMperINCH (consts.h:389)
-        result = result * units_factor * ctx.gages.scale_factor[ug];
-    }
+double getReportRainfall(const SimulationContext& ctx, int gage_idx,
+                         double report_date) {
+    return reportRainfall(ctx, gage_idx, report_date, false);
+}
 
-    return result;
+double getReportRainfallFromSeries(const SimulationContext& ctx, int gage_idx,
+                                   double report_date) {
+    return reportRainfall(ctx, gage_idx, report_date, true);
 }
 
 } // namespace gage
diff --git a/src/engine/hydrology/Gage.hpp b/src/engine/hydrology/Gage.hpp
index f6e19f3d1..1b2915d02 100644
--- a/src/engine/hydrology/Gage.hpp
+++ b/src/engine/hydrology/Gage.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Gage.hpp
  * @brief Rain gage processing — rainfall interpolation, type conversion.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GAGE_HPP
@@ -25,6 +41,7 @@
 namespace openswmm {
 
 struct SimulationContext;
+struct Table;
 
 namespace gage {
 
@@ -80,6 +97,74 @@ struct GageState {
  */
 double convertRainfall(double raw_value, GageState& state);
 
+// ---------------------------------------------------------------------------
+// Shared rainfall resolution
+// ---------------------------------------------------------------------------
+//
+// The sequence "pick the gage's series -> apply the rain-type transform ->
+// apply units factor -> apply scale factor" is needed by the routing update,
+// by report rainfall, and by the swmm_gage_get_rainfall_series C API. Three
+// private copies would drift, so the pieces that are genuinely common live
+// here. (getReportRainfall deliberately does NOT apply the CUMULATIVE delta —
+// see its comment — so it composes these itself rather than calling
+// convertGageValue.)
+
+/**
+ * @brief The rainfall table a gage actually reads.
+ *
+ * @details A FILE_RAIN gage reads its own resolved `rain_series`, built at load
+ *          by load_external_rain_files; every other gage reads the shared table
+ *          pool. Deliberately kept out of `ctx.tables` so an INP round-trip
+ *          still emits FILE.
+ * @returns nullptr when the gage has no usable series (unresolvable file, or a
+ *          rain-file format the loader does not support).
+ */
+const Table* gageRainSeries(const SimulationContext& ctx, int gage_idx);
+
+/// Legacy Gage.isUsed: some subcatchment reads the gage (subcatch.c:429) or a
+/// [HYDROGRAPHS] group names it (rdii.c:248). Legacy validates, advances and
+/// step-limits on used gages only.
+bool gageIsUsed(const SimulationContext& ctx, int gage_idx);
+
+/// Legacy gage_getNextRainDate on the gage's state machine as the last
+/// updateAllGages left it: the date the current rain interval starts or ends
+/// or the next non-zero record begins — legacy NO_DATE (a large negative
+/// value) when there is none, and `t` itself for an unused gage — for the
+/// runoff-step limit (runoff_getTimeStep takes only a positive difference).
+double gageNextRainDate(const SimulationContext& ctx, int gage_idx, double t);
+
+/**
+ * @brief The units factor the engine applies to a gage's raw values.
+ *
+ * @details 25.40 (MMperINCH) for a STANDARD rain-file gage in an SI project,
+ *          because that loader stores float-quantized INCHES for legacy
+ *          bit-parity; 1.0 for everything else.
+ *
+ *          Scoped to STAN_PRCP on purpose. USER_CSV data is stored in the
+ *          project's own rain units, exactly like a [TIMESERIES] gage, so it
+ *          must not be rescaled — and pinning the factor to the format keeps
+ *          the legacy standard-file path byte-identical.
+ */
+double gageUnitsFactor(const SimulationContext& ctx, int gage_idx);
+
+/**
+ * @brief Apply the rain-type transform, units factor and scale factor.
+ *
+ * @details The exact arithmetic updateAllGages performs, factored out so the
+ *          read-back API cannot drift from what the run actually applies.
+ *          Operand order is load-bearing for legacy parity: `raw / interval *
+ *          3600.0` as one divide then one multiply, and units factor BEFORE
+ *          scale factor.
+ *
+ * @param cumul_accum [in/out] Running total for CUMULATIVE gages; a decrease is
+ *                    read as a counter reset. Ignored for other rain types, but
+ *                    callers walking a whole series must carry it entry to
+ *                    entry or the deltas are wrong.
+ */
+double convertGageValue(double raw, int rain_type, double interval_sec,
+                        double& cumul_accum, double units_factor,
+                        double scale_factor);
+
 /**
  * @brief Result of splitting a gage's precipitation for one subcatchment.
  */
@@ -153,6 +238,12 @@ void updateAllGages(SimulationContext& ctx, double current_time);
 double getReportRainfall(const SimulationContext& ctx, int gage_idx,
                          double report_date);
 
+/// Report-date rainfall resolved from source records, independently of the
+/// current runoff cursor. Retains SWMM's +1 s report lookup convention.
+/// Used by 2D output when a routing step can advance runoff past the report.
+double getReportRainfallFromSeries(const SimulationContext& ctx, int gage_idx,
+                                   double report_date);
+
 } // namespace gage
 } // namespace openswmm
 
diff --git a/src/engine/hydrology/Groundwater.cpp b/src/engine/hydrology/Groundwater.cpp
index 5eb694683..96110798c 100644
--- a/src/engine/hydrology/Groundwater.cpp
+++ b/src/engine/hydrology/Groundwater.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Groundwater.cpp
  * @brief Two-zone groundwater — matching legacy gwater.c via RKF45 ODE solver.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Groundwater.hpp"
@@ -16,6 +32,10 @@
 #include "../math/OdeSolver.hpp"
 #include 
 #include 
+#include 
+#include 
+#include 
+#include 
 
 namespace openswmm {
 namespace groundwater {
@@ -39,6 +59,7 @@ void GWSoA::resize(int n) {
     lower_evap_depth.assign(un, 0.0);
     lower_loss_coeff.assign(un, 0.0);
     total_depth.assign(un, 0.0);
+    bottom_elev.assign(un, 0.0);
 
     a1.assign(un, 0.0); b1.assign(un, 0.0);
     a2.assign(un, 0.0); b2.assign(un, 0.0);
@@ -249,6 +270,11 @@ void GWSolver::execute(SimulationContext& ctx, double dt, double max_evap,
             soa_.deep_loss[ui] = 0.0;
             continue;
         }
+        // Legacy gwater_getGroundwater: `if (FracPerv <= 0.0) return;` — a
+        // fully impervious subcatchment's aquifer is never updated at all
+        // (no fluxes, no flow, no statistics); its flow stays at its last
+        // value, which is 0.
+        if (frac_perv[i] <= 0.0) continue;
 
         // --- Build per-subcatchment context (matching legacy shared vars) ---
         GWContext c;
@@ -316,7 +342,7 @@ void GWSolver::execute(SimulationContext& ctx, double dt, double max_evap,
         double node_flow = 0.0;
         if (gw_node >= 0 && gw_node < ctx.n_nodes()) {
             auto un = static_cast(gw_node);
-            double area_ft2 = ctx.subcatches.area[ui] * ucf::ACRES_TO_FT2;
+            double area_ft2 = ctx.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx.options);   // legacy Subcatch.area (ft2)
             if (area_ft2 > 0.0)
                 node_flow = (ctx.nodes.inflow[un] + ctx.nodes.volume[un] / dt) / area_ft2;
         }
@@ -372,7 +398,7 @@ void GWSolver::execute(SimulationContext& ctx, double dt, double max_evap,
         auto ui = static_cast(i);
         if (soa_.total_depth[ui] <= 0.0) continue;
 
-        double area = ctx.subcatches.area[ui] * ucf::ACRES_TO_FT2;
+        double area = ctx.subcatches.area[ui] / ucf::UCF(ucf::LANDAREA, ctx.options);   // legacy Subcatch.area (ft2)
         double ft2sec = area * dt;
 
         mb.gw_infil        += infil_rate[i] * ft2sec;
@@ -384,5 +410,232 @@ void GWSolver::execute(SimulationContext& ctx, double dt, double max_evap,
     }
 }
 
+// ============================================================================
+// [GWF] expression validation — diagnostic peer of mathexpr::parse
+// ============================================================================
+// mathexpr::parse is deliberately lenient (unknown characters are skipped,
+// unknown identifiers evaluate to 0.0), so an editor cannot use "does it
+// parse" as its verdict. This is a strict tokenizer + recursive-descent
+// grammar check that never compiles or stores anything.
+
+namespace {
+
+enum class GwfTok { NUM, VAR, FUNC, OP, LPAREN, RPAREN, COMMA, END };
+
+struct GwfToken {
+    GwfTok      kind;
+    std::string text;   // as typed (identifiers keep the user's case)
+    int         col;
+};
+
+struct GwfFail {
+    std::string msg;
+    int         col;
+};
+
+bool gwf_is_variable(const std::string& upper) {
+    // Legacy getVariableIndex() resolves a GW variable with findmatch(): a
+    // variable NAME that is a case-insensitive PREFIX of the token matches, so
+    // "Ksat" -> "KS" (saturated conductivity), "Area" -> "A". An exact compare
+    // wrongly rejected such legacy-valid names as ERR 233. As in legacy this is
+    // lenient — a token like "Hgww" also resolves ("HGW" is a prefix). `upper`
+    // is already upper-cased by the caller and GW_VAR_NAMES are upper-case.
+    for (const char* v : GW_VAR_NAMES) {
+        std::size_t k = 0;
+        while (v[k] && k < upper.size() && upper[k] == v[k]) ++k;
+        if (v[k] == '\0') return true;   // whole variable name is a prefix of `upper`
+    }
+    return false;
+}
+
+bool gwf_is_function(const std::string& lower) {
+    for (const auto& f : mathexpr::function_names())
+        if (lower == f) return true;
+    return false;
+}
+
+std::vector gwf_tokenize(const std::string& s) {
+    std::vector out;
+    std::size_t i = 0;
+    while (i < s.size()) {
+        const char c = s[i];
+        if (std::isspace(static_cast(c))) { ++i; continue; }
+        const int col = static_cast(i);
+
+        if (std::isdigit(static_cast(c)) || c == '.') {
+            const std::size_t start = i;
+            while (i < s.size() &&
+                   (std::isdigit(static_cast(s[i])) ||
+                    s[i] == '.' || s[i] == 'e' || s[i] == 'E' ||
+                    ((s[i] == '+' || s[i] == '-') && i > 0 &&
+                     (s[i-1] == 'e' || s[i-1] == 'E'))))
+                ++i;
+            const std::string word = s.substr(start, i - start);
+            char* end = nullptr;
+            std::strtod(word.c_str(), &end);
+            if (end == word.c_str() || *end != '\0')
+                throw GwfFail{"malformed number '" + word + "'", col};
+            out.push_back({GwfTok::NUM, word, col});
+            continue;
+        }
+
+        if (std::isalpha(static_cast(c)) || c == '_') {
+            const std::size_t start = i;
+            while (i < s.size() &&
+                   (std::isalnum(static_cast(s[i])) || s[i] == '_'))
+                ++i;
+            const std::string word = s.substr(start, i - start);
+            std::string lower = word, upper = word;
+            for (auto& ch : lower) ch = static_cast(std::tolower(static_cast(ch)));
+            for (auto& ch : upper) ch = static_cast(std::toupper(static_cast(ch)));
+            if (gwf_is_function(lower))      out.push_back({GwfTok::FUNC, word, col});
+            else if (gwf_is_variable(upper)) out.push_back({GwfTok::VAR, word, col});
+            else throw GwfFail{"unknown variable '" + word + "'", col};
+            continue;
+        }
+
+        switch (c) {
+            case '+': case '-': case '*': case '/': case '^':
+                out.push_back({GwfTok::OP, std::string(1, c), col}); break;
+            case '(': out.push_back({GwfTok::LPAREN, "(", col}); break;
+            case ')': out.push_back({GwfTok::RPAREN, ")", col}); break;
+            case ',': out.push_back({GwfTok::COMMA, ",", col}); break;
+            default:
+                throw GwfFail{std::string("unexpected character '") + c + "'", col};
+        }
+        ++i;
+    }
+    out.push_back({GwfTok::END, "", static_cast(s.size())});
+    return out;
+}
+
+// expr   := term (('+'|'-') term)*
+// term   := unary (('*'|'/') unary)*
+// unary  := '-' unary | power
+// power  := primary ('^' unary)?
+// primary:= NUM | VAR | FUNC '(' expr (',' expr)* ')' | '(' expr ')'
+struct GwfParser {
+    const std::vector& t;
+    std::size_t p = 0;
+    int paren_depth = 0;   // > 0 while inside any '(' — decides ')' diagnostics
+    int func_depth  = 0;   // > 0 while inside a function's argument list
+
+    const GwfToken& cur() const { return t[p]; }
+    bool is_op(const char* s) const { return cur().kind == GwfTok::OP && cur().text == s; }
+
+    void expr() {
+        term();
+        while (is_op("+") || is_op("-")) { ++p; term(); }
+    }
+    void term() {
+        unary();
+        while (is_op("*") || is_op("/")) { ++p; unary(); }
+    }
+    void unary() {
+        if (is_op("-")) { ++p; unary(); return; }
+        power();
+    }
+    void power() {
+        primary();
+        if (is_op("^")) { ++p; unary(); }
+    }
+    void primary() {
+        const GwfToken& k = cur();
+        switch (k.kind) {
+            case GwfTok::NUM:
+            case GwfTok::VAR:
+                ++p;
+                return;
+            case GwfTok::FUNC: {
+                ++p;
+                if (cur().kind != GwfTok::LPAREN)
+                    throw GwfFail{"function '" + k.text + "' must be followed by '('",
+                                  cur().col};
+                const GwfToken& open = cur();
+                ++p; ++paren_depth; ++func_depth;
+                int nargs = 1;
+                expr();
+                while (cur().kind == GwfTok::COMMA) { ++p; ++nargs; expr(); }
+                close_paren(open);
+                --paren_depth; --func_depth;
+                std::string lower = k.text;
+                for (auto& ch : lower) ch = static_cast(std::tolower(static_cast(ch)));
+                const int want = (lower == "min" || lower == "max") ? 2 : 1;
+                if (nargs != want)
+                    throw GwfFail{"function '" + k.text + "' takes " +
+                                  std::to_string(want) +
+                                  (want == 1 ? " argument" : " arguments"), k.col};
+                return;
+            }
+            case GwfTok::LPAREN: {
+                const GwfToken& open = cur();
+                ++p; ++paren_depth;
+                expr();
+                if (cur().kind == GwfTok::COMMA)
+                    throw GwfFail{"unexpected ','", cur().col};
+                close_paren(open);
+                --paren_depth;
+                return;
+            }
+            case GwfTok::OP:
+                throw GwfFail{"missing operand before '" + k.text + "'", k.col};
+            case GwfTok::RPAREN:
+                if (paren_depth == 0) throw GwfFail{"unbalanced parenthesis", k.col};
+                throw GwfFail{"missing operand before ')'", k.col};
+            case GwfTok::COMMA:
+                if (func_depth == 0) throw GwfFail{"unexpected ','", k.col};
+                throw GwfFail{"missing operand before ','", k.col};
+            case GwfTok::END: {
+                const GwfToken& prev = t[p - 1];
+                if (prev.kind == GwfTok::LPAREN)
+                    throw GwfFail{"unbalanced parenthesis", prev.col};
+                throw GwfFail{"missing operand after '" + prev.text + "'", prev.col};
+            }
+        }
+    }
+    // After an expression inside '(': the next token must close it.
+    void close_paren(const GwfToken& open) {
+        if (cur().kind == GwfTok::RPAREN) { ++p; return; }
+        if (cur().kind == GwfTok::END)
+            throw GwfFail{"unbalanced parenthesis", open.col};
+        throw GwfFail{"missing operator before '" + cur().text + "'", cur().col};
+    }
+};
+
+} // namespace
+
+int gwf_validate(const std::string& expr, std::string& msg, int& col) {
+    msg.clear();
+    col = -1;
+    try {
+        const auto tokens = gwf_tokenize(expr);
+        if (tokens.front().kind == GwfTok::END)
+            throw GwfFail{"expression is empty", 0};
+
+        GwfParser parser{tokens};
+        parser.expr();
+        const GwfToken& rest = parser.cur();
+        if (rest.kind != GwfTok::END) {
+            if (rest.kind == GwfTok::RPAREN) throw GwfFail{"unbalanced parenthesis", rest.col};
+            if (rest.kind == GwfTok::COMMA)  throw GwfFail{"unexpected ','", rest.col};
+            throw GwfFail{"missing operator before '" + rest.text + "'", rest.col};
+        }
+
+        // Drift guard: the production parser must accept what we accept.
+        mathexpr::Expression probe;
+        if (mathexpr::parse(expr, probe) != 0 || !probe.valid)
+            throw GwfFail{"internal: expression rejected by the engine parser", -1};
+    } catch (const GwfFail& f) {
+        msg = f.msg;
+        col = f.col;
+        return -1;
+    } catch (...) {
+        msg = "internal: expression rejected by the engine parser";
+        col = -1;
+        return -1;
+    }
+    return 0;
+}
+
 } // namespace groundwater
 } // namespace openswmm
diff --git a/src/engine/hydrology/Groundwater.hpp b/src/engine/hydrology/Groundwater.hpp
index a6efc4ff9..372b55489 100644
--- a/src/engine/hydrology/Groundwater.hpp
+++ b/src/engine/hydrology/Groundwater.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Groundwater.hpp
  * @brief Two-zone groundwater model — batch-oriented ODE integration.
@@ -20,7 +36,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GROUNDWATER_HPP
@@ -65,6 +81,39 @@ static const char* GW_VAR_NAMES[] = {
     "THETA", "PHI", "FI", "FU", "A"
 };
 
+/// Short English gloss per GW_VAR_NAMES entry (editor tooltips / completers).
+static const char* GW_VAR_DESCRIPTIONS[] = {
+    "Water table height above aquifer bottom (ft or m)",
+    "Surface-water head at the receiving node above aquifer bottom (ft or m)",
+    "Channel bottom height above aquifer bottom (Hstar) (ft or m)",
+    "Ground surface height above aquifer bottom (ft or m)",
+    "Saturated hydraulic conductivity (in/hr or mm/hr)",
+    "Unsaturated hydraulic conductivity (in/hr or mm/hr)",
+    "Upper-zone moisture content (fraction)",
+    "Soil porosity (fraction)",
+    "Surface infiltration rate (in/hr or mm/hr)",
+    "Upper-zone percolation rate (in/hr or mm/hr)",
+    "Subcatchment area (ac or ha)"
+};
+
+/**
+ * @brief Validate a [GWF] flow expression without compiling or storing it.
+ *
+ * @details Diagnostic peer of mathexpr::parse for editors: a strict scan
+ *          (unknown characters, malformed numbers and identifiers outside
+ *          GW_VAR_NAMES / mathexpr::function_names() are errors, all
+ *          case-insensitive), balanced parentheses, operand/operator
+ *          sequencing including unary minus, and function arity (min/max take
+ *          exactly 2 arguments, every other function exactly 1). An empty or
+ *          whitespace-only expression is invalid.
+ *
+ * @param expr  Expression text.
+ * @param msg   [out] Human-readable diagnostic ("" when valid).
+ * @param col   [out] 0-based column of the error, or -1 when not attributable.
+ * @returns 0 when valid, -1 when invalid.
+ */
+int gwf_validate(const std::string& expr, std::string& msg, int& col);
+
 // ============================================================================
 // Per-subcatchment GW state (SoA for vectorization)
 // ============================================================================
@@ -84,6 +133,7 @@ struct GWSoA {
     std::vector lower_evap_depth;
     std::vector lower_loss_coeff;   ///< Deep percolation coeff
     std::vector total_depth;        ///< Aquifer thickness (ft)
+    std::vector bottom_elev;        ///< Effective aquifer bottom elevation (ft): the [GROUNDWATER] row's Ebot, else the aquifer's
 
     // Lateral flow coefficients
     std::vector a1, b1;       ///< GW outflow
diff --git a/src/engine/hydrology/Infiltration.cpp b/src/engine/hydrology/Infiltration.cpp
index 0faab8ccd..f006b0c56 100644
--- a/src/engine/hydrology/Infiltration.cpp
+++ b/src/engine/hydrology/Infiltration.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Infiltration.cpp
  * @brief Infiltration models — numerically identical to legacy infil.c.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Infiltration.hpp"
@@ -213,107 +229,183 @@ void grnampt_init(GreenAmptState& state, double S, double Ks, double IMD,
     state.IMDmax = IMD;
     state.IMD    = IMD;
     state.F      = 0.0;
-    state.Lu     = 4.0 * std::sqrt(state.Ks * ucf_rain) / ucf_depth;
+    // Legacy grnampt_setParams (infil.c) derives the upper-zone depth from Ks
+    // expressed in in/hr WHATEVER the project's unit system:
+    //   ksat = Ks * 12. * 3600.;  Lu = 4.0 * sqrt(ksat) / 12.;
+    // (Mein's equation). Keep the two multiplications so the rounding matches.
+    double ksat  = state.Ks * 12. * 3600.;
+    state.Lu     = 4.0 * std::sqrt(ksat) / 12.;
     state.Fumax  = state.IMDmax * state.Lu;
     state.Fu     = 0.0;  // Legacy: starts dry (empty upper zone = max storage)
     state.saturated = false;
 }
 
-/// Newton solve for cumulative infiltration F2 given F1 and timestep.
-static double grnampt_getF2(double F1, double Ks, double c1, double dt) {
-    double f2 = F1 + Ks * dt;
-    double c2 = c1 * std::log(F1 + c1) - Ks * dt;
-
-    for (int i = 0; i < 20; ++i) {
-        double df2 = (f2 - F1 - c1 * std::log(f2 + c1) + c2);
-        double denom = 1.0 - c1 / (f2 + c1);
-        if (std::fabs(denom) < TINY) break;
-        df2 /= denom;
-        if (std::fabs(df2) < 0.00001) break;
+// ---------------------------------------------------------------------------
+// Green-Ampt: op-for-op transliteration of legacy infil.c (grnampt_getInfil,
+// grnampt_getUnsatInfil, grnampt_getSatInfil, grnampt_getF2). The parity
+// corpus exercises the saturation transition inside a step, the Newton
+// start point and floor of the F2 solve, and the dry-branch resets, so the
+// control flow and the arithmetic below follow legacy statement by
+// statement. `ks`, `lu` and `Fumax` are the factor-scaled locals legacy
+// computes per call from the unscaled state.
+// ---------------------------------------------------------------------------
+
+/// Legacy grnampt_getF2: cumulative infiltration F2 after time ts from F1.
+static double grnampt_getF2(double f1, double c1, double ks, double ts) {
+    double f2 = f1;
+    double f2min = f1 + ks * ts;
+
+    // --- special case of no capillary suction / no moisture deficit
+    if (c1 == 0.0) return f2min;
+
+    // --- use explicit form of G-A equation for small time steps
+    //     and when initial cum. infil. is > 0.01 * c1
+    if (ts < 10.0 && f1 > 0.01 * c1) {
+        f2 = f1 + ks * (1.0 + c1 / f1) * ts;
+        return std::max(f2, f2min);
+    }
+
+    // --- use Newton-Raphson method to solve integrated G-A equation
+    double c2 = c1 * std::log(f1 + c1) - ks * ts;
+    for (int i = 1; i <= 20; ++i) {
+        double df2 = (f2 - f1 - c1 * std::log(f2 + c1) + c2) /
+                     (1.0 - c1 / (f2 + c1));
+        if (std::fabs(df2) < 0.00001) return std::max(f2, f2min);
         f2 -= df2;
     }
-    return f2;
+    return f2min;
 }
 
-double grnampt_getInfil(GreenAmptState& state, double precip, double depth, double dt,
-                        InfilModel model_type) {
-    // Matching legacy infil.c grnampt_getInfil + grnampt_getUnsatInfil + grnampt_getSatInfil
-    double ia = precip + depth / dt;
-    double lu = state.Lu;
-    double Fumax = state.Fumax;  // InfilFactor applied at call-site to Ks/Lu
+/// Legacy grnampt_getSatInfil.
+static double grnampt_getSatInfil(GreenAmptState& s, double tstep, double irate,
+                                  double depth, double ks, double lu,
+                                  double Fumax, double recovery_factor) {
+    // --- total available inflow rate (rain + ponded depth)
+    double ia = irate + depth / tstep;
+    if (ia < TINY) return 0.0;
+
+    // --- reset time to drain upper zone
+    s.T = 5400.0 / lu / recovery_factor;
+
+    // --- find new cumulative infiltration volume (F2) over the time step
+    double c1 = (s.S + depth) * s.IMD;
+    double F2 = grnampt_getF2(s.F, c1, ks, tstep);
+    double dF = F2 - s.F;
+
+    // --- if potential infil. exceeds supply, then surface becomes unsaturated
+    if (dF > ia * tstep) {
+        dF = ia * tstep;
+        s.saturated = false;
+    }
 
-    // Decrement inter-event timer (matching legacy line 672)
-    state.T -= dt;
+    // --- update cumulative infiltration volumes and return infil. rate
+    s.F  += dF;
+    s.Fu += dF;
+    s.Fu  = std::min(s.Fu, Fumax);
+    return dF / tstep;
+}
 
-    if (ia <= 0.0) {
-        // Dry period — recovery (matching legacy grnampt_getUnsatInfil lines 705-727)
-        if (lu > 0.0 && Fumax > 0.0) {
-            double kr = lu / 90000.0;  // recoveryFactor applied at call-site to Lu
-            double dF = kr * Fumax * dt;
-            state.F  -= dF;
-            state.Fu -= dF;
-            state.F = std::max(state.F, 0.0);
-            state.Fu = std::max(state.Fu, 0.0);
-
-            // Inter-event reset: when timer expires, reset IMD and F
-            // Standard GA resets F; Modified GA does NOT (legacy line 736)
-            if (model_type == InfilModel::GREEN_AMPT && state.T <= 0.0) {
-                state.IMD = (Fumax > 0.0 && lu > 0.0)
-                    ? (Fumax - state.Fu) / lu : state.IMDmax;
-                state.F = 0.0;
-            }
+/// Legacy grnampt_getUnsatInfil.
+static double grnampt_getUnsatInfil(GreenAmptState& s, double tstep, double irate,
+                                    double depth, InfilModel model_type,
+                                    double ks, double lu, double Fumax,
+                                    double recovery_factor) {
+    // --- get available infiltration rate (rainfall + ponded water)
+    double ia = irate + depth / tstep;
+    if (ia < TINY) ia = 0.0;
+
+    // --- no rainfall so recover upper zone moisture
+    if (ia == 0.0) {
+        if (s.Fu <= 0.0) return 0.0;
+        double kr = lu / 90000.0 * recovery_factor;
+        double dF = kr * Fumax * tstep;
+        s.F  -= dF;
+        s.Fu -= dF;
+        if (s.Fu <= 0.0) {
+            s.Fu  = 0.0;
+            s.F   = 0.0;
+            s.IMD = s.IMDmax;
+            return 0.0;
+        }
+
+        // --- if a previous wet period exists, then adjust IMD & reset F
+        if (s.T <= 0.0) {
+            s.IMD = (Fumax - s.Fu) / lu;
+            s.F   = 0.0;
         }
-        state.saturated = false;
         return 0.0;
     }
 
-    // --- Wet period ---
-    double c1 = (state.S + depth) * state.IMD;
-
-    if (!state.saturated) {
-        // Unsaturated path (matching legacy grnampt_getUnsatInfil)
-        if (ia <= state.Ks) {
-            // Light rain: infiltrate all
-            state.F  += ia * dt;
-            state.Fu  = std::min(state.Fu + ia * dt, Fumax);
-
-            // Inter-event reset for standard Green-Ampt when timer expires
-            // (matching legacy line 736: only GREEN_AMPT, not MOD_GREEN_AMPT)
-            if (state.T <= 0.0) {
-                state.IMD = (Fumax > 0.0 && lu > 0.0)
-                    ? (Fumax - state.Fu) / lu : state.IMDmax;
-                state.F = 0.0;
-            }
-            return ia;
+    // --- rainfall does not exceed Ksat
+    if (ia <= ks) {
+        double dF = ia * tstep;
+        s.F  += dF;
+        s.Fu += dF;
+        s.Fu  = std::min(s.Fu, Fumax);
+        if (model_type == InfilModel::GREEN_AMPT && s.T <= 0.0) {
+            s.IMD = (Fumax - s.Fu) / lu;
+            s.F   = 0.0;
         }
+        return ia;
+    }
 
-        // Heavy rain: renew inter-event timer
-        // (matching legacy line 745: T = 5400 / lu / recoveryFactor)
-        if (lu > 0.0) state.T = 5400.0 / lu;
-
-        // Check if saturation occurs this step
-        double Fs = (c1 > 0.0 && ia > state.Ks)
-                    ? state.Ks * c1 / (ia - state.Ks) : 1.0e10;
-        if (state.F + ia * dt <= Fs) {
-            state.F  += ia * dt;
-            state.Fu  = std::min(state.Fu + ia * dt, Fumax);
-            return ia;
-        }
-        state.saturated = true;
+    // --- rainfall exceeds Ksat; renew time to drain upper zone
+    s.T = 5400.0 / lu / recovery_factor;
+
+    // --- find volume needed to saturate surface
+    double Fs = ks * (s.S + depth) * s.IMD / (ia - ks);
+
+    // --- surface is already saturated
+    if (s.F > Fs) {
+        s.saturated = true;
+        return grnampt_getSatInfil(s, tstep, irate, depth, ks, lu, Fumax,
+                                   recovery_factor);
     }
 
-    // Saturated path: renew timer
-    if (lu > 0.0) state.T = 5400.0 / lu;
+    // --- surface remains unsaturated
+    if (s.F + ia * tstep < Fs) {
+        double dF = ia * tstep;
+        s.F  += dF;
+        s.Fu += dF;
+        s.Fu  = std::min(s.Fu, Fumax);
+        return ia;
+    }
 
-    // Solve Green-Ampt equation
-    double F2 = grnampt_getF2(state.F, state.Ks, c1, dt);
-    double fp = (F2 - state.F) / dt;
-    fp = std::min(fp, ia);
-    fp = std::max(fp, 0.0);
+    // --- surface becomes saturated during time step;
+    //     compute time needed to saturate surface
+    double ts = tstep - (Fs - s.F) / ia;
+    if (ts <= 0.0) ts = 0.0;
+
+    // --- compute new total volume infiltrated
+    double c1 = (s.S + depth) * s.IMD;
+    double F2 = grnampt_getF2(Fs, c1, ks, ts);
+    if (F2 > Fs + ia * ts) F2 = Fs + ia * ts;
+
+    // --- compute infiltration rate
+    double dF = F2 - s.F;
+    s.F  = F2;
+    s.Fu += dF;
+    s.Fu  = std::min(s.Fu, Fumax);
+    s.saturated = true;
+    return dF / tstep;
+}
 
-    state.F  = F2;
-    state.Fu = std::min(state.Fu + fp * dt, Fumax);
-    return fp;
+double grnampt_getInfil(GreenAmptState& state, double precip, double depth, double dt,
+                        InfilModel model_type, double infil_factor,
+                        double recovery_factor) {
+    // Legacy grnampt_getInfil: the factor-scaled locals, then dispatch on
+    // the saturation flag. lu = 0 cannot happen for validated input (legacy
+    // rejects Ks <= 0 at parse), so the divisions below are legacy's own.
+    const double sqrt_if = std::sqrt(infil_factor);
+    const double Fumax   = state.IMDmax * state.Lu * sqrt_if;
+    const double ks      = state.Ks * infil_factor;
+    const double lu      = state.Lu * sqrt_if;
+    state.T -= dt;
+    if (state.saturated)
+        return grnampt_getSatInfil(state, dt, precip, depth, ks, lu, Fumax,
+                                   recovery_factor);
+    return grnampt_getUnsatInfil(state, dt, precip, depth, model_type, ks, lu,
+                                 Fumax, recovery_factor);
 }
 
 // ============================================================================
@@ -338,9 +430,13 @@ void curvenum_init(CurveNumState& state, double CN, double regen_days) {
     state.Tmax = (state.regen > 0.0) ? 0.06 / state.regen : 1.0e10;
 }
 
-double curvenum_getInfil(CurveNumState& state, double precip, double depth, double dt) {
-    // Matches legacy infil.c::curvenum_getInfil() exactly
-    constexpr double MIN_TOTAL_DEPTH = 0.0001; // ft
+double curvenum_getInfil(CurveNumState& state, double precip, double depth, double dt,
+                         double recovery_factor) {
+    // Matches legacy infil.c::curvenum_getInfil() exactly. MIN_TOTAL_DEPTH is
+    // legacy consts.h's 0.05 in (a former 0.0001 ft here kept the ponded
+    // water of a drying pervious area infiltrating long after legacy had
+    // stopped — 77-h-h-elements SB1).
+    constexpr double MIN_TOTAL_DEPTH = 0.004167; // ft
     double fa = precip + depth / dt;  // max available rate
     double f1 = 0.0;
 
@@ -395,9 +491,10 @@ double curvenum_getInfil(CurveNumState& state, double precip, double depth, doub
     }
     // --- Otherwise regenerate capacity ---
     else {
-        // Legacy line 1022: S += regen * Smax * tstep * recoveryFactor
-        // recoveryFactor is applied at call-site
-        state.S += state.regen * state.Smax * dt;
+        // Legacy: S += regen * Smax * tstep * Evap.recoveryFactor, in that
+        // order (the factor was folded into `regen` by the caller, a
+        // different rounding).
+        state.S += state.regen * state.Smax * dt * recovery_factor;
         state.S = std::min(state.S, state.Smax);
     }
 
@@ -405,5 +502,14 @@ double curvenum_getInfil(CurveNumState& state, double precip, double depth, doub
     return f1;
 }
 
+// ============================================================================
+// Constant rate — 2D only (plan §5.5.1); no legacy infil.c counterpart
+// ============================================================================
+
+double constant_getInfil(double rate_ftsec, double precip, double depth, double dt) {
+    double ia = precip + depth / dt;  // available water rate (ft/sec)
+    return std::max(0.0, std::min(rate_ftsec, ia));
+}
+
 } // namespace infil
 } // namespace openswmm
diff --git a/src/engine/hydrology/Infiltration.hpp b/src/engine/hydrology/Infiltration.hpp
index f78431896..238068dfb 100644
--- a/src/engine/hydrology/Infiltration.hpp
+++ b/src/engine/hydrology/Infiltration.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Infiltration.hpp
  * @brief Infiltration models — Horton, Green-Ampt, SCS Curve Number.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INFILTRATION_HPP
@@ -31,7 +47,9 @@ enum class InfilModel : int {
     MOD_HORTON     = 1,   ///< Modified Horton: linear decay fp = f0 - kd * Fe
     GREEN_AMPT     = 2,
     MOD_GREEN_AMPT = 3,   ///< Modified Green-Ampt: does not reset F between events
-    CURVE_NUM      = 4
+    CURVE_NUM      = 4,
+    CONSTANT       = 5    ///< Constant rate, capacity-bounded. 2D-only (no legacy
+                          ///< [INFILTRATION] token); see plan §5.5.1.
 };
 
 // ============================================================================
@@ -88,6 +106,13 @@ struct CurveNumState {
 
 namespace infil {
 
+// The state structs above are declared at `openswmm` scope. Re-export them
+// here so callers may also spell them `infil::HortonState` (the 2D adapter
+// contract, src/engine/2d/infil/Infil2D.hpp, uses that qualification).
+using ::openswmm::HortonState;
+using ::openswmm::GreenAmptState;
+using ::openswmm::CurveNumState;
+
 /**
  * @brief Compute Horton infiltration rate for one timestep.
  *
@@ -118,14 +143,29 @@ double modHorton_getInfil(HortonState& state, double precip, double depth, doubl
 /**
  * @brief Compute Green-Ampt infiltration rate.
  *
- * @param state   [in/out] Green-Ampt state.
- * @param precip  Rainfall rate (ft/sec).
- * @param depth   Ponded depth (ft).
- * @param dt      Timestep (seconds).
+ * Op-for-op transliteration of legacy infil.c grnampt_getInfil /
+ * grnampt_getUnsatInfil / grnampt_getSatInfil / grnampt_getF2. The two
+ * factors legacy keeps in file-scope globals (InfilFactor from the
+ * [ADJUSTMENTS] conductivity multiplier or a subcatchment pattern, and
+ * Evap.recoveryFactor from the evaporation recovery pattern) are passed in
+ * and applied exactly where legacy applies them: ks = Ks*InfilFactor,
+ * lu = Lu*sqrt(InfilFactor), Fumax = IMDmax*Lu*sqrt(InfilFactor),
+ * kr = lu/90000*recoveryFactor, T = 5400/lu/recoveryFactor. The state's
+ * Ks/Lu are never scaled in place.
+ *
+ * @param state            [in/out] Green-Ampt state.
+ * @param precip           Rainfall (plus runon) rate (ft/sec).
+ * @param depth            Ponded depth (ft).
+ * @param dt               Timestep (seconds).
+ * @param model_type       GREEN_AMPT resets F at the inter-event timer;
+ *                         MOD_GREEN_AMPT does not.
+ * @param infil_factor     Legacy InfilFactor (1.0 = none).
+ * @param recovery_factor  Legacy Evap.recoveryFactor (1.0 = none).
  * @returns Infiltration rate (ft/sec).
  */
 double grnampt_getInfil(GreenAmptState& state, double precip, double depth, double dt,
-                        InfilModel model_type = InfilModel::GREEN_AMPT);
+                        InfilModel model_type = InfilModel::GREEN_AMPT,
+                        double infil_factor = 1.0, double recovery_factor = 1.0);
 
 /**
  * @brief Compute SCS Curve Number infiltration rate.
@@ -136,7 +176,23 @@ double grnampt_getInfil(GreenAmptState& state, double precip, double depth, doub
  * @param dt      Timestep (seconds).
  * @returns Infiltration rate (ft/sec).
  */
-double curvenum_getInfil(CurveNumState& state, double precip, double depth, double dt);
+double curvenum_getInfil(CurveNumState& state, double precip, double depth, double dt,
+                         double recovery_factor = 1.0);
+
+/**
+ * @brief Compute constant-rate infiltration, bounded by available water.
+ *
+ * @details Stateless: f = min(rate, precip + depth/dt), floored at zero. Has
+ *          no legacy infil.c counterpart — added for the 2D per-cell
+ *          infiltration track (plan §5.5.1, InfilModel::CONSTANT).
+ *
+ * @param rate_ftsec  Constant infiltration rate (ft/sec).
+ * @param precip      Rainfall rate (ft/sec).
+ * @param depth       Ponded depth (ft).
+ * @param dt          Timestep (seconds).
+ * @returns Infiltration rate (ft/sec).
+ */
+double constant_getInfil(double rate_ftsec, double precip, double depth, double dt);
 
 /**
  * @brief Initialise Horton parameters from user input.
diff --git a/src/engine/hydrology/Inflow.cpp b/src/engine/hydrology/Inflow.cpp
index 9b92206b7..2e029585e 100644
--- a/src/engine/hydrology/Inflow.cpp
+++ b/src/engine/hydrology/Inflow.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Inflow.cpp
  * @brief External/DWF inflows — batch SoA, numerically identical to legacy.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Inflow.hpp"
@@ -16,6 +32,7 @@
 #include "../data/TableData.hpp"
 #include 
 #include 
+#include 
 #include 
 #include 
 #include 
@@ -25,6 +42,26 @@ namespace inflow {
 
 using constants::DATE_DELTA;
 
+namespace {
+
+/// Legacy `match(str, w_FLOW)` (keywords.c): the keyword has to be a
+/// case-insensitive PREFIX of the token, not the whole of it, after leading
+/// blanks are skipped. So FLOW, Flow, FLOWRATE and FLOW_EXPANSION all name the
+/// node's hydrograph in [INFLOWS] and [DWF].
+bool matches_flow_keyword(const std::string& s) {
+    static constexpr char kFlow[] = "FLOW";
+    std::size_t i = s.find_first_not_of(' ');
+    if (i == std::string::npos) return false;
+    for (std::size_t j = 0; j < 4; ++j, ++i) {
+        if (i >= s.size()) return false;
+        if (std::toupper(static_cast(s[i])) != kFlow[j])
+            return false;
+    }
+    return true;
+}
+
+}  // namespace
+
 void ExtInflowSoA::resize(int n) {
     count = n;
     auto un = static_cast(n);
@@ -34,6 +71,8 @@ void ExtInflowSoA::resize(int n) {
     baseline.assign(un, 0.0);
     scale_factor.assign(un, 1.0);
     conv_factor.assign(un, 1.0);
+    kind.assign(un, static_cast(ExtInflowKind::FLOW));
+    pollut_idx.assign(un, -1);
 }
 
 void DwfInflowSoA::resize(int n) {
@@ -45,6 +84,9 @@ void DwfInflowSoA::resize(int n) {
     pat_daily.assign(un, -1);
     pat_hourly.assign(un, -1);
     pat_weekend.assign(un, -1);
+    is_flow.assign(un, 0);
+    pollut_idx.assign(un, -1);
+    msx_idx.assign(static_cast(n), -1);
 }
 
 double InflowSolver::getPatternFactor(int pat_idx, int month, int day, int hour) const {
@@ -95,6 +137,17 @@ void InflowSolver::init(SimulationContext& ctx) {
     // ---- Copy patterns into runtime structures ----
     refreshPatterns(ctx);
 
+    // Z1 (amendment D-Y4): (re)assert the per-node inflow-age channel.
+    // Sized HERE — before the first routing step — because the loaders'
+    // lazy WaterAgeState::resize lands between Pass 3's first write and
+    // its first read; and re-filled with NaN on every init because init
+    // is the authority on which rows exist (an [INFLOWS] row removed via
+    // the API must not leave its last age behind).
+    if (ctx.options.water_age)
+        ctx.water_age_state.node_ext_inflow_age.assign(
+            static_cast(ctx.n_nodes()),
+            std::numeric_limits::quiet_NaN());
+
     // ---- Populate external inflows with name resolution ----
     int ne = ctx.ext_inflows.count();
     ext_inflows_.resize(ne);
@@ -112,9 +165,112 @@ void InflowSolver::init(SimulationContext& ctx) {
         // metric (CMS/LPS/MLD) direct inflows were applied ~35x too small.
         double cf = ctx.ext_inflows.m_factor[ui];
         const auto& cons = ctx.ext_inflows.constituent[ui];
-        if (cons == "FLOW" || cons == "flow" || cons == "Flow") {
+        // Classify the row. A constituent of FLOW is the node's hydrograph; any
+        // other constituent names a pollutant and carries a load, NOT water.
+        // Legacy: inflow_readExtInflow() / routing.c addExternalInflows().
+        auto upper = [](std::string s) {
+            for (auto& ch : s) ch = static_cast(std::toupper(
+                static_cast(ch)));
+            return s;
+        };
+        // Warnings below dedupe against ctx.warnings because init() re-runs
+        // on every swmm_ext_inflow_add() — without the check each API add
+        // would repeat every standing warning.
+        auto warn_once = [&ctx](const std::string& msg) {
+            for (const auto& w : ctx.warnings)
+                if (w == msg) return;
+            ctx.warnings.push_back(msg);
+        };
+        // Legacy inflow_readExtInflow (inflow.c:252-258) looks the token up in
+        // the POLLUTANT table first and only then tests match(tok[1], w_FLOW),
+        // which is a PREFIX test — see matches_flow_keyword above.
+        if (ctx.pollutant_names.find(cons) < 0 && matches_flow_keyword(cons)) {
+            ext_inflows_.kind[ui]       = static_cast(ExtInflowKind::FLOW);
+            ext_inflows_.pollut_idx[ui] = -1;
             int fu = static_cast(ctx.options.flow_units);
             if (fu >= 0 && fu < 6) cf /= ucf::Qcf[fu];
+        } else if (cons == "__WATER_AGE__") {
+            // Z1 (amendment D-Y4): the reserved age species is a legal
+            // [INFLOWS] constituent. The row's value is the AGE of the
+            // node's external inflow water — HOURS in the file (the
+            // [WATER_AGE_SOURCES] unit), SECONDS internally — and it wins
+            // over the source table's EXTERNAL_INFLOW entry at this node.
+            ext_inflows_.kind[ui]       = static_cast(ExtInflowKind::AGE);
+            ext_inflows_.pollut_idx[ui] = -1;
+            cf *= 3600.0;   // hours → seconds
+            const std::string type_u = upper(ctx.ext_inflows.inflow_type[ui]);
+            if (type_u == "MASS")
+                warn_once(
+                    "[INFLOWS] __WATER_AGE__ at node '" +
+                    ctx.ext_inflows.node_name[ui] +
+                    "': MASS has no meaning for the age species — the value "
+                    "is taken as the inflow's age in hours (CONCEN).");
+            if (!ctx.options.water_age)
+                warn_once(
+                    "[INFLOWS] __WATER_AGE__ rows are present but [OPTIONS] "
+                    "WATER_AGE is OFF — the rows are inert this simulation.");
+            // Amendment 1 §6: two ways to state an external-inflow age.
+            // The [INFLOWS] row wins because it is the more specific
+            // statement; say so instead of letting one silently lose.
+            for (std::size_t k = 0;
+                 k < ctx.water_age_config.node_over_source.size(); ++k)
+                if (ctx.water_age_config.node_over_source[k] ==
+                        static_cast(WaterAgeSource::EXTERNAL_INFLOW) &&
+                    ctx.water_age_config.node_over_node[k] ==
+                        ext_inflows_.node_idx[ui])
+                    warn_once(
+                        "[INFLOWS] __WATER_AGE__ at node '" +
+                        ctx.ext_inflows.node_name[ui] +
+                        "' overrides the [WATER_AGE_SOURCES] "
+                        "EXTERNAL_INFLOW row for the same node — the "
+                        "inflow row wins (amendment D-Y4).");
+        } else if (cons == "__TEMPERATURE__") {
+            // Heat keeps the dedicated-page treatment until its own round
+            // (amendment 1 §6) — but never the silent drop.
+            ext_inflows_.kind[ui]       = static_cast(ExtInflowKind::CONCEN);
+            ext_inflows_.pollut_idx[ui] = -1;
+            warn_once(
+                "[INFLOWS] __TEMPERATURE__ rows arrive with heat's round — "
+                "the row at node '" + ctx.ext_inflows.node_name[ui] +
+                "' is ignored.");
+        } else {
+            const std::string type_u = upper(ctx.ext_inflows.inflow_type[ui]);
+            const bool is_mass = (type_u == "MASS");
+            ext_inflows_.kind[ui] = static_cast(
+                is_mass ? ExtInflowKind::MASS : ExtInflowKind::CONCEN);
+            ext_inflows_.pollut_idx[ui] = ctx.pollutant_names.find(cons);
+            // U2 (2026-09-07): a reactions-component species is a legal
+            // constituent on the same footing as a pollutant (the one
+            // species resolver). Its load rides msx_ext_mass_in.
+            if (ext_inflows_.pollut_idx[ui] < 0 && ctx.reactions.configured) {
+                const int m = ctx.reactions.find_species(cons);
+                if (m >= 0) {
+                    ext_inflows_.kind[ui] = static_cast(
+                        is_mass ? ExtInflowKind::MSX_MASS : ExtInflowKind::MSX_CONCEN);
+                    ext_inflows_.pollut_idx[ui] = m;
+                    if (m < static_cast(ctx.reactions.species_is_wall.size()) &&
+                        ctx.reactions.species_is_wall[static_cast(m)])
+                        warn_once(
+                            "[INFLOWS] '" + cons + "' at node '" +
+                            ctx.ext_inflows.node_name[ui] +
+                            "' is a WALL species — inflow water carries no "
+                            "wall-bound mass; the row is ignored.");
+                }
+            }
+            // Z1: a constituent matching nothing was SILENTLY dropped at
+            // routing (pollut_idx −1 skips the row); a typo in a pollutant
+            // name deserves words.
+            if (ext_inflows_.pollut_idx[ui] < 0)
+                warn_once(
+                    "[INFLOWS] constituent '" + cons + "' at node '" +
+                    ctx.ext_inflows.node_name[ui] +
+                    "' matches no pollutant, reactions species or reserved "
+                    "species — the row is ignored.");
+            // Internal quality unit is ft3 x mg/L, so a user-supplied MASS rate
+            // divides by the liters-per-ft3 factor exactly as legacy does
+            // (inflow.c: "if ( type == MASS_INFLOW ) cf /= LperFT3").
+            constexpr double L_PER_FT3 = 28.317;   // legacy consts.h LperFT3
+            if (is_mass) cf /= L_PER_FT3;
         }
         ext_inflows_.conv_factor[ui]  = cf;
 
@@ -147,9 +303,26 @@ void InflowSolver::init(SimulationContext& ctx) {
         // (matching legacy inflow_readDwfInflow: x /= UCF(FLOW))
         double avg_val = ctx.dwf_inflows.avg_value[ui];
         const auto& constituent = ctx.dwf_inflows.constituent[ui];
-        if (constituent == "FLOW" || constituent == "flow" || constituent == "Flow") {
+        // Legacy inflow_readDwfInflow (inflow.c:252-257) searches the POLLUTANT
+        // table first and only then tests match(tok[1], w_FLOW) — a PREFIX
+        // test. v6 compared against an exact "FLOW"/"flow"/"Flow", so
+        // 3010-h-h-elements' eight `FLOW_EXPANSION` rows bound no pollutant
+        // and delivered no water: STOR-42 ran the whole simulation 0.05 cfs
+        // dry, and the network diverged before the first reported period.
+        const int dwf_pollut = ctx.pollutant_names.find(constituent);
+        if (dwf_pollut < 0 && matches_flow_keyword(constituent)) {
             int fu = static_cast(ctx.options.flow_units);
             avg_val /= ucf::Qcf[fu];
+            dwf_inflows_.is_flow[ui] = 1;
+        } else {
+            // Pollutant DWF row: a concentration tied to the node's DWF flow
+            // (legacy TDwfInflow.param = pollutant index). Unmatched names
+            // stay -1 and the row is inert, like a legacy parse would reject.
+            dwf_inflows_.pollut_idx[ui] = dwf_pollut;
+            // U2: a reactions-species DWF concentration (same footing as a
+            // pollutant row; the load goes to msx_ext_mass_in).
+            if (dwf_inflows_.pollut_idx[ui] < 0 && ctx.reactions.configured)
+                dwf_inflows_.msx_idx[ui] = ctx.reactions.find_species(constituent);
         }
         dwf_inflows_.avg_value[ui] = avg_val;
 
@@ -184,6 +357,76 @@ void InflowSolver::init(SimulationContext& ctx) {
         dwf_inflows_.pat_hourly[ui]  = tmp_pats[HOURLY_PATTERN];
         dwf_inflows_.pat_weekend[ui] = tmp_pats[WEEKEND_PATTERN];
     }
+
+    // ---- A repeated (node, constituent) row REPLACES the earlier one ----
+    //
+    // Legacy holds at most ONE inflow object per node and constituent:
+    // inflow_setExtInflow (inflow.c:129-150) and inflow_readDwfInflow
+    // (inflow.c:274-295) walk the node's list for a matching `param` and
+    // OVERWRITE every field of the object they find, appending only when
+    // there is none. A second row for the same pair therefore SUPERSEDES the
+    // first — timeseries, baseline, scale and patterns all come from the last
+    // row read. v6 kept each parsed row and summed them at runtime, so
+    // ocp-neid123's two S006-058 FLOW rows (a 5.42 cfs baseline, then a
+    // timeseries with no baseline) both fired and the node ran 5.42 cfs wet
+    // for the whole simulation. 17 corpus decks repeat a pair.
+    //
+    // `param` is legacy's key: −1 for FLOW, else the pollutant index. The
+    // v6-only constituents (a reactions species, the reserved age species)
+    // get disjoint key spaces so they cannot alias a pollutant index, and a
+    // row that resolved to nothing (legacy would have rejected the deck; v6
+    // warns and ignores it) is left out of the keying entirely — it is
+    // already inert, and its param of −1 would otherwise collide with the
+    // node's FLOW row and silence that. Superseded rows are marked with
+    // node_idx = −1, which every consumer below already skips.
+    {
+        constexpr long long kNone    = std::numeric_limits::min();
+        constexpr long long kMsxBase = 1LL << 32;
+        constexpr long long kAgeKey  = 1LL << 33;
+        auto ext_param = [](int kind, int idx) -> long long {
+            switch (static_cast(kind)) {
+                case ExtInflowKind::FLOW:       return -1;
+                case ExtInflowKind::AGE:        return kAgeKey;
+                case ExtInflowKind::MSX_CONCEN:
+                case ExtInflowKind::MSX_MASS:   return (idx >= 0) ? kMsxBase + idx : kNone;
+                default:                        return (idx >= 0) ? idx : kNone;
+            }
+        };
+        std::unordered_map last;
+        auto supersede = [&last](std::vector& node_idx, int row,
+                                 long long param) {
+            if (param == kNone) return;
+            // param ∈ [−1, 2^33]; +3 keeps it positive so the node bits above
+            // bit 34 stay clean.
+            const long long key =
+                (static_cast(node_idx[static_cast(row)])
+                 << 34) + param + 3;
+            auto it = last.find(key);
+            if (it != last.end())
+                node_idx[static_cast(it->second)] = -1;
+            last[key] = row;
+        };
+
+        for (int i = 0; i < ne; ++i) {
+            auto ui = static_cast(i);
+            if (ext_inflows_.node_idx[ui] < 0) continue;
+            supersede(ext_inflows_.node_idx, i,
+                      ext_param(ext_inflows_.kind[ui],
+                                ext_inflows_.pollut_idx[ui]));
+        }
+
+        last.clear();
+        for (int i = 0; i < nd; ++i) {
+            auto ui = static_cast(i);
+            if (dwf_inflows_.node_idx[ui] < 0) continue;
+            const long long param =
+                dwf_inflows_.is_flow[ui]        ? -1
+              : dwf_inflows_.msx_idx[ui] >= 0   ? kMsxBase + dwf_inflows_.msx_idx[ui]
+              : dwf_inflows_.pollut_idx[ui] >= 0 ? dwf_inflows_.pollut_idx[ui]
+                                                : kNone;
+            supersede(dwf_inflows_.node_idx, i, param);
+        }
+    }
 }
 
 void InflowSolver::computeAll(SimulationContext& ctx, double current_date, double /*dt*/) {
@@ -212,10 +455,14 @@ void InflowSolver::computeAll(SimulationContext& ctx, double current_date, doubl
     int month = datetime::monthOfYear(current_date) - 1;
 
     // ---- Batch external inflows (gather + multiply + scatter-add) ----
-    for (int i = 0; i < ext_inflows_.count; ++i) {
-        auto ui = static_cast(i);
-
-        // Baseline value, optionally modulated by a time pattern
+    // Two passes, matching legacy routing.c addExternalInflows(): the FLOW rows
+    // establish each node's direct inflow first, because a CONCEN row's mass
+    // rate is that flow times the concentration.
+    const int np = ctx.n_pollutants();
+
+    // Value of one [INFLOWS] row at the current date: cf * (tsv + blv), as in
+    // legacy inflow_getExtInflow().
+    auto row_value = [&](std::size_t ui) {
         double base = ext_inflows_.baseline[ui];
         int bp = ext_inflows_.base_pat_idx[ui];
         if (bp >= 0) {
@@ -231,10 +478,22 @@ void InflowSolver::computeAll(SimulationContext& ctx, double current_date, doubl
             ts_val = table_tseries_lookup_cursor(ctx.tables[ts], current_date);
             ts_val *= ext_inflows_.scale_factor[ui];
         }
+        return ext_inflows_.conv_factor[ui] * (ts_val + base);
+    };
+
+    // Pass 1 — FLOW rows only.
+    for (int i = 0; i < ext_inflows_.count; ++i) {
+        auto ui = static_cast(i);
+        if (ext_inflows_.kind[ui] != static_cast(ExtInflowKind::FLOW))
+            continue;
 
-        // Combined inflow: cf * (tsv + blv)
-        // Matches legacy: cf * (tsv + blv) in inflow_getExtInflow
-        double q = ext_inflows_.conv_factor[ui] * (ts_val + base);
+        double q = row_value(ui);
+        // PARITY routing.c addExternalInflows: `if (fabs(q) < FLOW_TOL) q = 0`
+        // — the node's external flow is dropped below FLOW_TOL before it joins
+        // newLatFlow (and before the CONCEN rows multiply by it). Without this
+        // the first step of a ramp starting at 0 injected ~1e-6 cfs that
+        // legacy zeroes (extran9: storage node depth 1.5e-7 ft off from step 1).
+        if (std::fabs(q) < constants::FLOW_TOL) q = 0.0;
 
         // Write to decomposed external inflow array (assembled into lat_flow later)
         int ni = ext_inflows_.node_idx[ui];
@@ -243,26 +502,106 @@ void InflowSolver::computeAll(SimulationContext& ctx, double current_date, doubl
         }
     }
 
+    // Pass 2 — pollutant rows: a mass rate into ext_qual_mass, never into the
+    // flow. QualitySolver::addExtInflowLoads() folds these into qual_mass_in.
+    if (np > 0 && !ctx.nodes.ext_qual_mass.empty()) {
+        for (int i = 0; i < ext_inflows_.count; ++i) {
+            auto ui = static_cast(i);
+            const int kind = ext_inflows_.kind[ui];
+            if (kind != static_cast(ExtInflowKind::CONCEN) &&
+                kind != static_cast(ExtInflowKind::MASS))
+                continue;
+            const int p  = ext_inflows_.pollut_idx[ui];
+            const int ni = ext_inflows_.node_idx[ui];
+            if (p < 0 || p >= np || ni < 0 || ni >= ctx.n_nodes()) continue;
+
+            double w = row_value(ui);
+            if (kind == static_cast(ExtInflowKind::CONCEN))
+                w *= ctx.nodes.ext_inflow[static_cast(ni)];
+
+            const auto idx = static_cast(ni) *
+                             static_cast(np) +
+                             static_cast(p);
+            if (idx < ctx.nodes.ext_qual_mass.size())
+                ctx.nodes.ext_qual_mass[idx] += w;
+        }
+    }
+
+    // Pass 2b — U2: reactions-species rows into msx_ext_mass_in (the same
+    // rate convention as ext_qual_mass, one stride per species). Sized on
+    // first use and re-zeroed every step here — this is the only writer.
+    {
+        auto& rx = ctx.reactions;
+        const int nsp = rx.configured ? rx.n_species() : 0;
+        if (nsp > 0 && ctx.n_nodes() > 0) {
+            bool any_msx = false;
+            for (int i = 0; i < ext_inflows_.count && !any_msx; ++i) {
+                const int kind = ext_inflows_.kind[static_cast(i)];
+                any_msx = (kind == static_cast(ExtInflowKind::MSX_CONCEN) ||
+                           kind == static_cast(ExtInflowKind::MSX_MASS));
+            }
+            const auto want = static_cast(ctx.n_nodes()) *
+                              static_cast(nsp);
+            if (any_msx || rx.msx_ext_mass_in.size() == want) {
+                if (rx.msx_ext_mass_in.size() != want) rx.msx_ext_mass_in.assign(want, 0.0);
+                else std::fill(rx.msx_ext_mass_in.begin(), rx.msx_ext_mass_in.end(), 0.0);
+            }
+            if (any_msx) {
+                for (int i = 0; i < ext_inflows_.count; ++i) {
+                    auto ui = static_cast(i);
+                    const int kind = ext_inflows_.kind[ui];
+                    if (kind != static_cast(ExtInflowKind::MSX_CONCEN) &&
+                        kind != static_cast(ExtInflowKind::MSX_MASS))
+                        continue;
+                    const int m  = ext_inflows_.pollut_idx[ui];
+                    const int ni = ext_inflows_.node_idx[ui];
+                    if (m < 0 || m >= nsp || ni < 0 || ni >= ctx.n_nodes()) continue;
+                    if (static_cast(m) < rx.species_is_wall.size() &&
+                        rx.species_is_wall[static_cast(m)])
+                        continue;   // wall species carry no inflow mass
+                    double w = row_value(ui);
+                    if (kind == static_cast(ExtInflowKind::MSX_CONCEN))
+                        w *= ctx.nodes.ext_inflow[static_cast(ni)];
+                    rx.msx_ext_mass_in[static_cast(ni) *
+                                       static_cast(nsp) +
+                                       static_cast(m)] += w;
+                }
+            }
+        }
+    }
+
+    // Pass 3 — __WATER_AGE__ rows (Z1, amendment D-Y4): the row's current
+    // value is the AGE (seconds after conv_factor) of this node's external
+    // inflow. It adds no water and no mass; the EXTERNAL_INFLOW loader
+    // (QualityRouting::addExtInflowLoads → addAgeVolume) reads it in place
+    // of the source table's age. Later rows at the same node win, matching
+    // write order. The state array is sized by the transport engine at
+    // init; the guard below only skips writes on an unsized array (age OFF).
+    if (ctx.options.water_age &&
+        !ctx.water_age_state.node_ext_inflow_age.empty()) {
+        auto& ov = ctx.water_age_state.node_ext_inflow_age;
+        for (int i = 0; i < ext_inflows_.count; ++i) {
+            auto ui = static_cast(i);
+            if (ext_inflows_.kind[ui] != static_cast(ExtInflowKind::AGE))
+                continue;
+            const int ni = ext_inflows_.node_idx[ui];
+            if (ni >= 0 && static_cast(ni) < ov.size())
+                ov[static_cast(ni)] = row_value(ui);
+        }
+    }
+
     // ---- Batch DWF inflows (pattern multiply chain + scatter-add) ----
     // Matches legacy inflow_getDwfInflow: f = monthly * daily * (hourly|weekend)
-    for (int i = 0; i < dwf_inflows_.count; ++i) {
-        auto ui = static_cast(i);
 
+    // Pattern factor of one DWF row at the current date, legacy
+    // inflow_getDwfInflow: f = monthly * daily * (hourly | weekend).
+    auto dwfFactor = [&](std::size_t ui) {
         double factor = 1.0;
-
-        // Monthly pattern
         int pm = dwf_inflows_.pat_monthly[ui];
         if (pm >= 0) factor *= getPatternFactor(pm, month, day, hour);
-
-        // Daily pattern
         int pd = dwf_inflows_.pat_daily[ui];
         if (pd >= 0) factor *= getPatternFactor(pd, month, day, hour);
-
-        // Hourly vs weekend pattern (matches legacy logic exactly):
-        //   if weekend pattern exists:
-        //     if day is Sun(0) or Sat(6): use weekend pattern
-        //     else if hourly pattern exists: use hourly pattern
-        //   else if hourly pattern exists: use hourly pattern
+        // Hourly vs weekend (matches legacy logic exactly):
         int ph = dwf_inflows_.pat_hourly[ui];
         int pw = dwf_inflows_.pat_weekend[ui];
         if (pw >= 0) {
@@ -274,8 +613,20 @@ void InflowSolver::computeAll(SimulationContext& ctx, double current_date, doubl
         } else if (ph >= 0) {
             factor *= getPatternFactor(ph, month, day, hour);
         }
+        return factor;
+    };
 
-        double q = factor * dwf_inflows_.avg_value[ui];
+    // Pass 1 — FLOW rows only. A pollutant DWF row is a concentration, not
+    // water — legacy addDryWeatherInflows (routing.c) reads only the FLOW
+    // row for the node's hydrograph. Adding the TN/BOD5 baselines here
+    // inflated lateral inflow (wq-mass-extran1: node 80408 got 47+2 cfs).
+    for (int i = 0; i < dwf_inflows_.count; ++i) {
+        auto ui = static_cast(i);
+        if (!dwf_inflows_.is_flow[ui]) continue;
+
+        double q = dwfFactor(ui) * dwf_inflows_.avg_value[ui];
+        // PARITY routing.c addDryWeatherInflows: `if (fabs(q) < FLOW_TOL) q = 0`.
+        if (std::fabs(q) < constants::FLOW_TOL) q = 0.0;
 
         // Write to decomposed DWF inflow array (assembled into lat_flow later)
         int ni = dwf_inflows_.node_idx[ui];
@@ -283,6 +634,67 @@ void InflowSolver::computeAll(SimulationContext& ctx, double current_date, doubl
             ctx.nodes.dwf_inflow[static_cast(ni)] += q;
         }
     }
+
+    // Pass 2 — pollutant rows (legacy addDryWeatherInflows pollutant portion,
+    // routing.c:668-688): each row adds q · (pattern-adjusted concentration)
+    // and subtracts the global-default q · dwfConcen it displaces. The net
+    // adjustment lands in nodes.dwf_qual_mass; QualityRouting adds it on top
+    // of the global-default DWF load it already computes from c_dwf.
+    if (np > 0 && !ctx.nodes.dwf_qual_mass.empty()) {
+        for (int i = 0; i < dwf_inflows_.count; ++i) {
+            auto ui = static_cast(i);
+            const int p = dwf_inflows_.pollut_idx[ui];
+            if (p < 0 || p >= np) continue;
+            const int ni = dwf_inflows_.node_idx[ui];
+            if (ni < 0 || ni >= ctx.n_nodes()) continue;
+
+            const double q = ctx.nodes.dwf_inflow[static_cast(ni)];
+            if (q <= 0.0) continue;   // legacy: no DWF quality without DWF flow
+
+            double w = q * (dwfFactor(ui) * dwf_inflows_.avg_value[ui]);
+            const double c_glob = ctx.pollutants.c_dwf[static_cast(p)];
+            if (c_glob > 0.0) w -= q * c_glob;
+
+            const auto idx = static_cast(ni) *
+                             static_cast(np) +
+                             static_cast(p);
+            if (idx < ctx.nodes.dwf_qual_mass.size())
+                ctx.nodes.dwf_qual_mass[idx] += w;
+        }
+    }
+
+    // Pass 2b — U2: species DWF rows: q · concentration into msx_ext_mass_in
+    // (no global default to displace — species have no c_dwf column).
+    {
+        auto& rx = ctx.reactions;
+        const int nsp = rx.configured ? rx.n_species() : 0;
+        if (nsp > 0 && ctx.n_nodes() > 0) {
+            bool any = false;
+            for (int i = 0; i < dwf_inflows_.count && !any; ++i)
+                any = dwf_inflows_.msx_idx[static_cast(i)] >= 0;
+            if (any) {
+                const auto want = static_cast(ctx.n_nodes()) *
+                                  static_cast(nsp);
+                if (rx.msx_ext_mass_in.size() != want) rx.msx_ext_mass_in.assign(want, 0.0);
+                for (int i = 0; i < dwf_inflows_.count; ++i) {
+                    auto ui = static_cast(i);
+                    const int m = dwf_inflows_.msx_idx[ui];
+                    if (m < 0 || m >= nsp) continue;
+                    if (static_cast(m) < rx.species_is_wall.size() &&
+                        rx.species_is_wall[static_cast(m)])
+                        continue;
+                    const int ni = dwf_inflows_.node_idx[ui];
+                    if (ni < 0 || ni >= ctx.n_nodes()) continue;
+                    const double q = ctx.nodes.dwf_inflow[static_cast(ni)];
+                    if (q <= 0.0) continue;
+                    rx.msx_ext_mass_in[static_cast(ni) *
+                                       static_cast(nsp) +
+                                       static_cast(m)] +=
+                        q * (dwfFactor(ui) * dwf_inflows_.avg_value[ui]);
+                }
+            }
+        }
+    }
 }
 
 } // namespace inflow
diff --git a/src/engine/hydrology/Inflow.hpp b/src/engine/hydrology/Inflow.hpp
index ac1c73eb6..34d0bd3c0 100644
--- a/src/engine/hydrology/Inflow.hpp
+++ b/src/engine/hydrology/Inflow.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Inflow.hpp
  * @brief External inflows, dry weather flows, and RDII at nodes.
@@ -12,12 +28,13 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_INFLOW_HPP
 #define OPENSWMM_INFLOW_HPP
 
+#include 
 #include 
 
 namespace openswmm {
@@ -39,6 +56,26 @@ constexpr int WEEKEND_PATTERN = 3;
 // Per-node external inflow definition (SoA)
 // ============================================================================
 
+/// `[INFLOWS]` row kind. A row is either the node's direct flow hydrograph or
+/// a pollutant load riding on it — the two must not be summed together.
+/// @see Legacy: FLOW_INFLOW / CONCEN_INFLOW / MASS_INFLOW in enums.h
+enum class ExtInflowKind : int {
+    FLOW   = 0,  ///< Volumetric inflow (constituent FLOW)
+    CONCEN = 1,  ///< Pollutant concentration; mass rate = value * node flow
+    MASS   = 2,  ///< Pollutant mass rate directly
+    /// Z1 (amendment D-Y4): a row naming the reserved species
+    /// `__WATER_AGE__`. Its value is the AGE (hours in the file, seconds
+    /// after conv_factor) carried by the node's external inflow — it adds
+    /// no water and no mass; the EXTERNAL_INFLOW loader books q·age with
+    /// this age instead of the source table's.
+    AGE    = 3,
+    /// U2 (2026-09-07): a row naming a reactions-component species.
+    /// pollut_idx holds the SPECIES index (0..n_species-1). The load goes to
+    /// ReactionData::msx_ext_mass_in, never to the pollutant arrays.
+    MSX_CONCEN = 4,
+    MSX_MASS   = 5
+};
+
 struct ExtInflowSoA {
     int count = 0;
     std::vector    node_idx;       ///< Which node this inflow applies to
@@ -47,6 +84,13 @@ struct ExtInflowSoA {
     std::vector baseline;       ///< Constant baseline value
     std::vector scale_factor;   ///< Timeseries scaling factor
     std::vector conv_factor;    ///< Units conversion factor
+    /// Row kind (see ExtInflowKind). Without this every row — including
+    /// pollutant rows — was added to the node's flow, injecting phantom water.
+    std::vector    kind;
+    /// Pollutant index for CONCEN/MASS rows, SPECIES index for MSX_CONCEN /
+    /// MSX_MASS rows; -1 for FLOW rows (and for a constituent name that
+    /// matches no declared pollutant or species).
+    std::vector    pollut_idx;
 
     void resize(int n);
 };
@@ -63,6 +107,15 @@ struct DwfInflowSoA {
     std::vector    pat_daily;      ///< Daily pattern index (-1 = none)
     std::vector    pat_hourly;     ///< Hourly pattern index (-1 = none)
     std::vector    pat_weekend;    ///< Weekend pattern index (-1 = none)
+    /// Constituent is FLOW (legacy TDwfInflow.param == -1). A pollutant DWF
+    /// row is a CONCENTRATION — it must never be added as water (legacy
+    /// addDryWeatherInflows reads only the FLOW row for the hydrograph).
+    std::vector is_flow;
+    /// Pollutant index for a non-FLOW row (-1 when FLOW or unmatched).
+    std::vector     pollut_idx;
+    /// U2: reactions-species index for a row naming a species (-1 else).
+    /// Its concentration rides the node's DWF flow into msx_ext_mass_in.
+    std::vector     msx_idx;
 
     void resize(int n);
 };
diff --git a/src/engine/hydrology/LID.cpp b/src/engine/hydrology/LID.cpp
index eb49bec3f..0b0b67436 100644
--- a/src/engine/hydrology/LID.cpp
+++ b/src/engine/hydrology/LID.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LID.cpp
  * @brief LID control modules — batch-oriented, type-grouped.
@@ -5,11 +21,12 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "LID.hpp"
 #include "../core/SimulationContext.hpp"
+#include "../core/DateTime.hpp"
 #include "../core/UnitConversion.hpp"
 #include 
 #include 
@@ -20,53 +37,6 @@ namespace lid {
 
 // static constexpr double MINFLOW = 2.3e-8;   // 0.001 in/hr in ft/sec
 
-// ============================================================================
-// Shared helpers for drain rate and storage exfiltration
-// ============================================================================
-
-/// Compute drain outflow rate with hysteresis (matching legacy getStorageDrainRate).
-/// Updates drain_open state for next timestep.
-///
-/// coeff/expon are kept in the user's flow-depth units (as the legacy engine
-/// does — they cannot be pre-scaled because the scale depends on `expon`), so
-/// the head is converted ft → user depth, the underdrain equation is evaluated
-/// in user rate units, and the result is converted back to internal ft/sec
-/// (issue #102). ucfRainDepth = UCF(RAINDEPTH), ucfRainfall = UCF(RAINFALL).
-static double getDrainRate(double head, double coeff, double expon,
-                           double offset, double hOpen, double hClose,
-                           int& drain_open_state,
-                           double ucfRainDepth, double ucfRainfall) {
-    double h = head - offset;
-    if (h <= 0.0) { drain_open_state = 0; return 0.0; }
-
-    // Hysteresis: drain opens when head >= hOpen, closes when head < hClose
-    if (hOpen > 0.0 || hClose > 0.0) {
-        if (drain_open_state) {
-            if (h < hClose) { drain_open_state = 0; return 0.0; }
-        } else {
-            if (h < hOpen) return 0.0;
-            drain_open_state = 1;
-        }
-    }
-
-    if (coeff <= 0.0) return 0.0;
-    double h_user = h * ucfRainDepth;                        // ft → in|mm
-    return coeff * std::pow(h_user, expon) / ucfRainfall;    // → ft/sec
-}
-
-/// Compute storage exfiltration rate with clogging reduction.
-static double getStorageExfil(double kSat, double clogFactor,
-                               double cumInflow) {
-    if (kSat <= 0.0) return 0.0;
-    double rate = kSat;
-    if (clogFactor > 0.0 && cumInflow > 0.0) {
-        double reduction = cumInflow / clogFactor;
-        reduction = std::min(reduction, 1.0);
-        rate *= (1.0 - reduction);
-    }
-    return rate;
-}
-
 void LIDGroupSoA::resize(int n) {
     count = n;
     auto un = static_cast(n);
@@ -125,7 +95,10 @@ void LIDGroupSoA::resize(int n) {
     surf_alpha.assign(un, 0.0);
     surf_side_slope.assign(un, 0.0);
     full_width.assign(un, 0.0);
+    unit_area.assign(un, 0.0);
+    unit_width.assign(un, 0.0);
     dry_time.assign(un, 0.0);
+    subcatch_rain.assign(un, 0.0);
 
     surf_depth.assign(un, 0.0);
     soil_moist.assign(un, 0.2);
@@ -135,11 +108,25 @@ void LIDGroupSoA::resize(int n) {
     // drain_rmvl sized separately in model builder (needs n_pollutants)
     drain_rmvl.clear();
 
+    in_surf.assign(un, 0.0);
+    in_pave.assign(un, 0.0);
+    in_soil.assign(un, 0.0);
+    in_stor.assign(un, 0.0);
+
     f_old_surf.assign(un, 0.0);
     f_old_soil.assign(un, 0.0);
     f_old_stor.assign(un, 0.0);
     f_old_pave.assign(un, 0.0);
 
+    soil_infil.assign(un, GreenAmptState{});
+    old_drain_flow.assign(un, 0.0);
+    is_wet.assign(un, 0);
+    rpt_path.assign(un, std::string{});
+    rpt_surf_infil.assign(un, 0.0);
+    rpt_pave_perc.assign(un, 0.0);
+    rpt_soil_perc.assign(un, 0.0);
+    can_overflow.assign(un, 1);
+    drainmat_alpha.assign(un, 0.0);
     surface_runoff.assign(un, 0.0);
     drain_flow.assign(un, 0.0);
     evap_loss.assign(un, 0.0);
@@ -216,6 +203,22 @@ void LIDSolver::init(SimulationContext& ctx) {
     for (int t = 0; t < N_LID_TYPES; ++t)
         groups_[static_cast(t)].resize(type_counts[static_cast(t)]);
 
+    // The group's unit-conversion pair feeds the DRAIN LAW itself —
+    // getStorageDrainRate computes `head *= ucf_raindepth` and
+    // `outflow /= ucf_rainfall` (legacy lidproc.c:1399-1414, "underdrain
+    // flow equation in user units"), and the roof-disconnection path caps
+    // at `drain_coeff / ucf_rainfall` (lidproc.c:484). The fields carried
+    // HARD-CODED US defaults (12.0, 43200.0) that nothing overwrote, so on
+    // an SI deck every underdrain ran with in/hr factors: for the common
+    // exponent 0.5 that is sqrt(304.8/12) x 25.4/... = 5.04x too much drain
+    // flow. usgs-runoff's rain barrels (FLOW_UNITS LPS) never filled and
+    // never overflowed — legacy books 96.27 mm of surface outflow there, v6
+    // booked 0.00 and pushed everything down the drain.
+    for (auto& g : groups_) {
+        g.ucf_raindepth = ucfRainDepth;
+        g.ucf_rainfall  = ucfRainfall;
+    }
+
     // 3. Populate per-unit parameters from LidControlStore + LidUsageStore
     std::array type_cursor = {};  // next free slot in each group
     for (int j = 0; j < n_usage; ++j) {
@@ -230,27 +233,49 @@ void LIDSolver::init(SimulationContext& ctx) {
         int slot = type_cursor[static_cast(ti)]++;
         auto us = static_cast(slot);
 
-        // Underdrain head/rate conversion factors (used by getDrainRate).
-        g.ucf_raindepth = ucfRainDepth;
-        g.ucf_rainfall  = ucfRainfall;
-
-        // Usage-level fields. Fold the replicate count (Number) into area and
-        // width — legacy aggregates as lidArea = area × number everywhere
-        // (lid.c:1688 runon divisor, 1168 subcatch total, 1445 stored volume).
-        // Scaling BOTH area and width keeps the Manning width/area ratio, so
-        // the depth-based per-unit dynamics are those of one representative
-        // unit while all flux/volume aggregation covers every replicate.
-        int num = (uj < ctx.lid_usage.number.size()) ? ctx.lid_usage.number[uj] : 1;
-        if (num < 1) num = 1;
-        double n_units = static_cast(num);
+        // Usage-level fields. area and full_width are scaled by the
+        // replicate count so g.area is the TOTAL footprint of the usage row
+        // (legacy lidUnit->area * lidUnit->number, lid.c:1688): every
+        // consumer — inflow capture, outflow/drain coupling,
+        // total_lid_area_ft2 — multiplies g.area as the footprint, while the
+        // per-unit flux dynamics only ever use the full_width/area ratio,
+        // which the common factor leaves unchanged (issue #131).
+        //
+        // They are also converted out of the deck's display units, like every
+        // other parameter read above: [LID_USAGE] Area is ft²|m² and Width is
+        // ft|m, while g.area / g.full_width are internal ft² / ft. Without the
+        // division `total_lid_area_ft2` (summed from g.area in initTotals())
+        // holds m² on an SI deck despite its name, and every consumer that
+        // divides a CFS rate by it — the inflow capture below, the full-
+        // coverage runon branch in SWMMEngine::stepRunoff — is off by 1/0.3048²
+        // (issue #102). US decks are unaffected: Ucf[LENGTH][US] is 1.0.
+        double n_units = static_cast(ctx.lid_usage.number[uj]);
         g.subcatch_idx[us] = ctx.lid_usage.subcatch_index[uj];
         g.control_idx[us]  = li;
-        g.area[us]         = ctx.lid_usage.area[uj] * n_units / ucfLength2;  // ft²|m² → ft²
-        g.full_width[us]   = ctx.lid_usage.width[uj] * n_units / ucfLength;  // ft|m → ft
+        g.area[us]         = ctx.lid_usage.area[uj]  * n_units / ucfLength2;
+        g.full_width[us]   = ctx.lid_usage.width[uj] * n_units / ucfLength;
+        // The swale kernel (legacy swaleFluxRates) is NOT invariant under the
+        // n_units scaling: botWidth = topWidth - 2*slope*thickness and the
+        // hydraulic radius use ONE unit's width and area (lidUnit->fullWidth,
+        // lidUnit->area), so the kernel is handed the per-unit values.
+        g.unit_area[us]    = ctx.lid_usage.area[uj]  / ucfLength2;
+        g.unit_width[us]   = ctx.lid_usage.width[uj] / ucfLength;
         g.from_imperv[us]  = ctx.lid_usage.from_imperv[uj] / 100.0;  // % → fraction
         g.from_perv[us]    = (uj < ctx.lid_usage.from_perv.size())
                              ? ctx.lid_usage.from_perv[uj] / 100.0 : 0.0;
         g.to_perv[us]      = ctx.lid_usage.to_perv[uj];
+        if (uj < ctx.lid_usage.rpt_file.size()) {
+            const auto& fp = ctx.lid_usage.rpt_file[uj];
+            g.rpt_path[us] = fp.absolute.empty() ? fp.original : fp.absolute;
+        }
+        // legacy validateLidGroup: no pervious area to return to on a
+        // (near-)fully impervious subcatchment.
+        {
+            const int sc0 = ctx.lid_usage.subcatch_index[uj];
+            if (sc0 >= 0 && static_cast(sc0) < ctx.subcatches.frac_imperv.size() &&
+                ctx.subcatches.frac_imperv[static_cast(sc0)] >= 0.999)
+                g.to_perv[us] = 0;
+        }
 
         // Resolve drain-to target
         if (uj < ctx.lid_usage.drain_to.size() && !ctx.lid_usage.drain_to[uj].empty()) {
@@ -265,14 +290,18 @@ void LIDSolver::init(SimulationContext& ctx) {
         }
 
         // SURFACE layer: [0]=StorHt, [1]=VegVolFrac, [2]=Roughness, [3]=SurfSlope, [4]=SideSlope
+        // Legacy readSurfaceData: a zero storage height zeroes the vegetation
+        // fraction; roughness and slope are kept as given (a zero of either
+        // makes alpha 0 in validateLidProc, which is what lets the surface
+        // overflow instantly instead of draining by Manning's equation).
         if (uli < ctx.lid_controls.surface.size()) {
             const auto& p = ctx.lid_controls.surface[uli];
+            const double veg = (p[0] == 0.0) ? 0.0 : p[1];
             g.surf_store[us]      = p[0] / ucfRainDepth;              // in|mm → ft
-            g.surf_void_frac[us]  = (p[1] > 0.0) ? (1.0 - p[1]) : 1.0;
-            g.surf_rough[us]      = (p[2] > 0.0) ? p[2] : 0.01;
-            g.surf_slope[us]      = (p[3] > 0.0) ? p[3] / 100.0 : 0.01; // % → fraction
+            g.surf_void_frac[us]  = 1.0 - veg;
+            g.surf_rough[us]      = p[2];
+            g.surf_slope[us]      = p[3] / 100.0;                     // % → fraction
             g.surf_side_slope[us] = p[4];  // swale side slope (run/rise)
-            g.surf_alpha[us] = 1.49 * std::sqrt(g.surf_slope[us]) / g.surf_rough[us];
         }
 
         // SOIL layer: [0]=Thick, [1]=Poros, [2]=FC, [3]=WP, [4]=Ksat, [5]=Kslope, [6]=Suction
@@ -331,6 +360,56 @@ void LIDSolver::init(SimulationContext& ctx) {
             g.drainmat_rough[us] = p[2];
         }
 
+        // Legacy validateLidProc (lid.c): the derived parameters, in its
+        // operation order. PHI is legacy's 1.486.
+        {
+            constexpr double PHI = 1.486;
+            if (g.type == LIDType::VEG_SWALE) {
+                g.surf_alpha[us] = (g.surf_rough[us] * g.surf_slope[us] > 0.0 &&
+                                    g.surf_store[us] != 0.0)
+                    ? PHI * std::sqrt(g.surf_slope[us]) / g.surf_rough[us] : 0.0;
+            } else {
+                g.surf_alpha[us] = (g.surf_rough[us] > 0.0)
+                    ? PHI / g.surf_rough[us] * std::sqrt(g.surf_slope[us]) : 0.0;
+            }
+            g.drainmat_alpha[us] = (g.drainmat_rough[us] > 0.0)
+                ? PHI / g.drainmat_rough[us] * std::sqrt(g.surf_slope[us]) : 0.0;
+            // Clogging factors become the treated volume (ft) at which the
+            // layer is fully clogged: void volume times the user's factor.
+            if (g.pave_thick[us] > 0.0)
+                g.pave_clog_factor[us] *= g.pave_thick[us] * g.pave_void[us]
+                                        * (1.0 - g.pave_imperv_frac[us]);
+            if (g.stor_thick[us] > 0.0)
+                g.stor_clog[us] *= g.stor_thick[us] * g.stor_void[us];
+            else {
+                g.stor_clog[us]     = 0.0;
+                g.stor_void[us]     = 1.0;   // no storage layer
+                g.drain_offset[us]  = 0.0;
+            }
+            bool can_overflow = true;
+            switch (g.type) {
+                case LIDType::ROOF_DISCON: can_overflow = false; break;
+                case LIDType::INFIL_TRENCH: case LIDType::PERM_PAVEMENT:
+                case LIDType::BIO_CELL: case LIDType::RAIN_GARDEN:
+                case LIDType::GREEN_ROOF:
+                    if (g.surf_alpha[us] > 0.0) can_overflow = false;
+                    break;
+                default: break;
+            }
+            g.can_overflow[us] = can_overflow ? 1 : 0;
+            if (g.type == LIDType::RAIN_BARREL) {
+                g.stor_void[us] = 1.0;
+                g.stor_ksat[us] = 0.0;
+            }
+            if (g.type == LIDType::GREEN_ROOF) {
+                // The drainage mat IS the storage layer.
+                g.stor_thick[us] = g.drainmat_thick[us];
+                g.stor_void[us]  = g.drainmat_void[us];
+                g.stor_clog[us]  = 0.0;
+                g.stor_ksat[us]  = 0.0;
+            }
+        }
+
         // Initial saturation (percent → fraction, legacy x[2]/100)
         double initSat = ctx.lid_usage.init_sat[uj] / 100.0;
         if (g.soil_thick[us] > 0.0) {
@@ -340,6 +419,36 @@ void LIDSolver::init(SimulationContext& ctx) {
         if (g.stor_thick[us] > 0.0) {
             g.stor_depth[us] = initSat * g.stor_thick[us];
         }
+
+        // The unit's own Green-Ampt state for surface-to-soil infiltration
+        // (legacy validateLidGroup lid.c:1173-1185 + lid_initState): the soil
+        // layer's suction, conductivity and (porosity - wilt point) x
+        // (1 - initSat) as the initial moisture deficit, handed through
+        // grnampt_setParams in the deck's units exactly as legacy does. A
+        // vegetative swale on a Green-Ampt subcatchment takes that
+        // subcatchment's parameters instead. Ks stays 0 otherwise, and the
+        // kernel then falls back to the native-soil rate.
+        g.soil_infil[us] = GreenAmptState{};
+        if (g.soil_thick[us] > 0.0) {
+            infil::grnampt_init(g.soil_infil[us],
+                                g.soil_suction[us] * ucfRainDepth,
+                                g.soil_ksat[us] * ucfRainfall,
+                                (g.soil_poros[us] - g.soil_wp[us]) * (1.0 - initSat),
+                                ctx.options);
+        }
+        if (g.type == LIDType::VEG_SWALE) {
+            const int sc = g.subcatch_idx[us];
+            const auto usc = static_cast(sc);
+            if (sc >= 0 && usc < ctx.subcatches.infil_model.size() &&
+                (ctx.subcatches.infil_model[usc] == 2 || ctx.subcatches.infil_model[usc] == 3)) {
+                infil::grnampt_init(g.soil_infil[us],
+                                    ctx.subcatches.infil_p1[usc], ctx.subcatches.infil_p2[usc],
+                                    ctx.subcatches.infil_p3[usc], ctx.options);
+            }
+        }
+        // legacy lid_initState: dryTime starts at DRY_DAYS
+        g.dry_time[us] = ctx.options.dry_days * 86400.0;
+        g.old_drain_flow[us] = 0.0;
     }
 
     // 4. Initialize water balance initial volumes
@@ -405,968 +514,908 @@ void LIDSolver::init(SimulationContext& ctx) {
                     ctx.subcatches.total_lid_area_ft2[static_cast(sc)] += grp.area[uu];
             }
         }
+        // Legacy lid_validate() (lid.c:1234): snap the LID total to the full
+        // subcatchment area when within 0.1%, so unit-conversion roundoff
+        // cannot leave a sliver of runoff-generating area on a fully
+        // LID-covered subcatchment (issue #131).
+        double ucf_area = ucf::UCF(ucf::LANDAREA, ctx.options);
+        for (int sc = 0; sc < n_sc; ++sc) {
+            auto usc = static_cast(sc);
+            double full_ft2 = ctx.subcatches.area[usc] / ucf_area;
+            if (ctx.subcatches.total_lid_area_ft2[usc] > 0.999 * full_ft2)
+                ctx.subcatches.total_lid_area_ft2[usc] = full_ft2;
+        }
     }
 }
 
-// ============================================================================
-// Batch bio-cell flux rates — VECTORISABLE
-// ============================================================================
-
-void LIDSolver::batchBioCellFlux(LIDGroupSoA& g, double rainfall,
-                                  const double* evap_rate, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        // Surface inflow: per-unit inflow if set, otherwise rainfall
-        double inflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-
-        // Surface evaporation (limited by ponded depth)
-        double surf_evap = std::min(evap_rate[ui], g.surf_depth[ui] / dt);
-
-        // Surface → soil infiltration (Green-Ampt style)
-        double theta = g.soil_moist[ui];
-        double delta = theta - g.soil_fc[ui];
-        double soil_infil = (delta > 0.0)
-            ? g.soil_ksat[ui] * std::exp(g.soil_kslope[ui] * delta)
-            : g.soil_ksat[ui];
-        soil_infil = std::min(soil_infil, g.surf_depth[ui] / dt + inflow - surf_evap);
-        soil_infil = std::max(soil_infil, 0.0);
-
-        // Soil → storage percolation
-        double soil_perc = (theta > g.soil_fc[ui])
-            ? g.soil_ksat[ui] * std::exp(g.soil_kslope[ui] * (theta - g.soil_fc[ui]))
-            : 0.0;
-
-        // Storage → native exfiltration (with clogging reduction)
-        double exfil = getStorageExfil(g.stor_ksat[ui], g.stor_clog[ui],
-                                        g.wb_inflow[ui]);
-
-        // Storage → drain (with hysteresis)
-        double drain = getDrainRate(g.stor_depth[ui], g.drain_coeff[ui],
-                                     g.drain_expon[ui], g.drain_offset[ui],
-                                     g.drain_hopen[ui], g.drain_hclose[ui],
-                                     g.drain_open[ui],
-                                     g.ucf_raindepth, g.ucf_rainfall);
-
-        // Surface overflow
-        double overflow = 0.0;
-        double new_surf = g.surf_depth[ui] + (inflow - surf_evap - soil_infil) * dt;
-        if (new_surf > g.surf_store[ui]) {
-            overflow = (new_surf - g.surf_store[ui]) / dt;
-            new_surf = g.surf_store[ui];
-        }
-        new_surf = std::max(new_surf, 0.0);
-
-        // Update states
-        g.surf_depth[ui] = new_surf;
-
-        // Soil moisture update
-        double soil_thick = g.soil_thick[ui];
-        if (soil_thick > 0.0) {
-            g.soil_moist[ui] += (soil_infil - soil_perc) * dt / soil_thick;
-            g.soil_moist[ui] = std::max(g.soil_moist[ui], g.soil_wp[ui]);
-            g.soil_moist[ui] = std::min(g.soil_moist[ui], g.soil_poros[ui]);
-        }
-
-        // Storage depth update. Bound the storage outflows (exfil + drain) to
-        // the water available this step, else the surplus is clamped out of
-        // storage yet still reported as exfiltration/drain outflow — corrupting
-        // the water balance once those terms are credited to the continuity
-        // (issue #102). Scale both together so their ratio is preserved.
-        double stor_void = g.stor_void[ui];
-        if (stor_void > 0.0) {
-            double avail = soil_perc + g.stor_depth[ui] * stor_void / dt;  // ft/s
-            double out   = exfil + drain;
-            if (out > avail && out > 0.0) {
-                double scale = std::max(avail, 0.0) / out;
-                exfil *= scale;
-                drain *= scale;
-            }
-            g.stor_depth[ui] += (soil_perc - exfil - drain) * dt / stor_void;
-            g.stor_depth[ui] = std::max(g.stor_depth[ui], 0.0);
-            g.stor_depth[ui] = std::min(g.stor_depth[ui], g.stor_thick[ui]);
+double LIDSolver::storedVolume() const {
+    // Same per-unit water content the water-balance init uses above (and
+    // legacy lid_getStoredVolume(), lid.c:1426): void-weighted layer depths
+    // times the unit footprint.
+    double total = 0.0;
+    for (const auto& g : groups_) {
+        for (int i = 0; i < g.count; ++i) {
+            auto ui = static_cast(i);
+            total += (g.surf_depth[ui] * g.surf_void_frac[ui]
+                      + g.soil_moist[ui] * g.soil_thick[ui]
+                      + g.stor_depth[ui] * g.stor_void[ui]
+                      + g.pave_depth[ui] * g.pave_void[ui]
+                          * (1.0 - g.pave_imperv_frac[ui]))
+                     * g.area[ui];
         }
-
-        // Outputs
-        g.surface_runoff[ui] = overflow;
-        g.drain_flow[ui] = drain;
-        g.evap_loss[ui] = surf_evap * dt;
-        g.infil_loss[ui] = exfil * dt;
-
-        // Water balance tracking
-        double totalVolume = g.surf_depth[ui] * g.surf_void_frac[ui]
-                           + g.soil_moist[ui] * g.soil_thick[ui]
-                           + g.stor_depth[ui] * g.stor_void[ui];
-        g.wb_inflow[ui]     += inflow * dt;
-        g.wb_evap[ui]       += surf_evap * dt;
-        g.wb_infil[ui]      += exfil * dt;
-        g.wb_surf_flow[ui]  += overflow * dt;
-        g.wb_drain_flow[ui] += drain * dt;
-        g.wb_final_vol[ui]   = totalVolume;
-        g.vol_treated[ui]   += inflow * dt;
     }
+    return total;
 }
 
 // ============================================================================
-// Batch rain barrel — VECTORISABLE (simplest LID)
+// Legacy lidproc.c — the per-unit kernel, ported op for op
 // ============================================================================
+// Every LID type runs through legacy lidproc_getOutflow(): the layer moisture
+// levels x[SURF, SOIL, STOR, PAVE] are advanced by modpuls_solve() with the
+// type's flux-rate function (one explicit step for every type but the
+// vegetative swale, which iterates with omega = 0.5), the results are
+// clamped to the layer limits, any surface excess above the storage depth
+// spills as overflow, and the unit's evaporation, exfiltration and drain
+// flow are the kernel's shared rates after the step. The kernel below keeps
+// legacy's file-scope shared variables as members and each legacy function
+// as a method, so the arithmetic — including its operation order, its
+// clamp order and every MIN/MAX — is legacy's. The SoA arrays hold the
+// per-unit parameters and state; a unit is a view onto one slot.
+//
+// The earlier per-type batch kernels were schemes of their own (a different
+// soil percolation law, no evaporation cascade, no Green-Ampt on the soil
+// layer, a different drain hysteresis, no Manning surface outflow, ...) and
+// every LID deck in the parity corpus failed; this is what closes them.
+namespace {
+
+constexpr int    L_SURF = 0, L_SOIL = 1, L_STOR = 2, L_PAVE = 3, L_MAX = 4;
+constexpr double L_BIG     = 1.0e10;      // legacy BIG
+constexpr double L_ZERO    = 1.0e-10;     // legacy ZERO
+constexpr double L_STOPTOL = 0.00328;     // legacy STOPTOL (1 mm)
+constexpr double L_MINFLOW = 2.3e-8;      // legacy MINFLOW (0.001 in/hr)
+
+/// Per-unit parameter view (ft, ft/s; legacy TLidProc after validateLidProc).
+struct LidProcView {
+    LIDType type;
+    double surf_thick, surf_void, surf_alpha, surf_side;
+    bool   can_overflow;
+    double pave_thick, pave_void, pave_imperv, pave_ksat, pave_clog,
+           pave_regen_days, pave_regen_deg;
+    double soil_thick, soil_poros, soil_fc, soil_wp, soil_ksat, soil_kslope;
+    double stor_thick, stor_void, stor_ksat, stor_clog;
+    double drain_coeff, drain_expon, drain_offset, drain_delay,
+           drain_hopen, drain_hclose;
+    double dm_thick, dm_alpha;
+    double area, full_width;                  // legacy TLidUnit
+    double ucf_rainfall, ucf_raindepth;
+};
+
+class LegacyLidKernel {
+public:
+    // legacy file-scope shared variables (lidproc.c)
+    double Tstep = 0.0, EvapRate = 0.0, MaxNativeInfil = L_BIG;
+    double SurfaceInflow = 0, SurfaceInfil = 0, SurfaceEvap = 0, SurfaceOutflow = 0;
+    double PaveEvap = 0, PavePerc = 0, SoilEvap = 0, SoilPerc = 0;
+    double StorageInflow = 0, StorageExfil = 0, StorageEvap = 0, StorageDrain = 0;
+    double SurfaceVolume = 0, PaveVolume = 0, SoilVolume = 0, StorageVolume = 0;
+    // the unit (legacy theLidUnit fields the kernel reads / writes)
+    const LidProcView* P = nullptr;
+    LIDGroupSoA* G = nullptr;
+    std::size_t U = 0;
+    double old_runoff_days = 0.0;
+
+    // ---- legacy getSurfaceOutflowRate
+    double getSurfaceOutflowRate(double depth) const {
+        double delta = depth - P->surf_thick;
+        if (delta < 0.0) return 0.0;
+        double outflow = P->surf_alpha * std::pow(delta, 5.0 / 3.0) *
+                         P->full_width / P->area;
+        outflow = std::min(outflow, delta / Tstep);
+        return outflow;
+    }
 
-void LIDSolver::batchBarrelFlux(LIDGroupSoA& g, double rainfall, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        // Covered barrel blocks direct rainfall (legacy: storage.covered)
-        double unit_inflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-        if (g.stor_covered[ui]) unit_inflow = 0.0;
-
-        // Track dry time for drain delay
-        if (unit_inflow > 0.0)
-            g.dry_time[ui] = 0.0;
-        else
-            g.dry_time[ui] += dt;
-
-        // Inflow fills storage
-        double new_depth = g.stor_depth[ui] + unit_inflow * dt;
-
-        // Overflow
-        double overflow = 0.0;
-        if (new_depth > g.stor_thick[ui]) {
-            overflow = (new_depth - g.stor_thick[ui]) / dt;
-            new_depth = g.stor_thick[ui];
-        }
-
-        // Drain — with delay and hysteresis
-        double drain = 0.0;
-        bool delay_ok = (g.drain_delay[ui] <= 0.0 || g.dry_time[ui] >= g.drain_delay[ui]);
-        if (delay_ok) {
-            drain = getDrainRate(new_depth, g.drain_coeff[ui], g.drain_expon[ui],
-                                 g.drain_offset[ui], g.drain_hopen[ui],
-                                 g.drain_hclose[ui], g.drain_open[ui],
-                                 g.ucf_raindepth, g.ucf_rainfall);
-            drain = std::min(drain, new_depth / dt);
-            new_depth -= drain * dt;
-        }
+    // ---- legacy getSurfaceOverflowRate (clamps the depth it is handed)
+    double getSurfaceOverflowRate(double* surfaceDepth) const {
+        double delta = *surfaceDepth - P->surf_thick;
+        if (delta <= 0.0) return 0.0;
+        *surfaceDepth = P->surf_thick;
+        return delta * P->surf_void / Tstep;
+    }
 
-        // Exfiltration through storage floor (Euler is exact for constant-rate ODE)
-        double exfil = 0.0;
-        if (g.stor_void[ui] > 0.0 && new_depth > 0.0) {
-            double ksat_eff = getStorageExfil(g.stor_ksat[ui], g.stor_clog[ui],
-                                              g.wb_inflow[ui]);
-            if (ksat_eff > 0.0) {
-                double exfil_depth = (ksat_eff / g.stor_void[ui]) * dt;
-                exfil_depth = std::min(exfil_depth, new_depth);
-                new_depth -= exfil_depth;
-                exfil = exfil_depth * g.stor_void[ui];
+    // ---- legacy getPavementPermRate
+    double getPavementPermRate() {
+        double permReduction = 0.0;
+        double clogFactor = P->pave_clog;
+        double regenDays  = P->pave_regen_days;
+        if (clogFactor > 0.0) {
+            if (regenDays > 0.0) {
+                if (old_runoff_days >= G->next_regen_day[U]) {
+                    G->vol_treated[U] *= (1.0 - P->pave_regen_deg);
+                    G->next_regen_day[U] += regenDays;
+                }
             }
+            permReduction = G->vol_treated[U] / clogFactor;
+            permReduction = std::min(permReduction, 1.0);
         }
-
-        g.stor_depth[ui] = std::max(new_depth, 0.0);
-        g.surface_runoff[ui] = overflow;
-        g.drain_flow[ui] = drain;
-        g.evap_loss[ui] = 0.0;
-        g.infil_loss[ui] = (dt > 0.0) ? exfil / dt : 0.0;
-
-        // Water balance tracking
-        g.wb_inflow[ui]     += unit_inflow * dt;
-        g.wb_evap[ui]       += 0.0;
-        g.wb_infil[ui]      += exfil;
-        g.wb_surf_flow[ui]  += overflow * dt;
-        g.wb_drain_flow[ui] += drain * dt;
-        g.wb_final_vol[ui]   = g.stor_depth[ui];
-        g.vol_treated[ui]   += unit_inflow * dt;
+        return P->pave_ksat * (1.0 - permReduction);
     }
-}
-
-// ============================================================================
-// Batch infiltration trench — VECTORISABLE
-// Gap #24: surface drains directly to storage (no soil layer).
-// Matches legacy lidproc.c trenchFluxRates().
-// ============================================================================
-
-void LIDSolver::batchInfilTrenchFlux(LIDGroupSoA& g, double rainfall,
-                                      const double* evap_rate, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        double surfaceDepth = g.surf_depth[ui];
-        double storageDepth = g.stor_depth[ui];
-        double storThick    = g.stor_thick[ui];
-        double storVoid     = g.stor_void[ui];
-        double surfVoid     = g.surf_void_frac[ui];
-
-        // Per-unit inflow (rainfall on surface + routed runoff)
-        double surfaceInflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-
-        // Convert depths to volumes (ft of equivalent water depth)
-        double surfaceVolume = surfaceDepth * surfVoid;
-        double storageVolume = storageDepth * storVoid;
-
-        // --- Evaporation cascade (matching legacy getEvapRates with pervFrac=1) ---
-        // Surface evap first; storage evap only when surface is dry.
-        double surfaceEvap = std::min(evap_rate[ui], surfaceVolume / dt);
-        surfaceEvap = std::max(0.0, surfaceEvap);
-        double storageEvap = 0.0;
-        if (surfaceDepth <= 0.0) {
-            double availEvap = std::max(0.0, evap_rate[ui] - surfaceEvap);
-            storageEvap = std::min(availEvap, storageVolume / dt);
-        }
-
-        // --- Storage inflow: all surface volume drains to storage each step ---
-        // Matching legacy: StorageInflow = SurfaceInflow + SurfaceVolume/Tstep
-        double storageInflow = surfaceInflow + surfaceVolume / dt;
-
-        // --- Exfiltration from storage to native soil (with clogging) ---
-        double storageExfil = getStorageExfil(g.stor_ksat[ui], g.stor_clog[ui],
-                                               g.wb_inflow[ui]);
-
-        // --- Underdrain flow ---
-        double storageDrain = 0.0;
-        if (g.drain_coeff[ui] > 0.0)
-            storageDrain = getDrainRate(storageDepth, g.drain_coeff[ui],
-                                        g.drain_expon[ui], g.drain_offset[ui],
-                                        g.drain_hopen[ui], g.drain_hclose[ui],
-                                        g.drain_open[ui],
-                                        g.ucf_raindepth, g.ucf_rainfall);
-
-        // --- Limit exfiltration (can't exceed available inflow + stored volume) ---
-        double maxRate = storageInflow - storageEvap
-                       + storageDepth * storVoid / dt;
-        storageExfil = std::min(storageExfil, maxRate);
-        storageExfil = std::max(0.0, storageExfil);
-
-        // --- Limit underdrain (matching legacy limit logic) ---
-        if (storageDrain > 0.0) {
-            maxRate = -storageExfil - storageEvap;
-            if (storageDepth >= storThick) maxRate += storageInflow;
-            if (g.drain_offset[ui] <= storageDepth)
-                maxRate += (storageDepth - g.drain_offset[ui]) * storVoid / dt;
-            maxRate = std::max(0.0, maxRate);
-            storageDrain = std::min(storageDrain, maxRate);
-        }
-
-        // --- Limit storage inflow to available capacity ---
-        maxRate = (storThick - storageDepth) * storVoid / dt
-                + storageExfil + storageEvap + storageDrain;
-        storageInflow = std::min(storageInflow, maxRate);
-
-        // Surface infil equals storage inflow (no soil layer)
-        double surfaceInfil = storageInflow;
-
-        // --- Surface outflow (Manning's over depression storage) ---
-        double surfaceOutflow = 0.0;
-        double excess = surfaceDepth - g.surf_store[ui];
-        if (excess > 0.0 && g.surf_alpha[ui] > 0.0
-            && g.full_width[ui] > 0.0 && g.area[ui] > 0.0) {
-            surfaceOutflow = g.surf_alpha[ui] * std::pow(excess, 5.0 / 3.0)
-                           * g.full_width[ui] / g.area[ui];
-            surfaceOutflow = std::min(surfaceOutflow, excess / dt);
-        }
 
-        // --- Euler integration ---
-        double fSurf = (surfaceInflow - surfaceEvap - surfaceInfil - surfaceOutflow)
-                       / surfVoid;
-        double fStor = (storageInflow - storageEvap - storageExfil - storageDrain)
-                       / storVoid;
-
-        double newSurf = std::max(0.0, surfaceDepth + fSurf * dt);
-        double newStor = std::max(0.0, std::min(storThick, storageDepth + fStor * dt));
-
-        g.surf_depth[ui]    = newSurf;
-        g.stor_depth[ui]    = newStor;
-
-        // Outputs
-        g.surface_runoff[ui] = surfaceOutflow;
-        g.drain_flow[ui]     = storageDrain;
-        g.evap_loss[ui]      = surfaceEvap + storageEvap;
-        g.infil_loss[ui]     = storageExfil;
-
-        // Water balance
-        g.wb_inflow[ui]     += surfaceInflow * dt;
-        g.wb_evap[ui]       += (surfaceEvap + storageEvap) * dt;
-        g.wb_infil[ui]      += storageExfil * dt;
-        g.wb_surf_flow[ui]  += surfaceOutflow * dt;
-        g.wb_drain_flow[ui] += storageDrain * dt;
-        g.wb_final_vol[ui]   = newSurf * surfVoid + newStor * storVoid;
-        g.vol_treated[ui]   += surfaceInflow * dt;
+    // ---- legacy getSoilPercRate
+    double getSoilPercRate(double theta) const {
+        if (theta <= P->soil_fc) return 0.0;
+        double delta = P->soil_poros - theta;
+        return P->soil_ksat * std::exp(-delta * P->soil_kslope);
     }
-}
-
-// ============================================================================
-// Batch vegetative swale — VECTORISABLE
-// ============================================================================
 
-void LIDSolver::batchSwaleFlux(LIDGroupSoA& g, double rainfall,
-                                const double* evap_rate, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        double inflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-        double surf_evap = std::min(evap_rate[ui], g.surf_depth[ui] / dt);
-
-        // Soil infiltration
-        double infil = g.soil_ksat[ui];
-        infil = std::min(infil, g.surf_depth[ui] / dt + inflow - surf_evap);
-        infil = std::max(infil, 0.0);
-
-        // Manning's surface outflow: Q = (1/n) * depth^(5/3) * sqrt(slope)
-        double excess = g.surf_depth[ui] - g.surf_store[ui];
-        double runoff = 0.0;
-        if (excess > 0.0 && g.surf_rough[ui] > 0.0) {
-            runoff = std::pow(excess, 5.0 / 3.0) * std::sqrt(g.surf_slope[ui])
-                     / g.surf_rough[ui];
+    // ---- legacy getStorageExfilRate
+    double getStorageExfilRate() const {
+        double infil = 0.0;
+        double clogFactor = 0.0;
+        if (P->stor_ksat == 0.0) return 0.0;
+        if (MaxNativeInfil == 0.0) return 0.0;
+        clogFactor = P->stor_clog;
+        if (clogFactor > 0.0) {
+            clogFactor = G->wb_inflow[U] / clogFactor;
+            clogFactor = std::min(clogFactor, 1.0);
         }
-
-        // Update surface depth
-        double new_surf = g.surf_depth[ui] + (inflow - surf_evap - infil - runoff) * dt;
-        g.surf_depth[ui] = std::max(new_surf, 0.0);
-
-        g.surface_runoff[ui] = runoff;
-        g.drain_flow[ui] = 0.0;
-        g.evap_loss[ui] = surf_evap * dt;
-        g.infil_loss[ui] = infil * dt;
-
-        // Water balance tracking
-        g.wb_inflow[ui]     += inflow * dt;
-        g.wb_evap[ui]       += surf_evap * dt;
-        g.wb_infil[ui]      += infil * dt;
-        g.wb_surf_flow[ui]  += runoff * dt;
-        g.wb_drain_flow[ui] += 0.0;
-        g.wb_final_vol[ui]   = g.surf_depth[ui] * g.surf_void_frac[ui];
-        g.vol_treated[ui]   += inflow * dt;
+        infil = P->stor_ksat * (1.0 - clogFactor);
+        return std::min(infil, MaxNativeInfil);
     }
-}
-
-// ============================================================================
-// Batch swale with Modified Puls (omega=0.5, iterative)
-// ============================================================================
-// Legacy reference: modpuls_solve() in lidproc.c with VEG_SWALE omega=0.5.
-// The swale Manning's equation is nonlinear — iteration is needed for
-// the trapezoid-rule time weighting to converge.
-
-static constexpr double STOPTOL = 0.00328;  // 1 mm in ft
-static constexpr int    MAX_ITERATIONS = 20;
-
-void LIDSolver::batchSwaleModPuls(LIDGroupSoA& g, double rainfall,
-                                   const double* evap_rate, double dt) {
-    constexpr double omega = 0.5;
-
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        double inflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
 
-        // Save initial state
-        double x_old = g.surf_depth[ui];
-        double x_prev = x_old;
-        double f_old = g.f_old_surf[ui];  // flux rate from previous timestep
-
-        // Iterate Modified Puls
-        double x = x_old;
-        double f_new = 0.0;
-        for (int iter = 0; iter < MAX_ITERATIONS; ++iter) {
-            // Compute flux rates at current state
-            double surf_evap = std::min(evap_rate[ui], std::max(x, 0.0) / dt);
-            double soil_infil = g.soil_ksat[ui];
-            soil_infil = std::min(soil_infil, std::max(x, 0.0) / dt + inflow - surf_evap);
-            soil_infil = std::max(soil_infil, 0.0);
-
-            double excess = x - g.surf_store[ui];
-            double runoff = 0.0;
-            if (excess > 0.0 && g.surf_rough[ui] > 0.0) {
-                runoff = std::pow(excess, 5.0 / 3.0) * std::sqrt(g.surf_slope[ui])
-                         / g.surf_rough[ui];
+    // ---- legacy getStorageDrainRate
+    double getStorageDrainRate(double storageDepth, double soilTheta,
+                               double paveDepth, double surfaceDepth) const {
+        double head = storageDepth;
+        double outflow = 0.0;
+        const double paveThickness    = P->pave_thick;
+        const double soilThickness    = P->soil_thick;
+        const double soilPorosity     = P->soil_poros;
+        const double soilFieldCap     = P->soil_fc;
+        const double storageThickness = P->stor_thick;
+        if (storageDepth >= storageThickness) {
+            if (soilThickness > 0.0) {
+                if (soilTheta > soilFieldCap) {
+                    head += (soilTheta - soilFieldCap) /
+                            (soilPorosity - soilFieldCap) * soilThickness;
+                    if (soilTheta >= soilPorosity) {
+                        if (paveThickness > 0.0) {
+                            head += paveDepth;
+                            if (paveDepth >= paveThickness) head += surfaceDepth;
+                        }
+                        else head += surfaceDepth;
+                    }
+                }
+            }
+            else if (paveThickness > 0.0) {
+                head += paveDepth;
+                if (paveDepth >= paveThickness) head += surfaceDepth;
             }
-
-            // Net flux = dx/dt
-            f_new = inflow - surf_evap - soil_infil - runoff;
-
-            // Modified Puls update: x = x_old + (omega*f_old + (1-omega)*f_new) * dt
-            x = x_old + (omega * f_old + (1.0 - omega) * f_new) * dt;
-            x = std::max(x, 0.0);
-
-            // Check convergence
-            if (std::abs(x - x_prev) <= STOPTOL) break;
-            x_prev = x;
         }
-
-        // Save new flux rate for next timestep
-        g.f_old_surf[ui] = f_new;
-        g.surf_depth[ui] = x;
-
-        // Compute final outputs at converged state for reporting
-        double surf_evap = std::min(evap_rate[ui], std::max(x, 0.0) / dt);
-        double soil_infil = g.soil_ksat[ui];
-        soil_infil = std::min(soil_infil, std::max(x, 0.0) / dt + inflow - surf_evap);
-        soil_infil = std::max(soil_infil, 0.0);
-        double excess = x - g.surf_store[ui];
-        double runoff = 0.0;
-        if (excess > 0.0 && g.surf_rough[ui] > 0.0) {
-            runoff = std::pow(excess, 5.0 / 3.0) * std::sqrt(g.surf_slope[ui])
-                     / g.surf_rough[ui];
+        if (G->old_drain_flow[U] == 0.0 && head <= P->drain_hopen) return 0.0;
+        if (G->old_drain_flow[U] > 0.0 && head <= P->drain_hclose) return 0.0;
+        head -= P->drain_offset;
+        if (head > L_ZERO) {
+            head *= P->ucf_raindepth;
+            outflow = P->drain_coeff * std::pow(head, P->drain_expon);
+            // (a user-supplied drain control curve is not carried by the
+            //  control store; legacy would multiply by its lookup here)
+            outflow /= P->ucf_rainfall;
         }
-
-        g.surface_runoff[ui] = runoff;
-        g.drain_flow[ui] = 0.0;
-        g.evap_loss[ui] = surf_evap * dt;
-        g.infil_loss[ui] = soil_infil * dt;
-
-        // Water balance: use actual state change to back-compute fluxes
-        // delta_vol = (x - x_old) * void_frac
-        // inflow*dt = evap*dt + infil*dt + runoff*dt + delta_vol
-        // => runoff*dt = inflow*dt - evap*dt - infil*dt - delta_vol
-        double delta_vol = (x - x_old) * g.surf_void_frac[ui];
-        double wb_runoff = inflow * dt - surf_evap * dt - soil_infil * dt - delta_vol;
-        wb_runoff = std::max(wb_runoff, 0.0);
-
-        g.wb_inflow[ui]     += inflow * dt;
-        g.wb_evap[ui]       += surf_evap * dt;
-        g.wb_infil[ui]      += soil_infil * dt;
-        g.wb_surf_flow[ui]  += wb_runoff;
-        g.wb_drain_flow[ui] += 0.0;
-        g.wb_final_vol[ui]   = x * g.surf_void_frac[ui];
-        g.vol_treated[ui]   += inflow * dt;
+        return outflow;
     }
-}
-
-// ============================================================================
-// Batch green roof flux rates — VECTORISABLE
-// ============================================================================
-// Legacy reference: greenRoofFluxRates() in lidproc.c
-// Layers: surface → soil → drainage mat (storage layer used as drain mat)
-// Key difference from biocell: no exfiltration, drainage mat outflow via
-// Manning equation through the mat, storage thickness = drainmat thickness.
 
-void LIDSolver::batchGreenRoofFlux(LIDGroupSoA& g, double rainfall,
-                                    const double* evap_rate, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        double surfaceDepth  = g.surf_depth[ui];
-        double soilTheta     = g.soil_moist[ui];
-        double storageDepth  = g.stor_depth[ui];
-
-        double soilThickness    = g.soil_thick[ui];
-        double soilPorosity     = g.soil_poros[ui];
-        double soilFieldCap     = g.soil_fc[ui];
-        double soilWiltPoint    = g.soil_wp[ui];
-        double surfVoidFrac     = g.surf_void_frac[ui];
-
-        // For green roof, storage layer represents the drainage mat
-        double storageThickness = g.drainmat_thick[ui];
-        double storageVoidFrac  = g.drainmat_void[ui];
-
-        // --- convert moisture levels to volumes ---
-        double surfaceVolume = surfaceDepth * surfVoidFrac;
-        double soilVolume    = soilTheta * soilThickness;
-        double storageVolume = storageDepth * storageVoidFrac;
-
-        // --- inflow ---
-        double surfaceInflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-
-        // --- surface infiltration (Green-Ampt style) ---
-        double surfaceInfil;
-        if (soilThickness > 0.0 && g.soil_ksat[ui] > 0.0) {
-            double delta = soilPorosity - soilTheta;
-            surfaceInfil = g.soil_ksat[ui] * std::exp(-delta * g.soil_kslope[ui]);
-        } else {
-            surfaceInfil = 0.0;
+    // ---- legacy getDrainMatOutflow
+    double getDrainMatOutflow(double depth) const {
+        double result = SoilPerc;
+        if (P->dm_alpha > 0.0) {
+            result = P->dm_alpha * std::pow(depth, 5.0 / 3.0) *
+                     P->full_width / P->area * P->stor_void;
         }
+        return result;
+    }
 
-        // --- evaporation cascade (legacy getEvapRates with pervFrac=1.0) ---
-        double availEvap = evap_rate[ui];
-        double surfaceEvap = std::min(availEvap, surfaceVolume / dt);
-        surfaceEvap = std::max(0.0, surfaceEvap);
-        availEvap = std::max(0.0, availEvap - surfaceEvap);
-
-        double soilEvap = 0.0;
-        double storageEvap = 0.0;
-        if (surfaceInfil > 0.0) {
-            // no subsurface evap if water is infiltrating
-            soilEvap = 0.0;
-            storageEvap = 0.0;
+    // ---- legacy getEvapRates
+    void getEvapRates(double surfaceVol, double paveVol, double soilVol,
+                      double storageVol, double pervFrac) {
+        double availEvap = EvapRate;
+        SurfaceEvap = std::min(availEvap, surfaceVol / Tstep);
+        SurfaceEvap = std::max(0.0, SurfaceEvap);
+        availEvap = std::max(0.0, (availEvap - SurfaceEvap));
+        availEvap *= pervFrac;
+        if (SurfaceInfil > 0.0) {
+            PaveEvap = 0.0;
+            SoilEvap = 0.0;
+            StorageEvap = 0.0;
         } else {
-            double availSoilVol = soilVolume - soilWiltPoint * soilThickness;
-            soilEvap = std::min(availEvap, std::max(0.0, availSoilVol) / dt);
-            availEvap = std::max(0.0, availEvap - soilEvap);
-            storageEvap = std::min(availEvap, storageVolume / dt);
-        }
-        // no storage evap if soil saturated
-        if (soilTheta >= soilPorosity) storageEvap = 0.0;
-
-        // --- soil percolation rate ---
-        double soilPerc = 0.0;
-        if (soilTheta > soilFieldCap) {
-            double delta = soilPorosity - soilTheta;
-            soilPerc = g.soil_ksat[ui] * std::exp(-delta * g.soil_kslope[ui]);
-        }
-        // limit by available water above field capacity
-        double availVolume = (soilTheta - soilFieldCap) * soilThickness;
-        double maxRate = std::max(availVolume, 0.0) / dt - soilEvap;
-        soilPerc = std::min(soilPerc, maxRate);
-        soilPerc = std::max(soilPerc, 0.0);
-
-        // --- drainage mat outflow (legacy getDrainMatOutflow) ---
-        double storageExfil = 0.0; // green roof has no exfiltration
-        double storageDrain = soilPerc; // default: pass all inflow
-        // Manning equation through drainage mat if alpha > 0
-        double drainmatAlpha = 0.0;
-        if (g.drainmat_rough[ui] > 0.0 && g.surf_slope[ui] > 0.0) {
-            drainmatAlpha = std::sqrt(g.surf_slope[ui]) / g.drainmat_rough[ui];
-        }
-        if (drainmatAlpha > 0.0 && g.full_width[ui] > 0.0 && g.area[ui] > 0.0) {
-            storageDrain = drainmatAlpha * std::pow(storageDepth, 5.0 / 3.0)
-                         * g.full_width[ui] / g.area[ui]
-                         * storageVoidFrac;
+            PaveEvap = std::min(availEvap, paveVol / Tstep);
+            availEvap = std::max(0.0, (availEvap - PaveEvap));
+            SoilEvap = std::min(availEvap, soilVol / Tstep);
+            availEvap = std::max(0.0, (availEvap - SoilEvap));
+            StorageEvap = std::min(availEvap, storageVol / Tstep);
         }
+    }
 
-        // --- limit fluxes for full/not-full conditions ---
+    // ---- legacy roofFluxRates
+    void roofFluxRates(const double x[], double f[]) {
+        double surfaceDepth = x[L_SURF];
+        getEvapRates(surfaceDepth, 0.0, 0.0, 0.0, 1.0);
+        SurfaceVolume = surfaceDepth;
+        SurfaceInfil = 0.0;
+        if (P->surf_alpha > 0.0)
+            SurfaceOutflow = getSurfaceOutflowRate(surfaceDepth);
+        else getSurfaceOverflowRate(&surfaceDepth);
+        StorageDrain = std::min(P->drain_coeff / P->ucf_rainfall, SurfaceOutflow);
+        SurfaceOutflow -= StorageDrain;
+        f[L_SURF] = (SurfaceInflow - SurfaceEvap - StorageDrain - SurfaceOutflow);
+    }
+
+    // ---- legacy greenRoofFluxRates
+    void greenRoofFluxRates(const double x[], double f[]) {
+        double availVolume, maxRate;
+        const double soilThickness    = P->soil_thick;
+        const double storageThickness = P->stor_thick;
+        const double soilPorosity     = P->soil_poros;
+        const double storageVoidFrac  = P->stor_void;
+        const double soilFieldCap     = P->soil_fc;
+        const double soilWiltPoint    = P->soil_wp;
+        const double surfaceDepth = x[L_SURF];
+        const double soilTheta    = x[L_SOIL];
+        const double storageDepth = x[L_STOR];
+        SurfaceVolume = surfaceDepth * P->surf_void;
+        SoilVolume = soilTheta * soilThickness;
+        StorageVolume = storageDepth * storageVoidFrac;
+        availVolume = SoilVolume - soilWiltPoint * soilThickness;
+        getEvapRates(SurfaceVolume, 0.0, availVolume, StorageVolume, 1.0);
+        if (soilTheta >= soilPorosity) StorageEvap = 0.0;
+        SoilPerc = getSoilPercRate(soilTheta);
+        availVolume = (soilTheta - soilFieldCap) * soilThickness;
+        maxRate = std::max(availVolume, 0.0) / Tstep - SoilEvap;
+        SoilPerc = std::min(SoilPerc, maxRate);
+        SoilPerc = std::max(SoilPerc, 0.0);
+        StorageExfil = 0.0;
+        StorageDrain = getDrainMatOutflow(storageDepth);
         if (soilTheta >= soilPorosity && storageDepth >= storageThickness) {
-            // Unit is full: outflow from both layers equals limiting rate
-            maxRate = std::min(soilPerc, storageDrain);
-            soilPerc = maxRate;
-            storageDrain = maxRate;
-            surfaceInfil = std::min(surfaceInfil, maxRate);
+            maxRate = std::min(SoilPerc, StorageDrain);
+            SoilPerc = maxRate;
+            StorageDrain = maxRate;
+            SurfaceInfil = std::min(SurfaceInfil, maxRate);
         } else {
-            // Unit not full
-            // limit drainmat outflow by available storage volume
-            maxRate = storageDepth * storageVoidFrac / dt - storageEvap;
-            if (storageDepth >= storageThickness) maxRate += soilPerc;
+            maxRate = storageDepth * storageVoidFrac / Tstep - StorageEvap;
+            if (storageDepth >= storageThickness) maxRate += SoilPerc;
             maxRate = std::max(maxRate, 0.0);
-            storageDrain = std::min(storageDrain, maxRate);
-
-            // limit soil perc by unused storage volume
-            maxRate = (storageThickness - storageDepth) * storageVoidFrac / dt
-                    + storageDrain + storageEvap;
-            soilPerc = std::min(soilPerc, maxRate);
-
-            // limit surface infil so soil porosity not exceeded
-            maxRate = (soilPorosity - soilTheta) * soilThickness / dt
-                    + soilPerc + soilEvap;
-            surfaceInfil = std::min(surfaceInfil, maxRate);
-        }
-
-        // --- surface outflow (Manning's over surface storage) ---
-        double surfaceOutflow = 0.0;
-        double delta_surf = surfaceDepth - g.surf_store[ui];
-        if (delta_surf > 0.0 && g.surf_alpha[ui] > 0.0
-            && g.full_width[ui] > 0.0 && g.area[ui] > 0.0) {
-            surfaceOutflow = g.surf_alpha[ui] * std::pow(delta_surf, 5.0 / 3.0)
-                           * g.full_width[ui] / g.area[ui];
-            surfaceOutflow = std::min(surfaceOutflow, delta_surf / dt);
-        }
-
-        // --- Euler integration of layer depths ---
-        // Surface
-        double f_surf = (surfaceInflow - surfaceEvap - surfaceInfil - surfaceOutflow)
-                       / surfVoidFrac;
-        double newSurf = surfaceDepth + f_surf * dt;
-        newSurf = std::max(newSurf, 0.0);
-
-        // Soil moisture
-        double f_soil = 0.0;
-        if (soilThickness > 0.0) {
-            f_soil = (surfaceInfil - soilEvap - soilPerc) / soilThickness;
-        }
-        double newTheta = soilTheta + f_soil * dt;
-        newTheta = std::max(newTheta, soilWiltPoint);
-        newTheta = std::min(newTheta, soilPorosity);
-
-        // Storage (drainage mat) depth
-        double f_stor = 0.0;
-        if (storageVoidFrac > 0.0) {
-            f_stor = (soilPerc - storageEvap - storageDrain) / storageVoidFrac;
+            StorageDrain = std::min(StorageDrain, maxRate);
+            maxRate = (storageThickness - storageDepth) * storageVoidFrac / Tstep +
+                      StorageDrain + StorageEvap;
+            SoilPerc = std::min(SoilPerc, maxRate);
+            maxRate = (soilPorosity - soilTheta) * soilThickness / Tstep +
+                      SoilPerc + SoilEvap;
+            SurfaceInfil = std::min(SurfaceInfil, maxRate);
         }
-        double newStor = storageDepth + f_stor * dt;
-        newStor = std::max(newStor, 0.0);
-        newStor = std::min(newStor, storageThickness);
-
-        // --- update state ---
-        g.surf_depth[ui] = newSurf;
-        g.soil_moist[ui] = newTheta;
-        g.stor_depth[ui] = newStor;
-
-        // --- outputs ---
-        g.surface_runoff[ui] = surfaceOutflow;
-        g.drain_flow[ui] = storageDrain;
-        double totalEvap = surfaceEvap + soilEvap + storageEvap;
-        g.evap_loss[ui] = totalEvap * dt;
-        g.infil_loss[ui] = storageExfil * dt; // always 0 for green roof
-
-        // --- water balance ---
-        double totalVolume = newSurf * surfVoidFrac
-                           + newTheta * soilThickness
-                           + newStor * storageVoidFrac;
-        g.wb_inflow[ui]     += surfaceInflow * dt;
-        g.wb_evap[ui]       += totalEvap * dt;
-        g.wb_infil[ui]      += storageExfil * dt;
-        g.wb_surf_flow[ui]  += surfaceOutflow * dt;
-        g.wb_drain_flow[ui] += storageDrain * dt;
-        g.wb_final_vol[ui]   = totalVolume;
-        g.vol_treated[ui]   += surfaceInflow * dt;
+        SurfaceOutflow = getSurfaceOutflowRate(surfaceDepth);
+        f[L_SURF] = (SurfaceInflow - SurfaceEvap - SurfaceInfil - SurfaceOutflow) /
+                    P->surf_void;
+        f[L_SOIL] = (SurfaceInfil - SoilEvap - SoilPerc) / P->soil_thick;
+        f[L_STOR] = (SoilPerc - StorageEvap - StorageDrain) / P->stor_void;
     }
-}
 
-// ============================================================================
-// Batch permeable pavement flux rates — VECTORISABLE
-// ============================================================================
-// Legacy reference: pavementFluxRates() in lidproc.c
-// Layers: surface → pavement → (optional soil) → storage → drain/exfil
-
-void LIDSolver::batchPavementFlux(LIDGroupSoA& g, double rainfall,
-                                   const double* evap_rate, double dt) {
-    for (int i = 0; i < g.count; ++i) {
-        auto ui = static_cast(i);
-
-        double surfaceDepth  = g.surf_depth[ui];
-        double paveDepth     = g.pave_depth[ui];
-        double soilTheta     = g.soil_moist[ui];
-        double storageDepth  = g.stor_depth[ui];
-
-        double pervFrac         = 1.0 - g.pave_imperv_frac[ui];
-        double paveVoidFrac     = g.pave_void[ui] * pervFrac;
-        double paveThickness    = g.pave_thick[ui];
-        double soilThickness    = g.soil_thick[ui];
-        double soilPorosity     = g.soil_poros[ui];
-        double soilFieldCap     = g.soil_fc[ui];
-        double soilWiltPoint    = g.soil_wp[ui];
-        double storageThickness = g.stor_thick[ui];
-        double storageVoidFrac  = g.stor_void[ui];
-        double surfVoidFrac     = g.surf_void_frac[ui];
-
-        // --- convert moisture levels to volumes ---
-        double surfaceVolume = surfaceDepth * surfVoidFrac;
-        double paveVolume    = paveDepth * paveVoidFrac;
-        double soilVolume    = soilTheta * soilThickness;
-        double storageVolume = storageDepth * storageVoidFrac;
-
-        // --- inflow ---
-        double surfaceInflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-
-        // --- evaporation cascade (legacy getEvapRates with pervFrac) ---
-        double availEvap = evap_rate[ui];
-        double surfaceEvap = std::min(availEvap, surfaceVolume / dt);
-        surfaceEvap = std::max(0.0, surfaceEvap);
-        availEvap = std::max(0.0, availEvap - surfaceEvap);
-        availEvap *= pervFrac;
-
-        double paveEvap = 0.0;
-        double soilEvap = 0.0;
-        double storageEvap = 0.0;
-
-        // Surface infiltration into pavement (nominal)
-        double surfaceInfil = surfaceInflow + surfaceVolume / dt;
-
-        if (surfaceInfil > 0.0) {
-            paveEvap = 0.0;
-            soilEvap = 0.0;
-            storageEvap = 0.0;
+    // ---- legacy biocellFluxRates
+    void biocellFluxRates(const double x[], double f[]) {
+        double availVolume, maxRate;
+        const double soilThickness    = P->soil_thick;
+        const double soilPorosity     = P->soil_poros;
+        const double soilFieldCap     = P->soil_fc;
+        const double soilWiltPoint    = P->soil_wp;
+        const double storageThickness = P->stor_thick;
+        const double storageVoidFrac  = P->stor_void;
+        const double surfaceDepth = x[L_SURF];
+        const double soilTheta    = x[L_SOIL];
+        const double storageDepth = x[L_STOR];
+        SurfaceVolume = surfaceDepth * P->surf_void;
+        SoilVolume    = soilTheta * soilThickness;
+        StorageVolume = storageDepth * storageVoidFrac;
+        availVolume = SoilVolume - soilWiltPoint * soilThickness;
+        getEvapRates(SurfaceVolume, 0.0, availVolume, StorageVolume, 1.0);
+        if (soilTheta >= soilPorosity) StorageEvap = 0.0;
+        SoilPerc = getSoilPercRate(soilTheta);
+        availVolume = (soilTheta - soilFieldCap) * soilThickness;
+        maxRate = std::max(availVolume, 0.0) / Tstep - SoilEvap;
+        SoilPerc = std::min(SoilPerc, maxRate);
+        SoilPerc = std::max(SoilPerc, 0.0);
+        StorageExfil = getStorageExfilRate();
+        StorageDrain = 0.0;
+        if (P->drain_coeff > 0.0) {
+            StorageDrain = getStorageDrainRate(storageDepth, soilTheta, 0.0,
+                                               surfaceDepth);
+        }
+        if (storageThickness == 0.0) {
+            StorageEvap = 0.0;
+            maxRate = std::min(SoilPerc, StorageExfil);
+            SoilPerc = maxRate;
+            StorageExfil = maxRate;
+            maxRate = (soilPorosity - soilTheta) * soilThickness / Tstep +
+                      SoilPerc + SoilEvap;
+            SurfaceInfil = std::min(SurfaceInfil, maxRate);
         } else {
-            paveEvap = std::min(availEvap, paveVolume / dt);
-            availEvap = std::max(0.0, availEvap - paveEvap);
-            double availSoilVol = soilVolume - soilWiltPoint * soilThickness;
-            soilEvap = std::min(availEvap, std::max(0.0, availSoilVol) / dt);
-            availEvap = std::max(0.0, availEvap - soilEvap);
-            storageEvap = std::min(availEvap, storageVolume / dt);
+            if (soilTheta >= soilPorosity && storageDepth >= storageThickness) {
+                maxRate = StorageExfil + StorageDrain;
+                if (SoilPerc < maxRate) {
+                    maxRate = SoilPerc;
+                    if (maxRate > StorageExfil) StorageDrain = maxRate - StorageExfil;
+                    else {
+                        StorageExfil = maxRate;
+                        StorageDrain = 0.0;
+                    }
+                }
+                else SoilPerc = maxRate;
+                SurfaceInfil = std::min(SurfaceInfil, maxRate);
+            } else {
+                maxRate = SoilPerc - StorageEvap + storageDepth * storageVoidFrac / Tstep;
+                StorageExfil = std::min(StorageExfil, maxRate);
+                StorageExfil = std::max(StorageExfil, 0.0);
+                if (StorageDrain > 0.0) {
+                    maxRate = -StorageExfil - StorageEvap;
+                    if (storageDepth >= storageThickness) maxRate += SoilPerc;
+                    if (P->drain_offset <= storageDepth) {
+                        maxRate += (storageDepth - P->drain_offset) *
+                                   storageVoidFrac / Tstep;
+                    }
+                    maxRate = std::max(maxRate, 0.0);
+                    StorageDrain = std::min(StorageDrain, maxRate);
+                }
+                maxRate = StorageExfil + StorageDrain + StorageEvap +
+                          (storageThickness - storageDepth) *
+                          storageVoidFrac / Tstep;
+                SoilPerc = std::min(SoilPerc, maxRate);
+                maxRate = (soilPorosity - soilTheta) * soilThickness / Tstep +
+                          SoilPerc + SoilEvap;
+                SurfaceInfil = std::min(SurfaceInfil, maxRate);
+            }
         }
+        SurfaceOutflow = getSurfaceOutflowRate(surfaceDepth);
+        f[L_SURF] = (SurfaceInflow - SurfaceEvap - SurfaceInfil - SurfaceOutflow) /
+                    P->surf_void;
+        f[L_SOIL] = (SurfaceInfil - SoilEvap - SoilPerc) / P->soil_thick;
+        if (storageThickness == 0.0) f[L_STOR] = 0.0;
+        else f[L_STOR] = (SoilPerc - StorageEvap - StorageExfil - StorageDrain) /
+                         P->stor_void;
+    }
 
-        // no storage evap if soil or pavement layer saturated
-        if (paveDepth >= paveThickness
-            || (soilThickness > 0.0 && soilTheta >= soilPorosity)) {
-            storageEvap = 0.0;
+    // ---- legacy trenchFluxRates
+    void trenchFluxRates(const double x[], double f[]) {
+        double availVolume = 0.0;
+        double maxRate = 0.0;
+        const double storageThickness = P->stor_thick;
+        const double storageVoidFrac  = P->stor_void;
+        const double surfaceDepth = x[L_SURF];
+        const double storageDepth = x[L_STOR];
+        SurfaceVolume = surfaceDepth * P->surf_void;
+        SoilVolume = 0.0;
+        StorageVolume = storageDepth * storageVoidFrac;
+        availVolume = (storageThickness - storageDepth) * storageVoidFrac;
+        (void)availVolume;
+        getEvapRates(SurfaceVolume, 0.0, 0.0, StorageVolume, 1.0);
+        if (surfaceDepth > 0.0) StorageEvap = 0.0;
+        StorageInflow = SurfaceInflow + SurfaceVolume / Tstep;
+        StorageExfil = getStorageExfilRate();
+        StorageDrain = 0.0;
+        if (P->drain_coeff > 0.0) {
+            StorageDrain = getStorageDrainRate(storageDepth, 0.0, 0.0, surfaceDepth);
         }
-
-        // --- pavement regeneration (reduce clogging at intervals) ---
-        if (g.pave_regen_days[ui] > 0.0 && g.next_regen_day[ui] > 0.0) {
-            // Decrement regen counter by dt (in days)
-            g.next_regen_day[ui] -= dt / 86400.0;
-            if (g.next_regen_day[ui] <= 0.0) {
-                // Regenerate: reduce vol_treated by (1 - regen_degree)
-                g.vol_treated[ui] *= (1.0 - g.pave_regen_deg[ui]);
-                g.next_regen_day[ui] = g.pave_regen_days[ui];
+        maxRate = StorageInflow - StorageEvap + storageDepth * storageVoidFrac / Tstep;
+        StorageExfil = std::min(StorageExfil, maxRate);
+        StorageExfil = std::max(StorageExfil, 0.0);
+        if (StorageDrain > 0.0) {
+            maxRate = -StorageExfil - StorageEvap;
+            if (storageDepth >= storageThickness) maxRate += StorageInflow;
+            if (P->drain_offset <= storageDepth) {
+                maxRate += (storageDepth - P->drain_offset) *
+                           storageVoidFrac / Tstep;
             }
+            maxRate = std::max(maxRate, 0.0);
+            StorageDrain = std::min(StorageDrain, maxRate);
         }
+        maxRate = (storageThickness - storageDepth) * storageVoidFrac / Tstep +
+                  StorageExfil + StorageEvap + StorageDrain;
+        StorageInflow = std::min(StorageInflow, maxRate);
+        SurfaceInfil = StorageInflow;
+        SurfaceOutflow = getSurfaceOutflowRate(surfaceDepth);
+        f[L_SURF] = (SurfaceInflow - SurfaceEvap - StorageInflow - SurfaceOutflow) /
+                    P->surf_void;
+        f[L_STOR] = (StorageInflow - StorageEvap - StorageExfil - StorageDrain) /
+                    P->stor_void;
+        f[L_SOIL] = 0.0;
+    }
 
-        // --- pavement permeability (exponential clog model) ---
-        double permReduction = 0.0;
-        double clogFactor = g.pave_clog_factor[ui];
-        if (clogFactor > 0.0) {
-            permReduction = g.vol_treated[ui] / clogFactor;
-            permReduction = std::min(permReduction, 1.0);
-        }
-        double pavePerc = g.pave_ksat[ui] * (1.0 - permReduction) * pervFrac;
-
-        // surface infil can't exceed pavement permeability
-        surfaceInfil = std::min(surfaceInfil, pavePerc);
-
-        // limit pavement perc by available water
-        double maxRate = paveVolume / dt + surfaceInfil - paveEvap;
+    // ---- legacy pavementFluxRates
+    void pavementFluxRates(const double x[], double f[]) {
+        const double pervFrac = (1.0 - P->pave_imperv);
+        double storageInflow;
+        double availVolume;
+        double maxRate;
+        const double paveVoidFrac     = P->pave_void * pervFrac;
+        const double paveThickness    = P->pave_thick;
+        const double soilThickness    = P->soil_thick;
+        const double soilPorosity     = P->soil_poros;
+        const double soilFieldCap     = P->soil_fc;
+        const double soilWiltPoint    = P->soil_wp;
+        const double storageThickness = P->stor_thick;
+        const double storageVoidFrac  = P->stor_void;
+        const double surfaceDepth = x[L_SURF];
+        const double paveDepth    = x[L_PAVE];
+        const double soilTheta    = x[L_SOIL];
+        const double storageDepth = x[L_STOR];
+        SurfaceVolume = surfaceDepth * P->surf_void;
+        PaveVolume = paveDepth * paveVoidFrac;
+        SoilVolume = soilTheta * soilThickness;
+        StorageVolume = storageDepth * storageVoidFrac;
+        availVolume = SoilVolume - soilWiltPoint * soilThickness;
+        getEvapRates(SurfaceVolume, PaveVolume, availVolume, StorageVolume,
+                     pervFrac);
+        if (paveDepth >= paveThickness ||
+            (soilThickness > 0.0 && soilTheta >= soilPorosity)) StorageEvap = 0.0;
+        SurfaceInfil = SurfaceInflow + (SurfaceVolume / Tstep);
+        PavePerc = getPavementPermRate() * pervFrac;
+        SurfaceInfil = std::min(SurfaceInfil, PavePerc);
+        maxRate = PaveVolume / Tstep + SurfaceInfil - PaveEvap;
         maxRate = std::max(maxRate, 0.0);
-        pavePerc = std::min(pavePerc, maxRate);
-
-        // --- soil percolation ---
-        double soilPerc = 0.0;
+        PavePerc = std::min(PavePerc, maxRate);
         if (soilThickness > 0.0) {
-            if (soilTheta > soilFieldCap) {
-                double delta = soilPorosity - soilTheta;
-                soilPerc = g.soil_ksat[ui] * std::exp(-delta * g.soil_kslope[ui]);
+            SoilPerc = getSoilPercRate(soilTheta);
+            availVolume = (soilTheta - soilFieldCap) * soilThickness;
+            maxRate = std::max(availVolume, 0.0) / Tstep - SoilEvap;
+            SoilPerc = std::min(SoilPerc, maxRate);
+            SoilPerc = std::max(SoilPerc, 0.0);
+        }
+        else SoilPerc = PavePerc;
+        StorageExfil = getStorageExfilRate();
+        StorageDrain = 0.0;
+        if (P->drain_coeff > 0.0) {
+            StorageDrain = getStorageDrainRate(storageDepth, soilTheta, paveDepth,
+                                               surfaceDepth);
+        }
+        if (soilThickness == 0.0 &&
+            storageDepth >= storageThickness &&
+            paveDepth >= paveThickness) {
+            maxRate = StorageEvap + StorageDrain + StorageExfil;
+            if (PavePerc > maxRate) PavePerc = maxRate;
+            else {
+                StorageExfil = std::min(StorageExfil, PavePerc);
+                StorageDrain = PavePerc - StorageExfil;
             }
-            double availVolume = (soilTheta - soilFieldCap) * soilThickness;
-            maxRate = std::max(availVolume, 0.0) / dt - soilEvap;
-            soilPerc = std::min(soilPerc, maxRate);
-            soilPerc = std::max(soilPerc, 0.0);
-        } else {
-            soilPerc = pavePerc;
+            SoilPerc = PavePerc;
+            SurfaceInfil = std::min(SurfaceInfil, PavePerc);
         }
-
-        // --- storage exfiltration (with clogging) ---
-        double storageExfil = getStorageExfil(g.stor_ksat[ui], g.stor_clog[ui],
-                                               g.wb_inflow[ui]);
-
-        // --- underdrain flow (with hysteresis) ---
-        double storageDrain = getDrainRate(storageDepth, g.drain_coeff[ui],
-                                            g.drain_expon[ui], g.drain_offset[ui],
-                                            g.drain_hopen[ui], g.drain_hclose[ui],
-                                            g.drain_open[ui],
-                                            g.ucf_raindepth, g.ucf_rainfall);
-
-        // --- adjacency saturation checks (from legacy pavementFluxRates) ---
-
-        if (soilThickness == 0.0
-            && storageDepth >= storageThickness
-            && paveDepth >= paveThickness) {
-            // No soil layer, pavement & storage full
-            maxRate = storageEvap + storageDrain + storageExfil;
-            if (pavePerc > maxRate) {
-                pavePerc = maxRate;
-            } else {
-                storageExfil = std::min(storageExfil, pavePerc);
-                storageDrain = pavePerc - storageExfil;
+        else if (soilThickness > 0 &&
+                 storageDepth >= storageThickness &&
+                 soilTheta >= soilPorosity &&
+                 paveDepth >= paveThickness) {
+            maxRate = StorageExfil + StorageDrain;
+            if (SoilPerc < maxRate) maxRate = SoilPerc;
+            else maxRate = std::min(maxRate, PavePerc);
+            if (maxRate > StorageExfil) StorageDrain = maxRate - StorageExfil;
+            else {
+                StorageExfil = maxRate;
+                StorageDrain = 0.0;
             }
-            soilPerc = pavePerc;
-            surfaceInfil = std::min(surfaceInfil, pavePerc);
-
-        } else if (soilThickness > 0.0
-                   && storageDepth >= storageThickness
-                   && soilTheta >= soilPorosity
-                   && paveDepth >= paveThickness) {
-            // Pavement, soil & storage full
-            maxRate = storageExfil + storageDrain;
-            if (soilPerc < maxRate) maxRate = soilPerc;
-            else maxRate = std::min(maxRate, pavePerc);
-            if (maxRate > storageExfil) storageDrain = maxRate - storageExfil;
-            else { storageExfil = maxRate; storageDrain = 0.0; }
-            soilPerc = maxRate;
-            pavePerc = maxRate;
-            surfaceInfil = std::min(surfaceInfil, pavePerc);
-
-        } else if (soilThickness > 0.0
-                   && storageDepth >= storageThickness
-                   && soilTheta >= soilPorosity) {
-            // Storage & soil full
-            maxRate = storageDrain + storageExfil;
-            if (soilPerc > maxRate) soilPerc = maxRate;
+            SoilPerc = maxRate;
+            PavePerc = maxRate;
+            SurfaceInfil = std::min(SurfaceInfil, PavePerc);
+        }
+        else if (soilThickness > 0.0 &&
+                 storageDepth >= storageThickness &&
+                 soilTheta >= soilPorosity) {
+            maxRate = StorageDrain + StorageExfil;
+            if (SoilPerc > maxRate) SoilPerc = maxRate;
             else {
-                storageExfil = std::min(storageExfil, soilPerc);
-                storageDrain = soilPerc - storageExfil;
+                StorageExfil = std::min(StorageExfil, SoilPerc);
+                StorageDrain = SoilPerc - StorageExfil;
             }
-            pavePerc = std::min(pavePerc, soilPerc);
-            double availVolume = (paveThickness - paveDepth) * paveVoidFrac;
-            maxRate = availVolume / dt + pavePerc + paveEvap;
-            surfaceInfil = std::min(surfaceInfil, maxRate);
-
-        } else if (soilThickness > 0.0
-                   && paveDepth >= paveThickness
-                   && soilTheta >= soilPorosity) {
-            // Soil and pavement full
-            pavePerc = std::min(pavePerc, soilPerc);
-            soilPerc = pavePerc;
-            surfaceInfil = std::min(surfaceInfil, pavePerc);
-            maxRate = std::max(storageVolume / dt + soilPerc - storageEvap, 0.0);
-            storageExfil = std::min(storageExfil, maxRate);
-
-        } else {
-            // No adjoining layers full
-            maxRate = soilPerc - storageEvap + storageVolume / dt;
+            PavePerc = std::min(PavePerc, SoilPerc);
+            availVolume = (paveThickness - paveDepth) * paveVoidFrac;
+            maxRate = availVolume / Tstep + PavePerc + PaveEvap;
+            SurfaceInfil = std::min(SurfaceInfil, maxRate);
+        }
+        else if (soilThickness > 0.0 &&
+                 paveDepth >= paveThickness &&
+                 soilTheta >= soilPorosity) {
+            PavePerc = std::min(PavePerc, SoilPerc);
+            SoilPerc = PavePerc;
+            SurfaceInfil = std::min(SurfaceInfil, PavePerc);
+            maxRate = std::max(StorageVolume / Tstep + SoilPerc - StorageEvap, 0.0);
+            StorageExfil = std::min(StorageExfil, maxRate);
+        }
+        else {
+            maxRate = SoilPerc - StorageEvap + StorageVolume / Tstep;
             maxRate = std::max(0.0, maxRate);
-            storageExfil = std::min(storageExfil, maxRate);
-
-            if (storageDrain > 0.0) {
-                maxRate = -storageExfil - storageEvap;
-                if (storageDepth >= storageThickness) maxRate += soilPerc;
-                if (g.drain_offset[ui] <= storageDepth) {
-                    maxRate += (storageDepth - g.drain_offset[ui])
-                             * storageVoidFrac / dt;
+            StorageExfil = std::min(StorageExfil, maxRate);
+            if (StorageDrain > 0.0) {
+                maxRate = -StorageExfil - StorageEvap;
+                if (storageDepth >= storageThickness) maxRate += SoilPerc;
+                if (P->drain_offset <= storageDepth) {
+                    maxRate += (storageDepth - P->drain_offset) *
+                               storageVoidFrac / Tstep;
                 }
                 maxRate = std::max(maxRate, 0.0);
-                storageDrain = std::min(storageDrain, maxRate);
+                StorageDrain = std::min(StorageDrain, maxRate);
             }
-
-            // limit soil & pavement by unused storage volume
-            double availVolume = (storageThickness - storageDepth) * storageVoidFrac;
-            maxRate = availVolume / dt + storageEvap + storageDrain + storageExfil;
+            availVolume = (storageThickness - storageDepth) * storageVoidFrac;
+            maxRate = availVolume / Tstep + StorageEvap + StorageDrain + StorageExfil;
             maxRate = std::max(maxRate, 0.0);
             if (soilThickness > 0.0) {
-                soilPerc = std::min(soilPerc, maxRate);
-                maxRate = (soilPorosity - soilTheta) * soilThickness / dt + soilPerc;
+                SoilPerc = std::min(SoilPerc, maxRate);
+                maxRate = (soilPorosity - soilTheta) * soilThickness / Tstep +
+                          SoilPerc;
             }
-            pavePerc = std::min(pavePerc, maxRate);
-
-            // limit surface infil by available pavement volume
+            PavePerc = std::min(PavePerc, maxRate);
             availVolume = (paveThickness - paveDepth) * paveVoidFrac;
-            maxRate = availVolume / dt + pavePerc + paveEvap;
-            surfaceInfil = std::min(surfaceInfil, maxRate);
+            maxRate = availVolume / Tstep + PavePerc + PaveEvap;
+            SurfaceInfil = std::min(SurfaceInfil, maxRate);
+        }
+        SurfaceOutflow = getSurfaceOutflowRate(surfaceDepth);
+        f[L_SURF] = SurfaceInflow - SurfaceEvap - SurfaceInfil - SurfaceOutflow;
+        f[L_PAVE] = (SurfaceInfil - PaveEvap - PavePerc) / paveVoidFrac;
+        if (P->soil_thick > 0.0) {
+            f[L_SOIL] = (PavePerc - SoilEvap - SoilPerc) / soilThickness;
+            storageInflow = SoilPerc;
+        } else {
+            f[L_SOIL] = 0.0;
+            storageInflow = PavePerc;
+            SoilPerc = 0.0;
         }
+        f[L_STOR] = (storageInflow - StorageEvap - StorageExfil - StorageDrain) /
+                    storageVoidFrac;
+    }
 
-        // --- surface outflow ---
-        double surfaceOutflow = 0.0;
-        double delta_surf = surfaceDepth - g.surf_store[ui];
-        if (delta_surf > 0.0 && g.surf_alpha[ui] > 0.0
-            && g.full_width[ui] > 0.0 && g.area[ui] > 0.0) {
-            surfaceOutflow = g.surf_alpha[ui] * std::pow(delta_surf, 5.0 / 3.0)
-                           * g.full_width[ui] / g.area[ui];
-            surfaceOutflow = std::min(surfaceOutflow, delta_surf / dt);
+    // ---- legacy swaleFluxRates
+    void swaleFluxRates(const double x[], double f[]) {
+        double depth = x[L_SURF];
+        depth = std::min(depth, P->surf_thick);
+        double dStore = 0.0;
+        double slope = P->surf_side;
+        double topWidth = P->full_width;
+        topWidth = std::max(topWidth, 0.5);
+        double botWidth = topWidth - 2.0 * slope * P->surf_thick;
+        if (botWidth < 0.5) {
+            botWidth = 0.5;
+            slope = 0.5 * (topWidth - 0.5) / P->surf_thick;
+        }
+        const double lidArea = P->area;
+        const double length = lidArea / topWidth;
+        const double surfWidth = botWidth + 2.0 * slope * depth;
+        const double surfArea = length * surfWidth;
+        double flowArea = (depth * (botWidth + slope * depth)) * P->surf_void;
+        const double volume = length * flowArea;
+        const double surfInflow = SurfaceInflow * lidArea;
+        SurfaceEvap = EvapRate * surfArea;
+        SurfaceEvap = std::min(SurfaceEvap, volume / Tstep);
+        StorageExfil = SurfaceInfil * surfArea;
+        const double xDepth = depth - dStore;
+        if (xDepth <= L_ZERO) SurfaceOutflow = 0.0;
+        else {
+            flowArea -= (dStore * (botWidth + slope * dStore)) * P->surf_void;
+            if (flowArea < L_ZERO) SurfaceOutflow = 0.0;
+            else {
+                botWidth = botWidth + 2.0 * dStore * slope;
+                double hydRadius = botWidth + 2.0 * xDepth * std::sqrt(1.0 + slope * slope);
+                hydRadius = flowArea / hydRadius;
+                SurfaceOutflow = P->surf_alpha * flowArea *
+                                 std::pow(hydRadius, 2. / 3.);
+            }
         }
+        double dVdT = surfInflow - SurfaceEvap - StorageExfil - SurfaceOutflow;
+        if (depth == P->surf_thick && dVdT > 0.0) {
+            SurfaceOutflow += dVdT;
+            dVdT = 0.0;
+        }
+        SurfaceEvap /= lidArea;
+        StorageExfil /= lidArea;
+        SurfaceOutflow /= lidArea;
+        f[L_SURF] = dVdT / surfArea;
+        f[L_SOIL] = 0.0;
+        f[L_STOR] = 0.0;
+        SurfaceVolume = volume / lidArea;
+        SoilVolume = 0.0;
+        StorageVolume = 0.0;
+    }
 
-        // --- Euler integration ---
-        // Surface
-        double f_surf = surfaceInflow - surfaceEvap - surfaceInfil - surfaceOutflow;
-        double newSurf = surfaceDepth + f_surf * dt;
-        newSurf = std::max(newSurf, 0.0);
+    // ---- legacy barrelFluxRates
+    void barrelFluxRates(const double x[], double f[]) {
+        const double storageDepth = x[L_STOR];
+        double head;
+        double maxValue;
+        SurfaceVolume = 0.0;
+        SoilVolume = 0.0;
+        StorageVolume = storageDepth;
+        SurfaceInfil = 0.0;
+        SurfaceOutflow = 0.0;
+        StorageDrain = 0.0;
+        if (P->drain_delay == 0.0 || G->dry_time[U] >= P->drain_delay) {
+            head = storageDepth - P->drain_offset;
+            if (head > 0.0) {
+                StorageDrain = getStorageDrainRate(storageDepth, 0.0, 0.0, 0.0);
+                maxValue = (head / Tstep);
+                StorageDrain = std::min(StorageDrain, maxValue);
+            }
+        }
+        StorageInflow = SurfaceInflow;
+        maxValue = (P->stor_thick - storageDepth) / Tstep + StorageDrain;
+        StorageInflow = std::min(StorageInflow, maxValue);
+        SurfaceInfil = StorageInflow;
+        f[L_SURF] = SurfaceInflow - StorageInflow;
+        f[L_STOR] = StorageInflow - StorageDrain;
+        f[L_SOIL] = 0.0;
+    }
 
-        // Pavement
-        double f_pave = 0.0;
-        if (paveVoidFrac > 0.0) {
-            f_pave = (surfaceInfil - paveEvap - pavePerc) / paveVoidFrac;
+    void fluxRates(const double x[], double f[]) {
+        switch (P->type) {
+            case LIDType::BIO_CELL:
+            case LIDType::RAIN_GARDEN:   biocellFluxRates(x, f);   break;
+            case LIDType::GREEN_ROOF:    greenRoofFluxRates(x, f); break;
+            case LIDType::INFIL_TRENCH:  trenchFluxRates(x, f);    break;
+            case LIDType::PERM_PAVEMENT: pavementFluxRates(x, f);  break;
+            case LIDType::RAIN_BARREL:   barrelFluxRates(x, f);    break;
+            case LIDType::ROOF_DISCON:   roofFluxRates(x, f);      break;
+            case LIDType::VEG_SWALE:     swaleFluxRates(x, f);     break;
         }
-        double newPave = paveDepth + f_pave * dt;
-        newPave = std::max(newPave, 0.0);
-        newPave = std::min(newPave, paveThickness);
-
-        // Soil
-        double f_soil = 0.0;
-        double newTheta = soilTheta;
-        double storageInflow_local = soilPerc;
-        if (soilThickness > 0.0) {
-            f_soil = (pavePerc - soilEvap - soilPerc) / soilThickness;
-            newTheta = soilTheta + f_soil * dt;
-            newTheta = std::max(newTheta, soilWiltPoint);
-            newTheta = std::min(newTheta, soilPorosity);
-        } else {
-            storageInflow_local = pavePerc;
-            soilPerc = 0.0;
+    }
+
+    // ---- legacy modpuls_solve
+    int modpulsSolve(int n, double* x, double* xOld, double* xPrev,
+                     const double* xMin, const double* xMax, const double* xTol,
+                     const double* qOld, double* q, double dt, double omega) {
+        int steps = 1;
+        const int maxSteps = 20;
+        for (int i = 0; i < n; i++) {
+            xOld[i] = x[i];
+            xPrev[i] = x[i];
+        }
+        while (steps < maxSteps) {
+            int canStop = 1;
+            fluxRates(x, q);
+            for (int i = 0; i < n; i++) {
+                x[i] = xOld[i] + (omega * qOld[i] + (1.0 - omega) * q[i]) * dt;
+                x[i] = std::min(x[i], xMax[i]);
+                x[i] = std::max(x[i], xMin[i]);
+                if (omega > 0.0 &&
+                    std::fabs(x[i] - xPrev[i]) > xTol[i]) canStop = 0;
+                xPrev[i] = x[i];
+            }
+            if (canStop) return steps;
+            steps++;
         }
+        return 0;
+    }
+
+    // ---- legacy lidproc_getOutflow: returns the surface outflow (ft/s per
+    //      unit area) and the unit's evaporation, exfiltration and drain rates
+    double getOutflow(double inflow, double evap, double infil, double maxInfil,
+                      double tStep, double infil_factor, double recovery_factor,
+                      double* lidEvap, double* lidInfil, double* lidDrain) {
+        double x[L_MAX], xOld[L_MAX], xPrev[L_MAX], xMin[L_MAX], xMax[L_MAX];
+        double fOld[L_MAX], f[L_MAX];
+        double xTol[L_MAX] = {L_STOPTOL, L_STOPTOL, L_STOPTOL, L_STOPTOL};
+        double omega = 0.0;
+
+        Tstep = tStep;
+        EvapRate = evap;
+        MaxNativeInfil = maxInfil;
+        x[L_SURF] = G->surf_depth[U];
+        x[L_SOIL] = G->soil_moist[U];
+        x[L_STOR] = G->stor_depth[U];
+        x[L_PAVE] = G->pave_depth[U];
+
+        SurfaceVolume  = 0.0;
+        PaveVolume     = 0.0;
+        SoilVolume     = 0.0;
+        StorageVolume  = 0.0;
+        SurfaceInflow  = inflow;
+        SurfaceInfil   = 0.0;
+        SurfaceEvap    = 0.0;
+        SurfaceOutflow = 0.0;
+        PaveEvap       = 0.0;
+        PavePerc       = 0.0;
+        SoilEvap       = 0.0;
+        SoilPerc       = 0.0;
+        StorageInflow  = 0.0;
+        StorageExfil   = 0.0;
+        StorageEvap    = 0.0;
+        StorageDrain   = 0.0;
+        fOld[L_SURF] = G->f_old_surf[U];
+        fOld[L_SOIL] = G->f_old_soil[U];
+        fOld[L_STOR] = G->f_old_stor[U];
+        fOld[L_PAVE] = G->f_old_pave[U];
+        for (int i = 0; i < L_MAX; i++) {
+            f[i] = 0.0;
+            xMin[i] = 0.0;
+            xMax[i] = L_BIG;
+        }
+
+        // surface-to-soil infiltration: the unit's own Green-Ampt state, or
+        // the native soil rate when the unit has no soil layer
+        if (P->type == LIDType::PERM_PAVEMENT) SurfaceInfil = 0.0;
+        else if (G->soil_infil[U].Ks > 0.0) {
+            SurfaceInfil = infil::grnampt_getInfil(G->soil_infil[U], SurfaceInflow,
+                                                   G->surf_depth[U], Tstep,
+                                                   InfilModel::MOD_GREEN_AMPT,
+                                                   infil_factor, recovery_factor);
+        }
+        else SurfaceInfil = infil;
 
-        // Storage
-        double f_stor = 0.0;
-        if (storageVoidFrac > 0.0) {
-            f_stor = (storageInflow_local - storageEvap - storageExfil - storageDrain)
-                   / storageVoidFrac;
+        if (P->soil_thick > 0.0) {
+            xMin[L_SOIL] = P->soil_wp;
+            xMax[L_SOIL] = P->soil_poros;
         }
-        double newStor = storageDepth + f_stor * dt;
-        newStor = std::max(newStor, 0.0);
-        newStor = std::min(newStor, storageThickness);
-
-        // --- update state ---
-        g.surf_depth[ui] = newSurf;
-        g.pave_depth[ui] = newPave;
-        g.soil_moist[ui] = newTheta;
-        g.stor_depth[ui] = newStor;
-
-        // --- outputs ---
-        g.surface_runoff[ui] = surfaceOutflow;
-        g.drain_flow[ui] = storageDrain;
-        double totalEvap = surfaceEvap + paveEvap + soilEvap + storageEvap;
-        g.evap_loss[ui] = totalEvap * dt;
-        g.infil_loss[ui] = storageExfil * dt;
-
-        // --- water balance ---
-        double totalVolume = newSurf * surfVoidFrac
-                           + newPave * paveVoidFrac
-                           + newTheta * soilThickness
-                           + newStor * storageVoidFrac;
-        g.wb_inflow[ui]     += surfaceInflow * dt;
-        g.wb_evap[ui]       += totalEvap * dt;
-        g.wb_infil[ui]      += storageExfil * dt;
-        g.wb_surf_flow[ui]  += surfaceOutflow * dt;
-        g.wb_drain_flow[ui] += storageDrain * dt;
-        g.wb_final_vol[ui]   = totalVolume;
-        g.vol_treated[ui]   += surfaceInflow * dt;
+        if (P->pave_thick > 0.0) xMax[L_PAVE] = P->pave_thick;
+        if (P->stor_thick > 0.0) xMax[L_STOR] = P->stor_thick;
+        if (P->type == LIDType::GREEN_ROOF) xMax[L_STOR] = P->dm_thick;
+        if (P->type == LIDType::VEG_SWALE) omega = 0.5;
+
+        modpulsSolve(L_MAX, x, xOld, xPrev, xMin, xMax, xTol, fOld, f, tStep, omega);
+
+        if (P->can_overflow || P->full_width == 0.0)
+            SurfaceOutflow += getSurfaceOverflowRate(&x[L_SURF]);
+
+        G->surf_depth[U] = x[L_SURF];
+        G->pave_depth[U] = x[L_PAVE];
+        G->soil_moist[U] = x[L_SOIL];
+        G->stor_depth[U] = x[L_STOR];
+        G->f_old_surf[U] = f[L_SURF];
+        G->f_old_soil[U] = f[L_SOIL];
+        G->f_old_stor[U] = f[L_STOR];
+        G->f_old_pave[U] = f[L_PAVE];
+
+        *lidEvap = SurfaceEvap + PaveEvap + SoilEvap + StorageEvap;
+        *lidInfil = StorageExfil;
+        *lidDrain = StorageDrain;
+        return SurfaceOutflow;
     }
+};
+
+/// Fill a parameter view from SoA slot u.
+inline LidProcView makeView(const LIDGroupSoA& g, std::size_t u) {
+    LidProcView p;
+    p.type = g.type;
+    p.surf_thick = g.surf_store[u]; p.surf_void = g.surf_void_frac[u];
+    p.surf_alpha = g.surf_alpha[u]; p.surf_side = g.surf_side_slope[u];
+    p.can_overflow = g.can_overflow[u] != 0;
+    p.pave_thick = g.pave_thick[u]; p.pave_void = g.pave_void[u];
+    p.pave_imperv = g.pave_imperv_frac[u]; p.pave_ksat = g.pave_ksat[u];
+    p.pave_clog = g.pave_clog_factor[u]; p.pave_regen_days = g.pave_regen_days[u];
+    p.pave_regen_deg = g.pave_regen_deg[u];
+    p.soil_thick = g.soil_thick[u]; p.soil_poros = g.soil_poros[u];
+    p.soil_fc = g.soil_fc[u]; p.soil_wp = g.soil_wp[u];
+    p.soil_ksat = g.soil_ksat[u]; p.soil_kslope = g.soil_kslope[u];
+    p.stor_thick = g.stor_thick[u]; p.stor_void = g.stor_void[u];
+    p.stor_ksat = g.stor_ksat[u]; p.stor_clog = g.stor_clog[u];
+    p.drain_coeff = g.drain_coeff[u]; p.drain_expon = g.drain_expon[u];
+    p.drain_offset = g.drain_offset[u]; p.drain_delay = g.drain_delay[u];
+    p.drain_hopen = g.drain_hopen[u]; p.drain_hclose = g.drain_hclose[u];
+    p.dm_thick = g.drainmat_thick[u]; p.dm_alpha = g.drainmat_alpha[u];
+    // ONE unit's area / width (legacy lidUnit->area, ->fullWidth); a hand-built
+    // group (unit tests) that only set the footprint is a single unit.
+    p.area = g.unit_area[u] > 0.0 ? g.unit_area[u] : g.area[u];
+    p.full_width = g.unit_area[u] > 0.0 ? g.unit_width[u] : g.full_width[u];
+    p.ucf_rainfall = g.ucf_rainfall; p.ucf_raindepth = g.ucf_raindepth;
+    return p;
 }
 
+/// Run one unit through the legacy kernel and book its results the way
+/// legacy evalLidUnit + lidproc_saveResults do. `evap` is the potential
+/// evaporation rate legacy's subcatch_getEvapRate returns for the parent
+/// subcatchment, `native_infil` / `max_native_infil` its findNativeInfil
+/// values, `inflow` the unit's surface inflow (ft/s).
+inline void runUnitLegacy(LIDGroupSoA& g, std::size_t u, double inflow, double evap,
+                          double native_infil, double max_native_infil, double dt,
+                          double old_runoff_sec, double infil_factor,
+                          double recovery_factor) {
+    LidProcView view = makeView(g, u);
+    LegacyLidKernel k;
+    k.P = &view;
+    k.G = &g;
+    k.U = u;
+    k.old_runoff_days = old_runoff_sec / 86400.0;
+
+    double lidEvap = 0.0, lidInfil = 0.0, lidDrain = 0.0;
+    double lidRunoff = k.getOutflow(inflow, evap, native_infil, max_native_infil, dt,
+                                    infil_factor, recovery_factor,
+                                    &lidEvap, &lidInfil, &lidDrain);
+
+    // legacy lidproc_saveResults: water balance and the wet-LID flag
+    const double totalEvap = k.SurfaceEvap + k.PaveEvap + k.SoilEvap + k.StorageEvap;
+    const double totalVolume = k.SurfaceVolume + k.PaveVolume + k.SoilVolume + k.StorageVolume;
+    g.vol_treated[u]   += k.SurfaceInflow * dt;
+    g.wb_inflow[u]     += k.SurfaceInflow * dt;
+    g.wb_evap[u]       += totalEvap * dt;
+    g.wb_infil[u]      += k.StorageExfil * dt;
+    g.wb_surf_flow[u]  += k.SurfaceOutflow * dt;
+    g.wb_drain_flow[u] += k.StorageDrain * dt;
+    g.wb_final_vol[u]   = totalVolume;
+    const bool is_dry = (k.SurfaceInflow < L_MINFLOW && k.SurfaceOutflow < L_MINFLOW &&
+                         k.StorageDrain < L_MINFLOW && k.StorageExfil < L_MINFLOW &&
+                         totalEvap < L_MINFLOW);
+    g.is_wet[u] = is_dry ? 0 : 1;
+
+    // outputs (rates per unit area; the engine scales by the footprint)
+    g.surface_runoff[u] = lidRunoff;
+    g.drain_flow[u]     = lidDrain;
+    g.evap_loss[u]      = lidEvap * dt;     // depth this step (ft)
+    g.infil_loss[u]     = lidInfil * dt;    // depth this step (ft)
+
+    // staged for the per-unit LID report file (legacy lidproc_saveResults
+    // reads lidproc.c's static flux variables; the kernel here is per-call)
+    g.rpt_surf_infil[u] = k.SurfaceInfil;
+    g.rpt_pave_perc[u]  = k.PavePerc;
+    g.rpt_soil_perc[u]  = k.SoilPerc;
+
+    // per-layer inflow rates after every clamp, for the transport tracks
+    g.in_surf[u] = k.SurfaceInflow;
+    g.in_pave[u] = (g.type == LIDType::PERM_PAVEMENT) ? k.SurfaceInfil : 0.0;
+    g.in_soil[u] = (g.type == LIDType::PERM_PAVEMENT) ? k.PavePerc
+                 : (g.soil_thick[u] > 0.0 ? k.SurfaceInfil : 0.0);
+    g.in_stor[u] = (g.type == LIDType::RAIN_BARREL || g.type == LIDType::INFIL_TRENCH)
+                   ? k.StorageInflow
+                   : ((g.soil_thick[u] > 0.0 && g.stor_thick[u] > 0.0) ? k.SoilPerc
+                      : (g.type == LIDType::PERM_PAVEMENT ? k.PavePerc : 0.0));
+}
+
+} // namespace
+
 // ============================================================================
-// Batch roof disconnection flux rates — VECTORISABLE
+// Per-type entry points — thin wrappers over the legacy kernel (kept for the
+// unit tests that drive a group directly: no engine context, so the native
+// infiltration is 0, its ceiling unlimited and the factors 1).
 // ============================================================================
-// Legacy reference: roofFluxRates() in lidproc.c
-// Simplest LID: rainfall → surface ponding → surface outflow split into
-// drain (downspout) and overflow.
 
-void LIDSolver::batchRoofDisconFlux(LIDGroupSoA& g, double rainfall,
-                                     const double* evap_rate, double dt) {
+namespace {
+inline void runGroupStandalone(LIDGroupSoA& g, double rainfall,
+                               const double* evap_rate, double dt) {
+    constexpr double MIN_RUNOFF = 2.31481e-8;   // legacy consts.h (ft/s)
     for (int i = 0; i < g.count; ++i) {
         auto ui = static_cast(i);
-
-        double surfaceDepth = g.surf_depth[ui];
-
-        // --- inflow ---
-        double surfaceInflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
-
-        // --- evaporation (surface only, pervFrac = 1.0) ---
-        double surfaceEvap = std::min(evap_rate[ui], surfaceDepth / dt);
-        surfaceEvap = std::max(0.0, surfaceEvap);
-
-        // --- surface outflow ---
-        double surfaceOutflow = 0.0;
-        if (g.surf_alpha[ui] > 0.0 && g.full_width[ui] > 0.0
-            && g.area[ui] > 0.0) {
-            // Manning's equation outflow from surface
-            double delta_surf = surfaceDepth - g.surf_store[ui];
-            if (delta_surf > 0.0) {
-                surfaceOutflow = g.surf_alpha[ui]
-                               * std::pow(delta_surf, 5.0 / 3.0)
-                               * g.full_width[ui] / g.area[ui];
-                surfaceOutflow = std::min(surfaceOutflow, delta_surf / dt);
-            }
-        } else {
-            // No Manning parameters: overflow = anything above surface storage
-            double delta_surf = surfaceDepth - g.surf_store[ui];
-            if (delta_surf > 0.0) {
-                surfaceOutflow = delta_surf * g.surf_void_frac[ui] / dt;
-            }
-        }
-
-        // --- drain (downspout): fraction of surface outflow up to drain_coeff ---
-        // Legacy: StorageDrain = MIN(drain.coeff/UCF(RAINFALL), SurfaceOutflow).
-        // drain_coeff is stored in user rate units, so convert to ft/s (#102).
-        double storageDrain = std::min(g.drain_coeff[ui] / g.ucf_rainfall,
-                                       surfaceOutflow);
-        surfaceOutflow -= storageDrain;
-
-        // --- Euler integration of surface depth ---
-        double f_surf = surfaceInflow - surfaceEvap - storageDrain - surfaceOutflow;
-        double newSurf = surfaceDepth + f_surf * dt;
-        newSurf = std::max(newSurf, 0.0);
-
-        // --- update state ---
-        g.surf_depth[ui] = newSurf;
-
-        // --- outputs ---
-        g.surface_runoff[ui] = surfaceOutflow;
-        g.drain_flow[ui] = storageDrain;
-        g.evap_loss[ui] = surfaceEvap * dt;
-        g.infil_loss[ui] = 0.0;
-
-        // --- water balance ---
-        double totalVolume = newSurf * g.surf_void_frac[ui];
-        g.wb_inflow[ui]     += surfaceInflow * dt;
-        g.wb_evap[ui]       += surfaceEvap * dt;
-        g.wb_infil[ui]      += 0.0;
-        g.wb_surf_flow[ui]  += surfaceOutflow * dt;
-        g.wb_drain_flow[ui] += storageDrain * dt;
-        g.wb_final_vol[ui]   = totalVolume;
-        g.vol_treated[ui]   += surfaceInflow * dt;
+        double inflow = (g.inflow[ui] > 0.0) ? g.inflow[ui] : rainfall;
+        if (g.type == LIDType::RAIN_BARREL && g.stor_covered[ui]) inflow = 0.0;
+        const double evap = evap_rate ? evap_rate[ui] : 0.0;
+        runUnitLegacy(g, ui, inflow, evap, 0.0, L_BIG, dt, 0.0, 1.0, 1.0);
+        // legacy evalLidUnit: the dry clock for the rain-barrel drain delay
+        if (g.subcatch_rain[ui] > MIN_RUNOFF) g.dry_time[ui] = 0.0;
+        else                                  g.dry_time[ui] += dt;
+        g.drain_open[ui] = (g.drain_flow[ui] > 0.0) ? 1 : 0;
+        g.old_drain_flow[ui] = g.drain_flow[ui];
     }
 }
+} // namespace
+
+void LIDSolver::batchBioCellFlux(LIDGroupSoA& g, double rainfall,
+                                  const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchBarrelFlux(LIDGroupSoA& g, double rainfall, double dt) {
+    runGroupStandalone(g, rainfall, nullptr, dt);
+}
+void LIDSolver::batchInfilTrenchFlux(LIDGroupSoA& g, double rainfall,
+                                      const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchSwaleFlux(LIDGroupSoA& g, double rainfall,
+                                const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchSwaleModPuls(LIDGroupSoA& g, double rainfall,
+                                   const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchGreenRoofFlux(LIDGroupSoA& g, double rainfall,
+                                    const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchPavementFlux(LIDGroupSoA& g, double rainfall,
+                                   const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
+void LIDSolver::batchRoofDisconFlux(LIDGroupSoA& g, double rainfall,
+                                     const double* evap_rate, double dt) {
+    runGroupStandalone(g, rainfall, evap_rate, dt);
+}
 
 // ============================================================================
 // Stored-volume queries — feed the runoff-continuity storage term (#102 C)
@@ -1422,54 +1471,176 @@ double LIDSolver::totalEvapVolume() const {
 
 void LIDSolver::execute(SimulationContext& ctx, double dt,
                         double rainfall, double evap_rate) {
+    constexpr double MIN_RUNOFF = 2.31481e-8;   // legacy consts.h (ft/s)
+    (void)rainfall;   // the engine sets each unit's inflow (rain + capture)
     for (auto& g : groups_) {
         if (g.count == 0) continue;
-
-        // Resolve per-unit effective PET rate: any prescribed PET forcing on
-        // the unit's parent subcatchment overrides/augments the broadcast rate.
         for (int u = 0; u < g.count; ++u) {
             auto uu = static_cast(u);
+            // legacy lid_getRunoff: a unit without area (0 units or 0 ft2,
+            // no-units-w-wo-rg-2subcatchments) is never evaluated — the
+            // kernel divides by it.
+            if (g.area[uu] <= 0.0) continue;
             int sc = g.subcatch_idx[uu];
-            g.evap_rate_unit[uu] = (sc >= 0)
-                ? ctx.forcing.effective_evap_rate(static_cast(sc), evap_rate)
-                : evap_rate;
+            const auto usc = static_cast(sc);
+            // legacy subcatch_getEvapRate: an API-prescribed rate first, else
+            // 0 under DRY_ONLY while it rains on the subcatchment, else the
+            // climate rate.
+            double e_dry = (ctx.options.evap_dry_only && g.subcatch_rain[uu] > 0.0)
+                           ? 0.0 : evap_rate;
+            const double evap = (sc >= 0)
+                ? ctx.forcing.effective_evap_rate(usc, e_dry) : e_dry;
+            g.evap_rate_unit[uu] = evap;
+            const double native = (sc >= 0 && usc < native_infil_.size())
+                                  ? native_infil_[usc] : 0.0;
+            const double max_native = (sc >= 0 && usc < max_native_infil_.size())
+                                      ? max_native_infil_[usc] : L_BIG;
+            const double infil_factor = (sc >= 0 && usc < infil_factor_.size())
+                                        ? infil_factor_[usc] : 1.0;
+            runUnitLegacy(g, uu, g.inflow[uu], evap, native, max_native, dt,
+                          old_runoff_sec_, infil_factor, recovery_factor_);
+            // legacy evalLidUnit: the dry clock for the rain-barrel drain
+            // delay, updated AFTER the unit ran (it reads the clock as it
+            // stood before this step); reset by the parent subcatchment's
+            // rainfall above MIN_RUNOFF.
+            if (g.subcatch_rain[uu] > MIN_RUNOFF) g.dry_time[uu] = 0.0;
+            else                                  g.dry_time[uu] += dt;
+            // legacy lidproc_saveResults' report-file half: one row per
+            // evaluated runoff step for a unit with a [LID_USAGE] file.
+            if (!g.rpt_path[uu].empty())
+                saveLidReport(ctx, static_cast(&g - groups_.data()),
+                              g, uu, dt);
         }
-        const double* evap = g.evap_rate_unit.data();
+    }
+}
 
-        switch (g.type) {
-            case LIDType::BIO_CELL:
-            case LIDType::RAIN_GARDEN:
-                batchBioCellFlux(g, rainfall, evap, dt);
-                break;
-
-            case LIDType::INFIL_TRENCH:
-                // Gap #24: infiltration trench has no soil layer — surface drains
-                // directly to storage. Uses batchInfilTrenchFlux() not batchBioCellFlux().
-                batchInfilTrenchFlux(g, rainfall, evap, dt);
-                break;
-
-            case LIDType::RAIN_BARREL:
-                batchBarrelFlux(g, rainfall, dt);
-                break;
-
-            case LIDType::VEG_SWALE:
-                batchSwaleModPuls(g, rainfall, evap, dt);
-                break;
-
-            case LIDType::GREEN_ROOF:
-                batchGreenRoofFlux(g, rainfall, evap, dt);
-                break;
-
-            case LIDType::PERM_PAVEMENT:
-                batchPavementFlux(g, rainfall, evap, dt);
-                break;
-
-            case LIDType::ROOF_DISCON:
-                batchRoofDisconFlux(g, rainfall, evap, dt);
-                break;
+// ============================================================================
+// Per-unit LID report file — legacy createLidRptFile + initLidRptFile
+// (lid.c) and the writing half of lidproc_saveResults (lidproc.c:386-437).
+// Same columns, same formats, same dry-spell compression, so the two
+// engines' files diff line-for-line.
+// ============================================================================
+void LIDSolver::saveLidReport(SimulationContext& ctx, int gi, LIDGroupSoA& g,
+                              std::size_t u, double dt) {
+    auto key = std::make_pair(gi, static_cast(u));
+    auto it = rpt_files_.find(key);
+    if (it == rpt_files_.end()) {
+        auto st = std::make_unique();
+        st->f.open(g.rpt_path[u], std::ios::out | std::ios::trunc);
+        st->failed = !st->f.is_open();
+        if (!st->failed) {
+            // --- initLidRptFile: title lines, two heading rows, a units row
+            //     picked by unit system, and the dashed rule.
+            static const char* head1[14] = {
+                "\n                    \t", "  Elapsed\t",
+                "    Total\t", "    Total\t", "  Surface\t", " Pavement\t",
+                "     Soil\t", "  Storage\t", "  Surface\t", "    Drain\t",
+                "  Surface\t", " Pavement\t", "     Soil\t", "  Storage"};
+            static const char* head2[14] = {
+                "\n                    \t", "     Time\t",
+                "   Inflow\t", "     Evap\t", "    Infil\t", "     Perc\t",
+                "     Perc\t", "    Exfil\t", "   Runoff\t", "  OutFlow\t",
+                "    Level\t", "    Level\t", " Moisture\t", "    Level"};
+            static const char* units1[14] = {
+                "\nDate        Time    \t", "    Hours\t",
+                "    in/hr\t", "    in/hr\t", "    in/hr\t", "    in/hr\t",
+                "    in/hr\t", "    in/hr\t", "    in/hr\t", "    in/hr\t",
+                "   inches\t", "   inches\t", "  Content\t", "   inches"};
+            static const char* units2[14] = {
+                "\nDate        Time    \t", "    Hours\t",
+                "    mm/hr\t", "    mm/hr\t", "    mm/hr\t", "    mm/hr\t",
+                "    mm/hr\t", "    mm/hr\t", "    mm/hr\t", "    mm/hr\t",
+                "       mm\t", "       mm\t", "  Content\t", "       mm"};
+            const bool is_us = (g.ucf_raindepth == 12.0);
+            const std::string title =
+                ctx.title_notes.empty() ? std::string{} : ctx.title_notes[0];
+            const int ci = g.control_idx[u];
+            const int si = g.subcatch_idx[u];
+            st->f << "SWMM5 LID Report File\n";
+            st->f << "\nProject:  " << title;
+            st->f << "\nLID Unit: "
+                  << (ci >= 0 ? ctx.lid_names.name_of(ci) : std::string{})
+                  << " in Subcatchment "
+                  << (si >= 0 ? ctx.subcatch_names.name_of(si) : std::string{})
+                  << "\n";
+            for (const char* c : head1) st->f << c;
+            for (const char* c : head2) st->f << c;
+            if (is_us) { for (const char* c : units1) st->f << c; }
+            else       { for (const char* c : units2) st->f << c; }
+            st->f << "\n----------- --------";
+            for (int i = 1; i < 14; ++i) st->f << "\t ---------";
         }
+        it = rpt_files_.emplace(key, std::move(st)).first;
+    }
+    LidRptFile& r = *it->second;
+    if (r.failed) return;
+
+    // --- rptVars, exactly lidproc.c:391-407: rates x ucfRainfall,
+    //     depths x ucfRainDepth, soil moisture raw.
+    const double total_evap = (dt > 0.0) ? g.evap_loss[u] / dt : 0.0;
+    const double stor_exfil = (dt > 0.0) ? g.infil_loss[u] / dt : 0.0;
+    const double ucfQ = g.ucf_rainfall, ucfD = g.ucf_raindepth;
+    const double rv[12] = {
+        g.in_surf[u]        * ucfQ,   // Total Inflow
+        total_evap          * ucfQ,   // Total Evap
+        g.rpt_surf_infil[u] * ucfQ,   // Surface Infil
+        g.rpt_pave_perc[u]  * ucfQ,   // Pavement Perc
+        g.rpt_soil_perc[u]  * ucfQ,   // Soil Perc
+        stor_exfil          * ucfQ,   // Storage Exfil
+        g.surface_runoff[u] * ucfQ,   // Surface Runoff
+        g.drain_flow[u]     * ucfQ,   // Drain OutFlow
+        g.surf_depth[u]     * ucfD,   // Surface Level
+        g.pave_depth[u]     * ucfD,   // Pavement Level
+        // legacy prints x[SOIL], which stays 0 for a unit with no soil
+        // layer (barrelFluxRates never touches it); g.soil_moist carries a
+        // seeded default there, so mirror the layer test.
+        g.soil_thick[u] > 0.0 ? g.soil_moist[u] : 0.0,  // Soil Moisture
+        g.stor_depth[u]     * ucfD }; // Storage Level
+
+    const bool is_dry = (g.in_surf[u]        < L_MINFLOW &&
+                         g.surface_runoff[u] < L_MINFLOW &&
+                         g.drain_flow[u]     < L_MINFLOW &&
+                         stor_exfil          < L_MINFLOW &&
+                         total_evap          < L_MINFLOW);
+
+    // --- a wet step ending a >1-period dry spell first flushes the HELD
+    //     row (the spell's last state), lidproc.c:412-417.
+    if (!is_dry && r.was_dry > 1) r.f << r.held;
+
+    // --- format the current row into the held buffer
+    const double new_sec = old_runoff_sec_ + dt;
+    const double when = ctx.options.start_date + new_sec / 86400.0;
+    int yy, mo, dd, hh, mi, ss;
+    datetime::decodeDate(when, yy, mo, dd);
+    datetime::decodeTime(when, hh, mi, ss);
+    char ts[24];
+    std::snprintf(ts, sizeof(ts), "%02d/%02d/%04d %02d:%02d:%02d",
+                  mo, dd, yy, hh, mi, ss);
+    char row[512];
+    std::snprintf(row, sizeof(row),
+        "\n%20s\t %8.3f\t %8.3f\t %8.4f\t %8.3f\t %8.3f\t %8.3f\t %8.3f\t"
+        "%8.3f\t %8.3f\t %8.3f\t %8.3f\t %8.3f\t %8.3f",
+        ts, new_sec / 3600.0,
+        rv[0], rv[1], rv[2], rv[3], rv[4], rv[5],
+        rv[6], rv[7], rv[8], rv[9], rv[10], rv[11]);
+    r.held = row;
+
+    // --- dry-spell compression, lidproc.c:419-437
+    if (is_dry) {
+        if (r.was_dry == 0) r.f << r.held;
+        r.was_dry++;
+    } else {
+        r.f << r.held;
+        r.was_dry = 0;
     }
 }
 
+bool LIDSolver::anyWet() const {
+    for (const auto& g : groups_)
+        for (int u = 0; u < g.count; ++u)
+            if (g.is_wet[static_cast(u)]) return true;
+    return false;
+}
+
 } // namespace lid
 } // namespace openswmm
diff --git a/src/engine/hydrology/LID.hpp b/src/engine/hydrology/LID.hpp
index 7b7d14b33..32488a1af 100644
--- a/src/engine/hydrology/LID.hpp
+++ b/src/engine/hydrology/LID.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LID.hpp
  * @brief Low Impact Development (LID) control modules.
@@ -20,14 +36,21 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_LID_HPP
 #define OPENSWMM_LID_HPP
 
+#include "Infiltration.hpp"
+#include 
 #include 
 #include 
+#include 
+#include 
+#include 
+#include 
+#include 
 
 namespace openswmm {
 
@@ -85,6 +108,14 @@ struct LIDGroupSoA {
     std::vector    drain_subcatch;///< Resolved drain-to subcatch index (-1=none)
     std::vector inflow;        ///< Per-unit inflow rate (ft/sec) — set before execute()
     std::vector evap_rate_unit;///< Per-unit effective PET rate (ft/sec) — filled by execute()
+    std::vector subcatch_rain; ///< Parent subcatchment rainfall (ft/sec) — for the rain-barrel dry-time reset (legacy lid.c:1920)
+    std::vector rpt_path; ///< Per-unit LID report file ([LID_USAGE] col 9); empty = none
+    // Per-step kernel rates staged for the LID report file (ft/s). Legacy
+    // lidproc_saveResults reads these straight from lidproc.c's static flux
+    // variables; the kernel here is per-call, so runUnitLegacy stages them.
+    std::vector rpt_surf_infil;  ///< SurfaceInfil this step
+    std::vector rpt_pave_perc;   ///< PavePerc this step
+    std::vector rpt_soil_perc;   ///< SoilPerc this step
 
     // Surface layer
     std::vector surf_store;    ///< Surface storage depth (ft)
@@ -136,6 +167,8 @@ struct LIDGroupSoA {
     std::vector surf_alpha;        ///< Surface Manning alpha = sqrt(slope)/n
     std::vector surf_side_slope;   ///< Swale side slope (run/rise)
     std::vector full_width;        ///< Full width for Manning's flow (ft)
+    std::vector unit_area;         ///< ONE unit's area (ft2) — legacy lidUnit->area
+    std::vector unit_width;        ///< ONE unit's width (ft) — legacy lidUnit->fullWidth
     std::vector dry_time;          ///< Seconds since last rainfall
 
     // State variables (updated each step)
@@ -144,16 +177,48 @@ struct LIDGroupSoA {
     std::vector stor_depth;    ///< Current storage depth
     std::vector pave_depth;    ///< Current pavement depth
 
+    // Legacy lidproc.c per-unit state the kernel needs beyond the layer
+    // depths (lid.c TLidUnit): the unit's own Green-Ampt infiltration
+    // state for the soil layer (soilInfil), the drain flow the previous
+    // step delivered (oldDrainFlow, the underdrain's hOpen/hClose
+    // hysteresis memory), and the process's canOverflow flag
+    // (validateLidProc: false for a roof disconnection and for a
+    // bio-cell / rain garden / trench / pavement / green roof whose surface
+    // has a Manning alpha).
+    std::vector soil_infil;
+    std::vector old_drain_flow;
+    std::vector is_wet;           ///< legacy lidproc_saveResults isDry == FALSE this step (HasWetLids)
+    std::vector can_overflow;
+    std::vector drainmat_alpha;    ///< legacy drainMat.alpha = PHI / roughness * sqrt(surfSlope)
+
     // Outputs (per unit)
     std::vector surface_runoff;
     std::vector drain_flow;
-    std::vector evap_loss;
-    std::vector infil_loss;
+    std::vector evap_loss;   ///< Evaporation loss this step (ft of depth)
+    std::vector infil_loss;  ///< Native infiltration loss this step (ft)
 
     // Pollutant drain removal fractions: drain_rmvl[unit * n_pollutants + pollutant]
     std::vector drain_rmvl;  ///< Removal fraction per unit per pollutant
     int n_pollutants = 0;            ///< Number of pollutants (for indexing drain_rmvl)
 
+    // ---- A4: per-layer INFLOW rates (ft/sec of water per unit area) ----
+    // Each layer receives from exactly one place: the layer above it in the
+    // present stack, or externally for the topmost present layer. Every
+    // batch*Flux routine already computes these as locals (soil_infil,
+    // soil_perc, pavePerc, storageInflow, ...); they are published here
+    // because a complete-mix age needs the INFLOW and nothing else — the
+    // outflow leaves at the layer's own age.
+    //
+    // These are NOT the `f_old_*` below. Those are the Modified Puls
+    // time-weighting term: `f_old_surf` is the NET dx/dt of the surface
+    // layer, and the other three are never written at all. A net rate of
+    // change is exactly the quantity that made phase A3 report elapsed time
+    // instead of age.
+    std::vector in_surf;      ///< External inflow onto the surface
+    std::vector in_pave;      ///< Surface → pavement
+    std::vector in_soil;      ///< Layer above → soil
+    std::vector in_stor;      ///< Layer above → storage
+
     // Previous flux rates (for Modified Puls time weighting)
     std::vector f_old_surf;   ///< Previous surface flux rate
     std::vector f_old_soil;   ///< Previous soil flux rate
@@ -186,16 +251,26 @@ class LIDSolver {
     const LIDGroupSoA& group(int type_index) const { return groups_[static_cast(type_index)]; }
     int numGroups() const { return static_cast(groups_.size()); }
 
-    /// Total water currently stored across all LID units (ft³): per-unit
-    /// stored depth (wb_final_vol, ft) × unit area (ft²). Feeds the
-    /// subcatchment runoff-continuity storage term (issue #102 C).
+    /// Total water volume currently stored in all LID units (ft³), for the
+    /// runoff mass balance (legacy lid_getStoredVolume()). This is the one
+    /// SWMMEngine calls (runoff_init_store / runoff_final_store).
+    double storedVolume() const;
+
+    /// Water-balance-ledger volume queries (#102 C), summing the per-unit
+    /// `wb_*` accumulators over the unit footprints.
+    ///
+    /// MERGE REPAIR (a38f0c0b, 2026-08-29): these four were DEFINED in
+    /// LID.cpp on the incoming `swmm6_rel` side with no declaration on
+    /// EITHER side of the merge — that branch does not compile as it stands,
+    /// and neither did the merge result. The definitions are kept and
+    /// declared here rather than deleted, because deleting is the one choice
+    /// that cannot be undone by whoever wires them up. **Nothing calls them
+    /// yet**: `storedVolume()` above, not `totalStoredVolume()`, is what the
+    /// runoff mass balance uses, and the two measure different things
+    /// (void-weighted layer depths vs the wb_ ledger's final volume).
     double totalStoredVolume() const;
-    /// Total initial LID storage (ft³): wb_init_vol (ft) × area (ft²).
     double totalInitVolume() const;
-    /// Cumulative LID exfiltration to native soil (ft³): wb_infil × area.
-    /// Added to the runoff-continuity infiltration term (legacy VlidInfil).
     double totalInfilVolume() const;
-    /// Cumulative LID evaporation (ft³): wb_evap × area (legacy VlidEvap).
     double totalEvapVolume() const;
 
     /**
@@ -217,6 +292,29 @@ class LIDSolver {
     void execute(SimulationContext& ctx, double dt,
                  double rainfall, double evap_rate);
 
+    /// The runoff clock's OLD time (seconds), legacy OldRunoffTime — the
+    /// pavement clogging regeneration test reads it (lidproc.c
+    /// getPavementPermRate). Set by the engine before each execute().
+    void setRunoffTime(double old_runoff_sec) { old_runoff_sec_ = old_runoff_sec; }
+
+    /// Per-subcatchment native-soil infiltration inputs for this runoff step
+    /// (legacy findNativeInfil: NativeInfil and MaxNativeInfil, ft/s). Set by
+    /// the engine before each execute(); empty means 0 and unlimited.
+    void setNativeInfil(std::vector native, std::vector max_native) {
+        native_infil_ = std::move(native); max_native_infil_ = std::move(max_native);
+    }
+
+    /// Per-subcatchment infiltration factor (the [ADJUSTMENTS] / pattern
+    /// multiplier the runoff solver applied this step) and the evaporation
+    /// recovery factor, for the units' own Green-Ampt states.
+    void setInfilFactors(std::vector infil_factor, double recovery_factor) {
+        infil_factor_ = std::move(infil_factor); recovery_factor_ = recovery_factor;
+    }
+
+    /// Legacy HasWetLids: any unit was not dry in the last execute()
+    /// (runoff.c keeps the WET step while it holds).
+    bool anyWet() const;
+
     /// Batch bio-cell flux rates — VECTORISABLE
     static void batchBioCellFlux(LIDGroupSoA& g, double rainfall,
                                   const double* evap_rate, double dt);
@@ -252,6 +350,26 @@ class LIDSolver {
 
 private:
     std::vector groups_;
+    double old_runoff_sec_ = 0.0;
+
+    /// One legacy TLidRptFile per reporting unit (legacy lid.h:150-156):
+    /// the stream, the count of successive dry periods (seeded 1 by the
+    /// header, initLidRptFile), and the held row that marks the end of a
+    /// dry spell. Keyed (group index, unit index); opened lazily on the
+    /// unit's first evaluated step.
+    struct LidRptFile {
+        std::ofstream f;
+        int  was_dry = 1;
+        std::string held;
+        bool failed = false;
+    };
+    std::map, std::unique_ptr> rpt_files_;
+    void saveLidReport(SimulationContext& ctx, int gi, LIDGroupSoA& g,
+                       std::size_t u, double dt);
+    double recovery_factor_ = 1.0;
+    std::vector native_infil_;
+    std::vector max_native_infil_;
+    std::vector infil_factor_;
 };
 
 } // namespace lid
diff --git a/src/engine/hydrology/RDII.cpp b/src/engine/hydrology/RDII.cpp
index 25e905194..18fb50991 100644
--- a/src/engine/hydrology/RDII.cpp
+++ b/src/engine/hydrology/RDII.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RDII.cpp
  * @brief RDII unit hydrograph convolution — matching legacy rdii.c.
@@ -5,11 +21,12 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RDII.hpp"
 #include "../core/SimulationContext.hpp"
+#include "../core/Constants.hpp"
 #include "../core/UnitConversion.hpp"
 #include "../core/DateTime.hpp"
 #include "../core/ErrorCodes.hpp"
@@ -28,8 +45,9 @@ void RDIIGroupSoA::resize(int n) {
     area.assign(un, 0.0);
     uh_data.resize(un * 3);  // 3 responses per group
     rain_interval.assign(un, 300);
-    time_accum.assign(un, 0.0);
-    rain_at_start.assign(un, 0.0);
+    gage_elapsed.assign(un, 0.0);
+    rate_recorded_until.assign(un, 0.0);
+    pending_rates.assign(un, {});
 }
 
 // ---------------------------------------------------------------------------
@@ -186,8 +204,21 @@ void RDIISolver::init(SimulationContext& ctx) {
         }
         auto& uh = uh_params[static_cast(idx)];
 
-        double tPeak_sec = entry.t * 3600.0;
-        double tBase_sec = entry.t * (1.0 + entry.k) * 3600.0;
+        // PARITY rdii.c:424-426 — legacy forms the base time in HOURS and
+        // stores both times TRUNCATED to whole seconds:
+        //   tBase = t * (1.0 + k);                    // hours
+        //   UnitHyd.tPeak = (long)(t * 3600.);        // seconds
+        //   UnitHyd.tBase = (long)(tBase * 3600.);    // seconds
+        // The truncation is not cosmetic: T 0.3 h, K 2.0 gives
+        // 0.3*(1+2) = 0.8999999999999999 h, so tBase lands at 3239 s, not
+        // 3240, and qPeak = 2/tBase*3600 is 3.1e-4 HIGH for the whole run.
+        // Keeping the exact product made every short-response RTK hydrograph
+        // in 405-h-h-elements 2.9e-4 low from its first nonzero ordinate.
+        double tBase_hrs = entry.t * (1.0 + entry.k);
+        double tPeak_sec = static_cast(
+            static_cast(entry.t * 3600.0));
+        double tBase_sec = static_cast(
+            static_cast(tBase_hrs * 3600.0));
 
         int m_start = (entry.month < 0) ? 0  : entry.month;
         int m_end   = (entry.month < 0) ? 11 : entry.month;
@@ -255,6 +286,13 @@ void RDIISolver::init(SimulationContext& ctx) {
 
     const auto& assigns = ctx.rdii_assigns;
     int n_assigns = assigns.count();
+
+    // Strict-grid state (see advance()) — reset for re-initialization.
+    grid_step_ = 0.0;
+    next_tick_ = 0.0;
+    grid_node_.clear();
+    grid_flows_.clear();
+
     if (n_assigns == 0) {
         groups_.count = 0;
         return;
@@ -263,6 +301,7 @@ void RDIISolver::init(SimulationContext& ctx) {
     groups_.resize(n_assigns);
     node_rdii_flow_.assign(static_cast(ctx.n_nodes()), 0.0);
     double wet_step = ctx.options.wet_step;
+    grid_step_ = wet_step;
 
     for (int i = 0; i < n_assigns; ++i) {
         auto ui = static_cast(i);
@@ -308,6 +347,13 @@ void RDIISolver::init(SimulationContext& ctx) {
             }
         }
     }
+
+    // Grid columns: the RDII node set (legacy RdiiNodeIndex file header).
+    for (int ni : groups_.node_idx)
+        if (ni >= 0) grid_node_.push_back(ni);
+    std::sort(grid_node_.begin(), grid_node_.end());
+    grid_node_.erase(std::unique(grid_node_.begin(), grid_node_.end()),
+                     grid_node_.end());
 }
 
 // ---------------------------------------------------------------------------
@@ -461,18 +507,63 @@ static void updateDryPeriod(UHResponseData& rd, double rainDepth,
 }
 
 // ---------------------------------------------------------------------------
-// computeAll — matches legacy getUnitHydRdii() + getUnitHydConvol().
+// advance — the legacy createRdiiFile() driver embedded at runtime.
+//
+// Legacy computes RDII once, before the run, on a fixed RdiiStep (= WetStep)
+// grid anchored at StartDateTime, with each UH group's rainfall processed in
+// its own rainInterval chunks (rdii.c:800-821, getRainfall's
+// `while (gageDate < currentDate)` loop). The previous implementation ticked
+// on the runoff substep cadence and crossed at most ONE rain interval per
+// substep, so a DRY_STEP jump swallowed the intermediate intervals — dry
+// seconds, IA recovery and the convolution grid all corrupted.
 //
-// 1. Accumulates rainfall over the rain interval
-// 2. At each rain interval boundary, stores rainfall depth (with IA) into
-//    per-response circular buffers
-// 3. Convolves past rainfall with UH ordinates
-// 4. Scatters RDII flow to nodes (area × rdii / UCF(RAINFALL))
+// Two facts make the embedded driver exact without re-scanning gage series:
+//   1. computeRunoffTimestep caps every runoff substep at the next gage
+//      entry boundary, so the CURRENT gage rate (with the monthly adjustment
+//      applied by the caller) is the step-function rate at every chunk start
+//      inside the substep. Rates are recorded per chunk as substeps pass.
+//   2. Legacy samples the gage ONCE per driver tick (Gage.isCurrent memo) —
+//      all chunks of one tick use the FIRST chunk's rate. Replicated below.
 // ---------------------------------------------------------------------------
-void RDIISolver::computeAll(SimulationContext& ctx, int month, double dt) {
-    int unit_sys = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+void RDIISolver::advance(SimulationContext& ctx, double new_elapsed_sec) {
+    if (groups_.count == 0 || grid_step_ <= 0.0) return;
+
+    // 1. Record the gage rate for every chunk whose start lies inside the
+    //    just-computed substep (chunk starts advance in rain_interval steps
+    //    from simulation start; strictly-before keeps the boundary chunk for
+    //    the substep that owns it).
+    for (int g = 0; g < groups_.count; ++g) {
+        auto ug = static_cast(g);
+        int ri = groups_.rain_interval[ug];
+        if (ri <= 0) continue;
+        int gi = groups_.gage_idx[ug];
+        double rate = 0.0;
+        if (gi >= 0 && gi < static_cast(ctx.gages.rainfall.size()))
+            rate = ctx.gages.rainfall[static_cast(gi)];
+        while (groups_.rate_recorded_until[ug] < new_elapsed_sec) {
+            groups_.pending_rates[ug].push_back(rate);
+            groups_.rate_recorded_until[ug] += static_cast(ri);
+        }
+    }
+
+    // 2. Emit every strict-grid tick the runoff clock has reached (legacy
+    //    driver: elapsedTime = 0, RdiiStep, 2·RdiiStep, ... — inclusive).
+    while (next_tick_ <= new_elapsed_sec) {
+        emitTick(ctx, next_tick_);
+        next_tick_ += grid_step_;
+    }
+}
+
+void RDIISolver::emitTick(SimulationContext& ctx, double T) {
+    const int unit_sys =
+        ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    constexpr double ZERO_RDII = 0.0001;  // legacy rdii.c:41 (cfs)
+
+    // Month of the tick date — legacy getRainfall computes it from
+    // currentDate and stamps it on every chunk stored this tick.
+    const double tick_date = datetime::addSeconds(ctx.options.start_date, T);
+    const int tick_month = datetime::monthOfYear(tick_date) - 1;
 
-    // Zero the per-node RDII buffer before accumulating
     std::fill(node_rdii_flow_.begin(), node_rdii_flow_.end(), 0.0);
 
     for (int g = 0; g < groups_.count; ++g) {
@@ -480,46 +571,31 @@ void RDIISolver::computeAll(SimulationContext& ctx, int month, double dt) {
         int uh_i = groups_.uh_idx[ug];
         if (uh_i < 0 || uh_i >= static_cast(uh_params.size())) continue;
         const auto& uh = uh_params[static_cast(uh_i)];
-
         int ri = groups_.rain_interval[ug];
+        if (ri <= 0) continue;
+
+        // --- legacy getRainfall: process rain chunks up to the tick.
+        // All chunks of one tick use the rate of the FIRST chunk
+        // (legacy Gage.isCurrent memo — gage_setState runs once per tick).
+        bool have_tick_rate = false;
+        double tick_rate = 0.0;
+        auto& pend = groups_.pending_rates[ug];
+        while (groups_.gage_elapsed[ug] < T) {
+            double c = groups_.gage_elapsed[ug];
+            double rate = pend.empty() ? 0.0 : pend.front();
+            if (!pend.empty()) pend.erase(pend.begin());
+            if (!have_tick_rate) { tick_rate = rate; have_tick_rate = true; }
+            double rainDepth = tick_rate * static_cast(ri) / 3600.0;
+
+            // IA month is the month of the CHUNK date (legacy applyIA uses
+            // gageDate); the buffer month is the tick's.
+            const double chunk_date =
+                datetime::addSeconds(ctx.options.start_date, c);
+            const int chunk_month = datetime::monthOfYear(chunk_date) - 1;
 
-        // Read rainfall from this group's assigned gage (legacy: UnitHyd[j].rainGage)
-        int gi = groups_.gage_idx[ug];
-        double rainfall = 0.0;
-        if (gi >= 0 && gi < static_cast(ctx.gages.rainfall.size())) {
-            rainfall = ctx.gages.rainfall[static_cast(gi)];
-        }
-
-        // Capture rainfall at start of each interval (matching legacy
-        // gage_setState at gageDate, which is the interval start time).
-        if (groups_.time_accum[ug] == 0.0) {
-            groups_.rain_at_start[ug] = rainfall;
-        }
-
-        // Track elapsed time within current rain interval
-        groups_.time_accum[ug] += dt;
-
-        // Only process when full rain interval has elapsed
-        if (groups_.time_accum[ug] < static_cast(ri)) {
-            // Not yet at rain interval boundary — continue with existing
-            // convolution from buffer for continuous RDII output.
-        } else {
-            // Full interval elapsed — compute rainfall depth using the
-            // rainfall rate captured at the START of the interval (matching
-            // legacy: gage_setState(g, gageDate) where gageDate is the
-            // interval start time).
-            double rainDepth = groups_.rain_at_start[ug]
-                             * static_cast(ri) / 3600.0;
-            groups_.time_accum[ug] = 0.0;
-
-            // Store into per-response buffers with IA subtraction
             for (int k = 0; k < 3; ++k) {
                 auto& rd = groups_.uh_data[ug * 3 + static_cast(k)];
                 if (rd.max_periods <= 0) continue;
-
-                // Apply initial abstraction — exponential model if a
-                // [RDII_DECAY] row is active for this (group, response),
-                // otherwise legacy linear iaRecov.
                 bool exp_on = (uh_i < static_cast(decay_params.size())) &&
                               decay_params[static_cast(uh_i)]
                                   [static_cast(k)].active;
@@ -527,44 +603,38 @@ void RDIISolver::computeAll(SimulationContext& ctx, int month, double dt) {
                     ? updateIA_exp(uh, rd,
                                    decay_params[static_cast(uh_i)]
                                                 [static_cast(k)],
-                                   month, k, rainDepth,
+                                   chunk_month, k, rainDepth,
                                    static_cast(ri), ctx)
-                    : updateIA_linear(uh, rd, month, k, rainDepth,
+                    : updateIA_linear(uh, rd, chunk_month, k, rainDepth,
                                       static_cast(ri));
 
-                // Update dry period tracking (matching legacy updateDryPeriod)
                 updateDryPeriod(rd, excessDepth, ri);
 
-                // Store in circular buffer
                 int p = rd.period;
                 if (p >= rd.max_periods) p = 0;
                 rd.past_rain[static_cast(p)] = excessDepth;
-                rd.past_month[static_cast(p)] = month;
+                rd.past_month[static_cast(p)] = tick_month;
                 rd.period = p + 1;
             }
+            groups_.gage_elapsed[ug] = c + static_cast(ri);
         }
 
-        // Convolution for each response — matches legacy getUnitHydConvol()
-        // rdii_group is in rainfall-rate units (in/hr)
+        // --- legacy getUnitHydConvol: convolve past rain with UH ordinates.
         double rdii_group = 0.0;
         for (int k = 0; k < 3; ++k) {
             auto& rd = groups_.uh_data[ug * 3 + static_cast(k)];
             if (!rd.has_past_rain || rd.max_periods <= 0) continue;
 
             int pMax = rd.max_periods;
-            // Start from most recent period and work backwards
             int i_buf = rd.period - 1;
             if (i_buf < 0) i_buf = pMax - 1;
             int p = 1;
-
             while (p < pMax) {
                 double v = rd.past_rain[static_cast(i_buf)];
                 int    m = rd.past_month[static_cast(i_buf)];
                 if (v > 0.0) {
-                    // Mid-point time of UH period (matching legacy)
                     double t = (static_cast(p) - 0.5)
                                * static_cast(ri);
-                    // ordinate × R fraction (legacy: getUnitHydOrd * r[m][k])
                     double u = uhOrdinate(uh, m, k, t) * uh.r[m % 12][k];
                     rdii_group += u * v;
                 }
@@ -574,32 +644,49 @@ void RDIISolver::computeAll(SimulationContext& ctx, int month, double dt) {
             }
         }
 
-        // Convert RDII from rainfall-rate units to CFS:
-        //   rdii_cfs = rdii_group * area_ft2 / UCF(RAINFALL)
-        // where area is in project units (acres for US),
-        // converted to ft2 by dividing by Ucf[LANDAREA].
+        // Node flow: rdii × sewer area / UCF(RAINFALL) (legacy getNodeRdii).
         double area_ft2 = groups_.area[ug] / ucf::Ucf[ucf::LANDAREA][unit_sys];
         double rdii_cfs = rdii_group * area_ft2
                         / ucf::Ucf[ucf::RAINFALL][unit_sys];
-
-        // Buffer RDII flow per node (applied to lat_flow later via applyRdiiInflows)
         int ni = groups_.node_idx[ug];
-        if (ni >= 0 && ni < static_cast(node_rdii_flow_.size())) {
+        if (ni >= 0 && ni < static_cast(node_rdii_flow_.size()))
             node_rdii_flow_[static_cast(ni)] += rdii_cfs;
-        }
+    }
+
+    // Threshold + float32 quantization per node (legacy getNodeRdii writes
+    // REAL4 records; ZERO_RDII zeroes trace flows) and append the grid row.
+    for (std::size_t col = 0; col < grid_node_.size(); ++col) {
+        auto un = static_cast(grid_node_[col]);
+        double q = (un < node_rdii_flow_.size()) ? node_rdii_flow_[un] : 0.0;
+        if (q < ZERO_RDII) q = 0.0;
+        float qf = static_cast(q);
+        node_rdii_flow_[un] = static_cast(qf);
+        grid_flows_.push_back(qf);
     }
 }
 
 // ---------------------------------------------------------------------------
-// applyRdiiInflows — add buffered RDII flows to node lateral inflows.
-// Matching legacy addRdiiInflows() in routing.c which reads pre-computed
-// RDII from the interface file and adds to Node[j].newLatFlow.
+// applyRdiiInflows — add the grid row covering the routing time to node
+// lateral inflows. Legacy addRdiiInflows() streams the RDII interface file:
+// a record at date D covers [D, D + RdiiStep) and dates outside any record
+// contribute zero. The dense zero-filled grid reproduces exactly that.
 // ---------------------------------------------------------------------------
-void RDIISolver::applyRdiiInflows(SimulationContext& ctx) const {
-    for (int i = 0; i < static_cast(node_rdii_flow_.size()); ++i) {
-        double q = node_rdii_flow_[static_cast(i)];
-        if (q == 0.0) continue;
-        ctx.nodes.rdii_inflow[static_cast(i)] += q;
+void RDIISolver::applyRdiiInflows(SimulationContext& ctx,
+                                  double elapsed_sec) const {
+    if (grid_step_ <= 0.0 || grid_node_.empty()) return;
+    if (elapsed_sec < 0.0) return;
+    auto row = static_cast(
+        std::floor(elapsed_sec / grid_step_));
+    const std::size_t ncol = grid_node_.size();
+    if ((row + 1) * ncol > grid_flows_.size()) return;  // beyond emitted grid
+    const float* flows = grid_flows_.data() + row * ncol;
+    for (std::size_t col = 0; col < ncol; ++col) {
+        double q = static_cast(flows[col]);
+        // legacy addRdiiInflows: `if (fabs(q) < FLOW_TOL) continue;`
+        if (std::fabs(q) < constants::FLOW_TOL) continue;
+        auto un = static_cast(grid_node_[col]);
+        if (un < ctx.nodes.rdii_inflow.size())
+            ctx.nodes.rdii_inflow[un] += q;
     }
 }
 
diff --git a/src/engine/hydrology/RDII.hpp b/src/engine/hydrology/RDII.hpp
index 25b729399..bf993b94f 100644
--- a/src/engine/hydrology/RDII.hpp
+++ b/src/engine/hydrology/RDII.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RDII.hpp
  * @brief RDII — rainfall-dependent infiltration/inflow via unit hydrograph.
@@ -14,7 +30,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_RDII_HPP
@@ -118,8 +134,15 @@ struct RDIIGroupSoA {
     std::vector uh_data;
 
     std::vector    rain_interval;  ///< Rain processing interval (sec) per group
-    std::vector time_accum;     ///< Accumulated time (sec) within current interval
-    std::vector rain_at_start;  ///< Rainfall (in/hr) captured at start of interval
+
+    // Strict-grid driver state (legacy createRdiiFile embedded at runtime).
+    // Chunk starts advance in rain_interval steps from simulation start;
+    // rates are recorded per chunk while the runoff substep containing the
+    // chunk's start is current (the substep never crosses a gage entry
+    // boundary, so the current gage rate IS the rate at the chunk start).
+    std::vector gage_elapsed;         ///< Chunk cursor (sec, legacy UHGroup.gageDate)
+    std::vector rate_recorded_until;  ///< Chunk starts with recorded rates (sec)
+    std::vector> pending_rates;  ///< FIFO of recorded chunk rates
 
     void resize(int n);
 };
@@ -150,22 +173,40 @@ class RDIISolver {
     const UhNameMap& uhNameIndex() const { return uh_name_to_idx_; }
 
     /**
-     * @brief Compute RDII inflows for all groups (buffered, not added to lat_flow).
+     * @brief Advance the strict-grid RDII computation to a runoff clock time.
+     *
+     * @details Embeds legacy createRdiiFile()'s driver at runtime: RDII is
+     *          evaluated on the fixed RdiiStep (= wet_step) grid anchored at
+     *          simulation start, with each group's rainfall processed in its
+     *          own rain_interval chunks — NOT on the runoff substep cadence.
+     *          (The previous per-substep accumulator crossed at most one rain
+     *          interval per runoff substep, so a DRY_STEP jump swallowed the
+     *          intermediate intervals: dry-period tracking, IA recovery and
+     *          the convolution grid all corrupted, showing as an RDII onset
+     *          lead/lag of about one wet step.)
      *
-     * @details Reads per-group gage rainfall from ctx.gages.rainfall[gage_idx].
-     *          Convolution: RDII = sum(pastRain[i] * r[m][k] * u(t))
-     *          Results are stored in node_rdii_flow_ for later application.
-     *          Should be called at the wet weather step (matching legacy RdiiStep = WetStep).
+     *          Call once per runoff substep after gage rates (and monthly
+     *          adjustment) are updated, with the substep's END elapsed time.
+     *          The substep never crosses a gage entry boundary (the runoff
+     *          timestep is capped to the next rain date), so the current gage
+     *          rate is exact for every chunk starting inside the substep.
+     *          Per-tick node flows are stored float32 with the legacy
+     *          ZERO_RDII threshold, one grid row per tick, zero-order held
+     *          over [tick, tick + wet_step) at lookup, matching the RDII
+     *          interface file's record windows.
      */
-    void computeAll(SimulationContext& ctx, int month, double dt);
+    void advance(SimulationContext& ctx, double new_elapsed_sec);
 
     /**
-     * @brief Apply buffered RDII inflows to node lateral flows.
+     * @brief Apply RDII inflows at a routing time to node lateral flows.
      *
-     * @details Called during routing to add pre-computed RDII to lat_flow,
-     *          matching legacy addRdiiInflows() which reads from the RDII file.
+     * @details Looks up the strict-grid row whose window contains
+     *          elapsed_sec (the START of the routing step, matching legacy
+     *          addRdiiInflows(currentDate) with currentDate taken at
+     *          routing_execute entry) and adds the stored float32 flows to
+     *          nodes.rdii_inflow.
      */
-    void applyRdiiInflows(SimulationContext& ctx) const;
+    void applyRdiiInflows(SimulationContext& ctx, double elapsed_sec) const;
 
     std::vector uh_params;
 
@@ -191,7 +232,17 @@ class RDIISolver {
 private:
     RDIIGroupSoA groups_;
     UhNameMap uh_name_to_idx_;  ///< UH group name → index (case-insensitive)
-    std::vector node_rdii_flow_;  ///< Buffered per-node RDII flow (CFS)
+    std::vector node_rdii_flow_;  ///< Latest tick's per-node RDII flow (CFS)
+
+    // Strict grid (legacy createRdiiFile records, kept in memory).
+    double grid_step_ = 0.0;        ///< RdiiStep (sec) = wet_step
+    double next_tick_ = 0.0;        ///< Next un-emitted tick (elapsed sec)
+    std::vector   grid_node_;  ///< Column → node index (sorted unique)
+    std::vector grid_flows_; ///< Emitted rows × grid_node_.size(), REAL4
+
+    /// Emit one strict-grid tick at elapsed time T: catch each group's chunk
+    /// processing up to T, convolve, threshold and store the node-flow row.
+    void emitTick(SimulationContext& ctx, double T);
 
     /// Compute UH ordinate at time t for response k, month m.
     double uhOrdinate(const UnitHydParams& uh, int month, int response, double t) const;
diff --git a/src/engine/hydrology/RdiiInterface.cpp b/src/engine/hydrology/RdiiInterface.cpp
index 97568e043..ac84088d3 100644
--- a/src/engine/hydrology/RdiiInterface.cpp
+++ b/src/engine/hydrology/RdiiInterface.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RdiiInterface.cpp
  * @brief RDII interface file — use/save pre-computed RDII inflows.
@@ -10,14 +26,17 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RdiiInterface.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "../core/SimulationContext.hpp"
+#include "../core/Constants.hpp"
 #include "../core/DateTime.hpp"
 #include "../core/UnitConversion.hpp"
 
+#include 
 #include 
 #include 
 
@@ -43,7 +62,7 @@ int RdiiInterfaceFile::openForRead(SimulationContext& ctx,
 
     // Try binary first: check the file stamp (legacy reads strlen(FileStamp)
     // bytes and compares).
-    fp_ = std::fopen(path.c_str(), "rb");
+    fp_ = openswmm::io::fopen_utf8(path, "rb");
     if (!fp_) return -1;
 
     char stamp[16] = {};
@@ -56,7 +75,7 @@ int RdiiInterfaceFile::openForRead(SimulationContext& ctx,
     } else {
         // Not binary — reopen in text mode (legacy openRdiiTextFile).
         std::fclose(fp_);
-        fp_ = std::fopen(path.c_str(), "rt");
+        fp_ = openswmm::io::fopen_utf8(path, "rt");
         if (!fp_) return -1;
         binary_ = false;
         const int rc = readTextHeader(ctx);
@@ -212,8 +231,10 @@ void RdiiInterfaceFile::applyFlows(SimulationContext& ctx,
     for (std::size_t i = 0; i < node_idx_.size(); ++i) {
         const int j = node_idx_[i];
         if (j < 0 || j >= ctx.n_nodes()) continue;
-        ctx.nodes.rdii_inflow[static_cast(j)] +=
-            static_cast(flows_[i]);
+        const double q = static_cast(flows_[i]);
+        // legacy addRdiiInflows: `if (fabs(q) < FLOW_TOL) continue;`
+        if (std::fabs(q) < constants::FLOW_TOL) continue;
+        ctx.nodes.rdii_inflow[static_cast(j)] += q;
     }
 }
 
@@ -226,7 +247,7 @@ int RdiiInterfaceFile::openForWrite(const std::string& path, int rdii_step,
     close();
     if (node_idx.empty()) return -2;   // no RDII in model — nothing to save
 
-    fp_ = std::fopen(path.c_str(), "wb");
+    fp_ = openswmm::io::fopen_utf8(path, "wb");
     if (!fp_) return -1;
 
     writing_ = true;
diff --git a/src/engine/hydrology/RdiiInterface.hpp b/src/engine/hydrology/RdiiInterface.hpp
index aaaf64492..d23afe4c9 100644
--- a/src/engine/hydrology/RdiiInterface.hpp
+++ b/src/engine/hydrology/RdiiInterface.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RdiiInterface.hpp
  * @brief RDII interface file — use/save pre-computed RDII inflows.
@@ -26,7 +42,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_RDII_INTERFACE_HPP
diff --git a/src/engine/hydrology/Runoff.cpp b/src/engine/hydrology/Runoff.cpp
index 6b7f76d2a..4fca08cca 100644
--- a/src/engine/hydrology/Runoff.cpp
+++ b/src/engine/hydrology/Runoff.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Runoff.cpp
  * @brief Subcatchment runoff — 3-subarea nonlinear reservoir model.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Runoff.hpp"
@@ -51,7 +67,8 @@ void RunoffSoA::resize(int n) {
     width.assign(un, 0.0);
     slope.assign(un, 0.0);
     imperv_pct.assign(un, 0.0);
-    imperv0_pct.assign(un, 0.0);
+    frac_imperv0.assign(un, 0.0);
+    frac_imperv1.assign(un, 0.0);
 
     alpha_imperv.assign(un, 0.0);
     alpha_perv.assign(un, 0.0);
@@ -71,8 +88,12 @@ void RunoffSoA::resize(int n) {
     runoff.assign(un, 0.0);
     evap_loss.assign(un, 0.0);
     infil_loss.assign(un, 0.0);
+    perv_evap_vol.assign(un, 0.0);
+    infil_vol.assign(un, 0.0);
+    subarea_runoff_rate.assign(un, 0.0);
     imperv_runoff_cfs.assign(un, 0.0);
     perv_runoff_cfs.assign(un, 0.0);
+    outflow_vol.assign(un, 0.0);
 }
 
 void RunoffSoA::computeAlpha() {
@@ -106,7 +127,8 @@ void RunoffSoA::computeAlpha() {
 // ============================================================================
 
 void RunoffSolver::updatePondedDepth(double& depth, double inflow,
-                                      double alpha, double dStore, double dt) {
+                                      double alpha, double dStore, double dt,
+                                      double& t_runoff) {
     double tx = dt;
 
     // --- Check if not enough inflow to fill depression storage ---
@@ -147,20 +169,9 @@ void RunoffSolver::updatePondedDepth(double& depth, double inflow,
     // --- Clamp to non-negative ---
     // Matches legacy subcatch.c line 1077
     depth = std::max(depth, 0.0);
-}
 
-double RunoffSolver::getRunoffRate(double depth, double dStore, double alpha) {
-    double excess = depth - dStore;
-    // PARITY subcatch.c findSubareaRunoff (line 1016): legacy computes runoff
-    // only when xDepth > ZERO (consts.h ZERO = 1e-10 ft), NOT > 0 — a
-    // recession tail with excess in (0, 1e-10] must report EXACTLY zero
-    // runoff (e.g. Bellinge subcatch 230 at step 36533).
-    if (excess > 1.0e-10) {
-        if (alpha > 0.0)
-            return alpha * std::pow(excess, MEXP);
-        // N=0 case is handled in processSubarea via instant drain
-    }
-    return 0.0;
+    // --- legacy `*dt = tx`: the time the depth spent above storage
+    t_runoff = tx;
 }
 
 // ============================================================================
@@ -184,7 +195,12 @@ void RunoffSolver::init(SimulationContext& ctx) {
         soa_.width[ui]      = ctx.subcatches.width[ui];
         soa_.slope[ui]      = ctx.subcatches.slope[ui];
         soa_.imperv_pct[ui] = ctx.subcatches.frac_imperv[ui];
-        soa_.imperv0_pct[ui]= ctx.subcatches.frac_imperv_no_store[ui];
+        // PARITY subcatch.c:268-270 — multiply by the AUTHORED percent,
+        // divide by 100 afterwards. See RunoffSoA::frac_imperv0.
+        const double fi_ = ctx.subcatches.frac_imperv[ui];
+        const double pz_ = ctx.subcatches.pct_zero[ui];
+        soa_.frac_imperv0[ui] = fi_ * pz_ / 100.0;
+        soa_.frac_imperv1[ui] = fi_ * (1.0 - pz_ / 100.0);
         soa_.n_imperv[ui]   = ctx.subcatches.n_imperv[ui];
         soa_.n_perv[ui]     = ctx.subcatches.n_perv[ui];
         soa_.ds_imperv[ui]  = ctx.subcatches.ds_imperv[ui] / ucf_depth;
@@ -196,6 +212,7 @@ void RunoffSolver::init(SimulationContext& ctx) {
     grnampt_states_.resize(static_cast(n));
     curvenum_states_.resize(static_cast(n));
     infil_models_.resize(static_cast(n), InfilModel::HORTON);
+    infil_factor_used_.assign(static_cast(n), 1.0);
 
     for (int i = 0; i < n; ++i) {
         auto ui = static_cast(i);
@@ -244,6 +261,75 @@ void RunoffSolver::init(SimulationContext& ctx) {
 // Execute — one runoff timestep for ALL subcatchments
 // ============================================================================
 
+// Legacy infil_getInfil (infil.c): dispatch on the subcatchment's model with
+// the [ADJUSTMENTS] / pattern factor and the evaporation recovery factor
+// applied the way each model applies them.
+double RunoffSolver::infilGetInfil(SimulationContext& ctx, int i, double precip,
+                                   double runon, double depth, double dt,
+                                   double local_infil, double recovery_factor) {
+    (void)ctx;
+    auto ui = static_cast(i);
+    double infil = 0.0;
+    const InfilModel im = infil_models_[ui];
+    switch (im) {
+        case InfilModel::HORTON:
+        case InfilModel::MOD_HORTON: {
+            auto& hs = horton_states_[ui];
+            double save_f0 = hs.f0, save_fmin = hs.fmin, save_regen = hs.regen;
+            hs.f0   *= local_infil;
+            hs.fmin *= local_infil;
+            hs.regen *= recovery_factor;
+            infil = (im == InfilModel::HORTON)
+                ? infil::horton_getInfil(hs, precip + runon, depth, dt)
+                : infil::modHorton_getInfil(hs, precip + runon, depth, dt);
+            hs.f0 = save_f0; hs.fmin = save_fmin; hs.regen = save_regen;
+            break;
+        }
+        case InfilModel::GREEN_AMPT:
+        case InfilModel::MOD_GREEN_AMPT: {
+            // Legacy applies InfilFactor and Evap.recoveryFactor inside
+            // grnampt_getInfil, per call, from the unscaled state (ks = Ks*IF,
+            // lu = Lu*sqrt(IF), Fumax = IMDmax*Lu*sqrt(IF), kr = lu/90000*RF,
+            // T = 5400/lu/RF). Baking them into Ks/Lu/Fumax changed both the
+            // operation order and Fumax (which scaled by IF instead of sqrt(IF)).
+            infil = infil::grnampt_getInfil(grnampt_states_[ui],
+                                            precip + runon, depth, dt, im,
+                                            local_infil, recovery_factor);
+            break;
+        }
+        case InfilModel::CURVE_NUM: {
+            auto& cs = curvenum_states_[ui];
+            // Gap #7: CN treats runon as ponded depth, not as a rainfall rate.
+            // Legacy infil.c lines 318-319: depth += runon * tstep; then pass
+            // only rainfall (not rainfall+runon) as the rate argument.
+            double cn_depth = depth + runon * dt;
+            infil = infil::curvenum_getInfil(cs, precip, cn_depth, dt,
+                                             recovery_factor);
+            break;
+        }
+        case InfilModel::CONSTANT:
+            // 2D-only method (plan §5.5.1): [INFILTRATION] has no token for
+            // it, so no subcatchment can carry it. Listed explicitly to keep
+            // the switch exhaustive.
+            break;
+    }
+    return infil;
+}
+
+// Legacy findNativeInfil (lid.c) for a subcatchment whose non-LID area is
+// absent or fully impervious: the native soil's infiltration rate for the
+// subcatchment's own rainfall + runon and pervious ponded depth — a call
+// that advances the subcatchment's infiltration state, as legacy's does.
+double RunoffSolver::nativeInfilFullLid(SimulationContext& ctx, int i, double dt,
+                                        double recovery_factor) {
+    auto ui = static_cast(i);
+    const double rain = ctx.subcatches.rainfall[ui];
+    const double runon = ctx.subcatches.runon_rate[ui];   // legacy Subcatch.runon
+    const double depth = soa_.depth_perv[ui];
+    return infilGetInfil(ctx, i, rain, runon, depth, dt,
+                         infil_factor_used_[ui], recovery_factor);
+}
+
 void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_in,
                            double infil_factor, double recovery_factor, int month) {
     int n = soa_.n_subcatch;
@@ -253,6 +339,7 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
     precip_.resize(un);
     evap_rate_.resize(un);
     infil_rate_.resize(un);
+    const double ucf_landarea = ucf::UCF(ucf::LANDAREA, ctx.options);
 
     // ----- Step 1: Rainfall → net precip (ft/sec) -----
     // Matches legacy getNetPrecip(): all subareas get same precipitation rate.
@@ -271,9 +358,16 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
     for (int i = 0; i < n; ++i) {
         auto ui = static_cast(i);
         gage::PrecipSplit p = gage::splitPrecip(ctx, ui);  // ft/sec
-        double rain_inhr = p.rainfall * ucf::UCF(ucf::RAINFALL, ctx.options);
-        rain_inhr = ctx.forcing.effective_rainfall(ui, rain_inhr);
-        double rain = rain_inhr / ucf::UCF(ucf::RAINFALL, ctx.options);
+        double rain = p.rainfall;
+        // The forcing channel speaks user units; the x*UCF/UCF round trip
+        // is not an identity in floating point, so it runs only when a
+        // forcing is actually set (legacy has no such channel).
+        if (ui < ctx.forcing.subcatch_rainfall_mode.size() &&
+            ctx.forcing.subcatch_rainfall_mode[ui] != ForcingMode::NONE) {
+            double rain_inhr = p.rainfall * ucf::UCF(ucf::RAINFALL, ctx.options);
+            rain_inhr = ctx.forcing.effective_rainfall(ui, rain_inhr);
+            rain = rain_inhr / ucf::UCF(ucf::RAINFALL, ctx.options);
+        }
         double snow = ctx.forcing.effective_snowfall(ui, p.snowfall);
         precip_[ui] = rain + snow;
         ctx.subcatches.rainfall[ui] = precip_[ui];  // ft/sec (internal units)
@@ -301,27 +395,19 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
         auto ui = static_cast(i);
         double fi = soa_.imperv_pct[ui];
         double fp = 1.0 - fi;
-        double f0 = fi * soa_.imperv0_pct[ui];
-        double f1 = fi * (1.0 - soa_.imperv0_pct[ui]);
+        double f0 = soa_.frac_imperv0[ui];
+        double f1 = soa_.frac_imperv1[ui];
         double total_area = soa_.area[ui];  // ft²
 
         double precip  = precip_[ui];     // ft/sec (rainfall + snowmelt)
         double evapRate = evap_rate_[ui]; // ft/sec (global evap rate)
 
-        // Gap #27: subcatchment cascading / runon from upstream subcatchments.
-        // Legacy subcatch_addRunonFlow() distributes upstream runoff (CFS) as
-        // a depth rate (ft/sec) added over the non-LID area of the subcatch.
-        if (total_area > 0.0) {
-            double runon_q = ctx.subcatches.runon_inflow[ui];  // CFS from prev step
-            if (runon_q > 0.0)
-                precip += runon_q / total_area;  // ft/sec over non-LID area
-        }
-
         double alpha_i = soa_.alpha_imperv[ui];
         double alpha_p = soa_.alpha_perv[ui];
 
         // Mass balance accumulators (matching legacy Vevap, Vinfil, Voutflow)
         double Vevap    = 0.0;  // Total evaporation volume (ft³)
+        double Vpevap   = 0.0;  // Pervious-subarea evaporation volume (ft³), legacy Vpevap
         double Vinfil   = 0.0;  // Total infiltration volume (ft³)
         double Voutflow = 0.0;  // Total runoff volume (ft³)
 
@@ -329,7 +415,7 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
         // Args: depth, alpha, dStore, subareaFrac, isPervious, runon
         auto processSubarea = [&](double& depth, double alpha, double dStore,
                                   double frac, bool isPervious,
-                                  double runon_in = 0.0) -> double {
+                                  double runon_in, double subarea_n) -> double {
             if (frac <= 0.0) return 0.0;
             double subarea_area = total_area * frac;
 
@@ -361,60 +447,9 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
                     }
                 }
 
-                // Apply monthly infiltration and recovery factors
-                // (matching legacy infil.c: InfilFactor scales f0/fmin/Ks,
-                //  Evap.recoveryFactor scales regen/kr)
-                const InfilModel im = infil_models_[ui];
-                switch (im) {
-                    case InfilModel::HORTON:
-                    case InfilModel::MOD_HORTON: {
-                        auto& hs = horton_states_[ui];
-                        double save_f0 = hs.f0, save_fmin = hs.fmin, save_regen = hs.regen;
-                        hs.f0   *= local_infil;
-                        hs.fmin *= local_infil;
-                        hs.regen *= recovery_factor;
-                        infil = (im == InfilModel::HORTON)
-                            ? infil::horton_getInfil(hs, precip + runon, depth, dt)
-                            : infil::modHorton_getInfil(hs, precip + runon, depth, dt);
-                        hs.f0 = save_f0; hs.fmin = save_fmin; hs.regen = save_regen;
-                        break;
-                    }
-                    case InfilModel::GREEN_AMPT:
-                    case InfilModel::MOD_GREEN_AMPT: {
-                        auto& gs = grnampt_states_[ui];
-                        double save_Ks    = gs.Ks;
-                        double save_Lu    = gs.Lu;
-                        double save_Fumax = gs.Fumax;
-                        // Gap #5: Legacy infil_setInfilFactor() applies sqrt(InfilFactor) to Lu:
-                        //   lu = 4 * sqrt(Ks * InfilFactor * ucf_rain) / ucf_depth
-                        //      = original_Lu * sqrt(InfilFactor)
-                        // Gap #5: Fumax = IMDmax * lu * sqrt(InfilFactor) = original_Fumax * InfilFactor
-                        // Gap #6: Recovery factor baked into Lu so that inside grnampt_getInfil():
-                        //   kr = lu/90000 = original_Lu * sqrt(if) * rf / 90000 = legacy kr ✓
-                        //   T  = 5400/lu  = 5400 / (original_Lu * sqrt(if) * rf)  = legacy T ✓
-                        double sqrt_infil = std::sqrt(local_infil);
-                        gs.Ks    = save_Ks * local_infil;
-                        gs.Lu    = save_Lu * sqrt_infil * recovery_factor;
-                        gs.Fumax = save_Fumax * local_infil;
-                        infil = infil::grnampt_getInfil(gs, precip + runon, depth, dt, im);
-                        gs.Ks    = save_Ks;
-                        gs.Lu    = save_Lu;
-                        gs.Fumax = save_Fumax;
-                        break;
-                    }
-                    case InfilModel::CURVE_NUM: {
-                        auto& cs = curvenum_states_[ui];
-                        double save_regen = cs.regen;
-                        cs.regen *= recovery_factor;
-                        // Gap #7: CN treats runon as ponded depth, not as a rainfall rate.
-                        // Legacy infil.c lines 318-319: depth += runon * tstep; then pass
-                        // only rainfall (not rainfall+runon) as the rate argument.
-                        double cn_depth = depth + runon * dt;
-                        infil = infil::curvenum_getInfil(cs, precip, cn_depth, dt);
-                        cs.regen = save_regen;
-                        break;
-                    }
-                }
+                infil_factor_used_[ui] = local_infil;
+                infil = infilGetInfil(ctx, i, precip, runon, depth, dt,
+                                      local_infil, recovery_factor);
             }
 
             // Gap #40: limit pervious infiltration by GW upper zone capacity.
@@ -432,33 +467,56 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
 
             // Step 3.5: Update mass balance volumes (legacy lines 934-937)
             Vevap  += surfEvap * subarea_area * dt;
+            // legacy subcatch.c:984 `if (i == PERV) Vpevap += Vevap;` — the
+            // WHOLE subcatchment's surface evaporation so far (the pervious
+            // subarea is processed last, after both impervious ones), not
+            // the pervious share. gwater_getGroundwater subtracts it from
+            // MaxEvap = Evap.rate * FracPerv, so an impervious cover
+            // evaporating at the full rate leaves the aquifer no evaporation
+            // (runoff41-sw5: legacy's soil moisture holds at field capacity).
+            if (isPervious) Vpevap += Vevap;
             Vinfil += infil * subarea_area * dt;
 
             // Step 3.6: Loss check shortcut (legacy lines 945-948)
             // If evaporation + infiltration >= total available moisture,
             // all water is consumed — no runoff, depth goes to zero.
             double runoff_rate = 0.0;
+            double t_runoff = dt;   // legacy tRunoff
             if (surfEvap + infil >= surfMoisture) {
                 depth = 0.0;
             } else {
-                // Step 3.7: Subtract losses from inflow before ODE (legacy line 954)
-                double net_inflow = inflow - surfEvap - infil;
-
-                // Step 3.8: N=0 instant drain — drain all excess above depression storage
-                // (matching legacy: when N=0, alpha=0, excess drains instantly)
-                if (alpha == 0.0) {
-                    depth += net_inflow * dt;
-                    if (depth > dStore) {
-                        runoff_rate = (depth - dStore) / dt;
+                // Step 3.7: Subtract losses from inflow before ODE. Legacy is
+                // `subarea->inflow -= surfEvap + infil` (subcatch.c:1002) — the
+                // two losses are summed FIRST and the sum subtracted once.
+                // Written as `inflow - surfEvap - infil` the subtraction
+                // rounds twice and lands one ULP away whenever the pervious
+                // infiltration is small next to the evaporation; that ULP
+                // seeds the whole network (user3's CCECROY at runoff step
+                // 11641 of 43200, then every link flow from report period 107
+                // on). Impervious subareas have infil == 0.0 and are
+                // unaffected either way.
+                double net_inflow = inflow - (surfEvap + infil);
+                // Step 3.8: Integrate ponded depth (legacy updatePondedDepth:
+                // with alpha 0 the depth simply accumulates), and keep the
+                // time it spent above storage for the no-routing case.
+                updatePondedDepth(depth, net_inflow, alpha, dStore, dt, t_runoff);
+            }
+
+            // Step 3.9: legacy findSubareaRunoff, keyed on Manning's N — NOT
+            // on alpha: a subarea with N > 0 on a ZERO-slope subcatchment has
+            // alpha 0 and legacy's runoff is Alpha*pow(...) = 0, the water
+            // ponds; only N == 0 drains the excess instantly, over tRunoff.
+            // Keyed on alpha, the flat S27 of 185-h-h-elements-si-units
+            // (%Slope 0) drained instantly where legacy reports no runoff.
+            {
+                const double xDepth = depth - dStore;
+                if (xDepth > 1.0e-10) {          // legacy ZERO
+                    if (subarea_n > 0.0) {
+                        runoff_rate = alpha * std::pow(xDepth, MEXP);
+                    } else {
+                        runoff_rate = xDepth / t_runoff;
                         depth = dStore;
                     }
-                    depth = std::max(depth, 0.0);
-                } else {
-                    // Step 3.8b: Integrate ponded depth via ODE (legacy line 955)
-                    updatePondedDepth(depth, net_inflow, alpha, dStore, dt);
-
-                    // Step 3.9: Compute runoff from final depth (legacy line 959)
-                    runoff_rate = getRunoffRate(depth, dStore, alpha);
                 }
             }
 
@@ -482,16 +540,45 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
             return runoff_rate;
         };
 
-        // --- Inter-subarea routing: compute runon from previous step ---
-        // (matching legacy subcatch_getRunon)
+        // --- Subarea inflows (legacy subcatch_getRunon), in its order ---
+        // Every subarea's inflow starts with the subcatchment's run-on from
+        // upstream subcatchments / outfalls / LID drains (subcatch_addRunonFlow
+        // adds the same depth rate to all three; runon_rate is that sum,
+        // formed in legacy's order by SWMMEngine::assembleRunon), then the
+        // inter-subarea transfer of the PREVIOUS step's runoff, then the LID
+        // return flow onto the pervious subarea. The run-on is NOT rainfall:
+        // it reaches the infiltration kernel as `runon` (Horton / Green-Ampt
+        // add it to the rate, the curve number adds it to the ponded depth —
+        // infil_getInfil), and the snow-modified per-subarea precipitation
+        // below replaces only the precipitation. Folded into `precip` it
+        // was infiltrated as rain on a curve-number deck whose subcatchments
+        // drain onto each other (185-h-h-elements-si-units S20 -> S21) and
+        // vanished on a snow deck.
         // route_mode: 0=TO_OUTLET, 1=TO_IMPERV (perv→imperv), 2=TO_PERV (imperv→perv)
         int route_mode = ctx.subcatches.subarea_routing[ui];
         double pct = ctx.subcatches.pct_routed[ui];
-        double runon_imperv = 0.0;  // additional inflow to imperv subareas (ft/sec)
-        double runon_perv   = 0.0;  // additional inflow to pervious subarea (ft/sec)
+        const double f_outlet = 1.0 - pct;   // legacy subArea.fOutlet
+        const double runon_sub = (total_area > 0.0) ? ctx.subcatches.runon_rate[ui] : 0.0;
+        double runon_imperv0 = runon_sub;
+        double runon_imperv1 = runon_sub;
+        double runon_perv    = runon_sub;
+
+        if (route_mode == 2 && fp > 0.0) {
+            // legacy Case 1, imperv --> perv: area-weighted outflow of both
+            // impervious subareas, (1 - fOutlet) of it, over the pervious area
+            double q1 = soa_.old_runoff_imperv0[ui] * f0;
+            double q2 = soa_.old_runoff_imperv1[ui] * f1;
+            double q  = q1 + q2;
+            runon_perv += q * (1.0 - f_outlet) / fp;
+        }
+        else if (route_mode == 1 && f1 > 0.0) {
+            // legacy Case 2, perv --> imperv (needs an IMPERV1 area)
+            double q = soa_.old_runoff_perv[ui];
+            runon_imperv1 += q * (1.0 - f_outlet) * fp / f1;
+        }
 
-        // Gap #23: LID return flow to pervious area (to_perv==1 from previous step).
-        // Matches legacy lid_getFlowToPerv() called in subcatch_getRunon() — one-step lag.
+        // Gap #23: LID return flow to pervious area (legacy lid_getFlowToPerv
+        // in subcatch_getRunon — one-step lag), after the transfer above.
         {
             double q_ret = ctx.subcatches.lid_return_to_perv_cfs[ui];
             if (q_ret > 0.0 && total_area > 0.0 && fp > 0.0) {
@@ -501,19 +588,6 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
             ctx.subcatches.lid_return_to_perv_cfs[ui] = 0.0;  // consume
         }
 
-        if (route_mode == 2 && fp > 0.0) {
-            // IMPERV → PERV: route fraction of imperv runoff to pervious
-            double q1 = soa_.old_runoff_imperv0[ui] * f0;  // area-wtd rate
-            double q2 = soa_.old_runoff_imperv1[ui] * f1;
-            double q  = q1 + q2;
-            runon_perv = q * pct / fp;  // distribute over pervious area fraction
-        }
-        else if (route_mode == 1 && f1 > 0.0) {
-            // PERV → IMPERV: route fraction of perv runoff to impervious
-            double q = soa_.old_runoff_perv[ui] * fp;  // area-wtd rate
-            runon_imperv = q * pct / f1;  // distribute over IMPERV1 area fraction
-        }
-
         // Gap #20: When snow is active, use snow-modified net precip per subarea
         // (imelt + rainfall*(1-asc)) instead of raw rainfall.
         // precip is captured by reference in processSubarea, so setting it here
@@ -532,17 +606,48 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
         }
 
         // Process all 3 subareas (matching legacy loop: IMPERV0, IMPERV1, PERV)
-        // IMPERV0 never receives runon (zero depression storage area)
         precip = precip_imperv;
         double runoff0  = processSubarea(soa_.depth_imperv0[ui], alpha_i, 0.0,
-                                         f0, false, 0.0);
-        // IMPERV1 receives runon from pervious when route_mode==TO_IMPERV
+                                         f0, false, runon_imperv0, soa_.n_imperv[ui]);
         double runoff1  = processSubarea(soa_.depth_imperv1[ui], alpha_i,
-                                         soa_.ds_imperv[ui], f1, false, runon_imperv);
-        // PERV receives runon from impervious when route_mode==TO_PERV
+                                         soa_.ds_imperv[ui], f1, false, runon_imperv1,
+                                         soa_.n_imperv[ui]);
+        // legacy adjustSubareaParams (subcatch.c:1168-1200): the PERVIOUS
+        // subarea's depression storage and runoff coefficient carry this
+        // month's [ADJUSTMENTS] DSTORE / N-PERV pattern, re-applied to the
+        // STORED values every runoff step. Alpha is DIVIDED by the roughness
+        // factor — not re-derived from n*f, which rounds differently — and a
+        // factor <= 0 zeroes it outright. v6 instead scaled ctx.subcatches
+        // .n_perv / .ds_perv once per step, which the runoff kernel never
+        // read back (its alphas and storages are snapshotted in init()), so
+        // both adjustments were inert.
+        double alpha_p_adj  = alpha_p;
+        double ds_perv_adj  = soa_.ds_perv[ui];
+        if (month >= 0) {
+            const auto umon = static_cast(month);
+            auto monthly = [&](const std::vector& pat, double& out) -> bool {
+                if (ui >= pat.size()) return false;
+                const int pi = pat[ui];
+                if (pi < 0) return false;
+                const auto upi = static_cast(pi);
+                if (upi >= ctx.patterns.types.size() || ctx.patterns.types[upi] != 0)
+                    return false;
+                const auto& facs = ctx.patterns.factors[upi];
+                if (umon >= facs.size()) return false;
+                out = facs[umon];
+                return true;
+            };
+            double f = 0.0;
+            if (monthly(ctx.subcatch_d_store_pattern, f) && f >= 0.0)
+                ds_perv_adj *= f;
+            if (monthly(ctx.subcatch_n_perv_pattern, f))
+                alpha_p_adj = (f <= 0.0) ? 0.0 : alpha_p_adj / f;
+        }
+
         precip = precip_perv;
-        double runoff_p = processSubarea(soa_.depth_perv[ui], alpha_p,
-                                         soa_.ds_perv[ui], fp, true, runon_perv);
+        double runoff_p = processSubarea(soa_.depth_perv[ui], alpha_p_adj,
+                                         ds_perv_adj, fp, true, runon_perv,
+                                         soa_.n_perv[ui]);
         precip = precip_[ui];   // restore for subsequent use
 
 
@@ -551,11 +656,52 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
         soa_.old_runoff_imperv1[ui] = runoff1;
         soa_.old_runoff_perv[ui]    = runoff_p;
 
+        // legacy subcatch_getRunoff's return value (subcatch.c:714-724,
+        // 773): `runoff += subArea[i].runoff * area_i` over the three
+        // subareas when nonLidArea > 0, then `/ Subcatch.area` — the whole
+        // surface's runoff BEFORE the imperv->perv / perv->imperv transfer
+        // and the LID exchange. runoff_execute keeps the WET step while it
+        // is positive: a zero-storage impervious subarea routed to the
+        // pervious one trickles for hours after the rain, and the outlet
+        // runoff (newRunoff) is 0 the whole time (117-h-h-elements-si-units
+        // took the 1 h DRY step there, so its curve-number ponding was
+        // tested against MIN_TOTAL_DEPTH an hour late).
+        {
+            double sum = 0.0;
+            if (total_area > 0.0) {
+                sum += runoff0  * (total_area * f0);
+                sum += runoff1  * (total_area * f1);
+                sum += runoff_p * (total_area * fp);
+            }
+            const double full_area = ctx.subcatches.area[ui] / ucf_landarea;
+            soa_.subarea_runoff_rate[ui] = (full_area > 0.0) ? sum / full_area : 0.0;
+        }
+
         // Gap #23: Store per-subarea runoff CFS for LID inflow computation.
         // Matches legacy qImperv/qPerv used in lid_getRunoff() lid.c line ~1669.
-        soa_.imperv_runoff_cfs[ui] = (runoff0 * total_area * f0)
-                                   + (runoff1 * total_area * f1);
-        soa_.perv_runoff_cfs[ui]   =  runoff_p * total_area * fp;
+        //
+        // Legacy getImpervAreaRunoff()/getPervAreaRunoff() scale by the same
+        // fOutlet the outlet volume above uses, so only the share that actually
+        // reaches the outlet is offered to the LID. `total_area` is already
+        // max(0, area − lidArea), i.e. legacy's nonLidArea. Without the fOutlet
+        // factor the LID inflow is overstated on any deck with inter-subarea
+        // routing, and the −VlidIn subtraction in SWMMEngine::stepRunoff — which
+        // removes exactly this captured share from the outlet runoff — could
+        // then drive that runoff negative.
+        // legacy getImpervAreaRunoff / getPervAreaRunoff op order (lid.c:
+        // 1794-1846): sum the subareas' DEPTH rates weighted by their area
+        // FRACTIONS, apply fOutlet to that sum, and multiply by the non-LID
+        // area ONCE at the end. Multiplying each term by the area first
+        // rounds differently (1-ULP q_imperv/q_perv, which VlidIn carries
+        // into the runoff of every LID subcatchment).
+        {
+            double q_i = runoff0 * f0 + runoff1 * f1;
+            if (route_mode == 2 && soa_.imperv_pct[ui] < 1.0) q_i *= 1.0 - pct;
+            soa_.imperv_runoff_cfs[ui] = q_i * total_area;
+            double q_p = runoff_p * fp;
+            if (route_mode == 1 && soa_.imperv_pct[ui] > 0.0) q_p *= 1.0 - pct;
+            soa_.perv_runoff_cfs[ui] = q_p * total_area;
+        }
 
         // ----- Step 4: Compute loss rates and net runoff -----
         // Matches legacy lines 700-709.
@@ -566,11 +712,38 @@ void RunoffSolver::execute(SimulationContext& ctx, double dt, double evap_rate_i
         double newRunoff = Voutflow / dt;  // CFS
 
         soa_.runoff[ui] = newRunoff;
+        soa_.outflow_vol[ui] = Voutflow;   // ft3, for the LID volume-domain fold
 
         // Write back to SimulationContext
         ctx.subcatches.runoff[ui]     = newRunoff;
+        // legacy subcatch_getRunoff's RETURN (`runoff / area`, ft/sec) — the
+        // rate the surface-quality paths wash off with. Mirrored onto the
+        // context so the pollutant and reactions-species kernels share one
+        // number; see SubcatchData::subarea_runoff_rate.
+        ctx.subcatches.subarea_runoff_rate[ui] = soa_.subarea_runoff_rate[ui];
+        // legacy subcatch_getDepth: the area-weighted mean depth of ponded
+        // water over the NON-LID subareas, the store findPondedLoads mixes
+        // wet deposition and run-on into. `ctx.subcatches.ponded_depth` was
+        // declared and read in three places but WRITTEN BY NOBODY, so the
+        // ponded pool was permanently empty: the whole findPondedLoads
+        // mirror was inert, and a subcatchment shed its rainfall-borne load
+        // the instant the rain stopped instead of draining it down the
+        // recession. The subarea fractions are the same triple the runoff
+        // mass balance and the age/heat watershed mirrors weight with.
+        {
+            const double fi = soa_.imperv_pct[ui];
+            ctx.subcatches.ponded_depth[ui] =
+                soa_.depth_imperv0[ui] * soa_.frac_imperv0[ui] +
+                soa_.depth_imperv1[ui] * soa_.frac_imperv1[ui] +
+                soa_.depth_perv[ui]    * (1.0 - fi);
+        }
         ctx.subcatches.evap_loss[ui]  = evapLoss;
         ctx.subcatches.infil_loss[ui] = infilLoss;
+        // The volumes themselves, for the groundwater step: legacy hands
+        // gwater_getGroundwater Vpevap and Vinfil (+ the LID shares) and
+        // divides by the FULL area then by tStep there.
+        soa_.perv_evap_vol[ui] = Vpevap;
+        soa_.infil_vol[ui]     = Vinfil;
 
         // Accumulate per-subcatchment statistics (matching legacy stats_updateSubcatchStats)
         ctx.subcatches.stat_evap_vol[ui]  += Vevap;
@@ -630,6 +803,8 @@ void RunoffSolver::infil_get_state(int i, int& model, double state[6]) const noe
             state[5] = c.T;
             break;
         }
+        case InfilModel::CONSTANT:
+            break;  // 2D-only, stateless — nothing to save
     }
 }
 
@@ -669,6 +844,8 @@ void RunoffSolver::infil_set_state(int i, int model, const double state[6]) noex
             c.T  = state[5];
             break;
         }
+        case InfilModel::CONSTANT:
+            break;  // 2D-only, stateless — nothing to restore
     }
 }
 
diff --git a/src/engine/hydrology/Runoff.hpp b/src/engine/hydrology/Runoff.hpp
index 9678fcaa1..df53bb231 100644
--- a/src/engine/hydrology/Runoff.hpp
+++ b/src/engine/hydrology/Runoff.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Runoff.hpp
  * @brief Subcatchment runoff generation — batch-oriented nonlinear reservoir.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_RUNOFF_HPP
@@ -52,7 +68,18 @@ struct RunoffSoA {
     std::vector width;         ///< Subcatchment width (ft)
     std::vector slope;         ///< Average slope (ft/ft)
     std::vector imperv_pct;    ///< Impervious fraction (0-1)
-    std::vector imperv0_pct;   ///< Fraction of imperv with zero dStore (0-1)
+    /// The three subarea area fractions, formed exactly as legacy forms them
+    /// (subcatch.c:268-270) from the AUTHORED [SUBAREAS] PctZero percent:
+    ///   frac_imperv0 = fracImperv * PctZero / 100
+    ///   frac_imperv1 = fracImperv * (1 - PctZero / 100)
+    /// Legacy multiplies by the percent and divides afterwards; dividing
+    /// first and multiplying by the stored 0-1 fraction is a different
+    /// double for about a tenth of all percentages, and the difference lands
+    /// straight in the subarea's area. Every consumer — the runoff kernel,
+    /// the stored-volume accounting, the water-age and heat watershed
+    /// modules — reads these so there is one definition of the split.
+    std::vector frac_imperv0;  ///< IMPERV0 (no depression storage)
+    std::vector frac_imperv1;  ///< IMPERV1 (with depression storage)
 
     // Per-subarea SoA: alpha = runoff coefficient
     std::vector alpha_imperv;  ///< Alpha for impervious subareas
@@ -81,11 +108,23 @@ struct RunoffSoA {
     std::vector runoff;             ///< Total runoff rate (cfs)
     std::vector evap_loss;          ///< Evaporation loss (ft3)
     std::vector infil_loss;         ///< Infiltration loss (ft3)
+    std::vector perv_evap_vol;      ///< Pervious-subarea evaporation this step (ft3) — legacy Vpevap
+    std::vector infil_vol;          ///< Non-LID infiltration this step (ft3) — legacy Vinfil
+    /// legacy subcatch_getRunoff's return value: the three subareas' runoff
+    /// summed over their areas and divided by the FULL area (ft/s), before
+    /// the inter-subarea routing and the LID exchange — what runoff_execute
+    /// tests for HasRunoff and hands surfqual_getWashoff.
+    std::vector subarea_runoff_rate;
 
     // Per-subcatchment: per-subarea runoff CFS from non-LID area (Gap #23)
     // Used by SWMMEngine to compute LID unit inflow from impervious/pervious fractions.
     std::vector imperv_runoff_cfs;  ///< Impervious subarea runoff (CFS, non-LID area)
     std::vector perv_runoff_cfs;    ///< Pervious subarea runoff (CFS, non-LID area)
+    /// Legacy Voutflow: this step's outlet runoff VOLUME from the non-LID
+    /// area (ft3). Kept so the LID exchange can rebuild newRunoff in the
+    /// volume domain exactly as legacy subcatch.c:746-751 does
+    /// (`vOutflow = Voutflow - VlidIn + VlidOut; newRunoff = vOutflow/tStep`).
+    std::vector outflow_vol;
 
     void resize(int n);
     void computeAlpha();
@@ -106,6 +145,15 @@ class RunoffSolver {
                  double infil_factor = 1.0, double recovery_factor = 1.0,
                  int month = -1);
 
+    /// Legacy findNativeInfil for a subcatchment with no pervious non-LID
+    /// area: the native soil's rate for its own rain + runon (advances the
+    /// subcatchment's infiltration state, as legacy does).
+    double nativeInfilFullLid(SimulationContext& ctx, int i, double dt,
+                              double recovery_factor);
+
+    /// The InfilFactor the last execute() applied to subcatchment i.
+    double infilFactorUsed(int i) const { return infil_factor_used_[static_cast(i)]; }
+
     const RunoffSoA& soa() const { return soa_; }
 
     // -----------------------------------------------------------------------
@@ -143,6 +191,12 @@ class RunoffSolver {
 
     // Infiltration state (one per subcatchment)
     std::vector     infil_models_;   ///< Per-subcatchment model type (BUG FIX: was a single shared field)
+    std::vector         infil_factor_used_; ///< The InfilFactor applied to each subcatchment this step (pattern or global)
+
+    /// Legacy infil_getInfil: the model dispatch with the factors applied.
+    double infilGetInfil(SimulationContext& ctx, int i, double precip, double runon,
+                         double depth, double dt, double local_infil,
+                         double recovery_factor);
     std::vector    horton_states_;
     std::vector grnampt_states_;
     std::vector  curvenum_states_;
@@ -154,11 +208,11 @@ class RunoffSolver {
 
     /// Solve dd/dt = inflow - alpha*(d-Ds)^(5/3) using RK45.
     /// Matches legacy updatePondedDepth() + odesolve_integrate().
+    /// `t_runoff` returns legacy's tRunoff: the part of `dt` over which the
+    /// depth stood above the depression storage (`*dt = tx`).
     static void updatePondedDepth(double& depth, double inflow, double alpha,
-                                  double dStore, double dt);
+                                  double dStore, double dt, double& t_runoff);
 
-    /// Compute runoff rate from final depth (after ODE integration).
-    static double getRunoffRate(double depth, double dStore, double alpha);
 };
 
 } // namespace runoff
diff --git a/src/engine/hydrology/RunoffInterface.cpp b/src/engine/hydrology/RunoffInterface.cpp
index fda2357fe..2d2f9d35f 100644
--- a/src/engine/hydrology/RunoffInterface.cpp
+++ b/src/engine/hydrology/RunoffInterface.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RunoffInterface.cpp
  * @brief Runoff interface file — binary save/load of pre-computed runoff.
@@ -9,10 +25,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RunoffInterface.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
 #include 
@@ -32,7 +49,7 @@ constexpr double MIN_RUNOFF = 2.31481e-8;
 
 int RunoffInterfaceFile::openForWrite(const std::string& path, int n_subcatch,
                                       int n_pollut, int flow_units) {
-    fp_ = std::fopen(path.c_str(), "wb");
+    fp_ = openswmm::io::fopen_utf8(path, "wb");
     if (!fp_) return -1;
 
     writing_ = true;
@@ -70,7 +87,7 @@ int RunoffInterfaceFile::openForWrite(const std::string& path, int n_subcatch,
 
 int RunoffInterfaceFile::openForRead(const std::string& path, int n_subcatch,
                                      int n_pollut, int flow_units) {
-    fp_ = std::fopen(path.c_str(), "rb");
+    fp_ = openswmm::io::fopen_utf8(path, "rb");
     if (!fp_) return -1;
 
     writing_ = false;
diff --git a/src/engine/hydrology/RunoffInterface.hpp b/src/engine/hydrology/RunoffInterface.hpp
index 6e6234d7c..c2dfb5cc6 100644
--- a/src/engine/hydrology/RunoffInterface.hpp
+++ b/src/engine/hydrology/RunoffInterface.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RunoffInterface.hpp
  * @brief Runoff interface file — save/load pre-computed runoff results.
@@ -41,7 +57,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_RUNOFF_INTERFACE_HPP
diff --git a/src/engine/hydrology/Snow.cpp b/src/engine/hydrology/Snow.cpp
index 645671730..5f27b5c8a 100644
--- a/src/engine/hydrology/Snow.cpp
+++ b/src/engine/hydrology/Snow.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Snow.cpp
  * @brief Snowmelt — batch-oriented, vectorisable kernels.
@@ -5,13 +21,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Snow.hpp"
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
 #include 
+#include 
 #include 
 
 namespace openswmm {
@@ -26,7 +43,15 @@ void SnowSoA::resize(int n) {
     fw.assign(total, 0.0);
     coldc.assign(total, 0.0);
     ati.assign(total, 32.0);
-    awe.assign(total, 0.0);
+    // 1.0, matching legacy `snow_initSnowpack` (snow.c:199). The new-snow
+    // ADC index starts ABOVE any real pack, so `awesi < awe` sends the first
+    // depleting step to the regular curve. Initialising it to 0 makes
+    // `awesi >= awe` true instead and `getArealDepletion` returns full cover
+    // forever — which was invisible while `si` was pinned to the initial pack
+    // depth, because the `wsnow >= si` branch then fired on step 1 and set
+    // `awe = 1.0` itself. Reading SD100 (F6) is what exposes it: a pack that
+    // starts BELOW its SD100 never takes that branch.
+    awe.assign(total, 1.0);
     imelt.assign(total, 0.0);
     tbase.assign(total, 32.0);
     dhm.assign(total, 0.0);
@@ -34,6 +59,8 @@ void SnowSoA::resize(int n) {
     dhmax.assign(total, 0.0);
     fwfrac.assign(total, 0.1);
     fArea.assign(total, 0.0);
+    age.assign(total, 0.0);
+    out_age.assign(total, 0.0);
     si.assign(total, 0.0);
     sba.assign(total, 0.0);
     sbws.assign(total, 0.0);
@@ -56,100 +83,125 @@ void SnowSolver::init(int n_subcatch) {
 /// @param adc    10-point curve (index 0-9 maps to AWESI 0.0-0.9+)
 /// @param awesi  Snow water equivalent relative to depth at 100% cover
 /// @return       Areal snow coverage fraction (0 to 1)
+// ============================================================================
+// S2b — complete-mix age arithmetic
+// ============================================================================
+
+/**
+ * @brief Mix `v_in` of water at age `a_in` into a pool holding `v_have` at
+ *        age `a_have`. Returns the pool's new age.
+ *
+ * @details Volume-weighted, and **guarded on the TOTAL rather than on either
+ *          term**: a pool that is empty before and after has no age to
+ *          report, and returning anything but 0 there would let a stale age
+ *          survive a pack that no longer exists. That is the shape of the
+ *          dry-element carried-temperature item still open from H1, and it
+ *          is cheaper to not create it than to mask it later.
+ *
+ * @note Removing water at the pool's own age leaves the age UNCHANGED, so
+ *       drainage and melt-out need no call here — only arrivals do.
+ */
+static inline double mixAge(double v_have, double a_have,
+                            double v_in, double a_in) noexcept {
+    const double v = v_have + v_in;
+    if (!(v > 0.0)) return 0.0;
+    return (v_have * a_have + v_in * a_in) / v;
+}
+
+// Legacy getArealSnowCover (snow.c:691): the ADC plots the covered fraction
+// at 10 equal awesi increments; the last interval interpolates to 1.0.
 static double getArealSnowCover(const double* adc, double awesi) {
-    if (awesi >= 0.9999) return 1.0;
     if (awesi <= 0.0)    return 0.0;
-    double x = awesi * 10.0;
-    int k = static_cast(x);
-    if (k >= 9) return adc[9];
-    double frac = x - static_cast(k);
-    return adc[k] + frac * (adc[k + 1] - adc[k]);
+    if (awesi >= 0.9999) return 1.0;
+    int m = static_cast(awesi * 10.0 + 0.00001);
+    double asc1 = adc[m];
+    double asc2 = (m >= 9) ? 1.0 : adc[m + 1];
+    return asc1 + (asc2 - asc1) / 0.1 * (awesi - 0.1 * static_cast(m));
 }
 
 // ============================================================================
-// Areal depletion with new-snow ADC transition (Gap #18)
-// Matches legacy getArealDepletion() in snow.c.
-// wsnow is the PRE-snowfall snow water equivalent for this step.
+// Areal depletion with new-snow ADC transition — legacy getArealDepletion
+// (snow.c:610), statement for statement. `wsnow` already carries this
+// step's snowfall (snow_plowSnow ran first), which is why the new-snow
+// branch subtracts it back out to find the pre-snow index.
 // ============================================================================
 
 /// @param soa      Snow state arrays (sba/sbws/awe updated in place).
 /// @param ui       Flat array index (subcatch * N_SUBAREAS + subarea).
 /// @param subarea  Subarea index (SNOW_PLOWABLE, SNOW_IMPERV, SNOW_PERV).
-/// @param snowfall Snowfall rate this step (ft/sec); 0 = melting/no-snow event.
+/// @param snowfall Snowfall rate this step (ft/sec).
 /// @param dt       Timestep (sec).
 /// @return         Areal snow coverage fraction (0 to 1).
 static double getArealDepletion(SnowSoA& soa, std::size_t ui, int subarea,
                                 double snowfall, double dt) {
-    // Plowable sub-area not subject to areal depletion (always 100% covered).
+    // Plowable sub-area not subject to areal depletion.
     if (subarea == SNOW_PLOWABLE) return 1.0;
 
-    double si_val = soa.si[ui];
-    double wsnow  = soa.wsnow[ui];
+    const double si = soa.si[ui];
 
-    // No depletion if si == 0 or pack is at or above 100%-cover depth.
-    if (si_val <= 0.0 || wsnow >= si_val) {
+    // No depletion if depth zero or above SI.
+    if (si == 0.0 || soa.wsnow[ui] >= si) {
         soa.awe[ui] = 1.0;
         return 1.0;
     }
-    // Zero snow → no coverage.
-    if (wsnow <= 0.0) {
+    if (soa.wsnow[ui] == 0.0) {
         soa.awe[ui] = 1.0;
         return 0.0;
     }
 
     const double* adc = (subarea == SNOW_PERV) ? soa.adc_perv : soa.adc_imperv;
 
-    // Case: new snowfall this step (Gap #18 — new-snow ADC branch).
-    // wsnow is pre-snowfall, so awe is the index before the new snow was added.
+    // Case of new snowfall.
     if (snowfall > 0.0) {
-        double awe   = wsnow / si_val;                             // pre-snow index
+        double awe = (soa.wsnow[ui] - snowfall * dt) / si;
         awe = std::max(awe, 0.0);
-        double sba   = getArealSnowCover(adc, awe);               // coverage at that index
-        double sbws  = awe + (0.75 * snowfall * dt) / si_val;     // end of new-snow ADC
+        double sba  = getArealSnowCover(adc, awe);
+        double sbws = awe + (0.75 * snowfall * dt) / si;
         sbws = std::min(sbws, 1.0);
         soa.awe[ui]  = awe;
         soa.sba[ui]  = sba;
         soa.sbws[ui] = sbws;
-        return 1.0;   // full coverage while actively snowing
+        return 1.0;
     }
 
-    // Case: no new snow — deplete using stored new-snow ADC state.
-    double awe   = soa.awe[ui];
-    double sba   = soa.sba[ui];
-    double sbws  = soa.sbws[ui];
-    double awesi = wsnow / si_val;   // current relative index
-
-    if (awesi < awe) {
-        // Pack has melted below the start of the new-snow ADC → use regular curve.
-        soa.awe[ui] = 1.0;   // reset for next snowfall event
-        return getArealSnowCover(adc, awesi);
-    }
-    if (awesi >= sbws) {
-        // Pack depth still at or above end of new-snow ADC → full coverage.
-        return 1.0;
+    // Case of no new snow.
+    const double awe   = soa.awe[ui];
+    const double sba   = soa.sba[ui];
+    const double sbws  = soa.sbws[ui];
+    const double awesi = soa.wsnow[ui] / si;
+    double asc;
+    if (awesi < soa.awe[ui]) {
+        // relative snow depth is below start of new snow ADC
+        soa.awe[ui] = 1.0;
+        asc = getArealSnowCover(adc, awesi);
+    } else if (awesi >= soa.sbws[ui]) {
+        // relative snow depth is above end of new snow ADC
+        asc = 1.0;
+    } else {
+        // relative snow depth is on new snow ADC
+        asc = sba + (1.0 - sba) / (sbws - awe) * (awesi - awe);
     }
-    // On the linear new-snow ADC segment.
-    if (sbws <= awe) return sba;   // degenerate: zero-width interval
-    return sba + (1.0 - sba) / (sbws - awe) * (awesi - awe);
+    return asc;
 }
 
 // ============================================================================
-// Rain-on-snow melt rate (legacy: getRainmelt) — one rainfall value
+// Rain-on-snow melt rate — legacy getRainmelt (snow.c:775). Returns the raw
+// value (it can be NEGATIVE below 32 F); the caller applies legacy's
+// `rmelt > 0` test.
 // ============================================================================
 
 double SnowSolver::rainMeltRate(double temp, double wind, double gamma,
                                  double ea, double rainfall) {
-    // Only applies when rainfall > 0.02 in/hr converted to ft/sec
-    const double ucf_rain_us = ucf::Ucf[ucf::RAINFALL][0]; // US: in/hr ↔ ft/sec
-    if (rainfall <= 0.02 / ucf_rain_us) return 0.0;
-
-    double rain_in_hr = rainfall * ucf_rain_us;  // ft/sec → in/hr
-    double uadj = 0.006 * wind;
-    double t1 = temp - 32.0;
-    double t2 = 7.5 * gamma * uadj;
-    double t3 = 8.5 * uadj * (ea - 0.18);
-    double smelt_in_hr = t1 * (0.001167 + t2 + 0.007 * rain_in_hr) + t3;
-    return std::max(smelt_in_hr / ucf_rain_us, 0.0);  // in/hr → ft/sec
+    rainfall = rainfall * 43200.0;     // convert rain to in/hr
+    if (rainfall > 0.02) {
+        double uadj = 0.006 * wind;
+        double t1 = temp - 32.0;
+        double t2 = 7.5 * gamma * uadj;
+        double t3 = 8.5 * uadj * (ea - 0.18);
+        double smelt = t1 * (0.001167 + t2 + 0.007 * rainfall) + t3;
+        return smelt / 43200.0;
+    }
+    return 0.0;
 }
 
 // ============================================================================
@@ -167,154 +219,147 @@ void SnowSolver::execute(SimulationContext& ctx, double dt,
 }
 
 // ============================================================================
-// Execute — all subcatchments batch
+// Execute — legacy snow_getSnowMelt (snow.c:510) for every subcatchment,
+// each snow sub-area in legacy's order and with legacy's arithmetic:
+// getArealDepletion -> meltSnowpack (getRainmelt / degree-day /
+// updateColdContent, reduceColdContent) -> routeSnowmelt. The result per
+// surface is `imelt` = the liquid melt rate leaving the pack (legacy's
+// `smelt + snowpack->imelt`, the second being the plowed/instant melt), and
+// `asc`, from which the engine forms legacy's netPrecip.
 // ============================================================================
 
-void SnowSolver::execute(SimulationContext& /*ctx*/, double dt,
-                          double temp, double wind, const double* rainfall,
-                          const double* snowfall, double gamma, double ea) {
-    int n = soa_.n_subcatch;
-    if (n == 0) return;
-    int total = n * N_SUBAREAS;
-
-    // -----------------------------------------------------------------------
-    // Step 0 (Gap #19): 0.001-inch minimum pack threshold.
-    // Packs thinner than this are melted instantly (matching legacy).
-    // -----------------------------------------------------------------------
-    constexpr double MIN_PACK_FT = 0.001 / 12.0;
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        double ws = soa_.wsnow[ui];
-        if (ws > 0.0 && ws <= MIN_PACK_FT) {
-            soa_.imelt[ui]  += (ws + soa_.fw[ui]) / dt;
-            soa_.wsnow[ui]   = 0.0;
-            soa_.fw[ui]      = 0.0;
-            soa_.coldc[ui]   = 0.0;
-            soa_.asc[ui]     = 0.0;   // no coverage after instant melt
-        }
-    }
-
-    // -----------------------------------------------------------------------
-    // Step 1 (Gap #18): Compute areal snow coverage per subarea.
-    // Uses sba/sbws new-snow ADC tracking (matching legacy getArealDepletion).
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0) {
-            soa_.asc[ui] = 0.0;
-            continue;
-        }
-        int subarea = i % N_SUBAREAS;
-        soa_.asc[ui] = getArealDepletion(soa_, ui, subarea,
-                                         snowfall[i / N_SUBAREAS], dt);
-    }
-
-    // -----------------------------------------------------------------------
-    // Step 2: ATI update — only during sub-freezing conditions (temp < tbase).
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0) continue;
-        if (temp < soa_.tbase[ui]) {
-            double tipm_adj = 1.0 - std::pow(1.0 - soa_.tipm, dt / 21600.0);
-            soa_.ati[ui] += tipm_adj * (temp - soa_.ati[ui]);
-            soa_.ati[ui]  = std::min(soa_.ati[ui], soa_.tbase[ui]);
-        }
-    }
-
-    // -----------------------------------------------------------------------
-    // Step 3: Cold content accumulation during sub-freezing periods.
-    // Uses stored soa_.asc[ui] (already computed in Step 1).
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0) continue;
-        if (temp < soa_.tbase[ui]) {
-            double asc     = soa_.asc[ui];
-            double cc_incr = soa_.rnm * soa_.dhm[ui] *
-                             (soa_.ati[ui] - temp) * dt * asc;
-            soa_.coldc[ui] += std::max(0.0, cc_incr);
-            // Cap cold content (legacy: ccMax = wsnow * 0.007/12 * (tbase - ati))
-            double ccMax = soa_.wsnow[ui] * 0.007 / 12.0 *
-                           (soa_.tbase[ui] - soa_.ati[ui]);
-            if (ccMax > 0.0 && soa_.coldc[ui] > ccMax)
-                soa_.coldc[ui] = ccMax;
-        }
+namespace {
+
+// legacy updateColdContent (snow.c:801)
+inline void updateColdContent(SnowSoA& soa, std::size_t ui, double temp,
+                              double asc, double snowfall, double dt) {
+    double ati = soa.ati[ui];
+    double cc  = soa.coldc[ui];
+    // if snowing, ATI = snow (air) temperature
+    if (snowfall * 43200.0 > 0.02) ati = temp;
+    else {
+        // convert ATI weighting factor from 6-hr to tStep time basis
+        double tipm = 1.0 - std::pow(1.0 - soa.tipm, dt / (6.0 * 3600.0));
+        ati += tipm * (temp - ati);
     }
+    // ATI cannot exceed snow melt base temperature
+    ati = std::min(ati, soa.tbase[ui]);
+    // update cold content
+    cc += soa.rnm * soa.dhm[ui] * (ati - temp) * dt * asc;
+    cc = std::max(cc, 0.0);
+    // maximum cold content based on assumed specific heat of snow
+    double ccMax = soa.wsnow[ui] * 0.007 / 12.0 * (soa.tbase[ui] - ati);
+    cc = std::min(cc, ccMax);
+    soa.coldc[ui] = cc;
+    soa.ati[ui]   = ati;
+}
 
-    // -----------------------------------------------------------------------
-    // Step 4: Compute melt rate — degree-day or rain-on-snow, selected per
-    // subcatchment from that subcatchment's own rainfall (matching legacy
-    // meltSnowpack: rmelt > 0 wins, else degree-day).
-    // -----------------------------------------------------------------------
-    const double RAIN_THRESHOLD = 0.02 / ucf::Ucf[ucf::RAINFALL][0];
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        double rain_sc = rainfall[i / N_SUBAREAS];
-        if (rain_sc > RAIN_THRESHOLD) {
-            soa_.imelt[ui] = rainMeltRate(temp, wind, gamma, ea, rain_sc);
-        } else {
-            double excess = temp - soa_.tbase[ui];
-            soa_.imelt[ui] = (excess > 0.0) ? soa_.dhm[ui] * excess : 0.0;
-        }
+// legacy reduceColdContent (snow.c:854)
+inline double reduceColdContent(SnowSoA& soa, std::size_t ui, double smelt,
+                                double ccFactor) {
+    double cc = soa.coldc[ui];
+    if (smelt * ccFactor > cc) {
+        smelt -= cc / ccFactor;
+        cc = 0.0;
+    } else {
+        cc -= smelt * ccFactor;
+        smelt = 0.0;
     }
+    soa.coldc[ui] = cc;
+    return smelt;
+}
 
-    // Step 4b: Scale melt by areal coverage (using stored soa_.asc[ui]).
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0 || soa_.imelt[ui] <= 0.0) continue;
-        soa_.imelt[ui] *= soa_.asc[ui];
+// legacy meltSnowpack (snow.c:729)
+inline double meltSnowpack(SnowSoA& soa, std::size_t ui, double temp,
+                           double rmelt, double asc, double snowfall,
+                           double dt) {
+    double smelt;
+    if (rmelt > 0.0) smelt = rmelt;
+    else if (temp >= soa.tbase[ui])
+        smelt = soa.dhm[ui] * (temp - soa.tbase[ui]);
+    else {
+        updateColdContent(soa, ui, temp, asc, snowfall, dt);
+        return 0.0;
     }
+    // adjust snowmelt for area of snow cover
+    smelt *= asc;
+    // reduce cold content of melting pack
+    double ccFactor = dt * soa.rnm * asc;
+    smelt = reduceColdContent(soa, ui, smelt, ccFactor);
+    soa.ati[ui] = soa.tbase[ui];
+    return smelt;
+}
 
-    // -----------------------------------------------------------------------
-    // Step 5: Cold content absorption — melt only exits after cc is satisfied.
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0) {
-            soa_.imelt[ui] = 0.0;
-            continue;
-        }
-        double melt_vol = soa_.imelt[ui] * dt;
-        if (melt_vol <= soa_.coldc[ui]) {
-            soa_.coldc[ui] -= melt_vol;
-            soa_.imelt[ui]  = 0.0;
-        } else {
-            soa_.imelt[ui]  = (melt_vol - soa_.coldc[ui]) / dt;
-            soa_.coldc[ui]  = 0.0;
-        }
-        // Limit melt to available snow
-        soa_.imelt[ui] = std::min(soa_.imelt[ui], soa_.wsnow[ui] / dt);
-    }
+}  // namespace
 
-    // -----------------------------------------------------------------------
-    // Step 6: Free water routing — excess drains as output melt.
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        if (soa_.wsnow[ui] <= 0.0) continue;
+void SnowSolver::execute(SimulationContext& /*ctx*/, double dt,
+                          double temp, double wind, const double* rainfall,
+                          const double* snowfall, double gamma, double ea) {
+    int n = soa_.n_subcatch;
+    if (n == 0) return;
 
-        double fw_cap = soa_.fwfrac[ui] * soa_.wsnow[ui];
-        soa_.fw[ui]  += soa_.imelt[ui] * dt;
+    for (int j = 0; j < n; ++j) {
+        auto uj = static_cast(j);
+        const double rain = rainfall[uj];
+        const double snow = snowfall[uj];
+
+        // compute snowmelt over entire subcatchment when rain falling
+        const double rmelt = rainMeltRate(temp, wind, gamma, ea, rain);
+
+        for (int i = SNOW_PLOWABLE; i <= SNOW_PERV; ++i) {
+            auto ui = static_cast(j * N_SUBAREAS + i);
+            double asc, smelt;
+            // `imelt` holds the plowed melt from snow_plowSnow (legacy
+            // snowpack->imelt); the instant melt of a thin pack adds to it.
+            double imelt = soa_.imelt[ui];
+
+            // completely melt pack if its depth is < 0.001 inch
+            if (soa_.wsnow[ui] <= 0.001 / 12.0) {
+                asc   = 0.0;
+                smelt = 0.0;
+                imelt += (soa_.wsnow[ui] + soa_.fw[ui]) / dt;
+                // S2b — the water leaves at the age the pack HAD.
+                if (soa_.track_age) {
+                    soa_.out_age[ui] = soa_.age[ui];
+                    soa_.age[ui]     = 0.0;
+                }
+                soa_.wsnow[ui] = 0.0;
+                soa_.fw[ui]    = 0.0;
+                soa_.coldc[ui] = 0.0;
+            }
+            // otherwise compute areal depletion, find snow melt and route it
+            // through pack (legacy routeSnowmelt, snow.c:883)
+            else {
+                asc   = getArealDepletion(soa_, ui, i, snow, dt);
+                smelt = meltSnowpack(soa_, ui, temp, rmelt, asc, snow, dt);
+
+                double vmelt = smelt * dt;
+                vmelt = std::min(vmelt, soa_.wsnow[ui]);
+                soa_.wsnow[ui] -= vmelt;
+                const double rain_on_snow = rain * dt * asc;
+                // S2b — melt moves wsnow -> fw INSIDE the pool (no age
+                // change); the rain arrives from outside and mixes against
+                // the pool as it is when it lands.
+                if (soa_.track_age && rain_on_snow > 0.0) {
+                    soa_.age[ui] = mixAge(soa_.wsnow[ui] + soa_.fw[ui],
+                                          soa_.age[ui], rain_on_snow,
+                                          soa_.precip_age);
+                }
+                soa_.fw[ui] += vmelt + rain_on_snow;
+                vmelt = soa_.fw[ui] - soa_.fwfrac[ui] * soa_.wsnow[ui];
+                vmelt = std::max(vmelt, 0.0);
+                soa_.fw[ui] -= vmelt;
+                smelt = vmelt / dt;
+                // S2b — water draining out of a complete-mix pool leaves at
+                // the pool's age.
+                if (soa_.track_age) soa_.out_age[ui] = soa_.age[ui];
+            }
 
-        if (soa_.fw[ui] > fw_cap) {
-            double excess   = soa_.fw[ui] - fw_cap;
-            soa_.fw[ui]     = fw_cap;
-            soa_.imelt[ui]  = excess / dt;
-        } else {
-            soa_.imelt[ui]  = 0.0;
+            soa_.asc[ui]   = asc;
+            soa_.imelt[ui] = smelt + imelt;
+            if (soa_.track_age && !(soa_.imelt[ui] > 0.0)) soa_.out_age[ui] = 0.0;
         }
     }
-
-    // -----------------------------------------------------------------------
-    // Step 7: Update SWE.
-    // -----------------------------------------------------------------------
-    for (int i = 0; i < total; ++i) {
-        auto ui = static_cast(i);
-        soa_.wsnow[ui] -= soa_.imelt[ui] * dt;
-        soa_.wsnow[ui]  = std::max(soa_.wsnow[ui], 0.0);
-        soa_.fw[ui]     = std::min(soa_.fw[ui], soa_.wsnow[ui]);
-    }
 }
 
 // ============================================================================
@@ -325,8 +370,17 @@ void SnowSolver::execute(SimulationContext& /*ctx*/, double dt,
 void SnowSolver::setMeltCoeffs(int day_of_year) {
     // Compute seasonal factor: -1.0 at winter solstice (Dec 21, day ~355),
     // +1.0 at summer solstice (Jun 21, day ~172).
-    // season = sin(2*pi*(day - 81)/365)  where day 81 ~ Mar 22 = equinox
-    double season = std::sin(2.0 * 3.14159265358979 * (day_of_year - 81.0) / 365.0);
+    // season = sin(0.0172615 * (day - 81))   — legacy `climate.c:1176`.
+    //
+    // The constant is NOT a mis-divided year, and it was retracted from the
+    // divergence register once that was checked. It gives a period of
+    // exactly 364.000 days, and with the day-81 phase offset (the vernal
+    // equinox) the sine peaks at day 172.000 — the summer solstice, June 21.
+    // 364 = 4 x 91 is what makes the equinox-to-solstice quarter a whole
+    // number of days. Substituting 2*pi/365 moves the seasonal melt peak to
+    // day 172.25, off the solstice, and buys nothing.
+    constexpr double kSeasonRad = 0.0172615;   // rad/day; period 364.000 d
+    double season = std::sin(kSeasonRad * (day_of_year - 81.0));
     soa_.season = season;  // Store for reporting (matching legacy Snow.season)
 
     int total = soa_.n_subcatch * N_SUBAREAS;
@@ -362,20 +416,58 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
         for (int k = SNOW_PLOWABLE; k <= SNOW_PERV; ++k) {
             auto idx = static_cast(j * N_SUBAREAS + k);
             if (soa_.fArea[idx] > 0.0) {
-                soa_.wsnow[idx] += snowfall[uj] * dt;
+                const double add = snowfall[uj] * dt;
+                // S2b — age, THEN mix, and both before the store moves.
+                //
+                // This is the step's first snow call (SWMMEngine.cpp:1596
+                // calls plowSnow immediately before execute, matching legacy
+                // runoff.c:254), so it is where the pack ages. Ageing here
+                // rather than in `execute` means new snow is mixed in at its
+                // source age and is aged from the NEXT step, which is the
+                // A3/A4 convention: arriving water is not older than the
+                // instant it arrived.
+                if (soa_.track_age) {
+                    const double have = soa_.wsnow[idx] + soa_.fw[idx];
+                    if (have > 0.0) soa_.age[idx] += dt;
+                    if (add > 0.0)
+                        soa_.age[idx] = mixAge(have, soa_.age[idx],
+                                               add, soa_.precip_age);
+                }
+                soa_.wsnow[idx] += add;
                 soa_.imelt[idx] = 0.0;
             }
         }
+    }
+
+    // S2b — ageing is a SEPARATE PASS over every subcatchment, completed
+    // before any plowing starts. Interleaving the two ages water twice when
+    // it is plowed into a subcatchment the loop has not reached yet, and not
+    // at all when it goes to one already passed: the answer then depends on
+    // subcatchment ORDER, which nothing else in this model does. Measured on
+    // the two-subcatchment transfer gate: age-volume gained exactly
+    // `dt * moved`, 60 against a 40180 baseline.
+    for (int j = 0; j < n; ++j) {
+        auto uj = static_cast(j);
 
         // Check if plowable area has excess snow
         auto plow_idx = static_cast(j * N_SUBAREAS + SNOW_PLOWABLE);
         if (soa_.fArea[plow_idx] <= 0.0) continue;
-        if (soa_.weplow[uj] <= 0.0) continue;
+        // legacy snow.c:454: `if (wsnow >= weplow)` — an SDplow of 0 plows
+        // every step (there was a `weplow <= 0` skip here).
         if (soa_.wsnow[plow_idx] < soa_.weplow[uj]) continue;
 
         double exc = soa_.wsnow[plow_idx];
         auto sf = static_cast(j * 5); // sfrac base index
         double sfracTotal = 0.0;
+        // S2b — the donor's age, read ONCE before any transfer moves water.
+        //
+        // Every receiving surface below takes water from this same pool, so
+        // they must all mix against the age the pool had at the start of the
+        // transfer, not against a value that the previous transfer moved.
+        // Plowing does not touch `fw`, and removing water from a complete-mix
+        // pool at the pool's own age leaves that age unchanged — so the
+        // plowable surface's own age needs no update here at all.
+        const double donor_age = soa_.track_age ? soa_.age[plow_idx] : 0.0;
 
         // Plow out of system (sfrac[0])
         // Accumulate removed volume: depth (ft) * plowable area fraction * non-LID area (ft2)
@@ -383,7 +475,20 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
         if (soa_.sfrac[sf + 0] > 0.0) {
             double lid_ft2 = (uj < ctx.subcatches.total_lid_area_ft2.size())
                              ? ctx.subcatches.total_lid_area_ft2[uj] : 0.0;
-            double area_ft2 = ctx.subcatches.area[uj] * 43560.0 // acres → ft2
+            // F9 — this read `* 43560.0` with the comment "acres -> ft2".
+            // `subcatches.area` is in PROJECT land-area units, which are
+            // acres only in US; in SI they are hectares, and the plough
+            // volume came out **2.471x too small** — the identical defect
+            // SWMMEngine.cpp's rainfall-volume site carries a comment about
+            // having already fixed once.
+            //
+            // Fixed HERE, in the ledger round rather than its own, and the
+            // reason is specific: `runoff_snowremov` had no writer until this
+            // round, so this number reached nobody. Wiring it up is what
+            // makes the error visible, and shipping a newly-visible wrong
+            // number is worse than shipping no number at all.
+            double area_ft2 = ctx.subcatches.area[uj] /
+                                  ucf::UCF(ucf::LANDAREA, ctx.options)
                               - lid_ft2;
             if (area_ft2 < 0.0) area_ft2 = 0.0;
             soa_.removed += soa_.sfrac[sf + 0] * exc *
@@ -395,7 +500,13 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
         auto imperv_idx = static_cast(j * N_SUBAREAS + SNOW_IMPERV);
         if (soa_.fArea[imperv_idx] > 0.0) {
             double f = soa_.fArea[plow_idx] / soa_.fArea[imperv_idx];
-            soa_.wsnow[imperv_idx] += soa_.sfrac[sf + 1] * exc * f;
+            const double moved = soa_.sfrac[sf + 1] * exc * f;
+            if (soa_.track_age && moved > 0.0) {
+                soa_.age[imperv_idx] =
+                    mixAge(soa_.wsnow[imperv_idx] + soa_.fw[imperv_idx],
+                           soa_.age[imperv_idx], moved, donor_age);
+            }
+            soa_.wsnow[imperv_idx] += moved;
             sfracTotal += soa_.sfrac[sf + 1];
         }
 
@@ -403,13 +514,26 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
         auto perv_idx = static_cast(j * N_SUBAREAS + SNOW_PERV);
         if (soa_.fArea[perv_idx] > 0.0) {
             double f = soa_.fArea[plow_idx] / soa_.fArea[perv_idx];
-            soa_.wsnow[perv_idx] += soa_.sfrac[sf + 2] * exc * f;
+            const double moved = soa_.sfrac[sf + 2] * exc * f;
+            if (soa_.track_age && moved > 0.0) {
+                soa_.age[perv_idx] =
+                    mixAge(soa_.wsnow[perv_idx] + soa_.fw[perv_idx],
+                           soa_.age[perv_idx], moved, donor_age);
+            }
+            soa_.wsnow[perv_idx] += moved;
             sfracTotal += soa_.sfrac[sf + 2];
         }
 
         // Convert to immediate melt (sfrac[3])
         if (dt > 0.0) {
             soa_.imelt[plow_idx] = soa_.sfrac[sf + 3] * exc / dt;
+            // S2b — plough-melt leaves the pack at the pack's age. `execute`
+            // runs next and will overwrite both `imelt` and `out_age` for
+            // this surface (step 4 assigns `imelt`), so this write is not
+            // what a caller reads; it is here so that the pair is never
+            // inconsistent at any point in the step, which is the invariant
+            // that makes the pair safe to read from anywhere later.
+            if (soa_.track_age) soa_.out_age[plow_idx] = donor_age;
         }
         sfracTotal += soa_.sfrac[sf + 3];
 
@@ -420,7 +544,17 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
                 auto target_perv = static_cast(m * N_SUBAREAS + SNOW_PERV);
                 if (soa_.fArea[target_perv] > 0.0) {
                     double f = soa_.fArea[plow_idx] / soa_.fArea[target_perv];
-                    soa_.wsnow[target_perv] += soa_.sfrac[sf + 4] * exc * f;
+                    const double moved = soa_.sfrac[sf + 4] * exc * f;
+                    // S2b — the CROSS-SUBCATCHMENT transfer, and the reason
+                    // the age has to live in this solver. An update running
+                    // after `execute` sees only that subcatchment `m` gained
+                    // snow; it cannot know it came from `j`, nor at what age.
+                    if (soa_.track_age && moved > 0.0) {
+                        soa_.age[target_perv] =
+                            mixAge(soa_.wsnow[target_perv] + soa_.fw[target_perv],
+                                   soa_.age[target_perv], moved, donor_age);
+                    }
+                    soa_.wsnow[target_perv] += moved;
                     sfracTotal += soa_.sfrac[sf + 4];
                 }
             }
@@ -429,6 +563,13 @@ void SnowSolver::plowSnow(SimulationContext& ctx, double dt, const double* snowf
         // Reduce plowable snow by total fraction plowed
         sfracTotal = std::min(sfracTotal, 1.0);
         soa_.wsnow[plow_idx] = exc * (1.0 - sfracTotal);
+        // S2b — a surface plowed clean has no water, so it has no age.
+        // Leaving the old value would let it survive as the mixing partner
+        // for the next snowfall, which would make new snow arrive old.
+        if (soa_.track_age &&
+            !(soa_.wsnow[plow_idx] + soa_.fw[plow_idx] > 0.0)) {
+            soa_.age[plow_idx] = 0.0;
+        }
     }
 }
 
diff --git a/src/engine/hydrology/Snow.hpp b/src/engine/hydrology/Snow.hpp
index 542256adb..bbff48b1b 100644
--- a/src/engine/hydrology/Snow.hpp
+++ b/src/engine/hydrology/Snow.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Snow.hpp
  * @brief Snowmelt — degree-day and rain-on-snow methods.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_SNOW_HPP
@@ -66,6 +82,32 @@ struct SnowSoA {
     // Per subcatchment × 3 subareas: area fractions
     std::vector fArea;    ///< Fraction of total area for each subarea
 
+    /// S2b — WATER AGE of the pack's water (seconds), per subcatchment ×
+    /// subarea. **Complete-mix over `wsnow + fw` TOGETHER.**
+    ///
+    /// Two stores would be more faithful — snow and free water have
+    /// genuinely different residence times — but the melt path moves water
+    /// between them within a single step anyway, and one age is the minimum
+    /// that carries residence time at all. Recorded as a deliberate
+    /// approximation in SNOW_DIVERGENCE_REGISTER.md rather than left
+    /// unnamed, which is what lesson 64 is actually about.
+    ///
+    /// Maintained inside this solver on purpose. Plowing moves water between
+    /// surfaces AND to another subcatchment inside `plowSnow`; an age update
+    /// running afterwards can see only the end state and would have to guess
+    /// which water went where. The age therefore moves at the point the
+    /// water moves, which is the only place that knows.
+    std::vector age;
+    /// S2b — age of the water this step PUBLISHED as `imelt` (seconds).
+    ///
+    /// Not the same as `age`, and the difference is the whole reason this
+    /// array exists: in a complete-mix pool the water leaving carries the
+    /// pool's age, but a pack that EMPTIES this step leaves `age` at 0 with
+    /// no water to describe. Meltwater from such a pack still carries the
+    /// age the pack had. Sentinel-free — it is only meaningful where
+    /// `imelt > 0`, and callers gate on that.
+    std::vector out_age;
+
     // Per subcatchment × 3 subareas: areal depletion state
     std::vector si;       ///< Snow depth for 100% cover (ft)
     std::vector sba;      ///< Snow coverage area at start of new-snow ADC
@@ -92,6 +134,21 @@ struct SnowSoA {
     double season  = 0.0;         ///< Current snowmelt season factor (-1 to +1)
     double removed = 0.0;         ///< Cumulative snow plowed out of system (ft3)
 
+    /// S2b — age of water arriving from the sky (seconds). Set by the engine
+    /// each runoff step from the water-age component's `RAINFALL` source.
+    ///
+    /// A scalar set from outside rather than a lookup into the transport
+    /// config, so hydrology keeps no dependency on the transport layer —
+    /// the same shape as `season`, `tipm` and `rnm`.
+    double precip_age = 0.0;
+    /// S2b — whether to maintain `age` / `out_age` at all.
+    ///
+    /// The age arrays are pure bookkeeping: nothing in the water balance
+    /// reads them, so a deck is byte-identical either way. The flag exists
+    /// to keep the arithmetic off the hot path when WATER_AGE is off, not to
+    /// protect an answer.
+    bool track_age = false;
+
     void resize(int n);
 };
 
diff --git a/src/engine/input/InputParseUtils.hpp b/src/engine/input/InputParseUtils.hpp
index 6f1348ac6..4dc8cd225 100644
--- a/src/engine/input/InputParseUtils.hpp
+++ b/src/engine/input/InputParseUtils.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InputParseUtils.hpp
  * @brief Shared parsing utilities for input section handlers.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INPUT_PARSE_UTILS_HPP
@@ -55,7 +71,21 @@ inline int to_int(std::string_view sv, int def = 0) noexcept {
 // ============================================================================
 
 /**
- * @brief Parse a date string in MM/DD/YYYY format to a DateTime (decimal days).
+ * @brief Parse a date string in MM/DD/YYYY or MM-DD-YYYY form to a DateTime
+ *        (decimal days).
+ *
+ * @details legacy datetime_strToDate accepts EITHER separator — it opens with
+ *          `if (strchr(s,'-') || strchr(s,'/'))` and then reads
+ *          `%d%c%d%c%d`, so `1-1-2000` and `01/01/2000` are the same date to
+ *          it (datetime.c). This parser took '/' only and returned 0.0 for
+ *          anything else, which is not a parse failure the caller can see: a
+ *          deck writing `START_DATE 1-1-2000` got a start and an end of zero,
+ *          a zero-length simulation, and an .out file with no periods at all
+ *          while the run reported success. 1900-nodes is the corpus case —
+ *          legacy writes 240 periods and 20 MB, v6 wrote 0 and 95 KB.
+ *
+ *          Single-digit months and days come for free, since from_chars reads
+ *          a run of digits rather than a fixed width.
  */
 inline double parse_date(std::string_view sv) {
     unsigned m = 0, d = 0, y = 0;
@@ -68,11 +98,15 @@ inline double parse_date(std::string_view sv) {
         p = np;
         return true;
     };
+    auto read_sep = [&]() -> bool {
+        if (p < end && (*p == '/' || *p == '-')) { ++p; return true; }
+        return false;
+    };
 
     if (!read_uint(m)) return 0.0;
-    if (p < end && *p == '/') ++p; else return 0.0;
+    if (!read_sep()) return 0.0;
     if (!read_uint(d)) return 0.0;
-    if (p < end && *p == '/') ++p; else return 0.0;
+    if (!read_sep()) return 0.0;
     if (!read_uint(y)) return 0.0;
 
     return datetime::encodeDate(static_cast(y),
@@ -127,10 +161,23 @@ inline double parse_time_seconds(std::string_view sv) {
  * @details For use with datetime::encodeTime. Returns fractional day [0, 1).
  */
 inline double parse_time_day_fraction(std::string_view sv) {
-    unsigned h = 0, m = 0, s = 0;
     const char* p = sv.data();
     const char* end = sv.data() + sv.size();
 
+    // A time token is EITHER decimal hours (a bare number such as "0.167" or
+    // "10") OR a clock string "HH:MM[:SS]" — matching legacy datetime_strToTime
+    // ("accepts time as hr:min:sec or as decimal hours"). Try a full decimal
+    // parse first: if the WHOLE token is a number it is decimal hours (/24);
+    // otherwise fall back to integer HH:MM:SS. This helper (and parse_datetime
+    // through it) previously handled only HH:MM:SS, so a bare "0.167" on a dated
+    // [TIMESERIES] row was truncated to 0 — corrupting the series and colliding
+    // with the prior day's "24" row (dx == 0 -> spurious ERR 173).
+    double dec_hours = 0.0;
+    auto [dp, dec] = openswmm::from_chars_double(p, end, dec_hours);
+    if (dec == std::errc{} && dp == end)
+        return dec_hours / 24.0;
+
+    unsigned h = 0, m = 0, s = 0;
     auto read_uint = [&](unsigned& out) -> bool {
         auto [np, ec] = std::from_chars(p, end, out);
         if (ec != std::errc{}) return false;
diff --git a/src/engine/input/InputReader.cpp b/src/engine/input/InputReader.cpp
index 3033faa85..5b1914de7 100644
--- a/src/engine/input/InputReader.cpp
+++ b/src/engine/input/InputReader.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InputReader.cpp
  * @brief Implementation of the top-level SWMM .inp file reader.
@@ -7,12 +23,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "InputReader.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "Tokenizer.hpp"
 #include "../core/ErrorCodes.hpp"
+#include "../core/PerfTimers.hpp"
 
 #include 
 #include 
@@ -36,7 +54,7 @@ InputReader::InputReader(SectionRegistry& registry)
 // ============================================================================
 
 bool InputReader::read(const std::string& path, SimulationContext& ctx) {
-    std::ifstream ifs(path);
+    std::ifstream ifs(openswmm::io::utf8_path(path));
     if (!ifs.is_open()) {
         ctx.error_code    = 2;  // public SWMM_ERR_INPFILE (was 1 = NOMEM)
         ctx.error_message = "InputReader: cannot open file '" + path + "'";
@@ -60,6 +78,7 @@ bool InputReader::read_stream(std::istream& stream, SimulationContext& ctx) {
 
     auto flush_section = [&]() {
         if (!current_tag.empty()) {
+            perf::ScopedTimer _pt(perf::sec_read_dispatch);
             dispatch_section(current_tag, section_lines, ctx);
             section_lines.clear();
         }
diff --git a/src/engine/input/InputReader.hpp b/src/engine/input/InputReader.hpp
index 16efd69b9..3b9d3106c 100644
--- a/src/engine/input/InputReader.hpp
+++ b/src/engine/input/InputReader.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InputReader.hpp
  * @brief Top-level SWMM .inp file reader.
@@ -33,7 +49,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INPUT_READER_HPP
diff --git a/src/engine/input/MultiColumnSeriesFile.cpp b/src/engine/input/MultiColumnSeriesFile.cpp
new file mode 100644
index 000000000..dc83859da
--- /dev/null
+++ b/src/engine/input/MultiColumnSeriesFile.cpp
@@ -0,0 +1,391 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MultiColumnSeriesFile.cpp
+ * @brief Parse-once cache for multi-column series files (CSV/TSV/TSF).
+ * @see MultiColumnSeriesFile.hpp
+ * @ingroup engine_input
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "MultiColumnSeriesFile.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "../core/DateTime.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::input {
+
+namespace {
+
+std::atomic g_parse_count_total{0};
+
+/// Trim ASCII whitespace and surrounding double quotes.
+/// (Relocated from PostParseResolver.cpp csv_trim.)
+std::string cell_trim(const std::string& s) {
+    std::size_t a = 0, b = s.size();
+    auto space = [](char c) {
+        return c == ' ' || c == '\t' || c == '\r' || c == '\n';
+    };
+    while (a < b && space(s[a])) ++a;
+    while (b > a && space(s[b - 1])) --b;
+    if (b - a >= 2 && s[a] == '"' && s[b - 1] == '"') { ++a; --b; }
+    return s.substr(a, b - a);
+}
+
+/// Quote-aware split on a single-character delimiter.
+/// (Generalises PostParseResolver.cpp csv_split to comma or tab.)
+std::vector cell_split(const std::string& line, char delim) {
+    std::vector out;
+    std::string cur;
+    bool in_quotes = false;
+    for (const char c : line) {
+        if (c == '"') { in_quotes = !in_quotes; cur.push_back(c); }
+        else if (c == delim && !in_quotes) { out.push_back(cell_trim(cur)); cur.clear(); }
+        else cur.push_back(c);
+    }
+    out.push_back(cell_trim(cur));
+    return out;
+}
+
+/// Count delimiters OUTSIDE double quotes — the delimiter sniff has to use
+/// the same notion of a delimiter as cell_split above, or a quoted header
+/// name containing the other delimiter (`Date"a,b,c"`) sniffs wrong and
+/// the whole file mis-splits.
+long count_unquoted(const std::string& line, char delim) {
+    long n = 0;
+    bool in_quotes = false;
+    for (const char c : line) {
+        if (c == '"') in_quotes = !in_quotes;
+        else if (c == delim && !in_quotes) ++n;
+    }
+    return n;
+}
+
+/// Case-insensitive equality (relocated from PostParseResolver.cpp csv_iequals).
+bool iequals(std::string_view a, std::string_view b) {
+    if (a.size() != b.size()) return false;
+    for (std::size_t i = 0; i < a.size(); ++i)
+        if (std::tolower(static_cast(a[i]))
+            != std::tolower(static_cast(b[i]))) return false;
+    return true;
+}
+
+/// 0 = none, 1 = AM, 2 = PM — detected from the cell's trailing token.
+int trailing_meridiem(const std::string& cell) {
+    std::size_t e = cell.find_last_not_of(" \t\r\n");
+    if (e == std::string::npos || e < 1) return 0;
+    const char m1 = static_cast(std::toupper(static_cast(cell[e])));
+    const char m0 = static_cast(std::toupper(static_cast(cell[e - 1])));
+    if (m1 != 'M' || (m0 != 'A' && m0 != 'P')) return 0;
+    return m0 == 'A' ? 1 : 2;
+}
+
+/// Strip a UTF-8 BOM and a trailing '\r' (files written on Windows).
+void normalize_line(std::string& line, bool first_line) {
+    if (first_line && line.size() >= 3 &&
+        static_cast(line[0]) == 0xEF &&
+        static_cast(line[1]) == 0xBB &&
+        static_cast(line[2]) == 0xBF)
+        line.erase(0, 3);
+    if (!line.empty() && line.back() == '\r') line.pop_back();
+}
+
+bool is_blank_or_comment(const std::string& line) {
+    for (const char c : line) {
+        if (c == ' ' || c == '\t') continue;
+        return c == ';' || c == '#';
+    }
+    return true;  // all-whitespace / empty
+}
+
+bool istarts_with(const std::string& line, std::string_view prefix) {
+    if (line.size() < prefix.size()) return false;
+    return iequals(std::string_view(line).substr(0, prefix.size()), prefix);
+}
+
+} // namespace
+
+// ---------------------------------------------------------------------------
+// ParsedSeriesFile
+// ---------------------------------------------------------------------------
+
+int ParsedSeriesFile::find_column(std::string_view name) const {
+    // Column 0 is the time stamp, so a match there is as wrong as no match.
+    for (std::size_t i = 1; i < headers.size(); ++i)
+        if (iequals(headers[i], name)) return static_cast(i);
+    return -1;
+}
+
+// ---------------------------------------------------------------------------
+// Datetime parsing (relocated csv_parse_datetime + 12-hour AM/PM)
+// ---------------------------------------------------------------------------
+
+bool parse_series_datetime(const std::string& cell, double& out) {
+    int y = 0, mo = 0, d = 0, h = 0, mi = 0, s = 0;
+    const char* c = cell.c_str();
+
+    // ISO-8601: YYYY-MM-DD[ T]HH:MM[:SS]
+    int n = std::sscanf(c, "%d-%d-%d%*[ T]%d:%d:%d", &y, &mo, &d, &h, &mi, &s);
+    if (n >= 3) {
+        if (n < 4) { h = mi = s = 0; }
+        else if (n < 6) { s = 0; }
+        out = datetime::encodeDate(y, mo, d) + datetime::encodeTime(h, mi, s);
+        return true;
+    }
+
+    // US: MM/DD/YYYY[ HH:MM[:SS]], optionally 12-hour with a trailing AM/PM
+    // token (the PCSWMM TSF form). The `n < 5` guard here used to drop a
+    // parsed hour when the minutes were absent — fixed to mirror the ISO
+    // branch above (plan §3.1).
+    n = std::sscanf(c, "%d/%d/%d %d:%d:%d", &mo, &d, &y, &h, &mi, &s);
+    if (n >= 3) {
+        if (n < 4) { h = mi = s = 0; }
+        else if (n < 6) { s = 0; }
+        if (n >= 4) {
+            const int meridiem = trailing_meridiem(cell);
+            if (meridiem != 0) {
+                if (h == 12) h = 0;          // 12:xx AM → 00:xx, 12:xx PM → 12:xx
+                if (meridiem == 2) h += 12;  // PM
+            }
+        }
+        out = datetime::encodeDate(y, mo, d) + datetime::encodeTime(h, mi, s);
+        return true;
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Sniff
+// ---------------------------------------------------------------------------
+
+bool looks_like_multicolumn_series_file(const std::string& abs_path) {
+    std::ifstream in(openswmm::io::utf8_path(abs_path));
+    if (!in.is_open()) return false;
+
+    std::string line;
+    bool first = true;
+    while (std::getline(in, line)) {
+        normalize_line(line, first);
+        first = false;
+        if (is_blank_or_comment(line)) continue;
+
+        if (istarts_with(line, "IDs:")) return true;      // PCSWMM TSF
+        if (line.find(',') != std::string::npos) return true;  // comma CSV
+        if (line.find('\t') != std::string::npos) {
+            // Tab-delimited: a legacy .dat data row starts with a date; a
+            // TSV header row does not.
+            const auto cells = cell_split(line, '\t');
+            double dt = 0.0;
+            return !cells.empty() && !parse_series_datetime(cells[0], dt);
+        }
+        return false;
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// `path:column` token split (one rule for gages AND timeseries)
+// ---------------------------------------------------------------------------
+
+bool split_series_file_token(std::string_view token,
+                             std::string& path_out,
+                             std::string& column_out) {
+    path_out.assign(token);
+    column_out.clear();
+
+    const auto colon = token.rfind(':');
+    if (colon == std::string_view::npos) return false;
+
+    // Windows drive letter ("C:\dir\f.csv"): not a column separator.
+    if (colon == 1 && std::isalpha(static_cast(token[0])))
+        return false;
+
+    // A colon inside a directory name ("/data/Rich:2024/f.csv"): the text
+    // after it is still path, not a column name.
+    const auto suffix = token.substr(colon + 1);
+    if (suffix.find('/') != std::string_view::npos ||
+        suffix.find('\\') != std::string_view::npos)
+        return false;
+
+    path_out.assign(token.substr(0, colon));
+    column_out.assign(suffix);
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+bool parse_multicolumn_series_file(const std::string& abs_path,
+                                   ParsedSeriesFile& out,
+                                   std::vector& errors,
+                                   SeriesFileStatus* status) {
+    auto fail = [&](SeriesFileStatus st, const std::string& msg) {
+        if (status) *status = st;
+        errors.push_back(msg);
+        return false;
+    };
+
+    out = ParsedSeriesFile{};
+    g_parse_count_total.fetch_add(1, std::memory_order_relaxed);
+
+    std::ifstream in(openswmm::io::utf8_path(abs_path));
+    if (!in.is_open())
+        return fail(SeriesFileStatus::OPEN_FAILED,
+                    "cannot open series file " + abs_path);
+
+    // --- Header ---------------------------------------------------------
+    std::string line;
+    bool first = true;
+    bool have_header = false;
+    while (std::getline(in, line)) {
+        normalize_line(line, first);
+        first = false;
+        if (is_blank_or_comment(line)) continue;
+        have_header = true;
+        break;
+    }
+    if (!have_header)
+        return fail(SeriesFileStatus::FORMAT_FAILED,
+                    "no header row in series file " + abs_path);
+
+    char delim = ',';
+    if (istarts_with(line, "IDs:")) {
+        // PCSWMM TSF: tab-delimited; line 1 tokens 1..N name the columns,
+        // line 2 (parameter row, e.g. "Date/Time  Rainfall …") and line 3
+        // (units row, e.g. "  in.  in.") carry no data — skip both.
+        delim = '\t';
+        out.headers = cell_split(line, delim);
+        std::string skip;
+        for (int i = 0; i < 2 && std::getline(in, skip); ++i) {}
+    } else {
+        // CSV/TSV: sniff the delimiter from the header row, counting only
+        // delimiters outside quotes (see count_unquoted).
+        const long tabs   = count_unquoted(line, '\t');
+        const long commas = count_unquoted(line, ',');
+        delim = (tabs > 0 && tabs >= commas) ? '\t' : ',';
+        out.headers = cell_split(line, delim);
+    }
+
+    const std::size_t ncols = out.headers.size();
+    if (ncols < 2)
+        return fail(SeriesFileStatus::FORMAT_FAILED,
+                    "no data columns in series file " + abs_path);
+
+    out.columns.assign(ncols, {});
+    out.col_first_date.assign(ncols, 0.0);
+    out.col_last_date.assign(ncols, 0.0);
+    out.col_periods_precip.assign(ncols, 0L);
+    out.col_unparsed_cells.assign(ncols, 0L);
+
+    // --- Data rows ------------------------------------------------------
+    constexpr double kNaN = std::numeric_limits::quiet_NaN();
+    while (std::getline(in, line)) {
+        normalize_line(line, false);
+        if (is_blank_or_comment(line)) continue;
+
+        const std::vector cells = cell_split(line, delim);
+        double dt = 0.0;
+        if (cells.empty() || !parse_series_datetime(cells[0], dt)) {
+            ++out.unparsed_rows;
+            continue;
+        }
+
+        out.dates.push_back(dt);
+        if (out.first_date == 0.0 || dt < out.first_date) out.first_date = dt;
+        if (dt > out.last_date) out.last_date = dt;
+
+        for (std::size_t i = 1; i < ncols; ++i) {
+            double v = kNaN;
+            if (i < cells.size()) {
+                const std::string& cell = cells[i];
+                char* endp = nullptr;
+                const double parsed = std::strtod(cell.c_str(), &endp);
+                if (endp != cell.c_str()) {
+                    v = parsed;
+                    if (out.col_first_date[i] == 0.0 || dt < out.col_first_date[i])
+                        out.col_first_date[i] = dt;
+                    if (dt > out.col_last_date[i]) out.col_last_date[i] = dt;
+                    if (v > 0.0) ++out.col_periods_precip[i];
+                } else {
+                    // Includes present-but-empty cells: the per-gage scan
+                    // this replaces counted them as unreadable (strtod
+                    // failure) and they feed the same skipped-rows warning.
+                    ++out.col_unparsed_cells[i];
+                }
+            }
+            // A short row (cell absent for this column) stays NaN without
+            // counting — the per-gage scan silently skipped those too.
+            out.columns[i].push_back(v);
+        }
+    }
+
+    // --- Sort rows ascending (records may be interleaved/out of order) --
+    if (!std::is_sorted(out.dates.begin(), out.dates.end())) {
+        std::vector order(out.dates.size());
+        std::iota(order.begin(), order.end(), std::size_t{0});
+        std::sort(order.begin(), order.end(),
+                  [&](std::size_t a, std::size_t b){ return out.dates[a] < out.dates[b]; });
+        auto permute = [&](std::vector& v) {
+            std::vector tmp(v.size());
+            for (std::size_t i = 0; i < order.size(); ++i) tmp[i] = v[order[i]];
+            v.swap(tmp);
+        };
+        permute(out.dates);
+        for (std::size_t i = 1; i < ncols; ++i) permute(out.columns[i]);
+    }
+
+    if (status) *status = SeriesFileStatus::OK;
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+
+const ParsedSeriesFile* MultiColumnFileCache::get_or_parse(
+        const std::string& abs_path,
+        std::vector& errors,
+        SeriesFileStatus* status) {
+    auto it = files_.find(abs_path);
+    if (it == files_.end()) {
+        Entry entry;
+        parse_multicolumn_series_file(abs_path, entry.file, errors, &entry.status);
+        ++parse_count_;
+        it = files_.emplace(abs_path, std::move(entry)).first;
+    }
+    if (status) *status = it->second.status;
+    return it->second.status == SeriesFileStatus::OK ? &it->second.file : nullptr;
+}
+
+long multicolumn_parse_count_total() noexcept {
+    return g_parse_count_total.load(std::memory_order_relaxed);
+}
+
+} /* namespace openswmm::input */
diff --git a/src/engine/input/MultiColumnSeriesFile.hpp b/src/engine/input/MultiColumnSeriesFile.hpp
new file mode 100644
index 000000000..6257659b7
--- /dev/null
+++ b/src/engine/input/MultiColumnSeriesFile.hpp
@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MultiColumnSeriesFile.hpp
+ * @brief Parse-once cache for multi-column external series files
+ *        (CSV / TSV / PCSWMM TSF).
+ *
+ * @details Implements the eager parse-once design of
+ *          `plans/MULTICOLUMN_SERIES_SINGLE_READ_2026-08-17.md` (§3.1):
+ *          each external file referenced by any number of rain gages and/or
+ *          FILE-backed [TIMESERIES] tables is read from disk exactly once
+ *          per resolve pass; consumers copy their selected column out of the
+ *          shared `ParsedSeriesFile` and the cache is freed at end of pass.
+ *
+ *          Values are stored RAW (file units, no rain-type or unit
+ *          conversion) — each consumer applies its own transform on
+ *          copy-out, exactly as it did when it read the file itself.
+ *
+ *          Format auto-detection:
+ *          - First content line starting with `IDs:` → PCSWMM TSF
+ *            (tab-delimited; line 1 tokens 1..N are the column names, the
+ *            next two lines — parameter and units rows — are skipped;
+ *            datetimes are 12-hour `MM/DD/YYYY hh:mm:ss AM/PM`).
+ *          - Otherwise CSV/TSV: delimiter sniffed from the header row
+ *            (tab when tabs dominate, else comma); row 1 = headers,
+ *            column 0 = time.
+ *
+ *          Lines are read with std::getline, so there is no fixed line-width
+ *          limit (replaces the 4096-byte fgets buffers that silently split
+ *          wide rows — plan gap P2).
+ *
+ * @see src/engine/input/PostParseResolver.cpp — the two consumers
+ * @ingroup engine_input
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_MULTI_COLUMN_SERIES_FILE_HPP
+#define OPENSWMM_ENGINE_MULTI_COLUMN_SERIES_FILE_HPP
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm::input {
+
+/**
+ * @brief One fully parsed multi-column series file (raw file-unit values).
+ *
+ * @details Rows are sorted ascending by datetime. A cell that was missing
+ *          (short row) or unparseable holds a quiet NaN in its column so all
+ *          columns stay aligned to `dates`; consumers skip NaNs on copy-out.
+ */
+struct ParsedSeriesFile {
+    /// Header names; index 0 is the time-column label and never matches.
+    std::vector          headers;
+
+    /// Row datetimes (SWMM OADate, whole file, ascending).
+    std::vector               dates;
+
+    /// columns[i] (i >= 1) aligned to `dates`; columns[0] is unused/empty.
+    std::vector>  columns;
+
+    /// Whole-file first/last datetime (0 when the file has no data rows).
+    double first_date = 0.0, last_date = 0.0;
+
+    // Per-column statistics over the WHOLE file (index-aligned with
+    // `headers`; entry 0 unused). These preserve the "Rainfall File
+    // Summary" values a per-gage scan used to produce.
+    std::vector               col_first_date;
+    std::vector               col_last_date;
+    std::vector                 col_periods_precip;  ///< cells with value > 0
+    std::vector                 col_unparsed_cells;  ///< value-parse failures
+
+    /// Data rows whose datetime cell failed to parse (skipped entirely).
+    long                              unparsed_rows = 0;
+
+    /**
+     * @brief Case-insensitive column lookup by header name.
+     * @returns Column index >= 1, or -1 when not found (a match on the time
+     *          column 0 is as wrong as no match and also returns -1).
+     */
+    int find_column(std::string_view name) const;
+
+    /// First data column (1) when one exists, else -1.
+    int first_data_column() const {
+        return headers.size() > 1 ? 1 : -1;
+    }
+};
+
+/// Why a parse failed (or that it did not).
+enum class SeriesFileStatus {
+    OK,            ///< parsed (possibly zero data rows)
+    OPEN_FAILED,   ///< file could not be opened
+    FORMAT_FAILED  ///< no header / no data columns
+};
+
+/**
+ * @brief Parse a full datetime cell.
+ *
+ * @details Accepts ISO-8601 `YYYY-MM-DD[ T]HH:MM[:SS]`, 24-hour US
+ *          `MM/DD/YYYY[ HH:MM[:SS]]`, and 12-hour US with a trailing
+ *          AM/PM token (`MM/DD/YYYY hh:mm[:ss] AM` — the TSF form).
+ *          Relocated from PostParseResolver.cpp (csv_parse_datetime) per
+ *          the 2026-08-17 plan; the `n<5` hour-dropping asymmetry of the
+ *          US branch is fixed to mirror the ISO branch.
+ *
+ * @param cell  Text of the cell (already trimmed).
+ * @param out   Receives the encoded SWMM OADate on success.
+ * @returns true when the cell parsed as a datetime.
+ */
+bool parse_series_datetime(const std::string& cell, double& out);
+
+/**
+ * @brief Parse a multi-column series file (format auto-detected).
+ *
+ * @param abs_path  Resolved path to open.
+ * @param out       Receives the parsed file on success.
+ * @param errors    Receives one human-readable string per file-level
+ *                  problem (cannot open, no header, no data columns).
+ * @param status    Optional; receives why parsing failed (or OK).
+ * @returns true on success (a well-formed file with zero data rows still
+ *          succeeds — consumers decide whether emptiness is an error).
+ */
+bool parse_multicolumn_series_file(const std::string& abs_path,
+                                   ParsedSeriesFile& out,
+                                   std::vector& errors,
+                                   SeriesFileStatus* status = nullptr);
+
+/**
+ * @brief Cheap content sniff: does this file look multi-column?
+ *
+ * @details Reads only up to the first content line. True when it starts
+ *          with `IDs:` (TSF), contains a comma (legacy .dat is whitespace
+ *          delimited), or is tab-delimited with a non-datetime first cell
+ *          (a TSV header row). Used by the timeseries loader to route a
+ *          FILE reference without a `:column` suffix.
+ */
+bool looks_like_multicolumn_series_file(const std::string& abs_path);
+
+/**
+ * @brief Split a `path[:column]` FILE token into its path and column parts.
+ *
+ * @details ONE rule, shared by every consumer of the convention — the rain
+ *          gage reader (`handlers/CatchmentHandler.cpp`) and the timeseries
+ *          loader (`PostParseResolver.cpp`). They used to differ (first
+ *          colon vs. last colon), which derived two different cache keys for
+ *          the same file and silently defeated the single-read guarantee
+ *          whenever a path contained a colon.
+ *
+ *          The rule: take the LAST colon in the token, then reject it as a
+ *          column separator when either
+ *          - it is the Windows drive-letter colon (index 1, preceded by a
+ *            letter), or
+ *          - the text after it contains a path separator ('/' or '\\'), i.e.
+ *            the colon belongs to a directory name (legal on POSIX/macOS,
+ *            e.g. `/data/Rich:2024/rain.csv`).
+ *
+ * @param token       The verbatim FILE token.
+ * @param path_out    Receives the path (the whole token when there is no
+ *                    column).
+ * @param column_out  Receives the column name (empty when there is none, and
+ *                    also when the token ends in a bare `:`).
+ * @returns true when a column separator was found. An empty @p column_out
+ *          with a true return is the `"path:"` form, which selects the first
+ *          data column but still identifies the file as multi-column.
+ */
+bool split_series_file_token(std::string_view token,
+                             std::string& path_out,
+                             std::string& column_out);
+
+/**
+ * @brief Per-resolve-pass cache keyed by resolved path.
+ *
+ * @details One instance is shared by the rain-gage and timeseries loaders
+ *          so a file referenced by both parses once (plan §5 single-read
+ *          guarantee). Failures are cached too, so N consumers of a broken
+ *          file trigger one open attempt.
+ */
+class MultiColumnFileCache {
+public:
+    /**
+     * @brief Return the parsed file, parsing it on first request.
+     * @param abs_path  Resolved path (the cache key).
+     * @param errors    Receives file-level parse errors (first parse only).
+     * @param status    Optional; receives the entry's status.
+     * @returns Pointer into the cache (valid for the cache's lifetime), or
+     *          nullptr when the file could not be parsed.
+     */
+    const ParsedSeriesFile* get_or_parse(const std::string& abs_path,
+                                         std::vector& errors,
+                                         SeriesFileStatus* status = nullptr);
+
+    /// Number of actual parse attempts (test hook for the single-read assertion).
+    int parse_count() const noexcept { return parse_count_; }
+
+private:
+    struct Entry {
+        SeriesFileStatus status = SeriesFileStatus::OPEN_FAILED;
+        ParsedSeriesFile file;
+    };
+    std::unordered_map files_;
+    int parse_count_ = 0;
+};
+
+/**
+ * @brief Process-wide count of multi-column file parses (test hook).
+ *
+ * @details Lets a black-box engine test assert the single-read guarantee
+ *          across swmm_engine_open (capture before, compare after). Not part
+ *          of the public C API.
+ */
+long multicolumn_parse_count_total() noexcept;
+
+} /* namespace openswmm::input */
+
+#endif /* OPENSWMM_ENGINE_MULTI_COLUMN_SERIES_FILE_HPP */
diff --git a/src/engine/input/PostParseResolver.cpp b/src/engine/input/PostParseResolver.cpp
index bcb79f9d3..e446afb7b 100644
--- a/src/engine/input/PostParseResolver.cpp
+++ b/src/engine/input/PostParseResolver.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PostParseResolver.cpp
  * @brief Post-parse cross-reference resolution.
@@ -6,13 +22,18 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "PostParseResolver.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+
+#include 
+#include "MultiColumnSeriesFile.hpp"
 #include "../core/Constants.hpp"
 #include "../core/ErrorCodes.hpp"
 #include "../core/PathResolver.hpp"
+#include "../core/PerfTimers.hpp"
 #include "../core/SimulationContext.hpp"
 #include "../core/DateTime.hpp"
 #include "../core/UnitConversion.hpp"
@@ -22,15 +43,52 @@
 #include "../hydraulics/Street.hpp"
 #include "../hydraulics/ForceMain.hpp"
 #include "../edit/VirtualJunctionOps.hpp"
+#include "../transport/MsxInitialQuality.hpp"   // U2: [INITIAL_QUALITY] MSX rows
+#include "Tokenizer.hpp"                          // U2: [INITIAL_QUALITY] FILE rows
+#include "InputParseUtils.hpp"
+#include 
+#include 
+
+#ifdef OPENSWMM_HAS_2D
+// SolverOptions2D is only forward-declared in SimulationContext.hpp; the full
+// definition is needed to resolve its mesh_file / output_file slots.
+#include "../2d/data/SolverOptions2D.hpp"
+#endif
 #include 
+#include 
 #include 
 #include 
+#include 
 #include 
+#include 
+#include 
 #include 
+#include 
+#include 
 #include 
 
 namespace openswmm::input {
 
+namespace {
+
+// legacy link.c getOffsetHeight (link.c:493-506): converts an ELEVATION offset
+// to a height above the node invert. A MISSING offset — what a '*' token
+// stores — means "sit on the node invert"; a small negative drop is silently
+// clamped, and only a drop deeper than MIN_DELTA_Z earns WARNING 03.
+double legacyOffsetHeight(double offset, double invert_elev,
+                          SimulationContext& ctx, const std::string& link_name) {
+    if (offset <= constants::MISSING) return 0.0;
+    offset -= invert_elev;
+    if (offset >= 0.0) return offset;
+    if (offset >= -constants::MIN_DELTA_Z) return 0.0;
+    ctx.warnings.push_back(format_warning(WARN_NEGATIVE_OFFSET, link_name));
+    return 0.0;
+}
+
+}  // namespace
+
+
+
 using openswmm::format_error;
 using openswmm::format_warning;
 using openswmm::ERR_TRANSECT_MANNING;
@@ -49,6 +107,10 @@ using openswmm::WARN_MAX_DEPTH_INCREASED;
 //   MM/DD/YYYY  H:MM  value
 //   ...
 // Fields may be tab or space delimited.
+//
+// Multi-column files (CSV/TSV/TSF, optionally referenced as "path:column")
+// are routed through the shared MultiColumnSeriesFile parse-once cache
+// instead — see load_external_timeseries_files below.
 // -------------------------------------------------------------------------
 // -------------------------------------------------------------------------
 // Slice IO-3: resolve every external-file slot's `original` token against
@@ -94,9 +156,25 @@ void resolve_external_file_slots(SimulationContext& ctx,
         if (tbl.type != TableType::TIMESERIES) continue;
         resolve(tbl.file_path);
     }
+
+    for (auto& rpt : ctx.lid_usage.rpt_file) resolve(rpt);
+
+    // 2D slots live behind a non-owning pointer wired by SWMMEngine's
+    // constructor, so it is non-null well before parsing — but a
+    // SimulationContext built standalone (unit tests, programmatic models)
+    // leaves it null. Without these two the external mesh reference could not
+    // be re-anchored on Save-As: the writer only ever saw a bare relative
+    // token with no way to tell what it was relative TO.
+#ifdef OPENSWMM_HAS_2D
+    if (ctx.twod_io.options) {
+        resolve(ctx.twod_io.options->mesh_file);
+        resolve(ctx.twod_io.options->output_file);
+    }
+#endif
 }
 
-static void load_external_timeseries_files(SimulationContext& ctx, const std::string& inp_dir) {
+static void load_external_timeseries_files(SimulationContext& ctx, const std::string& inp_dir,
+                                           MultiColumnFileCache& file_cache) {
     for (std::size_t t = 0; t < ctx.tables.tables.size(); ++t) {
         auto& tbl = ctx.tables.tables[t];
         if (tbl.type != TableType::TIMESERIES) continue;
@@ -111,69 +189,248 @@ static void load_external_timeseries_files(SimulationContext& ctx, const std::st
         // the cached resolution; fall back to inline resolution for
         // callers that built the model programmatically and never ran
         // the resolver pass.
-        std::string file_path = !tbl.file_path.absolute.empty()
-                                  ? tbl.file_path.absolute
-                                  : tbl.file_path.str();
+        std::string file_path;
+        if (!tbl.file_path.absolute.empty()) {
+            file_path = tbl.file_path.absolute;  // already anchored to the .inp dir
+        } else {
+            file_path = tbl.file_path.str();
+            // Resolve relative paths against INP file directory (legacy
+            // fallback path — kept so a fresh programmatic Table still loads
+            // even without the resolver pass). Applies only to the verbatim
+            // token: .absolute is already anchored, and prepending inp_dir a
+            // second time broke cwd-relative opens.
+            if (!file_path.empty() && file_path[0] != '/' && file_path[0] != '\\') {
+                if (!inp_dir.empty())
+                    file_path = inp_dir + "/" + file_path;
+            }
+        }
 
-        // Strip optional :column suffix (e.g. "path.dat:ColName")
-        auto colon_pos = file_path.rfind(':');
-        // Only strip if it's not a drive letter (e.g. "C:\path")
-        if (colon_pos != std::string::npos && colon_pos > 1) {
-            file_path = file_path.substr(0, colon_pos);
+        // Split the optional :column suffix (e.g. "path.csv:ColName") with the
+        // SHARED rule the gage reader uses (MultiColumnSeriesFile.hpp): last
+        // colon, ignoring a drive letter and any colon that belongs to a
+        // directory name. Both consumers must derive the same path or they key
+        // the cache differently and the file is read twice.
+        std::string col_name;
+        {
+            std::string path_only;
+            split_series_file_token(file_path, path_only, col_name);
+            file_path = path_only;
         }
 
-        // Resolve relative paths against INP file directory (legacy
-        // fallback path — kept so a fresh programmatic Table still loads
-        // even without the resolver pass).
-        if (!file_path.empty() && file_path[0] != '/' && file_path[0] != '\\') {
-            if (!inp_dir.empty())
-                file_path = inp_dir + "/" + file_path;
+        // Multi-column route: an explicit `:column` selector, or a file
+        // whose first content line reads as a header (CSV/TSV/TSF), goes
+        // through the shared parse-once cache so a file referenced by many
+        // series — and by rain gages — is read from disk exactly once per
+        // resolve pass. Plain `date time value` files keep the legacy
+        // whitespace path below.
+        if (!col_name.empty() || looks_like_multicolumn_series_file(file_path)) {
+            std::vector file_errors;
+            SeriesFileStatus st = SeriesFileStatus::OK;
+            const ParsedSeriesFile* pf =
+                file_cache.get_or_parse(file_path, file_errors, &st);
+            if (!pf && st == SeriesFileStatus::OPEN_FAILED) {
+                // Same final fallback the legacy fopen chain had: the
+                // verbatim token (minus any :column suffix) relative to the
+                // current working directory.
+                std::string verbatim, vcol;
+                split_series_file_token(tbl.file_path.str(), verbatim, vcol);
+                if (verbatim != file_path)
+                    pf = file_cache.get_or_parse(verbatim, file_errors, &st);
+            }
+            if (!pf) {
+                // Loud, not silent: an unreadable FILE series previously
+                // loaded as empty and read 0.0 at every lookup.
+                ctx.errors.push_back(format_error(
+                    st == SeriesFileStatus::OPEN_FAILED
+                        ? openswmm::ERR_TABLE_FILE_OPEN
+                        : openswmm::ERR_TABLE_FILE_READ,
+                    tbl.id));
+                continue;
+            }
+            const int col = col_name.empty() ? pf->first_data_column()
+                                             : pf->find_column(col_name);
+            if (col < 0) {
+                ctx.errors.push_back(format_error(
+                    openswmm::ERR_TABLE_FILE_READ, tbl.id,
+                    "column \"" + col_name + "\" not found in " + file_path));
+                continue;
+            }
+            const auto& vals = pf->columns[static_cast(col)];
+            tbl.x.reserve(pf->dates.size());
+            tbl.y.reserve(pf->dates.size());
+            for (std::size_t i = 0; i < pf->dates.size(); ++i) {
+                if (std::isnan(vals[i])) continue;  // missing/unreadable cell
+                tbl.x.push_back(pf->dates[i]);
+                tbl.y.push_back(vals[i]);
+            }
+            if (tbl.x.empty()) {
+                ctx.errors.push_back(format_error(
+                    openswmm::ERR_TABLE_FILE_READ, tbl.id, file_path));
+                continue;
+            }
+            tbl.x.shrink_to_fit();
+            tbl.y.shrink_to_fit();
+            // file_path is intentionally retained (see the note at the end
+            // of the legacy path below).
+            continue;
         }
 
         // Open the file
-        FILE* fp = std::fopen(file_path.c_str(), "r");
+        FILE* fp = openswmm::io::fopen_utf8(file_path, "r");
         if (!fp) {
             // Try the verbatim token as a final fallback (covers absolute
             // paths and same-cwd cases when inp_dir was empty).
-            fp = std::fopen(tbl.file_path.c_str(), "r");
-            if (!fp) continue; // Skip silently — legacy also reports ERROR 361
+            fp = openswmm::io::fopen_utf8(tbl.file_path, "r");
+            if (!fp) {
+                // Was a silent skip; legacy reports ERROR 361 and fails the
+                // open, so match it — an unloadable series otherwise reads
+                // as 0.0 everywhere with a clean-looking report.
+                ctx.errors.push_back(
+                    format_error(openswmm::ERR_TABLE_FILE_OPEN, tbl.id));
+                continue;
+            }
         }
 
-        // Reserve estimated capacity (large files can be millions of lines)
-        tbl.x.reserve(100000);
-        tbl.y.reserve(100000);
-
-        char line[256];
-        while (std::fgets(line, sizeof(line), fp)) {
-            // Skip comments and empty lines
-            if (line[0] == ';' || line[0] == '\n' || line[0] == '\r') continue;
+        // Reserve from the file's actual size rather than a flat 100k rows.
+        // The old constant committed 1.6 MB per FILE-backed series before
+        // reading a byte — on a model with hundreds of small rain files that
+        // is hundreds of megabytes of untouched pages, and on a genuinely
+        // large file it was too small anyway. ~24 bytes per "date time value"
+        // row is a deliberate under-estimate: geometric growth handles the
+        // remainder, whereas over-reserving cannot be given back.
+        {
+            std::error_code ec;
+            // utf8_path, not the implicit std::string -> path conversion: the
+            // open above already went through fopen_utf8, so a bare string
+            // here failed on a non-ASCII path and silently fell back to the
+            // 1024-row guess for a file we know the size of (issue #7).
+            const auto bytes =
+                std::filesystem::file_size(openswmm::io::utf8_path(file_path), ec);
+            std::size_t rows = ec ? std::size_t{1024}
+                                  : static_cast(bytes) / 24u + 16u;
+            rows = std::min(rows, 2000000u);
+            tbl.x.reserve(rows);
+            tbl.y.reserve(rows);
+        }
 
-            // Parse: date  time  value
-            // Format: MM/DD/YYYY  H:MM  value  (tab or space delimited)
-            int month = 0, day = 0, year = 0;
-            int hour = 0, minute = 0;
-            double value = 0.0;
+        // Row grammar — mirror legacy table_parseFileLine() (table.c:838).
+        // Tokens split on space/tab/CR/LF/comma (legacy TBLSEPSTR); a first
+        // token starting with ';' is a comment. A row is either
+        //   date time value   — date M/D/Y with '/' or '-' separators,
+        //                       numeric or 3-letter month name (DateFormat
+        //                       is pinned M_D_Y at open, legacy swmm5.c:647)
+        //   time value        — date carried from the last dated row
+        // and the time token is decimal HOURS when it is entirely numeric,
+        // else H:MM[:SS] (legacy datetime_strToTime). Rows before the first
+        // dated row are elapsed times anchored at the simulation START
+        // DATETIME: legacy input.c:176 seeds every series' lastDate with
+        // StartDate + StartTime, and options are already parsed when this
+        // loader runs, so the anchor is applied directly here (the rows are
+        // stored absolute; the resolver's inline relative-row offset pass
+        // does not apply to them). The previous parser accepted ONLY
+        // "M/D/Y H:MM value" rows, so every elapsed-time or decimal-hour
+        // legacy file loaded zero rows and failed the open with ERROR 363.
+        double last_date = ctx.options.start_date; // date carried across rows
+
+        auto next_tok = [](char*& p) -> char* {
+            while (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r' ||
+                   *p == ',') ++p;
+            if (*p == '\0') return nullptr;
+            char* start = p;
+            while (*p && *p != ' ' && *p != '\t' && *p != '\n' &&
+                   *p != '\r' && *p != ',') ++p;
+            if (*p) { *p = '\0'; ++p; }
+            return start;
+        };
 
-            // Try tab-delimited first, then space-delimited
-            char date_str[32] = {}, time_str[32] = {};
-            int fields = std::sscanf(line, "%31s %31s %lf", date_str, time_str, &value);
-            if (fields < 3) continue;
+        auto parse_file_date = [](const char* s, double& d_out) -> bool {
+            if (!std::strchr(s, '/') && !std::strchr(s, '-')) return false;
+            unsigned m = 0, d = 0, y = 0;
+            char sep1 = 0, sep2 = 0;
+            if (std::sscanf(s, "%u%c%u%c%u", &m, &sep1, &d, &sep2, &y) < 5) {
+                char mon[4] = {};
+                if (std::sscanf(s, "%3[A-Za-z]%c%u%c%u",
+                                mon, &sep1, &d, &sep2, &y) < 5) return false;
+                static const char* kMonths[12] = {
+                    "JAN", "FEB", "MAR", "APR", "MAY", "JUN",
+                    "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"};
+                m = 0;
+                for (unsigned i = 0; i < 12; ++i) {
+                    if (std::toupper(static_cast(mon[0])) == kMonths[i][0] &&
+                        std::toupper(static_cast(mon[1])) == kMonths[i][1] &&
+                        std::toupper(static_cast(mon[2])) == kMonths[i][2]) {
+                        m = i + 1;
+                        break;
+                    }
+                }
+                if (m == 0) return false;
+            }
+            const double enc = datetime::encodeDate(static_cast(y),
+                                                    static_cast(m),
+                                                    static_cast(d));
+            if (enc == -static_cast(datetime::DateDelta)) return false;
+            d_out = enc;
+            return true;
+        };
 
-            // Parse date: MM/DD/YYYY
-            if (std::sscanf(date_str, "%d/%d/%d", &month, &day, &year) != 3) continue;
+        auto parse_file_time = [](const char* s, double& t_out) -> bool {
+            char* endp = nullptr;
+            const double hrs = std::strtod(s, &endp);
+            if (endp && *endp == '\0') {           // decimal hours
+                t_out = hrs / 24.0;
+                return true;
+            }
+            int hr = 0, min = 0, sec = 0;
+            if (std::sscanf(s, "%d:%d:%d", &hr, &min, &sec) < 1) return false;
+            if (hr < 0 || min < 0 || sec < 0) return false;
+            t_out = datetime::encodeTime(hr, min, sec);
+            return true;
+        };
 
-            // Parse time: H:MM or HH:MM or H:MM:SS
-            int second = 0;
-            if (std::sscanf(time_str, "%d:%d:%d", &hour, &minute, &second) < 2) continue;
+        char line[256];
+        while (std::fgets(line, sizeof(line), fp)) {
+            char* p = line;
+            char* s1 = next_tok(p);
+            if (!s1 || *s1 == ';') continue;       // blank line or comment
+            char* s2 = next_tok(p);
+            char* s3 = next_tok(p);                // extra tokens ignored
+
+            const char* time_tok;
+            const char* value_tok;
+            double d = 0.0;
+            if (s3) {                              // date  time  value
+                if (!parse_file_date(s1, d)) continue;
+                last_date = d;
+                time_tok  = s2;
+                value_tok = s3;
+            } else if (s2) {                       // time  value
+                d = last_date;
+                time_tok  = s1;
+                value_tok = s2;
+            } else {
+                continue;
+            }
 
-            double dt = datetime::encodeDate(year, month, day)
-                      + datetime::encodeTime(hour, minute, second);
+            double t = 0.0;
+            if (!parse_file_time(time_tok, t)) continue;
+            char* endp = nullptr;
+            const double value = std::strtod(value_tok, &endp);
+            if (endp == value_tok || *endp != '\0') continue;
 
-            tbl.x.push_back(dt);
+            tbl.x.push_back(d + t);
             tbl.y.push_back(value);
         }
         std::fclose(fp);
 
+        // Loud, not silent: a file that opened but yielded no parseable
+        // rows (wrong delimiter, wrong format) previously produced an
+        // empty series that read as 0.0 at every lookup.
+        if (tbl.x.empty()) {
+            ctx.errors.push_back(
+                format_error(openswmm::ERR_TABLE_FILE_READ, tbl.id, file_path));
+            continue;
+        }
+
         // Shrink to fit
         tbl.x.shrink_to_fit();
         tbl.y.shrink_to_fit();
@@ -196,7 +453,406 @@ static void load_external_timeseries_files(SimulationContext& ctx, const std::st
 // `rain_series` Table so the runtime reuses the same step-function lookup as
 // an inline [TIMESERIES] gage without polluting ctx.tables.
 // -------------------------------------------------------------------------
-static void load_external_rain_files(SimulationContext& ctx) {
+// -------------------------------------------------------------------------
+// USER_CSV rain files (multi-column CSV / TSV / PCSWMM TSF)
+// -------------------------------------------------------------------------
+// `FILE "rain.csv:COLUMN"` — a header row, with the value taken from the
+// column whose header matches COLUMN (empty column = first data column).
+// Column 0 carries a full date-time. The delimiter and TSF header form are
+// auto-detected by MultiColumnSeriesFile. Values are in the PROJECT's rain
+// units and are stored verbatim: unlike the standard format there is no
+// legacy interface file to be bit-compatible with, so the read side
+// interprets them per the gage's declared Format exactly as it does for an
+// inline [TIMESERIES] gage. See gage::gageUnitsFactor, which is scoped to
+// STAN_PRCP for this reason.
+// -------------------------------------------------------------------------
+
+static void load_rain_file_user_csv(SimulationContext& ctx, int g,
+                                    const std::string& path,
+                                    double win_lo, double win_hi,
+                                    MultiColumnFileCache& file_cache) {
+    const auto ug = static_cast(g);
+
+    // Parse-once: the shared cache reads the file on first request; every
+    // other gage (and FILE timeseries) on the same file copies out of the
+    // same ParsedSeriesFile. CSV/TSV/TSF are auto-detected by content, so
+    // USER_CSV now means "multi-column text file" generally.
+    std::vector file_errors;
+    SeriesFileStatus st = SeriesFileStatus::OK;
+    const ParsedSeriesFile* pf = file_cache.get_or_parse(path, file_errors, &st);
+    if (!pf && st == SeriesFileStatus::OPEN_FAILED &&
+        ctx.gages.file_path[ug].str() != path) {
+        // Same fallback the direct fopen had: try the verbatim token.
+        pf = file_cache.get_or_parse(ctx.gages.file_path[ug].str(), file_errors, &st);
+    }
+    if (!pf) {
+        ctx.errors.push_back(format_error(
+            st == SeriesFileStatus::OPEN_FAILED ? openswmm::ERR_RAIN_FILE_OPEN
+                                                : openswmm::ERR_RAIN_FILE_FORMAT,
+            path));
+        return;
+    }
+
+    const std::string& want = ctx.gages.col_name[ug];
+    // B2 fix: an empty column name selects the first data column, matching
+    // the documented default (GageData.hpp col_name) instead of erroring.
+    const int col = want.empty() ? pf->first_data_column()
+                                 : pf->find_column(want);
+    if (col < 0) {
+        ctx.errors.push_back(format_error(openswmm::ERR_RAIN_FILE_FORMAT,
+                                          path + " (column \"" + want + "\")"));
+        return;
+    }
+    const auto uc = static_cast(col);
+
+    Table series;
+    series.type = TableType::TIMESERIES;
+    series.id   = ctx.gage_names.name_of(g);
+
+    // Retain only the records needed to route the simulation window; the
+    // cache rows are already sorted ascending, so the copy stays sorted.
+    const auto& vals = pf->columns[uc];
+    for (std::size_t i = 0; i < pf->dates.size(); ++i) {
+        const double val = vals[i];
+        if (std::isnan(val)) continue;  // missing/unreadable cell
+        const double dt = pf->dates[i];
+        if (dt < win_lo || dt > win_hi) continue;
+        series.x.push_back(dt);
+        series.y.push_back(val);
+    }
+
+    const long unparsed_rows = pf->unparsed_rows + pf->col_unparsed_cells[uc];
+    if (unparsed_rows > 0) {
+        // One warning per gage, not per row: a mis-specified file would
+        // otherwise bury the report under thousands of identical lines.
+        ctx.warnings.push_back(
+            format_warning(openswmm::WARN_RAIN_CSV_ROWS_SKIPPED,
+                           ctx.gage_names.name_of(g),
+                           std::to_string(unparsed_rows) + " row(s), " + path));
+    }
+
+    series.x.shrink_to_fit();
+    series.y.shrink_to_fit();
+
+    // Whole-file, per-column statistics for the "Rainfall File Summary".
+    ctx.gages.file_first_date[ug]     = pf->col_first_date[uc];
+    ctx.gages.file_last_date[ug]      = pf->col_last_date[uc];
+    ctx.gages.file_periods_precip[ug] = pf->col_periods_precip[uc];
+    ctx.gages.rain_series[ug]         = std::move(series);
+}
+
+// ============================================================================
+// NWS / NCDC external rain file formats (legacy rain.c)
+// ============================================================================
+//
+// A `FILE` gage whose data file is one of the NWS / NCDC layouts, rather than
+// the "standard" `station date time value` one, used to read as a file with no
+// parseable rows at all: every sscanf in the standard reader failed, the series
+// came back empty, and an empty series answers 0.0 at every lookup. The run
+// then completed, continuity closed at 0.000 %, and the .rpt printed a Rainfall
+// File Summary — a model with no precipitation anywhere, reported as a success.
+// events-example is the corpus case (legacy 12.02 in of rain, v6 none).
+//
+// Legacy sniffs the first five lines for the layout (findFileFormat) and reads
+// the NWS family through one routine (readNWSLine). Both are mirrored here.
+// The values these formats carry are depths in HUNDREDTHS OF AN INCH, and
+// legacy writes them to its interface file WITHOUT the rain-type transform and
+// WITHOUT the units factor that the standard reader applies — those belong to
+// readStdLine alone. The recording interval comes from the FILE (the element
+// type), overriding the interval the deck declared, exactly as legacy does at
+// findFileFormat's last line.
+//
+// Not ported: the Canadian AES_HLY / CMC_FIF / CMC_HLY layouts, which legacy
+// also detects. No corpus deck uses one; a file in those formats still reads as
+// the standard layout, i.e. as no rows.
+
+enum class NwsFormat { NONE, TAPE, SPACE_DELIMITED, COMMA_DELIMITED,
+                       ONLINE_60, ONLINE_15 };
+
+struct NwsFileSpec {
+    NwsFormat fmt              = NwsFormat::NONE;
+    int       interval_sec     = 0;
+    int       time_offset      = 0;  ///< legacy TimeOffset: stamps a reading at
+                                     ///< the START of the interval it ends
+    int       hdr_lines        = 0;
+    bool      has_station_name = false;
+    int       value_offset     = 0;  ///< ONLINE_* only (column of "HPCP"/"QPCP")
+    int       data_offset      = 0;  ///< ONLINE_* only (column of the date)
+};
+
+/// legacy getNWSInterval (rain.c): decodes the element type to an interval.
+static int nws_interval(const char* elem_type) {
+    if (std::strcmp(elem_type, "HPCP") == 0) return 3600;  // hourly
+    if (std::strcmp(elem_type, "QPCP") == 0) return 900;   // 15 minute
+    if (std::strcmp(elem_type, "QGAG") == 0) return 900;   // 15 minute
+    return 0;
+}
+
+/// legacy findNWSOnlineFormat (rain.c): the "Online Retrieval" layouts, whose
+/// header names the element and whose first COOP: row fixes the date column.
+static bool nws_detect_online(std::FILE* f, NwsFileSpec& spec) {
+    char line[1024];
+    std::rewind(f);
+    if (!std::fgets(line, sizeof(line), f)) return false;
+
+    if (const char* s = std::strstr(line, "HPCP")) {
+        spec.interval_sec = 3600;
+        spec.value_offset = static_cast(s - line);
+        spec.fmt          = NwsFormat::ONLINE_60;
+    } else if (const char* q = std::strstr(line, "QPCP")) {
+        spec.interval_sec = 900;
+        spec.value_offset = static_cast(q - line);
+        spec.fmt          = NwsFormat::ONLINE_15;
+    } else {
+        return false;
+    }
+    spec.time_offset = spec.interval_sec;
+
+    // The date begins 11 characters before the last ':' of the first data row.
+    for (int n = 1; n <= 5; ++n) {
+        if (!std::fgets(line, sizeof(line), f)) return false;
+        if (!std::strstr(line, "COOP:")) continue;
+        const char* last = std::strrchr(line, ':');
+        if (!last) return false;
+        spec.data_offset = static_cast(last - line) - 11;
+        return true;
+    }
+    return false;
+}
+
+/// legacy findFileFormat (rain.c), NWS branches only: the caller falls back to
+/// the standard reader when this returns NwsFormat::NONE.
+///
+/// The two "w/ station name" probes read from column 37. Legacy runs its sscanf
+/// there without checking that the line is that long, which walks off the end
+/// of a shorter row; the length guard here is the only deliberate departure.
+static NwsFileSpec nws_detect_format(std::FILE* f) {
+    NwsFileSpec spec;
+    char line[1024];
+    char elem[5]  = "";
+    char rec[4]   = "";
+    char coop[6]  = "";
+    long sn2 = 0;
+    int  div = 0, year = 0;
+
+    std::rewind(f);
+    for (int line_count = 1; line_count <= 5; ++line_count) {
+        if (!std::fgets(line, sizeof(line), f)) return spec;
+        const std::size_t len = std::strlen(line);
+
+        auto accept = [&](NwsFormat fmt, bool named) {
+            spec.interval_sec     = nws_interval(elem);
+            spec.time_offset      = spec.interval_sec;
+            spec.has_station_name = named;
+            if (spec.interval_sec > 0) spec.fmt = fmt;
+            return spec.interval_sec > 0;
+        };
+
+        if (std::sscanf(line, "%6ld %2d %4s", &sn2, &div, elem) == 3 &&
+            accept(NwsFormat::SPACE_DELIMITED, false)) return spec;
+
+        if (len > 37 &&
+            std::sscanf(&line[37], "%2d %4s %2s %4d", &div, elem, rec, &year) == 4 &&
+            accept(NwsFormat::SPACE_DELIMITED, true)) return spec;
+
+        if (std::sscanf(line, "%6ld,%2d,%4s", &sn2, &div, elem) == 3 &&
+            accept(NwsFormat::COMMA_DELIMITED, false)) return spec;
+
+        if (len > 37 &&
+            std::sscanf(&line[37], "%2d,%4s,%2s,%4d", &div, elem, rec, &year) == 4 &&
+            accept(NwsFormat::COMMA_DELIMITED, true)) return spec;
+
+        if (std::sscanf(line, "%3s%6ld%2d%4s", rec, &sn2, &div, elem) == 4 &&
+            accept(NwsFormat::TAPE, false)) return spec;
+
+        if (std::sscanf(line, "%5s%6ld", coop, &sn2) == 2 &&
+            std::strcmp(coop, "COOP:") == 0) {
+            if (!nws_detect_online(f, spec)) spec.fmt = NwsFormat::NONE;
+            return spec;
+        }
+
+        ++spec.hdr_lines;
+    }
+    return spec;
+}
+
+/// legacy setCondition (rain.c).
+enum class NwsCondition { NONE, ACCUMULATED, DELETED, MISSING };
+
+static NwsCondition nws_condition(char flag) {
+    switch (flag) {
+        case 'a': case 'A': return NwsCondition::ACCUMULATED;
+        case '{': case '}': return NwsCondition::DELETED;
+        case '[': case ']': return NwsCondition::MISSING;
+        default:            return NwsCondition::NONE;
+    }
+}
+
+/// legacy readNwsOnlineValue (rain.c): hundredths of an inch, or — in the newer
+/// online format — decimal inches, which are converted back to hundredths.
+static int nws_read_online_value(const char* s, long& v, char& flag) {
+    if (std::strchr(s, '.')) {
+        float x = 99.99f;
+        const int n = std::sscanf(s, "%f %c", &x, &flag);
+        v = static_cast(100.0f * x + 0.5f);
+        return n;
+    }
+    return std::sscanf(s, "%ld %c", &v, &flag);
+}
+
+/// Reads an NWS-family rain file into `series` (dates, depth in INCHES), and
+/// returns the whole-file statistics the "Rainfall File Summary" reports.
+/// Mirrors legacy readNWSLine + saveRainfall + saveAccumRainfall.
+static void nws_read_file(std::FILE* f, const NwsFileSpec& spec,
+                          double win_lo, double win_hi,
+                          Table& series,
+                          double& first_date, double& last_date,
+                          long& periods_precip) {
+    char line[4096];
+    NwsCondition condition   = NwsCondition::NONE;
+    double       accum_start = 0.0;   // legacy AccumStartDate (NO_DATE == 0)
+
+    // legacy saveRainfall: a reading is stamped at the start of the interval it
+    // ends, and only a non-missing value reaches the interface file.
+    auto emit = [&](double day, int hour, int minute, float x) {
+        const double when =
+            datetime::addSeconds(day, 3600.0 * hour + 60.0 * minute
+                                      - spec.time_offset);
+        if (first_date == 0.0 || when < first_date) first_date = when;
+        if (when > last_date) last_date = when;
+        if (x > 0.0f) ++periods_precip;
+        if (when < win_lo || when > win_hi) return;
+        series.x.push_back(when);
+        series.y.push_back(static_cast(x));
+    };
+
+    std::rewind(f);
+    for (int i = 1; i <= spec.hdr_lines; ++i) {
+        if (!std::fgets(line, sizeof(line), f)) return;
+    }
+
+    while (std::fgets(line, sizeof(line), f)) {
+        const int line_length = static_cast(std::strlen(line)) - 1;
+        int y = 0, m = 0, d = 0, n = 0, k = 0;
+
+        switch (spec.fmt) {
+            case NwsFormat::TAPE:
+                if (line_length <= 30) continue;
+                if (std::sscanf(&line[17], "%4d%2d%4d%3d", &y, &m, &d, &n) < 4)
+                    continue;
+                k = 30;
+                break;
+            case NwsFormat::SPACE_DELIMITED: {
+                const int name_length = spec.has_station_name ? 31 : 0;
+                if (line_length <= 28 + name_length) continue;
+                k = 18 + name_length;
+                if (std::sscanf(&line[k], "%4d %2d %2d", &y, &m, &d) < 3)
+                    continue;
+                k += 10;
+                break;
+            }
+            case NwsFormat::COMMA_DELIMITED:
+                if (line_length <= 28) continue;
+                if (std::sscanf(&line[18], "%4d,%2d,%2d", &y, &m, &d) < 3)
+                    continue;
+                k = 28;
+                break;
+            case NwsFormat::ONLINE_60:
+            case NwsFormat::ONLINE_15:
+                if (line_length <= spec.data_offset + 23) continue;
+                if (std::sscanf(&line[spec.data_offset], "%4d%2d%2d",
+                                &y, &m, &d) < 3) continue;
+                k = spec.data_offset + 8;
+                break;
+            default:
+                return;
+        }
+
+        double date1 = datetime::encodeDate(y, m, d);
+
+        // --- each recorded time, value & condition code on the line
+        while (k < line_length) {
+            char flag1 = 0, flag2 = 0;
+            long v = 99999;
+            int  hour = 25, minute = 0;
+
+            switch (spec.fmt) {
+                case NwsFormat::TAPE:
+                    n = std::sscanf(&line[k], "%2d%2d%6ld%c%c",
+                                    &hour, &minute, &v, &flag1, &flag2);
+                    k += 12;
+                    break;
+                case NwsFormat::SPACE_DELIMITED:
+                    n = std::sscanf(&line[k], " %2d%2d %6ld %c %c",
+                                    &hour, &minute, &v, &flag1, &flag2);
+                    k += 16;
+                    break;
+                case NwsFormat::COMMA_DELIMITED:
+                    n = std::sscanf(&line[k], ",%2d%2d,%6ld,%c,%c",
+                                    &hour, &minute, &v, &flag1, &flag2);
+                    k += 16;
+                    break;
+                default:  // ONLINE_60 / ONLINE_15
+                    n  = std::sscanf(&line[k], " %2d:%2d", &hour, &minute);
+                    n += nws_read_online_value(&line[spec.value_offset],
+                                               v, flag1);
+                    // ending hour 0 is really hour 24 of the previous day
+                    if (hour == 0) { hour = 24; date1 -= 1.0; }
+                    k += line_length;
+                    break;
+            }
+
+            // an hour, a minute and a value are the minimum; codes may be absent
+            if (n < 3 || hour >= 25) break;
+
+            condition = nws_condition(flag1);
+            const bool is_missing = (condition == NwsCondition::DELETED ||
+                                     condition == NwsCondition::MISSING ||
+                                     flag1 == 'M' || v >= 9999);
+
+            if (flag1 == 'a') {
+                accum_start = date1 + datetime::encodeTime(hour, minute, 0);
+            } else if (flag1 == 'A') {
+                // legacy saveAccumRainfall: spread the accumulated total evenly
+                // over the recording periods it covers.
+                if (accum_start != 0.0 && v != 99999 && spec.interval_sec > 0) {
+                    const double date2 = date1
+                                       + datetime::encodeTime(hour, minute, 0);
+                    const int np = static_cast(
+                        datetime::timeDiff(date2, accum_start)
+                        / spec.interval_sec) + 1;
+                    const float x = static_cast(v)
+                                  / static_cast(np) / 100.0f;
+                    if (x > 0.0f) {
+                        double when = datetime::addSeconds(accum_start,
+                                                           -spec.time_offset);
+                        for (int j = 0; j < np; ++j) {
+                            if (first_date == 0.0 || when < first_date)
+                                first_date = when;
+                            if (when > last_date) last_date = when;
+                            ++periods_precip;
+                            if (when >= win_lo && when <= win_hi) {
+                                series.x.push_back(when);
+                                series.y.push_back(static_cast(x));
+                            }
+                            when = datetime::addSeconds(when,
+                                                        spec.interval_sec);
+                        }
+                    }
+                }
+                accum_start = 0.0;
+            } else if (!is_missing) {
+                emit(date1, hour, minute, static_cast(v) / 100.0f);
+            }
+
+            if (flag1 == 'A' || flag1 == '}' || flag1 == ']')
+                condition = NwsCondition::NONE;
+        }
+    }
+}
+
+static void load_external_rain_files_impl(SimulationContext& ctx,
+                                          MultiColumnFileCache& file_cache) {
     const int n_gages = ctx.gages.count();
     if (n_gages == 0) return;
 
@@ -211,14 +867,38 @@ static void load_external_rain_files(SimulationContext& ctx) {
     for (int g = 0; g < n_gages; ++g) {
         const auto ug = static_cast(g);
         if (ctx.gages.source[ug] != RainSource::FILE_RAIN) continue;
-        if (ctx.gages.file_format[ug] != RainFileFormat::STAN_PRCP) continue;
+
+        bool is_csv = ctx.gages.file_format[ug] == RainFileFormat::USER_CSV;
+        if (!is_csv && ctx.gages.file_format[ug] != RainFileFormat::STAN_PRCP) continue;
 
         std::string path = !ctx.gages.file_path[ug].absolute.empty()
                              ? ctx.gages.file_path[ug].absolute
                              : ctx.gages.file_path[ug].str();
-        FILE* fp = std::fopen(path.c_str(), "r");
+
+        // A USER_CSV gage whose column is empty (= "first data column") is
+        // written as a bare `FILE "path"` token, because `FILE "path:"` is
+        // malformed for EPA SWMM / PCSWMM. That token re-parses as STAN_PRCP,
+        // so recover the format here, where the path is resolved and the file
+        // can be inspected: an empty station id plus multi-column CONTENT can
+        // only mean the compact form. The STAN_PRCP reader would otherwise
+        // fail every sscanf and hand back a silently empty series — the exact
+        // failure mode this change set exists to remove. Gated on an empty
+        // station id and on content, so a whitespace station file (which the
+        // sniff rejects) and any gage that names a station are untouched.
+        if (!is_csv && ctx.gages.station_id[ug].empty() &&
+            looks_like_multicolumn_series_file(path)) {
+            ctx.gages.file_format[ug] = RainFileFormat::USER_CSV;
+            is_csv = true;
+        }
+
+        if (is_csv) {
+            load_rain_file_user_csv(ctx, g, path, win_lo, win_hi, file_cache);
+            continue;
+        }
+
+        FILE* fp = openswmm::io::fopen_utf8(path, "r");
         if (!fp) {
-            fp = std::fopen(ctx.gages.file_path[ug].c_str(), "r");
+            fp = openswmm::io::fopen_utf8(ctx.gages.file_path[ug], "r");
             if (!fp) {
                 // A gage that declares FILE but whose file cannot be opened is
                 // FATAL, exactly as in legacy (ERROR 317). Skipping it silently
@@ -236,6 +916,30 @@ static void load_external_rain_files(SimulationContext& ctx) {
             }
         }
 
+        // An NWS / NCDC layout is read by its own reader, which carries the
+        // recording interval the FILE declares (legacy findFileFormat's last
+        // line: Gage[i].rainInterval = Interval) and neither the rain-type
+        // transform nor the units factor below — those are readStdLine's.
+        const NwsFileSpec nws = nws_detect_format(fp);
+        if (nws.fmt != NwsFormat::NONE) {
+            Table nws_series;
+            nws_series.type = TableType::TIMESERIES;
+            nws_series.id   = ctx.gage_names.name_of(g);
+            double nws_first = 0.0, nws_last = 0.0;
+            long   nws_periods = 0;
+            nws_read_file(fp, nws, win_lo, win_hi, nws_series,
+                          nws_first, nws_last, nws_periods);
+            std::fclose(fp);
+
+            ctx.gages.interval_sec[ug]        = nws.interval_sec;
+            ctx.gages.file_first_date[ug]     = nws_first;
+            ctx.gages.file_last_date[ug]      = nws_last;
+            ctx.gages.file_periods_precip[ug] = nws_periods;
+            ctx.gages.rain_series[ug]         = std::move(nws_series);
+            continue;
+        }
+        std::rewind(fp);
+
         // PARITY: legacy pipes external rain files through a binary "rain
         // interface file" that stores depths in INCHES as 4-byte FLOATS:
         //   - parseStdLine (rain.c) reads the value with sscanf "%f" (float);
@@ -331,6 +1035,88 @@ static void load_external_rain_files(SimulationContext& ctx) {
     }
 }
 
+void load_external_rain_files(SimulationContext& ctx) {
+    // Standalone entry point (swmm_gage_reload_rain_files): a fresh cache
+    // per call still guarantees one parse per unique file within the call.
+    // The resolve pass instead shares one cache with the timeseries loader
+    // (see resolve_cross_references).
+    MultiColumnFileCache file_cache;
+    load_external_rain_files_impl(ctx, file_cache);
+}
+
+double conduit_manning_n(const SimulationContext& ctx, int j) {
+    const auto uj = static_cast(j);
+    if (ctx.links.type[uj] != LinkType::CONDUIT) return 0.0;
+    const int cr = ctx.link_subtypes.conduit_row(j);
+    if (cr < 0) return 0.0;
+    const auto& CD = ctx.link_subtypes.conduits;
+    const auto ucr = static_cast(cr);
+    const XsectShape shape = ctx.links.xsect_shape[uj];
+
+    double n_val = CD.roughness[ucr];
+
+    // IRREGULAR (transect) conduits take their Manning's n from the transect's
+    // MAIN-CHANNEL roughness, NOT the [CONDUITS] value — legacy link.c:1024
+    //   Conduit[k].roughness = Transect[xsect.transect].roughness;
+    // (Transect.roughness is the un-Lfactor-adjusted main-channel n.) Using the
+    // [CONDUITS] n made the dynamic-wave friction/conveyance wrong by the ratio
+    // n_conduit/n_transect — e.g. user5's LIB transects (conduit n=0.014 vs
+    // transect n=0.04) conveyed ~2.9× too much flow; 50-transects authors 1.0
+    // against a transect n of 0.1.
+    const int ti = (shape == XsectShape::IRREGULAR) ? ctx.links.xsect_curve[uj] : -1;
+    if (ti >= 0 && static_cast(ti) < ctx.transects.n_channel.size()) {
+        const double nch = ctx.transects.n_channel[static_cast(ti)];
+        if (nch > 0.0) n_val = nch;
+    }
+
+    // For DW force mains, substitute equivalent Manning's n (Gap #22)
+    // Matches legacy conduit_validate in link.c lines 1094-1096:
+    //   if (RouteModel == DW && xsect.type == FORCE_MAIN)
+    //       roughness = forcemain_getEquivN(j, k);
+    // ==DYNWAVE audit (plan §4.1): FV solves the same momentum equation, so
+    // the force-main equivalent-n substitution applies to it identically.
+    const bool is_dw = (ctx.options.routing_model == RoutingModel::DYNWAVE ||
+                        ctx.options.routing_model == RoutingModel::FV);
+    if (is_dw && shape == XsectShape::FORCE_MAIN) {
+        auto fm = static_cast(ctx.options.force_main_eqn);
+        const double r_bot  = ctx.links.xsect_r_bot[uj];
+        const double y_full = ctx.links.xsect_y_full[uj];
+        const double slope  = std::fabs(CD.slope[ucr]);
+        const double eq = forcemain::getEquivN(fm, r_bot, y_full, slope, n_val);
+        n_val = (eq > 0.0) ? eq : CD.roughness[ucr];
+    }
+
+    // PARITY link.c:1101-1105: a meandering natural channel's n is raised by
+    // the square root of its transect's length factor (channel length over
+    // flood-plain length; legacy defaults a 0 on the X1 line to 1.0). This is
+    // on top of the sqrt(Lfactor) the transect table build already folds into
+    // its own conveyance (transect.c:232), exactly as legacy applies both.
+    if (ti >= 0 && static_cast(ti) < ctx.transects.length_factor.size()) {
+        const double lf = ctx.transects.length_factor[static_cast(ti)];
+        if (lf > 0.0) n_val *= std::sqrt(lf);
+    }
+    return n_val;
+}
+
+double conduit_true_length(const SimulationContext& ctx, int j) {
+    if (j < 0 || j >= ctx.n_links()) return 0.0;
+    const auto uj = static_cast(j);
+    if (ctx.links.type[uj] != LinkType::CONDUIT) return 0.0;
+    const int cr = ctx.link_subtypes.conduit_row(j);
+    if (cr < 0) return 0.0;
+    const double len =
+        ctx.link_subtypes.conduits.length[static_cast(cr)];
+    if (ctx.links.xsect_shape[uj] != XsectShape::IRREGULAR) return len;
+    const int ti = ctx.links.xsect_curve[uj];
+    if (ti < 0 ||
+        static_cast(ti) >= ctx.transects.length_factor.size())
+        return len;
+    const double lf =
+        ctx.transects.length_factor[static_cast(ti)];
+    // legacy defaults a 0 on the X1 line to 1.0 (transect.c:377).
+    return (lf > 0.0) ? len / lf : len;
+}
+
 void recompute_conduit_flow_properties(SimulationContext& ctx, int j) {
     using constants::GRAVITY;
     using constants::PHI;
@@ -344,46 +1130,18 @@ void recompute_conduit_flow_properties(SimulationContext& ctx, int j) {
     // that this link's cross-section-derived fields are changing.
     ++ctx.xsect_generation;
 
-    double n_val    = CD.roughness[ucr];
+    // The effective n (transect channel n / force-main equivalent n / meander
+    // factor — legacy conduit_validate's `roughness`); see conduit_manning_n.
+    // Router::init applies the same helper when it lengthens a conduit, so a
+    // lengthened transect conduit keeps its transect n as legacy does.
+    double n_val    = conduit_manning_n(ctx, j);
     double slope    = std::fabs(CD.slope[ucr]);
     double a_full   = ctx.links.xsect_a_full[uj];
     double s_full   = ctx.links.xsect_s_full[uj];
     double s_max    = ctx.links.xsect_s_max[uj];
 
-    // IRREGULAR (transect) conduits take their Manning's n from the transect's
-    // MAIN-CHANNEL roughness, NOT the [CONDUITS] value — legacy link.c:1024
-    //   Conduit[k].roughness = Transect[xsect.transect].roughness;
-    // (Transect.roughness is the un-Lfactor-adjusted main-channel n.) Using the
-    // [CONDUITS] n here made the dynamic-wave friction/conveyance wrong by the
-    // ratio n_conduit/n_transect — e.g. user5's LIB transects (conduit n=0.014
-    // vs transect n=0.04) conveyed ~2.9× too much flow.
-    if (ctx.links.xsect_shape[uj] == XsectShape::IRREGULAR) {
-        int ti = ctx.links.xsect_curve[uj];
-        if (ti >= 0 && static_cast(ti) < ctx.transects.n_channel.size()) {
-            double nch = ctx.transects.n_channel[static_cast(ti)];
-            if (nch > 0.0) n_val = nch;
-        }
-    }
-
     if (n_val <= 0.0 || a_full <= 0.0) return;
 
-    // For DW force mains, substitute equivalent Manning's n (Gap #22)
-    // Matches legacy conduit_validate in link.c lines 1094-1096:
-    //   if (RouteModel == DW && xsect.type == FORCE_MAIN)
-    //       roughness = forcemain_getEquivN(j, k);
-    bool is_force_main = (ctx.links.xsect_shape[uj] == XsectShape::FORCE_MAIN);
-    // ==DYNWAVE audit (plan §4.1): FV solves the same momentum equation, so
-    // the force-main equivalent-n substitution applies to it identically.
-    bool is_dw = (ctx.options.routing_model == RoutingModel::DYNWAVE ||
-                  ctx.options.routing_model == RoutingModel::FV);
-    if (is_dw && is_force_main) {
-        auto fm = static_cast(ctx.options.force_main_eqn);
-        double r_bot  = ctx.links.xsect_r_bot[uj];
-        double y_full = ctx.links.xsect_y_full[uj];
-        n_val = forcemain::getEquivN(fm, r_bot, y_full, slope, n_val);
-        if (n_val <= 0.0) n_val = CD.roughness[ucr];
-    }
-
     // Roughness factor for DW friction slope: GRAVITY * (n/PHI)^2.
     // PARITY link.c:1133: GRAVITY * SQR(roughness/PHI) — the square is grouped
     // FIRST, then multiplied by GRAVITY. Left-to-right G*(x)*(x) rounds
@@ -410,6 +1168,9 @@ void recompute_conduit_flow_properties(SimulationContext& ctx, int j) {
     // Matches legacy link.c lines 1127-1130:
     //   Link[j].xsect.sBot = forcemain_getRoughFactor(j, lengthFactor)
     // The lengthFactor = mod_length / length (1.0 if not lengthened).
+    const bool is_force_main = (ctx.links.xsect_shape[uj] == XsectShape::FORCE_MAIN);
+    const bool is_dw = (ctx.options.routing_model == RoutingModel::DYNWAVE ||
+                        ctx.options.routing_model == RoutingModel::FV);
     if (is_dw && is_force_main) {
         double length_factor = (CD.length[ucr] > 0.0)
             ? mod_len / CD.length[ucr] : 1.0;
@@ -469,7 +1230,34 @@ static void convert_inputs_to_internal(SimulationContext& ctx,
     }
 
     const double inv_len = ucf::Ucf_inv[ucf::LENGTH][usz];
-    if (inv_len == 1.0) return;  // US units: input already in internal units.
+    if (inv_len == 1.0) {
+        // US units: lengths are already internal feet, but flow-dimension
+        // inputs are in the deck's FLOW_UNITS — a GPM or MGD deck still
+        // needs the Qcf division legacy applies to every parsed flow
+        // (link.c:352-353 `x[4]/UCF(FLOW)`, node.c divider cutoff). Skipping
+        // it left q0/q_limit/cutoff in user units: a 2.6 MGD MaxFlow acted
+        // as a 2.6 cfs cap (small-orifice: pipe held to 1.68 instead of
+        // 4.02 cfs and the whole storage drawdown diverged).
+        const double qcf_us =
+            ucf::Qcf[static_cast(ctx.options.flow_units)];
+        if (qcf_us != 1.0) {
+            for (int i = 0; i < n_nodes; ++i) {
+                if (ctx.nodes.type[static_cast(i)] !=
+                    NodeType::DIVIDER) continue;
+                const int r = ctx.node_subtypes.divider_row(i);
+                if (r >= 0)
+                    ctx.node_subtypes.dividers.cutoff[
+                        static_cast(r)] /= qcf_us;
+            }
+            for (int j = 0; j < n_links; ++j) {
+                const auto uj = static_cast(j);
+                if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+                ctx.links.q0[uj]      /= qcf_us;
+                ctx.links.q_limit[uj] /= qcf_us;
+            }
+        }
+        return;
+    }
 
     // PARITY: legacy converts metric input to internal feet by DIVIDING by the
     // forward factor (internal = display / UCF, e.g. m / 0.3048), NOT multiplying
@@ -494,6 +1282,7 @@ static void convert_inputs_to_internal(SimulationContext& ctx,
         ctx.nodes.init_depth[ui]  /= len;
         ctx.nodes.sur_depth[ui]   /= len;
         ctx.nodes.ponded_area[ui] /= len2;
+        ctx.nodes.rim_depth[ui]   /= len;   // display-only, but still a length
         if (ctx.nodes.type[ui] == NodeType::OUTFALL) {
             const int r = ctx.node_subtypes.outfall_row(i);
             if (r >= 0 && ctx.node_subtypes.outfalls.bc_type[static_cast(r)]
@@ -547,8 +1336,11 @@ static void convert_inputs_to_internal(SimulationContext& ctx,
         ctx.links.offset1[uj]      /= len;
         ctx.links.offset2[uj]      /= len;
         const int wr = ctx.link_subtypes.weir_row(j);
-        if (wr >= 0) ctx.link_subtypes.weirs.crest_height[static_cast(wr)] /= len;
-        else {
+        if (wr >= 0) {
+            ctx.link_subtypes.weirs.crest_height[static_cast(wr)] /= len;
+            // legacy link_setParams: Weir.roadWidth = x[7] / UCF(LENGTH)
+            ctx.link_subtypes.weirs.road_width[static_cast(wr)] /= len;
+        } else {
             const int olr = ctx.link_subtypes.outlet_row(j);
             if (olr >= 0) ctx.link_subtypes.outlets.crest_height[static_cast(olr)] /= len;
         }
@@ -591,7 +1383,30 @@ void convert_internal_to_display(SimulationContext& ctx) {
     }
 
     const double len = ucf::Ucf[ucf::LENGTH][usz];
-    if (len == 1.0) return;  // US units: internal already equals display.
+    if (len == 1.0) {
+        // US units: lengths are display-identical, but GPM/MGD flow fields
+        // were divided by Qcf on the way in (see convert_inputs_to_internal)
+        // and must be multiplied back for writer round-trips.
+        const double qcf_us =
+            ucf::Qcf[static_cast(ctx.options.flow_units)];
+        if (qcf_us != 1.0) {
+            for (int i = 0; i < ctx.n_nodes(); ++i) {
+                if (ctx.nodes.type[static_cast(i)] !=
+                    NodeType::DIVIDER) continue;
+                const int r = ctx.node_subtypes.divider_row(i);
+                if (r >= 0)
+                    ctx.node_subtypes.dividers.cutoff[
+                        static_cast(r)] *= qcf_us;
+            }
+            for (int j = 0; j < ctx.n_links(); ++j) {
+                const auto uj = static_cast(j);
+                if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+                ctx.links.q0[uj]      *= qcf_us;
+                ctx.links.q_limit[uj] *= qcf_us;
+            }
+        }
+        return;
+    }
 
     const double area = len * len;
     const double flow = ucf::Qcf[static_cast(ctx.options.flow_units)];
@@ -609,6 +1424,7 @@ void convert_internal_to_display(SimulationContext& ctx) {
         ctx.nodes.init_depth[ui]  *= len;
         ctx.nodes.sur_depth[ui]   *= len;
         ctx.nodes.ponded_area[ui] *= area;
+        ctx.nodes.rim_depth[ui]   *= len;   // display-only, but still a length
         if (ctx.nodes.type[ui] == NodeType::OUTFALL) {
             const int r = ctx.node_subtypes.outfall_row(i);
             if (r >= 0 && ctx.node_subtypes.outfalls.bc_type[static_cast(r)]
@@ -649,8 +1465,10 @@ void convert_internal_to_display(SimulationContext& ctx) {
         ctx.links.offset1[uj]      *= len;
         ctx.links.offset2[uj]      *= len;
         const int wr = ctx.link_subtypes.weir_row(j);
-        if (wr >= 0) ctx.link_subtypes.weirs.crest_height[static_cast(wr)] *= len;
-        else {
+        if (wr >= 0) {
+            ctx.link_subtypes.weirs.crest_height[static_cast(wr)] *= len;
+            ctx.link_subtypes.weirs.road_width[static_cast(wr)] *= len;
+        } else {
             const int olr = ctx.link_subtypes.outlet_row(j);
             if (olr >= 0) ctx.link_subtypes.outlets.crest_height[static_cast(olr)] *= len;
         }
@@ -673,6 +1491,117 @@ void convert_internal_to_display(SimulationContext& ctx) {
         ctx.subcatches.width[static_cast(s)] *= len;
 }
 
+// ============================================================================
+// convert_internal_to_authored()
+// ============================================================================
+// resolve_cross_references applies two parse-time normalisations that mutate
+// authored link data in place: (1) adverse-slope conduits are reversed under
+// DYNWAVE/FV (node1/node2, offset1/offset2, q0 sign, inlet/outlet losses;
+// direction = -1), and (2) in LINK_OFFSETS=ELEVATION mode every offset/crest
+// is rewritten as a depth above its node invert. Neither was undone by the
+// .inp writer, so Open → Save silently swapped adverse conduits and wrote
+// depths under an ELEVATION header (destroying offsets on the next open).
+// Legacy SWMM-GUI never hit this because it exports its own object model, not
+// engine state. This is the exact inverse; call it on a COPY.
+bool needs_authored_conversion(const SimulationContext& ctx) {
+    if (ctx.options.link_offsets == 1) return true;
+    for (int j = 0; j < ctx.n_links(); ++j)
+        if (ctx.links.direction[static_cast(j)] < 0) return true;
+    // A partly filled circular conduit carries its sediment bump in offset1/2
+    // (resolve_cross_references, legacy link.c:1072-1077); the file must get
+    // the authored offsets back.
+    for (int j = 0; j < ctx.n_links(); ++j) {
+        const auto uj = static_cast(j);
+        if (ctx.links.type[uj] == LinkType::CONDUIT &&
+            ctx.links.xsect_shape[uj] == XsectShape::FILLED_CIRCULAR &&
+            ctx.links.xsect_y_bot[uj] > 0.0) return true;
+    }
+    return false;
+}
+
+// Un-reverse adverse-slope conduits. Offsets/losses travel with their node, so
+// swapping both pairs keeps them aligned. Vertices were never touched by the
+// reversal and stay as authored. Safe on a live editing context: the GUI runs
+// simulations from a separately opened engine, never from the edit context.
+int restore_authored_orientation(SimulationContext& ctx) {
+    int n = 0;
+    for (int j = 0; j < ctx.n_links(); ++j) {
+        const auto uj = static_cast(j);
+        if (ctx.links.type[uj] != LinkType::CONDUIT || ctx.links.direction[uj] >= 0)
+            continue;
+        std::swap(ctx.links.node1[uj], ctx.links.node2[uj]);
+        std::swap(ctx.links.offset1[uj], ctx.links.offset2[uj]);
+        ctx.links.q0[uj] = -ctx.links.q0[uj];
+        ctx.links.direction[uj] = 1;
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        if (cr >= 0) {
+            const auto ucr = static_cast(cr);
+            std::swap(ctx.link_subtypes.conduits.loss_inlet[ucr],
+                      ctx.link_subtypes.conduits.loss_outlet[ucr]);
+            ctx.link_subtypes.conduits.slope[ucr] = -ctx.link_subtypes.conduits.slope[ucr];
+        }
+        ++n;
+    }
+    return n;
+}
+
+void convert_internal_to_authored(SimulationContext& ctx) {
+    const int n_links = ctx.n_links();
+    const int n_nodes = ctx.n_nodes();
+
+    // (1) Orientation.
+    restore_authored_orientation(ctx);
+
+    // (1b) FILLED_CIRCULAR: resolve_cross_references raised both offsets by the
+    // sediment depth yBot (legacy link.c:1072-1077) so the hydraulics see the
+    // effective invert. Restore the AUTHORED offsets before the ELEVATION step
+    // below reads them. xsect_y_bot stays in internal ft, while the offsets are
+    // in display units iff convert_internal_to_display() ran on this copy —
+    // which is exactly when the LENGTH factor is not 1 — so scaling yBot by that
+    // factor is right in both unit systems.
+    {
+        const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+        const double len = ucf::Ucf[ucf::LENGTH][static_cast(us)];
+        for (int j = 0; j < n_links; ++j) {
+            const auto uj = static_cast(j);
+            if (ctx.links.type[uj] != LinkType::CONDUIT ||
+                ctx.links.xsect_shape[uj] != XsectShape::FILLED_CIRCULAR) continue;
+            const double dz = ctx.links.xsect_y_bot[uj] * len;
+            ctx.links.offset1[uj] -= dz;
+            ctx.links.offset2[uj] -= dz;
+        }
+    }
+
+    // (2) Depth → elevation (inverse of the two ELEV_OFFSET passes above).
+    if (ctx.options.link_offsets != 1) return;
+    for (int j = 0; j < n_links; ++j) {
+        const auto uj = static_cast(j);
+        const LinkType lt = ctx.links.type[uj];
+        if (lt == LinkType::PUMP) continue;
+        const int n1 = ctx.links.node1[uj];
+        const int n2 = ctx.links.node2[uj];
+        const bool ok1 = n1 >= 0 && n1 < n_nodes;
+        const bool ok2 = n2 >= 0 && n2 < n_nodes;
+        const double inv1 = ok1 ? ctx.nodes.invert_elev[static_cast(n1)] : 0.0;
+        const double inv2 = ok2 ? ctx.nodes.invert_elev[static_cast(n2)] : 0.0;
+
+        if (lt == LinkType::CONDUIT) {
+            if (ok1) ctx.links.offset1[uj] += inv1;
+            if (ok2) ctx.links.offset2[uj] += inv2;
+        } else if (lt == LinkType::ORIFICE) {
+            if (ok1) ctx.links.offset1[uj] += inv1;
+        } else if (lt == LinkType::WEIR || lt == LinkType::OUTLET) {
+            const int wr  = ctx.link_subtypes.weir_row(j);
+            const int olr = (wr < 0) ? ctx.link_subtypes.outlet_row(j) : -1;
+            double* crest = (wr >= 0)
+                ? &ctx.link_subtypes.weirs.crest_height[static_cast(wr)]
+                : (olr >= 0 ? &ctx.link_subtypes.outlets.crest_height[static_cast(olr)]
+                            : nullptr);
+            if (crest && ok1) *crest += inv1;
+        }
+    }
+}
+
 // ============================================================================
 // validate_virtual_junctions()
 // ============================================================================
@@ -720,6 +1649,200 @@ static void validate_virtual_junctions(SimulationContext& ctx) {
     }
 }
 
+// ============================================================================
+// Inlet reference resolution + validate_inlet_junctions()
+// ============================================================================
+// Refactored engine only — see
+// plans/INLET_JUNCTION_IMPLEMENTATION_PLAN_2026-09-05.md §2.4/§4.8. Runs with
+// validate_virtual_junctions, after slope computation and adverse-slope
+// reversal, so the attachment orientation observed here is final.
+
+namespace {
+
+/// Up to two conduits attached to `node_idx`; returns how many ends touch it.
+int ij_attached_conduits(const SimulationContext& ctx, int node_idx,
+                         int& link_a, int& link_b) {
+    link_a = link_b = -1;
+    int touches = 0;
+    for (int j = 0; j < ctx.n_links(); ++j) {
+        const auto uj = static_cast(j);
+        if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+        const int ends[2] = { ctx.links.node1[uj], ctx.links.node2[uj] };
+        for (const int n : ends) {
+            if (n != node_idx) continue;
+            if      (touches == 0) link_a = j;
+            else if (touches == 1) link_b = j;
+            ++touches;
+        }
+    }
+    return touches;
+}
+
+/// Index into ctx.streets for a link carrying a STREET cross-section, else -1.
+/// The street is referenced BY NAME on the link (LinkData::pump_curve_name is
+/// the named-xsect slot — see the STREET resolution pass below), so a street
+/// re-assigned to the conduit can never desynchronise the usage row.
+int ij_street_of_link(const SimulationContext& ctx, int link_idx) {
+    if (link_idx < 0 || link_idx >= ctx.n_links()) return -1;
+    const auto uj = static_cast(link_idx);
+    if (ctx.links.xsect_shape[uj] != XsectShape::STREET_XSECT) return -1;
+    if (uj >= ctx.links.pump_curve_name.size()) return -1;
+    const std::string& sname = ctx.links.pump_curve_name[uj];
+    if (sname.empty()) return -1;
+    for (int s = 0; s < ctx.streets.count(); ++s)
+        if (ieq(ctx.streets.names[static_cast(s)], sname)) return s;
+    return -1;
+}
+
+bool ij_is_drop_design(const SimulationContext& ctx, int design_idx) {
+    if (design_idx < 0 || design_idx >= ctx.inlets.count()) return false;
+    const std::string& t = ctx.inlets.inlet_type[static_cast(design_idx)];
+    return t == "DROP_GRATE" || t == "DROP_CURB";
+}
+
+} // namespace
+
+static void resolve_inlet_references(SimulationContext& ctx) {
+    // --- CUSTOM designs: capture curve name → index + kind ---
+    for (int i = 0; i < ctx.inlets.count(); ++i) {
+        const auto ui = static_cast(i);
+        if (ctx.inlets.inlet_type[ui] != "CUSTOM") continue;
+        const int c = ctx.find_curve(ctx.inlets.curve_id[ui]);
+        if (c < 0) {
+            ctx.errors.push_back(format_error(ERR_NAME, ctx.inlets.curve_id[ui]));
+            continue;
+        }
+        const TableType tt = ctx.tables[c].type;
+        if (tt == TableType::CURVE_DIVERSION)   ctx.inlets.curve_kind[ui] = 1;
+        else if (tt == TableType::CURVE_RATING) ctx.inlets.curve_kind[ui] = 2;
+        else {
+            // Legacy drops the usage (WARN12); the curve itself is the defect,
+            // so report it against the only curve-specific parse code we have.
+            ctx.errors.push_back(format_error(ERR_CURVE_SEQUENCE, ctx.inlets.curve_id[ui],
+                                              "(a custom inlet needs a DIVERSION or RATING curve)"));
+            continue;
+        }
+        ctx.inlets.curve_index[ui] = c;
+    }
+
+    // --- Usage rows: pending names, host conduit, street, shape ---
+    for (int r = 0; r < ctx.inlet_usages.count(); ++r) {
+        const auto ur = static_cast(r);
+        auto& U = ctx.inlet_usages;
+        const int host_node = U.node_host[ur];
+
+        if (host_node >= 0) {
+            const std::string& node_name = ctx.node_names.name_of(host_node);
+            // Design name → index (625).
+            if (!U.pending_design_name[ur].empty()) {
+                int di = -1;
+                for (int i = 0; i < ctx.inlets.count(); ++i)
+                    if (ieq(ctx.inlets.names[static_cast(i)],
+                            U.pending_design_name[ur])) { di = i; break; }
+                if (di < 0)
+                    ctx.errors.push_back(format_error(ERR_IJ_DESIGN, node_name,
+                                                      "('" + U.pending_design_name[ur] + "')"));
+                U.design_index[ur] = di;
+                U.pending_design_name[ur].clear();
+            }
+            // Capture node name → index (627): must exist, differ from the
+            // host, and be a real (non-virtual) node.
+            if (!U.pending_capture_name[ur].empty()) {
+                const int ci = ctx.node_names.find(U.pending_capture_name[ur]);
+                const bool bad = (ci < 0) || (ci == host_node) ||
+                                 ctx.nodes.is_virtual[static_cast(ci)] != 0;
+                if (bad)
+                    ctx.errors.push_back(format_error(ERR_IJ_CAPTURE_NODE, node_name,
+                                                      "('" + U.pending_capture_name[ur] + "')"));
+                U.node_index[ur] = bad ? -1 : ci;
+                U.pending_capture_name[ur].clear();
+            }
+        } else if (!U.pending_capture_name[ur].empty()) {
+            // Conduit-hosted row whose capture node was a forward reference
+            // in [INLET_USAGE]: bind it now, ERR_NAME (legacy
+            // inlet_readUsageParams parity) if the node never appeared.
+            const int ci = ctx.node_names.find(U.pending_capture_name[ur]);
+            if (ci < 0)
+                ctx.errors.push_back(format_error(ERR_NAME, U.pending_capture_name[ur]));
+            U.node_index[ur] = ci;
+            U.pending_capture_name[ur].clear();
+        }
+
+        // Street geometry always comes from the host conduit's cross-section,
+        // never from the row (plan §4.8) — so it is resolved for both host
+        // kinds and stays -1 when that conduit is not a street.
+        const int host_link = (host_node >= 0)
+            ? edit::ij_host_conduit(ctx, /*host_kind=*/1, host_node)
+            : U.link_index[ur];
+        U.street_index[ur] = ij_street_of_link(ctx, host_link);
+
+        // Shape compatibility, LINK-hosted rows only. Legacy simply drops an
+        // incompatible conduit usage with WARNING 12 rather than refusing the
+        // model, so this is a warning and the row is disarmed by clearing its
+        // design. A node-hosted row keeps its design: an inlet junction has a
+        // dedicated rule (623) which validate_inlet_junctions below reports,
+        // and disarming the row here would mask it behind 633.
+        if (host_node < 0 && U.design_index[ur] >= 0 &&
+            !edit::ij_usage_shape_ok(ctx, U.design_index[ur], host_link)) {
+            const std::string host = (host_link >= 0)
+                ? ("Link " + ctx.link_names.name_of(host_link))
+                : std::string("an unknown host");
+            ctx.warnings.push_back(format_error(
+                ERR_INLET_USAGE_SHAPE,
+                ctx.inlets.names[static_cast(U.design_index[ur])],
+                "(" + host + "; the inlet is ignored)"));
+            U.design_index[ur] = -1;
+        }
+    }
+}
+
+static void validate_inlet_junctions(SimulationContext& ctx) {
+    const int n_nodes = ctx.nodes.count();
+    for (int i = 0; i < n_nodes; ++i) {
+        const auto ui = static_cast(i);
+        if (ui >= ctx.nodes.is_inlet.size() || !ctx.nodes.is_inlet[ui]) continue;
+        const std::string& name = ctx.node_names.name_of(i);
+
+        // Rule 619 (the virtual-junction routing rule) admits FV because the
+        // FV mesh splices a virtual junction out at construction; an inlet
+        // junction cannot be spliced out — its capture sink needs the node —
+        // so under FV it is refused here. KINWAVE/STEADY already fail 619 in
+        // validate_virtual_junctions.
+        if (ctx.options.routing_model == RoutingModel::FV) {
+            ctx.errors.push_back(format_error(ERR_VJ_ROUTING_MODEL, name,
+                "(an inlet junction needs DYNWAVE: the finite-volume mesh splices "
+                "virtual junctions out and would drop the inlet)"));
+            continue;
+        }
+
+        // Rule 633: the node must own a usage row. The virtual-junction rules
+        // (609/611/613/617/619) already ran for this node in
+        // validate_virtual_junctions — is_inlet implies is_virtual.
+        const int row = ctx.inlet_usages.find_by_node_host(i);
+        if (row < 0 || ctx.inlet_usages.design_index[static_cast(row)] < 0) {
+            ctx.errors.push_back(format_error(ERR_IJ_NO_USAGE, name));
+            continue;
+        }
+
+        int j1 = -1, j2 = -1;
+        if (ij_attached_conduits(ctx, i, j1, j2) != 2) continue;  // 609 already reported
+
+        // Rule 623: both conduits carry the street section the inlet needs.
+        const int design = ctx.inlet_usages.design_index[static_cast(row)];
+        if (!edit::ij_usage_shape_ok(ctx, design, j1) ||
+            !edit::ij_usage_shape_ok(ctx, design, j2))
+            ctx.errors.push_back(format_error(ERR_IJ_NOT_STREET, name,
+                ij_is_drop_design(ctx, design)
+                    ? "(a drop inlet needs RECT_OPEN or TRAPEZOIDAL conduits)"
+                    : ""));
+
+        // Rule 629: no conduit-attribute inlet on the same pair (double capture).
+        if (ctx.inlet_usages.find_by_link(j1) >= 0 ||
+            ctx.inlet_usages.find_by_link(j2) >= 0)
+            ctx.errors.push_back(format_error(ERR_IJ_USAGE_ON_PAIR, name));
+    }
+}
+
 void resolve_cross_references(SimulationContext& ctx) {
     // -------------------------------------------------------------------------
     // Final counts → allocate SoA arrays to exact size
@@ -806,40 +1929,61 @@ void resolve_cross_references(SimulationContext& ctx) {
     // -------------------------------------------------------------------------
     // Timeseries with FILE references (e.g., rainfall .dat files) need to be
     // loaded into memory before any date offset or gage resolution.
-    load_external_timeseries_files(ctx, inp_dir);
-
-    // -------------------------------------------------------------------------
-    // Load external FILE-source rain-gage data (standard SWMM rain files).
-    // Must run after resolve_external_file_slots (for absolute paths) and after
-    // options parsing (needs the simulation window to bound retained records).
-    // -------------------------------------------------------------------------
-    load_external_rain_files(ctx);
+    const auto _pt_extfiles0 = perf::now();
+    {
+        // One parse-once cache shared by BOTH external-file loaders: a
+        // multi-column file referenced by any number of timeseries and rain
+        // gages is read from disk exactly once per resolve pass (plan
+        // MULTICOLUMN_SERIES_SINGLE_READ_2026-08-17 §5). Freed at the end of
+        // this scope — every consumer has copied its column into its own
+        // x/y arrays by then.
+        MultiColumnFileCache series_file_cache;
+        load_external_timeseries_files(ctx, inp_dir, series_file_cache);
+
+        // ---------------------------------------------------------------------
+        // Load external FILE-source rain-gage data (standard SWMM rain files).
+        // Must run after resolve_external_file_slots (for absolute paths) and
+        // after options parsing (needs the simulation window to bound retained
+        // records).
+        // ---------------------------------------------------------------------
+        load_external_rain_files_impl(ctx, series_file_cache);
+    }
+    perf::sec_res_extfiles += perf::since(_pt_extfiles0);
 
     // -------------------------------------------------------------------------
     // Timeseries date offset resolution
     // -------------------------------------------------------------------------
-    // Timeseries without explicit dates have x-values starting near 0 (fractional
-    // days from midnight). These are relative to the simulation start date.
-    // Offset them by start_date so absolute OADate lookups work.
+    // Rows authored without a date are elapsed times anchored at the
+    // simulation start (legacy input.c:170 seeds every series' lastDate with
+    // StartDate + StartTime before parsing). The parser stored those rows
+    // relative to 0 and counted them in Table::n_relative; add start_date to
+    // exactly those rows here so absolute OADate lookups work. Rows past
+    // n_relative carry explicit dates and must NOT move — the old x[0] < 366
+    // heuristic shifted a whole mixed series, pushing its dated rows ~107
+    // years out. rel_anchor records the offset currently baked in, which
+    // makes a re-resolve idempotent and re-anchors by the delta if
+    // START_DATE was edited between resolves.
     for (std::size_t t = 0; t < ctx.tables.tables.size(); ++t) {
         auto& tbl = ctx.tables.tables[t];
         if (tbl.type != TableType::TIMESERIES) continue;
-        if (tbl.x.empty()) continue;
-
-        // If first x-value is small (< 366, i.e. less than one year in days),
-        // it's a relative timeseries and needs the start_date offset.
-        // Absolute dates (with MM/DD/YYYY) would produce values > 30000.
-        if (tbl.x[0] < 366.0) {
-            double offset = ctx.options.start_date;
-            for (auto& xv : tbl.x) {
-                xv += offset;
-            }
-        }
+        if (tbl.n_relative <= 0) continue;
+
+        const double start = ctx.options.start_date;
+        const double delta = start - tbl.rel_anchor;
+        if (delta == 0.0) continue;
+        const std::size_t n = std::min(tbl.x.size(),
+                                       static_cast(tbl.n_relative));
+        for (std::size_t k = 0; k < n; ++k) tbl.x[k] += delta;
+        tbl.rel_anchor = start;
     }
 
     // -------------------------------------------------------------------------
     // Gage timeseries re-resolution
     // -------------------------------------------------------------------------
+    // Start of the name-binding region: gage/co-gage, subcatchment outlet and
+    // gage, storage and outfall and pump curves, external-inflow series. These
+    // are the find_timeseries/find_curve callers.
+    const auto _pt_tables0 = perf::now();
     // If RAINGAGES section appeared before TIMESERIES, ts_index will be -1.
     // Re-resolve using the stored ts_name.
     for (int g = 0; g < n_gages; ++g) {
@@ -851,28 +1995,6 @@ void resolve_cross_references(SimulationContext& ctx) {
         }
     }
 
-    // -------------------------------------------------------------------------
-    // Gap #53: Co-gage detection
-    // -------------------------------------------------------------------------
-    // When two or more gages share the same TIMESERIES source and ts_index, the
-    // secondary gages should copy rainfall from the primary (lowest-index gage)
-    // rather than querying the timeseries independently.  Matches legacy coGage.
-    for (int gj = 0; gj < n_gages; ++gj) {
-        auto ugj = static_cast(gj);
-        ctx.gages.co_gage_index[ugj] = -1;
-        if (ctx.gages.source[ugj] != RainSource::TIMESERIES) continue;
-        int ts_j = ctx.gages.ts_index[ugj];
-        if (ts_j < 0) continue;
-        for (int gi = 0; gi < gj; ++gi) {
-            auto ugi = static_cast(gi);
-            if (ctx.gages.source[ugi] == RainSource::TIMESERIES &&
-                ctx.gages.ts_index[ugi] == ts_j) {
-                ctx.gages.co_gage_index[ugj] = gi;
-                break;
-            }
-        }
-    }
-
     // -------------------------------------------------------------------------
     // Subcatchment outlet re-resolution
     // -------------------------------------------------------------------------
@@ -884,6 +2006,17 @@ void resolve_cross_references(SimulationContext& ctx) {
         const auto& name = ctx.subcatches.outlet_name[us];
         if (name.empty()) continue;
 
+        // Legacy subcatch_validate (subcatch.c:391-393): an outlet name that
+        // matches BOTH a node and a subcatchment is ambiguous — ERROR 108.
+        // Legacy stores the two resolutions independently and errors when
+        // both landed; here the single-slot model must check explicitly.
+        if (ctx.node_names.find(name) >= 0 &&
+            ctx.subcatch_names.find(name) >= 0) {
+            ctx.errors.push_back(format_error(
+                ERR_SUBCATCH_OUTLET, ctx.subcatch_names.name_of(s)));
+            continue;
+        }
+
         // Already resolved during parsing — validate it
         if (ctx.subcatches.outlet_node[us] >= 0 &&
             ctx.subcatches.outlet_node[us] < n_nodes) {
@@ -913,6 +2046,23 @@ void resolve_cross_references(SimulationContext& ctx) {
         }
     }
 
+    // -------------------------------------------------------------------------
+    // Subcatchment groundwater receiving-node re-resolution
+    // -------------------------------------------------------------------------
+    // [GROUNDWATER] normally precedes [JUNCTIONS], so handle_groundwater()
+    // resolved the node against an empty name index and stored -1. The raw name
+    // was captured in ctx.pending_gw_nodes for exactly this pass. A name that
+    // still fails to resolve is left at -1: the runtime falls back to the
+    // subcatchment outlet node (Groundwater.cpp), and the [GROUNDWATER] writer
+    // skips the row rather than emitting '*'.
+    for (const auto& [si, nm] : ctx.pending_gw_nodes) {
+        if (si < 0 || si >= n_subcatch) continue;
+        auto us = static_cast(si);
+        if (us < ctx.subcatches.gw_node.size() && ctx.subcatches.gw_node[us] < 0)
+            ctx.subcatches.gw_node[us] = ctx.node_names.find(nm);
+    }
+    ctx.pending_gw_nodes.clear();
+
     // -------------------------------------------------------------------------
     // Subcatchment snow pack resolution
     // -------------------------------------------------------------------------
@@ -926,6 +2076,16 @@ void resolve_cross_references(SimulationContext& ctx) {
         if (name.empty()) continue;
         if (ctx.subcatches.snowpack[us] >= 0) continue;  // already resolved
         ctx.subcatches.snowpack[us] = ctx.snowpack_names.find(name);
+        if (ctx.subcatches.snowpack[us] < 0)
+            // Dangling reference: legacy resolves the pack while reading the
+            // row (subcatch.c:171-174, project_findObject(SNOWMELT, tok[8]))
+            // and raises fatal ERROR 209 when it is absent — the parser has
+            // already excluded the "*" placeholder, so a stored name is
+            // always a real reference. Falling through left the subcatchment
+            // with no pack and no diagnostic: it simply never accumulated
+            // snow, and a deck legacy refuses ran to completion. Mirrors the
+            // IRREGULAR transect and CUSTOM curve checks.
+            ctx.errors.push_back(format_error(ERR_NAME, name));
     }
 
     // -------------------------------------------------------------------------
@@ -956,6 +2116,43 @@ void resolve_cross_references(SimulationContext& ctx) {
         }
     }
 
+    // -------------------------------------------------------------------------
+    // Gap #53: Co-gage detection (legacy gage_validate)
+    // -------------------------------------------------------------------------
+    // A gage sharing a TIMESERIES with an earlier gage copies that gage's
+    // rainfall instead of reading the series itself — but only among USED
+    // gages (one some subcatchment or [HYDROGRAPHS] group reads): legacy
+    // gage_validate returns at once for an unused gage and skips unused
+    // candidates for the primary. An unused primary never advances its
+    // state (gage_setState returns for it), so a used gage pointed at one
+    // would read a frozen rainfall (132-nodes-96-subs: RAINGAGE-3, unused,
+    // shares EXTREME with RAINGAGE-5, which every subcatchment reads).
+    // Placed after the subcatchment gage re-resolution above so the usage
+    // test sees resolved indices.
+    {
+        std::vector used(static_cast(n_gages), 0);
+        for (int s2 = 0; s2 < n_subcatch; ++s2) {
+            const int gi = ctx.subcatches.gage[static_cast(s2)];
+            if (gi >= 0 && gi < n_gages) used[static_cast(gi)] = 1;
+        }
+        for (const auto& gname : ctx.unit_hyds.gage_names) {
+            const int gi = ctx.gage_names.find(gname);
+            if (gi >= 0 && gi < n_gages) used[static_cast(gi)] = 1;
+        }
+        std::unordered_map first_on_ts;   // ts index -> first USED gage
+        first_on_ts.reserve(static_cast(n_gages));
+        for (int gj = 0; gj < n_gages; ++gj) {
+            auto ugj = static_cast(gj);
+            ctx.gages.co_gage_index[ugj] = -1;
+            if (!used[ugj]) continue;
+            if (ctx.gages.source[ugj] != RainSource::TIMESERIES) continue;
+            const int ts_j = ctx.gages.ts_index[ugj];
+            if (ts_j < 0) continue;
+            const auto ins = first_on_ts.emplace(ts_j, gj);
+            if (!ins.second) ctx.gages.co_gage_index[ugj] = ins.first->second;
+        }
+    }
+
     // -------------------------------------------------------------------------
     // Storage curve name resolution
     // -------------------------------------------------------------------------
@@ -1047,6 +2244,22 @@ void resolve_cross_references(SimulationContext& ctx) {
             ctx.errors.push_back(format_error(ERR_NAME, ctx.links.pump_curve_name[uj]));
     }
 
+    // Weir discharge-coefficient curve (legacy Weir.cdCurve, the [WEIRS]
+    // line's 13th column) — same name slot, resolved into WeirData.cd_curve.
+    for (int j = 0; j < n_links; ++j) {
+        auto uj = static_cast(j);
+        if (ctx.links.type[uj] != LinkType::WEIR) continue;
+        const int wr = ctx.link_subtypes.weir_row(j);
+        if (wr < 0) continue;
+        const auto uwr = static_cast(wr);
+        if (ctx.link_subtypes.weirs.cd_curve[uwr] >= 0) continue; // already resolved
+        if (ctx.links.pump_curve_name[uj].empty() ||
+            ctx.links.pump_curve_name[uj] == "*") continue;
+        ctx.link_subtypes.weirs.cd_curve[uwr] = ctx.find_curve(ctx.links.pump_curve_name[uj]);
+        if (ctx.link_subtypes.weirs.cd_curve[uwr] < 0)
+            ctx.errors.push_back(format_error(ERR_NAME, ctx.links.pump_curve_name[uj]));
+    }
+
     // Convert pump startup/shutoff depths from display units → internal (ft)
     {
         int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
@@ -1081,19 +2294,11 @@ void resolve_cross_references(SimulationContext& ctx) {
         ctx.nodes.depth[i] = ctx.nodes.init_depth[i];
     }
 
-    // -------------------------------------------------------------------------
-    // External inflow timeseries resolution
-    // -------------------------------------------------------------------------
-    // Resolve timeseries name → table index for all external inflows
-    for (int i = 0; i < ctx.ext_inflows.count(); ++i) {
-        auto ui = static_cast(i);
-        if (!ctx.ext_inflows.ts_name[ui].empty()) {
-            int ts_idx = ctx.find_timeseries(ctx.ext_inflows.ts_name[ui]);
-            // Store resolved index - the inflow solver uses ts_name for lookup,
-            // but we can cache the index for performance
-            (void)ts_idx; // ts_name is used directly by InflowSolver
-        }
-    }
+    // No external-inflow timeseries resolution here: ExtInflowData carries no
+    // index field, only ts_name, and InflowSolver::init resolves the name
+    // itself (hydrology/Inflow.cpp). This used to run find_timeseries() once
+    // per external inflow and discard the result.
+    perf::sec_res_tables += perf::since(_pt_tables0);
 
     // -------------------------------------------------------------------------
     // [INFLOWS] / [DWF] / [RDII] node re-resolution
@@ -1128,6 +2333,202 @@ void resolve_cross_references(SimulationContext& ctx) {
                           ctx.rdii_assigns.node_name);
     }
 
+    // -------------------------------------------------------------------------
+    // [INITIAL_QUALITY] element + constituent resolution
+    // -------------------------------------------------------------------------
+    // The section may precede the node/link/pollutant sections, so the handler
+    // stored raw names; resolve and classify here. Every failure is loud
+    // (fatal on strict open) and the failing row is erased so downstream
+    // consumers never see an unresolved entry. Iterate backwards so erase()
+    // keeps remaining indices valid.
+    {
+        auto& iq = ctx.initial_quality;
+
+        // U2: `[INITIAL_QUALITY] FILE ` — append the sidecar's rows
+        // (scope,element,constituent,value; comma or whitespace separated;
+        // a header line whose value column is not numeric is skipped) so
+        // they resolve below exactly like inline rows. Rows previously
+        // loaded from the file are dropped first (re-resolve is idempotent).
+        for (int i = iq.count() - 1; i >= 0; --i)
+            if (static_cast(i) < iq.from_file.size() &&
+                iq.from_file[static_cast(i)])
+                iq.erase(i);
+        if (!iq.file.empty()) {
+            const std::string dir  = openswmm::io::parentDir(ctx.inp_file_path);
+            const std::string path = openswmm::io::resolveRelative(iq.file, dir);
+            std::ifstream in(openswmm::io::utf8_path(path));
+            if (!in.is_open()) {
+                ctx.errors.push_back("[INITIAL_QUALITY] FILE '" + iq.file +
+                                     "' not found or unreadable (" + path + ").");
+            } else {
+                std::string line;
+                int lineno = 0;
+                while (std::getline(in, line)) {
+                    ++lineno;
+                    for (char& ch : line) if (ch == ',' || ch == ';' || ch == '\t') ch = ' ';
+                    auto tok = Tokenizer::tokenize(line);
+                    if (tok.empty()) continue;
+                    if (tok.size() < 4) {
+                        ctx.errors.push_back("[INITIAL_QUALITY] FILE '" + iq.file +
+                                             "' line " + std::to_string(lineno) +
+                                             ": needs scope element constituent value.");
+                        continue;
+                    }
+                    const std::string scope = Tokenizer::to_upper(tok[0]);
+                    double v = 0.0;
+                    const bool numeric =
+                        openswmm::from_chars_double(tok[3].data(),
+                                                    tok[3].data() + tok[3].size(), v)
+                            .ec == std::errc{};
+                    if (!numeric) {
+                        if (lineno == 1) continue;   // header
+                        ctx.errors.push_back("[INITIAL_QUALITY] FILE '" + iq.file +
+                                             "' line " + std::to_string(lineno) +
+                                             ": bad value '" + tok[3] + "'.");
+                        continue;
+                    }
+                    if (scope != "NODE" && scope != "LINK") {
+                        ctx.errors.push_back("[INITIAL_QUALITY] FILE '" + iq.file +
+                                             "' line " + std::to_string(lineno) +
+                                             ": scope must be NODE or LINK.");
+                        continue;
+                    }
+                    iq.add(scope == "LINK", tok[1], tok[2], v, -1,
+                           InitialQualityData::kKindUnresolved, /*fromFile*/ true);
+                }
+            }
+        }
+
+        for (int i = iq.count() - 1; i >= 0; --i) {
+            auto ui = static_cast(i);
+            const bool  link = iq.is_link[ui] != 0;
+            const auto& en   = iq.elem_name[ui];
+            const auto& cons = iq.constituent[ui];
+
+            // Element name → index.
+            iq.elem_idx[ui] = link ? ctx.link_names.find(en)
+                                   : ctx.node_names.find(en);
+            if (iq.elem_idx[ui] < 0) {
+                ctx.errors.push_back(
+                    std::string("[INITIAL_QUALITY] unknown ") +
+                    (link ? "link" : "node") + " '" + en + "'.");
+                iq.erase(i);
+                continue;
+            }
+
+            // Constituent → kind. Pollutant first, then the reserved species.
+            if (cons == "__WATER_AGE__") {
+                iq.kind[ui] = InitialQualityData::kKindWaterAge;
+                if (!ctx.options.water_age)
+                    ctx.warnings.push_back(
+                        "[INITIAL_QUALITY] __WATER_AGE__ rows are present but "
+                        "[OPTIONS] WATER_AGE is OFF — the rows are inert this "
+                        "simulation.");
+            } else if (cons == "__TEMPERATURE__") {
+                iq.kind[ui] = InitialQualityData::kKindTemperature;
+                if (!ctx.options.heat_transport)
+                    ctx.warnings.push_back(
+                        "[INITIAL_QUALITY] __TEMPERATURE__ rows are present "
+                        "but [OPTIONS] HEAT_TRANSPORT is OFF — the rows are "
+                        "inert this simulation.");
+            } else {
+                iq.kind[ui] = ctx.pollutant_names.find(cons);
+                // U2 (2026-09-07): an MSX species of the reactions component
+                // is accepted here on the same footing as a pollutant — the
+                // one species resolver (SpeciesRegistry) knows both. The
+                // row is mirrored into ReactionData::init_elem_* below, the
+                // table every quality engine seeds from; [REACTION_QUALITY]
+                // NODE|LINK in the .rxn remains a read alias.
+                //
+                // An MSX kind is ENCODED NEGATIVE (kKindMsxFirst - m), so
+                // "did it resolve" cannot be spelled `kind >= 0` here.
+                bool resolved = iq.kind[ui] >= 0;
+                if (!resolved && ctx.reactions.configured) {
+                    const int m = ctx.reactions.find_species(cons);
+                    if (m >= 0) {
+                        iq.kind[ui] = InitialQualityData::msxKind(m);
+                        resolved = true;
+                    }
+                }
+                if (!resolved) {
+                    ctx.errors.push_back(
+                        "[INITIAL_QUALITY] unknown constituent '" + cons +
+                        "' at " + std::string(link ? "link" : "node") + " '" +
+                        en + "' — [POLLUTANTS] names, reactions-component "
+                        "species and __WATER_AGE__/__TEMPERATURE__ are "
+                        "accepted here.");
+                    iq.erase(i);
+                    continue;
+                }
+                // Age (signed per D-NS1) and temperature (degC) may be
+                // negative; a pollutant or species concentration may not.
+                if (iq.value[ui] < 0.0) {
+                    ctx.errors.push_back(
+                        "[INITIAL_QUALITY] negative value for '" +
+                        cons + "' at " + std::string(link ? "link" : "node") +
+                        " '" + en + "'.");
+                    iq.erase(i);
+                    continue;
+                }
+            }
+        }
+
+        // Duplicate (scope, element, constituent) keys are an error, not
+        // last-wins — silent override order in a hand-edited deck is exactly
+        // the ambiguity this section should refuse. Forward scan so the
+        // SECOND occurrence is the one reported.
+        for (int i = 0; i < iq.count(); ++i) {
+            auto ui = static_cast(i);
+            for (int j = 0; j < i; ++j) {
+                auto uj = static_cast(j);
+                if (iq.is_link[ui] == iq.is_link[uj] &&
+                    iq.elem_idx[ui] == iq.elem_idx[uj] &&
+                    iq.kind[ui] == iq.kind[uj]) {
+                    ctx.errors.push_back(
+                        "[INITIAL_QUALITY] duplicate row for '" +
+                        iq.constituent[ui] + "' at " +
+                        std::string(iq.is_link[ui] ? "link" : "node") + " '" +
+                        iq.elem_name[ui] + "'.");
+                    iq.erase(i);
+                    --i;
+                    break;
+                }
+            }
+        }
+
+        // U2: mirror the MSX rows into the reactions component's
+        // per-element seed table (refusing a row the .rxn already carries).
+        if (ctx.reactions.configured) {
+            const auto errs = transport::mirrorInitialQualityMsxRows(ctx);
+            for (const auto& e : errs) ctx.errors.push_back(e);
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Link end-node re-resolution
+    // -------------------------------------------------------------------------
+    // Legacy parsing is order-independent, so [CONDUITS]/[PUMPS]/[ORIFICES]/
+    // [WEIRS]/[OUTLETS] may precede the node sections. The handlers resolve
+    // eagerly (yielding -1) and record the raw names in ctx.pending_link_nodes;
+    // re-resolve them here. A name that still fails to resolve is a fatal
+    // ERR_NAME, matching legacy link_readParams(). Previously such a link was
+    // loaded silently orphaned and then written back out with '*' end nodes.
+    // Runs before any consumer of links.node1/node2 further down this function.
+    {
+        auto resolve_end = [&ctx, n_nodes](int& idx, const std::string& name) {
+            if (idx >= 0 && idx < n_nodes) return;
+            idx = ctx.node_names.find(name);
+            if (idx < 0) ctx.errors.push_back(format_error(ERR_NAME, name));
+        };
+        for (const auto& [li, names] : ctx.pending_link_nodes) {
+            if (li < 0 || li >= ctx.links.count()) continue;
+            auto ul = static_cast(li);
+            resolve_end(ctx.links.node1[ul], names.first);
+            resolve_end(ctx.links.node2[ul], names.second);
+        }
+        ctx.pending_link_nodes.clear();
+    }
+
     // -------------------------------------------------------------------------
     // Quality data matrix sizing
     // -------------------------------------------------------------------------
@@ -1196,22 +2597,140 @@ void resolve_cross_references(SimulationContext& ctx) {
     // matching legacy flowrout.c::validateGeneralLayout.
 
     // -------------------------------------------------------------------------
-    // Evaporation timeseries resolution
+    // Virtual-junction initial-state seeding (issue #156)
     // -------------------------------------------------------------------------
-    if (ctx.options.evap_type == 2 && !ctx.options.evap_ts_name.empty()) {
-        int ts_idx = ctx.find_timeseries(ctx.options.evap_ts_name);
-        (void)ts_idx; // stored by name, resolved at runtime
+    // [VIRTUAL_JUNCTIONS] carries no init-depth column, so VJs started dry
+    // regardless of their neighbors — a deck whose real nodes define an
+    // initial pool began with a hole at every splice (found by the mixed-flow
+    // study P0 verification: a station VJ drained the Aureli initial pool).
+    // Seed each VJ head by distance-weighted linear interpolation between the
+    // nearest NON-virtual nodes reached by walking its spliced conduit chain
+    // in both directions. Runs before the solver initializes; decks without
+    // VJs (or with all-dry neighbors) are bitwise untouched.
+    //
+    // DYNWAVE ONLY, and that restriction is measured, not cautionary. Under FV
+    // the initial condition does not live in the node state: Router::initFv
+    // lays each conduit's cells at a UNIFORM DEPTH taken from links.depth (the
+    // average of the two end-node depths), and only overrides that where one
+    // bank is dry across a bed step. Seeding the node alone therefore starts
+    // the run with a VJ head that its own adjacent cells contradict, and the
+    // junction coupling drives the difference: measured on the study's e3
+    // deck (a pressurized 0.094 m pipe, FV_SLOT_CELERITY 300), the flow-
+    // routing continuity error went 0.000% -> -19.133% and VJ99's head
+    // excursion reached 4371 m. Making FV benefit needs the level-surface
+    // both-wet cell projection that Router::initFv deliberately does not do
+    // (see the comment block there, and the P0 verification's open issue 2);
+    // that is its own change with its own gates, so FV is left exactly as it
+    // was rather than half-seeded.
+    if (ctx.options.routing_model == RoutingModel::DYNWAVE) {
+        // Incident CONDUITS per node (VJ splices are conduit-only by
+        // validation; a VJ with conduit-degree != 2 is left unseeded here and
+        // rejected later by the mesh builder / DW vjunc validation).
+        std::vector> inc(static_cast(n_nodes),
+                                            {-1, -1});
+        std::vector inc_n(static_cast(n_nodes), 0);
+        for (int j = 0; j < n_links; ++j) {
+            auto uj = static_cast(j);
+            if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
+            for (int nd : {ctx.links.node1[uj], ctx.links.node2[uj]}) {
+                if (nd < 0 || nd >= n_nodes) continue;
+                auto und = static_cast(nd);
+                if (ctx.nodes.is_virtual[und] == 0) continue;
+                if (inc_n[und] < 2) inc[und][inc_n[und]] = j;
+                ++inc_n[und];
+            }
+        }
+        auto walk = [&](int start_vj, int via_link, double& head_out,
+                        double& dist_out, bool& wet_out) -> bool {
+            int node = start_vj, link = via_link;
+            double dist = 0.0;
+            for (int guard = 0; guard <= n_links; ++guard) {
+                auto ul = static_cast(link);
+                const int cr = ctx.link_subtypes.conduit_row(link);
+                dist += (cr >= 0)
+                    ? ctx.link_subtypes.conduits.length[static_cast(cr)]
+                    : 0.0;
+                const int other = (ctx.links.node1[ul] == node)
+                    ? ctx.links.node2[ul] : ctx.links.node1[ul];
+                if (other < 0 || other >= n_nodes) return false;
+                auto uo = static_cast(other);
+                if (ctx.nodes.is_virtual[uo] == 0) {
+                    head_out = ctx.nodes.head[uo];
+                    dist_out = dist;
+                    wet_out  = ctx.nodes.depth[uo] > 0.0;
+                    return true;
+                }
+                if (inc_n[uo] != 2) return false;
+                link = (inc[uo][0] == link) ? inc[uo][1] : inc[uo][0];
+                if (link < 0) return false;
+                node = other;
+            }
+            return false;  // cycle of VJs (rejected elsewhere)
+        };
+        for (int i = 0; i < n_nodes; ++i) {
+            auto ui = static_cast(i);
+            if (ctx.nodes.is_virtual[ui] == 0 || inc_n[ui] != 2) continue;
+            double hA = 0.0, dA = 0.0, hB = 0.0, dB = 0.0;
+            bool wetA = false, wetB = false;
+            const bool okA = walk(i, inc[ui][0], hA, dA, wetA);
+            const bool okB = walk(i, inc[ui][1], hB, dB, wetB);
+            // A dry node's head is just its invert — interpolating between two
+            // dry endpoints with differing inverts would MANUFACTURE water on a
+            // dry deck (P1 verification finding: vj_fv_invert_collision seeded
+            // 1 ft from nothing). Seeding requires at least one WET endpoint.
+            if (!(okA && wetA) && !(okB && wetB)) continue;
+            double head;
+            if (okA && okB) {
+                const double dt_sum = dA + dB;
+                head = (dt_sum > 0.0) ? (hA * dB + hB * dA) / dt_sum
+                                      : 0.5 * (hA + hB);
+            } else if (okA) {
+                head = hA;
+            } else if (okB) {
+                head = hB;
+            } else {
+                continue;
+            }
+            const double depth = head - ctx.nodes.invert_elev[ui];
+            if (depth > 0.0) {
+                // init_depth is the field that SURVIVES: SWMMEngine::initialize
+                // calls NodeData::reset_state(), which re-derives depth,
+                // old_depth and head from init_depth on every cold start. A
+                // seeding that wrote only depth/head was visible to a caller
+                // that just opened the model and gone by the first routing
+                // step — measured on the study's e4 deck, where base and
+                // seeded binaries produced byte-identical .out files.
+                ctx.nodes.init_depth[ui] = depth;
+                ctx.nodes.depth[ui]      = depth;
+                ctx.nodes.head[ui]       = head;
+            }
+        }
     }
 
     // -------------------------------------------------------------------------
-    // Link cross-section derived properties
+    // Evaporation timeseries resolution
+    // -------------------------------------------------------------------------
+    // Nothing to do: SWMMEngine::initHydrology resolves evap_ts_name into
+    // climate_state.evap_ts_index. The lookup that used to sit here discarded
+    // its result.
+
     // -------------------------------------------------------------------------
+    // Link cross-section derived properties
     // -------------------------------------------------------------------------
+        // -------------------------------------------------------------------------
     // Non-conduit link offset conversion (ELEVATION → DEPTH)
     // -------------------------------------------------------------------------
     // The conduit pass below skips non-conduit links (length==0). We need a
     // separate pass for pumps, orifices, weirs, outlets.
-    if (ctx.options.link_offsets == 1) { // ELEV_OFFSET
+    //
+    // A GeoPackage already holds RESOLVED offsets — it is the engine's
+    // canonical internal store, which is why convert_inputs_to_internal is
+    // skipped for it too (see the gpkg_units_internal gate below). Running the
+    // ELEVATION pass over values that are already depths subtracted the node
+    // invert a SECOND time, and the negative result clamped to zero: every
+    // link offset in an ELEVATION-mode model collapsed to its node invert on
+    // the first .gpkg round trip.
+    if (ctx.options.link_offsets == 1 && !ctx.gpkg_units_internal) { // ELEV_OFFSET
         for (int j = 0; j < n_links; ++j) {
             auto uj = static_cast(j);
             auto lt = ctx.links.type[uj];
@@ -1222,10 +2741,10 @@ void resolve_cross_references(SimulationContext& ctx) {
             if (lt == LinkType::ORIFICE) {
                 // [ORIFICES] offset1 = absolute invert elevation → convert to depth above n1
                 if (n1 >= 0 && n1 < n_nodes) {
-                    double raw1 = ctx.links.offset1[uj] - ctx.nodes.invert_elev[static_cast(n1)];
-                    if (raw1 < 0.0)
-                        ctx.warnings.push_back(format_warning(WARN_NEGATIVE_OFFSET, ctx.link_names.name_of(j)));
-                    ctx.links.offset1[uj] = std::max(0.0, raw1);
+                    ctx.links.offset1[uj] = legacyOffsetHeight(
+                        ctx.links.offset1[uj],
+                        ctx.nodes.invert_elev[static_cast(n1)],
+                        ctx, ctx.link_names.name_of(j));
                 }
             } else if (lt == LinkType::WEIR || lt == LinkType::OUTLET) {
                 // [WEIRS]/[OUTLETS]: crest_height = absolute crest elevation →
@@ -1237,11 +2756,64 @@ void resolve_cross_references(SimulationContext& ctx) {
                     : (olr >= 0 ? &ctx.link_subtypes.outlets.crest_height[static_cast(olr)]
                                 : nullptr);
                 if (crest && n1 >= 0 && n1 < n_nodes) {
-                    double rawCrest = *crest - ctx.nodes.invert_elev[static_cast(n1)];
-                    *crest = std::max(0.0, rawCrest);
+                    const double rawCrest = *crest;
+                    *crest = legacyOffsetHeight(
+                        rawCrest, ctx.nodes.invert_elev[static_cast(n1)],
+                        ctx, ctx.link_names.name_of(j));
                 }
             }
         }
+    } else {
+        // DEPTH mode. Legacy zeroes a negative authored offset in each link
+        // type's OWN validator, and the validators do not agree with each
+        // other:
+        //   CONDUIT  conduit_validate (link.c:1061-1070): offset1 AND
+        //            offset2, each with WARNING 03 (800-node-sewer: legacy
+        //            WARN03 on conduit 136687's -0.01 inOffset).
+        //   ORIFICE  orifice_validate (link.c:1719): offset1 only, SILENTLY.
+        //   WEIR     weir_validate (link.c:2188): offset1 only, SILENTLY.
+        //   OUTLET   nothing — a negative outlet crest is kept as authored
+        //            (it still passes through the WARNING-10 raise below).
+        //   PUMP     has no offsets.
+        // A regulator's offset2 is NEVER zeroed: link_setParams mirrors the
+        // authored value into it (link.c:366-391) and its one reader is the
+        // node crown-elevation pass, which legacy runs on the RAW value — an
+        // orifice authored with a large negative offset contributes a crown
+        // far BELOW its node and never raises the EXTRAN surcharge
+        // threshold. v6 zeroed both ends of every link (and warned each
+        // time), which lifted ST2337's crown in
+        // subcatchments-no-infiltration from legacy's 1.75 ft (conduit
+        // 334.1's crown) to 2.0 ft (the zeroed orifice INLET's), so legacy
+        // switched that junction to the surcharged dqdh depth update one
+        // step before v6 did — bit-exact for 776 report periods, then a
+        // permanent 0.1 % flow bias. The ELEV branch above is different and
+        // untouched: there link_getOffsetHeight converts and clamps every
+        // end, warning included, before the validators run.
+        for (int j = 0; j < n_links; ++j) {
+            auto uj = static_cast(j);
+            const auto lt = ctx.links.type[uj];
+            if (lt == LinkType::CONDUIT) {
+                if (ctx.links.offset1[uj] < 0.0) {
+                    ctx.warnings.push_back(format_warning(
+                        WARN_NEGATIVE_OFFSET, ctx.link_names.name_of(j)));
+                    ctx.links.offset1[uj] = 0.0;
+                }
+                if (ctx.links.offset2[uj] < 0.0) {
+                    ctx.warnings.push_back(format_warning(
+                        WARN_NEGATIVE_OFFSET, ctx.link_names.name_of(j)));
+                    ctx.links.offset2[uj] = 0.0;
+                }
+            } else if (lt == LinkType::WEIR) {
+                // A weir's WORKING crest is the side-table copy, zeroed next
+                // to the WARNING-10 raise below, AFTER the authored value is
+                // mirrored into offset2 — legacy's order (link_setParams
+                // mirror -> validator zero -> raise). links.offset1 is not
+                // read for weirs past this point; keep it on the value the
+                // old path left there.
+                if (ctx.links.offset1[uj] < 0.0)
+                    ctx.links.offset1[uj] = 0.0;
+            }
+        }
     }
 
     // -------------------------------------------------------------------------
@@ -1278,6 +2850,33 @@ void resolve_cross_references(SimulationContext& ctx) {
 
         double inv1 = ctx.nodes.invert_elev[static_cast(n1)];
         double inv2 = ctx.nodes.invert_elev[static_cast(n2)];
+        // legacy Link.offset2 of a regulator: link_setParams copies the
+        // AUTHORED offset1 into it and link_convertOffsets keeps them equal,
+        // but NOTHING later touches it — not the validators' silent negative
+        // zeroing and not the raise below, which touch offset1 only.
+        // link_setOutfallDepth reads offset2 (the un-raised crest) as `z`
+        // for a downstream outfall (kept for outfall::legacyOffset:
+        // dividers-in-dynamic-wave's outlet Under5, crest 0, raised 0.25 m
+        // to its FREE outfall's invert, gave the outfall a 0.25 m depth and
+        // ran 2 L/s backwards for the run), and the node crown-elevation
+        // pass reads it RAW — an orifice authored with a large negative
+        // offset contributes a crown far BELOW its node and never raises
+        // the EXTRAN surcharge threshold. Mirroring the post-zeroing value
+        // instead lifted ST2337's crown in subcatchments-no-infiltration
+        // from legacy's 1.75 ft (conduit 334.1's crown) to 2.0 ft (the
+        // zeroed orifice INLET's), so legacy switched that junction to the
+        // surcharged dqdh depth update one step before v6 did — bit-exact
+        // for 776 report periods, then a permanent 0.1 % flow bias. So:
+        // mirror FIRST (authored value), zero SECOND, raise LAST. In ELEV
+        // mode *off is already the converted height, clamped non-negative
+        // by legacyOffsetHeight, so the mirror matches link_convertOffsets
+        // and the zeroing below never fires.
+        ctx.links.offset2[uj] = *off;
+        // orifice_validate (link.c:1719) / weir_validate (link.c:2188): a
+        // negative crest is zeroed SILENTLY. Outlets have no such check —
+        // a negative outlet crest stays authored and goes into the raise.
+        if ((lt == LinkType::ORIFICE || lt == LinkType::WEIR) && *off < 0.0)
+            *off = 0.0;
         if (inv1 + *off < inv2) {
             if (ctx.options.routing_model == RoutingModel::DYNWAVE ||
                 ctx.options.routing_model == RoutingModel::FV) {
@@ -1290,59 +2889,52 @@ void resolve_cross_references(SimulationContext& ctx) {
     // Build transect geometry tables for IRREGULAR cross-sections.
     // Each TransectStore entry → TransectData with precomputed area/width/hrad tables.
     {
+        perf::ScopedTimer _pt_transects(perf::sec_res_transects);
         int nt = ctx.transects.count();
         ctx.transect_tables.resize(static_cast(nt));
+        // Copy-transform-build extracted to transect::buildFromStore so
+        // swmm_link_set_xsect (IRREGULAR) builds bit-identical tables; the
+        // parity notes on the legacy transforms live with the helper.
+        const int t_us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+        const double t_ucf = ucf::Ucf[ucf::LENGTH][static_cast(t_us)];
         for (int t = 0; t < nt; ++t) {
             auto ut = static_cast(t);
             auto& td = ctx.transect_tables[ut];
-            td.name      = ctx.transects.names[ut];
-            td.n_left    = ctx.transects.n_left[ut];
-            td.n_right   = ctx.transects.n_right[ut];
-            td.n_channel = ctx.transects.n_channel[ut];
-            if (td.n_channel <= 0.0) {
+            if (!transect::buildFromStore(ctx.transects, t, t_ucf, td)) {
                 ctx.errors.push_back(format_error(ERR_TRANSECT_MANNING, td.name));
                 continue;
             }
-            td.stations  = ctx.transects.stations[ut];
-            td.elevations = ctx.transects.elevations[ut];
-            td.length_factor = ctx.transects.length_factor[ut];
-            // PARITY: legacy transect setParams/addStation (transect.c:360-410)
-            // transform the raw [TRANSECTS] GR data BEFORE building the tables:
-            //   Station = x * Xfactor / UCF(LENGTH)          (mult, then divide)
-            //   Elev    = (y + Yfactor) / UCF(LENGTH),  Yfactor = x9 / UCF
-            //   Xbank   = (xbank / UCF) * Xfactor            (divide, then mult)
-            // The elevation OFFSET (x9, e.g. 799/798 in extran8a) is the load-
-            // bearing part: legacy builds every slice area/width/hrad at the
-            // real bed elevation (~800 ft), so `y - yhi` rounds at that
-            // magnitude. Building on the raw ~0-ft elevations rounds
-            // differently (~1e-13 per entry) and breaks bit-parity even though
-            // the geometry is offset-invariant in exact arithmetic. Applied to
-            // the td COPY only, so [TRANSECTS] round-trips the raw GR values.
-            const int t_us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
-            const double t_ucf = ucf::Ucf[ucf::LENGTH][static_cast(t_us)];
-            double xFactor = ctx.transects.x_factor[ut];      // parse-time 0→1 default
-            if (xFactor == 0.0) xFactor = 1.0;
-            const double yFactor = ctx.transects.y_factor[ut] / t_ucf;   // x9 / UCF
-            for (auto& s : td.stations)   s = s * xFactor / t_ucf;
-            for (auto& e : td.elevations) e = (e + yFactor) / t_ucf;
-            td.x_left_bank  = (ctx.transects.x_left_bank[ut]  / t_ucf) * xFactor;
-            td.x_right_bank = (ctx.transects.x_right_bank[ut] / t_ucf) * xFactor;
-            transect::buildTables(td);
-        }
-        // Resolve IRREGULAR link transect names → indices, then set properties
+        }
+        // Resolve IRREGULAR link transect names → indices, then set properties.
+        // The name→index map replaces a linear ieq scan per IRREGULAR link.
+        // emplace keeps the FIRST index for a duplicated name, which is what
+        // the scan returned (it broke at its first hit).
+        std::unordered_map transect_by_name;
+        transect_by_name.reserve(static_cast(nt));
+        for (int t = 0; t < nt; ++t)
+            transect_by_name.emplace(ctx.transects.names[static_cast(t)], t);
+
         for (int j = 0; j < n_links; ++j) {
             auto uj = static_cast(j);
             if (ctx.links.xsect_shape[uj] != XsectShape::IRREGULAR) continue;
             // Resolve transect name (stored in pump_curve_name as temp field)
             const auto& tname = ctx.links.pump_curve_name[uj];
             if (!tname.empty()) {
-                for (int t = 0; t < nt; ++t) {
-                    if (ieq(ctx.transects.names[static_cast(t)],
-                            tname)) {
-                        ctx.links.xsect_curve[uj] = t;
-                        break;
-                    }
-                }
+                const auto hit = transect_by_name.find(tname);
+                if (hit != transect_by_name.end())
+                    ctx.links.xsect_curve[uj] = hit->second;
+                else if (ctx.links.xsect_curve[uj] < 0)
+                    // Dangling reference: legacy raises fatal ERROR 209 here
+                    // (transect_validate). Leaving it silent let the link
+                    // degenerate to zero area with no diagnostic — the state a
+                    // corrupted save produced. Lenient opens still load for
+                    // repair; strict opens must fail loudly.
+                    ctx.errors.push_back(format_error(ERR_NAME, tname));
+            } else if (ctx.links.xsect_curve[uj] < 0) {
+                // No name and no resolved index: an IRREGULAR link with no
+                // transect at all is as dead as a dangling one.
+                ctx.errors.push_back(
+                    format_error(ERR_NAME, ctx.link_names.name_of(j)));
             }
             int ci = ctx.links.xsect_curve[uj];
             if (ci >= 0 && ci < nt) {
@@ -1360,10 +2952,21 @@ void resolve_cross_references(SimulationContext& ctx) {
         }
     }
 
+    // Per-link named cross-section resolution (CUSTOM shape curves, then
+    // STREET) followed by the full-flow xsect parameter loop. This is the
+    // region the per-link linear scans and per-link TransectData builds live
+    // in — see plan items 1.3 and 1.4.
+    const auto _pt_xsect0 = perf::now();
+
     // Resolve CUSTOM shape curves — these use [CURVES] Shape type entries
     // that define normalized (depth/yFull, width/wMax) relationships.
     {
         int n_tables = static_cast(ctx.tables.tables.size());
+        // A CUSTOM table is fully determined by (shape curve, y_full): every
+        // link sharing both gets a byte-identical ~1.2 KB TransectData. Build
+        // one per distinct pair instead of one per link. Exact double equality
+        // is the right test here — identical inputs, identical tabulation.
+        std::map, int> custom_memo;
         for (int j = 0; j < n_links; ++j) {
             auto uj = static_cast(j);
             if (ctx.links.xsect_shape[uj] != XsectShape::CUSTOM) continue;
@@ -1384,6 +2987,21 @@ void resolve_cross_references(SimulationContext& ctx) {
                 double y_full = ctx.links.xsect_y_full[uj];
                 if (y_full <= 0.0 || tbl.x.size() < 2) continue;
 
+                // Already built for this (curve, y_full)? Point at it and skip
+                // the tabulation entirely.
+                {
+                    const auto memo = custom_memo.find({ci, y_full});
+                    if (memo != custom_memo.end()) {
+                        const auto& shared = ctx.transect_tables[
+                            static_cast(memo->second)];
+                        ctx.links.xsect_a_full[uj] = shared.a_full;
+                        ctx.links.xsect_r_full[uj] = shared.r_full;
+                        ctx.links.xsect_w_max[uj]  = shared.w_max;
+                        ctx.links.xsect_curve[uj]  = memo->second;
+                        continue;
+                    }
+                }
+
                 // Find max width from curve (typically at y_norm ~0.5)
                 double w_max_norm = 0.0;
                 for (std::size_t i = 0; i < tbl.y.size(); ++i) {
@@ -1420,6 +3038,17 @@ void resolve_cross_references(SimulationContext& ctx) {
                 int custom_idx = static_cast(ctx.transect_tables.size());
                 ctx.transect_tables.push_back(std::move(ctd));
                 ctx.links.xsect_curve[uj] = custom_idx;
+                custom_memo.emplace(std::pair{ci, y_full}, custom_idx);
+            } else {
+                // Dangling reference: legacy resolves the shape curve while
+                // reading the row (link.c:229, project_findObject(CURVE,
+                // tok[3])) and raises fatal ERROR 209 when it is absent. v6 has
+                // to defer the lookup, because [CURVES] may be parsed after
+                // [XSECTIONS], but deferring is not the same as forgiving:
+                // falling through left the link with no shape table at all, so
+                // it ran at zero area with no diagnostic. Mirrors the IRREGULAR
+                // transect check above.
+                ctx.errors.push_back(format_error(ERR_NAME, cname));
             }
         }
     }
@@ -1431,6 +3060,23 @@ void resolve_cross_references(SimulationContext& ctx) {
     {
         const int us = ucf::getUnitSystem(static_cast(ctx.options.flow_units));
         const double inv_len = ucf::Ucf_inv[ucf::LENGTH][static_cast(us)];
+        // StreetParams derives entirely from the street index (inv_len is
+        // constant across links), so every link on a street produces the same
+        // ~1.2 KB table. N links over S streets used to allocate and tabulate
+        // N of them; now it is S. TransectData::name is write-only for these
+        // entries — nothing reads it back — so sharing one is safe even when
+        // two links spell the street name with different case.
+        std::unordered_map street_memo;
+        // Same treatment as transects: one map instead of a linear ieq scan
+        // per STREET link, first index wins on a duplicated name. Also hoists
+        // the ctx.streets.count() that the old inner loop re-read every pass.
+        std::unordered_map street_by_name;
+        {
+            const int n_streets = ctx.streets.count();
+            street_by_name.reserve(static_cast(n_streets));
+            for (int s = 0; s < n_streets; ++s)
+                street_by_name.emplace(ctx.streets.names[static_cast(s)], s);
+        }
         for (int j = 0; j < n_links; ++j) {
             auto uj = static_cast(j);
             if (ctx.links.xsect_shape[uj] != XsectShape::STREET_XSECT) continue;
@@ -1438,15 +3084,24 @@ void resolve_cross_references(SimulationContext& ctx) {
             if (sname.empty()) continue;
 
             int si = -1;
-            for (int s = 0; s < ctx.streets.count(); ++s) {
-                if (ieq(ctx.streets.names[static_cast(s)], sname)) {
-                    si = s;
-                    break;
-                }
-            }
+            if (const auto hit = street_by_name.find(sname);
+                hit != street_by_name.end())
+                si = hit->second;
             if (si < 0) continue;
             auto su = static_cast(si);
 
+            if (const auto memo = street_memo.find(si);
+                memo != street_memo.end()) {
+                const auto& shared = ctx.transect_tables[
+                    static_cast(memo->second)];
+                ctx.links.xsect_curve[uj]  = memo->second;
+                ctx.links.xsect_y_full[uj] = shared.y_full;
+                ctx.links.xsect_a_full[uj] = shared.a_full;
+                ctx.links.xsect_r_full[uj] = shared.r_full;
+                ctx.links.xsect_w_max[uj]  = shared.w_max;
+                continue;
+            }
+
             street::StreetParams sp;
             sp.width             = ctx.streets.t_crown[su]       * inv_len;
             sp.curb_height       = ctx.streets.h_curb[su]        * inv_len;
@@ -1465,6 +3120,7 @@ void resolve_cross_references(SimulationContext& ctx) {
 
             int idx_tbl = static_cast(ctx.transect_tables.size());
             ctx.transect_tables.push_back(std::move(td));
+            street_memo.emplace(si, idx_tbl);
             const auto& built = ctx.transect_tables[static_cast(idx_tbl)];
             ctx.links.xsect_curve[uj]  = idx_tbl;
             ctx.links.xsect_y_full[uj] = built.y_full;
@@ -1593,7 +3249,34 @@ void resolve_cross_references(SimulationContext& ctx) {
                 ctx.links.xsect_a_bot[uj] = xs.a_bot;
                 ctx.links.xsect_s_bot[uj] = xs.s_bot;
                 ctx.links.xsect_r_bot[uj] = xs.r_bot;
+                // legacy conduit_validate (link.c:1037): a Darcy-Weisbach
+                // force main's Geom2 is a roughness HEIGHT in inches (mm on
+                // an SI deck) and is brought to feet here — the equivalent
+                // Manning n and every per-step friction factor read it as
+                // feet. It stayed in inches, so the D-W force-main decks
+                // (extran1-forcemain-dw, routing-force-main-dw,
+                // force-main-reynolds, user1/user4-force-main-dw) ran with a
+                // 12x roughness height. The H-W C-factor is unitless.
+                if (shape == XsectShape::FORCE_MAIN &&
+                    ctx.options.force_main_eqn ==
+                        static_cast(forcemain::FrictionModel::DARCY_WEISBACH)) {
+                    ctx.links.xsect_r_bot[uj] /=
+                        ucf::Ucf[ucf::RAINDEPTH][static_cast(us)];
+                }
             } else {
+                if (rc != 0) {
+                    // setParams has answered "I cannot build a section from
+                    // this" — the same verdict legacy's xsect_setParams returns
+                    // as FALSE, and legacy refuses the deck on it
+                    // (link.c:250, ERROR 211 naming an empty token). v6 computed
+                    // the verdict and then threw it away, falling through to the
+                    // rectangular fallback below: a MODBASKETHANDLE with a top
+                    // width of 0, which has no geometry at all, ran as a
+                    // rectangle. rc is what must be tested, not this branch —
+                    // DUMMY reaches it with rc == 0, because setParams leaves a
+                    // dummy's fields to the caller.
+                    ctx.errors.push_back(format_error(ERR_NUMBER, ""));
+                }
                 // Invalid geometry — preserve the previous generic fallback.
                 a_full = w_max * y_full;
                 double p_def = 2.0 * y_full + w_max;
@@ -1615,6 +3298,8 @@ void resolve_cross_references(SimulationContext& ctx) {
         ctx.links.xsect_yw_max[uj] = yw_max;
     }
 
+    perf::sec_res_xsect += perf::since(_pt_xsect0);
+
     // -------------------------------------------------------------------------
     // Conduit slope computation (matches legacy conduit_getSlope in link.c)
     // -------------------------------------------------------------------------
@@ -1622,27 +3307,56 @@ void resolve_cross_references(SimulationContext& ctx) {
         auto uj = static_cast(j);
         if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
 
+        // Legacy conduit_validate (link.c:1072-1077): a partly filled circular
+        // section raises BOTH invert offsets by the sediment depth yBot before
+        // the slope, so every consumer of offset1/offset2 (z1/z2, the outfall
+        // z, crown extension, DRY/critical classification) sees the effective
+        // invert. The slope itself is unaffected (both ends move equally). The
+        // C API (link::filledCircularOffsetBump) and the writers' inverse
+        // (convert_internal_to_authored, GeoPackageWriter) rely on the bump
+        // being present on EVERY resolved filled conduit, so a lenient-opened
+        // conduit with a dangling node or zero length — skipped by the guards
+        // below — is bumped on its way out of the loop too. Internal ft.
+        auto bump_filled = [&]() {
+            if (ctx.links.xsect_shape[uj] == XsectShape::FILLED_CIRCULAR) {
+                ctx.links.offset1[uj] += ctx.links.xsect_y_bot[uj];
+                ctx.links.offset2[uj] += ctx.links.xsect_y_bot[uj];
+            }
+        };
+
         int n1 = ctx.links.node1[uj];
         int n2 = ctx.links.node2[uj];
-        if (n1 < 0 || n2 < 0) continue;
+        if (n1 < 0 || n2 < 0) { bump_filled(); continue; }
 
         const int cr = ctx.link_subtypes.conduit_row(j);  // ≥0 (CONDUIT)
         const auto ucr = static_cast(cr);
+        // legacy conduit_getSlope (link.c:1269) measures the drop over
+        // conduit_getLength(j) — the flood-plain length for an IRREGULAR
+        // section, which is 1/lengthFactor times the authored main-channel
+        // number. 337-nodes' transects carry Lfactor 0.93, so every one of
+        // its natural channels ran a 7 % steep slope and conveyed 3.6 % too
+        // much. The zero-length guard stays on the AUTHORED length, which is
+        // what legacy's ERR_LENGTH check reads.
         double length = (cr >= 0) ? ctx.link_subtypes.conduits.length[ucr] : 0.0;
-        if (length <= 0.0) continue;
-
-        // Convert elevation offsets if ELEV_OFFSET mode
-        if (ctx.options.link_offsets == 1) { // ELEV_OFFSET
-            double raw1 = ctx.links.offset1[uj] - ctx.nodes.invert_elev[n1];
-            double raw2 = ctx.links.offset2[uj] - ctx.nodes.invert_elev[n2];
-            if (raw1 < 0.0)
-                ctx.warnings.push_back(format_warning(WARN_NEGATIVE_OFFSET, ctx.link_names.name_of(j)));
-            if (raw2 < 0.0)
-                ctx.warnings.push_back(format_warning(WARN_NEGATIVE_OFFSET, ctx.link_names.name_of(j)));
-            ctx.links.offset1[uj] = std::max(0.0, raw1);
-            ctx.links.offset2[uj] = std::max(0.0, raw2);
+        if (length <= 0.0) { bump_filled(); continue; }
+        length = conduit_true_length(ctx, j);
+        if (length <= 0.0) { bump_filled(); continue; }
+
+        // Convert elevation offsets if ELEV_OFFSET mode. Skipped for a
+        // GeoPackage, whose offsets are already resolved depths — see the
+        // non-conduit pass above for what the double subtraction did.
+        if (ctx.options.link_offsets == 1 && !ctx.gpkg_units_internal) { // ELEV_OFFSET
+            const std::string& lname = ctx.link_names.name_of(j);
+            ctx.links.offset1[uj] = legacyOffsetHeight(
+                ctx.links.offset1[uj], ctx.nodes.invert_elev[n1], ctx, lname);
+            ctx.links.offset2[uj] = legacyOffsetHeight(
+                ctx.links.offset2[uj], ctx.nodes.invert_elev[n2], ctx, lname);
         }
 
+        // FILLED_CIRCULAR sediment bump — after the negative-offset clamp and
+        // before the slope, as in legacy; see bump_filled above.
+        bump_filled();
+
         double elev1 = ctx.links.offset1[uj] + ctx.nodes.invert_elev[n1];
         double elev2 = ctx.links.offset2[uj] + ctx.nodes.invert_elev[n2];
         double delta = std::fabs(elev1 - elev2);
@@ -1664,15 +3378,28 @@ void resolve_cross_references(SimulationContext& ctx) {
             slope = delta / std::sqrt(length * length - delta * delta);
         }
 
-        // Apply minimum slope (legacy WARNING 05)
-        if (ctx.options.min_slope > 0.0 && slope < ctx.options.min_slope) {
-            slope = ctx.options.min_slope;
+        // Apply minimum slope (legacy WARNING 05). Legacy conduit_getSlope
+        // (link.c:1291-1298) RETURNS the positive MinSlope for SF/KW routing
+        // before the adverse-sign flip — a sub-MinSlope adverse conduit is
+        // sanitized to a positive slope under those models.
+        // MIN_SLOPE is written in PERCENT (legacy project.c:737 `MinSlope
+        // /= 100.0` at read; the option keeps the percent here so the
+        // writers echo it): a deck's `MIN_SLOPE 0.1` is a slope of 0.001.
+        // Applied as 0.1 it clamped force-main-reynolds' 0.03 conduits to
+        // 0.1 and put the normal-flow limit (beta) 10x high.
+        const double min_slope = ctx.options.min_slope / 100.0;
+        bool min_slope_kw_sf = false;
+        if (min_slope > 0.0 && slope < min_slope) {
+            slope = min_slope;
             ctx.warnings.push_back(
                 format_warning(WARN_MIN_SLOPE, ctx.link_names.name_of(j)));
+            min_slope_kw_sf =
+                (ctx.options.routing_model == RoutingModel::STEADY ||
+                 ctx.options.routing_model == RoutingModel::KINWAVE);
         }
 
         // Negative slope for adverse gradient
-        if (elev1 < elev2) slope = -slope;
+        if (elev1 < elev2 && !min_slope_kw_sf) slope = -slope;
 
         if (cr >= 0) ctx.link_subtypes.conduits.slope[ucr] = slope;
 
@@ -1716,46 +3443,134 @@ void resolve_cross_references(SimulationContext& ctx) {
     // -------------------------------------------------------------------------
     validate_virtual_junctions(ctx);
 
+    // -------------------------------------------------------------------------
+    // Inlet references (deferred [INLET_JUNCTIONS] names, street index, custom
+    // curves, shape compatibility) then the inlet-junction rules 623/629/633
+    // -------------------------------------------------------------------------
+    resolve_inlet_references(ctx);
+    validate_inlet_junctions(ctx);
+
+    // -------------------------------------------------------------------------
+    // Table sequence check (legacy project_validate -> table_validate): every
+    // curve and time series must have STRICTLY increasing x. Legacy flags
+    // dx <= 0 (a backward OR duplicate abscissa) as ERR_*_SEQUENCE. v6 defines
+    // validate_table() but never wired it in, and it additionally applies
+    // v6-only empty/NaN/column checks that legacy's table_validate does not, so
+    // mirror ONLY legacy's monotonicity test here to avoid rejecting inputs
+    // legacy accepts. File-backed tables stream their data (in-memory x is
+    // empty) and are skipped; their boundaries are validated on load.
+    // -------------------------------------------------------------------------
+    for (const auto& tbl : ctx.tables.tables) {
+        const bool is_ts = (tbl.type == TableType::TIMESERIES);
+        for (std::size_t k = 1; k < tbl.x.size(); ++k) {
+            if (tbl.x[k] - tbl.x[k - 1] <= 0.0) {
+                ctx.errors.push_back(format_error(
+                    is_ts ? ERR_TIMESERIES_SEQUENCE : ERR_CURVE_SEQUENCE, tbl.id));
+                break;
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Rain-file station conflict (legacy rain.c rainFileConflict): a file-based
+    // rain gage whose station ID matches an EARLIER file-based gage's station ID
+    // but reads a DIFFERENT file is ambiguous — the shared station cannot pick
+    // one file — so legacy rejects the later gage with ERR_RAIN_FILE_CONFLICT
+    // (156). v6 normalizes a '*' station to empty; comparing the stored station
+    // IDs reproduces legacy's equal-staID test for the common all-'*' case.
+    // -------------------------------------------------------------------------
+    for (int i = 0; i < ctx.gages.count(); ++i) {
+        const auto ui = static_cast(i);
+        if (ctx.gages.source[ui] != RainSource::FILE_RAIN) continue;
+        for (int j = 0; j < i; ++j) {
+            const auto uj = static_cast(j);
+            if (ctx.gages.source[uj] != RainSource::FILE_RAIN) continue;
+            if (ieq(ctx.gages.station_id[ui], ctx.gages.station_id[uj]) &&
+                !ieq(ctx.gages.file_path[ui].original,
+                     ctx.gages.file_path[uj].original)) {
+                ctx.errors.push_back(format_error(ERR_RAIN_FILE_CONFLICT,
+                                                  ctx.gage_names.name_of(i)));
+                break;
+            }
+        }
+    }
+
     // -------------------------------------------------------------------------
     // Node fullDepth adjustment from connected link crowns
     // (matches legacy link_validate → node fullDepth adjustment)
     // -------------------------------------------------------------------------
-    std::vector warned_depth(static_cast(n_nodes), false);
+    // Legacy stashes the AUTHORED depth (project.c:244, oldDepth = fullDepth)
+    // before validation, then node_validate (node.c:212-215) warns only when the
+    // crown raised it AND the authored depth was non-zero. The scope of the
+    // adjustment and the gate on the warning are independent: an outfall with
+    // no authored depth is still extended, it just does not warn.
+    std::vector authored_full_depth(ctx.nodes.full_depth.begin(),
+                                            ctx.nodes.full_depth.end());
+
+    // Extend a node's full depth to a connected link's crown.
+    // Legacy link_validate (link.c:446-466): every node EXCEPT a storage node
+    // with no surcharge depth. Virtual junctions are a v6 concept and stay
+    // excluded — their full depth is exact by construction.
+    auto extend_to_crown = [&](int n, double crown) {
+        if (n < 0 || n >= n_nodes) return;
+        auto un = static_cast(n);
+        if (ctx.nodes.is_virtual[un]) return;
+        if (ctx.nodes.type[un] == NodeType::STORAGE && !(ctx.nodes.sur_depth[un] > 0.0))
+            return;
+        if (crown <= ctx.nodes.full_depth[un]) return;
+        ctx.nodes.full_depth[un] = crown;
+    };
+
     for (int j = 0; j < n_links; ++j) {
         auto uj = static_cast(j);
-        if (ctx.links.type[uj] != LinkType::CONDUIT) continue;
 
-        double y_full = ctx.links.xsect_y_full[uj];
-        int n1 = ctx.links.node1[uj];
-        int n2 = ctx.links.node2[uj];
+        // Legacy skips pumps and bottom orifices outright.
+        if (ctx.links.type[uj] == LinkType::PUMP) continue;
+        if (ctx.links.type[uj] == LinkType::ORIFICE) {
+            const int orr = ctx.link_subtypes.orifice_row(j);
+            // orifice_type: 0 = BOTTOM, 1 = SIDE (legacy param1)
+            if (orr >= 0 &&
+                ctx.link_subtypes.orifices.orifice_type[static_cast(orr)] == 0.0)
+                continue;
+        }
 
-        // Upstream node: crown = offset1 + y_full (JUNCTION only, matches legacy Warning 02;
-        // virtual junctions skipped — their full depth is exact by construction)
-        if (n1 >= 0 && n1 < n_nodes &&
-            ctx.nodes.type[static_cast(n1)] == NodeType::JUNCTION &&
-            !ctx.nodes.is_virtual[static_cast(n1)]) {
-            double crown = ctx.links.offset1[uj] + y_full;
-            if (crown > ctx.nodes.full_depth[n1]) {
-                ctx.nodes.full_depth[n1] = crown;
-                if (!warned_depth[static_cast(n1)]) {
-                    ctx.warnings.push_back(format_warning(WARN_MAX_DEPTH_INCREASED, ctx.node_names.name_of(n1)));
-                    warned_depth[static_cast(n1)] = true;
-                }
-            }
+        double y_full = ctx.links.xsect_y_full[uj];
+        // legacy xsect.yFull of a DUMMY section (outlet, DUMMY conduit) is
+        // TINY, not 0 (xsect_setParams(DUMMY)); a pump's is 0.
+        if (ctx.links.type[uj] == LinkType::OUTLET ||
+            (ctx.links.type[uj] == LinkType::CONDUIT &&
+             ctx.links.xsect_shape[uj] == XsectShape::DUMMY))
+            y_full = constants::TINY;
+
+        // legacy Link.offset1: a conduit's / orifice's offset1, a weir's or
+        // outlet's crest (side tables here; already WARNING-10 raised, as
+        // legacy's is at this point of link_validate). links.offset1 is 0
+        // for a weir / outlet, so 2-weirs-4subs' junction 24-IN kept its
+        // 5 ft rim where legacy raised it to the road weir's 7.21 ft crown
+        // and it ponded 2.2 ft too early.
+        double off1 = ctx.links.offset1[uj];
+        if (ctx.links.type[uj] == LinkType::WEIR) {
+            const int wr = ctx.link_subtypes.weir_row(j);
+            if (wr >= 0) off1 = ctx.link_subtypes.weirs.crest_height[static_cast(wr)];
+        } else if (ctx.links.type[uj] == LinkType::OUTLET) {
+            const int olr = ctx.link_subtypes.outlet_row(j);
+            if (olr >= 0) off1 = ctx.link_subtypes.outlets.crest_height[static_cast(olr)];
         }
-        // Downstream node: crown = offset2 + y_full (JUNCTION only, matches legacy Warning 02;
-        // virtual junctions skipped — their full depth is exact by construction)
-        if (n2 >= 0 && n2 < n_nodes &&
-            ctx.nodes.type[static_cast(n2)] == NodeType::JUNCTION &&
-            !ctx.nodes.is_virtual[static_cast(n2)]) {
-            double crown = ctx.links.offset2[uj] + y_full;
-            if (crown > ctx.nodes.full_depth[n2]) {
-                ctx.nodes.full_depth[n2] = crown;
-                if (!warned_depth[static_cast(n2)]) {
-                    ctx.warnings.push_back(format_warning(WARN_MAX_DEPTH_INCREASED, ctx.node_names.name_of(n2)));
-                    warned_depth[static_cast(n2)] = true;
-                }
-            }
+
+        // Upstream node: every non-pump, non-bottom-orifice link contributes.
+        extend_to_crown(ctx.links.node1[uj], off1 + y_full);
+
+        // Downstream node: conduits only.
+        if (ctx.links.type[uj] == LinkType::CONDUIT)
+            extend_to_crown(ctx.links.node2[uj], ctx.links.offset2[uj] + y_full);
+    }
+
+    for (int n = 0; n < n_nodes; ++n) {
+        auto un = static_cast(n);
+        if (ctx.nodes.full_depth[un] > authored_full_depth[un] &&
+            authored_full_depth[un] > 0.0) {
+            ctx.warnings.push_back(
+                format_warning(WARN_MAX_DEPTH_INCREASED, ctx.node_names.name_of(n)));
         }
     }
 
@@ -1821,7 +3636,10 @@ void resolve_cross_references(SimulationContext& ctx) {
     // -------------------------------------------------------------------------
     // Release excess vector capacity accumulated during parsing
     // -------------------------------------------------------------------------
-    ctx.shrink_all_to_fit();
+    {
+        perf::ScopedTimer _pt(perf::sec_res_shrink);
+        ctx.shrink_all_to_fit();
+    }
 
     // Relational refactor (Phase 4): the side-table rows were populated directly
     // by the parse/resolution writers above; this only re-derives the base→row
diff --git a/src/engine/input/PostParseResolver.hpp b/src/engine/input/PostParseResolver.hpp
index f4309b96d..f779f2072 100644
--- a/src/engine/input/PostParseResolver.hpp
+++ b/src/engine/input/PostParseResolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PostParseResolver.hpp
  * @brief Post-parse cross-reference resolution for the input system.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_POST_PARSE_RESOLVER_HPP
@@ -44,6 +60,21 @@ namespace openswmm::input {
  */
 void resolve_cross_references(SimulationContext& ctx);
 
+/**
+ * @brief (Re)load every FILE-source rain gage's data from disk.
+ *
+ * @details Runs as part of resolve_cross_references() during open(). Exposed
+ *          separately so an editing host can pick up a changed file path,
+ *          station, or units without reopening the model — nothing else
+ *          re-runs it, so `swmm_file_path_set` on a rain gage would otherwise
+ *          have no effect until the next open and callers would silently keep
+ *          reading the previous file's data.
+ *
+ *          Rebuilds `ctx.gages.rain_series` and the rainfall-file summary
+ *          statistics, windowed to the current [OPTIONS] simulation dates.
+ */
+void load_external_rain_files(SimulationContext& ctx);
+
 /**
  * @brief Convert the input fields the reader scaled to internal units back to
  *        display units (matching @c ctx.options.flow_units).
@@ -66,6 +97,34 @@ void resolve_cross_references(SimulationContext& ctx);
  */
 void convert_internal_to_display(SimulationContext& ctx);
 
+/**
+ * @brief True when the context holds parse-time normalisations that the .inp
+ *        writer must undo: LINK_OFFSETS=ELEVATION (offsets stored as depths)
+ *        or any conduit reversed for adverse slope (direction == -1).
+ */
+bool needs_authored_conversion(const SimulationContext& ctx);
+
+/**
+ * @brief Undo the parse-time adverse-slope reversal on every conduit with
+ *        direction == -1 (node1/node2, offset1/offset2, q0 sign, inlet/outlet
+ *        losses, slope sign) and reset direction to +1.
+ * @returns Number of conduits restored.
+ */
+int restore_authored_orientation(SimulationContext& ctx);
+
+/**
+ * @brief Restore authored link data for writing: un-reverse adverse-slope
+ *        conduits (node1/node2, offset1/offset2, q0 sign, inlet/outlet losses)
+ *        and, in ELEVATION offset mode, re-add each node's invert to the
+ *        depth-normalised offsets and weir/outlet crests.
+ *
+ * @details Exact inverse of the reversal and ELEV_OFFSET passes inside
+ *          @ref resolve_cross_references. Operate on a copy — the live engine
+ *          state must keep its canonical (depth, positive-slope) form.
+ *          Vertices are untouched (the reversal never reorders them).
+ */
+void convert_internal_to_authored(SimulationContext& ctx);
+
 /**
  * @brief Slice IO-3: Resolve every external-file slot's `.original` token
  *        against an anchor directory and populate `.absolute`.
@@ -116,6 +175,40 @@ void resolve_external_file_slots(SimulationContext& ctx,
  */
 void recompute_conduit_flow_properties(SimulationContext& ctx, int j);
 
+/**
+ * @brief The Manning's n a conduit actually routes with, before any Courant
+ *        lengthening adjustment — legacy conduit_validate's @c roughness.
+ *
+ * @details Starts from the [CONDUITS] value and applies, in legacy's order:
+ *          an IRREGULAR conduit takes its transect's main-channel n
+ *          (link.c:1024); a force main under dynamic-wave routing takes its
+ *          equivalent Manning n (link.c:1093-1096); an IRREGULAR conduit is
+ *          then scaled by the square root of its transect's meander length
+ *          factor (link.c:1101-1105). The stored @c roughness is never
+ *          overwritten — it is the authored value the writers persist.
+ *
+ * @return The effective n, or 0 for a non-conduit / missing conduit row.
+ */
+double conduit_manning_n(const SimulationContext& ctx, int j);
+
+/**
+ * @brief The length a conduit actually routes with — legacy
+ *        @c conduit_getLength (link.c:1198-1216).
+ *
+ * @details For every section but IRREGULAR this is the authored [CONDUITS]
+ *          length. For an IRREGULAR one the authored number is the MAIN
+ *          CHANNEL's length (what a FEMA study reports) while the routing
+ *          length is the whole flood plain's, @c length / @c
+ *          Transect.lengthFactor. The slope, the Courant lengthening ratio,
+ *          the conduit's stored volume, the dq6 friction divisor, the
+ *          evaporation / seepage loss rate and the variable-step scale all
+ *          use it; the .inp writer, the report's length column and
+ *          modLength's parse-time default keep the authored value.
+ *
+ * @return The routing length (ft), or 0 for a non-conduit / missing row.
+ */
+double conduit_true_length(const SimulationContext& ctx, int j);
+
 } /* namespace openswmm::input */
 
 #endif /* OPENSWMM_ENGINE_POST_PARSE_RESOLVER_HPP */
diff --git a/src/engine/input/SectionParser.hpp b/src/engine/input/SectionParser.hpp
index a369c39b6..e2595e112 100644
--- a/src/engine/input/SectionParser.hpp
+++ b/src/engine/input/SectionParser.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SectionParser.hpp
  * @brief Utility for splitting raw INP section lines into (data, comment) pairs.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #pragma once
diff --git a/src/engine/input/SectionRegistry.cpp b/src/engine/input/SectionRegistry.cpp
index db168d1f4..f8c68ef4b 100644
--- a/src/engine/input/SectionRegistry.cpp
+++ b/src/engine/input/SectionRegistry.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SectionRegistry.cpp
  * @brief Implementation of the section-handler registry.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "SectionRegistry.hpp"
diff --git a/src/engine/input/SectionRegistry.hpp b/src/engine/input/SectionRegistry.hpp
index 1cfb5a156..977d9abee 100644
--- a/src/engine/input/SectionRegistry.hpp
+++ b/src/engine/input/SectionRegistry.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SectionRegistry.hpp
  * @brief Registry that maps SWMM section tags to handler functions.
@@ -23,7 +39,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SECTION_REGISTRY_HPP
diff --git a/src/engine/input/Tokenizer.cpp b/src/engine/input/Tokenizer.cpp
index 3c21d610b..40466d250 100644
--- a/src/engine/input/Tokenizer.cpp
+++ b/src/engine/input/Tokenizer.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Tokenizer.cpp
  * @brief Implementation of the multi-delimiter SWMM input tokenizer.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Tokenizer.hpp"
@@ -42,10 +58,37 @@ std::string_view Tokenizer::strip_comment(std::string_view line) noexcept {
 // tokenize
 // ============================================================================
 
+bool Tokenizer::is_pure_csv_line(std::string_view line) noexcept {
+    bool in_quotes = false;
+    for (char c : line) {
+        if (c == '"') { in_quotes = !in_quotes; continue; }
+        if (!in_quotes && is_space(c)) return false;
+    }
+    return true;
+}
+
+bool Tokenizer::comma_separates(std::string_view line, std::size_t pos,
+                                bool pure_csv) noexcept {
+    // Nothing else structures the line, so the commas must.
+    if (pure_csv) return true;
+    // A comma opening or closing the line cannot be interior to a name.
+    if (pos == 0 || pos + 1 >= line.size()) return true;
+    // Otherwise it separates only where a token has already ended (or is about
+    // to begin) — i.e. against whitespace. Flanked by non-whitespace, it is
+    // part of the name, which is what legacy does with every comma.
+    return is_space(line[pos - 1]) || is_space(line[pos + 1]);
+}
+
 std::vector Tokenizer::tokenize(std::string_view line) {
     std::string_view stripped = strip_comment(line);
+    const bool pure_csv = is_pure_csv_line(stripped);
 
     std::vector tokens;
+    // Rows in every .inp section are a handful of columns; without this the
+    // vector reallocates two or three times per row, and there are millions of
+    // rows in a large model. 8 covers the overwhelming majority in one
+    // allocation (longer rows still grow normally).
+    tokens.reserve(8);
     std::size_t i = 0;
     const std::size_t n = stripped.size();
 
@@ -56,10 +99,13 @@ std::vector Tokenizer::tokenize(std::string_view line) {
         }
         if (i >= n) break;
 
-        if (stripped[i] == ',') {
-            // Comma separator: produces an empty token if nothing was before it
-            // but we treat consecutive commas as empty tokens (CSV semantics)
-            tokens.emplace_back();
+        if (stripped[i] == ',' && comma_separates(stripped, i, pure_csv)) {
+            // An empty CSV field, which must be kept or every later column
+            // shifts left. It is only empty when this comma directly follows
+            // another (",,") or opens the line — a comma reached after
+            // whitespace is just the separator that ended the previous token,
+            // so "A ,B" is two fields, not three.
+            if (i == 0 || stripped[i - 1] == ',') tokens.emplace_back();
             ++i;
             continue;
         }
@@ -80,9 +126,12 @@ std::vector Tokenizer::tokenize(std::string_view line) {
             continue;
         }
 
-        // Regular token: read until next delimiter
+        // Regular token: read to the next delimiter. A comma only ends the
+        // token where it separates; otherwise it is an ordinary name
+        // character, as it is in legacy SWMM.
         std::size_t start = i;
-        while (i < n && !is_delimiter(stripped[i])) {
+        while (i < n && !is_space(stripped[i]) &&
+               !(stripped[i] == ',' && comma_separates(stripped, i, pure_csv))) {
             ++i;
         }
         tokens.emplace_back(stripped.substr(start, i - start));
@@ -102,9 +151,18 @@ std::vector Tokenizer::tokenize(std::string_view line) {
 // ============================================================================
 
 std::vector Tokenizer::tokenize_views(std::string_view line) {
+    std::vector tokens;
+    tokenize_views_into(line, tokens);
+    return tokens;
+}
+
+void Tokenizer::tokenize_views_into(std::string_view line,
+                                    std::vector& tokens) {
     std::string_view stripped = strip_comment(line);
+    const bool pure_csv = is_pure_csv_line(stripped);
 
-    std::vector tokens;
+    tokens.clear();
+    if (tokens.capacity() < 8) tokens.reserve(8);
     std::size_t i = 0;
     const std::size_t n = stripped.size();
 
@@ -113,21 +171,20 @@ std::vector Tokenizer::tokenize_views(std::string_view line) {
         while (i < n && (stripped[i] == ' ' || stripped[i] == '\t')) ++i;
         if (i >= n) break;
 
-        if (stripped[i] == ',') {
+        if (stripped[i] == ',' && comma_separates(stripped, i, pure_csv)) {
             ++i;
             continue;
         }
 
         // Regular token (quoted tokens not supported — caller must use tokenize())
         std::size_t start = i;
-        while (i < n && !is_delimiter(stripped[i])) ++i;
+        while (i < n && !is_space(stripped[i]) &&
+               !(stripped[i] == ',' && comma_separates(stripped, i, pure_csv))) ++i;
         if (i > start) {
             tokens.push_back(stripped.substr(start, i - start));
         }
         if (i < n && stripped[i] == ',') ++i;
     }
-
-    return tokens;
 }
 
 // ============================================================================
diff --git a/src/engine/input/Tokenizer.hpp b/src/engine/input/Tokenizer.hpp
index 05c0623f9..83c1a8afd 100644
--- a/src/engine/input/Tokenizer.hpp
+++ b/src/engine/input/Tokenizer.hpp
@@ -1,21 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Tokenizer.hpp
  * @brief Multi-delimiter tokenizer for SWMM input files.
  *
  * @details Replaces the legacy space-only tokenizer in src/solver/input.c.
- *          The new tokenizer handles comma, tab, and one-or-more spaces as
- *          delimiters. This allows input files to be formatted as:
+ *          Whitespace always delimits; a comma delimits only where it cannot
+ *          be part of a name. This allows input files to be formatted as:
  *          - Traditional SWMM (space-delimited)
  *          - Spreadsheet export (comma or tab-delimited CSV)
  *          - Mixed formats within the same file
  *
+ *          The comma rule is positional, not dialect-wide, because the two
+ *          readings genuinely collide. Legacy splits on `" \t\n\r"` only, so a
+ *          comma is an ordinary name character — and real decks depend on it:
+ *          `S-2-M20-L109/link2,6-201-9(u)` is ONE subcatchment outlet. Treating
+ *          every comma as a delimiter truncated that reference, read the name
+ *          fragment after it as the subcatchment's area, and produced a
+ *          trailing token the legacy reader then rejected as an undefined
+ *          object.
+ *
+ *          So: a comma separates when it sits at a token boundary — adjacent
+ *          to whitespace or at a line edge — or when the line carries no
+ *          whitespace at all outside quotes and is therefore pure CSV. A comma
+ *          with non-whitespace on both sides, in an otherwise
+ *          whitespace-delimited line, belongs to its token. A value that
+ *          genuinely contains a comma AND sits in a CSV row must be quoted,
+ *          which is the ordinary CSV convention.
+ *
  * ### Key differences from legacy SWMM tokenizer
  *
  * | Feature | Legacy (input.c) | New Tokenizer |
  * |---------|-----------------|---------------|
- * | Delimiters | Space only | Space, tab, comma |
+ * | Delimiters | Space, tab, CR/LF | Same, plus comma at a token boundary |
  * | Comment char | `;` (semicolon) | `;` or `;;` |
- * | Quoted strings | Not supported | Supported (double-quotes) |
+ * | Quoted strings | Filenames only | Supported anywhere (double-quotes) |
  * | Performance | sscanf-based | std::string_view, no allocations |
  *
  * @see Legacy reference: src/solver/input.c — getToken()
@@ -24,7 +57,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TOKENIZER_HPP
@@ -106,6 +139,21 @@ class Tokenizer {
      */
     static std::vector tokenize_views(std::string_view line);
 
+    /**
+     * @brief tokenize_views into a caller-owned buffer.
+     *
+     * @details Hoist the buffer out of a per-row loop and this allocates
+     *          nothing at all after the first row — clear() keeps capacity.
+     *          That matters in the geometry sections, which are the row-count
+     *          leaders in a large model ([VERTICES] alone is three rows per
+     *          link).
+     *
+     *          Like tokenize_views(), quoted tokens are NOT supported; callers
+     *          that may see them must fall back to tokenize().
+     */
+    static void tokenize_views_into(std::string_view line,
+                                    std::vector& out);
+
     // -----------------------------------------------------------------------
     // Utilities
     // -----------------------------------------------------------------------
@@ -146,10 +194,43 @@ class Tokenizer {
     static bool parse_boolean(std::string_view sv) noexcept;
 
 private:
-    /** @brief Returns true if `c` is a token delimiter (comma, tab, space). */
-    static bool is_delimiter(char c) noexcept {
-        return c == ',' || c == '\t' || c == ' ';
-    }
+    /** @brief Space or tab — always a delimiter, as in legacy SWMM. */
+    static bool is_space(char c) noexcept { return c == ' ' || c == '\t'; }
+
+    /**
+     * @brief True when the line carries no whitespace OUTSIDE quotes.
+     *
+     * @details Such a line has no other structure to read, so its commas can
+     *          only be column separators — this is the "spreadsheet export"
+     *          case. Whitespace inside a quoted token does not count: for
+     *          `"a b",c` the quotes supply the structure and the comma still
+     *          separates.
+     */
+    static bool is_pure_csv_line(std::string_view line) noexcept;
+
+    /**
+     * @brief True when the comma at @p pos separates tokens rather than
+     *        belonging to one.
+     *
+     * @details Legacy SWMM splits on `" \t\n\r"` only (input.c SEPSTR), so a
+     *          comma is an ordinary name character there — and real decks rely
+     *          on that: `S-2-M20-L109/link2,6-201-9(u)` is ONE outlet name.
+     *          Splitting it truncated the reference, read a name fragment as
+     *          the area and invented a trailing token.
+     *
+     *          This engine also accepts comma-delimited input, so the two
+     *          readings are separated by position rather than by dialect: a
+     *          comma separates when it sits at a token boundary — against
+     *          whitespace or a line edge — or when the whole line is pure CSV.
+     *          A comma flanked by non-whitespace on both sides, in a line that
+     *          is otherwise whitespace-delimited, belongs to its token.
+     *
+     * @param line      The comment-stripped line.
+     * @param pos       Index of the comma.
+     * @param pure_csv  Result of is_pure_csv_line() for this line.
+     */
+    static bool comma_separates(std::string_view line, std::size_t pos,
+                                bool pure_csv) noexcept;
 };
 
 } /* namespace openswmm::input */
diff --git a/src/engine/input/geopackage/ExternalContentReader.cpp b/src/engine/input/geopackage/ExternalContentReader.cpp
index ded1a1593..7e9beaec0 100644
--- a/src/engine/input/geopackage/ExternalContentReader.cpp
+++ b/src/engine/input/geopackage/ExternalContentReader.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExternalContentReader.cpp
  * @brief Slice IO-8 — Part D content → SimulationContext slot hydration +
@@ -5,10 +21,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ExternalContentReader.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "GpkgUtils.hpp"
 #include "formats/ClimateFormat.hpp"
 #include "formats/HotstartFormat.hpp"
@@ -56,13 +73,16 @@ double isoToOaDate(const char* iso) {
 
 void ensureDir(const std::string& dir) {
     std::error_code ec;
-    fs::create_directories(dir, ec);
+    // utf8_path, not the implicit std::string -> fs::path conversion, which
+    // decodes in the ANSI code page on Windows (issue #7).
+    fs::create_directories(openswmm::io::utf8_path(dir), ec);
 }
 
 std::string joinScratch(const std::string& scratch_dir,
                          const std::string& filename) {
-    fs::path p = fs::path(scratch_dir) / filename;
-    return p.string();
+    fs::path p = openswmm::io::utf8_path(scratch_dir)
+               / openswmm::io::utf8_path(filename);
+    return openswmm::io::path_utf8(p);
 }
 
 void bindSlot(FilePathPair& slot,
@@ -413,7 +433,7 @@ void hydrateHotstart(sqlite3* db, SimulationContext& ctx,
 
         if (s.status != "populated") {
             // Create an empty placeholder so the path exists for the GUI.
-            std::FILE* fp = std::fopen(scratch_path.c_str(), "wb");
+            std::FILE* fp = openswmm::io::fopen_utf8(scratch_path, "wb");
             if (fp) std::fclose(fp);
         } else {
             // Build a HotstartSnapshot from state rows.
@@ -556,8 +576,12 @@ void hydrateHotstart(sqlite3* db, SimulationContext& ctx,
 // ============================================================================
 
 std::string scratchDirFor(const std::string& gpkg_path) {
-    fs::path p(gpkg_path);
-    std::string stem = p.stem().string();
+    // utf8_path/path_utf8, not fs::path(std::string)/.string(): the .gpkg path
+    // is UTF-8 and the narrow forms decode/encode in the ANSI code page, so a
+    // non-ASCII stem or parent came back mangled and the scratch dir landed
+    // somewhere else (issue #7).
+    const fs::path p = openswmm::io::utf8_path(gpkg_path);
+    std::string stem = openswmm::io::path_utf8(p.stem());
     if (stem.empty()) stem = "gpkg";
     const std::string leaf = stem + ".scratch";
     // Emit a portable forward-slash path. fs::path::operator/ joins with the
@@ -565,7 +589,7 @@ std::string scratchDirFor(const std::string& gpkg_path) {
     // like "/tmp\\foo.scratch"; build the sibling path with '/' instead.
     const fs::path parent = p.parent_path();
     if (parent.empty()) return leaf;
-    return parent.generic_string() + "/" + leaf;
+    return openswmm::io::path_utf8(parent, /*generic=*/true) + "/" + leaf;
 }
 
 void read_external_content(sqlite3*               db,
diff --git a/src/engine/input/geopackage/ExternalContentReader.hpp b/src/engine/input/geopackage/ExternalContentReader.hpp
index 4441cea18..bba7157af 100644
--- a/src/engine/input/geopackage/ExternalContentReader.hpp
+++ b/src/engine/input/geopackage/ExternalContentReader.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExternalContentReader.hpp
  * @brief Slice IO-8 — hydrate `SimulationContext` external-file slots from
@@ -29,7 +45,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_EXTERNAL_CONTENT_READER_HPP
diff --git a/src/engine/input/geopackage/ExternalContentWriter.cpp b/src/engine/input/geopackage/ExternalContentWriter.cpp
index f7740f96b..53384a2f5 100644
--- a/src/engine/input/geopackage/ExternalContentWriter.cpp
+++ b/src/engine/input/geopackage/ExternalContentWriter.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExternalContentWriter.cpp
  * @brief Slice IO-7 — implementation of the Part D content fan-out.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ExternalContentWriter.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "GpkgUtils.hpp"
 #include "formats/ClimateFormat.hpp"
 #include "formats/HotstartFormat.hpp"
@@ -40,7 +57,7 @@ using openswmm::FileMode;
 
 bool fileExists(const std::string& path) {
     if (path.empty()) return false;
-    std::FILE* fp = std::fopen(path.c_str(), "rb");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "rb");
     if (!fp) return false;
     std::fclose(fp);
     return true;
diff --git a/src/engine/input/geopackage/ExternalContentWriter.hpp b/src/engine/input/geopackage/ExternalContentWriter.hpp
index 5a44f53dd..843e13157 100644
--- a/src/engine/input/geopackage/ExternalContentWriter.hpp
+++ b/src/engine/input/geopackage/ExternalContentWriter.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ExternalContentWriter.hpp
  * @brief Slice IO-7 — fan-out from in-memory external-file slots to the
@@ -33,7 +49,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_EXTERNAL_CONTENT_WRITER_HPP
diff --git a/src/engine/input/geopackage/GeoPackageInputPlugin.hpp b/src/engine/input/geopackage/GeoPackageInputPlugin.hpp
index 37e2e2645..e22224bf5 100644
--- a/src/engine/input/geopackage/GeoPackageInputPlugin.hpp
+++ b/src/engine/input/geopackage/GeoPackageInputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageInputPlugin.hpp
  * @brief IInputPlugin implementation for reading/writing SWMM models from/to GeoPackage.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_INPUT_PLUGIN_HPP
diff --git a/src/engine/input/geopackage/GeoPackageOutputPlugin.cpp b/src/engine/input/geopackage/GeoPackageOutputPlugin.cpp
index 600905ed5..be417aa53 100644
--- a/src/engine/input/geopackage/GeoPackageOutputPlugin.cpp
+++ b/src/engine/input/geopackage/GeoPackageOutputPlugin.cpp
@@ -19,6 +19,101 @@
 
 namespace openswmm::gpkg {
 
+namespace {
+
+/// The `variables.units` label for a species column.
+///
+/// Water age is HOURS; a pollutant carries its own concentration unit. The
+/// binary `.out` cannot express this (its per-column unit field is a
+/// three-value concentration enum with no HOURS slot, which is why the
+/// species NAME is the discriminator there) — the GeoPackage `variables`
+/// table has a free-text `units` column, so here the unit can simply be
+/// stated.
+const char* species_units_label(MassUnits u) {
+    switch (u) {
+        case MassUnits::UG_PER_L:     return "ug/L";
+        case MassUnits::COUNTS_PER_L: return "#/L";
+        case MassUnits::MG_PER_L:     break;
+    }
+    return "mg/L";
+}
+
+}  // namespace
+
+int GeoPackageOutputPlugin::register_species_variables(const SimulationContext& ctx) {
+    // Mirrors DefaultOutputPlugin: IGNORE_QUALITY means no species columns
+    // anywhere, so nothing is registered and update()'s lookups keep
+    // returning −1 as before.
+    if (ctx.options.ignore_quality) return 0;
+
+    const int nr = ctx.n_reported_species();
+    if (nr <= 0) return 0;
+
+    // The REPORTED stride (pollutants, then __WATER_AGE__ when enabled) —
+    // the same single truth the .out writer strides by. Indices at or past
+    // n_pollutants() are the reserved age row.
+    const int np = ctx.n_pollutants();
+
+    // All three object types: update() already reads subcatch_quality,
+    // node_quality and link_quality and looks each species up per type.
+    // Subcatchment age reports 0 until plan phase A3; that is a VALUE
+    // question, not a registration one, and the .out already carries the
+    // same zero column, so the two outputs stay consistent.
+    static const char* const kObjTypes[] = {"NODE", "LINK", "SUBCATCH"};
+
+    auto probe = gpkg::prepare(db_.get(),
+        "SELECT category FROM variables WHERE name = ? AND object_type = ?");
+    auto ins = gpkg::prepare(db_.get(),
+        "INSERT INTO variables (name, object_type, category, units, description) "
+        "VALUES (?, ?, 'QUALITY', ?, ?)");
+
+    for (int s = 0; s < nr; ++s) {
+        const std::string& sname = ctx.reported_species_names[static_cast(s)];
+        const bool is_age = (s >= np);
+        const std::string units = is_age
+            ? "hours"
+            : species_units_label(ctx.pollutants.units[static_cast(s)]);
+        const std::string desc = is_age ? "Water age" : "Species concentration";
+
+        for (const char* obj : kObjTypes) {
+            sqlite3_reset(probe.get());
+            sqlite3_clear_bindings(probe.get());
+            bind_text(probe.get(), 1, sname);
+            bind_text(probe.get(), 2, obj);
+
+            if (sqlite3_step(probe.get()) == SQLITE_ROW) {
+                // A row already exists for this (name, object_type).
+                if (column_text(probe.get(), 0) == "QUALITY") continue;  // re-run into the same file
+
+                // NAME COLLISION with a hydraulic variable. This must not be
+                // ignored: `variables` is UNIQUE(name, object_type), so an
+                // INSERT OR IGNORE here would leave the hydraulic row in
+                // place and update()'s lookup_variable(sname, obj) would
+                // resolve to ITS id — writing species concentrations into,
+                // say, the node depth series. Silently corrupting an
+                // existing result is worse than refusing to open, and the
+                // condition is entirely under the user's control (rename the
+                // pollutant), so this fails loudly instead.
+                error_msg_ = "GeoPackage output: species '" + sname +
+                             "' collides with the built-in " + obj +
+                             " variable of the same name. Rename the "
+                             "pollutant; writing it would overwrite that "
+                             "variable's results.";
+                return -1;
+            }
+
+            sqlite3_reset(ins.get());
+            sqlite3_clear_bindings(ins.get());
+            bind_text(ins.get(), 1, sname);
+            bind_text(ins.get(), 2, obj);
+            bind_text(ins.get(), 3, units);
+            bind_text(ins.get(), 4, desc);
+            sqlite3_step(ins.get());
+        }
+    }
+    return 0;
+}
+
 int GeoPackageOutputPlugin::initialize(const std::vector& init_args,
                                         const IPluginComponentInfo* /*info*/) {
     if (init_args.size() < 1) {
@@ -62,6 +157,14 @@ int GeoPackageOutputPlugin::prepare(const SimulationContext& ctx) {
 
         populate_default_variables(db_.get());
 
+        // Species are model-dependent, so they cannot live in the static
+        // default list. MUST run before the variable-ID cache below, which
+        // is built once from the table.
+        if (register_species_variables(ctx) != 0) {
+            state_ = PluginState::ERROR;
+            return -1;
+        }
+
         // Per-timestep results arrive pre-converted to display units (engine
         // boundary); no plugin-side conversion factors needed.
 
diff --git a/src/engine/input/geopackage/GeoPackageOutputPlugin.hpp b/src/engine/input/geopackage/GeoPackageOutputPlugin.hpp
index 7699f92e6..fd12c6f5a 100644
--- a/src/engine/input/geopackage/GeoPackageOutputPlugin.hpp
+++ b/src/engine/input/geopackage/GeoPackageOutputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageOutputPlugin.hpp
  * @brief IOutputPlugin that writes per-timestep results to a GeoPackage.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_OUTPUT_PLUGIN_HPP
@@ -62,6 +78,18 @@ class GeoPackageOutputPlugin : public IOutputPlugin {
     void flush_buffer();
     int lookup_variable(const std::string& name, const std::string& obj_type);
 
+    /**
+     * @brief Register the run's reported species in the `variables` table.
+     * @details `populate_default_variables()` carries a fixed list of
+     *          hydraulic variables only; species names are model-dependent
+     *          and so cannot live there. Without this, every
+     *          `lookup_variable(species_name, ...)` in update() returns −1
+     *          and EVERY species row is silently dropped — pollutants
+     *          included, not just water age.
+     * @returns 0 on success, −1 on a name collision (see the .cpp).
+     */
+    int register_species_variables(const SimulationContext& ctx);
+
     // Per-timestep results arrive pre-converted to display units (engine
     // boundary), so no plugin-side unit-conversion factors are required.
 
diff --git a/src/engine/input/geopackage/GeoPackagePluginInfo.hpp b/src/engine/input/geopackage/GeoPackagePluginInfo.hpp
index c61b17ce0..75ca886ae 100644
--- a/src/engine/input/geopackage/GeoPackagePluginInfo.hpp
+++ b/src/engine/input/geopackage/GeoPackagePluginInfo.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackagePluginInfo.hpp
  * @brief IPluginComponentInfo implementation for the GeoPackage I/O plugin.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_PLUGIN_INFO_HPP
@@ -89,12 +105,13 @@ class GeoPackagePluginInfo : public IPluginComponentInfo {
     // -----------------------------------------------------------------------
 
     std::string license_type() const override {
-        return "MIT";
+        return "Apache-2.0";
     }
 
     std::string license_text() const override {
         return "Copyright (c) 2026 Caleb Buahin. All rights reserved.\n"
-               "MIT License — see LICENSE file for full text.";
+               "Licensed under the Apache License, Version 2.0 — see the\n"
+               "LICENSE and NOTICE files for full text.";
     }
 
     // -----------------------------------------------------------------------
diff --git a/src/engine/input/geopackage/GeoPackageReader.cpp b/src/engine/input/geopackage/GeoPackageReader.cpp
index ae1cb790e..b3ad994b7 100644
--- a/src/engine/input/geopackage/GeoPackageReader.cpp
+++ b/src/engine/input/geopackage/GeoPackageReader.cpp
@@ -5,6 +5,7 @@
  */
 
 #include "GeoPackageReader.hpp"
+#include "../../core/Constants.hpp"
 #include "ExternalContentReader.hpp"
 #include 
 #include "GpkgUtils.hpp"
@@ -28,6 +29,7 @@
 #include "2d/data/SolverOptions2D.hpp"
 #include "2d/data/BoundaryData.hpp"
 #include "2d/data/PendingRows2D.hpp"
+#include "2d/data/Report2DVars.hpp"
 
 #include "core/DateTime.hpp"
 
@@ -180,6 +182,8 @@ static void apply_option_2d(SimulationContext& ctx, const std::string& key,
     }
     else if (key == "2D_RAINFALL_MODE") {
         if      (val == "NATURAL_NEIGHBOUR") o->rainfall_mode = twoD::RainfallMode::NATURAL_NEIGHBOUR;
+        else if (val == "NEAREST_NEIGHBOUR" || val == "NEAREST_NEIGHBOR")
+            o->rainfall_mode = twoD::RainfallMode::NEAREST_NEIGHBOUR;
         else if (val == "SYSTEM")            o->rainfall_mode = twoD::RainfallMode::SYSTEM;
         else if (val == "NONE")              o->rainfall_mode = twoD::RainfallMode::NONE;
     }
@@ -200,6 +204,35 @@ static void apply_option_2d(SimulationContext& ctx, const std::string& key,
     else if (key == "2D_ADVECTION")     o->advection = (val == "YES");
     else if (key == "2D_COUPLING_AREA") o->coupling_area_auto = (val == "AUTO");
     else if (key == "2D_REPORT_2D")     o->report_2d = (val == "YES");
+    else if (key == "2D_OUTPUT_PRECISION")
+        o->output_precision = (val == "FLOAT64") ? twoD::OutputPrecision2D::FLOAT64
+                                                 : twoD::OutputPrecision2D::FLOAT32;
+    else if (key == "2D_OUTPUT_COMPRESSION") o->output_compression = std::stoi(val);
+    else if (key == "2D_REPORT_2D_VARIABLES") {
+        unsigned mask = 0;
+        if (twoD::report2d::parseMask(val, mask).empty()) o->report_2d_vars = mask;
+    }
+    else if (key == "2D_REPORT_2D_SPECIES") o->report_2d_species = twoD::report2d::parseSpecies(val);
+    else if (key == "2D_REPORT_2D_STEP")    o->report_2d_step = std::stod(val);
+    // E2 process enables.
+    else if (key == "2D_INFILTRATION")
+        o->infiltration = (val == "AUTO") ? -1 : (val == "YES" ? 1 : 0);
+    else if (key == "2D_INFIL_DEFAULT_METHOD")
+        o->infil_default_method = (val == "NONE" || val.empty()) ? std::string() : val;
+    else if (key == "2D_INFIL_DESTINATION")
+        o->infil_destination = (val == "LOST" || val.empty()) ? std::string() : val;
+    else if (key == "2D_EVAPORATION")
+        o->evaporation = (val == "NO") ? 0 : (val == "CLIMATE" ? 2 : 1);
+    else if (key == "2D_TRANSPORT_POLLUTANTS")  o->transport_pollutants  = (val != "NO");
+    else if (key == "2D_TRANSPORT_MSX")         o->transport_msx         = (val != "NO");
+    else if (key == "2D_TRANSPORT_AGE")         o->transport_age         = (val != "NO");
+    else if (key == "2D_TRANSPORT_TEMPERATURE") o->transport_temperature = (val != "NO");
+    // U5 — groundwater page keys.
+    // AUTO / absent both mean "unset"; older files spelled ON|OFF.
+    else if (key == "2D_GROUNDWATER")
+        o->groundwater = (val == "AUTO" || val.empty()) ? int8_t{-1}
+                       : ((val == "ON" || val == "YES") ? int8_t{1} : int8_t{0});
+    else if (key == "2D_GW_ET")       o->gw_et = (val == "NONE") ? "" : val;
     // HDF5 results path — restoring it lets SWMMEngine::open re-create the
     // Default2DOutputPlugin (2D results always stream to HDF5, never gpkg).
     else if (key == "2D_OUTPUT_FILE")   o->output_file = val;
@@ -244,6 +277,11 @@ static void read_options(sqlite3* db, SimulationContext& ctx, const std::string&
         else if (key == "NODE_CONTINUITY") ctx.options.node_continuity = static_cast(std::stoi(val));
         else if (key == "ANDERSON_ACCEL") ctx.options.anderson_accel = (std::stoi(val) != 0);
         else if (key == "SURCHARGE_METHOD") ctx.options.surcharge_method = std::stoi(val);
+        else if (key == "UNSTEADY_FRICTION") ctx.options.unsteady_friction = std::stoi(val);  // issue #156
+        else if (key == "UF_K3") ctx.options.uf_k3 = std::stod(val);
+        else if (key == "FV_PRESSURE_CLOSURE") ctx.options.fv.pressure_closure = std::stoi(val);  // issue #156
+        else if (key == "REPORT_SIGNED_HEADS") ctx.options.report_signed_heads = std::stoi(val);  // issue #156
+        else if (key == "TPA_CELERITY") ctx.options.tpa_celerity = std::stod(val);  // issue #156
         else if (key == "DPS_CELERITY") ctx.options.dps_target_celerity = std::stod(val);
         else if (key == "DPS_ALPHA") ctx.options.dps_alpha = std::stod(val);
         else if (key == "DPS_DECAY_TIME") ctx.options.dps_decay_time = std::stod(val);
@@ -314,10 +352,26 @@ static bool column_exists(sqlite3* db, const std::string& table,
 static void read_nodes(sqlite3* db, SimulationContext& ctx, const std::string& sim_id) {
     // --- base nodes (common columns + discriminator + geometry) ---
     {
+        // is_virtual / rim_depth were appended after the schema shipped; an
+        // older .gpkg does not have the columns at all (SELECTing them fails
+        // outright, and the db is opened READONLY so we cannot ALTER it), so
+        // probe first. Absent means "no virtual junctions", which is exactly
+        // how such a file behaved before.
+        const bool has_virtual = column_exists(db, "nodes", "is_virtual") &&
+                                 column_exists(db, "nodes", "rim_depth");
+        const bool has_inlet = has_virtual && column_exists(db, "nodes", "is_inlet");
         auto stmt = prepare(db,
-            "SELECT node_id, node_type, geom, invert_elev, max_depth, init_depth, "
-            "surcharge_depth, ponded_area, tag "
-            "FROM nodes WHERE simulation_id = ? ORDER BY fid");
+            has_inlet
+                ? "SELECT node_id, node_type, geom, invert_elev, max_depth, init_depth, "
+                  "surcharge_depth, ponded_area, tag, is_virtual, rim_depth, is_inlet "
+                  "FROM nodes WHERE simulation_id = ? ORDER BY fid"
+            : has_virtual
+                ? "SELECT node_id, node_type, geom, invert_elev, max_depth, init_depth, "
+                  "surcharge_depth, ponded_area, tag, is_virtual, rim_depth "
+                  "FROM nodes WHERE simulation_id = ? ORDER BY fid"
+                : "SELECT node_id, node_type, geom, invert_elev, max_depth, init_depth, "
+                  "surcharge_depth, ponded_area, tag "
+                  "FROM nodes WHERE simulation_id = ? ORDER BY fid");
         bind_text(stmt.get(), 1, sim_id);
         while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
             std::string name = column_text(stmt.get(), 0);
@@ -331,6 +385,9 @@ static void read_nodes(sqlite3* db, SimulationContext& ctx, const std::string& s
                 auto pt = decode_point(column_blob(stmt.get(), 2));
                 ctx.spatial.node_x[idx] = pt.x;
                 ctx.spatial.node_y[idx] = pt.y;
+                if (ctx.spatial.node_has_xy.size() < ctx.spatial.node_x.size())
+                    ctx.spatial.node_has_xy.resize(ctx.spatial.node_x.size(), 0);
+                ctx.spatial.node_has_xy[static_cast(idx)] = 1;   // G-X2
             }
             ctx.nodes.invert_elev[idx] = column_double(stmt.get(), 3);
             ctx.nodes.full_depth[idx]  = column_double(stmt.get(), 4);
@@ -342,6 +399,19 @@ static void read_nodes(sqlite3* db, SimulationContext& ctx, const std::string& s
                 if (u >= ctx.nodes.tags.size()) ctx.nodes.tags.resize(u + 1);
                 ctx.nodes.tags[u] = column_text(stmt.get(), 8);
             }
+            if (has_virtual) {
+                const auto u = static_cast(idx);
+                ctx.nodes.is_virtual[u] =
+                    (!column_is_null(stmt.get(), 9) && column_int(stmt.get(), 9) != 0) ? 1 : 0;
+                if (!column_is_null(stmt.get(), 10))
+                    ctx.nodes.rim_depth[u] = column_double(stmt.get(), 10);
+                // The inlet-usage row (design + capture node) has no table in
+                // the schema, so a node read back as is_inlet has no usage and
+                // fails validation with 633 until one is assigned.
+                if (has_inlet)
+                    ctx.nodes.is_inlet[u] =
+                        (!column_is_null(stmt.get(), 11) && column_int(stmt.get(), 11) != 0) ? 1 : 0;
+            }
         }
     }
 
@@ -756,6 +826,9 @@ static void read_subcatchments(sqlite3* db, SimulationContext& ctx, const std::s
         ctx.subcatches.ds_imperv[idx] = column_double(stmt.get(), 12);
         ctx.subcatches.ds_perv[idx] = column_double(stmt.get(), 13);
         ctx.subcatches.frac_imperv_no_store[idx] = column_double(stmt.get(), 14);
+        // The table stores only the fraction; recover the percent legacy
+        // multiplies by (see SubcatchData::pct_zero).
+        ctx.subcatches.pct_zero[idx] = ctx.subcatches.frac_imperv_no_store[idx] * 100.0;
         ctx.subcatches.subarea_routing[idx] = column_int(stmt.get(), 15);
         ctx.subcatches.pct_routed[idx] = column_double(stmt.get(), 16);
         ctx.subcatches.infil_model[idx] = column_int(stmt.get(), 17);
@@ -918,7 +991,11 @@ static void read_pollutants(sqlite3* db, SimulationContext& ctx, const std::stri
         ctx.pollutants.units[idx] = static_cast(column_int(stmt.get(), 1));
         ctx.pollutants.c_rain[idx] = column_double(stmt.get(), 2);
         ctx.pollutants.c_gw[idx] = column_double(stmt.get(), 3);
-        ctx.pollutants.k_decay[idx] = column_double(stmt.get(), 4);
+        // Column is file units (1/day) — pre-KD1 files stored the deck
+        // value unconverted, which is the same unit, so both eras read
+        // correctly here.
+        ctx.pollutants.k_decay[idx] =
+            column_double(stmt.get(), 4) / constants::SEC_PER_DAY;
         ctx.pollutants.snow_only[idx] = column_int(stmt.get(), 5) != 0;
 
         if (!column_is_null(stmt.get(), 6)) {
@@ -1088,8 +1165,8 @@ static void read_subcatch_loadings(sqlite3* db, SimulationContext& ctx, const st
         if (s < 0 || p < 0) continue;
         auto idx = static_cast(s) * static_cast(np)
                    + static_cast(p);
-        if (idx < ctx.subcatches.conc.size())
-            ctx.subcatches.conc[idx] = column_double(stmt.get(), 2);
+        if (idx < ctx.subcatches.init_loading.size())
+            ctx.subcatches.init_loading[idx] = column_double(stmt.get(), 2);
     }
 }
 
@@ -1654,6 +1731,94 @@ static void read_transects(sqlite3* db, SimulationContext& ctx, const std::strin
     }
 }
 
+// Street sections, inlet designs and inlet placements. Tables absent from a
+// .gpkg written before they existed → nothing read, exactly as before.
+static void read_streets(sqlite3* db, SimulationContext& ctx, const std::string& sim_id) {
+    if (!table_exists(db, "streets")) return;
+    auto stmt = prepare(db,
+        "SELECT street_id, t_crown, h_curb, sx, n_road, gutter_depres, gutter_width, "
+        "sides, back_width, back_slope, back_n FROM streets WHERE simulation_id = ? ORDER BY fid");
+    bind_text(stmt.get(), 1, sim_id);
+    auto& S = ctx.streets;
+    while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
+        S.names.push_back(column_text(stmt.get(), 0));
+        S.t_crown.push_back(column_double(stmt.get(), 1));
+        S.h_curb.push_back(column_double(stmt.get(), 2));
+        S.sx.push_back(column_double(stmt.get(), 3));
+        S.n_road.push_back(column_double(stmt.get(), 4));
+        S.gutter_depres.push_back(column_double(stmt.get(), 5));
+        S.gutter_width.push_back(column_double(stmt.get(), 6));
+        S.sides.push_back(column_is_null(stmt.get(), 7) ? 2 : column_int(stmt.get(), 7));
+        S.back_width.push_back(column_double(stmt.get(), 8));
+        S.back_slope.push_back(column_double(stmt.get(), 9));
+        S.back_n.push_back(column_double(stmt.get(), 10));
+    }
+}
+
+static void read_inlets(sqlite3* db, SimulationContext& ctx, const std::string& sim_id) {
+    if (!table_exists(db, "inlets")) return;
+    auto stmt = prepare(db,
+        "SELECT inlet_id, inlet_type, length, width, grate_type, open_area, splash_veloc, "
+        "curb_length, curb_height, curb_throat, curve_id, comment "
+        "FROM inlets WHERE simulation_id = ? ORDER BY fid");
+    bind_text(stmt.get(), 1, sim_id);
+    auto txt = [&](int col) {
+        return column_is_null(stmt.get(), col) ? std::string{} : column_text(stmt.get(), col);
+    };
+    auto& I = ctx.inlets;
+    while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
+        const int idx = I.add_row(column_text(stmt.get(), 0), column_text(stmt.get(), 1));
+        const auto u = static_cast(idx);
+        I.length[u]       = column_double(stmt.get(), 2);
+        I.width[u]        = column_double(stmt.get(), 3);
+        I.grate_type[u]   = txt(4);
+        I.open_area[u]    = column_double(stmt.get(), 5);
+        I.splash_veloc[u] = column_double(stmt.get(), 6);
+        I.curb_length[u]  = column_double(stmt.get(), 7);
+        I.curb_height[u]  = column_double(stmt.get(), 8);
+        I.curb_throat[u]  = column_is_null(stmt.get(), 9) ? 2 : column_int(stmt.get(), 9);
+        I.curve_id[u]     = txt(10);
+        if (I.comments.size() < I.names.size()) I.comments.resize(I.names.size());
+        I.comments[u]     = txt(11);
+    }
+}
+
+static void read_inlet_usage(sqlite3* db, SimulationContext& ctx, const std::string& sim_id) {
+    if (!table_exists(db, "inlet_usage")) return;
+    auto stmt = prepare(db,
+        "SELECT host_kind, host_id, inlet_id, capture_node, num_inlets, pct_clogged, "
+        "flow_limit, local_depress, local_width, placement "
+        "FROM inlet_usage WHERE simulation_id = ? ORDER BY fid");
+    bind_text(stmt.get(), 1, sim_id);
+    while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
+        const int  host_kind = column_int(stmt.get(), 0);
+        const std::string host = column_text(stmt.get(), 1);
+        const std::string design = column_text(stmt.get(), 2);
+        const int capture = ctx.node_names.find(column_text(stmt.get(), 3));
+        int di = -1;
+        for (int i = 0; i < ctx.inlets.count(); ++i)
+            if (ctx.inlets.names[static_cast(i)] == design) { di = i; break; }
+        const int host_node = (host_kind == 1) ? ctx.node_names.find(host) : -1;
+        const int host_link = (host_kind == 1) ? -1 : ctx.link_names.find(host);
+        // Unresolvable references are dropped, as the [INLET_USAGE] handler does.
+        if (di < 0 || capture < 0) continue;
+        if (host_kind == 1 ? host_node < 0 : host_link < 0) continue;
+        const int r = ctx.inlet_usages.add_row(host_link, host_node, di, capture);
+        const auto ur = static_cast(r);
+        ctx.inlet_usages.num_inlets[ur]    = column_is_null(stmt.get(), 4) ? 1 : column_int(stmt.get(), 4);
+        ctx.inlet_usages.clog_factor[ur]   = 1.0 - column_double(stmt.get(), 5) / 100.0;
+        ctx.inlet_usages.flow_limit[ur]    = column_double(stmt.get(), 6);
+        ctx.inlet_usages.local_depress[ur] = column_double(stmt.get(), 7);
+        ctx.inlet_usages.local_width[ur]   = column_double(stmt.get(), 8);
+        ctx.inlet_usages.placement[ur]     = column_is_null(stmt.get(), 9) ? 0 : column_int(stmt.get(), 9);
+        if (host_node >= 0) {
+            // The nodes table carries is_inlet; keep the two consistent.
+            const auto un = static_cast(host_node);
+            if (un < ctx.nodes.is_inlet.size()) ctx.nodes.is_inlet[un] = 1;
+        }
+    }
+}
+
 static void read_dwf(sqlite3* db, SimulationContext& ctx, const std::string& sim_id) {
     if (!table_exists(db, "dwf_inflows")) return;
     auto stmt = prepare(db,
@@ -1776,9 +1941,9 @@ static void read_mesh_2d(sqlite3* db, SimulationContext& ctx,
         while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
             const int t = column_int(stmt.get(), 0);
             if (t < 0 || t >= n) continue;
-            mesh.tri_v0[t]      = column_int(stmt.get(), 1);
-            mesh.tri_v1[t]      = column_int(stmt.get(), 2);
-            mesh.tri_v2[t]      = column_int(stmt.get(), 3);
+            mesh.set_triangle(t, column_int(stmt.get(), 1),
+                                 column_int(stmt.get(), 2),
+                                 column_int(stmt.get(), 3));
             mesh.mannings_n[t]  = column_double(stmt.get(), 4);
             mesh.tri_tag[t]     = column_text(stmt.get(), 5);
             if (has_init_depth)
@@ -1786,6 +1951,39 @@ static void read_mesh_2d(sqlite3* db, SimulationContext& ctx,
         }
     }
 
+    // ---- quads (mixed meshes; absent in older files) -------------------------
+    // Cell index = n_triangles + quad_idx.
+    if (table_exists(db, "mesh_2d_quads")) {
+        auto cnt = prepare(db,
+            "SELECT COUNT(*), COALESCE(MAX(quad_idx), -1) "
+            "FROM mesh_2d_quads WHERE simulation_id = ?");
+        bind_text(cnt.get(), 1, sim_id);
+        if (sqlite3_step(cnt.get()) == SQLITE_ROW) {
+            const int nq = column_int(cnt.get(), 0);
+            if (nq > 0) {
+                if (column_int(cnt.get(), 1) != nq - 1)
+                    throw GpkgError("mesh_2d_quads: quad_idx values are not "
+                                    "contiguous [0, n)");
+                const int nt0 = mesh.n_triangles();
+                mesh.resize_triangles(nt0 + nq);
+                auto stmt = prepare(db,
+                    "SELECT quad_idx, v0, v1, v2, v3, mannings_n, tag, init_depth "
+                    "FROM mesh_2d_quads WHERE simulation_id = ? ORDER BY quad_idx");
+                bind_text(stmt.get(), 1, sim_id);
+                while (sqlite3_step(stmt.get()) == SQLITE_ROW) {
+                    const int q = column_int(stmt.get(), 0);
+                    if (q < 0 || q >= nq) continue;
+                    const int t = nt0 + q;
+                    mesh.set_quad(t, column_int(stmt.get(), 1), column_int(stmt.get(), 2),
+                                     column_int(stmt.get(), 3), column_int(stmt.get(), 4));
+                    mesh.mannings_n[t]     = column_double(stmt.get(), 5);
+                    mesh.tri_tag[t]        = column_text(stmt.get(), 6);
+                    mesh.tri_init_depth[t] = column_double(stmt.get(), 7);
+                }
+            }
+        }
+    }
+
     // ---- coupling maps -------------------------------------------------------
     // Restored as NAMES (indices stay -1): SurfaceRouter2D::initialize()
     // resolves them against ctx.node_names with the same unknown-node fatal
@@ -1922,6 +2120,9 @@ int read_model(sqlite3* db, SimulationContext& ctx,
         read_inflows(db, ctx, simulation_id);
         read_dwf(db, ctx, simulation_id);
         read_transects(db, ctx, simulation_id);
+        read_streets(db, ctx, simulation_id);
+        read_inlets(db, ctx, simulation_id);
+        read_inlet_usage(db, ctx, simulation_id);
         read_controls(db, ctx, simulation_id);
 
         // Part E — 2D mesh model definition. Options keys (2D_*) were
diff --git a/src/engine/input/geopackage/GeoPackageReader.hpp b/src/engine/input/geopackage/GeoPackageReader.hpp
index aca647244..4c0d0ffe8 100644
--- a/src/engine/input/geopackage/GeoPackageReader.hpp
+++ b/src/engine/input/geopackage/GeoPackageReader.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageReader.hpp
  * @brief Reads a GeoPackage file into a SimulationContext (model input tables).
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_READER_HPP
diff --git a/src/engine/input/geopackage/GeoPackageReportPlugin.hpp b/src/engine/input/geopackage/GeoPackageReportPlugin.hpp
index 69502da8e..7b33b2a0a 100644
--- a/src/engine/input/geopackage/GeoPackageReportPlugin.hpp
+++ b/src/engine/input/geopackage/GeoPackageReportPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageReportPlugin.hpp
  * @brief IReportPlugin that writes summary statistics to a GeoPackage.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_REPORT_PLUGIN_HPP
diff --git a/src/engine/input/geopackage/GeoPackageSchema.cpp b/src/engine/input/geopackage/GeoPackageSchema.cpp
index 29b0ecafc..46465d2ef 100644
--- a/src/engine/input/geopackage/GeoPackageSchema.cpp
+++ b/src/engine/input/geopackage/GeoPackageSchema.cpp
@@ -95,6 +95,18 @@ CREATE TABLE IF NOT EXISTS nodes (
     surcharge_depth REAL,
     ponded_area     REAL,
     tag             TEXT,
+    -- Virtual junctions are JUNCTION-typed (node_type stays "JUNCTION"), so
+    -- the flag needs its own column or a round-trip demotes them to plain
+    -- junctions. rim_depth is the rendering-only ground depth that goes with
+    -- it (the optional [VIRTUAL_JUNCTIONS] MaxDepth); both are NULL in files
+    -- written before they existed and the reader treats that as 0.
+    is_virtual      INTEGER,
+    rim_depth       REAL,
+    -- Inlet junctions are virtual junctions that also carry a street inlet.
+    -- The flag round-trips here; the inlet USAGE row it needs ([INLETS] design
+    -- + capture node) has no GeoPackage table, so a .gpkg round-trip preserves
+    -- the flag but not the inlet assignment.
+    is_inlet        INTEGER,
     UNIQUE(simulation_id, node_id)
 );
 
@@ -240,7 +252,7 @@ CREATE TABLE IF NOT EXISTS orifices (
     link_id         TEXT NOT NULL,
     orientation     TEXT,                -- SIDE | BOTTOM
     discharge_coeff REAL,
-    orate           REAL,                -- open/close rate (s)
+    orate           REAL,                -- open/close rate (HOURS, as parsed)
     PRIMARY KEY (simulation_id, link_id),
     FOREIGN KEY (simulation_id, link_id)
         REFERENCES links(simulation_id, link_id)
@@ -721,6 +733,66 @@ CREATE INDEX IF NOT EXISTS idx_transects_lookup ON transects(simulation_id, tran
 )SQL";
 static_assert(sizeof(PART_A4_DDL) <= 16380, "MSVC C2026: split this DDL chunk");
 
+// Part A5: street sections, inlet designs and inlet placements. Values are
+// stored as the engine holds them after open (user units as read, cross slope
+// in percent) — the convention the [STREETS]/[INLETS] handlers and InpWriter
+// share. Usage rows cover both grammars: [INLET_USAGE] (host_kind 0, host_id =
+// conduit) and [INLET_JUNCTIONS] (host_kind 1, host_id = the inlet junction),
+// so a model with an inlet junction re-reads with its usage and passes rule 633.
+static const char PART_A5_DDL[] = R"SQL(
+CREATE TABLE IF NOT EXISTS streets (
+    fid             INTEGER PRIMARY KEY AUTOINCREMENT,
+    simulation_id   TEXT NOT NULL,
+    street_id       TEXT NOT NULL,
+    t_crown         REAL NOT NULL,
+    h_curb          REAL NOT NULL,
+    sx              REAL NOT NULL,      -- cross slope, percent
+    n_road          REAL NOT NULL,
+    gutter_depres   REAL,
+    gutter_width    REAL,
+    sides           INTEGER,
+    back_width      REAL,
+    back_slope      REAL,
+    back_n          REAL
+);
+CREATE INDEX IF NOT EXISTS idx_streets_lookup ON streets(simulation_id, street_id);
+
+CREATE TABLE IF NOT EXISTS inlets (
+    fid             INTEGER PRIMARY KEY AUTOINCREMENT,
+    simulation_id   TEXT NOT NULL,
+    inlet_id        TEXT NOT NULL,
+    inlet_type      TEXT NOT NULL,      -- GRATE/CURB/COMBO/SLOTTED/DROP_GRATE/DROP_CURB/CUSTOM
+    length          REAL,               -- grate or slotted length
+    width           REAL,
+    grate_type      TEXT,
+    open_area       REAL,               -- GENERIC grates
+    splash_veloc    REAL,
+    curb_length     REAL,
+    curb_height     REAL,
+    curb_throat     INTEGER,            -- 0 HORIZONTAL, 1 INCLINED, 2 VERTICAL
+    curve_id        TEXT,               -- CUSTOM capture curve NAME
+    comment         TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_inlets_lookup ON inlets(simulation_id, inlet_id);
+
+CREATE TABLE IF NOT EXISTS inlet_usage (
+    fid             INTEGER PRIMARY KEY AUTOINCREMENT,
+    simulation_id   TEXT NOT NULL,
+    host_kind       INTEGER NOT NULL,   -- 0 conduit ([INLET_USAGE]), 1 inlet junction ([INLET_JUNCTIONS])
+    host_id         TEXT NOT NULL,      -- conduit or node NAME
+    inlet_id        TEXT NOT NULL,
+    capture_node    TEXT NOT NULL,
+    num_inlets      INTEGER,
+    pct_clogged     REAL,
+    flow_limit      REAL,
+    local_depress   REAL,
+    local_width     REAL,
+    placement       INTEGER             -- 0 AUTOMATIC, 1 ON_GRADE, 2 ON_SAG
+);
+CREATE INDEX IF NOT EXISTS idx_inlet_usage_lookup ON inlet_usage(simulation_id, host_kind, host_id);
+)SQL";
+static_assert(sizeof(PART_A5_DDL) <= 16380, "MSVC C2026: split this DDL chunk");
+
 // ============================================================================
 // Part B: Simulation Results & Reports
 // ============================================================================
@@ -1166,6 +1238,41 @@ CREATE INDEX IF NOT EXISTS idx_mesh2d_tri_v0 ON mesh_2d_triangles(simulation_id,
 CREATE INDEX IF NOT EXISTS idx_mesh2d_tri_v1 ON mesh_2d_triangles(simulation_id, v1);
 CREATE INDEX IF NOT EXISTS idx_mesh2d_tri_v2 ON mesh_2d_triangles(simulation_id, v2);
 
+-- ----------------------------------------------------------------------------
+-- 2D mesh quadrilaterals (mixed tri-quad meshes, 2D_TRI_QUAD_MESH_PLAN
+-- 2026-09-06). quad_idx is the 0-based index WITHIN the quads; the engine
+-- cell index is n_triangles + quad_idx (cells are triangles first, then
+-- quads). Absent in older files (all-triangle).
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS mesh_2d_quads (
+    fid             INTEGER PRIMARY KEY AUTOINCREMENT,
+    simulation_id   TEXT NOT NULL,
+    quad_idx        INTEGER NOT NULL,
+    geom            BLOB,
+    v0              INTEGER NOT NULL,
+    v1              INTEGER NOT NULL,
+    v2              INTEGER NOT NULL,
+    v3              INTEGER NOT NULL,
+    mannings_n      REAL NOT NULL DEFAULT 0.035,
+    init_depth      REAL NOT NULL DEFAULT 0,
+    tag             TEXT,
+    bed_elev        REAL,
+    coupled_node    TEXT,
+    UNIQUE(simulation_id, quad_idx),
+    FOREIGN KEY (simulation_id, v0)
+        REFERENCES mesh_2d_vertices(simulation_id, vertex_idx)
+        ON DELETE CASCADE ON UPDATE CASCADE,
+    FOREIGN KEY (simulation_id, v1)
+        REFERENCES mesh_2d_vertices(simulation_id, vertex_idx)
+        ON DELETE CASCADE ON UPDATE CASCADE,
+    FOREIGN KEY (simulation_id, v2)
+        REFERENCES mesh_2d_vertices(simulation_id, vertex_idx)
+        ON DELETE CASCADE ON UPDATE CASCADE,
+    FOREIGN KEY (simulation_id, v3)
+        REFERENCES mesh_2d_vertices(simulation_id, vertex_idx)
+        ON DELETE CASCADE ON UPDATE CASCADE
+);
+
 -- ----------------------------------------------------------------------------
 -- Per-edge boundary conditions; canonical (tri_idx, edge) form matching
 -- [2D_BOUNDARY_CONDITIONS]. Rows exist only for non-default edges (absent
@@ -1270,6 +1377,7 @@ void create_schema(sqlite3* db) {
     exec(db, PART_A2_DDL);
     exec(db, PART_A3_DDL);
     exec(db, PART_A4_DDL);
+    exec(db, PART_A5_DDL);
     exec(db, PART_B_DDL);
     exec(db, PART_C_DDL);
     exec(db, PART_D_DDL);
diff --git a/src/engine/input/geopackage/GeoPackageSchema.hpp b/src/engine/input/geopackage/GeoPackageSchema.hpp
index 22d79f57d..29244b68b 100644
--- a/src/engine/input/geopackage/GeoPackageSchema.hpp
+++ b/src/engine/input/geopackage/GeoPackageSchema.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageSchema.hpp
  * @brief DDL and metadata registration for the OpenSWMM GeoPackage schema.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_SCHEMA_HPP
diff --git a/src/engine/input/geopackage/GeoPackageWriter.cpp b/src/engine/input/geopackage/GeoPackageWriter.cpp
index 487d86f82..aedec59a4 100644
--- a/src/engine/input/geopackage/GeoPackageWriter.cpp
+++ b/src/engine/input/geopackage/GeoPackageWriter.cpp
@@ -5,6 +5,7 @@
  */
 
 #include "GeoPackageWriter.hpp"
+#include "../../core/Constants.hpp"
 #include "ExternalContentWriter.hpp"
 #include "GeoPackageSchema.hpp"
 #include "GpkgUtils.hpp"
@@ -29,6 +30,7 @@
 #include "2d/data/BoundaryData.hpp"
 #include "2d/data/PendingRows2D.hpp"
 #include "2d/data/Serialize2D.hpp"
+#include "2d/data/Report2DVars.hpp"
 
 #include 
 #include 
@@ -227,6 +229,11 @@ static void write_options(sqlite3* db, const SimulationContext& ctx,
     insert("NODE_CONTINUITY", std::to_string(static_cast(opts.node_continuity)));
     insert("ANDERSON_ACCEL", std::to_string(opts.anderson_accel ? 1 : 0));
     insert("SURCHARGE_METHOD", std::to_string(opts.surcharge_method));
+    insert("UNSTEADY_FRICTION", std::to_string(opts.unsteady_friction));  // issue #156
+    insert_d("UF_K3", opts.uf_k3);
+    insert("FV_PRESSURE_CLOSURE", std::to_string(opts.fv.pressure_closure));  // issue #156
+    insert("REPORT_SIGNED_HEADS", std::to_string(opts.report_signed_heads));  // issue #156
+    insert_d("TPA_CELERITY", opts.tpa_celerity);  // issue #156
     if (opts.surcharge_method == 2) {
         insert_d("DPS_CELERITY", opts.dps_target_celerity);
         insert_d("DPS_ALPHA", opts.dps_alpha);
@@ -304,8 +311,9 @@ static void write_nodes(sqlite3* db, const SimulationContext& ctx,
     // node_id); the base row is inserted first each iteration so the FK resolves.
     auto stmt = prepare(db,
         "INSERT INTO nodes (simulation_id, node_id, node_type, geom, "
-        "invert_elev, max_depth, init_depth, surcharge_depth, ponded_area, tag) "
-        "VALUES (?,?,?,?,?,?,?,?,?,?)");
+        "invert_elev, max_depth, init_depth, surcharge_depth, ponded_area, tag, "
+        "is_virtual, rim_depth, is_inlet) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)");
     auto st_stmt = prepare(db,
         "INSERT INTO storages (simulation_id, node_id, curve_name, shape, a, b, c, "
         "p1, p2, p3, seep_rate, evap_frac, exfil_suction, exfil_ksat, exfil_imd) "
@@ -353,6 +361,15 @@ static void write_nodes(sqlite3* db, const SimulationContext& ctx,
         else
             bind_null(stmt.get(), 10);
 
+        // Virtual-junction flag + its rendering-only rim depth. node_type says
+        // JUNCTION for both kinds, so without these two the round-trip loses
+        // the virtual junction entirely.
+        bind_int(stmt.get(), 11,
+                 (utag < ctx.nodes.is_virtual.size() && ctx.nodes.is_virtual[utag]) ? 1 : 0);
+        bind_double(stmt.get(), 12, safe_dbl(ctx.nodes.rim_depth, i));
+        bind_int(stmt.get(), 13,
+                 (utag < ctx.nodes.is_inlet.size() && ctx.nodes.is_inlet[utag]) ? 1 : 0);
+
         sqlite3_step(stmt.get());
 
         // --- per-subtype child row ---
@@ -482,8 +499,18 @@ static void write_links(sqlite3* db, const SimulationContext& ctx,
 
         bind_text(stmt.get(), 5, from_name);
         bind_text(stmt.get(), 6, to_name);
-        bind_double(stmt.get(), 7, safe_dbl(ctx.links.offset1, i));
-        bind_double(stmt.get(), 8, safe_dbl(ctx.links.offset2, i));
+        // Persist the AUTHORED offsets: resolve_cross_references raises both
+        // offsets of a FILLED_CIRCULAR conduit by the sediment depth yBot
+        // (legacy link.c:1072-1077); undo it here (internal ft, as written).
+        double off1 = safe_dbl(ctx.links.offset1, i);
+        double off2 = safe_dbl(ctx.links.offset2, i);
+        if (ctx.links.type[i] == LinkType::CONDUIT &&
+            ctx.links.xsect_shape[i] == XsectShape::FILLED_CIRCULAR) {
+            off1 -= safe_dbl(ctx.links.xsect_y_bot, i);
+            off2 -= safe_dbl(ctx.links.xsect_y_bot, i);
+        }
+        bind_double(stmt.get(), 7, off1);
+        bind_double(stmt.get(), 8, off2);
 
         bind_double(stmt.get(), 9,  safe_dbl(ctx.links.q0, i));
         bind_double(stmt.get(), 10, safe_dbl(ctx.links.q_limit, i));
@@ -1019,7 +1046,10 @@ static void write_pollutants(sqlite3* db, const SimulationContext& ctx,
         bind_int(stmt.get(), 3, static_cast(safe_get(ctx.pollutants.units, (size_t)i, MassUnits::MG_PER_L)));
         bind_double(stmt.get(), 4, safe_dbl(ctx.pollutants.c_rain, i));
         bind_double(stmt.get(), 5, safe_dbl(ctx.pollutants.c_gw, i));
-        bind_double(stmt.get(), 6, safe_dbl(ctx.pollutants.k_decay, i));
+        // Kdecay column carries file units (1/day), like the INP column
+        // (KD1); internal storage is 1/sec.
+        bind_double(stmt.get(), 6,
+                    safe_dbl(ctx.pollutants.k_decay, i) * constants::SEC_PER_DAY);
         bind_int(stmt.get(), 7, safe_get(ctx.pollutants.snow_only, (size_t)i, false) ? 1 : 0);
         int co = safe_int(ctx.pollutants.co_pollut, i);
         if (co >= 0 && co < ctx.pollutant_names.size())
@@ -1153,8 +1183,8 @@ static void write_subcatch_loadings(sqlite3* db, const SimulationContext& ctx,
         for (int p = 0; p < np && p < ctx.n_pollutants(); ++p) {
             auto idx = static_cast(s) * static_cast(np)
                        + static_cast(p);
-            if (idx >= ctx.subcatches.conc.size()) break;
-            const double w = ctx.subcatches.conc[idx];
+            if (idx >= ctx.subcatches.init_loading.size()) break;
+            const double w = ctx.subcatches.init_loading[idx];
             if (w == 0.0) continue;
             sqlite3_reset(stmt.get());
             sqlite3_clear_bindings(stmt.get());
@@ -1489,6 +1519,106 @@ static void write_transects(sqlite3* db, const SimulationContext& ctx,
     }
 }
 
+// Street sections, inlet designs and inlet placements ([STREETS], [INLETS],
+// [INLET_USAGE] + [INLET_JUNCTIONS]). Written as the engine holds them (user
+// units as read, cross slope in percent), like the transects above.
+static void write_streets(sqlite3* db, const SimulationContext& ctx,
+                          const std::string& sim_id) {
+    const auto& S = ctx.streets;
+    if (S.count() == 0) return;
+    auto stmt = prepare(db,
+        "INSERT INTO streets (simulation_id, street_id, t_crown, h_curb, sx, n_road, "
+        "gutter_depres, gutter_width, sides, back_width, back_slope, back_n) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?)");
+    for (int i = 0; i < S.count(); ++i) {
+        const auto u = static_cast(i);
+        sqlite3_reset(stmt.get());
+        sqlite3_clear_bindings(stmt.get());
+        bind_text(stmt.get(), 1, sim_id);
+        bind_text(stmt.get(), 2, S.names[u]);
+        bind_double(stmt.get(), 3, S.t_crown[u]);
+        bind_double(stmt.get(), 4, S.h_curb[u]);
+        bind_double(stmt.get(), 5, S.sx[u]);
+        bind_double(stmt.get(), 6, S.n_road[u]);
+        bind_double(stmt.get(), 7, S.gutter_depres[u]);
+        bind_double(stmt.get(), 8, S.gutter_width[u]);
+        bind_int(stmt.get(), 9, S.sides[u]);
+        bind_double(stmt.get(), 10, S.back_width[u]);
+        bind_double(stmt.get(), 11, S.back_slope[u]);
+        bind_double(stmt.get(), 12, S.back_n[u]);
+        sqlite3_step(stmt.get());
+    }
+}
+
+static void write_inlets(sqlite3* db, const SimulationContext& ctx,
+                         const std::string& sim_id) {
+    const auto& I = ctx.inlets;
+    if (I.count() == 0) return;
+    auto stmt = prepare(db,
+        "INSERT INTO inlets (simulation_id, inlet_id, inlet_type, length, width, grate_type, "
+        "open_area, splash_veloc, curb_length, curb_height, curb_throat, curve_id, comment) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)");
+    for (int i = 0; i < I.count(); ++i) {
+        const auto u = static_cast(i);
+        sqlite3_reset(stmt.get());
+        sqlite3_clear_bindings(stmt.get());
+        bind_text(stmt.get(), 1, sim_id);
+        bind_text(stmt.get(), 2, I.names[u]);
+        bind_text(stmt.get(), 3, I.inlet_type[u]);
+        bind_double(stmt.get(), 4, I.length[u]);
+        bind_double(stmt.get(), 5, I.width[u]);
+        if (!I.grate_type[u].empty()) bind_text(stmt.get(), 6, I.grate_type[u]);
+        else                          bind_null(stmt.get(), 6);
+        bind_double(stmt.get(), 7, I.open_area[u]);
+        bind_double(stmt.get(), 8, I.splash_veloc[u]);
+        bind_double(stmt.get(), 9, I.curb_length[u]);
+        bind_double(stmt.get(), 10, I.curb_height[u]);
+        bind_int(stmt.get(), 11, I.curb_throat[u]);
+        if (!I.curve_id[u].empty()) bind_text(stmt.get(), 12, I.curve_id[u]);
+        else                        bind_null(stmt.get(), 12);
+        if (u < I.comments.size() && !I.comments[u].empty()) bind_text(stmt.get(), 13, I.comments[u]);
+        else                                                 bind_null(stmt.get(), 13);
+        sqlite3_step(stmt.get());
+    }
+}
+
+static void write_inlet_usage(sqlite3* db, const SimulationContext& ctx,
+                              const std::string& sim_id) {
+    const auto& U = ctx.inlet_usages;
+    if (U.count() == 0) return;
+    auto stmt = prepare(db,
+        "INSERT INTO inlet_usage (simulation_id, host_kind, host_id, inlet_id, capture_node, "
+        "num_inlets, pct_clogged, flow_limit, local_depress, local_width, placement) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?)");
+    for (int r = 0; r < U.count(); ++r) {
+        const auto ur = static_cast(r);
+        const int di = U.design_index[ur];
+        const int ni = U.node_index[ur];
+        const int host_node = U.node_host[ur];
+        const int host_link = U.link_index[ur];
+        // A row whose references never resolved would be dropped on re-read
+        // anyway (as the .inp writer does): skip it rather than write '?'.
+        if (di < 0 || di >= ctx.inlets.count() || ni < 0 || ni >= ctx.n_nodes()) continue;
+        if (host_node < 0 && (host_link < 0 || host_link >= ctx.n_links())) continue;
+        if (host_node >= ctx.n_nodes()) continue;
+        sqlite3_reset(stmt.get());
+        sqlite3_clear_bindings(stmt.get());
+        bind_text(stmt.get(), 1, sim_id);
+        bind_int(stmt.get(), 2, host_node >= 0 ? 1 : 0);
+        bind_text(stmt.get(), 3, host_node >= 0 ? ctx.node_names.name_of(host_node)
+                                                : ctx.link_names.name_of(host_link));
+        bind_text(stmt.get(), 4, ctx.inlets.names[static_cast(di)]);
+        bind_text(stmt.get(), 5, ctx.node_names.name_of(ni));
+        bind_int(stmt.get(), 6, U.num_inlets[ur]);
+        bind_double(stmt.get(), 7, (1.0 - U.clog_factor[ur]) * 100.0);
+        bind_double(stmt.get(), 8, U.flow_limit[ur]);
+        bind_double(stmt.get(), 9, U.local_depress[ur]);
+        bind_double(stmt.get(), 10, U.local_width[ur]);
+        bind_int(stmt.get(), 11, U.placement[ur]);
+        sqlite3_step(stmt.get());
+    }
+}
+
 static void write_controls(sqlite3* db, const SimulationContext& ctx,
                            const std::string& sim_id) {
     const auto& C = ctx.control_rules;
@@ -1567,6 +1697,7 @@ const char* bc_type_token(const twoD::PendingBoundaryRow& r) {
 const char* rainfall_mode_token(twoD::RainfallMode m) {
     switch (m) {
         case twoD::RainfallMode::NATURAL_NEIGHBOUR: return "NATURAL_NEIGHBOUR";
+        case twoD::RainfallMode::NEAREST_NEIGHBOUR: return "NEAREST_NEIGHBOUR";
         case twoD::RainfallMode::SYSTEM:            return "SYSTEM";
         case twoD::RainfallMode::NONE:              return "NONE";
     }
@@ -1624,6 +1755,27 @@ static void write_options_2d(sqlite3* db, const SimulationContext& ctx,
     insert("2D_ADVECTION",         o.advection ? "YES" : "NO");
     insert("2D_COUPLING_AREA",     o.coupling_area_auto ? "AUTO" : "DEFAULT");
     insert("2D_REPORT_2D",         o.report_2d ? "YES" : "NO");
+    // Results-file size controls (same tokens as the .inp grammar).
+    insert("2D_OUTPUT_PRECISION",
+           o.output_precision == twoD::OutputPrecision2D::FLOAT64 ? "FLOAT64" : "FLOAT32");
+    insert("2D_OUTPUT_COMPRESSION", std::to_string(o.output_compression));
+    insert("2D_REPORT_2D_VARIABLES", twoD::report2d::formatMask(o.report_2d_vars));
+    insert("2D_REPORT_2D_SPECIES",   twoD::report2d::formatSpecies(o.report_2d_species));
+    insert("2D_REPORT_2D_STEP",      fmt_g17(o.report_2d_step));
+    // E2 process enables (defaults written too — the reader tolerates absence).
+    insert("2D_INFILTRATION",        o.infiltration < 0 ? "AUTO" : (o.infiltration ? "YES" : "NO"));
+    insert("2D_INFIL_DEFAULT_METHOD", o.infil_default_method.empty() ? "NONE" : o.infil_default_method);
+    insert("2D_INFIL_DESTINATION",   o.infil_destination.empty() ? "LOST" : o.infil_destination);
+    insert("2D_EVAPORATION",         o.evaporation == 0 ? "NO" : (o.evaporation == 2 ? "CLIMATE" : "YES"));
+    insert("2D_TRANSPORT_POLLUTANTS",  o.transport_pollutants  ? "YES" : "NO");
+    insert("2D_TRANSPORT_MSX",         o.transport_msx         ? "YES" : "NO");
+    insert("2D_TRANSPORT_AGE",         o.transport_age         ? "YES" : "NO");
+    insert("2D_TRANSPORT_TEMPERATURE", o.transport_temperature ? "YES" : "NO");
+    // U5 — the groundwater process enable. Tri-state like 2D_INFILTRATION;
+    // GW_ET is not stored here, it belongs to the [2D_AQUIFER_OPTIONS] round
+    // trip (writing it in both places would double-author one setting).
+    insert("2D_GROUNDWATER",
+           o.groundwater < 0 ? "AUTO" : (o.groundwater ? "YES" : "NO"));
     // HDF5 results path — 2D outputs always go to HDF5, never gpkg tables.
     // Restored to SolverOptions2D::output_file on read so SWMMEngine::open
     // re-creates the Default2DOutputPlugin.
@@ -1705,6 +1857,9 @@ static void write_mesh_2d(sqlite3* db, const SimulationContext& ctx,
     };
 
     // ---- triangles -------------------------------------------------------
+    // Cells are triangles first, then quads; tri_idx / quad_idx are the
+    // 0-based positions within each shape, and the triangle's tri_idx is
+    // also its cell index.
     {
         auto stmt = prepare(db,
             "INSERT INTO mesh_2d_triangles "
@@ -1713,9 +1868,11 @@ static void write_mesh_2d(sqlite3* db, const SimulationContext& ctx,
             "VALUES (?,?,?,?,?,?,?,?,?,?,?)");
         std::vector xs(3), ys(3);
         for (int t = 0; t < nt; ++t) {
+            if (mesh.cell_vertex_count(t) != 3) continue;
             sqlite3_reset(stmt.get());
             sqlite3_clear_bindings(stmt.get());
-            const int v[3] = { mesh.tri_v0[t], mesh.tri_v1[t], mesh.tri_v2[t] };
+            const int v[3] = { mesh.cell_vertex(t, 0), mesh.cell_vertex(t, 1),
+                               mesh.cell_vertex(t, 2) };
             bind_text(stmt.get(), 1, sim_id);
             bind_int(stmt.get(), 2, t);
             if (v[0] >= 0 && v[0] < nv && v[1] >= 0 && v[1] < nv &&
@@ -1747,6 +1904,51 @@ static void write_mesh_2d(sqlite3* db, const SimulationContext& ctx,
         }
     }
 
+    // ---- quads -----------------------------------------------------------
+    if (mesh.n_quads() > 0) {
+        auto stmt = prepare(db,
+            "INSERT INTO mesh_2d_quads "
+            "(simulation_id, quad_idx, geom, v0, v1, v2, v3, mannings_n, tag, "
+            "bed_elev, coupled_node, init_depth) "
+            "VALUES (?,?,?,?,?,?,?,?,?,?,?,?)");
+        std::vector xs(4), ys(4);
+        int q = 0;
+        for (int t = 0; t < nt; ++t) {
+            if (mesh.cell_vertex_count(t) != 4) continue;
+            sqlite3_reset(stmt.get());
+            sqlite3_clear_bindings(stmt.get());
+            const int v[4] = { mesh.cell_vertex(t, 0), mesh.cell_vertex(t, 1),
+                               mesh.cell_vertex(t, 2), mesh.cell_vertex(t, 3) };
+            bind_text(stmt.get(), 1, sim_id);
+            bind_int(stmt.get(), 2, q++);
+            bool ok = true;
+            for (int k = 0; k < 4; ++k) ok = ok && v[k] >= 0 && v[k] < nv;
+            if (ok) {
+                for (int k = 0; k < 4; ++k) {
+                    xs[static_cast(k)] = mesh.vx[v[k]] * f;
+                    ys[static_cast(k)] = mesh.vy[v[k]] * f;
+                }
+                auto geom = encode_polygon(xs, ys, srs_id);
+                bind_blob(stmt.get(), 3, geom.data(), static_cast(geom.size()));
+                bind_double(stmt.get(), 10,
+                    (mesh.vz[v[0]] + mesh.vz[v[1]] + mesh.vz[v[2]] + mesh.vz[v[3]]) / 4.0 * f);
+            } else {
+                bind_null(stmt.get(), 3);
+                bind_null(stmt.get(), 10);
+            }
+            for (int k = 0; k < 4; ++k) bind_int(stmt.get(), 4 + k, v[k]);
+            bind_double(stmt.get(), 8, mesh.mannings_n[t]);
+            if (!mesh.tri_tag[t].empty()) bind_text(stmt.get(), 9, mesh.tri_tag[t]);
+            else                          bind_null(stmt.get(), 9);
+            const std::string cn = node_name_for(mesh.tri_coupled_node_name[t],
+                                                 mesh.tri_coupled_node[t]);
+            if (!cn.empty()) bind_text(stmt.get(), 11, cn);
+            else             bind_null(stmt.get(), 11);
+            bind_double(stmt.get(), 12, mesh.tri_init_depth[t]);
+            step_or_throw(db, stmt.get(), "mesh_2d_quads insert failed");
+        }
+    }
+
     // ---- coupling maps ----------------------------------------------------
     {
         auto stmt = prepare(db,
@@ -1794,7 +1996,8 @@ static void write_mesh_2d(sqlite3* db, const SimulationContext& ctx,
     {
         const auto rows = twoD::collectBCRows(
             ctx.twod_io.pending_bc, ctx.twod_io.boundary,
-            opts && opts->pending_rows_drained);
+            opts && opts->pending_rows_drained,
+            opts ? opts->bc_flow_to_si_applied : 1.0);
         if (!rows.empty()) {
             auto stmt = prepare(db,
                 "INSERT OR REPLACE INTO mesh_2d_boundary_conditions "
@@ -1803,7 +2006,7 @@ static void write_mesh_2d(sqlite3* db, const SimulationContext& ctx,
             for (const auto& r : rows) {
                 // Defensive: rows the initialize() drain would silently skip
                 // must not abort the save via an FK violation.
-                if (r.tri < 0 || r.tri >= nt || r.edge < 0 || r.edge > 2) continue;
+                if (r.tri < 0 || r.tri >= nt || r.edge < 0 || r.edge >= mesh.cell_vertex_count(r.tri)) continue;
                 sqlite3_reset(stmt.get());
                 sqlite3_clear_bindings(stmt.get());
                 bind_text(stmt.get(), 1, sim_id);
@@ -1941,6 +2144,9 @@ void write_model(sqlite3* db, const SimulationContext& ctx,
     write_inflows(db, ctx, simulation_id);
     write_dwf(db, ctx, simulation_id);
     write_transects(db, ctx, simulation_id);
+    write_streets(db, ctx, simulation_id);
+    write_inlets(db, ctx, simulation_id);
+    write_inlet_usage(db, ctx, simulation_id);
     write_controls(db, ctx, simulation_id);
 
     // Part E — 2D mesh model definition + solver options. No-ops when the
diff --git a/src/engine/input/geopackage/GeoPackageWriter.hpp b/src/engine/input/geopackage/GeoPackageWriter.hpp
index f30c46eea..0ac799d29 100644
--- a/src/engine/input/geopackage/GeoPackageWriter.hpp
+++ b/src/engine/input/geopackage/GeoPackageWriter.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GeoPackageWriter.hpp
  * @brief Writes a SimulationContext to a GeoPackage file (model input tables).
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_WRITER_HPP
diff --git a/src/engine/input/geopackage/GpkgGeometry.hpp b/src/engine/input/geopackage/GpkgGeometry.hpp
index 7cc213773..55f914d82 100644
--- a/src/engine/input/geopackage/GpkgGeometry.hpp
+++ b/src/engine/input/geopackage/GpkgGeometry.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpkgGeometry.hpp
  * @brief GeoPackage Binary geometry encoding and decoding (ISO WKB with GP header).
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GPKG_GEOMETRY_HPP
diff --git a/src/engine/input/geopackage/GpkgUtils.hpp b/src/engine/input/geopackage/GpkgUtils.hpp
index 4621c9fa9..d6027fc18 100644
--- a/src/engine/input/geopackage/GpkgUtils.hpp
+++ b/src/engine/input/geopackage/GpkgUtils.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file GpkgUtils.hpp
  * @brief RAII wrappers and utilities for SQLite operations in GeoPackage I/O.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GPKG_UTILS_HPP
diff --git a/src/engine/input/geopackage/formats/ClimateFormat.cpp b/src/engine/input/geopackage/formats/ClimateFormat.cpp
index 28f807136..0bc17f8e9 100644
--- a/src/engine/input/geopackage/formats/ClimateFormat.cpp
+++ b/src/engine/input/geopackage/formats/ClimateFormat.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ClimateFormat.cpp
  * @brief User-CSV climate file — parser + materialiser.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ClimateFormat.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include 
 #include 
@@ -58,7 +75,7 @@ double parseOrZero(const std::string& s) {
 
 FormatResult parseClimateCsv(const std::string&        path,
                               std::vector&  rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "r");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "r");
     if (!fp) return fail("could not open '" + path + "' for reading");
 
     char buf[2048];
@@ -106,7 +123,7 @@ FormatResult parseClimateCsv(const std::string&        path,
 
 FormatResult writeClimateCsv(const std::string&             path,
                               const std::vector& rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "w");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "w");
     if (!fp) return fail("could not open '" + path + "' for writing");
     std::fprintf(fp, "date,tmin,tmax,evap,wind,sky,humidity\n");
     for (const auto& r : rows) {
diff --git a/src/engine/input/geopackage/formats/ClimateFormat.hpp b/src/engine/input/geopackage/formats/ClimateFormat.hpp
index 5c7a95503..29b2c36c5 100644
--- a/src/engine/input/geopackage/formats/ClimateFormat.hpp
+++ b/src/engine/input/geopackage/formats/ClimateFormat.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ClimateFormat.hpp
  * @brief User-CSV climate-file parser / materialiser.
@@ -18,7 +34,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_CLIMATE_FORMAT_HPP
diff --git a/src/engine/input/geopackage/formats/FormatTypes.hpp b/src/engine/input/geopackage/formats/FormatTypes.hpp
index e86a570bd..f37f77311 100644
--- a/src/engine/input/geopackage/formats/FormatTypes.hpp
+++ b/src/engine/input/geopackage/formats/FormatTypes.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FormatTypes.hpp
  * @brief Plain-data types shared by every external-file format parser.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_FORMAT_TYPES_HPP
diff --git a/src/engine/input/geopackage/formats/HotstartFormat.cpp b/src/engine/input/geopackage/formats/HotstartFormat.cpp
index 302de9f8c..eb39949c5 100644
--- a/src/engine/input/geopackage/formats/HotstartFormat.cpp
+++ b/src/engine/input/geopackage/formats/HotstartFormat.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HotstartFormat.cpp
  * @brief Legacy HSF v4 binary hot-start file — parser + materialiser.
@@ -8,10 +24,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "HotstartFormat.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include 
 #include 
@@ -48,7 +65,7 @@ bool writeFloat(std::FILE* fp, float v) {
 
 FormatResult parseHotstartHsf(const std::string&  path,
                                HotstartSnapshot&  snapshot) {
-    std::FILE* fp = std::fopen(path.c_str(), "rb");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "rb");
     if (!fp) return fail("could not open '" + path + "' for reading");
 
     // --- File-stamp ---
@@ -182,7 +199,7 @@ FormatResult writeHotstartHsf(const std::string&        path,
         }
     }
 
-    std::FILE* fp = std::fopen(path.c_str(), "wb");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "wb");
     if (!fp) return fail("could not open '" + path + "' for writing");
 
     // Stamp (v4).
diff --git a/src/engine/input/geopackage/formats/HotstartFormat.hpp b/src/engine/input/geopackage/formats/HotstartFormat.hpp
index 58626784a..78493147d 100644
--- a/src/engine/input/geopackage/formats/HotstartFormat.hpp
+++ b/src/engine/input/geopackage/formats/HotstartFormat.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HotstartFormat.hpp
  * @brief Legacy HSF v4 binary hot-start file — parser / materialiser.
@@ -34,7 +50,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_HOTSTART_FORMAT_HPP
diff --git a/src/engine/input/geopackage/formats/RaingageFormat.cpp b/src/engine/input/geopackage/formats/RaingageFormat.cpp
index 438307ac1..8eb0e6414 100644
--- a/src/engine/input/geopackage/formats/RaingageFormat.cpp
+++ b/src/engine/input/geopackage/formats/RaingageFormat.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RaingageFormat.cpp
  * @brief SWMM "Standard" raingage text format — parser + materialiser.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RaingageFormat.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../../../core/DateTime.hpp"
 
@@ -18,7 +35,7 @@ namespace openswmm::gpkg::formats {
 
 FormatResult parseRaingageStd(const std::string&         path,
                                std::vector&  rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "r");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "r");
     if (!fp) return fail("could not open '" + path + "' for reading");
 
     char line[512];
@@ -46,7 +63,7 @@ FormatResult parseRaingageStd(const std::string&         path,
 
 FormatResult writeRaingageStd(const std::string&              path,
                                const std::vector& rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "w");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "w");
     if (!fp) return fail("could not open '" + path + "' for writing");
 
     for (const auto& r : rows) {
diff --git a/src/engine/input/geopackage/formats/RaingageFormat.hpp b/src/engine/input/geopackage/formats/RaingageFormat.hpp
index 44cbd28db..b9396630d 100644
--- a/src/engine/input/geopackage/formats/RaingageFormat.hpp
+++ b/src/engine/input/geopackage/formats/RaingageFormat.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RaingageFormat.hpp
  * @brief SWMM "Standard" raingage text-file parser / materialiser.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_RAINGAGE_FORMAT_HPP
diff --git a/src/engine/input/geopackage/formats/RoutingInterfaceFormat.cpp b/src/engine/input/geopackage/formats/RoutingInterfaceFormat.cpp
index ad107be23..3e3ee55da 100644
--- a/src/engine/input/geopackage/formats/RoutingInterfaceFormat.cpp
+++ b/src/engine/input/geopackage/formats/RoutingInterfaceFormat.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RoutingInterfaceFormat.cpp
  * @brief SWMM5 routing-interface text format — parser + materialiser.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "RoutingInterfaceFormat.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../../../core/DateTime.hpp"
 
@@ -51,7 +68,7 @@ FormatResult parseRoutingInterfaceText(
     RoutingInterfaceMetadata&         meta,
     std::vector& rows) {
 
-    std::FILE* fp = std::fopen(path.c_str(), "r");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "r");
     if (!fp) return fail("could not open '" + path + "' for reading");
 
     char buf[1024];
@@ -177,7 +194,7 @@ FormatResult writeRoutingInterfaceText(
     const RoutingInterfaceMetadata&         meta,
     const std::vector& rows) {
 
-    std::FILE* fp = std::fopen(path.c_str(), "w");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "w");
     if (!fp) return fail("could not open '" + path + "' for writing");
 
     std::fprintf(fp, "SWMM5 Interface File");
diff --git a/src/engine/input/geopackage/formats/RoutingInterfaceFormat.hpp b/src/engine/input/geopackage/formats/RoutingInterfaceFormat.hpp
index 74516f0a4..6fe68aa37 100644
--- a/src/engine/input/geopackage/formats/RoutingInterfaceFormat.hpp
+++ b/src/engine/input/geopackage/formats/RoutingInterfaceFormat.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file RoutingInterfaceFormat.hpp
  * @brief SWMM5 routing interface text format — parser / materialiser.
@@ -32,7 +48,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_ROUTING_INTERFACE_FORMAT_HPP
diff --git a/src/engine/input/geopackage/formats/TimeseriesFormat.cpp b/src/engine/input/geopackage/formats/TimeseriesFormat.cpp
index 438d2f74f..e57c6783c 100644
--- a/src/engine/input/geopackage/formats/TimeseriesFormat.cpp
+++ b/src/engine/input/geopackage/formats/TimeseriesFormat.cpp
@@ -1,13 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TimeseriesFormat.cpp
  * @brief SWMM-native timeseries text format — parser + materialiser.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TimeseriesFormat.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../../../core/DateTime.hpp"
 
@@ -18,7 +35,7 @@ namespace openswmm::gpkg::formats {
 
 FormatResult parseTimeseriesText(const std::string&          path,
                                   std::vector& rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "r");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "r");
     if (!fp) return fail("could not open '" + path + "' for reading");
 
     char line[512];
@@ -51,7 +68,7 @@ FormatResult parseTimeseriesText(const std::string&          path,
 
 FormatResult writeTimeseriesText(const std::string&                path,
                                   const std::vector& rows) {
-    std::FILE* fp = std::fopen(path.c_str(), "w");
+    std::FILE* fp = openswmm::io::fopen_utf8(path, "w");
     if (!fp) return fail("could not open '" + path + "' for writing");
 
     for (const auto& r : rows) {
diff --git a/src/engine/input/geopackage/formats/TimeseriesFormat.hpp b/src/engine/input/geopackage/formats/TimeseriesFormat.hpp
index 370e5be1a..72f023323 100644
--- a/src/engine/input/geopackage/formats/TimeseriesFormat.hpp
+++ b/src/engine/input/geopackage/formats/TimeseriesFormat.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TimeseriesFormat.hpp
  * @brief SWMM-native timeseries text-file parser / materialiser.
@@ -21,7 +37,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_GEOPACKAGE_TIMESERIES_FORMAT_HPP
diff --git a/src/engine/input/handlers/CatchmentHandler.cpp b/src/engine/input/handlers/CatchmentHandler.cpp
index 5d49016d6..8d638a701 100644
--- a/src/engine/input/handlers/CatchmentHandler.cpp
+++ b/src/engine/input/handlers/CatchmentHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file CatchmentHandler.cpp
  * @brief Section handlers for [SUBCATCHMENTS], [SUBAREAS], and [RAINGAGES].
@@ -32,19 +48,22 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "CatchmentHandler.hpp"
 
 #include "../Tokenizer.hpp"
 #include "../SectionParser.hpp"
+#include "../MultiColumnSeriesFile.hpp"
+#include "../../core/ErrorCodes.hpp"
 #include "../../core/SimulationContext.hpp"
 #include "../../data/SubcatchData.hpp"
 #include "../../data/GageData.hpp"
 
 #include "../InputParseUtils.hpp"
 
+#include 
 #include 
 #include 
 
@@ -80,6 +99,11 @@ static void ensure_gage_capacity(SimulationContext& ctx, int idx) {
     grow(ctx.gages.api_rainfall,  -1.0);  // -1 = no API override
     grow(ctx.gages.next_rain_date,0.0);
     grow(ctx.gages.is_raining,    false);
+    grow(ctx.gages.st_cur,  -2);
+    grow(ctx.gages.st_next, -1);
+    grow(ctx.gages.st_rain, 0.0);
+    grow(ctx.gages.st_init, static_cast(0));
+    grow(ctx.gages.st_used, static_cast(0));
 
     // Past-rain tracking (used by updateAllGages for controls past-rain)
     grow(ctx.gages.past_rain_accum,   0.0);
@@ -100,6 +124,10 @@ static void ensure_gage_capacity(SimulationContext& ctx, int idx) {
 // ============================================================================
 
 void handle_subcatchments(SimulationContext& ctx, const std::vector& lines) {
+    // Pre-reserve from the section's row count (an upper bound: some rows
+    // are comments or duplicates). Capacity only — see reserve_to().
+    ctx.subcatches.reserve_to(ctx.subcatches.count() + static_cast(lines.size()));
+    ctx.subcatch_names.reserve(static_cast(ctx.subcatch_names.size()) + lines.size());
     for (const auto& pl : parse_section(lines)) {
         auto tok = Tokenizer::tokenize(pl.data);
         if (tok.size() < 7) continue;
@@ -135,7 +163,11 @@ void handle_subcatchments(SimulationContext& ctx, const std::vector
         }
 
         ctx.subcatches.area[idx]       = to_double(tok[3]);
-        ctx.subcatches.frac_imperv[idx]= to_double(tok[4]) / 100.0;  // % → fraction
+        // Legacy subcatch_readParams: fracImperv = MIN(x[4], 100) / 100 — a
+        // percentage above 100 (w-wo-rb-2subcatchments writes 5000) is a
+        // fully impervious subcatchment, not a 50x area.
+        ctx.subcatches.frac_imperv[idx]=
+            std::min(to_double(tok[4]), 100.0) / 100.0;  // % → fraction
         ctx.subcatches.width[idx]      = to_double(tok[5]);
         ctx.subcatches.slope[idx]      = to_double(tok[6]) / 100.0;  // % → fraction
 
@@ -188,23 +220,38 @@ void handle_subareas(SimulationContext& ctx, const std::vector& lin
         ctx.subcatches.ds_perv[idx]   = to_double(tok[4]);
 
         // PctZero → fraction of impervious with no depression storage
+        // Both forms are kept: the 0-1 fraction every consumer reads, and
+        // the authored percent the runoff kernel needs to reproduce legacy's
+        // `fracImperv * x[4] / 100.0` bit for bit (see pct_zero).
+        ctx.subcatches.pct_zero[idx] = to_double(tok[5]);
         ctx.subcatches.frac_imperv_no_store[idx] = to_double(tok[5]) / 100.0;
 
-        // RouteTo: OUTLET (0), IMPERV (1), or PERV (2)
+        // RouteTo: OUTLET (0), IMPERV (1), or PERV (2). Legacy subcatch.c uses
+        // findmatch(tok[6], {"OUTLET","IMPERV","PERV"}) where match() treats the
+        // keyword as a case-insensitive PREFIX of the token — so the full words
+        // "IMPERVIOUS"/"PERVIOUS" that decks actually write map to IMPERV/PERV.
+        // v6 formerly required an EXACT "IMPERV"/"PERV", so the full words fell
+        // through to OUTLET and silently dropped all inter-subarea runon.
         if (tok.size() > 6) {
             std::string rt = Tokenizer::to_upper(tok[6]);
-            if (rt == "IMPERV")       ctx.subcatches.subarea_routing[idx] = 1;
-            else if (rt == "PERV")    ctx.subcatches.subarea_routing[idx] = 2;
-            else                      ctx.subcatches.subarea_routing[idx] = 0; // OUTLET
-        }
-
-        // PctRouted (default 100%)
-        if (tok.size() > 7) {
-            ctx.subcatches.pct_routed[idx] = to_double(tok[7]) / 100.0;
-        } else if (tok.size() > 6) {
-            // If RouteTo specified but no PctRouted, default to 100%
-            std::string rt = Tokenizer::to_upper(tok[6]);
-            if (rt == "IMPERV" || rt == "PERV")
+            auto has_prefix = [&](const char* p) { return rt.rfind(p, 0) == 0; };
+            int mode = 0;  // OUTLET
+            if      (has_prefix("OUTLET")) mode = 0;
+            else if (has_prefix("IMPERV")) mode = 1;
+            else if (has_prefix("PERV"))   mode = 2;
+            ctx.subcatches.subarea_routing[idx] = mode;
+
+            // PctRouted defaults to 100%, then tok[7] overrides. Legacy sets
+            // x[6] = 1.0 up front for EVERY RouteTo (subcatch.c), including
+            // OUTLET; gating the default on `mode != 0` left OUTLET rows at
+            // the array's initialised 0.0. That is inert in the solver —
+            // fOutlet is only overridden for TO_IMPERV/TO_PERV — but the
+            // writer then emitted an explicit "0.00" where the deck had no
+            // column at all, so a later edit of RouteTo to PERVIOUS would
+            // silently mean 0% routed where the original file meant 100%.
+            if (tok.size() > 7)
+                ctx.subcatches.pct_routed[idx] = to_double(tok[7]) / 100.0;
+            else
                 ctx.subcatches.pct_routed[idx] = 1.0;
         }
     }
@@ -226,12 +273,58 @@ void handle_infiltration(SimulationContext& ctx, const std::vector&
         const int idx = ctx.subcatch_names.find(tok[0]);
         if (idx < 0) continue;
 
-        ctx.subcatches.infil_model[idx] = model;
-        ctx.subcatches.infil_p1[idx] = to_double(tok[1]);
-        ctx.subcatches.infil_p2[idx] = to_double(tok[2]);
-        ctx.subcatches.infil_p3[idx] = to_double(tok[3]);
-        if (tok.size() > 4) ctx.subcatches.infil_p4[idx] = to_double(tok[4]);
-        if (tok.size() > 5) ctx.subcatches.infil_p5[idx] = to_double(tok[5]);
+        // SWMM 5.2 allows a per-subcatchment method override as the LAST
+        // token (legacy infil.c:150-155: findmatch against InfilModelWords).
+        // Without this the keyword parsed as 0.0 into a parameter slot.
+        std::size_t ntoks = tok.size();
+        int row_model = model;
+        {
+            const std::string last = Tokenizer::to_upper(tok[ntoks - 1]);
+            if      (last == "HORTON")         { row_model = 0; --ntoks; }
+            else if (last == "MOD_HORTON" ||
+                     last == "MODIFIED_HORTON") { row_model = 1; --ntoks; }
+            else if (last == "GREEN_AMPT")     { row_model = 2; --ntoks; }
+            else if (last == "MOD_GREEN_AMPT" ||
+                     last == "MODIFIED_GREEN_AMPT") { row_model = 3; --ntoks; }
+            else if (last == "CURVE_NUMBER")   { row_model = 4; --ntoks; }
+        }
+
+        ctx.subcatches.infil_model[idx] = row_model;
+        if (ntoks > 1) ctx.subcatches.infil_p1[idx] = to_double(tok[1]);
+        if (ntoks > 2) ctx.subcatches.infil_p2[idx] = to_double(tok[2]);
+        if (ntoks > 3) ctx.subcatches.infil_p3[idx] = to_double(tok[3]);
+        if (ntoks > 4) ctx.subcatches.infil_p4[idx] = to_double(tok[4]);
+        if (ntoks > 5) ctx.subcatches.infil_p5[idx] = to_double(tok[5]);
+
+        // Parameter validation — legacy infil_readParams raises ERROR 235
+        // when the model's setParams rejects the values (infil.c:198).
+        // Checks run on the RAW display-unit values, as legacy does.
+        const double p1 = ctx.subcatches.infil_p1[idx];
+        const double p2 = ctx.subcatches.infil_p2[idx];
+        const double p3 = ctx.subcatches.infil_p3[idx];
+        const double p4 = ctx.subcatches.infil_p4[idx];
+        const double p5 = ctx.subcatches.infil_p5[idx];
+        bool ok = true;
+        switch (static_cast(row_model)) {
+            case InfiltrationModel::HORTON:
+            case InfiltrationModel::MOD_HORTON:
+                // horton_setParams (infil.c:328): no negatives, f0 >= fmin
+                ok = p1 >= 0.0 && p2 >= 0.0 && p3 >= 0.0 &&
+                     p4 >= 0.0 && p5 >= 0.0 && p1 >= p2;
+                break;
+            case InfiltrationModel::GREEN_AMPT:
+            case InfiltrationModel::MOD_GREEN_AMPT:
+                // grnampt_setParams (infil.c:605): suction >= 0, Ksat > 0,
+                // IMD a fraction in [0, 1]
+                ok = p1 >= 0.0 && p2 > 0.0 && p3 >= 0.0 && p3 <= 1.0;
+                break;
+            case InfiltrationModel::CURVE_NUMBER:
+                // curvenum_setParams (infil.c): drying time (3rd param) > 0
+                ok = p3 > 0.0;
+                break;
+        }
+        if (!ok)
+            ctx.errors.push_back(format_error(ERR_INFILTRATION, ""));
     }
 }
 
@@ -292,24 +385,21 @@ void handle_raingages(SimulationContext& ctx, const std::vector& li
         } else if (src == "FILE" && tok.size() > 5) {
             ctx.gages.source[idx] = RainSource::FILE_RAIN;
 
-            // tok[5] already has quotes stripped by the tokenizer
-            // Check for "path:COLUMN" syntax (R08)
-            const std::string& file_tok = tok[5];
-            const auto colon = file_tok.rfind(':');
-
-            // On Windows, drive letters look like "C:\path" — skip the first char
-            const auto search_start = (file_tok.size() > 1 && file_tok[1] == ':') ? 2 : 0;
-            const auto col_sep = file_tok.find(':', search_start);
-
-            if (col_sep != std::string::npos) {
-                ctx.gages.file_path[idx] = file_tok.substr(0, col_sep);
-                ctx.gages.col_name[idx]  = file_tok.substr(col_sep + 1);
+            // tok[5] already has quotes stripped by the tokenizer.
+            // Check for "path:COLUMN" syntax (R08) using the SHARED split
+            // rule (MultiColumnSeriesFile.hpp) — the timeseries loader used
+            // to split differently, so a path containing a colon produced two
+            // different cache keys for one file and defeated the single-read
+            // guarantee.
+            std::string file_only, file_col;
+            if (split_series_file_token(tok[5], file_only, file_col)) {
+                ctx.gages.file_path[idx]   = file_only;
+                ctx.gages.col_name[idx]    = file_col;
                 ctx.gages.file_format[idx] = RainFileFormat::USER_CSV;
             } else {
-                ctx.gages.file_path[idx]  = file_tok;
+                ctx.gages.file_path[idx]   = file_only;
                 ctx.gages.file_format[idx] = RainFileFormat::STAN_PRCP;
             }
-            (void)colon; // suppress warning
 
             // Standard SWMM FILE grammar (legacy gage.c gage_readParams):
             //   Name Format Interval SCF FILE Fname Station Units [StartDate] [SCF]
diff --git a/src/engine/input/handlers/CatchmentHandler.hpp b/src/engine/input/handlers/CatchmentHandler.hpp
index 3679e011d..a5f6d44a9 100644
--- a/src/engine/input/handlers/CatchmentHandler.hpp
+++ b/src/engine/input/handlers/CatchmentHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file CatchmentHandler.hpp
  * @brief Section handlers for subcatchments and rain gages.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_CATCHMENT_HANDLER_HPP
diff --git a/src/engine/input/handlers/ControlsHandler.cpp b/src/engine/input/handlers/ControlsHandler.cpp
index 904ab4e96..a94674a79 100644
--- a/src/engine/input/handlers/ControlsHandler.cpp
+++ b/src/engine/input/handlers/ControlsHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ControlsHandler.cpp
  * @brief Section handlers for [CONTROLS] and [REPORT].
@@ -38,7 +54,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "ControlsHandler.hpp"
diff --git a/src/engine/input/handlers/ControlsHandler.hpp b/src/engine/input/handlers/ControlsHandler.hpp
index 22916b391..3c78d7eb5 100644
--- a/src/engine/input/handlers/ControlsHandler.hpp
+++ b/src/engine/input/handlers/ControlsHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file ControlsHandler.hpp
  * @brief Section handlers for [CONTROLS] and [REPORT].
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_CONTROLS_HANDLER_HPP
diff --git a/src/engine/input/handlers/FilesHandler.cpp b/src/engine/input/handlers/FilesHandler.cpp
index 2a3e75af1..a7c45d791 100644
--- a/src/engine/input/handlers/FilesHandler.cpp
+++ b/src/engine/input/handlers/FilesHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FilesHandler.cpp
  * @brief [FILES] section handler — secondary file references.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "FilesHandler.hpp"
diff --git a/src/engine/input/handlers/FilesHandler.hpp b/src/engine/input/handlers/FilesHandler.hpp
index d8294aa0f..907534cb0 100644
--- a/src/engine/input/handlers/FilesHandler.hpp
+++ b/src/engine/input/handlers/FilesHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FilesHandler.hpp
  * @brief [FILES] section handler — secondary file references.
@@ -25,7 +41,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_FILES_HANDLER_HPP
diff --git a/src/engine/input/handlers/HydrologyHandler.cpp b/src/engine/input/handlers/HydrologyHandler.cpp
index 9cab4b1af..2c97352b4 100644
--- a/src/engine/input/handlers/HydrologyHandler.cpp
+++ b/src/engine/input/handlers/HydrologyHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydrologyHandler.cpp
  * @brief Section handlers for [EVAPORATION], [TEMPERATURE], [SNOWPACKS],
@@ -20,6 +36,7 @@
  * FILE  "filename"  StartDate
  * WINDSPEED  MONTHLY  1.0 1.0 ... (12 values)
  * WINDSPEED  FILE
+ * HUMIDITY  [DEWPOINT]  value | MONTHLY h1 ... h12 | TIMESERIES name
  * SNOWMELT  divT  ATIwt  nrgRatio  lat  minMelt  maxMelt
  * ADC  IMPERVIOUS  frac1  frac2  ... frac10
  * ADC  PERVIOUS    frac1  frac2  ... frac10
@@ -62,15 +79,17 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "HydrologyHandler.hpp"
 
 #include "../Tokenizer.hpp"
+#include "../../core/Constants.hpp"
 #include "../../core/SimulationContext.hpp"
 #include "../../data/SubcatchData.hpp"
 #include "../../data/HydrologyData.hpp"
+#include "../../hydrology/Groundwater.hpp"
 
 #include "../InputParseUtils.hpp"
 
@@ -135,7 +154,10 @@ static void ensure_subcatch_gw_capacity(SimulationContext& ctx, int idx) {
     grow(ctx.subcatches.gw_b2,        0.0);
     grow(ctx.subcatches.gw_a3,        0.0);
     grow(ctx.subcatches.gw_tw,        0.0);
-    grow(ctx.subcatches.gw_hstar,     0.0);
+    grow(ctx.subcatches.gw_hstar,     constants::MISSING);
+    grow(ctx.subcatches.gw_bot_elev,  constants::MISSING);
+    grow(ctx.subcatches.gw_wt_elev,   constants::MISSING);
+    grow(ctx.subcatches.gw_upper_moist, constants::MISSING);
 }
 
 // ============================================================================
@@ -224,32 +246,61 @@ void handle_temperature(SimulationContext& ctx, const std::vector&
                 ctx.options.wind_type = 1;
             }
         }
+        // H2: relative humidity, % — the met input SurfaceExchange needs and
+        // the first thing ever to write ClimateState::humidity, which has
+        // carried a 50 % default with no writer. Forms:
+        //   HUMIDITY [DEWPOINT] 
+        //   HUMIDITY [DEWPOINT] MONTHLY h1 ... h12
+        //   HUMIDITY [DEWPOINT] TIMESERIES 
+        // A bare value is CONSTANT and fills all twelve months. DEWPOINT
+        // stores dew-point temperature (project temperature units) that the
+        // engine converts to RH each step.
+        else if (key == "HUMIDITY" && tok.size() >= 2) {
+            std::size_t p = 1;
+            ctx.options.humidity_var = 0;
+            if (Tokenizer::to_upper(tok[p]) == "DEWPOINT") {
+                ctx.options.humidity_var = 1;
+                ++p;
+            }
+            if (p >= tok.size()) continue;
+            const std::string htype = Tokenizer::to_upper(tok[p]);
+            if (htype == "MONTHLY" && tok.size() >= p + 13) {
+                ctx.options.humidity_type = 1;
+                for (int i = 0; i < 12; ++i)
+                    ctx.options.humidity[i] = to_double(tok[p + 1 + static_cast(i)]);
+            }
+            else if (htype == "TIMESERIES" && tok.size() >= p + 2) {
+                ctx.options.humidity_type = 2;
+                ctx.options.humidity_ts_name = tok[p + 1];
+            }
+            else if (htype != "MONTHLY" && htype != "TIMESERIES") {
+                ctx.options.humidity_type = 0;
+                const double h = to_double(tok[p]);
+                for (int i = 0; i < 12; ++i) ctx.options.humidity[i] = h;
+            }
+        }
         else if (key == "SNOWMELT" && tok.size() >= 7) {
-            // Legacy [TEMPERATURE] SNOWMELT format (9 tokens):
-            //   SNOWMELT divT ATIwt nrgRatio elev lat dtlong minMelt maxMelt
-            // New engine format (7 tokens):
-            //   SNOWMELT divT ATIwt nrgRatio lat minMelt maxMelt
-            // Disambiguate: if 9+ tokens, treat as legacy (elevation at tok[4])
+            // Legacy [TEMPERATURE] SNOWMELT line (climate.c case 3):
+            //   SNOWMELT Stemp ATIwt RNM Elev Lat DTLong
+            // Stemp and Elev stay in the deck's units here (degC / m on an
+            // SI deck) and are converted at init like legacy's.
+            // A previous reading took a 7-token line as a v6-only
+            // "divT ATIwt nrgRatio lat minMelt maxMelt" form, so every
+            // standard deck had its elevation read as the latitude and no
+            // elevation at all (psychrometric constant at sea level).
+            // Tokens 7-8, when present, are the v6-only minMelt/maxMelt
+            // (unused by the solver; legacy ignores extra tokens).
             ctx.options.snow_divt      = to_double(tok[1]);
             ctx.options.snow_ati_wt    = to_double(tok[2]);
             ctx.options.snow_nrg_ratio = to_double(tok[3]);
+            ctx.options.snow_elev      = to_double(tok[4]);
+            ctx.options.snow_lat       = to_double(tok[5]);
+            // tok[6] = longitude/solar-time correction (minutes); stored
+            // verbatim and converted to hours at init (legacy climate.c).
+            ctx.options.snow_dtlong    = to_double(tok[6]);
             if (tok.size() >= 9) {
-                // Legacy: elev at [4], lat at [5], dtlong at [6], min at [7], max at [8]
-                ctx.options.snow_elev      = to_double(tok[4]);
-                ctx.options.snow_lat       = to_double(tok[5]);
-                // tok[6] = longitude/solar-time correction (minutes); stored
-                // verbatim and converted to hours at init (legacy climate.c).
-                ctx.options.snow_dtlong    = to_double(tok[6]);
                 ctx.options.snow_min_melt  = to_double(tok[7]);
                 ctx.options.snow_max_melt  = to_double(tok[8]);
-            } else {
-                // New engine: lat at [4], min at [5], max at [6]
-                ctx.options.snow_lat       = to_double(tok[4]);
-                ctx.options.snow_min_melt  = to_double(tok[5]);
-                ctx.options.snow_max_melt  = to_double(tok[6]);
-                // Optional elevation at tok[7] (new extended format)
-                if (tok.size() >= 8)
-                    ctx.options.snow_elev  = to_double(tok[7]);
             }
         }
         else if (key == "ADC" && tok.size() >= 12) {
@@ -351,8 +402,15 @@ void handle_aquifers(SimulationContext& ctx, const std::vector& lin
 void handle_groundwater(SimulationContext& ctx, const std::vector& lines) {
     for (const auto& line : lines) {
         auto tok = Tokenizer::tokenize(line);
-        if (tok.size() < 11) continue;
+        if (tok.empty()) continue;
         // Subcatch  Aquifer  Node  SurfEl  A1  B1  A2  B2  A3  Twgr  Hstar
+        // Legacy gwater.c gwater_readGroundwaterParams requires >= 11 tokens;
+        // fewer is ERR_ITEMS (too few items). v6 formerly skipped short rows
+        // silently, so a truncated row ran instead of being rejected.
+        if (tok.size() < 11) {
+            ctx.errors.push_back(format_error(ERR_ITEMS, ""));
+            continue;
+        }
 
         const int idx = ctx.subcatch_names.find(tok[0]);
         if (idx < 0) continue;
@@ -361,6 +419,9 @@ void handle_groundwater(SimulationContext& ctx, const std::vector&
 
         ctx.subcatches.gw_aquifer[idx]   = ctx.aquifer_names.find(tok[1]);
         ctx.subcatches.gw_node[idx]      = ctx.node_names.find(tok[2]);
+        // [GROUNDWATER] normally precedes [JUNCTIONS], so the find() above
+        // returns -1 for a forward reference. Defer to PostParseResolver.
+        ctx.pending_gw_nodes.emplace_back(idx, tok[2]);
         ctx.subcatches.gw_surf_elev[idx] = to_double(tok[3]);
         ctx.subcatches.gw_a1[idx]        = to_double(tok[4]);
         ctx.subcatches.gw_b1[idx]        = to_double(tok[5]);
@@ -368,7 +429,18 @@ void handle_groundwater(SimulationContext& ctx, const std::vector&
         ctx.subcatches.gw_b2[idx]        = to_double(tok[7]);
         ctx.subcatches.gw_a3[idx]        = to_double(tok[8]);
         ctx.subcatches.gw_tw[idx]        = to_double(tok[9]);
-        ctx.subcatches.gw_hstar[idx]     = to_double(tok[10]);
+        // Optional Egwt Ebot Wgw Umc (legacy x[7..10]): absent or `*` is
+        // MISSING — the receiving node's invert for Egwt, the aquifer's
+        // values for the other three (legacy gwater_validate). Stored in the
+        // deck's units like the fields above; the engine converts at init.
+        auto opt = [&](std::size_t k) {
+            return (tok.size() > k && tok[k] != "*") ? to_double(tok[k])
+                                                     : constants::MISSING;
+        };
+        ctx.subcatches.gw_hstar[idx]       = opt(10);
+        ctx.subcatches.gw_bot_elev[idx]    = opt(11);
+        ctx.subcatches.gw_wt_elev[idx]     = opt(12);
+        ctx.subcatches.gw_upper_moist[idx] = opt(13);
     }
 }
 
@@ -384,14 +456,53 @@ void handle_gwf(SimulationContext& ctx, const std::vector& lines) {
         auto tok = Tokenizer::tokenize(line);
         if (tok.size() < 3) continue;
 
-        const std::string& subcatch = tok[0];
-        const std::string type = Tokenizer::to_upper(tok[1]);
+        // Key on the [SUBCATCHMENTS] spelling so a mixed-case name in [GWF]
+        // still matches the lookup at start() and the writer (both use the
+        // registry name). An unknown subcatchment keeps the typed name, as
+        // handle_groundwater() tolerates an unresolved name.
+        const std::string* canon = ctx.subcatch_names.canonical(tok[0]);
+        const std::string& subcatch = canon ? *canon : tok[0];
+
+        // Legacy gwater.c accepts any "LAT..." spelling for LATERAL.
+        const std::string type_tok = Tokenizer::to_upper(tok[1]);
+        std::string type;
+        if (type_tok.rfind("LAT", 0) == 0) type = "LATERAL";
+        else if (type_tok == "DEEP")       type = "DEEP";
+        else {
+            ctx.errors.push_back(format_error(ERR_KEYWORD, tok[1]));
+            continue;
+        }
 
-        // Reconstruct expression from remaining tokens
-        std::string expr;
-        for (std::size_t i = 2; i < tok.size(); ++i) {
-            if (!expr.empty()) expr += ' ';
-            expr += tok[i];
+        // The expression is free text — take it verbatim from the line.
+        // Re-joining the tokenizer's output would drop the ',' between
+        // min/max arguments (the tokenizer treats a comma as a column
+        // separator), turning "MIN(HGW, HCB)" into "MIN(HGW HCB)".
+        std::string_view rest = Tokenizer::strip_comment(line);
+        for (int col = 0; col < 2; ++col) {          // skip Subcatch, Type
+            std::size_t i = 0;
+            while (i < rest.size() && (rest[i] == ' ' || rest[i] == '\t')) ++i;
+            if (i < rest.size() && rest[i] == '"') {
+                ++i;
+                while (i < rest.size() && rest[i] != '"') ++i;
+                if (i < rest.size()) ++i;
+            } else {
+                while (i < rest.size() && rest[i] != ' ' && rest[i] != '\t' &&
+                       rest[i] != ',') ++i;
+            }
+            while (i < rest.size() && (rest[i] == ' ' || rest[i] == '\t')) ++i;
+            if (i < rest.size() && rest[i] == ',') ++i;  // optional CSV comma
+            rest.remove_prefix(i);
+        }
+        std::string expr(Tokenizer::trim(rest));
+
+        // mathexpr::parse is lenient (unknown identifiers evaluate to 0.0),
+        // so reject malformed expressions here like legacy ERR_MATH_EXPR.
+        std::string msg;
+        int col = -1;
+        if (groundwater::gwf_validate(expr, msg, col) != 0) {
+            ctx.errors.push_back(format_error(ERR_MATH_EXPR, "",
+                "in [GWF] " + type + " for Subcatchment " + subcatch + ": " + msg));
+            continue;
         }
 
         std::string key = "GWF:" + subcatch + ":" + type;
diff --git a/src/engine/input/handlers/HydrologyHandler.hpp b/src/engine/input/handlers/HydrologyHandler.hpp
index 165cb6422..a78434922 100644
--- a/src/engine/input/handlers/HydrologyHandler.hpp
+++ b/src/engine/input/handlers/HydrologyHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file HydrologyHandler.hpp
  * @brief Section handlers for hydrology-related input sections.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_HYDROLOGY_HANDLER_HPP
diff --git a/src/engine/input/handlers/InflowsHandler.cpp b/src/engine/input/handlers/InflowsHandler.cpp
index 15be3f225..1d2920419 100644
--- a/src/engine/input/handlers/InflowsHandler.cpp
+++ b/src/engine/input/handlers/InflowsHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InflowsHandler.cpp
  * @brief Section handlers for [PATTERNS], [INFLOWS], [DWF], [RDII],
@@ -33,7 +49,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "InflowsHandler.hpp"
diff --git a/src/engine/input/handlers/InflowsHandler.hpp b/src/engine/input/handlers/InflowsHandler.hpp
index 9617f8a14..b2b5287f2 100644
--- a/src/engine/input/handlers/InflowsHandler.hpp
+++ b/src/engine/input/handlers/InflowsHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InflowsHandler.hpp
  * @brief Section handlers for patterns, inflows, DWF, and RDII.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INFLOWS_HANDLER_HPP
diff --git a/src/engine/input/handlers/InfraHandler.cpp b/src/engine/input/handlers/InfraHandler.cpp
index 1e026cb1e..a5b9ab837 100644
--- a/src/engine/input/handlers/InfraHandler.cpp
+++ b/src/engine/input/handlers/InfraHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InfraHandler.cpp
  * @brief Section handlers for [STREETS], [INLETS], [INLET_USAGE],
@@ -8,17 +24,20 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "InfraHandler.hpp"
+#include "NodesHandler.hpp"
 #include "../Tokenizer.hpp"
+#include "../SectionParser.hpp"
 #include "../../core/SimulationContext.hpp"
 #include "../InputParseUtils.hpp"
 #include "../../core/DateTime.hpp"
 
 #include 
 #include 
+#include 
 
 namespace openswmm::input {
 
@@ -61,37 +80,194 @@ void handle_streets(SimulationContext& ctx, const std::vector& line
 // handle_inlets()
 // ============================================================================
 
+namespace {
+
+/// Grate bar patterns, legacy inlet.c GrateTypeWords order.
+const char* const kGrateTypeWords[] = {
+    "P_BAR-50", "P_BAR-50x100", "P_BAR-30", "CURVED_VANE",
+    "TILT_BAR-45", "TILT_BAR-30", "RETICULINE", "GENERIC"};
+
+/// Curb-opening throat orientations, legacy inlet.c ThroatAngleWords order.
+const char* const kThroatWords[] = {"HORIZONTAL", "INCLINED", "VERTICAL"};
+
+/// -1 when `w` is not one of `words`.
+int find_word(const char* const* words, int n, std::string_view w) {
+    for (int i = 0; i < n; ++i)
+        if (ieq(words[i], w)) return i;
+    return -1;
+}
+
+/// Row index of the inlet design named `name`, or -1.
+int find_inlet_design(const SimulationContext& ctx, std::string_view name) {
+    for (int i = 0; i < ctx.inlets.count(); ++i)
+        if (ieq(ctx.inlets.names[static_cast(i)], name)) return i;
+    return -1;
+}
+
+/// The optional tail shared by [INLET_USAGE] tokens 4-9 and
+/// [INLET_JUNCTIONS] tokens 6-11 (plan §2.3).
+struct UsageTail {
+    int    num_inlets    = 1;
+    int    placement     = 0;     ///< 0=AUTOMATIC 1=ON_GRADE 2=ON_SAG
+    double clog_factor   = 1.0;
+    double flow_limit    = 0.0;
+    double local_depress = 0.0;
+    double local_width   = 0.0;
+};
+
+/// Parse the tail beginning at token `first`. Pushes the legacy parse error
+/// and returns false on the first bad token (inlet.c:405-431).
+bool parse_inlet_usage_tail(SimulationContext& ctx,
+                            const std::vector& tok,
+                            std::size_t first, UsageTail& out) {
+    auto num = [&](std::size_t k, double& v, double lo, double hi) {
+        v = to_double(tok[k], -1.0);
+        if (v < lo || v > hi) {
+            ctx.errors.push_back(format_error(ERR_NUMBER, tok[k]));
+            return false;
+        }
+        return true;
+    };
+
+    if (tok.size() > first) {
+        out.num_inlets = to_int(tok[first], 0);
+        if (out.num_inlets < 1) {
+            ctx.errors.push_back(format_error(ERR_NUMBER, tok[first]));
+            return false;
+        }
+    }
+    if (tok.size() > first + 1) {
+        double pct = 0.0;
+        if (!num(first + 1, pct, 0.0, 99.0)) return false;
+        out.clog_factor = 1.0 - pct / 100.0;
+    }
+    if (tok.size() > first + 2 &&
+        !num(first + 2, out.flow_limit, 0.0, 1.0e30)) return false;
+    if (tok.size() > first + 3 &&
+        !num(first + 3, out.local_depress, 0.0, 1.0e30)) return false;
+    if (tok.size() > first + 4 &&
+        !num(first + 4, out.local_width, 0.0, 1.0e30)) return false;
+    if (tok.size() > first + 5) {
+        static const char* const kPlacementWords[] = {"AUTOMATIC", "ON_GRADE", "ON_SAG"};
+        out.placement = find_word(kPlacementWords, 3, tok[first + 5]);
+        if (out.placement < 0) {
+            ctx.errors.push_back(format_error(ERR_KEYWORD, tok[first + 5]));
+            return false;
+        }
+    }
+    return true;
+}
+
+void apply_usage_tail(InletUsageStore& u, int row, const UsageTail& t) {
+    const auto ur = static_cast(row);
+    u.num_inlets[ur]    = t.num_inlets;
+    u.placement[ur]     = t.placement;
+    u.clog_factor[ur]   = t.clog_factor;
+    u.flow_limit[ur]    = t.flow_limit;
+    u.local_depress[ur] = t.local_depress;
+    u.local_width[ur]   = t.local_width;
+}
+
+} // namespace
+
 void handle_inlets(SimulationContext& ctx, const std::vector& lines) {
-    // Format varies by type:
+    // Format varies by type (legacy inlet.c:321-327):
     //   ID  GRATE       Length  Width  GrateType  (OpenArea)  (SplashVeloc)
     //   ID  CURB        Length  Height (ThroatType)
     //   ID  SLOTTED     Length  Width
     //   ID  DROP_GRATE  Length  Width  GrateType  (OpenArea)  (SplashVeloc)
     //   ID  DROP_CURB   Length  Height
     //   ID  CUSTOM      CurveID
-    for (const auto& line : lines) {
-        auto tok = Tokenizer::tokenize(line);
+    // A GRATE line and a CURB line sharing one name are the legacy encoding of
+    // a combination inlet: the second line MERGES into the first row and
+    // retypes it COMBO (there is no COMBO keyword). Any other repeat of a name
+    // is a duplicate ID, as for [STREETS].
+    for (const auto& pl : parse_section(lines)) {
+        auto tok = Tokenizer::tokenize(pl.data);
         if (tok.size() < 3) continue;
 
-        std::string inlet_type = Tokenizer::to_upper(tok[1]);
-
-        ctx.inlets.names.push_back(std::string(tok[0]));
-        ctx.inlets.inlet_type.push_back(inlet_type);
-
-        if (inlet_type == "CUSTOM") {
-            // Custom inlet — tok[2] is curve ID, no numeric geometry
-            ctx.inlets.length.push_back(0.0);
-            ctx.inlets.width.push_back(0.0);
-            ctx.inlets.grate_type.push_back(std::string(tok[2])); // curve ID stored here
-            ctx.inlets.open_area.push_back(0.0);
-            ctx.inlets.splash_veloc.push_back(0.0);
-        } else {
-            ctx.inlets.length.push_back(tok.size() > 2 ? to_double(tok[2]) : 0.0);
-            ctx.inlets.width.push_back(tok.size() > 3 ? to_double(tok[3]) : 0.0);
-            ctx.inlets.grate_type.push_back(tok.size() > 4 ? std::string(tok[4]) : "");
-            ctx.inlets.open_area.push_back(tok.size() > 5 ? to_double(tok[5]) : 0.0);
-            ctx.inlets.splash_veloc.push_back(tok.size() > 6 ? to_double(tok[6]) : 0.0);
+        const std::string type = Tokenizer::to_upper(tok[1]);
+        const bool is_grate   = (type == "GRATE" || type == "DROP_GRATE");
+        const bool is_curb    = (type == "CURB"  || type == "DROP_CURB");
+        const bool is_slotted = (type == "SLOTTED");
+        const bool is_custom  = (type == "CUSTOM");
+        if (!is_grate && !is_curb && !is_slotted && !is_custom) {
+            ctx.errors.push_back(format_error(ERR_KEYWORD, tok[1]));
+            continue;
+        }
+
+        // --- Duplicate name: merge a GRATE/CURB pair, reject anything else ---
+        const int prev = find_inlet_design(ctx, tok[0]);
+        if (prev >= 0) {
+            const std::string& prev_type =
+                ctx.inlets.inlet_type[static_cast(prev)];
+            const bool combo = (prev_type == "GRATE" && type == "CURB") ||
+                               (prev_type == "CURB"  && type == "GRATE");
+            if (!combo) {
+                ctx.errors.push_back(format_error(ERR_DUP_NAME, tok[0]));
+                continue;
+            }
+        }
+
+        // --- Type-specific token count + range checks (legacy read*Params) ---
+        double length = 0.0, width = 0.0, open_area = 0.0, splash = 0.0;
+        int grate_type = -1, throat = 2;   // default VERTICAL
+
+        if (is_grate || is_curb || is_slotted) {
+            const std::size_t need = is_grate ? 5u : 4u;
+            if (tok.size() < need) {
+                ctx.errors.push_back(format_error(ERR_ITEMS, tok[0]));
+                continue;
+            }
+            length = to_double(tok[2], -1.0);
+            width  = to_double(tok[3], -1.0);   // CURB/DROP_CURB: opening height
+            if (length <= 0.0) { ctx.errors.push_back(format_error(ERR_NUMBER, tok[2])); continue; }
+            if (width  <= 0.0) { ctx.errors.push_back(format_error(ERR_NUMBER, tok[3])); continue; }
+        }
+        if (is_grate) {
+            grate_type = find_word(kGrateTypeWords, 8, tok[4]);
+            if (grate_type < 0) { ctx.errors.push_back(format_error(ERR_KEYWORD, tok[4])); continue; }
+            if (grate_type == 7) {   // GENERIC: open area is required
+                if (tok.size() < 6) { ctx.errors.push_back(format_error(ERR_ITEMS, tok[0])); continue; }
+                open_area = to_double(tok[5], -1.0);
+                if (open_area <= 0.0 || open_area > 1.0) {
+                    ctx.errors.push_back(format_error(ERR_NUMBER, tok[5]));
+                    continue;
+                }
+                if (tok.size() > 6) {
+                    splash = to_double(tok[6], -1.0);
+                    if (splash < 0.0) { ctx.errors.push_back(format_error(ERR_NUMBER, tok[6])); continue; }
+                }
+            }
+        }
+        if (type == "CURB" && tok.size() > 4) {   // DROP_CURB has no throat token
+            throat = find_word(kThroatWords, 3, tok[4]);
+            if (throat < 0) { ctx.errors.push_back(format_error(ERR_KEYWORD, tok[4])); continue; }
         }
+
+        // --- Write (new row, or merge into the existing half of a COMBO) ---
+        const int idx = (prev >= 0) ? prev : ctx.inlets.add_row(std::string(tok[0]), type);
+        const auto ui = static_cast(idx);
+        if (prev >= 0) ctx.inlets.inlet_type[ui] = "COMBO";
+
+        if (is_grate) {
+            ctx.inlets.length[ui]       = length;
+            ctx.inlets.width[ui]        = width;
+            ctx.inlets.grate_type[ui]   = kGrateTypeWords[grate_type];
+            ctx.inlets.open_area[ui]    = open_area;
+            ctx.inlets.splash_veloc[ui] = splash;
+        } else if (is_curb) {
+            ctx.inlets.curb_length[ui] = length;
+            ctx.inlets.curb_height[ui] = width;
+            ctx.inlets.curb_throat[ui] = throat;
+        } else if (is_slotted) {
+            ctx.inlets.length[ui] = length;
+            ctx.inlets.width[ui]  = width;
+        } else {   // CUSTOM — the curve is resolved in PostParseResolver
+            ctx.inlets.curve_id[ui] = std::string(tok[2]);
+        }
+        if (!pl.comment.empty() && ctx.inlets.comments[ui].empty())
+            ctx.inlets.comments[ui] = pl.comment;
     }
 }
 
@@ -106,44 +282,73 @@ void handle_inlet_usage(SimulationContext& ctx, const std::vector&
         if (tok.size() < 3) continue;
 
         const int link_idx = ctx.link_names.find(tok[0]);
-        if (link_idx < 0) continue;
-
-        // Find inlet design index by name (case-insensitive)
-        int design_idx = -1;
-        for (int i = 0; i < ctx.inlets.count(); ++i) {
-            if (ieq(ctx.inlets.names[static_cast(i)], tok[1])) {
-                design_idx = i;
-                break;
-            }
-        }
-        if (design_idx < 0) continue;
+        if (link_idx < 0) { ctx.errors.push_back(format_error(ERR_NAME, tok[0])); continue; }
+
+        const int design_idx = find_inlet_design(ctx, tok[1]);
+        if (design_idx < 0) { ctx.errors.push_back(format_error(ERR_NAME, tok[1])); continue; }
 
+        // The capture node may be declared after this section (legacy parsing
+        // is order-independent), so an unresolved name is deferred to
+        // PostParseResolver like the [INLET_JUNCTIONS] grammar's — ERR_NAME
+        // there if it never appears.
         const int node_idx = ctx.node_names.find(tok[2]);
-        if (node_idx < 0) continue;
-
-        int num_inlets = tok.size() > 3 ? to_int(tok[3], 1) : 1;
-        double pct_clog = tok.size() > 4 ? to_double(tok[4]) : 0.0;
-        double flow_limit = tok.size() > 5 ? to_double(tok[5]) : 0.0;
-        double a_local = tok.size() > 6 ? to_double(tok[6]) : 0.0;
-        double w_local = tok.size() > 7 ? to_double(tok[7]) : 0.0;
-
-        int placement = 0; // AUTO
-        if (tok.size() > 8) {
-            std::string p = Tokenizer::to_upper(tok[8]);
-            if (p == "ON_GRADE") placement = 1;
-            else if (p == "ON_SAG") placement = 2;
-        }
-
-        ctx.inlet_usages.link_index.push_back(link_idx);
-        ctx.inlet_usages.design_index.push_back(design_idx);
-        ctx.inlet_usages.node_index.push_back(node_idx);
-        ctx.inlet_usages.num_inlets.push_back(num_inlets);
-        ctx.inlet_usages.placement.push_back(placement);
-        ctx.inlet_usages.clog_factor.push_back(1.0 - pct_clog / 100.0);
-        ctx.inlet_usages.flow_limit.push_back(flow_limit);
-        ctx.inlet_usages.local_depress.push_back(a_local);
-        ctx.inlet_usages.local_width.push_back(w_local);
-        ctx.inlet_usages.street_index.push_back(-1);
+
+        UsageTail tail;
+        if (!parse_inlet_usage_tail(ctx, tok, 3, tail)) continue;
+
+        // street_index stays -1 here: it is a property of the host conduit's
+        // cross-section and is resolved in PostParseResolver (plan §4.8).
+        const int row = ctx.inlet_usages.add_row(link_idx, -1, design_idx, node_idx);
+        apply_usage_tail(ctx.inlet_usages, row, tail);
+        if (node_idx < 0)
+            ctx.inlet_usages.pending_capture_name[static_cast(row)] = tok[2];
+    }
+}
+
+// ============================================================================
+// handle_inlet_junctions()
+// ============================================================================
+
+void handle_inlet_junctions(SimulationContext& ctx, const std::vector& lines) {
+    // Format: Name Elev MaxDepth Inlet CaptureNode
+    //         (#Inlets %Clog Qmax aLocal wLocal Placement)
+    // Tokens 1-3 mirror [VIRTUAL_JUNCTIONS]; tokens 4-11 are the
+    // [INLET_USAGE] tail, so both grammars share parse_inlet_usage_tail.
+    for (const auto& pl : parse_section(lines)) {
+        auto tok = Tokenizer::tokenize(pl.data);
+        if (tok.size() < 5) continue;
+
+        const std::string& name = tok[0];
+        if (tok.size() > 11) {
+            ctx.errors.push_back(format_error(ERR_IJ_EXTRA_TOKENS, name));
+            continue;
+        }
+
+        UsageTail tail;
+        if (!parse_inlet_usage_tail(ctx, tok, 5, tail)) continue;
+
+        const int idx = add_unique(ctx.node_names, name, ctx.errors);
+        if (idx < 0) continue;  // duplicate ID (ERR 207, legacy input.c parity)
+
+        ctx.nodes.grow_to(idx + 1);
+        ctx.node_subtypes.set_node_type(ctx.nodes, idx, NodeType::JUNCTION);
+        const auto ui = static_cast(idx);
+        ctx.nodes.is_virtual[ui] = 1;
+        ctx.nodes.is_inlet[ui]   = 1;
+        ctx.nodes.invert_elev[ui] = to_double(tok[1]);
+        // MaxDepth: the flood threshold above the street invert (plan D-E2);
+        // like a virtual junction's it is carried in rim_depth, and a missing
+        // or negative value collapses to 0 = derive from the street section.
+        ctx.nodes.rim_depth[ui] = std::max(0.0, to_double(tok[2]));
+        if (!pl.comment.empty()) ctx.nodes.comments[ui] = pl.comment;
+
+        // The design and the capture node may be declared after this section,
+        // so both names are resolved in PostParseResolver (623/625/627).
+        const int row = ctx.inlet_usages.add_row(-1, idx, -1, -1);
+        apply_usage_tail(ctx.inlet_usages, row, tail);
+        const auto ur = static_cast(row);
+        ctx.inlet_usages.pending_design_name[ur]  = tok[3];
+        ctx.inlet_usages.pending_capture_name[ur] = tok[4];
     }
 }
 
@@ -165,31 +370,46 @@ void handle_adjustments(SimulationContext& ctx, const std::vector&
         auto tok = Tokenizer::tokenize(line);
         if (tok.size() < 2) continue;
 
-        std::string keyword = Tokenizer::to_upper(tok[0]);
+        const std::string keyword = Tokenizer::to_upper(tok[0]);
+        // legacy climate_readAdjustments uses match(): the keyword is a
+        // case-insensitive PREFIX of the token, so the long spellings
+        // `TEMPERATURE`, `EVAPORATION`, `RAINFALL`, `CONDUCTIVITY` (what
+        // several corpus decks write) bind too. An exact compare dropped
+        // them silently (usgs-runoff's +0.01 mm/day July evaporation).
+        auto kw = [&](const char* k) {
+            const std::size_t n = std::strlen(k);
+            return keyword.size() >= n && keyword.compare(0, n, k) == 0;
+        };
 
         // Monthly arrays: TEMP, EVAP, RAIN, CONDUCT (need 13 tokens total)
-        if (keyword == "TEMP" && tok.size() >= 13) {
+        if (kw("TEMP") && tok.size() >= 13) {
             for (int i = 0; i < 12; ++i)
                 ctx.adjust_temp[i] = to_double(tok[static_cast(i + 1)]);
         }
-        else if (keyword == "EVAP" && tok.size() >= 13) {
+        else if (kw("EVAP") && tok.size() >= 13) {
             for (int i = 0; i < 12; ++i)
                 ctx.adjust_evap[i] = to_double(tok[static_cast(i + 1)]);
         }
-        else if (keyword == "RAIN" && tok.size() >= 13) {
+        else if (kw("RAIN") && tok.size() >= 13) {
             for (int i = 0; i < 12; ++i)
                 ctx.adjust_rain[i] = to_double(tok[static_cast(i + 1)]);
         }
-        else if (keyword == "CONDUCT" && tok.size() >= 13) {
+        else if (kw("CONDUCT") && tok.size() >= 13) {
             for (int i = 0; i < 12; ++i) {
                 double v = to_double(tok[static_cast(i + 1)]);
                 ctx.adjust_hydcon[i] = (v <= 0.0) ? 1.0 : v;
             }
         }
-        // Subcatchment pattern assignments: N-PERV, DSTORE, INFIL
-        else if (keyword == "N-PERV" && tok.size() >= 3) {
+        // Subcatchment pattern assignments: N-PERV, DSTORE, INFIL.
+        // The third token names a TIME PATTERN (legacy climate_readAdjustments
+        // resolves it with project_findObject(TIMEPATTERN, tok[2])), NOT a
+        // time series or curve: ctx.find_table_any searches only those two, so
+        // every per-subcatchment adjustment row bound -1 and was dropped in
+        // silence — session13-user5-sub-patterns ran its three adjusted
+        // subcatchments at HALF legacy's August infiltration.
+        else if (kw("N-PERV") && tok.size() >= 3) {
             const int si = ctx.subcatch_names.find(tok[1]);
-            const int pi = ctx.find_table_any(tok[2]);
+            const int pi = ctx.patterns.find(tok[2]);
             if (si >= 0 && pi >= 0) {
                 const auto usi = static_cast(si);
                 if (usi >= ctx.subcatch_n_perv_pattern.size())
@@ -197,9 +417,9 @@ void handle_adjustments(SimulationContext& ctx, const std::vector&
                 ctx.subcatch_n_perv_pattern[usi] = pi;
             }
         }
-        else if (keyword == "DSTORE" && tok.size() >= 3) {
+        else if (kw("DSTORE") && tok.size() >= 3) {
             const int si = ctx.subcatch_names.find(tok[1]);
-            const int pi = ctx.find_table_any(tok[2]);
+            const int pi = ctx.patterns.find(tok[2]);
             if (si >= 0 && pi >= 0) {
                 const auto usi = static_cast(si);
                 if (usi >= ctx.subcatch_d_store_pattern.size())
@@ -207,9 +427,9 @@ void handle_adjustments(SimulationContext& ctx, const std::vector&
                 ctx.subcatch_d_store_pattern[usi] = pi;
             }
         }
-        else if (keyword == "INFIL" && tok.size() >= 3) {
+        else if (kw("INFIL") && tok.size() >= 3) {
             const int si = ctx.subcatch_names.find(tok[1]);
-            const int pi = ctx.find_table_any(tok[2]);
+            const int pi = ctx.patterns.find(tok[2]);
             if (si >= 0 && pi >= 0) {
                 const auto usi = static_cast(si);
                 if (usi >= ctx.subcatch_infil_pattern.size())
diff --git a/src/engine/input/handlers/InfraHandler.hpp b/src/engine/input/handlers/InfraHandler.hpp
index 9d56fd6b3..87cdb1454 100644
--- a/src/engine/input/handlers/InfraHandler.hpp
+++ b/src/engine/input/handlers/InfraHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file InfraHandler.hpp
  * @brief Section handlers for [STREETS], [INLETS], [INLET_USAGE].
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_INFRA_HANDLER_HPP
diff --git a/src/engine/input/handlers/LinksHandler.cpp b/src/engine/input/handlers/LinksHandler.cpp
index e54fe16b6..0ad8c450f 100644
--- a/src/engine/input/handlers/LinksHandler.cpp
+++ b/src/engine/input/handlers/LinksHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LinksHandler.cpp
  * @brief Section handlers for [CONDUITS], [PUMPS], [ORIFICES], [WEIRS], [OUTLETS], [XSECTIONS], [LOSSES], [TRANSECTS].
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "LinksHandler.hpp"
@@ -27,6 +43,8 @@
 #include "../Tokenizer.hpp"
 #include "../SectionParser.hpp"
 #include "../../core/SimulationContext.hpp"
+#include "../../core/ErrorCodes.hpp"
+#include "../../core/Constants.hpp"
 #include "../../data/LinkData.hpp"
 #include "../../data/InfraData.hpp"
 
@@ -34,7 +52,8 @@
 
 #include 
 #include 
-#include 
+#include 
+#include 
 
 namespace openswmm::input {
 
@@ -42,11 +61,43 @@ static void ensure_link_capacity(SimulationContext& ctx, int idx) {
     ctx.links.grow_to(idx + 1);
 }
 
+// Resolve a link's end nodes and record the raw names for deferred
+// re-resolution. Legacy parsing is order-independent, so a link section may
+// precede [JUNCTIONS]/[OUTFALLS]/etc.; without the deferred pass the link is
+// loaded silently orphaned (node1/node2 == -1) and the .inp writer then emits
+// '*' in the FromNode/ToNode columns.
+static void set_link_nodes(SimulationContext& ctx, int idx,
+                           const std::string& n1, const std::string& n2) {
+    ctx.links.node1[idx] = ctx.node_names.find(n1);
+    ctx.links.node2[idx] = ctx.node_names.find(n2);
+    ctx.pending_link_nodes.emplace_back(idx, std::make_pair(n1, n2));
+}
+
+namespace {
+
+// legacy link.c: under LINK_OFFSETS ELEVATION a '*' offset token means "this
+// end sits at the node invert" and is stored as MISSING (conduit_readParams
+// :966/969, orifice :1672, weir :2079, outlet :2591); getOffsetHeight then
+// turns MISSING into a zero offset. Reading it as 0.0 instead makes the offset
+// an ELEVATION of zero — on driveway's ditch (invert -0.75) that lifted the
+// conduit 0.75 ft off the node and cut its flow depth from 1.75 ft to 1.0.
+double offsetToken(const SimulationContext& ctx, const std::string& tok) {
+    if (ctx.options.link_offsets == 1 && !tok.empty() && tok[0] == '*')
+        return constants::MISSING;
+    return to_double(tok);
+}
+
+}  // namespace
+
 // ============================================================================
 // handle_conduits()
 // ============================================================================
 
 void handle_conduits(SimulationContext& ctx, const std::vector& lines) {
+    // Pre-reserve from the section's row count (an upper bound: some rows
+    // are comments or duplicates). Capacity only — see reserve_to().
+    ctx.links.reserve_to(ctx.links.count() + static_cast(lines.size()));
+    ctx.link_names.reserve(static_cast(ctx.link_names.size()) + lines.size());
     for (const auto& pl : parse_section(lines)) {
         auto tok = Tokenizer::tokenize(pl.data);
         if (tok.size() < 7) continue;  // Name Node1 Node2 Length Roughness In Out required
@@ -60,13 +111,11 @@ void handle_conduits(SimulationContext& ctx, const std::vector& lin
         const int cr = ctx.link_subtypes.set_link_type(ctx.links, idx, LinkType::CONDUIT);
         const auto ucr = static_cast(cr);
 
-        // Resolve node indices — nodes must be parsed before conduits
-        ctx.links.node1[idx]     = ctx.node_names.find(tok[1]);
-        ctx.links.node2[idx]     = ctx.node_names.find(tok[2]);
+        set_link_nodes(ctx, idx, tok[1], tok[2]);
         ctx.link_subtypes.conduits.length[ucr]    = to_double(tok[3]);
         ctx.link_subtypes.conduits.roughness[ucr] = to_double(tok[4]);
-        ctx.links.offset1[idx]   = to_double(tok[5]);
-        ctx.links.offset2[idx]   = to_double(tok[6]);
+        ctx.links.offset1[idx]   = offsetToken(ctx, tok[5]);
+        ctx.links.offset2[idx]   = offsetToken(ctx, tok[6]);
         if (tok.size() > 7) ctx.links.q0[idx]      = to_double(tok[7]);
         if (tok.size() > 8) ctx.links.q_limit[idx] = to_double(tok[8]);
         if (!pl.comment.empty())
@@ -91,8 +140,7 @@ void handle_pumps(SimulationContext& ctx, const std::vector& lines)
 
         const int pr = ctx.link_subtypes.set_link_type(ctx.links, idx, LinkType::PUMP);
         const auto upr = static_cast(pr);
-        ctx.links.node1[idx] = ctx.node_names.find(tok[1]);
-        ctx.links.node2[idx] = ctx.node_names.find(tok[2]);
+        set_link_nodes(ctx, idx, tok[1], tok[2]);
         // tok[3]: pump curve name — store for deferred resolution.
         // "*" is the ideal-pump placeholder (legacy pump_readParams,
         // link.c:1437), not a curve name: leave curve at -1 so the pump is
@@ -138,18 +186,17 @@ void handle_orifices(SimulationContext& ctx, const std::vector& lin
 
         const int orr = ctx.link_subtypes.set_link_type(ctx.links, idx, LinkType::ORIFICE);
         const auto uorr = static_cast(orr);
-        ctx.links.node1[idx]        = ctx.node_names.find(tok[1]);
-        ctx.links.node2[idx]        = ctx.node_names.find(tok[2]);
+        set_link_nodes(ctx, idx, tok[1], tok[2]);
         // tok[3]: SIDE or BOTTOM → orifice_type (0=BOTTOM, 1=SIDE)
         if (tok.size() > 3)
             ctx.link_subtypes.orifices.orifice_type[uorr] =
                 (Tokenizer::to_upper(tok[3]) == "SIDE") ? 1.0 : 0.0;
         // tok[4]: offset (height above invert)
-        if (tok.size() > 4) ctx.links.offset1[idx]      = to_double(tok[4]);
+        if (tok.size() > 4) ctx.links.offset1[idx]      = offsetToken(ctx, tok[4]);
         // tok[5]: discharge coefficient
         if (tok.size() > 5) ctx.link_subtypes.orifices.cd[uorr] = to_double(tok[5]);
         // tok[6]: flap gate (YES/NO)
-        if (tok.size() > 6) ctx.links.has_flap_gate[idx] = Tokenizer::to_upper(tok[6]) == "YES";
+        if (tok.size() > 6) ctx.links.has_flap_gate[idx] = Tokenizer::parse_boolean(tok[6]);
         // tok[7]: open/close time (seconds)
         if (tok.size() > 7) ctx.link_subtypes.orifices.orate[uorr] = to_double(tok[7]);
         if (!pl.comment.empty())
@@ -174,23 +221,24 @@ void handle_weirs(SimulationContext& ctx, const std::vector& lines)
 
         const int wr = ctx.link_subtypes.set_link_type(ctx.links, idx, LinkType::WEIR);
         const auto uwr = static_cast(wr);
-        ctx.links.node1[idx] = ctx.node_names.find(tok[1]);
-        ctx.links.node2[idx] = ctx.node_names.find(tok[2]);
-        // tok[3]: weir type (TRANSVERSE=0, SIDEFLOW=1, V-NOTCH=2, TRAPEZOIDAL=3)
+        set_link_nodes(ctx, idx, tok[1], tok[2]);
+        // tok[3]: weir type (TRANSVERSE=0, SIDEFLOW=1, V-NOTCH=2, TRAPEZOIDAL=3,
+        // ROADWAY=4 — legacy WeirTypeWords order)
+        double wt = 0.0;
         if (tok.size() > 3) {
             std::string wtype = Tokenizer::to_upper(tok[3]);
-            double wt = 0.0;
             if (wtype == "SIDEFLOW") wt = 1.0;
             else if (wtype == "V-NOTCH") wt = 2.0;
             else if (wtype == "TRAPEZOIDAL") wt = 3.0;
+            else if (wtype == "ROADWAY") wt = 4.0;
             ctx.link_subtypes.weirs.weir_type[uwr] = wt;
         }
         // tok[4]: crest height (above invert)
-        if (tok.size() > 4) ctx.link_subtypes.weirs.crest_height[uwr] = to_double(tok[4]);
+        if (tok.size() > 4) ctx.link_subtypes.weirs.crest_height[uwr] = offsetToken(ctx, tok[4]);
         // tok[5]: discharge coefficient
         if (tok.size() > 5) ctx.link_subtypes.weirs.cd[uwr] = to_double(tok[5]);
         // tok[6]: flap gate (YES/NO)
-        if (tok.size() > 6) ctx.links.has_flap_gate[idx] = Tokenizer::to_upper(tok[6]) == "YES";
+        if (tok.size() > 6) ctx.links.has_flap_gate[idx] = Tokenizer::parse_boolean(tok[6]);
         // tok[7]: end contractions
         if (tok.size() > 7) ctx.link_subtypes.weirs.end_contractions[uwr] = to_double(tok[7]);
         // tok[8]: end-section discharge coeff (legacy cDisch2, link.c weir_readParams x[5])
@@ -200,6 +248,26 @@ void handle_weirs(SimulationContext& ctx, const std::vector& lines)
         if (tok.size() > 9 && tok[9] != "*")
             ctx.link_subtypes.weirs.can_surcharge[uwr] =
                 (Tokenizer::to_upper(tok[9]) == "YES") ? uint8_t{1} : uint8_t{0};
+        // tok[10] road width, tok[11] road surface (legacy weir_readParams
+        // x[7], x[8]: read for a ROADWAY weir only; an unknown surface word
+        // leaves 0 = no surface → the user's Cd is used as is)
+        if (wt == 4.0) {
+            if (tok.size() > 10)
+                ctx.link_subtypes.weirs.road_width[uwr] = to_double(tok[10]);
+            if (tok.size() > 11) {
+                const std::string surf = Tokenizer::to_upper(tok[11]);
+                ctx.link_subtypes.weirs.road_surface[uwr] =
+                    surf == "PAVED" ? int8_t{1} : surf == "GRAVEL" ? int8_t{2} : int8_t{0};
+            }
+        }
+        // tok[12]: discharge-coefficient curve (legacy x[9], any weir type);
+        // the name is kept on the link's curve-name slot and resolved to a
+        // table index once every [CURVES] entry is read.
+        if (tok.size() > 12 && tok[12] != "*") {
+            const auto uidx = static_cast(idx);
+            if (uidx < ctx.links.pump_curve_name.size())
+                ctx.links.pump_curve_name[uidx] = tok[12];
+        }
         if (!pl.comment.empty())
             ctx.links.comments[static_cast(idx)] = pl.comment;
     }
@@ -222,10 +290,9 @@ void handle_outlets(SimulationContext& ctx, const std::vector& line
 
         const int olr = ctx.link_subtypes.set_link_type(ctx.links, idx, LinkType::OUTLET);
         const auto uolr = static_cast(olr);
-        ctx.links.node1[idx]        = ctx.node_names.find(tok[1]);
-        ctx.links.node2[idx]        = ctx.node_names.find(tok[2]);
+        set_link_nodes(ctx, idx, tok[1], tok[2]);
         if (tok.size() > 3)
-            ctx.link_subtypes.outlets.crest_height[uolr] = to_double(tok[3]);
+            ctx.link_subtypes.outlets.crest_height[uolr] = offsetToken(ctx, tok[3]);
         // tok[4]: type string (TABULAR/HEAD, TABULAR/DEPTH, FUNCTIONAL/HEAD, FUNCTIONAL/DEPTH)
         // tok[5]: curve name (TABULAR) or C1 coefficient (FUNCTIONAL)
         // tok[6]: C2 exponent (FUNCTIONAL only)
@@ -252,6 +319,14 @@ void handle_outlets(SimulationContext& ctx, const std::vector& line
         }
         if (tok.size() > 6 && !is_tabular)
             ctx.link_subtypes.outlets.expon[uolr] = to_double(tok[6]);
+        // Trailing optional Gated column (legacy link.c:395, x[4]). Its index
+        // depends on the rating type, because FUNCTIONAL carries two rating
+        // columns (C1, C2) where TABULAR carries one (the curve name):
+        //   TABULAR/*    : Name N1 N2 Offset Type Curve  [Gated]  -> tok[6]
+        //   FUNCTIONAL/* : Name N1 N2 Offset Type C1 C2  [Gated]  -> tok[7]
+        const std::size_t gate_tok = is_tabular ? 6u : 7u;
+        if (tok.size() > gate_tok)
+            ctx.links.has_flap_gate[idx] = Tokenizer::parse_boolean(tok[gate_tok]);
         if (!pl.comment.empty())
             ctx.links.comments[static_cast(idx)] = pl.comment;
     }
@@ -261,8 +336,12 @@ void handle_outlets(SimulationContext& ctx, const std::vector& line
 // handle_xsections()
 // ============================================================================
 
-// Map of shape name → XsectShape enum
-static const std::unordered_map SHAPE_MAP = {
+// Shape keywords in legacy's XsectTypeWords order (keywords.c:160-184). The
+// order is part of the semantics: legacy resolves the shape with
+// findmatch(), which returns the FIRST entry that is a PREFIX of the token
+// (input.c:791-823), not an exact match, so "DUMMY_2" reads as DUMMY.
+static const std::pair SHAPE_WORDS[] = {
+    {"DUMMY",           XsectShape::DUMMY},
     {"CIRCULAR",        XsectShape::CIRCULAR},
     {"FILLED_CIRCULAR", XsectShape::FILLED_CIRCULAR},
     {"RECT_CLOSED",     XsectShape::RECT_CLOSED},
@@ -271,7 +350,12 @@ static const std::unordered_map SHAPE_MAP = {
     {"TRIANGULAR",      XsectShape::TRIANGULAR},
     {"PARABOLIC",       XsectShape::PARABOLIC},
     {"POWER",           XsectShape::POWER},
+    {"RECT_TRIANGULAR", XsectShape::RECT_TRIANG},
+    {"RECT_ROUND",      XsectShape::RECT_ROUND},
     {"MODBASKETHANDLE", XsectShape::MODBASKETHANDLE},
+    {"HORIZ_ELLIPSE",   XsectShape::HORIZ_ELLIPSE},
+    {"VERT_ELLIPSE",    XsectShape::VERT_ELLIPSE},
+    {"ARCH",            XsectShape::ARCH},
     {"EGG",             XsectShape::EGGSHAPED},
     {"HORSESHOE",       XsectShape::HORSESHOE},
     {"GOTHIC",          XsectShape::GOTHIC},
@@ -279,19 +363,23 @@ static const std::unordered_map SHAPE_MAP = {
     {"SEMIELLIPTICAL",  XsectShape::SEMIELLIPTICAL},
     {"BASKETHANDLE",    XsectShape::BASKETHANDLE},
     {"SEMICIRCULAR",    XsectShape::SEMICIRCULAR},
-    {"RECT_TRIANGULAR", XsectShape::RECT_TRIANG},
-    {"RECT_TRIANG",     XsectShape::RECT_TRIANG},
-    {"RECT_ROUND",      XsectShape::RECT_ROUND},
-    {"HORIZ_ELLIPSE",   XsectShape::HORIZ_ELLIPSE},
-    {"VERT_ELLIPSE",    XsectShape::VERT_ELLIPSE},
-    {"ARCH",            XsectShape::ARCH},
     {"IRREGULAR",       XsectShape::IRREGULAR},
     {"CUSTOM",          XsectShape::CUSTOM},
     {"FORCE_MAIN",      XsectShape::FORCE_MAIN},
     {"STREET",          XsectShape::STREET_XSECT},
-    {"DUMMY",           XsectShape::DUMMY},
 };
 
+// Legacy findmatch(tok[1], XsectTypeWords): first keyword that prefixes the
+// (already upper-cased) token, or -1.
+static int find_shape_word(std::string_view s) {
+    int i = 0;
+    for (const auto& [word, shape] : SHAPE_WORDS) {
+        if (s.compare(0, word.size(), word) == 0) return i;
+        ++i;
+    }
+    return -1;
+}
+
 void handle_xsections(SimulationContext& ctx, const std::vector& lines) {
     for (const auto& line : lines) {
         auto tok = Tokenizer::tokenize(line);
@@ -309,10 +397,19 @@ void handle_xsections(SimulationContext& ctx, const std::vector& li
         ensure_link_capacity(ctx, idx);
 
         const std::string shape_str = Tokenizer::to_upper(tok[1]);
-        auto it = SHAPE_MAP.find(shape_str);
-        if (it != SHAPE_MAP.end()) {
-            ctx.links.xsect_shape[idx] = it->second;
+        const int shape_word = find_shape_word(shape_str);
+        if (shape_word < 0) {
+            // Legacy link.c:190 rejects an unmatched shape keyword outright.
+            // v6 used to leave the link on its default shape and then parse the
+            // geometry columns into it, so a deck naming a shape SWMM does not
+            // have — "SEMI_ELLIPTICAL" for w_SEMIELLIPTICAL, or the literal
+            // "UNKNOWN" an InfoWorks export writes when it cannot map a shape —
+            // ran to completion against the wrong cross-section and reported
+            // success.
+            ctx.errors.push_back(format_error(ERR_KEYWORD, tok[1]));
+            continue;
         }
+        ctx.links.xsect_shape[idx] = SHAPE_WORDS[shape_word].second;
 
         // IRREGULAR shapes: tok[2] is transect name, not a dimension.
         // STREET shapes:    tok[2] is street name, not a dimension.
@@ -430,9 +527,36 @@ void handle_transects(SimulationContext& ctx, const std::vector& li
 
         if (keyword == "NC") {
             // NC  nLeft  nRight  nChannel
-            if (tok.size() > 1) nc_left    = to_double(tok[1]);
-            if (tok.size() > 2) nc_right   = to_double(tok[2]);
-            if (tok.size() > 3) nc_channel = to_double(tok[3]);
+            //
+            // A zero component means "unchanged from the preceding NC
+            // record" (EPA SWMM 5.2.4; legacy transect.c::setManning), so
+            // only positive values overwrite the active roughness. Zeroing
+            // the stored values here wiped a previously declared channel
+            // roughness and tripped ERR_TRANSECT_MANNING (227) during
+            // validation for input EPA SWMM accepts.
+            const double n_left    = (tok.size() > 1) ? to_double(tok[1]) : 0.0;
+            const double n_right   = (tok.size() > 2) ? to_double(tok[2]) : 0.0;
+            const double n_channel = (tok.size() > 3) ? to_double(tok[3]) : 0.0;
+            // A negative component is invalid input, not an inheritance
+            // request (legacy setManning returns ERR_NUMBER for it).
+            if (n_left < 0.0) {
+                ctx.errors.push_back(format_error(ERR_NUMBER, tok[1]));
+                continue;
+            }
+            if (n_right < 0.0) {
+                ctx.errors.push_back(format_error(ERR_NUMBER, tok[2]));
+                continue;
+            }
+            if (n_channel < 0.0) {
+                ctx.errors.push_back(format_error(ERR_NUMBER, tok[3]));
+                continue;
+            }
+            if (n_left    > 0.0) nc_left    = n_left;
+            if (n_right   > 0.0) nc_right   = n_right;
+            if (n_channel > 0.0) nc_channel = n_channel;
+            // overbank roughness defaults to the channel value, as in legacy
+            if (nc_left  == 0.0) nc_left  = nc_channel;
+            if (nc_right == 0.0) nc_right = nc_channel;
         }
         else if (keyword == "X1") {
             // Per EPA SWMM 5 (transect.c::setParams) the X1 layout is:
diff --git a/src/engine/input/handlers/LinksHandler.hpp b/src/engine/input/handlers/LinksHandler.hpp
index 1cad3bc52..81b9149c9 100644
--- a/src/engine/input/handlers/LinksHandler.hpp
+++ b/src/engine/input/handlers/LinksHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file LinksHandler.hpp
  * @brief Section handlers for link types: CONDUITS, PUMPS, ORIFICES, WEIRS, OUTLETS, XSECTIONS, LOSSES, TRANSECTS.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_LINKS_HANDLER_HPP
diff --git a/src/engine/input/handlers/NodesHandler.cpp b/src/engine/input/handlers/NodesHandler.cpp
index 678289082..2e125a59f 100644
--- a/src/engine/input/handlers/NodesHandler.cpp
+++ b/src/engine/input/handlers/NodesHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NodesHandler.cpp
  * @brief Section handlers for [JUNCTIONS], [OUTFALLS], [DIVIDERS], [STORAGE], [COORDINATES].
@@ -8,6 +24,15 @@
  * J1           0.0    5.0       0.0        0.0       0.0
  * ```
  *
+ * ### [VIRTUAL_JUNCTIONS] format (refactored engine only)
+ * ```
+ * ;; Name      Elev   [MaxDepth]
+ * VJ1          9.0
+ * VJ2          9.0    4.5
+ * ```
+ * MaxDepth is optional and RENDERING ONLY — it is the rim/ground depth a
+ * viewer draws the surface at. The solver always uses the derived pipe crown.
+ *
  * ### [OUTFALLS] format
  * ```
  * ;; Name      Elev   Type      Stage/Tseries  Gated  RouteTo
@@ -28,7 +53,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "NodesHandler.hpp"
@@ -42,6 +67,7 @@
 
 #include "../InputParseUtils.hpp"
 
+#include 
 #include 
 #include 
 #include 
@@ -65,6 +91,10 @@ static void ensure_spatial_capacity(SimulationContext& ctx, int n_nodes) {
 // ============================================================================
 
 void handle_junctions(SimulationContext& ctx, const std::vector& lines) {
+    // Pre-reserve from the section's row count (an upper bound: some rows
+    // are comments or duplicates). Capacity only — see reserve_to().
+    ctx.nodes.reserve_to(ctx.nodes.count() + static_cast(lines.size()));
+    ctx.node_names.reserve(static_cast(ctx.node_names.size()) + lines.size());
     for (const auto& pl : parse_section(lines)) {
         auto tok = Tokenizer::tokenize(pl.data);
         if (tok.size() < 2) continue;
@@ -77,6 +107,27 @@ void handle_junctions(SimulationContext& ctx, const std::vector& li
 
         ensure_node_capacity(ctx, idx);
 
+        // legacy junc_readParams (node.c): the INVERT ELEVATION may be
+        // negative, but max depth, initial depth, surcharge depth and ponded
+        // area may not — "check for non-negative values (except for invert
+        // elev.)" — and a negative one is ERROR 211 naming the offending token,
+        // tested in column order once the row is read.
+        //
+        // Accepting them is not a lenient no-op. A negative max depth drives a
+        // pathological run: 1218-nodes carries maxDepth = -612 on six junctions
+        // and v6 simulated 21 days straight past the 1,800 s harness cap, where
+        // legacy refuses the deck in 24 ms. 960-nodes is the same rule at
+        // -0.100000.
+        bool negative_param = false;
+        for (std::size_t i = 2; i < tok.size() && i <= 5; ++i) {
+            if (to_double(tok[i]) < 0.0) {
+                ctx.errors.push_back(format_error(ERR_NUMBER, tok[i]));
+                negative_param = true;
+                break;
+            }
+        }
+        if (negative_param) continue;
+
         ctx.node_subtypes.set_node_type(ctx.nodes, idx, NodeType::JUNCTION);
         ctx.nodes.invert_elev[idx] = to_double(tok[1]);                          // Elev
         if (tok.size() > 2) ctx.nodes.full_depth[idx]  = to_double(tok[2]);     // MaxDepth
@@ -99,10 +150,11 @@ void handle_virtual_junctions(SimulationContext& ctx, const std::vector 2) {
+        // Name, invert elevation and an OPTIONAL rendering-only max depth.
+        // Everything the solver uses is derived from the two attached
+        // conduits, so a fourth token is still an error (keeps the format
+        // extensible without ambiguity).
+        if (tok.size() > 3) {
             ctx.errors.push_back(format_error(ERR_VJ_EXTRA_TOKENS, name));
             continue;
         }
@@ -115,6 +167,12 @@ void handle_virtual_junctions(SimulationContext& ctx, const std::vector(idx)] = 1;
         ctx.nodes.invert_elev[idx] = to_double(tok[1]);
+        // MaxDepth: rim/ground elevation for drawings only — never read by the
+        // solver, which uses the derived pipe crown (NodeData::rim_depth).
+        // Negatives and unparseable text collapse to 0 = unset.
+        if (tok.size() > 2)
+            ctx.nodes.rim_depth[static_cast(idx)] =
+                std::max(0.0, to_double(tok[2]));
         if (!pl.comment.empty())
             ctx.nodes.comments[static_cast(idx)] = pl.comment;
     }
@@ -125,6 +183,10 @@ void handle_virtual_junctions(SimulationContext& ctx, const std::vector& lines) {
+    // Pre-reserve from the section's row count (an upper bound: some rows
+    // are comments or duplicates). Capacity only — see reserve_to().
+    ctx.nodes.reserve_to(ctx.nodes.count() + static_cast(lines.size()));
+    ctx.node_names.reserve(static_cast(ctx.node_names.size()) + lines.size());
     for (const auto& pl : parse_section(lines)) {
         auto tok = Tokenizer::tokenize(pl.data);
         if (tok.size() < 3) continue;
@@ -240,18 +302,31 @@ void handle_dividers(SimulationContext& ctx, const std::vector& lin
             }
         } else if (dtype == "WEIR") {
             D.method[drow] = DividerType::WEIR;
+            // Legacy column order (node.c:1112): qMin dhMax cWeir — dhMax is
+            // token 5 and the discharge coefficient token 6 (was swapped).
             if (tok.size() > 4) D.cutoff[drow]    = to_double(tok[4]);
-            if (tok.size() > 5) D.cd[drow]        = to_double(tok[5]);
-            if (tok.size() > 6) D.max_depth[drow] = to_double(tok[6]);
+            if (tok.size() > 5) D.max_depth[drow] = to_double(tok[5]);
+            if (tok.size() > 6) D.cd[drow]        = to_double(tok[6]);
         }
 
-        // MaxDepth after type-specific fields
-        int md_offset = 5;
-        if (dtype == "CUTOFF" || dtype == "OVERFLOW") md_offset = 5;
-        else if (dtype == "TABULAR") md_offset = 5;
-        else if (dtype == "WEIR") md_offset = 7;
-        if (static_cast(tok.size()) > md_offset)
-            ctx.nodes.full_depth[ui] = to_double(tok[md_offset]);
+        // The optional tail is "maxDepth initDepth surDepth aPond", read from
+        // the first token AFTER the type-specific parameters — legacy's `n`
+        // (node.c divider_readParams, into x[7..10]).  OVERFLOW takes NO type
+        // parameter, so its tail starts at token 4; CUTOFF (qCutoff) and
+        // TABULAR (curve name) take one, WEIR (qMin dhMax cWeir) takes three.
+        //
+        // Two defects lived here: OVERFLOW used 5, so MaxDepth was read from
+        // the InitDepth column; and initDepth/surDepth/aPond were never read
+        // at all, so every divider silently lost them on load — not just on
+        // save, since the live model carried the zeros into the simulation.
+        int tail = 5;                                   // CUTOFF, TABULAR
+        if      (dtype == "OVERFLOW") tail = 4;
+        else if (dtype == "WEIR")     tail = 7;
+        const int ntoks = static_cast(tok.size());
+        if (ntoks > tail)     ctx.nodes.full_depth[ui] = to_double(tok[tail]);
+        if (ntoks > tail + 1) ctx.nodes.init_depth[ui] = to_double(tok[tail + 1]);
+        if (ntoks > tail + 2) ctx.nodes.sur_depth[ui]  = to_double(tok[tail + 2]);
+        if (ntoks > tail + 3) ctx.nodes.ponded_area[ui] = to_double(tok[tail + 3]);
         if (!pl.comment.empty())
             ctx.nodes.comments[ui] = pl.comment;
     }
@@ -320,15 +395,33 @@ void handle_storage(SimulationContext& ctx, const std::vector& line
             S.curve[srow] = -1;
         }
 
-        // Optional: SurDepth, Fevap, Seep — TABULAR consumes one token for the curve
-        // name, every other shape consumes three numeric params.
+        // Optional: SurDepth, Fevap, then the exfiltration parameters —
+        // TABULAR consumes one token for the curve name, every other shape
+        // three numeric params (legacy storage_readParams n = 6 / 8).
+        // legacy exfil_readStorageParams: ONE remaining token is a bare Ksat
+        // (suction and IMD 0 → a constant Ks rate), otherwise three tokens
+        // Psi Ksat IMD (Green-Ampt); Ksat 0 = no exfiltration. The third
+        // token used to land in the dead `seep_rate` slot and the
+        // Green-Ampt columns were never read, so every .inp storage
+        // exfiltration (36 corpus decks) was silently ignored.
         const int param_offset = (sshape == StorageShape::TABULAR) ? 6 : 8;
         if (static_cast(tok.size()) > param_offset)
             ctx.nodes.sur_depth[idx] = to_double(tok[param_offset]);
         if (static_cast(tok.size()) > param_offset + 1)
             S.evap_frac[srow] = to_double(tok[param_offset + 1]);
-        if (static_cast(tok.size()) > param_offset + 2)
-            S.seep_rate[srow] = to_double(tok[param_offset + 2]);
+        {
+            const int n = param_offset + 2;
+            const int ntoks = static_cast(tok.size());
+            if (ntoks == n + 1) {
+                S.exfil_suction[srow] = 0.0;
+                S.exfil_ksat[srow]    = to_double(tok[n]);
+                S.exfil_imd[srow]     = 0.0;
+            } else if (ntoks >= n + 3) {
+                S.exfil_suction[srow] = to_double(tok[n]);
+                S.exfil_ksat[srow]    = to_double(tok[n + 1]);
+                S.exfil_imd[srow]     = to_double(tok[n + 2]);
+            }
+        }
         if (!pl.comment.empty())
             ctx.nodes.comments[static_cast(idx)] = pl.comment;
     }
@@ -341,8 +434,19 @@ void handle_storage(SimulationContext& ctx, const std::vector& line
 void handle_coordinates(SimulationContext& ctx, const std::vector& lines) {
     ensure_spatial_capacity(ctx, ctx.node_names.size());
 
+    // One row per node — hoist the token buffer so the loop allocates nothing
+    // after the first row. Quoted node names fall back to the owned tokenizer,
+    // which tokenize_views_into cannot handle; same result, more allocation.
+    std::vector tok;
+    std::vector      quoted;
+
     for (const auto& line : lines) {
-        auto tok = Tokenizer::tokenize(line);
+        if (line.find('"') == std::string::npos) {
+            Tokenizer::tokenize_views_into(line, tok);
+        } else {
+            quoted = Tokenizer::tokenize(line);
+            tok.assign(quoted.begin(), quoted.end());
+        }
         if (tok.size() < 3) continue;
 
         const int idx = ctx.node_names.find(tok[0]);
@@ -352,6 +456,9 @@ void handle_coordinates(SimulationContext& ctx, const std::vector&
 
         ctx.spatial.node_x[idx] = to_double(tok[1]);
         ctx.spatial.node_y[idx] = to_double(tok[2]);
+        if (ctx.spatial.node_has_xy.size() < ctx.spatial.node_x.size())
+            ctx.spatial.node_has_xy.resize(ctx.spatial.node_x.size(), 0);
+        ctx.spatial.node_has_xy[static_cast(idx)] = 1;   // G-X2
     }
 }
 
diff --git a/src/engine/input/handlers/NodesHandler.hpp b/src/engine/input/handlers/NodesHandler.hpp
index e08878b11..0c0ac760a 100644
--- a/src/engine/input/handlers/NodesHandler.hpp
+++ b/src/engine/input/handlers/NodesHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file NodesHandler.hpp
  * @brief Section handlers for node types: JUNCTIONS, OUTFALLS, DIVIDERS, STORAGE.
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_NODES_HANDLER_HPP
@@ -28,6 +44,15 @@ void handle_junctions(SimulationContext& ctx, const std::vector& li
  *           parse error (ERR_VJ_EXTRA_TOKENS). Refactored engine only. */
 void handle_virtual_junctions(SimulationContext& ctx, const std::vector& lines);
 
+/** @brief Parse [INLET_JUNCTIONS] — virtual junctions that carry a street inlet.
+ *  @details `Name Elev MaxDepth Inlet CaptureNode (#Inlets %Clog Qmax aLocal
+ *           wLocal Placement)`: the node gets is_virtual = is_inlet = 1 and a
+ *           node-hosted InletUsageStore row whose design / capture-node names
+ *           are resolved by PostParseResolver. More than 11 tokens is a parse
+ *           error (ERR_IJ_EXTRA_TOKENS). Implemented in InfraHandler.cpp
+ *           beside the [INLET_USAGE] tail parser it shares. */
+void handle_inlet_junctions(SimulationContext& ctx, const std::vector& lines);
+
 /** @brief Parse [OUTFALLS] — sets outfall-specific fields for nodes of type OUTFALL. */
 void handle_outfalls(SimulationContext& ctx, const std::vector& lines);
 
diff --git a/src/engine/input/handlers/OptionsHandler.cpp b/src/engine/input/handlers/OptionsHandler.cpp
index cb743e58a..4943e5c71 100644
--- a/src/engine/input/handlers/OptionsHandler.cpp
+++ b/src/engine/input/handlers/OptionsHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OptionsHandler.cpp
  * @brief [OPTIONS] section handler for the new engine.
@@ -16,19 +32,19 @@
  *  FLOW_UNITS           → options.flow_units
  *  INFILTRATION         → options.infiltration
  *  FLOW_ROUTING         → options.routing_model
- *  LINK_OFFSETS         → (ignored — legacy compatibility)
- *  MIN_SLOPE            → (stored in ext_options — not used by new solver yet)
+ *  LINK_OFFSETS         → options.link_offsets (0 = DEPTH, 1 = ELEVATION)
+ *  MIN_SLOPE            → options.min_slope
  *  ALLOW_PONDING        → options.allow_ponding
- *  SKIP_STEADY_STATE    → (ignored)
+ *  SKIP_STEADY_STATE    → options.skip_steady_state
  *  START_DATE           → options.start_date (OADate (days since 12/30/1899))
  *  START_TIME           → combined with START_DATE
  *  END_DATE             → options.end_date
  *  END_TIME             → combined with END_DATE
  *  REPORT_START_DATE    → options.report_start
  *  REPORT_START_TIME    → combined with REPORT_START_DATE
- *  SWEEP_START          → (ext_options)
- *  SWEEP_END            → (ext_options)
- *  DRY_DAYS             → (ext_options)
+ *  SWEEP_START          → options.sweep_start (MM/DD → day-of-year)
+ *  SWEEP_END            → options.sweep_end (MM/DD → day-of-year)
+ *  DRY_DAYS             → options.dry_days
  *  REPORT_STEP          → options.report_step (HH:MM:SS or seconds)
  *  WET_STEP             → options.wet_step
  *  DRY_STEP             → options.dry_step
@@ -55,7 +71,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "OptionsHandler.hpp"
@@ -84,6 +100,14 @@ static std::string norm(std::string_view sv) {
     return Tokenizer::to_upper(sv);
 }
 
+// legacy findmatch / match (input.c): a keyword matches when it is a
+// case-insensitive PREFIX of the token — `STEADYFLOW` is STEADY, `DYNWAVE2`
+// DYNWAVE. `tok` is already upper-cased by norm().
+static bool legacyPrefix(const std::string& tok, const char* keyword) {
+    const std::size_t n = std::strlen(keyword);
+    return tok.size() >= n && tok.compare(0, n, keyword) == 0;
+}
+
 // ============================================================================
 // handle_options() — registered as built-in handler for "OPTIONS"
 // ============================================================================
@@ -128,9 +152,13 @@ void handle_options(SimulationContext& ctx, const std::vector& line
                 opt.infiltration = InfiltrationModel::HORTON;
             else if (iv == "MOD_HORTON" || iv == "MODIFIED_HORTON")
                 opt.infiltration = InfiltrationModel::MOD_HORTON;
-            else if (iv == "GREEN_AMPT"     || iv == "MODIFIED_GREEN_AMPT")
+            else if (iv == "GREEN_AMPT")
                 opt.infiltration = InfiltrationModel::GREEN_AMPT;
-            else if (iv == "MOD_GREEN_AMPT")
+            // Legacy InfilModelWords spells it MODIFIED_GREEN_AMPT (text.h
+            // w_MOD_GREEN_AMPT); MOD_GREEN_AMPT is this engine's own alias.
+            // The deck keyword was mapped to plain GREEN_AMPT — 11 corpus
+            // decks ran the wrong model (F reset between events).
+            else if (iv == "MOD_GREEN_AMPT" || iv == "MODIFIED_GREEN_AMPT")
                 opt.infiltration = InfiltrationModel::MOD_GREEN_AMPT;
             else if (iv == "CURVE_NUMBER")
                 opt.infiltration = InfiltrationModel::CURVE_NUMBER;
@@ -138,21 +166,80 @@ void handle_options(SimulationContext& ctx, const std::vector& line
 
         } else if (key == "FLOW_ROUTING") {
             const std::string rv = norm(val);
-            if      (rv == "STEADY")   opt.routing_model = RoutingModel::STEADY;
-            else if (rv == "KINWAVE"   || rv == "KINEMATIC_WAVE")
+            // legacy project_readOption ROUTE_MODEL: findmatch over
+            // RouteModelWords {NONE, STEADY, KINWAVE, XKINWAVE, DYNWAVE}, then
+            // OldRouteModelWords {NONE, NF, KW, EKW, DW}, each a prefix test
+            // in that order (routing-steadyflow writes `STEADYFLOW`, which
+            // ran as the dynamic wave here). XKINWAVE / EKW are the kinematic
+            // wave; NONE ignores routing.
+            if      (legacyPrefix(rv, "NONE"))     opt.ignore_routing = true;
+            else if (legacyPrefix(rv, "STEADY"))   opt.routing_model = RoutingModel::STEADY;
+            else if (legacyPrefix(rv, "KINWAVE"))  opt.routing_model = RoutingModel::KINWAVE;
+            else if (legacyPrefix(rv, "XKINWAVE")) opt.routing_model = RoutingModel::KINWAVE;
+            else if (legacyPrefix(rv, "DYNWAVE"))  opt.routing_model = RoutingModel::DYNWAVE;
+            else if (legacyPrefix(rv, "NF"))       opt.routing_model = RoutingModel::STEADY;
+            else if (legacyPrefix(rv, "KW"))       opt.routing_model = RoutingModel::KINWAVE;
+            else if (legacyPrefix(rv, "EKW"))      opt.routing_model = RoutingModel::KINWAVE;
+            else if (legacyPrefix(rv, "DW"))       opt.routing_model = RoutingModel::DYNWAVE;
+            // This engine's own spellings.
+            else if (rv == "KINEMATIC_WAVE")
                 opt.routing_model = RoutingModel::KINWAVE;
-            else if (rv == "DYNWAVE"   || rv == "DYNAMIC_WAVE")
+            else if (rv == "DYNAMIC_WAVE")
                 opt.routing_model = RoutingModel::DYNWAVE;
             else if (rv == "FV" || rv == "FINITE_VOLUME")
                 opt.routing_model = RoutingModel::FV;
-            // Legacy FLOW_ROUTING NONE maps to the NO_ROUTING method and forces
-            // IgnoreRouting = TRUE (project.c:504). The refactored RoutingModel
-            // enum has no NONE value, so realize the same effect by setting the
-            // ignore_routing flag directly (routing_model is unused when routing
-            // is ignored).
-            else if (rv == "NONE" || rv == "NO_ROUTING") opt.ignore_routing = true;
+            else if (rv == "NO_ROUTING") opt.ignore_routing = true;
+            else opt.ext_options[key] = val;
+
+        } else if (key == "QUALITY_SOLVER") {
+            // Unified Transport suite, master plan D-UT6. LAGRANGIAN selects
+            // the LARD dispatch (X1 wiring — a warned no-op until X2 lands
+            // transport; LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md). Unknown
+            // values still fall to ext_options for diagnostics.
+            const std::string qv = norm(val);
+            if      (qv == "LEGACY")       opt.quality_solver = QualitySolverKind::LEGACY;
+            else if (qv == "EULERIAN_ARD" || qv == "ARD")
+                opt.quality_solver = QualitySolverKind::EULERIAN_ARD;
+            else if (qv == "LAGRANGIAN" || qv == "LARD")
+                opt.quality_solver = QualitySolverKind::LAGRANGIAN;
             else opt.ext_options[key] = val;
 
+        } else if (key == "WATER_AGE") {
+            // Water age plan §1 (phase A1a): transported age tracking.
+            opt.water_age = (norm(val) == "ON" || norm(val) == "YES");
+
+        } else if (key == "OUTFALL_BACKFLOW_QUALITY") {
+            // Boundary re-entry quality at outfalls. LAST = legacy held
+            // state (the default); ZERO = fresh boundary — a supplying
+            // outfall's held state reads zero for pollutants and
+            // __WATER_AGE__ alike. Unknown values fall to ext_options.
+            const std::string bv = norm(val);
+            if      (bv == "LAST") opt.outfall_backflow_zero = false;
+            else if (bv == "ZERO") opt.outfall_backflow_zero = true;
+            else opt.ext_options[key] = val;
+
+        } else if (key == "HEAT_TRANSPORT") {
+            // Heat plan §1 (phase H1): transported temperature.
+            opt.heat_transport = (norm(val) == "ON" || norm(val) == "YES");
+
+        // Heat plan §1/§2.1 (phase H2) — energy bookkeeping and the
+        // SurfaceExchange coefficients, CSH Table 4.1 names and defaults.
+        } else if (key == "WATER_DENSITY") {
+            openswmm::from_chars_double(val.data(), val.data() + val.size(),
+                                        opt.water_density);
+        } else if (key == "WATER_SPECIFIC_HEAT_CAPACITY") {
+            openswmm::from_chars_double(val.data(), val.data() + val.size(),
+                                        opt.water_specific_heat);
+        } else if (key == "WIND_FUNC_COEFF_A") {
+            openswmm::from_chars_double(val.data(), val.data() + val.size(),
+                                        opt.wind_func_coeff_a);
+        } else if (key == "WIND_FUNC_COEFF_B") {
+            openswmm::from_chars_double(val.data(), val.data() + val.size(),
+                                        opt.wind_func_coeff_b);
+        } else if (key == "PRESSURE_RATIO") {
+            openswmm::from_chars_double(val.data(), val.data() + val.size(),
+                                        opt.pressure_ratio);
+
         // -----------------------------------------------------------------
         // Timesteps
         // -----------------------------------------------------------------
@@ -168,6 +255,27 @@ void handle_options(SimulationContext& ctx, const std::vector& line
             opt.wet_step = parse_time_seconds(val);
         } else if (key == "REPORT_STEP") {
             opt.report_step = parse_time_seconds(val);
+        } else if (key == "QUALITY_STEP") {
+            // X3a: LARD transport substep (strategy §4.2). Same time
+            // spelling as the other *_STEP keys.
+            opt.quality_step = parse_time_seconds(val);
+        } else if (key == "MAX_SEGMENTS_PER_LINK") {
+            // X3a: LARD slab capacity (strategy §4.1, EPANET MAXSEGS).
+            double d = 0.0;
+            openswmm::from_chars_double(val.data(), val.data() + val.size(), d);
+            opt.max_segments_per_link = static_cast(d);
+        } else if (key == "DISPERSION") {
+            // X3b: LARD RWPT toggle (GUI-plan Lagrangian-group key).
+            // Unknown values fall to ext_options for diagnostics.
+            const std::string dv = norm(val);
+            if      (dv == "RWPT")           opt.lard_rwpt = true;
+            else if (dv == "OFF" || dv == "NONE") opt.lard_rwpt = false;
+            else opt.ext_options[key] = val;
+        } else if (key == "RWPT_SEED") {
+            // X3b: D-L6 deterministic counter-RNG seed.
+            double d = 0.0;
+            openswmm::from_chars_double(val.data(), val.data() + val.size(), d);
+            opt.rwpt_seed = static_cast(d);
 
         // -----------------------------------------------------------------
         // Simulation dates / times
@@ -267,8 +375,13 @@ void handle_options(SimulationContext& ctx, const std::vector& line
               if (sp < se) ++sp;
               std::from_chars(sp, se, sd);
             }
+            // NON-leap anchor (2001), matching InpWriter's fmt_sweep and the
+            // 365-day default (sweep_end = 365 = 12/31). The old leap-year
+            // anchor (2000) made 12/31 parse as 366, which fmt_sweep then
+            // wrote back as 1/1 — every date past Feb 28 shifted a day per
+            // save/reopen cycle (found by the H6b save check).
             opt.sweep_start = datetime::dayOfYear(
-                datetime::encodeDate(2000, static_cast(sm), static_cast(sd)));
+                datetime::encodeDate(2001, static_cast(sm), static_cast(sd)));
         } else if (key == "SWEEP_END") {
             unsigned sm = 12, sd = 31;
             { const char* sp = val.data(); const char* se = sp + val.size();
@@ -278,7 +391,7 @@ void handle_options(SimulationContext& ctx, const std::vector& line
               std::from_chars(sp, se, sd);
             }
             opt.sweep_end = datetime::dayOfYear(
-                datetime::encodeDate(2000, static_cast(sm), static_cast(sd)));
+                datetime::encodeDate(2001, static_cast(sm), static_cast(sd)));
 
         } else if (key == "NORMAL_FLOW_LIMITED") {
             const std::string nv = norm(val);
@@ -305,6 +418,10 @@ void handle_options(SimulationContext& ctx, const std::vector& line
             if      (sv == "EXTRAN")       opt.surcharge_method = 0;
             else if (sv == "SLOT")         opt.surcharge_method = 1;
             else if (sv == "DYNAMIC_SLOT") opt.surcharge_method = 2;
+            else if (sv == "TPA")          opt.surcharge_method = 3;  // issue #156
+
+        } else if (key == "TPA_CELERITY") {  // issue #156
+            opt.tpa_celerity = to_double(val);
 
         } else if (key == "DPS_CELERITY") {
             opt.dps_target_celerity = to_double(val);
@@ -315,6 +432,25 @@ void handle_options(SimulationContext& ctx, const std::vector& line
         } else if (key == "DPS_DECAY_TIME") {
             opt.dps_decay_time = to_double(val);
 
+        // Unsteady friction (issue #156). Accepted-and-INERT, the same
+        // posture as the FV block below: nothing downstream reads either key
+        // yet (the Vitkovsky source term is Phase 2), so parsing them only
+        // stops a deck that names them from drawing an unknown-option warning
+        // and lets the writer carry them across a save.
+        } else if (key == "UNSTEADY_FRICTION") {
+            const std::string uv = norm(val);
+            if      (uv == "NONE")      opt.unsteady_friction = 0;
+            else if (uv == "VITKOVSKY") opt.unsteady_friction = 1;
+
+        } else if (key == "UF_K3") {
+            opt.uf_k3 = to_double(val);
+
+        } else if (key == "REPORT_SIGNED_HEADS") {  // issue #156 O-6
+            const std::string sv2 = norm(val);
+            opt.report_signed_heads =
+                (sv2 == "YES" || sv2 == "TRUE" || sv2 == "ON" || sv2 == "1")
+                    ? 1 : 0;
+
         // -----------------------------------------------------------------
         // Explicit finite-volume solver (FLOW_ROUTING FV).
         //
@@ -363,6 +499,16 @@ void handle_options(SimulationContext& ctx, const std::vector& line
         } else if (key == "FV_SLOT_CELERITY") {
             opt.fv.slot_celerity = to_double(val);
 
+        } else if (key == "FV_PRESSURIZED_IMPLICIT") {
+            const std::string pv = norm(val);
+            opt.fv.pressurized_implicit =
+                (pv == "YES" || pv == "TRUE" || pv == "ON" || pv == "1");
+
+        } else if (key == "FV_PRESSURE_CLOSURE") {  // issue #156 Phase 4
+            const std::string pc = norm(val);
+            if      (pc == "SLOT") opt.fv.pressure_closure = 0;
+            else if (pc == "TPA")  opt.fv.pressure_closure = 1;
+
         } else if (key == "FV_DISPERSION") {
             opt.fv.dispersion = to_double(val);
 
@@ -374,11 +520,21 @@ void handle_options(SimulationContext& ctx, const std::vector& line
                 opt.fv.structure_coupling = fv::StructureCoupling::ROUTING_STEP;
 
         } else if (key == "FV_NODE_COUPLING") {
-            const std::string nv = norm(val);
-            if      (nv == "EXPLICIT")
-                opt.fv.node_coupling = fv::NodeCoupling::EXPLICIT;
-            else if (nv == "SEMI_IMPLICIT")
-                opt.fv.node_coupling = fv::NodeCoupling::SEMI_IMPLICIT;
+            // RETIRED 2026-08-29 with FV_NODE_DT and FV_NODE_PICARD below.
+            // Two retirement tiers, on purpose: these three had an effect and
+            // warn when a deck asks for the behaviour that no longer exists
+            // (a calibrated model would otherwise change answers silently);
+            // FV_NODE_CELL_COUPLING / FV_JUNCTION_MODEL further down were
+            // already no-ops and stay silent. Spelling out the former default
+            // is not warned -- it is what every deck gets.
+            if (norm(val) == "EXPLICIT") {
+                ctx.warnings.push_back(
+                    "WARNING: FV_NODE_COUPLING EXPLICIT is retired and will be "
+                    "treated as SEMI_IMPLICIT - storage nodes are always coupled "
+                    "semi-implicitly (plain junctions are algebraic interfaces "
+                    "under either).");
+                if (ctx.warning_code == 0) ctx.warning_code = 101;
+            }
 
         } else if (key == "FV_COMPACTION") {
             const std::string bv = norm(val);
@@ -400,6 +556,11 @@ void handle_options(SimulationContext& ctx, const std::vector& line
             const std::string bv = norm(val);
             opt.fv.lts = !(bv == "NO" || bv == "FALSE" || bv == "0" || bv == "OFF");
 
+        } else if (key == "FV_NODE_FEEDBACK_DT") {
+            const std::string bv = norm(val);
+            opt.fv.node_feedback_dt =
+                !(bv == "NO" || bv == "FALSE" || bv == "0" || bv == "OFF");
+
         } else if (key == "FV_LTS_MAX_TIERS") {
             opt.fv.lts_max_tiers = std::max(1, static_cast(to_double(val)));
 
@@ -407,12 +568,25 @@ void handle_options(SimulationContext& ctx, const std::vector& line
             opt.fv.cfl_census_interval = std::max(1, static_cast(to_double(val)));
 
         } else if (key == "FV_NODE_DT") {
-            const std::string nd = norm(val);
-            if      (nd == "STABILITY") opt.fv.node_dt_limit = fv::NodeDtLimit::STABILITY;
-            else if (nd == "NONE")      opt.fv.node_dt_limit = fv::NodeDtLimit::NONE;
+            // RETIRED 2026-08-29 -- see FV_NODE_COUPLING above.
+            if (norm(val) == "NONE") {
+                ctx.warnings.push_back(
+                    "WARNING: FV_NODE_DT NONE is retired and will be treated as "
+                    "STABILITY - the node accuracy bound is always armed (it "
+                    "binds storage nodes only; algebraic junctions and outfalls "
+                    "are exempt).");
+                if (ctx.warning_code == 0) ctx.warning_code = 101;
+            }
 
         } else if (key == "FV_NODE_PICARD") {
-            opt.fv.node_picard_sweeps = std::max(1, static_cast(to_double(val)));
+            // RETIRED 2026-08-29 -- see FV_NODE_COUPLING above.
+            if (std::max(1, static_cast(to_double(val))) > 1) {
+                ctx.warnings.push_back(
+                    "WARNING: FV_NODE_PICARD " + val + " is retired and will be "
+                    "treated as 1 - the semi-implicit node correction is always "
+                    "a single sweep.");
+                if (ctx.warning_code == 0) ctx.warning_code = 101;
+            }
 
         } else if (key == "FV_NODE_CELL_COUPLING" ||
                    key == "FV_JUNCTION_MODEL") {
@@ -427,9 +601,29 @@ void handle_options(SimulationContext& ctx, const std::vector& line
             else if (nc == "SEMI_IMPLICIT") opt.node_continuity = NodeContinuity::SEMI_IMPLICIT;
 
         } else if (key == "VIRTUAL_JUNCTION_MOMENTUM") {
+            // RETIRED 2026-08-14. FULL is accepted and warned for one release,
+            // then the keyword goes the way of FV_NODE_CELL_COUPLING above.
+            // It was measured to be defective, not merely inaccurate: its
+            // cross-junction term dq4j is sign-inverted with respect to the
+            // per-link convective term it supplements (at constant Q,
+            // Δ(v²A) = −v²ΔA), and it is applied to BOTH adjacent links on top
+            // of each link's own full-length dq4. On SWASHES macdonald-periodic
+            // it destroyed 224-325 % of the routed volume; negating the term
+            // restores mass conservation but still leaves l1 5.24 % against
+            // BASIC's 0.163 % and plain DW's 0.141 %, so there is no
+            // term-level correction worth keeping. Evidence:
+            // epaswmm5_qa suites/swashes plans/VJ_MOMENTUM_SCOPE.md Phase 3.
             const std::string vm = norm(val);
-            if      (vm == "BASIC") opt.virtual_junction_momentum = 0;
-            else if (vm == "FULL")  opt.virtual_junction_momentum = 1;
+            opt.virtual_junction_momentum = 0;
+            if (vm == "FULL") {
+                ctx.warnings.push_back(
+                    "WARNING: VIRTUAL_JUNCTION_MOMENTUM FULL is retired and "
+                    "will be treated as BASIC - the cross-junction momentum "
+                    "term was not mass conserving.");
+                if (ctx.warning_code == 0) {
+                    ctx.warning_code = 101;  // SWMM_WARN_UNKNOWN_OPTION
+                }
+            }
 
         } else if (key == "ANDERSON_ACCEL") {
             const std::string av = norm(val);
diff --git a/src/engine/input/handlers/OptionsHandler.hpp b/src/engine/input/handlers/OptionsHandler.hpp
index 1adffaeba..3023a10e9 100644
--- a/src/engine/input/handlers/OptionsHandler.hpp
+++ b/src/engine/input/handlers/OptionsHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OptionsHandler.hpp
  * @brief [OPTIONS] section handler declaration.
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_OPTIONS_HANDLER_HPP
diff --git a/src/engine/input/handlers/PluginsHandler.cpp b/src/engine/input/handlers/PluginsHandler.cpp
index fa130f461..9cab49e1b 100644
--- a/src/engine/input/handlers/PluginsHandler.cpp
+++ b/src/engine/input/handlers/PluginsHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginsHandler.cpp
  * @brief [PLUGINS] section handler — parses plugin library specs (Phase 4, R12).
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "PluginsHandler.hpp"
diff --git a/src/engine/input/handlers/PluginsHandler.hpp b/src/engine/input/handlers/PluginsHandler.hpp
index c902334f9..411185854 100644
--- a/src/engine/input/handlers/PluginsHandler.hpp
+++ b/src/engine/input/handlers/PluginsHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginsHandler.hpp
  * @brief [PLUGINS] section handler (Phase 4, R12).
@@ -24,7 +40,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_PLUGINS_HANDLER_HPP
diff --git a/src/engine/input/handlers/ProcessComponentsHandler.cpp b/src/engine/input/handlers/ProcessComponentsHandler.cpp
new file mode 100644
index 000000000..cec08c935
--- /dev/null
+++ b/src/engine/input/handlers/ProcessComponentsHandler.cpp
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ProcessComponentsHandler.cpp
+ * @brief [PROCESS_COMPONENTS] section handler — parses component
+ *        registrations (Unified Transport suite, D-UT8; phase IO1).
+ *
+ * @see ProcessComponentsHandler.hpp
+ * @ingroup engine_input
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ProcessComponentsHandler.hpp"
+
+#include "../Tokenizer.hpp"
+#include "../../core/SimulationContext.hpp"
+
+namespace openswmm::input {
+
+namespace {
+
+/// Split `key="value"` / `key=value` (quotes stripped). Returns false when
+/// the token carries no '='.
+bool split_kv(const std::string& tok, std::string& key, std::string& val) {
+    const auto eq = tok.find('=');
+    if (eq == std::string::npos || eq == 0) return false;
+    key = tok.substr(0, eq);
+    val = tok.substr(eq + 1);
+    if (val.size() >= 2 && val.front() == '"' && val.back() == '"')
+        val = val.substr(1, val.size() - 2);
+    return true;
+}
+
+}  // namespace
+
+void handle_process_components(SimulationContext& ctx,
+                               const std::vector& lines) {
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+
+        ProcessComponentSpec spec;
+        spec.id = tok[0];
+
+        for (std::size_t i = 1; i < tok.size(); ++i) {
+            std::string key, val;
+            if (!split_kv(tok[i], key, val)) {
+                ctx.errors.push_back(
+                    "[PROCESS_COMPONENTS] '" + spec.id +
+                    "': argument '" + tok[i] +
+                    "' is not a key=\"value\" pair.");
+                continue;
+            }
+            if (Tokenizer::to_upper(key) == "CONFIG") {
+                spec.config_path = val;
+            } else {
+                spec.args.emplace_back(std::move(key), std::move(val));
+            }
+        }
+
+        ctx.process_component_specs.push_back(std::move(spec));
+    }
+}
+
+}  // namespace openswmm::input
diff --git a/src/engine/input/handlers/ProcessComponentsHandler.hpp b/src/engine/input/handlers/ProcessComponentsHandler.hpp
new file mode 100644
index 000000000..09b333445
--- /dev/null
+++ b/src/engine/input/handlers/ProcessComponentsHandler.hpp
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ProcessComponentsHandler.hpp
+ * @brief [PROCESS_COMPONENTS] section handler (Unified Transport suite, D-UT8).
+ *
+ * Row format (whitespace delimited, [PLUGINS]-style):
+ * @code
+ * [PROCESS_COMPONENTS]
+ * ;;ComponentId / library                 Arguments (key="value")
+ * org.hydrocouple.openswmm.reactions      config="model.rxn"
+ * ./components/libmycomponent.so          config="custom.cfg" version="1.2"
+ * @endcode
+ *
+ * The first token is the component id (or, reserved for phase HC2, a shared
+ * library path). Remaining tokens are key="value" pairs; `config=` names the
+ * component's external configuration file, resolved relative to the parent
+ * .inp at open() (the [2D_MESH_FILE] path rules). Registration implies
+ * enablement; resolution and config delivery happen in
+ * SWMMEngine::open() via plugins/ProcessComponentRegistry.
+ *
+ * @see plans/transport/TRANSPORT_IO_PLUGIN_CONFIG_PLAN.md §2
+ * @ingroup engine_input
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_INPUT_PROCESS_COMPONENTS_HANDLER_HPP
+#define OPENSWMM_ENGINE_INPUT_PROCESS_COMPONENTS_HANDLER_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::input {
+
+void handle_process_components(SimulationContext& ctx,
+                               const std::vector& lines);
+
+}  // namespace openswmm::input
+
+#endif  // OPENSWMM_ENGINE_INPUT_PROCESS_COMPONENTS_HANDLER_HPP
diff --git a/src/engine/input/handlers/QualityHandler.cpp b/src/engine/input/handlers/QualityHandler.cpp
index 7b86b57be..b28c85c96 100644
--- a/src/engine/input/handlers/QualityHandler.cpp
+++ b/src/engine/input/handlers/QualityHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file QualityHandler.cpp
  * @brief Section handlers for [POLLUTANTS], [LANDUSES], [COVERAGES],
@@ -51,7 +67,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "QualityHandler.hpp"
@@ -63,12 +79,45 @@
 #include "../../data/QualityData.hpp"
 
 #include "../InputParseUtils.hpp"
+#include "../../core/Constants.hpp"
 
 #include 
+#include 
 #include 
 
 namespace openswmm::input {
 
+namespace {
+
+/// Legacy `findmatch(tok, Words)` (input.c:791) over a keyword list, where
+/// `match(str, substr)` (input.c:805) returns true when the KEYWORD is a
+/// PREFIX of the token — not when the two are equal.
+///
+/// That distinction is load-bearing here. Legacy's BuildupTypeWords are the
+/// three-letter stems POW / EXP / SAT / EXT and its WashoffTypeWords are
+/// EXP / RC / EMC, while decks — including everything the SWMM GUI writes —
+/// spell the functions out as POWER, EXPON, SATUR, EXTERNAL. Comparing for
+/// equality left `func_type` at NONE for every one of them, so the land use
+/// silently had NO buildup function: nothing accumulated over the antecedent
+/// dry period and there was nothing for the washoff to wash off.
+///
+/// Returns the keyword's index, or -1 for no match.
+int findmatch_prefix(const std::string& token,
+                     std::initializer_list words) {
+    int i = 0;
+    for (const char* w : words) {
+        // The tokenizer has already stripped the leading blanks legacy's
+        // match() skips, so this is a plain prefix test.
+        const std::size_t n = std::char_traits::length(w);
+        if (n > 0 && token.size() >= n && token.compare(0, n, w) == 0)
+            return i;
+        ++i;
+    }
+    return -1;
+}
+
+}  // namespace
+
 // ============================================================================
 // handle_pollutants()
 // ============================================================================
@@ -112,7 +161,11 @@ void handle_pollutants(SimulationContext& ctx, const std::vector& l
         if (tok.size() > 2) ctx.pollutants.c_rain[idx]  = to_double(tok[2]);
         if (tok.size() > 3) ctx.pollutants.c_gw[idx]    = to_double(tok[3]);
         if (tok.size() > 4) ctx.pollutants.c_rdii[idx]  = to_double(tok[4]);
-        if (tok.size() > 5) ctx.pollutants.k_decay[idx] = to_double(tok[5]);
+        // The Kdecay column is 1/day; store 1/sec, exactly as legacy
+        // does (landuse.c divides by SECperDAY at parse) — KD1.
+        if (tok.size() > 5)
+            ctx.pollutants.k_decay[idx] =
+                to_double(tok[5]) / constants::SEC_PER_DAY;
 
         // SnowOnly
         if (tok.size() > 6) {
@@ -190,6 +243,15 @@ void handle_coverages(SimulationContext& ctx, const std::vector& li
     if (ctx.subcatches.coverage.size() < total) {
         ctx.subcatches.coverage.assign(total, 0.0);
     }
+    // BW-MSX round (2026-09-19), pre-existing defect: the per-(subcatchment,
+    // land use) last-swept counters were sized only by the C API
+    // (resize_coverage) and the GeoPackage reader — never by this handler —
+    // so street sweeping silently never fired on an .inp deck (the A7 loop
+    // skips any index past the empty array). Size them with the coverage
+    // matrix, as resize_coverage does.
+    if (ctx.subcatches.sweep_last_swept.size() < total) {
+        ctx.subcatches.sweep_last_swept.assign(total, 0.0);
+    }
     ctx.subcatches.coverage_n_landuses = n_landuses;
 
     for (const auto& line : lines) {
@@ -214,10 +276,11 @@ void handle_coverages(SimulationContext& ctx, const std::vector& li
 void handle_buildup(SimulationContext& ctx, const std::vector& lines) {
     const int n_landuses   = ctx.landuse_names.size();
     const int n_pollutants = ctx.pollutant_names.size();
-    if (n_landuses <= 0 || n_pollutants <= 0) return;
+    if (n_landuses <= 0) return;
 
     // Ensure buildup arrays are sized
-    if (ctx.buildup.n_landuses != n_landuses || ctx.buildup.n_pollutants != n_pollutants) {
+    if (n_pollutants > 0 &&
+        (ctx.buildup.n_landuses != n_landuses || ctx.buildup.n_pollutants != n_pollutants)) {
         ctx.buildup.resize(n_landuses, n_pollutants);
     }
 
@@ -230,17 +293,36 @@ void handle_buildup(SimulationContext& ctx, const std::vector& line
         if (lu_idx < 0) continue;
 
         const int p_idx = ctx.pollutant_names.find(tok[1]);
-        if (p_idx < 0) continue;
+        if (p_idx < 0) {
+            // BW-MSX: not a pollutant — park the row by name for the
+            // reactions component's species, resolved after the component
+            // is applied (msxsurf::resolve). Same deferral as [INITIAL_QUALITY].
+            MsxSurfaceRows::Buildup r;
+            r.landuse = tok[0]; r.species = tok[1];
+            const std::string ts = Tokenizer::to_upper(tok[2]);
+            const int mbt = findmatch_prefix(ts, {"NONE", "POW", "EXP", "SAT", "EXT"});
+            r.func_type = (mbt >= 0) ? mbt : 0;
+            r.c1 = to_double(tok[3]);
+            r.c2 = to_double(tok[4]);
+            if (tok.size() > 5) {
+                if (r.func_type == 4) r.ts_name = tok[5];
+                else                  r.c3 = to_double(tok[5]);
+            }
+            if (tok.size() > 6) r.normalizer = (Tokenizer::to_upper(tok[6]) == "CURB") ? 1 : 0;
+            ctx.reactions.surface.rows.buildup.push_back(std::move(r));
+            continue;
+        }
+        if (n_pollutants <= 0) continue;
 
         const auto flat = static_cast(lu_idx * n_pollutants + p_idx);
 
-        // Type: NONE=0, POW=1, EXP=2, SAT=3, EXT=4
+        // Type: NONE=0, POW=1, EXP=2, SAT=3, EXT=4 — legacy BuildupTypeWords,
+        // matched by PREFIX so the decks' POWER / EXPON / SATUR / EXTERNAL
+        // reach their stems (see findmatch_prefix).
         const std::string type_str = Tokenizer::to_upper(tok[2]);
-        if      (type_str == "POW") ctx.buildup.func_type[flat] = 1;
-        else if (type_str == "EXP") ctx.buildup.func_type[flat] = 2;
-        else if (type_str == "SAT") ctx.buildup.func_type[flat] = 3;
-        else if (type_str == "EXT") ctx.buildup.func_type[flat] = 4;
-        else                        ctx.buildup.func_type[flat] = 0;
+        const int bt = findmatch_prefix(type_str,
+                                        {"NONE", "POW", "EXP", "SAT", "EXT"});
+        ctx.buildup.func_type[flat] = (bt >= 0) ? bt : 0;
 
         ctx.buildup.coeff1[flat] = to_double(tok[3]);
         ctx.buildup.coeff2[flat] = to_double(tok[4]);
@@ -271,10 +353,11 @@ void handle_buildup(SimulationContext& ctx, const std::vector& line
 void handle_washoff(SimulationContext& ctx, const std::vector& lines) {
     const int n_landuses   = ctx.landuse_names.size();
     const int n_pollutants = ctx.pollutant_names.size();
-    if (n_landuses <= 0 || n_pollutants <= 0) return;
+    if (n_landuses <= 0) return;
 
     // Ensure washoff arrays are sized
-    if (ctx.washoff.n_landuses != n_landuses || ctx.washoff.n_pollutants != n_pollutants) {
+    if (n_pollutants > 0 &&
+        (ctx.washoff.n_landuses != n_landuses || ctx.washoff.n_pollutants != n_pollutants)) {
         ctx.washoff.resize(n_landuses, n_pollutants);
     }
 
@@ -287,16 +370,30 @@ void handle_washoff(SimulationContext& ctx, const std::vector& line
         if (lu_idx < 0) continue;
 
         const int p_idx = ctx.pollutant_names.find(tok[1]);
-        if (p_idx < 0) continue;
+        if (p_idx < 0) {
+            // BW-MSX: park by name (see handle_buildup).
+            MsxSurfaceRows::Washoff r;
+            r.landuse = tok[0]; r.species = tok[1];
+            const std::string ts = Tokenizer::to_upper(tok[2]);
+            const int mwt = findmatch_prefix(ts, {"NONE", "EXP", "RC", "EMC"});
+            r.func_type = (mwt >= 0) ? mwt : 0;
+            r.coeff = to_double(tok[3]);
+            r.expon = to_double(tok[4]);
+            if (tok.size() > 5) r.sweep_effic = to_double(tok[5]);
+            if (tok.size() > 6) r.bmp_effic   = to_double(tok[6]);
+            ctx.reactions.surface.rows.washoff.push_back(std::move(r));
+            continue;
+        }
+        if (n_pollutants <= 0) continue;
 
         const auto flat = static_cast(lu_idx * n_pollutants + p_idx);
 
-        // Type: NONE=0, EXP=1, RC=2, EMC=3
+        // Type: NONE=0, EXP=1, RC=2, EMC=3 — legacy WashoffTypeWords, matched
+        // by PREFIX so a deck spelling EXPON reaches EXP (see
+        // findmatch_prefix).
         const std::string type_str = Tokenizer::to_upper(tok[2]);
-        if      (type_str == "EXP") ctx.washoff.func_type[flat] = 1;
-        else if (type_str == "RC")  ctx.washoff.func_type[flat] = 2;
-        else if (type_str == "EMC") ctx.washoff.func_type[flat] = 3;
-        else                        ctx.washoff.func_type[flat] = 0;
+        const int wt = findmatch_prefix(type_str, {"NONE", "EXP", "RC", "EMC"});
+        ctx.washoff.func_type[flat] = (wt >= 0) ? wt : 0;
 
         ctx.washoff.coeff[flat] = to_double(tok[3]);
         ctx.washoff.expon[flat] = to_double(tok[4]);
@@ -349,6 +446,17 @@ void handle_treatment(SimulationContext& ctx, const std::vector& li
 
 void handle_loadings(SimulationContext& ctx, const std::vector& lines) {
     const int n_pollutants = ctx.pollutant_names.size();
+    // BW-MSX: rows naming a non-pollutant are parked by name for the
+    // reactions component's species (msxsurf::resolve); a deck with no
+    // [POLLUTANTS] at all may still carry MSX loadings.
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.size() < 3) continue;
+        if (ctx.pollutant_names.find(tok[1]) >= 0) continue;
+        MsxSurfaceRows::Loading r;
+        r.subcatch = tok[0]; r.species = tok[1]; r.value = to_double(tok[2]);
+        ctx.reactions.surface.rows.loadings.push_back(std::move(r));
+    }
     if (n_pollutants <= 0) return;
 
     // Size the quality arrays now (iteration 4): they used to be sized only
@@ -373,10 +481,79 @@ void handle_loadings(SimulationContext& ctx, const std::vector& lin
         if (p_idx < 0) continue;
 
         const auto flat = static_cast(sub_idx * n_pollutants + p_idx);
-        if (flat < ctx.subcatches.conc.size()) {
-            ctx.subcatches.conc[flat] = to_double(tok[2]);
+        // The row is an initial surface BUILDUP per unit area, not a runoff
+        // concentration — see SubcatchData::init_loading.
+        if (flat < ctx.subcatches.init_loading.size()) {
+            ctx.subcatches.init_loading[flat] = to_double(tok[2]);
         }
     }
 }
 
+// ============================================================================
+// handle_initial_quality()
+// ============================================================================
+// [INITIAL_QUALITY] format:
+//   ;;Scope   Element   Constituent      Value
+//   NODE      J1        TSS              12.5
+//   NODE      ST1       __WATER_AGE__    6.0        ; hours
+//   LINK      C3        __TEMPERATURE__  18.5       ; degC
+//
+// Per-element initial values overriding the global [POLLUTANTS] Cinit /
+// sidecar INITIAL_STATE seeds. Element names and constituents may be defined
+// in later sections, so both resolution and constituent classification are
+// deferred to PostParseResolver (legacy two-pass parsing is order-
+// independent); only row shape is validated here, loudly.
+// ============================================================================
+
+void handle_initial_quality(SimulationContext& ctx,
+                            const std::vector& lines) {
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        // U2: `FILE ` names a CSV sidecar (scope,element,constituent,
+        // value per line; header optional) read at open once the .inp
+        // directory is known (SWMMEngine::open → load_initial_quality_file).
+        if (Tokenizer::to_upper(tok[0]) == "FILE") {
+            if (tok.size() < 2) {
+                ctx.errors.push_back("[INITIAL_QUALITY] FILE needs a path.");
+                continue;
+            }
+            ctx.initial_quality.file = tok[1];
+            continue;
+        }
+        if (tok.size() < 4) {
+            ctx.errors.push_back(
+                "[INITIAL_QUALITY] row needs NODE|LINK element constituent "
+                "value: '" + line + "'.");
+            continue;
+        }
+
+        const std::string scope = Tokenizer::to_upper(tok[0]);
+        bool link = false;
+        if (scope == "LINK") {
+            link = true;
+        } else if (scope != "NODE") {
+            ctx.errors.push_back(
+                "[INITIAL_QUALITY] scope must be NODE or LINK: '" + tok[0] +
+                "'.");
+            continue;
+        }
+
+        // Value must be fully numeric — a lenient default here would turn a
+        // typo into a silent 0.0 initial condition.
+        const std::string& vs = tok[3];
+        double v = 0.0;
+        auto [p, ec] = openswmm::from_chars_double(vs.data(),
+                                                   vs.data() + vs.size(), v);
+        if (ec != std::errc{} || p != vs.data() + vs.size()) {
+            ctx.errors.push_back(
+                "[INITIAL_QUALITY] bad value '" + vs + "' for '" + tok[2] +
+                "' at " + scope + " '" + tok[1] + "'.");
+            continue;
+        }
+
+        ctx.initial_quality.add(link, tok[1], tok[2], v);
+    }
+}
+
 } /* namespace openswmm::input */
diff --git a/src/engine/input/handlers/QualityHandler.hpp b/src/engine/input/handlers/QualityHandler.hpp
index 80e4c48ac..cabee639f 100644
--- a/src/engine/input/handlers/QualityHandler.hpp
+++ b/src/engine/input/handlers/QualityHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file QualityHandler.hpp
  * @brief Section handlers for water quality input sections.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_QUALITY_HANDLER_HPP
@@ -39,6 +55,9 @@ void handle_treatment(SimulationContext& ctx, const std::vector& li
 /** @brief Parse [LOADINGS] — initial pollutant buildup on subcatchments. */
 void handle_loadings(SimulationContext& ctx, const std::vector& lines);
 
+/** @brief Parse [INITIAL_QUALITY] — per-node/per-link initial concentrations. */
+void handle_initial_quality(SimulationContext& ctx, const std::vector& lines);
+
 } /* namespace openswmm::input */
 
 #endif /* OPENSWMM_ENGINE_QUALITY_HANDLER_HPP */
diff --git a/src/engine/input/handlers/SpatialHandler.cpp b/src/engine/input/handlers/SpatialHandler.cpp
index 32b818572..3b1d533ad 100644
--- a/src/engine/input/handlers/SpatialHandler.cpp
+++ b/src/engine/input/handlers/SpatialHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SpatialHandler.cpp
  * @brief Section handlers for [MAP], [VERTICES], [POLYGONS], [SYMBOLS].
@@ -34,7 +50,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "SpatialHandler.hpp"
@@ -83,12 +99,29 @@ void handle_vertices(SimulationContext& ctx, const std::vector& lin
     if (ctx.spatial.link_vertices_x.size() < nl) ctx.spatial.link_vertices_x.resize(nl);
     if (ctx.spatial.link_vertices_y.size() < nl) ctx.spatial.link_vertices_y.resize(nl);
 
+    // Geometry sections are the row-count leaders in a large model, so the
+    // per-row token vector is hoisted and reused: after the first row this
+    // allocates nothing. tokenize_views_into cannot handle quoted tokens, so
+    // a line containing a quote falls back to the owned tokenizer — behaviour
+    // is identical either way, only the allocation differs.
+    std::vector tok;
+    std::vector      quoted;
+    auto split = [&](const std::string& line) -> const std::vector& {
+        if (line.find('"') == std::string::npos) {
+            Tokenizer::tokenize_views_into(line, tok);
+        } else {
+            quoted = Tokenizer::tokenize(line);
+            tok.assign(quoted.begin(), quoted.end());
+        }
+        return tok;
+    };
+
     // Rebuild from section contents to preserve deterministic per-link order.
     for (auto& xs : ctx.spatial.link_vertices_x) xs.clear();
     for (auto& ys : ctx.spatial.link_vertices_y) ys.clear();
 
     for (const auto& line : lines) {
-        auto tok = Tokenizer::tokenize(line);
+        const auto& tok = split(line);
         if (tok.size() < 3) continue;
 
         const int idx = ctx.link_names.find(tok[0]);
@@ -114,12 +147,29 @@ void handle_polygons(SimulationContext& ctx, const std::vector& lin
     if (ctx.spatial.subcatch_polygon_x.size() < ns) ctx.spatial.subcatch_polygon_x.resize(ns);
     if (ctx.spatial.subcatch_polygon_y.size() < ns) ctx.spatial.subcatch_polygon_y.resize(ns);
 
+    // Geometry sections are the row-count leaders in a large model, so the
+    // per-row token vector is hoisted and reused: after the first row this
+    // allocates nothing. tokenize_views_into cannot handle quoted tokens, so
+    // a line containing a quote falls back to the owned tokenizer — behaviour
+    // is identical either way, only the allocation differs.
+    std::vector tok;
+    std::vector      quoted;
+    auto split = [&](const std::string& line) -> const std::vector& {
+        if (line.find('"') == std::string::npos) {
+            Tokenizer::tokenize_views_into(line, tok);
+        } else {
+            quoted = Tokenizer::tokenize(line);
+            tok.assign(quoted.begin(), quoted.end());
+        }
+        return tok;
+    };
+
     // Rebuild from section contents to preserve deterministic per-subcatch order.
     for (auto& xs : ctx.spatial.subcatch_polygon_x) xs.clear();
     for (auto& ys : ctx.spatial.subcatch_polygon_y) ys.clear();
 
     for (const auto& line : lines) {
-        auto tok = Tokenizer::tokenize(line);
+        const auto& tok = split(line);
         if (tok.size() < 3) continue;
 
         const int idx = ctx.subcatch_names.find(tok[0]);
diff --git a/src/engine/input/handlers/SpatialHandler.hpp b/src/engine/input/handlers/SpatialHandler.hpp
index cba0c1f0f..93e638cf0 100644
--- a/src/engine/input/handlers/SpatialHandler.hpp
+++ b/src/engine/input/handlers/SpatialHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SpatialHandler.hpp
  * @brief Section handlers for spatial sections: [MAP], [VERTICES], [POLYGONS].
@@ -6,7 +22,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SPATIAL_HANDLER_HPP
diff --git a/src/engine/input/handlers/TablesHandler.cpp b/src/engine/input/handlers/TablesHandler.cpp
index a9498587f..63bbe1941 100644
--- a/src/engine/input/handlers/TablesHandler.cpp
+++ b/src/engine/input/handlers/TablesHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TablesHandler.cpp
  * @brief Section handlers for [TIMESERIES] and [CURVES].
@@ -31,7 +47,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TablesHandler.hpp"
@@ -64,6 +80,21 @@ void handle_timeseries(SimulationContext& ctx, const std::vector& l
     double      last_date = 0.0;
     int         current_idx = -1;
 
+    // Legacy keeps the date anchor PER SERIES (Tseries[j].lastDate), not per
+    // section scan, so interleaved rows of different series must each resume
+    // their own anchor. Rows are almost always grouped by series, so the
+    // anchor is kept in these locals on the hot path and swapped through the
+    // map only when the row's series changes. `seen_date == false` means the
+    // series has not yet had an explicit date token: its date-less rows are
+    // elapsed times anchored at the simulation start (legacy input.c:170
+    // seeds lastDate = StartDate + StartTime). Those rows are stored with
+    // x relative to 0 and COUNTED in Table::n_relative; the start_date
+    // offset is applied later by resolve_cross_references(), because
+    // [OPTIONS] may legally appear after [TIMESERIES] in the file.
+    struct SeriesParseState { double last_date = 0.0; bool seen_date = false; };
+    std::unordered_map series_state;
+    bool seen_date = false;
+
     for (const auto& pl : parse_section(lines)) {
         auto tok = Tokenizer::tokenize(pl.data);
         if (tok.empty()) continue;
@@ -71,7 +102,14 @@ void handle_timeseries(SimulationContext& ctx, const std::vector& l
         // First column: name (non-empty) or continuation (empty — same name)
         const std::string& maybe_name = tok[0];
         bool is_new_table = false;
-        if (!maybe_name.empty()) {
+        // Standard SWMM repeats the series name on every row, so the common
+        // case is "same table as the previous row". Skipping the lookup then
+        // keeps the whole section at one lookup per DISTINCT series.
+        if (!maybe_name.empty() &&
+            !(current_idx >= 0 && ieq(maybe_name, current_name))) {
+            // Park the outgoing series' anchor state before switching.
+            if (current_idx >= 0)
+                series_state[current_idx] = {last_date, seen_date};
             current_name = maybe_name;
             // Ensure table exists (kind-scoped: a curve with the same name
             // is a DIFFERENT object, matching legacy's separate hash tables)
@@ -80,6 +118,24 @@ void handle_timeseries(SimulationContext& ctx, const std::vector& l
                 current_idx = ctx.tables.add(current_name, TableType::TIMESERIES);
                 is_new_table = true;
             }
+            const auto it = series_state.find(current_idx);
+            if (it != series_state.end()) {
+                last_date = it->second.last_date;
+                seen_date = it->second.seen_date;
+            } else if (current_idx < ctx.n_tables() &&
+                       !ctx.tables[current_idx].x.empty()) {
+                // Series resumed from an earlier [TIMESERIES] section:
+                // reconstruct the anchor from its stored rows. All-relative
+                // rows keep any accumulated day wraps in floor(x.back());
+                // once a dated row exists, floor(x.back()) IS the last date.
+                const Table& prev = ctx.tables[current_idx];
+                seen_date = prev.n_relative <
+                            static_cast(prev.x.size());
+                last_date = std::floor(prev.x.back());
+            } else {
+                last_date = 0.0;
+                seen_date = false;
+            }
         }
         // Attach comment to the table on its first (name-introducing) row
         if (is_new_table && !pl.comment.empty() && current_idx >= 0)
@@ -125,6 +181,7 @@ void handle_timeseries(SimulationContext& ctx, const std::vector& l
             // scrambling rain/inflow hydrographs that repeat the date every N
             // rows.
             last_date = std::floor(x);
+            seen_date = true;
             y = to_double(tok[3]);
         } else if (!has_date && tok.size() >= 3) {
             // Name  Time  Value  (continuation, uses last_date)
@@ -176,6 +233,11 @@ void handle_timeseries(SimulationContext& ctx, const std::vector& l
             }
             x = last_date + time_frac;
             y = to_double(tok[2]);
+            // Date-less rows before the series' first explicit date are
+            // elapsed times anchored at the simulation start — count them
+            // so the resolver adds start_date to exactly these rows (and
+            // InpWriter emits them back in time-only form).
+            if (!seen_date) tbl.n_relative = static_cast(tbl.x.size()) + 1;
         } else {
             continue;
         }
@@ -196,6 +258,7 @@ static const std::unordered_map CURVE_TYPE_MAP = {
     {"SHAPE",     TableType::CURVE_SHAPE},
     {"CONTROL",   TableType::CURVE_CONTROL},
     {"TIDAL",     TableType::CURVE_TIDAL},
+    {"WEIR",      TableType::CURVE_WEIR},
     {"PUMP1",     TableType::CURVE_PUMP1},
     {"PUMP2",     TableType::CURVE_PUMP2},
     {"PUMP3",     TableType::CURVE_PUMP3},
@@ -214,17 +277,28 @@ void handle_curves(SimulationContext& ctx, const std::vector& lines
 
         const std::string& maybe_name = tok[0];
         bool is_new_table = false;
-        if (!maybe_name.empty()) {
+        // As in [TIMESERIES]: curve rows repeat the curve name, so skip the
+        // lookup when this row names the table we are already on. Only the
+        // lookup is skipped — the data-column handling below still runs, and
+        // current_name's spelling never reaches output (it feeds only the
+        // lookup and the add).
+        if (!maybe_name.empty() &&
+            !(current_idx >= 0 && ieq(maybe_name, current_name))) {
             current_name = maybe_name;
             // Kind-scoped: a timeseries with the same name is a DIFFERENT
             // object, matching legacy's separate hash tables.
             current_idx = ctx.find_curve(current_name);
             if (current_idx < 0) {
-                // Type may appear in tok[1] (first row only)
+                // Type appears in tok[1] on a new curve's first row. Legacy
+                // table_readCurve (table.c) rejects an unknown type keyword with
+                // ERR_KEYWORD; v6 formerly kept the default RATING and mis-parsed
+                // the token as data (e.g. a "GENERAL" curve was silently run).
                 if (tok.size() > 1) {
                     auto it = CURVE_TYPE_MAP.find(Tokenizer::to_upper(tok[1]));
                     if (it != CURVE_TYPE_MAP.end()) {
                         current_type = it->second;
+                    } else {
+                        ctx.errors.push_back(format_error(ERR_KEYWORD, tok[1]));
                     }
                 }
                 current_idx = ctx.tables.add(current_name, current_type);
diff --git a/src/engine/input/handlers/TablesHandler.hpp b/src/engine/input/handlers/TablesHandler.hpp
index dabda972c..9fb0026c6 100644
--- a/src/engine/input/handlers/TablesHandler.hpp
+++ b/src/engine/input/handlers/TablesHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TablesHandler.hpp
  * @brief Section handlers for [TIMESERIES] and [CURVES].
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TABLES_HANDLER_HPP
diff --git a/src/engine/input/handlers/TitleHandler.cpp b/src/engine/input/handlers/TitleHandler.cpp
index cdfaffbbe..d7f405a14 100644
--- a/src/engine/input/handlers/TitleHandler.cpp
+++ b/src/engine/input/handlers/TitleHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TitleHandler.cpp
  * @brief [TITLE] section handler implementation.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "TitleHandler.hpp"
diff --git a/src/engine/input/handlers/TitleHandler.hpp b/src/engine/input/handlers/TitleHandler.hpp
index 084807fd6..1729ff7ea 100644
--- a/src/engine/input/handlers/TitleHandler.hpp
+++ b/src/engine/input/handlers/TitleHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file TitleHandler.hpp
  * @brief [TITLE] section handler.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_TITLE_HANDLER_HPP
diff --git a/src/engine/input/handlers/UserFlagValuesHandler.cpp b/src/engine/input/handlers/UserFlagValuesHandler.cpp
index 05eed7e3d..6c9ceb998 100644
--- a/src/engine/input/handlers/UserFlagValuesHandler.cpp
+++ b/src/engine/input/handlers/UserFlagValuesHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UserFlagValuesHandler.cpp
  * @brief [USER_FLAG_VALUES] section handler — implements R28 per-object values.
@@ -8,7 +24,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "UserFlagValuesHandler.hpp"
diff --git a/src/engine/input/handlers/UserFlagValuesHandler.hpp b/src/engine/input/handlers/UserFlagValuesHandler.hpp
index 6084de57b..e71e3caba 100644
--- a/src/engine/input/handlers/UserFlagValuesHandler.hpp
+++ b/src/engine/input/handlers/UserFlagValuesHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UserFlagValuesHandler.hpp
  * @brief [USER_FLAG_VALUES] section handler (R28).
@@ -24,7 +40,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_USER_FLAG_VALUES_HANDLER_HPP
diff --git a/src/engine/input/handlers/UserFlagsHandler.cpp b/src/engine/input/handlers/UserFlagsHandler.cpp
index 7f977f8ed..79f434dff 100644
--- a/src/engine/input/handlers/UserFlagsHandler.cpp
+++ b/src/engine/input/handlers/UserFlagsHandler.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UserFlagsHandler.cpp
  * @brief [USER_FLAGS] section handler — parses flag schema definitions (R28).
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "UserFlagsHandler.hpp"
diff --git a/src/engine/input/handlers/UserFlagsHandler.hpp b/src/engine/input/handlers/UserFlagsHandler.hpp
index d9ba2b345..69f8f3607 100644
--- a/src/engine/input/handlers/UserFlagsHandler.hpp
+++ b/src/engine/input/handlers/UserFlagsHandler.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file UserFlagsHandler.hpp
  * @brief [USER_FLAGS] section handler (R28).
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_USER_FLAGS_HANDLER_HPP
diff --git a/src/engine/io/hdf5/Hdf5InputPlugin.cpp b/src/engine/io/hdf5/Hdf5InputPlugin.cpp
new file mode 100644
index 000000000..3969f8be8
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5InputPlugin.cpp
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5InputPlugin.cpp
+ * @brief Lifecycle wrapper over Hdf5ModelWriter / Hdf5ModelReader.
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "Hdf5InputPlugin.hpp"
+#include "Hdf5ModelWriter.hpp"
+
+namespace openswmm::h5io {
+
+int Hdf5InputPlugin::initialize(const std::vector& /*init_args*/,
+                                const IPluginComponentInfo* /*info*/) {
+    error_.clear();
+    skipped_.clear();
+    state_ = PluginState::INITIALIZED;
+    return 0;
+}
+
+int Hdf5InputPlugin::validate(const SimulationContext& /*ctx*/) {
+    state_ = PluginState::VALIDATED;
+    return 0;
+}
+
+int Hdf5InputPlugin::read(const std::string& /*path*/, SimulationContext& /*ctx*/) {
+    // Schema 1.0 ships write-first. Refusing outright is the honest answer: a
+    // partially populated SimulationContext would run and produce numbers,
+    // which is a far worse failure than not opening at all.
+    error_ = "HDF5 model read is not implemented in schema " +
+             std::string(kSchemaVersion) +
+             "; the format is currently an export target. Use the .inp or "
+             ".gpkg reader to load a model.";
+    state_ = PluginState::ERROR;
+    return 1;
+}
+
+int Hdf5InputPlugin::write(const std::string& path, const SimulationContext& ctx) {
+    error_.clear();
+    skipped_.clear();
+    std::vector warnings;
+    const int rc = write_model(path, ctx, &warnings);
+    if (rc != 0) {
+        error_ = warnings.empty() ? "HDF5 model write failed" : warnings.front();
+        state_ = PluginState::ERROR;
+        return rc;
+    }
+    // The writer reports every section it could not carry; surface them
+    // through the interface's own channel rather than dropping them.
+    skipped_ = std::move(warnings);
+    return 0;
+}
+
+int Hdf5InputPlugin::finalize(const SimulationContext& /*ctx*/) {
+    state_ = PluginState::FINALIZED;
+    return 0;
+}
+
+}  // namespace openswmm::h5io
diff --git a/src/engine/io/hdf5/Hdf5InputPlugin.hpp b/src/engine/io/hdf5/Hdf5InputPlugin.hpp
new file mode 100644
index 000000000..38e36ac11
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5InputPlugin.hpp
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5InputPlugin.hpp
+ * @brief IInputPlugin implementation for the columnar HDF5 model format.
+ *
+ * @details Mirrors GeoPackageInputPlugin: a thin lifecycle wrapper that
+ *          delegates to Hdf5ModelWriter / Hdf5ModelReader. Because the engine
+ *          dispatches `swmm_model_write_with_plugin` on a plugin id rather
+ *          than a file extension, registering this in
+ *          PluginFactory::register_builtin_infos() is all that is needed to
+ *          make
+ *
+ *          @code
+ *          swmm_model_write_with_plugin(e, "model.h5",
+ *              "org.hydrocouple.openswmm.plugins.hdf5");
+ *          @endcode
+ *
+ *          work with no other engine change.
+ *
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_HDF5_INPUT_PLUGIN_HPP
+#define OPENSWMM_HDF5_INPUT_PLUGIN_HPP
+
+#include 
+
+#include 
+#include 
+
+namespace openswmm::h5io {
+
+class Hdf5InputPlugin : public IInputPlugin {
+public:
+    Hdf5InputPlugin() = default;
+
+    PluginState state() const noexcept override { return state_; }
+
+    int initialize(const std::vector& init_args,
+                   const IPluginComponentInfo* info) override;
+
+    int validate(const SimulationContext& ctx) override;
+
+    /**
+     * @brief Read a model from an HDF5 file.
+     *
+     * @note Not implemented in schema 1.0 — the format ships write-first, as
+     *       an export target. Returns a non-zero code and sets
+     *       last_error_message() rather than half-populating a context, which
+     *       would be far worse than refusing.
+     */
+    int read(const std::string& path, SimulationContext& ctx) override;
+
+    /** @brief Write the model held by @p ctx to @p path. */
+    int write(const std::string& path, const SimulationContext& ctx) override;
+
+    /** @brief Sections the last write() could not carry. */
+    std::vector skipped_sections() const override { return skipped_; }
+
+    int finalize(const SimulationContext& ctx) override;
+
+    const char* last_error_message() const noexcept override { return error_.c_str(); }
+
+private:
+    PluginState              state_ = PluginState::UNLOADED;
+    std::string              error_;
+    std::vector skipped_;
+};
+
+}  // namespace openswmm::h5io
+
+#endif  // OPENSWMM_HDF5_INPUT_PLUGIN_HPP
diff --git a/src/engine/io/hdf5/Hdf5ModelWriter.cpp b/src/engine/io/hdf5/Hdf5ModelWriter.cpp
new file mode 100644
index 000000000..0e4a3b3c7
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5ModelWriter.cpp
@@ -0,0 +1,897 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5ModelWriter.cpp
+ * @brief Columnar HDF5 model serialisation. See STRATEGY.md.
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "Hdf5ModelWriter.hpp"
+#include "Hdf5Util.hpp"
+
+#include "core/SimulationContext.hpp"
+#include "core/UnitConversion.hpp"
+#include "data/StorageGeometry.hpp"   // storage_shape_keyword
+#include "input/PostParseResolver.hpp"
+
+#include 
+#include 
+#include 
+
+namespace openswmm::h5io {
+namespace {
+
+// ---------------------------------------------------------------------------
+// Shape keywords. Written as the LEGACY KEYWORD STRING, never an enum ordinal.
+//
+// Two enums in this codebase (LinkData::XsectShape and the kernel XSectShape)
+// disagree on ordering, and an `enum + 1` translation between them was once
+// the single largest parity defect in the project. A format that stores the
+// keyword cannot reproduce that class of error, and stays readable besides.
+// ---------------------------------------------------------------------------
+const char* shape_keyword(int s) {
+    static const char* n[] = {
+        "CIRCULAR","FILLED_CIRCULAR","RECT_CLOSED","RECT_OPEN",
+        "TRAPEZOIDAL","TRIANGULAR","PARABOLIC","POWER","MODBASKETHANDLE",
+        "EGG","HORSESHOE","GOTHIC","CATENARY","SEMIELLIPTICAL",
+        "BASKETHANDLE","SEMICIRCULAR","RECT_TRIANGULAR","RECT_ROUND",
+        "HORIZ_ELLIPSE","VERT_ELLIPSE","ARCH",
+        "IRREGULAR","CUSTOM","FORCE_MAIN","STREET","DUMMY"
+    };
+    return (s >= 0 && s <= 25) ? n[s] : "CIRCULAR";
+}
+
+/// Curve type as the legacy [CURVES] keyword. Same reasoning as the shape
+/// keywords: a string cannot be silently misread the way an ordinal can.
+const char* curve_type_keyword(TableType t) {
+    switch (t) {
+        case TableType::CURVE_DIVERSION: return "DIVERSION";
+        case TableType::CURVE_RATING:    return "RATING";
+        case TableType::CURVE_SHAPE:     return "SHAPE";
+        case TableType::CURVE_CONTROL:   return "CONTROL";
+        case TableType::CURVE_TIDAL:     return "TIDAL";
+        case TableType::CURVE_WEIR:      return "WEIR";
+        case TableType::CURVE_PUMP1:     return "PUMP1";
+        case TableType::CURVE_PUMP2:     return "PUMP2";
+        case TableType::CURVE_PUMP3:     return "PUMP3";
+        case TableType::CURVE_PUMP4:     return "PUMP4";
+        case TableType::CURVE_PUMP5:     return "PUMP5";
+        default:                         return "STORAGE";
+    }
+}
+
+const char* node_type_keyword(NodeType t) {
+    switch (t) {
+        case NodeType::OUTFALL: return "OUTFALL";
+        case NodeType::DIVIDER: return "DIVIDER";
+        case NodeType::STORAGE: return "STORAGE";
+        default:                return "JUNCTION";
+    }
+}
+
+const char* link_type_keyword(LinkType t) {
+    switch (t) {
+        case LinkType::PUMP:    return "PUMP";
+        case LinkType::ORIFICE: return "ORIFICE";
+        case LinkType::WEIR:    return "WEIR";
+        case LinkType::OUTLET:  return "OUTLET";
+        default:                return "CONDUIT";
+    }
+}
+
+/// Safe element access — a SoA array may legitimately be shorter than the
+/// object count when a model was built through the API rather than parsed.
+template 
+auto at(const V& v, std::size_t i) -> typename V::value_type {
+    return i < v.size() ? v[i] : typename V::value_type{};
+}
+
+/// Node / link name by index, or "" for an unresolved (-1) reference.
+std::string node_name(const SimulationContext& c, int idx) {
+    return (idx >= 0 && idx < c.n_nodes()) ? c.node_names.name_of(idx) : std::string();
+}
+std::string link_name(const SimulationContext& c, int idx) {
+    return (idx >= 0 && idx < c.n_links()) ? c.link_names.name_of(idx) : std::string();
+}
+
+/// Unit labels resolved against the file's unit system, so every column can
+/// say what it actually holds rather than "model units".
+struct UnitWords {
+    const char* length;
+    const char* area;
+    const char* flow;
+    const char* depth_rate;   // [LOSSES] seepage, infiltration rates
+};
+
+UnitWords unit_words(int unit_system) {
+    return unit_system == 0 ? UnitWords{"ft", "ac", "cfs", "in/hr"}
+                            : UnitWords{"m",  "ha", "cms", "mm/hr"};
+}
+
+const char* flow_units_keyword(int fu) {
+    static const char* n[] = {"CFS", "GPM", "MGD", "CMS", "LPS", "MLD"};
+    return (fu >= 0 && fu < 6) ? n[fu] : "CFS";
+}
+
+// ---------------------------------------------------------------------------
+// Sections
+// ---------------------------------------------------------------------------
+
+void write_root_attrs(hid_t file, const SimulationContext& ctx, int us) {
+    write_attr(file, "schema_version", std::string(kSchemaVersion));
+    write_attr(file, "format", std::string("openswmm-model-hdf5"));
+    write_attr(file, "flow_units",
+               std::string(flow_units_keyword(static_cast(ctx.options.flow_units))));
+    write_attr(file, "unit_system", std::string(us == 0 ? "US" : "SI"));
+    // Units are AUTHORED, not the engine's internal feet/cfs — the one thing a
+    // consumer most needs to know and the decision STRATEGY.md §4 turns on.
+    write_attr(file, "units_convention", std::string("authored"));
+
+    std::time_t now = std::time(nullptr);
+    char stamp[32] = {0};
+    std::strftime(stamp, sizeof(stamp), "%Y-%m-%dT%H:%M:%SZ", std::gmtime(&now));
+    write_attr(file, "created_utc", std::string(stamp));
+
+    std::string title;
+    for (const auto& line : ctx.title_notes) {
+        if (!title.empty()) title += "\n";
+        title += line;
+    }
+    write_attr(file, "title", title);
+}
+
+void write_nodes(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_nodes();
+    std::vector name(static_cast(n)), type, tag, comment;
+    std::vector invert, full, init, sur, ponded;
+    type.reserve(name.size()); tag.reserve(name.size()); comment.reserve(name.size());
+    invert.reserve(name.size()); full.reserve(name.size()); init.reserve(name.size());
+    sur.reserve(name.size()); ponded.reserve(name.size());
+
+    for (int j = 0; j < n; ++j) {
+        const auto i = static_cast(j);
+        name[i] = ctx.node_names.name_of(j);
+        type.push_back(node_type_keyword(at(ctx.nodes.type, i)));
+        tag.push_back(at(ctx.nodes.tags, i));
+        comment.push_back(at(ctx.nodes.comments, i));
+        invert.push_back(at(ctx.nodes.invert_elev, i));
+        full.push_back(at(ctx.nodes.full_depth, i));
+        init.push_back(at(ctx.nodes.init_depth, i));
+        sur.push_back(at(ctx.nodes.sur_depth, i));
+        ponded.push_back(at(ctx.nodes.ponded_area, i));
+    }
+
+    Handle g = make_group(file, "nodes");
+    if (!g) return;
+    write_column(g.get(), "name", name, "node id");
+    write_column(g.get(), "type", type, "JUNCTION | OUTFALL | DIVIDER | STORAGE");
+    write_column(g.get(), "invert_elev", invert, u.length, "invert elevation");
+    write_column(g.get(), "full_depth", full, u.length, "depth from invert to ground");
+    write_column(g.get(), "init_depth", init, u.length, "initial water depth");
+    write_column(g.get(), "sur_depth", sur, u.length, "surcharge depth above ground");
+    write_column(g.get(), "ponded_area", ponded,
+                 std::string(u.length) + "^2", "ponded surface area when flooded");
+    write_column(g.get(), "tag", tag, "user tag");
+    write_column(g.get(), "comment", comment, "authored comment");
+}
+
+void write_node_subtypes(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_nodes();
+
+    // --- outfalls -----------------------------------------------------------
+    {
+        std::vector name, bc, stage_curve;
+        std::vector stage;
+        std::vector gated;
+        std::vector route_to;
+        for (int j = 0; j < n; ++j) {
+            const auto i = static_cast(j);
+            if (at(ctx.nodes.type, i) != NodeType::OUTFALL) continue;
+            const int r = ctx.node_subtypes.outfall_row(j);
+            const auto& O = ctx.node_subtypes.outfalls;
+            name.push_back(ctx.node_names.name_of(j));
+            const auto bt = (r >= 0) ? at(O.bc_type, static_cast(r))
+                                     : OutfallType::FREE;
+            switch (bt) {
+                case OutfallType::NORMAL:     bc.push_back("NORMAL"); break;
+                case OutfallType::FIXED:      bc.push_back("FIXED"); break;
+                case OutfallType::TIDAL:      bc.push_back("TIDAL"); break;
+                case OutfallType::TIMESERIES: bc.push_back("TIMESERIES"); break;
+                default:                      bc.push_back("FREE"); break;
+            }
+            const double p = (r >= 0) ? at(O.param, static_cast(r)) : 0.0;
+            // FIXED parks a stage in `param`; TIDAL/TIMESERIES park a table
+            // index there instead, which is written as the table's NAME.
+            if (bt == OutfallType::FIXED) { stage.push_back(p); stage_curve.push_back(""); }
+            else {
+                stage.push_back(0.0);
+                const int t = static_cast(p);
+                stage_curve.push_back((bt == OutfallType::TIDAL || bt == OutfallType::TIMESERIES)
+                                      && t >= 0 && t < ctx.n_tables()
+                                      ? ctx.tables[t].id : std::string());
+            }
+            gated.push_back((r >= 0) ? at(O.has_flap_gate, static_cast(r)) : 0);
+            const int rt = (r >= 0) ? at(O.route_to, static_cast(r)) : -1;
+            route_to.push_back(rt >= 0 && rt < ctx.n_subcatches()
+                               ? ctx.subcatch_names.name_of(rt) : std::string());
+        }
+        Handle g = make_group(file, "nodes/outfalls");
+        if (g) {
+            write_column(g.get(), "name", name, "node id");
+            write_column(g.get(), "bc_type", bc, "FREE | NORMAL | FIXED | TIDAL | TIMESERIES");
+            write_column(g.get(), "stage", stage, u.length, "fixed stage elevation");
+            write_column(g.get(), "stage_series", stage_curve, "tidal curve or stage time series");
+            write_column(g.get(), "has_flap_gate", gated, "boolean", "flap gate present");
+            write_column(g.get(), "route_to", route_to, "subcatchment receiving the outflow");
+        }
+    }
+
+    // --- dividers -----------------------------------------------------------
+    {
+        std::vector name, div_link, method, curve;
+        std::vector cutoff, qmin, dh_max, cd;
+        for (int j = 0; j < n; ++j) {
+            const auto i = static_cast(j);
+            if (at(ctx.nodes.type, i) != NodeType::DIVIDER) continue;
+            const int r = ctx.node_subtypes.divider_row(j);
+            const auto& D = ctx.node_subtypes.dividers;
+            const auto ur = static_cast(r);
+            name.push_back(ctx.node_names.name_of(j));
+            const int dl = (r >= 0) ? at(D.link, ur) : -1;
+            std::string dln = link_name(ctx, dl);
+            if (dln.empty() && r >= 0) dln = at(D.link_name, ur);
+            div_link.push_back(dln);
+            const auto m = (r >= 0) ? at(D.method, ur) : DividerType::CUTOFF;
+            switch (m) {
+                case DividerType::OVERFLOW_DIV: method.push_back("OVERFLOW"); break;
+                case DividerType::TABULAR:      method.push_back("TABULAR"); break;
+                case DividerType::WEIR:         method.push_back("WEIR"); break;
+                default:                        method.push_back("CUTOFF"); break;
+            }
+            const int ci = (r >= 0) ? at(D.curve, ur) : -1;
+            std::string cn = (ci >= 0 && ci < ctx.n_tables()) ? ctx.tables[ci].id : std::string();
+            if (cn.empty() && r >= 0) cn = at(D.curve_name, ur);
+            curve.push_back(cn);
+            cutoff.push_back((r >= 0) ? at(D.cutoff, ur) : 0.0);
+            qmin.push_back((r >= 0) ? at(D.cutoff, ur) : 0.0);
+            dh_max.push_back((r >= 0) ? at(D.max_depth, ur) : 0.0);
+            cd.push_back((r >= 0) ? at(D.cd, ur) : 0.0);
+        }
+        Handle g = make_group(file, "nodes/dividers");
+        if (g) {
+            write_column(g.get(), "name", name, "node id");
+            write_column(g.get(), "diverted_link", div_link, "link receiving the diverted flow");
+            write_column(g.get(), "method", method, "CUTOFF | OVERFLOW | TABULAR | WEIR");
+            write_column(g.get(), "curve", curve, "diversion curve (TABULAR)");
+            write_column(g.get(), "cutoff_flow", cutoff, u.flow, "CUTOFF/WEIR minimum flow");
+            write_column(g.get(), "weir_dh_max", dh_max, u.length, "WEIR head range");
+            write_column(g.get(), "weir_cd", cd, "dimensionless", "WEIR discharge coefficient");
+        }
+    }
+
+    // --- storage ------------------------------------------------------------
+    {
+        std::vector name, shape, curve;
+        std::vector a0, a1, a2, p1, p2, p3, fevap, ksat, suction, imd;
+        for (int j = 0; j < n; ++j) {
+            const auto i = static_cast(j);
+            if (at(ctx.nodes.type, i) != NodeType::STORAGE) continue;
+            const int r = ctx.node_subtypes.storage_row(j);
+            const auto& S = ctx.node_subtypes.storages;
+            const auto ur = static_cast(r);
+            name.push_back(ctx.node_names.name_of(j));
+            const int ci = (r >= 0) ? at(S.curve, ur) : -1;
+            shape.push_back(ci >= 0 ? "TABULAR"
+                                    : storage_shape_keyword((r >= 0) ? at(S.shape, ur)
+                                                                     : StorageShape::FUNCTIONAL));
+            curve.push_back((ci >= 0 && ci < ctx.n_tables()) ? ctx.tables[ci].id : std::string());
+            // [STORAGE] FUNCTIONAL columns are A1 A2 A0 in that order, so the
+            // store's a/b/c are the COEFFICIENT, the EXPONENT and the
+            // CONSTANT — not a0/a1/a2 as the letters suggest.
+            a1.push_back((r >= 0) ? at(S.a, ur) : 0.0);   // A1, coefficient
+            a2.push_back((r >= 0) ? at(S.b, ur) : 0.0);   // A2, exponent
+            a0.push_back((r >= 0) ? at(S.c, ur) : 0.0);   // A0, constant
+            p1.push_back((r >= 0) ? at(S.p1, ur) : 0.0);
+            p2.push_back((r >= 0) ? at(S.p2, ur) : 0.0);
+            p3.push_back((r >= 0) ? at(S.p3, ur) : 0.0);
+            fevap.push_back((r >= 0) ? at(S.evap_frac, ur) : 0.0);
+            ksat.push_back((r >= 0) ? at(S.exfil_ksat, ur) : 0.0);
+            suction.push_back((r >= 0) ? at(S.exfil_suction, ur) : 0.0);
+            imd.push_back((r >= 0) ? at(S.exfil_imd, ur) : 0.0);
+        }
+        Handle g = make_group(file, "nodes/storage");
+        if (g) {
+            write_column(g.get(), "name", name, "node id");
+            write_column(g.get(), "shape", shape, "TABULAR | FUNCTIONAL | CYLINDRICAL | ...");
+            write_column(g.get(), "curve", curve, "storage curve (TABULAR)");
+            // FUNCTIONAL A(d) = a0 + a1*d^a2. These stay in USER units
+            // end-to-end by design (legacy converts per call in node.c), so
+            // they are already authored here.
+            write_column(g.get(), "a1", a1, "model",
+                         "FUNCTIONAL coefficient A1 in A(d) = A0 + A1*d^A2");
+            write_column(g.get(), "a2", a2, "dimensionless", "FUNCTIONAL exponent A2");
+            write_column(g.get(), "a0", a0, "model", "FUNCTIONAL constant A0");
+            write_column(g.get(), "p1", p1, u.length, "geometric shape parameter 1 (L)");
+            write_column(g.get(), "p2", p2, u.length, "geometric shape parameter 2 (W)");
+            write_column(g.get(), "p3", p3, u.length, "geometric shape parameter 3 (Z/H)");
+            write_column(g.get(), "evap_frac", fevap, "fraction", "evaporation factor");
+            write_column(g.get(), "exfil_suction", suction, u.length, "exfiltration suction head");
+            write_column(g.get(), "exfil_ksat", ksat, u.depth_rate, "exfiltration conductivity");
+            write_column(g.get(), "exfil_imd", imd, "fraction", "initial moisture deficit");
+        }
+    }
+}
+
+void write_links(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_links();
+    std::vector name, type, n1, n2, tag, comment;
+    std::vector off1, off2, q0, qlim;
+    std::vector flap;
+
+    for (int j = 0; j < n; ++j) {
+        const auto i = static_cast(j);
+        name.push_back(ctx.link_names.name_of(j));
+        type.push_back(link_type_keyword(at(ctx.links.type, i)));
+        n1.push_back(node_name(ctx, at(ctx.links.node1, i)));
+        n2.push_back(node_name(ctx, at(ctx.links.node2, i)));
+        off1.push_back(at(ctx.links.offset1, i));
+        off2.push_back(at(ctx.links.offset2, i));
+        q0.push_back(at(ctx.links.q0, i));
+        qlim.push_back(at(ctx.links.q_limit, i));
+        flap.push_back(at(ctx.links.has_flap_gate, i));
+        tag.push_back(at(ctx.links.tags, i));
+        comment.push_back(at(ctx.links.comments, i));
+    }
+
+    Handle g = make_group(file, "links");
+    if (!g) return;
+    write_column(g.get(), "name", name, "link id");
+    write_column(g.get(), "type", type, "CONDUIT | PUMP | ORIFICE | WEIR | OUTLET");
+    write_column(g.get(), "node1", n1, "upstream node id");
+    write_column(g.get(), "node2", n2, "downstream node id");
+    write_column(g.get(), "offset1", off1, u.length, "upstream offset (depth convention)");
+    write_column(g.get(), "offset2", off2, u.length, "downstream offset (depth convention)");
+    write_column(g.get(), "q0", q0, u.flow, "initial flow");
+    write_column(g.get(), "q_limit", qlim, u.flow, "maximum flow, 0 = no limit");
+    write_column(g.get(), "has_flap_gate", flap, "boolean", "flap gate present");
+    write_column(g.get(), "tag", tag, "user tag");
+    write_column(g.get(), "comment", comment, "authored comment");
+}
+
+void write_xsections(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_links();
+    std::vector link, shape, ref;
+    std::vector g1, g2, g3, g4;
+    std::vector barrels, culvert;
+
+    for (int j = 0; j < n; ++j) {
+        const auto i = static_cast(j);
+        const auto lt = at(ctx.links.type, i);
+        // Cross sections belong to conduits, orifices and weirs. A pump or
+        // outlet has none, and emitting a default one makes legacy reject the
+        // deck (ERROR 211).
+        if (lt == LinkType::PUMP || lt == LinkType::OUTLET) continue;
+
+        const auto sh = at(ctx.links.xsect_shape, i);
+        link.push_back(ctx.link_names.name_of(j));
+        shape.push_back(shape_keyword(static_cast(sh)));
+
+        // IRREGULAR names a transect, STREET names a street, CUSTOM names a
+        // shape curve — a NAME, not a dimension. Keeping it in its own column
+        // removes the .inp's overloading of the Geom1/Geom2 slots entirely.
+        std::string r;
+        if (sh == XsectShape::IRREGULAR || sh == XsectShape::STREET_XSECT ||
+            sh == XsectShape::CUSTOM) {
+            r = at(ctx.links.pump_curve_name, i);
+            if (r.empty()) {
+                const int xc = at(ctx.links.xsect_curve, i);
+                if (sh == XsectShape::IRREGULAR && xc >= 0 && xc < ctx.transects.count())
+                    r = ctx.transects.names[static_cast(xc)];
+            }
+        }
+        ref.push_back(r);
+
+        // RAW authored geoms — never the resolver's derived y_full/w_max.
+        // Their meaning is shape-dependent (a length, a dimensionless side
+        // slope, a C-factor, or a lookup-table index for the ellipse/arch
+        // standard sizes), and only the raw values reconstruct the section.
+        g1.push_back(at(ctx.links.xsect_geom1, i));
+        g2.push_back(at(ctx.links.xsect_geom2, i));
+        g3.push_back(at(ctx.links.xsect_geom3, i));
+        g4.push_back(at(ctx.links.xsect_geom4, i));
+
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        barrels.push_back(cr >= 0
+            ? at(ctx.link_subtypes.conduits.barrels, static_cast(cr)) : 1);
+        culvert.push_back(cr >= 0
+            ? at(ctx.link_subtypes.conduits.culvert_code, static_cast(cr)) : 0);
+    }
+
+    Handle g = make_group(file, "links/xsections");
+    if (!g) return;
+    write_column(g.get(), "link", link, "link id");
+    write_column(g.get(), "shape", shape, "legacy shape keyword");
+    write_column(g.get(), "reference", ref,
+                 "transect / street / shape-curve name for IRREGULAR, STREET, CUSTOM");
+    const char* geom_note =
+        "raw authored Geom value; meaning is shape-dependent — see STRATEGY.md and "
+        "the cross-section matrix in plans/FILE_IO_PARITY_AUDIT_2026-09-22.md";
+    write_column(g.get(), "geom1", g1, "shape-dependent", geom_note);
+    write_column(g.get(), "geom2", g2, "shape-dependent", geom_note);
+    write_column(g.get(), "geom3", g3, "shape-dependent", geom_note);
+    write_column(g.get(), "geom4", g4, "shape-dependent", geom_note);
+    write_column(g.get(), "barrels", barrels, "count", "identical parallel barrels");
+    write_column(g.get(), "culvert_code", culvert, "code",
+                 "FHWA culvert inlet-control code, 0 = not a culvert");
+    write_attr(g.get(), "note",
+               std::string("For HORIZ_ELLIPSE, VERT_ELLIPSE and ARCH a nonzero geom3 "
+                           "(or geom1 with geom2 == 0) is a STANDARD SIZE CODE, not a "
+                           "dimension. Preserved verbatim."));
+    (void)u;
+}
+
+void write_link_subtypes(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_links();
+
+    // --- conduits -----------------------------------------------------------
+    {
+        std::vector name;
+        std::vector length, rough, k_in, k_out, k_avg, seep;
+        for (int j = 0; j < n; ++j) {
+            if (at(ctx.links.type, static_cast(j)) != LinkType::CONDUIT) continue;
+            const int r = ctx.link_subtypes.conduit_row(j);
+            const auto& C = ctx.link_subtypes.conduits;
+            const auto ur = static_cast(r);
+            name.push_back(ctx.link_names.name_of(j));
+            length.push_back((r >= 0) ? at(C.length, ur) : 0.0);
+            rough.push_back((r >= 0) ? at(C.roughness, ur) : 0.01);
+            k_in.push_back((r >= 0) ? at(C.loss_inlet, ur) : 0.0);
+            k_out.push_back((r >= 0) ? at(C.loss_outlet, ur) : 0.0);
+            k_avg.push_back((r >= 0) ? at(C.loss_avg, ur) : 0.0);
+            seep.push_back((r >= 0) ? at(C.seep_rate, ur) : 0.0);
+        }
+        Handle g = make_group(file, "links/conduits");
+        if (g) {
+            write_column(g.get(), "name", name, "link id");
+            write_column(g.get(), "length", length, u.length, "conduit length");
+            write_column(g.get(), "roughness", rough, "dimensionless", "Manning's n");
+            write_column(g.get(), "loss_inlet", k_in, "dimensionless", "entry loss coefficient");
+            write_column(g.get(), "loss_outlet", k_out, "dimensionless", "exit loss coefficient");
+            write_column(g.get(), "loss_avg", k_avg, "dimensionless", "average loss coefficient");
+            // Seepage arrives and leaves in in/hr (mm/hr) even though the
+            // solver consumes ft/s — the conversion that a LENGTH-only writer
+            // gate used to skip on US decks.
+            write_column(g.get(), "seep_rate", seep, u.depth_rate, "seepage loss rate");
+        }
+    }
+
+    // --- pumps --------------------------------------------------------------
+    {
+        std::vector name, curve, status;
+        std::vector startup, shutoff;
+        for (int j = 0; j < n; ++j) {
+            if (at(ctx.links.type, static_cast(j)) != LinkType::PUMP) continue;
+            const int r = ctx.link_subtypes.pump_row(j);
+            const auto& P = ctx.link_subtypes.pumps;
+            const auto ur = static_cast(r);
+            name.push_back(ctx.link_names.name_of(j));
+            curve.push_back(at(ctx.links.pump_curve_name, static_cast(j)));
+            status.push_back((r >= 0 && at(P.init_state, ur) != 0) ? "ON" : "OFF");
+            startup.push_back((r >= 0) ? at(P.startup, ur) : 0.0);
+            shutoff.push_back((r >= 0) ? at(P.shutoff, ur) : 0.0);
+        }
+        Handle g = make_group(file, "links/pumps");
+        if (g) {
+            write_column(g.get(), "name", name, "link id");
+            write_column(g.get(), "curve", curve, "pump curve name, '*' for an ideal pump");
+            write_column(g.get(), "init_status", status, "ON | OFF");
+            write_column(g.get(), "startup_depth", startup, u.length, "wet-well start depth");
+            write_column(g.get(), "shutoff_depth", shutoff, u.length, "wet-well stop depth");
+        }
+    }
+
+    // --- orifices -----------------------------------------------------------
+    {
+        std::vector name, orient;
+        std::vector cd, crest, orate;
+        for (int j = 0; j < n; ++j) {
+            if (at(ctx.links.type, static_cast(j)) != LinkType::ORIFICE) continue;
+            const int r = ctx.link_subtypes.orifice_row(j);
+            const auto& O = ctx.link_subtypes.orifices;
+            const auto ur = static_cast(r);
+            name.push_back(ctx.link_names.name_of(j));
+            orient.push_back((r >= 0 && at(O.orifice_type, ur) != 0.0) ? "SIDE" : "BOTTOM");
+            cd.push_back((r >= 0) ? at(O.cd, ur) : 0.0);
+            crest.push_back(at(ctx.links.offset1, static_cast(j)));
+            orate.push_back((r >= 0) ? at(O.orate, ur) : 0.0);
+        }
+        Handle g = make_group(file, "links/orifices");
+        if (g) {
+            write_column(g.get(), "name", name, "link id");
+            write_column(g.get(), "orientation", orient, "SIDE | BOTTOM");
+            write_column(g.get(), "crest_height", crest, u.length, "offset above the node invert");
+            write_column(g.get(), "discharge_coeff", cd, "dimensionless", "Cd");
+            write_column(g.get(), "open_close_time", orate, "hours", "time to open or close fully");
+        }
+    }
+
+    // --- weirs --------------------------------------------------------------
+    {
+        std::vector name, wtype, cd_curve;
+        std::vector crest, cd, cd2, end_con, road_width;
+        std::vector surcharge;
+        for (int j = 0; j < n; ++j) {
+            if (at(ctx.links.type, static_cast(j)) != LinkType::WEIR) continue;
+            const int r = ctx.link_subtypes.weir_row(j);
+            const auto& W = ctx.link_subtypes.weirs;
+            const auto ur = static_cast(r);
+            static const char* kinds[] = {"TRANSVERSE","SIDEFLOW","V-NOTCH","TRAPEZOIDAL","ROADWAY"};
+            const int wt = (r >= 0) ? at(W.weir_type, ur) : 0;
+            name.push_back(ctx.link_names.name_of(j));
+            wtype.push_back((wt >= 0 && wt < 5) ? kinds[wt] : "TRANSVERSE");
+            crest.push_back((r >= 0) ? at(W.crest_height, ur) : 0.0);
+            cd.push_back((r >= 0) ? at(W.cd, ur) : 0.0);
+            cd2.push_back((r >= 0) ? at(W.cd2, ur) : 0.0);
+            end_con.push_back((r >= 0) ? at(W.end_contractions, ur) : 0.0);
+            road_width.push_back((r >= 0) ? at(W.road_width, ur) : 0.0);
+            surcharge.push_back((r >= 0) ? at(W.can_surcharge, ur) : 1);
+            cd_curve.push_back("");
+        }
+        Handle g = make_group(file, "links/weirs");
+        if (g) {
+            write_column(g.get(), "name", name, "link id");
+            write_column(g.get(), "weir_type", wtype,
+                         "TRANSVERSE | SIDEFLOW | V-NOTCH | TRAPEZOIDAL | ROADWAY");
+            write_column(g.get(), "crest_height", crest, u.length, "crest above the node invert");
+            write_column(g.get(), "discharge_coeff", cd, "dimensionless", "Cd");
+            write_column(g.get(), "discharge_coeff2", cd2, "dimensionless",
+                         "second Cd (TRAPEZOIDAL sides)");
+            write_column(g.get(), "end_contractions", end_con, "count", "end contractions");
+            write_column(g.get(), "road_width", road_width, u.length, "ROADWAY width");
+            write_column(g.get(), "can_surcharge", surcharge, "boolean", "may surcharge");
+        }
+    }
+
+    // --- outlets ------------------------------------------------------------
+    {
+        std::vector name, rating, curve;
+        std::vector crest, coeff, expon;
+        for (int j = 0; j < n; ++j) {
+            if (at(ctx.links.type, static_cast(j)) != LinkType::OUTLET) continue;
+            const int r = ctx.link_subtypes.outlet_row(j);
+            const auto& O = ctx.link_subtypes.outlets;
+            const auto ur = static_cast(r);
+            static const char* kinds[] = {"FUNCTIONAL/HEAD","FUNCTIONAL/DEPTH",
+                                          "TABULAR/HEAD","TABULAR/DEPTH"};
+            const int ot = (r >= 0) ? at(O.outlet_type, ur) : 0;
+            name.push_back(ctx.link_names.name_of(j));
+            rating.push_back((ot >= 0 && ot < 4) ? kinds[ot] : kinds[0]);
+            curve.push_back(at(ctx.links.pump_curve_name, static_cast(j)));
+            crest.push_back((r >= 0) ? at(O.crest_height, ur)
+                                     : at(ctx.links.offset1, static_cast(j)));
+            coeff.push_back((r >= 0) ? at(O.coeff, ur) : 0.0);
+            expon.push_back((r >= 0) ? at(O.expon, ur) : 0.0);
+        }
+        Handle g = make_group(file, "links/outlets");
+        if (g) {
+            write_column(g.get(), "name", name, "link id");
+            write_column(g.get(), "rating_type", rating,
+                         "FUNCTIONAL|TABULAR crossed with HEAD|DEPTH");
+            write_column(g.get(), "crest_height", crest, u.length, "offset above the node invert");
+            write_column(g.get(), "rating_curve", curve, "rating curve name (TABULAR)");
+            write_column(g.get(), "coefficient", coeff, "model", "FUNCTIONAL coefficient");
+            write_column(g.get(), "exponent", expon, "dimensionless", "FUNCTIONAL exponent");
+        }
+    }
+}
+
+void write_subcatchments(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    const int n = ctx.n_subcatches();
+    std::vector name, gage, outlet, route_to, tag, comment;
+    std::vector area, pct_imp, width, slope, curb;
+    std::vector n_imp, n_perv, s_imp, s_perv, pct_zero, pct_routed;
+
+    for (int j = 0; j < n; ++j) {
+        const auto i = static_cast(j);
+        name.push_back(ctx.subcatch_names.name_of(j));
+        const int gi = at(ctx.subcatches.gage, i);
+        gage.push_back(gi >= 0 && gi < ctx.gage_names.size()
+                       ? ctx.gage_names.name_of(gi) : std::string());
+        // An outlet is either a node or another subcatchment.
+        const int on = at(ctx.subcatches.outlet_node, i);
+        const int os = at(ctx.subcatches.outlet_subcatch, i);
+        outlet.push_back(on >= 0 ? node_name(ctx, on)
+                                 : (os >= 0 && os < n ? ctx.subcatch_names.name_of(os)
+                                                      : std::string()));
+        area.push_back(at(ctx.subcatches.area, i));
+        pct_imp.push_back(at(ctx.subcatches.frac_imperv, i) * 100.0);
+        width.push_back(at(ctx.subcatches.width, i));
+        slope.push_back(at(ctx.subcatches.slope, i) * 100.0);
+        curb.push_back(at(ctx.subcatches.curb_length, i));
+        n_imp.push_back(at(ctx.subcatches.n_imperv, i));
+        n_perv.push_back(at(ctx.subcatches.n_perv, i));
+        s_imp.push_back(at(ctx.subcatches.ds_imperv, i));
+        s_perv.push_back(at(ctx.subcatches.ds_perv, i));
+        pct_zero.push_back(at(ctx.subcatches.frac_imperv_no_store, i) * 100.0);
+        static const char* rt[] = {"OUTLET", "IMPERVIOUS", "PERVIOUS"};
+        const int m = at(ctx.subcatches.subarea_routing, i);
+        route_to.push_back((m >= 0 && m < 3) ? rt[m] : rt[0]);
+        pct_routed.push_back(at(ctx.subcatches.pct_routed, i) * 100.0);
+        tag.push_back(at(ctx.subcatches.tags, i));
+        comment.push_back(at(ctx.subcatches.comments, i));
+    }
+
+    Handle g = make_group(file, "subcatchments");
+    if (!g) return;
+    write_column(g.get(), "name", name, "subcatchment id");
+    write_column(g.get(), "rain_gage", gage, "rain gage id");
+    write_column(g.get(), "outlet", outlet, "receiving node or subcatchment id");
+    write_column(g.get(), "area", area, u.area, "surface area");
+    write_column(g.get(), "pct_imperv", pct_imp, "percent", "impervious fraction");
+    write_column(g.get(), "width", width, u.length, "characteristic overland-flow width");
+    write_column(g.get(), "slope", slope, "percent", "average surface slope");
+    write_column(g.get(), "curb_length", curb, u.length, "curb length for pollutant buildup");
+    write_column(g.get(), "n_imperv", n_imp, "dimensionless", "Manning's n, impervious");
+    write_column(g.get(), "n_perv", n_perv, "dimensionless", "Manning's n, pervious");
+    write_column(g.get(), "s_imperv", s_imp, "depth", "depression storage, impervious");
+    write_column(g.get(), "s_perv", s_perv, "depth", "depression storage, pervious");
+    write_column(g.get(), "pct_zero_imperv", pct_zero, "percent",
+                 "impervious area with no depression storage");
+    write_column(g.get(), "route_to", route_to, "OUTLET | IMPERVIOUS | PERVIOUS");
+    write_column(g.get(), "pct_routed", pct_routed, "percent", "runoff routed between subareas");
+    write_column(g.get(), "tag", tag, "user tag");
+    write_column(g.get(), "comment", comment, "authored comment");
+}
+
+/// Curves, time series and patterns share the ragged-table problem: each
+/// object owns a variable number of ordinates. The CSR idiom keeps everything
+/// contiguous — one flat value array plus an offsets array of length n+1 —
+/// which needs no variable-length HDF5 types and reads cleanly from h5py.
+void write_tables(hid_t file, const SimulationContext& ctx) {
+    std::vector cname, ctype;
+    std::vector coffs{0};
+    std::vector cx, cy;
+
+    std::vector tname;
+    std::vector toffs{0};
+    std::vector tx, ty;
+
+    for (int t = 0; t < ctx.n_tables(); ++t) {
+        const auto& tb = ctx.tables[t];
+        const bool is_series = (tb.type == TableType::TIMESERIES);
+        auto& nm  = is_series ? tname : cname;
+        auto& off = is_series ? toffs : coffs;
+        auto& xs  = is_series ? tx : cx;
+        auto& ys  = is_series ? ty : cy;
+        nm.push_back(tb.id);
+        if (!is_series) ctype.push_back(curve_type_keyword(tb.type));
+        xs.insert(xs.end(), tb.x.begin(), tb.x.end());
+        ys.insert(ys.end(), tb.y.begin(), tb.y.end());
+        off.push_back(static_cast(xs.size()));
+    }
+
+    {
+        Handle g = make_group(file, "tables/curves");
+        if (g) {
+            write_column(g.get(), "name", cname, "curve id");
+            write_column(g.get(), "type", ctype, "STORAGE | RATING | PUMP1..5 | SHAPE | ...");
+            write_column(g.get(), "offsets", coffs, "index",
+                         "CSR row starts into x/y; row i spans [offsets[i], offsets[i+1])");
+            write_column(g.get(), "x", cx, "model", "abscissa values, all curves concatenated");
+            write_column(g.get(), "y", cy, "model", "ordinate values, all curves concatenated");
+        }
+    }
+    {
+        Handle g = make_group(file, "tables/timeseries");
+        if (g) {
+            write_column(g.get(), "name", tname, "time series id");
+            write_column(g.get(), "offsets", toffs, "index", "CSR row starts into time/value");
+            // Times are stored as the engine holds them: absolute OADate when
+            // the series was authored with dates, else elapsed hours. The
+            // `absolute` flag says which, so a relative series is never
+            // silently anchored to a start date it did not have.
+            write_column(g.get(), "time", tx, "OADate or elapsed hours", "abscissa");
+            write_column(g.get(), "value", ty, "model", "ordinate");
+        }
+    }
+}
+
+void write_geometry(hid_t file, const SimulationContext& ctx, const UnitWords& u) {
+    // --- node coordinates ---------------------------------------------------
+    {
+        std::vector name;
+        std::vector x, y;
+        for (int j = 0; j < ctx.n_nodes(); ++j) {
+            const auto i = static_cast(j);
+            if (i >= ctx.spatial.node_x.size()) break;
+            name.push_back(ctx.node_names.name_of(j));
+            x.push_back(ctx.spatial.node_x[i]);
+            y.push_back(ctx.spatial.node_y[i]);
+        }
+        Handle g = make_group(file, "geometry/coordinates");
+        if (g) {
+            write_column(g.get(), "node", name, "node id");
+            write_column(g.get(), "x", x, "map units", "easting");
+            write_column(g.get(), "y", y, "map units", "northing");
+        }
+    }
+    // --- link vertices (CSR) ------------------------------------------------
+    {
+        std::vector name;
+        std::vector offs{0};
+        std::vector x, y;
+        for (int j = 0; j < ctx.n_links(); ++j) {
+            const auto i = static_cast(j);
+            if (i >= ctx.spatial.link_vertices_x.size()) break;
+            name.push_back(ctx.link_names.name_of(j));
+            const auto& vx = ctx.spatial.link_vertices_x[i];
+            const auto& vy = ctx.spatial.link_vertices_y[i];
+            x.insert(x.end(), vx.begin(), vx.end());
+            y.insert(y.end(), vy.begin(), vy.end());
+            offs.push_back(static_cast(x.size()));
+        }
+        Handle g = make_group(file, "geometry/vertices");
+        if (g) {
+            write_column(g.get(), "link", name, "link id");
+            write_column(g.get(), "offsets", offs, "index", "CSR row starts into x/y");
+            write_column(g.get(), "x", x, "map units", "easting");
+            write_column(g.get(), "y", y, "map units", "northing");
+        }
+    }
+    (void)u;
+}
+
+void write_transects_and_streets(hid_t file, const SimulationContext& ctx,
+                                 const UnitWords& u) {
+    // --- transects (CSR over the station/elevation pairs) -------------------
+    {
+        const int n = ctx.transects.count();
+        std::vector name;
+        std::vector nl, nr, nc, xl, xr, lf, xf, yf, station, elevation;
+        std::vector offs{0};
+        for (int t = 0; t < n; ++t) {
+            const auto i = static_cast(t);
+            name.push_back(ctx.transects.names[i]);
+            nl.push_back(ctx.transects.n_left[i]);
+            nr.push_back(ctx.transects.n_right[i]);
+            nc.push_back(ctx.transects.n_channel[i]);
+            xl.push_back(ctx.transects.x_left_bank[i]);
+            xr.push_back(ctx.transects.x_right_bank[i]);
+            lf.push_back(ctx.transects.length_factor[i]);
+            xf.push_back(ctx.transects.x_factor[i]);
+            yf.push_back(ctx.transects.y_factor[i]);
+            station.insert(station.end(), ctx.transects.stations[i].begin(),
+                           ctx.transects.stations[i].end());
+            elevation.insert(elevation.end(), ctx.transects.elevations[i].begin(),
+                             ctx.transects.elevations[i].end());
+            offs.push_back(static_cast(station.size()));
+        }
+        Handle g = make_group(file, "geometry/transects");
+        if (g) {
+            write_column(g.get(), "name", name, "transect id");
+            write_column(g.get(), "n_left", nl, "dimensionless", "Manning's n, left overbank");
+            write_column(g.get(), "n_right", nr, "dimensionless", "Manning's n, right overbank");
+            write_column(g.get(), "n_channel", nc, "dimensionless", "Manning's n, main channel");
+            write_column(g.get(), "x_left_bank", xl, u.length, "left bank station");
+            write_column(g.get(), "x_right_bank", xr, u.length, "right bank station");
+            write_column(g.get(), "length_factor", lf, "dimensionless", "meander modifier");
+            write_column(g.get(), "x_factor", xf, "dimensionless", "station multiplier");
+            write_column(g.get(), "y_factor", yf, u.length, "elevation offset");
+            write_column(g.get(), "offsets", offs, "index", "CSR row starts into station/elevation");
+            write_column(g.get(), "station", station, u.length, "horizontal station");
+            write_column(g.get(), "elevation", elevation, u.length, "ground elevation");
+        }
+    }
+    // --- streets ------------------------------------------------------------
+    {
+        const int n = ctx.streets.count();
+        std::vector name;
+        std::vector tcrown, hcurb, sx, nroad, a, wdep, tback, sback, nback;
+        std::vector sides;
+        for (int j = 0; j < n; ++j) {
+            const auto i = static_cast(j);
+            name.push_back(ctx.streets.names[i]);
+            tcrown.push_back(ctx.streets.t_crown[i]);
+            hcurb.push_back(ctx.streets.h_curb[i]);
+            sx.push_back(ctx.streets.sx[i]);
+            nroad.push_back(ctx.streets.n_road[i]);
+            a.push_back(ctx.streets.gutter_depres[i]);
+            wdep.push_back(ctx.streets.gutter_width[i]);
+            sides.push_back(ctx.streets.sides[i]);
+            tback.push_back(ctx.streets.back_width[i]);
+            sback.push_back(ctx.streets.back_slope[i]);
+            nback.push_back(ctx.streets.back_n[i]);
+        }
+        Handle g = make_group(file, "geometry/streets");
+        if (g) {
+            write_column(g.get(), "name", name, "street id");
+            write_column(g.get(), "crown_width", tcrown, u.length, "half-width to the crown");
+            write_column(g.get(), "curb_height", hcurb, u.length, "curb height");
+            write_column(g.get(), "cross_slope", sx, "percent", "road cross slope");
+            write_column(g.get(), "n_road", nroad, "dimensionless", "road Manning's n");
+            write_column(g.get(), "gutter_depression", a, u.length, "gutter depression");
+            write_column(g.get(), "gutter_width", wdep, u.length, "gutter width");
+            write_column(g.get(), "sides", sides, "count", "1 or 2 gutters");
+            write_column(g.get(), "backing_width", tback, u.length, "backing width");
+            write_column(g.get(), "backing_slope", sback, "percent", "backing slope");
+            write_column(g.get(), "n_backing", nback, "dimensionless", "backing Manning's n");
+        }
+    }
+}
+
+}  // namespace
+
+int write_model(const std::string& path, const SimulationContext& ctx_internal,
+                std::vector* warnings) {
+    // Authored units, exactly like the .inp writer (STRATEGY.md §4): the same
+    // display + authored passes on a COPY, so the live model is never mutated
+    // and the numbers in the file are the numbers the modeller typed.
+    const int us = ucf::getUnitSystem(static_cast(ctx_internal.options.flow_units));
+    const auto usz = static_cast(us);
+    const bool needs_display =
+        ucf::Ucf[ucf::LENGTH][usz]   != 1.0 ||
+        ucf::Ucf[ucf::RAINFALL][usz] != 1.0 ||
+        ucf::Qcf[static_cast(ctx_internal.options.flow_units)] != 1.0;
+    const bool needs_authored = input::needs_authored_conversion(ctx_internal);
+
+    SimulationContext copy;
+    if (needs_display || needs_authored) {
+        copy = ctx_internal;
+        if (needs_display)  input::convert_internal_to_display(copy);
+        if (needs_authored) input::convert_internal_to_authored(copy);
+    }
+    const SimulationContext& ctx = (needs_display || needs_authored) ? copy : ctx_internal;
+
+    Handle file(H5Fcreate(path.c_str(), H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT),
+                Handle::Kind::File);
+    if (!file) {
+        if (warnings) warnings->push_back("HDF5: could not create '" + path + "'");
+        return 1;
+    }
+
+    const UnitWords u = unit_words(us);
+    write_root_attrs(file.get(), ctx, us);
+    write_nodes(file.get(), ctx, u);
+    write_node_subtypes(file.get(), ctx, u);
+    write_links(file.get(), ctx, u);
+    write_link_subtypes(file.get(), ctx, u);
+    write_xsections(file.get(), ctx, u);
+    write_subcatchments(file.get(), ctx, u);
+    write_tables(file.get(), ctx);
+    write_transects_and_streets(file.get(), ctx, u);
+    write_geometry(file.get(), ctx, u);
+
+    // Sections this slice does not yet carry. Named explicitly rather than
+    // dropped in silence — the mistake the GeoPackage schema made and the
+    // file-IO audit had to reconstruct by reading the DDL.
+    if (warnings) {
+        warnings->push_back(
+            "HDF5 model schema " + std::string(kSchemaVersion) + " does not yet carry: "
+            "[CONTROLS], [LID_CONTROLS], [LID_USAGE], [AQUIFERS], [GROUNDWATER], [GWF], "
+            "[SNOWPACKS], [POLLUTANTS], [LANDUSES], [BUILDUP], [WASHOFF], [COVERAGES], "
+            "[LOADINGS], [TREATMENT], [INFLOWS], [DWF], [RDII], [HYDROGRAPHS], "
+            "[PATTERNS], [INLETS], [INLET_USAGE], [OPTIONS], [REPORT] and the 2D "
+            "sections. Use the .inp or .gpkg writer for a complete model.");
+    }
+    return 0;
+}
+
+}  // namespace openswmm::h5io
diff --git a/src/engine/io/hdf5/Hdf5ModelWriter.hpp b/src/engine/io/hdf5/Hdf5ModelWriter.hpp
new file mode 100644
index 000000000..b61109289
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5ModelWriter.hpp
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5ModelWriter.hpp
+ * @brief Serialise a SimulationContext to the columnar HDF5 model format.
+ *
+ * @details Design and rationale: `src/engine/io/hdf5/STRATEGY.md`.
+ *
+ *          Two decisions carry most of the weight:
+ *
+ *          1. **Authored units, exactly like the `.inp`** (STRATEGY §4). The
+ *             writer runs the same `convert_internal_to_display` +
+ *             `convert_internal_to_authored` pass on a copy that InpWriter
+ *             does, so the numbers in the file are the numbers the modeller
+ *             typed. GeoPackage made the opposite choice — internal units with
+ *             a single display-unit island for the cross-section geoms — and
+ *             the file-IO audit found that island is a standing trap.
+ *          2. **References are written as NAMES, not indices.** A file that
+ *             says `node1 = "J1"` survives renumbering and is legible in
+ *             h5py; resolution happens once on read.
+ *
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_HDF5_MODEL_WRITER_HPP
+#define OPENSWMM_HDF5_MODEL_WRITER_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+struct SimulationContext;
+
+namespace h5io {
+
+/// Bumped on any layout change. The reader refuses a major it does not know
+/// rather than silently misreading a file written by a newer engine.
+inline constexpr int    kSchemaVersionMajor = 1;
+inline constexpr int    kSchemaVersionMinor = 0;
+inline constexpr const char* kSchemaVersion = "1.0";
+
+/**
+ * @brief Write the model held by @p ctx to @p path as HDF5.
+ *
+ * @param path      Destination `.h5` path (overwritten if it exists).
+ * @param ctx       The model. Not modified: unit conversion runs on a copy.
+ * @param warnings  Receives one entry per section that could not be written
+ *                  in full. Optional.
+ * @returns 0 on success, non-zero on failure.
+ */
+int write_model(const std::string& path, const SimulationContext& ctx,
+                std::vector* warnings = nullptr);
+
+}  // namespace h5io
+}  // namespace openswmm
+
+#endif  // OPENSWMM_HDF5_MODEL_WRITER_HPP
diff --git a/src/engine/io/hdf5/Hdf5PluginInfo.cpp b/src/engine/io/hdf5/Hdf5PluginInfo.cpp
new file mode 100644
index 000000000..7ecd8468f
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5PluginInfo.cpp
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5PluginInfo.cpp
+ * @brief Factory methods for the HDF5 plugin info singleton.
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "Hdf5PluginInfo.hpp"
+#include "Hdf5InputPlugin.hpp"
+
+namespace openswmm::h5io {
+
+IInputPlugin* Hdf5PluginInfo::create_input_plugin() const {
+    // The caller owns the instance; swmm_model_write_with_plugin creates one
+    // transiently per call and deletes it, so the engine's primary input
+    // plugin is never disturbed.
+    return new Hdf5InputPlugin();
+}
+
+}  // namespace openswmm::h5io
diff --git a/src/engine/io/hdf5/Hdf5PluginInfo.hpp b/src/engine/io/hdf5/Hdf5PluginInfo.hpp
new file mode 100644
index 000000000..f64d909ae
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5PluginInfo.hpp
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5PluginInfo.hpp
+ * @brief IPluginComponentInfo for the HDF5 model I/O plugin.
+ *
+ * @details Registered as a built-in by PluginFactory::register_builtin_infos(),
+ *          exactly as GeoPackagePluginInfo is, so no dlopen and no [PLUGINS]
+ *          row is needed to reach it.
+ *
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_HDF5_PLUGIN_INFO_HPP
+#define OPENSWMM_HDF5_PLUGIN_INFO_HPP
+
+#include 
+
+#include 
+#include 
+
+namespace openswmm::h5io {
+
+/**
+ * @brief Singleton describing the HDF5 I/O plugin.
+ * @ingroup engine_hdf5
+ */
+class Hdf5PluginInfo : public IPluginComponentInfo {
+public:
+    static Hdf5PluginInfo& instance() {
+        static Hdf5PluginInfo inst;
+        return inst;
+    }
+
+    // --- identity -----------------------------------------------------------
+
+    std::string id() const override {
+        return "org.hydrocouple.openswmm.plugins.hdf5";
+    }
+
+    std::string caption() const override { return "HDF5 Model I/O Plugin"; }
+
+    std::string description() const override {
+        return "Writes SWMM model definitions to a columnar HDF5 container: one "
+               "group per object class, one array per attribute, in AUTHORED "
+               "units. Intended for array-shaped consumers — h5py, xarray, "
+               "MATLAB, notebooks — that want the model without parsing text or "
+               "issuing SQL. See src/engine/io/hdf5/STRATEGY.md.";
+    }
+
+    std::string version() const override { return "1.0.0"; }
+    std::string vendor()  const override { return "HydroCouple"; }
+
+    std::string url() const override {
+        return "https://hydrocouple.org/projects/openswmm/plugins/hdf5";
+    }
+
+    std::vector tags() const override {
+        return {"hdf5", "h5", "columnar", "input", "output", "export",
+                "analysis", "python"};
+    }
+
+    // --- licensing ----------------------------------------------------------
+
+    std::string license_type() const override { return "Apache-2.0"; }
+
+    std::string license_text() const override {
+        return "Copyright (c) 2026 Caleb Buahin. All rights reserved.\n"
+               "Licensed under the Apache License, Version 2.0 — see the\n"
+               "LICENSE and NOTICE files for full text.";
+    }
+
+    // --- capabilities -------------------------------------------------------
+    //
+    // Only the model role is claimed today. Results and report plugins are
+    // designed in STRATEGY.md §7 but not built, and advertising a capability
+    // this plugin cannot honour would make swmm_model_write_with_plugin
+    // resolve and then fail at the call rather than at the lookup.
+
+    bool has_input()  const noexcept override { return true; }
+    bool has_output() const noexcept override { return false; }
+    bool has_report() const noexcept override { return false; }
+
+    std::vector file_filters() const override {
+        const std::string desc = "OpenSWMM HDF5 model";
+        const std::vector patterns = {"*.h5", "*.hdf5"};
+        const std::vector mimes    = {"application/x-hdf5"};
+        return { FileFilter{ desc, patterns, PluginRole::INPUT_READ, mimes } };
+    }
+
+    // --- factories ----------------------------------------------------------
+
+    IInputPlugin* create_input_plugin() const override;
+
+private:
+    Hdf5PluginInfo() = default;
+};
+
+}  // namespace openswmm::h5io
+
+#endif  // OPENSWMM_HDF5_PLUGIN_INFO_HPP
diff --git a/src/engine/io/hdf5/Hdf5Util.cpp b/src/engine/io/hdf5/Hdf5Util.cpp
new file mode 100644
index 000000000..c2e6d78ef
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5Util.cpp
@@ -0,0 +1,353 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5Util.cpp
+ * @brief Implementation of the RAII handles and columnar helpers.
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "Hdf5Util.hpp"
+
+#include 
+#include 
+
+namespace openswmm::h5io {
+namespace {
+
+/// Chunking is required for a compressed or extendible dataset, and pointless
+/// for a tiny one. HDF5 rejects a zero-sized chunk, so an empty column is
+/// written contiguous and uncompressed.
+Handle make_dcpl(hsize_t n, int compression) {
+    if (n == 0 || compression <= 0) return {};
+    Handle plist(H5Pcreate(H5P_DATASET_CREATE), Handle::Kind::Plist);
+    if (!plist) return {};
+    hsize_t chunk = n < 1024 ? n : 1024;
+    H5Pset_chunk(plist.get(), 1, &chunk);
+    H5Pset_deflate(plist.get(), static_cast(compression));
+    return plist;
+}
+
+/// Attributes attach to an OBJECT, and a file id is not one. H5Aexists accepts
+/// a file id on some builds and refuses it on others (vcpkg's 1.14.4 refuses
+/// it on read with "can't set object access arguments"), so resolve a file id
+/// to its root group once and use that everywhere.
+struct AttrTarget {
+    Handle owned;       // holds "/" only when `loc` was a file
+    hid_t  id = -1;
+
+    explicit AttrTarget(hid_t loc) {
+        if (H5Iget_type(loc) == H5I_FILE) {
+            owned = Handle(H5Gopen2(loc, "/", H5P_DEFAULT), Handle::Kind::Group);
+            id = owned.get();
+        } else {
+            id = loc;
+        }
+    }
+    bool ok() const { return id >= 0; }
+};
+
+void tag_column(hid_t ds, const std::string& units, const std::string& description) {
+    if (!units.empty())       write_attr(ds, "units", units);
+    if (!description.empty()) write_attr(ds, "description", description);
+}
+
+/// Create a 1-D dataset of `type` holding `n` elements.
+Handle make_dataset(hid_t group, const std::string& name, hid_t type,
+                    hsize_t n, int compression) {
+    Handle space(H5Screate_simple(1, &n, nullptr), Handle::Kind::Space);
+    if (!space) return {};
+    Handle dcpl = make_dcpl(n, compression);
+    return Handle(H5Dcreate2(group, name.c_str(), type, space.get(),
+                             H5P_DEFAULT, dcpl ? dcpl.get() : H5P_DEFAULT,
+                             H5P_DEFAULT),
+                  Handle::Kind::Dataset);
+}
+
+}  // namespace
+
+void Handle::close() noexcept {
+    if (id_ < 0) return;
+    switch (kind_) {
+        case Kind::File:    H5Fclose(id_); break;
+        case Kind::Group:   H5Gclose(id_); break;
+        case Kind::Dataset: H5Dclose(id_); break;
+        case Kind::Space:   H5Sclose(id_); break;
+        case Kind::Type:    H5Tclose(id_); break;
+        case Kind::Attr:    H5Aclose(id_); break;
+        case Kind::Plist:   H5Pclose(id_); break;
+    }
+    id_ = -1;
+}
+
+Handle open_file_readonly(const std::string& path) {
+    return Handle(H5Fopen(path.c_str(), H5F_ACC_RDONLY, H5P_DEFAULT),
+                  Handle::Kind::File);
+}
+
+std::string column_units(hid_t group, const std::string& column) {
+    if (H5Lexists(group, column.c_str(), H5P_DEFAULT) <= 0) return {};
+    Handle ds(H5Dopen2(group, column.c_str(), H5P_DEFAULT), Handle::Kind::Dataset);
+    if (!ds) return {};
+    std::string out;
+    return read_attr(ds.get(), "units", out) ? out : std::string();
+}
+
+Handle make_string_type() {
+    Handle t(H5Tcopy(H5T_C_S1), Handle::Kind::Type);
+    if (!t) return t;
+    H5Tset_size(t.get(), H5T_VARIABLE);
+    H5Tset_cset(t.get(), H5T_CSET_UTF8);
+    return t;
+}
+
+Handle make_group(hid_t loc, const std::string& name) {
+    if (has_link(loc, name)) return open_group(loc, name);
+    // Intermediate groups on demand, so "nodes/junctions" needs one call.
+    Handle lcpl(H5Pcreate(H5P_LINK_CREATE), Handle::Kind::Plist);
+    if (lcpl) H5Pset_create_intermediate_group(lcpl.get(), 1);
+    return Handle(H5Gcreate2(loc, name.c_str(),
+                             lcpl ? lcpl.get() : H5P_DEFAULT,
+                             H5P_DEFAULT, H5P_DEFAULT),
+                  Handle::Kind::Group);
+}
+
+Handle open_group(hid_t loc, const std::string& name) {
+    return Handle(H5Gopen2(loc, name.c_str(), H5P_DEFAULT), Handle::Kind::Group);
+}
+
+bool has_link(hid_t loc, const std::string& name) {
+    // H5Lexists only checks one level, so walk the path; a missing ancestor
+    // must answer false rather than raise.
+    std::size_t start = 0;
+    std::string acc;
+    while (start <= name.size()) {
+        const std::size_t slash = name.find('/', start);
+        const std::string part = name.substr(start, slash - start);
+        if (!part.empty()) {
+            acc += (acc.empty() ? "" : "/") + part;
+            const htri_t e = H5Lexists(loc, acc.c_str(), H5P_DEFAULT);
+            if (e <= 0) return false;
+        }
+        if (slash == std::string::npos) break;
+        start = slash + 1;
+    }
+    return !acc.empty();
+}
+
+// ---------------------------------------------------------------------------
+// Attributes
+// ---------------------------------------------------------------------------
+
+bool write_attr(hid_t loc_in, const std::string& name, const std::string& value) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) > 0) H5Adelete(loc, name.c_str());
+    Handle type(H5Tcopy(H5T_C_S1), Handle::Kind::Type);
+    if (!type) return false;
+    // A fixed-size attribute type keeps the value readable from h5dump and
+    // MATLAB, both of which handle variable-length attributes poorly.
+    H5Tset_size(type.get(), value.empty() ? 1 : value.size());
+    H5Tset_cset(type.get(), H5T_CSET_UTF8);
+    Handle space(H5Screate(H5S_SCALAR), Handle::Kind::Space);
+    Handle attr(H5Acreate2(loc, name.c_str(), type.get(), space.get(),
+                           H5P_DEFAULT, H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    return H5Awrite(attr.get(), type.get(), value.empty() ? "" : value.data()) >= 0;
+}
+
+bool write_attr(hid_t loc_in, const std::string& name, double value) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) > 0) H5Adelete(loc, name.c_str());
+    Handle space(H5Screate(H5S_SCALAR), Handle::Kind::Space);
+    Handle attr(H5Acreate2(loc, name.c_str(), H5T_NATIVE_DOUBLE, space.get(),
+                           H5P_DEFAULT, H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    return H5Awrite(attr.get(), H5T_NATIVE_DOUBLE, &value) >= 0;
+}
+
+bool write_attr(hid_t loc_in, const std::string& name, int value) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) > 0) H5Adelete(loc, name.c_str());
+    Handle space(H5Screate(H5S_SCALAR), Handle::Kind::Space);
+    Handle attr(H5Acreate2(loc, name.c_str(), H5T_NATIVE_INT, space.get(),
+                           H5P_DEFAULT, H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    return H5Awrite(attr.get(), H5T_NATIVE_INT, &value) >= 0;
+}
+
+bool read_attr(hid_t loc_in, const std::string& name, std::string& out) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) <= 0) return false;
+    Handle attr(H5Aopen(loc, name.c_str(), H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    Handle type(H5Aget_type(attr.get()), Handle::Kind::Type);
+    if (!type) return false;
+    if (H5Tis_variable_str(type.get()) > 0) {
+        char* raw = nullptr;
+        Handle mem = make_string_type();
+        if (H5Aread(attr.get(), mem.get(), &raw) < 0) return false;
+        out = raw ? raw : "";
+        if (raw) H5free_memory(raw);
+        return true;
+    }
+    const std::size_t n = H5Tget_size(type.get());
+    std::vector buf(n + 1, '\0');
+    if (H5Aread(attr.get(), type.get(), buf.data()) < 0) return false;
+    out.assign(buf.data(), strnlen(buf.data(), n));
+    return true;
+}
+
+bool read_attr(hid_t loc_in, const std::string& name, double& out) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) <= 0) return false;
+    Handle attr(H5Aopen(loc, name.c_str(), H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    return H5Aread(attr.get(), H5T_NATIVE_DOUBLE, &out) >= 0;
+}
+
+bool read_attr(hid_t loc_in, const std::string& name, int& out) {
+    AttrTarget t(loc_in);
+    if (!t.ok()) return false;
+    const hid_t loc = t.id;
+    if (H5Aexists(loc, name.c_str()) <= 0) return false;
+    Handle attr(H5Aopen(loc, name.c_str(), H5P_DEFAULT), Handle::Kind::Attr);
+    if (!attr) return false;
+    return H5Aread(attr.get(), H5T_NATIVE_INT, &out) >= 0;
+}
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& units, const std::string& description,
+                  int compression) {
+    Handle ds = make_dataset(group, name, H5T_IEEE_F64LE,
+                             static_cast(values.size()), compression);
+    if (!ds) return false;
+    tag_column(ds.get(), units, description);
+    if (values.empty()) return true;
+    return H5Dwrite(ds.get(), H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL,
+                    H5P_DEFAULT, values.data()) >= 0;
+}
+
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& units, const std::string& description,
+                  int compression) {
+    Handle ds = make_dataset(group, name, H5T_STD_I32LE,
+                             static_cast(values.size()), compression);
+    if (!ds) return false;
+    tag_column(ds.get(), units, description);
+    if (values.empty()) return true;
+    return H5Dwrite(ds.get(), H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
+                    H5P_DEFAULT, values.data()) >= 0;
+}
+
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& description, int compression) {
+    Handle type = make_string_type();
+    if (!type) return false;
+    Handle ds = make_dataset(group, name, type.get(),
+                             static_cast(values.size()), compression);
+    if (!ds) return false;
+    tag_column(ds.get(), "", description);
+    if (values.empty()) return true;
+    // HDF5 writes variable-length strings from an array of char*, so the
+    // pointers must outlive the call — hence the temporary vector.
+    std::vector ptrs;
+    ptrs.reserve(values.size());
+    for (const auto& s : values) ptrs.push_back(s.c_str());
+    return H5Dwrite(ds.get(), type.get(), H5S_ALL, H5S_ALL,
+                    H5P_DEFAULT, ptrs.data()) >= 0;
+}
+
+namespace {
+/// Element count of a 1-D dataset.
+hsize_t dataset_length(hid_t ds) {
+    Handle space(H5Dget_space(ds), Handle::Kind::Space);
+    if (!space) return 0;
+    hsize_t dims[1] = {0};
+    if (H5Sget_simple_extent_dims(space.get(), dims, nullptr) < 0) return 0;
+    return dims[0];
+}
+}  // namespace
+
+bool read_column(hid_t group, const std::string& name, std::vector& out) {
+    if (H5Lexists(group, name.c_str(), H5P_DEFAULT) <= 0) return false;
+    Handle ds(H5Dopen2(group, name.c_str(), H5P_DEFAULT), Handle::Kind::Dataset);
+    if (!ds) return false;
+    out.assign(static_cast(dataset_length(ds.get())), 0.0);
+    if (out.empty()) return true;
+    return H5Dread(ds.get(), H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL,
+                   H5P_DEFAULT, out.data()) >= 0;
+}
+
+bool read_column(hid_t group, const std::string& name, std::vector& out) {
+    if (H5Lexists(group, name.c_str(), H5P_DEFAULT) <= 0) return false;
+    Handle ds(H5Dopen2(group, name.c_str(), H5P_DEFAULT), Handle::Kind::Dataset);
+    if (!ds) return false;
+    out.assign(static_cast(dataset_length(ds.get())), 0);
+    if (out.empty()) return true;
+    return H5Dread(ds.get(), H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
+                   H5P_DEFAULT, out.data()) >= 0;
+}
+
+bool read_column(hid_t group, const std::string& name, std::vector& out) {
+    if (H5Lexists(group, name.c_str(), H5P_DEFAULT) <= 0) return false;
+    Handle ds(H5Dopen2(group, name.c_str(), H5P_DEFAULT), Handle::Kind::Dataset);
+    if (!ds) return false;
+    const auto n = static_cast(dataset_length(ds.get()));
+    out.assign(n, std::string());
+    if (n == 0) return true;
+    Handle type = make_string_type();
+    std::vector raw(n, nullptr);
+    if (H5Dread(ds.get(), type.get(), H5S_ALL, H5S_ALL, H5P_DEFAULT, raw.data()) < 0)
+        return false;
+    for (std::size_t i = 0; i < n; ++i) {
+        out[i] = raw[i] ? raw[i] : "";
+    }
+    // Variable-length reads allocate per element; H5Dvlen_reclaim is the only
+    // sanctioned way to give them back.
+    Handle space(H5Dget_space(ds.get()), Handle::Kind::Space);
+    H5Dvlen_reclaim(type.get(), space.get(), H5P_DEFAULT, raw.data());
+    return true;
+}
+
+std::size_t column_length(hid_t group, const std::string& probe) {
+    if (H5Lexists(group, probe.c_str(), H5P_DEFAULT) <= 0) return 0;
+    Handle ds(H5Dopen2(group, probe.c_str(), H5P_DEFAULT), Handle::Kind::Dataset);
+    if (!ds) return 0;
+    return static_cast(dataset_length(ds.get()));
+}
+
+}  // namespace openswmm::h5io
diff --git a/src/engine/io/hdf5/Hdf5Util.hpp b/src/engine/io/hdf5/Hdf5Util.hpp
new file mode 100644
index 000000000..fbd82f1ec
--- /dev/null
+++ b/src/engine/io/hdf5/Hdf5Util.hpp
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file Hdf5Util.hpp
+ * @brief RAII handles and columnar table helpers over the raw HDF5 C API.
+ *
+ * @details The model format is columnar: one group per object class, one
+ *          equal-length 1-D dataset per attribute (see STRATEGY.md §3). Nearly
+ *          every write is therefore "here is a vector of doubles / ints /
+ *          strings, call it `length`, and say its units are feet". These
+ *          helpers reduce that to one line so the writer reads as a schema
+ *          rather than as HDF5 boilerplate.
+ *
+ *          Raw C HDF5 (`hdf5.h`, `hid_t`) deliberately — it is what
+ *          Default2DOutputPlugin uses, and HDF5 is PRIVATE-linked with hidden
+ *          symbols because a consumer linking its own copy (the Qt GUI does)
+ *          otherwise dies in H5_term_library on foreign global state.
+ *
+ * @ingroup engine_hdf5
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_HDF5_UTIL_HPP
+#define OPENSWMM_HDF5_UTIL_HPP
+
+#include 
+
+#include 
+#include 
+#include 
+
+namespace openswmm::h5io {
+
+/**
+ * @brief Owns an hid_t and closes it with the right H5*close on scope exit.
+ *
+ * HDF5 identifiers are not RAII and leak silently: a missed H5Dclose keeps the
+ * whole file object alive, so H5Fclose "succeeds" while flushing nothing.
+ */
+class Handle {
+public:
+    enum class Kind { File, Group, Dataset, Space, Type, Attr, Plist };
+
+    Handle() = default;
+    Handle(hid_t id, Kind kind) : id_(id), kind_(kind) {}
+    Handle(const Handle&) = delete;
+    Handle& operator=(const Handle&) = delete;
+    Handle(Handle&& o) noexcept : id_(o.id_), kind_(o.kind_) { o.id_ = -1; }
+    Handle& operator=(Handle&& o) noexcept {
+        if (this != &o) { close(); id_ = o.id_; kind_ = o.kind_; o.id_ = -1; }
+        return *this;
+    }
+    ~Handle() { close(); }
+
+    hid_t get() const noexcept { return id_; }
+    bool  ok()  const noexcept { return id_ >= 0; }
+    explicit operator bool() const noexcept { return ok(); }
+
+    /// Defined OUT OF LINE on purpose. HDF5 is PRIVATE-linked into the engine
+    /// with hidden symbols, so a consumer that also linked its own copy would
+    /// have two HDF5 instances with separate global state — the crash the
+    /// CMake comments at src/engine/CMakeLists.txt warn about. Keeping every
+    /// H5* call inside the engine means a caller needs these headers but not
+    /// the library, and ids never cross between instances.
+    void close() noexcept;
+
+private:
+    hid_t id_ = -1;
+    Kind  kind_ = Kind::File;
+};
+
+/// A variable-length UTF-8 string type, for name columns.
+Handle make_string_type();
+
+/// Open an existing model file read-only. Callers use this rather than
+/// H5Fopen so that every HDF5 call stays inside the engine's instance.
+Handle open_file_readonly(const std::string& path);
+
+/// A column's `units` attribute, or "" when it has none.
+std::string column_units(hid_t group, const std::string& column);
+
+/// Create (or open) a group, creating intermediate groups as needed.
+Handle make_group(hid_t loc, const std::string& name);
+Handle open_group(hid_t loc, const std::string& name);
+
+/// True when `loc` contains `name`.
+bool has_link(hid_t loc, const std::string& name);
+
+// ---------------------------------------------------------------------------
+// Attributes — scalars on a group or on the file root.
+// ---------------------------------------------------------------------------
+bool write_attr(hid_t loc, const std::string& name, const std::string& value);
+bool write_attr(hid_t loc, const std::string& name, double value);
+bool write_attr(hid_t loc, const std::string& name, int value);
+
+bool read_attr(hid_t loc, const std::string& name, std::string& out);
+bool read_attr(hid_t loc, const std::string& name, double& out);
+bool read_attr(hid_t loc, const std::string& name, int& out);
+
+// ---------------------------------------------------------------------------
+// Columns — equal-length 1-D datasets inside a group.
+//
+// `units` and `description` ride along as dataset attributes so the file
+// explains itself without this repository (STRATEGY.md §2). Pass an empty
+// string to omit either.
+//
+// An EMPTY column is still written, as a zero-length dataset: a group whose
+// columns disagree on length is the one corruption a columnar reader cannot
+// recover from, so shape is always explicit.
+// ---------------------------------------------------------------------------
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& units = "",
+                  const std::string& description = "",
+                  int compression = 4);
+
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& units = "",
+                  const std::string& description = "",
+                  int compression = 4);
+
+bool write_column(hid_t group, const std::string& name,
+                  const std::vector& values,
+                  const std::string& description = "",
+                  int compression = 4);
+
+bool read_column(hid_t group, const std::string& name, std::vector& out);
+bool read_column(hid_t group, const std::string& name, std::vector& out);
+bool read_column(hid_t group, const std::string& name, std::vector& out);
+
+/// Row count of a group's columns — the length of `probe`, or 0 if absent.
+std::size_t column_length(hid_t group, const std::string& probe);
+
+}  // namespace openswmm::h5io
+
+#endif  // OPENSWMM_HDF5_UTIL_HPP
diff --git a/src/engine/io/hdf5/STRATEGY.md b/src/engine/io/hdf5/STRATEGY.md
new file mode 100644
index 000000000..a80d8bc5a
--- /dev/null
+++ b/src/engine/io/hdf5/STRATEGY.md
@@ -0,0 +1,194 @@
+# HDF5 I/O Strategy for OpenSWMM
+
+Companion to `src/engine/input/geopackage/STRATEGY.md`. Where that document
+designs a *relational, queryable* container, this one designs a *columnar,
+array-native* one: the same model, laid out the way HDF5, h5py, xarray and
+MATLAB expect to find it.
+
+## 1. Why a third format
+
+`.inp` is the interchange format and the only one a legacy engine reads.
+`.gpkg` is the spatial/relational store, good for GIS and SQL. Neither is a
+good fit for the array-shaped consumers of this model — Python analysis,
+notebooks, ML pipelines, or anything that wants to slice 10⁶ links without
+parsing text or issuing SQL.
+
+HDF5 also already carries this project's 2D results
+(`src/engine/2d/output/Default2DOutputPlugin.cpp`), so the dependency, the
+toolchain and the symbol-hiding constraints are established. This makes the
+model side a natural extension rather than a new dependency.
+
+## 2. Design principles
+
+| Principle | Rationale |
+|---|---|
+| **Columnar, not relational** | One group per object class, one equal-length 1-D dataset per attribute. A reader gets `links/conduits/length` as a contiguous array — no joins, no row iteration. This mirrors the engine's own SoA layout (`LinkData`, `NodeData`), so read and write are both near-memcpy. |
+| **AUTHORED units, exactly like the `.inp`** | See §4. This is the single most consequential decision in the format and it is deliberately *not* GeoPackage's. |
+| **Self-describing** | Every group carries a `units` and `description` attribute per column. A file opened five years from now explains itself without this repository. |
+| **Cover what GeoPackage drops** | The file-IO audit (`plans/FILE_IO_PARITY_AUDIT_2026-09-22.md` §6) lists fourteen `.inp` sections the `.gpkg` schema has no column for. That list is this schema's requirements document, not a precedent to copy. |
+| **Versioned from day one** | Root attribute `schema_version`. The reader checks it and refuses a major it does not know, rather than silently misreading. |
+| **Plugin-shaped** | `IInputPlugin` / `IOutputPlugin` / `IReportPlugin`, exactly like GeoPackage, so `swmm_model_write_with_plugin` needs no engine change. |
+
+## 3. Layout
+
+```
+/                                 attrs: schema_version, engine_version,
+                                         flow_units, unit_system, created_utc,
+                                         title
+/options                          attrs: one per option key (scalar, typed)
+/report                           attrs: flags; datasets: subcatchments, nodes, links
+/nodes/junctions                  name, invert_elev, full_depth, init_depth,
+                                  sur_depth, ponded_area, tag, comment
+/nodes/outfalls                   + bc_type, stage, curve, has_flap_gate, route_to
+/nodes/dividers                   + div_link, method, cutoff, curve, qmin, dh_max, cd
+/nodes/storage                    + shape, curve, a0, a1, a2, p1, p2, p3,
+                                  evap_frac, exfil_*
+/links/conduits                   name, node1, node2, length, roughness,
+                                  offset1, offset2, q0, q_limit, barrels,
+                                  culvert_code, loss_*, seep_rate, has_flap_gate
+/links/pumps|orifices|weirs|outlets
+/links/xsections                  link, shape, geom1..geom4       (see §5)
+/subcatchments                    name, gage, outlet, area, pct_imperv, width,
+                                  slope, curb_length, snowpack, + subarea and
+                                  infiltration columns
+/hydrology/aquifers|groundwater|gwf|snowpacks|lid_controls|lid_usage
+/quality/pollutants|landuses|buildup|washoff|coverages|loadings|treatment
+/loading/inflows|dwf|rdii|hydrographs
+/tables/curves                    name, type, x, y  + an offsets index
+/tables/timeseries                name, date, time, value + offsets
+/tables/patterns                  name, type, factors
+/geometry/transects|streets|inlets|inlet_usage
+/geometry/coordinates|vertices|polygons|symbols|labels
+/controls                         rule text, one string per clause
+/plugins, /process_components, /user_flags
+/results//...      written by the OUTPUT plugin (§7)
+```
+
+**Ragged tables** (a curve's ordinates, a pattern's factors, a transect's
+stations) use the CSR idiom: one flat value dataset plus an `offsets` dataset
+of length `n+1`. It keeps everything a contiguous array and needs no
+variable-length HDF5 types, which are awkward from MATLAB and slow in h5py.
+
+**Names** are HDF5 variable-length UTF-8 strings. **Indices are written as
+names, not integers** — a file that says `node1 = "J1"` survives a renumbering
+and is legible; resolution happens once on read, the same way the `.inp`
+parser does it.
+
+## 4. Units: authored, not internal
+
+**Decision: the HDF5 file stores AUTHORED (display) units throughout — the
+same values the `.inp` carries, under the file's own `flow_units`.**
+
+GeoPackage chose the opposite: internal feet/cfs everywhere, with
+`xsect_geom1..4` as a single display-unit island, gated on read by
+`ctx.gpkg_units_internal`. That is a defensible choice for a canonical store,
+but the audit found the island is a live trap — the one exception a new
+format must replicate exactly or be wrong by 3.28084 on metric models — and
+found a probable ELEVATION-offset double-subtraction that the same gating
+made possible.
+
+Storing authored units instead means:
+
+* the write path is `convert_internal_to_display` + `convert_internal_to_authored`
+  on a copy, which is **the same, already-tested pass the `.inp` writer uses**
+  (`InpWriter.cpp`), including the adverse-slope un-reversal, the
+  `LINK_OFFSETS=ELEVATION` restoration and the FILLED_CIRCULAR sediment bump;
+* the read path is the ordinary `convert_inputs_to_internal`, with no gate and
+  no exception;
+* there is no island, so no rule for a future maintainer to forget;
+* the numbers in the file match the numbers in the `.inp` and in the GUI, which
+  is what anyone opening it in h5py expects.
+
+The cost is that the file is not the engine's internal representation. That is
+the right trade: this is an interchange format, not a memory image.
+
+Every dataset carries a `units` attribute naming the actual unit
+(`"ft"`, `"m"`, `"cfs"`, `"in/hr"`, `"dimensionless"`), resolved against the
+root `unit_system`.
+
+## 5. Cross sections
+
+The audit's §3 matrix is the specification. Two rules the format must not blur:
+
+1. **Geom1–Geom4 are stored raw, as authored**, never as the resolver's derived
+   `y_full`/`w_max`. Their meaning is shape-dependent — a length, a
+   dimensionless side slope, a Manning's-n-like C-factor, or a *lookup-table
+   index* — and only the raw values reconstruct the section. The engine already
+   retains them for exactly this reason (`LinkData::xsect_geom1`).
+2. **The ellipse/arch standard-size-code convention is preserved verbatim.**
+   `ARCH 12 0 0 0` means standard arch code 12, not a 12-ft rise
+   (`xsect.c:612-623`). A writer that "helpfully" substituted real dimensions
+   would silently change the geometry, and on an SI model the metres would be
+   re-read as a size code. The `shape` column plus the raw geoms is enough to
+   round-trip this; nothing is normalised on the way out.
+
+`xsections/shape` is written as the **legacy keyword string**
+(`"RECT_TRIANGULAR"`, not an enum ordinal). Two enums in this codebase disagree
+on ordering and an `enum + 1` translation between them was once the single
+largest parity bug in the project; a format that stores the keyword cannot
+reproduce that class of error.
+
+The culvert code gets its own column. It was the defect that opened the audit.
+
+## 6. Model read/write plugin
+
+`Hdf5InputPlugin : IInputPlugin` — `read()` and `write()` delegate to
+`Hdf5ModelReader` / `Hdf5ModelWriter`, exactly as `GeoPackageInputPlugin`
+delegates. Registered as a built-in in `PluginFactory::register_builtin_infos()`
+beside GeoPackage, so
+
+```c
+swmm_model_write_with_plugin(e, "model.h5", "org.hydrocouple.openswmm.plugins.hdf5");
+```
+
+works with **no engine change**. `file_filters()` advertises `*.h5` / `*.hdf5`
+for all three roles.
+
+Note there is no extension→plugin resolution in the engine today: nothing
+consumes `file_filters()`, and `swmm_model_write(e, "model.h5")` still writes
+an `.inp`. Adding an `IInputPlugin::can_write(path)` sniff mirroring
+`IStateIOPlugin::can_read` would fix that for every format at once. Proposed
+separately — it changes dispatch behaviour for existing callers and should not
+ride in on a new format.
+
+## 7. Results and report plugins
+
+`Hdf5OutputPlugin : IOutputPlugin` writes `/results//` with the
+same unlimited-dimension, chunked, gzip-compressed append the 2D plugin already
+uses (`createUnlimitedDataset`): `/time` plus `[nTime, nObject]` datasets per
+variable, per object class. Multiple runs coexist under distinct
+`simulation_id` groups, the same isolation GeoPackage gets from its
+`simulations` table.
+
+`Hdf5ReportPlugin : IReportPlugin` writes `/results//summary/` — the
+continuity tables, flow-stats and per-object summaries — as columnar tables
+rather than formatted text, so they can be read back without parsing a `.rpt`.
+
+A `.h5` is **never byte-identical** between runs (HDF5 embeds timestamps and
+allocates freelists nondeterministically). Compare with `h5diff`, never `cmp`.
+
+## 8. Build and linkage constraints
+
+Non-negotiable, all already load-bearing in this tree:
+
+* **Raw C HDF5 only** (`hdf5.h`, `hid_t`). No HighFive, no C++ bindings —
+  matching `Default2DOutputPlugin`, which is the only HDF5 code here today.
+* **HDF5 is PRIVATE-linked with hidden dynamic symbols**
+  (`src/engine/CMakeLists.txt:352-359`). A consumer that links its own HDF5 —
+  the Qt GUI does — otherwise crashes in `H5_term_library → H5I_clear_type` on
+  foreign global state. New symbols go in `macos_unexported_symbols.txt`.
+* HDF5 is reachable today only under `OPENSWMM_BUILD_2D`. The model plugin
+  takes its own `OPENSWMM_WITH_HDF5` option, defaulting ON when 2D is on,
+  following the `OPENSWMM_WITH_GEOPACKAGE` pattern, so a 2D-less build can
+  still read and write `.h5` models.
+
+## 9. Testing
+
+| Level | Scope |
+|---|---|
+| Unit | table round-trip per group; ragged CSR encode/decode; string columns; schema-version refusal |
+| Integration | `.inp` → `.h5` → reopen → **identical simulation results** — the end-to-end check GeoPackage currently lacks (audit §6) |
+| Cross section | every shape in the audit's §3 matrix, including both ellipse/arch idioms and the culvert column |
+| Units | the same model in CFS and CMS; authored values identical in both files modulo the unit factor |
+| Coverage | a deck exercising each section GeoPackage drops, asserting none is lost |
+| Comparison | `h5diff`, never `cmp` |
diff --git a/src/engine/math/FindRoot.cpp b/src/engine/math/FindRoot.cpp
index a027c0f87..e65e55dd5 100644
--- a/src/engine/math/FindRoot.cpp
+++ b/src/engine/math/FindRoot.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FindRoot.cpp
  * @brief Newton-Raphson + Ridder — numerically identical to legacy findroot.c.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "FindRoot.hpp"
@@ -15,87 +31,93 @@ namespace openswmm {
 namespace findroot {
 
 int newton(double x1, double x2, double* rts, double xacc, const NewtonFunc& func) {
-    double xlo, xhi, f, df, dx, dxold, temp;
-
-    // Orient bracket so f(xlo) < 0
-    double fl, fh, dfl, dfh;
-    func(x1, &fl, &dfl);
-    func(x2, &fh, &dfh);
-
-    if (fl < 0.0) { xlo = x1; xhi = x2; }
-    else          { xhi = x1; xlo = x2; }
-
-    double x = *rts;
+    // legacy findroot_Newton, op for op: the caller brackets the root with
+    // f(x1) < 0 < f(x2) (switching x1/x2 when f(x1) > f(x2), as kinwave.c
+    // solveContinuity does) — no orienting pre-evaluations here, so the
+    // function is called exactly in legacy's sequence and count; the
+    // return is the number of evaluations, 0 past MAXIT.
+    int n = 0;
+    double f, df, dx, dxold, temp;
+    double x   = *rts;
+    double xlo = x1;
+    double xhi = x2;
     dxold = std::fabs(x2 - x1);
     dx = dxold;
     func(x, &f, &df);
+    n++;
 
     for (int j = 1; j <= MAXIT; ++j) {
-        // Use bisection if Newton out of bracket or converging slowly
-        if (((x - xhi) * df - f) * ((x - xlo) * df - f) >= 0.0 ||
-            std::fabs(2.0 * f) > std::fabs(dxold * df)) {
+        // Bisect if Newton out of range or not decreasing fast enough.
+        if ((((x - xhi) * df - f) * ((x - xlo) * df - f) >= 0.0
+             || (std::fabs(2.0 * f) > std::fabs(dxold * df)))) {
             dxold = dx;
             dx = 0.5 * (xhi - xlo);
             x = xlo + dx;
-            if (xlo == x) { *rts = x; return j; }
-        } else {
+            if (xlo == x) break;
+        }
+        // Newton step acceptable. Take it.
+        else {
             dxold = dx;
             dx = f / df;
             temp = x;
             x -= dx;
-            if (temp == x) { *rts = x; return j; }
+            if (temp == x) break;
         }
 
-        if (std::fabs(dx) < xacc) { *rts = x; return j; }
+        // Convergence criterion.
+        if (std::fabs(dx) < xacc) break;
 
+        // Evaluate function. Maintain bracket on the root.
         func(x, &f, &df);
+        n++;
         if (f < 0.0) xlo = x;
         else         xhi = x;
     }
-
     *rts = x;
-    return 0;  // exceeded MAXIT
+    if (n <= MAXIT) return n;
+    else return 0;
 }
 
 double ridder(double x1, double x2, double xacc, const RidderFunc& func) {
-    double fl = func(x1);
-    double fh = func(x2);
-
-    if (fl == 0.0) return x1;
-    if (fh == 0.0) return x2;
-
-    double ans = -1.0e10;
-    double xlo = x1, xhi = x2;
-
-    for (int j = 1; j <= MAXIT; ++j) {
-        double xm = 0.5 * (xlo + xhi);
-        double fm = func(xm);
-
-        double s = std::sqrt(fm * fm - fl * fh);
-        if (s == 0.0) return ans;
-
-        double xnew = xm + (xm - xlo) * ((fl >= fh ? 1.0 : -1.0) * fm / s);
-
-        if (std::fabs(xnew - ans) <= xacc) return xnew;
-        ans = xnew;
-
-        double fnew = func(ans);
-        if (fnew == 0.0) return ans;
-
-        // Update bracket
-        if (fm * fnew < 0.0) {
-            xlo = xm; fl = fm;
-            xhi = ans; fh = fnew;
-        } else if (fl * fnew < 0.0) {
-            xhi = ans; fh = fnew;
-        } else {
-            xlo = ans; fl = fnew;
+    // legacy findroot_Ridder, op for op — including the evaluation SEQUENCE,
+    // which the culvert's Form-1 flow depends on (it reads the last
+    // form1Eqn evaluation, not the root), the initial estimate 0.5*(x1+x2),
+    // the return of the PREVIOUS estimate when the new one is within xacc
+    // (`break` then `return ans`), the SIGN-based bracket updates and the
+    // -1e20 no-bracket return.
+    auto SIGN = [](double x, double y) { return (y >= 0.0) ? std::fabs(x) : -std::fabs(x); };
+    double flo = func(x1);
+    double fhi = func(x2);
+    if (flo == 0.0) return x1;
+    if (fhi == 0.0) return x2;
+    double ans = 0.5 * (x1 + x2);
+    if ((flo > 0.0 && fhi < 0.0) || (flo < 0.0 && fhi > 0.0)) {
+        double xlo = x1;
+        double xhi = x2;
+        for (int j = 1; j <= MAXIT; ++j) {
+            const double xm = 0.5 * (xlo + xhi);
+            const double fm = func(xm);
+            const double s = std::sqrt(fm * fm - flo * fhi);
+            if (s == 0.0) return ans;
+            const double xnew = xm + (xm - xlo) * ((flo >= fhi ? 1.0 : -1.0) * fm / s);
+            if (std::fabs(xnew - ans) <= xacc) break;
+            ans = xnew;
+            const double fnew = func(ans);
+            if (SIGN(fm, fnew) != fm) {
+                xlo = xm;  flo = fm;
+                xhi = ans; fhi = fnew;
+            } else if (SIGN(flo, fnew) != flo) {
+                xhi = ans; fhi = fnew;
+            } else if (SIGN(fhi, fnew) != fhi) {
+                xlo = ans; flo = fnew;
+            } else {
+                return ans;
+            }
+            if (std::fabs(xhi - xlo) <= xacc) return ans;
         }
-
-        if (std::fabs(xhi - xlo) <= xacc) return ans;
+        return ans;
     }
-
-    return ans;
+    return -1.0e20;
 }
 
 } // namespace findroot
diff --git a/src/engine/math/FindRoot.hpp b/src/engine/math/FindRoot.hpp
index 8b959c5ec..6e122e1a6 100644
--- a/src/engine/math/FindRoot.hpp
+++ b/src/engine/math/FindRoot.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file FindRoot.hpp
  * @brief Newton-Raphson and Ridder root finders.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_FIND_ROOT_HPP
@@ -28,9 +44,12 @@ constexpr int MAXIT = 60;  ///< Maximum iterations
 /**
  * @brief Newton-Raphson with bisection fallback.
  *
- * @details Finds x in [x1, x2] such that f(x) = 0. Requires f(x1) and f(x2)
- *          to have opposite signs. Uses Newton steps when reliable, falls back
- *          to bisection when Newton would exit the bracket or converge slowly.
+ * @details Finds x in [x1, x2] such that f(x) = 0 — legacy findroot_Newton,
+ *          op for op. The CALLER brackets the root with f(x1) < 0 < f(x2)
+ *          (switch x1 and x2 when f(x1) > f(x2)); nothing is pre-evaluated
+ *          here, so the callback runs in legacy's sequence. Uses Newton
+ *          steps when reliable, falls back to bisection when Newton would
+ *          exit the bracket or converge slowly.
  *
  * @param x1    Left bracket.
  * @param x2    Right bracket.
@@ -50,7 +69,8 @@ int newton(double x1, double x2, double* rts, double xacc, const NewtonFunc& fun
  * @param x2    Right bracket.
  * @param xacc  Convergence tolerance.
  * @param func  Callback: func(x) returns f(x).
- * @returns Root value, or -1.0e10 if failed.
+ * @returns Root value; -1.0e20 when the bracket does not straddle a root
+ *          (legacy findroot_Ridder).
  */
 using RidderFunc = std::function;
 
diff --git a/src/engine/math/MathExpr.cpp b/src/engine/math/MathExpr.cpp
index 7d59e5c08..4eb512e63 100644
--- a/src/engine/math/MathExpr.cpp
+++ b/src/engine/math/MathExpr.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file MathExpr.cpp
  * @brief Shunting-yard parser + stack evaluator.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "MathExpr.hpp"
@@ -64,6 +80,21 @@ static const std::unordered_map func_map = {
     {"acot",  TokenType::FUNC_ACOT},
 };
 
+const std::vector& function_names() {
+    // Ordered by TokenType value (declaration order of the FUNC_* enumerators),
+    // so the list is stable across runs regardless of unordered_map layout.
+    static const std::vector names = [] {
+        std::vector> byType;
+        for (const auto& kv : func_map)
+            byType.emplace_back(static_cast(kv.second), kv.first);
+        std::sort(byType.begin(), byType.end());
+        std::vector out;
+        for (const auto& p : byType) out.push_back(p.second);
+        return out;
+    }();
+    return names;
+}
+
 static std::vector tokenize(const std::string& s) {
     std::vector tokens;
     size_t i = 0;
@@ -287,7 +318,13 @@ int bind_variables(Expression& expr,
     for (auto& tok : expr.postfix) {
         if (tok.type != TokenType::VARIABLE) continue;
         tok.var_idx = -1;
-        // Case-insensitive match against name table
+        // Case-insensitive PREFIX match against the name table, in table order,
+        // taking the first entry that is a prefix of the token — mirroring the
+        // legacy findmatch()/match() used by getVariableIndex (this binder is
+        // GWF-only). So a table name like "KS" binds "Ksat", and "K" binds
+        // anything else starting with K; an exact-only compare left such
+        // legacy-valid tokens unbound (var_idx -1, evaluated as 0). Table order
+        // matters: "KS" precedes "K" so "Ksat" binds to KS, not K.
         for (int v = 0; v < n_vars; ++v) {
             const char* tbl = name_table[v];
             const std::string& tn = tok.var_name;
@@ -300,7 +337,7 @@ int bind_variables(Expression& expr,
                     break;
                 }
             }
-            if (match && k == tn.size() && tbl[k] == '\0') {
+            if (match && tbl[k] == '\0') {  // whole table name is a prefix of the token
                 tok.var_idx = v;
                 ++bound;
                 break;
diff --git a/src/engine/math/MathExpr.hpp b/src/engine/math/MathExpr.hpp
index 384c88f81..1baf25589 100644
--- a/src/engine/math/MathExpr.hpp
+++ b/src/engine/math/MathExpr.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file MathExpr.hpp
  * @brief Mathematical expression parser and evaluator.
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_MATHEXPR_HPP
@@ -98,6 +114,17 @@ struct Expression {
  */
 int parse(const std::string& expr_str, Expression& result);
 
+/**
+ * @brief Names of the built-in functions the tokenizer recognises.
+ *
+ * @details Lower-case, in FUNC_* enumerator order (abs, sgn, sqrt, log, exp,
+ *          sin, cos, tan, asin, acos, atan, step, min, max, cot, sinh, cosh,
+ *          tanh, coth, log10, acot). Single source for editors/validators so
+ *          the list is never duplicated. min and max take two arguments; all
+ *          others take one.
+ */
+const std::vector& function_names();
+
 // ============================================================================
 // Variable binding (Tier 1 optimization)
 // ============================================================================
diff --git a/src/engine/math/OdeSolver.cpp b/src/engine/math/OdeSolver.cpp
index 29b11cdb5..ba25b69f3 100644
--- a/src/engine/math/OdeSolver.cpp
+++ b/src/engine/math/OdeSolver.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OdeSolver.cpp
  * @brief RK45 Cash-Karp ODE integrator — numerically identical to legacy.
@@ -5,12 +21,14 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "OdeSolver.hpp"
 #include 
+#include 
 #include 
+#include 
 #include 
 
 namespace openswmm {
@@ -38,7 +56,14 @@ static constexpr double dc6 = c6 - 0.25;
 //
 // Legacy uses file-scope globals: y[], yscal[], dydx[], yerr[], ytemp[], ak[].
 // We use a thread-local struct to remain reentrant while avoiding per-call
-// heap allocation. open/close match legacy odesolve_open/close.
+// heap allocation. ensureWorkspace() plays the role of legacy odesolve_open();
+// the destructor plays the role of odesolve_close() (legacy runoff.c:135).
+//
+// The destructor must stay declared even though the members are raw pointers:
+// it is what makes the type non-trivially destructible, and only that gets a
+// thread-exit handler registered. Without it, thread exit reclaims the TLS
+// block holding these pointers and strands the buffers they point at, leaking
+// one workspace per thread that ever integrated.
 // ============================================================================
 
 struct OdeWorkspace {
@@ -49,8 +74,26 @@ struct OdeWorkspace {
     double* yerr  = nullptr;
     double* ytemp = nullptr;
     double* ak    = nullptr;   // flat n*5 (ak2..ak6) matching legacy
+
+    ~OdeWorkspace() {
+        std::free(y);     std::free(yscal); std::free(dydx);
+        std::free(yerr);  std::free(ytemp); std::free(ak);
+        // Reset to the constructed state, as legacy odesolve_close() does.
+        // nmax = 0 matters: ensureWorkspace() early-returns while nmax >= n, so
+        // leaving it set would hand freed pointers to any integrate() that ran
+        // after teardown (thread_local destruction order is not guaranteed).
+        y = yscal = dydx = yerr = ytemp = ak = nullptr;
+        nmax = 0;
+    }
 };
 
+// Pins the property the destructor exists for. If it is ever removed or
+// =default'd, the leak returns silently on every platform whose leak checker
+// is unavailable (Darwin arm64 among them) -- fail the build instead.
+static_assert(!std::is_trivially_destructible::value,
+              "OdeWorkspace needs a non-trivial destructor so thread exit frees "
+              "its buffers; see tests/manual/ode_workspace_leak");
+
 static thread_local OdeWorkspace ws_;
 
 static void ensureWorkspace(int n) {
diff --git a/src/engine/math/OdeSolver.hpp b/src/engine/math/OdeSolver.hpp
index 766a916c2..e6b3ef18c 100644
--- a/src/engine/math/OdeSolver.hpp
+++ b/src/engine/math/OdeSolver.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OdeSolver.hpp
  * @brief Runge-Kutta-Cash-Karp (RK45) ODE integrator with adaptive step control.
@@ -20,7 +36,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ODE_SOLVER_HPP
diff --git a/src/engine/math/SIMD.hpp b/src/engine/math/SIMD.hpp
index 01e04837d..3df5d0ed9 100644
--- a/src/engine/math/SIMD.hpp
+++ b/src/engine/math/SIMD.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file SIMD.hpp
  * @brief SIMD abstraction layer for vectorized arithmetic operations.
@@ -28,7 +44,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_SIMD_HPP
diff --git a/src/engine/output/IOThread.cpp b/src/engine/output/IOThread.cpp
index b77895ece..56e81dcde 100644
--- a/src/engine/output/IOThread.cpp
+++ b/src/engine/output/IOThread.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IOThread.cpp
  * @brief IOThread — producer/consumer output writer implementation.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "IOThread.hpp"
@@ -15,6 +31,45 @@
 
 namespace openswmm {
 
+#ifdef __EMSCRIPTEN__
+// ============================================================================
+// WebAssembly: single-threaded build (no -pthread). Run every write task
+// synchronously on the caller's thread; the public contract is unchanged.
+// ============================================================================
+
+IOThread::IOThread(PluginFactory& factory, std::size_t capacity)
+    : factory_(factory)
+    , capacity_(capacity)
+{}
+
+IOThread::~IOThread() {
+    stop();
+}
+
+void IOThread::start() {
+    stop_flag_.store(false, std::memory_order_relaxed);
+    running_.store(true, std::memory_order_relaxed);
+}
+
+void IOThread::post(SimulationSnapshot snap) {
+    if (stop_flag_.load(std::memory_order_relaxed)) return;
+    WriteTask task(std::move(snap), next_sequence_++);
+    const int rc = factory_.update_all(task.snapshot);
+    if (rc != 0) {
+        last_error_.store(rc, std::memory_order_relaxed);
+    }
+    tasks_completed_.fetch_add(1, std::memory_order_relaxed);
+}
+
+void IOThread::stop() {
+    stop_flag_.store(true, std::memory_order_relaxed);
+    running_.store(false, std::memory_order_relaxed);
+}
+
+void IOThread::run() {}
+
+#else
+
 // ============================================================================
 // Constructor / Destructor
 // ============================================================================
@@ -114,4 +169,6 @@ void IOThread::run() {
     running_.store(false, std::memory_order_relaxed);
 }
 
+#endif /* __EMSCRIPTEN__ */
+
 } /* namespace openswmm */
diff --git a/src/engine/output/IOThread.hpp b/src/engine/output/IOThread.hpp
index 7c62cc864..90cd02fde 100644
--- a/src/engine/output/IOThread.hpp
+++ b/src/engine/output/IOThread.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file IOThread.hpp
  * @brief Separate IO writer thread with a bounded task queue (Phase 5, R17).
@@ -35,7 +51,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_IO_THREAD_HPP
diff --git a/src/engine/output/OutputReader.cpp b/src/engine/output/OutputReader.cpp
index 66d4345eb..095633596 100644
--- a/src/engine/output/OutputReader.cpp
+++ b/src/engine/output/OutputReader.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OutputReader.cpp
  * @brief OutputReader — reads SWMM 5.x binary .out files.
@@ -13,10 +29,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "OutputReader.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include 
 #include 
@@ -36,7 +53,7 @@ bool OutputReader::open(const char* path) {
 
     close();  // ensure clean state
 
-    file_ = std::fopen(path, "rb");
+    file_ = openswmm::io::fopen_utf8(path, "rb");
     if (!file_) return false;
 
     // Read footer first (last 6 × int32)
@@ -65,6 +82,83 @@ bool OutputReader::open(const char* path) {
     return true;
 }
 
+bool OutputReader::openLive(const char* path) {
+    if (!path) return false;
+
+    close();
+
+    file_ = openswmm::io::fopen_utf8(path, "rb");
+    if (!file_) return false;
+
+    // No footer yet (or maybe ever): derive every offset the footer would
+    // have supplied by parsing the header forward. The writer lays the
+    // sections down in exactly this order (DefaultOutputPlugin::writeHeader,
+    // legacy output_open): 7-int header, ID lists, pollutant unit codes,
+    // input properties, variable codes, report start date + step, records.
+    if (!readHeader()) { close(); return false; }
+    id_start_pos_ = std::ftell(file_);
+    if (!readIDs()) { close(); return false; }
+    // Pollutant concentration unit codes (one int per pollutant column).
+    if (std::fseek(file_, static_cast(n_polluts_) * static_cast(sizeof(int32_t)),
+                   SEEK_CUR) != 0) { close(); return false; }
+    input_start_pos_ = std::ftell(file_);
+    if (!readVariableCodes()) { close(); return false; }
+    output_start_pos_ = std::ftell(file_);
+
+    bytes_per_period_ = static_cast(sizeof(double))
+        + static_cast(n_subcatch_) * n_subcatch_vars_ * static_cast(sizeof(float))
+        + static_cast(n_nodes_)    * n_node_vars_     * static_cast(sizeof(float))
+        + static_cast(n_links_)    * n_link_vars_     * static_cast(sizeof(float))
+        + static_cast(n_system_vars_)                 * static_cast(sizeof(float));
+
+    live_       = true;
+    error_code_ = 0;
+    n_periods_  = 0;
+    refresh();
+    return true;
+}
+
+int OutputReader::refresh() {
+    if (!file_) return -1;
+    if (!live_) return n_periods_;          // finalised: the footer is authoritative
+
+    // Current size. fseek discards stdio's read buffer, so bytes the writer
+    // appended since the last call are visible on the next read.
+    if (std::fseek(file_, 0, SEEK_END) != 0) return n_periods_;
+    const long size = std::ftell(file_);
+    if (size < 0) return n_periods_;
+
+    // Footer arrived? It is exactly 24 bytes after the last whole record and
+    // repeats output_start_pos_, so a chance magic inside a record can't
+    // masquerade as one.
+    constexpr long kFooterBytes = 6 * static_cast(sizeof(int32_t));
+    if (size >= output_start_pos_ + kFooterBytes &&
+        std::fseek(file_, size - kFooterBytes, SEEK_SET) == 0)
+    {
+        int32_t id_pos = 0, input_pos = 0, output_pos = 0;
+        int32_t periods = 0, err = 0, magic = 0;
+        if (readInt4(id_pos) && readInt4(input_pos) && readInt4(output_pos) &&
+            readInt4(periods) && readInt4(err) && readInt4(magic) &&
+            magic == MAGIC_NUMBER &&
+            static_cast(output_pos) == output_start_pos_ &&
+            output_start_pos_ + static_cast(periods) * bytes_per_period_ + kFooterBytes == size)
+        {
+            n_periods_  = static_cast(periods);
+            error_code_ = static_cast(err);
+            live_       = false;
+            return n_periods_;
+        }
+    }
+
+    // Still being written: count whole records. A partially flushed last
+    // record is simply not counted yet.
+    const long avail = size - output_start_pos_;
+    n_periods_ = (bytes_per_period_ > 0 && avail > 0)
+                     ? static_cast(avail / bytes_per_period_)
+                     : 0;
+    return n_periods_;
+}
+
 void OutputReader::close() {
     if (file_) {
         std::fclose(file_);
@@ -74,6 +168,7 @@ void OutputReader::close() {
     node_ids_.clear();
     link_ids_.clear();
     n_periods_ = 0;
+    live_      = false;
 }
 
 // ============================================================================
@@ -95,6 +190,12 @@ const char* OutputReader::link_id(int index) const {
     return link_ids_[static_cast(index)].c_str();
 }
 
+const char* OutputReader::pollut_id(int index) const {
+    if (index < 0 || static_cast(index) >= pollut_ids_.size())
+        return nullptr;
+    return pollut_ids_[static_cast(index)].c_str();
+}
+
 // ============================================================================
 // Per-period results (all objects, one variable, one period)
 // ============================================================================
@@ -348,6 +449,9 @@ bool OutputReader::readIDs() {
     if (!readIDList(n_subcatch_, subcatch_ids_)) return false;
     if (!readIDList(n_nodes_, node_ids_))        return false;
     if (!readIDList(n_links_, link_ids_))        return false;
+    // The species (pollutant) ID list — emitted by the writer immediately
+    // after the link IDs since the format's inception, but never read.
+    if (!readIDList(n_polluts_, pollut_ids_))    return false;
 
     return true;
 }
diff --git a/src/engine/output/OutputReader.hpp b/src/engine/output/OutputReader.hpp
index 6c4dae618..95bc116f8 100644
--- a/src/engine/output/OutputReader.hpp
+++ b/src/engine/output/OutputReader.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file OutputReader.hpp
  * @brief Internal C++ class for reading SWMM 5.x binary output files.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_OUTPUT_READER_HPP
@@ -51,6 +67,36 @@ class OutputReader {
      */
     bool open(const char* path);
 
+    /**
+     * @brief Open a file that is still being written (no footer yet).
+     *
+     * @details Every offset the footer would supply is derived by parsing
+     *          the header forward, and the period count is derived from the
+     *          file size: `floor((size - output_start) / bytes_per_period)`,
+     *          so a partially flushed last record is never counted. Call
+     *          refresh() to pick up periods appended since. Works on any
+     *          file with a complete header — including one from a run that
+     *          died before writing its footer. Never writes to the file.
+     * @returns true on success (possibly with zero periods yet).
+     */
+    bool openLive(const char* path);
+
+    /**
+     * @brief Re-count periods on a live file.
+     *
+     * @details Re-reads the file size and updates period_count(). When the
+     *          footer has appeared (the run finished) it is adopted — period
+     *          count and error code become the writer's own — and the reader
+     *          leaves live mode; subsequent calls are no-ops. On a reader
+     *          opened with open() this returns period_count() unchanged.
+     * @returns the current period count, or -1 if no file is open.
+     */
+    int refresh();
+
+    /** @brief True while opened via openLive() and the footer has not yet
+     *  been seen. */
+    bool is_live() const noexcept { return live_; }
+
     /**
      * @brief Close the file and release resources.
      */
@@ -83,6 +129,21 @@ class OutputReader {
     const char* node_id(int index)     const;
     const char* link_id(int index)     const;
 
+    /**
+     * @brief Species (pollutant) ID at a column index, or nullptr.
+     *
+     * @details The writer has always emitted a fourth ID list after the
+     *          link IDs — the species names, one per pollutant column —
+     *          but the reader stopped after three and no public entry
+     *          point exposed them. Water age reports as a trailing
+     *          `__WATER_AGE__` column whose unit field necessarily reuses
+     *          a concentration code (the `.out` unit enum has no HOURS
+     *          slot), so the NAME is the only way a consumer can tell
+     *          hours from mg/L. That made this reader a prerequisite for
+     *          water age being usable at all, not a convenience.
+     */
+    const char* pollut_id(int index)   const;
+
     // -- Per-period results (all objects, one variable) --------------------
 
     /** @brief Read one subcatch variable for all subcatchments at a period.
@@ -181,10 +242,14 @@ class OutputReader {
     // Computed: bytes per period record
     long bytes_per_period_ = 0;
 
+    // openLive(): period count comes from the file size until the footer lands
+    bool live_ = false;
+
     // Object IDs
     std::vector subcatch_ids_;
     std::vector node_ids_;
     std::vector link_ids_;
+    std::vector pollut_ids_;
 
     // -- Helpers ----------------------------------------------------------
 
diff --git a/src/engine/output/WriteTask.hpp b/src/engine/output/WriteTask.hpp
index 0b7a5037c..49d3c6ea0 100644
--- a/src/engine/output/WriteTask.hpp
+++ b/src/engine/output/WriteTask.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file WriteTask.hpp
  * @brief Ring-buffer task descriptor for the IO thread (Phase 5, R17).
@@ -16,7 +32,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_WRITE_TASK_HPP
diff --git a/src/engine/output/openswmm_output_impl.cpp b/src/engine/output/openswmm_output_impl.cpp
index ad3101ad8..87d39f7e3 100644
--- a/src/engine/output/openswmm_output_impl.cpp
+++ b/src/engine/output/openswmm_output_impl.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file openswmm_output_impl.cpp
  * @brief C FFI wrapper for the OutputReader class.
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../../../include/openswmm/engine/openswmm_output.h"
@@ -41,6 +57,30 @@ SWMM_ENGINE_API SWMM_Output swmm_output_open(const char* path) {
     return static_cast(reader);
 }
 
+SWMM_ENGINE_API SWMM_Output swmm_output_open_live(const char* path) {
+    if (!path) return nullptr;
+    auto* reader = new (std::nothrow) openswmm::OutputReader();
+    if (!reader) return nullptr;
+    if (!reader->openLive(path)) {
+        delete reader;
+        return nullptr;
+    }
+    return static_cast(reader);
+}
+
+SWMM_ENGINE_API int swmm_output_refresh(SWMM_Output handle, int* periods) {
+    CHECK_READER(handle);
+    const int n = to_reader(handle)->refresh();
+    if (n < 0) return -1;
+    if (periods) *periods = n;
+    return 0;
+}
+
+SWMM_ENGINE_API int swmm_output_is_live(SWMM_Output handle) {
+    if (!handle) return -1;
+    return to_reader(handle)->is_live() ? 1 : 0;
+}
+
 SWMM_ENGINE_API void swmm_output_close(SWMM_Output handle) {
     if (!handle) return;
     auto* reader = to_reader(handle);
@@ -122,6 +162,12 @@ SWMM_ENGINE_API const char* swmm_output_get_link_id(SWMM_Output handle,
     return to_reader(handle)->link_id(index);
 }
 
+SWMM_ENGINE_API const char* swmm_output_get_pollut_id(SWMM_Output handle,
+                                                       int index) {
+    if (!handle) return nullptr;
+    return to_reader(handle)->pollut_id(index);
+}
+
 /* =========================================================================
  * Per-period result retrieval
  * ========================================================================= */
diff --git a/src/engine/plugins/BuiltinPluginInfos.cpp b/src/engine/plugins/BuiltinPluginInfos.cpp
index 19722f745..bcbc31a46 100644
--- a/src/engine/plugins/BuiltinPluginInfos.cpp
+++ b/src/engine/plugins/BuiltinPluginInfos.cpp
@@ -1,10 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file BuiltinPluginInfos.cpp
  * @brief Singletons + file_filters() implementations for built-in plugins.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "BuiltinPluginInfos.hpp"
diff --git a/src/engine/plugins/BuiltinPluginInfos.hpp b/src/engine/plugins/BuiltinPluginInfos.hpp
index d34a6c5b1..7038a2aae 100644
--- a/src/engine/plugins/BuiltinPluginInfos.hpp
+++ b/src/engine/plugins/BuiltinPluginInfos.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file BuiltinPluginInfos.hpp
  * @brief IPluginComponentInfo singletons for the engine's built-in default plugins.
@@ -15,7 +31,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_BUILTIN_PLUGIN_INFOS_HPP
@@ -37,8 +53,8 @@ class BuiltinDefaultInputPluginInfo final : public IPluginComponentInfo {
     std::string version()      const override { return "1.0.0"; }
     std::string vendor()       const override { return "HydroCouple"; }
     std::string url()          const override { return "https://hydrocouple.org"; }
-    std::string license_type() const override { return "MIT"; }
-    std::string license_text() const override { return "MIT License"; }
+    std::string license_type() const override { return "Apache-2.0"; }
+    std::string license_text() const override { return "Apache License, Version 2.0"; }
 
     bool has_input()  const noexcept override { return true; }
 
@@ -57,8 +73,8 @@ class BuiltinDefaultOutputPluginInfo final : public IPluginComponentInfo {
     std::string version()      const override { return "1.0.0"; }
     std::string vendor()       const override { return "HydroCouple"; }
     std::string url()          const override { return "https://hydrocouple.org"; }
-    std::string license_type() const override { return "MIT"; }
-    std::string license_text() const override { return "MIT License"; }
+    std::string license_type() const override { return "Apache-2.0"; }
+    std::string license_text() const override { return "Apache License, Version 2.0"; }
 
     bool has_output() const noexcept override { return true; }
 
@@ -77,8 +93,8 @@ class BuiltinDefaultReportPluginInfo final : public IPluginComponentInfo {
     std::string version()      const override { return "1.0.0"; }
     std::string vendor()       const override { return "HydroCouple"; }
     std::string url()          const override { return "https://hydrocouple.org"; }
-    std::string license_type() const override { return "MIT"; }
-    std::string license_text() const override { return "MIT License"; }
+    std::string license_type() const override { return "Apache-2.0"; }
+    std::string license_text() const override { return "Apache License, Version 2.0"; }
 
     bool has_report() const noexcept override { return true; }
 
@@ -98,8 +114,8 @@ class BuiltinDefaultStateIOPluginInfo final : public IPluginComponentInfo {
     std::string version()      const override { return "1.0.0"; }
     std::string vendor()       const override { return "HydroCouple"; }
     std::string url()          const override { return "https://hydrocouple.org"; }
-    std::string license_type() const override { return "MIT"; }
-    std::string license_text() const override { return "MIT License"; }
+    std::string license_type() const override { return "Apache-2.0"; }
+    std::string license_text() const override { return "Apache License, Version 2.0"; }
 
     bool has_state_io() const noexcept override { return true; }
 
diff --git a/src/engine/plugins/DefaultInputPlugin.cpp b/src/engine/plugins/DefaultInputPlugin.cpp
index c7b53bd3d..cda9b114a 100644
--- a/src/engine/plugins/DefaultInputPlugin.cpp
+++ b/src/engine/plugins/DefaultInputPlugin.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultInputPlugin.cpp
  * @brief DefaultInputPlugin — reads/writes SWMM .inp files.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DefaultInputPlugin.hpp"
@@ -27,6 +43,8 @@
 #include "../input/handlers/UserFlagsHandler.hpp"
 #include "../input/handlers/UserFlagValuesHandler.hpp"
 #include "../input/handlers/PluginsHandler.hpp"
+#include "../input/handlers/ProcessComponentsHandler.hpp"
+#include "../transport/components/ReactionModule/ReactionsComponent.hpp"
 #include "../input/handlers/FilesHandler.hpp"
 #include "../input/handlers/InflowsHandler.hpp"
 #include "../input/handlers/QualityHandler.hpp"
@@ -59,6 +77,7 @@ void DefaultInputPlugin::register_builtin_handlers() {
     // Node sections
     registry_.register_builtin("JUNCTIONS",    input::handle_junctions);
     registry_.register_builtin("VIRTUAL_JUNCTIONS", input::handle_virtual_junctions);
+    registry_.register_builtin("INLET_JUNCTIONS", input::handle_inlet_junctions);
     registry_.register_builtin("OUTFALLS",     input::handle_outfalls);
     registry_.register_builtin("DIVIDERS",     input::handle_dividers);
     registry_.register_builtin("STORAGE",      input::handle_storage);
@@ -110,6 +129,7 @@ void DefaultInputPlugin::register_builtin_handlers() {
     registry_.register_builtin("BUILDUP",       input::handle_buildup);
     registry_.register_builtin("WASHOFF",       input::handle_washoff);
     registry_.register_builtin("TREATMENT",     input::handle_treatment);
+    registry_.register_builtin("INITIAL_QUALITY", input::handle_initial_quality);
 
     // Control / map / reporting
     registry_.register_builtin("CONTROLS",      input::handle_controls);
@@ -135,6 +155,19 @@ void DefaultInputPlugin::register_builtin_handlers() {
     registry_.register_builtin("USER_FLAGS",       input::handle_user_flags);
     registry_.register_builtin("USER_FLAG_VALUES", input::handle_user_flag_values);
     registry_.register_builtin("PLUGINS",          input::handle_plugins);
+    registry_.register_builtin("PROCESS_COMPONENTS",
+                               input::handle_process_components);
+
+    // Embedded component sections (D-UT8 fallback): [REACTION_*] in the
+    // legacy .inp are captured verbatim and consumed after component
+    // resolution (style warning; external config file wins on conflict).
+    for (const auto& tag : transport::reactionSectionTags()) {
+        registry_.register_builtin(tag,
+            [tag](SimulationContext& ctx,
+                  const std::vector& lines) {
+                ctx.embedded_component_sections.emplace_back(tag, lines);
+            });
+    }
 }
 
 // ============================================================================
@@ -168,10 +201,30 @@ int DefaultInputPlugin::read(const std::string& path, SimulationContext& ctx) {
 }
 
 int DefaultInputPlugin::write(const std::string& path, const SimulationContext& ctx) {
-    int err = inp_writer::writeInpFile(ctx, path);
+    // The writer's warning sink is optional and this caller used to pass
+    // nullptr, which is half of why the "embedded [REACTION_*] sections are
+    // lost from this save" notice never reached a user (2026-08-26). The
+    // other two callers forward into ctx.warnings; this one cannot — the
+    // plugin interface hands it a CONST context by design — so the notice
+    // goes to the plugin's own diagnostic channel instead.
+    //
+    // ⚠ On a SUCCESSFUL write `last_error_message()` is not conventionally
+    // read, so a caller driving the engine through this interface can still
+    // miss it. That is a real residual gap, recorded rather than papered
+    // over: closing it needs a non-error diagnostic channel on IInputPlugin,
+    // which is an interface change and not this round's.
+    std::vector warns;
+    int err = inp_writer::writeInpFile(ctx, path, &warns);
     if (err != 0) {
         last_error_ = "Failed to write .inp file: " + path;
+        // Losing model data is worth saying even while reporting the failure.
+        for (const auto& w : warns) last_error_ += "\n" + w;
     }
+    // On SUCCESS the warnings are collected and deliberately NOT written to
+    // last_error_. Putting a non-error in an error channel is worse than the
+    // silence it replaces: a caller that checks last_error_message() after a
+    // successful write would read a warning as a failure. The first draft of
+    // this hunk did exactly that and it was wrong.
     return err;
 }
 
diff --git a/src/engine/plugins/DefaultInputPlugin.hpp b/src/engine/plugins/DefaultInputPlugin.hpp
index 63d056aa0..58eaa6274 100644
--- a/src/engine/plugins/DefaultInputPlugin.hpp
+++ b/src/engine/plugins/DefaultInputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultInputPlugin.hpp
  * @brief DefaultInputPlugin — reads/writes SWMM .inp files.
@@ -10,7 +26,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DEFAULT_INPUT_PLUGIN_HPP
diff --git a/src/engine/plugins/DefaultOutputPlugin.cpp b/src/engine/plugins/DefaultOutputPlugin.cpp
index 63e484898..d0c8a92a5 100644
--- a/src/engine/plugins/DefaultOutputPlugin.cpp
+++ b/src/engine/plugins/DefaultOutputPlugin.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultOutputPlugin.cpp
  * @brief DefaultOutputPlugin — SWMM 5.x binary .out file writer.
@@ -17,10 +33,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DefaultOutputPlugin.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 #include "../../../include/openswmm/plugin_sdk/PluginState.hpp"
 #include "../../../include/openswmm/plugin_sdk/SimulationSnapshot.hpp"
 #include "../core/SimulationContext.hpp"
@@ -49,21 +66,38 @@ int DefaultOutputPlugin::validate(const SimulationContext& /*ctx*/) {
     return 0;
 }
 
+namespace {
+/// Output-stream buffer size. 1 MB: large enough that a 500k-element
+/// header is a handful of writes, small enough to be irrelevant next to
+/// the model itself.
+constexpr std::size_t kOutputBufferBytes = 1u << 20;
+}  // namespace
+
 int DefaultOutputPlugin::prepare(const SimulationContext& ctx) {
     // Open binary output file
-    out_file_ = std::fopen(out_path_.c_str(), "w+b");
+    out_file_ = openswmm::io::fopen_utf8(out_path_, "w+b");
     if (!out_file_) {
         last_error_ = "Cannot open output file: " + out_path_;
         return -1;
     }
 
+    // Every scalar in the header and in every report period is its own fwrite —
+    // writeInt4/writeReal4/writeReal8 below — so a 500k-element model issues
+    // millions of calls, each taking the FILE lock and testing the buffer. The
+    // default buffer is a few kilobytes; a 1 MB one cuts the flush count by
+    // orders of magnitude for the cost of one allocation. Must be set before
+    // any I/O on the stream, which is why it sits immediately after fopen.
+    //
+    // Failure is not an error: setvbuf declining just leaves the default
+    // buffer, and the file is still perfectly writable.
+    std::setvbuf(out_file_, nullptr, _IOFBF, kOutputBufferBytes);
+
     // Per-timestep results arrive pre-converted to display units (engine
     // boundary). Only the static-object header below is written from the
     // SimulationContext (internal units), so retain just the length / land-area
     // factors it needs.
     flow_units_code_ = static_cast(ctx.options.flow_units);
     ucf_length_      = ucf::UCF(ucf::LENGTH,   ctx.options);
-    ucf_landarea_    = ucf::UCF(ucf::LANDAREA, ctx.options);
 
     // Write header
     writeHeader(ctx);
@@ -175,6 +209,12 @@ int DefaultOutputPlugin::update(const SimulationSnapshot& snapshot) {
 
     std::fwrite(sys, sizeof(float), MAX_SYS_RESULTS, out_file_);
 
+    // Push the completed period to disk so a live reader (OutputReader::
+    // openLive / swmm_output_open_live) can count it from the file size.
+    // Runs on the IO thread; one write(2) per report step. The 1 MB stdio
+    // buffer still batches the per-element fwrites inside the period.
+    std::fflush(out_file_);
+
     ++n_periods_;
     ++step_count_;
     return 0;
@@ -219,7 +259,13 @@ void DefaultOutputPlugin::writeHeader(const SimulationContext& ctx) {
     for (const auto& f : link_rpt_flag_) if (f) ++n_links_;
     // IGNORE_QUALITY: drop all pollutant columns from the binary .out file so
     // OutputReader reads zero pollutants (legacy output.c:150 NumPolluts = 0).
-    n_polluts_ = ctx.options.ignore_quality ? 0 : ctx.n_pollutants();
+    // A2b: the pollutant column block reports pollutants AND, when
+    // [OPTIONS] WATER_AGE is on, a trailing __WATER_AGE__ pseudo-column.
+    // ctx.reported_species_names is the single naming/count truth shared
+    // with the snapshot builder (which strides its quality vectors by the
+    // same number) — striding by n_pollutants() here would truncate the
+    // block and misalign every consumer.
+    n_polluts_ = ctx.options.ignore_quality ? 0 : ctx.n_reported_species();
 
     n_subcatch_vars_ = 8 + n_polluts_;  // rainfall..soilmoist + pollutants
     n_node_vars_ = 6 + n_polluts_;      // depth..overflow + pollutants
@@ -252,24 +298,48 @@ void DefaultOutputPlugin::writeHeader(const SimulationContext& ctx) {
             writeID(ctx.link_names.name_of(j).c_str());
     }
     for (int p = 0; p < n_polluts_; ++p)
-        writeID(ctx.pollutant_names.name_of(p).c_str());
+        writeID(ctx.reported_species_names[static_cast(p)]
+                    .c_str());
 
     // Pollutant concentration unit codes
     for (int p = 0; p < n_polluts_; ++p) {
-        writeInt4(static_cast(ctx.pollutants.units[static_cast(p)]));
+        // A RESERVED pseudo-column has no MassUnits member: water age is
+        // HOURS, temperature is degC, and the .out unit field is a 3-value
+        // concentration enum with no slot for either. Those columns write
+        // MG_PER_L's code and readers key on the NAME
+        // (swmm_output_get_pollut_id), not the unit code — a format decision
+        // rather than widening the enum, which would break every existing
+        // reader.
+        //
+        // Keyed on the INDEX, not on the name. reported_species_names is
+        // pollutants first, then the reserved rows, so anything at or past
+        // n_pollutants() has no entry in ctx.pollutants.units. Testing for
+        // "__WATER_AGE__" by name got this right only while age was the sole
+        // reserved species: adding __TEMPERATURE__ sent the unit lookup off
+        // the end of an EMPTY units vector on a heat-only deck (no
+        // [POLLUTANTS]) and segfaulted the writer.
+        const bool is_reserved = (p >= ctx.n_pollutants());
+        writeInt4(is_reserved
+                      ? 0
+                      : static_cast(
+                            ctx.pollutants.units[static_cast(p)]));
     }
 
     // Input data start
     input_start_pos_ = std::ftell(out_file_);
 
-    // Subcatchment input: area (converting to display units)
+    // Subcatchment input: area, in display units (acres / hectares).
+    // Legacy output.c:245-252 writes `Subcatch[j].area * UCF(LANDAREA)`
+    // because legacy stores the area in ft2. v6 stores it in DISPLAY units
+    // already — CatchmentHandler.cpp:159 keeps the [SUBCATCHMENTS] token
+    // verbatim, and every other consumer multiplies by ACRES_TO_FT2 to get
+    // ft2 — so applying UCF(LANDAREA) here divided every area by 43560.
     writeInt4(1);
     writeInt4(1);  // INPUT_AREA code
     for (int j = 0; j < ctx.n_subcatches(); ++j) {
         auto uj = static_cast(j);
         if (uj >= subcatch_rpt_flag_.size() || !subcatch_rpt_flag_[uj]) continue;
-        writeReal4(static_cast(
-            ctx.subcatches.area[uj] * ucf_landarea_));
+        writeReal4(static_cast(ctx.subcatches.area[uj]));
     }
 
     // Node input: type, invert, max depth
diff --git a/src/engine/plugins/DefaultOutputPlugin.hpp b/src/engine/plugins/DefaultOutputPlugin.hpp
index d349cb9bb..9eefdb774 100644
--- a/src/engine/plugins/DefaultOutputPlugin.hpp
+++ b/src/engine/plugins/DefaultOutputPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultOutputPlugin.hpp
  * @brief Built-in output plugin that writes the legacy SWMM binary output format.
@@ -17,7 +33,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DEFAULT_OUTPUT_PLUGIN_HPP
@@ -91,10 +107,11 @@ class DefaultOutputPlugin final : public IOutputPlugin {
     int                 n_periods_  = 0;
 
     // Static-object header is written from the SimulationContext (internal
-    // units), so it still needs these two factors. Per-timestep results arrive
-    // pre-converted by the engine boundary and need no plugin-side conversion.
+    // units), so it still needs this length factor. Subcatchment area is
+    // already held in display units and needs none. Per-timestep results
+    // arrive pre-converted by the engine boundary and need no plugin-side
+    // conversion.
     double ucf_length_    = 1.0;
-    double ucf_landarea_  = 1.0;
 
     // Per-object report flags, captured during prepare() from SimulationContext
     std::vector subcatch_rpt_flag_;
diff --git a/src/engine/plugins/DefaultReportPlugin.cpp b/src/engine/plugins/DefaultReportPlugin.cpp
index 29016da08..ad66ea132 100644
--- a/src/engine/plugins/DefaultReportPlugin.cpp
+++ b/src/engine/plugins/DefaultReportPlugin.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultReportPlugin.cpp
  * @brief DefaultReportPlugin — legacy SWMM-compatible .rpt report writer.
@@ -11,10 +27,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DefaultReportPlugin.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../../../include/openswmm/plugin_sdk/PluginState.hpp"
 #include "../../../include/openswmm/plugin_sdk/SimulationSnapshot.hpp"
@@ -22,13 +39,23 @@
 #include "../core/UnitConversion.hpp"
 #include "../core/DateTime.hpp"
 #include "../hydraulics/Node.hpp"   // node::getVolume — storage volume from its depth-relation
+#include "../hydraulics/Link.hpp"       // link::buildXSectParams — street spread at max depth
+#include "../hydraulics/XSectBatch.hpp" // xsect::getWofY
+#include "../transport/TransportPolicy.hpp"   // E2: Domain x Species matrix block
+#include "../2d/quality/SurfaceQuality2D.hpp"   // S7: 2D Surface Washoff Summary
+#include "../2d/data/MeshData.hpp"
+#include "../2d/subsurface/SubsurfaceData.hpp"   // G-O: 2D Aquifer Continuity
+#include "../2d/subsurface/SubsurfaceTransportState.hpp"  // T7.5: its quality twin
 
 #include 
 
 #include 
+#include 
+#include 
 #include 
 #include 
 #include 
+#include 
 #include 
 
 namespace openswmm {
@@ -41,7 +68,7 @@ static const char* InfilModelWords[] = {
     "HORTON", "MODIFIED_HORTON", "GREEN_AMPT",
     "MODIFIED_GREEN_AMPT", "CURVE_NUMBER"
 };
-static const char* SurchargeWords[] = { "EXTRAN", "SLOT", "DYNAMIC_SLOT" };
+static const char* SurchargeWords[] = { "EXTRAN", "SLOT", "DYNAMIC_SLOT", "TPA" };
 static const char* NodeTypeWords[] = { "JUNCTION", "OUTFALL", "DIVIDER", "STORAGE" };
 static const char* LinkTypeWords[] = { "CONDUIT", "PUMP", "ORIFICE", "WEIR", "OUTLET" };
 static const char* RainTypeWords[] = { "INTENSITY", "VOLUME", "CUMULATIVE" };
@@ -153,13 +180,11 @@ int DefaultReportPlugin::validate(const SimulationContext& /*ctx*/) {
 }
 
 int DefaultReportPlugin::prepare(const SimulationContext& ctx) {
-    std::time(&wall_start_);
-
     // Open the report file early and write preamble (title, input summaries,
     // analysis options) so they are available immediately — even if the
     // simulation crashes before write_summary() is called.
     if (!rpt_path_.empty() && !ctx.options.rpt_disabled) {
-        file_ = std::fopen(rpt_path_.c_str(), "w");
+        file_ = openswmm::io::fopen_utf8(rpt_path_, "w");
         if (file_) {
             write_preamble(file_, ctx);
             std::fflush(file_);
@@ -207,7 +232,7 @@ int DefaultReportPlugin::write_summary(const SimulationContext& ctx) {
     if (!f) {
         // Fallback: prepare() was not called or file open failed.
         // Write the entire report monolithically.
-        f = std::fopen(rpt_path_.c_str(), "w");
+        f = openswmm::io::fopen_utf8(rpt_path_, "w");
         if (!f) return -1;
         write_preamble(f, ctx);
 
@@ -222,7 +247,7 @@ int DefaultReportPlugin::write_summary(const SimulationContext& ctx) {
     write_results(f, ctx);
 
     // Write analysis timing and close
-    write_timing(f);
+    write_timing(f, ctx);
 
     std::fclose(f);
     file_ = nullptr;
@@ -375,6 +400,20 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
         std::fprintf(f,
             "\n  -------------------------------------------------------------------------------");
 
+        // Which nodes carry an inflow, resolved in one pass over the inflow
+        // rows instead of a scan of both row sets per node. The old form was
+        // O(n_nodes x n_inflow_rows) — around 10^10 comparisons on a model
+        // with 100k nodes and 100k inflows, all of it inside the report.
+        std::vector has_inflow(
+            static_cast(ctx.n_nodes()), 0u);
+        auto mark = [&](const std::vector& node_idx) {
+            for (const int n : node_idx)
+                if (n >= 0 && n < ctx.n_nodes())
+                    has_inflow[static_cast(n)] = 1u;
+        };
+        mark(ctx.ext_inflows.node_idx);
+        mark(ctx.dwf_inflows.node_idx);
+
         for (int i = 0; i < ctx.n_nodes(); ++i) {
             auto ui = static_cast(i);
             int nt = static_cast(ctx.nodes.type[ui]);
@@ -384,13 +423,7 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
                 ctx.nodes.invert_elev[ui],
                 ctx.nodes.full_depth[ui],
                 ctx.nodes.ponded_area[ui]);
-            // Check for external inflow
-            bool has_ext = false;
-            for (std::size_t k = 0; k < ctx.ext_inflows.node_idx.size(); ++k)
-                if (ctx.ext_inflows.node_idx[k] == i) { has_ext = true; break; }
-            for (std::size_t k = 0; !has_ext && k < ctx.dwf_inflows.node_idx.size(); ++k)
-                if (ctx.dwf_inflows.node_idx[k] == i) { has_ext = true; break; }
-            if (has_ext) std::fprintf(f, "    Yes");
+            if (has_inflow[ui] != 0u) std::fprintf(f, "    Yes");
         }
         WRITE(f, "");
         WRITE(f, "");
@@ -421,11 +454,21 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
             if (lt == static_cast(LinkType::CONDUIT)) {
                 const int cr = ctx.link_subtypes.conduit_row(i);
                 const auto& CD = ctx.link_subtypes.conduits;
+                // Legacy prints Conduit.roughness, which conduit_validate has
+                // replaced by the transect's channel n for an IRREGULAR
+                // conduit (link.c:1024); the stored value here stays authored.
+                double n_rep = (cr >= 0) ? CD.roughness[static_cast(cr)] : 0.01;
+                if (cr >= 0 && ctx.links.xsect_shape[static_cast(i)] == XsectShape::IRREGULAR) {
+                    const int ti = ctx.links.xsect_curve[static_cast(i)];
+                    if (ti >= 0 && static_cast(ti) < ctx.transects.n_channel.size() &&
+                        ctx.transects.n_channel[static_cast(ti)] > 0.0)
+                        n_rep = ctx.transects.n_channel[static_cast(ti)];
+                }
                 std::fprintf(f, "%-12s%10.1f%10.4f%10.4f",
                     "CONDUIT",
                     (cr >= 0) ? CD.length[static_cast(cr)] : 0.0,
                     ((cr >= 0) ? CD.slope[static_cast(cr)] : 0.0) * 100.0,
-                    (cr >= 0) ? CD.roughness[static_cast(cr)] : 0.01);
+                    n_rep);
             } else {
                 std::fprintf(f, "%-12s", lt_str(lt));
             }
@@ -517,6 +560,17 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
     std::fprintf(f, "\n    Water Quality .......... %s",
                  (ctx.n_pollutants() > 0 && !opt.ignore_quality) ? "YES" : "NO");
 
+    // E2 — the Domain x Species transport matrix (TransportPolicy), printed
+    // only when the project declares some species class at all, so a
+    // hydraulics-only report is unchanged. Answers "why is there no 2D
+    // quality" in the report itself.
+    if (ctx.n_pollutants() > 0 || ctx.options.water_age ||
+        ctx.options.heat_transport ||
+        (ctx.reactions.configured && ctx.reactions.compiled)) {
+        const auto matrix = openswmm::transport::resolve(ctx);
+        std::fprintf(f, "\n%s", openswmm::transport::formatReportBlock(matrix).c_str());
+    }
+
     if (ctx.n_subcatches() > 0) {
         int im = static_cast(opt.infiltration);
         if (im < 0 || im > 4) im = 0;
@@ -531,9 +585,20 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
                                         : "STEADY";
         std::fprintf(f, "\n  Flow Routing Method ...... %s", rm_name);
 
+        // TPA pressure closure (issue #156 Phase 4): FV, non-default only.
+        if (rm == 3 && opt.fv.pressure_closure == 1) {
+            std::fprintf(f, "\n  Pressure Closure ......... TPA");
+        }
+
+        // Unsteady friction (issue #156): applies to DW and FV alike.
+        if ((rm == 2 || rm == 3) && opt.unsteady_friction != 0) {
+            std::fprintf(f, "\n  Unsteady Friction ........ VITKOVSKY (k3 = %g)",
+                         opt.uf_k3);
+        }
+
         if (rm == 2) { // DYNWAVE
             int sm = opt.surcharge_method;
-            const char* sm_name = (sm >= 0 && sm <= 2) ? SurchargeWords[sm] : "EXTRAN";
+            const char* sm_name = (sm >= 0 && sm <= 3) ? SurchargeWords[sm] : "EXTRAN";
             std::fprintf(f, "\n  Surcharge Method ......... %s", sm_name);
             const char* nc_name = (opt.node_continuity == NodeContinuity::SEMI_IMPLICIT)
                                   ? "SEMI_IMPLICIT" : "EXPLICIT";
@@ -571,7 +636,8 @@ void DefaultReportPlugin::write_preamble(std::FILE* f,
                          opt.variable_step > 0.0 ? "YES" : "NO");
             std::fprintf(f, "\n  Maximum Trials ........... %d", opt.max_trials);
             std::fprintf(f, "\n  Number of Threads ........ %d", opt.num_threads);
-            std::fprintf(f, "\n  Head Tolerance ........... %f ft", opt.head_tol);
+            std::fprintf(f, "\n  Head Tolerance ........... %f ft",
+                         opt.head_tol == 0.0 ? 0.005 : opt.head_tol);
         }
     }
 
@@ -665,10 +731,42 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             std::fprintf(f, "\n  %s%14.3f%14.3f", label, af, depth_in);
         };
 
+        // F8 — the three snow rows the ledger never had. Guarded on the
+        // project having snowpacks at all, matching legacy's
+        // `Nobjects[SNOWMELT] > 0` (report.c:519, 560) rather than on the
+        // values being nonzero: a deck WITH packs that shows 0.000 here is
+        // saying something, and a deck without them should not carry the
+        // rows at all. Row ORDER matches legacy exactly, because these
+        // tables are read side by side against EPA SWMM output.
+        //
+        // The existing "Initial Storage" label is LEFT ALONE even though
+        // legacy calls the same row "Initial LID Storage". Renaming it is not
+        // part of this defect, and the 14-deck corpus compares report bytes —
+        // a label change would move decks that have nothing to do with snow
+        // and buy nothing. Recorded here so the difference is a decision
+        // rather than an oversight.
+        const bool has_snow = ctx.snowpack_names.size() > 0;
+
+        if (mb.runoff_init_store > 0.0)
+            row("Initial Storage ..........", mb.runoff_init_store);
+        if (has_snow)
+            row("Initial Snow Cover .......", mb.runoff_init_snow);
         row("Total Precipitation ......", mb.runoff_rainfall);
+        if (mb.runoff_runon > 0.0)
+            row("Outfall Runon ............", mb.runoff_runon);
         row("Evaporation Loss .........", mb.runoff_evap);
         row("Infiltration Loss ........", mb.runoff_infil);
         row("Surface Runoff ...........", mb.runoff_runoff);
+        // Legacy prints this row whenever the model has LID area
+        // (report.c:551); the plugin sees only the ledger, so it prints
+        // whenever the term is live — a deck with LIDs but zero drain
+        // outflow omits a 0.000 row legacy would show.
+        if (mb.runoff_lid_drain != 0.0)
+            row("LID Drainage .............", mb.runoff_lid_drain);
+        if (has_snow) {
+            row("Snow Removed .............", mb.runoff_snowremov);
+            row("Final Snow Cover .........", mb.runoff_final_snow);
+        }
         row("Final Storage ............", mb.runoff_final_store);
 
         std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f", mb.runoff_error() * 100.0);
@@ -726,8 +824,21 @@ void DefaultReportPlugin::write_results(std::FILE* f,
 
             double total_in  = init_bu + surf_bu + wet_dep;
             double total_out = sweep + bmp + infil + runoff + final_bu;
-            double err_pct = (total_in > 0.0) ?
-                (total_in - total_out) / total_in * 100.0 : 0.0;
+            // Legacy's THREE branches (massbal.c:900-911). The third is the
+            // one this site lacked, and this is the site the user reads: the
+            // 2026-08-23 API fix landed in swmm_get_quality_continuity_error
+            // and left the printed row on the two-branch form, so a deck
+            // that discharged mass it never received still printed 0.000 --
+            // which is the exact symptom Finding 10 was raised on.
+            double err_pct;
+            if (std::fabs(total_in - total_out) < 0.001)
+                err_pct = 0.0;
+            else if (total_in > 0.0)
+                err_pct = (total_in - total_out) / total_in * 100.0;
+            else if (total_out > 0.0)
+                err_pct = (total_in - total_out) / total_out * 100.0;
+            else
+                err_pct = 0.0;
             std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f", err_pct);
 
             WRITE(f, "");
@@ -770,6 +881,12 @@ void DefaultReportPlugin::write_results(std::FILE* f,
 
         gwRow("Initial Storage ..........", mb.gw_init_storage);
         gwRow("Infiltration .............", mb.gw_infil);
+        // U3 (track I-b): the 2D surface's share of that infiltration, named
+        // so a user can see the cross-domain transfer. Printed only when a
+        // deck actually routes it (INFIL_DESTINATION SUBCATCH_AQUIFER); it
+        // is INSIDE the Infiltration row above, not a second inflow.
+        if (mb.gw_infil_2d_recharge != 0.0)
+            gwRow("  of which from 2D .......", mb.gw_infil_2d_recharge);
         gwRow("Upper Zone ET ............", mb.gw_upper_evap);
         gwRow("Lower Zone ET ............", mb.gw_lower_evap);
         gwRow("Deep Percolation .........", mb.gw_lower_perc);
@@ -816,15 +933,37 @@ void DefaultReportPlugin::write_results(std::FILE* f,
         row("Dry Weather Inflow .......", mb.routing_dry_weather);
         row("Wet Weather Inflow .......", mb.routing_wet_weather);
         row("Groundwater Inflow .......", mb.routing_gw_inflow);
+        // G-X4: a gaining reach — the two-zone aquifer feeding a conduit that
+        // runs below the water table. Printed only when non-zero, so every
+        // deck without the signed conduit exchange keeps its report
+        // line-for-line.
+        if (mb.routing_link_gw_inflow != 0.0)
+            row("Conduit GW Inflow ........", mb.routing_link_gw_inflow);
         row("RDII Inflow ..............", mb.routing_rdii);
         row("External Inflow ..........", mb.routing_external);
         row("External Outflow .........", mb.routing_outflow);
         row("Flooding Loss ............", mb.routing_flooding);
+        // C2: the 1D→2D coupling spill, split out of Flooding Loss. Printed
+        // only when non-zero so an uncoupled model's report is unchanged
+        // line-for-line. (COUPLING_IN_FLOODING YES puts it back in the row
+        // above and leaves this one at zero, hence hidden.)
+        if (mb.routing_coupling_out != 0.0)
+            row("2D Coupling Outflow ......", mb.routing_coupling_out);
         row("Evaporation Loss .........", mb.routing_evap_loss);
         row("Exfiltration Loss ........", mb.routing_seep_loss);
         row("Initial Stored Volume ....", mb.routing_init_storage);
         row("Final Stored Volume ......", mb.routing_final_storage);
 
+        // FV only (slot_volume stays 0.0 under DW): the share of Final
+        // Stored Volume standing in the Preissmann slot. Informational —
+        // already inside Final Stored Volume, never added again.
+        {
+            double slot_ft3 = 0.0;
+            for (double sv : ctx.links.slot_volume) slot_ft3 += sv;
+            if (slot_ft3 > 0.0)
+                row("Final Slot Storage .......", slot_ft3);
+        }
+
         std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f", mb.routing_error() * 100.0);
     }
 
@@ -855,11 +994,114 @@ void DefaultReportPlugin::write_results(std::FILE* f,
         row2("Outfall Withdrawal .......", mb2.outfall_out);
         row2("Boundary Outflow .........", mb2.boundary_out);
         row2("Evaporation Loss .........", mb2.evap_out);
+        row2("Infiltration Loss ........", mb2.infil_out);
+        // G1-c item 1: the SUBCATCH_AQUIFER share — delivered to the legacy
+        // aquifer (the same number the Groundwater Continuity block prints as
+        // "of which from 2D", in ft³) and the tail still in flight at the end.
+        if (mb2.infil_to_aquifer > 0.0 || mb2.infil_aquifer_pending > 0.0) {
+            row2("  to Aquifer (delivered) .", mb2.infil_to_aquifer);
+            row2("  to Aquifer (in flight) .", mb2.infil_aquifer_pending);
+        }
         row2("Final Stored Volume ......", mb2.final_storage);
 
         std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f",
                      mb2.error() * 100.0);
 
+#ifdef OPENSWMM_HAS_2D
+        // G-O: the two-zone [2D_AQUIFER] ledger, the same terms the .h5
+        // /groundwater_2d group and groundwater_ledger series carry. Recharge
+        // and capillary rise are internal (unsaturated <-> saturated zone of
+        // the same cell) and are listed for information, not in the balance.
+        if (ctx.twod_io.aquifer_state && ctx.twod_io.aquifer_state->active) {
+            const auto& g = *ctx.twod_io.aquifer_state;
+            WRITE(f, "");
+            WRITE(f, "");
+            std::fprintf(f, "\n  **************************        Volume        Volume");
+            std::fprintf(f, "\n  2D Aquifer Continuity          cubic meters      10^6 ltr");
+            std::fprintf(f, "\n  **************************     ---------     ---------");
+            row2("Initial Stored Volume ....", g.led_init_storage);
+            row2("Infiltration Inflow ......", g.led_infil_in);
+            row2("Conduit Seepage Inflow ...", g.led_link);   // G-X3
+            row2("Lateral Net Inflow .......", g.led_lateral);
+            row2("Deep Percolation .........", g.led_deep);
+            row2("Node Exchange Outflow ....", g.led_node);
+            row2("Subsurface ET ............", g.led_et);
+            row2("Saturation Excess Return .", g.led_dunne);
+            row2("Final Stored Volume ......", g.liveStorage());
+            row2("  (Recharge, internal) ...", g.led_recharge);
+            row2("  (Capillary Rise, int.) .", g.led_caprise);
+            const double denom = g.led_init_storage + g.led_infil_in + g.led_link +   // G-X3
+                                 std::max(0.0, g.led_lateral);
+            std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f",
+                         (denom > 0.0) ? g.continuityResidual() / denom * 100.0 : 0.0);
+        }
+
+        // T7.5: the aquifer's SPECIES continuity, one block per transported
+        // row — the quality twin of the water block above, and the only
+        // place a modeller sees where a plume went. Printed only when the
+        // kernel actually carried a tuple, so a water-only aquifer deck's
+        // report is unchanged line-for-line.
+        if (ctx.twod_io.aquifer_transport != nullptr &&
+            ctx.twod_io.aquifer_transport->active()) {
+            const auto& t = *ctx.twod_io.aquifer_transport;
+            for (int sp = 0; sp < t.n_species; ++sp) {
+                const auto u = static_cast(sp);
+                const std::string& nm =
+                    (u < t.row_names.size()) ? t.row_names[u] : std::string("?");
+                WRITE(f, "");
+                WRITE(f, "");
+                std::fprintf(f, "\n  **************************%14s", nm.c_str());
+                std::fprintf(f, "\n  2D Aquifer Quality Continuity%11s", "mass");
+                std::fprintf(f, "\n  **************************    ----------");
+                auto qrow = [&](const char* label, double v) {
+                    std::fprintf(f, "\n  %s%14.4f", label, v);
+                };
+                qrow("Initial Stored Mass ......", t.init_mass[u]);
+                qrow("Infiltration Inflow ......", t.gained_infil[u]);
+                if (t.gained_node[u] != 0.0)
+                    qrow("Node Exchange Inflow .....", t.gained_node[u]);
+                if (t.gained_link[u] != 0.0)
+                    qrow("Conduit Seepage Inflow ...", t.gained_link[u]);
+                qrow("Lateral Net Inflow .......", t.net_lateral[u]);
+                qrow("Deep Percolation .........", t.lost_deep[u]);
+                qrow("Node Exchange Outflow ....", t.lost_node[u]);
+                if (t.lost_link[u] != 0.0)
+                    qrow("Conduit Seepage Outflow ..", t.lost_link[u]);
+                qrow("Saturation Excess Return .", t.lost_dunne[u]);
+                qrow("Evapotranspiration .......", t.lost_et[u]);
+                if (t.lost_reaction[u] != 0.0)
+                    qrow("Reacted / Decayed ........", t.lost_reaction[u]);
+                qrow("Final Stored Mass ........", t.ledgeredStorage(sp));
+                // The denominator is the scale the residual is judged
+                // against: what the aquifer started with plus every route
+                // mass can arrive by.
+                //
+                // T7.4 (2026-09-21): the sum lives on the state, beside the
+                // residual it scales, so a new channel cannot be added to one
+                // and forgotten in the other — which is exactly what happened
+                // when T7.4 added the node and link seams and this block's
+                // own copy kept dividing by three terms.
+                //
+                // T7.4b (2026-09-21): when the scale is zero there is no
+                // percentage to print. This used to print 0.000, which claims
+                // a perfect balance where the truth is that the question is
+                // unanswerable — and with the denominator now naming every
+                // route, a zero scale beside a NON-zero residual is precisely
+                // the signature of a route nobody has booked yet. Printing
+                // 0 % there would hide the next instance of the bug this
+                // denominator was fixed for, so it prints `n/a` instead.
+                const double denom = t.continuityDenominator(sp);
+                if (denom > 0.0)
+                    std::fprintf(f, "\n  Continuity Error (%%) .....%14.3f",
+                                 t.residual(sp) / denom * 100.0);
+                else
+                    std::fprintf(f, "\n  Continuity Error (%%) .....%14s",
+                                 "n/a");
+            }
+        }
+
+#endif
+
         // 2D Solver Statistics — cumulative marcher throughput. Printed only
         // when populated (>=0).
         if (mb2.solver_nsteps >= 0) {
@@ -930,12 +1172,21 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             rowx("Net 1D -> 2D .............", spill_1d - drain_1d);
 
             // Flow-routing continuity with the exchange internal: remove the
-            // drain from external inflow and the spill from flooding loss.
+            // drain from external inflow and the spill from whichever outflow
+            // category carries it.
+            //
+            // C2: the spill now lives in routing_coupling_out by default, and
+            // only in routing_flooding under COUPLING_IN_FLOODING. Subtracting
+            // it from the SUM of the two is correct in both groupings and
+            // needs no branch — the category it is not in contributes zero.
             const double in_adj  = mb1.routing_dry_weather + mb1.routing_wet_weather
-                                 + mb1.routing_gw_inflow + mb1.routing_rdii
+                                 + mb1.routing_gw_inflow
+                                 + mb1.routing_link_gw_inflow   // G-X4
+                                 + mb1.routing_rdii
                                  + (mb1.routing_external - drain_1d)
                                  + mb1.routing_init_storage;
-            const double out_adj = (mb1.routing_flooding - spill_1d)
+            const double out_adj = (mb1.routing_flooding
+                                    + mb1.routing_coupling_out - spill_1d)
                                  + mb1.routing_outflow + mb1.routing_evap_loss
                                  + mb1.routing_seep_loss + mb1.routing_final_storage;
             const double err_adj = (in_adj > 0.0)
@@ -996,7 +1247,6 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             double reacted = (up < mb.qual_routing_reacted.size())   ? mb.qual_routing_reacted[up]  : 0.0;
             double init    = (up < mb.qual_routing_init.size())      ? mb.qual_routing_init[up]     : 0.0;
             double final_  = (up < mb.qual_routing_final.size())     ? mb.qual_routing_final[up]    : 0.0;
-
             qrow("Dry Weather Inflow .......", dwf);
             qrow("Wet Weather Inflow .......", wet);
             qrow("Groundwater Inflow .......", gw);
@@ -1199,6 +1449,146 @@ void DefaultReportPlugin::write_results(std::FILE* f,
         }
     }
 
+    // =====================================================================
+    // FV Solver Statistics — cumulative explicit-integrator throughput, the
+    // 1D counterpart of the "2D Solver Statistics" block above. The Routing
+    // Time Step Summary reports the ROUTING step; this reports the substeps
+    // the FV solver filled it with, which is the number that actually sets
+    // the run time.
+    //
+    // Already inside the rpt_flowstats guard opened well above (the braces
+    // that close just before this comment are the anonymous scope holding the
+    // Routing Time Step Summary's `rs`, not the conditional) — so the FV block
+    // follows FLOWSTATS, whereas the 2D block above follows CONTINUITY. The
+    // two solver blocks answer to different report flags; that is inherited,
+    // not chosen here.
+    //
+    // Skipped on the -1 sentinel, which means "not an FV run".
+    // =====================================================================
+    if (ctx.routing_stats.fv_nsteps >= 0) {
+        const auto& rs = ctx.routing_stats;
+        WRITE(f, "");
+        WRITE(f, "");
+        WRITE(f, "*********************");
+        WRITE(f, "FV Solver Statistics");
+        WRITE(f, "*********************");
+        auto srow = [&](const char* label, long v) {
+            std::fprintf(f, "\n  %s%14ld", label, v);
+        };
+        srow("Explicit Substeps ........", rs.fv_nsteps);
+        srow("Face Flux Evaluations ....", rs.fv_nflux);
+        std::fprintf(f, "\n  Avg Substep (s) ..........%14.6f", rs.fv_avg_h);
+        std::fprintf(f, "\n  Min Substep (s) ..........%14.6f", rs.fv_min_h);
+        std::fprintf(f, "\n  Last Substep (s) .........%14.6f", rs.fv_last_h);
+        // Whether local time stepping ever ran a macro cycle. The tier
+        // occupancy rows below are filled by the tier ASSIGNMENT, which runs
+        // whether or not a cycle fits the routing step, so on their own they
+        // cannot distinguish "tiering did not help" from "tiering never
+        // engaged" — these two rows can.
+        srow("LTS Macro Cycles Fired ...", rs.fv_macro_cycles);
+        srow("LTS Macro Cycles Rejected ", rs.fv_macro_rejected);
+
+        // Compaction telemetry: the share of faces on the active list at each
+        // rebuild. A mean near 1.0 means compaction is finding nothing to skip.
+        if (rs.fv_active_mean >= 0.0) {
+            std::fprintf(f,
+                "\n  Active Faces min/mean/max %8.1f /%5.1f /%5.1f  (%%)",
+                100.0 * rs.fv_active_min,
+                100.0 * rs.fv_active_mean,
+                100.0 * rs.fv_active_max);
+        }
+
+        // dt-argmin attribution (slot program R0): which regime owned the
+        // binding CFL element, as a share of census/re-tier events. The
+        // number that says whether the step is set by the slot.
+        {
+            const long tot = rs.fv_dt_argmin_pressurized + rs.fv_dt_argmin_band +
+                             rs.fv_dt_argmin_free + rs.fv_dt_argmin_node;
+            if (tot > 0) {
+                auto pct = [&](long v) {
+                    return 100.0 * static_cast(v) /
+                           static_cast(tot);
+                };
+                std::fprintf(f, "\n  dt Argmin Pressurized (%%) %14.1f",
+                             pct(rs.fv_dt_argmin_pressurized));
+                std::fprintf(f, "\n  dt Argmin Taper Band (%%) .%14.1f",
+                             pct(rs.fv_dt_argmin_band));
+                std::fprintf(f, "\n  dt Argmin Free (%%) .......%14.1f",
+                             pct(rs.fv_dt_argmin_free));
+                std::fprintf(f, "\n  dt Argmin Node Bound (%%) .%14.1f",
+                             pct(rs.fv_dt_argmin_node));
+            }
+        }
+
+        // LTS tier occupancy. A run that quietly collapsed to one tier reads
+        // as n_tiers == 1 here rather than as a silently ordinary run — which
+        // is the difference between "tiering did not help" and "tiering never
+        // engaged", and they call for opposite responses.
+        if (rs.fv_n_tiers > 0) {
+            long total = 0;
+            for (int k = 0; k < rs.fv_n_tiers && k < 8; ++k)
+                total += rs.fv_tier_cells[k];
+            if (total > 0) {
+                for (int k = 0; k < rs.fv_n_tiers && k < 8; ++k)
+                    std::fprintf(f,
+                        "\n  LTS Tier %d Occupancy (%%) .%14.1f", k,
+                        100.0 * static_cast(rs.fv_tier_cells[k])
+                              / static_cast(total));
+            }
+        }
+    }
+
+    // =====================================================================
+    // Slot Storage Summary (FV slot program R0) — how much of the run's
+    // conduit storage stood in the Preissmann slot. The run share is the
+    // ratio of time integrals; links are listed when their peak share
+    // crossed the 1 % budget. Silent when the slot never held water.
+    // =====================================================================
+    {
+        double sum_slot_dt = 0.0, sum_vol_dt = 0.0;
+        for (std::size_t j = 0; j < ctx.links.stat_slot_vol_dt.size(); ++j) {
+            sum_slot_dt += ctx.links.stat_slot_vol_dt[j];
+            sum_vol_dt  += ctx.links.stat_vol_dt[j];
+        }
+        if (sum_slot_dt > 0.0) {
+            WRITE(f, "");
+            WRITE(f, "");
+            WRITE(f, "*********************");
+            WRITE(f, "Slot Storage Summary");
+            WRITE(f, "*********************");
+            std::fprintf(f, "\n  Run Slot Share (%%) .......%14.2f",
+                         100.0 * sum_slot_dt / std::max(sum_vol_dt, 1e-30));
+            std::fprintf(f, "\n  Peak Slot Share (%%) ......%14.2f",
+                         100.0 * ctx.routing_stats.slot_peak_share);
+            std::fprintf(f, "\n  Hours Share Above 1%% .....%14.2f",
+                         ctx.routing_stats.slot_time_above_s / 3600.0);
+
+            // Per-link rows for offenders (peak share >= 1%).
+            bool header = false;
+            for (int j = 0; j < ctx.n_links(); ++j) {
+                const auto uj = static_cast(j);
+                if (ctx.links.stat_peak_slot_share[uj] < 0.01) continue;
+                if (!header) {
+                    std::fprintf(f,
+                        "\n\n  Link                    Peak Share    Run Share"
+                        "   Hrs >1%%"
+                        "\n  ----------------------------------------------------------");
+                    header = true;
+                }
+                const double run_share =
+                    (ctx.links.stat_vol_dt[uj] > 0.0)
+                        ? ctx.links.stat_slot_vol_dt[uj] /
+                              ctx.links.stat_vol_dt[uj]
+                        : 0.0;
+                std::fprintf(f, "\n  %-20s %9.2f%%   %9.2f%% %9.2f",
+                             ctx.link_names.name_of(j).c_str(),
+                             100.0 * ctx.links.stat_peak_slot_share[uj],
+                             100.0 * run_share,
+                             ctx.links.stat_time_slot_above[uj] / 3600.0);
+            }
+        }
+    }
+
     WRITE(f, "");
     WRITE(f, "");
 
@@ -1216,6 +1606,7 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             "\n  Name                 Conduit          Conduit               Maximum          Mean");
         std::fprintf(f,
             "\n  ------------------------------------------------------------------------------------");
+        bool any_fed = false;
         for (std::size_t r = 0; r < ctx.vj_diag.node_idx.size(); ++r) {
             const int ni = ctx.vj_diag.node_idx[r];
             const int ju = ctx.vj_diag.up_link[r];
@@ -1223,12 +1614,33 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             const long long n = ctx.vj_diag.resid_n[r];
             const double mean = (n > 0)
                 ? ctx.vj_diag.resid_sum[r] / static_cast(n) : 0.0;
-            std::fprintf(f, "\n  %-20s %-16s %-16s %13.6f %13.6f",
-                ctx.node_names.name_of(ni).c_str(),
-                (ju >= 0) ? ctx.link_names.name_of(ju).c_str() : "*",
-                (jd >= 0) ? ctx.link_names.name_of(jd).c_str() : "*",
-                ctx.vj_diag.resid_max[r], mean);
+            // A virtual junction fed by a lateral inflow (plans/
+            // VJ_LATERAL_INFLOW_PLAN_2026-09-04.md) legitimately shows a
+            // nonzero residual — the added mass carries no momentum — so
+            // the row says so. Unfed rows keep the original format.
+            const auto uni = static_cast(ni);
+            const double max_lat = (ni >= 0 && uni < ctx.nodes.stat_max_lat_inflow.size())
+                ? ctx.nodes.stat_max_lat_inflow[uni] : 0.0;
+            // Signed statistic (an inlet junction's capture sink is negative).
+            if (std::fabs(max_lat) > 0.0) {
+                std::fprintf(f, "\n  %-20s %-16s %-16s %13.6f %13.6f   lateral %.3f %s",
+                    ctx.node_names.name_of(ni).c_str(),
+                    (ju >= 0) ? ctx.link_names.name_of(ju).c_str() : "*",
+                    (jd >= 0) ? ctx.link_names.name_of(jd).c_str() : "*",
+                    ctx.vj_diag.resid_max[r], mean,
+                    max_lat * Qcf, FlowUnitWords[fu]);
+                any_fed = true;
+            } else {
+                std::fprintf(f, "\n  %-20s %-16s %-16s %13.6f %13.6f",
+                    ctx.node_names.name_of(ni).c_str(),
+                    (ju >= 0) ? ctx.link_names.name_of(ju).c_str() : "*",
+                    (jd >= 0) ? ctx.link_names.name_of(jd).c_str() : "*",
+                    ctx.vj_diag.resid_max[r], mean);
+            }
         }
+        if (any_fed)
+            std::fprintf(f, "\n  (lateral: maximum lateral inflow at the node; "
+                            "its residual includes the added zero-momentum mass)");
         WRITE(f, "");
         WRITE(f, "");
     }
@@ -1309,13 +1721,23 @@ void DefaultReportPlugin::write_results(std::FILE* f,
                 char datebuf[16], timebuf[16];
                 std::snprintf(datebuf, sizeof(datebuf), "%02d/%02d/%04d", mo, dy, yr);
                 std::snprintf(timebuf, sizeof(timebuf), "%02d:%02d:%02d", hr, mn, sc);
+                const char* rule_name =
+                    (entry.rule_idx >= 0
+                     && entry.rule_idx < static_cast(ctx.control_rule_names.size()))
+                        ? ctx.control_rule_names[static_cast(entry.rule_idx)].c_str()
+                        : "Rule?";
                 std::fprintf(f,
                     "\n  %11s: %8s Link %s setting changed to %6.2f by Control %s",
                     datebuf, timebuf,
                     ctx.link_names.name_of(entry.link_idx).c_str(),
                     entry.new_setting,
-                    entry.rule_name.c_str());
+                    rule_name);
             }
+            if (ctx.control_log_dropped > 0)
+                std::fprintf(f,
+                    "\n  (%zu further control actions not listed: the log is "
+                    "capped at %zu entries)",
+                    ctx.control_log_dropped, SimulationContext::kMaxControlLog);
         }
 
         WRITE(f, "");
@@ -1383,13 +1805,19 @@ void DefaultReportPlugin::write_results(std::FILE* f,
 
     // =====================================================================
     // Subcatchment Washoff Summary — Gap #64, matches legacy writeSubcatchLoads()
-    // total_load is in mg (washoff_load [mg/s] × dt [s]); convert to lbs: /453592
+    // total_load is in USER MASS (lbs/kg) since the 2026-08-23 units fix:
+    // the washoff loop applies mcf at the booking seam, exactly as legacy
+    // does at surfqual.c:357 — so this summary prints the value RAW, and it
+    // agrees with the Runoff Quality Continuity ledger row by construction.
+    // The /453592 that used to sit here was half of the defect: with the
+    // booking in mg/L·ft³ the summary printed 1/28.3 of the true pounds
+    // while the ledger row printed 16057× them (known-mass audit,
+    // QUALITY_LEDGER_UNITS_AUDIT §7).
     // =====================================================================
     if (ctx.n_subcatches() > 0 && ctx.n_pollutants() > 0 && opt.rpt_subcatchments != 0
         && !opt.ignore_quality) {
         int ns = ctx.n_subcatches();
         int np = ctx.n_pollutants();
-        static constexpr double MG_TO_LBS = 1.0 / 453592.0;
 
         WRITE(f, "****************************");
         WRITE(f, "Subcatchment Washoff Summary");
@@ -1420,9 +1848,8 @@ void DefaultReportPlugin::write_results(std::FILE* f,
             for (int p = 0; p < np; ++p) {
                 auto up = static_cast(p);
                 auto idx = uj * static_cast(np) + up;
-                double load_mg = (idx < ctx.subcatches.total_load.size())
+                double load_lbs = (idx < ctx.subcatches.total_load.size())
                     ? ctx.subcatches.total_load[idx] : 0.0;
-                double load_lbs = load_mg * MG_TO_LBS;
                 sys_loads[up] += load_lbs;
                 std::fprintf(f, "%14.3f", load_lbs);
             }
@@ -1439,6 +1866,102 @@ void DefaultReportPlugin::write_results(std::FILE* f,
         WRITE(f, "");
     }
 
+    // =====================================================================
+    // BW-MSX (2026-09-19): the reactions component's species that build up
+    // and wash off — same layout as the pollutant block, user mass per
+    // species (MG/UG species print lbs/kg; other units print "mass").
+    // =====================================================================
+    {
+        const auto& ms = ctx.reactions.surface;
+        if (ms.active() && ctx.n_subcatches() > 0 && opt.rpt_subcatchments != 0
+            && !opt.ignore_quality) {
+            const int ns = ctx.n_subcatches();
+            const int nm = ms.n_species;
+            WRITE(f, "********************************");
+            WRITE(f, "Subcatchment MSX Washoff Summary");
+            WRITE(f, "********************************");
+            std::fprintf(f, "\n");
+            std::fprintf(f, " \n  ----------------------------------");
+            for (int m = 1; m < nm; ++m) std::fprintf(f, "--------------");
+            std::fprintf(f, " \n                                ");
+            for (int m = 0; m < nm; ++m)
+                std::fprintf(f, "%14s", ctx.reactions.species_name[static_cast(m)].c_str());
+            std::fprintf(f, " \n  Subcatchment                  ");
+            for (int m = 0; m < nm; ++m) {
+                const double mcf = ms.mcf[static_cast(m)];
+                std::fprintf(f, "%14s", (mcf == 1.0) ? "mass" : (si_report ? "kg" : "lbs"));
+            }
+            std::fprintf(f, " \n  ----------------------------------");
+            for (int m = 1; m < nm; ++m) std::fprintf(f, "--------------");
+            std::vector sys(static_cast(nm), 0.0);
+            for (int j = 0; j < ns; ++j) {
+                std::fprintf(f, "\n  %-30s", ctx.subcatch_names.name_of(j).c_str());
+                for (int m = 0; m < nm; ++m) {
+                    const double v = ms.led_subcatch_load[ms.sidx(j, m)];
+                    sys[static_cast(m)] += v;
+                    std::fprintf(f, "%14.3f", v);
+                }
+            }
+            std::fprintf(f, " \n  ----------------------------------");
+            for (int m = 1; m < nm; ++m) std::fprintf(f, "--------------");
+            std::fprintf(f, "\n  System                        ");
+            for (int m = 0; m < nm; ++m) std::fprintf(f, "%14.3f", sys[static_cast(m)]);
+            WRITE(f, "");
+            std::fprintf(f, "  Surface ledger (species: initial buildup, net buildup, washed to network, swept, BMP removed):\n");
+            for (int m = 0; m < nm; ++m) {
+                const auto um = static_cast(m);
+                std::fprintf(f, "    %-16s %14.3f %14.3f %14.3f %14.3f %14.3f\n",
+                             ctx.reactions.species_name[um].c_str(),
+                             ms.led_init_buildup[um], ms.led_buildup[um],
+                             ms.led_runoff_load[um], ms.led_sweeping[um], ms.led_bmp_removal[um]);
+            }
+            WRITE(f, "");
+            WRITE(f, "");
+        }
+    }
+
+#ifdef OPENSWMM_HAS_2D
+    // S7: 2D Surface Washoff Summary — the cells' land-use surfaces, per
+    // surface species (pollutants, then MSX). The same ledger rows as the
+    // subcatchment blocks above, in the same user mass, plus the store left
+    // on the mesh; "washed" is what entered the cell rows (it reaches the
+    // network through the coupling tuple, so it is not a node load here).
+    {
+        const auto* sq = ctx.twod_io.surface_quality;
+        if (sq && sq->active() && !opt.ignore_quality) {
+            const int nsp = sq->nSpecies();
+            WRITE(f, "**************************");
+            WRITE(f, "2D Surface Washoff Summary");
+            WRITE(f, "**************************");
+            std::fprintf(f, "\n");
+            std::fprintf(f, "  Cells: %d  Land uses: %d  (buildup per %s)\n",
+                         sq->nCells(), sq->nLandUses(), si_report ? "hectare" : "acre");
+            std::fprintf(f, "  %-16s %14s %14s %14s %14s %14s %14s\n", "Species",
+                         "Init Buildup", "Net Buildup", "Washed Off", "Swept", "BMP Removed", "On Mesh");
+            for (int sidx = 0; sidx < nsp; ++sidx) {
+                const auto us = static_cast(sidx);
+                double store = 0.0;
+                if (ctx.twod_io.mesh) {
+                    const auto& mesh = *ctx.twod_io.mesh;
+                    const double to_la = si_report ? 1.0e-4 : 1.0 / 4046.8564224;   // m² → ha | acre
+                    for (int c = 0; c < sq->nCells(); ++c)
+                        store += sq->buildupPerArea(c, sidx) *
+                                 mesh.tri_area[static_cast(c)] * to_la;
+                }
+                std::fprintf(f, "  %-16s %14.3f %14.3f %14.3f %14.3f %14.3f %14.3f\n",
+                             sq->speciesName(sidx).c_str(),
+                             sq->ledInitBuildup()[us], sq->ledBuildup()[us], sq->ledWashoff()[us],
+                             sq->ledSweeping()[us], sq->ledBmp()[us], store);
+            }
+            std::fprintf(f, "  (%s; a reactions species declared in UG or as a count keeps its own unit)\n",
+                         si_report ? "kg" : "lbs");
+            WRITE(f, "");
+            WRITE(f, "");
+        }
+    }
+
+#endif
+
     // =====================================================================
     // Groundwater Summary — matches legacy writeGroundwater()
     // =====================================================================
@@ -1813,8 +2336,7 @@ void DefaultReportPlugin::write_results(std::FILE* f,
                 elapsedToParts(ctx.nodes.stat_max_depth_date[uj],
                                ctx.options.start_date, days, hrs, mins);
 
-                // Max outflow: use stat_max_total_inflow as proxy (outflow stats not separate)
-                double max_outflow = ctx.nodes.stat_max_total_inflow[uj] * Qcf;
+                double max_outflow = ctx.nodes.stat_storage_max_outflow[uj] * Qcf;
 
                 std::fprintf(f, "\n  %-20s", ctx.node_names.name_of(j).c_str());
                 std::fprintf(f, "%10.3f  %5.1f  %5.1f  %5.1f  %10.3f  %5.1f",
@@ -2139,13 +2661,91 @@ void DefaultReportPlugin::write_results(std::FILE* f,
     }
 
     // =====================================================================
-    // Street Inlet Flow Summary — Gap #68
+    // Street tables — Street Flow Summary (Gap #9) and the Street Inlet Flow
+    // Summary (Gap #68). Both are gated the same way the inlet table already
+    // was: link reporting on, and something street-related in the model.
+    //
+    // Street index of a STREET conduit: xsect_curve is the built transect
+    // table, whose name is the street it was built from
+    // (PostParseResolver.cpp:2298-2310).
+    // =====================================================================
+    auto street_of_link = [&ctx](int j) -> int {
+        const auto uj = static_cast(j);
+        if (ctx.links.xsect_shape[uj] != XsectShape::STREET_XSECT) return -1;
+        const int tt = ctx.links.xsect_curve[uj];
+        if (tt < 0 || tt >= static_cast(ctx.transect_tables.size())) return -1;
+        const std::string& sname = ctx.transect_tables[static_cast(tt)].name;
+        for (int s = 0; s < ctx.streets.count(); ++s) {
+            const std::string& a = ctx.streets.names[static_cast(s)];
+            if (a.size() != sname.size()) continue;
+            bool same = true;
+            for (std::size_t c = 0; c < a.size(); ++c)
+                if (std::tolower(static_cast(a[c])) !=
+                    std::tolower(static_cast(sname[c]))) { same = false; break; }
+            if (same) return s;
+        }
+        return -1;
+    };
+
+    // ---------------------------------------------------------------------
+    // Street Flow Summary — legacy writeStreetStats (inlet.c:1055-1094):
+    // peak flow, SWMM's spread (flow width at max depth / sides, clipped to
+    // the street's curb-to-crown width) and max depth per STREET conduit.
+    // ---------------------------------------------------------------------
+    if (ctx.streets.count() > 0 && opt.rpt_links != 0) {
+        bool header = false;
+        const double inv_len = 1.0 / len_ucf;   // display → ft (street store is user units)
+        for (int j = 0; j < ctx.n_links(); ++j) {
+            const int si = street_of_link(j);
+            if (si < 0) continue;
+            const auto uj = static_cast(j);
+            const auto su = static_cast(si);
+
+            if (!header) {
+                WRITE(f, "*******************");
+                WRITE(f, "Street Flow Summary");
+                WRITE(f, "*******************");
+                std::fprintf(f,
+"\n\n  -------------------------------------------------------"
+"\n                          Peak   Maximum   Maximum"
+"\n                          Flow    Spread     Depth"
+"\n  Street Conduit           %-3s     %-5s     %-5s"
+"\n  -------------------------------------------------------",
+                    FlowUnitWords[fu], si_report ? "m" : "ft",
+                    si_report ? "m" : "ft");
+                header = true;
+            }
+
+            const double max_flow  = ctx.links.stat_max_flow[uj];
+            const double max_depth = ctx.links.stat_max_filling[uj]
+                                   * ctx.links.xsect_y_full[uj];
+
+            // SWMM's spread (flow width) at max depth — not HEC-22's, which is
+            // based on max flow and cannot see backwater (inlet.c:1077-1089).
+            const XSectParams xs =
+                link::buildXSectParams(ctx.links, uj, &ctx.transect_tables);
+            const int sides = std::max(ctx.streets.sides[su], 1);
+            double max_spread = xsect::getWofY(xs, max_depth) / sides;
+            max_spread = std::min(max_spread, ctx.streets.t_crown[su] * inv_len);
+
+            std::fprintf(f, "\n  %-16s %9.3f %9.3f %9.3f",
+                ctx.link_names.name_of(j).c_str(),
+                max_flow * Qcf, max_spread * len_ucf, max_depth * len_ucf);
+        }
+        if (header) { WRITE(f, ""); WRITE(f, ""); }
+    }
+
+    // ---------------------------------------------------------------------
+    // Street Inlet Flow Summary — Gap #68 volumes plus the legacy per-inlet
+    // performance columns (inlet.c:1096-1124). Inlet junctions are listed
+    // under their node name with a "(node)" marker.
     // Volumes in ft³; convert to 1000 gal: × 7.48052 / 1000
-    // =====================================================================
+    // ---------------------------------------------------------------------
     if (ctx.inlet_usages.count() > 0 && opt.rpt_links != 0) {
         int ni = ctx.inlet_usages.count();
         // Only write if stats arrays are populated
         bool has_stats = (static_cast(ctx.inlet_usages.stat_capture_vol.size()) >= ni);
+        const bool has_diag = (ctx.inlet_diag.count() >= ni);
 
         WRITE(f, "**************************");
         WRITE(f, "Street Inlet Flow Summary");
@@ -2157,34 +2757,81 @@ void DefaultReportPlugin::write_results(std::FILE* f,
         } else {
             static constexpr double FT3_TO_KGAL = 7.48052 / 1000.0;
             std::fprintf(f,
-"\n\n  -----------------------------------------------------------------------------------------"
-"\n                                          Peak        Pcnt        Pcnt       Vol.       Vol."
-"\n  Conduit               Inlet           Flow        Captured    Bypassed   Captured   Bypassed"
-"\n                                        %-3s         Percent     Percent    1000 Gal   1000 Gal"
-"\n  -----------------------------------------------------------------------------------------",
-                FlowUnitWords[fu]);
+"\n\n  ------------------------------------------------------------------------------------------------------------------------------------------"
+"\n                                                              Peak      Peak       Avg.    Bypass      Back      Peak      Peak      Vol.      Vol."
+"\n                                                              Flow   Capture    Capture      Flow      Flow   Capture    Bypass  Captured  Bypassed"
+"\n  Inlet Location        Inlet Design       Placement  Count     %-3s      Pcnt       Pcnt      Pcnt      Pcnt   / Inlet      %-3s  1000 Gal  1000 Gal"
+"\n  ------------------------------------------------------------------------------------------------------------------------------------------",
+                FlowUnitWords[fu], FlowUnitWords[fu]);
 
             for (int i = 0; i < ni; ++i) {
                 auto ui = static_cast(i);
                 int li  = ctx.inlet_usages.link_index[i];
+                int nh  = ctx.inlet_usages.node_host[ui];
                 int di  = ctx.inlet_usages.design_index[i];
 
-                const char* link_name  = (li >= 0) ? ctx.link_names.name_of(li).c_str() : "?";
+                std::string host_name = "?";
+                if (nh >= 0) host_name = ctx.node_names.name_of(nh) + " (node)";
+                else if (li >= 0) host_name = ctx.link_names.name_of(li);
+
                 const char* inlet_name = (di >= 0 && di < ctx.inlets.count())
                                          ? ctx.inlets.names[di].c_str() : "?";
 
                 double cap_vol  = ctx.inlet_usages.stat_capture_vol[ui];
                 double byp_vol  = ctx.inlet_usages.stat_bypass_vol[ui];
-                double peak     = ctx.inlet_usages.stat_peak_flow[ui] * Qcf;
-                double total    = cap_vol + byp_vol;
-                double cap_pct  = (total > 0.0) ? cap_vol / total * 100.0 : 0.0;
-                double byp_pct  = (total > 0.0) ? byp_vol / total * 100.0 : 0.0;
+                // "Peak Flow" is the peak APPROACH flow the inlet saw, like
+                // legacy's street maxFlow column (inlet.c:1092); the peak
+                // captured flow is the stat_peak_flow fallback only when the
+                // solver never ran (no diagnostics block).
+                double peak     = (has_diag ? ctx.inlet_diag.peak_flow[ui]
+                                            : ctx.inlet_usages.stat_peak_flow[ui]) * Qcf;
                 double cap_kgal = cap_vol * FT3_TO_KGAL;
                 double byp_kgal = byp_vol * FT3_TO_KGAL;
 
-                std::fprintf(f, "\n  %-20s  %-14s  %9.3f  %9.2f  %9.2f  %9.3f  %9.3f",
-                    link_name, inlet_name,
-                    peak, cap_pct, byp_pct, cap_kgal, byp_kgal);
+                // Legacy performance block. fp/cp are the legacy period counts
+                // divided by 100 so the sums below read out as percentages
+                // (inlet.c:1106-1122).
+                const char* placement = "ON-GRADE";
+                int    n_inlets = 1;
+                double pfc = 0.0, afc = 0.0, bpf = 0.0, bff = 0.0;
+                double peak_cap_per_inlet = 0.0, peak_bypass = 0.0;
+                if (has_diag) {
+                    const auto& dg = ctx.inlet_diag;
+                    placement = (dg.is_sag[ui] != 0) ? "ON-SAG  " : "ON-GRADE";
+                    n_inlets  = std::max(dg.num_inlets[ui], 1);
+                    const double fp = dg.flow_periods[ui] / 100.0;
+                    if (fp > 0.0) {
+                        const double cp = dg.capture_periods[ui] / 100.0;
+                        pfc = dg.peak_flow_capture[ui];
+                        if (cp > 0.0) {
+                            afc = dg.avg_flow_capture[ui] / cp;
+                            bpf = dg.bypass_freq[ui] / cp;
+                        }
+                        bff = dg.backflow_periods[ui] / fp;
+
+                        // Peak capture per inlet / peak bypass are scaled off
+                        // the approach conduit's peak flow (the host link, or
+                        // the inlet junction's approach conduit).
+                        const int hl = (li >= 0) ? li : dg.up_link[ui];
+                        if (hl >= 0 && hl < ctx.n_links()) {
+                            const auto uh = static_cast(hl);
+                            const double max_flow = ctx.links.stat_max_flow[uh];
+                            const int si = street_of_link(hl);
+                            const int sides = (si >= 0)
+                                ? std::max(ctx.streets.sides[static_cast(si)], 1)
+                                : 1;
+                            peak_cap_per_inlet = (max_flow / sides) * Qcf * 0.01
+                                                 * pfc / n_inlets;
+                            peak_bypass = max_flow * Qcf * 0.01 * (100.0 - pfc);
+                        }
+                    }
+                }
+
+                std::fprintf(f,
+                    "\n  %-20s  %-16s   %-9s  %5d  %8.3f  %8.2f  %9.2f  %8.2f  %8.2f  %8.3f  %8.3f  %8.3f  %8.3f",
+                    host_name.c_str(), inlet_name, placement, n_inlets,
+                    peak, pfc, afc, bpf, bff,
+                    peak_cap_per_inlet, peak_bypass, cap_kgal, byp_kgal);
             }
         }
         WRITE(f, "");
@@ -2258,25 +2905,36 @@ void DefaultReportPlugin::write_results(std::FILE* f,
 // write_timing — analysis timing section
 // ---------------------------------------------------------------------------
 
-void DefaultReportPlugin::write_timing(std::FILE* f) {
+void DefaultReportPlugin::write_timing(std::FILE* f, const SimulationContext& ctx) {
     // =====================================================================
-    // Analysis Timing — matches legacy report_writeRunTime()
+    // Analysis Timing — matches legacy report_writeSysTime()
+    //
+    // The start of the window is ctx.wall_start, stamped by
+    // SWMMEngine::open() before input parsing, mirroring legacy where
+    // report_writeLogo() takes SysTime ahead of project_readInput(). Elapsed
+    // time therefore covers parse + validation + initialization + routing,
+    // not just routing.
     // =====================================================================
     {
         char begin_str[64] = "";
         char end_str[64] = "";
 
-        if (wall_start_ != 0) {
-            const char* ct = std::ctime(&wall_start_);
+        std::time_t wall_end;
+        std::time(&wall_end);
+
+        // A zero wall_start means open() never ran (e.g. the plugin was
+        // driven directly). Fall back to the end time so the section reports
+        // "< 1 sec" rather than seconds-since-the-epoch.
+        std::time_t wall_start = (ctx.wall_start != 0) ? ctx.wall_start : wall_end;
+
+        {
+            const char* ct = std::ctime(&wall_start);
             if (ct) {
                 std::strncpy(begin_str, ct, sizeof(begin_str) - 1);
                 char* nl = std::strchr(begin_str, '\n');
                 if (nl) *nl = '\0';
             }
         }
-
-        std::time_t wall_end;
-        std::time(&wall_end);
         {
             const char* ct = std::ctime(&wall_end);
             if (ct) {
@@ -2290,12 +2948,17 @@ void DefaultReportPlugin::write_timing(std::FILE* f) {
         std::fprintf(f, "\n  Analysis ended on:  %s", end_str);
         std::fprintf(f, "\n  Total elapsed time: ");
 
-        double elapsed_secs = std::difftime(wall_end, wall_start_);
+        double elapsed_secs = std::difftime(wall_end, wall_start);
         if (elapsed_secs < 1.0) {
             std::fprintf(f, "< 1 sec");
         } else {
-            int es = static_cast(elapsed_secs);
-            std::fprintf(f, "%02d:%02d:%02d", es / 3600, (es % 3600) / 60, es % 60);
+            // Legacy rolls whole days into a "d." prefix ahead of hh:mm:ss.
+            long es = static_cast(elapsed_secs);
+            long days = es / 86400L;
+            long rem  = es % 86400L;
+            if (days > 0) std::fprintf(f, "%ld.", days);
+            std::fprintf(f, "%02ld:%02ld:%02ld",
+                         rem / 3600L, (rem % 3600L) / 60L, rem % 60L);
         }
         std::fprintf(f, "\n");
     }
diff --git a/src/engine/plugins/DefaultReportPlugin.hpp b/src/engine/plugins/DefaultReportPlugin.hpp
index 7591ff60d..374246d04 100644
--- a/src/engine/plugins/DefaultReportPlugin.hpp
+++ b/src/engine/plugins/DefaultReportPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultReportPlugin.hpp
  * @brief Built-in report plugin that writes the legacy SWMM .rpt summary.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DEFAULT_REPORT_PLUGIN_HPP
@@ -56,7 +72,6 @@ class DefaultReportPlugin final : public IReportPlugin {
     std::string rpt_path_;
     PluginState state_      = PluginState::UNLOADED;
     std::string last_error_;
-    std::time_t wall_start_ = 0;  ///< Wall-clock time when prepare() was called
 
     // Progressive write state
     std::FILE*  file_             = nullptr; ///< Persistent file handle (opened in prepare)
@@ -70,7 +85,7 @@ class DefaultReportPlugin final : public IReportPlugin {
     void write_results(std::FILE* f, const SimulationContext& ctx);
 
     /** @brief Write analysis timing section. */
-    void write_timing(std::FILE* f);
+    void write_timing(std::FILE* f, const SimulationContext& ctx);
 };
 
 } /* namespace openswmm */
diff --git a/src/engine/plugins/DefaultStateIOPlugin.cpp b/src/engine/plugins/DefaultStateIOPlugin.cpp
index bcc91b80c..30b05b44f 100644
--- a/src/engine/plugins/DefaultStateIOPlugin.cpp
+++ b/src/engine/plugins/DefaultStateIOPlugin.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultStateIOPlugin.cpp
  * @brief Built-in state IO plugin implementation.
@@ -6,10 +22,11 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "DefaultStateIOPlugin.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
 
 #include "../core/HotStartManager.hpp"
 #include "../core/SimulationContext.hpp"
@@ -27,7 +44,7 @@ namespace {
 // Read the leading bytes of a file into buf without depending on
 // HotStartManager internals. Returns the number of bytes read.
 std::size_t read_head(const std::string& path, char* buf, std::size_t len) noexcept {
-    std::FILE* f = std::fopen(path.c_str(), "rb");
+    std::FILE* f = openswmm::io::fopen_utf8(path, "rb");
     if (!f) return 0;
     const std::size_t n = std::fread(buf, 1, len, f);
     std::fclose(f);
diff --git a/src/engine/plugins/DefaultStateIOPlugin.hpp b/src/engine/plugins/DefaultStateIOPlugin.hpp
index a7b9c780a..475bd2f41 100644
--- a/src/engine/plugins/DefaultStateIOPlugin.hpp
+++ b/src/engine/plugins/DefaultStateIOPlugin.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file DefaultStateIOPlugin.hpp
  * @brief Built-in state IO plugin — wraps HotStartManager for read/write.
@@ -19,7 +35,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_DEFAULT_STATE_IO_PLUGIN_HPP
diff --git a/src/engine/plugins/PluginDiscovery.cpp b/src/engine/plugins/PluginDiscovery.cpp
index 33839f4aa..92c7bc76c 100644
--- a/src/engine/plugins/PluginDiscovery.cpp
+++ b/src/engine/plugins/PluginDiscovery.cpp
@@ -1,10 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginDiscovery.cpp
  * @brief Public filter-discovery facade — implementation.
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "../../../include/openswmm/plugin_sdk/PluginDiscovery.hpp"
diff --git a/src/engine/plugins/PluginFactory.cpp b/src/engine/plugins/PluginFactory.cpp
index d1e39ee7b..7190dfa07 100644
--- a/src/engine/plugins/PluginFactory.cpp
+++ b/src/engine/plugins/PluginFactory.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginFactory.cpp
  * @brief Plugin loader, auto-discovery, and lifecycle manager — implementation.
@@ -7,7 +23,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "PluginFactory.hpp"
@@ -18,6 +34,10 @@
 // instead of being picked up accidentally through the discover() scan's
 // dlsym(openswmm_plugin_info) on the engine's own binary. See §R.3 in
 // docs/GUI_IMPLEMENTATION_PLAN.md for the rationale.
+#ifdef OPENSWMM_HAS_HDF5_MODEL
+#  include "../io/hdf5/Hdf5PluginInfo.hpp"
+#endif
+
 #ifdef OPENSWMM_HAS_GEOPACKAGE
 #  include "../input/geopackage/GeoPackagePluginInfo.hpp"
 #endif
@@ -40,6 +60,10 @@
 #if defined(_WIN32)
 #  define WIN32_LEAN_AND_MEAN
 #  include 
+#elif defined(__EMSCRIPTEN__)
+   // WebAssembly: no dynamic loading (engine is statically linked into the
+   // .wasm). platform_* helpers below are stubs; built-in plugins
+   // (register_builtin_infos) are unaffected.
 #elif defined(__APPLE__) || defined(__linux__)
 #  include 
 #else
@@ -70,6 +94,9 @@ PluginFactory::~PluginFactory() {
 void* PluginFactory::platform_load(const std::string& path) {
 #if defined(_WIN32)
     return static_cast(::LoadLibraryA(path.c_str()));
+#elif defined(__EMSCRIPTEN__)
+    (void)path;
+    return nullptr;
 #else
     return ::dlopen(path.c_str(), RTLD_NOW | RTLD_LOCAL);
 #endif
@@ -79,6 +106,8 @@ void PluginFactory::platform_unload(void* handle) noexcept {
     if (!handle) return;
 #if defined(_WIN32)
     ::FreeLibrary(static_cast(handle));
+#elif defined(__EMSCRIPTEN__)
+    // nothing to unload
 #else
     ::dlclose(handle);
 #endif
@@ -89,6 +118,9 @@ void* PluginFactory::platform_sym(void* handle, const char* sym) noexcept {
 #if defined(_WIN32)
     return reinterpret_cast(
         ::GetProcAddress(static_cast(handle), sym));
+#elif defined(__EMSCRIPTEN__)
+    (void)sym;
+    return nullptr;
 #else
     return ::dlsym(handle, sym);
 #endif
@@ -102,6 +134,8 @@ std::string PluginFactory::platform_error() noexcept {
                      MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
                      buf, sizeof(buf), nullptr);
     return std::string(buf);
+#elif defined(__EMSCRIPTEN__)
+    return "dynamic plugin loading is not available in WebAssembly";
 #else
     const char* msg = ::dlerror();
     return msg ? std::string(msg) : "(unknown dlerror)";
@@ -128,6 +162,8 @@ std::string PluginFactory::get_library_directory() {
         }
     }
     return {};
+#elif defined(__EMSCRIPTEN__)
+    return {};
 #else
     // Use dladdr to find the shared library containing this function
     Dl_info dl_info;
@@ -610,6 +646,13 @@ void PluginFactory::register_builtin_infos() {
 #ifdef OPENSWMM_HAS_GEOPACKAGE
     register_one(&openswmm::gpkg::GeoPackagePluginInfo::instance());
 #endif
+
+    // The HDF5 model writer registers the same way and for the same reason:
+    // statically linked, so it must be announced explicitly rather than
+    // discovered by dlsym. See src/engine/io/hdf5/STRATEGY.md.
+#ifdef OPENSWMM_HAS_HDF5_MODEL
+    register_one(&openswmm::h5io::Hdf5PluginInfo::instance());
+#endif
 }
 
 // ============================================================================
diff --git a/src/engine/plugins/PluginFactory.hpp b/src/engine/plugins/PluginFactory.hpp
index 0161ae631..b7edc4d6a 100644
--- a/src/engine/plugins/PluginFactory.hpp
+++ b/src/engine/plugins/PluginFactory.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file PluginFactory.hpp
  * @brief Plugin loader, auto-discovery, and lifecycle manager.
@@ -34,7 +50,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_ENGINE_PLUGIN_FACTORY_HPP
diff --git a/src/engine/plugins/ProcessComponentRegistry.cpp b/src/engine/plugins/ProcessComponentRegistry.cpp
new file mode 100644
index 000000000..d88e0471f
--- /dev/null
+++ b/src/engine/plugins/ProcessComponentRegistry.cpp
@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ProcessComponentRegistry.cpp
+ * @brief Registry + config-file delivery for [PROCESS_COMPONENTS] — IO1–IO2.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ProcessComponentRegistry.hpp"
+#include "core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../core/SimulationContext.hpp"
+
+namespace openswmm::components {
+
+// ===========================================================================
+// Config-file reader (IO2)
+// ===========================================================================
+
+namespace {
+
+std::string upper(std::string s) {
+    std::transform(s.begin(), s.end(), s.begin(),
+                   [](unsigned char c) { return static_cast(std::toupper(c)); });
+    return s;
+}
+
+/// Strip ';'-style comments (the .inp convention) and trailing whitespace.
+std::string strip_comment(const std::string& line) {
+    const auto sc = line.find(';');
+    std::string s = (sc == std::string::npos) ? line : line.substr(0, sc);
+    while (!s.empty() &&
+           (s.back() == ' ' || s.back() == '\t' || s.back() == '\r'))
+        s.pop_back();
+    return s;
+}
+
+/// True when the id token is a shared-library path rather than a registry id
+/// (reserved for phase HC2 — HydroCouple component discovery).
+bool looks_like_library(const std::string& id) {
+    if (id.find('/') != std::string::npos ||
+        id.find('\\') != std::string::npos)
+        return true;
+    for (const char* ext : {".so", ".dylib", ".dll"}) {
+        const std::string e(ext);
+        if (id.size() > e.size() &&
+            id.compare(id.size() - e.size(), e.size(), e) == 0)
+            return true;
+    }
+    return false;
+}
+
+}  // namespace
+
+std::string parse_component_config_stream(std::istream& in,
+                                          const std::string& label,
+                                          ComponentConfigSections& out) {
+    std::vector* current = nullptr;
+    std::string raw;
+    while (std::getline(in, raw)) {
+        const std::string line = strip_comment(raw);
+        if (line.empty()) continue;
+
+        // Section header?
+        const auto lb = line.find('[');
+        if (lb != std::string::npos && line.find(']', lb) != std::string::npos &&
+            line.find_first_not_of(" \t") == lb) {
+            const auto rb = line.find(']', lb);
+            const std::string tag = upper(line.substr(lb + 1, rb - lb - 1));
+            if (tag == "PROCESS_COMPONENTS")
+                return "Component config '" + label +
+                       "' contains a nested [PROCESS_COMPONENTS] section — "
+                       "component files cannot register components (no "
+                       "recursion; TRANSPORT_IO_PLUGIN_CONFIG_PLAN §3.3).";
+            out.sections.emplace_back(tag, std::vector{});
+            current = &out.sections.back().second;
+            continue;
+        }
+        if (current == nullptr)
+            return "Component config '" + label +
+                   "' has content before its first [SECTION] header.";
+        current->push_back(line);
+    }
+    return {};
+}
+
+std::string parse_component_config_text(const std::string& text,
+                                        const std::string& label,
+                                        ComponentConfigSections& out) {
+    out.sections.clear();
+    out.source_path = label;
+    std::istringstream in(text);
+    return parse_component_config_stream(in, label, out);
+}
+
+std::string read_component_config(const std::string& path,
+                                  const std::string& base_dir,
+                                  ComponentConfigSections& out) {
+    out.sections.clear();
+
+    namespace fs = std::filesystem;
+    // utf8_path, not fs::path(std::string): the latter decodes in the native
+    // NARROW encoding on Windows (the ANSI code page), which is the issue #7
+    // bug one level up from the open call.
+    fs::path p = openswmm::io::utf8_path(path);
+    if (p.is_relative() && !base_dir.empty())
+        p = openswmm::io::utf8_path(base_dir) / p;
+    // path_utf8, not p.string(): source_path flows on to InpWriter as
+    // pc.resolved_config_path, which re-reads it as UTF-8.
+    out.source_path = openswmm::io::path_utf8(p);
+
+    std::ifstream in(p);
+    if (!in.is_open())
+        return "Process component config file not found or unreadable: '" +
+               out.source_path + "'.";
+    return parse_component_config_stream(in, out.source_path, out);
+}
+
+// ===========================================================================
+// Registry (IO1)
+// ===========================================================================
+
+ProcessComponentRegistry::ProcessComponentRegistry() {
+    // Planned built-in ids (TRANSPORT_IO_PLUGIN_CONFIG_PLAN §2). A
+    // registration line for one of these before its phase lands produces a
+    // precise diagnostic instead of "unknown component id". Entries are
+    // OVERWRITTEN by register_component() when the implementation arrives.
+    const struct { const char* id; const char* desc; const char* phase; } planned[] = {
+        {"org.hydrocouple.openswmm.reactions",
+         "Multispecies reaction system (EPANET-MSX conventions)", "R1 (reactions plan)"},
+        {"org.hydrocouple.openswmm.transport.ard",
+         "Eulerian ARD transport engine configuration", "E5 (Eulerian ARD plan)"},
+        {"org.hydrocouple.openswmm.transport.lard",
+         "Lagrangian (LARD) quality engine", "T5 (LARD plan)"},
+        {"org.hydrocouple.openswmm.heat",
+         "1D heat transport flux modules", "H1 (heat plan)"},
+        {"org.hydrocouple.openswmm.waterage",
+         "Water age tracking coordinator", "A1 (water age plan)"},
+        {"org.hydrocouple.openswmm.integrated2d",
+         "Unified 2D surface + two-zone groundwater component", "S1/G1 (2D + GW plans)"},
+    };
+    for (const auto& pl : planned)
+        entries_[pl.id] =
+            ProcessComponentEntry{pl.desc, pl.phase, nullptr, nullptr};
+}
+
+ProcessComponentRegistry& ProcessComponentRegistry::instance() {
+    static ProcessComponentRegistry reg;
+    return reg;
+}
+
+void ProcessComponentRegistry::register_component(const std::string& id,
+                                                  std::string description,
+                                                  ComponentConfigApply apply,
+                                                  ComponentConfigSave save) {
+    entries_[id] =
+        ProcessComponentEntry{std::move(description), std::string{},
+                              std::move(apply), std::move(save)};
+}
+
+const ProcessComponentEntry* ProcessComponentRegistry::find(
+    const std::string& id) const {
+    const auto it = entries_.find(id);
+    return (it == entries_.end()) ? nullptr : &it->second;
+}
+
+std::vector ProcessComponentRegistry::known_ids() const {
+    std::vector ids;
+    ids.reserve(entries_.size());
+    for (const auto& e : entries_) ids.push_back(e.first);
+    return ids;
+}
+
+// ===========================================================================
+// Resolution (IO1) — called from SWMMEngine::open after the input read
+// ===========================================================================
+
+std::vector resolve_process_components(SimulationContext& ctx,
+                                                    const std::string& base_dir) {
+    std::vector errors;
+    auto& reg = ProcessComponentRegistry::instance();
+
+    // Duplicate registrations are refused (IO1 validation finding, resolved
+    // per the R1 proposal): two rows for one id would run apply() twice with
+    // undefined precedence.
+    {
+        std::vector seen;
+        for (const auto& spec : ctx.process_component_specs) {
+            for (const auto& s0 : seen)
+                if (s0 == spec.id) {
+                    errors.push_back(
+                        "[PROCESS_COMPONENTS] duplicate registration of '" +
+                        spec.id + "' — each component id may appear once.");
+                    break;
+                }
+            seen.push_back(spec.id);
+        }
+        if (!errors.empty()) return errors;
+    }
+
+    for (auto& spec : ctx.process_component_specs) {
+        if (looks_like_library(spec.id)) {
+            errors.push_back(
+                "[PROCESS_COMPONENTS] '" + spec.id +
+                "': library-loaded HydroCouple components are not available "
+                "yet (arrives with plan phase HC2 — "
+                "IMPLEMENTATION_ROADMAP.md).");
+            continue;
+        }
+        const ProcessComponentEntry* entry = reg.find(spec.id);
+        if (entry == nullptr) {
+            std::string msg = "[PROCESS_COMPONENTS] unknown component id '" +
+                              spec.id + "'. Known ids:";
+            for (const auto& id : reg.known_ids()) msg += " " + id;
+            errors.push_back(msg);
+            continue;
+        }
+        if (!entry->pending_phase.empty()) {
+            errors.push_back(
+                "[PROCESS_COMPONENTS] '" + spec.id + "' (" +
+                entry->description +
+                ") is recognized but not yet implemented — arrives with "
+                "plan phase " + entry->pending_phase + ".");
+            continue;
+        }
+        if (spec.config_path.empty()) {
+            errors.push_back(
+                "[PROCESS_COMPONENTS] '" + spec.id +
+                "': missing required config=\"…\" argument.");
+            continue;
+        }
+        ComponentConfigSections config;
+        const std::string err =
+            read_component_config(spec.config_path, base_dir, config);
+        if (!err.empty()) {
+            errors.push_back(err);
+            continue;
+        }
+        // IO3: remember where the config was actually read from so a
+        // save-as can copy the file alongside the written .inp.
+        spec.resolved_config_path = config.source_path;
+        entry->apply(ctx, spec, config, errors);
+    }
+    return errors;
+}
+
+}  // namespace openswmm::components
diff --git a/src/engine/plugins/ProcessComponentRegistry.hpp b/src/engine/plugins/ProcessComponentRegistry.hpp
new file mode 100644
index 000000000..dc80b03fb
--- /dev/null
+++ b/src/engine/plugins/ProcessComponentRegistry.hpp
@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ProcessComponentRegistry.hpp
+ * @brief Registry + config-file delivery for [PROCESS_COMPONENTS]
+ *        (Unified Transport suite D-UT8; phases IO1–IO2).
+ *
+ * @details Maps component ids to their config-apply hooks. Built-in engine
+ *          components (reactions, water age, heat, transport engines,
+ *          integrated2d) register here as their plan phases land; the ids
+ *          are pre-declared so a registration line for a planned-but-not-
+ *          yet-implemented component produces a precise diagnostic instead
+ *          of "unknown id". Library-loaded HydroCouple components
+ *          (`hydrocouple_component_info()`) arrive with phase HC2 and will
+ *          resolve through PluginFactory discovery before falling back to
+ *          this table.
+ *
+ *          Config files are the component's own `.inp`-dialect file
+ *          (bracketed sections, `;;` comments), parsed by
+ *          read_component_config() with the [2D_MESH_FILE] path rules:
+ *          relative paths resolve against the parent .inp's directory, one
+ *          level only (a [PROCESS_COMPONENTS] section inside a component
+ *          file is an error), parse failures are fatal.
+ *
+ * @see plans/transport/TRANSPORT_IO_PLUGIN_CONFIG_PLAN.md §2–§3
+ * @ingroup engine_plugins
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_PLUGINS_PROCESS_COMPONENT_REGISTRY_HPP
+#define OPENSWMM_ENGINE_PLUGINS_PROCESS_COMPONENT_REGISTRY_HPP
+
+#include 
+#include 
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+struct ProcessComponentSpec;
+}
+
+namespace openswmm::components {
+
+/// A component config file split into its bracketed sections, in file order.
+/// Section tags are upper-cased; lines are verbatim minus blank and
+/// comment-only lines.
+struct ComponentConfigSections {
+    std::string source_path;  ///< resolved absolute/effective path
+    std::vector>> sections;
+
+    /// First section with this tag, or nullptr.
+    const std::vector* find(const std::string& upper_tag) const {
+        for (const auto& s : sections)
+            if (s.first == upper_tag) return &s.second;
+        return nullptr;
+    }
+};
+
+/**
+ * @brief Parse a component configuration file (phase IO2).
+ *
+ * @param path      As given in `config="…"`.
+ * @param base_dir  Directory of the parent .inp ("" ⇒ cwd) — relative
+ *                  paths resolve against it ([2D_MESH_FILE] §3).
+ * @param out       [out] cleared and filled.
+ * @return          Empty string on success, else a fatal diagnostic
+ *                  (missing file, unreadable, nested [PROCESS_COMPONENTS]).
+ */
+std::string read_component_config(const std::string& path,
+                                  const std::string& base_dir,
+                                  ComponentConfigSections& out);
+
+/// Parse config TEXT (same dialect/rules as read_component_config) —
+/// E-C3's swmm_reactions_check_text / apply_text surface. @p label names
+/// the source in diagnostics.
+std::string parse_component_config_text(const std::string& text,
+                                        const std::string& label,
+                                        ComponentConfigSections& out);
+
+/// Apply hook: consume the parsed config into engine state. Push
+/// diagnostics into `errors` (fatal) — never throw.
+using ComponentConfigApply =
+    std::function& errors)>;
+
+/**
+ * @brief Save hook (IO3a): render this component's CURRENT engine state back
+ *        to config-file text — the inverse of ::ComponentConfigApply.
+ *
+ * @details Until this existed, `swmm_model_write` emitted the
+ *          `[PROCESS_COMPONENTS]` `config=` PATH and copied the file the model
+ *          was read from, but nothing rewrote its CONTENT. So every edit made
+ *          through a C API or the GUI — a `[HEAT_SOURCES]` temperature, a
+ *          reaction expression — was **silently lost on save**, while a
+ *          hand-edit of the same file persisted. `InpWriter`'s own comment
+ *          states the intended division ("the component config FILES are each
+ *          component's own to write, never ours"); this is the hook that lets
+ *          a component honour it.
+ *
+ * @return  the complete config-file text, or **empty to decline** — an empty
+ *          return means "I have nothing to serialize", and the writer falls
+ *          back to the IO3 carry-alongside copy. Declining is how a component
+ *          that has not implemented saving yet stays correct rather than
+ *          truncating its own file to nothing.
+ *
+ * @note    `ctx` is CONST. A save must not mutate the model it is describing;
+ *          that is the property that makes writing twice give the same file.
+ */
+using ComponentConfigSave =
+    std::function;
+
+struct ProcessComponentEntry {
+    std::string description;      ///< short human-readable description
+    std::string pending_phase;    ///< non-empty ⇒ planned, not yet implemented
+    ComponentConfigApply apply;   ///< null for planned entries
+    /// IO3a. Null until a component implements serialization; the writer then
+    /// falls back to copying, so components can adopt this ONE AT A TIME
+    /// without any intermediate state losing data.
+    ComponentConfigSave  save;
+};
+
+/**
+ * @brief Process-global id → entry table.
+ *
+ * @details Planned built-in ids are pre-seeded (see the .cpp); implemented
+ *          components overwrite their entry via register_component() at
+ *          engine static-init or test setup. Not thread-safe for
+ *          registration (register at startup only).
+ */
+class ProcessComponentRegistry {
+public:
+    static ProcessComponentRegistry& instance();
+
+    /// @param save IO3a serialization hook; DEFAULTED so every existing
+    ///             registration compiles unchanged and components adopt
+    ///             saving one at a time (a null save falls back to the
+    ///             carry-alongside copy, which is what they do today).
+    void register_component(const std::string& id, std::string description,
+                            ComponentConfigApply apply,
+                            ComponentConfigSave save = nullptr);
+
+    const ProcessComponentEntry* find(const std::string& id) const;
+    std::vector known_ids() const;
+
+private:
+    ProcessComponentRegistry();
+    std::map entries_;
+};
+
+/**
+ * @brief Resolve every [PROCESS_COMPONENTS] spec (phase IO1): look up the
+ *        id, read its config file, and invoke the apply hook.
+ *
+ * @param base_dir Directory of the parent .inp for relative config paths.
+ * @return Diagnostics; empty ⇒ all specs resolved and applied. The caller
+ *         (SWMMEngine::open) decides fatality/leniency, mirroring the
+ *         external-2D-mesh handling.
+ */
+std::vector resolve_process_components(SimulationContext& ctx,
+                                                    const std::string& base_dir);
+
+}  // namespace openswmm::components
+
+#endif  // OPENSWMM_ENGINE_PLUGINS_PROCESS_COMPONENT_REGISTRY_HPP
diff --git a/src/engine/quality/Landuse.cpp b/src/engine/quality/Landuse.cpp
index 72532e4a0..ad6640fcb 100644
--- a/src/engine/quality/Landuse.cpp
+++ b/src/engine/quality/Landuse.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Landuse.cpp
  * @brief Pollutant buildup/washoff — batch SoA, numerically identical to legacy.
@@ -5,7 +21,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Landuse.hpp"
diff --git a/src/engine/quality/Landuse.hpp b/src/engine/quality/Landuse.hpp
index 43884d61f..5d2bdc93b 100644
--- a/src/engine/quality/Landuse.hpp
+++ b/src/engine/quality/Landuse.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Landuse.hpp
  * @brief Pollutant buildup and washoff per land use — batch SoA.
@@ -24,7 +40,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_LANDUSE_HPP
diff --git a/src/engine/quality/MsxSurfaceQuality.cpp b/src/engine/quality/MsxSurfaceQuality.cpp
new file mode 100644
index 000000000..828d4aba1
--- /dev/null
+++ b/src/engine/quality/MsxSurfaceQuality.cpp
@@ -0,0 +1,503 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxSurfaceQuality.cpp
+ * @brief BW-MSX — see MsxSurfaceQuality.hpp. Every formula below is the
+ *        pollutant step's (SWMMEngine::stepSurfaceQuality / A7 sweeping /
+ *        initialize 11b), transcribed with `p → m` and the pollutant arrays
+ *        replaced by `ReactionData::surface`. Keep them in lock-step: the
+ *        BW-MSX gate asserts an MSX species with a pollutant's parameters
+ *        produces the pollutant's loads bit-for-bit.
+ */
+
+#include "MsxSurfaceQuality.hpp"
+
+#include 
+#include 
+#include 
+#include 
+
+#include "../core/DateTime.hpp"
+#include "../core/SimulationContext.hpp"
+#include "../core/UnitConversion.hpp"
+
+namespace openswmm::msxsurf {
+
+namespace {
+
+constexpr double kMinRunoffRate = 1.0e-9;   // ft/s threshold (stepSurfaceQuality)
+constexpr double kLperFt3       = 28.317;
+
+std::string upper(std::string s) {
+    for (auto& c : s) c = static_cast(std::toupper(static_cast(c)));
+    return s;
+}
+
+
+/// Buildup function forward form (mass per normalizer unit after `days`).
+double buildupAt(int type, double c0, double c1, double c2, double days) {
+    if (!(days > 0.0)) return 0.0;
+    switch (type) {
+        case 1: return std::min(c1 * std::pow(days, c2), c0);                        // POW
+        case 2: return c0 * (1.0 - std::exp(-c1 * days));                            // EXP
+        case 3: return (c2 + days > 0.0) ? c0 * days / (c2 + days) : 0.0;            // SAT
+        default: return 0.0;
+    }
+}
+
+} // namespace
+
+double speciesUnitFactor(const std::string& units, const SimulationOptions& opts) {
+    // D-A27: concentration-mass → user-mass factor from the species' units.
+    const double mass_ucf = ucf::UCF(ucf::MASS, opts);
+    const std::string u = upper(units);
+    if (u.rfind("UG", 0) == 0) return mass_ucf / 1000.0;
+    if (u.rfind("MG", 0) == 0) return mass_ucf;
+    return 1.0;   // MMOL, counts, dimensionless: the pollutant COUNTS rule
+}
+
+bool active(const SimulationContext& ctx) noexcept {
+    return ctx.reactions.surface.active();
+}
+
+namespace {
+
+/// A parked row whose constituent turns out to be a pollutant declared
+/// later in the file than the section that named it: apply it to the
+/// pollutant tables now (the handlers dispatch in file order and used to
+/// drop such rows silently). Returns true when consumed.
+bool applyLatePollutantRow(SimulationContext& ctx, const MsxSurfaceRows::Buildup& r) {
+    const int p = ctx.pollutant_names.find(r.species);
+    const int lu = ctx.landuse_names.find(r.landuse);
+    if (p < 0 || lu < 0) return p >= 0;
+    const int np = ctx.n_pollutants(), nlu = ctx.n_landuses();
+    if (ctx.buildup.n_landuses != nlu || ctx.buildup.n_pollutants != np)
+        ctx.buildup.resize(nlu, np);
+    const auto k = static_cast(lu * np + p);
+    ctx.buildup.func_type[k] = r.func_type;
+    ctx.buildup.coeff1[k] = r.c1; ctx.buildup.coeff2[k] = r.c2;
+    ctx.buildup.coeff3[k] = (r.func_type == 4) ? static_cast(ctx.find_timeseries(r.ts_name)) : r.c3;
+    ctx.buildup.normalizer[k] = r.normalizer;
+    return true;
+}
+bool applyLatePollutantRow(SimulationContext& ctx, const MsxSurfaceRows::Washoff& r) {
+    const int p = ctx.pollutant_names.find(r.species);
+    const int lu = ctx.landuse_names.find(r.landuse);
+    if (p < 0 || lu < 0) return p >= 0;
+    const int np = ctx.n_pollutants(), nlu = ctx.n_landuses();
+    if (ctx.washoff.n_landuses != nlu || ctx.washoff.n_pollutants != np)
+        ctx.washoff.resize(nlu, np);
+    const auto k = static_cast(lu * np + p);
+    ctx.washoff.func_type[k] = r.func_type;
+    ctx.washoff.coeff[k] = r.coeff; ctx.washoff.expon[k] = r.expon;
+    ctx.washoff.sweep_effic[k] = r.sweep_effic; ctx.washoff.bmp_effic[k] = r.bmp_effic;
+    return true;
+}
+bool applyLatePollutantRow(SimulationContext& ctx, const MsxSurfaceRows::Loading& r) {
+    const int p = ctx.pollutant_names.find(r.species);
+    if (p < 0) return false;
+    const int sc = ctx.subcatch_names.find(r.subcatch);
+    const int np = ctx.n_pollutants();
+    if (sc >= 0 && ctx.subcatches.conc_n_pollutants == np) {
+        const auto k = static_cast(sc * np + p);
+        if (k < ctx.subcatches.conc.size()) ctx.subcatches.conc[k] = r.value;
+    }
+    return true;
+}
+
+} // namespace
+
+std::vector resolve(SimulationContext& ctx) {
+    std::vector warnings;
+    auto& s  = ctx.reactions.surface;
+    s.resolved = false;
+    if (s.rows.empty()) return warnings;
+
+    // Rows naming a pollutant declared after the section go back to the
+    // pollutant tables; what remains is MSX (or a typo).
+    {
+        MsxSurfaceRows keep;
+        for (const auto& r : s.rows.buildup)  if (!applyLatePollutantRow(ctx, r)) keep.buildup.push_back(r);
+        for (const auto& r : s.rows.washoff)  if (!applyLatePollutantRow(ctx, r)) keep.washoff.push_back(r);
+        for (const auto& r : s.rows.loadings) if (!applyLatePollutantRow(ctx, r)) keep.loadings.push_back(r);
+        s.rows = std::move(keep);
+    }
+    const auto& rows = s.rows;
+    if (rows.empty()) return warnings;
+
+    const int nm  = ctx.reactions.configured ? ctx.reactions.n_species() : 0;
+    const int nlu = ctx.n_landuses();
+    const int nsc = ctx.n_subcatches();
+    if (nm <= 0) {
+        warnings.push_back(
+            "[BUILDUP]/[WASHOFF]/[LOADINGS]: " +
+            std::to_string(rows.buildup.size() + rows.washoff.size() + rows.loadings.size()) +
+            " row(s) name a constituent that is neither a [POLLUTANTS] entry nor "
+            "a reactions-component species; they are ignored.");
+        return warnings;
+    }
+    s.resize_params(std::max(nlu, 0), nm);
+    s.init_loading.assign(static_cast(std::max(nsc, 0)) *
+                          static_cast(nm), 0.0);
+    for (int m = 0; m < nm; ++m)
+        s.mcf[static_cast(m)] =
+            speciesUnitFactor(static_cast(m) < ctx.reactions.species_units.size()
+                           ? ctx.reactions.species_units[static_cast(m)]
+                           : std::string{},
+                       ctx.options);
+
+    auto species = [&](const std::string& name, const char* section) -> int {
+        const int m = ctx.reactions.find_species(name);
+        if (m < 0) {
+            warnings.push_back(std::string("[") + section + "] '" + name +
+                               "' is neither a pollutant nor a reactions-component "
+                               "species; row ignored.");
+            return -1;
+        }
+        if (static_cast(m) < ctx.reactions.species_is_wall.size() &&
+            ctx.reactions.species_is_wall[static_cast(m)]) {
+            warnings.push_back(std::string("[") + section + "] '" + name +
+                               "' is a WALL species and cannot build up on a "
+                               "surface; row ignored.");
+            return -1;
+        }
+        return m;
+    };
+    auto landuse = [&](const std::string& name, const char* section) -> int {
+        const int lu = ctx.landuse_names.find(name);
+        if (lu < 0)
+            warnings.push_back(std::string("[") + section + "] land use '" + name +
+                               "' is not defined; row ignored.");
+        return lu;
+    };
+
+    bool any = false;
+    for (const auto& r : rows.buildup) {
+        const int lu = landuse(r.landuse, "BUILDUP"); if (lu < 0) continue;
+        const int m  = species(r.species, "BUILDUP");  if (m  < 0) continue;
+        const auto k = s.pidx(lu, m);
+        s.bu_type[k] = r.func_type;
+        s.bu_c1[k] = r.c1; s.bu_c2[k] = r.c2;
+        if (r.func_type == 4) {
+            const int ts = ctx.find_timeseries(r.ts_name);
+            if (ts < 0)
+                warnings.push_back("[BUILDUP] EXT time series '" + r.ts_name +
+                                   "' for '" + r.species + "' not found; no external buildup.");
+            s.bu_c3[k] = static_cast(ts);
+        } else {
+            s.bu_c3[k] = r.c3;
+        }
+        s.bu_normalizer[k] = r.normalizer;
+        any = any || r.func_type != 0;
+    }
+    for (const auto& r : rows.washoff) {
+        const int lu = landuse(r.landuse, "WASHOFF"); if (lu < 0) continue;
+        const int m  = species(r.species, "WASHOFF");  if (m  < 0) continue;
+        const auto k = s.pidx(lu, m);
+        s.wo_type[k] = r.func_type;
+        s.wo_coeff[k] = r.coeff; s.wo_expon[k] = r.expon;
+        s.wo_sweep_effic[k] = r.sweep_effic; s.wo_bmp_effic[k] = r.bmp_effic;
+        any = any || r.func_type != 0;
+    }
+    for (const auto& r : rows.loadings) {
+        const int sc = ctx.subcatch_names.find(r.subcatch);
+        if (sc < 0) {
+            warnings.push_back("[LOADINGS] subcatchment '" + r.subcatch +
+                               "' is not defined; row ignored.");
+            continue;
+        }
+        const int m = species(r.species, "LOADINGS"); if (m < 0) continue;
+        s.init_loading[s.sidx(sc, m)] = r.value;
+        any = true;
+    }
+    s.resolved = any && nlu > 0;
+    refreshDerived(ctx);
+    return warnings;
+}
+
+void refreshDerived(SimulationContext& ctx) noexcept {
+    auto& s = ctx.reactions.surface;
+    for (std::size_t k = 0; k < s.bu_type.size(); ++k) {
+        const double c0 = s.bu_c1[k], c1 = s.bu_c2[k], c2 = s.bu_c3[k];
+        double md = 0.0;
+        // refreshLanduseParams(): time to reach 99.9 % of the maximum
+        if (s.bu_type[k] == 2 && c1 > 0.0)                               md = -std::log(0.001) / c1;
+        else if (s.bu_type[k] == 1 && c1 > 0.0 && c2 > 0.0 && c0 > 0.0) md = std::pow(c0 / c1, 1.0 / c2);
+        else if (s.bu_type[k] == 3 && c2 > 0.0 && c0 > 0.0)             md = 999.0 * c2;
+        s.bu_max_days[k] = md;
+    }
+}
+
+void initState(SimulationContext& ctx) {
+    auto& s = ctx.reactions.surface;
+    if (!s.active()) return;
+    const int nsc = ctx.n_subcatches(), nlu = s.n_landuses, nm = s.n_species;
+    s.resize_state(nsc);
+    const double dry_days = ctx.options.dry_days;
+    // Legacy landuse_getInitBuildup: a supplied initial loading wins (per unit
+    // area, so it is stored per normalizer unit directly for PER_AREA land
+    // uses); otherwise the buildup function over the antecedent dry period.
+    for (int i = 0; i < nsc; ++i) {
+        const auto ui = static_cast(i);
+        for (int lu = 0; lu < nlu; ++lu) {
+            const auto cov = ui * static_cast(nlu) + static_cast(lu);
+            const double frac = (cov < ctx.subcatches.coverage.size())
+                                    ? ctx.subcatches.coverage[cov] / 100.0 : 0.0;
+            if (frac <= 0.0) continue;
+            for (int m = 0; m < nm; ++m) {
+                const auto k = s.pidx(lu, m);
+                const double norm = (s.bu_normalizer[k] == 0)
+                                        ? frac * ctx.subcatches.area[ui]
+                                        : frac * ctx.subcatches.curb_length[ui];
+                double mass = 0.0;
+                const double load0 = s.init_loading[s.sidx(i, m)];
+                if (load0 > 0.0) {
+                    // Legacy: absolute mass = loading × land-use AREA, whatever
+                    // the normalizer; per normalizer unit that is the loading
+                    // itself for PER_AREA and loading × area / curb for PER_CURB.
+                    if (s.bu_normalizer[k] == 0)
+                        mass = load0;
+                    else
+                        mass = (ctx.subcatches.curb_length[ui] > 0.0)
+                                   ? load0 * ctx.subcatches.area[ui] / ctx.subcatches.curb_length[ui]
+                                   : 0.0;
+                } else if (dry_days > 0.0 && s.bu_type[k] != 0 && s.bu_type[k] != 4) {
+                    mass = buildupAt(s.bu_type[k], s.bu_c1[k], s.bu_c2[k], s.bu_c3[k], dry_days);
+                }
+                if (mass <= 0.0) continue;
+                s.buildup[s.bu_idx(i, lu, m)] = mass;
+                s.led_init_buildup[static_cast(m)] += mass * norm;
+            }
+        }
+    }
+}
+
+void step(SimulationContext& ctx, double dt_runoff, double abs_time) {
+    auto& s = ctx.reactions.surface;
+    if (!s.active() || !(dt_runoff > 0.0)) return;
+    const int nsc = ctx.n_subcatches(), nlu = s.n_landuses, nm = s.n_species;
+    const double dt_days = dt_runoff / ucf::SEC_PER_DAY;
+    const double ucf_rain = ucf::UCF(ucf::RAINFALL, ctx.options);
+    const double ucf_flow = ucf::UCF(ucf::FLOW, ctx.options);
+
+    for (int i = 0; i < nsc; ++i) {
+        const auto ui = static_cast(i);
+        const double q       = ctx.subcatches.runoff[ui];    // cfs
+        const double area_ac = ctx.subcatches.area[ui];      // acres (LANDAREA units)
+        // legacy's washoff `runoff` argument: the area-averaged subarea rate
+        // in ft/sec (subcatch_getRunoff's return). Shared with the pollutant
+        // kernel so the two stay bit-identical — deriving it here as
+        // q / area_ft2 lands a ULP away, because q has round-tripped through
+        // a volume (Voutflow * dt / dt).
+        const double runoff_fts = (ui < ctx.subcatches.subarea_runoff_rate.size())
+                                ? ctx.subcatches.subarea_runoff_rate[ui] : 0.0;
+        for (int m = 0; m < nm; ++m) {
+            const double mcf_m = s.mcf[static_cast(m)];
+            double total_load = 0.0;   // concentration-mass units / s
+            for (int lu = 0; lu < nlu; ++lu) {
+                const auto cov = ui * static_cast(nlu) + static_cast(lu);
+                const double frac = (cov < ctx.subcatches.coverage.size())
+                                        ? ctx.subcatches.coverage[cov] / 100.0 : 0.0;
+                if (frac <= 0.0) continue;
+                const auto k  = s.pidx(lu, m);
+                const auto bu = s.bu_idx(i, lu, m);
+                const int  bt = s.bu_type[k];
+                const double norm = (s.bu_normalizer[k] == 0)
+                                        ? frac * area_ac : frac * ctx.subcatches.curb_length[ui];
+
+                // --- Buildup accumulation (stepSurfaceQuality) ---------------
+                // Legacy accumulates buildup ONLY while the subcatchment is
+                // effectively dry (runoff.c:280 guards surfqual_getBuildup
+                // with `runoff < MIN_RUNOFF`), the exact complement of the
+                // washoff gate below. The pollutant kernel carries the same
+                // condition and SameParametersSameSurfaceLoads asserts the
+                // two stay bit-identical, so they move together.
+                if (bt != 0 && runoff_fts < 2.31481e-8) {
+                    double mass = s.buildup[bu];
+                    if (bt == 4) {                                   // EXTERNAL
+                        const double max_bu = s.bu_c1[k], sf = s.bu_c2[k];
+                        const int ts_idx = static_cast(s.bu_c3[k]);
+                        double rate = 0.0;
+                        if (ts_idx >= 0 && ts_idx < static_cast(ctx.tables.tables.size()))
+                            rate = sf * table_lookup_cursor(
+                                ctx.tables.tables[static_cast(ts_idx)], abs_time);
+                        double new_mass = std::min(mass + rate * dt_days, max_bu);
+                        new_mass = std::max(new_mass, 0.0);
+                        const double change = new_mass - mass;
+                        if (change != 0.0) {
+                            s.buildup[bu] = new_mass;
+                            s.led_buildup[static_cast(m)] += change * norm;
+                        }
+                    } else {
+                        const double c0 = s.bu_c1[k], c1 = s.bu_c2[k], c2 = s.bu_c3[k];
+                        double days = 0.0;
+                        if (mass > 0.0) {
+                            switch (bt) {                            // inverse: mass → days
+                                case 1: days = (c1 * c2 > 0.0) ? std::pow(mass / c1, 1.0 / c2) : 0.0; break;
+                                case 2: days = (c0 * c1 > 0.0 && mass < c0) ? -std::log(1.0 - mass / c0) / c1 : 0.0; break;
+                                case 3: days = (c0 > mass) ? mass * c2 / (c0 - mass) : s.bu_max_days[k]; break;
+                                default: break;
+                            }
+                        }
+                        days += dt_days;
+                        // legacy surfqual.c:149 `MAX(newBuildup, oldBuildup)`
+                        // — buildup never decreases across a step.
+                        const double new_mass =
+                            std::max(buildupAt(bt, c0, c1, c2, days), mass);
+                        const double change = new_mass - mass;
+                        s.buildup[bu] = new_mass;
+                        if (change > 0.0)
+                            s.led_buildup[static_cast(m)] += change * norm;
+                    }
+                }
+
+                // --- Washoff (stepSurfaceQuality) -----------------------------
+                const int wt = s.wo_type[k];
+                // legacy findWashoffLoads returns below MIN_RUNOFF
+                // (2.31481e-8 ft/sec), on the ft/sec rate.
+                // legacy landuse_getWashoffLoad makes the load PROPORTIONAL to
+                // vOutflow, so a subcatchment that sheds nothing washes off
+                // nothing whatever is on the ground. `q` is that number
+                // (Voutflow/tStep); the pollutant kernel carries the same
+                // condition and SameParametersSameSurfaceLoads holds the two
+                // together.
+                if (wt != 0 && runoff_fts >= 2.31481e-8 && q > 0.0) {
+                    const double buildup  = s.buildup[bu];
+                    // legacy keeps Subcatch.area in ft2 as area / UCF(LANDAREA)
+                    // — 43561.6 ft2 per ACRE, 107639 per HECTARE. The
+                    // exact-acre constant is 3.7e-5 off on a US deck and a
+                    // factor 2.471 off on an SI one. The pollutant path
+                    // (SWMMEngine::stepSurfaceQuality) carries the same
+                    // correction; SameParametersSameSurfaceLoads asserts the
+                    // two stay bit-identical, so they move together.
+                    const double area_ft2 =
+                        area_ac / ucf::UCF(ucf::LANDAREA, ctx.options);
+                    (void)area_ft2;
+                    const double q_expon  = runoff_fts * ucf_rain;
+                    const double q_flow   = q * ucf_flow;
+                    double load = 0.0;
+                    switch (wt) {
+                        case 3: load = s.wo_coeff[k] * kLperFt3 * q * frac; break;                 // EMC
+                        case 1:                                                                    // EXP
+                            if (buildup > 0.0 && mcf_m > 0.0)
+                                load = (s.wo_coeff[k] / 3600.0) * std::pow(q_expon, s.wo_expon[k])
+                                     * (buildup * norm) / mcf_m;
+                            break;
+                        case 2: load = s.wo_coeff[k] * std::pow(q_flow, s.wo_expon[k]) * frac; break; // RC
+                        default: break;
+                    }
+                    const double avail    = (mcf_m > 0.0) ? (buildup * norm) / mcf_m : 0.0;
+                    const double max_load = avail / dt_runoff;
+                    if (load > max_load && wt != 3) load = max_load;
+
+                    const double washed_mass = load * mcf_m * dt_runoff;
+                    if (bt == 0 && washed_mass > buildup * norm) {
+                        // no buildup function: book the washoff as buildup so the
+                        // ledger balances (landuse.c:585-593)
+                        s.led_buildup[static_cast(m)] += washed_mass;
+                        s.buildup[bu] = 0.0;
+                    } else if (norm > 0.0) {
+                        s.buildup[bu] = std::max(s.buildup[bu] - washed_mass / norm, 0.0);
+                    }
+                    const double bmp_removed = load * (s.wo_bmp_effic[k] / 100.0);
+                    if (bmp_removed > 0.0) {
+                        s.led_bmp_removal[static_cast(m)] += bmp_removed * dt_runoff * mcf_m;
+                        load -= bmp_removed;
+                    }
+                    total_load += load;
+                }
+            }
+
+            // Reported concentration (surfqual.c:370) and the two bookings.
+            double conc = 0.0;
+            if (q > kMinRunoffRate && total_load > 0.0) conc = total_load / q / kLperFt3;
+            s.washoff_conc[s.sidx(i, m)] = conc;
+            if (total_load > 0.0) {
+                const double mass = total_load * dt_runoff * mcf_m;
+                const bool reaches_system =
+                    (ctx.subcatches.outlet_node[ui] >= 0 ||
+                     ctx.subcatches.outlet_subcatch[ui] == i);
+                if (reaches_system) s.led_runoff_load[static_cast(m)] += mass;
+                s.led_subcatch_load[s.sidx(i, m)] += mass;
+            }
+        }
+    }
+}
+
+void sweep(SimulationContext& ctx, int sc, int lu, double frac, double removal_frac) {
+    auto& s = ctx.reactions.surface;
+    if (!s.active() || sc < 0 || sc >= s.n_subcatch || lu < 0 || lu >= s.n_landuses) return;
+    const auto ui = static_cast(sc);
+    for (int m = 0; m < s.n_species; ++m) {
+        const auto k  = s.pidx(lu, m);
+        const auto bu = s.bu_idx(sc, lu, m);
+        const double effic = s.wo_sweep_effic[k] / 100.0;
+        const double norm = (s.bu_normalizer[k] == 0)
+                                ? frac * ctx.subcatches.area[ui]
+                                : frac * ctx.subcatches.curb_length[ui];
+        const double old_bu  = s.buildup[bu];
+        // legacy surfqual_sweepBuildup (surfqual.c:236-242): clamp the new
+        // store into [0, old] FIRST and book the clamped difference, so the
+        // ledger closes even when removal_frac * effic falls outside [0,1].
+        double new_bu = old_bu * (1.0 - removal_frac * effic);
+        new_bu = std::min(old_bu, new_bu);
+        new_bu = std::max(0.0, new_bu);
+        s.buildup[bu] = new_bu;
+        s.led_sweeping[static_cast(m)] += (old_bu - new_bu) * norm;
+    }
+}
+
+void deliver(SimulationContext& ctx, double /*dt_routing*/) {
+    auto& s = ctx.reactions.surface;
+    if (!s.active()) return;
+    auto& rx = ctx.reactions;
+    const int nm = rx.n_species();
+    if (nm != s.n_species || ctx.n_nodes() <= 0) return;
+    const auto want = static_cast(ctx.n_nodes()) * static_cast(nm);
+    if (rx.msx_ext_mass_in.size() != want) rx.msx_ext_mass_in.assign(want, 0.0);
+    for (int i = 0; i < ctx.n_subcatches(); ++i) {
+        const auto ui = static_cast(i);
+        const int out_node = ctx.subcatches.outlet_node[ui];
+        if (out_node < 0 || out_node >= ctx.n_nodes()) continue;
+        // addWetWeatherLoads, species side. Legacy weights the runoff flow and
+        // the load beside it by where THIS routing instant falls between the
+        // two runoff times; the fixed midpoint that used to stand here
+        // delivered the storm's average every routing step instead of its
+        // schedule. The pollutant kernel carries the same two lines and
+        // LoadReachesTheNetworkUnderBothSolvers holds the two together.
+        const double f  = ctx.runoff_interp_f;
+        const double f1 = 1.0 - f;
+        const double q_old = ctx.subcatches.old_runoff[ui];
+        const double q_new = ctx.subcatches.runoff[ui];
+        const double q = f1 * q_old + f * q_new;
+        if (q <= 0.0) continue;
+        const bool has_old = s.washoff_conc_old.size() == s.washoff_conc.size();
+        const auto base = static_cast(out_node) * static_cast(nm);
+        for (int m = 0; m < nm; ++m) {
+            const auto si = s.sidx(i, m);
+            const double c_new = s.washoff_conc[si];
+            const double c_old = has_old ? s.washoff_conc_old[si] : c_new;
+            // the interpolated PRODUCT runoff*conc, not the product of the two
+            // interpolations (legacy surfqual_getWtdWashoff).
+            const double mass_rate = f1 * (q_old * c_old) + f * (q_new * c_new);
+            if (mass_rate > 0.0)
+                rx.msx_ext_mass_in[base + static_cast(m)] += mass_rate;
+        }
+    }
+}
+
+} // namespace openswmm::msxsurf
diff --git a/src/engine/quality/MsxSurfaceQuality.hpp b/src/engine/quality/MsxSurfaceQuality.hpp
new file mode 100644
index 000000000..1137c5ce3
--- /dev/null
+++ b/src/engine/quality/MsxSurfaceQuality.hpp
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxSurfaceQuality.hpp
+ * @brief BW-MSX (2026-09-19) — buildup, washoff and street sweeping of the
+ *        reactions component's (MSX) species on subcatchment surfaces.
+ *
+ * @details The pollutant surface-quality step (`SWMMEngine::stepSurfaceQuality`,
+ *          the A7 sweeping block and `QualitySolver::addWetWeatherLoads`) is
+ *          keyed by pollutant index throughout. This module runs the SAME
+ *          arithmetic — buildup accrual through the inverse-days form
+ *          (POW / EXP / SAT / EXT), washoff EXP / RC / EMC with legacy's unit
+ *          pre-multiplies, the available-buildup cap, the "no buildup
+ *          function" ledger branch, BMP removal, and the per-(subcatchment,
+ *          land use) sweeping schedule — over a separate MSX-keyed store
+ *          (`ReactionData::surface`, `MsxSurfaceData`), and delivers the
+ *          washoff into `ReactionData::msx_ext_mass_in`, the rate the ARD
+ *          engine, the legacy MSX dispatch and LARD already consume for
+ *          external species loads.
+ *
+ *          What is deliberately NOT mirrored (pollutant-only mechanisms):
+ *          co-pollutant fractions (D-A28), rain concentration / ponded-quality
+ *          mixing and LID wet deposition (MSX species rain in clean, as on the
+ *          2D surface), and any kinetics inside the dry store (D-A29).
+ *
+ *          Units: buildup is user mass (lbs / kg) per normalizer unit; the
+ *          per-species factor `mcf` converts concentration-mass to user mass
+ *          from the species' declared units (D-A27: `MG` → UCF(MASS),
+ *          `UG` → UCF(MASS)/1000, anything else → 1).
+ *
+ *          Design: `plans/transport/OVERLAND_TRANSPORT_HEAT_MSX_PLAN_2026-09-01.md`
+ *          §8.9.
+ *
+ * @ingroup engine_quality
+ */
+
+#ifndef OPENSWMM_ENGINE_QUALITY_MSX_SURFACE_QUALITY_HPP
+#define OPENSWMM_ENGINE_QUALITY_MSX_SURFACE_QUALITY_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+
+struct SimulationContext;
+struct SimulationOptions;
+
+namespace msxsurf {
+
+/// D-A27: concentration-mass → user-mass factor from a species' declared
+/// units (`MG` → UCF(MASS), `UG` → UCF(MASS)/1000, anything else → 1). Shared
+/// with the 2D cell store (S7).
+double speciesUnitFactor(const std::string& units, const SimulationOptions& opts);
+
+/// True once rows resolved to at least one MSX species with a land use.
+bool active(const SimulationContext& ctx) noexcept;
+
+/**
+ * @brief Bind the by-name rows to (land use, species) — call after the
+ *        reactions component has been applied and the name tables are final.
+ * @return Warnings (unresolvable species / land use / subcatchment names,
+ *         WALL species). Never fatal: a typo in a row is a warning here,
+ *         exactly as the pollutant handlers silently skip theirs.
+ */
+std::vector resolve(SimulationContext& ctx);
+
+/// Re-derive `bu_max_days` after a parameter edit (C API).
+void refreshDerived(SimulationContext& ctx) noexcept;
+
+/**
+ * @brief Size the state and seed initial buildup: `[LOADINGS]` row when
+ *        given, else the land use's function at `[OPTIONS] DRY_DAYS`
+ *        (legacy `landuse_getInitBuildup`).
+ */
+void initState(SimulationContext& ctx);
+
+/**
+ * @brief One runoff step: buildup accrual then washoff for every
+ *        (subcatchment, land use, species); stores the washoff
+ *        concentration per (subcatchment, species) for delivery.
+ * @param dt_runoff   runoff step (s)
+ * @param abs_time    absolute date-time at the start of the step (EXT buildup)
+ */
+void step(SimulationContext& ctx, double dt_runoff, double abs_time);
+
+/**
+ * @brief Sweeping removal on the (subcatchment, land use) event the A7 block
+ *        fires — called AFTER that block has reset the shared
+ *        `sweep_last_swept` counter, with the same coverage fraction and
+ *        land-use removal fraction.
+ */
+void sweep(SimulationContext& ctx, int sc, int lu, double frac, double removal_frac);
+
+/**
+ * @brief Deliver this routing step's washoff into `msx_ext_mass_in`
+ *        (+= washoff_conc × q̄ per outlet node, the `addWetWeatherLoads`
+ *        trapezoid on old/new runoff). Call after the external-inflow
+ *        assembly has (re)zeroed the array for the step.
+ */
+void deliver(SimulationContext& ctx, double dt_routing);
+
+} // namespace msxsurf
+} // namespace openswmm
+
+#endif // OPENSWMM_ENGINE_QUALITY_MSX_SURFACE_QUALITY_HPP
diff --git a/src/engine/quality/NegativeSources.hpp b/src/engine/quality/NegativeSources.hpp
new file mode 100644
index 000000000..e763cf0db
--- /dev/null
+++ b/src/engine/quality/NegativeSources.hpp
@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file NegativeSources.hpp
+ * @brief D-NS1: one clamp-bookkeeping seam for all three quality engines.
+ *
+ * @details Subplan §3.1 (user requirement, 2026-08-23): negative sources
+ *          (mass extraction) are legal; extraction beyond an element's
+ *          held mass clamps to the available amount, the ledger books the
+ *          mass ACTUALLY removed (the shortfall is un-booked from the
+ *          extraction's own row — otherwise continuity breaks by
+ *          construction), and the counts are
+ *          summarized at end of run. LEGACY, ARD, and LARD all call the
+ *          same helper so the semantics cannot drift apart (the lesson-52
+ *          family, applied prospectively).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_QUALITY_NEGATIVE_SOURCES_HPP
+#define OPENSWMM_QUALITY_NEGATIVE_SOURCES_HPP
+
+#include 
+
+#include "../core/SimulationContext.hpp"
+
+namespace openswmm {
+namespace quality {
+
+/**
+ * @brief Book one pollutant-row clamp: count it and un-book the shortfall
+ *        from the external-extraction ledger row.
+ *
+ * @note NO per-clamp warning. There was one until 2026-08-29; it fired on
+ *       every correct extraction deck, because during fill every cell is
+ *       near-empty and any extraction clamps trivially (measured: 108 clamps
+ *       on a deck extracting 40 % of its inflow). A notice that fires on
+ *       ordinary models is one users learn to ignore — which destroys it on
+ *       the models where it matters (lesson 148). The end-of-run summary
+ *       carries the count and the unmet mass; that is the diagnostic.
+ *
+ * @param shortfall  the UNMET extraction (positive, internal mass units).
+ */
+inline void bookNegativeSourceClamp(SimulationContext& ctx, int node, int p,
+                                    double shortfall) {
+    auto& st = ctx.negsrc;
+    st.clamp_events += 1;
+    st.shortfall_mass += shortfall;
+    // The negative request was booked (signed) into qual_routing_ex_in by
+    // the loaders; the unmet part did not actually leave the water, so it
+    // is returned to the row. v1 scope: EXTERNAL_INFLOW and the API flux
+    // are the admitted negative pathways, and both book into ex_in —
+    // negative DWF/GW/RDII concentrations remain out of scope, recorded.
+    if (p >= 0 &&
+        static_cast(p) <
+            ctx.mass_balance.qual_routing_ex_in.size())
+        ctx.mass_balance.qual_routing_ex_in[static_cast(p)] +=
+            shortfall;
+    if (!st.first_clamp_recorded) {
+        st.first_clamp_recorded = true;
+        st.first_node = node;
+    }
+}
+
+/// Age-row clamp: counted, not ledgered (no age row until A2c) and not
+/// warned per-clamp (see bookNegativeSourceClamp's note).
+inline void bookNegativeAgeClamp(SimulationContext& ctx, int node) {
+    auto& st = ctx.negsrc;
+    st.age_clamp_events += 1;
+    if (!st.first_clamp_recorded) {
+        st.first_clamp_recorded = true;
+        st.first_node = node;
+    }
+}
+
+/**
+ * @brief P1.4: book one ARD **cell**-source clamp. Counted, NOT
+ *        ledgered — and the reason is structural, not an omission.
+ *
+ * @details The node seam un-books its shortfall from `qual_routing_ex_in`
+ *          because the loaders booked the signed request there in advance.
+ *          Cell sources have no such row to correct:
+ *
+ *          1. `[TRANSPORT_SOURCES]` rows resolve to **MSX species rows
+ *             only** — `ArdEngine.cpp` pushes `np + src_msx[i]`, so a cell
+ *             source can never name a pollutant; and
+ *          2. **MSX species have no mass-balance row at all.** The ARD
+ *             component writes to `ctx.mass_balance` nowhere.
+ *
+ *          So a per-pollutant row for this would be permanently zero, and
+ *          inventing an MSX row here would be a third self-consistent
+ *          balance (lesson 147) bolted on inside a defect fix. Giving MSX
+ *          species real ledger rows (sizing the `qual_*` vectors by
+ *          `np + nm`) is a deliberate, separate round — until it lands, the
+ *          delivered mass reaches `qual_routing_final` through the
+ *          end-of-run inventory sweep and therefore surfaces as CONTINUITY
+ *          ERROR rather than as a labelled term. **Recorded, not hidden.**
+ *
+ * @param conduit   mesh conduit row of the first clamp (diagnostic only).
+ * @param shortfall the UNMET extraction (positive, internal mass units).
+ */
+inline void bookNegativeCellSourceClamp(SimulationContext& ctx, int conduit,
+                                        double shortfall) {
+    auto& st = ctx.negsrc;
+    st.clamp_events += 1;
+    st.shortfall_mass += shortfall;
+    if (!st.first_clamp_recorded) {
+        st.first_clamp_recorded = true;
+        st.first_node = conduit;
+    }
+}
+
+/// End-of-run summary (pushed once by SWMMEngine::end when anything
+/// clamped; gates read ctx.warnings, so .rpt ordering is not load-bearing).
+inline void summarizeNegativeSourceClamps(SimulationContext& ctx) {
+    const auto& st = ctx.negsrc;
+    if (st.clamp_events == 0 && st.age_clamp_events == 0) return;
+    ctx.warnings.push_back(
+        "D-NS1 summary: extraction exceeded available mass " +
+        std::to_string(st.clamp_events) + " time(s) (unmet extraction " +
+        std::to_string(st.shortfall_mass) + " internal mass units)" +
+        (st.age_clamp_events > 0
+             ? ", water-age extraction clamped " +
+                   std::to_string(st.age_clamp_events) + " time(s)"
+             : std::string()) +
+        ", first at element index " + std::to_string(st.first_node) +
+        ". Extraction clamps ROUTINELY while the system fills, when elements "
+        "are near-empty; a nonzero count is not by itself a modelling error. "
+        "Node-seam clamps are ledgered (the ledger carries the mass actually "
+        "removed); ARD cell-source clamps are counted only — see "
+        "bookNegativeCellSourceClamp.");
+}
+
+}  // namespace quality
+}  // namespace openswmm
+
+#endif  // OPENSWMM_QUALITY_NEGATIVE_SOURCES_HPP
diff --git a/src/engine/quality/QualityRouting.cpp b/src/engine/quality/QualityRouting.cpp
index cab5c6172..1741d5456 100644
--- a/src/engine/quality/QualityRouting.cpp
+++ b/src/engine/quality/QualityRouting.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file QualityRouting.cpp
  * @brief Water quality routing — batch SoA, numerically identical to legacy.
@@ -9,10 +25,18 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "QualityRouting.hpp"
+
+#include "../transport/components/EulerianArdComponent/ArdConfig.hpp"
+#include "../transport/components/ReactionModule/MsxLegacyTransport.hpp"
+#include "../transport/components/ReactionModule/ReactionLegacyBinding.hpp"
+#include "../transport/components/HeatFluxModules/BedExchange.hpp"
+#include "../transport/components/HeatModule/HeatLegacy.hpp"
+#include "../transport/components/WaterAgeModule/WaterAgeLegacy.hpp"
+#include "NegativeSources.hpp"
 #include "Treatment.hpp"
 #include "../core/SimulationContext.hpp"
 #include "../core/UnitConversion.hpp"
@@ -31,10 +55,147 @@
 namespace openswmm {
 namespace quality {
 
-// ZERO_VOLUME defined in QualityRouting.hpp
+// ZERO_VOLUME, ZERO_DEPTH and LEGACY_ZERO are defined in QualityRouting.hpp
+
+// ============================================================================
+// The shared shape of the legacy mixing kernels — see QualityRouting.hpp.
+// ============================================================================
+
+bool linkTakesUpstreamValue(const SimulationContext& ctx, int link) {
+    const auto uj = static_cast(link);
+    return ctx.links.type[uj] != LinkType::CONDUIT ||
+           ctx.links.xsect_shape[uj] == XsectShape::DUMMY;
+}
+
+double conduitMixingInflow(const SimulationContext& ctx, int link, double dt) {
+    const auto uj = static_cast(link);
+    // Legacy reads |Conduit.q1| * barrels. Under DW and SF the solver writes
+    // one flow to both conduit ends, so |Link.newFlow| is that same number.
+    // KW publishes its accepted upstream flow separately from Link.newFlow.
+    const auto model = ctx.options.routing_model;
+    double q_in = std::fabs(model == RoutingModel::KINWAVE
+                               ? ctx.links.kw_inflow[uj] : ctx.links.flow[uj]);
+
+    // Legacy gates this correction on `RouteModel == DW` alone: dynamic wave
+    // produces a SINGLE flow rate per conduit, so the storage the conduit
+    // gained over the step is inflow that rate does not carry. Kinematic wave
+    // carries separate upstream and downstream flows and needs none — adding
+    // it there double-counts the fill. FV is this engine's other single-rate
+    // dynamic model, so it takes the DW branch.
+    if (model != RoutingModel::DYNWAVE && model != RoutingModel::FV)
+        return std::max(q_in, 0.0);
+    if (dt <= 0.0) return std::max(q_in, 0.0);
+
+    const int cr = ctx.link_subtypes.conduit_row(link);
+    double v_losses = 0.0;
+    if (cr >= 0) {
+        const auto ucr = static_cast(cr);
+        const auto& CD = ctx.link_subtypes.conduits;
+        const double barrels = static_cast(CD.barrels[ucr]);
+        v_losses = CD.seep_loss_rate[ucr] * barrels * dt +
+                   CD.evap_loss_rate[ucr] * barrels * dt;
+    }
+    q_in += (ctx.links.volume[uj] + v_losses - ctx.links.old_volume[uj]) / dt;
+    return std::max(q_in, 0.0);
+}
+
+bool linkIsDry(const SimulationContext& ctx, int link) {
+    const auto uj = static_cast(link);
+    return ctx.links.volume[uj] < ZERO_VOLUME ||
+           ctx.links.depth[uj] <= ZERO_DEPTH;
+}
+
+bool nodeIsReactor(const SimulationContext& ctx, int node) {
+    const auto ui = static_cast(node);
+    return ctx.nodes.type[ui] == NodeType::STORAGE ||
+           ctx.nodes.old_volume[ui] > ZERO_VOLUME;
+}
+
+bool nodeIsDry(const SimulationContext& ctx, int node, double q_in) {
+    const auto ui = static_cast(node);
+    return (ctx.nodes.volume[ui] <= ZERO_VOLUME ||
+            ctx.nodes.depth[ui]  <= ZERO_DEPTH) && q_in <= LEGACY_ZERO;
+}
 
 namespace {
 
+/// The external-load loaders below do two jobs: they accumulate per-pollutant
+/// MASS into qual_mass_in, and they accumulate the node's total external
+/// inflow VOLUME into qual_vol_in. Only the first is pollutant-shaped. E5a's
+/// [TRANSPORT_BOUNDARIES] injects `qual_vol_in * concentration`, so an
+/// MSX-only model (no [POLLUTANTS] — the nh2cl shape) needs the volume half
+/// to run even at np == 0, where every mass loop is already a no-op.
+/// Measured before this: a boundary on an MSX-only deck delivered exactly
+/// 0.0 while the same deck with one inert pollutant row delivered 8.0.
+bool loadersNeeded(int np, const SimulationContext& ctx) {
+    // A1a: water age needs the volume half (and the per-loader age-volume
+    // contributions) even on a deck with no [POLLUTANTS] — the pure-age
+    // model is A1a's motivating configuration (lesson 20).
+    // H1: heat needs the volume half for the same reason age does — a
+    // temperature-only deck (no [POLLUTANTS]) is a supported configuration
+    // and every mass loop is already a no-op at np == 0.
+    // R4b: and the MSX mirror is the FOURTH member of this family — an
+    // MSX-only deck (a reactions component, no [POLLUTANTS]) needs
+    // qual_vol_in zeroed and accumulated per step. Without this,
+    // assembleExternalLoads early-returns, the accumulator is never reset,
+    // v_in grows monotonically and routeLegacyMsx's mixing denominator
+    // diverges: the first run of the R4b gate read C3 at 2.5e-20 from
+    // exactly that. (The comment at the top of this function ALREADY
+    // recorded the 0.0-vs-8.0 version of this defect for ARD boundaries —
+    // same shape, fourth recurrence.)
+    return np > 0 || transport::ardBoundariesNeedExternalVolumes(ctx) ||
+           ctx.options.water_age || ctx.options.heat_transport ||
+           transport::legacyReactionsActive(ctx);
+}
+
+/// A1a: one loader's age-volume contribution — `q · age_source` (a RATE,
+/// age·ft³/s, the age analogue of qual_mass_in). No-op when WATER_AGE is
+/// off or the state is unsized (the ARD engine sizes it at init; the
+/// assemble stage zeroes it each step).
+inline void addAgeVolume(SimulationContext& ctx, int node, double q,
+                         WaterAgeSource src) {
+    if (!ctx.options.water_age) return;
+    auto& s = ctx.water_age_state.node_age_vol_in;
+    const auto un = static_cast(node);
+    if (un >= s.size()) return;
+    double age = ctx.water_age_config.source_age(src, node);
+    // Z1 (amendment D-Y4): an [INFLOWS] row naming __WATER_AGE__ is the
+    // more specific statement of THIS node's inflow age and wins over the
+    // source table's EXTERNAL_INFLOW entry (constant or node override).
+    // NaN marks "no row at this node" — never a value.
+    if (src == WaterAgeSource::EXTERNAL_INFLOW) {
+        const auto& ov = ctx.water_age_state.node_ext_inflow_age;
+        if (un < ov.size() && !std::isnan(ov[un])) age = ov[un];
+    }
+    s[un] += q * age;
+}
+
+/// H1: one loader's temperature-volume contribution — `q · T_source` (a
+/// RATE, °C·ft³/s), the heat analogue of the age channel above and the
+/// same seam (master plan §4.3 / D-UT10). Carries temperature-volume
+/// rather than Joules because ρw·cp cancel identically until H2 brings the
+/// energy fluxes that make them load-bearing — see HeatData.hpp.
+inline void addTempVolume(SimulationContext& ctx, int node, double q,
+                          HeatSource src) {
+    if (!ctx.options.heat_transport) return;
+    auto& s = ctx.heat_state.node_temp_vol_in;
+    const auto un = static_cast(node);
+    if (un >= s.size()) return;
+    s[un] += q * ctx.heat_config.source_temp(src, node);
+}
+
+/// Legacy `Node[j].treatment[p].equation != NULL` — findStorageQual skips its
+/// first-order reaction for a pollutant the node treats, so the two removals
+/// never stack.
+inline bool nodeHasTreatmentFor(const SimulationContext& ctx, int node, int p) {
+    const auto& tr = ctx.treatment;
+    if (tr.n_pollutants <= 0) return false;
+    const auto idx = static_cast(node) *
+                     static_cast(tr.n_pollutants) +
+                     static_cast(p);
+    return idx < tr.expressions.size() && !tr.expressions[idx].empty();
+}
+
 void applyLinkQualityForcing(SimulationContext& ctx, int n_pollutants, double dt) {
     if (n_pollutants <= 0) return;
 
@@ -72,24 +233,328 @@ void QualitySolver::init(int n_nodes, int n_links, int n_pollutants) {
     (void)n_links;
 }
 
-void QualitySolver::execute(SimulationContext& ctx, double dt) {
-    if (n_pollutants_ <= 0) return;
+void QualitySolver::assembleExternalLoads(SimulationContext& ctx, double dt) {
+    if (!loadersNeeded(n_pollutants_, ctx)) return;
 
     // Reset quality assembly arrays on NodeData
     std::fill(ctx.nodes.qual_mass_in.begin(), ctx.nodes.qual_mass_in.end(), 0.0);
+
+    // A1a: size + zero the age-volume accumulator alongside the pollutant
+    // loads (same lifecycle: assembled per routing step by the loaders).
+    if (ctx.options.water_age) {
+        auto& ws = ctx.water_age_state;
+        if (ws.node_age_vol_in.size() !=
+            static_cast(ctx.n_nodes()))
+            // A3: pass the subcatchment count — the 2-arg form defaults it
+            // to 0 and would WIPE subarea_age on any re-size.
+            ws.resize(ctx.n_nodes(), ctx.n_links(), ctx.n_subcatches());
+        std::fill(ws.node_age_vol_in.begin(), ws.node_age_vol_in.end(), 0.0);
+    }
+    // H1: same lifecycle for the temperature-volume accumulator.
+    if (ctx.options.heat_transport) {
+        auto& hs = ctx.heat_state;
+        if (hs.node_temp_vol_in.size() !=
+            static_cast(ctx.n_nodes()))
+            hs.resize(ctx.n_nodes(), ctx.n_links(),
+                      ctx.heat_config.global_temp[
+                          static_cast(HeatSource::INITIAL_STATE)]);
+        std::fill(hs.node_temp_vol_in.begin(), hs.node_temp_vol_in.end(), 0.0);
+    }
     std::fill(ctx.nodes.qual_vol_in.begin(),  ctx.nodes.qual_vol_in.end(),  0.0);
+    qual_vol_lat_.assign(static_cast(ctx.n_nodes()), 0.0);
+    qual_vol_lat_neg_.assign(static_cast(ctx.n_nodes()), 0.0);
 
     addWetWeatherLoads(ctx, dt);   // Subcatchment washoff → nodes
     addRdiiLoads(ctx, dt);         // RDII pollutant loads → nodes
     addDwfLoads(ctx, dt);          // Dry weather pollutant loads → nodes
     addGwLoads(ctx, dt);           // Groundwater inflow pollutant loads → nodes
     addIfaceLoads(ctx, dt);        // Routing interface file loads → nodes
+    addExtInflowLoads(ctx, dt);    // Direct [INFLOWS] CONCEN/MASS loads → nodes
+    addCouplingLoads(ctx, dt);     // S3: 2D→1D junction drain (volume + mass)
+
+    // legacy seeds the node's quality-inflow DENOMINATOR with the NET lateral
+    // flow floored at zero — routing.c:480, Node.qualInflow =
+    // MAX(0, Node.newLatFlow) — and dynwave's Node.inflow carries the same
+    // floored net into qualrout_execute. A lateral component that WITHDRAWS
+    // water (two-way groundwater exchange running aquifer-ward) therefore
+    // shrinks the carrier volume under the remaining lateral MASS, and the
+    // node's mixed concentration legitimately rises ABOVE every source
+    // concentration. v6 summed each positive source's own volume, so the
+    // negative component never touched the denominator: on usgs-runoff
+    // (Cppt 18 mg/L, GW drawing up to 2,000 cfs out of the receptors) legacy
+    // climbs to 47 mg/L while v6 could never exceed 18. Replace the lateral
+    // share of the accumulated volume with legacy's floored net. The
+    // correction is never positive (net <= sum of positive parts), and the
+    // S3 coupling volume is deliberately outside it (legacy has no 2D seam;
+    // legacy-comparable runs carry coupling_inflow == 0).
+    if (n_pollutants_ > 0) {
+        auto& nodes = ctx.nodes;
+        const std::size_t nn = std::min(qual_vol_lat_.size(),
+                                        nodes.qual_vol_in.size());
+        for (std::size_t ui = 0; ui < nn; ++ui) {
+            // Fire only when a negative lateral component actually arrived —
+            // on every other deck the correction is EXACTLY zero, so their
+            // ULPs are untouched. When it fires, take legacy's denominator
+            // from the flow side's own net lateral (the same newLatFlow
+            // legacy floors), not from re-summing the quality-side parts.
+            if (!(ui < qual_vol_lat_neg_.size() &&
+                  qual_vol_lat_neg_[ui] < 0.0)) continue;
+            const double lat_net_pos =
+                (ui < nodes.lat_flow.size())
+                    ? std::max(0.0, nodes.lat_flow[ui]) * dt : 0.0;
+            const double corr = lat_net_pos - qual_vol_lat_[ui];
+            if (corr < 0.0) nodes.qual_vol_in[ui] += corr;
+        }
+    }
+}
+
+// ============================================================================
+// S3 (D-2DT4, 2D→1D half): the 2D surface's junction drain. Engine-only (no
+// legacy counterpart — legacy has no 2D surface), added LAST so
+// legacy-comparable runs (coupling_inflow == 0) keep their ULPs.
+//
+// Two things arrive together and must both be booked, or the mix is wrong in
+// opposite directions: the WATER joins qual_vol_in (the mixing denominator —
+// before S3 the drain's water reached the node hydraulically but the quality
+// mix never saw it, so drained water diluted nothing) and the MASS joins
+// qual_mass_in at the rate assembleLateralInflows drained from the queue.
+// The spill (coupling_inflow < 0) books nothing here: the CSTR already takes
+// every outflow at the mixed concentration through the reduced inflow volume.
+// Age and temperature ride the EXTERNAL_INFLOW stand-ins until S4 carries
+// them on the surface. Booked as external inflow in the quality continuity
+// table, where the volume already goes on the flow side.
+// ============================================================================
+
+void QualitySolver::addCouplingLoads(SimulationContext& ctx, double dt) {
+    int np = n_pollutants_;
+    if (!loadersNeeded(np, ctx)) return;
+    auto& nodes = ctx.nodes;
+    if (nodes.coupling_inflow.empty()) return;
+
+    for (int i = 0; i < ctx.n_nodes(); ++i) {
+        auto ui = static_cast(i);
+        const double q = nodes.coupling_inflow[ui];
+        if (q > 0.0) {
+            nodes.qual_vol_in[ui] += q * dt;
+            // S4: when the surface carries the row, the tuple's own
+            // age-volume / temperature-volume arrives (drained by the same
+            // rule as the water, so the ratio is the cell's value); the
+            // EXTERNAL_INFLOW stand-in survives only for a surface that does
+            // not carry that row.
+            if (nodes.coupling_tuple_age && ctx.options.water_age &&
+                ui < ctx.water_age_state.node_age_vol_in.size() &&
+                ui < nodes.coupling_age_vol_inflow.size())
+                ctx.water_age_state.node_age_vol_in[ui] +=
+                    nodes.coupling_age_vol_inflow[ui];
+            else
+                addAgeVolume(ctx, i, q, WaterAgeSource::EXTERNAL_INFLOW);
+            if (nodes.coupling_tuple_temp && ctx.options.heat_transport &&
+                ui < ctx.heat_state.node_temp_vol_in.size() &&
+                ui < nodes.coupling_temp_vol_inflow.size())
+                ctx.heat_state.node_temp_vol_in[ui] +=
+                    nodes.coupling_temp_vol_inflow[ui];
+            else
+                addTempVolume(ctx, i, q, HeatSource::EXTERNAL_INFLOW);
+        }
+        if (nodes.coupling_qual_inflow.empty()) continue;
+        for (int p = 0; p < np; ++p) {
+            auto nd_idx = ui * static_cast(np) +
+                          static_cast(p);
+            if (nd_idx >= nodes.coupling_qual_inflow.size()) continue;
+            const double mass_rate = nodes.coupling_qual_inflow[nd_idx];
+            if (!(mass_rate > 0.0)) continue;
+            if (nd_idx < nodes.qual_mass_in.size())
+                nodes.qual_mass_in[nd_idx] += mass_rate;
+            auto pi = static_cast(p);
+            if (pi < ctx.mass_balance.qual_routing_ex_in.size())
+                ctx.mass_balance.qual_routing_ex_in[pi] += mass_rate * dt;
+        }
+    }
+}
+
+// ============================================================================
+// Add direct external inflow ([INFLOWS] CONCEN/MASS) pollutant loads.
+// Matches legacy routing.c addExternalInflows() pollutant portion:
+//   w = inflow value; if CONCEN, w *= node flow; Node[j].newQual[p] += w
+// ============================================================================
+
+void QualitySolver::addExtInflowLoads(SimulationContext& ctx, double dt) {
+    int np = n_pollutants_;
+    if (!loadersNeeded(np, ctx)) return;
+    auto& nodes = ctx.nodes;
+
+    for (int i = 0; i < ctx.n_nodes(); ++i) {
+        auto ui = static_cast(i);
+
+        // The direct inflow's own water joins the mixing denominator, matching
+        // legacy findNodeQual(), which divides the accumulated mass rate by
+        // Node[j].inflow — a total that includes the external lateral inflow.
+        // (LID drain-to-node water rides nodes.lid_drain_inflow, not this
+        //  array; its volume, age and temperature are booked once, by the
+        //  drain loader below, at the storage layer's own values.)
+        double q = nodes.ext_inflow[ui];
+        if (q < 0.0 && ui < qual_vol_lat_neg_.size())
+            qual_vol_lat_neg_[ui] += q * dt;
+        if (q > 0.0) {
+            nodes.qual_vol_in[ui] += q * dt;
+            qual_vol_lat_[ui] += q * dt;
+            addAgeVolume(ctx, i, q, WaterAgeSource::EXTERNAL_INFLOW);
+            addTempVolume(ctx, i, q, HeatSource::EXTERNAL_INFLOW);
+        }
+
+        if (nodes.ext_qual_mass.empty()) continue;
+        for (int p = 0; p < np; ++p) {
+            auto nd_idx = ui * static_cast(np) +
+                          static_cast(p);
+            if (nd_idx >= nodes.ext_qual_mass.size()) continue;
+            double mass_rate = nodes.ext_qual_mass[nd_idx];
+            if (mass_rate == 0.0) continue;
+            if (nd_idx < nodes.qual_mass_in.size())
+                nodes.qual_mass_in[nd_idx] += mass_rate;
+
+            // Legacy lumps direct and interface-file loads into EXTERNAL_INFLOW.
+            auto pi = static_cast(p);
+            if (pi < ctx.mass_balance.qual_routing_ex_in.size())
+                ctx.mass_balance.qual_routing_ex_in[pi] += mass_rate * dt;
+        }
+    }
+
+    // Runtime-API forced quality mass (swmm_node_set_quality_mass_flux), a
+    // mass RATE like the loads above. Legacy addExternalInflows() delivers it
+    // in exactly this stage and books it as EXTERNAL_INFLOW, positive only
+    // (routing.c: w = Node[j].apiExtQualMassFlux[p]; if (w > 0.0) {
+    // Node[j].newQual[p] += w; massbal_addInflowQual(EXTERNAL_INFLOW, p, w); }).
+    //
+    // It carries no water of its own, so nothing is added to qual_vol_in — the
+    // mixing denominator stays the node's actual inflow, as in legacy.
+    // routing_forcing_qual_inflow remains a diagnostic SUBSET of the external
+    // total (never added to it twice), mirroring routing_forcing_inflow on the
+    // flow side.
+    if (!nodes.user_conc_mass_flux.empty()) {
+        for (int i = 0; i < ctx.n_nodes(); ++i) {
+            auto ui = static_cast(i);
+            for (int p = 0; p < np; ++p) {
+                auto nd_idx = ui * static_cast(np) +
+                              static_cast(p);
+                if (nd_idx >= nodes.user_conc_mass_flux.size()) continue;
+                const double w = nodes.user_conc_mass_flux[nd_idx];
+                if (w == 0.0) continue;
+                // D-NS1 (X6): negative forced mass is extraction —
+                // DELIBERATE deviation from legacy's positive-only rule
+                // (routing.c `if (w > 0.0)`), per the user decision of
+                // 2026-08-23. The signed rate books signed; the mix stage
+                // clamps to available and un-books any shortfall. First
+                // negative warns once (the API has no parse stage).
+                if (w < 0.0 && !ctx.negsrc.api_warned) {
+                    ctx.negsrc.api_warned = true;
+                    ctx.warnings.push_back(
+                        "D-NS1: a negative quality mass flux was applied "
+                        "via the runtime API (extraction). It is clamped "
+                        "per step to the mass the element holds.");
+                }
+                if (nd_idx < nodes.qual_mass_in.size())
+                    nodes.qual_mass_in[nd_idx] += w;
+
+                auto pi = static_cast(p);
+                if (pi < ctx.mass_balance.qual_routing_ex_in.size())
+                    ctx.mass_balance.qual_routing_ex_in[pi] += w * dt;
+                if (pi < ctx.mass_balance.routing_forcing_qual_inflow.size())
+                    ctx.mass_balance.routing_forcing_qual_inflow[pi] += w * dt;
+            }
+        }
+    }
+}
+
+void QualitySolver::execute(SimulationContext& ctx, double dt) {
+    // R4: an MSX-only model (a reactions component and no [POLLUTANTS]) is a
+    // legitimate shape — EPANET-MSX decks routinely declare no legacy
+    // pollutant. Every stage below is a no-op at np == 0, so letting it
+    // through costs nothing and is the only way reactLegacyNodes/Links run
+    // for such a model. A1b: the pure-age LEGACY model is the same shape —
+    // the age mirror needs the volume accumulation these stages perform.
+    // Without a reactions component or WATER_AGE the early return is
+    // unchanged, so parity is preserved by construction.
+    // H1: and the temperature-only model is that same shape once more. This
+    // is the SECOND guard of this family on the path — the routing-step
+    // guard in SWMMEngine::stepRouting is the first — and a feature has to
+    // clear both to run at np == 0.
+    if (n_pollutants_ <= 0 && !transport::legacyReactionsActive(ctx) &&
+        !ctx.options.water_age && !ctx.options.heat_transport)
+        return;
+
+    assembleExternalLoads(ctx, dt);
     accumulateLinkLoads(ctx, dt);
     mixAtNodes(ctx, dt);
-    applyTreatment(ctx, dt);       // Treatment before decay (matching legacy order)
-    applyDecay(ctx, dt);
+    // R4b (transport half): MSX element state advects on the same CSTR
+    // mirror family as age and heat. It runs BEFORE the react stages —
+    // transport-then-react, the pollutant family's own order — because
+    // FORMULA's contract is that react is the LAST writer of a derived
+    // species. The first draft placed it after reactLegacyLinks and the
+    // FORMULA tracking gate promptly drifted by 4.3e-3: transport was
+    // mixing a value the formula had just pinned.
+    transport::routeLegacyMsx(ctx, dt);
+    // Legacy's per-node order is reaction, then mixing, then treatment — the
+    // first two inside findStorageQual, treatmnt_treat immediately after it
+    // (qualrout.c's node loop). mixAtNodes now carries the reaction, so this
+    // call is in the right place; the decay stage below is a no-op left in
+    // the sequence for shape.
+    applyTreatment(ctx, dt);
+    // R4: with a reactions component configured, pollutant decay upgrades to
+    // the exact exponential and MSX species react per element via the shared
+    // integrator (ReactionLegacyBinding). Nodes react here (where applyDecay
+    // ran); links react AFTER updateLinkQuality so the mixing pass does not
+    // overwrite them (its internal linear decay is zeroed below). Without a
+    // reactions component the legacy path runs untouched — bit-parity
+    // (G-UT1).
+    if (transport::legacyReactionsActive(ctx)) {
+        transport::reactLegacyNodes(ctx, dt);
+    } else {
+        applyDecay(ctx, dt);
+    }
     updateLinkQuality(ctx, dt);
+    if (transport::legacyReactionsActive(ctx))
+        transport::reactLegacyLinks(ctx, dt);
     applyLinkQualityForcing(ctx, n_pollutants_, dt);
+
+    // A1b: the LEGACY age mirror runs LAST — it reads the fully accumulated
+    // qual_vol_in as its mixing denominator and writes only water_age_state,
+    // so WATER_AGE ON leaves every pollutant trajectory bit-identical.
+    transport::routeLegacyAge(ctx, dt);
+
+    // H1: the LEGACY temperature mirror runs beside the age mirror, on the
+    // same fully accumulated qual_vol_in denominator, and writes only
+    // heat_state — so HEAT_TRANSPORT ON leaves both the pollutant and the
+    // water-age trajectories bit-identical under LEGACY.
+    transport::routeLegacyHeat(ctx, dt);
+
+    // H6b: the bed's SOLUTE exchange, after every pollutant stage and after
+    // the heat mirror (whose own bed coupling is inside `applyHeatFluxes`).
+    //
+    // It runs last for the same reason the two mirrors do: it reads the
+    // settled link concentrations rather than an intermediate, so with
+    // `[HEAT_FLUXES] SEDIMENT_EXCHANGE` off — which is the default — every
+    // pollutant trajectory is bit-identical to the pre-H6b engine.
+    //
+    // `ctx.links.conc` is already [link * np + p], the layout
+    // `applyBedSoluteExchange` documents, so the array is passed rather than
+    // repacked. A repack would be a second layout to keep in agreement.
+    //
+    // The bed carries ONE species set — pollutants then MSX — and LEGACY
+    // holds those in two arrays, so two calls with offsets into the same
+    // store. MSX rows exchange like the reference's solutes do
+    // (HTSComponent carries its transient-storage solutes generically).
+    if (transport::heat::bedExchangeEnabled(ctx)) {
+        const int np = ctx.links.conc_n_pollutants;
+        const int nm = ctx.reactions.n_species();
+        const int nt = (np > 0 ? np : 0) + (nm > 0 ? nm : 0);
+        if (np > 0 && !ctx.links.conc.empty())
+            transport::heat::applyBedSoluteExchange(
+                ctx, ctx.links.conc.data(), np, 0, nt, dt);
+        if (nm > 0 && !ctx.reactions.msx_link_conc.empty())
+            transport::heat::applyBedSoluteExchange(
+                ctx, ctx.reactions.msx_link_conc.data(), nm,
+                (np > 0 ? np : 0), nt, dt);
+    }
 }
 
 // ============================================================================
@@ -106,13 +571,63 @@ void QualitySolver::addWetWeatherLoads(SimulationContext& ctx, double dt) {
         if (out_node < 0 || out_node >= ctx.n_nodes()) continue;
         auto ud = static_cast(out_node);
 
-        // Time-weighted runoff: blend old and new (trapezoidal rule preserved)
+        // legacy addWetWeatherInflows (routing.c:713-719) weights both the
+        // runoff flow and the washoff load beside it by where THIS routing
+        // instant falls between the two runoff times:
+        //     f = (routingTime - OldRunoffTime)/(NewRunoffTime - OldRunoffTime)
+        // This used a fixed midpoint, 0.5*(old + new), for both. With a 60 s
+        // routing step inside a 15-minute runoff step legacy sweeps f from 0
+        // to 1 across fifteen steps while this delivered the average every
+        // time, so a storm's load arrived on the wrong schedule — and the
+        // FLOW side of the same seam (assembleLateralInflows) had been using
+        // legacy's f all along, so the two halves disagreed with each other.
+        const double f  = ctx.runoff_interp_f;
+        const double f1 = 1.0 - f;
         double q_new = ctx.subcatches.runoff[ui];
         double q_old = ctx.subcatches.old_runoff[ui];
-        double q = 0.5 * (q_old + q_new);
+        double q = f1 * q_old + f * q_new;
         if (q <= 0.0) continue;
 
         ctx.nodes.qual_vol_in[ud] += q * dt;
+        if (ud < qual_vol_lat_.size()) qual_vol_lat_[ud] += q * dt;
+        // A3: runoff arrives at the age the SUBCATCHMENT computed, not at the
+        // configured RAINFALL age. The rainfall age is what enters the
+        // subareas; by the time water leaves it has aged on the surface and
+        // mixed with whatever was already ponded, and that is the number the
+        // node must receive. Falls back to the configured source age when the
+        // watershed state is unsized (WATER_AGE on, runoff never stepped).
+        {
+            const bool have_sc = ctx.options.water_age &&
+                                 ui < ctx.water_age_state
+                                          .subcatch_runoff_age.size();
+            if (have_sc) {
+                auto& acc = ctx.water_age_state.node_age_vol_in;
+                if (ud < acc.size())
+                    acc[ud] += q * ctx.water_age_state
+                                       .subcatch_runoff_age[ui];
+            } else {
+                addAgeVolume(ctx, out_node, q, WaterAgeSource::RAINFALL);
+            }
+        }
+        // H5a: the temperature mirror of the block above. Runoff reaches the
+        // node at the SUBCATCHMENT's computed temperature, not the configured
+        // RAINFALL temperature — rain is what enters the subareas; by the
+        // time water leaves it has exchanged with the atmosphere and mixed
+        // with whatever was ponded. Falls back to the configured source when
+        // the watershed state is unsized (HEAT_TRANSPORT on, runoff never
+        // stepped).
+        {
+            const bool have_sc = ctx.options.heat_transport &&
+                                 ui < ctx.heat_state
+                                          .subcatch_runoff_temp.size();
+            if (have_sc) {
+                auto& acc = ctx.heat_state.node_temp_vol_in;
+                if (ud < acc.size())
+                    acc[ud] += q * ctx.heat_state.subcatch_runoff_temp[ui];
+            } else {
+                addTempVolume(ctx, out_node, q, HeatSource::RAINFALL);
+            }
+        }
 
         for (int p = 0; p < np; ++p) {
             auto sc_idx = ui * static_cast(np) + static_cast(p);
@@ -122,12 +637,23 @@ void QualitySolver::addWetWeatherLoads(SimulationContext& ctx, double dt) {
             double c_new = (sc_idx < ctx.subcatches.conc.size()) ? ctx.subcatches.conc[sc_idx] : 0.0;
             double c_old = (sc_idx < ctx.subcatches.conc_old.size()) ? ctx.subcatches.conc_old[sc_idx] : 0.0;
 
-            // Mass flow rate = weighted (q*c) — trapezoidal rule preserved
-            double mass_rate = 0.5 * (q_old * c_old + q_new * c_new);
+            // legacy surfqual_getWtdWashoff: the interpolated PRODUCT
+            // runoff*conc, not the product of the two interpolations — so the
+            // effective concentration the node sees is not the interpolated
+            // concentration. Same f as the flow above.
+            double mass_rate = f1 * (q_old * c_old) + f * (q_new * c_new);
 
             if (mass_rate > 0.0 && nd_idx < ctx.nodes.qual_mass_in.size()) {
                 ctx.nodes.qual_mass_in[nd_idx] += mass_rate;
             }
+
+            // Mass balance: wet weather quality inflow is attributed HERE, from
+            // the subcatchment's own washoff load — matching legacy
+            // addWetWeatherInflows(): massbal_addInflowQual(WET_WEATHER_INFLOW,
+            // p, q * Subcatch[i].newQual[p]).
+            auto pi = static_cast(p);
+            if (mass_rate > 0.0 && pi < ctx.mass_balance.qual_routing_wet.size())
+                ctx.mass_balance.qual_routing_wet[pi] += mass_rate * dt;
         }
     }
 
@@ -136,20 +662,67 @@ void QualitySolver::addWetWeatherLoads(SimulationContext& ctx, double dt) {
     // (CFS) are set once per runoff step in A6b and persist until overwritten.
     // Matches legacy lid_addDrainInflow() (node drain) / lid_addDrainRunon()
     // (subcatch drain routed to that subcatch's outlet node).
+    // legacy lid_addDrainInflow weights both halves of the pair by where
+    // this routing instant falls between the two runoff steps:
+    //   q = (1-f)*oldDrainFlow + f*newDrainFlow
+    //   w = (1-f)*oldDrainFlow*oldQual + f*newDrainFlow*newQual
+    // The per-node accumulators hold exactly those products, so the same
+    // f addWetWeatherLoads uses interpolates them per node.
+    const double f_dr  = ctx.runoff_interp_f;
+    const double f1_dr = 1.0 - f_dr;
     for (int j = 0; j < ctx.n_nodes(); ++j) {
         auto uj = static_cast(j);
-        double drain_vol_rate = (uj < ctx.nodes.lid_drain_qual_vol.size())
-                                ? ctx.nodes.lid_drain_qual_vol[uj] : 0.0;
+        double v_new = (uj < ctx.nodes.lid_drain_qual_vol.size())
+                       ? ctx.nodes.lid_drain_qual_vol[uj] : 0.0;
+        double v_old = (uj < ctx.nodes.lid_drain_qual_vol_old.size())
+                       ? ctx.nodes.lid_drain_qual_vol_old[uj] : 0.0;
+        double drain_vol_rate = f1_dr * v_old + f_dr * v_new;
         if (drain_vol_rate <= 0.0) continue;
 
         ctx.nodes.qual_vol_in[uj] += drain_vol_rate * dt;
+        if (uj < qual_vol_lat_.size()) qual_vol_lat_[uj] += drain_vol_rate * dt;
+        // A4 RETIRES the RAINFALL stand-in here: the drain now arrives at the
+        // age of the LID storage layer it was drawn from, accumulated as a
+        // q·age rate in A6b beside this very volume. Falls back to the
+        // configured source age only when the layer block is unsized (WATER_AGE
+        // on but the LID manager built no units).
+        if (ctx.options.water_age &&
+            uj < ctx.water_age_state.node_lid_drain_age_vol_in.size() &&
+            ctx.lid_layer_state.active()) {
+            auto& acc = ctx.water_age_state.node_age_vol_in;
+            if (uj < acc.size())
+                acc[uj] += ctx.water_age_state.node_lid_drain_age_vol_in[uj];
+        } else {
+            addAgeVolume(ctx, j, drain_vol_rate, WaterAgeSource::RAINFALL);
+        }
+        // H5b at the node seam: the drain arrives at its storage layer's
+        // temperature, accumulated beside this volume in the runoff step.
+        // The RAINFALL stand-in survives only when the layer block is unsized.
+        if (ctx.options.heat_transport &&
+            uj < ctx.heat_state.node_lid_drain_temp_vol_in.size() &&
+            ctx.lid_layer_state.active()) {
+            auto& tacc = ctx.heat_state.node_temp_vol_in;
+            if (uj < tacc.size())
+                tacc[uj] += ctx.heat_state.node_lid_drain_temp_vol_in[uj];
+        } else {
+            addTempVolume(ctx, j, drain_vol_rate, HeatSource::RAINFALL);
+        }
 
         for (int p = 0; p < np; ++p) {
             auto nd_idx = uj * static_cast(np) + static_cast(p);
-            double load = (nd_idx < ctx.nodes.lid_drain_qual_load.size())
-                          ? ctx.nodes.lid_drain_qual_load[nd_idx] : 0.0;
+            double w_new = (nd_idx < ctx.nodes.lid_drain_qual_load.size())
+                           ? ctx.nodes.lid_drain_qual_load[nd_idx] : 0.0;
+            double w_old = (nd_idx < ctx.nodes.lid_drain_qual_load_old.size())
+                           ? ctx.nodes.lid_drain_qual_load_old[nd_idx] : 0.0;
+            double load = f1_dr * w_old + f_dr * w_new;
             if (load > 0.0 && nd_idx < ctx.nodes.qual_mass_in.size())
                 ctx.nodes.qual_mass_in[nd_idx] += load;
+
+            // Legacy lid_addDrainInflow() / lid_addDrainRunon() also book drain
+            // loads as WET_WEATHER_INFLOW.
+            auto pi = static_cast(p);
+            if (load > 0.0 && pi < ctx.mass_balance.qual_routing_wet.size())
+                ctx.mass_balance.qual_routing_wet[pi] += load * dt;
         }
     }
 }
@@ -161,7 +734,7 @@ void QualitySolver::addWetWeatherLoads(SimulationContext& ctx, double dt) {
 
 void QualitySolver::addRdiiLoads(SimulationContext& ctx, double dt) {
     int np = n_pollutants_;
-    if (np <= 0) return;
+    if (!loadersNeeded(np, ctx)) return;
     auto& nodes = ctx.nodes;
 
     for (int i = 0; i < ctx.n_nodes(); ++i) {
@@ -171,6 +744,9 @@ void QualitySolver::addRdiiLoads(SimulationContext& ctx, double dt) {
 
         // Add volume inflow from RDII
         nodes.qual_vol_in[ui] += q * dt;
+        qual_vol_lat_[ui] += q * dt;
+        addAgeVolume(ctx, i, q, WaterAgeSource::RDII);
+        addTempVolume(ctx, i, q, HeatSource::RDII);
 
         // Add pollutant mass loads: mass_rate = q * c_rdii[p]
         // Matching legacy: w = q * Pollut[p].rdiiConcen
@@ -204,36 +780,43 @@ void QualitySolver::addRdiiLoads(SimulationContext& ctx, double dt) {
 
 void QualitySolver::addDwfLoads(SimulationContext& ctx, double dt) {
     int np = n_pollutants_;
-    if (np <= 0) return;
+    if (!loadersNeeded(np, ctx)) return;
     auto& nodes = ctx.nodes;
 
     for (int i = 0; i < ctx.n_nodes(); ++i) {
         auto ui = static_cast(i);
         double q = nodes.dwf_inflow[ui];
+        if (q < 0.0 && ui < qual_vol_lat_neg_.size())
+            qual_vol_lat_neg_[ui] += q * dt;
         if (q <= 0.0) continue;
 
         // Add volume inflow from DWF (legacy qualrout.c uses Node[j].inflow,
         // which includes DWF, as the mixing denominator). Without this the
         // mass added below is discarded by mixAtNodes when v_in == 0.
         nodes.qual_vol_in[ui] += q * dt;
+        qual_vol_lat_[ui] += q * dt;
+        addAgeVolume(ctx, i, q, WaterAgeSource::DWF);
+        addTempVolume(ctx, i, q, HeatSource::DWF);
 
         OPENSWMM_IVDEP
         for (int p = 0; p < np; ++p) {
             double c_dwf = ctx.pollutants.c_dwf[static_cast(p)];
-            if (c_dwf <= 0.0) continue;
             auto nd_idx = ui * static_cast(np) + static_cast(p);
+            // Per-node [DWF] pollutant rows arrive as a net adjustment on top
+            // of the global default (InflowSolver pass 2 — legacy
+            // addDryWeatherInflows adds the row's q·concentration and
+            // subtracts the q·dwfConcen default it displaces).
+            double w_adj = (nd_idx < nodes.dwf_qual_mass.size())
+                               ? nodes.dwf_qual_mass[nd_idx] : 0.0;
+            double w = (c_dwf > 0.0 ? q * c_dwf : 0.0) + w_adj;
+            if (w == 0.0) continue;
             if (nd_idx < nodes.qual_mass_in.size()) {
-                nodes.qual_mass_in[nd_idx] += q * c_dwf;
+                nodes.qual_mass_in[nd_idx] += w;
             }
-        }
-
-        // Mass balance: track dry weather quality inflow
-        for (int p = 0; p < np; ++p) {
-            double c_dwf = ctx.pollutants.c_dwf[static_cast(p)];
-            if (c_dwf <= 0.0) continue;
+            // Mass balance: track dry weather quality inflow
             auto pi = static_cast(p);
             if (pi < ctx.mass_balance.qual_routing_dw_in.size()) {
-                ctx.mass_balance.qual_routing_dw_in[pi] += q * c_dwf * dt;
+                ctx.mass_balance.qual_routing_dw_in[pi] += w * dt;
             }
         }
     }
@@ -247,17 +830,22 @@ void QualitySolver::addDwfLoads(SimulationContext& ctx, double dt) {
 
 void QualitySolver::addGwLoads(SimulationContext& ctx, double dt) {
     int np = n_pollutants_;
-    if (np <= 0) return;
+    if (!loadersNeeded(np, ctx)) return;
     auto& nodes = ctx.nodes;
 
     for (int i = 0; i < ctx.n_nodes(); ++i) {
         auto ui = static_cast(i);
         double q = nodes.gw_inflow[ui];
+        if (q < 0.0 && ui < qual_vol_lat_neg_.size())
+            qual_vol_lat_neg_[ui] += q * dt;
         if (q <= 0.0) continue;  // pollutant load only for positive inflow
 
         // Add volume inflow from groundwater (see addDwfLoads: the mass below
         // is discarded by mixAtNodes unless its carrier volume is counted).
         nodes.qual_vol_in[ui] += q * dt;
+        qual_vol_lat_[ui] += q * dt;
+        addAgeVolume(ctx, i, q, WaterAgeSource::GW);
+        addTempVolume(ctx, i, q, HeatSource::GW);
 
         OPENSWMM_IVDEP
         for (int p = 0; p < np; ++p) {
@@ -290,17 +878,22 @@ void QualitySolver::addGwLoads(SimulationContext& ctx, double dt) {
 
 void QualitySolver::addIfaceLoads(SimulationContext& ctx, double dt) {
     int np = n_pollutants_;
-    if (np <= 0) return;
+    if (!loadersNeeded(np, ctx)) return;
     auto& nodes = ctx.nodes;
     if (nodes.iface_qual_mass.empty()) return;
 
     for (int i = 0; i < ctx.n_nodes(); ++i) {
         auto ui = static_cast(i);
         double q = nodes.iface_inflow[ui];
+        if (q < 0.0 && ui < qual_vol_lat_neg_.size())
+            qual_vol_lat_neg_[ui] += q * dt;
         if (q <= 0.0) continue;
 
         // Add volume inflow from the interface file
         nodes.qual_vol_in[ui] += q * dt;
+        qual_vol_lat_[ui] += q * dt;
+        addAgeVolume(ctx, i, q, WaterAgeSource::IFACE);
+        addTempVolume(ctx, i, q, HeatSource::IFACE);
 
         OPENSWMM_IVDEP
         for (int p = 0; p < np; ++p) {
@@ -366,12 +959,33 @@ void QualitySolver::accumulateLinkLoads(SimulationContext& ctx, double dt) {
 }
 
 // ============================================================================
-// Complete mixing at all nodes — VECTORISABLE
+// Complete mixing at all nodes — legacy qualrout.c findStorageQual /
+// findNodeQual, op for op.
+//
+// Legacy dispatches on the node: a STORAGE unit, or any node that STARTED the
+// step holding more than a litre, is a mixed reactor whose own contents are
+// part of the balance (findStorageQual); everything else is pure flow-through
+// whose concentration is simply mass-in over flow-in, with no volume term, no
+// evaporation factor and no reaction (findNodeQual). This engine ran one
+// formula for every node and approximated the second case by substituting
+// `mass_in / v_in` whenever the starting volume was negligible — which is the
+// right answer for a junction and the WRONG one for a storage unit filling
+// from dry, where legacy still divides by (v1 + vIn).
 // ============================================================================
 
 void QualitySolver::mixAtNodes(SimulationContext& ctx, double dt) {
     int np = n_pollutants_;
     auto& nodes = ctx.nodes;
+    auto& poll  = ctx.pollutants;
+    auto& mb    = ctx.mass_balance;
+    // OUTFALL_BACKFLOW_QUALITY ZERO: a supplying outfall is a fresh
+    // boundary — its held state reads zero, so backflow re-enters clean
+    // instead of carrying the last mix (legacy LAST keeps the hold).
+    const bool zero_bf_opt = ctx.options.outfall_backflow_zero;
+    // R4: with a reactions component the exact exponential in
+    // reactLegacyNodes replaces this linear decay, and must not double-apply.
+    const bool reactions_active = transport::legacyReactionsActive(ctx);
+    const bool any_treatment = ctx.treatment.hasAny();
 
     // Batch over all nodes — inner loop over pollutants is vectorisable
     // Outer node loop is parallelisable: each node reads only its own
@@ -382,41 +996,166 @@ void QualitySolver::mixAtNodes(SimulationContext& ctx, double dt) {
 #endif
     for (int i = 0; i < ctx.n_nodes(); ++i) {
         auto ui = static_cast(i);
-        double v_old = nodes.old_volume[ui];
-        double v_in = nodes.qual_vol_in[ui];
+        const double v_old = nodes.old_volume[ui];
+        const double v_in = nodes.qual_vol_in[ui];
+        const bool is_storage = (nodes.type[ui] == NodeType::STORAGE);
+        const bool zero_bf =
+            zero_bf_opt && nodes.type[ui] == NodeType::OUTFALL;
+
+        // --- legacy qualrout_execute's dispatch (see nodeIsReactor).
+        if (!nodeIsReactor(ctx, i)) {
+            // ---- findNodeQual: no storage volume, so the concentration is
+            //      just the inflow's, and nothing reacts or concentrates.
+            //
+            // legacy tests the inflow RATE against ZERO (1e-10 cfs), not the
+            // volume against nothing: `if (qNode > ZERO)`, qualrout.c:301.
+            // v6 divided whenever v_in was merely non-zero, so a node taking
+            // 1.6e-18 cfs of numerical residue divided a residual mass by a
+            // residual volume and published the ratio. On duobiocell — a deck
+            // that never generates one drop of runoff — that read 227 mg/L at
+            // a dry, empty junction where legacy reads zero. The reactor half
+            // of this kernel has tested the rate against the same constant
+            // since the node-CSTR round (see nodeIsDry); only this half was
+            // left behind.
+            const double q_node = (dt > 0.0) ? v_in / dt : 0.0;
+            for (int p = 0; p < np; ++p) {
+                auto idx = ui * static_cast(np) + static_cast(p);
+                if (idx >= nodes.conc.size()) continue;
+                if (q_node > LEGACY_ZERO) {
+                    double mass_in = (idx < nodes.qual_mass_in.size())
+                                   ? nodes.qual_mass_in[idx] * dt : 0.0;
+                    // D-NS1 (X6): a negative load is extraction, clamped to
+                    // the mass the store holds; the shortfall is counted and
+                    // un-booked so the ledger carries what actually left. The
+                    // branch is untaken on every non-negative deck.
+                    if (mass_in < 0.0) {
+                        const double avail = nodes.conc_old[idx] * v_old;
+                        if (mass_in < -avail) {
+                            bookNegativeSourceClamp(ctx, i, p, -(avail + mass_in));
+                            mass_in = -avail;
+                        }
+                    }
+                    nodes.conc[idx] = mass_in / v_in;
+                } else if (zero_bf) {
+                    nodes.conc[idx] = 0.0;
+                } else if (nodes.depth[ui] > ZERO_DEPTH) {
+                    // Legacy 5.2.1: a WET node with no inflow holds its
+                    // quality; a DRY one keeps the accumulated load, which
+                    // with no inflow is nothing.
+                    nodes.conc[idx] = nodes.conc_old[idx];
+                } else {
+                    nodes.conc[idx] = 0.0;
+                }
+            }
+            continue;
+        }
+
+        // ---- findStorageQual: a mixed reactor.
+        // Evaporation concentration factor (P8-G20, repaired in KD1):
+        // legacy scales the STORED concentration by fEvap = 1 + vEvap/v1 from
+        // the storage unit's ACTUAL evaporation volume. An earlier spelling
+        // inferred evaporation from v_new < v_old + v_in — true for EVERY
+        // draining node, and outflow is not evaporation — inflating the store
+        // to retain mass the downstream link had already pulled.
+        double f_evap = 1.0;
+        double q_exfil = 0.0;
+        if (is_storage) {
+            const int srow = ctx.node_subtypes.storage_row(i);
+            if (srow >= 0) {
+                const auto us = static_cast(srow);
+                const auto& st = ctx.node_subtypes.storages;
+                const double v_evap =
+                    (us < st.evap_loss.size()) ? st.evap_loss[us] : 0.0;
+                const double v_exfil =
+                    (us < st.exfil_loss.size()) ? st.exfil_loss[us] : 0.0;
+                // legacy holds Storage[k].exfilLoss as a VOLUME over the step
+                // and books the seepage ledger at the rate exfilLoss/tStep.
+                q_exfil = (dt > 0.0) ? v_exfil / dt : 0.0;
+                if (v_evap > 0.0 && v_old > ZERO_VOLUME) f_evap += v_evap / v_old;
+            }
+        }
+
+        // Legacy zeroes a reactor that ends the step essentially empty AND is
+        // taking nothing in, booking what it held to final storage.
+        //
+        // NOTE the inflow RATE here is v_in/dt, where legacy reads
+        // Node[j].inflow — the single number the hydraulics produced, summed
+        // as rates and multiplied by dt once, against this engine's
+        // qual_vol_in, which sums per-source volumes each already multiplied
+        // by dt. The two agree to within summation order; closing that gap
+        // means moving every consumer of qual_vol_in and is left standing.
+        const double q_in = (dt > 0.0) ? v_in / dt : 0.0;
+        const bool dry = nodeIsDry(ctx, i, q_in);
 
         for (int p = 0; p < np; ++p) {
             auto idx = ui * static_cast(np) + static_cast(p);
             if (idx >= nodes.conc.size()) continue;
-
-            double c_old = nodes.conc_old[idx];
-
-            if (v_in <= 0.0) {
-                nodes.conc[idx] = c_old;
-                continue;
+            const auto up = static_cast(p);
+
+            double c1 = nodes.conc_old[idx];
+
+            // legacy massbal_addSeepageLoss(p, qExfil * c1), booked BEFORE
+            // the evaporation factor is applied.
+            const double seeped = q_exfil * c1 * dt;
+
+            c1 *= f_evap;
+
+            // getReactedQual — legacy applies the first-order reaction to the
+            // STORED concentration BEFORE mixing in this step's inflow, and
+            // SKIPS it entirely for a pollutant that has its own treatment
+            // equation at this node. This engine decayed AFTER mixing, in a
+            // separate pass that also bit the fresh inflow.
+            double k = (up < poll.k_decay.size()) ? poll.k_decay[up] : 0.0;
+            if (reactions_active) k = 0.0;
+            if (k != 0.0 && any_treatment && nodeHasTreatmentFor(ctx, i, p))
+                k = 0.0;
+            double reacted = 0.0;
+            if (k != 0.0) {
+                const double c2 = std::max(0.0, c1 * (1.0 - k * dt));
+                reacted = (c1 - c2) * v_old;
+                c1 = c2;
             }
 
-            double mass_in = (idx < nodes.qual_mass_in.size()) ? nodes.qual_mass_in[idx] * dt : 0.0;
-            double c_in = mass_in / v_in;
-            double c_max = std::max(c_old, c_in);
+            double mass_in = (idx < nodes.qual_mass_in.size())
+                           ? nodes.qual_mass_in[idx] * dt : 0.0;
+            if (mass_in < 0.0) {
+                const double avail = nodes.conc_old[idx] * v_old;
+                if (mass_in < -avail) {
+                    bookNegativeSourceClamp(ctx, i, p, -(avail + mass_in));
+                    mass_in = -avail;
+                }
+            }
 
-            double c_new = (v_old > ZERO_VOLUME)
-                ? (c_old * v_old + mass_in) / (v_old + v_in)
-                : c_in;
+            // getMixedQual(c1, v_old, wIn, q_in, dt), in legacy's own operand
+            // order: cIn is formed from the inflow load, the mixture is
+            // capped at max(c, cIn), and the whole thing is skipped when the
+            // inflow is below the effective zero.
+            double c_new;
+            if (q_in <= LEGACY_ZERO) {
+                c_new = c1;
+            } else {
+                const double c_in  = mass_in / v_in;
+                const double c_max = std::max(c1, c_in);
+                c_new = (c1 * v_old + mass_in) / (v_old + v_in);
+                c_new = std::min(c_new, c_max);
+                c_new = std::max(c_new, 0.0);
+            }
 
-            // Evaporation concentration factor (P8-G20)
-            // When water evaporates, concentration increases
-            double v_new = nodes.volume[ui];
-            if (v_new > ZERO_VOLUME && v_new < v_old + v_in) {
-                c_new *= (v_old + v_in) / v_new;
+            if (dry) {
+                if (up < mb.qual_routing_final_dry.size())
+                    mb.qual_routing_final_dry[up] += c_new * nodes.volume[ui];
+                c_new = 0.0;
             }
 
-            c_new = std::min(c_new, c_max);
             c_new = std::max(c_new, 0.0);
             nodes.conc[idx] = c_new;
+
+            if (reacted > 0.0 && up < mb.qual_routing_reacted.size())
+                mb.qual_routing_reacted[up] += reacted;
+            if (seeped != 0.0 && up < mb.qual_routing_seep.size())
+                mb.qual_routing_seep[up] += seeped;
         }
     }
-    (void)dt;
 }
 
 // ============================================================================
@@ -424,31 +1163,18 @@ void QualitySolver::mixAtNodes(SimulationContext& ctx, double dt) {
 // ============================================================================
 
 void QualitySolver::applyDecay(SimulationContext& ctx, double dt) {
-    int np = n_pollutants_;
-    auto& poll = ctx.pollutants;
-
-    // For each pollutant, pre-compute the decay factor (1 - k*dt) once,
-    // then apply it to the contiguous concentration arrays.
-    // When np == 1 this becomes a simple scalar multiply over a flat array
-    // which is trivially vectorisable.
-
-    // Decay at nodes — vectorisable per-pollutant stripe
-    for (int p = 0; p < np; ++p) {
-        double k = poll.k_decay[static_cast(p)];
-        if (k == 0.0) continue;
-        double decay_factor = 1.0 - k * dt;
-
-        OPENSWMM_IVDEP
-        for (int i = 0; i < ctx.n_nodes(); ++i) {
-            auto idx = static_cast(i) * static_cast(np) + static_cast(p);
-            if (idx >= ctx.nodes.conc.size()) continue;
-            ctx.nodes.conc[idx] *= decay_factor;
-            if (ctx.nodes.conc[idx] < 0.0) ctx.nodes.conc[idx] = 0.0;
-        }
-    }
-
-    // Link decay is applied within updateLinkQuality() (volume-balance mixing)
-    // so no separate per-link decay pass is needed here.
+    // Both halves of the first-order reaction now live where legacy puts
+    // them: inside the mixing kernels, applied to the STORED concentration
+    // before this step's inflow joins it (getReactedQual, called from
+    // findStorageQual and findLinkQual). Running it here as a separate pass
+    // afterwards decayed the fresh inflow as well — a whole step of decay on
+    // water that had only just arrived — and used the NEW volume as the
+    // booking basis where legacy uses the old.
+    //
+    // Kept as a no-op rather than deleted: it is a declared stage of the
+    // solver and part of its public shape.
+    (void)ctx;
+    (void)dt;
 }
 
 // ============================================================================
@@ -460,8 +1186,13 @@ void QualitySolver::updateLinkQuality(SimulationContext& ctx, double dt) {
     auto& links = ctx.links;
     auto& nodes = ctx.nodes;
     auto& poll  = ctx.pollutants;
+    auto& mb    = ctx.mass_balance;
 
     const bool is_steady = (ctx.options.routing_model == RoutingModel::STEADY);
+    // R4: reactions-active decays links exactly in reactLegacyLinks AFTER
+    // this mixing pass; the in-mix linear decay must not double-apply.
+    const bool reactions_active = transport::legacyReactionsActive(ctx);
+    const auto& CD = ctx.link_subtypes.conduits;
 
     // Batch over all links — parallelisable (each link writes to its own slot)
     // Legacy parity: src/legacy/engine/qualrout.c runs this loop serially.
@@ -470,90 +1201,139 @@ void QualitySolver::updateLinkQuality(SimulationContext& ctx, double dt) {
 #endif
     for (int j = 0; j < ctx.n_links(); ++j) {
         auto uj = static_cast(j);
-        double q = std::fabs(links.flow[uj]);
 
         int upstream = (links.flow[uj] >= 0.0) ? links.node1[uj] : links.node2[uj];
         if (upstream < 0 || upstream >= ctx.n_nodes()) continue;
         auto un = static_cast(upstream);
 
-        double v_old = links.old_volume[uj];
-        double v_new = links.volume[uj];
-
-        // Matching legacy qualrout.c findLinkQual():
-        //   New concentration = volume-balance complete-mixing with upstream
-        //   inflow, corrected for volume change, plus first-order in-link decay.
-        //
-        //   c_new = (c_old * v_old + c_up * q_in * dt - k * c_old * v_old * dt)
-        //           / max(v_new, ZERO_VOLUME)
-        //
-        // When there is no flow, the link retains its old concentration
-        // (with decay applied below).
-
-        // Evaporation concentration factor (Gap #2 / legacy findLinkQual):
-        //   fEvap = 1 + vEvap / v_old  where vEvap = evapLossRate * nBarrels * dt
-        //   Concentrates pollutants when conduit water evaporates.
-        double fEvap = 1.0;
-        if (v_old > ZERO_VOLUME) {
-            int cr = ctx.link_subtypes.conduit_row(j);
-            int nb = (cr >= 0) ? ctx.link_subtypes.conduits.barrels[static_cast(cr)] : 1;
-            double evap_rate = (cr >= 0) ? ctx.link_subtypes.conduits.evap_loss_rate[static_cast(cr)] : 0.0;
-            double v_evap = evap_rate * static_cast(nb) * dt;
-            if (v_evap > 0.0) fEvap = 1.0 + v_evap / v_old;
+        // --- legacy findLinkQual opens with the non-conduit shortcut (see
+        //     linkTakesUpstreamValue). This engine used to run the CSTR on
+        //     such links, which held the last mix whenever one carried no
+        //     flow.
+        if (linkTakesUpstreamValue(ctx, j)) {
+            for (int p = 0; p < np; ++p) {
+                auto li = uj * static_cast(np) + static_cast(p);
+                auto ni = un * static_cast(np) + static_cast(p);
+                if (li >= links.conc.size() || ni >= nodes.conc.size()) break;
+                links.conc[li] = nodes.conc[ni];
+            }
+            continue;
         }
 
+        // Legacy's test above is on the link's TYPE and cross-section alone —
+        // every CONDUIT owns a Conduit[] row. A row that does not resolve is
+        // a malformed context, not a different kind of link, so the barrel
+        // count and loss rates fall back to their defaults exactly as this
+        // function has always done rather than diverting the link.
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        const auto ucr = static_cast(cr < 0 ? 0 : cr);
+        const double barrels =
+            (cr >= 0) ? static_cast(CD.barrels[ucr]) : 1.0;
+        const double q_seep = (cr >= 0) ? CD.seep_loss_rate[ucr] * barrels : 0.0;
+        const double v_evap = (cr >= 0) ? CD.evap_loss_rate[ucr] * barrels * dt
+                                        : 0.0;
+
+        const double v_old = links.old_volume[uj];
+
+        // Evaporation concentration factor: fEvap = 1 + vEvap/v1.
+        double f_evap = 1.0;
+        if (v_evap > 0.0 && v_old > ZERO_VOLUME) f_evap += v_evap / v_old;
+
+        // |Link.newFlow| plus the DW volume-change correction — see
+        // conduitMixingInflow, which the age, heat and MSX mirrors share.
+        const double q_in = conduitMixingInflow(ctx, j, dt);
+
+        // --- legacy zeroes a link that ends the step essentially empty and
+        //     books what it held to final storage. The test is on EITHER
+        //     measure of emptiness — under a litre of water, or under a
+        //     millimetre of depth — and the depth half has no analogue here
+        //     at all. This engine did the opposite: it handed a zero-volume
+        //     link the upstream node's concentration outright, so a filling
+        //     conduit published its inflow concentration from the first
+        //     period instead of mixing up to it.
+        const bool dry = !is_steady && linkIsDry(ctx, j);
+
         for (int p = 0; p < np; ++p) {
             auto li = uj * static_cast(np) + static_cast(p);
             auto ni = un  * static_cast(np) + static_cast(p);
             if (li >= links.conc.size() || ni >= nodes.conc.size()) continue;
+            const auto up = static_cast(p);
 
-            double c_old = links.conc_old[li];
-            double c_up  = nodes.conc[ni];    // upstream node after node mixing
-
-            double k = (static_cast(p) < poll.k_decay.size())
-                ? poll.k_decay[static_cast(p)] : 0.0;
+            double k = (up < poll.k_decay.size()) ? poll.k_decay[up] : 0.0;
+            if (reactions_active) k = 0.0;
 
             double c_new;
+            double reacted = 0.0;   // KD1: decayed mass to book
+            double seeped  = 0.0;   // mass carried off by seepage
 
             if (is_steady) {
-                // Gap #38: Steady Flow quality routing (legacy findSFLinkQual).
-                // Link conc = upstream node conc, scaled by fEvap then exact
-                // exponential decay over the full routing timestep.
-                // No volume-balance mixing — steady flow has invariant volumes.
-                double c1 = c_up * fEvap;
-                c_new = (k > 0.0) ? c1 * std::exp(-k * dt) : c1;
-            } else if (q <= 0.0) {
-                // No flow: retain old concentration with in-place decay
-                // Apply fEvap first (legacy order: fEvap then decay)
-                c_new = c_old * fEvap * std::max(1.0 - k * dt, 0.0);
-            } else if (v_new <= ZERO_VOLUME) {
-                // Zero-volume link — matching legacy qualrout.c findLinkQual:
-                // when vNew == 0 the link carries upstream mass instantaneously,
-                // so assign upstream node concentration directly.
-                c_new = c_up;
+                // Steady Flow quality routing (legacy findSFLinkQual). The
+                // conduit's quality is the quality of node1 — the DOWNSTREAM
+                // node is never consulted, even on reverse flow — scaled by
+                // fEvap and then decayed EXPONENTIALLY over the whole step.
+                const int n1 = links.node1[uj];
+                if (n1 < 0 || n1 >= ctx.n_nodes()) continue;
+                const auto n1i =
+                    static_cast(n1) * static_cast(np) + up;
+                if (n1i >= nodes.conc.size()) continue;
+
+                double c1 = nodes.conc[n1i];
+                seeped = q_seep * c1 * dt;
+                c1 *= f_evap;
+                c_new = c1;
+                if (k > 0.0) {
+                    c_new = std::max(0.0, c1 * std::exp(-k * dt));
+                    // legacy findSFLinkQual: lossRate = (c1 - c2) * newFlow
+                    reacted = (c1 - c_new) * links.flow[uj] * dt;
+                }
             } else {
-                // Legacy order (findLinkQual): fEvap → decay → mix with upstream
-                //   c1 = c_old * fEvap
-                //   c2 = c1 * (1 - k*dt)                 [getReactedQual]
-                //   c_new = (c2 * v_old + c_up * q_in * dt) / (v_old + q_in * dt)
-                //
-                // Volume-change correction for DW (matching legacy line ~337):
-                //   qIn += (v2 + vLosses - v1) / tStep
-                double q_in = q;
-                if (v_new > v_old) q_in += (v_new - v_old) / dt;
-                q_in = std::max(q_in, 0.0);
-
-                double c1 = c_old * fEvap;           // evap-concentrated
-                double c2 = c1 * std::max(1.0 - k * dt, 0.0);  // decayed
-                double w_in = c_up * q_in;           // mass inflow rate
-
-                // getMixedQual: (c2 * v_old + w_in * dt) / (v_old + q_in * dt)
-                double denom = v_old + q_in * dt;
-                c_new = (denom > ZERO_VOLUME)
-                    ? (c2 * v_old + w_in * dt) / denom : c_up;
+                double c1 = links.conc_old[li];
+                seeped = q_seep * c1 * dt;
+                c1 *= f_evap;
+
+                // getReactedQual: c2 = max(0, c1 * (1 - k*dt)); the factor is
+                // clamped rather than the product so the booked removal below
+                // equals the actual loss even when 1 - k*dt goes negative
+                // (KD1).
+                double c2 = c1 * std::max(1.0 - k * dt, 0.0);
+                reacted = (c1 - c2) * v_old;
+
+                // getMixedQual(c2, v_old, wIn, q_in, dt), spelled in legacy's
+                // own operand order — cIn is formed as wIn*dt/vIn, not as the
+                // upstream concentration, and the mix is capped at
+                // max(c2, cIn). Both are algebraic no-ops in exact
+                // arithmetic and neither is one in floating point.
+                if (q_in <= LEGACY_ZERO) {
+                    c_new = c2;
+                } else {
+                    const double w_in = nodes.conc[ni] * q_in;
+                    const double v_in = q_in * dt;
+                    const double c_in = w_in * dt / v_in;
+                    const double c_max = std::max(c2, c_in);
+                    c_new = (c2 * v_old + w_in * dt) / (v_old + v_in);
+                    c_new = std::min(c_new, c_max);
+                    c_new = std::max(c_new, 0.0);
+                }
+
+                if (dry) {
+                    if (up < mb.qual_routing_final_dry.size())
+                        mb.qual_routing_final_dry[up] += c_new * links.volume[uj];
+                    c_new = 0.0;
+                }
             }
 
             c_new = std::max(c_new, 0.0);
             links.conc[li] = c_new;
+
+            // KD1: book in-link decay (legacy qualrout books both its
+            // link forms; this loop is serial — see the pragma note).
+            if (reacted > 0.0 && up < mb.qual_routing_reacted.size())
+                mb.qual_routing_reacted[up] += reacted;
+            // legacy massbal_addSeepageLoss(p, qSeep * c1), a rate the step
+            // totals scale by tStep. Until now this ledger row was never
+            // written and the .rpt reported zero exfiltrated mass.
+            if (seeped != 0.0 && up < mb.qual_routing_seep.size())
+                mb.qual_routing_seep[up] += seeped;
         }
     }
 }
@@ -562,7 +1342,8 @@ void QualitySolver::updateLinkQuality(SimulationContext& ctx, double dt) {
 // Apply treatment expressions at nodes — matching legacy treatmnt_treat()
 // ============================================================================
 
-void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
+void QualitySolver::applyTreatment(SimulationContext& ctx, double dt,
+                                   bool full_inflow) {
     int np = n_pollutants_;
     if (np <= 0) return;
     auto& treat = ctx.treatment;
@@ -575,15 +1356,59 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
         auto uj = static_cast(j);
         if (!treat.has_treatment[uj]) continue;
 
-        // 1. Compute inflow concentration: Cin[p] = mass_in[p] / vol_in
+        // 1. Inflow concentration. legacy treatmnt_setInflow (treatmnt.c:186)
+        //    is `Cin[p] = wIn[p] / qIn` — a mass RATE over a flow RATE.
+        //    qual_mass_in is a rate; qual_vol_in is a VOLUME (all eleven
+        //    writers accumulate `q * dt`, and every other reader either
+        //    divides it by dt or adds it to volumes — the "ft3/sec" in
+        //    NodeData's comment is stale). Dividing the rate by the volume
+        //    therefore left every Cin a factor of dt out. The apply path
+        //    multiplies it straight back into the treated concentration and a
+        //    removal expression naming a pollutant reads it directly: the
+        //    `treatment` deck's `R = 0.01*COD*HRT^0.75` at storage node P005
+        //    published 25.9 mg/L of COD against legacy's 755.
         double vol_in = nodes.qual_vol_in[uj];  // total inflow volume (ft3) this step
         double q_raw  = (dt > 0.0) ? vol_in / dt : 0.0;  // inflow rate (ft3/s)
         for (int p = 0; p < np; ++p) {
             auto mi = uj * static_cast(np) + static_cast(p);
-            treat.cin[static_cast(p)] =
-                (vol_in > 0.0 && mi < nodes.qual_mass_in.size())
-                ? nodes.qual_mass_in[mi] / vol_in : 0.0;
+            const bool have = mi < nodes.qual_mass_in.size();
+            if (full_inflow) {
+                treat.cin[static_cast(p)] =
+                    (q_raw > 0.0 && have) ? nodes.qual_mass_in[mi] / q_raw : 0.0;
+            } else {
+                // EULERIAN_ARD reaches here having assembled the EXTERNAL
+                // loads only, so these accumulators are not the node's
+                // influent and the ratio above is not legacy's Cin. Corrected,
+                // it exceeds the node's mixed concentration often enough that
+                // the MIN(cOut, node conc) clamp turns every removal into a
+                // no-op — which ArdE5bTest.TreatmentAppliesAtArdNodeStores
+                // correctly refuses. The real fix is for ARD to supply its own
+                // Cin from its own inflow figures, the way the LARD MIX
+                // already does (LagrangianSolver.hpp:430-438); until then the
+                // pre-existing ratio is kept here so that path is unchanged.
+                treat.cin[static_cast(p)] =
+                    (vol_in > 0.0 && have) ? nodes.qual_mass_in[mi] / vol_in : 0.0;
+            }
         }
+        applyNodeTreatment(ctx, j, dt, q_raw, treat.cin.data());
+    }
+}
+
+void applyNodeTreatment(SimulationContext& ctx, int j, double dt,
+                        double q_raw, const double* cin) {
+    const int np = ctx.n_pollutants();
+    if (np <= 0) return;
+    auto& treat = ctx.treatment;
+    if (!treat.hasAny()) return;
+    auto& nodes = ctx.nodes;
+    const auto uj = static_cast(j);
+    if (uj >= treat.has_treatment.size() || !treat.has_treatment[uj]) return;
+    {
+        // The caller's inflow concentrations become the process-variable
+        // inputs. `cin` may alias `treat.cin` (the LEGACY pass does).
+        if (cin != treat.cin.data())
+            for (int p = 0; p < np; ++p)
+                treat.cin[static_cast(p)] = cin ? cin[p] : 0.0;
 
         // 2. Get node state for process variables — apply UCF conversions (Gap #16)
         // Matching legacy treatmnt.c getVariableValue():
@@ -596,7 +1421,9 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
 
         double hrt_hours = nodes.hrt[uj] / 3600.0;
         double q = q_raw * ucf_flow;                        // flow in user units
-        double v = nodes.volume[uj];                         // volume (ft3)
+        // legacy passes vAvg = (oldVolume + newVolume)/2 as the V process
+        // variable (qualrout.c:121, 141) — not the end-of-step volume.
+        double v = (nodes.old_volume[uj] + nodes.volume[uj]) * 0.5;  // ft3
         double d_ft = (nodes.depth[uj] + nodes.old_depth[uj]) * 0.5;
         double d  = d_ft * ucf_length;                      // depth in user units
 
@@ -607,10 +1434,27 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
                                       ucf::getUnitSystem(unit_sys), &ctx.node_subtypes);
         double area = (a1 + a2) * 0.5 * ucf_length * ucf_length;  // user units²
 
-        // 3. Update HRT for storage nodes (matching legacy updateHRT)
-        if (nodes.type[uj] == NodeType::STORAGE && v > 0.0) {
-            double qdt = std::abs(q_raw) * dt;
-            nodes.hrt[uj] = (nodes.hrt[uj] + dt) * v / (v + qdt);
+        // 3. Update HRT for storage nodes. legacy updateHRT (qualrout.c:575)
+        // takes the node's OLD volume, not the average and not the new one,
+        // and RESETS the residence time to zero once the store empties:
+        //
+        //     if (v < ZERO) hrt = 0.0;
+        //     else hrt = (hrt + tStep) * v / (v + q*tStep);
+        //
+        // v6 skipped the update entirely on an empty store, so a stale
+        // residence time survived every dry spell and kept growing — and an
+        // expression like `R = 0.01*COD*HRT^0.75` reads it directly. On the
+        // `treatment` deck that drove node P005's COD to 25.9 mg/L against
+        // legacy's 755.
+        if (nodes.type[uj] == NodeType::STORAGE) {
+            const double v_old = nodes.old_volume[uj];
+            if (v_old < LEGACY_ZERO) {
+                nodes.hrt[uj] = 0.0;
+            } else {
+                const double qdt = std::abs(q_raw) * dt;
+                nodes.hrt[uj] = std::max(
+                    (nodes.hrt[uj] + dt) * v_old / (v_old + qdt), 0.0);
+            }
             hrt_hours = nodes.hrt[uj] / 3600.0;
         }
 
@@ -618,17 +1462,48 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
         for (int p = 0; p < np; ++p)
             treat.removal[static_cast(p)] = -1.0;
 
+        // 4b. What a BARE pollutant name reads. legacy getVariableValue
+        // (treatmnt.c:344-351) gives Cin[p] when THAT pollutant's treatment
+        // at this node is a removal equation, and the node's current
+        // concentration otherwise — so the choice depends on the OTHER
+        // pollutant's equation type, not this one's. Resolved here, where the
+        // per-pollutant compiled expressions are in hand, and handed to the
+        // evaluator as a plain array.
+        std::vector cpollut(static_cast(np), 0.0);
+        for (int p = 0; p < np; ++p) {
+            const auto up2 = static_cast(p);
+            const auto ci = uj * static_cast(np) + up2;
+            const bool p_is_removal =
+                ci < treat.compiled.size() && treat.compiled[ci].is_removal;
+            cpollut[up2] = p_is_removal
+                ? treat.cin[up2]
+                : ((ci < nodes.conc.size()) ? nodes.conc[ci] : 0.0);
+        }
+
         // 5. Evaluate treatment for each pollutant (with co-treatment + cycle detection)
         //    Uses the legacy getRemoval() pattern:
         //    - removal[p] == -1: not computed → evaluate now
         //    - removal[p] in [0,1]: already computed → use cached
         //    - removal[p] == 10: currently computing → cycle detected, return 0
+        // legacy latches a NODE-WIDE error the first time a removal turns out
+        // to depend on itself (treatmnt.c:402-406: `if (R[p] > 1.0 || ErrCode)
+        // { ErrCode = 1; return 0.0; }`). The latch is tested BEFORE the cached
+        // value, so once one removal cycles every other pollutant at this node
+        // reads 0 too — even one already computed. v6 returned 0 for the cycle
+        // itself but kept evaluating the rest, so err-cyclic-treatment treated
+        // pollutants legacy leaves alone.
+        // (`ErrCode = 1` never equals ERR_CYCLIC_TREATMENT = 161, so legacy
+        // does not report the error and does not skip the apply pass — it just
+        // proceeds with the zeroed removals.)
+        bool cyclic_err = false;
         auto getRemoval = [&](int p, auto& self) -> double {
             auto up = static_cast(p);
+            if (treat.removal[up] > 1.0 || cyclic_err) {
+                cyclic_err = true;
+                return 0.0;  // cycle — and every later pollutant follows it
+            }
             if (treat.removal[up] >= 0.0 && treat.removal[up] <= 1.0)
                 return treat.removal[up];  // already computed
-            if (treat.removal[up] > 1.0)
-                return 0.0;  // cycle detected
 
             auto idx = uj * static_cast(np) + up;
             if (idx >= treat.compiled.size() || treat.compiled[idx].tokens.empty()) {
@@ -644,24 +1519,42 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
             double c_node = (ci_idx < nodes.conc.size()) ? nodes.conc[ci_idx] : 0.0;
             double c_in = expr.is_removal ? treat.cin[up] : c_node;
 
-            if (c_in <= 0.0 && c_node <= 0.0) {
+            // legacy: `c0 = Node[J].newQual[p]; if (c0 == 0.0) { R[p] = 0; }`
+            // (treatmnt.c:397, 416-420) — the NODE concentration alone decides,
+            // not the inflow.
+            if (c_node <= 0.0) {
                 treat.removal[up] = 0.0;
                 return 0.0;
             }
 
-            // Before evaluation, ensure any R_POLLUT dependencies are resolved
+            // Resolve every R_POLLUT dependency through getRemoval, including
+            // one that is ALREADY being computed — that is the case legacy
+            // relies on to break a cycle, and it is also what sets the latch
+            // (treatmnt.c:384 routes R_xxx straight back into getRemoval).
+            // The old guard skipped exactly that case.
             for (const auto& tok : expr.tokens) {
                 if (tok.var == treatment::TreatVar::R_POLLUT &&
                     tok.pollut_ref >= 0 && tok.pollut_ref < np) {
-                    auto uq = static_cast(tok.pollut_ref);
-                    if (treat.removal[uq] < 0.0)
-                        self(tok.pollut_ref, self);
+                    self(tok.pollut_ref, self);
                 }
             }
 
+            // What R_xxx READS. legacy hands back getRemoval's return value,
+            // which is 0 for a pollutant still being computed; this engine
+            // passed the raw array, whose in-progress entries hold the 10.0
+            // marker. `R_TN = 0.1*R_TN` therefore evaluated to 0.1*10 = 1.0 —
+            // a 100 % removal — where legacy computes 0.1*0 = 0 and removes
+            // nothing. err-cyclic-treatment drove TN to zero against legacy's
+            // 2.96 on exactly this.
+            std::vector r_view(treat.removal.begin(),
+                                       treat.removal.end());
+            for (auto& x : r_view)
+                if (x < 0.0 || x > 1.0) x = 0.0;
+
             double result = treatment::evaluate(
                 expr, c_in, dt, hrt_hours, q, v, d,
-                treat.cin.data(), treat.removal.data(), np, area);
+                treat.cin.data(), r_view.data(), np, area,
+                cpollut.data());
             result = std::max(result, 0.0);
 
             if (expr.is_removal) {
@@ -673,8 +1566,24 @@ void QualitySolver::applyTreatment(SimulationContext& ctx, double dt) {
             return treat.removal[up];
         };
 
-        for (int p = 0; p < np; ++p)
-            getRemoval(p, getRemoval);
+        // legacy's driving loop (treatmnt.c:214-226) decides two cases WITHOUT
+        // evaluating anything: a pollutant with no equation, and a REMOVAL-type
+        // equation at a node taking no inflow, are both fixed at R = 0. Only
+        // what is left goes to getRemoval.
+        for (int p = 0; p < np; ++p) {
+            const auto up2 = static_cast(p);
+            const auto ci2 = uj * static_cast(np) + up2;
+            const bool no_eqn = ci2 >= treat.compiled.size() ||
+                                treat.compiled[ci2].tokens.empty();
+            if (no_eqn) {
+                treat.removal[up2] = 0.0;
+            } else if (treat.compiled[ci2].is_removal &&
+                       std::fabs(q_raw) <= LEGACY_ZERO) {
+                treat.removal[up2] = 0.0;
+            } else {
+                getRemoval(p, getRemoval);
+            }
+        }
 
         // 6. Apply removals to nodal concentrations + mass balance (Gap #17)
         // Legacy mass loss formula (treatmnt.c lines 262-263):
diff --git a/src/engine/quality/QualityRouting.hpp b/src/engine/quality/QualityRouting.hpp
index 528ecead0..8a32066eb 100644
--- a/src/engine/quality/QualityRouting.hpp
+++ b/src/engine/quality/QualityRouting.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file QualityRouting.hpp
  * @brief Water quality routing — constituent transport, mixing, decay.
@@ -13,7 +29,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_QUALITY_ROUTING_HPP
@@ -33,6 +49,74 @@ namespace quality {
 
 constexpr double ZERO_VOLUME = 0.0353147;  ///< 1 liter in ft3
 constexpr double ZERO_DEPTH  = 0.003281;   ///< 1 mm in ft
+/// Legacy's effective-zero flow (`ZERO` in src/legacy/engine/consts.h). The
+/// mixing kernels test the inflow RATE against this, not against 0.0.
+/// Published here because the water-age, heat and MSX transport mirrors run
+/// the same kernels and must not drift from them.
+constexpr double LEGACY_ZERO = 1.0e-10;
+
+// ============================================================================
+// Shared shape of the legacy mixing kernels
+//
+// The pollutant kernels in QualityRouting.cpp and the water-age, heat and MSX
+// mirrors in transport/components all route on the SAME rules — that identity
+// is the mirrors' design contract, and the reason WATER_AGE or HEAT_TRANSPORT
+// can be switched on without moving a pollutant trajectory. Four hand-copies
+// of those rules had already drifted apart (each mirror still carried the
+// pre-correction spelling, and their "matches the quality path" zero-volume
+// constant was 1e-10 against the quality path's one litre), so the rules live
+// here once and every kernel asks rather than re-derives.
+// ============================================================================
+
+/// Legacy findLinkQual's opening test: a non-conduit link — pump, orifice,
+/// weir, outlet — or a conduit with a DUMMY cross-section holds no water, so
+/// it takes its upstream node's value outright, with no mixing, no
+/// evaporation factor and no reaction.
+bool linkTakesUpstreamValue(const SimulationContext& ctx, int link);
+
+/// The mixing inflow rate a conduit sees over one step (legacy findLinkQual):
+/// KW's accepted upstream flow, or |Link.newFlow| for single-rate models,
+/// plus — under a single-rate dynamic model only — the volume
+/// the conduit gained together with what it lost to seepage and evaporation,
+/// the sum clamped at zero.
+double conduitMixingInflow(const SimulationContext& ctx, int link, double dt);
+
+/// Legacy findLinkQual's closing test: the link ends the step essentially
+/// empty — under a litre of water OR under a millimetre of depth.
+bool linkIsDry(const SimulationContext& ctx, int link);
+
+/// Legacy qualrout_execute's node dispatch: true when the node routes as a
+/// mixed reactor (findStorageQual), false when it is pure flow-through
+/// (findNodeQual). Note the asymmetry — the STORAGE half tests the node's
+/// TYPE, so a storage unit never drops to flow-through however empty it gets.
+bool nodeIsReactor(const SimulationContext& ctx, int node);
+
+/// Legacy findStorageQual's closing test: the node ends the step essentially
+/// empty AND is taking nothing in. Both halves matter — a dry node still
+/// receiving flow keeps its mix.
+bool nodeIsDry(const SimulationContext& ctx, int node, double q_in);
+
+/**
+ * @brief One node's [TREATMENT] application, against the CALLER's inflow
+ *        figures — the seam the LEGACY pass and the LARD MIX share.
+ *
+ * @details Evaluates the node's compiled expressions (removal- and
+ *          concentration-typed, with co-treatment resolution and cycle
+ *          detection), rewrites `nodes.conc` for every treated pollutant and
+ *          books the removed mass into `qual_routing_reacted`. The inflow
+ *          concentration and rate come from the CALLER because the two
+ *          engines hold them in different places: LEGACY accumulates
+ *          `qual_mass_in`/`qual_vol_in`, while LARD's node inflow lives in
+ *          its solver-internal drain accumulators — reading the LEGACY
+ *          arrays under LARD made an R-typed expression a literal no-op
+ *          (`cin` read 0, and `cOut = (c_in > 0) ? … : c_node` kept the
+ *          untreated value; P2.3's first draft shipped exactly that).
+ *
+ * @param q_in_cfs  Inflow rate feeding the node this interval, ft³/s.
+ * @param cin       Per-pollutant inflow concentration, length `np`.
+ */
+void applyNodeTreatment(SimulationContext& ctx, int node, double dt,
+                        double q_in_cfs, const double* cin);
 
 // ============================================================================
 // Quality solver
@@ -56,6 +140,36 @@ class QualitySolver {
      */
     void execute(SimulationContext& ctx, double dt);
 
+    /**
+     * @brief Stage 1 of execute() only: reset the assembly arrays and run the
+     *        five external-load adders (washoff, RDII, DWF, GW, iface) into
+     *        nodes.qual_mass_in / qual_vol_in — no mixing, decay, or link
+     *        update.
+     *
+     * @details Split out (behavior-preserving refactor) so the Eulerian ARD
+     *          engine (QUALITY_SOLVER EULERIAN_ARD) can consume the same
+     *          source loads while replacing the CSTR transport stages —
+     *          master plan §4.3 source-attribution seam.
+     */
+    void assembleExternalLoads(SimulationContext& ctx, double dt);
+
+    /**
+     * @brief Add direct external inflow (`[INFLOWS]` CONCEN/MASS) pollutant
+     *        loads, and the direct inflow's water, to the node assembly arrays.
+     *
+     * @details The mass rates were evaluated by the inflow solver into
+     *          nodes.ext_qual_mass (CONCEN rows already multiplied by the
+     *          node's flow). This also folds the direct inflow volume into
+     *          qual_vol_in, which is the mixing denominator — legacy divides
+     *          by Node[j].inflow, a total that includes lateral inflow.
+     * @see Legacy: routing.c addExternalInflows() pollutant portion
+     */
+    void addExtInflowLoads(SimulationContext& ctx, double dt);
+    /// S3: 2D→1D junction drain — its water into qual_vol_in, its species
+    /// mass (queued by SurfaceRouter2D, drained by assembleLateralInflows)
+    /// into qual_mass_in. No-op when no 2D coupling is active.
+    void addCouplingLoads(SimulationContext& ctx, double dt);
+
     /**
      * @brief Add subcatchment washoff quality loads to node inflows.
      *
@@ -70,8 +184,35 @@ class QualitySolver {
     /// Public for testing.
     void updateLinkQuality(SimulationContext& ctx, double dt);
 
+    /// Apply treatment expressions at nodes with treatment defined. Public
+    /// since E5b: the ARD engine reuses this exact evaluator for treatment
+    /// interop — it runs on the PUBLISHED nodes.conc after the ARD step and
+    /// the engine absorbs the treated concentrations back into its node
+    /// stores (ArdEngine::absorbTreatedNodeConc). Books its own
+    /// qual_routing_reacted losses.
+    /**
+     * @brief Apply [TREATMENT] at every node that has one.
+     *
+     * @param full_inflow  true when the caller assembled the node's COMPLETE
+     *        inflow (link mass flow plus the external loaders), which is what
+     *        legacy's Cin means. The EULERIAN_ARD entry runs only
+     *        assembleExternalLoads, so its accumulators hold the external
+     *        share alone and it passes false — see the note at the Cin site.
+     */
+    void applyTreatment(SimulationContext& ctx, double dt,
+                        bool full_inflow = true);
+
 private:
     int n_pollutants_ = 0;
+    /// Per-node LATERAL carrier volume added into qual_vol_in this step, so
+    /// the mixing denominator can be corrected to legacy's form afterwards
+    /// (routing.c:480 seeds quality inflow with MAX(0, NET lateral flow)).
+    std::vector qual_vol_lat_;
+    /// Negative lateral components seen this step (aquifer-ward GW, negative
+    /// external/DWF/iface inflows), ft3. Zero on almost every deck; the
+    /// denominator correction below fires only when this is nonzero, so
+    /// negative-free decks stay byte-identical.
+    std::vector qual_vol_lat_neg_;
 
     // Quality mass inflow arrays are stored on NodeData (nodes.qual_mass_in[],
     // nodes.qual_vol_in[]) so that external quality sources (user forcing, DWF
@@ -95,9 +236,6 @@ class QualitySolver {
     /// Batch complete mixing at all nodes.
     void mixAtNodes(SimulationContext& ctx, double dt);
 
-    /// Apply treatment expressions at nodes with treatment defined.
-    void applyTreatment(SimulationContext& ctx, double dt);
-
     /// Batch first-order decay.
     void applyDecay(SimulationContext& ctx, double dt);
 
diff --git a/src/engine/quality/Treatment.cpp b/src/engine/quality/Treatment.cpp
index 9b73dcca9..9ed6c1dc5 100644
--- a/src/engine/quality/Treatment.cpp
+++ b/src/engine/quality/Treatment.cpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Treatment.cpp
  * @brief Treatment expression parser (Shunting-yard) and evaluator (stack machine).
@@ -12,7 +28,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #include "Treatment.hpp"
@@ -21,6 +37,8 @@
 #include 
 #include 
 #include 
+#include 
+#include 
 
 namespace openswmm {
 namespace treatment {
@@ -73,15 +91,31 @@ static const std::unordered_map func_map = {
 };
 
 // Map of variable names (uppercase) to TreatVar.
+//
+// legacy's process variables are ProcessVarWords = { HRT, DT, FLOW, DEPTH,
+// AREA } (keywords.c:103). DEPTH is added here under legacy's own spelling —
+// it is how the SWMM manual writes the variable, and an expression using it
+// did not fail loudly, it hit the tokenizer's unknown-identifier path and the
+// whole treatment was skipped in silence.
+//
+// All five of legacy's process variables are accepted under legacy's own
+// spelling. FLOW was the last hold-out: the validator was contracted to
+// REJECT it, which made it the only legacy process variable this engine
+// refused, so a deck written the way the SWMM manual documents had its
+// treatment silently skipped. `Q` and `D` stay as this engine's own aliases —
+// legacy would reject them, but they cost nothing and existing decks may use
+// them.
 static const std::unordered_map var_map = {
-    {"C",    TreatVar::C},
-    {"R",    TreatVar::R},
-    {"DT",   TreatVar::DT},
-    {"HRT",  TreatVar::HRT},
-    {"Q",    TreatVar::Q},
-    {"V",    TreatVar::V},
-    {"D",    TreatVar::D},
-    {"AREA", TreatVar::AREA},  // Gap #16: legacy pvAREA
+    {"C",     TreatVar::C},
+    {"R",     TreatVar::R},
+    {"DT",    TreatVar::DT},
+    {"HRT",   TreatVar::HRT},
+    {"FLOW",  TreatVar::Q},    // legacy pvFLOW
+    {"Q",     TreatVar::Q},    // v6 alias
+    {"V",     TreatVar::V},
+    {"DEPTH", TreatVar::D},    // legacy pvDEPTH
+    {"D",     TreatVar::D},    // v6 alias
+    {"AREA",  TreatVar::AREA}, // Gap #16: legacy pvAREA
 };
 
 // ============================================================================
@@ -92,7 +126,8 @@ static const std::unordered_map var_map = {
 /// Variables and functions are recognized by name lookup.
 /// If pollut_lookup is non-null, R_xxx and C_xxx are resolved to pollutant refs.
 static std::vector tokenize(const std::string& s,
-                                    int (*pollut_lookup)(const std::string&) = nullptr) {
+                                   const std::function&
+                                       pollut_lookup = {}) {
     std::vector tokens;
     size_t i = 0;
     while (i < s.size()) {
@@ -163,6 +198,20 @@ static std::vector tokenize(const std::string& s,
                 } else {
                     return {};  // unknown pollutant name
                 }
+            } else if (pollut_lookup && pollut_lookup(word) >= 0) {
+                // A BARE pollutant name is that pollutant's concentration —
+                // legacy getVariableIndex checks the process variables, then
+                // `project_findObject(POLLUT, s)`, and only then the R_ form
+                // (treatmnt.c:307-318). This parser knew the R_/C_ forms and
+                // not the bare one, so `C = TSS * exp(-0.15*HRT)` — the form
+                // the SWMM manual uses — resolved to nothing, the token list
+                // came back empty, and the treatment was skipped WITHOUT any
+                // error. Twenty corpus decks write their expressions this way.
+                Token t;
+                t.type = TokenType::VARIABLE;
+                t.var  = TreatVar::C_POLLUT;
+                t.pollut_ref = pollut_lookup(word);
+                tokens.push_back(t);
             } else {
                 return {};  // unknown identifier
             }
@@ -650,8 +699,37 @@ double applyTreatment(const TreatExpr& expr, double c_in, double dt,
 // Extended parse with pollutant name resolution (co-treatment)
 // ============================================================================
 
+static int parse_impl(const std::string& expr_str, TreatExpr& result,
+                      const std::function& pollut_lookup);
+
+// Names-based overload. The deck-compile path has the pollutant NAME TABLE in
+// hand, not a free function, and the function-pointer overload below cannot
+// capture it — which is why both production call sites used the lookup-less
+// overload and NO deck-authored pollutant reference (bare name or R_xxx) has
+// ever resolved.
 int parse(const std::string& expr_str, TreatExpr& result,
-          int (*pollut_lookup)(const std::string& name)) {
+          const std::vector& pollut_names) {
+    result.tokens.clear();
+    result.pollutant_idx = -1;
+    result.is_removal = false;
+    auto lookup = [&pollut_names](const std::string& name) -> int {
+        for (std::size_t i = 0; i < pollut_names.size(); ++i) {
+            if (pollut_names[i].size() != name.size()) continue;
+            bool same = true;
+            for (std::size_t k = 0; k < name.size() && same; ++k)
+                same = std::toupper(static_cast(pollut_names[i][k])) ==
+                       std::toupper(static_cast(name[k]));
+            if (same) return static_cast(i);
+        }
+        return -1;
+    };
+    return parse_impl(expr_str, result, lookup);
+}
+
+// Shared body: everything below is independent of HOW a pollutant name is
+// looked up, so both public overloads funnel through here.
+static int parse_impl(const std::string& expr_str, TreatExpr& result,
+                      const std::function& pollut_lookup) {
     result.tokens.clear();
     result.pollutant_idx = -1;
     result.is_removal = false;
@@ -686,7 +764,7 @@ int parse(const std::string& expr_str, TreatExpr& result,
 double evaluate(const TreatExpr& expr, double c, double dt,
                 double hrt, double q, double v, double d,
                 const double* cin, const double* removal, int n_pollut,
-                double area) {
+                double area, const double* cpollut) {
     std::stack stk;
 
     for (const auto& tok : expr.tokens) {
@@ -706,10 +784,21 @@ double evaluate(const TreatExpr& expr, double c, double dt,
                     case TreatVar::D:     stk.push(d);    break;
                     case TreatVar::AREA:  stk.push(area); break;  // Gap #16
                     case TreatVar::C_POLLUT:
-                        if (cin && tok.pollut_ref >= 0 && tok.pollut_ref < n_pollut)
-                            stk.push(cin[tok.pollut_ref]);
-                        else
+                        // legacy getVariableValue (treatmnt.c:344-351): a
+                        // pollutant reference reads Cin[p] when THAT
+                        // pollutant's treatment here is a removal equation,
+                        // and the node's current concentration otherwise.
+                        // `cpollut` is that choice already made by the caller,
+                        // which is where the per-pollutant treatment types
+                        // are known; without it we keep the old Cin-only
+                        // reading.
+                        if (tok.pollut_ref >= 0 && tok.pollut_ref < n_pollut) {
+                            if (cpollut)   stk.push(cpollut[tok.pollut_ref]);
+                            else if (cin)  stk.push(cin[tok.pollut_ref]);
+                            else           stk.push(0.0);
+                        } else {
                             stk.push(0.0);
+                        }
                         break;
                     case TreatVar::R_POLLUT:
                         if (removal && tok.pollut_ref >= 0 && tok.pollut_ref < n_pollut)
@@ -776,5 +865,14 @@ double evaluate(const TreatExpr& expr, double c, double dt,
     return stk.empty() ? 0.0 : stk.top();
 }
 
+// Function-pointer overload, kept for callers that already have a free
+// function (the unit tests' mock lookup).
+int parse(const std::string& expr_str, TreatExpr& result,
+          int (*pollut_lookup)(const std::string& name)) {
+    if (!pollut_lookup) return parse_impl(expr_str, result, {});
+    return parse_impl(expr_str, result,
+                      std::function(pollut_lookup));
+}
+
 } // namespace treatment
 } // namespace openswmm
diff --git a/src/engine/quality/Treatment.hpp b/src/engine/quality/Treatment.hpp
index 838764d5c..477821617 100644
--- a/src/engine/quality/Treatment.hpp
+++ b/src/engine/quality/Treatment.hpp
@@ -1,3 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 /**
  * @file Treatment.hpp
  * @brief Treatment expression evaluator for water quality.
@@ -26,7 +42,7 @@
  *
  * @author   Caleb Buahin 
  * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
- * @license  MIT License
+ * @license  Apache-2.0
  */
 
 #ifndef OPENSWMM_TREATMENT_HPP
@@ -163,6 +179,19 @@ int validate(const std::string& expr_str, std::string& msg, int& col);
  * @param d      Depth.
  * @returns Computed value (concentration or removal fraction).
  */
+/**
+ * @brief Parse a treatment expression, resolving pollutant references against
+ *        a name table.
+ *
+ * @details The deck-compile path holds the pollutant NAMES, not a free
+ *          function, so this is the overload it needs. Without it no
+ *          deck-authored pollutant reference resolves at all — neither a bare
+ *          name (legacy's `project_findObject(POLLUT, s)` branch,
+ *          treatmnt.c:313) nor the R_xxx co-treatment form.
+ */
+int parse(const std::string& expr_str, TreatExpr& result,
+          const std::vector& pollut_names);
+
 double evaluate(const TreatExpr& expr, double c, double dt,
                 double hrt, double q, double v, double d, double area = 0.0);
 
@@ -185,7 +214,7 @@ double evaluate(const TreatExpr& expr, double c, double dt,
 double evaluate(const TreatExpr& expr, double c, double dt,
                 double hrt, double q, double v, double d,
                 const double* cin, const double* removal, int n_pollut,
-                double area = 0.0);
+                double area = 0.0, const double* cpollut = nullptr);
 
 /**
  * @brief Apply treatment at a node for one pollutant.
diff --git a/src/engine/quality/lard/LagrangianSolver.hpp b/src/engine/quality/lard/LagrangianSolver.hpp
new file mode 100644
index 000000000..32e3d2fe8
--- /dev/null
+++ b/src/engine/quality/lard/LagrangianSolver.hpp
@@ -0,0 +1,1093 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file LagrangianSolver.hpp
+ * @brief LARD (Lagrangian ARD) quality engine — X2: LTD transport core.
+ *
+ * @details Subplan X2 (`plans/transport/LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md`;
+ *          strategy `plans/LAGRANGIAN_QUALITY_STRATEGY.md` §2/§4, §16
+ *          amendments D-L1/D-L2/D-L5 binding). X3a: `[OPTIONS]
+ *          QUALITY_STEP` splits each routing step into equal transport
+ *          substeps (strategy §4.2) — flows are frozen within the routing
+ *          step, so refining dtq refines transport ALONE, which is what
+ *          the dt-reference instrument leans on; `MAX_SEGMENTS_PER_LINK`
+ *          sizes the slabs. Both keys warn when set under other engines.
+ *
+ *          Step orchestration (§4.2, trimmed to X2 scope):
+ *            0. flow-reversal detection → ring reversal + topo invalidation
+ *            1. DRAIN — every conduit sends |Q|·dt of back-end segment water
+ *               (and its mass) to its downstream node's inflow ledger; a
+ *               link whose new volume is below the remainder sheds the
+ *               difference through its FRONT to the upstream ledger, so
+ *               segment volume always sums exactly to `links.volume` and
+ *               the volume change is booked, never rescaled away (the E2
+ *               unbooked-resync family).
+ *            2. MIX — nodes in flow-aware topological order (Kahn; cycles
+ *               broken in index order, their residue carried in the ledger
+ *               to the next step rather than dropped): CSTR over the node's
+ *               own old volume — junctions, dividers, storages (CMSTR) and
+ *               outfalls all reduce to the same formula. External loads
+ *               join here from the SHARED loader seam (`qual_mass_in` rate ×
+ *               dt, `qual_vol_in` volume — assembled by
+ *               `QualitySolver::assembleExternalLoads`, the ARD precedent).
+ *               Zero-volume links (pump/orifice/weir/outlet) pass the node's
+ *               NEW concentration through in the same step — the reason the
+ *               order is topological (§4.3, Davis et al.).
+ *            3. RELEASE — each conduit gains a front segment at its upstream
+ *               node's new concentration, sized so the slab total equals
+ *               `links.volume` exactly; §4.5 merge tolerance collapses plug
+ *               flow.
+ *            4. DECAY — exact-exponential kdecay on segments and node
+ *               stores (species-major stripes), booked to
+ *               `qual_routing_reacted`.
+ *            5. PUBLISH — `links.conc` = volume-weighted segment mean (so
+ *               engine-side final-storage and outfall bookings are exact),
+ *               then `conc_old = conc` (the ARD convention).
+ *
+ *          X4: water age rides the segments as species row `np` — exact
+ *          aging (+dt on every live parcel and node store BEFORE
+ *          transport, the routeLegacyAge convention), volume-weighted
+ *          mixing through the same drain/mix/release phases, sources from
+ *          `node_age_vol_in` (the D-UT10 parallel accumulator, all seven
+ *          loader pathways), state published to `water_age_state`
+ *          (seconds), no decay on the age row, and the dry-link state
+ *          keeps aging (the A2b state/report separation).
+ *
+ *          X3b: `[OPTIONS] DISPERSION RWPT` activates resolved
+ *          vertical-shear dispersion on the segments (RwptDispersion.hpp,
+ *          D-X3b1: particles estimate inter-segment exchange, carry no
+ *          mass themselves), keyed by the deterministic `RWPT_SEED`
+ *          (D-L6). Runs on the substep's final field, conduits only.
+ *
+ *          Deliberately NOT here: reactions module binding (deferred L3),
+ *          heat (H7 — does not advance under this dispatch and
+ *          the open() warning says so), treatment
+ *          interop (warned bypass), storage mixing models beyond CMSTR,
+ *          the legacy evaporation up-concentration factor (recorded
+ *          deviation — steady gates cannot see it; parity work owns it),
+ *          D-NS1's clamp counter/warning (the max(0,·) floor is here, but
+ *          its observer — a negative source reaching a node — only exists
+ *          once X6 lands negative loads in the shared loaders).
+ *
+ *          Header-only for the same reason X1 was: the engine source glob
+ *          lacks CONFIGURE_DEPENDS, and a patch-applied .cpp silently does
+ *          not compile.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_QUALITY_LARD_LAGRANGIAN_SOLVER_HPP
+#define OPENSWMM_QUALITY_LARD_LAGRANGIAN_SOLVER_HPP
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../core/SimulationContext.hpp"
+#include "../../transport/InitialQualitySeeds.hpp"
+#include "../NegativeSources.hpp"
+#include "../QualityRouting.hpp"
+#include "../../transport/components/ReactionModule/ReactionLegacyBinding.hpp"
+#include "../../transport/TransportPolicy.hpp"   // E2
+#include "RwptDispersion.hpp"
+#include "SegmentStore.hpp"
+#include "../../core/UnitConversion.hpp"
+#include "../../hydraulics/Node.hpp"
+#include "../../transport/components/HeatFluxModules/BedExchange.hpp"
+#include "../../transport/components/HeatFluxModules/HeatFluxes.hpp"
+#include "../../transport/components/HeatFluxModules/HeatOverrides.hpp"
+#include "../../transport/components/HeatFluxModules/SolarRadiation.hpp"
+#include "../../transport/components/HeatFluxModules/SurfaceExchange.hpp"
+#include "../QualityRouting.hpp"
+
+namespace openswmm {
+namespace lard {
+
+constexpr double kTinyFlow = 1.0e-8;  ///< cfs; below this a link moves nothing
+
+/**
+ * @brief The segment store's species-row layout, computed in ONE place.
+ *
+ * @details H7a. Three call sites (`step`, `substep`, `init`) each used to
+ *          recompute `np + (age ? 1 : 0)` independently, and the age row was
+ *          identified by the predicate `s >= np`. That predicate is only
+ *          correct while age is the **one and only** reserved row: the
+ *          moment a second one exists (temperature, H7b) `s >= np` captures
+ *          both, and temperature would be silently aged, sourced from
+ *          `node_age_vol_in` and published to `water_age_state` — a defect
+ *          that produces plausible numbers rather than a crash.
+ *
+ *          So the row identity becomes an explicit INDEX rather than a
+ *          threshold, mirroring what the ARD engine already does
+ *          (`ArdEngine.cpp` `age_row_` / `temp_row_`). LARD is the engine
+ *          that kept the threshold because it only ever had one.
+ *
+ *          **This struct is deliberately introduced while `temp_row` is
+ *          always -1**, so the change is provably inert: with one reserved
+ *          row, `s == age_row` and `s >= np` select exactly the same row.
+ *          The corpus and the existing water-age gates are the proof. H7b
+ *          then adds the temperature row on top of a layout that is already
+ *          trusted, rather than changing the indexing and the physics in one
+ *          step where a bit-identity check can no longer separate them.
+ */
+struct SpeciesRowLayout {
+    int np        = 0;   ///< pollutant rows occupy [0, np)
+    int age_row   = -1;  ///< water-age row index, or -1 when absent
+    int temp_row  = -1;  ///< temperature row index, or -1 (H7b)
+    int msx_first = -1;  ///< first MSX species row, or -1 (L3);
+                         ///< species s rides row msx_first + s
+    int ns        = 0;   ///< total rows the store carries
+};
+
+/// The single source of truth for the row layout. Reserved rows are appended
+/// after the pollutants in a fixed order (age, then temperature) so an index
+/// means the same thing everywhere.
+inline SpeciesRowLayout rowLayout(const SimulationContext& ctx) {
+    // E2: the class ENABLES come from the one policy
+    // (transport::network1DEnables — allocation-free, this runs per step).
+    // Identical to the pre-E2 reads: LARD only runs with IGNORE_QUALITY NO,
+    // where the policy's gate is a no-op. The row ORDER below is deliberately
+    // LARD's own (pollutants, age, temperature, MSX) — see the struct note;
+    // E2 unifies the decision, not the index arithmetic.
+    const transport::ClassEnables en = transport::network1DEnables(ctx);
+    SpeciesRowLayout L;
+    L.np = en.n_pollut;
+    L.ns = L.np;
+    if (en.age)         L.age_row  = L.ns++;
+    if (en.temperature) L.temp_row = L.ns++;   // H7b
+    // L3: MSX species ride the segments after the reserved rows —
+    // stable across the run (the compiled species table is fixed at
+    // open). n_msx == 0 leaves every index above IDENTICAL to H7b's
+    // layout, which is the bit-inertness claim the corpus checks.
+    if (transport::legacyReactionsActive(ctx)) {
+        L.msx_first = L.ns;
+        L.ns += en.n_msx;
+    }
+    return L;
+}
+
+class LagrangianSolver {
+public:
+    /**
+     * @brief One routing step of LTD transport. Lazily initializes on the
+     *        first call (needs router-set volumes, the ARD precedent).
+     */
+    void step(SimulationContext& ctx, double dt_routing) {
+        // X4/H7b: the age and temperature rows ride the segments after
+        // the pollutants — age published to water_age_state (seconds),
+        // temperature to heat_state (degC) — rather than the np-strided
+        // conc arrays.
+        const SpeciesRowLayout L = rowLayout(ctx);
+        const int np = L.np;
+        const int ns = L.ns;
+        if (ns <= 0) return;
+        if (!initialized_) init(ctx);
+
+        const int nl = ctx.n_links();
+        auto& links = ctx.links;
+
+        // ---- 0. Flow reversal (§4.4) — once per routing step: the flow
+        //      solution is constant within it. -----------------------------
+        bool topo_dirty = false;
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            const double q = links.flow[ul];
+            if (std::abs(q) <= kTinyFlow) continue;
+            const std::int8_t sign = (q >= 0.0) ? 1 : -1;
+            if (sign != flow_sign_[ul]) {
+                if (links.type[ul] == LinkType::CONDUIT) store_.reverse(l);
+                flow_sign_[ul] = sign;
+                topo_dirty = true;
+            }
+        }
+        if (topo_dirty || topo_.empty()) computeTopoOrder(ctx);
+
+        // ---- X3a: QUALITY_STEP substepping (strategy §4.2). Equal
+        //      substeps; mass/age external loads are RATES and scale
+        //      through dt, the per-routing-step external VOLUME
+        //      (qual_vol_in) scales through frac. dtq absent or >= the
+        //      routing step degenerates to one substep — bit-identical to
+        //      the pre-X3a engine by construction.
+        const double dtq = ctx.options.quality_step;
+        const int nsub = (dtq > 0.0 && dtq < dt_routing)
+                             ? static_cast(std::ceil(dt_routing / dtq))
+                             : 1;
+        const double dt = dt_routing / static_cast(nsub);
+        const double frac = 1.0 / static_cast(nsub);
+        for (int sub = 0; sub < nsub; ++sub) substep(ctx, dt, frac);
+
+        // H2/H3/H6b under LARD: surface + radiative fluxes and the bed
+        // pair, once per routing step (the ARD slot), applied to the
+        // segment field before publication.
+        applyFluxesAndBed(ctx, dt_routing);
+
+        publish(ctx, dt_routing);
+    }
+
+    /**
+     * @brief One LTD substep: AGE → DRAIN → MIX(+passthrough) → RELEASE →
+     *        DECAY.
+     *
+     * @param frac  fraction of the per-routing-step external volume
+     *              (`qual_vol_in`) this substep consumes.
+     */
+    void substep(SimulationContext& ctx, double dt, double frac) {
+        const SpeciesRowLayout L = rowLayout(ctx);
+        const int np = L.np;
+        const int ns = L.ns;
+        // Derived from the layout rather than re-read from options, so the
+        // "is there a reserved row" question has exactly one answer per call.
+        const bool age  = (L.age_row >= 0);
+        const bool heat = (L.temp_row >= 0);
+        const int nn = ctx.n_nodes();
+        const int nl = ctx.n_links();
+        auto& nodes = ctx.nodes;
+        auto& links = ctx.links;
+        auto& ws = ctx.water_age_state;
+        auto& hs = ctx.heat_state;
+
+        // ---- AGE (before transport): every parcel ages by exactly dt, and
+        //      the aged value is this substep's "old" state — the plan §1
+        //      convention routeLegacyAge follows (age then mix). ------------
+        if (age) {
+            store_.add_species(L.age_row, dt);
+            for (int n = 0; n < nn; ++n)
+                ws.node_age[static_cast(n)] += dt;
+        }
+
+        // ---- 1. DRAIN (all conduits, before any node mixes) ---------------
+        scratch_.assign(static_cast(ns), 0.0);
+        treat_cin_.assign(static_cast(np > 0 ? np : 0), 0.0);
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            if (links.type[ul] != LinkType::CONDUIT) continue;
+            const double q = std::abs(links.flow[ul]);
+            const int dn = downstreamNode(ctx, l);
+            const int up = upstreamNode(ctx, l);
+
+            if (q > kTinyFlow && dn >= 0) {
+                std::fill(scratch_.begin(), scratch_.end(), 0.0);
+                const double drained = store_.drain_back(l, q * dt,
+                                                         scratch_.data());
+                addToLedger(dn, drained, scratch_.data(), ns);
+            }
+            // Volume reconciliation: the slab must sum to links.volume.
+            // A shortfall is filled at RELEASE with upstream water; an
+            // excess left after the outflow drain leaves through the FRONT
+            // to the upstream ledger — booked, not rescaled (see header).
+            const double v_new = links.volume[ul];
+            const double v_rem = store_.total_volume(l);
+            if (v_rem > v_new && up >= 0) {
+                std::fill(scratch_.begin(), scratch_.end(), 0.0);
+                const double shed = store_.drain_front(l, v_rem - v_new,
+                                                       scratch_.data());
+                addToLedger(up, shed, scratch_.data(), ns);
+            }
+        }
+
+        // ---- 2. MIX in topo order, passthrough zero-volume links ----------
+        for (const int n : topo_) {
+            const auto un = static_cast(n);
+            // The node's mixed STORE (node::storeVolume): the routers book
+            // nodes.volume in legacy's convention, 0 for a junction below
+            // its rim, but the store this solver mixes into is the water
+            // the continuity equation attributes to the node.
+            const double v_old = node::storeVolume(nodes, n, nodes.old_depth[un],
+                                                   nodes.old_volume[un]);
+            const double v_in = node_vol_in_[un];
+            // OUTFALL_BACKFLOW_QUALITY ZERO: an outfall taking no volume
+            // inflow this substep is a fresh boundary — its held state
+            // (pollutant rows AND the age row) reads zero, so the RELEASE
+            // seeding and zero-volume passthrough below draw clean water.
+            const bool zero_bf =
+                ctx.options.outfall_backflow_zero &&
+                nodes.type[un] == NodeType::OUTFALL &&
+                v_in + nodes.qual_vol_in[un] * frac <= 0.0;
+
+            for (int s = 0; s < ns; ++s) {
+                // H7a: identity by INDEX, not by threshold. `s >= np` was
+                // correct only while age was the sole reserved row; it would
+                // silently capture the temperature row too (H7b).
+                const bool is_age  = (s == L.age_row);
+                const bool is_temp = (s == L.temp_row);
+                // L3: species rows — state lives in msx_node_conc
+                // ([node*nsp + sp]); U2 gave them the [INFLOWS] pathway
+                // (msx_ext_mass_in, same index).
+                const bool is_msx =
+                    (L.msx_first >= 0 && s >= L.msx_first);
+                const auto xi =
+                    is_msx ? un * static_cast(
+                                      ns - L.msx_first) +
+                                 static_cast(s - L.msx_first)
+                           : 0;
+                const auto li = un * static_cast(ns) +
+                                static_cast(s);  // ledger index
+                // State and external load per row. Pollutants: nodes.conc +
+                // qual_mass_in (rate × dt — the mixAtNodes convention). Age:
+                // water_age_state.node_age (already aged +dt this step) +
+                // node_age_vol_in (age·ft³/s rate, the D-UT10 parallel
+                // accumulator filled by all seven loader pathways).
+                const auto ci = un * static_cast(np) +
+                                static_cast(s);
+                // Temperature mirrors age one row over: state in
+                // heat_state.node_temp (degC), external load from
+                // node_temp_vol_in (degC.ft3/s, the D-UT10 twin filled by
+                // the same seven loaders) -- H1's convention, consumed here
+                // instead of by routeLegacyHeat.
+                const double st_old =
+                    is_age  ? ws.node_age[un]
+                  : is_temp ? hs.node_temp[un]
+                  : is_msx  ? ctx.reactions.msx_node_conc[xi]
+                            : nodes.conc[ci];
+                // U2: species rows take the [INFLOWS] species loads
+                // (msx_ext_mass_in, a rate; empty when no such row).
+                const double m_ext =
+                    is_age  ? ws.node_age_vol_in[un] * dt
+                  : is_temp ? hs.node_temp_vol_in[un] * dt
+                  : is_msx  ? ((xi < ctx.reactions.msx_ext_mass_in.size())
+                                   ? ctx.reactions.msx_ext_mass_in[xi] * dt : 0.0)
+                            : nodes.qual_mass_in[ci] * dt;
+                double m = st_old * v_old + node_mass_in_[li] + m_ext;
+                // P2.3: stash the ARRIVING mass for the treatment cin below
+                // (pollutant rows only; s == p for rows 0..np-1).
+                if (!is_age && !is_temp && !is_msx &&
+                    s < static_cast(treat_cin_.size()))
+                    treat_cin_[static_cast(s)] =
+                        node_mass_in_[li] + m_ext;
+                // D-NS1 (X6, now observable): extraction beyond the
+                // store's mass clamps to available — counted, warned
+                // once, and (pollutant rows) un-booked so the ledger
+                // carries what actually left.
+                // The non-negativity clamp does NOT apply to temperature:
+                // degC water below zero is an ordinary state (the freezing
+                // gate in heat_watershed exists to keep it so), where a
+                // negative mass or age is a defect. Same reasoning as the
+                // report boundary's deliberate no-mask on temperature.
+                if (m < 0.0 && !is_temp) {
+                    if (is_age)
+                        quality::bookNegativeAgeClamp(ctx, n);
+                    else if (!is_msx)  // L3: species have no ledger row
+                        quality::bookNegativeSourceClamp(ctx, n, s, -m);
+                    m = 0.0;
+                }
+                const double denom =
+                    v_old + v_in + nodes.qual_vol_in[un] * frac;
+                // ALWAYS divide by the full denominator. m/denom is a convex
+                // combination of st_old and the arriving values, so it can
+                // never exceed its inputs; the fallback this replaces
+                // divided a mass that included st_old*v_old by a divisor
+                // that EXCLUDED v_old, and at a nearly-dry junction that
+                // quotient amplified step over step -- measured on a
+                // receding-flow deck (inflow stops at 1 h): node
+                // concentrations reached 2.7e30, 2.0e281, then inf, and the
+                // final-storage row went NaN. Below 1e-12 ft^3 there is no
+                // meaningful water and the store keeps its value.
+                const double st_new =
+                    zero_bf ? 0.0
+                            : ((denom > 1.0e-12) ? m / denom : st_old);
+                if (is_age)       ws.node_age[un] = st_new;
+                else if (is_temp) hs.node_temp[un] = st_new;
+                else if (is_msx)  ctx.reactions.msx_node_conc[xi] = st_new;
+                else              nodes.conc[ci] = st_new;
+                node_mass_in_[li] = 0.0;  // consumed; cycle residue carries
+            }
+            node_vol_in_[un] = 0.0;
+
+            // P2.3: [TREATMENT] applies HERE — to the freshly mixed node
+            // state, BEFORE the passthrough and RELEASE below draw it: the
+            // LEGACY ordering (mix → treat → links), transplanted. The
+            // handoff's end-of-step application outside the solver was a
+            // no-op twice over: the evaluator's cin read the LEGACY
+            // accumulators (external loads only — 0 at an interior node,
+            // and an R-typed expression keeps c_node when cin reads 0),
+            // and a junction's ~zero stored volume gave the late write no
+            // weight in the next mix. Fed with THIS substep's inflow
+            // figures instead; nodes with no treatment pay one flag test.
+            if (np > 0 && dt > 0.0 &&
+                un < ctx.treatment.has_treatment.size() &&
+                ctx.treatment.has_treatment[un]) {
+                const double v_in_total =
+                    v_in + nodes.qual_vol_in[un] * frac;
+                for (int p = 0; p < np; ++p)
+                    treat_cin_[static_cast(p)] =
+                        (v_in_total > 1.0e-12)
+                            ? std::max(0.0,
+                                       treat_cin_[
+                                           static_cast(p)]) /
+                                  v_in_total
+                            : 0.0;
+                quality::applyNodeTreatment(ctx, n, dt, v_in_total / dt,
+                                            treat_cin_.data());
+            }
+
+            // Zero-volume passthrough (§2.4): outgoing pump/orifice/weir/
+            // outlet links deliver the node's NEW concentration downstream
+            // within this step — the property the topo order exists for.
+            for (const int l : node_out_links_[un]) {
+                const auto ul = static_cast(l);
+                if (links.type[ul] == LinkType::CONDUIT) continue;
+                const double q = std::abs(links.flow[ul]);
+                if (q <= kTinyFlow) continue;
+                const int dn = downstreamNode(ctx, l);
+                if (dn < 0) continue;
+                for (int p = 0; p < np; ++p) {
+                    const auto ni = un * static_cast(np) +
+                                    static_cast(p);
+                    const auto lp = ul * static_cast(np) +
+                                    static_cast(p);
+                    scratch_[static_cast(p)] = nodes.conc[ni];
+                    links.conc[lp] = nodes.conc[ni];
+                }
+                if (age) {
+                    scratch_[static_cast(L.age_row)] =
+                        ws.node_age[un];
+                    ws.link_age[ul] = ws.node_age[un];
+                }
+                if (heat) {
+                    scratch_[static_cast(L.temp_row)] =
+                        hs.node_temp[un];
+                    hs.link_temp[ul] = hs.node_temp[un];
+                }
+                if (L.msx_first >= 0) {  // L3
+                    const int nsp = ns - L.msx_first;
+                    for (int sp = 0; sp < nsp; ++sp) {
+                        const double c = ctx.reactions.msx_node_conc[
+                            un * static_cast(nsp) +
+                            static_cast(sp)];
+                        scratch_[static_cast(
+                            L.msx_first + sp)] = c;
+                        ctx.reactions.msx_link_conc[
+                            ul * static_cast(nsp) +
+                            static_cast(sp)] = c;
+                    }
+                }
+                addToLedgerRate(dn, q * dt, scratch_.data(), ns);
+            }
+        }
+
+        // ---- 3. RELEASE new front segments --------------------------------
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            if (links.type[ul] != LinkType::CONDUIT) continue;
+            const int up = upstreamNode(ctx, l);
+            const double need = links.volume[ul] - store_.total_volume(l);
+            release_vol_[ul] = (need > 0.0) ? need : 0.0;  // X3b: RWPT's V_in
+            if (need <= 0.0 || up < 0) continue;
+            const auto uu = static_cast(up);
+            for (int p = 0; p < np; ++p)
+                scratch_[static_cast(p)] =
+                    nodes.conc[uu * static_cast(np) +
+                               static_cast(p)];
+            if (age)
+                scratch_[static_cast(L.age_row)] =
+                    ws.node_age[uu];
+            if (heat)
+                scratch_[static_cast(L.temp_row)] =
+                    hs.node_temp[uu];
+            if (L.msx_first >= 0) {  // L3
+                const int nsp = ns - L.msx_first;
+                for (int sp = 0; sp < nsp; ++sp)
+                    scratch_[static_cast(
+                        L.msx_first + sp)] =
+                        ctx.reactions.msx_node_conc[
+                            uu * static_cast(nsp) +
+                            static_cast(sp)];
+            }
+            store_.push_front(l, need, scratch_.data());
+        }
+
+        // ---- 3b. RWPT dispersion (X3b) — on the substep's FINAL segment
+        //      field, per link, resolved vertical shear + walk. The age row
+        //      disperses with the water like every other species — mixing
+        //      moves age, physically. H7b: so does TEMPERATURE, at the same
+        //      coefficient as a solute — the ARD engine's deliberate choice
+        //      for its temperature row, adopted here for cross-engine
+        //      consistency (decision 2026-08-30). ---------------------------
+        if (ctx.options.lard_rwpt) {
+            ++substep_counter_;
+            const auto& cond = ctx.link_subtypes.conduits;
+            for (int l = 0; l < nl; ++l) {
+                const auto ul = static_cast(l);
+                if (links.type[ul] != LinkType::CONDUIT) continue;
+                const double q = std::abs(links.flow[ul]);
+                if (q <= kTinyFlow) continue;
+                const int row = ctx.link_subtypes.conduit_row(l);
+                if (row < 0) continue;
+                const auto ur = static_cast(row);
+                const double len = cond.length[ur];
+                const double vol = links.volume[ul];
+                if (len <= 0.0 || vol <= 0.0) continue;
+                const double a_flow = vol / len;
+                const double ubar = q / a_flow;
+                const double h = links.depth[ul];
+                const bool circ =
+                    links.xsect_shape[ul] == XsectShape::CIRCULAR;
+                const double rh =
+                    rwpt_hyd_radius(a_flow, h, links.xsect_geom1[ul], circ);
+                rwpt_.disperse(ctx, store_, l, ubar, h, rh,
+                               cond.roughness[ur], release_vol_[ul],
+                               q * dt, dt, substep_counter_,
+                               static_cast(
+                                   ctx.options.rwpt_seed),
+                               scratch_);
+            }
+        }
+
+        // ---- 4. DECAY (exact exponential; species-major stripes) ----------
+        for (int p = 0; p < np; ++p) {
+            const double k = ctx.pollutants.k_decay[static_cast(p)];
+            if (k == 0.0) continue;
+            const double f = std::exp(-k * dt);
+            double removed = store_.decay_species(p, f);
+            for (int n = 0; n < nn; ++n) {
+                const auto idx = static_cast(n) *
+                                     static_cast(np) +
+                                 static_cast(p);
+                const double v = node::storeVolume(nodes, n);
+                removed += nodes.conc[idx] * (1.0 - f) * v;
+                nodes.conc[idx] *= f;
+            }
+            if (static_cast(p) <
+                ctx.mass_balance.qual_routing_reacted.size())
+                ctx.mass_balance.qual_routing_reacted[
+                    static_cast(p)] += removed;
+        }
+
+        // ---- 4b. REACT (L3): MSX species integrate per SEGMENT (pipe
+        //      scope, the segment's own pollutant rows as context) and
+        //      per NODE store (tank scope, the node's HRT) — D-L1's
+        //      gather/scatter through the shared integrator. Pollutant
+        //      kdecay is NOT re-applied here: stage 4 owns it (the
+        //      integrator handles only MSX kinetics), so there is no
+        //      double-decay the way the legacy binding had to avoid.
+        if (L.msx_first >= 0) {
+            auto& rx = ctx.reactions;
+            const int nsp = ns - L.msx_first;
+            if (static_cast(msx_block_.size()) < nsp)
+                msx_block_.assign(static_cast(nsp), 0.0);
+            if (static_cast(msx_poll_.size()) < np && np > 0)
+                msx_poll_.assign(static_cast(np), 0.0);
+            for (int l = 0; l < nl; ++l) {
+                const auto ul = static_cast(l);
+                if (links.type[ul] != LinkType::CONDUIT) continue;
+                const int cnt = store_.count(l);
+                for (int i = 0; i < cnt; ++i) {
+                    for (int sp = 0; sp < nsp; ++sp)
+                        msx_block_[static_cast(sp)] =
+                            store_.seg_conc(l, i, L.msx_first + sp);
+                    for (int p = 0; p < np; ++p)
+                        msx_poll_[static_cast(p)] =
+                            store_.seg_conc(l, i, p);
+                    // TEMP: the segment's own temperature row when heat
+                    // rides the store (H7b); NaN defers to the
+                    // [REACTION_OPTIONS] TEMPERATURE constant.
+                    const double seg_temp_c =
+                        (L.temp_row >= 0)
+                            ? store_.seg_conc(l, i, L.temp_row)
+                            : std::numeric_limits::quiet_NaN();
+                    transport::reactSpeciesBlock(
+                        ctx, /*tank=*/false, dt, msx_block_.data(),
+                        np > 0 ? msx_poll_.data() : nullptr, 0.0,
+                        seg_temp_c);
+                    for (int sp = 0; sp < nsp; ++sp)
+                        store_.set_seg_conc(l, i, L.msx_first + sp,
+                                            msx_block_[
+                                                static_cast(
+                                                    sp)]);
+                }
+            }
+            for (int n = 0; n < nn; ++n) {
+                const auto un = static_cast(n);
+                for (int sp = 0; sp < nsp; ++sp)
+                    msx_block_[static_cast(sp)] =
+                        rx.msx_node_conc[un * static_cast(
+                                                  nsp) +
+                                         static_cast(sp)];
+                for (int p = 0; p < np; ++p)
+                    msx_poll_[static_cast(p)] =
+                        nodes.conc[un * static_cast(np) +
+                                   static_cast(p)];
+                const double hrt =
+                    (un < nodes.hrt.size()) ? nodes.hrt[un] : 0.0;
+                const double node_temp_c =
+                    (L.temp_row >= 0 &&
+                     un < ctx.heat_state.node_temp.size())
+                        ? ctx.heat_state.node_temp[un]
+                        : std::numeric_limits::quiet_NaN();
+                transport::reactSpeciesBlock(
+                    ctx, /*tank=*/true, dt, msx_block_.data(),
+                    np > 0 ? msx_poll_.data() : nullptr, hrt,
+                    node_temp_c);
+                for (int sp = 0; sp < nsp; ++sp)
+                    rx.msx_node_conc[un * static_cast(nsp) +
+                                     static_cast(sp)] =
+                        msx_block_[static_cast(sp)];
+            }
+        }
+    }
+
+    /// Per-routing-step publication: link means + the conc_old convention.
+    /// `dt_routing` ages the held state of empty slabs (once per step).
+    void publish(SimulationContext& ctx, double dt_routing) {
+        // H7b: the fourth layout-aware site joins rowLayout() (H7a
+        // converted step/substep/init and flagged this one).
+        const SpeciesRowLayout L = rowLayout(ctx);
+        const int np = L.np;
+        const bool age  = (L.age_row >= 0);
+        const bool heat = (L.temp_row >= 0);
+        const int nl = ctx.n_links();
+        auto& nodes = ctx.nodes;
+        auto& links = ctx.links;
+        auto& ws = ctx.water_age_state;
+        auto& hs = ctx.heat_state;
+
+        // ---- 5. PUBLISH ---------------------------------------------------
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            if (links.type[ul] != LinkType::CONDUIT) continue;
+            store_.mean_conc(l, scratch_.data());
+            for (int p = 0; p < np; ++p)
+                links.conc[ul * static_cast(np) +
+                           static_cast(p)] =
+                    scratch_[static_cast(p)];
+            // Age: volume-weighted mean over the same segments, seconds.
+            // The dry-element report mask (A2b) is at the report boundary,
+            // engine-side — state keeps aging here regardless. An EMPTY
+            // slab holds no parcels to average, so the link's held age
+            // ages in place instead of resetting to 0 — the state/report
+            // separation the dry-mask round established (a dry element's
+            // STATE keeps aging; only the report masks it).
+            if (age) {
+                if (store_.count(l) > 0)
+                    ws.link_age[ul] =
+                        scratch_[static_cast(L.age_row)];
+                else
+                    ws.link_age[ul] += dt_routing;
+            }
+            // Temperature: volume-weighted mean over the same segments. An
+            // EMPTY slab HOLDS its temperature — unlike age it does not
+            // grow, and unlike the age report it is not masked when dry
+            // (0 degC is an ordinary temperature; the no-mask call is
+            // documented at the snapshot builder).
+            if (heat) {
+                if (store_.count(l) > 0)
+                    hs.link_temp[ul] =
+                        scratch_[static_cast(L.temp_row)];
+            }
+            // L3: species rows publish like temperature — an EMPTY
+            // slab HOLDS its concentration.
+            if (L.msx_first >= 0 && store_.count(l) > 0) {
+                const int nsp = L.ns - L.msx_first;
+                for (int sp = 0; sp < nsp; ++sp)
+                    ctx.reactions.msx_link_conc[
+                        ul * static_cast(nsp) +
+                        static_cast(sp)] =
+                        scratch_[static_cast(
+                            L.msx_first + sp)];
+            }
+        }
+        // conc_old bookkeeping matches the ARD/legacy convention.
+        links.conc_old = links.conc;
+        nodes.conc_old = nodes.conc;
+    }
+
+private:
+    /**
+     * @brief Surface + radiative fluxes and the H6b bed pair, LARD spelling.
+     *
+     * @details Nodes relax exactly as `HeatFluxes.cpp` relaxes them (the
+     *          node stores ARE `heat_state.node_temp` under this engine).
+     *          Links act on the SEGMENT field: the pair/relaxation is solved
+     *          against the volume-weighted link mean and the increment is
+     *          applied UNIFORMLY to every segment. Uniform-in-temperature is
+     *          exact for the flux linearization — each segment's surface
+     *          share is proportional to its volume, so k = A·J′/(ρ·cp·V) is
+     *          the same for every segment — and it preserves the along-link
+     *          profile, which is the property this engine exists for.
+     *          Solutes take the same uniform-delta spelling from
+     *          `exchangePair`. The bed itself stays per LINK (well-mixed
+     *          along the conduit) — a per-parcel bed would have to move
+     *          with the water, and a bed does not move. Recorded divergence.
+     *
+     *          Until this method the LARD engine TRANSPORTED temperature
+     *          but applied no flux module at all, silently — a deck with
+     *          SURFACE_EXCHANGE ON simply did not exchange, and no warning
+     *          said so. Found while closing H6b §4.
+     */
+    void applyFluxesAndBed(SimulationContext& ctx, double dt) {
+        const SpeciesRowLayout L = rowLayout(ctx);
+        const bool heat_on = (L.temp_row >= 0);
+        const bool bed_on  = transport::heat::bedExchangeEnabled(ctx);
+        const bool flux_on =
+            heat_on && (ctx.heat_config.surface_exchange ||
+                        ctx.heat_config.radiative_exchange);
+        if ((!flux_on && !bed_on) || !(dt > 0.0)) return;
+        namespace th = transport::heat;
+
+        if (flux_on) th::updateSolarForcing(ctx);
+        if (bed_on) th::seedBedTemperature(ctx);
+        const double t_gr = bed_on ? th::groundTemperature(ctx) : 0.0;
+        const double rho = ctx.options.water_density;
+        const double cp  = ctx.options.water_specific_heat;
+        constexpr double kSqFt = 0.09290304;
+        constexpr double kCuFt = 0.028316846592;
+
+        auto& hs = ctx.heat_state;
+        const int nl = ctx.n_links();
+        const int nn = ctx.n_nodes();
+
+        // ---- Nodes: storage surfaces only, HeatFluxes.cpp's convention. --
+        if (flux_on) {
+            const int unit_sys = ucf::getUnitSystem(
+                static_cast(ctx.options.flow_units));
+            for (int n = 0; n < nn; ++n) {
+                const auto un = static_cast(n);
+                if (un >= hs.node_temp.size()) break;
+                const double vol = node::storeVolume(ctx.nodes, n);
+                if (!(vol > 0.0)) continue;
+                const double a = node::getSurfArea(
+                    ctx.nodes, n, ctx.nodes.depth[un], &ctx.tables,
+                    unit_sys, &ctx.node_subtypes);
+                if (!(a > 0.0)) continue;
+                const double t = hs.node_temp[un];
+                const HeatElement ne = HeatElement::node(n);
+                hs.node_temp[un] += th::relaxT(
+                    th::netFluxOut(ctx, ne, t),
+                    th::netFluxOut(ctx, ne, t + th::kProbeC), th::kProbeC,
+                    a * kSqFt, vol * kCuFt, dt, rho, cp);
+            }
+        }
+
+        // ---- Links: segment field, uniform increments. -------------------
+        // Bed rows: pollutants then MSX — every row before age/temp.
+        const int n_bed = L.np + ((L.msx_first >= 0) ? (L.ns - L.msx_first)
+                                                     : 0);
+        auto& bed = ctx.bed_state;
+        if (bed_on && n_bed > 0 &&
+            (bed.n_species != n_bed ||
+             bed.link_conc.size() != static_cast(nl) *
+                                         static_cast(n_bed))) {
+            bed.link_conc.assign(static_cast(nl) *
+                                     static_cast(n_bed),
+                                 0.0);
+            bed.n_species = n_bed;
+        }
+
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            if (ctx.links.type[ul] != LinkType::CONDUIT) continue;
+            const int cnt = store_.count(l);
+            if (cnt <= 0) continue;
+            const double vol_ft3 = store_.total_volume(l);
+            if (!(vol_ft3 > 0.0)) continue;
+
+            store_.mean_conc(l, scratch_.data());
+            // PE1: every parcel of a conduit shares the conduit's
+            // attributes (D-PE1) — the bed and the shading belong to the
+            // pipe, not to the water passing through it.
+            const HeatElement le = HeatElement::link(l);
+
+            // Heat: one pair/relaxation against the mean, uniform dT.
+            if (heat_on) {
+                const double t_mean =
+                    scratch_[static_cast(L.temp_row)];
+                const double surf_m2 =
+                    flux_on ? th::linkFreeSurfaceFt2(ctx, l) * kSqFt : 0.0;
+                double d_tw = 0.0;
+                bool bed_stepped = false;
+                if (bed_on && ul < bed.link_temp.size()) {
+                    // PE2: this link's own bed material and boundary.
+                    const auto& sd = th::sedimentFor(ctx, le);
+                    const th::BedCoupling g = th::bedCouplingFromContact(
+                        ctx, sd, th::linkBedAreaM2(ctx, l), vol_ft3,
+                        th::groundTempFor(ctx, sd, t_gr));
+                    if (g.viable()) {
+                        const th::PairStep ps = th::relaxPair(
+                            g, t_mean, bed.link_temp[ul],
+                            flux_on ? th::netFluxOut(ctx, le, t_mean) : 0.0,
+                            flux_on ? th::netFluxOut(ctx, le,
+                                                     t_mean + th::kProbeC)
+                                    : 0.0,
+                            flux_on ? th::kProbeC : 0.0, surf_m2, dt);
+                        d_tw = ps.dt_w;
+                        bed.link_temp[ul] += ps.dt_b;
+                        bed_stepped = true;
+                    }
+                }
+                if (!bed_stepped && flux_on && surf_m2 > 0.0) {
+                    d_tw = th::relaxT(
+                        th::netFluxOut(ctx, le, t_mean),
+                        th::netFluxOut(ctx, le, t_mean + th::kProbeC),
+                        th::kProbeC, surf_m2, vol_ft3 * kCuFt, dt, rho, cp);
+                }
+                if (d_tw != 0.0)
+                    for (int i = 0; i < cnt; ++i)
+                        store_.set_seg_conc(
+                            l, i, L.temp_row,
+                            store_.seg_conc(l, i, L.temp_row) + d_tw);
+            }
+
+            // Solutes: pair against the mean, uniform dc, per bed row.
+            if (bed_on && n_bed > 0) {
+                // PE2: same per-link config the heat pair above used, so the
+                // two halves of one bed cannot disagree about its material.
+                const auto& sd = th::sedimentFor(ctx, le);
+                const double bed_m2 = th::linkBedAreaM2(ctx, l);
+                const double vol_b = bed_m2 * sd.bed_thickness;
+                const double q_exch = th::bedExchangeQ(sd, bed_m2);
+                if (q_exch > 0.0 && vol_b > 0.0) {
+                    for (int b = 0; b < n_bed; ++b) {
+                        // Bed row b: pollutants 0..np-1 map directly, MSX
+                        // rows at msx_first + (b - np).
+                        const int row = (b < L.np)
+                                            ? b
+                                            : L.msx_first + (b - L.np);
+                        const double c_mean =
+                            scratch_[static_cast(row)];
+                        double& cb = bed.link_conc[
+                            ul * static_cast(n_bed) +
+                            static_cast(b)];
+                        const th::SolutePairStep st = th::exchangePair(
+                            c_mean, cb, vol_ft3 * kCuFt, vol_b, q_exch,
+                            dt);
+                        if (st.dc_w != 0.0)
+                            for (int i = 0; i < cnt; ++i)
+                                store_.set_seg_conc(
+                                    l, i, row,
+                                    store_.seg_conc(l, i, row) + st.dc_w);
+                        cb += st.dc_b;
+                    }
+                }
+            }
+        }
+    }
+
+    void init(SimulationContext& ctx) {
+
+        const SpeciesRowLayout L = rowLayout(ctx);
+        const int np = L.np;
+        const int ns = L.ns;
+        // Derived from the layout rather than re-read from options, so the
+        // "is there a reserved row" question has exactly one answer per call.
+        const bool age  = (L.age_row >= 0);
+        const bool heat = (L.temp_row >= 0);
+        const int nn = ctx.n_nodes();
+        const int nl = ctx.n_links();
+        // X3a: slab capacity from [OPTIONS] MAX_SEGMENTS_PER_LINK, floored
+        // at 2 (one segment to hold, one to receive).
+        store_.resize(nl, ns,
+                      std::max(2, ctx.options.max_segments_per_link));
+        flow_sign_.assign(static_cast(nl), 1);
+        node_mass_in_.assign(
+            static_cast(nn) * static_cast(ns), 0.0);
+        node_vol_in_.assign(static_cast(nn), 0.0);
+        scratch_.assign(static_cast(ns), 0.0);
+        treat_cin_.assign(static_cast(np > 0 ? np : 0), 0.0);
+        node_out_links_.assign(static_cast(nn), {});
+        release_vol_.assign(static_cast(nl), 0.0);
+        if (ctx.options.lard_rwpt) rwpt_.resize(nl);
+
+        // L3: size + seed the shared MSX element state (GLOBAL fill +
+        // [REACTION_QUALITY] overrides) with the SAME spelling the
+        // LEGACY dispatch uses, then let the seeded link values seed
+        // the segments below like every other row.
+        if (L.msx_first >= 0) transport::ensureMsxState(ctx);
+
+        // X4 age seeding, the ARD precedent: a hotstart-loaded state wins
+        // (node_age/link_age already carry the restored values, A2a);
+        // otherwise a configured INITIAL_STATE age fills the network.
+        // Restored/seeded link ages then seed the segments below — the
+        // same within-link profile collapse A2a recorded for ARD
+        // (lesson 37): continuous, not bit-continuous.
+        if (age) {
+            auto& ws = ctx.water_age_state;
+            if (ws.node_age.size() != static_cast(nn))
+                ws.resize(nn, nl, ctx.n_subcatches());
+            if (!ws.hotstart_loaded) {
+                const double a0 = ctx.water_age_config.global_age[
+                    static_cast(WaterAgeSource::INITIAL_STATE)];
+                if (a0 > 0.0) {
+                    std::fill(ws.node_age.begin(), ws.node_age.end(), a0);
+                    std::fill(ws.link_age.begin(), ws.link_age.end(), a0);
+                }
+            }
+            // E-A3: [INITIAL_QUALITY] __WATER_AGE__ rows override the
+            // global fill; the helper no-ops under hotstart (D-IQ7). The
+            // per-link values then seed the segments below.
+            transport::applyInitialAgeOverrides(ctx);
+        }
+
+        // H7b temperature seeding, the routeLegacyHeat convention: size the
+        // state if the loaders have not already, fill with the configured
+        // INITIAL_STATE once (legacy_seeded — shared with the LEGACY mirror
+        // so a fallback path never re-seeds), then let per-element
+        // [INITIAL_QUALITY] __TEMPERATURE__ rows override. The seeded link
+        // temperatures seed the segments below, the same within-link
+        // profile collapse the age row records (lesson 37): continuous,
+        // not bit-continuous. Hotstart does NOT restore temperature — no
+        // engine's does, the record has no field for it (owed; see the
+        // H7b round record) — so a restarted run re-seeds from
+        // INITIAL_STATE exactly as LEGACY and ARD do.
+        if (heat) {
+            auto& hstate = ctx.heat_state;
+            const double t0 = ctx.heat_config.global_temp[
+                static_cast(HeatSource::INITIAL_STATE)];
+            if (hstate.node_temp.size() != static_cast(nn))
+                hstate.resize(nn, nl, t0);
+            if (!hstate.legacy_seeded) {
+                std::fill(hstate.node_temp.begin(), hstate.node_temp.end(),
+                          t0);
+                std::fill(hstate.link_temp.begin(), hstate.link_temp.end(),
+                          t0);
+                transport::applyInitialTempOverrides(ctx);
+                hstate.legacy_seeded = true;
+            }
+        }
+
+        // Seed: one segment per conduit at the link's current volume and
+        // (initQuality-seeded) concentration — a dry link seeds nothing.
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            store_.clear_link(l);
+            if (ctx.links.type[ul] != LinkType::CONDUIT) continue;
+            const double v = ctx.links.volume[ul];
+            if (v <= 0.0) continue;
+            for (int p = 0; p < np; ++p)
+                scratch_[static_cast(p)] =
+                    ctx.links.conc[ul * static_cast(np) +
+                                   static_cast(p)];
+            if (age)
+                scratch_[static_cast(L.age_row)] =
+                    ctx.water_age_state.link_age[ul];
+            if (heat)
+                scratch_[static_cast(L.temp_row)] =
+                    ctx.heat_state.link_temp[ul];
+            if (L.msx_first >= 0) {  // L3
+                const int nsp = ns - L.msx_first;
+                for (int sp = 0; sp < nsp; ++sp)
+                    scratch_[static_cast(
+                        L.msx_first + sp)] =
+                        ctx.reactions.msx_link_conc[
+                            ul * static_cast(nsp) +
+                            static_cast(sp)];
+            }
+            store_.push_front(l, v, scratch_.data());
+            flow_sign_[ul] = (ctx.links.flow[ul] >= 0.0) ? 1 : -1;
+        }
+        computeTopoOrder(ctx);
+        initialized_ = true;
+    }
+
+    int upstreamNode(const SimulationContext& ctx, int l) const {
+        const auto ul = static_cast(l);
+        return (flow_sign_[ul] >= 0) ? ctx.links.node1[ul]
+                                     : ctx.links.node2[ul];
+    }
+    int downstreamNode(const SimulationContext& ctx, int l) const {
+        const auto ul = static_cast(l);
+        return (flow_sign_[ul] >= 0) ? ctx.links.node2[ul]
+                                     : ctx.links.node1[ul];
+    }
+
+    void addToLedger(int n, double vol, const double* mass, int np) {
+        const auto un = static_cast(n);
+        node_vol_in_[un] += vol;
+        for (int p = 0; p < np; ++p)
+            node_mass_in_[un * static_cast(np) +
+                          static_cast(p)] +=
+                mass[static_cast(p)];
+    }
+    /// Ledger add where `conc` (not mass) is supplied — passthrough links.
+    void addToLedgerRate(int n, double vol, const double* conc, int np) {
+        const auto un = static_cast(n);
+        node_vol_in_[un] += vol;
+        for (int p = 0; p < np; ++p)
+            node_mass_in_[un * static_cast(np) +
+                          static_cast(p)] +=
+                vol * conc[static_cast(p)];
+    }
+
+    /// Kahn over the node graph, edges from links with |Q| > kTinyFlow in
+    /// current flow direction (§4.3). Cycles: leftovers appended in index
+    /// order — their same-step passthrough mass carries in the ledger to
+    /// the next step instead of being dropped.
+    void computeTopoOrder(SimulationContext& ctx) {
+        const int nn = ctx.n_nodes();
+        const int nl = ctx.n_links();
+        std::vector indeg(static_cast(nn), 0);
+        for (auto& v : node_out_links_) v.clear();
+        for (int l = 0; l < nl; ++l) {
+            const auto ul = static_cast(l);
+            const int up = upstreamNode(ctx, l);
+            const int dn = downstreamNode(ctx, l);
+            if (up < 0 || dn < 0) continue;
+            node_out_links_[static_cast(up)].push_back(l);
+            if (std::abs(ctx.links.flow[ul]) > kTinyFlow)
+                indeg[static_cast(dn)] += 1;
+        }
+        topo_.clear();
+        topo_.reserve(static_cast(nn));
+        std::vector q;
+        for (int n = 0; n < nn; ++n)
+            if (indeg[static_cast(n)] == 0) q.push_back(n);
+        std::vector seen(static_cast(nn), 0);
+        std::size_t qi = 0;
+        while (qi < q.size()) {
+            const int n = q[qi++];
+            if (seen[static_cast(n)]) continue;
+            seen[static_cast(n)] = 1;
+            topo_.push_back(n);
+            for (const int l : node_out_links_[static_cast(n)]) {
+                if (std::abs(ctx.links.flow[static_cast(l)]) <=
+                    kTinyFlow)
+                    continue;
+                const int dn = downstreamNode(ctx, l);
+                if (dn >= 0 && --indeg[static_cast(dn)] == 0)
+                    q.push_back(dn);
+            }
+        }
+        for (int n = 0; n < nn; ++n)  // cycle leftovers
+            if (!seen[static_cast(n)]) topo_.push_back(n);
+    }
+
+    SegmentStore store_;
+    RwptDispersion rwpt_;                ///< X3b particle field
+    std::vector release_vol_;    ///< per-substep V_in per link (X3b)
+    std::uint64_t substep_counter_ = 0;  ///< D-L6 RNG key component
+    std::vector topo_;
+    std::vector> node_out_links_;
+    std::vector flow_sign_;
+    std::vector node_mass_in_;  ///< per-step ledger, mass
+    std::vector node_vol_in_;   ///< per-step ledger, volume
+    std::vector scratch_;       ///< np-sized work array
+    /// P2.3: per-substep inflow MASS per pollutant at the node under MIX,
+    /// becoming the treatment evaluator's cin — LARD's own inflow figures,
+    /// because the LEGACY accumulators carry only external loads here.
+    std::vector treat_cin_;
+    std::vector msx_block_;     ///< L3: per-element species block
+    std::vector msx_poll_;      ///< L3: pollutant context block
+    bool initialized_ = false;
+};
+
+}  // namespace lard
+}  // namespace openswmm
+
+#endif  // OPENSWMM_QUALITY_LARD_LAGRANGIAN_SOLVER_HPP
diff --git a/src/engine/quality/lard/RwptDispersion.hpp b/src/engine/quality/lard/RwptDispersion.hpp
new file mode 100644
index 000000000..e2d0d3d66
--- /dev/null
+++ b/src/engine/quality/lard/RwptDispersion.hpp
@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file RwptDispersion.hpp
+ * @brief X3b: RWPT longitudinal dispersion on LARD segments.
+ *
+ * @details Subplan X3b (strategy §5, §2.5; §16 D-L4/D-L6). Longitudinal
+ *          dispersion emerges from resolved VERTICAL shear plus a vertical
+ *          random walk — the Taylor/Elder mechanism — rather than from a
+ *          fitted D_L coefficient (that deterministic alternative is the
+ *          ARD engine's E3 machinery; the user chose RWPT for LARD).
+ *
+ *          **D-X3b1 — particles carry no mass; they estimate the
+ *          inter-segment dispersive exchange.** Persistent per-particle
+ *          state is (ζ, η): ζ ∈ [0, V] the volume coordinate from the
+ *          link's FRONT (upstream) boundary — volume coordinates make the
+ *          substep's bulk advection an exact uniform shift (ζ += V_in) —
+ *          and η ∈ (0,1) the normalized depth, which holds the velocity
+ *          memory that shear dispersion correlates against position.
+ *          Each substep, after the segment field is final (post-RELEASE):
+ *
+ *            1. ζ += V_in (ride the water); particles pushed past V are
+ *               water that left — recycled as fresh entries near the
+ *               front with a fresh η (deterministic draw).
+ *            2. Shear + walk: ζ += (u(η) − ū)·dt·A ; η does a reflected
+ *               random walk with the Itô drift term dD_η/dη·dt (omitting
+ *               the drift piles particles into low-diffusivity zones —
+ *               the standard RWPT defect).
+ *            3. Every boundary crossing carries δm_s = C_s(ORIGIN
+ *               segment)·V/N of each species across — an upwind-carried
+ *               Monte-Carlo estimate of the dispersive flux. A uniform
+ *               field exchanges symmetrically and does not move (no
+ *               spurious drift); total mass is conserved EXACTLY by
+ *               construction (every debit has a matching credit).
+ *
+ *          Profiles (v1, wide-channel forms, documented deviations):
+ *          - Turbulent (Re ≥ 2000): log-law deviation
+ *            u(η) − ū = (u_star/κ)(1 + ln η), κ = 0.41; D_t = κ·u_star·h·η(1−η)
+ *            (Rouse parabola). u* = √(g·R_h·S_f), S_f from Manning at the
+ *            link's own n, R_h exact for CIRCULAR, ≈ h otherwise.
+ *            The emergent longitudinal coefficient's reference is
+ *            **Elder, D_L = 5.93·u*·h** — vertical-shear-only, exactly
+ *            what is resolved here.
+ *          - Laminar (Re < 2000): parabolic u(η) = 1.5·ū·η(2−η) deviation,
+ *            D_t = D_m (molecular, 1.25e-9 m²/s → 1.3454e-8 ft²/s).
+ *
+ *          **D-L6 counter RNG**: draws are a pure function of
+ *          (seed, link, global substep counter, particle, draw#) via a
+ *          splitmix64-style hash — bit-reproducible under any threading,
+ *          schedule, or run repetition; RWPT_SEED changes every draw.
+ *
+ *          NOT here (recorded): inter-LINK particle dispersion (ζ reflects
+ *          at both link ends; segment exchange stops at the boundary
+ *          node's CSTR, which already mixes), transverse-shear dispersion
+ *          (Fischer's field-scale term — a calibrated-D machinery, not a
+ *          resolved one), particle-count adaptivity, wall species.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_QUALITY_LARD_RWPT_DISPERSION_HPP
+#define OPENSWMM_QUALITY_LARD_RWPT_DISPERSION_HPP
+
+#include 
+#include 
+#include 
+#include 
+
+#include "../../core/SimulationContext.hpp"
+#include "SegmentStore.hpp"
+
+namespace openswmm {
+namespace lard {
+
+constexpr int    kRwptParticlesPerLink = 2000;
+constexpr double kKappa   = 0.41;        ///< von Kármán
+constexpr double kNuWater = 1.05e-5;     ///< kinematic viscosity, ft²/s
+constexpr double kDm      = 1.3454e-8;   ///< molecular diffusivity, ft²/s
+constexpr double kEtaMin  = 1.0e-3;      ///< log-law floor
+constexpr double kReTurb  = 2000.0;
+
+// ---------------------------------------------------------------------------
+// D-L6 counter-based RNG: pure function of the key, no state anywhere.
+// ---------------------------------------------------------------------------
+inline std::uint64_t rwpt_hash(std::uint64_t z) {
+    z += 0x9e3779b97f4a7c15ULL;
+    z = (z ^ (z >> 30)) * 0xbf58476d1ce4e5b9ULL;
+    z = (z ^ (z >> 27)) * 0x94d049bb133111ebULL;
+    return z ^ (z >> 31);
+}
+/// Uniform in (0,1), keyed. `draw` distinguishes multiple draws per particle.
+inline double rwpt_uniform(std::uint64_t seed, std::uint64_t link,
+                           std::uint64_t stepc, std::uint64_t particle,
+                           std::uint64_t draw) {
+    std::uint64_t k = rwpt_hash(seed ^ rwpt_hash(link));
+    k = rwpt_hash(k ^ rwpt_hash(stepc));
+    k = rwpt_hash(k ^ rwpt_hash(particle * 8ULL + draw));
+    // 53-bit mantissa, strictly inside (0,1).
+    return (static_cast(k >> 11) + 0.5) * (1.0 / 9007199254740992.0);
+}
+/// Standard normal (Box–Muller on two keyed uniforms).
+inline double rwpt_normal(std::uint64_t seed, std::uint64_t link,
+                          std::uint64_t stepc, std::uint64_t particle,
+                          std::uint64_t draw) {
+    const double u1 = rwpt_uniform(seed, link, stepc, particle, draw);
+    const double u2 = rwpt_uniform(seed, link, stepc, particle, draw + 1);
+    return std::sqrt(-2.0 * std::log(u1)) *
+           std::cos(6.283185307179586 * u2);
+}
+
+// ---------------------------------------------------------------------------
+// Profile kernels — exposed free functions so the unit gates can pin the
+// math without an engine run.
+// ---------------------------------------------------------------------------
+/// Velocity DEVIATION u(η) − ū. Turbulent: log-law; laminar: parabola.
+inline double rwpt_u_dev(double eta, double ubar, double ustar,
+                         bool turbulent) {
+    // The kEtaMin floor belongs to the LOG-LAW only (ln 0 = -inf); clamping
+    // the laminar parabola too biased its mean by ~1.5e-6*ubar — gate 4's
+    // mean-free quadrature caught it (X3b round).
+    if (turbulent)
+        return (ustar / kKappa) * (1.0 + std::log(std::max(eta, kEtaMin)));
+    return 1.5 * ubar * eta * (2.0 - eta) - ubar;  // parabola, mean-free
+}
+/// Vertical diffusivity in η-units (D_t/h²), and its η-gradient (the Itô
+/// drift). Turbulent: Rouse parabola κ·u*·h·η(1−η); laminar: molecular.
+inline double rwpt_d_eta(double eta, double h, double ustar, bool turbulent) {
+    if (!turbulent) return kDm / (h * h);
+    const double e = std::min(std::max(eta, 0.0), 1.0);
+    return kKappa * ustar * e * (1.0 - e) / h;  // (κ u* h η(1-η))/h²
+}
+inline double rwpt_d_eta_grad(double eta, double h, double ustar,
+                              bool turbulent) {
+    if (!turbulent) return 0.0;
+    return kKappa * ustar * (1.0 - 2.0 * eta) / h;
+}
+
+/// Hydraulic radius: exact for CIRCULAR from flow area, ≈ depth otherwise
+/// (wide-channel v1 approximation, recorded).
+inline double rwpt_hyd_radius(double area, double depth, double diam,
+                              bool circular) {
+    if (!circular || diam <= 0.0 || depth <= 0.0) return std::max(depth, 0.0);
+    const double ratio =
+        std::min(std::max(1.0 - 2.0 * depth / diam, -1.0), 1.0);
+    const double theta = 2.0 * std::acos(ratio);
+    if (theta <= 1.0e-6) return std::max(depth, 0.0);
+    const double a = diam * diam / 8.0 * (theta - std::sin(theta));
+    const double p = diam * theta / 2.0;
+    (void)area;
+    return (p > 0.0) ? a / p : std::max(depth, 0.0);
+}
+
+/**
+ * @brief Persistent particle field + the per-substep exchange operator.
+ */
+class RwptDispersion {
+public:
+    void resize(int n_links, int n_per_link = kRwptParticlesPerLink) {
+        nl_ = n_links;
+        npart_ = n_per_link;
+        const std::size_t total =
+            static_cast(nl_) * static_cast(npart_);
+        zeta_.assign(total, -1.0);  // <0 marks "not yet seeded"
+        eta_.assign(total, 0.5);
+        seg_idx_.assign(total, 0);
+    }
+
+    /**
+     * @brief One substep of dispersive exchange on link `l`'s segments.
+     *
+     * @param v_in     the volume that entered at the FRONT this substep
+     *                 (bulk-advection shift in volume coordinates).
+     * @param stepc    global substep counter (RNG key component).
+     * @param delta    scratch, ns entries — reused across calls.
+     */
+    void disperse(SimulationContext& ctx, SegmentStore& segs, int l,
+                  double ubar, double h, double rh, double n_manning,
+                  double v_in, double q_dt, double dt, std::uint64_t stepc,
+                  std::uint64_t seed, std::vector& delta) {
+        (void)ctx;
+        const int nseg = segs.count(l);
+        if (nseg < 2 || h <= 1.0e-3 || ubar <= 0.0) return;
+        const double vol = segs.total_volume(l);
+        if (vol <= 0.0) return;
+        const int ns = segs.species();
+
+        // Friction: Manning S_f at the link's own n → u*. Regime by Re.
+        const double sf = (n_manning * ubar) * (n_manning * ubar) /
+                          (2.208 * std::pow(std::max(rh, 1.0e-3), 4.0 / 3.0));
+        const double ustar =
+            std::sqrt(32.174 * std::max(rh, 1.0e-3) * sf);
+        const bool turbulent = (ubar * 4.0 * rh / kNuWater) >= kReTurb;
+
+        // Segment boundaries in volume coordinates, front → back.
+        bounds_.assign(static_cast(nseg) + 1, 0.0);
+        for (int j = 0; j < nseg; ++j)
+            bounds_[static_cast(j) + 1] =
+                bounds_[static_cast(j)] + segs.seg_volume(l, j);
+
+        const std::size_t base = static_cast(l) *
+                                 static_cast(npart_);
+        for (int p = 0; p < npart_; ++p) {
+            const std::size_t ip = base + static_cast(p);
+            double z = zeta_[ip];
+            double e = eta_[ip];
+
+            // Seed / recycle: unseeded particles spread evenly; particles
+            // that rode out the back are new water entering at the front.
+            if (z < 0.0) {
+                z = vol * (static_cast(p) + 0.5) /
+                    static_cast(npart_);
+                e = rwpt_uniform(seed, static_cast(l), stepc,
+                                 static_cast(p), 7);
+            } else {
+                z += v_in;  // ride the bulk advection (volume coordinates)
+                if (z >= vol) {
+                    z = std::min(v_in,
+                                 vol * rwpt_uniform(
+                                           seed, static_cast(l),
+                                           stepc,
+                                           static_cast(p), 8));
+                    e = rwpt_uniform(seed, static_cast(l),
+                                     stepc, static_cast(p), 9);
+                }
+            }
+
+            const int j_from = locate(z, nseg);
+
+            // Shear displacement in VOLUME units through the ratio form:
+            // dζ = u_dev·dt·A = (u_dev/ū)·(ū·A·dt) = (u_dev/ū)·(Q·dt) —
+            // exact and unit-safe; Q·dt is the substep's through-volume,
+            // supplied by the caller (NOT v_in, which differs from Q·dt
+            // whenever the link's volume is changing).
+            const double dz =
+                (rwpt_u_dev(e, ubar, ustar, turbulent) / ubar) * q_dt;
+
+            // Vertical walk with Itô drift, reflected into (0,1). The
+            // kernels already return η-units (D_t/h² and its η-gradient).
+            const double d_eta = rwpt_d_eta(e, h, ustar, turbulent);
+            const double drift = rwpt_d_eta_grad(e, h, ustar, turbulent);
+            e += drift * dt +
+                 rwpt_normal(seed, static_cast(l), stepc,
+                             static_cast(p), 3) *
+                     std::sqrt(std::max(2.0 * d_eta * dt, 0.0));
+            while (e < 0.0 || e > 1.0) {
+                if (e < 0.0) e = -e;
+                if (e > 1.0) e = 2.0 - e;
+            }
+
+            // Longitudinal reflection at the link ends (no inter-link
+            // particle transfer — recorded).
+            z += dz;
+            while (z < 0.0 || z > vol) {
+                if (z < 0.0) z = -z;
+                if (z > vol) z = 2.0 * vol - z;
+            }
+
+            const int j_to = locate(z, nseg);
+
+            // Upwind-carried exchange: each crossing moves the ORIGIN
+            // segment's concentration × (V/N) of water-equivalent mass,
+            // one boundary at a time so multi-segment jumps stay upwind.
+            if (j_to != j_from) {
+                const double vshare = vol / static_cast(npart_);
+                int j = j_from;
+                const int stepdir = (j_to > j_from) ? 1 : -1;
+                while (j != j_to) {
+                    const int jn = j + stepdir;
+                    // Quantum = upwind conc x the PENETRATION past this
+                    // boundary (capped at the particle's own water, V/N).
+                    // A fixed V/N quantum let random-walk RE-crossings each
+                    // move a full share while the limiter zeroed the
+                    // up-gradient legs -- a rectified pump measured at
+                    // ~10x Elder on the 6000 ft probe (X3b round). The
+                    // penetration scale restores flux ~ displacement, so
+                    // the exchange magnitude is dt-robust.
+                    const double bnd =
+                        bounds_[static_cast(std::max(j, jn))];
+                    const double pen = std::min(std::abs(z - bnd), vshare);
+                    for (int s = 0; s < ns; ++s)
+                        delta[static_cast(s)] =
+                            segs.seg_conc(l, j, s) * pen;
+                    exchange(segs, l, j, jn, delta.data(), ns);
+                    j = jn;
+                }
+            }
+
+            zeta_[ip] = z;
+            eta_[ip] = e;
+            seg_idx_[ip] = j_to;
+        }
+    }
+
+private:
+    /// D-L4's intent is "no per-particle binary search on the hot path";
+    /// segment counts are ≤ cap (≤ ~100) and this branch-light linear walk
+    /// is exact. The maintained-sort two-pointer refinement is an L6
+    /// perf-pass item, recorded.
+    int locate(double z, int nseg) const {
+        int j = 0;
+        while (j + 1 < nseg &&
+               z >= bounds_[static_cast(j) + 1])
+            ++j;
+        return j;
+    }
+
+    /// Move `delta` (ns masses) from segment j to jn, with the D-X3b1
+    /// equalizing limiter: an event may move the receiver TOWARD the donor
+    /// but never past it (`take ≤ (c_j − c_n)·v_n`), and never more than
+    /// the donor holds. Consequences, all deliberate: the maximum
+    /// principle holds by construction per event; a uniform field is a
+    /// strict no-op (zero spurious drift, exactly); mass conserves exactly
+    /// (every debit pairs with a credit).
+    void exchange(SegmentStore& segs, int l, int j, int jn,
+                  const double* delta, int ns) {
+        for (int s = 0; s < ns; ++s) {
+            const double vj = segs.seg_volume(l, j);
+            const double vn = segs.seg_volume(l, jn);
+            if (vj <= 0.0 || vn <= 0.0) continue;
+            const double cj = segs.seg_conc(l, j, s);
+            const double cn = segs.seg_conc(l, jn, s);
+            const double take =
+                std::min({delta[s], cj * vj,
+                          std::max(0.0, (cj - cn)) * vn});
+            if (take <= 0.0) continue;
+            segs.set_seg_conc(l, j, s, (cj * vj - take) / vj);
+            segs.set_seg_conc(l, jn, s, (cn * vn + take) / vn);
+        }
+    }
+
+    int nl_ = 0, npart_ = 0;
+    std::vector zeta_, eta_;
+    std::vector seg_idx_;
+    std::vector bounds_;
+};
+
+}  // namespace lard
+}  // namespace openswmm
+
+#endif  // OPENSWMM_QUALITY_LARD_RWPT_DISPERSION_HPP
diff --git a/src/engine/quality/lard/SegmentStore.hpp b/src/engine/quality/lard/SegmentStore.hpp
new file mode 100644
index 000000000..223d76110
--- /dev/null
+++ b/src/engine/quality/lard/SegmentStore.hpp
@@ -0,0 +1,288 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SegmentStore.hpp
+ * @brief LARD segment slabs — per-link ring buffers of plug-flow segments.
+ *
+ * @details Subplan X2 (`LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md`), layout per
+ *          the strategy's binding §16 amendments:
+ *
+ *          - **D-L2 slab layout**: link `l` owns physical slots
+ *            `[l*cap, (l+1)*cap)` with a per-link `head`/`count` ring —
+ *            prepend at the front (upstream), consume from the back
+ *            (downstream), no compaction, no mid-step reallocation.
+ *          - **D-L1 species-major**: `conc[s * slab_total + l*cap + slot]` —
+ *            one species is a contiguous stripe across every slab, which is
+ *            what vectorizes decay and (later) advection sweeps.
+ *          - **D-L5**: overflow merges the two front segments
+ *            (mass-conservative) instead of growing under the step.
+ *
+ *          Front (logical index 0) is the **current upstream** end; the ring
+ *          is reversed in place when the link's flow changes sign (§4.4).
+ *          All operations conserve mass exactly: a drain reports the mass it
+ *          removed, a push books the mass it added, and a merge is a
+ *          volume-weighted average.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_QUALITY_LARD_SEGMENT_STORE_HPP
+#define OPENSWMM_QUALITY_LARD_SEGMENT_STORE_HPP
+
+#include 
+#include 
+#include 
+
+namespace openswmm {
+namespace lard {
+
+/// EPANET-style cap on segments per link (strategy §4.1 default; the
+/// [OPTIONS] MAX_SEGMENTS_PER_LINK override arrives with X3).
+constexpr int kMaxSegmentsPerLink = 100;
+
+/// Merge tolerance for a released segment against the current front segment
+/// (strategy §4.5): merge when |dC| <= atol + rtol·|C_front| for EVERY
+/// species. Plug-flow stretches then collapse to one segment — the dominant
+/// constant-factor win in EPANET's LTD.
+constexpr double kMergeAtol = 1.0e-6;
+constexpr double kMergeRtol = 1.0e-4;
+
+class SegmentStore {
+public:
+    void resize(int n_links, int n_species, int cap = kMaxSegmentsPerLink) {
+        nl_ = n_links;
+        ns_ = n_species;
+        cap_ = cap;
+        const std::size_t slab =
+            static_cast(nl_) * static_cast(cap_);
+        head_.assign(static_cast(nl_), 0);
+        count_.assign(static_cast(nl_), 0);
+        vol_.assign(slab, 0.0);
+        conc_.assign(slab * static_cast(ns_ > 0 ? ns_ : 1), 0.0);
+    }
+
+    int  count(int l) const { return count_[static_cast(l)]; }
+    int  species() const { return ns_; }
+    int  capacity() const { return cap_; }
+
+    double total_volume(int l) const {
+        double v = 0.0;
+        for (int i = 0; i < count(l); ++i) v += vol_[phys(l, i)];
+        return v;
+    }
+
+    double seg_volume(int l, int i) const { return vol_[phys(l, i)]; }
+    double seg_conc(int l, int i, int s) const { return conc_[cidx(l, i, s)]; }
+    /// X3b: the RWPT exchange rewrites segment concentrations in place
+    /// (mass-conserving by its own construction — every debit pairs with a
+    /// credit; see RwptDispersion::exchange).
+    void set_seg_conc(int l, int i, int s, double c) {
+        conc_[cidx(l, i, s)] = c;
+    }
+
+    /// Volume-weighted mean concentration over the link's segments.
+    /// `out` has ns_ entries; an empty link reports 0.
+    void mean_conc(int l, double* out) const {
+        for (int s = 0; s < ns_; ++s) out[s] = 0.0;
+        double v = 0.0;
+        for (int i = 0; i < count(l); ++i) {
+            const double sv = vol_[phys(l, i)];
+            v += sv;
+            for (int s = 0; s < ns_; ++s) out[s] += sv * conc_[cidx(l, i, s)];
+        }
+        if (v > 0.0)
+            for (int s = 0; s < ns_; ++s) out[s] /= v;
+    }
+
+    /// Remove one whole link's contents (init/re-seed).
+    void clear_link(int l) {
+        head_[static_cast(l)] = 0;
+        count_[static_cast(l)] = 0;
+    }
+
+    /**
+     * @brief Drain up to `vol_target` from the BACK (downstream end).
+     *
+     * @param mass_out  ns_ entries, ACCUMULATED into (not reset) — the mass
+     *                  carried by the drained water.
+     * @return the volume actually drained (< target iff the link emptied).
+     */
+    double drain_back(int l, double vol_target, double* mass_out) {
+        double drained = 0.0;
+        while (vol_target - drained > 0.0 && count(l) > 0) {
+            const int i = count(l) - 1;  // back
+            const std::size_t p = phys(l, i);
+            const double take = std::min(vol_[p], vol_target - drained);
+            for (int s = 0; s < ns_; ++s)
+                mass_out[s] += take * conc_[cidx(l, i, s)];
+            vol_[p] -= take;
+            drained += take;
+            if (vol_[p] <= 0.0) count_[static_cast(l)] -= 1;
+        }
+        return drained;
+    }
+
+    /// Same as drain_back but from the FRONT (upstream end) — the volume-
+    /// reconciliation path for a link that shrank by more than its outflow.
+    double drain_front(int l, double vol_target, double* mass_out) {
+        double drained = 0.0;
+        while (vol_target - drained > 0.0 && count(l) > 0) {
+            const std::size_t p = phys(l, 0);
+            const double take = std::min(vol_[p], vol_target - drained);
+            for (int s = 0; s < ns_; ++s)
+                mass_out[s] += take * conc_[cidx(l, 0, s)];
+            vol_[p] -= take;
+            drained += take;
+            if (vol_[p] <= 0.0) {
+                head_[static_cast(l)] =
+                    (head_[static_cast(l)] + 1) % cap_;
+                count_[static_cast(l)] -= 1;
+            }
+        }
+        return drained;
+    }
+
+    /**
+     * @brief Release a new segment at the FRONT (upstream end).
+     *
+     * @details Merges into the existing front segment when every species is
+     *          within the §4.5 tolerance; on a full ring the two front
+     *          segments merge first (D-L5) so the push never reallocates.
+     */
+    void push_front(int l, double volume, const double* c) {
+        if (volume <= 0.0) return;
+        if (count(l) > 0 && mergeable(l, 0, c)) {
+            merge_into(l, 0, volume, c);
+            return;
+        }
+        if (count(l) >= cap_) {
+            // D-L5: merge front pair, mass-conservative, then push.
+            merge_front_pair(l);
+        }
+        head_[static_cast(l)] =
+            (head_[static_cast(l)] - 1 + cap_) % cap_;
+        count_[static_cast(l)] += 1;
+        const std::size_t p = phys(l, 0);
+        vol_[p] = volume;
+        for (int s = 0; s < ns_; ++s) conc_[cidx(l, 0, s)] = c[s];
+    }
+
+    /// §4.4 flow reversal: front becomes back, in place.
+    void reverse(int l) {
+        const int n = count(l);
+        for (int i = 0, j = n - 1; i < j; ++i, --j) {
+            std::swap(vol_[phys(l, i)], vol_[phys(l, j)]);
+            for (int s = 0; s < ns_; ++s)
+                std::swap(conc_[cidx(l, i, s)], conc_[cidx(l, j, s)]);
+        }
+    }
+
+    /**
+     * @brief Add a constant to one species on every LIVE segment.
+     *
+     * @details X4: the water-age row ages by exactly +dt per routing step in
+     *          every parcel (zero-order growth, water age plan §1). Only
+     *          live segments are touched — stale slot contents never age.
+     */
+    void add_species(int s, double delta) {
+        for (int l = 0; l < nl_; ++l)
+            for (int i = 0; i < count(l); ++i) conc_[cidx(l, i, s)] += delta;
+    }
+
+    /**
+     * @brief Exact-exponential decay on one species over every LIVE segment.
+     *
+     * @param factor  exp(-k·dt), applied multiplicatively.
+     * @return the total mass removed (for the reacted ledger row).
+     */
+    double decay_species(int s, double factor) {
+        double removed = 0.0;
+        for (int l = 0; l < nl_; ++l)
+            for (int i = 0; i < count(l); ++i) {
+                const std::size_t ci = cidx(l, i, s);
+                removed += vol_[phys(l, i)] * conc_[ci] * (1.0 - factor);
+                conc_[ci] *= factor;
+            }
+        return removed;
+    }
+
+private:
+    /// Logical index i (0 = front/upstream) → physical slot in the slab.
+    std::size_t phys(int l, int i) const {
+        const int slot = (head_[static_cast(l)] + i) % cap_;
+        return static_cast(l) * static_cast(cap_) +
+               static_cast(slot);
+    }
+    /// Species-major concentration index (D-L1).
+    std::size_t cidx(int l, int i, int s) const {
+        return static_cast(s) * static_cast(nl_) *
+                   static_cast(cap_) +
+               phys(l, i);
+    }
+
+    bool mergeable(int l, int i, const double* c) const {
+        for (int s = 0; s < ns_; ++s) {
+            const double cf = conc_[cidx(l, i, s)];
+            if (std::abs(c[s] - cf) > kMergeAtol + kMergeRtol * std::abs(cf))
+                return false;
+        }
+        return true;
+    }
+
+    void merge_into(int l, int i, double volume, const double* c) {
+        const std::size_t p = phys(l, i);
+        const double v0 = vol_[p];
+        const double vt = v0 + volume;
+        if (vt <= 0.0) return;
+        for (int s = 0; s < ns_; ++s) {
+            const std::size_t ci = cidx(l, i, s);
+            conc_[ci] = (conc_[ci] * v0 + c[s] * volume) / vt;
+        }
+        vol_[p] = vt;
+    }
+
+    void merge_front_pair(int l) {
+        if (count(l) < 2) return;
+        // Fold segment 1 into segment 0 (volume-weighted), drop slot 1 by
+        // moving the head forward over it after copying 0 into 1.
+        const std::size_t p0 = phys(l, 0);
+        const std::size_t p1 = phys(l, 1);
+        const double v0 = vol_[p0], v1 = vol_[p1], vt = v0 + v1;
+        if (vt > 0.0)
+            for (int s = 0; s < ns_; ++s) {
+                const std::size_t c0 = cidx(l, 0, s);
+                const std::size_t c1 = cidx(l, 1, s);
+                conc_[c1] = (conc_[c0] * v0 + conc_[c1] * v1) / vt;
+            }
+        vol_[p1] = vt;
+        head_[static_cast(l)] =
+            (head_[static_cast(l)] + 1) % cap_;
+        count_[static_cast(l)] -= 1;
+    }
+
+    int nl_ = 0, ns_ = 0, cap_ = kMaxSegmentsPerLink;
+    std::vector head_, count_;
+    std::vector vol_;
+    std::vector conc_;  ///< species-major (D-L1)
+};
+
+}  // namespace lard
+}  // namespace openswmm
+
+#endif  // OPENSWMM_QUALITY_LARD_SEGMENT_STORE_HPP
diff --git a/src/engine/transport/InitialQualitySeeds.hpp b/src/engine/transport/InitialQualitySeeds.hpp
new file mode 100644
index 000000000..8e86beea5
--- /dev/null
+++ b/src/engine/transport/InitialQualitySeeds.hpp
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file InitialQualitySeeds.hpp
+ * @brief [INITIAL_QUALITY] reserved-species (__WATER_AGE__/__TEMPERATURE__)
+ *        helpers for the per-engine seed sites (E-A3).
+ *
+ * @details Precedence (D-IQ7): hotstart > [INITIAL_QUALITY] per-element >
+ *          sidecar INITIAL_STATE GLOBAL. The age appliers no-op when a
+ *          hotstart state is loaded so no call site can get the order wrong.
+ *          The age/heat state arrays are wiped by resize() at engine-specific
+ *          moments, so callers apply these AT their seed site rather than
+ *          relying on a write surviving a later resize (D-IQ8).
+ *
+ *          Units: [INITIAL_QUALITY] __WATER_AGE__ rows are HOURS in the file
+ *          (the [WATER_AGE_SOURCES] convention) and SECONDS internally;
+ *          __TEMPERATURE__ rows are degC both places.
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_INITIAL_QUALITY_SEEDS_HPP
+#define OPENSWMM_ENGINE_INITIAL_QUALITY_SEEDS_HPP
+
+#include "../core/SimulationContext.hpp"
+#include "../data/InitialQualityData.hpp"
+
+namespace openswmm::transport {
+
+/**
+ * @brief Per-element initial age (SECONDS) for one node/link, falling back
+ *        to @p fallback (normally the INITIAL_STATE global) when no
+ *        [INITIAL_QUALITY] row targets the element. Later rows win.
+ */
+inline double initialAgeSecondsFor(const SimulationContext& ctx, bool is_link,
+                                   int idx, double fallback) {
+    double v = fallback;
+    const auto& iq = ctx.initial_quality;
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if (iq.kind[ur] != InitialQualityData::kKindWaterAge) continue;
+        if ((iq.is_link[ur] != 0) != is_link) continue;
+        if (iq.elem_idx[ur] != idx) continue;
+        v = iq.value[ur] * 3600.0;   // hours -> seconds
+    }
+    return v;
+}
+
+/**
+ * @brief Per-element initial temperature (degC) for one node/link, falling
+ *        back to @p fallback (normally the INITIAL_STATE global).
+ */
+inline double initialTempFor(const SimulationContext& ctx, bool is_link,
+                             int idx, double fallback) {
+    double v = fallback;
+    const auto& iq = ctx.initial_quality;
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if (iq.kind[ur] != InitialQualityData::kKindTemperature) continue;
+        if ((iq.is_link[ur] != 0) != is_link) continue;
+        if (iq.elem_idx[ur] != idx) continue;
+        v = iq.value[ur];
+    }
+    return v;
+}
+
+/**
+ * @brief Apply __WATER_AGE__ rows onto water_age_state.node_age/link_age
+ *        (hours -> seconds). No-op when a hotstart state is loaded (D-IQ7)
+ *        or the arrays are unsized.
+ */
+inline void applyInitialAgeOverrides(SimulationContext& ctx) {
+    auto& ws = ctx.water_age_state;
+    if (ws.hotstart_loaded) return;
+    const auto& iq = ctx.initial_quality;
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if (iq.kind[ur] != InitialQualityData::kKindWaterAge) continue;
+        const int ei = iq.elem_idx[ur];
+        if (ei < 0) continue;
+        auto& arr = iq.is_link[ur] ? ws.link_age : ws.node_age;
+        if (static_cast(ei) < arr.size())
+            arr[static_cast(ei)] = iq.value[ur] * 3600.0;
+    }
+}
+
+/**
+ * @brief Apply __TEMPERATURE__ rows onto heat_state.node_temp/link_temp
+ *        (degC). No-op on unsized arrays.
+ */
+inline void applyInitialTempOverrides(SimulationContext& ctx) {
+    auto& hs = ctx.heat_state;
+    const auto& iq = ctx.initial_quality;
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if (iq.kind[ur] != InitialQualityData::kKindTemperature) continue;
+        const int ei = iq.elem_idx[ur];
+        if (ei < 0) continue;
+        auto& arr = iq.is_link[ur] ? hs.link_temp : hs.node_temp;
+        if (static_cast(ei) < arr.size())
+            arr[static_cast(ei)] = iq.value[ur];
+    }
+}
+
+} // namespace openswmm::transport
+
+#endif // OPENSWMM_ENGINE_INITIAL_QUALITY_SEEDS_HPP
diff --git a/src/engine/transport/MsxInitialQuality.cpp b/src/engine/transport/MsxInitialQuality.cpp
new file mode 100644
index 000000000..00a7a8db2
--- /dev/null
+++ b/src/engine/transport/MsxInitialQuality.cpp
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxInitialQuality.cpp
+ * @brief U2 — [INITIAL_QUALITY] MSX rows mirrored into ReactionData (see header).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "MsxInitialQuality.hpp"
+
+#include "../core/SimulationContext.hpp"
+#include "../data/InitialQualityData.hpp"
+
+namespace openswmm::transport {
+
+bool initialQualityHasMsxRow(const SimulationContext& ctx, bool is_link,
+                             int elem_idx, int species) {
+    const auto& iq = ctx.initial_quality;
+    const int want = InitialQualityData::msxKind(species);
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        if ((iq.is_link[ur] != 0) == is_link && iq.elem_idx[ur] == elem_idx &&
+            iq.kind[ur] == want)
+            return true;
+    }
+    return false;
+}
+
+std::vector mirrorInitialQualityMsxRows(SimulationContext& ctx) {
+    std::vector errs;
+    auto& rx = ctx.reactions;
+    const auto& iq = ctx.initial_quality;
+    if (!rx.configured) return errs;
+
+    for (int r = 0; r < iq.count(); ++r) {
+        const auto ur = static_cast(r);
+        const int m = InitialQualityData::msxSpecies(iq.kind[ur]);
+        if (m < 0 || m >= rx.n_species()) continue;
+        const int  ei   = iq.elem_idx[ur];
+        const bool link = iq.is_link[ur] != 0;
+        if (ei < 0) continue;
+
+        bool found = false;
+        for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+            if ((rx.init_elem_is_link[k] != 0) == link &&
+                rx.init_elem_idx[k] == ei && rx.init_elem_species[k] == m) {
+                if (rx.init_elem_value[k] != iq.value[ur]) {
+                    // A different value from the .rxn's [REACTION_QUALITY]
+                    // NODE|LINK row: the same ambiguity [INITIAL_QUALITY]
+                    // refuses for its own duplicates.
+                    errs.push_back(
+                        "[INITIAL_QUALITY] '" + iq.constituent[ur] + "' at " +
+                        (link ? "link '" : "node '") + iq.elem_name[ur] +
+                        "' conflicts with a [REACTION_QUALITY] " +
+                        (link ? "LINK" : "NODE") +
+                        " row in the reactions config — keep one.");
+                }
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            rx.init_elem_is_link.push_back(link ? 1 : 0);
+            rx.init_elem_idx.push_back(ei);
+            rx.init_elem_species.push_back(m);
+            rx.init_elem_value.push_back(iq.value[ur]);
+        }
+    }
+    return errs;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/MsxInitialQuality.hpp b/src/engine/transport/MsxInitialQuality.hpp
new file mode 100644
index 000000000..fbe756613
--- /dev/null
+++ b/src/engine/transport/MsxInitialQuality.hpp
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxInitialQuality.hpp
+ * @brief U2 (2026-09-07) — [INITIAL_QUALITY] rows for MSX species.
+ *
+ * @details `[INITIAL_QUALITY]` is the canonical home of a per-element initial
+ *          value for ANY constituent — pollutant, reactions-component species,
+ *          age, temperature. The reactions engines (LEGACY binding, ARD,
+ *          LARD) seed MSX species from `ReactionData::init_elem_*`, the
+ *          table `[REACTION_QUALITY] NODE|LINK` fills. This helper mirrors
+ *          the MSX-kind rows of `ctx.initial_quality` into that table so
+ *          every engine sees them without a fourth seed site:
+ *
+ *          - called from PostParseResolver after the rows are classified,
+ *          - called again by the reactions component whenever it re-parses
+ *            its `[REACTION_QUALITY]` block (the block reset clears the
+ *            table; the mirrored rows must come back).
+ *
+ *          A row the .rxn also carries (same element, same species) is an
+ *          error — the same duplicate policy `[INITIAL_QUALITY]` applies to
+ *          itself. The ReactionsWriter skips mirrored rows so a save emits
+ *          each row once, in `[INITIAL_QUALITY]`.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_MSX_INITIAL_QUALITY_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_MSX_INITIAL_QUALITY_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Mirror every MSX-kind `[INITIAL_QUALITY]` row into
+/// `ctx.reactions.init_elem_*` (upsert; a conflicting .rxn row is reported).
+/// Returns the diagnostics (empty on success).
+std::vector mirrorInitialQualityMsxRows(SimulationContext& ctx);
+
+/// True when `ctx.initial_quality` carries an MSX row for (is_link, elem,
+/// species) — the ReactionsWriter's "already written elsewhere" test.
+bool initialQualityHasMsxRow(const SimulationContext& ctx, bool is_link,
+                             int elem_idx, int species);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_MSX_INITIAL_QUALITY_HPP
diff --git a/src/engine/transport/TransportPolicy.cpp b/src/engine/transport/TransportPolicy.cpp
new file mode 100644
index 000000000..5c349dab0
--- /dev/null
+++ b/src/engine/transport/TransportPolicy.cpp
@@ -0,0 +1,379 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file TransportPolicy.cpp
+ * @brief Domain × Species-class transport contract (see the header).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "TransportPolicy.hpp"
+
+#include "../core/SimulationContext.hpp"
+#include "../2d/data/MeshData.hpp"
+#include "../2d/data/SolverOptions2D.hpp"
+#include "../2d/gw/GwTransportData.hpp"          // T7.1
+#include "../2d/subsurface/SubsurfaceData.hpp"   // T7.1
+
+#include 
+
+namespace openswmm::transport {
+
+namespace {
+
+bool reactionsActive(const SimulationContext& ctx) noexcept {
+    return ctx.reactions.configured && ctx.reactions.compiled;
+}
+
+bool reactionsHaveWall(const SimulationContext& ctx) noexcept {
+    for (const auto w : ctx.reactions.species_is_wall)
+        if (w != 0) return true;
+    return false;
+}
+
+bool hasMesh2D(const SimulationContext& ctx) noexcept {
+    return ctx.twod_io.mesh && ctx.twod_io.mesh->n_cells() > 0;
+}
+
+const twoD::SolverOptions2D* opts2D(const SimulationContext& ctx) noexcept {
+    return ctx.twod_io.options;
+}
+
+void enabled(Cell& c, int count) {
+    c.state = CellState::ENABLED;
+    c.count = count;
+    c.reason.clear();
+}
+void disabled(Cell& c, const char* key) {
+    c.state = CellState::DISABLED_BY_USER;
+    c.count = 0;
+    c.reason = key;
+}
+void unavailable(Cell& c, const char* why) {
+    c.state = CellState::UNAVAILABLE;
+    c.count = 0;
+    c.reason = why;
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// Enables (allocation-free)
+// ---------------------------------------------------------------------------
+
+ClassEnables network1DEnables(const SimulationContext& ctx) noexcept {
+    ClassEnables e;
+    const bool q = !ctx.options.ignore_quality;
+    e.n_pollut     = q ? ctx.n_pollutants() : 0;
+    e.msx_has_wall = reactionsHaveWall(ctx);
+    e.n_msx        = (q && reactionsActive(ctx)) ? ctx.reactions.n_species() : 0;
+    e.age          = q && ctx.options.water_age;
+    e.temperature  = q && ctx.options.heat_transport;
+    return e;
+}
+
+ClassEnables surface2DEnables(const SimulationContext& ctx) noexcept {
+    ClassEnables e;
+    const auto* o = opts2D(ctx);
+    const bool q = !ctx.options.ignore_quality;
+    const bool tp = !o || o->transport_pollutants;
+    const bool tm = !o || o->transport_msx;
+    const bool ta = !o || o->transport_age;
+    const bool tt = !o || o->transport_temperature;
+    e.n_pollut     = (q && tp) ? ctx.n_pollutants() : 0;
+    e.msx_has_wall = reactionsHaveWall(ctx);
+    // WALL species have no surface transport semantics: the 2D row block
+    // refuses them (with its warning) exactly as before E2.
+    e.n_msx        = (q && tm && reactionsActive(ctx) && !e.msx_has_wall)
+                         ? ctx.reactions.n_species() : 0;
+    e.age          = ta && ctx.options.water_age;
+    e.temperature  = tt && ctx.options.heat_transport;
+    return e;
+}
+
+ClassEnables groundwaterEnables(const SimulationContext& ctx) noexcept {
+    ClassEnables e;
+    // The kernel is the gate: no resolved [2D_AQUIFER], no subsurface
+    // transport, whatever the [GW_*] rows say.
+    const auto* aq = ctx.twod_io.aquifer_state;
+    if (aq == nullptr || !aq->active || aq->n_cells <= 0) return e;
+    const auto* g = ctx.twod_io.gw;
+    const bool q  = !ctx.options.ignore_quality;
+    const bool tp = !g || g->options.transport_pollutants;
+    const bool tm = !g || g->options.transport_msx;
+    const bool ta = !g || g->options.transport_age;
+    const bool tt = !g || g->options.transport_temperature;
+    e.n_pollut     = (q && tp) ? ctx.n_pollutants() : 0;
+    e.msx_has_wall = reactionsHaveWall(ctx);
+    // WALL species are a pipe-surface concept; the aquifer refuses them for
+    // the same reason the 2D surface does.
+    e.n_msx        = (q && tm && reactionsActive(ctx) && !e.msx_has_wall)
+                         ? ctx.reactions.n_species() : 0;
+    e.age          = ta && ctx.options.water_age;
+    e.temperature  = tt && ctx.options.heat_transport;
+    return e;
+}
+
+RowLayout canonicalRows(const SimulationContext& ctx, const ClassEnables& e) {
+    RowLayout L;
+    L.n_pollut = e.n_pollut;
+    L.n_msx    = e.n_msx;
+    L.age_row  = e.age ? L.n_pollut + L.n_msx : -1;
+    L.temp_row = e.temperature ? L.n_pollut + L.n_msx + (e.age ? 1 : 0) : -1;
+    L.ns       = e.total();
+    L.names.reserve(static_cast(L.ns));
+    for (int p = 0; p < L.n_pollut; ++p) L.names.push_back(ctx.pollutant_names.name_of(p));
+    for (int m = 0; m < L.n_msx; ++m)
+        L.names.push_back(ctx.reactions.species_name[static_cast(m)]);
+    if (e.age)         L.names.push_back("__WATER_AGE__");
+    if (e.temperature) L.names.push_back("__TEMPERATURE__");
+    return L;
+}
+
+// ---------------------------------------------------------------------------
+// The matrix
+// ---------------------------------------------------------------------------
+
+Matrix resolve(const SimulationContext& ctx) {
+    Matrix m;
+    const int  np       = ctx.n_pollutants();
+    const bool ignoreQ  = ctx.options.ignore_quality;
+    const bool msxOn    = reactionsActive(ctx);
+    const int  nm       = msxOn ? ctx.reactions.n_species() : 0;
+    const bool msxWall  = msxOn && reactionsHaveWall(ctx);
+    const bool ageOn    = ctx.options.water_age;
+    const bool heatOn   = ctx.options.heat_transport;
+
+    // ---- Runoff / LID ------------------------------------------------------
+    {
+        const bool has_sub = ctx.n_subcatches() > 0;
+        Cell& pol = m.at(Domain::RUNOFF, SpeciesClass::POLLUTANTS);
+        if (!has_sub)      unavailable(pol, "no subcatchments");
+        else if (np == 0)  unavailable(pol, "no [POLLUTANTS]");
+        else if (ignoreQ)  disabled(pol, "IGNORE_QUALITY");
+        else               enabled(pol, np);
+
+        unavailable(m.at(Domain::RUNOFF, SpeciesClass::MSX),
+                    msxOn ? "runoff and LID have no reactions binding"
+                          : "no reactions component");
+
+        Cell& age = m.at(Domain::RUNOFF, SpeciesClass::AGE);
+        if (!has_sub)      unavailable(age, "no subcatchments");
+        else if (!ageOn)   unavailable(age, "WATER_AGE OFF");
+        else if (ignoreQ)  disabled(age, "IGNORE_QUALITY");
+        else               enabled(age, 1);
+
+        Cell& tmp = m.at(Domain::RUNOFF, SpeciesClass::TEMPERATURE);
+        if (!has_sub)      unavailable(tmp, "no subcatchments");
+        else if (!heatOn)  unavailable(tmp, "HEAT_TRANSPORT OFF");
+        else if (ignoreQ)  disabled(tmp, "IGNORE_QUALITY");
+        else               enabled(tmp, 1);
+    }
+
+    // ---- Groundwater --------------------------------------------------------
+    // T7.1: the two-zone [2D_AQUIFER] kernel transports. A deck with only the
+    // legacy subcatchment [AQUIFERS] keeps the old row verbatim — that
+    // aquifer still has no transported quality of its own.
+    {
+        const auto* aq = ctx.twod_io.aquifer_state;
+        const bool two_zone = aq != nullptr && aq->active && aq->n_cells > 0;
+        if (two_zone) {
+            const ClassEnables e = groundwaterEnables(ctx);
+            const auto* g = ctx.twod_io.gw;
+            Cell& pol = m.at(Domain::GROUNDWATER, SpeciesClass::POLLUTANTS);
+            if (np == 0)                                    unavailable(pol, "no [POLLUTANTS]");
+            else if (ignoreQ)                               disabled(pol, "IGNORE_QUALITY");
+            else if (g && !g->options.transport_pollutants) disabled(pol, "TRANSPORT_POLLUTANTS NO");
+            else                                            enabled(pol, e.n_pollut);
+
+            Cell& msx = m.at(Domain::GROUNDWATER, SpeciesClass::MSX);
+            if (!reactionsActive(ctx))                unavailable(msx, "no reactions component");
+            else if (e.msx_has_wall)                  unavailable(msx, "WALL species have no subsurface transport");
+            else if (ignoreQ)                         disabled(msx, "IGNORE_QUALITY");
+            else if (g && !g->options.transport_msx)  disabled(msx, "TRANSPORT_MSX NO");
+            else                                      enabled(msx, e.n_msx);
+
+            Cell& age = m.at(Domain::GROUNDWATER, SpeciesClass::AGE);
+            if (!ctx.options.water_age)               unavailable(age, "WATER_AGE OFF");
+            else if (g && !g->options.transport_age)  disabled(age, "TRANSPORT_AGE NO");
+            else                                      enabled(age, 1);
+
+            Cell& tmp = m.at(Domain::GROUNDWATER, SpeciesClass::TEMPERATURE);
+            if (!ctx.options.heat_transport)                  unavailable(tmp, "HEAT_TRANSPORT OFF");
+            else if (g && !g->options.transport_temperature)  disabled(tmp, "TRANSPORT_TEMPERATURE NO");
+            else                                              enabled(tmp, 1);
+        } else {
+            const bool has_aq = ctx.aquifer_names.size() > 0;
+            const char* no_aq = "no [AQUIFERS] or [2D_AQUIFER]";
+            unavailable(m.at(Domain::GROUNDWATER, SpeciesClass::POLLUTANTS),
+                        has_aq ? "no transported quality — the aquifer supplies the "
+                                 "[POLLUTANTS] GW concentration at the node seam (legacy)"
+                               : no_aq);
+            unavailable(m.at(Domain::GROUNDWATER, SpeciesClass::MSX),
+                        has_aq ? "no transported quality in groundwater" : no_aq);
+            unavailable(m.at(Domain::GROUNDWATER, SpeciesClass::AGE),
+                        has_aq ? "source volume only (new water enters at age 0)" : no_aq);
+            unavailable(m.at(Domain::GROUNDWATER, SpeciesClass::TEMPERATURE),
+                        has_aq ? "source volume only (GROUNDWATER source temperature)" : no_aq);
+        }
+    }
+
+    // ---- 1D network --------------------------------------------------------
+    {
+        Cell& pol = m.at(Domain::NETWORK_1D, SpeciesClass::POLLUTANTS);
+        if (np == 0)       unavailable(pol, "no [POLLUTANTS]");
+        else if (ignoreQ)  disabled(pol, "IGNORE_QUALITY");
+        else               enabled(pol, np);
+
+        Cell& msx = m.at(Domain::NETWORK_1D, SpeciesClass::MSX);
+        if (!msxOn)        unavailable(msx, "no reactions component");
+        else if (ignoreQ)  disabled(msx, "IGNORE_QUALITY");
+        else               enabled(msx, nm);
+        if (msx.state == CellState::ENABLED && msxWall &&
+            ctx.options.quality_solver == QualitySolverKind::EULERIAN_ARD)
+            msx.reason = "WALL species: EULERIAN_ARD falls back to LEGACY";
+
+        Cell& age = m.at(Domain::NETWORK_1D, SpeciesClass::AGE);
+        if (!ageOn)        unavailable(age, "WATER_AGE OFF");
+        else if (ignoreQ)  disabled(age, "IGNORE_QUALITY");
+        else               enabled(age, 1);
+
+        Cell& tmp = m.at(Domain::NETWORK_1D, SpeciesClass::TEMPERATURE);
+        if (!heatOn)       unavailable(tmp, "HEAT_TRANSPORT OFF");
+        else if (ignoreQ)  disabled(tmp, "IGNORE_QUALITY");
+        else               enabled(tmp, 1);
+    }
+
+    // ---- 2D surface --------------------------------------------------------
+    {
+        const bool mesh = hasMesh2D(ctx);
+        const auto* o   = opts2D(ctx);
+        const bool ig2d = ctx.options.ignore_2d;
+        auto gate = [&](Cell& c, bool project_on, const char* off_why,
+                        bool key_on, const char* key, bool quality_gated,
+                        int count, const char* unavailable_why = nullptr) {
+            if (!mesh)                     { unavailable(c, "no 2D mesh"); return; }
+            if (!project_on)               { unavailable(c, off_why); return; }
+            if (ig2d)                      { disabled(c, "IGNORE_2D"); return; }
+            if (quality_gated && ignoreQ)  { disabled(c, "IGNORE_QUALITY"); return; }
+            if (unavailable_why)           { unavailable(c, unavailable_why); return; }
+            if (!key_on)                   { disabled(c, key); return; }
+            enabled(c, count);
+        };
+        gate(m.at(Domain::SURFACE_2D, SpeciesClass::POLLUTANTS),
+             np > 0, "no [POLLUTANTS]",
+             !o || o->transport_pollutants, "TRANSPORT_POLLUTANTS", true, np);
+        gate(m.at(Domain::SURFACE_2D, SpeciesClass::MSX),
+             msxOn, "no reactions component",
+             !o || o->transport_msx, "TRANSPORT_MSX", true, nm,
+             msxWall ? "WALL species have no surface transport semantics" : nullptr);
+        gate(m.at(Domain::SURFACE_2D, SpeciesClass::AGE),
+             ageOn, "WATER_AGE OFF",
+             !o || o->transport_age, "TRANSPORT_AGE", false, 1);
+        gate(m.at(Domain::SURFACE_2D, SpeciesClass::TEMPERATURE),
+             heatOn, "HEAT_TRANSPORT OFF",
+             !o || o->transport_temperature, "TRANSPORT_TEMPERATURE", false, 1);
+    }
+
+    return m;
+}
+
+// ---------------------------------------------------------------------------
+// Names and the report block
+// ---------------------------------------------------------------------------
+
+const char* domainName(Domain d) noexcept {
+    switch (d) {
+        case Domain::RUNOFF:      return "Runoff / LID";
+        case Domain::GROUNDWATER: return "Groundwater";
+        case Domain::NETWORK_1D:  return "1D network";
+        case Domain::SURFACE_2D:  return "2D surface";
+        default:                  return "?";
+    }
+}
+
+const char* speciesClassName(SpeciesClass c) noexcept {
+    switch (c) {
+        case SpeciesClass::POLLUTANTS:  return "Pollutants";
+        case SpeciesClass::MSX:         return "MSX";
+        case SpeciesClass::AGE:         return "Age";
+        case SpeciesClass::TEMPERATURE: return "Temperature";
+        default:                        return "?";
+    }
+}
+
+const char* cellStateName(CellState s) noexcept {
+    switch (s) {
+        case CellState::ENABLED:          return "ENABLED";
+        case CellState::DISABLED_BY_USER: return "DISABLED_BY_USER";
+        case CellState::UNAVAILABLE:      return "UNAVAILABLE";
+        default:                          return "?";
+    }
+}
+
+std::string formatReportBlock(const Matrix& m) {
+    std::string out;
+    out += "  Transport by domain (Domain x Species; on(n) = rows carried,\n";
+    out += "  off:KEY = switched off by that option, n/a = not carried):\n";
+    char buf[256];
+    std::snprintf(buf, sizeof(buf), "  %-14s %-14s %-14s %-14s %-14s\n",
+                  "", "Pollutants", "MSX", "Age", "Temperature");
+    out += buf;
+    for (int d = 0; d < static_cast(Domain::COUNT); ++d) {
+        std::string line = "  ";
+        std::snprintf(buf, sizeof(buf), "%-14s ", domainName(static_cast(d)));
+        line += buf;
+        for (int c = 0; c < static_cast(SpeciesClass::COUNT); ++c) {
+            const Cell& cell = m.cells[d][c];
+            std::string tok;
+            switch (cell.state) {
+                case CellState::ENABLED:
+                    tok = "on(" + std::to_string(cell.count) + ")";
+                    break;
+                case CellState::DISABLED_BY_USER:
+                    tok = "off:" + cell.reason;
+                    break;
+                default:
+                    tok = "n/a";
+                    break;
+            }
+            std::snprintf(buf, sizeof(buf), "%-14s ", tok.c_str());
+            line += buf;
+        }
+        out += line;
+        out += '\n';
+    }
+    // The n/a explanations, once each, so the table stays narrow.
+    bool any = false;
+    for (int d = 0; d < static_cast(Domain::COUNT); ++d) {
+        for (int c = 0; c < static_cast(SpeciesClass::COUNT); ++c) {
+            const Cell& cell = m.cells[d][c];
+            if (cell.state != CellState::UNAVAILABLE || cell.reason.empty()) continue;
+            if (!any) { out += "  n/a because:\n"; any = true; }
+            std::snprintf(buf, sizeof(buf), "    %-14s %-12s %s\n",
+                          domainName(static_cast(d)),
+                          speciesClassName(static_cast(c)),
+                          cell.reason.c_str());
+            out += buf;
+        }
+    }
+    return out;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/TransportPolicy.hpp b/src/engine/transport/TransportPolicy.hpp
new file mode 100644
index 000000000..2c5c5b81e
--- /dev/null
+++ b/src/engine/transport/TransportPolicy.hpp
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file TransportPolicy.hpp
+ * @brief The Domain × Species-class transport contract (OPT plan §5, E2).
+ *
+ * @details One function decides which species classes run in which domain
+ *          and why. Before E2 the answer was re-derived in three places —
+ *          `ArdEngine::init`, the LARD `rowLayout()` and the 2D
+ *          `SurfaceRouter2D::initialize` row block — and no surface (API or
+ *          report) could explain "why is there no 2D quality". Now:
+ *
+ *          - `network1DEnables()` / `surface2DEnables()` are the allocation-
+ *            free class enables the engines size from (LARD calls its layout
+ *            per step, so this path must stay cheap).
+ *          - `resolve()` builds the full matrix with states and reasons for
+ *            the C API (`swmm_get_transport_matrix`), the `.rpt` header and
+ *            the GUI hub.
+ *
+ *          Row ORDER stays where it is: ARD and 2D carry pollutants, MSX,
+ *          age, temperature (the SpeciesRegistry order); LARD keeps its
+ *          pollutants, age, temperature, MSX order for the bit-inertness
+ *          argument recorded on `SpeciesRowLayout`. E2 unifies the ENABLE
+ *          decision, not the index arithmetic — flipping LARD's order is a
+ *          separate, corpus-gated change.
+ *
+ *          Policy (OPT plan §5.1): inherit-on. A class enabled at project
+ *          level runs in every domain whose solver carries it; per-domain
+ *          opt-outs exist only where a key does (2D: `TRANSPORT_*`; 1D:
+ *          `IGNORE_QUALITY`; runoff/GW/LID have none). Groundwater has no
+ *          transported quality (legacy parity) and reports UNAVAILABLE with
+ *          the seam-column explanation rather than staying silent.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_POLICY_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_POLICY_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Rows of the matrix. Values are the C API's SWMM_TRANSPORT_DOMAIN_* codes.
+enum class Domain : int {
+    RUNOFF      = 0,  ///< subcatchment runoff + LID
+    GROUNDWATER = 1,  ///< legacy per-subcatchment aquifers
+    NETWORK_1D  = 2,  ///< LEGACY / EULERIAN_ARD / LAGRANGIAN routing
+    SURFACE_2D  = 3,  ///< the 2D mesh
+    COUNT       = 4
+};
+
+/// Columns of the matrix. Values are the C API's SWMM_TRANSPORT_CLASS_* codes.
+enum class SpeciesClass : int {
+    POLLUTANTS  = 0,  ///< [POLLUTANTS]
+    MSX         = 1,  ///< reactions component species
+    AGE         = 2,  ///< __WATER_AGE__
+    TEMPERATURE = 3,  ///< __TEMPERATURE__
+    COUNT       = 4
+};
+
+/// One cell's state. Values are the C API's SWMM_TRANSPORT_* state codes.
+enum class CellState : int {
+    ENABLED          = 0,  ///< rows are carried in this domain
+    DISABLED_BY_USER = 1,  ///< a key turned it off — `reason` names the key
+    UNAVAILABLE      = 2   ///< nothing to carry, or the solver lacks it — `reason` says which
+};
+
+struct Cell {
+    CellState   state  = CellState::UNAVAILABLE;
+    int         count  = 0;      ///< rows of this class carried (0 unless ENABLED)
+    std::string reason;          ///< key (DISABLED_BY_USER) or explanation (UNAVAILABLE); empty when ENABLED
+};
+
+/**
+ * @brief Allocation-free class enables for one domain — what the engines
+ *        size from. `n_msx` is the reactions component's species count when
+ *        MSX is on for the domain; `msx_has_wall` tells ARD / 2D that the
+ *        component declares WALL species (their own fallback / warning).
+ */
+struct ClassEnables {
+    int  n_pollut     = 0;
+    int  n_msx        = 0;
+    bool age          = false;
+    bool temperature  = false;
+    bool msx_has_wall = false;
+    int  total() const noexcept { return n_pollut + n_msx + (age ? 1 : 0) + (temperature ? 1 : 0); }
+};
+
+/// 1D network enables: LEGACY / ARD / LARD all size from this.
+ClassEnables network1DEnables(const SimulationContext& ctx) noexcept;
+
+/// 2D surface enables: the 1D rule plus the [2D_OPTIONS] TRANSPORT_* keys.
+/// Age and temperature are NOT gated by IGNORE_QUALITY here (pre-E2 rule:
+/// "IGNORE_QUALITY turns off the pollutant and MSX rows only").
+ClassEnables surface2DEnables(const SimulationContext& ctx) noexcept;
+
+/// T7.1: two-zone groundwater enables — the 2D surface rule plus the
+/// `[GW_TRANSPORT_OPTIONS] TRANSPORT_*` keys. Like the surface, age and
+/// temperature are not gated by IGNORE_QUALITY. Every row is 0 unless a
+/// `[2D_AQUIFER]` actually resolved: the sections are authorable on a deck
+/// with no kernel, and they transport nothing there.
+ClassEnables groundwaterEnables(const SimulationContext& ctx) noexcept;
+
+/// The canonical row layout (pollutants, MSX, age, temperature) for a set of
+/// enables — the SpeciesRegistry order ARD and 2D use.
+struct RowLayout {
+    int n_pollut = 0;
+    int n_msx    = 0;
+    int age_row  = -1;
+    int temp_row = -1;
+    int ns       = 0;
+    std::vector names;   ///< one per row
+};
+RowLayout canonicalRows(const SimulationContext& ctx, const ClassEnables& e);
+
+struct Matrix {
+    Cell cells[static_cast(Domain::COUNT)][static_cast(SpeciesClass::COUNT)];
+    const Cell& at(Domain d, SpeciesClass c) const noexcept {
+        return cells[static_cast(d)][static_cast(c)];
+    }
+    Cell& at(Domain d, SpeciesClass c) noexcept {
+        return cells[static_cast(d)][static_cast(c)];
+    }
+};
+
+/// Build the full matrix (states + reasons). Pure: never writes warnings.
+Matrix resolve(const SimulationContext& ctx);
+
+const char* domainName(Domain d) noexcept;
+const char* speciesClassName(SpeciesClass c) noexcept;
+const char* cellStateName(CellState s) noexcept;
+
+/// The `.rpt` block: a fixed-width table, one line per domain, one column
+/// per class, each cell "on(n)" / "off:KEY" / "n/a:reason". Ends with '\n'.
+std::string formatReportBlock(const Matrix& m);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_POLICY_HPP
diff --git a/src/engine/transport/components/EulerianArdComponent/ArdConfig.cpp b/src/engine/transport/components/EulerianArdComponent/ArdConfig.cpp
new file mode 100644
index 000000000..afe73d5e8
--- /dev/null
+++ b/src/engine/transport/components/EulerianArdComponent/ArdConfig.cpp
@@ -0,0 +1,602 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ArdConfig.cpp
+ * @brief transport.ard component apply hook — phase E3 body (dispersion
+ *        subset of model.ard).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ArdConfig.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../../core/FileIO.hpp"   // issue #7: UTF-8 paths on Windows
+#include "../../../core/SimulationContext.hpp"
+#include "../../../plugins/ProcessComponentRegistry.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr const char* kArdId = "org.hydrocouple.openswmm.transport.ard";
+
+std::vector tokenize(const std::string& line) {
+    std::vector toks;
+    std::string cur;
+    for (const char ch : line) {
+        if (ch == ' ' || ch == '\t') {
+            if (!cur.empty()) { toks.push_back(cur); cur.clear(); }
+        } else {
+            cur.push_back(ch);
+        }
+    }
+    if (!cur.empty()) toks.push_back(cur);
+    return toks;
+}
+
+std::string upper(std::string s) {
+    std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) {
+        return static_cast(std::toupper(c));
+    });
+    return s;
+}
+
+/// Parse a non-negative double; false if the token is not fully numeric.
+bool parse_value(const std::string& tok, double& out) {
+    char* end = nullptr;
+    out = std::strtod(tok.c_str(), &end);
+    return end != nullptr && *end == '\0' && end != tok.c_str();
+}
+
+void applyArdSections(SimulationContext& ctx,
+                      const components::ComponentConfigSections& config,
+                      std::vector& errors) {
+    // Reset wholesale so a reopened model never inherits stale rows.
+    ctx.ard_config = ArdConfigData{};
+
+    const std::size_t errors_before = errors.size();
+
+    for (const auto& sec : config.sections) {
+        const std::string& tag = sec.first;
+
+        if (tag == "TRANSPORT_OPTIONS") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.empty()) continue;
+                const std::string key = upper(toks[0]);
+                if (key == "DISPERSION") {
+                    if (toks.size() != 2) {
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] DISPERSION expects exactly "
+                            "one argument (OFF | FISCHER | value): '" + line +
+                            "'.");
+                        continue;
+                    }
+                    const std::string val = upper(toks[1]);
+                    if (val == "OFF") {
+                        ctx.ard_config.dispersion_mode = ArdDispersionMode::OFF;
+                    } else if (val == "FISCHER") {
+                        ctx.ard_config.dispersion_mode =
+                            ArdDispersionMode::FISCHER;
+                    } else {
+                        double d = 0.0;
+                        if (!parse_value(toks[1], d) || d < 0.0) {
+                            errors.push_back(
+                                "[TRANSPORT_OPTIONS] DISPERSION '" + toks[1] +
+                                "' is not OFF, FISCHER, or a non-negative "
+                                "coefficient (display units, len²/s).");
+                            continue;
+                        }
+                        ctx.ard_config.dispersion_mode =
+                            ArdDispersionMode::VALUE;
+                        ctx.ard_config.dispersion_value = d;
+                    }
+                } else if (key == "SCALAR_SCHEME") {
+                    // E5a: aliases of the internal FV transport config
+                    // (plan §4). model.ard wins over [OPTIONS] FV_* — the
+                    // component applies after the options parse.
+                    if (toks.size() != 2) {
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] SCALAR_SCHEME expects "
+                            "UPWIND | MUSCL | QUICKEST_ULTIMATE.");
+                        continue;
+                    }
+                    const std::string v = upper(toks[1]);
+                    ctx.ard_config.sets_scalar_scheme = true;  // IO3c
+                    if (v == "UPWIND")
+                        ctx.options.fv.scalar_scheme = fv::ScalarScheme::UPWIND;
+                    else if (v == "MUSCL")
+                        ctx.options.fv.scalar_scheme = fv::ScalarScheme::MUSCL;
+                    else if (v == "QUICKEST_ULTIMATE")
+                        ctx.options.fv.scalar_scheme =
+                            fv::ScalarScheme::QUICKEST_ULTIMATE;
+                    else
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] SCALAR_SCHEME '" + toks[1] +
+                            "' is not UPWIND, MUSCL, or QUICKEST_ULTIMATE.");
+                } else if (key == "LIMITER") {
+                    if (toks.size() != 2) {
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] LIMITER expects MINMOD | "
+                            "VANLEER | SUPERBEE.");
+                        continue;
+                    }
+                    const std::string v = upper(toks[1]);
+                    ctx.ard_config.sets_limiter = true;  // IO3c
+                    if (v == "MINMOD")
+                        ctx.options.fv.limiter = fv::Limiter::MINMOD;
+                    else if (v == "VANLEER")
+                        ctx.options.fv.limiter = fv::Limiter::VANLEER;
+                    else if (v == "SUPERBEE")
+                        ctx.options.fv.limiter = fv::Limiter::SUPERBEE;
+                    else
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] LIMITER '" + toks[1] +
+                            "' is not MINMOD, VANLEER, or SUPERBEE.");
+                } else if (key == "TARGET_DX") {
+                    // E5b: the plan §8 open item resolved — transport-mesh
+                    // cell length under non-FV hydraulics (display units).
+                    // Under FLOW_ROUTING FV the engine warns and ignores it
+                    // (the solver mesh governs).
+                    double v = 0.0;
+                    if (toks.size() != 2 || !parse_value(toks[1], v) ||
+                        v <= 0.0) {
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] TARGET_DX expects a "
+                            "positive cell length (display length units).");
+                        continue;
+                    }
+                    ctx.ard_config.target_dx = v;
+                } else if (key == "DETAILED_OUTPUT") {
+                    if (toks.size() != 2) {
+                        errors.push_back(
+                            "[TRANSPORT_OPTIONS] DETAILED_OUTPUT expects "
+                            "one path argument.");
+                        continue;
+                    }
+                    // Relative paths resolve against the CONFIG file's own
+                    // directory (component-file locality, like the config
+                    // itself resolves against the .inp).
+                    namespace fsys = std::filesystem;
+                    // utf8_path/path_utf8, not fsys::path(std::string)/.string():
+                    // the token and the config's own path are UTF-8, and the
+                    // narrow forms decode/encode in the ANSI code page (#7).
+                    fsys::path p = openswmm::io::utf8_path(toks[1]);
+                    if (p.is_relative()) {
+                        const fsys::path base =
+                            openswmm::io::utf8_path(config.source_path)
+                                .parent_path();
+                        if (!base.empty()) p = base / p;
+                    }
+                    ctx.ard_config.detailed_output_path =
+                        openswmm::io::path_utf8(p);
+                } else {
+                    errors.push_back(
+                        "[TRANSPORT_OPTIONS] unknown key '" + toks[0] +
+                        "' (E5b recognizes: DISPERSION, SCALAR_SCHEME, "
+                        "LIMITER, TARGET_DX, DETAILED_OUTPUT).");
+                }
+            }
+        } else if (tag == "CONDUIT_DISPERSION") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.size() != 2) {
+                    errors.push_back(
+                        "[CONDUIT_DISPERSION] expects ' "
+                        "': '" + line + "'.");
+                    continue;
+                }
+                const int link = ctx.link_names.find(toks[0]);
+                if (link < 0) {
+                    errors.push_back(
+                        "[CONDUIT_DISPERSION] unknown conduit '" + toks[0] +
+                        "'.");
+                    continue;
+                }
+                if (ctx.link_subtypes.conduit_row(link) < 0) {
+                    errors.push_back(
+                        "[CONDUIT_DISPERSION] link '" + toks[0] +
+                        "' is not a conduit — dispersion applies to conduits "
+                        "only (structures are zero-volume passthrough).");
+                    continue;
+                }
+                double d = 0.0;
+                if (!parse_value(toks[1], d) || d < 0.0) {
+                    errors.push_back(
+                        "[CONDUIT_DISPERSION] '" + toks[0] + "': value '" +
+                        toks[1] + "' is not a non-negative coefficient "
+                        "(display units, len²/s).");
+                    continue;
+                }
+                bool dup = false;
+                for (const int prev : ctx.ard_config.conduit_disp_link)
+                    if (prev == link) { dup = true; break; }
+                if (dup) {
+                    errors.push_back(
+                        "[CONDUIT_DISPERSION] duplicate row for conduit '" +
+                        toks[0] + "'.");
+                    continue;
+                }
+                ctx.ard_config.conduit_disp_link.push_back(link);
+                ctx.ard_config.conduit_disp_value.push_back(d);
+            }
+        } else if (tag == "TRANSPORT_BOUNDARIES" ||
+                   tag == "TRANSPORT_SOURCES") {
+            // E5a. Rows are stored RAW — species are resolved after every
+            // component has applied (order-independence w.r.t. the reactions
+            // component; see resolveArdTransportRows). Syntax and numerics
+            // are validated here, where the row text is at hand.
+            const bool is_bc = (tag == "TRANSPORT_BOUNDARIES");
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.size() != 4) {
+                    errors.push_back(
+                        "[" + tag + "] expects '<" +
+                        std::string(is_bc ? "node" : "conduit") +
+                        ">  VALUE  | TIMESERIES ': '" +
+                        line + "'.");
+                    continue;
+                }
+                ArdTransportRow row;
+                row.element = toks[0];
+                row.species = toks[1];
+                const std::string mode = upper(toks[2]);
+                if (mode == "VALUE") {
+                    double v = 0.0;
+                    // P1.4: a boundary CONCENTRATION below zero is
+                    // meaningless and stays refused; a source RATE below
+                    // zero is extraction (D-NS1) and is accepted here, then
+                    // warned once in resolveArdTransportRows.
+                    if (!parse_value(toks[3], v) || (is_bc && v < 0.0)) {
+                        errors.push_back(
+                            "[" + tag + "] '" + toks[0] + "': VALUE '" +
+                            toks[3] + (is_bc ? "' is not a non-negative number."
+                                             : "' is not a number."));
+                        continue;
+                    }
+                    row.value = v;
+                } else if (mode == "TIMESERIES") {
+                    row.is_ts   = true;
+                    row.ts_name = toks[3];
+                } else {
+                    errors.push_back(
+                        "[" + tag + "] '" + toks[0] + "': mode '" + toks[2] +
+                        "' is not VALUE or TIMESERIES.");
+                    continue;
+                }
+                (is_bc ? ctx.ard_config.boundary_rows
+                       : ctx.ard_config.source_rows)
+                    .push_back(std::move(row));
+            }
+        } else if (tag == "STORAGE_MIXING") {
+            errors.push_back(
+                "[STORAGE_MIXING] arrives with plan phase E2b (Eulerian ARD "
+                "plan) — not yet implemented.");
+        } else {
+            errors.push_back(
+                "model.ard: unknown section [" + tag +
+                "] (E5a recognizes: [TRANSPORT_OPTIONS] "
+                "[CONDUIT_DISPERSION] [TRANSPORT_BOUNDARIES] "
+                "[TRANSPORT_SOURCES]).");
+        }
+    }
+
+    if (errors.size() != errors_before) {
+        ctx.ard_config = ArdConfigData{};  // never half-apply
+        return;
+    }
+    ctx.ard_config.configured = true;
+
+    // Silent-bypass enumeration (R4 validation lesson): every configuration
+    // under which this file parses but its content reaches nothing warns at
+    // open, naming the remedy. E5b: TARGET_DX and DETAILED_OUTPUT count as
+    // engine content too (any_engine_content).
+    if (ctx.ard_config.any_engine_content()) {
+        if (ctx.options.ignore_quality) {
+            ctx.warnings.push_back(
+                "A transport.ard component is configured but IGNORE_QUALITY "
+                "is YES — the quality stage does not run, so none of its "
+                "dispersion/boundary/source configuration applies this "
+                "simulation.");
+        } else if (ctx.options.quality_solver !=
+                   QualitySolverKind::EULERIAN_ARD) {
+            // X1: "the LEGACY engine" became "the selected engine" when
+            // LAGRANGIAN joined the enum — the old wording would have
+            // misnamed the engine on a LARD deck.
+            ctx.warnings.push_back(
+                "A transport.ard component is configured but QUALITY_SOLVER "
+                "is not EULERIAN_ARD — its dispersion/boundary/source "
+                "configuration is inert under the selected engine. Set "
+                "[OPTIONS] QUALITY_SOLVER EULERIAN_ARD to activate it.");
+        } else if (ctx.n_pollutants() == 0 &&
+                   ctx.ard_config.any_dispersion()) {
+            // E4/R6: MSX species now transport (and disperse) under the ARD
+            // engine, so an MSX-only model is no longer a bypass. The
+            // reactions component may apply before OR after this hook, so
+            // test the [PROCESS_COMPONENTS] registrations, which are
+            // order-independent, rather than ctx.reactions.
+            bool has_reactions_component = false;
+            for (const auto& spec : ctx.process_component_specs)
+                if (spec.id == "org.hydrocouple.openswmm.reactions")
+                    has_reactions_component = true;
+            if (!has_reactions_component)
+                ctx.warnings.push_back(
+                    "A transport.ard component configures dispersion but the "
+                    "model has no [POLLUTANTS] and no reactions component — "
+                    "there are no transported species, so nothing disperses "
+                    "this simulation.");
+        }
+    }
+}
+
+}  // namespace
+
+void warnIfFvDispersionKeyIgnored(SimulationContext& ctx) {
+    if (ctx.options.fv.dispersion == 0.0) return;
+    if (ctx.options.quality_solver != QualitySolverKind::EULERIAN_ARD) return;
+    ctx.warnings.push_back(
+        "[OPTIONS] FV_DISPERSION is set but does not configure the Eulerian "
+        "ARD engine — it reads dispersion from the transport.ard component "
+        "(model.ard: [TRANSPORT_OPTIONS] DISPERSION OFF|FISCHER| and "
+        "[CONDUIT_DISPERSION] rows). No dispersion is applied from this key. "
+        "Unifying the FV_*/ARD_* option surface arrives with plan phase E5.");
+}
+
+bool ardBoundariesNeedExternalVolumes(const SimulationContext& ctx) {
+    return ctx.options.quality_solver == QualitySolverKind::EULERIAN_ARD &&
+           !ctx.options.ignore_quality &&
+           !ctx.ard_config.bc_node.empty();
+}
+
+void resolveArdTransportRows(SimulationContext& ctx,
+                             std::vector& errors) {
+    auto& cfg = ctx.ard_config;
+    cfg.bc_node.clear();  cfg.bc_msx.clear();
+    cfg.bc_value.clear(); cfg.bc_ts.clear();
+    cfg.src_link.clear(); cfg.src_msx.clear();
+    cfg.src_value.clear(); cfg.src_ts.clear();
+    cfg.transport_rows_resolved = false;
+    if (!cfg.configured || !cfg.any_transport_rows()) {
+        cfg.transport_rows_resolved = true;
+        return;
+    }
+
+    // Species must be MSX: pollutants keep their full legacy loading
+    // surface ([INFLOWS] CONCEN/MASS, DWF, RDII, washoff) and allowing them
+    // here would create a silent double-count question E5a refuses to have.
+    const auto resolve_species = [&](const ArdTransportRow& row,
+                                     const char* sec) -> int {
+        const int s = ctx.reactions.find_species(row.species);
+        if (s >= 0) return s;
+        if (ctx.species_registry.find(row.species) >= 0) {
+            errors.push_back(
+                std::string("[") + sec + "] '" + row.element + "': '" +
+                row.species + "' is a pollutant — pollutant loading uses "
+                "the legacy pathways ([INFLOWS], DWF, washoff); transport "
+                "boundaries/sources apply to MSX species only (E5a).");
+        } else {
+            errors.push_back(
+                std::string("[") + sec + "] '" + row.element +
+                "': unknown species '" + row.species +
+                "' — declare it in the reactions component's "
+                "[REACTION_SPECIES].");
+        }
+        return -1;
+    };
+    const auto resolve_ts = [&](const ArdTransportRow& row,
+                                const char* sec) -> int {
+        const int t = ctx.tables.find_by_kind(row.ts_name, true);
+        if (t < 0)
+            errors.push_back(std::string("[") + sec + "] '" + row.element +
+                             "': unknown timeseries '" + row.ts_name + "'.");
+        return t;
+    };
+
+    for (const auto& row : cfg.boundary_rows) {
+        const int nd = ctx.node_names.find(row.element);
+        if (nd < 0) {
+            errors.push_back("[TRANSPORT_BOUNDARIES] unknown node '" +
+                             row.element + "'.");
+            continue;
+        }
+        const int s = resolve_species(row, "TRANSPORT_BOUNDARIES");
+        if (s < 0) continue;
+        int ts = -1;
+        if (row.is_ts &&
+            (ts = resolve_ts(row, "TRANSPORT_BOUNDARIES")) < 0)
+            continue;
+        bool dup = false;
+        for (std::size_t i = 0; i < cfg.bc_node.size(); ++i)
+            if (cfg.bc_node[i] == nd && cfg.bc_msx[i] == s) {
+                errors.push_back(
+                    "[TRANSPORT_BOUNDARIES] duplicate row for node '" +
+                    row.element + "' species '" + row.species + "'.");
+                dup = true;
+                break;
+            }
+        if (dup) continue;
+        cfg.bc_node.push_back(nd);
+        cfg.bc_msx.push_back(s);
+        cfg.bc_value.push_back(row.value);
+        cfg.bc_ts.push_back(row.is_ts ? ts : -1);
+    }
+
+    for (const auto& row : cfg.source_rows) {
+        const int link = ctx.link_names.find(row.element);
+        if (link < 0 || ctx.link_subtypes.conduit_row(link) < 0) {
+            errors.push_back(
+                "[TRANSPORT_SOURCES] '" + row.element +
+                "' is not a conduit — distributed sources apply to "
+                "conduits.");
+            continue;
+        }
+        const int s = resolve_species(row, "TRANSPORT_SOURCES");
+        if (s < 0) continue;
+        int ts = -1;
+        if (row.is_ts && (ts = resolve_ts(row, "TRANSPORT_SOURCES")) < 0)
+            continue;
+        bool dup = false;
+        for (std::size_t i = 0; i < cfg.src_link.size(); ++i)
+            if (cfg.src_link[i] == link && cfg.src_msx[i] == s) {
+                errors.push_back(
+                    "[TRANSPORT_SOURCES] duplicate row for conduit '" +
+                    row.element + "' species '" + row.species + "'.");
+                dup = true;
+                break;
+            }
+        if (dup) continue;
+        // P1.4 / D-NS1: a negative rate is legal — it means extraction — but
+        // it is unusual enough to say so once at parse time, matching the
+        // node seam's warning for negative [INFLOWS] quality baselines.
+        // Only configured VALUE rows are scanned; a TIMESERIES that dips
+        // negative at runtime is covered by the clamp warning instead
+        // (X6 §2.6's recorded caveat, same reasoning).
+        if (!row.is_ts && row.value < 0.0)
+            ctx.warnings.push_back(
+                "[TRANSPORT_SOURCES] '" + row.element + "' species '" +
+                row.species + "': negative rate is treated as EXTRACTION "
+                "(D-NS1). Removal is clamped to the mass the conduit's "
+                "cells actually hold.");
+        cfg.src_link.push_back(link);
+        cfg.src_msx.push_back(s);
+        // VALUE rates arrive in species mass units per second; internal MSX
+        // store mass is conc(mass/L)·ft³, so divide by L/ft³ once here.
+        // TIMESERIES values get the same conversion at evaluation time.
+        cfg.src_value.push_back(row.value / kLitersPerFt3);
+        cfg.src_ts.push_back(row.is_ts ? ts : -1);
+    }
+
+    // Resolution ran; fatality of any errors pushed above is the caller's
+    // decision (the strict-vs-lenient open path).
+    cfg.transport_rows_resolved = true;
+}
+
+namespace {
+
+/// Shortest decimal that reads back EXACTLY (fmt_degc's convention).
+std::string fmt_num(double v) {
+    char buf[64];
+    for (int prec = 15; prec <= 17; ++prec) {
+        std::snprintf(buf, sizeof(buf), "%.*g", prec, v);
+        if (std::strtod(buf, nullptr) == v) break;
+    }
+    return buf;
+}
+
+/// IO3c: render model.ard from the live config. Boundary/source rows
+/// come from the RAW copies (element/species/value exactly as parsed —
+/// no unit conversion ever touched them; the resolved arrays are
+/// derived, not authoritative). SCALAR_SCHEME and LIMITER are ALIASES
+/// of [OPTIONS] FV_SCALAR_SCHEME / FV_LIMITER — but the INP writer
+/// emits the FV_* block only under FLOW_ROUTING FV, so on a non-FV
+/// deck THIS file is the only carrier of that state across a save.
+/// The provenance flags (sets_scalar_scheme/sets_limiter) say whether
+/// the file spelled the alias: if so it re-renders with the CURRENT
+/// live value (API/GUI edits persist); if not, no alias is invented
+/// (lesson 196).
+/// DETAILED_OUTPUT canonicalises to the absolute path resolved at
+/// apply (the original relative spelling is not retained).
+std::string saveArdConfig(const SimulationContext& ctx) {
+    const auto& cfg = ctx.ard_config;
+    if (!cfg.configured) return {};
+    std::string out;
+    std::string opts;
+    if (cfg.sets_scalar_scheme) {
+        static const char* const kScalar[] = {"UPWIND", "MUSCL",
+                                              "QUICKEST_ULTIMATE"};
+        opts += std::string("SCALAR_SCHEME ") +
+                kScalar[static_cast(ctx.options.fv.scalar_scheme)] +
+                "\n";
+    }
+    if (cfg.sets_limiter) {
+        static const char* const kLim[] = {"MINMOD", "VANLEER",
+                                           "SUPERBEE"};
+        opts += std::string("LIMITER ") +
+                kLim[static_cast(ctx.options.fv.limiter)] + "\n";
+    }
+    if (cfg.dispersion_mode == ArdDispersionMode::FISCHER)
+        opts += "DISPERSION FISCHER\n";
+    else if (cfg.dispersion_mode == ArdDispersionMode::VALUE)
+        opts += "DISPERSION " + fmt_num(cfg.dispersion_value) + "\n";
+    if (cfg.target_dx > 0.0)
+        opts += "TARGET_DX " + fmt_num(cfg.target_dx) + "\n";
+    if (!cfg.detailed_output_path.empty())
+        opts += "DETAILED_OUTPUT " + cfg.detailed_output_path + "\n";
+    if (!opts.empty()) out += "[TRANSPORT_OPTIONS]\n" + opts + "\n";
+    if (!cfg.conduit_disp_link.empty()) {
+        out += "[CONDUIT_DISPERSION]\n";
+        for (std::size_t i = 0; i < cfg.conduit_disp_link.size(); ++i) {
+            const int lk = cfg.conduit_disp_link[i];
+            if (lk < 0 || lk >= ctx.n_links()) continue;
+            out += ctx.link_names.name_of(lk);
+            out += ' ';
+            out += fmt_num(cfg.conduit_disp_value[i]);
+            out += "\n";
+        }
+        out += "\n";
+    }
+    const auto rows = [&out](const char* tag,
+                             const std::vector& rs) {
+        if (rs.empty()) return;
+        out += std::string("[") + tag + "]\n";
+        for (const auto& r : rs) {
+            out += r.element;
+            out += ' ';
+            out += r.species;
+            out += ' ';
+            if (r.is_ts)
+                out += "TIMESERIES " + r.ts_name;
+            else
+                out += "VALUE " + fmt_num(r.value);
+            out += "\n";
+        }
+        out += "\n";
+    };
+    rows("TRANSPORT_BOUNDARIES", cfg.boundary_rows);
+    rows("TRANSPORT_SOURCES", cfg.source_rows);
+    return out;
+}
+
+}  // namespace
+
+void registerArdComponent() {
+    components::ProcessComponentRegistry::instance().register_component(
+        kArdId,
+        "Eulerian ARD transport engine configuration (E3: dispersion; "
+        "boundaries/sources arrive with E5)",
+        [](SimulationContext& ctx, const ProcessComponentSpec& /*spec*/,
+           const components::ComponentConfigSections& config,
+           std::vector& errors) {
+            applyArdSections(ctx, config, errors);
+        },
+        [](const SimulationContext& ctx,
+           const ProcessComponentSpec& /*spec*/) -> std::string {
+            return saveArdConfig(ctx);
+        });
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/EulerianArdComponent/ArdConfig.hpp b/src/engine/transport/components/EulerianArdComponent/ArdConfig.hpp
new file mode 100644
index 000000000..a1433e284
--- /dev/null
+++ b/src/engine/transport/components/EulerianArdComponent/ArdConfig.hpp
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ArdConfig.hpp
+ * @brief The `org.hydrocouple.openswmm.transport.ard` process component —
+ *        phase E3: parse the dispersion subset of `model.ard` into
+ *        SimulationContext::ard_config.
+ *
+ * @details E3 scope: `[TRANSPORT_OPTIONS] DISPERSION OFF|FISCHER|`
+ *          and `[CONDUIT_DISPERSION]` per-conduit overrides. The remaining
+ *          [TRANSPORT_OPTIONS] keys (SCALAR_SCHEME/LIMITER/TARGET_DX — the
+ *          [OPTIONS] FV_* keys still configure those today) and the shared
+ *          1D sections ([TRANSPORT_BOUNDARIES]/[TRANSPORT_SOURCES] E5,
+ *          [STORAGE_MIXING] E2b) are refused with precise deferral errors.
+ *          Configurations under which the parsed dispersion cannot take
+ *          effect (QUALITY_SOLVER other than EULERIAN_ARD, IGNORE_QUALITY,
+ *          no pollutants) warn at open rather than running silently —
+ *          the R4 silent-bypass lesson applied at introduction time.
+ *
+ * @see plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md §4, §6 E3
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_ARD_CONFIG_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_ARD_CONFIG_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Register `org.hydrocouple.openswmm.transport.ard` with the
+/// process-component registry (idempotent; called from SWMMEngine::open
+/// before resolution, next to registerReactionsComponent).
+void registerArdComponent();
+
+/// Warn when `[OPTIONS] FV_DISPERSION` is set under QUALITY_SOLVER
+/// EULERIAN_ARD. The component's own bypass warnings only cover models that
+/// HAVE a transport.ard file; this is the reverse case — the user spelled
+/// dispersion the familiar way, selected the engine that now supports it,
+/// and got nothing. FV_DISPERSION reaches no solver today (WARN 105 says so
+/// under FLOW_ROUTING FV, and nothing says it under DYNWAVE), so E3's
+/// arrival is what makes the silence misleading rather than merely inert.
+void warnIfFvDispersionKeyIgnored(SimulationContext& ctx);
+
+/// E5a: resolve the raw [TRANSPORT_BOUNDARIES]/[TRANSPORT_SOURCES] rows to
+/// node/link/species/timeseries indices. Called from SWMMEngine::open AFTER
+/// all process components (and the embedded reactions fallback) have
+/// applied, because the rows name MSX species and the reactions component
+/// may apply before or after transport.ard in file order. Pushes fatal
+/// diagnostics into `errors`; pollutant species are refused (their loading
+/// surface is the legacy pathways). Source VALUE rates convert from species
+/// mass/s to internal conc·ft³/s here (kLitersPerFt3).
+void resolveArdTransportRows(SimulationContext& ctx,
+                             std::vector& errors);
+
+/// True when the external-load loaders must run even though the model has
+/// no pollutants: a [TRANSPORT_BOUNDARIES] row injects
+/// `qual_vol_in * concentration`, and `qual_vol_in` is accumulated by those
+/// loaders. Without this an MSX-ONLY model — the nh2cl shape, and the one
+/// E5a exists to enable — assembles no inflow volume and its boundary
+/// delivers exactly nothing.
+bool ardBoundariesNeedExternalVolumes(const SimulationContext& ctx);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_ARD_CONFIG_HPP
diff --git a/src/engine/transport/components/EulerianArdComponent/ArdEngine.cpp b/src/engine/transport/components/EulerianArdComponent/ArdEngine.cpp
new file mode 100644
index 000000000..297364ef9
--- /dev/null
+++ b/src/engine/transport/components/EulerianArdComponent/ArdEngine.cpp
@@ -0,0 +1,1789 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ArdEngine.cpp
+ * @brief Solver-agnostic Eulerian ARD transport engine — phase E1 body.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ArdEngine.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../core/UnitConversion.hpp"
+#include "../../../quality/NegativeSources.hpp"
+#include "../../../hydraulics/Node.hpp"
+#include "../../InitialQualitySeeds.hpp"
+#include "../../TransportPolicy.hpp"   // E2
+#include "../ReactionModule/ReactionLegacyBinding.hpp"   // U2: ensureMsxState
+#include "../../../hydraulics/fv/FvKernels.hpp"
+#include "../../../hydraulics/fv/NetworkMeshBuilder.hpp"
+#include "../HeatFluxModules/BedExchange.hpp"
+#include "../HeatFluxModules/HeatFluxes.hpp"
+#include "../HeatFluxModules/HeatOverrides.hpp"
+#include "../HeatFluxModules/SolarRadiation.hpp"
+#include "../HeatFluxModules/SurfaceExchange.hpp"
+#include "../../fvkernels/SpeciesTransportKernels.hpp"
+#include "../ReactionModule/ReactionArdBinding.hpp"
+
+namespace openswmm::transport {
+
+namespace fvk = openswmm::transport::fvkernels;
+namespace k   = openswmm::fv::kernels;
+
+namespace {
+/// CFL number for the advection subcycling. Conservative: the kernels are
+/// TVD at CFL ≤ 1; 0.9 leaves headroom for the projected-flux ramp.
+constexpr double kCfl = 0.9;
+/// Hard cap on substeps per routing step (pathological velocities).
+constexpr int kMaxSubsteps = 512;
+/// Below this store volume (ft3) a node holds no meaningful concentration —
+/// used to decide when a store has emptied rather than merely shrunk.
+constexpr double kMinStoreVol = 1.0e-9;
+/// Relative resync mismatch |v_new/v_old - 1| treated as hydraulic noise
+/// rather than untracked water (see step()). The bit-exact DW kernels leave a
+/// steady chain jittering by up to 5.6e-6 (test_ard_node_store); genuine
+/// untracked gains (the draining-storage deck) are O(0.1).
+constexpr double kResyncNoiseRel = 1.0e-4;
+/// Debt 216's containment band: the temperature row is exempt from the
+/// non-negativity floor (0 degC is an ordinary state, and flooring there
+/// silently pins sub-zero water at freezing) but NOT unbounded — the naked
+/// exemption let the near-dry store oscillation (the recorded CFL-starvation
+/// family) run temp-mass to +-1e62 where the floor used to eat its negative
+/// half. The band is the PARSER's own authoring range (parse_celsius,
+/// HeatComponent.cpp kMinTemp/kMaxTemp — the values MUST agree): any deck
+/// whose real temperatures live inside it is untouched, and a store outside
+/// it is numerically broken by the engine's own definition.
+constexpr double kTempFloorC = -50.0;
+constexpr double kTempCeilC  = 100.0;
+/// Legacy's ZERO_VOLUME (massbal.c): one litre, in ft3. Below this an
+/// element's mass/volume quotient is residue over residue — LEGACY treats
+/// the element as holding no water at all, which is why it stays bounded on
+/// a draining deck where a 1e-12 floor publishes astronomical quotients.
+constexpr double kZeroVolumeFt3 = 0.0353147;
+
+// --- E3 Fischer auto-computation guards (all internal ft units) -------------
+/// g (ft/s²) for the shear velocity U* = √(g·Y·S).
+constexpr double kGravity = 32.174;
+/// Slope floor: a dead-flat conduit has S = 0 and the formula divides by
+/// U* — the same reason legacy SWMM floors conduit slopes. Physics below
+/// this floor is dominated by mixing the formula does not model anyway.
+constexpr double kMinSlope = 1.0e-5;
+/// Depth floor (ft): below this the conduit is effectively dry; v² in the
+/// numerator vanishes faster than Y·U* in the denominator, so D → 0 is the
+/// physical limit and also the numerically safe one.
+constexpr double kMinFischerDepth = 0.01;
+}  // namespace
+
+// ===========================================================================
+// init — mesh + state sizing
+// ===========================================================================
+
+bool ArdEngine::init(SimulationContext& ctx) {
+    warnings_.clear();
+    initialized_ = false;
+
+    // E4/R6: the mesh state carries pollutants (rows 0..np-1, index-aligned
+    // with the legacy pollutant index) plus the MSX species (rows np..) when
+    // a reactions component is active — MSX species are TRANSPORTED under
+    // this engine, retiring the R4b element-local limitation here. WALL
+    // species have no transport semantics yet: fall back to LEGACY (whose
+    // R4 binding runs them element-locally) with a precise warning.
+    // E2: the class enables come from the one policy
+    // (transport::network1DEnables — identical values to the pre-E2 inline
+    // derivation: this engine only initialises when IGNORE_QUALITY is NO).
+    // The row ORDER is the canonical SpeciesRegistry order (pollutants,
+    // MSX, age, temperature), the same one the 2D surface state uses.
+    const transport::ClassEnables en = transport::network1DEnables(ctx);
+    const int np = en.n_pollut;
+    int nm = 0;
+    if (transport::ardReactionsActive(ctx)) {
+        if (en.msx_has_wall) {
+            warnings_.push_back(
+                "QUALITY_SOLVER EULERIAN_ARD: WALL species have no transport "
+                "semantics under this engine yet — falling back to LEGACY, "
+                "which runs them per element (R4).");
+            return false;
+        }
+        nm = en.n_msx;
+    }
+    // A1a: the reserved __WATER_AGE__ species rides the mesh as the LAST
+    // row (after pollutants and MSX): zero-order aging + volume-weighted
+    // mixing come free from the shared kernels; loaders deliver per-source
+    // age-volume like a pollutant load.
+    const int na = en.age ? 1 : 0;
+    // H4: __TEMPERATURE__ takes the row AFTER age, so the mesh row order
+    // matches the reported column order H1 fixed (pollutants, MSX, age,
+    // temperature). Advection, FCT, node mixing, structure passthrough and
+    // dispersion are all generic over `ns` — the row gets every one of them
+    // for free, at the same dispersion coefficient as a solute.
+    const int nt = en.temperature ? 1 : 0;
+    const int ns = np + nm + na + nt;
+    nm_       = nm;
+    age_row_  = (na > 0) ? np + nm : -1;
+    temp_row_ = (nt > 0) ? np + nm + na : -1;
+    if (ns <= 0) return false;
+
+    // Mesh options are entered in DISPLAY units and must convert to internal
+    // feet before meshing — exactly what Router::initFv does for the FV
+    // solver. E1 passed ctx.options.fv RAW, a latent SI defect (an explicit
+    // FV_CELL_LENGTH in metres meshed as feet; invisible to every CFS gate —
+    // the lesson-20 shape). Fixed here alongside E5b's TARGET_DX, which sets
+    // the transport-mesh cell length under non-FV hydraulics (plan §8
+    // resolved); under FLOW_ROUTING FV the solver mesh governs and the key
+    // warns.
+    fv::FvOptions mesh_opts = ctx.options.fv;
+    {
+        const double ucf_len0 = ucf::Ucf[ucf::LENGTH][ucf::getUnitSystem(
+            static_cast(ctx.options.flow_units))];
+        mesh_opts.cell_length   /= ucf_len0;
+        mesh_opts.slot_celerity /= ucf_len0;
+        mesh_opts.dispersion    /= ucf_len0 * ucf_len0;
+        if (ctx.ard_config.configured && ctx.ard_config.target_dx > 0.0) {
+            if (ctx.options.routing_model == RoutingModel::FV) {
+                warnings_.push_back(
+                    "[TRANSPORT_OPTIONS] TARGET_DX is ignored under "
+                    "FLOW_ROUTING FV — the hydraulic solver's mesh governs "
+                    "transport (FV_CELL_LENGTH).");
+            } else {
+                mesh_opts.cell_length = ctx.ard_config.target_dx / ucf_len0;
+            }
+        }
+    }
+    const auto report = fv::buildNetworkMesh(ctx, mesh_opts, mesh_);
+    for (const auto& w : report.warnings) warnings_.push_back(w);
+    if (!report.errors.empty()) {
+        for (const auto& e : report.errors)
+            warnings_.push_back("EULERIAN_ARD mesh error: " + e);
+        return false;
+    }
+    const int nc = mesh_.n_cells();
+    const int nf = mesh_.n_faces();
+    const int nn = static_cast(mesh_.node_face_ptr.empty()
+                                        ? 0
+                                        : mesh_.node_face_ptr.size() - 1);
+    if (nc <= 0) return false;
+
+    state_.resize(nc, nn, ns);
+
+    const auto unc = static_cast(nc);
+    const auto unf = static_cast(nf);
+    const auto uns = static_cast(ns);
+
+    face_q_.assign(unf, 0.0);
+    f_mass_.assign(unf, 0.0);
+    f_sstar_.assign(unf, 0.0);
+    f_state_l_.assign(unf, k::FaceState{});
+    f_state_r_.assign(unf, k::FaceState{});
+    f_flux_.assign(unf, k::FaceFlux{});
+    f_phi_l_.assign(uns * unf, 0.0);
+    f_phi_r_.assign(uns * unf, 0.0);
+    f_phi_flux_.assign(uns * unf, 0.0);
+    cell_slope_.assign(unc, 0.0);
+    lo_flux_.assign(unf, 0.0);
+    anti_flux_.assign(unf, 0.0);
+    td_.assign(unc, 0.0);
+    anew_.assign(unc, 0.0);
+    rplus_.assign(unc, 1.0);
+    rminus_.assign(unc, 1.0);
+    cell_u_.assign(unc, 0.0);
+    cell_active_.assign(unc, char{1});
+    active_faces_.resize(unf);
+    for (int f = 0; f < nf; ++f) active_faces_[static_cast(f)] = f;
+
+    node_mass_.assign(static_cast(nn) * uns, 0.0);
+    node_vol_.assign(static_cast(nn), 0.0);
+
+    // Initial state: cell areas from link volume spread uniformly over the
+    // conduit; pollutant rows (s < np) from the link's/node's initial
+    // quality — the legacy arrays are np-STRIDED, not ns-strided (E4/R6
+    // stride audit); MSX rows (s >= np) from the component's GLOBAL initial
+    // values, matching R4's element-state seeding.
+    const auto unp = static_cast(np);
+    // U2: MSX rows seed from the element state (msx_*_conc), which
+    // ensureMsxState fills from GLOBAL + the per-element rows and a V4
+    // hotstart overwrites. Sizing it here is idempotent and makes the seed
+    // path identical under all three engines (D-IQ5, D-IQ6).
+    const auto unm_msx = static_cast(nm);
+    if (nm > 0) transport::ensureMsxState(ctx);
+
+    // A2a: hotstart-loaded ages win over INITIAL_STATE. Snapshot them
+    // BEFORE the resize below wipes the arrays, and consume the flag.
+    std::vector hs_node_age, hs_link_age;
+    bool age_from_hs = false;
+    if (age_row_ >= 0 && ctx.water_age_state.hotstart_loaded) {
+        age_from_hs = true;
+        hs_node_age = ctx.water_age_state.node_age;
+        hs_link_age = ctx.water_age_state.link_age;
+    }
+    const auto age_seed_link = [&](int link) {
+        if (age_from_hs &&
+            static_cast(link) < hs_link_age.size())
+            return hs_link_age[static_cast(link)];
+        // E-A3: [INITIAL_QUALITY] __WATER_AGE__ rows override the global
+        // (hotstart wins above, D-IQ7).
+        return initialAgeSecondsFor(
+            ctx, true, link,
+            ctx.water_age_config.global_age[static_cast(
+                WaterAgeSource::INITIAL_STATE)]);
+    };
+    // H4: temperature's INITIAL_STATE. Unlike age (whose default is 0, so
+    // an unseeded row merely looks plausible) HeatConfigData's defaults are
+    // deliberately NON-zero — 0 degC is an ordinary temperature — so the
+    // seed must come from the config, never from a zeroed array.
+    const double temp_seed = ctx.heat_config.global_temp[static_cast(
+        HeatSource::INITIAL_STATE)];
+    const auto age_seed_node = [&](std::size_t nd) {
+        if (age_from_hs && nd < hs_node_age.size()) return hs_node_age[nd];
+        return initialAgeSecondsFor(
+            ctx, false, static_cast(nd),
+            ctx.water_age_config.global_age[static_cast(
+                WaterAgeSource::INITIAL_STATE)]);
+    };
+
+    const int n_links = ctx.n_links();
+    for (int r = 0; r < static_cast(mesh_.conduit_link.size()); ++r) {
+        const auto ur = static_cast(r);
+        const int link = mesh_.conduit_link[ur];
+        if (link < 0 || link >= n_links) continue;
+        const int  b   = mesh_.conduit_cell_begin[ur];
+        const int  n   = mesh_.conduit_cell_count[ur];
+        double length = 0.0;
+        for (int i = 0; i < n; ++i)
+            length += mesh_.cell_dx[static_cast(b + i)];
+        const double vol = ctx.links.volume[static_cast(link)];
+        const double a0  = (length > 0.0) ? vol / length : 0.0;
+        for (int i = 0; i < n; ++i) {
+            const auto uc = static_cast(b + i);
+            state_.cell_a[uc] = a0;
+            for (int s = 0; s < np; ++s) {
+                state_.cell_phi[static_cast(s) * unc + uc] =
+                    ctx.links.conc[static_cast(link) * unp +
+                                   static_cast(s)];
+            }
+            // U2: MSX rows seed from the element state (msx_link_conc),
+            // which ensureMsxState fills with GLOBAL + the per-element rows
+            // ([REACTION_QUALITY] LINK and, mirrored, [INITIAL_QUALITY]) —
+            // the same numbers the inline fill produced — and which a V4
+            // hotstart overwrites before this lazy init (D-IQ5).
+            for (int m = 0; m < nm; ++m) {
+                const std::size_t xi = static_cast(link) * unm_msx +
+                                       static_cast(m);
+                state_.cell_phi[static_cast(np + m) * unc + uc] =
+                    xi < ctx.reactions.msx_link_conc.size()
+                        ? ctx.reactions.msx_link_conc[xi]
+                        : ctx.reactions.init_global[static_cast(m)];
+            }
+            if (age_row_ >= 0)
+                state_.cell_phi[static_cast(age_row_) * unc + uc] =
+                    age_seed_link(link);
+            if (temp_row_ >= 0)
+                state_.cell_phi[static_cast(temp_row_) * unc + uc] =
+                    initialTempFor(ctx, true, link, temp_seed);   // E-A3
+        }
+    }
+    for (int nd = 0; nd < nn && nd < ctx.n_nodes(); ++nd) {
+        const auto und = static_cast(nd);
+        // The store is the water the continuity equation attributes to the
+        // node (node::storeVolume), not nodes.volume: the routers book that
+        // in legacy's convention, which is 0 for a junction below its rim.
+        node_vol_[und] = node::storeVolume(ctx.nodes, nd);
+        for (int s = 0; s < np; ++s)
+            node_mass_[und * uns + static_cast(s)] =
+                ctx.nodes.conc[und * unp + static_cast(s)] *
+                node_vol_[und];
+        // U2: node MSX seeds from msx_node_conc (see the link loop).
+        for (int m = 0; m < nm; ++m) {
+            const std::size_t xi = und * unm_msx + static_cast(m);
+            node_mass_[und * uns + static_cast(np + m)] =
+                (xi < ctx.reactions.msx_node_conc.size()
+                     ? ctx.reactions.msx_node_conc[xi]
+                     : ctx.reactions.init_global[static_cast(m)]) *
+                node_vol_[und];
+        }
+        if (age_row_ >= 0)
+            node_mass_[und * uns + static_cast(age_row_)] =
+                age_seed_node(und) * node_vol_[und];
+        if (temp_row_ >= 0)
+            node_mass_[und * uns + static_cast(temp_row_)] =
+                initialTempFor(ctx, false, nd, temp_seed) *       // E-A3
+                node_vol_[und];
+    }
+    if (age_row_ >= 0)
+        ctx.water_age_state.resize(ctx.n_nodes(), ctx.n_links(),
+                                   ctx.n_subcatches());  // A3: keep watershed rows
+    if (temp_row_ >= 0) {
+        ctx.heat_state.resize(ctx.n_nodes(), ctx.n_links(), temp_seed);
+        // E-A3: mirror per-element temperature rows into the state arrays so
+        // anything reading heat_state before the first publish agrees with
+        // the mesh (which already carries them and republishes each step).
+        applyInitialTempOverrides(ctx);
+    }
+    // (resize consumed hotstart_loaded — the loaded ages now live in the
+    // mesh state and republish on the first step.)
+
+    // E2: structures (pumps/orifices/weirs/outlets) transport as zero-volume
+    // passthrough of the donor node store (plan §2.1, element coverage) — no
+    // warning needed any more.
+
+    // E3: dispersion configuration from the transport.ard component. Values
+    // arrive in project display units (len²/s); convert to internal ft²/s
+    // exactly the way Router::initFv converts FV_DISPERSION.
+    disp_active_    = false;
+    disp_mode_      = static_cast(ArdDispersionMode::OFF);
+    disp_global_ft_ = 0.0;
+    conduit_disp_ft_.assign(mesh_.conduit_link.size(), -1.0);
+    cell_disp_.assign(unc, 0.0);
+    if (ctx.ard_config.configured && ctx.ard_config.any_dispersion()) {
+        const double ucf_len = ucf::Ucf[ucf::LENGTH][ucf::getUnitSystem(
+            static_cast(ctx.options.flow_units))];
+        disp_mode_      = static_cast(ctx.ard_config.dispersion_mode);
+        disp_global_ft_ =
+            ctx.ard_config.dispersion_value / (ucf_len * ucf_len);
+        // Overrides are keyed by LINK index; invert mesh conduit_link so
+        // each mesh conduit row learns its override (if any).
+        for (std::size_t i = 0; i < ctx.ard_config.conduit_disp_link.size();
+             ++i) {
+            const int link = ctx.ard_config.conduit_disp_link[i];
+            const double d_ft =
+                ctx.ard_config.conduit_disp_value[i] / (ucf_len * ucf_len);
+            for (std::size_t r = 0; r < mesh_.conduit_link.size(); ++r)
+                if (mesh_.conduit_link[r] == link) conduit_disp_ft_[r] = d_ft;
+        }
+        disp_active_ = true;
+    }
+
+    // E4: kdecay is applied by the reaction stage (exact exponential) — the
+    // E1 "not yet applied" warning is retired.
+
+    // E5a: boundary/source rows onto the mesh. The rows were resolved to
+    // indices at open (resolveArdTransportRows); here they map to species
+    // ROWS (np + msx) and, for sources, to mesh conduit rows + lengths.
+    bc_node_.clear(); bc_srow_.clear(); bc_ts_.clear();
+    bc_value_.clear(); bc_now_.clear();
+    src_crow_.clear(); src_srow_.clear(); src_ts_.clear();
+    src_value_.clear(); src_len_.clear(); src_now_.clear();
+    if (nm > 0) {
+        const auto& cfg = ctx.ard_config;
+        for (std::size_t i = 0; i < cfg.bc_node.size(); ++i) {
+            if (cfg.bc_msx[i] < 0 || cfg.bc_msx[i] >= nm) continue;
+            if (cfg.bc_node[i] < 0 || cfg.bc_node[i] >= nn) continue;
+            bc_node_.push_back(cfg.bc_node[i]);
+            bc_srow_.push_back(np + cfg.bc_msx[i]);
+            bc_value_.push_back(cfg.bc_value[i]);
+            bc_ts_.push_back(cfg.bc_ts[i]);
+        }
+        bc_now_.assign(bc_node_.size(), 0.0);
+        for (std::size_t i = 0; i < cfg.src_link.size(); ++i) {
+            if (cfg.src_msx[i] < 0 || cfg.src_msx[i] >= nm) continue;
+            // Find the mesh conduit row carrying this link.
+            int crow = -1;
+            for (std::size_t r2 = 0; r2 < mesh_.conduit_link.size(); ++r2)
+                if (mesh_.conduit_link[r2] == cfg.src_link[i]) {
+                    crow = static_cast(r2);
+                    break;
+                }
+            if (crow < 0) continue;
+            double length = 0.0;
+            const int b2 = mesh_.conduit_cell_begin[static_cast(crow)];
+            const int n2 = mesh_.conduit_cell_count[static_cast(crow)];
+            for (int i2 = 0; i2 < n2; ++i2)
+                length += mesh_.cell_dx[static_cast(b2 + i2)];
+            src_crow_.push_back(crow);
+            src_srow_.push_back(np + cfg.src_msx[i]);
+            src_value_.push_back(cfg.src_value[i]);
+            src_ts_.push_back(cfg.src_ts[i]);
+            src_len_.push_back(std::max(length, 1.0e-6));
+        }
+        src_now_.assign(src_crow_.size(), 0.0);
+    }
+
+    // E5b: per-cell CSV sidecar. Failure to open is a WARNING (the run
+    // proceeds without detail output), never fatal.
+    detail_active_ = false;
+    detail_time_s_ = 0.0;
+    if (detail_out_.is_open()) detail_out_.close();
+    if (ctx.ard_config.configured &&
+        !ctx.ard_config.detailed_output_path.empty()) {
+        detail_out_.open(ctx.ard_config.detailed_output_path,
+                         std::ios::out | std::ios::trunc);
+        if (detail_out_.is_open()) {
+            detail_out_ << "time_s,element,kind,cell,species,conc\n";
+            detail_active_ = true;
+        } else {
+            warnings_.push_back(
+                "[TRANSPORT_OPTIONS] DETAILED_OUTPUT: could not open '" +
+                ctx.ard_config.detailed_output_path +
+                "' for writing — detail output disabled this run.");
+        }
+    }
+
+    initialized_ = true;
+    return true;
+}
+
+// ===========================================================================
+// updateTransportRows — per-routing-step BC/source evaluation (E5a)
+// ===========================================================================
+
+void ArdEngine::updateTransportRows(SimulationContext& ctx) {
+    for (std::size_t i = 0; i < bc_node_.size(); ++i) {
+        double c = bc_value_[i];
+        const int ts = bc_ts_[i];
+        if (ts >= 0 && ts < static_cast(ctx.tables.count()))
+            c = table_tseries_lookup_cursor(ctx.tables[ts],
+                                            ctx.current_date);
+        bc_now_[i] = std::max(0.0, c);
+    }
+    for (std::size_t i = 0; i < src_crow_.size(); ++i) {
+        double r = src_value_[i];   // already internal conc·ft³/s
+        const int ts = src_ts_[i];
+        if (ts >= 0 && ts < static_cast(ctx.tables.count()))
+            r = table_tseries_lookup_cursor(ctx.tables[ts],
+                                            ctx.current_date) /
+                kLitersPerFt3;      // ts values are species mass/s
+        // P1.4: the sign is CARRIED. This was `std::max(0.0, r)`, which
+        // silently zeroed a negative rate before the apply loop ever saw
+        // it — so a [TRANSPORT_SOURCES] extraction row did nothing at all,
+        // and said nothing about doing nothing. That is the same shape X6
+        // fixed at the loader seam in this file ("silently DROPPED negative
+        // loads while the ledger booked the full request"); cell sources
+        // were scoped out of D-NS1 (X6 §2.5) and kept the defect.
+        //
+        // The BC clamp above is deliberately NOT changed: a boundary
+        // CONCENTRATION below zero is meaningless, whereas a source RATE
+        // below zero is extraction. Same expression, different quantity.
+        src_now_[i] = r;
+    }
+}
+
+// ===========================================================================
+// projectHydraulics — continuity-consistent face fluxes (plan §3.2)
+// ===========================================================================
+
+void ArdEngine::projectHydraulics(SimulationContext& ctx, double dt) {
+    const int nf = mesh_.n_faces();
+    std::fill(face_q_.begin(), face_q_.end(), 0.0);
+    std::vector face_set(static_cast(nf), char{0});
+
+    for (int r = 0; r < static_cast(mesh_.conduit_link.size()); ++r) {
+        const auto ur = static_cast(r);
+        const int link = mesh_.conduit_link[ur];
+        if (link < 0) continue;
+        const auto ul = static_cast(link);
+        const int b = mesh_.conduit_cell_begin[ur];
+        const int n = mesh_.conduit_cell_count[ur];
+        if (n <= 0) continue;
+
+        // Link flow + volume change over this routing step. The ramp
+        // F_i = Q + dV/dt·(1/2 − i/n), i = 0..n (cell-boundary index along
+        // the conduit axis), gives every cell exactly dV/n of storage change
+        // and centres the profile on the solver's link flow. Uniform-field
+        // preservation and exact conservation both follow (E1 gates).
+        const double q  = ctx.links.flow[ul];
+        const double dv = (dt > 0.0)
+                              ? (ctx.links.volume[ul] -
+                                 ctx.links.old_volume[ul]) / dt
+                              : 0.0;
+
+        for (int i = 0; i <= n; ++i) {
+            // The face between cell (b+i-1) and (b+i); ends map through the
+            // cells' own face indices. Walk via the cell face pair arrays.
+            // Side convention (per the FCT gather in the kernels): side == 0
+            // means the CELL IS LEFT of that face — the face sits at the
+            // cell's axis-POSITIVE (downstream) end; side == 1 means the face
+            // is the cell's upstream face.
+            int face = -1;
+            if (i < n) {
+                const auto uc = static_cast(b + i);
+                face = (mesh_.cell_side0[uc] == 1) ? mesh_.cell_face0[uc]
+                                                   : mesh_.cell_face1[uc];
+                // upstream face of cell b+i (between b+i-1 and b+i)
+            } else {
+                const auto uc = static_cast(b + n - 1);
+                face = (mesh_.cell_side0[uc] == 0) ? mesh_.cell_face0[uc]
+                                                   : mesh_.cell_face1[uc];
+                // downstream face of the last cell
+            }
+            if (face < 0 || face >= nf) continue;
+            const auto uf = static_cast(face);
+            const double frac = (n > 0)
+                                    ? (0.5 - static_cast(i) /
+                                                 static_cast(n))
+                                    : 0.0;
+            const double fq = q + dv * frac;
+            if (face_set[uf]) {
+                // Splice face shared with the neighbouring conduit (virtual
+                // junction): take the mean of the two conduits' end values.
+                face_q_[uf] = 0.5 * (face_q_[uf] + fq);
+            } else {
+                face_q_[uf]  = fq;
+                face_set[uf] = char{1};
+            }
+        }
+    }
+
+    // Publish into the kernel-facing face arrays. Sign-of-flux upwinding is
+    // the degenerate contact-speed criterion of the projected path (plan
+    // §2, Riemann-solver clarification): sstar carries the flux sign.
+    for (int f = 0; f < nf; ++f) {
+        const auto uf = static_cast(f);
+        const double fq = face_q_[uf];
+        f_mass_[uf]  = fq;
+        f_sstar_[uf] = fq;
+        k::FaceFlux fl;
+        fl.mass  = fq;
+        fl.sstar = fq;
+        f_flux_[uf] = fl;
+
+        const int cl = mesh_.face_cl[uf];
+        const int cr = mesh_.face_cr[uf];
+        k::FaceState sl{}, sr{};
+        if (cl >= 0) {
+            const auto ucl = static_cast(cl);
+            sl.a = state_.cell_a[ucl];
+            sl.q = fq;
+        }
+        if (cr >= 0) {
+            const auto ucr = static_cast(cr);
+            sr.a = state_.cell_a[ucr];
+            sr.q = fq;
+        }
+        f_state_l_[uf] = sl;
+        f_state_r_[uf] = sr;
+    }
+
+    // Cell velocities for the QUICKEST Courant number.
+    const int nc = mesh_.n_cells();
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        const double a = state_.cell_a[uc];
+        cell_u_[uc] = (a > k::kDryArea)
+                          ? 0.5 * (face_q_[static_cast(
+                                       mesh_.cell_face0[uc])] +
+                                   face_q_[static_cast(
+                                       mesh_.cell_face1[uc])]) / a
+                          : 0.0;
+    }
+}
+
+// ===========================================================================
+// updateDispersion — per-cell coefficients for this routing step (E3)
+// ===========================================================================
+
+void ArdEngine::updateDispersion(SimulationContext& ctx) {
+    const auto mode = static_cast(disp_mode_);
+    for (int r = 0; r < static_cast(mesh_.conduit_link.size()); ++r) {
+        const auto ur = static_cast(r);
+        double d = 0.0;
+        if (conduit_disp_ft_[ur] >= 0.0) {
+            d = conduit_disp_ft_[ur];        // user override always wins
+        } else if (mode == ArdDispersionMode::VALUE) {
+            d = disp_global_ft_;
+        } else if (mode == ArdDispersionMode::FISCHER) {
+            // Fischer et al. (1979): D = 0.011 v²B²/(Y·U*), U* = √(g·Y·S) —
+            // the CSH §4.2 coefficient model without the numerical-dispersion
+            // correction (plan §2). Link-mean quantities, internal ft units:
+            //   A = V/L, v = |Q|/A, Y = midpoint depth, B = A/Y (mean width),
+            //   S = |conduit slope| floored.
+            // A dry or stagnant conduit gets D = 0 (the physical limit).
+            // Note D is unbounded above as Y → floor with v finite; that is
+            // safe here because the implicit solve is unconditionally stable
+            // and monotone — the worst case is over-mixing toward uniform,
+            // never an overshoot.
+            const int link = mesh_.conduit_link[ur];
+            const int cr2  = (link >= 0)
+                                 ? ctx.link_subtypes.conduit_row(link)
+                                 : -1;
+            if (link >= 0 && cr2 >= 0) {
+                const auto ul   = static_cast(link);
+                const auto ucr  = static_cast(cr2);
+                const double len =
+                    ctx.link_subtypes.conduits.length[ucr];
+                const double vol = ctx.links.volume[ul];
+                const double y   = ctx.links.depth[ul];
+                const double a   =
+                    (len > 0.0) ? vol / len : 0.0;
+                if (a > k::kDryArea && y > kMinFischerDepth) {
+                    const double vel = std::fabs(ctx.links.flow[ul]) / a;
+                    if (vel > 0.0) {
+                        const double b_w = a / y;
+                        const double s = std::max(
+                            std::fabs(ctx.link_subtypes.conduits.slope[ucr]),
+                            kMinSlope);
+                        const double ustar = std::sqrt(kGravity * y * s);
+                        d = 0.011 * vel * vel * b_w * b_w / (y * ustar);
+                    }
+                }
+            }
+        }
+        const int b = mesh_.conduit_cell_begin[ur];
+        const int n = mesh_.conduit_cell_count[ur];
+        for (int i = 0; i < n; ++i)
+            cell_disp_[static_cast(b + i)] = d;
+    }
+}
+
+// ===========================================================================
+// substep — advection + node mixing over dt_sub
+// ===========================================================================
+
+void ArdEngine::substep(SimulationContext& ctx, double dt_sub,
+                        double load_frac) {
+    const int ns = state_.n_species;
+    const int nc = mesh_.n_cells();
+    const int nf = mesh_.n_faces();
+    const auto uns = static_cast(ns);
+    const auto unc = static_cast(nc);
+    const auto unf = static_cast(nf);
+
+    // 1. Interior reconstruction + FCT through the shared kernels.
+    fvk::SpeciesKernelView v;
+    v.mesh          = &mesh_;
+    v.state         = &state_;
+    v.scalar_scheme = ctx.options.fv.scalar_scheme;
+    v.limiter       = ctx.options.fv.limiter;
+    v.dispersion    = 0.0;   // scalar path unused; per-cell array below (E3)
+    v.cell_dispersion = disp_active_ ? &cell_disp_ : nullptr;
+    v.hllc          = true;  // sstar = flux sign (projected path)
+    v.f_mass        = &f_mass_;
+    v.f_sstar       = &f_sstar_;
+    v.f_state_l     = &f_state_l_;
+    v.f_state_r     = &f_state_r_;
+    v.f_flux        = &f_flux_;
+    v.cell_u        = &cell_u_;
+    v.cell_active   = &cell_active_;
+    v.active_faces  = &active_faces_;
+    v.f_phi_l       = &f_phi_l_;
+    v.f_phi_r       = &f_phi_r_;
+    v.f_phi_flux    = &f_phi_flux_;
+    v.cell_slope    = &cell_slope_;
+    v.lo_flux       = &lo_flux_;
+    v.anti_flux     = &anti_flux_;
+    v.td            = &td_;
+    v.anew          = &anew_;
+    v.rplus         = &rplus_;
+    v.rminus        = &rminus_;
+    fvk::reconstructScalars(v, dt_sub);
+
+    const int nn = static_cast(node_mass_.size() / std::max(uns, 1));
+
+    // 1b. External loads (washoff, DWF, RDII, GW, iface, direct inflows) are
+    //     mixed into the store BEFORE the faces read it — "mix, then
+    //     discharge". This ordering is the whole ballgame for a junction,
+    //     whose own volume is small next to what passes through it.
+    //
+    //     Discharging first and mixing afterwards, as this did, meant the
+    //     water leaving a node in a given step carried the concentration
+    //     the node held BEFORE that step's inflow arrived — a full-step lag
+    //     that got worse as ROUTING_STEP grew, and it broke in both
+    //     directions:
+    //
+    //       * The face debit could exceed the store, and the max(0.0, ...)
+    //         floor on volume swallowed the excess as a silent sink while
+    //         the mass debit stood in full. A steady 5 cfs / 100 mg/L
+    //         inflow published 70.6 mg/L at ROUTING_STEP 5.
+    //       * Above ROUTING_STEP ~10 the mass debit itself exceeded the
+    //         store's mass, the floor clamped the store at zero, and the
+    //         receiving cell had already been handed the full oversized
+    //         flux — mass created from nothing, 7730 mg/L out of a 100 mg/L
+    //         inflow at ROUTING_STEP 20.
+    //
+    //     Mixing first makes a zero-volume junction behave the way legacy's
+    //     findNodeQual does — what enters in a step leaves in that step at
+    //     the mixed concentration — and makes the store's outflow
+    //     self-limiting, because the volume the faces draw is the volume
+    //     the inflow just delivered. LEGACY reads 100.000 at every routing
+    //     step on that deck; so does this now.
+    //
+    //     NOTE the load asymmetry, which is not a typo: qual_vol_in is an
+    //     AMOUNT already integrated over the routing step (the loaders add
+    //     q*dt), so it is prorated by load_frac; qual_mass_in is a RATE
+    //     (mass/sec — see mixAtNodes, which multiplies it by dt), so it
+    //     integrates over dt_sub. Prorating the rate instead of integrating
+    //     it made every external load land a factor of dt_step too small.
+    //
+    //     E4/R6 stride audit: qual_mass_in is a POLLUTANT array
+    //     ([node * np + p]) — only the pollutant rows receive external
+    //     loads. MSX species have no loading pathway until [TRANSPORT_
+    //     SOURCES]/[TRANSPORT_BOUNDARIES] land (E5): inflow water carries
+    //     ZERO MSX concentration, so sustained inflow dilutes MSX stores —
+    //     the documented default, and the transport observable the R6 gate
+    //     rides on.
+    // 1a'. Loads at a VIRTUAL junction go to the two cells adjoining its
+    //     spliced face, half each (see cell_src_vol_ in the header). The
+    //     node-store stages below skip these nodes. A negative (extraction)
+    //     load lands on the cells' own non-negativity floor in stage 3.
+    has_vj_src_ = false;
+    if (!mesh_.node_vj_face.empty()) {
+        const int np_v = ctx.n_pollutants();
+        const auto unp_v = static_cast(np_v);
+        auto ensure = [&]() {
+            if (has_vj_src_) return;
+            cell_src_vol_.assign(unc, 0.0);
+            cell_src_mass_.assign(uns * unc, 0.0);
+            has_vj_src_ = true;
+        };
+        auto credit_mass = [&](std::size_t uf, std::size_t s_row, double amount) {
+            if (amount == 0.0) return;
+            ensure();
+            for (const int c : {mesh_.face_cl[uf], mesh_.face_cr[uf]})
+                if (c >= 0)
+                    cell_src_mass_[s_row * unc + static_cast(c)] +=
+                        0.5 * amount;
+        };
+        for (int nd = 0; nd < nn && nd < ctx.n_nodes(); ++nd) {
+            const auto und = static_cast(nd);
+            if (und >= mesh_.node_kind.size() ||
+                mesh_.node_kind[und] != fv::kNodeVirtual)
+                continue;
+            const int f = mesh_.node_vj_face[und];
+            if (f < 0) continue;
+            const auto uf = static_cast(f);
+            const double vol = load_frac * ctx.nodes.qual_vol_in[und];
+            if (vol != 0.0) {
+                ensure();
+                for (const int c : {mesh_.face_cl[uf], mesh_.face_cr[uf]})
+                    if (c >= 0)
+                        cell_src_vol_[static_cast(c)] += 0.5 * vol;
+            }
+            for (int s = 0; s < np_v; ++s)
+                credit_mass(uf, static_cast(s),
+                            dt_sub * ctx.nodes.qual_mass_in[und * unp_v +
+                                                            static_cast(s)]);
+            // U2: species rows np..np+nm-1 take the [INFLOWS] species loads.
+            if (nm_ > 0 && ctx.reactions.msx_ext_mass_in.size() >=
+                               static_cast(ctx.n_nodes()) *
+                                   static_cast(nm_))
+                for (int m = 0; m < nm_; ++m)
+                    credit_mass(uf, static_cast(np_v + m),
+                                dt_sub * ctx.reactions.msx_ext_mass_in[
+                                    und * static_cast(nm_) +
+                                    static_cast(m)]);
+            if (age_row_ >= 0 &&
+                und < ctx.water_age_state.node_age_vol_in.size())
+                credit_mass(uf, static_cast(age_row_),
+                            dt_sub * ctx.water_age_state.node_age_vol_in[und]);
+            if (temp_row_ >= 0 &&
+                und < ctx.heat_state.node_temp_vol_in.size())
+                credit_mass(uf, static_cast(temp_row_),
+                            dt_sub * ctx.heat_state.node_temp_vol_in[und]);
+        }
+        // E5a transport boundaries riding a virtual junction's inflow water
+        // (the same rule as stage 1b(ii) below, routed to the cells).
+        for (std::size_t i = 0; i < bc_node_.size(); ++i) {
+            const auto und = static_cast(bc_node_[i]);
+            if (static_cast(und) >= nn || und >= mesh_.node_kind.size() ||
+                mesh_.node_kind[und] != fv::kNodeVirtual)
+                continue;
+            const int f = mesh_.node_vj_face[und];
+            const double vol_ext = load_frac * ctx.nodes.qual_vol_in[und];
+            if (f >= 0 && vol_ext > 0.0 && bc_now_[i] > 0.0)
+                credit_mass(static_cast(f),
+                            static_cast(bc_srow_[i]),
+                            vol_ext * bc_now_[i]);
+        }
+    }
+
+    {
+        const int np_l = ctx.n_pollutants();
+        const auto unp_l = static_cast(np_l);
+        for (int nd = 0; nd < nn && nd < ctx.n_nodes(); ++nd) {
+            const auto und = static_cast(nd);
+            // Virtual junctions were credited to their spliced cells in 1a'.
+            if (und < mesh_.node_kind.size() &&
+                mesh_.node_kind[und] == fv::kNodeVirtual)
+                continue;
+            node_vol_[und] += load_frac * ctx.nodes.qual_vol_in[und];
+            for (int s = 0; s < np_l; ++s) {
+                // D-NS1 (X6): the old `max(0, ...)` silently DROPPED a
+                // negative load while the loaders had booked the full
+                // request — a silent ledger break. Extraction now applies
+                // signed, clamped to the store's mass, shortfall counted
+                // and un-booked. Positive loads take the identical value —
+                // bit-inert on every non-negative deck.
+                double delta =
+                    dt_sub * ctx.nodes.qual_mass_in[und * unp_l +
+                                                    static_cast(s)];
+                double& mstore =
+                    node_mass_[und * uns + static_cast(s)];
+                if (delta < 0.0 && mstore + delta < 0.0) {
+                    quality::bookNegativeSourceClamp(ctx, nd, s,
+                                                     -(mstore + delta));
+                    delta = -mstore;
+                }
+                mstore += delta;
+            }
+            // U2: species rows np..np+nm-1 take the [INFLOWS] species loads
+            // (msx_ext_mass_in, a rate; empty when no such row exists).
+            // Same signed-with-floor rule as the pollutant rows above, minus
+            // the ledger booking (species have no ledger row, L3).
+            if (nm_ > 0 && ctx.reactions.msx_ext_mass_in.size() >=
+                               static_cast(ctx.n_nodes()) *
+                                   static_cast(nm_)) {
+                for (int m = 0; m < nm_; ++m) {
+                    double delta = dt_sub * ctx.reactions.msx_ext_mass_in[
+                        und * static_cast(nm_) + static_cast(m)];
+                    double& mstore =
+                        node_mass_[und * uns + static_cast(np_l + m)];
+                    if (delta < 0.0 && mstore + delta < 0.0) delta = -mstore;
+                    mstore += delta;
+                }
+            }
+            // Persistent user quality mass flux is NOT added here: it is
+            // folded into qual_mass_in by QualitySolver::addExtInflowLoads(),
+            // the same loader stage legacy uses, so the line above already
+            // carries it. Adding it a second time here would double the mass.
+            //
+            // A1a: age-volume load — a RATE like qual_mass_in (the loaders
+            // add q · age_source per pathway), so it integrates over dt_sub.
+            if (age_row_ >= 0 &&
+                und < ctx.water_age_state.node_age_vol_in.size())
+                node_mass_[und * uns + static_cast(age_row_)] +=
+                    dt_sub * ctx.water_age_state.node_age_vol_in[und];
+            // H4: the heat channel is the same shape (degC·ft3/s), filled at
+            // the same seven loader pathways per D-UT10, so it integrates
+            // over the substep identically.
+            if (temp_row_ >= 0 &&
+                und < ctx.heat_state.node_temp_vol_in.size())
+                node_mass_[und * uns + static_cast(temp_row_)] +=
+                    dt_sub * ctx.heat_state.node_temp_vol_in[und];
+        }
+    }
+
+    // 1b(ii). E5a transport boundaries ride the SAME external inflow water
+    //     stage 1b just credited (the qual_vol_in the pollutant loaders
+    //     integrated), each boundary species at its current concentration —
+    //     internal store mass is conc·ft³, so vol·conc needs no conversion.
+    //     Rows on dry-inflow nodes add nothing (vol_ext = 0).
+    //
+    //     This must stay beside the volume it rides on. It used to run
+    //     after the outflow faces, which was consistent while the volume
+    //     did too; once the volume moved ahead of the donor read and this
+    //     did not, each substep read a store holding the boundary WATER but
+    //     not yet its MASS. The donor came out diluted, less left than
+    //     arrived, and the store climbed past the boundary value it was
+    //     supposed to hold — 8.0128 against a boundary of 8.0.
+    for (std::size_t i = 0; i < bc_node_.size(); ++i) {
+        const auto und = static_cast(bc_node_[i]);
+        if (static_cast(und) >= nn) continue;
+        if (und < mesh_.node_kind.size() &&
+            mesh_.node_kind[und] == fv::kNodeVirtual)
+            continue;   // routed to the spliced cells in 1a'
+        const double vol_ext = load_frac * ctx.nodes.qual_vol_in[und];
+        if (vol_ext > 0.0 && bc_now_[i] > 0.0)
+            node_mass_[und * uns + static_cast(bc_srow_[i])] +=
+                vol_ext * bc_now_[i];
+    }
+
+    // 1c. Face INFLOWS are mixed in before the donor is read, for the same
+    //     reason the external loads are (stage 1b) — a store must mix what
+    //     arrives this substep before it decides what leaves. Applying the
+    //     inflow afterwards made the store a forward-Euler CSTR, and a
+    //     junction's own volume is far smaller than what passes through it:
+    //     at ROUTING_STEP 20 on a plain 5 cfs chain the store's residence
+    //     time is 3.2 s against a 20 s step, so dt*q/V = 6.25 — an explicit
+    //     integration run at six times its stability bound. It oscillated
+    //     and diverged, compounding link by link (C1 exact, C2 3-4x, C3
+    //     8-12x) and manufacturing mass wherever the floor at zero clipped
+    //     the negative half of the oscillation.
+    //
+    //     Mixing first makes the donor a weighted AVERAGE of what the store
+    //     held and what just arrived, so it can never exceed the larger of
+    //     the two: the maximum principle holds at any step size, with no
+    //     extra substeps. It also cannot drive the store negative — the
+    //     outflow demand dt*Qout*M/(V0 + Qin*dt) stays below M whenever
+    //     Qin >= Qout, which is every junction that is not draining its own
+    //     storage; the floors below still cover the ones that are.
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const int b = mesh_.node_face_ptr[und];
+        const int e = mesh_.node_face_ptr[und + 1];
+        for (int p = b; p < e; ++p) {
+            const auto uf = static_cast(
+                mesh_.node_face_idx[static_cast(p)]);
+            const double sign = mesh_.node_face_sign[static_cast(p)];
+            const double fq = face_q_[uf];
+            if (sign * fq <= 0.0) continue;   // into the CELL — stage 4
+            node_vol_[und] += dt_sub * sign * fq;
+            for (int s = 0; s < ns; ++s)
+                node_mass_[und * uns + static_cast(s)] +=
+                    dt_sub * sign *
+                    f_phi_flux_[static_cast(s) * unf + uf];
+        }
+    }
+
+    // 2. Node boundary faces: replace the kernels' zero-gradient ghost with
+    //    the node store as the inflow donor (fixes the FV plan's "no node
+    //    concentration" gap for this engine). Outflow (cell → node) keeps
+    //    the cell donor value the kernels already assembled.
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const int b = mesh_.node_face_ptr[und];
+        const int e = mesh_.node_face_ptr[und + 1];
+        for (int p = b; p < e; ++p) {
+            const auto uf = static_cast(
+                mesh_.node_face_idx[static_cast(p)]);
+            const double sign = mesh_.node_face_sign[static_cast(p)];
+            const double fq = face_q_[uf];
+            // Flux INTO the node when sign*fq > 0; into the CELL otherwise.
+            if (sign * fq < 0.0) {
+                // An empty store has no concentration to donate. Dividing the
+                // residual mass by a 1e-12 floor instead handed the receiving
+                // cell an astronomical donor value, and on a storm deck under
+                // FV that injection ran away (outfall load ~1e25). Below the
+                // store threshold the donor contributes nothing, which is both
+                // stable and what "the node holds no water" means.
+                const double vol = node_vol_[und];
+                // OUTFALL_BACKFLOW_QUALITY ZERO: an outfall donating into
+                // the network is a fresh boundary — it contributes water
+                // but no mass and no age (same rule as the LEGACY and LARD
+                // solvers' held-state sites). Its store keeps the mass that
+                // arrived; the flag guarantees that mass never re-enters.
+                const bool fresh_outfall =
+                    ctx.options.outfall_backflow_zero &&
+                    ctx.nodes.type[und] == NodeType::OUTFALL;
+                for (int s = 0; s < ns; ++s) {
+                    const double cnode =
+                        (!fresh_outfall && vol > kMinStoreVol)
+                            ? node_mass_[und * uns +
+                                         static_cast(s)] / vol
+                            : 0.0;
+                    f_phi_flux_[static_cast(s) * unf + uf] =
+                        fq * cnode;
+                }
+            }
+        }
+    }
+
+    // 3. Cell update: species mass and area from the SAME fluxes.
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        const int faces[2]    = {mesh_.cell_face0[uc], mesh_.cell_face1[uc]};
+        const int8_t sides[2] = {mesh_.cell_side0[uc], mesh_.cell_side1[uc]};
+        const double inv_dx = 1.0 / mesh_.cell_dx[uc];
+        double dA = 0.0;
+        for (int e2 = 0; e2 < 2; ++e2) {
+            const auto uf = static_cast(faces[e2]);
+            const double sg = (sides[e2] == 0) ? -1.0 : 1.0;
+            dA += sg * f_mass_[uf];
+        }
+        const double a_old = state_.cell_a[uc];
+        double a_new = std::max(0.0, a_old + dt_sub * dA * inv_dx);
+        // Virtual-junction lateral water (1a') enters as a zero-momentum
+        // area source before the divide, so it dilutes the species exactly
+        // as the hydraulic solver's cell_qlat_ split does.
+        if (has_vj_src_)
+            a_new = std::max(0.0, a_new + cell_src_vol_[uc] * inv_dx);
+        for (int s = 0; s < ns; ++s) {
+            const auto sb = static_cast(s);
+            double dm = 0.0;
+            for (int e2 = 0; e2 < 2; ++e2) {
+                const auto uf = static_cast(faces[e2]);
+                const double sg = (sides[e2] == 0) ? -1.0 : 1.0;
+                dm += sg * f_phi_flux_[sb * unf + uf];
+            }
+            double m = a_old * state_.cell_phi[sb * unc + uc] +
+                       dt_sub * dm * inv_dx;
+            if (has_vj_src_) m += cell_src_mass_[sb * unc + uc] * inv_dx;
+            // Debt 216: the temperature row is EXEMPT from the
+            // non-negativity floor (its zero is 0 °C, an ordinary state —
+            // H7b's LARD row made the same call) but CLAMPED to the
+            // parser's own band instead: see kTempFloorC. Every genuine
+            // species row keeps the floor.
+            const double m_f = (s == temp_row_)
+                ? std::clamp(m, kTempFloorC * a_new, kTempCeilC * a_new)
+                : std::max(0.0, m);
+            state_.cell_phi[sb * unc + uc] =
+                (a_new > k::kDryArea) ? m_f / a_new
+                                      : state_.cell_phi[sb * unc + uc];
+        }
+        state_.cell_a[uc] = a_new;
+    }
+
+    // 4. Node stores: the OUTFLOW half of the face exchange. Inflow faces
+    //    (stage 1c) and external loads (stage 1b) were mixed in before the
+    //    donor concentration was read, so only the debit is left here.
+    for (int nd = 0; nd < nn && nd < ctx.n_nodes(); ++nd) {
+        const auto und = static_cast(nd);
+        const int b = mesh_.node_face_ptr[und];
+        const int e = mesh_.node_face_ptr[und + 1];
+        double dvol = 0.0;
+        for (int p = b; p < e; ++p) {
+            const auto uf = static_cast(
+                mesh_.node_face_idx[static_cast(p)]);
+            const double sign = mesh_.node_face_sign[static_cast(p)];
+            const double fq = face_q_[uf];
+            if (sign * fq > 0.0) continue;   // into the NODE — stage 1c
+            dvol += sign * fq;
+            for (int s = 0; s < ns; ++s) {
+                node_mass_[und * uns + static_cast(s)] +=
+                    dt_sub * sign *
+                    f_phi_flux_[static_cast(s) * unf + uf];
+            }
+        }
+        // Volume after the outflow faces. The inflows and the external load
+        // were already credited, so this floor now only catches a store the
+        // outflow genuinely drained — it is no longer sitting between the
+        // debit and the credit, where it silently ate the difference.
+        node_vol_[und] = std::max(0.0, node_vol_[und] + dt_sub * dvol);
+        // The non-negativity floor is a property of a STORE, not of a
+        // pollutant, so it runs over every row — including the MSX rows the
+        // load loop above deliberately skips. Narrowing this clamp along
+        // with the load stride left MSX store masses unfloored: a node that
+        // repeatedly empties (the junction just upstream of an outfall)
+        // accumulated a large oscillating NEGATIVE mass, which the node
+        // boundary-face override then donated into the first cell of the
+        // adjoining conduit. Symptom was a 0.67 mg/L divergence confined to
+        // the outfall-adjacent conduit's MSX rows while every pollutant row
+        // stayed bit-identical.
+        for (int s = 0; s < ns; ++s) {
+            auto& ms = node_mass_[und * uns + static_cast(s)];
+            if (s == temp_row_) {
+                // debt 216 — the cell loop's band clamp, store edition.
+                const double v = node_vol_[und];
+                ms = std::clamp(ms, kTempFloorC * v, kTempCeilC * v);
+            } else {
+                ms = std::max(0.0, ms);
+            }
+        }
+    }
+
+    // 5. Structures (E2): pumps/orifices/weirs/outlets are zero-volume
+    //    passthrough elements (plan §2.1 element coverage; same table as
+    //    LARD §2). Water the hydraulic solver moves through a structure
+    //    carries the DONOR node store's concentration; both stores update
+    //    volume and mass symmetrically. Donor below the store-empty
+    //    threshold moves water but no mass (consistent with the boundary
+    //    donor guard above). Mass is capped at what the donor holds so a
+    //    large q*dt_sub cannot go negative.
+    const int n_struct = static_cast(mesh_.struct_link.size());
+    for (int i = 0; i < n_struct; ++i) {
+        const auto ui = static_cast(i);
+        const int link = mesh_.struct_link[ui];
+        if (link < 0 || link >= ctx.n_links()) continue;
+        const double q = ctx.links.flow[static_cast(link)];
+        if (q == 0.0) continue;
+        const int donor_n    = (q >= 0.0) ? mesh_.struct_n1[ui] : mesh_.struct_n2[ui];
+        const int receiver_n = (q >= 0.0) ? mesh_.struct_n2[ui] : mesh_.struct_n1[ui];
+        if (donor_n < 0 || receiver_n < 0 || donor_n >= nn || receiver_n >= nn)
+            continue;
+        const auto ud = static_cast(donor_n);
+        const auto ur = static_cast(receiver_n);
+        const double dv = std::fabs(q) * dt_sub;
+        const double donor_vol = node_vol_[ud];
+        if (donor_vol > kMinStoreVol) {
+            for (int s = 0; s < ns; ++s) {
+                const auto sb = static_cast(s);
+                const double c_donor = node_mass_[ud * uns + sb] / donor_vol;
+                const double dm = std::min(dv * c_donor,
+                                           node_mass_[ud * uns + sb]);
+                node_mass_[ud * uns + sb] -= dm;
+                node_mass_[ur * uns + sb] += dm;
+            }
+        }
+        node_vol_[ud] = std::max(0.0, node_vol_[ud] - dv);
+        node_vol_[ur] += dv;
+    }
+
+    // 5c. E5a distributed sources: internal rate r (conc·ft³/s) spread over
+    //     the conduit's cells ∝ dx ⇒ Δconc per cell = r·dt/(L·a) — dx
+    //     cancels. Dry cells are skipped and their share is NOT delivered
+    //     (a source into a dry conduit has no water to dissolve into);
+    //     documented, and the mass-balance ledger (E5b) will book the
+    //     undelivered remainder explicitly.
+    for (std::size_t i = 0; i < src_crow_.size(); ++i) {
+        const double r = src_now_[i];
+        // P1.4: was `r <= 0.0`, which skipped extraction rows. Zero is still
+        // nothing to do; a negative rate is now extraction (D-NS1).
+        if (r == 0.0) continue;
+        const auto ucrow = static_cast(src_crow_[i]);
+        const int b2 = mesh_.conduit_cell_begin[ucrow];
+        const int n2 = mesh_.conduit_cell_count[ucrow];
+        const auto sb = static_cast(src_srow_[i]);
+        double shortfall = 0.0;   // unmet extraction, internal mass units
+        for (int i2 = 0; i2 < n2; ++i2) {
+            const auto uc = static_cast(b2 + i2);
+            const double a = state_.cell_a[uc];
+            if (a <= k::kDryArea) continue;
+            // Identical arithmetic to the pre-P1.4 form for a POSITIVE r —
+            // same operations in the same order — so positive-source decks
+            // stay bit-identical. Only the negative branch is new.
+            double  dphi = dt_sub * r / (src_len_[i] * a);
+            double& phi  = state_.cell_phi[sb * unc + uc];
+            if (dphi < 0.0 && phi + dphi < 0.0) {
+                // Clamp to what THIS cell holds. The deficit is per-cell
+                // because the source's share is distributed ∝ dx, so a
+                // conduit whose cells are unevenly loaded can clamp in one
+                // cell while another still has mass to give.
+                shortfall += -(phi + dphi) * a * mesh_.cell_dx[uc];
+                dphi = -phi;
+            }
+            phi += dphi;
+        }
+        if (shortfall > 0.0)
+            quality::bookNegativeCellSourceClamp(ctx, src_crow_[i],
+                                                 shortfall);
+    }
+
+    // 6. Dispersion (E3): implicit per-chain Thomas solve over the updated
+    //    cells — sequential (Lie) operator split, advection → dispersion
+    //    (plan §2). One full step of each, so the splitting error is O(dt),
+    //    not the O(dt²) a symmetric Strang split would give; the substep is
+    //    already Courant-limited by advection, and the dispersion half is
+    //    unconditionally stable, so the first-order split is the cheap
+    //    choice rather than an accuracy claim. Symmetrizing it is an E5
+    //    option, not a defect. The kernel
+    //    early-outs when v.cell_dispersion is null (disp_active_ false), so
+    //    the pre-E3 substep is bit-identical. Node stores do not disperse:
+    //    the solve spans conduit chains (including splice virtual
+    //    junctions), matching the FV solver's D-FV1 behavior; junction
+    //    mixing remains the CSTR exchange above.
+    fvk::dispersionSolve(v, dt_sub);
+}
+
+// ===========================================================================
+// step
+// ===========================================================================
+
+void ArdEngine::step(SimulationContext& ctx, double dt) {
+    if (!initialized_ || dt <= 0.0) return;
+
+    // conc_old bookkeeping matches the legacy engine's convention.
+    ctx.links.conc_old = ctx.links.conc;
+    ctx.nodes.conc_old = ctx.nodes.conc;
+
+    projectHydraulics(ctx, dt);
+    if (disp_active_) updateDispersion(ctx);
+    if (!bc_node_.empty() || !src_crow_.empty()) updateTransportRows(ctx);
+
+    // Node volumes resync to the solver's each routing step (the store keeps
+    // its own between substeps only).
+    const int ns  = state_.n_species;
+    const int nn  = std::min(ctx.n_nodes(),
+                             static_cast(node_vol_.size()));
+    const auto uns = static_cast(ns);
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const double v_old = node_vol_[und];
+        const double v_new = node::storeVolume(ctx.nodes, nd);   // see initialize
+
+        // Water that leaves the SYSTEM — outfall discharge, flooding — rides no
+        // mesh face, so the store never saw it go. Preserving mass across the
+        // resync (as this did) left every boundary node accumulating mass it
+        // could not shed while its volume snapped back toward zero, and
+        // conc = mass/vol diverged: an outfall manufactured mass quadratically
+        // in time. A well-mixed store discharges at its OWN concentration, so
+        // the mass follows the water down. Scale DOWN only: a store whose
+        // volume the solver reports as larger has gained water the store did
+        // not track, and scaling up would create mass from nothing.
+        // Except within kResyncNoiseRel: scaling down but never up turns
+        // zero-mean solver jitter into one-way dilution (a steady 100 mg/L
+        // arrived 2.5e-5 short), so inside the band concentration is kept.
+        if (v_old > kMinStoreVol) {
+            const double ratio = v_new / v_old;
+            if (ratio < 1.0 || ratio - 1.0 <= kResyncNoiseRel)
+                for (int s = 0; s < ns; ++s)
+                    node_mass_[und * uns + static_cast(s)] *= ratio;
+        } else if (v_new <= kMinStoreVol) {
+            for (int s = 0; s < ns; ++s)
+                node_mass_[und * uns + static_cast(s)] = 0.0;
+        }
+        node_vol_[und] = v_new;
+    }
+
+    // CFL subcycling on the projected velocities.
+    double dt_cfl = dt;
+    const int nc = mesh_.n_cells();
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        const double u = std::fabs(cell_u_[uc]);
+        if (u > 1.0e-12)
+            dt_cfl = std::min(dt_cfl, kCfl * mesh_.cell_dx[uc] / u);
+    }
+    int nsub = static_cast(std::ceil(dt / std::max(dt_cfl, 1.0e-12)));
+    if (nsub > kMaxSubsteps) {
+        // E2 (validation note 5.3): the clamp must be LOUD — a silently
+        // clamped run violates CFL and the max principle can leak. Warn once
+        // per run with the achieved ratio so the user can shorten
+        // ROUTING_STEP or coarsen FV_CELL_LENGTH.
+        if (!warned_cfl_clamp_) {
+            warned_cfl_clamp_ = true;
+            ctx.warnings.push_back(
+                "QUALITY_SOLVER EULERIAN_ARD: transport subcycling clamped at " +
+                std::to_string(kMaxSubsteps) + " substeps (needed " +
+                std::to_string(nsub) +
+                ") — effective CFL exceeds the stability target; shorten "
+                "ROUTING_STEP or increase FV_CELL_LENGTH.");
+        }
+        nsub = kMaxSubsteps;
+    }
+    const double dt_sub = dt / static_cast(nsub);
+    const double load_frac = 1.0 / static_cast(nsub);
+
+    for (int i = 0; i < nsub; ++i) substep(ctx, dt_sub, load_frac);
+
+    // A1a: aging — the exact integral of d(age)/dt = 1 over the routing
+    // step. Cells carry age as a concentration-like mean (+= dt); stores
+    // carry age-VOLUME (mass += dt·vol keeps the mean advancing by dt at
+    // constant volume). Lie-split like every other stage.
+    if (age_row_ >= 0) {
+        const auto ar  = static_cast(age_row_);
+        const auto unc0 = static_cast(mesh_.n_cells());
+        for (std::size_t c = 0; c < unc0; ++c)
+            state_.cell_phi[ar * unc0 + c] += dt;
+        const auto uns0 = static_cast(state_.n_species);
+        for (std::size_t nd2 = 0; nd2 < node_vol_.size(); ++nd2)
+            node_mass_[nd2 * uns0 + ar] += dt * node_vol_[nd2];
+    }
+
+    // H4: surface heat fluxes, the same Lie-split slot aging occupies —
+    // this is plan §1's `Sum(J)/Y - (Je + Jc)/Y` source term, applied PER
+    // CELL rather than per link, which is the whole point of binding heat
+    // to the mesh instead of leaving it on the LEGACY mirror.
+    applyHeatFluxes(ctx, dt);
+
+    // E4: reaction stage over the full routing step, Lie-split after the
+    // advection–dispersion subcycle (roadmap lesson 13 — first-order
+    // splitting, documented; the integrator substeps adaptively inside):
+    // exact-exponential kdecay on pollutant rows + MSX integration per cell
+    // (pipe scope) and per node store (tank scope).
+    transport::reactArdStage(
+        ctx, dt, state_.cell_phi.data(), state_.cell_a.data(),
+        mesh_.cell_dx.data(), mesh_.n_cells(), node_mass_.data(),
+        node_vol_.data(), static_cast(node_vol_.size()),
+        ctx.n_pollutants(), state_.n_species, kMinStoreVol, temp_row_);
+
+    // H6b-ARD: bed/channel SOLUTE exchange, per cell, in the same Lie-split
+    // slot as the other source stages — after reactions so the bed sees the
+    // reacted concentrations (the LEGACY ordering: the bed runs last).
+    applyBedSoluteExchange(ctx, dt);
+
+    publish(ctx);
+
+    // E5b: per-cell sidecar rows (every routing step — see the header note).
+    if (detail_active_) {
+        detail_time_s_ += dt;
+        writeDetailRows(ctx);
+    }
+}
+
+// ===========================================================================
+// absorbTreatedNodeConc — E5b treatment interop (see the header)
+// ===========================================================================
+
+void ArdEngine::absorbTreatedNodeConc(SimulationContext& ctx) {
+    if (!initialized_) return;
+    const int np = ctx.n_pollutants();
+    if (np <= 0 || !ctx.treatment.hasAny()) return;
+    const int ns = state_.n_species;
+    const auto uns = static_cast(ns);
+    const auto unp = static_cast(np);
+    const int nn = std::min(ctx.n_nodes(),
+                            static_cast(node_vol_.size()));
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        if (!ctx.treatment.has_treatment[und]) continue;
+        const double vol = node_vol_[und];
+        if (vol <= kMinStoreVol) continue;
+        for (int p = 0; p < np; ++p)
+            node_mass_[und * uns + static_cast(p)] =
+                ctx.nodes.conc[und * unp + static_cast(p)] * vol;
+    }
+}
+
+// ===========================================================================
+// writeDetailRows — E5b per-cell CSV sidecar
+// ===========================================================================
+
+void ArdEngine::writeDetailRows(SimulationContext& ctx) {
+    const int ns  = state_.n_species;
+    const int np  = ctx.n_pollutants();
+    const auto unc = static_cast(mesh_.n_cells());
+    const auto uns = static_cast(ns);
+    const auto species_name = [&](int s) -> std::string {
+        if (s == age_row_)  return "__WATER_AGE__";
+        if (s == temp_row_) return "__TEMPERATURE__";
+        return (s < np)
+                   ? std::string(ctx.pollutant_names.name_of(s))
+                   : ctx.reactions.species_name[static_cast(s - np)];
+    };
+    for (int r = 0; r < static_cast(mesh_.conduit_link.size()); ++r) {
+        const auto ur = static_cast(r);
+        const int link = mesh_.conduit_link[ur];
+        if (link < 0 || link >= ctx.n_links()) continue;
+        const std::string& lname =
+            ctx.link_names.names()[static_cast(link)];
+        const int b = mesh_.conduit_cell_begin[ur];
+        const int n = mesh_.conduit_cell_count[ur];
+        for (int i = 0; i < n; ++i) {
+            const auto uc = static_cast(b + i);
+            for (int s = 0; s < ns; ++s)
+                detail_out_ << detail_time_s_ << ',' << lname << ",L," << i
+                            << ',' << species_name(s) << ','
+                            << state_.cell_phi[static_cast(s) *
+                                                   unc + uc]
+                            << '\n';
+        }
+    }
+    const int nn = std::min(ctx.n_nodes(),
+                            static_cast(node_vol_.size()));
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const double vol = node_vol_[und];
+        const std::string& nname = ctx.node_names.names()[und];
+        for (int s = 0; s < ns; ++s) {
+            const double c =
+                (vol > kMinStoreVol)
+                    ? node_mass_[und * uns + static_cast(s)] / vol
+                    : 0.0;
+            detail_out_ << detail_time_s_ << ',' << nname << ",N,0,"
+                        << species_name(s) << ',' << c << '\n';
+        }
+    }
+}
+
+// ===========================================================================
+// applyHeatFluxes — H4: per-cell surface exchange on the transport mesh
+// ===========================================================================
+
+/// @details The LEGACY mirror applies H2/H3's fluxes once per LINK, on a
+///          single lumped temperature. On the mesh a conduit is many cells
+///          with their own temperatures, so the flux is evaluated per cell
+///          against that cell's own state — which is what makes an advected
+///          thermal wave possible at all, and is the reason plan §6 H4 asks
+///          for the ARD binding rather than treating it as a refinement.
+///
+///          Free surface per cell: `top width(depth) x cell_dx`. The area
+///          identity with the LEGACY path is deliberate — evaporation, H2
+///          and H3 all use `top width x length`; here `length` is the cell's
+///          share of it. Gated on `FvGeometry::is_open` exactly as the
+///          LEGACY path gates on `xsect::isOpen`, which also sidesteps the
+///          Preissmann slot: a closed conduit never exchanges, so the slot
+///          width can never be mistaken for a free surface.
+///
+///          Node STORES take the same treatment as under LEGACY: only
+///          storage nodes have a free surface (`kNodeStorage`), and their
+///          state is a mass, so the flux converts to a mass change.
+// ---------------------------------------------------------------------------
+// applyBedSoluteExchange — H6b-ARD: per-cell transient-storage exchange
+// ---------------------------------------------------------------------------
+int ArdEngine::cellLink(std::size_t cell) const noexcept {
+    if (cell >= mesh_.cell_conduit.size()) return -1;
+    const int cr = mesh_.cell_conduit[cell];
+    if (cr < 0 ||
+        static_cast(cr) >= mesh_.conduit_link.size())
+        return -1;
+    return mesh_.conduit_link[static_cast(cr)];
+}
+
+void ArdEngine::applyBedSoluteExchange(SimulationContext& ctx, double dt) {
+    if (!heat::bedExchangeEnabled(ctx) || !(dt > 0.0)) return;
+
+    // Exchanged rows are pollutants + MSX — everything BEFORE the reserved
+    // age/temperature rows, which are last by construction (init()). Age
+    // does not live in the bed (the reference carries no bed age) and
+    // temperature has its own pair inside applyHeatFluxes.
+    int n_exch = state_.n_species;
+    if (age_row_  >= 0) --n_exch;
+    if (temp_row_ >= 0) --n_exch;
+    if (n_exch <= 0) return;
+
+    auto& bed = ctx.bed_state;
+    const int ncells = mesh_.n_cells();
+    if (bed.cell_temp.size() != static_cast(ncells) ||
+        bed.cell_n_species != n_exch) {
+        // Solutes seed at ZERO (BedExchange.cpp's reasoning); the
+        // temperature seed is preserved when only the species extent grows.
+        const auto& sd = ctx.heat_config.sediment;
+        const double t_keep =
+            (bed.cell_temp.size() == static_cast(ncells) &&
+             !bed.cell_temp.empty())
+                ? bed.cell_temp[0]
+                : (sd.has_initial_temp ? sd.initial_temp : sd.ground_temp);
+        std::vector keep_temp;
+        if (bed.cell_temp.size() == static_cast(ncells))
+            keep_temp = bed.cell_temp;
+        bed.resizeCells(ncells, n_exch, t_keep);
+        if (!keep_temp.empty()) bed.cell_temp = std::move(keep_temp);
+    }
+
+    constexpr double kSqFtToSqM = 0.09290304;
+    constexpr double kCuFtToCuM = 0.028316846592;
+    const auto unc = static_cast(ncells);
+    const auto une = static_cast(n_exch);
+
+    for (std::size_t c = 0; c < unc; ++c) {
+        const auto gi = static_cast(mesh_.cell_geom[c]);
+        if (gi >= mesh_.geom.size()) continue;
+        const auto& g = mesh_.geom[gi];
+        const double area_x = state_.cell_a[c];
+        if (!(area_x > 0.0)) continue;
+        const double vol_ft3 = area_x * mesh_.cell_dx[c];
+        if (!(vol_ft3 > 0.0)) continue;
+        const double h = fv::kernels::depthOfArea(g, area_x);
+        if (!(h > 0.0)) continue;
+        const double rh = fv::kernels::hydRadOfDepth(g, h);
+        if (!(rh > 0.0)) continue;
+        const double bed_m2 =
+            (area_x / rh) * mesh_.cell_dx[c] * kSqFtToSqM;
+
+        // PE2: the parent link's bed material (cells resolve to their link,
+        // D-PE1), so the ARD bed and the LEGACY/LARD beds read one config.
+        const auto& sd_c = heat::sedimentFor(
+            ctx, HeatElement::link(cellLink(c)));
+        const double vol_w  = vol_ft3 * kCuFtToCuM;
+        const double vol_b  = bed_m2 * sd_c.bed_thickness;
+        const double q_exch = heat::bedExchangeQ(sd_c, bed_m2);
+        if (!(q_exch > 0.0) || !(vol_b > 0.0)) continue;
+
+        for (std::size_t sp = 0; sp < une; ++sp) {
+            double& cw = state_.cell_phi[sp * unc + c];
+            double& cb = bed.cell_conc[sp * unc + c];
+            const heat::SolutePairStep st =
+                heat::exchangePair(cw, cb, vol_w, vol_b, q_exch, dt);
+            cw += st.dc_w;
+            cb += st.dc_b;
+        }
+    }
+}
+
+void ArdEngine::applyHeatFluxes(SimulationContext& ctx, double dt) {
+    if (temp_row_ < 0 || !(dt > 0.0)) return;
+    const bool bed_on = heat::bedExchangeEnabled(ctx);
+    const bool any = ctx.heat_config.surface_exchange ||
+                     ctx.heat_config.radiative_exchange || bed_on;
+    if (!any) return;
+
+    // H6b-ARD: per-CELL bed slices, 1:1 — the reference's own element
+    // mapping (BedZoneData.hpp). Seeded once, at the bed's configured
+    // initial temperature, NOT the water's (BedExchange.cpp's reasoning).
+    double t_gr = 0.0;
+    if (bed_on) {
+        auto& bed = ctx.bed_state;
+        const int ncells = mesh_.n_cells();
+        if (bed.cell_temp.size() != static_cast(ncells) ||
+            !bed.cells_seeded) {
+            const auto& sd = ctx.heat_config.sediment;
+            bed.resizeCells(ncells, bed.cell_n_species,
+                            sd.has_initial_temp ? sd.initial_temp
+                                                : sd.ground_temp);
+        }
+        t_gr = heat::groundTemperature(ctx);
+    }
+
+    // H6a: resolve this step's Jin and cloud fraction before any flux call.
+    // Each of the four bindings does this in its own prologue — they run on
+    // two different clocks, so no single upstream call site covers all of
+    // them (SolarRadiation.hpp).
+    heat::updateSolarForcing(ctx);
+
+    constexpr double kSqFtToSqM = 0.09290304;
+    constexpr double kCuFtToCuM = 0.028316846592;
+
+    const double rho = ctx.options.water_density;
+    const double cp  = ctx.options.water_specific_heat;
+
+    // The met forcing and wind-function coefficients that used to be
+    // extracted here moved inside the shared evaluators with D-H5e; this
+    // function no longer needs to know which parameters a flux family reads.
+
+    /// Net flux OUT of the water, W/m2. Delegates to the shared
+    /// composition (D-H5e) rather than re-summing the modules here: a
+    /// hand-rolled copy is how the LEGACY node/link path came to relax each
+    /// module separately, and a fifth flux family must not need editing in
+    /// four places.
+    // PE1: a CELL resolves to its PARENT LINK for attribute lookup (D-PE1).
+    // Cells deliberately do not get their own attribute row: shading does
+    // not vary within one conduit in any data a modeller can supply, and a
+    // per-cell table would be one nothing could fill.
+    const auto flux_out = [&](const HeatElement& e, double t_w) {
+        return heat::netFluxOut(ctx, e, t_w);
+    };
+
+    // ---- Cells ----------------------------------------------------------
+    const auto tr  = static_cast(temp_row_);
+    const auto unc = static_cast(mesh_.n_cells());
+    for (std::size_t c = 0; c < unc; ++c) {
+        const auto gi = static_cast(mesh_.cell_geom[c]);
+        if (gi >= mesh_.geom.size()) continue;
+        const auto& g = mesh_.geom[gi];
+        const double area_x = state_.cell_a[c];
+        if (!(area_x > 0.0)) continue;
+        const double vol_ft3 = area_x * mesh_.cell_dx[c];
+        if (!(vol_ft3 > 0.0)) continue;
+
+        const double h = fv::kernels::depthOfArea(g, area_x);
+        if (!(h > 0.0)) continue;
+
+        // H6b-ARD: a CLOSED cell has no free surface but it does have a
+        // bed, so `is_open` gates the surface AREA rather than the whole
+        // iteration — the same restructure the LEGACY link loop took, for
+        // the same full-pipe reason.
+        double surf_m2 = 0.0;
+        if (g.is_open) {
+            const double width = fv::kernels::widthOfDepth(g, h);
+            if (width > 0.0)
+                surf_m2 = width * mesh_.cell_dx[c] * kSqFtToSqM;
+        }
+
+        const double t_w = state_.cell_phi[tr * unc + c];
+        const HeatElement ce = HeatElement::link(cellLink(c));
+
+        // H6b-ARD: the bed is a second body — the pair is relaxed
+        // SIMULTANEOUSLY, never sequentially (D-H5e; BedExchange.hpp).
+        // Contact area per cell: wetted perimeter x dx = (A/R) x dx, with
+        // barrels already inside `area_x` via barrel_scale and R identical
+        // per barrel, so A_total/R = n x per-barrel perimeter, exactly the
+        // link derivation one level up.
+        if (bed_on && c < ctx.bed_state.cell_temp.size()) {
+            const double rh = fv::kernels::hydRadOfDepth(g, h);
+            const double bed_m2 = (rh > 0.0)
+                ? (area_x / rh) * mesh_.cell_dx[c] * kSqFtToSqM
+                : 0.0;
+            // PE2: the parent link's bed attributes and boundary.
+            const auto& sd_c = heat::sedimentFor(ctx, ce);
+            const heat::BedCoupling bc = heat::bedCouplingFromContact(
+                ctx, sd_c, bed_m2, vol_ft3,
+                heat::groundTempFor(ctx, sd_c, t_gr));
+            if (bc.viable()) {
+                const heat::PairStep ps = heat::relaxPair(
+                    bc, t_w, ctx.bed_state.cell_temp[c], flux_out(ce, t_w),
+                    flux_out(ce, t_w + heat::kProbeC), heat::kProbeC,
+                    surf_m2, dt);
+                state_.cell_phi[tr * unc + c] += ps.dt_w;
+                ctx.bed_state.cell_temp[c]   += ps.dt_b;
+                continue;
+            }
+        }
+        if (!(surf_m2 > 0.0)) continue;
+
+        // D-H5d's integrator, not forward Euler. This site shipped as the
+        // explicit step `-J·A·dt/(ρ cp V)` while the plan's §6.3 recorded it
+        // as already correct — the SUMMING was correct (both modules through
+        // netFluxOut), the STEPPING was not, and a draining cell's thin film
+        // is exactly the regime whose k·dt explodes the explicit form
+        // (SurfaceExchange.hpp). Found while reading for H6b (§3 of its
+        // handoff); fixed here with the same relaxT the other bindings use.
+        state_.cell_phi[tr * unc + c] += heat::relaxT(
+            flux_out(ce, t_w), flux_out(ce, t_w + heat::kProbeC),
+            heat::kProbeC, surf_m2, vol_ft3 * kCuFtToCuM, dt, rho, cp);
+    }
+
+    // ---- Node stores ----------------------------------------------------
+    const int unit_sys =
+        ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+    const auto uns = static_cast(state_.n_species);
+    const int nn = std::min(ctx.n_nodes(),
+                            static_cast(node_vol_.size()));
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const double vol_ft3 = node_vol_[und];
+        if (!(vol_ft3 > 0.0)) continue;
+        const double area_ft2 = node::getSurfArea(
+            ctx.nodes, nd, ctx.nodes.depth[und], &ctx.tables, unit_sys,
+            &ctx.node_subtypes);
+        if (!(area_ft2 > 0.0)) continue;       // junctions have none
+
+        const double t_w = node_mass_[und * uns + tr] / vol_ft3;
+        const HeatElement ne = HeatElement::node(nd);
+        // relaxT, same as the cell loop above — the node stores had the same
+        // explicit step and the same thin-volume failure mode.
+        const double dT = heat::relaxT(
+            flux_out(ne, t_w), flux_out(ne, t_w + heat::kProbeC),
+            heat::kProbeC, area_ft2 * kSqFtToSqM, vol_ft3 * kCuFtToCuM,
+            dt, rho, cp);
+        // The store carries MASS (conc x volume), so a temperature
+        // change of dT is a mass change of dT x volume.
+        node_mass_[und * uns + tr] += dT * vol_ft3;
+    }
+}
+
+// ===========================================================================
+// publish — cell state → legacy link/node arrays
+// ===========================================================================
+
+void ArdEngine::publish(SimulationContext& ctx) {
+    const int ns = state_.n_species;
+    const int np = ctx.n_pollutants();
+    const int na = (age_row_ >= 0) ? 1 : 0;
+    const int nt = (temp_row_ >= 0) ? 1 : 0;
+    // MSX rows (0 when no reactions component). BOTH reserved rows must be
+    // subtracted: with only `- na`, a heat deck would report one MSX row too
+    // many and the else-branches below would index msx_*_conc out of range.
+    const int nm = ns - np - na - nt;
+    const auto uns = static_cast(ns);
+    const auto unp = static_cast(np);
+    const auto unm = static_cast(nm > 0 ? nm : 0);
+    const auto unc = static_cast(mesh_.n_cells());
+
+    // E4/R6: MSX rows publish into the R4 element-state arrays
+    // ([element * nm + m]) so reporting and the C API read one place under
+    // either engine. Sized here (NOT via the legacy binding's ensure, whose
+    // R4b warning does not apply — species ARE transported under ARD).
+    auto& rx = ctx.reactions;
+    if (nm > 0) {
+        const auto want_l = static_cast(ctx.n_links()) * unm;
+        const auto want_n = static_cast(ctx.n_nodes()) * unm;
+        if (rx.msx_link_conc.size() != want_l)
+            rx.msx_link_conc.assign(want_l, 0.0);
+        if (rx.msx_node_conc.size() != want_n)
+            rx.msx_node_conc.assign(want_n, 0.0);
+    }
+
+    for (int r = 0; r < static_cast(mesh_.conduit_link.size()); ++r) {
+        const auto ur = static_cast(r);
+        const int link = mesh_.conduit_link[ur];
+        if (link < 0 || link >= ctx.n_links()) continue;
+        const int b = mesh_.conduit_cell_begin[ur];
+        const int n = mesh_.conduit_cell_count[ur];
+        for (int s = 0; s < ns; ++s) {
+            const auto sb = static_cast(s);
+            double m = 0.0, vol = 0.0;
+            for (int i = 0; i < n; ++i) {
+                const auto uc = static_cast(b + i);
+                const double dv = state_.cell_a[uc] * mesh_.cell_dx[uc];
+                m   += dv * state_.cell_phi[sb * unc + uc];
+                vol += dv;
+            }
+            const double conc = (vol > 1.0e-12) ? m / vol : 0.0;
+            if (s == age_row_) {
+                if (static_cast(link) <
+                    ctx.water_age_state.link_age.size())
+                    ctx.water_age_state.link_age[static_cast(
+                        link)] = conc;
+            } else if (s == temp_row_) {
+                // H4: temperature publishes into heat_state, which is where
+                // the snapshot builder reads it from REGARDLESS of engine —
+                // so the .out column is fed by whichever engine is active.
+                // Without this branch the row would fall through to the MSX
+                // else and write past msx_link_conc.
+                //
+                // Below legacy's ZeroVolume the quotient is residue over
+                // residue (a draining conduit published 6e+117 degC from
+                // exactly this line) — HOLD the last real reading instead,
+                // which is H1's carried-temperature convention for dry
+                // elements and what the LEGACY engine does on this deck.
+                if (static_cast(link) <
+                        ctx.heat_state.link_temp.size() &&
+                    vol > kZeroVolumeFt3)
+                    ctx.heat_state.link_temp[static_cast(link)] =
+                        conc;
+            } else if (s < np) {
+                ctx.links.conc[static_cast(link) * unp + sb] =
+                    conc;
+            } else {
+                rx.msx_link_conc[static_cast(link) * unm +
+                                 static_cast(s - np)] = conc;
+            }
+        }
+    }
+
+    const int nn = std::min(ctx.n_nodes(),
+                            static_cast(node_vol_.size()));
+    for (int nd = 0; nd < nn; ++nd) {
+        const auto und = static_cast(nd);
+        const double vol = node_vol_[und];
+        for (int s = 0; s < ns; ++s) {
+            const double conc =
+                (vol > 1.0e-12)
+                    ? node_mass_[und * uns + static_cast(s)] / vol
+                    : 0.0;
+            if (s == age_row_) {
+                if (und < ctx.water_age_state.node_age.size())
+                    ctx.water_age_state.node_age[und] = conc;
+            } else if (s == temp_row_) {
+                // The link loop's ZeroVolume hold, node-store edition — the
+                // same deck read 2.8e+36 degC at an outfall store here.
+                if (und < ctx.heat_state.node_temp.size() &&
+                    vol > kZeroVolumeFt3)
+                    ctx.heat_state.node_temp[und] = conc;
+            } else if (s < np) {
+                ctx.nodes.conc[und * unp + static_cast(s)] = conc;
+            } else {
+                rx.msx_node_conc[und * unm +
+                                 static_cast(s - np)] = conc;
+            }
+        }
+    }
+
+    // Structure links (E2) report the donor node's published concentration —
+    // the zero-volume passthrough convention (matches legacy, which sets a
+    // structure's quality from its upstream node). E4/R6: MSX rows too.
+    const int n_struct = static_cast(mesh_.struct_link.size());
+    for (int i = 0; i < n_struct; ++i) {
+        const auto ui = static_cast(i);
+        const int link = mesh_.struct_link[ui];
+        if (link < 0 || link >= ctx.n_links()) continue;
+        const double q = ctx.links.flow[static_cast(link)];
+        const int donor_n = (q >= 0.0) ? mesh_.struct_n1[ui] : mesh_.struct_n2[ui];
+        if (donor_n < 0 || donor_n >= nn) continue;
+        const auto ud = static_cast(donor_n);
+        for (int s = 0; s < np; ++s)
+            ctx.links.conc[static_cast(link) * unp +
+                           static_cast(s)] =
+                ctx.nodes.conc[ud * unp + static_cast(s)];
+        for (int m2 = 0; m2 < nm; ++m2)
+            rx.msx_link_conc[static_cast(link) * unm +
+                             static_cast(m2)] =
+                rx.msx_node_conc[ud * unm + static_cast(m2)];
+        if (age_row_ >= 0 &&
+            static_cast(link) <
+                ctx.water_age_state.link_age.size() &&
+            ud < ctx.water_age_state.node_age.size())
+            ctx.water_age_state.link_age[static_cast(link)] =
+                ctx.water_age_state.node_age[ud];
+        // H4: a regulator carries its donor node's temperature for the same
+        // reason it carries its age — it stores nothing, so there is no
+        // mixed value of its own.
+        if (temp_row_ >= 0 &&
+            static_cast(link) < ctx.heat_state.link_temp.size() &&
+            ud < ctx.heat_state.node_temp.size())
+            ctx.heat_state.link_temp[static_cast(link)] =
+                ctx.heat_state.node_temp[ud];
+    }
+}
+
+// ===========================================================================
+// totalMass — conservation ledger for the unit gates
+// ===========================================================================
+
+std::vector ArdEngine::totalMass(const SimulationContext& ctx) const {
+    (void)ctx;
+    const int ns = state_.n_species;
+    const auto uns = static_cast(ns);
+    const auto unc = static_cast(mesh_.n_cells());
+    std::vector total(uns, 0.0);
+    for (int s = 0; s < ns; ++s) {
+        const auto sb = static_cast(s);
+        double m = 0.0;
+        for (std::size_t c = 0; c < unc; ++c)
+            m += state_.cell_a[c] * mesh_.cell_dx[c] * state_.cell_phi[sb * unc + c];
+        for (std::size_t nd = 0; nd < node_vol_.size(); ++nd)
+            m += node_mass_[nd * uns + sb];
+        total[sb] = m;
+    }
+    return total;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/EulerianArdComponent/ArdEngine.hpp b/src/engine/transport/components/EulerianArdComponent/ArdEngine.hpp
new file mode 100644
index 000000000..2e3bc7c02
--- /dev/null
+++ b/src/engine/transport/components/EulerianArdComponent/ArdEngine.hpp
@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ArdEngine.hpp
+ * @brief Solver-agnostic Eulerian ARD transport engine (phase E1).
+ *
+ * @details Selected by `[OPTIONS] QUALITY_SOLVER EULERIAN_ARD`
+ *          (plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md rev. 2). Runs the
+ *          promoted FV species kernels (transport/fvkernels) on the
+ *          NetworkMeshBuilder cell mesh under ANY hydraulic routing model:
+ *          link/node hydraulics are projected onto the cells each routing
+ *          step with continuity-consistent face fluxes (§3.2 of the plan),
+ *          species advect with sign-of-flux upwinding + MUSCL/QUICKEST
+ *          reconstruction + Zalesak FCT, junctions mix as CSTRs fed by the
+ *          same face fluxes, and results publish back into the legacy
+ *          links.conc / nodes.conc arrays so reporting is unchanged.
+ *
+ *          Scope as of E4/R6 (see the validation handoffs): conservative
+ *          transport with structures (pumps/orifices/weirs/outlets) as
+ *          zero-volume passthrough of the donor node store, persistent
+ *          user quality-mass-flux forcing, longitudinal dispersion
+ *          (per-conduit user coefficients and/or Fischer et al. 1979 via
+ *          the transport.ard component, E3) sequentially split after
+ *          advection each substep, and REACTIONS (E4/R6, Lie-split per
+ *          routing step): exact-exponential kdecay plus MSX species
+ *          integration per cell (pipe scope) and node store (tank scope)
+ *          through the shared reaction module. MSX species are TRANSPORTED
+ *          on the mesh under this engine — the state carries pollutant
+ *          rows first (np-aligned) then the MSX rows; the R4b
+ *          element-local limitation is LEGACY-only. WALL species fall
+ *          back to LEGACY with a warning.
+ *
+ *          Treatment interop, sources/BCs and the mass-balance ledger rows
+ *          LANDED with E5a (`cbb9d321`) and E5b (`721ae60c`) — this comment
+ *          listed all three as pending until 2026-08-25, five rounds after
+ *          the fact, and a program-state audit read it as authoritative.
+ *
+ *          Genuinely still pending: direct consumption of the FV solver's
+ *          own cell state instead of the projection (E2b); storage mixing
+ *          models beyond CMSTR (E2b, shared with LARD); tidal reverse-flow
+ *          boundary concentration (E2b, no scaffolding at all).
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_ARD_ENGINE_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_ARD_ENGINE_HPP
+
+#include 
+#include 
+#include 
+
+#include "../../../hydraulics/fv/FvKernels.hpp"
+#include "../../../hydraulics/fv/NetworkMeshData.hpp"
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+class ArdEngine {
+public:
+    /**
+     * @brief Build the transport mesh and size all state; call once after the
+     *        model is fully resolved (Router::init done, pollutants known).
+     * @return false if the mesh could not be built — the caller must fall
+     *         back to the legacy quality path and surface the warnings.
+     */
+    bool init(SimulationContext& ctx);
+
+    /**
+     * @brief One transport step over the routing step dt.
+     *
+     * @details Pre-condition: the external quality loads for this step have
+     *          been assembled into nodes.qual_mass_in / qual_vol_in (the
+     *          QualitySolver loader stage). Post-condition: links.conc,
+     *          links.conc_old, nodes.conc, nodes.conc_old updated.
+     */
+    void step(SimulationContext& ctx, double dt);
+
+    bool initialized() const noexcept { return initialized_; }
+    const std::vector& warnings() const noexcept { return warnings_; }
+
+    /**
+     * @brief E5b treatment interop: absorb treated node concentrations back
+     *        into the node stores.
+     *
+     * @details Called by SWMMEngine AFTER QualitySolver::applyTreatment ran
+     *          on the PUBLISHED nodes.conc. Only nodes with treatment
+     *          defined are touched — untreated nodes keep their store mass
+     *          bit-identical (a conc→mass→conc round trip is NOT exact in
+     *          floating point, so a blanket absorb would break the
+     *          no-treatment parity).
+     */
+    void absorbTreatedNodeConc(SimulationContext& ctx);
+
+    /// Total species mass currently held (cells + node stores), one entry per
+    /// species — the conservation ledger the unit gates check.
+    std::vector totalMass(const SimulationContext& ctx) const;
+
+private:
+    // Continuity-consistent face fluxes from the link/node fields of the
+    // current routing step (plan §3.2): within each conduit the face flux
+    // ramps linearly so every cell receives an equal share of the conduit's
+    // volume change, and the two end faces carry the flux the node exchange
+    // actually saw. Splice faces (virtual junctions) take the mean of the
+    // two conduits' end values.
+    void projectHydraulics(SimulationContext& ctx, double dt);
+
+    // One advection substep of length dt_sub: kernel reconstruction + FCT on
+    // interior faces, donor-upwinded node boundary fluxes, cell mass/area
+    // update, node CSTR update (external loads prorated by dt_sub / dt_step),
+    // then the implicit dispersion solve over the updated cells (E3,
+    // sequential Lie split: one full advection step, then one full
+    // dispersion step — NOT Strang, which would halve the advection).
+    void substep(SimulationContext& ctx, double dt_sub, double load_frac);
+
+    // E3: refresh cell_disp_ from the routing step's hydraulics. Per-conduit
+    // overrides always win; otherwise VALUE mode broadcasts the global
+    // coefficient and FISCHER mode evaluates D = 0.011 v²B²/(Y·U*),
+    // U* = √(g·Y·S) from the link fields (all internal ft units).
+    void updateDispersion(SimulationContext& ctx);
+
+    void publish(SimulationContext& ctx);
+
+    fv::NetworkMeshData  mesh_;
+    fv::NetworkStateData state_;
+
+    // Projected per-face volumetric flux for the current routing step and the
+    // per-cell start-of-step areas it is consistent with.
+    std::vector face_q_;
+
+    // Node stores: species mass [node * ns + s] and water volume the mass
+    // sits in (tracked from the same fluxes, so node concentration is
+    // self-consistent between substeps).
+    std::vector node_mass_;
+    std::vector node_vol_;
+
+    // Lateral loads at VIRTUAL junctions (plans/VJ_LATERAL_INFLOW_PLAN_
+    // 2026-09-04.md §E4). A virtual junction owns no faces — its conduits
+    // were spliced into one interior face — so a node store there could
+    // never discharge and the per-step resync zeroed it: the load was
+    // destroyed. Its water and mass go straight into the two cells adjoining
+    // the splice, half each, mirroring the hydraulic solver's cell_qlat_
+    // split. Rebuilt every substep; has_vj_src_ gates the whole path so a
+    // deck without a fed virtual junction executes no new arithmetic.
+    std::vector cell_src_vol_;    ///< water (ft³) per cell this substep
+    std::vector cell_src_mass_;   ///< [s * nc + c] mass per cell this substep
+    bool has_vj_src_ = false;
+
+    // Kernel scratch (sized once in init; see SpeciesKernelView).
+    std::vector f_mass_, f_sstar_, f_phi_l_, f_phi_r_, f_phi_flux_,
+        cell_slope_, lo_flux_, anti_flux_, td_, anew_, rplus_, rminus_, cell_u_;
+    std::vector f_state_l_, f_state_r_;
+    std::vector  f_flux_;
+    std::vector cell_active_;
+    std::vector  active_faces_;
+
+    // E5a: transport boundaries/sources resolved onto the mesh at init.
+    // Boundaries: the node's external inflow water carries the species at
+    // bc_now_ (evaluated once per routing step: VALUE or timeseries).
+    // Sources: internal-rate mass distributed over the conduit's wet cells.
+    void updateTransportRows(SimulationContext& ctx);
+    std::vector    bc_node_, bc_srow_, bc_ts_;
+    std::vector bc_value_, bc_now_;
+    std::vector    src_crow_, src_srow_, src_ts_;
+    std::vector src_value_, src_len_, src_now_;
+
+    // E3 dispersion state. disp_active_ gates the whole path: when false the
+    // substep passes no per-cell array and dispersionSolve early-outs — the
+    // pre-E3 behavior, bit-identical for existing ARD decks.
+    bool disp_active_ = false;
+    int  disp_mode_   = 0;      ///< ArdDispersionMode as int (OFF/FISCHER/VALUE)
+    double disp_global_ft_ = 0.0;   ///< VALUE-mode coefficient, ft²/s
+    std::vector conduit_disp_ft_;  ///< per mesh-conduit override, ft²/s (<0 ⇒ none)
+    std::vector cell_disp_;        ///< per-cell D handed to the kernel
+
+    // E5b: per-cell CSV sidecar ([TRANSPORT_OPTIONS] DETAILED_OUTPUT).
+    // Written every routing step (documented decision — a detail feature
+    // for short diagnostic runs; cadence control can come later if sizes
+    // demand it). Columns: time_s, element, kind (L link cell / N node
+    // store), cell index, species name, concentration.
+    void writeDetailRows(SimulationContext& ctx);
+    std::ofstream detail_out_;
+    bool   detail_active_ = false;
+    double detail_time_s_ = 0.0;
+
+    /// A1a: state row of the reserved __WATER_AGE__ species (after
+    /// pollutants and MSX); -1 when WATER_AGE is off.
+    int age_row_ = -1;
+
+    /// U2: MSX species rows carried on the mesh (rows np .. np+nm_-1); the
+    /// [INFLOWS] species loads (ReactionData::msx_ext_mass_in) land there.
+    int nm_ = 0;
+
+    /// H4: per-cell surface heat exchange (plan §1's source term), the
+    /// mesh twin of the LEGACY mirror's whole-link application.
+    void applyHeatFluxes(SimulationContext& ctx, double dt);
+
+    /// H6b-ARD: per-cell bed/channel solute exchange (pollutant + MSX rows;
+    /// the reserved age/temperature rows are excluded by construction).
+    void applyBedSoluteExchange(SimulationContext& ctx, double dt);
+
+    /// PE1: the LinkData index a cell belongs to, or -1. Cells resolve to
+    /// their parent link for per-element attribute lookup (D-PE1); -1 makes
+    /// the accessors fall back to the global, which is the safe answer for a
+    /// cell whose conduit row cannot be resolved.
+    int cellLink(std::size_t cell) const noexcept;
+
+    /// H4: state row of the reserved __TEMPERATURE__ species — the LAST
+    /// row, after age, matching the REPORTED column order fixed in H1 so a
+    /// deck that adds heat to an age model does not move the age column.
+    /// -1 when HEAT_TRANSPORT is off.
+    int temp_row_ = -1;
+
+    std::vector warnings_;
+    bool initialized_ = false;
+    bool warned_cfl_clamp_ = false;  ///< E2: once-per-run loud subcycle clamp
+};
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_ARD_ENGINE_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/BedExchange.cpp b/src/engine/transport/components/HeatFluxModules/BedExchange.cpp
new file mode 100644
index 000000000..b302b424c
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/BedExchange.cpp
@@ -0,0 +1,378 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file BedExchange.cpp
+ * @brief Plan H6b — implementation. See BedExchange.hpp for the derivation.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "BedExchange.hpp"
+
+#include 
+#include 
+
+#include "HeatOverrides.hpp"   // sedimentFor — PE2
+#include "SurfaceExchange.hpp"
+#include "../../../core/SimulationContext.hpp"
+#include "../../../data/TableData.hpp"
+#include "../../../hydraulics/XSectBatch.hpp"
+#include "../../../hydraulics/Link.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+/// phi1(z) = expm1(z)/z, with the removable singularity taken.
+double phi1(double z) noexcept {
+    if (std::fabs(z) < 1e-8) return 1.0 + 0.5 * z;   // series, exact to 1e-16
+    return std::expm1(z) / z;
+}
+
+/// phi2(z) = (e^z - 1 - z)/z^2, with the removable singularity taken.
+/// Used only on the near-degenerate branch, where the spectral formula's
+/// 1/(lambda1 - lambda2) is not usable.
+double phi2(double z) noexcept {
+    if (std::fabs(z) < 1e-5) return 0.5 + z / 6.0;
+    return (std::expm1(z) - z) / (z * z);
+}
+
+/// Cross-section parameters for a link. The same shape `HeatFluxes.cpp`
+/// builds; kept local rather than exported because widening that file's
+/// helper to a public seam is a bigger change than repeating ten field
+/// copies, and CLAUDE.md §3 says touch only what must be touched.
+XSectParams buildXsp(const LinkData& links, std::size_t uk) {
+    XSectParams xs{};
+    const auto ls = links.xsect_shape[uk];
+    xs.type   = link::translateShape(ls);
+    xs.y_full = links.xsect_y_full[uk];
+    xs.a_full = links.xsect_a_full[uk];
+    xs.w_max  = links.xsect_w_max[uk];
+    xs.r_full = links.xsect_r_full[uk];
+    xs.s_full = links.xsect_s_full[uk];
+    xs.s_max  = links.xsect_s_max[uk];
+    xs.y_bot  = links.xsect_y_bot[uk];
+    xs.a_bot  = links.xsect_a_bot[uk];
+    xs.s_bot  = links.xsect_s_bot[uk];
+    xs.r_bot  = links.xsect_r_bot[uk];
+    return xs;
+}
+
+}  // namespace
+
+// ---------------------------------------------------------------------------
+// The coupled stepper
+// ---------------------------------------------------------------------------
+PairStep relaxPair(const BedCoupling& g, double t_w, double t_b,
+                   double j0, double j1, double h, double area_m2,
+                   double dt) noexcept {
+    PairStep out{};
+    if (!g.viable() || !(dt > 0.0)) return out;
+
+    // Surface flux slope, W/m²/°C. `h <= 0` or a non-increasing flux means
+    // there is no usable linearization; treat the surface term as a constant
+    // forcing, which is exactly `relaxT`'s own fallback and keeps the two
+    // functions agreeing about when the probe is trusted.
+    double djdt = 0.0;
+    if (h > 0.0) {
+        const double s = (j1 - j0) / h;
+        if (s > 0.0 && std::isfinite(s)) djdt = s;
+    }
+
+    // du/dt = M u + c, u = (T_w - t_w, T_b - t_b), u(0) = 0.
+    const double a11 = -(area_m2 * djdt + g.g_wb) / g.c_w;
+    const double a12 = g.g_wb / g.c_w;
+    const double a21 = g.g_wb / g.c_b;
+    const double a22 = -(g.g_wb + g.g_bg) / g.c_b;
+
+    const double c1 = (-area_m2 * j0 + g.g_wb * (t_b - t_w)) / g.c_w;
+    const double c2 = (g.g_wb * (t_w - t_b) + g.g_bg * (g.t_gr - t_b)) / g.c_b;
+
+    // Eigenvalues. The discriminant is (a11-a22)^2 + 4*a12*a21 with both
+    // off-diagonals >= 0, so it is never negative: the pair relaxes, it never
+    // oscillates, and there is no dt at which this overshoots.
+    const double tr   = a11 + a22;
+    const double diff = a11 - a22;
+    const double disc = diff * diff + 4.0 * a12 * a21;
+    const double s    = std::sqrt(disc > 0.0 ? disc : 0.0);
+
+    // phi1(M*dt) = alpha*M + beta*I, by the spectral formula for a 2x2.
+    double alpha = 0.0, beta = 0.0;
+    if (s * dt > 1e-8) {
+        const double l1 = 0.5 * (tr + s);
+        const double l2 = 0.5 * (tr - s);
+        const double p1 = phi1(l1 * dt);
+        const double p2 = phi1(l2 * dt);
+        alpha = (p1 - p2) / s;
+        beta  = (p2 * l1 - p1 * l2) / s;
+    } else {
+        // Near-degenerate: the spectral formula divides by s. The confluent
+        // form is the limit and needs no division —
+        //   phi1(M dt) = phi1(l dt) I + dt phi2(l dt) (M - l I),
+        // and since phi1(z) = 1 + z phi2(z) identically, the identity
+        // coefficient collapses to exactly 1.
+        const double l = 0.5 * tr;
+        alpha = dt * phi2(l * dt);
+        beta  = 1.0;
+    }
+
+    // u = dt * phi1(M dt) * c = dt * (alpha * M c + beta * c)
+    const double mc1 = a11 * c1 + a12 * c2;
+    const double mc2 = a21 * c1 + a22 * c2;
+    const double dw  = dt * (alpha * mc1 + beta * c1);
+    const double db  = dt * (alpha * mc2 + beta * c2);
+
+    // A non-finite result means the linearization produced something the
+    // caller must not absorb. Refusing to move is the safe answer and the
+    // one `relaxT` also takes.
+    if (!std::isfinite(dw) || !std::isfinite(db)) return out;
+    out.dt_w = dw;
+    out.dt_b = db;
+    return out;
+}
+
+SolutePairStep exchangePair(double c_w, double c_b, double vol_w,
+                            double vol_b, double q_exch, double dt) noexcept {
+    SolutePairStep out{};
+    if (!(vol_w > 0.0) || !(vol_b > 0.0) || !(q_exch > 0.0) || !(dt > 0.0))
+        return out;
+
+    // Two bodies exchanging with nothing else: total mass is invariant and
+    // the DIFFERENCE decays exponentially. Solving in those coordinates
+    // makes conservation STRUCTURAL — there is no separate ledger step that
+    // could be forgotten. It is not bit-exact, because `vol_w*(vol_b*share)`
+    // and `vol_b*(vol_w*share)` associate differently; the residual is
+    // relative round-off and the gate asserts that bound. See the header.
+    const double vt = vol_w + vol_b;
+    const double mu = q_exch * vt / (vol_w * vol_b);   // 1/s
+    const double d0 = c_w - c_b;
+    const double dd = d0 * std::expm1(-mu * dt);       // d(t) - d0
+
+    const double share = dd / vt;
+    if (!std::isfinite(share)) return out;
+    out.dc_w =  vol_b * share;
+    out.dc_b = -vol_w * share;
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration and geometry
+// ---------------------------------------------------------------------------
+bool bedExchangeEnabled(const SimulationContext& ctx) noexcept {
+    return ctx.options.heat_transport && ctx.heat_config.sediment_exchange;
+}
+
+double groundTemperature(SimulationContext& ctx) noexcept {
+    const auto& sc = ctx.heat_config.sediment;
+    if (sc.ground_ts_index >= 0 &&
+        sc.ground_ts_index < static_cast(ctx.tables.count()))
+        return table_tseries_lookup_cursor(ctx.tables[sc.ground_ts_index],
+                                           ctx.current_date);
+    return sc.ground_temp;
+}
+
+double linkBedAreaM2(const SimulationContext& ctx, int link) noexcept {
+    const auto uj = static_cast(link);
+    const int  cr = ctx.link_subtypes.conduit_row(link);
+    if (cr < 0) return 0.0;                  // regulators have no bed
+    const auto ucr = static_cast(cr);
+    const auto& CD = ctx.link_subtypes.conduits;
+
+    double length = CD.length[ucr];
+    if (!(length > 0.0)) length = CD.mod_length[ucr];
+    if (!(length > 0.0)) return 0.0;
+
+    const double depth = ctx.links.depth[uj];
+    if (!(depth > 0.0)) return 0.0;
+
+    // Contact area = wetted perimeter x length x barrels. P = A/R, the
+    // engine's own identity — NOT the reference's top width, which is zero
+    // for a full pipe. See BedZoneData.hpp divergence 1.
+    const auto   xs   = buildXsp(ctx.links, uj);
+    const double area = xsect::getAofY(xs, depth);
+    const double rhyd = xsect::getRofY(xs, depth);
+    if (!(area > 0.0) || !(rhyd > 0.0)) return 0.0;
+    const double perim_ft = area / rhyd;
+
+    const double m2 =
+        perim_ft * length * static_cast(CD.barrels[ucr]) * kSqFtToSqM;
+    return (m2 > 0.0) ? m2 : 0.0;
+}
+
+double linkFreeSurfaceFt2(const SimulationContext& ctx, int link) noexcept {
+    const auto uj = static_cast(link);
+    const int  cr = ctx.link_subtypes.conduit_row(link);
+    if (cr < 0) return 0.0;
+    if (!xsect::isOpen(ctx.links.xsect_batch_shape[uj])) return 0.0;
+    const auto ucr = static_cast(cr);
+    const auto& CD = ctx.link_subtypes.conduits;
+
+    double length = CD.length[ucr];
+    if (!(length > 0.0)) length = CD.mod_length[ucr];
+    const double depth = ctx.links.depth[uj];
+    if (!(length > 0.0) || !(depth > 0.0)) return 0.0;
+    const auto xs = buildXsp(ctx.links, uj);
+    const double top_width = xsect::getWofY(xs, depth);
+    if (!(top_width > 0.0)) return 0.0;
+    return top_width * length * static_cast(CD.barrels[ucr]);
+}
+
+double bedExchangeQ(const SedimentConfig& cfg, double bed_m2) noexcept {
+    if (!(bed_m2 > 0.0) || !(cfg.bed_thickness > 0.0)) return 0.0;
+    return cfg.solute_diffusivity * bed_m2 / cfg.bed_thickness +
+           cfg.hyporheic_velocity * bed_m2;
+}
+
+double groundTempFor(const SimulationContext& ctx, const SedimentConfig& sc,
+                     double t_gr_global) noexcept {
+    // The TIMESERIES spelling is GLOBAL-only by grammar, so when one is
+    // configured it IS the boundary everywhere; otherwise each element's
+    // resolved constant is (per-element rows included, and identical to the
+    // global on a model with none).
+    return (ctx.heat_config.sediment.ground_ts_index >= 0) ? t_gr_global
+                                                           : sc.ground_temp;
+}
+
+BedCoupling bedCouplingFromContact(const SimulationContext& ctx,
+                                   const SedimentConfig& sc,
+                                   double bed_m2, double vol_ft3,
+                                   double t_gr) noexcept {
+    BedCoupling g{};
+    if (!(bed_m2 > 0.0) || !(vol_ft3 > 0.0)) return g;
+
+    const double rho_cp_s = sc.sed_density * sc.sed_specific_heat;  // J/m3/K
+    const double y_bed    = sc.bed_thickness;
+    const double y_gr     = sc.ground_depth;
+    if (!(y_bed > 0.0)) return g;
+
+    // Conduction: alpha * rho_s * c_s has units W/m/K, so dividing by a
+    // length and multiplying by an area gives W/K. This is the reference's
+    // grouping (`element.cpp:132`) rather than a conductivity k, because
+    // alpha is the parameter the reference exposes and re-deriving k here
+    // would silently invent a second material description.
+    const double k_eff  = sc.thermal_diffusivity * rho_cp_s;        // W/m/K
+    const double g_cond = k_eff * bed_m2 / y_bed;
+    const double g_adv  = ctx.options.water_density *
+                          ctx.options.water_specific_heat *
+                          sc.hyporheic_velocity * bed_m2;           // W/K
+
+    g.g_wb = g_cond + g_adv;
+    g.g_bg = (y_gr > 0.0) ? (k_eff * bed_m2 / y_gr) : 0.0;
+    g.c_w  = ctx.options.water_density * ctx.options.water_specific_heat *
+             vol_ft3 * kCuFtToCuM;
+    g.c_b  = rho_cp_s * bed_m2 * y_bed;
+    g.t_gr = t_gr;
+    return g;
+}
+
+BedCoupling bedCouplingForLink(const SimulationContext& ctx, int link,
+                               double vol_ft3, double t_gr) noexcept {
+    if (!(vol_ft3 > 0.0)) return BedCoupling{};
+    // PE2: the link's own bed attributes. On a model with no overrides this
+    // is the very global object the pre-PE code read.
+    const SedimentConfig& sc = sedimentFor(ctx, HeatElement::link(link));
+    return bedCouplingFromContact(ctx, sc, linkBedAreaM2(ctx, link), vol_ft3,
+                                  groundTempFor(ctx, sc, t_gr));
+}
+
+// ---------------------------------------------------------------------------
+// Bindings
+// ---------------------------------------------------------------------------
+void seedBedTemperature(SimulationContext& ctx) {
+    auto& bed = ctx.bed_state;
+    const int nl = ctx.n_links();
+    const auto& sc = ctx.heat_config.sediment;
+    const double t0 = sc.has_initial_temp ? sc.initial_temp : sc.ground_temp;
+
+    // Temperature and solute extents are sized INDEPENDENTLY. A single
+    // `resize` would have to know the species count, and the heat binding
+    // runs first and does not — so a combined resize would either wipe the
+    // solute store on every heat step or force the heat step to guess a
+    // dimension that belongs to the transport engine.
+    if (!bed.sized(nl)) {
+        bed.link_temp.assign(
+            static_cast(nl > 0 ? nl : 0), t0);
+        bed.seeded = false;
+    }
+    if (!bed.seeded) {
+        // The bed starts at the configured initial temperature, falling back
+        // to the ground temperature — the only number in the configuration
+        // that describes the subsurface. It deliberately does NOT start at
+        // the water's INITIAL_STATE: a bed that starts at the channel
+        // temperature exchanges nothing for the first steps and would hide a
+        // mis-wired coupling behind a plausible flat line.
+        for (auto& t : bed.link_temp) t = t0;
+        bed.seeded = true;
+    }
+}
+
+void applyBedSoluteExchange(SimulationContext& ctx, double* link_conc,
+                            int n_arr, int offset, int n_total, double dt) {
+    if (!bedExchangeEnabled(ctx) || !(dt > 0.0) || link_conc == nullptr) return;
+    if (n_arr <= 0 || offset < 0 || n_total < offset + n_arr) return;
+    seedBedTemperature(ctx);
+
+    auto& bed = ctx.bed_state;
+    const int nl_all = ctx.n_links();
+    const auto need = static_cast(nl_all > 0 ? nl_all : 0) *
+                      static_cast(n_total);
+    if (bed.n_species != n_total || bed.link_conc.size() != need) {
+        // First solute step, or the species count changed. Seeding the bed
+        // at ZERO is the honest default: the reference has no initial-bed
+        // concentration input either, and inventing one would put mass into
+        // the system that no deck asked for.
+        bed.link_conc.assign(need, 0.0);
+        bed.n_species = n_total;
+    }
+
+    const int    nl = ctx.n_links();
+    const auto   na = static_cast(n_arr);
+    const auto   nt = static_cast(n_total);
+    const auto   off = static_cast(offset);
+
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        if (uj >= bed.link_temp.size()) break;
+
+        const double vol_ft3 = ctx.links.volume[uj];
+        if (!(vol_ft3 > 0.0)) continue;
+        const double bed_m2 = linkBedAreaM2(ctx, j);
+        if (!(bed_m2 > 0.0)) continue;
+
+        // PE2: this link's bed material — thickness and exchange rates may
+        // be overridden per element, and the solute store's volume must
+        // agree with the heat pair's about the same bed.
+        const SedimentConfig& sc = sedimentFor(ctx, HeatElement::link(j));
+        const double vol_w  = vol_ft3 * kCuFtToCuM;
+        const double vol_b  = bed_m2 * sc.bed_thickness;
+        const double q_exch = bedExchangeQ(sc, bed_m2);
+        if (!(q_exch > 0.0) || !(vol_b > 0.0)) continue;
+
+        for (std::size_t s = 0; s < na; ++s) {
+            double& cw = link_conc[uj * na + s];
+            double& cb = bed.link_conc[uj * nt + off + s];
+            const SolutePairStep st =
+                exchangePair(cw, cb, vol_w, vol_b, q_exch, dt);
+            cw += st.dc_w;
+            cb += st.dc_b;
+        }
+    }
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/BedExchange.hpp b/src/engine/transport/components/HeatFluxModules/BedExchange.hpp
new file mode 100644
index 000000000..1eee1fce6
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/BedExchange.hpp
@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file BedExchange.hpp
+ * @brief Plan H6b — bed conduction, deep-ground conduction, and hyporheic
+ *        exchange, integrated SIMULTANEOUSLY with the surface fluxes.
+ *
+ * @par Why this is not "one more term in netFluxOut"
+ *      `HeatFluxes.hpp` predicted that H6b would be exactly that. It cannot
+ *      be, for two independent reasons, and both were found by trying:
+ *
+ *      1. **`netFluxOut` returns W/m² at the FREE SURFACE.** Bed exchange
+ *         acts on the wetted perimeter, which is a different area — and for
+ *         a closed conduit the free-surface area is zero while the bed area
+ *         is not. Summing them would multiply the bed flux by the wrong
+ *         area, and would switch it off entirely in a full pipe.
+ *      2. **The bed is a SECOND STATE VARIABLE.** `relaxT` relaxes one body
+ *         toward a fixed equilibrium. Two bodies exchanging with each other
+ *         do not have a fixed equilibrium to relax toward: each one's target
+ *         moves as the other responds. Treating the bed as a constant-
+ *         temperature reservoir inside `netFluxOut` would make a thin bed
+ *         behave like an infinite heat sink, which is the opposite of what a
+ *         thin bed does.
+ *
+ *      So H6b adds a coupled stepper rather than a term. **D-H5e's rule
+ *      still holds and is why the stepper is coupled rather than sequential**:
+ *      relaxations do not commute, so the surface families and the bed
+ *      exchange are solved in ONE step, not one after the other. Doing it
+ *      sequentially would reintroduce precisely the defect D-H5e removed,
+ *      one phase after it was removed.
+ *
+ * @par The system
+ *      With `J(T_w) ~ J0 + J'(T_w - T_w0)` linearized exactly as `relaxT`
+ *      already linearizes it:
+ *      @code
+ *      C_w dT_w/dt = -A_s J(T_w) + G_wb (T_b - T_w)
+ *      C_b dT_b/dt =  G_wb (T_w - T_b) + G_bg (T_gr - T_b)
+ *      @endcode
+ *      a 2x2 linear system `du/dt = M u + c` solved by its exact matrix
+ *      exponential, `u(dt) = dt * phi1(M dt) * c`, `phi1(z) = expm1(z)/z`.
+ *
+ *      Both eigenvalues of `M` are real and non-positive — the discriminant
+ *      is `(a11-a22)^2 + 4 a12 a21` with `a12, a21 >= 0`, so it can never be
+ *      negative and the pair can never oscillate. **The step therefore cannot
+ *      overshoot at any dt**, which is the property D-H5d bought for the
+ *      single body and which would have been lost by any explicit coupling.
+ *
+ * @par Conservation, and the gate that checks it
+ *      Adding the two equations, `G_wb` cancels identically:
+ *      `C_w dT_w/dt + C_b dT_b/dt = -A_s J + G_bg (T_gr - T_b)`.
+ *      Whatever the water loses to the bed, the bed gains. The exchange is
+ *      therefore conservative BY CONSTRUCTION, not by a bookkeeping step
+ *      that could be forgotten, and `BedExchangeConservesEnergy` asserts the
+ *      identity rather than a tolerance on a ledger.
+ *
+ * @par Solutes
+ *      The solute pair is the same system minus the surface flux and minus
+ *      the ground term — `HTSComponent` leaves its ground solute exchange
+ *      commented out (`element.cpp:161`) and parity keeps it out. Two bodies
+ *      exchanging with nothing else has a closed form that needs no matrix:
+ *      the total mass is invariant and the DIFFERENCE decays exponentially.
+ *      `exchangePair` uses that form, so conservation is STRUCTURAL — there
+ *      is no separate bookkeeping step that could be omitted.
+ *
+ *      It is **not bit-exact**, and the first draft of this file claimed it
+ *      was. `vol_w * dc_w` evaluates `vol_w * (vol_b * share)` while
+ *      `vol_b * dc_b` evaluates `vol_b * (vol_w * share)` — the same factors
+ *      in a different association, which round differently once `share`
+ *      saturates at large `dt`. The residual is relative round-off, ~1e-16,
+ *      and the gate asserts that bound rather than equality. Measured, not
+ *      assumed: a driver over `dt` in {1, 600, 7200, 1e6} agreed bit for bit
+ *      on the first three and differed on the fourth.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.3, §6.5 D-H6b
+ * @see HTSComponent/src/element.cpp:121-200 (the reference)
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_BED_EXCHANGE_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_BED_EXCHANGE_HPP
+
+#include "../../../data/BedZoneData.hpp"   // SedimentConfig (light header)
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport::heat {
+
+/**
+ * @brief One element's bed coupling, fully reduced to SI conductances.
+ *
+ * @details Everything geometric and material has already been folded in, so
+ *          `relaxPair` contains no unit conversion and no reference to
+ *          conduit shape. That separation is deliberate: the geometry is
+ *          what differs between the LEGACY link binding and the ARD mesh
+ *          binding, and the integration is what must not.
+ */
+struct BedCoupling {
+    double g_wb = 0.0;  ///< Water<->bed conductance, W/K (conduction + advection)
+    double g_bg = 0.0;  ///< Bed<->deep-ground conductance, W/K
+    double c_w  = 0.0;  ///< Water heat capacity, J/K
+    double c_b  = 0.0;  ///< Bed heat capacity, J/K
+    double t_gr = 0.0;  ///< Deep-ground temperature, °C
+
+    /// True when the pair is worth stepping at all.
+    bool viable() const noexcept { return c_w > 0.0 && c_b > 0.0; }
+};
+
+/// Simultaneous temperature increments for the coupled pair, °C.
+struct PairStep {
+    double dt_w = 0.0;  ///< Channel water
+    double dt_b = 0.0;  ///< Bed
+};
+
+/**
+ * @brief One exact step of the coupled (water, bed) pair.
+ *
+ * @param g       Conductances and capacities for this element.
+ * @param t_w     Current channel water temperature, °C.
+ * @param t_b     Current bed temperature, °C.
+ * @param j0      Net outward SURFACE flux at `t_w`, W/m² (`netFluxOut`).
+ * @param j1      The same flux at `t_w + h` — the probe `relaxT` already
+ *                takes, passed in rather than recomputed so the pair is
+ *                stepped against exactly the function the single body was.
+ * @param h       Probe offset, °C. `<= 0` disables the linearization and
+ *                takes `j0` as a constant forcing.
+ * @param area_m2 Free-surface area the surface flux acts on, m². May be 0
+ *                for a closed conduit — the bed terms still apply.
+ * @param dt      Step, seconds.
+ *
+ * @return Increments for both bodies. `{0,0}` when `g` is not viable.
+ *
+ * @note Reduces to `relaxT` when `g_wb == g_bg == 0`, to within 1-2 ULP —
+ *       the two take different but algebraically identical routes to the
+ *       same scalar, so the last bit can differ. Measured over `dt` in
+ *       {1, 60, 900, 86400}: 1 ULP at every step, well inside the 4 ULP
+ *       `EXPECT_DOUBLE_EQ` allows. **The reduction is what keeps pre-H6b
+ *       answers unchanged, and it holds only because the module is OFF by
+ *       default** — a deck without `SEDIMENT_EXCHANGE` never enters
+ *       `relaxPair` at all, so byte-identity is exact for the reason that
+ *       matters, not for this one.
+ */
+PairStep relaxPair(const BedCoupling& g, double t_w, double t_b,
+                   double j0, double j1, double h, double area_m2,
+                   double dt) noexcept;
+
+/// Simultaneous concentration increments for the coupled pair.
+struct SolutePairStep {
+    double dc_w = 0.0;  ///< Channel water
+    double dc_b = 0.0;  ///< Bed water
+};
+
+/**
+ * @brief One exact step of the two-body solute exchange.
+ *
+ * @param c_w     Channel concentration.
+ * @param c_b     Bed concentration.
+ * @param vol_w   Channel water volume, m³.
+ * @param vol_b   Bed water volume, m³ (bed volume x porosity is the honest
+ *                reading; the reference uses the bulk volume and so does
+ *                this, see the header note on porosity).
+ * @param q_exch  Total exchange discharge, m³/s: `D_sed*A/Y + v_hyp*A`.
+ * @param dt      Step, seconds.
+ *
+ * @return Increments satisfying `vol_w*dc_w + vol_b*dc_b == 0` to relative
+ *         round-off. See the header on why this is not bit-exact.
+ */
+SolutePairStep exchangePair(double c_w, double c_b, double vol_w,
+                            double vol_b, double q_exch, double dt) noexcept;
+
+/**
+ * @brief Bed conductances for link `j` from the deck configuration and the
+ *        link's current hydraulics.
+ *
+ * @details Contact area is the WETTED PERIMETER times length times barrels —
+ *          see `BedZoneData.hpp` divergence 1. Returns a non-viable coupling
+ *          (which `relaxPair` treats as a no-op) for a dry link, a
+ *          non-conduit, or a link whose perimeter cannot be formed.
+ */
+///          `t_gr` is passed in rather than resolved here because the
+///          TIMESERIES lookup is GLOBAL scope: one lookup per STEP, not one
+///          per link. That is `updateSolarForcing`'s pattern and the reason
+///          it exists. PE2: the link's own SedimentConfig (per-element
+///          overrides included) is resolved INSIDE, so every caller of the
+///          link form gets per-element bed attributes without threading them.
+BedCoupling bedCouplingForLink(const SimulationContext& ctx, int link,
+                               double vol_ft3, double t_gr) noexcept;
+
+/**
+ * @brief The material half of the coupling, geometry already folded in.
+ *
+ * @details Split out of `bedCouplingForLink` for the ARD binding: a CELL has
+ *          its own contact area and volume but the same material math, and a
+ *          second hand-written copy of that math is how the two engines'
+ *          beds would come to disagree about the same sediment. LEGACY and
+ *          LARD go through `bedCouplingForLink` (link geometry); ARD
+ *          computes its per-cell `bed_m2`/`vol_ft3` and calls this directly.
+ *
+ *          PE2: `sc` is the SedimentConfig in force for the element —
+ *          `sedimentFor(ctx, elem)`, or the global for a caller with no
+ *          element. The check found the handoff's draft resolving the
+ *          per-element table and never passing it to ANY bed reader: both
+ *          links of the per-tag gate cooled to the identical bit.
+ */
+BedCoupling bedCouplingFromContact(const SimulationContext& ctx,
+                                   const SedimentConfig& sc,
+                                   double bed_m2, double vol_ft3,
+                                   double t_gr) noexcept;
+
+/// PE2: the deep-ground temperature in force for ONE element. The global
+/// `GROUND_TEMPERATURE TIMESERIES` wins when configured — the TIMESERIES
+/// spelling is GLOBAL-only by grammar (per-element series are PE3/D-PE7) —
+/// otherwise the element's own resolved constant. For a model with no
+/// overrides `sc.ground_temp` IS the global constant, so this returns
+/// exactly what `groundTemperature` returned, by construction.
+double groundTempFor(const SimulationContext& ctx, const SedimentConfig& sc,
+                     double t_gr_global) noexcept;
+
+/// Total solute exchange discharge across a bed interface of `bed_m2`, m³/s:
+/// `D_sed·A/Y + v_hyp·A`. One spelling, used by every engine's solute loop.
+double bedExchangeQ(const SedimentConfig& cfg, double bed_m2) noexcept;
+
+/// Bed contact area for link `j`, m² — wetted perimeter × length × barrels
+/// (divergence 1). 0 for a dry link or a non-conduit.
+double linkBedAreaM2(const SimulationContext& ctx, int link) noexcept;
+
+/// Free-surface area for link `j`, ft² — top width × length × barrels for an
+/// OPEN conduit, 0 otherwise. The `Routing.cpp:597` evaporation-area
+/// expression, exported so the LARD binding does not grow a fourth copy of
+/// the XSectParams builder.
+double linkFreeSurfaceFt2(const SimulationContext& ctx, int link) noexcept;
+
+/// The deep-ground temperature in force this step, °C — resolves the
+/// `GROUND_TEMPERATURE TIMESERIES` spelling against the simulation clock.
+/// Non-const because the timeseries lookup advances the table's own cursor,
+/// exactly as `table_tseries_lookup_cursor` does everywhere else.
+double groundTemperature(SimulationContext& ctx) noexcept;
+
+/// True when `[HEAT_FLUXES] SEDIMENT_EXCHANGE` is on and heat transport is.
+bool bedExchangeEnabled(const SimulationContext& ctx) noexcept;
+
+/**
+ * @brief Size and seed the bed temperature array, idempotently.
+ *
+ * @details There is deliberately **no `applyBedHeatExchange`**. A function by
+ *          that name would be called beside `applyHeatFluxes` and would step
+ *          the bed in its own relaxation — which is D-H5e's defect, one phase
+ *          after D-H5e removed it. The heat coupling instead happens INSIDE
+ *          `applyHeatFluxes`'s link loop, which calls `relaxPair` with the
+ *          real `j0`/`j1`/area so the surface families and the bed are one
+ *          simultaneous step. This function is only the state setup that
+ *          loop needs first.
+ */
+void seedBedTemperature(SimulationContext& ctx);
+
+/**
+ * @brief Step every conduit's bed/channel solute exchange for one `dt`.
+ *
+ * @param link_conc  [link * n_arr + s] channel concentrations, updated in
+ *                   place. The caller owns the layout because the engines
+ *                   hold their channel state differently; what they share
+ *                   is this function and the bed array it moves mass into.
+ * @param n_arr      Species carried by `link_conc`.
+ * @param offset     Where `link_conc`'s rows start inside the bed store.
+ *                   The bed carries ONE species set — pollutants then MSX —
+ *                   and LEGACY holds those in two arrays (`links.conc`,
+ *                   `msx_link_conc`), so it calls twice: `(conc, np, 0)`
+ *                   and `(msx, nm, np)`. Splitting the bed store instead
+ *                   would give the two halves independent sizing paths and
+ *                   a seam where one resizes and the other does not.
+ * @param n_total    Total species the bed store carries (`np + nm`). Sizing
+ *                   is by `n_total`, so the two LEGACY calls agree about
+ *                   the store's shape by construction.
+ */
+void applyBedSoluteExchange(SimulationContext& ctx, double* link_conc,
+                            int n_arr, int offset, int n_total, double dt);
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_BED_EXCHANGE_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/HeatFluxes.cpp b/src/engine/transport/components/HeatFluxModules/HeatFluxes.cpp
new file mode 100644
index 000000000..daa5217e2
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/HeatFluxes.cpp
@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatFluxes.cpp
+ * @brief Plan D-H5e — the single node/link surface-flux binding.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatFluxes.hpp"
+
+#include 
+
+#include "BedExchange.hpp"
+#include "RadiativeExchange.hpp"
+#include "SolarRadiation.hpp"
+#include "SurfaceExchange.hpp"
+#include "../../../core/SimulationContext.hpp"
+#include "../../../core/UnitConversion.hpp"
+#include "../../../hydraulics/Node.hpp"
+#include "../../../hydraulics/XSectBatch.hpp"
+#include "../../../hydraulics/Link.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+/// Cross-section parameters for a link. Mirrors `Routing.cpp:54`'s local
+/// helper — the same one the non-DYNWAVE evaporation path uses, so an open
+/// conduit's exchange area is built exactly the way its evaporation area is.
+///
+/// D-H5e: there was one of these in SurfaceExchange.cpp and a hand-inlined
+/// near-copy in RadiativeExchange.cpp. Now there is one.
+XSectParams buildXsp(const LinkData& links, std::size_t uk) {
+    XSectParams xs{};
+    const auto ls = links.xsect_shape[uk];
+    xs.type   = link::translateShape(ls);
+    xs.y_full = links.xsect_y_full[uk];
+    xs.a_full = links.xsect_a_full[uk];
+    xs.w_max  = links.xsect_w_max[uk];
+    xs.r_full = links.xsect_r_full[uk];
+    xs.s_full = links.xsect_s_full[uk];
+    xs.s_max  = links.xsect_s_max[uk];
+    xs.y_bot  = links.xsect_y_bot[uk];
+    xs.a_bot  = links.xsect_a_bot[uk];
+    xs.s_bot  = links.xsect_s_bot[uk];
+    xs.r_bot  = links.xsect_r_bot[uk];
+    return xs;
+}
+
+}  // namespace
+
+double netFluxOut(const SimulationContext& ctx,
+                  const HeatElement& elem, double t_w) noexcept {
+    // Every family, one sign convention (positive OUT of the water), one
+    // sum. H6b's SEDIMENT_EXCHANGE is a fourth term on this line.
+    //
+    // H6a deliberately adds NO term here: it changes where `Jin` comes from
+    // inside radiativeFluxOut, not how many families are summed.
+    return surfaceFluxOut(ctx, elem, t_w) +
+           radiativeFluxOut(ctx, elem, t_w);
+}
+
+void applyHeatFluxes(SimulationContext& ctx, double dt) {
+    if (!ctx.options.heat_transport) return;
+    const bool bed_on = bedExchangeEnabled(ctx);
+    if (!ctx.heat_config.surface_exchange &&
+        !ctx.heat_config.radiative_exchange && !bed_on)
+        return;
+    if (!(dt > 0.0)) return;
+    // H6b: seed the bed and resolve the deep-ground temperature ONCE per
+    // step, beside `updateSolarForcing` and for the same reason — both are
+    // GLOBAL-scope forcings whose timeseries cursors must not be advanced
+    // once per element.
+    double t_gr = 0.0;
+    if (bed_on) {
+        seedBedTemperature(ctx);
+        t_gr = groundTemperature(ctx);
+    }
+
+    // H6a: resolve this step's Jin and cloud fraction BEFORE any flux call.
+    // `netFluxOut` is const and reads the cache; nothing downstream can
+    // refresh it.
+    updateSolarForcing(ctx);
+
+    auto& hs = ctx.heat_state;
+    const double rho = ctx.options.water_density;
+    const double cp  = ctx.options.water_specific_heat;
+    const int unit_sys =
+        ucf::getUnitSystem(static_cast(ctx.options.flow_units));
+
+    // One relaxation per element against the SUMMED flux. Stepping each
+    // module separately is what made the answer depend on module order —
+    // see the header.
+    // PE1: the element travels with the temperature. A binding that dropped
+    // it would silently read the global block for every element, which is
+    // exactly the pre-PE behaviour and therefore invisible to a gate that
+    // only checks "did the answer change" — see the PE handoff's falsifier.
+    const auto step = [&](const HeatElement& e, double t_w, double area_ft2,
+                          double vol_ft3) {
+        return relaxT(netFluxOut(ctx, e, t_w),
+                      netFluxOut(ctx, e, t_w + kProbeC), kProbeC,
+                      area_ft2 * kSqFtToSqM, vol_ft3 * kCuFtToCuM,
+                      dt, rho, cp);
+    };
+
+    // ---- Nodes. Only STORAGE nodes have a free surface: node::getSurfArea
+    //      returns 0 for JUNCTION/OUTFALL/DIVIDER, which is legacy's own
+    //      convention and the same one its evaporation obeys. A manhole is
+    //      closed; it does not exchange with the atmosphere. ---------------
+    const int nn = ctx.n_nodes();
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        if (ui >= hs.node_temp.size()) break;
+        const double vol_ft3 = node::storeVolume(ctx.nodes, i);
+        if (!(vol_ft3 > 0.0)) continue;
+
+        const double area_ft2 = node::getSurfArea(
+            ctx.nodes, i, ctx.nodes.depth[ui], &ctx.tables, unit_sys,
+            &ctx.node_subtypes);
+        if (!(area_ft2 > 0.0)) continue;
+
+        hs.node_temp[ui] +=
+            step(HeatElement::node(i), hs.node_temp[ui], area_ft2,
+                 vol_ft3);
+    }
+
+    // ---- Links. Open conduits only, area = top width x length x barrels,
+    //      exactly the expression Routing.cpp:597 uses for evaporation. ----
+    const int nl = ctx.n_links();
+    const auto& CD = ctx.link_subtypes.conduits;
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        if (uj >= hs.link_temp.size()) break;
+        const double vol_ft3 = ctx.links.volume[uj];
+        if (!(vol_ft3 > 0.0)) continue;
+
+        const int cr = ctx.link_subtypes.conduit_row(j);
+        if (cr < 0) continue;                       // regulators have no surface
+
+        // H6b: a CLOSED conduit has no free surface but it does have a bed,
+        // so the open-conduit test can no longer gate the whole iteration —
+        // it gates the surface AREA only. A full pipe reaches this loop with
+        // `area_ft2 == 0` and is stepped by its bed terms alone, which is
+        // exactly the case the reference's top-width spelling would have
+        // switched off (BedZoneData.hpp divergence 1).
+        double area_ft2 = 0.0;
+        if (xsect::isOpen(ctx.links.xsect_batch_shape[uj])) {
+            const auto ucr = static_cast(cr);
+            double length = CD.length[ucr];
+            if (!(length > 0.0)) length = CD.mod_length[ucr];
+            const double depth = ctx.links.depth[uj];
+            if (length > 0.0 && depth > 0.0) {
+                const auto xs = buildXsp(ctx.links, uj);
+                const double top_width = xsect::getWofY(xs, depth);
+                if (top_width > 0.0)
+                    area_ft2 = top_width * length * CD.barrels[ucr];
+            }
+        }
+
+        // H6b: the bed is a SECOND BODY, not another term — see
+        // BedExchange.hpp. When it is present the pair is relaxed
+        // SIMULTANEOUSLY against the same `j0`/`j1` probe the single body
+        // would have used; stepping them one after the other is D-H5e's
+        // defect and this is the one place it could be reintroduced.
+        if (bed_on && uj < ctx.bed_state.link_temp.size()) {
+            const BedCoupling g = bedCouplingForLink(ctx, j, vol_ft3, t_gr);
+            if (g.viable()) {
+                const double t_w = hs.link_temp[uj];
+                const HeatElement le = HeatElement::link(j);
+                const PairStep s = relaxPair(
+                    g, t_w, ctx.bed_state.link_temp[uj],
+                    netFluxOut(ctx, le, t_w),
+                    netFluxOut(ctx, le, t_w + kProbeC), kProbeC,
+                    area_ft2 * kSqFtToSqM, dt);
+                hs.link_temp[uj]             += s.dt_w;
+                ctx.bed_state.link_temp[uj]  += s.dt_b;
+                continue;
+            }
+        }
+
+        if (!(area_ft2 > 0.0)) continue;
+        hs.link_temp[uj] += step(HeatElement::link(j),
+                                 hs.link_temp[uj], area_ft2, vol_ft3);
+    }
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/HeatFluxes.hpp b/src/engine/transport/components/HeatFluxModules/HeatFluxes.hpp
new file mode 100644
index 000000000..a2d7bda79
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/HeatFluxes.hpp
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatFluxes.hpp
+ * @brief Plan D-H5e — the single node/link surface-flux binding.
+ *
+ * @details **One traversal, one net flux, one relaxation.** Every enabled
+ *          flux family contributes to `J(T)`; the element is then stepped
+ *          once.
+ *
+ * @par The defect this exists to make unrepresentable
+ *      H2 and H3 each owned a binding: `applySurfaceExchange` then
+ *      `applyRadiativeExchange`, called back to back from `routeLegacyHeat`.
+ *      Under forward Euler that was harmless — the two increments were
+ *      linear and added exactly. D-H5d replaced the step with an exponential
+ *      relaxation, and relaxations **do not commute**: each sub-step relaxes
+ *      FULLY toward its own module's equilibrium, so the pair overshoots the
+ *      true combined one and the result depends on which module ran last.
+ *      Measured, two equal modules with equilibria at 30 °C and 10 °C, true
+ *      combined 20 °C, from 5 °C:
+ *
+ *      | k·dt   | split    | combined |
+ *      |--------|----------|----------|
+ *      | 4.1e-3 | 5.061317 | 5.061359 |
+ *      | 0.41   | 9.700850 | 10.044256|
+ *      | 39.4   | 10.000000| 20.000000|
+ *
+ *      At large `k·dt` the split lands exactly on the last module's
+ *      equilibrium — the first module's contribution has been erased.
+ *
+ *      **The general lesson, worth more than this instance:** replacing an
+ *      integrator underneath an existing operator split silently changes
+ *      what the split means. Forward Euler's linearity was load-bearing and
+ *      nobody had written that down.
+ *
+ * @par Why a separate file
+ *      The traversal belongs to neither module. It lived in both — H2's copy
+ *      and H3's near-identical copy — which is also how H3 came to carry
+ *      H2's divergence through a different spelling. A SURFACE flux family
+ *      is one line in `netFluxOut` here and cannot acquire a binding of its
+ *      own — but that sentence once claimed H6's SEDIMENT_EXCHANGE too, and
+ *      it was wrong: the bed acts on the wetted perimeter (a different area,
+ *      nonzero exactly when the free surface is zero) and adds a SECOND state
+ *      variable, so `relaxT`'s fixed equilibrium does not exist for it. H6b
+ *      therefore steps the water/bed pair as ONE coupled relaxation
+ *      (`BedExchange.hpp`) inside this file's link loop — coupled rather than
+ *      sequential for exactly the D-H5e reason above.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §6.2 D-H5d, §6.3 D-H5e
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_FLUXES_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_FLUXES_HPP
+
+#include "../../../data/HeatOverrideData.hpp"   // HeatElement (PE1)
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport::heat {
+
+/**
+ * @brief Net outward surface flux at `t_w`, summed over every enabled
+ *        module [W/m²].
+ *
+ * @details Each module's evaluator returns 0 when its own `[HEAT_FLUXES]`
+ *          toggle is off, so this sums unconditionally and no caller has to
+ *          know which families exist. **This is the extension point**: a new
+ *          flux family is one added term here and nowhere else.
+ *
+ *          Shared with the ARD mesh and watershed bindings, which have their
+ *          own element geometry but must compose the flux identically — the
+ *          alternative being four hand-rolled copies of the same sum, which
+ *          is the duplication that produced the defect above.
+ *
+ *          **PE1: `elem` names WHICH element is being evaluated**, so a
+ *          module can read per-element attributes (shading, sky view, bed
+ *          properties) instead of one global block. Passing a default-
+ *          constructed `HeatElement` yields the global config — which is
+ *          exactly what every caller got before PE — so a binding that
+ *          forgets to pass its element degrades to the old behaviour rather
+ *          than reading element 0's attributes.
+ */
+double netFluxOut(const SimulationContext& ctx,
+                  const HeatElement& elem, double t_w) noexcept;
+
+/**
+ * @brief Apply one step of surface heat exchange to every exchanging
+ *        node and link.
+ *
+ * @details Storage nodes (`node::getSurfArea`) and open conduits (top width
+ *          × length × barrels) — the engine's own evaporation surfaces, so
+ *          heat crosses the free surface exactly where water leaves it.
+ *          Junctions, outfalls, dividers and closed conduits have no free
+ *          surface and no exchange.
+ *
+ *          Modifies `heat_state.node_temp` and `link_temp` in place. No-op
+ *          unless HEAT_TRANSPORT is on and at least one flux module is
+ *          enabled.
+ */
+void applyHeatFluxes(SimulationContext& ctx, double dt);
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_FLUXES_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/HeatOverrides.cpp b/src/engine/transport/components/HeatFluxModules/HeatOverrides.cpp
new file mode 100644
index 000000000..77629abb8
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/HeatOverrides.cpp
@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatOverrides.cpp
+ * @brief Plan PE — resolution and lookup. See the header.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatOverrides.hpp"
+
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+/// Write one attribute into a radiative block. Split from the sediment
+/// version rather than merged behind a tag: two switches over disjoint enum
+/// ranges are clearer than one switch with an unreachable half, and the
+/// compiler warns on a missing case in each.
+void patchRadiative(RadiativeConfig& c, HeatAttr a, double v) noexcept {
+    switch (a) {
+        case HeatAttr::ALBEDO:          c.albedo = v; break;
+        case HeatAttr::SHADE_FACTOR:    c.shade_factor = v; break;
+        case HeatAttr::SKY_VIEW:        c.sky_view = v; break;
+        case HeatAttr::EMISS_WATER:     c.emiss_water = v; break;
+        case HeatAttr::EMISS_LANDCOVER: c.emiss_landcover = v; break;
+        case HeatAttr::LANDCOVER_TEMP:  c.landcover_temp = v; break;
+        default: break;   // sediment attrs never reach here (isSedimentAttr)
+    }
+}
+
+void patchSediment(SedimentConfig& c, HeatAttr a, double v) noexcept {
+    switch (a) {
+        case HeatAttr::SED_THERMAL_DIFFUSIVITY: c.thermal_diffusivity = v; break;
+        case HeatAttr::SED_SOLUTE_DIFFUSIVITY:  c.solute_diffusivity = v; break;
+        case HeatAttr::SED_BED_THICKNESS:       c.bed_thickness = v; break;
+        case HeatAttr::SED_GROUND_DEPTH:        c.ground_depth = v; break;
+        case HeatAttr::SED_GROUND_TEMP:
+            c.ground_temp = v;
+            // A per-element ground temperature is by definition stated, so
+            // it also silences the "you did not set GROUND_TEMPERATURE"
+            // warning for models that set it only per element. Without this
+            // a fully-specified model is warned about the one thing it was
+            // most careful with.
+            c.has_ground_temp = true;
+            break;
+        case HeatAttr::SED_HYPORHEIC_VELOCITY:  c.hyporheic_velocity = v; break;
+        case HeatAttr::SED_DENSITY:             c.sed_density = v; break;
+        case HeatAttr::SED_SPECIFIC_HEAT:       c.sed_specific_heat = v; break;
+        default: break;
+    }
+}
+
+}  // namespace
+
+std::vector resolveHeatOverrides(SimulationContext& ctx) {
+    std::vector errors;
+    auto& ov = ctx.heat_config.overrides;
+    ov.resolved = true;
+    if (ov.rows.empty()) return errors;   // nothing sized, nothing allocated
+
+    const int nl = ctx.n_links();
+    const int nn = ctx.n_nodes();
+
+    // Which families are actually targeted. Sizing only what is used is
+    // D-PE2's whole point: a deck that shades three conduits must not
+    // allocate a SedimentConfig for every link in the network.
+    bool want_rad_link = false, want_rad_node = false, want_sed = false;
+    for (const auto& r : ov.rows) {
+        if (r.scope == HeatScope::GLOBAL) continue;     // already in the base
+        if (isSedimentAttr(r.attr)) {
+            want_sed = true;
+        } else if (r.scope == HeatScope::NODE) {
+            want_rad_node = true;
+        } else {
+            // TAG rows can land on either kind, so a TAG row arms both.
+            want_rad_link = true;
+            if (r.scope == HeatScope::TAG) want_rad_node = true;
+        }
+    }
+
+    if (want_rad_link && nl > 0)
+        ov.rad_link.assign(static_cast(nl),
+                           ctx.heat_config.radiative);
+    if (want_rad_node && nn > 0)
+        ov.rad_node.assign(static_cast(nn),
+                           ctx.heat_config.radiative);
+    if (want_sed && nl > 0)
+        ov.sed_link.assign(static_cast(nl),
+                           ctx.heat_config.sediment);
+
+    // Two passes, in specificity order (D-PE3). Precedence is a property of
+    // the ORDER, not of a comparison: TAG writes first, element writes
+    // second and simply wins. Encoding it as a comparison would state the
+    // ordering twice and let the two spellings disagree.
+    for (int pass = 0; pass < 2; ++pass) {
+        const HeatScope want = (pass == 0) ? HeatScope::TAG : HeatScope::NODE;
+        for (const auto& r : ov.rows) {
+            if (r.scope == HeatScope::GLOBAL) continue;
+            const bool is_elem = (r.scope == HeatScope::NODE ||
+                                  r.scope == HeatScope::LINK);
+            if (pass == 0 && r.scope != HeatScope::TAG) continue;
+            if (pass == 1 && !is_elem) continue;
+            (void)want;
+
+            if (r.scope == HeatScope::TAG) {
+                bool hit = false;
+                for (int j = 0; j < nl; ++j) {
+                    const auto uj = static_cast(j);
+                    if (uj >= ctx.links.tags.size() ||
+                        ctx.links.tags[uj] != r.name)
+                        continue;
+                    hit = true;
+                    if (isSedimentAttr(r.attr)) {
+                        if (uj < ov.sed_link.size())
+                            patchSediment(ov.sed_link[uj], r.attr, r.value);
+                    } else if (uj < ov.rad_link.size()) {
+                        patchRadiative(ov.rad_link[uj], r.attr, r.value);
+                    }
+                }
+                if (!isSedimentAttr(r.attr)) {
+                    for (int i = 0; i < nn; ++i) {
+                        const auto ui = static_cast(i);
+                        if (ui >= ctx.nodes.tags.size() ||
+                            ctx.nodes.tags[ui] != r.name)
+                            continue;
+                        hit = true;
+                        if (ui < ov.rad_node.size())
+                            patchRadiative(ov.rad_node[ui], r.attr, r.value);
+                    }
+                }
+                // A tag that matches nothing is a typo with the same
+                // consequence as a bad element name — the row silently does
+                // nothing — so it is fatal for the same reason (D-PE5).
+                if (!hit)
+                    errors.push_back(
+                        "model.heat: TAG '" + r.name + "' matches no link or "
+                        "node, so this override would silently do nothing. "
+                        "Check [TAGS].");
+                continue;
+            }
+
+            if (r.scope == HeatScope::LINK) {
+                const int j = ctx.link_names.find(r.name);
+                if (j < 0) {
+                    errors.push_back("model.heat: unknown link '" + r.name +
+                                     "' in a per-element heat override.");
+                    continue;
+                }
+                const auto uj = static_cast(j);
+                if (isSedimentAttr(r.attr)) {
+                    if (uj < ov.sed_link.size())
+                        patchSediment(ov.sed_link[uj], r.attr, r.value);
+                } else if (uj < ov.rad_link.size()) {
+                    patchRadiative(ov.rad_link[uj], r.attr, r.value);
+                }
+                continue;
+            }
+
+            // NODE scope. Sediment attributes are refused at parse (the bed
+            // is conduits only), so only radiative rows reach here.
+            const int i = ctx.node_names.find(r.name);
+            if (i < 0) {
+                errors.push_back("model.heat: unknown node '" + r.name +
+                                 "' in a per-element heat override.");
+                continue;
+            }
+            const auto ui = static_cast(i);
+            if (ui < ov.rad_node.size())
+                patchRadiative(ov.rad_node[ui], r.attr, r.value);
+        }
+    }
+    return errors;
+}
+
+const RadiativeConfig& radiativeFor(const SimulationContext& ctx,
+                                    const HeatElement& e) noexcept {
+    const auto& ov = ctx.heat_config.overrides;
+    if (e.index >= 0) {
+        const auto ui = static_cast(e.index);
+        if (e.kind == HeatElemKind::LINK && ui < ov.rad_link.size())
+            return ov.rad_link[ui];
+        if (e.kind == HeatElemKind::NODE && ui < ov.rad_node.size())
+            return ov.rad_node[ui];
+    }
+    // SUBCATCH and LID have no radiative override table: a subcatchment's
+    // shading is a watershed property this program models through its own
+    // land-cover inputs, and a LID layer is below the surface. Both read the
+    // global, which is what they did before PE.
+    return ctx.heat_config.radiative;
+}
+
+const SedimentConfig& sedimentFor(const SimulationContext& ctx,
+                                  const HeatElement& e) noexcept {
+    const auto& ov = ctx.heat_config.overrides;
+    if (e.kind == HeatElemKind::LINK && e.index >= 0) {
+        const auto ui = static_cast(e.index);
+        if (ui < ov.sed_link.size()) return ov.sed_link[ui];
+    }
+    return ctx.heat_config.sediment;
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/HeatOverrides.hpp b/src/engine/transport/components/HeatFluxModules/HeatOverrides.hpp
new file mode 100644
index 000000000..6d1d689fc
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/HeatOverrides.hpp
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatOverrides.hpp
+ * @brief Plan PE — resolve per-element attributes, and read them.
+ *
+ * @details Two accessors and one resolver. Everything else about the
+ *          feature is parsing (HeatComponent.cpp) or threading
+ *          (the flux evaluators).
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_OVERRIDES_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_OVERRIDES_HPP
+
+#include 
+#include 
+
+#include "../../../data/HeatData.hpp"
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport::heat {
+
+/**
+ * @brief Materialise the dense per-element vectors from the parsed rows.
+ *
+ * @details Called ONCE from `SWMMEngine::open`, after every process
+ *          component has applied — the D-RQ1 timing, so `link_names`,
+ *          `node_names` and the `[TAGS]` columns are all complete and an
+ *          unknown element name can be reported with the row that named it.
+ *
+ *          Precedence is applied by CONSTRUCTION rather than by comparison:
+ *          rows are swept in scope order (GLOBAL is already in the base
+ *          config, then TAG, then element), so a later write simply wins.
+ *          A comparison-based resolver would have to encode the ordering a
+ *          second time and the two spellings could disagree.
+ *
+ * @return Diagnostics; non-empty means the model must not open. Unknown
+ *         element names are FATAL (D-PE5): a silently ignored override
+ *         produces a plausible answer, which is the failure mode lessons
+ *         10/20 are about.
+ */
+std::vector resolveHeatOverrides(SimulationContext& ctx);
+
+/**
+ * @brief The radiative attributes in force for `e`.
+ *
+ * @details Returns the GLOBAL config when no override targets this family,
+ *          when the element index is out of range, or when the element is
+ *          not a kind that carries radiative overrides. **The empty-vector
+ *          path returns the very same object the pre-PE engine used**, which
+ *          is what makes a non-PE model bit-identical by construction rather
+ *          than by tolerance.
+ */
+const RadiativeConfig& radiativeFor(const SimulationContext& ctx,
+                                    const HeatElement& e) noexcept;
+
+/**
+ * @brief The bed attributes in force for `e`.
+ *
+ * @details Bed overrides are LINK-scoped only — the bed zone itself is
+ *          conduits only (`BedZoneState`), so a node-scoped bed attribute
+ *          would describe a body that does not exist. A NODE element
+ *          therefore always reads the global here, and the parser refuses
+ *          `NODE` scope on a `[SEDIMENT_EXCHANGE]` row rather than accepting
+ *          a row that could never take effect.
+ */
+const SedimentConfig& sedimentFor(const SimulationContext& ctx,
+                                  const HeatElement& e) noexcept;
+
+// The NaN sentinel on `landcover_temp` ("use air temperature") is resolved
+// in exactly one place: `netRadiativeFluxOut`, which receives the resolved
+// per-element RadiativeConfig and is the only reader of the field. The
+// handoff's draft declared a `landcoverTempC` accessor here instead — and no
+// call site ever used it, which left the key parsed, validated, serialized
+// and physically inert. The check deleted the accessor and moved the
+// resolution to the reader.
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_OVERRIDES_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/RadiativeExchange.cpp b/src/engine/transport/components/HeatFluxModules/RadiativeExchange.cpp
new file mode 100644
index 000000000..254439c20
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/RadiativeExchange.cpp
@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file RadiativeExchange.cpp
+ * @brief Phase H3 body — shortwave/longwave radiation.
+ *
+ * @details D-H5e moved the node and link BINDING out of this file into
+ *          HeatFluxes.cpp. This file had its own hand-inlined explicit
+ *          conversion and its own copy of the element traversal, which is
+ *          how it came to carry H2's divergence through a different
+ *          spelling and then to relax separately from it.
+ *
+ * @details Line-for-line provenance is `RHEComponent/src/element.cpp`:
+ *          `computeNetSWSolarRadiation` (:106), `computeBackLWRadiation`
+ *          (:113), `computeAtmosphericLWRadiation` (:119),
+ *          `computeLandCoverLWRadiation` (:131).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "RadiativeExchange.hpp"
+
+#include "HeatOverrides.hpp"
+
+#include 
+#include 
+
+#include "SolarRadiation.hpp"
+#include "SurfaceExchange.hpp"
+#include "../../../core/SimulationContext.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+// `kSqFtToSqM`, `kCuFtToCuM` and `airTempCelsius` were duplicated here and
+// in SurfaceExchange.cpp. H5a exported them from SurfaceExchange.hpp (which
+// this file already includes) because a third copy would have been needed
+// for the watershed binding; the local copies are removed rather than left
+// to shadow, since unqualified lookup would find both and neither the
+// ambiguity nor a future divergence is something a test would catch.
+
+/// T⁴ in Kelvin, written once so the offset cannot drift between terms.
+double kelvin4(double t_c) noexcept {
+    const double k = t_c + kKelvinOffset;
+    return k * k * k * k;
+}
+
+}  // namespace
+
+double netShortwave(double incoming_wm2, double albedo,
+                    double shade_factor) noexcept {
+    // max(0, 1 - fs) mirrors the reference: an over-unity shade factor
+    // shades completely rather than turning into negative insolation.
+    return (1.0 - albedo) * incoming_wm2 *
+           std::max(0.0, 1.0 - shade_factor);
+}
+
+double backLongwave(double t_water_c, double emiss_water) noexcept {
+    return emiss_water * kStefanBoltzmann * kelvin4(t_water_c);
+}
+
+double atmosphericEmissivity(double e_a_kpa, double atm_emiss_coeff,
+                             double cloud_factor) noexcept {
+    // Brunt (1932). The reference passes PASCALS into the square root
+    // (`sqrt(vaporPressureAir * 1000)`); vapour pressure here is kPa, so
+    // the ×1000 is the unit conversion, not a fudge. Using kPa understates
+    // this term by sqrt(1000).
+    const double clear =
+        atm_emiss_coeff + 0.0027 * std::sqrt(std::max(0.0, e_a_kpa) * 1000.0);
+
+    // H6a (D-H6a-2). Guarded rather than multiplied unconditionally: the
+    // clear-sky result must be the SAME OBJECT CODE H3 was gated on, not a
+    // multiply by a value that happens to be 1.0. `cloudLongwaveFactor`
+    // returns a literal 1.0 for C <= 0 for the same reason.
+    if (cloud_factor == 1.0) return clear;
+    return clear * cloud_factor;
+}
+
+double atmosphericLongwave(double t_air_c, double humidity_pct,
+                           double atm_emiss_coeff, double lw_reflection,
+                           double sky_view, double cloud_factor) noexcept {
+    const double e_a =
+        (humidity_pct / 100.0) * saturationVapourPressure(t_air_c);
+    return kStefanBoltzmann * kelvin4(t_air_c) *
+           atmosphericEmissivity(e_a, atm_emiss_coeff, cloud_factor) *
+           (1.0 - lw_reflection) * sky_view;
+}
+
+double landCoverLongwave(double t_air_c, double emiss_landcover,
+                         double sky_view) noexcept {
+    // The reference carries a separate land-cover TEMPERATURE state; H3
+    // uses air temperature, per plan §2.2. Recorded as a known difference:
+    // a canopy warmer than the air (the usual daytime case) radiates more
+    // than this predicts.
+    return emiss_landcover * kStefanBoltzmann * (1.0 - sky_view) *
+           kelvin4(t_air_c);
+}
+
+double netRadiativeFluxOut(double t_water_c, double t_air_c,
+                           double humidity_pct, const RadiativeConfig& cfg,
+                           double jin_wm2, double cloud_factor) noexcept {
+    // Negative sentinel = "no resolved value, use the configured constant".
+    // 0 is a legal Jin (night) and must not read as unset.
+    const double jin = (jin_wm2 < 0.0) ? cfg.shortwave_wm2 : jin_wm2;
+
+    const double jsn = netShortwave(jin, cfg.albedo, cfg.shade_factor);
+    const double jbr = backLongwave(t_water_c, cfg.emiss_water);
+    const double jan = atmosphericLongwave(t_air_c, humidity_pct,
+                                           cfg.atm_emiss_coeff,
+                                           cfg.lw_reflection, cfg.sky_view,
+                                           cloud_factor);
+    // PE2: the land cover radiates at ITS OWN temperature when the deck
+    // states one; NaN is the sentinel for "use air temperature", which is
+    // what this term did unconditionally before PE and what it still does
+    // for every model that does not set the key. (The check found the field
+    // parsed, validated and serialized but never read — this line is where
+    // it is read.)
+    const double t_lc_c = std::isnan(cfg.landcover_temp) ? t_air_c
+                                                         : cfg.landcover_temp;
+    const double jlc = landCoverLongwave(t_lc_c, cfg.emiss_landcover,
+                                         cfg.sky_view);
+    // Sign flip lives here and nowhere else: three terms warm the water,
+    // one cools it, and this module's callers expect positive = OUT.
+    return jbr - jsn - jan - jlc;
+}
+
+double radiativeFluxOut(const SimulationContext& ctx,
+                        const HeatElement& elem, double t_w) noexcept {
+    if (!ctx.options.heat_transport || !ctx.heat_config.radiative_exchange)
+        return 0.0;
+
+    // H6a. `shortwave_now` is resolved once per step by `updateSolarForcing`
+    // at every binding prologue; this call is const and only reads it.
+    //
+    // Under CONSTANT with no cloud these two arguments reproduce H3 exactly:
+    // `updateSolarForcing` copies `cfg.shortwave_wm2` into `shortwave_now`
+    // unchanged, and `cloudLongwaveFactor(0, k)` is a literal 1.0 which
+    // `atmosphericEmissivity` then short-circuits.
+    const auto& cc = ctx.heat_config.cloud;
+    // PE2: the per-element radiative block (shading, sky view, emissivities,
+    // land-cover temperature). Returns the GLOBAL object when this model has
+    // no overrides, so the call below is unchanged for every pre-PE deck.
+    const RadiativeConfig& rc = radiativeFor(ctx, elem);
+    // PE4: per-element climate, resolved at the flux call (see SurfaceExchange).
+    const double t_air_c =
+        (ctx.forcing.elementAirTempF(elem, ctx.climate_state.temperature)
+         - 32.0) * 5.0 / 9.0;
+    const double rh = ctx.forcing.elementHumidity(elem,
+                          ctx.climate_state.humidity);
+    // PE4: a coupled shade model can push Jin per element outright; the deck
+    // states one incident resource and SHADE_FACTOR modulates it. Precedence
+    // is stated once, here: API element forcing > deck shade on global Jin.
+    const double jin = ctx.forcing.elementShortwave(elem,
+                           ctx.heat_state.shortwave_now);
+    return netRadiativeFluxOut(
+        t_w, t_air_c, rh, rc, jin,
+        cloudLongwaveFactor(ctx.heat_state.cloud_now, cc.lw_cloud_k));
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/RadiativeExchange.hpp b/src/engine/transport/components/HeatFluxModules/RadiativeExchange.hpp
new file mode 100644
index 000000000..00cda8131
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/RadiativeExchange.hpp
@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file RadiativeExchange.hpp
+ * @brief Phase H3 — shortwave and longwave radiation at the water surface
+ *        (heat plan §2.2; RHEComponent §6).
+ *
+ * @details Four terms, each a pure function so it can be gated against the
+ *          reference implementation rather than against this engine's own
+ *          output:
+ *
+ *          - **Net shortwave** `Jsn = (1 − Rs) Jin (1 − fs)` — absorbed
+ *            solar.
+ *          - **Back longwave** `Jbr = εw σ Tw⁴` — emitted by the water.
+ *          - **Atmospheric longwave** `Jan = εatm σ Ta⁴ (1 − RL) fsky`,
+ *            Brunt (1932) `εatm = Aa + 0.0027 √(e_a in PASCALS)`.
+ *          - **Land-cover longwave** `Jlc = εlc σ Ta⁴ (1 − fsky)`.
+ *
+ * @par Two corrections to the plan text, taken from the reference
+ *      The plan's §2.2 summary omits both, and either would have been a
+ *      silent error (`RHEComponent/src/element.cpp:106-135`):
+ *      1. **The sky-view factor splits the longwave budget.** `Jan` is
+ *         multiplied by `fsky` and `Jlc` by `(1 − fsky)`; they are
+ *         complementary shares of the same hemisphere, not independent
+ *         terms. Written without it, an open-sky element would double-count
+ *         and a fully shaded one would receive atmospheric longwave through
+ *         a canopy.
+ *      2. **Brunt's square root takes PASCALS**, not the kPa the vapour
+ *         pressure is computed in — `0.0027 √(e_a · 1000)`. Feeding kPa
+ *         understates the emissivity term by √1000 ≈ 31.6.
+ *
+ * @par Sign convention
+ *      **This module returns POSITIVE = leaving the water**, matching
+ *      SurfaceExchange, so the two modules can be summed. The reference
+ *      uses the opposite sign (its `netMCRadiation` is positive into the
+ *      water, with `backLWRadiation` pre-negated); `netRadiativeFluxOut`
+ *      performs the flip in one named place.
+ *
+ * @par Not carried over from the reference: the sediment split
+ *      RHE splits absorbed shortwave into a water share and a bed share
+ *      with `exp(−extinction · depth)` and hands the latter to the sediment
+ *      column. There is no sediment column until H4, so **H3 keeps all
+ *      absorbed shortwave in the water**. That is a deliberate difference,
+ *      not an omission: routing bed-bound energy into the water column
+ *      overestimates warming in shallow, clear water, and H4 is where the
+ *      receiving state appears.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.2, §6 H3
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_RADIATIVE_EXCHANGE_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_RADIATIVE_EXCHANGE_HPP
+
+#include "../../../data/HeatOverrideData.hpp"   // HeatElement (PE1)
+
+namespace openswmm {
+struct SimulationContext;
+struct RadiativeConfig;
+}
+
+namespace openswmm::transport::heat {
+
+/// Stefan–Boltzmann constant, W/m²/K⁴ (`rhemodel.cpp:46`).
+inline constexpr double kStefanBoltzmann = 5.67e-8;
+
+/// Celsius → Kelvin offset.
+inline constexpr double kKelvinOffset = 273.15;
+
+/// Net absorbed shortwave [W/m²], INTO the water.
+double netShortwave(double incoming_wm2, double albedo,
+                    double shade_factor) noexcept;
+
+/// Back longwave emitted by the water [W/m²], OUT of the water.
+double backLongwave(double t_water_c, double emiss_water) noexcept;
+
+/// Brunt atmospheric emissivity [-]. `e_a_kpa` is converted to Pa inside.
+///
+/// H6a: `cloud_factor` is Bolz's `1 + k_lw C²` from
+/// `SolarRadiation::cloudLongwaveFactor`. It DEFAULTS TO 1.0 and the
+/// default is not decorative — every H3 gate calls the two-argument form,
+/// so the clear-sky value is unchanged by construction rather than by
+/// arithmetic that happens to round the same way.
+double atmosphericEmissivity(double e_a_kpa, double atm_emiss_coeff,
+                             double cloud_factor = 1.0) noexcept;
+
+/// Atmospheric longwave [W/m²], INTO the water.
+double atmosphericLongwave(double t_air_c, double humidity_pct,
+                           double atm_emiss_coeff, double lw_reflection,
+                           double sky_view,
+                           double cloud_factor = 1.0) noexcept;
+
+/// Land-cover longwave [W/m²], INTO the water.
+double landCoverLongwave(double t_air_c, double emiss_landcover,
+                         double sky_view) noexcept;
+
+/// Net radiative flux [W/m²], **positive OUT of the water** so it sums with
+/// SurfaceExchange's `Je + Jc`.
+///
+/// H6a adds two optional arguments and changes nothing without them:
+///   - `jin_wm2 < 0` (the default) means "use `cfg.shortwave_wm2`", the H3
+///     behaviour. A caller with a resolved per-step `Jin` passes it here.
+///     The sentinel is negative rather than NaN because a deck may legally
+///     mean 0 W/m² (night), and 0 must not be mistaken for "unset".
+///   - `cloud_factor` defaults to 1.0 — see `atmosphericEmissivity`.
+double netRadiativeFluxOut(double t_water_c, double t_air_c,
+                           double humidity_pct, const RadiativeConfig& cfg,
+                           double jin_wm2 = -1.0,
+                           double cloud_factor = 1.0) noexcept;
+
+/// This module's contribution to the net outward flux at `t_w` [W/m²].
+/// Returns 0 unless HEAT_TRANSPORT is on AND `[HEAT_FLUXES]
+/// RADIATIVE_EXCHANGE` is enabled, so a caller sums it unconditionally.
+///
+/// D-H5e: this module no longer has a binding of its own. It had one, with
+/// its own element traversal and its own explicit conversion, and that is
+/// how it came to relax separately from SurfaceExchange toward a different
+/// equilibrium — making the answer depend on which module ran last.
+double radiativeFluxOut(const SimulationContext& ctx,
+                        const HeatElement& elem, double t_w) noexcept;
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_RADIATIVE_EXCHANGE_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/SolarRadiation.cpp b/src/engine/transport/components/HeatFluxModules/SolarRadiation.cpp
new file mode 100644
index 000000000..d5f33c6bd
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/SolarRadiation.cpp
@@ -0,0 +1,338 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SolarRadiation.cpp
+ * @brief Phase H6a — solar position, clear-sky irradiance, cloud.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SolarRadiation.hpp"
+
+#include 
+#include 
+
+#include "../../../core/DateTime.hpp"
+#include "../../../core/SimulationContext.hpp"
+#include "../../../data/TableData.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+constexpr double kPi     = 3.14159265358979323846;
+constexpr double kDegRad = kPi / 180.0;
+constexpr double kRadDeg = 180.0 / kPi;
+
+/// Feet → metres. `ClimateState::elev` is feet (legacy `Temp.elev`).
+constexpr double kFtToM = 0.3048;
+
+}  // namespace
+
+// ===========================================================================
+// Solar position — Spencer (1971) Fourier series, NOAA's published form.
+//
+// Every coefficient below is a term of a truncated Fourier fit and can be
+// checked by inspection against the NOAA Solar Calculator documentation.
+// That readability IS the reason this is here instead of SPA (header, D-H6a-4).
+// ===========================================================================
+
+SolarPosition solarPosition(int day_of_year, double hour_local, double lat_deg,
+                            double lon_deg, double tz_hours) noexcept {
+    SolarPosition p{};
+
+    // Fractional year, radians. The (hour − 12)/24 term puts the fit at the
+    // instant rather than at local midnight; omitting it costs ~0.2° of
+    // declination at the equinoxes, where declination moves fastest.
+    const double g =
+        2.0 * kPi / 365.0 *
+        (static_cast(day_of_year) - 1.0 + (hour_local - 12.0) / 24.0);
+
+    const double c1 = std::cos(g),      s1 = std::sin(g);
+    const double c2 = std::cos(2.0*g),  s2 = std::sin(2.0*g);
+    const double c3 = std::cos(3.0*g),  s3 = std::sin(3.0*g);
+
+    // Equation of time, minutes.
+    p.eq_time_min = 229.18 * (0.000075 + 0.001868 * c1 - 0.032077 * s1
+                              - 0.014615 * c2 - 0.040849 * s2);
+
+    // Declination, radians → degrees.
+    const double decl = 0.006918 - 0.399912 * c1 + 0.070257 * s1
+                        - 0.006758 * c2 + 0.000907 * s2
+                        - 0.002697 * c3 + 0.001480 * s3;
+    p.declination_deg = decl * kRadDeg;
+
+    // Eccentricity / earth-sun distance correction (Spencer 1971), the E0
+    // that scales the solar constant. Bird needs it; the position does not.
+    p.eccentricity = 1.00011 + 0.034221 * c1 + 0.001280 * s1
+                     + 0.000719 * c2 + 0.000077 * s2;
+
+    // True solar time. `4 * longitude` converts degrees to minutes (the sun
+    // moves 1° in 4 min); `60 * tz` removes the civil-clock offset. Sign
+    // convention: longitude POSITIVE EAST, timezone POSITIVE EAST — so a
+    // Utah deck is (-111.8, -7) and the two corrections nearly cancel, which
+    // is the arithmetic to check when a result looks shifted by hours.
+    const double time_offset_min =
+        p.eq_time_min + 4.0 * lon_deg - 60.0 * tz_hours;
+    const double tst_min = hour_local * 60.0 + time_offset_min;
+
+    // Hour angle: −180° at solar midnight, 0 at solar noon.
+    double ha = tst_min / 4.0 - 180.0;
+    // Wrap to [−180, 180]. Without this a time_offset large enough to push
+    // tst past a day boundary yields |ha| > 180 and a cos_zenith that is
+    // right by accident for zenith but wrong for any azimuth use later.
+    while (ha < -180.0) ha += 360.0;
+    while (ha >  180.0) ha -= 360.0;
+    p.hour_angle_deg = ha;
+
+    const double lat = lat_deg * kDegRad;
+    const double cz  = std::sin(lat) * std::sin(decl)
+                     + std::cos(lat) * std::cos(decl) * std::cos(ha * kDegRad);
+    const double cz_clamped = std::max(-1.0, std::min(1.0, cz));
+
+    p.zenith_deg    = std::acos(cz_clamped) * kRadDeg;
+    p.elevation_deg = 90.0 - p.zenith_deg;
+    // Below the horizon is 0, not a negative cosine: every downstream term
+    // treats this as "no sun", and a negative here would make Bird's air
+    // mass and the GHI product silently change sign rather than vanish.
+    p.cos_zenith    = std::max(0.0, cz_clamped);
+
+    return p;
+}
+
+// ===========================================================================
+// Bird & Hulstrom (1981) clear-sky model
+// ===========================================================================
+
+double airMass(double zenith_deg) noexcept {
+    // Kasten & Young (1989). Undefined at and below the horizon; the caller
+    // contract is that 0 means "no path", and every transmittance below is
+    // written so that 0 produces darkness rather than a NaN.
+    if (zenith_deg >= 90.0) return 0.0;
+    const double z = zenith_deg;
+    const double denom =
+        std::cos(z * kDegRad) + 0.50572 * std::pow(96.07995 - z, -1.6364);
+    if (!(denom > 0.0)) return 0.0;
+    return 1.0 / denom;
+}
+
+double pressureFromElevation(double elevation_m) noexcept {
+    // Standard atmosphere. Negative elevations (below sea level) are legal.
+    return kStdPressureMb * std::pow(1.0 - 2.25577e-5 * elevation_m, 5.25588);
+}
+
+double birdClearSkyGHI(const SolarPosition& pos, double pressure_mb,
+                       const SolarConfig& cfg) noexcept {
+    const double cz = pos.cos_zenith;
+    if (!(cz > 0.0)) return 0.0;
+
+    const double am = airMass(pos.zenith_deg);
+    if (!(am > 0.0)) return 0.0;
+
+    // Pressure-corrected air mass.
+    const double amp = am * (pressure_mb / kStdPressureMb);
+
+    // --- Rayleigh scattering
+    const double t_r = std::exp(-0.0903 * std::pow(amp, 0.84) *
+                                (1.0 + amp - std::pow(amp, 1.01)));
+
+    // --- Ozone absorption
+    const double xo = cfg.ozone_cm * am;
+    const double t_o =
+        1.0 - 0.1611 * xo * std::pow(1.0 + 139.48 * xo, -0.3034)
+        - 0.002715 * xo / (1.0 + 0.044 * xo + 0.0003 * xo * xo);
+
+    // --- Uniformly mixed gases
+    const double t_um = std::exp(-0.0127 * std::pow(amp, 0.26));
+
+    // --- Water vapour
+    const double xw = cfg.precip_water_cm * am;
+    const double t_w =
+        1.0 - 2.4959 * xw /
+                  (std::pow(1.0 + 79.034 * xw, 0.6828) + 6.385 * xw);
+
+    // --- Aerosol. The 0.2758/0.35 pair is Bird's broadband weighting of the
+    //     two measured optical depths onto one effective depth.
+    const double tau_a = 0.2758 * cfg.aod380 + 0.35 * cfg.aod500;
+    const double t_a =
+        std::exp(-std::pow(tau_a, 0.873) *
+                 (1.0 + tau_a - std::pow(tau_a, 0.7088)) *
+                 std::pow(am, 0.9108));
+
+    // Aerosol absorptance / scattering split. Ba is the forward-scattering
+    // ratio, a fixed 0.85 in Bird.
+    constexpr double kBa = 0.85;
+    const double t_aa = 1.0 - 0.1 * (1.0 - am + std::pow(am, 1.06)) * (1.0 - t_a);
+    const double t_as = (t_aa > 0.0) ? (t_a / t_aa) : 0.0;
+
+    const double i_ext = kSolarConstant * pos.eccentricity;
+
+    // Direct normal, then its horizontal component.
+    const double i_dn = 0.9662 * i_ext * t_r * t_o * t_um * t_w * t_a;
+    const double i_d  = i_dn * cz;
+
+    // Diffuse on the horizontal.
+    const double denom = 1.0 - am + std::pow(am, 1.02);
+    const double i_as =
+        (denom > 0.0)
+            ? (i_ext * cz * 0.79 * t_o * t_um * t_w * t_aa *
+               (0.5 * (1.0 - t_r) + kBa * (1.0 - t_as)) / denom)
+            : 0.0;
+
+    // Sky-ground multiple reflection. `ground_albedo` is the LAND surface,
+    // not the water's `RadiativeConfig::albedo` — see SolarConfig.
+    const double rs = 0.0685 + (1.0 - kBa) * (1.0 - t_as);
+    const double refl_denom = 1.0 - cfg.ground_albedo * rs;
+
+    const double ghi =
+        (refl_denom > 0.0) ? ((i_d + i_as) / refl_denom) : (i_d + i_as);
+
+    return std::max(0.0, ghi);
+}
+
+// ===========================================================================
+// Cloud
+// ===========================================================================
+
+double cloudShortwaveFactor(double cloud_fraction, double k,
+                            double n) noexcept {
+    if (!(cloud_fraction > 0.0)) return 1.0;
+    const double c = std::min(1.0, cloud_fraction);
+    // max(0, ...) for the same reason netShortwave guards its shade factor:
+    // an over-unity product blocks completely, it does not invert the sign.
+    return std::max(0.0, 1.0 - k * std::pow(c, n));
+}
+
+double cloudLongwaveFactor(double cloud_fraction, double k_lw) noexcept {
+    // A LITERAL 1.0, not `1 + k·0²`. The clear-sky longwave path must be
+    // bit-identical to H3's, not merely equal to it within rounding — plan
+    // §2.5 makes that a verify criterion, and `1 + k*0*0` is not guaranteed
+    // to be exactly 1.0 for every k under every rounding mode.
+    if (!(cloud_fraction > 0.0)) return 1.0;
+    const double c = std::min(1.0, cloud_fraction);
+    return 1.0 + k_lw * c * c;
+}
+
+// ===========================================================================
+// Per-step resolution
+// ===========================================================================
+
+void updateSolarForcing(SimulationContext& ctx) noexcept {
+    auto& hs = ctx.heat_state;
+
+    // Unobserved work is not free and not tested (lesson 39): under any
+    // configuration that never reads these, do not compute them.
+    //
+    // `shortwave_now` goes back to the UNRESOLVED sentinel rather than to
+    // 0: `radiativeFluxOut` returns early under this same condition, so
+    // nothing reads it, and leaving a resolved-looking 0 behind would make
+    // a later read silently lose the configured constant.
+    if (!ctx.options.heat_transport || !ctx.heat_config.radiative_exchange) {
+        hs.shortwave_now = -1.0;
+        hs.cloud_now     = 0.0;
+        return;
+    }
+
+    const auto& rc = ctx.heat_config.radiative;
+    const auto& cc = ctx.heat_config.cloud;
+
+    // ---- Cloud fraction first: the shortwave path needs it.
+    double cloud = 0.0;
+    if (cc.configured) {
+        if (cc.use_timeseries) {
+            if (cc.ts_index >= 0 &&
+                cc.ts_index < static_cast(ctx.tables.count())) {
+                cloud = table_tseries_lookup_cursor(ctx.tables[cc.ts_index],
+                                                    ctx.current_date);
+            }
+        } else {
+            cloud = cc.fraction;
+        }
+    }
+    // A cloud series is user data and may carry percent, a stray negative,
+    // or an interpolation past its end. Clamp rather than refuse: unlike a
+    // config fraction (refused at parse time, where the user can still fix
+    // it), a series value arrives mid-run where there is no one to ask.
+    hs.cloud_now = std::max(0.0, std::min(1.0, cloud));
+
+    // ---- Incoming shortwave.
+    double jin = 0.0;
+    switch (rc.sw_mode) {
+        case ShortwaveMode::CONSTANT:
+            jin = rc.shortwave_wm2;
+            break;
+
+        case ShortwaveMode::TIMESERIES:
+            if (rc.sw_ts_index >= 0 &&
+                rc.sw_ts_index < static_cast(ctx.tables.count())) {
+                // tseries lookup (not table_lookup_cursor): returns 0 past
+                // the end of the series rather than clamping to the last
+                // value forever. A solar record that ran out should go dark,
+                // not hold yesterday's noon indefinitely.
+                jin = table_tseries_lookup_cursor(ctx.tables[rc.sw_ts_index],
+                                                  ctx.current_date);
+            }
+            break;
+
+        case ShortwaveMode::COMPUTED: {
+            const auto& sc = ctx.heat_config.solar;
+            // The parser refuses COMPUTED without both coordinates, so
+            // reaching here without them is a programming error, not a deck
+            // error. Fail dark rather than at latitude 0 — an equatorial
+            // answer is the exact plausible-but-wrong result plan §2.5
+            // trap 1 is about.
+            if (!sc.has_latitude || !sc.has_longitude) {
+                jin = 0.0;
+                break;
+            }
+
+            const double doy = static_cast(
+                datetime::dayOfYear(ctx.current_date));
+            // Fractional local hour from the OADate's time part.
+            const double day_frac = ctx.current_date - std::floor(ctx.current_date);
+            const double hour_local = day_frac * 24.0;
+
+            const auto pos = solarPosition(static_cast(doy), hour_local,
+                                           sc.latitude_deg, sc.longitude_deg,
+                                           sc.timezone_hours);
+
+            // Elevation: the deck's explicit value if given, else the
+            // climate state's `elev`, which is FEET.
+            //
+            // Keyed on the FLAG, not on the sign. A `< 0` test was the
+            // first spelling and silently discarded every below-sea-level
+            // site the parser deliberately admits.
+            const double elev_m = sc.has_elevation
+                                      ? sc.elevation_m
+                                      : ctx.climate_state.elev * kFtToM;
+
+            jin = birdClearSkyGHI(pos, pressureFromElevation(elev_m), sc);
+            break;
+        }
+    }
+
+    // Cloud attenuates every spelling, not only COMPUTED. A measured
+    // pyranometer series already contains the clouds that were there, so
+    // configuring BOTH double-counts — the parser warns; see HeatComponent.
+    jin *= cloudShortwaveFactor(hs.cloud_now, cc.sw_atten_k, cc.sw_atten_n);
+
+    hs.shortwave_now = std::max(0.0, jin);
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/SolarRadiation.hpp b/src/engine/transport/components/HeatFluxModules/SolarRadiation.hpp
new file mode 100644
index 000000000..8462b3ca8
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/SolarRadiation.hpp
@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SolarRadiation.hpp
+ * @brief Phase H6a — where incoming shortwave `Jin` comes from
+ *        (heat plan §2.5, D-H6a).
+ *
+ * @details H3 took `Jin` as a static constant. This module adds the two
+ *          other spellings of plan §2.5: an interpolated timeseries, and a
+ *          computed clear-sky value from solar position — plus the cloud
+ *          parameterization that modulates BOTH shortwave and longwave.
+ *
+ *          Nothing here is a flux family. This module produces a number in
+ *          W/m² and hands it to H3's existing `netShortwave`; it adds no
+ *          term to `netFluxOut`, touches no sign convention, and introduces
+ *          no element state. That is why H6a is separable from H6b.
+ *
+ * @par Solar position: NOAA/Spencer, NOT NREL SPA — and why (D-H6a-4, as
+ *      amended 2026-08-30)
+ *      The plan first specified NREL SPA for its published test vectors.
+ *      Implementing it faithfully needs ~260 rows of periodic-term
+ *      constants (truncated VSOP87 L/B/R plus the IAU 1980 nutation
+ *      series). Transcribing those without the source document in reach
+ *      means the TABLES and the TEST VECTOR would both be recalled — and a
+ *      consistently misremembered pair gates green on wrong physics. That
+ *      is the H3 Brunt-in-kPa failure (a plausible wrong number that only a
+ *      true reference catches) at 260× the surface area, with the reference
+ *      itself compromised.
+ *
+ *      So the position solver here is the Spencer (1971) / NOAA formulation:
+ *      ~40 lines, no constant tables, **verifiable by inspection**, and
+ *      independently cross-checkable against two things already in this
+ *      engine — `Climate.cpp:178`'s declination and its sunrise/sunset
+ *      hours. Stated accuracy is ~0.1° in declination and ~0.5 min in the
+ *      equation of time, against SPA's ±0.0003°.
+ *
+ *      **That error is not the binding one.** A 0.1° zenith error moves
+ *      clear-sky GHI by well under 0.1%; the cloud fraction multiplying it
+ *      is a whole-number guess. Spending 400 lines of unverifiable
+ *      constants to refine the small term under the large one is the wrong
+ *      trade.
+ *
+ * @par The SPA swap point
+ *      `solarPosition()` is the ONLY function that knows how a position is
+ *      obtained. Everything downstream consumes `SolarPosition`. Landing
+ *      SPA later is a new implementation of that one function plus a
+ *      `SolarAlgorithm` selector — no caller changes. Do it with NREL's
+ *      published C source open, so the tables can be DIFFED rather than
+ *      recalled, and gate it against the report's worked example.
+ *
+ * @par Clear-sky: Bird & Hulstrom (1981)
+ *      Broadband direct + diffuse on a horizontal surface. Five
+ *      transmittance terms (Rayleigh, ozone, mixed gases, water vapour,
+ *      aerosol) and a sky-ground multiple-reflection correction. Defaults
+ *      are the paper's standard atmosphere.
+ *
+ * @warning The Bird coefficients below are transcribed from the published
+ *          formulation. The validation handoff instructs the checking agent
+ *          to re-derive them from the paper before trusting any gate that
+ *          uses them — see `H6A_VALIDATION_HANDOFF_2026-08-30.md` §2.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §6 H6a, §6.4
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_SOLAR_RADIATION_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_SOLAR_RADIATION_HPP
+
+namespace openswmm {
+struct SimulationContext;
+struct SolarConfig;
+struct CloudConfig;
+}
+
+namespace openswmm::transport::heat {
+
+/// Solar constant, W/m² (Bird & Hulstrom 1981; WMO 1982).
+inline constexpr double kSolarConstant = 1367.0;
+
+/// Sea-level standard pressure, millibars — Bird's pressure reference.
+inline constexpr double kStdPressureMb = 1013.25;
+
+/**
+ * @brief Sun geometry at one instant. The SPA swap point's return type.
+ *
+ * @details Angles in DEGREES. `cos_zenith` is carried alongside `zenith_deg`
+ *          because every downstream consumer wants the cosine and rounding
+ *          a degree value back through `cos` twice is how a night-time
+ *          `cos_zenith` acquires a small positive value.
+ */
+struct SolarPosition {
+    double declination_deg = 0.0;  ///< Solar declination, +N
+    double eq_time_min     = 0.0;  ///< Equation of time, minutes
+    double hour_angle_deg  = 0.0;  ///< Solar hour angle, 0 at solar noon
+    double zenith_deg      = 90.0; ///< Solar zenith angle
+    double cos_zenith      = 0.0;  ///< Clamped at 0 below the horizon
+    double elevation_deg   = 0.0;  ///< 90 − zenith (may be negative)
+    /// Earth–sun distance correction `E0 = (r0/r)²`, dimensionless.
+    double eccentricity    = 1.0;
+};
+
+/**
+ * @brief Sun position by the Spencer (1971) / NOAA formulation.
+ *
+ * @param day_of_year 1–366.
+ * @param hour_local  Local clock hour, decimal (13.5 = 13:30).
+ * @param lat_deg     Latitude, +N.
+ * @param lon_deg     Longitude, +E.
+ * @param tz_hours    Offset from UTC, +E (MST = −7).
+ *
+ * @note This is the function SPA replaces. Nothing else in this module
+ *       knows how a position is obtained.
+ */
+SolarPosition solarPosition(int day_of_year, double hour_local, double lat_deg,
+                            double lon_deg, double tz_hours) noexcept;
+
+/// Kasten–Young relative optical air mass. Returns 0 below the horizon,
+/// which is what makes every Bird transmittance collapse to a dark result
+/// rather than to a domain error.
+double airMass(double zenith_deg) noexcept;
+
+/// Station pressure [mb] from elevation [m], standard atmosphere.
+double pressureFromElevation(double elevation_m) noexcept;
+
+/**
+ * @brief Bird & Hulstrom clear-sky global horizontal irradiance [W/m²].
+ *
+ * @param pos           Sun geometry from `solarPosition`.
+ * @param pressure_mb   Station pressure.
+ * @param cfg           Aerosol / water / ozone / ground albedo.
+ * @returns 0 when the sun is at or below the horizon.
+ */
+double birdClearSkyGHI(const SolarPosition& pos, double pressure_mb,
+                       const SolarConfig& cfg) noexcept;
+
+/**
+ * @brief Cloud attenuation of shortwave, `1 − k·C^n` (Kasten–Czeplak).
+ *
+ * @details Clamped at 0: an over-unity `k·C^n` blocks completely rather
+ *          than turning into negative insolation — the same guard
+ *          `netShortwave` applies to an over-unity shade factor.
+ */
+double cloudShortwaveFactor(double cloud_fraction, double k, double n) noexcept;
+
+/**
+ * @brief Cloud enhancement of atmospheric emissivity, `1 + k_lw·C²` (Bolz).
+ *
+ * @warning This multiplies into H3's RHE-gated Brunt term. It returns a
+ *          LITERAL 1.0 when `cloud_fraction <= 0`, rather than evaluating
+ *          `1 + k·0²`, so the clear-sky path is bit-identical to H3 rather
+ *          than merely equal to it. Plan §2.5 makes that a verify criterion.
+ */
+double cloudLongwaveFactor(double cloud_fraction, double k_lw) noexcept;
+
+/**
+ * @brief Resolve `Jin` and `C` for this step into `ctx.heat_state`.
+ *
+ * @details Call at the PROLOGUE of every binding that will go on to call
+ *          `netFluxOut`. There are four (`applyHeatFluxes`, the ARD
+ *          binding, the watershed binding, the LID binding) and they run on
+ *          two different clocks, so a single call site upstream of all of
+ *          them does not exist. The function is idempotent within a step
+ *          and costs ~40 flops, which is why repeating it is cheaper than
+ *          inventing a scheduler to avoid repeating it.
+ *
+ * @note No-op unless HEAT_TRANSPORT is on and RADIATIVE_EXCHANGE is
+ *       enabled — under any other configuration `shortwave_now` is never
+ *       read, and computing it would be the kind of unobserved work
+ *       lesson 39 is about.
+ */
+void updateSolarForcing(SimulationContext& ctx) noexcept;
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_SOLAR_RADIATION_HPP
diff --git a/src/engine/transport/components/HeatFluxModules/SurfaceExchange.cpp b/src/engine/transport/components/HeatFluxModules/SurfaceExchange.cpp
new file mode 100644
index 000000000..26f31a8f7
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/SurfaceExchange.cpp
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SurfaceExchange.cpp
+ * @brief Phase H2 body — latent/sensible surface exchange.
+ *
+ * @details D-H5e moved the node and link BINDING out of this file into
+ *          HeatFluxes.cpp. What remains is the formulation plus one
+ *          evaluator, `surfaceFluxOut`, which is this module's contribution
+ *          to a single net flux. Owning a binding of its own is what let
+ *          this module and RadiativeExchange each relax separately toward
+ *          their own equilibrium.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SurfaceExchange.hpp"
+
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+
+namespace openswmm::transport::heat {
+
+namespace {
+
+/// The module's own net outward flux at a given water temperature, W/m².
+/// Written once because `relaxT` needs it evaluated TWICE per element — at
+/// `T` and at `T + kProbeC` — and two hand-inlined copies of a three-call
+/// expression is how a probe silently comes to measure a different function
+/// than the one being stepped.
+double netFluxOut(double t_w, double t_air, double rh, double wind_ms,
+                  double a, double b, double rho, double p_ratio) noexcept {
+    const double je = latentFlux(t_w, t_air, rh, wind_ms, a, b, rho);
+    return je + sensibleFlux(je, bowenRatio(t_w, t_air, rh, p_ratio));
+}
+
+}  // namespace
+
+double airTempCelsius(const SimulationContext& ctx) noexcept {
+    return (ctx.climate_state.temperature - 32.0) * 5.0 / 9.0;
+}
+
+double relaxT(double j0, double j1, double h, double area_m2, double vol_m3,
+              double dt, double rho, double cp) noexcept {
+    const double heat_capacity = rho * cp * vol_m3;
+    if (!(heat_capacity > 0.0) || !(area_m2 > 0.0) || !(dt > 0.0)) return 0.0;
+
+    // The explicit step, kept as the fallback and as the small-dt limit this
+    // must agree with. It is deliberately NOT exported: it is the form that
+    // diverged, and the only safe place to reach it is from inside here.
+    const double explicit_dT = -j0 * area_m2 * dt / heat_capacity;
+    if (!(h > 0.0)) return explicit_dT;
+
+    const double djdt = (j1 - j0) / h;                 // W/m²/°C
+    // J′ ≤ 0 means the outward flux does not grow with temperature, so the
+    // linearized system has no fixed point to relax onto. There is nothing
+    // to be stable about, so take the explicit step and let the caller's
+    // finiteness check catch it.
+    if (!(djdt > 0.0)) return explicit_dT;
+
+    const double k = area_m2 * djdt / heat_capacity;   // 1/s
+    if (!(k > 0.0)) return explicit_dT;
+
+    // ΔT = (J₀/J′)·expm1(−k·dt). expm1 rather than exp(x)−1 so the small-dt
+    // limit is accurate to full precision instead of cancelling to noise —
+    // that limit is what makes this agree with H2/H3's existing answers.
+    const double dT = (j0 / djdt) * std::expm1(-k * dt);
+    return std::isfinite(dT) ? dT : explicit_dT;
+}
+
+double equilibriumT(double t0_c, double j0, double j1, double h) noexcept {
+    if (!(h > 0.0)) return t0_c;
+    const double djdt = (j1 - j0) / h;
+    if (!(djdt > 0.0)) return t0_c;
+    return t0_c - j0 / djdt;
+}
+
+double saturationVapourPressure(double t_c) noexcept {
+    return 0.61275 * std::exp(17.27 * t_c / (237.3 + t_c));
+}
+
+double latentHeatOfVaporization(double t_c) noexcept {
+    return 1000.0 * (2499.0 - 2.36 * t_c);
+}
+
+double windFunction(double wind_ms, double a, double b) noexcept {
+    return a + b * std::max(wind_ms, 0.0);
+}
+
+double evaporationRate(double t_water_c, double t_air_c, double humidity_pct,
+                       double wind_ms, double a, double b) noexcept {
+    const double es_w = saturationVapourPressure(t_water_c);
+    const double e_a  = (humidity_pct / 100.0) *
+                        saturationVapourPressure(t_air_c);
+    return windFunction(wind_ms, a, b) * (es_w - e_a);
+}
+
+double latentFlux(double t_water_c, double t_air_c, double humidity_pct,
+                  double wind_ms, double a, double b,
+                  double water_density) noexcept {
+    const double e = evaporationRate(t_water_c, t_air_c, humidity_pct,
+                                     wind_ms, a, b);
+    return water_density * latentHeatOfVaporization(t_water_c) * e;
+}
+
+double bowenRatio(double t_water_c, double t_air_c, double humidity_pct,
+                  double pressure_ratio) noexcept {
+    const double es_w = saturationVapourPressure(t_water_c);
+    const double e_a  = (humidity_pct / 100.0) *
+                        saturationVapourPressure(t_air_c);
+    const double deficit = es_w - e_a;
+    // Removable singularity: as the deficit vanishes so does Je, and Jc =
+    // Br·Je tends to a finite limit. Returning 0 here keeps Jc finite
+    // instead of producing inf/NaN that would then propagate into every
+    // downstream temperature.
+    if (std::fabs(deficit) < 1.0e-12) return 0.0;
+    return kBowenCoeff * pressure_ratio * (t_water_c - t_air_c) / deficit;
+}
+
+double sensibleFlux(double latent_flux, double bowen_ratio) noexcept {
+    return bowen_ratio * latent_flux;
+}
+
+double surfaceFluxOut(const SimulationContext& ctx,
+                      const HeatElement& elem, double t_w) noexcept {
+    if (!ctx.options.heat_transport || !ctx.heat_config.surface_exchange)
+        return 0.0;
+    // PE4: air temperature, humidity and wind are GLOBAL in the deck and
+    // per-element only through the forcing API. Resolving them HERE rather
+    // than writing them into `climate_state` is what keeps a per-link push
+    // out of snowmelt and evaporation — see ForcingData::elementClimate.
+    const double t_air = ctx.forcing.elementAirTempF(elem,
+                             ctx.climate_state.temperature);
+    const double rh    = ctx.forcing.elementHumidity(elem,
+                             ctx.climate_state.humidity);
+    const double wind  = ctx.forcing.elementWindMph(elem,
+                             ctx.climate_state.wind_speed);
+    return netFluxOut(t_w, (t_air - 32.0) * 5.0 / 9.0, rh, wind * kMphToMs,
+                      ctx.options.wind_func_coeff_a,
+                      ctx.options.wind_func_coeff_b,
+                      ctx.options.water_density,
+                      ctx.options.pressure_ratio);
+}
+
+}  // namespace openswmm::transport::heat
diff --git a/src/engine/transport/components/HeatFluxModules/SurfaceExchange.hpp b/src/engine/transport/components/HeatFluxModules/SurfaceExchange.hpp
new file mode 100644
index 000000000..dbc7281bb
--- /dev/null
+++ b/src/engine/transport/components/HeatFluxModules/SurfaceExchange.hpp
@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SurfaceExchange.hpp
+ * @brief Phase H2 — latent and sensible heat exchange at the water surface
+ *        (heat plan §2.1; CSHComponent §4.4–4.5).
+ *
+ * @details The formulations are exposed as PURE FUNCTIONS above the engine
+ *          binding on purpose: they are the part with published reference
+ *          values (CSH Table 4.1, Dingman 2008, Martin & McCutcheon 1998),
+ *          so they can be gated against numbers from outside this codebase
+ *          rather than against the engine's own output.
+ *
+ *          - `e_s(T) = 0.61275 exp(17.27 T / (237.3 + T))`   [kPa]
+ *          - `Le(T)  = 1000 (2499 − 2.36 T)`                 [J/kg]
+ *          - `f(w)   = a + b w`                              [m/s/kPa]
+ *          - `E      = f(w) (e_s(Tw) − e_a)`                 [m/s]
+ *          - `Je     = ρw Le E`                              [W/m²]
+ *          - `Br     = CB (Pa/P) (Tw − Ta) / (e_s(Tw) − e_a)`
+ *          - `Jc     = Br Je`                                [W/m²]
+ *
+ * @par Sign convention
+ *      `Je` and `Jc` are positive when heat LEAVES the water — evaporation
+ *      cools. The governing equation (plan §1) carries them as
+ *      `− (Je + Jc) / Y`, and `relaxT` applies that sign, so a
+ *      caller never has to remember it.
+ *
+ * @par Which surfaces exchange, and why that question has a precedent
+ *      Heat crosses the free surface exactly where evaporation does, so this
+ *      module uses the ENGINE'S OWN evaporation surfaces rather than a new
+ *      area model:
+ *        - storage nodes → `node::getSurfArea` (`Routing.cpp:490`),
+ *        - open conduits → `xsect::getWofY(y) · length · barrels`
+ *          (`Routing.cpp:597`, `DynamicWave.cpp:2028`),
+ *        - junctions, outfalls, dividers and CLOSED conduits → no free
+ *          surface, no exchange (legacy's convention: `getSurfArea` returns
+ *          0 for them and `xsect::isOpen` gates the conduit branch).
+ *      Both of those are solver-independent — `initNodeFlows` and
+ *      `computeConduitLosses` run under every routing model — which is what
+ *      keeps this module from silently doing nothing under STEADY or
+ *      KINWAVE. That was the open question when H2 was scoped.
+ *
+ * @par Units
+ *      The engine is foot-second internally; these formulations are SI.
+ *      Conversion happens once, at the binding, and is named
+ *      `kSqFtToSqM` / `kCuFtToCuM` rather than folded into a magic number.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §2.1, §2.4, §6 H2
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_SURFACE_EXCHANGE_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_SURFACE_EXCHANGE_HPP
+
+#include "../../../data/HeatOverrideData.hpp"   // HeatElement (PE1)
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport::heat {
+
+/// Bowen's coefficient, kPa/°C (CSH §4.5).
+inline constexpr double kBowenCoeff = 0.061;
+
+/// Saturation vapour pressure over water at `t_c` degrees Celsius [kPa].
+double saturationVapourPressure(double t_c) noexcept;
+
+/// Latent heat of vaporization at `t_c` degrees Celsius [J/kg]
+/// (Martin & McCutcheon 1998).
+double latentHeatOfVaporization(double t_c) noexcept;
+
+/// Mass-transfer wind function `a + b·w`, w in m/s [m/s/kPa].
+double windFunction(double wind_ms, double a, double b) noexcept;
+
+/// Evaporative mass-transfer rate [m/s]. Negative under condensation.
+double evaporationRate(double t_water_c, double t_air_c, double humidity_pct,
+                       double wind_ms, double a, double b) noexcept;
+
+/// Latent heat flux [W/m²], POSITIVE out of the water.
+double latentFlux(double t_water_c, double t_air_c, double humidity_pct,
+                  double wind_ms, double a, double b,
+                  double water_density) noexcept;
+
+/// Bowen ratio [-]. Returns 0 when the vapour-pressure deficit vanishes,
+/// which is the removable singularity in `Br`'s definition, not an error.
+double bowenRatio(double t_water_c, double t_air_c, double humidity_pct,
+                  double pressure_ratio) noexcept;
+
+/// Sensible heat flux [W/m²], POSITIVE out of the water.
+double sensibleFlux(double latent_flux, double bowen_ratio) noexcept;
+
+/// Air temperature in °C. `ClimateState` carries °F (a legacy convention);
+/// every formulation in this program is Celsius. Exported at H5a so the
+/// watershed binding cannot acquire a second, drifting copy of the
+/// conversion — there is exactly one place that knows the units.
+double airTempCelsius(const SimulationContext& ctx) noexcept;
+
+/// Probe offset for the flux derivative, °C. Small enough that `J′` is the
+/// local slope, large enough that the difference is not float noise.
+inline constexpr double kProbeC = 1.0e-3;
+
+/**
+ * @brief One element's temperature change, integrated SEMI-IMPLICITLY [°C].
+ *
+ * @details Plan D-H5d. The energy balance `ρ cp V dT/dt = −A·J(T)` is
+ *          linearized about the current temperature and the resulting linear
+ *          ODE is integrated exactly:
+ *
+ *          ```
+ *          k    = A·J′ / (ρ cp V)        [1/s]
+ *          T_eq = T₀ − J₀/J′
+ *          ΔT   = (J₀/J′)·expm1(−k·dt)
+ *          ```
+ *
+ *          **This replaces a forward-Euler step that diverged to NaN.** Heat
+ *          capacity is `ρ cp V`, so a thin film has almost none: a 0.52 ft³
+ *          film over 27,226 ft² took a +862 °C step in 60 s and the sequence
+ *          ran `5 → 182 → −1.8e4 → −3.9e9 → inf → NaN`. The explicit form had
+ *          simply stopped representing the ODE.
+ *
+ *          Three properties earned this scheme its place, and each is gated:
+ *          - **`|ΔT| ≤ |T_eq − T₀|` always** — the step cannot overshoot
+ *            equilibrium, whatever `dt` is. That is an assertion needing no
+ *            reference value, so no deck or timestep change can stale it.
+ *          - **No iteration**, hence no cap to tune and no failure mode when
+ *            the cap is reached.
+ *          - **Degrades to forward Euler as `dt → 0`** (`expm1(−x) ≈ −x`),
+ *            so every small-step answer is unchanged from H2/H3.
+ *
+ *          The flux FORMULATIONS of H2 and H3 were never wrong; only the
+ *          stepping was. CSH runs these same formulas at a 1e-4 s timestep
+ *          with a selectable ODE solver — we took its physics and not its
+ *          integrator.
+ *
+ * @param j0      Net flux OUT of the water at `T₀`, W/m² (sum of every
+ *                enabled module: `Je + Jc` from here, `Jr` from
+ *                RadiativeExchange — all signed positive out, so they add).
+ * @param j1      The same sum re-evaluated at `T₀ + h`.
+ * @param h       The probe offset used for `j1`; `kProbeC` unless testing.
+ * @param area_m2 Exchange area.
+ * @param vol_m3  Element volume — the thermal mass, and the reason this
+ *                function exists.
+ *
+ * @return ΔT in °C. Zero for a volume-less or area-less element. Falls back
+ *         to the explicit step when `J′ ≤ 0` (anti-damping: the linearized
+ *         system has no fixed point to relax onto, so there is nothing to be
+ *         stable about).
+ */
+double relaxT(double j0, double j1, double h, double area_m2, double vol_m3,
+              double dt, double rho, double cp) noexcept;
+
+/// The equilibrium temperature the linearization relaxes toward, °C —
+/// `T₀ − J₀/J′`. Exported so a gate can assert the no-overshoot property
+/// against it directly rather than recomputing the slope by hand.
+/// Returns `t0_c` when `J′ ≤ 0`, matching `relaxT`'s fallback.
+double equilibriumT(double t0_c, double j0, double j1, double h) noexcept;
+
+/// ft² → m². Exported with `relaxT`, which is useless without it.
+inline constexpr double kSqFtToSqM = 0.09290304;
+/// ft³ → m³.
+inline constexpr double kCuFtToCuM = 0.028316846592;
+/// mph → m/s. `ClimateState::wind_speed` is mph.
+inline constexpr double kMphToMs = 0.44704;
+
+/**
+ * @brief This module's contribution to the net outward flux at `t_w` [W/m²].
+ *
+ * @details Returns 0 unless HEAT_TRANSPORT is on AND `[HEAT_FLUXES]
+ *          SURFACE_EXCHANGE` is enabled, so a caller sums it
+ *          unconditionally and the toggle stays this module's business.
+ *
+ * @par Why this module no longer has a binding of its own (D-H5e)
+ *      It did, and so did RadiativeExchange, and each relaxed FULLY toward
+ *      its own equilibrium. Under forward Euler the two increments were
+ *      linear and added exactly; under relaxation they do NOT commute, so
+ *      with both modules on the pair overshot the true combined equilibrium
+ *      and the answer depended on module order — at large `k·dt` it landed
+ *      on whichever module ran last. Every flux family now sums into one
+ *      `J(T)` before a single relaxation, in `HeatFluxes.cpp`.
+ */
+double surfaceFluxOut(const SimulationContext& ctx,
+                      const HeatElement& elem, double t_w) noexcept;
+
+}  // namespace openswmm::transport::heat
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_SURFACE_EXCHANGE_HPP
diff --git a/src/engine/transport/components/HeatModule/HeatComponent.cpp b/src/engine/transport/components/HeatModule/HeatComponent.cpp
new file mode 100644
index 000000000..34c649869
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatComponent.cpp
@@ -0,0 +1,1379 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatComponent.cpp
+ * @brief heat component apply hook — phase H1 body.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatComponent.hpp"
+
+#include 
+#include 
+#include 
+#include    // IO3a: snprintf in fmt_degc
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../plugins/ProcessComponentRegistry.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr const char* kHeatId = "org.hydrocouple.openswmm.heat";
+
+/// Physically motivated guard rails on an inlet temperature (°C). Liquid
+/// water outside this band is not a modelling case H1 supports, and a
+/// typo (a Fahrenheit value, a stray exponent) is far more likely than a
+/// deck that means it.
+constexpr double kMinTemp = -50.0;
+constexpr double kMaxTemp = 100.0;
+
+std::vector tokenize(const std::string& line) {
+    std::vector toks;
+    std::string cur;
+    for (const char ch : line) {
+        if (ch == ' ' || ch == '\t') {
+            if (!cur.empty()) { toks.push_back(cur); cur.clear(); }
+        } else {
+            cur.push_back(ch);
+        }
+    }
+    if (!cur.empty()) toks.push_back(cur);
+    return toks;
+}
+
+std::string upper(std::string s) {
+    std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) {
+        return static_cast(std::toupper(c));
+    });
+    return s;
+}
+
+/// Strict finite number. `std::strtod` ACCEPTS "nan" and "inf", and every
+/// range test in this file is written as `v < lo || v > hi` — both of which
+/// are FALSE for NaN, so a NaN sails through every guard and lands in the
+/// config looking like a value. H6a found this on the new [SOLAR_RADIATION]
+/// parser; it is checked here so the new sections cannot reintroduce it.
+///
+/// @note `parse_celsius` never had the hole — its range test is the
+///       conjunctive ACCEPT form (`v >= lo && v <= hi`), which NaN fails.
+///       The `[RADIATIVE_FLUXES]` ladder did, via its reject-form `frac()`
+///       guard; its parse now comes through here (step 3 validation round).
+bool parse_finite(const std::string& tok, double& out) {
+    char* end = nullptr;
+    out = std::strtod(tok.c_str(), &end);
+    if (end == nullptr || *end != '\0' || end == tok.c_str()) return false;
+    return std::isfinite(out);
+}
+
+/// Unlike the age parser's `parse_hours`, this accepts NEGATIVE values —
+/// sub-zero water temperatures are ordinary — so the range check is
+/// explicit rather than riding on a `>= 0` test.
+bool parse_celsius(const std::string& tok, double& out) {
+    char* end = nullptr;
+    out = std::strtod(tok.c_str(), &end);
+    if (end == nullptr || *end != '\0' || end == tok.c_str()) return false;
+    return out >= kMinTemp && out <= kMaxTemp;
+}
+
+int source_of(const std::string& u) {
+    if (u == "RAINFALL")        return static_cast(HeatSource::RAINFALL);
+    if (u == "DWF")             return static_cast(HeatSource::DWF);
+    if (u == "GW")              return static_cast(HeatSource::GW);
+    if (u == "RDII")            return static_cast(HeatSource::RDII);
+    if (u == "EXTERNAL_INFLOW") return static_cast(HeatSource::EXTERNAL_INFLOW);
+    if (u == "IFACE")           return static_cast(HeatSource::IFACE);
+    if (u == "INITIAL_STATE")   return static_cast(HeatSource::INITIAL_STATE);
+    return -1;
+}
+
+/// Inverse of source_of, for IO3a serialization. Table order matches the
+/// enum, so a new HeatSource that forgets this array trips the static_assert
+/// rather than silently writing the wrong keyword.
+const char* source_name(int s) {
+    static const char* kNames[] = {"RAINFALL", "DWF", "GW", "RDII",
+                                   "EXTERNAL_INFLOW", "IFACE",
+                                   "INITIAL_STATE"};
+    static_assert(sizeof(kNames) / sizeof(kNames[0]) ==
+                      static_cast(HeatSource::COUNT_),
+                  "source_name is missing a HeatSource");
+    return (s >= 0 && s < static_cast(HeatSource::COUNT_))
+               ? kNames[s] : "?";
+}
+
+/// Shortest decimal that reads back EXACTLY — ReactionsWriter's fmt_double
+/// convention. A save that rounds is a save that moves the model.
+std::string fmt_degc(double v) {
+    char buf[64];
+    for (int prec = 15; prec <= 17; ++prec) {
+        std::snprintf(buf, sizeof(buf), "%.*g", prec, v);
+        if (std::strtod(buf, nullptr) == v) break;
+    }
+    return buf;
+}
+
+/**
+ * @brief PE2 — one attribute table shared by the parser, the resolver and
+ *        the serializer.
+ *
+ * @details `static_assert` against `HeatAttr::COUNT_` is load-bearing:
+ *          adding an attribute without teaching this table breaks the BUILD
+ *          rather than silently dropping the new key on save, which is the
+ *          IO3a/lesson-201 shape one enum over.
+ */
+struct AttrSpec {
+    const char* key;
+    HeatAttr    attr;
+    bool        is_fraction;   ///< refused outside [0,1]
+    bool        positive_only; ///< refused at or below zero
+};
+
+constexpr AttrSpec kAttrTable[] = {
+    {"ALBEDO",                 HeatAttr::ALBEDO,                  true,  false},
+    {"SHADE_FACTOR",           HeatAttr::SHADE_FACTOR,            true,  false},
+    {"SKY_VIEW",               HeatAttr::SKY_VIEW,                true,  false},
+    {"EMISS_WATER",            HeatAttr::EMISS_WATER,             true,  false},
+    {"EMISS_LANDCOVER",        HeatAttr::EMISS_LANDCOVER,         true,  false},
+    {"LANDCOVER_TEMPERATURE",  HeatAttr::LANDCOVER_TEMP,          false, false},
+    {"THERMAL_DIFFUSIVITY",    HeatAttr::SED_THERMAL_DIFFUSIVITY, false, true},
+    {"SOLUTE_DIFFUSIVITY",     HeatAttr::SED_SOLUTE_DIFFUSIVITY,  false, false},
+    {"BED_THICKNESS",          HeatAttr::SED_BED_THICKNESS,       false, true},
+    {"GROUND_DEPTH",           HeatAttr::SED_GROUND_DEPTH,        false, true},
+    {"GROUND_TEMPERATURE",     HeatAttr::SED_GROUND_TEMP,         false, false},
+    {"HYPORHEIC_VELOCITY",     HeatAttr::SED_HYPORHEIC_VELOCITY,  false, false},
+    {"SEDIMENT_DENSITY",       HeatAttr::SED_DENSITY,             false, true},
+    {"SEDIMENT_SPECIFIC_HEAT", HeatAttr::SED_SPECIFIC_HEAT,       false, true},
+};
+static_assert(sizeof(kAttrTable) / sizeof(kAttrTable[0]) ==
+                  static_cast(HeatAttr::COUNT_),
+              "HeatAttr gained a member: add it to kAttrTable so the parser "
+              "and saveHeatConfig both learn it, then this pin passes");
+
+const AttrSpec* findAttr(HeatAttr a) {
+    for (const auto& e : kAttrTable) if (e.attr == a) return &e;
+    return nullptr;
+}
+const char* attrKey(HeatAttr a) {
+    const AttrSpec* e = findAttr(a);
+    return e ? e->key : "?";
+}
+
+/// PE2 — the scope prefix of an override row. `value_at` is where the
+/// numeric token starts, so a caller reads `toks[value_at]` regardless of
+/// which scope was written.
+struct ScopeRef {
+    HeatScope   scope = HeatScope::GLOBAL;
+    std::string name;
+    int         value_at = 2;
+    bool        ok = false;
+};
+
+ScopeRef parseScope(const std::vector& toks,
+                    const std::string& section, const std::string& line,
+                    std::vector& errors) {
+    ScopeRef r;
+    if (toks.size() < 3) {
+        errors.push_back("[" + section + "] expects ' GLOBAL ' "
+                         "or ' TAG|LINK|NODE  ': '" +
+                         line + "'.");
+        return r;
+    }
+    const std::string sc = upper(toks[1]);
+    if (sc == "GLOBAL") {
+        r.scope = HeatScope::GLOBAL; r.value_at = 2; r.ok = true; return r;
+    }
+    if (sc == "TAG" || sc == "LINK" || sc == "NODE") {
+        if (toks.size() < 4) {
+            errors.push_back("[" + section + "] " + sc +
+                             " scope needs a name and a value: '" + line +
+                             "'.");
+            return r;
+        }
+        r.scope = (sc == "TAG")  ? HeatScope::TAG
+                : (sc == "LINK") ? HeatScope::LINK
+                                 : HeatScope::NODE;
+        r.name = toks[2];
+        r.value_at = 3;
+        r.ok = true;
+        return r;
+    }
+    errors.push_back("[" + section + "] unknown scope '" + toks[1] +
+                     "' (GLOBAL, TAG, LINK, NODE): '" + line + "'.");
+    return r;
+}
+
+/**
+ * @brief One validator for every scope (D-PE6).
+ *
+ * @details The GLOBAL path already refused rather than clamped; a
+ *          per-element path with its own copy is how a global refusal and a
+ *          per-element clamp end up in the same file disagreeing about the
+ *          same key.
+ */
+bool validateAttr(const AttrSpec& spec, double v, const std::string& section,
+                  const std::string& tok, std::vector& errors) {
+    if (spec.is_fraction && (v < 0.0 || v > 1.0)) {
+        errors.push_back("[" + section + "] '" + std::string(spec.key) +
+                         "' must be a fraction in [0,1], got " + tok + ".");
+        return false;
+    }
+    if (spec.positive_only && !(v > 0.0)) {
+        errors.push_back("[" + section + "] " + std::string(spec.key) +
+                         " must be greater than zero, got " + tok + ".");
+        return false;
+    }
+    if (spec.attr == HeatAttr::SED_HYPORHEIC_VELOCITY && v < 0.0) {
+        errors.push_back("[" + section + "] HYPORHEIC_VELOCITY cannot be "
+                         "negative: the exchange direction follows the "
+                         "gradient, not this sign. Got " + tok + ".");
+        return false;
+    }
+    if (spec.attr == HeatAttr::SED_SOLUTE_DIFFUSIVITY && v < 0.0) {
+        errors.push_back("[" + section + "] SOLUTE_DIFFUSIVITY cannot be "
+                         "negative, got " + tok + ".");
+        return false;
+    }
+    return true;
+}
+
+/// D-PE4 — two rows at the SAME scope for the same target mean the user
+/// believes one of them and cannot be told which won. Refused, following
+/// D-H6a-3 and the [REACTION_QUALITY] duplicate rule.
+bool recordOverride(SimulationContext& ctx, HeatAttr attr,
+                    const ScopeRef& sr, double v,
+                    const std::string& section, const std::string& line,
+                    std::vector& errors) {
+    auto& rows = ctx.heat_config.overrides.rows;
+    for (const auto& r : rows) {
+        if (r.attr == attr && r.scope == sr.scope && r.name == sr.name) {
+            errors.push_back("[" + section + "] duplicate " +
+                             std::string(attrKey(attr)) +
+                             " row at the same scope for '" + sr.name +
+                             "' — one of the two would silently win: '" +
+                             line + "'.");
+            return false;
+        }
+    }
+    rows.push_back(HeatOverrideRow{attr, sr.scope, sr.name, v});
+    return true;
+}
+
+void applyHeatSections(SimulationContext& ctx,
+                       const components::ComponentConfigSections& config,
+                       std::vector& errors) {
+    ctx.heat_config = HeatConfigData{};  // reopen hygiene
+    const std::size_t errors_before = errors.size();
+
+    // H6a (D-H6a-3). The three SHORTWAVE spellings are MUTUALLY EXCLUSIVE,
+    // so the parser has to remember whether it has seen one. A precedence
+    // ladder was the alternative and was rejected: it makes a deck that
+    // configures two sources run plausibly while silently discarding one.
+    bool shortwave_seen = false;
+
+    // Was an actual FRACTION row given, as opposed to coefficients alone?
+    // A [CLOUD_COVER] holding only k/n tunes a cloud fraction of zero,
+    // which is no cloud at all — worth saying so.
+    bool cloud_fraction_seen = false;
+
+    // Warnings are collected LOCALLY and merged into ctx only if the parse
+    // succeeds. Pushing them straight to `ctx.warnings` meant that an error
+    // anywhere in model.heat discarded the config via the reset below while
+    // the warnings survived — so on a lenient open the user was warned
+    // about a configuration that never took effect. Worse, a malformed
+    // COMPUTED row left `sw_mode` at CONSTANT and produced the advice
+    // "Set SHORTWAVE GLOBAL COMPUTED" to a user who had written exactly
+    // that.
+    std::vector pending_warnings;
+
+    for (const auto& sec : config.sections) {
+        // H2: [HEAT_FLUXES] toggles the plan §2 modules, one row per module.
+        // H3: [RADIATIVE_FLUXES] carries the plan §2.2 parameters. GLOBAL
+        // scope only; RHE's per-element ranges are a later phase.
+        if (sec.first == "RADIATIVE_FLUXES") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                const ScopeRef sr =
+                    parseScope(toks, "RADIATIVE_FLUXES", line, errors);
+                if (!sr.ok) continue;
+                auto& rc = ctx.heat_config.radiative;
+                const std::string k = upper(toks[0]);
+
+                // PE2 §2.2: SHORTWAVE stays GLOBAL. The deck states one
+                // incident resource and SHADE_FACTOR modulates it per
+                // element; making both per-element gives two ways to say one
+                // thing, and they will disagree. (A coupled driver CAN push
+                // Jin per element — through the forcing API, where the
+                // precedence is stated once. See ForcingData PE4.)
+                if (sr.scope != HeatScope::GLOBAL &&
+                    (k == "SHORTWAVE" || k == "ATM_EMISS_COEFF" ||
+                     k == "ATM_LW_REFLECTION")) {
+                    errors.push_back(
+                        "[RADIATIVE_FLUXES] " + toks[0] + " is GLOBAL only — "
+                        "it describes the incident resource or the "
+                        "atmosphere, not the reach. Per-element shading is "
+                        "SHADE_FACTOR / SKY_VIEW: '" + line + "'.");
+                    continue;
+                }
+
+                // H6a. SHORTWAVE is handled BEFORE the numeric parse for the
+                // same structural reason [HEAT_FLUXES] checks
+                // DRY_ELEMENT_TEMPERATURE before its ON|OFF test: two of its
+                // three spellings are keywords, not numbers, and a
+                // number-first test would reject them as "not a number"
+                // before their own branch could run — making the feature
+                // unreachable rather than merely unimplemented. That exact
+                // shape was the A1a defect.
+                if (k == "SHORTWAVE") {
+                    if (shortwave_seen) {
+                        errors.push_back(
+                            "[RADIATIVE_FLUXES] SHORTWAVE is given more than "
+                            "once. The constant, TIMESERIES and COMPUTED "
+                            "spellings are mutually exclusive — pick one "
+                            "(plan D-H6a-3).");
+                        continue;
+                    }
+                    const std::string spelling = upper(toks[2]);
+
+                    if (spelling == "COMPUTED") {
+                        if (toks.size() != 3) {
+                            errors.push_back(
+                                "[RADIATIVE_FLUXES] SHORTWAVE GLOBAL COMPUTED "
+                                "takes no further tokens: '" + line + "'.");
+                            continue;
+                        }
+                        rc.sw_mode = ShortwaveMode::COMPUTED;
+                        shortwave_seen = true;
+                        continue;
+                    }
+
+                    if (spelling == "TIMESERIES") {
+                        if (toks.size() != 4) {
+                            errors.push_back(
+                                "[RADIATIVE_FLUXES] SHORTWAVE GLOBAL "
+                                "TIMESERIES takes a series name: '" + line +
+                                "'.");
+                            continue;
+                        }
+                        const int ts = ctx.find_timeseries(toks[3]);
+                        if (ts < 0) {
+                            errors.push_back(
+                                "[RADIATIVE_FLUXES] SHORTWAVE TIMESERIES '" +
+                                toks[3] + "' is not a [TIMESERIES] in the "
+                                "model.");
+                            continue;
+                        }
+                        rc.sw_mode      = ShortwaveMode::TIMESERIES;
+                        rc.sw_ts_index  = ts;
+                        shortwave_seen  = true;
+                        continue;
+                    }
+
+                    // Constant — the H3 spelling, still the default.
+                    if (toks.size() != 3) {
+                        errors.push_back(
+                            "[RADIATIVE_FLUXES] malformed SHORTWAVE row: '" +
+                            line + "'.");
+                        continue;
+                    }
+                    double sw = 0.0;
+                    if (!parse_finite(toks[2], sw)) {
+                        errors.push_back(
+                            "[RADIATIVE_FLUXES] SHORTWAVE '" + toks[2] +
+                            "' is not a finite number, TIMESERIES, or "
+                            "COMPUTED.");
+                        continue;
+                    }
+                    if (sw < 0.0) {
+                        errors.push_back("[RADIATIVE_FLUXES] SHORTWAVE must "
+                                         "be >= 0 W/m2.");
+                        continue;
+                    }
+                    rc.shortwave_wm2 = sw;
+                    rc.sw_mode       = ShortwaveMode::CONSTANT;
+                    shortwave_seen   = true;
+                    continue;
+                }
+
+                const auto vt = static_cast(sr.value_at);
+                double v = 0.0;
+                if (vt >= toks.size() || !parse_finite(toks[vt], v)) {
+                    errors.push_back("[RADIATIVE_FLUXES] '" + toks[0] +
+                                     "': missing or non-finite value in '" +
+                                     line + "'.");
+                    continue;
+                }
+                // Fractions are refused outside [0,1] rather than clamped: a
+                // 97 typed for an emissivity of 0.97 would otherwise scale
+                // every longwave term by a hundred, silently. The two
+                // atmosphere keys keep their own GLOBAL-only writes below;
+                // everything else goes through the shared table so the
+                // GLOBAL and per-element paths validate identically (D-PE6).
+                if (k == "ATM_EMISS_COEFF" || k == "ATM_LW_REFLECTION") {
+                    if (v < 0.0 || v > 1.0) {
+                        errors.push_back("[RADIATIVE_FLUXES] '" + toks[0] +
+                                         "' must be a fraction in [0,1], got "
+                                         + toks[vt] + ".");
+                        continue;
+                    }
+                    if (k == "ATM_EMISS_COEFF") rc.atm_emiss_coeff = v;
+                    else                        rc.lw_reflection   = v;
+                    continue;
+                }
+
+                const AttrSpec* spec = nullptr;
+                for (const auto& e : kAttrTable)
+                    if (k == e.key && !isSedimentAttr(e.attr)) spec = &e;
+                if (spec == nullptr) {
+                    errors.push_back("[RADIATIVE_FLUXES] unknown parameter '" +
+                                     toks[0] + "'.");
+                    continue;
+                }
+                if (!validateAttr(*spec, v, "RADIATIVE_FLUXES", toks[vt],
+                                  errors))
+                    continue;
+
+                if (sr.scope == HeatScope::GLOBAL) {
+                    switch (spec->attr) {
+                        case HeatAttr::ALBEDO:          rc.albedo = v; break;
+                        case HeatAttr::SHADE_FACTOR:    rc.shade_factor = v; break;
+                        case HeatAttr::SKY_VIEW:        rc.sky_view = v; break;
+                        case HeatAttr::EMISS_WATER:     rc.emiss_water = v; break;
+                        case HeatAttr::EMISS_LANDCOVER: rc.emiss_landcover = v; break;
+                        case HeatAttr::LANDCOVER_TEMP:  rc.landcover_temp = v; break;
+                        default: break;
+                    }
+                } else {
+                    recordOverride(ctx, spec->attr, sr, v,
+                                   "RADIATIVE_FLUXES", line, errors);
+                }
+            }
+            continue;
+        }
+        // H6a. Site geometry and Bird atmosphere, consulted only under
+        // SHORTWAVE ... COMPUTED. Same ' GLOBAL ' shape as
+        // [RADIATIVE_FLUXES] so the two sections read alike.
+        if (sec.first == "SOLAR_RADIATION") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.size() != 3 || upper(toks[1]) != "GLOBAL") {
+                    errors.push_back(
+                        "[SOLAR_RADIATION] expects ' GLOBAL ': '"
+                        + line + "'.");
+                    continue;
+                }
+                double v = 0.0;
+                if (!parse_finite(toks[2], v)) {
+                    errors.push_back("[SOLAR_RADIATION] '" + toks[0] + "': '" +
+                                     toks[2] + "' is not a finite number.");
+                    continue;
+                }
+                auto& sc = ctx.heat_config.solar;
+                const std::string k = upper(toks[0]);
+
+                // Ranges are REFUSED, not clamped — the [RADIATIVE_FLUXES]
+                // precedent. A latitude of 100 is a typo, and silently
+                // saturating it to 90 would put the model at the pole.
+                //
+                // `ranged` RETURNS whether it assigned, and the "was this
+                // provided" flags are set from that return value. Setting
+                // them from a second copy of the range predicate instead
+                // was the first spelling, and it disagreed with the
+                // assignment for exactly one input class — NaN, which
+                // passes `!(v < lo || v > hi)` and so got assigned while
+                // the flag read false.
+                auto ranged = [&](double lo, double hi, double& dst,
+                                  const char* units) -> bool {
+                    if (v < lo || v > hi) {
+                        errors.push_back("[SOLAR_RADIATION] '" + toks[0] +
+                                         "' must be in [" + std::to_string(lo) +
+                                         ", " + std::to_string(hi) + "] " +
+                                         units + ", got " + toks[2] + ".");
+                        return false;
+                    }
+                    dst = v;
+                    return true;
+                };
+                auto nonneg = [&](double& dst) {
+                    if (v < 0.0)
+                        errors.push_back("[SOLAR_RADIATION] '" + toks[0] +
+                                         "' must be >= 0, got " + toks[2] +
+                                         ".");
+                    else dst = v;
+                };
+
+                if (k == "LATITUDE") {
+                    if (ranged(-90.0, 90.0, sc.latitude_deg, "degrees"))
+                        sc.has_latitude = true;
+                } else if (k == "LONGITUDE") {
+                    if (ranged(-180.0, 180.0, sc.longitude_deg, "degrees"))
+                        sc.has_longitude = true;
+                } else if (k == "TIMEZONE") {
+                    // ±14 covers every real offset (Kiribati is +14).
+                    if (ranged(-14.0, 14.0, sc.timezone_hours,
+                               "hours from UTC"))
+                        sc.has_timezone = true;
+                } else if (k == "ELEVATION") {
+                    // Metres. Below sea level is legal — and the flag, not
+                    // the sign, is what marks it as provided, so a negative
+                    // elevation is no longer indistinguishable from "unset".
+                    if (ranged(-500.0, 9000.0, sc.elevation_m, "metres"))
+                        sc.has_elevation = true;
+                } else if (k == "TURBIDITY_380")  { nonneg(sc.aod380);
+                } else if (k == "TURBIDITY_500")  { nonneg(sc.aod500);
+                } else if (k == "PRECIP_WATER")   { nonneg(sc.precip_water_cm);
+                } else if (k == "OZONE")          { nonneg(sc.ozone_cm);
+                } else if (k == "GROUND_ALBEDO")  {
+                    if (v < 0.0 || v > 1.0)
+                        errors.push_back("[SOLAR_RADIATION] GROUND_ALBEDO must "
+                                         "be a fraction in [0,1], got " +
+                                         toks[2] + ".");
+                    else sc.ground_albedo = v;
+                } else {
+                    errors.push_back(
+                        "[SOLAR_RADIATION] unknown parameter '" + toks[0] +
+                        "' (LATITUDE, LONGITUDE, TIMEZONE, ELEVATION, "
+                        "TURBIDITY_380, TURBIDITY_500, PRECIP_WATER, OZONE, "
+                        "GROUND_ALBEDO).");
+                }
+            }
+            continue;
+        }
+
+        // H6a (D-H6a-2). ONE fraction, TWO modules — shortwave attenuation
+        // and the longwave emissivity correction both read it.
+        // H6b — the bed / hyporheic zone. Every key is GLOBAL scope: the
+        // reference takes these per element from a coupled subsurface model
+        // and SWMM has no such supplier, so a per-element spelling would be
+        // a table nothing could fill. Rows are ' GLOBAL ', the
+        // same shape [CLOUD_COVER] and [RADIATIVE_FLUXES] already use.
+        if (sec.first == "SEDIMENT_EXCHANGE") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                const ScopeRef sr =
+                    parseScope(toks, "SEDIMENT_EXCHANGE", line, errors);
+                if (!sr.ok) continue;
+                auto& sd = ctx.heat_config.sediment;
+                const std::string k = upper(toks[0]);
+
+                // The bed zone is CONDUITS ONLY (BedZoneState), so a
+                // node-scoped bed attribute would describe a body that does
+                // not exist. Refused rather than accepted-and-ignored: a row
+                // that can never take effect is the silent-override failure
+                // D-PE5 exists to prevent.
+                if (sr.scope == HeatScope::NODE) {
+                    errors.push_back(
+                        "[SEDIMENT_EXCHANGE] NODE scope is not available — "
+                        "the bed zone exists beneath CONDUITS only. Use LINK "
+                        "or TAG: '" + line + "'.");
+                    continue;
+                }
+
+                // GROUND_TEMPERATURE is the one key with a TIMESERIES
+                // spelling: a deep-ground boundary that varies seasonally is
+                // the ordinary case, while a bed thickness that varies with
+                // time is not a thing a deck means.
+                if (k == "GROUND_TEMPERATURE" &&
+                    sr.scope == HeatScope::GLOBAL) {
+                    if (upper(toks[2]) == "TIMESERIES") {
+                        if (toks.size() != 4) {
+                            errors.push_back(
+                                "[SEDIMENT_EXCHANGE] GROUND_TEMPERATURE "
+                                "GLOBAL TIMESERIES takes a series name: '" +
+                                line + "'.");
+                            continue;
+                        }
+                        const int ts = ctx.find_timeseries(toks[3]);
+                        if (ts < 0) {
+                            errors.push_back(
+                                "[SEDIMENT_EXCHANGE] TIMESERIES '" + toks[3] +
+                                "' is not a [TIMESERIES] in the model.");
+                            continue;
+                        }
+                        sd.ground_ts_index  = ts;
+                        sd.has_ground_temp  = true;
+                        continue;
+                    }
+                }
+
+                const auto vt = static_cast(sr.value_at);
+                double v = 0.0;
+                if (vt >= toks.size() || !parse_finite(toks[vt], v)) {
+                    errors.push_back(
+                        "[SEDIMENT_EXCHANGE] " + toks[0] +
+                        ": missing or non-finite value in '" + line + "'.");
+                    continue;
+                }
+
+                // PE2: per-element rows go through the SHARED validator and
+                // land as override rows; GLOBAL keeps the existing writes
+                // below so this round changes no global behaviour.
+                if (sr.scope != HeatScope::GLOBAL) {
+                    const AttrSpec* spec = nullptr;
+                    for (const auto& e : kAttrTable)
+                        if (k == e.key && isSedimentAttr(e.attr)) spec = &e;
+                    if (spec == nullptr) {
+                        errors.push_back(
+                            "[SEDIMENT_EXCHANGE] '" + toks[0] + "' has no "
+                            "per-element form (INITIAL_TEMPERATURE is the "
+                            "bed's own seed and is GLOBAL).");
+                        continue;
+                    }
+                    if (validateAttr(*spec, v, "SEDIMENT_EXCHANGE", toks[vt],
+                                     errors))
+                        recordOverride(ctx, spec->attr, sr, v,
+                                       "SEDIMENT_EXCHANGE", line, errors);
+                    continue;
+                }
+
+                // Lengths, diffusivities and material properties are refused
+                // at zero or below rather than clamped: every one of them is
+                // a DIVISOR or a capacity in BedExchange.cpp, and a silently
+                // repaired zero would produce an infinite conductance or a
+                // massless bed that tracks the water exactly — both of which
+                // look like a working model.
+                const auto positive = [&](double& dst) {
+                    if (!(v > 0.0)) {
+                        errors.push_back("[SEDIMENT_EXCHANGE] " + toks[0] +
+                                         " must be greater than zero, got " +
+                                         toks[vt] + ".");
+                        return;
+                    }
+                    dst = v;
+                };
+
+                if (k == "THERMAL_DIFFUSIVITY")           positive(sd.thermal_diffusivity);
+                else if (k == "SOLUTE_DIFFUSIVITY") {
+                    // The one quantity for which zero is meaningful: it
+                    // selects advection-only transient storage, which is a
+                    // configuration a tracer study deliberately runs.
+                    if (v < 0.0)
+                        errors.push_back("[SEDIMENT_EXCHANGE] "
+                                         "SOLUTE_DIFFUSIVITY cannot be "
+                                         "negative, got " + toks[vt] + ".");
+                    else sd.solute_diffusivity = v;
+                }
+                else if (k == "BED_THICKNESS")            positive(sd.bed_thickness);
+                else if (k == "GROUND_DEPTH")             positive(sd.ground_depth);
+                else if (k == "SEDIMENT_DENSITY")         positive(sd.sed_density);
+                else if (k == "SEDIMENT_SPECIFIC_HEAT")   positive(sd.sed_specific_heat);
+                else if (k == "HYPORHEIC_VELOCITY") {
+                    // Zero is the default and means conduction only. A
+                    // NEGATIVE exchange velocity has no reading — the
+                    // exchange is symmetric and its direction is set by the
+                    // temperature difference, not by a sign here.
+                    if (v < 0.0)
+                        errors.push_back("[SEDIMENT_EXCHANGE] "
+                                         "HYPORHEIC_VELOCITY cannot be "
+                                         "negative: the exchange direction "
+                                         "follows the gradient, not this "
+                                         "sign. Got " + toks[vt] + ".");
+                    else sd.hyporheic_velocity = v;
+                }
+                else if (k == "GROUND_TEMPERATURE") {
+                    sd.ground_temp     = v;
+                    sd.ground_ts_index = -1;
+                    sd.has_ground_temp = true;
+                }
+                else if (k == "INITIAL_TEMPERATURE") {
+                    sd.initial_temp     = v;
+                    sd.has_initial_temp = true;
+                }
+                else {
+                    errors.push_back(
+                        "[SEDIMENT_EXCHANGE] unknown parameter '" + toks[0] +
+                        "' (THERMAL_DIFFUSIVITY, SOLUTE_DIFFUSIVITY, "
+                        "BED_THICKNESS, GROUND_DEPTH, GROUND_TEMPERATURE, "
+                        "HYPORHEIC_VELOCITY, SEDIMENT_DENSITY, "
+                        "SEDIMENT_SPECIFIC_HEAT, INITIAL_TEMPERATURE).");
+                }
+            }
+            continue;
+        }
+
+        if (sec.first == "CLOUD_COVER") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.size() < 3 || upper(toks[1]) != "GLOBAL") {
+                    errors.push_back(
+                        "[CLOUD_COVER] expects ' GLOBAL ': '" +
+                        line + "'.");
+                    continue;
+                }
+                auto& cc = ctx.heat_config.cloud;
+                const std::string k = upper(toks[0]);
+
+                if (k == "FRACTION") {
+                    if (upper(toks[2]) == "TIMESERIES") {
+                        if (toks.size() != 4) {
+                            errors.push_back(
+                                "[CLOUD_COVER] FRACTION GLOBAL TIMESERIES "
+                                "takes a series name: '" + line + "'.");
+                            continue;
+                        }
+                        const int ts = ctx.find_timeseries(toks[3]);
+                        if (ts < 0) {
+                            errors.push_back(
+                                "[CLOUD_COVER] TIMESERIES '" + toks[3] +
+                                "' is not a [TIMESERIES] in the model.");
+                            continue;
+                        }
+                        cc.use_timeseries = true;
+                        cc.ts_index       = ts;
+                        cc.configured     = true;
+                        cloud_fraction_seen = true;
+                        continue;
+                    }
+                    if (toks.size() != 3) {
+                        errors.push_back("[CLOUD_COVER] malformed FRACTION "
+                                         "row: '" + line + "'.");
+                        continue;
+                    }
+                    double c = 0.0;
+                    if (!parse_finite(toks[2], c)) {
+                        errors.push_back("[CLOUD_COVER] FRACTION '" + toks[2] +
+                                         "' is not a finite number or "
+                                         "TIMESERIES.");
+                        continue;
+                    }
+                    // Refused, not clamped — a 75 meant as 75% would
+                    // otherwise blacken the sky and look deliberate. (The
+                    // TIMESERIES path DOES clamp, at runtime: a series value
+                    // arrives mid-run where there is no user to ask.)
+                    if (c < 0.0 || c > 1.0) {
+                        errors.push_back(
+                            "[CLOUD_COVER] FRACTION must be in [0,1], got " +
+                            toks[2] + " (it is a fraction, not a percent).");
+                        continue;
+                    }
+                    cc.use_timeseries = false;
+                    cc.fraction       = c;
+                    cc.configured     = true;
+                    cloud_fraction_seen = true;
+                    continue;
+                }
+
+                // Unknown key is checked BEFORE the numeric parse, so a
+                // misspelled parameter reports itself rather than reporting
+                // its value as "not a number" — the report should name the
+                // thing the user can act on.
+                if (k != "SW_ATTEN_K" && k != "SW_ATTEN_N" &&
+                    k != "LW_CLOUD_K") {
+                    errors.push_back(
+                        "[CLOUD_COVER] unknown parameter '" + toks[0] +
+                        "' (FRACTION, SW_ATTEN_K, SW_ATTEN_N, LW_CLOUD_K).");
+                    continue;
+                }
+                if (toks.size() != 3) {
+                    errors.push_back("[CLOUD_COVER] expects ' GLOBAL "
+                                     "': '" + line + "'.");
+                    continue;
+                }
+                double v = 0.0;
+                if (!parse_finite(toks[2], v)) {
+                    errors.push_back("[CLOUD_COVER] '" + toks[0] + "': '" +
+                                     toks[2] + "' is not a finite number.");
+                    continue;
+                }
+                if (v < 0.0) {
+                    errors.push_back("[CLOUD_COVER] '" + toks[0] +
+                                     "' must be >= 0, got " + toks[2] + ".");
+                    continue;
+                }
+                if      (k == "SW_ATTEN_K") cc.sw_atten_k = v;
+                else if (k == "SW_ATTEN_N") cc.sw_atten_n = v;
+                else                        cc.lw_cloud_k = v;
+                // Marked configured on a COEFFICIENT row too, matching
+                // `swmm_heat_set_cloud`. Without this a section holding only
+                // coefficients left `configured` false, `updateSolarForcing`
+                // skipped the whole cloud read, and the section did nothing
+                // at all — with no error and no warning. The
+                // no-FRACTION-given case is warned about below; it is a
+                // different complaint from "the section was ignored".
+                cc.configured = true;
+            }
+            continue;
+        }
+
+        if (sec.first == "HEAT_FLUXES") {
+            for (const auto& line : sec.second) {
+                const auto toks = tokenize(line);
+                if (toks.size() != 2) {
+                    errors.push_back(
+                        "[HEAT_FLUXES] expects ' ON|OFF': '" + line +
+                        "'.");
+                    continue;
+                }
+                const std::string mod = upper(toks[0]);
+                const std::string val = upper(toks[1]);
+
+                // H5a/D-H5c. Checked BEFORE the ON|OFF validation because it
+                // is the one key in this section whose value is a named mode
+                // rather than a toggle; leaving it below would have it
+                // rejected as "not ON or OFF" before its own branch ran.
+                // Ladder shape follows ArdConfig.cpp:116-137 (SCALAR_SCHEME).
+                if (mod == "DRY_ELEMENT_TEMPERATURE") {
+                    if (val == "HOLD")
+                        ctx.heat_config.dry_temp_policy = DryTempPolicy::HOLD;
+                    else if (val == "AIR")
+                        ctx.heat_config.dry_temp_policy = DryTempPolicy::AIR;
+                    else if (val == "DEFAULT")
+                        ctx.heat_config.dry_temp_policy =
+                            DryTempPolicy::DEFAULT;
+                    else
+                        errors.push_back(
+                            "[HEAT_FLUXES] DRY_ELEMENT_TEMPERATURE '" +
+                            toks[1] + "' is not HOLD, AIR, or DEFAULT.");
+                    continue;
+                }
+
+                if (val != "ON" && val != "OFF" && val != "YES" &&
+                    val != "NO") {
+                    errors.push_back(
+                        "[HEAT_FLUXES] '" + toks[0] + "': '" + toks[1] +
+                        "' is not ON or OFF.");
+                    continue;
+                }
+                const bool on = (val == "ON" || val == "YES");
+                if (mod == "SURFACE_EXCHANGE") {
+                    ctx.heat_config.surface_exchange = on;
+                } else if (mod == "RADIATIVE_EXCHANGE") {
+                    ctx.heat_config.radiative_exchange = on;
+                } else if (mod == "LAYER_CONDUCTION") {
+                    ctx.heat_config.layer_conduction = on;
+                } else if (mod == "SEDIMENT_EXCHANGE") {
+                    ctx.heat_config.sediment_exchange = on;   // H6b
+                } else {
+                    errors.push_back(
+                        "[HEAT_FLUXES] unknown module '" + toks[0] +
+                        "' (SURFACE_EXCHANGE in H2, RADIATIVE_EXCHANGE in "
+                        "H3, DRY_ELEMENT_TEMPERATURE in H5a, "
+                        "LAYER_CONDUCTION in H5b, SEDIMENT_EXCHANGE in "
+                        "H6b).");
+                }
+            }
+            continue;
+        }
+        if (sec.first != "HEAT_SOURCES") {
+            errors.push_back(
+                "model.heat: unknown section [" + sec.first +
+                "] (recognized: [HEAT_SOURCES], [HEAT_FLUXES], "
+                "[RADIATIVE_FLUXES], [SOLAR_RADIATION], [CLOUD_COVER], "
+                "[SEDIMENT_EXCHANGE]).");
+            continue;
+        }
+        for (const auto& line : sec.second) {
+            const auto toks = tokenize(line);
+            if (toks.size() < 3) {
+                errors.push_back(
+                    "[HEAT_SOURCES] expects '  [name] "
+                    "': '" + line + "'.");
+                continue;
+            }
+            const int src = source_of(upper(toks[0]));
+            if (src < 0) {
+                errors.push_back(
+                    "[HEAT_SOURCES] unknown source '" + toks[0] +
+                    "' (RAINFALL, DWF, GW, RDII, EXTERNAL_INFLOW, IFACE, "
+                    "INITIAL_STATE).");
+                continue;
+            }
+            const std::string scope = upper(toks[1]);
+
+            // Deferral surface — precise phase names, never silence.
+            if (scope == "SUBCATCH") {
+                errors.push_back(
+                    "[HEAT_SOURCES] SUBCATCH scope arrives with plan phase "
+                    "H5 (watershed temperature states).");
+                continue;
+            }
+            if (scope == "EDGE_BC") {
+                errors.push_back(
+                    "[HEAT_SOURCES] EDGE_BC scope arrives with phase T6 "
+                    "(2D transport).");
+                continue;
+            }
+            // Bind the value token only once the row is known to HAVE that
+            // column (A1a lesson: reading toks[3] before the arity check
+            // was an out-of-bounds read on a 3-token NODE row).
+            const bool has_name = (scope == "NODE");
+            const std::size_t vpos = has_name ? 3u : 2u;
+            if (toks.size() <= vpos) {
+                errors.push_back(
+                    "[HEAT_SOURCES] malformed row: '" + line + "'.");
+                continue;
+            }
+            const std::string& vtok = toks[vpos];
+            // TIMESERIES is checked BEFORE the exact-arity test: its
+            // spelling carries a series NAME after the keyword, so it has
+            // one column more than a constant row, and an arity-first test
+            // would report "malformed" for the documented spelling —
+            // making this deferral unreachable (the A1a defect).
+            if (upper(vtok).rfind("TIMESERIES", 0) == 0) {
+                errors.push_back(
+                    "[HEAT_SOURCES] TIMESERIES temperatures arrive with a "
+                    "later heat phase — H1 takes constant degC.");
+                continue;
+            }
+            if (toks.size() != vpos + 1) {
+                errors.push_back(
+                    "[HEAT_SOURCES] malformed row: '" + line + "'.");
+                continue;
+            }
+            double degc = 0.0;
+            if (!parse_celsius(vtok, degc)) {
+                errors.push_back(
+                    "[HEAT_SOURCES] '" + toks[0] + "': '" + vtok +
+                    "' is not a temperature in degC between -50 and 100.");
+                continue;
+            }
+
+            if (scope == "GLOBAL") {
+                ctx.heat_config.global_temp[src] = degc;
+                ctx.heat_config.configured_source[src] = true;
+            } else if (scope == "NODE") {
+                if (src != static_cast(HeatSource::DWF) &&
+                    src != static_cast(HeatSource::EXTERNAL_INFLOW)) {
+                    errors.push_back(
+                        "[HEAT_SOURCES] NODE scope applies to DWF and "
+                        "EXTERNAL_INFLOW in H1; '" + toks[0] +
+                        "' takes GLOBAL.");
+                    continue;
+                }
+                const int nd = ctx.node_names.find(toks[2]);
+                if (nd < 0) {
+                    errors.push_back(
+                        "[HEAT_SOURCES] unknown node '" + toks[2] + "'.");
+                    continue;
+                }
+                bool dup = false;
+                for (std::size_t i = 0;
+                     i < ctx.heat_config.node_over_source.size(); ++i)
+                    if (ctx.heat_config.node_over_source[i] == src &&
+                        ctx.heat_config.node_over_node[i] == nd) {
+                        errors.push_back(
+                            "[HEAT_SOURCES] duplicate NODE row for '" +
+                            toks[0] + "' at '" + toks[2] + "'.");
+                        dup = true;
+                        break;
+                    }
+                if (dup) continue;
+                ctx.heat_config.node_over_source.push_back(src);
+                ctx.heat_config.node_over_node.push_back(nd);
+                ctx.heat_config.node_over_temp.push_back(degc);
+            } else {
+                errors.push_back(
+                    "[HEAT_SOURCES] unknown scope '" + toks[1] +
+                    "' (GLOBAL or NODE in H1).");
+            }
+        }
+    }
+
+    // ---- H6a cross-section checks. These need every section parsed, so
+    //      they cannot live inside the loop above.
+    {
+        const auto& rc = ctx.heat_config.radiative;
+        const auto& sc = ctx.heat_config.solar;
+
+        // D-H6a / plan §2.5 trap 1. COMPUTED without coordinates must be an
+        // ERROR, never a default. `ClimateState::latitude` is the
+        // [TEMPERATURE] SNOWMELT field: it defaults to 0 and is written only
+        // by decks carrying that line, so borrowing it would silently model
+        // equatorial noon — a plausible wrong answer, which is the only kind
+        // that survives review.
+        if (rc.sw_mode == ShortwaveMode::COMPUTED) {
+            if (!sc.has_latitude || !sc.has_longitude)
+                errors.push_back(
+                    "[RADIATIVE_FLUXES] SHORTWAVE GLOBAL COMPUTED requires "
+                    "[SOLAR_RADIATION] LATITUDE and LONGITUDE. They are NOT "
+                    "taken from the [TEMPERATURE] SNOWMELT line: that "
+                    "latitude defaults to 0 and its longitude field is a "
+                    "solar-time correction in minutes, not a longitude "
+                    "(plan §2.5).");
+        } else if (ctx.heat_config.solar.has_latitude ||
+                   ctx.heat_config.solar.has_longitude) {
+            // Not an error — the section is harmless — but silence here is
+            // exactly the bypass lessons 10/20 are about: the user wrote
+            // coordinates and nothing reads them.
+            pending_warnings.push_back(
+                "[SOLAR_RADIATION] is configured but [RADIATIVE_FLUXES] "
+                "SHORTWAVE is not COMPUTED, so the site coordinates are "
+                "unused. Set SHORTWAVE GLOBAL COMPUTED to use them.");
+        }
+
+        // Double-counting: a measured pyranometer series already contains
+        // the clouds that were over it. Attenuating it again is a real
+        // modelling error, but it is not unambiguously one — a user may be
+        // scaling a clear-sky-corrected record on purpose — so it warns.
+        if (rc.sw_mode == ShortwaveMode::TIMESERIES &&
+            ctx.heat_config.cloud.configured) {
+            pending_warnings.push_back(
+                "[CLOUD_COVER] is applied on top of a measured SHORTWAVE "
+                "TIMESERIES. A measured record already contains its clouds, "
+                "so this attenuates them twice. Drop [CLOUD_COVER] unless the "
+                "series is explicitly clear-sky. (The longwave cloud "
+                "correction still applies either way.)");
+        }
+
+        // Coefficients with nothing to scale. Both cloud factors are
+        // identities at C = 0, so this section changes nothing.
+        if (ctx.heat_config.cloud.configured && !cloud_fraction_seen) {
+            pending_warnings.push_back(
+                "[CLOUD_COVER] sets coefficients but no FRACTION, so the "
+                "cloud fraction is 0 and both cloud corrections are the "
+                "identity — the section has no effect. Add 'FRACTION GLOBAL "
+                "' or 'FRACTION GLOBAL TIMESERIES '.");
+        }
+
+        // An omitted TIMEZONE is a legal 0 (UTC), and it is also the single
+        // largest error available in this module: it shifts the whole
+        // diurnal curve by up to 12 h, dwarfing the 0.1° position accuracy
+        // D-H6a-4 spends its argument on. Not an error — a deck really may
+        // mean UTC — but never silent.
+        if (rc.sw_mode == ShortwaveMode::COMPUTED && !sc.has_timezone) {
+            pending_warnings.push_back(
+                "[SOLAR_RADIATION] has no TIMEZONE, so local time is taken "
+                "as UTC. If the deck's clock is local, the computed solar "
+                "day is shifted by the site's offset — up to 12 hours, "
+                "which is larger than every other error in this module. "
+                "Add 'TIMEZONE GLOBAL '.");
+        }
+    }
+
+    if (errors.size() != errors_before) {
+        ctx.heat_config = HeatConfigData{};  // never half-apply
+        return;                              // ...and never half-warn either:
+                                             // pending_warnings dies here.
+    }
+    ctx.heat_config.configured = true;
+
+    // The parse stood, so its warnings are about a configuration that
+    // actually took effect.
+    for (auto& w : pending_warnings)
+        ctx.warnings.push_back(std::move(w));
+
+    // Silent-bypass enumeration (lessons 10/20): every configuration in
+    // which this table reaches nothing says so. (ON + IGNORE_QUALITY warns
+    // engine-level in SWMMEngine::open — it applies with or without this
+    // component.)
+    if (!ctx.options.heat_transport) {
+        ctx.warnings.push_back(
+            "A heat component is configured but [OPTIONS] HEAT_TRANSPORT is "
+            "OFF — no temperature is tracked this simulation. Set "
+            "HEAT_TRANSPORT ON.");
+    }
+}
+
+/**
+ * @brief IO3a: render `heat_config` back to `model.heat` text.
+ *
+ * @details Only what the model actually SET is emitted. A source at its 20 °C
+ *          default with `configured_source == false` produces no row, so a
+ *          save does not invent configuration the user never wrote — the
+ *          reason `configured_source` exists at all.
+ *
+ *          Sections are emitted in the parser's own recognized order so the
+ *          file reads the way a hand-written one does, and every value is
+ *          written in the units the parser reads (°C here; the radiative and
+ *          solar blocks are H6a's own and stay in their documented units).
+ *
+ *          **Declines by returning empty when nothing is configured.** An
+ *          empty return means "copy the original instead" — writing an empty
+ *          file over a config the model never touched would be the data loss
+ *          this hook exists to end, inverted.
+ */
+/// IO3b: the renderer covers every heat section, so the IO3a decline guard
+/// (`hasUnrenderableSections`) is DELETED rather than kept as a safety net —
+/// a decline that cannot be reached is dead code pretending to be one. What
+/// replaces its protection is STRUCTURAL: the static_asserts below break the
+/// build when any of the three config structs grows a field, so the renderer
+/// must be taught about it before the engine compiles again — the failure
+/// mode is a build error, never a silent data loss (IO3b handoff §3).
+/// The sizes are the LP64 layouts (doubles + int-sized enums/bools with
+/// standard padding), identical on arm64 and x86-64; a platform where they
+/// differ fails the build loudly, which is the safe direction.
+// PE2 bumped this from 72 with `landcover_temp`. The pin FIRED on that
+// change, which is what it is for — compiler-measured, not hand-computed.
+static_assert(sizeof(RadiativeConfig) == 80,
+              "RadiativeConfig changed: teach saveHeatConfig its new field, "
+              "then update this size pin");
+static_assert(sizeof(SolarConfig) == 88,
+              "SolarConfig changed: teach saveHeatConfig its new field, "
+              "then update this size pin");
+// H6b. Compiler-measured, not hand-computed — IO3b's record notes the first
+// hand computation was wrong twice, which is the whole point of asking.
+static_assert(sizeof(SedimentConfig) == 88,
+              "SedimentConfig changed: teach saveHeatConfig its new field, "
+              "then update this size pin");
+static_assert(sizeof(CloudConfig) == 40,
+              "CloudConfig changed: teach saveHeatConfig its new field, "
+              "then update this size pin");
+
+/**
+ * @brief PE2 — render the per-element override rows of one section.
+ *
+ * @details Emitted in PARSE ORDER, not sorted: a save/reopen/save cycle must
+ *          be byte-stable (the `3e87868e` gen2 == gen3 gate), and parse
+ *          order is stable by construction while any sort would have to
+ *          agree with itself across two different in-memory orderings.
+ *
+ *          Written in the SAME round as the parser, deliberately. IO3a
+ *          shipped a renderer that did not know about H6a's sections and
+ *          every radiative deck would have lost its configuration on first
+ *          save (lesson 201); a config surface and its serializer landing
+ *          together is the only shape in which that cannot recur.
+ */
+std::string renderOverrides(const SimulationContext& ctx, bool sediment) {
+    std::string out;
+    for (const auto& r : ctx.heat_config.overrides.rows) {
+        if (isSedimentAttr(r.attr) != sediment) continue;
+        const char* scope = (r.scope == HeatScope::TAG)  ? "TAG"
+                          : (r.scope == HeatScope::LINK) ? "LINK"
+                          : (r.scope == HeatScope::NODE) ? "NODE"
+                                                         : "GLOBAL";
+        out += std::string(attrKey(r.attr)) + " " + scope + " " + r.name +
+               " " + fmt_degc(r.value) + "\n";
+    }
+    return out;
+}
+
+std::string saveHeatConfig(const SimulationContext& ctx) {
+    const auto& cfg = ctx.heat_config;
+    std::string out;
+
+    // [HEAT_SOURCES] — GLOBAL rows for explicitly configured sources, then
+    // NODE overrides in table order.
+    std::string rows;
+    for (int s = 0; s < static_cast(HeatSource::COUNT_); ++s) {
+        const auto us = static_cast(s);
+        if (!cfg.configured_source[us]) continue;
+        rows += std::string(source_name(s)) + " GLOBAL " +
+                fmt_degc(cfg.global_temp[us]) + "\n";
+    }
+    for (std::size_t i = 0; i < cfg.node_over_source.size(); ++i) {
+        const int nd = cfg.node_over_node[i];
+        if (nd < 0 || nd >= ctx.n_nodes()) continue;  // stale index: skip
+        rows += std::string(source_name(cfg.node_over_source[i])) + " NODE " +
+                ctx.node_names.name_of(nd) + " " +
+                fmt_degc(cfg.node_over_temp[i]) + "\n";
+    }
+    if (!rows.empty()) out += "[HEAT_SOURCES]\n" + rows + "\n";
+
+    // [HEAT_FLUXES] — only the modules that are ON. An OFF module is the
+    // default, and emitting it would make every saved file look configured.
+    std::string flux;
+    if (cfg.surface_exchange)   flux += "SURFACE_EXCHANGE ON\n";
+    if (cfg.radiative_exchange) flux += "RADIATIVE_EXCHANGE ON\n";
+    if (cfg.layer_conduction)   flux += "LAYER_CONDUCTION ON\n";
+    if (cfg.sediment_exchange)  flux += "SEDIMENT_EXCHANGE ON\n";   // H6b
+    if (!flux.empty()) out += "[HEAT_FLUXES]\n" + flux + "\n";
+
+    // [RADIATIVE_FLUXES] — H3's scalars plus H6a's three SHORTWAVE
+    // spellings. Emission conditions are the exact comparisons the IO3a
+    // decline guard used: only what departs from a default-constructed
+    // config is written (lesson 196 — a serializer that writes every
+    // default makes every saved model look configured).
+    {
+        const RadiativeConfig rd{};
+        const auto& r = cfg.radiative;
+        std::string rad;
+        switch (r.sw_mode) {
+            case ShortwaveMode::CONSTANT:
+                if (r.shortwave_wm2 != rd.shortwave_wm2)
+                    rad += "SHORTWAVE GLOBAL " + fmt_degc(r.shortwave_wm2) +
+                           "\n";
+                break;
+            case ShortwaveMode::TIMESERIES:
+                // sw_ts_index indexes ctx.tables; the file needs the NAME —
+                // `id` is the string `by_name` is built from, so this IS the
+                // back-mapping (never search by_name for a matching index).
+                if (r.sw_ts_index >= 0 &&
+                    r.sw_ts_index < static_cast(ctx.tables.count()))
+                    rad += "SHORTWAVE GLOBAL TIMESERIES " +
+                           ctx.tables[r.sw_ts_index].id + "\n";
+                break;
+            case ShortwaveMode::COMPUTED:
+                rad += "SHORTWAVE GLOBAL COMPUTED\n";
+                break;
+        }
+        if (r.albedo != rd.albedo)
+            rad += "ALBEDO GLOBAL " + fmt_degc(r.albedo) + "\n";
+        if (r.shade_factor != rd.shade_factor)
+            rad += "SHADE_FACTOR GLOBAL " + fmt_degc(r.shade_factor) + "\n";
+        if (r.sky_view != rd.sky_view)
+            rad += "SKY_VIEW GLOBAL " + fmt_degc(r.sky_view) + "\n";
+        if (r.emiss_water != rd.emiss_water)
+            rad += "EMISS_WATER GLOBAL " + fmt_degc(r.emiss_water) + "\n";
+        if (r.emiss_landcover != rd.emiss_landcover)
+            rad += "EMISS_LANDCOVER GLOBAL " + fmt_degc(r.emiss_landcover) +
+                   "\n";
+        if (r.atm_emiss_coeff != rd.atm_emiss_coeff)
+            rad += "ATM_EMISS_COEFF GLOBAL " + fmt_degc(r.atm_emiss_coeff) +
+                   "\n";
+        if (r.lw_reflection != rd.lw_reflection)
+            rad += "ATM_LW_REFLECTION GLOBAL " + fmt_degc(r.lw_reflection) +
+                   "\n";
+        // PE2: NaN means "use air temperature" and is the default, so the
+        // emission test is `is not NaN` rather than `differs from the
+        // default` — NaN != NaN would make a value-compare emit the key on
+        // every save, inventing configuration on models that set nothing.
+        if (!std::isnan(r.landcover_temp))
+            rad += "LANDCOVER_TEMPERATURE GLOBAL " +
+                   fmt_degc(r.landcover_temp) + "\n";
+        // PE2: per-element rows for THIS section, in parse order so a
+        // save/reopen/save cycle is byte-stable (the gen2 == gen3 gate).
+        rad += renderOverrides(ctx, /*sediment=*/false);
+        if (!rad.empty()) out += "[RADIATIVE_FLUXES]\n" + rad + "\n";
+    }
+
+    // [SOLAR_RADIATION] — the sited fields carry explicit has_* flags (0 is
+    // a legal latitude/timezone/elevation, so presence cannot ride on the
+    // value); the Bird atmosphere fields compare against the paper defaults.
+    {
+        const SolarConfig sd{};
+        const auto& sl = cfg.solar;
+        std::string sol;
+        if (sl.has_latitude)
+            sol += "LATITUDE GLOBAL " + fmt_degc(sl.latitude_deg) + "\n";
+        if (sl.has_longitude)
+            sol += "LONGITUDE GLOBAL " + fmt_degc(sl.longitude_deg) + "\n";
+        if (sl.has_timezone)
+            sol += "TIMEZONE GLOBAL " + fmt_degc(sl.timezone_hours) + "\n";
+        if (sl.has_elevation)
+            sol += "ELEVATION GLOBAL " + fmt_degc(sl.elevation_m) + "\n";
+        if (sl.aod380 != sd.aod380)
+            sol += "TURBIDITY_380 GLOBAL " + fmt_degc(sl.aod380) + "\n";
+        if (sl.aod500 != sd.aod500)
+            sol += "TURBIDITY_500 GLOBAL " + fmt_degc(sl.aod500) + "\n";
+        if (sl.precip_water_cm != sd.precip_water_cm)
+            sol += "PRECIP_WATER GLOBAL " + fmt_degc(sl.precip_water_cm) +
+                   "\n";
+        if (sl.ozone_cm != sd.ozone_cm)
+            sol += "OZONE GLOBAL " + fmt_degc(sl.ozone_cm) + "\n";
+        if (sl.ground_albedo != sd.ground_albedo)
+            sol += "GROUND_ALBEDO GLOBAL " + fmt_degc(sl.ground_albedo) +
+                   "\n";
+        if (!sol.empty()) out += "[SOLAR_RADIATION]\n" + sol + "\n";
+    }
+
+    // [CLOUD_COVER] — `configured` is user intent (the one per-section flag
+    // these structs have), so a configured section always emits its FRACTION
+    // anchor row, even at 0.0: a coefficients-only original canonicalises to
+    // an explicit FRACTION 0 with identical physics (both cloud factors are
+    // identities at C = 0) and the file stops warning about a fraction it
+    // now visibly carries.
+    if (cfg.cloud.configured) {
+        const CloudConfig cd{};
+        const auto& c = cfg.cloud;
+        std::string cl;
+        if (c.use_timeseries) {
+            if (c.ts_index >= 0 &&
+                c.ts_index < static_cast(ctx.tables.count()))
+                cl += "FRACTION GLOBAL TIMESERIES " +
+                      ctx.tables[c.ts_index].id + "\n";
+        } else {
+            cl += "FRACTION GLOBAL " + fmt_degc(c.fraction) + "\n";
+        }
+        if (c.sw_atten_k != cd.sw_atten_k)
+            cl += "SW_ATTEN_K GLOBAL " + fmt_degc(c.sw_atten_k) + "\n";
+        if (c.sw_atten_n != cd.sw_atten_n)
+            cl += "SW_ATTEN_N GLOBAL " + fmt_degc(c.sw_atten_n) + "\n";
+        if (c.lw_cloud_k != cd.lw_cloud_k)
+            cl += "LW_CLOUD_K GLOBAL " + fmt_degc(c.lw_cloud_k) + "\n";
+        if (!cl.empty()) out += "[CLOUD_COVER]\n" + cl + "\n";
+    }
+
+    // [SEDIMENT_EXCHANGE] — H6b. Rendered in the SAME round that added the
+    // section, deliberately. IO3a shipped a renderer that did not know about
+    // H6a's sections and every radiative deck would have lost its
+    // configuration on first save (lesson 201); adding a config struct and
+    // its serializer together is the only shape in which that cannot recur.
+    {
+        const SedimentConfig sd{};
+        const auto& s = cfg.sediment;
+        std::string bed;
+        if (s.thermal_diffusivity != sd.thermal_diffusivity)
+            bed += "THERMAL_DIFFUSIVITY GLOBAL " +
+                   fmt_degc(s.thermal_diffusivity) + "\n";
+        if (s.solute_diffusivity != sd.solute_diffusivity)
+            bed += "SOLUTE_DIFFUSIVITY GLOBAL " +
+                   fmt_degc(s.solute_diffusivity) + "\n";
+        if (s.bed_thickness != sd.bed_thickness)
+            bed += "BED_THICKNESS GLOBAL " + fmt_degc(s.bed_thickness) + "\n";
+        if (s.ground_depth != sd.ground_depth)
+            bed += "GROUND_DEPTH GLOBAL " + fmt_degc(s.ground_depth) + "\n";
+        if (s.hyporheic_velocity != sd.hyporheic_velocity)
+            bed += "HYPORHEIC_VELOCITY GLOBAL " +
+                   fmt_degc(s.hyporheic_velocity) + "\n";
+        if (s.sed_density != sd.sed_density)
+            bed += "SEDIMENT_DENSITY GLOBAL " + fmt_degc(s.sed_density) + "\n";
+        if (s.sed_specific_heat != sd.sed_specific_heat)
+            bed += "SEDIMENT_SPECIFIC_HEAT GLOBAL " +
+                   fmt_degc(s.sed_specific_heat) + "\n";
+        // Both temperatures are emitted on `has_*`, not on a value
+        // comparison: 12 °C is a perfectly ordinary deliberate choice and
+        // the flags are the only record that the user made it. This is the
+        // `configured_source` distinction, one struct over.
+        if (s.has_ground_temp) {
+            if (s.ground_ts_index >= 0 &&
+                s.ground_ts_index < static_cast(ctx.tables.count()))
+                bed += "GROUND_TEMPERATURE GLOBAL TIMESERIES " +
+                       ctx.tables[s.ground_ts_index].id + "\n";
+            else
+                bed += "GROUND_TEMPERATURE GLOBAL " +
+                       fmt_degc(s.ground_temp) + "\n";
+        }
+        if (s.has_initial_temp)
+            bed += "INITIAL_TEMPERATURE GLOBAL " +
+                   fmt_degc(s.initial_temp) + "\n";
+        bed += renderOverrides(ctx, /*sediment=*/true);
+        if (!bed.empty()) out += "[SEDIMENT_EXCHANGE]\n" + bed + "\n";
+    }
+
+    // Empty still means DECLINE (a model with no heat configuration at all
+    // keeps the copy fallback) — but with every section rendered above, a
+    // configured model never declines again: IO3b is what retired the
+    // step-3 loss for H6a-configured models.
+    return out;
+}
+
+}  // namespace
+
+void registerHeatComponent() {
+    components::ProcessComponentRegistry::instance().register_component(
+        kHeatId,
+        "Heat transport coordinator ([HEAT_SOURCES] inlet temperatures, "
+        "[HEAT_FLUXES] module toggles, [RADIATIVE_FLUXES] parameters, and "
+        "H6a's [SOLAR_RADIATION] + [CLOUD_COVER] shortwave forcing)",
+        [](SimulationContext& ctx, const ProcessComponentSpec& /*spec*/,
+           const components::ComponentConfigSections& config,
+           std::vector& errors) {
+            applyHeatSections(ctx, config, errors);
+        },
+        [](const SimulationContext& ctx,
+           const ProcessComponentSpec& /*spec*/) -> std::string {
+            return saveHeatConfig(ctx);
+        });
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/HeatModule/HeatComponent.hpp b/src/engine/transport/components/HeatModule/HeatComponent.hpp
new file mode 100644
index 000000000..f0596bd2c
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatComponent.hpp
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatComponent.hpp
+ * @brief The `org.hydrocouple.openswmm.heat` process component — phase H1:
+ *        parse `[HEAT_SOURCES]` (`model.heat`) into
+ *        SimulationContext::heat_config.
+ *
+ * @details Heat TRANSPORT is embedded in the engines (the LEGACY CSTR
+ *          mirror in H1); this component carries only the per-source inlet
+ *          temperature table, so every engine agrees when QUALITY_SOLVER
+ *          flips. `[OPTIONS] HEAT_TRANSPORT ON` enables tracking with
+ *          default source temperatures even without this component.
+ *
+ *          H1 scope: GLOBAL rows for all seven sources + NODE overrides
+ *          for DWF/EXTERNAL_INFLOW, VALUE (°C) only. TIMESERIES
+ *          temperatures, SUBCATCH/EDGE_BC scopes and the flux modules of
+ *          plan §2 are later phases and refuse with precise deferral
+ *          errors.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §3, §6 H1
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_COMPONENT_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_COMPONENT_HPP
+
+namespace openswmm::transport {
+
+/// Register `org.hydrocouple.openswmm.heat` with the process-component
+/// registry (idempotent; called from SWMMEngine::open before resolution).
+void registerHeatComponent();
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_COMPONENT_HPP
diff --git a/src/engine/transport/components/HeatModule/HeatLegacy.cpp b/src/engine/transport/components/HeatModule/HeatLegacy.cpp
new file mode 100644
index 000000000..d3ba9ea92
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatLegacy.cpp
@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatLegacy.cpp
+ * @brief Phase H1 body — LEGACY CSTR temperature transport.
+ *
+ * @details Formula provenance is the pollutant path in QualityRouting.cpp,
+ *          by way of the A1b age mirror: accumulateLinkLoads (rate
+ *          convention q·value), mixAtNodes (the findStorageQual /
+ *          findNodeQual dispatch and the volume-balance mix),
+ *          updateLinkQuality (the non-conduit shortcut, findSFLinkQual's
+ *          node1 and the DW volume-change inflow), all asked for through
+ *          the shared predicates in QualityRouting.hpp.
+ *
+ *          Differences from the age mirror are enumerated in the header.
+ *          Two are load-bearing: nothing here is floored at zero, and the
+ *          DRY-NODE AND DRY-LINK RULES DO NOT CARRY OVER — legacy zeroes a
+ *          concentration because an empty store holds no mass, but 0 °C is
+ *          an ordinary temperature rather than an absence, so zeroing it
+ *          would freeze every element that happened to drain.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatLegacy.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../quality/QualityRouting.hpp"
+#include "../../InitialQualitySeeds.hpp"
+#include "../HeatFluxModules/HeatFluxes.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+/// The quality path's own thresholds — one litre and one millimetre, the
+/// numbers legacy qualrout.c routes on. This mirror previously carried a
+/// local 1e-10, so it dispatched differently from the family it mirrors.
+using quality::ZERO_DEPTH;
+using quality::LEGACY_ZERO;
+
+/// Routing-thread scratch (the BindingScratch pattern): old-state
+/// snapshots and the per-node temperature-volume accumulator.
+struct HeatScratch {
+    std::vector node_old, link_old, temp_in;
+    void ensure(int nn, int nl) {
+        if (node_old.size() != static_cast(nn)) {
+            node_old.assign(static_cast(nn), 0.0);
+            temp_in.assign(static_cast(nn), 0.0);
+        }
+        if (link_old.size() != static_cast(nl))
+            link_old.assign(static_cast(nl), 0.0);
+    }
+};
+HeatScratch& scratch() {
+    static HeatScratch s;
+    return s;
+}
+}  // namespace
+
+void routeLegacyHeat(SimulationContext& ctx, double dt) {
+    if (!ctx.options.heat_transport || dt <= 0.0) return;
+    auto& hs = ctx.heat_state;
+    const int nn = ctx.n_nodes();
+    const int nl = ctx.n_links();
+    const double t_init = ctx.heat_config.global_temp[static_cast(
+        HeatSource::INITIAL_STATE)];
+    if (hs.node_temp.size() != static_cast(nn))
+        hs.resize(nn, nl, t_init);
+
+    auto& sc = scratch();
+    sc.ensure(nn, nl);
+
+    // ---- 0. INITIAL_STATE seeding, once. Unlike age (whose initial state
+    //         is usually 0, so an unseeded mirror merely looks plausible),
+    //         an unseeded temperature field would sit at whatever resize()
+    //         left and every gate would read a number — so the seed is
+    //         asserted, not assumed. --------------------------------------
+    if (!hs.legacy_seeded) {
+        std::fill(hs.node_temp.begin(), hs.node_temp.end(), t_init);
+        std::fill(hs.link_temp.begin(), hs.link_temp.end(), t_init);
+        // E-A3: per-element [INITIAL_QUALITY] __TEMPERATURE__ rows override
+        // the global fill.
+        applyInitialTempOverrides(ctx);
+        hs.legacy_seeded = true;
+    }
+
+    // ---- 1. Source terms, then old state. Age advances 1 s/s here;
+    //         temperature changes only by exchange with its surroundings,
+    //         so this is where plan §2's flux modules act — BEFORE the
+    //         old-state snapshot, so the step's advective mixing sees the
+    //         post-flux temperature exactly as it sees the post-aging age.
+    //         H2 delivers SurfaceExchange; H3/H4 add radiative and
+    //         sediment terms at this same point. ------------------------
+    //
+    //         D-H5e: ONE call. This was two, and once D-H5d made the step a
+    //         relaxation the two stopped commuting — each relaxed fully
+    //         toward its own module's equilibrium, so the result depended on
+    //         which ran last. Every family now sums into one J(T) inside
+    //         applyHeatFluxes before a single step.
+    heat::applyHeatFluxes(ctx, dt);
+
+    for (int i = 0; i < nn; ++i)
+        sc.node_old[static_cast(i)] =
+            hs.node_temp[static_cast(i)];
+    for (int j = 0; j < nl; ++j)
+        sc.link_old[static_cast(j)] =
+            hs.link_temp[static_cast(j)];
+
+    // ---- 2. Temperature-volume accumulation (accumulateLinkLoads mirror,
+    //         RATE convention) + the loaders' per-source rates. ----------
+    std::fill(sc.temp_in.begin(), sc.temp_in.end(), 0.0);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        const double q = std::fabs(ctx.links.flow[uj]);
+        if (q <= 0.0) continue;
+        const int downstream = (ctx.links.flow[uj] >= 0.0)
+                                   ? ctx.links.node2[uj]
+                                   : ctx.links.node1[uj];
+        if (downstream < 0 || downstream >= nn) continue;
+        sc.temp_in[static_cast(downstream)] +=
+            q * sc.link_old[uj];
+    }
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        if (ui < hs.node_temp_vol_in.size())
+            sc.temp_in[ui] += hs.node_temp_vol_in[ui];
+    }
+
+    // ---- 3. Node mixing (mixAtNodes mirror). The clamp is TWO-SIDED: a
+    //         volume-weighted mean lies between its inputs, and unlike age
+    //         the incoming value can be COLDER than what is held.
+    //
+    //         Dispatch and the inflow test are the quality path's. The
+    //         DRY-NODE RULE IS NOT: legacy zeroes a concentration because an
+    //         empty store holds no mass, but 0 °C is an ordinary temperature
+    //         rather than an absence, and zeroing it would freeze every node
+    //         that happened to drain. A dry node keeps the temperature it
+    //         held, which is also what it does with no inflow. ----------
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        const double v_old = ctx.nodes.old_volume[ui];
+        const double v_in  = ctx.nodes.qual_vol_in[ui];
+        const double q_in  = (dt > 0.0) ? v_in / dt : 0.0;
+        const double t_old = sc.node_old[ui];
+
+        if (!quality::nodeIsReactor(ctx, i)) {
+            // findNodeQual: no storage volume, so the temperature is the
+            // inflow's; with no inflow the node holds what it had.
+            // The gate is legacy's `qNode > ZERO` on the RATE, the same one
+            // the reactor half below uses — not "v_in is non-zero", which
+            // divides residual heat by residual volume.
+            hs.node_temp[ui] =
+                (q_in > LEGACY_ZERO) ? (sc.temp_in[ui] * dt) / v_in : t_old;
+            continue;
+        }
+
+        if (q_in <= LEGACY_ZERO) {
+            hs.node_temp[ui] = t_old;
+            continue;
+        }
+        const double mass_in = sc.temp_in[ui] * dt;
+        const double t_in    = mass_in / v_in;
+        double t_new = (t_old * v_old + mass_in) / (v_old + v_in);
+        // No max(·, 0): sub-zero water temperatures are ordinary, and a
+        // zero floor would silently warm every cold-weather model.
+        t_new = std::clamp(t_new, std::min(t_old, t_in),
+                           std::max(t_old, t_in));
+        hs.node_temp[ui] = t_new;
+    }
+
+    // ---- 4. Link update (updateLinkQuality mirror; no decay, no evap).
+    //         As at the nodes, the dry-link rule does not carry over: an
+    //         essentially empty conduit takes the upstream temperature,
+    //         where a pollutant would read zero. ------------------------
+    const bool is_steady =
+        (ctx.options.routing_model == RoutingModel::STEADY);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        // Steady flow draws on node1 unconditionally (findSFLinkQual).
+        const int upstream =
+            is_steady ? ctx.links.node1[uj]
+                      : ((ctx.links.flow[uj] >= 0.0) ? ctx.links.node1[uj]
+                                                     : ctx.links.node2[uj]);
+        if (upstream < 0 || upstream >= nn) continue;
+        const auto un = static_cast(upstream);
+        const double t_up = hs.node_temp[un];
+
+        // A non-conduit or DUMMY link holds no water: upstream outright.
+        if (quality::linkTakesUpstreamValue(ctx, j)) {
+            hs.link_temp[uj] = t_up;
+            continue;
+        }
+
+        const double v_old = ctx.links.old_volume[uj];
+        const double t_old = sc.link_old[uj];
+
+        double t_new;
+        if (is_steady) {
+            t_new = t_up;
+        } else if (quality::linkIsDry(ctx, j)) {
+            t_new = t_up;
+        } else {
+            const double q_in = quality::conduitMixingInflow(ctx, j, dt);
+            if (q_in <= LEGACY_ZERO) {
+                t_new = t_old;
+            } else {
+                const double v_in = q_in * dt;
+                t_new = (t_old * v_old + t_up * v_in) / (v_old + v_in);
+                t_new = std::clamp(t_new, std::min(t_old, t_up),
+                                   std::max(t_old, t_up));
+            }
+        }
+        hs.link_temp[uj] = t_new;
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/HeatModule/HeatLegacy.hpp b/src/engine/transport/components/HeatModule/HeatLegacy.hpp
new file mode 100644
index 000000000..0f02fe60c
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatLegacy.hpp
@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatLegacy.hpp
+ * @brief Phase H1 — the LEGACY (CSTR) engine's temperature transport.
+ *
+ * @details A single-scalar rerun of the CSTR quality stages for
+ *          `__TEMPERATURE__`, in the same order the pollutant arrays take
+ *          — structurally the A1b water-age mirror
+ *          (`WaterAgeModule/WaterAgeLegacy.cpp`) with three deliberate
+ *          differences, each of which is a way a verbatim copy would have
+ *          been wrong:
+ *
+ *          1. **No aging step.** Age grows at 1 s/s in every parcel;
+ *             temperature does not grow at all in H1. Heat SOURCES (the
+ *             W/m² surface, radiative and sediment fluxes of plan §2)
+ *             arrive with H2–H4 and will enter here, at the stage the age
+ *             mirror uses for aging.
+ *          2. **No zero floor.** The age mirror ends each stage with
+ *             `max(value, 0)` because a negative age is meaningless.
+ *             Temperatures below 0 °C are ordinary, and flooring them
+ *             would silently warm every cold-weather model to freezing.
+ *             The bound here is the physical one: a volume-weighted mean
+ *             lies between its inputs, so the clamp is two-sided,
+ *             `[min(T_old, T_in), max(T_old, T_in)]`.
+ *          3. **Initial state is a temperature, not a zero.** An unseeded
+ *             network starts at the configured INITIAL_STATE temperature
+ *             (default 20 °C), not at 0.
+ *
+ *          Like the age mirror this runs at the END of
+ *          QualitySolver::execute — it reads the fully accumulated
+ *          `qual_vol_in` as its mixing denominator — and writes ONLY
+ *          `heat_state`, so HEAT_TRANSPORT ON leaves every pollutant and
+ *          water-age trajectory bit-identical under LEGACY.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §1, §6 H1
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_LEGACY_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_LEGACY_HPP
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// One LEGACY temperature routing step (call at the END of
+/// QualitySolver::execute, after qual_vol_in is fully accumulated).
+/// No-op when HEAT_TRANSPORT is off.
+void routeLegacyHeat(SimulationContext& ctx, double dt);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_LEGACY_HPP
diff --git a/src/engine/transport/components/HeatModule/HeatLid.cpp b/src/engine/transport/components/HeatModule/HeatLid.cpp
new file mode 100644
index 000000000..39402b718
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatLid.cpp
@@ -0,0 +1,434 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatLid.cpp
+ * @brief Phase H5b body — temperature through the LID layer stack.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §6 H5b, §6.1 D-H5b/D-H5c
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatLid.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../hydrology/LID.hpp"
+#include "../HeatFluxModules/HeatFluxes.hpp"
+#include "../HeatFluxModules/SolarRadiation.hpp"
+#include "../HeatFluxModules/SurfaceExchange.hpp"
+#include "../LidLayerCommon.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr int    kTemp    = static_cast(LidSpecies::TEMPERATURE);
+constexpr double kTinyVol = 1.0e-12;  ///< ft of water per unit area
+constexpr double kFtToM   = 0.3048;
+
+/// What a layer holding no water reports (plan D-H5c) — the same policy the
+/// watershed uses, for the same reason: A4's "no water, no age" zero is a
+/// sentinel, and 0 °C is a real temperature.
+double dryTemperature(const SimulationContext& ctx, double held,
+                      double t_air_c) noexcept {
+    switch (ctx.heat_config.dry_temp_policy) {
+        case DryTempPolicy::AIR:     return t_air_c;
+        case DryTempPolicy::DEFAULT: return HeatConfigData::kDefaultTemp;
+        case DryTempPolicy::HOLD:
+        default:                     return held;
+    }
+}
+
+/// Physical thickness of each layer, metres. Distinct from the WATER each
+/// holds (`layerVolumes`): conduction crosses the whole layer, matrix
+/// included, while advection only carries the water.
+void layerThickness(const lid::LIDGroupSoA& g, std::size_t ui,
+                    double (&d)[kNL]) {
+    d[kSurf] = g.surf_store[ui] * kFtToM;
+    d[kPave] = g.pave_thick[ui] * kFtToM;
+    d[kSoil] = g.soil_thick[ui] * kFtToM;
+    d[kStor] = g.stor_thick[ui] * kFtToM;
+}
+
+/// Volumetric heat capacity of a layer, J/m³/K — water and matrix together.
+///
+/// The SURFACE layer is ponded water over a (mostly) impervious face, so it
+/// is water alone. The buried layers are a matrix with water in the voids,
+/// so both contribute; that is what makes their thermal mass large enough
+/// for conduction to be slow, and it is why a thin surface film is the only
+/// stiff member of the stack.
+double heatCapacity(const ConductionConfig& c, int layer, double water_m,
+                    double thick_m, double rho_w, double cp_w) noexcept {
+    const double water = rho_w * cp_w * water_m;
+    if (layer == kSurf) return (thick_m > 0.0) ? water / thick_m : 0.0;
+    const double solid_m = (thick_m > water_m) ? thick_m - water_m : 0.0;
+    const double total   = water + c.sed_density * c.sed_specific_heat *
+                                       solid_m;
+    return (thick_m > 0.0) ? total / thick_m : 0.0;
+}
+
+/// Effective thermal conductivity of a layer, W/m/K — volume-weighted
+/// between water and matrix. The simplest defensible mixing model; a
+/// geometric or Johansen mixture would be a second parameter set with no
+/// reference value in HydroCouple to gate it against.
+double conductivity(const ConductionConfig& c, int layer, double water_m,
+                    double thick_m) noexcept {
+    if (layer == kSurf) return c.water_conductivity;
+    if (!(thick_m > 0.0)) return c.water_conductivity;
+    const double theta = std::min(1.0, water_m / thick_m);
+    return theta * c.water_conductivity + (1.0 - theta) * c.sed_conductivity;
+}
+
+/// Solve a tridiagonal system in place (Thomas). `n <= kNL`.
+void solveTridiagonal(int n, double (&a)[kNL], double (&b)[kNL],
+                      double (&c)[kNL], double (&d)[kNL],
+                      double (&x)[kNL]) noexcept {
+    double cp[kNL], dp[kNL];
+    if (!(std::fabs(b[0]) > 0.0)) { for (int i = 0; i < n; ++i) x[i] = d[i]; return; }
+    cp[0] = c[0] / b[0];
+    dp[0] = d[0] / b[0];
+    for (int i = 1; i < n; ++i) {
+        const double m = b[i] - a[i] * cp[i - 1];
+        if (!(std::fabs(m) > 0.0)) { for (int k = 0; k < n; ++k) x[k] = d[k]; return; }
+        cp[i] = c[i] / m;
+        dp[i] = (d[i] - a[i] * dp[i - 1]) / m;
+    }
+    x[n - 1] = dp[n - 1];
+    for (int i = n - 2; i >= 0; --i) x[i] = dp[i] - cp[i] * x[i + 1];
+}
+
+}  // namespace
+
+double lidLayerHeatCapacity(const SimulationContext& ctx,
+                            const lid::LIDGroupSoA& g, std::size_t unit,
+                            int layer) noexcept {
+    if (layer < 0 || layer >= kNL) return 0.0;
+    double v[kNL], thick[kNL];
+    layerVolumes(g, unit, v);
+    layerThickness(g, unit, thick);
+    if (!(thick[layer] > 0.0)) return 0.0;
+    return heatCapacity(ctx.heat_config.conduction, layer,
+                        v[layer] * kFtToM, thick[layer],
+                        ctx.options.water_density,
+                        ctx.options.water_specific_heat) * thick[layer];
+}
+
+void initLidLayerTemperature(SimulationContext& ctx,
+                             const lid::LIDSolver& solver) {
+    if (!ctx.options.heat_transport) return;
+    auto offsets = buildOffsets(solver);
+    const int units = offsets.empty() ? 0 : offsets.back();
+    if (units <= 0) return;
+
+    auto& st = ctx.lid_layer_state;
+    st.ensureSized(units, static_cast(LidSpecies::COUNT_), offsets);
+
+    const double t_init = ctx.heat_config.global_temp[
+        static_cast(HeatSource::INITIAL_STATE)];
+    for (int t = 0; t < solver.numGroups(); ++t) {
+        const auto& g = solver.group(t);
+        for (int u = 0; u < g.count; ++u) {
+            const auto ui   = static_cast(u);
+            const int  flat = offsets[static_cast(t)] + u;
+            double v[kNL];
+            layerVolumes(g, ui, v);
+            for (int k = 0; k < kNL; ++k) {
+                const auto idx = static_cast(flat) * kNL +
+                                 static_cast(k);
+                st.vol_prev[idx] = v[k];
+                // EVERY layer is seeded, wet or dry — unlike the age row,
+                // which leaves a dry layer at 0 because 0 is age's "nothing
+                // here". A dry layer at 0 °C would be a freezing layer.
+                st.value[st.layer_index(flat, static_cast(k),
+                                        kTemp)] = t_init;
+            }
+        }
+    }
+}
+
+void setLidInflowTemperature(SimulationContext& ctx, int type_index, int unit,
+                             int subcatch, double rain_rate, double q_imperv,
+                             double q_perv, double q_runon, double lid_area) {
+    auto& st = ctx.lid_layer_state;
+    if (!ctx.options.heat_transport || !st.active()) return;
+    const auto ut = static_cast(type_index);
+    if (ut + 1 >= st.group_offset.size()) return;
+    const int flat = st.group_offset[ut] + unit;
+    if (flat < 0 || flat >= st.n_units) return;
+
+    const double q_rain = rain_rate * lid_area;
+    const double t_rain = ctx.heat_config.global_temp[
+        static_cast(HeatSource::RAINFALL)];
+
+    // Everything captured from the surface around the unit arrives at the
+    // temperature H5a publishes for that subcatchment's runoff — the same
+    // choice A4 made for age, and for the same reason: reconstructing a mean
+    // from the raw subarea rows looks more precise and is wrong, because a
+    // subarea can be shedding while its end-of-step stored volume is zero.
+    const auto& hs = ctx.heat_state;
+    const double t_surface =
+        (subcatch >= 0 &&
+         static_cast(subcatch) < hs.subcatch_runoff_temp.size())
+            ? hs.subcatch_runoff_temp[static_cast(subcatch)]
+            : t_rain;
+
+    const double q_surface = q_imperv + q_perv + q_runon;
+    const double q_tot = q_rain + q_surface;
+    const double temp = (q_tot > 0.0)
+        ? (q_rain * t_rain + q_surface * t_surface) / q_tot
+        : t_rain;
+    st.inflow_value[static_cast(flat) *
+                        static_cast(st.n_species) +
+                    static_cast(kTemp)] = temp;
+}
+
+void routeLidLayerTemperature(SimulationContext& ctx,
+                              const lid::LIDSolver& solver, double dt) {
+    auto& st = ctx.lid_layer_state;
+    if (!ctx.options.heat_transport || !st.active() || !(dt > 0.0)) return;
+
+    const double t_air = heat::airTempCelsius(ctx);
+    const double rho_w = ctx.options.water_density;
+    const double cp_w  = ctx.options.water_specific_heat;
+    const auto&  cc    = ctx.heat_config.conduction;
+    const bool   do_cond = ctx.heat_config.layer_conduction;
+    const bool   do_flux = ctx.heat_config.surface_exchange ||
+                           ctx.heat_config.radiative_exchange;
+
+    // H6a: runoff-clock binding, same reasoning as HeatWatershed
+    // (SolarRadiation.hpp).
+    heat::updateSolarForcing(ctx);
+
+    for (int t = 0; t < solver.numGroups(); ++t) {
+        const auto& g = solver.group(t);
+        if (g.count == 0) continue;
+        const auto ut = static_cast(t);
+        if (ut + 1 >= st.group_offset.size()) continue;
+
+        for (int u = 0; u < g.count; ++u) {
+            const auto ui   = static_cast(u);
+            const int  flat = st.group_offset[ut] + u;
+            if (flat < 0 || flat >= st.n_units) continue;
+            const auto uf = static_cast(flat);
+
+            const Donors d = donorsFor(g.type, g.soil_thick[ui] > 0.0);
+            const int donor[kNL] = {d.surface, d.pavement, d.soil, d.storage};
+            const double in_rate[kNL] = {g.in_surf[ui], g.in_pave[ui],
+                                         g.in_soil[ui], g.in_stor[ui]};
+            double v_new[kNL], thick[kNL];
+            layerVolumes(g, ui, v_new);
+            layerThickness(g, ui, thick);
+
+            const double t_ext =
+                st.inflow_value[uf * static_cast(st.n_species) +
+                                static_cast(kTemp)];
+
+            double t_old[kNL];
+            for (int k = 0; k < kNL; ++k)
+                t_old[k] = st.value[st.layer_index(flat,
+                                                   static_cast(k),
+                                                   kTemp)];
+
+            // ---- 1. Advection: complete-mix on the published inflows.
+            //         Donors are read from t_old, so a parcel cannot fall
+            //         through the whole stack in one step (A4's finding).
+            double tk[kNL];
+            bool   live[kNL];      ///< holds or receives WATER → advection
+            bool   mass[kNL];      ///< has THERMAL MASS → conduction, policy
+            for (int k = 0; k < kNL; ++k) {
+                const auto vidx = uf * kNL + static_cast(k);
+                const double v_old = st.vol_prev[vidx];
+                const double v_in  = std::max(0.0, in_rate[k]) * dt;
+
+                live[k] = (donor[k] != kAbsent) &&
+                          (v_old > kTinyVol || v_in > kTinyVol);
+
+                // "Holds water" and "has thermal mass" are NOT the same
+                // predicate, and the first draft used one for both. A buried
+                // layer is a matrix with water in its voids: dry, it still
+                // has `rho_s*cp_s` — the larger term — and it still conducts.
+                // A SURFACE layer is ponded water over a face, so dry it has
+                // nothing.
+                //
+                // Conflating them cost two things. The drying soil layer
+                // dropped out of the conduction system, leaving the wet
+                // surface conducting DIRECTLY into the wet storage layer
+                // across the gap that should insulate them. And it fell
+                // under the D-H5c dry policy, which then RESET a layer whose
+                // temperature is a real physical state governed by
+                // conduction. D-H5c answers "what does an element with no
+                // thermal mass report?" — a present soil matrix was never
+                // one of those.
+                mass[k] = (thick[k] > 0.0) &&
+                          ((k == kSurf) ? live[k] : donor[k] != kAbsent);
+
+                if (!live[k]) {
+                    // No water to mix. If there is also no thermal mass, the
+                    // deck's policy decides; otherwise the value is carried
+                    // and the thermal solve below governs it.
+                    tk[k] = mass[k] ? t_old[k]
+                                    : dryTemperature(ctx, t_old[k], t_air);
+                    st.vol_prev[vidx] = v_new[k];
+                    continue;
+                }
+
+                double tt = t_old[k];
+                if (v_in > kTinyVol) {
+                    const double t_in =
+                        (donor[k] == kExternal) ? t_ext
+                        : (donor[k] >= 0)       ? t_old[donor[k]]
+                                                : t_ext;
+                    const double den = v_old + v_in;
+                    tt = (den > kTinyVol)
+                             ? (tt * v_old + t_in * v_in) / den
+                             : t_in;
+                }
+                tk[k] = tt;                 // NO aging term, NO zero floor
+                st.vol_prev[vidx] = v_new[k];
+            }
+
+            if (!do_cond && !do_flux) {
+                for (int k = 0; k < kNL; ++k)
+                    st.value[st.layer_index(flat, static_cast(k),
+                                            kTemp)] = tk[k];
+            } else {
+                // ---- 2. ONE coupled thermal solve over the column.
+                //
+                // Conduction couples adjacent layers, so it is a second
+                // operator on the same state. Applying it as its own pass
+                // after a per-layer relaxation is exactly the composition
+                // defect D-H5e fixed between SurfaceExchange and
+                // RadiativeExchange (lesson 80) — it would land on whichever
+                // operator ran last. And applying it explicitly is stiff
+                // where it matters: a 1e-4 m film against 0.3 m of soil
+                // gives k*dt ~ 1.4 at a 60 s step, the regime that produced
+                // H5a's NaN.
+                //
+                // Backward Euler on the coupled system is therefore the
+                // scheme: unconditionally stable, and the inter-layer flux
+                // is evaluated ONCE at the new time and applied equal and
+                // opposite, so the column conserves energy exactly. Only the
+                // atmospheric term enters or leaves.
+                // Membership is `mass[k]`, not `live[k]` — see the comment
+                // where it is computed. A layer conducts if it HAS thermal
+                // mass, not if it holds water.
+                int  idx[kNL], n = 0;
+                for (int k = 0; k < kNL; ++k)
+                    if (mass[k]) idx[n++] = k;
+
+                if (n == 0) {
+                    for (int k = 0; k < kNL; ++k)
+                        st.value[st.layer_index(flat,
+                                                static_cast(k),
+                                                kTemp)] = tk[k];
+                    continue;
+                }
+
+                double cap[kNL], cond[kNL];
+                for (int i = 0; i < n; ++i) {
+                    const int k = idx[i];
+                    const double water_m = v_new[k] * kFtToM;
+                    cap[i]  = heatCapacity(cc, k, water_m, thick[k],
+                                           rho_w, cp_w) * thick[k];
+                    cond[i] = conductivity(cc, k, water_m, thick[k]);
+                }
+
+                double a[kNL] = {}, b[kNL] = {}, c[kNL] = {}, rhs[kNL] = {},
+                       out[kNL] = {};
+                for (int i = 0; i < n; ++i) {
+                    b[i]   = (cap[i] > 0.0) ? cap[i] : 1.0;
+                    rhs[i] = b[i] * tk[idx[i]];
+                }
+
+                if (do_cond) {
+                    for (int i = 0; i + 1 < n; ++i) {
+                        // Series resistance between layer centres: each half
+                        // thickness over its own conductivity. Using a single
+                        // averaged k over the whole gap would let a thin
+                        // high-conductivity layer dominate a thick one.
+                        const double r =
+                            0.5 * thick[idx[i]] / std::max(cond[i], 1.0e-12) +
+                            0.5 * thick[idx[i + 1]] /
+                                std::max(cond[i + 1], 1.0e-12);
+                        if (!(r > 0.0)) continue;
+                        const double h = dt / r;   // J/m2/K over the step
+                        b[i]     += h;  c[i]       = -h;
+                        b[i + 1] += h;  a[i + 1]   = -h;
+                    }
+                }
+
+                if (do_flux) {
+                    // Atmospheric flux on the TOPMOST PRESENT layer only.
+                    // A buried layer has no sky and no wind; the surface
+                    // layer of a stack that has one is where the exchange
+                    // happens, and for a rain barrel that layer is storage.
+                    const int top = idx[0];
+                    // PE1: a LID layer has no per-element attribute table
+                    // (kind LID resolves to the global in radiativeFor), but
+                    // the token is passed rather than defaulted so this call
+                    // site, like HeatWatershed's, says WHICH element it
+                    // means. This file was the call site the PE changeset
+                    // missed — a caller outside the changeset that a per-file
+                    // syntax check cannot see.
+                    const HeatElement el{HeatElemKind::LID, flat};
+                    const double j0 = heat::netFluxOut(ctx, el, tk[top]);
+                    const double j1 =
+                        heat::netFluxOut(ctx, el, tk[top] + heat::kProbeC);
+                    const double djdt = (j1 - j0) / heat::kProbeC;
+                    // Linearize as J(T) = j0 + J'(T - T0), the same
+                    // linearization relaxT performs, so the coupled solve
+                    // and the single-element relaxation agree in the limit
+                    // of one layer and no conduction.
+                    if (djdt > 0.0) {
+                        b[0]   += dt * djdt;
+                        rhs[0] += dt * (djdt * tk[top] - j0);
+                    } else {
+                        rhs[0] -= dt * j0;
+                    }
+                }
+
+                solveTridiagonal(n, a, b, c, rhs, out);
+                for (int k = 0; k < kNL; ++k)
+                    st.value[st.layer_index(flat, static_cast(k),
+                                            kTemp)] = tk[k];
+                for (int i = 0; i < n; ++i)
+                    if (std::isfinite(out[i]))
+                        st.value[st.layer_index(
+                            flat, static_cast(idx[i]), kTemp)] =
+                            out[i];
+            }
+
+            // The underdrain draws from the storage layer, matching A4's
+            // decision and `getDrainRate`'s own read of `stor_depth`. Roof
+            // disconnection has no storage: its drain is a routed fraction
+            // of the roof outflow, so it leaves at the surface temperature.
+            const bool from_surface = (g.type == lid::LIDType::ROOF_DISCON);
+            const auto src = from_surface ? LidLayer::SURFACE
+                                          : LidLayer::STORAGE;
+            st.drain_value[uf * static_cast(st.n_species) +
+                           static_cast(kTemp)] =
+                st.value[st.layer_index(flat, src, kTemp)];
+        }
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/HeatModule/HeatLid.hpp b/src/engine/transport/components/HeatModule/HeatLid.hpp
new file mode 100644
index 000000000..742b3317f
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatLid.hpp
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatLid.hpp
+ * @brief Phase H5b — temperature through the LID layer stack.
+ *
+ * @details A4 built `LidLayerSpeciesState` with a species stride for exactly
+ *          this. Temperature is row 1; nothing about the layer indexing
+ *          changes. What differs from `WaterAgeLid` is the same three things
+ *          `HeatWatershed` differs from `WaterAgeWatershed` by — no aging
+ *          term, no zero floor, and a dry layer takes the D-H5c policy
+ *          rather than A4's `= 0` — plus one that is new here: the column
+ *          exchanges heat with itself.
+ *
+ * @par The thermal step is COLUMN-COUPLED, and that is the call to challenge
+ *      Conduction couples adjacent layers, so it is a second operator on the
+ *      same state. Lesson 80 says an operator applied sequentially after a
+ *      relaxation does not compose — that is the defect D-H5e just fixed
+ *      between SurfaceExchange and RadiativeExchange, and applying
+ *      conduction as its own pass would reproduce it inside one phase.
+ *
+ *      So the whole column is stepped at once: atmospheric flux on the
+ *      exposed layer, conduction on every adjacent pair, solved implicitly
+ *      as one tridiagonal system.
+ *
+ *      Two alternatives were measured and rejected:
+ *        - **Per-layer relaxation with frozen neighbours** is stable, but the
+ *          energy leaving a layer is not the energy its neighbour receives,
+ *          so the column leaks. On a thin surface film relaxing fully toward
+ *          its equilibrium with the soil in one step, the leak is the whole
+ *          exchange.
+ *        - **Explicit conduction** conserves energy exactly but is stiff
+ *          where it matters. A 1e-4 m surface film against a 0.3 m soil
+ *          layer gives **`k·dt = 1.91` at a 60 s step** — the same regime
+ *          that produced H5a's NaN. Not "probably fine": computed, with the
+ *          module's own capacity and conductivity expressions. The same
+ *          column with the soil layer alone gives `k·dt = 5.3e-4`, which is
+ *          why conduction looks harmless until a film appears.
+ *
+ * @par Adjacency comes from the DONOR MAP, not a second table
+ *      `WaterAgeLid`'s `donorsFor` already encodes which layer feeds which,
+ *      per LID type, and for a vertical stack that IS the physical
+ *      adjacency. Writing a second stacking table would be a third copy of
+ *      the same topology, which is the shape of lesson 81.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §6 H5b, §6.1 D-H5b/D-H5c
+ * @see src/engine/transport/components/WaterAgeModule/WaterAgeLid.hpp
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_LID_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_LID_HPP
+
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+namespace openswmm::lid {
+class LIDSolver;
+struct LIDGroupSoA;
+}
+
+namespace openswmm::transport {
+
+/// Size the shared layer block if needed and seed the TEMPERATURE row from
+/// `HeatSource::INITIAL_STATE`. Independent of `initLidLayerAge`: either may
+/// run first, neither wipes the other (`LidLayerSpeciesState::ensureSized`).
+void initLidLayerTemperature(SimulationContext& ctx,
+                             const lid::LIDSolver& solver);
+
+/// Temperature of the water arriving at one unit this step, flow-weighted
+/// over the same four rates `setLidInflowAge` weights. Mirrors it exactly,
+/// including its hard-won choice to take the SUBCATCHMENT's published
+/// runoff value rather than reconstructing a mean from the subarea rows.
+void setLidInflowTemperature(SimulationContext& ctx, int type_index, int unit,
+                             int subcatch, double rain_rate, double q_imperv,
+                             double q_perv, double q_runon, double lid_area);
+
+/// Advance every LID column one runoff step: advective mixing per layer,
+/// then one coupled thermal solve over the stack. Publishes the underdrain
+/// temperature, retiring `HeatSource::RAINFALL`'s "(and LID drains until
+/// H5)" marker.
+void routeLidLayerTemperature(SimulationContext& ctx,
+                              const lid::LIDSolver& solver, double dt);
+
+/**
+ * @brief Heat capacity of one layer, J/m²/K over the layer's footprint.
+ *
+ * @details Exported so a gate can sum a column's heat content and assert
+ *          conservation WITHOUT restating the water/matrix mixture — a
+ *          second copy of it in the test would make the gate agree with
+ *          itself rather than with the code. Zero for an absent layer.
+ */
+double lidLayerHeatCapacity(const SimulationContext& ctx,
+                            const lid::LIDGroupSoA& g, std::size_t unit,
+                            int layer) noexcept;
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_LID_HPP
diff --git a/src/engine/transport/components/HeatModule/HeatWatershed.cpp b/src/engine/transport/components/HeatModule/HeatWatershed.cpp
new file mode 100644
index 000000000..afb8aa75e
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatWatershed.cpp
@@ -0,0 +1,317 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatWatershed.cpp
+ * @brief Phase H5a — temperature on subcatchment surfaces.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §6 H5a, §6.1
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "HeatWatershed.hpp"
+
+#include "../WatershedCommon.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../hydrology/Runoff.hpp"
+#include "../HeatFluxModules/HeatFluxes.hpp"
+#include "../HeatFluxModules/SolarRadiation.hpp"
+#include "../HeatFluxModules/SurfaceExchange.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr int    kNSub    = HeatState::kNSubArea;
+constexpr double kTinyVol = 1.0e-12;  ///< ft³
+
+// `kMaxStepC` lived here: the refuse-above-5-°C bound H5a used to stop the
+// forward-Euler divergence. D-H5d removed it with the divergence — a
+// relaxation step cannot overshoot equilibrium, so there is nothing left to
+// refuse, and keeping a threshold nothing can reach would be a constant that
+// no gate could observe being wrong (lesson 39).
+
+/// What a subarea holding no water reports (plan D-H5c).
+///
+/// A4's age rule — "no water, no age", write 0 — cannot be reused, because
+/// 0 °C is a real temperature and a reader has no way to tell the sentinel
+/// from a freezing puddle. The policy is the deck's choice.
+double dryTemperature(const SimulationContext& ctx, double held,
+                      double t_air_c) noexcept {
+    switch (ctx.heat_config.dry_temp_policy) {
+        case DryTempPolicy::AIR:     return t_air_c;
+        case DryTempPolicy::DEFAULT: return HeatConfigData::kDefaultTemp;
+        case DryTempPolicy::HOLD:
+        default:                     return held;
+    }
+}
+
+}  // namespace
+
+void addRunonTemperature(SimulationContext& ctx, int donor_sc,
+                         int receiver_sc, double q) {
+    if (!ctx.options.heat_transport) return;
+    auto& hs = ctx.heat_state;
+    const auto ud = static_cast(donor_sc);
+    const auto ur = static_cast(receiver_sc);
+    if (ud >= hs.subcatch_runoff_temp.size() ||
+        ur >= hs.subcatch_runon_temp_vol_in.size() ||
+        ur >= hs.subcatch_runon_temp_rate.size())
+        return;
+    addRunonTemperatureAt(ctx, receiver_sc, q, hs.subcatch_runoff_temp[ud]);
+}
+
+void addRunonTemperatureAt(SimulationContext& ctx, int receiver_sc, double q,
+                           double temp_c) {
+    if (!ctx.options.heat_transport || !(q > 0.0)) return;
+    auto& hs = ctx.heat_state;
+    const auto ur = static_cast(receiver_sc);
+    if (ur >= hs.subcatch_runon_temp_vol_in.size() ||
+        ur >= hs.subcatch_runon_temp_rate.size())
+        return;
+    // Numerator AND denominator, always together. Adding to one without the
+    // other is the shape of A3's defect, and keeping them in a single
+    // function is what makes that shape hard to write by accident.
+    hs.subcatch_runon_temp_vol_in[ur] += q * temp_c;
+    hs.subcatch_runon_temp_rate[ur]   += q;
+}
+
+void routeSubcatchmentTemperature(SimulationContext& ctx,
+                                  const runoff::RunoffSoA& soa, double dt) {
+    if (!ctx.options.heat_transport || dt <= 0.0) return;
+
+    auto& hs  = ctx.heat_state;
+    const int nsc = ctx.n_subcatches();
+    if (nsc <= 0) return;
+    // Seed from INITIAL_STATE, not kDefaultTemp: that is the source meaning
+    // "water already in the model at t = 0", and it is exactly what
+    // QualityRouting.cpp:164-166 seeds the node and link temperatures from.
+    // A dry surface at t = 0 holds no water, but the first rain mixes
+    // against this value, so seeding it differently from the network would
+    // put a discontinuity at the outlet that no gate would name.
+    if (!hs.watershedSized(nsc))
+        hs.resizeWatershed(nsc, ctx.heat_config.global_temp[
+            static_cast(HeatSource::INITIAL_STATE)]);
+
+    // Temperature of water arriving from the sky. RAINFALL is the pathway
+    // the wet-weather loader already uses, so one table governs both.
+    const double t_rain = ctx.heat_config.global_temp[
+        static_cast(HeatSource::RAINFALL)];
+
+    // Met forcing. These are written in stepRunoff at SWMMEngine.cpp:1379
+    // (air), :1424 (wind) and :1431 (humidity), all BEFORE runoff_.execute
+    // at :1648 — so they are current here, which is the fact that made the
+    // runoff-clock binding possible at all.
+    // Air temperature is still read here — the DRY-element policy needs it
+    // (D-H5c). The humidity, wind and wind-function coefficients that used
+    // to be extracted alongside it moved inside the shared flux evaluators
+    // with D-H5e, so this function no longer knows which parameters a flux
+    // family reads.
+    const double t_air = heat::airTempCelsius(ctx);
+    const double rho   = ctx.options.water_density;
+    const double cp    = ctx.options.water_specific_heat;
+
+    const bool do_surface   = ctx.heat_config.surface_exchange;
+    const bool do_radiative = ctx.heat_config.radiative_exchange;
+
+    // H6a: this binding runs on the RUNOFF clock, the node/link one on the
+    // routing clock, so each resolves its own step's solar forcing
+    // (SolarRadiation.hpp). Idempotent within a step.
+    heat::updateSolarForcing(ctx);
+
+    for (int i = 0; i < nsc && i < static_cast(soa.area.size()); ++i) {
+        const auto ui = static_cast(i);
+
+        // `soa.area` is ft2, LID-excluded. `ctx.subcatches.area` is the
+        // deck's USER area units (acres here — Runoff.cpp:197 divides by
+        // ucf_area before subtracting the LID footprint), so substituting it
+        // is a 43560x error, not the footprint double-count it looks like.
+        // See the header: the exchange area cancels in `relaxT`, so only the
+        // run-on depth conversion below can see this.
+        const double area = soa.area[ui];
+        const double fi   = soa.imperv_pct[ui];
+        const double fp   = 1.0 - fi;
+        const double f0   = soa.frac_imperv0[ui];
+        const double f1   = soa.frac_imperv1[ui];
+
+        const double frac[kNSub]  = {f0, f1, fp};
+        const double depth[kNSub] = {soa.depth_imperv0[ui],
+                                     soa.depth_imperv1[ui],
+                                     soa.depth_perv[ui]};
+
+        // Run-on spreads over the whole subcatchment as extra precipitation
+        // (Runoff.cpp:331-333), so it mixes into every subarea in proportion
+        // to that subarea's share of the inflow.
+        const double runon_rate =
+            (ui < ctx.subcatches.runon_inflow.size())
+                ? ctx.subcatches.runon_inflow[ui]
+                : 0.0;
+
+        // Divide by the rate whose temperature is KNOWN, not by the total
+        // run-on. A3 divided by the total while filling the numerator from
+        // one of three contributors, and the arriving age came out younger
+        // than anything entering the model. Since H5b all three contributors
+        // — cascade, outfall return and LID underdrain — supply one, so the
+        // two rates coincide today; the pair is what keeps a FOURTH
+        // contributor from reintroducing the defect, and
+        // `EveryRunonContributorKeepsTemperaturesInsideTheSources` asserts
+        // they still match.
+        const double known_rate =
+            (ui < hs.subcatch_runon_temp_rate.size())
+                ? hs.subcatch_runon_temp_rate[ui]
+                : 0.0;
+        const double runon_temp =
+            (known_rate > kTinyVol &&
+             ui < hs.subcatch_runon_temp_vol_in.size())
+                ? hs.subcatch_runon_temp_vol_in[ui] / known_rate
+                : t_rain;
+
+        // Run-on spreads over the whole subcatchment, so its depth rate is
+        // the same for every subarea. The PRECIPITATION rate is not.
+        const double runon_depth_rate = (area > 0.0) ? runon_rate / area : 0.0;
+
+        double out_num = 0.0, out_den = 0.0;
+        for (int k = 0; k < kNSub; ++k) {
+            const auto idx = ui * static_cast(kNSub) +
+                             static_cast(k);
+            if (idx >= hs.subarea_temp.size()) break;
+
+            // S1: the water that ACTUALLY reached THIS subarea — the gage
+            // rate on a bare subcatchment, `imelt + rain·(1 − asc)` under a
+            // snowpack, and different BETWEEN subareas in the second case.
+            // See WatershedCommon.hpp; A3's copy of this read had the same
+            // defect and is fixed in the same changeset.
+            const double rain_rate = arrivingPrecipRate(ctx, ui, k);
+            const double in_rate = rain_rate + runon_depth_rate;
+
+            // S2: the temperature of that precipitation. Under a pack it is
+            // NOT the configured RAINFALL value — the arriving water is part
+            // meltwater, which is at 0 °C essentially by definition, and
+            // part rain that reached the ground through the snow-free
+            // fraction. `arrivingPrecipTemperature` blends the two and
+            // returns the configured value unchanged wherever there is no
+            // pack, so a bare deck is untouched.
+            const double t_precip = arrivingPrecipTemperature(ctx, ui, k);
+
+            // Arriving water is precipitation and run-on MIXED, flow-
+            // weighted. Rain routinely outweighs run-on by orders of
+            // magnitude, so treating the arrival as pure run-on wherever any
+            // exists would hand the whole inflow the donor's temperature.
+            const double t_in = (in_rate > 0.0)
+                ? (rain_rate * t_precip + runon_depth_rate * runon_temp) / in_rate
+                : t_precip;
+
+            const double v_new = depth[k] * frac[k] * area;
+            const double v_old = hs.subarea_vol_prev[idx];
+            const double v_in  = in_rate * frac[k] * area * dt;
+            const double a_ft2 = frac[k] * area;
+
+            double t = hs.subarea_temp[idx];
+
+            // A subarea with no water and none arriving has no thermal mass
+            // to speak of. Applying a flux to it would divide by ~zero, and
+            // A4's answer (write 0) is wrong for a temperature — so the
+            // deck's policy decides, and the volume ledger still advances.
+            if (v_old <= kTinyVol && v_in <= kTinyVol) {
+                hs.subarea_temp[idx]     = dryTemperature(ctx, t, t_air);
+                hs.subarea_vol_prev[idx] = v_new;
+                continue;
+            }
+
+            // 1. The surface energy balance acts on the water that is
+            //    ALREADY there, over that subarea's ponded area (D-H5a).
+            //    Applying it to the post-mix volume instead would let a
+            //    step's rain be heated before it had arrived.
+            if (v_old > kTinyVol && (do_surface || do_radiative)) {
+                // Net outward flux, via the shared composition (D-H5e).
+                // This was a hand-rolled sum of the two modules — the fourth
+                // such copy in the program, and copies of exactly this sum
+                // are how the LEGACY node/link path ended up relaxing each
+                // module separately toward a different equilibrium.
+                // PE1: a subarea is scoped to its SUBCATCHMENT. There is
+                // no per-subcatchment radiative override table (a
+                // watershed's shading is a land-cover input this program
+                // models elsewhere), so this resolves to the global — but
+                // the token is passed rather than defaulted so the call
+                // site says WHICH element it means.
+                const HeatElement er = HeatElement::subcatch(i);
+                const auto net_out = [&](double tw) {
+                    return heat::netFluxOut(ctx, er, tw);
+                };
+                // Both flux families are signed POSITIVE OUT of the water, so
+                // they add. There is exactly one sign flip in this program
+                // and it lives inside `relaxT`; a second one here would
+                // silently cancel it.
+                //
+                // D-H5d: SEMI-IMPLICIT. H5a shipped a forward-Euler step and
+                // a refuse-above-5 C bound, because a ponded film has almost
+                // no thermal mass per unit exchanging area: a 0.52 ft3 film
+                // over 27226 ft2 moved 862 C in one 60 s step and the
+                // sequence diverged 5 -> 182 -> -1.8e4 -> -3.9e9 -> inf ->
+                // NaN. The bound stopped the divergence but made an
+                // unresolved film carry its inflow temperature instead of
+                // exchanging at all. Relaxation removes both problems: the
+                // step cannot overshoot the equilibrium temperature however
+                // thin the film, so there is nothing left to refuse.
+                t += heat::relaxT(net_out(t), net_out(t + heat::kProbeC),
+                                  heat::kProbeC, a_ft2 * heat::kSqFtToSqM,
+                                  v_old * heat::kCuFtToCuM, dt, rho, cp);
+            }
+
+            // 2. What arrived mixes in by GROSS inflow volume — never the
+            //    net gain. A subarea shedding as fast as it fills has
+            //    v_new == v_old and so no net gain at all, which is the
+            //    ordinary state of an impervious surface under rain; A3
+            //    measured that mistake at 6.3x on the age it produced.
+            if (v_in > kTinyVol) {
+                const double denom = v_old + v_in;
+                t = (denom > kTinyVol) ? (t * v_old + t_in * v_in) / denom
+                                       : t_in;
+            }
+
+            // No aging term and NO ZERO FLOOR. `WaterAgeWatershed` clamps
+            // with max(a, 0) because a negative age is meaningless; a
+            // sub-zero temperature is ordinary, and clamping it would
+            // silently manufacture energy on every frozen surface.
+            hs.subarea_temp[idx]     = t;
+            hs.subarea_vol_prev[idx] = v_new;
+
+            // 3. Runoff leaves at the volume-weighted mean of the subareas
+            //    HOLDING water. Weighting by area would let a dry pervious
+            //    surface — whose temperature is a policy value, not a
+            //    measurement — drag the runoff temperature.
+            if (v_new > kTinyVol) {
+                out_num += t * v_new;
+                out_den += v_new;
+            }
+        }
+        if (ui < hs.subcatch_runoff_temp.size())
+            hs.subcatch_runoff_temp[ui] =
+                (out_den > kTinyVol) ? out_num / out_den : t_rain;
+    }
+
+    // The run-on accumulators are zeroed by SWMMEngine::assembleRunon at the
+    // start of the next runoff step, beside the flow they describe.
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/HeatModule/HeatWatershed.hpp b/src/engine/transport/components/HeatModule/HeatWatershed.hpp
new file mode 100644
index 000000000..03e5fb416
--- /dev/null
+++ b/src/engine/transport/components/HeatModule/HeatWatershed.hpp
@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file HeatWatershed.hpp
+ * @brief Phase H5a — temperature on subcatchment surfaces.
+ *
+ * @details This is A3's `WaterAgeWatershed` with the same complete-mix
+ *          bookkeeping and three deliberate differences, which are the
+ *          whole content of the file:
+ *
+ *          1. **No aging term.** Age gains `+dt` every step because that is
+ *             what age IS. Temperature gains nothing from the passage of
+ *             time; it changes only by mixing and by flux.
+ *          2. **No zero floor.** `WaterAgeWatershed` clamps with
+ *             `std::max(a, 0.0)` because a negative age is meaningless. A
+ *             negative temperature is ordinary — this is the same difference
+ *             `HeatLegacy` makes against `WaterAgeLegacy`.
+ *          3. **A dry subarea is not zero.** A4 writes 0 for a layer holding
+ *             no water ("no water, no age"); 0 °C is a real temperature, so
+ *             the answer is the deck's `DryTempPolicy` (plan D-H5c).
+ *
+ * @par Why the surface energy balance is here and not in H6
+ *      The H5 plan line scoped "temperature states" but its verify criterion
+ *      was a *runoff temperature equilibration* test, which advection alone
+ *      cannot produce: without atmospheric exchange a ponded subarea holds
+ *      the rain temperature forever. D-H5a resolved that by pulling the
+ *      balance forward. The flux modules themselves are H2's and H3's,
+ *      unchanged — only the binding is new.
+ *
+ * @par The exchange area, and the trap in it
+ *      Heat crosses the free surface exactly where evaporation does (H2's
+ *      precedent). On a subcatchment that surface is the ponded subarea:
+ *      `RunoffSoA::area × frac[k]`.
+ *
+ *      `RunoffSoA::area` is **not** `ctx.subcatches.area`, and the
+ *      difference is bigger than it looks. `Runoff.cpp:197-199` builds it as
+ *      `ctx.subcatches.area / ucf_area − total_lid_area_ft2`: the SoA row is
+ *      **ft²**, the context row is in the deck's **user area units** —
+ *      acres in US customary, a factor of 43560. The LID footprint is the
+ *      second, far smaller correction. Substituting `ctx.subcatches.area`
+ *      here was measured at 14.34 °C against 12.95 °C on a LID deck, with
+ *      the ponded volume ledger collapsing from 27342 ft³ to 0.78 ft³.
+ *
+ *      Note what does NOT go wrong: a temperature is intensive, and the
+ *      exchange area cancels exactly against the thermal mass in `relaxT`
+ *      (it enters only through `k = A·J′/(ρ cp V)`, and `A / V ≡ 1 /
+ *      depth_prev`), so the flux term alone cannot
+ *      see the substitution. It survives only through
+ *      `runon_depth_rate = runon_rate / area`, which converts a run-on flow
+ *      into the depth rate that weights it against rainfall. That is the
+ *      one place the number has to be right, and it is not where the
+ *      double-counting argument would look.
+ *
+ * @par Clocks
+ *      This runs on the RUNOFF clock, immediately after `runoff_.execute`,
+ *      because that is when the depths it reads are current. H2's node and
+ *      link bindings run on the ROUTING clock inside `routeLegacyHeat`.
+ *      Both are correct; the `dt` each passes is its own, and conflating
+ *      them would scale every flux by the wrong interval.
+ *
+ * @see plans/transport/HEAT_TRANSPORT_PLAN.md §6 H5a, §6.1 D-H5a/D-H5c
+ * @see src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.hpp
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_HEAT_WATERSHED_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_HEAT_WATERSHED_HPP
+
+namespace openswmm {
+struct SimulationContext;
+}
+namespace openswmm::runoff {
+struct RunoffSoA;
+}
+
+namespace openswmm::transport {
+
+/**
+ * @brief Accumulate run-on temperature from `donor_sc` onto `receiver_sc`.
+ *
+ * @details The RATE convention every loader uses: donors add `q · T`, the
+ *          consumer divides by the total rate. Mirrors `addRunonAge`, and
+ *          must be called at **every** contributor to `runon_inflow` — the
+ *          subcatchment cascade, the LID underdrain return, and the outfall
+ *          return. A3 filled this numerator from one of the three and
+ *          divided by all three, which produced arriving water younger than
+ *          anything entering the model. The temperature analogue of that
+ *          defect is quieter and worse: a missing contributor pulls the
+ *          arriving temperature toward 0 °C, which is a plausible number.
+ *
+ * @param q Volumetric flow rate, ft³/s.
+ */
+void addRunonTemperature(SimulationContext& ctx, int donor_sc,
+                         int receiver_sc, double q);
+
+/**
+ * @brief Accumulate run-on at an explicitly supplied temperature.
+ *
+ * @details For contributors whose donor is not another subcatchment: the
+ *          outfall return (which carries `heat_state.node_temp`) and, from
+ *          H5b, the LID underdrain. Adds to the numerator **and** the rate
+ *          together — the pairing is why this is one function and not two
+ *          array writes at each call site.
+ *
+ * @param q      Volumetric flow rate, ft³/s.
+ * @param temp_c Temperature of that flow, °C.
+ */
+void addRunonTemperatureAt(SimulationContext& ctx, int receiver_sc, double q,
+                           double temp_c);
+
+/**
+ * @brief Advance ponded subarea temperatures one runoff step.
+ *
+ * @details Per subarea, in order: apply the surface energy balance to the
+ *          water that was already there, mix in what arrived by GROSS
+ *          inflow volume, then publish the subcatchment's runoff
+ *          temperature as the volume-weighted mean of the subareas holding
+ *          water. Outflow leaves at the subarea's own temperature, so only
+ *          the inflow is needed — the same complete-mix argument A3 arrived
+ *          at after its net-gain estimate proved to be a 6.3× defect.
+ *
+ * @param soa The solver's own SoA. `ctx.subcatches.ponded_depth` is declared
+ *            but written by nobody; reading it would give zeros.
+ * @param dt  Runoff timestep, seconds.
+ */
+void routeSubcatchmentTemperature(SimulationContext& ctx,
+                                  const runoff::RunoffSoA& soa, double dt);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_HEAT_WATERSHED_HPP
diff --git a/src/engine/transport/components/LidLayerCommon.cpp b/src/engine/transport/components/LidLayerCommon.cpp
new file mode 100644
index 000000000..3eb54888b
--- /dev/null
+++ b/src/engine/transport/components/LidLayerCommon.cpp
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file LidLayerCommon.cpp
+ * @brief LID layer topology and geometry, shared by every species track.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "LidLayerCommon.hpp"
+
+namespace openswmm::transport {
+
+Donors donorsFor(lid::LIDType t, bool has_soil) {
+    switch (t) {
+        case lid::LIDType::BIO_CELL:
+        case lid::LIDType::RAIN_GARDEN:
+            // Rain garden is the storage-less bio-cell; its stor_thick is 0,
+            // so in_stor stays 0 and the storage row never mixes.
+            return {kExternal, kAbsent, kSurf, kSoil};
+        case lid::LIDType::GREEN_ROOF:
+            // "Storage" is the drainage mat, fed by soil percolation.
+            return {kExternal, kAbsent, kSurf, kSoil};
+        case lid::LIDType::INFIL_TRENCH:
+            return {kExternal, kAbsent, kAbsent, kSurf};
+        case lid::LIDType::PERM_PAVEMENT:
+            // The only four-layer stack, and the only conditional donor:
+            // storage takes soil percolation when there is a soil layer and
+            // pavement percolation when there is not, exactly as the solver's
+            // storageInflow_local resolves it.
+            return {kExternal, kSurf, kPave, has_soil ? kSoil : kPave};
+        case lid::LIDType::RAIN_BARREL:
+            // Storage is the ONLY layer, and it is therefore the topmost
+            // present one — its inflow is external, not from a layer above.
+            return {kAbsent, kAbsent, kAbsent, kExternal};
+        case lid::LIDType::VEG_SWALE:
+        case lid::LIDType::ROOF_DISCON:
+            return {kExternal, kAbsent, kAbsent, kAbsent};
+    }
+    return {kExternal, kAbsent, kAbsent, kAbsent};
+}
+
+/// Void-weighted water held in each layer, as a depth per unit area (ft).
+/// The four terms are exactly those `LIDSolver::storedVolume()` sums, so a
+/// layer's age is weighted by the same water the mass balance counts.
+void layerVolumes(const lid::LIDGroupSoA& g, std::size_t ui,
+                  double (&v)[kNL]) {
+    v[kSurf] = g.surf_depth[ui] * g.surf_void_frac[ui];
+    v[kPave] = g.pave_depth[ui] * g.pave_void[ui] *
+               (1.0 - g.pave_imperv_frac[ui]);
+    v[kSoil] = g.soil_moist[ui] * g.soil_thick[ui];
+    v[kStor] = g.stor_depth[ui] * g.stor_void[ui];
+}
+
+std::vector buildOffsets(const lid::LIDSolver& solver) {
+    std::vector off;
+    off.reserve(static_cast(solver.numGroups()) + 1);
+    int running = 0;
+    for (int t = 0; t < solver.numGroups(); ++t) {
+        off.push_back(running);
+        running += solver.group(t).count;
+    }
+    off.push_back(running);
+    return off;
+}
+
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/LidLayerCommon.hpp b/src/engine/transport/components/LidLayerCommon.hpp
new file mode 100644
index 000000000..2b6f581a9
--- /dev/null
+++ b/src/engine/transport/components/LidLayerCommon.hpp
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file LidLayerCommon.hpp
+ * @brief LID layer topology and geometry, shared by every species track.
+ *
+ * @details A4 wrote these as file-local helpers in `WaterAgeLid.cpp`, when
+ *          age was the only species. H5b adds temperature and needs the same
+ *          three facts: which layer feeds which, how much water each holds,
+ *          and how the per-type groups flatten to unit indices.
+ *
+ *          They are extracted rather than copied. Copies of exactly this
+ *          kind of shared expression are what let `RadiativeExchange`
+ *          acquire its own element traversal and thereby its own copy of
+ *          H2's divergence (D-H5e, lesson 81) — and the donor map is worse
+ *          to duplicate than a traversal, because it encodes eight
+ *          hand-checked per-type stacks.
+ *
+ * @par The donor map is also the PHYSICAL adjacency
+ *      For a vertical stack, "which layer feeds which" and "which layers
+ *      touch" are the same relation. H5b's conduction term therefore reads
+ *      this map rather than introducing a second stacking table that could
+ *      disagree with it.
+ *
+ * @see src/engine/data/LidLayerSpeciesData.hpp
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_LID_LAYER_COMMON_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_LID_LAYER_COMMON_HPP
+
+#include 
+
+#include "../../data/LidLayerSpeciesData.hpp"
+#include "../../hydrology/LID.hpp"
+
+namespace openswmm::transport {
+
+constexpr int kNL = LidLayerSpeciesState::kLayerCount;
+
+/// -1 means "external to the unit"; -2 means "this type has no such layer".
+constexpr int kExternal = -1;
+constexpr int kAbsent   = -2;
+
+constexpr int kSurf = static_cast(LidLayer::SURFACE);
+constexpr int kPave = static_cast(LidLayer::PAVEMENT);
+constexpr int kSoil = static_cast(LidLayer::SOIL);
+constexpr int kStor = static_cast(LidLayer::STORAGE);
+
+/// Where each layer's water comes from — and, equivalently, which layers are
+/// physically adjacent. Explicit per type rather than inferred: the eight
+/// stacks genuinely differ, and the solver is itself written one routine per
+/// type.
+struct Donors { int surface, pavement, soil, storage; };
+
+Donors donorsFor(lid::LIDType t, bool has_soil);
+
+/// Void-weighted water held in each layer, as a depth per unit area (ft).
+/// The four terms are exactly those `LIDSolver::storedVolume()` sums.
+void layerVolumes(const lid::LIDGroupSoA& g, std::size_t ui,
+                  double (&v)[kNL]);
+
+/// Flat index of each per-type group's first unit; `back() == n_units`.
+std::vector buildOffsets(const lid::LIDSolver& solver);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_LID_LAYER_COMMON_HPP
diff --git a/src/engine/transport/components/ReactionModule/MsxLegacyTransport.cpp b/src/engine/transport/components/ReactionModule/MsxLegacyTransport.cpp
new file mode 100644
index 000000000..3636f4bb4
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/MsxLegacyTransport.cpp
@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxLegacyTransport.cpp
+ * @brief R4b body. Formula provenance is `routeLegacyHeat` — see the header.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "MsxLegacyTransport.hpp"
+
+#include 
+#include 
+#include 
+
+#include "ReactionLegacyBinding.hpp"
+#include "../../../core/SimulationContext.hpp"
+#include "../../../quality/QualityRouting.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+/// The quality path's own thresholds — one litre and one millimetre, the
+/// numbers legacy qualrout.c routes on. This mirror previously carried a
+/// local 1e-10, so it dispatched differently from the family it mirrors.
+using quality::ZERO_DEPTH;
+using quality::LEGACY_ZERO;
+
+/// Routing-thread scratch (the BindingScratch pattern). Strided per species:
+/// the node/link snapshots and the per-node mass-rate accumulator.
+struct MsxScratch {
+    std::vector node_old, link_old, mass_in;
+    void ensure(std::size_t nn, std::size_t nl, std::size_t ns) {
+        if (node_old.size() != nn * ns) {
+            node_old.assign(nn * ns, 0.0);
+            mass_in.assign(nn * ns, 0.0);
+        }
+        if (link_old.size() != nl * ns) link_old.assign(nl * ns, 0.0);
+    }
+};
+MsxScratch& scratch() {
+    static MsxScratch s;
+    return s;
+}
+}  // namespace
+
+void routeLegacyMsx(SimulationContext& ctx, double dt) {
+    auto& rx = ctx.reactions;
+    const int nsp = rx.n_species();
+    if (nsp <= 0 || dt <= 0.0) return;
+
+    const int nn = ctx.n_nodes();
+    const int nl = ctx.n_links();
+    const auto uns = static_cast(nsp);
+
+    // R4's seeding path — sizes the arrays and applies GLOBAL +
+    // [REACTION_QUALITY] fills exactly once, whichever dispatch touches the
+    // state first this run.
+    ensureMsxState(ctx);
+    if (rx.msx_node_conc.size() < static_cast(nn) * uns ||
+        rx.msx_link_conc.size() < static_cast(nl) * uns)
+        return;
+
+    auto& sc = scratch();
+    sc.ensure(static_cast(nn), static_cast(nl),
+              uns);
+
+    // ---- 1. Old-state snapshots (post-reaction: the react stages ran
+    //         earlier in execute(), so transport moves this step's reacted
+    //         concentrations — the Lie split the header documents). --------
+    std::copy(rx.msx_node_conc.begin(),
+              rx.msx_node_conc.begin() +
+                  static_cast(static_cast(nn) *
+                                              uns),
+              sc.node_old.begin());
+    std::copy(rx.msx_link_conc.begin(),
+              rx.msx_link_conc.begin() +
+                  static_cast(static_cast(nl) *
+                                              uns),
+              sc.link_old.begin());
+
+    // ---- 2. Mass accumulation (accumulateLinkLoads mirror, RATE
+    //         convention q·c_old into the downstream node). ----------------
+    std::fill(sc.mass_in.begin(), sc.mass_in.end(), 0.0);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        const double q = std::fabs(ctx.links.flow[uj]);
+        if (q <= 0.0) continue;
+        const int dn = (ctx.links.flow[uj] >= 0.0) ? ctx.links.node2[uj]
+                                                   : ctx.links.node1[uj];
+        if (dn < 0 || dn >= nn) continue;
+        const auto udn = static_cast(dn);
+        for (std::size_t s = 0; s < uns; ++s)
+            sc.mass_in[udn * uns + s] += q * sc.link_old[uj * uns + s];
+    }
+
+    // ---- 3. Node mixing (mixAtNodes mirror; no evap factor). External
+    //         loads: U2 (2026-09-07) — [INFLOWS] rows naming a species
+    //         arrive through msx_ext_mass_in (a RATE, the qual_mass_in
+    //         shape) and join the link mass here; empty when no such row
+    //         exists, so species-only-from-reactions decks are unchanged.
+    //         The clamp is TWO-SIDED like the heat mirror's: mixing cannot
+    //         exceed the larger of the held and incoming concentrations,
+    //         nor go below zero. --------------------------------------------
+    const bool has_ext = rx.msx_ext_mass_in.size() >=
+                         static_cast(nn) * uns;
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        const double v_old = ctx.nodes.old_volume[ui];
+        const double v_in  = ctx.nodes.qual_vol_in[ui];
+        const double q_in  = (dt > 0.0) ? v_in / dt : 0.0;
+        const bool zero_bf = ctx.options.outfall_backflow_zero &&
+                             ctx.nodes.type[ui] == NodeType::OUTFALL &&
+                             v_in <= 0.0;
+        // The quality path's dispatch and dry-node rule, asked rather than
+        // re-derived — a species IS a concentration, so both carry over
+        // exactly as they do for a pollutant.
+        const bool reactor = quality::nodeIsReactor(ctx, i);
+        const bool dry     = quality::nodeIsDry(ctx, i, q_in);
+        for (std::size_t s = 0; s < uns; ++s) {
+            const double c_old = sc.node_old[ui * uns + s];
+            const double ext_rate = has_ext ? rx.msx_ext_mass_in[ui * uns + s] : 0.0;
+            const double mass = (sc.mass_in[ui * uns + s] + ext_rate) * dt;
+
+            if (!reactor) {
+                // findNodeQual: no storage volume, so the concentration is
+                // the inflow's.
+                // The gate is legacy's `qNode > ZERO` on the RATE, the same
+                // one the reactor half below uses — not "v_in is non-zero",
+                // which divides residual mass by residual volume.
+                double c;
+                if (q_in > LEGACY_ZERO)    c = mass / v_in;
+                else if (zero_bf)          c = 0.0;
+                else if (ctx.nodes.depth[ui] > ZERO_DEPTH) c = c_old;
+                else                       c = 0.0;
+                rx.msx_node_conc[ui * uns + s] = std::max(c, 0.0);
+                continue;
+            }
+
+            double c_new;
+            if (q_in <= LEGACY_ZERO) {
+                c_new = zero_bf ? 0.0 : c_old;
+            } else {
+                const double c_in  = mass / v_in;
+                const double c_max = std::max(c_old, c_in);
+                c_new = (c_old * v_old + mass) / (v_old + v_in);
+                c_new = std::min(c_new, c_max);
+            }
+            if (dry) c_new = 0.0;
+            rx.msx_node_conc[ui * uns + s] = std::max(c_new, 0.0);
+        }
+    }
+
+    // ---- 4. Link update (updateLinkQuality mirror; k = 0, no evap). ------
+    const bool is_steady =
+        (ctx.options.routing_model == RoutingModel::STEADY);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        // Steady flow draws on node1 unconditionally (findSFLinkQual).
+        const int up = is_steady
+                           ? ctx.links.node1[uj]
+                           : ((ctx.links.flow[uj] >= 0.0) ? ctx.links.node1[uj]
+                                                          : ctx.links.node2[uj]);
+        if (up < 0 || up >= nn) continue;
+        const auto uup = static_cast(up);
+
+        // A non-conduit or DUMMY link holds no water: upstream outright.
+        const bool passthrough = quality::linkTakesUpstreamValue(ctx, j);
+        const double v_old = ctx.links.old_volume[uj];
+        const double q_in  = passthrough
+                                 ? 0.0
+                                 : quality::conduitMixingInflow(ctx, j, dt);
+        const bool dry = !is_steady && !passthrough && quality::linkIsDry(ctx, j);
+
+        for (std::size_t s = 0; s < uns; ++s) {
+            const double c_old = sc.link_old[uj * uns + s];
+            const double c_up  = rx.msx_node_conc[uup * uns + s];
+            double c_new;
+            if (passthrough || is_steady) {
+                c_new = c_up;
+            } else if (q_in <= LEGACY_ZERO) {
+                c_new = c_old;
+            } else {
+                const double v_in  = q_in * dt;
+                const double c_max = std::max(c_old, c_up);
+                c_new = (c_old * v_old + c_up * v_in) / (v_old + v_in);
+                c_new = std::min(c_new, c_max);
+            }
+            if (dry) c_new = 0.0;
+            rx.msx_link_conc[uj * uns + s] = std::max(c_new, 0.0);
+        }
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/MsxLegacyTransport.hpp b/src/engine/transport/components/ReactionModule/MsxLegacyTransport.hpp
new file mode 100644
index 000000000..6e65165c6
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/MsxLegacyTransport.hpp
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file MsxLegacyTransport.hpp
+ * @brief Phase R4b (transport half) — MSX species advect under LEGACY.
+ *
+ * @details R4 gave MSX species per-element STATE and per-element REACTION
+ *          under the LEGACY dispatch, but nothing moved that state between
+ *          elements: a species injected via `[REACTION_QUALITY]` upstream
+ *          reacted in place and never arrived downstream, and a warning
+ *          said so at open. This is the mirror that retires that warning.
+ *
+ * @par Provenance
+ *      Line for line, `routeLegacyHeat` (`HeatLegacy.cpp`) — the CSTR
+ *      mirror family A1b established: snapshot old state, accumulate
+ *      `q · c_old` into each downstream node, mix as
+ *      `(c_old·v_old + mass_in)/(v_old + v_in)` with the two-sided clamp,
+ *      then the `updateLinkQuality` link branches with the DW `q_in`
+ *      correction. Differences from the heat mirror, each deliberate:
+ *      - **No external-load pathway.** Species take no `[INFLOWS]`; their
+ *        only sources are initial state and reactions (L3's own note).
+ *        The `node_temp_vol_in` term has no analogue here.
+ *      - **No aging and no decay.** Reaction kinetics belong to the shared
+ *        integrator (`reactLegacyNodes/Links`), which runs in its own
+ *        stage; re-applying anything here would double-count, which is the
+ *        trap the L3 record names for LARD's stage 4/4b split.
+ *      - **No evaporation factor**, matching the age and heat mirrors
+ *        rather than the pollutant path. Recorded divergence: during
+ *        evaporation an MSX concentration will not up-concentrate. The
+ *        pollutant path's own evap factor was found CREATING mass at
+ *        draining nodes (KD1), so the omission is the safer side.
+ *
+ * @par Ordering
+ *      Runs beside the age and heat mirrors at the END of
+ *      `QualitySolver::execute` — after `reactLegacyNodes/Links`, so a
+ *      RATE species reacts against this step's pre-transport state and is
+ *      then advected (Lie split, the roadmap's lesson-13 convention). With
+ *      no reaction system configured this function returns before touching
+ *      anything, so pollutant-only models are bit-identical by
+ *      construction.
+ *
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md (R4b)
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_MSX_LEGACY_TRANSPORT_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_MSX_LEGACY_TRANSPORT_HPP
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Advect the MSX element state one routing step on the LEGACY CSTR path.
+/// No-op unless a reaction system with at least one species is configured.
+void routeLegacyMsx(SimulationContext& ctx, double dt);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_MSX_LEGACY_TRANSPORT_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionArdBinding.cpp b/src/engine/transport/components/ReactionModule/ReactionArdBinding.cpp
new file mode 100644
index 000000000..dd8c93325
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionArdBinding.cpp
@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionArdBinding.cpp
+ * @brief Phase E4/R6 body — Eulerian ARD engine reaction stage.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ReactionArdBinding.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "ReactionIntegrator.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+/// One workspace + gather blocks per thread of execution; the stage runs on
+/// the routing thread only, so a function-local static suffices (the R4
+/// BindingScratch pattern). Re-inited when the species count changes.
+struct ArdScratch {
+    RxWorkspace ws;
+    std::vector msx;     ///< [n_msx] gathered MSX block
+    std::vector pollut;  ///< [n_pollut] gathered pollutant block
+    int sized_species = -1;
+    int sized_pollut  = -1;
+    void ensure(const ReactionData& rx, int np) {
+        if (sized_species != rx.n_species()) {
+            ws.init(rx);
+            msx.assign(static_cast(rx.n_species()), 0.0);
+            sized_species = rx.n_species();
+        }
+        if (sized_pollut != np) {
+            pollut.assign(static_cast(np > 0 ? np : 1), 0.0);
+            sized_pollut = np;
+        }
+    }
+};
+
+ArdScratch& scratch() {
+    static ArdScratch s;
+    return s;
+}
+
+void containFailure(SimulationContext& ctx, const char* what, int index,
+                    const std::string& error) {
+    if (ctx.reactions.warned_react_failure) return;
+    ctx.reactions.warned_react_failure = true;
+    ctx.warnings.push_back(std::string("Reaction step failed at ARD ") +
+                           what + " index " + std::to_string(index) +
+                           " (element state left unchanged): " + error);
+}
+
+}  // namespace
+
+bool ardReactionsActive(const SimulationContext& ctx) {
+    return ctx.reactions.configured && ctx.reactions.compiled;
+}
+
+bool ardHasWallSpecies(const SimulationContext& ctx) {
+    for (const auto w : ctx.reactions.species_is_wall)
+        if (w != 0) return true;
+    return false;
+}
+
+void reactArdStage(SimulationContext& ctx, double dt, double* cell_phi,
+                   const double* cell_a, const double* cell_dx, int n_cells,
+                   double* node_mass, const double* node_vol, int n_nodes,
+                   int n_pollut, int ns_total, double min_store_vol,
+                   int temp_row) {
+    if (dt <= 0.0) return;
+
+    const auto unc = static_cast(n_cells);
+    const auto uns = static_cast(ns_total);
+
+    // ---- 1. Pollutant kdecay: exact exponential (closed form of the
+    //         first-order implicit RATE; plan E4 "kdecay-as-RATE"). Applied
+    //         to cell CONCENTRATIONS and store MASSES — both scale by the
+    //         same factor, so store concentration follows. E5b: the removed
+    //         mass books into the qual_routing_reacted ledger row (cells:
+    //         a·dx·Δconc; stores: Δmass), closing the continuity gap the
+    //         report would otherwise show as unexplained loss. ------------
+    for (int p = 0; p < n_pollut; ++p) {
+        const double k = ctx.pollutants.k_decay[static_cast(p)];
+        if (k == 0.0) continue;
+        const double f = std::exp(-k * dt);
+        const double loss_frac = 1.0 - f;
+        double removed = 0.0;
+        const auto row = static_cast(p) * unc;
+        for (int c = 0; c < n_cells; ++c) {
+            const auto uc = row + static_cast(c);
+            const auto ucc = static_cast(c);
+            if (cell_phi[uc] > 0.0)
+                removed += cell_a[ucc] * cell_dx[ucc] * cell_phi[uc] *
+                           loss_frac;
+            cell_phi[uc] *= f;
+            if (cell_phi[uc] < 0.0) cell_phi[uc] = 0.0;
+        }
+        for (int nd = 0; nd < n_nodes; ++nd) {
+            const auto ui =
+                static_cast(nd) * uns + static_cast(p);
+            if (node_mass[ui] > 0.0) removed += node_mass[ui] * loss_frac;
+            node_mass[ui] *= f;
+            if (node_mass[ui] < 0.0) node_mass[ui] = 0.0;
+        }
+        if (static_cast(p) <
+            ctx.mass_balance.qual_routing_reacted.size())
+            ctx.mass_balance.qual_routing_reacted[static_cast(p)] +=
+                removed;
+    }
+
+    // ---- 2. MSX species: per-cell pipe scope, per-store tank scope. -----
+    if (!ardReactionsActive(ctx)) return;
+    auto& rx = ctx.reactions;
+    const int nm = rx.n_species();
+    // A1a: ns_total may exceed np + nm by the reserved __WATER_AGE__ row
+    // (which reacts with nothing) — the MSX block still occupies rows
+    // [np, np + nm). The old equality guard would have SILENTLY skipped
+    // every reaction the moment the age row appeared (the lesson-14 shape:
+    // a consistency check about one layout blocking another).
+    if (nm == 0 || ns_total < n_pollut + nm) return;
+
+    auto& sc = scratch();
+    sc.ensure(rx, n_pollut);
+    double hydvar[static_cast(RxHydVar::COUNT_)] = {};
+
+    // Cells (pipe scope). HRT is a node concept — zero here, matching R4's
+    // link treatment; the fuller hydraulic-variable population is E5 work.
+    for (int c = 0; c < n_cells; ++c) {
+        const auto ucell = static_cast(c);
+        for (int m = 0; m < nm; ++m)
+            sc.msx[static_cast(m)] =
+                cell_phi[static_cast(n_pollut + m) * unc + ucell];
+        for (int p = 0; p < n_pollut; ++p)
+            sc.pollut[static_cast(p)] =
+                cell_phi[static_cast(p) * unc + ucell];
+        hydvar[static_cast(RxHydVar::HRT)] = 0.0;
+        // TEMP: the cell's own heat-transport temperature row when the mesh
+        // carries one, else the [REACTION_OPTIONS] TEMPERATURE constant.
+        hydvar[static_cast(RxHydVar::TEMP)] =
+            (temp_row >= 0)
+                ? cell_phi[static_cast(temp_row) * unc + ucell]
+                : rx.default_temp_c;
+
+        const auto rep = ReactionIntegrator::step(
+            rx, /*tank=*/false, dt, sc.msx.data(), hydvar, sc.ws,
+            (n_pollut > 0) ? sc.pollut.data() : nullptr);
+        if (rep.ok) {
+            for (int m = 0; m < nm; ++m)
+                cell_phi[static_cast(n_pollut + m) * unc + ucell] =
+                    sc.msx[static_cast(m)];
+        } else {
+            containFailure(ctx, "cell", c, rep.error);
+        }
+    }
+
+    // Node stores (tank scope): integrate CONCENTRATIONS, write back MASS.
+    for (int nd = 0; nd < n_nodes; ++nd) {
+        const auto und = static_cast(nd);
+        const double vol = node_vol[und];
+        if (vol <= min_store_vol) continue;  // no meaningful concentration
+        for (int m = 0; m < nm; ++m)
+            sc.msx[static_cast(m)] =
+                node_mass[und * uns + static_cast(n_pollut + m)] /
+                vol;
+        for (int p = 0; p < n_pollut; ++p)
+            sc.pollut[static_cast(p)] =
+                node_mass[und * uns + static_cast(p)] / vol;
+        hydvar[static_cast(RxHydVar::HRT)] =
+            (und < ctx.nodes.hrt.size()) ? ctx.nodes.hrt[und] : 0.0;
+        // TEMP: node stores carry temperature-volume (degC·ft³) on the
+        // temperature row, so concentration-form division recovers degC.
+        hydvar[static_cast(RxHydVar::TEMP)] =
+            (temp_row >= 0)
+                ? node_mass[und * uns + static_cast(temp_row)] /
+                      vol
+                : rx.default_temp_c;
+
+        const auto rep = ReactionIntegrator::step(
+            rx, /*tank=*/true, dt, sc.msx.data(), hydvar, sc.ws,
+            (n_pollut > 0) ? sc.pollut.data() : nullptr);
+        if (rep.ok) {
+            for (int m = 0; m < nm; ++m)
+                node_mass[und * uns + static_cast(n_pollut + m)] =
+                    sc.msx[static_cast(m)] * vol;
+        } else {
+            containFailure(ctx, "node store", nd, rep.error);
+        }
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionArdBinding.hpp b/src/engine/transport/components/ReactionModule/ReactionArdBinding.hpp
new file mode 100644
index 000000000..35c5b0cb4
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionArdBinding.hpp
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionArdBinding.hpp
+ * @brief Phase E4/R6 — reaction binding for the Eulerian ARD engine.
+ *
+ * @details One reaction stage per ROUTING step on the ARD mesh state,
+ *          Lie-split after the advection–dispersion subcycle (first-order
+ *          splitting, the documented decision of roadmap lesson 13: the
+ *          integrator substeps adaptively inside the stage, routing steps
+ *          are short relative to typical kinetics, and the projection error
+ *          dominates — revisit if the LEGACY-vs-ARD convergence gate says
+ *          otherwise):
+ *
+ *          1. **Pollutant kdecay as the exact exponential** on every cell
+ *             (concentration) and node store (mass) — the closed form of
+ *             the implicit first-order RATE the plan's E4 row names. This
+ *             runs whether or not a reactions component is configured,
+ *             retiring the E1 "kdecay not yet applied" warning.
+ *          2. **MSX species integrate per cell** (pipe scope) and **per
+ *             node store** (tank scope, HRT populated) via
+ *             ReactionIntegrator, with the element's pollutant
+ *             concentrations readable (PUSH_POLLUT). FORMULA sees
+ *             post-decay pollutants — the R4 ordering, kept identical so
+ *             the two bindings agree at the CSTR limit.
+ *
+ *          MSX species are TRANSPORTED on the mesh under this engine (R6):
+ *          the ARD state carries n_pollutants + n_msx species rows, so the
+ *          R4b element-local limitation does not apply here. WALL species
+ *          have no transport semantics yet — a model with WALL species
+ *          under EULERIAN_ARD falls back to LEGACY with a warning.
+ *
+ *          Failure containment matches R4: a failed integration leaves the
+ *          element's block unchanged and warns once per run with the
+ *          element kind/index and the integrator's remedy text.
+ *
+ * @see plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md §6 E4
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md §5 R6
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_REACTION_ARD_BINDING_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_REACTION_ARD_BINDING_HPP
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// True when the reactions component is active (configured + compiled) —
+/// the ARD engine's condition for carrying MSX species on the mesh.
+bool ardReactionsActive(const SimulationContext& ctx);
+
+/// True when any declared MSX species is WALL — unsupported under the ARD
+/// engine (no transport semantics for attached species yet); the engine
+/// falls back to LEGACY, whose R4 binding runs them element-locally.
+bool ardHasWallSpecies(const SimulationContext& ctx);
+
+/**
+ * @brief The E4 reaction stage over one routing step.
+ *
+ * @param cell_phi  ARD cell state, species-major [s * n_cells + c]; rows
+ *                  0..n_pollut-1 are pollutants, rows n_pollut.. are the
+ *                  MSX species in ReactionData order.
+ * @param cell_a    Cell areas (read-only; dry cells still react — their
+ *                  carried concentration evolves like LEGACY's, and holds
+ *                  negligible mass).
+ * @param cell_dx   Cell lengths (read-only; E5b — with cell_a they give the
+ *                  water volume each kdecay concentration change acts on,
+ *                  so the removed pollutant mass books into the
+ *                  qual_routing_reacted ledger row).
+ * @param node_mass Node-store species MASS [nd * ns_total + s].
+ * @param node_vol  Node-store water volume [nd].
+ * @param n_pollut  Pollutant row count (may be 0 — MSX-only model).
+ * @param ns_total  Total species rows (n_pollut + rx.n_species() when the
+ *                  component is active, else n_pollut).
+ * @param min_store_vol Below this volume a store has no meaningful
+ *                  concentration: MSX tank integration is skipped there
+ *                  (mass-form kdecay still applies).
+ */
+void reactArdStage(SimulationContext& ctx, double dt, double* cell_phi,
+                   const double* cell_a, const double* cell_dx, int n_cells,
+                   double* node_mass, const double* node_vol, int n_nodes,
+                   int n_pollut, int ns_total, double min_store_vol,
+                   int temp_row = -1);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_REACTION_ARD_BINDING_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionExpression.cpp b/src/engine/transport/components/ReactionModule/ReactionExpression.cpp
new file mode 100644
index 000000000..a302e567a
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionExpression.cpp
@@ -0,0 +1,532 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionExpression.cpp
+ * @brief Reaction expression compiler + Tier-1 evaluator — phase R2 body.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ReactionExpression.hpp"
+
+#include 
+#include 
+#include 
+
+namespace openswmm::transport {
+
+namespace {
+
+// ---------------------------------------------------------------------------
+// Lexer
+// ---------------------------------------------------------------------------
+
+enum class LexKind {
+    NUMBER, IDENT, OP, LPAREN, RPAREN, COMMA, END
+};
+
+struct Lexeme {
+    LexKind     kind = LexKind::END;
+    char        op   = 0;       ///< for OP: + - * / ^
+    double      num  = 0.0;
+    std::string ident;
+    int         col  = 0;       ///< 1-based start column
+};
+
+struct Lexer {
+    const std::string& s;
+    std::size_t i = 0;
+    explicit Lexer(const std::string& src) : s(src) {}
+
+    Lexeme next(std::string& err) {
+        while (i < s.size() &&
+               (s[i] == ' ' || s[i] == '\t')) ++i;
+        Lexeme lx;
+        lx.col = static_cast(i) + 1;
+        if (i >= s.size()) { lx.kind = LexKind::END; return lx; }
+        const char c = s[i];
+        if (std::isdigit(static_cast(c)) || c == '.') {
+            char* end = nullptr;
+            lx.num  = std::strtod(s.c_str() + i, &end);
+            lx.kind = LexKind::NUMBER;
+            i = static_cast(end - s.c_str());
+            return lx;
+        }
+        if (std::isalpha(static_cast(c)) || c == '_') {
+            std::size_t b = i;
+            while (i < s.size() &&
+                   (std::isalnum(static_cast(s[i])) ||
+                    s[i] == '_')) ++i;
+            lx.kind  = LexKind::IDENT;
+            lx.ident = s.substr(b, i - b);
+            return lx;
+        }
+        switch (c) {
+            case '+': case '-': case '*': case '/': case '^':
+                lx.kind = LexKind::OP; lx.op = c; ++i; return lx;
+            case '(': lx.kind = LexKind::LPAREN; ++i; return lx;
+            case ')': lx.kind = LexKind::RPAREN; ++i; return lx;
+            case ',': lx.kind = LexKind::COMMA;  ++i; return lx;
+            default:
+                err = std::string("unexpected character '") + c + "'";
+                return lx;
+        }
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Function table
+// ---------------------------------------------------------------------------
+
+struct FuncDef { const char* name; RxToken::Op op; int arity; };
+
+const FuncDef kFuncs[] = {
+    {"EXP",   RxToken::F_EXP,   1}, {"LOG",   RxToken::F_LOG,   1},
+    {"LOG10", RxToken::F_LOG10, 1}, {"SQRT",  RxToken::F_SQRT,  1},
+    {"ABS",   RxToken::F_ABS,   1}, {"SGN",   RxToken::F_SGN,   1},
+    {"STEP",  RxToken::F_STEP,  1}, {"SIN",   RxToken::F_SIN,   1},
+    {"COS",   RxToken::F_COS,   1}, {"TAN",   RxToken::F_TAN,   1},
+    {"MIN",   RxToken::F_MIN,   2}, {"MAX",   RxToken::F_MAX,   2},
+    {"POW",   RxToken::POW,     2},
+};
+
+std::string upper(std::string t) {
+    for (auto& ch : t)
+        ch = static_cast(std::toupper(static_cast(ch)));
+    return t;
+}
+
+const FuncDef* findFunc(const std::string& ident) {
+    const std::string u = upper(ident);
+    for (const auto& f : kFuncs)
+        if (u == f.name) return &f;
+    return nullptr;
+}
+
+/// Hydraulic variable names + one-line descriptions (E-C1: also served to
+/// the GUI through reactionHydVarInfo — one copy of the truth). Meanings and
+/// units per ReactionTokens.hpp.
+const char* kHydVarNames[] = {"D", "Q", "U", "RE", "US", "FF", "AV",
+                              "HRT", "DT", "TEMP"};
+const char* kHydVarDescs[] = {
+    "Depth (ft)",
+    "Flow (cfs)",
+    "Velocity (ft/s)",
+    "Reynolds number",
+    "Shear velocity (ft/s)",
+    "Darcy-Weisbach friction factor",
+    "Wetted surface area per volume (1/ft)",
+    "Hydraulic residence time (s)",
+    "Reaction step (s)",
+    "Water temperature (degC; TEMPERATURE option when heat is off)",
+};
+static_assert(sizeof(kHydVarNames) / sizeof(kHydVarNames[0]) ==
+                  static_cast(RxHydVar::COUNT_),
+              "hydraulic-variable name table out of sync with RxHydVar");
+static_assert(sizeof(kHydVarDescs) / sizeof(kHydVarDescs[0]) ==
+                  static_cast(RxHydVar::COUNT_),
+              "hydraulic-variable description table out of sync with RxHydVar");
+
+/// Hydraulic variable lookup (case-insensitive — "Re" and "RE" both work).
+int findHydVar(const std::string& ident) {
+    const std::string u = upper(ident);
+    for (int i = 0; i < static_cast(RxHydVar::COUNT_); ++i)
+        if (u == kHydVarNames[i]) return i;
+    return -1;
+}
+
+// ---------------------------------------------------------------------------
+// Shunting-yard
+// ---------------------------------------------------------------------------
+
+struct OpEntry {
+    RxToken::Op op;
+    int  prec;
+    bool right_assoc;
+    int  col;
+    bool is_func;
+    int  arity;        ///< funcs
+    const char* name;  ///< funcs — for the arity diagnostic (D-R9)
+    bool is_paren;     ///< '(' marker
+    int  commas;       ///< parens — argument-separator count (D-R9)
+};
+
+int precOf(char op) {
+    switch (op) {
+        case '+': case '-': return 1;
+        case '*': case '/': return 2;
+        case '^':           return 3;
+        default:            return 0;
+    }
+}
+
+RxToken::Op binOf(char op) {
+    switch (op) {
+        case '+': return RxToken::ADD;
+        case '-': return RxToken::SUB;
+        case '*': return RxToken::MUL;
+        case '/': return RxToken::DIV;
+        default:  return RxToken::POW;
+    }
+}
+
+}  // namespace
+
+std::string compileReactionExpression(const std::string& src,
+                                      const RxSymbols& symbols,
+                                      std::vector& pool,
+                                      RxExprSpan& out,
+                                      int& error_col) {
+    out = RxExprSpan{static_cast(pool.size()), 0};
+    error_col = 0;
+
+    std::vector  output;
+    std::vector  ops;
+    Lexer lex(src);
+
+    auto fail = [&](const std::string& msg, int col) {
+        error_col = col;
+        return msg;
+    };
+
+    auto popOpToOutput = [&](const OpEntry& e) {
+        RxToken t;
+        t.op = e.op;
+        output.push_back(t);
+    };
+
+    bool expect_operand = true;    // start of expression / after operator
+    int  depth_guard    = 0;
+
+    for (;;) {
+        std::string lex_err;
+        Lexeme lx = lex.next(lex_err);
+        if (!lex_err.empty()) return fail(lex_err, lx.col);
+        if (lx.kind == LexKind::END) break;
+
+        switch (lx.kind) {
+            case LexKind::NUMBER: {
+                if (!expect_operand)
+                    return fail("unexpected number", lx.col);
+                RxToken t;
+                t.op = RxToken::PUSH_NUM;
+                t.value = lx.num;
+                output.push_back(t);
+                expect_operand = false;
+                break;
+            }
+            case LexKind::IDENT: {
+                if (!expect_operand)
+                    return fail("unexpected identifier '" + lx.ident + "'",
+                                lx.col);
+                if (const FuncDef* f = findFunc(lx.ident)) {
+                    // Must be followed by '('.
+                    std::string e2;
+                    Lexeme la = lex.next(e2);
+                    if (!e2.empty()) return fail(e2, la.col);
+                    if (la.kind != LexKind::LPAREN)
+                        return fail("function '" + lx.ident +
+                                    "' needs '('", lx.col);
+                    OpEntry fe{};
+                    fe.op = f->op; fe.is_func = true; fe.arity = f->arity;
+                    fe.name = f->name;
+                    fe.col = lx.col;
+                    ops.push_back(fe);
+                    OpEntry pe{};
+                    pe.is_paren = true; pe.col = la.col;
+                    ops.push_back(pe);
+                    ++depth_guard;
+                    expect_operand = true;
+                    break;
+                }
+                RxToken t;
+                int idx = -1;
+                // Resolution order: species, coefficient, term (forward-only),
+                // hydraulic variable.
+                if (symbols.species) {
+                    for (std::size_t k = 0; k < symbols.species->size(); ++k)
+                        if ((*symbols.species)[k] == lx.ident) {
+                            idx = static_cast(k);
+                            t.op = RxToken::PUSH_SPECIES;
+                            break;
+                        }
+                }
+                if (idx < 0 && symbols.coefs) {
+                    for (std::size_t k = 0; k < symbols.coefs->size(); ++k)
+                        if ((*symbols.coefs)[k] == lx.ident) {
+                            idx = static_cast(k);
+                            t.op = RxToken::PUSH_COEF;
+                            break;
+                        }
+                }
+                if (idx < 0 && symbols.terms) {
+                    for (std::size_t k = 0; k < symbols.terms->size(); ++k)
+                        if ((*symbols.terms)[k] == lx.ident) {
+                            if (static_cast(k) >= symbols.max_term)
+                                return fail("term '" + lx.ident +
+                                            "' references later term — term "
+                                            "references are forward-only",
+                                            lx.col);
+                            idx = static_cast(k);
+                            t.op = RxToken::PUSH_TERM;
+                            break;
+                        }
+                }
+                if (idx < 0 && symbols.pollutants) {
+                    for (std::size_t k = 0; k < symbols.pollutants->size(); ++k)
+                        if ((*symbols.pollutants)[k] == lx.ident) {
+                            idx = static_cast(k);
+                            t.op = RxToken::PUSH_POLLUT;
+                            break;
+                        }
+                }
+                if (idx < 0) {
+                    const int hv = findHydVar(lx.ident);
+                    if (hv >= 0) { idx = hv; t.op = RxToken::PUSH_HYDVAR; }
+                }
+                if (idx < 0)
+                    return fail("undefined identifier '" + lx.ident + "'",
+                                lx.col);
+                t.idx = idx;
+                output.push_back(t);
+                expect_operand = false;
+                break;
+            }
+            case LexKind::OP: {
+                if (expect_operand) {
+                    if (lx.op == '-') {           // unary minus
+                        // D-R8 (decided 2026-08-16): unary minus binds BELOW
+                        // '^' — Python/Fortran/MATLAB convention, -2^2 = -4.
+                        // Precedence 2 (== '*'): '^' stacks above NEG
+                        // (2 < 3 ⇒ no pop), while '*' and '+'/'-' pop it
+                        // first — every case then matches sympy, which the
+                        // R5 authoring path round-trips through. The R2
+                        // validator proved legacy mathexpr.c cannot
+                        // arbitrate (returns 0 for both spellings).
+                        OpEntry e{};
+                        e.op = RxToken::NEG; e.prec = 2; e.right_assoc = true;
+                        e.col = lx.col;
+                        ops.push_back(e);
+                        break;
+                    }
+                    if (lx.op == '+') break;      // unary plus: no-op
+                    return fail(std::string("unexpected operator '") +
+                                lx.op + "'", lx.col);
+                }
+                const int  p  = precOf(lx.op);
+                const bool ra = (lx.op == '^');
+                while (!ops.empty() && !ops.back().is_paren &&
+                       !ops.back().is_func &&
+                       (ops.back().prec > p ||
+                        (ops.back().prec == p && !ra))) {
+                    popOpToOutput(ops.back());
+                    ops.pop_back();
+                }
+                OpEntry e{};
+                e.op = binOf(lx.op); e.prec = p; e.right_assoc = ra;
+                e.col = lx.col;
+                ops.push_back(e);
+                expect_operand = true;
+                break;
+            }
+            case LexKind::LPAREN: {
+                if (!expect_operand)
+                    return fail("unexpected '('", lx.col);
+                OpEntry e{};
+                e.is_paren = true; e.col = lx.col;
+                ops.push_back(e);
+                ++depth_guard;
+                if (depth_guard > kRxMaxStackDepth)
+                    return fail("expression too deep", lx.col);
+                break;
+            }
+            case LexKind::RPAREN: {
+                if (expect_operand)
+                    return fail("unexpected ')'", lx.col);
+                while (!ops.empty() && !ops.back().is_paren) {
+                    popOpToOutput(ops.back());
+                    ops.pop_back();
+                }
+                if (ops.empty())
+                    return fail("unbalanced ')'", lx.col);
+                const int commas = ops.back().commas;
+                ops.pop_back();               // the '('
+                --depth_guard;
+                // Function application?
+                if (!ops.empty() && ops.back().is_func) {
+                    // D-R9: name the function and its arity at the call
+                    // site, instead of the generic RPN-discipline
+                    // "malformed expression" at col 1.
+                    const int argc = commas + 1;
+                    if (argc != ops.back().arity)
+                        return fail(
+                            std::string("function '") + ops.back().name +
+                                "' expects " +
+                                std::to_string(ops.back().arity) +
+                                (ops.back().arity == 1 ? " argument"
+                                                       : " arguments") +
+                                ", got " + std::to_string(argc),
+                            ops.back().col);
+                    popOpToOutput(ops.back());
+                    ops.pop_back();
+                }
+                break;
+            }
+            case LexKind::COMMA: {
+                if (expect_operand)
+                    return fail("unexpected ','", lx.col);
+                while (!ops.empty() && !ops.back().is_paren) {
+                    popOpToOutput(ops.back());
+                    ops.pop_back();
+                }
+                if (ops.empty() || ops.size() < 2 ||
+                    !ops[ops.size() - 2].is_func)
+                    return fail("',' outside a function call", lx.col);
+                ++ops.back().commas;          // the paren frame (D-R9)
+                expect_operand = true;
+                break;
+            }
+            case LexKind::END: break;
+        }
+    }
+
+    if (expect_operand)
+        return fail("expression ends with an operator",
+                    static_cast(src.size()) + 1);
+    while (!ops.empty()) {
+        if (ops.back().is_paren)
+            return fail("unbalanced '('", ops.back().col);
+        popOpToOutput(ops.back());
+        ops.pop_back();
+    }
+    if (output.empty())
+        return fail("empty expression", 1);
+
+    // Verify stack discipline + final depth 1, and bound the depth so the
+    // evaluator's fixed stack is provably sufficient.
+    int depth = 0, max_depth = 0;
+    for (const auto& t : output) {
+        switch (t.op) {
+            case RxToken::PUSH_NUM: case RxToken::PUSH_SPECIES:
+            case RxToken::PUSH_COEF: case RxToken::PUSH_TERM:
+            case RxToken::PUSH_HYDVAR: case RxToken::PUSH_POLLUT:
+                ++depth; break;
+            case RxToken::NEG: case RxToken::F_EXP: case RxToken::F_LOG:
+            case RxToken::F_LOG10: case RxToken::F_SQRT: case RxToken::F_ABS:
+            case RxToken::F_SGN: case RxToken::F_STEP: case RxToken::F_SIN:
+            case RxToken::F_COS: case RxToken::F_TAN:
+                if (depth < 1) return fail("malformed expression", 1);
+                break;
+            default:                                     // binary
+                if (depth < 2) return fail("malformed expression", 1);
+                --depth; break;
+        }
+        if (depth > max_depth) max_depth = depth;
+    }
+    if (depth != 1) return fail("malformed expression", 1);
+    if (max_depth > kRxMaxStackDepth)
+        return fail("expression too deep", 1);
+
+    out.begin = static_cast(pool.size());
+    out.len   = static_cast(output.size());
+    pool.insert(pool.end(), output.begin(), output.end());
+    return {};
+}
+
+// ---------------------------------------------------------------------------
+// Tier-1 evaluator — fixed stack, pre-resolved indices, allocation-free.
+// ---------------------------------------------------------------------------
+
+double evalReactionExpression(const std::vector& pool,
+                              const RxExprSpan& span,
+                              const RxEvalEnv& env) noexcept {
+    // D-R9: len == 0 is the documented "no expression" encoding — it must
+    // be safe regardless of caller discipline (the R2 validator caught the
+    // uninitialized-read alternative). Callers may ALSO skip empty spans;
+    // this branch is the contract, their skip is the optimization.
+    if (span.len <= 0) return 0.0;
+    double st[kRxMaxStackDepth];
+    int sp = 0;
+    const RxToken* t   = pool.data() + span.begin;
+    const RxToken* end = t + span.len;
+    for (; t != end; ++t) {
+        switch (t->op) {
+            case RxToken::PUSH_NUM:     st[sp++] = t->value; break;
+            case RxToken::PUSH_SPECIES: st[sp++] = env.species[t->idx]; break;
+            case RxToken::PUSH_COEF:    st[sp++] = env.coefs[t->idx]; break;
+            case RxToken::PUSH_TERM:    st[sp++] = env.terms[t->idx]; break;
+            case RxToken::PUSH_HYDVAR:  st[sp++] = env.hydvar[t->idx]; break;
+            case RxToken::PUSH_POLLUT:  st[sp++] = env.pollutants[t->idx]; break;
+            case RxToken::ADD: --sp; st[sp - 1] += st[sp]; break;
+            case RxToken::SUB: --sp; st[sp - 1] -= st[sp]; break;
+            case RxToken::MUL: --sp; st[sp - 1] *= st[sp]; break;
+            case RxToken::DIV: --sp; st[sp - 1] /= st[sp]; break;
+            case RxToken::POW: --sp; st[sp - 1] = std::pow(st[sp - 1], st[sp]); break;
+            case RxToken::NEG: st[sp - 1] = -st[sp - 1]; break;
+            case RxToken::F_EXP:   st[sp - 1] = std::exp(st[sp - 1]); break;
+            case RxToken::F_LOG:   st[sp - 1] = std::log(st[sp - 1]); break;
+            case RxToken::F_LOG10: st[sp - 1] = std::log10(st[sp - 1]); break;
+            case RxToken::F_SQRT:  st[sp - 1] = std::sqrt(st[sp - 1]); break;
+            case RxToken::F_ABS:   st[sp - 1] = std::fabs(st[sp - 1]); break;
+            case RxToken::F_SGN:
+                st[sp - 1] = (st[sp - 1] > 0.0) ? 1.0
+                             : (st[sp - 1] < 0.0) ? -1.0 : 0.0;
+                break;
+            case RxToken::F_STEP:  st[sp - 1] = (st[sp - 1] > 0.0) ? 1.0 : 0.0; break;
+            case RxToken::F_SIN:   st[sp - 1] = std::sin(st[sp - 1]); break;
+            case RxToken::F_COS:   st[sp - 1] = std::cos(st[sp - 1]); break;
+            case RxToken::F_TAN:   st[sp - 1] = std::tan(st[sp - 1]); break;
+            case RxToken::F_MIN:
+                --sp; st[sp - 1] = (st[sp - 1] < st[sp]) ? st[sp - 1] : st[sp];
+                break;
+            case RxToken::F_MAX:
+                --sp; st[sp - 1] = (st[sp - 1] > st[sp]) ? st[sp - 1] : st[sp];
+                break;
+        }
+    }
+    return st[0];
+}
+
+// ---------------------------------------------------------------------------
+// Vocabulary discovery (E-C1) — the completer/highlighter contract.
+// ---------------------------------------------------------------------------
+
+int reactionFunctionCount() {
+    return static_cast(sizeof(kFuncs) / sizeof(kFuncs[0]));
+}
+
+bool reactionFunctionInfo(int idx, const char** name, int* arity) {
+    if (idx < 0 || idx >= reactionFunctionCount()) return false;
+    if (name)  *name  = kFuncs[idx].name;
+    if (arity) *arity = kFuncs[idx].arity;
+    return true;
+}
+
+int reactionHydVarCount() {
+    return static_cast(RxHydVar::COUNT_);
+}
+
+bool reactionHydVarInfo(int idx, const char** name, const char** description) {
+    if (idx < 0 || idx >= reactionHydVarCount()) return false;
+    if (name)        *name        = kHydVarNames[idx];
+    if (description) *description = kHydVarDescs[idx];
+    return true;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionExpression.hpp b/src/engine/transport/components/ReactionModule/ReactionExpression.hpp
new file mode 100644
index 000000000..e3fe3fb66
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionExpression.hpp
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionExpression.hpp
+ * @brief Reaction expression compiler + Tier-1 evaluator (phase R2).
+ *
+ * @details Shunting-yard compiler from the MSX-convention DSL to a FLAT
+ *          token pool (LARD plan §16 D-L3 / reactions plan D-R2 Tier 1):
+ *          all compiled expressions share one contiguous
+ *          `std::vector`; each expression is a (begin, len) span.
+ *          Operands carry PRE-RESOLVED indices (species slot, coefficient
+ *          slot, term slot, hydraulic-variable code) so evaluation is a
+ *          single allocation-free pass over the span with a fixed-depth
+ *          value stack — no name lookups, no std::string, no heap.
+ *
+ *          Same shunting-yard family as quality/Treatment.cpp (D-R1: one
+ *          compiler approach, two front doors); actual TU-level
+ *          consolidation of the two VMs is the PROCESS_MODULARIZATION §10
+ *          decision and deliberately NOT forced here.
+ *
+ *          Grammar: numbers; identifiers (species | coefficient | term |
+ *          hydraulic variable, resolved in that order); + - * / ^ with
+ *          standard precedence, right-assoc ^; unary minus; parentheses;
+ *          functions EXP LOG LOG10 SQRT ABS SGN STEP SIN COS TAN (unary),
+ *          MIN MAX POW (binary, comma-separated). Term references are
+ *          FORWARD-ONLY (a term may reference only earlier terms), so term
+ *          evaluation is a simple in-order sweep with no cycle machinery.
+ *
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md §3.2, §5 R2
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_REACTION_EXPRESSION_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_REACTION_EXPRESSION_HPP
+
+#include 
+#include 
+
+#include "../../../data/ReactionTokens.hpp"
+
+namespace openswmm::transport {
+
+using openswmm::RxToken;
+using openswmm::RxExprSpan;
+using openswmm::RxHydVar;
+using openswmm::kRxMaxStackDepth;
+
+/// Name resolution offered to the compiler (pre-resolved at compile time —
+/// the evaluator never sees names).
+struct RxSymbols {
+    const std::vector* species = nullptr;  ///< local slots
+    const std::vector* coefs   = nullptr;
+    const std::vector* terms   = nullptr;  ///< only [0, max_term) resolvable
+    /// R4: pollutant names, resolved AFTER terms and BEFORE hydraulic
+    /// variables (a pollutant named "D" shadows the depth variable —
+    /// user-defined beats builtin; documented in the DSL reference).
+    /// Pollutants are READ-ONLY in expressions.
+    const std::vector* pollutants = nullptr;
+    int max_term = 0;   ///< forward-only rule: terms below this index only
+};
+
+/// Evaluation environment: pre-gathered pointers, no lookups.
+struct RxEvalEnv {
+    const double* species = nullptr;  ///< local species concentrations
+    const double* coefs   = nullptr;  ///< coefficient values
+    const double* terms   = nullptr;  ///< term values (evaluated in-order)
+    const double* hydvar  = nullptr;  ///< RxHydVar::COUNT_ entries
+    const double* pollutants = nullptr;  ///< element pollutant conc (R4, read-only)
+};
+
+/**
+ * @brief Compile `src` into the shared pool.
+ * @param error_col [out] 1-based column of the offending token on failure.
+ * @return empty on success, else the diagnostic ("undefined identifier
+ *         'x'", "expression too deep", "term 'T' references later term", …).
+ */
+std::string compileReactionExpression(const std::string& src,
+                                      const RxSymbols& symbols,
+                                      std::vector& pool,
+                                      RxExprSpan& out,
+                                      int& error_col);
+
+// ---------------------------------------------------------------------------
+// Vocabulary discovery (E-C1) — served from the compiler's OWN tables so the
+// GUI completer/highlighter (swmm_reaction_hydvar_* / swmm_reaction_
+// function_*) cannot drift from what actually compiles. Returned pointers
+// are static storage.
+// ---------------------------------------------------------------------------
+
+/// Number of built-in functions.
+int reactionFunctionCount();
+/// Name + arity of function @p idx; false when out of range.
+bool reactionFunctionInfo(int idx, const char** name, int* arity);
+/// Number of built-in hydraulic variables.
+int reactionHydVarCount();
+/// Name + one-line description of hydraulic variable @p idx.
+bool reactionHydVarInfo(int idx, const char** name, const char** description);
+
+/// Tier-1 evaluation: one pass, fixed-depth stack, allocation-free.
+double evalReactionExpression(const std::vector& pool,
+                              const RxExprSpan& span,
+                              const RxEvalEnv& env) noexcept;
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_REACTION_EXPRESSION_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionIntegrator.cpp b/src/engine/transport/components/ReactionModule/ReactionIntegrator.cpp
new file mode 100644
index 000000000..ec0fe0bd6
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionIntegrator.cpp
@@ -0,0 +1,693 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionIntegrator.cpp
+ * @brief Reaction kinetics integration — phase R3 body.
+ *
+ * @details Solver notes:
+ *          - EUL: single explicit Euler step over dt (MSX EUL semantics).
+ *          - RK5: Cash–Karp embedded 4(5) with adaptive substepping
+ *            controlled by the per-species atol/rtol weighted RMS norm.
+ *          - ROS2: 2-stage L-stable Rosenbrock (γ = 1 − 1/√2) with FD
+ *            Jacobian, adaptive by step-doubling comparison.
+ *          - BDF2: fixed-order BDF2 with Newton (+ dense LU), backward-
+ *            Euler startup step, adaptive by halving on Newton failure —
+ *            the D-R7-amendment stiff workhorse.
+ *          Substep floor guards against pathological kinetics; hitting it
+ *          is a HARD failure (report.error), never a silent inaccuracy.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ReactionIntegrator.hpp"
+
+#include 
+#include 
+
+#include "ReactionExpression.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr int    kMaxSubsteps    = 100000;
+constexpr int    kNewtonMax      = 50;
+constexpr double kMinStepFrac    = 1.0e-8;   ///< dt_sub floor = dt * frac
+constexpr double kFdEps          = 1.0e-7;
+/// Accepted substeps a cached FD Jacobian may serve before being re-derived.
+/// Bounds how far y can drift from the point J was taken at; rejections and
+/// Newton failures invalidate it earlier.
+constexpr int    kJacMaxAge      = 20;
+
+double unitFactor(ReactionRateUnits u) {
+    switch (u) {
+        case ReactionRateUnits::SEC: return 1.0;
+        case ReactionRateUnits::MIN: return 1.0 / 60.0;
+        case ReactionRateUnits::HR:  return 1.0 / 3600.0;
+        default:                     return 1.0 / 86400.0;
+    }
+}
+
+/// Evaluate all terms (forward-only order) for the current species state.
+void evalTerms(const ReactionData& rx, const double* species,
+               const double* hydvar, const double* pollut,
+               std::vector& terms) {
+    RxEvalEnv env{species, rx.coef_value.data(), terms.data(), hydvar, pollut};
+    for (std::size_t i = 0; i < rx.term_expr.size(); ++i)
+        terms[i] = evalReactionExpression(rx.token_pool, rx.term_expr[i], env);
+}
+
+/// Rates (1/s) for the RATE subset listed in `idx`, at state `species`.
+void evalRates(const ReactionData& rx, bool tank, const double* species,
+               const double* hydvar, const double* pollut,
+               std::vector& terms,
+               const std::vector& idx, double factor, double* out) {
+    evalTerms(rx, species, hydvar, pollut, terms);
+    RxEvalEnv env{species, rx.coef_value.data(), terms.data(), hydvar, pollut};
+    const auto& spans = tank ? rx.tank_expr : rx.pipe_expr;
+    for (std::size_t k = 0; k < idx.size(); ++k)
+        out[k] = factor *
+                 evalReactionExpression(rx.token_pool,
+                                        spans[static_cast(idx[k])],
+                                        env);
+}
+
+/// Weighted RMS error norm against per-species atol/rtol. `idx`/`count`
+/// describe the ACTIVE GROUP (group-local y/e views) — under COUPLING NONE
+/// the group is a single species, and iterating the full RATE set here
+/// would read past the group-local arrays.
+double errNorm(const ReactionData& rx, const int* idx, std::size_t count,
+               const double* y, const double* e) {
+    if (count == 0) return 0.0;
+    double s = 0.0;
+    for (std::size_t k = 0; k < count; ++k) {
+        const auto us = static_cast(idx[k]);
+        const double atol = (rx.species_atol[us] > 0.0) ? rx.species_atol[us]
+                                                        : rx.atol;
+        const double rtol = (rx.species_rtol[us] > 0.0) ? rx.species_rtol[us]
+                                                        : rx.rtol;
+        const double w = atol + rtol * std::fabs(y[k]);
+        const double r = e[k] / w;
+        s += r * r;
+    }
+    return std::sqrt(s / static_cast(count));
+}
+
+bool finiteAll(const double* v, std::size_t n) {
+    for (std::size_t i = 0; i < n; ++i)
+        if (!std::isfinite(v[i])) return false;
+    return true;
+}
+
+// ---------------------------------------------------------------------------
+// Dense LU (partial pivoting) on n×n scratch — n is small (species count).
+// ---------------------------------------------------------------------------
+
+bool luFactor(std::vector& a, std::vector& piv, int n) {
+    for (int i = 0; i < n; ++i) piv[static_cast(i)] = i;
+    for (int c = 0; c < n; ++c) {
+        int p = c;
+        double best = std::fabs(a[static_cast(c * n + c)]);
+        for (int r = c + 1; r < n; ++r) {
+            const double v = std::fabs(a[static_cast(r * n + c)]);
+            if (v > best) { best = v; p = r; }
+        }
+        if (best < 1.0e-300) return false;
+        if (p != c) {
+            for (int k = 0; k < n; ++k)
+                std::swap(a[static_cast(c * n + k)],
+                          a[static_cast(p * n + k)]);
+            std::swap(piv[static_cast(c)],
+                      piv[static_cast(p)]);
+        }
+        const double d = a[static_cast(c * n + c)];
+        for (int r = c + 1; r < n; ++r) {
+            const double m = a[static_cast(r * n + c)] / d;
+            a[static_cast(r * n + c)] = m;
+            for (int k = c + 1; k < n; ++k)
+                a[static_cast(r * n + k)] -=
+                    m * a[static_cast(c * n + k)];
+        }
+    }
+    return true;
+}
+
+void luSolve(const std::vector& a, const std::vector& piv,
+             int n, const double* b, double* x) {
+    for (int i = 0; i < n; ++i)
+        x[i] = b[piv[static_cast(i)]];
+    for (int i = 0; i < n; ++i)
+        for (int k = 0; k < i; ++k)
+            x[i] -= a[static_cast(i * n + k)] * x[k];
+    for (int i = n - 1; i >= 0; --i) {
+        for (int k = i + 1; k < n; ++k)
+            x[i] -= a[static_cast(i * n + k)] * x[k];
+        x[i] /= a[static_cast(i * n + i)];
+    }
+}
+
+}  // namespace
+
+// ===========================================================================
+// Workspace
+// ===========================================================================
+
+void RxWorkspace::init(const ReactionData& rx) {
+    n_ = rx.n_species();
+    const auto un = static_cast(n_);
+    terms_.assign(rx.term_expr.size(), 0.0);
+    y_.assign(un, 0.0);   y0_.assign(un, 0.0);  ytmp_.assign(un, 0.0);
+    rates_.assign(un, 0.0); err_.assign(un, 0.0);
+    k1_.assign(un, 0.0); k2_.assign(un, 0.0); k3_.assign(un, 0.0);
+    k4_.assign(un, 0.0); k5_.assign(un, 0.0); k6_.assign(un, 0.0);
+    jac_.assign(un * un, 0.0); lu_.assign(un * un, 0.0);
+    piv_.assign(un, 0);
+    res_.assign(un, 0.0); res2_.assign(un, 0.0); dy_.assign(un, 0.0);
+    grp_out_.assign(un, 0.0);
+
+    rate_idx_.clear(); equil_idx_.clear(); formula_idx_.clear();
+    // Scope-independent classification is not possible (pipe vs tank forms
+    // may differ per species); classified per call in step(). Vectors are
+    // reserved here so step() never allocates.
+    rate_idx_.reserve(un); equil_idx_.reserve(un); formula_idx_.reserve(un);
+}
+
+// ===========================================================================
+// step
+// ===========================================================================
+
+RxStepReport ReactionIntegrator::step(const ReactionData& rx, bool tank,
+                                      double dt, double* species,
+                                      double* hydvar, RxWorkspace& ws,
+                                      const double* pollutants) {
+    RxStepReport rep;
+    const int n = rx.n_species();
+    if (!rx.compiled || n == 0 || dt <= 0.0) return rep;
+
+    hydvar[static_cast(RxHydVar::DT)] = dt;
+    const double factor = unitFactor(rx.rate_units);
+    const auto& forms = tank ? rx.tank_form : rx.pipe_form;
+
+    // Classify species for this scope (no allocation — reserved in init).
+    ws.rate_idx_.clear(); ws.equil_idx_.clear(); ws.formula_idx_.clear();
+    for (int s = 0; s < n; ++s) {
+        switch (forms[static_cast(s)]) {
+            case ReactionExprForm::RATE:    ws.rate_idx_.push_back(s); break;
+            case ReactionExprForm::EQUIL:   ws.equil_idx_.push_back(s); break;
+            case ReactionExprForm::FORMULA: ws.formula_idx_.push_back(s); break;
+            default: break;
+        }
+    }
+
+    // Build and factor I - scale*J into ws.lu_, reusing the existing
+    // factorization when both the Jacobian and `scale` are unchanged. A
+    // lambda rather than a free function: the workspace scratch is private
+    // to RxWorkspace, and step() is its friend.
+    auto factorIterationMatrix = [&ws](int nn, double scale) -> bool {
+        if (ws.lu_valid_ && ws.lu_scale_ == scale) return true;
+        for (int r = 0; r < nn; ++r)
+            for (int c = 0; c < nn; ++c)
+                ws.lu_[static_cast(r * nn + c)] =
+                    ((r == c) ? 1.0 : 0.0) -
+                    scale * ws.jac_[static_cast(r * nn + c)];
+        if (!luFactor(ws.lu_, ws.piv_, nn)) { ws.lu_valid_ = false; return false; }
+        ws.lu_valid_ = true;
+        ws.lu_scale_ = scale;
+        return true;
+    };
+
+    // ---- 1. RATE integration -------------------------------------------
+    const auto& ridx = ws.rate_idx_;
+    const std::size_t nr = ridx.size();
+    if (nr > 0) {
+        const bool coupled = (rx.coupling == ReactionCoupling::FULL) || nr == 1;
+        // COUPLING NONE with nr > 1: integrate one species at a time with
+        // the others frozen (MSX semantics). Realized by running the same
+        // machinery once per species with a 1-entry index view — but to
+        // stay allocation-free we freeze OTHER rate species inside f by
+        // restoring them after each evaluation; start-of-step snapshot:
+        for (int s2 = 0; s2 < n; ++s2)
+            ws.y0_[static_cast(s2)] = species[s2];
+        auto freeze_others = [&](std::size_t active) {
+            if (coupled) return;
+            for (std::size_t k = 0; k < nr; ++k)
+                if (k != active)
+                    species[ridx[k]] = ws.y0_[static_cast(ridx[k])];
+        };
+        // Each group's result is STAGED here, not written straight back into
+        // `species`: under COUPLING NONE the next group's freeze_others()
+        // restores every other species from the start-of-step snapshot, which
+        // would otherwise wipe the group just finished (leaving all but the
+        // last species unintegrated). Published once, after every group.
+        for (std::size_t k = 0; k < nr; ++k)
+            ws.grp_out_[static_cast(ridx[k])] =
+                ws.y0_[static_cast(ridx[k])];
+
+        const std::size_t groups = coupled ? 1 : nr;
+        for (std::size_t g = 0; g < groups && rep.ok; ++g) {
+            // Active index set for this group.
+            const std::size_t gb = coupled ? 0 : g;
+            const std::size_t gn = coupled ? nr : 1;
+
+            // The cache is keyed to this group's state and index view.
+            ws.jac_valid_ = false;
+            ws.lu_valid_  = false;
+            double t = 0.0;
+            double h = dt;
+            double h_prev = 0.0;          ///< last ACCEPTED step (BDF2 history)
+            const double h_min = dt * kMinStepFrac;
+            int guard = 0;
+
+            auto fg = [&](const double* y, double* out) {
+                // y/out are the group view; map through the full machinery.
+                for (std::size_t k = 0; k < gn; ++k)
+                    ws.ytmp_[k] = y[k];
+                for (std::size_t k = 0; k < gn; ++k)
+                    species[ridx[gb + k]] = ws.ytmp_[k];
+                freeze_others(coupled ? static_cast(-1) : gb);
+                evalRates(rx, tank, species, hydvar, pollutants, ws.terms_, ridx, factor,
+                          ws.rates_.data());
+                for (std::size_t k = 0; k < gn; ++k)
+                    out[k] = ws.rates_[gb + k];
+            };
+
+            // Current group state.
+            for (std::size_t k = 0; k < gn; ++k)
+                ws.y_[k] = species[ridx[gb + k]];
+
+            while (t < dt && rep.ok) {
+                if (++guard > kMaxSubsteps) {
+                    rep.ok = false;
+                    // Name the remedy. RK5 is the default and is
+                    // stability-limited at roughly lambda_fast*dt/3.3
+                    // substeps, so this is the cap an explicit solver hits
+                    // on stiff kinetics — the one case where the default is
+                    // the wrong choice, and the user cannot know that from
+                    // "exceeded the substep cap" alone.
+                    rep.error =
+                        rx.solver == ReactionSolverKind::RK5 ||
+                        rx.solver == ReactionSolverKind::EUL
+                        ? "reaction step exceeded the substep cap: the "
+                          "explicit solver is resolving kinetics too stiff "
+                          "for it. Set [REACTION_OPTIONS] SOLVER to ROS2 or "
+                          "BDF2, or declare the fast species EQUIL."
+                        : "reaction step exceeded the substep cap "
+                          "(stiffness beyond the solver — see the D-R7 "
+                          "escape hatch)";
+                    break;
+                }
+                if (h < h_min) {
+                    rep.ok = false;
+                    rep.error = "reaction step size collapsed below the "
+                                "floor (stiffness beyond the solver — see "
+                                "D-R7 escape hatch)";
+                    break;
+                }
+                if (t + h > dt) h = dt - t;
+                bool accepted = false;
+                // Step size for the NEXT substep. The controllers must NOT
+                // write `h` on acceptance: `t += h` below has to advance by
+                // the step actually taken, not by the one being proposed.
+                double h_next = h;
+
+                switch (rx.solver) {
+                    case ReactionSolverKind::EUL: {
+                        fg(ws.y_.data(), ws.k1_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.y_[k] += h * ws.k1_[k];
+                        accepted = true;
+                        break;
+                    }
+                    case ReactionSolverKind::RK5: {
+                        // Cash–Karp 4(5).
+                        static constexpr double
+                          b21=0.2,
+                          b31=3.0/40.0,  b32=9.0/40.0,
+                          b41=0.3,       b42=-0.9,      b43=1.2,
+                          b51=-11.0/54.0,b52=2.5,       b53=-70.0/27.0, b54=35.0/27.0,
+                          b61=1631.0/55296.0, b62=175.0/512.0, b63=575.0/13824.0,
+                          b64=44275.0/110592.0, b65=253.0/4096.0,
+                          c1=37.0/378.0, c3=250.0/621.0, c4=125.0/594.0, c6=512.0/1771.0,
+                          d1=2825.0/27648.0, d3=18575.0/48384.0, d4=13525.0/55296.0,
+                          d5=277.0/14336.0,  d6=0.25;
+                        double* y = ws.y_.data();
+                        fg(y, ws.k1_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.ytmp_[k] = y[k] + h * b21 * ws.k1_[k];
+                        fg(ws.ytmp_.data(), ws.k2_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.ytmp_[k] = y[k] + h * (b31*ws.k1_[k] + b32*ws.k2_[k]);
+                        fg(ws.ytmp_.data(), ws.k3_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.ytmp_[k] = y[k] + h * (b41*ws.k1_[k] + b42*ws.k2_[k] + b43*ws.k3_[k]);
+                        fg(ws.ytmp_.data(), ws.k4_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.ytmp_[k] = y[k] + h * (b51*ws.k1_[k] + b52*ws.k2_[k] + b53*ws.k3_[k] + b54*ws.k4_[k]);
+                        fg(ws.ytmp_.data(), ws.k5_.data());
+                        for (std::size_t k = 0; k < gn; ++k)
+                            ws.ytmp_[k] = y[k] + h * (b61*ws.k1_[k] + b62*ws.k2_[k] + b63*ws.k3_[k] + b64*ws.k4_[k] + b65*ws.k5_[k]);
+                        fg(ws.ytmp_.data(), ws.k6_.data());
+                        for (std::size_t k = 0; k < gn; ++k) {
+                            const double y5 = y[k] + h * (c1*ws.k1_[k] + c3*ws.k3_[k] + c4*ws.k4_[k] + c6*ws.k6_[k]);
+                            const double y4 = y[k] + h * (d1*ws.k1_[k] + d3*ws.k3_[k] + d4*ws.k4_[k] + d5*ws.k5_[k] + d6*ws.k6_[k]);
+                            ws.err_[k]  = y5 - y4;
+                            ws.ytmp_[k] = y5;
+                        }
+                        const double en = errNorm(rx, ridx.data() + gb, gn,
+                                                  ws.ytmp_.data(), ws.err_.data());
+                        if (en <= 1.0) {
+                            for (std::size_t k = 0; k < gn; ++k)
+                                y[k] = ws.ytmp_[k];
+                            accepted = true;
+                            if (en > 1.0e-30)
+                                h_next = std::min(dt, 0.9 * h *
+                                                  std::pow(en, -0.2));
+                        } else {
+                            h *= std::max(0.1, 0.9 * std::pow(en, -0.25));
+                        }
+                        break;
+                    }
+                    case ReactionSolverKind::ROS2:
+                    case ReactionSolverKind::BDF2: {
+                        // Shared implicit machinery. The FD Jacobian costs gn
+                        // extra RHS evaluations — the dominant per-substep
+                        // cost — so it is REUSED across substeps and only
+                        // refreshed when it is likely stale: first substep of
+                        // a group, after a rejected step or a Newton failure
+                        // (both invalidate below), or after kJacMaxAge
+                        // accepted substeps as a bound on drift in y.
+                        // Safety differs by solver, and it matters:
+                        //  - BDF2 iterates to a residual tolerance, so an
+                        //    inexact J is a modified-Newton chord step. It
+                        //    changes the convergence RATE, never the answer.
+                        //  - ROS2 has no corrector, so a stale J does move
+                        //    the result. It stays second order (ROS2 is a
+                        //    W-method), and the embedded controller sees any
+                        //    extra error and shortens h — but that is why the
+                        //    age bound exists rather than caching forever.
+                        const int gni = static_cast(gn);
+                        double* y = ws.y_.data();
+                        fg(y, ws.k1_.data());               // f(y)
+                        const bool refresh_jac =
+                            !ws.jac_valid_ || ws.jac_age_ >= kJacMaxAge;
+                        if (refresh_jac) {
+                            for (int c = 0; c < gni; ++c) {
+                                const double save = y[c];
+                                const double dy = kFdEps * std::max(1.0, std::fabs(save));
+                                y[c] = save + dy;
+                                fg(y, ws.k2_.data());
+                                y[c] = save;
+                                for (int r = 0; r < gni; ++r)
+                                    ws.jac_[static_cast(r * gni + c)] =
+                                        (ws.k2_[static_cast(r)] -
+                                         ws.k1_[static_cast(r)]) / dy;
+                            }
+                            ws.jac_valid_ = true;
+                            ws.jac_age_   = 0;
+                            ws.lu_valid_  = false;   // matrix built from jac_
+                            // The FD sweep left `species` holding the last
+                            // perturbed column. Restore it directly rather
+                            // than through fg(), which would cost the RHS
+                            // evaluation this cache exists to avoid. (k1_
+                            // was computed before the sweep and is intact.)
+                            for (std::size_t k = 0; k < gn; ++k)
+                                species[ridx[gb + k]] = y[k];
+                            freeze_others(coupled ? static_cast(-1)
+                                                  : gb);
+                        }
+
+                        if (rx.solver == ReactionSolverKind::ROS2) {
+                            // 2-stage L-stable Rosenbrock (Verwer, Spee, Blom
+                            // & Hundsdorfer), γ = 1 − 1/√2:
+                            //   (I − γhJ) k1 = f(y)
+                            //   (I − γhJ) k2 = f(y + h k1) − 2 k1
+                            //   y⁺ = y + (3/2) h k1 + (1/2) h k2
+                            // The weights must be 3/2 and 1/2: as h → 0,
+                            // k1 → f and k2 → −f, so any other pair fails
+                            // consistency. (1 − 1/(2γ), 1/(2γ)) = (−0.707,
+                            // +1.707) gives y⁺ → y − 2.414 h f — the R3
+                            // validator's step-size collapse.
+                            const double g2 = 1.0 - 1.0 / std::sqrt(2.0);
+                            if (!factorIterationMatrix(gni, g2 * h)) {
+                                h *= 0.5; ws.jac_valid_ = false; break;
+                            }
+                            luSolve(ws.lu_, ws.piv_, gni, ws.k1_.data(),
+                                    ws.k3_.data());                 // k1 solved
+                            for (std::size_t k = 0; k < gn; ++k)
+                                ws.ytmp_[k] = y[k] + h * ws.k3_[k];
+                            fg(ws.ytmp_.data(), ws.k4_.data());
+                            for (std::size_t k = 0; k < gn; ++k)
+                                ws.res_[k] = ws.k4_[k] - 2.0 * ws.k3_[k];
+                            luSolve(ws.lu_, ws.piv_, gni, ws.res_.data(),
+                                    ws.k5_.data());                 // k2 solved
+                            constexpr double w1 = 1.5, w2 = 0.5;
+                            for (std::size_t k = 0; k < gn; ++k) {
+                                // Embedded first-order companion y + h k1;
+                                // the difference is (h/2)(k1 + k2), which
+                                // vanishes as h → 0 because k2 → −k1. The
+                                // (k2 − k1) form tends to −2 h f instead and
+                                // never falls below tolerance — the R3
+                                // validator's 99,991-substep run.
+                                ws.err_[k]  = 0.5 * h * (ws.k3_[k] + ws.k5_[k]);
+                                ws.ytmp_[k] = y[k] + h * (w1 * ws.k3_[k] +
+                                                          w2 * ws.k5_[k]);
+                            }
+                            const double en = errNorm(rx, ridx.data() + gb, gn,
+                                                      ws.ytmp_.data(), ws.err_.data());
+                            if (en <= 1.0) {
+                                for (std::size_t k = 0; k < gn; ++k)
+                                    y[k] = ws.ytmp_[k];
+                                accepted = true;
+                                if (en > 1.0e-30)
+                                    h_next = std::min(dt, 0.9 * h *
+                                                      std::pow(en, -1.0 / 3.0));
+                            } else {
+                                h *= std::max(0.1,
+                                              0.9 * std::pow(en, -0.5));
+                            }
+                        } else {
+                            // Newton-solved implicit step. BE starts the
+                            // step; once a history point exists we use
+                            // VARIABLE-step BDF2 with r = h/h_prev:
+                            //   y⁺ = a0 y − a1 y_prev + β h f(y⁺),
+                            //   a0 = (1+r)²/(1+2r), a1 = r²/(1+2r),
+                            //   β  = (1+r)/(1+2r)
+                            // (r = 1 recovers the familiar 4/3, 1/3, 2/3).
+                            // The fixed-step coefficients were wrong to use
+                            // here because the controller below changes h
+                            // between substeps. History y_prev is ws.res2_.
+                            const bool have_hist = (t > 0.0 && h_prev > 0.0);
+                            const double r = have_hist ? (h / h_prev) : 0.0;
+                            const double a0 = have_hist
+                                ? (1.0 + r) * (1.0 + r) / (1.0 + 2.0 * r) : 1.0;
+                            const double a1 = have_hist
+                                ? (r * r) / (1.0 + 2.0 * r) : 0.0;
+                            for (std::size_t k = 0; k < gn; ++k)
+                                ws.ytmp_[k] = y[k];         // Newton seed
+                            const double beta = have_hist
+                                ? (1.0 + r) / (1.0 + 2.0 * r) : 1.0;
+                            // The iteration matrix I - beta*h*J is constant
+                            // across the Newton loop (J is held at y, beta*h
+                            // is fixed), so it is factored ONCE here. It was
+                            // previously rebuilt and re-factored on every
+                            // iteration.
+                            bool newton_ok = false;
+                            if (!factorIterationMatrix(gni, beta * h)) {
+                                h *= 0.5;
+                                ws.jac_valid_ = false;
+                                break;
+                            }
+                            for (int it = 0; it < kNewtonMax; ++it) {
+                                ++rep.newton_iters;
+                                fg(ws.ytmp_.data(), ws.k2_.data());
+                                for (std::size_t k = 0; k < gn; ++k) {
+                                    const double rhs = have_hist
+                                        ? (a0 * y[k] - a1 * ws.res2_[k])
+                                        : y[k];
+                                    ws.res_[k] = ws.ytmp_[k] - rhs -
+                                                 beta * h * ws.k2_[k];
+                                }
+                                double rn = 0.0;
+                                for (std::size_t k = 0; k < gn; ++k)
+                                    rn = std::max(rn, std::fabs(ws.res_[k]));
+                                if (rn < rx.atol) { newton_ok = true; break; }
+                                luSolve(ws.lu_, ws.piv_, gni,
+                                        ws.res_.data(), ws.dy_.data());
+                                for (std::size_t k = 0; k < gn; ++k)
+                                    ws.ytmp_[k] -= ws.dy_[k];
+                            }
+                            // A chord step that fails to converge is the
+                            // classic stale-Jacobian symptom: drop the cache
+                            // so the retry re-derives it.
+                            if (!newton_ok) ws.jac_valid_ = false;
+                            if (newton_ok &&
+                                finiteAll(ws.ytmp_.data(), gn)) {
+                                // Error control. Without it BDF2 took ONE
+                                // step of the whole dt (pure backward Euler)
+                                // and was 248% off at k·dt = 2.5 — the R3
+                                // validator's finding. The embedded
+                                // companion is the explicit predictor
+                                // y + h f(y); f(y) is ws.k1_, already
+                                // evaluated for the Jacobian, so the
+                                // estimate is free. Implicit − explicit is
+                                // O(h²): a first-order pair, hence the
+                                // -1/2 growth exponent.
+                                for (std::size_t k = 0; k < gn; ++k)
+                                    ws.err_[k] = ws.ytmp_[k] -
+                                                 (y[k] + h * ws.k1_[k]);
+                                const double en =
+                                    errNorm(rx, ridx.data() + gb, gn,
+                                            ws.ytmp_.data(), ws.err_.data());
+                                if (en <= 1.0) {
+                                    for (std::size_t k = 0; k < gn; ++k) {
+                                        ws.res2_[k] = y[k];     // history
+                                        y[k]        = ws.ytmp_[k];
+                                    }
+                                    accepted = true;
+                                    if (en > 1.0e-30)
+                                        h_next = std::min(dt, 0.9 * h *
+                                                          std::pow(en, -0.5));
+                                } else {
+                                    h *= std::max(0.1,
+                                                  0.9 * std::pow(en, -0.5));
+                                }
+                            } else {
+                                h *= 0.5;
+                            }
+                        }
+                        break;
+                    }
+                }
+
+                if (accepted) {
+                    t     += h;          // the step TAKEN, before adopting…
+                    h_prev = h;          // …the controller's proposal
+                    h      = h_next;
+                    ++rep.substeps;
+                    ++ws.jac_age_;
+                } else {
+                    // A rejected step is evidence the linearization no longer
+                    // describes the local behavior — re-derive it.
+                    ws.jac_valid_ = false;
+                    if (!finiteAll(ws.y_.data(), gn)) {
+                        rep.ok = false;
+                        rep.error = "non-finite species state during "
+                                    "reaction integration";
+                    }
+                }
+            }
+            // Stage the group result; see the grp_out_ note above.
+            if (rep.ok)
+                for (std::size_t k = 0; k < gn; ++k)
+                    ws.grp_out_[static_cast(ridx[gb + k])] =
+                        ws.y_[k];
+        }
+        // Publish every group at once, after the last freeze_others().
+        if (rep.ok)
+            for (std::size_t k = 0; k < nr; ++k)
+                species[ridx[k]] =
+                    ws.grp_out_[static_cast(ridx[k])];
+    }
+    if (!rep.ok) return rep;
+
+    // ---- 2. EQUIL: joint damped Newton on {expr_s = 0} ------------------
+    const auto& eidx = ws.equil_idx_;
+    const int ne = static_cast(eidx.size());
+    if (ne > 0) {
+        const auto& spans = tank ? rx.tank_expr : rx.pipe_expr;
+        auto residual = [&](double* out) {
+            evalTerms(rx, species, hydvar, pollutants, ws.terms_);
+            RxEvalEnv env{species, rx.coef_value.data(), ws.terms_.data(),
+                          hydvar, pollutants};
+            for (int k = 0; k < ne; ++k)
+                out[k] = evalReactionExpression(
+                    rx.token_pool,
+                    spans[static_cast(eidx[static_cast(k)])],
+                    env);
+        };
+        bool converged = false;
+        for (int it = 0; it < kNewtonMax; ++it) {
+            ++rep.newton_iters;
+            residual(ws.res_.data());
+            double rn = 0.0;
+            for (int k = 0; k < ne; ++k)
+                rn = std::max(rn, std::fabs(ws.res_[static_cast(k)]));
+            if (rn < rx.atol) { converged = true; break; }
+            // FD Jacobian wrt the EQUIL species.
+            for (int c = 0; c < ne; ++c) {
+                const int sc = eidx[static_cast(c)];
+                const double save = species[sc];
+                const double dy = kFdEps * std::max(1.0, std::fabs(save));
+                species[sc] = save + dy;
+                residual(ws.res2_.data());
+                species[sc] = save;
+                for (int r = 0; r < ne; ++r)
+                    ws.jac_[static_cast(r * ne + c)] =
+                        (ws.res2_[static_cast(r)] -
+                         ws.res_[static_cast(r)]) / dy;
+            }
+            for (std::size_t k = 0; k < static_cast(ne * ne); ++k)
+                ws.lu_[k] = ws.jac_[k];
+            if (!luFactor(ws.lu_, ws.piv_, ne)) break;
+            luSolve(ws.lu_, ws.piv_, ne, ws.res_.data(), ws.dy_.data());
+            // Damped line search (halving) on the max-residual norm.
+            double lambda = 1.0;
+            for (int ls = 0; ls < 8; ++ls) {
+                for (int k = 0; k < ne; ++k)
+                    species[eidx[static_cast(k)]] -=
+                        lambda * ws.dy_[static_cast(k)];
+                residual(ws.res2_.data());
+                double rn2 = 0.0;
+                for (int k = 0; k < ne; ++k)
+                    rn2 = std::max(rn2,
+                                   std::fabs(ws.res2_[static_cast(k)]));
+                if (rn2 < rn) break;
+                for (int k = 0; k < ne; ++k)          // undo, halve
+                    species[eidx[static_cast(k)]] +=
+                        lambda * ws.dy_[static_cast(k)];
+                lambda *= 0.5;
+            }
+        }
+        if (!converged) {
+            rep.ok = false;
+            rep.error = "EQUIL Newton failed to converge";
+            return rep;
+        }
+    }
+
+    // ---- 3. FORMULA: declaration order, current values ------------------
+    if (!ws.formula_idx_.empty()) {
+        const auto& spans = tank ? rx.tank_expr : rx.pipe_expr;
+        for (const int s : ws.formula_idx_) {
+            evalTerms(rx, species, hydvar, pollutants, ws.terms_);
+            RxEvalEnv env{species, rx.coef_value.data(), ws.terms_.data(),
+                          hydvar, pollutants};
+            species[s] = evalReactionExpression(
+                rx.token_pool, spans[static_cast(s)], env);
+        }
+    }
+
+    if (!finiteAll(species, static_cast(n))) {
+        rep.ok = false;
+        rep.error = "non-finite species state after reaction step";
+    }
+    return rep;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionIntegrator.hpp b/src/engine/transport/components/ReactionModule/ReactionIntegrator.hpp
new file mode 100644
index 000000000..d7bd342f0
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionIntegrator.hpp
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionIntegrator.hpp
+ * @brief Reaction kinetics integration over one reaction step (phase R3):
+ *        EUL / RK5 (Cash–Karp) / ROS2 / BDF2 for RATE species, joint
+ *        damped-Newton for EQUIL species, in-order FORMULA evaluation,
+ *        rate-unit scaling.
+ *
+ * @details Semantics (MSX conventions, reactions plan §2/§3):
+ *          per step of length dt on one element's local species block:
+ *            1. RATE species integrate dφ/dt = expr · unit_factor with the
+ *               configured solver. COUPLING FULL integrates the RATE set
+ *               as one system; COUPLING NONE integrates each RATE species
+ *               with every other species frozen at start-of-step values.
+ *            2. EQUIL species solve the joint algebraic system
+ *               {expr_s = 0} by damped Newton (FD Jacobian, step-halving
+ *               line search, atol/rtol convergence, hard iteration cap).
+ *            3. FORMULA species evaluate in declaration order (may
+ *               reference any current value; declaration-order semantics
+ *               are the documented contract).
+ *          Terms re-evaluate (in their forward-only order) inside every
+ *          right-hand-side evaluation — they are part of f(φ).
+ *
+ *          Hand-rolled per D-R7 (no CVODE/SUNDIALS): the workload is many
+ *          tiny independent systems; BDF2 (D-R7 amendment) covers the
+ *          practically stiff range with Newton + the same dense LU ROS2
+ *          uses. All scratch lives in a caller-owned workspace sized once —
+ *          the step call is allocation-free (D-R3).
+ *
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md §3.2 D-R3–D-R9
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_REACTION_INTEGRATOR_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_REACTION_INTEGRATOR_HPP
+
+#include 
+#include 
+
+#include "../../../data/ReactionData.hpp"
+
+namespace openswmm::transport {
+
+/// Outcome of one reaction step. `ok == false` is a HARD failure (Newton
+/// divergence, non-finite state) — the caller decides fatality; soft
+/// adaptivity (substepping) is internal and only reported.
+struct RxStepReport {
+    bool ok            = true;
+    int  substeps      = 0;   ///< RATE substeps actually taken
+    int  newton_iters  = 0;   ///< EQUIL + implicit-solver Newton iterations
+    std::string error;        ///< set when !ok
+};
+
+/// Caller-owned scratch; size once per (thread × reaction system). The
+/// step call never allocates.
+class RxWorkspace {
+public:
+    void init(const ReactionData& rx);
+    bool initialized() const noexcept { return n_ > 0 || terms_.capacity() > 0; }
+
+private:
+    friend class ReactionIntegrator;
+    int n_ = 0;                       ///< n_species
+    std::vector terms_;       ///< term value cache
+    std::vector y_, y0_, ytmp_, rates_, err_;
+    std::vector k1_, k2_, k3_, k4_, k5_, k6_;   ///< RK5 stages
+    std::vector jac_, lu_;                      ///< dense n×n
+    std::vector    piv_;
+    std::vector    rate_idx_, equil_idx_, formula_idx_;
+    std::vector res_, res2_, dy_;               ///< Newton
+    std::vector grp_out_;     ///< staged per-group RATE results
+
+    // FD-Jacobian / LU reuse across substeps. The Jacobian costs `gn` extra
+    // RHS evaluations, each of which re-evaluates every term and rate
+    // expression — the dominant per-substep cost once a system has more than
+    // a species or two. J depends on y (not on h), so it survives a step-size
+    // change; the FACTORED matrix I - c*h*J does not, hence the separate
+    // scale key.
+    bool   jac_valid_ = false;   ///< jac_ holds a usable Jacobian
+    int    jac_age_   = 0;       ///< accepted substeps on the current jac_
+    bool   lu_valid_  = false;   ///< lu_/piv_ factored and reusable
+    double lu_scale_  = 0.0;     ///< the c*h that lu_ was factored at
+};
+
+class ReactionIntegrator {
+public:
+    /**
+     * @brief One reaction step on one element's local species block.
+     *
+     * @param rx      Compiled reaction system (rx.compiled must be true).
+     * @param tank    true ⇒ tank-scope expressions, false ⇒ pipe scope.
+     * @param dt      Step length (seconds).
+     * @param species [in/out] local species values, size rx.n_species().
+     * @param hydvar  RxHydVar::COUNT_ entries (DT slot is overwritten with
+     *                dt by this call).
+     * @param ws      Workspace initialized against `rx`.
+     */
+    static RxStepReport step(const ReactionData& rx, bool tank, double dt,
+                             double* species, double* hydvar, RxWorkspace& ws,
+                             const double* pollutants = nullptr);
+};
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_REACTION_INTEGRATOR_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.cpp b/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.cpp
new file mode 100644
index 000000000..6b59fdc42
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.cpp
@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionLegacyBinding.cpp
+ * @brief Phase R4 body — LEGACY quality engine reaction binding.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ReactionLegacyBinding.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "ReactionIntegrator.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+/// One workspace + block per thread of execution; the binding runs on the
+/// routing thread only, so a function-local static suffices. Re-inited when
+/// the species count changes (model reopen).
+struct BindingScratch {
+    RxWorkspace ws;
+    std::vector block;
+    int sized_for = -1;
+    void ensure(const ReactionData& rx) {
+        if (sized_for != rx.n_species()) {
+            ws.init(rx);
+            block.assign(static_cast(rx.n_species()), 0.0);
+            sized_for = rx.n_species();
+        }
+    }
+};
+
+BindingScratch& scratch() {
+    static BindingScratch s;
+    return s;
+}
+
+}  // namespace
+
+/// Lazily size + seed the MSX element state; warn once about the R4b
+/// transport limitation when any RATE MSX species exists in either scope
+/// (LEGACY only — under LARD the species ride the segments as of L3).
+void ensureMsxState(SimulationContext& ctx) {
+    auto& rx = ctx.reactions;
+    const auto ns = static_cast(rx.n_species());
+    const auto want_nodes = static_cast(ctx.n_nodes()) * ns;
+    const auto want_links = static_cast(ctx.n_links()) * ns;
+    if (rx.msx_node_conc.size() != want_nodes) {
+        rx.msx_node_conc.assign(want_nodes, 0.0);
+        rx.msx_link_conc.assign(want_links, 0.0);
+        for (std::size_t e = 0; e < static_cast(ctx.n_nodes()); ++e)
+            for (std::size_t s = 0; s < ns; ++s)
+                rx.msx_node_conc[e * ns + s] = rx.init_global[s];
+        for (std::size_t e = 0; e < static_cast(ctx.n_links()); ++e)
+            for (std::size_t s = 0; s < ns; ++s)
+                rx.msx_link_conc[e * ns + s] = rx.init_global[s];
+        // E-B2: [REACTION_QUALITY] NODE/LINK rows override the GLOBAL fill.
+        for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+            const auto e = static_cast(rx.init_elem_idx[k]);
+            const auto s = static_cast(rx.init_elem_species[k]);
+            if (s >= ns) continue;
+            auto& arr = rx.init_elem_is_link[k] ? rx.msx_link_conc
+                                                : rx.msx_node_conc;
+            if (e * ns + s < arr.size()) arr[e * ns + s] =
+                rx.init_elem_value[k];
+        }
+    }
+    // R4b (2026-09-01): the not-transported warning is GONE, not narrowed —
+    // routeLegacyMsx advects the element state on the CSTR mirror family
+    // (QualityRouting.cpp end-of-execute), so RATE species now arrive
+    // downstream under every engine.
+}
+
+namespace {
+
+/// Exact exponential pollutant decay: c *= exp(-k*dt), clamp at 0. The
+/// closed form of first-order decay — replaces the legacy linearized
+/// (1 - k*dt) when reactions are active.
+void decayPollutantsExact(SimulationContext& ctx, double dt,
+                          std::vector& conc, int n_elems,
+                          const std::vector& volume,
+                          const std::vector* node_types) {
+    const int np = ctx.n_pollutants();
+    for (int p = 0; p < np; ++p) {
+        const double k = ctx.pollutants.k_decay[static_cast(p)];
+        if (k == 0.0) continue;
+        const double f = std::exp(-k * dt);
+        double removed = 0.0;  // KD1: book the decayed mass
+        for (int i = 0; i < n_elems; ++i) {
+            const auto idx = static_cast(i) *
+                             static_cast(np) +
+                             static_cast(p);
+            if (idx >= conc.size()) continue;
+            const auto ui = static_cast(i);
+            const double v = (ui < volume.size()) ? volume[ui] : 0.0;
+            // KD1 legacy parity: a non-storage node holding no volume
+            // does not decay (qualrout.c findNodeQual decays nothing).
+            if (node_types && ui < node_types->size() &&
+                (*node_types)[ui] != NodeType::STORAGE &&
+                v <= 0.0353147)  // ZERO_VOLUME (QualityRouting.hpp)
+                continue;
+            removed += conc[idx] * (1.0 - f) * v;
+            conc[idx] *= f;
+            if (conc[idx] < 0.0) conc[idx] = 0.0;
+        }
+        if (static_cast(p) <
+            ctx.mass_balance.qual_routing_reacted.size())
+            ctx.mass_balance.qual_routing_reacted[
+                static_cast(p)] += removed;
+    }
+}
+
+void reactElements(SimulationContext& ctx, double dt, bool tank,
+                   std::vector& msx_conc,
+                   const std::vector& pollutant_conc, int n_elems,
+                   const char* what) {
+    auto& rx = ctx.reactions;
+    const int ns = rx.n_species();
+    if (ns == 0) return;
+    auto& sc = scratch();
+    sc.ensure(rx);
+
+    const int np = ctx.n_pollutants();
+    double hydvar[static_cast(RxHydVar::COUNT_)] = {};
+
+    // TEMP source: the heat engines mirror element temperatures into
+    // heat_state (node_temp / link_temp, degC) whichever router runs;
+    // absent that (HEAT_TRANSPORT off), the [REACTION_OPTIONS]
+    // TEMPERATURE constant applies.
+    const auto& elem_temp =
+        tank ? ctx.heat_state.node_temp : ctx.heat_state.link_temp;
+
+    for (int e = 0; e < n_elems; ++e) {
+        const auto ue = static_cast(e);
+        const auto base = ue * static_cast(ns);
+
+        // HRT for nodes (treatment-variable parity); zero elsewhere in R4 —
+        // full hydraulic-variable population is the ARD binding's job (R6).
+        hydvar[static_cast(RxHydVar::HRT)] =
+            (tank && ue < ctx.nodes.hrt.size()) ? ctx.nodes.hrt[ue] : 0.0;
+        hydvar[static_cast(RxHydVar::TEMP)] =
+            (ctx.options.heat_transport && ue < elem_temp.size())
+                ? elem_temp[ue]
+                : rx.default_temp_c;
+
+        for (int s = 0; s < ns; ++s)
+            sc.block[static_cast(s)] =
+                msx_conc[base + static_cast(s)];
+
+        const double* pollut =
+            (np > 0) ? &pollutant_conc[ue * static_cast(np)]
+                     : nullptr;
+
+        const auto rep = ReactionIntegrator::step(
+            rx, tank, dt, sc.block.data(), hydvar, sc.ws, pollut);
+
+        if (rep.ok) {
+            for (int s = 0; s < ns; ++s)
+                msx_conc[base + static_cast(s)] =
+                    sc.block[static_cast(s)];
+        } else if (!rx.warned_react_failure) {
+            rx.warned_react_failure = true;
+            ctx.warnings.push_back(
+                std::string("Reaction step failed at ") + what + " index " +
+                std::to_string(e) + " (element state left unchanged): " +
+                rep.error);
+        }
+    }
+}
+
+}  // namespace
+
+void reactSpeciesBlock(SimulationContext& ctx, bool tank, double dt,
+                       double* species_block, const double* pollut,
+                       double hrt_seconds, double temp_c) {
+    auto& rx = ctx.reactions;
+    const int ns = rx.n_species();
+    if (ns == 0) return;
+    auto& sc = scratch();
+    sc.ensure(rx);
+    double hydvar[static_cast(RxHydVar::COUNT_)] = {};
+    hydvar[static_cast(RxHydVar::HRT)] = hrt_seconds;
+    hydvar[static_cast(RxHydVar::TEMP)] =
+        std::isfinite(temp_c) ? temp_c : rx.default_temp_c;
+    for (int s = 0; s < ns; ++s)
+        sc.block[static_cast(s)] = species_block[s];
+    const auto rep = ReactionIntegrator::step(rx, tank, dt,
+                                              sc.block.data(), hydvar,
+                                              sc.ws, pollut);
+    if (rep.ok) {
+        for (int s = 0; s < ns; ++s)
+            species_block[s] = sc.block[static_cast(s)];
+    } else if (!rx.warned_react_failure) {
+        rx.warned_react_failure = true;
+        ctx.warnings.push_back(
+            std::string("Reaction step failed on a LARD element "
+                        "(element state left unchanged): ") +
+            rep.error);
+    }
+}
+
+bool legacyReactionsActive(const SimulationContext& ctx) {
+    return ctx.reactions.configured && ctx.reactions.compiled;
+}
+
+void reactLegacyNodes(SimulationContext& ctx, double dt) {
+    if (!legacyReactionsActive(ctx) || dt <= 0.0) return;
+    ensureMsxState(ctx);
+    decayPollutantsExact(ctx, dt, ctx.nodes.conc, ctx.n_nodes(),
+                         ctx.nodes.volume, &ctx.nodes.type);
+    reactElements(ctx, dt, /*tank=*/true, ctx.reactions.msx_node_conc,
+                  ctx.nodes.conc, ctx.n_nodes(), "node");
+}
+
+void reactLegacyLinks(SimulationContext& ctx, double dt) {
+    if (!legacyReactionsActive(ctx) || dt <= 0.0) return;
+    ensureMsxState(ctx);
+    decayPollutantsExact(ctx, dt, ctx.links.conc, ctx.n_links(),
+                         ctx.links.volume, nullptr);
+    reactElements(ctx, dt, /*tank=*/false, ctx.reactions.msx_link_conc,
+                  ctx.links.conc, ctx.n_links(), "link");
+}
+
+void warnIfLegacyBindingBypassed(SimulationContext& ctx) {
+    if (!legacyReactionsActive(ctx)) return;
+    if (ctx.options.ignore_quality) {
+        ctx.warnings.push_back(
+            "A reactions component is configured but IGNORE_QUALITY is YES — "
+            "the quality stage does not run, so no species react and no "
+            "pollutant decays this simulation.");
+    }
+    // EULERIAN_ARD is no longer a bypass: the ARD engine runs its own
+    // reaction binding as of E4/R6 (ReactionArdBinding), with MSX species
+    // transported on the mesh. The R4-era warning is retired.
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.hpp b/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.hpp
new file mode 100644
index 000000000..6dbab52a0
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionLegacyBinding.hpp
@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionLegacyBinding.hpp
+ * @brief Phase R4 — reaction binding for the LEGACY (CSTR) quality engine.
+ *
+ * @details When a reactions component is configured:
+ *          - Pollutant kdecay upgrades from the legacy linearized factor
+ *            `(1 − k·dt)` to the EXACT exponential `exp(−k·dt)` at nodes
+ *            and links (the "kdecay-as-RATE" semantics realized in closed
+ *            form — pollutant decay is exactly first-order, so the
+ *            integrator would only approximate what the exponential IS).
+ *            Bit-parity holds when NO reactions component is present: the
+ *            legacy applyDecay / in-mix decay paths are untouched then.
+ *          - MSX species evolve per element (nodes: tank scope; links:
+ *            pipe scope) via ReactionIntegrator, with the element's
+ *            pollutant concentrations exposed READ-ONLY to their
+ *            expressions (PUSH_POLLUT). MSX species are NOT yet transported
+ *            between elements under LEGACY (R4b) — a RATE MSX species
+ *            triggers a once-per-run warning. EQUIL/FORMULA MSX species
+ *            are fully meaningful (element-local algebra over pollutants).
+ *          - Integration failures are LOUD but not fatal: the element's
+ *            block is left unchanged and a once-per-run warning carries
+ *            the element id and the integrator's remedy text.
+ *
+ * @see plans/transport/MULTISPECIES_REACTIONS_MSX_PLAN.md §5 R4
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_REACTION_LEGACY_BINDING_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_REACTION_LEGACY_BINDING_HPP
+
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// True when the reactions component is active (configured + compiled) —
+/// the QualitySolver's branch condition.
+bool legacyReactionsActive(const SimulationContext& ctx);
+
+/// L3: lazily size + seed the MSX element state (GLOBAL fill +
+/// [REACTION_QUALITY] overrides). Shared by the LEGACY dispatch and the
+/// LARD engine's init — one seeding spelling for both engines.
+void ensureMsxState(SimulationContext& ctx);
+
+/// L3: integrate ONE species block in place over dt through the shared
+/// integrator. `pollut` may be null (no pollutant context); `tank`
+/// selects tank-scope expressions; `hrt_seconds` feeds RxHydVar::HRT and
+/// `temp_c` feeds RxHydVar::TEMP (NaN ⇒ the [REACTION_OPTIONS]
+/// TEMPERATURE constant). On an integrator failure the block is left
+/// unchanged and the once-per-run failure warning fires — the
+/// reactElements contract.
+void reactSpeciesBlock(SimulationContext& ctx, bool tank, double dt,
+                       double* species_block, const double* pollut,
+                       double hrt_seconds,
+                       double temp_c = std::numeric_limits::quiet_NaN());
+
+/// Node-side step: exact-exponential pollutant decay + MSX tank-scope
+/// integration. Runs where applyDecay() ran (before updateLinkQuality).
+void reactLegacyNodes(SimulationContext& ctx, double dt);
+
+/// Link-side step: exact-exponential pollutant decay + MSX pipe-scope
+/// integration. Runs AFTER updateLinkQuality() (whose internal linear decay
+/// is zeroed when reactions are active), so the reacted concentrations are
+/// not overwritten by the mixing pass.
+void reactLegacyLinks(SimulationContext& ctx, double dt);
+
+/// Warn (once, at open) when a reactions component is configured but no
+/// engine will run it this simulation. As of E4/R6 the only remaining
+/// bypass is IGNORE_QUALITY — EULERIAN_ARD now runs its own binding
+/// (ReactionArdBinding) with MSX species transported on the mesh. Without
+/// this a user who wrote a .rxn file gets a run in which nothing reacted
+/// and nothing said so.
+void warnIfLegacyBindingBypassed(SimulationContext& ctx);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_REACTION_LEGACY_BINDING_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionsComponent.cpp b/src/engine/transport/components/ReactionModule/ReactionsComponent.cpp
new file mode 100644
index 000000000..2a2f78068
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionsComponent.cpp
@@ -0,0 +1,614 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionsComponent.cpp
+ * @brief Reactions process component — phase R1 body.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "ReactionsComponent.hpp"
+#include "../../MsxInitialQuality.hpp"   // U2
+#include "ReactionsWriter.hpp"   // IO3a save hook
+
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../input/Tokenizer.hpp"
+#include "../../../plugins/ProcessComponentRegistry.hpp"
+#include "ReactionExpression.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+using input::Tokenizer;
+
+constexpr const char* kComponentId = "org.hydrocouple.openswmm.reactions";
+
+/// The raw remainder of @p line after its first @p n_lead fields —
+/// expression bodies span the rest of their row VERBATIM, so an unquoted
+/// comma (`MIN(A, 2)`) survives where the old tokenize-then-rejoin capture
+/// ate it as a delimiter (E-D1). A fully double-quoted remainder is
+/// unwrapped, keeping the pre-E-D1 quoted workaround working.
+std::string expr_payload(const std::string& line, std::size_t n_lead) {
+    const auto is_delim = [](char c) {
+        return c == ' ' || c == '\t' || c == ',';
+    };
+    std::size_t i = 0;
+    for (std::size_t f = 0; f < n_lead; ++f) {
+        while (i < line.size() && is_delim(line[i])) ++i;
+        if (i < line.size() && line[i] == '"') {          // quoted field
+            ++i;
+            while (i < line.size() && line[i] != '"') ++i;
+            if (i < line.size()) ++i;
+        } else {
+            while (i < line.size() && !is_delim(line[i])) ++i;
+        }
+    }
+    while (i < line.size() && is_delim(line[i])) ++i;
+    std::size_t e = line.size();
+    while (e > i && (line[e - 1] == ' ' || line[e - 1] == '\t' ||
+                     line[e - 1] == '\r'))
+        --e;
+    std::string s = line.substr(i, e - i);
+    if (s.size() >= 2 && s.front() == '"' && s.back() == '"')
+        s = s.substr(1, s.size() - 2);
+    return s;
+}
+
+bool to_num(const std::string& s, double& out) {
+    char* end = nullptr;
+    out = std::strtod(s.c_str(), &end);
+    return end != nullptr && *end == '\0' && end != s.c_str();
+}
+
+void parseOptions(SimulationContext& ctx, const std::vector& lines,
+                  std::vector& errors) {
+    auto& rx = ctx.reactions;
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.size() < 2) continue;
+        const std::string key = Tokenizer::to_upper(tok[0]);
+        const std::string val = Tokenizer::to_upper(tok[1]);
+        double num = 0.0;
+        if (key == "SOLVER") {
+            if      (val == "EUL")  rx.solver = ReactionSolverKind::EUL;
+            else if (val == "RK5")  rx.solver = ReactionSolverKind::RK5;
+            else if (val == "ROS2") rx.solver = ReactionSolverKind::ROS2;
+            else if (val == "BDF2") rx.solver = ReactionSolverKind::BDF2;
+            else errors.push_back("[REACTION_OPTIONS] unknown SOLVER '" +
+                                  tok[1] + "' (EUL|RK5|ROS2|BDF2).");
+        } else if (key == "COUPLING") {
+            if      (val == "NONE") rx.coupling = ReactionCoupling::NONE;
+            else if (val == "FULL") rx.coupling = ReactionCoupling::FULL;
+            else errors.push_back("[REACTION_OPTIONS] unknown COUPLING '" +
+                                  tok[1] + "' (NONE|FULL).");
+        } else if (key == "RATE_UNITS") {
+            if      (val == "SEC") rx.rate_units = ReactionRateUnits::SEC;
+            else if (val == "MIN") rx.rate_units = ReactionRateUnits::MIN;
+            else if (val == "HR")  rx.rate_units = ReactionRateUnits::HR;
+            else if (val == "DAY") rx.rate_units = ReactionRateUnits::DAY;
+            else errors.push_back("[REACTION_OPTIONS] unknown RATE_UNITS '" +
+                                  tok[1] + "' (SEC|MIN|HR|DAY).");
+        } else if (key == "AREA_UNITS") {
+            if      (val == "FT2") rx.area_units = ReactionAreaUnits::FT2;
+            else if (val == "M2")  rx.area_units = ReactionAreaUnits::M2;
+            else if (val == "CM2") rx.area_units = ReactionAreaUnits::CM2;
+            else errors.push_back("[REACTION_OPTIONS] unknown AREA_UNITS '" +
+                                  tok[1] + "' (FT2|M2|CM2).");
+        } else if (key == "TIMESTEP") {
+            if (to_num(tok[1], num) && num >= 0.0) rx.timestep = num;
+            else errors.push_back("[REACTION_OPTIONS] bad TIMESTEP '" + tok[1] + "'.");
+        } else if (key == "ATOL") {
+            if (to_num(tok[1], num) && num > 0.0) rx.atol = num;
+            else errors.push_back("[REACTION_OPTIONS] bad ATOL '" + tok[1] + "'.");
+        } else if (key == "RTOL") {
+            if (to_num(tok[1], num) && num > 0.0) rx.rtol = num;
+            else errors.push_back("[REACTION_OPTIONS] bad RTOL '" + tok[1] + "'.");
+        } else if (key == "TEMPERATURE") {
+            // TEMP's fallback (degC) for elements without a heat-transport
+            // temperature. Any finite value is a temperature; no range gate.
+            if (to_num(tok[1], num)) rx.default_temp_c = num;
+            else errors.push_back("[REACTION_OPTIONS] bad TEMPERATURE '" +
+                                  tok[1] + "'.");
+        } else {
+            errors.push_back("[REACTION_OPTIONS] unknown option '" + tok[0] + "'.");
+        }
+    }
+}
+
+void parseSpecies(SimulationContext& ctx, const std::vector& lines,
+                  std::vector& errors) {
+    auto& rx = ctx.reactions;
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        if (tok.size() < 3) {
+            errors.push_back("[REACTION_SPECIES] row needs BULK|WALL name "
+                             "units [atol rtol]: '" + line + "'.");
+            continue;
+        }
+        const std::string kind = Tokenizer::to_upper(tok[0]);
+        const bool is_wall = (kind == "WALL");
+        if (!is_wall && kind != "BULK") {
+            errors.push_back("[REACTION_SPECIES] kind must be BULK or WALL: '" +
+                             tok[0] + "'.");
+            continue;
+        }
+        const std::string& name = tok[1];
+        if (rx.find_species(name) >= 0) {
+            errors.push_back("[REACTION_SPECIES] duplicate species '" + name + "'.");
+            continue;
+        }
+        // Collision with pollutant (or reserved) names is refused — species
+        // names are globally unique (master plan §4.1). STAGED ONLY: the
+        // registry commit happens after the whole config validates and
+        // compiles (R2 transactional rule — a rejected file must leave no
+        // registry entries behind, R1 validation finding).
+        if (ctx.species_registry.find(name) >= 0) {
+            errors.push_back("[REACTION_SPECIES] '" + name +
+                             "' collides with an existing pollutant or "
+                             "species name.");
+            continue;
+        }
+        rx.species_name.push_back(name);
+        rx.species_is_wall.push_back(is_wall ? 1 : 0);
+        rx.species_units.push_back(tok[2]);
+        double atol = 0.0, rtol = 0.0;
+        if (tok.size() > 3 && !to_num(tok[3], atol))
+            errors.push_back("[REACTION_SPECIES] bad atol for '" + name + "'.");
+        if (tok.size() > 4 && !to_num(tok[4], rtol))
+            errors.push_back("[REACTION_SPECIES] bad rtol for '" + name + "'.");
+        rx.species_atol.push_back(atol);
+        rx.species_rtol.push_back(rtol);
+    }
+}
+
+void parseCoefficients(SimulationContext& ctx,
+                       const std::vector& lines,
+                       std::vector& errors) {
+    auto& rx = ctx.reactions;
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        if (tok.size() < 3) {
+            errors.push_back("[REACTION_COEFFICIENTS] row needs "
+                             "PARAMETER|CONSTANT name value: '" + line + "'.");
+            continue;
+        }
+        const std::string kind = Tokenizer::to_upper(tok[0]);
+        if (kind != "PARAMETER" && kind != "CONSTANT") {
+            errors.push_back("[REACTION_COEFFICIENTS] kind must be PARAMETER "
+                             "or CONSTANT: '" + tok[0] + "'.");
+            continue;
+        }
+        if (rx.find_coef(tok[1]) >= 0 || rx.find_species(tok[1]) >= 0) {
+            errors.push_back("[REACTION_COEFFICIENTS] name '" + tok[1] +
+                             "' duplicates a coefficient or species.");
+            continue;
+        }
+        double v = 0.0;
+        if (!to_num(tok[2], v)) {
+            errors.push_back("[REACTION_COEFFICIENTS] bad value for '" +
+                             tok[1] + "'.");
+            continue;
+        }
+        rx.coef_name.push_back(tok[1]);
+        rx.coef_is_param.push_back(kind == "PARAMETER" ? 1 : 0);
+        rx.coef_value.push_back(v);
+    }
+}
+
+void parseTerms(SimulationContext& ctx, const std::vector& lines,
+                std::vector& errors) {
+    auto& rx = ctx.reactions;
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        if (tok.size() < 2) {
+            errors.push_back("[REACTION_TERMS] row needs name expression: '" +
+                             line + "'.");
+            continue;
+        }
+        if (rx.find_term(tok[0]) >= 0 || rx.find_species(tok[0]) >= 0 ||
+            rx.find_coef(tok[0]) >= 0) {
+            errors.push_back("[REACTION_TERMS] name '" + tok[0] +
+                             "' duplicates a term, species, or coefficient.");
+            continue;
+        }
+        rx.term_name.push_back(tok[0]);
+        rx.term_expr_src.push_back(expr_payload(line, 1));
+    }
+}
+
+void parseExpressions(SimulationContext& ctx,
+                      const std::vector& lines, bool tanks,
+                      std::vector& errors) {
+    auto& rx = ctx.reactions;
+    const char* sec = tanks ? "[REACTION_TANKS]" : "[REACTION_PIPES]";
+    auto& forms = tanks ? rx.tank_form : rx.pipe_form;
+    auto& srcs  = tanks ? rx.tank_expr_src : rx.pipe_expr_src;
+    forms.resize(static_cast(rx.n_species()), ReactionExprForm::NONE);
+    srcs.resize(static_cast(rx.n_species()));
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        if (tok.size() < 3) {
+            errors.push_back(std::string(sec) +
+                             " row needs RATE|EQUIL|FORMULA species "
+                             "expression: '" + line + "'.");
+            continue;
+        }
+        const std::string form = Tokenizer::to_upper(tok[0]);
+        ReactionExprForm f = ReactionExprForm::NONE;
+        if      (form == "RATE")    f = ReactionExprForm::RATE;
+        else if (form == "EQUIL")   f = ReactionExprForm::EQUIL;
+        else if (form == "FORMULA") f = ReactionExprForm::FORMULA;
+        else {
+            errors.push_back(std::string(sec) + " unknown form '" + tok[0] +
+                             "' (RATE|EQUIL|FORMULA).");
+            continue;
+        }
+        const int s = rx.find_species(tok[1]);
+        if (s < 0) {
+            if (ctx.species_registry.find(tok[1]) >= 0) {
+                errors.push_back(std::string(sec) + " '" + tok[1] +
+                                 "' is a pollutant — pollutant kinetics "
+                                 "(RATE/EQUIL/FORMULA on a pollutant) arrive "
+                                 "with plan phase R4b; pollutants may be "
+                                 "REFERENCED read-only in MSX expressions "
+                                 "today, and kdecay applies under every "
+                                 "engine.");
+            } else {
+                errors.push_back(std::string(sec) + " undeclared species '" +
+                                 tok[1] +
+                                 "' — declare it in [REACTION_SPECIES].");
+            }
+            continue;
+        }
+        const auto us = static_cast(s);
+        if (forms[us] != ReactionExprForm::NONE) {
+            errors.push_back(std::string(sec) + " species '" + tok[1] +
+                             "' already has an expression in this scope.");
+            continue;
+        }
+        forms[us] = f;
+        srcs[us]  = expr_payload(line, 2);
+    }
+}
+
+void parseQuality(SimulationContext& ctx, const std::vector& lines,
+                  std::vector& errors) {
+    auto& rx = ctx.reactions;
+    rx.init_global.assign(static_cast(rx.n_species()), 0.0);
+    rx.init_elem_is_link.clear();
+    rx.init_elem_idx.clear();
+    rx.init_elem_species.clear();
+    rx.init_elem_value.clear();
+    for (const auto& line : lines) {
+        auto tok = Tokenizer::tokenize(line);
+        if (tok.empty()) continue;
+        const std::string scope = Tokenizer::to_upper(tok[0]);
+
+        // E-B1: NODE/LINK per-element rows. Element resolution happens here
+        // (D-RQ1): components apply at open, AFTER the full .inp parse, so
+        // ctx.node_names/link_names are complete.
+        if (scope == "NODE" || scope == "LINK") {
+            const bool link = (scope == "LINK");
+            if (tok.size() < 4) {
+                errors.push_back("[REACTION_QUALITY] row needs " + scope +
+                                 " element species value: '" + line + "'.");
+                continue;
+            }
+            const int ei = link ? ctx.link_names.find(tok[1])
+                                : ctx.node_names.find(tok[1]);
+            if (ei < 0) {
+                errors.push_back(std::string("[REACTION_QUALITY] unknown ") +
+                                 (link ? "link" : "node") + " '" + tok[1] +
+                                 "'.");
+                continue;
+            }
+            const int s = rx.find_species(tok[2]);
+            if (s < 0) {
+                errors.push_back("[REACTION_QUALITY] undeclared species '" +
+                                 tok[2] + "'.");
+                continue;
+            }
+            double v = 0.0;
+            if (!to_num(tok[3], v) || v < 0.0) {
+                errors.push_back("[REACTION_QUALITY] bad value for '" +
+                                 tok[2] + "'.");
+                continue;
+            }
+            bool dup = false;
+            for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+                if ((rx.init_elem_is_link[k] != 0) == link &&
+                    rx.init_elem_idx[k] == ei &&
+                    rx.init_elem_species[k] == s) {
+                    dup = true;
+                    break;
+                }
+            }
+            if (dup) {
+                errors.push_back("[REACTION_QUALITY] duplicate row for '" +
+                                 tok[2] + "' at " +
+                                 (link ? "link" : "node") + " '" + tok[1] +
+                                 "'.");
+                continue;
+            }
+            rx.init_elem_is_link.push_back(link ? 1 : 0);
+            rx.init_elem_idx.push_back(ei);
+            rx.init_elem_species.push_back(s);
+            rx.init_elem_value.push_back(v);
+            continue;
+        }
+
+        if (scope != "GLOBAL") {
+            errors.push_back("[REACTION_QUALITY] scope '" + tok[0] +
+                             "' is not GLOBAL, NODE, or LINK.");
+            continue;
+        }
+        if (tok.size() < 3) {
+            errors.push_back("[REACTION_QUALITY] row needs GLOBAL species "
+                             "value: '" + line + "'.");
+            continue;
+        }
+        const int s = rx.find_species(tok[1]);
+        if (s < 0) {
+            errors.push_back("[REACTION_QUALITY] undeclared species '" +
+                             tok[1] + "'.");
+            continue;
+        }
+        double v = 0.0;
+        if (!to_num(tok[2], v) || v < 0.0) {
+            errors.push_back("[REACTION_QUALITY] bad value for '" + tok[1] + "'.");
+            continue;
+        }
+        rx.init_global[static_cast(s)] = v;
+    }
+    // U2: [INITIAL_QUALITY] MSX rows live in ctx.initial_quality (already
+    // classified when this is a re-apply; PostParseResolver mirrors them at
+    // open). The block reset above emptied init_elem_*, so bring them back.
+    for (const auto& e : mirrorInitialQualityMsxRows(ctx)) errors.push_back(e);
+}
+
+}  // namespace
+
+const std::vector& reactionSectionTags() {
+    static const std::vector tags = {
+        "REACTION_OPTIONS",       "REACTION_SPECIES",
+        "REACTION_COEFFICIENTS",  "REACTION_TERMS",
+        "REACTION_PIPES",         "REACTION_TANKS",
+        "REACTION_SOURCES",       "REACTION_QUALITY",
+        "REACTION_PARAMETERS",    "REACTION_PATTERNS",
+        "REACTION_REPORT",        "REACTION_SUBCATCHMENTS"};
+    return tags;
+}
+
+void applyReactionSections(SimulationContext& ctx,
+                           const components::ComponentConfigSections& config,
+                           std::vector& errors) {
+    if (ctx.reactions.configured) {
+        errors.push_back(
+            "Reactions system configured twice — duplicate registration or "
+            "embedded sections alongside an external component file.");
+        return;
+    }
+    ctx.reactions.clear();
+
+    // Order matters: species before coefficients/terms/expressions so
+    // references validate. Sections may appear in any file order.
+    const auto* s = config.find("REACTION_OPTIONS");
+    if (s) parseOptions(ctx, *s, errors);
+    s = config.find("REACTION_SPECIES");
+    if (s) parseSpecies(ctx, *s, errors);
+    if (ctx.reactions.n_species() == 0) {
+        errors.push_back("Reactions config declares no [REACTION_SPECIES] — "
+                         "at least one species is required.");
+        return;
+    }
+    s = config.find("REACTION_COEFFICIENTS");
+    if (s) parseCoefficients(ctx, *s, errors);
+    s = config.find("REACTION_TERMS");
+    if (s) parseTerms(ctx, *s, errors);
+    s = config.find("REACTION_PIPES");
+    if (s) parseExpressions(ctx, *s, /*tanks=*/false, errors);
+    else {
+        ctx.reactions.pipe_form.assign(
+            static_cast(ctx.reactions.n_species()),
+            ReactionExprForm::NONE);
+        ctx.reactions.pipe_expr_src.resize(
+            static_cast(ctx.reactions.n_species()));
+    }
+    s = config.find("REACTION_TANKS");
+    if (s) parseExpressions(ctx, *s, /*tanks=*/true, errors);
+    else {
+        ctx.reactions.tank_form.assign(
+            static_cast(ctx.reactions.n_species()),
+            ReactionExprForm::NONE);
+        ctx.reactions.tank_expr_src.resize(
+            static_cast(ctx.reactions.n_species()));
+    }
+    s = config.find("REACTION_QUALITY");
+    if (s) parseQuality(ctx, *s, errors);
+    else
+        ctx.reactions.init_global.assign(
+            static_cast(ctx.reactions.n_species()), 0.0);
+
+    // Later-phase sections: defined behavior, never silent acceptance.
+    const struct { const char* tag; const char* phase; } later[] = {
+        {"REACTION_SOURCES",       "R-sources (post-R3)"},
+        {"REACTION_PARAMETERS",    "R-parameters (post-R3)"},
+        {"REACTION_PATTERNS",      "R-sources (post-R3)"},
+        {"REACTION_REPORT",        "R5"},
+        {"REACTION_SUBCATCHMENTS", "R6"},
+    };
+    for (const auto& l : later) {
+        if (config.find(l.tag) != nullptr)
+            errors.push_back(std::string("[") + l.tag +
+                             "] is recognized but not yet supported — "
+                             "arrives with plan phase " + l.phase + ".");
+    }
+
+    // Unknown REACTION_* sections in the file are typos worth failing on.
+    for (const auto& sect : config.sections) {
+        bool known = false;
+        for (const auto& t : reactionSectionTags())
+            if (sect.first == t) { known = true; break; }
+        if (!known)
+            errors.push_back("Unknown section [" + sect.first +
+                             "] in reactions config '" + config.source_path +
+                             "'.");
+    }
+
+    if (!errors.empty()) {
+        // Transactional: a rejected config leaves NOTHING behind — neither
+        // reaction state nor registry entries (nothing was committed yet).
+        ctx.reactions.clear();
+        return;
+    }
+
+    // ---- R2: compile every expression into the flat token pool. --------
+    if (!recompileReactionSystem(ctx, errors)) {
+        ctx.reactions.clear();
+        return;
+    }
+    auto& rx2 = ctx.reactions;
+
+    // ---- Commit: registry entries only now, after full success. --------
+    for (int sidx = 0; sidx < rx2.n_species(); ++sidx) {
+        const auto us = static_cast(sidx);
+        const int reg = ctx.species_registry.add(
+            rx2.species_name[us],
+            rx2.species_is_wall[us] ? SpeciesKind::MSX_WALL
+                                    : SpeciesKind::MSX_BULK,
+            rx2.species_units[us]);
+        if (rx2.registry_base < 0) rx2.registry_base = reg;
+    }
+    rx2.compiled   = true;
+    rx2.configured = true;
+}
+
+void applyEmbeddedReactionSections(SimulationContext& ctx,
+                                   bool external_component_registered,
+                                   std::vector& errors) {
+    if (ctx.embedded_component_sections.empty()) return;
+
+    if (external_component_registered) {
+        ctx.warnings.push_back(
+            "Embedded [REACTION_*] sections in the .inp are IGNORED because "
+            "an external reactions component is registered in "
+            "[PROCESS_COMPONENTS] — the external config file wins "
+            "(TRANSPORT_IO_PLUGIN_CONFIG_PLAN §3.2).");
+        return;
+    }
+
+    ctx.warnings.push_back(
+        "Embedded [REACTION_*] sections found in the .inp. This works, but "
+        "the clean layout is an external component config file registered "
+        "via [PROCESS_COMPONENTS] (config=\"model.rxn\") — see "
+        "TRANSPORT_IO_PLUGIN_CONFIG_PLAN.md (style warning, D-UT8).");
+
+    components::ComponentConfigSections synth;
+    synth.source_path = "(embedded in .inp)";
+    synth.sections    = ctx.embedded_component_sections;
+    applyReactionSections(ctx, synth, errors);
+}
+
+void registerReactionsComponent() {
+    components::ProcessComponentRegistry::instance().register_component(
+        kComponentId,
+        "Multispecies reaction system (EPANET-MSX conventions)",
+        [](SimulationContext& ctx, const ProcessComponentSpec& /*spec*/,
+           const components::ComponentConfigSections& config,
+           std::vector& errors) {
+            applyReactionSections(ctx, config, errors);
+        },
+        // IO3a: the canonical .rxn serializer already existed (E-C3,
+        // ReactionsWriter) and was reachable only through the C API's
+        // get-text call. Nothing ever asked it to write the file on save, so
+        // reaction edits made through the API or the GUI were lost exactly
+        // like heat's. The capability was present; the CALL SITE was missing.
+        [](const SimulationContext& ctx,
+           const ProcessComponentSpec& /*spec*/) -> std::string {
+            return transport::serializeReactionSystem(ctx);
+        });
+}
+
+// ============================================================================
+// recompileReactionSystem() — the one compile path (E-C2 / D-RC4)
+// ============================================================================
+
+bool recompileReactionSystem(SimulationContext& ctx,
+                             std::vector& errors) {
+    auto& rx = ctx.reactions;
+    rx.compiled = false;
+    rx.token_pool.clear();
+    rx.term_expr.assign(rx.term_name.size(), RxExprSpan{});
+    rx.pipe_expr.assign(static_cast(rx.n_species()),
+                        RxExprSpan{});
+    rx.tank_expr.assign(static_cast(rx.n_species()),
+                        RxExprSpan{});
+
+    // R4: pollutants are referencable (read-only) in expressions. Build the
+    // name list in registry order (pollutants occupy the first registry
+    // slots; PUSH_POLLUT idx == pollutant index).
+    std::vector pollutant_names;
+    for (int p2 = 0; p2 < ctx.species_registry.pollutant_count(); ++p2)
+        pollutant_names.push_back(ctx.species_registry.name(p2));
+
+    RxSymbols sym;
+    sym.species    = &rx.species_name;
+    sym.coefs      = &rx.coef_name;
+    sym.terms      = &rx.term_name;
+    sym.pollutants = &pollutant_names;
+
+    const std::size_t n_errors_in = errors.size();
+    auto compile_one = [&](const std::string& src_expr, RxExprSpan& span,
+                           const std::string& where) {
+        int col = 0;
+        const std::string err = compileReactionExpression(
+            src_expr, sym, rx.token_pool, span, col);
+        if (!err.empty())
+            errors.push_back(where + " (col " + std::to_string(col) +
+                             "): " + err + ".");
+    };
+
+    for (std::size_t i = 0; i < rx.term_name.size(); ++i) {
+        sym.max_term = static_cast(i);   // forward-only rule
+        compile_one(rx.term_expr_src[i], rx.term_expr[i],
+                    "[REACTION_TERMS] '" + rx.term_name[i] + "'");
+    }
+    sym.max_term = static_cast(rx.term_name.size());
+    for (int sidx = 0; sidx < rx.n_species(); ++sidx) {
+        const auto us = static_cast(sidx);
+        if (rx.pipe_form[us] != ReactionExprForm::NONE)
+            compile_one(rx.pipe_expr_src[us], rx.pipe_expr[us],
+                        "[REACTION_PIPES] '" + rx.species_name[us] + "'");
+        if (rx.tank_form[us] != ReactionExprForm::NONE)
+            compile_one(rx.tank_expr_src[us], rx.tank_expr[us],
+                        "[REACTION_TANKS] '" + rx.species_name[us] + "'");
+    }
+    if (errors.size() != n_errors_in) return false;
+    rx.compiled = true;
+    return true;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionsComponent.hpp b/src/engine/transport/components/ReactionModule/ReactionsComponent.hpp
new file mode 100644
index 000000000..4dbdd87c1
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionsComponent.hpp
@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionsComponent.hpp
+ * @brief The `org.hydrocouple.openswmm.reactions` process component —
+ *        phase R1: parse `model.rxn` [REACTION_*] sections into
+ *        ReactionData + the species registry.
+ *
+ * @details R1 scope: structure and references are fully validated (species
+ *          declared before use, unique names, no collision with pollutant
+ *          names, valid forms/kinds/options); expression BODIES are stored
+ *          as source and compiled by phase R2's Tier-1 VM. Sections whose
+ *          semantics land in later phases ([REACTION_SOURCES],
+ *          [REACTION_PARAMETERS], [REACTION_PATTERNS], [REACTION_REPORT],
+ *          [REACTION_SUBCATCHMENTS]) produce a precise
+ *          "arrives with plan phase …" error rather than being silently
+ *          accepted. Embedded [REACTION_*] sections in the legacy .inp are
+ *          honored with a style warning when no external component is
+ *          registered; the external file wins wholesale on conflict
+ *          (TRANSPORT_IO_PLUGIN_CONFIG_PLAN §3.2).
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_REACTIONS_COMPONENT_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_REACTIONS_COMPONENT_HPP
+
+#include 
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+namespace openswmm::components {
+struct ComponentConfigSections;
+}
+
+namespace openswmm::transport {
+
+/// Register `org.hydrocouple.openswmm.reactions` with the process-component
+/// registry (idempotent; called from SWMMEngine::open before resolution).
+void registerReactionsComponent();
+
+/// The 12 [REACTION_*] tags (upper-case, no brackets) — shared by the
+/// embedded-fallback handlers and the config parser.
+const std::vector& reactionSectionTags();
+
+/// Parse + validate a set of reaction sections into ctx.reactions and the
+/// species registry. Shared by the component apply hook (external file) and
+/// the embedded fallback. Diagnostics are appended to `errors` (fatal).
+void applyReactionSections(SimulationContext& ctx,
+                           const components::ComponentConfigSections& config,
+                           std::vector& errors);
+
+/// Embedded fallback (called from SWMMEngine::open after component
+/// resolution): if [REACTION_*] sections were found in the legacy .inp,
+/// apply them with a style warning — unless an external reactions component
+/// was registered, in which case the external file wins wholesale and the
+/// embedded sections are reported ignored.
+void applyEmbeddedReactionSections(SimulationContext& ctx,
+                                   bool external_component_registered,
+                                   std::vector& errors);
+
+/// Recompile every reaction expression (terms, pipes, tanks) into a fresh
+/// flat token pool from the sources in ctx.reactions (E-C2: the one compile
+/// path, shared by the file apply and the CRUD API's eager validation —
+/// D-RC4, no second compiler). Returns true and sets rx.compiled on
+/// success; on failure appends diagnostics and leaves rx.compiled false
+/// (the pool/spans hold the partial result — callers roll back or clear).
+bool recompileReactionSystem(SimulationContext& ctx,
+                             std::vector& errors);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_REACTIONS_COMPONENT_HPP
diff --git a/src/engine/transport/components/ReactionModule/ReactionsWriter.cpp b/src/engine/transport/components/ReactionModule/ReactionsWriter.cpp
new file mode 100644
index 000000000..e30338d27
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionsWriter.cpp
@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionsWriter.cpp
+ * @brief Canonical .rxn serializer (E-C3). @see ReactionsWriter.hpp
+ */
+
+#include "ReactionsWriter.hpp"
+#include "../../MsxInitialQuality.hpp"   // U2
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+/// Shortest decimal form that parses back to exactly @p v — stable across
+/// serialize -> parse -> serialize (the D-RC6 requirement).
+std::string fmt_double(double v) {
+    char buf[64];
+    for (int prec = 15; prec <= 17; ++prec) {
+        std::snprintf(buf, sizeof(buf), "%.*g", prec, v);
+        if (std::strtod(buf, nullptr) == v) break;
+    }
+    return buf;
+}
+
+void row(std::string& out, const char* a, const std::string& b,
+         const std::string& c = {}, const std::string& d = {},
+         const std::string& e = {}) {
+    char line[512];
+    if (!e.empty())
+        std::snprintf(line, sizeof(line), "%-10s %-16s %-16s %-12s %s\n",
+                      a, b.c_str(), c.c_str(), d.c_str(), e.c_str());
+    else if (!d.empty())
+        std::snprintf(line, sizeof(line), "%-10s %-16s %-16s %s\n",
+                      a, b.c_str(), c.c_str(), d.c_str());
+    else if (!c.empty())
+        std::snprintf(line, sizeof(line), "%-10s %-16s %s\n",
+                      a, b.c_str(), c.c_str());
+    else
+        std::snprintf(line, sizeof(line), "%-10s %s\n", a, b.c_str());
+    out += line;
+}
+
+const char* form_tok(ReactionExprForm f) {
+    switch (f) {
+        case ReactionExprForm::RATE:    return "RATE";
+        case ReactionExprForm::EQUIL:   return "EQUIL";
+        case ReactionExprForm::FORMULA: return "FORMULA";
+        default:                        return nullptr;
+    }
+}
+
+} // namespace
+
+std::string serializeReactionSystem(const SimulationContext& ctx) {
+    const auto& rx = ctx.reactions;
+    if (!rx.configured && rx.n_species() == 0) return {};
+
+    std::string out;
+    out += ";; Reaction system configuration — written by OpenSWMM.\n";
+
+    out += "\n[REACTION_OPTIONS]\n";
+    {
+        static const char* kSolver[] = {"EUL", "RK5", "ROS2", "BDF2"};
+        static const char* kRate[]   = {"SEC", "MIN", "HR", "DAY"};
+        static const char* kArea[]   = {"FT2", "M2", "CM2"};
+        row(out, "SOLVER",     kSolver[static_cast(rx.solver)]);
+        row(out, "COUPLING",
+            static_cast(rx.coupling) == 1 ? "FULL" : "NONE");
+        row(out, "RATE_UNITS", kRate[static_cast(rx.rate_units)]);
+        row(out, "AREA_UNITS", kArea[static_cast(rx.area_units)]);
+        row(out, "TIMESTEP",   fmt_double(rx.timestep));
+        row(out, "ATOL",       fmt_double(rx.atol));
+        row(out, "RTOL",       fmt_double(rx.rtol));
+        row(out, "TEMPERATURE", fmt_double(rx.default_temp_c));
+    }
+
+    out += "\n[REACTION_SPECIES]\n";
+    out += ";;Kind     Name             Units            [Atol]       [Rtol]\n";
+    for (int s = 0; s < rx.n_species(); ++s) {
+        const auto u = static_cast(s);
+        const bool tols = rx.species_atol[u] > 0.0 || rx.species_rtol[u] > 0.0;
+        if (tols)
+            row(out, rx.species_is_wall[u] ? "WALL" : "BULK",
+                rx.species_name[u], rx.species_units[u],
+                fmt_double(rx.species_atol[u]),
+                fmt_double(rx.species_rtol[u]));
+        else
+            row(out, rx.species_is_wall[u] ? "WALL" : "BULK",
+                rx.species_name[u], rx.species_units[u]);
+    }
+
+    if (!rx.coef_name.empty()) {
+        out += "\n[REACTION_COEFFICIENTS]\n";
+        out += ";;Kind     Name             Value\n";
+        for (std::size_t i = 0; i < rx.coef_name.size(); ++i)
+            row(out, rx.coef_is_param[i] ? "PARAMETER" : "CONSTANT",
+                rx.coef_name[i], fmt_double(rx.coef_value[i]));
+    }
+
+    if (!rx.term_name.empty()) {
+        out += "\n[REACTION_TERMS]\n";
+        out += ";;Name     Expression\n";
+        for (std::size_t i = 0; i < rx.term_name.size(); ++i)
+            row(out, rx.term_name[i].c_str(), rx.term_expr_src[i]);
+    }
+
+    auto emit_scope = [&](const char* tag,
+                          const std::vector& forms,
+                          const std::vector& srcs) {
+        bool any = false;
+        for (const auto f : forms)
+            if (f != ReactionExprForm::NONE) any = true;
+        if (!any) return;
+        out += std::string("\n[") + tag + "]\n";
+        out += ";;Form     Species          Expression\n";
+        for (int s = 0; s < rx.n_species(); ++s) {
+            const auto u = static_cast(s);
+            const char* tok = form_tok(forms[u]);
+            if (!tok) continue;
+            row(out, tok, rx.species_name[u], srcs[u]);
+        }
+    };
+    emit_scope("REACTION_PIPES", rx.pipe_form, rx.pipe_expr_src);
+    emit_scope("REACTION_TANKS", rx.tank_form, rx.tank_expr_src);
+
+    // Initial quality: nonzero GLOBAL rows, then the per-element rows.
+    {
+        bool any = false;
+        for (const auto v : rx.init_global)
+            if (v != 0.0) any = true;
+        // U2: per-element rows mirrored from [INITIAL_QUALITY] are written
+        // THERE by the InpWriter; only rows the .rxn itself owns (authored in
+        // its NODE|LINK scopes or set through the reactions C API) stay here.
+        bool any_own_elem = false;
+        for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+            if (!initialQualityHasMsxRow(ctx, rx.init_elem_is_link[k] != 0,
+                                         rx.init_elem_idx[k], rx.init_elem_species[k])) {
+                any_own_elem = true;
+                break;
+            }
+        }
+        if (any || any_own_elem) {
+            out += "\n[REACTION_QUALITY]\n";
+            out += ";;Scope    [Element]        Species          Value\n";
+            for (int s = 0; s < rx.n_species(); ++s) {
+                const auto u = static_cast(s);
+                if (u < rx.init_global.size() && rx.init_global[u] != 0.0)
+                    row(out, "GLOBAL", rx.species_name[u],
+                        fmt_double(rx.init_global[u]));
+            }
+            for (std::size_t k = 0; k < rx.init_elem_idx.size(); ++k) {
+                const bool link = rx.init_elem_is_link[k] != 0;
+                const int ei = rx.init_elem_idx[k];
+                const int si = rx.init_elem_species[k];
+                if (si < 0 || si >= rx.n_species()) continue;
+                if (initialQualityHasMsxRow(ctx, link, ei, si)) continue;   // U2
+                const std::string en =
+                    link ? ((ei >= 0 && ei < ctx.n_links())
+                                ? ctx.link_names.name_of(ei)
+                                : std::string("*"))
+                         : ((ei >= 0 && ei < ctx.n_nodes())
+                                ? ctx.node_names.name_of(ei)
+                                : std::string("*"));
+                row(out, link ? "LINK" : "NODE", en,
+                    rx.species_name[static_cast(si)],
+                    fmt_double(rx.init_elem_value[k]));
+            }
+        }
+    }
+
+    return out;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/ReactionModule/ReactionsWriter.hpp b/src/engine/transport/components/ReactionModule/ReactionsWriter.hpp
new file mode 100644
index 000000000..38108f199
--- /dev/null
+++ b/src/engine/transport/components/ReactionModule/ReactionsWriter.hpp
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file ReactionsWriter.hpp
+ * @brief Canonical .rxn text from engine state (E-C3).
+ *
+ * @details The round-trip IS the spec (D-RC6): serialize -> apply_text ->
+ *          serialize must be byte-identical, which is the sync contract the
+ *          GUI text tab builds on. Numbers print in shortest-round-trip
+ *          form; expressions emit verbatim (unquoted — E-D1 made commas
+ *          re-parseable).
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_REACTIONS_WRITER_HPP
+#define OPENSWMM_ENGINE_REACTIONS_WRITER_HPP
+
+#include 
+
+namespace openswmm { struct SimulationContext; }
+
+namespace openswmm::transport {
+
+/// Canonical .rxn text for the current reaction system (empty system ->
+/// a header comment plus an empty [REACTION_SPECIES] shell is NOT emitted;
+/// the result is an empty string when nothing is configured).
+std::string serializeReactionSystem(const SimulationContext& ctx);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_REACTIONS_WRITER_HPP
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.cpp b/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.cpp
new file mode 100644
index 000000000..1c9f898ad
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.cpp
@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeComponent.cpp
+ * @brief waterage component apply hook — phase A1a body.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "WaterAgeComponent.hpp"
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../plugins/ProcessComponentRegistry.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr const char* kAgeId = "org.hydrocouple.openswmm.waterage";
+
+std::vector tokenize(const std::string& line) {
+    std::vector toks;
+    std::string cur;
+    for (const char ch : line) {
+        if (ch == ' ' || ch == '\t') {
+            if (!cur.empty()) { toks.push_back(cur); cur.clear(); }
+        } else {
+            cur.push_back(ch);
+        }
+    }
+    if (!cur.empty()) toks.push_back(cur);
+    return toks;
+}
+
+std::string upper(std::string s) {
+    std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) {
+        return static_cast(std::toupper(c));
+    });
+    return s;
+}
+
+bool parse_hours(const std::string& tok, double& out) {
+    // D-NS1 (X6): negative hours are now legal — a negative source age is
+    // age-volume EXTRACTION (warned at the call site). The parse rejects
+    // only non-numbers.
+    char* end = nullptr;
+    out = std::strtod(tok.c_str(), &end);
+    return end != nullptr && *end == '\0' && end != tok.c_str();
+}
+
+/// Storage-index → file spelling, the inverse of source_of below.
+const char* source_name(int s) {
+    static const char* const kNames[] = {
+        "RAINFALL", "DWF", "GW", "RDII", "EXTERNAL_INFLOW",
+        "IFACE", "INITIAL_STATE"};
+    static_assert(sizeof(kNames) / sizeof(kNames[0]) ==
+                      static_cast(WaterAgeSource::COUNT_),
+                  "source_name is missing a WaterAgeSource — teach it "
+                  "the new pathway, then serializeWaterAgeConfig");
+    return (s >= 0 && s < static_cast(WaterAgeSource::COUNT_))
+               ? kNames[s] : "?";
+}
+
+/// Shortest decimal that reads back EXACTLY — fmt_degc's convention.
+/// The config stores SECONDS against a file in HOURS; a formatter
+/// that rounds (the old %g) drifts the model on every save.
+std::string fmt_hours(double v) {
+    char buf[64];
+    for (int prec = 15; prec <= 17; ++prec) {
+        std::snprintf(buf, sizeof(buf), "%.*g", prec, v);
+        if (std::strtod(buf, nullptr) == v) break;
+    }
+    return buf;
+}
+
+int source_of(const std::string& u) {
+    if (u == "RAINFALL")        return static_cast(WaterAgeSource::RAINFALL);
+    if (u == "DWF")             return static_cast(WaterAgeSource::DWF);
+    if (u == "GW")              return static_cast(WaterAgeSource::GW);
+    if (u == "RDII")            return static_cast(WaterAgeSource::RDII);
+    if (u == "EXTERNAL_INFLOW") return static_cast(WaterAgeSource::EXTERNAL_INFLOW);
+    if (u == "IFACE")           return static_cast(WaterAgeSource::IFACE);
+    if (u == "INITIAL_STATE")   return static_cast(WaterAgeSource::INITIAL_STATE);
+    return -1;
+}
+
+void applyWaterAgeSections(SimulationContext& ctx,
+                           const components::ComponentConfigSections& config,
+                           std::vector& errors) {
+    ctx.water_age_config = WaterAgeConfigData{};  // reopen hygiene
+    const std::size_t errors_before = errors.size();
+
+    for (const auto& sec : config.sections) {
+        if (sec.first != "WATER_AGE_SOURCES") {
+            errors.push_back(
+                "model.age: unknown section [" + sec.first +
+                "] (A1a recognizes: [WATER_AGE_SOURCES]).");
+            continue;
+        }
+        for (const auto& line : sec.second) {
+            const auto toks = tokenize(line);
+            if (toks.size() < 3) {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] expects '  [name] "
+                    "': '" + line + "'.");
+                continue;
+            }
+            const int src = source_of(upper(toks[0]));
+            if (src < 0) {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] unknown source '" + toks[0] +
+                    "' (RAINFALL, DWF, GW, RDII, EXTERNAL_INFLOW, IFACE, "
+                    "INITIAL_STATE).");
+                continue;
+            }
+            const std::string scope = upper(toks[1]);
+
+            // Deferral surface — precise phase names, never silence.
+            if (scope == "SUBCATCH") {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] SUBCATCH scope arrives with plan "
+                    "phase A3 (watershed age states).");
+                continue;
+            }
+            if (scope == "EDGE_BC") {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] EDGE_BC scope arrives with phase "
+                    "T6 (2D transport).");
+                continue;
+            }
+            // The value token sits after the scope's optional name. Bind it
+            // only once the row is known to HAVE that column: reading
+            // toks[3] before the arity check was an out-of-bounds read on
+            // any 3-token NODE row ('DWF NODE J0', an age omitted by hand).
+            const bool has_name = (scope == "NODE");
+            const std::size_t vpos = has_name ? 3u : 2u;
+            if (toks.size() <= vpos) {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] malformed row: '" + line + "'.");
+                continue;
+            }
+            const std::string& vtok = toks[vpos];
+            // TIMESERIES is checked BEFORE the exact-arity test because its
+            // documented spelling carries a series NAME after the keyword
+            // ('EXTERNAL_INFLOW NODE N4 TIMESERIES age_ts', plan §2) and so
+            // has one column more than a constant row. Testing arity first
+            // reported "malformed row" for the very spelling the plan
+            // documents, and the deferral this phase owes the user was
+            // unreachable in the only form anyone would write.
+            if (upper(vtok).rfind("TIMESERIES", 0) == 0) {
+                // Z1 (amendment D-Y4) FLIPPED this from a deferral to a
+                // redirect: time-varying ages ARE supported now, through
+                // the pathway that already speaks timeseries.
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] TIMESERIES ages are prescribed as "
+                    "[INFLOWS] rows naming __WATER_AGE__ (amendment D-Y4 / "
+                    "Z1) — this table takes constant hours.");
+                continue;
+            }
+            if (toks.size() != vpos + 1) {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] malformed row: '" + line + "'.");
+                continue;
+            }
+            double hours = 0.0;
+            if (!parse_hours(vtok, hours)) {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] '" + toks[0] + "': '" + vtok +
+                    "' is not an age in hours.");
+                continue;
+            }
+            // D-NS1 (X6): a negative source age is age-volume EXTRACTION —
+            // legal, warned at parse per the subplan §3.1 contract.
+            if (hours < 0.0)
+                ctx.warnings.push_back(
+                    "[WATER_AGE_SOURCES] '" + toks[0] + "' is negative (" +
+                    vtok + " h): the pathway EXTRACTS age-volume (water "
+                    "reads younger). Extraction clamps so age never goes "
+                    "below zero (D-NS1).");
+            const double seconds = hours * 3600.0;
+
+            if (scope == "GLOBAL") {
+                ctx.water_age_config.global_age[src] = seconds;
+            } else if (scope == "NODE") {
+                if (src != static_cast(WaterAgeSource::DWF) &&
+                    src != static_cast(WaterAgeSource::EXTERNAL_INFLOW)) {
+                    errors.push_back(
+                        "[WATER_AGE_SOURCES] NODE scope applies to DWF and "
+                        "EXTERNAL_INFLOW in A1a; '" + toks[0] +
+                        "' takes GLOBAL.");
+                    continue;
+                }
+                const int nd = ctx.node_names.find(toks[2]);
+                if (nd < 0) {
+                    errors.push_back(
+                        "[WATER_AGE_SOURCES] unknown node '" + toks[2] +
+                        "'.");
+                    continue;
+                }
+                bool dup = false;
+                for (std::size_t i = 0;
+                     i < ctx.water_age_config.node_over_source.size(); ++i)
+                    if (ctx.water_age_config.node_over_source[i] == src &&
+                        ctx.water_age_config.node_over_node[i] == nd) {
+                        errors.push_back(
+                            "[WATER_AGE_SOURCES] duplicate NODE row for '" +
+                            toks[0] + "' at '" + toks[2] + "'.");
+                        dup = true;
+                        break;
+                    }
+                if (dup) continue;
+                ctx.water_age_config.node_over_source.push_back(src);
+                ctx.water_age_config.node_over_node.push_back(nd);
+                ctx.water_age_config.node_over_age.push_back(seconds);
+            } else {
+                errors.push_back(
+                    "[WATER_AGE_SOURCES] unknown scope '" + toks[1] +
+                    "' (GLOBAL or NODE in A1a).");
+            }
+        }
+    }
+
+    if (errors.size() != errors_before) {
+        ctx.water_age_config = WaterAgeConfigData{};  // never half-apply
+        return;
+    }
+    ctx.water_age_config.configured = true;
+
+    // Silent-bypass enumeration (lessons 10/20): every configuration in
+    // which this table reaches nothing says so.
+    // (The ON + IGNORE_QUALITY case warns engine-level in SWMMEngine::open
+    // — it applies with or without this component.)
+    if (!ctx.options.water_age) {
+        ctx.warnings.push_back(
+            "A waterage component is configured but [OPTIONS] WATER_AGE is "
+            "OFF — no age is tracked this simulation. Set WATER_AGE ON.");
+    }
+}
+
+}  // namespace
+
+std::string serializeWaterAgeConfig(const SimulationContext& ctx) {
+    const auto& cfg = ctx.water_age_config;
+    // Never applied → DECLINE (empty): the carry-alongside copy runs,
+    // exactly the heat convention. A configured model always renders —
+    // applyWaterAgeSections sets `configured` whenever it applied
+    // cleanly, sections or none.
+    if (!cfg.configured) return {};
+    std::string out = "[WATER_AGE_SOURCES]\n";
+    for (int s = 0; s < static_cast(WaterAgeSource::COUNT_); ++s) {
+        // Zero is the default age and there is NO per-source configured
+        // flag, so an explicit-zero row canonicalises away (physically
+        // identical: source_age falls back to 0). Writing every row
+        // would make a save-as of an untouched model look configured
+        // (lesson 196). Negative rows DO write (D-NS1 extraction).
+        if (cfg.global_age[s] == 0.0) continue;
+        out += source_name(s);
+        out += " GLOBAL ";
+        out += fmt_hours(cfg.global_age[s] / 3600.0);
+        out += "\n";
+    }
+    for (std::size_t i = 0; i < cfg.node_over_source.size(); ++i) {
+        const int nd = cfg.node_over_node[i];
+        if (nd < 0 || nd >= ctx.n_nodes()) continue;
+        out += source_name(cfg.node_over_source[i]);
+        out += " NODE ";
+        out += ctx.node_names.name_of(nd);
+        out += ' ';
+        out += fmt_hours(cfg.node_over_age[i] / 3600.0);
+        out += "\n";
+    }
+    return out;
+}
+
+void registerWaterAgeComponent() {
+    components::ProcessComponentRegistry::instance().register_component(
+        kAgeId,
+        "Water age tracking coordinator (A1a: [WATER_AGE_SOURCES] GLOBAL + "
+        "NODE constant ages)",
+        [](SimulationContext& ctx, const ProcessComponentSpec& /*spec*/,
+           const components::ComponentConfigSections& config,
+           std::vector& errors) {
+            applyWaterAgeSections(ctx, config, errors);
+        },
+        [](const SimulationContext& ctx,
+           const ProcessComponentSpec& /*spec*/) -> std::string {
+            return serializeWaterAgeConfig(ctx);
+        });
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.hpp b/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.hpp
new file mode 100644
index 000000000..cd1954e66
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeComponent.hpp
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeComponent.hpp
+ * @brief The `org.hydrocouple.openswmm.waterage` process component — phase
+ *        A1a: parse `[WATER_AGE_SOURCES]` (`model.age`) into
+ *        SimulationContext::water_age_config.
+ *
+ * @details The coordinator of the water age plan's packaging note: age
+ *          TRANSPORT is embedded in the engines (a reserved species row on
+ *          the ARD mesh in A1a); this component only carries the
+ *          per-source initial-age table so every engine agrees when
+ *          QUALITY_SOLVER flips. `[OPTIONS] WATER_AGE ON` enables tracking
+ *          with all-zero source ages even without this component.
+ *
+ *          A1a scope: GLOBAL rows for all seven sources + NODE overrides
+ *          for DWF/EXTERNAL_INFLOW, VALUE (hours) only. TIMESERIES ages,
+ *          SUBCATCH/EDGE_BC scopes, snow/GW state toggles are later phases
+ *          and refuse with precise deferral errors.
+ *
+ * @see plans/transport/WATER_AGE_TRACKING_PLAN.md §1–§2, §7 A1
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_COMPONENT_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_COMPONENT_HPP
+
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Register `org.hydrocouple.openswmm.waterage` with the process-component
+/// registry (idempotent; called from SWMMEngine::open before resolution).
+void registerWaterAgeComponent();
+
+/// Render [WATER_AGE_SOURCES] from the live config in FILE units
+/// (HOURS, shortest-exact) — the single spelling shared by the
+/// ComponentConfigSave hook and swmm_water_age_save (IO3c), the same
+/// sharing the reactions component has with serializeReactionSystem.
+/// Empty when the component never applied (save DECLINES → the
+/// carry-alongside copy runs).
+std::string serializeWaterAgeConfig(const SimulationContext& ctx);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_COMPONENT_HPP
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.cpp b/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.cpp
new file mode 100644
index 000000000..24d31a186
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.cpp
@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeLegacy.cpp
+ * @brief Phase A1b body — LEGACY CSTR water-age mirror.
+ *
+ * @details Formula provenance, line by line, is the pollutant path in
+ *          QualityRouting.cpp: accumulateLinkLoads (rate convention
+ *          q·value), mixAtNodes (the findStorageQual / findNodeQual
+ *          dispatch, the volume-balance mix with the c_max clamp and the
+ *          dry-node rule), updateLinkQuality (the non-conduit shortcut,
+ *          findSFLinkQual's node1, the DW volume-change inflow and the
+ *          dry-link rule). Those rules are ASKED for through the shared
+ *          predicates in QualityRouting.hpp rather than re-derived here —
+ *          four hand-copies had already drifted apart. Deliberate
+ *          differences, both documented in the header: no evaporation
+ *          factor (plan §8 — evaporation leaves the mean age unchanged)
+ *          and no decay (age has none).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "WaterAgeLegacy.hpp"
+
+#include 
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../quality/NegativeSources.hpp"
+#include "../../../quality/QualityRouting.hpp"
+#include "../../InitialQualitySeeds.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+/// The quality path's own thresholds — one litre and one millimetre, the
+/// numbers legacy qualrout.c routes on. This mirror previously carried a
+/// local 1e-10 under a comment claiming it matched the quality path; it did
+/// not, and the two families dispatched differently as a result.
+using quality::ZERO_DEPTH;
+using quality::LEGACY_ZERO;
+
+/// Routing-thread scratch (the BindingScratch pattern): aged old-state
+/// snapshots and the per-node age-mass accumulator.
+struct AgeScratch {
+    std::vector node_old, link_old, age_in;
+    void ensure(int nn, int nl) {
+        if (node_old.size() != static_cast(nn)) {
+            node_old.assign(static_cast(nn), 0.0);
+            age_in.assign(static_cast(nn), 0.0);
+        }
+        if (link_old.size() != static_cast(nl))
+            link_old.assign(static_cast(nl), 0.0);
+    }
+};
+AgeScratch& scratch() {
+    static AgeScratch s;
+    return s;
+}
+}  // namespace
+
+void routeLegacyAge(SimulationContext& ctx, double dt) {
+    if (!ctx.options.water_age || dt <= 0.0) return;
+    auto& ws = ctx.water_age_state;
+    const int nn = ctx.n_nodes();
+    const int nl = ctx.n_links();
+    if (ws.node_age.size() != static_cast(nn))
+        ws.resize(nn, nl, ctx.n_subcatches());  // A3: keep watershed rows
+
+    auto& sc = scratch();
+    sc.ensure(nn, nl);
+
+    // ---- 0. INITIAL_STATE seeding, once (the ARD engine seeds at its own
+    //         init; here the first routing step is the natural site). An
+    //         unseeded mirror would leave a configured INITIAL_STATE age
+    //         silently inert under LEGACY — the lesson-10 shape. ----------
+    if (!ws.legacy_seeded) {
+        const double a0 = ctx.water_age_config.global_age[static_cast(
+            WaterAgeSource::INITIAL_STATE)];
+        if (a0 > 0.0) {
+            std::fill(ws.node_age.begin(), ws.node_age.end(), a0);
+            std::fill(ws.link_age.begin(), ws.link_age.end(), a0);
+        }
+        // E-A3: per-element [INITIAL_QUALITY] __WATER_AGE__ rows override
+        // the global fill (hotstart wins inside the helper, D-IQ7).
+        applyInitialAgeOverrides(ctx);
+        ws.legacy_seeded = true;
+    }
+
+    // ---- 1. Aging: +dt, then the aged values are this step's "old" state
+    //         (plan §1: age advances by dt then mixes). -------------------
+    for (int i = 0; i < nn; ++i)
+        sc.node_old[static_cast(i)] =
+            ws.node_age[static_cast(i)] + dt;
+    for (int j = 0; j < nl; ++j)
+        sc.link_old[static_cast(j)] =
+            ws.link_age[static_cast(j)] + dt;
+
+    // ---- 2. Age-mass accumulation (accumulateLinkLoads mirror, RATE
+    //         convention) + the loaders' per-source rates. ----------------
+    std::fill(sc.age_in.begin(), sc.age_in.end(), 0.0);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        const double q = std::fabs(ctx.links.flow[uj]);
+        if (q <= 0.0) continue;
+        const int downstream = (ctx.links.flow[uj] >= 0.0)
+                                   ? ctx.links.node2[uj]
+                                   : ctx.links.node1[uj];
+        if (downstream < 0 || downstream >= nn) continue;
+        sc.age_in[static_cast(downstream)] += q * sc.link_old[uj];
+    }
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        if (ui < ws.node_age_vol_in.size())
+            sc.age_in[ui] += ws.node_age_vol_in[ui];
+    }
+
+    // ---- 3. Node mixing (mixAtNodes mirror; NO evap factor — plan §8:
+    //         evaporation leaves the mean age unchanged, and no reaction:
+    //         age has no decay constant). Dispatch, dry-node rule and the
+    //         inflow test are the quality path's, asked rather than
+    //         re-derived. ----------------------------------------------
+    for (int i = 0; i < nn; ++i) {
+        const auto ui = static_cast(i);
+        const double v_old = ctx.nodes.old_volume[ui];
+        const double v_in  = ctx.nodes.qual_vol_in[ui];
+        const double q_in  = (dt > 0.0) ? v_in / dt : 0.0;
+        const double a_old = sc.node_old[ui];
+
+        if (!quality::nodeIsReactor(ctx, i)) {
+            // findNodeQual: no storage volume, so the age is the inflow's.
+            // The gate is legacy's `qNode > ZERO` on the RATE, the same one
+            // the reactor half below uses — not "v_in is non-zero", which
+            // divides residual mass by residual volume.
+            if (q_in > LEGACY_ZERO) {
+                double mass_in = sc.age_in[ui] * dt;
+                if (mass_in < 0.0 && a_old * v_old + mass_in < 0.0) {
+                    quality::bookNegativeAgeClamp(ctx, i);
+                    mass_in = -(a_old * v_old);
+                }
+                ws.node_age[ui] = std::max(mass_in / v_in, 0.0);
+            } else if (ctx.options.outfall_backflow_zero &&
+                       ctx.nodes.type[ui] == NodeType::OUTFALL) {
+                // OUTFALL_BACKFLOW_QUALITY ZERO: a supplying outfall delivers
+                // fresh (age-zero) boundary water — without this, the held
+                // boundary water ages 1:1 forever and every reversal imports
+                // it.
+                ws.node_age[ui] = 0.0;
+            } else {
+                ws.node_age[ui] =
+                    (ctx.nodes.depth[ui] > ZERO_DEPTH) ? a_old : 0.0;
+            }
+            continue;
+        }
+
+        // findStorageQual: a mixed reactor.
+        double mass_in = sc.age_in[ui] * dt;
+        // D-NS1 (X6): a negative age source extracts age·volume, clamped
+        // to what the store holds — counted and warned, not ledgered
+        // (age has no continuity row until A2c). Branch untaken on
+        // non-negative decks.
+        if (mass_in < 0.0 && a_old * v_old + mass_in < 0.0) {
+            quality::bookNegativeAgeClamp(ctx, i);
+            mass_in = -(a_old * v_old);
+        }
+        double a_new;
+        if (q_in <= LEGACY_ZERO) {
+            a_new = a_old;
+        } else {
+            const double a_in  = mass_in / v_in;
+            const double a_max = std::max(a_old, a_in);
+            a_new = (a_old * v_old + mass_in) / (v_old + v_in);
+            a_new = std::min(a_new, a_max);
+        }
+        // A reactor that ends the step empty with nothing coming in holds no
+        // water, so it holds no aged water either — the age analogue of
+        // legacy zeroing the concentration.
+        if (quality::nodeIsDry(ctx, i, q_in)) a_new = 0.0;
+        ws.node_age[ui] = std::max(a_new, 0.0);
+    }
+
+    // ---- 4. Link update (updateLinkQuality mirror; k = 0, no evap). -----
+    const bool is_steady =
+        (ctx.options.routing_model == RoutingModel::STEADY);
+    for (int j = 0; j < nl; ++j) {
+        const auto uj = static_cast(j);
+        // Steady flow draws on node1 unconditionally — legacy
+        // findSFLinkQual never consults the downstream end, even on reverse
+        // flow.
+        const int upstream =
+            is_steady ? ctx.links.node1[uj]
+                      : ((ctx.links.flow[uj] >= 0.0) ? ctx.links.node1[uj]
+                                                     : ctx.links.node2[uj]);
+        if (upstream < 0 || upstream >= nn) continue;
+        const auto un = static_cast(upstream);
+        const double a_up  = ws.node_age[un];
+
+        // A pump, orifice, weir, outlet or DUMMY conduit holds no water, so
+        // it carries the upstream age outright.
+        if (quality::linkTakesUpstreamValue(ctx, j)) {
+            ws.link_age[uj] = std::max(a_up, 0.0);
+            continue;
+        }
+
+        const double v_old = ctx.links.old_volume[uj];
+        const double a_old = sc.link_old[uj];
+
+        double a_new;
+        if (is_steady) {
+            a_new = a_up;
+        } else {
+            const double q_in = quality::conduitMixingInflow(ctx, j, dt);
+            if (q_in <= LEGACY_ZERO) {
+                a_new = a_old;
+            } else {
+                const double v_in  = q_in * dt;
+                const double a_max = std::max(a_old, a_up);
+                a_new = (a_old * v_old + a_up * v_in) / (v_old + v_in);
+                a_new = std::min(a_new, a_max);
+            }
+            // An essentially empty conduit holds no water and so no aged
+            // water — the age analogue of legacy zeroing the concentration.
+            // This engine handed such a link the UPSTREAM age instead, so a
+            // filling conduit reported its inflow's age from the first period
+            // rather than mixing up to it.
+            if (quality::linkIsDry(ctx, j)) a_new = 0.0;
+        }
+        ws.link_age[uj] = std::max(a_new, 0.0);
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.hpp b/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.hpp
new file mode 100644
index 000000000..42085c7ed
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeLegacy.hpp
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeLegacy.hpp
+ * @brief Phase A1b — the LEGACY (CSTR) engine's water-age mirror.
+ *
+ * @details A single-scalar rerun of the CSTR quality stages for the
+ *          reserved age quantity, in the same order the pollutant arrays
+ *          take (water age plan §5, LEGACY row):
+ *
+ *          1. **Aging**: node and link ages advance by dt ("age advances
+ *             by dt then mixes volume-weighted" — plan §1).
+ *          2. **Link-load accumulation** (accumulateLinkLoads mirror):
+ *             each flowing link contributes `q · age_link` to its
+ *             downstream node; the loaders' per-source
+ *             `node_age_vol_in` rates add on top. The VOLUME denominator
+ *             is the same `qual_vol_in` the pollutant stages accumulated
+ *             — this runs at the END of QualitySolver::execute, after
+ *             those totals are complete.
+ *          3. **Node mixing** (mixAtNodes mirror): the identical
+ *             volume-balance formula and max-principle clamp. The
+ *             EVAPORATION concentration factor is deliberately SKIPPED:
+ *             per the plan's §8 proposal, evaporation removes volume at
+ *             the parcel's current age, leaving the volume-intensive
+ *             mean age unchanged.
+ *          4. **Link update** (updateLinkQuality mirror with k = 0 and no
+ *             evap factor): STEADY assigns the upstream node age;
+ *             no-flow retains; zero-volume takes upstream; otherwise the
+ *             legacy volume-balance mix with the DW q_in correction.
+ *
+ *          The mirror reads pollutant-side arrays (flows, volumes,
+ *          qual_vol_in) and writes ONLY water_age_state — WATER_AGE ON
+ *          leaves every pollutant trajectory bit-identical under LEGACY.
+ *
+ * @see plans/transport/WATER_AGE_TRACKING_PLAN.md §5, §7 A1
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_LEGACY_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_LEGACY_HPP
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// One LEGACY age routing step (call at the END of QualitySolver::execute,
+/// after qual_vol_in is fully accumulated). No-op when WATER_AGE is off.
+void routeLegacyAge(SimulationContext& ctx, double dt);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_LEGACY_HPP
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeLid.cpp b/src/engine/transport/components/WaterAgeModule/WaterAgeLid.cpp
new file mode 100644
index 000000000..c0bc23319
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeLid.cpp
@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeLid.cpp
+ * @brief Phase A4 body — water age through the LID layer stack.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "WaterAgeLid.hpp"
+
+#include "../LidLayerCommon.hpp"
+
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../hydrology/LID.hpp"
+#include "../../../hydrology/Runoff.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+
+constexpr int    kAge     = static_cast(LidSpecies::AGE);
+constexpr double kTinyVol = 1.0e-12;  ///< ft of water per unit area
+
+// Donors/donorsFor, layerVolumes and buildOffsets moved to
+// LidLayerCommon at H5b: temperature needs the same topology, and a
+// second copy of an eight-case per-type stack table is exactly the
+// duplication lesson 81 is about.
+
+}  // namespace
+
+void initLidLayerAge(SimulationContext& ctx, const lid::LIDSolver& solver) {
+    if (!ctx.options.water_age) return;
+    auto offsets = buildOffsets(solver);
+    const int units = offsets.empty() ? 0 : offsets.back();
+    if (units <= 0) return;
+
+    auto& st = ctx.lid_layer_state;
+    // H5b: ensureSized, not resize. The block is now shared with the heat
+    // track, and whichever capability initialises first must not wipe the
+    // other's row.
+    st.ensureSized(units, static_cast(LidSpecies::COUNT_), offsets);
+
+    // Seed the volumes a unit already holds, so the first step mixes against
+    // real water rather than against zero. INITIAL_STATE is the age of water
+    // already in the model, the same source A1a and A3 seed from.
+    const double a_init = ctx.water_age_config.global_age[
+        static_cast(WaterAgeSource::INITIAL_STATE)];
+    for (int t = 0; t < solver.numGroups(); ++t) {
+        const auto& g = solver.group(t);
+        for (int u = 0; u < g.count; ++u) {
+            const auto ui   = static_cast(u);
+            const int  flat = offsets[static_cast(t)] + u;
+            double v[kNL];
+            layerVolumes(g, ui, v);
+            for (int k = 0; k < kNL; ++k) {
+                const auto idx = static_cast(flat) * kNL +
+                                 static_cast(k);
+                st.vol_prev[idx] = v[k];
+                if (v[k] > kTinyVol)
+                    st.value[st.layer_index(flat, static_cast(k),
+                                            kAge)] = a_init;
+            }
+        }
+    }
+}
+
+void setLidInflowAge(SimulationContext& ctx, int type_index, int unit,
+                     int subcatch, double rain_rate, double q_imperv,
+                     double q_perv, double q_runon, double lid_area) {
+    auto& st = ctx.lid_layer_state;
+    if (!ctx.options.water_age || !st.active()) return;
+    const auto ut = static_cast(type_index);
+    if (ut + 1 >= st.group_offset.size()) return;
+    const int flat = st.group_offset[ut] + unit;
+    if (flat < 0 || flat >= st.n_units) return;
+
+    // The unit's inflow is assembled from four sources with known rates, all
+    // in one place — so the age is a direct flow-weighted mean rather than
+    // the scattered-donor accumulator A3's run-on needed. Rates here are
+    // volumes per unit time over the LID footprint (ft3/s): `rain_rate` is a
+    // depth rate, the rest are already CFS.
+    const double q_rain = rain_rate * lid_area;
+
+    const double a_rain = ctx.water_age_config.global_age[
+        static_cast(WaterAgeSource::RAINFALL)];
+
+    // Everything the unit captures from the surface around it — impervious
+    // runoff, pervious runoff, and whole-subcatchment run-on — is the same
+    // water A3 publishes as `subcatch_runoff_age`, so that is what it
+    // arrives at. Reconstructing an impervious mean from the raw
+    // `subarea_age` rows instead looked more precise and was wrong: a
+    // subarea can be shedding while its END-of-step stored volume is zero,
+    // and the untouched zero of a dry row then drags the mix BELOW the
+    // youngest thing entering the model. Measured on the composition deck:
+    // 3.759 h of arriving water under 4 h rain, with no source younger than
+    // 4 h anywhere. A3 already resolves exactly this weighting for the
+    // outlet node, so using its answer keeps the LID and the node
+    // consistent as well as correct.
+    const auto& ws = ctx.water_age_state;
+    const int   sc = subcatch;
+    const double a_surface =
+        (sc >= 0 && static_cast(sc) < ws.subcatch_runoff_age.size() &&
+         ws.subcatch_runoff_age[static_cast(sc)] > 0.0)
+            ? ws.subcatch_runoff_age[static_cast(sc)]
+            : a_rain;
+
+    const double q_surface = q_imperv + q_perv + q_runon;
+    const double q_tot = q_rain + q_surface;
+    const double age = (q_tot > 0.0)
+        ? (q_rain * a_rain + q_surface * a_surface) / q_tot
+        : a_rain;
+    st.inflow_value[static_cast(flat) *
+                        static_cast(st.n_species) +
+                    static_cast(kAge)] = age;
+}
+
+void routeLidLayerAge(SimulationContext& ctx, const lid::LIDSolver& solver,
+                      double dt) {
+    auto& st = ctx.lid_layer_state;
+    if (!ctx.options.water_age || !st.active() || !(dt > 0.0)) return;
+
+    for (int t = 0; t < solver.numGroups(); ++t) {
+        const auto& g = solver.group(t);
+        if (g.count == 0) continue;
+        const auto ut = static_cast(t);
+        if (ut + 1 >= st.group_offset.size()) continue;
+
+        for (int u = 0; u < g.count; ++u) {
+            const auto ui   = static_cast(u);
+            const int  flat = st.group_offset[ut] + u;
+            if (flat < 0 || flat >= st.n_units) continue;
+            const auto uf = static_cast(flat);
+
+            const Donors d = donorsFor(g.type, g.soil_thick[ui] > 0.0);
+            const int donor[kNL] = {d.surface, d.pavement, d.soil, d.storage};
+            const double in_rate[kNL] = {g.in_surf[ui], g.in_pave[ui],
+                                         g.in_soil[ui], g.in_stor[ui]};
+            double v_new[kNL];
+            layerVolumes(g, ui, v_new);
+
+            const double a_ext =
+                st.inflow_value[uf * static_cast(st.n_species) +
+                                static_cast(kAge)];
+
+            // Read the donors' OLD ages before any layer is overwritten:
+            // percolation carries the water the donor held at the start of
+            // the step, not the value it ends with. Updating in place would
+            // let a parcel fall through the whole stack in one step.
+            double a_old[kNL];
+            for (int k = 0; k < kNL; ++k)
+                a_old[k] = st.value[st.layer_index(flat,
+                                                   static_cast(k),
+                                                   kAge)];
+
+            for (int k = 0; k < kNL; ++k) {
+                const auto vidx = uf * kNL + static_cast(k);
+                const double v_old = st.vol_prev[vidx];
+                const double v_in  = std::max(0.0, in_rate[k]) * dt;
+
+                // A layer this TYPE does not have carries no age, whatever
+                // the SoA happens to hold in its slot. A vegetative swale
+                // has soil parameters — that is where its infiltration
+                // conductivity lives — but no soil LAYER: water that
+                // infiltrates leaves for native ground. Without this the
+                // swale's soil row would sit on a nonzero `soil_moist`,
+                // receive nothing, and climb to the elapsed run time.
+                //
+                // A layer that holds nothing AND receives nothing is the
+                // same case for a different reason: no water, no age.
+                if (donor[k] == kAbsent ||
+                    (v_old <= kTinyVol && v_in <= kTinyVol)) {
+                    st.value[st.layer_index(flat, static_cast(k),
+                                            kAge)] = 0.0;
+                    st.vol_prev[vidx] = v_new[k];
+                    continue;
+                }
+
+                // 1. What is held ages.
+                double a = a_old[k] + dt;
+
+                // 2. What arrived mixes in, by GROSS inflow volume. The
+                //    solver publishes the rate, so this is exact — there is
+                //    no need for the net change in storage, which is zero
+                //    for a layer passing water straight through and was how
+                //    A3 came to report elapsed time instead of age.
+                if (v_in > kTinyVol) {
+                    const double a_in =
+                        (donor[k] == kExternal) ? a_ext
+                        : (donor[k] >= 0)       ? a_old[donor[k]] + dt
+                                                : a_ext;
+                    const double den = v_old + v_in;
+                    a = (den > kTinyVol) ? (a * v_old + a_in * v_in) / den
+                                         : a_in;
+                }
+
+                // 3. What leaves does so at the layer's own age, so nothing
+                //    more is needed — that is why the outflow rates the
+                //    solver does not publish are not required.
+                st.value[st.layer_index(flat, static_cast(k),
+                                        kAge)] = std::max(a, 0.0);
+                st.vol_prev[vidx] = v_new[k];
+            }
+
+            // The underdrain draws from the storage layer (decision,
+            // 2026-08-18) — `getDrainRate` reads `stor_depth`. Roof
+            // disconnection has no storage layer: its "drain" is a routed
+            // fraction of the roof outflow, so it leaves at the surface age.
+            const bool from_surface = (g.type == lid::LIDType::ROOF_DISCON);
+            const auto src = from_surface ? LidLayer::SURFACE
+                                          : LidLayer::STORAGE;
+            st.drain_value[uf * static_cast(st.n_species) +
+                           static_cast(kAge)] =
+                st.value[st.layer_index(flat, src, kAge)];
+        }
+    }
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeLid.hpp b/src/engine/transport/components/WaterAgeModule/WaterAgeLid.hpp
new file mode 100644
index 000000000..61d5300c2
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeLid.hpp
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeLid.hpp
+ * @brief Phase A4 — water age through the LID layer stack.
+ *
+ * @details Each layer of each LID unit is a complete-mix tank: what it holds
+ *          ages by `dt`, what arrives mixes in by volume, and what leaves —
+ *          percolation to the layer below, evaporation, exfiltration, the
+ *          underdrain — leaves at the layer's own age. **Only the inflow is
+ *          needed**, which is the whole reason this phase does not repeat
+ *          A3's defect.
+ *
+ * @par Where the inflow rates come from
+ *      Every `batch*Flux` routine already computed each layer's inflow as a
+ *      local (`soil_infil`, `soil_perc`, `pavePerc`, `storageInflow`, ...);
+ *      A4 publishes them as `LIDGroupSoA::in_surf/in_pave/in_soil/in_stor`,
+ *      written after every clamp. They are **not** `f_old_*`: `f_old_surf`
+ *      is the Modified Puls net `dx/dt` of the surface layer and
+ *      `f_old_soil/stor/pave` are allocated and never written. A net rate of
+ *      change is precisely what made A3 report elapsed time rather than age,
+ *      so the survey claim that those four fields were inter-layer fluxes
+ *      does not hold and is not what this uses.
+ *
+ * @par Which layer feeds which
+ *      Resolved from an explicit per-TYPE table rather than inferred, because
+ *      the stacks genuinely differ and the solver itself is written one
+ *      routine per type. The single conditional is permeable pavement, whose
+ *      storage receives from the soil when there is one and from the pavement
+ *      when there is not — mirroring the solver's own `storageInflow_local`.
+ *
+ * @par Not in this phase
+ *      Hotstart persistence. LID layer depths are not in the hot start file
+ *      (no `surf_depth`/`soil_moist`/`stor_depth`/`pave_depth` anywhere in
+ *      `HotStartManager.cpp`), so a restored age would be a mean over a
+ *      volume that was not restored — A3's reasoning, verified rather than
+ *      inherited.
+ *
+ *      Surface overflow returns to the subcatchment, and its age is the
+ *      surface layer's, but it is not fed back into A3's subarea ages here.
+ *
+ * @see plans/transport/WATER_AGE_TRACKING_PLAN.md §7 A4
+ * @see plans/transport/A4_IMPLEMENTATION_BRIEF_2026-08-17.md
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_WATERAGELID_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_WATERAGELID_HPP
+
+namespace openswmm {
+struct SimulationContext;
+namespace lid { class LIDSolver; }
+}  // namespace openswmm
+
+namespace openswmm::transport {
+
+/// Size the per-layer block against the model's LID units and seed the
+/// layers that already hold water at t = 0. Idempotent; safe to call once
+/// the LID manager has built its groups.
+void initLidLayerAge(SimulationContext& ctx, const lid::LIDSolver& solver);
+
+/// Flow-weighted age of the water arriving at each LID unit this step,
+/// stored into `ctx.lid_layer_state.inflow_value`. Called where
+/// `LIDGroupSoA::inflow` is assembled, because that is the only place the
+/// contributing rates (rain, captured impervious and pervious runoff,
+/// whole-subcatchment run-on) exist together.
+void setLidInflowAge(SimulationContext& ctx, int type_index, int unit,
+                     int subcatch, double rain_rate, double q_imperv,
+                     double q_perv, double q_runon, double lid_area);
+
+/// Advance the per-layer ages one runoff step, after `LIDSolver::execute`.
+void routeLidLayerAge(SimulationContext& ctx, const lid::LIDSolver& solver,
+                      double dt);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_WATERAGELID_HPP
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.cpp b/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.cpp
new file mode 100644
index 000000000..cdd17dcfa
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.cpp
@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeWatershed.cpp
+ * @brief Phase A3 body — subcatchment surface water age.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "WaterAgeWatershed.hpp"
+
+#include "../WatershedCommon.hpp"
+
+#include 
+#include 
+
+#include "../../../core/SimulationContext.hpp"
+#include "../../../hydrology/Runoff.hpp"
+
+namespace openswmm::transport {
+
+namespace {
+constexpr int kNSub = static_cast(SubArea::COUNT_);
+constexpr double kTinyVol = 1.0e-12;  ///< ft³
+}  // namespace
+
+void addRunonAge(SimulationContext& ctx, int donor_sc, int receiver_sc,
+                 double q) {
+    if (!ctx.options.water_age) return;
+    auto& ws = ctx.water_age_state;
+    const auto ud = static_cast(donor_sc);
+    const auto ur = static_cast(receiver_sc);
+    if (ud >= ws.subcatch_runoff_age.size() ||
+        ur >= ws.subcatch_runon_age_vol_in.size())
+        return;
+    // The RATE convention the loaders use everywhere: q · age, integrated by
+    // the consumer. Run-on arrives at the age the donor's runoff left at.
+    ws.subcatch_runon_age_vol_in[ur] += q * ws.subcatch_runoff_age[ud];
+}
+
+void routeSubcatchmentAge(SimulationContext& ctx,
+                          const runoff::RunoffSoA& soa, double dt) {
+    if (!ctx.options.water_age || dt <= 0.0) return;
+
+    auto& ws = ctx.water_age_state;
+    const int nsc = ctx.n_subcatches();
+    if (nsc <= 0) return;
+    const auto want = static_cast(nsc) *
+                      static_cast(kNSub);
+    if (ws.subarea_age.size() != want)
+        ws.resize(ctx.n_nodes(), ctx.n_links(), nsc);
+
+    // Age of water arriving from the sky. RAINFALL is the pathway the
+    // wet-weather loader already uses for washoff, so the same configured
+    // source age governs both — one table, one meaning.
+    const double a_rain = ctx.water_age_config.global_age[
+        static_cast(WaterAgeSource::RAINFALL)];
+
+    for (int i = 0; i < nsc && i < static_cast(soa.area.size()); ++i) {
+        const auto ui = static_cast(i);
+        const double area = soa.area[ui];
+        const double fi   = soa.imperv_pct[ui];
+        const double fp   = 1.0 - fi;
+        const double f0   = soa.frac_imperv0[ui];
+        const double f1   = soa.frac_imperv1[ui];
+
+        // Area-weighted subarea volumes, the same expression the runoff
+        // mass balance uses (SWMMEngine.cpp:3664-3666).
+        const double frac[kNSub] = {f0, f1, fp};
+        const double depth[kNSub] = {soa.depth_imperv0[ui],
+                                     soa.depth_imperv1[ui],
+                                     soa.depth_perv[ui]};
+
+        // Run-on arrives spread over the whole subcatchment as extra
+        // precipitation (Runoff.cpp:331-333), so it mixes into every
+        // subarea in proportion to that subarea's share of the inflow.
+        const double runon_rate =
+            (ui < ws.subcatch_runon_age_vol_in.size() &&
+             ui < ctx.subcatches.runon_inflow.size())
+                ? ctx.subcatches.runon_inflow[ui]
+                : 0.0;
+        const double runon_age =
+            (runon_rate > 0.0 && ui < ws.subcatch_runon_age_vol_in.size())
+                ? ws.subcatch_runon_age_vol_in[ui] / runon_rate
+                : 0.0;
+
+        // Run-on spreads over the whole subcatchment, so its depth rate is
+        // the same for every subarea. The PRECIPITATION rate is not — see
+        // below.
+        const double runon_depth_rate = (area > 0.0) ? runon_rate / area : 0.0;
+
+        double out_num = 0.0, out_den = 0.0;
+        for (int k = 0; k < kNSub; ++k) {
+            const auto idx = ui * static_cast(kNSub) +
+                             static_cast(k);
+            const double v_new = depth[k] * frac[k] * area;
+            const double v_old = ws.subarea_vol_prev[idx];
+
+            // S1: the water that ACTUALLY reached THIS subarea. On a bare
+            // subcatchment that is the gage rate; under a snowpack it is
+            // `imelt + rain·(1 − asc)`, which differs BETWEEN subareas — the
+            // impervious value is an area-weighted blend over plowable and
+            // non-plowable fractions, the pervious one is not. This read used
+            // to sit outside the loop as a single scalar, which was wrong
+            // even where the total was right.
+            const double rain_rate = arrivingPrecipRate(ctx, ui, k);
+            // S2b: and the water that arrived is not all the same AGE. Under
+            // a pack it is meltwater carrying the pack's residence time plus
+            // rain through the snow-free fraction at the configured source
+            // age; `arrivingPrecipAge` blends them on the same fraction the
+            // heat track uses. On a bare subcatchment it returns `a_rain`
+            // exactly, so this is inert everywhere there is no pack.
+            const double a_precip = arrivingPrecipAge(ctx, ui, k);
+            const double in_rate = rain_rate + runon_depth_rate;
+
+            // Arriving water is precipitation and run-on MIXED, flow-
+            // weighted. Rain routinely outweighs run-on by orders of
+            // magnitude — on the gate deck's cascade it is 10.08 cfs against
+            // 0.027 — so treating the arrival as pure run-on whenever any
+            // run-on exists would hand the whole inflow the donor's age.
+            const double a_in = (in_rate > 0.0)
+                ? (rain_rate * a_precip + runon_depth_rate * runon_age) / in_rate
+                : a_precip;
+
+            // 1. Age what was already there.
+            double a = ws.subarea_age[idx] + dt;
+
+            // 2. Mix in what arrived — the GROSS inflow, not the net gain.
+            //    A subarea shedding as fast as it fills has v_new == v_old
+            //    and so no net gain at all, which is the ordinary state of
+            //    an impervious surface during a storm: a net-gain mixing
+            //    volume never admits the rain pouring through it, and the
+            //    age degenerates into the time since the surface first
+            //    wetted. Measured on a 100% impervious, zero-depression
+            //    deck under sustained rain: 0.88592 h against a residence
+            //    time V/Q of 0.14062 h. Complete-mix is the right model
+            //    here — outflow leaves at the subarea's own age, so only
+            //    the INFLOW is needed, and the solver already publishes it;
+            //    the same deck then reads 0.14022 h.
+            const double v_in = in_rate * frac[k] * area * dt;
+            if (v_in > kTinyVol) {
+                const double denom = v_old + v_in;
+                a = (denom > kTinyVol) ? (a * v_old + a_in * v_in) / denom
+                                       : a_in;
+            }
+            ws.subarea_age[idx]      = std::max(a, 0.0);
+            ws.subarea_vol_prev[idx] = v_new;
+
+            // 3. Runoff leaves at the volume-weighted mean of the subareas
+            //    that hold water. A subarea with nothing on it contributes
+            //    no water and therefore no age — weighting by area alone
+            //    would let a dry pervious surface drag the runoff age.
+            if (v_new > kTinyVol) {
+                out_num += a * v_new;
+                out_den += v_new;
+            }
+        }
+        if (ui < ws.subcatch_runoff_age.size())
+            ws.subcatch_runoff_age[ui] =
+                (out_den > kTinyVol) ? out_num / out_den : a_rain;
+    }
+
+    // The run-on accumulator is zeroed by SWMMEngine::assembleRunon at the
+    // start of the next runoff step, beside the flow it describes.
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.hpp b/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.hpp
new file mode 100644
index 000000000..ac096a8b4
--- /dev/null
+++ b/src/engine/transport/components/WaterAgeModule/WaterAgeWatershed.hpp
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WaterAgeWatershed.hpp
+ * @brief Phase A3 — water age on subcatchment surfaces.
+ *
+ * @details Each subcatchment carries THREE ages, one per ponded subarea
+ *          (`IMPERV0`, `IMPERV1`, `PERV`), mirroring the RunoffSolver's own
+ *          `depth_imperv0/1/perv`. Per-subarea rather than lumped is a user
+ *          decision (2026-08-17): impervious water is systematically younger
+ *          than pervious, and the depths are already separate, so lumping
+ *          would discard information the state already has.
+ *
+ *          Per step, per subarea: **age +dt, then mix with what arrived**,
+ *          volume-weighted — the same order the node/link mirror uses.
+ *          Water leaving as runoff carries the volume-weighted mean of the
+ *          contributing subareas, and THAT is what reaches the outlet node
+ *          and what run-on hands to a downstream subcatchment.
+ *
+ * @par Why the mixing volume is the GROSS inflow
+ *      A subarea shedding as fast as it fills has `v_new == v_old`, which
+ *      is the ordinary state of an impervious surface during a storm. A
+ *      mixing volume taken as the NET gain, `max(0, v_new − v_old)`, is
+ *      therefore zero exactly when rain is pouring through the surface, and
+ *      the age stops being a residence time and becomes the elapsed time
+ *      since the surface first wetted. Measured on a 100 % impervious,
+ *      zero-depression deck under sustained 2 in/h rain (V = 5104.5 ft³,
+ *      Q = 10.08 cfs, so V/Q = 0.14062 h): a net-gain mixing volume reports
+ *      **0.88592 h**, 6.3x too old.
+ *
+ *      Only the INFLOW is needed to avoid this. Complete-mix means outflow
+ *      leaves at the subarea's own age, so the outflow never enters the
+ *      update — and the inflow the solver applied is already published:
+ *      `ctx.subcatches.rainfall` (ft/s, written by `Runoff.cpp:295`) plus
+ *      run-on, which the solver spreads over the whole area as extra
+ *      precipitation (`Runoff.cpp:331-333`). So
+ *      `v_in = (rain + runon/area) · frac · area · dt`, and the same deck
+ *      returns **0.14022 h** against the analytic 0.14062 h — 0.3 %.
+ *
+ * @par What this still approximates
+ *      With a snowpack active the solver substitutes `snow_net_imperv/perv`
+ *      for rainfall per subarea (`Runoff.cpp:543-548`), and inter-subarea
+ *      routing (`RouteTo IMPERV`/`PERV`) moves water between subareas
+ *      without appearing in either term. Both leave the arriving volume
+ *      mis-stated; neither is exercised by a `RouteTo OUTLET`, snow-free
+ *      deck. Runoff also leaves at the **stored-volume** weighted mean of
+ *      the subareas rather than at their outflow-weighted mean, because
+ *      per-subarea outflow is genuinely not published — a depression-storage
+ *      subarea therefore counts toward the departing age in proportion to
+ *      what it holds, not what it sheds.
+ *
+ * @par Not in this phase
+ *      Hotstart persistence (user decision: defer). The subarea depths are
+ *      not in the hotstart either, so an age restored over a volume that
+ *      was not restored would be a mean of nothing.
+ *
+ * @see plans/transport/WATER_AGE_TRACKING_PLAN.md §3, §7 A3
+ * @see plans/transport/A3_SCOPING_2026-08-17.md
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_WATERSHED_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_WATERSHED_HPP
+
+namespace openswmm {
+struct SimulationContext;
+namespace runoff { struct RunoffSoA; }
+}
+
+namespace openswmm::transport {
+
+/// One runoff-step update of the subarea ages and the published runoff age.
+/// Call immediately AFTER the runoff solver has stepped, so the depths are
+/// this step's. No-op when WATER_AGE is off.
+void routeSubcatchmentAge(SimulationContext& ctx,
+                          const runoff::RunoffSoA& soa, double dt);
+
+/// Accumulate run-on age-volume from a donor subcatchment to its receiver.
+/// Called from the run-on assembly beside the flow it mirrors.
+void addRunonAge(SimulationContext& ctx, int donor_sc, int receiver_sc,
+                 double q);
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_WATER_AGE_WATERSHED_HPP
diff --git a/src/engine/transport/components/WatershedCommon.cpp b/src/engine/transport/components/WatershedCommon.cpp
new file mode 100644
index 000000000..fea4e8f52
--- /dev/null
+++ b/src/engine/transport/components/WatershedCommon.cpp
@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WatershedCommon.cpp
+ * @brief The arriving-water rate at a subarea (S1 — snow mixing volume).
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "WatershedCommon.hpp"
+
+#include "../../core/SimulationContext.hpp"
+
+namespace openswmm::transport {
+
+double arrivingPrecipRate(const SimulationContext& ctx, std::size_t ui,
+                          int subarea) noexcept {
+    const double gage = (ui < ctx.subcatches.rainfall.size())
+                            ? ctx.subcatches.rainfall[ui]
+                            : 0.0;
+
+    // The IGNORE_SNOWMELT fallback is not redundant, though a deck cannot
+    // show it: for such a DECK the whole snow block is skipped and
+    // `snow_net_*` never leave the sentinel, so the test below answers the
+    // same way. It earns its place when the flag is raised on a run whose
+    // pack has already published a rate — the stale arrays Runoff.cpp:551
+    // calls harmless — which is reachable because IGNORE_SNOWMELT is
+    // settable at runtime (openswmm_model_impl.cpp:1189).
+    if (ctx.options.ignore_snow_melt) return gage;
+    if (ui >= ctx.subcatches.snowpack.size()) return gage;
+    // This one IS redundant, and measurably so: deleting it fails nothing,
+    // because `snow_net_*` are written only for subcatchments with a pack
+    // (SWMMEngine.cpp:1595) and initialise to -1.0, so the sentinel test
+    // below already answers "no pack" correctly. Kept because it mirrors the
+    // solver's own two-part guard (Runoff.cpp:548) and would be the thing
+    // that saves this function if those arrays ever became unconditional.
+    if (ctx.subcatches.snowpack[ui] < 0) return gage;
+
+    // `>= 0.0`, not `> 0.0`: a pack that melted nothing this step publishes a
+    // genuine 0.0, and only the -1.0 sentinel means "no pack". This mirrors
+    // Runoff.cpp:551-552 exactly — the solver's own test — so the transport
+    // mixing volume and the hydrology cannot disagree about whether the pack
+    // is in charge.
+    const bool perv = (subarea == kSubPERV);
+    const auto& src = perv ? ctx.subcatches.snow_net_perv
+                           : ctx.subcatches.snow_net_imperv;
+    if (ui >= src.size()) return gage;
+    const double net = src[ui];
+    return (net >= 0.0) ? net : gage;
+}
+
+double arrivingMeltFraction(const SimulationContext& ctx, std::size_t ui,
+                            int subarea) noexcept {
+    if (ctx.options.ignore_snow_melt) return 0.0;
+    if (ui >= ctx.subcatches.snowpack.size()) return 0.0;
+    if (ctx.subcatches.snowpack[ui] < 0) return 0.0;
+
+    const bool perv = (subarea == kSubPERV);
+    const auto& net_v  = perv ? ctx.subcatches.snow_net_perv
+                              : ctx.subcatches.snow_net_imperv;
+    const auto& melt_v = perv ? ctx.subcatches.snow_melt_perv
+                              : ctx.subcatches.snow_melt_imperv;
+    if (ui >= net_v.size() || ui >= melt_v.size()) return 0.0;
+
+    const double net  = net_v[ui];
+    const double melt = melt_v[ui];
+    // The -1.0 sentinel on either array means the pack published nothing.
+    if (!(net > 0.0) || !(melt >= 0.0)) return 0.0;
+    // Clamped rather than trusted: `net` and `melt` are blended through the
+    // same area weights, so melt <= net holds by construction — but a future
+    // change to one blend and not the other would otherwise hand a caller a
+    // fraction above 1 and silently invert a mixture.
+    const double f = melt / net;
+    return (f < 0.0) ? 0.0 : (f > 1.0 ? 1.0 : f);
+}
+
+double arrivingPrecipTemperature(const SimulationContext& ctx, std::size_t ui,
+                                 int subarea) noexcept {
+    const double t_rain = ctx.heat_config.global_temp[
+        static_cast(HeatSource::RAINFALL)];
+    const double f = arrivingMeltFraction(ctx, ui, subarea);
+    if (f <= 0.0) return t_rain;
+    return (1.0 - f) * t_rain + f * kMeltwaterTempC;
+}
+
+double arrivingPrecipAge(const SimulationContext& ctx, std::size_t ui,
+                         int subarea) noexcept {
+    const double a_rain = ctx.water_age_config.global_age[
+        static_cast(WaterAgeSource::RAINFALL)];
+    // The SAME fraction the temperature blend uses. See the header.
+    const double f = arrivingMeltFraction(ctx, ui, subarea);
+    if (f <= 0.0) return a_rain;
+
+    const bool perv = (subarea == kSubPERV);
+    const auto& age_v = perv ? ctx.subcatches.snow_melt_age_perv
+                             : ctx.subcatches.snow_melt_age_imperv;
+    if (ui >= age_v.size()) return a_rain;
+    const double a_pack = age_v[ui];
+    // The -1.0 sentinel means the pack published no age. Falling back to the
+    // rain age rather than to 0 is deliberate: 0 is a REAL age -- the age of
+    // water that fell this instant -- so using it as a "missing" marker would
+    // make an unpublished pack look like the freshest water in the model.
+    // A4's dry-element column has the same shape and H1 left it open.
+    if (!(a_pack >= 0.0)) return a_rain;
+
+    return (1.0 - f) * a_rain + f * a_pack;
+}
+
+}  // namespace openswmm::transport
diff --git a/src/engine/transport/components/WatershedCommon.hpp b/src/engine/transport/components/WatershedCommon.hpp
new file mode 100644
index 000000000..0f52c1b3c
--- /dev/null
+++ b/src/engine/transport/components/WatershedCommon.hpp
@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file WatershedCommon.hpp
+ * @brief The arriving-water rate at a subarea — shared by every species
+ *        track on the watershed surface.
+ *
+ * @details A3 and H5a each read `ctx.subcatches.rainfall` as "how much water
+ *          landed on this subarea this step". On a subcatchment with a
+ *          SNOWPACK that is the wrong field, and wrong in two directions at
+ *          once. This header is the one place that knows which field is
+ *          right, so the two tracks cannot drift apart on it — the
+ *          `LidLayerCommon` move, for the same reason.
+ *
+ * @see plans/transport/SNOW_MIXING_VOLUME_FINDING_2026-08-20.md
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_WATERSHED_COMMON_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_WATERSHED_COMMON_HPP
+
+#include 
+
+namespace openswmm {
+struct SimulationContext;
+}
+
+namespace openswmm::transport {
+
+/// Subarea ordering shared by `SubArea` (A3) and `HeatSubArea` (H5a). Both
+/// enums are deliberately separate types; this is the ordinal they agree on.
+constexpr int kSubIMPERV0 = 0;
+constexpr int kSubIMPERV1 = 1;
+constexpr int kSubPERV    = 2;
+
+/**
+ * @brief Net precipitation actually reaching one subarea this step [ft/s].
+ *
+ * @details **This is the mixing volume, and it is not always the rainfall.**
+ *
+ *          `ctx.subcatches.rainfall` is set once, at `Runoff.cpp:294-295`,
+ *          to `rain + SNOWFALL`, and never updated. On a subcatchment with a
+ *          snowpack the runoff solver does not use it: it uses
+ *          `snow_net_imperv` for IMPERV0/IMPERV1 and `snow_net_perv` for
+ *          PERV (`Runoff.cpp:548-552`), each built as
+ *          `imelt + rainfall·(1 − asc)` — **melt, plus the rain falling on
+ *          the snow-free fraction** (`SWMMEngine.cpp:1608-1616`).
+ *
+ *          Reading the rainfall field on such a deck is wrong twice over:
+ *          - **snowfall is counted as arriving liquid**, so water being
+ *            stored in the pack is mixed into the surface as though it had
+ *            landed, and
+ *          - **snowmelt is not counted at all**, so the water that genuinely
+ *            arrives is invisible to the mixing volume and the surface ages
+ *            as if nothing arrived.
+ *
+ *          The second of those is A3's own net-gain failure (lessons 64, 68)
+ *          reappearing through a different field: the mixing volume is again
+ *          not the arriving volume. They do not cancel — they are displaced
+ *          by the whole residence time of the pack, which is precisely the
+ *          quantity a snow-aware age model exists to measure.
+ *
+ * @par The `-1.0` sentinel is the whole guard
+ *      `snow_net_*` initialise to **-1.0** (`SubcatchData.hpp:642`), and the
+ *      solver's own test is `>= 0.0` (`Runoff.cpp:551-552`). A subcatchment
+ *      with a pack but no melt this step publishes 0.0, which is a real
+ *      rate; only the negative sentinel means "no pack, use the gage". This
+ *      function mirrors that test exactly rather than inventing its own.
+ *
+ * @par IGNORE_SNOWMELT
+ *      Falls back to the gage value, matching `Runoff.cpp:548`'s
+ *      `!ctx.options.ignore_snow_melt` and legacy `subcatch.c:784`.
+ *
+ * @param subarea One of `kSubIMPERV0` / `kSubIMPERV1` / `kSubPERV`.
+ */
+double arrivingPrecipRate(const SimulationContext& ctx, std::size_t ui,
+                          int subarea) noexcept;
+
+/**
+ * @brief Fraction of the arriving water that is MELTWATER, in [0, 1].
+ *
+ * @details Under a pack the arriving water is two different waters:
+ *          meltwater, and rain that reached the ground through the snow-free
+ *          fraction. `arrivingPrecipRate` returns their sum, and a sum
+ *          cannot say what either is worth — this is the split.
+ *
+ *          Returns **0** wherever there is no pack, `IGNORE_SNOWMELT` is on,
+ *          or nothing arrived, so a caller can blend unconditionally and a
+ *          bare deck is bit-identical to its pre-S2 behaviour.
+ */
+double arrivingMeltFraction(const SimulationContext& ctx, std::size_t ui,
+                            int subarea) noexcept;
+
+/**
+ * @brief Temperature of the water arriving at one subarea [°C] (S2).
+ *
+ * @details **Meltwater is at 0 °C essentially by definition** — that is what
+ *          melting means — so the arriving temperature is the melt fraction
+ *          blended against the configured `HeatSource::RAINFALL` value:
+ *
+ *          `T = (1 − f)·T_rain + f·0`
+ *
+ *          On a winter deck this is not a small approximation to make: it is
+ *          the difference between a stream fed by snowmelt and one fed by
+ *          rain. Unlike the age half, it needs **no pack state at all** —
+ *          the freezing point is not something the pack has to remember.
+ */
+double arrivingPrecipTemperature(const SimulationContext& ctx, std::size_t ui,
+                                 int subarea) noexcept;
+
+/**
+ * @brief Water age of the water arriving at one subarea [seconds] (S2b).
+ *
+ * @details The age analogue of `arrivingPrecipTemperature`, and **it uses
+ *          the same `arrivingMeltFraction`** — not an equivalent expression,
+ *          the same call. Under a pack the arriving water is meltwater
+ *          carrying the pack's residence time plus rain that reached the
+ *          ground through the snow-free fraction carrying the configured
+ *          `WaterAgeSource::RAINFALL` age:
+ *
+ *          `a = (1 − f)·a_rain + f·a_pack`
+ *
+ *          If the two tracks ever computed `f` separately they could drift,
+ *          and the drift would be invisible: both answers stay inside their
+ *          brackets, and only a deck comparing arriving age against arriving
+ *          temperature could see it. One call is what makes that
+ *          unrepresentable.
+ *
+ * @par Where a_pack comes from
+ *      `snow_melt_age_*`, published beside `snow_melt_*` under the identical
+ *      area blend. **It is NOT the age of the water still in the pack** — a
+ *      pack that empties this step publishes the age its water HAD, which
+ *      the remaining-water age cannot express because there is none.
+ *
+ * @par The no-pack answer
+ *      Returns the configured RAINFALL age wherever there is no pack,
+ *      `IGNORE_SNOWMELT` is on, nothing arrived, or the pack published no
+ *      melt — so a caller blends unconditionally and a bare deck is
+ *      bit-identical to its pre-S2b behaviour.
+ */
+double arrivingPrecipAge(const SimulationContext& ctx, std::size_t ui,
+                         int subarea) noexcept;
+
+/// The temperature meltwater leaves a pack at, °C. Zero, and named rather
+/// than written as a literal so a gate can assert against the constant the
+/// code uses instead of against a number a reader hopes it uses.
+inline constexpr double kMeltwaterTempC = 0.0;
+
+}  // namespace openswmm::transport
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_WATERSHED_COMMON_HPP
diff --git a/src/engine/transport/fvkernels/SpeciesTransportKernels.cpp b/src/engine/transport/fvkernels/SpeciesTransportKernels.cpp
new file mode 100644
index 000000000..fc1989c83
--- /dev/null
+++ b/src/engine/transport/fvkernels/SpeciesTransportKernels.cpp
@@ -0,0 +1,450 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SpeciesTransportKernels.cpp
+ * @brief Shared 1D FV species transport kernels — bodies moved VERBATIM from
+ *        hydraulics/fv/ExplicitFvSolver.cpp (phase E0; see the header).
+ *
+ * @details Local reference aliases at the top of each function reproduce the
+ *          member names the bodies were written against (`mesh_`, `state_`,
+ *          `cell_slope_`, ...) so the moved code is textually identical to
+ *          the pre-move solver code — the cheapest possible bitwise-identity
+ *          argument. Do not "clean up" the aliases: they are the point.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include "SpeciesTransportKernels.hpp"
+
+namespace openswmm::transport::fvkernels {
+
+namespace k = openswmm::fv::kernels;
+
+// ===========================================================================
+// Scalar reconstruction — the anti-diffusion layer (plan §3.2)
+// ===========================================================================
+
+void reconstructScalars(const SpeciesKernelView& v, double dt) {
+    const NetworkMeshData* mesh_  = v.mesh;
+    NetworkStateData*      state_ = v.state;
+    auto&       cell_slope_   = *v.cell_slope;
+    auto&       f_phi_l_      = *v.f_phi_l;
+    auto&       f_phi_r_      = *v.f_phi_r;
+    const auto& f_sstar_      = *v.f_sstar;
+    const auto& cell_u_       = *v.cell_u;
+    const auto& active_faces_ = *v.active_faces;
+
+    const int ns = state_->n_species;
+    if (ns <= 0) return;
+
+    const int nc = mesh_->n_cells();
+    const int nf = mesh_->n_faces();
+
+    for (int s = 0; s < ns; ++s) {
+        const auto sbase = static_cast(s) * static_cast(nc);
+        const auto fbase = static_cast(s) * static_cast(nf);
+
+        // ---- per-cell limited slope along the chain ------------------------
+        if (v.scalar_scheme == ScalarScheme::UPWIND) {
+            std::fill(cell_slope_.begin(), cell_slope_.end(), 0.0);
+        } else {
+            for (int ch = 0; ch < mesh_->n_chains(); ++ch) {
+                const int b = mesh_->chain_ptr[static_cast(ch)];
+                const int e = mesh_->chain_ptr[static_cast(ch) + 1];
+                for (int i = b; i < e; ++i) {
+                    const int c = mesh_->chain_cells[static_cast(i)];
+                    const auto uc = static_cast(c);
+                    if (i == b || i == e - 1) { cell_slope_[uc] = 0.0; continue; }
+                    const int cm = mesh_->chain_cells[static_cast(i - 1)];
+                    const int cp = mesh_->chain_cells[static_cast(i + 1)];
+                    const auto um = static_cast(cm);
+                    const auto up = static_cast(cp);
+                    const double dm = 0.5 * (mesh_->cell_dx[um] + mesh_->cell_dx[uc]);
+                    const double dp = 0.5 * (mesh_->cell_dx[uc] + mesh_->cell_dx[up]);
+                    const double gm = (state_->cell_phi[sbase + uc] -
+                                       state_->cell_phi[sbase + um]) / dm;
+                    const double gp = (state_->cell_phi[sbase + up] -
+                                       state_->cell_phi[sbase + uc]) / dp;
+                    // Chain-space slope → the cell's OWN axis.
+                    cell_slope_[uc] =
+                        limitSlope(gm, gp, v.limiter) *
+                        static_cast(mesh_->chain_dir[static_cast(i)]);
+                }
+            }
+        }
+
+        // ---- face values ----------------------------------------------------
+        for (const int f : active_faces_) {
+            const auto uf = static_cast(f);
+            const int cl = mesh_->face_cl[uf];
+            const int cr = mesh_->face_cr[uf];
+            // A node ghost presents the interior cell's own value (zero
+            // gradient). That keeps a uniform field uniform under inflow, which
+            // is the §6.11(a) gate, without inventing a node concentration this
+            // solver does not track.
+            const int el = (cl >= 0) ? cl : cr;
+            const int er = (cr >= 0) ? cr : cl;
+            const auto ul = static_cast(el);
+            const auto ur = static_cast(er);
+
+            double phil = state_->cell_phi[sbase + ul];
+            double phir = state_->cell_phi[sbase + ur];
+            if (cl >= 0) {
+                const double sign = static_cast(mesh_->face_dir_l[uf]);
+                phil += sign * cell_slope_[ul] * 0.5 * mesh_->cell_dx[ul];
+            }
+            if (cr >= 0) {
+                const double sign = -static_cast(mesh_->face_dir_r[uf]);
+                phir += sign * cell_slope_[ur] * 0.5 * mesh_->cell_dx[ur];
+            }
+
+            if (v.scalar_scheme == ScalarScheme::QUICKEST_ULTIMATE) {
+                // QUICKEST needs TWO upstream cells. Where the stencil exists
+                // it is 3rd order; where it does not — the first cell below a
+                // manhole with several inflowing pipes, or a short conduit —
+                // it degrades, and the MUSCL value computed above is the
+                // fallback. In COARSE mode a sewer spends much of its length in
+                // that degraded regime, which is exactly what the §6.11(d)
+                // junction-density sweep is there to quantify.
+                const bool fwd = (f_sstar_[uf] >= 0.0);
+                const int cu = fwd ? cl : cr;         // upwind cell
+                const int cd = fwd ? cr : cl;         // downwind cell
+                if (cu >= 0 && cd >= 0) {
+                    const auto uu = static_cast(cu);
+                    const int chn = mesh_->cell_chain[uu];
+                    const int pos = mesh_->cell_chain_pos[uu];
+                    const int cb = mesh_->chain_ptr[static_cast(chn)];
+                    const int ce = mesh_->chain_ptr[static_cast(chn) + 1];
+                    // Step one further upstream ALONG THE FLOW, which is the
+                    // downwind cell's opposite neighbour in the chain.
+                    const int dpos = mesh_->cell_chain_pos[static_cast(cd)];
+                    const int upos = pos + (pos - dpos);   // one further upstream
+                    if (upos >= 0 && upos < ce - cb) {
+                        const int cuu = mesh_->chain_cells[
+                            static_cast(cb + upos)];
+                        const auto uuu = static_cast(cuu);
+                        const double pu  = state_->cell_phi[sbase + uu];
+                        const double pd  = state_->cell_phi[sbase + static_cast(cd)];
+                        const double puu = state_->cell_phi[sbase + uuu];
+                        const double dx  = mesh_->cell_dx[uu];
+                        const double cr_no = std::min(
+                            1.0, std::fabs(cell_u_[uu]) * dt / std::max(dx, 1.0e-12));
+                        const double q = pd - 2.0 * pu + puu;
+                        double pf = 0.5 * (pd + pu) - 0.5 * cr_no * (pd - pu) -
+                                    (1.0 - cr_no * cr_no) / 6.0 * q;
+                        // ULTIMATE monotonicity limiter (Leonard 1991), applied
+                        // in normalized variables.
+                        const double den = pd - puu;
+                        if (std::fabs(den) > 1.0e-30) {
+                            const double un_ = (pu - puu) / den;
+                            if (un_ <= 0.0 || un_ >= 1.0) {
+                                pf = pu;                       // non-monotone ⇒ upwind
+                            } else {
+                                double fn = (pf - puu) / den;
+                                const double hi = std::min(1.0, un_ / std::max(cr_no, 1.0e-12));
+                                fn = std::clamp(fn, un_, hi);
+                                pf = puu + fn * den;
+                            }
+                        } else {
+                            pf = pu;
+                        }
+                        if (fwd) phil = pf; else phir = pf;
+                    }
+                }
+            }
+
+            // Local-extremum clamp — the last line of defence for the "no new
+            // extrema, no negative concentrations" contract (§6.11b). Both
+            // higher-order reconstructions are TVD for PURE advection on a
+            // fixed grid; here the cell areas are evolving underneath them
+            // (reflections, wetting, drying), and QUICKEST's normalized-variable
+            // limiter measurably loses monotonicity in that regime. Clamping the
+            // face value into the bracket its own two cells span costs nothing
+            // where the scheme is already monotone and restores the guarantee
+            // where it is not.
+            if (v.scalar_scheme != ScalarScheme::UPWIND) {
+                const double a = state_->cell_phi[sbase + ul];
+                const double b = state_->cell_phi[sbase + ur];
+                const double lo = std::min(a, b);
+                const double hi = std::max(a, b);
+                phil = std::clamp(phil, lo, hi);
+                phir = std::clamp(phir, lo, hi);
+            }
+
+            f_phi_l_[fbase + uf] = phil;
+            f_phi_r_[fbase + uf] = phir;
+        }
+
+        // ---- flux assembly + Zalesak limiting ------------------------------
+        limitSpeciesFluxes(v, s, dt);
+    }
+}
+
+/**
+ * @brief Assemble the face species fluxes and limit them (Zalesak FCT).
+ *
+ * @details Bracketing the reconstructed FACE value between its two cells is
+ *          necessary but NOT sufficient for the discrete maximum principle:
+ *          under reversing, unsteady flow with the cell areas evolving
+ *          underneath the scalar, a face value legitimately inside its bracket
+ *          can still drain more solute than its donor cell holds. Measured:
+ *          QUICKEST-ULTIMATE produced −1.3e-3 on a step-function advection case
+ *          with wall reflections, which is not acceptable in a water-quality
+ *          model.
+ *
+ *          The fix has to limit the FLUX, not the result. Clipping the updated
+ *          concentration would enforce the bound but destroy exact solute
+ *          conservation (§6.11c) — the two properties trade off, and Zalesak
+ *          (1979) is the construction that keeps both: blend each face's
+ *          high-order flux back toward first-order upwind by the largest factor
+ *          that no incident cell's bound rejects. The SAME limited flux updates
+ *          both incident cells, so conservation is untouched.
+ */
+void limitSpeciesFluxes(const SpeciesKernelView& v, int species, double dt) {
+    const NetworkMeshData* mesh_  = v.mesh;
+    NetworkStateData*      state_ = v.state;
+    const auto& f_mass_       = *v.f_mass;
+    const auto& f_state_l_    = *v.f_state_l;
+    const auto& f_state_r_    = *v.f_state_r;
+    const auto& f_flux_       = *v.f_flux;
+    const auto& f_phi_l_      = *v.f_phi_l;
+    const auto& f_phi_r_      = *v.f_phi_r;
+    const auto& cell_active_  = *v.cell_active;
+    const auto& active_faces_ = *v.active_faces;
+    auto&       f_phi_flux_   = *v.f_phi_flux;
+    auto&       lo_flux_      = *v.lo_flux;
+    auto&       anti_flux_    = *v.anti_flux;
+    auto&       td_           = *v.td;
+    auto&       anew_         = *v.anew;
+    auto&       rplus_        = *v.rplus;
+    auto&       rminus_       = *v.rminus;
+    const bool  hllc_         = v.hllc;
+
+    /// The flux record with the positivity-scaled mass flux substituted in, so
+    /// the species rides on exactly the water the hydrodynamic update moved.
+    /// (Formerly ExplicitFvSolver::adjustedFlux.)
+    const auto adjustedFlux = [&](int face) {
+        k::FaceFlux f = f_flux_[static_cast(face)];
+        f.mass = f_mass_[static_cast(face)];
+        return f;
+    };
+
+    const int nc = mesh_->n_cells();
+    const int nf = mesh_->n_faces();
+    const auto cbase = static_cast(species) *
+                       static_cast(nc);
+    const auto fbase = static_cast(species) *
+                       static_cast(nf);
+
+    lo_flux_.assign(static_cast(nf), 0.0);
+    anti_flux_.assign(static_cast(nf), 0.0);
+
+    // Low-order (first-order upwind on the sign of the mass flux) and the
+    // antidiffusive remainder.
+    for (const int f : active_faces_) {
+        const auto uf = static_cast(f);
+        const int cl = mesh_->face_cl[uf];
+        const int cr = mesh_->face_cr[uf];
+        const auto ul = static_cast((cl >= 0) ? cl : cr);
+        const auto ur = static_cast((cr >= 0) ? cr : cl);
+        const double fm = f_mass_[uf];
+        const double lo = fm * ((fm >= 0.0) ? state_->cell_phi[cbase + ul]
+                                            : state_->cell_phi[cbase + ur]);
+        const double hi = k::speciesFlux(f_state_l_[uf], f_state_r_[uf],
+                                         adjustedFlux(f), f_phi_l_[fbase + uf],
+                                         f_phi_r_[fbase + uf], hllc_);
+        lo_flux_[uf]   = lo;
+        anti_flux_[uf] = hi - lo;
+    }
+
+    // Transported-diffused state under the low-order flux alone, plus the
+    // local bounds it and its neighbours span.
+    td_.assign(static_cast(nc), 0.0);
+    anew_.assign(static_cast(nc), 0.0);
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        if (!cell_active_[uc]) { td_[uc] = state_->cell_phi[cbase + uc];
+                                 anew_[uc] = state_->cell_a[uc]; continue; }
+        const int faces[2]    = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
+        const int8_t sides[2] = {mesh_->cell_side0[uc], mesh_->cell_side1[uc]};
+        double dA = 0.0, dm = 0.0;
+        for (int e = 0; e < 2; ++e) {
+            const auto uf = static_cast(faces[e]);
+            const double sg = (sides[e] == 0) ? -1.0 : 1.0;
+            dA += sg * f_mass_[uf];
+            dm += sg * lo_flux_[uf];
+        }
+        const double inv_dx = 1.0 / mesh_->cell_dx[uc];
+        const double a_new = std::max(0.0, state_->cell_a[uc] + dt * dA * inv_dx);
+        anew_[uc] = a_new;
+        const double m = state_->cell_a[uc] * state_->cell_phi[cbase + uc] +
+                         dt * dm * inv_dx;
+        td_[uc] = (a_new > k::kDryArea) ? m / a_new : state_->cell_phi[cbase + uc];
+    }
+
+    rplus_.assign(static_cast(nc), 1.0);
+    rminus_.assign(static_cast(nc), 1.0);
+    for (int c = 0; c < nc; ++c) {
+        const auto uc = static_cast(c);
+        if (!cell_active_[uc]) continue;
+        const int faces[2]    = {mesh_->cell_face0[uc], mesh_->cell_face1[uc]};
+        const int8_t sides[2] = {mesh_->cell_side0[uc], mesh_->cell_side1[uc]};
+
+        double pmax = std::max(state_->cell_phi[cbase + uc], td_[uc]);
+        double pmin = std::min(state_->cell_phi[cbase + uc], td_[uc]);
+        double pplus = 0.0, pminus = 0.0;
+        for (int e = 0; e < 2; ++e) {
+            const auto uf = static_cast(faces[e]);
+            const int cl = mesh_->face_cl[uf];
+            const int cr = mesh_->face_cr[uf];
+            const int nb = (cl == c) ? cr : cl;
+            if (nb >= 0) {
+                const auto un = static_cast(nb);
+                pmax = std::max({pmax, state_->cell_phi[cbase + un], td_[un]});
+                pmin = std::min({pmin, state_->cell_phi[cbase + un], td_[un]});
+            }
+            const double sg = (sides[e] == 0) ? -1.0 : 1.0;
+            const double a = sg * anti_flux_[uf];
+            if (a > 0.0) pplus += a; else pminus -= a;
+        }
+        const double cap = anew_[uc] * mesh_->cell_dx[uc] / dt;
+        if (pplus  > 0.0) rplus_[uc]  = std::min(1.0, (pmax - td_[uc]) * cap / pplus);
+        if (pminus > 0.0) rminus_[uc] = std::min(1.0, (td_[uc] - pmin) * cap / pminus);
+        rplus_[uc]  = std::max(0.0, rplus_[uc]);
+        rminus_[uc] = std::max(0.0, rminus_[uc]);
+    }
+
+    for (const int f : active_faces_) {
+        const auto uf = static_cast(f);
+        const double a = anti_flux_[uf];
+        double coef = 1.0;
+        if (a != 0.0) {
+            const int cl = mesh_->face_cl[uf];
+            const int cr = mesh_->face_cr[uf];
+            // The face contributes −a to its LEFT cell and +a to its RIGHT one.
+            const double from_r = (cr >= 0)
+                ? ((a > 0.0) ? rplus_[static_cast(cr)]
+                             : rminus_[static_cast(cr)])
+                : 1.0;
+            const double from_l = (cl >= 0)
+                ? ((a > 0.0) ? rminus_[static_cast(cl)]
+                             : rplus_[static_cast(cl)])
+                : 1.0;
+            coef = std::min(from_r, from_l);
+        }
+        f_phi_flux_[fbase + uf] = lo_flux_[uf] + coef * a;
+    }
+}
+
+// ===========================================================================
+// Implicit dispersion (D-FV1)
+// ===========================================================================
+
+void dispersionSolve(const SpeciesKernelView& v, double dt) {
+    const NetworkMeshData* mesh_  = v.mesh;
+    NetworkStateData*      state_ = v.state;
+
+    const int ns = state_->n_species;
+    if (ns <= 0) return;
+    // Per-cell coefficients (E3) take precedence; the scalar early-out is
+    // the pre-E3 condition, untouched when no per-cell array is supplied.
+    const std::vector* cd = v.cell_dispersion;
+    if (cd == nullptr && v.dispersion <= 0.0) return;
+
+    /// Cell coefficient under either model. E3 bitwise-preservation note:
+    /// each face uses 0.5*(D_i + D_j). With cd == nullptr both operands are
+    /// v.dispersion, and 0.5*(D + D) == D EXACTLY in binary floating point
+    /// (the ×2 and ×0.5 are exponent shifts), so the face coefficient — and
+    /// therefore every downstream product in the same evaluation order — is
+    /// bit-identical to the pre-E3 `v.dispersion * …` expression. The FV
+    /// solver passes cd == nullptr and keeps its bitwise contract (E0 gate).
+    const auto cellD = [&](int c) {
+        return (cd != nullptr) ? (*cd)[static_cast(c)]
+                               : v.dispersion;
+    };
+
+    const int nc = mesh_->n_cells();
+    static thread_local std::vector aa, bb, ccv, rr, xx;
+
+    // One tridiagonal system per chain (Thomas) — cheap, unconditionally
+    // stable, and it removes the Δx²/(2·D_L) explicit constraint entirely,
+    // which at fine Δx is MORE restrictive than CFL (plan §3.2, D-FV1). Chains
+    // span virtual junctions, so a spliced pair disperses as one conduit.
+    for (int ch = 0; ch < mesh_->n_chains(); ++ch) {
+        const int b = mesh_->chain_ptr[static_cast(ch)];
+        const int e = mesh_->chain_ptr[static_cast(ch) + 1];
+        const int m = e - b;
+        if (m < 2) continue;
+        aa.assign(static_cast(m), 0.0);
+        bb.assign(static_cast(m), 0.0);
+        ccv.assign(static_cast(m), 0.0);
+        rr.assign(static_cast(m), 0.0);
+        xx.assign(static_cast(m), 0.0);
+
+        for (int s = 0; s < ns; ++s) {
+            const auto base = static_cast(s) *
+                              static_cast(nc);
+            for (int i = 0; i < m; ++i) {
+                const int c = mesh_->chain_cells[static_cast(b + i)];
+                const auto uc = static_cast(c);
+                const double dx = mesh_->cell_dx[uc];
+                const double a  = std::max(state_->cell_a[uc], k::kDryArea);
+                const double dc = cellD(c);
+                double lo = 0.0, hi = 0.0;
+                if (i > 0) {
+                    const int cm = mesh_->chain_cells[static_cast(b + i - 1)];
+                    const double am = std::max(
+                        state_->cell_a[static_cast(cm)], k::kDryArea);
+                    lo = 0.5 * (dc + cellD(cm)) * 0.5 * (a + am) * dt /
+                         (dx * dx * a);
+                }
+                if (i < m - 1) {
+                    const int cp = mesh_->chain_cells[static_cast(b + i + 1)];
+                    const double ap = std::max(
+                        state_->cell_a[static_cast(cp)], k::kDryArea);
+                    hi = 0.5 * (dc + cellD(cp)) * 0.5 * (a + ap) * dt /
+                         (dx * dx * a);
+                }
+                aa[static_cast(i)]  = -lo;
+                ccv[static_cast(i)] = -hi;
+                bb[static_cast(i)]  = 1.0 + lo + hi;
+                rr[static_cast(i)]  = state_->cell_phi[base + uc];
+            }
+            for (int i = 1; i < m; ++i) {
+                const auto ui = static_cast(i);
+                const double w = aa[ui] / bb[ui - 1];
+                bb[ui] -= w * ccv[ui - 1];
+                rr[ui] -= w * rr[ui - 1];
+            }
+            const auto ulast = static_cast(m - 1);
+            xx[ulast] = rr[ulast] / bb[ulast];
+            for (int i = m - 2; i >= 0; --i) {
+                const auto ui = static_cast(i);
+                xx[ui] = (rr[ui] - ccv[ui] * xx[ui + 1]) / bb[ui];
+            }
+            for (int i = 0; i < m; ++i) {
+                const int c = mesh_->chain_cells[static_cast(b + i)];
+                state_->cell_phi[base + static_cast(c)] =
+                    xx[static_cast(i)];
+            }
+        }
+    }
+}
+
+}  // namespace openswmm::transport::fvkernels
diff --git a/src/engine/transport/fvkernels/SpeciesTransportKernels.hpp b/src/engine/transport/fvkernels/SpeciesTransportKernels.hpp
new file mode 100644
index 000000000..e5d5d548f
--- /dev/null
+++ b/src/engine/transport/fvkernels/SpeciesTransportKernels.hpp
@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file SpeciesTransportKernels.hpp
+ * @brief Shared 1D FV species transport kernels (advection reconstruction,
+ *        Zalesak FCT flux limiting, implicit per-chain dispersion).
+ *
+ * @details Phase E0 of the Unified Transport suite
+ *          (plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md, rev. 2): the
+ *          species-transport machinery formerly private to
+ *          hydraulics/fv/ExplicitFvSolver is promoted here VERBATIM so the
+ *          standalone Eulerian ARD engine and the FV hydraulic solver share
+ *          one implementation (master plan D-UT1 as amended). The FV solver
+ *          calls these free functions through a thin view over its own
+ *          state; behavior is bitwise-identical to the pre-move code by
+ *          construction (E0 gate).
+ *
+ *          The kernels operate on the FV cell mesh types
+ *          (`NetworkMeshData` / `NetworkStateData`) and the face records the
+ *          hydrodynamic solve produced. They own no state: every array —
+ *          including scratch — is supplied by the caller through
+ *          @ref SpeciesKernelView, so the same code can later be driven by
+ *          the HydraulicsProjection path (plan §3.2) without change.
+ *
+ * @ingroup engine_transport
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#ifndef OPENSWMM_ENGINE_TRANSPORT_FVKERNELS_SPECIES_TRANSPORT_KERNELS_HPP
+#define OPENSWMM_ENGINE_TRANSPORT_FVKERNELS_SPECIES_TRANSPORT_KERNELS_HPP
+
+#include 
+#include 
+#include 
+
+#include "../../hydraulics/fv/FvKernels.hpp"
+#include "../../hydraulics/fv/FvOptions.hpp"
+#include "../../hydraulics/fv/NetworkMeshData.hpp"
+
+namespace openswmm::transport::fvkernels {
+
+using openswmm::fv::Limiter;
+using openswmm::fv::NetworkMeshData;
+using openswmm::fv::NetworkStateData;
+using openswmm::fv::ScalarScheme;
+
+/// Slope limiters for the second-order scalar reconstruction. All three are
+/// TVD; superbee is the sharpest and can artificially steepen smooth profiles,
+/// minmod the most diffusive and most robust. (Moved verbatim from
+/// ExplicitFvSolver.cpp; also used by the solver's hydrodynamic
+/// reconstructState.)
+inline double limitSlope(double a, double b, Limiter lim) {
+    if (a * b <= 0.0) return 0.0;                  // extremum ⇒ no slope
+    switch (lim) {
+        case Limiter::VANLEER:
+            return 2.0 * a * b / (a + b);
+        case Limiter::SUPERBEE: {
+            const double s = (a > 0.0) ? 1.0 : -1.0;
+            return s * std::max(std::min(2.0 * std::fabs(a), std::fabs(b)),
+                                std::min(std::fabs(a), 2.0 * std::fabs(b)));
+        }
+        case Limiter::MINMOD:
+        default:
+            return (std::fabs(a) < std::fabs(b)) ? a : b;
+    }
+}
+
+/**
+ * @brief Non-owning view over everything the species kernels read and write.
+ *
+ * @details Built per call by the driving solver. Read-only inputs are the
+ *          mesh, the hydrodynamic face records of the current substep, and
+ *          the derived cell velocity/active flags; `state->cell_phi` is the
+ *          transported field; the remaining vectors are caller-owned scratch
+ *          sized exactly as ExplicitFvSolver sizes its members (f_phi_l/r and
+ *          f_phi_flux are [n_species * n_faces]; the rest are per-face or
+ *          per-cell).
+ */
+struct SpeciesKernelView {
+    const NetworkMeshData* mesh = nullptr;
+    NetworkStateData*      state = nullptr;
+
+    // Scheme options (subset of FvOptions the kernels consume).
+    ScalarScheme scalar_scheme = ScalarScheme::MUSCL;
+    Limiter      limiter       = Limiter::MINMOD;
+    double       dispersion    = 0.0;
+    bool         hllc          = true;
+
+    /// Per-cell dispersion coefficients [n_cells], ft²/s (phase E3:
+    /// per-conduit user overrides + FISCHER auto-computation). When null,
+    /// the scalar `dispersion` above applies uniformly — the pre-E3 path,
+    /// bitwise-unchanged (see the exactness note in dispersionSolve). When
+    /// set, `dispersion` is ignored and each interior face uses the
+    /// arithmetic mean of its two cells' coefficients.
+    const std::vector* cell_dispersion = nullptr;
+
+    // Hydrodynamic face records of the current substep (read-only).
+    const std::vector* f_mass  = nullptr;  ///< positivity-scaled mass flux
+    const std::vector* f_sstar = nullptr;  ///< HLLC contact speed
+    const std::vector* f_state_l = nullptr;
+    const std::vector* f_state_r = nullptr;
+    const std::vector*  f_flux    = nullptr;
+
+    // Derived cell fields (read-only).
+    const std::vector* cell_u      = nullptr;  ///< Q/A, dry-guarded
+    const std::vector*   cell_active = nullptr;
+    const std::vector*    active_faces = nullptr;
+
+    // Caller-owned outputs / scratch.
+    std::vector* f_phi_l    = nullptr;  ///< [s*n_faces+f] reconstructed
+    std::vector* f_phi_r    = nullptr;  ///<   face values
+    std::vector* f_phi_flux = nullptr;  ///< [s*n_faces+f] limited flux
+    std::vector* cell_slope = nullptr;
+    std::vector* lo_flux    = nullptr;
+    std::vector* anti_flux  = nullptr;
+    std::vector* td         = nullptr;
+    std::vector* anew       = nullptr;
+    std::vector* rplus      = nullptr;
+    std::vector* rminus     = nullptr;
+};
+
+/// Scalar reconstruction — the anti-diffusion layer (FV plan §3.2). Computes
+/// limited face values for every species and calls limitSpeciesFluxes to
+/// assemble/limit the face species fluxes into `f_phi_flux`.
+void reconstructScalars(const SpeciesKernelView& v, double dt);
+
+/// Assemble the face species fluxes and limit them (Zalesak FCT). See the
+/// implementation notes: limits the FLUX, not the result, so the discrete
+/// maximum principle and exact solute conservation hold together.
+void limitSpeciesFluxes(const SpeciesKernelView& v, int species, double dt);
+
+/// Implicit longitudinal dispersion (decision D-FV1): one Thomas tridiagonal
+/// solve per cell chain per species; unconditionally stable, removes the
+/// Δx²/(2·D_L) explicit constraint. E3: honours `v.cell_dispersion` when set
+/// (per-conduit / FISCHER coefficients); scalar `v.dispersion` otherwise.
+void dispersionSolve(const SpeciesKernelView& v, double dt);
+
+}  // namespace openswmm::transport::fvkernels
+
+#endif  // OPENSWMM_ENGINE_TRANSPORT_FVKERNELS_SPECIES_TRANSPORT_KERNELS_HPP
diff --git a/src/legacy/engine/dwflow.c b/src/legacy/engine/dwflow.c
index b083a53c8..828431b1d 100644
--- a/src/legacy/engine/dwflow.c
+++ b/src/legacy/engine/dwflow.c
@@ -28,6 +28,13 @@
 //   - Implements the new option to skip checking for normal flow limitations.
 //   Build 5.2.4:
 //   - Arguments to function link_getLossRate changed.
+//   OpenSWMM (issue #144):
+//   - Preissmann slot area removed from the momentum equation. Velocity,
+//     upstream-weighted area, inertial terms and local losses now use the
+//     conveyance area (getConveyArea); node continuity and link storage keep
+//     the slot-inclusive area. Previously getHydRad() excluded the slot from
+//     the hydraulic radius while getArea() left it in the area, so a single
+//     friction term mixed two cross-sections.
 //-----------------------------------------------------------------------------
 #define _CRT_SECURE_NO_DEPRECATE
 
@@ -54,6 +61,7 @@ static double findLocalLosses(int link, double a1, double a2, double aMid,
 static double getWidth(TXsect* xsect, double y);
 static double getSlotWidth(TXsect* xsect, double y);
 static double getArea(TXsect* xsect, double y, double wSlot);
+static double getConveyArea(TXsect* xsect, double a);
 static double getHydRad(TXsect* xsect, double y);
 
 static double checkNormalFlow(int j, double q, double y1, double y2,
@@ -81,6 +89,8 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
     double qLast;                      // flow from previous iteration (cfs)
     double qOld;                       // flow from previous time step (cfs)
     double aOld;                       // area from previous time step (ft2)
+    double a1Conv, a2Conv;             // upstrm/dnstrm conveyance areas (ft2)
+    double aMidConv, aOldConv;         // midpoint & previous conveyance areas (ft2)
     double v;                          // velocity (ft/sec)
     double rho;                        // upstream weighting factor
     double sigma;                      // inertial damping factor
@@ -161,6 +171,16 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
     //aMid = (a1+a2)/2.0;
     //rMid = (r1+getHydRad(xsect,y2))/2.0;
 
+    // --- conveyance areas for the momentum equation exclude the Preissmann
+    //     slot (see getConveyArea). aOld is clamped alongside aMid so the
+    //     dq3 difference below stays apples-to-apples across a time step in
+    //     which the conduit crosses its crown; the slot-inclusive a1/a2/aMid
+    //     are still used for stored area, volume and full-state below.
+    a1Conv   = getConveyArea(xsect, a1);
+    a2Conv   = getConveyArea(xsect, a2);
+    aMidConv = getConveyArea(xsect, aMid);
+    aOldConv = getConveyArea(xsect, aOld);
+
     // --- check if conduit is flowing full
     if ( y1 >= xsect->yFull &&
          y2 >= xsect->yFull) isFull = TRUE;
@@ -184,7 +204,7 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
     }
 
     // --- compute velocity from last flow estimate
-    v = qLast / aMid;
+    v = qLast / aMidConv;
     if ( fabs(v) > MAXVELOCITY )  v = MAXVELOCITY * SGN(qLast);
 
     // --- compute Froude No.
@@ -201,7 +221,7 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
     //     (modified version of R. Dickinson's slope weighting)
     rho = 1.0;
     if ( !isFull && qLast > 0.0 && h1 >= h2 ) rho = sigma;
-    aWtd = a1 + (aMid - a1) * rho;
+    aWtd = a1Conv + (aMidConv - a1Conv) * rho;
     rWtd = r1 + (rMid - r1) * rho;
 
     // --- determine how much inertial damping to apply
@@ -225,15 +245,16 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
     dq4 = 0.0;
     if ( sigma > 0.0 )
     {
-        dq3 = 2.0 * v * (aMid - aOld) * sigma;
-        dq4 = dt * v * v * (a2 - a1) / length * sigma;
+        dq3 = 2.0 * v * (aMidConv - aOldConv) * sigma;
+        dq4 = dt * v * v * (a2Conv - a1Conv) / length * sigma;
     }
 
     // --- 5. local losses term
     dq5 = 0.0;
     if ( Conduit[k].hasLosses )
     {
-        dq5 = findLocalLosses(linkIndex, a1, a2, aMid, qLast) / 2.0 / length * dt;
+        dq5 = findLocalLosses(linkIndex, a1Conv, a2Conv, aMidConv, qLast) /
+              2.0 / length * dt;
     }
 
     // --- 6. term for evap and seepage losses per unit length
@@ -271,7 +292,7 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
                 snprintf(fname, sizeof(fname), "%s.link%ld", tr, lfTarget);
                 lf = fopen(fname, "w");
                 if ( lf ) fprintf(lf,
-                    "n,qLast,v,sigma,rho,aWtd,rWtd,dq1,dq2,dq3,dq4,dq5,dq6,qOld,q,sa1,sa2,fc,y1,yMid,a1,aMid,r1,rMid\n");
+                    "n,qLast,v,sigma,rho,aWtd,rWtd,dq1,dq2,dq3,dq4,dq5,dq6,qOld,q,sa1,sa2,fc,y1,yMid,a1,aMid,r1,rMid,aMidConv,dqdh,h1,h2,n1,n2,yn1,yn2\n");
             }
         }
         if ( lf && linkIndex == lfTarget )
@@ -287,12 +308,15 @@ void  dwflow_findConduitFlow(int linkIndex, int steps, double omega, double dt)
             if ( inWindow && lfRows < 128 )
             {
                 ++lfRows;
-                fprintf(lf, "%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%a,%a,%a,%a,%a,%a\n",
+                fprintf(lf, "%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%d,%d,%a,%a\n",
                         lfCount, qLast, v, sigma, rho, aWtd, rWtd,
                         dq1, dq2, dq3, dq4, dq5, dq6, qOld, q,
                         Link[linkIndex].surfArea1, Link[linkIndex].surfArea2,
                         Link[linkIndex].flowClass,
-                        y1, yMid, a1, aMid, r1, rMid);
+                        y1, yMid, a1, aMid, r1, rMid, aMidConv,
+                        Link[linkIndex].dqdh, h1, h2,
+                        Link[linkIndex].node1, Link[linkIndex].node2,
+                        Node[Link[linkIndex].node1].newDepth, Node[Link[linkIndex].node2].newDepth);
                 if ( lfRows >= 128 ) { fclose(lf); lf = NULL; }
             }
         }
@@ -676,6 +700,35 @@ double getArea(TXsect* xsect, double y, double wSlot)
 
 //=============================================================================
 
+double getConveyArea(TXsect* xsect, double a)
+//
+//  Input:   xsect = ptr. to conduit cross section
+//           a     = flow area, slot included if surcharged (ft2)
+//  Output:  returns conveyance area (ft2)
+//  Purpose: strips the Preissmann slot contribution from a flow area.
+//
+//  The slot is a fictitious gap above the crown whose purpose is to supply a
+//  finite free-surface top width so the Saint-Venant system stays hyperbolic
+//  once a conduit pressurizes. It stores water but conveys none, so the
+//  momentum equation - velocity, friction, inertial terms and local losses -
+//  must use the closed-section area. This mirrors getHydRad(), which already
+//  clamps to rFull on the same reasoning: the slot adds no wetted perimeter.
+//
+//  Node continuity (findSurfArea) and link storage (newVolume) deliberately
+//  keep the slot-inclusive area - that is where the slot does its real work,
+//  and where the water it holds is booked. See issue #144.
+//
+//  Off the slot path this is the identity: getArea() returns aFull for an
+//  open shape or under EXTRAN (wSlot == 0), and less than aFull below full
+//  depth, so nothing is clamped.
+//
+{
+    if ( a > xsect->aFull ) return xsect->aFull;
+    return a;
+}
+
+//=============================================================================
+
 double getHydRad(TXsect* xsect, double y)
 //
 //  Input:   xsect = ptr. to conduit cross section
diff --git a/src/legacy/engine/enums.h b/src/legacy/engine/enums.h
index d4c65fba1..50ca8dade 100644
--- a/src/legacy/engine/enums.h
+++ b/src/legacy/engine/enums.h
@@ -768,6 +768,18 @@ enum SurchargeMethodType
      SLOT,
 };
 
+/*!
+* \enum BackflowQualType
+* \brief Quality carried by reverse flow at outfalls
+*/
+enum BackflowQualType
+{
+     /*! \brief Hold the last mixed concentration (legacy behavior) */
+     BACKFLOW_LAST,
+     /*! \brief Fresh boundary: backflow enters with zero concentration */
+     BACKFLOW_ZERO,
+};
+
 /*!
 * \enum InflowType
 * \brief Enumeration of inflow method types
@@ -1196,6 +1208,8 @@ enum InputOptionType
      NUM_THREADS,
      /*! \brief Surcharge method */
      SURCHARGE_METHOD,
+     /*! \brief Quality carried by reverse flow at outfalls */
+     OUTFALL_BACKFLOW_QUALITY,
 };
 
 /*!
diff --git a/src/legacy/engine/gage.c b/src/legacy/engine/gage.c
index 65c797e62..69f7ce0ed 100644
--- a/src/legacy/engine/gage.c
+++ b/src/legacy/engine/gage.c
@@ -260,14 +260,19 @@ void  gage_validate(int gageIndex)
         {
             report_writeErrorMsg(ERR_RAIN_GAGE_TSERIES, Gage[gageIndex].ID);
         }
-        gageInterval = (int)(floor(Tseries[k].dxMin*SECperDAY + 0.5));
-        if ( gageInterval > 0 && Gage[gageIndex].rainInterval > gageInterval )
+        // --- a single-point time series never updates dxMin from its BIG
+        //     sentinel, so it has no meaningful recording interval to check
+        if ( Tseries[k].dxMin < BIG )
         {
-            report_writeErrorMsg(ERR_RAIN_GAGE_INTERVAL, Gage[gageIndex].ID);
-        } 
-        if ( Gage[gageIndex].rainInterval < gageInterval )
-        {
-            report_writeWarningMsg(WARN09, Gage[gageIndex].ID);
+            gageInterval = (int)(floor(Tseries[k].dxMin*SECperDAY + 0.5));
+            if ( gageInterval > 0 && Gage[gageIndex].rainInterval > gageInterval )
+            {
+                report_writeErrorMsg(ERR_RAIN_GAGE_INTERVAL, Gage[gageIndex].ID);
+            }
+            if ( Gage[gageIndex].rainInterval < gageInterval )
+            {
+                report_writeWarningMsg(WARN09, Gage[gageIndex].ID);
+            }
         }
         if ( Gage[gageIndex].rainInterval < WetStep )
         {
diff --git a/src/legacy/engine/globals.h b/src/legacy/engine/globals.h
index 5ba7440d0..137903c12 100644
--- a/src/legacy/engine/globals.h
+++ b/src/legacy/engine/globals.h
@@ -78,7 +78,8 @@ EXTERN int
                   RouteModel,               // Flow routing method
                   ForceMainEqn,             // Flow equation for force mains
                   LinkOffsets,              // Link offset convention
-                  SurchargeMethod,          // EXTRAN or SLOT method 
+                  SurchargeMethod,          // EXTRAN or SLOT method
+                  ZeroOutfallBackflowQual,  // Outfall backflow enters clean
                   AllowPonding,             // Allow water to pond at nodes
                   InertDamping,             // Degree of inertial damping
                   NormalFlowLtd,            // Normal flow limited
diff --git a/src/legacy/engine/keywords.c b/src/legacy/engine/keywords.c
index 5f4b4e443..09067a766 100644
--- a/src/legacy/engine/keywords.c
+++ b/src/legacy/engine/keywords.c
@@ -94,7 +94,7 @@ char* OptionWords[]        = { w_FLOW_UNITS,        w_INFIL_MODEL,
                                w_SYS_FLOW_TOL,      w_LAT_FLOW_TOL,
                                w_IGNORE_RDII,       w_MIN_ROUTE_STEP,
                                w_NUM_THREADS,       w_SURCHARGE_METHOD,
-                               NULL };
+                               w_OUTFALL_BF_QUAL,   NULL };
 char* OrificeTypeWords[]   = { w_SIDE, w_BOTTOM, NULL};
 char* OutfallTypeWords[]   = { w_FREE, w_NORMAL, w_FIXED, w_TIDAL,
                                w_TIMESERIES, NULL};
@@ -146,6 +146,7 @@ char* SectWords[]          = { ws_TITLE,          ws_OPTION,
                                ws_INLET,          NULL};
 char* SnowmeltWords[]      = { w_PLOWABLE, w_IMPERV, w_PERV, w_REMOVAL, NULL};
 char* SurchargeWords[]     = { w_EXTRAN, w_SLOT, NULL};
+char* BackflowQualWords[]  = { w_LAST, w_ZERO, NULL};
 char* TempKeyWords[]       = { w_TIMESERIES, w_FILE, w_WINDSPEED, w_SNOWMELT,
                                w_ADC, NULL};
 char* TransectKeyWords[]   = { w_NC, w_X1, w_GR, NULL};
diff --git a/src/legacy/engine/keywords.h b/src/legacy/engine/keywords.h
index e330c59bc..60ddd8fbe 100644
--- a/src/legacy/engine/keywords.h
+++ b/src/legacy/engine/keywords.h
@@ -59,6 +59,7 @@ extern char* RuleKeyWords[];
 extern char* SectWords[];
 extern char* SnowmeltWords[];
 extern char* SurchargeWords[];
+extern char* BackflowQualWords[];
 extern char* TempKeyWords[];
 extern char* TransectKeyWords[];
 extern char* TreatTypeWords[];
diff --git a/src/legacy/engine/landuse.c b/src/legacy/engine/landuse.c
index a0f6808b3..bd597be20 100644
--- a/src/legacy/engine/landuse.c
+++ b/src/legacy/engine/landuse.c
@@ -630,7 +630,14 @@ double landuse_getWashoffQual(int i, int p, double buildup, double runoff,
     if ( func == NO_WASHOFF || runoff == 0.0 ) return 0.0;
     
     // --- if buildup function exists but no current buildup, return 0
-    if ( Landuse[i].buildupFunc[p].funcType != NO_BUILDUP && buildup >= 0.0 )
+    //     RESTORED to stock EPA 5.2.4 (2026-08-23, Finding 11): our vendored
+    //     copy carried `>= 0.0` since 03ed283a, under which a land use with
+    //     any buildup function washed off NOTHING, ever -- buildup is never
+    //     negative, so the guard always fired. This file is the parity
+    //     REFERENCE; a corrupted control corrupts every quality comparison
+    //     made against it. Measured inert on the known-mass EMC deck (no
+    //     buildup function there), so it did not cause Finding 6.
+    if ( Landuse[i].buildupFunc[p].funcType != NO_BUILDUP && buildup == 0.0 )
         return 0.0;
 
     // --- Exponential Washoff function
diff --git a/src/legacy/engine/link.c b/src/legacy/engine/link.c
index a2d3566a4..31925e1f3 100644
--- a/src/legacy/engine/link.c
+++ b/src/legacy/engine/link.c
@@ -1956,17 +1956,18 @@ double orifice_getInflow(int j)
                 snprintf(fname, sizeof(fname), "%s.orif%ld", tr, ofTarget);
                 of = fopen(fname, "w");
                 if ( of ) fprintf(of,
-                    "h1,h2,hcrest,hcrown,f,head,cWeir,cOrif,hCrit,dqdh,q\n");
+                    "h1,h2,hcrest,hcrown,f,head,cWeir,cOrif,hCrit,dqdh,q,surfArea,length,newDepth\n");
             }
         }
         if ( of && j == ofTarget &&
              (ofStep <= 0 || SwmmTraceRstepSn + 1 >= ofStep) && ofRows < 128 )
         {
             ++ofRows;
-            fprintf(of, "%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a\n",
+            fprintf(of, "%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a,%a\n",
                     h1, h2, hcrest, hcrown, f, head,
                     Orifice[k].cWeir, Orifice[k].cOrif, Orifice[k].hCrit,
-                    Link[j].dqdh, q);
+                    Link[j].dqdh, q,
+                    Orifice[k].surfArea, Orifice[k].length, Link[j].newDepth);
             if ( ofRows >= 128 ) { fclose(of); of = NULL; }
         }
     }
diff --git a/src/legacy/engine/output.c b/src/legacy/engine/output.c
index b1ace97d1..f57370e61 100644
--- a/src/legacy/engine/output.c
+++ b/src/legacy/engine/output.c
@@ -515,6 +515,10 @@ void output_saveResults(double reportTime)
                              SysResults[SYS_EXFLOW];
     fwrite(SysResults, sizeof(REAL4), MAX_SYS_RESULTS, Fout.file);
 
+    // --- flush the completed period so a live reader (GUI tailing the
+    //     binary file while the worker runs) can count it from the file size
+    fflush(Fout.file);
+
     // --- save outfall flows to interface file if called for
     if ( Foutflows.mode == SAVE_FILE && !IgnoreRouting ) 
         iface_saveOutletResults(reportDate, Foutflows.file);
diff --git a/src/legacy/engine/project.c b/src/legacy/engine/project.c
index c560fed75..d24c17f8b 100644
--- a/src/legacy/engine/project.c
+++ b/src/legacy/engine/project.c
@@ -777,6 +777,13 @@ int project_readOption(char* s1, char* s2)
           SurchargeMethod = m;
           break;
 
+      // --- quality carried by reverse flow at outfalls (LAST or ZERO)
+      case OUTFALL_BACKFLOW_QUALITY:
+          m = findmatch(s2, BackflowQualWords);
+          if (m < 0) return error_setInpError(ERR_KEYWORD, s2);
+          ZeroOutfallBackflowQual = (m == BACKFLOW_ZERO);
+          break;
+
       case TEMPDIR: // Temporary Directory
         sstrncpy(TempDir, s2, MAXFNAME);
         break;
@@ -870,6 +877,7 @@ void setDefaults()
    InfilModel      = HORTON;           // Horton infiltration method
    RouteModel      = DW;               // Dynamic wave flow routing method
    SurchargeMethod = EXTRAN;           // Use EXTRAN method for surcharging
+   ZeroOutfallBackflowQual = FALSE;    // Outfall backflow keeps last quality
    CrownCutoff     = 0.96;             // Fractional pipe crown cutoff 
    AllowPonding    = FALSE;            // No ponding at nodes
    InertDamping    = PARTIAL_DAMPING;  // Partial inertial damping
diff --git a/src/legacy/engine/qualrout.c b/src/legacy/engine/qualrout.c
index 36e9ed56e..1cf5ae139 100644
--- a/src/legacy/engine/qualrout.c
+++ b/src/legacy/engine/qualrout.c
@@ -253,11 +253,17 @@ void findNodeQual(int j)
     }
 
     // --- otherwise concen. remains the same
+    //     (OUTFALL_BACKFLOW_QUALITY ZERO: a supplying outfall is a fresh
+    //      boundary — its held state reads zero so reverse flow re-enters
+    //      clean instead of carrying the last mix; see findLinkQual, which
+    //      draws the downstream node's quality on reverse flow)
     else
     {
         for (p = 0; p < Nobjects[POLLUT]; p++)
         {
-            if (Node[j].newDepth > ZeroDepth)
+            if ( ZeroOutfallBackflowQual && Node[j].type == OUTFALL )
+                Node[j].newQual[p] = 0.0;
+            else if (Node[j].newDepth > ZeroDepth)
                 Node[j].newQual[p] = Node[j].oldQual[p];
         }
     }
diff --git a/src/legacy/engine/swmm5.c b/src/legacy/engine/swmm5.c
index d549ca187..4096c9a4d 100644
--- a/src/legacy/engine/swmm5.c
+++ b/src/legacy/engine/swmm5.c
@@ -1115,13 +1115,27 @@ int EXPORT_OPENSWMMCORE_SOLVER_API swmm_close()
     if (IsOpenFlag)
         project_close();
     report_writeSysTime();
+    // Each handle is cleared as it is closed so a second swmm_close() is a
+    // no-op rather than a double fclose(). IsOpenFlag guards project_close()
+    // above but not these, and calling close twice is ordinary usage: a caller
+    // that closes explicitly to flush the report, then closes again in its own
+    // teardown, otherwise double-frees the FILE struct (glibc aborts with
+    // "free(): invalid pointer"). Reached whenever swmm_open() fails, since
+    // openFiles() has already opened Finp/Frpt by then.
     if (Finp.file != NULL)
+    {
         fclose(Finp.file);
+        Finp.file = NULL;
+    }
     if (Frpt.file != NULL)
+    {
         fclose(Frpt.file);
+        Frpt.file = NULL;
+    }
     if (Fout.file != NULL)
     {
         fclose(Fout.file);
+        Fout.file = NULL;
         if (Fout.mode == SCRATCH_FILE)
             remove(Fout.name);
     }
diff --git a/src/legacy/engine/text.h b/src/legacy/engine/text.h
index e105ffb6e..f34cb47cc 100644
--- a/src/legacy/engine/text.h
+++ b/src/legacy/engine/text.h
@@ -107,6 +107,9 @@
 #define  w_MIN_ROUTE_STEP    "MINIMUM_STEP"
 #define  w_NUM_THREADS       "THREADS"
 #define  w_SURCHARGE_METHOD  "SURCHARGE_METHOD"
+#define  w_OUTFALL_BF_QUAL   "OUTFALL_BACKFLOW_QUALITY"
+#define  w_LAST              "LAST"
+#define  w_ZERO              "ZERO"
 
 // Flow Units
 #define  w_CFS               "CFS"
diff --git a/src/legacy/engine/transect.c b/src/legacy/engine/transect.c
index 24b9acda7..c8e58ca36 100644
--- a/src/legacy/engine/transect.c
+++ b/src/legacy/engine/transect.c
@@ -346,10 +346,13 @@ int  setManning(double n[])
     {
         if ( n[i] < 0.0 ) return ERR_NUMBER;
     }
-    if ( n[3] == 0.0 ) return ERR_TRANSECT_MANNING;
+    // --- a zero component means "unchanged from the preceding NC record",
+    //     so only positive values update the active roughness; the missing
+    //     channel roughness error is raised after inheritance is applied
     if ( n[1] > 0.0 ) Nleft = n[1];
     if ( n[2] > 0.0 ) Nright = n[2];
     if ( n[3] > 0.0 ) Nchannel = n[3];
+    if ( Nchannel <= 0.0 ) return ERR_TRANSECT_MANNING;
     if ( Nleft == 0.0  ) Nleft = Nchannel;
     if ( Nright == 0.0 ) Nright = Nchannel;
     return 0;
diff --git a/src/tools/o4_differential/CMakeLists.txt b/src/tools/o4_differential/CMakeLists.txt
new file mode 100644
index 000000000..6d51ed1df
--- /dev/null
+++ b/src/tools/o4_differential/CMakeLists.txt
@@ -0,0 +1,54 @@
+#
+# src/tools/o4_differential/CMakeLists.txt
+#
+# A diagnostic driver for O4 — the API/CLI hydrology divergence.
+# Mirrors src/cli/CMakeLists.txt so the two link identically; the whole
+# point of the tool is that it differs from the CLI only in the sequence
+# it makes, not in how it was built.
+#
+
+add_executable(o4_differential
+    main.cpp
+)
+
+target_link_libraries(o4_differential
+    PRIVATE
+        openswmm_engine
+        openswmm::common
+)
+
+target_include_directories(o4_differential
+    PRIVATE
+        ${PROJECT_SOURCE_DIR}/include/openswmm/engine
+)
+
+set_target_properties(o4_differential
+    PROPERTIES
+        CXX_STANDARD 20
+        CXX_STANDARD_REQUIRED ON
+        OUTPUT_NAME "o4_differential"
+)
+
+# Land it beside the CLI in the build tree. Without this the binary stays in
+# src/tools/o4_differential/ while `openswmm` is in bin//, and the
+# protocol's own commands read as though the two sit together. This is the
+# only part of src/cli/CMakeLists.txt worth mirroring beyond the link line —
+# the install, RPATH and bundling rules there are for a shipped artefact and
+# this is a debugging instrument that is OFF by default.
+add_custom_command(TARGET o4_differential POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy
+        $
+        ${CMAKE_BINARY_DIR}/bin/$/$
+)
+
+# Windows finds its DLLs beside the exe or not at all; the CLI stages them the
+# same way. Untested here — this round ran on macOS only.
+if(WIN32)
+    add_custom_command(TARGET o4_differential POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            $
+            $
+            $
+        COMMAND_EXPAND_LISTS
+    )
+endif()
diff --git a/src/tools/o4_differential/main.cpp b/src/tools/o4_differential/main.cpp
new file mode 100644
index 000000000..f3ca69032
--- /dev/null
+++ b/src/tools/o4_differential/main.cpp
@@ -0,0 +1,313 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file main.cpp
+ * @brief `o4_differential` — the plain A/B driver O4's protocol §3 calls for.
+ *
+ * @details **O4:** the same parity deck delivered **7.25 in** to the ground
+ *          through `lifecycle_open_model` + `lifecycle_run_simulation` where
+ *          the CLI delivered **12.98 in**, from an identical 12.000 in of
+ *          precipitation — the packs barely melted. Three CLI builds agree
+ *          with each other and disagree with that run, **including one built
+ *          at the API run's own commit**, so the commit range is controlled
+ *          for and the execution path is the variable left standing.
+ *
+ * @par What this tool is FOR, and the variable it removes
+ *      Those two names are **MCP tool names, not engine entry points.** There
+ *      is no `lifecycle_run_simulation` anywhere in `src/`. So the measurement
+ *      was taken through the MCP server, and the server is a *third* variable
+ *      — its own stepping, its working directory, its process lifetime across
+ *      `close_model`/reopen.
+ *
+ *      This driver removes it. It runs the deck through the C API **in one
+ *      process, from one binary**, twice:
+ *
+ *        - **A** — the CLI's exact sequence, byte for byte
+ *          (`src/cli/main.cpp:76-131`).
+ *        - **B** — the same sequence with the differences a session driver
+ *          plausibly introduces, selectable so each can be tested alone.
+ *
+ *      If A and B agree, the C API is not the variable and the MCP server is
+ *      — which is a finding, and a much narrower place to look.
+ *
+ * @par What it deliberately does NOT do
+ *      It does not instrument `dhm`, `season` or `last_melt_doy_`. O4 §4 is
+ *      explicit that those three come *after* localisation, because the
+ *      hypothesis that motivated them is the one §2 eliminated. **Reading
+ *      them first is how a plain differential becomes a targeted hunt for a
+ *      cause that has already been ruled out.**
+ *
+ * @par Where to look in the output it produces
+ *      Each variant writes its own `.rpt` and `.out`. **The tool does not
+ *      parse or compare them** — it deliberately leaves that to `cmp` and
+ *      `diff`, which is the protocol's step 4, because a comparison written
+ *      into the instrument is a comparison nobody can check independently.
+ *
+ *      The `.rpt` is where O4's signature lives: the runoff continuity block
+ *      says *which reservoir* the water went to, and the divergence is
+ *      specifically `Snow Cover` against `Infiltration`. A binary `.out`
+ *      diff says only *that* two runs parted.
+ *
+ * @see plans/transport/O4_API_CLI_DIFFERENTIAL_2026-08-22.md
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "openswmm_engine.h"
+
+namespace {
+
+/// The ways a session driver can differ from the CLI while still making the
+/// same C API calls. Each is separately selectable: the point of a plain
+/// differential is that **one variable moves at a time**.
+struct Variant {
+    const char* name;
+    bool        chdir_elsewhere;   ///< run with cwd != the deck's directory
+    bool        reopen_first;      ///< open/close/open before stepping
+    bool        save_results;      ///< `start`'s only argument
+    bool        report_before_end; ///< call report() before end()
+};
+
+/// Restores the previous working directory on scope exit, so one variant
+/// cannot leak its cwd into the next and turn a one-variable differential
+/// into a two-variable one.
+class ScopedCwd {
+public:
+    explicit ScopedCwd(const std::filesystem::path& to)
+        : prev_(std::filesystem::current_path()), moved_(false) {
+        std::error_code ec;
+        std::filesystem::current_path(to, ec);
+        moved_ = !ec;
+    }
+    ~ScopedCwd() {
+        if (moved_) {
+            std::error_code ec;
+            std::filesystem::current_path(prev_, ec);
+        }
+    }
+    ScopedCwd(const ScopedCwd&) = delete;
+    ScopedCwd& operator=(const ScopedCwd&) = delete;
+    bool moved() const { return moved_; }
+private:
+    std::filesystem::path prev_;
+    bool moved_;
+};
+
+int runOnce(const char* inp, const char* rpt, const char* out,
+            const Variant& v, double* out_elapsed, long* out_steps) {
+    // The MCP server runs with a working directory that is NOT the deck's
+    // (`.../Projects/default`), and §3 names that as a suspect. Reproducing
+    // it needs the deck given as an ABSOLUTE path — which is what a session
+    // driver passes — so the move cannot be mistaken for a path-resolution
+    // failure. `..` is used rather than a fixed path so the tool has no
+    // machine-specific assumption in it.
+    std::unique_ptr cwd_guard;
+    if (v.chdir_elsewhere) {
+        cwd_guard = std::make_unique(
+            std::filesystem::temp_directory_path());
+        if (!cwd_guard->moved())
+            std::printf("  [%s] WARNING: could not change directory; this "
+                        "variant is now identical to `cli`\n", v.name);
+    }
+
+    SWMM_Engine e = swmm_engine_create();
+    if (e == nullptr) {
+        std::printf("  [%s] engine create FAILED\n", v.name);
+        return 1;
+    }
+
+    // A session driver that keeps a model open across calls has already
+    // opened and closed this deck at least once by the time it steps. That
+    // is a real difference from a fresh CLI process and costs one line to
+    // reproduce.
+    if (v.reopen_first) {
+        if (swmm_engine_open(e, inp, rpt, out, nullptr) == SWMM_OK)
+            swmm_engine_close(e);
+    }
+
+    int err = swmm_engine_open(e, inp, rpt, out, nullptr);
+    if (err != SWMM_OK) {
+        std::printf("  [%s] open FAILED: %s\n", v.name,
+                    swmm_get_last_error_msg(e));
+        swmm_engine_destroy(e);
+        return err;
+    }
+
+    err = swmm_engine_initialize(e);
+    if (err != SWMM_OK) {
+        std::printf("  [%s] initialize FAILED: %s\n", v.name,
+                    swmm_get_last_error_msg(e));
+        swmm_engine_close(e);
+        swmm_engine_destroy(e);
+        return err;
+    }
+
+    err = swmm_engine_start(e, v.save_results ? 1 : 0);
+    if (err != SWMM_OK) {
+        std::printf("  [%s] start FAILED: %s\n", v.name,
+                    swmm_get_last_error_msg(e));
+        swmm_engine_close(e);
+        swmm_engine_destroy(e);
+        return err;
+    }
+
+    double elapsed = 0.0;
+    long   steps   = 0;
+    while (true) {
+        err = swmm_engine_step(e, &elapsed);
+        if (err != SWMM_OK) {
+            std::printf("  [%s] step %ld FAILED: %s\n", v.name, steps,
+                        swmm_get_last_error_msg(e));
+            break;
+        }
+        if (elapsed <= 0.0) break;
+        ++steps;
+    }
+
+    // Order matters, and so does LOOKING AT WHAT THE ENGINE SAYS ABOUT IT.
+    //
+    // The first version of this driver discarded both return codes, and the
+    // round that ran it recorded `report()` before `end()` as "legal and
+    // silently lossy — no crash, no error code." There IS a code. An
+    // instrument that ignores a return value cannot tell "the engine allowed
+    // this" from "the engine refused and nobody asked".
+    //
+    // MEASURED, once the codes were printed — and it is not the call the
+    // correction predicted:
+    //
+    //   * `step()` sets `ENDED` when the run finishes (SWMMEngine.cpp:1177),
+    //     so by the time this driver reports, the engine is ALREADY ended.
+    //     `report()`'s `state != ENDED` guard (4924) therefore never fires:
+    //     **`report()` succeeds**, and sets `REPORTED` (4970).
+    //   * `end()` accepts only `RUNNING` or `ENDED` (4813). It sees
+    //     `REPORTED`. **`end()` is the call the engine refuses**, with
+    //     SWMM_ERR_WRONG_STATE (6).
+    //
+    // And the two artefacts have two different causes, separated by
+    // falsifier ii-b (let `end()` accept `REPORTED`):
+    //
+    //   * the `.out` is 24 bytes short because `end()` never wrote its
+    //     closing block — ii-b makes it byte-identical to `cli`;
+    //   * the `.rpt` says "All links are stable." and prints a flat
+    //     `300.000 - 300.000 sec` ladder because `report()` ran BEFORE
+    //     `end()` computed those two diagnostics — ii-b does NOT bring them
+    //     back, because by then the report is already written.
+    //
+    // Removing `report()`'s guard entirely (falsifier ii) changes nothing at
+    // all, which is how the attribution was settled rather than argued.
+    // Reported at the CALL, not after both. `swmm_get_last_error_msg` returns
+    // whatever the engine set most recently, so printing after the pair would
+    // caption a failing `report()` with a later `end()`'s message -- an
+    // instrument that mislabels which call failed is the same defect this
+    // file was corrected for, one step smaller.
+    auto call = [&](const char* what, int rc) {
+        if (rc != SWMM_OK)
+            std::printf("  [%s] %s returned %d: %s\n", v.name, what, rc,
+                        swmm_get_last_error_msg(e));
+        return rc;
+    };
+
+    if (v.report_before_end) {
+        call("report()", swmm_engine_report(e));
+        call("end()",    swmm_engine_end(e));
+    } else {
+        call("end()",    swmm_engine_end(e));
+        call("report()", swmm_engine_report(e));
+    }
+    call("close()", swmm_engine_close(e));
+
+    swmm_engine_destroy(e);
+
+    *out_elapsed = elapsed;
+    *out_steps   = steps;
+    return SWMM_OK;
+}
+
+void usage() {
+    std::printf(
+        "o4_differential — run one deck through the C API several ways.\n\n"
+        "  o4_differential  \n\n"
+        "Writes _.rpt / .out for each variant, then\n"
+        "leaves the comparison to the caller:\n\n"
+        "  cmp  _cli.out _.out\n"
+        "  diff _cli.rpt _.rpt\n\n"
+        "The `cli` variant is byte-for-byte the sequence in src/cli/main.cpp,\n"
+        "so `_cli.*` must match a real CLI run of the same deck. If\n"
+        "it does not, THAT is the finding and nothing below it means\n"
+        "anything.\n");
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {
+    if (argc < 3) { usage(); return argc < 2 ? 1 : 0; }
+
+    // Absolute, so the `elsewhere` variant tests the working directory and
+    // not the engine's ability to resolve a relative path from one.
+    std::error_code abs_ec;
+    const std::string inp =
+        std::filesystem::absolute(argv[1], abs_ec).string();
+    if (abs_ec) {
+        std::printf("cannot resolve %s: %s\n", argv[1], abs_ec.message().c_str());
+        return 1;
+    }
+    const std::string prefix =
+        std::filesystem::absolute(argv[2], abs_ec).string();
+
+    // One variable at a time. `cli` is the control and MUST reproduce a real
+    // CLI run; every other row changes exactly one thing against it.
+    const Variant variants[] = {
+        {"cli",        false, false, true,  false},
+        {"reopened",   false, true,  true,  false},
+        {"nosave",     false, false, false, false},
+        {"reportfirst",false, false, true,  true },
+        {"elsewhere",  true,  false, true,  false},
+    };
+
+    std::printf("o4_differential\n  deck: %s\n\n", inp.c_str());
+
+    int failures = 0;
+    for (const auto& v : variants) {
+        const std::string rpt = prefix + "_" + v.name + ".rpt";
+        const std::string out = prefix + "_" + v.name + ".out";
+        double elapsed = 0.0;
+        long   steps   = 0;
+        const int err = runOnce(inp.c_str(), rpt.c_str(), out.c_str(), v,
+                                &elapsed, &steps);
+        if (err != SWMM_OK) { ++failures; continue; }
+        std::printf("  %-12s steps=%-8ld rpt=%s\n", v.name, steps, rpt.c_str());
+    }
+
+    std::printf(
+        "\nNext, per O4 protocol step 4 — compare, do NOT instrument yet:\n"
+        "  cmp %s_cli.out %s_reopened.out\n"
+        "  diff %s_cli.rpt %s_reopened.rpt\n\n"
+        "and the control first:\n"
+        "  openswmm %s /tmp/real_cli.rpt /tmp/real_cli.out\n"
+        "  cmp /tmp/real_cli.out %s_cli.out\n",
+        prefix.c_str(), prefix.c_str(), prefix.c_str(), prefix.c_str(),
+        inp.c_str(), prefix.c_str());
+
+    return failures == 0 ? 0 : 1;
+}
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 85d8d1254..e8ded1b5e 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -112,6 +112,11 @@ endfunction()
 if(OPENSWMM_BUILD_UNIT_TESTS)
     add_subdirectory(unit)
 
+    # G1 — the two-zone groundwater numerical gates. Deliberately NOT under
+    # unit/: it needs no gtest and no model, so it can be built and run first
+    # when the kernel is under suspicion.
+    add_subdirectory(verification/gw2d_gates)
+
     # Legacy solver tests
     add_test(NAME test_legacy_solver_api
         COMMAND $
@@ -131,6 +136,20 @@ if(OPENSWMM_BUILD_UNIT_TESTS)
     add_test(NAME test_legacy_solver_storage_shapes
         COMMAND $
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/unit/legacy/engine/data)
+    # These two are built by add_solver_test() like the rest, but that helper
+    # only creates the executable -- ctest registration is this hand-kept list,
+    # so a target added there and not here BUILDS AND NEVER RUNS.
+    add_test(NAME test_legacy_solver_transect_nc
+        COMMAND $
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/unit/legacy/engine/data)
+    add_test(NAME test_legacy_solver_backflow_quality
+        COMMAND $
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/unit/legacy/engine/data)
+    # NOT the data directory: this one reads "./data/gage_scalefactor.inp",
+    # so its working directory is the PARENT of the others'.
+    add_test(NAME test_legacy_gage_scalefactor
+        COMMAND $
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/unit/legacy/engine)
     add_test(NAME test_legacy_output
         COMMAND $
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/unit/legacy/output/data)
@@ -143,9 +162,123 @@ if(OPENSWMM_BUILD_UNIT_TESTS)
         test_legacy_solver_shapes
         test_legacy_solver_expanded_api
         test_legacy_solver_storage_shapes
+        test_legacy_solver_transect_nc
+        test_legacy_gage_scalefactor
         test_legacy_output
         PROPERTIES LABELS "unit"
     )
+
+    # ---- Load-optimization gates -------------------------------------------
+    # Sources live under benchmarks/ but the gates belong here: neither needs
+    # Google Benchmark, and tests/benchmarks/ is only added when
+    # OPENSWMM_BUILD_BENCHMARKS is ON — a configuration that has
+    # enable_testing() off, so add_test() there would silently register
+    # nothing. See plans/MODEL_LOAD_INIT_OPTIMIZATION_PLAN_2026-08-12.md §0.4.
+
+    # parity_probe emits the .rpt / .out / written-back .inp that the parity
+    # gate diffs; the shipped CLI has no write-back flag.
+    add_executable(parity_probe ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks/parity_probe.cpp)
+    target_link_libraries(parity_probe PRIVATE openswmm_engine)
+    target_include_directories(parity_probe PRIVATE ${PROJECT_SOURCE_DIR}/include)
+    set_target_properties(parity_probe PROPERTIES
+        CXX_STANDARD 20
+        CXX_STANDARD_REQUIRED ON)
+    openswmm_stage_test_runtime_deps(parity_probe)
+
+    # bench_fv_closure: per-op cost of the explicit-FV cross-section closure
+    # (plans/FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11.md, Phase 0). Same
+    # reasoning as parity_probe: it needs no Google Benchmark, and the
+    # numbers must come from the SAME build the FV gates run in, so it is
+    # built here rather than only in the benchmarks-only tree. tests/benchmarks
+    # guards its own registration with `if(NOT TARGET ...)`.
+    if(NOT TARGET bench_fv_closure)
+        add_executable(bench_fv_closure ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks/bench_fv_closure.cpp)
+        # Same link rule as the unit tests, for the same reason: this TU
+        # includes src/engine/core/SWMMEngine.hpp and calls xsect::isOpen,
+        # xsect::setParams, link::translateShape, link::buildXSectParams and
+        # fv::buildGeometry, none of which are dllexported — the DLL is built
+        # with WINDOWS_EXPORT_ALL_SYMBOLS OFF, so on MSVC those are 8
+        # unresolved externals at link. parity_probe above can link
+        # openswmm_engine because it only touches the exported C API. Inside
+        # OPENSWMM_BUILD_UNIT_TESTS, so openswmm_engine_internal exists.
+        target_link_libraries(bench_fv_closure PRIVATE
+            $,openswmm_engine_internal,openswmm_engine>)
+        target_include_directories(bench_fv_closure PRIVATE ${PROJECT_SOURCE_DIR}/include)
+        if(OPENSWMM_FAST_XSECT_LOOKUP)
+            target_compile_definitions(bench_fv_closure PRIVATE SWMM_XSECT_FAST_LOOKUP)
+        endif()
+        set_target_properties(bench_fv_closure PROPERTIES
+            CXX_STANDARD 20
+            CXX_STANDARD_REQUIRED ON)
+        openswmm_stage_test_runtime_deps(bench_fv_closure)
+    endif()
+
+    # Determinism gate: two runs of the same build must produce identical
+    # artifacts. Without this, a `check` failure after an optimization could
+    # not be distinguished from run-to-run noise.
+    if(UNIX)
+        add_test(NAME load_parity_selfcheck
+            COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks/scripts/load_parity.sh
+                    selfcheck $)
+        set_tests_properties(load_parity_selfcheck PROPERTIES LABELS "unit")
+    endif()
+
+    # Generator gate: proves gen_load_bench.py still emits every corpus model.
+    # Uses the tiny --smoke sizes so it costs seconds, not gigabytes.
+    find_package(Python3 COMPONENTS Interpreter QUIET)
+    if(Python3_Interpreter_FOUND)
+        add_test(NAME bench_corpus_generator_smoke
+            COMMAND ${Python3_EXECUTABLE}
+                    ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks/scripts/gen_load_bench.py
+                    --smoke --force
+                    --out-dir ${CMAKE_CURRENT_BINARY_DIR}/corpus_smoke)
+        set_tests_properties(bench_corpus_generator_smoke PROPERTIES LABELS "unit")
+    endif()
+endif()
+
+# ---- D1 (program plan §C.1): the HydroCouple dependency's two checks ----
+if(OPENSWMM_BUILD_UNIT_TESTS)
+    # (a) The D-C6 guard: no engine target includes or links HydroCoupleSDK.
+    #     Registered in BOTH option states — the rule does not switch off with
+    #     the feature. Two-sided: the real tree must pass AND the planted
+    #     fixtures must fail, or the guard proves nothing (a guard that scans
+    #     nothing also "passes"). `prose_only` pins the other side: files that
+    #     state D-C6 name the SDK, and the guard must not fire on the word.
+    set(_d1_guard  ${PROJECT_SOURCE_DIR}/cmake/CheckNoHydroCoupleSDK.cmake)
+    set(_d1_fix    ${CMAKE_CURRENT_SOURCE_DIR}/unit/engine/data/d1_sdk_guard)
+    # The roots engine TARGETS are built from. Not the whole repository:
+    # tests/output alone is ~118k result files, docs/ and python/build are
+    # not target source, and a guard that takes minutes gets disabled.
+    set(_d1_roots
+        "${PROJECT_SOURCE_DIR}/src;${PROJECT_SOURCE_DIR}/include;${PROJECT_SOURCE_DIR}/cmake;${CMAKE_CURRENT_SOURCE_DIR}/unit;${CMAKE_CURRENT_SOURCE_DIR}/regression;${CMAKE_CURRENT_SOURCE_DIR}/benchmarks;${CMAKE_CURRENT_SOURCE_DIR}/verification;${CMAKE_CURRENT_SOURCE_DIR}/compile_check;${PROJECT_SOURCE_DIR}/python/openswmm;${PROJECT_SOURCE_DIR}/python/cmake")
+    set(_d1_files
+        "${PROJECT_SOURCE_DIR}/CMakeLists.txt;${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt;${PROJECT_SOURCE_DIR}/python/CMakeLists.txt")
+    add_test(NAME d1_no_hydrocouplesdk
+        COMMAND ${CMAKE_COMMAND} "-DROOTS=${_d1_roots}" "-DFILES=${_d1_files}"
+                "-DEXCLUDE=${_d1_fix}" -P ${_d1_guard})
+    add_test(NAME d1_guard_catches_planted_include
+        COMMAND ${CMAKE_COMMAND} -DROOTS=${_d1_fix}/planted_include -P ${_d1_guard})
+    add_test(NAME d1_guard_catches_planted_link
+        COMMAND ${CMAKE_COMMAND} -DROOTS=${_d1_fix}/planted_link -P ${_d1_guard})
+    add_test(NAME d1_guard_ignores_prose
+        COMMAND ${CMAKE_COMMAND} -DROOTS=${_d1_fix}/prose_only -P ${_d1_guard})
+    set_tests_properties(d1_guard_catches_planted_include d1_guard_catches_planted_link
+        PROPERTIES WILL_FAIL TRUE)
+    set_tests_properties(d1_no_hydrocouplesdk d1_guard_catches_planted_include
+        d1_guard_catches_planted_link d1_guard_ignores_prose PROPERTIES LABELS "unit")
+
+    # (b) Compile-check of every HydroCouple header, plus the pin's ABI as a
+    #     static_assert. Only with the option ON (the headers are absent
+    #     otherwise). An OBJECT library in ALL: if it builds, it passed; if the
+    #     headers found are not the pin's ABI, the build fails naming both.
+    if(OPENSWMM_WITH_HYDROCOUPLE)
+        add_library(openswmm_hydrocouple_header_check OBJECT
+            ${CMAKE_CURRENT_SOURCE_DIR}/compile_check/hydrocouple_headers.cpp)
+        target_link_libraries(openswmm_hydrocouple_header_check
+            PRIVATE HydroCouple::HydroCouple)
+        target_compile_definitions(openswmm_hydrocouple_header_check PRIVATE
+            OPENSWMM_HYDROCOUPLE_EXPECTED_ABI=${OPENSWMM_HYDROCOUPLE_EXPECTED_ABI})
+    endif()
 endif()
 
 # ---- Regression tests ----
diff --git a/tests/benchmarks/CMakeLists.txt b/tests/benchmarks/CMakeLists.txt
index c7582b80f..bcefb80c3 100644
--- a/tests/benchmarks/CMakeLists.txt
+++ b/tests/benchmarks/CMakeLists.txt
@@ -8,6 +8,7 @@
 #   bench_engine_vs_legacy      — wall-time comparison: new engine vs legacy
 #   bench_timeseries_lookup     — cursor-based vs linear scan for time series
 #   bench_hydraulics            — SIMD vs scalar routing kernel
+#   bench_xsect_eval            — IRREGULAR cross-section evaluator per-op cost
 #
 # See: docs/MASTER_IMPLEMENTATION_PLAN.md Phase 9
 #
@@ -46,3 +47,134 @@ endfunction()
 add_benchmark(bench_engine_vs_legacy   bench_engine_vs_legacy.cpp)
 add_benchmark(bench_timeseries_lookup  bench_timeseries_lookup.cpp)
 add_benchmark(bench_hydraulics         bench_hydraulics.cpp)
+
+# ---------------------------------------------------------------------------
+# bench_model_load — open()/initialize()/start() timings over the synthetic
+# scaling corpus (see plans/MODEL_LOAD_INIT_OPTIMIZATION_PLAN_2026-08-12.md).
+#
+# Not built with add_benchmark(): it discovers its models at run time and so
+# needs its own main(), which would clash with benchmark::benchmark_main.
+# ---------------------------------------------------------------------------
+add_executable(bench_model_load bench_model_load.cpp)
+
+target_link_libraries(bench_model_load
+    PRIVATE
+        benchmark::benchmark
+        openswmm_engine
+)
+
+target_include_directories(bench_model_load
+    PRIVATE
+        ${PROJECT_SOURCE_DIR}/include
+)
+
+set_target_properties(bench_model_load PROPERTIES
+    CXX_STANDARD 20
+    CXX_STANDARD_REQUIRED ON
+)
+
+add_custom_command(TARGET bench_model_load POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy
+        $
+        ${CMAKE_BINARY_DIR}/bin/$/$
+)
+
+# ---------------------------------------------------------------------------
+# bench_xsect_eval — per-op timings of the IRREGULAR cross-section evaluation
+# chain on the transect tables a real deck builds
+# (plans/XSECT_LOOKUP_ACCEL_PLAN.md phase 0/1 gates).
+#
+# Like bench_model_load it opens decks named on the command line and reports
+# CSV, so it needs its own main() and cannot use benchmark::benchmark_main.
+# It reaches into src/engine directly (XSectKernels/XSectBatch are internal
+# headers), which is why it links the engine target rather than the public API
+# alone.
+# ---------------------------------------------------------------------------
+add_executable(bench_xsect_eval bench_xsect_eval.cpp)
+
+target_link_libraries(bench_xsect_eval PRIVATE openswmm_engine)
+
+target_include_directories(bench_xsect_eval
+    PRIVATE
+        ${PROJECT_SOURCE_DIR}/include
+)
+
+# The bench times BOTH lookup variants' kernels through the engine it links, so
+# its TU must agree with the engine on which one is compiled in — otherwise the
+# fused-pair kernel it calls and the one the engine built disagree on the
+# normalization argument (y_full vs 1/y_full).
+if(OPENSWMM_FAST_XSECT_LOOKUP)
+    target_compile_definitions(bench_xsect_eval PRIVATE SWMM_XSECT_FAST_LOOKUP)
+endif()
+
+set_target_properties(bench_xsect_eval PROPERTIES
+    CXX_STANDARD 20
+    CXX_STANDARD_REQUIRED ON
+)
+
+add_custom_command(TARGET bench_xsect_eval POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy
+        $
+        ${CMAKE_BINARY_DIR}/bin/$/$
+)
+
+# ---------------------------------------------------------------------------
+# bench_fv_closure — per-op cost of the explicit-FV cross-section closure
+# (FvKernels.hpp) on the geometries the mesh builder builds: the rows every
+# candidate closure kernel reports against, and the ns/call that turns the
+# solver's [PERF-FV] closure-call counters into a share of the routing step
+# (plans/FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11.md, Phase 0 / Phase 2a″).
+# Own main(), CSV output, reaches into src/engine — same shape as
+# bench_xsect_eval above.
+# ---------------------------------------------------------------------------
+if(NOT TARGET bench_fv_closure)
+    add_executable(bench_fv_closure bench_fv_closure.cpp)
+
+    target_link_libraries(bench_fv_closure PRIVATE openswmm_engine)
+
+    target_include_directories(bench_fv_closure
+        PRIVATE
+            ${PROJECT_SOURCE_DIR}/include
+    )
+
+    if(OPENSWMM_FAST_XSECT_LOOKUP)
+        target_compile_definitions(bench_fv_closure PRIVATE SWMM_XSECT_FAST_LOOKUP)
+    endif()
+
+    set_target_properties(bench_fv_closure PROPERTIES
+        CXX_STANDARD 20
+        CXX_STANDARD_REQUIRED ON
+    )
+
+    add_custom_command(TARGET bench_fv_closure POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy
+            $
+            ${CMAKE_BINARY_DIR}/bin/$/$
+    )
+endif()
+
+# The two load-optimization ctest gates are registered in tests/CMakeLists.txt,
+# not here: they need no Google Benchmark, and this directory is only added
+# when OPENSWMM_BUILD_BENCHMARKS is ON — a build that has enable_testing() off,
+# where add_test() would register nothing.
+#
+# parity_probe itself is still wanted here. A benchmarks-only build is the
+# RELEASE configuration the numbers come from, and parity must be checked in
+# the same configuration it was recorded in — comparing a Release reference
+# against a Debug run would flag optimizer-level FP differences as parity
+# failures. The guard keeps the two definitions from colliding in a build that
+# has both flags on.
+if(NOT TARGET parity_probe)
+    add_executable(parity_probe parity_probe.cpp)
+    target_link_libraries(parity_probe PRIVATE openswmm_engine)
+    target_include_directories(parity_probe PRIVATE ${PROJECT_SOURCE_DIR}/include)
+    set_target_properties(parity_probe PROPERTIES
+        CXX_STANDARD 20
+        CXX_STANDARD_REQUIRED ON
+    )
+    add_custom_command(TARGET parity_probe POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy
+            $
+            ${CMAKE_BINARY_DIR}/bin/$/$
+    )
+endif()
diff --git a/tests/benchmarks/bench_fv_closure.cpp b/tests/benchmarks/bench_fv_closure.cpp
new file mode 100644
index 000000000..a23048483
--- /dev/null
+++ b/tests/benchmarks/bench_fv_closure.cpp
@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file bench_fv_closure.cpp
+ * @brief Per-op cost of the explicit-FV cross-section closure (FvKernels.hpp)
+ *        on the geometries NetworkMeshBuilder::buildGeometry builds.
+ *
+ * @details Phase 0 of plans/FV1D_CLOSURE_KERNEL_PERF_PLAN_2026-09-11.md. The
+ *          solver's closure-call counters ([PERF-FV] n.area/n.width/n.i1/
+ *          n.hydrad/n.invert) × the ns/call measured here is how the closure's
+ *          share of a routing step is sized; and every candidate replacement
+ *          kernel reports against these rows in the same binary.
+ *
+ *          Ops, named after how the solver calls them:
+ *
+ *            area              areaOfDepth(g, h)
+ *            width             widthOfDepth(g, h)
+ *            hydrad            hydRadOfDepth(g, h)
+ *            area_i1           i1OfDepth(g, h, areaOfDepth(g, h)) — the pair
+ *                              faceSide evaluates for the cell's own side
+ *            faceside          one side of a first-order face flux: area+I₁ at
+ *                              the cell depth, then area+width+I₁ at the
+ *                              reconstructed depth (2 area, 1 width, 2 I₁)
+ *            invert            depthOfArea(g, a) — Newton on the closure cubic
+ *            roundtrip         depthOfArea(g, areaOfDepth(g, h))
+ *            eval_fused        closureEval(g.closure_tbl, h) — A, T, I₁ from
+ *                              one panel locate (what faceSide and the
+ *                              per-cell cache call)
+ *
+ *          Inputs are precomputed outside the timed region: a temporally
+ *          coherent random walk in h over [0, 1.5·y_full] (the substep-to-
+ *          substep pattern the solver actually presents, slot band included)
+ *          and the areas of those depths for the inverse ops. A deterministic
+ *          LCG, so two runs sweep byte-identical inputs.
+ *
+ *          Output is CSV on stdout: shape,op,calls,reps,ns_med,ns_min,ns_max,
+ *          followed by one `# roundtrip_max_rel` comment line per shape (the
+ *          |depthOfArea(areaOfDepth(h)) − h| / y_full maximum over the sweep,
+ *          recorded so the accuracy of the inverse rides along with its cost).
+ *
+ * Usage:
+ *   bench_fv_closure [--slot-celerity C] [--samples N] [--deck file.inp ...]
+ *
+ *   With no deck the built-in analytic shapes are timed. Each --deck adds its
+ *   IRREGULAR / STREET links (through link::buildXSectParams, exactly as the
+ *   mesh builder sees them) as one row per link, capped at 64 links per deck.
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../src/engine/core/SWMMEngine.hpp"
+#include "../../src/engine/core/SimulationContext.hpp"
+#include "../../src/engine/hydraulics/Link.hpp"
+#include "../../src/engine/hydraulics/XSectBatch.hpp"
+#include "../../src/engine/hydraulics/fv/FvKernels.hpp"
+#include "../../src/engine/hydraulics/fv/NetworkMeshBuilder.hpp"
+
+namespace {
+
+using openswmm::XSectParams;
+using openswmm::XSectShape;
+using openswmm::fv::FvGeometry;
+namespace k = openswmm::fv::kernels;
+
+volatile double g_sink = 0.0;   // defeats DCE across every timed loop
+
+constexpr int kReps = 9;        // repetitions of the whole sweep; median reported
+
+struct Timed {
+    double ns_med, ns_min, ns_max;
+};
+
+template 
+Timed time_sweep(std::size_t calls, F&& fn) {
+    std::vector per_call(kReps);
+    for (int r = 0; r < kReps; ++r) {
+        const auto t0 = std::chrono::steady_clock::now();
+        fn();
+        const auto t1 = std::chrono::steady_clock::now();
+        per_call[static_cast(r)] =
+            std::chrono::duration(t1 - t0).count() /
+            static_cast(calls);
+    }
+    std::sort(per_call.begin(), per_call.end());
+    return {per_call[kReps / 2], per_call.front(), per_call.back()};
+}
+
+void report(const std::string& shape, const char* op, std::size_t calls, Timed t) {
+    std::printf("%s,%s,%zu,%d,%.2f,%.2f,%.2f\n",
+                shape.c_str(), op, calls, kReps, t.ns_med, t.ns_min, t.ns_max);
+}
+
+/// One named geometry under test.
+struct Case {
+    std::string name;
+    FvGeometry  g;
+};
+
+
+/// Analytic shape from legacy-order geom1..4 (the [XSECTIONS] columns).
+Case analytic(const char* name, XSectShape type, double p0, double p1 = 0.0,
+              double p2 = 0.0, double p3 = 0.0, double slot_celerity = 100.0) {
+    Case c;
+    c.name = name;
+    XSectParams xs;
+    xs.type = static_cast(type);
+    double p[4] = {p0, p1, p2, p3};
+    openswmm::xsect::setParams(xs, xs.type, p, 1.0);
+    openswmm::fv::buildGeometry(xs, openswmm::xsect::isOpen(xs.type),
+                                slot_celerity, c.g);
+    return c;
+}
+
+/// Deterministic LCG in [0, 1).
+struct Lcg {
+    unsigned long long s = 0x9E3779B97F4A7C15ULL;
+    double next() {
+        s = s * 6364136223846793005ULL + 1442695040888963407ULL;
+        return static_cast(s >> 11) * (1.0 / 9007199254740992.0);
+    }
+};
+
+/// A coherent random walk in depth over [0, h_max]: each step moves by at most
+/// ±step. This is the substep-to-substep pattern a cell presents, and it is
+/// what keeps the bracket/locate cost honest (a uniform sweep would be the
+/// pessimistic control; both are reported).
+std::vector walk(int n, double h_max, double step, Lcg& rng) {
+    std::vector h(static_cast(n));
+    double x = 0.4 * h_max;
+    for (int i = 0; i < n; ++i) {
+        x += step * (2.0 * rng.next() - 1.0);
+        if (x < 0.0) x = -x;
+        if (x > h_max) x = 2.0 * h_max - x;
+        h[static_cast(i)] = x;
+    }
+    return h;
+}
+
+void bench_case(const Case& c, int n_samples, Lcg& rng) {
+    const FvGeometry& g = c.g;
+    if (!(g.y_full > 0.0) || !(g.a_crown > 0.0)) {
+        std::fprintf(stderr, "%s: degenerate geometry — skipped\n", c.name.c_str());
+        return;
+    }
+
+    // Inputs, outside the timed region. The walk covers the slot band and a
+    // stretch above the crown (1.5·y_full), because both are on the hot path
+    // of a surcharging network.
+    const std::vector hs = walk(n_samples, 1.5 * g.y_full, 0.02 * g.y_full, rng);
+    std::vector hstar(hs.size());
+    std::vector as(hs.size());
+    for (std::size_t i = 0; i < hs.size(); ++i) {
+        hstar[i] = 0.9 * hs[i];                       // a reconstructed depth
+        as[i]    = k::areaOfDepth(g, hs[i]);          // the inverse's input
+    }
+    const std::size_t calls = hs.size();
+
+    report(c.name, "area", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) acc += k::areaOfDepth(g, h);
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "width", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) acc += k::widthOfDepth(g, h);
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "hydrad", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) acc += k::hydRadOfDepth(g, h);
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "area_i1", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) {
+            const double a = k::areaOfDepth(g, h);
+            acc += a + k::i1OfDepth(g, h, a);
+        }
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "faceside", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (std::size_t i = 0; i < hs.size(); ++i) {
+            const double h = hs[i];
+            const double i1_raw = (h > k::kDryDepth)
+                ? k::i1OfDepth(g, h, k::areaOfDepth(g, h)) : 0.0;
+            const double hst = hstar[i];
+            if (hst <= k::kDryDepth) { acc += i1_raw; continue; }
+            const double a = k::areaOfDepth(g, hst);
+            const double cc = k::celerity(a, k::widthOfDepth(g, hst));
+            acc += i1_raw + a + cc + k::i1OfDepth(g, hst, a);
+        }
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "invert", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double a : as) acc += k::depthOfArea(g, a);
+        g_sink = g_sink + acc;
+    }));
+    report(c.name, "roundtrip", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) acc += k::depthOfArea(g, k::areaOfDepth(g, h));
+        g_sink = g_sink + acc;
+    }));
+
+    // The fused evaluation: A, T and I₁ from one panel locate — what
+    // faceSide and the per-cell cache call.
+    report(c.name, "eval_fused", calls, time_sweep(calls, [&] {
+        double acc = 0.0;
+        for (double h : hs) {
+            const k::ClosureEval e = k::closureEval(g.closure_tbl, h);
+            acc += e.a + e.t + e.i1;
+        }
+        g_sink = g_sink + acc;
+    }));
+
+    // Accuracy of the inverse over the same sweep, so cost and correctness
+    // are read side by side.
+    double max_rel = 0.0;
+    for (double h : hs) {
+        const double back = k::depthOfArea(g, k::areaOfDepth(g, h));
+        max_rel = std::max(max_rel, std::fabs(back - h) / g.y_full);
+    }
+    std::printf("# %s roundtrip_max_rel=%.3e y_full=%.6g a_crown=%.6g t_slot=%.6g\n",
+                c.name.c_str(), max_rel, g.y_full, g.a_crown, g.t_slot);
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    double slot_celerity = 100.0;
+    int n_samples = 4096;
+    std::vector decks;
+    for (int i = 1; i < argc; ++i) {
+        if (std::strcmp(argv[i], "--slot-celerity") == 0 && i + 1 < argc)
+            slot_celerity = std::atof(argv[++i]);
+        else if (std::strcmp(argv[i], "--samples") == 0 && i + 1 < argc)
+            n_samples = std::atoi(argv[++i]);
+        else if (std::strcmp(argv[i], "--deck") == 0 && i + 1 < argc)
+            decks.emplace_back(argv[++i]);
+        else {
+            std::fprintf(stderr,
+                "usage: %s [--slot-celerity C] [--samples N] [--deck f.inp ...]\n",
+                argv[0]);
+            return 2;
+        }
+    }
+
+    std::printf("shape,op,calls,reps,ns_med,ns_min,ns_max\n");
+    Lcg rng;
+
+    // The dominant sewer shapes first, then the ones whose closed forms the
+    // exact-geometry program will replace, in the 3–5 ft class.
+    const Case cases[] = {
+        analytic("circular_3ft",      XSectShape::CIRCULAR,      3.0, 0.0, 0.0, 0.0, slot_celerity),
+        analytic("force_main_3ft",    XSectShape::FORCE_MAIN,    3.0, 120.0, 0.0, 0.0, slot_celerity),
+        analytic("rect_closed_4x3",   XSectShape::RECT_CLOSED,   3.0, 4.0, 0.0, 0.0, slot_celerity),
+        analytic("rect_open_10x5",    XSectShape::RECT_OPEN,     5.0, 10.0, 0.0, 0.0, slot_celerity),
+        analytic("trapezoid_5_4_2_2", XSectShape::TRAPEZOIDAL,   5.0, 4.0, 2.0, 2.0, slot_celerity),
+        analytic("triangular_5x10",   XSectShape::TRIANGULAR,    5.0, 10.0, 0.0, 0.0, slot_celerity),
+        analytic("horiz_ellipse_3x4", XSectShape::HORIZ_ELLIPSE, 3.0, 4.0, 0.0, 0.0, slot_celerity),
+        analytic("eggshaped_3ft",     XSectShape::EGGSHAPED,     3.0, 0.0, 0.0, 0.0, slot_celerity),
+        analytic("parabolic_5x10",    XSectShape::PARABOLIC,     5.0, 10.0, 0.0, 0.0, slot_celerity),
+    };
+    for (const Case& c : cases) bench_case(c, n_samples, rng);
+
+    for (const auto& deck : decks) {
+        openswmm::SWMMEngine eng;
+        const std::string rpt = deck + ".benchrpt";
+        if (eng.open(deck.c_str(), rpt.c_str(), nullptr) != 0) {
+            std::fprintf(stderr, "open(%s) failed — skipped\n", deck.c_str());
+            continue;
+        }
+        auto& ctx = eng.context();
+        const std::string stem = std::filesystem::path(deck).stem().string();
+        int taken = 0;
+        for (int j = 0; j < ctx.n_links() && taken < 64; ++j) {
+            const auto uj = static_cast(j);
+            const auto shape = ctx.links.xsect_shape[uj];
+            if (shape != openswmm::XsectShape::IRREGULAR &&
+                shape != openswmm::XsectShape::STREET_XSECT)
+                continue;
+            ctx.links.xsect_batch_shape[uj] = openswmm::link::translateShape(shape);
+            XSectParams xs =
+                openswmm::link::buildXSectParams(ctx.links, uj, &ctx.transect_tables);
+            if (!(xs.a_full > 0.0) || !(xs.y_full > 0.0)) continue;
+            Case c;
+            c.name = stem + ":L" + std::to_string(j);
+            openswmm::fv::buildGeometry(xs, openswmm::xsect::isOpen(xs.type),
+                                        slot_celerity, c.g);
+            bench_case(c, n_samples, rng);
+            ++taken;
+        }
+        if (taken == 0)
+            std::fprintf(stderr, "%s: no IRREGULAR/STREET links — nothing timed\n",
+                         stem.c_str());
+    }
+    return 0;
+}
diff --git a/tests/benchmarks/bench_model_load.cpp b/tests/benchmarks/bench_model_load.cpp
new file mode 100644
index 000000000..986533922
--- /dev/null
+++ b/tests/benchmarks/bench_model_load.cpp
@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file bench_model_load.cpp
+ * @brief Model load / initialization benchmark (optimization plan Phase 0.3).
+ *
+ * @details The window a user experiences between clicking Run and the first
+ *          routing step is open() + initialize() + start(). This benchmark
+ *          times three cuts of that window for every model in the synthetic
+ *          corpus, so an optimization can be attributed to the phase it
+ *          actually changed:
+ *
+ *          | Cut         | Calls                                          |
+ *          |-------------|------------------------------------------------|
+ *          | `open`      | open → close                                   |
+ *          | `open_init` | open → initialize → close                      |
+ *          | `full`      | open → initialize → start → end → report → close |
+ *
+ *          No stepping happens in any cut — this measures load, not routing.
+ *
+ *          Models are discovered at run time from the corpus directory rather
+ *          than hard-coded, because the corpus is generated on demand and is
+ *          deliberately not committed (the large ones are hundreds of MB). Set
+ *          `OPENSWMM_BENCH_CORPUS` to point elsewhere; the default is
+ *          `tests/benchmarks/generated` relative to the working directory.
+ *
+ *          Peak RSS is reported as a counter. It is the process high-water
+ *          mark from getrusage(), so it is monotonic across iterations within
+ *          one process — read it as "this model needed at least this much",
+ *          and compare it between runs of the same single model, not between
+ *          benchmarks inside one run.
+ *
+ * @author   Caleb Buahin 
+ * @license  Apache-2.0
+ */
+
+#include 
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include 
+
+#include 
+
+namespace {
+
+namespace fs = std::filesystem;
+
+/** @brief Which calls a benchmark iteration makes. */
+enum class Cut { Open, OpenInit, Full };
+
+/** @returns process peak resident set size in bytes, 0 if unavailable. */
+std::size_t peak_rss_bytes() {
+    rusage ru{};
+    if (getrusage(RUSAGE_SELF, &ru) != 0) return 0;
+#if defined(__APPLE__)
+    return static_cast(ru.ru_maxrss);          // bytes
+#else
+    return static_cast(ru.ru_maxrss) * 1024u;  // kilobytes
+#endif
+}
+
+/** @brief Scratch output paths — the .rpt/.out content is not of interest. */
+std::string scratch(const std::string& stem, const char* ext) {
+    return (fs::temp_directory_path() / ("bench_load_" + stem + ext)).string();
+}
+
+/**
+ * @brief One iteration of the requested cut.
+ * @returns false if the engine rejected the model, which fails the benchmark
+ *          loudly instead of reporting a fast time for work that never ran.
+ */
+bool run_cut(const std::string& inp, const std::string& stem, Cut cut) {
+    SWMM_Engine eng = swmm_engine_create();
+    if (eng == nullptr) return false;
+
+    const std::string rpt = scratch(stem, ".rpt");
+    const std::string out = scratch(stem, ".out");
+
+    bool ok = swmm_engine_open(eng, inp.c_str(), rpt.c_str(), out.c_str(),
+                               nullptr) == SWMM_OK;
+    if (ok && cut != Cut::Open) {
+        ok = swmm_engine_initialize(eng) == SWMM_OK;
+    }
+    if (ok && cut == Cut::Full) {
+        ok = swmm_engine_start(eng, 1) == SWMM_OK;
+        // Deliberately no step() calls — this is a load benchmark.
+        if (ok) ok = swmm_engine_end(eng) == SWMM_OK;
+        if (ok) ok = swmm_engine_report(eng) == SWMM_OK;
+    }
+    swmm_engine_close(eng);
+    swmm_engine_destroy(eng);
+    return ok;
+}
+
+void bm_load(benchmark::State& state, std::string inp, std::string stem,
+             Cut cut) {
+    for (auto _ : state) {
+        if (!run_cut(inp, stem, cut)) {
+            state.SkipWithError("engine rejected the model");
+            break;
+        }
+    }
+    state.counters["peak_rss_MB"] = benchmark::Counter(
+        static_cast(peak_rss_bytes()) / (1024.0 * 1024.0));
+    state.SetLabel(stem);
+}
+
+/**
+ * @brief Repetition count, from OPENSWMM_BENCH_REPS (default 5).
+ * @details Not --benchmark_repetitions: Google Benchmark only consults that
+ *          flag when the benchmark itself requested 0 repetitions, so a
+ *          registered Repetitions(n) silently wins over the command line. An
+ *          env var keeps the knob honest. Minimum 2, because single-repetition
+ *          runs emit no _median aggregate row for the capture script to read.
+ */
+int repetitions_from_env() {
+    const char* s = std::getenv("OPENSWMM_BENCH_REPS");
+    if (s == nullptr) return 5;
+    const int n = std::atoi(s);
+    return n >= 2 ? n : 2;
+}
+
+const char* cut_suffix(Cut c) {
+    switch (c) {
+        case Cut::Open:     return "open";
+        case Cut::OpenInit: return "open_init";
+        case Cut::Full:     return "full";
+    }
+    return "?";
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    benchmark::Initialize(&argc, argv);
+
+    const char* env = std::getenv("OPENSWMM_BENCH_CORPUS");
+    const fs::path corpus = env != nullptr
+        ? fs::path(env)
+        : fs::path("tests") / "benchmarks" / "generated";
+
+    std::error_code ec;
+    if (!fs::is_directory(corpus, ec)) {
+        std::fprintf(stderr,
+            "bench_model_load: corpus directory '%s' not found.\n"
+            "Generate it first:\n"
+            "  python3 tests/benchmarks/scripts/gen_load_bench.py\n"
+            "or point OPENSWMM_BENCH_CORPUS at an existing one.\n",
+            corpus.string().c_str());
+        return 1;
+    }
+
+    std::vector models;
+    for (const auto& e : fs::directory_iterator(corpus, ec)) {
+        if (e.is_regular_file(ec) && e.path().extension() == ".inp")
+            models.push_back(e.path());
+    }
+    // directory_iterator order is unspecified; sort so successive runs report
+    // in the same order and diffs between result files stay readable.
+    std::sort(models.begin(), models.end());
+
+    if (models.empty()) {
+        std::fprintf(stderr, "bench_model_load: no .inp files in '%s'\n",
+                     corpus.string().c_str());
+        return 1;
+    }
+
+    const int reps = repetitions_from_env();
+
+    for (const auto& m : models) {
+        const std::string stem = m.stem().string();
+        const std::string inp  = m.string();
+        for (const Cut cut : {Cut::Open, Cut::OpenInit, Cut::Full}) {
+            const std::string name =
+                "BM_Load/" + stem + "/" + cut_suffix(cut);
+            benchmark::RegisterBenchmark(
+                name.c_str(),
+                [inp, stem, cut](benchmark::State& st) {
+                    bm_load(st, inp, stem, cut);
+                })
+                ->Unit(benchmark::kMillisecond)
+                ->UseRealTime()
+                ->MinTime(0.5)
+                ->Repetitions(reps)
+                ->ReportAggregatesOnly(true);
+        }
+    }
+
+    benchmark::RunSpecifiedBenchmarks();
+    benchmark::Shutdown();
+    return 0;
+}
diff --git a/tests/benchmarks/bench_xsect_eval.cpp b/tests/benchmarks/bench_xsect_eval.cpp
new file mode 100644
index 000000000..253bbbd25
--- /dev/null
+++ b/tests/benchmarks/bench_xsect_eval.cpp
@@ -0,0 +1,370 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file bench_xsect_eval.cpp
+ * @brief Microbenchmark of the IRREGULAR cross-section evaluation chain on
+ *        REAL transect tables (plans/XSECT_LOOKUP_ACCEL_PLAN.md, phase 0).
+ *
+ * @details Opens one or more decks through the real engine, builds the same
+ *          XSectParams the routing paths use (link::buildXSectParams, table
+ *          pointers into ctx.transect_tables), and times each evaluator the
+ *          way the solvers call it:
+ *
+ *            fwd_AofY / fwd_WofY / fwd_RofY   uniform-grid lookup (lookup_exact
+ *                                             via XsectEval — the scalar/FV form)
+ *            inv_YofA                         binary-search invLookup
+ *            SofA                             a * RofA^(2/3) (one inv + one fwd + pow)
+ *            newton_AofS                      the full Newton chain (getSofA +
+ *                                             central-difference dSdA per iter)
+ *            brent_depthOfArea                faithful replica of the FV
+ *                                             inversion (FvKernels.hpp:316):
+ *                                             bisection/secant on AofY with the
+ *                                             same 1e-10*a_full exit, so the
+ *                                             3-6 forward evals per call are
+ *                                             reproduced (documented replica,
+ *                                             not the shipped symbol)
+ *            gather_area                      the batch perlink_tabulated
+ *                                             shape: per-element table-pointer
+ *                                             gather then one area lookup
+ *            batch_AR_2pass / batch_AR_fused  the DW STEP-D shape: area and
+ *                                             hyd-radius over a whole group,
+ *                                             as two perlink_tabulated passes
+ *                                             (pre-A2) vs one fused pass
+ *            inv_YofA_bisect                  inv_YofA with the A1 bucket maps
+ *                                             unbound — the pre-A1 locate()
+ *
+ *          The `*_bisect` / `*_2pass` variants are the PRE-change code paths,
+ *          kept compiled here so each accelerated op reports against its own
+ *          baseline in the same binary and the same run.
+ *
+ *          Output is CSV on stdout: deck,op,calls,reps,ns_med,ns_min,ns_max.
+ *          Median over kReps repetitions of the whole input sweep; a volatile
+ *          sink defeats dead-code elimination.
+ *
+ *          --dump-tables  instead writes one CSV per transect (51-row
+ *          area/hrad/width tables + full-depth properties + the RAW store
+ *          stations/elevations), for offline analysis of the engine-built
+ *          tables (a Python reimplementation of buildTables would not do: the
+ *          hrad conveyance back-solve and legacy dy accumulation are parity
+ *          traps).
+ *
+ * Usage:
+ *   bench_xsect_eval deck1.inp [deck2.inp ...]
+ *   bench_xsect_eval --dump-tables out_dir deck1.inp [deck2.inp ...]
+ *
+ * @author   Caleb Buahin 
+ * @copyright Copyright (c) 2026 Caleb Buahin. All rights reserved.
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#include "../../src/engine/core/SWMMEngine.hpp"
+#include "../../src/engine/core/SimulationContext.hpp"
+#include "../../src/engine/hydraulics/Link.hpp"
+#include "../../src/engine/hydraulics/XSectBatch.hpp"
+#include "../../src/engine/hydraulics/XSectKernels.hpp"
+
+namespace {
+
+using openswmm::SimulationContext;
+using openswmm::SWMMEngine;
+using openswmm::XSectParams;
+using openswmm::xsect::XsectEval;
+
+volatile double g_sink = 0.0;   // defeats DCE across every timed loop
+
+constexpr int kReps = 9;        // repetitions of the whole sweep; median reported
+
+struct Timed {
+    double ns_med, ns_min, ns_max;
+};
+
+/// Time fn() (one full sweep of `calls` evaluator invocations) kReps times.
+template 
+Timed time_sweep(std::size_t calls, F&& fn) {
+    std::vector per_call(kReps);
+    for (int r = 0; r < kReps; ++r) {
+        const auto t0 = std::chrono::steady_clock::now();
+        fn();
+        const auto t1 = std::chrono::steady_clock::now();
+        per_call[static_cast(r)] =
+            std::chrono::duration(t1 - t0).count() /
+            static_cast(calls);
+    }
+    std::sort(per_call.begin(), per_call.end());
+    return {per_call[kReps / 2], per_call.front(), per_call.back()};
+}
+
+void report(const std::string& deck, const char* op, std::size_t calls, Timed t) {
+    std::printf("%s,%s,%zu,%d,%.2f,%.2f,%.2f\n",
+                deck.c_str(), op, calls, kReps, t.ns_med, t.ns_min, t.ns_max);
+}
+
+/// Faithful replica of FvKernels.hpp depthOfArea: bracketed bisection/secant
+/// on f(y) = AofY(y) - a with the FV exit tolerance (|f| <= 1e-10 * a_full or
+/// 60 iterations). Kept here so the bench does not need FvGeometry plumbing;
+/// the iteration count and per-iteration cost (one forward area lookup) match
+/// the shipped inversion's 3-6 evals per call on smooth sections.
+double brent_depth_of_area(const XsectEval& ev, const XSectParams& xs, double a) {
+    if (a <= 0.0) return 0.0;
+    if (a >= xs.a_full) return xs.y_full;
+    double lo = 0.0, hi = xs.y_full;
+    double flo = -a, fhi = xs.a_full - a;
+    double y = hi * (a / xs.a_full);   // proportional first guess
+    const double tol = 1e-10 * xs.a_full;
+    for (int it = 0; it < 60; ++it) {
+        const double f = ev.getAofY(xs, y) - a;
+        if (std::fabs(f) <= tol) return y;
+        if (f > 0.0) { hi = y; fhi = f; }
+        else         { lo = y; flo = f; }
+        // secant step, bisection fallback (Brent-lite, same eval count regime)
+        const double denom = fhi - flo;
+        double ynew = (denom != 0.0) ? (lo * fhi - hi * flo) / denom
+                                     : 0.5 * (lo + hi);
+        if (!(ynew > lo && ynew < hi)) ynew = 0.5 * (lo + hi);
+        y = ynew;
+    }
+    return y;
+}
+
+int dump_tables(const SimulationContext& ctx, const std::string& deck_stem,
+                const std::filesystem::path& out_dir) {
+    std::filesystem::create_directories(out_dir);
+    const int nt = ctx.transects.count();
+    for (int t = 0; t < nt; ++t) {
+        const auto ut = static_cast(t);
+        if (ut >= ctx.transect_tables.size()) break;
+        const auto& td = ctx.transect_tables[ut];
+        const auto path = out_dir / (deck_stem + "_" + td.name + ".csv");
+        FILE* f = std::fopen(path.string().c_str(), "w");
+        if (!f) { std::fprintf(stderr, "cannot write %s\n", path.string().c_str()); return 1; }
+        std::fprintf(f, "# transect,%s\n# deck,%s\n", td.name.c_str(), deck_stem.c_str());
+        std::fprintf(f, "# y_full,%.17g\n# a_full,%.17g\n# r_full,%.17g\n# w_max,%.17g\n",
+                     td.y_full, td.a_full, td.r_full, td.w_max);
+        std::fprintf(f, "# s_max,%.17g\n# a_max,%.17g\n", td.s_max, td.a_max);
+        std::fprintf(f, "# x_left_bank,%.17g\n# x_right_bank,%.17g\n",
+                     td.x_left_bank, td.x_right_bank);
+        std::fprintf(f, "# n_left,%.17g\n# n_right,%.17g\n# n_channel,%.17g\n",
+                     td.n_left, td.n_right, td.n_channel);
+        // RAW store data (display units) — what [TRANSECTS] round-trips.
+        std::fprintf(f, "# raw_stations");
+        for (double s : ctx.transects.stations[ut]) std::fprintf(f, ",%.17g", s);
+        std::fprintf(f, "\n# raw_elevations");
+        for (double e : ctx.transects.elevations[ut]) std::fprintf(f, ",%.17g", e);
+        std::fprintf(f, "\nidx,area_norm,hrad_norm,width_norm\n");
+        for (int i = 0; i < openswmm::transect::N_TRANSECT_TBL; ++i)
+            std::fprintf(f, "%d,%.17g,%.17g,%.17g\n",
+                         i, td.area_tbl[i], td.hrad_tbl[i], td.width_tbl[i]);
+        std::fclose(f);
+    }
+    std::fprintf(stderr, "%s: dumped %d transect tables to %s\n",
+                 deck_stem.c_str(), nt, out_dir.string().c_str());
+    return 0;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    std::string dump_dir;
+    std::vector decks;
+    for (int i = 1; i < argc; ++i) {
+        if (std::strcmp(argv[i], "--dump-tables") == 0 && i + 1 < argc)
+            dump_dir = argv[++i];
+        else
+            decks.push_back(argv[i]);
+    }
+    if (decks.empty()) {
+        std::fprintf(stderr,
+                     "usage: %s [--dump-tables out_dir] deck1.inp [...]\n", argv[0]);
+        return 2;
+    }
+
+    if (dump_dir.empty())
+        std::printf("deck,op,calls,reps,ns_med,ns_min,ns_max\n");
+
+    for (const auto& deck : decks) {
+        SWMMEngine eng;
+        const std::string rpt = deck + ".benchrpt";
+        if (eng.open(deck.c_str(), rpt.c_str(), nullptr) != 0) {
+            std::fprintf(stderr, "open(%s) failed — skipped\n", deck.c_str());
+            continue;
+        }
+        auto& ctx = eng.context();
+        const std::string stem = std::filesystem::path(deck).stem().string();
+
+        if (!dump_dir.empty()) {
+            const int rc = dump_tables(ctx, stem, dump_dir);
+            if (rc != 0) return rc;
+            continue;
+        }
+
+        // XSectParams for every IRREGULAR link — identical to what DW/FV use.
+        // xsect_batch_shape is only populated at initialize() (SWMMEngine.cpp
+        // q0 note), so translate it here the same way before building params.
+        std::vector xss;
+        for (int j = 0; j < ctx.n_links(); ++j) {
+            const auto uj = static_cast(j);
+            if (ctx.links.xsect_shape[uj] != openswmm::XsectShape::IRREGULAR)
+                continue;
+            ctx.links.xsect_batch_shape[uj] =
+                openswmm::link::translateShape(ctx.links.xsect_shape[uj]);
+            XSectParams xs =
+                openswmm::link::buildXSectParams(ctx.links, uj, &ctx.transect_tables);
+            if (xs.area_tbl && xs.a_full > 0.0 && xs.y_full > 0.0)
+                xss.push_back(xs);
+        }
+        if (xss.empty()) {
+            std::fprintf(stderr, "%s: no IRREGULAR links — skipped\n", stem.c_str());
+            continue;
+        }
+
+        const XsectEval& ev = openswmm::xsect::hostEval();
+
+        // Deterministic input sweeps: kSamples fractions per link, avoiding the
+        // exact endpoints (0 and full are early-out branches, not the lookup).
+        constexpr int kSamples = 64;
+        std::vector frac(kSamples);
+        for (int i = 0; i < kSamples; ++i)
+            frac[static_cast(i)] = (i + 0.5) / kSamples;
+
+        const std::size_t calls = xss.size() * static_cast(kSamples);
+
+        const auto sweep = [&](auto&& per_call) {
+            double acc = 0.0;
+            for (const auto& xs : xss)
+                for (double fr : frac) acc += per_call(xs, fr);
+            g_sink = g_sink + acc;
+        };
+
+        report(stem, "fwd_AofY", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getAofY(xs, fr * xs.y_full); });
+        }));
+        report(stem, "fwd_WofY", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getWofY(xs, fr * xs.y_full); });
+        }));
+        report(stem, "fwd_RofY", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getRofY(xs, fr * xs.y_full); });
+        }));
+        report(stem, "inv_YofA", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getYofA(xs, fr * xs.a_full); });
+        }));
+        report(stem, "SofA", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getSofA(xs, fr * xs.a_full); });
+        }));
+        report(stem, "newton_AofS", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return ev.getAofS(xs, fr * xs.s_full); });
+        }));
+        report(stem, "brent_depthOfArea", calls, time_sweep(calls, [&] {
+            sweep([&](const XSectParams& xs, double fr) {
+                return brent_depth_of_area(ev, xs, fr * xs.a_full); });
+        }));
+
+        // Batch gather shape: iterate links in the inner loop so consecutive
+        // evaluations chase different table pointers, like perlink_tabulated.
+        report(stem, "gather_area", calls, time_sweep(calls, [&] {
+            double acc = 0.0;
+            for (double fr : frac)
+                for (const auto& xs : xss)
+                    acc += ev.getAofY(xs, fr * xs.y_full);
+            g_sink = g_sink + acc;
+        }));
+
+        // ---- A1: inv_YofA with the bucket maps unbound (the pre-change path).
+        // Same evaluator, same params, only the search strategy differs — so
+        // the ratio against inv_YofA above is the LUT's own contribution.
+        openswmm::xsect::XsectTables no_lut_tbl = openswmm::xsect::hostTables();
+        no_lut_tbl.luts = nullptr;
+        const XsectEval bisecting{no_lut_tbl};
+        std::vector xss_nolut = xss;
+        for (auto& xs : xss_nolut) xs.area_lut = nullptr;
+
+        report(stem, "inv_YofA_bisect", calls, time_sweep(calls, [&] {
+            double acc = 0.0;
+            for (const auto& xs : xss_nolut)
+                for (double fr : frac) acc += bisecting.getYofA(xs, fr * xs.a_full);
+            g_sink = g_sink + acc;
+        }));
+
+        // ---- A2: the DW STEP-D batch shape — area + hyd-radius over the whole
+        // group at one depth, as two perlink_tabulated passes vs one fused pass.
+        const std::size_t nlink = xss.size();
+        std::vector b_nrm(nlink), b_af(nlink), b_rf(nlink);
+        std::vector b_ta(nlink), b_tb(nlink);
+        for (std::size_t li = 0; li < nlink; ++li) {
+            b_nrm[li] = xss[li].y_full;
+#ifdef SWMM_XSECT_FAST_LOOKUP
+            b_nrm[li] = (xss[li].y_full > 0.0) ? 1.0 / xss[li].y_full : 0.0;
+#endif
+            b_af[li] = xss[li].a_full;
+            b_rf[li] = xss[li].r_full;
+            b_ta[li] = xss[li].area_tbl;
+            b_tb[li] = xss[li].hrad_tbl;
+        }
+        std::vector b_a(nlink), b_r(nlink);
+        const int tbl_n = xss.front().transect_tbl_size;
+
+        // The depth sweeps are materialised OUTSIDE the timed region. Filling
+        // them costs a strided walk over the XSectParams array (~150 B/link),
+        // which on a 20k-link deck is more traffic than the kernel itself — in
+        // the timed loop it would swamp the very difference being measured.
+        std::vector> depth_sweeps;
+        depth_sweeps.reserve(frac.size());
+        for (double fr : frac) {
+            std::vector d(nlink);
+            for (std::size_t li = 0; li < nlink; ++li) d[li] = fr * xss[li].y_full;
+            depth_sweeps.push_back(std::move(d));
+        }
+        const std::size_t batch_calls = nlink * depth_sweeps.size();
+
+        report(stem, "batch_AR_2pass", batch_calls, time_sweep(batch_calls, [&] {
+            for (const auto& d : depth_sweeps) {
+                openswmm::xsect_batch::perlink_tabulated(
+                    d.data(), b_nrm.data(), b_af.data(), b_ta.data(),
+                    tbl_n, b_a.data(), static_cast(nlink));
+                openswmm::xsect_batch::perlink_tabulated(
+                    d.data(), b_nrm.data(), b_rf.data(), b_tb.data(),
+                    tbl_n, b_r.data(), static_cast(nlink));
+                g_sink = g_sink + b_a[0] + b_r[0];
+            }
+        }));
+        report(stem, "batch_AR_fused", batch_calls, time_sweep(batch_calls, [&] {
+            for (const auto& d : depth_sweeps) {
+                openswmm::xsect_batch::perlink_tabulated_pair(
+                    d.data(), b_nrm.data(), b_af.data(), b_rf.data(),
+                    b_ta.data(), b_tb.data(), tbl_n,
+                    b_a.data(), b_r.data(), static_cast(nlink));
+                g_sink = g_sink + b_a[0] + b_r[0];
+            }
+        }));
+
+    }
+    return 0;
+}
diff --git a/tests/benchmarks/generated/LOAD_BASELINE_2026-08-12.md b/tests/benchmarks/generated/LOAD_BASELINE_2026-08-12.md
new file mode 100644
index 000000000..0b083d199
--- /dev/null
+++ b/tests/benchmarks/generated/LOAD_BASELINE_2026-08-12.md
@@ -0,0 +1,58 @@
+# Model load benchmark — BASELINE
+
+**Date:** 2026-08-12  
+**Host:** macOS-26.5.2-arm64-arm-64bit-Mach-O  
+**CPU:** arm  
+**Benchmark:** `/Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/build/darwin-bench/tests/benchmarks/bench_model_load`  
+**Corpus:** `/Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/tests/benchmarks/generated`  
+**Repetitions:** 5 (medians reported)
+
+Times are milliseconds, medians of the reported repetitions.
+`open` is open+close; `open_init` adds initialize();
+`full` adds start()+end()+report(). No routing steps are run.
+Peak RSS is the process high-water mark, one process per model.
+
+| Model | open (ms) | open_init (ms) | full (ms) | peak RSS (MB) |
+|---|---:|---:|---:|---:|
+| `fv_variant` | 311.2 | 8047.4 | 8343.1 | 822 |
+| `gage_heavy` | 335.3 | 339.8 | 354.3 | 92 |
+| `grid_100k` | 306.7 | 336.5 | 660.9 | 396 |
+| `grid_100k_geo` | 625.1 | 657.2 | 1028.7 | 489 |
+| `grid_10k` | 28.5 | 32.5 | 65.6 | 59 |
+| `grid_10k_geo` | 56.4 | 59.7 | 100.0 | 67 |
+| `grid_250k` | 823.2 | 886.0 | 1691.6 | 906 |
+| `grid_250k_geo` | 1626.9 | 1709.2 | 2596.1 | 1049 |
+| `grid_500k` | 1762.1 | 1993.7 | 3656.7 | 1451 |
+| `grid_500k_geo` | 3553.0 | 3707.2 | 5549.2 | 1749 |
+| `grid_50k` | 145.7 | 159.5 | 319.9 | 221 |
+| `grid_50k_geo` | 294.5 | 310.1 | 480.6 | 270 |
+| `inflow_heavy` | 403.9 | 436.5 | 751.1 | 456 |
+| `inflow_heavy_rpt` | 410.1 | 442.7 | 2550.1 | 469 |
+| `street_heavy` | 448.3 | 465.9 | 641.5 | 376 |
+| `transect_heavy` | 70.2 | 75.7 | 141.2 | 115 |
+| `ts_heavy` | 7213.1 | 7037.1 | 7038.6 | 1183 |
+
+## Phase-timer breakdown (`OPENSWMM_PERF=1`, full cut, seconds)
+
+| Model | open.read | open.resolve | open.validate | open.prescan2d | res.extfiles | res.tables | res.transects | res.xsect | res.shrink | init.state | init.hydraulics | init.hydrology | init.quality | init.geometry | start.iface | start.plugins |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| `fv_variant` | 0.257 | 0.011 | 0.000 | 0.036 | 0.000 | 0.000 | 0.000 | 0.005 | 0.003 | 0.004 | 7.663 | 0.000 | 0.000 | 0.001 | 0.000 | 0.044 |
+| `gage_heavy` | 0.310 | 0.014 | 0.000 | 0.007 | 0.000 | 0.012 | 0.000 | 0.000 | 0.001 | 0.000 | 0.000 | 0.001 | 0.000 | 0.000 | 0.000 | 0.002 |
+| `grid_100k` | 0.252 | 0.010 | 0.000 | 0.036 | 0.000 | 0.000 | 0.000 | 0.005 | 0.003 | 0.004 | 0.027 | 0.000 | 0.000 | 0.001 | 0.000 | 0.037 |
+| `grid_100k_geo` | 0.500 | 0.018 | 0.000 | 0.101 | 0.000 | 0.000 | 0.000 | 0.005 | 0.010 | 0.004 | 0.026 | 0.001 | 0.000 | 0.001 | 0.000 | 0.037 |
+| `grid_10k` | 0.023 | 0.001 | 0.000 | 0.004 | 0.000 | 0.000 | 0.000 | 0.001 | 0.001 | 0.000 | 0.003 | 0.000 | 0.000 | 0.000 | 0.000 | 0.004 |
+| `grid_10k_geo` | 0.045 | 0.002 | 0.000 | 0.007 | 0.000 | 0.000 | 0.000 | 0.001 | 0.001 | 0.000 | 0.002 | 0.000 | 0.000 | 0.000 | 0.000 | 0.004 |
+| `grid_250k` | 0.671 | 0.026 | 0.000 | 0.086 | 0.000 | 0.001 | 0.000 | 0.012 | 0.007 | 0.011 | 0.070 | 0.000 | 0.000 | 0.002 | 0.000 | 0.088 |
+| `grid_250k_geo` | 1.314 | 0.046 | 0.000 | 0.252 | 0.000 | 0.001 | 0.000 | 0.012 | 0.028 | 0.012 | 0.074 | 0.007 | 0.000 | 0.002 | 0.000 | 0.094 |
+| `grid_500k` | 1.580 | 0.065 | 0.000 | 0.178 | 0.000 | 0.001 | 0.000 | 0.025 | 0.023 | 0.024 | 0.160 | 0.000 | 0.000 | 0.004 | 0.000 | 0.193 |
+| `grid_500k_geo` | 2.845 | 0.099 | 0.000 | 0.524 | 0.000 | 0.002 | 0.000 | 0.025 | 0.058 | 0.025 | 0.160 | 0.011 | 0.000 | 0.005 | 0.000 | 0.191 |
+| `grid_50k` | 0.121 | 0.006 | 0.000 | 0.018 | 0.000 | 0.000 | 0.000 | 0.002 | 0.001 | 0.002 | 0.013 | 0.000 | 0.000 | 0.000 | 0.000 | 0.018 |
+| `grid_50k_geo` | 0.238 | 0.009 | 0.000 | 0.048 | 0.000 | 0.000 | 0.000 | 0.002 | 0.005 | 0.002 | 0.014 | 0.002 | 0.000 | 0.000 | 0.000 | 0.019 |
+| `inflow_heavy` | 0.335 | 0.010 | 0.000 | 0.057 | 0.000 | 0.000 | 0.000 | 0.005 | 0.003 | 0.004 | 0.031 | 0.000 | 0.000 | 0.001 | 0.000 | 0.035 |
+| `inflow_heavy_rpt` | 0.335 | 0.011 | 0.000 | 0.058 | 0.000 | 0.000 | 0.000 | 0.005 | 0.003 | 0.004 | 0.028 | 0.000 | 0.000 | 0.001 | 0.000 | 1.825 |
+| `street_heavy` | 0.136 | 0.298 | 0.000 | 0.020 | 0.000 | 0.000 | 0.000 | 0.294 | 0.003 | 0.004 | 0.016 | 0.000 | 0.000 | 0.001 | 0.000 | 0.018 |
+| `transect_heavy` | 0.056 | 0.006 | 0.000 | 0.009 | 0.000 | 0.000 | 0.005 | 0.001 | 0.001 | 0.001 | 0.005 | 0.000 | 0.000 | 0.000 | 0.000 | 0.008 |
+| `ts_heavy` | 6.407 | 0.002 | 0.000 | 0.554 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 |
+
+Phase timers come from a separate single-iteration run, so they will not sum exactly to the medians above.
+
diff --git a/tests/benchmarks/generated/LOAD_FINAL_2026-08-13.md b/tests/benchmarks/generated/LOAD_FINAL_2026-08-13.md
new file mode 100644
index 000000000..eb2e548ac
--- /dev/null
+++ b/tests/benchmarks/generated/LOAD_FINAL_2026-08-13.md
@@ -0,0 +1,60 @@
+# Model load benchmark — FINAL
+
+**Date:** 2026-08-13  
+**Host:** macOS-26.5.2-arm64-arm-64bit-Mach-O  
+**CPU:** arm  
+**Benchmark:** `/Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/build/darwin-bench/tests/benchmarks/bench_model_load`  
+**Corpus:** `/Users/calebbuahin/Documents/Projects/cbuahin_github/openswmm.engine/tests/benchmarks/generated`  
+**Repetitions:** 5 (medians reported)
+
+Times are milliseconds, medians of the reported repetitions.
+`open` is open+close; `open_init` adds initialize();
+`full` adds start()+end()+report(). No routing steps are run.
+Peak RSS is the process high-water mark, one process per model.
+
+| Model | open (ms) | open_init (ms) | full (ms) | peak RSS (MB) |
+|---|---:|---:|---:|---:|
+| `fv_small` | 0.8 | 1.6 | 3.0 | 10 |
+| `fv_variant` | 232.9 | 438.2 | 762.2 | 884 |
+| `gage_heavy` | 37.6 | 38.0 | 56.7 | 86 |
+| `grid_100k` | 230.4 | 259.6 | 566.9 | 368 |
+| `grid_100k_geo` | 434.4 | 468.6 | 798.9 | 493 |
+| `grid_10k` | 23.2 | 26.1 | 57.1 | 51 |
+| `grid_10k_geo` | 41.2 | 44.4 | 78.4 | 62 |
+| `grid_250k` | 625.8 | 688.6 | 1463.3 | 836 |
+| `grid_250k_geo` | 1155.3 | 1240.8 | 2087.0 | 1103 |
+| `grid_500k` | 1328.7 | 1521.9 | 3105.6 | 1354 |
+| `grid_500k_geo` | 2471.3 | 2666.5 | 4398.5 | 1721 |
+| `grid_50k` | 113.4 | 128.3 | 293.7 | 222 |
+| `grid_50k_geo` | 214.7 | 230.1 | 397.1 | 273 |
+| `inflow_heavy` | 300.1 | 333.4 | 645.2 | 468 |
+| `inflow_heavy_rpt` | 299.1 | 332.4 | 781.7 | 456 |
+| `street_heavy` | 123.0 | 140.1 | 293.6 | 225 |
+| `transect_heavy` | 55.4 | 59.3 | 120.3 | 114 |
+| `ts_heavy` | 1915.4 | 1821.7 | 1819.4 | 1181 |
+
+## Phase-timer breakdown (`OPENSWMM_PERF=1`, full cut, seconds)
+
+| Model | open.read | open.resolve | open.validate | open.prescan2d | res.extfiles | res.tables | res.transects | res.xsect | res.shrink | init.state | init.hydraulics | init.hydrology | init.quality | init.geometry | start.iface | start.plugins |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| `fv_small` | 0.001 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.001 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 |
+| `fv_variant` | 0.207 | 0.012 | 0.000 | 0.013 | 0.000 | 0.000 | 0.000 | 0.005 | 0.004 | 0.004 | 0.207 | 0.000 | 0.000 | 0.001 | 0.000 | 0.031 |
+| `gage_heavy` | 0.031 | 0.002 | 0.000 | 0.003 | 0.000 | 0.000 | 0.000 | 0.000 | 0.002 | 0.000 | 0.000 | 0.001 | 0.000 | 0.000 | 0.000 | 0.002 |
+| `grid_100k` | 0.202 | 0.011 | 0.000 | 0.013 | 0.000 | 0.000 | 0.000 | 0.005 | 0.003 | 0.004 | 0.028 | 0.000 | 0.000 | 0.001 | 0.000 | 0.032 |
+| `grid_100k_geo` | 0.382 | 0.023 | 0.000 | 0.039 | 0.000 | 0.000 | 0.000 | 0.005 | 0.015 | 0.004 | 0.025 | 0.001 | 0.000 | 0.001 | 0.000 | 0.033 |
+| `grid_10k` | 0.021 | 0.002 | 0.000 | 0.001 | 0.000 | 0.000 | 0.000 | 0.001 | 0.001 | 0.000 | 0.002 | 0.000 | 0.000 | 0.000 | 0.000 | 0.003 |
+| `grid_10k_geo` | 0.034 | 0.002 | 0.000 | 0.004 | 0.000 | 0.000 | 0.000 | 0.001 | 0.001 | 0.000 | 0.002 | 0.000 | 0.000 | 0.000 | 0.000 | 0.003 |
+| `grid_250k` | 0.556 | 0.025 | 0.000 | 0.033 | 0.000 | 0.001 | 0.000 | 0.012 | 0.006 | 0.011 | 0.067 | 0.000 | 0.000 | 0.002 | 0.000 | 0.080 |
+| `grid_250k_geo` | 0.996 | 0.055 | 0.000 | 0.098 | 0.000 | 0.001 | 0.000 | 0.012 | 0.035 | 0.012 | 0.077 | 0.003 | 0.000 | 0.002 | 0.000 | 0.084 |
+| `grid_500k` | 1.194 | 0.059 | 0.000 | 0.066 | 0.000 | 0.001 | 0.000 | 0.025 | 0.018 | 0.025 | 0.158 | 0.000 | 0.000 | 0.004 | 0.000 | 0.161 |
+| `grid_500k_geo` | 2.125 | 0.098 | 0.000 | 0.196 | 0.000 | 0.001 | 0.000 | 0.024 | 0.058 | 0.025 | 0.161 | 0.013 | 0.000 | 0.005 | 0.000 | 0.173 |
+| `grid_50k` | 0.098 | 0.005 | 0.000 | 0.007 | 0.000 | 0.000 | 0.000 | 0.002 | 0.001 | 0.002 | 0.012 | 0.000 | 0.000 | 0.000 | 0.000 | 0.016 |
+| `grid_50k_geo` | 0.184 | 0.009 | 0.000 | 0.019 | 0.000 | 0.000 | 0.000 | 0.002 | 0.005 | 0.002 | 0.013 | 0.001 | 0.000 | 0.001 | 0.000 | 0.017 |
+| `inflow_heavy` | 0.269 | 0.012 | 0.000 | 0.022 | 0.000 | 0.000 | 0.000 | 0.005 | 0.004 | 0.004 | 0.033 | 0.000 | 0.000 | 0.001 | 0.000 | 0.031 |
+| `inflow_heavy_rpt` | 0.267 | 0.012 | 0.000 | 0.022 | 0.000 | 0.000 | 0.000 | 0.005 | 0.004 | 0.004 | 0.035 | 0.000 | 0.000 | 0.001 | 0.000 | 0.184 |
+| `street_heavy` | 0.112 | 0.006 | 0.000 | 0.009 | 0.000 | 0.000 | 0.000 | 0.002 | 0.003 | 0.002 | 0.016 | 0.000 | 0.000 | 0.001 | 0.000 | 0.022 |
+| `transect_heavy` | 0.044 | 0.004 | 0.000 | 0.004 | 0.000 | 0.000 | 0.001 | 0.001 | 0.001 | 0.001 | 0.005 | 0.000 | 0.000 | 0.000 | 0.000 | 0.006 |
+| `ts_heavy` | 1.501 | 0.001 | 0.000 | 0.195 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 |
+
+Phase timers come from a separate single-iteration run, so they will not sum exactly to the medians above.
+
diff --git a/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/definition.md b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/definition.md
index 1b567b55e..7998d014a 100644
--- a/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/definition.md
+++ b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/definition.md
@@ -18,7 +18,7 @@ At `d = 2.0 ft` this gives:
 
 ```text
 bottom area = 50 ft^2
-bank area   = A(2.0) = 250 ft^2
+bank area   = A(2.0) - A_bottom = 250 - 50 = 200 ft^2
 bank depth  = d / 2 = 1.0 ft
 ```
 
@@ -47,7 +47,7 @@ c1_bank   = (0.5 + 1.0) * 0.2 = 0.3 ft
 The exact cumulative exfiltration volume is therefore:
 
 ```text
-E(t) = 50 F_bottom(t) + 250 F_bank(t)
+E(t) = 50 F_bottom(t) + 200 F_bank(t)
 ```
 
 This is a true storage-geometry benchmark because the total seepage combines
@@ -60,7 +60,7 @@ the analytically defined bottom area and the analytically defined bank area.
 | `A(d)` | `50 + 100 d` | ft^2 | analytical storage surface area |
 | `d` | 2.0 | ft | fixed storage stage |
 | `A_bottom` | 50.0 | ft^2 | bottom seepage area |
-| `A_bank` | 250.0 | ft^2 | bank seepage area at `d = 2 ft` |
+| `A_bank` | 200.0 | ft^2 | bank seepage area at `d = 2 ft` (`A(d) - A_bottom`, the wetted side area — SWMM 5 exfil.c convention) |
 | `d_bank` | 1.0 | ft | bank seepage depth argument |
 | `K_s` | 4.32 | in/hr | Green-Ampt saturated conductivity |
 | `S` | 0.5 | ft | suction head |
@@ -74,7 +74,7 @@ For each component, solve the implicit saturated Green-Ampt equation for
 `F_bottom(t)` and `F_bank(t)` with the appropriate `c1`, then compute:
 
 ```text
-E(t) = 50 F_bottom(t) + 250 F_bank(t)
+E(t) = 50 F_bottom(t) + 200 F_bank(t)
 q(t_n) = [E(t_n) - E(t_{n-1})] / dt
 ```
 
diff --git a/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/reference.csv b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/reference.csv
index b672bfba2..8cd93df5c 100644
--- a/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/reference.csv
+++ b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/reference.csv
@@ -1,17 +1,17 @@
 # Fixed-stage storage exfiltration, analytic geometry + saturated Green-Ampt
-# A(d) = 50 + 100 d; at d=2 ft: bottom 50 ft^2 (c1=0.5), bank 250 ft^2 (c1=0.3)
+# A(d) = 50 + 100 d; at d=2 ft: bottom 50 ft^2 (c1=0.5), bank A(2)-50 = 200 ft^2 (c1=0.3)
 # Ks = 1e-4 ft/s.  t(F) = [F - c1 ln(1 + F/c1)] / Ks inverted per component
-# E(t) = 50 F_bottom(t) + 250 F_bank(t) [ft^3]; rate = dE/dt averaged over interval
+# E(t) = 50 F_bottom(t) + 200 F_bank(t) [ft^3]; rate = dE/dt averaged over interval
 # Full double precision.
 t_s,exfil_rate_cfs,exfil_cumul_ft3
 0,0.0,0.0
-60,0.3348623428923268,20.091740573539607
-120,0.1508529539386122,29.14291780985634
-180,0.12069481453089535,36.38460668171006
-240,0.1051265900939093,42.69220208734462
-300,0.09520340479013795,48.404406374752895
-360,0.08817228945308789,53.69474374193817
-420,0.0828574232307434,58.66618913578277
-480,0.0786596479185377,63.385768010895035
-540,0.07523702191006455,67.89998932549891
-600,0.07237821034266408,72.24268194605875
+60,0.28147491610439435,16.88849496626366
+120,0.12671171562053024,24.491197903495475
+180,0.10134528695814744,30.571915120984322
+240,0.08825006558323084,35.86691905597817
+300,0.0799028316233232,40.661088953377565
+360,0.07398813255567861,45.10037690671828
+420,0.06951700438561777,49.27139716985535
+480,0.06598549937641553,53.23052713244028
+540,0.06310600981092461,57.016887721095756
+600,0.06070077968040906,60.6589345019203
diff --git a/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/scripts/generate_reference.py b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/scripts/generate_reference.py
new file mode 100644
index 000000000..38bb67fbd
--- /dev/null
+++ b/tests/benchmarks/manufactured/exfil-storage-geometry-greenampt/scripts/generate_reference.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Generate reference CSV for the exfil-storage-geometry-greenampt benchmark.
+
+Fixed-stage storage node (depth = 2.0 ft) with analytical area A(d) = 50 + 100 d.
+At depth 2.0 ft the bottom seepage area is 50 ft^2 (c1_bottom = 0.5 ft) and the
+bank seepage area is A(2) - 50 = 200 ft^2 (c1_bank = 0.3 ft; SWMM 5
+exfil.c: bank area = MIN(area, bankMaxArea) - btmArea). Each component follows the
+exact saturated Green-Ampt relation
+
+    t(F) = [F - c1*ln(1 + F/c1)] / Ks
+
+inverted for cumulative depth F at each sample time. The cumulative exfiltration
+volume is
+
+    E(t) = 50*F_bottom(t) + 200*F_bank(t)        [ft^3]
+
+and the per-interval average rate is (E[i] - E[i-1]) / dt [cfs]. Values are
+written at full (round-trippable) double precision per shared/conventions.md.
+
+Output: ../reference.csv
+Columns: t_s, exfil_rate_cfs, exfil_cumul_ft3
+"""
+
+import csv
+import math
+import pathlib
+
+# ── parameters (US customary) ────────────────────────────────────────────────
+KS         = 1.0e-4    # ft/s (4.32 in/hr)
+C1_BOTTOM  = 0.5       # ft  (suction 0.5 ft, bottom)
+C1_BANK    = 0.3       # ft  (bank)
+A_BOTTOM   = 50.0      # ft^2
+A_BANK     = 200.0     # ft^2  (A(2) - A_bottom)
+DT         = 60.0      # s
+N_STEPS    = 10        # -> t = 0,60,...,600 s
+
+
+def F_of_t(t: float, c1: float) -> float:
+    """Invert t(F) = [F - c1*ln(1+F/c1)]/Ks for F given t (Newton + bisection)."""
+    if t <= 0.0:
+        return 0.0
+    target = KS * t                      # solve F - c1*ln(1+F/c1) = target
+    # g(F) = F - c1*ln(1+F/c1) - target ;  g'(F) = F/(F+c1)  (>0, increasing)
+    F = target + c1                      # robust initial guess (F >= target)
+    for _ in range(200):
+        g  = F - c1 * math.log(1.0 + F / c1) - target
+        gp = F / (F + c1)
+        step = g / gp
+        F -= step
+        if F <= 0.0:
+            F = target * 0.5 + 1e-9      # keep iterate positive
+        if abs(step) < 1e-15:
+            break
+    return F
+
+
+# ── generate + self-check ──────────────────────────────────────────────────────
+times = [DT * i for i in range(N_STEPS + 1)]
+cumul = []
+for t in times:
+    Fb = F_of_t(t, C1_BOTTOM)
+    Fk = F_of_t(t, C1_BANK)
+    # residual self-check: the inverted F must satisfy the relation to ~machine eps
+    for (F, c1) in ((Fb, C1_BOTTOM), (Fk, C1_BANK)):
+        if F > 0.0:
+            resid = (F - c1 * math.log(1.0 + F / c1)) - KS * t
+            assert abs(resid) < 1e-11, f"GA inversion residual {resid} at t={t}"
+    cumul.append(A_BOTTOM * Fb + A_BANK * Fk)
+
+rows = []
+for i, t in enumerate(times):
+    rate = 0.0 if i == 0 else (cumul[i] - cumul[i - 1]) / DT
+    rows.append((t, rate, cumul[i]))
+
+for (_, r0, E0), (_, r1, E1) in zip(rows[1:], rows[2:]):
+    assert E1 > E0 and r1 <= r0, "cumulative must grow, rate must relax"
+
+# ── write CSV ────────────────────────────────────────────────────────────────
+out = pathlib.Path(__file__).parent.parent / "reference.csv"
+with open(out, "w", newline="") as fh:
+    fh.write("# Fixed-stage storage exfiltration, analytic geometry + saturated Green-Ampt\n")
+    fh.write("# A(d) = 50 + 100 d; at d=2 ft: bottom 50 ft^2 (c1=0.5), bank A(2)-50 = 200 ft^2 (c1=0.3)\n")
+    fh.write("# Ks = 1e-4 ft/s.  t(F) = [F - c1 ln(1 + F/c1)] / Ks inverted per component\n")
+    fh.write("# E(t) = 50 F_bottom(t) + 200 F_bank(t) [ft^3]; rate = dE/dt averaged over interval\n")
+    fh.write("# Full double precision.\n")
+    writer = csv.writer(fh)
+    writer.writerow(["t_s", "exfil_rate_cfs", "exfil_cumul_ft3"])
+    for (t, rate, E) in rows:
+        writer.writerow([int(t), repr(rate), repr(E)])
+
+print(f"Wrote {len(rows)} rows to {out}")
+print(f"E(600) = {cumul[-1]!r} ft^3")
diff --git a/tests/benchmarks/parity_probe.cpp b/tests/benchmarks/parity_probe.cpp
new file mode 100644
index 000000000..cc5e14115
--- /dev/null
+++ b/tests/benchmarks/parity_probe.cpp
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 2026 Caleb Buahin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @file parity_probe.cpp
+ * @brief Emits the three artifacts the load-optimization parity gate compares.
+ *
+ * @details The plan's gate (Phase 0.4) diffs, for each model, the report minus
+ *          its timing lines, the binary output byte-for-byte, and the
+ *          written-back `.inp`. The shipped CLI produces the first two but has
+ *          no write-back flag, so this probe drives all three from one open:
+ *
+ *              parity_probe   [stem]
+ *
+ *          writes `/.rpt`, `.out` and `.writeback.inp`.
+ *
+ *          The write-back happens straight after open() — before initialize()
+ *          — so it captures the parsed+resolved model rather than post-run
+ *          state. That is what makes it a parse/resolve parity check, which is
+ *          exactly the surface Phases 1 and 2 disturb.
+ *
+ * @author   Caleb Buahin 
+ * @license  Apache-2.0
+ */
+
+#include 
+#include 
+#include 
+
+#include 
+#include 
+
+namespace fs = std::filesystem;
+
+namespace {
+
+int fail(const char* what, int rc) {
+    std::fprintf(stderr, "parity_probe: %s failed (rc=%d)\n", what, rc);
+    return rc != 0 ? rc : 1;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    if (argc < 3) {
+        std::fprintf(stderr,
+                     "usage: parity_probe   [stem]\n");
+        return 2;
+    }
+
+    const std::string inp = argv[1];
+    const fs::path    dir = argv[2];
+    const std::string stem =
+        (argc > 3) ? argv[3] : fs::path(inp).stem().string();
+
+    std::error_code ec;
+    fs::create_directories(dir, ec);
+
+    const std::string rpt = (dir / (stem + ".rpt")).string();
+    const std::string out = (dir / (stem + ".out")).string();
+    const std::string wb  = (dir / (stem + ".writeback.inp")).string();
+
+    SWMM_Engine eng = swmm_engine_create();
+    if (eng == nullptr) return fail("create", 1);
+
+    int rc = swmm_engine_open(eng, inp.c_str(), rpt.c_str(), out.c_str(),
+                              nullptr);
+    if (rc != SWMM_OK) { swmm_engine_destroy(eng); return fail("open", rc); }
+
+    // Write-back before initialize(): the parse/resolve product, not run state.
+    rc = swmm_model_write(eng, wb.c_str());
+    if (rc != SWMM_OK) {
+        swmm_engine_close(eng);
+        swmm_engine_destroy(eng);
+        return fail("model_write", rc);
+    }
+
+    rc = swmm_engine_initialize(eng);
+    if (rc != SWMM_OK) {
+        swmm_engine_close(eng);
+        swmm_engine_destroy(eng);
+        return fail("initialize", rc);
+    }
+
+    rc = swmm_engine_start(eng, 1);
+    if (rc != SWMM_OK) {
+        swmm_engine_close(eng);
+        swmm_engine_destroy(eng);
+        return fail("start", rc);
+    }
+
+    // Run to completion so the .out is a full result set, not a header.
+    double elapsed_days = 0.0;
+    long   guard        = 0;
+    do {
+        rc = swmm_engine_step(eng, &elapsed_days);
+        if (rc != SWMM_OK) {
+            swmm_engine_close(eng);
+            swmm_engine_destroy(eng);
+            return fail("step", rc);
+        }
+    } while (elapsed_days > 0.0 && ++guard < 100000000L);
+
+    rc = swmm_engine_end(eng);
+    if (rc == SWMM_OK) rc = swmm_engine_report(eng);
+    swmm_engine_close(eng);
+    swmm_engine_destroy(eng);
+    if (rc != SWMM_OK) return fail("end/report", rc);
+
+    std::printf("parity_probe: wrote %s{.rpt,.out,.writeback.inp}\n",
+                (dir / stem).string().c_str());
+    return 0;
+}
diff --git a/tests/benchmarks/scripts/capture_load_baseline.py b/tests/benchmarks/scripts/capture_load_baseline.py
new file mode 100755
index 000000000..d46a806cd
--- /dev/null
+++ b/tests/benchmarks/scripts/capture_load_baseline.py
@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Caleb Buahin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Capture load-benchmark medians + phase-timer breakdown into a markdown doc.
+
+Plan Phase 0.3, "Baseline capture". Emits
+``tests/benchmarks/generated/LOAD_